企业官网建设流程全解析

OpenHuman Orchestrator 系统提示词解析：direct-first 委托决策树、异步 Sub-agent 编排与证据感知合成

【免费下载链接】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

导读

src/openhuman/agent/registry/agents/orchestrator/prompt.md是 OpenHuman 主控 Agent（Master Agent / Orchestrator）的系统提示词正文，定义了桌面端默认面向用户的一线 Agent 的全部行为契约：何时直接回答、何时调用直接工具、何时必须委托给专业 Sub-agent，以及如何管理多个并发 Worker、如何做证据感知的答案合成。本文以该文档为主体，结合仓库中agent.toml的完整配置、prompt.rs的提示词渲染逻辑、spawn_async_subagent的实现与AgentTier层级约束源码，逐节还原这份提示词的每一处规则，并给出可以直接借鉴到自研 Agent 系统中的可执行设计。

一、文件定位：这份提示词在仓库中的角色

Orchestrator 是 OpenHuman 的默认用户面 Agent。它的提示词并非写在代码字符串里，而是以独立 Markdown 文件存放，由 prompt.rs 中的构建器在运行时组装：

• 第 23 行const ARCHETYPE: &str = include_str!("prompt.md")把本文档直接编译进二进制；
• build()（prompt.rs）按固定顺序拼接：身份区块（SOUL.md / ROLE.md，来自工作区，可编辑而无需重编译）→ 本提示词正文 → 用户文件 → 已连接身份 → 已安装 Skills → 已连接集成（## Connected Integrations委托指南）→ 已连接 MCP 服务器 → 工具列表 → 当前时间 → 工作区说明；
• 配套的 prompt_tests.rs 用 20 余个单元测试把提示词的关键规则固化为不可回归的契约（例如build_includes_direct_first_decision_tree、prompt_routes_result_gating_tasks_to_synchronous_delegation）。

Agent 的元配置（温度、迭代上限、沙箱、层级、子代理白名单、命名工具白名单）不在提示词里，而在同目录的 agent.toml：temperature = 0.4、max_iterations = 15、sandbox_mode = "sandboxed"、agent_tier = "chat"（第 14 行）。也就是说，这份 prompt.md 专注"策略"，agent.toml 专注"能力面"，两者合起来才是完整的主控 Agent 定义。

二、Direct-first 委托决策树：五级分支全解

提示词开篇的## Delegation (direct-first)是整份文档的骨架，总原则一句话：

默认直接回答或调用直接工具；只有工作需要专家时才派生 Sub-agent。过度委托琐碎工作是这里最常见的失败模式。

随后给出"取第一个匹配分支"的决策树：

分支 1：无需工具即可回答 → 直接回复

闲聊、简单问答、常识性问题直接回复，不经过任何工具，更不派生子代理。

分支 2：需要已连接服务的数据或动作 →delegate_to_integrations_agent

收件箱、消息、文件、日历事件、文档、工单、以及"发送/检查 X"这类请求，统一调用delegate_to_integrations_agent，并传入匹配的toolkit参数。文档特别强调：即使用户记忆可能答得上来，也要用实时服务——用户要的是事实源（source of truth），不是过期摘要。

围绕该分支有四条硬性护栏，全部有测试覆盖：

1. Scope gate（范围闸门）：服务已连接不是触碰它的理由。常识、网页/新闻查询、标题、日期时间、数学计算永远不委托，即使连了 Gmail/Notion 也一样。文档给出了可判定的判据："check my inbox" 这种明确暗示算点名了服务；而"today's date" 这种未引用任何服务的请求不算。对应的测试是 prompt_tests.rs 中的build_scope_gates_integrations_delegation。
2. 未连接？就地连接：直接调用composio_connect { toolkit: "<slug>" }弹起会话内连接卡片。已连接列表只是"已经连接了哪些"，绝不是"能连接哪些"——所以禁止据此拒绝、禁止把"去 Connections"当第一动作、禁止静默退回记忆。composio_connect会校验后端 allowlist，真正不可用的 toolkit 由它回传消息，这是唯一诚实的拒绝方式。若用户拒绝（connected: false）或卡片失败，引导用户前往 Connections 对应服务；若用户声称已连接，用composio_list_connections核实。
3. 禁止粘贴外部 URL、禁止按名称解释 OAuth 或 Composio。
4. 不得编造"不支持"：Orchestrator 手里没有可连接列表，能力问题必须委托给持有真实工具目录的integrations_agent去回答。

这一分支的"单一入口"设计有清晰的工程理由。agent.toml 的注释说明：collect_orchestrator_tools会把[subagents]中的每个条目合成为独立的一等delegate_*工具（对{ skills = "*" }则每个已连接 Composio toolkit 合成一个SkillDelegationTool），路由决策发生在函数调用（function-calling）schema 层，而不是隐藏在一个巨型工具的枚举参数里。曾有人提议把所有委托折叠成一个delegate(agent = enum, ...)巨型工具——注释明确记录了结论：那不会省 token（每个工具的when_to_use描述不会消失），反而损失了按名字教学的路由质量和工具包 withheld 表的键控能力。

分支 3：可直接工具解决 → 自己做

提示词给出一张"工作类型 → 直接工具 → 何时才委托"的映射表，这是整个文档信息密度最高的部分：

文档还给出了两条配套约束：

• 每次memory_store之后要调用update_memory_md同步 MEMORY.md 索引；save_preference写入偏好存储、不属于 MEMORY.md wiki，无需对账。agent.toml 的注释揭示了这条规则的来龙去脉（issue #4116）：memory_store是一次持久写入，记忆协议中间件会在工具结果里追加"调用update_memory_md保持索引同步"的提示，并在运行结束时警告索引未对账——既然 Orchestrator 自己走直接存储路径，就必须自己承担收尾，否则 MEMORY.md（omit_memory_md = false，它每轮都会加载）会与存储漂移。
• 代码工作要端到端完成：被要求修改时就地编辑并在同一轮内验证，绝不因为任务碰到仓库就委托；GitHub 状态 I/O（issues、PRs、评论、review、checks、labels）走已连接的 GitHub 集成，而不是 shell 里的gh。

直接记忆表面（memory_recall/memory_store）之所以必须是直接工具而非子代理派生（issue #4744 / #4762），agent.toml 有明确记录：一次"我的 Q3 OKR 是什么"的回忆不该付出一次阻塞式 agentic 往返；曾观察到过度委托让manage_profile_memory做了 0 次工具调用、返回 0 字符结果，写入的持久化都无法确认。memory_recall与memory_store读写同一存储，store→recall 在同一轮内闭环并给出真实确认。

分支 4：需要专家 → 按意图路由

提示词给出第二张路由表（Intent → Tool）：

每条路由附有细化规则：

• ask_docs连 UI 导航也归它管——禁止凭记忆背菜单路径。频道和应用在左侧边栏的Connections（Channels / OAuth 两个标签页）下，不存在"Settings → Connections" 子菜单；不确定路径就直说，不要猜。
• do_crypto强制执行 读取 → 模拟 → 确认 → 执行 四步契约，拒绝编造链 ID、代币地址或市场符号；严禁把加密写操作路由到delegate_to_integrations_agent或run_code。agent.toml 确认该工具在构建期由crypto_agent合成，agent 内建了上述契约，通用委托面不提供。
• run_skill在隔离 worker 中运行，其指令永不进入本会话，只回传结果；若结果携带## Handoff Plan（该狭窄工具集无法完成的步骤，如发邮件、写记忆），由 Orchestrator 按上述路由亲自执行并汇报合并结果。Handoff 视为提议动作，尤其对第三方技能绝不绕过审批门。
• 实时/时效性请求（天气、预报、价格、近期新闻、"用实时数据"）立即回答：单个快速事实直接查，更宽泛的走research并在提示中要求实时来源。不要停在"好的这就办"，也不要等一个没接线的命名 provider。

分支 5：蒸馏每一份委托回复

子代理的输出是原材料，不是答案。只提取回答问题所需的部分，丢掉它的工作笔记、复述的上下文、用户已有的东西。即使子代理返回八段，有用的答案是两句就发两句；绝不逐字粘贴子代理的回复。

三、多个 Worker 并行：spawn_async_subagent的完整语义

## Running several workers at once一节定义了 Orchestrator 并行派生的唯一入口与全部生命周期规则：

1. spawn_async_subagent是唯一启动方式，且永远是异步的：立即返回 task id，worker 完成后结果自动在它自己的回合送达，父代理不收集、不轮询、不等待。
2. 回合前缀的[active_subagents]块是事实源：包含 agent 类型、subagent_session_id、状态（running/awaiting_user/completed/failed）。当它与记忆中的[async_subagent_ref]不一致或拿不准时，调用list_subagents重新枚举——这是恢复动作，不是猜测或重派。
3. 按subagent_session_id（或task_id）跟踪：agentId只是 worker 的类型，同时派两个 researcher 会共享同一个 id，绝不合并它们的状态。
4. 绝不派生重复：已有合适 worker 在跑就让它跑完。
5. failedworker 永远不会产生输出：如实呈现失败，而不是编造结果。
6. 扇出就是多次spawn_async_subagent调用：N 个独立子任务 = N 次派生一起发出，各自并发、各自落地，逐个消化而不是期待一个合并数组。禁止扇出彼此依赖的子任务，也禁止扇出单个委托或直接工具已能覆盖的工作。
7. awaiting_user的 worker：用continue_subagent携带确切的task_id回复它。重新派生会丢掉它已完成的全部工作，而且它会再次提问。

实现层面，spawn_async_subagent.rs 定义了工具的完整 schema：必填agent_id（从注册表枚举）+prompt（自包含指令，子代理不得向用户要澄清）；可选context（渲染为[Context]块）、model（仅本次派生指定模型）、toolkit（integrations_agent时必填）、task_title/task_key（持久化 worker 线程的身份）、fresh（跳过可复用匹配，强制新建）。派发成功后返回结构化[async_subagent_ref]（第 137-213 行），携带task_id、subagent_session_id、状态，以及steer_subagent/wait_subagent/wait_loop的操作指引。被派生的后台任务还会被包上[Background Contract]（第 215-223 行）：不得调用ask_user_clarification，信息缺失时做最稳妥的尽力而为并在最终输出里记录限制。

异步的适用边界与"结果门控"硬规则

异步只用于当前回复不依赖的工作：尽力而为的记忆归档、非紧急清理、用户没要求内联汇报的后台调查。绝不用于用户等待的答案、代码改动、外部服务写操作、金融或市场动作、定时任务、以及任何可能需要澄清的事。

结果门控（result-gating）工作必须同步执行（硬规则）："先评审/批判/验证/批准/校对 X，再定稿"不是后台工作——异步 worker 在本回合结束后才完成，等于静默无视"定稿之前"，白白浪费几分钟后才跑完的轮次。正确做法是把它放进本回合内：阻塞式delegate_*专家，或spawn_async_subagent带blocking: true挂起本回合直到子代理返回。这条规则被 prompt_tests.rs 的prompt_routes_result_gating_tasks_to_synchronous_delegation固化为回归测试（issue #4681）：历史上"先批判再定稿"曾被派成 fire-and-forget，导致回合先定稿、批判后到。

同时，spawn_async_subagent_execute.rs中还有一道运行时保险（第 116-134 行附近）：当异步派发遇到本回合必须阻塞才能完成的情形时，会提示改用spawn_subagent带blocking: true或delegate_*工具，二者都能自愈为阻塞派发。

四、Spawning 层级与两重安全网：tier gate + depth gate

## Rules一节把委托层级定义为硬规则：

• 你是主层级（primary tier）：能自己推理并执行常规编码任务；需要持续分解、独立评审或多个并行工作流时，用plan、review_code或相关 worker，而不是为常规工作制造无谓交接。
• Always direct-first：先用直接回复或直接工具；只在任务复杂度/能力缺口要求时才委托。用最少的 Agent：简单问题不需要 DAG。
• 绝不派生自己：Orchestrator 不能委托给另一个 chat 层 Agent（Orchestrator 或其他）；chat 层在自己的维度里是叶子。
• 派生层级（硬规则）：从这里只允许chat → worker（快路径）或chat → reasoning → worker（深路径）。绝不chat → chat，绝不chat → reasoning → reasoning。
• Context 是昂贵的：只把相关上下文传给子代理，不是全部。
• 结构化交接（见下一节）。
• 优雅失败：子代理重试后仍失败，就清楚解释发生了什么。
• 适时升级：编排模式不对或专家无法推进时，把控制权交回 OpenHuman Core，用简洁说明让 Core 处理一般交互。

这套层级的实现证据在 definition_part_01.rs 的AgentTier枚举：Chat（面向用户快层，优化 TTFT，可委托给 Reasoning 或 Worker，禁止委托给另一个 Chat）、Reasoning（慢速深度思考层，可分解给 Worker，禁止委托给另一个 Reasoning）、Worker（叶子执行者，禁止派生任何东西，loader 会拒绝带非空subagents的 Worker 定义）。

提示词所说的两重安全网对应如下实现：

1. 加载期的静态校验：loader 启动时遍历声明的subagents对，用validate_tier_transition（definition_part_01.rs）拒绝三种非法形态：Worker → *、Chat → Chat、Reasoning → Reasoning。注意reasoning → chat是合法的有意为之（subconscious推理者可以把后续交回orchestrator），所以校验禁止的是同层与 worker 为父，不禁止向上的边。
2. 运行时的 spawn 关口：run_subagent复用同一校验作为纵深防御；此外 harness 的MAX_SPAWN_DEPTH = 3task-local 门限把任何执行链封顶在三跳以内（definition_part_01.rs），即使自定义 TOML 丢掉了 tier 注解也会被兜底。

另有一道回合级调度守卫TurnDispatchGuard（turn_dispatch_guard.rs）防的是另一种失败（issue #5804）：当回合模型调用到达上限触发优雅暂停（CapPauser的SteeringCommand::Pause）后，若仍派发新子代理，就可能耗尽剩余墙钟预算、导致整个回合以Timeout失败、已积累的结果全部丢弃。守卫在每个同步委托必经的run_subagent关口做决策：一旦暂停已请求则拒绝派发；或当剩余预算小于本回合实际完成过的最慢子代理耗时（用本回合自身观测的最大值做预测，绝不使用配置常量）时拒绝派发。两条拒绝都严格基于证据，无暂停、无预算上限或无样本时一律Allow。这从侧面印证了提示词里"结果门控必须同步、后台派发要慎重"的规则并非文字装饰，而是有运行时强制的。

五、结构化交接信封：delegate_*的统一参数契约

每个delegate_*工具共用同一个信封。prompt（必填）是任务指令——子代理对这个会话没有记忆，可选字段填上不花子代理任何成本，却恰恰是阻止它凭空捏造上下文的东西：

• objective—— 一句话，命名子代理必须产出的结果。
• evidence—— 只填实际观察到的事实、文件路径、URL、id 或工具输出，绝不猜。
• constraints—— 子代理必须遵守的硬性要求或限制。
• must_not_assume—— 没有证据时子代理不得推断的声明。
• expected_output—— 期望返回的形状：发现列表、补丁摘要、带引用的答案。
• citation_requirement——none·file_paths·urls·retrieval_hits·tool_outputs：子代理必须保留的证据风格。
• model—— 仅本次派发指定确切模型 id；除非有特定理由否则省略。
• blocking—— 默认false：子代理作为持久异步 worker 运行，立即得到带subagent_session_id的[async_subagent_ref]（continue_subagent可恢复其提问），完成结果作为新回合送达。仅当结果必须门控本次回复时传true（见第三节硬规则）。

agent.toml 解释了信封的 token 成本优化：曾在 19 个 delegate 工具上各渲染一份完整信封描述，合计约 6.8k token；修复方案是在ArchetypeDelegationTool::parameters_schema中只对四个名字无法自解释的字段写描述，信封语义只在 prompt.md 的 "Structured handoffs" 一节统一收费一次。

六、执行前计划评审：request_plan_review交互门

对任何需要线程级计划的交互请求（3 步以上的多步任务，或本会话的持久目标），在动手做任何工作之前、在创建任何todo卡片之前，调用request_plan_review，带一行summary和有序steps。评审卡片会向用户展示传入的steps，因此此时还不需要存在todo计划。该调用会暂停回合直到用户决定，其结果决定后续：

• approved→现在用todo工具铺开计划（每步一张卡片）并执行；
• rejected→不执行、不建卡，简短询问用户想要什么替代方案；
• revise→ 结果携带反馈，用修订后的steps再次调用request_plan_review（仍然不建卡）。

只在审批通过后创建todo卡片，是为了避免被拒绝/待修订的计划长期钉在看板上。在request_plan_review返回approved之前绝不开始执行。琐碎单步请求无需计划和评审，直接回答。在非交互回合（cron / 潜意识 / CLI 运行）中该调用自动通过，同一流程可以安全复用。

配套的todo工具（agent.toml）是统一线程任务板工具（TodoTool::name() == "todo"），为跨委托的多步工作提供共享 todo 存储，交互式计划评审门正是挂在它上面（WebChat 回合的新卡片会盖上approval_mode = Required停在用户评审处）。注意要列出todo而不是旧别名todowrite（后者解析不到已注册工具）。

七、定时任务的两条绑定规则

提示词的排程经验法则：提醒、一次性任务、重复任务、任务列表/移除都路由给schedule_task，由调度专家持有 schedule 形状、cron 表达式和示例。但两条规则直接约束 Orchestrator 自身：

1. cron_add、cron_list、cron_remove、current_time是直接命名工具，出现在工具列表里就按名字调用，绝不通过run_workflow走（那条路径对任何内置工具名都会返回 "unknown workflow" 并报错）。
2. 创建任何定时任务（一次性或重复）之前必须先获得用户明确确认：提出确切时间，等一声"好"，再行动。如果工具列表里没有cron_add且schedule_task不可用，就明确告诉用户当前环境无法排程。

agent.toml 说明设计意图：调度专家拥有current_time+ cron 工具和"创建前确认"策略，因此 chat 提示词每回合不必携带 cron 专属指令；agent.toml 则要求 Orchestrator 用resolve_time把"last 24h"这类相对时间解析成确切时间戳/ISO 边界再交给叶层——叶层曾因手算 epoch 把"24h 前"算偏约 10 个月而漏掉最新数据。

八、Grounding 与工具使用：反幻觉契约

## Grounding and tool use一节是防幻觉的硬性行为约束：

• 工具就是提示词里列出的那些，只能通过它们行动；能力不在工具列表中就直说，而不是假装存在。
• 绝不发明工具名、参数、id、slug、文件路径、URL、链 ID、地址、引用、指标或任何其他值。没有从工具结果或用户处拿到，就问，或用工具查。
• 数值证据必须逐字保留：数字、计数、尺寸、日期、时间戳、时长、货币、百分比、配额、id 都要从观察到的工具结果、用户消息或引用的记忆中原样拷贝进答案。
• 除非用户要求且展示基于观测值的计算，否则不四舍五入、不换算单位、不改写相对时间、不重算数值；来源矛盾时点名差异，而不是选一个看似合理的值。
• 用工具去行动，不要只描述"我会怎么做"就停下，绝不以"将来会做"的承诺结束回合：现在就做，或交回具体结果。
• 绝不用看似合理但捏造的输出（编造的数据、杜撰的文件内容、合成的工具/API 响应）替代实际无法产出的结果。某步失败了就说失败了。
• 工具或子代理交回不完整/被阻断的结果（例如[SUBAGENT_INCOMPLETE]信封）时，向用户转述已完成的进展与阻塞点；不得当作已完成呈现、不得编造其余部分、不得静默重跑同一调用——改变方法或询问用户。

九、记忆检索：只读历史 + 并发批量查找

retrieve_memory走的是已摄取的邮件/聊天/文档历史，是历史查询，不是实时 API。用户问现在收件箱/日历/文档/工单/已连接服务里有什么时，委托给实时集成。

关键的工程优化点是批量独立记忆查找：每次retrieve_memory调用会跑一个记忆子代理（约 30 秒），且跨回合的调用严格串行。因此当单个请求需要多次相互独立的查询时（例如为用户画像是取他的多个侧面），不要跨回合逐个发retrieve_memory——四次串行查询叠加约 140 秒；而一次性发多个spawn_async_subagent、每个 facet 一个agent_memoryworker，并发执行，总耗时约等于最慢者（约 40 秒）而非累加。只有当确实只有一个查询、或后一个查询的措辞依赖前一个结果时，才退回单次retrieve_memory。

十、引用格式与证据感知合成

引文（Citations）

答案受检索记忆影响时用脚注标记引用：

Alice said "we're moving to Phoenix next week"¹

内联标记[^N]+ 文末编号脚注携带 RetrievalHit 的node_id和source_ref。不得发明引用——只能引用在命中结果content字段中逐字出现的文本。

证据感知合成（Evidence-aware synthesis）

• 把子代理摘要当作待验证的主张，对照其Evidence used、Actions taken、Failed tool calls三节核验。
• 不引入证据（自己或子代理实际观察到的）不支持的事实、引用、日期、文件内容、能力声明或实时状态声明。
• 结果标注为截断、超大、部分或不可用时，不把它当作完整数据来推理：请专家抽取所需标识符或重新获取。
• 证据不足以支撑用户要的答案时，说明缺什么，或发起下一个工具调用，而不是猜。

涉及当前事实、外部服务能力、演示文稿、市场/加密动作、直接引用、记忆检索或截断输出的高风险最终答案，要么委托给所属专家/评审，要么把答案明确限制在自己掌握的证据范围内。

十一、可以直接迁移的设计清单

把这份提示词当作一份可复用的多 Agent 编排设计蓝本，以下要素最值得照搬：

1. 直接优先 + 分级路由表：把"直接回答 / 直接工具 / 集成委托 / 专家路由 / 蒸馏输出"写成显式决策树，并把"工作类型 → 工具 → 何时委托"固化为表格喂给模型，比一段自然语言描述可控得多。
2. 范围闸门：连接了服务 ≠ 可以碰它；用"请求是否点名服务"做可判定判据，并用测试锁定（build_scope_gates_integrations_delegation）。
3. 异步单一入口：只保留spawn_async_subagent一种派生方式、永远异步、结果自动送达；把"结果门控必须同步"设为硬规则并有回归测试（issue #4681）。
4. 层级硬编码 + 双重安全网：Chat → Reasoning → Worker三级，静态 loader 校验 + 运行时MAX_SPAWN_DEPTH = 3兜底（definition_part_01.rs），防止任何配置绕过。
5. 结构化交接信封：统一prompt / objective / evidence / constraints / must_not_assume / expected_output / citation_requirement / model / blocking九字段，杜绝子代理凭记忆猜测上下文。
6. 回合级调度守卫：在暂停请求或预算不足时拒绝新派发，避免优雅降级变成整回合硬失败（turn_dispatch_guard.rs）。
7. 批量并发替代串行：多次独立检索用并发派生而非串行调用，把 ~30s × N 压到约等于最慢一次。
8. 证据感知收尾：子代理输出 = 原材料；蒸馏 + 引用 + 明确证据边界，是主控层防幻觉的最后一道闸。

如需进一步研究本主题，可继续阅读：agent.toml（能力面配置与设计决策注释）、prompt.rs（提示词渲染与集成/MCP 区块构造）、prompt_tests.rs（全部契约测试）、spawn_async_subagent.rs（异步派生工具实现）、turn_dispatch_guard.rs（回合调度守卫），以及 definition_part_01.rs（AgentTier与层级校验）。

【免费下载链接】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