|
|
|
|
@ -1,14 +1,64 @@
|
|
|
|
|
---
|
|
|
|
|
name: gitlink-cli-contract-guard
|
|
|
|
|
description: "CLI 契约守卫：审查 GitLink CLI 改动是否破坏既有命令契约，重点检查 flags 与默认值、命令层级与帮助文本、`--format json` 输出结构、错误提示与编码质量、README/示例命令和实际行为是否漂移。用于用户需要判断某个 PR 或本地改动会不会破坏旧用法、引入不兼容输出、造成帮助文档失真，或在合并前补做兼容性审查时。"
|
|
|
|
|
description: "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 或敏感值：
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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`](../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 使用颜色和粗体并保留文本标签。
|
|
|
|
|
- 聊天和报告首屏按 PR 分节；参数与帮助、JSON/文本输出、错误与退出码、编码与颜色、兼容与文档、契约结论分别使用结论前置判断卡，后接解释、`依据：` 和影响/下一步。
|
|
|
|
|
- 一次运行只生成一份 UTF-8 Markdown，保存到 `reports/skill-runs/gitlink-cli-contract-guard/<owner>-<repo>-<scope>-<yyyyMMdd-HHmmssZ>.md`；多个 PR 在同一报告内分开结论。
|
|
|
|
|
|
|
|
|
|
最终回复复用报告首屏的逐 PR 六方面判断卡，再给报告绝对路径；不能把多个 PR 或方面压成一段，也不能只给路径。无法写入工作区时输出完整 Markdown 并标记“未落盘”。
|
|
|
|
|
|
|
|
|
|
首屏固定先使用以下结构，再展开完整契约面：
|
|
|
|
|
|
|
|
|
|
```markdown
|
|
|
|
|
# CLI 契约审查摘要
|
|
|
|
|
|
|
|
|
|
## PR #<number>
|
|
|
|
|
**参数与帮助：** <span style="color:#067647"><strong>旧调用保持兼容</strong></span> **[passed]**：新 flag 为可选且默认行为不变；依据：baseline/current `--help` 与旧调用对照；影响：现有用户无需迁移。
|
|
|
|
|
**JSON/文本输出：** <span style="color:#B42318"><strong>机器输出已被破坏</strong></span> **[failed]**：ANSI 状态文本混入 JSON；依据：golden 解析和原始字节；下一步：分离人读渲染与 JSON。
|
|
|
|
|
**错误与退出码：** <span style="color:#067647"><strong>错误语义稳定</strong></span> **[passed]**：参数错误和远端失败仍可区分；依据：失败命令、stderr 和退出码；影响：自动化可继续判断故障。
|
|
|
|
|
**编码与颜色：** <span style="color:#B54708"><strong>颜色边界未完整验证</strong></span> **[partial]**：中文 UTF-8 正常但 `NO_COLOR` 缺测；依据：编码扫描和测试清单；下一步：补无颜色回归。
|
|
|
|
|
**兼容与文档：** <span style="color:#B54708"><strong>文档与行为部分不一致</strong></span> **[partial]**：示例未说明新增字段可选性；依据：README、帮助与实际 JSON 对照；下一步：同步说明。
|
|
|
|
|
**契约结论：** <span style="color:#B42318"><strong>修复 JSON 后再审</strong></span> **[blocked]**：存在一个 blocking 契约问题；依据：CG-001 与复现命令；下一步：修复并重跑完整矩阵。
|
|
|
|
|
|
|
|
|
|
## 先处理这 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 换行和注入边界。
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
多个 PR 在同一报告中重复 `## PR #<number>` 和六张判断卡，不能共享状态或证据。
|
|
|
|
|
|
|
|
|
|
这个 skill 的目标很窄，也很硬：**找出会把现有 CLI 用户用法搞坏的改动。**
|
|
|
|
|
|
|
|
|
|
它重点审查五类契约面：
|
|
|
|
|
@ -16,14 +66,58 @@ description: "CLI 契约守卫：审查 GitLink 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、示例、帮助文本与真实行为是否一致。
|
|
|
|
|
|
|
|
|
|
## 效率版契约门禁
|
|
|
|
|
|
|
|
|
|
先给维护者一个兼容性决策，再列证据。首屏最多展示 5 个会阻断合并或影响脚本用户的动作，问题编号使用 `CG-xxx`。每次运行记录目标、默认分支 SHA、采集时间、实际命令、退出码和证据缺口；默认只读，除非用户明确授权，不自动回写任何远端对象。
|
|
|
|
|
|
|
|
|
|
除五类既有契约面外，增加安全契约检查：
|
|
|
|
|
|
|
|
|
|
- token、cookie、Authorization 和调试输出必须脱敏，不能进入 Markdown 或 JSON 报告。
|
|
|
|
|
- header、path、query、文件路径和 shell 参数在模板渲染后仍需校验，防止注入和路径遍历。
|
|
|
|
|
- `--format json` 不得混入 ANSI 颜色、HTML 标签、日志或非 JSON 文本；退出码要能区分成功、参数错误、认证失败和远端失败。
|
|
|
|
|
- 认证、权限、webhook、文件读写、外部 URL 和新依赖改动必须进入安全矩阵，并补未登录、无权、恶意输入和超时测试。
|
|
|
|
|
|
|
|
|
|
推荐首屏格式：
|
|
|
|
|
|
|
|
|
|
```markdown
|
|
|
|
|
# CLI 契约审查摘要
|
|
|
|
|
## PR #<number>
|
|
|
|
|
**参数与帮助：** <span style="color:#067647"><strong>默认调用兼容</strong></span> **[passed]**：新参数保持旧默认值；依据：baseline/current 帮助和旧调用对照；影响：无需迁移。
|
|
|
|
|
**JSON/文本输出：** <span style="color:#B42318"><strong>JSON 已被 ANSI 破坏</strong></span> **[failed]**：机器输出无法稳定解析；依据：golden 解析与原始字节；下一步：隔离渲染。
|
|
|
|
|
**错误与退出码：** <span style="color:#067647"><strong>错误语义稳定</strong></span> **[passed]**：退出码仍可区分错误；依据：失败矩阵；影响：脚本兼容。
|
|
|
|
|
**编码与颜色：** <span style="color:#B54708"><strong>注入和 NO_COLOR 未验证</strong></span> **[partial]**：边界测试缺失；依据：测试清单；下一步：补恶意输入。
|
|
|
|
|
**兼容与文档：** <span style="color:#B54708"><strong>文档说明不完整</strong></span> **[partial]**：未说明字段可选性；依据：README 与实际输出；下一步：同步文档。
|
|
|
|
|
**契约结论：** <span style="color:#B42318"><strong>修复 JSON 后再审</strong></span> **[blocked]**：存在 blocking 问题；依据：CG-001；下一步：修复并重跑矩阵。
|
|
|
|
|
|
|
|
|
|
## 先做这 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-pr-assessor`
|
|
|
|
|
- PR 是否值得合并：由 `gitlink-code-review` 和 `gitlink-pr-integrator` 提供价值与集成依据
|
|
|
|
|
- PR 是否适合集成主线：交给 `gitlink-pr-integrator`
|
|
|
|
|
- commit message、分支命名、PR 模板质量：交给 `gitlink-commit-quality`
|
|
|
|
|
- 维护者今日值班优先级：交给 `gitlink-maintainer-radar`
|
|
|
|
|
@ -153,27 +247,7 @@ go test ./...
|
|
|
|
|
|
|
|
|
|
### Step 6：输出契约审查结论
|
|
|
|
|
|
|
|
|
|
推荐输出结构：
|
|
|
|
|
|
|
|
|
|
```markdown
|
|
|
|
|
# CLI 契约审查报告
|
|
|
|
|
|
|
|
|
|
## 高风险问题
|
|
|
|
|
- `--header` 模板渲染后未再次校验，可能生成非法 header。
|
|
|
|
|
- README.zh-CN 新增示例出现中文乱码，会污染用户可见文档。
|
|
|
|
|
|
|
|
|
|
## 契约面影响
|
|
|
|
|
- 参数契约：`--header` 新增并改变请求构造行为。
|
|
|
|
|
- 输出契约：无破坏性字段变更证据。
|
|
|
|
|
- 错误契约：中文错误提示存在编码退化风险。
|
|
|
|
|
|
|
|
|
|
## 缺失验证
|
|
|
|
|
- 缺少对 `Accept` 头覆盖行为的边界测试。
|
|
|
|
|
- 缺少对渲染后非法 header 的测试。
|
|
|
|
|
|
|
|
|
|
## 结论
|
|
|
|
|
- 需要修改后再合并。
|
|
|
|
|
```
|
|
|
|
|
聊天和 Markdown 首屏必须使用前述逐 PR 六方面判断卡，详细 `CG-` 发现、命令和 golden 差异放在后文。交付前严格按 UTF-8 重读报告，并检查每个目标均包含六张判断卡、至少一个可复现命令和明确的 `CG-` 证据；不满足时必须重写，不能交付报告路径。只有本地改动且不存在 PR 编号时，可以用 `## PR #0` 表示本地候选，并在解释中注明不是远端 PR。
|
|
|
|
|
|
|
|
|
|
## 典型触发语句
|
|
|
|
|
|
|
|
|
|
|
Mengz