Codewhale Issue Triage 实操指南基于 needs-info 生命周期的过期清理策略与 gh 命令工作流【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale在 Codewhale 这种由 Rust 编写、面向终端与 Agent 协作的开源编码代理项目中Issue 队列既承载用户反馈也是新 Agent 与贡献者上手的主要入口。为了把队列收敛到一个刚启动的 Agent 无需额外上下文即可直接执行的状态仓库以 docs/ISSUE_TRIAGE.md 为核心维护文档定义了一套与needs-info过期状态机并行的 stale过期清理生命周期包括标签体系、受保护标签、动手前的 dry-run 查询以及首次人工清理的判据。读完本文你将掌握如何用ghCLI 安全地识别等待报告者补充信息的陈旧 Issue、在保护 release/security/里程碑工作的前提下执行清理并理解该策略如何与仓库内docs/skills/中一套 agent-ready 的 Issue 维护技能互相衔接。一、策略定位一切向 agent-ready Issue 标准看齐文档开篇即点明Issue triage 的目标是把问题对齐到agent-ready issue standard——即一个全新的 Agent 无需额外上下文即可执行的 Issue 正文。这是 Codewhale 作为 Agent 项目对自身社区维护流程的反向要求既然 Agent 能消费 Issue那么 Issue 本身就要写得像可执行的规格说明而不是便签式的模糊抱怨。围绕这一标准仓库在 docs/skills/README.md 中把整套 GitHub 维护流程技能化为 SKILL.md 格式Claude Code 与 Codewhale 均可加载的通用技能格式其中明确写到这些技能编码了维护者每个 release 周期都要执行的issue-triage、PR-harvest、credit 与 release-QA 工作流。与 triage 直接相关的技能包括gh-file-issue/SKILL.md新建一个高质量、可执行的 Issuegh-compile-issues/SKILL.md把一批 Issue 编成带证据引用的覆盖矩阵coverage matrixgh-close-issues/SKILL.md验证修复落地后再关闭并给予 creditgh-assign-issues/SKILL.md批量调整 milestone 与负责人。而 docs/ISSUE_TRIAGE.md 讲的是这套标准中偏负向清理的一面当一个已标记needs-info的 Issue 长时间没有报告者反馈时如何安全地走过警告 → 关闭的生命周期。二、Staleneeds-info清理的运行边界只动维护者明确标记过的队列该清理策略最核心的设计约束是克制自动化的 stale 工作流只作用于维护者显式打过needs-info标签的 Issue绝不主动清扫未标记的队列。The stale workflow only acts on issues that a maintainer has explicitly labeled needs-info.这样做的意义在于旧的路线图roadmap、release、security 以及当前 milestone 的工作在维护者主动把某个 Issue 标记为等待报告者输入之前不会被任何自动清理机制波及。换句话说needs-info标签是一个显式的进入清理管道开关——由人按下机器才接手。这一约束与仓库中其他 Issue 维护文档一脉相承。例如 gh-file-issue/SKILL.md 明确规定严重性标签release-blocker只在真正阻塞下一个 release 时才允许打上而 gh-close-issues/SKILL.md 要求绝不能仅凭标题、标签或一个绿色的 PR 状态就关闭。整体维护哲学是标签与状态是人的决策信号自动化只在这条信号明确后才介入。三、标签体系必要标签与受保护标签要让 stale 生命周期运转文档定义了四个必要标签它们协同描述一个 Issue 在清理管道中的状态标签含义needs-info等待报告者补充信息或等待当前版本的复现细节stale处于不活跃状态的needs-infoIssue等待自动关闭keep-open受保护维护者有意保持其打开pinned受保护维护者置顶的 Issue其中stale是状态推进的标志——一个needs-infoIssue 长时间没有动静后被打上stale进入待自动关闭的观察窗口。与必要标签相对的是一组受保护标签。只要命中以下任意一个stale 清理就不得触碰该 Issuepinned keep-open release-blocker security文档特别强调了一条容易被误判的规则Abugissue is not protected just because it is a bug.即它是 bug本身并不构成保护。如果一个维护者已经把某个 bug 标记为needs-info且它没有携带上述任何受保护标签那么它同样符合 stale 警告与关闭的条件。保护只来自显式标签不来自 Issue 类型推断——这与 gh-compile-issues/SKILL.md 中绝不从标题或标签推断结论、必须逐条对照当前代码取证的纪律同源。四、动手前先查dry-run 查询三板斧文档强烈建议在修改 stale 策略或执行人工清理之前先跑 dry-run 查询。下面三组查询来自文档原文分别从三个视角圈定候选集合。需要先在 shell 里计算出两个截止日期STALE_CUTOFF$(python3 -c from datetime import date, timedelta; print(date.today() - timedelta(days45))) NEEDS_INFO_CUTOFF$(python3 -c from datetime import date, timedelta; print(date.today() - timedelta(days30)))两个阈值各有用意45 天用于判定整体陈旧30 天用于判定标记了 needs-info 后仍无反馈。计算日期时使用python3单行表达式保证每天执行结果都是相对今天滚动的无需手工改日期。查询一超过 45 天未更新的所有 open Issuegh issue list --repo Hmbown/CodeWhale --state open \ --search updated:${STALE_CUTOFF} \ --limit 100 \ --json number,title,updatedAt,labels,url这是最宽的候选集updated:45天前过滤出所有长时间没有动静的 open Issue。注意--json显式要求返回number,title,updatedAt,labels,url字段方便后续逐条评估——尤其updatedAt与labels是关闭判定的核心输入。查询二needs-info超 30 天未更新的 Issuegh issue list --repo Hmbown/CodeWhale --state open \ --search label:needs-info updated:${NEEDS_INFO_CUTOFF} \ --limit 100 \ --json number,title,updatedAt,labels,url这是自动化清理的直接输入集合label:needs-info保证只命中维护者显式标记过的 Issueupdated:30天前保证只命中长时间无反馈的。两个条件叠加正对应本文第二节所述进入清理管道的必要条件。查询三创建超 45 天且零评论、且无保护标签的 Issuegh issue list --repo Hmbown/CodeWhale --state open \ --search created:${STALE_CUTOFF} comments:0 -label:keep-open -label:release-blocker -label:security \ --limit 100 \ --json number,title,createdAt,updatedAt,labels,url这个查询通过-label:负号表示排除预先剔除了keep-open、release-blocker、security三类受保护对象专门筛高龄且无人讨论的孤儿 Issue。注以上命令中的--repo Hmbown/CodeWhale为文档与仓库维护脚本使用的远程仓库标识实际运行时请将其替换为你所维护的 CodeWhale 仓库地址可先export REPOowner/repo再用--repo $REPO引用。关闭判定基准updatedAt 而非 createdAt文档对判定依据给出了一句明确的经验法则UseupdatedAt, labels, and current release relevance as the closure basis. Creation date alone is too aggressive.即关闭决策应综合三条信息updatedAt最近活跃时间、标签、与当前 release 的相关性单看创建日期过于激进——一个创建很久的 Issue 可能最近仍在被讨论、或恰好属于当前 milestone仅凭年久就关闭会误伤活跃工作。这也是第三组查询仍然同时输出createdAt与updatedAt的原因创建时间只用于筛选候选决策时仍要看更新时间。五、首次人工清理First Cleanup Pass在依赖自动化之前先做一轮文档明确要求在依赖自动化之前必须由维护者手工执行一轮清理。这轮人工清理包含四条可操作规则老旧的未解决 bug先要复现细节再贴needs-info不要直接把一个无人问津的旧 bug 标记为needs-info而要先向报告者索要当前版本current-version的复现细节。这与整个仓库的取证文化一致——gh-compile-issues/SKILL.md 强调Issue 正文是不可信数据永远要对照当前代码验证一个没有当前版本还能不能复现结论的 bug 无法进入可执行的 agent-ready 标准。关闭明显的 GUI / VS Code / Web UI 重复 Issue并链接到规范 Issue桌面端与运行时相关的重复报告应被关闭但不能静默关闭——必须附上指向 canonical规范desktop/runtime Issue 的链接。这与 gh-close-issues/SKILL.md 中重复 Issue 要指向 canonical 条目而非悄悄关闭的处理方式完全一致。关闭已被 rebrand 工作取代的品牌讨论 Issue当 Codewhale rebrand 及 README/历史整理工作已覆盖某类品牌讨论时相关旧 Issue 应以 superseded已被取代为由关闭。保护或关闭 v0.9.0 路线图碎片对刻意保留的 v0.9.0 路线图分片roadmap shards要么用keep-open显式保护要么在它们已被某个 canonical epic 取代时以 superseded 关闭。规则的核心是路线图工作要么被显式保护要么被显式归并不能悬在中间地带任其腐烂。六、关闭边界什么绝不能由 stale 自动化关闭与该清理什么同样重要的是什么不能碰。文档以近乎禁令的口吻收尾Do not close release blockers, security issues, or active milestone work from stale automation alone.release blocker、security Issue、活跃的 milestone 工作 不得仅凭 stale 自动化单独关闭。结合前面的标签体系可以看到完整的保护逻辑release-blocker与security是受保护标签它们在 dry-run 查询阶段就被-label:排除keep-open与pinned则由维护者手工用于有意保持打开的场景如路线图碎片。这套设计把自动化的强项低成本的持续清扫与人的强项判断价值与风险的裁决分隔开自动化只处理已被维护者显式标记、且不携带任何保护信号的低风险 Issue。七、仓库配套佐证agent-ready 技能栈与审计工作流如何补全闭环ISSUE_TRIAGE.md描述的是 Issue 生命周期的清理段而仓库中的技能与工作流文件构成了完整的闭环——它们共享同一套纪律值得在理解 triage 时一并参照准入段怎么写gh-file-issue/SKILL.md 规定新建 Issue 必须具备命名差距而非情绪化描述、分节正文Why/Current/Desired/Repro/Acceptance/Related、可证伪的验收标准如cargo test -p tui passes并绝不打上不存在的标签或 milestone。这就是agent-ready在上游的落点。体检段怎么评估存量gh-compile-issues/SKILL.md 教你如何把一批 Issue 分类为already-done / quick-fix / design / defer每个结论都必须带path:line证据对 80 条的大型 milestone它建议用并行只读 Agent 分批处理每批约 10~12 条再合并成一张覆盖矩阵。收尾段怎么关闭gh-close-issues/SKILL.md 要求关闭前必须用git log、git branch --contains、git merge-tree验证修复确实落在你将要引用的真实分支上并给出path:line或 commit SHA 引用部分修复只留状态评论、不关闭关闭时必须感谢报告者并留下可 reopen 的口子。与 Issue 审计相关的自动化样例workflows/issue_audit.workflow.js 展示了一个声明式 JavaScript 工作流用三个并行、只读的 specialist Agentcode-audit / test-audit / docs-audit分别限定crates、tests、docs文件范围审计某个 Issue 修复再由一个 reduce 节点把专家结论汇总成 release-ready 风险摘要。它在 crates/tui/src/tools/workflow/mod.rs 中有对应的驱动测试declarative_issue_audit_fixture_runs_through_subagent_driver验证该声明式工作流可被降级为类型化 Workflow IR 并经 subagent driver 运行。虽然它审计的是修复质量而非清理陈旧队列但它示范了仓库中用并行 Agent 处理 Issue 批次的执行方式——这正是大规模 triage 时 [gh-compile-issues] 所建议的扩展手段也与 docs/FLEET_WORKFLOW_TUTORIAL.md、docs/WORKFLOW_AUTHORING.md后者将workflows/issue_audit.workflow.js列为当前示例描述的工作流体系一致。综上Codewhale 的 Issue triage 策略可以概括为一句话用needs-info作为显式入闸信号用受保护标签划出不可触碰的边界用 dry-run 查询保持每次清理的可审计性用人工首轮清理兜底最后才让 stale 自动化在低风险子集上持续运行。这套纪律既保护了 release、security 与里程碑工作不被误伤也让整个队列逐步收敛到新 Agent 拿起来就能执行的 agent-ready 标准——对一个以 Agent 为核心产品的开源项目而言这本身就是最自然、也最有说服力的自举式实践。【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考