forked from Gitlink/gitlink-cli
feat(skills): 深化维护者审查闭环与自动化边界
This commit is contained in:
parent
1c8ed58b55
commit
cb17616f96
|
|
@ -34,6 +34,16 @@ gitlink-cli workflow +review-queue --from queue.json --previous queue-previous.j
|
|||
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、示例、帮助文本与真实行为是否一致。
|
||||
|
||||
|
|
@ -41,6 +51,8 @@ gitlink-cli workflow +review-queue --from queue.json --previous queue-previous.j
|
|||
|
||||
默认遵循 [`../gitlink-shared/references/maintenance-report-contract.md`](../gitlink-shared/references/maintenance-report-contract.md)，先给维护者一个兼容性决策，再列证据。首屏最多展示 5 个会阻断合并或影响脚本用户的动作，问题编号使用 `CG-xxx`。
|
||||
|
||||
运行键、证据台账、刷新和自动回写边界遵循 [`../gitlink-shared/references/maintenance-run-protocol.md`](../gitlink-shared/references/maintenance-run-protocol.md)。
|
||||
|
||||
除五类既有契约面外，增加安全契约检查：
|
||||
|
||||
- token、cookie、Authorization 和调试输出必须脱敏，不能进入 Markdown 或 JSON 报告。
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
interface:
|
||||
display_name: "CLI 契约守卫"
|
||||
short_description: "检查 flags、help、JSON 输出和错误提示是否发生破坏性变化。"
|
||||
default_prompt: "Use $gitlink-cli-contract-guard 审查这个 GitLink CLI 改动是否破坏了既有命令契约，重点检查参数、帮助、JSON 输出、错误提示和兼容性。"
|
||||
default_prompt: "Use $gitlink-cli-contract-guard 审查这个 GitLink CLI 改动是否破坏既有命令契约，先建立旧用法基线，再检查 flags、help、JSON、错误、UTF-8、NO_COLOR 和安全边界，输出最多五项带复现命令的 CG 发现。"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
name: gitlink-code-review
|
||||
version: 1.0.0
|
||||
description: "智能代码审查：获取 PR 变更、分析代码质量、自动生成 Review 评论与摘要报告。当用户需要审查 Pull Request、检查代码质量或生成审查报告时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
|
|
@ -18,11 +17,14 @@ gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <num
|
|||
|
||||
本 Skill 只消费代码层证据；CI 失败可以作为审查依据，但不直接替代 `gitlink-pr-integrator` 的合并门禁。若 `sections` 缺少 `commits` 或 `ci_builds`，或 `notes` 标记探针失败，相关结论必须标记为 `partial`。
|
||||
|
||||
当结果包含 `ci_summary` 时，只统计与当前 PR head SHA 匹配的构建；`match_mode=branch` 只能作为回退，`none/unavailable` 必须标记 CI 证据不足。报告还要记录运行键、当前 head、证据台账和限制项，避免把旧 commit 或其他分支的结果写进本次审查。
|
||||
|
||||
# gitlink-code-review（智能代码审查）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有写入/删除操作前，务必先确认用户意图。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
|
||||
**CRITICAL — 默认只生成本地审查报告或评论草稿；只有用户明确要求且满足共享运行协议的安全条件时，才允许发布普通评论。不得自动 APPROVE、MERGE、CLOSE 或修改权限。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
|
||||
|
|
@ -30,11 +32,24 @@ gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <num
|
|||
|
||||
本 Skill 默认遵循 [`../gitlink-shared/references/maintenance-report-contract.md`](../gitlink-shared/references/maintenance-report-contract.md)，先输出维护者可直接执行的摘要，不把完整分析堆在首屏：
|
||||
|
||||
运行键、证据台账、刷新和自动回写边界遵循 [`../gitlink-shared/references/maintenance-run-protocol.md`](../gitlink-shared/references/maintenance-run-protocol.md)。
|
||||
|
||||
1. 先给 `decision`、最高严重性、阻断数、高风险数、安全门禁和验证状态。
|
||||
2. 只列最多 5 项按优先级排序的动作，每项标明 `CR-xxx`、责任方、文件/行号或命令证据。
|
||||
3. 完整逐文件审查、正向反馈和原始证据放到“证据附录”；无关的风格建议合并，不刷屏。
|
||||
4. Markdown 使用“颜色 + 粗体 + 纯文本回退”；JSON 只输出稳定字段，绝不混入 ANSI、HTML 或 emoji。
|
||||
|
||||
## 证据驱动的审查闭环
|
||||
|
||||
按“范围确认、声明提取、行为 Diff、数据流安全、测试证据、Review 反馈、兼容性边界、摘要决策”顺序执行。每条 `CR-` 发现必须满足：
|
||||
|
||||
1. 有精确文件/行号、命令输出或 Review 引用；无法定位时只能标为 `candidate`。
|
||||
2. 说明实际影响、触发条件和最小修复方向，不能只贴规则名称。
|
||||
3. 标出 `observed`、`derived` 或 `unknown`；推导结论不能单独升级为 blocking。
|
||||
4. 与 `CG-` 契约问题、`IN-` 集成门禁或 `MR-` 维护动作通过 `related_ids` 关联，不重复催办。
|
||||
|
||||
审查完成后将发现按“必须修复、需要验证、可选建议、正向证据”分组，首屏只保留最多 5 个会改变维护决策的动作。测试作者声称“通过”不等于行为已经验证，必须有实际命令或可复现观察。
|
||||
|
||||
报告首屏固定使用以下结构：
|
||||
|
||||
```markdown
|
||||
|
|
@ -169,6 +184,8 @@ gitlink-cli pr +review --body '{
|
|||
|
||||
> **注意：** `event` 参数支持 `COMMENT`（普通评论）和 `APPROVE`（批准）。对于需要修改的问题，使用 `COMMENT`。
|
||||
|
||||
默认不要执行上述写入命令。先输出草稿并等待明确授权；即使获得授权，也只发布带稳定运行键、证据引用和修复建议的 `COMMENT`，不发布 `APPROVE`。
|
||||
|
||||
#### Step 5：生成审查摘要
|
||||
|
||||
审查完成后，输出 Markdown 摘要供用户查阅：
|
||||
|
|
@ -198,7 +215,11 @@ gitlink-cli pr +review --body '{
|
|||
|
||||
---
|
||||
|
||||
### 工作流 2：仓库代码健康度扫描
|
||||
### 非默认职责：仓库健康度与 Issue 分拣
|
||||
|
||||
仓库整体健康度、Issue 分类分配和维护者队列治理不属于本 Skill 的默认职责，分别交给专门的仓库/维护 Skill。下面的历史命令仅在用户明确点名该兼容流程时执行；普通 PR 代码审查不得自动扩展成仓库扫描或 Issue 写操作。
|
||||
|
||||
### 历史兼容：仓库代码健康度扫描
|
||||
|
||||
**场景**：对仓库整体代码质量进行评估，不依赖 PR。
|
||||
|
||||
|
|
@ -263,7 +284,7 @@ gitlink-cli repo +contributors
|
|||
|
||||
---
|
||||
|
||||
### 工作流 3：批量 Issue Triage + 自动分配
|
||||
### 历史兼容：批量 Issue Triage + 自动分配
|
||||
|
||||
**场景**：对新 Issue 进行自动分类、标签分配和责任人推荐。
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
interface:
|
||||
display_name: "PR 代码审查"
|
||||
short_description: "基于 Diff、测试和安全证据生成精确、可执行的代码 Review。"
|
||||
default_prompt: "Use $gitlink-code-review 审查这个 GitLink PR 的代码质量、测试充分性和代码级安全风险，优先引用精确证据，输出最多五项动作；默认只生成报告或评论草稿，不自动批准或合并。"
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
# 证据优先的代码审查示例
|
||||
|
||||
这个示例用于演示一次可复查的 PR 深审，不自动发布 Review。
|
||||
|
||||
## 采集
|
||||
|
||||
```powershell
|
||||
$context = gitlink-cli workflow +review-context `
|
||||
--owner Gitlink --repo gitlink-cli --number 123 `
|
||||
--include-commits=true --include-ci=true --format json
|
||||
$context | Set-Content .\pr-123-context.json -Encoding utf8
|
||||
```
|
||||
|
||||
先记录 `run_id`、PR head SHA、`sections`、`notes` 和 `ci_summary`。如果 CI 没有按 SHA 或分支关联，或 `notes` 表示探针失败，报告中的 CI 门禁只能是 `partial`/`not_run`。
|
||||
|
||||
## 审查顺序
|
||||
|
||||
1. 从标题、正文和测试说明提取作者声明，不把标题当作事实。
|
||||
2. 逐文件检查行为变化、错误处理、输入边界、资源释放、权限和敏感数据流。
|
||||
3. 对每条发现记录 `CR-` 编号、直接证据、触发条件、影响和最小修复建议。
|
||||
4. 区分 `observed`、`derived` 和 `unknown`；无法精确定位的问题只能标为 `candidate`。
|
||||
5. 只在当前 head 的构建、测试和安全证据完整时给出较高置信度。
|
||||
|
||||
## 首屏输出
|
||||
|
||||
```markdown
|
||||
# PR #123 代码审查摘要
|
||||
**结论：** 需要补充验证 **[action_required]**
|
||||
**证据：** 当前 head `abcdef1` | CI SHA 匹配 `1/1` | 安全 `partial`
|
||||
|
||||
## 先做这 2 件事
|
||||
1. **[CR-001][high] 补充** 失败路径测试（责任：作者；证据：`E-CR-001`）。
|
||||
2. **[CR-002][medium] 复看** 错误输出中的敏感字段脱敏（责任：作者；证据：`diff:internal/client/client.go:42`）。
|
||||
```
|
||||
|
||||
完整 Diff、命令输出、未匹配构建和正向反馈放入附录。默认只生成这份报告或评论草稿；只有用户明确授权并满足共享运行协议，才允许发布普通 `COMMENT`，不得自动 `APPROVE` 或 `MERGE`。
|
||||
|
|
@ -38,11 +38,27 @@ gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <num
|
|||
|
||||
默认遵循 [`../gitlink-shared/references/maintenance-report-contract.md`](../gitlink-shared/references/maintenance-report-contract.md)，首屏只给维护者今天可以执行的队列：
|
||||
|
||||
运行键、证据台账、刷新和自动回写边界遵循 [`../gitlink-shared/references/maintenance-run-protocol.md`](../gitlink-shared/references/maintenance-run-protocol.md)。
|
||||
|
||||
- 先显示 HOT 数量、最早超时对象、安全事项、reviewer 瓶颈和本轮扫描时间。
|
||||
- 最多输出 5 项动作，并明确等待方：`author`、`reviewer`、`maintainer` 或 `platform`。
|
||||
- 同一 PR 的 SLA、review 负载和责任停滞信号合并为一项，避免重复催办。
|
||||
- 普通消息、点赞和已明确归属且未超时的条目只计数，不展开正文。
|
||||
|
||||
## 待办生成与误催防护
|
||||
|
||||
每个待办先计算 `urgency`、`impact`、`confidence` 三项，再合并成一个 `MR-` 动作：
|
||||
|
||||
- `urgency`：首响超时、review 等待时长、超 SLA 程度和最近一次活动时间。
|
||||
- `impact`：安全热点、阻塞关系、PR 风险和受影响范围；只引用其他 Skill 的事实，不重新宣称漏洞。
|
||||
- `confidence`：是否有明确时间、reviewer/assignee、当前 head 和证据来源；未知责任或缺失快照必须降低置信度。
|
||||
|
||||
`waiting_on=author` 才生成作者跟进，`waiting_on=reviewer` 才生成 reviewer 跟进，`waiting_on=maintainer` 才生成维护者收口动作，空值只报告“责任未知”。同一 PR 的多个超时信号合并为一项；每日重复运行若运行键和证据未变化，只更新计数，不重复评论。
|
||||
|
||||
自动回写仅允许发布低风险、可撤销的事实提醒，且必须经过运行协议的幂等和证据条件；不得自动关闭 Issue/PR、强制分配 reviewer 或将超时升级为合并阻断。
|
||||
|
||||
报告首屏必须带 `as_of`、扫描范围、队列快照来源和数据完整性；每项 `MR-` 动作引用一个主证据和一个责任方，无法确认责任方时明确写“责任未知”。
|
||||
|
||||
读取 [`../gitlink-shared/references/security-review-matrix.md`](../gitlink-shared/references/security-review-matrix.md)。对涉及凭据、权限、命令、路径、webhook、依赖和敏感数据的 PR 提升为安全 HOT；但仅凭标题或标签不能认定存在漏洞，必须标记证据状态。
|
||||
|
||||
首屏格式：
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
interface:
|
||||
display_name: "维护者雷达"
|
||||
short_description: "识别响应超时、review 失衡和责任停滞，生成维护者处置面板。"
|
||||
default_prompt: "Use $gitlink-maintainer-radar 扫描这个 GitLink 仓库当前的响应 SLA、review 负载和责任停滞情况，输出按优先级排序的处置清单和建议动作。"
|
||||
default_prompt: "Use $gitlink-maintainer-radar 扫描这个 GitLink 仓库当前的响应 SLA、review 负载和责任停滞情况，固定 as_of、合并同一 PR 的重复信号，输出最多五项带责任方和证据的处置动作，不误催未知责任人。"
|
||||
|
|
|
|||
|
|
@ -319,6 +319,25 @@ open PR：<n>
|
|||
|
||||
如果要把它真正放进开源社区，不要要求维护者手工逐条调用，而是用外层系统定时或事件触发它。
|
||||
|
||||
### 证据优先的自动审查策略
|
||||
|
||||
自动运行先建立运行键 `<producer>:<repo>:<pr>:<head_sha>:<mode>`，再按“筛选、采集、静态评估、执行验证、生成摘要”五阶段执行。只有当前 head SHA 尚未生成过报告时才发布新的建议性 Review；作者提交新 commit、Review 状态变化或 CI 状态变化时重新评估。报告必须包含 `run`、`evidence` 和 `limitations`，维护者可以据此判断结论是否仍然新鲜。
|
||||
|
||||
自动审查只允许输出事实、证据和补充建议。下列任一情况出现时只生成草稿，不自动发表评论：CI 未与当前 head SHA/分支关联、代码检出 SHA 不一致、存在 blocking/高风险安全候选、关键测试未执行、或 PR 状态已不是 open。自动模式不得自动 approve、merge、close、分配权限或处理真实凭据。
|
||||
|
||||
### 结论矩阵
|
||||
|
||||
不要用单一分数替代证据判断：
|
||||
|
||||
| 条件 | 结论方向 |
|
||||
|------|----------|
|
||||
| 价值明确、声明验证通过、回归和安全证据完整 | 建议进入人工合并前确认 |
|
||||
| 价值明确但声明、回归或 CI 证据部分缺失 | `action_required`，列出最小补证动作 |
|
||||
| 发现 blocking 安全/兼容问题或核心行为失败 | `blocked`，只保留可复现证据 |
|
||||
| 数据不完整、PR 已变更或本地验证过期 | `observe`，等待刷新，不猜测通过 |
|
||||
|
||||
队列模式首屏最多展示 5 条动作，其余用 `deferred_count` 计数；每条动作只保留一个主责任方和一个主证据，完整扫描结果进入附录。
|
||||
|
||||
推荐的触发方式有两类：
|
||||
|
||||
### 方式 1：PR 事件触发
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
interface:
|
||||
display_name: "PR 价值与可行性评估"
|
||||
short_description: "验证 open PR 的价值、实现、测试和安全性，输出可追溯的维护者结论。"
|
||||
default_prompt: "Use $gitlink-pr-assessor 评估这个 GitLink PR 或扫描未形成维护者结论的 open PR，优先验证作者声明、当前 head 的构建测试和安全风险，输出最多五项可执行动作，不要在证据不足时自动评论或合并。"
|
||||
|
|
@ -31,6 +31,8 @@ CI 门禁必须读取 `ci_summary`：`match_mode=sha` 优先，`branch` 只能
|
|||
|
||||
执行命令前，按需读取 [`references/api_reference.md`](./references/api_reference.md)。其中包含 GitLink CLI 命令、Windows 调用方式、独立 worktree 验证方法和报告字段约定。
|
||||
|
||||
运行键、证据台账、刷新和自动回写边界遵循 [`../gitlink-shared/references/maintenance-run-protocol.md`](../gitlink-shared/references/maintenance-run-protocol.md)。
|
||||
|
||||
## 效率版集成门禁
|
||||
|
||||
默认遵循 [`../gitlink-shared/references/maintenance-report-contract.md`](../gitlink-shared/references/maintenance-report-contract.md)，先回答“现在能否进入 merge queue”，再展开证据。首屏只保留：
|
||||
|
|
@ -56,6 +58,16 @@ CI 门禁必须读取 `ci_summary`：`match_mode=sha` 优先，`branch` 只能
|
|||
|
||||
只有六项门禁全部有充分证据且无 `blocking/high` 未解决项，才可使用 `merge`。大型 PR 先做文件/目录重叠和安全热点筛选，只有高风险候选才进入独立 worktree 的完整合并验证，避免批量扫描浪费维护者时间。
|
||||
|
||||
## 集成验证的刷新与停机规则
|
||||
|
||||
集成报告的幂等键必须包含 PR head SHA。验证开始后若远端 head SHA 变化，立即停止剩余门禁并标记 `stale`，不要把旧 commit 的构建结果套到新代码上。每项门禁都登记实际检出 SHA、命令、退出码和时间；缺少这些信息只能是 `not_run` 或 `partial`。
|
||||
|
||||
门禁决策按以下顺序收敛：先确认 base/head 和 merge-base，再确认冲突与文件影响面，然后执行仓库规定的构建/测试，最后合并 `CR-`、`CG-`、`TP-` 的未解决发现。`ci_summary.match_mode=none/unavailable` 时 CI 门禁不通过；`unmatched` 构建不能计入失败，但必须进入限制说明。安全、构建、测试或契约任一关键门禁为 `failed`，结论不得为 `merge`。
|
||||
|
||||
集成器可以生成 merge queue 顺序和合并后动作，但不得自动 merge。只有维护者明确授权且所有门禁仍针对同一个 head SHA 时，才可以生成可执行的合并命令草稿。
|
||||
|
||||
输出必须携带统一协议的 `run`、`evidence`、`limitations` 和 `next_run`；维护者首先看六项门禁和最多五项动作，完整命令、merge-base 和测试日志放入附录。
|
||||
|
||||
## 职责边界与组合协同
|
||||
|
||||
独立运行时，本 Skill 只判断一个 PR 是否具备进入合并队列的条件；它不重新做完整代码审查、不判断 PR 之间的替代关系，也不按 SLA 排维护者任务。组合运行时读取 `CR-xxx`、`CG-xxx` 和 `TP-xxx` 结果，使用 `IN-xxx` 记录集成阻断和门禁，不改写专项发现。安全专项未运行时，安全门禁必须保持 `not_run`，不能因构建通过而推断安全通过。
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
interface:
|
||||
display_name: "PR 集成检查"
|
||||
short_description: "评估 PR 是否能安全并入主线，分析冲突、发布影响和合并后动作。"
|
||||
default_prompt: "Use $gitlink-pr-integrator 评估这个 GitLink PR 的集成就绪度，执行合并态验证、冲突风险分析、发布影响判断和合并后动作梳理，不要回写远端。"
|
||||
default_prompt: "Use $gitlink-pr-integrator 评估这个 GitLink PR 的集成就绪度，按当前 head SHA 执行合并态、构建、测试、契约、安全和冲突门禁，输出最多五项动作和合并后清单，不要回写、批准或合并远端。"
|
||||
|
|
|
|||
|
|
@ -42,11 +42,31 @@ gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <num
|
|||
|
||||
默认遵循 [`../gitlink-shared/references/maintenance-report-contract.md`](../gitlink-shared/references/maintenance-report-contract.md)，输出“关系摘要”而不是完整的两两比较表：
|
||||
|
||||
运行键、证据台账、刷新和自动回写边界遵循 [`../gitlink-shared/references/maintenance-run-protocol.md`](../gitlink-shared/references/maintenance-run-protocol.md)。
|
||||
|
||||
1. 先给 open PR 数、关系簇数量、冲突热点、安全热点和建议处理顺序。
|
||||
2. 只展示会改变维护决策的最多 5 条关系；相同关系簇合并成一项，完整边列表放附录或 JSON。
|
||||
3. 每条关系使用 `TP-xxx` 稳定编号，写明证据、置信度和建议动作；没有足够证据时标为 `candidate`，不能断言重复或 supersedes。
|
||||
4. 对同时修改认证、权限、命令执行、路径处理、依赖或输出敏感数据的 PR，增加 `security_hotspot` 关系，要求先完成安全审查再排序。
|
||||
|
||||
## 关系判定的证据等级
|
||||
|
||||
关系图谱先建立候选边，再判定关系，不允许仅凭标题相似就断言重复：
|
||||
|
||||
| 关系 | 最低证据 | 输出动作 |
|
||||
|------|----------|----------|
|
||||
| `depends_on` / `stacked_on` | 分支、提交、API 字段或文件引用形成明确先后 | 先处理被依赖 PR |
|
||||
| `overlaps` / `duplicate_candidate` | 同一命令、文件、Issue 或行为目标，且 Diff 有交集 | 合并评审上下文或择一 |
|
||||
| `supersedes` | 目标相同且一条覆盖另一条的功能、测试和文档 | 保留更完整者，另一条进入人工确认 |
|
||||
| `conflicts` | 同一契约/代码区域存在互斥修改 | 先解决冲突再排序 |
|
||||
| `complements` | 目标不同但共享稳定接口或可以串联 | 建议打包评审，不判重复 |
|
||||
|
||||
置信度分为 `high`、`medium`、`candidate`。`candidate` 只能作为待核对关系，不能直接建议关闭 PR；关系动作必须引用文件、分支、字段或快照证据。队列的 `stale`、`waiting_on` 只影响维护排序，不构成功能关系。
|
||||
|
||||
关系图谱的首屏最多列 5 个关系簇，并同时给出“保留、先后处理、并行评审、人工确认”四类动作之一；完整边列表和两两评分放 JSON 附录。
|
||||
|
||||
每条关系都要登记 `TP-` 编号、置信度、关系证据和建议动作；队列快照缺失或 PR head 已变化时，将关系标为 `stale`/`candidate`，不使用旧图谱直接建议关闭或替代。
|
||||
|
||||
首屏示例：
|
||||
|
||||
```markdown
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
interface:
|
||||
display_name: "PR 关系图谱"
|
||||
short_description: "分析 open PR 之间的依赖、重叠、替代和建议处理顺序。"
|
||||
default_prompt: "Use $gitlink-pr-topology 扫描这个 GitLink 仓库的 open PR 队列，识别依赖链、功能重叠、潜在替代关系、冲突热点和建议处理顺序。"
|
||||
default_prompt: "Use $gitlink-pr-topology 扫描这个 GitLink 仓库的 open PR 队列，基于文件、分支、接口和快照证据识别依赖、重叠、替代、冲突和互补关系，标注置信度并输出最多五个关系簇，不关闭 PR。"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
---
|
||||
name: gitlink-shared
|
||||
version: 1.0.0
|
||||
description: "gitlink-cli 共享基础：认证登录、全局参数、错误处理、安全规则。当用户首次使用 gitlink-cli、遇到认证错误、权限不足时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
|
|
@ -12,6 +11,8 @@ metadata:
|
|||
|
||||
可直接照着 [`examples/maintenance-evidence-v2.md`](examples/maintenance-evidence-v2.md) 演示一次固定时间点的队列扫描、单 PR CI 证据关联和五个 Skill 的最短交接路径。
|
||||
|
||||
自动运行、幂等键、证据台账、刷新策略和自动 review 边界见 [`references/maintenance-run-protocol.md`](references/maintenance-run-protocol.md)。任何 Skill 需要自动回写时，必须先满足该协议的安全条件，否则只输出草稿。
|
||||
|
||||
# gitlink-cli 共享规则
|
||||
|
||||
维护者类 Skill 的报告协议见 [`references/maintenance-report-contract.md`](references/maintenance-report-contract.md)，安全检查见 [`references/security-review-matrix.md`](references/security-review-matrix.md)，五个维护 Skill 的核心职责、允许重叠范围和交接见 [`references/skill-scope-and-handoff.md`](references/skill-scope-and-handoff.md)。生成报告时先给执行摘要，再提供可追溯的证据附录；JSON 不得混入展示层样式。
|
||||
|
|
|
|||
|
|
@ -2,6 +2,14 @@
|
|||
|
||||
这个示例展示一次扫描如何被五个 Skill 复用，而不是让每个 Skill 重复请求接口或输出整份原始数据。
|
||||
|
||||
每次执行先建立运行键，例如：
|
||||
|
||||
```text
|
||||
gitlink-pr-assessor:Gitlink/gitlink-cli:123:abcdef1:executive
|
||||
```
|
||||
|
||||
同一运行键只生成一次报告；只有 PR head、Review、CI 或维护者策略变化时才重新评估。
|
||||
|
||||
## 1. 固定证据时间点
|
||||
|
||||
```powershell
|
||||
|
|
@ -42,6 +50,10 @@ gitlink-cli workflow +review-context `
|
|||
|
||||
组合报告只在首屏展示最多 5 个动作，原始响应、完整 diff、未匹配构建和未执行项放入附录。任何 Skill 单独运行时，都必须把未纳入的其他维度标为“未检查”。
|
||||
|
||||
## 5. 自动 Review 的安全边界
|
||||
|
||||
只有报告证据完整、PR 仍为 open、当前运行键没有已发布报告、没有 blocking/高风险安全发现，并且评论只包含事实和建议时，才可以由外层 runner 自动发布建议性 Review。以下情况只生成草稿：CI 未关联当前 head、工作树 SHA 不一致、关键测试未执行、数据过期或责任方不明确。五个 Skill 都不能自动合并、关闭、拒绝或修改权限。
|
||||
|
||||
## 4. 最小自检
|
||||
|
||||
```powershell
|
||||
|
|
|
|||
|
|
@ -7,6 +7,24 @@
|
|||
"security_gate": "passed",
|
||||
"verification": "partial",
|
||||
"scope": {"owner": "Gitlink", "repo": "gitlink-cli", "items": 1},
|
||||
"run": {
|
||||
"run_id": "gitlink-pr-assessor:Gitlink/gitlink-cli:42:abcdef1:executive",
|
||||
"trigger": "schedule",
|
||||
"started_at": "2026-07-20T12:00:00Z",
|
||||
"as_of": "2026-07-20T12:01:10Z",
|
||||
"mode": "executive"
|
||||
},
|
||||
"evidence": [
|
||||
{
|
||||
"id": "E-CR-001",
|
||||
"kind": "test_output",
|
||||
"source": "local_worktree",
|
||||
"status": "complete",
|
||||
"observed_at": "2026-07-20T12:00:40Z",
|
||||
"ref": "go test ./shortcuts/example",
|
||||
"scope": "head:abcdef1234567"
|
||||
}
|
||||
],
|
||||
"top_actions": [
|
||||
{
|
||||
"id": "CR-001",
|
||||
|
|
@ -16,5 +34,6 @@
|
|||
}
|
||||
],
|
||||
"findings": [],
|
||||
"limitations": ["平台 CI 结果未提供"]
|
||||
"limitations": ["平台 CI 结果未提供"],
|
||||
"next_run": {"reason": "等待作者提交新 commit", "after_minutes": 60}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -15,8 +15,42 @@ foreach ($name in $required) {
|
|||
}
|
||||
|
||||
if ($report.mode -notin @('executive', 'standard', 'full')) { throw "invalid report mode" }
|
||||
if ($report.decision -notin @('merge', 'action_required', 'reorder', 'observe', 'blocked')) { throw "invalid report decision" }
|
||||
if ($report.top_actions.Count -gt 5) { throw "executive report has more than five top actions" }
|
||||
if ($raw -match "`e\[|<span|</span>") { throw "JSON contains presentation markers" }
|
||||
if ($raw.Contains([char]0xfffd)) { throw "JSON contains UTF-8 replacement character" }
|
||||
if ($raw.Contains([char]0xfffd) -or $raw.Contains([char]0)) { throw "JSON contains encoding control characters" }
|
||||
if ($raw -match '(?i)(authorization|bearer)\s+[A-Za-z0-9._-]{20,}') { throw "JSON contains a credential-like value" }
|
||||
|
||||
foreach ($action in @($report.top_actions)) {
|
||||
foreach ($name in @('id', 'owner', 'action', 'evidence')) {
|
||||
if ($null -eq $action.PSObject.Properties[$name]) { throw "top action missing field: $name" }
|
||||
}
|
||||
if ($action.evidence.Count -eq 0) { throw "top action has no evidence: $($action.id)" }
|
||||
}
|
||||
|
||||
if ($null -ne $report.PSObject.Properties['run']) {
|
||||
foreach ($name in @('run_id', 'trigger', 'as_of')) {
|
||||
if ($null -eq $report.run.PSObject.Properties[$name]) { throw "run missing field: $name" }
|
||||
}
|
||||
if ($report.run.trigger -notin @('pull_request_opened', 'pull_request_synchronized', 'review_submitted', 'schedule', 'manual')) { throw "invalid run trigger" }
|
||||
try { [DateTimeOffset]::Parse($report.run.as_of) | Out-Null } catch { throw "invalid run as_of" }
|
||||
}
|
||||
|
||||
if ($null -ne $report.PSObject.Properties['evidence']) {
|
||||
$evidenceIds = @{}
|
||||
foreach ($item in @($report.evidence)) {
|
||||
foreach ($name in @('id', 'kind', 'status', 'ref')) {
|
||||
if ($null -eq $item.PSObject.Properties[$name]) { throw "evidence missing field: $name" }
|
||||
}
|
||||
if ($item.status -notin @('complete', 'partial', 'failed', 'not_run', 'stale')) { throw "invalid evidence status: $($item.id)" }
|
||||
if ($evidenceIds.ContainsKey($item.id)) { throw "duplicate evidence id: $($item.id)" }
|
||||
$evidenceIds[$item.id] = $true
|
||||
}
|
||||
}
|
||||
|
||||
if ($null -ne $report.PSObject.Properties['next_run']) {
|
||||
if ($null -eq $report.next_run.PSObject.Properties['reason'] -or $null -eq $report.next_run.PSObject.Properties['after_minutes']) { throw "next_run requires reason and after_minutes" }
|
||||
if ([int]$report.next_run.after_minutes -lt 0) { throw "next_run.after_minutes must be non-negative" }
|
||||
}
|
||||
|
||||
Write-Output "maintenance report contract passed: $Path"
|
||||
|
|
|
|||
|
|
@ -48,6 +48,8 @@ gitlink-cli workflow +review-queue \
|
|||
| `gitlink-maintainer-radar` | Review 和 PR 元数据 | 重点消费新增、风险变化和已解决项 | SLA、Reviewer 负载、责任停滞和今日待办 |
|
||||
| `gitlink-cli-contract-guard` | 文件、帮助、JSON 和错误证据 | 只在涉及 workflow flags/JSON 时消费 | CLI 参数、帮助、输出、错误和编码契约 |
|
||||
|
||||
补充：`gitlink-pr-assessor` 是五个核心 Skill 之前的可选初筛层，负责价值、声明可行性和执行验证，不计入核心五个 Skill 的最终职责矩阵。
|
||||
|
||||
## 组合运行规则
|
||||
|
||||
1. 先获取一次证据包和队列快照，后续 Skill 通过 `sections`、`notes` 和 `changes` 判断证据完整性。
|
||||
|
|
|
|||
|
|
@ -32,6 +32,8 @@ Markdown 和 JSON 的结论必须一致。推荐使用以下字段：
|
|||
"security_gate": "fail",
|
||||
"verification": "partial",
|
||||
"scope": {"owner": "Gitlink", "repo": "gitlink-cli", "items": 12},
|
||||
"run": {"run_id": "producer:repo:scope:head:executive", "trigger": "schedule", "as_of": "2026-07-20T12:01:10Z"},
|
||||
"evidence": [{"id": "E-001", "kind": "test_output", "status": "complete", "ref": "go test ./..."}],
|
||||
"top_actions": [
|
||||
{"id": "CR-001", "owner": "maintainer", "action": "先处理安全阻断", "evidence": ["diff:shortcuts/x/y.go:42"]}
|
||||
],
|
||||
|
|
@ -40,6 +42,8 @@ Markdown 和 JSON 的结论必须一致。推荐使用以下字段：
|
|||
}
|
||||
```
|
||||
|
||||
`run`、`evidence` 和 `next_run` 是可选扩展字段；存在时必须遵循 [`maintenance-run-protocol.md`](maintenance-run-protocol.md)。它们让报告可以判断“这是哪一次扫描、证据针对哪个 commit、下一次何时复查”，而不是只保留一段无法去重的文字。
|
||||
|
||||
允许的 `decision`：`merge`、`action_required`、`reorder`、`observe`、`blocked`。没有足够证据时必须使用 `observe` 或 `blocked`，不能猜测为通过。
|
||||
|
||||
## 严重性和稳定编号
|
||||
|
|
|
|||
|
|
@ -0,0 +1,71 @@
|
|||
# 维护 Skill 运行协议
|
||||
|
||||
本协议把五个 Skill 从“一次性生成文字”约束为可重复、可追溯、可安全自动运行的维护流水线。它不改变五个 Skill 的职责，只规定共同的运行输入、证据、刷新和自动化边界。
|
||||
|
||||
## 运行标识与幂等
|
||||
|
||||
每次运行生成稳定键：
|
||||
|
||||
```text
|
||||
<producer>:<owner>/<repo>:<pr-number-or-queue>:<head-sha-or-snapshot>:<mode>
|
||||
```
|
||||
|
||||
相同稳定键不得重复发布报告或重复评论。PR 在新 commit、Review 状态变化、CI 结果变化或维护者明确要求复查时，才创建新的运行键。队列扫描使用快照时间和队列内容摘要作为版本，不使用当前时间单独去重。
|
||||
|
||||
## 最小运行上下文
|
||||
|
||||
```json
|
||||
{
|
||||
"run": {
|
||||
"run_id": "gitlink-pr-assessor:Gitlink/gitlink-cli:123:abcdef1:executive",
|
||||
"trigger": "pull_request_synchronized",
|
||||
"started_at": "2026-07-20T12:00:00Z",
|
||||
"as_of": "2026-07-20T12:01:10Z",
|
||||
"mode": "executive"
|
||||
},
|
||||
"scope": {"owner": "Gitlink", "repo": "gitlink-cli", "number": 123},
|
||||
"evidence": [],
|
||||
"decision": "action_required",
|
||||
"next_run": {"reason": "等待作者提交新 commit", "after_minutes": 60}
|
||||
}
|
||||
```
|
||||
|
||||
`trigger` 至少区分 `pull_request_opened`、`pull_request_synchronized`、`review_submitted`、`schedule`、`manual`。时间统一使用 RFC3339 UTC；没有可靠时间时标记 `unknown`，不能用本地当前时间伪造事件时间。
|
||||
|
||||
## 证据台账
|
||||
|
||||
每个会改变决策的事实都要在 `evidence` 中登记：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "E-CR-001",
|
||||
"kind": "test_output",
|
||||
"source": "local_worktree",
|
||||
"status": "complete",
|
||||
"observed_at": "2026-07-20T12:00:40Z",
|
||||
"ref": "go test ./shortcuts/workflow",
|
||||
"scope": "head:abcdef1234567"
|
||||
}
|
||||
```
|
||||
|
||||
允许的 `kind`：`pr_api`、`diff`、`review`、`ci`、`local_checkout`、`test_output`、`cli_help`、`queue_snapshot`、`human_policy`。允许的 `status`：`complete`、`partial`、`failed`、`not_run`、`stale`。`findings[].evidence` 必须引用台账 ID 或明确的文件/命令证据；没有证据的发现只能是 `candidate`，不能是 blocking。
|
||||
|
||||
事实分为 `observed`、`derived` 和 `unknown`：文件/命令/API 直接返回的是 `observed`，规则计算得到的是 `derived`，没有可靠来源的是 `unknown`。`derived` 可以改变排序和建议，但不能单独产生 blocking；`unknown` 必须进入 `limitations`。
|
||||
|
||||
## 刷新策略
|
||||
|
||||
- PR 元数据、Diff、Review：同一运行内保持同一快照，避免标题和 Diff 来自不同时间点。
|
||||
- CI：优先匹配当前 PR head SHA；只按分支匹配时降低置信度；没有匹配构建时为 `not_run`。
|
||||
- 本地验证：记录实际检出的 commit SHA，必须与 PR head SHA 一致；不一致只能输出 `stale`。
|
||||
- 队列：先保存快照，再比较 `new`、`resolved`、优先级、风险和 SLA 变化；稳定项只计数。
|
||||
|
||||
## 自动动作边界
|
||||
|
||||
只有同时满足以下条件，才允许自动发布“建议性 review”评论：
|
||||
|
||||
1. 当前运行键没有已发布报告。
|
||||
2. PR 仍为 open，证据状态为 `complete`，且报告明确标出扫描范围和时间。
|
||||
3. 没有 `blocking` 或未确认的高风险安全发现。
|
||||
4. 评论只包含事实、证据和补充建议，不包含自动合并、关闭、拒绝或强制分配动作。
|
||||
|
||||
任一条件不满足时，只生成本地报告或评论草稿。任何 Skill 都不得自动合并、关闭 PR、修改权限、处理真实凭据或把未知状态写成通过。
|
||||
|
|
@ -12,6 +12,8 @@
|
|||
| `gitlink-pr-integrator` | 合并态、rebase、构建、测试、契约、安全门禁和发布影响 | 不重新进行完整代码审查或维护者值班排序 | 单 PR 证据、其他 Skill 结论、主线和 CI 状态 | `IN-xxx` 集成门禁、决策和合并后动作 |
|
||||
| `gitlink-maintainer-radar` | 首响 SLA、reviewer 负载、责任停滞、等待方和队列变化 | 不判断代码漏洞、CLI 兼容性或 PR 功能优劣 | 队列快照、review 状态、评论时间、分配关系和安全优先级 | `MR-xxx` 维护动作、责任调整和催办建议 |
|
||||
|
||||
`gitlink-pr-assessor` 是五个核心 Skill 之外的前置评估器：它判断 PR 的贡献价值、作者声明可行性和执行验证结果，适合批量筛选未形成维护者结论的 open PR；它不能替代 `gitlink-code-review` 的逐行代码审查，也不能替代 `gitlink-pr-integrator` 的合并门禁。组合运行时可把 assessor 的证据和限制交给核心五个 Skill，但不得把“价值明确”改写成“代码已通过”。
|
||||
|
||||
## 允许的功能重叠
|
||||
|
||||
重叠本身不是问题，关键是不能让一个 Skill 的完整功能覆盖另一个 Skill。以下能力可以被多个 Skill 使用：
|
||||
|
|
@ -62,6 +64,18 @@
|
|||
|
||||
一个专项 Skill 失败不会让整条流水线伪造通过。将该专项的状态设为 `not_run`，并让集成器按门禁规则降级结论。
|
||||
|
||||
## 独立与组合的运行契约
|
||||
|
||||
独立运行时，Skill 只获取自己的最小输入并生成自己的编号前缀；例如单独运行 `gitlink-maintainer-radar` 不得为了判断代码质量而拉取完整 Diff。组合运行时，所有专项共享同一个 `run.run_id`、`as_of` 和 PR head/snapshot，交接只传递事实、证据 ID、状态和 `related_ids`，不传递未经证实的自然语言结论。
|
||||
|
||||
组合流程的降级规则如下：
|
||||
|
||||
1. 证据采集失败：所有下游将对应维度标为 `not_run`，不使用历史数据补齐。
|
||||
2. 代码审查或契约守卫出现 blocking：集成器结论至少为 `blocked`，维护雷达只提升待办优先级。
|
||||
3. 拓扑关系为 `candidate`：只影响评审顺序，不关闭或替代任何 PR。
|
||||
4. 维护者 SLA 超时：只产生 `MR-` 动作，不改变代码、契约或合并门禁。
|
||||
5. 任一 Skill 输出与当前 run/head 不一致：标记 `stale`，要求重新运行。
|
||||
|
||||
## 交接字段
|
||||
|
||||
各 Skill 的 JSON 结果应包含以下字段；`findings` 可使用各自的编号前缀：
|
||||
|
|
|
|||
Loading…
Reference in New Issue