docs/INTEGRATION_WALKTHROUGH.md

Rama main · réplica de lectura del repositorio original.

# 非作者业务接入走查

这份清单用于检验公开文档能否让此前不熟悉项目的开发者完成接入。先完成[独立 Demo 验证](INDEPENDENT_VALIDATION.md)，再用自己有权操作的非生产 API 跑通一项读取与一项需审批的写操作。Demo 成功、维护者代做和真实业务接入分别记录。

## 准备与记录方式

- 固定 Core 版本、提交或镜像摘要，以及所用 SDK/客户端版本。未发布源码必须标明候选身份，不能用版本字段代替提交号。
- 使用独立测试环境、合成数据和可撤销的小范围测试操作；不连接生产写接口、不使用真实退款。
- 业务方提供两个精确 operationId 及各自的 scope、现有权限判断、审批决策入口，以及查询原业务操作结果的方法。AI 或浏览器输入不能决定租户和操作主体。
- 选一个入口即可：业务后端调用、网页 Widget 或本地 Agent。仅在该入口需要模型时提供测试模型；不用先安装全部适配器。
- 预留半天作为首次走查时间盒；时间用完仍阻塞就记录问题，不通过维护者代做来记为“独立成功”。环境下载耗时与实际操作耗时分开。
- 每步记录 `PASS / FAIL / BLOCKED / NOT_RUN / NOT_APPLICABLE`、耗时、文档入口、期望与实际、脱敏错误码和关联 ID。`NOT_APPLICABLE` 要写理由，不算通过。

帮助等级：`H0` 只用公开资料；`H1` 获得文档定位提示；`H2` 获得环境或接入方案指导；`H3` 维护者直接改配置/代码或代操作。失败后帮助继续推进可以，但应分别保留帮助前后的结果。

## A. 全新安装与 Demo

按[独立验证任务卡](INDEPENDENT_VALIDATION.md)选择安装路径并完成五项检查，记录首个阻塞点。确认匿名预览不继承后台身份。自动 Demo 的通过不代替后面的自有 API 和负向检查。

## B. 自有非生产 API：一读一写

| 步骤 | 操作 | 通过时应留下的证据 |
| --- | --- | --- |
| B1 选定业务边界 | 选择一项查询和一项需审批的写接口，明确成功、拒绝、重复调用与结果不明时的处理 | 两个 operationId 及独立精确 scope、合成对象、业务方权限/幂等规则说明 |
| B2 声明和验签 | 按 [SDK 与业务契约](CONTRACT.md)发布能力清单，接入签名校验及既有业务权限判断 | 无签名、错误签名、无主体或无权限请求被业务端拒绝；不要用 `authorize = true` 替代授权 |
| B3 注册与限权 | 注册工具源，核对清单访问策略；路由 `allow` 填上述 scope（不是 operationId），主体由可信后端提供 | 核对最终目录只有目标工具；若共享 scope 带入其他工具，先拆测试声明或专用工具源。目录可见不等于业务授权通过 |
| B4 查询 | 从选定入口查询合成对象，并对照业务接口结果 | 原 run/job/trace 与业务请求关联、查询结果一致 |
| B5 待审批 | 发起一次受审批的写操作，先不批准 | 审批意图与冻结参数；业务端写入计数仍为零 |
| B6 批准与核对 | 由有权限的人批准；按所选入口的续办语义继续原操作 | 原审批、原调用与业务记录对应，只有获批参数被执行；通知或模型总结不能替代业务记录 |
| B7 可解释性 | 请接入者仅用控制台/公开接口解释这次操作是谁发起、为何允许、审批了什么、最终结果如何 | 能找到原 trace/调用与业务结果，记录缺失或难懂的信息 |

参考：[快速开始第 9 步](QUICKSTART.md)、[Agent 接入](AGENT_CLIENT_QUICKSTART.md)、[Agent Runtime](AGENT_CLIENT_RUNTIME_API.md)。本地 Agent 的只读 receipt 与有副作用的 resume 分开；不要把 resume 当轮询。

## C. 隔离负向场景

每个场景使用新的合成测试对象，并在业务端记录实际写入次数。异常只注入测试接口；不通过更换请求 ID、授权或重建任务掩盖失败。

| 场景 | 操作 | 应有结果 |
| --- | --- | --- |
| C1 拒绝审批 | 为另一项合成写请求拒绝审批，再从原入口核对状态 | 业务写入为零，拒绝可追踪 |
| C2 批准后改参 | 在隔离调用夹具中尝试把获批请求的金额/对象或其他受审批参数改掉 | 修改不能复用原批准；业务端不得执行未获批参数。没有可控调用夹具则记 BLOCKED，不宣称已测 |
| C3 权限变化 | 清单可见后撤销该测试主体的业务权限，再发起调用 | 业务端最终授权拒绝；目录缓存不能提供执行权限 |
| C4a 业务确认丢失 | 测试业务端已接收写入，但让响应在抵达 Hub 前丢失；核对原调用和业务记录 | 按入口契约呈现结果不明（Agent receipt 为 `reconciliation_required`），保留原调用直到有证据核定；不得自动创建替代写。普通 5xx 演示不等于此场景 |
| C4b 客户端确认丢失 | Core 已持久保存结果，但客户端未收到响应；通过只读 receipt 核对原调用 | 返回已保存的结果（成功调用为 `executed`），业务写入次数不增加；不能把客户端超时直接当作 Core 结果未知 |
| C5 重复请求 | 对一个已确认的逻辑操作按该接口规定重试同一请求/幂等键 | 实际业务副作用不重复；明确区分 Hub 原调用恢复和业务自身幂等保障 |
| C6 停止与恢复 | 在测试任务/审批有记录时正常停止，再使用同一存储启动并核对原 ID | 状态和关联保留，已完成业务不因重启重复执行；正常重启不冒充 SIGKILL 验证 |

若选用本地 Agent，可按 [任务控制](AGENT_TASK_CONTROL.md)追加暂停、跨轮写额度和撤销成员场景；它们是选定能力的扩展，不能替代 B/C 的业务权限检查。

## 收口与反馈模板

```text
验证者角色（是否参与过项目实现）：
日期 / 环境 / Core 提交或镜像摘要 / SDK 与入口版本：
轨道：Demo / 自有非生产 API
目标操作与授权范围（脱敏）：
步骤编号 / 状态 / 耗时 / 帮助等级：
所用公开文档：
期望 / 实际 / 首个阻塞点：
脱敏错误码、关联 ID、业务端实际写入次数：
能否在无维护者代做的情况下重复完成：
尚未测试的场景及原因：
```

保留失败记录，修复后重跑原阻塞步骤及相关上下游。反馈可用[独立验证 Issue 模板](https://github.com/bailinghub/bailinghub/issues/new?template=independent_validation.yml)，但不上传密钥、完整配置、个人信息或业务正文。两位开发者能复现也只证明相应版本、入口和环境；性能、升级恢复及长期运行仍需各自的证据。