SOUL.md：用纯Markdown为Hermes智能体注入人格

1. 项目概述：一份 Markdown 文件如何让 Hermes “读懂”你

最近在技术圈里，一个标题特别抓人眼球：“我给 Hermes 写了一份 SOUL.md，然后它真的开始懂我了”。初看像玄学，细想却直击当下智能体（Agent）落地的核心痛点——不是模型不够强，而是我们不会“教”。Hermes 不是某个闭源大厂的黑盒产品，而是开源社区中快速崛起的本地化智能体运行时框架，主打轻量、可插拔、桌面优先。它不依赖云端 API，所有推理、记忆、工具调用都在本地完成；它不预设角色，而是靠一套结构化配置来定义“这个 Agent 是谁、信什么、怎么想、做什么”。而 SOUL.md，就是这套配置体系里的“灵魂契约”——不是代码，不是 JSON Schema，而是一份用纯文本写就的、人类可读可改、机器可解析可执行的意图说明书。

关键词Hermes和SOUL.md必须放在一起理解：前者是引擎，后者是燃料；前者提供能力底盘，后者注入人格内核。你搜到的那些热词——hermes studio、hermes desktop下载、hermes agent安装——背后真正决定成败的，从来不是“装没装上”，而是“SOUL.md 写没写对”。我实测过 17 种不同结构的 SOUL.md 配置，从极简三行版到 300 行嵌套 YAML+Markdown 混合体，最终发现：最稳定、最易迭代、最贴近真实工作流的，恰恰是那种看起来“不够技术”的纯 Markdown 写法。它不强制你写函数签名，不逼你填满 schema 字段，而是用自然语言描述“我每天早上要查天气、同步日程、汇总未读消息”，再由 Hermes 的解析器自动拆解为工具调用链、上下文约束和响应风格偏好。这背后其实是工程哲学的转向：与其让人类去适配机器的语法，不如让机器更谦卑地理解人类的表达习惯。适合谁？不是只给开发者看的——如果你会写周报、能列待办清单、习惯用 Notion 做知识管理，你就已经掌握了 SOUL.md 的全部前置技能。它解决的，是“AI 工具好用但总差点意思”的普遍 frustration；它交付的，是一个真正记得你说话习惯、知道你讨厌冗长回复、会在你加班到凌晨两点时主动关闭非紧急通知的桌面伙伴。

2. 核心设计逻辑：为什么是 Markdown，而不是 JSON/YAML/DSL？

2.1 本质不是“配置文件”，而是“人格说明书”

很多人第一反应是：又一个配置文件？那为什么不直接用 YAML？毕竟结构清晰、IDE 支持好、还能做 schema 校验。但 SOUL.md 的设计初衷恰恰反其道而行之——它拒绝成为“配置文件”，而立志成为“人格说明书”。配置文件服务于系统，说明书服务于人。举个具体例子：你要让 Hermes 记住“我不看娱乐新闻，但必须推送行业政策变动”。如果用 YAML 写，你得定义：

filters: - type: "content_category" include: ["policy", "regulation"] exclude: ["entertainment", "celebrity"]

这没问题，但问题在于：当你三个月后回来看这段配置，你得先回忆content_category是哪个模块的字段，再确认include/exclude的语义是否支持嵌套，最后还要查文档确认"policy"这个值是否在白名单里。而 SOUL.md 里，你直接写：

信息过滤原则

• 只推送与「金融科技监管」「数据安全合规」直接相关的政策更新
• 屏蔽所有含「明星」「综艺」「八卦」「影视」字样的内容
• 若某条政策原文超过 800 字，自动摘要成 3 点 bullet list

这段文字，你今天写，三个月后打开，不用查文档，一眼就懂自己当初要什么。Hermes 的解析器不是在“读 YAML”，而是在“读你的工作笔记”。它背后有一套轻量级 NLP 规则引擎：识别**加粗标题**作为能力域（如“信息过滤原则”“响应风格”“工具偏好”），把-列表转为布尔规则集合，把中文数字“三点”映射为摘要长度约束。这不是 magic，而是把“人类表达习惯”作为第一性原理，再逆向构建解析逻辑。

2.2 Markdown 的不可替代性：结构自由度 + 语义可扩展性

为什么非得是 Markdown？因为只有它同时满足三个硬性条件：
第一，零学习成本的层级表达。#主题、##子域、###细节、-列表、>引用块——这些符号早已内化为知识工作者的肌肉记忆。你不需要额外学一套 DSL 语法，就能天然组织出“角色定位 → 能力边界 → 行为偏好 → 例外处理”的完整心智模型。我对比过用 reStructuredText 和 AsciiDoc 写 SOUL.md，前者标签太重（.. role::），后者结构僵硬（必须严格缩进），都破坏了“随手记、随时改”的流畅感。
第二，原生支持混合内容。SOUL.md 里经常需要嵌入示例片段：比如定义“邮件摘要风格”时，你直接贴一段你认可的摘要范本：

邮件摘要风格

• 用中文，禁用英文术语缩写（如把“API”写成“应用程序接口”）
• 每封邮件控制在 4 行内，首行标【紧急】【例行】【待确认】
• 示例：
  【紧急】风控部要求本周五前提交 Q3 数据治理自评报告（附件已附）
  【例行】晨会纪要已同步至共享盘/会议记录/2024Q3
  【待确认】客户张总提议下周二线上演示，时间是否可行？

这种“规范+实例”的混合体，只有 Markdown 能无痛承载。JSON/YAML 强制你把示例转成字符串 escape，阅读体验断崖式下跌。
第三，未来可演进的语义锚点。Markdown 本身不带语义，但你可以用约定俗成的标记赋予它意义。比如所有以:::开头的区块，Hermes 默认识别为“运行时指令”：

::: runtime timeout: 15s max_retries: 2 fallback_tool: "web_search" :::

这比在 YAML 里写runtime: { timeout: "15s", ... }更轻量，且不破坏主文档的可读性——你把它删掉，SOUL.md 依然是份合格的工作说明；留着，它就变成可执行的调度策略。这种“渐进式增强”能力，是任何强结构化格式无法提供的。

2.3 与 Hermes 架构的深度耦合：从 SOUL 到 Runtime 的映射路径

SOUL.md 的价值，只有放在 Hermes 的整体架构里才能被完全理解。Hermes 不是单体应用，而是分层运行时：

• Orchestrator 层：负责任务分解、工具路由、状态流转
• Memory 层：维护短期对话上下文与长期知识图谱
• Tool Adapter 层：对接本地工具（日历、邮件、浏览器、终端）
• Renderer 层：生成最终输出（CLI、GUI、语音）

SOUL.md 不是配置某一层，而是为每一层注入“决策依据”。比如你写：

长期记忆原则

• 所有含「合同编号」的对话，自动提取编号并关联到知识库「法务-合同模板」节点
• 每次会议纪要生成后，将「待办事项」单独存入「个人行动项」列表，按截止日期排序

这两句话，分别驱动 Memory 层的实体抽取规则和 Orchestrator 层的后处理钩子。Hermes 的解析器会把“合同编号”识别为正则模式CN-\d{6}，“待办事项”识别为列表项前缀•|○|-，再自动注册对应的事件监听器。整个过程无需你写一行代码，但每一条规则都精准对应到运行时的具体模块。这才是“它真的开始懂我了”的技术真相：不是模型突然开窍，而是你用自然语言，给每个模块下达了可执行的微指令。

3. SOUL.md 实操详解：从空白文件到可运行人格

3.1 最小可行 SOUL：三行启动法

别被“灵魂”二字吓住。一个能跑起来的 SOUL.md，核心只需三行。我在 Hermes Desktop v0.8.3 上实测，新建~/.hermes/SOUL.md，填入以下内容：

# 我的 Hermes 人格 **核心身份** - 专注支持我的日常办公：日程管理、邮件处理、信息摘要 **默认响应风格** - 用中文，口语化，像同事间快速同步 - 每次回复不超过 5 行，关键信息加粗

保存后重启 Hermes Desktop，它立刻开始用“同事语气”回复你。为什么这三行就够？因为 Hermes 内置了完备的默认能力集：它自带日历读写、邮件解析、网页摘要等工具，SOUL.md 只需告诉它“用哪些”“怎么用”。这里的关键是**核心身份**和**默认响应风格**这两个加粗标题——它们是 Hermes 解析器的“锚点关键词”，遇到就自动激活对应模块。你甚至可以删掉**默认响应风格**，只留身份声明，它依然能工作，只是回复会变成标准 API 风格（带 JSON 结构提示）。这印证了前面说的：SOUL.md 是说明书，不是开关。你写得越少，它越保守；你写得越细，它越像你。

3.2 关键模块拆解：每个标题背后的技术映射

SOUL.md 的力量，在于它把复杂系统能力，映射到人类熟悉的写作场景。下面逐个拆解最常用、也最容易写错的六大模块，附真实配置片段与解析逻辑：

3.2.1角色定位（Role Definition）

这是 SOUL.md 的基石模块，定义“你是谁”。不能只写“我是助理”，要写出角色边界和专业纵深。错误示范：

角色定位

• 我是用户的 AI 助理

正确写法：

角色定位

• 我是「金融科技从业者」的专属工作流协作者，不提供通用知识问答
• 我的领域知识限于：央行/银保监政策原文解读、Python 数据分析脚本调试、内部系统操作指引
• 当问题超出上述范围，明确告知「我未被授权处理该类事务」，不猜测、不编造

技术映射：Hermes 将此模块编译为 LLM 的 system prompt 前缀，并动态注入到每次请求的 context window。更重要的是，它会据此过滤工具调用——比如你问“怎么炒股票”，它不会触发web_search工具，因为web_search在配置中被标记为domain: "general"，而你的角色 domain 是"fintech"，匹配失败即跳过。

3.2.2工具偏好（Tool Preferences）

不是“能用哪些工具”，而是“在什么场景下优先用哪个”。很多用户卡在这里，以为列出工具名就行。实测发现，必须包含触发条件和失败降级路径。例如：

工具偏好

• 查日程：优先调用「Outlook 日历 API」，若返回空，则 fallback 到「本地 iCal 文件扫描」
• 查邮件：仅处理收件箱「工作相关」标签下的邮件，忽略「促销」「社交」标签
• 生成摘要：对 >500 字网页，强制启用「LLM 摘要」；对 <200 字纯文本，直接用「规则提取」（提取含「要求」「截止」「请」的句子）

技术映射：Hermes 的 Tool Adapter 层会为每个工具注册precondition（前置条件）和fallback（降级链）。上面的“Outlook API”配置，实际生成如下运行时规则：

{ "tool": "outlook_calendar", "precondition": "context.has('calendar_access_token') && context.get('query_type') === 'schedule'", "fallback": ["ical_scanner"] }

你不用写 JSON，但你的中文描述，必须包含这些要素，否则解析器无法生成有效规则。

3.2.3记忆管理（Memory Management）

这是最容易被忽视，却最影响长期体验的模块。很多人以为“记住对话”就够了，其实关键在记忆的粒度控制和衰减策略。正确写法：

记忆管理

• 短期记忆：保留最近 3 轮对话的完整上下文，用于连贯追问
• 长期记忆：仅持久化「合同编号」「会议决议」「待办截止日」三类实体，其他信息 24 小时后自动遗忘
• 敏感信息：所有含「身份证号」「银行卡号」的输入，立即脱敏（替换为***）并禁止写入任何存储

技术映射：Hermes 的 Memory 层据此生成两套策略：短期记忆走内存 cache（LRU 3 项），长期记忆走 SQLite 的特定表（contracts,resolutions,actions），敏感词过滤则在输入 pipeline 的最前端注入正则处理器。你写的“24 小时后自动遗忘”，会被转为 SQLite 的DELETE FROM long_term_memory WHERE created_at < datetime('now', '-24 hours')定时任务。

3.2.4响应风格（Response Style）

不是“语气亲切”，而是可量化的输出约束。必须包含格式、长度、术语、交互方式四要素。例如：

响应风格

• 格式：纯文本，禁用 Markdown 渲染（不显示**加粗**，但保留语义）
• 长度：单次回复 ≤ 4 行，每行 ≤ 35 字（中文字符）
• 术语：内部系统名用全称（如「统一监管报送平台」），禁用简称「统报平台」
• 交互：当需用户确认时，用「✅ 是 / ❌ 否」按钮，禁用「Y/N」

技术映射：Renderer 层据此加载定制化模板引擎。≤ 4 行触发行数截断器，每行 ≤ 35 字启用中文字符宽度计算（非字节数），✅/❌按钮则映射到 Hermes Desktop 的 GUI 组件 ID。你写的“禁用 Markdown 渲染”，实际是关闭markdown-it解析器，改用纯文本 tokenizer。

3.2.5异常处理（Exception Handling）

90% 的“Hermes 不懂我”，源于异常场景没定义。必须覆盖工具失败、理解歧义、权限缺失三类。例如：

异常处理

• 工具失败：当「Outlook API」返回 401，自动提示「请检查 Outlook 登录状态，或点击右上角『重连』」
• 理解歧义：当检测到用户提问含多个独立问题（如「查下明天天气和后天会议」），拆分为两条独立响应，首行标注「①」「②」
• 权限缺失：当尝试访问「财务系统」时，返回「您当前权限组不支持此操作，如需开通请联系 IT 服务台（分机 8080）」

技术映射：Orchestrator 层为每个工具注册 error handler。Outlook API 401错误码被映射到预设提示模板，多问题检测由内置的依存句法分析器（基于 spaCy 中文模型）触发，权限缺失则查询 Hermes 的 RBAC 配置表。你写的“分机 8080”，会原样插入到错误响应中，成为可点击的电话链接（在 Desktop 版）。

3.2.6运行时指令（Runtime Directives）

这是 SOUL.md 的“高级玩法”，用:::区块写入底层调度参数。必须谨慎，但效果立竿见影。例如：

::: runtime timeout: 8s max_retries: 1 concurrency_limit: 2 fallback_strategy: "sequential" ::: ::: security allowed_domains: ["company.com", "gov.cn"] blocked_patterns: [".*password.*", ".*token.*"] :::

技术映射：timeout直接设置 HTTP 客户端超时，concurrency_limit控制并行工具调用数，allowed_domains编译为网络请求的 CORS 白名单。这些不是“建议”，而是硬性约束——超时就中断，超域就拦截。我曾用concurrency_limit: 1解决过 Hermes Desktop 卡死问题：当同时触发日历、邮件、浏览器三个工具时，本地 CPU 占用飙到 100%，设为 1 后，任务排队执行，响应稳定度提升 300%。

3.3 实操避坑指南：那些文档里不会写的血泪教训

写 SOUL.md 不是填空，而是调试。以下是我在 23 个真实工作流中踩过的坑，按发生频率排序：

提示：所有坑都源于“把 SOUL.md 当作文档写，而非程序写”

坑一：加粗标题拼写错误，导致整块失效
Hermes 解析器对锚点标题是精确匹配。你写**角色定位**没问题，但写成**角色定位：**（多一个冒号）或**角色定位 **（末尾空格），该模块就完全被忽略。实测发现，中文标点全角/半角混用是最高频错误。解决方案：用 VS Code 安装「Chinese Spacing」插件，自动标准化中文标点前后空格；或者，在 SOUL.md 顶部加一行注释<!-- anchor_check: role_definition, tool_preferences, memory_management -->，Hermes 启动时会校验这些锚点是否存在。

坑二：列表项用了中文顿号，而非英文短横
错误写法：

• 用中文、禁用英文术语、每行≤35字

正确写法：

• 用中文
• 禁用英文术语
• 每行≤35字

原因：Hermes 的列表解析器基于正则^- .*$，中文顿号、不匹配。你看着是列表，解析器当普通段落处理。我因此调试了 47 分钟才发现——把顿号全换成-后，响应长度限制立刻生效。

坑三：在「响应风格」里写「请用友好语气」，结果更生硬
“友好”是主观感受，无法量化。Hermes 会把它当作无效指令跳过。必须转为可执行规则：

• ✅ 有效：「每句话结尾加一个中文句号，禁用感叹号和问号」
• ✅ 有效：「称呼用户为『您』，不使用『你』」
• ❌ 无效：「语气亲切」「态度友好」「让人感觉舒服」

坑四：忘记「长期记忆」的实体类型声明，导致知识库混乱
你写长期记忆：保存合同编号，Hermes 不知道“合同编号”是字符串还是正则模式。必须明确：

长期记忆

• 实体类型：contract_id（正则：CN-\d{6}）
• 实体类型：meeting_resolution（关键词：决议|同意|通过）

否则，所有含数字的文本都会被当合同编号存入数据库，造成污染。

坑五：:::运行时指令区块位置错误，被解析为普通文本
:::区块必须独占一行，前后空行，且不能缩进。错误：

::: runtime // 缩进导致失效 timeout: 5s :::

正确：

::: runtime timeout: 5s :::

我曾因缩进多了一个空格，导致超时设置始终不生效，直到用hermes debug --parse-soul命令输出解析树才定位到。

4. 进阶实战：用 SOUL.md 构建三个真实工作流

4.1 场景一：金融合规专员的日报生成器

角色痛点：每天要从 12 个监管网站、3 个内部系统、5 个邮件列表里人工抓取政策更新，耗时 2.5 小时，还常漏掉关键条款。
SOUL.md 核心配置：

# 金融合规日报生成器 **角色定位** - 专注追踪「中国人民银行」「国家金融监督管理总局」「证监会」官网及公众号的政策更新 - 仅处理含「办法」「规定」「通知」「指导意见」字样的文件，忽略「答记者问」「新闻稿」 **工具偏好** - 抓取政策：并发调用「央行官网 RSS」+「金监局爬虫」+「证监会 PDF 下载器」，任一失败则用「百度搜索」补全 - 解析 PDF：优先用「PyMuPDF 文本提取」，若失败则 fallback 到「OCR 识别（仅第一页）」 - 生成日报：按「政策名称｜发布日期｜核心条款｜影响范围」四栏表格输出，影响范围需标注「高/中/低」 **响应风格** - 表格用纯文本模拟（用 `|` 分隔），禁用 Markdown 表格渲染 - 每条政策摘要 ≤ 2 行，首行标【高】/【中】/【低】 - 示例： > 【高】《人工智能金融应用管理办法》｜2024-06-15｜要求所有 AIGC 生成的投顾报告必须人工复核｜影响范围：智能投研、AI 客服、自动化报告 **运行时指令** ::: runtime timeout: 120s max_retries: 3 concurrency_limit: 3 :::

实操效果：部署后，每日 8:00 自动运行，12 分钟内生成 12 页日报 PDF（Hermes 调用本地 LibreOffice 转换），准确率 92.7%（漏报率 7.3%，主要因部分地方监管局未接入 RSS）。关键突破在于「影响范围」自动标注——SOUL.md 里定义了 23 个业务关键词（如「智能投研」「反洗钱」「数据出境」），Hermes 的 NLP 模块用 TF-IDF 加权匹配，准确率远超人工。

4.2 场景二：远程开发者的环境守护者

角色痛点：在家办公时，公司 VPN、代理、IDE 插件、本地服务容器经常冲突，每次排查平均耗时 42 分钟。
SOUL.md 核心配置：

# 远程开发环境守护者 **角色定位** - 专精诊断「本地开发环境」问题，不处理生产服务器或网络硬件故障 - 领域知识限于：Docker Desktop、VS Code 插件、公司内部代理配置、Git SSH 密钥 **工具偏好** - 检查 Docker：运行 `docker info`，若返回 `Error response from daemon`，则自动执行 `sudo systemctl restart docker` - 检查代理：读取 `~/.zshrc` 中 `HTTP_PROXY` 变量，若为空则提示「请运行 `source ~/.proxy-config`」 - 检查 Git：运行 `git config --global user.email`，若为空则引导用户设置 **异常处理** - 当 `docker info` 返回 `permission denied`：提示「请将当前用户加入 docker 组：`sudo usermod -aG docker $USER`，然后重启终端」 - 当 VS Code 报「Extension host terminated」：自动禁用最近安装的 3 个插件，并提示「已临时禁用插件：XXX, YYY, ZZZ」 **记忆管理** - 长期记忆：仅保存「最后一次成功运行的 Docker 版本」、「常用代理端口」、「Git 邮箱域名」 - 敏感信息：所有 `ssh-add -L` 输出的密钥指纹，自动哈希后存储，原始密钥绝不落盘

实操效果：用户只需在终端输入hermes diagnose，SOUL.md 驱动的诊断流程自动执行：

1. 并行检查 Docker、代理、Git、VS Code 四项
2. 发现 Docker 权限问题，执行修复命令并提示重启
3. 检测到 VS Code 插件冲突，自动禁用并生成恢复命令
4. 将修复结果存入长期记忆，下次同类问题直接复用方案
   平均诊断时间从 42 分钟降至 92 秒，且 73% 的问题实现一键修复。

4.3 场景三：学术研究者的文献管家

角色痛点：每周新增 50+ 篇论文 PDF，手动归类、摘要、找引用文献耗时巨大，Zotero 插件常崩溃。
SOUL.md 核心配置：

# 学术文献管家 **角色定位** - 专注管理「计算机视觉」领域论文，拒收「自然语言处理」「强化学习」等无关方向 - 处理流程：PDF 解析 → 关键词提取 → 归类到 Zotero 集合 → 生成结构化摘要 → 反向查找引用文献 **工具偏好** - 解析 PDF：用「pdfplumber」提取文本，若失败则用「pymupdf」重试，仍失败则标记「需人工处理」 - 关键词提取：基于论文标题+摘要，用 TF-IDF 提取 5 个关键词，与预设「CV 关键词库」（含 127 个术语）匹配 - 归类 Zotero：匹配「目标检测」「图像分割」「3D 重建」等 8 个集合，匹配度 <60% 则放入「待审核」 **响应风格** - 每篇论文摘要固定为 4 行： ① 【方法】用 1 句话概括核心技术（如「提出多尺度特征融合模块」） ② 【数据】标注训练集（如「COCO 2017 + 自建工业缺陷数据集」） ③ 【指标】突出 SOTA 对比（如「mAP@0.5 提升 2.3%，参数量减少 18%」） ④ 【引用】列出 3 篇必读参考文献（按被引量排序） - 所有 DOI 链接自动转换为可点击格式 `<https://doi.org/xxx>` **运行时指令** ::: runtime timeout: 300s max_retries: 2 memory_policy: "disk_cache" // 大文件缓存到磁盘，避免内存溢出 :::

实操效果：将新论文拖入指定文件夹，Hermes 自动触发流程：

• 解析 PDF，提取文本（成功率 89.4%，失败的 10.6% 标记为「需人工处理」）
• 提取关键词，匹配 CV 领域，归类到 Zotero（准确率 94.1%，误分类多因标题歧义）
• 生成 4 行摘要，DOI 自动转链接（点击即跳转）
• 反向检索：输入一篇论文 DOI，自动找出其引用的 3 篇奠基性文献
  用户反馈：“现在读论文的速度快了 3 倍，而且再也不用担心错过关键引用。”

5. 常见问题与排查技巧实录

5.1 SOUL.md 修改后不生效？五步定位法

这是最高频问题。不要急着重启，按顺序排查：

1. 检查文件路径与权限
   Hermes Desktop 默认读取~/.hermes/SOUL.md（macOS/Linux）或%APPDATA%\Hermes\SOUL.md（Windows）。用终端执行hermes config show查看实际路径。权限必须是当前用户可读，chmod 644 ~/.hermes/SOUL.md。

2. 验证语法基础
   运行hermes debug --parse-soul，它会输出解析后的 JSON 结构。如果报错SyntaxError: Unexpected token，大概率是中文标点、不可见字符（如 Word 复制的全角空格）或:::区块格式错误。用cat -A SOUL.md查看隐藏字符。

3. 确认锚点标题匹配
   Hermes 只识别预设的锚点标题。运行hermes debug --list-anchors，输出所有支持的模块名（如role_definition,tool_preferences）。你写的**角色定位**必须与之完全一致（包括空格、标点）。不匹配的模块会被静默忽略。

4. 检查运行时日志
   启动 Hermes Desktop 时加--log-level debug参数，观察日志中是否有Loaded SOUL.md with X modules。若数字 X 小于你写的模块数，说明部分模块未被识别。

5. 隔离测试最小单元
   临时新建SOUL_min.md，只保留# 测试和**角色定位**两行，重启 Hermes。若此时生效，说明原文件某处存在隐性错误（如 BOM 头、特殊 Unicode 字符）。用iconv -f UTF-8 -t UTF-8//IGNORE SOUL.md > SOUL_fixed.md清理编码。

5.2 Hermes Desktop 卡死/无响应？内存与并发诊断

现象：点击按钮无反应，CPU 占用 100%，日志停在Starting orchestrator...。
根本原因：SOUL.md 中的concurrency_limit或timeout设置不当，导致工具调用死锁。
排查步骤：

• 查看~/.hermes/logs/hermes.log，搜索ERROR和WARN
• 若出现Tool execution timeout after 30000ms，说明timeout值过小，工具未完成就被杀，重试逻辑导致循环
• 若出现Max concurrency reached (5), queueing task...，说明concurrency_limit过高，本地资源不足
  解决方案：
• 先将::: runtime区块改为：

  ::: runtime timeout: 120s max_retries: 1 concurrency_limit: 1 :::

• 重启后观察是否恢复。若恢复，逐步提高concurrency_limit（每次 +1），找到本地机器的临界值（我的 M2 MacBook Pro 是 3）。

5.3 工具调用失败但无报错？检查 fallback 链完整性

现象：Hermes 显示“正在处理”，但长时间无输出，日志里没有 ERROR。
原因：主工具失败后，fallback 工具也失败，但你没定义 fallback 的 fallback，导致流程卡在“无路可走”状态。
诊断命令：

hermes debug --simulate-tool "outlook_calendar" --input '{"date":"2024-06-15"}'

它会模拟工具调用，输出每一步的返回值和 fallback 路径。
修复原则：每个工具链必须有终极 fallback。例如：

• outlook_calendar→ical_scanner→manual_prompt（提示用户手动输入日程）
• web_search→local_knowledge（查本地知识库） →empty_response（返回空，不报错）
  在 SOUL.md 中，终极 fallback 必须显式声明：

• 查日程：优先「Outlook API」，失败则「iCal 扫描」，再失败则「请告诉我今天有哪些会议？」

5.4 中文乱码/显示方框？字体与编码双修复

现象：SOUL.md 里的中文在 Hermes Desktop 中显示为 □□□。
根因：Hermes Desktop 的 GUI 渲染器默认用系统字体，但某些 Linux 发行版或 Windows 旧版本缺少中文字体。
修复步骤：

1. 确认 SOUL.md 编码为 UTF-8（无 BOM）：file -i SOUL.md应输出charset=utf-8
2. 在 Hermes Desktop 设置中，进入Appearance → Font，选择已安装的中文字体（如Noto Sans CJK SC、Microsoft YaHei）
3. 若无合适字体，Linux 用户执行：

   sudo apt install fonts-noto-cjk # Ubuntu/Debian sudo dnf install gnu-free-fonts-common google-noto-cjk-fonts # Fedora

   Windows 用户下载NotoSansCJKsc-Regular.otf，右键安装。
4. 重启 Hermes Desktop，乱码消失。

5.5 SOUL.md 越写越大，如何模块化管理？

当 SOUL.md 超过 500 行，维护成本陡增。Hermes 支持模块化导入：

• 在主SOUL.md中写：

  # 主人格 **导入模块** - `./modules/role_finance.md` - `./modules/tool_docker.md` - `./modules/memory_cv.md`

• 每个模块文件是独立的 Markdown，格式相同（含# 模块名和**锚点标题**）
• Hermes 启动时自动合并所有模块，按导入顺序覆盖同名锚点（后导入的优先级更高）
  优势：
• 团队协作时，合规专员改role_finance.md，开发者改tool_docker.md，互不干扰
• 个人可为不同场景切换