先给结论：这项研究讨论的不是“怎么把聊天记录拉得更长”，而是“怎么让 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 的状态文件，至少要包含以下几类信息：
- 技能标识与版本：当前在执行哪个 Skill，Skill 的版本是什么
- 目标与约束：用户这次任务的目标，以及已经确认不可变更的约束
- 文件与资源状态：读取或修改了哪些文件，文件的校验信息
- 步骤进度：任务拆成哪几步，每一步是 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(encoding="utf-8")) def save_state(state_path: str, state: dict) -> None: Path(state_path).parent.mkdir(parents=True, exist_ok=True) Path(state_path).write_text( json.dumps(state, ensure_ascii=False, indent=2), encoding="utf-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(f"step {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)，那第 n+1 轮请求的输入 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可以被程序直接 upsert，events.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 工作流中加入一个“状态目录”，就能明显改善长任务和中断续跑体验。
