Home Explore Help
Register Sign In
AI-Special-Project-Team
/
agent-management
3
1
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: a1f0c68a14
Branches Tags
agent-managemen...
/
skills
/
agent-management-external-workflow
/
SKILL.md

SKILL.md 10.0 KB
History Raw

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 适配器或运行记录视图，应在目标仓库内勘察并扩展该本地实现。