context-management

上下文全生命周期管理——设计（放什么）+ 压缩（过载了怎么缩减），覆盖 agent 上下文从注入到回收的完整链路

Context Management v1.0.0

上下文全生命周期管理：设计 → 注入 → 监控 → 压缩 → 刷新。

来源：context-engineering v1.0.0（Anthropic 官方，设计侧）+ context-compressor v1.0.0（压缩引擎侧）

---

Part 1: 上下文设计

核心理念：在正确的时间给 agent 提供正确的信息。上下文是 agent 输出质量的最大杠杆——太少会幻觉，太多会失焦。

1.1 上下文五层次

从最持久到最瞬态：

text

┌─────────────────────────────────────────┐
│ Level 1: Rules 文件 (AGENTS.md/SOUL.md) │ ← 始终加载，项目级
├─────────────────────────────────────────┤
│ Level 2: 规范 / 架构文档                 │ ← 按功能/会话加载
├─────────────────────────────────────────┤
│ Level 3: 相关源文件                      │ ← 按任务加载
├─────────────────────────────────────────┤
│ Level 4: 错误输出 / 测试结果             │ ← 按迭代加载
├─────────────────────────────────────────┤
│ Level 5: 对话历史                        │ ← 累积，可压缩
└─────────────────────────────────────────┘

Level 1: Rules 文件 — 最高杠杆上下文。OpenClaw 体系用 AGENTS.md / SOUL.md / USER.md / TOOLS.md。没写进 rules 的就不存在。

Level 2: 规范和架构 — 只加载当前功能相关的部分，不要加载整个规范。

Level 3: 相关源文件 — 任务前上下文加载清单：

1. 读取你将修改的文件
2. 读取相关测试文件
3. 找到代码库中类似模式的一个示例
4. 读取涉及的类型定义或接口

信任级别：源代码/测试/类型定义 = 可信 | 配置文件/外部文档 = 需验证 | 用户提交/第三方API = 不可信

Level 4: 错误输出 — 只给精确错误信息，不要粘贴 500 行完整输出。

Level 5: 对话管理 — 长对话累积过时上下文时：开始新会话 / 总结进度 / 自动压缩（见 Part 2）。

1.2 三种打包策略

策略	适用场景	做法
Brain Dump	会话开始 / 新项目	结构化块提供：技术栈 + 规范摘录 + 约束 + 涉及文件 + 已知陷阱
Selective Include	单一功能开发	只含当前任务相关文件、模式、约束
Hierarchical Summary	大型项目	维护摘要索引，按区域加载

1.3 混淆管理

当上下文冲突时，不要默默选择一种解释——呈现歧义，给出选项，停下来问。

当需求不完整时：检查现有代码先例 → 没有先例就停下来问 → 不要发明需求。

内联规划模式：多步骤任务执行前发出轻量级计划，30秒投资防止30分钟返工。

1.4 反模式

反模式	修复
上下文饥饿（发明API、忽略约定）	每个任务前加载 rules 文件 + 相关源文件
上下文洪水（>5000行非任务内容，失焦）	只包含与当前任务相关的内容，目标 <2000 行
过时上下文（引用已删除代码）	上下文漂移时开始新会话
缺少示例（发明新风格）	包含一个要遵循的模式示例
隐式知识（不知道项目规则）	写进 rules 文件
默默混淆（该问时猜）	使用混淆管理模式明确呈现歧义

1.5 验证清单

• Rules 文件存在且覆盖技术栈、命令、约定和边界
• Agent 输出遵循 rules 文件中展示的模式
• Agent 引用实际项目文件/API（非幻觉的）
• 在主要任务之间切换时上下文已刷新

---

Part 2: 上下文压缩

五策略压缩引擎，在长任务中智能压缩上下文，减少 token 消耗 40-60%。

2.1 五策略概览

#	策略	触发条件	效果
1	基于时间清理	工具输出 > 5 分钟	替换为占位符，保留结构
2	对话摘要	消息数 > 20 条	旧消息生成摘要，保留最近 20 条
3	观察遮蔽	旧工具输出	隐藏内容，保留调用记录
4	结构化笔记	含决策/结论的消息	提取关键信息注入 system prompt
5	子Agent委托（预留）	工具 > 10 次	复杂任务交给子 Agent

2.2 使用方法

python

import sys
sys.path.insert(0, "<skill-dir>/scripts")

from compressor import ContextCompressor

compressor = ContextCompressor(max_tokens=128000)
messages, stats = compressor.check_and_compress(messages)

print(f"压缩前: {stats['before_tokens']} tokens")
print(f"压缩后: {stats['after_tokens']} tokens")
print(f"应用策略: {stats['strategies_applied']}")
print(f"压缩率: {stats['reduction_percent']:.1f}%")

2.3 集成点

• coding-framework Step 5.2: 当 token 使用超过 80% 时自动触发
• 长任务子代理: spawn 前压缩父会话上下文
• 定期压缩: 每 N 轮对话后检查一次

2.4 阈值配置

参见 references/thresholds.md 获取详细阈值说明。默认：

• 最大 token: 128,000 | 触发阈值: 80% (102,400 tokens)
• 时间清理: 5 分钟 | 对话摘要: 20 条 | 观察遮蔽: 保留最近 10 条

2.5 测试

bash

cd <skill-dir>
python -m pytest scripts/test_compressor.py -v
# 或 python scripts/test_compressor.py

---

Part 3: 生命周期协同

text

设计(Part 1)          注入              监控              压缩(Part 2)         刷新
┌──────────┐    ┌──────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────┐
│ 五层次模型 │ →  │ 三种打包  │ →  │ token 使用率 │ →  │ 五策略引擎    │ →  │ 新会话/   │
│ 打包策略   │    │ 策略选择  │    │ 阈值检测     │    │ 自动压缩     │    │ 上下文重置 │
│ 混淆管理   │    │          │    │              │    │              │    │          │
└──────────┘    └──────────┘    └──────────────┘    └──────────────┘    └──────────┘

接力规则：

• 设计阶段用 Part 1 决定"放什么"
• 运行中 Part 2 监控 token 使用率，超阈值自动压缩
• 压缩后仍超 90% → 建议开始新会话（回到 Part 1 重新设计）

---

约束

• 聚焦上下文 > 大量上下文：目标 <2000 行/任务
• 写下来 > 隐式知识：没写进 rules 的就不存在
• 呈现歧义 > 默默猜测：混淆时停下来问
• 新会话 > 长对话：主要任务切换时刷新上下文
• 示例 > 描述：一个代码示例胜过一段描述

---

Version 1.0.0 — 合并自 context-engineering v1.0.0 + context-compressor v1.0.0