【Agent Harness】Gliding Horse 工具结果压缩体系：如何用“指针”驯服上下文膨胀
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 随时通过微工具查询完整细节的能力。信息不丢失，上下文不爆炸。
一、三层压缩架构：纵深防御
流马的工具结果管理分为三个层次，在结果注入上下文的不同阶段递进式压缩：
- 第一层 (ResultRouter)：结果进入上下文之前，根据大小和类型自动选择处理策略——小结果原样放行，大结果截断或图谱化，并注册微工具供 LLM 按需查询。
- 第二层 (ToolResultCompressor)：在上下文已有压力时，对 message 列表中的旧工具结果做二次摘要压缩，作为兜底安全网。
- 第三层 (ContextWindowManager)：当消息总数或估算 Token 超过硬上限时，对整个消息序列进行结构化压缩，保留最近关键信息，中间段用摘要替代。
三层相互配合，既保证了单条结果不撑爆上下文，又防止了多次小结果累积膨胀。
二、第一层：ResultRouter 的智能路由
ResultRouter 是整个压缩体系的核心防线。它在工具结果返回后、注入 messages 前工作，能够访问 L0 存储和 ToolExecutor，拥有完整上下文。
关键机制：
-
Micro-tool 模式：任何被压缩或截断的结果，系统都会自动注册一个专用微工具（如
read_full_result_{call_id}），LLM 可以随时调用它来获取完整原始数据。信息零丢失。 -
PassThrough 增强：即使结果小于 16KB 原样放行，只要超过 3KB，系统也会预注册微工具。这为后续的“智能回收”埋下伏笔——当上下文压力增大时，这些较大的 PassThrough 结果可以被替换为轻量引用，而不丢失可回溯性。
-
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 或知识图谱引擎。
三、第二层：ToolResultCompressor 安全网
当上下文中的工具消息累积到一定数量（默认 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逻辑，压缩效果一致。
七、给平台带来的核心优势
| 指标 | 优化前 | 优化后 | 说明 |
|---|---|---|---|
| 单次 grep 搜索 (15KB) | 15KB 原文注入 | ~200 字节摘要 + IRI | 缩减 98.7% |
| 10 次 bash 命令 (各 10KB) | 100KB 累积，压缩后丢失信息 | 10 条引用 + 微工具，可查询全文 | 信息零丢失 |
| 大型 JSON (50KB) 结果 | 截断或硬丢弃 | 图谱摘要 + 微工具，结构可探索 | 语义不丢失 |
| 长对话 (>30 轮) | 超过限制被截断，前文丢失 | 历史结构化引用，IRI 可回溯 | 关键决策链完整 |
整体上，单次任务的平均工具结果 Token 消耗降低 90% 以上，同时实现了 100% 的关键信息可追溯——因为每个被压缩的结果都有一个 IRI 和对应的微工具，Agent 永远不会真正“遗忘”。
八、结语
Gliding Horse 的工具结果压缩体系，本质上是一套信息无损的指针系统。它把“笨重”的原始数据留在图数据库和 L0 持久化层，只把轻量的“名片”（摘要 + IRI + 微工具）递进上下文。当 LLM 需要时，按图索骥即可精准取回。这套设计让 Agent 既能拥有海量的工作记忆，又不必为 Token 账单发愁，是让自主 Agent 走向长周期、高可靠的核心基础设施。
Gliding Horse 已在 GitHub 开源：https://github.com/doiito/gliding_horse
浙公网安备 33010602011771号