OoderAgent技能包开发与发布指南——如何把一个想法变成平台上线的智能能力

目录

AI 智能体开发平台 · 实践指南

技能包开发与发布指南—— 业务人员如何把一个想法变成平台上线的智能能力

不需要先学一套私有框架，也不需要成为全栈工程师。用自然语言描述技能、在对话里驱动开发、在沙箱里联调验证、一键发布到平台——这就是本指南要讲清楚的全过程：技能包是怎么开发的、怎么发布的、平台内部三层如何为它协同、以及如何用 CodeBuddy / Qoder / Trae 等 AI 编程工具通过 MCP 与平台衔接。

版本 v2.0 · 2026-10-15

读者：业务人员 · 解决方案开发者 · 实施顾问

主线：五阶段旅程 + 八步开发法

关键词：技能包 · 三层协同 · A2A · MCP

00导读：一次技能包开发的完整旅程

把「我要给业务加一个智能能力」变成「业务人员在对话里真的用上了它」，中间是一条清晰的五阶段旅程。每个阶段都有对应的工具面、明确的完成标志和可回退点——全文的每一章都挂靠在这条旅程上：

图 1

怎么读这份指南

只想尽快上手：直接读第 3 章（技能包长什么样）和第 4 章（八步开发法），遇到卡点再回第 2 章看架构。 习惯用 AI 编程工具：读完第 0–3 章后直接跳第 6 章（MCP 接入），用 CodeBuddy / Qoder / Trae 完成开发与发布。 负责平台推广与培训：第 2 章（三层协同）+ 第 7 章（入口选择）+ 第 8 章（保障机制）是面向团队讲解的核心材料。

三个贯穿全程的原则

• 声明先行：技能包的本质是一组「声明」（要什么能力、走什么流程、用什么知识），代码由平台生成与执行——先把声明想清楚，就完成了大半工作；
• 对话驱动：从描述技能到排查错误，首选交互方式是对话；界面操作是补充，命令行是兜底；
• 失败可见：任何一步失败都会得到明确的原因反馈（而非静默吞掉），这是联调与发布的信心来源。

01你会用到的工作面：三类角色，三个入口

平台为「开发一个技能包」准备了三个工作面。同一个技能包，从哪个工作面进入都可以推进，区别只在顺手程度与自动化程度：

对话工作台与技能工作台通常出现在同一个页面里——左栏是对话（业务视角），中栏是能力卡与工程配置（技能视角），右栏是执行输出（工程视角）：

图 2

· 技能工作台实拍（示例为财务技能场景）：中栏「工程」页签完成工程绑定，右栏「输出」页签展示编译/部署/发布等执行结果。业务人员日常只需要关注左栏对话与中栏的技能卡

图 3

· 对话工作台实拍：左栏是可协作的执行体列表（含能力标签与在线状态），中栏是会话流。技能包上线后，它的执行体就会出现在这份目录里，业务人员直接@它、或用自然语言唤起

一个心智模型

把平台想成一家「智能能力餐厅」：对话工作台是点餐台（说什么、上什么）；技能工作台是明档厨房（看得见每道工序）；AI 编程工具是你自带的私厨团队（经 MCP 这条专用传菜通道与后厨协作）。三层协同架构（下一章）就是后厨的组织方式。

02三层协同架构：技能包背后的分工

技能包之所以能「声明即上线」，是因为平台内部有三个层次在协同。用通用技术语言来描述，它们是：交互编排层（负责对话与调度）、领域声明层（负责「技能包」本身）、宿主适配层（负责与企业系统对接），外加一个独立部署的技能执行引擎承担全部工程动作：

图 4

· 三层协同与技能执行引擎：声明进技能包、实现进执行引擎、对接进适配层（含产物落盘与 MCP 接入点）

协同关系：三个「为什么」

• 为什么执行引擎要独立部署？工程动作（编译、打包、运行）资源消耗大、需要真实工具链，与对话服务分开部署，互不拖累；独立进程也意味着它可以部署在单独的开发机上。
• 为什么交互层不直接调执行引擎的内部接口？两层之间只走 A2A 协议（智能体互联协议）——请求方声明「找谁、干什么、回执送到哪」，执行方按能力域受理。协议化的好处：任何一侧升级都不影响另一侧，第三方执行体也能按同一协议接入。
• 为什么产物由交互层统一落库？技能代码的最终归宿是平台统一的产物库（虚拟文件系统 VFS）。执行引擎只负责「生成产物字节」，落盘与呈现由交互层统一完成——单一落盘口径，杜绝「生成的东西不知道去哪了」。

能力域边界是硬约束

每个执行体只受理自己能力域内的操作。请求一个执行体做越域的事（比如让「构建执行体」去生成代码），会被带原因明确拒绝（而不是猜着做或静默失败）。这让「谁该干什么」永远可预期——编排者（人或 AI 工具）可以放心地把任务拆给不同执行体。

03认识技能包：它到底由什么组成旅程阶段 ①

「技能包」是本指南的核心概念，也是平台对「一项智能能力」的标准封装。一个技能包 = 四类声明的组合——想清楚这四件事，就完成了技能开发中最需要人来判断的部分：

① 执行体清单（它是什么）

声明这个技能包对外提供哪些执行体：名字、锚点（能力域或业务场景）、具备的能力、可否被委派。上线后，对话目录里能看到的就是它们。

② 流程定义（它怎么走）

把技能的执行路径写成流程 DAG：先做什么、再做什么、哪里并行、哪里要人确认、失败走哪条分支。流程定义是编排的唯一真源。

③ 知识资产（它知道什么）

技能包自带的领域知识：业务规则、术语表、常见问答。检索与回答都从这份知识出发，随技能包一起版本化。

④ 配置声明（它连到哪）

企业环境的连接声明：数据源、表单、权限映射。宿主适配层按这份声明完成对接，联调阶段验证的就是它。

落到文件上，一个技能包的目录结构大致如下（约定优于配置，大部分文件由平台按模板生成）：

my-skill-pack/
├── agents.yaml            # 执行体清单：有哪些执行体、能力、委派模式
├── flow-decl/             # 流程定义（DAG 真源）
│   └── main-flow/
│       └── definition.json
├── knowledge/             # 领域知识资产（规则 / 术语 / 问答）
├── config-decl/           # 企业环境连接声明（数据源 / 表单 / 权限）
└── src/                   # 技能代码（由代码生成域产出，可人工修改）

「声明先行」意味着什么

平台启动时读取技能包声明，自动把执行体注册进对话目录、把流程装载进流程引擎——你不需要写任何「注册代码」。声明改了，平台行为跟着变；声明与平台视图的一致性由平台自动对账（发现漂移会显式提示，而不是悄悄用旧值）。

把需求翻译成四类声明：一个例子

假设业务方提出：「报销单金额超过 5000 元要自动加签财务总监，并且要能回答『我的报销到哪一步了』」。翻译成声明语言：

这张表就是阶段 ① 的交付物。接下来的开发（阶段 ②）本质上是：让平台把声明变成可运行的代码与流程，再把代码打磨到验收标准。

04八步开发法：从需求到可交付旅程阶段 ②③

技能执行引擎的六大能力域，恰好支撑一条完整的开发链路。把典型开发过程整理成八个操作步骤——每一步给出「怎么做」和「做完你会看到什么」。前六步是单技能开发主线，后两步是进阶协作：

图 5

S1

生成技能代码

代码生成域

目标：把第 3 章的四类声明变成可运行的技能代码骨架。

怎么做：在对话工作台点「代码生成」卡（或直接说「给报销技能生成 Entity/DTO/服务类/接口」），携带工程名与技能描述。平台按

D2C 模板生成代码，产物自动落到工程。

完成标志：会话里出现产出卡与产物清单；在技能工作台「源码」页签能浏览并修改这些文件。生成模式有三档（本地生成 / 远端优先 / 仅远端），平台按工程配置自动选择，失败时会明确告知而非静默降级。

图 6· 生成完成后在「源码」页签浏览与修改：机器写（S1）→ 人改（这里）→ 机器验（S2），同一工作面闭环

S2构建校验构建校验域

目标：确认代码可编译，把错误变成可定位的结构化信息。

怎么做：点「构建校验」卡（或让 AI 工具触发编译）。平台调用构建工具链编译当前工程。

完成标志：返回结构化诊断清单（文件、行号、错误原因）。建议养成习惯：每次生成后立刻编译，编译不过就继续下一步——平台在部署前也会强制做这道门禁，编译不过不会产出部署包。

S3沙箱联调部署联调域

目标：在沙箱环境把技能真正跑起来，端到端验证。

怎么做：点「沙箱联调」卡 → 平台自动完成 编译 → 部署到沙箱 → 启动 → 运行验证，返回运行标识与日志；凭运行标识可随时回看日志尾部。目标环境若有歧义（沙箱还是生产），平台会弹确认卡让你选。完成标志：运行日志显示技能正常响应；到对话工作台试call一次，验证第 3 章声明的能力确实可用。

S4建立基线工程治理域

目标：给当前工程拍一个「快照」，作为后续发布与回滚的锚点。

怎么做：点「工程治理」卡 →「建立基线」。平台对工程文件做快照并落盘到工程治理目录。

完成标志：返回基线标识；之后每次改动都可以先比对基线（平台会列出差异文件清单），做到「改了什么、回退到哪」心里有数。

S5检索工程知识工程知识域

目标：改代码之前，先知道「这个功能现在在哪实现」。

怎么做：问「这个审核规则在哪个类里实现？」平台在工程知识库中检索（知识库可随时从当前工程重建/补充）。

完成标志：得到类/方法级的定位结果；无命中时平台会明确说「未检索到」，不会编一个答案。

S6维护 D2C 模板模板管理域

目标：当团队有固定的代码风格或骨架规范时，让 S1 的生成结果长成团队的样子。

怎么做：点「模板管理」卡，查看/编辑模板段落。模板属于写操作，平台会弹审批确认。

完成标志：返回模板内容与缓存失效确认——下一次生成即生效。

S7委派协作（进阶）A2A 委派

目标：让其他技能包 / 其他 Agent 把工程类任务委托给技能执行引擎，而不必自己重复实现。怎么做：在对话里@执行体说任务；或在技能包声明里标记

强制委派（匹配到委派语义时自动转交）；AI 编程工具经 MCP 也可触发同一委派。跨节点委派时平台自动携带回执地址，确保结果送回发起方。

完成标志：会话台账里出现「已将任务委派给『××执行体』」→ 随后回执行。

图 7· 委派台账气泡实拍（示例为财务技能场景）：「已将任务委派给『××执行体』，等待执行…」→ 回执返回。所有跨执行体协作都在台账里留痕，进度随时可查

S8端到端流水线（进阶）多执行体串联

目标：把 S1–S4 串成一条「从需求到可发布」的自动流水线，适合迭代频繁的技能包。

怎么做：在技能包的流程定义里把各步骤编排成流水线（生成 → 编译 → 部署 → 验证 → 发布）；也可在对话里让平台按流程驱动。关键节点（生成落盘、生产发布）由平台强制插入人工确认。

完成标志：流水线各步的产物与台账由平台拼装呈现；任何一步失败，流水线在该步停下并给出原因。

一次生成任务在平台内部是怎么走的（供理解，无需记忆）

你在对话里点卡后：对话路由识别意图 → 组装任务请求（找谁、干什么、参数、回执送到哪）→ 经 A2A 协议定向发给技能执行引擎 → 执行引擎校验能力域、执行、按协议回投任务回执 → 交互层把产物统一落进产物库（VFS）→ 前端渲染产出卡。全程两条任务状态事件（已受理 / 已答复）都会进台账，最终结果只由任务回执承载——你在界面上看到的每一条进度都有据可查。

05发布到平台：让技能真正被用起来旅程阶段 ④

联调通过的技能包，走一条发布流水线进入平台。发布不是「把文件拷过去」，而是让平台的三个注册面同时感知到新技能：对话目录（执行体上线）、流程引擎（流程可编排）、知识库（知识可检索）。

5.1 发布前检查清单

5.2 发布五步

1. 比对基线：确认本次要发布的改动范围（平台列出与基线的差异文件清单）；
2. 打包：工程治理域调用构建工具链产出部署包（依赖齐备是前提——目标环境需要能解析工程全部依赖）；
3. 生成发布台账：平台为部署包计算指纹校验值（md5）并记入台账——「发布的到底是什么、有没有被改动」从此可审计；
4. 注册生效：平台装载部署包，技能包声明中的执行体进入对话目录、流程装载进流程引擎、知识入库；
5. 上线验证：在对话工作台确认新执行体出现、试 call 一次、查看台账首条记录。

发布到生产环境是受控动作

发布目标为生产时，平台强制插入人工审批（APPROVAL 卡）；沙箱发布可自动通过。这不是流程繁文缛节，而是平台对「谁在什么时候把什么能力推向了真实业务」的刚性留痕——审批记录与部署包指纹一起进台账。

5.3 发布之后：版本与回滚

• 版本锚点：每次发布对应的基线标识与部署包指纹都记录在发布台账里，历史可追溯；
• 快速回滚：出现问题时，从最近的好基线重新打包发布即可；基线机制保证「回滚到一个明确的状态」而非「凭记忆改回去」；
• 迭代节奏：已上线技能的修改走同一条链（改声明/代码 → 编译 → 沙箱 → 基线 → 发布），建议小步快跑、每次发布只带一个意图的改动。

06用 AI 编程工具经 MCP 接入平台旅程阶段 ②③④ 的加速路径

如果你的团队已经在用 CodeBuddy、Qoder、Trae 这类 AI 编程工具，不需要切换工作环境——平台把技能开发能力以 MCP（Model Context Protocol，模型上下文协议）标准开放，AI 工具作为 MCP 客户端直连平台，在熟悉的 IDE 里完成检索、生成、构建、发布的全流程。

6.1 接入拓扑：一条协议，两端各取所需

图 8· MCP 接入拓扑：AI 编程工具（MCP 客户端）⇄ 技能中心（MCP 接入点）⇄ 技能执行引擎 / 流程引擎

6.2 接入三步（以 Trae / CodeBuddy / Qoder 为例）

M1获取接入凭据

怎么做：向平台管理员索取技能中心的

MCP 接入地址（URL）与访问令牌（Token）。管理员在技能中心为你的团队创建接入账号，并按需圈定可用工具范围（例如：只读检索 + 构建，或全量含发布）。

完成标志：拿到两样东西——形如 https://<平台地址>/mcp/skills 的端点、一串访问令牌。

M2在 AI 工具中配置 MCP 服务

怎么做：在工具的 MCP 设置中新增服务。三家工具均遵循同一份标准配置格式（文件位置与设置入口以各产品当前版本为准）：

{
  "mcpServers": {
    "platform-skills": {
      "url": "https://<平台地址>/mcp/skills",
      "headers": { "Authorization": "Bearer <访问令牌>" }
    }
  }
}

完成标志：工具的 MCP 面板显示 platform-skills 已连接，工具清单加载成功（检索、生成、构建、联调、发布等条目可见）。

M3验证与开工

怎么做：在 AI 工具对话框里说一句「列出平台上可用的技能域」——AI 会调用平台目录工具返回能力清单；再试一条「检索：XX 功能在哪个类里实现」确认读链路畅通。

完成标志：工具清单可见 + 一读一写两条链路验证通过，即可按第 4 章八步法开工。

6.3 平台经 MCP 暴露的工具面（与能力域一一对应）

6.4 三条典型工作流

① 在 Trae 里开发一个新技能

「帮我按这个声明初始化报销技能包工程」→ 生成 → 「编译并修复报错」→ 循环 → 「部署到沙箱验证」→ 全程在 IDE 内完成，产物同步落在平台产物库，工作台里同样可见。

② 在 CodeBuddy 里做一次发布

「比对基线，列出本次改动」→「打包并生成发布台账」→「发布到测试环境」→ 发布生产时，AI 工具会收到平台的审批要求，到工作台完成人工确认后流水线继续。

③ 在 Qoder 里做变更影响分析

「这个接口被哪些技能用到？改动会影响什么」→ 检索工具定位引用 → 生成域给出修改方案 → 构建域验证——AI 负责检索与草拟，平台负责执行与留痕。

MCP 通道的安全边界

令牌即身份：经 MCP 的每一次调用都以令牌归属的账号留痕，与工作台操作同一套台账；白名单即范围：管理员可按团队圈定可用工具（例如先开放只读族，跑顺后再放开发布）；确认不因通道而免：写操作与生产发布的人工确认在 MCP 通道上同样强制——AI 工具会收到「待确认」状态，需要人到工作台或经授权通道完成确认。平台不提供「跳过确认」的开关。

07三种入口怎么选：一张决策表

对话工作台、技能工作台、AI 编程工具（MCP）三种入口并非三选一——同一技能包的三类角色往往同时使用三种入口。按你的当前任务选入口：

一条实践建议

新团队从「对话工作台 + 快捷卡」起步建立信心 → 需要精细工程控制时引入「技能工作台」→ 团队已有 AI 编程习惯后接入「MCP」提速。三层入口共享同一套产物库与台账，随时可以换入口、随时可以接续——换工具不换状态。

08平台保障机制：为什么可以放心把活交给它

把工程动作交给自动化执行，前提是「它错的时候我知道、它危险的时候它停下」。平台在整条旅程上布了四层保障，全部默认开启：

8.1 该停的地方一定停：人工确认

平台内置人工确认机制（人工门）：写路径授权（越界写文件 → 拒绝/请求授权）、生产发布审批（APPROVAL 卡）、参数歧义澄清（CHOICE 卡）、目标环境选择（沙箱还是生产）。超时行为可配置（自动通过 / 自动拒绝 / 升级人工），确认记录（谁、何时、确认了哪一步）全程落库。

图 9

· 人工确认实拍：系统确认行（谁在何时确认了哪个步骤）+ 用户输入 + 智能体响应。对话工作台与 MCP 通道共用同一套确认机制

8.2 出错的时候一定说：失败可见

• 失败带原因：每个失败回执必带错误码与说明（请求不合法 / 能力未开放 / 编译失败 / 目标节点不可达…），拒绝与失败分得很清楚——「没受理」和「干了没干成」是两种终态；
• 不静默降级：生成模式设为「仅远端」时，远端失败就是失败，不会偷偷换条路装成功；
• 不编造答案：知识检索无命中时明确说「未检索到」。

8.3 越界的事一定不做：能力域边界

每个执行体只受理本能力域的操作，越域请求被带原因拒绝。这是多执行体协作能够放心的前提——把「构建」派给构建执行体，它永远不会「顺手」帮你改了别的。对编排者（人、流程、或 AI 工具）而言，能力边界可预期，任务拆分才安全。

8.4 做过的事一定有痕：全程留痕

结语：把复杂性留在平台，把注意力还给业务

回看整条旅程：业务人员真正要做的只有三件事——把技能说清楚（四类声明）、把产物验一验（八步法）、把发布把好关（检查清单 + 审批）。生成、编译、部署、注册、留痕这些确定性工作，由三层协同架构与技能执行引擎完成；AI 编程工具经 MCP 把这套能力直接送进开发者熟悉的 IDE。复杂性被协议与机制消化在平台内部，这正是「业务人员也能开发技能」能够成立的原因。

参考与延伸阅读

1. 平台内部设计底稿：技能包用户故事与三层数据流转、工程拆分与接线方案、以技能执行引擎为中心的平台规划（2026-10）—— 本指南架构描述与操作步骤的依据。平台知识库 · 内部文档
2. Model Context Protocol（MCP）官方规范 —— AI 工具与平台技能中心的接入协议标准（Streamable HTTP 传输、工具发现与调用）。https://modelcontextprotocol.io
3. Trae · CodeBuddy · Qoder 官方文档 —— 各产品 MCP 客户端配置入口与 mcpServers 配置格式说明（以各产品当前版本为准）。各产品官方文档站
4. 截图说明 —— 文中界面截图取自平台实测环境（示例场景为财务技能包），机制表述适用于全部技能场景。工程实测环境

Generated by Trae Work · 2026-10-15 · 全文使用通用技术语言表述，配合平台任意技能场景阅读