---
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、调用工作流、展示执行过程、展示思考过程、运行记录页面、参考运行记录页。"
---

# Agent Management 外部工作流

使用此技能以确保 vibe coding 工作与 agent-management 外部工作流契约及预期的运行执行体验保持一致。用户的描述可能比较模糊，需根据其诉求和目标代码库自行推断集成范围。

## 第一步

由你自行判断任务形态，不要让用户来做分类。

- **API 集成**：用户需要调用 agent-management 工作流服务、上传输入、消费 SSE 或拉取结果。阅读 `references/external-workflow-api.md`。
- **运行展示 UI**：用户需要前端页面/组件来展示执行进度、节点输出、思考过程、日志、错误或工作空间下载。阅读 `references/run-history-ui.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 事件、断连/重连以及终态成功/失败。
   - **baseUrl、workflow name/id、API Key、超时、TTL 等参数全部从配置文件读取，禁止硬编码到源码**；凭证不得写入受版本控制的源码或浏览器可见产物中，除非用户明确接受此风险。

3. 实现运行展示 UI，保留运行记录的内容与流程层级。
   - 展示工作流/运行选择、运行状态、时间/耗时、节点卡片、输出变量、思考过程、非思考日志、错误和工作空间下载。
   - 保留运行记录体验的核心概念：历史列表按工作流分组、选中运行详情、节点执行顺序、节点状态、可折叠的日志/上下文、思考过程独立成区。
   - 不要求目标 UI 完全复刻原运行记录页的颜色、间距、图标、暗色主题、左右两栏布局或组件库，除非用户明确要求近似视觉。
   - 把交互模型与信息层级翻译到目标框架中，而不是照搬框架特定的代码或样式。

4. 验证集成。
   - 用真实的变量走通「创建/启动/订阅/查询/下载」链路。
   - 确认 SSE 事件能增量更新 UI，终态事件能正确关闭或标记运行。
   - 确认失败运行能浮现错误，并仍允许查看结果/日志（如果可用）。
   - 运行目标项目相关的测试、lint、类型检查或构建命令。

## 可移植性

本技能以自包含目录形式分发。不要依赖仓库本地路径、已部署的参考页面、特定公网 IP 或原前端的视觉主题。如果目标仓库已经自带 agent-management 适配器或运行记录视图，应在目标仓库内勘察并扩展该本地实现。
