Taskr — 持久化任务规划与执行

Taskr 为 OpenClaw 智能体提供持久化、结构化的任务管理能力，该能力独立于聊天会话之外运行。任务计划可在上下文重置后继续存在，可由任意机器上的任意智能体恢复执行，并始终通过 Taskr 网页应用、VS Code 插件或移动应用向用户可见。

Taskr 为 OpenClaw 提供六大核心能力：

1. 分层式规划 —— 在调用任何工具前，先将任意工作拆解为嵌套式任务层级
2. 持久化上下文 —— 任务、备注及状态在会话重置与上下文压缩后仍完整保留
3. 跨智能体连续性 —— 任意智能体均可从任意位置接手任一任务列表；get_task 自动完成任务所有权转移
4. 基于备注的审计追踪 —— 备注直接关联至具体任务；因果关系集中呈现，不分散于聊天历史中
5. 回溯式同步 —— task_sync 可记录 Taskr 启用前已完成的工作，补全历史记录中的空白
6. 共享状态 —— 状态（open、wip、done、skipped）为智能体与用户提供明确、实时的进度视图

何时使用 Taskr

建议在以下情形中启用 Taskr：

• 工作包含 3 个以上步骤，或预计耗时超过数分钟
• 工作跨越多个会话，或可能移交至其他智能体处理
• 用户需远程监控或审批进度
• 需从上一会话中恢复工作

无需使用 Taskr 的情形：

• 单次快速操作（＜3 步，＜2 分钟）
• 纯信息检索或简单问答
• 用户明确拒绝使用

主动默认策略： 对于任何实质性工作，应在启动前主动提议使用 Taskr：

“我将先在 Taskr 中进行规划——您可在执行前审阅任务分解方案。是否可行？”

一旦启用 Taskr，请全程保持在 Taskr 工作流内。 切勿在工作流程中途放弃任务。仪表板中未完成的任务会造成理解混乱，并破坏审计追踪的完整性。

核心工作循环

规划 → 创建 → 创建 CONTEXT 备注 → 用户审阅 → 执行 → 归档 → 循环

1. 规划 —— 全面梳理工作范围；在调用任何工具前，将其拆分为阶段与子任务
2. 创建 —— 使用 create_task 并指定 taskListTitle，单次调用即可构建完整任务层级
3. 创建 CONTEXT 备注 —— 始终为新建任务列表（TL_）附加一条 CONTEXT 备注，内容包括背景说明、目标及用户偏好
4. 审阅 —— 向用户呈现任务计划；获得批准后方可执行
5. 执行 —— 调用 get_task → 执行工作 → 调用 update_task 将状态设为 done → 重复此流程
6. 归档 —— 工作过程中持续为任务附加备注；各阶段完成后撰写 PROGRESS 备注

单任务原则： 每次仅处理一个任务。get_task 将使你成为该任务的负责人（wip），必须在切换至下一任务前完成或跳过当前任务。

规划：任务层级设计

使用带 taskListTitle 参数的 create_task 创建新任务列表。单次调用可提交 1–100 个任务——务必在执行开始前一次性创建完整层级，以便用户审阅。

层级编号规则：

• "1"、"2"、"3" —— 顶层阶段（任务列表的直接子节点）
• "1.1"、"1.2" —— 阶段 1 下的子任务
• "1.1.1" —— 更深层级嵌套（最多支持 10 层）
• 父任务必须在同一次调用中先于其子任务声明

任务类型： setup、analysis、implementation、validation、testing

保持任务聚焦。 若某任务体量过大，无法在单次智能体响应中完成，则应将其拆分为子任务——可在创建时完成，也可在执行中途通过 create_task + parentId 动态拆分。子任务可避免上下文过载，并在恰当粒度上清晰呈现进展。

创建任务列表后，请立即为其创建一条 CONTEXT 备注：

create_note(type="CONTEXT", title="[Task List] — Context", body="...", taskId="TL_...")

执行：任务处理流程

get_task

调用 get_task 获取下一个待处理任务。该操作将自动将任务状态设为 wip 并分配所有权。请务必使用 get_task，切勿手动将任务设为 wip。

• 省略 task_list_id 参数以继续当前任务列表
• 传入 task_list_id=TL_... 以切换至其他任务列表
• 传入 include_context=true 可获取额外任务上下文与备注
• 仅在紧急任务切换场景下传入 bypass_task_id

update_task — 两种模式

状态更新模式（单任务）：

update_task(taskId="TS_...", status="done", ruleContext="RU-PROC-001")

批量更新模式（仅支持标题/描述更新，批量模式下禁止设置状态）：

update_task(tasks=[{taskId, title?, description?}, ...], ruleContext="RU-PROC-001")

任务状态 —— 共享检查点

状态是智能体与用户均可实时查看的检查点，请严格遵循规范使用。

当某父任务的所有子任务均完成时，系统将自动将该父任务标记为 done，无需手动设置。

处理意外工作项

当发现超出当前任务范围的工作时：

• 阻塞当前任务 → 调用 create_task（parentId 设为当前任务），完成子任务后再恢复主任务
• 完全无关 → 先完成当前任务，再为新工作创建独立任务
• 可延后处理 → 以 FINDING 备注形式记录，继续当前任务

审阅：get_task_hierarchy

使用 get_task_hierarchy 浏览与审阅任务结构 —— 请勿使用 get_task 进行结构查看。切勿仅为查看结构而调用 get_task。

task_list 作用域下的响应路径：data.task_lists[0].tasks[0].children[]

备注 —— 关联至任务的审计追踪

备注与具体任务绑定。例如在任务 2.3 执行过程中发现的问题，其 FINDING 备注将永久附着于任务 2.3，而非悬浮于项目层级。后续任何智能体恢复工作时，均可在所需位置获得完整上下文。这正是防止信息碎片化的关键机制。

备注类型：

备注使用规范：

• 将备注附加至最具体的关联任务（TS_ > TL_ > 项目级）
• 优先更新已有备注而非重复创建 —— 使用 update_note
• 创建前先搜索：search_notes 可在恢复工作时快速获取先前上下文
• 设置 skipped 状态时，必须同时创建一条含原因说明的 FINDING 备注

两步式备注检索：

1. list_notes(taskId="TL_...", includeDescendants=true) —— 获取备注 ID 与标题（data.notes.notes[]）
2. get_note(noteId="NT_...") —— 按需获取完整内容

task_sync — 回溯式记录维护

当工作已在 Taskr 启用前完成，或需回溯性补全任务历史记录空白时，请使用 task_sync。共三步操作：

步骤 1 —— 概览（无参数）：轻量级汇总所有任务列表

task_sync(ruleContext="")
→ data.sync_check.task_lists[]: {id, name, status, task_count, done_count, open_count, wip_count}

步骤 2 —— 深入查看（传入 task_list_id）：平铺列出所有任务的标题、描述、状态与层级

task_sync(task_list_id="TL_...", ruleContext="")
→ data.sync_drill_down.tasks[]: {id, task_number, title, description, status, level, parent_id}

步骤 3 —— 创建已完成任务（传入 items[]）：创建预设状态为 done 的任务

task_sync(items=[
  {
    "action": "create_done",
    "title": "...",
    "parentId": "TS_or_TL_...",
    "description": "...",
    "type": "implementation"
  }
], ruleContext="")

每项必须包含 action: "create_done" 与 title。若未提供 parentId（TS_ 或 TL_），则需提供 taskListTitle 以创建新任务列表；未指定 parentId 的条目将默认归属至该新列表。单次调用最多支持 50 项。

同步完成后，请为所创建任务附加 CONTEXT 或 FINDING 备注，以记录工作的背景与决策依据。

跨会话与跨智能体连续性

Taskr 状态存储于云端，而非本地上下文窗口中。恢复工作流程如下：

1. search_notes —— 查找先前的决策、上下文与发现
2. get_task_hierarchy(scope="project", depth=0) —— 识别当前活跃的任务列表
3. get_task(task_list_id="TL_...") —— 在上次中断处接管任务所有权
4. 执行前审阅 CONTEXT 与 PROGRESS 备注

任意智能体——无论来自不同会话、不同设备或不同模型——均可精确恢复至工作中断处。任务列表即计划，备注即记忆，状态即当前进展。

配置

当凭证缺失时：

1. 向用户获取凭证：

   • 项目 ID：访问 https://taskr.one 的 Projects 页面（格式示例：PR_00000000...）
   • API Key：点击用户头像 → API Keys 菜单（点击眼形图标或复制按钮）

2. 通过 gateway.config.patch 配置：

   {
     "skills": {
       "entries": {
         "taskr": {
           "env": {
             "MCP_API_URL": "https://taskr.one/api/mcp",
             "MCP_PROJECT_ID": "",
             "MCP_USER_API_KEY": ""
           }
         }
       }
     }
   }
   

3. 验证配置： 调用 tools/list 并确认 create_task 已出现在可用工具列表中。

用户可为不同工作场景创建多个项目。

对于 mcporter 或其他 MCP 客户端：

mcporter config add taskr "$MCP_API_URL" 
  --header "x-project-id=$MCP_PROJECT_ID" 
  --header "x-user-api-key=$MCP_USER_API_KEY"

速查表

ruleContext 取值说明： 传入 Schema 中定义的规则 ID（例如 RU-CTX-001、RU-PROC-001、RU-NOTE-001）。当 Schema 明确要求“请留空此参数”时，传入 ""。