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