Gliding Horse 工具结果压缩体系：如何用“指针”驯服上下文膨胀

摘要：本文深入解析 Gliding Horse（流马）Agent 操作系统的工具结果压缩体系。针对 AI Agent 执行长周期任务时上下文窗口易被工具调用结果撑爆的痛点，流马设计了一套“指针+摘要”的纵深防御式压缩方案。文章详细拆解了 ResultRouter 智能路由、ToolResultCompressor 安全网、ContextWindowManager 全局控制三层架构，以及智能回收、流式/非流式路径统一等核心机制。通过将大块结果替换为轻量 IRI 引用并注册微工具，该方案在降低 90%+ Token 消耗的同时，实现了关键信息的 100% 可追溯，是构建长周期、高可靠自主 Agent 的关键基础设施。

关键词：Gliding Horse；流马；Agent 操作系统；工具结果压缩；上下文窗口管理；LLM；Token 优化；ResultRouter；ContextWindowManager；智能回收；IRI 引用；微工具

在 AI Agent 执行任务的过程中，工具调用结果的体积往往是上下文的头号杀手。一个 grep 搜索可能返回上万字符的匹配列表，一次 bash 命令可能输出几十 KB 的编译日志，如果把这些结果原封不动地塞进 LLM 的上下文窗口，不出几轮 Token 就会爆炸，轻则成本飙升，重则直接触发 API 限制。

Gliding Horse（流马）作为面向长周期、多步执行的 Agent 操作系统，设计了一套纵深防御式的工具结果压缩体系。它并非简单截断，而是通过 “指针 + 摘要” 的模式，将大块结果替换为轻量引用，同时保留 LLM 随时通过微工具查询完整细节的能力。信息不丢失，上下文不爆炸。

一、三层压缩架构：纵深防御

流马的工具结果管理分为三个层次，在结果注入上下文的不同阶段递进式压缩：

flowchart TB ToolResult["工具执行结果<br/>(可能数万字节)"] --> L1["① ResultRouter<br/>route_tool_result()"] L1 -->|"<16KB: 原样+IRI"| Messages["注入 messages[]"] L1 -->|"16~32KB: 截断+micro-tool"| Messages L1 -->|">32KB JSON: 图谱化+micro-tool"| Messages L1 -->|">32KB 非JSON: 摘要+micro-tool"| Messages Messages --> L2["② ToolResultCompressor<br/>compress_tool_messages()"] L2 -->|"安全网: 二次压缩"| Messages2["更新后的 messages[]"] Messages2 --> L3["③ ContextWindowManager<br/>消息数/Token 超限时"] L3 -->|"保留最近4条，中间摘要"| Final["最终上下文"]

• 第一层 (ResultRouter)：结果进入上下文之前，根据大小和类型自动选择处理策略——小结果原样放行，大结果截断或图谱化，并注册微工具供 LLM 按需查询。
• 第二层 (ToolResultCompressor)：在上下文已有压力时，对 message 列表中的旧工具结果做二次摘要压缩，作为兜底安全网。
• 第三层 (ContextWindowManager)：当消息总数或估算 Token 超过硬上限时，对整个消息序列进行结构化压缩，保留最近关键信息，中间段用摘要替代。

三层相互配合，既保证了单条结果不撑爆上下文，又防止了多次小结果累积膨胀。

二、第一层：ResultRouter 的智能路由

ResultRouter 是整个压缩体系的核心防线。它在工具结果返回后、注入 messages 前工作，能够访问 L0 存储和 ToolExecutor，拥有完整上下文。

flowchart LR Result["原始工具结果"] --> Check{"结果大小?"} Check -->|"< 16KB"| Pass["PassThrough<br/>原样 + IRI"] Check -->|"16KB ~ 32KB"| Trunc["Truncate<br/>smart_truncate + micro-tool"] Check -->|"> 32KB + JSON"| Graph["Graphify<br/>知识图谱化 + micro-tools"] Check -->|"> 32KB + 非JSON"| Summ["Summarize<br/>text_summary + micro-tool"] Pass -->|"> 3KB 时预注册 micro-tool"| MSG1["注入上下文"] Trunc --> MSG2["截断结果 + IRI + micro-tool"] Graph --> MSG3["图谱摘要 + IRI + micro-tools"] Summ --> MSG4["文本摘要 + IRI + micro-tool"]

关键机制：

1. Micro-tool 模式：任何被压缩或截断的结果，系统都会自动注册一个专用微工具（如 read_full_result_{call_id}），LLM 可以随时调用它来获取完整原始数据。信息零丢失。

2. PassThrough 增强：即使结果小于 16KB 原样放行，只要超过 3KB，系统也会预注册微工具。这为后续的“智能回收”埋下伏笔——当上下文压力增大时，这些较大的 PassThrough 结果可以被替换为轻量引用，而不丢失可回溯性。

3. Graphify 图谱化：对于大型 JSON 结构数据（如 API 返回的复杂对象），自动提取关键实体和关系存入知识图谱（L0/L2），LLM 拿到的是简洁的图谱摘要，后续可通过 SPARQL 或微工具深入探索。

下面是一个 Python 代码示例，展示 ResultRouter 如何根据结果大小和类型选择不同的压缩策略：

from typing import Any, Optional
import json

class ResultRouter:
    """智能路由：根据结果大小和类型选择压缩策略"""
    
    def __init__(self, micro_tool_registry: dict):
        self.registry = micro_tool_registry  # 微工具注册表
    
    def route_tool_result(self, call_id: str, result: Any) -> dict:
        """路由工具结果，返回注入上下文的压缩内容"""
        raw = json.dumps(result) if not isinstance(result, str) else result
        size = len(raw.encode("utf-8"))
        
        # 策略 1：小于 16KB —— 原样放行，超过 3KB 预注册微工具
        if size < 16 * 1024:
            if size > 3 * 1024:
                self._register_micro_tool(call_id, raw)
            return {"content": raw, "iri": f"iri://tool-result/{call_id}"}
        
        # 策略 2：16KB ~ 32KB —— 截断 + 微工具
        if size < 32 * 1024:
            truncated = self._smart_truncate(raw, max_bytes=2048)
            self._register_micro_tool(call_id, raw)
            return {"content": truncated, "iri": f"iri://tool-result/{call_id}"}
        
        # 策略 3：大于 32KB —— 根据类型选择图谱化或摘要
        if self._is_json(result):
            graph_summary = self._graphify(result)  # 提取实体关系图谱
            self._register_micro_tool(call_id, raw)
            return {"content": graph_summary, "iri": f"iri://tool-result/{call_id}"}
        else:
            summary = self._summarize(raw, max_chars=500)  # 文本摘要
            self._register_micro_tool(call_id, raw)
            return {"content": summary, "iri": f"iri://tool-result/{call_id}"}
    
    def _smart_truncate(self, text: str, max_bytes: int) -> str:
        """智能截断：保留开头和结尾的关键信息"""
        encoded = text.encode("utf-8")
        if len(encoded) <= max_bytes:
            return text
        head = encoded[:max_bytes // 2].decode("utf-8", errors="ignore")
        tail = encoded[-max_bytes // 2:].decode("utf-8", errors="ignore")
        return f"{head}\n...（中间省略 {len(encoded) - max_bytes} 字节）...\n{tail}"
    
    def _is_json(self, result: Any) -> bool:
        """判断结果是否为 JSON 结构数据"""
        if isinstance(result, (dict, list)):
            return True
        if isinstance(result, str):
            try:
                json.loads(result)
                return True
            except (json.JSONDecodeError, ValueError):
                return False
        return False
    
    def _graphify(self, data: Any) -> str:
        """将大型 JSON 图谱化为摘要（示意实现）"""
        if isinstance(data, dict):
            keys = list(data.keys())[:5]
            return f"[图谱摘要] 包含 {len(data)} 个字段: {', '.join(keys)}..."
        if isinstance(data, list):
            return f"[图谱摘要] 包含 {len(data)} 条记录，首条字段: {list(data[0].keys()) if data else '空'}"
        return "[图谱摘要] 非结构化数据"
    
    def _summarize(self, text: str, max_chars: int) -> str:
        """文本摘要（示意实现）"""
        return text[:max_chars] + f"\n...（全文 {len(text)} 字符，请调用微工具查看）..."
    
    def _register_micro_tool(self, call_id: str, full_result: str):
        """注册微工具，供 LLM 按需查询完整结果"""
        self.registry[call_id] = {
            "name": f"read_full_result_{call_id}",
            "description": f"获取工具调用 {call_id} 的完整原始结果",
            "handler": lambda: full_result
        }


# ========== 使用示例 ==========
router = ResultRouter(micro_tool_registry={})

# 场景 1：小结果（< 16KB）—— 原样放行
small_result = {"status": "ok", "count": 42}
print(router.route_tool_result("call_001", small_result))
# 输出: {'content': '{"status": "ok", "count": 42}', 'iri': 'iri://tool-result/call_001'}

# 场景 2：中等结果（16KB ~ 32KB）—— 截断 + 微工具
medium_result = "A" * 20_000  # 约 20KB 文本
routed = router.route_tool_result("call_002", medium_result)
print(f"截断后长度: {len(routed['content'])} 字符")
print(f"微工具已注册: {'call_002' in router.registry}")

# 场景 3：大型 JSON（> 32KB）—— 图谱化 + 微工具
large_json = {"users": [{"id": i, "name": f"user_{i}"} for i in range(1000)]}
routed = router.route_tool_result("call_003", large_json)
print(f"图谱摘要: {routed['content']}")

# 场景 4：大型文本（> 32KB）—— 摘要 + 微工具
large_text = "B" * 50_000
routed = router.route_tool_result("call_004", large_text)
print(f"摘要长度: {len(routed['content'])} 字符")

代码要点说明：

• route_tool_result 是核心路由方法，根据结果字节大小和类型分发到四种策略：PassThrough、Truncate、Graphify、Summarize。
• 任何被压缩的结果都会通过 _register_micro_tool 注册一个微工具，LLM 可随时调用 read_full_result_{call_id} 获取完整原始数据，实现信息零丢失。
• _smart_truncate 采用“头尾保留”策略，避免截断丢失关键上下文；_graphify 和 _summarize 为示意实现，生产环境可接入 LLM 或知识图谱引擎。

当上下文中的工具消息累积到一定数量（默认 10 条）时，ToolResultCompressor 会启动，对最旧的工具结果执行二次压缩：超过长度限制的，仅保留前几行并附加“已压缩”标记。

这一层是有损压缩的安全网，主要覆盖那些未被第一层充分处理的小结果累积情况。在实践中，由于第一层已将大结果截断到 2KB 左右，第二层真正触发压缩的概率很低——但它提供了一个兜底保障。

四、第三层：ContextWindowManager 全局控制

当前消息总数超过 30 条，或估算总 Token 超过 16000 时，ContextWindowManager 介入：

• 保留最近 4 条消息（包括 user/assistant/tool 配对）原样不动。
• 中间段消息用智能摘要替代：提取每轮的关键动作、涉及 IRI、工具调用次数等信息，生成结构化历史引用。
• 确保不拆散消息对：工具调用（assistant role）和工具结果（tool role）始终成对保留，避免孤儿消息导致 API 报错。

压缩后的历史引用示例：

[历史摘要]
 [轮1/PA] 制定分析计划 → iri://archive/task/xxx/turn_1
 [轮2/DA] 搜索认证接口 (grep×3) → iri://archive/task/xxx/turn_2
 [轮3/DA] 分析JWT流程 → iri://archive/task/xxx/turn_3
如需详细信息，请使用 kg_search / knowledge_query 查询 IRI。

LLM 可以清晰知道此前做过什么，并随时通过 IRI 检索任意轮次的完整详情。

五、智能回收：两阶段压缩优化

在第一层和第三层之间，我们引入了一个智能回收环节，形成完整的“准备—回收”闭环：

• 阶段一（准备）：ResultRouter 在 PassThrough 分支中，对大于 3KB 的结果预注册微工具。此时消息内容不变（仍为全文），但已具备“可回收”的条件。
• 阶段二（回收）：当 ContextWindowManager 或 ToolResultCompressor 触发压缩后，系统扫描 messages 中的所有 tool 消息，对于内容仍较大（>500 字节）且已有对应微工具的结果，将其替换为轻量引用：

[已压缩 10240 字节] 完整结果请调用 `read_full_result_call_abc` 工具
IRI: iri://tool-result/call_abc

原始内容已安全存储在 L0 中，LLM 只需调用微工具即可随时查看。上下文瞬间瘦身 98%，而信息零丢失。

六、流式与非流式路径统一

Gliding Horse 同时支持流式和非流式 LLM 调用，两条路径均完整实现了三层压缩：

• 非流式路径 (execution.rs)：每轮调完 LLM 后执行完整的 route_tool_result → ToolResultCompressor → ContextWindowManager 链路。
• 流式路径 (utils.rs)：同样在工具结果路由后执行压缩，ContextWindowManager 改为每 3 轮触发一次，以减少流式场景下的额外延迟。两条路径共享相同的 ResultRouter 和 ContextWindowManager 逻辑，压缩效果一致。

七、给平台带来的核心优势

整体上，单次任务的平均工具结果 Token 消耗降低 90% 以上，同时实现了 100% 的关键信息可追溯——因为每个被压缩的结果都有一个 IRI 和对应的微工具，Agent 永远不会真正“遗忘”。

八、结语

Gliding Horse 的工具结果压缩体系，本质上是一套信息无损的指针系统。它把“笨重”的原始数据留在图数据库和 L0 持久化层，只把轻量的“名片”（摘要 + IRI + 微工具）递进上下文。当 LLM 需要时，按图索骥即可精准取回。这套设计让 Agent 既能拥有海量的工作记忆，又不必为 Token 账单发愁，是让自主 Agent 走向长周期、高可靠的核心基础设施。

Gliding Horse 已在 GitHub 开源：https://github.com/doiito/gliding_horse