diff --git a/skills/README.md b/skills/README.md index d507074..e98b084 100644 --- a/skills/README.md +++ b/skills/README.md @@ -148,6 +148,14 @@ skills/ | **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、Release Notes | | **gitlink-health** | 开源项目健康度 | 详情见SKILL.md | +### 分析与治理 Skills + +| Skill | 说明 | 常用命令 | +|-------|------|----------| +| **gitlink-code-review** | 结构化审查 Pull Request，输出可直接给维护者使用的 Review 报告 | `pr +view`, `pr +files`, `pr +diff`, `pr +reviews` | +| **gitlink-contributor-insight** | 分析贡献者活跃度、贡献分布和社区协作风险，生成团队洞察报告 | `repo +info`, `pr +list`, `issue +list`, `user +info` | +| **gitlink-pr-integrator** | 评估 PR 是否具备合并条件，识别冲突风险、发布影响和后续动作 | `pr +view`, `pr +files`, `pr +reviews`, `ci +builds` | + --- ## 🎯 使用场景 diff --git a/skills/gitlink-code-review/SKILL.md b/skills/gitlink-code-review/SKILL.md index 3294536..4326ec7 100644 --- a/skills/gitlink-code-review/SKILL.md +++ b/skills/gitlink-code-review/SKILL.md @@ -1,6 +1,5 @@ --- name: gitlink-code-review -version: 1.0.0 description: "智能代码审查：获取 PR 变更、分析代码质量、自动生成 Review 评论与摘要报告。当用户需要审查 Pull Request、检查代码质量或生成审查报告时触发。" metadata: requires: diff --git a/skills/gitlink-code-review/assets/codex-skill-directory.png b/skills/gitlink-code-review/assets/codex-skill-directory.png new file mode 100644 index 0000000..17f97e0 Binary files /dev/null and b/skills/gitlink-code-review/assets/codex-skill-directory.png differ diff --git a/skills/gitlink-code-review/assets/codex-validation-output.png b/skills/gitlink-code-review/assets/codex-validation-output.png new file mode 100644 index 0000000..cf8b0d7 Binary files /dev/null and b/skills/gitlink-code-review/assets/codex-validation-output.png differ diff --git a/skills/gitlink-code-review/examples/codex-validation-2026-06-25.md b/skills/gitlink-code-review/examples/codex-validation-2026-06-25.md new file mode 100644 index 0000000..0f83b0f --- /dev/null +++ b/skills/gitlink-code-review/examples/codex-validation-2026-06-25.md @@ -0,0 +1,75 @@ +# Codex 验证记录（2026-06-25） + +本记录用于提交 `gitlink-code-review` 的 Agent 平台验证材料，包含技能目录截图、实际使用截图和完整输出转录。 + +## 验证平台 + +- 平台：Codex +- 仓库：`Gitlink/gitlink-cli` +- 目标 PR：`#281` +- 执行约束：只读分析，不回写评论、不提交 review、不执行合并或关闭操作 + +## 触发提示词 + +```text +使用 gitlink-code-review 对 Gitlink/gitlink-cli 的 PR #281 做一次结构化代码审查，分析主要改动、代码质量、潜在问题、风险点和值得肯定的地方，输出可直接给维护者参考的审查报告，不要回写远端。 +``` + +## 技能目录截图 + +![Codex 技能目录截图](../assets/codex-skill-directory.png) + +## 输出结果全文 + +```markdown +使用 gitlink-code-review 完成了只读审查；未提交评论、未重启/合并/关闭 PR，也未写远端。 + +## PR #281 代码审查报告 + +PR: `fix(api): 补齐单次请求模板变量与请求头支持` +状态: `open`，`mergeable=true`，1 commit，6 个文件，`+364/-12` +结论: 核心修复方向正确，测试覆盖较扎实；建议合并前先处理 2 个文档/行为一致性问题。 + +### Warning + +- `README.zh-CN.md:573`、`README.zh-CN.md:576` + 新增中文内容在 GitLink diff 中呈现为乱码，中文 README 新增段落需要按 UTF-8 重新保存并确认显示正常。英文 README 和 `doc/changes/...` 看起来正常，这个问题大概率只影响中文 README 的新增行。 + +- `internal/client/client.go:85` + 增加了自定义 header 注入，但 `internal/auth/transport.go:41` 后续仍会条件执行 `req.Header.Set("Accept", "application/json")`。这意味着用户传 `--header 'Accept: text/plain'` 会被静默覆盖，与“支持自定义请求头”的预期不完全一致。建议改成仅当 `Accept` 为空时设置默认值，或在文档里明确由 CLI 固定管理。 + +### Suggestion + +- `cmd/api/api.go:213` 的 `normalizeSingleAPIPath` 使用全局字符串替换 `:owner` / `:repo`。这能解决当前 issue #20，但对 raw API 来说路径宽泛，可能误改形如 `:repository`、`:owner_id` 之类的路径片段。建议改成路径 segment 级替换，或至少补一个 `:repository` 不被误替换的回归测试。 + +- `cmd/api/api.go:333` 渲染 `header name` 后没有重新校验。当前 `parseAPIHeaders` 只校验模板渲染前的 `name` 非空，若用户传 `--header '{{name}}: x' --var name=`，错误可能延迟到 HTTP 层。建议渲染后再次校验 `header name` 非空且合法，错误信息也会更好。 + +### 主要改动理解 + +- 单次 `gitlink-cli api` 现在会在 `path`、`query`、`JSON body`、`header` 中渲染 `{{var}}`。 +- `/:owner/:repo` 被转换为 `{{owner}}/{{repo}}`，并可从 `--var`、全局 `--owner/--repo` 或当前仓库上下文解析。 +- 新增 `DoWithHeaders`，保持原 `Do` 兼容。 +- 补充了端到端测试、渲染函数测试、非法 header 测试和文档说明。 + +### 值得肯定 + +- PR 精准覆盖 issue #20：单次 Raw API 不替换 `:owner/:repo` 的问题确实被纳入实现和测试。 +- 复用了 batch 模式已有的模板渲染逻辑，语义一致，维护成本低。 +- 测试覆盖了 `path/query/body/header` 的联动渲染，不只是单点 happy path。 +- `DoWithHeaders` 设计保留了现有 `Do` 调用方兼容性，改动面控制得不错。 + +### 维护者建议 + +建议先要求作者修复中文 README 乱码，并决定 `Accept` header 是否允许用户覆盖。处理后，这个 PR 的核心实现可以进入合并流程。 +``` + +## 输出截图 + +![Codex 输出截图](../assets/codex-validation-output.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-code-review" +Skill is valid! +``` diff --git a/skills/gitlink-contributor-insight/SKILL.md b/skills/gitlink-contributor-insight/SKILL.md index 9ad7ba8..ade82e4 100644 --- a/skills/gitlink-contributor-insight/SKILL.md +++ b/skills/gitlink-contributor-insight/SKILL.md @@ -1,6 +1,5 @@ --- name: gitlink-contributor-insight -version: 1.1.0 description: "贡献者活跃度分析：分析仓库贡献者的活跃度、贡献趋势和工作节奏，生成贡献者洞察报告。当用户需要分析贡献者活跃度、查看团队贡献趋势、评估成员参与度时触发。" metadata: requires: diff --git a/skills/gitlink-contributor-insight/assets/codex-skill-directory.png b/skills/gitlink-contributor-insight/assets/codex-skill-directory.png new file mode 100644 index 0000000..17f97e0 Binary files /dev/null and b/skills/gitlink-contributor-insight/assets/codex-skill-directory.png differ diff --git a/skills/gitlink-contributor-insight/assets/codex-validation-output-1.png b/skills/gitlink-contributor-insight/assets/codex-validation-output-1.png new file mode 100644 index 0000000..89b3fa0 Binary files /dev/null and b/skills/gitlink-contributor-insight/assets/codex-validation-output-1.png differ diff --git a/skills/gitlink-contributor-insight/assets/codex-validation-output-2.png b/skills/gitlink-contributor-insight/assets/codex-validation-output-2.png new file mode 100644 index 0000000..219772e Binary files /dev/null and b/skills/gitlink-contributor-insight/assets/codex-validation-output-2.png differ diff --git a/skills/gitlink-contributor-insight/assets/codex-validation-output-3.png b/skills/gitlink-contributor-insight/assets/codex-validation-output-3.png new file mode 100644 index 0000000..5618de1 Binary files /dev/null and b/skills/gitlink-contributor-insight/assets/codex-validation-output-3.png differ diff --git a/skills/gitlink-contributor-insight/examples/codex-validation-2026-06-25.md b/skills/gitlink-contributor-insight/examples/codex-validation-2026-06-25.md new file mode 100644 index 0000000..e897863 --- /dev/null +++ b/skills/gitlink-contributor-insight/examples/codex-validation-2026-06-25.md @@ -0,0 +1,147 @@ +# Codex 验证记录（2026-06-25） + +本记录用于提交 `gitlink-contributor-insight` 的 Agent 平台验证材料，包含技能目录截图、实际使用截图和完整输出转录。 + +## 验证平台 + +- 平台：Codex +- 仓库：`Gitlink/gitlink-cli` +- 执行范围：读取仓库贡献者活跃度、PR/Issue 分布和团队协作风险 +- 执行约束：只读分析，不修改远端，不发表评论 + +## 触发提示词 + +```text +使用 gitlink-contributor-insight 分析 Gitlink/gitlink-cli 仓库的贡献者活跃度，统计主要贡献者、近期贡献趋势、贡献分布和团队参与情况，输出一份贡献者洞察报告，不要修改远端。 +``` + +## 技能目录截图 + +![Codex 技能目录截图](../assets/codex-skill-directory.png) + +## 输出结果全文 + +```markdown +# Gitlink/gitlink-cli 贡献者洞察报告 + +分析时间：2026-06-25 +数据范围：GitLink 平台数据，已分页读取全部 282 个 PR 与 19 个 Issue +只读确认：未修改远端，未发表评论，未执行写操作 + +## 一、团队概览 + +| 指标 | 数值 | +|------|------| +| 仓库贡献者数 | 28 | +| PR 总数 | 282 | +| Issue 总数 | 19 | +| 本次从 PR 识别出的贡献者 | 28 | +| 近 30 天活跃贡献者 | 26 | +| 近 60 天活跃贡献者 | 28 | +| 默认分支 | `master` | + +活跃度很高，近 30 天已有 26/28 名 PR 贡献者参与，说明近期社区协作活动明显升温。 + +## 二、近期贡献趋势 + +| 时间段 | PR 数 | 参与作者数 | +|--------|------:|-----------:| +| 2026-04 | 7 | 2 | +| 2026-05 | 53 | 10 | +| 2026-06 | 222 | 26 | + +近 30 天 PR 数为 239，相比前一个 30 天的 37，增长约 6.5 倍。贡献明显集中爆发在 2026 年 6 月。 + +近几周节奏： + +| 周期 | PR 数 | 作者数 | +|------|------:|-------:| +| 2026-W23 | 16 | 8 | +| 2026-W24 | 145 | 21 | +| 2026-W25 | 46 | 6 | +| 2026-W26，截至 06-25 | 15 | 5 | + +W24 出现一次高峰，随后回落。建议维护者重点关注高峰期遗留的 open PR 队列。 + +## 三、贡献分布 + +PR 状态分布： + +| 状态 | 数量 | 占比 | +|------|------:|-----:| +| Open | 150 | 53.2% | +| Merged | 65 | 23.0% | +| Closed | 67 | 23.8% | + +Top 贡献集中度： + +| 范围 | PR 占比 | +|------|--------:| +| Top 1 | 31.6% | +| Top 2 | 57.4% | +| Top 5 | 73.4% | +| Top 10 | 86.9% | + +贡献者数量足够多，但产出高度集中在前两位，存在一定知识集中和评审压力风险。 + +## 四、主要贡献者排行 + +| 排名 | 贡献者 | 等级 | PR | Open/Merged/Closed | 活跃天数 | 最近贡献 | Issue | +|------|--------|------|---:|-------------------:|---------:|----------|------:| +| 1 | `wangyue111` | 核心 | 89 | 56/12/21 | 17 | 2026-06-17 | 0 | +| 2 | `Mengz` | 核心 | 73 | 49/6/18 | 14 | 2026-06-25 | 0 | +| 3 | `wbtiger` | 核心 | 19 | 0/15/4 | 12 | 2026-06-14 | 9 | +| 4 | `luwanzhou` | 核心 | 15 | 9/2/4 | 2 | 2026-06-15 | 0 | +| 5 | `Ct201314` | 核心 | 11 | 11/0/0 | 2 | 2026-06-12 | 0 | +| 6 | `dtwdtw` | 核心 | 10 | 2/3/5 | 4 | 2026-06-14 | 0 | +| 7 | `yangsai` | 核心 | 10 | 1/6/3 | 7 | 2026-06-17 | 0 | +| 8 | `co63oc` | 核心 | 8 | 3/5/0 | 6 | 2026-06-23 | 0 | +| 9 | `whale_hihihi` | 核心 | 6 | 2/1/3 | 2 | 2026-06-14 | 0 | +| 10 | `ohanabi` | 活跃 | 4 | 0/1/3 | 1 | 2026-06-08 | 0 | + +贡献者分层： + +| 分层 | 人数 | +|------|----:| +| 核心贡献者 | 9 | +| 活跃贡献者 | 6 | +| 新兴贡献者 | 10 | +| 一般参与者 | 3 | +| 休眠贡献者 | 0 | + +## 五、团队参与情况 + +Issue 参与主要集中在少数用户： + +| 贡献者 | Issue 数 | +|--------|---------:| +| `wbtiger` | 9 | +| `topshare` | 4 | +| `gzkoala` | 2 | +| `Kexing` / `yingjie` / `recorder` / `amylier` | 各 1 | + +Top 10 贡献者画像显示，7 位是在 2026 年注册的新用户，说明仓库近期吸引了明显的新贡献者流入。`wbtiger` 是长期平台用户，同时在 PR 合并和 Issue 反馈上都有较强参与，是维护和社区反馈的关键节点。 + +## 六、风险与建议 + +1. **Open PR 队列偏大**：150 个 open PR，占 53.2%。建议按优先级建立 triage 队列，先处理高质量小 PR，阻塞性修复和重要 PR。 +2. **贡献集中度偏高**：Top 2 贡献者贡献 57.4% PR。建议引入 reviewer rotation，避免知识和维护压力集中。 +3. **新贡献者涌入明显**：10 名新兴贡献者是好信号。建议补充贡献指南、Good First Issue、PR 模板和验收标准，提高首次贡献转化率。 +4. **Issue 反馈参与较少**：Issue 侧主要由少数人支撑。建议鼓励代码贡献者同步参与问题复现、需求澄清和回归验证。 +5. **合并率需要观察**：整体 merged 占比 23.0%，但近期 PR 激增会自然拉低该比例。建议在未来一周重点观察 open PR 消化速度。 +``` + +## 输出截图 + +![Codex 输出截图 1](../assets/codex-validation-output-1.png) + +![Codex 输出截图 2](../assets/codex-validation-output-2.png) + +![Codex 输出截图 3](../assets/codex-validation-output-3.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-contributor-insight" +Skill is valid! +``` 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 +``` + +如果输出里已经出现 `?`，先停下来修正编码链路，不要带着乱码继续演示或提交。