Integration · ERP / CRM 接入
商户把自己那套 ERP / CRM 接进来；agent 需要时问一次，答案变成一条可追溯的事实。
入口：console → Integrations（
/console/integrations）
一句话
平台不复制你 ERP 里的数据，也不要求你先做一次全量同步。 你在控制台里填自己实例的地址与凭据，平台把它变成一个可调用的能力： agent 需要库存时问一次，拿到的答案作为一条事实记下来，谁在什么时候问了什么，可追。
支持的连接器
| 分类 | 连接器 | 典型能力 |
|---|---|---|
| ERP | 金蝶云星空、用友 YonSuite、聚水潭、旺店通、SAP S/4HANA | 库存查询、订单查询/创建 |
| CRM | Salesforce | 客户查询、商机查询 |
| 自建 | 通用 REST | 通用查询、通用写入 |
目录是数据，不是代码：加一家厂商只改 connector-catalog.ts 里的数组， 业务逻辑一行不动。能力路径有出厂默认值，也可以在连接里覆盖。
四步接入
| 步骤 | 你做什么 | 平台做什么 |
|---|---|---|
| 1. 选连接器 | 选厂商 / 自建 | 给出必须填的凭据字段与可开放的能力 |
| 2. 填地址与凭据 | 填自己实例的地址、账号或 Token | 校验地址、加密凭据、落库为「未自检」 |
| 3. 连通性自检 | 点一次「自检」 | 真的发一次请求，记录 HTTP 状态与耗时 |
| 4. 发布 | 点「发布」 | 把勾选的能力注册成 agent 可调用的 skill |
自检通过（外部系统有响应）才能发布。地址对但凭据错了也会被指出来（HTTP 401）， 这是一个能改的配置问题，不会把你卡在「发不出去」。
地址为什么有白名单
平台的服务器会真的去请求你填的地址。如果允许任意 URL，就等于让登录用户指挥 平台去访问内网服务（SSRF）。所以：
- 只允许 HTTPS
- 预置连接器要求域名命中厂商后缀；私有化部署请选「通用 REST」
- 拒绝本机、内网、链路本地、云元数据地址与常见管理端口
- 发请求前用真实 DNS 解析结果再复核一次
- 自检不跟随重定向
- 能力路径只能是相对路径
自托管、且实例就在内网时，由运维用 INTEGRATION_ALLOW_HOSTS 显式放行这些主机 （默认空）：放行只跳过「本机 / 内网 / 管理端口」检查，协议与厂商后缀仍然校验。
残余风险：校验与请求之间域名可能被重新解析到内网（DNS rebinding）。 彻底的做法是让平台出网走代理，这一点我们如实写在模块 README 里，不假装已经解决。
凭据怎么存
- AES-256-GCM 加密后入库，主密钥来自部署侧注入的
INTEGRATION_SECRET_KEY - 生产环境没配这把钥匙时直接失败，不退回默认值
- 接口只回「已配置哪些字段」，明文与密文都不出接口、不进日志
- 换主密钥后旧凭据解不开，需要重填 —— 自检会明确报出来
撤销与一致性
| 你的操作 | 平台的行为 |
|---|---|
| 改实例地址 | 撤销已发布的能力，并要求重新自检 |
| 改凭据 | 撤销已发布的能力（旧请求头已失效） |
| 取消某个能力 | 撤销那一个 skill，其余保留 |
| 停用 / 删除连接 | 撤销全部 skill |
进程重启后，平台会读库里状态为「已就绪」的连接，把能力重新注册一遍 —— 不需要你重新点发布。
不做的事
- 不做全量数据同步，也不做只读镜像（那是模式 B / C，见「外部集成」）
- 不实现厂商专有签名算法：非敏感凭据以
x-conn-<key>请求头透传， 需要时你在前面挂一层轻量适配端点 - 不做重试与熔断（只做超时）
相关文档
- External Skill 能力集成：能力怎么被调用、结果怎么落事实
libs/modules/src/integration/README.md：实现细节、安全清单、测试证据