# Agent State Bar

Stops agent loops and runaway token use with a status bar injected into long tasks.

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill agent-state-bar -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill agent-state-bar -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill agent-state-bar -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill agent-state-bar -g -a gemini-cli -y`

## Description

Agent 陷入无限循环、数不清工具调用次数、遗忘 TODO 或目标偏离、长任务中思考 token 持续膨胀时使用, , Agent 状态栏机制、作为 user 消息注入末尾的 KV Cache 理由、每轮替换与持久追加两种实现及成本模型、五种状态栏技术（时间戳、工具计数器、TODO、详细错误、系统状态）与维护铁律。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Agent 状态栏：通过元信息增强 Agent 轨迹管理

提示工程给的是静态指令，而 Agent 执行中还需要动态感知自身状态与任务进展。**Agent 状态栏**把任务进度、环境变化、工具调用计数等运行时状态整理成结构化摘要，由框架在上下文末尾持续注入。类比手机屏幕顶部始终显示时间、电量、信号, , 模型每次生成新回复时都能「瞥一眼」，据此做出更准确的决策。

## 何时使用

- Agent 反复执行相同工具调用、陷入无限循环（如超过次数限制仍在拨打）
- 模型数不清「已经调用了几次」「还剩几项 TODO」，违反显式约束
- 长任务中每次迭代的思考 token 量随上下文变长而持续增长
- Agent 过分关注局部子任务，忘记用户原始诉求和核心约束
- 小模型需要接近前沿模型的任务遵循能力
- 设计状态消息的注入方式与更新策略

## 核心原则

- **状态栏不是对话主体内容**：它不属于用户消息、模型输出或工具结果，而是框架自动生成的状态摘要，注入在上下文**最末尾**，紧邻模型即将生成的新 token。
- **理论基础是「上下文学习是检索而非推理」**：模型擅长查找，不擅长在一次前向传播中主动归纳统计。「已经打了几次电话」这类知识以原始记录形式分散在上下文里，模型每次决策都要花额外思考 token 扫描重算，效率极低且错误率高。
- **本质是把隐式状态提炼为显式知识**：原始轨迹高度冗余，大量 token 中只含少量关键状态信息；状态栏以极低的额外 token 成本，呈现原本需要扫描数千 token 才能获得的信息。
- **显式操纵注意力分配**：长上下文中早期目标和关键约束容易被后续工具结果淹没；结构化元信息放在末尾，空间上更接近新 token，获得更高注意力权重, , 一种「强制性的注意力引导」。
- **实测收益**：提供提前算好的状态栏后，较小开源模型的准确率可以接近前沿大模型；每次迭代的思考 token 量、延迟和花费均降低约一个数量级。不带状态栏时思考量随上下文变长**持续增长**，带上后**基本恒定**。
- **状态栏是上下文压缩技术之一**：它用代码确定性地维护「关于轨迹的结论」，与 LLM 驱动的压缩互补。
- **无侵入性**：所有元信息以人类可读形式出现在上下文里，开发者随时可检查；不需要微调，直接在任何语言模型上起效。

## 实践模式

### 1. 注入位置：一条 user 角色的消息，放在最末尾

```text
messages: [
  { role: "system",    content: "You are a customer service assistant..." }  ← 固定，KV Cache 已缓存
  { role: "user",      content: "Help me cancel my Xfinity plan" }
  { role: "assistant", content: null, tool_calls: [...] }   ← 第 1 轮决策
  { role: "tool",      content: "Call log..." }
  { role: "assistant", content: null, tool_calls: [...] }   ← 第 2 轮决策
  { role: "tool",      content: "Call log..." },
  { role: "user",      content: "Can you call them again to follow up?" },
  { role: "user",      content: "<agent_status>
      Current State:
      - phone_call invoked 3 times (Xfinity: 3/3 max)
      - Current time: 2025-09-14 10:30:45
      - TODO: [1] Cancel plan (in_progress)
    </agent_status>" }                                        ← 框架注入的状态栏
]
```

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/agent-state-bar/SKILL.md