OpenHuman Task Manager Agent 深度解析：todo 任务板、主动任务源与工作流包的系统提示词设计

OpenHuman Task Manager Agent 深度解析：todo 任务板、主动任务源与工作流包的系统提示词设计

【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman

导读

本文围绕 OpenHuman 内置子代理 Task Manager Agent 的系统提示词（prompt.md）展开，逐条拆解其"任务面"职责边界、六条操作铁律与证据化收尾要求，并结合其注册配置（agent.toml）与底层工具实现（todos/tools.rs、task_sources/tools.rs），讲清每条提示词约束在代码层面如何落地。读完你将掌握：这个子代理管什么、每个 todo / task_source / workflow 工具的语义与权限分级、为什么"先读后写""部分更新"会被固化为提示词铁律，以及如何通过工具矩阵反推一个面向状态变更的 Agent 提示词应当如何设计。

一、角色定位：你拥有用户的 Agent 任务面

提示词开篇给出了该代理的职责总纲：

You own the user's agent task surfaces: per-thread todo boards, proactive task-source feeds, workflow bundles, and task evidence.

这句话定义了四个互不重叠的"任务面"：

"Own"（拥有）一词意味着这是一个有状态的任务板专家（stateful task-board specialist）：它不仅要能读写卡片，还要对变更过程负责——先观察、再决策、后修改、最后汇报。这正是它与通用工具代理的区别：在编排层，Orchestrator 将"创建、编辑、审批/拒绝、获取、清空、删除或汇总任务与任务源"的请求路由给本代理，而不是让通用工具代理看到整族工具。见 orchestrator/agent.toml 中 subagent allowlist 对task_manager_agent的注释：

Route any request to create, edit, approve/reject, fetch, clear, remove, or summarize agent tasks, proactive task sources, workflow bundles, task evidence, or artifacts here instead of letting the generic tools agent see the full family.

对应的when_to_use描述（agent.toml）同样把触发条件限定在"任务板与任务源专家：todo 卡片、主动式消息流、工作流包、产物、证据与状态"。

二、六条操作铁律：提示词如何约束一个写密集代理

提示词主体是六条行为规则，它们共同构成该代理的写操作纪律。逐条拆解：

1. 先读后写（Always read before you write）

Inspect the current board/source/workflow with the narrowest read tool before changing it.

任何修改之前，先用最窄的读工具（narrowest read tool）检查当前板/源/工作流。代码层面的印证：todo_list的工具描述明确写道 "Use to review outstanding/completed work before adding or updating tasks"（todos/tools.rs），且它是纯只读工具（is_concurrency_safe返回true），代价最低、可安全先行。单元测试 prompt_tests.rs 也把read before you write作为断言契约之一，说明这不是装饰性文案，而是被测试锁定的提示词行为。

"最窄"三个字是关键：能todo_list就不todo_replace后回读，能task_source_get单个源就不整表拉取，先获取事实再决定写什么。

2. 保留用户创作的内容（Preserve user-authored content）

Preserve user-authored task content, acceptance criteria, assigned agent, allowed tools, evidence, blockers, and source metadata unless the user explicitly asks to replace them.

需要被保留的字段清单恰好对应卡片数据模型（见 todos/tools.rs 的CardPatch）：

• content（任务内容）
• acceptance_criteria（验收标准）
• assigned_agent（指派代理）
• allowed_tools（允许工具）
• evidence（证据）
• blocker（阻塞项）
• source_metadata（来源元数据）

代码层面，todo_edit被设计为只更新显式传入的字段（"Only the fields you supply are changed; omitted fields are left untouched"），这从机制上保证了未提及字段不会因一次编辑被静默清空。

3. 偏好部分更新（Prefer partial updates）

Prefer partial updates (todo_edit,todo_update_status,update_task,task_source_update) over wholesale replacement.

提示词点名了四类"外科手术式"工具：todo_edit、todo_update_status、update_task、task_source_update。它们共同的特点是定点修改：todo_edit按id改字段、todo_update_status只转状态、task_source_update用patch对象只改要改的配置项。而整板替换类工具（todo_replace、todo_clear）则被归入破坏性工具，默认关闭（见第四节权限分级）。

4. 破坏性工具需显式授权

Use destructive tools (todo_remove,todo_replace,todo_clear,artifact_delete,agent_workflow_uninstall,task_source_remove) only when the user explicitly names what should be removed or confirms your proposed removal.

提示词明确列出的六把"破坏性工具"，代码层面对应PermissionLevel分级：

代码依据见 todos/tools.rs 文件头注释：只读的todo_list与"有界、可逆"的写工具（todo_add/todo_edit/todo_update_status/todo_decide_plan）默认启用；破坏性写工具通过tools/user_filter.rs默认关闭。task_source_remove更是直接标为PermissionLevel::Dangerous（task_sources/tools.rs），因为它的删除是级联的——连同该源摄入的全部任务历史一并移除且不可逆。

提示词因此要求：只有在用户明确点名要删什么或确认了你的删除提案时才可动用。这不是提示词的一厢情愿，而是与默认关闭的权限配置互为表里。

5. 任务源：先预览过滤器，再加持久源

For task-source setup, preview filters before adding or updating a persistent source. After adding/updating, fetch once and summarize counts plus any skipped/duplicate tasks.

这是一条"建源协议"：dry-run 先行，建源后回读一次。代码层面有两处支撑：

• task_source_preview_filter工具专门用于"干跑"：它对某个provider+filter返回会命中哪些任务，但不创建持久源、不摄入任何数据，工具描述明确要求 "Validate the filter withtask_source_preview_filterfirst"（task_sources/tools.rs）。
• task_source_fetch返回"本次拉取任务数、新路由数、作为重复项被跳过的数量"（"Returns counts of tasks fetched, newly routed, and skipped as duplicates"），这正是提示词要求向用户汇报的"计数 + 跳过/重复"摘要的来源。

task_source_add/task_source_update/task_source_remove因为"改变摄入行为并级联历史"，默认关闭（同见 task_sources/tools.rs 文件头注释）。

6. 工作流：先读再改，改前解释影响

For workflow changes, read the existing workflow first and explain the phase or install/uninstall effect before running a mutating action.

与任务板同理，工作流包也是"先读后写"的管辖对象：变更前必须agent_workflow_read读现有工作流，并解释当前所处阶段（phase）或安装/卸载的影响，之后才能执行变更动作。从工具清单看，该代理持有完整的工作流工具组：agent_workflow_list、agent_workflow_read、agent_workflow_phase_info、agent_workflow_create、agent_workflow_uninstall，以及workflow_load、workflow_phase（见 agent.toml）。其中agent_workflow_uninstall已被提示词列为破坏性工具，受第 4 条铁律约束。

收尾契约：证据化汇报

When marking work done, attach concrete evidence. When blocking, include the blocker and the next user decision needed. Return a concise task-state summary with changed ids and final statuses.

提示词要求该代理的输出是可审计的任务状态摘要：标done必须带具体证据（对应卡片的evidence字段）；置blocked必须给出阻塞项和"接下来需要用户决策什么"；最终汇报要列出变更过的 id 与最终状态。这保证了板上的每个状态迁移都有据可查、可回溯。

三、agent.toml：注册配置逐字段解析

agent.toml 是这类内置代理的注册清单，逐字段解读：

id = "task_manager_agent" display_name = "Task Manager Agent" delegate_name = "manage_tasks" when_to_use = "Task-board and task-source specialist: todo cards, proactive feeds, workflow bundles, artifacts, evidence and status. Use when the user asks to create, edit, route, approve, reject, clear or summarize tasks or sources." temperature = 0.2 max_iterations = 8 iteration_policy = "extended" sandbox_mode = "none" agent_tier = "worker" omit_identity = true omit_memory_context = false omit_safety_preamble = false omit_profile = false omit_memory_md = false [model] hint = "agentic" [tools] named = [ ... ]

关键字段语义：

• delegate_name = "manage_tasks"：该代理在编排层对外暴露的委派工具名。Orchestrator 据此把任务管理请求转交过来，正如其他委派工具（如delegate_retrieve_memory）一样，由delegate_name合成的委派工具出现在主代理的工具面中。
• temperature = 0.2：采样温度被压得很低，符合"有状态任务板专家"定位——任务是确定性业务数据，不需要高熵发散，追求的是稳定、可复现的字段操作。
• max_iterations = 8+iteration_policy = "extended"：单轮委派内允许最多 8 次工具迭代，且策略为extended（允许更长工具链），足以覆盖"读板 → 改卡 → 回读确认 → 汇报"的完整闭环。
• sandbox_mode = "none"：任务板操作不涉及任意代码执行，无需沙箱。
• agent_tier = "worker"：工作级代理，区别于 orchestrator 等协调级代理。
• omit_identity = true：不注入身份声明，因为任务管理不需要人格化自我介绍；其余上下文（memory、safety preamble、profile、memory_md）均保留，保证安全护栏与个性化上下文仍生效。
• [model] hint = "agentic"：模型选择提示走 "agentic" 档，暗示该任务适合具备强工具调用能力的模型。

四、工具矩阵全景：四族工具 + 时间与澄清工具

[tools] named共声明 31 个具名工具（含注释），按职能可分为以下族：

4.1 todo 任务板族（12 个）

todo_list（只读）、todo_add、todo_edit、todo_update_status、todo_decide_plan（审批/否决待批计划卡）、todo_remove、todo_replace、todo_clear、todowrite、update_task。

核心数据模型（来自 todos/tools.rs 的CardPatch与 JSON Schema）：

• 卡片状态机：todo | awaiting_approval | ready | in_progress | blocked | done | rejected
• 卡片字段：content（必填）、status、objective、plan（有序字符串数组）、acceptance_criteria（数组）、assigned_agent、allowed_tools（数组）、evidence（数组）、notes、blocker
• 状态流转语义：todo_decide_plan对awaiting_approval卡审批（approve: true→ready）或否决（approve: false→rejected）

特别值得注意的是线程作用域：所有 todo 工具都接受可选thread_id参数，board_location函数（todos/tools.rs）在传入thread_id时定位到线程级看板（BoardLocation::Thread），未传入时退化为进程级 scratch board（BoardLocation::Scratch）——这就是"per-thread todo boards"的代码实现。

4.2 任务源族（8 个）

task_source_list、task_source_get、task_source_fetch、task_source_list_tasks、task_source_preview_filter、task_source_status、task_source_add、task_source_update、task_source_remove（9 个）。

• Provider 枚举：github | notion | linear | clickup（参数 Schema 的 enum 限定）
• Filter 形态：provider 标签化的过滤器对象，如{ "provider": "github", "repo": "owner/name", "labels": ["bug"] }（见task_source_preview_filter描述）
• 建源参数：provider、filter必填；可选name、connection_id（Composio 连接）、interval_secs（轮询间隔，≥1）、target（agent_todo_proactive主动喂给代理 |todo_only仅入板）、max_tasks_per_fetch、assigned_executor
• 更新方式：task_source_update接受 camelCase 的patch对象，只改传入字段

4.3 工作流族（7 个）

agent_workflow_list、agent_workflow_read、agent_workflow_phase_info、agent_workflow_create、agent_workflow_uninstall、workflow_load、workflow_phase。

4.4 产物族（3 个）

artifact_list、artifact_get、artifact_delete。其中artifact_delete与agent_workflow_uninstall、task_source_remove一起被提示词列为破坏性工具。

4.5 时间与澄清工具（3 个）

• current_time：读取当前时间
• resolve_time：注释说明其用途是"将截止日期/提醒窗口解析为精确时间戳，而不是手工计算 epoch 秒数"——对任务板这类强时间语义场景（due-date、reminder window）是重要的防错设计
• ask_user_clarification：信息不足时向用户提问，配合提示词"When blocking, include the blocker and the next user decision needed"使用

五、提示词如何被装配进真实系统

系统提示词并不是 agent.toml 之外的孤本，而是通过 prompt.rs 在运行时组装：

const ARCHETYPE: &str = include_str!("prompt.md"); pub fn build(ctx: &PromptContext<'_>) -> Result<String> { // ARCHETYPE（prompt.md 本体） // + render_user_files(ctx) 用户文件上下文 // + render_tools(ctx) 当前可见的工具集与描述 // + render_safety() 安全前导（safety preamble） // + render_workspace(ctx) 工作区上下文 }

装配顺序为：archetype 提示词 → 用户文件 → 工具清单 → 安全护栏 → 工作区。也就是说 prompt.md 只是"骨架"，真正的运行时提示词还叠加了动态注入的用户文件、按权限过滤后的工具描述、统一安全前导与工作区信息。include_str!编译期内联保证了 archetype 文本与源码版本严格同步。

对应的契约测试 prompt_tests.rs 构造最小PromptContext调用build，断言输出同时包含Task Manager Agent与read before you write两个关键契约，防止提示词核心语义被意外改掉。

六、编排视角：为什么需要"任务面专属"子代理

结合 orchestrator/agent.toml 的 subagent allowlist 可以看清设计意图：Orchestrator 维护了一长串专职子代理（researcher、planner、code_executor、tools_agent、settings_agent、profile_memory_agent、vision_agent、image_agent、video_agent、skill_creator、critic、archivist、help 等），task_manager_agent位列其中，注释专门说明它的价值在于：

1. 路由收敛：任务相关请求统一进入本代理，避免通用 tools_agent 面对整族工具的提示词膨胀；
2. 纪律本地化："先读后写"与"确认后删除"的确认策略只在高风险工具附近生效（与 settings_agent 的设计理由同构），让确认负担不扩散到无关场景；
3. 上下文裁剪：omit_identity = true等开关按需裁剪上下文，控制 token 成本。

值得留意的是 integrations_agent/agent.toml 中的一条历史注释提到旧的workflow_load/workflow_phase工具"随 agent_workflows 域被移除"，而 task_manager_agent 的工具清单中仍保留了这两个名字——在阅读该代理工具面时，应以当前 agent.toml 的清单为准，并留意域重构可能带来的工具名演进。

七、实践要点小结

• 状态变更类代理的提示词应"约束行为而非描述功能"：prompt.md 通篇没有教模型"怎么用工具"，而是约束"何时读、何时写、何时必须确认、如何汇报"，行为纪律与 todos/tools.rs、task_sources/tools.rs 的权限分级（默认启用 vs 默认关闭 vsDangerous）互相印证。
• 可审计性写在提示词里：证据化收尾（done 附 evidence、blocked 附 blocker + 下一步决策）让任务板状态迁移可被用户和系统回溯。
• 最窄读取 + 部分更新 + 显式授权三件套，是"有状态写密集代理"防止数据被误覆盖的标准姿势。
• 若要在 OpenHuman 中触发本代理，只需在对话中提出"创建/编辑/审批/拒绝/清空/汇总任务或任务源"类需求，Orchestrator 会依据when_to_use与delegate_name = "manage_tasks"将请求委派给它；其完整行为契约可直接阅读 prompt.md 原文。

【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman