金蝶对接手册

给业务系统是金蝶云星空、而不是 RuoYi Office 的客户。按本篇做完，员工可以在智能体里问「查一下本月华东客户的销售订单」，答案直接来自金蝶。

接入后，治理规则和接 RuoYi Office 时完全一样：能力要审核上架、本人范围强制只查本人、写操作要员工确认、每一步留痕。

接入流程

没有真实金蝶时（售前演示、内部验收），打开「演示模式」，整个流程照样能走通，结果会标注「演示数据」。

准备

项	说明
金蝶地址	形如 http://<金蝶服务器>/k3cloud
账套 ID	金蝶管理中心里数据中心的 ID
集成账号	建议在金蝶里单独建一个集成用户，权限按需最小化；或使用第三方应用的应用 ID 与密钥
网络	智能体服务能访问金蝶服务器

一、新建连接并测试

要办的事：把智能体和金蝶连起来。

点哪里：「开发」→「业务系统连接」→「新建连接」：

1. 「业务系统类型」选「金蝶云星空」。
2. 填连接名称、连接标识（英文，后面能力标识会以它开头）、系统地址。
3. 「认证方式」选「账号密码」，填账套 ID、用户名、密码；或选第三方应用登录，填应用 ID 和密钥。
4. 语言默认 2052（简体中文），超时默认 15 秒。
5. 保存后点列表里的「测试连接」。

你会看到：

要注意什么：

• 密码、密钥保存后列表只显示「已配置」；编辑时留空表示不修改。页面上无法清空已保存的密钥，要换账号就直接填新值。
• 演示模式打开时不连真实金蝶，测试结果会提示「演示模式：未连接真实金蝶，样例数据可用」。接真实系统时记得关掉。

二、登记预置能力

要办的事：把常用的金蝶查询登记成智能体能调用的能力。

点哪里：连接列表里点「登记预置能力」。

预置七条：

能力	金蝶表单	风险	范围
销售订单查询	销售订单	只读	全部
应收单查询	应收单	只读	全部
即时库存查询	即时库存	只读	全部
客户查询	客户	只读	全部
采购订单查询	采购订单	只读	全部
我的费用报销	费用报销单	只读	本人
新建客户	客户	写入	全部（需员工确认）

要注意什么：登记后能力是待审，同时生成一个未安装的技能包，此时员工还用不了。重复点「登记预置能力」不会重复登记。

三、审核上架

要办的事：逐条确认风险等级和数据范围，再上架。

点哪里：连接列表里点「能力」，在抽屉里看每条能力；点上方链接进入「开发 → 能力审核」上架。

你会看到：

要注意什么：

• 「我的费用报销」是本人范围，审核时「本人参数」要填 proposer（抽屉里会显示这个名字）。填错会被拒绝调用，不会查出全公司的数据。
• 「新建客户」是写入能力，员工在对话里要求新建时，会先出确认卡片，确认后才提交到金蝶。
• 金蝶的提交、审核、反审核属于审批类动作，产品不提供，也不能配置出来。
• 抽屉里每条能力可以点「自测」，确认调用模板对不对。

四、账号映射

要办的事：把员工在 RuoYi 里的身份对应到金蝶里的员工编码，「我的费用报销」这类本人范围能力靠它过滤。

点哪里：连接列表里点「账号映射」，填员工编号、员工姓名、外部账号（建议填金蝶员工编码）、外部姓名，点「绑定」；不再需要时点「解绑」。

你会看到：

要注意什么：没有绑定的员工调用本人范围能力会被拒绝，并提示还没有绑定账号，不会退回去查全部数据。只读的全量能力（如销售订单查询）不需要映射。

五、安装技能并挂到智能体

要办的事：让员工在对话里能用到金蝶能力。

点哪里：

1. 「开发 → 技能开发」，找到「金蝶云星空 业务」技能包，安装。
2. 「开发 → 智能体开发」，编辑需要的智能体（或新建一个「金蝶助手」），挂上这个技能。

六、对话验证

在工作台问：

问法	期望
查一下本月华东客户的销售订单	列出销售订单，含单据编号、日期、客户、价税合计、状态
华东精密机械最近的应收单合计多少	按客户查应收并汇总
我的费用报销到哪一步了	只列本人的；没绑定账号时提示先绑定
帮我新建一个客户「某某公司」	先出确认卡片，确认后才提交
帮我把这张订单审核了	明确拒绝

客户改过金蝶字段怎么办

预置模板按金蝶标准版的表单和字段写。客户做过二次开发、改过字段或启用了别的表单时，在「能力」抽屉里点「模板」改调用模板即可，不用改代码：

{
  "operation": "query",
  "formId": "SAL_SaleOrder",
  "fieldKeys": ["FBillNo", "FDate", "FCustId.FName", "FBillAllAmount", "FDocumentStatus"],
  "fieldLabels": ["单据编号", "日期", "客户", "价税合计", "单据状态"],
  "filters": [
    { "param": "startDate", "expr": "FDate>='{value}'" },
    { "param": "customerName", "expr": "FCustId.FName like '%{value}%'" }
  ],
  "orderString": "FDate DESC",
  "limit": 20
}

字段	说明
operation	query 查询列表、view 查看单据、save 保存
formId	金蝶表单标识
fieldKeys / fieldLabels	要取的字段和对应的中文名，一一对应
filters	模型给了对应参数时才拼进条件，多条用 AND 连接；参数里的单引号会被转义
orderString / limit	排序和最多返回条数

要注意什么：已上架能力的模板改动后会自动退回待审，需要重新审核上架。写入类模板（save）的风险等级必须是写入。

常见问题

现象	先查什么
测试连接失败	地址是否带 /k3cloud；账套 ID、账号密码；智能体服务能否访问金蝶服务器
员工问了但智能体没去查金蝶	能力是否已上架；技能是否已安装并挂到当前智能体
提示还没有绑定账号	在「账号映射」里给这名员工绑定金蝶员工编码
查出来的字段是空的	客户改过字段，按上一节改模板
结果里有「演示数据」字样	连接还开着演示模式