From 1c8ed58b55eae9f4981a4f81eba5a170480a308d Mon Sep 17 00:00:00 2001 From: Mengz <2567587994@qq.com> Date: Mon, 20 Jul 2026 17:33:53 +0800 Subject: [PATCH] =?UTF-8?q?feat(skills):=20=E5=BC=BA=E5=8C=96=E7=BB=B4?= =?UTF-8?q?=E6=8A=A4=E8=AF=81=E6=8D=AE=E4=B8=8E=E9=AB=98=E6=95=88=E6=91=98?= =?UTF-8?q?=E8=A6=81=E5=8D=8F=E8=AE=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/gitlink-cli-contract-guard/SKILL.md | 3 +- skills/gitlink-maintainer-radar/SKILL.md | 3 +- skills/gitlink-pr-assessor/SKILL.md | 4 ++ skills/gitlink-pr-integrator/SKILL.md | 3 +- skills/gitlink-pr-topology/SKILL.md | 3 +- skills/gitlink-shared/SKILL.md | 2 + .../examples/maintenance-evidence-v2.md | 51 +++++++++++++++++++ .../maintenance-evidence-workflow.md | 10 +++- .../references/maintenance-report-contract.md | 6 +++ 9 files changed, 80 insertions(+), 5 deletions(-) create mode 100644 skills/gitlink-shared/examples/maintenance-evidence-v2.md diff --git a/skills/gitlink-cli-contract-guard/SKILL.md b/skills/gitlink-cli-contract-guard/SKILL.md index bc3401d..f19f57f 100644 --- a/skills/gitlink-cli-contract-guard/SKILL.md +++ b/skills/gitlink-cli-contract-guard/SKILL.md @@ -1,6 +1,5 @@ --- name: gitlink-cli-contract-guard -version: 1.0.0 description: "CLI 契约守卫：审查 GitLink CLI 改动是否破坏既有命令契约，重点检查 flags 与默认值、命令层级与帮助文本、`--format json` 输出结构、错误提示与编码质量、README/示例命令和实际行为是否漂移。用于用户需要判断某个 PR 或本地改动会不会破坏旧用法、引入不兼容输出、造成帮助文档失真，或在合并前补做兼容性审查时。" metadata: requires: @@ -20,6 +19,8 @@ gitlink-cli workflow +review-queue --from queue.json --previous queue-previous.j 本 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)。** diff --git a/skills/gitlink-maintainer-radar/SKILL.md b/skills/gitlink-maintainer-radar/SKILL.md index 02b8876..631ad19 100644 --- a/skills/gitlink-maintainer-radar/SKILL.md +++ b/skills/gitlink-maintainer-radar/SKILL.md @@ -1,6 +1,5 @@ --- name: gitlink-maintainer-radar -version: 1.0.0 description: "维护者雷达：面向 GitLink 仓库维护者，联合扫描 open Pull Request、open Issue、消息提醒、review 分配和等待时长，识别响应超时、review 负载失衡、负责人长期停滞等协作瓶颈，生成按优先级排序的处置清单、催办建议和责任调整建议。用于用户需要值班巡检待办、判断哪些事项被晾着了、找出 reviewer 瓶颈、发现有负责人但无进展的条目，或生成维护者今日工作面板时。" metadata: requires: @@ -19,6 +18,8 @@ gitlink-cli workflow +review-context --owner --repo --number 这个 Skill 是“评估引擎”，不是常驻监听进程。要实现社区里 open PR 自动审查，必须由 webhook、定时任务或 Agent runner 负责触发它。 ### Windows 编码前置 diff --git a/skills/gitlink-pr-integrator/SKILL.md b/skills/gitlink-pr-integrator/SKILL.md index 0cc597b..1b236ed 100644 --- a/skills/gitlink-pr-integrator/SKILL.md +++ b/skills/gitlink-pr-integrator/SKILL.md @@ -1,6 +1,5 @@ --- name: gitlink-pr-integrator -version: 1.0.0 description: 评估 GitLink Pull Request 是否已经具备集成到主线的条件，输出合并态验证、与其他 open PR 的冲突风险、集成影响面、发布与回移建议以及合并后动作清单。用于维护者需要决定某个 PR 是否可以进入 merge queue、为一批待合并 PR 排顺序、在合并前验证 rebase 或 merge 后是否仍能构建测试通过，或为自动化队列生成集成就绪报告时。 metadata: requires: @@ -18,6 +17,8 @@ gitlink-cli workflow +review-context --owner --repo --number --repo --number queue-current.json +``` + +如果要比较上一轮，把 `queue-current.json` 作为下一轮的 `--previous` 输入。队列首屏只保留新增、优先级变化、风险变化和超 SLA 项，稳定项保留数量。 + +## 2. 获取单条 PR 证据 + +```powershell +gitlink-cli workflow +review-context ` + --owner Gitlink --repo gitlink-cli --number 123 ` + --include-commits=true --include-ci=true ` + --format json > pr-123-context.json +``` + +审查 `ci_summary` 时遵循以下判定： + +- `match_mode=sha`：优先级最高，只统计当前 PR head SHA 对应的构建。 +- `match_mode=branch`：仅在没有可用 SHA 匹配时接受，并在报告中降低置信度。 +- `matched=0` 或 `match_mode=none/unavailable`：CI 为 `not_run`，不能写成通过。 +- `unmatched`：只表示本次列表中未关联的构建，不是失败数。 + +## 3. 五个 Skill 的最短交接 + +| Skill | 首先读取 | 产生的动作 | +|---|---|---| +| `gitlink-pr-assessor` | `files`、`reviews`、`ci_summary`、`notes` | `CR-` 代码、测试和安全发现 | +| `gitlink-pr-integrator` | `ci_summary`、本地验证、`changes` | `IN-` 集成门禁 | +| `gitlink-pr-topology` | `changes`、候选 PR 的文件和分支 | `TP-` 依赖与重叠关系 | +| `gitlink-maintainer-radar` | `waiting_hours`、`stale`、`waiting_on`、reviewer 数量 | `MR-` 今日待办 | +| `gitlink-cli-contract-guard` | `--help`、可选 JSON 字段、错误输出 | `CG-` 契约问题 | + +组合报告只在首屏展示最多 5 个动作，原始响应、完整 diff、未匹配构建和未执行项放入附录。任何 Skill 单独运行时，都必须把未纳入的其他维度标为“未检查”。 + +## 4. 最小自检 + +```powershell +$json = Get-Content -Raw -Encoding utf8 .\pr-123-context.json | ConvertFrom-Json +if ($null -eq $json.sections) { throw "missing sections" } +if ($json.ci_summary.match_mode -in @("none", "unavailable")) { Write-Output "CI not_run/partial" } +``` diff --git a/skills/gitlink-shared/references/maintenance-evidence-workflow.md b/skills/gitlink-shared/references/maintenance-evidence-workflow.md index 3d329c7..a72f28c 100644 --- a/skills/gitlink-shared/references/maintenance-evidence-workflow.md +++ b/skills/gitlink-shared/references/maintenance-evidence-workflow.md @@ -15,6 +15,10 @@ gitlink-cli workflow +review-context \ 证据包包含仓库信息、PR 详情、变更文件、Reviews、提交记录和 CI 构建结果。所有集合都有上限；某个探针失败时检查 `notes` 和 `sections`，不能把缺失数据写成“通过”。已有调用不传新增开关时保持原行为。 +### CI 关联规则 + +当结果包含 `ci_summary` 时，优先使用 `match_mode=sha` 的提交匹配；只有 PR 没有可用 head SHA 或 SHA 无匹配时，才接受 `match_mode=branch`。`passed`、`failed`、`pending` 和 `unknown` 只统计已匹配构建，`unmatched` 不能被当作失败或通过。`match_mode=none`、`unavailable` 或 `sections` 缺少 `ci_builds` 时，相关结论必须标为 `not_run`/`partial`。 + ## 队列变化快照 前置 PR #427 合并后，先保存 JSON 基线，再在下一轮比较： @@ -30,6 +34,10 @@ gitlink-cli workflow +review-queue \ `changes` 只表达队列事实：`new`、`resolved`、`priority_changed`、`risk_changed` 和 `unchanged`。它不替代代码审查、集成门禁或维护者判断。无 PR 编号的本地输入只能按规范化标题匹配，报告必须降低置信度。 +### 等待与责任字段 + +使用 `--as-of ` 固定报告时点，使用 `--stale-after-hours ` 设置仓库 SLA。队列项的 `age_hours`、`waiting_hours`、`stale`、`review_state`、`reviewers`、`reviewer_count` 和 `waiting_on` 用于生成维护动作；`waiting_on` 只有在 review 状态明确时才归属 `author`、`reviewer` 或 `maintainer`，未知状态必须保留为空。 + ## 五个 Skill 的消费边界 | Skill | 使用单 PR 证据 | 使用队列变化 | 最终只负责什么 | @@ -46,4 +54,4 @@ gitlink-cli workflow +review-queue \ 2. 单独运行某个 Skill 时只读取它需要的字段，并把其他维度标记为未纳入本次检查。 3. 组合运行时允许共享事实和安全信号，但发现编号必须保留各自前缀：`CR-`、`IN-`、`TP-`、`MR-`、`CG-`。 4. 同一事实可以被多个 Skill 引用，但只能由负责该维度的 Skill 生成最终动作；例如 CI 失败可以被代码审查引用，却只能由集成 Skill 决定是否形成合并阻断。 -5. 任何探针失败或快照缺失都输出 `not_run`/`partial`，不能用默认值填充成功结论。 +5. 任何探针失败、CI 未匹配或快照缺失都输出 `not_run`/`partial`，不能用默认值填充成功结论。 diff --git a/skills/gitlink-shared/references/maintenance-report-contract.md b/skills/gitlink-shared/references/maintenance-report-contract.md index 2f97a13..f626ba8 100644 --- a/skills/gitlink-shared/references/maintenance-report-contract.md +++ b/skills/gitlink-shared/references/maintenance-report-contract.md @@ -10,6 +10,12 @@ 2. **今日动作**：最多 5 项，按优先级排序；每项必须包含对象、责任方、下一动作和证据引用。 3. **证据附录**：完整发现、命令输出摘要、文件/行号、时间戳和未验证项。 +## 增量信号的首屏规则 + +- CI 首屏显示“匹配数/总数、匹配方式、失败数、未匹配数”；没有 SHA 或分支匹配时显示“未关联”，不能把仓库其他构建的失败计入当前 PR。 +- 队列首屏显示“新增、已解决、优先级变化、风险变化、超 SLA 数量”；稳定项只保留计数。 +- 每项动作最多引用一个主证据和一个责任方，更多原始字段放到 JSON 或附录，避免维护者重复阅读。 + 不要在首屏输出原始 API 响应、完整 diff、所有通知或所有 PR 两两比较结果。需要保留时放入附录或 JSON。 ## 统一决策字段