Gitlink
/
gitlink-cli
0
0
Fork 49
Code Issues Pull Requests 11 Packages Projects Releases 10 Wiki Activity

Merge PR #277: 新增 GitLink PR 队列评估与执行验证 Skill

This commit is contained in:
wbtiger 2026-07-14 22:49:54 +08:00
parent c4ead5b702 2c47f2357a
commit 0ff59db80f
7 changed files with 1085 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
skills/README.md
View File

@ -150,6 +150,7 @@ skills/
| **gitlink-wiki** | Wiki 页面管理 | `wiki +list`, `wiki +view`, `wiki +create`, `wiki +update`, `wiki +delete` |
| **gitlink-pm** | 项目管理 | 通过 Raw API 访问 |
| **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、Release Notes |
| **gitlink-pr-assessor** | open PR 队列评估与执行验证 | open 未审查 PR 扫描、维护者报告 |
| **gitlink-health** | 开源项目健康度 | 详情见SKILL.md |
| **gitlink-research-trust** | 科研开源可信度评估 | `search +repos`, `repo +info`, `repo +tree`, `repo +readme` |

476
skills/gitlink-pr-assessor/REFERENCE.md Normal file
View File

@ -0,0 +1,476 @@
# gitlink-pr-assessor REFERENCE
> 本文件补充 `gitlink-pr-assessor` 的筛选规则、字段建议、自动化接入方式和报告结构。总体工作流以 [`SKILL.md`](./SKILL.md) 为准。
## 1. 数据源
评估 open PR 队列时，优先从四类信息构建证据。
### 1.1 PR 列表与筛选
```bash
gitlink-cli pr +list --owner <owner> --repo <repo> --state open --page 1 --limit 50 --format json
```
注意：
- `--state open` 只作为粗过滤，必须再用 `pull_request_status == 0` 做二次过滤。
- PR 多时需要分页。
建议提取字段：
- `pull_request_number`
- `pull_request_status`
- `subject`
- `author_login`
- `updated_at`
- `files_count`
- `comments_count`
### 1.2 单条 PR 元数据
```bash
gitlink-cli pr +view --id <pull_request_id> --format json
gitlink-cli pr +reviews --id <pull_request_id> --format json
gitlink-cli api GET /:owner/:repo/pulls/:id/commits --format json
```
重点关注：
- 标题、描述、作者、base/head
- 现有 review 状态
- commit 数量、提交信息质量
- 关联 issue 和协作上下文
### 1.3 变更内容
```bash
gitlink-cli pr +files --id <pull_request_id> --format json
gitlink-cli pr +diff --id <pull_request_id> --format json
```
重点分析：
- 改动是否聚焦
- 是否涉及高风险目录
- 是否新增测试
- 是否新增帮助文档、CLI 输出或用户可见行为
### 1.4 仓库约束与执行证据
```bash
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
gitlink-cli ci +builds --owner <owner> --repo <repo> --format json
gitlink-cli api GET /:owner/:repo/sub_entries --query "filepath=README.md&ref=master"
gitlink-cli api GET /:owner/:repo/sub_entries --query "filepath=Makefile&ref=master"
gitlink-cli api GET /:owner/:repo/sub_entries --query "filepath=go.mod&ref=master"
```
说明：
- 这里统一使用 `pull_request_id` 作为 `--id` 的输入值。
- `raw/master/...` 在 GitLink 上实测可能返回 `403`，读取仓库约束文件时改用 `sub_entries` 更稳妥。
从仓库中判断：
- 技术栈
- 默认分支
- 官方构建和测试命令
- 是否已有 CI
- 是否有 CONTRIBUTING、docs、examples
本地验证优先使用：
- 已检出的 PR 分支
- 独立 worktree
- 临时验证目录
---
## 2. “未审查”判定细则
### 2.1 基本规则
一条 PR 进入队列，需要满足：
1. `pull_request_status == 0`
2. review 列表中没有维护者 `approved` 或 `rejected`
3. 不存在 assessor 已产出报告的标记
### 2.2 报告标记
推荐在 Markdown 报告顶部写入：
```markdown
<!-- gitlink-pr-assessor:report v1 -->
```
有了这个标记，后续定时扫描时就可以识别“这条 PR 已经评估过”。
### 2.3 需要重新评估的条件
即使已有报告，以下情况也建议重新跑：
- PR 新增了 commit
- PR 描述被明显改写
- CI 状态从失败变为通过，或从通过变为失败
- 维护者明确要求重新评估
推荐记录：
- 上次评估时的 head commit SHA
- 上次评估时间
- 上次结论
---
## 3. 待验证声明抽取规则
把 PR 描述中的自然语言整理成可以验证的声明，每条声明应尽量满足“能验证、能反驳、能给出证据”。
### 3.1 常见声明类型
| 类型 | 例子 | 推荐验证方式 |
|------|------|-------------|
| bug 修复 | 修复 Windows 路径错误 | 跑失败用例、对比 base 与 PR 行为 |
| 新命令 | 新增 `wiki +list` | 构建 CLI、执行 `--help`、跑命令 |
| 参数增强 | 支持 `owner/repo:branch` | 直接执行目标参数组合 |
| 输出优化 | 错误信息更清晰 | 复现场景，检查输出文本 |
| 兼容性修复 | 兼容复杂分支名、空格路径 | 设计特定输入验证 |
| 安全修复 | 避免注入、限制权限 | 代码检查 + 负向测试 |
### 3.2 证据不足与无法验证
以下情况不要强行写“通过”或“失败”：
- PR 描述没有说明修复或新增了什么
- 需要外部服务、私有凭据或特定平台
- 仓库没有可执行验证步骤
- 行为入口不明确
此时应明确写为：
- `evidence_status: insufficient`
- 或 `execution_status: blocked`
---
## 4. 评估维度建议
### 4.1 贡献价值
重点看：
- 问题是否真实、常见或关键
- 是否符合项目定位
- 是否减少维护负担或补齐能力缺口
### 4.2 实现可行性
重点看：
- 是否贴合现有架构
- 是否依赖不存在的接口或假设
- 是否以过高复杂度解决小问题
### 4.3 代码质量
重点看：
- 模块边界是否清晰
- 错误处理是否一致
- 命名和控制流是否易读
- 测试是否覆盖行为而不仅是路径
### 4.4 安全与风险
重点看：
- 输入校验
- 命令、路径、模板、编码、URL、权限边界
- 敏感信息暴露
- 默认行为是否危险
### 4.5 维护成本
重点看：
- 是否引入特例逻辑
- 是否增加长期兼容负担
- 文档、帮助、测试是否同步更新
### 4.6 协作质量
重点看：
- PR 描述是否清楚
- 变更是否过大
- 是否适合拆分
- reviewer 是否容易理解和复现
---
## 5. 执行验证策略
### 5.1 验证模式
#### 快速分诊模式
适用于：
- PR 很多，需要先筛选
- 只需判断是否值得继续看
- 环境重、依赖多，不适合深跑
动作：
- 跑最小构建或最相关测试
- 验证 1-2 条关键声明
- 给出初步管理建议
#### 深度验证模式
适用于：
- PR 价值高
- 涉及核心命令或高风险模块
- 维护者需要强证据
动作：
- 依据仓库规范完整构建和测试
- 对主要声明逐项验证
- 补做回归检查
### 5.2 验证命令选择顺序
按下面优先级选择：
1. PR 描述里的验证命令
2. README / docs / CONTRIBUTING / Makefile
3. CI 工作流
4. 语言生态默认命令
### 5.3 停止条件
出现以下情况应停止深挖，并明确记录阻塞原因：
- 缺少依赖或凭据
- 命令会修改外部系统
- 构建耗时或资源开销过大
- 用户当前工作树有冲突风险
---
## 6. 结构化 JSON 输出建议
自动化接入时，优先输出结构化 JSON，再派生 Markdown。
### 6.1 单条 PR 输出
```json
{
"repository": "Gitlink/gitlink-cli",
"pr_number": 42,
"title": "feat: add ...",
"queue_reason": "open-unreviewed",
"verdict": "needs_followup",
"priority": "P2",
"risk_level": "medium",
"confidence": "medium",
"execution_status": "partial",
"required_human_review": ["cli", "testing"],
"auto_review_eligible": false,
"summary": "功能方向合理，但边界验证不足。",
"dimensions": {
"contribution_value": "strong",
"feasibility": "medium",
"code_quality": "medium",
"security_risk": "low",
"maintenance_cost": "low",
"collaboration_quality": "medium"
},
"claims": [
{
"claim": "支持复杂分支名比较",
"result": "insufficient",
"evidence": "现有测试只覆盖简单分支名"
}
],
"commands": [
{
"type": "build",
"command": "go build ./...",
"result": "passed",
"note": "无构建错误"
}
],
"suggested_review": {
"status": "common",
"comment_markdown": "请补充分支名包含特殊字符时的测试。"
}
}
```
### 6.2 队列扫描输出
```json
{
"repository": "Gitlink/gitlink-cli",
"scanned_at": "2026-06-24T10:30:00+08:00",
"open_pr_total": 18,
"assessed_pr_total": 6,
"skipped": [
{
"pr_number": 19,
"reason": "already-approved"
},
{
"pr_number": 20,
"reason": "already-has-assessor-report"
}
],
"reports": [
{
"pr_number": 21,
"verdict": "needs_followup",
"priority": "P1",
"risk_level": "high"
}
]
}
```
### 6.3 推荐枚举值
| 字段 | 建议值 |
|------|--------|
| `verdict` | `ready_for_maintainer_confirmation` / `needs_followup` / `needs_more_evidence` / `needs_split` / `defer` / `reject` |
| `priority` | `P1` / `P2` / `P3` |
| `risk_level` | `low` / `medium` / `high` |
| `confidence` | `high` / `medium` / `low` |
| `execution_status` | `passed` / `partial` / `failed` / `blocked` / `not_run` |
| `claim.result` | `passed` / `failed` / `insufficient` / `blocked` |
---
## 7. 自动化接入建议
### 7.1 外层触发器
本 Skill 自身不监听 PR。自动化落地依赖外层 runner，例如：
- webhook 处理器
- 定时扫描任务
- `codex exec` 驱动脚本
- 其他 Agent 平台工作流
### 7.2 推荐事件
- PR opened
- PR reopened
- PR synchronized
- 定时全量补偿扫描
### 7.3 幂等策略
至少实现以下之一：
1. 报告正文加入 marker
2. 记录最近处理的 head SHA
3. 写入专用标签或状态文件
### 7.4 回写策略
默认建议：
- 先生成内部报告给维护者
- 不自动批准或拒绝
- 只有在仓库规则允许时，才自动回写普通评论或 review 建议
高风险 PR 一律只出报告，不自动形成强语义结论。
---
## 8. 回写建议
默认只读。只有用户或外层自动化明确要求写回时，才输出适合贴到 PR 的 Markdown。
推荐回写内容：
- 一句话结论
- 3 条以内最关键判断
- 执行验证结果
- 需要作者补充的点
不推荐回写：
- 过长命令日志
- 没有证据支撑的强结论
- 对维护者内部优先级的细节判断
---
## 9. 常见风险模式
- PR 描述很大，但测试很少
- 只新增 happy path，没有失败路径验证
- 声称“修复兼容性”，但没有平台特定验证
- 改动散落多个模块，却没有拆分
- 引入新行为，但帮助文档、命令说明、错误消息未更新
- compare、path、encoding、URL、base64 等边界只用简单样例验证
---
## 10. Windows 中文乱码排查
如果报告里的中文显示成 `?`，优先检查是不是终端编码链路有问题，而不是先怀疑 skill 文件本身损坏。
### 10.1 常见症状
- 控制台里中文正常，但重定向到文件后变成 `?`
- 通过 PowerShell 管道写文件时，中文丢失
- 报告里只有 ASCII 正常，中文和部分标点被替换
### 10.2 根因
在 Windows PowerShell 下，以下任一情况都可能导致中文被降成 `?`：
- 当前代码页不是 UTF-8
- `$OutputEncoding` 仍然是 `us-ascii`
- 用默认编码写文件，没有显式指定 UTF-8
### 10.3 建议修复
先执行：
```powershell
chcp 65001 > $null
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [Console]::OutputEncoding
```
然后保存报告时显式写 UTF-8：
```powershell
$report | Set-Content -Path .\pr-queue-report.md -Encoding utf8
```
如果需要用 Python 生成或中转文本，再补一行：
```powershell
$env:PYTHONUTF8 = '1'
```
### 10.4 快速自检
```powershell
[Console]::OutputEncoding.WebName
$OutputEncoding.WebName
```
理想结果应为：
- `[Console]::OutputEncoding.WebName` 是 `utf-8`
- `$OutputEncoding.WebName` 也是 `utf-8`

381
skills/gitlink-pr-assessor/SKILL.md Normal file
View File

@ -0,0 +1,381 @@
---
name: gitlink-pr-assessor
description: "开源社区 Pull Request 队列评估与执行验证：面向 open 且尚未形成维护者结论的 PR，批量拉取 GitLink Pull Request 的描述、diff、review、CI 与仓库上下文，评估贡献价值、实现可行性、代码质量、安全性、维护成本、协作质量和回归风险，并在项目规定环境下验证 PR 声明是否与实际行为一致。用于维护者需要自动筛查待审 PR、生成逐条管理报告、给出 review 建议，或为 webhook/定时任务/Agent runner 提供结构化决策结果时。"
---
# gitlink-pr-assessor
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理、GitLink API 特性和安全边界。**
**CRITICAL — GitLink 平台操作只能使用 `gitlink-cli`。禁止用 `gh` 或其他平台 CLI 操作 GitLink PR。**
**CRITICAL — 本 Skill 的默认目标是给维护者生成报告，不默认回写评论、Review、标签或合并结论。**
**CRITICAL — 执行验证优先使用仓库规定的构建/测试命令；不要擅自发明与项目习惯不一致的验证方式。**
**CRITICAL — 不要在用户当前工作树上冒险覆盖代码。执行验证优先使用独立 worktree、临时目录或已明确指定的 PR 检出目录。**
**CRITICAL — 在 Windows PowerShell 中生成或保存中文报告前，先切换到 UTF-8 输出链路；否则报告中的中文可能被写成 `?`。**
> 这个 Skill 是“评估引擎”，不是常驻监听进程。要实现社区里 open PR 自动审查，必须由 webhook、定时任务或 Agent runner 负责触发它。
### Windows 编码前置
如果你在 Windows PowerShell 里演示、重定向或落盘报告，先执行：
```powershell
chcp 65001 > $null
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [Console]::OutputEncoding
```
如果要把报告保存成文件，显式指定 UTF-8，不要依赖默认编码：
```powershell
$report = @"
<!-- gitlink-pr-assessor:report v1 -->
## PR #42 维护者评估报告
...
"@
$report | Set-Content -Path .\pr-42-report.md -Encoding utf8
```
---
## 目标
这个 Skill 解决的是维护者的队列压力，而不只是单条 PR 的代码挑错。
它要回答的是：
1. 当前 open PR 里，哪些还没有形成维护者结论，值得优先看。
2. 每条 PR 是否真的解决了一个有价值的问题。
3. PR 描述中的功能声明，是否能在项目规定环境下跑通。
4. 这条 PR 应该进入哪条处理路径：继续人工评审、补证据、拆分、暂缓，还是直接建议合并。
5. 如果需要人工接手，维护者最应该先看什么，review 文案可以怎么写。
---
## 使用模式
### 模式 1：单条 PR 深度评估
适用于：
- 维护者点名要看一条 PR
- 某条 PR 风险高，需要执行验证
- 用户想判断一条 PR 是否值得继续推进
### 模式 2：open 未审查 PR 队列扫描
适用于：
- 仓库有一批 open PR 等待维护者处理
- 希望自动筛出“尚未形成维护者结论”的 PR
- 希望给每条 PR 生成一份统一结构的报告，供维护者批量浏览
如果用户没有特别指定，优先按“队列扫描”来理解这个 Skill。
---
## open 未审查 PR 的判定规则
这个 Skill 对“未审查”采用保守定义，目标是筛出“还没有维护者结论”的 PR，而不是简单看有没有任何评论。
一条 PR 进入待评估队列，需要同时满足：
1. `pull_request_status == 0`，即 PR 仍然是 open。
2. 没有维护者最终态 review，例如 `approved` 或 `rejected`。
3. 没有本 Skill 已经产出的报告标记，例如 `<!-- gitlink-pr-assessor:report v1 -->`。
以下情况默认仍视为“未审查”：
- 作者自己的补充评论
- 普通讨论评论，但没有形成维护者结论
- 只有零散 review 意见，还没有统一判断
如果仓库另有规则，也可以扩展为：
- 没有 `maintainer-reviewed` 标签
- 没有“已分派 reviewer”记录
- 没有满足门禁的自动评分结果
---
## 标准流程
### Step 1：枚举 open PR
先拿仓库 PR 列表：
```bash
gitlink-cli pr +list --owner <owner> --repo <repo> --state open --page 1 --limit 50 --format json
```
注意：
- GitLink 的 `--state open` 过滤不总是精确，必须再用返回里的 `pull_request_status` 做客户端过滤。
- 仓库 PR 多时要分页扫描。
### Step 2：筛选待评估队列
对每条 open PR 补拉 review 信息：
```bash
gitlink-cli pr +reviews --owner <owner> --repo <repo> --id <pull_request_id> --format json
gitlink-cli pr +view --owner <owner> --repo <repo> --id <pull_request_id> --format json
```
然后判断：
- 是否已有 `approved` 或 `rejected`
- 是否已有 assessor 报告标记
- 是否需要跳过，例如已是 draft、明显等待作者补改、或仓库规则要求延后处理
输出一个“本轮待处理 PR 队列”。
### Step 3：为每条 PR 采集评估上下文
```bash
gitlink-cli pr +view --id <pull_request_id> --format json
gitlink-cli pr +files --id <pull_request_id> --format json
gitlink-cli pr +diff --id <pull_request_id> --format json
gitlink-cli pr +reviews --id <pull_request_id> --format json
gitlink-cli api GET /:owner/:repo/pulls/:id/commits --format json
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
gitlink-cli ci +builds --owner <owner> --repo <repo> --format json
```
`pr +view`、`pr +files`、`pr +diff`、`pr +reviews` 在这里统一使用 `pull_request_id`。
`pull_request_number` 只保留给维护者看的报告标题、队列表格和网页链接。
至少提取：
- PR 标题、描述、作者、创建时间、base/head
- 文件数、增删行、核心改动目录
- 现有 review 和 comment 的主要争议点
- commit 粒度与信息质量
- CI 状态
- 仓库默认分支、语言、构建方式和测试方式
### Step 4：提炼“待验证声明”
从 PR 标题、描述、关联 issue、测试说明中提炼作者声称完成的事情，例如：
- 修复某个具体 bug
- 新增某个命令、参数或输出格式
- 改善兼容性、错误提示或跨平台行为
- 不影响已有流程
每条声明都必须能被标记为以下结果之一：
- 通过
- 失败
- 证据不足
- 无法验证
### Step 5：做静态决策评估
至少覆盖以下维度：
| 维度 | 关注点 |
|------|------|
| 贡献价值 | 是否解决真实痛点，是否符合项目方向 |
| 实现可行性 | 是否贴合现有架构，复杂度是否合理 |
| 代码质量 | 结构、命名、错误处理、测试、可读性 |
| 安全与风险 | 输入校验、权限边界、回归风险、危险默认行为 |
| 维护成本 | 后续扩展成本、特例逻辑、文档与帮助是否同步 |
| 协作质量 | PR 描述是否清楚、变更是否过大、是否适合拆分 |
### Step 6：做执行验证
按下面顺序决定验证方式：
1. PR 描述中作者给出的验证步骤
2. 仓库 README、docs、CONTRIBUTING、Makefile
3. CI 配置中的官方命令
4. 语言生态默认命令
常见命令示例：
- Go：`go build ./...`、`go test ./...`
- Node.js：`npm test`、`pnpm test`、`npm run build`
- Python：`pytest`、`python -m pytest`
- Rust：`cargo test`、`cargo build`
执行验证分三层：
1. **环境层**：依赖、构建、测试入口能否正常工作。
2. **功能层**：PR 声明的行为是否复现。
3. **回归层**：核心已有流程是否仍然正常。
### Step 7：给出维护者报告
每条 PR 都要生成一份独立报告，核心必须包含：
- 明确结论
- 风险等级
- 证据强度
- 执行验证状态
- 声明验证结果
- 最值得维护者关注的 2-3 个点
- 建议 review 文案
### Step 8：输出队列总览
如果是批量扫描，还要再生成一个“本轮 PR 队列总览”，至少包括：
- 本轮扫描时间
- 扫描仓库
- open PR 总数
- 纳入评估的 PR 数
- 被跳过的 PR 及原因
- 每条待处理 PR 的结论、风险和优先级
---
## 输出格式
优先同时产出两份结果：
### 1. 结构化 JSON
给 runner、自动化脚本或后续 Agent 消费。字段建议见 [`REFERENCE.md`](./REFERENCE.md)。
### 2. Markdown 报告
给维护者直接阅读，既可以本地存档，也可以在得到授权后回写到 PR 或管理面板。
---
## 维护者报告模板
```markdown
<!-- gitlink-pr-assessor:report v1 -->
## PR #<id> 维护者评估报告
**结论：** 建议小改后再进入人工评审
**风险等级：** 中
**证据强度：** 中
**执行验证：** 部分通过
### 核心判断
1. <这条 PR 到底解决了什么问题，值不值得继续看>
2. <维护者现在最需要关注的实现问题或风险>
3. <最关键的验证结果或阻塞项>
### 维度评估
| 维度 | 结论 | 说明 |
|------|------|------|
| 贡献价值 | 强 / 中 / 弱 | ... |
| 实现可行性 | 强 / 中 / 弱 | ... |
| 代码质量 | 强 / 中 / 弱 | ... |
| 安全与风险 | 低 / 中 / 高 | ... |
| 维护成本 | 低 / 中 / 高 | ... |
| 协作质量 | 强 / 中 / 弱 | ... |
### 声明验证
| 声明 | 结果 | 证据 |
|------|------|------|
| <作者声称修复/新增的内容> | 通过 / 失败 / 证据不足 / 无法验证 | <命令、测试或观察> |
### 执行验证记录
| 类型 | 命令/动作 | 结果 | 备注 |
|------|-----------|------|------|
| 构建 | `...` | 通过 | ... |
| 测试 | `...` | 通过 | ... |
| 场景验证 | `...` | 失败 | ... |
### 建议 review 文案
<给维护者可直接改写或粘贴的 review 建议，重点指出应让作者补什么、维护者接下来怎么处理。>
```
---
## 队列总览模板
```markdown
# <owner>/<repo> PR 待审队列报告
扫描时间：<timestamp>
open PR：<n>
纳入评估：<n>
跳过：<n>
| PR | 标题 | 结论 | 风险 | 优先级 | 说明 |
|----|------|------|------|--------|------|
| #12 | ... | 建议优先人工评审 | 高 | P1 | 涉及认证与权限 |
| #13 | ... | 建议补测试后再审 | 中 | P2 | 功能价值明确，但证据不足 |
| #14 | ... | 建议暂缓 | 低 | P3 | 依赖上层设计决策 |
## 跳过项
- #15：已有 `approved`
- #16：已存在 assessor 报告标记
```
---
## 自动化接入方式
如果要把它真正放进开源社区，不要要求维护者手工逐条调用，而是用外层系统定时或事件触发它。
推荐的触发方式有两类：
### 方式 1：PR 事件触发
在以下事件触发一次评估：
- PR opened
- PR reopened
- PR synchronized / push new commits
适合及时反馈，但要注意避免重复生成报告。
### 方式 2：定时队列扫描
例如每 10 分钟或每小时扫一次仓库 open PR：
- 列出 open PR
- 过滤出未审查项
- 为每条生成报告
- 汇总为维护者面板或日报
适合社区管理场景，也更容易补偿 webhook 漏触发。
### 幂等规则
自动模式必须有幂等设计，避免同一条 PR 重复刷报告：
- 在回写内容中加入 `<!-- gitlink-pr-assessor:report v1 -->`
- 或记录最近处理的 commit SHA
- 或给 PR 打上专用标签，例如 `assessor-reviewed`
---
## 结论规则
最终结论必须是明确动作，而不是泛泛而谈。推荐使用以下集合：
- 建议直接进入合并前人工确认
- 建议小改后继续人工评审
- 建议补测试或补文档后再审
- 建议拆分后重提
- 建议暂缓
- 建议拒绝
同时标注：
- `risk_level`：低 / 中 / 高
- `confidence`：高 / 中 / 低
- `execution_status`：通过 / 部分通过 / 未通过 / 无法验证
- `priority`：P1 / P2 / P3
---
## 边界
- 不要把“无法验证”写成“失败”。
- 不要把“作者写了测试”写成“功能已经被证明正确”。
- 不要只看代码风格而忽略真实价值和维护成本。
- 不要只跑全量测试而忽略 PR 描述中的关键声明。
- 不要在缺少证据时给出过度确定的结论。
- 不要把这个 Skill 伪装成自动监听器；自动化必须由外层 webhook、cron 或 runner 提供。
更多字段建议、筛选规则、自动化运行建议和 JSON 结构见 [`REFERENCE.md`](./REFERENCE.md)。
实际验证产物见 [`examples/codex-first40-validation.md`](./examples/codex-first40-validation.md)。

36
skills/gitlink-pr-assessor/examples/codex-first40-validation.md Normal file
View File

@ -0,0 +1,36 @@
# Codex 验证记录：扫描前 40 条 open PR
这个示例记录了 `gitlink-pr-assessor` 在 Codex 中的一次实际验证，用来证明这个 skill 可以在真实仓库上完成 open PR 队列扫描、逐条评估和维护者报告整理。
## 验证环境
- Agent 平台：Codex
- 仓库：`Gitlink/gitlink-cli`
- 时间：2026-06-24
- 模式：只读扫描，不回写 PR
## 使用提示词
```text
$gitlink-pr-assessor 扫描 Gitlink/gitlink-cli 仓库当前前 40 条 open PR。只保留 pull_request_status == 0、且没有 approved / rejected、且没有 assessor 报告标记的 PR。对符合条件的 PR 生成一份队列总览，并为每条 PR 生成维护者报告，不要回写到 PR。
```
## 产出结果
- 这次验证已经成功生成队列总览和逐条评估结果，证明 skill 可以在真实 open PR 队列上完成批量筛查。
- 为避免把一次性运行日志和截图长期提交进仓库，详细报告与界面截图不再作为仓库内容保留；如需展示，可在 PR 描述、评审回复或单独的演示材料中引用。
- 仓库内保留这份验证说明，作为“已在真实项目执行过”的复核依据。
## 验证结论
- 成功扫描当前列表顺序下前 40 条 open PR。
- 按 `pull_request_status == 0`、review 状态和 assessor 标记完成过滤。
- 对纳入范围的 PR 生成了维护者队列总览和逐条报告。
- 全程没有向 PR 回写内容，也没有修改当前工作树中的既有文件。
## 结果摘要
- 纳入评估：39 条
- 跳过：1 条
- `origin/master` 基线上的 `go build ./...` 与 `go test ./...` 均通过
- 扫描结果能够区分可继续推进、需补测试、需拆分、建议拒绝等不同结论

128
skills/gitlink-pr-assessor/examples/gitlink-cli-pr-assessment.md Normal file
View File

@ -0,0 +1,128 @@
# gitlink-cli PR 队列评估示例
这个示例展示如何用 `gitlink-pr-assessor` 扫描 `gitlink-cli` 仓库里的 open PR，并筛出“还没有形成维护者结论”的 PR，给每条 PR 生成一份报告。
## 示例目标
维护者希望每天或每隔一段时间得到一份待审队列报告，帮助回答：
- 哪些 open PR 还没有被真正处理
- 哪些 PR 值得优先投入人工评审
- 哪些 PR 只是证据不足，需要作者先补测试或补说明
## 推荐流程
这里统一约定：
- `pull_request_id` 用来执行 `pr +view`、`pr +files`、`pr +diff`、`pr +reviews`
- `pull_request_number` 只用于人类阅读的报告标题、列表展示和网页链接
### 1. 拉 open PR 列表
```bash
gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state open --page 1 --limit 50 --format json
```
注意：
- 不要只信 `--state open`
- 必须再按 `pull_request_status == 0` 过滤
### 2. 对每条 PR 判断是否进入待评估队列
```bash
gitlink-cli pr +view --owner Gitlink --repo gitlink-cli --id <pull_request_id> --format json
gitlink-cli pr +reviews --owner Gitlink --repo gitlink-cli --id <pull_request_id> --format json
```
建议跳过：
- 已有 `approved`
- 已有 `rejected`
- 已经带有 assessor 报告标记 `<!-- gitlink-pr-assessor:report v1 -->`
### 3. 对纳入队列的 PR 拉上下文
```bash
gitlink-cli pr +files --id <pull_request_id> --format json
gitlink-cli pr +diff --id <pull_request_id> --format json
gitlink-cli api GET /Gitlink/gitlink-cli/pulls/<pull_request_id>/commits --format json
gitlink-cli repo +info --owner Gitlink --repo gitlink-cli --format json
gitlink-cli ci +builds --owner Gitlink --repo gitlink-cli --format json
```
### 4. 提炼待验证声明
例如 PR 描述写了：
- 新增某个 shortcut
- 修复某个复杂边界输入问题
- 补充帮助文档和测试
那么可以整理出声明清单：
1. 命令或参数是否真的存在。
2. 行为是否与 PR 描述一致。
3. 测试是否覆盖关键边界值。
4. 构建和相关模块测试是否通过。
### 5. 按 `gitlink-cli` 的仓库习惯做执行验证
对这个仓库，通常优先验证：
```bash
go build ./...
go test ./...
```
如果 PR 只影响局部模块，再补局部测试，例如：
```bash
go test ./shortcuts/pr/...
go test ./shortcuts/attachment/...
go test ./shortcuts/workflow/...
```
### 6. 输出两层结果
#### 队列总览
给维护者快速看：
- 今天扫描到多少 open PR
- 其中多少条需要优先看
- 哪些被跳过，为什么跳过
#### 单条 PR 报告
给维护者细看：
- 这条 PR 值不值得继续投精力
- 当前最关键的风险是什么
- 作者下一步该补什么
- 维护者适合给出什么 review 建议
## 一个典型结论示例
如果某条 PR 的情况是：
- 功能方向合理
- 局部测试通过
- 全量构建通过
- 但复杂边界输入没有测试
那么更合适的报告结论通常是：
`建议补测试或补验证说明后再进入人工评审`
如果某条 PR 的情况是：
- 涉及鉴权、路径、编码或发布逻辑
- 影响面大
- 证据还不够完整
那么应提高优先级，并明确写出：
- `risk_level: high`
- `priority: P1`
- 需要哪类维护者继续接手，例如 CLI、安全或架构方向

23
skills/gitlink-pr-assessor/examples/queue-scan-summary.md Normal file
View File

@ -0,0 +1,23 @@
# PR 队列总览示例
```markdown
# Gitlink/gitlink-cli PR 待审队列报告
扫描时间：2026-06-24 10:30:00 +08:00
open PR：12
纳入评估：4
跳过：8
| PR | 标题 | 结论 | 风险 | 优先级 | 说明 |
|----|------|------|------|--------|------|
| #21 | feat: ... | 建议小改后继续人工评审 | 中 | P2 | 功能方向明确，但关键边界测试不足 |
| #22 | fix: ... | 建议优先人工评审 | 高 | P1 | 涉及路径和编码边界，需确认回归风险 |
| #24 | feat: ... | 建议补文档后再审 | 低 | P3 | 代码可读性尚可，但帮助与示例未更新 |
| #25 | refactor: ... | 建议拆分后重提 | 中 | P2 | 变更范围过大，混入多类修改 |
## 跳过项
- #18：已有 `approved`
- #19：已有 `rejected`
- #20：已存在 assessor 报告标记
- #23：作者刚 push 新提交，等待下一轮统一重评
```

40
skills/gitlink-pr-assessor/examples/report-template.md Normal file
View File

@ -0,0 +1,40 @@
<!-- gitlink-pr-assessor:report v1 -->
## PR #42 维护者评估报告
**结论：** 建议补测试或补验证说明后再进入人工评审
**风险等级：** 中
**证据强度：** 中
**执行验证：** 部分通过
**优先级：** P2
### 核心判断
1. 这条 PR 解决的问题真实且有价值，能够补齐当前 CLI 的能力缺口。
2. 实现方向基本合理，但对边界输入的处理证据不足，复杂分支名和特殊字符场景仍需补验证。
3. 本地构建和相关模块测试可以通过，但还不能充分证明 PR 描述中的全部声明都成立。
### 维度评估
| 维度 | 结论 | 说明 |
|------|------|------|
| 贡献价值 | 强 | 解决真实维护痛点或用户需求 |
| 实现可行性 | 中 | 主体方案成立，但仍有边界条件待确认 |
| 代码质量 | 中 | 结构清晰，测试还可继续加强 |
| 安全与风险 | 中 | 暂未发现明显安全问题，但兼容性回归仍需关注 |
| 维护成本 | 低 | 未明显引入额外长期负担 |
| 协作质量 | 中 | PR 描述基本清楚，但验证说明还可更具体 |
### 声明验证
| 声明 | 结果 | 证据 |
|------|------|------|
| 新命令或新参数已经可用 | 通过 | `--help` 与目标命令执行结果符合预期 |
| 修复复杂边界输入 | 证据不足 | 现有测试样例过于简单，未覆盖关键边界 |
| 不影响现有核心流程 | 通过 | 相关模块测试与构建通过 |
### 执行验证记录
| 类型 | 命令/动作 | 结果 | 备注 |
|------|-----------|------|------|
| 构建 | `go build ./...` | 通过 | 无构建错误 |
| 定向测试 | `go test ./shortcuts/pr/...` | 通过 | 相关模块测试通过 |
| 声明验证 | 使用复杂输入手工推演 | 证据不足 | 尚缺自动化测试或明确复现步骤 |
### 建议 review 文案
当前实现方向是合理的，但关于复杂输入和边界字符的行为还缺少足够证据。建议补充覆盖特殊分支名或特殊字符场景的测试，并在 PR 描述里写明复现与验证步骤；补齐后这条 PR 会更适合继续进入人工评审。