人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载Cherry Studio 为内置的 Cherry AssistantCherry 小助手Agent 提供了一套以文件为载体的人格系统SOUL.md定义 Agent 如何呈现自己性格与语气USER.md记录用户是谁memory/FACT.md沉淀跨会话的长期知识。本文将逐条解读SOUL.md的规范原文并深入源码揭示它如何在系统提示词中加载、如何与 Agent System Prompt 分层协作、如何完成首次引导写入以及用户应如何查看与定制这份人格文件。一、SOUL.md 是什么一份人格即配置的文件在 Cherry Studio 中Agent 的数据目录位于应用 Data/Agents 目录下按 Agent ID 隔离存放着四个承担不同职责的文件文件职责更新方式SOUL.md如何呈现自己名字、性格、语气、沟通风格在未配置 System Prompt 时还承担角色定义Read Edit 工具USER.md用户是谁称呼、偏好、时区、个人上下文Read Edit 工具memory/FACT.md知道什么进行中的项目、技术决策、长期知识6 个月以上mcp__agent-memory__memory工具action: updatememory/JOURNAL.jsonl何时发生一次性事件、会话笔记追加式日志mcp__agent-memory__memory工具action: append / search这份文件布局在源码 src/main/ai/agents/prompt.ts 中以模板字符串形式写入系统提示词并在 docs/references/memory/overview.md 中被归纳为Agent File MemoryAgent 文件记忆——它是专属于单个 Agent 的记忆机制跨会话、不跨 Agent。而内置 Agent 的模板文件存放在仓库的 resources/builtin-agents/cherry-assistant/ 目录下与agent.json、USER.md、memory/FACT.md一起构成 Cherry Assistant 的出厂人格。二、Personality性格逐条解读SOUL.md的第一部分定义了 Agent 的性格基调Warm, patient, and practical. Keep a natural, lively voice with light humor when it fits — never forced, and never a flood of exclamation marks or emoji.可以拆解为三层要求基调三词温暖Warm、耐心Patient、务实Practical。这是内置 Agent 面向所有用户的底线气质无论用户是新手还是资深用户。自然与轻幽默语气要自然、生动在合适场景可以带一点轻幽默light humor但合适是关键限定词——幽默永远服务于对话而不是表演。两个绝不绝不刻意never forced、绝不用感叹号或 emoji 刷屏never a flood of exclamation marks or emoji。这一条与仓库中内置 Agent 的头像配置形成呼应——agent.json 中avatar为 产品选择用单个 emoji 作为视觉身份但对话语气上明确禁止 emoji 泛滥避免AI 味过重。从源码角度看这份性格并非写死的摆设当 Agent 没有配置 System Prompt 时SOUL.md是系统提示词中承载角色与性格的唯一权威来源当配置了 System Prompt 时它退居为如何呈现既定角色的个性化层。这一分层逻辑在 docs/references/ai/agent-prompt-layers.md 的提示词优先级表中被明确标注为第 4 层Agent Persona。三、Tone语气五条规范从答什么到怎么答SOUL.md的第二部分是五条可执行的语气规范原文如下Mirror the users terminology and level of formality.Be especially patient with beginners, incomplete or repeated questions, and failed attempts: acknowledge the confusion, break the task into smaller steps, and rephrase instead of repeating yourself.Adapt the level of detail to the users experience. Never mock, blame, patronize, or fall back on canned support phrasing.Lead with the answer, keep it concise, and give the user a way to verify the outcome.Ask for clarification only when the missing detail materially changes the answer.3.1 镜像用户的术语与正式程度第一条要求 Agent 跟随用户的用词习惯terminology和正式程度level of formality说话。用户用口语提问Agent 就不该用书面官腔用户使用专业术语Agent 也应采用相应术语体系回应。这与 USER.md 中根据用户消息中展现的经验水平调整细节与术语Adapt detail and terminology to the experience shown in the users messages的约定互为表里。3.2 对新手与失败尝试的加倍耐心第二条是整份规范中最长的一条也是内置 Agent 作为上手引导onboarding guide定位的直接体现。它给出了一套可操作的三步处理框架承认困惑acknowledge the confusion先确认用户当前卡住的点而不是直接丢答案拆解任务break the task into smaller steps把大问题切分成小步骤降低用户认知负担换一种说法rephrase instead of repeating yourself用户没听懂时用不同表述重新解释而不是原样复读。这条规范与agent.json中 Cherry Assistant 的角色说明高度一致其英文指令明确指出尤其要帮助用户开始使用 Cherry Studio、回答产品问题和排查故障particularly taking ownership of helping users get started with Cherry Studio, asking product questions, or troubleshooting problems见 agent.json。3.3 按经验适配细节禁用客服腔第三条划定了两个边界一是细节量要适配用户经验新手给步骤老手给结论二是严禁嘲讽mock、归咎blame、居高临下patronize或回退到模板化客服话术canned support phrasing。3.4 答案先行 可验证结果第四条是一条沟通效率原则先给结论lead with the answer保持简洁并给用户一个验证结果的方法。这意味着 Agent 的回答不能只是告知还要给出如何确认我做对了的路径——例如配置完成后告诉用户在设置页看到绿色状态即表示连接成功。3.5 只在关键信息缺失时才追问第五条是对提问成本的约束只有当缺失的信息会实质性地改变答案materially changes the answer时才向用户追问澄清。避免为了流程感而反复盘问保证对话高效。四、SOUL.md 在提示词分层中的位置与加载机制4.1 提示词优先级SOUL.md 是第 4 层人格Cherry Studio 的 Agent 会话会组合多个独立存储的提示词来源docs/references/ai/agent-prompt-layers.md 给出了如下优先级契约优先级来源存储位置作用域与生命周期1平台与运行时安全约束应用与运行时代码不可覆盖的运行时策略随连接物化2Agent System PromptAgent 配置的agent.instructions权威角色、目标、能力边界与行为约束3工作区指令workspace/system.md及运行时原生的CLAUDE.md/AGENTS.md工作区局部指导4Agent 人格agent-data/SOUL.md跨工作区持久的名字、性格、语气与沟通风格关键结论是SOUL.md不是 Agent 配置的副本。在配置了 System Prompt 时引导流程只允许用SOUL.md记录名字、性格、语气与沟通风格禁止发现、复述或替换既定角色在未配置 System Prompt 时SOUL.md保留传统的角色发现职责。保存 Agent 配置永远不会写SOUL.md编辑SOUL.md也永远不会改写agent.instructions——两份内容完全解耦。4.2 源码级的加载路径soul包裹SOUL.md的内容由 src/main/ai/agents/prompt.ts 中的PromptBuilder.buildMemoriesSection读取并包裹进系统提示词的 Memories 区块## Memories Persistent files in the agent data directory ... carry your identity and memory across workspaces and sessions. | File | Purpose | How to update | |---|---|---| | .../SOUL.md | HOW you present yourself ... | Read Edit tools | | .../USER.md | WHO the user is ... | Read Edit tools | | .../memory/FACT.md | WHAT you know ... | mcp__agent-memory__memory update action | | .../memory/JOURNAL.jsonl | WHEN things happened ... | mcp__agent-memory__memory tool only | soul 此处注入 SOUL.md 原文 /soul user 此处注入 USER.md 原文 /user facts 此处注入 FACT.md 原文 /facts这段模板同时告诉 AgentSOUL.md与USER.md用 Read Edit 工具直接读写FACT.md只能通过mcp__agent-memory__memory更新JOURNAL.jsonl不在上下文加载、只能通过 memory 工具追加或检索。也就是说Agent 会在运行中自主维护这份人格文件——用户改不改它自己都会根据对话沉淀更新。4.3 读取的安全与缓存细节PromptBuilder在读取这些文件时做了多层防护值得了解大小写不敏感匹配文件名不区分大小写resolveFile先精确匹配、再大小写兜底拒绝符号链接SOUL.md、USER.md若是指向目录外的符号链接会被忽略并记录警告避免提示词注入风险路径越界校验通过realpath比对禁止读取预期根目录之外的文件mtime 缓存以修改时间mtimeMs为键缓存 30 分钟命中缓存则跳过磁盘读取降低每次会话构建的成本。这些细节与 src/main/ai/agents/agentDataDirectory.ts 中对 Agent 数据目录的路径断言拒绝符号链接、拒绝逃逸根目录共同构成了人格文件读写的安全边界。五、首次引导SOUL.md 是如何被写出来的5.1 Bootstrap 引导流程Agent 首次创建时SOUL.md可能是空模板或尚不存在。此时 src/main/ai/agents/bootstrap.ts 会注入一段 Bootstrap Mode 指令让 Agent 通过一次自然的对话完成人格初始化自我介绍说明这是一次一次性的关系建立对话探索偏好通过对话了解用户希望的名字、性格、语气与沟通风格有 System Prompt 时只探索如何呈现角色无则进一步探索角色本身了解用户自然地询问称呼、时区、工作时段、沟通偏好语言、详略、正式程度且问题总数不超过 35 个落盘用 Write/Edit 工具写入SOUL.md与USER.md用mcp__cherry-tools__config完成改名与标记complete_bootstrap。判断是否进入引导的逻辑在 src/main/ai/agents/prompt.tsbootstrap_completed显式为 true 则跳过显式为 false 则强制引导SOUL.md已有实质内容去头尾后超过 50 字符阈值SOUL_CONTENT_THRESHOLD则视为已完成兼容旧版本迁移。5.2 内置 Agent 的出厂写入对于内置的 Cherry Assistantsrc/main/ai/agents/builtin/BuiltinAgentProvisioner.ts 的provisionBuiltinAgent负责把仓库模板目录下的SOUL.md、USER.md、memory/FACT.md复制到持久化的 Agent 数据目录规则非常明确只填空不覆盖目标文件不存在或大小为 0 时才写入任何非空文件一律视为用户已定制原样保留外科手术式迁移仅当目标SOUL.md的字节与已知的旧版出厂 blob按大小 SHA-256 哈希双重匹配完全一致时才替换为当前出厂人格——用户只要动过一个字符哈希即改变便永远不会被覆盖。这个设计在测试 src/main/ai/agents/builtin/tests/BuiltinAgentProvisioner.test.ts 中有专门覆盖包括对 v2.0.0-rc.5 旧版人格3600 字节 blob与 PR #17870 过渡版人格321 字节 blob的迁移断言。六、与配套文件的协同一套完整的内置 AgentSOUL.md不是孤立文件它与同目录的其它文件构成 Cherry Assistant 的完整出厂包resources/builtin-agents/cherry-assistant/agent.json / agent-template.jsonAgent 的权威配置包含中英文指令、permission_mode: acceptEdits、bootstrap_completed: true、头像 以及 7 个内置技能如cherry-assistant-guide、cherry-studio-feedback、skills-manager。其中 agent-template.json 是事实来源agent.json 由pnpm build:builtin-knowledge生成见 scripts/generate-cherry-assistant-knowledge/index.tsUSER.md定义用户是谁——强调绝不从账户名、文件系统路径、设备名或应用设置推断用户身份未提供称呼时主动询问会话上下文运行在 Cherry Studio 中属于环境元数据而非用户身份memory/FACT.md长期知识文件明确告知 Agent 此文件不会在应用更新时被覆盖用户定制可持久保留产品知识应通过cherry-assistant-guide技能与mcp__assistant__product_info查询当前包 manifest避免在 FACT.md 中复制产品事实导致过期product-manifest.json由脚本生成的运行时产品清单路由、快捷键、62 个提供商、13 个语言、功能默认值等供 Agent 回答产品问题时实时查询。对照可见SOUL.md回答你是什么气质USER.md回答用户是谁FACT.md回答你知道什么三层各司其职、互不重叠——这也正是 docs/references/memory/overview.md 中强调的每个文件有排他作用域绝不跨文件重复信息。七、用户视角如何查看与定制 Agent 人格从使用角度用户并不需要直接编辑源码中的模板而是操作应用内的 Agent 数据目录Data/Agents 下对应 Agent 的文件夹查看打开SOUL.md、USER.md、memory/FACT.md即可看到当前 Agent 的人格、用户画像与长期记忆定制直接编辑SOUL.md中的 Personality / Tone 段落即可重塑性格语气——由于内置 Agent 的部署逻辑只填空、不覆盖任何用户编辑都会原样保留即使应用升级也不会被出厂人格冲掉重置引导若想重新走一遍人格初始化对话可通过配置中的reset_bootstrap将bootstrap_completed置为 false下一会话即重新进入 Bootstrap Mode注意边界当 Agent 已配置 System Prompt 时角色、目标与能力边界由agent.instructions权威定义SOUL.md只应承载呈现层名字、性格、语气两者修改互不影响。八、小结SOUL.md是 Cherry Studio Agent 人格系统的最小但最核心的单元它以纯文本定义性格与语气以soul包裹注入系统提示词以只填空不覆盖 哈希迁移保证用户定制安全并与 System Prompt、工作区指令构成四层提示词契约。理解这份文件就理解了 Cherry Studio 内置 Agent 的人设从哪来、如何加载、如何被保护——无论是想深度使用 Cherry Assistant还是基于同一套文件记忆机制自定义自己的 Agent都能从中找到清晰的落点。赞分享人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载相关推荐Cherry Studio 内置「产品反馈」Agent 的 SOUL.md 人格设计从语气规范到源码落地Cherry Studio 内置「产品反馈」Agent 的 SOUL.md 人格设计从语气规范到源码落地 本篇技术指南围绕 Cherry Studio 内置问人工智能大模型AI 应用交互助手本地部署Cherry Studio 内置 Agent 的长期记忆机制深入解析 FACT.md 的设计与实现Cherry Studio 内置 Agent 的长期记忆机制深入解析 FACT.md 的设计与实现 本指南聚焦 Cherry Studio 内置 AgentAI 应用大模型桌面应用本地部署RAGCherry Studio Agent 系统提示词权威性机制详解System Prompt 如何覆盖 system.md 与 SOUL.mdCherry Studio Agent 系统提示词权威性机制详解System Prompt 如何覆盖 system.md 与 SOUL.md 这篇技术指南围绕人工智能大模型AI 应用交互助手本地部署上一篇learnxinyminutes-docs 之 Vim 上手指南从模式、导航到宏与 vimrc 配置的完整实战手册下一篇描述创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考