erpnew/docs/WECOM_APP_INTEGRATION_GUIDE.md

企业微信应用接入说明

本文档面向企业微信自建应用开发组，说明当前 AI Agent 的接入方式、适合的消息入口、菜单和提问引导建议、能力边界，以及消息处理侧需要注意的事项。

1. 目标

当前 Agent 不是通用对话机器人，而是一个“受约束的业务查询助手”。

它适合处理以下两类问题：

1. MES / 出货 / 运输车辆等业务数据查询。
2. 指定客户的财务记录查询。

它不适合承担以下职责：

1. 开放式闲聊。
2. 多轮澄清式对话。
3. 写入、审批、修改业务数据。
4. 复杂统计分析和自定义报表。

因此，企业微信侧的入口设计应尽量采用“菜单驱动 + 明确提问”的方式，而不是把它当成一个无限制聊天窗口。

2. 当前调用入口

当前服务对外提供的 Agent 入口为：

• POST /agent

健康检查：

• GET /health

当前请求体：

{
  "message": "查询华东未出货出货单",
  "merchant_id": 1
}

当前响应体：

{
  "reply": "目前查询到华东区域没有未出货的出货单（结果为0条）。"
}

说明：

• message 为发送给 Agent 的自然语言问题。
• merchant_id 目前只对商户隔离型业务 API 生效。
• 财务查询当前不依赖 merchant_id。
• 返回值是自然语言文本，面向企业微信 markdown 消息渲染。

3. 当前能力范围

3.1 商户业务查询

当前已接入以下业务能力：

1. 查询 MES 设备列表。
2. 查询指定日期范围内的 MES 生产安排。
3. 查询运输车辆详情。
4. 查询未进入送货单的出货单。

这些能力依赖：

• merchant_id

因此企业微信应用侧如果要接这类查询，建议在进入 Agent 前就明确当前商户身份，或由调用方稳定注入 merchant_id。

3.2 财务查询

当前已接入以下财务记录类型：

1. 销售记录
2. 销退记录
3. 收款记录
4. 退款记录

财务查询支持：

• 单选一种记录类型
• 多选多种记录类型
• 宽泛的“财务记录”查询

财务查询还能区分：

1. 真实资金变动
2. 挂账 / 冲减 / 欠款调整

4. 当前明确不支持的能力

企业微信应用开发组应优先在入口侧理解这些边界，因为这些能力不应引导给 Agent。

4.1 不支持写操作

当前不支持：

1. 写入财务数据
2. 修改财务数据
3. 删除财务数据
4. 审批财务数据
5. 纠正财务数据
6. 写入业务单据

如果用户发起这类请求，推荐在企业微信应用侧直接拦截，或允许 Agent 返回标准拒绝说明。

4.2 不支持复杂统计

当前财务接口只支持“查记录”，不支持复杂统计分析。

允许的上限只有：

1. 对返回记录做直接计数。
2. 对返回记录做直接累计。

当前不支持：

1. 按季度汇总
2. 按月汇总
3. 按年汇总
4. 环比
5. 同比
6. 趋势分析
7. 占比分析
8. 分组统计
9. 筛选后再累计
10. 小计、分类汇总、派生统计口径

如果企业微信应用已经能判断是这类诉求，建议不要直接把这类问题送给 Agent。

5. 企业微信消息渲染约束

当前 Agent 的回复是按企业微信应用消息中的 markdown 消息来约束的。

已知约束如下：

1. 企业微信 markdown 只支持 markdown 子集。
2. content 最长不超过 2048 字节，UTF-8 编码。
3. 当前 Agent 会尽量把回复压缩在约 1200 字节以内。
4. 不应使用表格。
5. 不应使用 fenced code block。
6. 不应使用复杂嵌套列表。
7. 不应依赖复杂 HTML 排版。

当前更适合的展示形式：

1. 一段简洁结论。
2. 2 到 5 条短列表。
3. 必要时附少量关键字段。

因此，企业微信应用侧不应期待 Agent 返回：

1. 表格型结果
2. 长篇报告
3. 大批量明细完整铺开

6. 入口设计建议

6.1 推荐采用单入口调用，多菜单引导

当前技术上只需要一个 Agent 接口入口：

• POST /agent

但在企业微信应用层，建议不要只给一个“自由提问”入口。更合适的是：

1. 菜单项负责限定业务范围。
2. 菜单点击后，用明确提示语引导用户输入必要字段。
3. 应用层把整理后的自然语言问题发送给 /agent。

换句话说，推荐是“多个菜单入口，共用一个 Agent API”。

6.2 推荐菜单分组

建议至少拆成两大类：

1. 生产/物流类查询
2. 财务类查询

财务类再细分为：

1. 查询客户销售记录
2. 查询客户销退记录
3. 查询客户收款记录
4. 查询客户退款记录
5. 查询客户全部财务记录

生产/物流类可拆为：

1. 查询 MES 设备
2. 查询生产安排
3. 查询车辆信息
4. 查询未出货出货单

7. 提问引导建议

7.1 总原则

企业微信侧不应引导用户输入过于自由的问题，而应尽量引导输入“Agent 已支持的字段”。

推荐原则：

1. 一次只问一类问题。
2. 提示词里直接说明需要提供什么。
3. 对关键参数给示例。
4. 不要让用户猜系统支持哪些写法。

7.2 财务类推荐引导文案

查询客户销售记录

推荐引导：

请输入客户名称，例如：查询杭州某客户的销售记录

查询客户销退记录

推荐引导：

请输入客户名称，例如：查询杭州某客户的销退记录

查询客户收款记录

推荐引导：

请输入客户名称，例如：查询杭州某客户的收款记录

查询客户退款记录

推荐引导：

请输入客户名称，例如：查询杭州某客户的退款记录

查询客户全部财务记录

推荐引导：

请输入客户名称，例如：查询杭州某客户的财务记录

查询挂账或冲减

推荐引导：

请输入客户名称，并明确说明挂账或冲减，例如：查询杭州某客户的收款挂账调整记录

7.3 生产/物流类推荐引导文案

查询 MES 设备

推荐引导：

请输入查询需求，例如：查询当前商户的 MES 设备

查询生产安排

推荐引导：

请输入日期范围，例如：查询 2026-05-01 到 2026-05-07 的生产安排

查询车辆信息

推荐引导：

请输入车牌号，例如：查询车牌 粤A12345 的车辆信息

查询未出货出货单

推荐引导：

请输入地区，例如：查询华东未出货出货单

8. 建议的应用层预处理

企业微信应用侧建议做以下最小预处理：

1. 注入 merchant_id，如果当前入口属于商户业务场景。
2. 保留用户原始问题，不要做过度改写。
3. 可以在菜单点击后，补一个简短上下文前缀，例如：
   • 当前是财务查询场景：查询杭州某客户的销退记录
   • 当前是生产安排查询场景：查询 2026-05-01 到 2026-05-07 的生产安排
4. 不要在应用层生成复杂长提示词，避免和 Agent 提示词互相冲突。

9. 建议的应用层拦截规则

以下问题建议在企业微信应用层直接拦截，或者至少标记为“超出当前 Agent 支持范围”：

1. 帮我新增一条财务记录
2. 把这个客户的退款改掉
3. 审批这笔收款
4. 按季度汇总这个客户的销售和回款
5. 统计今年每个月的销退趋势
6. 按地区筛选后累计某客户收款

推荐返回说明：

当前入口只支持记录查询，不支持写入、修改、审批或复杂统计分析。

10. 建议的调用方式

10.1 财务查询示例

{
  "message": "查询杭州某客户的销退记录"
}

10.2 商户业务查询示例

{
  "message": "查询华东未出货出货单",
  "merchant_id": 1
}

10.3 财务能力说明类示例

{
  "message": "你可以查询哪些财务数据？是否可以多选？"
}

期望回答方向：

1. 支持销售、销退、收款、退款。
2. 可以单选，也可以多选。
3. 如果问“财务记录”，可以查全部四类。

11. 推荐的消息处理流程

推荐流程如下：

1. 用户点击菜单。
2. 企业微信应用展示该菜单对应的引导语。
3. 用户输入问题。
4. 应用层判断是否需要补 merchant_id。
5. 应用层判断是否属于明显超范围请求。
6. 如果在支持范围内，则调用 /agent。
7. 将 reply 直接作为企业微信 markdown 消息发送。

12. 入口选择建议

如果开发组需要判断“应该做几个入口”，建议如下：

方案 A：一个统一输入入口

优点：

1. 技术实现最简单。
2. 前端交互最少。

缺点：

1. 用户容易提超范围问题。
2. 参数缺失率会更高。
3. 结果稳定性较弱。

方案 B：按业务域拆菜单，共用一个 Agent API

优点：

1. 更符合当前 Agent 的能力边界。
2. 更容易做提问引导。
3. 回复稳定性更高。
4. 更适合企业微信菜单场景。

缺点：

1. 菜单设计需要更多前期整理。

当前更推荐：

• 采用方案 B。

13. 当前接入结论

对于企业微信应用开发组，当前最合适的接入方式不是“开放聊天入口”，而是：

1. 用菜单限制问题范围。
2. 用引导语约束用户输入。
3. 用一个统一的 /agent 入口承接调用。
4. 在应用层提前拦截写操作和复杂统计类请求。

这样能最大程度发挥当前 Agent 的查询能力，同时避免把不支持的能力暴露成错误体验。