## 选择合适的外部系统连接方式

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

“系统提供了接口”不等于 Loop 已经能安全使用它。
你要先确认当前 Agent 获准做什么，再决定复用、代办、文件交换或建设新集成。

学完本章，你将能够：

- 让 AI 在后台检查当前 Agent 的 Extension Catalog，并只使用其中当前可见且已授权的动作。
- 按固定顺序选择成本最低、权限最小、结果可核验的连接方式。
- 区分外部系统活动、Workflow 调用和 Trigger，不把一条外部事件误解成自动运行。
- 用行动卡、结果卡和责任表说明决定。

<!-- slot: 边界 -->
### 适用边界

- **覆盖**：为读取信息、写入结果、批量交换文件和事件后续处理选择连接方式。
- **不覆盖**：自行安装连接、索取凭据、猜测提供方接口，或设计新 App / Extension 的技术实现。
- **假设**：你能说明业务目标、数据负责人、预期结果和谁有权批准外部动作。

本书校验时，Catalog 只列出 `gitea list-watches`、`gitea watch-pull-request`、`gitea pause-watch`、`gitea resume-watch` 和 `gitea unwatch`。
这只是一次快照；每项任务都要重新检查，且不能据此推断 Workspace 天然具备 Gmail、Microsoft Graph 或任意 API。

<!-- slot: 提示词 -->
### 复制这段选择提示词

把方括号替换为真实信息。
你不需要记后台命令，只要要求 AI 展示检查结论和证据边界：

```text
请帮我为下面这项业务选择外部系统连接方式，先分析，不要执行外部写入、安装连接或启动 Workflow。

业务目标：[要解决什么问题]
外部系统：[系统名称与业务范围]
需要读取什么：[对象、字段、时间范围]
需要写入什么：[没有就写“只读”]
权威操作身份：[谁的身份才有资格读取或写入]
数据敏感度：[公开 / 内部 / 受限，以及不能进入对话的内容]
高影响动作：[发送、删除、付款、发布、改权限等；没有就写“无”]
结果如何核验：[页面、记录编号、回执、导入报告或对账人]
失败后谁负责：[业务负责人、系统管理员或其他角色]

请按下面顺序处理：
1. 在后台检查当前 Agent 的实际 Extension Catalog，只列出本次可见且已授权、并与目标直接相关的动作。不要猜动作名，不要把系统存在 API 当成 Workspace 已连接。
2. 依次评估：已有 App 或 Extension → Agent 或人工交换 → 文件导入 → 新建 App 或 Extension。前一种以最小权限满足目标并可核验时，不跳到后一种。
3. 对每种可行方式说明读写、权威操作身份、权限、敏感数据、核验、高影响动作和审计责任。
4. 如果使用已有 App 或 Extension，只能采用本次 Catalog 实际列出的动作；没有匹配能力就明确写“当前不可用”。
5. 如果由 Workflow 协调外部工作，说明 Workflow 没有 HTTP 节点或 Extension 节点。应使用 send_message，并等待 Agent callback；Agent 仍只能使用它当前获准的能力。
6. 外部事件不是 Trigger。Workflow 调用来源只有 manual 或 schedule。若某个外部事件需要带动 Workflow，由已授权人或 Agent 基于该事件另行明确发起手动调用，并重新确认 Workflow、版本、输入与影响。
7. 先返回推荐与备选方式，再展示行动卡。写入意图用“对象 + 来源批准版本或业务事件 + 期望变更”标识；确认前不执行写入、新连接或手动调用。
8. 没有权威回执就标记“结果不明”。只有证据证明原请求未执行、不会再生效，且动作契约允许同一意图安全重放时才有界重试；否则人工接管。
```

提示词不会创造授权，只要求 AI 先盘点事实。

### 谁负责什么

| 角色 | 负责什么 | 不应替谁决定 |
| --- | --- | --- |
| 业务发起人 | 说明目标、数据范围、结果和人工成本 | 不猜 Agent 的连接能力 |
| AI 助手 | 检查 Catalog、比较方式、展示卡片并执行已确认工作 | 不虚构动作、接口、权限或回执 |
| 获授权 Agent | 通过消息接收任务，使用当前获准能力处理并回传结果 | 不把自身权限扩大到整个 Workspace |
| 外部系统授权人或管理员 | 维护 App 连接、身份和最小权限 | 不替业务负责人批准高影响动作 |
| 人工操作人或文件管理员 | 在外部系统完成约定操作，或导出、检查和导入文件 | 不省略来源、时间和导入报告 |
| 审计责任人 | 保存行动卡、确认记录、回执与异常结论 | 不把 AI 自述当成权威证据 |

<!-- slot: 流程 -->
### 按四级顺序做决定

![外部系统连接方式决策树：先核对当前 Catalog 与已有 App 或 Extension；不满足时依次判断能否由获授权 Agent 或人工交换、能否通过受控文件导入，最后才提出新建集成；四种方式都不会自动启动 Workflow，外部事件需要由已授权人或 Agent 另行明确发起手动调用](../../media/chapters/fig-19-01-connection-choice.svg){#fig-19-connection-choice width=96%}

图 19-1 外部系统连接方式决策树：按“已有 App / Extension → Agent 或人工交换 → 文件导入 → 新建集成”逐级选择，并明确所有方式都不会自动启动 Workflow。

1. **已有 App 或 Extension**：优先使用当前 Catalog 中与目标直接匹配的授权动作。
   仍要核对读写范围、回执和业务确认。
2. **Agent 或人工交换**：由有权进入外部系统的人或 Agent 完成低频任务，再按约定格式带回证据。
3. **文件导入**：用受控文件批量交换，并记录来源、范围、校验和导入报告；不用于频繁双向写入。
4. **新建 App 或 Extension**：只有前三种无法满足业务时效、规模、安全或审计要求时才进入实施。
   第 20 章会把它写成可交付的需求卡。

Workflow 没有 HTTP 节点或 Extension 节点。
它用 `send_message` 与 `completion: callback` 委托指定 Agent，实际动作仍取决于该 Agent 当时的授权。
外部事件不是 Trigger；调用来源只有 `manual` 和 `schedule`，需要运行时由已授权人或 Agent 另行发起 `manual` 调用。

<!-- slot: 配置 -->
### 用八项依据比较方案

你不需要阅读连接配置，只要让 AI 为每个候选方式填写同一张比较卡：

| 选择依据 | 要回答的问题 |
| --- | --- |
| 业务目标 | 要缩短什么时间、减少什么错误，还是满足什么审计要求？ |
| 读取或写入 | 只读能否完成目标；若必须写，精确写哪些对象？ |
| 权威操作身份 | 哪个人、服务身份或 App 才是外部系统认可的操作主体？ |
| 最小权限 | 能否只开放本次对象、范围和动作，而不是整个系统？ |
| 数据敏感度 | 哪些字段可以进入 Loop，哪些只能留在外部系统或受控文件中？ |
| 失败后能否核验 | 能否用页面、记录编号、回执、导入报告或对账结果确认事实？ |
| 高影响动作 | 是否涉及发送、删除、付款、发布、改权限或其他难以撤销的结果？ |
| 审计责任 | 谁保存确认、回执和异常记录，谁最终解释差异？ |

### 行动卡与结果卡

执行前的**行动卡**写明：推荐方式、Catalog 证据、对象、读写、权威操作身份、权限、数据边界、高影响动作、确认人、核验方法、失败负责人，以及“不会自动启动 Workflow”。
写入还要固定意图身份：对象、来源批准版本或业务事件、期望变更三者共同标识同一项业务意图。

执行后的**结果卡**写明：采用方式、实际动作和身份、时间、权威回执、未执行与未知事项、人工对账，以及是否另行发起过手动调用。
只收到 Agent 的自然语言回复而没有外部回执时，应把它标为 Agent 声明，不写成外部系统已经确认。

<!-- slot: 审批 -->
### 授权、确认和流程内审批是三件事

外部系统授权人决定 Agent 或 App 能否访问相应对象；业务负责人决定本次读取、写入或文件交换是否应该发生；Workflow 中的 `request_approval` 只决定当前 Run 在该人工决策点如何继续。
流程内通过不能替代外部系统权限，也不能自动批准新建 App、扩大数据范围或重复一次高影响写入。

只读且低敏感的查询也要受 Catalog 与权限约束。
写入、高影响动作和新连接，应重新展示精确对象、影响和核验方式，再由有权角色明确确认。
结果不明时，确认不能替代权威核验。
只有权威证据证明原请求没有执行、以后也不会再生效，而且动作的真实契约明确保证同一意图可以安全重放时，才可按原意图做有界重试；其他情况都应停止并交给人工接管。

<!-- slot: 异常 -->
### 常见异常与安全处置

| 你看到的现象 | 先判断什么 | 安全的下一步 |
| --- | --- | --- |
| AI 说系统“应该有接口” | 当前 Catalog 是否真的列出匹配动作 | 标为当前不可用，改评估代办、文件或新集成 |
| Catalog 有相近动作但不满足目标 | 动作是只读还是写入，范围是否相同 | 只使用实际动作；缺少的能力另列需求，不拼接猜测 |
| Agent 或人工完成后没有回执 | 外部结果是否能由页面、编号或对账人核验 | 标为结果不明，停止自动重做 |
| 导入文件字段或时间范围不一致 | 来源、版本、字段映射和重复记录是否清楚 | 隔离本批文件，修正后重新校验，不覆盖既有数据 |
| 外部事件到达但 Workflow 没运行 | 事件本来就不是 Trigger | 确认是否需要由已授权人或 Agent 另行发起手动调用 |
| 手动调用前信息已经变化 | Workflow 版本、输入或影响与原行动卡不一致 | 重新展示行动卡并再次确认 |
| 高影响写入响应不明 | 请求可能已被接受、排队或稍后生效 | 按“对象 + 来源批准版本或业务事件 + 期望变更”核验；只有证明未执行、不会再生效且动作契约允许安全重放时才有界重试，否则人工接管 |
| 敏感数据误入对话或文件 | 数据边界与接收人可能被突破 | 停止继续传播，按组织规则通知数据负责人处理 |

<!-- slot: 外部系统 -->
### 外部系统

公开文档或 API 不是 Loop 已连接的证据。
可用性由当前 Catalog、App 授权、外部对象权限和 Loop 接收权限共同决定。
凭据不进入提示词、Workflow 输入或卡片；文件交换不复制受限数据作为“证明”。

若选择新建 App 或 Extension，本章只记录业务缺口，不猜提供方接口、动作名称或状态。
管理员与研发应从最小读写范围、权威操作身份、回执、重复保护、失败恢复和审计责任开始设计。

### 业务收益怎样衡量

选择一项真实连接需求，连续记录至少四周或累计十次处理：

- 从需求提出到取得可核验结果的中位时间。
- 因选错连接方式、权限不清或数据格式不一致造成的返工次数。
- 有行动卡、确认记录和权威回执的处理比例。
- 结果不明时在重试前完成查询或人工对账的比例。
- 高影响动作由正确责任人确认的比例。

样本不足时只记录事实，不宣称比例已经达到目标，也不把“自动化更多”直接等同于业务收益。

<!-- slot: 验收 -->
### 如何判断选择可以投入使用

- [ ] AI 每次先检查当前 Agent 的实际 Catalog，只使用本次可见且已授权的动作。
- [ ] 团队按已有 App / Extension、Agent 或人工交换、文件导入、新建集成的顺序比较方案。
- [ ] 每个候选方式都回答业务目标、读写、权威操作身份、最小权限、敏感度、核验、高影响和审计责任。
- [ ] 行动前有确认卡，执行后有结果卡；未知结果不会被写成成功。
- [ ] 团队能说明 Workflow 通过 `send_message` 与 callback 委托 Agent，而不是直接连接任意外部系统。
- [ ] 团队能说明外部事件不是 Trigger；需要运行时由已授权人或 Agent 另行明确发起手动调用。
- [ ] 结果不明时按完整意图身份核验；只有证明未执行、不会再生效且契约允许安全重放时才有界重试，否则人工接管。
- [ ] 业务收益有连续样本和可比较指标，而不是只统计自动化次数。

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

<!-- media: fig-19-01-connection-choice.svg -->
图 19-1 外部系统连接方式决策树：按“已有 App / Extension → Agent 或人工交换 → 文件导入 → 新建集成”逐级选择，并明确所有方式都不会自动启动 Workflow。

### 小结

选择外部连接的第一原则是先看当前授权事实，而不是先看外部系统能提供什么。
按“已有 App / Extension → Agent 或人工交换 → 文件导入 → 新建集成”逐级评估，并用统一的八项依据比较，通常能以更小权限和更低实施成本得到可核验结果。
Workflow 通过 `send_message` 与 callback 把外部工作交给 Agent；外部事件本身不是 Trigger，也不会自动启动 Workflow。

下一章会把“确实需要新建集成”变成一张可交付的连接需求卡，交代管理员和研发需要的业务动作、授权边界、失败恢复与验收标准。