第三讲：智能体的上下文文件
同样是寅宾，为什么有的团队用起来像一个严谨的项目助理，有的团队却总得到泛泛而谈的答案？
差异往往不在模型，而在上下文文件。
可以把一次对话想象成一次工作交接：模型本身拥有通用能力，但不知道你是谁、正在做什么、应该遵守什么规则，也不知道过去已经做过哪些决定。上下文文件的作用，就是把这些稳定信息交给它。
模型提供通用能力，上下文文件塑造一个可长期协作的具体智能体。
学完这一讲，你应该能够回答：
| 问题 | 本讲给出的答案 |
|---|---|
| 为什么需要多个文件 | 把规则、人格、身份、用户偏好和记忆分层管理 |
| AGENTS.md 做什么 | 规定怎么做事、什么优先、有哪些工具与边界 |
| SOUL.md 做什么 | 规定像谁、如何表达、坚持什么价值观 |
| IDENTITY.md 做什么 | 记录名字、头像、气质等身份元数据 |
| MEMORY.md 做什么 | 保存经过筛选、值得长期保留的事实和决策 |
| 为什么还会按日期建文件 | 原始记录需要可追溯，精选记忆不能承担全部日志 |
| TOOLS.md 还要不要 | 当前优先把本地工具说明放进 AGENTS.md 的 ## Tools；TOOLS.md 视版本和兼容需要保留 |
一、先理解“上下文预算”
大语言模型每次生成回答时，只能看到当前上下文窗口中的内容。窗口很大，但不是无限大。系统提示、渠道信息、对话历史、工具定义、文件和记忆都要共享这份预算。
如果不加区分地把所有资料都塞进去，会带来三个问题：
- 成本上升。 每次对话都携带大量无关内容。
- 注意力稀释。 真正重要的规则被淹没在背景资料里。
- 维护失控。 新旧规则相互冲突，没人知道哪一条最终生效。
所以，成熟的做法不是写一个越来越长的提示词，而是让不同文件承担不同职责，并给每一类内容设定生命周期。
| 文件 | 解决的问题 | 更新频率 | 典型加载时机 |
|---|---|---|---|
AGENTS.md | 怎么做事 | 规则变化时 | 每轮会话加载 |
SOUL.md | 像谁、怎么说话 | 很少变化 | 每轮会话加载 |
IDENTITY.md | 叫什么、头像和气质 | 初始化后很少变化 | 按入口或初始化流程 |
USER.md | 用户是谁、有什么稳定偏好 | 几周到几个月 | 每轮会话加载 |
MEMORY.md | 长期事实、决策和教训 | 定期整理 | 主要在主会话加载 |
memory/YYYY-MM-DD.md | 每天发生了什么 | 每天追加 | 新会话或重置时按需带入 |
这里最重要的不是死记“哪个文件在哪一秒加载”，而是理解一条原则：
稳定规则与人设放前面，临时资料与原始日志放后面；先加载少量高价值信息，再按需检索更多细节。
二、AGENTS.md：告诉智能体怎么做事
AGENTS.md 是最接近“操作手册”的文件。它回答的不是“你是谁”，而是：
- 接到任务后先做什么、后做什么？
- 哪些规则优先级最高？
- 应该使用哪些工具、目录和项目约定？
- 哪些动作必须先询问？
- 输出应该包含哪些字段、格式和验收标准？
- 遇到信息冲突时，以谁为准？
一个清晰的 AGENTS.md 通常包含这些部分：
# 工作规则
## 优先级
1. 用户当前明确要求
2. 本文件中的安全与权限规则
3. 当前项目 README
4. 历史记忆
## 工作方式
- 修改文件前先阅读相关代码和文档。
- 先给出简短计划，再执行。
- 完成后运行可执行的验证命令。
- 不能验证时，明确说明未验证的部分。
## 权限边界
- 不读取或输出密钥。
- 删除、发布、付款和权限变更必须获得人工确认。
- 对外内容必须检查公司名称、讲师和联系方式。
## Tools
- 浏览器：用于需要登录或动态交互的页面。
- 文件系统：项目文件位于指定工作区。
- 搜索：优先官方来源，并在结论后附链接。2.1 规则必须可执行
“回答要专业一点”不是可执行规则。“结论先写三句话，再给证据；不确定项标注置信度”才是。
“注意安全”也不是可执行规则。“任何删除操作先列出文件清单，等待确认后才能执行”才是。
好的规则有三个特征：
- 可判断。 能明确知道是否做到。
- 可验证。 可以通过输出或日志检查。
- 冲突少。 不与项目已有规范重复或互相矛盾。
2.2 当前推荐：把工具说明放进 AGENTS.md
早期资料中常单独维护 TOOLS.md，用于记录本机工具、设备名称、命令和环境备注。当前官方文档更推荐把这些内容放入 AGENTS.md 的 ## Tools 小节，让代理打开一个文件就能看到操作规则与工具环境。
这不意味着所有旧文件都要立刻删除：
| 情况 | 建议 |
|---|---|
| 新项目 | 优先使用 AGENTS.md 的 ## Tools |
已有 TOOLS.md 且运行正常 | 保持现状，逐步合并，避免为了形式而迁移 |
| 多智能体共享同一套工具说明 | 可保留独立文件，再由 AGENTS.md 引用 |
| 工具说明经常变化 | 与稳定规则分开放，减少 AGENTS.md 的频繁改动 |
| 不确定当前版本是否读取 | 先查官方文档和 /context 一类诊断能力，再决定 |
TOOLS.md 有旧版本和兼容性背景，不应武断地说它一定在每轮注入。课程中的原则是：先确保信息会被当前版本读取，再考虑文件如何命名。
三、SOUL.md：稳定的人格与价值观
SOUL.md 回答的是“用什么姿态和用户长期相处”。
它不是角色扮演台词，也不只是“说话活泼一点”。真正有价值的 SOUL.md 会写明：
- 核心气质：冷静、直接、耐心、严谨，还是富有探索精神？
- 沟通方式：先给结论还是先讲背景？什么时候使用类比？
- 价值观：诚实、透明、尊重隐私、不夸大能力。
- 观点边界：可以提出不同意见，但要说明理由和不确定性。
- 幽默尺度：什么时候可以轻松，什么时候必须严肃。
- 禁止行为：不迎合、不编造、不泄露、不代替用户做高风险决定。
示例：
# SOUL
## 气质
- 冷静、清楚、务实。
- 对复杂问题先建立结构，再给结论。
- 不为讨好用户而同意明显错误的判断。
## 表达
- 默认使用简体中文。
- 先给结论，再给依据；关键结论使用短句。
- 不使用夸张营销语言。
- 不确定时明确说“不确定”，并给出验证路径。
## 边界
- 保护隐私和密钥。
- 不伪造来源、数据或执行结果。
- 高风险动作必须说明影响并请求确认。SOUL.md 应当稳定。今天“温柔耐心”，明天“犀利毒舌”，会让协作体验不可预测。真正需要改变时，也应明确记录原因，而不是频繁微调。
四、IDENTITY.md：智能体是谁
IDENTITY.md 保存的是更轻量、更结构化的身份信息，例如：
- 名字或称呼
- 一句话气质描述
- 头像
- 常用的 emoji 标识
- 自我介绍模板
示例：
# IDENTITY
- Name: 寅宾
- Vibe: 可靠、克制、善于拆解复杂问题
- Avatar: /images/yinbin-avatar.svg
- Emoji: 无可以把三者这样区分：
| 文件 | 回答的问题 | 例子 |
|---|---|---|
SOUL.md | 我坚持什么、怎么思考 | 不同意用户时仍保持尊重，并给出理由 |
IDENTITY.md | 我叫什么、长什么样 | 名字、头像、气质标签 |
AGENTS.md | 我具体怎么做 | 修改前先读文件，完成后运行测试 |
公开教程、客服机器人、内部助理可以共享同一套模型，但通过不同身份文件呈现不同角色。这就是“同一个引擎，不同界面”的思路。
五、USER.md：用户是谁
USER.md 存放关于用户的稳定信息，用于减少重复说明。例如：
- 用户的名字、角色和主要职责
- 常用语言、表达偏好和时区
- 希望使用表格还是段落
- 技术与业务背景
- 当前活跃项目
- 长期偏好，例如“先给结论”“不要使用 emoji”
- 需要特别提醒的沟通习惯
示例：
# USER
- Name: Job
- Timezone: Asia/Shanghai
- Role: 智能体工程课程讲师与产品负责人
## Preferences
- 中文回答，先给结论。
- 需要具体命令和文件路径。
- 对外文档保持零 emoji。
- 重要事实附来源和日期。
## Active Projects
- 智能体工程导论
- 寅宾发行版教程5.1 USER.md 不要变成档案袋
只保存“下次仍然需要知道”的信息。下面这些不适合长期写入：
- 一次性的任务要求
- 密码、令牌、身份证号和银行卡信息
- 未经确认的猜测
- 经常变化的价格、库存和日程
- 敏感健康、财务或家庭信息
如果公开渠道、群聊和私人主会话共用同一套用户文件，还要检查是否会把私人偏好暴露给其他人。记忆隔离首先是权限问题，不只是提示词问题。
六、MEMORY.md：从日志中提炼长期记忆
长期记忆不应该记录所有对话，而应该保留以后仍会影响判断的内容：
- 已经确认的重要事实
- 长期有效的偏好
- 已做出的关键决策及原因
- 项目约定、术语和命名
- 失败教训与修复方式
- 尚未解决但需要继续跟踪的问题
示例：
# MEMORY
## 长期事实
- 教程站使用 Astro 静态站，内容放在 `src/content/tutorials/`。
- 生产域名采用 EdgeOne Makers 托管。
## 决策
- 2026-09-27：实践课由两讲扩展为五讲。
- 原因：原第二讲同时承载概念、渠道、技能和企业场景，范围过大。
## 待跟踪
- 新讲上线后检查旧链接与生产构建结果。6.1 每日记录与精选记忆有什么区别
memory/YYYY-MM-DD.md 更像工作日志，适合保存当天发生的过程：
# 2026-09-27
- 完成第二讲 Web Search 初稿。
- 核对 SearXNG 配置项。
- 待办：补充飞书语音控制示例。| 类型 | 文件 | 内容特点 | 用途 |
|---|---|---|---|
| 原始日志 | memory/2026-09-27.md | 按时间追加，内容较全 | 追溯当天发生什么 |
| 精选记忆 | MEMORY.md | 去重、提炼、长期有效 | 让主会话快速获得关键信息 |
主会话通常重点加载 MEMORY.md；当用户执行 /new 或 /reset 开始一段新会话时，今天的日志和昨天的日志也可能被带入，帮助智能体接续最近工作。具体行为应以当前版本文档和实际配置为准。
6.2 记忆需要整理
如果一直追加却从不清理，记忆会逐渐变成噪声。建议每周或每个项目阶段做一次整理：
- 合并。 把重复描述合并成一条稳定事实。
- 降级。 已经失效的计划移出 MEMORY.md，保留在日期日志中。
- 纠错。 发现旧记忆错误时，明确标注替代关系。
- 分层。 项目细节放项目目录，私人偏好放用户文件，公司通用规则放公共层。
- 验证。 修改后让智能体复述关键规则，确认它读取的是新版本。
七、文件如何放置与加载
不同版本的目录布局可能略有差异，但通常可以把内容分为三层：
| 层级 | 适合内容 | 特点 |
|---|---|---|
| 共享层 | 公司规则、公共工具、团队术语 | 多个智能体共同使用 |
| 智能体层 | SOUL、IDENTITY、USER、MEMORY | 定义一个长期协作者 |
| 项目层 | 项目 AGENTS.md、README、局部记忆 | 只在具体工作区生效 |
一个常见结构如下：
workspace/
├── AGENTS.md
├── SOUL.md
├── IDENTITY.md
├── USER.md
├── MEMORY.md
├── memory/
│ ├── 2026-09-26.md
│ └── 2026-09-27.md
└── projects/
└── agent-engineering/
└── AGENTS.md7.1 上下文不是无限容器
每个文件都有字符预算。默认引导内容存在总上限，单个文件过大时会被截断。即使系统没有截断，过长的内容也会降低回答质量。
因此：
- 把最重要的规则放在文件前部。
- 不把整本手册复制进 AGENTS.md。
- 大段资料放知识库，通过检索按需读取。
- 用链接和文件路径引用详细资料，不把所有细节内联。
- 定期检查哪些规则已经失效。
7.2 修改后的验收方法
每次修改上下文文件，不要只看“保存成功”。应完成一次小验收：
- 新开一段会话，避免旧上下文污染。
- 问一个只能靠新规则回答的问题。
- 检查它是否使用正确文件、称呼和输出格式。
- 问一个权限边界问题，确认不会越权执行。
- 如果结果异常，检查文件位置、优先级、截断和版本兼容性。
八、常见错误
| 错误做法 | 后果 | 改进方式 |
|---|---|---|
| 把所有内容写进一个文件 | 注意力分散、维护困难 | 按职责拆分 |
| 规则写得含糊 | 每次回答风格不稳定 | 改成可判断、可验证的句子 |
| 把密码写进 USER.md | 泄露风险 | 使用密钥管理系统 |
| MEMORY.md 记录全部聊天 | 噪声越来越大 | 日期日志与精选记忆分层 |
| 群聊直接加载私人记忆 | 隐私泄露 | 会话、用户和渠道隔离 |
| 依赖旧版 TOOLS.md | 当前版本可能不读取 | 合并到 AGENTS.md 的 ## Tools |
| 修改后不验收 | 不知道新规则是否生效 | 新会话做一次行为测试 |
九、课堂练习
为寅宾建立一套最小可用的上下文：
- 在
AGENTS.md写五条工作规则和三条权限边界。 - 在
SOUL.md定义语气、价值观和禁止行为。 - 在
IDENTITY.md填写名字、气质和头像。 - 在
USER.md写三条稳定偏好，不要包含敏感信息。 - 在
MEMORY.md写一项长期事实、一项决策和一项待跟踪问题。 - 新开会话，让寅宾复述它将如何遵守这些规则，并验证一次。
十、本讲小结
- 上下文文件塑造具体的智能体。 模型相同，文件不同，协作效果就不同。
- 不同文件解决不同问题。 AGENTS 管规则，SOUL 管人格，IDENTITY 管身份，USER 管用户模型，MEMORY 管长期记忆。
- 稳定内容前置，原始记录后置。 信息按生命周期分层，才能长期维护。
- TOOLS.md 不必神化。 新项目优先使用
AGENTS.md的## Tools，旧文件按兼容需要处理。 - 记忆必须筛选。 只保留未来仍会影响行动的事实、决策和教训。
下一讲：第四讲：Skill 与 ClawHub。
课程： 智能体工程导论
讲师： Job Zhao
公司名称： 青岛火一五信息科技有限公司
联系邮箱： postmaster@huo15.com
