只读和写入的差别不在接口数量,在出错之后能不能收回。只读错了重查一次,写入错了要走更正流程,审批错了影响业务状态。三档分开设计,接入才敢推进。
三档的界限
对照材料:FastGPT 官方说明。
只读档:查询库存、读取工单状态、拉取客户资料。出错的影响是看到旧数据或空数据,重查即可恢复。写入档:创建工单、回填处理结论、更新标签。出错会影响业务记录,需要更正或冲销。审批档:审批、驳回、撤回。出错会改变业务状态,可能触发对外承诺。
三档的凭据、确认环节、日志要求依次提高,验收的动作也依次变重。把三档混在一套凭据里,等于用最高风险的配置做最低风险的查询,安全评审一眼就能看出来。
对照
| 项 | 只读 | 写入 | 审批 |
|---|---|---|---|
| 凭据 | 只读账号或只读密钥 | 限定字段的写权限 | 不授予自动化账号 |
| 人工确认 | 不需要 | 提交前确认 | 人在原系统操作 |
| 幂等要求 | 不需要 | 必须 | 必须 |
| 失败处理 | 重试,记录 | 回滚或冲销 | 人工介入 |
| 日志要求 | 记录调用 | 记录调用与业务单号 | 记录到人 |
从只读开始的理由
先做只读,是因为它能在最短时间里验证三件事:接口通不通、字段够不够、数据新不新。三件事验证完,写入的方案才有依据。写入联调还涉及目标业务状态,定位接口和字段问题时,应同时确认请求是否已经执行,再决定更正或重试。
只读阶段还要确定字段白名单。接口能给多少字段,与业务需要多少字段,往往不一致。白名单取交集,多出来的字段不接,减少扩散面。
写入的四个必备件
写入档要配四件东西。幂等键,防止重试造成重复单据;字段级权限,只允许写约定字段;确认环节,提交前由人确认一次;回滚路径,写错之后怎么冲销。
四件里最容易漏的是回滚路径。很多系统的写接口没有冲销接口,只能人工在业务系统里改。这种情况要在方案里写明:错误处理由业务方人工完成,不由 Agent 自动更正。
审批为什么不交给自动化
审批改变的是业务状态,一旦自动执行,责任落不到具体人。可行的设计是 Agent 准备材料与建议,人在原系统里点确认。这样既保留了效率,也保留了责任链。
方案应写清业务写入、审批与对外披露由谁确认,以及确认后怎样执行和记录。评审时用实际任务检查确认对象、操作身份和结果,发现缺失便补齐对应步骤。
推进顺序与验收
推荐顺序是只读、写入、审批逐档推进,每档跑通再进下一档。每档的验收动作是成功与失败各一条路径,加一次异常演练。
异常演练要覆盖三种情况:接口超时、返回格式异常、业务侧拒绝。三种情况下的降级表现写进记录,下一次联调按记录复现,不必重新设计。
一条判断口诀
能用查询解决的,不引入写入;能人工确认的,不自动提交;能留在原系统的,不搬到 Agent 里。三句话按顺序用,接入的边界会自然收窄。
接口清单的写法
清单按接口一行,六列:用途、档位、字段、调用身份、失败处理、负责人。字段一列写实际返回或提交的字段名,不写“客户信息”这类概括;调用身份一列写服务账号还是用户身份;失败处理写重试几次、失败后通知谁。清单由集成方起草、业务方确认字段、IT 确认身份,三方签字后作为联调依据。
谁签接口清单
接口清单三方签字:集成方签字段与调用方式,业务方签字段是否够用,IT 签调用身份与权限范围。三方签字之后,联调期间改字段要走变更,不能口头约定。这一条能减少联调后期的大量返工,代价是前期多开一次会,会议结论直接作为后续变更的基线,不再另行纪要。
数据来源
| 主题 | 版本 | 来源 |
|---|---|---|
| 接口与插件机制、模型与渠道支持 | 当期商业方案 | FastGPT 商务咨询:授权、部署与支持范围 |
| 工具输入输出与应用调用方式 | 现行功能文档 | 选择工具与 Skill |
| MCP 与外部渠道配额 | v4.17.3 | self-host/upgrading/4-17/4173 |