feat(skills): 丰富五个维护 Skill 的协同审查能力 #428
|
|
@ -114,6 +114,18 @@ skills/
|
|||
└── SKILL.md # 工作流模板（Issue 分类、PR Review、Release Notes）
|
||||
```
|
||||
|
||||
维护者效率 Skill：
|
||||
|
||||
```text
|
||||
├── gitlink-code-review/ # 代码质量、安全和回归审查
|
||||
├── gitlink-pr-integrator/ # 合并门禁、冲突和集成验证
|
||||
├── gitlink-pr-topology/ # open PR 依赖、重叠和处理顺序
|
||||
├── gitlink-maintainer-radar/ # SLA、review 负载和责任停滞
|
||||
└── gitlink-cli-contract-guard/ # CLI 参数、帮助、JSON 和安全契约
|
||||
```
|
||||
|
||||
这五个 Skill 默认输出“执行摘要 + 最多五项动作 + 证据附录”，并共享 [`gitlink-shared/references/maintenance-report-contract.md`](gitlink-shared/references/maintenance-report-contract.md) 和安全审查矩阵，适合维护者快速批阅 open PR 队列。
|
||||
|
||||
---
|
||||
|
||||
## 📖 所有 Skills 概览
|
||||
|
|
@ -142,6 +154,16 @@ skills/
|
|||
| **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、Release Notes |
|
||||
| **gitlink-docs-assistant** | 文档智能维护 ★ | `wiki +list/+create/+update/+view` |
|
||||
|
||||
### 维护者效率 Skills
|
||||
|
||||
| Skill | 说明 | 适用决策 |
|
||||
|-------|------|----------|
|
||||
| **gitlink-code-review** | 代码质量、安全边界、回归和测试证据 | 这条 PR 是否需要修改 |
|
||||
| **gitlink-pr-integrator** | 合并态、构建、测试、契约、安全和冲突门禁 | 现在能否进入合并队列 |
|
||||
| **gitlink-pr-topology** | PR 依赖、重叠、替代、冲突和关系簇 | 哪些 PR 先看、一起看或择一保留 |
|
||||
| **gitlink-maintainer-radar** | 首响 SLA、reviewer 负载、责任停滞和安全优先级 | 今天维护者先处理什么 |
|
||||
| **gitlink-cli-contract-guard** | flags、帮助、JSON、错误、文档和安全契约 | 是否破坏既有 CLI 用户 |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 使用场景
|
||||
|
|
@ -237,6 +259,13 @@ gitlink-cli org +info -i Gitlink
|
|||
- [gitlink-pr/SKILL.md](gitlink-pr/SKILL.md) - PR 命令
|
||||
- [gitlink-issue/examples/issue-workflow.md](gitlink-issue/examples/issue-workflow.md) - Issue 工作流
|
||||
|
||||
**维护者效率**:
|
||||
- [gitlink-code-review/SKILL.md](gitlink-code-review/SKILL.md) - PR 代码审查
|
||||
- [gitlink-pr-integrator/SKILL.md](gitlink-pr-integrator/SKILL.md) - 集成门禁
|
||||
- [gitlink-pr-topology/SKILL.md](gitlink-pr-topology/SKILL.md) - PR 关系图谱
|
||||
- [gitlink-maintainer-radar/SKILL.md](gitlink-maintainer-radar/SKILL.md) - 维护者值班雷达
|
||||
- [gitlink-cli-contract-guard/SKILL.md](gitlink-cli-contract-guard/SKILL.md) - CLI 契约守卫
|
||||
|
||||
**发布和搜索**:
|
||||
- [gitlink-release/SKILL.md](gitlink-release/SKILL.md) - Release 命令
|
||||
- [gitlink-search/SKILL.md](gitlink-search/SKILL.md) - 搜索命令
|
||||
|
|
|
|||
|
|
@ -1,8 +1,25 @@
|
|||
---
|
||||
name: gitlink-cli-contract-guard
|
||||
version: 1.0.0
|
||||
description: "CLI 契约守卫：审查 GitLink CLI 改动是否破坏既有命令契约，重点检查 flags 与默认值、命令层级与帮助文本、`--format json` 输出结构、错误提示与编码质量、README/示例命令和实际行为是否漂移。用于用户需要判断某个 PR 或本地改动会不会破坏旧用法、引入不兼容输出、造成帮助文档失真，或在合并前补做兼容性审查时。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli pr --help"
|
||||
---
|
||||
|
||||
## 已合并功能的增量证据
|
||||
|
||||
前置 PR #426 和 #427 同时扩展了 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-` 契约问题；不把新增字段本身判为破坏性变化，也不替代代码质量、队列治理或集成门禁结论。
|
||||
|
||||
# gitlink-cli-contract-guard
|
||||
|
||||
**CRITICAL - 如果需要拉取 GitLink 上的 PR 元数据、diff 或评论，先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。**
|
||||
|
|
@ -19,6 +36,35 @@ description: "CLI 契约守卫：审查 GitLink CLI 改动是否破坏既有命
|
|||
4. **错误契约**：错误提示、退出语义、编码质量、用户可理解性。
|
||||
5. **文档契约**：README、示例、帮助文本与真实行为是否一致。
|
||||
|
||||
## 效率版契约门禁
|
||||
|
||||
默认遵循 [`../gitlink-shared/references/maintenance-report-contract.md`](../gitlink-shared/references/maintenance-report-contract.md)，先给维护者一个兼容性决策，再列证据。首屏最多展示 5 个会阻断合并或影响脚本用户的动作，问题编号使用 `CG-xxx`。
|
||||
|
||||
除五类既有契约面外，增加安全契约检查：
|
||||
|
||||
- token、cookie、Authorization 和调试输出必须脱敏，不能进入 Markdown 或 JSON 报告。
|
||||
- header、path、query、文件路径和 shell 参数在模板渲染后仍需校验，防止注入和路径遍历。
|
||||
- `--format json` 不得混入 ANSI 颜色、HTML 标签、日志或非 JSON 文本；退出码要能区分成功、参数错误、认证失败和远端失败。
|
||||
- 认证、权限、webhook、文件读写、外部 URL 和新依赖改动必须进入安全矩阵，并补未登录、无权、恶意输入和超时测试。
|
||||
|
||||
推荐首屏格式：
|
||||
|
||||
```markdown
|
||||
# CLI 契约审查摘要
|
||||
**结论：** <span style="color:#B42318"><strong>阻断合并</strong></span> **[blocked]**
|
||||
**门禁：** 参数通过 | 帮助通过 | JSON 失败 | 错误提示通过 | 安全未验证
|
||||
|
||||
## 先做这 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 的职责：
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ Agent 平台：Codex
|
|||
|
||||
- `git diff --name-status origin/master...HEAD`：确认仅 skill 文档和图片资产变更。
|
||||
- `git diff --check origin/master...HEAD`：通过。
|
||||
- `rg "<EFBFBD>|锛|鈥|Ã|Â|绠|璇|涓|馃"`：未命中新增/修改文本。
|
||||
- `rg "锛|鈥|Ã|Â|绠|璇|涓"`：未命中新增/修改文本。
|
||||
- `go test ./cmd/... ./shortcuts/...`：通过。
|
||||
|
||||
### 低风险备注
|
||||
|
|
|
|||
|
|
@ -0,0 +1,20 @@
|
|||
# 轻量 CLI 契约审查示例
|
||||
|
||||
```powershell
|
||||
go test ./cmd/... ./shortcuts/...
|
||||
go run . pr +view --owner Gitlink --repo gitlink-cli --id 123 --format json
|
||||
go run . --help
|
||||
go run . pr +view --owner Gitlink --repo gitlink-cli --id 123 --format json 2>error.txt
|
||||
```
|
||||
|
||||
```markdown
|
||||
# CLI 契约审查摘要
|
||||
**结论：** <span style="color:#B42318"><strong>阻断合并</strong></span> **[blocked]**
|
||||
**门禁：** 参数通过 | 帮助通过 | JSON 失败 | 错误提示通过 | 安全未验证
|
||||
|
||||
## 先做这 2 件事
|
||||
1. **[CG-001][blocking] 修复** JSON 输出中的调试文本，并补结构化断言。
|
||||
2. **[CG-002][high] 验证** `--header` 的换行、引号和敏感值脱敏边界。
|
||||
```
|
||||
|
||||
关键回归至少覆盖旧 flag、默认值、帮助、成功 JSON、错误 JSON、退出码、中文 UTF-8、`NO_COLOR` 和恶意输入；不要只以进程返回 0 作为通过依据。
|
||||
|
|
@ -8,6 +8,16 @@ metadata:
|
|||
cliHelp: "gitlink-cli pr --help"
|
||||
---
|
||||
|
||||
## 已合并功能的增量证据
|
||||
|
||||
前置 PR #426 合并后，优先用 `workflow +review-context` 一次获取变更文件、Review、提交记录和 CI 结果，再进行本 Skill 的代码质量、测试充分性和代码安全审查：
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <number> --include-commits=true --include-ci=true --format json
|
||||
```
|
||||
|
||||
本 Skill 只消费代码层证据；CI 失败可以作为审查依据，但不直接替代 `gitlink-pr-integrator` 的合并门禁。若 `sections` 缺少 `commits` 或 `ci_builds`，或 `notes` 标记探针失败，相关结论必须标记为 `partial`。
|
||||
|
||||
# gitlink-code-review（智能代码审查）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
|
|
@ -16,6 +26,39 @@ metadata:
|
|||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
|
||||
## 效率版默认输出
|
||||
|
||||
本 Skill 默认遵循 [`../gitlink-shared/references/maintenance-report-contract.md`](../gitlink-shared/references/maintenance-report-contract.md)，先输出维护者可直接执行的摘要，不把完整分析堆在首屏：
|
||||
|
||||
1. 先给 `decision`、最高严重性、阻断数、高风险数、安全门禁和验证状态。
|
||||
2. 只列最多 5 项按优先级排序的动作，每项标明 `CR-xxx`、责任方、文件/行号或命令证据。
|
||||
3. 完整逐文件审查、正向反馈和原始证据放到“证据附录”；无关的风格建议合并，不刷屏。
|
||||
4. Markdown 使用“颜色 + 粗体 + 纯文本回退”；JSON 只输出稳定字段，绝不混入 ANSI、HTML 或 emoji。
|
||||
|
||||
报告首屏固定使用以下结构：
|
||||
|
||||
```markdown
|
||||
# PR #<number> 代码审查摘要
|
||||
**结论：** <span style="color:#B42318"><strong>需要修改</strong></span> **[action_required]**
|
||||
**安全门禁：** <span style="color:#B42318"><strong>未通过</strong></span> | **验证：** 部分完成
|
||||
**问题：** blocking 1 / high 2 / medium 1 | **范围：** 4 files, +120/-30
|
||||
|
||||
## 先做这 3 件事
|
||||
1. **[CR-001][blocking] 修复** `path/to/file.go:42` 的凭据泄露风险（责任：作者）。
|
||||
2. **[CR-002][high] 补充** 恶意输入和失败路径测试（责任：作者）。
|
||||
3. **[CR-003][medium] 复看** 中文错误提示的 UTF-8 输出（责任：维护者）。
|
||||
```
|
||||
|
||||
## 安全和验证门禁
|
||||
|
||||
除了语言专项检查，必须读取 [`../gitlink-shared/references/security-review-matrix.md`](../gitlink-shared/references/security-review-matrix.md)，根据 diff 命中的数据流执行凭据、注入、路径、权限、依赖、敏感输出和资源耗尽检查。至少验证正常路径、失败路径和兼容路径；没有仓库定义的测试命令时写明“未找到”，不得写成通过。
|
||||
|
||||
安全发现使用 `CR-xxx` 编号，疑似真实密钥只报告类型和位置，不复制内容。涉及写操作、权限或外连的验证使用脱敏 fixture、临时 worktree 和 `--dry-run`。
|
||||
|
||||
## 职责边界与组合协同
|
||||
|
||||
独立运行时，本 Skill 只评价单个 PR 的代码、测试、可维护性和代码级安全，不评价 reviewer SLA、PR 之间的重复关系或是否进入合并队列。组合运行时读取共享上下文，向 `gitlink-pr-integrator` 交接 `CR-xxx` 发现和验证门禁；如果发现涉及 CLI 参数、JSON 或错误边界，关联 `gitlink-cli-contract-guard` 的 `CG-xxx`，不要重复生成同一条泛化安全结论。
|
||||
|
||||
## 工作流概览
|
||||
|
||||
本 Skill 提供一套完整的 AI 驱动代码审查工作流，覆盖从获取 PR 变更到生成审查报告的全过程。不需要额外的 CLI Shortcuts——现有 `gitlink-cli` 命令 + AI Agent 的分析能力即可完成。
|
||||
|
|
|
|||
|
|
@ -0,0 +1,27 @@
|
|||
# 轻量 PR 审查示例
|
||||
|
||||
这个示例展示维护者默认看到的摘要，而不是完整审查记录。完整 diff 和命令输出放在附录。
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +view --owner Gitlink --repo gitlink-cli --id 123 --format json
|
||||
gitlink-cli pr +files --owner Gitlink --repo gitlink-cli --id 123 --format json
|
||||
gitlink-cli pr +diff --owner Gitlink --repo gitlink-cli --id 123 --format json
|
||||
gitlink-cli pr +reviews --owner Gitlink --repo gitlink-cli --id 123 --format json
|
||||
```
|
||||
|
||||
```markdown
|
||||
# PR #123 代码审查摘要
|
||||
**结论：** <span style="color:#B54708"><strong>需要补验证</strong></span> **[action_required]**
|
||||
**安全门禁：** 部分完成 | **验证：** 部分完成 | **问题：** high 1 / medium 2
|
||||
|
||||
## 先做这 3 件事
|
||||
1. **[CR-001][high] 补充** 恶意路径和无权限请求测试（责任：作者）。
|
||||
2. **[CR-002][medium] 验证** Windows PowerShell 下的中文错误输出（责任：作者）。
|
||||
3. **[CR-003][medium] 复看** API 失败时的回滚行为（责任：维护者）。
|
||||
```
|
||||
|
||||
## 关键验证
|
||||
|
||||
- 正常路径、失败路径、兼容路径至少各一条。
|
||||
- 触及 token、权限、命令、文件路径、外部 URL 或依赖时，执行共享安全矩阵对应检查。
|
||||
- 报告落盘后确认 Markdown 为 UTF-8；JSON 可解析且没有 ANSI、HTML 或敏感值。
|
||||
|
|
@ -1,8 +1,24 @@
|
|||
---
|
||||
name: gitlink-maintainer-radar
|
||||
version: 1.0.0
|
||||
description: "维护者雷达：面向 GitLink 仓库维护者，联合扫描 open Pull Request、open Issue、消息提醒、review 分配和等待时长，识别响应超时、review 负载失衡、负责人长期停滞等协作瓶颈，生成按优先级排序的处置清单、催办建议和责任调整建议。用于用户需要值班巡检待办、判断哪些事项被晾着了、找出 reviewer 瓶颈、发现有负责人但无进展的条目，或生成维护者今日工作面板时。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli pr --help"
|
||||
---
|
||||
|
||||
## 已合并功能的增量证据
|
||||
|
||||
前置 PR #427 的队列差异是本 Skill 的增量输入。值班扫描应优先展示 `new`、`priority_changed`、`risk_changed` 和 `resolved`，把未变化项压缩为数量；需要深入某个 PR 时，再用前置 PR #426 的证据包补齐 Review、提交和 CI 状态：
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +review-queue --owner <owner> --repo <repo> --previous queue-previous.json --format json
|
||||
gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <number> --include-ci=true --format json
|
||||
```
|
||||
|
||||
本 Skill 只负责 SLA、Reviewer 负载、责任停滞和今日待办；`risk_changed` 是提醒信号，不直接宣称代码存在漏洞或阻断合并。
|
||||
|
||||
# gitlink-maintainer-radar
|
||||
|
||||
**CRITICAL - 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，按其中的认证、全局参数和安全规则执行。**
|
||||
|
|
@ -17,6 +33,37 @@ description: "维护者雷达：面向 GitLink 仓库维护者，联合扫描 op
|
|||
|
||||
把它当作“维护者值班面板”来用，而不是通知中心。
|
||||
|
||||
## 效率版值班面板
|
||||
|
||||
默认遵循 [`../gitlink-shared/references/maintenance-report-contract.md`](../gitlink-shared/references/maintenance-report-contract.md)，首屏只给维护者今天可以执行的队列：
|
||||
|
||||
- 先显示 HOT 数量、最早超时对象、安全事项、reviewer 瓶颈和本轮扫描时间。
|
||||
- 最多输出 5 项动作，并明确等待方：`author`、`reviewer`、`maintainer` 或 `platform`。
|
||||
- 同一 PR 的 SLA、review 负载和责任停滞信号合并为一项，避免重复催办。
|
||||
- 普通消息、点赞和已明确归属且未超时的条目只计数，不展开正文。
|
||||
|
||||
读取 [`../gitlink-shared/references/security-review-matrix.md`](../gitlink-shared/references/security-review-matrix.md)。对涉及凭据、权限、命令、路径、webhook、依赖和敏感数据的 PR 提升为安全 HOT；但仅凭标题或标签不能认定存在漏洞，必须标记证据状态。
|
||||
|
||||
首屏格式：
|
||||
|
||||
```markdown
|
||||
# 维护者值班摘要
|
||||
**结论：** <span style="color:#B42318"><strong>今日需处理</strong></span> **[action_required]**
|
||||
**队列：** HOT 4 | WATCH 6 | reviewer 瓶颈 1 | 安全 HOT 1
|
||||
|
||||
## 先做这 4 件事
|
||||
1. **[MR-001][blocking] 转派** PR #123 的安全复查，当前等待 reviewer（责任：维护者）。
|
||||
2. **[MR-002][high] 回复** Issue #87，首响已超 24 小时（责任：维护者）。
|
||||
3. **[MR-003][high] 复看** 作者更新后的 PR #118（责任：reviewer）。
|
||||
4. **[MR-004][medium] 确认** Issue #91 是否继续推进（责任：assignee）。
|
||||
```
|
||||
|
||||
如果没有 open PR 或 open Issue，明确报告“没有可分析的 open PR/Issue”；如果消息接口失败，不得用通知列表代替协作队列，也不得伪造 SLA。
|
||||
|
||||
## 职责边界与组合协同
|
||||
|
||||
独立运行时，本 Skill 只分析响应时效、reviewer 负载、责任停滞和队列变化，不判断代码是否有漏洞、不评价 CLI 契约，也不决定 PR 是否可合并。组合运行时读取 `CR-xxx`、`CG-xxx`、`TP-xxx` 和 `IN-xxx` 的状态，只将它们转换为维护动作 `MR-xxx`；一个安全发现只提升优先级，不在本 Skill 中重新宣称漏洞成立。
|
||||
|
||||
## 核心能力
|
||||
|
||||
### 1. 响应时效雷达
|
||||
|
|
|
|||
|
|
@ -0,0 +1,20 @@
|
|||
# 轻量维护者值班示例
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state open --format json
|
||||
gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state open --format json
|
||||
gitlink-cli api GET users/<login>/messages.json --query "status=1&limit=40" --format json
|
||||
```
|
||||
|
||||
```markdown
|
||||
# 维护者值班摘要
|
||||
**结论：** <span style="color:#B42318"><strong>今日需处理</strong></span> **[action_required]**
|
||||
**队列：** HOT 3 | WATCH 5 | reviewer 瓶颈 1 | 安全 HOT 1
|
||||
|
||||
## 先做这 3 件事
|
||||
1. **[MR-001][blocking] 转派** PR #123 的安全复查，当前等待 reviewer（责任：维护者）。
|
||||
2. **[MR-002][high] 回复** Issue #87，首响已超时（责任：维护者）。
|
||||
3. **[MR-003][high] 复看** 作者已更新的 PR #118（责任：reviewer）。
|
||||
```
|
||||
|
||||
只展开会改变本轮行动的条目。普通通知只计数；接口失败、空队列和未配置 SLA 都要原样标出。
|
||||
|
|
@ -1,8 +1,23 @@
|
|||
---
|
||||
name: gitlink-pr-integrator
|
||||
version: 1.0.0
|
||||
description: 评估 GitLink Pull Request 是否已经具备集成到主线的条件，输出合并态验证、与其他 open PR 的冲突风险、集成影响面、发布与回移建议以及合并后动作清单。用于维护者需要决定某个 PR 是否可以进入 merge queue、为一批待合并 PR 排顺序、在合并前验证 rebase 或 merge 后是否仍能构建测试通过，或为自动化队列生成集成就绪报告时。
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli pr --help"
|
||||
---
|
||||
|
||||
## 已合并功能的增量证据
|
||||
|
||||
前置 PR #426 合并后，先复用统一 PR 证据包，再进入本 Skill 的独立 worktree 验证。重点读取 `commits`、`ci_builds`、`sections` 和 `notes`，将 CI 状态与本地构建、测试结果一起纳入集成门禁：
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <number> --include-commits=true --include-ci=true --format json
|
||||
```
|
||||
|
||||
本 Skill 只负责合并态、构建、测试、契约和发布影响，不代替代码审查。已有队列快照时可读取前置 PR #427 的 `changes`，但它只能辅助排序，不能跳过本地验证。
|
||||
|
||||
# gitlink-pr-integrator
|
||||
|
||||
**CRITICAL - 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。**
|
||||
|
|
@ -15,6 +30,35 @@ description: 评估 GitLink Pull Request 是否已经具备集成到主线的条
|
|||
|
||||
执行命令前，按需读取 [`references/api_reference.md`](./references/api_reference.md)。其中包含 GitLink CLI 命令、Windows 调用方式、独立 worktree 验证方法和报告字段约定。
|
||||
|
||||
## 效率版集成门禁
|
||||
|
||||
默认遵循 [`../gitlink-shared/references/maintenance-report-contract.md`](../gitlink-shared/references/maintenance-report-contract.md)，先回答“现在能否进入 merge queue”，再展开证据。首屏只保留：
|
||||
|
||||
- `decision`：`merge`、`action_required` 或 `blocked`
|
||||
- 合并态、构建、测试、契约、安全和冲突六个门禁
|
||||
- 最多 5 项下一动作，明确等待作者、reviewer、维护者还是平台
|
||||
- 仅列会改变排序的冲突和影响面，其余放附录
|
||||
|
||||
读取 [`../gitlink-shared/references/security-review-matrix.md`](../gitlink-shared/references/security-review-matrix.md)。若 PR 修改认证、权限、命令执行、文件路径、webhook、依赖或敏感输出，安全门禁至少为 `not_run`，不能直接给出 `ready_to_merge`。安全验证、构建和测试都要分别记录 `passed` / `failed` / `not_run`。
|
||||
|
||||
推荐的首屏格式：
|
||||
|
||||
```markdown
|
||||
# PR #<number> 集成摘要
|
||||
**结论：** <span style="color:#B54708"><strong>需补验证</strong></span> **[action_required]**
|
||||
**门禁：** 合并态通过 | 构建通过 | 测试未执行 | 安全未验证 | 冲突低
|
||||
|
||||
## 先做这 2 件事
|
||||
1. **[IN-001][high] 验证** `go test ./...`（责任：作者/维护者确认命令）。
|
||||
2. **[IN-002][high] 复查** `internal/auth/` 的权限边界（责任：reviewer）。
|
||||
```
|
||||
|
||||
只有六项门禁全部有充分证据且无 `blocking/high` 未解决项，才可使用 `merge`。大型 PR 先做文件/目录重叠和安全热点筛选，只有高风险候选才进入独立 worktree 的完整合并验证，避免批量扫描浪费维护者时间。
|
||||
|
||||
## 职责边界与组合协同
|
||||
|
||||
独立运行时，本 Skill 只判断一个 PR 是否具备进入合并队列的条件；它不重新做完整代码审查、不判断 PR 之间的替代关系，也不按 SLA 排维护者任务。组合运行时读取 `CR-xxx`、`CG-xxx` 和 `TP-xxx` 结果，使用 `IN-xxx` 记录集成阻断和门禁，不改写专项发现。安全专项未运行时，安全门禁必须保持 `not_run`，不能因构建通过而推断安全通过。
|
||||
|
||||
## Windows 前置
|
||||
|
||||
如果你在 Windows PowerShell 里运行或落盘报告，先执行：
|
||||
|
|
|
|||
|
|
@ -0,0 +1,19 @@
|
|||
# 轻量集成审查示例
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +view --owner Gitlink --repo gitlink-cli --id 123 --format json
|
||||
gitlink-cli pr +files --owner Gitlink --repo gitlink-cli --id 123 --format json
|
||||
gitlink-cli pr +reviews --owner Gitlink --repo gitlink-cli --id 123 --format json
|
||||
gitlink-cli ci +builds --owner Gitlink --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
```markdown
|
||||
# PR #123 集成摘要
|
||||
**结论：** <span style="color:#067647"><strong>可进入合并队列</strong></span> **[merge]**
|
||||
**门禁：** 合并态通过 | 构建通过 | 测试通过 | 契约通过 | 安全通过 | 冲突低
|
||||
|
||||
## 需要记录的动作
|
||||
1. **[IN-001][low] 更新** 发布说明（责任：维护者）。
|
||||
```
|
||||
|
||||
如果构建、测试或安全门禁是 `not_run`，结论必须降级为 `action_required` 或 `blocked`。高风险 PR 需要在独立 worktree 中验证，且报告记录真实 base、head 和命令。
|
||||
|
|
@ -1,8 +1,24 @@
|
|||
---
|
||||
name: gitlink-pr-topology
|
||||
version: 1.0.0
|
||||
description: "开源社区 PR 队列关系图谱：面向一个仓库的多条 open Pull Request，识别它们之间的依赖链、功能重叠、替代/超越关系、冲突热点、可打包评审分组和建议处理顺序。用于维护者需要批量梳理 open PR 为什么互相卡住、哪几条其实在做同一件事、哪一条实现更完整、哪些 PR 应该先合并或先关闭，以及如何把复杂队列整理成可执行决策时。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli pr --help"
|
||||
---
|
||||
|
||||
## 已合并功能的增量证据
|
||||
|
||||
前置 PR #426 提供统一的 PR 文件、提交和 Review 证据；前置 PR #427 提供队列变化。拓扑分析可以先取一次队列快照，再为候选关系补取证据，减少对整条 open PR 队列的重复请求：
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +review-queue --owner <owner> --repo <repo> --previous queue-previous.json --format json
|
||||
gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <number> --include-commits=true --format json
|
||||
```
|
||||
|
||||
本 Skill 只输出 `TP-` 关系、证据、置信度和处理顺序，不把队列变化直接解释为代码缺陷，也不替代 `gitlink-code-review` 和 `gitlink-pr-integrator` 的结论。
|
||||
|
||||
# gitlink-pr-topology
|
||||
|
||||
**CRITICAL - 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。**
|
||||
|
|
@ -21,6 +37,34 @@ description: "开源社区 PR 队列关系图谱：面向一个仓库的多条 o
|
|||
5. 哪些 PR 应该一起评审，避免维护者重复进入同一上下文。
|
||||
6. 当前 open PR 队列最合理的处理顺序是什么。
|
||||
|
||||
## 效率版队列输出
|
||||
|
||||
默认遵循 [`../gitlink-shared/references/maintenance-report-contract.md`](../gitlink-shared/references/maintenance-report-contract.md)，输出“关系摘要”而不是完整的两两比较表：
|
||||
|
||||
1. 先给 open PR 数、关系簇数量、冲突热点、安全热点和建议处理顺序。
|
||||
2. 只展示会改变维护决策的最多 5 条关系；相同关系簇合并成一项，完整边列表放附录或 JSON。
|
||||
3. 每条关系使用 `TP-xxx` 稳定编号，写明证据、置信度和建议动作；没有足够证据时标为 `candidate`，不能断言重复或 supersedes。
|
||||
4. 对同时修改认证、权限、命令执行、路径处理、依赖或输出敏感数据的 PR，增加 `security_hotspot` 关系，要求先完成安全审查再排序。
|
||||
|
||||
首屏示例：
|
||||
|
||||
```markdown
|
||||
# PR 队列关系摘要
|
||||
**结论：** <span style="color:#B54708"><strong>需要重排</strong></span> **[reorder]**
|
||||
**范围：** 18 个 open PR | 4 个关系簇 | 2 个高风险热点
|
||||
|
||||
## 先处理
|
||||
1. **[TP-001][blocking] 先处理** #61，再处理 #63：共享 `shortcuts/pr/`，#63 依赖 #61 的输出字段。
|
||||
2. **[TP-002][high] 择一评审** #71 / #74：目标重叠，但 #74 缺安全和回归测试，不能直接判定 supersedes。
|
||||
3. **[TP-003][high] 安全复查** #80 / #82：同时改变权限校验。
|
||||
```
|
||||
|
||||
先按标题、issue、改动文件和目录做低成本候选筛选，再对候选关系读取 diff、review 和测试证据；不要对所有 PR 做完整笛卡尔积分析。
|
||||
|
||||
## 职责边界与组合协同
|
||||
|
||||
独立运行时，本 Skill 只判断多个 open PR 之间的关系，不判断单条 PR 的代码缺陷、契约通过与否或维护者响应是否超时。组合运行时向 `gitlink-pr-integrator` 交接 `TP-xxx` 关系和建议顺序，向 `gitlink-maintainer-radar` 交接冲突热点和待处理簇；`security_hotspot` 只表示需要安全复查，不等同于已确认漏洞。
|
||||
|
||||
## 不覆盖的内容
|
||||
|
||||
下面这些不属于本 skill 的职责：
|
||||
|
|
|
|||
|
|
@ -0,0 +1,22 @@
|
|||
# 轻量 PR 队列关系示例
|
||||
|
||||
先使用列表信息筛选候选，再对候选读取 diff，避免所有 PR 两两拉取完整内容。
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state open --limit 50 --format json
|
||||
gitlink-cli pr +files --owner Gitlink --repo gitlink-cli --id <candidate> --format json
|
||||
gitlink-cli pr +diff --owner Gitlink --repo gitlink-cli --id <candidate> --format json
|
||||
```
|
||||
|
||||
```markdown
|
||||
# PR 队列关系摘要
|
||||
**结论：** <span style="color:#B54708"><strong>需要重排</strong></span> **[reorder]**
|
||||
**范围：** 12 个 open PR | 3 个关系簇 | 1 个安全热点
|
||||
|
||||
## 先处理
|
||||
1. **[TP-001][blocking] 先处理** #61，再处理 #63：共享命令入口且 #63 使用 #61 的输出字段。
|
||||
2. **[TP-002][high] 一起评审** #71、#74：修改同一 API 包装层，需统一错误契约。
|
||||
3. **[TP-003][high] 安全复查** #80：修改权限校验，不能仅凭标题判定可合并。
|
||||
```
|
||||
|
||||
关系证据不足时写 `candidate`，并说明还缺哪些 diff、review 或测试证据。
|
||||
|
|
@ -8,8 +8,12 @@ metadata:
|
|||
cliHelp: "gitlink-cli --help"
|
||||
---
|
||||
|
||||
五个维护 Skill 的证据复用和职责边界见 [`references/maintenance-evidence-workflow.md`](references/maintenance-evidence-workflow.md)。前置 PR #426 提供单 PR 证据包，前置 PR #427 提供队列快照差异；二者只提供只读基础数据，不合并五个 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 不得混入展示层样式。
|
||||
|
||||
本技能指导你如何通过 gitlink-cli 操作 GitLink 平台资源。
|
||||
|
||||
## 认证
|
||||
|
|
|
|||
|
|
@ -0,0 +1,20 @@
|
|||
{
|
||||
"schema_version": "1.0",
|
||||
"mode": "executive",
|
||||
"decision": "action_required",
|
||||
"severity": "high",
|
||||
"counts": {"blocking": 0, "high": 1, "medium": 1, "low": 0},
|
||||
"security_gate": "passed",
|
||||
"verification": "partial",
|
||||
"scope": {"owner": "Gitlink", "repo": "gitlink-cli", "items": 1},
|
||||
"top_actions": [
|
||||
{
|
||||
"id": "CR-001",
|
||||
"owner": "author",
|
||||
"action": "补充失败路径测试",
|
||||
"evidence": ["shortcuts/example/example_test.go:42"]
|
||||
}
|
||||
],
|
||||
"findings": [],
|
||||
"limitations": ["平台 CI 结果未提供"]
|
||||
}
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
param(
|
||||
[Parameter(Mandatory = $true)]
|
||||
[string]$Path
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$raw = Get-Content -Raw -Encoding utf8 $Path
|
||||
$report = $raw | ConvertFrom-Json
|
||||
|
||||
$required = @('schema_version', 'mode', 'decision', 'severity', 'counts', 'security_gate', 'verification', 'top_actions', 'findings', 'limitations')
|
||||
foreach ($name in $required) {
|
||||
if ($null -eq $report.PSObject.Properties[$name]) {
|
||||
throw "missing report field: $name"
|
||||
}
|
||||
}
|
||||
|
||||
if ($report.mode -notin @('executive', 'standard', 'full')) { throw "invalid report mode" }
|
||||
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" }
|
||||
|
||||
Write-Output "maintenance report contract passed: $Path"
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
# 维护 Skill 证据工作流
|
||||
|
||||
这份协议把五个维护 Skill 的输入分成两层：单个 PR 的证据包，以及 open PR 队列的变化快照。它们是基础数据，不是新的“总控 Skill”；每个 Skill 仍然只对自己的职责给出结论。
|
||||
|
||||
## 单个 PR 证据包
|
||||
|
||||
前置 PR #426 合并后，优先使用以下只读命令：
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +review-context \
|
||||
--owner <owner> --repo <repo> --number <pr-number> \
|
||||
--include-commits=true --commit-limit 100 \
|
||||
--include-ci=true --ci-limit 20 --format json
|
||||
```
|
||||
|
||||
证据包包含仓库信息、PR 详情、变更文件、Reviews、提交记录和 CI 构建结果。所有集合都有上限；某个探针失败时检查 `notes` 和 `sections`，不能把缺失数据写成“通过”。已有调用不传新增开关时保持原行为。
|
||||
|
||||
## 队列变化快照
|
||||
|
||||
前置 PR #427 合并后，先保存 JSON 基线，再在下一轮比较：
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +review-queue \
|
||||
--owner <owner> --repo <repo> --format json > queue-previous.json
|
||||
|
||||
gitlink-cli workflow +review-queue \
|
||||
--owner <owner> --repo <repo> \
|
||||
--previous queue-previous.json --format json
|
||||
```
|
||||
|
||||
`changes` 只表达队列事实：`new`、`resolved`、`priority_changed`、`risk_changed` 和 `unchanged`。它不替代代码审查、集成门禁或维护者判断。无 PR 编号的本地输入只能按规范化标题匹配，报告必须降低置信度。
|
||||
|
||||
## 五个 Skill 的消费边界
|
||||
|
||||
| Skill | 使用单 PR 证据 | 使用队列变化 | 最终只负责什么 |
|
||||
|---|---|---|---|
|
||||
| `gitlink-code-review` | 文件、提交、Review、CI | 不需要 | 代码质量、测试充分性和代码层安全问题 |
|
||||
| `gitlink-pr-integrator` | PR 详情、提交、CI、已有结论 | 可读取变化作为上下文 | rebase、构建、测试、契约和合并态门禁 |
|
||||
| `gitlink-pr-topology` | PR 详情和文件摘要 | 新增/解决项作为关系图增量 | PR 间依赖、重叠、冲突和替代关系 |
|
||||
| `gitlink-maintainer-radar` | Review 和 PR 元数据 | 重点消费新增、风险变化和已解决项 | SLA、Reviewer 负载、责任停滞和今日待办 |
|
||||
| `gitlink-cli-contract-guard` | 文件、帮助、JSON 和错误证据 | 只在涉及 workflow flags/JSON 时消费 | CLI 参数、帮助、输出、错误和编码契约 |
|
||||
|
||||
## 组合运行规则
|
||||
|
||||
1. 先获取一次证据包和队列快照，后续 Skill 通过 `sections`、`notes` 和 `changes` 判断证据完整性。
|
||||
2. 单独运行某个 Skill 时只读取它需要的字段，并把其他维度标记为未纳入本次检查。
|
||||
3. 组合运行时允许共享事实和安全信号，但发现编号必须保留各自前缀：`CR-`、`IN-`、`TP-`、`MR-`、`CG-`。
|
||||
4. 同一事实可以被多个 Skill 引用，但只能由负责该维度的 Skill 生成最终动作；例如 CI 失败可以被代码审查引用，却只能由集成 Skill 决定是否形成合并阻断。
|
||||
5. 任何探针失败或快照缺失都输出 `not_run`/`partial`，不能用默认值填充成功结论。
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
# 维护者效率报告协议
|
||||
|
||||
五个维护类 Skill 统一遵循本协议。目标是让维护者在 30 秒内知道“先处理什么、为什么、下一步由谁做”，同时保留可追溯的证据。
|
||||
|
||||
## 默认输出层级
|
||||
|
||||
默认生成 `executive` 模式；用户明确要求细节时再生成 `standard` 或 `full`。
|
||||
|
||||
1. **执行摘要**：结论、阻断数、高风险数、安全门禁、验证状态和扫描范围。
|
||||
2. **今日动作**：最多 5 项，按优先级排序；每项必须包含对象、责任方、下一动作和证据引用。
|
||||
3. **证据附录**：完整发现、命令输出摘要、文件/行号、时间戳和未验证项。
|
||||
|
||||
不要在首屏输出原始 API 响应、完整 diff、所有通知或所有 PR 两两比较结果。需要保留时放入附录或 JSON。
|
||||
|
||||
## 统一决策字段
|
||||
|
||||
Markdown 和 JSON 的结论必须一致。推荐使用以下字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"mode": "executive",
|
||||
"decision": "action_required",
|
||||
"severity": "high",
|
||||
"counts": {"blocking": 1, "high": 2, "medium": 3, "low": 0},
|
||||
"security_gate": "fail",
|
||||
"verification": "partial",
|
||||
"scope": {"owner": "Gitlink", "repo": "gitlink-cli", "items": 12},
|
||||
"top_actions": [
|
||||
{"id": "CR-001", "owner": "maintainer", "action": "先处理安全阻断", "evidence": ["diff:shortcuts/x/y.go:42"]}
|
||||
],
|
||||
"findings": [],
|
||||
"limitations": []
|
||||
}
|
||||
```
|
||||
|
||||
允许的 `decision`：`merge`、`action_required`、`reorder`、`observe`、`blocked`。没有足够证据时必须使用 `observe` 或 `blocked`，不能猜测为通过。
|
||||
|
||||
## 严重性和稳定编号
|
||||
|
||||
- `blocking`：阻止合并、会泄露凭据、破坏兼容性或无法证明核心行为可用。
|
||||
- `high`：高概率影响真实用户、维护队列或安全边界，应进入本轮处理。
|
||||
- `medium`：需要补验证、文档或边界处理，但不立即阻断。
|
||||
- `low`：可延后处理的质量或可读性问题。
|
||||
|
||||
每条发现使用稳定前缀和递增编号：代码审查 `CR-001`、集成 `IN-001`、关系图谱 `TP-001`、维护雷达 `MR-001`、契约守卫 `CG-001`。复审时复用已有编号；新问题才新增编号。
|
||||
|
||||
## 醒目显示规则
|
||||
|
||||
Markdown 使用 HTML 颜色和粗体，同时必须提供纯 Markdown 回退，确保终端、网页和被清洗的渲染器都可读：
|
||||
|
||||
```markdown
|
||||
<span style="color:#B42318"><strong>阻断</strong></span> **[blocking]** #CR-001
|
||||
<span style="color:#B54708"><strong>高风险</strong></span> **[high]** #CR-002
|
||||
<span style="color:#067647"><strong>通过</strong></span> **[pass]**
|
||||
```
|
||||
|
||||
颜色只用于结论、严重性、门禁和动作，不要给整段正文着色。JSON、CSV 和命令管道输出禁止包含 ANSI 转义、HTML 标签或 emoji；使用纯字段值。
|
||||
|
||||
在支持终端颜色时，可以根据 `NO_COLOR` 约定关闭 ANSI 颜色。报告落盘默认不写 ANSI。
|
||||
|
||||
## 验证门禁
|
||||
|
||||
每次报告都要分别记录 `passed`、`failed`、`not_run`、`not_applicable`，不能把未执行写成通过：
|
||||
|
||||
| 门禁 | 最低要求 |
|
||||
|------|----------|
|
||||
| 数据完整性 | 目标、状态、更新时间和证据来源齐全 |
|
||||
| 核心行为 | 使用仓库定义的构建/测试命令，或明确记录未找到命令 |
|
||||
| 安全 | 扫描敏感文件、凭据、危险输入边界和权限变化 |
|
||||
| 回归 | 至少覆盖本次改动的正常路径、失败路径和兼容路径 |
|
||||
| 输出 | Markdown 可读，JSON 可解析，中文无替换字符或乱码 |
|
||||
|
||||
关键门禁失败时，结论不得为 `merge`。只列最能改变决策的测试；完整命令和输出摘要放在附录。
|
||||
|
||||
## 队列效率约束
|
||||
|
||||
- 首屏最多展示 5 个动作；其余项目按 `deferred_count` 计数并放入附录。
|
||||
- 同一对象的多个问题合并为一项动作，避免维护者重复阅读。
|
||||
- 每项动作只写一个明确动词：`修复`、`验证`、`复看`、`转派`、`合并`、`收口`。
|
||||
- 对“等待作者 / 等待 reviewer / 等待维护者 / 等待平台”的状态必须显式标注，避免错误催办。
|
||||
- 无 open PR 或无可用数据时，明确输出“没有可分析的 open PR”或“数据不足”，不得用历史样例冒充实时结果。
|
||||
|
||||
## 质量自检
|
||||
|
||||
生成报告后，依次检查：
|
||||
|
||||
```powershell
|
||||
# JSON 可解析且无颜色控制符
|
||||
$json | ConvertFrom-Json | Out-Null
|
||||
if ($json -match "`e\[|<span|</span>") { throw "JSON 含展示层标记" }
|
||||
|
||||
# Markdown 使用 UTF-8 保存，并检查替换字符
|
||||
$markdown | Set-Content .\maintenance-report.md -Encoding utf8
|
||||
$bytes = [IO.File]::ReadAllBytes('.\maintenance-report.md')
|
||||
$text = [Text.Encoding]::UTF8.GetString($bytes)
|
||||
if ($text.Contains([char]0xfffd) -or $text.Contains('?')) { throw "报告存在编码风险" }
|
||||
```
|
||||
|
||||
最后一条检查只针对报告中预期的中文文本；如果业务数据本身包含问号，应改为检查 UTF-8 替换字符和已知乱码片段，并记录例外。
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
# PR 安全审查矩阵
|
||||
|
||||
安全检查不是“看到 security 标签才执行”的附加项。五个维护类 Skill 都要先根据改动文件和数据流判断是否命中以下类别；无法验证时标记为 `not_run`，不能直接判定安全通过。
|
||||
|
||||
| 类别 | 重点信号 | 最低验证 | 默认级别 |
|
||||
|------|----------|----------|----------|
|
||||
| 凭据泄露 | token、密码、私钥、`.env`、日志回显 | 扫描 diff、配置、测试 fixture 和日志；确认脱敏 | blocking |
|
||||
| 命令注入 | shell 拼接、`exec`、用户可控参数进入命令 | 使用带空格、引号、shell 元字符的输入测试 | blocking |
|
||||
| 路径遍历 | 文件名、压缩包、下载地址来自用户或远端 | 验证 `..`、绝对路径、符号链接和跨平台分隔符 | high |
|
||||
| 注入 | SQL、模板、Markdown、HTML、JSON 拼接 | 正常值、边界值、恶意值和转义结果 | high |
|
||||
| SSRF / 外连 | URL、webhook、重定向、代理配置 | 限制协议、主机、重定向和内网地址 | high |
|
||||
| 认证授权 | token 作用域、项目权限、管理员动作 | 未登录、无权、越权和过期 token | blocking |
|
||||
| 不安全反序列化 | 任意类型、远端 JSON/YAML、对象恢复 | 不可信输入和异常输入，确认无任意代码执行 | blocking |
|
||||
| 依赖供应链 | 新增依赖、安装脚本、下载二进制 | 锁定版本、核对来源和最小权限 | high |
|
||||
| 敏感信息暴露 | PR 报告、错误、调试、缓存包含用户数据 | 检查 stdout、文件、JSON 和日志 | high |
|
||||
| 资源耗尽 | 无界分页、超大 diff、并发、重试 | 空数据、最大数据、超时和取消 | medium/high |
|
||||
| 加密与传输 | TLS、证书校验、随机数、哈希用途 | 禁止跳过证书校验，确认算法和错误处理 | high |
|
||||
|
||||
## 证据规则
|
||||
|
||||
每个命中的安全项至少记录：`category`、`status`、`evidence`、`test`、`owner`。代码位置使用文件和行号；行为验证使用实际命令；平台能力不确定时标记 `unverified_platform_behavior`。
|
||||
|
||||
## 自动化边界
|
||||
|
||||
静态关键词命中只能生成候选项，不能单独证明漏洞。动态验证不能覆盖真实凭据或生产写操作；默认使用脱敏 fixture、临时 worktree、`--dry-run` 和最小权限 token。发现疑似真实密钥时不要复制到报告，报告只保留类型、位置和轮换建议。
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
# 五个维护 Skill 的职责边界与交接协议
|
||||
|
||||
五个 Skill 可以单独运行，也可以由 Agent 编排成一条 PR 维护流水线。单独运行时只执行被请求的 Skill；组合运行时共享证据，但不互相越权替代判断。
|
||||
|
||||
## 职责矩阵
|
||||
|
||||
| Skill | 核心职责 | 明确不负责 | 主要输入 | 主要输出 |
|
||||
|------|----------|------------|----------|----------|
|
||||
| `gitlink-code-review` | 代码正确性、可维护性、测试充分性、代码级安全漏洞 | 不判断队列 SLA、PR 间关系或最终合并顺序 | 单个 PR 的 diff、文件、提交、review、测试证据 | `CR-xxx` 发现、修复建议和代码审查结论 |
|
||||
| `gitlink-cli-contract-guard` | flags、help、JSON、错误、退出码、文档和 CLI 边界安全 | 不评价业务设计价值、一般代码风格或 reviewer 负载 | CLI 改动、旧用法、golden 输出、错误路径测试 | `CG-xxx` 契约门禁和兼容性结论 |
|
||||
| `gitlink-pr-topology` | 多个 open PR 的依赖、重叠、替代、冲突和评审分组 | 不替代单 PR 代码审查或判断谁已满足合并条件 | PR 列表、文件集合、命令/API 面、diff 摘要 | `TP-xxx` 关系、证据、置信度和处理顺序 |
|
||||
| `gitlink-pr-integrator` | 合并态、rebase、构建、测试、契约、安全门禁和发布影响 | 不重新进行完整代码审查或维护者值班排序 | 单 PR 证据、其他 Skill 结论、主线和 CI 状态 | `IN-xxx` 集成门禁、决策和合并后动作 |
|
||||
| `gitlink-maintainer-radar` | 首响 SLA、reviewer 负载、责任停滞、等待方和队列变化 | 不判断代码漏洞、CLI 兼容性或 PR 功能优劣 | 队列快照、review 状态、评论时间、分配关系和安全优先级 | `MR-xxx` 维护动作、责任调整和催办建议 |
|
||||
|
||||
## 允许的功能重叠
|
||||
|
||||
重叠本身不是问题，关键是不能让一个 Skill 的完整功能覆盖另一个 Skill。以下能力可以被多个 Skill 使用：
|
||||
|
||||
- **证据采集**：多个 Skill 可以读取同一个 PR 上下文、Diff、Review、CI 和评论，但不应各自产生互不一致的事实。
|
||||
- **安全信号**：多个 Skill 可以发现安全相关信号，但必须按照不同层次输出；代码漏洞、CLI 边界、安全热点、合并门禁和维护优先级不能混为一谈。
|
||||
- **测试状态**：代码审查关注测试是否覆盖行为，契约守卫关注兼容性回归测试，集成器关注主线合并后的构建测试是否通过。
|
||||
- **报告格式**：所有 Skill 都可以使用统一的执行摘要、严重性、颜色和 JSON 字段，但发现编号和最终决策必须保持各自前缀与职责。
|
||||
- **排序信息**：拓扑提供依赖顺序，集成器提供合并顺序，维护雷达提供值班顺序；三者可能引用同一 PR，但排序依据不同。
|
||||
|
||||
以下情况视为错误设计：
|
||||
|
||||
- 代码审查已经替代 CLI 契约守卫的 flags/help/JSON 兼容检查。
|
||||
- 集成器直接替代代码审查，凭“构建通过”推断代码质量和安全通过。
|
||||
- 维护雷达直接决定 PR 是否可合并，或拓扑直接判定代码实现优劣。
|
||||
- 一个综合 Skill 包含其他四个 Skill 的全部输入、规则、输出和决策，导致其他 Skill 只剩转发作用。
|
||||
|
||||
每个 Skill 至少保留一个不可替代的决策对象：代码问题、CLI 契约、PR 关系、集成门禁或维护动作。组合运行只是汇总这些判断，不把它们压扁成一个万能 Skill。
|
||||
|
||||
## 安全职责分层
|
||||
|
||||
安全可以在多个 Skill 中出现，但检查对象不同，不能重复输出同一条泛化结论：
|
||||
|
||||
- `gitlink-code-review`：检查代码数据流，例如注入、路径遍历、反序列化、权限绕过和资源耗尽。
|
||||
- `gitlink-cli-contract-guard`：检查用户输入进入 flag、header、path、query、JSON、错误输出和 token 脱敏的边界。
|
||||
- `gitlink-pr-topology`：只标记涉及认证、权限、命令执行、外联和依赖的 PR 之间的安全热点关系。
|
||||
- `gitlink-pr-integrator`：汇总安全门禁；只要存在未解决的 blocking 安全发现，就不能给出 `merge`。
|
||||
- `gitlink-maintainer-radar`：只负责安全事项的运营优先级、等待方和催办，不宣称漏洞成立。
|
||||
|
||||
## 独立运行模式
|
||||
|
||||
用户只请求一个 Skill 时：
|
||||
|
||||
1. 只读取该 Skill 需要的最小数据。
|
||||
2. 只使用该 Skill 的编号前缀和决策集合。
|
||||
3. 对其他维度写“未纳入本次检查”，而不是擅自调用其他 Skill。
|
||||
4. 仍然遵循统一报告协议，因此输出可以被后续组合流程消费。
|
||||
|
||||
## 组合运行模式
|
||||
|
||||
当用户要求“全方位审查”或维护者启动完整流水线时，按以下顺序执行：
|
||||
|
||||
1. **证据收集**：获取单 PR 上下文和 open PR 队列快照。
|
||||
2. **并行专项检查**：同时运行 `code-review`、`cli-contract-guard` 和 `pr-topology`。
|
||||
3. **集成决策**：`pr-integrator` 读取专项结论，执行独立 worktree、构建、测试和合并门禁。
|
||||
4. **维护排序**：`maintainer-radar` 读取队列变化和前述结论，生成最多五项维护动作。
|
||||
5. **合并报告**：只保留一个主结论；重复发现合并为一个动作，并保留所有来源编号。
|
||||
|
||||
一个专项 Skill 失败不会让整条流水线伪造通过。将该专项的状态设为 `not_run`，并让集成器按门禁规则降级结论。
|
||||
|
||||
## 交接字段
|
||||
|
||||
各 Skill 的 JSON 结果应包含以下字段；`findings` 可使用各自的编号前缀：
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"producer": "gitlink-code-review",
|
||||
"scope": "single_pr",
|
||||
"target": {"owner": "Gitlink", "repo": "gitlink-cli", "number": 123},
|
||||
"decision": "action_required",
|
||||
"status": "completed",
|
||||
"findings": [
|
||||
{
|
||||
"id": "CR-001",
|
||||
"severity": "high",
|
||||
"status": "open",
|
||||
"summary": "缺少恶意路径测试",
|
||||
"evidence": ["shortcuts/example/example_test.go:42"],
|
||||
"related_ids": []
|
||||
}
|
||||
],
|
||||
"gates": {"security": "passed", "verification": "partial"},
|
||||
"limitations": []
|
||||
}
|
||||
```
|
||||
|
||||
下游 Skill 不改写上游发现，只通过 `related_ids` 关联；同一根因的多个发现由最终报告合并展示，保留 `source_ids` 供维护者追溯。
|
||||
|
||||
## 组合去重规则
|
||||
|
||||
- 相同文件/行号、相同行为和相同修复动作：合并为一个动作。
|
||||
- 同一安全问题分别命中代码层和 CLI 边界：保留两条证据，但只显示一个主动作。
|
||||
- `TP-xxx` 关系不能直接变成代码缺陷；它只影响处理顺序。
|
||||
- `MR-xxx` 等待超时不能直接变成合并阻断；它只影响维护优先级。
|
||||
- `IN-xxx` 只能引用专项发现，不能重写专项发现的技术结论。
|
||||
Loading…
Reference in New Issue