@winspan/claude-forge 8.0.0 → 8.11.0

package/dist/engine/conventions/basic-security.yaml

@@ -17,6 +17,9 @@ forbidden:
     level: block
     message: "禁止强制推送到受保护分支 {{git.branch}}"
     suggestion: "使用 --force-with-lease 或创建新分支"
+    operator_guidance: "Git 安全规范：受保护分支禁止强制推送；如需改写历史，请在新分支完成并通过 PR 合并。"
+    doc_ref: "CLAUDE.md#Git 安全规范"
+    tags: ["git", "protected-branch", "history-rewrite"]
 
   - id: "warn-force-push"
     when: |
@@ -26,6 +29,9 @@ forbidden:
     level: warn
     message: "检测到 git push --force，请确认这是有意为之"
     suggestion: "force push 会覆盖远程仓库的提交历史"
+    operator_guidance: "优先使用 --force-with-lease，避免覆盖他人刚推送的提交。"
+    doc_ref: "CLAUDE.md#Git 安全规范"
+    tags: ["git", "force-push"]
 
   - id: "no-rm-rf-root"
     when: |
@@ -33,6 +39,9 @@ forbidden:
       && args.command.match(/rm\s+-[^\s]*r[^\s]*f[^\s]*\s+\//).ok()
     level: block
     message: "禁止 rm -rf / 操作"
+    operator_guidance: "这是不可逆的高危删除命令；先缩小目标路径，并用 ls 或 dry-run 确认作用范围。"
+    doc_ref: "CLAUDE.md#基础安全规范"
+    tags: ["filesystem", "destructive"]
 
   - id: "no-sudo-rm"
     when: |
@@ -48,6 +57,9 @@ forbidden:
     level: block
     message: "禁止设置 777 权限（安全风险）"
     suggestion: "使用更安全的权限设置，如 755 或 644"
+    operator_guidance: "按最小权限原则收紧权限；可执行文件通常使用 755，普通文件通常使用 644。"
+    doc_ref: "CLAUDE.md#基础安全规范"
+    tags: ["permissions", "security"]
 
   - id: "no-drop-database"
     when: |
@@ -55,6 +67,9 @@ forbidden:
       && args.command.lower().includes("drop database")
     level: block
     message: "禁止 DROP DATABASE 操作"
+    operator_guidance: "删库属于不可逆操作；先确认环境、库名和备份，再考虑使用更小粒度的数据变更命令。"
+    doc_ref: "CLAUDE.md#基础安全规范"
+    tags: ["database", "destructive"]
 
   - id: "warn-drop-table"
     when: |

package/dist/engine/conventions/database-safety.yaml

@@ -0,0 +1,74 @@
+id: "database-safety"
+name: "数据库安全规范"
+version: "1.0.0"
+description: "数据库操作安全规则，防止 SQL 注入、数据丢失和性能问题"
+triggers: ["sql", "database", "mysql", "postgres", "mongodb", "数据库", "查询"]
+
+variables:
+  sql_file_patterns: [".sql"]
+  dangerous_sql_keywords: ["DROP", "TRUNCATE", "DELETE", "UPDATE"]
+  orm_patterns: ["execute", "raw", "query"]
+
+forbidden:
+  - id: "no-sql-injection"
+    when: |
+      tool.in(["Write", "Edit"])
+      && (args.content ?? args.new_string ?? "").match(/(?:execute|query|raw)\s*\([^)]*\+[^)]*\)/).ok()
+    level: block
+    message: "检测到 SQL 字符串拼接，存在 SQL 注入风险"
+    suggestion: "使用参数化查询或 ORM 的安全 API"
+    operator_guidance: "字符串拼接无法防止 SQL 注入；使用 ? 占位符或 ORM 的参数绑定。"
+    doc_ref: "https://owasp.org/www-community/attacks/SQL_Injection"
+    tags: ["database", "sql-injection", "security"]
+
+  - id: "warn-delete-without-where"
+    when: |
+      tool.in(["Write", "Edit", "Bash"])
+      && (args.content ?? args.new_string ?? args.command ?? "").lower().match(/delete\s+from\s+\w+\s*;/).ok()
+    level: block
+    message: "检测到无 WHERE 条件的 DELETE，会删除全表数据"
+    suggestion: "添加 WHERE 条件限定删除范围，或使用 TRUNCATE"
+    operator_guidance: "无条件 DELETE 是不可逆操作；先用 SELECT 验证条件，再执行 DELETE。"
+    tags: ["database", "data-loss"]
+
+  - id: "warn-update-without-where"
+    when: |
+      tool.in(["Write", "Edit", "Bash"])
+      && (args.content ?? args.new_string ?? args.command ?? "").lower().match(/update\s+\w+\s+set\s+[^;]*;/).ok()
+      && !(args.content ?? args.new_string ?? args.command ?? "").lower().match(/where/).ok()
+    level: block
+    message: "检测到无 WHERE 条件的 UPDATE，会修改全表数据"
+    suggestion: "添加 WHERE 条件限定更新范围"
+    operator_guidance: "无条件 UPDATE 会覆盖所有行；先用 SELECT 验证条件，确认影响行数。"
+    tags: ["database", "data-loss"]
+
+  - id: "warn-select-star"
+    when: |
+      tool.in(["Write", "Edit"])
+      && (args.content ?? args.new_string ?? "").match(/SELECT\s+\*\s+FROM/i).ok()
+    level: warn
+    message: "检测到 SELECT *，可能影响性能和可维护性"
+    suggestion: "显式列出需要的字段，避免传输不必要的数据"
+    operator_guidance: "SELECT * 传输所有列，增加网络开销；显式列出字段提升性能和可读性。"
+    tags: ["database", "performance"]
+
+  - id: "no-drop-production"
+    when: |
+      tool == "Bash"
+      && args.command.lower().match(/drop\s+(database|table)/).ok()
+      && (args.command.includes("prod") || args.command.includes("production"))
+    level: block
+    message: "禁止在生产环境执行 DROP 操作"
+    operator_guidance: "生产环境的 DROP 操作必须经过审批和备份；先在测试环境验证。"
+    tags: ["database", "production", "destructive"]
+
+escalation: []
+
+deliverables: []
+
+principles: |
+  ## 数据库安全规范
+  - 禁止 SQL 字符串拼接，使用参数化查询
+  - DELETE/UPDATE 必须带 WHERE 条件
+  - 避免 SELECT *，显式列出字段
+  - 生产环境禁止 DROP 操作

package/dist/engine/conventions/docker-safety.yaml

@@ -0,0 +1,69 @@
+id: "docker-safety"
+name: "Docker/容器安全规范"
+version: "1.0.0"
+description: "容器化应用安全规则，覆盖镜像构建、运行时安全和资源管理"
+triggers: ["docker", "dockerfile", "container", "镜像", "容器"]
+
+variables:
+  dockerfile_patterns: ["Dockerfile", ".dockerfile"]
+  dangerous_base_images: ["latest", "alpine:latest"]
+
+forbidden:
+  - id: "no-latest-tag"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_path != null
+      && (file_path.endsWith("Dockerfile") || file_path.includes("Dockerfile"))
+      && (args.content ?? args.new_string ?? "").match(/FROM\s+[^:]+:latest/).ok()
+    level: warn
+    message: "Dockerfile 使用 :latest 标签，可能导致构建不可复现"
+    suggestion: "使用具体版本号，如 node:18.20.0-alpine"
+    operator_guidance: "latest 标签会随时间变化；固定版本号确保构建可复现。"
+    tags: ["docker", "reproducibility"]
+
+  - id: "warn-run-as-root"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_path != null
+      && (file_path.endsWith("Dockerfile") || file_path.includes("Dockerfile"))
+      && !(args.content ?? args.new_string ?? "").match(/USER\s+\w+/).ok()
+    level: warn
+    message: "Dockerfile 未指定 USER，容器将以 root 运行"
+    suggestion: "添加 USER 指令切换到非 root 用户"
+    operator_guidance: "以 root 运行容器增加攻击面；创建专用用户并切换：RUN adduser -D appuser && USER appuser"
+    tags: ["docker", "security"]
+
+  - id: "no-apt-get-without-cleanup"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_path != null
+      && (file_path.endsWith("Dockerfile") || file_path.includes("Dockerfile"))
+      && (args.content ?? args.new_string ?? "").match(/apt-get\s+install/).ok()
+      && !(args.content ?? args.new_string ?? "").match(/rm\s+-rf\s+\/var\/lib\/apt\/lists/).ok()
+    level: warn
+    message: "apt-get install 后未清理缓存，会增大镜像体积"
+    suggestion: "在同一 RUN 层添加清理命令：&& rm -rf /var/lib/apt/lists/*"
+    operator_guidance: "每个 RUN 层都会保留文件系统快照；在同一层安装和清理可减小镜像体积。"
+    tags: ["docker", "optimization"]
+
+  - id: "warn-expose-sensitive-port"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_path != null
+      && (file_path.endsWith("Dockerfile") || file_path.includes("Dockerfile"))
+      && (args.content ?? args.new_string ?? "").match(/EXPOSE\s+(22|3306|5432|6379|27017)/).ok()
+    level: warn
+    message: "Dockerfile 暴露敏感端口（SSH/数据库），可能存在安全风险"
+    suggestion: "确认是否需要暴露该端口，生产环境应通过网络策略限制访问"
+    tags: ["docker", "security"]
+
+escalation: []
+
+deliverables: []
+
+principles: |
+  ## Docker/容器安全规范
+  - 使用具体版本号而非 :latest 标签
+  - 容器应以非 root 用户运行
+  - apt-get install 后清理缓存减小镜像体积
+  - 避免暴露敏感端口（SSH、数据库）

package/dist/engine/conventions/git-safety.yaml

@@ -17,6 +17,9 @@ forbidden:
     level: block
     message: "禁止强制推送到受保护分支 {{git.branch}}"
     suggestion: "使用 --force-with-lease 或创建新分支后提交 PR"
+    operator_guidance: "公共分支改写历史会影响他人协作；优先通过新分支和 PR 完成修复。"
+    doc_ref: "CLAUDE.md#Git 操作安全规范"
+    tags: ["git", "protected-branch", "history-rewrite"]
 
   - id: "warn-force-push-feature"
     when: |
@@ -26,6 +29,9 @@ forbidden:
     level: warn
     message: "检测到 git push --force，这会覆盖远程历史"
     suggestion: "考虑使用 --force-with-lease 以避免覆盖他人提交"
+    operator_guidance: "只有在确认远端无人基于该提交继续工作时，才考虑 force push。"
+    doc_ref: "CLAUDE.md#Git 操作安全规范"
+    tags: ["git", "force-push"]
 
   - id: "no-reset-hard-uncommitted"
     when: |
@@ -35,6 +41,9 @@ forbidden:
     level: block
     message: "禁止在有未提交更改时执行 git reset --hard"
     suggestion: "先使用 git stash 保存更改，或提交后再 reset"
+    operator_guidance: "先用 git status 确认工作区，再 stash 或提交，避免本地未保存改动丢失。"
+    doc_ref: "CLAUDE.md#Git 操作安全规范"
+    tags: ["git", "reset-hard", "uncommitted-changes"]
 
   - id: "warn-reset-hard"
     when: |
@@ -43,6 +52,9 @@ forbidden:
     level: confirm
     message: "git reset --hard 会丢弃所有未提交的更改"
     suggestion: "确认这是有意为之，或使用 git stash 保存更改"
+    operator_guidance: "执行前先确认 HEAD 目标和工作区状态，必要时先创建临时分支保存现场。"
+    doc_ref: "CLAUDE.md#Git 操作安全规范"
+    tags: ["git", "reset-hard"]
 
   - id: "warn-clean-fd"
     when: |

package/dist/engine/conventions/go-best-practices.yaml

@@ -0,0 +1,84 @@
+id: "go-best-practices"
+name: "Go 最佳实践"
+version: "1.0.0"
+description: "Go 开发规范，覆盖错误处理、并发安全、资源管理和性能"
+triggers: ["go", "golang", "goroutine", "channel", "defer", "panic"]
+
+variables:
+  go_file_patterns: [".go"]
+  dangerous_packages: ["unsafe", "reflect"]
+  max_function_lines: 50
+
+forbidden:
+  - id: "no-panic-in-library"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext == ".go"
+      && !file_path.includes("_test.go")
+      && (args.content ?? args.new_string ?? "").match(/\bpanic\(/).ok()
+    level: warn
+    message: "库代码中检测到 panic，应返回 error 而非 panic"
+    suggestion: "将 panic 改为返回 error，让调用方决定如何处理"
+    operator_guidance: "panic 应只用于不可恢复的错误；库代码应返回 error，由调用方处理。"
+    doc_ref: "https://go.dev/blog/error-handling-and-go"
+    tags: ["go", "error-handling"]
+
+  - id: "warn-goroutine-leak"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext == ".go"
+      && (args.content ?? args.new_string ?? "").match(/go\s+func\s*\(/).ok()
+      && !(args.content ?? args.new_string ?? "").match(/context\./).ok()
+    level: warn
+    message: "检测到 goroutine 但未使用 context，可能导致泄漏"
+    suggestion: "传入 context.Context 参数，监听 ctx.Done() 以优雅退出"
+    operator_guidance: "goroutine 泄漏会耗尽资源；用 context 控制生命周期，监听 Done() 信号退出。"
+    doc_ref: "https://go.dev/blog/context"
+    tags: ["go", "concurrency", "resource-leak"]
+
+  - id: "no-defer-in-loop"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext == ".go"
+      && (args.content ?? args.new_string ?? "").match(/for\s+[^{]*\{[^}]*defer\s+/).ok()
+    level: warn
+    message: "检测到循环中使用 defer，会延迟到函数结束才执行"
+    suggestion: "将循环体提取为独立函数，或手动调用清理函数"
+    operator_guidance: "defer 在函数返回时执行，不是循环迭代结束；循环中的 defer 会累积，可能导致资源耗尽。"
+    doc_ref: "https://go.dev/ref/spec#Defer_statements"
+    tags: ["go", "defer", "resource-leak"]
+
+  - id: "warn-error-ignored"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext == ".go"
+      && (args.content ?? args.new_string ?? "").match(/\w+\([^)]*\)\s*$/).ok()
+      && (args.content ?? args.new_string ?? "").match(/,\s*err\s*:=/).ok()
+    level: warn
+    message: "检测到可能未检查的 error 返回值"
+    suggestion: "显式检查 error：if err != nil { return err }"
+    operator_guidance: "Go 的错误处理依赖显式检查；忽略 error 会掩盖问题，用 if err != nil 立即处理。"
+    tags: ["go", "error-handling"]
+
+  - id: "no-unsafe-package"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext == ".go"
+      && (args.content ?? args.new_string ?? "").match(/import\s+.*"unsafe"/).ok()
+    level: warn
+    message: "检测到 unsafe 包，会绕过 Go 的类型安全"
+    suggestion: "除非性能关键场景，避免使用 unsafe"
+    operator_guidance: "unsafe 绕过类型安全和内存安全；只在性能瓶颈且充分测试后使用。"
+    tags: ["go", "safety"]
+
+escalation: []
+
+deliverables: []
+
+principles: |
+  ## Go 最佳实践
+  - 库代码返回 error 而非 panic
+  - goroutine 使用 context 控制生命周期
+  - 避免在循环中使用 defer
+  - 显式检查所有 error 返回值
+  - 谨慎使用 unsafe 包

package/dist/engine/conventions/python-best-practices.yaml

@@ -0,0 +1,96 @@
+id: "python-best-practices"
+name: "Python 最佳实践"
+version: "1.0.0"
+description: "Python 开发规范，覆盖代码风格、类型安全、安全性和性能"
+triggers: ["python", "py", "pip", "django", "flask", "fastapi", "虚拟环境"]
+
+variables:
+  python_file_patterns: [".py"]
+  dangerous_imports: ["pickle", "eval", "exec", "compile", "__import__"]
+  max_function_lines: 50
+  max_class_lines: 300
+
+forbidden:
+  - id: "no-pickle-untrusted"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext == ".py"
+      && (args.content ?? args.new_string ?? "").match(/pickle\.loads?\(/).ok()
+    level: warn
+    message: "检测到 pickle.load/loads，反序列化不可信数据存在代码执行风险"
+    suggestion: "使用 JSON 或其他安全的序列化格式，避免 pickle 处理外部数据"
+    operator_guidance: "pickle 可以执行任意代码；只用于可信数据，外部数据优先用 JSON/MessagePack。"
+    doc_ref: "https://docs.python.org/3/library/pickle.html#module-pickle"
+    tags: ["python", "security", "deserialization"]
+
+  - id: "no-eval-exec"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext == ".py"
+      && (args.content ?? args.new_string ?? "").match(/\b(eval|exec)\s*\(/).ok()
+    level: block
+    message: "禁止使用 eval() 或 exec()，存在代码注入风险"
+    suggestion: "使用 ast.literal_eval() 解析字面量，或重新设计避免动态执行"
+    operator_guidance: "eval/exec 可执行任意代码；用 ast.literal_eval 安全解析，或用字典映射替代动态执行。"
+    doc_ref: "https://docs.python.org/3/library/ast.html#ast.literal_eval"
+    tags: ["python", "security", "code-injection"]
+
+  - id: "warn-bare-except"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext == ".py"
+      && (args.content ?? args.new_string ?? "").match(/except\s*:/).ok()
+    level: warn
+    message: "检测到裸 except:，会捕获所有异常包括 KeyboardInterrupt"
+    suggestion: "使用 except Exception: 或捕获具体异常类型"
+    operator_guidance: "裸 except 会捕获系统退出信号；用 except Exception 或具体异常类型。"
+    tags: ["python", "error-handling"]
+
+  - id: "warn-mutable-default-arg"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext == ".py"
+      && (args.content ?? args.new_string ?? "").match(/def\s+\w+\([^)]*=\s*(\[\]|\{\})\s*[,)]/).ok()
+    level: warn
+    message: "检测到可变默认参数（[] 或 {}），会在调用间共享"
+    suggestion: "使用 None 作为默认值，在函数内部初始化"
+    operator_guidance: "可变默认参数只创建一次，多次调用会共享同一对象；用 None 并在函数内 if arg is None: arg = []"
+    doc_ref: "https://docs.python-guide.org/writing/gotchas/#mutable-default-arguments"
+    tags: ["python", "correctness"]
+
+  - id: "no-shell-injection"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext == ".py"
+      && (args.content ?? args.new_string ?? "").match(/subprocess\.(call|run|Popen)\([^)]*shell\s*=\s*True/).ok()
+    level: warn
+    message: "检测到 subprocess 使用 shell=True，存在命令注入风险"
+    suggestion: "使用列表形式传递参数，避免 shell=True"
+    operator_guidance: "shell=True 会通过 shell 解析命令，存在注入风险；用列表传参：['ls', '-la']"
+    doc_ref: "https://docs.python.org/3/library/subprocess.html#security-considerations"
+    tags: ["python", "security", "command-injection"]
+
+  - id: "warn-requirements-no-version"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_path != null
+      && file_path.endsWith("requirements.txt")
+      && (args.content ?? args.new_string ?? "").match(/^\w+\s*$/m).ok()
+    level: warn
+    message: "requirements.txt 中存在未固定版本的依赖"
+    suggestion: "使用 == 固定版本号，确保构建可复现"
+    operator_guidance: "未固定版本会导致不同环境安装不同版本；用 pip freeze 生成精确版本。"
+    tags: ["python", "dependency", "reproducibility"]
+
+escalation: []
+
+deliverables: []
+
+principles: |
+  ## Python 最佳实践
+  - 禁止 pickle 反序列化不可信数据
+  - 禁止 eval/exec 动态执行代码
+  - 使用 except Exception 而非裸 except
+  - 避免可变默认参数
+  - subprocess 避免 shell=True
+  - requirements.txt 固定依赖版本

package/dist/engine/conventions/react-best-practices.yaml

@@ -0,0 +1,96 @@
+id: "react-best-practices"
+name: "React 最佳实践"
+version: "1.0.0"
+description: "React/前端开发规范，覆盖组件设计、状态管理、性能优化和安全性"
+triggers: ["react", "jsx", "tsx", "component", "hook", "useState", "useEffect", "组件", "前端"]
+
+variables:
+  react_file_patterns: [".jsx", ".tsx"]
+  hook_names: ["useState", "useEffect", "useCallback", "useMemo", "useRef", "useContext", "useReducer"]
+  dangerous_html_props: ["dangerouslySetInnerHTML", "innerHTML"]
+  max_component_lines: 300
+  max_useEffect_deps: 5
+
+forbidden:
+  - id: "no-dangerously-set-inner-html"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext.in(vars.react_file_patterns)
+      && (args.content ?? args.new_string ?? "").match(/dangerouslySetInnerHTML/).ok()
+    level: warn
+    message: "检测到 dangerouslySetInnerHTML，存在 XSS 风险"
+    suggestion: "使用 React 的默认转义机制，或使用 DOMPurify 清理 HTML"
+    operator_guidance: "dangerouslySetInnerHTML 绕过了 React 的 XSS 防护；如必须使用，需先用 DOMPurify.sanitize() 清理内容。"
+    doc_ref: "https://react.dev/reference/react-dom/components/common#dangerously-setting-the-inner-html"
+    tags: ["react", "xss", "security"]
+
+  - id: "no-inline-function-in-jsx"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext.in(vars.react_file_patterns)
+      && (args.content ?? args.new_string ?? "").match(/onClick=\{(?:\(\)|function)/).ok()
+    level: warn
+    message: "检测到 JSX 中的内联函数，可能导致不必要的重渲染"
+    suggestion: "使用 useCallback 包裹函数，或将函数提取到组件外"
+    operator_guidance: "每次渲染都会创建新函数引用，导致子组件不必要的重渲染；用 useCallback 缓存函数引用。"
+    tags: ["react", "performance"]
+
+  - id: "warn-missing-key-prop"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext.in(vars.react_file_patterns)
+      && (args.content ?? args.new_string ?? "").match(/\.map\([^)]*=>\s*<[A-Z]/).ok()
+      && !(args.content ?? args.new_string ?? "").match(/key=/).ok()
+    level: warn
+    message: "检测到 map 渲染列表但可能缺少 key 属性"
+    suggestion: "为列表项添加唯一的 key 属性，避免使用数组索引"
+    operator_guidance: "key 帮助 React 识别哪些元素改变了；使用稳定的唯一标识符（如 id），不要用数组索引。"
+    doc_ref: "https://react.dev/learn/rendering-lists#keeping-list-items-in-order-with-key"
+    tags: ["react", "performance", "correctness"]
+
+  - id: "warn-useEffect-missing-deps"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext.in(vars.react_file_patterns)
+      && (args.content ?? args.new_string ?? "").match(/useEffect\([^,]+,\s*\[\s*\]\s*\)/).ok()
+    level: warn
+    message: "检测到 useEffect 使用空依赖数组，可能遗漏依赖"
+    suggestion: "检查 effect 中使用的所有外部变量是否都在依赖数组中"
+    operator_guidance: "空依赖数组意味着 effect 只在挂载时运行一次；如果 effect 内部使用了 props/state，应添加到依赖数组。"
+    doc_ref: "https://react.dev/reference/react/useEffect#specifying-reactive-dependencies"
+    tags: ["react", "hooks", "correctness"]
+
+  - id: "no-direct-state-mutation"
+    when: |
+      tool.in(["Write", "Edit"])
+      && file_ext.in(vars.react_file_patterns)
+      && (args.content ?? args.new_string ?? "").match(/\bstate\.[a-zA-Z_]+\s*=/).ok()
+    level: block
+    message: "禁止直接修改 state，必须使用 setState"
+    suggestion: "使用 setState 或 useState 返回的 setter 函数更新状态"
+    operator_guidance: "直接修改 state 不会触发重渲染，且违反 React 的不可变性原则；始终通过 setState 更新。"
+    doc_ref: "https://react.dev/learn/updating-objects-in-state"
+    tags: ["react", "state", "correctness"]
+
+escalation:
+  - id: "large-component-warning"
+    when: |
+      tool == "Write"
+      && file_ext.in(vars.react_file_patterns)
+      && (args.content ?? "").split("\n").length > vars.max_component_lines
+    action: warn
+    message: "组件超过 {{vars.max_component_lines}} 行，建议拆分"
+    suggestion: "将大组件拆分为多个小组件，提升可维护性"
+    operator_guidance: "大组件难以理解和测试；按功能或 UI 区域拆分，每个组件专注单一职责。"
+    tags: ["react", "maintainability"]
+
+deliverables: []
+
+principles: |
+  ## React 最佳实践
+  - 禁止使用 dangerouslySetInnerHTML，防止 XSS 攻击
+  - 避免 JSX 中的内联函数，使用 useCallback 优化性能
+  - 列表渲染必须添加唯一 key，不使用数组索引
+  - useEffect 依赖数组必须完整，避免遗漏依赖
+  - 禁止直接修改 state，必须通过 setState 更新
+  - 组件超过 300 行时建议拆分

package/dist/engine/dsl/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/engine/dsl/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EACV,UAAU,EAKX,MAAM,YAAY,CAAC;AAuDpB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,cAAc,CAAS;gBAEnB,cAAc,CAAC,EAAE,MAAM;IAWnC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU;IAkBvC,OAAO,IAAI,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC;IAyBlC,kBAAkB,CAChB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GACtC,UAAU;IAiBb,OAAO,CAAC,gBAAgB;IAsDxB,OAAO,CAAC,cAAc;CAkBvB"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/engine/dsl/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EACV,UAAU,EAKX,MAAM,YAAY,CAAC;AA6DpB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,cAAc,CAAS;gBAEnB,cAAc,CAAC,EAAE,MAAM;IAWnC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU;IAkBvC,OAAO,IAAI,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC;IAyBlC,kBAAkB,CAChB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GACtC,UAAU;IAiBb,OAAO,CAAC,gBAAgB;IAsDxB,OAAO,CAAC,cAAc;CAkBvB"}

package/dist/engine/dsl/parser.js

@@ -18,6 +18,9 @@ const RuleSchema = z.object({
     level: z.enum(['allow', 'warn', 'confirm', 'block']),
     message: z.string(),
     suggestion: z.string().optional(),
+    operator_guidance: z.string().optional(),
+    doc_ref: z.string().optional(),
+    tags: z.array(z.string()).optional(),
     enabled: z.boolean().optional().default(true),
 });
 const EscalationRuleSchema = z.object({
@@ -26,6 +29,9 @@ const EscalationRuleSchema = z.object({
     action: z.enum(['allow', 'warn', 'confirm', 'block']),
     message: z.string(),
     suggestion: z.string().optional(),
+    operator_guidance: z.string().optional(),
+    doc_ref: z.string().optional(),
+    tags: z.array(z.string()).optional(),
     enabled: z.boolean().optional().default(true),
 });
 const DeliverableSchema = z.object({
@@ -33,7 +39,7 @@ const DeliverableSchema = z.object({
     pattern: z.string().optional(),
     command: z.string().optional(),
     required: z.boolean(),
-    check_at: z.enum(['session_end', 'before_commit', 'on_demand']),
+    check_at: z.enum(['session_end', 'before_commit', 'on_demand', 'ci']),
     condition: z.string().optional(),
 });
 const RuleOverrideSchema = z.object({

package/dist/engine/dsl/parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../src/engine/dsl/parser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../src/engine/dsl/parser.ts"],"names":[],"mappings":"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"}

package/dist/engine/dsl/types.d.ts

@@ -14,6 +14,22 @@ export interface GovernanceDecision {
     reason?: string;
     suggestion?: string;
 }
+export interface RuleMetadata {
+    operator_guidance?: string;
+    doc_ref?: string;
+    tags?: string[];
+}
+export interface MatchedRule extends RuleMetadata {
+    id: string;
+    level: DecisionLevel;
+    reason: string;
+    suggestion?: string;
+    source_convention: string;
+}
+export interface RuleEvaluationResult {
+    decision: GovernanceDecision;
+    matches: MatchedRule[];
+}
 export interface Convention {
     id: string;
     name: string;
@@ -34,6 +50,9 @@ export interface Rule {
     level: DecisionLevel;
     message: string;
     suggestion?: string;
+    operator_guidance?: string;
+    doc_ref?: string;
+    tags?: string[];
     enabled?: boolean;
 }
 export interface EscalationRule {
@@ -42,6 +61,9 @@ export interface EscalationRule {
     action: DecisionLevel;
     message: string;
     suggestion?: string;
+    operator_guidance?: string;
+    doc_ref?: string;
+    tags?: string[];
     enabled?: boolean;
 }
 export interface Deliverable {
@@ -49,7 +71,7 @@ export interface Deliverable {
     pattern?: string;
     command?: string;
     required: boolean;
-    check_at: 'session_end' | 'before_commit' | 'on_demand';
+    check_at: 'session_end' | 'before_commit' | 'on_demand' | 'ci';
     condition?: string;
 }
 export interface RuleOverride {
@@ -103,6 +125,9 @@ export interface CompiledRule {
     level: DecisionLevel;
     message: string;
     suggestion?: string;
+    operator_guidance?: string;
+    doc_ref?: string;
+    tags?: string[];
     evaluate: CompiledExpression;
     render: (ctx: RuleContext) => string;
     source_convention: string;