diff --git a/skills/gitlink-ci-health/EXAMPLES.md b/skills/gitlink-ci-health/EXAMPLES.md deleted file mode 100644 index af237f8..0000000 --- a/skills/gitlink-ci-health/EXAMPLES.md +++ /dev/null @@ -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 界面激活 -- 报告结构完整，包含了仓库基本信息 diff --git a/skills/gitlink-ci-health/SKILL.md b/skills/gitlink-ci-health/SKILL.md deleted file mode 100644 index 8721c8b..0000000 --- a/skills/gitlink-ci-health/SKILL.md +++ /dev/null @@ -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 --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 --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 --repo --build --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 是否激活的最可靠方式 diff --git a/skills/gitlink-cli-contract-guard/SKILL.md b/skills/gitlink-cli-contract-guard/SKILL.md new file mode 100644 index 0000000..8675483 --- /dev/null +++ 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 --repo -i --format json +gitlink-cli pr +version-diff --owner --repo -i --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//*_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 行为契约审查。” diff --git a/skills/gitlink-cli-contract-guard/agents/openai.yaml b/skills/gitlink-cli-contract-guard/agents/openai.yaml new file mode 100644 index 0000000..89544b8 --- /dev/null +++ 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 输出、错误提示和兼容性。" diff --git a/skills/gitlink-cli-contract-guard/assets/codex-skill-directory.png b/skills/gitlink-cli-contract-guard/assets/codex-skill-directory.png new file mode 100644 index 0000000..17f97e0 Binary files /dev/null and b/skills/gitlink-cli-contract-guard/assets/codex-skill-directory.png differ diff --git a/skills/gitlink-cli-contract-guard/assets/codex-validation-output.png b/skills/gitlink-cli-contract-guard/assets/codex-validation-output.png new file mode 100644 index 0000000..896b32b Binary files /dev/null and b/skills/gitlink-cli-contract-guard/assets/codex-validation-output.png differ diff --git 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 new file mode 100644 index 0000000..42f7ca2 --- /dev/null +++ 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 "�|锛|鈥|Ã|Â|绠|璇|涓|馃"`：未命中新增/修改文本。 +- `go test ./cmd/... ./shortcuts/...`：通过。 + +### 低风险备注 + +删除 `version: 1.1.0` 不影响 CLI 用户契约；它只可能影响 skill 元数据展示或外部 skill schema 约定。若仓库要求所有 skill 保留 `version` 字段，建议由 skill 校验流程单独确认，但这不是 CLI flags/help/JSON/error 契约破坏。 + +最终判断：**无 blocking/high/medium 契约问题。** diff --git a/skills/gitlink-cli-contract-guard/examples/encoding-and-doc-drift.md b/skills/gitlink-cli-contract-guard/examples/encoding-and-doc-drift.md new file mode 100644 index 0000000..526a932 --- /dev/null +++ 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 / 帮助 / 代码三者不一致时，要明确指出谁是事实来源、谁需要修正。 diff --git a/skills/gitlink-cli-contract-guard/examples/flag-compat-review.md b/skills/gitlink-cli-contract-guard/examples/flag-compat-review.md new file mode 100644 index 0000000..c51af99 --- /dev/null +++ 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. 输出按严重性排序的问题和缺失验证。 + +输出要点： + +- 明确指出是“新增能力”还是“破坏旧用法”。 +- 如果默认值改变，要说明对已有用户的影响。 diff --git a/skills/gitlink-cli-contract-guard/examples/json-output-review.md b/skills/gitlink-cli-contract-guard/examples/json-output-review.md new file mode 100644 index 0000000..541773c --- /dev/null +++ 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. 给出“安全 / 需补验证 / 高风险”的结论。 + +输出要点： + +- 区分“新增字段”与“破坏字段”。 +- 如果只是怀疑，不要下过度确定的结论，要把缺失证据写清楚。 diff --git a/skills/gitlink-cli-contract-guard/references/contract-surfaces.md b/skills/gitlink-cli-contract-guard/references/contract-surfaces.md new file mode 100644 index 0000000..33f2c18 --- /dev/null +++ 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/**` +- 命令帮助中的示例 + +高风险信号： + +- 文档示例已不能运行 +- 示例使用了不存在的参数 +- 文档与实际默认值不一致 +- 文档新增内容出现乱码 diff --git a/skills/gitlink-cli-contract-guard/references/severity-rubric.md b/skills/gitlink-cli-contract-guard/references/severity-rubric.md new file mode 100644 index 0000000..55d0278 --- /dev/null +++ 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` 时，可以给出“可合并，但建议跟进”的结论。