From 5f1bceb76783373413b6be714efa900ed667edcf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E5=AE=B6=E8=AE=AD?=
 <zhangjiaxun-xf@bestpay.com.cn>
Date: Wed, 29 Jul 2026 09:46:19 +0800
Subject: [PATCH] =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E7=BB=8F=E5=B8=B8=E5=B4=A9?=
 =?UTF-8?q?=E6=BA=83=EF=BC=8C=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE=E8=A7=84?=
 =?UTF-8?q?=E5=88=99=E7=BA=A6=E6=9D=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .codebuddy/rules/workutils.yaml | 81 +++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 .codebuddy/rules/workutils.yaml

diff --git a/.codebuddy/rules/workutils.yaml b/.codebuddy/rules/workutils.yaml
new file mode 100644
index 0000000..822d647
--- /dev/null
+++ b/.codebuddy/rules/workutils.yaml
@@ -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 检查结构，或通过单元测试验证行为。