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] =?UTF-8?q?=E5=AE=8C=E5=96=84=E7=BB=B4=E6=8A=A4=E8=80=85?= =?UTF-8?q?=E5=AE=A1=E6=9F=A5=20Skills=20=E7=9A=84=E6=8A=A5=E5=91=8A?= =?UTF-8?q?=E6=95=88=E7=8E=87=E4=B8=8E=E5=AE=89=E5=85=A8=E9=97=A8=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。发现疑似真实密钥时不要复制到报告，报告只保留类型、位置和轮换建议。