SOP-Manager 技能

本技能提供智能的任务优化、拆解与上下文管理能力。通过SOP库实现经验复用，通过任务拆解最大化并行效率，通过上下文压缩减少无效token消耗。整体目标：更少的工具调用、更短的上下文、更少的试错。

📦 安装说明

首次安装

1. 复制技能目录
   bash # 将技能目录复制到WorkBuddy技能目录 cp -r sop-manager ~/.workbuddy/skills/

2. 运行初始化脚本
   bash cd ~/.workbuddy/skills/sop-manager/scripts python init.py

3. 赋予脚本执行权限（Unix/macOS）
   bash chmod +x ~/.workbuddy/skills/sop-manager/scripts/*.py

4. 在SOUL.md中增加配置

将以下内容添加到你的 ~/.workbuddy/SOUL.md 文件中：

```markdown
## 智能任务优化（SOP-Manager）

核心理念：上下文信息密度最大化（来自Generic Agent）
> 不是上下文越长越好，而是每一条出现在上下文中的信息都对当前决策有用。

每次任务开始前，必须主动：

1. 提取任务特征：分析用户请求，提取任务类型和关键词
2. 查询SOP库：检查 ~/.workbuddy/sop-library.json 是否匹配（匹配度>0.3）
3. 决策技能组合：
   • 简单任务（<3工具调用）：不调用优化技能
   • 中等任务（3-8工具调用）：调用 karpathy-guidelines
   • 复杂任务（>8工具调用）：调用 karpathy-guidelines + self-improving-agent
   • 有SOP匹配时：遵循SOP中的 skill_combination
4. 加载SOP（如匹配）：读取SOP中的 steps 和 learnings，直接应用

Token追踪与省Token证明（必须执行）：

1. Token追踪（每次工具调用后）

   • 记录到 ~/.workbuddy/sop-manager/token-logs/YYYY-MM-DD.json
   • 使用脚本：python ~/.workbuddy/skills/sop-manager/scripts/track_token.py --log --tool <tool> --task <desc> --input <n> --output <n>

2. 生成Token消耗报告（任务完成后）

   • 使用脚本：python ~/.workbuddy/skills/sop-manager/scripts/token_report.py --daily
     ```

验证安装

运行以下命令验证安装是否成功：

# 测试SOP匹配
python ~/.workbuddy/skills/sop-manager/scripts/match_sop.py "测试任务"

# 测试token追踪
python ~/.workbuddy/skills/sop-manager/scripts/track_token.py --summary

# 测试报告生成
python ~/.workbuddy/skills/sop-manager/scripts/token_report.py --daily

卸载

# 删除技能目录
rm -rf ~/.workbuddy/skills/sop-manager/

# 删除SOP库（可选）
rm ~/.workbuddy/sop-library.json

# 删除token日志（可选）
rm -rf ~/.workbuddy/sop-manager/token-logs/

核心理念：上下文信息密度最大化

> 来自 Generic Agent（GA）的第一性原理
>
> $$\text{信息密度} D(\mathcal{C}) = \frac{\text{决策相关信息量}(\mathcal{C})}{\text{上下文总长度}(\mathcal{C})}$$
>
> 追求每一条出现在上下文中的信息都对当前决策有用，而非追求上下文越长越好。

三大操作原则

第一部分：任务拆解方法论

> 这是节省token的核心。拆解好了，后续执行才能高效。

拆解四原则

原则1：按依赖关系排列（识别串行/并行）

并行 vs 串行判断标准：

原则2：控制粒度——每个任务"一次可验证"

粒度三问（三个都是"是"才适中）：
1. 这步完成后，我能明确说"✅ 完成了"吗？
2. 这步大概需要 1-5 次工具调用吗？
3. 如果卡住了，我知道卡在哪里吗？

原则3：优先级排列

① 阻塞其他任务的前提（克隆仓库、读取配置）← 最高优先级
② 核心产出（构建模型、修复代码、生成报告）
③ 包装/文档（更新README、写注释）
④ 最终交付（git push、发送邮件）        ← 最后执行

原则4：拆解后自我审查

完成初始拆解后：
- 有没有两个任务高度重叠（>80%）？→ 合并
- 有没有任务可以和上一个一起完成（顺手的事）？→ 合并
- 整体任务数是否在 5-10个 之间？超过10个要再合并

第二部分：最小工具集选择

> GA 核心发现：9个原子工具覆盖5大能力类，token消耗仅为Claude Code的35%

工具选择原则

组合优于枚举：复杂行为通过原子工具的序列组合来实现，而非引入新的专用接口。

通用原子工具集（参考GA设计）

工具选择纪律

1. 优先用 code_run 替代专用工具
   - 能用脚本实现的，不新增工具
   - 示例：GlobTool → code_run + glob模块；GrepTool → code_run + grep

2. file_read 精准读取，不全量加载
   - 用 start + count 参数只读需要的部分
   - 用 keyword 参数锚定到相关代码段

3. 每轮 code_run 只调用一次
   - 确保每次执行结果被观察后再决定下一步
   - 避免并行执行多个代码块导致状态混乱

工具膨胀的代价

第三部分：四级压缩流水线

> 执行过程中主动"瘦身"，确保活跃上下文始终保持简洁和任务相关。
> GA 用此方法将上下文控制在30k token以内。

何时触发各级压缩

消息产生
  ↓
Stage 1（每条消息）: 工具输出截断
  ↓
Stage 2（每~5轮）: Tag级压缩
  ↓
Stage 3（超预算时）: 消息驱逐
  ↓
Stage 4（每轮注入）: 工作记忆锚点（补偿损失）

Stage 1：工具级截断——控制增量

策略：每个工具执行结果进入对话历史之前截断。

对称头尾保留：超过阈值L时，保留前L/2和后L/2字符，中间替换为省略号。
原因：尾部信息同样关键（错误信息、文件结尾、最新日志）。

Stage 2：Tag级压缩——控制存量

触发：约每5轮执行一次；额外收益：使约80%的轮次能命中prompt-cache。

做法（分两类处理）：

1. 替换过期的工作记忆块：<history> 和 <key_info> 中的旧快照替换为 [...]
2. 截短推理和工具标签：<thinking>、<tool_use>、<tool_result> 截断到约800字符的头尾窗口

保护：最近10条消息不受Stage 2压缩影响。

Stage 3：消息驱逐——总量控制

触发条件：对话历史总字符数 $C_H$ 超过预算 $B$ 时启动。

执行步骤：

1. 更激进地重跑Stage 2：只豁免最近4条消息
2. FIFO驱逐：按先进先出顺序从最早消息开始移除，直到 $C_H$ 降到 $0.6B$ 以下（刻意"过度修剪"，预留40%缓冲区）
3. 结构修复：重新对齐历史确保以用户消息开头；孤立的 tool_result 转为纯文本

关键设计：被驱逐的消息直接丢弃，不生成摘要（避免额外LLM调用、摘要占用空间、质量难保证）。

Stage 4：工作记忆锚点——补偿损失

注入时机：每次工具调用之后，在下一条用户消息中注入。

锚点内容（三部分）：

1. 最近20条单行轮次摘要（每条约100字符）
   - 记录"第N轮做了什么、结果如何"
   - 优先用 <summary> 字段（模型在推理过程中提供）
   - 备选：从该轮实际工具操作自动生成

2. 当前轮次编号：让模型知道任务已进行多少轮

3. 持久化 key_info 块：通过 update_working_checkpoint 维护的结构化笔记
   - 包含：当前目标、关键发现、约束条件
   - Agent显式更新，系统自动携带到后续每一轮上下文

自动压缩：锚点被注入到每条用户消息中，Stage 2会自动将旧锚点副本压缩为 [...]，只保留最新一份完整内容。

第四部分：三阶段自我进化

> GA核心机制：从自然语言→SOP→代码执行，节省89.6% token

进化路径

Stage 1: 自然语言执行
  "从零探索，trial-and-error"
  Token消耗：高（~222,203）
  LLM调用：多（~32次）
         ↓ 蒸馏成功经验为SOP
Stage 2: SOP执行
  "读取SOP → 按步骤执行 → 根据结果优化SOP"
  Token消耗：中（~50,000）
  LLM调用：中（~8次）
         ↓ 将稳定SOP编译为代码
Stage 3: 代码执行
  "直接调用预编写脚本完成整个流程"
  Token消耗：低（~23,000）
  LLM调用：少（~5次）

进化触发机制

start_long_term_update() —— 只在以下条件满足时触发蒸馏：

触发时机：
- 子目标成功完成时
- 故障恢复转换时
- 发现可复用模式时

对SOP库的增强

在SOP对象中新增字段：

{
  "evolution_stage": 3,
  "code_script": "scripts/do_task_v3.py",
  "token_cost": {
    "stage1": 222203,
    "stage2": 50000,
    "stage3": 23000
  }
}

第五部分：任务复杂度评估与技能调度

复杂度判断

技能组合决策

任务到来 → 查询SOP库（匹配度>0.3?）
  ├─ 有匹配 → 使用SOP中的skill_combination，加载steps/learnings/evolution_stage
  └─ 无匹配 → 根据复杂度决策
               ├─ 简单（<3）  → 不调用优化技能，直接执行
               ├─ 中等（3-8） → 调用 karpathy-guidelines
               └─ 复杂（>8） → 调用 karpathy-guidelines + self-improving-agent
                                  + 执行任务拆解 + 启动四级压缩

第六部分：SOP库管理

SOP库结构（增强版）

{
  "version": "2.0",
  "total_token_saved": 0,
  "evolution_stats": {
    "stage1_total": 0,
    "stage2_total": 0,
    "stage3_total": 0
  },
  "sops": [
    {
      "id": "sop-001",
      "name": "Python数据分析任务",
      "keywords": ["数据分析", "pandas", "可视化"],
      "task_pattern": "分析{数据类型}并生成{输出格式}",
      "skill_combination": ["karpathy-guidelines"],
      "evolution_stage": 2,
      "code_script": "",
      "task_decomposition": {
        "parallel_groups": [["读取数据文件", "检查环境依赖"]],
        "serial_steps": ["数据清洗", "生成图表", "输出报告"]
      },
      "steps": ["读取数据文件", "数据清洗", "生成可视化图表", "输出分析报告"],
      "learnings": ["优先使用pandas_profiling", "图表保存到指定目录"],
      "last_used": "2026-05-11",
      "success_count": 3,
      "avg_token_saved": 1500,
      "token_cost": {"stage1": 8000, "stage2": 3000, "stage3": 1200}
    }
  ]
}

SOP创建

python ~/.workbuddy/skills/sop-manager/scripts/create_sop.py \
  --name "任务名称" \
  --keywords "关键词1,关键词2" \
  --steps "步骤1|步骤2|步骤3" \
  --learnings "经验1|经验2"

SOP更新

python ~/.workbuddy/skills/sop-manager/scripts/update_sop.py \
  --sop-id "sop-001" \
  --add-learning "新经验" \
  --token-saved 2000

第七部分：完整执行流程

任务开始时（MUST DO）

Step 1 —— 评估复杂度
- 快速判断：简单/中等/复杂？
- 复杂任务进入Step 2

Step 2 —— 查询SOP库

python ~/.workbuddy/skills/sop-manager/scripts/match_sop.py "任务描述"

• 有匹配 → 加载SOP，跳到Step 4
• 无匹配 → 继续Step 3

Step 3 —— 任务拆解（仅复杂任务）
- 按依赖关系拆解，标注并行组
- 展示拆解结果给用户确认再执行
- 启动四级压缩流水线（Stage 1-4）

Step 4 —— 执行
- 严格按拆解顺序
- 并行组：同一消息中多个工具调用同时发出
- 串行组：逐步完成，每步完成后标记TaskUpdate
- 每轮结束后：注入工作记忆锚点（Stage 4）

任务执行中（上下文压缩纪律）

任务完成后（MUST DO）

Step 5 —— 评估进化阶段
- 首次执行：Stage 1 → 创建SOP（stage=1）
- 第二次执行：Stage 2 → 加载SOP执行，优化SOP，更新 evolution_stage=2
- 稳定后：Stage 3 → 将SOP编译为代码脚本，更新 evolution_stage=3、code_script

Step 6 —— 更新SOP库
- create_sop.py 或 update_sop.py
- 记录本次节省的token估算值
- 更新 token_cost 字段

第八部分：Token消耗追踪与省Token报告

> 为什么需要这个？ 没有量化的节省证明，"省token"就是一句空话。本部分提供完整的token追踪、报告生成和省token证明，形成技能完美收官闭环。

Token追踪机制

追踪内容

每次工具调用都记录以下信息到 ~/.workbuddy/sop-manager/token-logs/YYYY-MM-DD.json：

{
  "timestamp": "2026-05-11T19:30:00",
  "tool_name": "code_run",
  "task_description": "执行数据分析脚本",
  "input_tokens": 1500,
  "output_tokens": 800,
  "total_tokens": 2300,
  "metadata": {
    "skill_combination": ["karpathy-guidelines"],
    "sop_id": "sop-001",
    "evolution_stage": 2
  }
}

自动追踪时机

Token消耗报告

报告类型

1. 每日报告（默认）：今日token消耗详情
2. 每周报告：本周token消耗趋势
3. 简化版报告：当今日消耗 > 100,000 tokens 时自动触发

报告内容

============================================================
📊 Token消耗日报 - 2026-05-11
============================================================

## 📈 总体统计
- 总消耗：**45,230 tokens**
- 总调用次数：18 次
- 平均每次调用：2,513 tokens

## 🔧 工具消耗排行
1. **code_run**
   - 调用次数：8 次
   - 总消耗：20,000 tokens
   - 平均每次：2,500 tokens

2. **web_fetch**
   - 调用次数：5 次
   - 总消耗：15,000 tokens
   - 平均每次：3,000 tokens

3. **file_read**
   - 调用次数：5 次
   - 总消耗：10,230 tokens
   - 平均每次：2,046 tokens

## 🔥 最耗Token的任务（Top 3）
1. 执行数据分析脚本
   - 消耗：**12,000 tokens**

2. 爬取网页内容
   - 消耗：**8,000 tokens**

3. 读取大文件
   - 消耗：**5,000 tokens**

## 💡 优化建议
- 🔴 **web_fetch** 平均消耗较高（3,000 tokens/次），建议检查是否可以拆分任务或使用SOP优化
- 🟡 检测到权限确认工具调用，考虑使用 `allowedTools` 参数预授权，减少交互轮次
- 💡 对于重复性任务，建议使用SOP-Manager形成SOP，下次直接复用，可节省50-80% token

## ✅ 省Token证明
今日通过SOP复用节省约 **15,000 tokens**
累计通过SOP库节省约 **45,000 tokens**

**节省来源：**
- SOP复用：避免重复探索，直接按步骤执行
- 任务拆解：最大化并行执行，减少总轮次
- 上下文压缩：Stage 1-4 流水线控制上下文大小
- 三阶段进化：Stage 3 代码执行，token消耗降低89.6%
============================================================

生成报告的方法

方法1：使用脚本生成

# 生成今日详细报告
python ~/.workbuddy/skills/sop-manager/scripts/token_report.py --daily

# 生成今日简化版报告（token消耗 > 100k 时）
python ~/.workbuddy/skills/sop-manager/scripts/token_report.py --daily --simple

# 生成指定日期的报告
python ~/.workbuddy/skills/sop-manager/scripts/token_report.py --daily --date 2026-05-10

# 生成本周报告
python ~/.workbuddy/skills/sop-manager/scripts/token_report.py --weekly

方法2：任务完成后自动生成

在任务完成的Step 6（更新SOP库）之后，自动调用 token_report.py 生成今日报告，并 appended 到工作记忆中。

省Token证明计算

计算逻辑

省Token证明 = 实际消耗（无优化） - 实际消耗（有优化）

其中：
- 实际消耗（无优化） = 从SOP库的token_cost.stage1估算（首次探索消耗）
- 实际消耗（有优化） = 本次任务实际消耗的token数
- 节省量 = 实际消耗（无优化） - 实际消耗（有优化）

证明展示

在每日报告的最后部分，展示：

1. 今日节省量：通过SOP复用节省的token数
2. 累计节省量：通过SOP库累计节省的token数
3. 节省来源：列出具体的节省机制（SOP复用、任务拆解、上下文压缩、三阶段进化）
4. 节省百分比：(节省量 / 无优化消耗) * 100%

优化建议生成规则

规则1：高消耗工具警告

如果某个工具的平均消耗 > 5,000 tokens/次，给出警告和建议。

规则2：权限工具检查

如果检测到 ask_permission 或 AskUserQuestion 调用，建议用 allowedTools 预授权。

规则3：调用次数检查

如果今日工具调用次数 > 20次，建议检查是否有可合并的操作。

规则4：SOP复用建议

对于重复性任务，强烈建议使用SOP-Manager形成SOP，下次直接复用。

简化版报告触发条件

触发条件：今日token消耗 > 100,000

简化版内容：
- 只显示总消耗和前3个最耗token的工具
- 只显示前3个最耗token的任务
- 只显示前3条优化建议

目的：快速定位token消耗大户，避免信息过载。

参考资料

• references/sop-library-format.md - SOP库完整结构说明（含evolution_stage）
• references/skill-combination-rules.md - 技能组合决策规则详解
• GA 原文：https://datawhalechina.github.io/hello-generic-agent/
• 第7章：上下文信息密度最大化（第一性原理）
• 第9章：最小原子工具集（9工具 vs 53工具）
• 第11章：四级压缩流水线（30k token以内）
• 第12章：自我进化机制（89.6% token节省）