在智能体相关讨论里SKILL.state 被当作提升长程智能体任务准确率的一种关键设计被反复提及。所谓长程智能体任务指的是需要多轮模型推理、多次工具调用、中间结果互相依赖并且最终要形成可验收产物的复杂任务。真实业务里的竞品分析、数据看板生成、故障定位、工单自动处理都属于这一类。任务越往后执行准确率下降得越明显问题往往不是模型单一能力不够而是“技能是否可复用”和“状态是否可追踪”没有被纳入工程结构。SKILL.state 的价值在于把这两件事显式建模SKILL 是经过验证的可复用能力单元state 是每一步决策依赖的结构化事实快照。下面从失败机制讲起逐步拆解如何把这条研究思路落到一套可以本地运行、评测并复现的智能体骨架里。1. 长程智能体任务为什么会越到后面越容易出错1.1 先用一个 12 步任务理解“长程”的含义假设要让智能体完成一个数据分析任务用户给一句需求“分析上半年各渠道销售额差异定位下滑最严重的渠道并生成一份带图表的报告”。这个任务表面简单一旦拆开会形成接近 12 个可执行步骤解析用户需求中的分析范围、维度和产出格式列出可用数据库表或数据文件检查字段语义和数据范围编写查询 SQL 并执行校验查询结果是否与需求匹配处理空值、重复值和异常值按渠道分组并计算聚合指标计算环比或目标完成率识别下滑最严重的渠道选择适合的可视化图表生成图表和文字结论将整份材料与原始需求做一致性校验后输出。每个步骤内部可能还要触发多次模型调用或工具调用。也就是说用户看到的一次“自动分析”底层可能是 30 到 50 次模型推理。任何一个环节决策错误都会被后续步骤当作前提继续放大。长程任务和短问答最大的区别就在这里短问答只验证最后一句答案长程任务要求整条动作链上的每一步都可追溯、可校验、可回退。1.2 准确率流失往往来自四种机制很多团队在试点长程智能体时会发现前几步效果很好任务进行到中段以后模型开始做一些与目标无关的操作甚至反复执行已经完成过的动作。把失败案例拉出来看通常会落在下面几种机制上失败机制典型现场对最终准确率的影响单步误差逐级放大第 4 步查询写错了字段后面的统计全部基于错误数据错误沿着依赖链传播最后结果看似完整实则全错上下文超长导致约束失忆用户原始需求在第 9 步之后被模型遗忘报告遗漏关键维度最终产物与目标不一致验收失败状态漂移外部表结构或数据被其他系统修改模型仍按旧状态继续基于过期事实做决策步骤成功但业务意义错误动作缺少校验模型把“执行成功”误判为“结果正确”直接写入中间产物校验环节缺位错误结果被当作正确依据继续使用可以用一个简单模型理解误差累积假设每一步本身的正确率是 95%连续执行 12 步理想情况下最终完成概率只有 0.95 的 12 次方约等于 54%。现实里步骤之间还有状态依赖错误概率会比独立假设更高。所以长程任务提升准确率不能只依赖模型单步能力变强更重要的是减少决策次数、压缩无关信息、让错误能被及时发现。1.3 SKILL.state 的核心判断减少临时推理显式记录事实SKILL.state 这类设计的基本判断并不复杂让模型在每一步都从零开始推理“现在该怎么办”是在浪费模型能力。更好的做法是把经常出现的动作沉淀为技能 SKILL把任务当前处在什么阶段用结构化状态 state 记录下来。模型每次只需要做两件事根据当前 state 选择一个 SKILL以及把 SKILL 的执行结果更新成新的 state。这样做至少有三个直接收益。第一单步决策的上下文变短了模型只需要看当前状态和技能说明不需要把几万字的对话历史重新读一遍。第二技能可以被单独测试、单独复用同一个技能在不同任务里表现一致这比每次临时生成一段工具调用逻辑稳定得多。第三因为 state 是显式存在的失败时可以对比前后两个快照定位到具体是哪一步污染了后续过程排查成本会低很多。2. 把“技能”和“状态”分开建模设计上发生了什么变化2.1 SKILL可复用、可测试、可回退的动作单元很多资料会把 SKILL 和 Tool 混为一谈实际工程里应该把它们区分开。Tool 是原子的工具接口例如“执行一段 SQL”“读取一个文件”“调用一个搜索 API”。而 SKILL 是围绕某个业务目标组织的动作序列或操作封装它内部可以调用多个 Tool也包含前置条件、参数约束、结果校验和回滚逻辑。一个典型的 SKILL 注册项可以看作这样一段描述name: compute_channel_agg description: 对当前数据集按渠道分组计算销售额汇总和环比 applicable_when: - state.data.is_prepared true - state.task.analysis_dimension channel input_params: group_by: channel metric: total_sales output_keys: - state.data.channel_agg verify: - channel_agg.row_count 2 - channel_agg.columns contains [total_sales, mom_ratio] rollback: - delete state.data.channel_agg tags: - 数据分析 - 聚合这段配置里最关键的是applicable_when和verify。前者告诉调度器“什么状态下才允许调用这个技能”避免模型在数据还没有准备完成时就执行聚合后者是对技能产出的硬校验校验通过后才允许写回 state。一个技能如果没有明确前置条件和验证规则本质上仍然是临时代码不具备任何稳定性。把技能独立出来还有一个好处它和模型解耦。技能实现可以先写成普通 Python 函数用单元测试覆盖正确之后再交给智能体调度。这样整个智能体的可靠性不会完全押在模型随机生成的工具调用上。2.2 state机器可读的当前事实而不是对话历史state 在智能体里要回答三个问题任务目标是什么、已经完成了什么、当前可用的中间产物有哪些。它的设计原则和数据库里的“状态快照”很像要尽量结构化少用自然语言长段落。因为在长任务里模型最容易丢失的就是精确约束和可操作对象的引用。一份简化后的 state 快照可以是这样的 JSON{ task: { task_id: task_20250601_001, intent: 分析上半年各渠道销售差异并定位下滑渠道, constraints: { time_range: 2025-01-01~2025-06-30, output_format: report_with_chart } }, env: { database: sales_dw, dataset_path: /data/sales_2025.csv }, steps: [ {step: parse_intent, status: verified, output: intent_id_1}, {step: load_dataset, status: verified, output: dataset_id_1} ], data: { raw_data: {ref: dataset_id_1, rows: 52000}, channel_agg: null }, errors: [] }注意这里的 step 列表不是完整对话记录而是高度压缩的进度描述。每一步只记录状态、关键产物引用和时间。模型决策时读取这样的 state信息密度远高于读一段冗长的工具返回日志。这也是为什么把 state 单独拿出来建模非常重要它让智能体对“当前在哪一步”有精确定义而不是靠模型从上下文里猜测。2.3 两种模式对比长 Prompt 走到底与 SKILL.state用一个表格直观对比传统“把历史全部塞进 Prompt”的方式和技能加状态分开建模的方式对比维度长 Prompt 走到底SKILL.state 模式单次决策输入整段对话历史和工具日志结构化状态快照 技能说明上下文长度随步骤线性增长容易超限基本稳定状态只保留最新事实错误回退只能整段调整难以精准定位按步骤快照回退可恢复上一步技能复用每轮都要现场生成调用逻辑注册一次多任务复用可测试性只能做端到端测试失败难定位技能单独测试状态可单测可观测性长文本日志人工阅读成本高每步 state diff变更一目了然实现成本低前期建模成本高后期维护收益明显这个对比不是说长 Prompt 模式一无是处。短任务、低风险、只做一轮问答的场景直接让模型自由发挥可能效率更高。但任务一旦超过 8 到 10 个步骤或者中间产物需要被多个环节共享状态和技能拆分的收益就会显著放大。2.4 需要注意的边界并不是把任务拆成技能、再定义一堆 state 字段就能保证准确率提升。真正落地时有两个容易踩的边界问题。第一个是“过度结构化”有人把技能的每个分支都做成配置节点最后技能库比业务代码还难维护模型选择技能的开销甚至超过直接完成任务。第二个是“状态权威性不足”state 只是模型维护的内存字典如果外部系统已经从真实状态变化而智能体没有同步机制那 state 就会成为新的错误来源。优秀的设计应该把 state 当作缓存而非事实源头对关键事实尽量从真实系统查询验证。3. 最小可运行骨架SkillRegistry 加 SkillStateAgent3.1 应用场景与运行方式为了让前面的设计更容易理解这里用一个可以在本地开发环境复现的数据分析长任务为例。任务输入是一条自然语言需求例如“计算 2025 年各渠道销售额并找出环比下降最多的渠道”。底层接一个包含渠道、销售额、日期字段的 CSV 文件即可不需要数据库。整个骨架分为三部分Skill 定义每个技能是一个 Python 类或 dataclass包含 description、run、verify、rollbackSkillRegistry负责登记、检索技能SkillStateAgent负责维护 state、选择技能、执行技能、校验并更新状态。下面代码用于说明思路。实际项目要结合自己的包名、路径和模型接入方式调整。3.2 状态与技能的数据模型先把状态和技能的数据结构定义清楚。用 Python 的 dataclass 可以避免大量字典手写错误from dataclasses import dataclass, field from typing import Any, Callable, Optional from enum import Enum class StepStatus(str, Enum): PENDING pending RUNNING running SUCCEEDED succeeded FAILED failed VERIFIED verified ROLLED_BACK rolled_back dataclass class TaskMeta: task_id: str intent: str constraints: dict field(default_factorydict) dataclass class StepRecord: step_name: str skill_name: str status: StepStatus output_ref: Optional[str] None error: Optional[str] None dataclass class StateSnapshot: task: TaskMeta env: dict field(default_factorydict) data: dict field(default_factorydict) steps: list field(default_factorylist) errors: list field(default_factorylist) def push_step(self, record: StepRecord) - None: self.steps.append(record) def snapshot(self) - dict: return { task: self.task.task_id, intent: self.task.intent, env: self.env, data: self.data, steps: [s.__dict__ for s in self.steps], errors: self.errors[-10:], } dataclass class Skill: name: str description: str applicable_when: Callable[[StateSnapshot], bool] run: Callable[[StateSnapshot, dict], dict] verify: Callable[[StateSnapshot, dict], bool] rollback: Optional[Callable[[StateSnapshot], None]] None output_keys: list field(default_factorylist)这里把 verify 设计成独立函数而不是让 run 内部顺手做校验是为了强制区分“动作完成”和“结果正确”。很多长任务失败就是因为把“调用成功”当成了“步骤成功”。3.3 技能注册表与主循环技能注册表只需要做两件事登记技能、按名称获取。更复杂的场景可以给 Skill 增加 embedding 描述再用向量检索选出候选技能但对于最小骨架先用名称和人工编排即可class SkillRegistry: def __init__(self): self._skills {} def register(self, skill: Skill) - None: self._skills[skill.name] skill def get(self, name: str) - Optional[Skill]: return self._skills.get(name) def all_skills(self) - list: return list(self._skills.values())然后是智能体主循环。它维护一个状态快照对计划中的每一小步执行如下逻辑检查技能前置条件、执行技能、执行验证、更新状态。一旦验证失败可以选择重试或回滚class SkillStateAgent: def __init__(self, registry: SkillRegistry, max_retries: int 1): self.registry registry self.max_retries max_retries def is_applicable(self, skill: Skill, state: StateSnapshot) - bool: return skill.applicable_when(state) def execute_step( self, state: StateSnapshot, skill_name: str, plan_params: dict ) - StepRecord: skill self.registry.get(skill_name) if skill is None: return StepRecord(skill_name, skill_name, StepStatus.FAILED, errorfskill not found: {skill_name}) if not self.is_applicable(skill, state): return StepRecord(skill_name, skill_name, StepStatus.FAILED, errorfprecondition not met: {skill_name}) last_error None for attempt in range(self.max_retries 1): try: result skill.run(state, plan_params) except Exception as exc: last_error str(exc) continue if skill.verify(state, result): for key in skill.output_keys: state.data[key] result.get(key) return StepRecord(skill_name, skill_name, StepStatus.VERIFIED, output_refskill_name) last_error verify failed if skill.rollback is not None: skill.rollback(state) return StepRecord(skill_name, skill_name, StepStatus.FAILED, errorlast_error)主循环执行完成后状态快照里会留下每一步的 verified 或 failed 记录。后面做评测、排查、回放都依赖这些记录。这里要注意max_retries不要设置过大否则一次错误可能在错误状态下反复重试浪费模型调用次数也掩盖真实根因。3.4 关键参数与建议取值如果原始资料没有给出明确版本或参数落地前要结合自己的任务类型调整。下面这张表给出最小骨架里几个核心参数的说明和建议范围参数含义建议取值调大的影响调小的影响max_retries单个技能的最大重试次数1 到 2面对偶发超时更稳但失败成本上升快速失败利于尽早暴露问题checkpoint_interval状态快照保存步数粒度每步保存可回放粒度细存储开销增大排障信息不足verify 严格度对产出结果的校验门槛核心字段非空、行数变化、字段引用有效更安全但误杀率升高容易放过错误中间结果skill description 长度检索技能时的说明文本50 到 200 字信息完整但模型选择变慢信息不足导致误选在开发阶段参数应该偏保守尽量每步保存快照让重试次数少一些。进入生产后再根据日志统计调整重试阈值和校验规则。4. 让“准确率提升”变成可测量的实验4.1 长程任务评测集的设计要点要验证 SKILL.state 是否真的提升了准确率不能只靠一两个演示任务。需要一组能覆盖任务复杂度、状态依赖和外部变化的长程任务评测集。构造评测集时至少要考虑五个方面任务要有明确终点最好定义一个可检查的“期望最终状态”而不只是一段输出文本。中间步骤之间要有依赖关系比如下一步必须使用上一步生成的中间文件。要包含容易出错的陷阱例如字段名相似的表、空值比例高的列、需要先清洗才能聚合的数据。要有不同任务长度分布从 5 步到 20 步以上都有覆盖。每条任务要有独立的人工校验步骤不能假设模型输出就是标准答案。评测集的一条记录可以简化成下面这样的结构task_id用户需求初始数据期望最终状态允许最大步骤关键校验点task_001统计 2025 年各渠道销售额sales_2025.csv产出 channel_agg 表和下滑渠道结论12聚合前数据已清洗task_002对比 A/B 两个推广活动的转化率campaign_log.csv产出对比表包含显著性说明15分母口径一致4.2 指标定义不要只盯着“最终有没有成功”最终成功率当然是最重要的指标但只有这一个指标失败时很难定位问题。建议同时统计以下指标最终任务成功率达到期望最终状态的任务比例。步骤完成率成功执行并验证通过的步骤占总计划步骤的比例。中间产物有效率写回 state 的中间结果中通过独立抽查的比例。平均模型调用次数衡量单任务成本避免为了提升准确率无限重试。回退恢复率发生错误后通过回滚和重试恢复并完成任务的比例。统计时可以把任务按长度分成短程、中程、长程三组。如果 SKILL.state 的改进主要发生在长程组而短程组差异不大说明它的价值确实在长任务上体现。4.3 状态回放与失败归因SKILL.state 模式下一个很有用的调试手段是“状态回放”。每一步执行后都导出快照当最终任务失败时可以从终点往前回放找出第一次出现 failed 或第一次出现异常中间结果的步骤。回放数据需要至少记录如下字段{ task_id: task_001, step_index: 4, skill_name: execute_sql, action: run, before_state: { data: {raw_data: {is_clean: false}} }, plan_params: { table: sales_2025, where: amount 0 }, result_summary: {row_count: 51200, columns: [channel, amount]}, after_state: { data: {raw_data: {is_clean: true, rows: 51200}} }, verify_ok: true }失败归因时优先看两个位置第一次出现verify_ok: false的位置以及第一次与前一步预期结果不一致的位置。如果状态回放里每一步都看起来正常但最终结果错误多半是评测目标里的期望状态定义不完整需要回头补校验点。4.4 做对比实验时需要控制哪些变量推荐至少跑四个版本Baseline单长 Prompt 走到底不做技能拆分。State Only只加状态追踪不引入技能库。Skill Only只做技能复用不做状态回放。SKILL.state两者都启用。对比时注意控制变量同一个模型版本、同一组评测任务、同一套工具环境、同样的随机种子。模型推理有随机性每个版本建议至少跑 3 到 5 次记录均值和方法而不是只看单次结果。还要避免评测集顺序对结果产生干扰每次运行前打乱顺序并记录。5. 常见问题排查从现象倒推智能体失效原因5.1 高频故障对照表实践过程中以下故障最常出现。排查时先看现象再对照可能原因避免一上来就调整 Prompt。问题现象常见原因检查方式处理建议模型反复执行同一个步骤但进度不推进技能前置条件一直不满足或 verify 永远失败查看状态快照中该步骤的 attempt 和 error 字段检查前置条件引用字段是否存在修正 verify 规则模型选择了明显不相关的技能技能 description 语义不清或技能注册数量过多输出每次技能选择的 top 候选与匹配分数精简技能库增加 description 关键词和否定条件状态里显示成功但外部系统没有真实变化工具调用成功后未提交事务或外部系统为异步处理对比外部数据库日志与状态快照时间戳将“提交确认”纳入 verify 规则必要时候轮询状态报告内容与用户原始需求不一致任务约束没有写入核心 state只在第一轮 Prompt 中检查最终状态中的 constraints 字段是否被保留将目标约束写入 state.task每步决策前重新注入verify 一直失败但人工看结果是对的验证器写得过严例如要求固定列顺序独立用正确输出跑验证函数放宽列顺序检查改为集合包含关系任务中途 token 超限state 里塞入了长文本而不是引用检查快照中是否有大段文本对象data 字段只保存文件路径、表名或摘要不保存完整内容5.2 推荐排查顺序当一个问题同时有多种可能时按下面顺序排查效率更高先看输入状态是否正确state 中是否存在关键字段为空或引用失效。再看技能名称和注册表是否一致模型是否调用了不存在的技能。然后看前置条件是否满足是否因为某个字段命名差异导致条件永假。接着看执行结果本身的错误日志区分是模型错误还是工具错误。然后看 verify 逻辑确认失败是因为结果真的错误还是检查代码写错。最后才考虑是调整模型 Prompt 还是重写技能实现。这条顺序能避免最常见的浪费模型输出明明正确但因为技能注册表没更新或 verify 写错字段名导致任务不断重试。5.3 一条硬规矩不要让 verify 变成摆设实际项目里最容易出现的情况是前期为了快速跑通把 verify 函数写成return True。这样的系统表面上很流畅所有步骤都“通过”但没有任何质量保障。verify 至少应该包含三项检查结果非空、关键字段存在、结果与输入状态可关联。对于数据类任务建议再加入行数变化、值与上游数据总量一致性等业务规则。技能只有经过验证才能写回 state这条规矩应作为代码评审和日志监控的强制项。6. 工程落地的最佳实践与扩展方向6.1 把技能库当代码库管理技能库不应该是一堆散落在项目里的 Python 函数。每个技能都应具备注册名、业务描述、输入输出字段、前置条件、验证规则、回滚逻辑、版本号。当技能行为变化时要更新版本并保留历史记录因为任务状态回放时可能涉及旧版本技能。技能上线前至少要有独立的单元测试覆盖“正常输入、边界输入、错误输入”三类场景。技能库可以放到独立目录或独立 Python 包中与智能体主流程解耦。6.2 明确 state 的权威源与同步机制state 本质上是智能体对现实的建模不是现实本身。生产环境中外部数据库、文件系统、审批流都可能被其他系统修改。设计时应区分两类状态一类是智能体自身产生的中间产物这类以本系统记录为准另一类是外部真实状态这类应该在关键动作前主动查询确认。不能长期依赖缓存中的旧状态做决策尤其是涉及金额、权限、订单状态的任务。可以设计一个轻量同步层在执行需要外部状态的技能前强制刷新一次。6.3 学习环境与生产环境的差异如果只是学习 SKILL.state 的概念本地用一个 CSV 文件和一个 SkillStateAgent 类就能跑通。但进入生产环境还需要额外考虑以下几点关注点学习环境生产环境状态存储内存 dict持久化数据库支持任务恢复日志print结构化日志关联 task_id技能版本手工修改版本化发布保留兼容记录校验手工确认自动 verify 人工抽检异常恢复直接重跑支持断点续跑、回滚预案成本控制不关注限制模型调用次数、设置预算告警权限安全忽略技能仅具备最小权限工具调用留审计生产环境的每项能力都对应一种真实事故没有持久化进程重启任务就丢没有审计日志出错后无法追溯技能权限过大一次误调用可能污染整张表。所以问题不该是“学习环境能不能加生产能力”而是“从第几个任务开始必须加”。6.4 后续可以扩展的方向这套骨架继续完善可以朝四个方向展开。第一个方向是技能检索智能化技能数量达到几百个以后用向量检索替代关键词匹配通过技能的历史成功率调整排序权重。第二个方向是多智能体协同不同智能体分别维护自己的技能和状态通过共享状态总线交互此时 SKILL.state 可以作为单个节点内部的稳定模式。第三个方向是状态压缩与摘要当环境信息过大时用模型对原始数据生成结构化摘要再存回 state避免超长字段。第四个方向是评测自动化把上面的状态回放、指标统计和差异分析封装成回归测试套件每次模型升级或技能变更后自动执行。对新手来说最有价值的练习是拿一套真实的 15 步业务任务跑一遍 Baseline 和 SKILL.state 两个版本记录失败步骤和最终成功率。只有当自己看到“错误在某个状态节点上被拦截”而不是一路传播到最终产物才能理解这套设计真正的意义。长程智能体任务的工程难点从来不在某个模型调用上而在于如何让每一步都有依据、有校验、有回退路径。SKILL.state 提供的正是这样一条路径。