11 KiB

Raw Blame History

gitlink-pr-assessor REFERENCE

本文件补充 gitlink-pr-assessor 的筛选规则、字段建议、自动化接入方式和报告结构。总体工作流以 SKILL.md 为准。

1. 数据源

评估 open PR 队列时，优先从四类信息构建证据。

1.1 PR 列表与筛选

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 元数据

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 变更内容

gitlink-cli pr +files --id <pull_request_id> --format json
gitlink-cli pr +diff --id <pull_request_id> --format json

重点分析：

改动是否聚焦
是否涉及高风险目录
是否新增测试
是否新增帮助文档、CLI 输出或用户可见行为

1.4 仓库约束与执行证据

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 进入队列，需要满足：

pull_request_status == 0
review 列表中没有维护者 approved 或 rejected
不存在 assessor 已产出报告的标记

2.2 报告标记

推荐在 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 验证命令选择顺序

按下面优先级选择：

PR 描述里的验证命令
README / docs / CONTRIBUTING / Makefile
CI 工作流
语言生态默认命令

5.3 停止条件

出现以下情况应停止深挖，并明确记录阻塞原因：

缺少依赖或凭据
命令会修改外部系统
构建耗时或资源开销过大
用户当前工作树有冲突风险

6. 结构化 JSON 输出建议

自动化接入时，优先输出结构化 JSON，再派生 Markdown。

6.1 单条 PR 输出

{
  "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 队列扫描输出

{
  "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 幂等策略

至少实现以下之一：

报告正文加入 marker
记录最近处理的 head SHA
写入专用标签或状态文件

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 建议修复

先执行：

chcp 65001 > $null
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [Console]::OutputEncoding

然后保存报告时显式写 UTF-8：

$report | Set-Content -Path .\pr-queue-report.md -Encoding utf8

如果需要用 Python 生成或中转文本，再补一行：

$env:PYTHONUTF8 = '1'

10.4 快速自检

[Console]::OutputEncoding.WebName
$OutputEncoding.WebName

理想结果应为：

[Console]::OutputEncoding.WebName 是 utf-8
$OutputEncoding.WebName 也是 utf-8

11 KiB Raw Blame History Unescape Escape

gitlink-pr-assessor REFERENCE

1. 数据源

1.1 PR 列表与筛选

1.2 单条 PR 元数据

1.3 变更内容

1.4 仓库约束与执行证据

2. “未审查”判定细则

2.1 基本规则

2.2 报告标记

2.3 需要重新评估的条件

3. 待验证声明抽取规则

3.1 常见声明类型

3.2 证据不足与无法验证

4. 评估维度建议

4.1 贡献价值

4.2 实现可行性

4.3 代码质量

4.4 安全与风险

4.5 维护成本

4.6 协作质量

5. 执行验证策略

5.1 验证模式

快速分诊模式

深度验证模式

5.2 验证命令选择顺序

5.3 停止条件

6. 结构化 JSON 输出建议

6.1 单条 PR 输出

6.2 队列扫描输出

6.3 推荐枚举值

7. 自动化接入建议

7.1 外层触发器

7.2 推荐事件

7.3 幂等策略

7.4 回写策略

8. 回写建议

9. 常见风险模式

10. Windows 中文乱码排查

10.1 常见症状

10.2 根因

10.3 建议修复

10.4 快速自检

11 KiB

Raw Blame History