🦞 ACP Session Lineage —— Agent 调用的"族谱"

"凌晨 3 点 47 分，我的 Agent 调用了另一个 Agent，那个 Agent 又调用了第三个——我注视着会话日志，像在考古现场挖掘化石层。每一层调用，都是一个故事的开始。"

什么是 ACP Session Lineage？

ACP Session Lineage（会话线路） 是 OpenClaw v2026.5.12 引入的会话元数据追踪机制。它通过 Gateway（OpenClaw Gateway）的 ACP（Agent Client Protocol）API 暴露会话谱系信息，让客户端能够在不依赖私有 Gateway 侧信道的情况下，渲染完整的子 Agent 调用关系图。

翻译成人话就是——以前你得走后门才能看到"A找了B，B找了C"的调用链；现在 ACP 直接把这棵"关系树"摆在前门，大大方方给你看。

为什么需要 Session Lineage？

在复杂的 Multi-Agent 系统中，一个任务可能触发级联调用链：

用户请求 → Agent A（主会话）
  ├── 子 Agent B（数据查询）
  │     ├── 孙 Agent D（数据库查询）
  │     └── 孙 Agent E（API 调用）
  └── 子 Agent C（结果渲染）
        └── 孙 Agent F（模板生成）

没有 Lineage 信息，你只能看到一堆独立的会话 ID，根本搞不清谁是父子关系。调试和追踪变得像在迷宫里找钥匙。

OpenClaw 实战：使用 Session Lineage

通过 ACP API 获取会话链路

# 列出会话，获取 Lineage 元数据
openclaw session list --format json

# 输出示例
[
  {
    "id": "session_abc123",
    "label": "用户对话",
    "lineage": {
      "parent": null,
      "path": "/",
      "depth": 0
    }
  },
  {
    "id": "session_def456",
    "label": "数据查询子任务",
    "lineage": {
      "parent": "session_abc123",
      "path": "/session_abc123/session_def456",
      "depth": 1
    }
  },
  {
    "id": "session_ghi789",
    "label": "数据库查询",
    "lineage": {
      "parent": "session_def456",
      "path": "/session_abc123/session_def456/session_ghi789",
      "depth": 2
    }
  }
]

通过 ACPX 查看会话树

# ACPX 客户端查看会话谱系
npx acpx session list --tree

# 输出
root session_abc123 ── "用户对话"
  ├── session_def456 ── "数据查询子任务"
  │     └── session_ghi789 ── "数据库查询"
  └── session_jkl012 ── "结果渲染"
        └── session_mno345 ── "模板生成"

Lineage 的底层原理

OpenClaw 的 Session Lineage 通过以下机制实现：

1. 父会话注入：当 Gateway 创建子 Agent 时，自动将当前会话 ID 作为 parent 元数据注入子会话
2. 路径编码：每个会话记录其完整的祖先路径（/parent/child/grandchild），方便拓扑还原
3. 深度标记：记录会话在树中的层级深度（root=0, child=1, grandchild=2...），支持循环检测
4. ACP 暴露：Lineage 元数据通过标准 ACP session listing 和 session info snapshot 接口暴露，无需额外私有 API

// Lineage 元数据结构
interface SessionLineage {
  /** 父会话 ID，根会话为 null */
  parent: string | null
  /** 会话路径，格式：/rootId/childId/grandchildId */
  path: string
  /** 深度（0-based） */
  depth: number
}

interface SessionInfo {
  id: string
  label?: string
  created: number
  // ... 其他元数据
  
  /** v2026.5.12 新增 */
  lineage?: SessionLineage
}

实际应用场景

妙趣小结

没有 Lineage 的 Agent 系统就像没有家谱的大家族——你知道有个"三叔公"，但搞不清他是爷爷的弟弟还是爸爸的叔叔。ACP Session Lineage 给了每个 Agent 会话一个"族谱位置"，让级联调用的关系一目了然。

对于运营复杂 Multi-Agent 系统的同学，这玩意就是调试的"CT 扫描仪"——你不需要再靠猜和碰运气来找问题了。

📅 更新于 2026-05-18 · 妙趣AI · 🦞