diff --git a/skills/gitlink-pr-integrator/SKILL.md b/skills/gitlink-pr-integrator/SKILL.md new file mode 100644 index 0000000..7e48efe --- /dev/null +++ b/skills/gitlink-pr-integrator/SKILL.md @@ -0,0 +1,254 @@ +--- +name: gitlink-pr-integrator +description: 评估 GitLink Pull Request 是否已经具备集成到主线的条件，输出合并态验证、与其他 open PR 的冲突风险、集成影响面、发布与回移建议以及合并后动作清单。用于维护者需要决定某个 PR 是否可以进入 merge queue、为一批待合并 PR 排顺序、在合并前验证 rebase 或 merge 后是否仍能构建测试通过，或为自动化队列生成集成就绪报告时。 +--- + +# gitlink-pr-integrator + +**CRITICAL - 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。** +**CRITICAL - GitLink 平台数据采集和回写只使用 `gitlink-cli`，不要改用 `gh` 或其他平台 CLI。** +**CRITICAL - 默认只做读取、验证和报告；只有用户明确要求时才回写评论或 review。** +**CRITICAL - 不要在用户当前的脏工作树里做合并验证。优先使用独立 worktree、临时 clone 或明确指定的检出目录。** +**CRITICAL - 在 Windows PowerShell 中保存中文报告前，先切到 UTF-8 输出链路，否则中文可能被写成 `?`。** + +这个 Skill 解决的是“这个 PR 现在能不能安全并入主线”，不是“这个 PR 有没有价值”。如果需求是判断贡献价值、功能可行性、代码质量或声明是否成立，先使用 `gitlink-pr-assessor`；如果价值判断已经成立，需要决定是否进入合并队列、是否先 rebase、是否会与别的 open PR 打架，再使用这个 Skill。 + +执行命令前，按需读取 [`references/api_reference.md`](./references/api_reference.md)。其中包含 GitLink CLI 命令、Windows 调用方式、独立 worktree 验证方法和报告字段约定。 + +## Windows 前置 + +如果你在 Windows PowerShell 里运行或落盘报告，先执行： + +```powershell +chcp 65001 > $null +[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false) +[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) +$OutputEncoding = [Console]::OutputEncoding +``` + +如果 PowerShell 因执行策略拦截 `gitlink-cli.ps1`，改用： + +```powershell +& "$env:APPDATA\npm\gitlink-cli.cmd" auth status +``` + +如果全局安装版本落后于当前仓库源码，优先在仓库根目录运行： + +```powershell +go run . pr --help +``` + +## 结论集合 + +最终结论只从下列集合中选择一个： + +- `ready_to_merge`：合并态干净，官方构建/测试通过，冲突和发布风险可接受。 +- `ready_after_rebase`：主要阻塞是基线已漂移，rebase 或重新合并后大概率可继续。 +- `ready_after_followups`：代码本身接近可合并，但还缺文档、帮助文本、测试、changelog 或发布动作。 +- `not_integration_ready`：当前无法安全并入主线，存在冲突、失败验证、较高回归风险或明显的集成阻塞。 + +同时给出以下评级： + +- `merge_readiness`: `high` / `medium` / `low` +- `integration_risk`: `low` / `medium` / `high` +- `conflict_risk`: `low` / `medium` / `high` +- `release_impact`: `none` / `patch` / `minor` / `major` + +## 标准流程 + +### Step 1: 采集 PR 集成上下文 + +先拿到目标 PR 的元信息、变更范围、已有 review 和仓库默认分支信息。 + +优先命令： + +```bash +gitlink-cli pr +view --owner --repo --id --format json +gitlink-cli pr +files --owner --repo --id --format json +gitlink-cli pr +reviews --owner --repo --id --format json +gitlink-cli repo +info --owner --repo --format json +gitlink-cli ci +builds --owner --repo --format json +``` + +至少提取： + +- base 分支、head 分支、head 来源仓库 +- 变更文件、核心目录、是否涉及 CLI 命令入口、帮助文本、文档、测试 +- 当前 review 结论、是否已有 maintainer 明确阻塞项 +- 仓库默认分支、语言、CI 是否开启、项目推荐的验证命令 + +### Step 2: 准备独立的集成验证环境 + +集成验证必须隔离执行。优先顺序如下： + +1. 用户明确提供的临时检出目录 +2. 当前仓库下的新 worktree +3. 系统临时目录里的新 clone + +禁止直接在用户当前脏工作树里 `merge` 或 `rebase`。如果仓库里已经有未提交改动，只把它当信息源，不把它当验证环境。 + +### Step 3: 做合并态验证 + +目标不是只看 PR 自己能不能编译，而是回答“把它并到最新主线后还能不能工作”。 + +建议流程： + +```bash +git fetch origin +git worktree add origin/ +cd +git switch -c pr-integration-check +git remote add pr-source +git fetch pr-source +git merge --no-ff --no-commit FETCH_HEAD +``` + +如果 PR head 就在同一个远端，也可以直接从 `origin/` 拉取，不必额外加 remote。 +注意 GitLink PR 的 `head` 字段常见格式是 `login/branch`。对 fork PR 做本地验证时，不要机械地把它裁成最后一段；如果你的 remote 名就叫这个 login，那么实际 remote-tracking ref 可能是 `refs/remotes//`，例如 `refs/remotes/mengz/mengz/api-single-call-templates`。 + +记录下列结果： + +- 是否无冲突完成 merge +- 是否必须 rebase 才能继续 +- 官方构建命令是否通过 +- 官方测试命令是否通过 +- 是否出现只在合并态暴露的问题，例如接口签名漂移、帮助文本未同步、测试夹具过时、文档示例失效 + +验证命令必须优先使用项目文档、CI 配置、`Makefile` 或仓库惯例，不要发明一套项目从未使用过的检查方式。 + +### Step 4: 扫描与其他 open PR 的冲突风险 + +集成就绪度不是单 PR 视角，还要考虑队列里的其他候选项。 + +先列出 open PR： + +```bash +gitlink-cli pr +list --owner --repo --state open --page 1 --limit 50 --format json +``` + +然后重点比较： + +- 是否修改同一文件 +- 是否落在同一目录或模块 +- 是否同时修改同一条 CLI 命令、flag、帮助文案或 API 包装层 +- 是否会产生相互覆盖的测试或快照 + +冲突评级建议： + +- `high`：同文件或同命令入口直接重叠，合并顺序明显重要 +- `medium`：目录或模块重叠，存在行为级联风险 +- `low`：基本独立，只存在轻微上下文漂移可能 + +如果发现明显的先后依赖，给出建议合并顺序。 + +### Step 5: 输出集成影响矩阵 + +不要只写“测试通过”。要明确主线在什么面上会被改变。 + +至少覆盖以下面向： + +- CLI 命令行为 +- flags / help 输出 +- README / docs / 示例 +- API 封装或协议兼容性 +- 测试与夹具 +- release notes / changelog + +如果代码改了，但帮助文本、README、示例或测试没有同步，直接记为集成跟进项，而不是轻描淡写地放过。 + +### Step 6: 给出发布与回移建议 + +把改动归入以下类型之一： + +- bugfix +- feature +- breaking change +- refactor-only + +并说明： + +- 对版本号的影响更像 `patch` / `minor` / `major` +- 是否需要 release notes +- 是否需要迁移说明或兼容性提示 +- 是否适合回移到维护分支 + +### Step 7: 形成合并后动作清单 + +如果 PR 代码已经接近可合并，但还差最后几步，明确写成动作清单： + +- 补 help / README / 示例 +- 补或修正测试 +- 更新 changelog / release notes +- 调整 milestone / 看板状态 +- 合并后立即跟进的 issue 或回归验证 + +### Step 8: 可选回写 + +只有用户明确要求时，才把结论回写到远端。回写前先生成本地 Markdown 报告，并优先 `dry-run`。 + +适合的回写方式： + +- `pr +comment`：发布集成报告 +- `pr +review --status common --dry-run`：预览 review 文案 + +不要默认 approve 或 merge。这个 Skill 的职责是“给出可集成判断”，不是替维护者自动盖章。 + +## 报告模板 + +```markdown + +## PR # 集成就绪报告 + +**结论：** ready_after_followups +**merge_readiness：** medium +**integration_risk：** medium +**conflict_risk：** high +**release_impact：** minor + +### 1. 合并态验证 +- 基线：`` +- 结果：可合并 / 需 rebase / 存在冲突 +- 构建：通过 / 失败 / 未执行 +- 测试：通过 / 失败 / 未执行 +- 备注：<只在合并态暴露的问题> + +### 2. 与 open PR 的冲突分析 +| PR | 风险 | 原因 | 建议顺序 | +|----|------|------|----------| +| #123 | high | 同时修改 `shortcuts/pr/pr.go` | 先合并对方 | + +### 3. 集成影响矩阵 +| 面向 | 状态 | 说明 | +|------|------|------| +| CLI 行为 | changed | 新增 `...` | +| Help / docs | follow-up needed | 命令帮助已更新，README 未同步 | +| Tests | changed | 新增单测，但缺少回归场景 | + +### 4. 发布建议 +- 类型：feature +- 版本影响：minor +- 是否需要 release notes：是 +- 是否建议回移：否 + +### 5. 合并后动作 +1. <动作 1> +2. <动作 2> +3. <动作 3> +``` + +## 批量模式 + +如果用户要求扫描 PR 队列，按下面的顺序执行： + +1. 列出 open PR。 +2. 过滤掉已经 merged、closed 或已经明确被维护者拒绝的项。 +3. 按最近活动时间、冲突密度和合并态风险排序。 +4. 对前 N 条候选 PR 逐条生成集成就绪报告。 +5. 再输出一份队列总览，包含建议合并顺序和需要先处理的冲突热点文件。 + +批量模式下，仍然不要默认对全部 PR 执行高成本本地构建。先做元信息和冲突雷达，只有用户指定或风险较高时再进入本地合并验证。 + +## 示例请求 + +- “使用 `gitlink-pr-integrator` 检查 `Gitlink/gitlink-cli` 的 PR #281 是否已经具备合并条件，不要回写远端。” +- “使用 `gitlink-pr-integrator` 扫描 `Gitlink/gitlink-cli` 最近 10 个 open PR，给出建议合并顺序、冲突风险和发布影响。” diff --git a/skills/gitlink-pr-integrator/agents/openai.yaml b/skills/gitlink-pr-integrator/agents/openai.yaml new file mode 100644 index 0000000..9ebcb7a --- /dev/null +++ b/skills/gitlink-pr-integrator/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "PR 集成检查" + short_description: "评估 PR 是否能安全并入主线，分析冲突、发布影响和合并后动作。" + default_prompt: "Use $gitlink-pr-integrator 评估这个 GitLink PR 的集成就绪度，执行合并态验证、冲突风险分析、发布影响判断和合并后动作梳理，不要回写远端。" diff --git a/skills/gitlink-pr-integrator/assets/codex-skill-directory.png b/skills/gitlink-pr-integrator/assets/codex-skill-directory.png new file mode 100644 index 0000000..17f97e0 Binary files /dev/null and b/skills/gitlink-pr-integrator/assets/codex-skill-directory.png differ diff --git a/skills/gitlink-pr-integrator/assets/codex-validation-output-1.png b/skills/gitlink-pr-integrator/assets/codex-validation-output-1.png new file mode 100644 index 0000000..98de5e1 Binary files /dev/null and b/skills/gitlink-pr-integrator/assets/codex-validation-output-1.png differ diff --git a/skills/gitlink-pr-integrator/assets/codex-validation-output-2.png b/skills/gitlink-pr-integrator/assets/codex-validation-output-2.png new file mode 100644 index 0000000..6d16c2d Binary files /dev/null and b/skills/gitlink-pr-integrator/assets/codex-validation-output-2.png differ diff --git a/skills/gitlink-pr-integrator/examples/codex-validation-2026-06-25.md b/skills/gitlink-pr-integrator/examples/codex-validation-2026-06-25.md new file mode 100644 index 0000000..5795a40 --- /dev/null +++ b/skills/gitlink-pr-integrator/examples/codex-validation-2026-06-25.md @@ -0,0 +1,113 @@ +# Codex 验证记录（2026-06-25） + +本记录用于提交 `gitlink-pr-integrator` 的 Agent 平台验证材料，包含技能目录截图、实际使用截图和完整输出转录。 + +## 验证平台 + +- 平台：Codex +- 仓库：`Gitlink/gitlink-cli` +- 目标 PR：`#281` +- 执行范围：校验合并态、集成风险、与其他 open PR 的冲突关系、发布影响和合并前动作 +- 执行约束：只读分析，不回写 review、评论、状态或合并操作 + +## 触发提示词 + +```text +使用 gitlink-pr-integrator 检查 Gitlink/gitlink-cli 的 PR #281 是否已经具备合并条件，执行合并态验证、冲突风险分析、发布影响判断和合并后动作清单整理，不要回写远端。 +``` + +## 技能目录截图 + +![Codex 技能目录截图](../assets/codex-skill-directory.png) + +## 输出结果全文 + +```markdown + +## PR #281 集成就绪报告 + +结论：`not_integration_ready` +merge_readiness：`medium` +integration_risk：`medium` +conflict_risk：`high` +release_impact：`patch` + +只读检查已完成，没有向 GitLink 远端回写评论、review、状态或合并操作；临时合并验证 worktree 已清理，当前工作树未被修改。 + +### 1. 合并态验证 + +- PR：`fix(api): 补齐单次请求模板变量与请求头支持` +- Base：`origin/master` at `71ca2bb` +- Head：`Mengz/gitlink-cli: mengz/api-single-call-templates` at `ac211ac4` +- 平台状态：`mergeable=true` +- 本地合并：`git merge --no-ff --no-commit FETCH_HEAD` 无冲突 +- CI：仓库 `open_devops=false`，`ci +builds` 返回 `[-1]` 接口数据异常，不能作为放行依据 +- 验证通过过： + - `go test ./cmd/api ./internal/client` + - `go test ./...` + - `go build ./...` + - `git diff --check` +- 验证未达预期： + - `go run . api GET /:owner/:repo/issues --owner Gitlink --repo gitlink-cli --query 'limit=1' --format json` + - CLI 退出码为 0，但响应为 `ok:false`，错误码 `404`，信息为“您访问的页面不存在或已被删除”。这是 PR 描述中的冒烟命令，合并前需要澄清 endpoint 示例错误还是 Raw API 行为问题。 + +### 2. 主要集成阻塞 + +| 项 | 风险 | 说明 | +|----|------|------| +| Raw API 冒烟命令返回 404 | high | PR 声明的端到端验证未得到成功响应，不能直接作为已验证能力合并 | +| `README.zh-CN.md` 新增段落乱码 | high | PR 头部文件中中文示例是 mojibake，会把主线中文文档污染 | +| 自定义 `Accept` 头无法真正覆盖 | medium | `internal/auth/transport.go` 会条件 `Set("Accept", "application/json")`，与“自定义请求头支持”的用户预期不完全一致 | +| `:owner` / `:repo` 全局替换边界不足 | medium | 当前 `strings.NewReplacer` 可能误伤类似 `:repository` 的路径片段，建议补边界测试或改为路径级替换 | +| header 名模板渲染后未二次校验 | medium | 解析时校验的是渲染前 header，渲染后若生成非法 header name，风险会延后到请求阶段 | + +### 3. 与 open PR 的冲突分析 + +| PR | 风险 | 原因 | 建议顺序 | +|----|------|------|----------| +| #254 | high | 同样修改 `cmd/api/api.go`、`cmd/api/api_test.go`，也是 Raw API 单次调用 `:owner/:repo` 和 `--var` 占位符能力 | 先决定 #254 与 #281 谁是主实现；另一个 rebase、收敛或关闭 | +| #259 | high | 广泛修改 156 个文件，重叠 `README.md`、`README.zh-CN.md`、`cmd/api/api.go`、`internal/client/client.go` | 不建议并行进入 merge queue | +| #276 | high | 重叠 `internal/client/client.go`，且变更面很大 | #281 合并后需 rebase #276，或反过来重新验证 #281 | +| #275 | high | 重叠 `README.md`、`README.zh-CN.md`、`internal/client/client.go` | 合并顺序会影响文档和 client 层 | +| #282 / #274 / #273 / #272 等 | medium | 大量 README 双文件重叠 | 文档冲突多，建议集中整理 README 后再批量合并 | + +### 4. 集成影响矩阵 + +| 面向 | 状态 | 说明 | +|------|------|------| +| CLI 行为 | changed | 单次 `api` 请求支持 `/:owner/:repo`、`{{var}}` 在 `path/query/body/header` 中渲染 | +| Flags / help | changed | 既有 `--header` 被打通，并加入示例 | +| API client | changed | 新增 `DoWithHeaders`，`Do` 改为委托调用 | +| Docs | follow-up needed | 英文 README 可读，中文 README 新增内容乱码，必须修复 | +| Tests | changed | 新增路径、模板、header 相关单测；建议补 `:repository`、`Accept` 覆盖、渲染后非法 header 场景 | +| Release notes | needed | `doc/changes/api-single-request-templates.md` 已新增，但合并前需确认语义和示例可运行 | + +### 5. 发布建议 + +- 类型：`bugfix + 小型 CLI 能力补齐` +- 版本影响：建议按 `patch` 处理；若维护者把单次请求 `header/template` 视为新公开能力，也可以归入 `minor` +- 需要 release notes：是 +- 回移建议：如果存在维护分支且 Issue #20 属于已发布版本缺陷，适合回移；但必须先修复中文文档和冒烟验证问题 + +### 6. 合并前动作清单 + +1. 修复 `README.zh-CN.md` 新增段落编码乱码。 +2. 重新验证 PR 描述中的 Raw API 冒烟命令；若 endpoint 示例不成立，替换为确实返回 `ok:true` 的只读示例。 +3. 明确 #254 与 #281 的取舍和合并顺序，避免两套 Raw API 占位符实现互相覆盖。 +4. 明确 `--header 'Accept: ...'` 是否允许覆盖默认 `Accept`；若允许，需要调整 transport 或文档说明限制。 +5. 补充边界测试：`:repository` 不应被 `:repo` 误替换；渲染后的 header name 仍需合法。 +6. 完成后重跑本次验证命令，并在合并后关闭或关联 Issue #20。 +``` + +## 输出截图 + +![Codex 输出截图 1](../assets/codex-validation-output-1.png) + +![Codex 输出截图 2](../assets/codex-validation-output-2.png) + +## 结构校验 + +```powershell +python -X utf8 "C:\Users\Z Y\.codex\skills\.system\skill-creator\scripts\quick_validate.py" "D:\temp\gitlink-cli-skills-submit\skills\gitlink-pr-integrator" +Skill is valid! +``` diff --git a/skills/gitlink-pr-integrator/examples/gitlink-pr-integrator-demo.md b/skills/gitlink-pr-integrator/examples/gitlink-pr-integrator-demo.md new file mode 100644 index 0000000..dea8e34 --- /dev/null +++ b/skills/gitlink-pr-integrator/examples/gitlink-pr-integrator-demo.md @@ -0,0 +1,41 @@ +# gitlink-pr-integrator 使用示例 + +## 场景 1：单条 PR 集成检查 + +用户请求： + +```text +使用 gitlink-pr-integrator 检查 Gitlink/gitlink-cli 的 PR #281 是否已经具备合并条件，执行合并态验证、冲突风险分析、发布影响判断和合并后动作清单整理，不要回写远端。 +``` + +期望输出重点： + +- 明确的结论：`ready_to_merge` / `ready_after_rebase` / `ready_after_followups` / `not_integration_ready` +- 是否能在最新 base 上 clean merge +- 官方构建和测试是否通过 +- 与其他 open PR 的冲突风险 +- 是否需要补文档、help、changelog 或 release notes + +## 场景 2：批量扫描合并队列 + +用户请求： + +```text +使用 gitlink-pr-integrator 扫描 Gitlink/gitlink-cli 最近 10 个 open PR，给出建议合并顺序、冲突热点、发布影响和需要优先处理的阻塞项，不要回写远端。 +``` + +期望输出重点： + +- 候选 PR 列表 +- 每条 PR 的集成结论和冲突等级 +- 推荐合并顺序 +- 重叠最严重的文件或模块 +- 只对高风险项进入本地合并验证 + +## 演示建议 + +在 Codex 中优先使用仓库源码构建的 CLI，而不是依赖全局安装版本。Windows 下如果 PowerShell 拦截 `gitlink-cli`，就改用 `gitlink-cli.cmd`，或直接在仓库根目录用： + +```powershell +go run . pr --help +``` diff --git a/skills/gitlink-pr-integrator/references/api_reference.md b/skills/gitlink-pr-integrator/references/api_reference.md new file mode 100644 index 0000000..1bb8880 --- /dev/null +++ b/skills/gitlink-pr-integrator/references/api_reference.md @@ -0,0 +1,204 @@ +# gitlink-pr-integrator 参考命令 + +## 1. 命令入口选择 + +优先级如下： + +1. 当前仓库源码构建出的 CLI +2. `go run .` +3. 全局安装的 `gitlink-cli.cmd` + +在 Windows PowerShell 中，如果 `gitlink-cli` 被执行策略拦截，改用： + +```powershell +& "$env:APPDATA\npm\gitlink-cli.cmd" auth status +``` + +如果需要确保使用的是当前仓库源码能力，直接在仓库根目录执行： + +```powershell +go run . pr --help +go run . pr +list --owner Gitlink --repo gitlink-cli --state open --format json +``` + +## 2. 采集 PR 元信息 + +```bash +gitlink-cli pr +view --owner --repo --id --format json +gitlink-cli pr +files --owner --repo --id --format json +gitlink-cli pr +diff --owner --repo --id --format json +gitlink-cli pr +reviews --owner --repo --id --format json +gitlink-cli repo +info --owner --repo --format json +gitlink-cli ci +builds --owner --repo --format json +``` + +关注字段： + +- `pull_request.base` / `pull_request.head` +- `pull_request_status` +- `pull_request_number` +- `issue.id` +- 变更文件路径、增删行、diff 片段 +- review 状态：`common` / `approved` / `rejected` +- `default_branch` +- `open_devops` + +## 3. 列出候选 open PR + +```bash +gitlink-cli pr +list --owner --repo --state open --page 1 --limit 50 --format json +``` + +批量扫描时优先抓取： + +- PR 号 +- 标题 +- 作者 +- 更新时间 +- base / head +- 状态 + +再对高风险或高优先级项补拉 `+view`、`+files`、`+reviews`。 + +## 4. 远端回写命令 + +只有用户明确要求时才使用： + +```bash +gitlink-cli pr +comment --owner --repo --id --body "" +gitlink-cli pr +review --owner --repo --id --status common --content "" --dry-run +gitlink-cli pr +review --owner --repo --id --status common --content "" +``` + +规则： + +- 默认先 `--dry-run` +- 默认用 `common` +- 不默认 `approved` +- 不默认触发 `merge` + +## 5. 独立 worktree 验证 + +推荐在仓库根目录执行： + +```bash +git fetch origin +git worktree add origin/ +cd +git switch -c pr-integration-check +``` + +如果 PR head 来自 fork： + +```bash +git remote add pr-source +git fetch pr-source +git merge --no-ff --no-commit FETCH_HEAD +``` + +如果 PR head 来自同仓库： + +```bash +git fetch origin +git merge --no-ff --no-commit origin/ +``` + +注意 GitLink PR 的 `head` 常常已经是 `login/branch` 形式。对 fork PR，不要默认只取最后一段 branch 名。若 remote 名恰好也是这个 login，实际可用 ref 可能是 `refs/remotes//`，例如： + +```bash +refs/remotes/mengz/mengz/api-single-call-templates +``` + +如果本地已经存在同名本地分支，也可以直接 merge 那个本地分支，但报告里要写清楚你实际使用的是哪个 ref。 + +记录四类结果： + +1. 是否发生冲突 +2. 是否需要 rebase +3. 官方构建是否通过 +4. 官方测试是否通过 + +验证结束后，如果这个 worktree 只是一次性检查环境，及时清理： + +```bash +git worktree remove +``` + +不要在用户当前工作树清理或覆盖任何未提交改动。 + +## 6. 官方验证命令选择顺序 + +按以下顺序选命令： + +1. PR 描述里作者写的验证步骤 +2. 仓库 `README` / `CONTRIBUTING` +3. CI 配置或 `Makefile` +4. 语言惯例 + +常见命令： + +```bash +go build ./... +go test ./... +npm test +pnpm test +pytest +cargo test +``` + +如果仓库没有明确写测试命令，不要假装“全部通过”；应标注“未找到项目定义的官方验证命令”。 + +## 7. 冲突雷达的最小比对法 + +没有必要把每个 open PR 都完整 clone 一遍。先用文件级和目录级比对做第一轮筛查： + +- 同文件重叠：高风险 +- 同目录或同模块重叠：中风险 +- 同一 CLI 命令、flag、帮助文本或 API 包装层：至少中风险 +- 文档或测试只轻微重叠：低到中风险，按实际耦合上调 + +只有当前两条 PR 都处于高优先级、而且重叠严重时，才进入更深的本地顺序合并验证。 + +## 8. 报告字段约定 + +推荐结构化字段： + +```json +{ + "verdict": "ready_after_followups", + "merge_readiness": "medium", + "integration_risk": "medium", + "conflict_risk": "high", + "release_impact": "minor", + "merge_validation": { + "base_branch": "master", + "merge_result": "clean", + "build": "passed", + "tests": "passed" + }, + "conflicts": [ + { + "pr": 123, + "risk": "high", + "reason": "same file overlap: shortcuts/pr/pr.go", + "suggested_order": "merge #123 first" + } + ], + "post_merge_actions": [ + "update README example", + "add regression test for fork PR head parsing" + ] +} +``` + +Markdown 报告和 JSON 结论保持一致，不要出现“结构化字段说可合并，正文却写暂缓”的相互矛盾。 + +## 9. 中文报告落盘 + +Windows PowerShell 中保存中文报告时显式指定 UTF-8： + +```powershell +$report | Set-Content -Path .\pr-integration-report.md -Encoding utf8 +``` + +如果输出里已经出现 `?`，先停下来修正编码链路，不要带着乱码继续演示或提交。