---
name: huanxi-task
description: "寰汐任务管理：查任务、建任务、改状态与进度、分配执行人、认领。当用户说「我有什么任务」「建个任务」「把这个标成完成」「派给谁」时使用。"
---

# 寰汐任务管理

**前置：先读 `huanxi-shared`（尤其「状态是可配置的两层模型」一节）。**

---

## ID 传递链

任务操作几乎都是这条链，**中间结果要展示给用户**，不要一路闷头做到底：

```
module_query()                     → module_id
  ↓
task_query(module_ids=[...])       → task_id[]     ← 展示给用户看
  ↓ ⏸ 用户指明改哪些
task_update(updates=[{id, ...}])
```

---

## 查

```
task_query(scope="mine")                    我负责执行的（默认）
task_query(scope="all", module_ids=[...])   某几个模块的全部任务
task_query(q="关键词")                       标题模糊搜
task_get(task_ids=[...])                    详情：描述 + 层级路径
```

过滤维度都收列表，一次查多个模块比循环调用好。

---

## 改状态与进度

**先 `dict_get` 取 task 类型的状态选项**，拿到 `status_option_id` 再传：

```
dict_get(kinds=["status_options"])
  → 筛 entity_type == "task"
  → 按 category 找到目标状态（not_started/in_progress/completed/cancelled）
  → 取它的 id
task_update(updates=[{id: 任务id, status_option_id: 状态id}])
```

状态与进度**有联动，只传一个就够**：进度设到 100 会自动转完成；已完成的任务把进度
调低会自动回落进行中。两个都传等于重复表达同一个意思。

**非叶子任务不能直接设进度**——返回里 `progress_readonly` 为 true 的那些，进度是子任务
聚合出来的，硬设会被拒绝。要推进它，去改它的子任务。

---

## 建任务

```
task_create(module_id=..., tasks=[{title, description?, priority?, end_date?,
                                    parent_id?, milestone_id?, assignee_ids?}])
```

- 建子任务传 `parent_id`，**最多三级**（任务 / 子任务 / 孙任务）
- 需要是该模块的成员或负责人
- `priority` 的取值以工具说明为准——**不要凭直觉写**，这个字段有 DB 级约束，写错直接报错

---

## 执行人

```
task_set_assignees(task_id=..., user_ids=[...])   整组覆盖，传空即清空
task_claim(task_ids=[...], claim=true/false)      认领 / 取消认领（只动自己）
```

**`task_set_assignees` 是替换不是追加。** 想加一个人，要先 `task_get` 拿到现有名单，
把新人拼进去再整组传回——直接传一个人会把其余执行人全部踢掉。这是最容易出错的地方，
覆盖前把「改完会变成谁」说给用户听。

被指派的人若不是模块成员，会自动加入该模块；新增执行人会收到飞书通知。

---

## 不在工具里的操作

删除任务、跨模块转移任务**不在 MCP**，请引导用户去网页端——这两个动作作用于整棵子树
且不可逆，需要看清楚影响范围再点。