项目经常崩溃，添加项目规则约束

2026-07-29 09:46:19 +08:00
parent c349254304
commit 5f1bceb767
1 changed files with 81 additions and 0 deletions
@@ -0,0 +1,81 @@
+# WorkUtils 项目规则
+# https://www.codebuddy.ai/docs/zh/IDE/User-guide/Workspace
+version: 1
+
+# ===== 项目信息 =====
+name: workutils
+description: WorkUtils API 文档生成工具
+
+# ===== 规则定义 =====
+rules:
+
+  # 1. 导出目录 —— 禁止全文搜索
+  - id: no-export-search
+    description: |
+      禁止对 export/ 目录进行搜索/读取操作。
+      该目录包含导出的 HTML 文件，单文件可达数 MB，ripgrep 默认跳过超长行导致结果不准确。
+    condition: "path starts with 'export/'"
+    action: "reject"
+    fallback: "如需调试导出结果，使用源码模板文件 (templates/apidoc/*.js) + 单元测试验证"
+
+  # 2. 模板规范 —— 禁止 code-in-string 反模式
+  - id: no-code-in-string
+    description: |
+      禁止在 JS 中用函数返回压缩字符串来重复已有代码。
+      典型反模式：SNAPSHOT_JS() { return 'function sendDubboRequest(){...}' }
+      这种方式导致：
+        - 三层转义地狱 (JS字符串→HTML→JS参数)
+        - 无法调试、无法 lint、无法语法高亮
+        - 代码漂移：修改 api-doc.js 后快照版不会同步
+      正确方式：window.__API_DOC_JS__ = {{JS_JSON}}; // 复用原文
+    example: |
+      # 错误示例
+      function SNAPSHOT_JS() {
+        return 'function sendDubboRequest(){var e=buildDubboBody();...}';
+      }
+      # 正确示例
+      var mainJs = window.__API_DOC_JS__; // 由 Java 注入的 JSON
+      var override = 'function getActiveDubboCard(){...}';
+      var fullJs = override + '\n' + mainJs;
+    enforcement: "warn"
+    severity: high
+
+  # 3. 占位符命名规范
+  - id: placeholder-naming
+    description: "模板占位符统一使用 {{NAME}} 格式，双大写加下划线"
+    pattern: "\\{\\{[A-Z][A-Z0-9_]*\\}\\}"
+    enforcement: "review"
+
+  # 4. 大文件读取检查
+  - id: large-file-check
+    description: |
+      读取 >500KB 文件前先检查行数和内容分布。
+      超大文件（如压缩后的 JS/CSS、生成的 HTML）不适合直接读取全文。
+    condition: "file.size > 500KB"
+    action: "warn"
+    suggestion: "使用 head/tail 检查文件结构，或使用单元测试验证行为"
+
+  # 5. 转义函数集中管理
+  - id: escape-centralized
+    description: |
+      HTML/JS/JSON 转义函数统一在 Java 侧或独立工具模块管理。
+      避免在 JS 源码中混用多种转义方式（\\、\\\、\\'、&#39; 等）。
+    files: ["ApiDocGenerator.java"]
+    enforcement: "review"
+
+  # 6. Git 忽略大型产物
+  - id: gitignore-export
+    description: "export/ 目录应加入 .gitignore，避免提交大型产物文件"
+    action: "suggest"
+    suggestion: "echo 'export/' >> .gitignore"
+
+# ===== 触发提示 =====
+# 当规则被触发时，AI 会看到这些提示
+messages:
+  no-export-search: |
+    ⚠️ 检测到对 export/ 目录的操作。
+    该目录包含导出的 HTML 文件（单文件可达数 MB），不适合搜索/读取。
+    请改用源码模板文件 (src/main/resources/templates/apidoc/*.js) 进行调试。
+  large-file-check: |
+    ⚠️ 目标文件 >500KB，可能是压缩产物或大型导出文件。
+    建议使用 head/tail 检查结构，或通过单元测试验证行为。