feat(skills): 新增 gitlink-pr-topology skill

skills/gitlink-pr-topology/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: gitlink-pr-topology
+description: "开源社区 PR 队列关系图谱：面向一个仓库的多条 open Pull Request，识别它们之间的依赖链、功能重叠、替代/超越关系、冲突热点、可打包评审分组和建议处理顺序。用于维护者需要批量梳理 open PR 为什么互相卡住、哪几条其实在做同一件事、哪一条实现更完整、哪些 PR 应该先合并或先关闭，以及如何把复杂队列整理成可执行决策时。"
+---
+
+# gitlink-pr-topology
+
+**CRITICAL - 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。**
+**CRITICAL - GitLink 平台数据采集和回写只使用 `gitlink-cli`。**
+**CRITICAL - 这个 skill 关注的是 PR 与 PR 之间的关系，不代替单条 PR 的代码审查或合并验收。**
+**CRITICAL - 如果需要把中文报告写入文件或重定向输出，在 Windows PowerShell 中先切到 UTF-8 输出链路。**
+
+这个 skill 解决的是“PR 太多，维护者看不出它们彼此是什么关系”的问题。
+
+它不只回答“有没有重复”，还要回答：
+
+1. 哪些 PR 有明显的先后依赖，像 stacked PR 一样要按顺序处理。
+2. 哪些 PR 实际上在解决同一个需求、同一个 bug、同一个命令入口。
+3. 如果两条 PR 目标重叠，哪一条更完整、更稳、更值得保留。
+4. 哪些 PR 虽然不完全重复，但会在同一文件、同一命令、同一输出契约上互相打架。
+5. 哪些 PR 应该一起评审，避免维护者重复进入同一上下文。
+6. 当前 open PR 队列最合理的处理顺序是什么。
+
+## 不覆盖的内容
+
+下面这些不属于本 skill 的职责：
+
+- 单条 PR 的贡献价值、可行性、执行验证：交给 `gitlink-pr-assessor`
+- 单条 PR 是否已经具备并入主线的条件：交给 `gitlink-pr-integrator`
+- 维护者值班、SLA、review 负载和停滞治理：交给 `gitlink-maintainer-radar`
+
+## Windows UTF-8 前置
+
+如果你在 Windows PowerShell 中运行并准备保存中文报告，先执行：
+
+```powershell
+chcp 65001 > $null
+[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$OutputEncoding = [Console]::OutputEncoding
+```
+
+保存报告时显式指定 UTF-8：
+
+```powershell
+$report | Set-Content -Path .\pr-topology-report.md -Encoding utf8
+```
+
+## 关系类型
+
+先阅读 [`references/relationship-taxonomy.md`](references/relationship-taxonomy.md) 了解关系定义和证据标准。这个 skill 至少识别以下六类关系：
+
+1. `depends_on`
+表示 PR B 依赖 PR A 先落地，否则 B 难以独立评审、测试或合并。
+
+2. `overlaps_with`
+表示两条 PR 在需求目标、命令入口、模块范围或改动文件上明显重叠。
+
+3. `supersedes`
+表示一条较新的 PR 在同一目标上覆盖更完整，足以替代另一条较弱 PR。
+
+4. `conflicts_with`
+表示两条 PR 即使目标不同，也会在同一文件、同一 flag、同一 JSON 字段、同一帮助文案或同一 API 包装层上互相冲突。
+
+5. `review_together`
+表示几条 PR 共享足够多的上下文，维护者一起看更高效。
+
+6. `merge_after`
+表示不是严格代码依赖，但为了减少返工，建议某条 PR 排在另一条之后处理。
+
+## 标准流程
+
+### Step 1：拉取 open PR 队列
+
+先列出目标仓库的 open PR：
+
+```bash
+gitlink-cli pr +list --owner <owner> --repo <repo> --state open --page 1 --limit 50 --format json
+```
+
+注意：
+
+- `--state open` 的服务端过滤并不总是可靠，必须再用 `pull_request_status == 0` 做客户端过滤。
+- 队列过大时优先扫描最近活跃的前 20-50 条，而不是一次吃完整个仓库。
+
+### Step 2：为每条 PR 建立关系画像
+
+对每条候选 PR 至少补拉这些信息：
+
+```bash
+gitlink-cli pr +view --owner <owner> --repo <repo> --id <number> --format json
+gitlink-cli pr +files --owner <owner> --repo <repo> --id <number> --format json
+gitlink-cli pr +reviews --owner <owner> --repo <repo> --id <number> --format json
+gitlink-cli repo +info --owner <owner> --repo <repo> --format json
+```
+
+优先提取：
+
+- PR 标题、描述、作者、创建时间、最近更新时间
+- base/head 分支、fork 来源
+- 修改文件、核心目录、是否触及同一条命令或同一 API 封装
+- 是否修改测试、帮助文案、README、示例
+- review 争议点、是否已有人指出重复或依赖关系
+- 关联 issue、里程碑、标签
+
+### Step 3：先做“候选关系”粗筛
+
+先不要急着得结论，先把可能有关联的 PR 成对找出来。粗筛信号包括：
+
+- 标题和描述出现同一需求词、同一命令名、同一 issue 编号
+- 修改相同文件
+- 修改同一目录或同一 shortcuts 子模块
+- 同时触碰同一 flag、同一输出字段、同一错误提示
+- 一条 PR 的描述直接提到 “基于 #xx” “依赖 #xx” “替代 #xx”
+- 两条 PR 都在补同一类能力，例如 release、attachment、milestone、search
+
+只把这些候选对放进下一步，不要把所有 PR 两两做重分析。
+
+### Step 4：判断具体关系类型
+
+对每个候选对，结合 [`references/relationship-taxonomy.md`](references/relationship-taxonomy.md) 给出单一主关系，必要时允许附加次关系。
+
+判断顺序建议如下：
+
+1. 先看是否存在明确依赖链。
+2. 再看是否实际上在做同一件事。
+3. 再看是否已出现“更完整版本替代较弱版本”。
+4. 如果目标不同但落点冲突，则标为冲突热点。
+5. 如果只是共享上下文但不冲突，标为建议一起评审。
+
+没有足够证据时，写成 `possible_overlap` 或 `possible_dependency`，不要过度下结论。
+
+### Step 5：在重叠 PR 中比较“谁更值得保留”
+
+如果两条或多条 PR 目标重叠，读取 [`references/comparison-rubric.md`](references/comparison-rubric.md)，从以下维度比较：
+
+- 需求覆盖是否更完整
+- 代码路径是否更贴近现有架构
+- 测试是否更充分
+- 帮助文档、README、示例是否同步
+- 向后兼容性是否更好
+- 风险和复杂度是否更低
+- review 反馈吸收是否更充分
+
+输出时不要只说“PR A 更好”，而要明确指出：
+
+- A 比 B 多解决了什么
+- B 缺了什么
+- B 是否还能拆成补充 PR，还是应该直接关闭
+
+### Step 6：生成队列图谱和处理顺序
+
+最终输出的不是一堆散点结论，而是一份维护者可执行的“队列图谱”：
+
+- 哪些是依赖链，先后顺序怎样
+- 哪些是一组重叠实现，需要择一保留
+- 哪些是热点文件/热点命令，应该集中处理
+- 哪些 PR 值得一起 review
+- 哪些 PR 可以暂缓，因为上游未定
+
+## 输出要求
+
+同时产出两类结果：
+
+### 1. 关系边列表
+
+每条关系边至少包含：
+
+- `source_pr`
+- `target_pr`
+- `relation`
+- `confidence`
+- `evidence`
+- `recommended_action`
+
+### 2. 维护者摘要报告
+
+报告至少包含：
+
+1. open PR 总数和本轮纳入分析的数量
+2. 主要依赖链
+3. 主要重叠簇
+4. 明显替代关系
+5. 冲突热点文件/模块
+6. 建议处理顺序
+7. 需要进一步切换到 `gitlink-pr-assessor` 或 `gitlink-pr-integrator` 深挖的对象
+
+## 报告模板
+
+```markdown
+# <owner>/<repo> PR 队列关系图谱
+
+扫描时间：<timestamp>
+open PR：<n>
+纳入分析：<n>
+
+## 1. 依赖链
+- #41 -> #44 -> #52
+  说明：#44 基于 #41 引入的 API 包装，#52 又建立在 #44 的 CLI 参数层上。
+
+## 2. 重叠实现
+- #61 vs #63
+  共同点：都在实现同一条命令的编号搜索能力。
+  保留建议：优先保留 #63，因为测试覆盖更完整，且同时补了帮助文档和 JSON 输出。
+
+## 3. 替代关系
+- #71 supersedes #58
+  说明：#71 覆盖了 #58 的核心功能，还补齐了错误处理和帮助文档；#58 可关闭或拆成子改动。
+
+## 4. 冲突热点
+- `shortcuts/pr/pr.go`
+- `internal/client/client.go`
+- `README.md`
+
+## 5. 建议一起评审
+- #80, #81, #83
+  说明：都在修改 milestone 相关 CLI 行为，一起看更容易统一参数和输出契约。
+
+## 6. 建议处理顺序
+1. 先处理 #41，解除后续依赖链阻塞。
+2. 在 #61 和 #63 中择一保留，避免重复 review。
+3. 将 #80、#81、#83 打包评审，统一命令体验。
+4. 暂缓 #52，等待上游 API 包装方案稳定。
+```
+
+## 典型触发语句
+
+- “扫描这个仓库的 open PR，找出哪些在做同一件事。”
+- “帮我分析这批 PR 的依赖关系和建议合并顺序。”
+- “哪些 PR 其实可以一起 review，哪些应该择一保留？”
+- “如果有两条 PR 功能重叠，判断哪条实现更完整。”
+- “给我一个 open PR 队列关系图谱，方便维护者决定先看谁。”

skills/gitlink-pr-topology/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PR 关系图谱"
+  short_description: "分析 open PR 之间的依赖、重叠、替代和建议处理顺序。"
+  default_prompt: "Use $gitlink-pr-topology 扫描这个 GitLink 仓库的 open PR 队列，识别依赖链、功能重叠、潜在替代关系、冲突热点和建议处理顺序。"

skills/gitlink-pr-topology/examples/codex-validation-2026-06-26.md

@@ -0,0 +1,89 @@
+# Codex 验证记录（2026-06-26）
+
+Agent 平台：Codex
+
+验证目标：确认 `gitlink-pr-topology` 能在 GitLink 仓库的 open PR 队列上产出可读、可执行的关系图谱，识别依赖链、功能重叠、替代关系、冲突热点和建议处理顺序。
+
+验证结果如下：
+
+# Gitlink/gitlink-cli PR 队列关系图谱
+
+扫描时间：2026-06-26 11:46:10 +08:00
+
+open PR 总数：156
+
+本轮纳入分析：最近 40 条 open PR
+
+范围：#292, #291, #290, #285, #284, #283, #282, #281, #280, #279, #277, #276, #275, #274, #262, #273, #272, #271, #270, #269, #268, #267, #265, #263, #261, #238, #225, #259, #258, #257, #256, #255, #254, #167, #151, #135, #82, #76, #72, #70
+
+### 1. 主要关系边
+
+| 关系 | 置信度 | 证据 | 建议动作 |
+|---|---:|---|---|
+| #281 supersedes #254 | 高 | 都修 `cmd/api/api.go` 的单次 Raw API 占位符；#281 还补 `--header`、body/query/header 模板和 `internal/client` 支持 | 优先评审 #281；#254 可关闭或改成补充测试 |
+| #282 supersedes #268 | 高 | 都改 `shortcuts/branch/branch.go` 和 branch lifecycle；#282 覆盖筛选、默认分支切换与恢复，并补 i18n/文档 | 保留 #282，#268 只保留可迁移的小补丁 |
+| #272 supersedes #270 | 高 | #270 新增 message settings；#272 同时包含 message settings 和 notification 工作流 | 若 #272 验证通过，#270 可关闭 |
+| #272 overlaps_with #76 | 中 | 都新增 notification 相关 shortcut，均改 `shortcuts/notification/notification.go` 与注册入口 | 对比 API 覆盖面，择一实现，避免双实现 |
+| #274 overlaps_with #263/#72 | 高 | 三者都新增 template shortcut，并改 `shortcuts/template/template.go`、`shortcuts/register.go` | 选择一个 template 实现；可从其他 PR cherry-pick 文档或 skill |
+| #261 conflicts_with #263/#274/#72 | 高 | #261 标题是 auth checkin，但同时新增 template 文件，和 template PR 重叠 | 要求拆分：auth checkin 与 template shortcut 分开 |
+| #283 merge_after #258 | 中 | #283 改 `internal/output/formatter.go` 以显示 PR 编号；#258 修 table 顺序和错误码，是输出层基础修复 | 先合 #258，再处理 #283 |
+| #284 review_together #283/#285 | 高 | 三者都改 `shortcuts/pr/pr.go`、`pr_test.go`，分别处理编号显示、编号搜索、login 过滤 | 打包 review，建议顺序 #283 -> #284 -> #285 |
+| #273 review_together #275/#225 | 中 | 都改 `shortcuts/repo/repo.go`；分别是治理/转移、upload、scaffold | 一起统一 repo 命令命名和帮助文案 |
+| #262 review_together #238/#70/#167 | 中 | 都涉及 user/account 能力；#262/#238/#70 改 `shortcuts/user/user.go`，#167 补 account email | 拆分 account、stats、key 三类能力后择序合并 |
+| #276 conflicts_with 多数 shortcut PR | 高 | 127 文件，覆盖 register、pr、repo、user、branch、client、README 等热点 | 暂缓，建议拆分后再进队列 |
+| #259 conflicts_with 多数 shortcut/skill PR | 高 | 156 文件，覆盖 `cmd/api`、`cmd/auth`、多数 shortcuts、skills、README | 暂缓，要求拆成可审单元 |
+
+### 2. 重叠实现簇
+
+**PR 列表能力簇：#283/#284/#285**
+
+共同点：都在扩展 `pr +list`。#283 显示 PR 编号，#284 支持按编号搜索，#285 支持按作者 login 过滤。三者目标互补，但同改 `shortcuts/pr/pr.go` 的 flag、结果封装和 helper 区域，合并时很容易互相重写。建议一起 review，先确立列表输出契约，再合功能。
+
+**Raw API 占位符簇：#281/#254**
+
+#281 覆盖更完整，已经从 path 扩展到 query/body/header 模板，并补了 client header 支持；#254 更像早期窄修。建议保留 #281，#254 关闭或转为补充用例。
+
+**Branch lifecycle 簇：#282/#268**
+
+两者目标高度一致。#282 范围更完整，且同步 README、中文 README、i18n 和测试。建议以 #282 为主线。
+
+**Notification/message setting 簇：#272/#270/#76**
+
+#270 是 message setting 子集，#272 是 notification + message setting 组合，#76 是较早的 notification OpenAPI shortcut。建议维护者先决定 notification 命令的最终 API 覆盖，再合并一个代表实现。
+
+**Template 簇：#274/#263/#72/#261**
+
+#274/#263/#72 都实现 template shortcut；#72 还带 `skills/gitlink-template/SKILL.md`，#274 带更完整的 `doc/changes` 和 i18n。#261 混入 template 改动但标题是 auth checkin，应拆分。
+
+**大而全冲突簇：#276/#259**
+
+这两条是当前队列最大冲突源。它们和几乎所有 shortcut PR 都抢 README、注册入口、i18n、核心 shortcut 文件。建议不要直接进入合并队列，先拆分。
+
+### 3. 冲突热点
+
+- `README.md`：25 条 PR 修改
+- `README.zh-CN.md`：23 条 PR 修改
+- `skills/README.md`：14 条 PR 修改
+- `shortcuts/register.go`：13 条 PR 修改
+- `shortcuts/register_test.go`：11 条 PR 修改
+- `internal/i18n/locales/en-US.json` / `zh-CN.json`：各 10 条 PR 修改
+- `shortcuts/pr/pr.go`：#285/#284/#283/#276/#259
+- `shortcuts/repo/repo.go`：#275/#273/#225/#276/#259
+- `shortcuts/user/user.go`：#262/#238/#70/#276/#259
+- `cmd/api/api.go`：#281/#254/#259
+
+### 4. 建议处理顺序
+
+1. 先冻结 #276 和 #259：要求拆分，不建议在现状下合并，否则会持续冲突后续小 PR。
+2. 先处理明确替代关系：#281 替代 #254；#282 替代 #268；#272 替代或吸收 #270。
+3. 先合基础修复：#258 输出稳定性、#281 Raw API 修复，优先级高，能降低后续验证不确定性。
+4. 打包评审 PR 列表簇：按 #283 -> #284 -> #285 顺序处理，统一 `pr +list` 输出、编号查询和 login 过滤。
+5. 择一处理重复命令簇：template 在 #274/#263/#72 中选主实现；notification 在 #272/#76 中选主实现。
+6. 按命令族处理 focused shortcut：branch 用 #282；repo 组一起看 #273/#275/#225；user/account 组一起看 #262/#238/#167/#70。
+7. 最后处理 skill-only PR：#292/#291/#290/#277/#280/#257/#256/#255/#265/#269 主要冲突在 `skills/README.md` 或各自 skill 目录，可批量审查索引一致性。
+
+### 5. 需要深挖的对象
+
+- 用 `gitlink-pr-integrator`：#281、#282、#272、#274、#283/#284/#285，重点做合并态和冲突验证。
+- 用 `gitlink-pr-assessor`：#276、#259，重点判断是否应拆分、暂缓或拒绝。
+- 人工重点比较：#272 vs #76、#274 vs #72/#263、#262 vs #238/#70。

skills/gitlink-pr-topology/examples/dependency-chain-scan.md

@@ -0,0 +1 @@
+使用 `$gitlink-pr-topology` 扫描 `Gitlink/gitlink-cli` 最近 20 条 open PR，找出明确依赖链和建议处理顺序，不要回写远端，只输出中文维护者报告。

skills/gitlink-pr-topology/examples/overlap-comparison.md

@@ -0,0 +1 @@
+使用 `$gitlink-pr-topology` 对 `Gitlink/gitlink-cli` 的 open PR 做功能重叠分析，重点找出在同一命令、同一模块或同一 issue 上重复实现的 PR，并比较哪一条更完整、更值得保留。

skills/gitlink-pr-topology/examples/review-bundles.md

@@ -0,0 +1 @@
+使用 `$gitlink-pr-topology` 给我一个 open PR 评审分组建议，指出哪些 PR 应该一起 review，哪些 PR 应该择一保留，哪些 PR 需要等上游先落地。

skills/gitlink-pr-topology/references/comparison-rubric.md

@@ -0,0 +1,55 @@
+# 重叠 PR 比较标尺
+
+当两条或多条 PR 目标重叠时，不要只看代码行数。按下面七个维度比较“哪一条更值得保留”。
+
+## 1. 需求覆盖
+
+- 是否覆盖用户提出的完整场景
+- 是否只做了半截能力
+- 是否同时处理了边界情况
+
+## 2. 架构贴合度
+
+- 是否沿用现有封装模式
+- 是否引入了额外特例
+- 是否把逻辑放在合理层次
+
+## 3. 测试完整度
+
+- 是否新增单元测试
+- 是否覆盖正常路径与错误路径
+- 是否能证明和宣称功能一致
+
+## 4. 文档与帮助同步
+
+- `--help` 是否更新
+- README、示例、变更说明是否同步
+- 中文文案是否正常、无乱码
+
+## 5. 兼容性
+
+- 是否破坏原有参数或输出契约
+- 是否影响既有脚本调用
+- 默认值和错误提示是否稳妥
+
+## 6. 风险与复杂度
+
+- 是否引入不必要的大改动
+- 是否触碰高风险公共层
+- 是否容易产生回归
+
+## 7. review 吸收度
+
+- 是否已响应 reviewer 意见
+- 是否还存在已指出但未修的问题
+- 是否比竞争 PR 更接近可落地状态
+
+## 建议输出格式
+
+比较结论应长这样：
+
+- “优先保留 #63。它和 #61 目标重叠，但 #63 多补了编号搜索的测试、帮助文案和错误处理，且没有改坏现有关键字搜索入口；#61 仍可把其中的 UI 文案优化拆成小补丁继续保留。”
+
+避免这种空话：
+
+- “#63 更好，更全面。”

skills/gitlink-pr-topology/references/relationship-taxonomy.md

@@ -0,0 +1,94 @@
+# 关系分类与证据标准
+
+在 `gitlink-pr-topology` 中，不要把“有点像”直接写成“重复”。先按下面的证据标准分型。
+
+## 1. depends_on
+
+适用场景：
+
+- 一条 PR 的描述明确写了依赖另一条 PR
+- 下游 PR 直接建立在上游新增的命令、结构体、API 包装或测试夹具之上
+- 不先合并上游，当前 PR 的验证、评审或主线集成都缺前提
+
+高置信证据：
+
+- 描述或评论中明确提到 `depends on #xx`
+- 两条 PR 的 head/base 明显形成链条
+- 下游代码直接引用上游新增符号
+
+## 2. overlaps_with
+
+适用场景：
+
+- 解决同一个 issue 或同一个用户需求
+- 修改同一命令入口或同一子模块
+- 标题不同，但行为目标一致
+
+高置信证据：
+
+- 相同 issue 编号或相同命令名
+- 相同文件集合重叠明显
+- 两条 PR 的帮助文案或输出字段目标一致
+
+## 3. supersedes
+
+适用场景：
+
+- 两条 PR 明显重叠，但其中一条覆盖范围更完整
+- 较新的 PR 已吸收较旧 PR 的核心思路和大部分实现点
+- 保留两条 PR 已没有意义
+
+高置信证据：
+
+- 功能覆盖包含关系明显
+- 更强 PR 同时补齐测试、文档、兼容性
+- 较弱 PR 长期未更新，而较强 PR 已响应 review 并继续演进
+
+## 4. conflicts_with
+
+适用场景：
+
+- 两条 PR 改动同一热点文件
+- 两条 PR 对同一 flag、同一 JSON 字段、同一错误提示给出不同方案
+- 未来即使都要保留，也一定会互相重写或产生合并冲突
+
+高置信证据：
+
+- 同一文件相邻区域同时被修改
+- 同一命令帮助文本或参数行为相互不兼容
+- 一个 PR 的默认值选择与另一个 PR 相反
+
+## 5. review_together
+
+适用场景：
+
+- 几条 PR 涉及相同模块，但没有明显冲突
+- 一起 review 更容易统一命名、参数和输出风格
+- 拆开看会让维护者重复加载同一上下文
+
+高置信证据：
+
+- 同一目录、同一组件、同一命令族
+- 目标互补而非互斥
+
+## 6. merge_after
+
+适用场景：
+
+- 不是严格依赖，但某 PR 最好在另一条 PR 之后处理
+- 上游 PR 会影响接口、帮助文案或目录结构，下游先审价值不高
+
+高置信证据：
+
+- 上游 PR 改的是底层封装，下游 PR 改的是调用层
+- 先合并下游会造成明显返工
+
+## 低置信措辞
+
+证据不足时，使用保守措辞：
+
+- `possible_overlap`
+- `possible_dependency`
+- `possible_conflict`
+
+不要在证据不足时使用 `supersedes`。