diff --git a/skills/README.md b/skills/README.md index 2ef5c54..cdd42a9 100644 --- a/skills/README.md +++ b/skills/README.md @@ -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` | diff --git a/skills/gitlink-pr-assessor/REFERENCE.md b/skills/gitlink-pr-assessor/REFERENCE.md new file mode 100644 index 0000000..0cabb06 --- /dev/null +++ b/skills/gitlink-pr-assessor/REFERENCE.md @@ -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 --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 --format json +gitlink-cli pr +reviews --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 --format json +gitlink-cli pr +diff --id --format json +``` + +重点分析: + +- 改动是否聚焦 +- 是否涉及高风险目录 +- 是否新增测试 +- 是否新增帮助文档、CLI 输出或用户可见行为 + +### 1.4 仓库约束与执行证据 + +```bash +gitlink-cli repo +info --owner --repo --format json +gitlink-cli ci +builds --owner --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 + +``` + +有了这个标记,后续定时扫描时就可以识别“这条 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` diff --git a/skills/gitlink-pr-assessor/SKILL.md b/skills/gitlink-pr-assessor/SKILL.md new file mode 100644 index 0000000..1360d84 --- /dev/null +++ b/skills/gitlink-pr-assessor/SKILL.md @@ -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 = @" + +## 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 已经产出的报告标记,例如 ``。 + +以下情况默认仍视为“未审查”: + +- 作者自己的补充评论 +- 普通讨论评论,但没有形成维护者结论 +- 只有零散 review 意见,还没有统一判断 + +如果仓库另有规则,也可以扩展为: + +- 没有 `maintainer-reviewed` 标签 +- 没有“已分派 reviewer”记录 +- 没有满足门禁的自动评分结果 + +--- + +## 标准流程 + +### Step 1:枚举 open PR + +先拿仓库 PR 列表: + +```bash +gitlink-cli pr +list --owner --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 --repo --id --format json +gitlink-cli pr +view --owner --repo --id --format json +``` + +然后判断: + +- 是否已有 `approved` 或 `rejected` +- 是否已有 assessor 报告标记 +- 是否需要跳过,例如已是 draft、明显等待作者补改、或仓库规则要求延后处理 + +输出一个“本轮待处理 PR 队列”。 + +### Step 3:为每条 PR 采集评估上下文 + +```bash +gitlink-cli pr +view --id --format json +gitlink-cli pr +files --id --format json +gitlink-cli pr +diff --id --format json +gitlink-cli pr +reviews --id --format json +gitlink-cli api GET /:owner/:repo/pulls/:id/commits --format json +gitlink-cli repo +info --owner --repo --format json +gitlink-cli ci +builds --owner --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 + +## PR # 维护者评估报告 + +**结论:** 建议小改后再进入人工评审 +**风险等级:** 中 +**证据强度:** 中 +**执行验证:** 部分通过 + +### 核心判断 +1. <这条 PR 到底解决了什么问题,值不值得继续看> +2. <维护者现在最需要关注的实现问题或风险> +3. <最关键的验证结果或阻塞项> + +### 维度评估 +| 维度 | 结论 | 说明 | +|------|------|------| +| 贡献价值 | 强 / 中 / 弱 | ... | +| 实现可行性 | 强 / 中 / 弱 | ... | +| 代码质量 | 强 / 中 / 弱 | ... | +| 安全与风险 | 低 / 中 / 高 | ... | +| 维护成本 | 低 / 中 / 高 | ... | +| 协作质量 | 强 / 中 / 弱 | ... | + +### 声明验证 +| 声明 | 结果 | 证据 | +|------|------|------| +| <作者声称修复/新增的内容> | 通过 / 失败 / 证据不足 / 无法验证 | <命令、测试或观察> | + +### 执行验证记录 +| 类型 | 命令/动作 | 结果 | 备注 | +|------|-----------|------|------| +| 构建 | `...` | 通过 | ... | +| 测试 | `...` | 通过 | ... | +| 场景验证 | `...` | 失败 | ... | + +### 建议 review 文案 +<给维护者可直接改写或粘贴的 review 建议,重点指出应让作者补什么、维护者接下来怎么处理。> +``` + +--- + +## 队列总览模板 + +```markdown +# / PR 待审队列报告 + +扫描时间: +open PR: +纳入评估: +跳过: + +| 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 重复刷报告: + +- 在回写内容中加入 `` +- 或记录最近处理的 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)。 diff --git a/skills/gitlink-pr-assessor/examples/codex-first40-validation.md b/skills/gitlink-pr-assessor/examples/codex-first40-validation.md new file mode 100644 index 0000000..1f90545 --- /dev/null +++ b/skills/gitlink-pr-assessor/examples/codex-first40-validation.md @@ -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 ./...` 均通过 +- 扫描结果能够区分可继续推进、需补测试、需拆分、建议拒绝等不同结论 diff --git a/skills/gitlink-pr-assessor/examples/gitlink-cli-pr-assessment.md b/skills/gitlink-pr-assessor/examples/gitlink-cli-pr-assessment.md new file mode 100644 index 0000000..49824ca --- /dev/null +++ b/skills/gitlink-pr-assessor/examples/gitlink-cli-pr-assessment.md @@ -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 --format json +gitlink-cli pr +reviews --owner Gitlink --repo gitlink-cli --id --format json +``` + +建议跳过: + +- 已有 `approved` +- 已有 `rejected` +- 已经带有 assessor 报告标记 `` + +### 3. 对纳入队列的 PR 拉上下文 + +```bash +gitlink-cli pr +files --id --format json +gitlink-cli pr +diff --id --format json +gitlink-cli api GET /Gitlink/gitlink-cli/pulls//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、安全或架构方向 diff --git a/skills/gitlink-pr-assessor/examples/queue-scan-summary.md b/skills/gitlink-pr-assessor/examples/queue-scan-summary.md new file mode 100644 index 0000000..b9b33ca --- /dev/null +++ b/skills/gitlink-pr-assessor/examples/queue-scan-summary.md @@ -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 新提交,等待下一轮统一重评 +``` diff --git a/skills/gitlink-pr-assessor/examples/report-template.md b/skills/gitlink-pr-assessor/examples/report-template.md new file mode 100644 index 0000000..351c49e --- /dev/null +++ b/skills/gitlink-pr-assessor/examples/report-template.md @@ -0,0 +1,40 @@ + +## PR #42 维护者评估报告 + +**结论:** 建议补测试或补验证说明后再进入人工评审 +**风险等级:** 中 +**证据强度:** 中 +**执行验证:** 部分通过 +**优先级:** P2 + +### 核心判断 +1. 这条 PR 解决的问题真实且有价值,能够补齐当前 CLI 的能力缺口。 +2. 实现方向基本合理,但对边界输入的处理证据不足,复杂分支名和特殊字符场景仍需补验证。 +3. 本地构建和相关模块测试可以通过,但还不能充分证明 PR 描述中的全部声明都成立。 + +### 维度评估 +| 维度 | 结论 | 说明 | +|------|------|------| +| 贡献价值 | 强 | 解决真实维护痛点或用户需求 | +| 实现可行性 | 中 | 主体方案成立,但仍有边界条件待确认 | +| 代码质量 | 中 | 结构清晰,测试还可继续加强 | +| 安全与风险 | 中 | 暂未发现明显安全问题,但兼容性回归仍需关注 | +| 维护成本 | 低 | 未明显引入额外长期负担 | +| 协作质量 | 中 | PR 描述基本清楚,但验证说明还可更具体 | + +### 声明验证 +| 声明 | 结果 | 证据 | +|------|------|------| +| 新命令或新参数已经可用 | 通过 | `--help` 与目标命令执行结果符合预期 | +| 修复复杂边界输入 | 证据不足 | 现有测试样例过于简单,未覆盖关键边界 | +| 不影响现有核心流程 | 通过 | 相关模块测试与构建通过 | + +### 执行验证记录 +| 类型 | 命令/动作 | 结果 | 备注 | +|------|-----------|------|------| +| 构建 | `go build ./...` | 通过 | 无构建错误 | +| 定向测试 | `go test ./shortcuts/pr/...` | 通过 | 相关模块测试通过 | +| 声明验证 | 使用复杂输入手工推演 | 证据不足 | 尚缺自动化测试或明确复现步骤 | + +### 建议 review 文案 +当前实现方向是合理的,但关于复杂输入和边界字符的行为还缺少足够证据。建议补充覆盖特殊分支名或特殊字符场景的测试,并在 PR 描述里写明复现与验证步骤;补齐后这条 PR 会更适合继续进入人工评审。