fix(skills): 兼容现有 CLI 采证并校验维护报告
This commit is contained in:
parent
29ef9b342d
commit
9818a05aff
|
|
@ -33,18 +33,23 @@ gitlink-cli workflow +review-queue --from queue.json --previous queue-previous.j
|
|||
- 只读运行，不评论、不 approve、不合并、不关闭、不修改远端。
|
||||
- 使用 `CG-001` 起的稳定编号，记录旧行为、新行为、复现命令、严重性、证据、修复建议和验证限制。
|
||||
- 首屏先显示兼容性结论、关键门禁和最多 5 项会影响现有用户或脚本的动作；blocking/high 使用颜色和粗体并保留文本标签。
|
||||
- 聊天和报告首屏按 PR 分节；参数与帮助、JSON/文本输出、错误与退出码、编码与颜色、兼容与文档、契约结论分别使用结论前置判断卡，后接解释、`依据：` 和影响/下一步。
|
||||
- 一次运行只生成一份 UTF-8 Markdown，保存到 `reports/skill-runs/gitlink-cli-contract-guard/<owner>-<repo>-<scope>-<yyyyMMdd-HHmmssZ>.md`；多个 PR 在同一报告内分开结论。
|
||||
|
||||
无法写入工作区时输出完整 Markdown 并标记“未落盘”。最终回复只需给出报告绝对路径、主结论和阻断数，不在聊天中重复整份报告。
|
||||
最终回复复用报告首屏的逐 PR 六方面判断卡，再给报告绝对路径；不能把多个 PR 或方面压成一段，也不能只给路径。无法写入工作区时输出完整 Markdown 并标记“未落盘”。
|
||||
|
||||
首屏固定先使用以下结构，再展开完整契约面：
|
||||
|
||||
```markdown
|
||||
# CLI 契约审查摘要
|
||||
|
||||
**结论：** <span style="color:#B42318"><strong>阻断合并</strong></span> **[blocked]**
|
||||
**门禁：** 参数 `passed` | 帮助 `passed` | JSON `failed` | 错误 `passed` | 安全 `not_run`
|
||||
**发现：** blocking 1 | high 1 | medium 0 | low 0
|
||||
## PR #<number>
|
||||
**参数与帮助：** <span style="color:#067647"><strong>旧调用保持兼容</strong></span> **[passed]**：新 flag 为可选且默认行为不变；依据：baseline/current `--help` 与旧调用对照；影响：现有用户无需迁移。
|
||||
**JSON/文本输出：** <span style="color:#B42318"><strong>机器输出已被破坏</strong></span> **[failed]**：ANSI 状态文本混入 JSON；依据：golden 解析和原始字节；下一步：分离人读渲染与 JSON。
|
||||
**错误与退出码：** <span style="color:#067647"><strong>错误语义稳定</strong></span> **[passed]**：参数错误和远端失败仍可区分；依据：失败命令、stderr 和退出码；影响：自动化可继续判断故障。
|
||||
**编码与颜色：** <span style="color:#B54708"><strong>颜色边界未完整验证</strong></span> **[partial]**：中文 UTF-8 正常但 `NO_COLOR` 缺测；依据：编码扫描和测试清单；下一步：补无颜色回归。
|
||||
**兼容与文档：** <span style="color:#B54708"><strong>文档与行为部分不一致</strong></span> **[partial]**：示例未说明新增字段可选性；依据：README、帮助与实际 JSON 对照；下一步：同步说明。
|
||||
**契约结论：** <span style="color:#B42318"><strong>修复 JSON 后再审</strong></span> **[blocked]**：存在一个 blocking 契约问题；依据：CG-001 与复现命令；下一步：修复并重跑完整矩阵。
|
||||
|
||||
## 先处理这 2 项
|
||||
|
||||
|
|
@ -52,6 +57,8 @@ gitlink-cli workflow +review-queue --from queue.json --previous queue-previous.j
|
|||
2. <span style="color:#B54708"><strong>[CG-002][high] 验证</strong></span> header 换行和注入边界。
|
||||
```
|
||||
|
||||
多个 PR 在同一报告中重复 `## PR #<number>` 和六张判断卡，不能共享状态或证据。
|
||||
|
||||
这个 skill 的目标很窄，也很硬：**找出会把现有 CLI 用户用法搞坏的改动。**
|
||||
|
||||
它重点审查五类契约面：
|
||||
|
|
@ -89,8 +96,13 @@ gitlink-cli workflow +review-queue --from queue.json --previous queue-previous.j
|
|||
|
||||
```markdown
|
||||
# CLI 契约审查摘要
|
||||
**结论：** <span style="color:#B42318"><strong>阻断合并</strong></span> **[blocked]**
|
||||
**门禁：** 参数通过 | 帮助通过 | JSON 失败 | 错误提示通过 | 安全未验证
|
||||
## PR #<number>
|
||||
**参数与帮助：** <span style="color:#067647"><strong>默认调用兼容</strong></span> **[passed]**：新参数保持旧默认值；依据：baseline/current 帮助和旧调用对照；影响：无需迁移。
|
||||
**JSON/文本输出：** <span style="color:#B42318"><strong>JSON 已被 ANSI 破坏</strong></span> **[failed]**：机器输出无法稳定解析；依据：golden 解析与原始字节；下一步：隔离渲染。
|
||||
**错误与退出码：** <span style="color:#067647"><strong>错误语义稳定</strong></span> **[passed]**：退出码仍可区分错误；依据：失败矩阵；影响：脚本兼容。
|
||||
**编码与颜色：** <span style="color:#B54708"><strong>注入和 NO_COLOR 未验证</strong></span> **[partial]**：边界测试缺失；依据：测试清单；下一步：补恶意输入。
|
||||
**兼容与文档：** <span style="color:#B54708"><strong>文档说明不完整</strong></span> **[partial]**：未说明字段可选性；依据：README 与实际输出；下一步：同步文档。
|
||||
**契约结论：** <span style="color:#B42318"><strong>修复 JSON 后再审</strong></span> **[blocked]**：存在 blocking 问题；依据：CG-001；下一步：修复并重跑矩阵。
|
||||
|
||||
## 先做这 2 件事
|
||||
1. **[CG-001][blocking] 修复** JSON 输出中的 ANSI 转义，并补 golden 测试（责任：作者）。
|
||||
|
|
@ -237,28 +249,23 @@ go test ./...
|
|||
|
||||
### Step 6：输出契约审查结论
|
||||
|
||||
推荐输出结构：
|
||||
聊天和 Markdown 首屏必须使用前述逐 PR 六方面判断卡，详细 `CG-` 发现、命令和 golden 差异放在后文。保存后针对每个目标重复 `--require-pr` 并运行：
|
||||
|
||||
```markdown
|
||||
# CLI 契约审查报告
|
||||
|
||||
## 高风险问题
|
||||
- `--header` 模板渲染后未再次校验，可能生成非法 header。
|
||||
- README.zh-CN 新增示例出现中文乱码，会污染用户可见文档。
|
||||
|
||||
## 契约面影响
|
||||
- 参数契约：`--header` 新增并改变请求构造行为。
|
||||
- 输出契约：无破坏性字段变更证据。
|
||||
- 错误契约：中文错误提示存在编码退化风险。
|
||||
|
||||
## 缺失验证
|
||||
- 缺少对 `Accept` 头覆盖行为的边界测试。
|
||||
- 缺少对渲染后非法 header 的测试。
|
||||
|
||||
## 结论
|
||||
- 需要修改后再合并。
|
||||
```bash
|
||||
python -X utf8 skills/gitlink-shared/scripts/validate_pr_cards.py \
|
||||
--report <absolute-report-path> \
|
||||
--require-pr <target-number> \
|
||||
--min-cards 6 \
|
||||
--required-aspect "参数与帮助" \
|
||||
--required-aspect "JSON/文本输出" \
|
||||
--required-aspect "错误与退出码" \
|
||||
--required-aspect "编码与颜色" \
|
||||
--required-aspect "兼容与文档" \
|
||||
--required-aspect "契约结论"
|
||||
```
|
||||
|
||||
校验失败时必须重写，不能交付报告路径。只有本地改动且不存在 PR 编号时，可以用 `## PR #0` 表示本地候选，并在解释中注明不是远端 PR。
|
||||
|
||||
## 典型触发语句
|
||||
|
||||
- “帮我看这个改动会不会破坏现有 CLI 用法。”
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
interface:
|
||||
display_name: "CLI 契约守卫"
|
||||
short_description: "检查 flags、help、JSON 输出和错误提示是否发生破坏性变化。"
|
||||
default_prompt: "使用 $gitlink-cli-contract-guard 检查指定 PR 或本地改动。按 Skill 默认契约执行只读 CLI 契约审查，并生成关键结论前置的单一 Markdown 报告。"
|
||||
default_prompt: "使用 $gitlink-cli-contract-guard 检查指定 PR 或本地改动；聊天和 Markdown 均按 PR 分节，将参数与帮助、JSON/文本输出、错误与退出码、编码与颜色、兼容与文档、契约结论分别做成结论前置判断卡，后接依据与影响，全程只读。"
|
||||
|
|
|
|||
|
|
@ -9,8 +9,14 @@ go run . pr +view --owner Gitlink --repo gitlink-cli --id 123 --format json 2>er
|
|||
|
||||
```markdown
|
||||
# CLI 契约审查摘要
|
||||
**结论：** <span style="color:#B42318"><strong>阻断合并</strong></span> **[blocked]**
|
||||
**门禁：** 参数通过 | 帮助通过 | JSON 失败 | 错误提示通过 | 安全未验证
|
||||
|
||||
## PR #123
|
||||
**参数与帮助：** <span style="color:#067647"><strong>旧调用保持兼容</strong></span> **[passed]**：新增参数为可选且默认值不变；依据：默认分支与当前 head 的帮助、旧命令和解析结果对照；影响：现有脚本无需迁移。
|
||||
**JSON/文本输出：** <span style="color:#B42318"><strong>机器输出契约已破坏</strong></span> **[failed]**：调试文本混入 JSON 并导致解析失败；依据：相同命令的原始字节和结构化解析测试；下一步：分离人读日志与 JSON。
|
||||
**错误与退出码：** <span style="color:#067647"><strong>错误语义仍可区分</strong></span> **[passed]**：参数错误和远端错误保留不同退出码；依据：失败矩阵、stderr 和退出码；影响：自动化判断不受影响。
|
||||
**编码与颜色：** <span style="color:#B54708"><strong>注入与无颜色边界未验证</strong></span> **[partial]**：中文 UTF-8 正常，但 `--header` 恶意输入和 `NO_COLOR` 缺少证据；依据：编码扫描与测试清单；下一步：补边界回归。
|
||||
**兼容与文档：** <span style="color:#B54708"><strong>文档说明不完整</strong></span> **[partial]**：帮助未说明新增字段的可选性；依据：README、帮助和真实输出对照；下一步：同步契约说明。
|
||||
**契约结论：** <span style="color:#B42318"><strong>修复 JSON 后再审</strong></span> **[blocked]**：存在一个会阻断脚本消费的契约问题；依据：CG-001 和稳定复现命令；下一步：修复并重跑完整矩阵。
|
||||
|
||||
## 先做这 2 件事
|
||||
1. **[CG-001][blocking] 修复** JSON 输出中的调试文本，并补结构化断言。
|
||||
|
|
|
|||
|
|
@ -18,10 +18,11 @@ description: "GitLink 社区智能审查：审查一个或多个 PR 的贡献价
|
|||
- **只读远端**：可以生成 Review 结论、整体评论草稿和内联评论草稿，但不提交 Review、不评论、不 approve、不合并、不关闭、不分配、不改标签。
|
||||
- **独立运行**：不调用其他 Skill。遇到需要专项判断的内容，可以注明验证限制，但仍完成本 Skill 能够完成的分析。
|
||||
- **结论前置**：首屏先显示评审建议、阻断项、Review 履约结果和最多 5 项关键动作；blocking/high 使用颜色和粗体，并保留纯文本标签。
|
||||
- **报告结论加依据**：Markdown 中的价值、实现、Review 履约、测试和安全等关键方面先醒目显示 `passed/failed/partial/not_run`，随后用 1 至 2 句说明实际功能、判定证据和影响；状态词不能脱离描述单独出现。
|
||||
- **证据可追溯**：发现使用 `CR-`，Review 履约项使用 `RV-`，健康项使用 `RH-`，Issue 分诊项使用 `IT-` 稳定编号。
|
||||
- **单文件落盘**：一次运行生成一份 UTF-8 Markdown，保存到 `reports/skill-runs/gitlink-code-review/<owner>-<repo>-<scope>-<yyyyMMdd-HHmmssZ>.md`。
|
||||
|
||||
无法写入工作区时，在最终回复中输出完整 Markdown 并标记“未落盘”。Markdown 不写 ANSI；凭据、cookie、token 和敏感值必须脱敏。
|
||||
最终回复的 PR 部分必须按 PR 分节，并分别显示 Review 建议、贡献价值、Review 履约、实现与逻辑、测试、安全和关键发现七张结论前置判断卡；不得压缩成一段“审查结论”。Issue 部分必须解释每个 P 级别含义、本批事项共同问题和下一步。最后声明 Review 草稿未提交并给出 Markdown 绝对路径。无法写入工作区时输出完整 Markdown 并标记“未落盘”。Markdown 不写 ANSI；凭据、cookie、token 和敏感值必须脱敏。
|
||||
|
||||
## 运行模式
|
||||
|
||||
|
|
@ -35,20 +36,69 @@ description: "GitLink 社区智能审查：审查一个或多个 PR 的贡献价
|
|||
|
||||
### Issue 分诊模式
|
||||
|
||||
用户要求 Issue 扫描或综合社区审查时启用。首屏只列各优先级的数量和 Issue 编号，详细分类统一放在报告最后。
|
||||
用户要求 Issue 扫描或综合社区审查时启用，支持三种明确范围：
|
||||
|
||||
## 首屏固定结构
|
||||
- **前 N 条 open Issue**：例如“处理前 40 条 open Issue”；按最近更新时间降序取 N 条，并用真实状态二次过滤。
|
||||
- **全部 open Issue**：自动翻页、按 Issue ID 去重并处理当前全部开启项；报告必须记录实际页数、条数和截断/失败情况。
|
||||
- **指定 Issue**：例如“只处理 #12、#18、#31”；逐条读取并回显真实状态，closed 项只标记为历史项，不混入 open 待办。
|
||||
|
||||
用户只说“处理 Issue”但没有范围时，默认取最近更新的前 40 条 open Issue，并在首屏明确该默认范围。只请求 PR 审查时不自动扫描 Issue，首屏省略 `Issue 待办`，报告末尾注明该模式未启用。Issue 首屏只列范围、各优先级数量和编号，详细分类统一放在报告最后。
|
||||
|
||||
## 聊天和报告首屏固定结构
|
||||
|
||||
聊天可以比详细报告短，但必须逐 PR 保留全部专项方面；每一方面独立成行，最直接结论位于最前：
|
||||
|
||||
```markdown
|
||||
## PR #<number>
|
||||
**Review 建议：** <span style="color:#B42318"><strong>修改后再审</strong></span> **[action_required]**：存在 2 个影响真实使用的问题；依据：CR-<number>-001、CR-<number>-002；下一步：按发现逐项修复并复验。
|
||||
**贡献价值：** <span style="color:#067647"><strong>价值成立</strong></span> **[passed]**：解决 <实际问题>；依据：默认分支差异、需求和受益范围；影响：<用户或维护收益>。
|
||||
**Review 履约：** <span style="color:#175CD3"><strong>本轮无可核对 Review</strong></span> **[not_applicable]**：没有有效 Review 意见；依据：Review 列表与当前 head；影响：只评估当前完整 Diff。
|
||||
**实现与逻辑：** <span style="color:#B42318"><strong>核心边界仍有错误</strong></span> **[failed]**：<触发条件与错误行为>；依据：`path/file.go:42` 与复现命令；下一步：<具体修改>。
|
||||
**测试：** <span style="color:#B54708"><strong>关键失败路径缺失</strong></span> **[partial]**：正常测试通过但 <场景> 未覆盖；依据：测试文件与执行结果；下一步：补回归用例。
|
||||
**安全：** <span style="color:#067647"><strong>未扩大安全边界</strong></span> **[passed]**：没有新增认证、执行或敏感输出路径；依据：Diff 与安全矩阵；影响：无安全阻断。
|
||||
**关键发现：** <span style="color:#B42318"><strong>2 项必须修改</strong></span> **[high]**：CR-<number>-001、CR-<number>-002；依据：文件行号和复现证据；下一步：优先修复 high 项。
|
||||
|
||||
**Issue 分诊**
|
||||
|
||||
P0（立即处置）：0 条。没有发现安全事故、数据损坏或核心服务不可用事项。
|
||||
P1（本轮优先处理）：#27、#26、#24。上述事项影响常用流程或阻塞维护工作，信息基本完整，应在当前维护周期确认负责人并推进。
|
||||
P2（进入计划处理）：#25、#17。问题真实但不构成当前阻断，建议补充验收条件后排入迭代。
|
||||
P3（可延后或先补信息）：#23、#22。影响较低或上下文不足，先请求复现信息、去重或确认需求。
|
||||
```
|
||||
|
||||
问题编号、文件位置、问题数量和 Issue 概述必须来自本轮证据，不能复制示例。closed/merged 历史 PR 仍按同样七方面输出，以 `not_applicable` 说明无需当前门禁，并在 Review 建议中写清保持关闭或历史对照的依据。
|
||||
|
||||
## Markdown 报告首屏固定结构
|
||||
|
||||
首屏只保留直接改变维护者决策的信息：
|
||||
|
||||
```markdown
|
||||
# GitLink 社区审查摘要
|
||||
|
||||
**Review 建议：** <span style="color:#B42318"><strong>修改后再审</strong></span> **[action_required]**
|
||||
**PR 门禁：** 价值 `passed` | Review 履约 `failed` | 实现 `partial` | 测试 `failed` | 安全 `passed`
|
||||
**Review 履约：** 8 条 | 已完成 6 | 部分完成 1 | 未完成 1 | 引入回归 0
|
||||
**代码发现：** blocking 0 | high 2 | medium 3 | low 4
|
||||
**Issue 待办：** P0 1 条（#81）| P1 3 条（#72、#76、#89）| P2 5 条 | P3 8 条
|
||||
## PR #123
|
||||
**Review 建议：** <span style="color:#B42318"><strong>修改后再审</strong></span> **[action_required]**：正常流程可用，但 closed PR 会进入 open 队列；依据：`shortcuts/workflow/pr_fetch.go:403`、真实响应和缺失的回归 fixture；下一步：增加客户端二次过滤并补三类真实响应测试后复看。
|
||||
|
||||
**贡献价值：** <span style="color:#067647"><strong>价值成立</strong></span> **[passed]**：为维护者增加 SLA 与责任方识别；依据：默认分支没有等价输出、需求与受益范围；影响：减少人工排队。
|
||||
**Review 履约：** <span style="color:#175CD3"><strong>没有待履约意见</strong></span> **[not_applicable]**：当前没有有效 Review；依据：Review 列表与 head SHA；影响：本轮只评价完整 Diff。
|
||||
**实现与逻辑：** <span style="color:#B42318"><strong>核心队列结果不可靠</strong></span> **[failed]**：真实 open 查询会混入 closed PR；依据：真实响应与 `pull_request_status` 归一化路径；下一步：增加客户端二次过滤。
|
||||
**测试：** <span style="color:#B54708"><strong>真实响应覆盖不完整</strong></span> **[partial]**：构建和理想响应测试通过；依据：测试命令和现有 fixture；下一步：补服务端忽略 state、数值状态和无责任字段场景。
|
||||
**安全：** <span style="color:#067647"><strong>未扩大安全边界</strong></span> **[passed]**：改动为只读归一化；依据：Diff 未新增认证、权限、执行或敏感输出路径；影响：无安全阻断。
|
||||
**关键发现：** <span style="color:#B42318"><strong>1 项 high 必须修复</strong></span> **[high]**：open 队列可能包含 closed PR；依据：CR-001 与真实响应；下一步：修复后复验。
|
||||
|
||||
**代码发现：**
|
||||
- **blocking（阻止合并）：0 条。** 未发现已证实的漏洞、数据破坏或不可逆回归。
|
||||
- <span style="color:#B54708"><strong>high（本轮必须修复）：1 条，CR-001。</strong></span> open 队列可能包含 closed PR，直接影响维护者判断。
|
||||
- **medium（应补齐后复看）：2 条，CR-002、CR-003。** 缺少真实响应测试，更新时间回退来源也未显式说明。
|
||||
- **low（可延后优化）：0 条。**
|
||||
|
||||
## 已关闭历史对照
|
||||
**#90：** 状态为 closed，只用于比较既有实现，不生成当前门禁、Review 建议或重新打开建议。
|
||||
|
||||
## Issue 分诊（最近更新的前 40 条 open，实际取得 15 条）
|
||||
**P0（立即处置）：0 条。** 没有发现需要立刻止损的安全事故、数据损坏或核心服务不可用事项。
|
||||
**P1（本轮优先处理）：#81、#82、#83。** 这些事项影响常用流程或阻塞维护工作，信息基本足够，应在当前维护周期确认负责人并推进。
|
||||
**P2（进入计划处理）：#84、#85。** 问题真实但没有当前阻断证据，建议补充验收条件后进入迭代计划。
|
||||
**P3（可延后或先补信息）：#86、#87。** 影响较低或上下文不足，先请求复现信息、去重或确认需求。
|
||||
|
||||
## 先处理这 3 项
|
||||
|
||||
|
|
@ -57,7 +107,9 @@ description: "GitLink 社区智能审查：审查一个或多个 PR 的贡献价
|
|||
3. <span style="color:#B54708"><strong>[CR-004][high] 收紧权限边界</strong></span>：写操作缺少资源归属校验。
|
||||
```
|
||||
|
||||
Issue 首屏摘要不得展开标题、原因、标签或负责人。颜色只用于最终结论、blocking/high 和关键动作；始终保留 `[action_required]`、`[high]` 等文本回退。
|
||||
示例中的编号、状态和发现仅用于定义格式，实际输出必须从本次 API、Diff、Review 和测试证据重新计算，禁止复制示例结论。
|
||||
|
||||
聊天和 Markdown 中每个 PR 都必须有独立的七方面判断卡，不能把多条 PR 或多个方面合并成一句“修改后再审”。每张卡必须以加粗、着色的结论开头，随后给出简短解释、明确的 `依据：` 和影响/下一步；任何结论都不能单独出现。closed/merged 历史项仍按七方面输出，以 `not_applicable` 说明无需当前门禁。Issue 首屏不逐条展开完整正文，但每个 P 级别必须说明级别含义、编号、本批事项的共同问题和下一步，不能只列计数。颜色只用于状态结论、总建议、blocking/high 和关键动作；始终保留 `[action_required]`、`[high]` 等文本回退。
|
||||
|
||||
## 证据采集
|
||||
|
||||
|
|
@ -143,10 +195,83 @@ gitlink-cli pr +reviews --owner <owner> --repo <repo> --id <pull_request_id> --f
|
|||
|
||||
### 6. 生成 Review 建议
|
||||
|
||||
给出 `建议通过`、`修改后再审`、`暂缓合并` 或 `需要人工判断`，并生成可供维护者编辑的整体 Review 草稿；需要精确定位时生成内联评论草稿。草稿应包含正向评价、阻断问题、证据和最小修复建议。
|
||||
对每个 open PR 分别给出 `建议合并`、`修改后再审`、`暂缓合并` 或 `需要人工判断`，并在报告中生成一份可供维护者直接审核的 Review 草稿。不得只写“测试失败”“实现不完整”等泛化意见，草稿至少包含：
|
||||
|
||||
1. PR 实际解决的问题和已经做对的部分。
|
||||
2. 每个必须修改的问题，包含 `CR-/RV-` 编号、文件与行号或复现命令、当前行为和用户影响。
|
||||
3. 具体修改要求，说明应改哪段逻辑、补什么边界或保持什么兼容行为，而不是只说“请优化”。
|
||||
4. 需要新增或重跑的验证，以及维护者再次 Review 时的通过条件。
|
||||
5. 若不存在阻断项，明确说明建议通过的证据和仍需关注的非阻断风险。
|
||||
|
||||
无论使用预定义结论还是根据仓库语境生成其他结论，都必须给出与结论匹配的依据。常见结论至少遵循以下要求：
|
||||
|
||||
- **建议合并**：先说明 PR 解决的具体问题和实现亮点，再列出已核验的正常、失败、兼容或安全证据，明确没有必须修改的 `blocking/high` 问题；存在非阻断风险时说明为什么不影响当前合并。
|
||||
- **修改后再审**：先肯定已经成立的功能，再逐项指出不合格的文件、逻辑、触发条件和影响，给出具体修改方式、需要补充的测试以及可核验的复审通过条件。
|
||||
- **暂缓合并**：说明当前阻塞来自前置依赖、主线冲突、外部 API、发布窗口还是仓库决策，列出已有证据、继续合并的具体风险、解除阻塞的责任方和重新评估条件。
|
||||
- **需要人工判断**：列出无法由代码事实单独决定的选项和权衡，说明已经确认与仍缺失的证据，并把维护者需要回答的问题写成可执行决策点。
|
||||
- **保持关闭/拒绝**：说明能力是否已被主线或其他 PR 覆盖、问题是否不适合仓库定位，引用对照提交或重复实现证据，并说明为什么继续投入没有增量价值。
|
||||
|
||||
需要精确定位时生成内联评论草稿。多个 PR 的 Review 草稿必须分节，不能共享结论或问题编号。closed/merged 历史 PR 不生成新的 Review 草稿，除非用户明确要求复审历史实现。
|
||||
|
||||
所有 Review 草稿先使用统一结构，结论必须位于具体描述之前：
|
||||
|
||||
```markdown
|
||||
### PR #<number> Review 建议草稿（未提交）
|
||||
**Review 建议：** <span style="color:<status-color>"><strong><结论></strong></span> **[<decision_status>]**：<用 1 至 3 句说明 PR 做了什么、关键证据以及为什么得到该结论。>
|
||||
|
||||
**依据与影响：** <引用 Diff、文件行号、Review、测试命令或主线对照，说明成立的功能、存在的问题和用户/维护者影响。>
|
||||
|
||||
**下一步：** <合并、具体修改与复验、解除依赖或需要维护者决定的问题；没有必改项时明确写出。>
|
||||
```
|
||||
|
||||
例如，“修改后再审”不能只写状态，必须落到可执行问题：
|
||||
|
||||
```markdown
|
||||
### PR #<number> Review 建议草稿（未提交）
|
||||
**Review 建议：** <span style="color:#B42318"><strong>修改后再审</strong></span> **[action_required]**：这项改动解决了 <具体问题>，其中 <已验证的优点> 已有证据；但 `path/file.go:42` 在 <触发条件> 下仍会 <错误行为和影响>，当前不能合并。
|
||||
|
||||
**依据与影响：** [CR-001][high] <当前行为、证据和用户影响>；[RV-001][medium] <既有 Review 未满足部分及证据>。
|
||||
|
||||
**下一步：** 请 <具体修改要求>，新增 <正常/失败/兼容场景> 测试并运行 `<仓库命令>`；确认 <预期结果> 后重新 Review。
|
||||
```
|
||||
|
||||
草稿中的路径、行号、命令和要求必须来自当前 PR 证据；无法定位时标为 `not_verifiable` 并说明缺什么，不得填入示例占位内容。
|
||||
|
||||
无论结论为何，都不得调用远端写接口。最终回复必须明确说明“Review 草稿尚未提交，需人工审核”。
|
||||
|
||||
### 7. 校验报告中的 Review 依据
|
||||
|
||||
PR 审查模式完成 Markdown 后必须运行：
|
||||
|
||||
```bash
|
||||
python -X utf8 skills/gitlink-code-review/scripts/validate_review_report.py \
|
||||
--report <absolute-report-path> \
|
||||
--require-review
|
||||
|
||||
python -X utf8 skills/gitlink-shared/scripts/validate_pr_cards.py \
|
||||
--report <absolute-report-path> \
|
||||
--require-pr <target-number> \
|
||||
--min-cards 7 \
|
||||
--required-aspect "Review 建议" \
|
||||
--required-aspect "贡献价值" \
|
||||
--required-aspect "Review 履约" \
|
||||
--required-aspect "实现与逻辑" \
|
||||
--required-aspect "测试" \
|
||||
--required-aspect "安全" \
|
||||
--required-aspect "关键发现"
|
||||
```
|
||||
|
||||
多个 PR 重复追加 `--require-pr`。两个校验器都通过后才能交付报告并复用首屏卡片作为聊天摘要。
|
||||
|
||||
校验器会拒绝以下输出：
|
||||
|
||||
- `Review 建议` 只有醒目结论和状态，没有在同一字段中紧跟依据。
|
||||
- 依据过短，或没有事实、证据、影响、验证和可执行下一步中的任何一项。
|
||||
- Review 草稿仍使用旧的 `**建议：** 修改后再审` 格式。
|
||||
- 模板占位符没有替换，或 PR 审查报告完全缺少 Review 建议。
|
||||
|
||||
校验失败时必须修改报告并重新执行，直到退出码为 0；不能把未通过校验的 Markdown 路径返回给用户。Issue-only 或仓库健康度-only 模式可以省略 `--require-review`。
|
||||
|
||||
## 仓库健康扫描
|
||||
|
||||
仓库模式至少检查：
|
||||
|
|
@ -162,7 +287,9 @@ gitlink-cli pr +reviews --owner <owner> --repo <repo> --id <pull_request_id> --f
|
|||
|
||||
## 批量 Issue 分诊
|
||||
|
||||
扫描 open、未分类、近期新增或长期未处理的 Issue，按以下维度建立 `IT-` 项：
|
||||
先把用户输入规范化为 `first_n_open`、`all_open` 或 `issue_ids`，并在报告中记录排序、翻页、去重和最终纳入数量。open 范围必须按真实 Issue 状态二次过滤；接口失败时保留已取得页并明确 `partial`，不能用历史样例补足数量。
|
||||
|
||||
扫描纳入范围内未分类、近期新增或长期未处理的 Issue，按以下维度建立 `IT-` 项：
|
||||
|
||||
- 类型：bug、feature、documentation、question、performance、security 或 maintenance。
|
||||
- 优先级：`P0` 立即处置、`P1` 本轮处理、`P2` 计划处理、`P3` 可延后。
|
||||
|
|
@ -174,6 +301,8 @@ gitlink-cli pr +reviews --owner <owner> --repo <repo> --id <pull_request_id> --f
|
|||
|
||||
P0/P1 必须有证据，安全问题避免在报告中复制利用细节或敏感值。默认只生成建议；标签、分配、回复、关闭和其他写操作必须经过人工审核和新的明确授权。
|
||||
|
||||
聊天摘要和报告中的 Issue 分诊均按以下形式输出：`级别（处置含义）：编号；本批事项概述；建议下一步`。概述必须来自本批 Issue 的标题、正文、标签、响应状态和等待方，不能复制通用定义冒充分析。相同原因可以合并描述，特殊的 P0/P1 单独指出。
|
||||
|
||||
## 发现与严重性
|
||||
|
||||
每条 `CR-` 发现必须包含严重性、事实类型、文件与行号或复现命令、触发条件、影响、证据、最小修复建议和验证限制。
|
||||
|
|
@ -185,12 +314,14 @@ P0/P1 必须有证据，安全问题避免在报告中复制利用细节或敏
|
|||
|
||||
没有精确证据的内容只能标记 `candidate`，不能升级为 blocking。纯格式偏好和可自动修复的低价值问题不得进入首屏。
|
||||
|
||||
首屏按严重性给出 `级别含义 + 数量/编号 + 本批问题摘要`。数量为 0 时简要说明未发现该级别的已证实问题；数量大于 0 时至少概括最影响决策的一类问题，不能只输出 `blocking 0 | high 1`。
|
||||
|
||||
## 单一 Markdown 报告顺序
|
||||
|
||||
1. 首屏审查结论、Review 建议、门禁、Review 履约统计、Issue 优先级计数和最多五项动作。
|
||||
1. 首屏按 PR 分开的实质性 Review 参考、带依据门禁、代码发现说明、Issue 分级说明和最多五项动作。
|
||||
2. PR 目标、贡献价值和变更概览。
|
||||
3. `RV-` Review 修改履约明细。
|
||||
4. 完整 `CR-` 代码审查、正向证据和 Review 草稿。
|
||||
4. 每个 open PR 独立的完整 `CR-` 代码审查、正向证据和可供人工审核的 Review 草稿。
|
||||
5. 构建、测试、功能验证和验证限制。
|
||||
6. `RH-` 仓库代码健康度。
|
||||
7. `IT-` Issue 分诊详细结果。
|
||||
|
|
@ -200,11 +331,14 @@ P0/P1 必须有证据，安全问题避免在报告中复制利用细节或敏
|
|||
|
||||
## 完成前自检
|
||||
|
||||
- 首屏是否先给结论，且最多只有五项会改变维护者决策的动作。
|
||||
- 聊天回复和 Markdown 首屏是否都按 PR 分节，并完整保留七方面结论前置判断卡。
|
||||
- 每张卡是否在醒目结论后紧跟简短解释、明确 `依据：` 和影响/下一步；无论结论为何都没有只写状态。
|
||||
- 是否完整分析实际相关维度，而不是机械限制为五项。
|
||||
- 是否区分完整 PR Diff 与 Review 后增量 Diff。
|
||||
- 每条有效 Review 是否有 `RV-` 状态、证据和剩余动作。
|
||||
- Review 建议和草稿是否只写入报告，没有提交远端。
|
||||
- 仓库健康扫描和 Issue 分诊是否在请求时保留，Issue 详情是否位于报告最后。
|
||||
- PR 审查报告是否同时通过 `validate_review_report.py --require-review` 和 `validate_pr_cards.py` 七方面校验。
|
||||
- 仓库健康扫描和 Issue 分诊是否在请求时保留，Issue 范围是否明确为前 N 条、全部 open 或指定编号，Issue 详情是否位于报告最后。
|
||||
- blocking/high 是否有可复现证据，未执行测试是否标为 `not_run`。
|
||||
- 是否生成一份 UTF-8 Markdown，并在最终回复中给出绝对路径和一句话结论。
|
||||
- Issue 的聊天直接输出是否解释 P0/P1/P2/P3 的处置含义、对应编号、本批问题概述和下一步，而不是只列级别与编号。
|
||||
- 是否生成一份 UTF-8 Markdown，并在最终回复中给出审查结论、Issue 分诊说明、Review 草稿状态和绝对路径。
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
interface:
|
||||
display_name: "社区智能审查"
|
||||
short_description: "验证 PR、Review 修改、仓库健康和 Issue 分诊，生成决策优先报告。"
|
||||
default_prompt: "使用 $gitlink-code-review 审查指定 GitLink PR，验证已有 Review 的修改情况，并生成结论前置、详情完整且不回写远端的 Markdown 报告。"
|
||||
default_prompt: "使用 $gitlink-code-review 审查指定 GitLink PR；聊天和 Markdown 均按 PR 分节，将 Review 建议、贡献价值、Review 履约、实现与逻辑、测试、安全和关键发现分别做成结论前置判断卡，后接依据与影响；Issue 分级另行说明，不回写远端。"
|
||||
|
|
|
|||
|
|
@ -24,9 +24,14 @@ $context | Set-Content .\pr-123-context.json -Encoding utf8
|
|||
## 首屏输出
|
||||
|
||||
```markdown
|
||||
# PR #123 代码审查摘要
|
||||
**结论：** 需要补充验证 **[action_required]**
|
||||
**证据：** 当前 head `abcdef1` | CI SHA 匹配 `1/1` | 安全 `partial`
|
||||
## PR #123
|
||||
**Review 建议：** <span style="color:#B54708"><strong>修改后再审</strong></span> **[action_required]**：失败路径和错误输出仍可能影响真实用户；依据：CR-001、CR-002 以及缺失的脱敏测试；下一步：修复并按当前 head 复验。
|
||||
**贡献价值：** <span style="color:#067647"><strong>目标问题真实且增量明确</strong></span> **[passed]**：新增能力填补默认分支缺口；依据：Issue、baseline Diff 和受益范围；影响：减少维护者人工步骤。
|
||||
**Review 履约：** <span style="color:#067647"><strong>既有意见已经满足</strong></span> **[passed]**：作者修复了错误映射并补正常路径测试；依据：Review 后提交、当前代码和 RV-001；影响：没有遗留 Review 阻断。
|
||||
**实现与逻辑：** <span style="color:#067647"><strong>主流程行为正确</strong></span> **[passed]**：当前 head 的核心路径运行成功；依据：CI 按 SHA 匹配 `1/1` 和复现命令；影响：声明功能可用。
|
||||
**测试：** <span style="color:#B54708"><strong>失败路径覆盖不完整</strong></span> **[partial]**：异常输入没有回归用例；依据：测试文件和测试清单；下一步：补失败与兼容测试。
|
||||
**安全：** <span style="color:#B54708"><strong>脱敏行为尚未证明</strong></span> **[partial]**：Diff 可定位敏感输出风险；依据：错误路径和缺失的脱敏断言；下一步：验证日志不泄露敏感值。
|
||||
**关键发现：** <span style="color:#B54708"><strong>2 项问题需要处理</strong></span> **[high]**：失败路径和敏感输出会影响合并判断；依据：CR-001、CR-002；下一步：修复后按同一 head 复验。
|
||||
|
||||
## 先做这 2 件事
|
||||
1. **[CR-001][high] 补充** 失败路径测试（责任：作者；证据：`E-CR-001`）。
|
||||
|
|
|
|||
|
|
@ -10,14 +10,28 @@ gitlink-cli pr +reviews --owner Gitlink --repo gitlink-cli --id 123 --format jso
|
|||
```
|
||||
|
||||
```markdown
|
||||
# PR #123 代码审查摘要
|
||||
**结论：** <span style="color:#B54708"><strong>需要补验证</strong></span> **[action_required]**
|
||||
**安全门禁：** 部分完成 | **验证：** 部分完成 | **问题：** high 1 / medium 2
|
||||
## PR #123
|
||||
**Review 建议：** <span style="color:#B54708"><strong>修改后再审</strong></span> **[action_required]**：批量操作入口和帮助文档已经形成完整主流程，但输入边界可能产生不可诊断错误或跨平台回归；依据：无权限请求、恶意路径和 Windows 中文错误输出尚未验证；下一步：补齐实现和测试后复看。
|
||||
**贡献价值：** <span style="color:#067647"><strong>功能增量成立</strong></span> **[passed]**：PR 补齐高频批量操作，默认分支没有等价入口；依据：需求、Diff、帮助文本和受益范围；影响：减少重复人工操作。
|
||||
**Review 履约：** <span style="color:#175CD3"><strong>本轮没有待核对意见</strong></span> **[not_applicable]**：未发现有效 Review；依据：Review 列表与当前 head SHA；影响：本轮只评价完整 Diff。
|
||||
**实现与逻辑：** <span style="color:#B54708"><strong>正常路径可用但边界不完整</strong></span> **[partial]**：权限失败和恶意路径没有可靠处理证据；依据：实现分支与复现清单；下一步：补错误映射和输入校验。
|
||||
**测试：** <span style="color:#B54708"><strong>关键失败路径缺测</strong></span> **[partial]**：现有测试只覆盖成功流程；依据：测试文件和执行结果；下一步：补权限、非法路径和 Windows UTF-8 回归。
|
||||
**安全：** <span style="color:#B54708"><strong>输入边界未完整验证</strong></span> **[partial]**：改动触及路径和权限输入；依据：Diff 与安全矩阵仅覆盖部分场景；下一步：补恶意输入和无权限测试。
|
||||
**关键发现：** <span style="color:#B54708"><strong>1 项 high 与 2 项 medium 待处理</strong></span> **[high]**：问题集中在权限失败和跨平台边界；依据：CR-001 至 CR-003；下一步：先修 high 再完成编码回归。
|
||||
|
||||
**代码发现：**
|
||||
- **blocking（阻止合并）：0 条。** 未发现已证实的漏洞或数据破坏。
|
||||
- **high（本轮必须修复）：1 条，CR-001。** 权限失败路径缺失，可能让无权限请求得到错误结果。
|
||||
- **medium（应补齐后复看）：2 条，CR-002、CR-003。** Windows 中文错误和 API 回滚行为没有验证。
|
||||
- **low（可延后优化）：0 条。**
|
||||
|
||||
## 先做这 3 件事
|
||||
1. **[CR-001][high] 补充** 恶意路径和无权限请求测试（责任：作者）。
|
||||
2. **[CR-002][medium] 验证** Windows PowerShell 下的中文错误输出（责任：作者）。
|
||||
3. **[CR-003][medium] 复看** API 失败时的回滚行为（责任：维护者）。
|
||||
|
||||
### PR #123 Review 建议草稿（未提交）
|
||||
**Review 建议：** <span style="color:#B54708"><strong>修改后再审</strong></span> **[action_required]**：批量操作入口和帮助文档已经形成完整主流程，但合并前需要补齐无权限请求、恶意路径和 Windows 中文错误输出，这些未验证边界会影响错误诊断和跨平台可用性。请在 `shortcuts/example/example.go:42` 保留当前正常路径，同时对无权限响应返回可诊断错误，并新增失败路径与 Windows UTF-8 回归测试。完成后运行 `go test ./shortcuts/example -count=1`，确认成功、无权限和非法路径三类场景均通过，再提交复看。
|
||||
```
|
||||
|
||||
## 关键验证
|
||||
|
|
|
|||
|
|
@ -72,6 +72,14 @@ gitlink-cli pr +reviews --id 42 --format json
|
|||
```markdown
|
||||
## PR #42 代码审查报告
|
||||
|
||||
**Review 建议：** <span style="color:#B42318"><strong>修复安全阻断后再审</strong></span> **[action_required]**：认证实现存在硬编码凭据和 SQL 注入风险；依据：CR-42-001、CR-42-002 与精确代码位置；下一步：完成参数化查询、密钥外置和安全回归后复看。
|
||||
**贡献价值：** <span style="color:#067647"><strong>认证能力具有实际价值</strong></span> **[passed]**：PR 提供登录和 Token 流程；依据：需求、模块 Diff 和主要使用路径；影响：形成可用的认证入口。
|
||||
**Review 履约：** <span style="color:#175CD3"><strong>没有既有意见可核对</strong></span> **[not_applicable]**：本轮没有有效 Review；依据：Review 列表和当前 head；影响：直接审查完整实现。
|
||||
**实现与逻辑：** <span style="color:#B42318"><strong>认证边界不安全</strong></span> **[failed]**：查询直接拼接输入且密码处理不正确；依据：`src/auth/login.py:42`、`src/auth/login.py:88`；下一步：参数化查询并使用安全哈希。
|
||||
**测试：** <span style="color:#B54708"><strong>安全与边界用例不足</strong></span> **[partial]**：已有测试覆盖主要成功路径；依据：`tests/test_auth.py` 和测试清单；下一步：补注入、空值、超长输入和过期 Token。
|
||||
**安全：** <span style="color:#B42318"><strong>存在两个阻断级风险</strong></span> **[failed]**：硬编码密钥和 SQL 注入可被直接触发；依据：`src/config.py:15`、`src/auth/login.py:42`；下一步：移除凭据并使用参数化 API。
|
||||
**关键发现：** <span style="color:#B42318"><strong>2 项 blocking 必须先修复</strong></span> **[blocking]**：CR-42-001、CR-42-002 会影响数据和凭据安全；依据：代码证据和攻击路径；下一步：阻断合并直到安全测试通过。
|
||||
|
||||
### 🔴 Critical
|
||||
|
||||
1. **JWT Secret 硬编码** — `src/config.py:15`
|
||||
|
|
|
|||
|
|
@ -0,0 +1,75 @@
|
|||
#!/usr/bin/env python3
|
||||
"""Validate that a code-review report gives evidence-backed Review advice."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
REVIEW_PREFIX = "**Review 建议：**"
|
||||
LEGACY_PREFIX = "**建议：**"
|
||||
REVIEW_PATTERN = re.compile(
|
||||
r"^\*\*Review 建议：\*\*\s*"
|
||||
r"<span\b[^>]*><strong>([^<]+)</strong></span>\s*"
|
||||
r"\*\*\[([^\]]+)\]\*\*：\s*(\S.*)$"
|
||||
)
|
||||
REVIEW_DRAFT_HEADING = re.compile(r"^### PR #\d+ Review 建议草稿（未提交）\s*$")
|
||||
EVIDENCE_MARKERS = ("依据", "测试", "Diff", "文件", "行号", "CR-", "RV-", "实现", "影响", "主线", "API", "命令", "已核验", "未发现", "通过", "失败", "缺少", "需要")
|
||||
PLACEHOLDER_MARKERS = ("<结论>", "<具体", "<status-", "<decision_")
|
||||
|
||||
|
||||
def validate_report(text: str, require_review: bool = False) -> list[str]:
|
||||
errors: list[str] = []
|
||||
review_lines: list[int] = []
|
||||
lines = text.splitlines()
|
||||
for line_number, line in enumerate(lines, start=1):
|
||||
stripped = line.strip()
|
||||
if stripped.startswith(LEGACY_PREFIX):
|
||||
errors.append(f"line {line_number}: legacy conclusion-only field is not allowed")
|
||||
if not stripped.startswith(REVIEW_PREFIX):
|
||||
continue
|
||||
review_lines.append(line_number)
|
||||
match = REVIEW_PATTERN.match(stripped)
|
||||
if not match:
|
||||
errors.append(f"line {line_number}: Review decision requires a status tag and rationale")
|
||||
continue
|
||||
conclusion, status, rationale = match.groups()
|
||||
if not conclusion.strip() or not status.strip() or len(rationale.strip()) < 30:
|
||||
errors.append(f"line {line_number}: Review rationale is too short")
|
||||
if not any(marker in rationale for marker in EVIDENCE_MARKERS):
|
||||
errors.append(f"line {line_number}: Review rationale lacks evidence or an actionable next step")
|
||||
if any(marker in rationale for marker in PLACEHOLDER_MARKERS):
|
||||
errors.append(f"line {line_number}: unresolved template placeholder in rationale")
|
||||
for index, line in enumerate(lines):
|
||||
if REVIEW_DRAFT_HEADING.match(line.strip()) and not any(candidate.strip().startswith(REVIEW_PREFIX) for candidate in lines[index + 1:index + 7]):
|
||||
errors.append(f"line {index + 1}: Review draft must start with a substantive Review suggestion")
|
||||
if require_review and not review_lines:
|
||||
errors.append("PR review mode requires at least one substantive Review decision")
|
||||
return errors
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description="Validate substantive Review decisions.")
|
||||
parser.add_argument("--report", required=True, type=Path)
|
||||
parser.add_argument("--require-review", action="store_true")
|
||||
args = parser.parse_args()
|
||||
try:
|
||||
text = args.report.read_text(encoding="utf-8", errors="strict")
|
||||
except (OSError, UnicodeError) as exc:
|
||||
print(f"review report validation failed: {exc}", file=sys.stderr)
|
||||
return 2
|
||||
errors = validate_report(text, args.require_review)
|
||||
if errors:
|
||||
print("review report validation failed:", file=sys.stderr)
|
||||
for error in errors:
|
||||
print(f"- {error}", file=sys.stderr)
|
||||
return 1
|
||||
print("review report validation passed")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
|
|
@ -32,17 +32,27 @@ gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <num
|
|||
- 只读运行，不评论、不催办、不标记已读、不改标签、不分配、不关闭、不修改远端。
|
||||
- 使用 `MR-001` 起的稳定编号，记录对象、等待方、超时证据、紧迫度、影响、置信度和建议动作。
|
||||
- 首屏先显示今天直接能执行的最多 5 项动作；HOT、高风险和安全运营事项使用颜色和粗体。
|
||||
- 聊天和报告首屏按 PR 分节；响应 SLA、等待方、Reviewer 负载、责任停滞、安全运营优先级、维护动作分别使用结论前置判断卡，后接解释、`依据：` 和影响/下一步。
|
||||
- 一次运行只生成一份 UTF-8 Markdown，保存到 `reports/skill-runs/gitlink-maintainer-radar/<owner>-<repo>-<scope>-<yyyyMMdd-HHmmssZ>.md`；完整队列与负载明细放同一文件附录。
|
||||
- 报告文件是完成条件，不是可选附件。必须先确定本轮唯一绝对路径、写入完整报告并通过 `validate_radar_report.py`，之后才能发送聊天结论。
|
||||
|
||||
无法写入工作区时输出完整 Markdown 并标记“未落盘”。最终回复给出报告绝对路径、HOT 数、超 SLA 数和第一待办。
|
||||
最终回复按 PR 复用报告首屏六方面判断卡，再给报告绝对路径；不得把多个 PR 或多个治理方面压成一段。正常可写工作区中不得以“已在聊天输出”为由跳过落盘，也不得返回上一轮旧报告路径。写入失败时先创建父目录并使用明确 UTF-8；只有文件系统确实不可写时才允许输出完整 Markdown 并标记“未落盘”。
|
||||
|
||||
首屏固定先使用：
|
||||
|
||||
```markdown
|
||||
# 维护者值班摘要
|
||||
|
||||
**结论：** <span style="color:#B42318"><strong>今日需处理</strong></span> **[action_required]**
|
||||
**队列：** HOT 4 | WATCH 6 | 超 SLA 3 | reviewer 瓶颈 1 | 安全 HOT 1
|
||||
**队列事实：** 扫描 open PR <n> 条，目标 PR <n> 条，数据完整性 <status>。
|
||||
**判定依据：** 固定 `as_of`、当前状态、活动时间和分配关系；详细结论按 PR 展示。
|
||||
|
||||
## PR #123
|
||||
**响应 SLA：** <span style="color:#B42318"><strong>已超时 24 小时</strong></span> **[hot]**：等待 review 共 96 小时；依据：创建时间、最近活动和 72 小时阈值；影响：进入今日优先队列。
|
||||
**等待方：** <span style="color:#B54708"><strong>当前等待 reviewer</strong></span> **[action_required]**：作者已经更新且没有新 Review；依据：最后提交、Review 状态和分配关系；下一步：提醒或转派 reviewer。
|
||||
**Reviewer 负载：** <span style="color:#B54708"><strong>当前 reviewer 过载</strong></span> **[high]**：名下积压 5 条待审 PR；依据：同一快照的 reviewer 待办计数；影响：建议释放容量。
|
||||
**责任停滞：** <span style="color:#B42318"><strong>责任明确但长期无动作</strong></span> **[hot]**：分配后 4 天没有推进；依据：assignee/reviewer 与最后活动时间；下一步：确认接单或转派。
|
||||
**安全运营优先级：** <span style="color:#B42318"><strong>需要优先安排安全复看</strong></span> **[high]**：改动触及权限路径；依据：文件范围和已有安全标记，不代表漏洞成立；影响：优先匹配安全 reviewer。
|
||||
**维护动作：** <span style="color:#B42318"><strong>今天完成转派并启动复看</strong></span> **[action_required]**：该 PR 同时超 SLA 且责任停滞；依据：MR-001 与上述时间/负载证据；下一步：维护者确认 reviewer。
|
||||
|
||||
## 先做这 3 件事
|
||||
|
||||
|
|
@ -51,6 +61,8 @@ gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <num
|
|||
3. <span style="color:#B54708"><strong>[MR-003][high] 复看</strong></span> PR #118；等待：maintainer。
|
||||
```
|
||||
|
||||
指定多个 PR 时重复 `## PR #<number>` 和六张卡。队列级计数仅作为范围元数据，不能代替逐 PR 判断。
|
||||
|
||||
这个 skill 不再做“把通知列表抄一遍”的弱摘要，而是把三类真正影响维护者效率的治理信号合在一起：
|
||||
|
||||
1. **响应时效雷达**：找出超出响应 SLA 的 Issue 和 PR。
|
||||
|
|
@ -90,14 +102,13 @@ gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <num
|
|||
|
||||
```markdown
|
||||
# 维护者值班摘要
|
||||
**结论：** <span style="color:#B42318"><strong>今日需处理</strong></span> **[action_required]**
|
||||
**队列：** HOT 4 | WATCH 6 | reviewer 瓶颈 1 | 安全 HOT 1
|
||||
|
||||
## 先做这 4 件事
|
||||
1. **[MR-001][blocking] 转派** PR #123 的安全复查，当前等待 reviewer（责任：维护者）。
|
||||
2. **[MR-002][high] 回复** Issue #87，首响已超 24 小时（责任：维护者）。
|
||||
3. **[MR-003][high] 复看** 作者更新后的 PR #118（责任：reviewer）。
|
||||
4. **[MR-004][medium] 确认** Issue #91 是否继续推进（责任：assignee）。
|
||||
## PR #123
|
||||
**响应 SLA：** <span style="color:#B42318"><strong>已超过 Review SLA</strong></span> **[hot]**：等待 96 小时；依据：固定扫描时间与最后活动；影响：今天处理。
|
||||
**等待方：** <span style="color:#B54708"><strong>等待 reviewer</strong></span> **[action_required]**：作者已更新；依据：提交和 Review 状态；下一步：安排复看。
|
||||
**Reviewer 负载：** <span style="color:#B54708"><strong>分配存在瓶颈</strong></span> **[high]**：当前 reviewer 积压较多；依据：同一快照待审计数；下一步：考虑转派。
|
||||
**责任停滞：** <span style="color:#B42318"><strong>已分配但无推进</strong></span> **[hot]**：责任关系存在但四天无动作；依据：分配与活动时间；下一步：确认接单。
|
||||
**安全运营优先级：** <span style="color:#B54708"><strong>需要安全复看</strong></span> **[high]**：涉及权限路径；依据：改动文件与风险标签；影响：匹配专项 reviewer。
|
||||
**维护动作：** <span style="color:#B42318"><strong>今天转派并复看</strong></span> **[action_required]**：同时命中超时和停滞；依据：MR-001；下一步：维护者执行分派。
|
||||
```
|
||||
|
||||
如果没有 open PR 或 open Issue，明确报告“没有可分析的 open PR/Issue”；如果消息接口失败，不得用通知列表代替协作队列，也不得伪造 SLA。
|
||||
|
|
@ -259,6 +270,26 @@ gitlink-cli pr +version-diff --owner <owner> --repo <repo> -i <number> --format
|
|||
4. 今天建议先做的动作
|
||||
5. 可延后的背景项
|
||||
|
||||
保存后必须运行：
|
||||
|
||||
```bash
|
||||
python -X utf8 skills/gitlink-maintainer-radar/scripts/validate_radar_report.py \
|
||||
--report <absolute-report-path>
|
||||
|
||||
python -X utf8 skills/gitlink-shared/scripts/validate_pr_cards.py \
|
||||
--report <absolute-report-path> \
|
||||
--require-pr <target-number> \
|
||||
--min-cards 6 \
|
||||
--required-aspect "响应 SLA" \
|
||||
--required-aspect "等待方" \
|
||||
--required-aspect "Reviewer 负载" \
|
||||
--required-aspect "责任停滞" \
|
||||
--required-aspect "安全运营优先级" \
|
||||
--required-aspect "维护动作"
|
||||
```
|
||||
|
||||
多个目标重复 `--require-pr`。校验会确认目标文件真实存在、可按严格 UTF-8 读取，并且每个 PR 都有六方面结论前置判断卡。失败时必须补写或修复报告并重新校验，不能直接结束任务。
|
||||
|
||||
推荐输出模板：
|
||||
|
||||
```markdown
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
interface:
|
||||
display_name: "维护者雷达"
|
||||
short_description: "识别响应超时、review 失衡和责任停滞，生成维护者处置面板。"
|
||||
default_prompt: "使用 $gitlink-maintainer-radar 扫描指定 GitLink 仓库。按 Skill 默认契约只读生成维护者优先待办，并保存关键结论前置的单一 Markdown 报告。"
|
||||
default_prompt: "使用 $gitlink-maintainer-radar 扫描指定 GitLink 仓库或 PR；聊天和 Markdown 均按 PR 分节，将响应 SLA、等待方、Reviewer 负载、责任停滞、安全运营优先级、维护动作分别做成结论前置判断卡，后接依据与影响；保存并校验 UTF-8 报告，全程只读。"
|
||||
|
|
|
|||
|
|
@ -8,8 +8,17 @@ gitlink-cli api GET users/<login>/messages.json --query "status=1&limit=40" --fo
|
|||
|
||||
```markdown
|
||||
# 维护者值班摘要
|
||||
**结论：** <span style="color:#B42318"><strong>今日需处理</strong></span> **[action_required]**
|
||||
**队列：** HOT 3 | WATCH 5 | reviewer 瓶颈 1 | 安全 HOT 1
|
||||
|
||||
**队列事实：** 扫描 open PR 12 条、open Issue 8 条，时间基线为 `2026-07-23T08:00:00Z`。
|
||||
**判定依据：** 当前状态、创建和最后活动时间、Review、reviewer/assignee 与配置 SLA。
|
||||
|
||||
## PR #123
|
||||
**响应 SLA：** <span style="color:#B42318"><strong>Review 已超时</strong></span> **[hot]**：等待 reviewer 96 小时，超过 72 小时阈值；依据：固定扫描时间和最后有效活动；影响：进入今日优先队列。
|
||||
**等待方：** <span style="color:#B54708"><strong>当前等待 reviewer</strong></span> **[action_required]**：作者已提交修复但尚无复看结论；依据：最后提交晚于最后 Review；下一步：提醒或转派 reviewer。
|
||||
**Reviewer 负载：** <span style="color:#B54708"><strong>现有分配形成瓶颈</strong></span> **[high]**：当前 reviewer 同时积压 5 条待审 PR；依据：同一快照内的待审计数；影响：继续等待风险较高。
|
||||
**责任停滞：** <span style="color:#B42318"><strong>责任明确但长期无推进</strong></span> **[hot]**：分配后 4 天没有动作；依据：reviewer 分配时间与活动时间线；下一步：确认接单或释放责任。
|
||||
**安全运营优先级：** <span style="color:#B42318"><strong>需要优先安排安全复看</strong></span> **[high]**：改动触及认证路径但不代表漏洞成立；依据：文件范围和已有安全标记；影响：应匹配安全 reviewer。
|
||||
**维护动作：** <span style="color:#B42318"><strong>今天完成转派并启动复看</strong></span> **[action_required]**：超 SLA、负载瓶颈和安全关注同时存在；依据：MR-001 至 MR-003；下一步：维护者指定可用 reviewer。
|
||||
|
||||
## 先做这 3 件事
|
||||
1. **[MR-001][blocking] 转派** PR #123 的安全复查，当前等待 reviewer（责任：维护者）。
|
||||
|
|
|
|||
|
|
@ -0,0 +1,60 @@
|
|||
#!/usr/bin/env python3
|
||||
"""Validate that maintainer-radar saves a usable UTF-8 Markdown report."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
REQUIRED_MARKERS = (
|
||||
"# 维护者值班摘要",
|
||||
"**队列事实：**",
|
||||
"**判定依据：**",
|
||||
"## PR #",
|
||||
"**响应 SLA：**",
|
||||
"**等待方：**",
|
||||
"**Reviewer 负载：**",
|
||||
"**责任停滞：**",
|
||||
"**安全运营优先级：**",
|
||||
"**维护动作：**",
|
||||
"MR-",
|
||||
)
|
||||
|
||||
|
||||
def validate_report(text: str) -> list[str]:
|
||||
errors: list[str] = []
|
||||
if "\ufffd" in text or "\x00" in text or "\x1b" in text:
|
||||
errors.append("report contains invalid encoding or ANSI control characters")
|
||||
for marker in REQUIRED_MARKERS:
|
||||
if marker not in text:
|
||||
errors.append(f"missing radar report marker: {marker}")
|
||||
cjk_count = len(re.findall(r"[\u3400-\u9fff]", text))
|
||||
if cjk_count < 60:
|
||||
errors.append(f"radar narrative is incomplete: found {cjk_count} CJK characters, need at least 60")
|
||||
return errors
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description="Validate a saved maintainer-radar report.")
|
||||
parser.add_argument("--report", required=True, type=Path)
|
||||
args = parser.parse_args()
|
||||
try:
|
||||
text = args.report.read_text(encoding="utf-8", errors="strict")
|
||||
except (OSError, UnicodeError) as exc:
|
||||
print(f"radar report validation failed: {exc}", file=sys.stderr)
|
||||
return 2
|
||||
errors = validate_report(text)
|
||||
if errors:
|
||||
print("radar report validation failed:", file=sys.stderr)
|
||||
for error in errors:
|
||||
print(f"- {error}", file=sys.stderr)
|
||||
return 1
|
||||
print(f"radar report validation passed: {args.report.resolve()}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
|
|
@ -11,9 +11,9 @@ description: "五个 GitLink 维护 Skill 的只读编排器：用户只需点
|
|||
|
||||
| 阶段 | Skill | 输出重点 |
|
||||
|---|---|---|
|
||||
| 并行 | `gitlink-code-review` | `CR-` 代码正确性、测试覆盖和代码级安全问题 |
|
||||
| 并行 | `gitlink-code-review` | `CR-/RV-` 贡献价值、代码正确性、Review 履约、测试、安全，以及按需健康扫描/Issue 分诊 |
|
||||
| 并行 | `gitlink-cli-contract-guard` | `CG-` flags、help、JSON、错误、退出码和 CLI 边界契约 |
|
||||
| 并行 | `gitlink-pr-topology` | `TP-` PR 之间的依赖、重叠、替代、冲突和处理顺序 |
|
||||
| 并行 | `gitlink-pr-topology` | `TP-` 目标 PR 与主线源码、全部 open/merged PR 的依赖、继承、重叠、替代、冲突、互补和处理顺序 |
|
||||
| 串行 | `gitlink-pr-integrator` | `IN-` 合并态、构建测试、安全和集成门禁 |
|
||||
| 串行 | `gitlink-maintainer-radar` | `MR-` 等待方、SLA、reviewer 负载和维护者待办 |
|
||||
|
||||
|
|
@ -28,19 +28,41 @@ description: "五个 GitLink 维护 Skill 的只读编排器：用户只需点
|
|||
- 共享一次队列快照和每个目标 PR 的固定 head 上下文，编排五个专项 Skill；不要求用户逐条重复五个 Skill 的提示词。
|
||||
- 全流程只读，不评论、不 approve、不合并、不关闭、不分配、不修改标签或权限。
|
||||
- 单 PR 和多 PR 都支持；多 PR 先做队列级拓扑/维护排序，再对重点 PR 逐条做代码、契约和集成检查，不能混合 Diff。
|
||||
- 首屏只保留一个最终决策、关键门禁、最多 5 项跨专项去重后的动作和责任方；直接影响评审的 blocking/high 使用颜色和粗体。
|
||||
- 报告首屏先按 PR 分节；每条 PR 分别显示代码审查、CLI 契约、仓库关系、集成门禁、维护状态和最终结论六张判断卡。聊天结论也按 PR 和这六个方面组织，但必须重新提炼成更短的维护者语言。
|
||||
- 每张卡先显示醒目加粗结论，再写简短解释、明确 `依据：` 和影响/下一步；不得把五个专项压成一段或把多个 PR 合并总结。
|
||||
- 人读 `final-report.md` 必须使用中文叙述；命令名、路径、稳定编号和机器状态枚举可以保留英文。每个阶段的 `assessment.fact` 与 `assessment.basis` 在交给 finalize 前先转成忠实的中文摘要，不能把整份英文阶段报告直接拼入。
|
||||
- 一次运行只生成一份主要人读报告 `<run-directory>/final-report.md`。五个专项 JSON 和 `final-report.json` 作为机器证据附件，不再让维护者阅读五份独立长 Markdown。
|
||||
|
||||
最终回复只给出 `final-report.md` 的绝对路径、最终决策、阻断数和第一动作。若无法落盘，输出完整 Markdown 并标记“未落盘”。
|
||||
最终回复必须由执行 Skill 的 Agent 在读完 `final-report.md` 和 `final-report.json` 后重新提炼，不能复制报告首屏、不能机械删除 Markdown/HTML 格式、不能把卡片原文改成纯文本后直接输出。聊天摘要要比报告更短，按每个 PR 输出六个方面的结论、最关键依据和解释/影响，每个方面一至两句完整自然语言；省略路径清单、阶段索引、分页过程、机器状态标签和次要证据。全部 PR 摘要后再给最多五项跨专项动作，并用可点击链接或当前 Agent 平台的文件附件交付 `final-report.md`。若无法落盘，输出完整 Markdown 并标记“未落盘”。
|
||||
|
||||
聊天摘要示例只表达风格，不是可复制模板：
|
||||
|
||||
```text
|
||||
PR #430
|
||||
代码审查：建议修改后再审。它补齐维护队列的真实状态过滤，但当前 fixture 仍显示 closed 项会进入 open 队列，这会直接误导维护者的待审范围。
|
||||
CLI 契约：需要先稳定字段语义。新增 changes、waiting_on 和 SLA 字段有实际价值，但空值、兼容回退和错误提示还要和主线帮助/JSON 输出对齐。
|
||||
仓库关系：适合排在 #431 前面评审。#431 会消费 #430 的队列字段，所以先确认 #430 的运行时契约，可以减少后续 Skill 协议返工。
|
||||
集成门禁：暂时不能进入合并队列。构建和基础测试可以作为正向证据，但真实队列过滤失败仍是集成前必须修复的问题。
|
||||
维护状态：当前主要等待作者修复。维护者最需要检查的是过滤逻辑、字段空值和回归测试是否补齐。
|
||||
最终结论：先修复再复审。这个 PR 的方向成立，但真实队列可信度是它能否合入的前提。
|
||||
|
||||
完整报告：[final-report.md](D:\path\to\final-report.md)
|
||||
```
|
||||
|
||||
最终聊天不能只回复路径、状态计数或跨 PR 总段落。Markdown 能使用醒目颜色和加粗；聊天摘要除必要的 PR 编号、证据编号和最终报告链接外，不输出 HTML/Markdown 展示标签。
|
||||
|
||||
首屏固定先使用：
|
||||
|
||||
```markdown
|
||||
# PR 维护全流程摘要
|
||||
|
||||
**结论：** <span style="color:#B42318"><strong>已阻断</strong></span> **[blocked]**
|
||||
**门禁：** 代码 `failed` | 契约 `passed` | 拓扑 `reorder` | 集成 `blocked` | 维护 `action_required`
|
||||
**风险：** blocking 1 | high 2 | security `failed` | verification `partial`
|
||||
## PR #<number>
|
||||
**代码审查：** <span style="color:#B42318"><strong>核心队列结果不可靠</strong></span> **[action_required]**：closed 项进入 open 响应；依据：CR-001 与真实 fixture；下一步：修复过滤并补测试。
|
||||
**CLI 契约：** <span style="color:#067647"><strong>新增字段保持向后兼容</strong></span> **[passed]**：字段可选且旧调用不变；依据：CG 对照和 golden 输出；影响：现有脚本无需迁移。
|
||||
**仓库关系：** <span style="color:#175CD3"><strong>需要先稳定上游契约</strong></span> **[reorder]**：存在字段生产/消费关系；依据：主线、全部 open/merged PR 索引；影响：调整评审顺序。
|
||||
**集成门禁：** <span style="color:#B42318"><strong>当前不能进入合并队列</strong></span> **[blocked]**：真实响应测试失败；依据：IN-001 和当前 head 验证；下一步：修复后重跑。
|
||||
**维护状态：** <span style="color:#B54708"><strong>等待作者修复后复看</strong></span> **[action_required]**：责任链明确；依据：Review、提交和 SLA 快照；下一步：作者更新后通知 reviewer。
|
||||
**最终结论：** <span style="color:#B42318"><strong>修复真实状态过滤后重新审查</strong></span> **[blocked]**：存在一个阻断和两个高风险项；依据：CR-001、IN-001、MR-001；下一步：按动作顺序处理。
|
||||
|
||||
## 先处理这 3 项
|
||||
|
||||
|
|
@ -49,6 +71,8 @@ description: "五个 GitLink 维护 Skill 的只读编排器：用户只需点
|
|||
3. <span style="color:#B54708"><strong>[MR-001][high] 转派</strong></span> 安全复查；责任：maintainer。
|
||||
```
|
||||
|
||||
多个 PR 重复完整六张卡，每张卡只能引用该 PR 的证据。跨 PR 动作放在全部 PR 卡片之后。
|
||||
|
||||
## 编排流程
|
||||
|
||||
```mermaid
|
||||
|
|
@ -84,14 +108,23 @@ flowchart TD
|
|||
|
||||
### 2. 采集一次、复用证据
|
||||
|
||||
优先使用 CLI 的组合上下文接口，减少五个 Skill 对同一 PR 的重复请求：
|
||||
当当前 CLI 已提供下列增强接口时，优先使用它们，减少五个 Skill 对同一 PR 的重复请求：
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +review-queue --owner <owner> --repo <repo> --format json
|
||||
gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <number> --include-commits=true --include-ci=true --format json
|
||||
```
|
||||
|
||||
队列级运行只需采集一次 open PR 快照；单 PR 深审再补充该 PR 的上下文。真实数据写入运行目录后，子 Skill 只消费快照和证据，不重新猜测当前状态。
|
||||
若 `workflow +review-queue`、`workflow +review-context` 或其增强参数不可用，必须回退到当前 CLI 已有的只读接口，不得把命令不存在误写成 JSON 解析错误，也不得虚构 SLA、等待方、提交或 CI 证据：
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +list --owner <owner> --repo <repo> --state open --page 1 --limit 100 --format json
|
||||
gitlink-cli pr +view --owner <owner> --repo <repo> -i <number> --format json
|
||||
gitlink-cli pr +files --owner <owner> --repo <repo> -i <number> --format json
|
||||
gitlink-cli pr +reviews --owner <owner> --repo <repo> -i <number> --format json
|
||||
```
|
||||
|
||||
`pr +reviews` 本身不存在时，保留 `pr +view/+files` 结果，并在 `collection-manifest.json` 与专项报告中标记 Review 证据为 `not_run`。队列级运行只需采集一次 open PR 快照；单 PR 深审再补充该 PR 的上下文。拓扑阶段是例外：指定 PR 只限制目标，不限制对照范围，必须额外固定默认分支 baseline、建立源码索引并完整分页采集 merged PR 元数据。真实数据写入运行目录后，子 Skill 只消费快照和证据，不重新猜测当前状态。
|
||||
|
||||
### 3. 并行执行专项检查
|
||||
|
||||
|
|
@ -105,6 +138,24 @@ cli-contract-guard.json
|
|||
pr-topology.json
|
||||
```
|
||||
|
||||
每个阶段 JSON 还必须包含简短的解释性判断，供聊天结论和总报告复用：
|
||||
|
||||
```json
|
||||
{
|
||||
"assessment": {
|
||||
"conclusion": "一句可直接决定本专项状态的短结论",
|
||||
"fact": "PR 实际增加或改变了什么，以及发现的关键问题",
|
||||
"basis": "与默认分支、Diff、Review、测试或队列时间证据的比较方式"
|
||||
},
|
||||
"decision": "action_required"
|
||||
}
|
||||
```
|
||||
|
||||
`conclusion` 必须是可独立阅读的专项判断，不能只写“通过”“观察”或“需要处理”；
|
||||
`fact` 和 `basis` 必须针对当前目标，不能复制状态词。兼容旧阶段结果时，编排器可从
|
||||
`fact` 的第一条事实生成结论，并从首条 finding/action 和 evidence 生成降级说明，但必须
|
||||
保留“证据受限”提示。
|
||||
|
||||
阶段失败时仍写出 `status: failed` 或 `status: not_run` 和失败证据，禁止静默跳过。缺少专项结果时，后续只能降级为 `blocked` 或 `observe`。
|
||||
|
||||
### 4. 集成门禁与维护排序
|
||||
|
|
@ -120,12 +171,12 @@ pr-topology.json
|
|||
|
||||
### 5. 生成维护者首屏
|
||||
|
||||
最终报告必须先展示维护者能立即执行的信息：
|
||||
|
||||
1. **最终决策、阻断数、高风险数、安全门禁、验证状态和扫描时间**。
|
||||
2. **最多五项待办**，每项包含对象、责任方、下一动作、严重性和一个主证据。
|
||||
3. 五个阶段的状态和关键结论。
|
||||
4. 完整 findings、证据台账、限制和下一次复查条件放入附录或 JSON。
|
||||
最终报告必须先按目标 PR 展示六张判断卡，顺序固定为代码审查、CLI 契约、仓库关系、
|
||||
集成门禁、维护状态、最终结论。每张卡先给醒目结论，再写当前 PR 的事实、`依据：`
|
||||
以及影响或下一步；不能把五个阶段压缩成一段总体叙述。全部目标 PR 的判断卡展示完后，
|
||||
再给最多五项跨专项待办，每项包含对象、责任方、下一动作、严重性和一个主证据。
|
||||
阻断数、高风险数、安全门禁和验证状态可以作为卡片之后的索引，不能替代解释。
|
||||
完整 findings、证据台账、限制和下一次复查条件放入附录或 JSON。
|
||||
|
||||
Markdown 使用醒目的颜色和加粗，同时保留 `[blocking]`、`[high]`、`[pass]` 等纯文本回退；JSON 不得包含 HTML、ANSI 或颜色控制符。推荐颜色：blocking `#B42318`、high `#B54708`、pass `#067647`、observe `#175CD3`。
|
||||
|
||||
|
|
@ -147,8 +198,16 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\skills\gitlink-maintenance
|
|||
# 五个 Skill 完成后，校验同一运行上下文并生成最终摘要
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File .\skills\gitlink-maintenance-orchestrator\scripts\run-maintenance-pipeline.ps1 `
|
||||
-Mode finalize -RunPath .\maintenance-runs\<run-directory>
|
||||
|
||||
# 再次确认最终人读报告为中文，且没有退化为英文模板
|
||||
python -X utf8 .\skills\gitlink-maintenance-orchestrator\scripts\validate_chinese_report.py `
|
||||
--report .\maintenance-runs\<run-directory>\final-report.md `
|
||||
--require-pr 123
|
||||
```
|
||||
|
||||
多 PR 报告为每个目标重复 `--require-pr`。任何目标缺少完整六张判断卡、卡片没有明确
|
||||
`依据：`、中文被写成连续问号或报告退化为英文模板时，校验失败且不得交付路径。
|
||||
|
||||
`collect` 只执行 `gitlink-cli` 的读操作，不发布评论、不添加标签、不分配 reviewer、不关闭或合并 PR。若 PowerShell 禁止执行 `gitlink-cli.ps1`，传入可执行的 `gitlink-cli.exe` 或 `gitlink-cli.cmd` 到 `-CliPath`。
|
||||
|
||||
## 输出目录
|
||||
|
|
@ -157,6 +216,8 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\skills\gitlink-maintenance
|
|||
<run-directory>/
|
||||
├── run.json # 运行键、目标和时间
|
||||
├── queue-snapshot.json # open PR 队列快照
|
||||
├── merged-pr-index.json # 全部 merged PR 元数据与分页覆盖
|
||||
├── baseline-source-index.json # 默认分支 SHA、源码路径和能力索引
|
||||
├── pr-context-<number>.json # 单 PR 组合上下文
|
||||
├── code-review.json # CR 阶段原始结果
|
||||
├── cli-contract-guard.json # CG 阶段原始结果
|
||||
|
|
@ -169,6 +230,8 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\skills\gitlink-maintenance
|
|||
|
||||
最终报告只保留一个主决策；专项报告仍作为附件保留，便于定位责任而不是让维护者重复阅读。脚本会检查 UTF-8、替换字符、NUL、重复证据 ID、凭据样式内容、运行键不一致和缺失阶段。
|
||||
|
||||
`finalize` 已内置中文报告校验。不得在 finalize 成功后用手写英文摘要覆盖 `final-report.md`；如果需要补充内容，应更新阶段 JSON 中的中文 `assessment` 后重新 finalize。最终回复前再次运行 `validate_chinese_report.py`，失败时不得交付报告路径。
|
||||
|
||||
## 安全与写入边界
|
||||
|
||||
- 默认只读；编排器不自动 `pr +review`、`pr +comment`、`pr +merge`、关闭、分配或改标签。
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
interface:
|
||||
display_name: "GitLink 维护审查编排器"
|
||||
short_description: "编排五个维护 Skill 生成可验证的 PR 维护摘要"
|
||||
default_prompt: "使用 $gitlink-maintenance-orchestrator 分析指定仓库或一个/多个 PR。自动应用只读编排、证据一致性和首屏高亮规则，生成一份最终 Markdown 总报告。"
|
||||
default_prompt: "使用 $gitlink-maintenance-orchestrator 分析指定仓库或一个/多个 PR；完整证据保存为中文 Markdown，聊天结论由执行 Agent 读完报告后重新提炼，按 PR 分别概括代码审查、CLI 契约、仓库关系、集成门禁、维护状态和最终结论，每方面说明结论、关键依据与影响，不复制报告卡片原文、不输出 HTML/Markdown 展示标签，全程只读。"
|
||||
|
|
|
|||
|
|
@ -2,11 +2,16 @@
|
|||
"schema_version": "1.0",
|
||||
"producer": "gitlink-cli-contract-guard",
|
||||
"status": "completed",
|
||||
"decision": "observe",
|
||||
"decision": "merge",
|
||||
"run": {"run_id": "gitlink-maintenance-orchestrator:Gitlink/gitlink-cli:123:abc1234:executive", "as_of": "2026-07-21T10:00:00Z"},
|
||||
"target": {"owner": "Gitlink", "repo": "gitlink-cli", "number": 123, "head_sha": "abc1234"},
|
||||
"security_gate": "passed",
|
||||
"verification": "complete",
|
||||
"assessment": {
|
||||
"conclusion": "CLI 外部契约保持兼容",
|
||||
"fact": "新增命令保持原有参数、帮助、JSON 类型和错误语义，未观察到用户可感知的契约破坏",
|
||||
"basis": "对默认分支与当前 head 执行相同帮助和结构化输出测试，契约测试完整通过"
|
||||
},
|
||||
"findings": [],
|
||||
"top_actions": [],
|
||||
"evidence": [
|
||||
|
|
|
|||
|
|
@ -7,6 +7,11 @@
|
|||
"target": {"owner": "Gitlink", "repo": "gitlink-cli", "number": 123, "head_sha": "abc1234"},
|
||||
"security_gate": "passed",
|
||||
"verification": "partial",
|
||||
"assessment": {
|
||||
"conclusion": "错误路径缺测，修复后再审",
|
||||
"fact": "PR 为示例命令增加批量处理能力，但错误路径缺少回归测试，核心失败行为尚未被证明可靠",
|
||||
"basis": "对照默认分支与当前 Diff，并执行 go test ./shortcuts/example；正常路径通过，失败路径覆盖不完整"
|
||||
},
|
||||
"findings": [
|
||||
{"id": "CR-001", "severity": "high", "status": "open", "summary": "错误路径缺少回归测试", "evidence": ["E-CR-001"], "related_ids": []}
|
||||
],
|
||||
|
|
|
|||
|
|
@ -7,6 +7,11 @@
|
|||
"target": {"owner": "Gitlink", "repo": "gitlink-cli", "number": 123, "head_sha": "abc1234"},
|
||||
"security_gate": "passed",
|
||||
"verification": "complete",
|
||||
"assessment": {
|
||||
"conclusion": "当前等待作者补测",
|
||||
"fact": "PR #123 已有明确修复动作但仍等待作者补测，继续占用维护者复看队列",
|
||||
"basis": "队列快照显示 waiting_on=author，当前 head 和 Review 后续动作尚未变化"
|
||||
},
|
||||
"findings": [],
|
||||
"top_actions": [
|
||||
{"id": "MR-001", "owner": "maintainer", "severity": "medium", "action": "安排维护者复看 PR #123，当前等待作者补测", "evidence": ["queue:pr-123"]}
|
||||
|
|
|
|||
|
|
@ -7,6 +7,11 @@
|
|||
"target": {"owner": "Gitlink", "repo": "gitlink-cli", "number": 123, "head_sha": "abc1234"},
|
||||
"security_gate": "passed",
|
||||
"verification": "partial",
|
||||
"assessment": {
|
||||
"conclusion": "失败路径门禁未通过，暂不能合并",
|
||||
"fact": "贡献方向与仓库需求一致，但代码审查发现的失败路径缺口尚未修复，当前实现不能安全进入合并队列",
|
||||
"basis": "当前 head 的基础构建可执行，但 CR-001 未解决且全量集成验证只完成部分门禁"
|
||||
},
|
||||
"findings": [],
|
||||
"top_actions": [
|
||||
{"id": "IN-001", "owner": "author", "severity": "high", "action": "修复 CR-001 后重新执行合并态验证", "evidence": ["CR-001"]}
|
||||
|
|
|
|||
|
|
@ -2,11 +2,16 @@
|
|||
"schema_version": "1.0",
|
||||
"producer": "gitlink-pr-topology",
|
||||
"status": "completed",
|
||||
"decision": "observe",
|
||||
"decision": "reorder",
|
||||
"run": {"run_id": "gitlink-maintenance-orchestrator:Gitlink/gitlink-cli:123:abc1234:executive", "as_of": "2026-07-21T10:00:00Z"},
|
||||
"target": {"owner": "Gitlink", "repo": "gitlink-cli", "number": 123, "head_sha": "abc1234"},
|
||||
"security_gate": "passed",
|
||||
"verification": "complete",
|
||||
"assessment": {
|
||||
"conclusion": "与 #124 共享入口，需要复核合并顺序",
|
||||
"fact": "PR #123 与 #124 修改同一命令入口，功能不完全重复，但合并顺序可能改变最终输出契约",
|
||||
"basis": "比较两条 PR 的文件集合、队列快照和目标行为后确认存在共享入口，尚无证据判定其中一条完全替代另一条"
|
||||
},
|
||||
"findings": [
|
||||
{"id": "TP-001", "severity": "medium", "status": "open", "summary": "与 PR #124 修改同一命令入口，建议合并顺序复核", "evidence": ["E-TP-001"], "related_ids": ["PR-124"]}
|
||||
],
|
||||
|
|
|
|||
|
|
@ -41,6 +41,11 @@
|
|||
"target": {"owner": "Gitlink", "repo": "gitlink-cli", "number": 123, "head_sha": "abcdef1"},
|
||||
"security_gate": "passed",
|
||||
"verification": "complete",
|
||||
"assessment": {
|
||||
"conclusion": "错误路径缺测，修复后再审",
|
||||
"fact": "核心成功路径可用，但远端失败没有回归证据",
|
||||
"basis": "当前 head 的 Diff、专项测试和失败路径测试清单"
|
||||
},
|
||||
"findings": [],
|
||||
"top_actions": [],
|
||||
"evidence": [],
|
||||
|
|
@ -48,7 +53,11 @@
|
|||
}
|
||||
```
|
||||
|
||||
`status` 可为 `completed`、`partial`、`failed`、`not_run`、`stale`。`decision` 可为 `merge`、`action_required`、`reorder`、`observe`、`blocked`。阶段之间不得篡改其他 Skill 的 finding，只通过 `related_ids` 关联。
|
||||
`assessment.conclusion` 是首屏加粗的直接判断，不能只重复 `decision` 状态词；
|
||||
`assessment.fact` 解释实际行为，`assessment.basis` 给出核验证据。`status` 可为
|
||||
`completed`、`partial`、`failed`、`not_run`、`stale`。`decision` 可为 `merge`、
|
||||
`action_required`、`reorder`、`observe`、`blocked`。阶段之间不得篡改其他 Skill 的
|
||||
finding，只通过 `related_ids` 关联。
|
||||
|
||||
## 最终决策规则
|
||||
|
||||
|
|
@ -82,4 +91,3 @@
|
|||
- 重复的 action/finding/evidence 能去重而不丢失来源。
|
||||
- blocking、安全失败、CI 未关联和测试未执行会正确降级。
|
||||
- 中文报告为 UTF-8，不能出现替换字符、NUL 或凭据样式内容。
|
||||
|
||||
|
|
|
|||
|
|
@ -101,8 +101,37 @@ function Get-StageSummary {
|
|||
if (Has-Property $Artifact 'findings') { $findings = @($Artifact.findings) }
|
||||
$topActions = @()
|
||||
if (Has-Property $Artifact 'top_actions') { $topActions = @($Artifact.top_actions) }
|
||||
$evidence = @()
|
||||
if (Has-Property $Artifact 'evidence') { $evidence = @($Artifact.evidence) }
|
||||
$limitations = @()
|
||||
if (Has-Property $Artifact 'limitations') { $limitations = @($Artifact.limitations) }
|
||||
$assessment = if (Has-Property $Artifact 'assessment') { $Artifact.assessment } else { $null }
|
||||
$blocking = @($findings | Where-Object { (Get-DisplaySeverity (Get-Value $_ 'severity' '')) -eq 'blocking' }).Count
|
||||
$high = @($findings | Where-Object { (Get-DisplaySeverity (Get-Value $_ 'severity' '')) -eq 'high' }).Count
|
||||
$focus = if ($null -ne $assessment -and -not [string]::IsNullOrWhiteSpace([string](Get-Value $assessment 'fact' ''))) {
|
||||
[string](Get-Value $assessment 'fact' '')
|
||||
} elseif ($findings.Count -gt 0) {
|
||||
[string](Get-Value $findings[0] 'summary' '发现需要维护者复核的问题')
|
||||
} elseif ($topActions.Count -gt 0) {
|
||||
[string](Get-Value $topActions[0] 'action' '存在待处理动作')
|
||||
} else {
|
||||
'在已采集范围内未发现需要立即处理的问题'
|
||||
}
|
||||
$basis = if ($null -ne $assessment -and -not [string]::IsNullOrWhiteSpace([string](Get-Value $assessment 'basis' ''))) {
|
||||
[string](Get-Value $assessment 'basis' '')
|
||||
} elseif ($evidence.Count -gt 0) {
|
||||
$firstEvidence = $evidence[0]
|
||||
"$(Get-Value $firstEvidence 'source' 'unknown source') / $(Get-Value $firstEvidence 'ref' 'unknown ref')（$(Get-Value $firstEvidence 'status' 'unknown')）"
|
||||
} elseif ($limitations.Count -gt 0) {
|
||||
"证据受限：$($limitations[0])"
|
||||
} else {
|
||||
'没有可引用的专项证据，结论置信度受限'
|
||||
}
|
||||
$conclusion = if ($null -ne $assessment -and -not [string]::IsNullOrWhiteSpace([string](Get-Value $assessment 'conclusion' ''))) {
|
||||
[string](Get-Value $assessment 'conclusion' '')
|
||||
} else {
|
||||
([string]$focus -split '[，；。]', 2)[0].Trim()
|
||||
}
|
||||
return [ordered]@{
|
||||
producer = $Producer
|
||||
status = [string](Get-Value $Artifact 'status' 'not_run')
|
||||
|
|
@ -113,6 +142,9 @@ function Get-StageSummary {
|
|||
blocking_count = $blocking
|
||||
high_count = $high
|
||||
top_action_count = $topActions.Count
|
||||
conclusion = $conclusion
|
||||
focus = $focus
|
||||
basis = $basis
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -287,6 +319,13 @@ function New-FinalReport {
|
|||
$validator = Join-Path $PSScriptRoot '..\..\gitlink-shared\examples\validate-maintenance-report.ps1'
|
||||
if (-not (Test-Path -LiteralPath $validator)) { throw "missing maintenance report validator: $validator" }
|
||||
& $validator -Path (Join-Path $Path 'final-report.json') | Out-Null
|
||||
$markdownValidator = Join-Path $PSScriptRoot 'validate_chinese_report.py'
|
||||
if (-not (Test-Path -LiteralPath $markdownValidator)) { throw "missing Chinese report validator: $markdownValidator" }
|
||||
$markdownArgs = @('-X', 'utf8', $markdownValidator, '--report', (Join-Path $Path 'final-report.md'))
|
||||
$targetNumber = Get-Value $run.target 'number' $null
|
||||
if ($null -ne $targetNumber) { $markdownArgs += @('--require-pr', [string]$targetNumber) }
|
||||
& python @markdownArgs | Out-Null
|
||||
if ($LASTEXITCODE -ne 0) { throw 'final-report.md must be a complete Chinese report' }
|
||||
return $report
|
||||
}
|
||||
|
||||
|
|
@ -305,15 +344,69 @@ function Get-ColorLabel {
|
|||
}
|
||||
}
|
||||
|
||||
function Get-ConclusionLabel {
|
||||
param([string]$Conclusion, [string]$Decision)
|
||||
$color = switch ($Decision) {
|
||||
'merge' { '#067647' }
|
||||
'action_required' { '#B54708' }
|
||||
'blocked' { '#B42318' }
|
||||
'reorder' { '#175CD3' }
|
||||
'observe' { '#175CD3' }
|
||||
default { '#175CD3' }
|
||||
}
|
||||
$safeConclusion = [Net.WebUtility]::HtmlEncode($Conclusion)
|
||||
return "<span style=`"color:$color`"><strong>$safeConclusion</strong></span> **[$Decision]**"
|
||||
}
|
||||
|
||||
function Get-StageAspect {
|
||||
param([string]$Producer)
|
||||
switch ($Producer) {
|
||||
'gitlink-code-review' { return '代码审查' }
|
||||
'gitlink-cli-contract-guard' { return 'CLI 契约' }
|
||||
'gitlink-pr-topology' { return '仓库关系' }
|
||||
'gitlink-pr-integrator' { return '集成门禁' }
|
||||
'gitlink-maintainer-radar' { return '维护状态' }
|
||||
default { return '专项判断' }
|
||||
}
|
||||
}
|
||||
|
||||
function Get-DecisionImpact {
|
||||
param([string]$Decision)
|
||||
switch ($Decision) {
|
||||
'merge' { return '当前专项没有阻止进入合并队列的动作' }
|
||||
'action_required' { return '完成高优先级动作后重新评估' }
|
||||
'blocked' { return '当前不能进入合并队列' }
|
||||
'reorder' { return '需要调整评审或合并顺序' }
|
||||
'observe' { return '证据不足，保留观察并补充验证' }
|
||||
default { return '按专项证据决定下一步' }
|
||||
}
|
||||
}
|
||||
|
||||
function Write-MarkdownReport {
|
||||
param([string]$Path, [object]$Report)
|
||||
$lines = New-Object Collections.Generic.List[string]
|
||||
$lines.Add('# PR 维护全流程摘要')
|
||||
$lines.Add('')
|
||||
$lines.Add("**结论：** $(Get-ColorLabel $Report.decision)")
|
||||
$lines.Add("**范围：** $($Report.scope.owner)/$($Report.scope.repo) | **运行时间：** $($Report.run.as_of) | **运行 ID：** ``$($Report.run.run_id)``")
|
||||
$lines.Add("**风险：** 阻断 $($Report.counts.blocking) | 高风险 $($Report.counts.high) | 中风险 $($Report.counts.medium) | 低风险 $($Report.counts.low) | **安全门禁：** ``$($Report.security_gate)`` | **验证：** ``$($Report.verification)``")
|
||||
$lines.Add('')
|
||||
$targetNumber = Get-Value $Report.run.target 'number' 0
|
||||
if ($null -eq $targetNumber) { $targetNumber = 0 }
|
||||
$lines.Add("## PR #$targetNumber")
|
||||
foreach ($stage in @($Report.stages)) {
|
||||
$aspect = Get-StageAspect ([string]$stage.producer)
|
||||
$impact = Get-DecisionImpact ([string]$stage.decision)
|
||||
$lines.Add("**${aspect}：** $(Get-ConclusionLabel ([string]$stage.conclusion) ([string]$stage.decision))：$($stage.focus)；依据：$($stage.basis)；影响：$impact。")
|
||||
}
|
||||
$finalReason = if (@($Report.top_actions).Count -gt 0) {
|
||||
[string]$Report.top_actions[0].action
|
||||
} else {
|
||||
'当前没有需要立即处理的高优先级动作'
|
||||
}
|
||||
$finalNext = Get-DecisionImpact ([string]$Report.decision)
|
||||
$finalConclusion = if (@($Report.top_actions).Count -gt 0) { $finalReason } else { $finalNext }
|
||||
$lines.Add("**最终结论：** $(Get-ConclusionLabel $finalConclusion ([string]$Report.decision))：该动作决定当前集成状态；依据：阻断 $($Report.counts.blocking) 项、高风险 $($Report.counts.high) 项，安全门禁 ``$($Report.security_gate)``、验证 ``$($Report.verification)``；下一步：$finalNext。")
|
||||
$lines.Add('')
|
||||
$lines.Add('## 先处理这几项')
|
||||
if (@($Report.top_actions).Count -eq 0) {
|
||||
$lines.Add('暂无需要立即处理的动作。')
|
||||
|
|
@ -326,7 +419,7 @@ function Write-MarkdownReport {
|
|||
}
|
||||
}
|
||||
$lines.Add('')
|
||||
$lines.Add('## 五个专项结果')
|
||||
$lines.Add('## 五个专项状态索引')
|
||||
$lines.Add('| 专项 | 状态 | 决策 | 发现 | 关键动作 |')
|
||||
$lines.Add('|---|---|---|---:|---:|')
|
||||
foreach ($stage in @($Report.stages)) {
|
||||
|
|
@ -345,8 +438,46 @@ function Invoke-GitLinkJson {
|
|||
$output = & $Executable @Arguments 2> $ErrorPath | Out-String
|
||||
$exitCode = $LASTEXITCODE
|
||||
Write-Utf8Text -Path $OutputPath -Text $output
|
||||
if ($exitCode -ne 0) { throw "gitlink-cli command failed with exit code $exitCode; see $ErrorPath" }
|
||||
try { return ($output | ConvertFrom-Json) } catch { throw "gitlink-cli returned invalid JSON; see $OutputPath" }
|
||||
$command = "$Executable $($Arguments -join ' ')"
|
||||
if ($exitCode -ne 0) {
|
||||
$errorSummary = if (Test-Path -LiteralPath $ErrorPath) {
|
||||
((Get-Content -LiteralPath $ErrorPath -Raw -Encoding utf8).Trim() -replace "[\r\n]+", ' ')
|
||||
} else {
|
||||
'no stderr output'
|
||||
}
|
||||
throw "gitlink-cli command failed with exit code ${exitCode}: $command; stderr: $errorSummary"
|
||||
}
|
||||
try {
|
||||
return ($output | ConvertFrom-Json)
|
||||
} catch {
|
||||
throw "gitlink-cli command returned non-JSON output: $command; this can mean an unsupported command or unexpected CLI output; see $OutputPath"
|
||||
}
|
||||
}
|
||||
|
||||
function Try-InvokeGitLinkJson {
|
||||
param([string]$Executable, [string[]]$Arguments, [string]$OutputPath, [string]$ErrorPath)
|
||||
try {
|
||||
return [pscustomobject]@{
|
||||
Succeeded = $true
|
||||
Value = Invoke-GitLinkJson -Executable $Executable -Arguments $Arguments -OutputPath $OutputPath -ErrorPath $ErrorPath
|
||||
Failure = ''
|
||||
}
|
||||
} catch {
|
||||
return [pscustomobject]@{
|
||||
Succeeded = $false
|
||||
Value = $null
|
||||
Failure = $_.Exception.Message
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function Write-CollectionManifest {
|
||||
param([string]$Path, [string]$QueueSource, [string]$ContextSource, [string[]]$Limitations)
|
||||
Write-JsonFile -Path (Join-Path $Path 'collection-manifest.json') -Value ([ordered]@{
|
||||
queue_source = $QueueSource
|
||||
context_source = $ContextSource
|
||||
limitations = @($Limitations)
|
||||
})
|
||||
}
|
||||
|
||||
function New-RunContext {
|
||||
|
|
@ -370,13 +501,62 @@ function Start-Collect {
|
|||
$run = New-RunContext -Path $path -RunTrigger $Trigger -Timestamp $timestamp -TargetNumber $Number
|
||||
$queuePath = Join-Path $path 'queue-snapshot.json'
|
||||
$queueErrorPath = Join-Path $path 'queue-snapshot.stderr.log'
|
||||
Invoke-GitLinkJson -Executable $CliPath -Arguments @('workflow', '+review-queue', '--owner', $Owner, '--repo', $Repo, '--format', 'json') -OutputPath $queuePath -ErrorPath $queueErrorPath | Out-Null
|
||||
$limitations = @()
|
||||
$queue = Try-InvokeGitLinkJson -Executable $CliPath -Arguments @('workflow', '+review-queue', '--owner', $Owner, '--repo', $Repo, '--format', 'json') -OutputPath $queuePath -ErrorPath $queueErrorPath
|
||||
$queueSource = 'workflow +review-queue'
|
||||
if (-not $queue.Succeeded) {
|
||||
$workflowQueueFailure = $queue.Failure
|
||||
$queue = Try-InvokeGitLinkJson -Executable $CliPath -Arguments @('pr', '+list', '--owner', $Owner, '--repo', $Repo, '--state', 'open', '--page', '1', '--limit', '100', '--format', 'json') -OutputPath $queuePath -ErrorPath $queueErrorPath
|
||||
if (-not $queue.Succeeded) {
|
||||
throw "unable to collect open PR queue. workflow attempt: $workflowQueueFailure; pr +list fallback: $($queue.Failure)"
|
||||
}
|
||||
$queueSource = 'pr +list fallback'
|
||||
$limitations += 'workflow +review-queue is unavailable; queue snapshot is raw pr +list output without queue delta, SLA, or waiting_on fields.'
|
||||
}
|
||||
|
||||
$contextSource = 'not requested'
|
||||
if ($Number) {
|
||||
$contextPath = Join-Path $path "pr-context-$Number.json"
|
||||
$contextErrorPath = Join-Path $path "pr-context-$Number.stderr.log"
|
||||
Invoke-GitLinkJson -Executable $CliPath -Arguments @('workflow', '+review-context', '--owner', $Owner, '--repo', $Repo, '--number', $Number, '--include-commits=true', '--include-ci=true', '--format', 'json') -OutputPath $contextPath -ErrorPath $contextErrorPath | Out-Null
|
||||
$context = Try-InvokeGitLinkJson -Executable $CliPath -Arguments @('workflow', '+review-context', '--owner', $Owner, '--repo', $Repo, '--number', $Number, '--format', 'json') -OutputPath $contextPath -ErrorPath $contextErrorPath
|
||||
$contextSource = 'workflow +review-context'
|
||||
if (-not $context.Succeeded) {
|
||||
$viewPath = Join-Path $path "pr-view-$Number.json"
|
||||
$viewErrorPath = Join-Path $path "pr-view-$Number.stderr.log"
|
||||
$view = Try-InvokeGitLinkJson -Executable $CliPath -Arguments @('pr', '+view', '--owner', $Owner, '--repo', $Repo, '-i', $Number, '--format', 'json') -OutputPath $viewPath -ErrorPath $viewErrorPath
|
||||
if (-not $view.Succeeded) {
|
||||
throw "unable to collect PR #$Number context. workflow attempt: $($context.Failure); pr +view fallback: $($view.Failure)"
|
||||
}
|
||||
$fallbackContext = [ordered]@{
|
||||
repository = "$Owner/$Repo"
|
||||
pull_request = [int]$Number
|
||||
source = 'pr +view/+files/+reviews fallback'
|
||||
pr = $view.Value
|
||||
files = $null
|
||||
reviews = $null
|
||||
}
|
||||
foreach ($part in @(
|
||||
@{ Name = 'files'; Arguments = @('pr', '+files', '--owner', $Owner, '--repo', $Repo, '-i', $Number, '--format', 'json') },
|
||||
@{ Name = 'reviews'; Arguments = @('pr', '+reviews', '--owner', $Owner, '--repo', $Repo, '-i', $Number, '--format', 'json') }
|
||||
)) {
|
||||
$partPath = Join-Path $path "pr-$($part.Name)-$Number.json"
|
||||
$partErrorPath = Join-Path $path "pr-$($part.Name)-$Number.stderr.log"
|
||||
$partResult = Try-InvokeGitLinkJson -Executable $CliPath -Arguments $part.Arguments -OutputPath $partPath -ErrorPath $partErrorPath
|
||||
if (-not $partResult.Succeeded) {
|
||||
$limitations += "pr +$($part.Name) fallback was unavailable: $($partResult.Failure)"
|
||||
} else {
|
||||
$fallbackContext[$part.Name] = $partResult.Value
|
||||
}
|
||||
}
|
||||
Write-JsonFile -Path $contextPath -Value $fallbackContext
|
||||
$contextSource = 'pr +view/+files/+reviews fallback'
|
||||
$limitations += 'workflow +review-context is unavailable; commits and CI evidence were not collected and must be marked not_run or partial.'
|
||||
} else {
|
||||
$limitations += 'Current review-context output does not include commit or CI evidence; mark those gates not_run or partial unless separate evidence is collected.'
|
||||
}
|
||||
}
|
||||
Write-Output "collected read-only evidence: $path"
|
||||
Write-CollectionManifest -Path $path -QueueSource $queueSource -ContextSource $contextSource -Limitations $limitations
|
||||
Write-Output "collected read-only evidence: $path (queue: $queueSource; context: $contextSource)"
|
||||
}
|
||||
|
||||
function Start-Fixture {
|
||||
|
|
|
|||
|
|
@ -0,0 +1,45 @@
|
|||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
$pipeline = Join-Path $PSScriptRoot 'run-maintenance-pipeline.ps1'
|
||||
$validator = Join-Path $PSScriptRoot '..\..\gitlink-shared\examples\validate-maintenance-report.ps1'
|
||||
$chineseReportValidatorTests = Join-Path $PSScriptRoot 'test_validate_chinese_report.py'
|
||||
$orchestratorPromptTests = Join-Path $PSScriptRoot 'test_orchestrator_prompt_contract.py'
|
||||
$chineseReportValidator = Join-Path $PSScriptRoot 'validate_chinese_report.py'
|
||||
$tempRoot = Join-Path ([IO.Path]::GetTempPath()) ("gitlink-maintenance-output-" + [Guid]::NewGuid().ToString('N'))
|
||||
|
||||
try {
|
||||
& $pipeline -Mode fixture -RunRoot $tempRoot -Force | Out-Null
|
||||
$markdown = Get-ChildItem -LiteralPath $tempRoot -Recurse -Filter final-report.md | Select-Object -First 1
|
||||
$json = Get-ChildItem -LiteralPath $tempRoot -Recurse -Filter final-report.json | Select-Object -First 1
|
||||
if ($null -eq $markdown -or $null -eq $json) { throw 'pipeline did not generate final reports' }
|
||||
|
||||
& $validator -Path $json.FullName | Out-Null
|
||||
$utf8 = New-Object Text.UTF8Encoding($false, $true)
|
||||
$content = [IO.File]::ReadAllText($markdown.FullName, $utf8)
|
||||
if ($content.Contains([char]0xfffd) -or $content.Contains([char]0)) { throw 'Markdown contains invalid encoding characters' }
|
||||
foreach ($producer in @('gitlink-code-review', 'gitlink-cli-contract-guard', 'gitlink-pr-topology', 'gitlink-pr-integrator', 'gitlink-maintainer-radar')) {
|
||||
if (-not $content.Contains("| $producer |")) { throw "missing stage index entry: $producer" }
|
||||
}
|
||||
foreach ($fixtureName in @('code-review.json', 'cli-contract-guard.json', 'pr-topology.json', 'pr-integrator.json', 'maintainer-radar.json')) {
|
||||
$fixture = Get-Content -LiteralPath (Join-Path $PSScriptRoot "..\examples\fixtures\$fixtureName") -Raw -Encoding utf8 | ConvertFrom-Json
|
||||
$expectedConclusion = [Net.WebUtility]::HtmlEncode([string]$fixture.assessment.conclusion)
|
||||
if (-not $content.Contains("<strong>$expectedConclusion</strong>")) { throw "missing direct stage conclusion from fixture: $fixtureName" }
|
||||
}
|
||||
$decisionPattern = '<strong>[^<]+</strong></span> \*\*\[(merge|action_required|reorder|observe|blocked)\]\*\*'
|
||||
$decisions = [regex]::Matches($content, $decisionPattern)
|
||||
$actionsIndex = $content.IndexOf('1. **[')
|
||||
if ($decisions.Count -lt 6 -or $actionsIndex -lt 0 -or $decisions[5].Index -gt $actionsIndex) { throw 'final conclusion must appear after five stage decisions and before actions' }
|
||||
|
||||
& python -X utf8 $orchestratorPromptTests | Out-Null
|
||||
if ($LASTEXITCODE -ne 0) { throw 'orchestrator prompt contract tests failed' }
|
||||
& python -X utf8 $chineseReportValidatorTests | Out-Null
|
||||
if ($LASTEXITCODE -ne 0) { throw 'orchestrator Chinese report validator tests failed' }
|
||||
& python -X utf8 $chineseReportValidator --report $markdown.FullName --require-pr 123 | Out-Null
|
||||
if ($LASTEXITCODE -ne 0) { throw 'generated report does not satisfy the Chinese per-PR card contract' }
|
||||
|
||||
Write-Output 'maintenance output tests passed: Chinese per-PR cards, UTF-8, agent synthesis contract'
|
||||
} finally {
|
||||
if (Test-Path -LiteralPath $tempRoot) {
|
||||
Remove-Item -LiteralPath $tempRoot -Recurse -Force
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
from pathlib import Path
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
|
||||
|
||||
def read_utf8(path: Path) -> str:
|
||||
return path.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
def test_chat_summary_requires_agent_synthesis() -> None:
|
||||
content = read_utf8(ROOT / "SKILL.md")
|
||||
required_markers = [
|
||||
"必须由执行 Skill 的 Agent",
|
||||
"重新提炼",
|
||||
"不能复制报告首屏",
|
||||
"不能机械删除 Markdown/HTML 格式",
|
||||
"每个方面一至两句完整自然语言",
|
||||
"可点击链接或当前 Agent 平台的文件附件",
|
||||
]
|
||||
missing = [marker for marker in required_markers if marker not in content]
|
||||
assert not missing, f"missing orchestrator chat synthesis markers: {missing}"
|
||||
assert "最终回复直接复用" not in content
|
||||
|
||||
|
||||
def test_default_agent_prompt_requires_a_plain_summary() -> None:
|
||||
content = read_utf8(ROOT / "agents" / "openai.yaml")
|
||||
required_markers = ["重新提炼", "不复制报告卡片原文", "不输出 HTML/Markdown 展示标签"]
|
||||
missing = [marker for marker in required_markers if marker not in content]
|
||||
assert not missing, f"missing agent prompt markers: {missing}"
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
#!/usr/bin/env python3
|
||||
|
||||
import unittest
|
||||
|
||||
from validate_chinese_report import validate_report
|
||||
|
||||
|
||||
class ChineseReportValidatorTests(unittest.TestCase):
|
||||
def test_accepts_complete_chinese_report(self) -> None:
|
||||
report = """# PR 维护全流程摘要
|
||||
**范围：** Gitlink/gitlink-cli
|
||||
**风险：** 阻断 1 项，高风险 2 项，以下内容用于帮助维护者快速确认处理顺序和责任人。
|
||||
## PR #123
|
||||
**代码审查：** <span><strong>需要修改</strong></span> **[action_required]**：失败路径缺少覆盖；依据：当前 Diff 与专项测试；下一步：补回归测试。
|
||||
**CLI 契约：** <span><strong>兼容性部分成立</strong></span> **[partial]**：旧调用正常但 JSON 缺边界；依据：帮助和输出对照；下一步：补 golden。
|
||||
**仓库关系：** <span><strong>需要调整顺序</strong></span> **[reorder]**：目标消费上游字段；依据：主线、open 和 merged 索引；影响：先稳定上游。
|
||||
**集成门禁：** <span><strong>当前被阻断</strong></span> **[blocked]**：关键测试未完成；依据：合并态和验证账本；下一步：补测试。
|
||||
**维护状态：** <span><strong>需要维护者接单</strong></span> **[action_required]**：责任方尚未确认；依据：时间和分配快照；下一步：安排 reviewer。
|
||||
**最终结论：** <span><strong>修复阻断问题后重新审查</strong></span> **[blocked]**：存在未解决高风险项；依据：CR-001 与 IN-001；下一步：修复并重跑。
|
||||
## 先处理这几项
|
||||
先修复真实响应错误，再补充测试，然后重新执行完整验证并由维护者复看。
|
||||
## 五个专项状态索引
|
||||
gitlink-code-review | gitlink-cli-contract-guard | gitlink-pr-topology | gitlink-pr-integrator | gitlink-maintainer-radar
|
||||
## 完整证据与限制
|
||||
当前结论来自固定时间快照、目标提交差异、构建测试和只读平台数据；未验证内容已明确标记。"""
|
||||
self.assertEqual([], validate_report(report, [123]))
|
||||
|
||||
def test_rejects_english_template(self) -> None:
|
||||
errors = validate_report("# PR Maintenance Summary\n## Core Judgment\n**Final decision:** blocked")
|
||||
self.assertTrue(any("English report template" in error for error in errors))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
|
@ -0,0 +1,112 @@
|
|||
#!/usr/bin/env python3
|
||||
"""Validate that the orchestrator saves a complete Chinese Markdown report."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
REQUIRED_MARKERS = (
|
||||
"# PR 维护全流程摘要",
|
||||
"**范围：**",
|
||||
"**风险：**",
|
||||
"## PR #",
|
||||
"**最终结论：**",
|
||||
"## 先处理这几项",
|
||||
"## 五个专项状态索引",
|
||||
"## 完整证据与限制",
|
||||
)
|
||||
REQUIRED_ASPECTS = (
|
||||
"代码审查",
|
||||
"CLI 契约",
|
||||
"仓库关系",
|
||||
"集成门禁",
|
||||
"维护状态",
|
||||
"最终结论",
|
||||
)
|
||||
FORBIDDEN_ENGLISH_TEMPLATES = (
|
||||
"# PR Maintenance Summary",
|
||||
"## Core Judgment",
|
||||
"## Top Actions",
|
||||
"## Stage Index",
|
||||
"## Limits",
|
||||
"**Scope:**",
|
||||
"**Risk:**",
|
||||
"**Final decision:**",
|
||||
)
|
||||
PR_HEADING = re.compile(r"^## PR #(\d+)(?:\s.*)?$", re.MULTILINE)
|
||||
CARD_PATTERN = re.compile(
|
||||
r"^\*\*([^*\n]+)：\*\*\s*"
|
||||
r"<span\b[^>]*><strong>([^<]+)</strong></span>\s*"
|
||||
r"\*\*\[([^\]]+)\]\*\*：\s*(\S.*)$",
|
||||
re.MULTILINE,
|
||||
)
|
||||
|
||||
|
||||
def validate_report(text: str, required_prs: list[int] | None = None) -> list[str]:
|
||||
errors: list[str] = []
|
||||
if "\ufffd" in text or "\x00" in text or "\x1b" in text:
|
||||
errors.append("report contains invalid encoding or terminal control characters")
|
||||
if re.search(r"\?{2,}", text):
|
||||
errors.append("report contains repeated question marks indicating encoding loss")
|
||||
for marker in REQUIRED_MARKERS:
|
||||
if marker not in text:
|
||||
errors.append(f"missing Chinese report marker: {marker}")
|
||||
for marker in FORBIDDEN_ENGLISH_TEMPLATES:
|
||||
if marker in text:
|
||||
errors.append(f"English report template is not allowed: {marker}")
|
||||
if len(re.findall(r"[\u3400-\u9fff]", text)) < 100:
|
||||
errors.append("Chinese narrative is insufficient")
|
||||
|
||||
sections = {int(match.group(1)): match.start() for match in PR_HEADING.finditer(text)}
|
||||
targets = required_prs or sorted(sections)
|
||||
if not targets:
|
||||
errors.append("report contains no PR section")
|
||||
return errors
|
||||
for number in targets:
|
||||
start = sections.get(number)
|
||||
if start is None:
|
||||
errors.append(f"missing PR section: #{number}")
|
||||
continue
|
||||
next_heading = PR_HEADING.search(text, start + 1)
|
||||
end = next_heading.start() if next_heading else len(text)
|
||||
cards = CARD_PATTERN.findall(text[start:end])
|
||||
aspects = {card[0] for card in cards}
|
||||
if len(cards) < len(REQUIRED_ASPECTS):
|
||||
errors.append(f"PR #{number} has {len(cards)} judgment cards, need 6")
|
||||
for aspect in REQUIRED_ASPECTS:
|
||||
if aspect not in aspects:
|
||||
errors.append(f"PR #{number} is missing aspect card: {aspect}")
|
||||
for aspect, conclusion, status, rationale in cards:
|
||||
if not conclusion.strip() or not status.strip() or len(rationale.strip()) < 20:
|
||||
errors.append(f"PR #{number} aspect {aspect} is not substantive")
|
||||
if "依据：" not in rationale:
|
||||
errors.append(f"PR #{number} aspect {aspect} is missing evidence")
|
||||
return errors
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description="Validate a Chinese orchestrator report.")
|
||||
parser.add_argument("--report", required=True, type=Path)
|
||||
parser.add_argument("--require-pr", action="append", type=int, default=[])
|
||||
args = parser.parse_args()
|
||||
try:
|
||||
text = args.report.read_text(encoding="utf-8", errors="strict")
|
||||
except (OSError, UnicodeError) as exc:
|
||||
print(f"orchestrator report validation failed: {exc}", file=sys.stderr)
|
||||
return 2
|
||||
errors = validate_report(text, args.require_pr)
|
||||
if errors:
|
||||
print("orchestrator report validation failed:", file=sys.stderr)
|
||||
for error in errors:
|
||||
print(f"- {error}", file=sys.stderr)
|
||||
return 1
|
||||
print("orchestrator report validation passed: Chinese human-readable report")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
|
|
@ -21,7 +21,7 @@ CI 门禁必须读取 `ci_summary`：`match_mode=sha` 优先，`branch` 只能
|
|||
**CRITICAL - GitLink 平台数据采集和回写只使用 `gitlink-cli`，不要改用 `gh` 或其他平台 CLI。**
|
||||
**CRITICAL - 默认只做读取、验证和报告；只有用户明确要求时才回写评论或 review。**
|
||||
**CRITICAL - 不要在用户当前的脏工作树里做合并验证。优先使用独立 worktree、临时 clone 或明确指定的检出目录。**
|
||||
**CRITICAL - 在 Windows PowerShell 中保存中文报告前，先切到 UTF-8 输出链路，否则中文可能被写成 `?`。**
|
||||
**CRITICAL - 在 Codex 中优先使用 `apply_patch` 写中文报告；不要通过 Windows PowerShell 5.1 here-string/变量管道写入，否则中文可能永久变成 `?`。**
|
||||
|
||||
## 默认调用契约
|
||||
|
||||
|
|
@ -32,19 +32,24 @@ CI 门禁必须读取 `ci_summary`：`match_mode=sha` 优先，`branch` 只能
|
|||
- 独立判断贡献价值和集成就绪度，不调用其他 Skill；不重新做完整代码审查，不输出完整 PR 替代图谱，也不判断维护者 SLA。
|
||||
- 只读远端；允许在隔离 worktree 中执行本地验证，但不评论、不 approve、不合并、不关闭、不修改远端。
|
||||
- 使用 `IN-001` 起的稳定编号，记录门禁、当前 head SHA、命令、退出码、证据、下一动作和限制。
|
||||
- 首屏先给出“贡献是否值得合入”和“现在能否进入 merge queue”，显示贡献价值与六项技术门禁及最多 5 项动作；失败或高风险使用颜色和粗体。
|
||||
- 聊天和报告首屏按 PR 分节，将贡献价值、合并态、构建、测试、契约、安全与发布、集成结论分别做成判断卡；每张卡先显示醒目结论，再写解释、`依据：` 和影响/下一步。
|
||||
- 一次运行只生成一份 UTF-8 Markdown，保存到 `reports/skill-runs/gitlink-pr-integrator/<owner>-<repo>-<scope>-<yyyyMMdd-HHmmssZ>.md`；多个 PR 先给队列摘要，再分别给每条 PR 的门禁。
|
||||
|
||||
无法写入工作区时输出完整 Markdown 并标记“未落盘”。最终回复给出报告绝对路径、可进入队列数量、阻断数量和第一下一动作。
|
||||
最终回复复用报告首屏的逐 PR 七方面判断卡，再给报告绝对路径；不得把多个 PR 或多个门禁压成一段。无法写入工作区时输出完整 Markdown 并标记“未落盘”。
|
||||
|
||||
首屏固定先使用：
|
||||
|
||||
```markdown
|
||||
# PR #<number> 集成摘要
|
||||
# PR 集成摘要
|
||||
|
||||
**结论：** <span style="color:#B54708"><strong>需补验证</strong></span> **[action_required]**
|
||||
**贡献价值：** <span style="color:#067647"><strong>值得合入</strong></span> **[passed]**：需求明确、增量有效，维护成本可接受
|
||||
**门禁：** 价值 `passed` | 合并态 `passed` | 构建 `passed` | 测试 `not_run` | 契约 `partial` | 安全 `not_run` | 冲突 `low`
|
||||
## 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 项
|
||||
|
||||
|
|
@ -72,16 +77,39 @@ CI 门禁必须读取 `ci_summary`：`match_mode=sha` 优先，`branch` 只能
|
|||
推荐的首屏格式：
|
||||
|
||||
```markdown
|
||||
# PR #<number> 集成摘要
|
||||
**结论：** <span style="color:#B54708"><strong>需补验证</strong></span> **[action_required]**
|
||||
**贡献价值：** <span style="color:#067647"><strong>值得合入</strong></span> **[passed]**：解决高频维护问题，现有命令没有等价能力
|
||||
**门禁：** 价值通过 | 合并态通过 | 构建通过 | 测试未执行 | 安全未验证 | 冲突低
|
||||
# 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）。
|
||||
```
|
||||
|
||||
保存报告后，针对每个目标重复 `--require-pr` 并运行：
|
||||
|
||||
```bash
|
||||
python -X utf8 skills/gitlink-shared/scripts/validate_pr_cards.py \
|
||||
--report <absolute-report-path> \
|
||||
--require-pr <target-number> \
|
||||
--min-cards 7 \
|
||||
--required-aspect "贡献价值" \
|
||||
--required-aspect "合并态" \
|
||||
--required-aspect "构建" \
|
||||
--required-aspect "测试" \
|
||||
--required-aspect "契约" \
|
||||
--required-aspect "安全与发布" \
|
||||
--required-aspect "集成结论"
|
||||
```
|
||||
|
||||
报告通过后，聊天直接复用逐 PR 七张卡；校验失败或出现连续 `???` 时必须重写，不能交付路径。
|
||||
|
||||
只有贡献价值和六项技术门禁都有充分证据且无 `blocking/high` 未解决项，才可使用 `merge`。大型 PR 先做价值证据、文件/目录重叠和安全热点筛选，低价值或高度重复候选先交维护者判断，高风险候选再进入独立 worktree 的完整合并验证，避免批量扫描浪费维护者时间。
|
||||
|
||||
## 贡献价值门禁
|
||||
|
|
@ -323,9 +351,14 @@ gitlink-cli pr +list --owner <owner> --repo <repo> --state open --page 1 --limit
|
|||
<!-- gitlink-pr-integrator:report v1 -->
|
||||
## PR #<id> 集成就绪报告
|
||||
|
||||
**结论：** <span style="color:#B54708"><strong>需要维护者判断</strong></span> **[observe]**
|
||||
**贡献价值：** <span style="color:#B54708"><strong>证据不完整</strong></span> **[partial]**
|
||||
**门禁：** 价值 `partial` | 合并态 `passed` | 构建 `passed` | 测试 `passed` | 契约 `passed` | 安全 `passed` | 冲突 `low`
|
||||
**贡献价值：** <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
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
interface:
|
||||
display_name: "PR 价值与集成检查"
|
||||
short_description: "以详细证据评估贡献价值，并验证 PR 能否安全并入主线。"
|
||||
default_prompt: "使用 $gitlink-pr-integrator 评估指定 GitLink PR 的贡献价值和集成条件，生成结论前置、依据完整且不修改远端的 Markdown 报告。"
|
||||
default_prompt: "使用 $gitlink-pr-integrator 评估指定 GitLink PR；聊天和 Markdown 均按 PR 分节，将贡献价值、合并态、构建、测试、契约、安全与发布、集成结论分别做成结论前置判断卡，后接依据与影响，不修改远端。"
|
||||
|
|
|
|||
|
|
@ -9,9 +9,15 @@ gitlink-cli ci +builds --owner Gitlink --repo gitlink-cli --format json
|
|||
|
||||
```markdown
|
||||
# PR #123 集成摘要
|
||||
**结论：** <span style="color:#067647"><strong>可进入合并队列</strong></span> **[merge]**
|
||||
**贡献价值：** <span style="color:#067647"><strong>值得合入</strong></span> **[passed]**：解决高频批量操作缺口，默认分支无等价能力
|
||||
**门禁：** 价值通过 | 合并态通过 | 构建通过 | 测试通过 | 契约通过 | 安全通过 | 冲突低
|
||||
|
||||
## PR #123
|
||||
**贡献价值：** <span style="color:#067647"><strong>功能增量值得合入</strong></span> **[passed]**：补齐高频批量操作缺口；依据：默认分支无等价能力、需求、Diff 和受益范围；影响：减少重复人工操作。
|
||||
**合并态：** <span style="color:#067647"><strong>可干净应用到最新主线</strong></span> **[passed]**：当前 head 没有文本冲突；依据：固定 base/head SHA 的隔离 worktree 合并结果；影响：无合并阻断。
|
||||
**构建：** <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/current 对照与 golden 测试；影响：现有调用方无需迁移。
|
||||
**安全与发布：** <span style="color:#067647"><strong>安全与发布门禁通过</strong></span> **[passed]**：未发现凭据、权限或危险输入阻断；依据：安全矩阵、依赖和发布影响检查；影响：无额外发布前置。
|
||||
**集成结论：** <span style="color:#067647"><strong>可进入合并队列</strong></span> **[merge]**：价值和全部技术门禁均成立；依据：IN-001 至 IN-006 与同一 SHA 的验证证据；下一步：维护者执行最终合并。
|
||||
|
||||
## 需要记录的动作
|
||||
1. **[IN-001][low] 更新** 发布说明（责任：维护者）。
|
||||
|
|
|
|||
|
|
@ -1,322 +1,325 @@
|
|||
---
|
||||
name: gitlink-pr-topology
|
||||
description: "GitLink open PR 队列关系专项分析：识别依赖、继承、重叠、替代、冲突、互补和可打包评审关系，比较重叠实现的完整性并给出处理顺序，生成带 TP 编号和证据置信度的只读 Markdown 报告。用户只需点名 gitlink-pr-topology 并提供仓库或指定 PR 编号集合；默认不调用其他 Skill、不修改远端。"
|
||||
description: "GitLink PR 仓库关系专项分析：把一个或多个目标 PR 分别与当前默认分支源码、全部 open PR 和全部 merged PR 对照，识别已实现、扩展、依赖、继承、重叠、替代、冲突、互补和联合评审关系，生成带 TP 编号、覆盖统计和证据置信度的只读 Markdown 报告。指定 PR 只限制目标，不缩小仓库对照范围；默认不调用其他 Skill、不修改远端。"
|
||||
---
|
||||
|
||||
## 已合并功能的增量证据
|
||||
|
||||
配套基础能力 PR #429 提供统一的 PR 文件、提交和 Review 证据，PR #430 提供队列变化。它们未合并或命令不可用时，必须回退到现有只读接口并标记限制；可用时先取一次队列快照，再为候选关系补取证据：
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +review-queue --owner <owner> --repo <repo> --previous queue-previous.json --format json
|
||||
gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <number> --include-commits=true --format json
|
||||
```
|
||||
|
||||
本 Skill 只输出 `TP-` 关系、证据、置信度和处理顺序，不把队列变化直接解释为代码缺陷，也不替代 `gitlink-code-review` 和 `gitlink-pr-integrator` 的结论。
|
||||
|
||||
队列差异应先按 `new`、`resolved` 和排名/优先级变化缩小候选集，再对候选 PR 比较文件、命令入口和输出字段。`stale` 或 `waiting_on` 是维护协作信号，不构成功能继承或重叠证据；只有存在文件、API、分支或正文证据时，才能输出 `depends_on`、`overlaps` 或 `supersedes`。
|
||||
|
||||
# gitlink-pr-topology
|
||||
# GitLink PR 仓库关系分析
|
||||
|
||||
**CRITICAL - 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。**
|
||||
**CRITICAL - GitLink 平台数据采集和回写只使用 `gitlink-cli`。**
|
||||
**CRITICAL - 这个 skill 关注的是 PR 与 PR 之间的关系，不代替单条 PR 的代码审查或合并验收。**
|
||||
**CRITICAL - 如果需要把中文报告写入文件或重定向输出，在 Windows PowerShell 中先切到 UTF-8 输出链路。**
|
||||
**CRITICAL - GitLink 平台数据采集只使用 `gitlink-cli`；本地源码分析可以使用 `git`、`rg` 和仓库自带工具。**
|
||||
**CRITICAL - 指定的 PR 编号只定义目标 PR，不得把比较范围缩成这些 PR 之间。**
|
||||
**CRITICAL - 本 Skill 判断功能关系，不代替代码缺陷审查、合并验收或 SLA 治理。**
|
||||
|
||||
## 解决的问题
|
||||
|
||||
维护者需要知道的不是“目标 PR 彼此有没有关系”，而是每个目标 PR 相对于仓库当前能力处在什么位置：
|
||||
|
||||
1. 主线源码是否已经实现相同能力，目标 PR 是重复、补缺、扩展还是回归。
|
||||
2. 全部 open PR 中是否存在上游依赖、竞争实现、互补能力或潜在冲突。
|
||||
3. 全部 merged PR 中是否存在被继承的基础能力、已经合入的同类实现或演进来源。
|
||||
4. 如果存在重叠实现，哪一条覆盖更完整、测试更充分、与现有架构更一致。
|
||||
5. 维护者应独立评审、联合评审、调整顺序、择一保留还是先确认产品方向。
|
||||
|
||||
## 默认调用契约
|
||||
|
||||
用户只需说“使用 `gitlink-pr-topology` 分析 `<owner>/<repo>` 的 open PR”，也可以列出若干 PR 编号限制范围。默认扫描当前 open 队列；除非仓库无法确定，不要求用户重复说明关系类型、输出格式或保存位置。
|
||||
用户可以提供仓库和一个或多个目标 PR，例如“分析 `Gitlink/gitlink-cli` 的 #430、#431”。调用范围解释为：
|
||||
|
||||
- **目标集合**：`#430`、`#431`，报告必须分别给出结论。
|
||||
- **仓库对照宇宙**：当前默认分支源码 + 全部 open PR + 全部 merged PR。
|
||||
- **目标间关系**：只是 open/merged 关系图中的附加边，不能代替目标与整个仓库的分析。
|
||||
|
||||
用户没有指定编号时，把当前全部 open PR 作为目标集合，并使用相同仓库对照宇宙。用户明确要求仅做局部快速检查时才允许缩小对照范围，报告必须醒目标为 `partial`，不能称为仓库全量关系分析。
|
||||
|
||||
点名后默认自动执行：
|
||||
|
||||
- 只分析 PR 之间的关系，不调用其他 Skill，不做单 PR 代码缺陷、CLI 契约、合并门禁或 SLA 判断。
|
||||
- 只读运行，不评论、不关闭、不合并、不分配、不修改远端。
|
||||
- 使用 `TP-001` 起的稳定编号，记录关系类型、相关 PR、证据、置信度、比较结论、建议动作和限制。
|
||||
- 首屏先显示最能减少重复评审的关系簇、冲突热点和建议顺序，最多 5 项；高置信度阻断/高风险使用颜色和粗体。
|
||||
- 一次运行只生成一份 UTF-8 Markdown，保存到 `reports/skill-runs/gitlink-pr-topology/<owner>-<repo>-<scope>-<yyyyMMdd-HHmmssZ>.md`；完整边列表放同一文件附录，不再额外生成第二份人读报告。
|
||||
- 自动翻页取得全部 open 和 merged PR；服务端状态过滤不可信时按真实状态、合并时间和关闭时间二次校验。
|
||||
- 固定默认分支名称与 baseline SHA，分析该 SHA 下的源码、测试、帮助、文档和历史。
|
||||
- 对每个目标 PR 独立建立“主线、open、merged”三层关系结论，不混用证据。
|
||||
- 使用 `TP-001` 起的稳定编号，记录目标、对照对象、关系、证据、置信度、影响和建议动作。
|
||||
- 全程只读，不评论、不关闭、不合并、不分配、不修改标签或远端内容。
|
||||
- 生成一份 UTF-8 Markdown，保存到 `reports/skill-runs/gitlink-pr-topology/<owner>-<repo>-<targets>-<yyyyMMdd-HHmmssZ>.md`。
|
||||
- Markdown 首屏按目标 PR 分节，每个方面先给醒目加粗结论，再写解释、`依据：` 和影响/下一步。
|
||||
- 聊天摘要按相同 PR 和方面输出纯文本精简版，去除 HTML、Markdown 和机器状态标签。每个方面用一至两句完整自然语言重新提炼直接结论、最关键依据和解释/影响，详细证据留在报告。
|
||||
|
||||
无法写入工作区时输出完整 Markdown 并标记“未落盘”。最终回复给出报告绝对路径、关系簇数量和第一处理顺序。
|
||||
最终回复按目标 PR 分节，由执行本 Skill 的 Agent 在理解完整报告后重新归纳主线、open 队列、merged 历史、综合关系和处理建议。每个方面最多两句，必须同时让维护者知道结论、主要依据以及为什么重要；禁止复制报告卡片、文件清单、长证据链和覆盖过程，禁止用省略号截断半句话。除报告链接外不输出 HTML、Markdown 展示标记或机器状态标签，也不能把多个方面合并成一段连续文字。
|
||||
|
||||
首屏固定先使用：
|
||||
## 强制分析范围
|
||||
|
||||
```markdown
|
||||
# PR 队列关系摘要
|
||||
### 1. 当前主线源码
|
||||
|
||||
**结论：** <span style="color:#B54708"><strong>需要重排</strong></span> **[reorder]**
|
||||
**范围：** open PR 18 | 关系簇 4 | 冲突热点 2 | 安全热点 1
|
||||
先固定默认分支和 baseline SHA：
|
||||
|
||||
## 先处理这 3 项
|
||||
|
||||
1. <span style="color:#B42318"><strong>[TP-001][blocking] 先处理</strong></span> #61，再处理 #63；证据：共享接口依赖。
|
||||
2. <span style="color:#B54708"><strong>[TP-002][high] 择一评审</strong></span> #71/#74；先比较测试与兼容性。
|
||||
3. <span style="color:#B54708"><strong>[TP-003][high] 集中复看</strong></span> #80/#82 的权限热点。
|
||||
```bash
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
git rev-parse <remote>/<default-branch>
|
||||
rg --files
|
||||
```
|
||||
|
||||
这个 skill 解决的是“PR 太多，维护者看不出它们彼此是什么关系”的问题。
|
||||
对每个目标 PR 的声明功能和变更路径，至少检查：
|
||||
|
||||
它不只回答“有没有重复”，还要回答：
|
||||
- 主线中是否已有同名命令、flag、API 包装、结构体、JSON 字段或帮助入口。
|
||||
- 主线已有行为是否由其他路径实现，不能只按文件名判断“尚未实现”。
|
||||
- 目标 PR 是补齐主线缺口、扩展已有能力、重复已有实现，还是会覆盖或退化现有行为。
|
||||
- 主线测试、文档和调用方是否证明目标能力已经存在或形成兼容约束。
|
||||
|
||||
1. 哪些 PR 有明显的先后依赖，像 stacked PR 一样要按顺序处理。
|
||||
2. 哪些 PR 实际上在解决同一个需求、同一个 bug、同一个命令入口。
|
||||
3. 如果两条 PR 目标重叠，哪一条更完整、更稳、更值得保留。
|
||||
4. 哪些 PR 虽然不完全重复，但会在同一文件、同一命令、同一输出契约上互相打架。
|
||||
5. 哪些 PR 应该一起评审，避免维护者重复进入同一上下文。
|
||||
6. 当前 open PR 队列最合理的处理顺序是什么。
|
||||
本地仓库不在固定 baseline、存在用户未提交改动或无法取得默认分支时，使用只读 worktree 或 `git show <baseline>:<path>`，不得覆盖用户工作区。无法取得完整源码时把主线层标记为 `partial`。
|
||||
|
||||
## 效率版队列输出
|
||||
### 2. 全部 open PR
|
||||
|
||||
默认遵循 [`../gitlink-shared/references/maintenance-report-contract.md`](../gitlink-shared/references/maintenance-report-contract.md)，输出“关系摘要”而不是完整的两两比较表：
|
||||
自动翻页直到没有下一页，不得只读取默认第一页或最近 20-50 条：
|
||||
|
||||
运行键、证据台账、刷新和自动回写边界遵循 [`../gitlink-shared/references/maintenance-run-protocol.md`](../gitlink-shared/references/maintenance-run-protocol.md)。
|
||||
|
||||
1. 先给 open PR 数、关系簇数量、冲突热点、安全热点和建议处理顺序。
|
||||
2. 只展示会改变维护决策的最多 5 条关系；相同关系簇合并成一项，完整边列表放附录或 JSON。
|
||||
3. 每条关系使用 `TP-xxx` 稳定编号，写明证据、置信度和建议动作；没有足够证据时标为 `candidate`，不能断言重复或 supersedes。
|
||||
4. 对同时修改认证、权限、命令执行、路径处理、依赖或输出敏感数据的 PR，增加 `security_hotspot` 关系，要求先完成安全审查再排序。
|
||||
|
||||
## 关系判定的证据等级
|
||||
|
||||
关系图谱先建立候选边，再判定关系，不允许仅凭标题相似就断言重复：
|
||||
|
||||
| 关系 | 最低证据 | 输出动作 |
|
||||
|------|----------|----------|
|
||||
| `depends_on` / `stacked_on` | 分支、提交、API 字段或文件引用形成明确先后 | 先处理被依赖 PR |
|
||||
| `overlaps` / `duplicate_candidate` | 同一命令、文件、Issue 或行为目标，且 Diff 有交集 | 合并评审上下文或择一 |
|
||||
| `supersedes` | 目标相同且一条覆盖另一条的功能、测试和文档 | 保留更完整者，另一条进入人工确认 |
|
||||
| `conflicts` | 同一契约/代码区域存在互斥修改 | 先解决冲突再排序 |
|
||||
| `complements` | 目标不同但共享稳定接口或可以串联 | 建议打包评审，不判重复 |
|
||||
|
||||
置信度分为 `high`、`medium`、`candidate`。`candidate` 只能作为待核对关系，不能直接建议关闭 PR；关系动作必须引用文件、分支、字段或快照证据。队列的 `stale`、`waiting_on` 只影响维护排序，不构成功能关系。
|
||||
|
||||
关系图谱的首屏最多列 5 个关系簇，并同时给出“保留、先后处理、并行评审、人工确认”四类动作之一；完整边列表和两两评分放 JSON 附录。
|
||||
|
||||
每条关系都要登记 `TP-` 编号、置信度、关系证据和建议动作；队列快照缺失或 PR head 已变化时，将关系标为 `stale`/`candidate`，不使用旧图谱直接建议关闭或替代。
|
||||
|
||||
首屏示例：
|
||||
|
||||
```markdown
|
||||
# PR 队列关系摘要
|
||||
**结论：** <span style="color:#B54708"><strong>需要重排</strong></span> **[reorder]**
|
||||
**范围：** 18 个 open PR | 4 个关系簇 | 2 个高风险热点
|
||||
|
||||
## 先处理
|
||||
1. **[TP-001][blocking] 先处理** #61，再处理 #63：共享 `shortcuts/pr/`，#63 依赖 #61 的输出字段。
|
||||
2. **[TP-002][high] 择一评审** #71 / #74：目标重叠，但 #74 缺安全和回归测试，不能直接判定 supersedes。
|
||||
3. **[TP-003][high] 安全复查** #80 / #82：同时改变权限校验。
|
||||
```bash
|
||||
gitlink-cli pr +list --owner <owner> --repo <repo> --state open --page <page> --limit 100 --format json
|
||||
```
|
||||
|
||||
先按标题、issue、改动文件和目录做低成本候选筛选，再对候选关系读取 diff、review 和测试证据；不要对所有 PR 做完整笛卡尔积分析。
|
||||
对响应按真实状态二次过滤、按 PR 编号去重，并记录：
|
||||
|
||||
## 职责边界与组合协同
|
||||
- API 返回总数、分页数、去重后 open 数。
|
||||
- 被状态二次过滤排除的编号。
|
||||
- 失败页和是否存在截断。
|
||||
|
||||
独立运行时，本 Skill 只判断多个 open PR 之间的关系，不判断单条 PR 的代码缺陷、契约通过与否或维护者响应是否超时。组合运行时向 `gitlink-pr-integrator` 交接 `TP-xxx` 关系和建议顺序，向 `gitlink-maintainer-radar` 交接冲突热点和待处理簇；`security_hotspot` 只表示需要安全复查，不等同于已确认漏洞。
|
||||
指定 PR 可能是 closed/merged 历史项，但不能因此把其他 open PR 排除。对每个目标，从全部 open 元数据中粗筛候选，再为候选补取文件、Diff、Review 和提交证据。
|
||||
|
||||
## 不覆盖的内容
|
||||
### 3. 全部 merged PR
|
||||
|
||||
下面这些不属于本 skill 的职责：
|
||||
同样自动翻页取得全部 merged PR，不能只看最近合并项：
|
||||
|
||||
- 单条 PR 的贡献价值和实现审查：交给 `gitlink-code-review`；集成价值与执行验证交给 `gitlink-pr-integrator`
|
||||
- 单条 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
|
||||
```bash
|
||||
gitlink-cli pr +list --owner <owner> --repo <repo> --state merged --page <page> --limit 100 --format json
|
||||
```
|
||||
|
||||
保存报告时显式指定 UTF-8：
|
||||
如果快捷命令不能可靠返回 merged 状态，使用 `gitlink-cli api GET` 调用对应只读列表接口，再根据真实 `merged_at`、状态字段和合并提交二次过滤。记录总页数、merged 总数、失败页和截断状态。
|
||||
|
||||
```powershell
|
||||
$report | Set-Content -Path .\pr-topology-report.md -Encoding utf8
|
||||
全量 merged PR 先做元数据与模块索引；再结合默认分支 `git log`、`git blame`、路径历史和目标 PR 变更定位深度候选。这样保证所有 merged PR 都进入筛选范围，同时避免对历史中每一条 PR 拉取完整 Diff。
|
||||
|
||||
## 分层取证策略
|
||||
|
||||
“全量分析”不等于对所有对象执行昂贵的笛卡尔积比较，采用两阶段方法：
|
||||
|
||||
### 阶段 A：全量覆盖
|
||||
|
||||
对全部 open 和 merged PR 读取并索引：
|
||||
|
||||
- 编号、标题、正文摘要、状态、关联 Issue。
|
||||
- base/head、作者、创建/更新时间、merged commit。
|
||||
- 涉及模块、命令名、API 名、flag、输出字段和主要路径关键词。
|
||||
|
||||
目标 PR 必须读取完整详情、文件列表、Diff、提交和 Review：
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +view --owner <owner> --repo <repo> --id <target> --format json
|
||||
gitlink-cli pr +files --owner <owner> --repo <repo> --id <target> --format json
|
||||
gitlink-cli pr +diff --owner <owner> --repo <repo> --id <target> --format json
|
||||
gitlink-cli pr +reviews --owner <owner> --repo <repo> --id <target> --format json
|
||||
```
|
||||
|
||||
组合上下文可用时可以使用：
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +review-context --owner <owner> --repo <repo> --number <target> --include-commits=true --format json
|
||||
```
|
||||
|
||||
命令不可用时回退到现有只读命令并记录限制，不能把“不支持命令”误报成“没有关系”。
|
||||
|
||||
### 阶段 B：候选深度比较
|
||||
|
||||
出现以下任一信号时进入深度比较：
|
||||
|
||||
- 相同 Issue、需求目标、命令、flag、API、JSON 字段或用户行为。
|
||||
- 修改文件相同，或修改同一模块/调用链的上下游。
|
||||
- PR 正文、提交或代码显式引用另一个 PR 提供的符号或契约。
|
||||
- 主线历史表明目标路径来自某条 merged PR。
|
||||
- 一条实现提供基础信号，另一条消费该信号形成上层能力。
|
||||
|
||||
只对候选补拉完整 Diff、文件、测试和 Review。无候选关系时也要报告“已覆盖多少对象、采用哪些筛选字段、未发现何种关系”，不能静默省略。
|
||||
|
||||
## 关系类型
|
||||
|
||||
先阅读 [`references/relationship-taxonomy.md`](references/relationship-taxonomy.md) 了解关系定义和证据标准。这个 skill 至少识别以下六类关系：
|
||||
关系边的对照对象可以是 `mainline:<sha/path/capability>`、`open:#<number>` 或 `merged:#<number>`。
|
||||
|
||||
1. `depends_on`
|
||||
表示 PR B 依赖 PR A 先落地，否则 B 难以独立评审、测试或合并。
|
||||
| 关系 | 含义 | 最低证据 |
|
||||
|---|---|---|
|
||||
| `already_in_mainline` | 主线已存在等价能力，目标增量可能重复 | 可定位源码行为、测试或帮助入口 |
|
||||
| `extends_mainline` | 目标在主线现有能力上增加有效场景 | 主线与目标 Diff 的行为差异 |
|
||||
| `fills_mainline_gap` | 主线确认缺失该能力，目标补齐空白 | 全仓搜索、调用链和测试缺口 |
|
||||
| `regresses_mainline` | 目标会删除、绕过或破坏现有行为 | 主线对照和目标 Diff |
|
||||
| `depends_on` / `stacked_on` | 不先具备对照 PR 的能力，目标无法独立工作 | 分支链、提交、符号或契约引用 |
|
||||
| `inherits_from` | 目标沿用已 merged 或 open PR 的基础设计，但可独立演进 | 代码历史、符号和设计来源 |
|
||||
| `overlaps_with` | 双方解决同一需求或改变同一行为 | 行为目标加文件/命令/Issue 证据 |
|
||||
| `supersedes` | 一方完整覆盖另一方且更适合保留 | 功能、测试、文档和兼容性包含关系 |
|
||||
| `conflicts_with` | 双方对同一代码或契约给出互斥修改 | 相邻 Diff、字段或默认值冲突 |
|
||||
| `complements` | 目标不同但能力可组合，组合后价值更完整 | 稳定接口、生产/消费或工作流证据 |
|
||||
| `review_together` | 共享上下文，联合评审能减少重复工作 | 同模块、同契约或互补链路 |
|
||||
| `merge_after` | 非硬依赖，但先后处理可避免返工 | 上游契约仍可能变化 |
|
||||
|
||||
2. `overlaps_with`
|
||||
表示两条 PR 在需求目标、命令入口、模块范围或改动文件上明显重叠。
|
||||
详细定义见 [`references/relationship-taxonomy.md`](references/relationship-taxonomy.md)。`stale`、`waiting_on` 和更新时间只属于维护信号，不能单独证明功能关系。
|
||||
|
||||
3. `supersedes`
|
||||
表示一条较新的 PR 在同一目标上覆盖更完整，足以替代另一条较弱 PR。
|
||||
置信度使用：
|
||||
|
||||
4. `conflicts_with`
|
||||
表示两条 PR 即使目标不同，也会在同一文件、同一 flag、同一 JSON 字段、同一帮助文案或同一 API 包装层上互相冲突。
|
||||
- `high`：有源码、Diff、提交链、字段引用或明确正文证据。
|
||||
- `medium`：目标和模块高度一致，已有多项间接证据但缺少一项关键验证。
|
||||
- `candidate`：只有标题、关键词或目录相似，需要继续取证。
|
||||
|
||||
5. `review_together`
|
||||
表示几条 PR 共享足够多的上下文，维护者一起看更高效。
|
||||
`candidate` 不能用于建议关闭、替代或阻止合并。
|
||||
|
||||
6. `merge_after`
|
||||
表示不是严格代码依赖，但为了减少返工，建议某条 PR 排在另一条之后处理。
|
||||
## 每个目标 PR 的强制结论
|
||||
|
||||
## 标准流程
|
||||
每个目标 PR 都必须独立回答：
|
||||
|
||||
### Step 1：拉取 open PR 队列
|
||||
1. **对主线：** 已实现、扩展、补缺、重复、回归或 `not_verifiable`，并引用源码路径/符号/测试。
|
||||
2. **对全部 open PR：** 发现的依赖、重叠、冲突和互补候选；没有关系时说明覆盖数量和筛选依据。
|
||||
3. **对全部 merged PR：** 继承来源、历史重叠、已合入替代能力；没有关系时说明覆盖数量和历史定位方式。
|
||||
4. **目标间附加关系：** 只有确有证据时再说明指定目标之间的关系。
|
||||
5. **维护动作：** 独立评审、先处理上游、联合评审、择一比较、调整设计或人工确认。
|
||||
|
||||
先列出目标仓库的 open PR：
|
||||
例如指定 `#430、#431` 时，不能只输出：
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +list --owner <owner> --repo <repo> --state open --page 1 --limit 50 --format json
|
||||
> #431 依赖 #430，两者互补，建议一起评审。
|
||||
|
||||
必须分别输出类似：
|
||||
|
||||
```markdown
|
||||
## PR #431
|
||||
**对主线：** <span style="color:#B54708"><strong>缺少目标声明的上游契约</strong></span> **[partial]**：baseline 未提供某项 workflow 能力；依据：`cmd/...`、`shortcuts/workflow/...` 和帮助输出；影响：目标暂不能独立验证。
|
||||
**对 open 队列：** <span style="color:#B54708"><strong>存在一个顺序依赖</strong></span> **[reorder]**：#430 提供目标消费的队列字段；依据：全部 12 条 open PR 的元数据索引和候选 Diff；下一步：先稳定 #430 字段。
|
||||
**对 merged 历史：** <span style="color:#067647"><strong>继承既有证据结构但没有重复实现</strong></span> **[passed]**：#429 是上下文证据来源；依据：全部 86 条 merged PR 索引、Git 历史和符号来源；影响：保留演进关系。
|
||||
**关系判断：** <span style="color:#175CD3"><strong>与 #430 互补且应联合评审</strong></span> **[review_together]**：两者位于基础信号与消费层；依据：字段生产/消费关系且文件交集不是唯一标准；影响：一次确认接口稳定性。
|
||||
**处理建议：** <span style="color:#B54708"><strong>先稳定上游契约，再复看 #431</strong></span> **[reorder]**：当前主要风险是契约漂移；依据：上述主线与 open 关系；下一步：固定字段和默认值后重新运行。
|
||||
```
|
||||
|
||||
注意：
|
||||
示例数字和关系不能复用，必须来自本轮证据。
|
||||
|
||||
- `--state open` 的服务端过滤并不总是可靠，必须再用 `pull_request_status == 0` 做客户端过滤。
|
||||
- 队列过大时优先扫描最近活跃的前 20-50 条，而不是一次吃完整个仓库。
|
||||
## 重叠实现比较
|
||||
|
||||
### Step 2：为每条 PR 建立关系画像
|
||||
发现 `overlaps_with`、`already_in_mainline` 或 `supersedes` 候选时，读取 [`references/comparison-rubric.md`](references/comparison-rubric.md)，至少比较：
|
||||
|
||||
对每条候选 PR 至少补拉这些信息：
|
||||
- 需求与边界场景覆盖。
|
||||
- 与仓库现有封装和命令结构的一致性。
|
||||
- 正常、失败、兼容和安全测试。
|
||||
- 帮助、文档、示例和变更说明。
|
||||
- 向后兼容、复杂度和维护成本。
|
||||
- 既有 Review 的吸收情况。
|
||||
|
||||
```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
|
||||
不能只说“A 更全面”。必须说明 A 多实现了什么、B 缺少什么、主线已有多少、可否拆分互补部分，以及建议保留或调整的依据。
|
||||
|
||||
## 输出结构
|
||||
|
||||
Markdown 首屏使用完整的逐 PR 判断卡，不先展示跨 PR 总段落或目标间关系：
|
||||
|
||||
```markdown
|
||||
# PR 仓库关系摘要
|
||||
|
||||
**分析基线：** `<default-branch>@<sha>`；源码文件 <n>；open PR <n>/<n> 页；merged PR <n>/<n> 页；失败页 <n>。
|
||||
|
||||
## PR #<target>
|
||||
**对主线：** <span style="color:<color>"><strong><最直接关系结论></strong></span> **[<status>]**：<简短解释>；依据：<源码路径、符号或测试>；影响：<对评审的含义>。
|
||||
**对 open 队列：** <span style="color:<color>"><strong><最直接关系结论></strong></span> **[<status>]**：<覆盖数量和关键关系>；依据：<分页、候选和 Diff>；影响：<排序或择一建议>。
|
||||
**对 merged 历史：** <span style="color:<color>"><strong><最直接关系结论></strong></span> **[<status>]**：<继承、重复或无关系>；依据：<历史索引与 Git 来源>；影响：<演进含义>。
|
||||
**关系判断：** <span style="color:<color>"><strong><依赖/重叠/互补结论></strong></span> **[<status>]**：<关系解释>；依据：<生产消费、行为或契约证据>；影响：<联合或独立评审>。
|
||||
**处理建议：** <span style="color:<color>"><strong><可执行建议></strong></span> **[<decision>]**：<为什么这样处理>；依据：<前述 TP 关系>；下一步：<明确动作>。
|
||||
|
||||
## PR #<next-target>
|
||||
...
|
||||
|
||||
## 先处理这几项
|
||||
1. **[TP-001][high] <动作>**：<目标、对照对象、证据和原因>。
|
||||
```
|
||||
|
||||
优先提取：
|
||||
完整报告顺序：
|
||||
|
||||
- PR 标题、描述、作者、创建时间、最近更新时间
|
||||
- base/head 分支、fork 来源
|
||||
- 修改文件、核心目录、是否触及同一条命令或同一 API 封装
|
||||
- 是否修改测试、帮助文案、README、示例
|
||||
- review 争议点、是否已有人指出重复或依赖关系
|
||||
- 关联 issue、里程碑、标签
|
||||
1. baseline SHA、源码索引、open/merged 分页与覆盖统计。
|
||||
2. 每个目标 PR 的主线关系。
|
||||
3. 每个目标 PR 与全部 open PR 的关系。
|
||||
4. 每个目标 PR 与全部 merged PR 的关系。
|
||||
5. 目标间附加关系和关系簇。
|
||||
6. 重叠实现的完整性比较。
|
||||
7. 建议处理顺序、证据台账、失败页和验证限制。
|
||||
|
||||
### Step 3：先做“候选关系”粗筛
|
||||
## UTF-8 安全写入与报告校验
|
||||
|
||||
先不要急着得结论，先把可能有关联的 PR 成对找出来。粗筛信号包括：
|
||||
使用当前 Agent 平台支持的明确 UTF-8 文件 API 写 Markdown；平台提供补丁式文件工具时优先使用。不要在 Windows PowerShell 5.1 中把含中文的 here-string、变量或命令输出通过管道传给 `Set-Content`/`Out-File`，这会在部分宿主编码下把中文永久写成 `?`。写入后必须按严格 UTF-8 重新读取。
|
||||
|
||||
- 标题和描述出现同一需求词、同一命令名、同一 issue 编号
|
||||
- 修改相同文件
|
||||
- 修改同一目录或同一 shortcuts 子模块
|
||||
- 同时触碰同一 flag、同一输出字段、同一错误提示
|
||||
- 一条 PR 的描述直接提到 “基于 #xx” “依赖 #xx” “替代 #xx”
|
||||
- 两条 PR 都在补同一类能力，例如 release、attachment、milestone、search
|
||||
保存后针对每个目标追加一个 `--require-pr`，并执行：
|
||||
|
||||
只把这些候选对放进下一步，不要把所有 PR 两两做重分析。
|
||||
```bash
|
||||
python -X utf8 skills/gitlink-shared/scripts/validate_pr_cards.py \
|
||||
--report <absolute-report-path> \
|
||||
--require-pr <target-number> \
|
||||
--min-cards 5 \
|
||||
--required-aspect "对主线" \
|
||||
--required-aspect "对 open 队列" \
|
||||
--required-aspect "对 merged 历史" \
|
||||
--required-aspect "关系判断" \
|
||||
--required-aspect "处理建议"
|
||||
```
|
||||
|
||||
### Step 4：判断具体关系类型
|
||||
多个目标在同一次命令中重复 `--require-pr`。校验器会拒绝连续 `???`、乱码、中文不足、缺少 PR 分节、结论不前置或没有明确 `依据：` 的判断卡。失败时必须重写并重新校验，不能返回损坏报告路径。
|
||||
|
||||
对每个候选对，结合 [`references/relationship-taxonomy.md`](references/relationship-taxonomy.md) 给出单一主关系，必要时允许附加次关系。
|
||||
## Agent 摘要交付
|
||||
|
||||
判断顺序建议如下：
|
||||
报告校验通过后，必须由执行本 Skill 的 Agent 根据完整报告重新提炼摘要，不能使用字符串
|
||||
截取、去标签或复制卡片原文代替理解与归纳。每个目标 PR 固定输出五行：
|
||||
|
||||
1. 先看是否存在明确依赖链。
|
||||
2. 再看是否实际上在做同一件事。
|
||||
3. 再看是否已出现“更完整版本替代较弱版本”。
|
||||
4. 如果目标不同但落点冲突，则标为冲突热点。
|
||||
5. 如果只是共享上下文但不冲突，标为建议一起评审。
|
||||
```text
|
||||
PR #<number>
|
||||
对主线：<结论>。<最关键依据，以及该事实为什么影响评审>。
|
||||
对 open 队列：<结论>。<最关键依据，以及联审、排序或择一含义>。
|
||||
对 merged 历史：<结论>。<最关键依据，以及继承、重复或演进含义>。
|
||||
关系判断：<结论>。<依赖、重叠、互补或冲突的简短解释>。
|
||||
处理建议：<结论>。<维护者下一步及其理由>。
|
||||
```
|
||||
|
||||
没有足够证据时，写成 `possible_overlap` 或 `possible_dependency`，不要过度下结论。
|
||||
摘要质量要求：
|
||||
|
||||
### Step 5：在重叠 PR 中比较“谁更值得保留”
|
||||
- 必须由 Agent 根据报告结论重新提炼，不得复制报告卡片原文或机械删除格式。
|
||||
- 每个方面一至两句完整句子，通常控制在 50 至 120 个中文字符，不使用省略号截断。
|
||||
- 依据只保留最能支撑结论的一项事实，例如“主线已有基础实现”“扫描全部 open PR 后只有两条高置信候选”；不复制路径和编号清单。
|
||||
- 解释必须回答“为什么维护者需要关心”，不能只换一种说法重复结论。
|
||||
- 多个 PR 分别归纳，不把共同关系写成一段跨 PR 总结。
|
||||
- 最后一行通过当前 Agent 平台支持的可点击链接或文件附件交付报告。支持 Markdown 本地链接时使用 `完整报告：[<文件名>](<绝对路径>)`；不支持时使用平台原生文件引用，不能只给不可点击的裸路径。
|
||||
|
||||
如果两条或多条 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`
|
||||
- `counterpart_type`: `mainline`、`open_pr` 或 `merged_pr`
|
||||
- `counterpart`
|
||||
- `relation`
|
||||
- `confidence`
|
||||
- `evidence`
|
||||
- `impact`
|
||||
- `recommended_action`
|
||||
|
||||
### 2. 维护者摘要报告
|
||||
## 覆盖与失败语义
|
||||
|
||||
报告至少包含：
|
||||
报告必须区分：
|
||||
|
||||
1. open PR 总数和本轮纳入分析的数量
|
||||
2. 主要依赖链
|
||||
3. 主要重叠簇
|
||||
4. 明显替代关系
|
||||
5. 冲突热点文件/模块
|
||||
6. 建议处理顺序
|
||||
7. 需要进一步切换到 `gitlink-code-review` 或 `gitlink-pr-integrator` 深挖的对象
|
||||
- `complete`：全部 open/merged 页成功，baseline 源码可读。
|
||||
- `partial`：存在失败页、权限缺口、源码不完整或命令回退。
|
||||
- `not_verifiable`：无法取得目标 Diff 或 baseline，不能形成可靠关系。
|
||||
|
||||
## 报告模板
|
||||
禁止以下行为：
|
||||
|
||||
```markdown
|
||||
# <owner>/<repo> PR 队列关系图谱
|
||||
- 只比较用户指定的目标 PR。
|
||||
- 只扫描第一页或最近 N 条，却宣称“全部 PR”。
|
||||
- 把“文件交集为 0”直接等同于“没有功能重叠”；不同层也可能实现同一行为。
|
||||
- 把“使用同一字段”自动断言为硬依赖；要判断字段是否已在主线或可由目标自行提供。
|
||||
- 把 merged PR 当作当前待处理项；它只用于来源、重复和演进对照。
|
||||
- 因某个 API 不可用而填入历史样例或猜测关系。
|
||||
|
||||
扫描时间：<timestamp>
|
||||
open PR：<n>
|
||||
纳入分析：<n>
|
||||
## 职责边界
|
||||
|
||||
## 1. 依赖链
|
||||
- #41 -> #44 -> #52
|
||||
说明：#44 基于 #41 引入的 API 包装，#52 又建立在 #44 的 CLI 参数层上。
|
||||
本 Skill 可以为了判断关系检查源码结构、测试和文档，但不输出单条 PR 的代码缺陷清单，也不决定合并门禁。需要代码质量审查时交给 `gitlink-code-review`，需要实际合并与测试验收时交给 `gitlink-pr-integrator`，需要等待时长和责任人排序时交给 `gitlink-maintainer-radar`。
|
||||
|
||||
## 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 队列关系图谱，方便维护者决定先看谁。”
|
||||
- 指定编号是否只限制目标，而没有缩小主线/open/merged 对照范围。
|
||||
- 是否记录 baseline SHA、源码索引规模、全部 open/merged 页数和去重后数量。
|
||||
- 是否为每个目标分别给出主线、open、merged 三层结论。
|
||||
- 是否把目标间关系放在附加位置，而不是充当全部结果。
|
||||
- 每条高/中置信关系是否引用源码、Diff、提交、字段、Issue 或 Review 证据。
|
||||
- “无关系”是否同时说明实际覆盖数量和筛选依据。
|
||||
- Markdown 首屏是否按 PR 分节并包含五张完整判断卡。
|
||||
- 最终摘要是否由 Agent 根据报告重新提炼，而不是复制、去标签或截断报告原文。
|
||||
- 摘要是否按 PR 和五方面输出一至两句完整自然语言，并同时包含结论、关键依据和解释/影响。
|
||||
- 最终报告是否通过当前 Agent 平台支持的可点击链接或文件附件交付。
|
||||
- Markdown 是否通过 `validate_pr_cards.py` 的全部目标和五方面校验。
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
interface:
|
||||
display_name: "PR 关系图谱"
|
||||
short_description: "分析 open PR 之间的依赖、重叠、替代和建议处理顺序。"
|
||||
default_prompt: "使用 $gitlink-pr-topology 分析指定仓库或 PR 集合。按 Skill 默认契约只读识别 PR 关系和处理顺序，并生成关键结论前置的单一 Markdown 报告。"
|
||||
short_description: "分析目标 PR 与主线源码、全部 open/merged PR 的仓库关系。"
|
||||
default_prompt: "使用 $gitlink-pr-topology 分析指定仓库和目标 PR；目标编号只限制分析对象，对照范围必须包含当前主线源码、全部 open PR 和全部 merged PR。Markdown 校验通过后，由执行 Skill 的 Agent 理解报告并重新提炼逐 PR 五方面摘要，每方面用一至两句完整自然语言说明结论、关键依据和解释/影响，不复制报告原文、不机械去格式、不截断句子；最后通过可点击链接或文件附件交付报告，全程只读。"
|
||||
|
|
|
|||
|
|
@ -1,22 +1,35 @@
|
|||
# 轻量 PR 队列关系示例
|
||||
# 目标 PR 与仓库关系示例
|
||||
|
||||
先使用列表信息筛选候选，再对候选读取 diff，避免所有 PR 两两拉取完整内容。
|
||||
指定 `#430、#431` 只表示这两条是目标，不表示只比较它们。先固定主线并完整扫描 open/merged 元数据：
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state open --limit 50 --format json
|
||||
gitlink-cli pr +files --owner Gitlink --repo gitlink-cli --id <candidate> --format json
|
||||
gitlink-cli pr +diff --owner Gitlink --repo gitlink-cli --id <candidate> --format json
|
||||
gitlink-cli repo +info --owner Gitlink --repo gitlink-cli --format json
|
||||
gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state open --page 1 --limit 100 --format json
|
||||
gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state merged --page 1 --limit 100 --format json
|
||||
gitlink-cli pr +files --owner Gitlink --repo gitlink-cli --id <target> --format json
|
||||
gitlink-cli pr +diff --owner Gitlink --repo gitlink-cli --id <target> --format json
|
||||
```
|
||||
|
||||
列表命令必须继续翻页直到结束。全部对象先进入元数据索引，只有命令、模块、Issue、字段、路径或历史来源命中的候选才补拉完整 Diff。
|
||||
|
||||
```markdown
|
||||
# PR 队列关系摘要
|
||||
**结论：** <span style="color:#B54708"><strong>需要重排</strong></span> **[reorder]**
|
||||
**范围：** 12 个 open PR | 3 个关系簇 | 1 个安全热点
|
||||
# PR 仓库关系摘要
|
||||
|
||||
## 先处理
|
||||
1. **[TP-001][blocking] 先处理** #61，再处理 #63：共享命令入口且 #63 使用 #61 的输出字段。
|
||||
2. **[TP-002][high] 一起评审** #71、#74：修改同一 API 包装层，需统一错误契约。
|
||||
3. **[TP-003][high] 安全复查** #80：修改权限校验，不能仅凭标题判定可合并。
|
||||
**分析基线：** `master@abcdef1`；源码 420 个文件；open PR 12 条/1 页；merged PR 86 条/2 页；失败页 0。
|
||||
|
||||
## PR #431
|
||||
**对主线：** <span style="color:#175CD3"><strong>扩展主线维护能力</strong></span> **[extends_mainline]**：baseline 没有维护编排入口但已有 Skill 目录约定；依据：主线源码和 frontmatter 契约；影响：应保持现有规范。
|
||||
**对 open 队列：** <span style="color:#B54708"><strong>存在一个上游契约依赖</strong></span> **[reorder]**：#430 提供目标消费的队列字段；依据：全部 12 条 open 索引和候选 Diff；下一步：先稳定字段。
|
||||
**对 merged 历史：** <span style="color:#067647"><strong>继承证据结构且无重复编排器</strong></span> **[passed]**：#429 提供上下文证据结构；依据：全部 86 条 merged 索引与 Git 历史；影响：保留演进来源。
|
||||
**关系判断：** <span style="color:#175CD3"><strong>与 #430 互补并适合联合评审</strong></span> **[review_together]**：一条生产队列信号、一条消费信号；依据：字段与调用链；影响：一次确认契约。
|
||||
**处理建议：** <span style="color:#B54708"><strong>先稳定上游字段，再复看 #431</strong></span> **[reorder]**：当前风险来自字段漂移；依据：TP-001 与 TP-002；下一步：固定契约后重跑。
|
||||
|
||||
## PR #430
|
||||
**对主线：** <span style="color:#067647"><strong>补齐主线队列差异缺口</strong></span> **[fills_mainline_gap]**：baseline 有 workflow 框架但缺少等待方输出；依据：主线命令与源码索引；影响：形成有效增量。
|
||||
**对 open 队列：** <span style="color:#175CD3"><strong>存在互补下游且无竞争实现</strong></span> **[review_together]**：#431 消费新增字段；依据：全部 12 条 open 索引与候选 Diff；影响：需要确认接口。
|
||||
**对 merged 历史：** <span style="color:#067647"><strong>继承 workflow 基础但没有历史重复</strong></span> **[passed]**：历史只有基础命令来源；依据：全部 86 条 merged 索引与路径历史；影响：无需择一。
|
||||
**关系判断：** <span style="color:#175CD3"><strong>是 #431 的互补上游</strong></span> **[complements]**：提供队列信号；依据：生产/消费字段关系；影响：建议联合理解。
|
||||
**处理建议：** <span style="color:#175CD3"><strong>先独立验证字段契约</strong></span> **[reorder]**：下游依赖稳定字段；依据：TP-001；下一步：通过契约测试后处理 #431。
|
||||
```
|
||||
|
||||
关系证据不足时写 `candidate`，并说明还缺哪些 diff、review 或测试证据。
|
||||
示例数字和关系只定义格式。实际运行必须重新分页、固定 baseline、读取源码并生成当前证据，不能复用示例判断。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,24 @@
|
|||
# 关系分类与证据标准
|
||||
|
||||
在 `gitlink-pr-topology` 中，不要把“有点像”直接写成“重复”。先按下面的证据标准分型。
|
||||
在 `gitlink-pr-topology` 中，不要把“有点像”直接写成“重复”。关系的起点始终是目标 PR，对照对象可以是当前主线能力、open PR 或 merged PR。先标记 `counterpart_type`，再按下面的证据标准分型。
|
||||
|
||||
## 0. 主线关系
|
||||
|
||||
### already_in_mainline
|
||||
|
||||
主线已经存在等价用户行为。必须引用可执行入口、源码符号、测试或帮助，不能只因为出现相同关键词就判定重复。
|
||||
|
||||
### extends_mainline
|
||||
|
||||
目标在主线既有能力上增加新的有效场景，同时保持原契约。证据应同时展示主线行为与目标增量。
|
||||
|
||||
### fills_mainline_gap
|
||||
|
||||
主线确认缺少目标能力。必须完成全仓搜索和调用链检查，避免漏掉不同目录中的等价实现。
|
||||
|
||||
### regresses_mainline
|
||||
|
||||
目标会删除、绕过或破坏主线已有行为。必须引用 baseline 与目标 Diff 的具体差异。
|
||||
|
||||
## 1. depends_on
|
||||
|
||||
|
|
@ -16,6 +34,8 @@
|
|||
- 两条 PR 的 head/base 明显形成链条
|
||||
- 下游代码直接引用上游新增符号
|
||||
|
||||
如果上游能力已经存在于主线，关系应写为 `extends_mainline` 或 `inherits_from`，不能继续把 merged PR 当作未满足的硬依赖。
|
||||
|
||||
## 2. overlaps_with
|
||||
|
||||
适用场景：
|
||||
|
|
@ -44,6 +64,8 @@
|
|||
- 更强 PR 同时补齐测试、文档、兼容性
|
||||
- 较弱 PR 长期未更新，而较强 PR 已响应 review 并继续演进
|
||||
|
||||
对 merged PR 使用 `supersedes` 时要谨慎：已合入能力不能“关闭”，动作应是说明目标替换或升级哪部分主线实现，并评估兼容迁移。
|
||||
|
||||
## 4. conflicts_with
|
||||
|
||||
适用场景：
|
||||
|
|
@ -71,6 +93,16 @@
|
|||
- 同一目录、同一组件、同一命令族
|
||||
- 目标互补而非互斥
|
||||
|
||||
## 5.1 complements
|
||||
|
||||
适用场景：
|
||||
|
||||
- 一条提供基础信号或 API，另一条把它用于上层工作流
|
||||
- 目标不同、文件可以不重叠，但组合后形成完整用户能力
|
||||
- 单独评审仍可进行，联合评审能确认接口和命名是否一致
|
||||
|
||||
`complements` 不自动等于 `depends_on`。只有下游无法在当前主线独立工作时才同时标记依赖。
|
||||
|
||||
## 6. merge_after
|
||||
|
||||
适用场景：
|
||||
|
|
@ -83,6 +115,16 @@
|
|||
- 上游 PR 改的是底层封装，下游 PR 改的是调用层
|
||||
- 先合并下游会造成明显返工
|
||||
|
||||
## 7. inherits_from
|
||||
|
||||
适用场景：
|
||||
|
||||
- 目标沿用某条 merged PR 引入的架构、命令或证据结构
|
||||
- 目标吸收 open PR 的设计但已经自带所需实现，不构成硬依赖
|
||||
- Git 历史、符号来源或正文可以定位明确演进链
|
||||
|
||||
输出时说明继承了什么、目标新增了什么，不能把历史来源误写成当前阻断。
|
||||
|
||||
## 低置信措辞
|
||||
|
||||
证据不足时，使用保守措辞：
|
||||
|
|
|
|||
|
|
@ -2,13 +2,27 @@
|
|||
|
||||
五个维护专项 Skill 和一个编排 Skill 统一遵循本协议。目标是让维护者在 30 秒内知道“先处理什么、为什么、下一步由谁做”，同时保留可追溯的证据。
|
||||
|
||||
## 默认调用与单报告落盘
|
||||
## 默认调用、聊天结论与证据落盘
|
||||
|
||||
用户点名某个 Skill 并给出可确定的仓库、PR 或本地改动范围后，该 Skill 必须自行应用只读边界、专项职责、严重性、首屏格式和保存规则。不得要求用户重复粘贴“不要调用其他 Skill”“不要修改远端”“关键结论放前面”等固定提示词。
|
||||
|
||||
五个专项 Skill 默认独立运行，不自动调用其他 Skill；只有 `gitlink-maintenance-orchestrator` 可以编排五个专项。目标无法从用户输入或当前 Git remote 唯一确定时才请求补充。
|
||||
|
||||
每次运行只生成一份主要人读 Markdown：
|
||||
每次运行必须产生两种互补呈现，内容结论必须一致：
|
||||
|
||||
1. **聊天结论**：在最终回复中直接给维护者可阅读的执行摘要，不能只返回“报告已保存”或一个文件路径。
|
||||
2. **证据报告**：将完整分析保存为一份主要人读 Markdown，作为复查、协作和答辩留存。
|
||||
|
||||
只要本轮包含 PR，聊天结论和 Markdown 首屏都必须先按 PR 分组，再按专项方面输出判断卡。不得把多个 PR 合并成一个总段落，也不得把多个方面压成一段连续叙述。聊天可以比报告更短，但不能删除方面结论和主要依据；聊天与报告的事实、编号和最终决策必须一致。
|
||||
|
||||
聊天摘要不是报告卡片的机械裁剪。执行 Skill 的 Agent 必须在读完完整报告后重新提炼维护者
|
||||
语言：按 PR 和方面用一至两句完整自然语言说明结论、最关键依据和解释/影响，省略路径清单、
|
||||
分页过程和次要证据。除最终报告链接外，聊天不输出 HTML、Markdown 展示标签或机器状态标签；
|
||||
详细依据保留在 Markdown。Markdown 校验通过不代表聊天交付通过，禁止复制完整卡片、机械
|
||||
删除格式或输出被省略号截断的半句话。报告应通过当前 Agent 平台支持的可点击链接或文件附件
|
||||
交付，而不是只给裸路径。
|
||||
|
||||
Markdown 路径：
|
||||
|
||||
```text
|
||||
reports/skill-runs/<skill>/<owner>-<repo>-<pr-number-or-queue>-<yyyyMMdd-HHmmssZ>.md
|
||||
|
|
@ -16,13 +30,46 @@ reports/skill-runs/<skill>/<owner>-<repo>-<pr-number-or-queue>-<yyyyMMdd-HHmmssZ
|
|||
|
||||
编排器使用 `<run-directory>/final-report.md`。多个 PR 放在同一份报告内，但每个 PR 的证据、发现和决策必须独立；原始 API、完整 Diff、阶段 JSON 和机器证据放附件，不再生成多份互相重复的人读报告。
|
||||
|
||||
Markdown 使用 UTF-8、无 ANSI，并在最终回复中给出绝对路径。无法落盘时输出完整 Markdown 并明确标记“未落盘”，不能只返回聊天摘要。
|
||||
Markdown 使用 UTF-8、无 ANSI，并在聊天结论后给出绝对路径。无法落盘时输出完整 Markdown 并明确标记“未落盘”。聊天结论不能省略，Markdown 也不能被聊天摘要替代。
|
||||
|
||||
## 解释性判断卡
|
||||
|
||||
首屏和聊天结论不能只列 `价值 passed`、`测试 failed` 等状态词。每个会影响决策的方面必须使用独立一行判断卡，回答三件事：
|
||||
|
||||
1. **结论是什么**：字段开头先给醒目的粗体/颜色结论和纯文本状态回退，让维护者快速定位结果。
|
||||
2. **看到了什么**：结论后立即说明 PR 实际增加或改变了什么，队列或契约出现了什么事实。
|
||||
3. **如何判断**：引用 Diff、默认分支、Review、测试、时间戳或其他可核验证据，说明采用了什么比较标准。
|
||||
|
||||
统一结构：
|
||||
|
||||
```markdown
|
||||
## PR #<number>
|
||||
**价值：** <span style="color:#067647"><strong>价值成立</strong></span> **[passed]**：增加 open 队列 SLA 与责任方识别；依据：默认分支差异、命令帮助和受益范围；影响：减少维护者手工判断。
|
||||
**实现：** <span style="color:#B42318"><strong>核心结果不可靠</strong></span> **[failed]**：真实响应中的关闭项仍进入 open 队列；依据：真实 API fixture 与复现命令；下一步：修复客户端二次过滤并补回归测试。
|
||||
```
|
||||
|
||||
固定顺序是“方面标签 → 醒目加粗结论 → 状态回退 → 简短解释 → `依据：` → 影响或下一步”。最直接的结论必须位于每张卡最前面，不能先写一段事实再让维护者到句尾找结论。每张卡至少包含明确的 `依据：`，并尽量控制在一行或两个短句内；完整证据放后文。
|
||||
|
||||
状态矩阵可以作为快速索引保留，但必须放在逐 PR 判断卡之后，不能代替判断依据。多个 PR 分别生成判断卡；不得把一条 PR 的证据用于另一条。最终总决策放在该 PR 全部方面之后，并使用粗体和颜色突出。
|
||||
|
||||
### 各 Skill 的默认方面
|
||||
|
||||
- `gitlink-code-review`：Review 建议、贡献价值、Review 履约、实现与逻辑、测试、安全、关键发现。
|
||||
- `gitlink-cli-contract-guard`：参数与帮助、JSON/文本输出、错误与退出码、编码与颜色、兼容与文档、契约结论。
|
||||
- `gitlink-pr-topology`：对主线、对 open 队列、对 merged 历史、关系判断、处理建议。
|
||||
- `gitlink-pr-integrator`：贡献价值、合并态、构建、测试、契约、安全与发布、集成结论。
|
||||
- `gitlink-maintainer-radar`：响应 SLA、等待方、Reviewer 负载、责任停滞、安全运营优先级、维护动作。
|
||||
- `gitlink-maintenance-orchestrator`：代码审查、CLI 契约、仓库关系、集成门禁、维护状态、最终结论。
|
||||
|
||||
没有相关改动的方面仍保留判断卡并写 `not_applicable` 及依据；证据不可用时写 `not_run/not_verifiable` 和缺失项，不能直接省略。
|
||||
|
||||
默认 open 队列必须按响应中的真实状态做客户端二次过滤。用户显式提供 closed/merged PR 时，只把它作为历史对照并注明状态，不纳入当前待审数量，也不建议重新打开，除非用户明确要求复审历史 PR。
|
||||
|
||||
## 默认输出层级
|
||||
|
||||
默认生成 `executive` 模式；用户明确要求细节时再生成 `standard` 或 `full`。
|
||||
|
||||
1. **执行摘要**：使用颜色、粗体和纯文本标签突出结论、阻断数、高风险数、安全门禁、验证状态和扫描范围。
|
||||
1. **执行摘要**：先用解释性判断卡说明事实、依据和判断，再使用颜色、粗体和纯文本标签突出最终结论、阻断数、高风险数、安全门禁、验证状态和扫描范围。
|
||||
2. **今日动作**：最多 5 项，按优先级排序；每项必须包含对象、责任方、下一动作和证据引用。
|
||||
3. **证据附录**：完整发现、命令输出摘要、文件/行号、时间戳和未验证项。
|
||||
|
||||
|
|
@ -83,7 +130,7 @@ Markdown 使用 HTML 颜色和粗体，同时必须提供纯 Markdown 回退，
|
|||
<span style="color:#067647"><strong>通过</strong></span> **[pass]**
|
||||
```
|
||||
|
||||
颜色只用于结论、严重性、门禁和动作，不要给整段正文着色。JSON、CSV 和命令管道输出禁止包含 ANSI 转义、HTML 标签或 emoji；使用纯字段值。
|
||||
颜色只用于每项判断的最终结论、总决策、严重性和关键动作，不要给事实与依据整段着色。JSON、CSV 和命令管道输出禁止包含 ANSI 转义、HTML 标签或 emoji；使用纯字段值。
|
||||
|
||||
在支持终端颜色时，可以根据 `NO_COLOR` 约定关闭 ANSI 颜色。报告落盘默认不写 ANSI。
|
||||
|
||||
|
|
@ -118,11 +165,14 @@ Markdown 使用 HTML 颜色和粗体，同时必须提供纯 Markdown 回退，
|
|||
$json | ConvertFrom-Json | Out-Null
|
||||
if ($json -match "`e\[|<span|</span>") { throw "JSON 含展示层标记" }
|
||||
|
||||
# Markdown 使用 UTF-8 保存，并检查替换字符
|
||||
$markdown | Set-Content .\maintenance-report.md -Encoding utf8
|
||||
$bytes = [IO.File]::ReadAllBytes('.\maintenance-report.md')
|
||||
$text = [Text.Encoding]::UTF8.GetString($bytes)
|
||||
if ($text.Contains([char]0xfffd) -or $text.Contains('?')) { throw "报告存在编码风险" }
|
||||
# Markdown 必须由支持显式 UTF-8 的文件 API 保存；平台提供补丁式文件工具时优先使用。
|
||||
# 不要在 Windows PowerShell 5.1 中把中文 here-string、变量或命令输出通过管道
|
||||
# 交给 Set-Content/Out-File。保存后使用严格 UTF-8 回读并执行逐 PR 卡片校验。
|
||||
python -X utf8 skills/gitlink-shared/scripts/validate_pr_cards.py `
|
||||
--report .\maintenance-report.md `
|
||||
--require-pr <number> `
|
||||
--min-cards <skill-required-card-count>
|
||||
```
|
||||
|
||||
最后一条检查只针对报告中预期的中文文本；如果业务数据本身包含问号，应改为检查 UTF-8 替换字符和已知乱码片段，并记录例外。
|
||||
校验器拒绝 UTF-8 替换字符、NUL、已知乱码片段、连续问号、中文叙述不足、缺少 PR 分节、
|
||||
结论未前置和缺少明确依据。单个业务问号允许保留，不能用“删除所有问号”掩盖编码损坏。
|
||||
|
|
|
|||
|
|
@ -0,0 +1,107 @@
|
|||
#!/usr/bin/env python3
|
||||
"""Validate UTF-8 Markdown reports that summarize one or more PRs."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
PR_HEADING = re.compile(r"^## PR #(\d+)(?:\s.*)?$")
|
||||
CARD_PATTERN = re.compile(
|
||||
r"^\*\*([^*\n]+)：\*\*\s*"
|
||||
r"<span\b[^>]*><strong>([^<]+)</strong></span>\s*"
|
||||
r"\*\*\[([^\]]+)\]\*\*：\s*(\S.*)$"
|
||||
)
|
||||
MOJIBAKE_PATTERNS = ("\ufffd", "\x00", "\x1b")
|
||||
|
||||
|
||||
def parse_pr_sections(lines: list[str]) -> dict[int, list[str]]:
|
||||
sections: dict[int, list[str]] = {}
|
||||
current: int | None = None
|
||||
for line in lines:
|
||||
match = PR_HEADING.match(line.strip())
|
||||
if match:
|
||||
current = int(match.group(1))
|
||||
sections.setdefault(current, [])
|
||||
continue
|
||||
if current is not None and line.startswith("## "):
|
||||
current = None
|
||||
elif current is not None:
|
||||
sections[current].append(line)
|
||||
return sections
|
||||
|
||||
|
||||
def validate_report(
|
||||
text: str,
|
||||
required_prs: list[int] | None = None,
|
||||
min_cards: int = 2,
|
||||
required_aspects: list[str] | None = None,
|
||||
) -> list[str]:
|
||||
errors: list[str] = []
|
||||
for marker in MOJIBAKE_PATTERNS:
|
||||
if marker in text:
|
||||
errors.append(f"report contains invalid encoding marker: {marker!r}")
|
||||
if re.search(r"\?{4,}", text):
|
||||
errors.append("report contains repeated question marks indicating encoding loss")
|
||||
if len(re.findall(r"[\u3400-\u9fff]", text)) < 40:
|
||||
errors.append("report does not contain enough readable Chinese narrative")
|
||||
|
||||
sections = parse_pr_sections(text.splitlines())
|
||||
targets = required_prs or sorted(sections)
|
||||
if not targets:
|
||||
return errors + ["report contains no '## PR #<number>' section"]
|
||||
for number in targets:
|
||||
if number not in sections:
|
||||
errors.append(f"missing PR section: #{number}")
|
||||
continue
|
||||
cards = []
|
||||
for line in sections[number]:
|
||||
match = CARD_PATTERN.match(line.strip())
|
||||
if not match:
|
||||
continue
|
||||
aspect, conclusion, status, rationale = match.groups()
|
||||
cards.append((aspect, conclusion, status, rationale))
|
||||
if len(rationale) < 20:
|
||||
errors.append(f"PR #{number} aspect '{aspect}' explanation is too short")
|
||||
if "依据：" not in rationale:
|
||||
errors.append(f"PR #{number} aspect '{aspect}' is missing explicit evidence")
|
||||
if any(token.startswith("<") and token.endswith(">") for token in (conclusion, status)):
|
||||
errors.append(f"PR #{number} aspect '{aspect}' contains a placeholder")
|
||||
if len(cards) < min_cards:
|
||||
errors.append(f"PR #{number} has {len(cards)} valid aspect card(s), need at least {min_cards}")
|
||||
aspects = [card[0] for card in cards]
|
||||
if len(set(aspects)) != len(aspects):
|
||||
errors.append(f"PR #{number} contains duplicate aspect cards")
|
||||
for aspect in required_aspects or []:
|
||||
if aspect not in aspects:
|
||||
errors.append(f"PR #{number} is missing required aspect card: {aspect}")
|
||||
return errors
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description="Validate per-PR aspect cards.")
|
||||
parser.add_argument("--report", required=True, type=Path)
|
||||
parser.add_argument("--require-pr", action="append", type=int, default=[])
|
||||
parser.add_argument("--min-cards", type=int, default=2)
|
||||
parser.add_argument("--required-aspect", action="append", default=[])
|
||||
args = parser.parse_args()
|
||||
try:
|
||||
text = args.report.read_text(encoding="utf-8", errors="strict")
|
||||
except (OSError, UnicodeError) as exc:
|
||||
print(f"PR card validation failed: {exc}", file=sys.stderr)
|
||||
return 2
|
||||
errors = validate_report(text, args.require_pr, args.min_cards, args.required_aspect)
|
||||
if errors:
|
||||
print("PR card validation failed:", file=sys.stderr)
|
||||
for error in errors:
|
||||
print(f"- {error}", file=sys.stderr)
|
||||
return 1
|
||||
print("PR card validation passed")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Loading…
Reference in New Issue