概念与背景

Agent状态栏（Agent Status Bar）：框架向模型注入结构化元信息的通用通道，上一节Skills的元数据列表就是该机制的一个特例。

问题背景：纯靠模型原生能力执行复杂Agent任务，容易出现无限循环、遗忘约束、目标偏移。

• System Prompt：静态不变，相当于员工入职手册
• Agent状态栏：动态更新的仪表盘，持续输出任务进度、统计计数、环境信息

类比手机系统状态栏：不是业务主内容，但模型每一轮生成都可以直接读取，获取当前状态。

底层理论：上下文蒸馏 Context Distillation

模型上下文擅长检索原始信息，但不擅长自动归纳统计；所有计数、约束、进度，模型每次都要扫描全部历史重新计算，开销随上下文长度N增大，还容易出错。

状态栏本质：把分散在轨迹中的隐式状态，提炼为显式结构化知识，放在上下文末尾，抢占高注意力权重。

实验结论：

1. 弱模型：准确率提升 40~54个百分点；2B小模型可追平无状态栏的前沿大模型。
2. 强模型：思考token、延迟、开销下降约一个数量级。
3. 带上状态栏后，推理开销基本恒定，不再随上下文变长而上涨。

格式要求：使用键值结构化文本，不要大段散文；散文格式会让模型还要额外解析，效果大打折扣。

三条工程实践铁律

1. 状态统计优先用代码实现，不要交给LLM做批量总结
   正则/简单统计代码可以做到标准答案级别；交给大模型批量读取历史做统计，反而会出错，性能比不用状态栏还差。

   如果一定要用LLM，只能逐条抽取，代码做汇总，禁止一次性批量统计全部历史。

2. 状态栏属于有损投影，删除原始上下文前必须确认字段全覆盖
   只覆盖预想维度；遇到未覆盖的查询，准确率会断崖下跌。

   • 安全做法：新增业务维度就新增状态栏字段；不确定就保留原始上下文，不要删除。
   • 长文本多跳推理场景，状态栏提升有限。

3. 状态栏准确率作为生产指标监控
   模型几乎无条件采信状态栏输出，不会主动校验；状态栏写错，错误直接向下传递。

   信息尽量来自外部真实观测，避免可污染数据源，防止状态栏投毒。

深层原理：状态栏给模型输入模型自身无法推断的外部观测事实，把闭卷推理变成可查阅外部真实状态。

2.6.1 Agent状态栏包含的四类信息

1. 任务规划信息
   TODO任务清单，记录待办、进行中、已完成，防止Agent沉迷局部子任务，遗忘原始目标。
2. 事件侧信道信息 Side‑channel
   时间戳、时间间隔、地理位置等辅助元数据，不参与主业务逻辑，但帮助理解时序与环境背景。
3. 环境当前状态
   系统时间、工作目录、工具调用次数、异常告警；隐式状态转为显式可读。
4. 可用能力清单
   Skill元数据列表，复用上节的<system‑reminder>通道，仅安装卸载Skill时更新，KV Cache友好。

侧信道、能力清单基本不变；任务规划、环境状态高频动态变化。

2.6.2 API消息结构与插入位置

• 不修改system消息（修改system会破坏全部KV Cache前缀）
• 技术实现：以user角色消息追加到消息列表末尾，标签包裹<agent_status>

⚠️ 这里user只是API协议角色，并不是真实用户输入，是框架自动生成的元信息。

示例片段：

{
  "role":"user",
  "content":"<agent_status>\nphone_call invoked 3 times(Xfinity:3/3 max)\nCurrent time:2025‑09‑14 10:30:45\nTODO:[1] Cancel plan(in_progress)\n</agent_status>"
}

放在上下文最末尾，紧邻模型生成位置，获得最高注意力权重；只追加不修改历史，保护KV缓存。

2.6.3 状态更新两种实现 & KV Cache权衡

方案	实现逻辑	优点	缺点	适用场景
每轮替换	删除旧状态栏消息，末尾追加最新	上下文永远只有一份最新状态	删除会破坏其后缓存；长会话反复失效代价高	会话短、状态消息体积大
持久追加（Claude Code采用）	旧状态永久保留，每轮只追加新状态	完全不破坏KV Cache，缓存友好	旧状态堆积占用token；要求模型识别最新条目	长轨迹、高频更新状态

经验法则：长会话优先选持久追加；短会话选每轮替换换取上下文干净。

实验2‑8：五类实用状态栏技术

1. 时间戳跟踪
   给消息附加时间戳；支持时间模拟；便于理解时序、调试审计。
2. 工具调用计数器
   统计每个工具调用次数；触发模式识别，实现隐式成本感知，避免无限重试。
3. TODO列表管理
   外部记忆，标记pending/in_progress/completed/cancelled；实验：启用后平均迭代从21次下降到15次，减少子任务遗漏。
4. 详细错误信息
   输出错误类型、参数、调用栈、修复建议；错误场景解决成功率从60%提升至95%。
5. 系统状态感知
   注入时间、工作目录、操作系统、Shell/Python版本；对文件操作、跨平台命令至关重要。

组合使用会产生涌现效应，单一项效果有限，协同后Agent具备自适应排错行为。

2.6.4 Agent的物理时间感知（时间感三轴）

状态栏可以输出时间、调用次数读数，但仅有读数不足以改变模型行为，必须配套策略说明。

时间感三个度量轴：

1. 紧迫度 urgency（预算轴）：根据时间预算调整投入的工作量。
2. 坚持度 persistence（终点轴）：区分真实障碍和临时故障，控制重试/放弃策略。
3. 警觉度 vigilance（监控轴）：识别超时、异常响应，发起诊断。

关键结论：只输出elapsed_ms=5000这类原始读数，模型不会自动调整行为；读数 + 操作策略说明成对提供，才会生效。该缺陷是当前主流模型通用短板，可通过状态栏+提示词补偿，也可通过后训练蒸馏进模型权重。

2.6.5 整体设计哲学

1. 无侵入：不需要微调模型，纯提示层方案，可增量叠加各项能力。
2. 可观测：全部元信息可读，开发者可以直接查看Agent拿到什么状态。
3. 本质是交互缩放：框架作为外部仪器观测真实运行状态，把观测结果写回上下文，补充模型无法凭空推理的事实。