dogfood-cli

使用 vigiles CLI 进行自测（专家级问题发现与修复分工）

通过让工具检查自身和真实插件，找出 vigiles 中的实际缺陷并直接修复，而不是提交缺陷报告。这是 2026-07 批次发现并修复 14 个经源码追踪确认的缺陷所采用的方法。

何时使用

• “对 CLI 进行自测”、“用源码追踪的方式找出更多缺陷”、“分派多个 Agent 审查 vigiles 本身”、“排查 audit/lint 中的误报”。
• 不适用于已知的单个缺陷（直接修复即可），也不适用于已发布的用户功能（这只是贡献者专用的开发流程；.claude/ 不会发布）。

循环流程

fan out (parallel experts) → synthesize + VERIFY each finding → fix directly
   → regression test → build → targeted test → commit per theme → FULL SUITE → push

1. 分派任务，覆盖不同的检查面

启动多个 Agent（Sonnet——适合低成本并行阅读和追踪；每个 Agent 无需综合分析），每个 Agent 负责一个检查面，避免任务重叠。以下检查面的效果不错：

• compile / eject — 往返正确性、frontmatter/数据丢失、完整性。
• audit / lint 误报 — 真实插件必须保持干净（不要虚惊一场）；幽灵路径；误读 glob/引号标记；仅注释中的匹配项。
• init / scaffold 边缘情况 — 没有 package.json、由配置驱动的 harness、格式错误的 frontmatter、--target、生成的 CI 工作流、--test/--lint。
• 只解析、不校验配置 — .vigilesrc.json 严重级别（"off"/0/1/2）、字符串或数组类型的键、未知值。
• CLI 错误提示体验 — 未知标志或 harness 必须输出清晰的消息并以状态码 2 退出，绝不能输出原始 Node 堆栈跟踪。
• 跨 harness（CC + Codex）及浏览器/磁盘一致性 — scanFiles 必须与 scanPlugin 逐字节一致；Codex 结构的仓库不得被当作 CC 仓库扫描。

告诉每个 Agent：通过源码追踪，将每个缺陷定位到 文件:行号，并提出修复方案。 未经追踪的发现只是线索，不是缺陷。

2. 综合分析 + 自行验证

Agent 往往会报告过多问题。在修改任何内容之前，亲自复现每个发现（在临时 fixture 或 vendored 的 test/dogfood/* 插件上运行实际构建的 CLI）。无法复现的就丢弃。确认准确的 文件:行号。

3. 直接修复——不要提交缺陷报告

对于经源码追踪确认、结果确定的缺陷，无需提交 issue：直接修复。只有在修复确实存在歧义时才提交 issue（存在多种合理解释，或涉及需要创始人权衡的重大架构变更）。“修复，不提交”是创始人对此流程的一贯要求。

每个修复都要：

• 复现 → 修复 → 回归测试 → npm run build → 有针对性的 vitest → 提交。
• 每次提交只涉及一个主题。 使用 Conventional Commit 格式的主题；正文末尾添加 Co-Authored-By: Claude … 提交说明。绝不要包含会话 URL 或原始模型 ID（这是公开仓库——参见 no-session-links / model-identity 规则）。
• 修复必须精确可靠——修复误报时不得悄悄造成漏检（不要为了避免虚惊一场而漏掉真正的问题）。
• 遵循架构：共享检测器只能有一个归属位置（one-detector-no-drift）；core ⊄ adapter；src/core/** 和无关检测器中不得出现 CC 字面值。

来之不易的经验教训

• 序列化／合并对 SHARED 文件的修复（src/cli.ts、 src/scan-core.ts）。并行编辑同一文件会产生冲突——请按顺序处理，或为每个 Agent 分配自己的 git worktree（isolation: "worktree"）。
• 宣布完成前，运行完整测试套件。 只有运行全部测试时，_不相关_测试文件中的 严格断言才可能暴露问题——I2 修复更改了一条安装命令，另一个 e2e 文件中的 严格正则表达式因此失效；逐文件运行时全部通过，而完整的 vitest run 发现了 问题。
• 每次修改源代码后都要重新构建——e2e 测试运行的是 dist/cli.js，因此 过期的 dist/ 会悄悄地让测试继续测试旧代码。
• 留意一致性门禁。 对扫描检测器的任何更改，都必须确保 scanFiles ↔ scanPlugin 逐字节一致（src/scan-files.test.ts）；如果磁盘端增加 了字段，浏览器端也需要有这个字段。
• 提交前运行 Prettier 和 fmt:check——Markdown 代码跨度周围需要有空格； CI 会运行 fmt:check。
• 覆盖率门禁采用允许列表（vitest.config.ts 中的 coverage.include）—— 新增文件若位于该列表范围内，就需要达到 100%；目前 scan/cli 文件不在其中。

两类反复出现的 Bug——发现后排查，并从根本上防止这类问题

这个仓库几乎所有 Bug 都属于以下两类之一。发现一个实例时，就用 GREP 查找同类 问题，并添加门禁，防止这类问题再次出现。

1. 对外部契约的假设未经验证

代码猜测外部事物的行为，却没有进行核实：CLI 标志的格式（原以为 skills 的 -s 接受逗号分隔，实际却是空格分隔 → 安装以 1 退出）、运行框架的 frontmatter 键（skills 使用 allowed-tools，而不是 tools:）、git 的行为（在子目录中运行 git config origin 会向上遍历到父仓库）、模块解析（没有 package.json 时无法 解析 vigiles）、linter 的启用状态（severity=ignore 的 checkstyle 模块处于 禁用状态）。

• 在边界处解析，而非验证。 编码前先查阅真实契约——工具的 --help、其在 node_modules 中的参数解析器、git rev-parse、linter 自身的状态逻辑。不要 猜测，要核实。
• 为命令／格式的结构添加单元断言，而不只是依赖受网络／二进制文件影响的 e2e 测试。运行真实命令的 e2e 测试在开发环境中会跳过（没有网络／没有 claude／没有 linter 二进制文件），因此不是可靠的保障——只有 CI 会运行它。 单元测试应以外部工具相同的方式解析构造出的命令（例如 setup-plan.test.ts 中对 -s 按空格拆分的断言），这样回归发生时就能立即 离线失败。

2. 修复不完整——只修复某种模式的部分调用点，而不是全部

某种模式在一处修复了，但其他地方仍然存在：audit／init 遵循 config.harness，但 test／eval／generate harness 没有；E1 修复了 ScanAgent.path，但没有修复 frontmatter 系列的发现项；一个检测器添加了注释剥离 逻辑，下一个检测器却没有。

• 修复一处后，立即用 GREP 查找该模式的每个实例。
• 让无效状态不可表示——设立单一关口。 让每个调用方都通过同一个辅助函数 （例如 resolveCommandHarness），这样新调用点就无法绕过它；并添加门禁测试， 确保旧路径一旦重新出现就会失败（cli-harness-resolution.test.ts 断言 cli.ts 从不调用原始检测器）。
• 扫描原始文本的检测器有共同风险（在注释／示例／说明性文字中匹配）——请检查 是否已有共享的文本上下文辅助函数，并确保重复使用，而非为每个检测器重新编写； 同时确保 FP 防护夹具测试通过。

不是本技能的内容

盲测 Agent 上手体验（一个全新的 Agent 在 GHA 的多 OS 矩阵中，对真实仓库运行 npx vigiles init，再进行订阅评估）是单独规划的 e2e 工作——不要把它的 OS 矩阵并入这里。本技能关注仓库内部的查找与修复循环；而前者衡量的是从头到尾的冷启动 上手体验。