name: token-optimizer
description: OpenClaw 系统的成本控制与 Token 消耗节约助手。当系统需要进行性能优化、上下文压缩、日志清理或发现某个助手（如进化官）消耗异常飙升时使用。它提供工作区清理、长文本读取熔断以及会话生命周期管理策略。

# Token 优化与成本控制技能 (Token Optimizer)

## 核心原则
OpenClaw 是基于上下文运行的数字员工。过度臃肿的工作区文件、未处理的长对话、不加限制的全量读取，都会导致 Input Token 呈指数级飙升。本技能旨在以系统化的方式拦截浪费，保持系统“精悍”。

## 一、 会话生命周期管理（关于 `/new` 怎么用最科学）

用户询问“在启用 /new 命令前后，怎样做才能既省 Token 又保持任务延续性”时，请严格执行以下 **“存档-截断-重载” 三步法**：

1. **启用 `/new` 前（记忆浓缩）**
   - 不要直接执行 `/new`，这会导致当前任务状态全丢。
   - 先执行：`请将我们刚才讨论的任务进展、已确认的结论和下一步计划，提炼为一份不超过 300 字的摘要，保存为当前目录下的 "TASK_CONTEXT_临时.md" 文件。`
   - *（注：如果任务极大，可存入该助手的 MEMORY.md 的“进行中任务”版块）。*

2. **执行 `/new`（切断死重）**
   - 助手提示用户输入 `/new`（或由用户直接输入）。系统将丢弃数万字的啰嗦对话历史，Input Token 瞬间清零。

3. **启用 `/new` 后（热启动重载）**
   - 在新会话的开头，用户或助手执行指令：`请读取 "TASK_CONTEXT_临时.md"（或 MEMORY.md），了解我们的当前进度并继续工作。`
   - **效果**：用 300 字的“浓缩记忆”替换了之前可能多达 30000 字的“长篇大论”，任务丝滑延续，且成本暴降 90%。

## 二、 工作区大扫除策略 (Workspace Hygiene)

- **为什么耗 Token**：OpenClaw 默认会将根目录下的所有 `.md` 文件塞入系统提示词。死文件越多，起步消耗越大。
- **清理规则**：
  - 根目录 **仅保留** 核心架构文件：`AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`, `MEMORY.md`, `BOOTSTRAP.md` 以及必要的代码依赖如 `package.json`。
  - **动态保护**：在执行脚本清理时，只移动 `mtime +3`（超过 3 天未被修改）的文件到 `archive/` 或 `docs/` 目录，以防打断正在进行的草稿修改任务。

## 三、 长文本拦截与熔断 (Tool Output Truncation)

当协助用户进行长文本分析、代码审查或网页读取时，遵守以下铁律：
- **禁止全量输出**：绝不使用 `cat` 命令直接读取万行日志，绝不把整个网页源码未经处理直接塞回对话。
- **使用管道与摘要**：优先使用 `head -n 100` 查看结构，使用 `grep "error"` 提取关键信息。
- **主动预警**：当检测到需要处理的输入文件超过 50KB 时，主动提示用户：“该文件过长，可能产生高额 Token 费用，建议您使用便宜的模型（如 GLM-5），或允许我只提取核心结构。”

## 四、 跨助手监测 (Audit)
- 支持调用 `openclaw sessions list --json` 提取并分析各助手的 Token 消耗榜单。
- 若发现某助手消耗不成比例，优先排查其工作路径根目录是否存在大文件，或其对话 Session 是否过长。

## 五、 L2/L3 自动化工具 (v2.1 改进版)

为将上述原则转化为可执行的生产力工具，本 Skill 已开发出配套的自动化脚本：

### L2 - 交互式优化助手 (`improved_interactive_token_optimizer.sh`)
- **定位**: 中级用户
- **功能**: 
  - 交互式生成任务上下文摘要，用于 `/new` 命令前后无缝衔接
  - 扫描所有助手工作区，识别潜在的"Token 杀手"文件，并提供清理建议
  - 一键安装自动化清理定时任务
  - 查看优化日志和统计信息
- **使用方式**: 
  ```bash
  # 从 token-optimizer 技能目录运行
  cd /path/to/token-optimizer
  ./scripts/improved_interactive_token_optimizer.sh
  
  # 或使用完整路径（替换为你的实际路径）
  /your/openclaw/path/skills/token-optimizer/scripts/improved_interactive_token_optimizer.sh
  ```

### L3 - 自动化守护进程 (`automated_token_optimizer.py`)
- **定位**: 高级用户 / 系统级部署
- **功能**: 
  - **每日凌晨 2 点**自动执行（通过 OpenClaw cron job）
  - 安全地将所有助手工作区中**超过 3 天未修改**的非核心文件移入 `archive/` 目录
  - 严格遵守"动态保护"原则，绝不触碰进行中的任务文件
  - 详细的日志记录和错误处理
- **效果**: 系统长期保持"精悍"状态，从根本上杜绝因工作区臃肿导致的隐性成本浪费

### 安装与配置
- **一键安装**: 运行 `install-token-optimizer.sh` 脚本
- **手动配置**: 使用 OpenClaw cron 系统添加定时任务
- **日志位置**: `./logs/optimizer.log`（相对于技能目录）

> **📌 用户分级建议**:
> - **新手 (L1)**: 请先阅读并理解本 Skill 的核心原则，手动实践“三步法”和“工作区大扫除”。
> - **中级 (L2)**: 可以使用交互式工具，在获得建议后手动确认执行。
> - **高级 (L3)**: 可以启用自动化守护，让系统自我维护。但请确保理解其工作原理和安全边界。