4.1 KiB

Raw Blame History

维护 Skill 证据工作流

这份协议把五个维护 Skill 的输入分成两层：单个 PR 的证据包，以及 open PR 队列的变化快照。它们是基础数据，不是新的“总控 Skill”；每个 Skill 仍然只对自己的职责给出结论。

单个 PR 证据包

配套 PR #429 合并后可优先使用以下只读命令；未合并或命令不可用时回退到现有 PR 只读接口，并把缺失字段标记为 not_run/partial：

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，不能把缺失数据写成“通过”。已有调用不传新增开关时保持原行为。

CI 关联规则

当结果包含 ci_summary 时，优先使用 match_mode=sha 的提交匹配；只有 PR 没有可用 head SHA 或 SHA 无匹配时，才接受 match_mode=branch。passed、failed、pending 和 unknown 只统计已匹配构建，unmatched 不能被当作失败或通过。match_mode=none、unavailable 或 sections 缺少 ci_builds 时，相关结论必须标为 not_run/partial。

队列变化快照

配套 PR #430 合并后可保存 JSON 基线并在下一轮比较；未合并时只生成当前队列快照，不得虚构 changes：

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 编号的本地输入只能按规范化标题匹配，报告必须降低置信度。

等待与责任字段

使用 --as-of <RFC3339> 固定报告时点，使用 --stale-after-hours <hours> 设置仓库 SLA。队列项的 age_hours、waiting_hours、stale、review_state、reviewers、reviewer_count 和 waiting_on 用于生成维护动作；waiting_on 只有在 review 状态明确时才归属 author、reviewer 或 maintainer，未知状态必须保留为空。

五个 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 参数、帮助、输出、错误和编码契约

贡献价值和声明可行性由 gitlink-code-review 与 gitlink-pr-integrator 独立保留，不依赖未合并的 assessor。

组合运行规则

先获取一次证据包和队列快照，后续 Skill 通过 sections、notes 和 changes 判断证据完整性。
单独运行某个 Skill 时只读取它需要的字段，并把其他维度标记为未纳入本次检查。
组合运行时允许共享事实和安全信号，但发现编号必须保留各自前缀：CR-、IN-、TP-、MR-、CG-。
同一事实可以被多个 Skill 引用，但只能由负责该维度的 Skill 生成最终动作；例如 CI 失败可以被代码审查引用，却只能由集成 Skill 决定是否形成合并阻断。
任何探针失败、CI 未匹配或快照缺失都输出 not_run/partial，不能用默认值填充成功结论。

4.1 KiB Raw Blame History Unescape Escape