从零跑通 gitcode-issue-triage:手把手用 AI Agent 清理仓库 Issue 噪声
从零跑通 gitcode-issue-triage:手把手用 AI Agent 清理仓库 Issue 噪声
项目地址:https://gitcode.com/agent-best-practices/gitcode-issue-triage 本文是一篇上手教程:从环境准备到实际关掉第一批灌水 issue,全程可复制。 全程只需 Python 3.8+ 标准库,不需要
pip install任何东西。
读完这篇你能做到什么
按本文顺序走一遍,你会完成这样一条链路:
零凭据侦察 → 出全库候选清单 → 创建令牌 → 认身份 → 单条干跑
→ 正式关闭一条 → 批量处理 → 读报告排错
并且你会在每一步都先看到将要发生什么,再决定是否执行——这是这个 Skill 的默认工作方式,也是它敢用来自动化不可逆操作的原因。
前置条件清单
| 项 | 要求 | 怎么确认 |
|---|---|---|
| Python | 3.8 或更高 | python --version |
| GitCode 账号 | 要有一个对目标仓库有写权限的账号 | 网页端能进仓库 Settings 即可 |
| 目标仓库 | GitCode(gitcode.com / atomgit.com)上的仓库 | 记住 owner 和 repo 两个值 |
| 令牌 | 写操作阶段才需要,先不用建 | 见第 4 步 |
⚠️ 先说明边界:本 Skill 仅支持 GitCode,不处理 GitHub、Gitee。
第 1 步:拿到 Skill
方式一,直接克隆:
git clone https://gitcode.com/agent-best-practices/gitcode-issue-triage.git
cd gitcode-issue-triage
方式二,把仓库地址直接交给你的 AI Agent,让它按地址安装(Agent 通常能自己完成下载 + 放目录)。
拿到后先确认目录结构对得上:
ls -la
# 期望看到:SKILL.md README.md LICENSE references/ scripts/
ls scripts/
# 期望看到:gitcode_issue.py sweep.py selftest.py
顺手跑一次离线自测,确认代码是好的(无网络调用,几秒钟):
python scripts/selftest.py
# 期望输出:ALL TESTS PASSED
如果这一步就报错,说明 Python 环境或文件不完整,先解决它,别再往下走。
第 2 步:装进 Agent 的 skills 目录
把整个 gitcode-issue-triage/ 目录放进下面任一个位置:
| 位置 | 作用范围 | 建议 |
|---|---|---|
~/.workbuddy/skills/ |
用户级,所有项目可用 | 推荐 |
<项目>/.workbuddy/skills/ |
项目级,随项目共享 | 团队协作时用 |
两条容易踩的坑:
- 目录内必须直接包含
SKILL.md,不能再多套一层同名目录。也就是说路径必须是~/.workbuddy/skills/gitcode-issue-triage/SKILL.md,而不是.../gitcode-issue-triage/gitcode-issue-triage/SKILL.md。 - 装好后需要新开一个会话才会被加载——技能只在会话启动时扫描一次。
验证是否装好:新开的会话里问你的 Agent"有哪些可用技能",看它能不能列出 gitcode-issue-triage。
第 3 步:先只读侦察(零凭据,最安全的一步)
这一步不会产生任何写操作。 所有请求都是 GET。
references/gitcode-api.md 里实测确认了一个很关键的事实:公开仓库的读操作完全不需要令牌。所以可以零凭据先扫全库。
用 sweep.py 一次扫完,它会复用 CLI 里同一套 classify() 和 safety_guard(),保证判定结果和 CLI 完全一致:
python scripts/sweep.py --owner <owner> --repo <repo> --state all --no-auth --out report.md
sweep.py 的完整参数(比 README 里列的更全):
| 参数 | 说明 |
|---|---|
--owner / --repo |
仓库标识,也可用环境变量 GITCODE_OWNER / GITCODE_REPO |
--token |
可选;不传即匿名(公开仓库够用) |
--no-auth |
显式声明匿名,不带令牌 |
--state |
open / closed / all,默认 all |
--per-page |
每页条数,默认 50(最大 100) |
--json |
输出 JSON 而不是表格 |
--out |
额外把报告写成 UTF-8 文件(Windows 上强烈建议加) |
--max |
只扫前 N 条,试跑时非常有用 |
--agent-login |
Agent 账号 login,用于"真人参与"护栏的比对 |
--bot-logins |
额外机器人账号,逗号分隔 |
第一次跑,建议先小步试水:
python scripts/sweep.py --owner <owner> --repo <repo> --state all --no-auth --max 30 --out trial.md
怎么读输出
每行是一个 issue,关键看第二列的判定:
GitCode triage sweep — owner/repo (state=all)
total=128 CLOSE=68 KEEP=60 HUMAN=0
issue state verdict title / signals
----------------------------------------------------------------------------
#146 open CLOSE ...
拿个积分,points_farming
#142 open KEEP ...
是否支持 docker 部署 | guard: legit_request:...
三种判定含义:
| verdict | 含义 | 该怎么处理 |
|---|---|---|
| CLOSE | 命中强信号,且安全护栏放行 | 可以关,是 process 的候选 |
| KEEP | 护栏一票否决了 | 不要动,交人工 |
| HUMAN | 信号弱或有歧义 | 需要人去读正文再定,不要自动关 |
设计上就偏向"多出 KEEP/HUMAN,少出 CLOSE":
sweep.py源码里verdict_for()明文写着——只要allowed为 false 就直接返回 KEEP;没有强信号就返回 HUMAN。宁可漏,不可错。
本步的两个坑
坑 1:分页会静默截断。 GET /issues 单次最多返回 100 条,而这个真实仓库有 142 条 issue(编号 1–144 有空隙)。不翻页会完全漏掉 1–42 号。sweep.py 内部是走全量分页的,但你自己写脚本时一定要检查这点。
坑 2:限流是 50 次/分钟,而且是账号+IP 的全局预算。 全库扫描很容易撞上:
{"error_code":429,"error_message":"429 The number of times the user invokes this API is too large. Threshold: 50 times per user per Minute. ..."}
sweep.py 里的 RATE.wait() 就是为此准备的:只在真的需要额外请求时(比如该 issue 有评论才去拉评论)才等待,把请求预算省下来。
第 4 步:创建令牌并配置
只读阶段不需要令牌;要回复和关闭,才需要。
- 打开
https://gitcode.com/setting/token-classic创建个人访问令牌。 - 勾选这些 scope:
api、read_repository、write_repository、issues。
配置方式二选一:
# 方式一:环境变量(推荐,适合反复运行)
export GITCODE_TOKEN=<你的令牌>
export GITCODE_OWNER=<owner>
export GITCODE_REPO=<repo>
# 方式二:命令行直接传 --token(适合一次性操作)
可选变量:
| 变量 | 说明 |
|---|---|
GITCODE_AGENT_LOGIN |
Agent 账号的 login,下一步 whoami 会给 |
GITCODE_BOT_LOGINS |
额外机器人账号,逗号分隔 |
GITCODE_MAX_RETRIES |
429 重试次数,默认 3 |
GITCODE_API_BASE |
接口基址覆盖,默认官方 v5 |
🔒 安全纪律:令牌永不落盘到技能目录或任何会被提交的文件。 只用参数或环境变量传入。技能目录本身不含任何凭据,可以安全分发。
第 5 步:认身份(这一步有个会静默失败的坑)
python scripts/gitcode_issue.py --owner <owner> --repo <repo> --token <token> whoami
输出里有两个字段,不要搞混:
| 字段 | 含义 | 可变性 |
|---|---|---|
login |
唯一账号句柄,用于 URL | 稳定 |
name |
显示名 | 随时可改 |
所有身份比对都必须用 login。 因为:
- 它是幂等判断的基准("这条 issue 我是不是已经回复过");
- 它是"真人参与讨论"护栏的排除依据(评论者是不是我自己/机器人)。
坑在这里:填 name 不会报错,但会静默失效——你上一轮发的评论会被系统当成"陌生人参与讨论",结果是一条 issue 都关不掉。脚本内置了防呆:whoami 会在你填了昵称时报告 agent_login_matches: false,写操作漏填时向 stderr 告警。
所以:把 login 的值记下来,用它作为 --agent-login。
第 6 步:单条干跑(dry-run)
这一步同样不写任何东西,但它会打印"如果真跑,我打算做什么"。
从第 3 步的 report.md 里挑一条 CLOSE 的 issue,先干跑:
python scripts/gitcode_issue.py --owner <owner> --repo <repo> --token <token> \
--agent-login <login> process 146 --dry-run
仔细看输出:判定理由、命中信号、护栏结论、将执行的回复话术、将执行的关闭动作。确认无误再进行下一步。
第 7 步:正式关闭一条(看它怎么保证不出错)
python scripts/gitcode_issue.py --owner <owner> --repo <repo> --token <token> \
--agent-login <login> process 146
process 的执行顺序是固定不可颠倒的,任一步失败即中止:
- 重读 issue;已关闭 → 跳过(幂等)
- 载入评论;固定话术已存在 → 跳过回复(幂等)
- 重跑安全护栏;被否决 → 退出码 5 拒绝(除非人工显式
--force) - 发布固定话术:
感谢您的支持,欢迎进一步使用交流 - 重新拉取评论,确认回复已落库;缺失 → 退出码 6 中止,不关闭
- 关闭 issue,回读确认
state == closed;仍是打开 → 退出码 6
第 5、6 步就是写后回读(read-after-write verification):API 返回 200 不代表真的落库,所以每一步写完都重新读一次远端状态。这也是它为什么"慢一点但可靠"。
跑完去网页上看一眼那条 issue:应该有一条回复 + 状态已关闭。
第 8 步:批量处理
确认单条没问题后,批量跑:
python scripts/gitcode_issue.py --owner <owner> --repo <repo> --token <token> \
--agent-login <login> batch 146,147,151 --delay 2
batch 的三个特性:
- 自适应限流:识别 429 后自动退避、自我降速,无需你干预;
- 幂等可重跑:中途失败的项目独立报告,用相同参数重跑即可——已关闭的跳过,已回复的只补关闭;
--delay:每条之间的间隔秒数,仓库大时可以调大一点,跑得更稳。
第 9 步:读报告 / 排错
退出码是语义化的契约,看码就知道怎么处理:
| 退出码 | 含义 | 你该做什么 |
|---|---|---|
0 |
成功 | 继续 |
1 |
网络错误 | 检查网络;429/5xx 已内置重试 |
2 |
参数缺失 | 补 --owner / --repo 等 |
3 |
鉴权失败 | 令牌无效或 scope 不够,重开令牌 |
4 |
资源不存在 | owner/repo/issue 号写错,核对路径 |
5 |
护栏拒绝 | 正常保护行为,转人工,别硬关 |
6 |
写后验证失败 | 回复/关闭没落库,先查 issue 现状再重跑 |
常见现象对照:
- 一条都关不掉,全部 exit 5 且理由含
external_participant→ 大概率--agent-login填的是昵称而不是login,回第 5 步。 - 扫全库必然失败 → 429 限流,降低频率 / 用
--max分批。 - 只处理了 100 条就停了 → 分页没走全,改用
sweep.py或list --all。 - 机器人评论把 issue 卡成不可关 → 该账号不符合
_bot/-bot/[bot]命名约定,用GITCODE_BOT_LOGINS补上。
机器人识别是自动的:
_bot/-bot/[bot]后缀默认排除,不需要配置。这一点很重要——仓库自带的自动化账号(如grape_bot)会在每条 issue 上发分析评论,如果把它算成"真人参与讨论",就会一条都关不掉。
第 10 步:定制与收尾
换回复话术(默认契约是只用固定话术,改之前想清楚):
... process 146 --phrase "感谢反馈,此 issue 已归档"
--force 是危险开关:它绕过护栏。只能在人工明确决策后使用,并且必须在对话中留痕——不要把它放进自动化脚本。
分享前自查(确认没把凭据带出去):
# 期望:无任何输出
grep -rE '[0-9a-f]{32,}|[A-Za-z]:[\\/]Users[\\/]' gitcode-issue-triage/
# 期望:ALL TESTS PASSED
python gitcode-issue-triage/scripts/selftest.py
附录 A:判定规则速查
强信号(命中任一项即视为无价值)
- 正文为空或实质无内容(空白、单字符、填充符)
- 无意义重复字符、乱敲键盘、类 lorem ipsum
- 纯客套/夸奖无请求:支持一下 / 支持一波 / 支持开源 / 很好的项目
- 积分或任务刷量:拿个积分 / 为啥积分任务完不成 / 都是来拿积分的
- 与项目无关的通用提问:怎么安装 / 源码在哪 / how to install
- 广告、招聘、离题推广、拉联系方式
- 无描述裸链接、占位测试帖(issueTest / 测试)
- 与已有 issue 完全重复
- 维护者已打上 invalid / spam / duplicate 标签
否决信号(命中任一项即拒绝关闭,交人工)
- 命中护栏标签集(bug、defect、regression、security、requirement、feature、priority、blocker、p0/p1……)
- 已指派给真人,或挂在里程碑上
- 真人(非报告者、非机器人)有实质回复——存在进行中的讨论
- 请求式表述且带领域实质:
是否支持…/缺少 xxx/增加 xxx,或出现项目文件名、模块名、技术术语 - 含堆栈、错误码、版本号、复现步骤
- 报告数据丢失、安全问题或崩溃
- 由维护者或组织成员提交
最重要的一条否决是"请求式表述 + 领域实质",它拦住的是"短但合法"的真实请求:
#142 是否支持 docker 部署 → 必须保留
#133 缺少 requirements.txt → 必须保留
#48 增加输出格式 → 必须保留
护栏要求领域实质(项目相关词汇或文件引用)才把请求式表述当作真实请求,这样裸愿望(如果支持apk就好了)和刷量话术(能不能拿积分)就不会借"支持/能不能"这几个字获得合法性。
必须读正文,不能只看标题——这是实测踩出来的坑:
#75 Title: 支持一下 Body: 能否增加支持更多的agent → 真实需求,保留
#120 Title: 支持开源 Body: 建议补充…中文文档说明 → 真实需求,保留
标题精确命中"纯夸奖"模式,只看标题的分类器一定会误关。这类"垃圾标题 + 真实正文"在手工实测中出现了 2 次,全部被保住。
附录 B:为什么这么设计(保守自动化)
维护者的 issue 区是公开记录。所以第一原则不是"关得干净",而是宁漏勿错:
漏关一个无价值 issue 成本很低;误关一个真实缺陷报告,损害信任,还可能掩盖线上事故。
三条硬规则:
| 规则 | 含义 |
|---|---|
| 证据不足即放行 | 判定有分歧就归 needs human,不做任何写操作 |
| 顺序不可颠倒 | 先回复 → 回读确认 → 才关闭 → 再回读确认 |
| 护栏可一票否决 | 命中任何 veto 信号直接拒绝关闭 |
实测数据(真实 GitCode 社区仓库校准,不是纸面推演):
| 指标 | 结果 |
|---|---|
| 仓库开启 issue 总数 | 128 条 |
| 判定为无价值 | 68 条(灌水类是主流量,不是边缘情况) |
| 保留 | 60 条 |
| 歧义转人工 | 0 条 |
| 离线自测 | 113 项全部通过,零网络依赖 |
实测中修复的、只靠单元测试无法暴露的真实缺陷:assignees[] 字段形态不兼容导致"已指派"护栏完全失效;429 限流未处理导致扫全库必然失败;list 不翻页导致 142 条只取到 100 条;机器人评论被误判为真人参与导致一条都关不掉。
附录 C:GitCode API 踩坑清单(二次开发 / 排错必读)
这些是官方文档里查不到、只能实测得到的:
- v5 可用,v4 不可信。 旧 v4 层在某些路径返回 HTML 而非 JSON,分页还会丢数据。直接用
https://api.gitcode.com/api/v5。 - 读取无需令牌,写入才需要。 公开仓库的
list/show/comments/labels匿名可用;whoami、发评论、关闭 issue、仓库元数据与权限查询返回 401。 login≠name。 见第 5 步。填错静默失效。- 报文与文档不符。 文档
assignee: {...},实测是assignees: []且assignee键不存在;文档milestone: int,实测该键不存在;state有open/opened/closed/close多种形态,统一小写比较。 issue_state是陷阱。 它可能和state: "open"同时出现,且值可能是中文(如"待办的")。只有state决定开/关。- 限流 50 次/分钟,账号+IP 全局。 需自适应退避。
- 分页上限 100。 必须翻页。
- 写接口有兼容性坑。 发评论的 POST 某些部署拒绝 JSON、要求表单编码(脚本先试 JSON、失败回退
application/x-www-form-urlencoded);关闭的 PATCH 路径也有变体(closedvsclose、repo 在路径还是表单),脚本按 3 种形态依次尝试,每次尝试后都回读验证。 - 机器人账号自动识别。
_bot/-bot/[bot]后缀默认排除。
常见问题(FAQ)
Q:它会误关我的真实 issue 吗? 设计上以"宁可漏关"为准。命中任何否决信号(尤其"请求式表述 + 领域实质")就直接拒绝,转人工。想先看效果,全程用 --dry-run。
Q:机器人评论会让它一条都关不掉吗? 不会。_bot / -bot / [bot] 后缀自动识别并排除,无需配置。不遵循该约定的账号用 GITCODE_BOT_LOGINS 补上。
Q:跑一半被限流了怎么办? batch 会识别 429 并自适应退避,无需干预;中途失败的项目独立报告,用相同参数重跑即可。
Q:能改成别的回复话术吗? process 支持 --phrase 覆盖,但默认契约是"只用固定话术",改之前请确认这是你要的。
Q:为什么只关了 68 条,剩下的呢? 剩下 60 条要么命中护栏,要么是真实技术请求。这正是设计目标:只清噪声,不碰真问题。
Q:能处理 GitHub / Gitee 吗? 不能。GitHub 用 gh,Gitee 需另建。本 Skill 仅支持 GitCode。
结语
这个项目最值得学的,不是它"关掉了 68 条 issue",而是它把"不敢自动关"这件事工程化了:用护栏一票否决、用退出码表达语义、用写后回读保证一致、用幂等保证可重跑。
在一个"AI Agent 什么都能自动做"的年份里,一个明确写下"什么不做"、并把"不做"实现成硬约束的项目,反而更值得上手。
现在你可以回到第 3 步,用 --dry-run 先看看自己的仓库会被怎么判定。
参考资料:项目 README、scripts/sweep.py、references/triage-rubric.md、references/gitcode-api.md(所有计数与报文均为项目内可复现实测值)。
- 点赞
- 收藏
- 关注作者
评论(0)