扩展开发指南

给想自己扩展技能、智能体和接入外部系统的客户开发团队与实施人员。页面操作见管理员篇，本篇讲每一层能扩展什么、怎么写、边界在哪。

扩展分四层

想做的事	用哪层	要写代码吗
做一个「采购助手」	智能体 + 技能	不用，页面配置
让助手会查某个已有的业务接口	能力审核上架 + 技能	不用
固定几步的业务（查完确认再写）	流程型技能	不用
接第三方提供的 MCP 工具	MCP 服务	不用
接金蝶云星空	业务系统连接（内置适配器）	不用，见金蝶对接手册
接只有 REST/JSON 接口的系统	业务系统连接（通用 HTTP）	不用
接协议特殊的自研系统	自研适配器	写一个类

不管走哪一层，下面这些治理规则都会生效，扩展的人绕不过去：

能力必须审核上架，并定好风险等级和数据范围；
本人范围的能力强制只查本人；
写操作先出确认卡片，员工确认后才执行；
资金和审批类动作一律拦截；
每一步调用都留痕；
失控防护：单轮步数、会话轮次、输入长度都有上限。

能力：智能体能调的业务接口

能力就是一个可调用的接口，带名称、入参说明、风险等级、数据范围。来源有四种：

来源	说明
业务系统接口	从 RuoYi Office 的接口文档批量导入
MCP	第三方 MCP 服务同步进来的工具
业务系统连接	金蝶等外部系统，按调用模板调用
内置	产品自带的，如知识库检索、待办详情

导入业务系统接口

实施人员用智能体管理员身份调用导入接口，从业务系统的接口文档抓取接口：

http

POST /admin-api/agentos/capability/import-from-mainline
Content-Type: application/json

{ "module": "oa" }

建议按模块分批导入、分批审核，不要一次放开全部接口。
导入的接口一律是待审；重复导入只刷新接口说明，不覆盖人工标注的风险等级和数据范围。
导入后到「开发 → 能力审核」逐条上架。

审核上架的要点

项	怎么定
风险等级	只读、写入、资金、审批。资金和审批类不允许智能体执行
数据范围	全部，或本人
本人参数	本人范围必填：接口里用来过滤员工的参数名。系统会强制用当前员工的身份填它

经验：

先上架列表、详情这类只读接口，跑顺后再考虑写入接口。
接口名称和入参说明写成员工能看懂的中文，模型选工具时靠的就是它。
返回字段特别多的接口，模型容易抓不到重点；能用汇总接口就不用明细接口。

技能包（SKILL.md）

技能 = 何时用 + 一组能力 + 一段提示词。可以在页面新建，也可以写成 SKILL.md 文件在不同环境之间导入导出。

markdown

---
name: 审批办理
code: skill_approval
description: 查待办、看摘要、留言确认；不能代批
capabilities: bpm_task_todo_page,bpm_task_done_page,agentos_bpm_todo_detail,post_bpm_comment_create
version: 1
---
查待办后，员工要「看看要批什么 / 办理第一条」时调用 agentos_bpm_todo_detail。
先说流程名、发起人、摘要或表单要点，再列当前节点。
员工说同意、驳回、通过、退回时，明确拒绝并请他到流程中心待办页亲自点，不要调用任何通过 / 驳回接口。
要在单上留意见时用 post_bpm_comment_create，未确认不要声称已经写上。

字段	说明
`name`	页面显示名
`code`	唯一标识，导入时同 code 覆盖
`description`	何时用，一句话，模型据此决定用不用这个技能
`capabilities`	能力标识，英文逗号分隔，必须是已上架的能力
`version`	版本号，自己维护
正文	提示词片段：先做什么、什么情况拒绝、输出什么格式

写好提示词的几条经验：

写边界：什么情况下必须拒绝（代批、付款、看别人的数据），比写「你很专业」有用得多。
写顺序：先查什么、再查什么、结果怎么组织。
写确认：写操作要说清「未确认不要声称已完成」。
一个技能只管一件事，能力控制在十个左右；需要的能力多了，就拆成两个技能挂到同一个智能体上。

操作：「开发 → 技能开发」→「导出」得到 SKILL.md；另一套环境「导入 SKILL.md」。导入后同样要能力都已上架才能用。

智能体

智能体 = 系统提示词 + 若干技能 + 可用范围。

「开发 → 智能体开发」→「新建智能体」：填名称、标识、系统提示词，选挂载技能。
系统提示词写角色和总体规则（语气、输出格式、不做什么）；具体业务规则写在技能里，方便复用。
可以限定哪些业务系统角色能用这个智能体；不限定时全员可用。
保存后新会话立即生效，已有会话不受影响。

也可以在「开发 → 新会话」里用一句话描述需求，让系统从已上架能力里推荐技能和提示词，确认后保存。

流程型技能

适合步骤固定、中间要人确认的业务，比如「查应收单 → 确认 → 生成催收单」。

步骤有两种：

类型	写法	说明
能力调用	`{"type":"capability","code":"<能力标识>","arguments":{}}`	按顺序调用已上架能力
确认	`{"type":"confirm","message":"确认后才生成催收单"}`	停下来等人确认

示例：

json

[
  { "type": "capability", "code": "kingdee_demo_receivable_query", "arguments": {} },
  { "type": "confirm", "message": "确认后才生成催收单" },
  { "type": "capability", "code": "kingdee_demo_customer_save", "arguments": {} }
]

在「开发 → 应用开发」里用步骤编辑器配置，点「试跑」验证。试跑遇到确认步骤就停，不会越过确认去执行后面的写操作；每次试跑都留痕。

接入第三方 MCP 工具

实施人员登记 MCP 服务：标识、名称、服务地址（Streamable HTTP）、鉴权方式（无 / Bearer / API Key）和超时。凭据只在服务器上维护，不要写进脚本提交。
管理员在「开发 → MCP 服务」点「同步工具」，工具会作为能力进入「能力审核」，默认按最严格的风险等级登记。
点「自测」做一次连通性调用。
人工核对后上架，再挂到技能里。

接入外部业务系统

非 RuoYi Office 的业务系统通过「业务系统连接」接入。内置两种适配器：

适配器	适合
金蝶云星空	金蝶 WebAPI，见金蝶对接手册
通用 HTTP	有 REST/JSON 接口的系统，认证支持无、请求头、Bearer

每条能力的调用方式写在「调用模板」里，由适配器解释。客户改过字段时，改模板即可，不用改代码；已上架能力的模板被修改后会自动退回待审。

自研适配器

协议特殊的系统（如自研 ERP、老系统的 SOAP 接口），写一个适配器类注册成 Spring Bean 即可，只依赖智能体的 api 模块：

java

@Component
public class AcmeErpConnectorAdapter implements AgentosConnectorAdapter {

    @Override
    public String vendor() { return "acme_erp"; }

    @Override
    public String name() { return "Acme ERP"; }

    @Override
    public List<AgentosConnectorAuthType> authTypes() {
        // 认证方式和各自的表单字段，标明哪些是密钥
    }

    @Override
    public String test(AgentosConnectorEndpoint endpoint) {
        // 连通性测试，返回给管理员看的一句话
    }

    @Override
    public String invoke(AgentosConnectorEndpoint endpoint, AgentosConnectorInvocation invocation) {
        // 按调用模板和入参调外部系统，返回 JSON 文本
    }

    @Override
    public List<AgentosConnectorTemplate> templates() {
        // 预置能力模板，管理员点「登记预置能力」时写进能力注册表
    }
}

适配器的约定：

只管协议，不做治理。 上架、风险、本人范围、确认、留痕都在适配器之前完成，适配器里不要再判断。
抛 IllegalStateException 时，消息会原样给员工看，不要带密钥和内部地址。
返回结果尽量整理成 {"total": n, "list": [...]}，字段名用中文标签，模型更容易读懂。
不要依赖 RuoYi Office 的 OA、人力、CRM 等业务模块。

扩展完成后的自检

检查	期望
普通员工问一句涉及新能力的话	能答出，且只看到本人有权限的数据
让它执行写操作	先出确认卡片
让它代批或付款	明确拒绝
「开发 → 授权与运营」	今日调用数增加，失败数没有异常上涨
员工点「不准」的问答	导出后据此改提示词或知识库

扩展开发指南 ​

扩展分四层 ​

能力：智能体能调的业务接口 ​

导入业务系统接口 ​

审核上架的要点 ​

技能包（SKILL.md） ​

智能体 ​

流程型技能 ​

接入第三方 MCP 工具 ​

接入外部业务系统 ​

自研适配器 ​

扩展完成后的自检 ​