先给结论这项研究讨论的不是“怎么把聊天记录拉得更长”而是“怎么让 AI 不再依赖聊天记录”。SKILL.state 把智能体执行任务时的关键信息抽出来保存成显式状态。每次要继续干活先读状态而不是把几十轮人机对话重新塞进上下文。这样既省 token也降低了长任务中断后无法恢复的风险。如果你平时用 Claude Code 这类 AI 编程助手或者自建 Agent 工具链应该会对下面这个问题有共鸣任务做久了对话历史越来越长AI 开始抓不住重点中途换新会话又要把之前的结论重新描述一遍。很多人搜索“Claude Code 怎么保存对话历史”本质上就是想解决“断了之后怎么续上”的问题。但从 SKILL.state 的思路看保存对话历史只是保存“过程录像”更可靠的方案是保存“任务存档”。这篇文章会拆解这个研究想解决的问题、显式状态与纯对话历史的差异再用一个可落地的“状态文件 技能策略”示例演示如何在 Claude Code 这类编码 Agent 场景中应用这个思路包括断点续跑、API 调用和批量任务设计。没有 GPU 门槛也不绑定特定硬件重点在于改变 Agent 的上下文组织方式。1. SKILL.state 核心思路速览在展开之前先把这项研究的核心信息整理成一张速览表方便快速判断它跟你当前的工作是否相关。能力项说明研究方向面向 AI Agent / 技能系统的状态管理与上下文组织核心观点用显式状态替代隐式对话历史作为任务恢复和决策的主要依据解决的核心问题长会话上下文膨胀、历史噪声干扰、中断后难以准确续跑关键载体Skill 定义、State Schema、状态读写策略、基于状态的下一步动作选择典型应用场景AI 编程助手、多步任务 Agent、自动化脚本、批量任务队列主要收益降低请求 token 量、提升长任务稳定性、支持从断点继续执行是否依赖 GPU不依赖纯思路/框架设计运行效果与所用模型有关与 Claude Code 的关系可作为编码 Agent 保存任务进度、恢复上下文的一种状态管理方案验证方式用一个多步骤任务分别在纯历史和显式状态两种模式下跑对比 token 消耗与续跑准确率从材料能看到的是它的核心不是某个具体模型而是一套“Agent 状态应该怎么组织”的方法。换句话说同一个大模型用显式状态管理之后长任务表现可能比一味追加历史更好。2. 为什么对话历史不等于任务状态对话历史和任务状态是两个层面的东西。对话历史记录的是“人和 AI 说了什么”包括用户需求、AI 回复、工具调用、报错信息、日志输出等。任务状态则需要表达“这个任务到底进行到哪一步了、已经决定了什么、下一步要做什么”。举一个常见编程场景。假设你让 Claude Code 把一个旧模块拆成独立服务前 20 轮对话可能包含用户提出的原始需求AI 对代码结构的初步分析第一次修改后的代码片段测试运行输出报错堆栈AI 根据报错再次修改的过程到第 30 轮时完整上下文可能已经包含了几万甚至十几万 token。但真正决定“下一步怎么走”的信息可能只有几条已经确认要保留原有函数签名修改了哪个文件当前测试是失败状态失败原因是配置路径错误把这两类信息混在一起AI 每次都要从大量历史内容里重新定位关键信息。上下文越长注意力越分散也越容易出现“和前面结论不一致”的情况。SKILL.state 的思路很简单把这些关键决策和执行状态单独抽出来用结构化的字段保存。AI 每次读取状态就能知道当前进度不需要把整段历史重新翻一遍。对话历史可以继续保留但它的角色从“唯一记忆”降级为“可审计日志”。2.1 日志与存档的区别可以这样理解对话历史是录像显式状态是存档。录像记录了每一秒发生了什么但你要知道游戏打到第几关、血量是多少、背包里有什么直接看存档最快。断线重连时游戏读的是存档不是把整个操作过程回放一遍。放到 Agent 场景里这个类比尤其准确。编码 Agent 的任务环境本身是真实存在的文件系统和命令行。任务进度并不只存在于对话里文件改了没有、测试过了没有、端口通不通都是客观状态。把这些状态落地为结构化数据远比让 AI 从聊天记录里“推断”状态可靠。3. 显式状态应该如何设计如果要落地 SKILL.state 的思路第一步不是写代码而是设计状态结构。一个适合编码 Agent 的状态文件至少要包含以下几类信息技能标识与版本当前在执行哪个 SkillSkill 的版本是什么目标与约束用户这次任务的目标以及已经确认不可变更的约束文件与资源状态读取或修改了哪些文件文件的校验信息步骤进度任务拆成哪几步每一步是 pending / running / done / failed关键决策记录AI 在哪个环节做了哪个决策依据是什么最近一次错误当前挂在哪一步报错摘要是什么下一步动作根据当前状态紧接着应该执行什么下面给出一个状态文件示例。注意这不是某个公开项目的固定格式而是一个通用模板你可以按自己的 Agent 工具调整字段。{ skill: refactor_module, skill_version: 1.0.0, goal: 将 legacy_auth.py 中的登录逻辑拆成独立 auth 模块, constraints: [ 保持 login() 函数签名不变, 不引入新的第三方依赖 ], resources: [ { kind: file, path: src/legacy_auth.py, checksum: sha256:abc123, status: read }, { kind: file, path: src/auth/__init__.py, checksum: sha256:def456, status: created } ], steps: [ { step_id: 1, name: 读取遗留代码, status: done }, { step_id: 2, name: 确认外部调用接口, status: done, decision: 保留 login() 函数签名 }, { step_id: 3, name: 拆分 auth 模块, status: running }, { step_id: 4, name: 补充单元测试, status: pending }, { step_id: 5, name: 运行完整测试, status: pending } ], current_focus: 拆分 auth 模块, last_error: { step_id: 3, message: 导入循环依赖auth.handler 引用了 legacy_auth, suggested_next_action: 检查 handler 的导入边界 }, updated_at: 2025-01-01T10:30:00Z }这个状态文件非常小通常不超过 1KB 到 2KB。相比之下同样任务的完整对话历史可能已经达到几十 KB。更重要的是状态文件可以被程序直接读取和校验不依赖模型的“阅读理解能力”。3.1 状态更新时机设计好 Schema 之后还需要确定什么时候更新状态。比较稳妥的策略是在每个关键动作完成后更新一次而不是每生成一条文本就更新一次。关键动作包括读取文件结束、修改文件结束、执行命令结束、确认一个约束、发现一个错误。更新频率太低状态会滞后更新频率太高每个 token 都去保存状态反而增加负担。在编码 Agent 场景里推荐的做法是把工具调用结果作为状态更新触发点。每次工具执行完成Agent 把返回结果中与任务进度相关的部分提取出来合并到状态文件。3.2 从状态生成回复而不是从历史生成回复显式状态能替代对话历史的另一个关键点是每次启动新会话时可以用状态文件生成任务的“精炼摘要”而不是直接拼接旧对话。例如你可以写一个简单函数把步骤列表拼成提示词。这样新对话的第一条消息只包含当前状态不包含旧对话上下文长度大幅缩短。4. 纯对话历史 与 显式状态 对比为了更直观地说明问题下面把两种方式放在同一张表里对比。对比维度纯对话历史显式状态SKILL.state 思路信息组织按时间顺序线性排列按任务要素分类存储关键进度定位需要模型从长文本中自行提取程序直接读取结构化字段上下文长度随轮次增长通常只增不减固定为状态文件大小可裁剪中断恢复依赖完整历史回放读取存档即可继续可调试性难定位是哪一轮决策出了问题可直接检查 decision 字段批量任务支持每个任务都需要独立长历史每个任务只需要独立状态文件并发执行历史互相交织易串扰状态按任务隔离互不干扰审计能力有完整过程但检索困难需要额外保留日志或事件流表格只是抽象对比本质是一种技术选型视角。不是说显式状态一定要完全抛弃历史而是说“历史不作为决策主依据”。真正科学的设计通常是两种都要显式状态负责决策历史日志负责审计。5. 如何应用到 Claude Code 类编码 Agent很多人搜索“Claude Code 怎么保存对话历史”核心痛点其实是会话关了以后下一个会话怎么接着干。直接用对话历史续跑会遇到两个问题一是历史太长续跑成本高二是历史里包含大量探索过程这些过程不一定都是有效进度。SKILL.state 的落地方式是把“当前任务状态”保存成项目内的一个文件在每次新会话开始时加载。5.1 项目内保存状态文件最直接的落地方式是在当前项目目录下建立一个隐藏目录保存所有任务状态。例如.myagent/ tasks/ task_001/ state.json events.logstate.json存放任务当前状态events.log存放每次操作的事件。每次调用 Agent 前先读取对应的state.json再根据状态决定需要执行的动作。这种方式的优点是很轻量不需要额外数据库也不需要改造模型。只要 Agent 能够读文件、写文件就可以实现。5.2 一个简单的状态管理脚本为了说明实现原理下面给出一段 Python 脚本。它并不依赖某个特定 Agent而是一个通用的状态读写模板。import json from pathlib import Path def load_state(state_path: str) - dict: p Path(state_path) if not p.exists(): return {steps: [], issues: [], current_focus: } return json.loads(p.read_text(encodingutf-8)) def save_state(state_path: str, state: dict) - None: Path(state_path).parent.mkdir(parentsTrue, exist_okTrue) Path(state_path).write_text( json.dumps(state, ensure_asciiFalse, indent2), encodingutf-8 ) def mark_step_done(state: dict, step_id: int) - None: for step in state[steps]: if step[step_id] step_id: step[status] done return raise ValueError(fstep {step_id} not found) def compose_prompt_from_state(state_path: str) - str: state load_state(state_path) lines [ f步骤 {s[step_id]}{s[name]}状态 {s[status]} for s in state[steps] ] prompt f继续执行技能 {state.get(skill, )}。 目标{state.get(goal, )} 当前焦点{state.get(current_focus, )} 已完成步骤 {chr(10).join(lines)} 请优先查看 {state_path} 中的显式状态不要依赖旧对话。 return prompt这段代码展示了最核心的逻辑状态从文件读步骤状态被更新提示词从状态生成。实际接入 Claude Code 时你可以把compose_prompt_from_state的输出作为新会话的初始指令。5.3 恢复执行的动作在一个新会话里AI 读到了状态文件知道当前步骤是“拆分 auth 模块”并且知道上一步报错是“导入循环依赖”。接下来它要做的不是重新分析整个项目而是只围绕这个报错继续修复。这种方式的优势在于即使中间换了一次会话只要 state.json 没有丢AI 就能继续干活。而且因为上下文里不再有前面大量询问和试错内容模型需要处理的信息更集中结果也更容易保持稳定。6. API 调用与批量任务中的显式状态SKILL.state 的思路不仅适用于交互式会话在 API 调用和批量任务里更有价值。批量任务常见问题是几十个任务同时在跑某个任务失败后如何恢复如果只保存对话历史恢复时无法判断这个任务之前执行到哪。如果保存显式状态任务恢复就是一次“读状态 继续执行”的操作。6.1 任务级 API 设计假设你自己搭了一个 Agent 执行服务接口可以设计成这样{ task_id: task_001, skill: refactor_module, goal: 将 legacy_auth.py 中的登录逻辑拆成独立 auth 模块, state_file: ./tasks/task_001/state.json, max_steps: 20 }当任务开始时服务创建 state.json。每执行一步服务更新 state.json。如果任务失败接口返回错误并把错误写入last_error字段。后续重试时只需要向同一个任务提交“继续执行”的命令Agent 会读取 state.json而不是从头开始。用 curl 模拟一个继续执行请求curl -X POST http://127.0.0.1:8080/tasks/task_001/resume \ -H Content-Type: application/json \ -d { reason: 上次因网络超时中断任务状态已保存在 state.json }这里给出的接口路径只是一个通用示例具体路径和参数需要按你自己的服务调整。重点是设计思路任务恢复必须基于 state_key不能基于对话轮次。6.2 批量任务的队列设计批量任务里每个任务都维护独立的状态文件。一个典型任务队列结构如下{ task_id: task_042, skill: code_review, status: running, attempts: 2, max_attempts: 3, state_file: ./tasks/task_042/state.json, input: { target_dir: ./src/auth, focus: security } }批量执行器只做三件事扫描任务队列找出 status 为 pending 或 failed 的任务读取任务关联的 state.json调用模型继续执行执行完更新 state.json 和任务状态如果任务失败不需要重新放回队列头部只需要原地重试。因为有了显式状态重试成本大幅降低。6.3 幂等性与重复执行防护批量任务还有一个风险模型可能执行了某个操作但状态没来得及保存导致重启后重复执行。解决方法是引入“事件日志 状态快照”双写机制。每次工具执行前先记录一条intent事件执行后再记录result事件。state.json 记录的是这些事件处理后的聚合结果。这样即使 state.json 写失败也可以从事件日志重建。7. 上下文占用与执行耗时观察SKILL.state 对性能的影响在纯对话历史和显式状态两种模式下最明显。虽然没有具体的基准测试数据但可以从原理上判断几类指标。7.1 token 消耗对话历史模式下每次新请求都要把之前的全部消息发送一次。假设第 n 轮之后历史长度为 H(n)那第 n1 轮请求的输入 token 至少是 H(n)。显式状态模式下如果旧历史被丢弃输入 token 只包含 state.json 生成的精简指令长度记为 S。S 通常远小于 H(n)且不会随轮次无限增长。需要说明的是显式状态不是自动省 token。如果你仍然把全部对话历史放在上下文里又额外加了一份状态文件那 token 反而更多。正确做法是在合适的节点开启新会话让旧历史留在日志里新会话只加载状态。7.2 首 token 延迟与本地显存观察对于云端大模型 API输入 token 减少会降低 prefill 时间从而影响首 token 延迟。对于本地部署的开源模型上下文越长KV Cache 越大显存占用越高。用nvidia-smi可以观察到同一个模型在固定 batch size 下输入越长显存占用通常越高。所以显式状态方案对本地模型的友好之处在于它不是通过减少模型参数量来省显存而是通过减少每次请求的上下文长度来降低 KV Cache 占用。实际能降多少需要根据状态文件精简程度和模型上下文窗口测试。7.3 可观察指标建议如果你想在项目里验证效果建议记录以下指标每轮请求的输入 token 和输出 token单任务总 token 消耗平均每轮请求耗时任务完成率中断后恢复的成功率通过对比“纯历史模式”和“显式状态模式”的同一批任务可以得出比较可靠的结论。注意要保证任务类型、难度、模型版本一致否则对比没有意义。8. 常见问题与排查方法把对话历史切换成显式状态会遇到一些新的问题。下面是几个高频场景和排查建议。问题现象可能原因排查方向处理建议新会话读了 state.json 仍然不知道干什么状态文件里缺少当前焦点或步骤描述模糊检查current_focus和last_error字段在状态里补充“下一步建议”字段状态进度和实际文件不一致文件系统被外部修改或状态更新遗漏对比文件校验信息和执行日志增加文件 checksum 记录token 没有下降反而增加历史没有清理状态文件又额外加入上下文查看实际消息体长度在新会话中不要携带旧历史只加载状态任务恢复后重复执行某一步状态写入晚于工具执行完成检查事件日志和状态快照时间线执行前先记录 intent执行后再记录 result批量任务中某个任务卡死缺少超时控制模型持续调用工具查看任务状态更新时间为每一步增加超时阈值和失败重试状态文件被并发写坏多个进程同时修改同一个 state.json检查写入时是否有文件锁每个任务使用独立状态文件减少并发冲突state.json 里的信息让模型忽略提示词里没有强调“以状态为准”检查系统提示语在系统提示中说明优先读取 state.json隐私数据被写入状态文件设计时没有过滤敏感信息检查状态写入逻辑敏感信息用环境变量或密钥服务保存其中最容易被忽略的是“状态更新时机”。很多开发者实现了显式状态却仍然在工具执行前不记录、执行后延迟记录结果一旦中断状态就丢失。建议把状态更新看作与文件保存同等重要的操作宁可多写几次也不能漏写。9. 最佳实践与使用边界SKILL.state 是一个很实用的研究方向但应用时要注意边界。下面是工程上比较稳妥的做法。9.1 最小状态原则状态文件不应该承载所有信息只保存“任务推进所需的最小集合”。大段代码、完整日志、原图等都不应该直接放进状态文件而应该保存路径或引用。原因很现实状态文件越小更新越频繁时开销越低模型读取时干扰也越少。如果一个状态文件膨胀到几十 KB它就跟对话历史没太大区别了。9.2 状态与日志分离状态文件负责决策日志文件负责审计。如果项目需要追溯 AI 为什么做了某个决策可以查事件日志但如果只是恢复任务就只读状态文件。我建议这样安排目录.myagent/ tasks/ task_001/ state.json events.log artifacts/state.json可以被程序直接 upsertevents.log只追加不修改。这样即使 state.json 写坏了也可以通过事件日志回溯重建。9.3 版本化与迁移Skill 会更新状态 Schema 也会变。建议在 state.json 里保留version字段。后续读状态时先检查版本再决定要不要迁移。例如早期版本可能没有constraints字段新版本增加后旧状态文件需要补一个空数组。迁移逻辑应该在加载状态时自动完成而不是让模型去猜。9.4 合规与隐私边界这个方向最终要落到真实项目和代码数据上使用时有几条底线不要让 Agent 读取你没有权限访问的目录和文件不要把数据库密码、API Key、内网地址写进状态文件如果使用云端大模型 API提交前需要确认代码内容是否允许出网涉及用户隐私数据或人脸、声音、版权素材时必须有明确授权批量任务跑完以后对输出结果要做人工复核不能完全自动化发布显式状态只是工程手段不能替代合规审查。尤其是把本地代码库内容作为上下文发送到云端时要严格遵守企业内部数据安全规范。10. 总结与下一步SKILL.state 值得关注的点不是它发明了某种新模型而是它提供了一个新的思考角度Agent 的记忆不能只靠“把所有说过的话都留着”而应该像软件设计一样把状态显式建模。这个思路在 Claude Code 场景里尤其实用因为它直接回答了“Claude Code 怎么保存对话历史”的升级版问题不只要保存过程还要保存进度。建议你先从一个两周内会重复执行三次以上的技能任务开始验证。给这个任务定义一个最小状态文件把步骤拆清楚在每次模型执行关键动作后更新状态。然后尝试在任务中途关闭会话重新开一个新会话只把状态文件给模型看看它能不能准确续跑。最需要留意的坑是状态与真实执行环境之间的不一致Agent 在执行文件修改、命令或接口调用时如果状态写得太慢或者漏写恢复时就会出现重复执行或遗漏。第一次落地时不要追求完整复杂的 Schema用一个只有 goal、steps、current_status 三个字段的小文件跑通流程再逐步增加约束、决策记录和错误信息。后续扩展方向一是把这个状态文件和你的持续集成流程打通让 Agent 能够处理跨会话的长期任务二是把多个技能的状态聚合起来实现更复杂的多阶段自动化流水线三是给状态文件加入权限控制让一批任务共享只读上下文同时保留各自独立的可写状态。对多数开发者而言这个方向不需要立刻替换现有工具只需要在你当前使用的编码 Agent 工作流中加入一个“状态目录”就能明显改善长任务和中断续跑体验。