OpenShell 社区 Issue 分流实战指南：triage-issue 技能的状态机、七步工作流与人工决策边界

导读

本文讲解 OpenShell 仓库内置的贡献者技能triage-issue（位于 .agents/skills/triage-issue/SKILL.md）：它是一套面向 Agent 的社区 Issue 评估与分流工作流，负责把用户提交的 issue 转化为“事实充分、等待人工处置”的state:validated状态，同时严格把路线图（roadmap）排期、接受与否等决策留给维护者。读完本文，你将掌握该技能的调用方式、七个核心步骤、十一类分类标准、state:*状态机与agent:*委托标签的完整语义，并了解它与create-spike、build-from-issue等下游技能如何串联成端到端管道。

背景：OpenShell 的 agent-first 协作模型

OpenShell 是一个为自主 AI Agent 提供安全、私有运行时的开源项目。其贡献流程同样贯彻“agent-first”理念：Agent 负责调查、验证、规划与实现，人类负责产品决策与路线图。CONTRIBUTING.md 开篇即声明“OpenShell is built agent-first”，并围绕这一理念把贡献工作拆分为“技术评估、产品处置、路线图排期、代理委托”四个互不混淆的层次。

在 AGENTS.md 中，项目把技能划分为两套：

• skills/：面向用户的公共、可安装技能（如 openshell-cli、debug-inference、debug-openshell-cluster），必须在源码检出之外也能工作，以已安装 CLI 帮助与已发布文档为准。
• .agents/skills/：面向贡献者与维护者的内部工作流，triage-issue即属于此集合，由仓库感知的 Agent 运行时原生加载。

triage-issue 的定位：只建立事实，不做产品决策

triage-issue的核心使命非常明确：为人类决策者建立“OpenShell 是否应该处理该 issue、以及它属于路线图的哪个位置”所需的事实。技能文档反复强调三件事它不做：

• 不授权工作、不排期、不产出实现计划（那是build-from-issue的职责）；
• 不决定技术上有效的工作是否该投入；
• 不把“技术有效性”当作“产品接受”。

换言之，分流（triage）是评估层（assessment layer），它只回答“报告是否真实、证据是否充分、影响有多大”，然后停下，等待人类给出是/否与排期结论。

前置条件

运行该技能前需要确认：

1. ghCLI 已认证（gh auth status）；
2. 当前位于带有 GitHub remote 的 git 仓库中；
3. 工作流标签state:validated、state:accepted、state:needs-info必须已存在。若缺失，应向操作者报告，不得隐式创建。

关键约束：处置与路线图排期只能由人完成

技能文档专门设置了“Critical: Disposition and Roadmap Placement Are Human-Only”一节。执行分流时，Agent 必须遵守以下红线：

• 不得决定 OpenShell 是否应在其他有效工作上投入；
• 不得应用或移除state:accepted；
• 不得把 issue 加入路线图项目、不得应用或移除roadmap标签，也不得推荐具体路线图条目；
• 不得应用agent:plan-requested或agent:implementation-requested；
• 不得把技术有效性等同于产品接受。

OpenShell没有priority:*优先级标签。排期完全来自 issue 与 OpenShell 路线图条目的关联，而这种关联是维护者的专属决策。CONTRIBUTING.md 的“Issue Lifecycle, Roadmap, and Agent Work”一节用一张决策表总结了分工：

state:validated表示“事实评估已完成、等待人类处置”，不等于项目已接受该工作。维护者用state:accepted或路线图放置来发出接受信号；路线图放置额外携带排期信息，但不指派所有者。

状态机与 agent 委托标签

CONTRIBUTING.md 定义了四个生命周期状态：

state:stale只是非活跃标记，不是生命周期决策：已接受、待人工处置的 issue 豁免于 stale 处理，而state:needs-info若无新证据则可能变 stale。

agent:*标签用于维护者把工作排队给持续运行的无人值守 Agent：

标准的委托链路是state:accepted（或路线图放置）→agent:plan-requested→agent:plan-ready→agent:implementation-requested→agent:in-progress→agent:pr-opened。规划授权不等于实现授权：agent:plan-requested只授权取走规划，agent:implementation-requested才确认人类已评审计划并授权实现。Agent 永远不得应用这两个请求标签。

一个重要的例外：用户直接指示 Agent 处理某个具体 issue 时，该指示本身即授权所请求的阶段，即使 issue 缺少预期的生命周期或工作流标签。此时 Agent 应警告缺失的标签，然后继续工作，但不得擅自修改这些标签。

评论标记：区分 Agent 与人类评论

该技能发布的所有评论必须以以下标记行开头：

> **📋 triage-agent**

该标记用于把分流评论与人类评论以及其他技能（如🏗️ build-from-issue-agent、🔒 security-review-agent等）区分开，也用于 Step 2 的“是否已分流”检测。

调用模式

该技能支持两种调用模式。

单 issue 模式

triage issue 250 triage issue #250

给定 issue 编号，直接进入 Step 1 开始评估。

批量模式

triage issues

批量模式在处理前必须经过确认门禁，防止对公共仓库造成意外的大规模评论。

Step 1：预览。查询所有匹配的 issue 并显示摘要：

gh issue list --label "state:triage-needed" --state open --json number,title --jq '.[] | "#\(.number) \(.title)"'

把结果呈现给用户（最多展示 10 条，超出显示 “and N more”），并提示“这将在每个 issue 上发布分流评论”。

Step 2：确认。使用AskUserQuestion向用户索要明确确认，选项为 “Proceed with all N issues”、“Let me pick specific issues”，并允许自定义输入。未获确认不得继续。

Step 3：处理。仅在确认后，对每个 issue 运行完整的七步工作流，最后报告每一条 issue 及其分类的摘要。

七步分流工作流

Step 1：获取 Issue

去掉 issue 编号前导的#，然后获取完整内容：

gh issue view <id> --json title,body,state,labels,author,comments

若该 issue 已关闭，直接报告并停止。

Step 2：检查是否已分流

在 issue 评论中搜索分流标记> **📋 triage-agent**：

• 若找到标记且其后没有携带新信息或新问题的人类评论：报告“该 issue 已被分流”并停止。
• 若找到标记但有更新的、包含额外信息的人类评论：进入 Step 3，基于新上下文重新评估。
• 若人类已拒绝该 issue、应用了state:accepted或已将其放入路线图：不得撤销或重新解释该决策。
• 若未找到标记：进入 Step 3。

Step 3：检查报告完整性

检查是否包含实质性的 User Story、Problem Statement、Impact / Why This Matters 与 Acceptance Criteria。Impact 应解释当前行为的后果以及现有 workaround 为何不足。Bug 报告还需复现步骤与相关环境；功能请求需检查 Proposed Design 与 Alternatives Considered。报告者提供的诊断与 Agent 输出是可选项，不得作为准入门禁。

• 若所需章节缺失关键信息：归类为needs-information，只请求缺失的确切信息，移除state:triage-needed并添加state:needs-info。
• 若公共 issue 可能披露安全漏洞：不得复述或展开敏感细节，归类为security-report，引导操作者阅读 SECURITY.md。
• 使用类问题与支持请求：转介到文档化的支持渠道。
• 明确的重复、错误仓库报告与客观上的预期行为：无需完整技术调查即可处理。

报告需要技术验证时，进入 Step 4。

Step 4：核对报告版本与已知修复

在深入诊断前，先判断报告是否可能已被较新版本修复：

1. 从 issue 正文、环境章节、日志与评论中提取报告的 OpenShell 版本；若未提供，记录为缺失上下文并继续。
2. 在可用时核对当前发布信息与已知修复：
   • gh release list --limit 10
   • gh release view <tag>
   • 关联 issue、已合并 PR、发布说明、本地 git 标签/历史，以及开放与关闭状态的潜在重复
3. 若网络访问或发布元数据不可用：在分流评论中说明该限制，而不是猜测。

若 issue 针对旧版本、而较新版本或已合并 PR 看起来解决了相同行为：

• 若报告者已在修复/当前版本上复现：继续 Step 5。
• 若报告者尚未在修复/当前版本上测试：在采用fixed-in-release前必须找到具体的修复变更；若因果联系不确定，请请求重测，而不是宣告已修复。

Step 5：诊断与验证

通过 Task 工具调用principal-engineer-reviewer子代理评估报告，向其提供：

• 完整 issue 标题与正文；
• 以怀疑视角评估的指令，包含 10 个问题：
  1. 用户故事确立了怎样的人物画像与期望能力？
  2. 问题陈述是否与当前产品行为一致？
  3. Impact 是否解释了后果、当前 workaround 及其为何不足？
  4. 验收标准是否具体、可观察、与用户故事一致？
  5. 描述的工作流能否从给定信息复现或以其他方式验证？
  6. 当前产品是否支持所请求的结果，哪个组件拥有该行为？
  7. 该报告最适合归类为 bug、功能请求、支持请求还是其他类别？
  8. 若是功能请求，提议的设计在技术上是否自洽且可行？（不要决定项目是否应接受它）
  9. 是否存在开放或已关闭的重复 issue？
  10. 仍有怎样的不确定性，哪些确切证据可以消除它？

基于子代理的分析，还要直接尝试验证报告：

• Bug 报告：检查相关代码路径，寻找所述失败模式；
• 功能请求：对照现有架构评估可行性；
• 网关部署或基础设施问题：参考 skills/debug-openshell-cluster/SKILL.md 中的已知失败模式；
• 推理与 provider 拓扑问题：参考 skills/debug-inference/SKILL.md；
• CLI/使用问题：参考 skills/openshell-cli/SKILL.md 中的工作流，并用openshell --help确认已安装语法。

最后，为人类决策记录影响信号：受影响用户与范围、回归状态、workaround 可用性、严重性证据、证据质量。不要把这些事实转换为路线图或排期建议。

Step 6：分类

根据调查结果，把 issue 归入以下十一类之一：

两个明确的禁止项：不得用validated-feature暗示路线图接受；不得用expected-behavior拒绝技术上有效的功能请求。

Step 7：发布分流评论

发布带有分流标记的结构化评论：

> **📋 triage-agent** > > ## Triage Assessment > > **Classification:** <validated-bug | validated-feature | needs-investigation> > > ### Summary > <What was established and confidence in the evidence.> > > ### Investigation > <Reproduction results, code/release evidence, affected components, and duplicates.> > > ### Impact Signals > - **Affected users/scope:** <facts or unknown> > - **Regression:** <yes/no/unknown> > - **Workaround:** <available/unavailable/unknown> > - **Evidence quality:** <high/medium/low with reason> > > ### Human Decision Required > Decide whether OpenShell should address this issue. If yes, apply > `state:accepted`, associate it with a roadmap item, or do both, and decide > whether the work remains human-owned. Either action records acceptance; > roadmap placement additionally records sequencing. > To queue investigation or planning for an unattended agent, also apply > `agent:plan-requested`. You can instead directly ask an agent to use > `create-spike` or `build-from-issue` on this issue; the agent will warn about > missing expected workflow labels and continue without changing them. If no, > close it as not planned and record the rationale.

对其他结果（如needs-information、fixed-in-release、duplicate等），把影响与决策部分替换为确切的信息请求、客观的解决方案或安全转介指引。

分流期间的状态规则

• 在state:triage-needed、state:needs-info、state:validated中恰好保持一个入站/分流状态；
• 每次评估完成后移除state:triage-needed；
• 分流期间永不应用state:accepted、任何agent:*标签或roadmap标签；
• 永不关闭已通过验证的 issue。

与其他技能的关系：端到端管道

triage-issue是社区贡献管道的第一环。技能文档给出了完整的关系图：

Community issue filed | [GitHub Action: instant gate check] | triage-issue | state:validated | human decline OR state:accepted / roadmap placement | create-spike (if deeper investigation is approved) | human queues planning with agent:plan-requested OR directly requests planning | build-from-issue (creates implementation plan) | human queues implementation with agent:implementation-requested OR directly requests implementation | implementation

各技能的分工是：

• triage-issue建立技术有效性与影响证据；
• 人类决定是否接受有效工作以及它落在路线图的什么位置；
• create-spike（见 .agents/skills/create-spike/SKILL.md）只有在投入调查获得批准后深化调查，把模糊问题映射为结构化、可构建的 issue，并在证据充分时标记state:validated、否则标记state:needs-info——它同样永不添加state:accepted、agent:*或roadmap标签；
• build-from-issue可在特定 issue 上被直接调用；无人值守 Agent 用agent:plan-requested取走规划、用agent:implementation-requested取走实现。

AGENTS.md 还列出了项目内的其他工作流链，与分流管道形成对照：内部开发链为create-spike→ 人工处置 →build-from-issue；安全链为review-security-issue→fix-security-issue（通用构建 Agent 不得处理topic:security的 issue，安全 issue 按 SECURITY.md 走私有流程）；策略迭代链为openshell-cli→generate-sandbox-policy。

从源码结构看该工作流的可执行性

从仓库结构可以确认，triage-issue引用的全部支撑材料在仓库中真实存在并保持同步：

• 状态机与决策分工的权威定义位于 CONTRIBUTING.md 的 “Issue Lifecycle, Roadmap, and Agent Work” 章节，其中“谁执行哪项动作”的对照表与技能文档的红线完全一致；
• AGENTS.md 作为注入给 Agent 的指令表面，把triage-issue明确列为 “Community inflow” 管道的起点，并规定“issue triage 只确立技术有效性与影响证据，Agent 永不决定接受、应用state:accepted、把 issue 放上路线图或应用agent:*请求标签”；
• 技能引用的三个公共诊断技能——openshell-cli、debug-inference、debug-openshell-cluster——均位于skills/目录，供 Step 5 按问题类型（CLI、推理/provider 拓扑、网关部署）分流参考；
• 下游的create-spike技能与本技能共用同一套状态语义与标签红线，保证管道各环对state:*与agent:*的理解一致。

这套设计把“谁调查、谁验证、谁接受、谁排期、谁实现”彻底解耦：分流 Agent 是事实调查者，维护者是人类决策者，agent:*标签与直接用户指令是委托通道。任何一环都不能越权替代另一环。

小结：为什么这套分流机制值得借鉴

triage-issue的价值在于用机制而不是信任来约束 Agent：评论标记保证可审计、批量模式用确认门禁保护公共仓库、state:*状态机让所有贡献者对 issue 所处阶段一目了然、agent:*标签为无人值守 Agent 提供安全的队列拾取语义，而“技术有效 ≠ 产品接受”的红线保证了机器判断永远无法替人类拍板路线图。对 OpenShell 社区而言，这意味着每个新 issue 都能以一致、可追溯、证据充分的方式进入评估流程；对构建类似 agent-first 协作流程的团队而言，这套“评估层/处置层/排期层/委托层”分离的模型本身就是一份可复制的设计范本。