从“模型会说话”到“Agent 可管理”：一套 AI 资产平台的前端工程实践分享

刚开始，我们只关心接入大模型实现一些具体问题，但当Agent相关资产越来越多，就会出现以下问题：比如提示词由谁维护？工具升级后会不会影响已有 Agent？Skill 如何打包和复用？某次调用失败，究竟是模型、工具，还是编排出了问题？这时，真正稀缺的已经不只是模型能力，而是把能力沉淀、组合、发布和追踪的工程系统。

而我们团队开发的 Agent Hub，正是在解决这类问题。它把散落在代码、文档和接口中的 AI 能力，整理成五类可管理资产：

Tool：Agent 可以调用的原子工具；
Skill：带有说明、脚本和参考资料的复合能力包；
Prompt：可编辑、可版本化的提示词资产；
Agent：组合模型、Prompt、Tool、Skill 与 Workflow 的运行单元；
Trace：用于回答"这次调用到底发生了什么"的观测记录。

如果把 Agent 比作一支数字化团队，那么 Tool 是它手里的工具，Skill 是工作手册，Prompt 是岗位说明，Agent 是员工本身，而 Trace 则是完整的工作日志。

部分UI如下：

提示词管理

skill管理

观测平台

Agent编辑

一、五类资产不是五座孤岛

如果只是分别做五张 CRUD 表格，系统当然可以很快上线，但它不会真正成为 Agent 平台。

Agent Hub 更关键的价值，在于建立资产之间的关系：

text 复制代码

Tool ──┐
Skill ─┼──> Agent ───> 运行与调试 ───> Trace
Prompt ┤
Workflow ┘

一个 Agent 的创建过程，不是填写几项基础信息后保存，而是一次能力编排：

选择大模型，并根据模型元数据配置参数；
选择已发布的 Prompt 版本；
绑定指定版本的 Skill；
添加算法工具，并维护输入参数 Schema；
绑定 Workflow；
设置最大步骤数、最长运行时间、Token 上限等运行边界；
在右侧预览区直接发起多轮调试。

Agent 的编辑体验被拆分为基础信息弹窗、三栏画布、资产选择器、算法工具配置、预览附件上传等多个模块。

创建 Agent 时，前端先保存一个草稿骨架，再进入画布继续编排；"保存并发布"则先保存最新编排，再执行发布。这个顺序避免了"发布成功但编排仍是旧版本"的中间状态。

二、版本管理：

AI 资产与普通表单数据最大的区别，是它们会被其他资产引用。

一个工具的 Endpoint 被修改、一个 Skill 的脚本被替换、一个 Prompt 的正文被重写，都可能改变线上 Agent 的行为。因此，Agent Hub 没有把"保存"简单等同于"覆盖"。

项目中，Tool、Skill 和 Prompt 都区分普通信息与核心内容：

修改名称、描述、产品线等信息，可以更新当前草稿；
修改已发布资产的核心内容，需要提示用户创建新版本；
历史版本可以查看，并根据状态执行启用或禁用；
Agent 对 Skill、Workflow 等关联资产使用明确版本；Prompt 则从已发布版本导入内容，而不是依赖一个随时变化的名称。

这种设计背后的原则是：被复用的能力必须可追溯，可追溯的能力必须有版本。

以 Skill 为例，它不仅是一段 Markdown，而是一个目录型能力包。前端会维护 SKILL.md、references/、scripts/ 等文件，生成 manifest 与 checksum，上传到对象存储，再把目录地址和清单写入管理接口。

于是，"Skill 是否变化"不再依赖肉眼判断，而可以通过文件路径、大小与校验和形成稳定签名：

ts 复制代码

function manifestSignature(manifest: SkillManifest | undefined) {
  if (!manifest)
    return undefined

  return JSON.stringify({
    entryFile: manifest.entryFile,
    files: [...manifest.files]
      .map(file => ({
        path: file.path,
        size: file.size ?? 0,
        checksum: file.checksum ?? '',
      }))
      .sort((left, right) => left.path.localeCompare(right.path)),
  })
}

这比"用户点了保存就算变更"更可靠，也为后续的版本比较、缓存和审计留下了空间。

三、状态、权限和产品线：

资产平台真正复杂的地方，往往不在编辑器，而在"谁能看、谁能改、什么状态允许改"。

Agent Hub 同时处理三类约束：

1. 状态约束

资产存在草稿、已发布、已禁用等状态。按钮是否出现、操作是否需要确认、更新时调用草稿接口还是版本状态接口，都由当前状态决定。

例如，工具草稿发布与已发布版本禁用是两条不同链路：前者推动草稿进入发布态，后者修改某个明确版本的可用状态。前端必须保存版本号，不能只拿资产编码发起模糊操作。

2. 权限约束

平台管理员、产品管理员和普通用户看到的产品线与资产范围不同。项目把权限计算集中到一处，由 Hook 计算可见 Tab、可选权限与产品范围，页面组件只消费最终结果。

这避免了权限判断散落在按钮、表格列和弹窗中。

3. 产品线约束

Tool、Skill、Prompt、Agent 都带有产品归属。筛选"全部"时，管理员可以不传产品 ID；普通用户则必须把请求收敛到自己有权限的产品集合。

四、按需加载：

Agent 画布需要选择 Skill、Prompt 和 Workflow，但这并不意味着进入 Agent 列表时就要加载全部关联资产。

项目采用"列表轻加载、编辑时补数据"的策略：

进入独立路由，只请求当前模块的列表；
打开 Agent 编辑画布时，再获取 Agent 详情；
打开资产选择器时，再加载可发布版本；
Skill、Prompt 与 Workflow 可以并行请求，降低等待时间。

请求回来后，前端还要进行一次业务过滤：Skill 和 Prompt 只有存在已发布版本时才能被 Agent 绑定。这里不能只看资产顶层状态，因为顶层状态可能代表"最新版本状态"，并不能说明历史版本中是否仍有可用版本。

换句话说，懒加载解决的是性能问题，版本过滤解决的是正确性问题，两者缺一不可。

五、Agent 画布：把配置表单变成工作台

普通资产适合表格加弹窗，Agent 却不适合。

因为 Agent 配置不是一组彼此独立的字段，而是一条从"角色设定"到"能力绑定"，再到"运行验证"的连续路径。项目因此采用三栏画布：

text 复制代码

左栏：Prompt、模型与参数
中栏：Tool、Skill、Workflow 与运行限制
右栏：预览调试与多轮会话

三栏布局的意义，不只是信息放得更多，而是让"配置---验证---调整"形成一个短循环。用户修改提示词或模型参数后，不需要离开页面，就能立即在预览区发起调用，观察流式结果，再回到左侧继续调整。

预览调试还需要处理两类典型的 AI 应用问题：

会话：进入画布时创建 sessionId，多轮对话复用当前会话，清空后创建新会话；
流式响应：解析 SSE 事件，逐步追加文本，并识别图片、视频、音频和文件资源。

这让 Agent Hub 从"配置管理后台"向"开发与调试工作台"迈出了一步。

六、Trace：让每次运行都有证据

没有观测能力的 Agent，就像一个只交付结果、拒绝解释过程的黑盒员工。

Agent Hub 的 Trace 模块承担了补全证据链的职责。它支持按产品线等条件查询运行记录，并在明细抽屉中展示结构化步骤树。用户可以沿着一次会话向下查看模型调用、工具执行、耗时和成本信息。

这类观测数据不仅用于排错，还可以反向推动资产治理：

某个 Tool 是否频繁超时；
某个 Prompt 是否导致 Token 消耗异常；
某个 Agent 的失败是否集中在特定模型或工作流；
新版本发布后，成功率和成本是否发生变化。

当 Trace 与版本号、资产编码关联起来，平台才真正具备"发布后可验证、出现问题可回溯"的闭环。

结语：Agent 平台的核心，是让能力有秩序地流动

Agent Hub 最值得借鉴的，并不是某个表格或某段请求代码，而是它对 AI 能力的重新组织：

Tool、Skill、Prompt 和 Agent 都被视为有归属、有状态、有版本的资产；
Agent 通过版本选择或内容导入组合这些资产，避免依赖悄悄漂移；
服务层屏蔽多后端协议，路由和 Hook 保持业务边界；
画布把配置与调试放进同一条反馈回路；
Trace 为发布后的行为提供可追溯证据。

当模型能力越来越容易获得，平台真正的壁垒会逐渐从"接入了哪个模型"，转向"能否稳定地组织、复用和治理这些能力"。

一个成熟的 Agent，不应该只是一次成功的模型调用；它应该是一组可管理资产经过明确编排后，产生的可发布、可观测、可演进的数字能力，希望能给大家一些参考。