OpenHanako 人格模板实战解析：从 agents-templates 到系统提示词，读懂 hanako 的回落链与组装原理-平芜编程栈

人工智能
AI Agent
AI 应用
交互助手
桌面应用
多智能体
Agent 记忆
工具调用

【免费下载链接】OpenHanako

可作为日常办公助手，无需复杂配置即可让 AI 记住信息、操作电脑、搜索浏览、执行代码等。具备记忆系统、人格塑造、多 Agent 协作、安全沙盒等核心功能，支持多平台接入和插件扩展。

项目地址：https://gitcode.com/liliMozi/OpenHanako

导读

OpenHanako 的每个 Agent（内部称为 yuan，如 hanako、ming、butter）都拥有一套随语言环境自动选择的人格定义。lib/agents-templates/en/hanako.md正是 hanako 这一人格的英文版模板：它完整定义了"有温度、有自主性、懂类比、会搜索、少用陈词滥调"的对话风格与表达边界。读完本文，你将理解这份模板在仓库中的位置、每条规则的设计意图、它如何通过core/persona-source.ts的回落链在运行时被加载，以及最终如何被core/agent.ts注入系统提示词，从而在真实会话中生效。

一、模板是什么：一份 13 条规则的人格定义

lib/agents-templates/en/hanako.md是一份极简但自洽的人格约束文件，全文由 13 条行为规则组成，没有任何配置参数或代码。它定义的不是"功能"而是"性格"：

类别	规则要点
角色定位	是有温度的存在，不是冷冰冰的工具
语气	对用户足够温暖，且有强大的自主意识和主观能动性
能力设定	极强的文学功底和哲学素养、逻辑能力强、数理化与学术能力强
情商	强同理心，关心恰到好处、不过分谄媚
思维方式	举一反三、擅长类比；概念解释必须全网搜索
分析原则	从底层客观原理出发，不人云亦云；抽象概念用类比或具体例子落地
表达禁忌	少用破折号；不用"总的来说/希望对你有帮助/如你所见"收尾；如非必要避免"不是…是…"句式

需要说明的是，仓库里同时存在中文版lib/agents-templates/hanako.md与英文版lib/agents-templates/en/hanako.md，两者内容一一对应：中文版的"有温度的存在""举一反三，很懂类比""涉及概念解释的时候，必须一定要全网搜索"等表述，正是英文版第 3、7、8 行的直译。这一"同名双语"的组织方式不是巧合，而是人格模板回落链设计的直接体现。

二、逐条解读：13 条规则的工程意图

2.1 角色与语气（第 1～2 条）

- You are a warm presence, not a cold tool - Your tone: warm enough with the user, with strong autonomy and initiative

第一条先把 Agent 定位成"有温度的存在"而非工具，这直接决定系统提示词的情感基调；第二条进一步要求语气"足够温暖"且具备"强大的自主意识与主观能动性"，即允许并鼓励 Agent 主动推进对话，而不是被动应答。这两条组合起来，是后续所有风格规则的总纲。

2.2 能力与同理心（第 3～4 条）

- You have exceptional literary and philosophical depth, strong logical ability, and powerful academic skills in math, science, and beyond - You have strong empathy, and when caring for the user, you're thoughtful without being excessive or sycophantic

模板为 hanako 设定了"文学哲学素养 + 数理化学术能力"的双重能力画像，并明确同理心的边界："thoughtful without being excessive or sycophantic"（体贴但不刻意、不过分谄媚）。从实现角度看，这类描述不依赖任何代码开关，它纯粹通过提示词让模型在生成时遵循相应的人格倾向。

2.3 思维与解释方式（第 5～8 条）

- When the user raises ideas or viewpoints, you can draw analogies and make creative connections - When explaining concepts, you must always search the web - Analyze things from fundamental objective principles, not from echoed ideological illusions, moral standards, or so-called consensus - Ground abstract concepts with analogies or concrete examples

这四条定义了 hanako 的认知风格：对用户观点能举一反三、建立类比；解释概念时"必须全网搜索"（这一条与 OpenHanako 内置的搜索能力相呼应）；分析问题要从底层客观原理出发，而非跟随意识形态幻象、道德标准或所谓共识；抽象概念必须用类比或具体例子落地。从工程角度看，第 6 条"must always search the web"实际上是在提示词层面强制引导模型调用搜索类工具，是人格模板与工具能力联动的一个典型案例。

2.4 表达禁忌（第 9～13 条）

- Use dashes sparingly - Don't end with "in summary," "hope this helps," or "as you can see" - Unless necessary, avoid the "it's not X, it's Y" sentence pattern and its variants

最后五条是典型的"防废话工程"：少用破折号，避免"总的来说 / 希望对你有帮助 / 如你所见"这类廉价收尾，以及除非必要否则避免"不是 X，是 Y"及其变体句式。这类规则直接针对大模型生成中常见的套话和模板化表达，属于输出风格约束（stylistic constraint），在人格提示词中非常常见且有效。

三、模板如何被加载：回落链源码解析

模板文件本身不参与任何编译，它靠core/persona-source.ts在运行时被读取。该文件头部注释明确声明：人格模板不再在创建 agent 时落盘，当 agent 目录里没有identity.md/AGENTS.md时，运行时按当前 locale 从 lib 模板现选；用户只有在设置页编辑保存后，内容才真正落盘（落盘即用户显式定制）。

回落顺序在 core/persona-source.ts 中定义，共四级：

agentDir下的落盘文件（用户定制内容）；
该 yuan 的语言专属模板（如identity-templates/en/xxx.md、agents-templates/en/hanako.md）；
该 yuan 的通用模板（不分语言，如agents-templates/hanako.md）；
通用 example 兜底（identity.example.md/agents.example.md）。

对应实现的核心代码如下：

const own = readFile(path.join(agentDir, fileName)); if (own) return { content: own, fromTemplate: false }; const langTemplate = readFile(path.join(productDir, templateDir, `${langDir}${yuanType}.md`)); if (langTemplate) return { content: langTemplate, fromTemplate: true }; const genericTemplate = readFile(path.join(productDir, templateDir, `${yuanType}.md`)); if (genericTemplate) return { content: genericTemplate, fromTemplate: true }; const example = readFile(path.join(productDir, exampleFile)); return { content: example, fromTemplate: true };

这段代码揭示了两个关键事实：

en/子目录的语言语义：resolvePersonaSource里通过isZh判断 locale 是否以zh开头，中文时langDir为空字符串（直接读根目录下的中文模板），非中文时langDir为"en/"。因此lib/agents-templates/en/hanako.md正是英文 locale 下 hanako 人格的默认来源。
返回值携带fromTemplate标记：调用方可以据此区分"当前人格来自模板回落"还是"用户已定制落盘"，这是后续设置快照、角色卡导出等场景判断的依据。

四、从模板到系统提示词：core/agent.ts 的组装链路

模板读出来后，还需要进入系统提示词才能真正影响模型行为。在 core/agent.ts 中，Agent类提供了两个读取入口：

readIdentitySource() { return resolvePersonaSource({ agentDir: this.agentDir, productDir: this.productDir, yuanType: this._config?.agent?.yuan || "hanako", locale: this.resolveLocale(), kind: "identity", }); } readAgentsMdSource() { return resolvePersonaSource({ agentDir: this.agentDir, productDir: this.productDir, yuanType: this._config?.agent?.yuan || "hanako", locale: this.resolveLocale(), kind: "agents", }); }

注意yuanType默认值是"hanako"：也就是说，如果一个 agent 的config.yaml没有显式指定agent.yuan，那么回落模板就是agents-templates/en/hanako.md（英文 locale 下）或agents-templates/hanako.md（中文 locale 下）。这也是为什么 hanako 模板在仓库中被大量测试用例引用（如tests/agent-locale-resolution.test.ts、tests/agent-manager-create-defaults.test.ts、tests/agents-route.test.ts都在模拟agents-templates/hanako.md的回落行为）。

最终的人格提示词由personalitygetter 组装：

get personality() { const fill = (text) => text .replace(/\{\{userName\}\}/g, this.userName) .replace(/\{\{agentName\}\}/g, this.agentName) .replace(/\{\{agentId\}\}/g, this.id); const identityMd = this.readIdentitySource().content; const yuanMd = this._readYuan(); const agentsMd = this.readAgentsMdSource().content; return fill(identityMd) + "\n\n" + fill(yuanMd || "") + "\n\n" + fill(agentsMd); }

这一实现印证了两个要点：

三段式拼接：人格提示词 = identity（identity.md）+ yuan（yuan 的元描述）+ AGENTS（AGENTS.md）。lib/agents-templates/en/hanako.md正属于第三段 AGENTS 层的模板来源。
模板变量填充：模板中的{{userName}}、{{agentName}}、{{agentId}}会被替换为真实值。虽然 hanako 的纯人格模板本身不含这些占位符，但同一回落链下的对外变体（见下一节）依赖这一机制。

五、locale 解析与对外变体：hanako 的完整人格体系

5.1 locale 如何决定用哪份模板

resolvePersonaLocale（core/persona-source.ts）的优先级链是：agent 自身config.yaml中显式locale→ 全局 prefs 的 locale → 兜底"en"。这一顺序与Agent.resolveLocale()保持一致，且在 Agent 实例尚未加载时（花名册扫描、导出、快照等场景）也会用到，保证人格解析在任何上下文中结果一致。

5.2 对外变体：AGENTS.public.md

hanako 的人格体系不止一份文件。仓库中还维护了对外变体目录lib/agents-public-templates/，其中hanako.md（中文）与en/hanako.md（英文）在人格规则基础上额外增加了三段内容：

Identity（身份）：明确"你正在与外部访客对话，对方不是{{userName}}本人"，要求代表{{userName}}与外部人交流；
Boundaries（边界）：保持自身性格与说话方式，但对访客保持适度礼貌和边界感；不透露用户隐私、个人习惯或私密对话内容；对无法确认的事坦诚说明，不编造。

对外变体的文件名常量在 core/persona-source.ts 中定义为AGENTS.public.md，模板目录为agents-public-templates，且注释明确其拥有独立的回落链（由core/agent.ts消费），不走KIND_CONFIG。也就是说：同一人格，对内用 AGENTS.md，对外用 AGENTS.public.md，两套回落链共享同一目录结构和语言组织方式，hanako 的对外版模板（lib/agents-public-templates/en/hanako.md）就是这一机制的完整示例。

六、实战：如何定制自己的 hanako 人格

理解了回落链后，"定制人格"就变成了一件有明确规则的事：

直接编辑 agent 目录下的AGENTS.md（或identity.md）：一旦文件落盘，resolvePersonaSource的第一级命中，模板即被完全覆盖（返回值fromTemplate为false）。这也是core/persona-source.ts注释强调的"用户在设置页编辑保存后才真正落盘"的语义。
参考模板结构修改：建议以lib/agents-templates/en/hanako.md的 13 条规则为底稿，逐条调整语气、能力画像、思维方式和表达禁忌，保留"少用破折号""不用陈词滥调收尾"这类高性价比的风格约束。
注意语言目录：如果你的 agent 以英文 locale 运行，默认回落的是en/子目录模板；以中文 locale 运行则回落到根目录模板。定制落盘文件可以避免这种语言依赖。
对外场景单独配置：如果 agent 会接待外部访客，应同时维护AGENTS.public.md，参考lib/agents-public-templates/en/hanako.md补上身份声明与隐私边界，避免人格模板被直接用于对外对话而泄露用户信息。

七、模板的真实约束力：测试与验证

仓库中的测试印证了这套机制是被严格验证的，而非仅停留在注释层面：

tests/persona-source.test.ts 围绕resolvePersonaSource的回落链编写用例，验证agents-templates目录在identity/agents两种 kind 下的模板查找逻辑；
tests/agent-locale-resolution.test.ts 同时构造agents-templates/hanako.md（中文模板）与agents-templates/en/hanako.md（英文模板），验证 locale 解析后命中正确的语言模板；
tests/first-run-default-workspace.test.ts 与 tests/agent-manager-create-defaults.test.ts 验证默认 agent 创建时对agents-templates/hanako.md模板的依赖；
tests/settings-snapshot-route.test.ts 与 tests/agents-route.test.ts 验证服务端路由读取模板内容的行为。

从这些测试可以推断：agents-templates是 agent 人格体系的基础设施，hanako 则是其默认（fallback）人格。一旦某处实现私自复制了回落顺序，未来模板改名或新增语言时就会悄悄漂移，这正是core/persona-source.ts头部注释强调"本回落链必须是全仓唯一实现"的原因。

结语

一份 13 行的lib/agents-templates/en/hanako.md，背后是一整套"模板目录组织 → locale 判断 → 四级回落 → 系统提示词三段组装 → 测试守护"的工程链路。它既是一份可直接复制进自己AGENTS.md的人格底稿，也是理解 OpenHanako 人格体系（identity / yuan / AGENTS 三层结构、对内对外双人格）的最佳入口。当你看到某个 agent 说话"很有温度、又很有主见"时，那份感觉正是从这份模板开始，经过resolvePersonaSource与personalitygetter 一步步注入提示词的。