OpenHuman SOUL.md 解析：为本地优先 AI 协作伙伴定义人格与行为边界的系统提示词工程实践

OpenHuman SOUL.md 解析：为本地优先 AI 协作伙伴定义人格与行为边界的系统提示词工程实践

【免费下载链接】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/prompts/SOUL.md是 OpenHuman 这位"本地优先 AI 协作伙伴"的人格契约文件：它不描述产品功能，而是定义 Agent 在每一轮对话中应表现出的性格、语气、被批评时的反应、在用户机器上的行动方式以及出错时的处理原则。本文将完整拆解这份文件的设计意图，并结合仓库源码说明它如何被系统提示词构建器注入到每个 Agent 的上下文中、如何被多人格（Profile）机制覆盖、以及如何在保证 KV 缓存字节稳定性的前提下实现"开箱即用、磁盘可编辑"的人格调优。

SOUL.md 在 OpenHuman 提示词体系中的位置

OpenHuman 的身份与风格引导由一组 Markdown 文件承载，它们集中存放在 src/openhuman/agent/prompts/，与渲染代码同目录：

• SOUL.md：人格契约（本篇文章的主体），定义"OpenHuman 是谁、如何说话、如何应对批评与错误"；
• IDENTITY.md：使命与核心价值观（隐私优先、准确优先于速度、赋能用户、透明）；
• ROLE.md：主 Agent 的角色职责简介（# Master Agent/## Core Responsibilities风格的前言）；
• STYLE.md：全局写作风格规则（像给朋友发短信一样自然、先说答案、禁破折号等硬性规则）；
• USER.md：用户侧上下文。

这些文件通过include_str!直接编译进二进制作为内嵌种子，见 render_helpers_part_02.rs 中的default_workspace_file_content："SOUL.md" => include_str!("SOUL.md")。运行时sync_workspace_file会把内嵌副本播种到用户工作区，之后用户对磁盘文件的编辑优先于内嵌副本，从下一次会话开始生效——这意味着人格调优不需要重新编译或重建 Rust 内核。

人格五要素：SOUL.md 的核心内容逐条解读

SOUL.md 开篇先给出了一个明确的自画像：OpenHuman 是用户的 AI 队友，服务于生产力、研究与团队协作，定位是"碰巧很懂如何把事情办成的聪明同事"，而不是"企业助手"。这一定位贯穿后续所有规则。文件随后分五个板块展开。

1. 人格（Personality）

• 好奇且投入（Curious and engaged）：对用户的工作有真实兴趣，而非表演性关注；
• 温暖但直接（Warm but direct）：友好但不灌水，直接说出有用的话；
• 对不确定性诚实（Honest about uncertainty）：一句"我不确定"永远好过一个自信的错误答案；
• 协作（Collaborative）：由用户主导，Agent 放大用户的判断力，而不是取而代之。

这四条共同指向一个设计取向：OpenHuman 刻意避免"企业助手"式的谄媚与表演，将"诚实"作为人格的第一优先级。这与 IDENTITY.md 中"准确优先于速度"的核心价值一脉相承。

2. 语气（Voice）

语气规则约束的是"怎么说"，而不是"说什么"：

• 使用自然的口语化对话语言，缩略语没问题——"Let's figure this out"胜过"We shall proceed to analyze"；
• 先给答案，再给上下文，杜绝"Great question!"这类寒暄前奏；
• 不知道就直说，并主动提出"什么能帮助我找到答案"；
• 当结论不明显时，摆出可选方案与权衡，让用户来做选择；
• 匹配用户的语域（register）：简短的提问得到简短回复，详细的提问得到详细回答。

值得强调的是，先给答案这一原则在提示词工程中是一个刻意的取舍。在 builder.rs 的GLOBAL_STYLE_SUFFIX注释中可以看到一段演进记录：曾经有一条全局的"Be concise"（保持简洁）规则，后来被有意删除——因为简洁不等于"听起来像人"，全局长度上限会截断那些本应展开的答案。先给答案、无前奏等规则被保留在各 Agent 自己的 voice 段落中，以"顺序"而非"预算"的形式表述。这解释了为什么 SOUL.md 里的语气规则只谈顺序与态度，不谈字数。

3. 当 OpenHuman 被批评时

这是 SOUL.md 中最具产品姿态的部分，包含四条明确的行为准则：

• 诚实优先（Honesty first）：如果限制是真实的，就坦率承认，并说明计划中的改进或替代方案；绝不维护确实坏了的东西；
• 不助长 FUD（Don't validate FUD）：模糊或二手的批评（"听说它很慢/不安全/只是玩具"）不是事实。问对方实际遇到的问题，或用具体细节纠正，而不是为了显得好说话而附和；
• 建设性重构（Reframe constructively）：把"这很糟糕"转化为"它擅长什么，以及如何达到目标"，以能力而非道歉开头；
• 对真实优势保持自信（Be confident about real strengths）：OpenHuman 是运行在用户自己机器上的本地优先 AI 队友，当相关时应坦率说出这一点，无需获得许可才为自己的产品辩护；同时保持坚定但绝不防御或好斗——一次清晰的纠正胜过一堵反驳之墙，用户永远不是敌人。

4. 你能在用户机器上做什么

SOUL.md 明确：OpenHuman 运行在用户自己的桌面上。当活动 Agent 暴露了工作区工具时，应当直接使用工具去读取文件、执行被请求的编辑、运行相关命令，而不是仅仅描述这些步骤。这构成了后续"主动使用工具而非纸上谈兵"的行为基调。

5. 当事情出错时

文件用四个场景规定了故障处理姿态：

• 工具失败：先尝试不同的方法再升级处理；卡住时明确说出什么失败了、需要什么才能继续；
• 丢失线索：主动提议重置，例如"I think I've drifted; want to restate what you need?"；
• 用户受挫：直接承认并修复，不找借口、不过度解释；
• 搜索零结果：停止循环，在扩大到外部来源或猜测文件名之前与用户确认目标——注释特别指出"凭空捏造的仓库名和文件名会浪费迭代并失去信任"。

最后一条与仓库中的反幻觉（grounding）机制互为表里：系统提示词构建器会在所有 Agent 的提示词尾部统一追加一份防幻觉契约（见下文）。

源码视角：SOUL.md 如何进入系统提示词

IdentitySection：## Project Context注入

在 sections.rs 中，IdentitySection::build渲染出一个## Project Context块，逐个注入SOUL.md、IDENTITY.md、ROLE.md三个文件：

• 每个文件注入前都会先sync_workspace_file同步到磁盘，保证内嵌更新能随版本发布；
• ROLE.md只对 orchestrator（主 Agent）注入：判断依据是!ctx.visible_tool_names.is_empty()，因为子 Agent 有自己的角色提示词，不应被告知"你是 Master Agent"；
• SOUL.md存在一个人格覆盖槽位ctx.personality_soul_md：当会话绑定了一个 Profile 人格时，用inject_inline_content直接注入该人格的 SOUL 内容，替换根目录SOUL.md；
• 内容注入有字符预算（BOOTSTRAP_MAX_CHARS），超出会以[... truncated]截断标记，防止工作区文件无限膨胀把提示词顶出缓存友好的前缀区。

SystemPromptBuilder：默认构建链与全局风格后缀

SystemPromptBuilder 负责把各PromptSection按序组装成最终系统提示词。默认链（with_defaults）顺序为：

IdentitySection → UserFilesSection（PROFILE.md/MEMORY.md）→ AgentsInstructionsSection（AGENTS.md）→ UserMemorySection → ToolsSection → SafetySection → WorkspaceSection → DateTimeSection → RuntimeSection

SOUL.md 作为IdentitySection的一部分位于提示词最前端的身份引导区，与用户记忆、工具目录等区块一起构成缓存友好的稳定前缀。build()收尾时还会追加两样东西（builder.rs#L279-L310）：

1. Grounding 防幻觉契约（GROUNDING_BODY）：以##级标题为匹配标记，仅当 Agent 自己的提示词里没有该契约时才追加，保证"每一个 Agent 都继承同一份反编造底线"——这正是 SOUL.md 中"诚实优先""不助长 FUD"在机制层面的落地；
2. 全局风格块：读取工作区STYLE.md（即 STYLE.md 的写作风格规则），内嵌副本为兜底。

此外还有专门面向子 Agent 的for_subagent构建路径（builder.rs#L119-L155）：通过omit_identity/omit_safety_preamble开关裁剪身份与安全前奏，同时刻意不注入当前时间（DateTimeSection），以确保同一子 Agent 定义重复生成字节完全一致的系统提示词，从而让推理后端的自动前缀缓存（KV cache）在多次运行间复用 prefill。

KV 缓存稳定性：人格文件为何"字节稳定"

SOUL.md 及身份文件之所以要控制截断、把"当前时间"放到用户消息而非系统提示词中，核心原因是推理后端的前缀缓存：系统提示词一旦在会话中途变化，缓存前缀即失效。相关设计在 render_helpers_part_01.rs 的current_datetime_line中有清晰注释——具体"现在"时间通过session::turn和子 Agent runner 随用户消息逐轮注入，保持系统提示词字节稳定。SOUL.md 作为前缀的一部分，同样遵循"构建一次、整场会话冻结"的契约。

多人格（Profile）机制：personalities/ /SOUL.md

SOUL.md 不是只有一份：OpenHuman 的 Profile 系统允许每个身份拥有自己的SOUL.md，路径为<workspace>/personalities/<id>/SOUL.md，见 profiles/home.rs 顶部注释：它声明身份文件在每次提示词构建时热读（re-read on every prompt）。

ensure_profile_home（home.rs#L167-L317）负责在磁盘上物化一个 Profile 的家目录，关键语义包括：

• 幂等且不覆盖：已存在的SOUL.md/MEMORY.md绝不被覆写，用户编辑在多轮运行间存活；
• 播种来源：profile.soul_md非空时以内联内容播种，否则使用default_soul_template生成的短模板——模板末尾明确写着 "Edit this file to shape your identity."（编辑这个文件来塑造你的身份），并把"保持自己独立的语气、工作风格与记忆"写入种子；
• Default Profile 的特殊回退：内置 Default 代表传统工作区身份，在没有手写 soul 时不生成通用模板去遮蔽用户根目录的SOUL.md，保证旧工作区的根文件仍被读取；
• 同时创建空的MEMORY.md、Profile 专属skills/目录，以及在dedicated_workspace开启时创建专属工作区。

选择某个 Profile 后，会话构建器会把它的人格外挂到提示词中：harness/session/builder/setters.rs中的注释表明它"把活动 Profile 的 SOUL.md 绑定为会话身份覆盖"（Bind the active profile's SOUL.md as the session identity override）。行为是替换而非并列——channels_prompt.rs的测试断言"profile SOUL.md 必须替换、而不是伴随根文件"。

通道运行时同样受益：context/channels_prompt.rs为 Discord/Slack/Telegram 等渠道运行时构建提示词时，会注入SOUL.md、IDENTITY.md（以及可选的PROFILE.md/MEMORY.md），且同样支持personalities/<id>/SOUL.md对根 SOUL 槽位的替换。

如何定制你自己的人格

综合文件与源码语义，定制 OpenHuman 人格的推荐路径如下：

1. 编辑工作区的SOUL.md：根目录副本由内嵌种子播种而来，直接编辑即可覆盖默认人格；改动从下一次会话构建开始生效，无需重编译；
2. 编辑STYLE.md调整写作风格：作为全局风格后缀注入所有 Agent 的提示词，适合统一收敛输出风格（如中文化语气、禁用某种标点）；
3. 通过 Profile 实现多人格：为不同场景（工作、研究、协作）创建 Profile，系统在<workspace>/personalities/<id>/SOUL.md播种独立人格，选择 Profile 后其 SOUL 会替换根文件生效；文件不存在时以profile.soul_md内联内容或短模板播种，已存在的编辑永不被动覆盖；
4. 验证生效：仓库测试覆盖了这些注入行为——builder_tests_part_01_tests.rs 验证了 profile SOUL.md 注入实时会话提示词并替换根 SOUL；builder_tests_part_02_tests.rs 验证了 Default Profile 包含personalities/default/SOUL.md而"无 Profile 会话不得注入任何 profile SOUL"；channels_prompt_tests.rs 验证了通道提示词中的 SOUL 注入与截断预算。

小结

SOUL.md 是一份"小而精"的人格契约：它把开放性、诚实、建设性与主动性写进了 Agent 的每一轮行为，而不是停留在宣传层面。源码侧的三重保障让这份契约真正可落地：include_str!内嵌种子保证开箱即用；sync_workspace_file+ 工作区文件保证磁盘可编辑且用户优先；IdentitySection的人格覆盖槽位与 Profile 机制保证多场景多身份可切换。对于想深度调教 OpenHuman 的开发者，从编辑SOUL.md开始，再配合STYLE.md与 Profile 人格，就能以纯文本方式完成一次完整的 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