[VOD Agent] 任务已完成。

[Issue Agent] 📋 Spec Document

Spec: Issue #199 — 建立 runbook 命令示例与 grape CLI 契约的同步校验机制（防文档漂移）

Generated by Issue Agent | Developability: ready | 2026-10-30

Objective

• 构建：一个可重复执行的校验脚本 + CI 接入，自动比对技能包 runbook 中的 grape ... 命令示例与 CLI 实际契约（命令存在性 + 选项级合法性）。
• 价值：杜绝「文档写 A、CLI 只支持 B」的漂移，消除 Agent 执行时逐条 --help 试错的成本（#154/#157/#113 等反馈均事后暴露）。
• 用户：本仓维护者、所有消费 runbook 的 Agent（vod/qa/issue/pr/sre）。
• 成功标准：能检出 #154（issues 组 --state 注解残留）与 #157（feedback submit 独立参数形式）两类已知漂移作为冒烟用例；全量扫描 skills/**/references/*.md 输出差异报告；接入合入/发布流程。

Scope

In Scope

• 校验脚本：解析 skills/**/references/*.md（含 *-runbook.md 与 grape-cli-reference.md）代码块中的 grape ... 命令示例
• 契约来源：grape commands 列表 + 各子命令 --help 输出（或缓存为 JSON 快照），校验命令/子命令存在性与选项合法性（含组间差异：issues 组无 --state、git-repo 组 --state 合法）
• 冒烟用例：以 #154、#157 两个已知漂移验证检出能力
• 全量扫描一次并输出可定位的差异清单（文件:行号 + 差异描述）
• CI 接入（GitCode 流水线或仓内 lint 脚本约定），契约升级后可一键重跑

Out of Scope

• 平台侧技能同步/部署时的同款校验（grape 仓范畴，本 Issue 可选增强，仅留接口建议）
• #154/#157 两处文档本身的修正（独立 Issue 跟进，不互相阻塞）
• 非 grape 命令示例（bash/jq 等）的语法校验

Technical Approach

方案概述

Python 校验脚本（如 scripts/check_grape_cli_drift.py）：抽取 markdown 代码块中的 grape 命令行 → 解析为命令/子命令/选项 → 与 CLI 契约快照比对 → 输出差异清单并以非零退出码阻断。

实现路径

1. 契约采集：调用 grape commands（及关键子命令 --help）生成契约快照 JSON（tools/contract-snapshot），随脚本可重新生成
2. 命令抽取：遍历 skills/**/references/*.md 代码块，匹配以 grape 开头的命令行（剔除注释/续行等噪声）
3. 比对校验：命令组/子命令存在性 → 选项级校验（未知选项、组间同义差异）→ --json 请求体字段粗校验（如 feedback submit 仅支持 --json）
4. 冒烟验证：将 #154（vod-runbook Step 2 issues list --state all）与 #157（qa-runbook Step 6c feedback submit 独立参数）作为断言用例
5. 全量扫描 + 报告输出；接入 CI（合入/发布触发）或 README 约定契约升级后重跑命令

关键设计决策

Affected Modules

依赖关系：无对现有 skills 内容的改动（纯增量工具链）。

Acceptance Criteria

• 校验脚本在本仓可运行，对 #154 漂移（issues 组 --state 注解残留）报检出
• 对 #157 漂移（feedback submit --category/--title/--description 独立参数）报检出
• 对全部 skills/**/references/*.md 完成一次全量扫描并输出报告（文件:行号级定位）
• 校验接入合入/发布流程，或在 CONTRIBUTING 明确契约升级后重跑命令
• 校验通过场景（正确命令示例）无误报

Risks & Mitigations

Open Questions

• 无

[Coding Agent] ✅ 已完成实现，请审查 PR #74。

交付：契约快照生成脚本 + 漂移校验脚本（文件:行号级报告、漂移非零退出阻断）+ 11 个单元测试（#154/#157 冒烟断言均通过）+ CONTRIBUTING 合入必跑约定。全量扫描 353 个 references/*.md 检出 26 处漂移（#154 于 vod-runbook.md:55、#157 共 4 处），报告见 PR 内 docs/issue-199/drift-report.md；正确示例零误报。skills 内容未改动，漂移修复留独立 Issue。

已合入，关闭

• PR #74 已合入 main（2026-11-02）：scripts/gen_grape_cli_contract.py / scripts/check_grape_cli_drift.py + 契约快照 + CONTRIBUTING 纳入。
• 流水线产物（docs/issue-199）已按要求剥离，不膨胀技能包。
• 后续建议（非阻塞）：契约快照 ools/contract/grape_cli_contract.json 建议改由 CI 实时生成，避免随 CLI 演进长期漂移；本 issue 关闭。

[QA Agent] 已知悉关闭说明，确认 Issue #199 闭环。

引用 @dongzhiri 原评论：

已合入，关闭

• PR #74 已合入 main（2026-11-02）：scripts/gen_grape_cli_contract.py / scripts/check_grape_cli_drift.py + 契约快照 + CONTRIBUTING 纳入。
• 流水线产物（docs/issue-199）已按要求剥离，不膨胀技能包。
• 后续建议（非阻塞）：契约快照 \tools/contract/grape_cli_contract.json 建议改由 CI 实时生成，避免随 CLI 演进长期漂移；本 issue 关闭。

验收确认

• PR #74 状态复核：state=merged、merged_at=2026-11-02T16:39:30+08:00、mergeable_state 全项 passed、approval_reviewers/approvers/testers 均 passed（2/2），合入链路完整无残留。
• 交付物落地确认：scripts/gen_grape_cli_contract.py / scripts/check_grape_cli_drift.py / tools/contract/grape_cli_contract.json / scripts/tests/test_check_grape_cli_drift.py / CONTRIBUTING(.zh).md 均随 PR #74 进入 main；docs/issue-199 流水线产物未纳入技能包，符合「不膨胀」约定。
• 校验机制冒烟基线：11 个单元测试全绿，#154（issues list --state 漂移）与 #157（feedback submit 独立参数）作为冒烟断言均检出，正确示例零误报——既为交付物自身背书，也为本仓后续 runbook 维护提供可复跑的漂移阻断能力。

后续建议（呼应原评论「非阻塞」项，登记不立项）

• 契约快照由 CI 实时生成：当前快照随仓提交（cli 0.3.3 / 91 命令），随 grape CLI 演进存在长期漂移风险；建议在 GitCode 流水线中增加 python3 scripts/gen_grape_cli_contract.py --regen 步骤，使快照生成与 CLI 版本绑定，避免人工升级滞后。该项作为增强项记录，不阻塞本 issue 关闭。
• 漂移修复独立跟进：全量扫描检出的 26 处历史漂移（含 #154 / #157）由独立 Issue 修复，与本 issue 解耦，符合 Spec Out of Scope。

结论

两轴审查基线在合入时已复核（Standards 0 / Spec 0，merge-danger: none），合入后无回归。本 issue 关闭确认，QA 流程终止。