context-status-bar

name	context-status-bar
description	当 Agent 陷入循环、状态遗忘、目标偏离，或在长上下文下决策质量下降时使用；当需要让模型随时感知任务进度、工具调用计数、环境状态时使用。核心目标：把分散在上下文各处的隐式状态提炼为可直接使用的显式知识。不适用于静态提示词设计（见 prompt-engineering）或缓存布局（见 context-kv-cache-friendly）。

Agent 状态栏（Agent Status Bar）

角色与读者

面向构建生产级 Agent 的开发者。本 Skill 服务的目标：通过在上文末尾注入结构化元信息，为 Agent 补上自我感知和自我调节机制。类比手机屏幕顶部的状态栏（时间/电量/信号）——不是主界面内容，但随时可瞥一眼掌握状态。

理论基础（为什么有效）

• 上下文学习更像检索而非推理：模型擅长从已有内容"查找"，不擅长主动"归纳统计"。"上下文窗口是一台只有一半的检索引擎"——检索的一半很强，但缺"提炼层"。
• 例子：系统提示词要求每商家拨打不超 3 次，但打了 3 次后模型数不清又打第 4 次——"打了几次"的知识没被提炼，以原始记录分散在 KV Cache 向量中。
• 效果：提供状态栏后，小模型准确率接近前沿大模型；每次迭代思考 token 量/延迟/花费降低约一个数量级；带状态栏后思考量基本恒定（不带则随上下文变长持续增长）。
• 注意力衰减/位置偏好：长上下文下早期目标与关键约束被后续大量工具结果淹没；状态栏放末尾（紧邻生成位置）获得最高注意力权重，是"强制性注意力引导"。

核心原则（配正例/反例）

1. 状态栏内容：任务规划（TODO）+ 事件侧信道信息 + 环境状态摘要

   • TODO 列表（外部记忆）：每项含唯一 ID、内容、状态（pending/in_progress/completed/cancelled）、时间戳。启用 TODO 的 Agent 平均 15 次迭代完成任务，禁用需 21 次且常遗漏子任务。
   • 侧信道信息：为每个事件附加精确时间、地理位置、距上次回复间隔（帮模型理解时序）。
   • 环境状态：当前时间、工作目录、OS 类型、Shell、Python 版本；异常操作提醒（"该工具已重复调用 N 次"）。

2. 位置：作为 user 角色消息追加到上下文末尾

   • 不是修改 system 消息（否则破坏整个前缀缓存）。用 <agent_status> 标签包裹以便模型识别特殊性质。
   • 澄清：这里的 user 角色只是 API 协议技术选择（借用消息槽位注入框架生成的系统状态），不等同于"来自终端用户的输入"。

3. 状态栏必须用代码维护，不要让 LLM 批量统计

   • 模型几乎无条件相信状态栏——你写"打了 3 次电话"它就当真 3 次，不会自己重算；LLM 做数量统计本来就易错。
   • 实在要用 LLM，也要逐条抽取、再由代码汇总。

4. 五种好用的状态栏技术（可组合，涌现效应）

   • 时间戳跟踪（[2025-09-14 10:30:45] 前缀加到 user 消息和工具响应，不是 system）；工具调用计数器（"Tool call #3 for read_file"，触发模式识别）；TODO 列表管理（rewrite_todo_list / update_todo_status 工具）；详细错误信息（四层：错误类型描述 + 完整参数 JSON + 调用栈 + 修复建议，成功率从 60% 提到 95%）；系统状态感知（当前时间/工作目录/OS）。

5. 谨慎删除原始上下文（状态栏是有损投影）

   • 状态栏只提前算了"你预想会被问到"的维度。够用可删原始记录省 token，但只要一个问题涉及未计算维度，仅保留状态栏会导致准确率断崖式下降。

执行流程（SOP 检查清单）

1. 确定要提炼的状态维度：任务进度（TODO）、工具计数、环境状态、详细错误。
2. 用代码确定性维护（计数器用全局字典，TODO 用专门工具，环境状态实时读取）。
3. 每次 API 调用前，把状态栏作为 user 消息追加到轨迹末尾（<agent_status> 包裹）。
4. 选择更新方式：状态小/更新间消息多 → 持久追加（缓存友好）；状态大/更新频繁 → 每轮替换（只使上次注入后短后缀失效）。
5. 定期检查：状态栏是否被代码正确维护（而非 LLM 统计）、是否误删了未覆盖维度的原始记录。

禁止清单（写清合法例外）

• 禁止让 LLM 一次性批量统计状态（数量统计易错且模型无条件相信状态栏）。例外：逐条抽取、代码汇总。
• 禁止把状态栏内容写进 system 消息（破坏前缀缓存）。例外：作为 user 消息追加到末尾。
• 禁止伪造未完成工具的成功结果（状态栏里"已完成"必须是真实状态）。例外：未完成用显式占位符。
• 禁止随意删除原始上下文。例外：状态栏够用（计数/状态跟踪）时可删原始记录，但保留未覆盖维度的原始信息。
• 禁止让状态摘要来自可被外部污染的数据源（如把外部网页片段直接写进状态栏——模型高度信任状态栏，会被反向利用）。例外：状态栏内容只来自可信的代码计算和本地环境。

参考资料

• 本书第 2.6 节《Agent 状态栏》（理论基础、构成、位置、两种更新实现与缓存代价、五种技术）。
• 笔记 02-上下文工程.md 第 2.6 节。
• Li, Bojie & Noah Shi. "Distill, Don't Retrieve: Inference-Time Context Distillation for LLM Agent Reasoning"（状态栏效果实证）。