OpenHuman Context Scout 深度解析只读预检代理如何用[context_bundle]为编排器压缩上下文【免费下载链接】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 内置代理 Context Scoutcontext_scout展开它是一类只读预检read-only pre-flight代理在被编排器orchestrator执行首轮任务之前先以极低成本完成记忆、用户画像、已连接集成与联网信息的收集并返回一个紧凑的[context_bundle]数据包。读完本文你将掌握该代理的三段式工作流、六大只读信息源、输出契约的每个字段语义以及它在 agent.toml 与 prompt.rs 中的实现细节与安全设计。一、设计定位为什么需要预检代理在 OpenHuman 的多代理架构里编排器承担思考并行动的职责但它每轮可用的上下文窗口是有限的。如果每收到一个用户请求编排器都自行去翻记忆、查技能、扫集成列表既浪费 token也容易把上下文撑爆。Context Scout 的定位正是把收集上下文这一步从编排器中剥离出来、前置到一个廉价只读代理上。从 agent_prepare_context.rs 的模块注释可以看到两种触发方式agent harness 首轮前自动触发在编排器第一个 turn 之前harness 先跑一次 Context Scout 完成预检父代理显式请求父代理通过调用agent_prepare_context工具plan mode as a subagent同步地、阻塞式地跑一遍 Context Scout获得一次临时ad hoc上下文收集。无论哪种方式Scout 的输出都受max_result_chars约 1000 tokens上限约束因此父代理的上下文只会以有界的方式增长——这正是该设计的核心收益用一次廉价预检换取编排器后续每一轮都站在信息充分的起点上。二、工作流程收集 → 汇总 → 推荐然后立即停止Scout 的角色提示词 prompt.md 明确给出了三段式工作流读取请求读取传入的请求以及调用方可能附加的[Focus]指令明确本次预检的靶心。只读收集仅收集采取行动真正需要的信息而不是漫无目的地罗列。及时停止一旦信息足够就立即产出结果——绝不尝试回答请求或执行任务那是编排器的职责。Scout 拥有的每个工具都是只读的它从不写、不发送、不安装、不执行任何动作。这一点在 agent.toml 中有硬约束兜底sandbox_mode read_only并且工具白名单全部是只读工具详见第五节。从源码结构看Scout 被声明为agent_tier worker的叶子 worker它只收集并停止从不向下委托没有[subagents]块加载器会在 worker 层拒绝任何子代理。三、六大只读信息源Scout 的收集面覆盖六个来源每一条都映射到具体的只读工具信息源工具/载体用途与注意点记忆Memorymemory_recall按 namespace query 检索memory_flavour读取用户风格/偏好画像的一个 facet只读绝不能写记忆。memory_flavour的 facet 包括 communication、coding_style、stack、workflow、environment、directives、anti_preferences当请求依赖用户喜欢怎么工作而非某个具体事实时优先使用它历史对话Past conversations经由memory_recall间接访问thread_*系列与transcript_search工具已被移除因此用户之前说过什么只能通过记忆检索触达而不是线程索引目标/画像Goals / profile注入在 prompt 中的PROFILE.md与MEMORY.md这两份用户文件会随系统提示词一起注入omit_profile false、omit_memory_md falseScout 直接从中挖掘用户声明的目标与偏好技能Skillslist_workflows列出已安装技能skill_registry_search/skill_registry_browse检索技能注册表若技能明显契合请求则在recommended_skills中上报交由编排器运行或安装已连接集成Connected integrations系统提示词中的 Connected Integrations 区块直接告诉 Scout 哪些平台gmail、notion、slack 等真实接线可用用于判断请求是否可由某个已连接应用处理网络The webweb_search_tool/web_fetch仅当请求真正依赖新外部事实时才使用记忆/画像已覆盖时跳过——Scout 被要求保持廉价cheap其中记忆检索的底层实现与编排器的记忆工具同源Scout 的memory_recall走的是 memory/api/provider/retrieval.rs 提供的检索能力该模块同时承载FastRetrieveQuery快路径命中数上限为MEMORY_FAST_PATH_LIMIT 8但 Scout 侧只暴露只读接口。四、输出契约严格单一[context_bundle]数据块Scout 的产出被约束为唯一一个[context_bundle] … [/context_bundle]数据块块外不允许有任何前言或收尾散文。其完整模板如下[context_bundle] has_enough_context: true|false proposed_goal: ONE single line — the durable objective this thread should pursue (what done looks like), or none for a trivial/one-shot request that needs no goal. Keep it on this one line; the harness only reads the text on the same line as proposed_goal:. summary: ≤ ~700 tokens of distilled, source-attributed context. Lead with what matters. Attribute facts: (memory), (transcript: thread), (profile), (web: url), (integrations). recommended_tool_calls: - tool: exact orchestrator tool name from the Orchestrator tools list args: concrete arg values or a tight sketch why: one line recommended_skills: - skill: runnable id — for installed skills the dir_name slug from list_workflows (NOT the display name), since run_workflow resolves by that id; for registry hits the installable entry id from skill_registry_search installed: true|false why: one line — why this skill fits the request [/context_bundle]各字段语义如下has_enough_contexttrue表示编排器此刻即可行动、无需再收集false表示关键事实仍缺失须在 summary 中说明缺什么。proposed_goal线程的持久目标完成的样貌而非步骤清单。harness 仅在线程尚未设置目标时才将其记录为线程目标——编排器仍保有权威并可后续细化。对闲聊或一次性琐碎请求填写none即可不值得记录目标。注意该字段的解析约定harness 只读取proposed_goal:同一行上的文本因此目标必须压缩在单行内。summary不超过约 700 tokens 的蒸馏摘要要求先讲重点并为每条事实标注来源(memory)、(transcript: thread)、(profile)、(web: url)、(integrations)。recommended_tool_calls按编排器应执行的顺序排列的推荐调用。每个tool必须是下方注入的 Orchestrator tools 列表中的精确名称——这些是编排器能调的工具而不是 Scout 自己用过的工具。若已信息充分且答案属知识型、无需更多调用则返回空列表并置has_enough_context: true。recommended_skills明确契合请求的技能工作流清单。已安装技能使用可运行 id——即list_workflows返回的dir_nameslug而非显示名因为run_workflow按该 id 解析installed: true注册表命中的技能使用skill_registry_search返回的可安装条目 idinstalled: false。仅当技能真正匹配时才包含否则整节省略或留空绝不虚构技能 id。整个 bundle 有预算上限应把预算花在 summary、plan 与真正匹配的技能上而不是含糊其辞的修饰语上。五、agent.toml配置逐项剖析agent.toml 是 Scout 的完整定义文件关键配置项如下id context_scout display_name Context Scout when_to_use Pre-flight context collector. Reads memory, the users goals/profile, connected integrations, and the web, then returns a tight context bundle plus a recommended plan of next tool calls. Read-only; produces a structured bundle, not actions. temperature 0.3 max_iterations 8 iteration_policy extended max_result_chars 5000 sandbox_mode read_only agent_tier worker omit_identity true omit_memory_context true omit_safety_preamble true omit_profile false omit_memory_md false [model] hint burst [tools] named [ ... ]temperature 0.3低随机性保证预检输出稳定、可复现。max_iterations 8、iteration_policy extended注释说明从 6 提升到 8——Scout 如今拥有更宽的只读收集面transcripts、threads、skills需要多几步完成recall → check skills → assess再产出 bundle 的循环。max_result_chars 5000返回 bundle 的字符上限char-safe。runner 在交还给父代理前会把最终输出截断到这个长度从而保证编排器上下文只增长有界量。该值从 4000 提升为recommended_skills块与 summary、recommended_tool_calls留出空间。sandbox_mode read_only沙箱只读配合工具白名单构成双重防护。agent_tier worker叶子 worker 层级禁止向下再委托子代理。四个omit_*开关omit_identity true、omit_memory_context true、omit_safety_preamble true去掉身份、通用记忆上下文与安全前言但omit_profile false、omit_memory_md false保留PROFILE.md用户声明的目标与MEMORY.md档案员策展的长期记忆注入——因为 Scout 的整个职责就是让编排器扎根于用户是谁、想要什么。[model] hint burst多步收集循环recall → 可能 fetch → assess走高通量的burst层托管后端解析为burst-v1。设计意图是Scout 是廉价、延迟容忍、非推理的预检高速模型上的原始吞吐优于更贵的 agentic/reasoning 层。工具白名单的取舍艺术[tools].named是精心策展的只读收集面没有写工具、没有 shell、没有委托。特别值得注意的是memory_tree被故意排除该工具在一个 ReadOnly 声明的包装器下捆绑了写模式ingest_document→MemoryTreeIngestDocumentTool若 Scout 自动运行在可注入的输入上一旦拿到该工具就可能边运行只读、边改写记忆remember this document——这等于给提示注入留下立足点。因此用纯检索的memory_recall覆盖需求。同理skill_registry_install/skill_registry_uninstall被刻意挡在白名单外只保留三个只读技能工具。六、系统提示词构建prompt.rs的组装流程prompt.rs 负责在运行时把角色 Markdown 与动态注入块拼装成最终系统提示词。其build()流程为以include_str!(prompt.md)加载角色提示词即本文解析的这份文档本体调用render_user_files注入PROFILE.md与MEMORY.md由include_profile/include_memory_md门控runner 依据定义的omit_profile false/omit_memory_md false设置调用render_tools渲染 Scout 自己的只读工具目录调用render_connected_integrations渲染## Connected Integrations区块——只列出connected true的平台空连接时整块省略见prompt_tests.rs的render_connected_integrations_lists_only_connected测试调用render_workspace追加工作区块。而编排器的工具目录Scout 推荐回去的那份不在这里注入——它由AgentPrepareContextTool在 spawn 时注入prompt.rs只描述 Scout 自身的收集面。二者职责分离非常清晰。七、与编排器协作的两个实现细节1. 跳过通用子代理结果契约通用子代理会被追加一个 Result Contract 后缀Answer / Evidence used / Actions taken / Open uncertainties / Failed tool calls / Recommended next step。但在 subagent_runner/ops/prompt.rs 的append_subagent_role_contract中对context_scout做了特判跳过因为 Scout 定义了自己的严格输出契约只发一个[context_bundle]通用契约会与之冲突导致 Scout 输出通用标题而非 bundle使编排器拿不到has_enough_context/recommended_tool_calls。2. 有界上下文注入agent_prepare_context.rs 明确记载Scout 的输出被max_result_chars约束到约 1000 tokens父代理上下文只增长有界量。结合 runner 中的截断逻辑这是整个预检设计能够规模化运作的保障。八、测试验证与质量保障prompt_tests.rs 锁定了以下行为build_returns_nonempty_body构建的提示词非空body_describes_the_context_bundle_contract提示词必须包含[context_bundle]、has_enough_context、recommended_tool_calls契约关键词body_instructs_transcript_and_skill_gathering提示词必须指引通过memory_recall检索历史对话因thread_*/transcript_search已移除、必须定义recommended_skills输出块、必须指向list_workflows技能发现render_connected_integrations_*集成区块只列已连接平台全空时返回空字符串。这些测试与 loader.rs 中对context_scout的定义加载校验、以及agent_prepare_context_tests.rs对显式调用路径的测试共同构成质量网防止后续改动悄悄破坏预检契约。九、延伸阅读代理定义与注册loader.rs、agents/mod.rs提示词构建基础设施src/openhuman/agent/context/prompt.rsrender_tools、render_user_files、render_workspace、ConnectedIntegration等均在此显式调用工具agent_prepare_context.rs 及其测试子代理运行器subagent_runner/ops/runner.rs层级门控tier_gate_decision与迭代预算、subagent_runner/ops/prompt.rs契约跳过逻辑记忆检索后端src/openhuman/memory/api/provider/retrieval.rs小结Context Scout 是 OpenHuman 多代理体系中以廉价预检换有界上下文的关键实践一条严格的角色提示词 一份精心配置的agent.toml 一个模板化构建器共同保证了它只收集、不行动、产出唯一[context_bundle]并把下一步该调用编排器的哪些工具以结构化形式交还父代理。理解它也就理解了 OpenHuman 如何在多代理协作中控制上下文成本与注入面。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考