--- name: agent-management-external-workflow description: "当需要构建或修改接入智能体管理平台（agent-management）外部工作流服务的软件时使用：调用 /api/v1 工作流运行接口、上传变量/文件、启动运行、订阅节点状态/思考/工具 SSE 流、查询结果、下载工作空间，或构建前端执行/运行记录视图且需保留智能体管理平台运行内容、流程与信息层级、但不必照搬 /history 页面样式时使用。用户必须显式提供智能体管理平台的 baseUrl、目标工作流的 ID 或名称（以及 API key、超时等可选项）；这些值必须落在目标应用的配置文件中（如 .env / application.yml / config.json 等），严禁在源码中硬编码，以适应环境切换与平台迁移。触发关键词包括：智能体管理平台、接入智能体管理平台、agent-management、接入 agent-management、调用工作流、展示执行过程、展示思考过程、展示工具调用、展示待办清单、运行记录页面、参考运行记录页、断线重连、SSE 续传、AskFor 用户确认、与平台前端完全一致。" --- # Agent Management 外部工作流 使用此技能以确保 vibe coding 工作与 agent-management 外部工作流契约及预期的运行执行体验保持一致。用户的描述可能比较模糊，需根据其诉求和目标代码库自行推断集成范围。 ## 第一步 由你自行判断任务形态，不要让用户来做分类。 - **API 集成**：用户需要调用 agent-management 工作流服务、上传输入、消费 SSE 或拉取结果。阅读 `references/external-workflow-api.md`。 - **运行展示 UI**：用户需要前端页面/组件来展示执行进度、节点输出、思考过程、日志、错误或工作空间下载。阅读 `references/run-history-ui.md`。 - **JS/Vue 参考代码**：需要可直接复用的 SSE 客户端、状态容器（VisitStore）或 Vue 组件实现。阅读 `references/js-implementation.md`（代码正确性以另两份契约为准）。 - **与平台前端完全一致（源码级）**：用户要求运行展示的表现与平台前端零差异（视觉类名、折叠交互、multi-visit、AskFor、断线重连逐项一致）。阅读 `references/platform/README.md`（平台源码自包含副本的索引与接入流程），做实时执行视图另读 `references/platform/workflow-run-live.md`（实时态与回放态的差异）。 - **端到端集成**：用户同时需要服务调用和前端执行视图。三份参考文档都要读。 优先沿用目标仓库已有的框架、请求封装、状态管理、组件库、路由和样式约定。将打包的参考文档视为集成契约，把运行记录的概念翻译为目标系统原生的 UI 风格。 ## 输入约定 集成前必须由用户明确给出以下输入；缺失任一关键项应主动追问，不要自行假设： - **智能体管理平台 baseUrl（必填）**：例如 `https://amp.example.com` 或 `http://10.0.0.5:2438`。注意是否包含端口与协议；末尾不要带 `/api/v1`，因为端点路径已经包含。 - **目标工作流（必填）**：优先使用工作流的 `name`（kebab-case 字符串，例如 `military-analyze-agent`，全局唯一、可读、用于所有外部 API URL 路径）。同时兼容旧的数字 `id`：纯数字路径参数会被视为 `id` 回退查找。同一 baseUrl 下可能存在多个工作流，必须由用户指定具体的一个或一组。 - **API Key（必填，敏感）**：用于 `X-API-Key` 鉴权。禁止写入受版本控制的源码或浏览器可见产物；默认放在后端配置或环境变量中。 - **超时、重试、TTL 等可选项**：如不提供，使用契约默认值（如 `ttlHours=720`）。 ### 配置而非硬编码 目标业务应用必须把上述值落到自身的配置体系里，不允许在源码中写死，以适应环境切换、平台迁移和密钥轮换： - 后端应用：放进 `application.yml` / `application.properties` / `.env`，通过 `@Value` / `@ConfigurationProperties` 注入。 - 前端应用：通过构建期环境变量（如 Vite 的 `import.meta.env.VITE_AMP_BASE_URL`）或运行期由后端代理下发的配置接口注入。 - 容器/部署：通过环境变量或 ConfigMap 注入，写入部署文档。 - 提供 `.env.example` / `application.yml.example` 等模板文件，列出全部需要填写的键，方便后续部署人员按环境填写。 ## 用户沟通 仅在缺少信息会阻塞安全可运行的实现时才提问。 - 不要询问那些能从目标仓库代码、配置、文档或现有运行视图中自行发现的信息。 - 仅当无法推断时，才询问 `baseUrl`、API key 存储位置、目标工作流 `name`（或旧数字 `id`）或页面挂载位置。 - `X-API-Key` 默认通过后端代理或服务端环境变量注入；不要将 API key 硬编码到浏览器代码中。 - 若用户明确要求在前端直接携带 `X-API-Key`，需在实现前说明泄露风险。 - 对非阻塞性细节，简要说明假设后继续推进。 ## 实现流程 1. 编辑前先勘察目标应用。 - 识别前后端边界、请求辅助封装、环境配置、路由模式以及已有的 SSE 工具。 - 如果应用已存在 API 客户端或运行视图，应在其基础上扩展，而不是另起平行抽象。 2. 按外部工作流契约实现 API 接入。 - 使用 `/api/v1` 端点，而不是内部 `/api/workflows` 端点，除非任务明确限定在 agent-management 内部。 - 工作流通过 `name`（kebab-case）标识，所有 URL 路径使用 `{workflowName}` 段；纯数字 `id` 作为兼容兜底也合法，但不应在新集成中作为首选。 - 支持默认异步流程：创建运行、启动运行、订阅流、查询结果、下载工作空间。 - 正确处理统一 JSON 响应包、二进制 zip 响应、SSE 事件、断连/重连以及终态成功/失败。 - SSE 鉴权与续传：`X-API-Key` 只支持请求头，浏览器直连必须用 `fetch` + `ReadableStream` 手动解析（原生 `EventSource` 无法携带该头）；重连通过 `Last-Event-ID` 请求头续传，指数退避 5 次后降级轮询 `GET /runs/{runId}`（30 秒/次），SSE 恢复后立即停止轮询。 - 事件路由：SSE 事件按 `visitUuid` 聚合（AGENTIC 智能体模式下同一节点可被多次访问，绝不能按 `nodeId` 合并卡片）；`node_status` 的 `status` 是大写枚举，`node_stream` 的增量在扁平 `content` 字段上。 - AskFor（用户确认）：外部 API 已开放 `POST /api/v1/runs/{runId}/resume` 与 `GET /api/v1/runs/{runId}/state`（v1.2，路径不带 workflowName 段，runId 全局唯一）。断线重连恢复流程：先查 `/state` 恢复 AskFor 面板（`currentPause.choices` 已是数组），再以 `Last-Event-ID` 续传 SSE；同一 `clarifyId` 重复提交返回 409，前端按幂等约定视为成功。 - **baseUrl、workflow name/id、API Key、超时、TTL 等参数全部从配置文件读取，禁止硬编码到源码**；凭证不得写入受版本控制的源码或浏览器可见产物中，除非用户明确接受此风险。 3. 实现运行展示 UI，保留运行记录的内容与流程层级。 - **Vue 3 项目且要求与平台一致时，优先整体拷贝 `references/platform/` 目录**：它是平台前端源码的自包含副本（含外部 `/api/v1` 适配层 `api/workflow.js`，`useWorkflowRunner` 零改动可用），拷入后按其 README 配置环境变量即可获得零差异表现；非 Vue 技术栈或允许交互近似时，才走手写翻译路线（按下述硬性要求实现）。 - **硬性要求**：完整呈现「实时状态、思考过程、待办清单、工具调用、执行日志、最终结果」六类内容（无数据的面板不渲染空占位框），折叠策略、multi-visit 渲染、AskFor 处理与本系统一致（详见 `references/run-history-ui.md`）。 - 折叠与输出：节点完成后卡片自动折叠（用户手动操作优先），最终输出始终可见；节点输出是 envelope 结构（`status` 为数字 200/400，业务字段在 `data` 内），解包后渲染，工作流最终输出同样带壳。 - markdown 渲染：思考过程与最终输出按 GFM 渲染并带代码高亮，渲染 HTML 前必须过 DOMPurify 消毒。 - 展示工作流/运行选择、运行状态、时间/耗时、节点卡片、输出变量、思考过程、非思考日志、错误和工作空间下载。 - 保留运行记录体验的核心概念：历史列表按工作流分组、选中运行详情、节点执行顺序、节点状态、可折叠的日志/上下文、思考过程独立成区。 - 不要求目标 UI 完全复刻原运行记录页的颜色、间距、图标、暗色主题、左右两栏布局或组件库，除非用户明确要求近似视觉。 - 把交互模型与信息层级翻译到目标框架中，而不是照搬框架特定的代码或样式。 4. 验证集成。 - 用真实的变量走通「创建/启动/订阅/查询/下载」链路。 - 确认 SSE 事件能增量更新 UI，终态事件能正确关闭或标记运行。 - 确认 multi-visit：同节点多次访问独立成卡（带「第 N 次访问」标识）；断线重连、刷新页面后卡片不重复、可完整回放。 - 确认失败运行能浮现错误，并仍允许查看结果/日志（如果可用）。 - 运行目标项目相关的测试、lint、类型检查或构建命令。 ## 可移植性 本技能以自包含目录形式分发。`references/platform/` 是平台前端源码的自包含副本：目录内相对 import 与平台 `frontend/src/` 层级一致，无 `@/` 别名、无仓库本地路径依赖，业务方可整体拷贝使用（是否照搬其视觉主题由用户的需求决定——要求完全一致时照搬，仅要交互一致时按目标系统风格改写样式）。除此之外，不要依赖仓库本地路径、已部署的参考页面或特定公网 IP。如果目标仓库已经自带 agent-management 适配器或运行记录视图，应在目标仓库内勘察并扩展该本地实现。