看见AI工作流的每一步：acpx replay-viewer回放可视化完整指南-二趣网

看见AI工作流的每一步：acpx replay-viewer回放可视化完整指南

【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpx

acpx 是一个面向 Agent Client Protocol（ACP）的无头（headless）命令行客户端，而它的 replay-viewer 回放可视化工具，能让你把 AI 工作流的每一次运行变成一部可倒放、可拖动时间轴的"录像"——每一步节点、每一轮 ACP 会话、每一次工具调用，全都看得见。🎬

replay-viewer 能帮你做什么？

当你用acpx flow run跑完一个多步骤 AI 工作流后，replay-viewer 会把保存下来的运行记录（run bundle）渲染成浏览器里的可视化界面：

🗺️完整流程图：用 React Flow 绘制工作流定义图，每个节点带状态标记
🕒时间线回放：像播放器一样播放、暂停、快进、倒放整个运行过程
💬会话检查：查看每个 ACP 步骤对应的完整对话（用户消息、Agent 回复、工具调用与结果）
📡实时更新：正在运行中的工作流会通过 WebSocket 实时推送进展，无需手动刷新
🗂️最近运行列表：左侧栏自动列出~/.acpx/flows/runs/下的历史运行记录

replay-viewer 是只读的：它只回放已保存的 bundle，不会重新执行工作流，可以放心用来复盘和排查问题。

三步启动 acpx replay-viewer（最快上手方法）

前提：已安装 Node.js 22.13+ 和 pnpm。

第 1 步：获取源码

git clone https://gitcode.com/gh_mirrors/ac/acpx cd acpx

第 2 步：安装依赖

pnpm install --frozen-lockfile

第 3 步：启动回放查看器

pnpm viewer

然后打开浏览器访问http://127.0.0.1:4173即可。viewer 固定使用 4173 端口，如果已有实例在运行，命令会直接复用它，而不会跳到随机端口。

配套的管理命令也很方便：

命令	作用
`pnpm viewer:open`	启动并自动打开浏览器
`pnpm viewer:status`	查看 viewer 运行状态
`pnpm viewer:stop`	停止 viewer 服务

这些脚本定义在 package.json 中。详细说明可参考 examples/flows/replay-viewer/README.md。

💡提示：如果启动时还没有任何运行记录，左侧栏会保持空白并等待第一条真实运行出现，而不是展示演示数据。之后新产生的运行会自动出现在侧边栏中。

先跑一个 flow，才能看到回放数据

replay-viewer 的数据来源是 flow 运行产生的 bundle。先用一条命令生成一次运行：

acpx flow run examples/flows/echo.flow.ts \ --input-json '{"request":"Summarize this repo in one sentence."}'

运行过程中，acpx 会把每一步的图状态、ACP 会话记录、工具输出等实时持久化到~/.acpx/flows/runs/<runId>/。运行结束后，这个 bundle 即为不可变（immutable），也就是回放可视化要读取的输入。更多示例见 docs/flows.md 的 "Practical examples" 部分，以及内置示例 two-turn.flow.ts 和 pr-triage.flow.ts。

看懂回放图：定义 + 运行叠加层

打开某个运行后，主区域是一张自上而下布局的流程图。理解它的关键在于两层语义：

底层：完整的 flow 定义图——展示工作流"可以走哪些路"，包括起点、分支、循环、终点，即使某条分支这次没走到，也会保持可见；
叠加层：本次实际运行——高亮显示实际访问过的节点、访问顺序、当前选中的尝试（attempt），以及运行真正停止或完成的位置。

图中会明确区分 5 种节点类型（见 docs/flows.md 的 Node types 表）：

节点	含义
`acp`	模型驱动的步骤，对 Agent 会话执行一次 ACP 对话轮次
`action`	确定性运行时步骤，通常是 shell 命令或 HTTP 调用
`compute`	纯本地函数，用于整形数据、路由、格式化
`decision`	带约束选项的 ACP 分支，实现类型化路由
`checkpoint`	需要运行时外部条件（如人工审核）的暂停点

一个重要的细节：回放位置 ≠ 运行结果。时间轴停在第 N 步，绝不意味着运行成功了；真实的运行结果（completed/failed/timed_out/waiting/running）会单独显示在回放控件上。这个设计的完整规则见 docs/2026-03-27-flow-replay-viewer.md。

逐步回放：像放视频一样拖动时间轴

底部是一排媒体播放器风格的控件，支持：

▶️ 播放 / ⏸ 暂停
⏮ 上一步 / ⏭ 下一步 / 跳到开头 / 跳到最新
🖱️可拖动的 scrubber（进度条）：拖动时预览连续播放位置，松手后自动吸附到最近的一步

回放以"尝试"（attempt）为单位推进，界面会显示Attempt N of M和当前节点。播放时还会带来两个很讨喜的效果：

AI 回复渐进显示：Agent 的文本随播放头逐步"打字"呈现，而不是整段突然出现；工具调用和结果则在播放头到达相应位置时出现；
镜头跟随：默认follow模式下，视图会平滑地跟随当前活跃节点移动；切换到overview模式则可鸟瞰整张定义图。

暂停时，右侧检查器面板会精确展示该步骤的完整状态。面板默认是ACP 会话标签页，以对话形式呈现用户消息、Agent 消息、工具调用与结果（工具输出默认折叠为一行，原始数据藏在展开控件后面），当前回放对应的会话切片会用色条高亮。

键盘党福利：聚焦 scrubber 后，←/↓选中上一个 attempt，→/↑选中下一个，每次按键都会停在完整的记录步上。

实时观看：正在跑的 AI 工作流也能看

replay-viewer 不只是"事后回放"。当某次运行还在进行中时：

侧边栏会实时显示它的running状态和当前节点
选中该运行后，新的步骤、追踪事件、流式 ACP 文本会通过WebSocket + JSON Patch+持续推送到浏览器
即使你倒放（rewind）到历史步骤，新数据继续到达也不会把你"拽回"最新位置——时间轴会变长，但你的停留点保持不变

这套"快照 + 增量补丁"的实时同步模型有专门的设计文档，可阅读 docs/2026-03-31-flow-replay-live-transport.md。

run bundle 内部结构速览

想深入理解回放数据从哪来，看看 bundle 的文件布局（规范见 docs/2026-03-26-acpx-flow-trace-replay.md）：

<run-id>/ manifest.json # 版本化索引与文件映射，回放的唯一入口 flow.json # 实际运行的 flow 结构快照 trace.ndjson # 只追加的事件日志——事实来源 projections/ run.json # 最新完整运行快照 live.json # 最新存活状态快照 steps.json # 有序的步骤尝试收据 sessions/ <session-id>/ binding.json # 会话绑定元数据 record.json # 规范化会话记录快照 events.ndjson # 该会话的原始 ACP 事件流 artifacts/ sha256-<digest>.* # 内容寻址的不可变大文件（prompt、原始输出等）

三层模型一句话总结：追加式 trace 是事实来源，projections 是派生视图，artifacts 存放大负载。仓库里还内置了一个可直接查看的样例 bundle，其入口文件是 manifest.json，它来自 two-turn.flow.ts 的一次真实运行。

常见疑问 FAQ

Q：viewer 会重新执行我的 flow 吗？不会。它是只读回放工具，只读取已保存的 bundle。

Q：bundle 里的会话数据从哪里来？每次运行都会把用到的 ACP 会话完整复制进sessions/目录，回放不依赖全局会话存储，bundle 自带即可离线复盘。

Q：viewer 端口被占用会怎样？不会报错换端口。固定 4173 端口，已有实例会被直接复用。

企业官网建设流程全解析