# 运行记录 UI 参考

当需要构建展示 agent-management 工作流执行进度或历史运行详情的前端页面/组件时，使用本参考。保留其内容、状态流转和信息层级；视觉设计则按目标产品自身风格适配。

如果用户提供了已部署的参考页面，可将其作为可选的内容与交互参考，而不是必须照搬的样式来源。

## 页面结构

采用面向执行的视图。对于管理/历史类页面，左右两栏的运行记录布局是较优的默认选择，但嵌入式或面向特定任务的集成不强制使用。

- 页面标题：`运行记录` 或目标应用中的等价文案。
- 浏览历史运行时需有运行选择区。
- 选中或当前运行的详情区。
- 没有运行或未选中运行时，展示清晰的空状态。
- 初始加载运行数据时，居中展示 loading spinner。

集成到目标应用时，遵循其既有约定，例如：

- API 封装或服务模块约定。
- 请求辅助封装、鉴权与错误处理约定。
- 既有的组件库与图标集。
- 既有的路由、状态管理、间距、排版与状态样式。

除非用户明确要求近似视觉，否则不要照搬原运行记录页样式。

## 工作流与运行选择

展示运行历史时，按工作流分组有助于用户查找历史执行：

- 工作流头部：折叠箭头、工作流图标、工作流名称和运行数量。
- 工作流标题下方可选地展示工作流标签（小 chip）。
- 运行条目：
  - 状态圆点
  - 短运行 ID，例如 `#a3f9b2c1`
  - 状态徽标
  - 启动时间
  - 完成时展示耗时
  - 删除操作仅出现在管理/历史页面，只读嵌入式视图不展示

常用交互：

- 工作流分组可折叠，默认展开。
- 点击运行会加载并选中其详情。
- 当前运行有明显的选中态。

对于纯实时执行视图，完整的历史列表是可选的；展示当前工作流/运行身份、实时状态与节点推进即可。

## 运行详情

运行详情头部：

- 状态圆点
- `运行 #<runId>`
- 状态徽标
- 启动时间
- 完成时间（如有）
- 耗时（如有）
- 运行级错误块（如存在）

随后按执行顺序渲染节点结果卡片、时间轴行或等价的区块。

页脚：

- 当工作空间下载可用时，提供 `下载工作空间`。
- 对外部 API 集成，使用 `workspace.downloadUrl` 或 `/api/v1/workflows/{workflowName}/runs/{runId}/workspace`。`{workflowName}` 是 kebab-case 唯一标识（推荐），纯数字 `id` 作为兼容兜底也合法。
- 下载作为二进制导航/blob 处理，不要按 JSON 处理。

## 节点类型映射

使用一致的节点标签。下方颜色与图标仅为示例，不是必须的样式：

| nodeType | 标签 | 颜色 | 图标建议 |
|---|---|---|---|
| `userInput` | `用户输入` | `#10B981` | 聊天/输入 |
| `llm` | `大模型` | `#8B5CF6` | 闪光 |
| `skill` | `技能` | `#06B6D4` | 烧瓶 |
| `agent` | `智能体` | `#F59E0B` | 火箭 |
| `smartAction` | `智能操作` | `#EC4899` | 魔杖 |
| `condition` | `条件` | `#F97316` | 分支 |
| `output` | `输出` | `#EF4444` | 出口/输出 |

节点区块行为：

- 展示标签、类型标签、日志数量（如可用）、状态，以及有日志时的展开控件。
- 点击头部或明确的控件可切换非思考日志的显隐。
- 若使用颜色/图标，需按节点类型保持一致，并与目标应用设计体系对齐。

## 状态映射

文案：

- `running` 或 `RUNNING`：`执行中`
- `success` 或 `SUCCESS`：`成功`
- `failed` 或 `FAILED`：`失败`
- `skipped` 或 `SKIPPED`：`跳过`
- 未知：`未知`

若使用 CSS 类，将状态归一化为小写，例如 `status-success`。

可选的状态色意图（当目标设计体系使用状态色时）：

- 执行中：蓝/紫强调
- 成功：绿
- 失败：红
- 跳过/未知：弱化灰

## 节点卡片内容

存在数据时渲染以下区块：

1. 输出变量
   - 必要时解析 JSON 对象输出。
   - 以紧凑的等宽样式展示键和值。
   - 对象/数组值用 `JSON.stringify(value, null, 2)` 美化输出。
   - 限制高度并对长值提供滚动。

2. 思考过程
   - 抽取所有 type 为 `THINKING` 的日志。
   - 按顺序拼接消息片段。
   - 在完整日志列表上方的高亮区块中展示。
   - 默认展开，除非用户折叠。
   - 展示近似字符数。

3. 上下文快照
   - 可选的调试区块。
   - 默认折叠，或放在明确的开关之后。
   - 以等宽格式展示键值对，并限制高度。

4. 错误
   - 按目标应用的标准错误呈现方式，在节点内联展示错误。

5. 非思考日志
   - 过滤掉 `THINKING` 日志，因为思考过程已在专属区块展示。
   - 将 `TOOL_CALL`、`TOOL_RESULT`、`INFO`、`ERROR` 保留在可折叠列表中。
   - 展示日志类型标签、消息及可选的详情。

## 辅助逻辑

实现以下辅助函数或等价物：

- `formatTime(t)`：兼容 ISO 字符串与 Spring/Java 的数组式日期数组。
- `duration(run)`：基于 started/completed 计算耗时；按秒、分秒或时分适配展示。
- `parseJson(str)`：成功返回解析后的对象，否则返回 `null`。
- `formatContextValue(value)`：对象/数组字符串化；字符串原样保留；基本类型字符串化。
- `extractThinking(logsJson)`：解析日志数组，拼接 `THINKING.message`。
- `nonThinkingLogs(logsJson)`：解析日志数组，过滤掉 `THINKING`。

对实时 SSE 视图，即便日志是以增量方式到达而非来自持久化 JSON，也应保持同样的派生数据形态。

## 实时 SSE 视图适配

当页面通过外部 API 展示正在运行的工作流时：

- `run_started`：初始化运行状态，标记为执行中。
- `node_status`：创建或更新节点卡片；存在时设置 status/output/error/completedAt。
- `node_stream` 且 `kind: "thinking"`：把内容追加到该节点的思考缓冲区。
- `node_stream` 且 `kind: "tool_call"` 或 `kind: "tool_result"`：追加到非思考日志。
- `workflow_complete`：标记运行成功，存储最终输出，暴露工作空间/结果链接。
- `workflow_error`：标记运行失败，展示错误与失败节点。

终态事件到达后，再查询持久化结果端点，对齐持久化输出、节点顺序、日志数量与工作空间元数据。

## 视觉规范

- 保持信息密度高的运维型 UI。除非目标产品显式使用，否则避免落地页/营销式排版。
- 运行条目与节点结果区块按目标设计体系，使用紧凑卡片、行、时间轴项或面板。
- 不要在卡片里再嵌套卡片。
- 圆点、徽标、图标与列表行使用稳定尺寸，避免布局抖动。
- 长文本要换行或可滚动；输出、思考或日志文本绝不可溢出容器。
- 在外部系统中，优先保证含义与工作流清晰度；视觉风格应贴合宿主应用。

## 验证清单

- 空、加载中、选中、执行中、成功、失败、无日志等状态均能正确渲染。
- 长思考流不会破坏布局。
- 大体量 JSON 输出可读且有边界约束。
- 工具日志可展开，且不与思考文本重复。
- 工作空间下载可正常工作，不触发 JSON 拦截器错误。
- 移动端或窄屏下，状态徽标、运行 ID 或节点头部不会重叠。
