为什么需要标签驱动开发？
一个 Issue 从提出到合并，常常要经过问题判断、方案设计、代码实现、审查和 CI 验证。如果这些动作散落在评论、聊天记录与不同的自动化任务里，我们很难回答一个简单的问题：现在卡在哪一步，下一步该由谁做？
让 Issue 成为流程入口，用标签标明当前阶段、执行主体与阻塞原因。AI 可以承担问题初审、方案拟定和编码等工作；JEV 模型负责阶段性的判断；人在不确定、高风险或需要业务决策的节点介入。标签不是为了让机器人看起来忙碌，而是要让任何人打开 Issue，都能知道当前状态、下一步动作和停下来的原因。
如何实现问题+标签驱动开发
1. 标签设计
标签分成三类：状态标签、动作标签、元数据标签
状态标签、动作标签为机器与人服务，应当实现自动流转；元数据标签仅为人服务，自主添加。状态标签流转的三种情况：新问题创建时、移除动作标签后没有动作标签、动作标签导致的异常状态。动作标签创建依赖状态标签流转触发的工作流。
为了方便管理可以使用颜色/前缀名的方式管理标签类型
- 状态标签：红色/state:---
- 动作标签：绿色/action:---
- 元数据标签：蓝色
2. 最小标签列表
最小实现包含六个状态标签，其中五个正常状态、一个异常暂停状态、两个动作标签。以 Issue 作为流程主记录，关联 PR 承载代码变更、审查与合并结果。
2.1 状态标签
状态标签表示问题当前所处的阶段。一个尚未关闭的 Issue，在稳定状态下应当且仅有一个状态标签。
正常流转顺序：
state:needs-triage → state:assess-plan → state:coding → state:code-review → state:wait-auto-merge
状态标签
- state:needs-triage：需求待评审。主要判断需求是否清晰、是否有必要处理。
- state:assess-plan：制作方案。提出实现方案及对应的验证方式。
- state:coding：编码实现。按照确认后的需求和方案完成代码修改、测试与验证，创建或更新关联 PR，并记录实现结果。
- state:code-review：代码待审查。检查实现是否满足需求、符合方案，测试是否充分，以及是否存在缺陷和风险。通过后进入待合并阶段；需要修改时退回编码。
- state:wait-auto-merge：等待自动合并。跟进必要检查、审查要求及合并条件，处理阻塞。只有关联 PR 实际合并后，才结束流程。
- state:agent-failed：自动执行异常暂停。Agent 执行失败或任务分配超时后进入此状态，停止自动重试和重新分配，减少无效请求。
前五个阶段均可由 Agent 或人独立完成，由 Jev 分配执行方。state:agent-failed 不属于正常推进顺序，是异常时进入的暂停分支。
2.2 动作标签
动作标签表示当前阶段的待办由谁负责，不与某个状态固定绑定。
- action:human：当前待办分配给人，等待人工完成。
- action:agent：当前待办分配给 Agent，等待 Agent 完成。
同一个状态可以分配给任意一方。例如，state:code-review 可以搭配 action:agent，也可以搭配 action:human，具体由 Jev 根据任务上下文与分配规则判断。
最小实现中，一次待办分配给一个执行方即可，不默认要求双方都参与或依次审批。只有确实拆分出两方独立待办时，才同时保留两个动作标签，并等待各自完成。
2.3 元数据标签
元数据标签按需人工添加，不参与流转判断。
3. 最小标签流转自动化
自动化分为两部分：状态标签的生命周期管理、动作标签的生命周期管理。状态表示当前阶段，动作表示该阶段由谁处理。
3.1 状态标签的生命周期管理
- 初始化：新 Issue 创建时，设置 state:needs-triage，进入需求评审阶段。
- 流转：当前阶段的动作全部完成后，进入下一阶段。切换时替换原状态标签，保持当前状态唯一。
- 异常：Agent 执行失败或任务分配超时后，设置 state:agent-failed，暂停自动推进与重复请求，等待处理后恢复。
正常流转顺序：
state:needs-triage → state:assess-plan → state:coding → state:code-review → state:wait-auto-merge
3.2 动作标签的生命周期管理
- 判定：进入一个正常状态后，由 Jev 根据当前阶段与任务上下文，判定由 Agent 还是人处理。各阶段不固定绑定执行者。
- 触发：根据分配结果添加 action:agent 或 action:human，触发对应的执行或通知流程。
- 删除：执行方完成任务并记录结果后，移除对应动作标签。如果没有剩余动作标签，则触发状态流转判断。
状态变化触发动作分配，动作完成触发状态判断，两者共同构成自动化闭环。state:agent-failed 作为暂停状态，不进入正常的自动分配循环。
4. 标签驱动模板
可以使用 Juejin 模板，将其中的 .github/ 目录放入自己的项目，并提交到默认分支。模板分为三个部分，也可以按需分别接入。
4.1 创建标签
.github/label.yaml 定义标签名称、颜色和描述，sync_labels.py 负责同步，sync-labels.yml 提供手动运行入口。
配置完成后，在 GitHub 点击 Actions → Sync labels → Run workflow，即可创建或更新仓库标签。以后修改标签配置，再运行一次即可；手工维护的元数据标签会保留。
4.2 管理状态标签
state-control.yaml 和 advance_issue_state.py 负责状态流转：新建 Issue 时添加初始状态，当前阶段的动作全部完成后推进到下一阶段，遇到 state:agent-failed 时暂停。
正常阶段按标签配置中的顺序推进。状态切换完成后，会直接调用动作评审，因此也需要配齐下面的动作管理配置。
4.3 管理动作标签
动作管理需要配置三个方面：
- 评审模型 ：在仓库的 Actions Secrets 中添加
TYPESAFE_API_KEY，让 TypeSafe Jev 负责阶段判断。 - 能力与提示词 ：
action-policy.yaml描述可用 Agent 的模型和能力；state-review.yaml定义通用规则及各阶段的专属提示词。 - 执行 Agent ：按照
agent-action-protocol.md接入任务执行器，负责发现任务、执行阶段工作和反馈结果。
action-control.yaml 响应新增状态标签，调用评审脚本。Jev 根据 Issue 描述、评论和阶段提示词，判断是否需要更强模型。当前模板将常规模型足够映射为 action:agent，需要升级映射为 action:human，交给升级处理方接管。
模板负责状态管理和任务分配，执行 Agent 需要另外介入。 执行成功后，先记录结果，再移除动作标签；执行失败时，按协议切换到 state:agent-failed。完成这部分接入后，整个流程才形成闭环。
最佳实践
自动化动作标签极其沉重，优先配置管理状态标签自动化+评审模型配置，手动分配Agent接管任务。