Coze Studio 工作流测试运行 Trace 面板：@coze-workflow/test-run-trace 包深度解析

Coze Studio 工作流测试运行 Trace 面板：@coze-workflow/test-run-trace 包深度解析

【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio

Coze Studio（coze-studio）是一个"开箱即用"的 AI Agent 开发平台，其前端工作流模块提供了可视化的 Agent 编排、调试与部署能力。本文围绕工作流测试运行（TestRun）子模块中的@coze-workflow/test-run-trace包，深入讲解其在工作流调试中承担的角色：以 Trace 列表 + 详情双面板的方式，将一次工作流运行产生的节点级 Span 观测数据（输入、输出、耗时、Token 消耗、状态码等）可视化呈现，帮助开发者快速定位节点执行问题。读完本文，你将掌握该包的导出 API、组件结构与调用链，并理解如何在自己的工作流调试场景中接入与复用这两个面板组件。

包定位：工作流 TestRun 链路中的 Trace 观测层

在 frontend/packages/workflow/test-run-next/trace/package.json 中，该包被描述为Workflow TestRun Form（工作流测试运行表单），版本0.0.1，是 Coze Studio monorepo 中test-run-next系列的一部分。它依赖同仓的 @coze-workflow/test-run-shared（提供BottomPanel等共享面板组件）与 @coze-workflow/base，并通过@coze-arch/bot-api获取工作流运行时的 Trace/Span 数据结构定义。

从命名与代码结构看，该包对应工作流测试运行底栏（Bottom Panel）中的"运行记录 / Trace"视图，核心职责是：

• 将一次测试运行的完整执行轨迹（Trace）以节点列表/表格形式呈现；
• 支持按状态、时间等条件筛选历史运行记录；
• 点击某条记录后可下钻查看单个节点（Span）的输入、输出、延迟、Token 消耗与状态详情；
• 支持从 Trace 详情一键"定位到节点"（Goto Node），回到画布对应节点位置。

包根目录的 src/index.ts 是唯一对外出口，仅导出两个组件：

export { TraceListPanel } from './components/trace-list-panel'; export { TraceDetailPanel } from './components/trace-detail-panel';

安装与接入

安装方式

由于 Coze Studio 前端采用 rush.json 组织的 pnpm monorepo 工作区，包之间通过workspace:*协议互相引用。按 README.md 的说明，在目标包（例如 test-run 主面板）的package.json中添加依赖：

{ "dependencies": { "@coze-workflow/test-run-trace": "workspace:*" } }

然后执行依赖安装与更新：

rush update

如果希望锁定某个版本，可参考该包自身的 package.json 中的exports与main字段（均指向./src/index.ts），即直接以 TypeScript 源码形式对外提供，无需单独构建产物。

基础用法

在组件中导入并组合两个面板：

import { TraceListPanel, TraceDetailPanel } from '@coze-workflow/test-run-trace'; import type { TraceFrontendSpan } from '@coze-arch/bot-api/workflow_api'; import type { GotoParams } from '@coze-workflow/test-run-trace/src/types'; // 列表面板：挂在测试运行底栏 <TraceListPanel spaceId={spaceId} workflowId={workflowId} maxHeight={600} isInOp={false} onOpenDetail={(span: TraceFrontendSpan) => setSelectedSpan(span)} onGotoNode={(params: GotoParams) => jumpToCanvasNode(params)} onClose={() => setShowTrace(false)} /> // 详情面板：用户点击列表项后展示 {selectedSpan && ( <TraceDetailPanel span={selectedSpan} onClose={() => setSelectedSpan(null)} onGotoNode={(params: GotoParams) => jumpToCanvasNode(params)} /> )}

组件 API 详解

TraceListPanel：运行记录列表

定义见 list-panel.tsx：

实现上，TraceListPanel使用 @coze-workflow/test-run-shared 提供的BottomPanel作为底栏容器，默认高度 300px，支持min: 300、max: maxHeight的拖拽调整；头部由TraceListPanelHeader渲染（包含筛选、刷新等操作），主体由TraceGraph负责 Trace 数据的图形化渲染，并用TraceListProvider注入运行上下文。

TraceDetailPanel：节点运行详情

定义见 trace-detail-panel.tsx：

详情面板从上到下依次渲染：节点名称（span.alias_name）、状态标签（StatusTag，依据span.status_code渲染成功/失败/运行中状态）、"定位节点"按钮（FocusButton）、延迟与 Token 消耗摘要（PayBlocks）、可一键复制的LogId（span.log_id），以及节点输入（INPUT）与输出（OUTPUT）的 JSON 查看器（基于@textea/json-viewer，并关闭了displayDataTypes）。

支撑类型 GotoParams

定义见 types.ts，用于"从 Trace 定位回画布节点"：

export interface GotoParams { nodeId: string; // 画布节点 ID workflowId: string; // 工作流 ID executeId: string; // 执行实例 ID subExecuteId: string; // 子执行实例 ID（嵌套/子工作流场景） }

关键实现：Span 数据解析工具

utils.ts 集中了 Trace 数据的解析逻辑，是整个面板的"数据解码层"，与后端下发的 Span 结构强耦合：

• sortSpans(spans)：按span_id去重，并按start_time升序排序，保证列表顺序即执行时序；
• getTimeFromSpan(span)：将span.start_time格式化为YYYY-MM-DD HH:mm:ss；
• isTriggerFromSpan(span)：从tags中查找is_trigger标签，用于识别触发源节点；
• getStrFromSpan(span, key)/getLongFromSpan(span, key)：从span.tags键值数组中按 key 取值（字符串 / 长整型）；
• getTokensFromSpan(span)：读取tokens标签，用于在详情面板展示 LLM Token 消耗；
• formatDuration(time)：毫秒级时长格式化，依次输出ms/s/min/h/d；
• getGotoNodeParams(span)：从 Span 的workflow_id、workflow_node_id、execute_id、sub_execute_id四个标签组装GotoParams，供"定位到节点"使用。

这些 tag 取值逻辑与后端 Trace 数据模型（@coze-arch/bot-api中的workflow_api类型，含Span、Int64、TraceFrontendSpan）一一对应，是前后端观测数据契约在前端的落点。

状态管理：基于 zustand 的 TraceListProvider

contexts/trace-list/index.tsx 使用 zustand（createWithEqualityFn+shallow比较）创建TraceListStore，管理三个核心状态：

export interface TraceListState { spaceId: string; // 空间 ID workflowId: string; // 工作流 ID isInOp?: boolean; // 是否 OP 场景 /** 首次打开时先请求列表，再默认选中第一条 */ ready: boolean; /** 当前选中的 span */ span: Span | null; }

并通过patch(next)action 统一更新状态。TraceListProvider用useMemo依据spaceId / workflowId / isInOp创建 store 实例，useTraceListStore(selector)提供带 selector 的访问方式，避免无关状态变更引起重渲染。

观测组件体系：Trace 可视化的支撑层

observation-components 是 trace 包内部的"观测组件库"，按目录可分为四类：

• trace-graph（列表图）：graph.tsx 与 table.tsx 提供"表格式 Trace 列表"与"火焰线程式（FlameThread）"两种图表模式；use-trace.ts 负责拉取与聚合 Trace 数据；
• flamethread（火焰图）：基于@visactor/vgrammar0.12.5-alpha.4 渲染的火焰线程视图，用于直观展示各节点的时间开销与嵌套调用关系；
• trace-tree（树视图）：以树形结构呈现 Span 的父子调用链，支持在树与图之间联动；
• message-panel / custom-json-viewer：统一的输入输出 JSON 查看器，详情面板的 INPUT/OUTPUT 展示即复用了它，并通过i18nMapping注入"节点输入/节点输出"的国际化标题。

此外，observation-components/assets/graph/span-type 目录下按 Span 类型提供了一整套 SVG 图标（icon-agent、icon-llm-call、icon-knowledge、icon-plugin-tool、icon-condition、icon-code、icon-database、icon-workflow-start、icon-workflow-end等），用于在图中区分不同类型的节点。

常量约束与运行限制

constants.ts 定义了 Trace 查询的两条硬约束：

export enum TraceChartsMode { Table, // 表格模式 FlameThread, // 火焰线程模式 } /** Log query for up to 50 records */ export const MAX_TRACE_LENGTH = 50; /** Log query for up to 7 days */ export const MAX_TRACE_TIME = 7;

即 Trace 列表最多拉取最近 50 条运行记录，时间窗口最多回溯 7 天。这两个常量应在 UI 上同步体现（例如日期选择器的可选范围、列表分页上限），避免出现"选到了第 8 天却查不到数据"的困惑。

开发与工程配置

按 README.md 的 Development 小节，该包使用 TypeScript 5.x + React 18.2 构建，质量工具链包括 ESLint（eslint.config.js，基于@coze-arch/eslint-config）与 Vitest。当前 package.json 的build/test脚本为占位实现（exit 0），即该包暂以源码形式被消费、不产出独立构建物。

总结

@coze-workflow/test-run-trace是 Coze Studio 工作流 TestRun 底栏中的 Trace 观测模块，通过TraceListPanel（运行记录列表，支持表格/火焰线程双模式）与TraceDetailPanel（单节点输入输出、延迟、Token、状态详情）两个对外组件，把后端下发的 Span 级观测数据转化为可筛选、可下钻、可回溯（最多 50 条 / 7 天）的可视化面板，并支持从 Trace 一键定位回画布节点。其内部以 zustand 管理选中状态、以工具函数集中解析 Span tags、以独立的 observation-components 目录支撑树/火焰图/JSON 查看器等多种观测视图，是理解 Coze Studio 工作流调试观测体系的最佳入口之一。若需二次开发，可从 src/index.ts 出发，沿组件 → 数据解析（utils.ts）→ 状态管理（contexts/trace-list/index.tsx）→ 观测组件（observation-components）逐层深入。

【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio