moai-foundation-context

快速参考

企业级上下文和会话管理 — 为 Claude Code 提供统一的上下文优化和会话状态管理，包括 200K 令牌预算管理、会话持久化和多 Agent 移交协议。

核心能力：

• 200K 令牌预算分配和监控
• 带持久化功能的会话状态跟踪
• 上下文感知型令牌优化
• 多 Agent 移交协议
• 渐进式披露和记忆管理
• 用于并行探索的会话分叉

适用场景：

• 会话初始化和清理
• 超过 10 分钟的长时间运行工作流
• 多 Agent 编排
• 上下文窗口接近上限，令牌数超过 150K
• 在 Haiku 和 Sonnet 之间切换模型
• 工作流阶段转换

核心原则：

避免使用最后 20%：上下文窗口最后五分之一的性能会下降。

积极清理：对于 SPEC 工作流，每 1–3 条消息执行一次 /clear。

精简记忆文件：每个文件控制在 500 行以内。

禁用未使用的 MCP：最大限度减少工具定义开销。

质量胜过数量：10% 的相关上下文胜过 90% 的噪声。

---

实施指南

功能

• 智能管理 Claude Code 会话的上下文窗口
• 按优先级缓存并渐进式加载文件
• 跟踪令牌预算并发出优化提醒
• 在 /clear 操作之间选择性保留上下文
• 持久化 MCP 集成上下文

适用场景

• 管理令牌数超过 150K 限制的大型代码库
• 优化长时间运行的开发会话中的令牌使用
• 在会话重置后保留关键上下文
• 使用共享上下文协调多 Agent 工作流
• 调试 Claude Code 中与上下文相关的问题

核心模式

模式 1 — 渐进式文件加载：

按优先级层级加载文件。第 1 层包含始终加载的 CLAUDE.md 和 config.json。第 2 层包含当前 SPEC 和实现文件。第 3 层包含相关模块和依赖项。第 4 层包含按需加载的参考文档。

模式 2 — 上下文检查点：

监控令牌用量，在达到 150K 时发出警告，在达到 180K 时发出严重警报。识别需要保留的必要上下文。执行 /clear 重置会话。自动重新加载第 1 层和第 2 层文件。使用保留的上下文恢复工作。

模式 3 — MCP 上下文连续性：

通过存储 agent_id，在 /clear 操作后保留 MCP Agent 上下文。执行 /clear 后，通过重新初始化 MCP Agent 来恢复上下文。

核心模式详解

模式 1：令牌预算管理

概念：对 200K 令牌上下文窗口进行策略性分配和监控。

预算细分：系统提示词和指令约占 15K 令牌，占 7.5%，其中包括 8K 的 CLAUDE.md、4K 的命令定义和 3K 的技能元数据。活跃对话约占 80K 令牌，占 40%，其中包括 50K 的近期消息、20K 的上下文缓存和 10K 的活跃参考。通过渐进式披露加载的参考上下文约占 50K 令牌，占 25%，其中包括 15K 的项目结构、20K 的相关技能和 15K 的工具定义。紧急恢复预留约 55K 令牌，占 27.5%，其中包括 10K 的会话状态快照、15K 的 TAG 和交叉引用、20K 的错误恢复上下文以及 10K 的空闲缓冲区。

监控阈值：使用量超过 85% 时，触发紧急压缩并执行 clear 命令。使用量超过 75% 时，推迟非关键上下文，并提醒用户即将达到上限。使用量超过 60% 时，跟踪上下文增长模式。

使用场景：防止长时间运行的 SPEC 优先工作流出现上下文溢出。

模式 2：积极的 /clear 策略

概念：在关键检查点主动清理上下文，以保持效率。

必须执行 /clear 的时机：/moai:1-plan 完成后，以节省 45-50K 个 token。上下文超过 150K 个 token 时，以防止溢出。对话超过 50 条消息时，以移除过时记录。主要阶段转换前，以清空上下文。切换模型时，在 Haiku 交接到 Sonnet 的过程中执行。

适用场景：在 SPEC-Run-Sync 循环中最大限度地提高 token 效率。

模式 3：会话状态持久化

概念：通过状态快照，在中断后保持会话连续性。

会话状态层：L1 是适用于 Claude 4.5+ 的上下文感知层，包含 token 预算跟踪、上下文窗口位置、自动摘要触发条件和特定模型的优化。L2 是当前任务、变量和范围的活动上下文。L3 是近期操作和决策的会话历史。L4 是 SPEC 进度和里程碑的项目状态。L5 是用户偏好、语言和专业知识等用户上下文。L6 是工具、权限和环境等系统状态。

适用场景：在中断后恢复长期运行的任务，且不丢失上下文。

模式 4：多 Agent 交接协议

概念：以极低的 token 开销，在 Agent 之间无缝传递上下文。

交接包内容：包括 handoff_id、from_agent、to_agent、含有 session_id、model、context_position、available_tokens 和 user_language 的 session_context，含有 spec_id、current_phase、completed_steps 和 next_step 的 task_context，以及含有 last_checkpoint、recovery_tokens_reserved 和 session_fork_available 的 recovery_info。

交接验证：检查 token 预算，确保至少有 30K 的可用缓冲。验证 Agent 兼容性。必要时触发上下文压缩。

适用场景：高效执行 Plan 到 Run 再到 Sync 的工作流。

模式 5：渐进式披露与记忆优化

概念：根据相关性和需求逐步加载上下文。

渐进式摘要：提取关键句，将内容从 50K 压缩至 15K，目标压缩比为 0.3。添加指向原始内容的引用，以供参考。将原始内容存储在会话归档中，以便恢复。结果可节省约 35K 个 token。

上下文标记：避免使用“The user configuration from the previous 20 messages...”这类 token 开销较高的表述，改用“Refer to @CONFIG-001 for user preferences”这类高效引用。

适用场景：在保持上下文连续性的同时，最大限度地减少 token 开销。

---

高级文档

有关详细模式和实施策略，请参阅：

• modules/token-budget-allocation.md - 预算细分、分配策略、监控阈值
• modules/session-state-management.md - 状态层、持久化、恢复模式
• modules/context-optimization.md - 渐进式披露、摘要、记忆管理
• modules/handoff-protocols.md - Agent 间通信、数据包格式、验证
• modules/memory-mcp-optimization.md - 记忆文件结构、MCP 服务配置
• modules/reference.md - API 参考、故障排除、最佳实践

---

最佳实践

推荐做法：

• 创建 SPEC 后立即执行 /clear
• 监控 Token 使用量并做好规划
• 使用上下文感知的 Token 预算跟踪
• 在重大操作前创建检查点
• 对长工作流进行渐进式摘要
• 启用会话持久化，以便恢复
• 使用会话分叉进行并行探索
• 将每个记忆文件控制在 500 行以内
• 禁用未使用的 MCP 服务以减少开销

必需做法：

定期清理，保持上下文历史处于有界状态。上下文无限累积会降低性能，并使 Token 成本呈指数级增长。这样可以防止上下文溢出，保持响应质量稳定，并减少 60-70% 的 Token 浪费。

当 Token 使用量超过 150K 时，立即响应预算警告。在上下文窗口最后 20% 的范围内运行会导致性能显著下降。

在会话恢复期间执行状态验证检查。状态无效可能导致多步骤流程失败和数据丢失。

在执行任何上下文清理操作前，持久化会话标识符。会话 ID 是恢复中断工作流的唯一可靠机制。

当使用量达到 85% 阈值时，执行上下文压缩或清理。这样可以保留 55K Token 的紧急储备，并防止被迫中断。

---

配合使用效果良好

• moai-cc-memory - 记忆管理和上下文持久化
• moai-cc-configuration - 会话配置和偏好设置
• moai-core-workflow - 工作流状态持久化和恢复
• moai-cc-agents - 跨会话的 Agent 状态管理
• moai-foundation-trust - 质量门禁集成

---

工作流集成

会话初始化：使用 Pattern 1 初始化 Token 预算，使用 Pattern 3 加载会话状态，使用 Pattern 5 设置渐进式信息披露，使用 Pattern 4 配置交接协议。

SPEC 优先工作流：执行 /moai:1-plan，然后必须执行 /clear 以节省 45-50K Token，再执行 /moai:2-run SPEC-XXX，然后使用 Pattern 4 进行多 Agent 交接，再执行 /moai:3-sync SPEC-XXX，最后使用 Pattern 3 持久化会话状态。

上下文监控：使用 Pattern 1 持续跟踪 Token 使用量，使用 Pattern 5 实施渐进式信息披露，在达到阈值时使用 Pattern 2 执行 /clear，并使用 Pattern 4 验证交接。

---

成功指标

• Token 效率：通过积极清理降低 60-70%
• 上下文开销：系统/技能元数据少于 15K Token
• 交接成功率：经验证后高于 95%
• 会话恢复：通过状态持久化，少于 5 秒
• 记忆优化：每个记忆文件少于 500 行

---

状态：可用于生产环境（企业级） 模块化架构：SKILL.md + 6 个模块 集成：已针对 Plan-Run-Sync 工作流进行优化 生成工具：MoAI-ADK Skill Factory