feat(skills): 新增 gitlink-cli-contract-guard skill

2026-06-26 12:02:15 +08:00 · 2026-06-26 12:02:15 +08:00 · 036939ccff
parent 71ca2bb683
commit 036939ccff
12 changed files with 441 additions and 367 deletions
--- a/skills/gitlink-ci-health/EXAMPLES.md
+++ b/skills/gitlink-ci-health/EXAMPLES.md
@ -1,178 +0,0 @@
-# gitlink-ci-health 使用样例
-
-## 样例 1：CI 未激活的仓库
-
-**日期**：2026-06-03
-**仓库**：jiangtx/gitlink-cli（Fork from Gitlink/gitlink-cli）
-**CLI 版本**：gitlink-cli 0.1.18
-
-### 执行流程
-
-```bash
-# Step 1: 检查 CI 状态（方法 1 — repo +info）
-gitlink-cli repo +info --owner jiangtx --repo gitlink-cli --format json
-# → "open_devops": false  ← CI 未激活
-
-# Step 1 补充（方法 2 — ci +builds）
-gitlink-cli ci +builds --owner jiangtx --repo gitlink-cli --format json
-# → {"status":-1,"message":"接口数据异常"}  ← 确认 CI 未激活
-
-# 此时终止后续步骤，生成"CI 未激活"报告
-```
-
-### 关键发现
-
-| 项目 | 值 |
-|------|-----|
-| `open_devops` | `false` |
-| `ci +builds` 返回 | `{"status": -1, "message": "接口数据异常"}` |
-| 可用 CI 命令 | `+builds`、`+logs`、`+restart`、`+stop` |
-| 不存在的命令 | `ci +authorize`、`ci +activate`、`ci +deactivate` |
-
-### 诊断结论
-
-CI 完全未启用，需通过 GitLink Web 界面开启（仓库设置 → DevOps）。用户拥有 Manager 权限，可以操作。
-
-### 生成的报告
-
-```markdown
-# 🔧 CI 健康巡检报告：jiangtx/gitlink-cli
-
-> 巡检时间：2026-06-03
-> 仓库：jiangtx/gitlink-cli（Fork from Gitlink/gitlink-cli）
-> CI 状态：❌ 未激活
-
-## 一、健康度总览
-
-| 指标 | 数值 | 评分 |
-|------|------|------|
-| CI 激活状态 | ❌ 未激活（open_devops: false） | 0/4 |
-| 整体成功率 | N/A | —/5 |
-| 近期稳定性 | N/A | —/5 |
-| 构建频率 | N/A | —/3 |
-| 修复速度 | N/A | —/3 |
-| **总分** | | **0/20** |
-
-## 二、诊断详情
-
-API 调用 ci +builds 返回：
-{"status": -1, "message": "接口数据异常"}
-
-仓库元数据显示 open_devops: false，确认该仓库尚未启用 GitLink 平台的 CI/CD（DevOps）服务。
-
-## 三、改进建议
-
- 🔴 立即激活 CI：前往 GitLink Web 界面 → 仓库设置 → DevOps 开启 CI/CD 服务
- 🟡 配置 CI Pipeline：建议添加 .gitlink-ci.yml 配置编译和测试流水线
-
-## 四、仓库基本信息
-
-| 项目 | 值 |
-|------|-----|
-| 默认分支 | master |
-| 仓库大小 | 13.4 MB |
-| 贡献者 | 2 |
-| PR 数量 | 9 |
-| 权限 | Manager |
-```
-
---
-
-## 异常场景速查
-
-| 场景 | 检测方式 | `ci +builds` 返回值 | 处理 |
-|------|----------|---------------------|------|
-| CI 未激活 | `repo +info` 的 `open_devops: false` | `{"status":-1,"message":"接口数据异常"}` | 建议 Web 界面激活，终止巡检 |
-| CI 已激活但无构建 | `repo +info` 的 `open_devops: true` + builds 为空 | `[]` 或空列表 | 标注"暂无构建记录" |
-| 构建样本不足（<5） | builds 列表长度 < 5 | 正常 JSON 数组 | 标注"数据有限，不具代表性" |
-
---
-
-## 版本兼容性说明
-
-本 skill 基于 `gitlink-cli 0.1.18` 编写。不同版本的 CI 子命令可能有差异：
-
-| CLI 版本 | 可用 CI 命令 |
-|----------|-------------|
-| 0.1.18 | `+builds`、`+logs`、`+restart`、`+stop` |
-| 未来版本 | 可能新增 `+activate`、`+deactivate` 等 |
-
-当 CLI 版本更新后，重新验证可用命令：
-```bash
-gitlink-cli ci --help
-```
-
---
-
-## 样例 2：通过 Agent 调用 Skill（自动巡检）
-
-**日期**：2026-06-03
-**仓库**：jiangtx/gitlink-cli
-**调用方式**：`Agent(subagent_type="general-purpose", prompt="调用 gitlink-ci-health skill，检查 jiangtx/gitlink-cli 的 CI 状态。严格按照 skill 的工作流步骤执行。")`
-
-### Agent 自主执行的命令序列
-
-```
-工具调用 1: gitlink-cli repo +info --owner jiangtx --repo gitlink-cli --format json
-           → open_devops: false  ← 发现 CI 未激活
-
-工具调用 2: gitlink-cli ci +builds --owner jiangtx --repo gitlink-cli --format json
-           → {"status": -1, "message": "接口数据异常"}  ← 二次确认
-```
-
-### Agent 决策过程
-
-Agent 读取到 `open_devops: false` 后，**正确遵循了 skill 的异常场景处理规则**：
-
-> "CI 未激活 → 报告 CI 状态为'未激活'，建议通过 Web 界面开启，**不再继续后续步骤**"
-
-Agent 没有继续尝试 `ci +logs` 或统计分析，直接生成了完整报告。共消耗 **5 次工具调用**，**32,113 tokens**，耗时 **35.8 秒**。
-
-### Agent 生成的报告
-
-```markdown
-# CI 健康巡检报告：gitlink-cli
-
-> 巡检时间：2026-06-03
-> 仓库：jiangtx/gitlink-cli
-> CI 状态：未激活
-
-## 一、健康度总览
-
-| 指标 | 数值 | 评分 |
-|------|------|------|
-| CI 激活状态 | 未激活 | 0/4 |
-| 整体成功率 | N/A | -/5 |
-| 近期稳定性 | N/A | -/5 |
-| 构建频率 | N/A | -/3 |
-| 修复速度 | N/A | -/3 |
-| **总分** | | **0/20** |
-
-## 二、构建趋势
-
-无构建记录。仓库 CI 未启用。
-
-## 三、故障分析
-
-CI 未激活，无构建数据可供分析。
-
-## 四、改进建议
-
- **立即激活 CI**：前往 GitLink Web 界面 → 仓库设置 → DevOps，开启 CI/CD 服务。
-  （CLI 暂不支持 ci +activate 命令，需要通过 Web 界面操作。）
-
---
-
-总结：仓库 jiangtx/gitlink-cli（项目 ID: 1547588，默认分支: master，权限: Manager）
-当前 open_devops 字段为 false，CI/CD 服务未开启。其他仓库信息：2 位贡献者、
-9 个 PR、0 个 Issue，Fork 自 Gitlink/gitlink-cli。
-```
-
-### 验证结论
-
-✅ skill v1.1.0 修复验证通过：
- Agent 正确使用了 `repo +info` 的 `open_devops` 字段判断 CI 状态
- Agent 在 CI 未激活时正确终止，没有执行后续无效步骤
- Agent 没有尝试调用不存在的 `ci +authorize` 或 `ci +activate`
- Agent 正确建议通过 Web 界面激活
- 报告结构完整，包含了仓库基本信息
--- a/skills/gitlink-ci-health/SKILL.md
+++ b/skills/gitlink-ci-health/SKILL.md
@ -1,189 +0,0 @@
---
-name: gitlink-ci-health
-version: 1.1.0
-description: "CI 健康巡检：检查仓库 CI/CD 授权状态、构建历史和成功率，生成 CI 健康度报告。当用户需要检查 CI 状态、分析构建成功率、排查 CI 故障时触发。"
-metadata:
-  requires:
-    bins: ["gitlink-cli"]
-  cliHelp: "gitlink-cli ci --help"
---
-
-# gitlink-ci-health（CI 健康巡检）
-
-**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
-**CRITICAL — 本 Skill 为只读操作。CI 激活/关闭需通过 GitLink Web 界面操作，CLI 不提供对应命令。**
-**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
-
-> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
-
---
-
-## 功能概述
-
-面向维护者的 CI/CD 健康度巡检工具：
-
-1. **授权检查** — 确认仓库 CI 是否已激活
-2. **构建历史** — 获取近期构建列表
-3. **成功率统计** — 计算构建成功率和平均耗时
-4. **故障分析** — 识别频繁失败的构建及其原因
-5. **健康报告** — 生成 CI 健康度评分和改进建议
-
---
-
-## 工作流：CI 健康巡检
-
-### Step 1：检查 CI 授权状态
-
-**方法 1（推荐）**：通过 `repo +info` 查看 `open_devops` 字段：
-
-```bash
-gitlink-cli repo +info --owner <owner> --repo <repo> --format json
-```
-
- `"open_devops": true` → CI 已激活
- `"open_devops": false` → CI 未激活
-
-**方法 2**：直接调用 `ci +builds`，CI 未激活时返回：
-
-```json
-{"status": -1, "message": "接口数据异常"}
-```
-
-> ⚠️ `ci +authorize` 命令在当前 CLI 版本（v0.1.18）中**不存在**。可用 CI 命令仅：`+builds`、`+logs`、`+restart`、`+stop`。
-
-若 CI 未激活，报告中说明"CI 未启用"，建议通过 GitLink Web 界面（仓库设置 → DevOps）开启，随后不再继续后续步骤。
-
-### Step 2：获取构建历史
-
-```bash
-gitlink-cli ci +builds --owner <owner> --repo <repo> --format json
-```
-
-提取每次构建的：
- `status` — 构建状态（success/failed/running/pending）
- `created_at` / `finished_at` — 时间信息
- `duration` — 耗时（如有）
- `branch` — 触发分支
-
-如构建数量 >30，取最近 30 次分析。
-
-### Step 3：构建日志（失败构建）
-
-对状态为 failed 的构建获取日志：
-
-```bash
-gitlink-cli ci +logs --owner <owner> --repo <repo> --build <build_id> --format json
-```
-
-> ⚠️ **控制调用量**：仅对最近 5 次失败构建获取日志，避免过多 API 调用。日志可能过大，提取关键错误行（最后 20 行）。
-
-### Step 4：统计分析
-
-#### 4.1 成功率计算
-
-| 指标 | 计算方式 |
-|------|----------|
-| 整体成功率 | 成功构建数 / 总构建数 × 100% |
-| 近 10 次成功率 | 最近 10 次中成功占比 |
-| 平均修复时间 | 从失败到下次成功的平均间隔 |
-
-#### 4.2 健康度评分（满分 20）
-
-| 维度 | 权重 | 评分标准 |
-|------|------|----------|
-| CI 激活 | 4 | 已激活=4，未激活=0 |
-| 构建成功率 | 5 | ≥90%=5，≥80%=4，≥70%=3，≥50%=2，<50%=1 |
-| 近期稳定性 | 5 | 近10次全部成功=5，8-9次=4，6-7次=3，4-5次=2，<4次=1 |
-| 构建频率 | 3 | 每天有构建=3，2-3天=2，每周=1，更少=0 |
-| 修复速度 | 3 | 失败后1次内修复=3，2-3次=2，>3次=1 |
-
-### Step 5：生成 CI 健康报告
-
---
-
-## 输出模板
-
-```markdown
-# 🔧 CI 健康巡检报告：{{仓库名}}
-
-> 巡检时间：{{当前时间}}
-> 仓库：{{full_name}}
-> CI 状态：{{ci_status_display}}
-
---
-
-## 一、健康度总览
-
-| 指标 | 数值 | 评分 |
-|------|------|------|
-| CI 激活状态 | {{activated_status}} | {{activate_score}}/4 |
-| 整体成功率 | {{success_rate}}%（{{success_count}}/{{total_count}}） | {{success_score}}/5 |
-| 近期稳定性 | 近 10 次 {{recent_success}} 次成功 | {{stability_score}}/5 |
-| 构建频率 | {{build_frequency_desc}} | {{frequency_score}}/3 |
-| 修复速度 | {{repair_speed_desc}} | {{repair_score}}/3 |
-| **总分** | | **{{total_score}}/20** |
-
-## 二、构建趋势
-
-```
-最近 20 次构建：
-✅✅❌✅✅✅❌✅✅✅✅✅❌✅✅✅✅✅✅
-（✅=成功  ❌=失败）
-```
-
-| 时间段 | 总构建 | 成功 | 失败 | 成功率 |
-|--------|--------|------|------|--------|
-| 最近 7 天 | {{w1_total}} | {{w1_success}} | {{w1_fail}} | {{w1_rate}}% |
-| 7-14 天 | {{w2_total}} | {{w2_success}} | {{w2_fail}} | {{w2_rate}}% |
-| 14-30 天 | {{w3_total}} | {{w3_success}} | {{w3_fail}} | {{w3_rate}}% |
-
-## 三、故障分析
-
-> 如无失败构建，输出：**🎉 分析期内无失败构建，CI 运行健康。**
-
-| 构建 ID | 分支 | 失败时间 | 错误摘要 |
-|---------|------|----------|----------|
-| {{id}} | {{branch}} | {{time}} | {{error_summary}} |
-
-### 故障模式分类
-
-| 故障类型 | 次数 | 占比 |
-|----------|------|------|
-| 编译错误 | {{compile_count}} | {{compile_pct}}% |
-| 测试失败 | {{test_fail_count}} | {{test_fail_pct}}% |
-| 超时 | {{timeout_count}} | {{timeout_pct}}% |
-| 环境问题 | {{env_count}} | {{env_pct}}% |
-| 其他 | {{other_count}} | {{other_pct}}% |
-
-## 四、改进建议
-
-<!-- 根据分析结果，从以下列表中选择匹配的建议输出 -->
-
- **立即激活 CI**（当 CI 未激活时）：前往 GitLink Web 界面 → 仓库设置 → DevOps 开启 CI/CD 服务（CLI 暂不支持 `ci +activate`）
- **提升成功率**（当 success_rate < 80% 时）：优先修复高频失败原因
- **增加构建频率**（当构建频率评分 < 2 时）：建议每次 push 触发 CI
- **缩短修复时间**（当修复速度评分 < 2 时）：建立 CI 失败告警
-```
-
---
-
-## 异常场景处理
-
-| 场景 | 处理方式 |
-|------|----------|
-| CI 未激活 | 报告 CI 状态为"未激活"，建议通过 Web 界面开启，不再继续后续步骤 |
-| 无构建记录 | 标注"仓库暂无 CI 构建记录" |
-| `ci +logs` 返回空 | 标注"日志不可用" |
-| 构建总数 < 5 | 样本量不足，标注"数据有限，统计不具代表性" |
-
---
-
-## 注意事项
-
- ✅ **所有命令使用 `--format json`**，确保可解析
- ✅ **CI 激活/关闭需通过 GitLink Web 界面**，CLI 不提供 `+activate`/`+deactivate` 命令
- ✅ **Owner/repo 优先从 `git remote` 自动解析**
- ⚠️ **`ci +logs` 输出可能很大**，仅提取关键错误行
- ⚠️ **构建历史无分页参数**，实际返回条数取决于 API
- ⚠️ **CI 数据仅反映 GitLink 平台活动**，不包括第三方 CI 服务
- ⚠️ **`repo +info` 的 `open_devops` 字段**是判断 CI 是否激活的最可靠方式
--- a/skills/gitlink-cli-contract-guard/SKILL.md
+++ b/skills/gitlink-cli-contract-guard/SKILL.md
@ -0,0 +1,183 @@
+---
+name: gitlink-cli-contract-guard
+description: "CLI 契约守卫：审查 GitLink CLI 改动是否破坏既有命令契约，重点检查 flags 与默认值、命令层级与帮助文本、`--format json` 输出结构、错误提示与编码质量、README/示例命令和实际行为是否漂移。用于用户需要判断某个 PR 或本地改动会不会破坏旧用法、引入不兼容输出、造成帮助文档失真，或在合并前补做兼容性审查时。"
+---
+
+# gitlink-cli-contract-guard
+
+**CRITICAL - 如果需要拉取 GitLink 上的 PR 元数据、diff 或评论，先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。**
+**CRITICAL - 这个 skill 默认只读分析，不直接修改远端评论、标签或分配关系。**
+**CRITICAL - 这个 skill 只关注 CLI 对用户承诺的行为契约，不负责判断 PR 是否应当合并。**
+
+这个 skill 的目标很窄，也很硬：**找出会把现有 CLI 用户用法搞坏的改动。**
+
+它重点审查五类契约面：
+
+1. **参数契约**：flag 名称、短别名、默认值、必填规则、参数语义。
+2. **帮助契约**：命令层级、`--help` 内容、国际化文案、示例命令。
+3. **输出契约**：`--format json` 结构、字段名、字段类型、包裹 envelope。
+4. **错误契约**：错误提示、退出语义、编码质量、用户可理解性。
+5. **文档契约**：README、示例、帮助文本与真实行为是否一致。
+
+## 不覆盖的内容
+
+下面这些不属于这个 skill 的职责：
+
+- PR 是否值得合并：交给 `gitlink-pr-assessor`
+- 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，再结合本地代码理解。
+
+如果是本地改动，优先看：
+
+```bash
+git diff --name-only
+git diff --stat
+```
+
+如果是 GitLink PR，优先看：
+
+```bash
+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`](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：要求验证证据
+
+只指出风险还不够，要同时判断“有没有证据证明它没坏”。
+
+常用验证方式：
+
+```bash
+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`](references/severity-rubric.md) 把问题分成：
+
+- `blocking`：明确破坏旧用法或输出契约
+- `high`：高概率影响真实用户或自动化脚本
+- `medium`：存在漂移或边界缺口，但不一定立即破坏
+- `low`：文案、可读性或一致性问题
+
+### Step 6：输出契约审查结论
+
+推荐输出结构：
+
+```markdown
+# CLI 契约审查报告
+
+## 高风险问题
+- `--header` 模板渲染后未再次校验，可能生成非法 header。
+- README.zh-CN 新增示例出现中文乱码，会污染用户可见文档。
+
+## 契约面影响
+- 参数契约：`--header` 新增并改变请求构造行为。
+- 输出契约：无破坏性字段变更证据。
+- 错误契约：中文错误提示存在编码退化风险。
+
+## 缺失验证
+- 缺少对 `Accept` 头覆盖行为的边界测试。
+- 缺少对渲染后非法 header 的测试。
+
+## 结论
+- 需要修改后再合并。
+```
+
+## 典型触发语句
+
+- “帮我看这个改动会不会破坏现有 CLI 用法。”
+- “检查这个 PR 有没有 flag / help / JSON 输出兼容性问题。”
+- “看看这个命令改动会不会影响脚本调用方。”
+- “帮我做一轮 CLI 行为契约审查。”
--- a/skills/gitlink-cli-contract-guard/agents/openai.yaml
+++ b/skills/gitlink-cli-contract-guard/agents/openai.yaml
@ -0,0 +1,4 @@
+interface:
+  display_name: "CLI 契约守卫"
+  short_description: "检查 flags、help、JSON 输出和错误提示是否发生破坏性变化。"
+  default_prompt: "Use $gitlink-cli-contract-guard 审查这个 GitLink CLI 改动是否破坏了既有命令契约，重点检查参数、帮助、JSON 输出、错误提示和兼容性。"
--- a/skills/gitlink-cli-contract-guard/assets/codex-skill-directory.png
+++ b/skills/gitlink-cli-contract-guard/assets/codex-skill-directory.png
--- a/skills/gitlink-cli-contract-guard/assets/codex-validation-output.png
+++ b/skills/gitlink-cli-contract-guard/assets/codex-validation-output.png
--- a/skills/gitlink-cli-contract-guard/examples/codex-validation-2026-06-26.md
+++ b/skills/gitlink-cli-contract-guard/examples/codex-validation-2026-06-26.md
@ -0,0 +1,42 @@
+# Codex 验证记录（2026-06-26）
+
+Agent 平台：Codex
+
+验证目标：确认 `gitlink-cli-contract-guard` 能对 GitLink CLI 改动执行兼容性审查，尤其关注 flags、帮助文案、JSON 输出契约、错误提示与中文编码质量。
+
+验证结果如下：
+
+# PR #290 CLI 契约审查报告
+
+审查对象：GitLink/gitlink-cli PR #290
+
+结论：**未发现会破坏现有 CLI 契约的问题，可从契约角度通过。**
+
+#290 的改动范围只在 `skills/gitlink-contributor-insight` 下：
+
+- 删除 `SKILL.md` frontmatter 中的 `version: 1.1.0`
+- 新增 4 张 Codex 验证截图
+- 新增 `examples/codex-validation-2026-06-25.md`
+
+### 契约面检查
+
+| 契约面 | 结论 |
+|---|---|
+| flags / 默认值 | 未触碰 `cmd/`、`shortcuts/`，未新增/删除/改名任何 CLI flag |
+| help 文案 | 未触碰命令注册、help、i18n、README，不影响 `--help` |
+| JSON 输出结构 | 未触碰输出层、shortcut 返回结构或 envelope |
+| 错误提示 | 未触碰 client、auth、错误处理或校验逻辑 |
+| 中文编码 | 新增 Markdown 中文可读，未发现常见乱码模式；`git diff --check` 通过 |
+
+### 验证记录
+
+- `git diff --name-status origin/master...HEAD`：确认仅 skill 文档和图片资产变更。
+- `git diff --check origin/master...HEAD`：通过。
+- `rg "<22>|锛|鈥|Ã|Â|绠|璇|涓|馃"`：未命中新增/修改文本。
+- `go test ./cmd/... ./shortcuts/...`：通过。
+
+### 低风险备注
+
+删除 `version: 1.1.0` 不影响 CLI 用户契约；它只可能影响 skill 元数据展示或外部 skill schema 约定。若仓库要求所有 skill 保留 `version` 字段，建议由 skill 校验流程单独确认，但这不是 CLI flags/help/JSON/error 契约破坏。
+
+最终判断：**无 blocking/high/medium 契约问题。**
--- a/skills/gitlink-cli-contract-guard/examples/encoding-and-doc-drift.md
+++ b/skills/gitlink-cli-contract-guard/examples/encoding-and-doc-drift.md
@ -0,0 +1,19 @@
+# 示例：编码与文档漂移审查
+
+用户请求：
+
+```text
+Use $gitlink-cli-contract-guard 审查这个 PR 的中文提示、README 示例和错误文案是否有编码或行为漂移问题。
+```
+
+期望动作：
+
+1. 检查用户可见中文文本是否出现 mojibake。
+2. 对照 README 和帮助示例，确认命令是否仍可用。
+3. 检查错误提示是否仍然可操作、可理解。
+4. 输出具体问题点和建议补测项。
+
+输出要点：
+
+- 中文乱码默认按高风险处理。
+- README / 帮助 / 代码三者不一致时，要明确指出谁是事实来源、谁需要修正。
--- a/skills/gitlink-cli-contract-guard/examples/flag-compat-review.md
+++ b/skills/gitlink-cli-contract-guard/examples/flag-compat-review.md
@ -0,0 +1,19 @@
+# 示例：参数兼容性审查
+
+用户请求：
+
+```text
+Use $gitlink-cli-contract-guard 检查这个 PR 有没有破坏现有 flag、默认值或帮助文案。
+```
+
+期望动作：
+
+1. 定位变更是否触及 `cmd/`、`shortcuts/`、`README`。
+2. 检查 flag 的 `Name`、`Short`、`Default`、`Required` 是否变化。
+3. 检查 `--help` 和示例命令是否同步。
+4. 输出按严重性排序的问题和缺失验证。
+
+输出要点：
+
+- 明确指出是“新增能力”还是“破坏旧用法”。
+- 如果默认值改变，要说明对已有用户的影响。
--- a/skills/gitlink-cli-contract-guard/examples/json-output-review.md
+++ b/skills/gitlink-cli-contract-guard/examples/json-output-review.md
@ -0,0 +1,19 @@
+# 示例：JSON 输出契约审查
+
+用户请求：
+
+```text
+Use $gitlink-cli-contract-guard 看一下这个改动会不会破坏 `--format json` 输出，尤其是脚本依赖的字段。
+```
+
+期望动作：
+
+1. 定位输出相关代码和测试。
+2. 判断字段名、字段类型、envelope 是否变化。
+3. 核对是否有测试覆盖机器可读输出。
+4. 给出“安全 / 需补验证 / 高风险”的结论。
+
+输出要点：
+
+- 区分“新增字段”与“破坏字段”。
+- 如果只是怀疑，不要下过度确定的结论，要把缺失证据写清楚。
--- a/skills/gitlink-cli-contract-guard/references/contract-surfaces.md
+++ b/skills/gitlink-cli-contract-guard/references/contract-surfaces.md
@ -0,0 +1,115 @@
+# CLI 契约面映射
+
+这个 skill 的第一步不是直接评论代码，而是先判断改动触到了哪类契约面。
+
+## 1. 参数契约
+
+典型文件：
+
+- `cmd/root.go`
+- `cmd/*/*.go`
+- `shortcuts/*/*.go`
+- `shortcuts/common/runner.go`
+- `shortcuts/common/types.go`
+
+重点观察：
+
+- `Name`
+- `Short`
+- `Default`
+- `Required`
+- `Bool`
+- `Usage`
+
+高风险信号：
+
+- 旧 flag 被重命名或移除
+- 必填/可选规则变化
+- 默认值变化但没有说明
+- 示例命令仍使用旧 flag
+
+## 2. 帮助契约
+
+典型文件：
+
+- `cmd/root.go`
+- `cmd/root_test.go`
+- `shortcuts/register.go`
+- `internal/i18n/**`
+- `README.md`
+- `README.zh-CN.md`
+
+重点观察：
+
+- 命令分组和层级
+- `Use` / `Short` / `Long`
+- 中英文帮助文案
+- `--help` 输出快照或断言
+
+高风险信号：
+
+- 命令已改，但帮助仍描述旧行为
+- 中文或英文帮助不一致
+- i18n key 缺失导致回退或错误
+
+## 3. 输出契约
+
+典型文件：
+
+- `shortcuts/common/types.go`
+- `internal/output/**`
+- `shortcuts/*/*_test.go`
+- `cmd/*/*_test.go`
+
+重点观察：
+
+- `--format json`
+- envelope 结构
+- 字段名和字段类型
+- 是否仍适合脚本消费
+
+高风险信号：
+
+- 字段重命名
+- 类型从字符串改为对象/数组
+- 原有必备字段消失
+- 错误输出结构不再稳定
+
+## 4. 错误契约
+
+典型文件：
+
+- `internal/client/**`
+- `internal/auth/**`
+- `cmd/**`
+- `internal/i18n/**`
+
+重点观察：
+
+- `suggestFix`
+- 缺参错误
+- 校验错误
+- header/path/query 渲染后行为
+- 中文提示编码
+
+高风险信号：
+
+- 用户可见中文乱码
+- 错误变得不可操作
+- 渲染后非法 header/path 没有被拦截
+
+## 5. 文档契约
+
+典型文件：
+
+- `README.md`
+- `README.zh-CN.md`
+- `examples/**`
+- 命令帮助中的示例
+
+高风险信号：
+
+- 文档示例已不能运行
+- 示例使用了不存在的参数
+- 文档与实际默认值不一致
+- 文档新增内容出现乱码
--- a/skills/gitlink-cli-contract-guard/references/severity-rubric.md
+++ b/skills/gitlink-cli-contract-guard/references/severity-rubric.md
@ -0,0 +1,40 @@
+# CLI 契约问题分级
+
+把发现的问题按下面的标准分级，避免把所有问题都说成“高风险”。
+
+## blocking
+
+满足任一项即可：
+
+- 删除、重命名或破坏已有 flag / 命令路径
+- 破坏 `--format json` 的既有字段名或字段类型
+- 引入明确的中文乱码或编码损坏
+- 文档和帮助明显宣称支持，但实际命令已无法工作
+- 会导致自动化脚本或既有调用方高概率失败
+
+## high
+
+- 新增功能影响了现有行为，但证据还不完整
+- header/path/query 渲染存在高风险边界问题
+- 错误提示退化，用户很难定位或修复问题
+- 默认值变化会显著改变用户结果，但没有迁移说明
+- 测试没有覆盖关键兼容面
+
+## medium
+
+- 文档、帮助、示例与实际实现有轻度漂移
+- 中英文文案不同步
+- 新增参数的边界行为未覆盖
+- 输出是“扩展式变化”，但缺少明确验证
+
+## low
+
+- 文案可读性问题
+- 示例可进一步收敛
+- 一致性或可维护性问题
+
+## 结论规则
+
+- 只要存在 `blocking`，结论就是“需要修改后再合并”。
+- 没有 `blocking` 但有多个 `high`，结论仍然偏向“需要补验证或修复”。
+- 只有 `medium/low` 时，可以给出“可合并，但建议跟进”的结论。