feat(skills): 新增 gitlink-pr-integrator Skill
This commit is contained in:
parent
71ca2bb683
commit
5aa81e15fb
|
|
@ -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 <owner> --repo <repo> --id <pr_number> --format json
|
||||
gitlink-cli pr +files --owner <owner> --repo <repo> --id <pr_number> --format json
|
||||
gitlink-cli pr +reviews --owner <owner> --repo <repo> --id <pr_number> --format json
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
gitlink-cli ci +builds --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
至少提取：
|
||||
|
||||
- base 分支、head 分支、head 来源仓库
|
||||
- 变更文件、核心目录、是否涉及 CLI 命令入口、帮助文本、文档、测试
|
||||
- 当前 review 结论、是否已有 maintainer 明确阻塞项
|
||||
- 仓库默认分支、语言、CI 是否开启、项目推荐的验证命令
|
||||
|
||||
### Step 2: 准备独立的集成验证环境
|
||||
|
||||
集成验证必须隔离执行。优先顺序如下：
|
||||
|
||||
1. 用户明确提供的临时检出目录
|
||||
2. 当前仓库下的新 worktree
|
||||
3. 系统临时目录里的新 clone
|
||||
|
||||
禁止直接在用户当前脏工作树里 `merge` 或 `rebase`。如果仓库里已经有未提交改动，只把它当信息源，不把它当验证环境。
|
||||
|
||||
### Step 3: 做合并态验证
|
||||
|
||||
目标不是只看 PR 自己能不能编译，而是回答“把它并到最新主线后还能不能工作”。
|
||||
|
||||
建议流程：
|
||||
|
||||
```bash
|
||||
git fetch origin <base_branch>
|
||||
git worktree add <temp_dir> origin/<base_branch>
|
||||
cd <temp_dir>
|
||||
git switch -c pr-integration-check
|
||||
git remote add pr-source <head_repo_url>
|
||||
git fetch pr-source <head_branch>
|
||||
git merge --no-ff --no-commit FETCH_HEAD
|
||||
```
|
||||
|
||||
如果 PR head 就在同一个远端，也可以直接从 `origin/<head_branch>` 拉取，不必额外加 remote。
|
||||
注意 GitLink PR 的 `head` 字段常见格式是 `login/branch`。对 fork PR 做本地验证时，不要机械地把它裁成最后一段；如果你的 remote 名就叫这个 login，那么实际 remote-tracking ref 可能是 `refs/remotes/<login>/<head>`，例如 `refs/remotes/mengz/mengz/api-single-call-templates`。
|
||||
|
||||
记录下列结果：
|
||||
|
||||
- 是否无冲突完成 merge
|
||||
- 是否必须 rebase 才能继续
|
||||
- 官方构建命令是否通过
|
||||
- 官方测试命令是否通过
|
||||
- 是否出现只在合并态暴露的问题，例如接口签名漂移、帮助文本未同步、测试夹具过时、文档示例失效
|
||||
|
||||
验证命令必须优先使用项目文档、CI 配置、`Makefile` 或仓库惯例，不要发明一套项目从未使用过的检查方式。
|
||||
|
||||
### Step 4: 扫描与其他 open PR 的冲突风险
|
||||
|
||||
集成就绪度不是单 PR 视角，还要考虑队列里的其他候选项。
|
||||
|
||||
先列出 open PR：
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +list --owner <owner> --repo <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
|
||||
<!-- gitlink-pr-integrator:report v1 -->
|
||||
## PR #<id> 集成就绪报告
|
||||
|
||||
**结论：** ready_after_followups
|
||||
**merge_readiness：** medium
|
||||
**integration_risk：** medium
|
||||
**conflict_risk：** high
|
||||
**release_impact：** minor
|
||||
|
||||
### 1. 合并态验证
|
||||
- 基线：`<base_branch>`
|
||||
- 结果：可合并 / 需 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，给出建议合并顺序、冲突风险和发布影响。”
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
interface:
|
||||
display_name: "PR 集成检查"
|
||||
short_description: "评估 PR 是否能安全并入主线，分析冲突、发布影响和合并后动作。"
|
||||
default_prompt: "Use $gitlink-pr-integrator 评估这个 GitLink PR 的集成就绪度，执行合并态验证、冲突风险分析、发布影响判断和合并后动作梳理，不要回写远端。"
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 147 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 167 KiB |
|
|
@ -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 是否已经具备合并条件，执行合并态验证、冲突风险分析、发布影响判断和合并后动作清单整理，不要回写远端。
|
||||
```
|
||||
|
||||
## 技能目录截图
|
||||
|
||||
|
||||
|
||||
## 输出结果全文
|
||||
|
||||
```markdown
|
||||
<!-- gitlink-pr-integrator:report v1 -->
|
||||
## 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。
|
||||
```
|
||||
|
||||
## 输出截图
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 结构校验
|
||||
|
||||
```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!
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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 <owner> --repo <repo> --id <pr_number> --format json
|
||||
gitlink-cli pr +files --owner <owner> --repo <repo> --id <pr_number> --format json
|
||||
gitlink-cli pr +diff --owner <owner> --repo <repo> --id <pr_number> --format json
|
||||
gitlink-cli pr +reviews --owner <owner> --repo <repo> --id <pr_number> --format json
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
gitlink-cli ci +builds --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
关注字段：
|
||||
|
||||
- `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 <owner> --repo <repo> --state open --page 1 --limit 50 --format json
|
||||
```
|
||||
|
||||
批量扫描时优先抓取：
|
||||
|
||||
- PR 号
|
||||
- 标题
|
||||
- 作者
|
||||
- 更新时间
|
||||
- base / head
|
||||
- 状态
|
||||
|
||||
再对高风险或高优先级项补拉 `+view`、`+files`、`+reviews`。
|
||||
|
||||
## 4. 远端回写命令
|
||||
|
||||
只有用户明确要求时才使用：
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +comment --owner <owner> --repo <repo> --id <pr_number> --body "<markdown>"
|
||||
gitlink-cli pr +review --owner <owner> --repo <repo> --id <pr_number> --status common --content "<markdown>" --dry-run
|
||||
gitlink-cli pr +review --owner <owner> --repo <repo> --id <pr_number> --status common --content "<markdown>"
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- 默认先 `--dry-run`
|
||||
- 默认用 `common`
|
||||
- 不默认 `approved`
|
||||
- 不默认触发 `merge`
|
||||
|
||||
## 5. 独立 worktree 验证
|
||||
|
||||
推荐在仓库根目录执行：
|
||||
|
||||
```bash
|
||||
git fetch origin <base_branch>
|
||||
git worktree add <temp_dir> origin/<base_branch>
|
||||
cd <temp_dir>
|
||||
git switch -c pr-integration-check
|
||||
```
|
||||
|
||||
如果 PR head 来自 fork：
|
||||
|
||||
```bash
|
||||
git remote add pr-source <head_repo_url>
|
||||
git fetch pr-source <head_branch>
|
||||
git merge --no-ff --no-commit FETCH_HEAD
|
||||
```
|
||||
|
||||
如果 PR head 来自同仓库：
|
||||
|
||||
```bash
|
||||
git fetch origin <head_branch>
|
||||
git merge --no-ff --no-commit origin/<head_branch>
|
||||
```
|
||||
|
||||
注意 GitLink PR 的 `head` 常常已经是 `login/branch` 形式。对 fork PR，不要默认只取最后一段 branch 名。若 remote 名恰好也是这个 login，实际可用 ref 可能是 `refs/remotes/<remote>/<head>`，例如：
|
||||
|
||||
```bash
|
||||
refs/remotes/mengz/mengz/api-single-call-templates
|
||||
```
|
||||
|
||||
如果本地已经存在同名本地分支，也可以直接 merge 那个本地分支，但报告里要写清楚你实际使用的是哪个 ref。
|
||||
|
||||
记录四类结果：
|
||||
|
||||
1. 是否发生冲突
|
||||
2. 是否需要 rebase
|
||||
3. 官方构建是否通过
|
||||
4. 官方测试是否通过
|
||||
|
||||
验证结束后，如果这个 worktree 只是一次性检查环境，及时清理：
|
||||
|
||||
```bash
|
||||
git worktree remove <temp_dir>
|
||||
```
|
||||
|
||||
不要在用户当前工作树清理或覆盖任何未提交改动。
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
如果输出里已经出现 `?`，先停下来修正编码链路，不要带着乱码继续演示或提交。
|
||||
Loading…
Reference in New Issue