2026/9/19 1:57:05
FEATURED · 精选文章 
1. 从 400 溢出报错开始复盘TaoToken 接入与请求地址对齐凌晨两点Agent 跑到第 47 轮Claude Code 侧抛回400 invalid_request_error: prompt is too longCodex 侧则报context_length_exceeded。这不是模型不行而是长任务上下文工程里最典型的溢出信号。复盘时先别急着扩上下文窗口先去 TaoToken 官网拿 Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_replay_intro把请求地址统一到https://taotoken.net/api再按记忆分层把复盘检索和回灌调用拆开计量。本文以 Agent 运维工程师视角给出一套可复现的溢出复盘流程先对齐供应商入口再落记忆分层配置最后用复盘 Token 对照表定位到底是哪一层在吃预算。很多团队遇到溢出第一反应是换更大窗口的模型或者把历史消息粗暴截断。但长任务真正的问题往往不是窗口不够而是记忆没有分层工作记忆、情景记忆、语义记忆、程序记忆混在一个 messages 数组里复盘检索和回灌调用又共用一个 Token 池。结果就是该记住的目标被截掉不该回灌的日志被反复塞入。要解决它先把请求地址和 Key 管好。如果你还没有 TaoToken 的 Key可以在官网控制台创建或者直接走 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_keys。拿到 Key 后所有 AI CLI 的 Base URL 都指到https://taotoken.net/api注意Base URL 不加 UTM 参数UTM 只用于官网入口统计。Key 统一用占位符YOUR_API_KEY替代不要提交到仓库。先做一次最小连通性检查。以 Claude Code 使用的 Anthropic 兼容接口为例可以在本地终端执行curl -sS https://taotoken.net/api/v1/messages \ -H x-api-key: YOUR_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 32, messages: [ {role: user, content: ping} ] }如果返回正常说明 TaoToken 侧链路通了。接下来才是复盘为什么第 47 轮会溢出为什么目标在第 32 轮之后开始漂移为什么跨会话记忆召回时又产生了一次 Token 尖峰。把这三个问题拆开才能决定补哪层记忆。2. 溢出复盘Agent 运维工程师要看的 6 个指标不要只记录“溢出发生了”。复盘要留下可对照的数据否则下一次长任务还会在同一个位置断掉。建议至少采集以下 6 个指标Token 增量曲线每轮输入 Token、输出 Token、缓存命中 Token。重点看输入 Token 在哪一轮开始非线性上升。记忆载入来源本轮上下文里有多少来自工作记忆、多少来自情景摘要、多少来自向量召回、多少来自跨会话记忆。压缩次数与压缩比从第几轮开始触发压缩压缩前后 Token 比是多少压缩后是否丢失决策、错误、未完成 todo。todo-state 复述频率目标、约束、已完成项、待办项是否每轮或每 N 轮重新注入。跨会话召回命中率检索到的记忆片段有多少真正被后续步骤引用多少只是“看起来相关”。目标漂移点从哪一轮开始Agent 的回答偏离原始目标或者开始重复已完成步骤。这 6 个指标里第 2 和第 5 直接对应复盘检索与记忆回灌调用也是 Token 消耗方。很多溢出不是模型不会压缩而是回灌策略没有预算上限向量库 top_k 设成 20每条记忆 800 Token一次回灌就吃掉 16000 Token再叠加工作记忆和 todo-state窗口瞬间见底。复盘时可以把一次溢出快照保存为本地 JSON{ task_id: agent-ops-2026-02-14-001, overflow_turn: 47, model: claude-sonnet-4-5, input_tokens: 198420, output_tokens: 3120, memory_sources: { working: 62000, episodic_summary: 28000, semantic_recall: 76000, procedural_todo: 1800 }, compression_rounds: 5, todo_repeat_interval: 3, goal_drift_turn: 32 }这个快照不直接解决问题但它让“记忆该补哪层”从感觉变成对照。3. 记忆分四层工作记忆、情景记忆、语义记忆、程序记忆原文把长任务 harness 的机制拆成上下文预算与卸载、压缩、todo-state 复述、跨会话记忆。落到 Agent 运维可以把它们映射成四层记忆。分层的目的不是学术分类而是让每层有独立的 Token 预算、生命周期和回灌优先级。工作记忆当前轮次直接需要的消息、工具返回、临时变量。它最容易膨胀也最该有 TTL。对应“上下文预算与卸载”超过预算就卸载到情景层而不是继续堆在 messages 里。情景记忆一次任务中的事件流摘要做过什么、失败过什么、关键决策是什么。对应“压缩”把长对话压成结构化摘要保留决策、错误、未完成项去掉寒暄和重复工具输出。语义记忆跨任务可复用的知识、项目规范、领域事实。对应“跨会话记忆”从向量库或文件库召回但必须限制 top_k 和单条长度否则复盘检索会变成新的溢出源。程序记忆Agent 的行为规则、工具使用约束、todo-state 复述模板。对应“todo-state 复述”目标、约束、当前进度、下一步用固定格式每轮或每 N 轮注入。它 Token 少但对防止目标丢失最关键。如果只补一层优先补程序记忆和情景记忆如果溢出根因在检索回灌再补语义记忆的预算和过滤工作记忆则应该持续卸载而不是扩容。4. 可复现的记忆分层配置memory_layers.yaml下面这份配置可以直接作为复盘基线。它不绑定某个框架任何 Agent 运行时都能读取。核心是给每层设置max_tokens、ttl_turns、recall和store让复盘检索与记忆回灌调用有独立账本。# memory_layers.yaml version: 1 task_defaults: total_context_budget: 120000 reserve_output_tokens: 8000 overflow_policy: unload_then_summarize memory_layers: working: description: 当前轮直接可见的消息与工具返回 max_tokens: 24000 ttl_turns: 8 store: memory recall: always unload_to: episodic unload_trigger: 0.85 episodic: description: 任务事件流摘要保留决策、错误、未完成项 max_tokens: 32000 ttl_turns: 80 store: sqlite recall: summary summary_fields: - decision - error - unfinished_todo - artifact_path semantic: description: 跨会话可复用知识向量或全文召回 max_tokens: 20000 ttl_turns: 0 store: vector recall: top_k top_k: 6 max_item_tokens: 1200 score_threshold: 0.72 procedural: description: 目标、约束、todo-state 复述模板 max_tokens: 2000 ttl_turns: 0 store: file recall: always repeat_interval: 2 template: | [GOAL] {goal} [CONSTRAINTS] {constraints} [DONE] {done_items} [TODO] {todo_items} [NEXT] {next_action}这份配置的关键参数解释working.max_tokens: 24000工作记忆不是越大越好。超过 85% 就卸载到情景层。episodic.max_tokens: 32000情景摘要允许较大因为它承载决策和错误但必须有字段白名单。semantic.top_k: 6复盘检索最容易失控的地方。top_k 从 20 降到 6单条限制 1200 Token一次回灌最多 7200 Token。procedural.repeat_interval: 2todo-state 每 2 轮复述一次成本约 1k-2k Token但显著降低目标漂移。配置落盘后在 Agent 启动时加载import yaml def load_memory_config(pathmemory_layers.yaml): with open(path, r, encodingutf-8) as f: cfg yaml.safe_load(f) layers cfg[memory_layers] total cfg[task_defaults][total_context_budget] reserve cfg[task_defaults][reserve_output_tokens] used sum(layer[max_tokens] for layer in layers.values()) if used reserve total: raise ValueError(fmemory layers exceed budget: {used reserve} {total}) return cfg if __name__ __main__: print(load_memory_config())这段代码的作用是把“记忆分层”从口头约定变成启动检查。如果各层预算之和加输出预留超过总上下文直接失败避免上线后才溢出。如果你在 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_memory_config查看模型能力时也要同步确认所选模型的上下文窗口再把total_context_budget写成窗口的 80% 左右留出压缩和回灌余量。5. 复盘 Token 对照表检索与回灌分别花了多少溢出复盘最容易忽略的是复盘本身也在烧 Token。你为了查清第 47 轮为什么溢出把历史对话、工具日志、向量召回结果重新喂给模型这一次调用可能比原任务还贵。所以要把“复盘检索”和“记忆回灌”作为两个独立账本。下面是一张可填写的复盘 Token 对照表阶段调用方典型 Token 量建议预算观测点优化动作溢出快照复盘检索8k-20k单独计量输入长度、轮次范围只取最近 N 轮 错误摘要情景摘要压缩3k-8k摘要预算压缩比、字段完整率保留决策/错误/未完成 todo语义召回向量检索2k-12ktop_k × 单条上限命中率、引用率top_k≤6单条≤1200 Token程序回灌todo-state0.5k-2k固定注入目标漂移轮次每 2 轮复述目标与约束跨会话记忆记忆回灌4k-16k分层预算溢出率、重复率冷热分层热记忆常驻复盘问答模型对话5k-15k复盘总预算是否引入新事实先本地聚合再让模型解释填表时不要估算直接记录实际调用。可以给每次复盘打一个 ledgerfrom dataclasses import dataclass dataclass class ReplayTokenLedger: retrieval: int 0 rehydration: int 0 compression: int 0 todo_state: int 0 def add(self, phase: str, tokens: int) - None: if not hasattr(self, phase): raise ValueError(funknown phase: {phase}) setattr(self, phase, getattr(self, phase) tokens) def total(self) - int: return self.retrieval self.rehydration self.compression self.todo_state def report(self) - dict: total self.total() return { retrieval: self.retrieval, rehydration: self.rehydration, compression: self.compression, todo_state: self.todo_state, total: total, rehydration_ratio: round(self.rehydration / total, 3) if total else 0.0, } ledger ReplayTokenLedger() ledger.add(retrieval, 12400) ledger.add(rehydration, 8600) ledger.add(compression, 5200) ledger.add(todo_state, 1600) print(ledger.report())如果rehydration_ratio超过 0.35说明回灌过重优先压缩语义记忆如果todo_state很低但目标仍漂移说明复述模板没覆盖关键约束如果retrieval很高说明复盘检索本身需要先本地聚合再交给模型。6. Claude Code 接入 TaoTokensettings.json ANTHROPIC_* 三件套Claude Code 侧建议使用~/.claude/settings.json管理供应商配置。不要把 Key 写进项目仓库也不要用 Codex 的配置格式混搭。下面是一个可复制示例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5 }, permissions: { allow: [ Read, Write, Bash(git status), Bash(git diff), Bash(npm test) ], deny: [ Bash(rm -rf *), Bash(curl * | sh) ] } }这里的ANTHROPIC_*三件套是ANTHROPIC_BASE_URL请求地址固定为https://taotoken.net/api。ANTHROPIC_AUTH_TOKEN占位符YOUR_API_KEY替换成你的 TaoToken Key。ANTHROPIC_MODEL/ANTHROPIC_SMALL_FAST_MODEL主模型与快速模型。如果不想写进 settings.json也可以在 shell 里临时导出export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELclaude-sonnet-4-5 export ANTHROPIC_SMALL_FAST_MODELclaude-haiku-4-5 claude检查是否生效claude --version claude -p 只输出当前 Base URL 配置是否存在不要执行工具然后观察 Agent 启动日志里请求是否指向 TaoToken。如果仍然报旧供应商的错误先检查是否有更高优先级的环境变量覆盖了 settings.json。在 Claude Code 里做记忆分层时可以把memory_layers.yaml放在项目根目录并通过权限允许 Agent 读取但禁止它直接修改预算上限。运维工程师负责预算Agent 负责在预算内工作。7. Codex 接入 TaoTokenconfig.toml 不要混用 ANTHROPIC_*Codex 不要套用ANTHROPIC_*。它使用~/.codex/config.toml供应商通过model_providers声明。下面是一个 TaoToken 接入示例# ~/.codex/config.toml model gpt-5-codex model_provider taotoken approval_policy on-request sandbox_mode workspace-write [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api responses对应的环境变量export TAOTOKEN_API_KEYYOUR_API_KEY codex如果你同时使用 Claude Code 和 Codex建议把 Key 放在同一个密钥管理入口但配置格式分开Claude Code~/.claude/settings.json里的ANTHROPIC_*。Codex~/.codex/config.toml里的model_providers。通用 KeyTAOTOKEN_API_KEY或ANTHROPIC_AUTH_TOKEN按客户端要求注入。Codex 的排障重点是wire_api和base_url。如果报 404先确认客户端拼接路径是否与 TaoToken 兼容如果报 401检查env_key指向的环境变量是否真的导出。不要把 Claude Code 的ANTHROPIC_AUTH_TOKEN直接当作 Codex 的env_key两者语义不同。8. CC Switch 三件套让多 CLI 共用 TaoToken Base URL如果你在 Claude Code、Codex 和另一个 CLI 之间切换手动改配置很容易把供应商混掉。可以用 CC Switch 的思路管理三件套Claude Code 配置、Codex 配置、通用环境变量文件。这里给一个不依赖具体插件名的落地方式。第一件Claude Code settings.json路径~/.claude/settings.json内容见上一节。第二件Codex config.toml路径~/.codex/config.toml内容见上一节。第三件通用环境变量文件~/.config/taotoken/env.sh# ~/.config/taotoken/env.sh export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYYOUR_API_KEY # Claude Code export ANTHROPIC_BASE_URL$TAOTOKEN_BASE_URL export ANTHROPIC_AUTH_TOKEN$TAOTOKEN_API_KEY # Codex 仅使用 TAOTOKEN_API_KEY不要导出 ANTHROPIC_* 给 Codex 使用每次切换前 source 一次source ~/.config/taotoken/env.sh再写一个本地检查脚本避免配置漂移#!/usr/bin/env bash set -euo pipefail echo ANTHROPIC_BASE_URL${ANTHROPIC_BASE_URL:-未设置} echo ANTHROPIC_AUTH_TOKEN${ANTHROPIC_AUTH_TOKEN:已设置} echo TAOTOKEN_API_KEY${TAOTOKEN_API_KEY:已设置} if [[ ${ANTHROPIC_BASE_URL:-} ! https://taotoken.net/api ]]; then echo Claude Code Base URL 不一致请检查 ~/.claude/settings.json 或 env.sh fi if [[ ${TAOTOKEN_API_KEY:-} ]]; then echo Codex 缺少 TAOTOKEN_API_KEY fi三件套的管理原则是Base URL 只有一个真相源即https://taotoken.net/apiKey 只有一个占位符即YOUR_API_KEYClaude Code 和 Codex 的配置格式分开。你可以在 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_cc_switch确认控制台入口再配合本地脚本做切换。9. 回灌策略按优先级注入而不是全量塞回记忆分层配置写好之后真正的溢出防线在回灌策略。复盘时不要把所有检索结果一次性塞回主上下文。建议按优先级注入程序记忆目标、约束、todo-state固定注入成本最低优先级最高。工作记忆最近 N 轮消息和工具返回只保留当前步骤相关部分。情景记忆按任务阶段召回摘要优先决策、错误、未完成项。语义记忆按向量相似度和引用率过滤top_k 不超过 6单条不超过 1200 Token。可以用一个回灌计划器做预算裁剪def build_rehydration_plan(goal, constraints, todo_items, layers, budget): plan [] remaining budget procedural { layer: procedural, content: { goal: goal, constraints: constraints, todo: todo_items, }, priority: 0, } plan.append(procedural) for layer_name in (working, episodic, semantic): for item in layers.get(layer_name, []): if remaining 0: break cost item.get(tokens, 0) if cost remaining: continue plan.append({ layer: layer_name, content: item[content], priority: item.get(priority, 10), }) remaining - cost plan.sort(keylambda x: x[priority]) return plan, remaining if __name__ __main__: layers { working: [{content: 最近工具输出, tokens: 3000, priority: 1}], episodic: [{content: 第 32 轮目标漂移摘要, tokens: 1800, priority: 2}], semantic: [{content: 项目规范片段, tokens: 900, priority: 3}], } plan, left build_rehydration_plan( goal完成 Agent 长任务复盘, constraints[禁止直接操作生产库, SQL 仅本地执行], todo_items[补程序记忆, 补情景摘要], layerslayers, budget8000, ) print(剩余预算:, left) for step in plan: print(step[layer], step[priority])关键点回灌不是把向量库结果全量拼进 prompt而是先做预算裁剪再按优先级排序。复盘检索的高 Token 调用应该发生在本地或一次性批处理中主任务上下文里只保留结论和引用。10. 排障清单从 400/429 到目标丢失把下面这份清单放进 Agent 运维手册溢出复盘时逐项打勾400 prompt too long检查memory_layers.yaml各层max_tokens之和是否超过总预算检查working.unload_trigger是否触发。400 invalid_request_error确认 Base URL 是https://taotoken.net/apiKey 使用YOUR_API_KEY替换检查模型名是否在 TaoToken 模型列表中。401/403Claude Code 看ANTHROPIC_AUTH_TOKENCodex 看TAOTOKEN_API_KEY不要在 Codex 里找ANTHROPIC_*。404检查客户端拼接路径确认没有把 Base URL 写成带 UTM 的官网地址。429复盘检索和记忆回灌是否并发过高把语义召回改为批量限制 top_k。目标丢失检查procedural.repeat_interval把目标、约束、TODO 每 2 轮复述一次。跨会话召回不命中检查向量 metadata 是否带task_id、artifact_path、decision字段。压缩后信息丢失检查摘要字段白名单至少保留决策、错误、未完成 todo、产物路径。配置不生效检查环境变量优先级settings.json、config.toml、shell export 是否互相覆盖。复盘 Token 再次尖峰查ReplayTokenLedger.report()看rehydration_ratio是否超过 0.35。这份清单不解决所有问题但它能把“溢出”从偶发事故变成可观测、可回滚的运维事件。11. 复盘后的固化把记忆分层写进 Agent 运维手册一次溢出复盘的价值不在于写出一份事故报告而在于把结论固化成默认配置。建议复盘结束后完成三件事把memory_layers.yaml合并进项目模板作为 Agent 启动检查的一部分。把ReplayTokenLedger接入日志每次长任务结束后输出检索、回灌、压缩、todo-state 的 Token 占比。把排障清单加入值班手册下次出现prompt is too long时按顺序检查而不是直接换模型。如果你还没有稳定的 Key 和请求入口可以先在 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_manual完成注册与 Key 创建再把所有 AI CLI 的 Base URL 统一到https://taotoken.net/api。这样复盘数据才有可比性记忆分层的 Token 对照才有意义。12. CTA模型对话、Coding Plan、创建 Key、Claude Code 文档下一步可以根据你的使用方式选择入口想先验证模型对话和记忆回灌效果走模型对话https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_chat想把 Claude Code / Codex 长期接入长任务工作流看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_plan需要创建和管理自己的 Key进入 API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_keysClaude Code 侧配置细节参考 Claude Code 文档https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_cc_doc把 Key 占位符YOUR_API_KEY替换掉把请求地址设为https://taotoken.net/api然后回到你的memory_layers.yaml和复盘 Token 对照表。溢出复盘时该补哪层记忆答案不在模型窗口里而在你的分层预算和回灌优先级里。
溢出复盘时，TaoToken 下 Agent 该补哪层记忆
1. 从 400 溢出报错开始复盘TaoToken 接入与请求地址对齐凌晨两点Agent 跑到第 47 轮Claude Code 侧抛回400 invalid_request_error: prompt is too longCodex 侧则报context_length_exceeded。这不是模型不行而是长任务上下文工程里最典型的溢出信号。复盘时先别急着扩上下文窗口先去 TaoToken 官网拿 Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_replay_intro把请求地址统一到https://taotoken.net/api再按记忆分层把复盘检索和回灌调用拆开计量。本文以 Agent 运维工程师视角给出一套可复现的溢出复盘流程先对齐供应商入口再落记忆分层配置最后用复盘 Token 对照表定位到底是哪一层在吃预算。很多团队遇到溢出第一反应是换更大窗口的模型或者把历史消息粗暴截断。但长任务真正的问题往往不是窗口不够而是记忆没有分层工作记忆、情景记忆、语义记忆、程序记忆混在一个 messages 数组里复盘检索和回灌调用又共用一个 Token 池。结果就是该记住的目标被截掉不该回灌的日志被反复塞入。要解决它先把请求地址和 Key 管好。如果你还没有 TaoToken 的 Key可以在官网控制台创建或者直接走 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_keys。拿到 Key 后所有 AI CLI 的 Base URL 都指到https://taotoken.net/api注意Base URL 不加 UTM 参数UTM 只用于官网入口统计。Key 统一用占位符YOUR_API_KEY替代不要提交到仓库。先做一次最小连通性检查。以 Claude Code 使用的 Anthropic 兼容接口为例可以在本地终端执行curl -sS https://taotoken.net/api/v1/messages \ -H x-api-key: YOUR_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 32, messages: [ {role: user, content: ping} ] }如果返回正常说明 TaoToken 侧链路通了。接下来才是复盘为什么第 47 轮会溢出为什么目标在第 32 轮之后开始漂移为什么跨会话记忆召回时又产生了一次 Token 尖峰。把这三个问题拆开才能决定补哪层记忆。2. 溢出复盘Agent 运维工程师要看的 6 个指标不要只记录“溢出发生了”。复盘要留下可对照的数据否则下一次长任务还会在同一个位置断掉。建议至少采集以下 6 个指标Token 增量曲线每轮输入 Token、输出 Token、缓存命中 Token。重点看输入 Token 在哪一轮开始非线性上升。记忆载入来源本轮上下文里有多少来自工作记忆、多少来自情景摘要、多少来自向量召回、多少来自跨会话记忆。压缩次数与压缩比从第几轮开始触发压缩压缩前后 Token 比是多少压缩后是否丢失决策、错误、未完成 todo。todo-state 复述频率目标、约束、已完成项、待办项是否每轮或每 N 轮重新注入。跨会话召回命中率检索到的记忆片段有多少真正被后续步骤引用多少只是“看起来相关”。目标漂移点从哪一轮开始Agent 的回答偏离原始目标或者开始重复已完成步骤。这 6 个指标里第 2 和第 5 直接对应复盘检索与记忆回灌调用也是 Token 消耗方。很多溢出不是模型不会压缩而是回灌策略没有预算上限向量库 top_k 设成 20每条记忆 800 Token一次回灌就吃掉 16000 Token再叠加工作记忆和 todo-state窗口瞬间见底。复盘时可以把一次溢出快照保存为本地 JSON{ task_id: agent-ops-2026-02-14-001, overflow_turn: 47, model: claude-sonnet-4-5, input_tokens: 198420, output_tokens: 3120, memory_sources: { working: 62000, episodic_summary: 28000, semantic_recall: 76000, procedural_todo: 1800 }, compression_rounds: 5, todo_repeat_interval: 3, goal_drift_turn: 32 }这个快照不直接解决问题但它让“记忆该补哪层”从感觉变成对照。3. 记忆分四层工作记忆、情景记忆、语义记忆、程序记忆原文把长任务 harness 的机制拆成上下文预算与卸载、压缩、todo-state 复述、跨会话记忆。落到 Agent 运维可以把它们映射成四层记忆。分层的目的不是学术分类而是让每层有独立的 Token 预算、生命周期和回灌优先级。工作记忆当前轮次直接需要的消息、工具返回、临时变量。它最容易膨胀也最该有 TTL。对应“上下文预算与卸载”超过预算就卸载到情景层而不是继续堆在 messages 里。情景记忆一次任务中的事件流摘要做过什么、失败过什么、关键决策是什么。对应“压缩”把长对话压成结构化摘要保留决策、错误、未完成项去掉寒暄和重复工具输出。语义记忆跨任务可复用的知识、项目规范、领域事实。对应“跨会话记忆”从向量库或文件库召回但必须限制 top_k 和单条长度否则复盘检索会变成新的溢出源。程序记忆Agent 的行为规则、工具使用约束、todo-state 复述模板。对应“todo-state 复述”目标、约束、当前进度、下一步用固定格式每轮或每 N 轮注入。它 Token 少但对防止目标丢失最关键。如果只补一层优先补程序记忆和情景记忆如果溢出根因在检索回灌再补语义记忆的预算和过滤工作记忆则应该持续卸载而不是扩容。4. 可复现的记忆分层配置memory_layers.yaml下面这份配置可以直接作为复盘基线。它不绑定某个框架任何 Agent 运行时都能读取。核心是给每层设置max_tokens、ttl_turns、recall和store让复盘检索与记忆回灌调用有独立账本。# memory_layers.yaml version: 1 task_defaults: total_context_budget: 120000 reserve_output_tokens: 8000 overflow_policy: unload_then_summarize memory_layers: working: description: 当前轮直接可见的消息与工具返回 max_tokens: 24000 ttl_turns: 8 store: memory recall: always unload_to: episodic unload_trigger: 0.85 episodic: description: 任务事件流摘要保留决策、错误、未完成项 max_tokens: 32000 ttl_turns: 80 store: sqlite recall: summary summary_fields: - decision - error - unfinished_todo - artifact_path semantic: description: 跨会话可复用知识向量或全文召回 max_tokens: 20000 ttl_turns: 0 store: vector recall: top_k top_k: 6 max_item_tokens: 1200 score_threshold: 0.72 procedural: description: 目标、约束、todo-state 复述模板 max_tokens: 2000 ttl_turns: 0 store: file recall: always repeat_interval: 2 template: | [GOAL] {goal} [CONSTRAINTS] {constraints} [DONE] {done_items} [TODO] {todo_items} [NEXT] {next_action}这份配置的关键参数解释working.max_tokens: 24000工作记忆不是越大越好。超过 85% 就卸载到情景层。episodic.max_tokens: 32000情景摘要允许较大因为它承载决策和错误但必须有字段白名单。semantic.top_k: 6复盘检索最容易失控的地方。top_k 从 20 降到 6单条限制 1200 Token一次回灌最多 7200 Token。procedural.repeat_interval: 2todo-state 每 2 轮复述一次成本约 1k-2k Token但显著降低目标漂移。配置落盘后在 Agent 启动时加载import yaml def load_memory_config(pathmemory_layers.yaml): with open(path, r, encodingutf-8) as f: cfg yaml.safe_load(f) layers cfg[memory_layers] total cfg[task_defaults][total_context_budget] reserve cfg[task_defaults][reserve_output_tokens] used sum(layer[max_tokens] for layer in layers.values()) if used reserve total: raise ValueError(fmemory layers exceed budget: {used reserve} {total}) return cfg if __name__ __main__: print(load_memory_config())这段代码的作用是把“记忆分层”从口头约定变成启动检查。如果各层预算之和加输出预留超过总上下文直接失败避免上线后才溢出。如果你在 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_memory_config查看模型能力时也要同步确认所选模型的上下文窗口再把total_context_budget写成窗口的 80% 左右留出压缩和回灌余量。5. 复盘 Token 对照表检索与回灌分别花了多少溢出复盘最容易忽略的是复盘本身也在烧 Token。你为了查清第 47 轮为什么溢出把历史对话、工具日志、向量召回结果重新喂给模型这一次调用可能比原任务还贵。所以要把“复盘检索”和“记忆回灌”作为两个独立账本。下面是一张可填写的复盘 Token 对照表阶段调用方典型 Token 量建议预算观测点优化动作溢出快照复盘检索8k-20k单独计量输入长度、轮次范围只取最近 N 轮 错误摘要情景摘要压缩3k-8k摘要预算压缩比、字段完整率保留决策/错误/未完成 todo语义召回向量检索2k-12ktop_k × 单条上限命中率、引用率top_k≤6单条≤1200 Token程序回灌todo-state0.5k-2k固定注入目标漂移轮次每 2 轮复述目标与约束跨会话记忆记忆回灌4k-16k分层预算溢出率、重复率冷热分层热记忆常驻复盘问答模型对话5k-15k复盘总预算是否引入新事实先本地聚合再让模型解释填表时不要估算直接记录实际调用。可以给每次复盘打一个 ledgerfrom dataclasses import dataclass dataclass class ReplayTokenLedger: retrieval: int 0 rehydration: int 0 compression: int 0 todo_state: int 0 def add(self, phase: str, tokens: int) - None: if not hasattr(self, phase): raise ValueError(funknown phase: {phase}) setattr(self, phase, getattr(self, phase) tokens) def total(self) - int: return self.retrieval self.rehydration self.compression self.todo_state def report(self) - dict: total self.total() return { retrieval: self.retrieval, rehydration: self.rehydration, compression: self.compression, todo_state: self.todo_state, total: total, rehydration_ratio: round(self.rehydration / total, 3) if total else 0.0, } ledger ReplayTokenLedger() ledger.add(retrieval, 12400) ledger.add(rehydration, 8600) ledger.add(compression, 5200) ledger.add(todo_state, 1600) print(ledger.report())如果rehydration_ratio超过 0.35说明回灌过重优先压缩语义记忆如果todo_state很低但目标仍漂移说明复述模板没覆盖关键约束如果retrieval很高说明复盘检索本身需要先本地聚合再交给模型。6. Claude Code 接入 TaoTokensettings.json ANTHROPIC_* 三件套Claude Code 侧建议使用~/.claude/settings.json管理供应商配置。不要把 Key 写进项目仓库也不要用 Codex 的配置格式混搭。下面是一个可复制示例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5 }, permissions: { allow: [ Read, Write, Bash(git status), Bash(git diff), Bash(npm test) ], deny: [ Bash(rm -rf *), Bash(curl * | sh) ] } }这里的ANTHROPIC_*三件套是ANTHROPIC_BASE_URL请求地址固定为https://taotoken.net/api。ANTHROPIC_AUTH_TOKEN占位符YOUR_API_KEY替换成你的 TaoToken Key。ANTHROPIC_MODEL/ANTHROPIC_SMALL_FAST_MODEL主模型与快速模型。如果不想写进 settings.json也可以在 shell 里临时导出export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELclaude-sonnet-4-5 export ANTHROPIC_SMALL_FAST_MODELclaude-haiku-4-5 claude检查是否生效claude --version claude -p 只输出当前 Base URL 配置是否存在不要执行工具然后观察 Agent 启动日志里请求是否指向 TaoToken。如果仍然报旧供应商的错误先检查是否有更高优先级的环境变量覆盖了 settings.json。在 Claude Code 里做记忆分层时可以把memory_layers.yaml放在项目根目录并通过权限允许 Agent 读取但禁止它直接修改预算上限。运维工程师负责预算Agent 负责在预算内工作。7. Codex 接入 TaoTokenconfig.toml 不要混用 ANTHROPIC_*Codex 不要套用ANTHROPIC_*。它使用~/.codex/config.toml供应商通过model_providers声明。下面是一个 TaoToken 接入示例# ~/.codex/config.toml model gpt-5-codex model_provider taotoken approval_policy on-request sandbox_mode workspace-write [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api responses对应的环境变量export TAOTOKEN_API_KEYYOUR_API_KEY codex如果你同时使用 Claude Code 和 Codex建议把 Key 放在同一个密钥管理入口但配置格式分开Claude Code~/.claude/settings.json里的ANTHROPIC_*。Codex~/.codex/config.toml里的model_providers。通用 KeyTAOTOKEN_API_KEY或ANTHROPIC_AUTH_TOKEN按客户端要求注入。Codex 的排障重点是wire_api和base_url。如果报 404先确认客户端拼接路径是否与 TaoToken 兼容如果报 401检查env_key指向的环境变量是否真的导出。不要把 Claude Code 的ANTHROPIC_AUTH_TOKEN直接当作 Codex 的env_key两者语义不同。8. CC Switch 三件套让多 CLI 共用 TaoToken Base URL如果你在 Claude Code、Codex 和另一个 CLI 之间切换手动改配置很容易把供应商混掉。可以用 CC Switch 的思路管理三件套Claude Code 配置、Codex 配置、通用环境变量文件。这里给一个不依赖具体插件名的落地方式。第一件Claude Code settings.json路径~/.claude/settings.json内容见上一节。第二件Codex config.toml路径~/.codex/config.toml内容见上一节。第三件通用环境变量文件~/.config/taotoken/env.sh# ~/.config/taotoken/env.sh export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYYOUR_API_KEY # Claude Code export ANTHROPIC_BASE_URL$TAOTOKEN_BASE_URL export ANTHROPIC_AUTH_TOKEN$TAOTOKEN_API_KEY # Codex 仅使用 TAOTOKEN_API_KEY不要导出 ANTHROPIC_* 给 Codex 使用每次切换前 source 一次source ~/.config/taotoken/env.sh再写一个本地检查脚本避免配置漂移#!/usr/bin/env bash set -euo pipefail echo ANTHROPIC_BASE_URL${ANTHROPIC_BASE_URL:-未设置} echo ANTHROPIC_AUTH_TOKEN${ANTHROPIC_AUTH_TOKEN:已设置} echo TAOTOKEN_API_KEY${TAOTOKEN_API_KEY:已设置} if [[ ${ANTHROPIC_BASE_URL:-} ! https://taotoken.net/api ]]; then echo Claude Code Base URL 不一致请检查 ~/.claude/settings.json 或 env.sh fi if [[ ${TAOTOKEN_API_KEY:-} ]]; then echo Codex 缺少 TAOTOKEN_API_KEY fi三件套的管理原则是Base URL 只有一个真相源即https://taotoken.net/apiKey 只有一个占位符即YOUR_API_KEYClaude Code 和 Codex 的配置格式分开。你可以在 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_cc_switch确认控制台入口再配合本地脚本做切换。9. 回灌策略按优先级注入而不是全量塞回记忆分层配置写好之后真正的溢出防线在回灌策略。复盘时不要把所有检索结果一次性塞回主上下文。建议按优先级注入程序记忆目标、约束、todo-state固定注入成本最低优先级最高。工作记忆最近 N 轮消息和工具返回只保留当前步骤相关部分。情景记忆按任务阶段召回摘要优先决策、错误、未完成项。语义记忆按向量相似度和引用率过滤top_k 不超过 6单条不超过 1200 Token。可以用一个回灌计划器做预算裁剪def build_rehydration_plan(goal, constraints, todo_items, layers, budget): plan [] remaining budget procedural { layer: procedural, content: { goal: goal, constraints: constraints, todo: todo_items, }, priority: 0, } plan.append(procedural) for layer_name in (working, episodic, semantic): for item in layers.get(layer_name, []): if remaining 0: break cost item.get(tokens, 0) if cost remaining: continue plan.append({ layer: layer_name, content: item[content], priority: item.get(priority, 10), }) remaining - cost plan.sort(keylambda x: x[priority]) return plan, remaining if __name__ __main__: layers { working: [{content: 最近工具输出, tokens: 3000, priority: 1}], episodic: [{content: 第 32 轮目标漂移摘要, tokens: 1800, priority: 2}], semantic: [{content: 项目规范片段, tokens: 900, priority: 3}], } plan, left build_rehydration_plan( goal完成 Agent 长任务复盘, constraints[禁止直接操作生产库, SQL 仅本地执行], todo_items[补程序记忆, 补情景摘要], layerslayers, budget8000, ) print(剩余预算:, left) for step in plan: print(step[layer], step[priority])关键点回灌不是把向量库结果全量拼进 prompt而是先做预算裁剪再按优先级排序。复盘检索的高 Token 调用应该发生在本地或一次性批处理中主任务上下文里只保留结论和引用。10. 排障清单从 400/429 到目标丢失把下面这份清单放进 Agent 运维手册溢出复盘时逐项打勾400 prompt too long检查memory_layers.yaml各层max_tokens之和是否超过总预算检查working.unload_trigger是否触发。400 invalid_request_error确认 Base URL 是https://taotoken.net/apiKey 使用YOUR_API_KEY替换检查模型名是否在 TaoToken 模型列表中。401/403Claude Code 看ANTHROPIC_AUTH_TOKENCodex 看TAOTOKEN_API_KEY不要在 Codex 里找ANTHROPIC_*。404检查客户端拼接路径确认没有把 Base URL 写成带 UTM 的官网地址。429复盘检索和记忆回灌是否并发过高把语义召回改为批量限制 top_k。目标丢失检查procedural.repeat_interval把目标、约束、TODO 每 2 轮复述一次。跨会话召回不命中检查向量 metadata 是否带task_id、artifact_path、decision字段。压缩后信息丢失检查摘要字段白名单至少保留决策、错误、未完成 todo、产物路径。配置不生效检查环境变量优先级settings.json、config.toml、shell export 是否互相覆盖。复盘 Token 再次尖峰查ReplayTokenLedger.report()看rehydration_ratio是否超过 0.35。这份清单不解决所有问题但它能把“溢出”从偶发事故变成可观测、可回滚的运维事件。11. 复盘后的固化把记忆分层写进 Agent 运维手册一次溢出复盘的价值不在于写出一份事故报告而在于把结论固化成默认配置。建议复盘结束后完成三件事把memory_layers.yaml合并进项目模板作为 Agent 启动检查的一部分。把ReplayTokenLedger接入日志每次长任务结束后输出检索、回灌、压缩、todo-state 的 Token 占比。把排障清单加入值班手册下次出现prompt is too long时按顺序检查而不是直接换模型。如果你还没有稳定的 Key 和请求入口可以先在 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_manual完成注册与 Key 创建再把所有 AI CLI 的 Base URL 统一到https://taotoken.net/api。这样复盘数据才有可比性记忆分层的 Token 对照才有意义。12. CTA模型对话、Coding Plan、创建 Key、Claude Code 文档下一步可以根据你的使用方式选择入口想先验证模型对话和记忆回灌效果走模型对话https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_chat想把 Claude Code / Codex 长期接入长任务工作流看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_plan需要创建和管理自己的 Key进入 API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_keysClaude Code 侧配置细节参考 Claude Code 文档https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentoverflow_cc_doc把 Key 占位符YOUR_API_KEY替换掉把请求地址设为https://taotoken.net/api然后回到你的memory_layers.yaml和复盘 Token 对照表。溢出复盘时该补哪层记忆答案不在模型窗口里而在你的分层预算和回灌优先级里。 
