todos

添加新项前先列出未完成项

先读取可以避免多个 agent 在同一 project scope 中工作时创建重复的 TODO。

todo({ action: "list" })

公开 MCP 工具

todo

用途

创建、更新、完成、列出或明确批量删除 project TODO，同时将 task state 保存在其已授权的 project context 附近。

适用场景

用户需要持久 task state、due date、priority、completion 或 handoff list。
project workspace 需要使用其 signed mount capability 执行受治理的 TODO mutation。
调用者需要列出所有已授权的 open、in-progress、completed 或全部 items。

不适用场景

不要用 TODO 保存通用的持久 fact 或 decision；请使用 remember。
不要将 financial transaction 作为 TODO content 保存；请使用 ledger。
没有明确的 user request 和 confirm_delete_all=true 时，不要调用 delete_all。
REST API 接受的 field set 比 public MCP tool 更宽；scope、bucket、team 和 provenance filter 见 /docs/api/memory。

所需权限范围

List 使用 memory:read；在 public chat surface 中，create、update、complete 和 delete_all 使用 memory:write。
Project Workspace mutation 还需要有效的 mount_capability 和 project_id。

参数列表

参数名	类型	描述
`action`	create \| update \| complete \| list \| delete_all · 必填	Dispatcher operation。
`todo_id`	string	用于 update 或 completion 的准确 item ID。
`content / title`	string	Task text；如果同时提供，两者必须一致。
`project_id`	string	已授权的 project workspace identifier。
`priority / due_at / status / note`	string	Task priority、due timestamp、status transition 和 handoff note。
`item_status / due_before / search / query`	string	List filters；search 和 query 仅用于 list，如果同时提供则必须一致。
`limit / cursor / owner_timezone`	integer / string · 默认值: 20 / empty / configured timezone	Pagination 和日期解释控制项。
`client_mutation_id / expected_version`	string / integer	create/update 的幂等 key，以及 update 的 optimistic concurrency version。
`confirm_delete_all`	boolean · 默认值: false	执行明确的可恢复批量删除所需的 true 值。

返回模式

Structured output 会标识 action，并返回受影响的 item(s)、pagination cursor、mutation status 和安全的 task metadata。Bulk deletion 始终是可恢复的 soft deletion。

使用示例

创建幂等 task

todo({
  action: "create",
  content: "Review the MCP scope matrix",
  client_mutation_id: "task-review-scope-001",
  due_at: "2026-08-25T09:00:00Z"
})

列出未完成 task

todo({ action: "list", item_status: "open", limit: 10 })

错误信息

Authorization failure：list 缺少 memory:read，或 mutation 缺少 memory:write/project capability。
Validation failure：create 缺少 client_mutation_id，update 缺少正数 expected_version，或 action fields 互相冲突。
Safety rejection：delete_all 需要明确确认，widget/mount-capability caller 不可使用。
Timezone、project 或 optimistic-concurrency errors 会被明确返回；dispatcher 不会静默忽略 fields。

remember — 保存 task 背后的持久 decision 或 fact。
recall_context — 继续工作前恢复 task 和 project context。
forget — 需要时按准确 ID 删除一个经过审查的 TODO。

来源: SDK 工作流辅助工具