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，需在实现前说明泄露风险。
对非阻塞性细节，简要说明假设后继续推进。

实现流程

编辑前先勘察目标应用。
- 识别前后端边界、请求辅助封装、环境配置、路由模式以及已有的 SSE 工具。
- 如果应用已存在 API 客户端或运行视图，应在其基础上扩展，而不是另起平行抽象。
按外部工作流契约实现 API 接入。
- 使用 /api/v1 端点，而不是内部 /api/workflows 端点，除非任务明确限定在 agent-management 内部。
- 工作流通过 name（kebab-case）标识，所有 URL 路径使用 {workflowName} 段；纯数字 id 作为兼容兜底也合法，但不应在新集成中作为首选。
- 支持默认异步流程：创建运行、启动运行、订阅流、查询结果、下载工作空间。
- 正确处理统一 JSON 响应包、二进制 zip 响应、SSE 事件、断连/重连以及终态成功/失败。
- baseUrl、workflow name/id、API Key、超时、TTL 等参数全部从配置文件读取，禁止硬编码到源码；凭证不得写入受版本控制的源码或浏览器可见产物中，除非用户明确接受此风险。
实现运行展示 UI，保留运行记录的内容与流程层级。
- 展示工作流/运行选择、运行状态、时间/耗时、节点卡片、输出变量、思考过程、非思考日志、错误和工作空间下载。
- 保留运行记录体验的核心概念：历史列表按工作流分组、选中运行详情、节点执行顺序、节点状态、可折叠的日志/上下文、思考过程独立成区。
- 不要求目标 UI 完全复刻原运行记录页的颜色、间距、图标、暗色主题、左右两栏布局或组件库，除非用户明确要求近似视觉。
- 把交互模型与信息层级翻译到目标框架中，而不是照搬框架特定的代码或样式。
验证集成。
- 用真实的变量走通「创建/启动/订阅/查询/下载」链路。
- 确认 SSE 事件能增量更新 UI，终态事件能正确关闭或标记运行。
- 确认失败运行能浮现错误，并仍允许查看结果/日志（如果可用）。
- 运行目标项目相关的测试、lint、类型检查或构建命令。

可移植性

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

SKILL.md 6.7 KB Histórico Raw