1M Context 也会失忆Coding Agent 为什么需要 Context LedgerTL;DR场景1M Context 解决容量上限却不能自动保证 compact 后约束不丢、仓库不漂移、prompt cache 仍然可用。结论Coding Agent 应建立 Context Ledger把 Context Window、Cache、History、Memory、Repository Snapshot、Tool Registry 分开记账区分 provider_surface model_id reasoning_effort policy_hash repo_snapshot tool_schema_hash summary_hash。产出六类状态分离 Context Ledger 四层字段 稳定前缀/半稳定工作状态/易变后缀三段组织 Cache Hit ≠ Context Correct 的五类风险 24 任务 × 3 策略 × 5 重复的对照实验设计。版本矩阵维度状态说明Kimi K3 发布日期✅ 已验证2026-07-16 / 2026-07-17官方与第三方报道时间点略有差异总参数✅ 已验证2.8T896 专家 / 激活 16上下文窗口✅ 已验证1,048,576 token全窗口统一定价默认 reasoning_effort✅ 已验证Open Platformkimi-k3默认maxKimi Codek3与k3-256k默认highAPI 模型 ID✅ 已验证Open Platformkimi-k3Kimi Codek3、k3-256kClaude Code 兼容kimi-k3[1m]输入价格缓存命中✅ 已验证$0.30 / 百万 token发布前需重新核价输入价格缓存未命中✅ 已验证$3.00 / 百万 token输出价格✅ 已验证$15.00 / 百万 tokencached_tokens 暴露✅ 已验证API 响应中可直接读取用于账本计算Prompt Cache 自动启用✅ 已验证不需要 cache ID无 TTL 管理256 token 才进入前缀缓存Kimi Code compact✅ 已验证支持自动压缩与手动/compact [instruction]新版本会把 todo 列表附加到摘要完整权重开源✅ 已验证官方承诺最迟 2026-07-27 发布完整权重1M 上下文与窗口越大越聪明❌ 不成立容量扩展不解决约束丢失、仓库漂移、缓存失效问题cache hit 证明上下文正确❌ 不成立仅证明前缀计算复用不证明摘要完整、仓库未漂移或授权有效Kimi Code 额度与 Open Platform 美元成本直接互换❌ 不成立计费单位不同发布边界价格、会员层级、模型 ID、默认 effort、缓存与 compact 行为需在发布前复核本文不声称已完成本地吞吐或成本实测。摘要1M Context 解决容量上限却不能自动保证约束没有在 compact 中丢失、仓库没有漂移、缓存仍然有效。本文把 Context Window、Cache、History、Memory、Repository Snapshot 与 Tool Registry 分开并提出一份可回放、可归因的 Context Ledger。关键词Kimi K3、Context Ledger、Context Cache、Compaction、Agent Harness目录一、先停止把六种东西都叫记忆二、K3 的 1M、自动缓存和产品入口必须分开解释三、Context Ledger 应记录什么四、把请求组织成稳定前缀、半稳定工作状态和易变后缀五、为什么 cache hit 不能证明上下文正确六、怎样做一组不虚构结果的对照实验七、最后把选择写成工程规则先看一种由多个官方机制组合而成的合成故障链。它用于说明风险不代表已经发生的客户事故或本文完成了本地实测。一个 Agent 已经在同一仓库里工作了几十轮。它读过架构说明、测试约束、禁止修改的目录也完成了第一批代码改动。当前会话接近 256K操作者为了节省 Kimi Code 额度把模型从k3切到k3-256k。由于上下文已经超过 256K客户端先做 compact把此前消息压成一段摘要。摘要保留了继续完成支付模块重构却漏掉了不得修改数据库迁移文件和必须复用已有幂等键的约束。与此同时模型切换使原有 prompt cache 失效长前缀需要重新 prefill。新模型拿到的是一份更短、但不完整的历史它发现缺少局部代码证据于是再次读取仓库随后生成了一个能通过部分测试、却违反原始约束的补丁。账单或额度曲线在这一轮突然抬升端到端延迟也变长。这不是1M 上下文不够长而是系统没有回答四个更基本的问题这一轮上下文到底由什么组成哪些内容是原文哪些是摘要当前仓库还是不是模型曾经读过的那个版本一次 cache hit 或 cache miss 应该归因于什么变化Kimi 官方文档说明Open Platform 的kimi-k3支持最多 1M token上下文缓存会自动尝试复用重复的初始前缀Kimi Code 则提供k3和k3-256k两个不同模型 ID并明确提示模型或 reasoning effort 的切换可能使缓存失效1M 降到 256K 时还可能由工具侧触发 compact。S1、S3、S5、S8、S9这些能力解决的是容量、推理计算复用和客户端会话管理不等于生产状态已经被正确管理。真正需要建立的是一份Context Ledger上下文账本。它不是再造一套聊天记录而是把每次请求所依赖的状态、状态版本、压缩边界、缓存结果和任务结果放进同一条可追溯链路。上下文窗口只是容量上限账本才负责说明这个容量里装了什么、为什么可信、何时失效以及失效造成了多少成本。一、先停止把六种东西都叫记忆生产系统最常见的概念错误是把 Context Window、Context Cache、Agent Memory、Conversation History、Repository Snapshot 和 Tool Registry 全部归入模型记忆。它们实际上回答六个不同问题。Context Window是一次推理允许容纳的最大 token 总量。Kimi Open Platform 文档把kimi-k3的窗口写为 1M token模型参数表给出的精确上限是 1,048,576输入与输出共同占用这个预算。S1、S6它回答最多能放多少不回答应该放什么也不保证长上下文中的约束一定被正确使用。Context Cache是对重复初始前缀的计算复用。Kimi API 自动启用缓存不要求调用方创建 cache ID也不提供需要自行管理的 TTL当系统识别到重复的 system prompt、文档或工具定义时可能复用已计算的前缀。官方还说明前一请求的 prompt 超过 256 token 才可能进入前缀缓存并通过响应中的cached_tokens暴露命中量。S5、S7它回答哪些输入 token 不必重新 prefill不是长期业务记忆更不是事实新鲜度证明。Agent Memory应由 Harness 管理是跨轮次乃至跨 Session 保存的结构化状态例如用户确认过的决策、任务约束、失败经验、实体关系或可检索笔记。它需要来源、更新时间、作用域和撤销机制。API 是否命中缓存与这类记忆是否存在没有必然关系。Conversation History是本轮请求重放给模型的消息序列。Kimi API 本身是无状态的不保存多轮历史调用方必须把此前 assistant 消息和工具结果重新加入messages。Kimi Code CLI 则会把 Session 的事件流持久化到本地用于恢复和回放。S7、S10历史是事件记录不等于已经提炼好的工作状态。Repository Snapshot是 Agent 所依据的代码世界版本。至少要能定位 commit 或 tree hash、branch、dirty diff、submodule、依赖锁文件和生成物状态。模型读过payment/service.go只说明它见过某一时刻的文件内容如果人类、另一个 Agent 或格式化工具随后改了文件旧阅读结果就已经过期。Tool Registry是当前可调用工具的契约集合包括工具名、JSON Schema、版本、权限、端点、超时和副作用级别。只有工具名相同不代表工具语义相同。参数从path改成paths、默认分支从只读改成写入、MCP Server 升级或权限策略变化都会让旧上下文中的调用计划失效。把六者分开后故障定位才有可能成立约束丢失是 compaction 问题重复读仓库可能是 Repository Snapshot 未复用成本突增可能是缓存失效错误工具调用可能是 Tool Registry 漂移。它们不能再被笼统归因成模型忘了。二、K3 的 1M、自动缓存和产品入口必须分开解释Kimi 的官方页面存在三个容易被混写的产品入口Open Platform API、Kimi Code以及包含 Kimi Code 权益的会员产品。三者的 Key、余额或权益和计费方式并不通用。S1、S3因此Context Ledger 首先要记录provider_surface再记录model_id不能只写一个K3。在Open Platform API中直接调用使用kimi-k3。该模型最多支持 1M tokenreasoning_effort可取low、high、max默认是max。API 按 token 计费截至本次访问K3 每 100 万 token 的缓存命中输入、缓存未命中输入和输出价格分别为 0.30、3.00 和 15.00 美元未含适用税费。S4、S6响应提供prompt_tokens、completion_tokens、cached_tokens因此账本可以计算cache_hit_tokens cached_tokenscache_miss_tokens prompt_tokens - cached_tokensrequest_cost hit_tokens × 0.30 / 1,000,000 miss_tokens × 3.00 / 1,000,000 output_tokens × 15.00 / 1,000,000这只是当前官方价格下的计算式发布前必须重新核价并单独计入 Web Search 等附加能力的费用。在Kimi Code中模型 ID 是k3与k3-256k。文档写明两者默认 reasoning effort 都是highk3-256k固定为 256Kk3的最高 1M 能力取决于会员等级。Kimi Code 采用会员额度语境官方称 1M 的k3大约消耗k3-256k两倍额度这不能直接换算成 Open Platform 的美元价格。S8模型 ID 的差异也不只是命名问题。Kimi 的故障排查页面指出Open Platform 直接 API 与 Codex 集成使用kimi-k3Claude Code 的兼容路径可能使用kimi-k3[1m]Kimi Code 自己的兼容端点又使用k3或k3-256k。S3、S8如果 Harness 在不同适配器之间只保存K3就无法知道一次恢复究竟回到了哪个产品、哪个上下文上限和哪个默认 effort。官方文档还给出一个值得保留原貌的版本化差异Kimi Code 的通用说明和发布日志都说切换模型 ID 或 effort 会使已有 prompt cache 失效建议新建 Session但同一模型配置页又对当前版本从k3-256k升到k3给出限定说明称该方向目前不影响缓存。S8、S9这不是应该由文章替官方消除的矛盾而是账本必须记录client_version、切换方向和实际cached_tokens的理由。生产规则应以观测结果为准不能把某一版客户端的例外写成永久协议。三、Context Ledger 应记录什么一份可用的账本至少分成任务、上下文、请求和结果四层。下面是一条最小记录的示意字段名可以落入数据库、Trace Span 或 JSONL{task_id:TASK-8421,session_id:sess-17,attempt_id:a3,provider_surface:kimi_open_platform,model_id:kimi-k3,model_version:unknown_alias_resolution,reasoning_effort:high,policy_hash:sha256:...,repo_snapshot:git:4f8c...dirty:9a1b...,tool_schema_hash:sha256:...,history_range:event:120-188,summary_hash:sha256:...,cache_hit_tokens:184320,cache_miss_tokens:17342,compaction_event:{occurred:true,reason:model_window_downshift,source_range:event:1-119,preserve_manifest_hash:sha256:...,validator:constraint-check-v2}}任务层必须有task_id并区分 Session 与 Attempt。一次任务失败后新建 Session 重试仍应归到同一任务否则每 Session 成本下降可能只是把失败成本藏到了别处。模型层至少记录model_id、model_version、reasoning_effort和客户端或适配器版本。若供应商只暴露滚动别名model_version应明确写成未知或别名解析时间而不是伪造一个精确版本。Kimi API 的响应model字段、Kimi Code 的运行状态和客户端版本都应原样保存。上下文层记录policy_hash、repo_snapshot、tool_schema_hash、history_range与summary_hash。哈希之前必须先做确定性序列化统一字段顺序、换行、编码和路径规范否则只是无意义地制造 miss。除总哈希外还应保存可解释的 manifest例如策略文件列表、工具版本表、仓库 commit 与 dirty 文件清单。压缩层不能只有compactedtrue。compaction_event还要记录触发者、触发原因、压缩前 token、源历史范围、摘要生成模型、保留指令、摘要哈希、被删除的原文位置以及压缩后的约束校验结果。Kimi Code 支持自动压缩和手动/compact [instruction]发布日志还提到新版会把 todo 列表附加到摘要中。S9、S10、S11这说明 compact 本身就是一次有损状态迁移应像数据库迁移一样审计而不是当作普通聊天清理。请求层记录prompt_tokens、cache_hit_tokens、cache_miss_tokens、输出 token、TTFT、端到端耗时、工具调用次数、重复读取字节数和请求 ID。结果层记录功能测试、约束测试、人工验收、错误类型和是否回滚。只有把成本与成功结果连接起来才有每个成功任务成本而不只是便宜但失败的请求均价。账本还应生成一个可比较的context_identity例如由provider_surface model_id reasoning_effort policy_hash repo_snapshot tool_schema_hash summary_hash组合后再做哈希。它不是供应商缓存键而是 Harness 自己的上下文身份。两个请求即使都显示 80% cache hit只要context_identity不同就不能被当作同一实验条件反过来如果身份相同却出现命中率骤降就可以进一步检查消息排序、客户端升级、隐式工具注入或供应商侧缓存波动。对每次 compact还应保存压缩前后的身份映射使团队能够从一个错误补丁反查到它究竟继承了哪份摘要。四、把请求组织成稳定前缀、半稳定工作状态和易变后缀自动前缀缓存要求重复的初始上下文尽量稳定。一个适合 Coding Agent 的组织方法是把每次请求拆成三层但每层都必须版本化。第一层是稳定前缀组织策略、权限边界、输出协议、长期不变的项目约束以及本轮确实启用的工具 Schema。它应采用固定排序和固定序列化末尾附上policy_hash与tool_schema_hash。失效条件包括策略变更、工具参数或权限变化、模型 ID 变化、reasoning effort 变化以及适配器改变消息排列。Kimi 官方明确把 system prompt、知识文档和工具定义列为适合稳定前缀的内容并提醒修改前缀会降低命中率。S3、S5第二层是半稳定工作状态当前目标、已确认决策、执行计划、仓库快照、相关文件摘要、测试基线、尚未解决的阻塞项。它不应随着每条工具输出都整体重写而应按 epoch 更新。例如完成一次提交、切换 branch、依赖锁文件变化或用户改变验收标准时生成新的work_state_version。其失效条件是repo_snapshot改变、摘要被重算、计划被批准或撤销、检索索引落后于仓库。第三层是易变后缀当前用户指令、最近几轮对话、刚返回的工具结果、当前 diff 和错误日志。它天然每轮变化不应为了追求 cache hit 被强行塞入稳定区。后缀的目标是小、近、可丢弃真正需要跨轮保存的结论应先通过验证再晋升到半稳定工作状态。这种分层的价值不只在缓存。当 Agent 重复读取仓库时Harness 可以检查相同repo_snapshot下这个文件是否已经有内容哈希和可信摘要当工具升级时可以只使 Tool Registry 相关前缀失效当用户修改策略时可以强制重建第一层而不是继续复用一个高命中但过期的前缀。五、为什么 cache hit 不能证明上下文正确缓存命中只说明请求前缀与某个可复用计算相匹配。它不证明前缀中的内容仍然适用于当前任务也不证明上下文完整。第一种风险是过期策略。旧policy_hash对应的前缀可以获得很高命中率但如果安全团队已经禁止网络访问继续复用旧规则反而稳定地产生错误行为。第二种风险是工具版本漂移。工具名和大部分 Schema 未变缓存仍可能命中但后端语义、权限或副作用已经变化。账本必须把工具版本、端点和权限纳入 manifest而不能只哈希展示给模型的名称。第三种风险是错误摘要。一次 compact 把不允许修改 migrations漏掉后这份摘要可以在后续多轮被稳定复用。缓存越好错误传播得越便宜、越快。summary_hash只能证明摘要没变不能证明摘要正确还需要约束清单校验、来源回链和必要时的原文抽查。第四种风险是仓库已变化。模型对旧文件内容的前缀命中不代表当前 working tree 仍相同。只有repo_snapshot一致历史阅读结果才有资格复用。第五种风险是跨模型状态不兼容。不同模型或 effort 可能要求不同的 reasoning 字段、工具消息结构和压缩策略。Kimi 官方明确要求多轮 K3 请求回传完整 assistant message并记录模型或 effort 切换的缓存失效风险。S6、S8、S9因此恢复 Session 前必须执行兼容性检查而不是把上一模型的历史盲目塞给下一模型。生产看板至少要同时展示两组指标计算复用指标与语义正确指标。前者包括 hit tokens、miss tokens、hit ratio、TTFT 和输入成本后者包括策略版本一致率、仓库快照一致率、摘要约束召回率、工具 Schema 一致率和任务成功率。只有两组都通过缓存才是优化而不是把错误加速。六、怎样做一组不虚构结果的对照实验可以用同一批冻结仓库与验收测试对比三种上下文策略A 组全历史每轮携带完整消息B 组稳定前缀加增量组合稳定前缀、版本化工作状态和增量后缀C 组检索加短历史只保留稳定策略与短历史其余代码证据通过检索按需注入。任务集建议包含 24 个任务8 个单文件或小功能任务、8 个跨模块修改、8 个长链路任务。每组都要包含显式约束陷阱例如禁止改某目录、必须复用既有接口、只能调用只读工具。每个任务固定 commit、依赖、测试命令和验收脚本每种策略独立运行 5 次共 360 条任务轨迹。由于 K3 的采样参数并非都可自由设为零应通过重复、随机化运行顺序和相同时间窗降低偶然性而不是拿一次结果下结论。S6一次成功必须同时满足目标测试通过无禁止文件改动工具权限与副作用合规补丁能够从干净快照复现任务没有依赖人工补写被遗漏的原始约束。错误分类至少包括约束丢失、仓库状态过期、摘要遗漏、工具契约不匹配、上下文溢出或 compact 失败、重复读取或循环、功能失败。每条轨迹记录端到端耗时和 TTFT 的 P50/P95、输入与输出 token、cached_tokens、计算得到的 miss tokens、缓存命中率、总成本、每成功任务成本、重复文件读取字节数、工具调用次数、compact 次数和失败恢复次数。A/B/C 三组必须使用同一 Open Platform 模型 ID 与 effort不能把kimi-k3的美元成本和 Kimi Code 会员额度混在一张表里。另做一组 Kimi Code 故障注入在固定 Session 中分别执行 effort 切换、k3→k3-256k、k3-256k→k3、自动 compact 和手动 compact。记录客户端版本、切换方向、压缩前后约束召回和实际额度变化用来验证当前文档中的通用规则与限定例外。这里同样只报告实测不预填B 组一定最好之类结论。七、最后把选择写成工程规则优先使用 256K当经过检索后的有效工作集、短历史和预留输出空间稳定落在 256K 内任务是日常问答、补全、常规功能开发或少量文件修改时256K 应是默认档。Kimi Code 官方也把k3-256k定位在这些场景并提醒其不支持视频输入。S8升级到 1M当跨模块迁移、长测试证据、大量相互依赖文件或无法安全压缩的决策链确实超过 256K 时再升级到 1M。升级依据应是账本里的 working-set 估算和历史失败证据而不是窗口越大越聪明。接近 256K 且压缩可能丢失关键证据时Kimi Code 文档允许直接从k3-256k升到k3但仍要记录客户端版本并验证实际缓存结果。S8新建 Session模型 ID 或 effort 要改变、任务目标已经切换、策略版本改变、仓库基线大幅变化或者现有摘要无法通过约束校验时应新建 Session。Kimi Code 对模型与 effort 切换也明确建议/new以避免旧缓存失效后的额外消耗。S8、S9执行 compact同一任务、同一模型下早期历史大多已收敛且可被结构化状态替代时可以 compact从 1M 降到 256K 前若会话超限也应先显式 compact。压缩前必须生成保留清单压缩后运行约束、计划、未完成 todo 和关键证据的自动校验。没有校验的摘要不能成为新的事实源。重新构建上下文只要policy_hash、repo_snapshot、tool_schema_hash或summary_hash与预期不符检索索引落后工具语义升级跨模型历史结构不兼容或者 cache hit 很高但正确性 canary 失败就应放弃复用按权威来源重新构建三层上下文。最终Context Ledger 的目标不是追求最高缓存命中率也不是让每个 Session 尽可能长。它要让团队能回答一次任务为什么成功或失败哪段状态被压缩或过期哪次切换导致 re-prefill重复读取浪费了多少扩大窗口是否真正改善了每成功任务成本。1M Context 给了 Agent 更大的工作台但不会替你整理工作台。只有把模型、策略、仓库、工具、历史、摘要、缓存与结果统一记账长上下文才从一个容量卖点变成可以复现、比较和治理的生产能力。FAQContext Ledger 是另一份聊天记录吗不是。它记录请求依赖的状态版本、哈希、压缩边界、缓存与结果用于重放和归因。Cache Hit 为什么不能证明上下文正确它只证明前缀计算被复用无法证明摘要完整、仓库未漂移或任务授权仍有效。先上 1M 还是先做账本二者解决不同问题即使使用 1M也应先有最小账本否则错误与成本都难以解释。错误速查卡症状根因定位修复cache hit 80% 但答案明显违反原始约束摘要遗漏了不可违反的约束缓存越高效传播越快检查summary_hash对应摘要的约束清单是否完整定位 compact 前的源历史摘要生成后跑约束/计划/todo 校验未通过则不作为新的事实源账本记录validator失败原因切换k3→k3-256k后长前缀被重新 prefill账单突增客户端升级、模型 ID 或 effort 改变使 prompt cache 失效查账本model_id/reasoning_effort/client_version与cached_tokens跳变点跨档切换按官方建议先/new记录切换方向把 hit 骤降归因为代际切换而不是缓存策略错同一仓库不同 Session 下行为不一致repo_snapshot没绑定历史阅读结果模型读到的是过期文件账本repo_snapshot字段是否记录 commit dirty diff 依赖锁文件Harness 在 commit 变化或 dirty 文件变化时强制重建上下文不允许裸 path 引用调用工具时收到参数不匹配或权限拒绝Tool Schema 漂移旧上下文还在用旧参数 / 旧权限比对账本tool_schema_hash与 Tool Registry 当前 manifest工具版本/端点/权限变化时只重建第一层稳定前缀并把变化记入 manifest1M 上下文里模型显得很聪明但仍违反本地约束容量扩展 ≠ 状态管理约束在 compact 中被丢弃查账本 compact_event 链哪一次压缩、什么触发、保留清单、校验结果压缩前生成 preserve_manifest压缩后跑约束校验校验失败强制从原文重建每 Session 成本下降但每个成功任务成本没变失败成本被新 Session 隐藏没有以 task_id 归并账本是否在 task 层把同一 task 的多次 attempt 关联任务层强制task_idattempt_id按 task 归并而非按 Session 归并团队复盘时无法回答哪次切换导致 re-prefill账本只记 hit/miss没记代际 / 客户端 / 切换方向查账本是否记录client_version、model_id切换、effort 切换与方向增加context_identity hash(provider_surface model_id effort policy repo tool summary)identity 改变即重建账本摘要说已完成支付模块重构模型以为当前任务就是这个compact 时把当前目标误晋升为已完成事实查history_range与summary_hash定位摘要生成时刻的状态摘要里区分目标与完成事实前者必须经约束/测试/人工确认才晋升为完成事实检索到的代码片段命中但引用了已删除文件Repository Snapshot 落后于仓库repo_snapshot与 working tree 不一致检索前强制 rebase 到当前repo_snapshot检索索引落后时拒绝检索每次 commit、dirty 文件变化或依赖锁文件变化都刷新 snapshot旧摘要标注 stale禁止直接喂给模型Kimi Code 会员额度与 Open Platform 美元成本混算两个产品入口的 Key/余额/计费方式不通用查账本provider_surface是否正确区分Context Ledger 强制先记provider_surface再记model_id成本按 surface 分表计算8 个跨模块任务中频繁超时、TTFT 抖动大1M 上下文做 prefill 拖慢首 token任务实际不需要 1M查账本working-set估算有效工作集是否真的超过 256K优先用 256K 检索注入只有账本显示 working-set 超过 256K 才升 1M同一约束在 5 轮 compact 后被悄悄抹掉compact 是有损状态迁移但日志只记compactedtrue查compaction_event是否记录触发者 / 原因 / 源历史 / 保留清单 / 校验结果compact 必须像数据库迁移一样审计保留清单 校验 摘要哈希全部进账本Harness 在不同适配器之间把 K3 都记成同一个模型 ID 在不同产品入口命名不同kimi-k3/k3/k3-256k/kimi-k3[1m]查账本provider_surface与model_id是否成对保存账本字段必须成对恢复 Session 前做兼容性检查不盲塞上一模型历史一次任务失败后新建 Session 重试审计上看不到关联Session 与 Attempt 都被当成独立事件查账本是否以task_id归并 attempt任务层强制task_idattempt_id同一 task 的所有 attempt 共享 task 级成本与结果指标作者武子康的个人博客
1M Context 也会失忆Coding Agent 为什么需要 Context LedgerTL;DR场景1M Context 解决容量上限却不能自动保证 compact 后约束不丢、仓库不漂移、prompt cache 仍然可用。结论Coding Agent 应建立 Context Ledger把 Context Window、Cache、History、Memory、Repository Snapshot、Tool Registry 分开记账区分 provider_surface model_id reasoning_effort policy_hash repo_snapshot tool_schema_hash summary_hash。产出六类状态分离 Context Ledger 四层字段 稳定前缀/半稳定工作状态/易变后缀三段组织 Cache Hit ≠ Context Correct 的五类风险 24 任务 × 3 策略 × 5 重复的对照实验设计。版本矩阵维度状态说明Kimi K3 发布日期✅ 已验证2026-07-16 / 2026-07-17官方与第三方报道时间点略有差异总参数✅ 已验证2.8T896 专家 / 激活 16上下文窗口✅ 已验证1,048,576 token全窗口统一定价默认 reasoning_effort✅ 已验证Open Platformkimi-k3默认maxKimi Codek3与k3-256k默认highAPI 模型 ID✅ 已验证Open Platformkimi-k3Kimi Codek3、k3-256kClaude Code 兼容kimi-k3[1m]输入价格缓存命中✅ 已验证$0.30 / 百万 token发布前需重新核价输入价格缓存未命中✅ 已验证$3.00 / 百万 token输出价格✅ 已验证$15.00 / 百万 tokencached_tokens 暴露✅ 已验证API 响应中可直接读取用于账本计算Prompt Cache 自动启用✅ 已验证不需要 cache ID无 TTL 管理256 token 才进入前缀缓存Kimi Code compact✅ 已验证支持自动压缩与手动/compact [instruction]新版本会把 todo 列表附加到摘要完整权重开源✅ 已验证官方承诺最迟 2026-07-27 发布完整权重1M 上下文与窗口越大越聪明❌ 不成立容量扩展不解决约束丢失、仓库漂移、缓存失效问题cache hit 证明上下文正确❌ 不成立仅证明前缀计算复用不证明摘要完整、仓库未漂移或授权有效Kimi Code 额度与 Open Platform 美元成本直接互换❌ 不成立计费单位不同发布边界价格、会员层级、模型 ID、默认 effort、缓存与 compact 行为需在发布前复核本文不声称已完成本地吞吐或成本实测。摘要1M Context 解决容量上限却不能自动保证约束没有在 compact 中丢失、仓库没有漂移、缓存仍然有效。本文把 Context Window、Cache、History、Memory、Repository Snapshot 与 Tool Registry 分开并提出一份可回放、可归因的 Context Ledger。关键词Kimi K3、Context Ledger、Context Cache、Compaction、Agent Harness目录一、先停止把六种东西都叫记忆二、K3 的 1M、自动缓存和产品入口必须分开解释三、Context Ledger 应记录什么四、把请求组织成稳定前缀、半稳定工作状态和易变后缀五、为什么 cache hit 不能证明上下文正确六、怎样做一组不虚构结果的对照实验七、最后把选择写成工程规则先看一种由多个官方机制组合而成的合成故障链。它用于说明风险不代表已经发生的客户事故或本文完成了本地实测。一个 Agent 已经在同一仓库里工作了几十轮。它读过架构说明、测试约束、禁止修改的目录也完成了第一批代码改动。当前会话接近 256K操作者为了节省 Kimi Code 额度把模型从k3切到k3-256k。由于上下文已经超过 256K客户端先做 compact把此前消息压成一段摘要。摘要保留了继续完成支付模块重构却漏掉了不得修改数据库迁移文件和必须复用已有幂等键的约束。与此同时模型切换使原有 prompt cache 失效长前缀需要重新 prefill。新模型拿到的是一份更短、但不完整的历史它发现缺少局部代码证据于是再次读取仓库随后生成了一个能通过部分测试、却违反原始约束的补丁。账单或额度曲线在这一轮突然抬升端到端延迟也变长。这不是1M 上下文不够长而是系统没有回答四个更基本的问题这一轮上下文到底由什么组成哪些内容是原文哪些是摘要当前仓库还是不是模型曾经读过的那个版本一次 cache hit 或 cache miss 应该归因于什么变化Kimi 官方文档说明Open Platform 的kimi-k3支持最多 1M token上下文缓存会自动尝试复用重复的初始前缀Kimi Code 则提供k3和k3-256k两个不同模型 ID并明确提示模型或 reasoning effort 的切换可能使缓存失效1M 降到 256K 时还可能由工具侧触发 compact。S1、S3、S5、S8、S9这些能力解决的是容量、推理计算复用和客户端会话管理不等于生产状态已经被正确管理。真正需要建立的是一份Context Ledger上下文账本。它不是再造一套聊天记录而是把每次请求所依赖的状态、状态版本、压缩边界、缓存结果和任务结果放进同一条可追溯链路。上下文窗口只是容量上限账本才负责说明这个容量里装了什么、为什么可信、何时失效以及失效造成了多少成本。一、先停止把六种东西都叫记忆生产系统最常见的概念错误是把 Context Window、Context Cache、Agent Memory、Conversation History、Repository Snapshot 和 Tool Registry 全部归入模型记忆。它们实际上回答六个不同问题。Context Window是一次推理允许容纳的最大 token 总量。Kimi Open Platform 文档把kimi-k3的窗口写为 1M token模型参数表给出的精确上限是 1,048,576输入与输出共同占用这个预算。S1、S6它回答最多能放多少不回答应该放什么也不保证长上下文中的约束一定被正确使用。Context Cache是对重复初始前缀的计算复用。Kimi API 自动启用缓存不要求调用方创建 cache ID也不提供需要自行管理的 TTL当系统识别到重复的 system prompt、文档或工具定义时可能复用已计算的前缀。官方还说明前一请求的 prompt 超过 256 token 才可能进入前缀缓存并通过响应中的cached_tokens暴露命中量。S5、S7它回答哪些输入 token 不必重新 prefill不是长期业务记忆更不是事实新鲜度证明。Agent Memory应由 Harness 管理是跨轮次乃至跨 Session 保存的结构化状态例如用户确认过的决策、任务约束、失败经验、实体关系或可检索笔记。它需要来源、更新时间、作用域和撤销机制。API 是否命中缓存与这类记忆是否存在没有必然关系。Conversation History是本轮请求重放给模型的消息序列。Kimi API 本身是无状态的不保存多轮历史调用方必须把此前 assistant 消息和工具结果重新加入messages。Kimi Code CLI 则会把 Session 的事件流持久化到本地用于恢复和回放。S7、S10历史是事件记录不等于已经提炼好的工作状态。Repository Snapshot是 Agent 所依据的代码世界版本。至少要能定位 commit 或 tree hash、branch、dirty diff、submodule、依赖锁文件和生成物状态。模型读过payment/service.go只说明它见过某一时刻的文件内容如果人类、另一个 Agent 或格式化工具随后改了文件旧阅读结果就已经过期。Tool Registry是当前可调用工具的契约集合包括工具名、JSON Schema、版本、权限、端点、超时和副作用级别。只有工具名相同不代表工具语义相同。参数从path改成paths、默认分支从只读改成写入、MCP Server 升级或权限策略变化都会让旧上下文中的调用计划失效。把六者分开后故障定位才有可能成立约束丢失是 compaction 问题重复读仓库可能是 Repository Snapshot 未复用成本突增可能是缓存失效错误工具调用可能是 Tool Registry 漂移。它们不能再被笼统归因成模型忘了。二、K3 的 1M、自动缓存和产品入口必须分开解释Kimi 的官方页面存在三个容易被混写的产品入口Open Platform API、Kimi Code以及包含 Kimi Code 权益的会员产品。三者的 Key、余额或权益和计费方式并不通用。S1、S3因此Context Ledger 首先要记录provider_surface再记录model_id不能只写一个K3。在Open Platform API中直接调用使用kimi-k3。该模型最多支持 1M tokenreasoning_effort可取low、high、max默认是max。API 按 token 计费截至本次访问K3 每 100 万 token 的缓存命中输入、缓存未命中输入和输出价格分别为 0.30、3.00 和 15.00 美元未含适用税费。S4、S6响应提供prompt_tokens、completion_tokens、cached_tokens因此账本可以计算cache_hit_tokens cached_tokenscache_miss_tokens prompt_tokens - cached_tokensrequest_cost hit_tokens × 0.30 / 1,000,000 miss_tokens × 3.00 / 1,000,000 output_tokens × 15.00 / 1,000,000这只是当前官方价格下的计算式发布前必须重新核价并单独计入 Web Search 等附加能力的费用。在Kimi Code中模型 ID 是k3与k3-256k。文档写明两者默认 reasoning effort 都是highk3-256k固定为 256Kk3的最高 1M 能力取决于会员等级。Kimi Code 采用会员额度语境官方称 1M 的k3大约消耗k3-256k两倍额度这不能直接换算成 Open Platform 的美元价格。S8模型 ID 的差异也不只是命名问题。Kimi 的故障排查页面指出Open Platform 直接 API 与 Codex 集成使用kimi-k3Claude Code 的兼容路径可能使用kimi-k3[1m]Kimi Code 自己的兼容端点又使用k3或k3-256k。S3、S8如果 Harness 在不同适配器之间只保存K3就无法知道一次恢复究竟回到了哪个产品、哪个上下文上限和哪个默认 effort。官方文档还给出一个值得保留原貌的版本化差异Kimi Code 的通用说明和发布日志都说切换模型 ID 或 effort 会使已有 prompt cache 失效建议新建 Session但同一模型配置页又对当前版本从k3-256k升到k3给出限定说明称该方向目前不影响缓存。S8、S9这不是应该由文章替官方消除的矛盾而是账本必须记录client_version、切换方向和实际cached_tokens的理由。生产规则应以观测结果为准不能把某一版客户端的例外写成永久协议。三、Context Ledger 应记录什么一份可用的账本至少分成任务、上下文、请求和结果四层。下面是一条最小记录的示意字段名可以落入数据库、Trace Span 或 JSONL{task_id:TASK-8421,session_id:sess-17,attempt_id:a3,provider_surface:kimi_open_platform,model_id:kimi-k3,model_version:unknown_alias_resolution,reasoning_effort:high,policy_hash:sha256:...,repo_snapshot:git:4f8c...dirty:9a1b...,tool_schema_hash:sha256:...,history_range:event:120-188,summary_hash:sha256:...,cache_hit_tokens:184320,cache_miss_tokens:17342,compaction_event:{occurred:true,reason:model_window_downshift,source_range:event:1-119,preserve_manifest_hash:sha256:...,validator:constraint-check-v2}}任务层必须有task_id并区分 Session 与 Attempt。一次任务失败后新建 Session 重试仍应归到同一任务否则每 Session 成本下降可能只是把失败成本藏到了别处。模型层至少记录model_id、model_version、reasoning_effort和客户端或适配器版本。若供应商只暴露滚动别名model_version应明确写成未知或别名解析时间而不是伪造一个精确版本。Kimi API 的响应model字段、Kimi Code 的运行状态和客户端版本都应原样保存。上下文层记录policy_hash、repo_snapshot、tool_schema_hash、history_range与summary_hash。哈希之前必须先做确定性序列化统一字段顺序、换行、编码和路径规范否则只是无意义地制造 miss。除总哈希外还应保存可解释的 manifest例如策略文件列表、工具版本表、仓库 commit 与 dirty 文件清单。压缩层不能只有compactedtrue。compaction_event还要记录触发者、触发原因、压缩前 token、源历史范围、摘要生成模型、保留指令、摘要哈希、被删除的原文位置以及压缩后的约束校验结果。Kimi Code 支持自动压缩和手动/compact [instruction]发布日志还提到新版会把 todo 列表附加到摘要中。S9、S10、S11这说明 compact 本身就是一次有损状态迁移应像数据库迁移一样审计而不是当作普通聊天清理。请求层记录prompt_tokens、cache_hit_tokens、cache_miss_tokens、输出 token、TTFT、端到端耗时、工具调用次数、重复读取字节数和请求 ID。结果层记录功能测试、约束测试、人工验收、错误类型和是否回滚。只有把成本与成功结果连接起来才有每个成功任务成本而不只是便宜但失败的请求均价。账本还应生成一个可比较的context_identity例如由provider_surface model_id reasoning_effort policy_hash repo_snapshot tool_schema_hash summary_hash组合后再做哈希。它不是供应商缓存键而是 Harness 自己的上下文身份。两个请求即使都显示 80% cache hit只要context_identity不同就不能被当作同一实验条件反过来如果身份相同却出现命中率骤降就可以进一步检查消息排序、客户端升级、隐式工具注入或供应商侧缓存波动。对每次 compact还应保存压缩前后的身份映射使团队能够从一个错误补丁反查到它究竟继承了哪份摘要。四、把请求组织成稳定前缀、半稳定工作状态和易变后缀自动前缀缓存要求重复的初始上下文尽量稳定。一个适合 Coding Agent 的组织方法是把每次请求拆成三层但每层都必须版本化。第一层是稳定前缀组织策略、权限边界、输出协议、长期不变的项目约束以及本轮确实启用的工具 Schema。它应采用固定排序和固定序列化末尾附上policy_hash与tool_schema_hash。失效条件包括策略变更、工具参数或权限变化、模型 ID 变化、reasoning effort 变化以及适配器改变消息排列。Kimi 官方明确把 system prompt、知识文档和工具定义列为适合稳定前缀的内容并提醒修改前缀会降低命中率。S3、S5第二层是半稳定工作状态当前目标、已确认决策、执行计划、仓库快照、相关文件摘要、测试基线、尚未解决的阻塞项。它不应随着每条工具输出都整体重写而应按 epoch 更新。例如完成一次提交、切换 branch、依赖锁文件变化或用户改变验收标准时生成新的work_state_version。其失效条件是repo_snapshot改变、摘要被重算、计划被批准或撤销、检索索引落后于仓库。第三层是易变后缀当前用户指令、最近几轮对话、刚返回的工具结果、当前 diff 和错误日志。它天然每轮变化不应为了追求 cache hit 被强行塞入稳定区。后缀的目标是小、近、可丢弃真正需要跨轮保存的结论应先通过验证再晋升到半稳定工作状态。这种分层的价值不只在缓存。当 Agent 重复读取仓库时Harness 可以检查相同repo_snapshot下这个文件是否已经有内容哈希和可信摘要当工具升级时可以只使 Tool Registry 相关前缀失效当用户修改策略时可以强制重建第一层而不是继续复用一个高命中但过期的前缀。五、为什么 cache hit 不能证明上下文正确缓存命中只说明请求前缀与某个可复用计算相匹配。它不证明前缀中的内容仍然适用于当前任务也不证明上下文完整。第一种风险是过期策略。旧policy_hash对应的前缀可以获得很高命中率但如果安全团队已经禁止网络访问继续复用旧规则反而稳定地产生错误行为。第二种风险是工具版本漂移。工具名和大部分 Schema 未变缓存仍可能命中但后端语义、权限或副作用已经变化。账本必须把工具版本、端点和权限纳入 manifest而不能只哈希展示给模型的名称。第三种风险是错误摘要。一次 compact 把不允许修改 migrations漏掉后这份摘要可以在后续多轮被稳定复用。缓存越好错误传播得越便宜、越快。summary_hash只能证明摘要没变不能证明摘要正确还需要约束清单校验、来源回链和必要时的原文抽查。第四种风险是仓库已变化。模型对旧文件内容的前缀命中不代表当前 working tree 仍相同。只有repo_snapshot一致历史阅读结果才有资格复用。第五种风险是跨模型状态不兼容。不同模型或 effort 可能要求不同的 reasoning 字段、工具消息结构和压缩策略。Kimi 官方明确要求多轮 K3 请求回传完整 assistant message并记录模型或 effort 切换的缓存失效风险。S6、S8、S9因此恢复 Session 前必须执行兼容性检查而不是把上一模型的历史盲目塞给下一模型。生产看板至少要同时展示两组指标计算复用指标与语义正确指标。前者包括 hit tokens、miss tokens、hit ratio、TTFT 和输入成本后者包括策略版本一致率、仓库快照一致率、摘要约束召回率、工具 Schema 一致率和任务成功率。只有两组都通过缓存才是优化而不是把错误加速。六、怎样做一组不虚构结果的对照实验可以用同一批冻结仓库与验收测试对比三种上下文策略A 组全历史每轮携带完整消息B 组稳定前缀加增量组合稳定前缀、版本化工作状态和增量后缀C 组检索加短历史只保留稳定策略与短历史其余代码证据通过检索按需注入。任务集建议包含 24 个任务8 个单文件或小功能任务、8 个跨模块修改、8 个长链路任务。每组都要包含显式约束陷阱例如禁止改某目录、必须复用既有接口、只能调用只读工具。每个任务固定 commit、依赖、测试命令和验收脚本每种策略独立运行 5 次共 360 条任务轨迹。由于 K3 的采样参数并非都可自由设为零应通过重复、随机化运行顺序和相同时间窗降低偶然性而不是拿一次结果下结论。S6一次成功必须同时满足目标测试通过无禁止文件改动工具权限与副作用合规补丁能够从干净快照复现任务没有依赖人工补写被遗漏的原始约束。错误分类至少包括约束丢失、仓库状态过期、摘要遗漏、工具契约不匹配、上下文溢出或 compact 失败、重复读取或循环、功能失败。每条轨迹记录端到端耗时和 TTFT 的 P50/P95、输入与输出 token、cached_tokens、计算得到的 miss tokens、缓存命中率、总成本、每成功任务成本、重复文件读取字节数、工具调用次数、compact 次数和失败恢复次数。A/B/C 三组必须使用同一 Open Platform 模型 ID 与 effort不能把kimi-k3的美元成本和 Kimi Code 会员额度混在一张表里。另做一组 Kimi Code 故障注入在固定 Session 中分别执行 effort 切换、k3→k3-256k、k3-256k→k3、自动 compact 和手动 compact。记录客户端版本、切换方向、压缩前后约束召回和实际额度变化用来验证当前文档中的通用规则与限定例外。这里同样只报告实测不预填B 组一定最好之类结论。七、最后把选择写成工程规则优先使用 256K当经过检索后的有效工作集、短历史和预留输出空间稳定落在 256K 内任务是日常问答、补全、常规功能开发或少量文件修改时256K 应是默认档。Kimi Code 官方也把k3-256k定位在这些场景并提醒其不支持视频输入。S8升级到 1M当跨模块迁移、长测试证据、大量相互依赖文件或无法安全压缩的决策链确实超过 256K 时再升级到 1M。升级依据应是账本里的 working-set 估算和历史失败证据而不是窗口越大越聪明。接近 256K 且压缩可能丢失关键证据时Kimi Code 文档允许直接从k3-256k升到k3但仍要记录客户端版本并验证实际缓存结果。S8新建 Session模型 ID 或 effort 要改变、任务目标已经切换、策略版本改变、仓库基线大幅变化或者现有摘要无法通过约束校验时应新建 Session。Kimi Code 对模型与 effort 切换也明确建议/new以避免旧缓存失效后的额外消耗。S8、S9执行 compact同一任务、同一模型下早期历史大多已收敛且可被结构化状态替代时可以 compact从 1M 降到 256K 前若会话超限也应先显式 compact。压缩前必须生成保留清单压缩后运行约束、计划、未完成 todo 和关键证据的自动校验。没有校验的摘要不能成为新的事实源。重新构建上下文只要policy_hash、repo_snapshot、tool_schema_hash或summary_hash与预期不符检索索引落后工具语义升级跨模型历史结构不兼容或者 cache hit 很高但正确性 canary 失败就应放弃复用按权威来源重新构建三层上下文。最终Context Ledger 的目标不是追求最高缓存命中率也不是让每个 Session 尽可能长。它要让团队能回答一次任务为什么成功或失败哪段状态被压缩或过期哪次切换导致 re-prefill重复读取浪费了多少扩大窗口是否真正改善了每成功任务成本。1M Context 给了 Agent 更大的工作台但不会替你整理工作台。只有把模型、策略、仓库、工具、历史、摘要、缓存与结果统一记账长上下文才从一个容量卖点变成可以复现、比较和治理的生产能力。FAQContext Ledger 是另一份聊天记录吗不是。它记录请求依赖的状态版本、哈希、压缩边界、缓存与结果用于重放和归因。Cache Hit 为什么不能证明上下文正确它只证明前缀计算被复用无法证明摘要完整、仓库未漂移或任务授权仍有效。先上 1M 还是先做账本二者解决不同问题即使使用 1M也应先有最小账本否则错误与成本都难以解释。错误速查卡症状根因定位修复cache hit 80% 但答案明显违反原始约束摘要遗漏了不可违反的约束缓存越高效传播越快检查summary_hash对应摘要的约束清单是否完整定位 compact 前的源历史摘要生成后跑约束/计划/todo 校验未通过则不作为新的事实源账本记录validator失败原因切换k3→k3-256k后长前缀被重新 prefill账单突增客户端升级、模型 ID 或 effort 改变使 prompt cache 失效查账本model_id/reasoning_effort/client_version与cached_tokens跳变点跨档切换按官方建议先/new记录切换方向把 hit 骤降归因为代际切换而不是缓存策略错同一仓库不同 Session 下行为不一致repo_snapshot没绑定历史阅读结果模型读到的是过期文件账本repo_snapshot字段是否记录 commit dirty diff 依赖锁文件Harness 在 commit 变化或 dirty 文件变化时强制重建上下文不允许裸 path 引用调用工具时收到参数不匹配或权限拒绝Tool Schema 漂移旧上下文还在用旧参数 / 旧权限比对账本tool_schema_hash与 Tool Registry 当前 manifest工具版本/端点/权限变化时只重建第一层稳定前缀并把变化记入 manifest1M 上下文里模型显得很聪明但仍违反本地约束容量扩展 ≠ 状态管理约束在 compact 中被丢弃查账本 compact_event 链哪一次压缩、什么触发、保留清单、校验结果压缩前生成 preserve_manifest压缩后跑约束校验校验失败强制从原文重建每 Session 成本下降但每个成功任务成本没变失败成本被新 Session 隐藏没有以 task_id 归并账本是否在 task 层把同一 task 的多次 attempt 关联任务层强制task_idattempt_id按 task 归并而非按 Session 归并团队复盘时无法回答哪次切换导致 re-prefill账本只记 hit/miss没记代际 / 客户端 / 切换方向查账本是否记录client_version、model_id切换、effort 切换与方向增加context_identity hash(provider_surface model_id effort policy repo tool summary)identity 改变即重建账本摘要说已完成支付模块重构模型以为当前任务就是这个compact 时把当前目标误晋升为已完成事实查history_range与summary_hash定位摘要生成时刻的状态摘要里区分目标与完成事实前者必须经约束/测试/人工确认才晋升为完成事实检索到的代码片段命中但引用了已删除文件Repository Snapshot 落后于仓库repo_snapshot与 working tree 不一致检索前强制 rebase 到当前repo_snapshot检索索引落后时拒绝检索每次 commit、dirty 文件变化或依赖锁文件变化都刷新 snapshot旧摘要标注 stale禁止直接喂给模型Kimi Code 会员额度与 Open Platform 美元成本混算两个产品入口的 Key/余额/计费方式不通用查账本provider_surface是否正确区分Context Ledger 强制先记provider_surface再记model_id成本按 surface 分表计算8 个跨模块任务中频繁超时、TTFT 抖动大1M 上下文做 prefill 拖慢首 token任务实际不需要 1M查账本working-set估算有效工作集是否真的超过 256K优先用 256K 检索注入只有账本显示 working-set 超过 256K 才升 1M同一约束在 5 轮 compact 后被悄悄抹掉compact 是有损状态迁移但日志只记compactedtrue查compaction_event是否记录触发者 / 原因 / 源历史 / 保留清单 / 校验结果compact 必须像数据库迁移一样审计保留清单 校验 摘要哈希全部进账本Harness 在不同适配器之间把 K3 都记成同一个模型 ID 在不同产品入口命名不同kimi-k3/k3/k3-256k/kimi-k3[1m]查账本provider_surface与model_id是否成对保存账本字段必须成对恢复 Session 前做兼容性检查不盲塞上一模型历史一次任务失败后新建 Session 重试审计上看不到关联Session 与 Attempt 都被当成独立事件查账本是否以task_id归并 attempt任务层强制task_idattempt_id同一 task 的所有 attempt 共享 task 级成本与结果指标作者武子康的个人博客
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
