## 没有现成集成时，写一张连接需求卡

<!-- slot: 目标 -->
### 本章目标

没有现成连接时，不能只说“把两个系统打通”，却不说明目的、权限、重复写入和结果不明怎么办。
本章用一张需求卡，把业务语言整理成可实施、验收和追责的约定。

学完本章，你将能够：

- 写清业务目标、读写范围、最小数据与最小权限。
- 为外部写入定义完整意图身份、幂等和权威核验方法。
- 区分当前已经可用、需要管理员配置和仍需开发的能力。
- 让业务 Owner、管理员、实现者和 Agent 各守自己的责任边界。

<!-- slot: 边界 -->
### 先认清 Workflow 与集成的边界

- **覆盖**：把一个外部系统需求整理为可评审、可实施、可验收的连接需求卡。
- **不覆盖**：选择具体厂商接口、虚构路径或动作名，以及直接执行高影响外部写入。
- **假设**：业务 Owner 能说明目的、风险和成功标准；管理员与实现者随后参与评审。

Workflow 没有 HTTP 节点或 Extension 节点；它用 `send_message` 与 `completion: callback` 委托 Agent。
外部事件不是 Trigger；需要运行时由具备权限的人或 Agent 发起 `manual` 调用，`schedule` 只用于计划调用。

> **⚠️ 注意：** Agent 只能使用当前授权 Catalog 中已经列出的能力。
> 它不能自行索要 token，不能把对话里的秘密当连接配置，也不能为赶进度自造动作。

<!-- slot: 流程 -->
### 从一句需求收敛为可实施约定

先从业务结果出发，再逐层收紧数据、权限、重复保护、恢复和证据，最后才谈由谁实现：
本章把“结果不明后读取外部系统权威状态并对照完整意图身份”称为**权威核验**。

![连接需求卡收敛路径：业务 Owner 定义目标；团队确定权威操作身份、最小数据和权限；随后约定完整意图身份、幂等、安全重试与权威核验；再定义审计、留存和验收；最后把连接交给管理员、App 或 Extension 与安全证据交给实现者，并把 Agent 限定在当前授权 Catalog 内](../../media/chapters/fig-20-01-integration-requirement-card.svg){#fig-20-integration-requirement-card width=96%}

图 20-1 连接需求卡从业务目标到实现责任的收敛路径。

需求评审按下面顺序进行：

1. 业务 Owner 先确认“为什么做”和“失败会伤害谁”。
2. 管理员确认连接身份、权限和秘密边界是否可接受。
3. 实现者说明哪些能力要由 App 或 Extension 提供，并提交安全与测试证据。
4. Agent 只核对当前 Catalog；缺少能力时返回“需配置”或“需开发”，不把设计描述成现状。

<!-- slot: 提示词 -->
### 复制这段需求澄清提示词

```text
请把下面的业务想法整理成一张连接需求卡，不要调用外部系统，也不要编造 API、路径、动作或现有能力。

业务想法：[希望解决的问题]
来源系统与目标系统：[系统类别即可]
业务 Owner：[member_ref 或 role_code]
管理员：[member_ref 或 role_code]
预期使用者：[团队或角色]

请完成以下工作：
1. 分别列出“当前已经可用”“需配置”“需开发”，没有证据的能力一律不能放进“当前已经可用”。
2. 写清业务目标、读动作、写动作、权威操作身份、最小数据、最小权限、输入、输出、敏感数据与秘密边界。
3. 为写动作定义意图身份：对象 + 来源批准版本或业务事件 + 期望变更；再说明幂等依据、结果不明后的权威核验、限流和安全重试。
4. 写清审计证据、留存期限、验收条件和每项 Owner。
5. 标出 Workflow 边界：没有 HTTP 或 Extension 节点；外部工作通过 send_message + callback 交给已授权 Agent。
6. 核对当前授权 Catalog。缺少能力时只写“需配置”或“需开发”，不要索要 token，不要自造动作。
7. 把高影响写动作标为“第 21 章行动卡与人工确认后才可执行”。

最后返回：需求卡、角色职责表、异常处置表、验收卡和需求评审结果卡。结果卡必须列出三类能力证据、各角色接受或拒绝、开放缺口、具体留存期限、删除 Owner 与验收结论。
```

### 角色职责表

| 角色 | 必须决定或交付 | 不能代替谁 |
| --- | --- | --- |
| 业务 Owner | 目的、风险、写入范围、验收和收益 | 不替管理员批准权限或替实现者证明安全 |
| 管理员 | 建立连接，授予最小权限，保管与轮换秘密 | 不替业务 Owner 决定是否值得写入 |
| 实现者 | 完成 App 或 Extension、意图身份、幂等与权威核验，并交付测试和安全证据 | 不把尚未开发的能力写成已经可用 |
| Agent | 在当前授权 Catalog 内执行已获准工作并返回可核验结果 | 不索要 token，不自造动作，不扩大授权 |

<!-- slot: 配置 -->
### 可复制示例：同步已批准客户记录

本例不绑定厂商，也不假定接口存在，只描述同步已批准客户记录所需的合同。

| 字段 | 本例填写 |
| --- | --- |
| 业务目标 | 减少销售重复录入，让已批准客户在外部 CRM 可被后续跟进；未批准记录不得同步 |
| 读 / 写动作 | 读取内部已批准记录及同步状态；在外部 CRM 创建或更新对应客户记录；本章只设计，不执行写入 |
| 权威操作身份 | 来源侧身份获准读取已批准客户；目标侧 App 连接只管理客户记录；秘密不交给 Agent |
| 最小数据 | 客户名称、稳定记录编号、负责团队、批准时间、允许同步的联系字段；不传审批备注全文 |
| 最小权限 | 来源侧只读批准范围；目标侧只管理客户记录，不授予用户、账单或全局管理权限 |
| 输入 / 输出 | 输入为已批准记录与稳定身份；输出为结论、外部映射身份、时间和失败分类 |
| 敏感数据 / 秘密边界 | 联系字段按数据分级处理；连接秘密不进入提示词、Workflow 输入、回调或审计正文 |
| 意图身份与幂等 | 用“内部客户记录编号 + 来源批准版本或批准事件 + 期望同步变更”标识同一意图；外部身份只作映射，换临时请求编号不能变成新意图 |
| 结果不明后的权威核验 | 以目标系统按意图中的对象身份或既有映射读到的当前记录为权威结果；无法唯一核验时停止并交给 Owner 判断 |
| 限流 / 安全重试 | 遵守目标系统返回的节流信号；只读查询可有界重试；写入结果不明时，只有权威证据证明原请求未执行且不会再生效、动作契约又明确保证同一意图可安全重放，才允许有界重试，否则人工接管 |
| 审计 / 留存 | 外部需求卡、确认记录与脱敏验收副本保留至验收后 180 天，由 Workspace 数据管理员删除；组织政策要求更长时以已批准政策为准。该期限不承诺逐对象删除平台 PlanVersion、Invocation、Run 或事件账本 |
| 验收 | 用少量测试记录证明未批准记录不进入范围、重复请求不产生第二条客户、结果不明可对账、秘密不出连接边界 |
| Owner | 业务 Owner 管目的与验收；管理员管连接；实现者管能力证据；运行责任人管异常 |

能力状态必须单独登记：

| 分类 | 本例状态 |
| --- | --- |
| 当前已经可用 | Workflow 可把外部任务通过 `send_message` 与 callback 交给 Agent；Agent 可核对自己的当前授权 Catalog |
| 需配置 | 管理员建立目标系统连接、选择最小权限、设置秘密轮换和审计访问范围 |
| 需开发 | 实现者提供经过评审的 App 或 Extension 能力，以及稳定身份映射、幂等、权威核验、限流处理和安全证据 |

### 需求评审结果卡

结果卡只判断需求是否说清楚，不把范围获批写成实现可用：

| 评审项目 | 本例结论 |
| --- | --- |
| 当前能力证据 | Workflow 已能通过 `send_message` 与 callback 委托 Agent，Agent 能核对当前 Catalog；当前证据不包含 CRM 写入动作 |
| 需配置 | CRM 连接、最小客户记录权限、秘密轮换和审计访问范围尚待管理员配置 |
| 需开发 | 客户同步 App / Extension、意图身份、映射、幂等、权威核验、限流与安全测试尚待实现者交付 |
| 业务 Owner | **接受**业务目标、仅同步已批准记录、试点范围与收益指标 |
| 管理员 | **拒绝当前生产启用**；连接、权限和秘密方案通过安全验收后再决定 |
| 实现者 | **接受**本卡列出的交付范围；不承诺尚未验证的提供方能力 |
| Agent | 不是需求批准人；只能在以后实际授权的 Catalog 内执行 |
| 开放缺口 | 完成配置与开发、用测试记录关闭验收项，并为首次真实写入准备第 21 章行动卡 |
| 留存与删除 | 外部需求卡、确认记录和脱敏验收副本保留至试点验收后 180 天；删除 Owner 为 Workspace 数据管理员。平台 PlanVersion、Invocation、Run 和事件账本不在这项逐对象删除承诺内 |
| 验收结论 | **需求范围通过；实现与生产写入未通过。** 开放缺口关闭前不得同步真实客户 |

<!-- slot: 审批 -->
### 高影响写入留到行动卡

需求卡获批只允许按边界实施和验证，不授权写入真实客户。
批量创建、覆盖关键字段或改变客户归属要留到第 21 章，以行动卡逐次展示对象、数量、影响、幂等和恢复路线。
业务 Owner、管理员和实现者分别接受自己的范围，不能用一次笼统同意互相替代。

<!-- slot: 异常 -->
### 异常处置表

| 现象 | 先判断什么 | 安全处置 |
| --- | --- | --- |
| Catalog 中没有所需能力 | 尚未授权、需配置，还是根本未开发 | 停止执行，按三类状态登记；不索要 token，不猜动作名 |
| 写入请求没有明确结果 | 外部结果可能已发生或稍后生效 | 按完整意图身份权威核验；只有证明未执行、不会再生效且动作契约允许安全重放时才有界重试，否则人工接管 |
| 出现重复客户 | 幂等依据、映射或并发保护不足 | 停止后续写入，保留两侧身份和证据，由业务人员决定合并或保留 |
| 遭遇限流或服务不可用 | 是可延后读取，还是结果不明的写入 | 读取可有界退避；写入仍执行同一严格核验门槛，不因限流直接重放 |
| 回调包含超出约定的数据 | 输出或秘密边界被突破 | 拒绝进入后续处理，清理不当暴露并由管理员与 Owner 评估影响 |

<!-- slot: 外部系统 -->
### 外部系统怎样接入 Workflow

实现后，Workflow 仍用 `send_message` 与 callback 委托已授权 Agent，回调只含需求卡声明的最小输出。
外部变化不会自动成为 Trigger；需要运行时另行发起 `manual` 调用。

### 业务收益怎样衡量

选择小范围试点并记录足够样本，再比较：

- 每条已批准客户记录节省的重复录入时间。
- 因字段缺失、身份不稳或权限不足转人工处理的比例。
- 重复客户数量，以及结果不明后可通过权威核验明确结论的比例。
- 超出最小数据、最小权限或留存期限的例外数量。

样本不足时只记录事实，不宣称收益已经稳定，也不把目标值写成平台承诺。

<!-- slot: 验收 -->
### 验收卡

- [ ] 需求卡覆盖业务目标、读写动作、权威操作身份、最小数据、最小权限、输入输出和 Owner。
- [ ] 敏感数据与秘密边界清楚，提示词、输入、回调和审计记录都不携带连接秘密。
- [ ] 意图身份包含对象、来源批准版本或业务事件、期望变更；幂等、权威核验、限流与安全重试可以用测试记录证明。
- [ ] 需求评审结果卡列出三类能力证据、各角色结论、开放缺口、具体留存期限、删除 Owner 与验收结论。
- [ ] 180 天期限只覆盖外部需求卡、确认记录与脱敏验收副本，不承诺逐对象删除平台版本与运行账本。
- [ ] 当前已经可用、需配置、需开发分栏有证据，不把设计写成现状。
- [ ] 角色责任已经分别确认，Agent 只在当前授权 Catalog 内工作。
- [ ] 高影响写动作尚未执行，并已标记为第 21 章行动卡与人工确认范围。

<!-- slot: 媒体槽位 -->
### 媒体槽位

<!-- media: fig-20-01-integration-requirement-card.svg -->
图 20-1 连接需求卡从业务目标到实现责任的收敛路径。

### 小结

连接需求卡从业务目标、最小数据和责任开始，把意图身份、幂等、权威核验、重试、审计和验收写成同一约定。
它严格区分当前可用、需配置和需开发，让管理员、实现者与 Agent 各守边界。

下一章将把已获准的高影响写动作做成行动卡，加入逐次人工确认、失败恢复、补偿和人工兜底。