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-studioCoze Studiocoze-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.tsxProps类型说明spaceIdstring空间 ID用于请求 Trace 列表数据的上下文隔离workflowIdstring工作流 IDTrace 查询的主键maxHeightnumber底栏面板可拖拽调整的最大高度isInOp?boolean是否处于 OP运营/线上观测场景影响数据来源与展示onOpenDetail(span: TraceFrontendSpan) void点击某条 Trace 记录时回调把选中 Span 传给详情面板onGotoNode(params: GotoParams) void从列表定位到节点时回调onClose() void关闭底栏时回调实现上TraceListPanel使用 coze-workflow/test-run-shared 提供的BottomPanel作为底栏容器默认高度 300px支持min: 300、max: maxHeight的拖拽调整头部由TraceListPanelHeader渲染包含筛选、刷新等操作主体由TraceGraph负责 Trace 数据的图形化渲染并用TraceListProvider注入运行上下文。TraceDetailPanel节点运行详情定义见 trace-detail-panel.tsxProps类型说明spanTraceFrontendSpan待展示的单个节点运行数据onClose() void关闭详情面板onGotoNode(params: GotoParams) void点击定位到节点按钮时回调详情面板从上到下依次渲染节点名称span.alias_name、状态标签StatusTag依据span.status_code渲染成功/失败/运行中状态、定位节点按钮FocusButton、延迟与 Token 消耗摘要PayBlocks、可一键复制的LogIdspan.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:ssisTriggerFromSpan(span)从tags中查找is_trigger标签用于识别触发源节点getStrFromSpan(span, key)/getLongFromSpan(span, key)从span.tags键值数组中按 key 取值字符串 / 长整型getTokensFromSpan(span)读取tokens标签用于在详情面板展示 LLM Token 消耗formatDuration(time)毫秒级时长格式化依次输出ms/s/min/h/dgetGotoNodeParams(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 的 TraceListProvidercontexts/trace-list/index.tsx 使用 zustandcreateWithEqualityFnshallow比较创建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 构建质量工具链包括 ESLinteslint.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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-studioCoze Studiocoze-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.tsxProps类型说明spaceIdstring空间 ID用于请求 Trace 列表数据的上下文隔离workflowIdstring工作流 IDTrace 查询的主键maxHeightnumber底栏面板可拖拽调整的最大高度isInOp?boolean是否处于 OP运营/线上观测场景影响数据来源与展示onOpenDetail(span: TraceFrontendSpan) void点击某条 Trace 记录时回调把选中 Span 传给详情面板onGotoNode(params: GotoParams) void从列表定位到节点时回调onClose() void关闭底栏时回调实现上TraceListPanel使用 coze-workflow/test-run-shared 提供的BottomPanel作为底栏容器默认高度 300px支持min: 300、max: maxHeight的拖拽调整头部由TraceListPanelHeader渲染包含筛选、刷新等操作主体由TraceGraph负责 Trace 数据的图形化渲染并用TraceListProvider注入运行上下文。TraceDetailPanel节点运行详情定义见 trace-detail-panel.tsxProps类型说明spanTraceFrontendSpan待展示的单个节点运行数据onClose() void关闭详情面板onGotoNode(params: GotoParams) void点击定位到节点按钮时回调详情面板从上到下依次渲染节点名称span.alias_name、状态标签StatusTag依据span.status_code渲染成功/失败/运行中状态、定位节点按钮FocusButton、延迟与 Token 消耗摘要PayBlocks、可一键复制的LogIdspan.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:ssisTriggerFromSpan(span)从tags中查找is_trigger标签用于识别触发源节点getStrFromSpan(span, key)/getLongFromSpan(span, key)从span.tags键值数组中按 key 取值字符串 / 长整型getTokensFromSpan(span)读取tokens标签用于在详情面板展示 LLM Token 消耗formatDuration(time)毫秒级时长格式化依次输出ms/s/min/h/dgetGotoNodeParams(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 的 TraceListProvidercontexts/trace-list/index.tsx 使用 zustandcreateWithEqualityFnshallow比较创建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 构建质量工具链包括 ESLinteslint.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考