26 KiB
| name | description |
|---|---|
| gitlink-pr-integrator | GitLink PR 价值与集成验证:评估贡献价值及其详细依据,并检查当前 head 对最新主线的合并态、构建、测试、契约、安全、冲突与发布影响,生成结论前置、带 IN 编号和可追溯证据的只读 Markdown 报告。用户只需点名 gitlink-pr-integrator 并提供一个或多个 PR;默认独立运行、不调用其他 Skill、不评论或合并远端。 |
已合并功能的增量证据
配套基础能力 PR #429 合并后可复用统一 PR 证据包,再进入本 Skill 的独立 worktree 验证。#429 未合并或命令不可用时必须回退到现有只读接口并标记限制,不能假定证据包已经存在。重点读取 commits、ci_builds、sections 和 notes:
gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <number> --include-commits=true --include-ci=true --format json
本 Skill 独立评估贡献价值,并负责合并态、构建、测试、契约、安全、冲突和发布影响。配套 PR #430 可提供 changes;#430 未合并时继续使用现有队列接口。队列变化只能作为价值和排序证据,不能跳过仓库现状核对或本地验证。
CI 门禁必须读取 ci_summary:match_mode=sha 优先,branch 只能作为回退;matched=0 时 CI 为 not_run,不能给出 ready_to_merge。只要匹配构建中存在 failed,集成结论至少为 action_required;unmatched 构建只进入限制说明。队列的 waiting_on 仅用于安排下一动作,不改变合并门禁。
gitlink-pr-integrator
CRITICAL - 开始前先阅读 ../gitlink-shared/SKILL.md。
CRITICAL - GitLink 平台数据采集和回写只使用 gitlink-cli,不要改用 gh 或其他平台 CLI。
CRITICAL - 默认只做读取、验证和报告;只有用户明确要求时才回写评论或 review。
CRITICAL - 不要在用户当前的脏工作树里做合并验证。优先使用独立 worktree、临时 clone 或明确指定的检出目录。
CRITICAL - 在 Codex 中优先使用 apply_patch 写中文报告;不要通过 Windows PowerShell 5.1 here-string/变量管道写入,否则中文可能永久变成 ?。
默认调用契约
用户只需说“使用 gitlink-pr-integrator 检查 <owner>/<repo> 的 PR #<number>”;多个 PR 可直接列出多个编号。除非目标或验证环境无法确定,不要求用户重复说明门禁、只读边界或报告路径。
点名后默认自动执行:
- 独立判断贡献价值和集成就绪度,不调用其他 Skill;不重新做完整代码审查,不输出完整 PR 替代图谱,也不判断维护者 SLA。
- 只读远端;允许在隔离 worktree 中执行本地验证,但不评论、不 approve、不合并、不关闭、不修改远端。
- 使用
IN-001起的稳定编号,记录门禁、当前 head SHA、命令、退出码、证据、下一动作和限制。 - 聊天和报告首屏按 PR 分节,将贡献价值、合并态、构建、测试、契约、安全与发布、集成结论分别做成判断卡;每张卡先显示醒目结论,再写解释、
依据:和影响/下一步。 - 一次运行只生成一份 UTF-8 Markdown,保存到
reports/skill-runs/gitlink-pr-integrator/<owner>-<repo>-<scope>-<yyyyMMdd-HHmmssZ>.md;多个 PR 先给队列摘要,再分别给每条 PR 的门禁。
最终回复复用报告首屏的逐 PR 七方面判断卡,再给报告绝对路径;不得把多个 PR 或多个门禁压成一段。无法写入工作区时输出完整 Markdown 并标记“未落盘”。
首屏固定先使用:
# PR 集成摘要
## PR #<number>
**贡献价值:** <span style="color:#067647"><strong>值得进入社区</strong></span> **[passed]**:消除维护者手工关联构建步骤;依据:默认分支无等价命令、需求与受益范围;影响:降低日常操作成本。
**合并态:** <span style="color:#067647"><strong>可干净应用到最新主线</strong></span> **[passed]**:当前 head 没有文本冲突;依据:固定 head/base SHA 与隔离 worktree 合并结果;影响:无合并阻断。
**构建:** <span style="color:#067647"><strong>构建通过</strong></span> **[passed]**:仓库构建命令退出码为 0;依据:当前 head 的命令、时间和日志摘要;影响:编译链路可用。
**测试:** <span style="color:#B54708"><strong>全量测试尚未执行</strong></span> **[not_run]**:只有专项测试证据;依据:测试账本缺少 `go test ./...`;下一步:补全量测试。
**契约:** <span style="color:#B54708"><strong>兼容证据不完整</strong></span> **[partial]**:新输出字段尚未覆盖旧调用;依据:帮助与 JSON 对照缺口;下一步:补兼容回归。
**安全与发布:** <span style="color:#B54708"><strong>安全边界尚未验证</strong></span> **[not_run]**:涉及权限路径但未运行边界测试;依据:Diff 安全矩阵与测试账本;下一步:补无权和恶意输入验证。
**集成结论:** <span style="color:#B54708"><strong>补齐测试和安全后再集成</strong></span> **[action_required]**:价值成立但证据门禁不完整;依据:IN-001、IN-002 与上述门禁;下一步:完成验证后重新运行。
## 先处理这 2 项
1. <span style="color:#B54708"><strong>[IN-001][high] 验证</strong></span> `go test ./...`;责任:作者。
2. <span style="color:#B54708"><strong>[IN-002][high] 复查</strong></span> 权限边界;责任:reviewer。
这个 Skill 同时回答“这个贡献是否值得进入社区”和“当前实现能否安全并入主线”。价值判断必须有仓库事实、需求和差异证据,不能根据标题、代码量、作者身份或主观新颖感下结论。完整代码缺陷审查仍不在本 Skill 内重复执行,但集成验证中发现的明确阻断问题必须记录并影响结论。
执行命令前,按需读取 references/api_reference.md。其中包含 GitLink CLI 命令、Windows 调用方式、独立 worktree 验证方法和报告字段约定。
每次运行记录目标、baseline SHA、采集时间、合并结果、执行命令、退出码和证据缺口;默认只读,不评论、不合并、不关闭或修改远端对象。
效率版集成门禁
先回答“现在能否进入 merge queue”,再展开证据。首屏只保留:
decision:merge、action_required或blocked- 贡献价值、合并态、构建、测试、契约、安全和冲突七个门禁
- 最多 5 项下一动作,明确等待作者、reviewer、维护者还是平台
- 仅列会改变排序的冲突和影响面,其余放附录
若 PR 修改认证、权限、命令执行、文件路径、webhook、依赖或敏感输出,安全门禁至少为 not_run,不能直接给出 ready_to_merge。至少核对凭据泄露、命令注入、路径遍历、权限边界、外连、依赖来源和敏感输出;安全验证、构建和测试都要分别记录 passed / failed / not_run。
推荐的首屏格式:
# PR 集成摘要
## PR #<number>
**贡献价值:** <span style="color:#067647"><strong>价值成立</strong></span> **[passed]**:解决高频维护问题;依据:需求、默认分支差异和受益范围;影响:减少重复操作。
**合并态:** <span style="color:#067647"><strong>当前无冲突</strong></span> **[passed]**:head 可应用到 baseline;依据:隔离 worktree 合并;影响:无文本阻断。
**构建:** <span style="color:#067647"><strong>构建通过</strong></span> **[passed]**:仓库构建成功;依据:当前 SHA 的命令和退出码;影响:编译可用。
**测试:** <span style="color:#B54708"><strong>测试未执行</strong></span> **[not_run]**:没有全量结果;依据:验证账本为空;下一步:运行仓库测试。
**契约:** <span style="color:#175CD3"><strong>仅部分验证</strong></span> **[partial]**:旧调用仍需确认;依据:帮助和 JSON 对照;下一步:补兼容测试。
**安全与发布:** <span style="color:#B54708"><strong>边界未验证</strong></span> **[not_run]**:权限输入缺证据;依据:安全矩阵与测试缺口;下一步:执行安全场景。
**集成结论:** <span style="color:#B54708"><strong>补齐验证后再进入队列</strong></span> **[action_required]**:关键门禁不完整;依据:IN-001、IN-002;下一步:完成后重跑。
## 先做这 2 件事
1. **[IN-001][high] 验证** `go test ./...`(责任:作者/维护者确认命令)。
2. **[IN-002][high] 复查** `internal/auth/` 的权限边界(责任:reviewer)。
保存报告后,严格按 UTF-8 重读,并检查每个目标均有“贡献价值、合并态、构建、测试、契约、安全与发布、集成结论”七张结论前置判断卡;缺少证据、出现连续 ??? 或无法标识验证限制时必须重写,不能交付路径。聊天直接复用逐 PR 七张卡的精炼结论。
只有贡献价值和六项技术门禁都有充分证据且无 blocking/high 未解决项,才可使用 merge。大型 PR 先做价值证据、文件/目录重叠和安全热点筛选,低价值或高度重复候选先交维护者判断,高风险候选再进入独立 worktree 的完整合并验证,避免批量扫描浪费维护者时间。
贡献价值门禁
贡献价值是正式门禁,不依赖其他未安装或未合并的 Skill。先核对仓库事实,再从以下七个方面形成依据:
- 需求真实性:是否有 Issue、用户反馈、现有命令缺口、重复人工步骤、错误记录或文档限制等直接证据。
- 社区适配度:是否符合仓库定位、维护方向、现有架构和公开协作规范,而不是仅对作者私有场景有用。
- 功能增量:相对默认分支、已合并实现和 open PR,具体增加、修复或简化了什么;不得把代码量当成功能价值。
- 使用频率与受益面:是否覆盖常用流程,影响普通用户、维护者、自动化调用方还是极少数边缘场景。
- 实现完整性:代码、失败路径、测试、帮助、文档和兼容处理是否足以交付,而非只有演示路径。
- 维护成本:新增 API、依赖、配置、平台分支、长期兼容和支持成本是否与收益匹配。
- 风险收益比:安全、兼容、性能和回归风险是否可控,是否存在更小且同样有效的实现。
每个维度标记 strong、moderate、weak 或 unknown,并至少引用一个证据 ID。详细价值结论必须回答:解决了什么已证实的问题、比仓库现状多了什么、谁会受益、代价是什么、为什么值得或不值得现在合入。
价值门禁使用:
passed:需求和增量有直接证据,适配社区,交付完整度与维护成本合理。partial:价值方向成立,但重复关系、受益范围、完整性或维护代价仍需确认。failed:有充分证据表明没有有效增量、与仓库定位冲突,或维护风险明显高于收益。not_run:仓库现状、需求来源或相关实现无法获取,不能判断。
价值为 partial 或 not_run 时,机器决策使用协议内的 observe,人读结论显示“需要维护者判断”;价值为 failed 时不得建议进入 merge queue。禁止仅凭 star、作者历史、PR 描述措辞或变更行数给分。
集成验证的刷新与停机规则
集成报告的幂等键必须包含 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 是否具备进入合并队列的条件。为确认功能增量,可以识别明显重复和已存在实现,但不生成完整替代关系图谱;它也不重新做完整代码审查或按 SLA 排维护者任务。组合运行时可读取 CR-xxx、CG-xxx 和 TP-xxx 结果,使用 IN-xxx 记录价值和集成门禁,不改写专项发现。专项结果不存在时必须独立采集价值证据;安全未验证时保持 not_run,不能因构建通过而推断安全通过。
Windows 前置
如果你在 Windows PowerShell 里运行或落盘报告,先执行:
chcp 65001 > $null
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [Console]::OutputEncoding
如果 PowerShell 因执行策略拦截 gitlink-cli.ps1,改用:
& "$env:APPDATA\npm\gitlink-cli.cmd" auth status
如果全局安装版本落后于当前仓库源码,优先在仓库根目录运行:
go run . pr --help
结论集合
最终结论只从下列集合中选择一个:
ready_to_merge:合并态干净,官方构建/测试通过,冲突和发布风险可接受。ready_after_rebase:主要阻塞是基线已漂移,rebase 或重新合并后大概率可继续。ready_after_followups:代码本身接近可合并,但还缺文档、帮助文本、测试、changelog 或发布动作。observe:技术上可能可集成,但贡献价值、重复程度、受益范围或维护成本缺少足够证据,需要维护者决策。not_integration_ready:当前无法安全并入主线,存在冲突、失败验证、较高回归风险或明显的集成阻塞。
同时给出以下评级:
merge_readiness:high/medium/lowcontribution_value:passed/partial/failed/not_runintegration_risk:low/medium/highconflict_risk:low/medium/highrelease_impact:none/patch/minor/major
标准流程
Step 1: 采集 PR 集成上下文
先拿到目标 PR 的元信息、变更范围、已有 review 和仓库默认分支信息。
优先命令:
gitlink-cli pr +view --owner <owner> --repo <repo> --id <pr_number> --format json
gitlink-cli pr +files --owner <owner> --repo <repo> --id <pr_number> --format json
gitlink-cli pr +reviews --owner <owner> --repo <repo> --id <pr_number> --format json
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
gitlink-cli ci +builds --owner <owner> --repo <repo> --format json
至少提取:
- base 分支、head 分支、head 来源仓库
- PR 声明解决的问题、关联 Issue、用户反馈和使用场景
- 变更文件、核心目录、是否涉及 CLI 命令入口、帮助文本、文档、测试
- 当前 review 结论、是否已有 maintainer 明确阻塞项
- 仓库默认分支、语言、CI 是否开启、项目推荐的验证命令
Step 2: 建立贡献价值证据
先检查默认分支、文档、命令帮助、相关 Issue、已合并实现和 open PR,建立“当前仓库已经具有什么、仍缺什么”的基线。然后将 PR 的每项声明映射到具体 Diff、测试和文档,输出七维价值矩阵。
至少形成以下证据:
E-IN-VALUE-01:需求来源或仓库缺口,例如关联 Issue、可复现限制、重复人工步骤或缺失命令。E-IN-VALUE-02:相对默认分支的实际功能增量及对应文件、命令或行为。E-IN-VALUE-03:与已合并实现及 open PR 的重复、互补或差异证据。E-IN-VALUE-04:测试、帮助、文档和失败路径体现的交付完整性。E-IN-VALUE-05:新增依赖、API、配置、兼容层和长期维护成本。E-IN-VALUE-06:受益对象、使用频率依据和风险收益判断。
无法访问 Issue、历史实现或真实使用证据时,将对应维度标记 unknown,不得用 PR 描述补齐。发现疑似重复时可以影响价值门禁,但只有证据充分时才能写“无有效增量”;复杂替代关系应记录为需要维护者进一步比较。
Step 3: 准备独立的集成验证环境
集成验证必须隔离执行。优先顺序如下:
- 用户明确提供的临时检出目录
- 当前仓库下的新 worktree
- 系统临时目录里的新 clone
禁止直接在用户当前脏工作树里 merge 或 rebase。如果仓库里已经有未提交改动,只把它当信息源,不把它当验证环境。
Step 4: 做合并态验证
目标不是只看 PR 自己能不能编译,而是回答“把它并到最新主线后还能不能工作”。
建议流程:
git fetch origin <base_branch>
git worktree add <temp_dir> origin/<base_branch>
cd <temp_dir>
git switch -c pr-integration-check
git remote add pr-source <head_repo_url>
git fetch pr-source <head_branch>
git merge --no-ff --no-commit FETCH_HEAD
如果 PR head 就在同一个远端,也可以直接从 origin/<head_branch> 拉取,不必额外加 remote。
注意 GitLink PR 的 head 字段常见格式是 login/branch。对 fork PR 做本地验证时,不要机械地把它裁成最后一段;如果你的 remote 名就叫这个 login,那么实际 remote-tracking ref 可能是 refs/remotes/<login>/<head>,例如 refs/remotes/mengz/mengz/api-single-call-templates。
记录下列结果:
- 是否无冲突完成 merge
- 是否必须 rebase 才能继续
- 官方构建命令是否通过
- 官方测试命令是否通过
- 是否出现只在合并态暴露的问题,例如接口签名漂移、帮助文本未同步、测试夹具过时、文档示例失效
验证命令必须优先使用项目文档、CI 配置、Makefile 或仓库惯例,不要发明一套项目从未使用过的检查方式。
Step 5: 扫描与其他 open PR 的冲突风险
集成就绪度不是单 PR 视角,还要考虑队列里的其他候选项。
先列出 open PR:
gitlink-cli pr +list --owner <owner> --repo <repo> --state open --page 1 --limit 50 --format json
然后重点比较:
- 是否修改同一文件
- 是否落在同一目录或模块
- 是否同时修改同一条 CLI 命令、flag、帮助文案或 API 包装层
- 是否会产生相互覆盖的测试或快照
冲突评级建议:
high:同文件或同命令入口直接重叠,合并顺序明显重要medium:目录或模块重叠,存在行为级联风险low:基本独立,只存在轻微上下文漂移可能
如果发现明显的先后依赖,给出建议合并顺序。
Step 6: 输出集成影响矩阵
不要只写“测试通过”。要明确主线在什么面上会被改变。
至少覆盖以下面向:
- CLI 命令行为
- flags / help 输出
- README / docs / 示例
- API 封装或协议兼容性
- 测试与夹具
- release notes / changelog
如果代码改了,但帮助文本、README、示例或测试没有同步,直接记为集成跟进项,而不是轻描淡写地放过。
Step 7: 给出发布与回移建议
把改动归入以下类型之一:
- bugfix
- feature
- breaking change
- refactor-only
并说明:
- 对版本号的影响更像
patch/minor/major - 是否需要 release notes
- 是否需要迁移说明或兼容性提示
- 是否适合回移到维护分支
Step 8: 形成合并后动作清单
如果 PR 代码已经接近可合并,但还差最后几步,明确写成动作清单:
- 补 help / README / 示例
- 补或修正测试
- 更新 changelog / release notes
- 调整 milestone / 看板状态
- 合并后立即跟进的 issue 或回归验证
Step 9: 可选回写
只有用户明确要求时,才把结论回写到远端。回写前先生成本地 Markdown 报告,并优先 dry-run。
适合的回写方式:
pr +comment:发布集成报告pr +review --status common --dry-run:预览 review 文案
不要默认 approve 或 merge。这个 Skill 的职责是“给出可集成判断”,不是替维护者自动盖章。
报告模板
<!-- gitlink-pr-integrator:report v1 -->
## PR #<id> 集成就绪报告
**贡献价值:** <span style="color:#B54708"><strong>价值证据部分成立</strong></span> **[partial]**:PR 解决了可复现问题且实现完整,但尚未排除等价能力;依据:需求、Diff 和默认分支已核对,open/merged PR 对照未完成;下一步:补等价能力检查。
**合并态:** <span style="color:#067647"><strong>可干净应用到最新主线</strong></span> **[passed]**:当前 head 没有文本冲突;依据:固定 base/head SHA 的隔离合并;影响:无文本阻断。
**构建:** <span style="color:#067647"><strong>构建通过</strong></span> **[passed]**:仓库构建命令成功;依据:当前 head 的命令、退出码与日志;影响:编译链路可用。
**测试:** <span style="color:#067647"><strong>测试通过</strong></span> **[passed]**:专项与全量测试均成功;依据:同一 head 的测试账本;影响:已验证核心行为。
**契约:** <span style="color:#067647"><strong>外部契约保持兼容</strong></span> **[passed]**:旧调用和结构化输出未破坏;依据:帮助、JSON 与 baseline 对照;影响:调用方无需迁移。
**安全与发布:** <span style="color:#067647"><strong>安全与发布检查通过</strong></span> **[passed]**:没有阻断项;依据:安全矩阵、依赖和发布影响检查;影响:无额外前置。
**集成结论:** <span style="color:#B54708"><strong>先确认功能增量再决定入队</strong></span> **[observe]**:技术门禁通过但价值证据不完整;依据:IN-VALUE-03 和上述门禁;下一步:完成仓库能力对照后重评。
**状态索引:** 价值 `partial` | 合并态 `passed` | 构建 `passed` | 测试 `passed` | 契约 `passed` | 安全 `passed` | 冲突 `low`
**merge_readiness:** medium
**integration_risk:** medium
**conflict_risk:** high
**release_impact:** minor
### 先处理
1. **[IN-001][high] 确认** 是否已有等价批量能力;责任:维护者;证据:`E-IN-VALUE-03`。
### 1. 贡献价值依据
| 维度 | 评级 | 依据 | 证据 |
|------|------|------|------|
| 需求真实性 | strong | 关联 Issue 描述了可复现的高频人工步骤 | E-IN-VALUE-01 |
| 社区适配度 | strong | 能力落在现有命令体系和维护方向内 | E-IN-VALUE-01 |
| 功能增量 | unknown | 尚未完成已合并 PR 与 open PR 的等价能力核对 | E-IN-VALUE-03 |
| 使用频率与受益面 | moderate | 维护者和脚本调用方可复用,但缺少使用数据 | E-IN-VALUE-06 |
| 实现完整性 | strong | 代码、测试、help 和失败路径均有对应变更 | E-IN-VALUE-04 |
| 维护成本 | moderate | 新增一个 API 面,需要长期保持兼容 | E-IN-VALUE-05 |
| 风险收益比 | moderate | 收益明确,但重复程度确认前不能建议合入 | E-IN-VALUE-03 |
**价值结论依据:** <说明解决的问题、仓库当前缺口、实际增量、受益对象、维护代价和当前为何值得或不值得合入>
### 2. 合并态验证
- 基线:`<base_branch>`
- 结果:可合并 / 需 rebase / 存在冲突
- 构建:通过 / 失败 / 未执行
- 测试:通过 / 失败 / 未执行
- 备注:<只在合并态暴露的问题>
### 3. 与 open PR 的冲突分析
| PR | 风险 | 原因 | 建议顺序 |
|----|------|------|----------|
| #123 | high | 同时修改 `shortcuts/pr/pr.go` | 先合并对方 |
### 4. 集成影响矩阵
| 面向 | 状态 | 说明 |
|------|------|------|
| CLI 行为 | changed | 新增 `...` |
| Help / docs | follow-up needed | 命令帮助已更新,README 未同步 |
| Tests | changed | 新增单测,但缺少回归场景 |
### 5. 发布建议
- 类型:feature
- 版本影响:minor
- 是否需要 release notes:是
- 是否建议回移:否
### 6. 合并后动作
1. <动作 1>
2. <动作 2>
3. <动作 3>
批量模式
如果用户要求扫描 PR 队列,按下面的顺序执行:
- 列出 open PR。
- 过滤掉已经 merged、closed 或已经明确被维护者拒绝的项。
- 先按需求证据、功能增量、重复风险和受益面形成轻量价值门禁。
- 再按价值、最近活动时间、冲突密度和合并态风险排序,对前 N 条候选 PR 生成集成就绪报告。
- 再输出一份队列总览,包含建议合并顺序和需要先处理的冲突热点文件。
批量模式下,不默认对全部 PR 执行高成本本地构建。先做价值证据、元信息和冲突雷达;价值为 failed 的项不进入构建队列,partial/not_run 的项进入维护者确认队列,价值通过且风险较高的候选再进入本地合并验证。
示例请求
- “使用
gitlink-pr-integrator检查Gitlink/gitlink-cli的 PR #281 是否已经具备合并条件,不要回写远端。” - “使用
gitlink-pr-integrator扫描Gitlink/gitlink-cli最近 10 个 open PR,给出建议合并顺序、冲突风险和发布影响。”