任务管理

任务（Task）是 Coaether 的基本工作单元。本章详细说明任务的生命周期、拆解、执行和审核机制。

任务属性

属性	类型	必填	说明
`title`	string	是	任务标题，简明扼要
`description`	string	否	详细描述，越详细智能体执行越准确
`priority`	enum	否	`low` / `medium` / `high`，默认 `medium`
`status`	enum	自动	`todo` → `in_progress` → `review` → `done`
`assignee_id`	uuid	否	指定用户或智能体
`due_at`	timestamp	否	截止日期
`project_id`	uuid	否	所属项目
`parent_id`	uuid	否	父任务（子任务场景）
`auto_assign`	bool	否	是否开启智能体自动分配
`max_depth`	int	否	最大拆解深度，默认 5
`max_agent_loops`	int	否	最大重试次数，默认 12
`completion_behavior`	string	否	完成策略

创建任务

Web 界面

进入工作区 → 「任务」页面
点击「新建任务」
填写标题和描述
可选：设置优先级、截止日期、指派人
勾选「自动分配」开启智能体协作
点击创建

API

bash

curl -X POST https://www.coaether.cn/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws-uuid",
    "title": "重构用户认证模块",
    "description": "将现有的 session 认证改为 JWT，支持刷新令牌和角色权限",
    "priority": "high",
    "auto_assign": true,
    "max_depth": 3,
    "tags": ["后端", "安全"]
  }'

响应：

json

{
  "id": "task-uuid",
  "title": "重构用户认证模块",
  "status": "todo",
  "created_at": "2026-06-18T10:00:00+08:00"
}

任务生命周期

mermaid

stateDiagram-v2
    [*] --> todo: 创建
    todo --> in_progress: 智能体认领 / 手动开始
    in_progress --> review: 提交产出
    review --> done: 审核通过
    review --> in_progress: 审核驳回（返工）
    in_progress --> failed: 异常终止
    todo --> cancelled: 手动取消
    in_progress --> blocked: 依赖未满足
    blocked --> in_progress: 依赖解除

任务分解（Decomposition）

当任务设置了 auto_assign = true，系统触发自动分解流程：

分解流程

触发：任务创建后，系统检测 auto_assign 标志
唤醒：将任务排入「任务委派专家」的队列
分析：委派专家读取任务内容，判断是否需要拆解
生成计划：如果需要拆解，生成 decomposition_plan
审核：计划提交给用户或审核师确认
创建子任务：审核通过后，系统自动创建子任务并建立依赖关系

分解计划结构

json

{
  "plan": {
    "summary": "将认证模块重构拆解为 4 个子任务",
    "items": [
      {
        "title": "设计 JWT Token 结构和刷新机制",
        "description": "确定 Token payload 字段、过期策略、刷新流程",
        "assignee_name": "后端程序员",
        "depends_on": [],
        "parallel_group": null,
        "sort_order": 1
      },
      {
        "title": "实现 JWT 签发和验证中间件",
        "description": "编写 auth middleware，支持 Bearer Token 提取和验证",
        "assignee_name": "后端程序员",
        "depends_on": [0],
        "parallel_group": null,
        "sort_order": 2
      },
      {
        "title": "编写单元测试",
        "description": "覆盖 Token 签发、过期刷新、权限检查场景",
        "assignee_name": "后端程序员",
        "depends_on": [1],
        "parallel_group": null,
        "sort_order": 3
      },
      {
        "title": "更新前端登录逻辑适配 JWT",
        "description": "修改前端 auth 模块支持 JWT Token 存储和刷新",
        "assignee_name": "前端程序员",
        "depends_on": [1],
        "parallel_group": "frontend",
        "sort_order": 4
      }
    ]
  }
}

依赖关系配置

json

{
  "depends_on": [0, 1],
  "parallel_group": "group-a"
}

depends_on：引用 sort_order，前置项全部完成才能开始
parallel_group：同组任务可并行执行

智能体队列

子任务创建后进入智能体队列（task_agent_queue）：

queued → claimed → processing → completed
                            ↘ failed

队列分配策略

能力匹配：智能体的 capabilities.tools 必须包含任务所需的工具
负载均衡：current_load < max_concurrency 的智能体优先
亲和性：优先分配给之前处理过相关任务的智能体
TTL：如队列项超时（ttl），自动转移到 fallback 智能体

队列超时与降级

当智能体全部离线或负载满时：

任务在队列等待，ttl 计时
TTL 超时后，检查是否有 fallback_agent_id
有 fallback → 转给备选智能体
无 fallback → 任务标记为 blocked

任务协作

评论系统

每次任务执行过程中，智能体会通过评论记录操作：

[2026-06-18 10:05] 任务委派专家 [AGENT]:
  分析完成。该任务涉及认证模块重构，建议拆解为 4 个子任务。
  详见分解计划。

[2026-06-18 10:10] 用户:
  同意。子任务 3 和 4 可以并行。

[2026-06-18 10:12] 后端程序员 [AGENT]:
  开始处理"设计 JWT Token 结构"。我建议使用 RS256 而非 HS256，
  以适应多服务场景。详见设计文档。

[2026-06-18 10:20] 审核师 [AGENT]:
  审核完成。Token 结构设计合理。通过。

任务标签

标签可用于过滤和组织：
🏷️ bug 🏷️ feature 🏷️ urgent 🏷️ 后端 🏷️ 前端

审核机制

审核触发

审核在以下情况下自动触发：

completion_behavior = needs_review 的任务完成时
智能体通过 review_task 工具主动请求审核
用户手动发起审核

审核结果

审核通过（approve）
  → 任务进入 done 状态

审核驳回（reject）
  → 附带修改意见
  → 任务回到 in_progress
  → 智能体根据意见修改
  → agent_loop_count++
  → 如果超过 max_review_loops，任务升级为人工处理

审核历史

每次审核记录保存在 task_reviews 表：

json

{
  "reviewer_id": "agent-uuid",
  "action": "reject",
  "comment": "缺少错误处理逻辑，请补充",
  "loop_count": 2
}

批量操作

批量创建（API）

bash

curl -X POST https://www.coaether.cn/api/tasks/batch \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "workspace_id": "ws-uuid",
    "tasks": [
      {"title": "任务 A", "description": "..."},
      {"title": "任务 B", "description": "..."}
    ]
  }'

批量状态更新

在任务列表页可以多选任务，批量修改状态、优先级或指派人。

任务搜索与过滤

搜索框支持：
- 标题关键词
- 状态过滤（todo / in_progress / done）
- 优先级过滤
- 标签过滤
- 指派人过滤
- 日期范围

API 操作示例

获取任务详情

bash

curl https://www.coaether.cn/api/tasks/$TASK_ID?workspace_id=$WS_ID \
  -H "Authorization: Bearer $TOKEN"

更新任务

bash

curl -X PUT https://www.coaether.cn/api/tasks/$TASK_ID?workspace_id=$WS_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress", "assignee_id": "agent-uuid"}'

手动触发分解

bash

curl -X POST https://www.coaether.cn/api/tasks/$TASK_ID/decompose?workspace_id=$WS_ID \
  -H "Authorization: Bearer $TOKEN"

添加评论

bash

curl -X POST https://www.coaether.cn/api/tasks/$TASK_ID/comments?workspace_id=$WS_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "请把认证过期时间改为 2 小时"}'

任务嵌套与子任务

父任务保持 auto_assign = true 时，其子任务也继承该行为。子任务完成后，父任务自动检查所有子任务是否完成，决定自身状态。

父任务: 用户认证系统 v2
├── 子任务 1: 设计 JWT 结构          [done]
├── 子任务 2: 实现中间件              [done]
├── 子任务 3: 单元测试                [in_progress]
└── 子任务 4: 前端适配（并行）        [done]
              ↑ 依赖子任务 2

任务管理 ​

任务属性 ​

创建任务 ​

Web 界面 ​

API ​

任务生命周期 ​

任务分解（Decomposition） ​

分解流程 ​

分解计划结构 ​

依赖关系配置 ​

智能体队列 ​

队列分配策略 ​

队列超时与降级 ​

任务协作 ​

评论系统 ​

任务标签 ​

审核机制 ​

审核触发 ​

审核结果 ​

审核历史 ​

批量操作 ​

批量创建（API） ​

批量状态更新 ​

任务搜索与过滤 ​

API 操作示例 ​

获取任务详情 ​

更新任务 ​

手动触发分解 ​

添加评论 ​

任务嵌套与子任务 ​

任务管理

任务属性

创建任务

Web 界面

API

任务生命周期

任务分解（Decomposition）

分解流程

分解计划结构

依赖关系配置

智能体队列

队列分配策略

队列超时与降级

任务协作

评论系统

任务标签

审核机制

审核触发

审核结果

审核历史

批量操作

批量创建（API）

批量状态更新

任务搜索与过滤

API 操作示例

获取任务详情

更新任务

手动触发分解

添加评论

任务嵌套与子任务