对比与迁移深度场景内容4 分钟阅读matrix

只读与写入:按操作后果划三档

按操作后果把系统接入分成只读、写入与审批三档,比较各自需要的凭据、确认环节、日志要求与失败处理,并给出从只读到写入的推进顺序与接口清单写法。

只读和写入的差别不在接口数量,在出错之后能不能收回。只读错了重查一次,写入错了要走更正流程,审批错了影响业务状态。三档分开设计,接入才敢推进。

三档的界限

对照材料:FastGPT 官方说明。

只读档:查询库存、读取工单状态、拉取客户资料。出错的影响是看到旧数据或空数据,重查即可恢复。写入档:创建工单、回填处理结论、更新标签。出错会影响业务记录,需要更正或冲销。审批档:审批、驳回、撤回。出错会改变业务状态,可能触发对外承诺。

三档的凭据、确认环节、日志要求依次提高,验收的动作也依次变重。把三档混在一套凭据里,等于用最高风险的配置做最低风险的查询,安全评审一眼就能看出来。

对照

项只读写入审批
凭据只读账号或只读密钥限定字段的写权限不授予自动化账号
人工确认不需要提交前确认人在原系统操作
幂等要求不需要必须必须
失败处理重试,记录回滚或冲销人工介入
日志要求记录调用记录调用与业务单号记录到人

从只读开始的理由

先做只读,是因为它能在最短时间里验证三件事:接口通不通、字段够不够、数据新不新。三件事验证完,写入的方案才有依据。写入联调还涉及目标业务状态,定位接口和字段问题时,应同时确认请求是否已经执行,再决定更正或重试。

只读阶段还要确定字段白名单。接口能给多少字段,与业务需要多少字段,往往不一致。白名单取交集,多出来的字段不接,减少扩散面。

写入的四个必备件

写入档要配四件东西。幂等键,防止重试造成重复单据;字段级权限,只允许写约定字段;确认环节,提交前由人确认一次;回滚路径,写错之后怎么冲销。

四件里最容易漏的是回滚路径。很多系统的写接口没有冲销接口,只能人工在业务系统里改。这种情况要在方案里写明:错误处理由业务方人工完成,不由 Agent 自动更正。

审批为什么不交给自动化

审批改变的是业务状态,一旦自动执行,责任落不到具体人。可行的设计是 Agent 准备材料与建议,人在原系统里点确认。这样既保留了效率,也保留了责任链。

方案应写清业务写入、审批与对外披露由谁确认,以及确认后怎样执行和记录。评审时用实际任务检查确认对象、操作身份和结果,发现缺失便补齐对应步骤。

推进顺序与验收

推荐顺序是只读、写入、审批逐档推进,每档跑通再进下一档。每档的验收动作是成功与失败各一条路径,加一次异常演练。

异常演练要覆盖三种情况:接口超时、返回格式异常、业务侧拒绝。三种情况下的降级表现写进记录,下一次联调按记录复现,不必重新设计。

一条判断口诀

能用查询解决的,不引入写入;能人工确认的,不自动提交;能留在原系统的,不搬到 Agent 里。三句话按顺序用,接入的边界会自然收窄。

接口清单的写法

清单按接口一行,六列:用途、档位、字段、调用身份、失败处理、负责人。字段一列写实际返回或提交的字段名,不写“客户信息”这类概括;调用身份一列写服务账号还是用户身份;失败处理写重试几次、失败后通知谁。清单由集成方起草、业务方确认字段、IT 确认身份,三方签字后作为联调依据。

谁签接口清单

接口清单三方签字:集成方签字段与调用方式,业务方签字段是否够用,IT 签调用身份与权限范围。三方签字之后,联调期间改字段要走变更,不能口头约定。这一条能减少联调后期的大量返工,代价是前期多开一次会,会议结论直接作为后续变更的基线,不再另行纪要。

数据来源

主题版本来源
接口与插件机制、模型与渠道支持当期商业方案FastGPT 商务咨询:授权、部署与支持范围
工具输入输出与应用调用方式现行功能文档选择工具与 Skill
MCP 与外部渠道配额v4.17.3self-host/upgrading/4-17/4173