From defbef7fe78a0f75fec272277597aa9faffabcb4 Mon Sep 17 00:00:00 2001 From: Mengz <2567587994@qq.com> Date: Mon, 20 Jul 2026 11:25:37 +0800 Subject: [PATCH 1/4] =?UTF-8?q?=E5=AE=8C=E5=96=84=E7=BB=B4=E6=8A=A4?= =?UTF-8?q?=E8=80=85=E5=AE=A1=E6=9F=A5=20Skills=20=E7=9A=84=E6=8A=A5?= =?UTF-8?q?=E5=91=8A=E6=95=88=E7=8E=87=E4=B8=8E=E5=AE=89=E5=85=A8=E9=97=A8?= =?UTF-8?q?=E7=A6=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/README.md | 29 +++++ skills/gitlink-cli-contract-guard/SKILL.md | 30 ++++++ .../examples/codex-validation-2026-06-26.md | 2 +- .../examples/executive-contract-gate.md | 20 ++++ skills/gitlink-code-review/SKILL.md | 29 +++++ .../examples/executive-review.md | 27 +++++ skills/gitlink-maintainer-radar/SKILL.md | 32 ++++++ .../examples/executive-duty-board.md | 20 ++++ skills/gitlink-pr-integrator/SKILL.md | 30 ++++++ .../examples/executive-integration.md | 19 ++++ skills/gitlink-pr-topology/SKILL.md | 29 +++++ .../examples/executive-queue.md | 22 ++++ skills/gitlink-shared/SKILL.md | 2 + .../examples/maintenance-report.fixture.json | 20 ++++ .../examples/validate-maintenance-report.ps1 | 22 ++++ .../references/maintenance-report-contract.md | 100 ++++++++++++++++++ .../references/security-review-matrix.md | 25 +++++ 17 files changed, 457 insertions(+), 1 deletion(-) create mode 100644 skills/gitlink-cli-contract-guard/examples/executive-contract-gate.md create mode 100644 skills/gitlink-code-review/examples/executive-review.md create mode 100644 skills/gitlink-maintainer-radar/examples/executive-duty-board.md create mode 100644 skills/gitlink-pr-integrator/examples/executive-integration.md create mode 100644 skills/gitlink-pr-topology/examples/executive-queue.md create mode 100644 skills/gitlink-shared/examples/maintenance-report.fixture.json create mode 100644 skills/gitlink-shared/examples/validate-maintenance-report.ps1 create mode 100644 skills/gitlink-shared/references/maintenance-report-contract.md create mode 100644 skills/gitlink-shared/references/security-review-matrix.md diff --git a/skills/README.md b/skills/README.md index ab395e6..0912b3c 100644 --- a/skills/README.md +++ b/skills/README.md @@ -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) - 搜索命令 diff --git a/skills/gitlink-cli-contract-guard/SKILL.md b/skills/gitlink-cli-contract-guard/SKILL.md index 8675483..558b673 100644 --- a/skills/gitlink-cli-contract-guard/SKILL.md +++ b/skills/gitlink-cli-contract-guard/SKILL.md @@ -1,6 +1,11 @@ --- 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" --- # gitlink-cli-contract-guard @@ -19,6 +24,31 @@ 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 契约审查摘要 +**结论：** 阻断合并 **[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 的职责： 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 index 42f7ca2..57245d8 100644 --- 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 @@ -32,7 +32,7 @@ Agent 平台：Codex - `git diff --name-status origin/master...HEAD`：确认仅 skill 文档和图片资产变更。 - `git diff --check origin/master...HEAD`：通过。 -- `rg "�|锛|鈥|Ã|Â|绠|璇|涓|馃"`：未命中新增/修改文本。 +- `rg "锛|鈥|Ã|Â|绠|璇|涓"`：未命中新增/修改文本。 - `go test ./cmd/... ./shortcuts/...`：通过。 ### 低风险备注 diff --git a/skills/gitlink-cli-contract-guard/examples/executive-contract-gate.md b/skills/gitlink-cli-contract-guard/examples/executive-contract-gate.md new file mode 100644 index 0000000..6aeab57 --- /dev/null +++ b/skills/gitlink-cli-contract-guard/examples/executive-contract-gate.md @@ -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 契约审查摘要 +**结论：** 阻断合并 **[blocked]** +**门禁：** 参数通过 | 帮助通过 | JSON 失败 | 错误提示通过 | 安全未验证 + +## 先做这 2 件事 +1. **[CG-001][blocking] 修复** JSON 输出中的调试文本，并补结构化断言。 +2. **[CG-002][high] 验证** `--header` 的换行、引号和敏感值脱敏边界。 +``` + +关键回归至少覆盖旧 flag、默认值、帮助、成功 JSON、错误 JSON、退出码、中文 UTF-8、`NO_COLOR` 和恶意输入；不要只以进程返回 0 作为通过依据。 diff --git a/skills/gitlink-code-review/SKILL.md b/skills/gitlink-code-review/SKILL.md index e43b0ab..3345c85 100644 --- a/skills/gitlink-code-review/SKILL.md +++ b/skills/gitlink-code-review/SKILL.md @@ -16,6 +16,35 @@ 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 # 代码审查摘要 +**结论：** 需要修改 **[action_required]** +**安全门禁：** 未通过 | **验证：** 部分完成 +**问题：** 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 提供一套完整的 AI 驱动代码审查工作流，覆盖从获取 PR 变更到生成审查报告的全过程。不需要额外的 CLI Shortcuts——现有 `gitlink-cli` 命令 + AI Agent 的分析能力即可完成。 diff --git a/skills/gitlink-code-review/examples/executive-review.md b/skills/gitlink-code-review/examples/executive-review.md new file mode 100644 index 0000000..6aee589 --- /dev/null +++ b/skills/gitlink-code-review/examples/executive-review.md @@ -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 代码审查摘要 +**结论：** 需要补验证 **[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 或敏感值。 diff --git a/skills/gitlink-maintainer-radar/SKILL.md b/skills/gitlink-maintainer-radar/SKILL.md index 7f34682..0bdfc20 100644 --- a/skills/gitlink-maintainer-radar/SKILL.md +++ b/skills/gitlink-maintainer-radar/SKILL.md @@ -1,6 +1,11 @@ --- 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" --- # gitlink-maintainer-radar @@ -17,6 +22,33 @@ 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 +# 维护者值班摘要 +**结论：** 今日需处理 **[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。 + ## 核心能力 ### 1. 响应时效雷达 diff --git a/skills/gitlink-maintainer-radar/examples/executive-duty-board.md b/skills/gitlink-maintainer-radar/examples/executive-duty-board.md new file mode 100644 index 0000000..fa90e03 --- /dev/null +++ b/skills/gitlink-maintainer-radar/examples/executive-duty-board.md @@ -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//messages.json --query "status=1&limit=40" --format json +``` + +```markdown +# 维护者值班摘要 +**结论：** 今日需处理 **[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 都要原样标出。 diff --git a/skills/gitlink-pr-integrator/SKILL.md b/skills/gitlink-pr-integrator/SKILL.md index 7e48efe..b334b2e 100644 --- a/skills/gitlink-pr-integrator/SKILL.md +++ b/skills/gitlink-pr-integrator/SKILL.md @@ -1,6 +1,11 @@ --- 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" --- # gitlink-pr-integrator @@ -15,6 +20,31 @@ 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 # 集成摘要 +**结论：** 需补验证 **[action_required]** +**门禁：** 合并态通过 | 构建通过 | 测试未执行 | 安全未验证 | 冲突低 + +## 先做这 2 件事 +1. **[IN-001][high] 验证** `go test ./...`（责任：作者/维护者确认命令）。 +2. **[IN-002][high] 复查** `internal/auth/` 的权限边界（责任：reviewer）。 +``` + +只有六项门禁全部有充分证据且无 `blocking/high` 未解决项，才可使用 `merge`。大型 PR 先做文件/目录重叠和安全热点筛选，只有高风险候选才进入独立 worktree 的完整合并验证，避免批量扫描浪费维护者时间。 + ## Windows 前置 如果你在 Windows PowerShell 里运行或落盘报告，先执行： diff --git a/skills/gitlink-pr-integrator/examples/executive-integration.md b/skills/gitlink-pr-integrator/examples/executive-integration.md new file mode 100644 index 0000000..8573688 --- /dev/null +++ b/skills/gitlink-pr-integrator/examples/executive-integration.md @@ -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 集成摘要 +**结论：** 可进入合并队列 **[merge]** +**门禁：** 合并态通过 | 构建通过 | 测试通过 | 契约通过 | 安全通过 | 冲突低 + +## 需要记录的动作 +1. **[IN-001][low] 更新** 发布说明（责任：维护者）。 +``` + +如果构建、测试或安全门禁是 `not_run`，结论必须降级为 `action_required` 或 `blocked`。高风险 PR 需要在独立 worktree 中验证，且报告记录真实 base、head 和命令。 diff --git a/skills/gitlink-pr-topology/SKILL.md b/skills/gitlink-pr-topology/SKILL.md index 5db00cd..b7dd973 100644 --- a/skills/gitlink-pr-topology/SKILL.md +++ b/skills/gitlink-pr-topology/SKILL.md @@ -1,6 +1,11 @@ --- 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" --- # gitlink-pr-topology @@ -21,6 +26,30 @@ 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 队列关系摘要 +**结论：** 需要重排 **[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 的职责： diff --git a/skills/gitlink-pr-topology/examples/executive-queue.md b/skills/gitlink-pr-topology/examples/executive-queue.md new file mode 100644 index 0000000..3306ec7 --- /dev/null +++ b/skills/gitlink-pr-topology/examples/executive-queue.md @@ -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 --format json +gitlink-cli pr +diff --owner Gitlink --repo gitlink-cli --id --format json +``` + +```markdown +# PR 队列关系摘要 +**结论：** 需要重排 **[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 或测试证据。 diff --git a/skills/gitlink-shared/SKILL.md b/skills/gitlink-shared/SKILL.md index 858a827..d5a0684 100644 --- a/skills/gitlink-shared/SKILL.md +++ b/skills/gitlink-shared/SKILL.md @@ -10,6 +10,8 @@ metadata: # gitlink-cli 共享规则 +维护者类 Skill 的报告协议见 [`references/maintenance-report-contract.md`](references/maintenance-report-contract.md)，安全检查见 [`references/security-review-matrix.md`](references/security-review-matrix.md)。生成报告时先给执行摘要，再提供可追溯的证据附录；JSON 不得混入展示层样式。 + 本技能指导你如何通过 gitlink-cli 操作 GitLink 平台资源。 ## 认证 diff --git a/skills/gitlink-shared/examples/maintenance-report.fixture.json b/skills/gitlink-shared/examples/maintenance-report.fixture.json new file mode 100644 index 0000000..b73e439 --- /dev/null +++ b/skills/gitlink-shared/examples/maintenance-report.fixture.json @@ -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 结果未提供"] +} diff --git a/skills/gitlink-shared/examples/validate-maintenance-report.ps1 b/skills/gitlink-shared/examples/validate-maintenance-report.ps1 new file mode 100644 index 0000000..89a6d3f --- /dev/null +++ b/skills/gitlink-shared/examples/validate-maintenance-report.ps1 @@ -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\[|") { throw "JSON contains presentation markers" } +if ($raw.Contains([char]0xfffd)) { throw "JSON contains UTF-8 replacement character" } + +Write-Output "maintenance report contract passed: $Path" diff --git a/skills/gitlink-shared/references/maintenance-report-contract.md b/skills/gitlink-shared/references/maintenance-report-contract.md new file mode 100644 index 0000000..2f97a13 --- /dev/null +++ b/skills/gitlink-shared/references/maintenance-report-contract.md @@ -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 +阻断 **[blocking]** #CR-001 +高风险 **[high]** #CR-002 +通过 **[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\[|") { 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 替换字符和已知乱码片段，并记录例外。 diff --git a/skills/gitlink-shared/references/security-review-matrix.md b/skills/gitlink-shared/references/security-review-matrix.md new file mode 100644 index 0000000..3a3f388 --- /dev/null +++ b/skills/gitlink-shared/references/security-review-matrix.md @@ -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。发现疑似真实密钥时不要复制到报告，报告只保留类型、位置和轮换建议。 -- 2.34.1 From 23a5ed48415d861700c312bc75ca20824f42ee0b Mon Sep 17 00:00:00 2001 From: Mengz <2567587994@qq.com> Date: Mon, 20 Jul 2026 15:47:24 +0800 Subject: [PATCH 2/4] =?UTF-8?q?=E6=98=8E=E7=A1=AE=E4=BA=94=E4=B8=AA?= =?UTF-8?q?=E7=BB=B4=E6=8A=A4=20Skill=20=E7=9A=84=E8=81=8C=E8=B4=A3?= =?UTF-8?q?=E8=BE=B9=E7=95=8C=E4=B8=8E=E5=8D=8F=E5=90=8C=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 | 4 + skills/gitlink-code-review/SKILL.md | 4 + skills/gitlink-maintainer-radar/SKILL.md | 4 + skills/gitlink-pr-integrator/SKILL.md | 4 + skills/gitlink-pr-topology/SKILL.md | 4 + skills/gitlink-shared/SKILL.md | 2 +- .../references/skill-scope-and-handoff.md | 81 +++++++++++++++++++ 7 files changed, 102 insertions(+), 1 deletion(-) create mode 100644 skills/gitlink-shared/references/skill-scope-and-handoff.md diff --git a/skills/gitlink-cli-contract-guard/SKILL.md b/skills/gitlink-cli-contract-guard/SKILL.md index 558b673..19fb1ec 100644 --- a/skills/gitlink-cli-contract-guard/SKILL.md +++ b/skills/gitlink-cli-contract-guard/SKILL.md @@ -49,6 +49,10 @@ metadata: 关键验证至少包括：旧命令和默认值、`--help`、正常 JSON、错误 JSON、退出码、中文 UTF-8、`NO_COLOR`、敏感值脱敏和恶意边界输入。使用 golden/snapshot 或等价结构化断言，避免只检查命令返回 0。 +## 职责边界与组合协同 + +独立运行时，本 Skill 只判断 CLI 用户契约是否保持兼容，不评价业务功能价值、通用代码质量或维护者队列优先级。组合运行时向 `gitlink-pr-integrator` 交接 `CG-xxx` 契约门禁；与 `gitlink-code-review` 同时命中安全问题时，保留 CLI 边界证据并通过 `related_ids` 关联代码层发现，避免重复催办。 + ## 不覆盖的内容 下面这些不属于这个 skill 的职责： diff --git a/skills/gitlink-code-review/SKILL.md b/skills/gitlink-code-review/SKILL.md index 3345c85..46281ea 100644 --- a/skills/gitlink-code-review/SKILL.md +++ b/skills/gitlink-code-review/SKILL.md @@ -45,6 +45,10 @@ metadata: 安全发现使用 `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 的分析能力即可完成。 diff --git a/skills/gitlink-maintainer-radar/SKILL.md b/skills/gitlink-maintainer-radar/SKILL.md index 0bdfc20..285af7a 100644 --- a/skills/gitlink-maintainer-radar/SKILL.md +++ b/skills/gitlink-maintainer-radar/SKILL.md @@ -49,6 +49,10 @@ metadata: 如果没有 open PR 或 open Issue，明确报告“没有可分析的 open PR/Issue”；如果消息接口失败，不得用通知列表代替协作队列，也不得伪造 SLA。 +## 职责边界与组合协同 + +独立运行时，本 Skill 只分析响应时效、reviewer 负载、责任停滞和队列变化，不判断代码是否有漏洞、不评价 CLI 契约，也不决定 PR 是否可合并。组合运行时读取 `CR-xxx`、`CG-xxx`、`TP-xxx` 和 `IN-xxx` 的状态，只将它们转换为维护动作 `MR-xxx`；一个安全发现只提升优先级，不在本 Skill 中重新宣称漏洞成立。 + ## 核心能力 ### 1. 响应时效雷达 diff --git a/skills/gitlink-pr-integrator/SKILL.md b/skills/gitlink-pr-integrator/SKILL.md index b334b2e..41e62b6 100644 --- a/skills/gitlink-pr-integrator/SKILL.md +++ b/skills/gitlink-pr-integrator/SKILL.md @@ -45,6 +45,10 @@ metadata: 只有六项门禁全部有充分证据且无 `blocking/high` 未解决项，才可使用 `merge`。大型 PR 先做文件/目录重叠和安全热点筛选，只有高风险候选才进入独立 worktree 的完整合并验证，避免批量扫描浪费维护者时间。 +## 职责边界与组合协同 + +独立运行时，本 Skill 只判断一个 PR 是否具备进入合并队列的条件；它不重新做完整代码审查、不判断 PR 之间的替代关系，也不按 SLA 排维护者任务。组合运行时读取 `CR-xxx`、`CG-xxx` 和 `TP-xxx` 结果，使用 `IN-xxx` 记录集成阻断和门禁，不改写专项发现。安全专项未运行时，安全门禁必须保持 `not_run`，不能因构建通过而推断安全通过。 + ## Windows 前置 如果你在 Windows PowerShell 里运行或落盘报告，先执行： diff --git a/skills/gitlink-pr-topology/SKILL.md b/skills/gitlink-pr-topology/SKILL.md index b7dd973..9c7621b 100644 --- a/skills/gitlink-pr-topology/SKILL.md +++ b/skills/gitlink-pr-topology/SKILL.md @@ -50,6 +50,10 @@ metadata: 先按标题、issue、改动文件和目录做低成本候选筛选，再对候选关系读取 diff、review 和测试证据；不要对所有 PR 做完整笛卡尔积分析。 +## 职责边界与组合协同 + +独立运行时，本 Skill 只判断多个 open PR 之间的关系，不判断单条 PR 的代码缺陷、契约通过与否或维护者响应是否超时。组合运行时向 `gitlink-pr-integrator` 交接 `TP-xxx` 关系和建议顺序，向 `gitlink-maintainer-radar` 交接冲突热点和待处理簇；`security_hotspot` 只表示需要安全复查，不等同于已确认漏洞。 + ## 不覆盖的内容 下面这些不属于本 skill 的职责： diff --git a/skills/gitlink-shared/SKILL.md b/skills/gitlink-shared/SKILL.md index d5a0684..d5b6d87 100644 --- a/skills/gitlink-shared/SKILL.md +++ b/skills/gitlink-shared/SKILL.md @@ -10,7 +10,7 @@ metadata: # gitlink-cli 共享规则 -维护者类 Skill 的报告协议见 [`references/maintenance-report-contract.md`](references/maintenance-report-contract.md)，安全检查见 [`references/security-review-matrix.md`](references/security-review-matrix.md)。生成报告时先给执行摘要，再提供可追溯的证据附录；JSON 不得混入展示层样式。 +维护者类 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 平台资源。 diff --git a/skills/gitlink-shared/references/skill-scope-and-handoff.md b/skills/gitlink-shared/references/skill-scope-and-handoff.md new file mode 100644 index 0000000..b375d5e --- /dev/null +++ b/skills/gitlink-shared/references/skill-scope-and-handoff.md @@ -0,0 +1,81 @@ +# 五个维护 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 中出现，但检查对象不同，不能重复输出同一条泛化结论： + +- `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` 只能引用专项发现，不能重写专项发现的技术结论。 -- 2.34.1 From e16cfeb7473dec1c448941fd7de4b66b71d513c3 Mon Sep 17 00:00:00 2001 From: Mengz <2567587994@qq.com> Date: Mon, 20 Jul 2026 15:48:39 +0800 Subject: [PATCH 3/4] =?UTF-8?q?=E5=AE=8C=E5=96=84=E7=BB=B4=E6=8A=A4=20Skil?= =?UTF-8?q?l=20=E7=9A=84=E9=87=8D=E5=8F=A0=E8=BE=B9=E7=95=8C=E4=B8=8E?= =?UTF-8?q?=E4=B8=8D=E5=8F=AF=E6=9B=BF=E4=BB=A3=E8=81=8C=E8=B4=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/gitlink-shared/SKILL.md | 2 +- .../references/skill-scope-and-handoff.md | 21 ++++++++++++++++++- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/skills/gitlink-shared/SKILL.md b/skills/gitlink-shared/SKILL.md index d5b6d87..ddc227c 100644 --- a/skills/gitlink-shared/SKILL.md +++ b/skills/gitlink-shared/SKILL.md @@ -10,7 +10,7 @@ metadata: # 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 不得混入展示层样式。 +维护者类 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 平台资源。 diff --git a/skills/gitlink-shared/references/skill-scope-and-handoff.md b/skills/gitlink-shared/references/skill-scope-and-handoff.md index b375d5e..5b7599e 100644 --- a/skills/gitlink-shared/references/skill-scope-and-handoff.md +++ b/skills/gitlink-shared/references/skill-scope-and-handoff.md @@ -4,7 +4,7 @@ ## 职责矩阵 -| 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` 契约门禁和兼容性结论 | @@ -12,6 +12,25 @@ | `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 中出现，但检查对象不同，不能重复输出同一条泛化结论： -- 2.34.1 From cf784aadfd2169b15e15c4b999db5a7848b57913 Mon Sep 17 00:00:00 2001 From: Mengz <2567587994@qq.com> Date: Mon, 20 Jul 2026 16:27:12 +0800 Subject: [PATCH 4/4] =?UTF-8?q?feat(skills):=20=E6=8E=A5=E5=85=A5=20PR=20?= =?UTF-8?q?=E8=AF=81=E6=8D=AE=E5=8C=85=E4=B8=8E=E9=98=9F=E5=88=97=E5=B7=AE?= =?UTF-8?q?=E5=BC=82=E8=83=BD=E5=8A=9B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/gitlink-cli-contract-guard/SKILL.md | 12 +++++ skills/gitlink-code-review/SKILL.md | 10 ++++ skills/gitlink-maintainer-radar/SKILL.md | 11 +++++ skills/gitlink-pr-integrator/SKILL.md | 10 ++++ skills/gitlink-pr-topology/SKILL.md | 11 +++++ skills/gitlink-shared/SKILL.md | 2 + .../maintenance-evidence-workflow.md | 49 +++++++++++++++++++ 7 files changed, 105 insertions(+) create mode 100644 skills/gitlink-shared/references/maintenance-evidence-workflow.md diff --git a/skills/gitlink-cli-contract-guard/SKILL.md b/skills/gitlink-cli-contract-guard/SKILL.md index 19fb1ec..bc3401d 100644 --- a/skills/gitlink-cli-contract-guard/SKILL.md +++ b/skills/gitlink-cli-contract-guard/SKILL.md @@ -8,6 +8,18 @@ metadata: 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)。** diff --git a/skills/gitlink-code-review/SKILL.md b/skills/gitlink-code-review/SKILL.md index 46281ea..460ef07 100644 --- a/skills/gitlink-code-review/SKILL.md +++ b/skills/gitlink-code-review/SKILL.md @@ -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 --repo --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 注意事项。** diff --git a/skills/gitlink-maintainer-radar/SKILL.md b/skills/gitlink-maintainer-radar/SKILL.md index 285af7a..02b8876 100644 --- a/skills/gitlink-maintainer-radar/SKILL.md +++ b/skills/gitlink-maintainer-radar/SKILL.md @@ -8,6 +8,17 @@ metadata: 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 --repo --previous queue-previous.json --format json +gitlink-cli workflow +review-context --owner --repo --number --include-ci=true --format json +``` + +本 Skill 只负责 SLA、Reviewer 负载、责任停滞和今日待办；`risk_changed` 是提醒信号，不直接宣称代码存在漏洞或阻断合并。 + # gitlink-maintainer-radar **CRITICAL - 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，按其中的认证、全局参数和安全规则执行。** diff --git a/skills/gitlink-pr-integrator/SKILL.md b/skills/gitlink-pr-integrator/SKILL.md index 41e62b6..0cc597b 100644 --- a/skills/gitlink-pr-integrator/SKILL.md +++ b/skills/gitlink-pr-integrator/SKILL.md @@ -8,6 +8,16 @@ metadata: cliHelp: "gitlink-cli pr --help" --- +## 已合并功能的增量证据 + +前置 PR #426 合并后，先复用统一 PR 证据包，再进入本 Skill 的独立 worktree 验证。重点读取 `commits`、`ci_builds`、`sections` 和 `notes`，将 CI 状态与本地构建、测试结果一起纳入集成门禁： + +```bash +gitlink-cli workflow +review-context --owner --repo --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)。** diff --git a/skills/gitlink-pr-topology/SKILL.md b/skills/gitlink-pr-topology/SKILL.md index 9c7621b..75581cd 100644 --- a/skills/gitlink-pr-topology/SKILL.md +++ b/skills/gitlink-pr-topology/SKILL.md @@ -8,6 +8,17 @@ metadata: cliHelp: "gitlink-cli pr --help" --- +## 已合并功能的增量证据 + +前置 PR #426 提供统一的 PR 文件、提交和 Review 证据；前置 PR #427 提供队列变化。拓扑分析可以先取一次队列快照，再为候选关系补取证据，减少对整条 open PR 队列的重复请求： + +```bash +gitlink-cli workflow +review-queue --owner --repo --previous queue-previous.json --format json +gitlink-cli workflow +review-context --owner --repo --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)。** diff --git a/skills/gitlink-shared/SKILL.md b/skills/gitlink-shared/SKILL.md index ddc227c..f630fa0 100644 --- a/skills/gitlink-shared/SKILL.md +++ b/skills/gitlink-shared/SKILL.md @@ -8,6 +8,8 @@ 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 不得混入展示层样式。 diff --git a/skills/gitlink-shared/references/maintenance-evidence-workflow.md b/skills/gitlink-shared/references/maintenance-evidence-workflow.md new file mode 100644 index 0000000..3d329c7 --- /dev/null +++ b/skills/gitlink-shared/references/maintenance-evidence-workflow.md @@ -0,0 +1,49 @@ +# 维护 Skill 证据工作流 + +这份协议把五个维护 Skill 的输入分成两层：单个 PR 的证据包，以及 open PR 队列的变化快照。它们是基础数据，不是新的“总控 Skill”；每个 Skill 仍然只对自己的职责给出结论。 + +## 单个 PR 证据包 + +前置 PR #426 合并后，优先使用以下只读命令： + +```bash +gitlink-cli workflow +review-context \ + --owner --repo --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 --repo --format json > queue-previous.json + +gitlink-cli workflow +review-queue \ + --owner --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`，不能用默认值填充成功结论。 -- 2.34.1