跳到主要内容

议题管理

议题（Issue）是你与 Agent 协作的核心入口。通过创建议题并绑定 Workflow 模板，你可以将开发需求交给 Agent 自动处理。

议题生命周期​

一个议题（Issue）有 9 种状态，遵循以下状态机：

状态说明
draft刚创建（草稿），等待启动自动化
planned已规划，planner/Workflow 已分析并准备拆分任务
in_progress进行中，Workflow 映射出的 Task 正在执行
review_pending待审查，等待 reviewer 评审
changes_requested要求修改，人工或 reviewer 反馈后回到 planned 重新处理
approved已通过审查
completed已完成，所有 Task 执行完毕
archived已归档
error错误，未绑定 Workflow、模板缺失、运行前校验失败，或重试超过上限

典型成功路径：

draft -> planned -> in_progress -> completed

异常或人工反馈路径：

changes_requested -> planned -> in_progress -> completed
planned -> error
in_progress -> changes_requested

Issue 完成由依赖调度器根据所有 Task 的状态判定：当所有 Task 都为 done 时，Issue 被标记为 completed。

创建议题​

  1. 在工作空间中打开议题面板
  2. 点击「新建议题」
  3. 填写标题和描述
  4. 选择 Workflow 模板（必选，否则 Issue 无法自动执行）

写好描述的技巧：

  • 明确说明需求目标和期望结果
  • 提供必要的上下文信息
  • 如果涉及特定文件或模块，直接说明
  • 如果有参考代码或设计稿，附上链接

Workflow 驱动的任务分解​

议题启动自动化后，系统会：

  1. 加载选定的 Workflow 模板
  2. 将 Workflow 中的 Agent 节点映射为可执行的 Task（每节点 → 一 Task）
  3. 节点的入边作为 Task 的 dependsOnTaskIds 依赖
  4. 调度执行：只有所有前置 Task 都为 done 时，Task 才会启动
  5. 所有 Task 完成后 Issue 标记为 completed

注意：当前同一轮可运行的 Task 按数组顺序串行执行，DAG 表达依赖关系，但同层不会真正并行运行多个 Agent。

Task 状态​

每个 Task 有 8 种状态：

状态说明
pending待执行
running正在执行
reviewing正在被 reviewer 审查
waiting_review等待审查
retrying重试中
done已完成
failed失败
cancelled已取消

每个 Task 包含：

  • 绑定的 Agent 预设（agentConfigId）与运行时实际分配的 Agent session（assignedAgentId）
  • 执行状态、重试计数（retryCount / maxRetries）
  • 依赖关系（dependsOnTaskIds）
  • 工具调用记录、代码变更（diff）与执行日志

详见 Workflow 编辑器。

议题评论​

在议题详情页可以添加评论，支持富文本格式。评论用于：

  • 补充需求信息
  • 与 Agent 交互讨论
  • 记录决策和变更

失败重试与恢复​

Task 和 Issue 都有独立的重试计数：Task 有 retryCount / maxRetries，Issue 有 retryCount / maxRetries / retryPaused。

Task 失败重试​

Agent 执行失败时：

  • retryCount < maxRetries：Task 重置为 pending 并重新调度
  • retryCount >= maxRetries：Task 保持 failed，并设置 Issue 错误信息

Issue 错误与自动重试​

Issue 进入 error 后，后台调度器会在后续 tick 中通过 error issue retry service 处理：

  • retryCount < maxRetries：将失败的 Task 重置为 pending，Issue 切回 in_progress，继续调度
  • retryCount >= maxRetries：设置 retryPaused = true，停止自动重试

手动恢复​

  • 后端：POST /api/workspaces/:workspaceId/issues/:issueId/resume
  • 前端：Issue 详情页在 error 状态显示 Resume failed tasks 按钮
  • 单个 failed Task 也可单独重试，后端会将其恢复为 pending 并立即重新调度

服务器启动恢复​

服务器启动时会执行恢复流程（issue-retry.ts）：

  1. 所有状态为 running 或 retrying 的 Task 被标记为 failed
  2. 所有状态为 in_progress 的 Issue 被切换为 error
  3. 后续由调度器的 error issue retry service 继续自动恢复，超过最大重试次数后暂停

替代方式：频道聊天​

除了通过 Issue + Workflow 自动编排外，你也可以在频道聊天中 @mention Agent 直接触发执行，适合快速下达指令。