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_contentSOUL.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语气规则约束的是怎么说而不是说什么使用自然的口语化对话语言缩略语没问题——Lets 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如果限制是真实的就坦率承认并说明计划中的改进或替代方案绝不维护确实坏了的东西不助长 FUDDont validate FUD模糊或二手的批评听说它很慢/不安全/只是玩具不是事实。问对方实际遇到的问题或用具体细节纠正而不是为了显得好说话而附和建设性重构Reframe constructively把这很糟糕转化为它擅长什么以及如何达到目标以能力而非道歉开头对真实优势保持自信Be confident about real strengthsOpenHuman 是运行在用户自己机器上的本地优先 AI 队友当相关时应坦率说出这一点无需获得许可才为自己的产品辩护同时保持坚定但绝不防御或好斗——一次清晰的纠正胜过一堵反驳之墙用户永远不是敌人。4. 你能在用户机器上做什么SOUL.md 明确OpenHuman 运行在用户自己的桌面上。当活动 Agent 暴露了工作区工具时应当直接使用工具去读取文件、执行被请求的编辑、运行相关命令而不是仅仅描述这些步骤。这构成了后续主动使用工具而非纸上谈兵的行为基调。5. 当事情出错时文件用四个场景规定了故障处理姿态工具失败先尝试不同的方法再升级处理卡住时明确说出什么失败了、需要什么才能继续丢失线索主动提议重置例如I think Ive 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 AgentSOUL.md存在一个人格覆盖槽位ctx.personality_soul_md当会话绑定了一个 Profile 人格时用inject_inline_content直接注入该人格的 SOUL 内容替换根目录SOUL.md内容注入有字符预算BOOTSTRAP_MAX_CHARS超出会以[... truncated]截断标记防止工作区文件无限膨胀把提示词顶出缓存友好的前缀区。SystemPromptBuilder默认构建链与全局风格后缀SystemPromptBuilder 负责把各PromptSection按序组装成最终系统提示词。默认链with_defaults顺序为IdentitySection → UserFilesSectionPROFILE.md/MEMORY.md→ AgentsInstructionsSectionAGENTS.md→ UserMemorySection → ToolsSection → SafetySection → WorkspaceSection → DateTimeSection → RuntimeSectionSOUL.md 作为IdentitySection的一部分位于提示词最前端的身份引导区与用户记忆、工具目录等区块一起构成缓存友好的稳定前缀。build()收尾时还会追加两样东西builder.rs#L279-L310Grounding 防幻觉契约GROUNDING_BODY以##级标题为匹配标记仅当 Agent 自己的提示词里没有该契约时才追加保证每一个 Agent 都继承同一份反编造底线——这正是 SOUL.md 中诚实优先不助长 FUD在机制层面的落地全局风格块读取工作区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.mdSOUL.md 不是只有一份OpenHuman 的 Profile 系统允许每个身份拥有自己的SOUL.md路径为workspace/personalities/id/SOUL.md见 profiles/home.rs 顶部注释它声明身份文件在每次提示词构建时热读re-read on every prompt。ensure_profile_homehome.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 profiles 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 人格的推荐路径如下编辑工作区的SOUL.md根目录副本由内嵌种子播种而来直接编辑即可覆盖默认人格改动从下一次会话构建开始生效无需重编译编辑STYLE.md调整写作风格作为全局风格后缀注入所有 Agent 的提示词适合统一收敛输出风格如中文化语气、禁用某种标点通过 Profile 实现多人格为不同场景工作、研究、协作创建 Profile系统在workspace/personalities/id/SOUL.md播种独立人格选择 Profile 后其 SOUL 会替换根文件生效文件不存在时以profile.soul_md内联内容或短模板播种已存在的编辑永不被动覆盖验证生效仓库测试覆盖了这些注入行为——builder_tests_part_01_tests.rs 验证了 profile SOUL.md 注入实时会话提示词并替换根 SOULbuilder_tests_part_02_tests.rs 验证了 Default Profile 包含personalities/default/SOUL.md而无 Profile 会话不得注入任何 profile SOULchannels_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考