---
name: zentao-task
description: "禅道任务管理：创建任务、启动、完成、关闭、激活，查执行下的任务列表。当用户说「建个任务」「这个任务开始做了」「任务做完了」「任务关掉」时使用。"
---

# 禅道任务管理

**前置：先读 `zentao-shared`（尤其"路径参数不出现在 inputSchema 里"一节）。**

---

## 状态机

```
未开始 ──start 启动──▶ 进行中 ──finish 完成──▶ 已完成
  │                        │
  └──────── close 关闭 ─────┘（不做了/取消，跳过完成）
                             ▲
                    activate 激活（重新打开，从已完成/已关闭回到进行中）
```

---

## 字段名坑：跟 story/bug 不一致

**任务标题字段叫 `name`，不是 `title`**（story/bug/epic/requirement 都是 `title`，
只有 task 是 `name`，创建时容易写错）。

**创建任务时所属执行的字段叫 `executionID`**，不是 `execution`（bug 创建时挂执行用的
是 `execution`）——同一个"所属执行"的语义，在不同实体的创建接口里字段名不统一，
调用前对照该工具自己的 inputSchema，不要照抄别的实体的字段名。

---

## 查

```
get_executions_executionID_tasks(executionID, ...)   某执行下的任务列表
get_tasks_taskID(taskID)                              任务详情
```

任务只能按"所属执行"维度查列表，没有按产品/项目查任务的接口——要看某个产品下的任务，
先找到相关执行再查。

---

## 建

```
post_tasks({ payload: { name, executionID, type?, assignedTo?, estStarted?, deadline?,
                         pri?, estimate?, module?, story?, desc? } })
```

`name`/`executionID` 必填。`story` 字段可以关联到具体需求（story ID），常用于"这个
任务是为了实现哪个需求"。

---

## 启动（start）

```
put_tasks_taskID_start({ taskID, payload: { realStarted, assignedTo?, consumed?, left?, comment? } })
```

`realStarted`（实际开始日期）必填。

---

## 完成（finish）

```
put_tasks_taskID_finish({ taskID, payload: { currentConsumed, realStarted, finishedDate,
                                              assignedTo?, consumed?, comment? } })
```

**三个必填字段**：`currentConsumed`（本次消耗）、`realStarted`（实际开始，即使之前
`start` 过也要再传一次）、`finishedDate`（实际完成日期）。完成前把这三个数字/日期跟
用户确认清楚（`zentao-shared` 全局约定：状态流转类操作先确认），尤其 `currentConsumed`
容易被和"总计消耗 `consumed`"搞混——前者是这一次填报的增量工时，后者是累计总工时，
两个都传的话以工具说明为准判断二者关系，不要凭直觉认为两者相等。

---

## 关闭（close）/ 激活（activate）

```
put_tasks_taskID_close({ taskID, payload: { comment? } })
put_tasks_taskID_activate({ taskID, payload: { left?, assignedTo?, comment? } })
```

都没有必填字段。`close` 用于跳过完成流程直接终止任务（比如需求取消了）；`activate`
把已完成/已关闭的任务重新打开，可以顺带更新预计剩余工时 `left`。

---

## 改 / 删

```
put_tasks_taskID({ taskID, payload: {...} })
delete_tasks_taskID({ taskID })
```

删除不可逆，执行前必须确认。