# 平台前端实现源码（表现完全一致的参考实现）

本目录是 agent-management 前端「运行展示」相关源码的**自包含副本**，用于让业务方前端与平台自有的运行体验完全一致——视觉（`nrc-*` / `vc-*` / `md-body` 类名与配色）、交互（折叠策略、multi-visit、AskFor、断线重连）、数据聚合逻辑（`visitUuid` 路由、8 种 `node_stream.kind` 分流）均以这里的代码为准。

与上级目录 `../js-implementation.md`（按契约手写的框架无关简化参考）的分工：

| 场景 | 用哪个 |
|---|---|
| 快速理解契约、非 Vue 技术栈、允许交互近似 | `../js-implementation.md` |
| Vue 3 项目、要求与平台表现**完全一致** | **本目录**（直接拷贝使用） |
| 接口契约与错误码 | `../external-workflow-api.md` |
| 展示规范（六面板/折叠/multi-visit 的文字定义） | `../run-history-ui.md` |

## 文件清单

| 本目录文件 | 平台源码位置（`frontend/src/` 下） | 说明 |
|---|---|---|
| `api/workflow.js` | —（适配版，非复制） | **外部 `/api/v1` 客户端**，函数签名与内部版一致，`useWorkflowRunner` 零改动可用 |
| `api/workflow.internal.js` | `api/workflow.js` | 平台内部版留档，供对照排查 |
| `api/runHistory.js` | `api/runHistory.js` | 历史列表/详情/删除（内部 API，见下文「RunHistory 的内部 API 依赖」） |
| `composables/useWorkflowRunner.js` | `composables/useWorkflowRunner.js` | **核心数据层**：SSE 解析、事件分发、Visit 聚合、迭代式重连（5 次 × 3s → 30s 轮询降级）、AskFor 提交 |
| `utils/visitChain.js` | `utils/visitChain.js` | 回放 Visit 卡片构建（`outputJson`/`variablesJson`/`decisionJson`/`logsJson` 反序列化） |
| `utils/runResultReplay.js` | `utils/runResultReplay.js` | 持久化日志 → 六面板还原（thinking 拼接、工具顺序配对、最新 todos） |
| `utils/markdown.js` | `utils/markdown.js` | Marked 单例 + 代码高亮 + KaTeX + DOMPurify |
| `utils/hermesThinking.js` | `utils/hermesThinking.js` | Hermes 思考流装饰过滤（颜文字/前缀剥离） |
| `utils/logLabels.js` | `utils/logLabels.js` | 10 种日志类型的中文标签与归类 |
| `utils/request.js` | `utils/request.js` | axios 实例（仅 `api/runHistory.js` 使用） |
| `components/agent-thinking/*.vue`（6 个） | 同路径 | 六面板组件：`AgentThinkingPanel`（容器）、`ThinkingLive`（实时状态）、`ToolCalls`、`TodoListPanel`、`AskforPanel`、`RunReconnectBadge` |
| `styles/hljs-theme.css` | `styles/hljs-theme.css` | highlight.js 深色主题 + `pre` 滚动条美化 |
| `styles/log-types.css` | `styles/log-types.css` | 10 种日志类型标签上色（`.log-type-{suffix}`） |
| `views/workflow/RunHistory.vue` | `views/workflow/RunHistory.vue` | **历史记录页完整实现**（左列表 + 右详情 Visit 卡片链 + 全套 scoped 样式，自包含） |

目录内相对 import 与平台 `frontend/src/` 层级**完全一致**（`RunHistory.vue` 位于 `views/workflow/` 两层深度，其 `../../` 引用正好落在本目录根）。业务方把 `platform/` 整体拷入自家 `src/` 下任意子目录（如 `src/amp/`）即可保持引用有效。

## 接入流程

1. **拷贝**：`cp -r platform/ <业务方>/src/amp/`
2. **安装依赖**（见下）
3. **配置环境变量**（以 Vite 为例，其他构建体系等价）：
   - `VITE_AMP_BASE_URL`：平台地址（如 `https://amp.example.com`，**不含** `/api/v1`，末尾无斜杠）
   - `VITE_AMP_API_KEY`：`X-API-Key` 密钥。生产环境推荐改为后端反代注入（同源部署时两者可省略，见 `api/workflow.js` 顶部注释）
4. **挂载视图**，二选一：
   - **历史记录页形态**：路由直接挂 `views/workflow/RunHistory.vue`（注意其历史列表依赖内部 API，见下节）
   - **实时执行视图形态**：`useWorkflowRunner` + WorkflowEditor 运行结果 Tab 的模板结构，见 `../workflow-run-live.md`

## npm 依赖

平台当前使用版本（业务方按自身版本策略调整）：

| 依赖 | 版本 | 用途 |
|---|---|---|
| `vue` | ^3.5 | 框架 |
| `naive-ui` | — | `useMessage`、`NInput`（AskforPanel）、`NEmpty`/`NSpin`/`NIcon`/`NPopconfirm`/`NButton`（RunHistory） |
| `@vicons/ionicons5` | — | RunHistory 图标 |
| `axios` | — | `api/runHistory.js` + `utils/request.js` |
| `marked` / `marked-highlight` | ^18 / ^2.2 | markdown + 高亮集成 |
| `marked-katex-extension` / `katex` | ^4 / ^0.17 | 数学公式 |
| `highlight.js` | ^11.12 | 代码高亮（`/lib/common` 子集） |
| `dompurify` | ^3.4 | XSS 消毒 |

## 内外 API 差异（`api/workflow.js` 适配层已抹平）

| 维度 | 平台内部版 | 本目录外部适配版 |
|---|---|---|
| 基础路径 | `/api` | `/api/v1` |
| 鉴权 | 无 | 每请求 `X-API-Key` 头 |
| 创建运行 | 单阶段：FormData POST `/run` 直接返回 SSE | 两阶段：`POST /runs`（async:true）→ `POST /runs/{runId}/start` → `GET .../stream`；对上层仍一次调用返回 SSE Response |
| SSE 续传 | `?lastEventId=` query 参数 | `Last-Event-ID` **请求头** |
| stream 路径 | `/runs/{runId}/stream` | `/workflows/{workflowName}/runs/{runId}/stream`——适配层记录最近一次的工作流标识；**页面刷新后需先 `setWorkflowName(nameOrId)` 再重连** |
| 响应包络 | `code` 数字 `200` | `code` 字符串 `'OK'` |
| `/state`、`/resume` | `/runs/{runId}/state`、`/runs/{runId}/resume` | 外部 API 已开放（v1.2），路径 `/api/v1/runs/{runId}/...` **不带 workflowName 段**；适配层把 `accepted` 映射为内部版语义的 `resolved`，并对 409 幂等兼容 |

## RunHistory.vue 的内部 API 依赖

左栏历史列表（`api/runHistory.js` 的 `getWorkflowsWithRuns` / `getRunDetail` / `deleteRun`）走内部 `/api/run-history`，**外部 API 无对应端点**。外部集成场景：

- 运行列表由业务方自管（记录自家发起的 runId + 状态）
- **右侧详情区（Visit 卡片链）是复用主体**，数据源改造点：
  - AGENTIC 模式：25 小时内用 SSE 重放（`reconnectRunStream(runId, null)` 从头订阅，事件幂等重建卡片）；更久由业务方后端落库 visit 数据后按 `buildReplayVisit` 组装
  - DAG 模式：外部 `GET /runs/{runId}` 的 `nodes[]` + 每节点 `logsUrl`，经 `visitChain` / `runResultReplay` 分流六面板
- `deleteRun`（删除按钮）外部无权限时应移除
- 详情数据结构与内部接口一致时（业务方后端中转），`RunHistory.vue` 可整体不改

## 维护约定

平台源码更新后，同步更新本目录对应文件（除 `api/workflow.js` 适配版需人工核对差异外，其余直接覆盖复制），并核对 `../run-history-ui.md` 与 `../external-workflow-api.md` 是否需要同步。