3.4 KiB

Raw Blame History

维护 Skill 运行协议

本协议把五个 Skill 从“一次性生成文字”约束为可重复、可追溯、可安全自动运行的维护流水线。它不改变五个 Skill 的职责，只规定共同的运行输入、证据、刷新和自动化边界。

运行标识与幂等

每次运行生成稳定键：

<producer>:<owner>/<repo>:<pr-number-or-queue>:<head-sha-or-snapshot>:<mode>

相同稳定键不得重复发布报告或重复评论。PR 在新 commit、Review 状态变化、CI 结果变化或维护者明确要求复查时，才创建新的运行键。队列扫描使用快照时间和队列内容摘要作为版本，不使用当前时间单独去重。

最小运行上下文

{
  "run": {
    "run_id": "gitlink-code-review: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 中登记：

{
  "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、contract_test、integration_test、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”评论：

当前运行键没有已发布报告。
PR 仍为 open，证据状态为 complete，且报告明确标出扫描范围和时间。
没有 blocking 或未确认的高风险安全发现。
评论只包含事实、证据和补充建议，不包含自动合并、关闭、拒绝或强制分配动作。

任一条件不满足时，只生成本地报告或评论草稿。任何 Skill 都不得自动合并、关闭 PR、修改权限、处理真实凭据或把未知状态写成通过。

3.4 KiB Raw Blame History Unescape Escape