看见AI工作流的每一步acpx replay-viewer回放可视化完整指南【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpxacpx 是一个面向 Agent Client ProtocolACP的无头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.mdrun-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 的一次真实运行。常见疑问 FAQQviewer 会重新执行我的 flow 吗不会。它是只读回放工具只读取已保存的 bundle。Qbundle 里的会话数据从哪里来每次运行都会把用到的 ACP 会话完整复制进sessions/目录回放不依赖全局会话存储bundle 自带即可离线复盘。Qviewer 端口被占用会怎样不会报错换端口。固定 4173 端口已有实例会被直接复用。延伸阅读回放数据格式规范docs/2026-03-26-acpx-flow-trace-replay.mdviewer 界面语义与布局规则docs/2026-03-27-flow-replay-viewer.md实时传输与状态同步模型docs/2026-03-31-flow-replay-live-transport.mdflow 使用指南docs/flows.mdviewer 源码目录examples/flows/replay-viewer/跑一次 flow再pnpm viewer打开浏览器——从此你的 AI 工作流每一步都有据可查。【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考