业务内部能力怎样先协议化

一句话收获：Agent 能理解业务过程的前提，是内部调用已经拥有机器可读契约。

这个场景在解决什么问题

想让 Agent 帮你操作公司内部的业务系统（查订单、建任务、改状态），不能直接让它去"看网页、点按钮"——页面背后藏着大量只有人懂的上下文。真正可行的路是：先把业务能力"协议化"，给它一个机器能读懂的契约。

这个场景的目标（goal）是：实现内部 API、Tool Contract、权限、状态和回执。观察点（observation）是：从隐藏在页面中的动作形成可供 Agent 使用的业务能力——把原来人肉在页面上点的动作，抽成一个 Agent 能安全调用的能力。

它值得单独学，因为它讲清了一个关键门槛：Agent 能不能理解业务过程，不取决于模型多聪明，而取决于内部调用有没有机器可读的契约。没有契约，模型只能瞎猜。

先理清这条判断链（文字版）

把"页面动作"变成"Agent 能力"是一条链，先认清楚"能力是什么"，再补契约，再写适配代码，最后看回执：

先看识别业务能力——把"读取对象、查询状态、创建待复核任务"这类动作从页面流程里分离出来，先用业务意图命名。
再看补齐 Tool Contract——声明用途、输入输出、权限、前置状态、副作用、幂等、错误和证据。
然后看生成适配代码——Coding Agent 连接现有业务服务，不绕过服务直写数据库，执行前还要对象和 Schema 校验。
最后看回执与验收——工具返回对象、状态、副作用、是否可重试、后续查询入口，回执再进入独立业务验收。

逐层详解

第 1 步：识别业务能力

原文：将读取对象、查询状态、创建待复核任务等动作从页面流程中分离。

白话：先去看业务系统里人是怎么操作的，把那些"真正有业务意义"的动作挑出来——比如"读取一个对象""查询一个状态""创建一个待复核任务"，把它们从页面的一堆点击流程里单独拎出来，定义成一个个能力。

类比：像给老工厂做自动化改造，先得看清楚工人手上的工序里，哪些是"核心动作"（拧这个螺丝、装那个零件），把它们从一堆零碎操作里分离出来，才能谈得上上机器人。

举例：审批系统里，人工操作是"登录 → 打开待办列表 → 点开某条申请 → 看信息 → 点'创建复核任务'"。真正有业务意义的能力是"创建一个待复核任务"，前面那些登录、翻页都是噪音，应该抽出来定义成一个叫"创建待复核任务"的能力。

为什么重要：页面操作隐含大量人的上下文。页面上的按钮顺序、默认值、灰色不可点状态，都藏着只有人看得懂的隐含信息，直接让 Agent 学点按钮是行不通的，必须先分离出干净的"能力"。

怎么验证（证据点）：

能力目的：每个能力能说清"它是为了干什么业务"。
业务对象：这个能力操作的对象（订单、任务、申请）是明确的。
权威来源：能说清这个能力的权威数据从哪个系统来。

别踩的坑（边界）：把数据库 CRUD 暴露出来不等于业务协议化。直接把"增删改查数据库"暴露给 Agent，是偷懒且危险的——那不是业务能力，是裸操作，业务规则（校验、权限、副作用）全没带上。

落地检查：先用业务意图命名能力。落地时能力要用业务语言命名（"创建待复核任务""查询订单状态"），而不是技术语言（"insert 一条记录"），命名对了才能谈契约。

第 2 步：补齐 Tool Contract

原文：声明用途、输入输出、权限、前置状态、副作用、幂等、错误和证据。

白话：给每个能力写一份完整的"工具契约"（Tool Contract），说清楚：它是干嘛的、输入什么输出什么、谁有权调用、调用前要满足什么前置状态、调用后会有什么副作用、重复调用会不会出问题（幂等）、会报什么错、以及能给什么证据。

类比：像给家电写说明书，不能只写"按这个键"，要写清楚"电压多少、装哪、按下去会怎样、连续按两次会不会坏、坏了看哪个指示灯、保修凭证在哪"。

举例：给"创建待复核任务"写契约：用途=为某笔申请建立人工复核；输入=申请 ID、复核类型；输出=新任务 ID；权限=仅复核组；前置=申请必须处于"待复核"状态；副作用=创建一条新任务；幂等=同一申请重复调用不重复建任务；错误=申请不存在返回 404；证据=返回任务 ID 供后续查询。

为什么重要：模型需要理解什么时候可以用以及如何判断结果。光知道"有这个工具"没用，模型得知道"什么条件下能调""调完了怎么看成功没成功"，这些全靠契约说清楚。

怎么验证（证据点）：

前置条件：调用前必须满足的状态是否写明。
副作用：调用后会产生什么改变是否写明。
查询入口：调用后从哪查结果是否写明。

别踩的坑（边界）：自然语言说明不能替代后端检查。契约里用大白话写的"需要 XX 权限"，不能只是说说而已，后端必须真的有对应的权限校验和状态检查，否则契约就是一张废纸。

落地检查：契约语义要映射实际 API。落地时契约里的每一项（权限、前置、副作用、幂等）都要能映射到真实后端 API 的具体实现，不能有"契约写一套、代码做另一套"的断层。

第 3 步：生成适配代码

原文：Coding Agent 连接现有业务服务，不绕过服务直写数据库。

白话：契约定好后，让 Coding Agent 去生成"适配器"代码，把 Agent 的调用连到现有业务服务上。关键是：必须走业务服务，不能为了图省事绕过服务、直接写数据库。

类比：像给老系统接一个新前端，新前端必须通过老系统已有的接口去访问，不能为了省事直接去改数据库表，否则老系统里的业务规则（校验、日志、权限）全被绕过了。

举例：Agent 要"创建待复核任务"，适配代码应该调用审批系统已有的"创建任务" API（复用它的权限检查、状态机、日志），而不是直接往任务表里 insert 一行——直写数据库会绕过所有业务规则，页面、程序和 Agent 就会各用一套规则。

为什么重要：页面、程序和 Agent 共享同一业务规则。只有都走同一个业务服务，三者的行为才一致；一旦 Agent 直写数据库，它就成了一套独立的、没人维护的旁路规则。

怎么验证（证据点）：

API 复用：确认走的是现有业务 API，不是新开旁路。
权限一致：Agent 调用的权限与页面/程序一致。
状态一致：状态变更走的是同一套状态机。

别踩的坑（边界）：接口能调用不证明参数指向唯一对象。接口通了、没报错，不代表你传的参数真的指向"那个唯一的对象"——可能参数模糊，指向了多个对象，执行前还要校验。

落地检查：执行前还要对象和 Schema 校验。落地时在真正执行前，要校验"对象唯一存在""参数符合 Schema"，通过之后才执行，不能接口能通就直接跑。

第 4 步：回执与验收

原文：工具返回对象、状态、副作用、是否可重试和后续查询入口。

白话：工具调用完，不能只返回一个"成功/失败"，要返回一份结构化"回执"：操作的对象是什么、当前状态是什么、产生了什么副作用、失败了能不能重试、下次从哪查。

类比：像去办事窗口办完事，拿到的不只是"办好了"三个字，而是一张回执单——上面写着办的事、当前进度、留了凭证、下次去哪查。

举例："创建待复核任务"成功后，返回：对象=任务 ID 12345、状态=已创建待复核、副作用=生成一条复核任务、可重试=是（幂等）、查询入口=GET /task/12345。这样下一轮对话就有了结构化的环境反馈，知道"现在走到哪了"。

为什么重要：下一轮需要结构化环境反馈。Agent 是多轮循环的，这一轮的结果要作为下一轮的输入，如果回执只有一句"成功了"，下一轮就无从下手，必须结构化。

怎么验证（证据点）：

对象明确：返回的操作对象 ID 是明确的。
状态当前：返回的状态是调用后的最新状态。
证据可查：返回的证据（ID、回执号）能再去查询验证。

别踩的坑（边界）：工具成功仍不等于任务整体完成。这个工具调用成功，只代表"这一步做成了"，不代表"整个任务完成"——可能还有后续步骤，别把单步成功当成终局成功。

落地检查：回执进入独立业务验收。落地时工具的回执只是中间产物，还要进入一个独立的业务验收环节，由验收器去判断"业务上到底完成没有"，而不是工具自己说完成就完成。

落地可行性小结

本场景涉及的核心技术栈：内部 API、Tool Contract（工具契约）、Coding Agent（生成适配器）、Schema 校验、幂等、回执（receipt）、独立业务验收。

真实落地要检查的事：

能力要先"协议化"，用业务意图命名，写清用途/输入输出/权限/前置/副作用/幂等/错误/证据。
适配代码必须走现有业务 API，禁止绕过服务直写数据库。
契约语义要能映射到真实 API 实现，不能"文档一套、代码一套"。
工具回执要结构化（对象、状态、副作用、可重试、查询入口），并进入独立业务验收。

常见坑：

直接把数据库 CRUD 暴露给 Agent，当成"业务能力"，绕过所有业务规则。
契约里写了权限和前置条件，但后端没有对应校验，契约形同虚设。
接口通了就以为"参数指对了对象"，没做对象唯一性和 Schema 校验。
把工具单步成功当成任务整体完成，缺独立业务验收。

回顾

Agent 能理解业务过程的前提，是内部调用已经有机器可读契约，不是模型聪明。
能力要先用业务意图命名，再补完整 Tool Contract（权限/前置/副作用/幂等/错误/证据）。
适配代码必须复用现有业务服务，不能直写数据库，否则规则分裂。
回执要结构化，并且工具成功≠任务完成，还要进独立业务验收。
自然语言说明替代不了后端校验，契约语义必须映射真实 API。