SelfRef 工程实践
本页介绍用于生产环境 Agent 架构的高级 SelfRef 模式。压缩策略
何时进行压缩
在以下情况下应执行压缩:- Token 使用量接近上下文窗口限制
- 完成了一个逻辑里程碑(任务完成、阶段转换)
- 工作对话中包含大量过时信息(旧的工具输出、已废弃的计划)
一次好的 Compact 调用应该怎么写
discoveries= 已发现的、后续可能需要的事实completed= 已完成的工作(防止 Agent 重复执行)current_status= 停止时的状态likely_next_work= 下一步要做什么(为恢复后的 Agent 提供方向)remember= 简短的持久化经验教训,会作为 experience 保留(谨慎使用)
压缩生命周期
- 在
execute_code内调用compact(...) - 压缩被加入队列(不会立即生效)
- 当前工具批次完成后,运行时会将压缩补丁应用到对话记录
- 系统提示词和 experiences 被保留
- 工作对话被替换为摘要消息
- Agent 的下一轮对话从精简的上下文开始
自动压缩模式
当接近 token 限制时注入压缩指令:Fork 编排
基本 Fork 模式
Fork 设计规则
- 子任务继承 fork 前的上下文 —— 它们能看到父任务在 fork 工具调用之前的对话内容,但看不到 fork 调用本身。
- 子任务是独立的 —— 它们无法读取或修改父任务的上下文。每个子任务都有自己隔离的 ReAct 循环。
-
Gather 会阻塞 ——
gather_all()会等待所有已创建的子任务完成。除非确实需要立即获取结果,否则不要在 spawn 后立即调用它。 - 保持任务范围明确 —— 为每个子任务提供清晰的范围、验收标准和停止条件。范围不明确的任务会浪费 token。
-
要求返回摘要 —— 告诉子任务返回简洁的结果和文件路径,而不是完整的对话记录。仅在需要检查子任务推理过程时使用
include_history=True。
Fork 与顺序执行的选择
适合使用 Fork 的场景:- 任务之间相互独立(没有数据依赖)
- 任务规模足以证明子上下文的开销是值得的
- 并行化可以节省实际时间
- 任务之间依赖彼此的输出
- 任务很小(每个只需一次工具调用)
- 需要中间结果来决定下一步
多键记忆
SelfReference 支持多个记忆键,用于分区管理状态:- 在一个应用中分离不同的 Agent 角色
- 长期项目记忆与临时任务上下文的分离
- 共享参考上下文与每用户对话的分离
Experience 管理
何时使用 Remember
适合作为 experience 的内容:- 持久性的经验教训(“这个 API 需要认证头 X”)
- 用户偏好(“偏好简洁的输出”)
- 项目约定(“始终使用 pytest,不使用 unittest”)
- 临时状态(“当前正在处理文件 X”)—— 应放在 compact 摘要中
- 大量数据 —— experiences 存在于系统提示词中,应保持简短
- 临时上下文 —— 使用工作消息或 compact 检查点代替
清理 Experiences
生产模式:持久化 Agent
- 跨会话记忆(experiences 持久化在 SelfReference backend 中)
- 在里程碑处压缩上下文(保持上下文精简)
- 将工作委托给 fork(复杂任务的并行处理)
- 完整的文件和代码访问权限(通过工具集)