optimize-rules

## 用途 审计并更新 `.omp/rules/` 文件，使其保持准确、精准、精简。本技能会在规则文本与实际代码之间进行系统性的交叉比对，然后应用修复。 ## 触发时机 在重大重构之后、规则文件长期未更新时，或 Claude 报告"找不到 X"但规则声称 X 存在时调用。 ## TTSR 规则结构 本技能审计的 `.omp/rules/*.md` 文件是 TTSR（Time-Traveling Stream Rules）规则，通过 frontmatter 中的 `condition`（触发正则）和 `scope`（流范围）决定**何时触发**和**在哪触发**。 ### 数据流向 ``` 助手在"说话"（生成回复） │ ├─ 写自然语言（text）──→ text 缓冲区 ├─ 思考过程（thinking）──→ thinking 缓冲区 └─ 调用工具（tool）──→ tool 缓冲区 │ ▼ 每个缓冲区的内容不断累积， 每来一段新内容就拿 condition 正则去匹配 │ 匹配上了？ ├─ 否 → 继续流 └─ 是 → scope 允许在这个场景触发吗？ ├─ 否 → 继续流 └─ 是 → 中断助手 → 注入规则内容 → 重试 ``` ### 关键术语 - **"流"（stream）**：助手生成回复不是一次性给的，是一段一段（像水流一样）陆续产生的。规则检查在流中进行。 - **三种流来源（source）**： - `text` — 助手写的自然语言正文 - `thinking` — 模型的思考过程 - `tool` — 助手调用工具时传的参数（如 `edit` 工具传的补丁内容、`write` 工具传的文件内容） - **condition（触发正则）**：正则表达式，匹配流缓冲区内容。命中时触发规则检查（如果 scope 也允许）。审计时重点验证：(a) condition 是否实际匹配它声称要约束的代码模式，(b) condition 是否过于宽泛导致误触发 - **scope（流范围）**：定义哪些流来源（`text`/`thinking`/`tool`）在哪些路径上允许触发。审计时重点验证 scope 是否覆盖了规则约束的所有文件路径 有关 TTSR 规则的完整设计指南，参见 `skill://add-rule`。 ## 执行流程 ### 第一阶段：并行发现（6 个 agent） 如果传入了 `args`（如 `".omp/RULES.md"` 或 `"plugin-system.md"`），则所有 Agent **只分析指定的规则文件**。如果 `args` 为 `"all"` 或未传入，则分析全部 `.omp/rules/*.md` 文件。 同时启动六个 Explore agent，各负责一个维度： **Agent 0 — Frontmatter 覆盖分析** - 逐一分析每个规则文件的 `scope` 和 `condition` frontmatter，验证两者是否准确覆盖规则所约束的领域 - **scope 检查**：用 Glob 展开 `scope` 中所有通配符得到实际覆盖的文件集合，与规则正文提及的路径比对： - 明确引用的文件路径（如 `core/config/manager.rs`） - 明确引用的目录（如 `builtin_plugin/config/`） - 明确引用的 crate（如 `plugin-api`、`plugin-protocol`、`platform-windows`） - **主题隐含范围**：从规则标题和核心内容推断该规则所约束的代码领域（如 `sdk.md` 主题是整个 SDK 层，约束范围 = trait 定义 `crates/plugin-api/src/` + 平台实现 `crates/platform-windows/src/` + re-export 桥 `src-tauri/src/sdk.rs`） - **核心检验**：如果规则说"X 定义在 Y"或"在 Z 目录下添加"但 Y/Z 不在 `scope` 里 → 编辑 Y/Z 时该规则**不会被触发** → 覆盖缺失 - **condition 检查**： - 验证 condition 正则是有效且合理的：无空串、无纯空白、`|` 分割的每个原子项本身是合法正则 - 对每个原子项，在代码库中搜索其是否真实出现（grep），判断 condition 是否实际匹配它声称要约束的代码模式 - 判断 condition 是否过于宽泛导致大量误触发（如 `File|file` 这种常见词），或过于狭窄漏掉常见变体 - 报告：(a) `scope` 条目覆盖不足的路径，(b) 规则约束的整个域完全不在 `scope` 中，(c) 过宽或过窄的 scope 模式，(d) condition 无效正则或空字符串，(e) condition 原子项在代码中无匹配（规则声称约束但 condition 永远触不发），(f) condition 过于宽泛常见（高误报风险） - 严重程度分级： - **高**：规则约束的核心域超过 50% 不在 `scope` 内；condition 永远无法触发（未匹配任何代码） - **中**：规则引用了次要依赖但未覆盖；condition 过于宽泛可能误触发 - **低**：单一边缘路径遗漏；condition 缺少一两个常见变体 - 报告格式： ``` ## Agent 0 报告 — Frontmatter 覆盖分析 ### 发现 - **<严重程度: 高/中/低>** | <规则文件> | <问题字段: scope/condition> | <当前值> | <问题描述> | <建议修复> ``` **Agent 1 — 结构覆盖** - 通读目标规则文件的全部内容 - 对规则中声称的每个文件路径、目录树和模块清单，通过 Glob 验证磁盘上是否存在 - 报告：(a) 规则**正文**中存在的路径在磁盘上 **不存在**，(b) 磁盘上存在但规则**正文**中 **缺失** 的路径，(c) 数值声明（文件数/插件数/命令数）与实际情况不符的地方 - **注意**：此 Agent 只检查规则**正文**中提到的路径是否正确，**不**检查 `scope` frontmatter 的覆盖范围（由 Agent 0 专门负责） - 报告格式： ``` ## Agent 1 报告 — 结构覆盖 ### 发现 - **<严重程度: 高/中/低>** | <规则文件> | <规则声称 X，实际是 Y> | <建议修复> ``` **Agent 2 — 代码与规则匹配** - 通读目标规则文件的全部内容 - 对每条行为约束（如"使用 X 模式"、"禁止 Y"、"必须 Z"），通过 Grep 和 `codegraph_explore` 与实际代码进行比对验证 - **condition 模式验证**：取规则 `condition` 的每个原子项，在代码库中搜索是否存在匹配——如果 condition 声明的模式在代码中找不到匹配，说明该 condition 实际无法触发，规则成为"死规则" - 报告：(a) 规则声称的模式在代码中被违反，(b) 规则声称的模式已不再适用（相关代码已被重构），(c) 规则引用了已删除的类型/函数/模块，(d) condition 原子项在代码中无任何匹配（死规则） - 报告格式： ``` ## Agent 2 报告 — 代码与规则匹配 ### 发现 - **<严重程度: 高/中/低>** | <规则文件> | <约束原文> | <代码现状> | <建议修复> ``` **Agent 3 — 新模式发现** - 运行 `.omp/skills/optimize-rules/scripts/git-changes.sh` 识别近期的结构变更（优先找与远程默认分支的 merge-base → 显示分支全量变更；找不到时回退到最近 15 个提交） - 通过 `codegraph_explore` 搜索新引入的模块、新 trait、新事件通道、新依赖方向等 - 报告：需要文档化的新约束/新模式（重构中产生但尚未在规则中体现的架构约定） - 报告格式： ``` ## Agent 3 报告 — 新模式发现 ### 发现 - **<严重程度: 高/中/低>** | <涉及的规则文件或建议新建> | <新模式描述> | <建议添加的规则内容> ``` **Agent 4 — 最佳实践审计** - 通读目标规则文件的全部内容，按以下清单逐项审计： 1. **长度**：是否有规则文件超过 200 行？（超过则建议拆分） 2. **模糊规则**：是否使用"注意""合理""适当"等模糊词汇而无具体、可验证的标准？ 3. **有禁无导**："不要做 X"但没有给出"应该做 Y"的替代方案？ 4. **冗余**：规则是否重复了 linter/formatter（rustfmt、clippy、ESLint）已经能强制的内容？ 5. **无因规则**：约束陈述了但没有解释**为什么**？ - 报告：违反最佳实践、应收紧或删除的规则。对每条问题规则给出具体的替换文本或删除建议。 - 报告格式： ``` ## Agent 4 报告 — 最佳实践审计 ### 发现 - **<严重程度: 高/中/低>** | <规则文件> | <违反的检查项> | <原文摘录> | <建议修复或删除> ``` **Agent 5 — Condition 触发重叠与同质/异质判定** - 术语前提：检查对象是 `condition`（触发正则）+ `scope`（适用路径），即规则文件实际 frontmatter - 扫描所有规则 `condition`，按 `|` 切成原子项，构建"原子项 → 命中规则"映射 - 找出 `condition` 交集非空的规则对，**先判性质再定处理**： 1. **同质** —— 小规则是大规则主题的子方面（描述同一条规则，离开大规则主题无独立意义）→ **合并**：删小规则，大规则 `condition` 保留完整并集 2. **异质** —— 大规则由多个完全不同/不相关/方向不一样的规则用 `condition` 并集捆绑，小规则是可独立成立的不同关切点 → **拆分**：保留/恢复小规则，大规则移除对应 `condition` 原子项与正文段落 3. **语义冲突** —— 同一触发点给出相反指导 → 删其一，保留正确方 - 判定准则（内嵌，不依赖执行者另查原则）：触发重叠 ≠ 内容冗余；判定顺序是"先同质/异质，再决定合并/拆分"，禁止一见重叠就删小规则。区分关键：小规则是"大规则主题的子方面"（同质）还是"可独立成立的不同关切点"（异质） - 报告格式： ``` ## Agent 5 报告 — Condition 触发重叠与同质/异质判定 ### 发现 - **<严重程度: 高/中/低>** | <规则对> | <性质: 同质/异质/语义冲突> | <重叠的原子项> | <建议: 合并/拆分/删其一> ``` ### 第二阶段：综合发现 阅读六份 agent 报告，产出一份合并差异清单： 1. **需要修改的文件** — 按严重程度排序（最严重排最前） 2. **每个文件的具体改动** — 增、删、改的具体内容 3. **需要新增的规则** — 重构中产生但尚未文档化的模式 4. **违反最佳实践** — 按 `.omp/RULES.md`（工程纪律）和 `.omp/rules/`（条件规则）的最佳实践需要收紧、拆分或删除的规则 5. **冲突规则** — 两条或多条规则之间存在矛盾，需要再次审查，决定保留哪条、删除哪条 ### 第三阶段：呈现计划 进入 plan 模式，将综合发现以结构化计划形式呈现，计划必须： - 按规则文件分组，严重程度排序 - 每处改动说明具体的失配（规则说 X，代码实际是 Y） - 对每条过时/错误的规则给出具体的替换文本 - 按"缓慢添加，果断删除"原则，标记应该 **删除**（而非仅更新）的规则 ### 第四阶段：执行（用户批准后） 应用所有已批准的改动，然后验证： 1. `cargo check` 通过（本技能专用于 ZeroLaunch-rs Rust 项目） 2. 更新后的规则中提到的每个文件路径在磁盘上确实存在（逐个 Glob 验证） 3. 快速一致性检查：是否有两条规则现在互相矛盾？ 4. **并集守恒**（仅适用于拆分组）：拆分后小规则 `condition` ∪ 大规则(新) `condition` == 原大规则 `condition`，触发覆盖不丢失 5. **零重叠**（仅适用于拆分组）：拆分后两规则 `condition` 交集为空，不再重复触发 6. **同质/异质复核**：对每对重叠规则，确认"小规则是大规则主题子方面（同质）还是独立关切点（异质）"的判定成立 ## 核心原则（适用于规则文件） 以下原则指导本技能的所有判断： 1. **"如果删掉这条规则，AI agent 会不会更容易犯错？"** — 唯一的试金石。如果删掉一条规则不会改变 agent 的行为，立即删除。 2. **有原因的规则才具有泛化能力** — 每条约束必须解释为什么。"不要做 X，遇到这种情况应该做 Y"是禁止性规则的标准格式。 3. **不要记录工具已经能强制执行的内容** — 如果 ESLint/rustfmt/clippy 已经能捕获，就不要写进规则。 4. **缓慢添加，果断删除** — 每次出错就加一条规则是膨胀之路。等同一类错误重复出现 2-3 次再固化为规则。 5. **积极使用 scope 限定作用域** — 如果规则只适用于 `commands/` 或 `plugin_system/`，用 `scope` frontmatter 限定。不要全局加载。 6. **目标每个文件不超过 200 行** — 超过则按主题或路径拆分。 7. **具体优于模糊** — 将"注意性能"替换为具体、可验证的标准。 8. **审计冲突** — 两条规则说相反的话 = 两条都不会被遵循。积极消解冲突。 ## 参考资料 - OMP 官方文档: https://omp.sh/docs - OMP TTSR 规则: https://omp.sh/docs/customization/ttsr-rules - 规则文件最佳实践: https://omp.sh/docs/customization/context-files