Gitlink
/
gitlink-cli
0
0
Fork 49
Code Issues Pull Requests 11 Packages Projects Releases 10 Wiki Activity
gitlink-cli/skills/gitlink-cli-contract-guard/SKILL.md

13 KiB
Raw Blame History

name description
gitlink-cli-contract-guard GitLink CLI 契约专项审查：检查 flags 与默认值、命令层级与帮助、JSON 结构、错误和退出码、UTF-8、NO_COLOR、文档示例与安全输入边界，生成带 CG 编号和复现证据的只读 Markdown 报告。用户只需点名 gitlink-cli-contract-guard 并提供本地改动或一个/多个 PR；默认不调用其他 Skill、不修改远端。

已合并功能的增量证据

配套基础能力 PR #429 和 #430 扩展了 workflow 命令的参数与可选 JSON 字段。本 Skill 应把它们作为待验证的契约变更样本，而不是已合并前置；命令可用时核对旧调用兼容性、新开关默认值、changes/commits/ci_builds 字段可选性，以及 JSON 不含 ANSI、HTML 或敏感值：

gitlink-cli workflow +review-context --help
gitlink-cli workflow +review-queue --help
gitlink-cli workflow +review-queue --from queue.json --previous queue-previous.json --format json

本 Skill 只输出 CG- 契约问题；不把新增字段本身判为破坏性变化，也不替代代码质量、队列治理或集成门禁结论。

针对 workflow v2 字段，必须验证 --as-of、--stale-after-hours 的默认值与非法输入错误；验证 ci_summary、age_hours、waiting_on 等字段在 JSON 中保持类型稳定且可选。旧调用不传新开关时应保持原行为，Markdown 的 SLA/CI 摘要不得泄漏到 JSON，且中文输出必须通过 UTF-8 与替换字符检查。

gitlink-cli-contract-guard

CRITICAL - 如果需要拉取 GitLink 上的 PR 元数据、diff 或评论，先阅读 ../gitlink-shared/SKILL.md。 CRITICAL - 这个 skill 默认只读分析，不直接修改远端评论、标签或分配关系。 CRITICAL - 这个 skill 只关注 CLI 对用户承诺的行为契约，不负责判断 PR 是否应当合并。

默认调用契约

用户只需说“使用 gitlink-cli-contract-guard 检查 <owner>/<repo> 的 PR #<number>”或“检查当前本地改动”。多个 PR 可直接列出多个编号；除非目标无法确定，不再要求用户补充输出格式或报告路径。

点名后默认自动执行：

  • 只检查 CLI 契约，不调用其他 Skill，不评价业务价值、通用代码质量、PR 关系或维护者 SLA。
  • 只读运行，不评论、不 approve、不合并、不关闭、不修改远端。
  • 使用 CG-001 起的稳定编号，记录旧行为、新行为、复现命令、严重性、证据、修复建议和验证限制。
  • 首屏先显示兼容性结论、关键门禁和最多 5 项会影响现有用户或脚本的动作；blocking/high 使用颜色和粗体并保留文本标签。
  • 一次运行只生成一份 UTF-8 Markdown，保存到 reports/skill-runs/gitlink-cli-contract-guard/<owner>-<repo>-<scope>-<yyyyMMdd-HHmmssZ>.md；多个 PR 在同一报告内分开结论。

无法写入工作区时输出完整 Markdown 并标记“未落盘”。最终回复只需给出报告绝对路径、主结论和阻断数，不在聊天中重复整份报告。

首屏固定先使用以下结构，再展开完整契约面：

# CLI 契约审查摘要

**结论：** <span style="color:#B42318"><strong>阻断合并</strong></span> **[blocked]**
**门禁：** 参数 `passed` | 帮助 `passed` | JSON `failed` | 错误 `passed` | 安全 `not_run`
**发现：** blocking 1 | high 1 | medium 0 | low 0

## 先处理这 2 项

1. <span style="color:#B42318"><strong>[CG-001][blocking] 修复</strong></span> JSON 中的 ANSI，并补 golden 测试。
2. <span style="color:#B54708"><strong>[CG-002][high] 验证</strong></span> header 换行和注入边界。

这个 skill 的目标很窄，也很硬：找出会把现有 CLI 用户用法搞坏的改动。

它重点审查五类契约面：

  1. 参数契约：flag 名称、短别名、默认值、必填规则、参数语义。
  2. 帮助契约：命令层级、--help 内容、国际化文案、示例命令。
  3. 输出契约：--format json 结构、字段名、字段类型、包裹 envelope。

契约差异的分级与验证顺序

先保存旧版本的 --help、JSON 字段集合、错误码和关键 Markdown 片段作为基线，再对新版本做结构化比较。字段新增通常是兼容变化；字段删除、类型变化、默认值变化、退出码变化和旧命令失效才是高风险契约变化。只要文档、帮助和实际行为不一致，就生成 CG- 发现，即使代码本身可以编译。

验证按“旧调用不带新 flag、显式新 flag、正常 JSON、错误 JSON、table/markdown、中文 UTF-8、NO_COLOR、恶意边界输入”顺序执行。JSON 只允许数据字段，不能包含 ANSI、HTML、Token、Cookie 或 Authorization；Markdown 可以有醒目样式，但必须有纯文本回退。新字段缺失时，必须确认是合法可选字段，而不是把失败响应误当成空对象。

对 workflow 命令还要核对 ci_summary 的匹配模式、队列 as_of/SLA 字段和 waiting_on 的空值语义。契约守卫只报告用户可感知的兼容问题，不把业务价值、代码风格或维护者等待时长本身判为契约失败。

输出必须带 CG- 稳定编号、旧/新行为、复现命令、严重性和证据引用；基线不完整时结论为 observe 或 blocked，不能用当前版本自身的输出证明兼容。 4. 错误契约：错误提示、退出语义、编码质量、用户可理解性。 5. 文档契约：README、示例、帮助文本与真实行为是否一致。

效率版契约门禁

默认遵循 ../gitlink-shared/references/maintenance-report-contract.md，先给维护者一个兼容性决策，再列证据。首屏最多展示 5 个会阻断合并或影响脚本用户的动作，问题编号使用 CG-xxx。

运行键、证据台账、刷新和自动回写边界遵循 ../gitlink-shared/references/maintenance-run-protocol.md。

除五类既有契约面外，增加安全契约检查：

  • token、cookie、Authorization 和调试输出必须脱敏，不能进入 Markdown 或 JSON 报告。
  • header、path、query、文件路径和 shell 参数在模板渲染后仍需校验，防止注入和路径遍历。
  • --format json 不得混入 ANSI 颜色、HTML 标签、日志或非 JSON 文本；退出码要能区分成功、参数错误、认证失败和远端失败。
  • 认证、权限、webhook、文件读写、外部 URL 和新依赖改动必须进入安全矩阵，并补未登录、无权、恶意输入和超时测试。

推荐首屏格式：

# CLI 契约审查摘要
**结论：** <span style="color:#B42318"><strong>阻断合并</strong></span> **[blocked]**
**门禁：** 参数通过 | 帮助通过 | JSON 失败 | 错误提示通过 | 安全未验证

## 先做这 2 件事
1. **[CG-001][blocking] 修复** JSON 输出中的 ANSI 转义，并补 golden 测试（责任：作者）。
2. **[CG-002][high] 验证** `--header` 渲染后的换行和注入边界（责任：作者）。

关键验证至少包括：旧命令和默认值、--help、正常 JSON、错误 JSON、退出码、中文 UTF-8、NO_COLOR、敏感值脱敏和恶意边界输入。使用 golden/snapshot 或等价结构化断言，避免只检查命令返回 0。

职责边界与组合协同

独立运行时，本 Skill 只判断 CLI 用户契约是否保持兼容，不评价业务功能价值、通用代码质量或维护者队列优先级。组合运行时向 gitlink-pr-integrator 交接 CG-xxx 契约门禁；与 gitlink-code-review 同时命中安全问题时，保留 CLI 边界证据并通过 related_ids 关联代码层发现，避免重复催办。

不覆盖的内容

下面这些不属于这个 skill 的职责：

  • PR 是否值得合并：由 gitlink-code-review 和 gitlink-pr-integrator 提供价值与集成依据
  • PR 是否适合集成主线：交给 gitlink-pr-integrator
  • commit message、分支命名、PR 模板质量：交给 gitlink-commit-quality
  • 维护者今日值班优先级：交给 gitlink-maintainer-radar

工作流

Step 1：确定分析对象

优先区分两种输入：

  • 本地改动：当前工作区已有变更或已 checkout 到目标分支，直接看 git diff、文件改动和本地测试。
  • 远端 PR：用户只给出 GitLink PR 编号，需要先通过 gitlink-cli 拉 PR 元数据和 diff，再结合本地代码理解。

如果是本地改动，优先看：

git diff --name-only
git diff --stat

如果是 GitLink PR，优先看：

gitlink-cli pr +view --owner <owner> --repo <repo> -i <number> --format json
gitlink-cli pr +version-diff --owner <owner> --repo <repo> -i <number> --format json

Step 2：把改动映射到契约面

根据改动文件，先判断它可能影响哪一类契约。常见映射见 references/contract-surfaces.md。

重点关注这些高风险位置：

  • cmd/：根命令、全局 flag、命令层级、帮助文本
  • shortcuts/*/*.go：shortcut 参数、默认值、必填规则、输出行为
  • shortcuts/common/：通用运行时、输出封装、参数解析
  • internal/client/、internal/auth/：API client 行为、header、错误处理
  • internal/i18n/：国际化文案、语言切换、编码风险
  • README.md、README.zh-CN.md、examples/：文档和真实行为漂移

Step 3：逐类检查契约是否被破坏

3.1 参数契约

检查：

  • 是否删除或重命名了已有 flag
  • 是否变更了短别名
  • 是否改了默认值但没有迁移说明
  • 是否把原本可选参数改成必填
  • 是否改变了 flag 含义但名字未变

对 shortcut 代码重点查看 Name、Short、Default、Required、Bool、Usage。

3.2 帮助契约

检查：

  • 命令层级是否变了
  • --help 内容是否仍然描述真实行为
  • 示例命令是否还可运行
  • 中英文帮助文本是否同步
  • 本地化 key 是否丢失或回退异常

如果触及 cmd/root.go、shortcuts/register.go 或 i18n 文案，优先检查 help 相关测试。

3.3 输出契约

检查：

  • --format json 是否仍然返回既有结构
  • 字段名是否发生破坏性变更
  • 字段类型是否变化
  • envelope 是否还保持稳定
  • 机器可读消费者依赖的路径是否变化

如果字段是新增但非破坏性变更，要明确说明是“扩展”而不是“破坏”。

3.4 错误契约

检查：

  • 错误消息是否退化为难以理解的技术细节
  • 中文或多语言提示是否出现乱码
  • suggestFix、校验错误、缺参错误是否还可读
  • 渲染后的 header、path 模板或其他用户输入是否可能导致非法请求

尤其要把 中文 mojibake、编码损坏、格式化后非法 header/path 当成高风险契约问题。

3.5 文档契约

检查：

  • README 中的示例命令是否与当前实现一致
  • 文档新增内容是否引入乱码
  • 文档说支持的参数/输出，代码是否真的支持
  • 代码新增能力后，帮助或 README 是否漏更新

Step 4：要求验证证据

只指出风险还不够，要同时判断“有没有证据证明它没坏”。

常用验证方式：

go build ./...
go test ./cmd/... ./shortcuts/...
go test ./...

需要更聚焦时，优先跑与改动最相关的包测试。典型情况：

  • 改 cmd/ 或帮助/i18n：优先看 cmd/root_test.go
  • 改 shortcut 参数或输出：优先看对应 shortcuts/<name>/*_test.go
  • 改 API client 或错误处理：优先看 internal/... 和相关 shortcut 测试

如果改动了契约面，但没有补测试或现有测试没覆盖到，直接把它列为缺口。

Step 5：按严重性归类

用 references/severity-rubric.md 把问题分成：

  • blocking：明确破坏旧用法或输出契约
  • high：高概率影响真实用户或自动化脚本
  • medium：存在漂移或边界缺口，但不一定立即破坏
  • low：文案、可读性或一致性问题

Step 6：输出契约审查结论

推荐输出结构：

# CLI 契约审查报告

## 高风险问题
- `--header` 模板渲染后未再次校验，可能生成非法 header。
- README.zh-CN 新增示例出现中文乱码，会污染用户可见文档。

## 契约面影响
- 参数契约：`--header` 新增并改变请求构造行为。
- 输出契约：无破坏性字段变更证据。
- 错误契约：中文错误提示存在编码退化风险。

## 缺失验证
- 缺少对 `Accept` 头覆盖行为的边界测试。
- 缺少对渲染后非法 header 的测试。

## 结论
- 需要修改后再合并。

典型触发语句

  • “帮我看这个改动会不会破坏现有 CLI 用法。”
  • “检查这个 PR 有没有 flag / help / JSON 输出兼容性问题。”
  • “看看这个命令改动会不会影响脚本调用方。”
  • “帮我做一轮 CLI 行为契约审查。”