上下文管理
Myrm 上下文管理确保 Agent 在 200+ 轮对话中不丢信息，并通过智能压缩与缓存优化控制成本。全链路经 1,400+ 个自动化测试验证。架构概览
每条消息在到达 LLM 前经 12 步渐进降载流水线处理：压缩流水线
第 0 层：意图引导压缩（CompressionIntent）
在任何数据被移除之前，流水线先分析当前用户查询和近期历史，构建一个压缩意图——标记哪些内容必须保留：- 聚焦文件：当前查询中主动引用的文件路径标记为受保护
- 聚焦模块：正在讨论的代码模块不受激进压缩影响
- 失败工具恢复：保留最近失败工具调用的 ID，以便 Agent 重试或解释错误
第 1 层：即时过滤（ContextBudgetGuard）
大工具输出（文件内容、搜索结果等）由智能预算守卫即时处理。区别于竞品对每个工具设置固定截断阈值的做法，Myrm 采用整体预算管理：- 智能免除：文件读写工具免截断，避免”读取→截断→重读”死循环
- 结构感知：JSON/XML/CSV 输出使用结构化裁剪（保留 schema），而非暴力截字符
- 磁盘持久化：超大输出自动保存到磁盘并返回摘要+路径，Agent 按需回查
- 预测性溢出保护：基于剩余 Token 预算动态调整截断力度
第 1.5 层：全工具输出智能管理（FilterProcessor）
不只终端命令——所有工具（搜索、API、浏览器、MCP 等）返回的大结果均受三层递进防护：
工具保护白名单：
file_read_tool、file_edit_tool 等关键工具自动豁免过滤，避免”读→截断→重读”死循环。
Prompt Cache 感知：会话恢复（Resume）或人机协作（HITL）场景自动跳过过滤，保护已有缓存前缀不被破坏。
全文可恢复：所有被过滤的大结果均持久化到 .myrm/artifacts/tool_outputs/，Agent 随时可通过文件读取工具回查原始内容。
第 2 层：Cache TTL 剪枝
过期缓存内容自动清除，避免陈旧数据占用上下文窗口。第 3 层：优先级感知压缩
消息分三档优先级：
按序应用三策略：Dedup（去重）→ Truncate（缩短冗长输出）→ Remove（丢弃低价值轮次）。
第 4 层：结构化摘要
仅压缩不足时，LLM 生成 14 字段结构化摘要（用户目标、活跃任务、错误、决策、阻塞项、下一步计划等）替换压缩历史。SummaryAuditor 验证质量，增量合并确保新信息无损折叠。摘要持久化前执行凭证+PII 双重脱敏，确保原始消息中的敏感数据不会残留在压缩历史中。 任务交接字段：摘要包含专用的blocked_items（最多 3 条当前阻塞项）和 next_steps（最多 5 条计划行动）。这些信息在 Lost-in-Middle U-curve 尾部高注意力区域（~80% 召回率）渲染，确保 Agent 压缩后精确记住”卡在哪”和”下一步做什么”。
增量合并智能：新摘要与已有摘要合并时，已解决的阻塞项自动移除，已完成的步骤自动丢弃，保持交接上下文始终最新。
第 4.5 层：压缩后热恢复
摘要完成后，PostCompactionRereadProcessor 自动从 ArtifactTracker 查询最近修改/创建的 top-5 文件，读取最新内容以 HumanMessage 注入上下文。确保 Agent 压缩后立即拥有最新文件内容，而非压缩前的过期快照。
- 动态预算：总重读内容上限 50,000 token，防止上下文再膨胀
- 完整性守卫同步：重读的文件路径自动注册到
FileIntegrityGuard，防止”文件已被修改”误报 - Prompt Cache 安全：内容以
HumanMessage注入，不触碰系统提示词前缀
第 5 层：缓存优化
注入提供商特定缓存标记（Anthropiccache_control、Qwen 前缀缓存）以最大化后续请求的 Prompt 缓存命中。
可逆压缩
不同于永久丢弃压缩内容的竞品，Myrm 压缩可逆：- 工具输出卸载到
.context/存储，非删除 - 归档检查点在压缩前捕获完整状态
- 可按需恢复内容
系统提示词架构
四档 Prompt 模式
Myrm 支持四档提示词模式，按场景控制注入 LLM 的系统指令密度和范围：
每种模式在启动时预构建为静态字符串，确保同一参数组合始终返回相同字符串对象——最大化跨用户 KV Cache 命中率。
XML 标签结构化规则隔离
所有系统提示词规则均用语义化 XML 标签包裹，让 LLM 能精确解析规则边界，避免长会话中的注意力漂移：- 框架层（
model_discipline.py）：<agent_behavior_rules>、<tool_use_enforcement>、<execution_discipline>（per-model）、<escalation_contract> - 业务层（
shared_rules.py）：<security_rules>、<memory_rules>、<task_integrity>、<response_rules>、<desktop_control_rules>、<absolute_obedience_override> - 身份层（
general_agent_prompt.py）：<identity>、<ruleset>、<tool_guidance> - 中间件层：
<user_instructions>、<workspace_context>、<cli_tools>
Per-Model 执行纪律
不同 LLM 家族有已知的失败模式。Myrm 使用模型特定的纪律提示自动修正：
这些修正在初始化时确定且会话期间不变——完全 KV Cache 安全。
Prompt Cache 优化
Prompt 缓存命中时输入 Token 成本最高可降 90%。设计原则
- 静/动分离 — 系统提示词冻结（可缓存）；动态内容进用户消息
- 4 层稳定前缀 — 系统提示词 → 工具 → 工作区规则 → 首条用户消息形成稳定前缀
- 缓存断裂检测 —
cache_break_detector主动监控失效并报告原因 - 仅追加策略 — 历史消息就地不改，保持前缀稳定
- 技能收窄不破坏缓存 — 加载技能后通过
tool_choice.allowed_tools收窄可选工具；绑定的 tools schema 列表不变，会话中 Prefix Cache 不被打断
缓存预热与空闲保活（零冷启动）
Myrm 在三个关键时刻自动预热 Anthropic/Qwen 服务端前缀缓存：- Agent 初始化时 — 系统提示词构建完成后，立即发送 fire-and-forget
max_tokens=0请求预热缓存。用户发送第一条消息时直接命中热缓存，首字延迟降低最高 52%。 - 上下文压缩后 — 上下文压缩重写消息列表后，立即预热新前缀，避免下条消息缓存未命中。
- 空闲保活 — Agent 空闲超过 4 分钟时，后台
CacheKeepAliveManager每 4 分钟发送轻量 probe（10 input tokens，0 output），防止提供商 5 分钟 TTL 过期。用户暂停思考后继续对话时，TTFT 始终保持 0.5-1s（vs 无保活的 2-5s 冷启动）。成本仅 ~$0.09/天/session。活跃对话期间自动暂停，LLM Failover 时自动替换。
保护特性
工具调用线性对齐
长对话不可避免需要压缩——但压缩消息绝不能破坏 AI 工具调用与其结果的配对关系。Myrm 提供三层架构级保护：
彻底消除竞品在会话截断后频繁出现的
Tool message must follow tool_calls API 拒绝错误。239 项专项测试验证。
会话级路由亲和（OpenAI）
对 OpenAI 模型，Myrm 自动在每个请求上注入prompt_cache_key 路由提示，确保同一会话的所有调用路由到同一推理节点，最大化 Auto Prefix Cache 命中率：
- 自动检测 — 仅 OpenAI 原生端点（api.openai.com）时注入
- 零配置 — 使用现有 session ID，用户无需任何操作
- 子 Agent 传播 — 子 Agent 通过 Python ContextVar 自动继承路由 key
- 效果 — 缓存命中率从约 60% 提升至约 87%（OpenAI 官方数据）
思考内容管理
使用推理/思考模型（DeepSeek、MiMo、Kimi、Anthropic Claude）时，ThinkingBlockCleaner 自动管理 reasoning_content 与 thinking_blocks 防上下文膨胀：
- Anthropic — 移除
reasoning_content（与thinking_blocks冗余）；保留thinking_blocks - DeepSeek/MiMo/Kimi — 选择性移除末条用户消息之前的历史
reasoning_content，除带tool_calls的消息（API 要求）。当前轮推理始终保留 - 模型切换 — 会话中从非思考模型切到思考模型时，自动为历史 assistant 消息回填空
reasoning_content防 400 错误
极端场景防爆
大规模上下文与多模态自主任务下，Myrm 采用 4 层防护：1. 网关卫生（Token 阻断）
请求进 Harness 前，控制平面网关扫描载荷。超大恶意或畸形载荷（>120K tokens）即时400 Bad Request，防 LLM 节点 OOM 与系统 halt。
2. 辅助比例护盾（优雅降级）
主模型（如 200K 窗口）接近上限时用辅助模型压缩。若辅助模型过小（如 8K），传 100K tokens 会致命崩溃并丢历史。Myrm 动态检查比例；过小时静默降级用主模型摘要并警告，会话仍存活。3. 智能媒体剥离
视觉模型自主操作（如 Computer Use）会大量追加截图。Myrm 实现滑动视觉证据窗口，仅保留最近 2 条含媒体消息用于视觉推理，剥离更早历史中的大 Base64 图，大幅降 Token 膨胀且保持视觉能力。4. 尾部预算比例
非任意截断消息，而是为主模型最大上下文预留专用 Token 预算（如 20%）给最近对话尾部，确保当前工作记忆与活跃工具结果不被挤出，保证任务连续性。子 Agent 结果蒸馏
当子 Agent 执行任务（如运行测试套件、研究代码库）时，原始输出可能长达数千行。Myrm 通过 3 级递进保护确保父 Agent 的上下文保持干净：
此外，子 Agent 通过
enable_context_compression 继承完整的上下文流水线，其内部执行过程就已享受同样的压缩、剪枝和摘要层——从源头防止产出冗长结果。
子 Agent 压缩安全：子 Agent 上下文压缩时，同样的流水线保护生效——extract_protected_head 保护前导系统消息，摘要以 HumanMessage（而非 SystemMessage）注入以保护提示词缓存，ensure_tool_pair_integrity 验证消息结构完整性。压缩后子 Agent 上下文始终以合法系统消息开头，从架构层面消除了竞品中常见的「压缩后 assistant-first 被拒」失败模式。
为什么重要：竞品将”让子 Agent 处理长日志，主 Agent 只看结果”描述为目标——Myrm 已通过零信息丢失（file_read_tool 读 vault://，支持行号范围）、聊天内 VaultArtifactCard 与结构化交接状态完整实现；无需额外 LLM vault 元工具。
会话笔记
Agent 可在会话中创建结构化笔记 — 零 API 成本持久于上下文（无需 LLM 调用），是完整压缩的轻量替代。动态阈值
压缩阈值随上下文利用率自适应：辅助模型防护
用小 LLM 做摘要时，Myrm 动态检测辅助模型上下文窗口并在发送前截断消息，防小模型压缩时崩溃 — 任意输入规模均可优雅处理。Human Anchor 保护
上下文压缩时，用户的首条指令（系统消息之后的第一条HumanMessage）不能与系统生成的合成消息（如压缩摘要、会话笔记）混淆。
Myrm 通过架构级 correct-by-construction 保证而非运行时检测来解决：
- 执行时序保证：
extract_protected_head()在任何合成消息（摘要、会话笔记、预压缩回忆）注入消息列表之前运行，函数只看到真实用户消息。 - 角色隔离：从数据库重载聊天历史时，
compacted_summary以assistant角色（AIMessage）注入，永远不会被 HumanMessage 检查器误匹配。 - 标记纵深防御：所有合成 user 角色消息携带
UNVERIFIED_CONTEXT_MARKER与<memory-context>/<pre_compact_recall_context>标签，提供额外语义边界。
_is_real_user_message() —— ~120 行运行时检查器，每次压缩时检查 4 种 flag + 5 种前缀 + 压缩元数据。每新增一种合成消息类型都需同步更新检查器，维护负担大且存在绕过风险。Myrm 的架构从结构上消除了误识别的可能性。
7 层超大输出纵深防护
当工具输出超出上下文窗口预算（如 200KB JSON 响应、50K 行测试日志），Myrm 采用 7 层纵深防护策略。每层独立运作并有独立 fallback，确保零数据丢失和完整可恢复性：
完整数据保留：竞品替换超大输出为简短指令（原数据丢失）或仅做字符截断，Myrm 的 vault 机制保留 100% 原始内容。Agent 可通过
file_read_tool(paths=["vault://..."], line_range="100:200") 按需精确读取任意片段。
vs. 竞品：nanobot 使用单层”in-flight context governor”，用 bounded instruction 替换工具输出——原始数据丢失。OpenClaw 使用 2 层截断（per-result + aggregate budget）+ 文件 spill——可用但缺乏 vault 协议和前端可视化。Myrm 的 7 层方案确保每条工具路径（MCP、bash、浏览器、子 Agent、hooks）都有专属防护和独立 fallback 链。
后台任务的极致降噪与 Token 优化
Myrm 对后台辅助任务（如自动生成会话标题）的 Token 消耗进行了极致优化：- O(1) 截断与结构化剥离：精准剥离代码块、URL 链接、HTML 标签等对生成标题毫无帮助的“高 Token 密度”结构，只保留核心自然语言。
- 0 Token 拦截机制：如果经过降噪后文本为空（例如用户只发了一段代码），系统会直接触发本地兜底文案（如
Snippet），实现 0 Token 消耗，彻底避免无效的 API 调用。
零配置压缩参数与模型热切换
切换模型或调整上下文参数，下一条消息即时生效——无需重启、无需/reset、无需编辑 YAML。
工作原理
- DB 配置持久化：所有模型/压缩设置通过 GUI Settings 存储在数据库中，修改即刻持久化。
- Per-message 指纹比对：
compute_execution_fingerprint()对 30+ 参数（model、provider、engine_params、prompt_mode、skills 等）生成哈希。每条新消息都会比对当前指纹与缓存指纹。 - 自动重建：指纹不匹配时，
ChatAgentExecutionCache自动 teardown 旧 agent unit → 构建新 unit——对用户完全透明。 - 比例阈值自动计算：
ContextConfig(max_context_tokens=N)自动按 N 的比例计算所有压缩阈值：compress_threshold= N × 50%compress_force_threshold= N × 70%summarize_trigger_threshold= N × 90%- 从 GPT-4o (128K) 切换到 Claude Sonnet (200K) → 所有阈值自动等比放大。
- 上下文窗口自动发现：
enrich_model_context_window()从 LiteLLM registry 自动获取 500+ 模型的真实max_input_tokens，无需手动配置context_length。 - 压缩模型自动选择：
summarizer_llm默认使用lite_model（更便宜、更快），不可用时自动回退到主模型。 - 熔断器保护：摘要失败触发熔断器 + half-open 探针自动恢复——无级联错误。
前端可视化
- 上下文健康环（
ContextUsageIndicator）：实时 SVG 环形指示器显示 Token 用量百分比、健康状态点（绿/黄/红）、一键手动压缩按钮、≥75% 用量自动显示 Fork 建议。 - 会话上下文健康面板（
SessionContextHealthPanel）：三卡片布局展示 20+ 指标，涵盖压缩效率、修剪 ROI、缓存命中率、自适应退避状态。
vs. 竞品
409 项热更新测试验证（execution_cache 21 + context_management 312 + config/hot-reload 17 + 前端 59）。
Progress-Aware 双超时保护
压缩（Summarization）过程可能因 LLM 响应缓慢或完全挂死而阻塞。Myrm 采用 Progress-Aware 双超时 精准区分两种情况：
vs. 竞品：Hermes 仅提供
hygiene_timeout_seconds（固定单一超时 + 冷却期）。当本地模型生成速度慢（如 8B Q4 模型每秒仅几个 token）时，固定超时会误杀正常生成过程。Myrm 的 progress-aware 设计从根本上解决了「慢≠死」的区分问题。