以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。
「这个 Agent 能接我们的 CRM 吗?」这是任务定义阶段最常被问到的问题。问的人通常期待一个二选一的答案:能,或者不能。但真实的产品判断不是二选一,而是先拆开:接的是这个系统的哪一层?读它的数据、写它的字段,还是触发它的流程?三种接法带来的风险、验收方式和回滚成本完全不同。
集成地图要解决的就是这件事。它不是系统清单,不是「已对接多少个平台」的营销数字,而是一张把每个外部系统拆成接口、标出副作用、排好接入顺序的工作图。地图画完,产品经理才能回答:第一步接什么,哪些接口永远不接,哪些接了也必须有人确认。
集成地图不是系统清单
系统清单回答「接了多少」,集成地图回答「接在哪一层」。同样接一个工单系统,只读工单正文和写入工单状态是两件不同的事:前者不改变任何外部状态,后者会让下一个打开工单的人看到不同的队列和优先级。把两者都写成「已对接工单系统」,等于把风险藏进了名词里。
一张可用的集成地图至少要有七个字段:
| 字段 | 要回答的问题 | 写错会怎样 |
|---|---|---|
| 系统 | 接的是哪个外部系统 | 把同一系统的不同接口混为一谈 |
| 接口 | 具体读或写哪个对象 | 验收时说不清到底改了什么 |
| 类型 | 读、写还是触发 | 风险等级被低估 |
| 数据方向 | 数据从哪来到哪去 | 权限面与隐私边界模糊 |
| 失败后果 | 这一步错了会怎样 | 回滚方案无从设计 |
| 回滚方式 | 能不能撤回、撤回要多久 | 出事时只能人工补救 |
| 负责人 | 谁授权、谁维护 | 权限过期后无人回收 |
七个字段里,最容易被省略的是「失败后果」和「回滚方式」。团队在演示阶段只关心接口能不能通,不关心通了之后错一次会留下什么。但 Agent 产品的风险恰恰不在「通不通」,而在「通了之后做错了怎么办」。一张没有失败后果的集成地图,只能用于立项,不能用于上线。
三类接口:读、写、触发
把所有接口压成三类,是因为三类的副作用形态不同。读只改变模型看到的上下文;写改变外部系统的状态;触发会让外部系统自己开始一段流程。副作用越往外走,撤回越难,需要的人在环上的位置越靠前。
| 类型 | 典型接口 | 副作用 | 默认风险 | 回滚难度 |
|---|---|---|---|---|
| 读 | 查工单、读商品、拉报告 | 无外部状态变化 | 低 | 不需要回滚 |
| 写 | 改队列、改价格、写草稿 | 改变字段或文件 | 中 | 有前值即可回滚 |
| 触发 | 发通知、提交审批、调用外部流程 | 引发他人或他系统的动作 | 高 | 通常不能完全撤回 |
读的风险低,不等于没有风险。它可能读到过期数据,可能读到超出任务需要的隐私字段,也可能因为权限给得太大而看到不该看的东西。读的风险主要落在数据治理,而不是业务状态。
写的关键是「有没有前值」。改价格时记录原价,改库存时记录原库存,改队列时记录原队列,才有回滚的可能。没有前值的写操作,即使技术上能改回去,也无法证明改回了什么。
触发是最容易被低估的一类。发一条通知看起来只是「发消息」,但通知一旦到达供应商,对方可能已经开始备货或调价。技术上撤回一条消息,不等于撤回对方已经采取的行动。所以触发类接口默认按高风险处理,除非能证明外部流程有幂等和撤销机制。
三案例各画一张地图
三个案例的任务不同,集成地图的形状也不同。把它们并排看,可以看到「自主档越高,接口越往外走」这条规律。
A Relay:读两份、写一份
A Relay 是 Northwind 的客服工单分诊 Agent,月工单量 26,400 单,人工分诊基线 3.5 分钟一单。它的地图只有三个接口:
| 系统 | 接口 | 类型 | 数据方向 | 失败后果 | 回滚 |
|---|---|---|---|---|---|
| 工单系统 | 读工单正文、客户等级、历史工单 | 读 | 外部 → Agent | 建议依据不足 | 不需要 |
| 工单系统 | 写队列归属与优先级 | 写 | Agent → 外部 | 工单进错队列 | 改回原队列 |
| 知识库 | 取首响模板编号 | 读 | 外部 → Agent | 模板不匹配 | 不需要 |
A 的地图里没有触发类接口。它不直接给客户发消息,只给支持人员一个建议。建议采纳率 78%,分诊正确率 91.4%,采纳后仍出错率 2.9%。这三个数字说明:A 的价值来自「人确认得快」,而不是「机器替人决定」。地图上那条写接口之所以安全,是因为它写的是内部队列,且人就在旁边。
B Quill:读一份、写两份
B Quill 是 Meridian 的客户报告起草 Agent,月报告量 606 份,人工基线 4.2 小时一份。它的接口集中在文件侧:
| 系统 | 接口 | 类型 | 数据方向 | 失败后果 | 回滚 |
|---|---|---|---|---|---|
| 数据平台 | 读客户数据包与上月报告 | 读 | 外部 → Agent | 初稿事实错误 | 不需要 |
| 图表引擎 | 渲染图表文件 | 写 | Agent → 草稿目录 | 图表与正文不一致 | 重新渲染 |
| 文档库 | 写 Markdown 初稿 | 写 | Agent → 草稿目录 | 初稿不可用 | 删除重写 |
B 的写接口都落在「草稿目录」,不碰客户门户。这是一个刻意设计的产品边界:Agent 可以生成,但不能发布。一次采纳率 63%,小改率 28%,返工率 9%,三档加起来才是审改工作的真实形状。如果 B 直接写客户门户,返工就不再是内部成本,而是客户可见的事故。
C Runner:读一份、写两份、触发一份
C Runner 是 Kettle 的电商运营任务执行 Agent,月任务量 13,200 个,人工基线 18 分钟一个。它的地图最靠外:
| 系统 | 接口 | 类型 | 数据方向 | 失败后果 | 回滚 |
|---|---|---|---|---|---|
| 商品中心 | 读商品、价格、库存 | 读 | 外部 → Agent | 判断依据过期 | 不需要 |
| 定价系统 | 改价格、改库存 | 写 | Agent → 外部 | 价格或库存错误 | 用前值回滚 |
| 通知系统 | 向运营与供应商发通知 | 触发 | Agent → 外部 | 对方已开始行动 | 只能补发更正 |
C 的自动完成率 78%,其余 22% 转人工;审计抽检比例 8%,单次复核 12 分钟。它的错误中 86% 可回滚,不可回滚错误率 0.238%。这组数字解释了为什么 C 的地图必须把「通知」单独标成触发:写价格错了还能用前值改回去,通知发错了,对方可能已经按错误信息行动。
为什么只读接入是最稳的第一步
只读接入之所以稳,不是因为它简单,而是因为它把「理解是否正确」和「动作是否安全」拆成了两个可以分别验收的问题。
第一,只读不改变外部状态。Agent 读错了工单,最坏结果是给出一条不准确的建议;人看一眼就能发现。写错了队列,下一个人会按错误队列处理;触发错了通知,外部伙伴会按错误信息行动。只读把错误的暴露面限制在「建议」这一层。
第二,只读可以和人工判断直接对比。让 Agent 先只读,再输出它认为的队列、优先级和模板编号,然后与人工分诊结果对照,就能在上线前得到一组可复算的一致率。这个动作不需要改任何系统,也不需要外部伙伴配合。
第三,只读能暴露数据质量问题。字段缺失、编码不一致、历史工单脏数据,这些问题在只读阶段就会显现。如果先做写接口,数据问题会被写操作放大,排查时很难分清是模型判断错了,还是输入本身就错了。
第四,只读给团队留出建立信任的时间。支持人员先看到「它读得懂工单」,才会愿意让它写队列;先看到「它写的队列我改过两次」,才会讨论要不要扩大范围。信任不是一次性授权,而是一串可观察的小成功。
但只读只是第一步,不是终点。一个永远只读的 Agent,价值停在建议层,用户仍要把结果手工复制到系统里。只读接入选的是「先证明理解力」,不是「永远不写」。地图上的写接口应该在只读阶段就跑通验收标准,只是先不打开。
只读也有三种风险
把只读说成零风险是另一种偷懒。只读至少有三类风险,产品文档里要单独写。
权限过大。 为了省事,团队常给 Agent 一个「读全部工单」的账号。它确实只需要读当前工单,但账号能看到所有客户的历史。正确的做法是按任务开数据范围:只读当前工单、当前客户、与分诊相关的字段。
数据过期。 只读接口返回的是某一刻的快照。工单在 Agent 读取后被人改过,建议就会基于旧状态。地图上要标出哪些接口有缓存、缓存多久、是否需要二次确认。
隐私越界。 工单正文里可能有客户的联系方式、合同金额、投诉记录。Agent 读这些字段是为了分诊,不代表可以把它写进建议、日志或提示词。读权限和用权限要分开写。
这三类风险不会因为「只是读」而消失。它们只是不会立刻造成业务状态错误,所以更容易被忽略。
把地图写成可运行的模型
下面这个模型把集成地图做成可检查的结构:每个接口带类型和可回滚标记,风险由副作用推导,接入顺序固定为读、写、触发。三个案例的地图也写在同一个文件里。
// file: src/task/08-1-integration-map.ts
// tier: L2
// verify: node --test test/task/08-1-integration-map.test.ts
// 集成地图:把每个外部系统拆成读、写、触发三类接口,再按风险排序。
// 地图只描述边界,不替产品决定要不要接。
import { CASES, type Profile } from "../cases.ts";
export type SurfaceKind = "read" | "write" | "trigger";
export type Surface = {
readonly system: string;
readonly kind: SurfaceKind;
readonly detail: string;
readonly reversible: boolean;
};
export type Risk = "low" | "medium" | "high";
export const KIND_LABEL: Record<SurfaceKind, string> = {
read: "只读",
write: "写入",
trigger: "触发",
};
// 接入顺序固定:先只读,再可回滚写入,最后才是触发。
export const SURFACE_ORDER: readonly SurfaceKind[] = ["read", "write", "trigger"];
// 只读不会改变外部状态;写入可回滚;触发会引发外部流程,通常不能完全撤回。
export function riskOf(surface: Surface): Risk {
if (surface.kind === "read") return "low";
if (surface.kind === "write") return surface.reversible ? "medium" : "high";
return "high";
}
export type IntegrationMap = {
readonly caseKey: Profile["key"];
readonly surfaces: readonly Surface[];
readonly counts: Record<SurfaceKind, number>;
};
export function countKinds(
surfaces: readonly Surface[],
): Record<SurfaceKind, number> {
const counts: Record<SurfaceKind, number> = { read: 0, write: 0, trigger: 0 };
for (const surface of surfaces) counts[surface.kind] += 1;
return counts;
}
export function buildMap(
caseKey: Profile["key"],
surfaces: readonly Surface[],
): IntegrationMap {
return { caseKey, surfaces, counts: countKinds(surfaces) };
}
export const MAPS: Record<Profile["key"], IntegrationMap> = {
A: buildMap("A", [
{
system: "ticketing",
kind: "read",
detail: "读取工单正文、客户等级与历史工单",
reversible: true,
},
{
system: "ticketing",
kind: "write",
detail: "写入队列归属与优先级",
reversible: true,
},
{
system: "knowledge-base",
kind: "read",
detail: "按队列取首响模板编号",
reversible: true,
},
]),
B: buildMap("B", [
{
system: "data-pack",
kind: "read",
detail: "读取客户数据包与上月报告",
reversible: true,
},
{
system: "chart-engine",
kind: "write",
detail: "渲染图表并写入草稿目录",
reversible: true,
},
{
system: "document-store",
kind: "write",
detail: "写入 12 到 20 页 Markdown 初稿",
reversible: true,
},
]),
C: buildMap("C", [
{
system: "catalog",
kind: "read",
detail: "读取商品、价格与库存",
reversible: true,
},
{
system: "pricing",
kind: "write",
detail: "修改价格与库存",
reversible: true,
},
{
system: "notification",
kind: "trigger",
detail: "向运营与供应商发通知",
reversible: false,
},
]),
};
// 地图排期:同一批接口按风险从低到高拆成可独立验收的阶段。
export function rolloutOrder(surfaces: readonly Surface[]): Surface[] {
return [...surfaces].sort(
(a, b) => SURFACE_ORDER.indexOf(a.kind) - SURFACE_ORDER.indexOf(b.kind),
);
}
// 只读切片是接入的第一步:能证明理解力,又不改变任何外部状态。
export function readOnlySlice(map: IntegrationMap): Surface[] {
return map.surfaces.filter((surface) => surface.kind === "read");
}
export function profileOf(map: IntegrationMap): Profile {
const found = CASES.find((profile) => profile.key === map.caseKey);
if (!found) throw new Error(`unknown case: ${map.caseKey}`);
return found;
}
// 一行摘要,评审会上直接对照任务量与接口结构。
export function mapSummary(map: IntegrationMap): string {
const profile = profileOf(map);
return [
`${profile.key} ${profile.name}`,
`${profile.monthlyTasks.toLocaleString("en-US")} 任务/月`,
`读 ${map.counts.read}`,
`写 ${map.counts.write}`,
`触发 ${map.counts.trigger}`,
].join(" / ");
}
riskOf 的判断顺序值得注意:读永远是低风险;写要看是否可回滚,可回滚是中风险,不可回滚直接升为高风险;触发不看可回滚标记,一律高风险。这不是说触发一定不能用,而是说它不能靠「技术上能撤回」来降级。
rolloutOrder 把一张地图排成接入顺序:先读、再写、最后触发。readOnlySlice 取出第一步能独立验收的接口。mapSummary 把案例的任务量和接口数量放在一行,方便在评审会上对照——同样是「一个读接口」,落在 26,400 单和 606 份上是不同的暴露规模。
模型不替产品做决定。它只保证一件事:当有人说「我们已经接入了这个系统」时,团队能追问一句「接的是哪一类接口,失败了怎么回滚」。
从地图到接入路线
一张地图要变成路线图,需要给每一类接口配一个退出条件。C Runner 的放量节奏可以直接借用:
| 阶段 | 接什么 | 时长 | 退出条件 |
|---|---|---|---|
| 影子 | 全部只读,只记录不执行 | 4 周 | 与人工决策一致率 ≥ 85% |
| 执行 5% | 低风险写动作 | 4 周 | 错误率 ≤ 2%,零不可回滚错误 |
| 执行 20% | 加中风险写动作 | 8 周 | 错误率 ≤ 1.8%,回滚成功率 100% |
| 执行 60% | 不含高风险动作 | — | 连续 8 周达标 |
这张表里没有「全量」这一行,是刻意的。触发类接口和高风险写动作不应该出现在自动放量的终点,它们需要单独的人审或完全不接。地图的价值之一,就是让团队早一点承认:有些接口不是「以后再接」,而是「设计上就不接」。
路线图还要写清楚「不接什么」。不接的接口同样是产品决策:不接客户门户的发布接口,意味着 B 的产出永远停在草稿;不接供应商的自动下单接口,意味着 C 的通知永远只到「提醒」这一层。把这些写进地图,比写在需求文档的附录里更不容易被后来的版本悄悄推翻。
小结
- 集成地图不是系统清单,它按接口拆系统,按副作用排风险。
- 读、写、触发三类接口的副作用形态不同,风险不能用一个「已对接」概括。
- 只读接入是最稳的第一步,因为它把「理解是否正确」和「动作是否安全」分开验收。
- 只读不是零风险:权限过大、数据过期、隐私越界都要单独写。
- 写接口的关键是前值,没有前值就没有可证明的回滚。
- 触发接口默认高风险,技术撤回不等于外部行动撤回。
- A 不接触发、B 只写草稿目录、C 把通知单列,三张地图的差异就是三种责任分配。
- 地图还要写「不接什么」,否则边界会在后续版本里被慢慢磨掉。
阅读导航:上一节:7.3 出事了谁负责 · 下一节:8.2 权限面:它能碰哪些数据与动作 。
常见错误与边界
- 把系统数量当集成能力。 接了很多系统但全是只读,和接一个系统但能安全写入,是两种完全不同的产品;用数量宣传会误导用户对能力的预期。
- 把读接口当无风险。 读可能带来权限过大、数据过期和隐私越界;这些风险不改变业务状态,但会改变合规与信任。
- 写接口不留前值。 没有前值的写操作无法证明回滚到了什么状态;「我记得原来是 100」不算回滚能力。
- 用技术撤回掩盖触发风险。 消息可以撤回,对方已经采取的行动不能;触发类接口要按外部流程的真实后果定级。
- 只画要接的接口。 不接的接口同样要写进地图,否则下一版需求会以「顺手加一个」的方式突破边界。
- 把地图当一次性文档。 系统接口、权限和负责人都会变;地图不随版本更新,就会变成一张过期的宣传图。
这一节画的是「能接什么」。下一节要把地图上的每个接口翻到背面,写清楚它到底能碰哪些数据、能做什么动作。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。