当前仓库没有 Tool Connectors 专属测试。Contracts/Infrastructure 可编译不等于连接器满足商业交付；GA 需要从组合、输入安全、供应商合同、业务流程和运维恢复逐层给证据。

1. 测试金字塔

单元测试不能证明 SDK 行为；真实 sandbox 测试昂贵且不稳定。四层各自锁定不同风险。

2. 组合合同

三连接器都要覆盖 Disabled、非法值、Enabled+SDK 缺失、Enabled+SDK 存在、预注册覆盖和注册顺序。测试应断言真实类型和调用结果，而不是只断言 GetService 非 null。

Host 测试还必须证明 API Host 实际引用 Infrastructure、注册 SDK、执行 Adapter 扩展，并按租户 Feature/权限关闭请求。当前这些证据不存在。

3. Unavailable 合同

所有异步方法应返回各自 ProviderUnavailable，不接触网络或磁盘；OCR Captcha 目前应断言抛 InvalidOperationException。若未来统一为 Result，测试与迁移说明必须同步。

错误码、HTTP 映射、可重试标识和日志级别要稳定。禁用是预期配置状态，不应造成错误风暴。

4. Crawler 安全门禁

必须自动化验证 SSRF 地址族、重定向、DNS rebinding、端口/scheme、任意脚本拒绝、输出上限、租户会话隔离、Cookie 清理、超时后 driver 废弃和资源配额。

使用受控 DNS/HTTP 测试服务器，不能让 CI 扫描真实内网。浏览器/driver 版本升级要跑固定网站夹具，而非依赖公网页面。

5. OCR 安全门禁

验证路径逃逸、符号链接、URL SSRF、巨大/畸形/Base64 输入、图像炸弹、区域溢出、取消、内存预算、低置信度和敏感文本不入日志。

质量回归按语言/文档类型维护许可金丝雀数据，记录期望文本或业务字段阈值。引擎/语言包升级必须产出差异报告。

6. iManage 合同门禁

在供应商 sandbox 或可信 emulator 中验证上传元数据、下载 stream 所有权、大小限制、签出冲突、签入 null/空流真实语义、历史时区、Custom 字段与供应商错误映射。

超时注入应覆盖“供应商已完成但客户端未收到结果”。测试必须证明对账能收敛，不能只测立即失败。

7. 业务 owner 集成

连接器没有自己的 Endpoint，因此每个 consumer 都需要独立合同测试：

TenantId/ActorId 来自可信上下文；
对象归属、状态、审批与扫描已执行；
Feature 和权限实际拒绝；
输入策略先于 Port；
状态变更有 idempotency/operation record；
输出脱敏、审计与保留生效；
Provider failure 映射为稳定业务错误。

这是“独立 Consumer Contract Tests”的核心，而非给 Adapter 增加一条 happy path。

8. 故障演练

至少演练：DNS 失败、TLS 证书错误、401/403、429、慢响应、连接重置、半完成上传、浏览器崩溃、OCR 内存压力、secret 轮换和供应商区域不可用。

每次演练记录触发方法、预期 SLO、告警、用户表现、恢复步骤和数据对账。未知结果必须有人工与自动处置路径。

// ① sandbox 完成远端写入后，让传输层在响应到达前中断。
provider.CompleteThenDropResponse(operationId);

// ② consumer 不得立即重试，而应保存 UnknownOutcome。
Result result = await useCase.ExecuteAsync(command, ct);
Assert.Equal(OperationStatus.UnknownOutcome, await operations.GetStatus(operationId));

// ③ 对账任务读取远端事实，并把同一 operation 收敛到 Succeeded。
await reconciler.RunOnceAsync(ct);
Assert.Equal(OperationStatus.Succeeded, await operations.GetStatus(operationId));

9. 可观测性合同

统一 trace 属性建议包含 connector、operation、outcome、retryable、provider status category 和 correlation ID。TenantId 仅使用受控低基数哈希/分区标签；文档名、URL、OCR 文本禁止作为标签。

核心 SLI：可用率、p50/p95/p99 延迟、超时/限流率、输入拒绝率、队列等待、活动会话、处理字节、未知结果和对账年龄。

10. Runbook

每个连接器需要独立 Runbook：

如何判断是未组合、配置错误还是供应商故障；
如何安全禁用并告知 consumer；
如何轮换凭据/证书；
如何排空队列、回收浏览器或释放锁；
如何识别未知结果并对账；
如何回滚 SDK/语言包/driver；
哪些日志可给供应商，哪些含客户数据；
谁拥有升级与事故响应。

11. 数据与合规

为三个连接器建立数据流清单：来源、目的、分类、处理位置、第三方、传输/静态加密、保留、删除、数据主体请求和跨境要求。

Crawler 页面、OCR 文本与法律文档天然可能高敏。默认不在应用日志、指标或 trace 记录正文；测试样本也必须脱敏并有许可。

12. 商业 GA 阻断项

优先级	阻断
P0	Host 未组合；没有 consumer/Endpoint；权限与 Feature 未执行
P0	Crawler SSRF、脚本和跨租户会话隔离缺失
P0	OCR 路径/URL/大小/图像安全边界缺失
P0	iManage 状态变更无幂等、未知结果对账与审计
P1	下载全量内存、动态错误码、异常边界不完整
P1	治理重复声明、注册顺序、健康与指标缺失
P1	无模块、consumer、sandbox 和故障演练测试

13. GA 证据包

发布评审应附：源码/包版本、依赖 SBOM、配置矩阵、权限/Feature 自动化结果、威胁模型、数据流、测试报告、性能容量、故障演练、供应商兼容报告、Runbook、告警面板、回滚和已知限制。

没有证据的能力写成 Preview/Not delivered；不可用 Adapter 只是安全默认，不是供应商就绪证明。

14. 当前可执行验证

dotnet build src/Platform/ToolConnectors/BitzOrcas.Platform.ToolConnectors.Contracts/\
BitzOrcas.Platform.ToolConnectors.Contracts.csproj --no-restore

dotnet build src/Platform/ToolConnectors/BitzOrcas.Platform.ToolConnectors.Infrastructure/\
BitzOrcas.Platform.ToolConnectors.Infrastructure.csproj --no-restore

# 当前预期没有 Tool Connectors 专属测试命中。
rg -n "CrawlingAdapter|OcrAdapter|IManageAdapter|UnavailableOcrPort" tests -g '*.cs'

15. 完成定义

只有 Host 组合、consumer 用例、安全策略、授权/Feature、供应商合同、幂等对账、可观测性、Runbook 与独立测试同时通过，才能把某一个连接器标为 GA。三个连接器应独立评级，不因其中一个完成而整体宣称就绪。

返回 Tool Connectors 总览