ACP Transcript Sync

ACP 子会话内容自动回写主会话。当 spawn ACP 子 agent（cfuse/claude code/codex/gemini cli 等）完成任务后，将子会话的 transcript 回写到主会话 transcript 文件，使 AIMA 等平台能通过采集主会话看到子 agent 的完整推理过程。触发场景：(1) spawn ACP 子会话后需要回写内容到主会话，(2) 需要让 AIMA 平台采集到子 agent 的工作记录，(3) 将 ACP 子会话内容合并到主会话以保持完整链路。关键词：ACP回写、子会话回写、transcript同步、ACP sync、回写主会话、子agent内容同步、AIMA采集。

ACP 子会话完成后，将子会话内容回写到主会话 transcript，让 AIMA 平台能通过采集主会话看到完整链路。

标准流程

1. Spawn ACP 子会话

sessions_spawn({ runtime: "acp", agentId: "<agentId>", task: "<任务描述>" })

记录返回的 childSessionKey 和完成后的 session_id。

2. 等待子会话完成

子会话完成后会自动推送完成通知。收到通知后执行回写。

3. 执行回写脚本

python3 <skill-dir>/scripts/sync-acp-to-main.py <acp_session_id> <acp_agent> [<main_session_id>] [<main_agent>]

参数说明：

参数	必填	说明
acp_session_id	✅	ACP 子会话的 UUID（从完成通知或 sessions_list 获取）
acp_agent	✅	ACP agent 的 ID，如 cfuse、claude、codex
main_session_id	❌	主会话 UUID，不传则自动找最新的主会话
main_agent	❌	主 agent ID，不传则自动检测

示例：

# 指定所有参数
python3 scripts/sync-acp-to-main.py f935963c-b8dd-431c-9d85-85e0e5a41341 cfuse 44c3f987-f9ad-4a02-b107-768ae9f517d3

# 自动检测主会话和主 agent
python3 scripts/sync-acp-to-main.py f935963c-b8dd-431c-9d85-85e0e5a41341 cfuse

4. 验证回写

# 查看主会话最后几条消息
tail -5 ~/.openclaw/agents/<main_agent>/sessions/<main_session_id>.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    d = json.loads(line)
    if d.get('type') == 'message':
        msg = d.get('message', {})
        content = msg.get('content', [])
        text = ''.join(c.get('text','') for c in content if c.get('type')=='text')
        print(f'[{msg.get(\"role\")}] {text[:100]}')
"

回写格式

回写内容以 [xxx推理过程] 为前缀标识来源，xxx 是具体的 agent 名称：

• 📋 cfuse推理过程 — 标记消息
• [cfuse推理过程] user — 子会话中的用户输入
• [cfuse推理过程] assistant — 子会话中 agent 的回复

不同 agent 示例：

• cfuse → [cfuse推理过程]
• claude code → [claude code推理过程]
• codex → [codex推理过程]

获取 sessionId 的方法

子会话完成后需要获取其 sessionId，有三种方式：

1. 完成通知：子会话完成后 OpenClaw 会推送完成事件，其中包含 session_id
2. sessions_list：sessions_list({ label: "acp" }) 过滤 ACP 会话
3. subagents：subagents({ action: "list" }) 查看子会话状态和 sessionKey

从 sessionKey（格式 agent:<agentId>:acp:<uuid>）中，实际的 transcript 文件名（sessionId）可能不同于 key 中的 uuid。需要通过 sessions_list 获取 sessionId 字段。

完整自动化模式

将回写步骤集成到 spawn 流程中：

1. sessions_spawn({ runtime: "acp", agentId: "cfuse", task: "..." })
2. 等待完成通知
3. 从通知中提取 session_id 和 agentId
4. exec 执行回写脚本
5. 完成

关键规则：每次 spawn ACP 子会话后，必须执行回写，否则 AIMA 平台无法采集子会话内容。

故障排查

问题	原因	解决
ACP 子会话不存在	sessionId 错误或 transcript 已被清理	检查 sessionId，确认文件存在
主会话为空	主会话 transcript 文件无消息	检查 main_session_id 是否正确
ACP 子会话没有有效消息	子会话未产生有效输出	检查子会话是否真的执行了任务
回写后 AIMA 看不到	AIMA 尚未重新采集	等待 AIMA 下次采集周期