@agentunion/fastaun-browser 0.5.20 → 0.5.21

package/_packed_docs/sdk/0.5.21-SDK/345/272/224/347/224/250/351/233/206/346/210/220/346/214/207/345/215/227.md

@@ -0,0 +1,368 @@
+# AUN SDK 0.5.21 应用集成指南
+
+> 面向应用开发者。依据 `0.5.21` 工作区整理，相对基线为已发布的 `0.5.20`（`08221fbb`）；当前 CHANGELOG 仍标记未发布，本文不表示发布包或部署环境已通过全部验收。
+>
+> 示例使用 TypeScript，默认运行于 Node.js；浏览器差异单独列出。SDK 实现者另读 [开发与移植指南](0.5.21-SDK开发与移植指南.md)。字段级定义见 [API 手册](06-API手册.md) 和各领域 RPC 手册。
+
+## 1. 本版接入重点
+
+| 能力 | 应用接入方式 | 相对 0.5.20 的重点 |
+| --- | --- | --- |
+| 身份与连接 | `AIDStore` → `AID` → `AUNClient` | 保留原身份、设备、slot 和持久目录；服务端须明确支持 peer Pull |
+| 消息同步 | `message.peers/pull/history` | 按完整 sender 隔离消费进度；目录估计不能当未读数 |
+| 消息消费 | 三类 batch 或原逐条事件 | 处理器完成后才提交；失败可能重放，应用负责持久幂等 |
+| 名片与元数据 | `store.resolve(aid, opts)` | 直接读取完整 `frontmatter`，按需附带 ownership 与 owner.md 快照 |
+| Ownership | 原 2.1 工作流与共识检查 | 双文件和控制格式保持；增加本端未完成任务 reset，兼容历史任务 |
+| 凭证与组织 | `credential`、`org` 门面及实体编排 | 取得当前托管凭证，自动续期、撤销同步及加密 checkpoint 恢复 |
+| 诊断 | `client.debug.diag(scope)` | 分项 dry-run 报告，明确区分通过、失败和缺材料跳过 |
+
+普通聊天应用先完成身份、消息持久化和连接；需要展示名片时调用 resolve。依赖 owner 授权、组织成员或 CAP 的业务，再接入对应的审批和完整验证流程。
+
+## 2. 身份、运行环境与连接
+
+### 2.1 选择产物与本地存储
+
+Node.js 包为 `@agentunion/fastaun`，当前要求 Node.js `>=22.16.0`；浏览器包为 `@agentunion/fastaun-browser`。使用与目标版本一致的构建产物及锁文件，不能仅凭文档标题判断当前安装的版本。
+
+`aunPath` 是应用级持久目录，可管理多个 AID。密钥、token、关系任务和续期 checkpoint 由 SDK 管理；应用自己的消息及业务事务另存数据库。启动时恢复原目录、密钥保护配置、设备与消费 slot。
+
+```typescript
+import { AIDStore, AUNClient } from '@agentunion/fastaun';
+const localAid = 'helper.agentid.pub';
+const store = new AIDStore({
+  aunPath: process.env.AUN_PATH!,
+  encryptionSeed: process.env.AUN_SEED ?? '',
+  slotId: 'main', verifySsl: true,
+});
+```
+
+`AUN_PATH` 和 `AUN_SEED` 由应用部署提供。TLS 和自定义根证书在 `AIDStore` 配置，客户端从 AID 继承，详见 [连接与认证](04-连接与认证.md)。
+
+### 2.2 首次注册与日常加载
+
+仅在明确创建新身份时执行注册，然后加载同一身份；已有身份直接加载。普通 `agent` 可以不指定 owner，绑定关系可稍后单独申请。
+
+```typescript
+const registered = await store.register(localAid, { type: 'agent' });
+if (!registered.ok) throw new Error(registered.error.message);
+```
+
+注册返回 `registered: true` 不代表 Ownership 已建立。指定 owner 只保存待审批意图，连接后继续原工作流；不要再重复发起绑定。`human` 禁止指定 owner；`group/org` 使用专属生命周期及实体身份编排。
+
+```typescript
+const loaded = store.load(localAid);
+if (!loaded.ok) throw new Error(loaded.error.message);
+const client = new AUNClient(loaded.data.aid);
+```
+
+`AUNClient` 接收 AID 对象，也可无参创建后 `loadIdentity()`；不要传 AID 字符串或旧版构造配置。先按第 3 节注册处理器，再调用 connect，避免启动补拉先于业务订阅。
+
+### 2.3 浏览器差异
+
+浏览器身份读取及存储使用异步接口和 IndexedDB。下面替换 Node.js 的初始化片段；后续消息门面的用法相同。
+
+```typescript
+import { AIDStore as BrowserStore, AUNClient as BrowserClient } from '@agentunion/fastaun-browser';
+const browserStore = new BrowserStore({ aunPath: 'myapp', encryptionSeed: '' });
+const browserLoaded = await browserStore.load('helper.agentid.pub');
+if (!browserLoaded.ok) throw new Error(browserLoaded.error.message);
+const browserClient = new BrowserClient(browserLoaded.data.aid);
+```
+
+浏览器 `aunPath` 是本地存储命名空间。Node 文件、文件 seed 轮换和浏览器密钥存储的使用方式有区别，不能直接复制磁盘目录操作。
+
+### 2.4 连接与关闭边界
+
+新 SDK 在 `auth.connect` 声明 `p2p_peer_pull_v1: true`，要求服务端以布尔 `true` 确认支持；缺失能力时返回 `unsupported_protocol`。升级应用前应核对 Gateway 和 Message 服务能力。
+
+`connect()` 完成表示连接可用，后台消息补拉、Ownership 恢复和凭证续期可能仍在进行。界面分别展示连接状态、同步进度和业务任务状态；`auto_reconnect` 不代表业务已经完成。
+
+## 3. 消息接收、发送与同步
+
+### 3.1 选择 batch 或逐条消费
+
+| 订阅事件 | `items` 中的原事件 |
+| --- | --- |
+| `message.batch` | `message.received`、`message.recalled` |
+| `group.message_batch` | `group.message_created`、`group.message_recalled` |
+| `group.event_batch` | `group.changed` |
+
+三类批次均为 `{ namespace, items: [{ event, payload }], source }`。批次保持实际页内顺序，不跨页或 namespace；Push/inline 也可形成单元素批次，空批次不发布。
+
+同类 batch 有订阅时，该页只发 batch；没有 batch 订阅时，沿用原逐条链路。不要依赖同时订阅两种形式收到两份事件。batch 模式及其处理器在每页开始时固定，订阅变化从下一页生效；逐条处理器仍动态查找。
+
+下面的 `commitDeliveryBatch` 是应用实现的数据库事务函数，接收上述批次；只有消息、撤回状态及相关业务记录已经可靠提交，才完成 Promise。
+
+```typescript
+declare function commitDeliveryBatch(batch: unknown): Promise<void>;
+const subscriptions = [
+  client.on('message.batch', batch => commitDeliveryBatch(batch)),
+  client.on('group.message_batch', batch => commitDeliveryBatch(batch)),
+  client.on('group.event_batch', batch => commitDeliveryBatch(batch)),
+];
+await client.connect({ auto_reconnect: true });
+```
+
+业务处理要求：
+
+1. 返回或 await 持久化 Promise；只启动后台写入就返回，会让 SDK 过早认定处理成功。
+2. 写入失败向外抛出；吞掉错误等同于向 SDK 确认成功。失败不会自动改走逐条事件。
+3. 按接收身份、会话、消息 ID 和事件语义持久幂等；消息创建与撤回分别处理，保留 tombstone，避免重放后恢复已撤回内容。
+4. 多个处理器中已有部分成功，或业务提交后进程崩溃，仍可能重放整批。SDK 的 50,000 条运行时去重缓存不替代应用事务，也不保证跨 client、跨进程或跨重启只回调一次。
+5. 在处理器外安排后续实时 Pull；不要在处理器内等待同一交付链再次发布事件，SDK 会拒绝这种等待重入。
+
+Pull 内部页容量为 200，最多预取 4 页；应用共享排队容量默认按 `200 × 4` 计算。这些是 SDK 的流控边界，应用无需再写一套自动 Pull/ACK 循环。
+
+### 3.2 发送与渲染提示
+
+```typescript
+const sent = await client.message.send({
+  to: 'alice.agentid.pub',
+  payload: { type: 'text', text: '你好' },
+  encrypt: true,
+  need_render: true,
+});
+```
+
+`message.send` / `group.send` 门面的参数沿用 RPC 字段 `need_render`；低层 TypeScript V2 编码选项使用 `needRender`，不能把两者混用。接收及返回保持 `need_render`，历史缺字段按可渲染处理。
+
+`need_render=false` 只提示界面渲染策略，仍须正常消费、幂等保存和完成交付；它不是可信授权字段。需要受保护的业务元数据时，按 [ProtectedHeaders 专题](ProtectedHeaders用法专题.md) 接入。发送成功不代表对端应用已处理，也不等同于业务已读。
+
+### 3.3 查询对端目录与主动补拉
+
+```typescript
+const pendingPeers = await client.message.peers({ filter: 'pending' });
+const peerPage = await client.message.pull({
+  sender_aid: 'alice.agentid.pub', limit: 200,
+});
+```
+
+`message.peers` 是服务端消息消费目录，区别于本地身份目录 `client.peers()`：
+
+- `filter: 'pending'` 一次返回完整待处理 peer，不能传 `limit/page_token`；`catalog_ready=false` 表示目录未准备好。
+- `filter: 'all'` 查询仍有消息状态的 peer，可用 `limit`（1–200）与 `page_token` 翻页；它不是联系人列表。
+- 每 peer 的进度由完整 `sender_aid` 隔离；seq 仍属于接收设备原收件箱，不是每个 sender 从 1 开始重新编号。
+- 可选 `pending_count_estimate` 是整体持久 seq 跨度估计，可能明显偏大、不含 volatile；不能作为准确条数、未读数或完成比例。不要依赖已移除的逐 peer 精确计数字段。
+
+省略 sender 的 `client.message.pull()` 会聚合全部 pending peer；使用返回的 `peers` 和 `partial` 判断各 peer 的结果。聚合请求不传 `after_seq`（包括 0）、`after_volatile_cursor`、`window_mode` 或 `force=true`，这些选项须指定 sender。
+
+历史浏览使用 `message.history` / `group.history`，不推进实时水位、不 ACK，也不发布实时接收事件；翻页使用响应游标。`force`、Tail 和历史返回列表可能包含已交付消息，仍需按业务键合并。
+
+自动同步、显式 Pull 和 Push 的应用交付使用同一处理链。不要将 Pull 返回列表再次作为另一份新消息写入非幂等业务，也不要用返回页的最大 seq 手工越过未交付消息 ACK。
+
+### 3.4 UI 刷新、同步与业务已读
+
+| 入口 | 应用用途 |
+| --- | --- |
+| batch 或原消息事件 | 消息与撤回的可靠业务入库 |
+| `message.peers_snapshot` | 展示待处理对端、水位及可选整体积压估计；不承担入库提交 |
+| `sync.started/progress/stopped` | 展示同步工作生命周期 |
+| `delivery.changed` | 在已处理消息后合并刷新界面；其计数不是当前未读总数 |
+| `message/group.read` | 用户实际阅读后上报业务已读位置 |
+| `message/group.readState`、`read_changed`、`read_state_sync` | 查询、观察及重连补偿同一 AID 的跨设备已读汇总 |
+
+```typescript
+await client.message.read({
+  scope: 'p2p', topic_key: 'inbox:primary',
+  last_read_message_id: 'm-100',
+});
+const readState = await client.message.readState({
+  scope: 'p2p', topic_key: 'inbox:primary',
+});
+```
+
+业务已读与交付 ACK 分开。`read` 返回设备写入回执，共享状态以 `readState` 或有效变更事件为准。`current_device_seq=null` 保留原值；超出安全整数范围的 `last_read_order/current_device_seq` 在 TS/JS 中为精确十进制字符串，比较时可转 `BigInt`，不能先转 Number。完整接入见 [跨设备已读指南](../跨设备已读未读SDK集成指南.md)。
+
+## 4. resolve：名片、frontmatter 与 owner 展示
+
+### 4.1 普通名片读取
+
+```typescript
+const profile = await store.resolve('alice.agentid.pub');
+if (!profile.ok) throw new Error(profile.error.message);
+const frontmatter = profile.data.agent_md?.frontmatter;
+console.log(frontmatter?.name, frontmatter?.description, frontmatter?.tags);
+```
+
+沿用 resolve，无需新增 frontmatter 查询方法。成功 `data` 包含 `aid`（AID 对象）、可选 `agent_md`、可选 `ownership` 和 `source`；`agent_md.content` 是完整原文，`agent_md.frontmatter` 是该名片的全部 YAML 元数据。
+
+常用字段包括 `aid/name/type/version/exttype`、`description/avatar/tags`、`owner/ownership`、实体的 `entity_cert_fingerprint`；`visibility/skills` 及其它扩展键存在时也返回。嵌套对象、数组、字符串、数字、布尔值和 null 保留解析后的类型。扩展字段在 TypeScript 中为 `unknown`，使用前按应用数据约定缩小类型。
+
+历史名片缺字段时不补默认值，裸 Markdown 的 frontmatter 为 `{}`。读取兼容不等于发布可省略当前 Schema 的必填字段。
+
+### 4.2 按需获取 ownership
+
+```typescript
+const withOwner = await store.resolve('alice.agentid.pub', {
+  ownership: client, ownershipTtlMs: 60_000,
+});
+if (!withOwner.ok) throw new Error(withOwner.error.message);
+console.log(withOwner.data.ownership?.status, withOwner.data.ownership?.owner_aid);
+```
+
+`ownership` 传已有 client 或实现共识接口的对象，不是布尔开关；SDK 复用 `checkOwnershipConsensus`，不另建连接。默认普通 resolve 不额外查询 Ownership。
+
+| opts | 默认值 | 应用选择 |
+| --- | --- | --- |
+| `forceRefresh` | `false` | 刷新远端身份与名片；启用 ownership 时也绕过共识缓存 |
+| `skipAgentMd` | `false` | 省略输出名片；显式请求 ownership 时，内部仍可读取权威名片 |
+| `timeout` | 名片下载 10,000 ms | Node/浏览器沿用名片下载超时范围，共识调用使用所传 client 的配置 |
+| `ownership` | 不传 | 普通展示不查询；需要关系状态时传当前 client |
+| `ownershipTtlMs` | 60,000 ms | 展示缓存期限；`0` 每次重新查询 |
+
+| `ownership.status` | 展示含义 |
+| --- | --- |
+| `consensus` | 当前双文件匹配且校验通过；此时 `owner_aid` 才非 null |
+| `released` | 当前材料确认已释放，旧 owner 不再据此获权 |
+| `unbound` | 当前有效权威名片没有关系声明，关系版本投影为 0 |
+| `single_sided` | 单方声明或准备，稳定关系尚未成立 |
+| `invalid` | 声明、签名或身份绑定等材料无效 |
+| `unavailable` | 读取、网络、证书、服务能力或一致性不足，当前无法确认 |
+| `not_applicable` | Group/Org 等使用专属生命周期 |
+
+`checked_at` 为本次检查完成的 Unix 毫秒，`cached` 表示复用了快照。实际读取 owner 文件后，可选 `owner_md` 包含 `owner_aid/bucket/path/exists/content/sha256/observed_at`；正文含签名，`observed_at` 为 Unix 秒。确认不存在时 `exists=false` 且内容、摘要为空；没有读取时省略该对象。
+
+SDK 将共识及 owner.md 原文一起缓存到 `agentmd.json.ownership_snapshot`，浏览器使用 IndexedDB 等价记录；不额外创建本地 owner.md 文件。目标、TTL、时钟及名片原文摘要须匹配才复用，`unavailable` 不复用。名片解析成功而额外共识失败时，外层仍成功，关系状态为 unavailable。
+
+自有身份 resolve 可返回本地未发布草稿，共识检查仍读取远端原件，两者通过共识的 `agent_md_sha256` 区分。`frontmatter.owner`、legacy `verification.ownership_status` 和展示缓存均不授予 owner 权限；执行端须使用新鲜共识并核对当前调用者、sub、完整声明及权限范围。完整输入输出见 [resolve 规格](06-API手册.md#resolve-输入与输出)。
+
+## 5. Ownership：审批、关系操作与恢复
+
+### 5.1 使用现有 2.1 入口
+
+| 发起角色或用途 | TypeScript 方法 |
+| --- | --- |
+| sub 申请 owner | `client.bindOwneraid(ownerAid)` |
+| owner 申请管理 sub | `client.bindSubaid(subAid)` |
+| 本端明确同意或拒绝请求 | `acceptOwnershipRequest(operationId)` / `rejectOwnershipRequest(operationId)` |
+| 当前 owner 释放 sub | `client.releaseSubaid(subAid)` |
+| 当前 owner 发起三方转移 | `client.transferSubaid(subAid, newOwnerAid)` |
+| 查询当前权威关系 | `client.checkOwnershipConsensus(subAid)` |
+
+应用在连接前订阅 `ownership.request/action_required/progress/completed/rejected/stopped/error`，保存 `operation_id` 与自己的业务记录。收到 request 后交由有权用户明确决定；应用审批不替代 SDK 的文件校验与最终共识。
+
+当前关系继续由 NS `agent.md` 和 owner Storage `default/sub_aids/{subAid}/owner.md` 确认。声明六字段和 `aun.ownership.sdk.v1` 控制格式沿用；无需迁移到独立关系资源。
+
+任务 completed 表示该次操作曾完成；之后的释放或转移不会抹去历史。展示当前关系另查共识。普通名片读取、正文更新不要求 owner Storage 在线或先有共识；更新仍须保留已有关系材料，并由 SDK 按本人签名和原 ETag/CAS 提交。
+
+Group/Org 使用专属创建、转让、rekey 和实体名片流程，通用共识为 not_applicable。详细审批及关系操作见 [Ownership 应用指南](Ownership2.1-SDK应用集成指南.md)。
+
+### 5.2 reset 的使用边界
+
+仅在用户明确要归档本端发起的未完成任务时执行：
+
+```typescript
+const reset = await client.resetOwnershipTask();
+console.log(reset.reset_operation_ids);
+console.log(reset.skipped_operation_ids);
+```
+
+该方法无参数，只处理当前 AID 发起的未完成绑定、释放、转移，保留终态历史、参与他人发起的任务及远端文件。无法安全判断的记录列入 skipped。reset 不解绑、不解锁、不删除 owner.md，也不自动发起新关系；不要放在每次启动或网络失败的通用重试逻辑中。
+
+升级后先恢复原存储和原任务。0.5.20/0.5.19 的 operation、有效审批、原签名字节及原提交条件继续保留；网络、IO 或 CAS 冲突不应通过 reset 清空现场。历史边界见 [编排指南恢复章节](Ownership-SDK编排指南2.1.md#8-崩溃与响应丢失后的恢复)。
+
+## 6. 凭证与组织集成
+
+### 6.1 取得当前托管凭证
+
+`credential.current` 是本地查询，输入为完整凭证或 CID，沿续期链返回当前托管记录，未找到为 null；记录的 `credential` 才是 CAP，可能还带 `membership_binding` 等材料。它不是新增的服务端 RPC，也不表示刚查询过远端授权状态。
+
+```typescript
+declare const originalCredentialCid: string;
+const managed = await client.credential.current(originalCredentialCid);
+if (!managed) throw new Error('没有当前托管凭证');
+const currentCredential = managed.credential;
+```
+
+业务请求应使用当前凭证及配套 binding，不长期复用初始化时截取的旧 CAP。完整 `credential.verify` 仍须验证证书、时间、audience、父链、当前状态、能力范围及实际请求绑定；`verifySignature` 只做签名预检。
+
+对于 SDK 已托管且具备续期材料的长期凭证，进入 READY 后恢复并检查续期，在线期间每 60 秒重新扫描。续期使用加密请求/响应、登记回执及提交确认，断线后复用原 checkpoint。缺少颁发方、登记或成员材料时，不能仅靠启用连接获得有效新凭证。
+
+已知撤销状态会用于当前凭证与证明链检查；旧 CAP 不因曾经有效而获得豁免。服务不可用、状态未知或回执不匹配时，暂停依赖该凭证的副作用操作。
+
+### 6.2 组织业务请求
+
+Credential 和 Org 业务 RPC 通过 Gateway service-plane；facade 存在不等于服务已经部署。组织受保护读取同样需要有效授权和请求绑定。
+
+下面的 `orgParams` 由应用提供，包含目标 `org_id`、当前成员 CAP/binding 及该方法所需业务字段；signer 来自当前认证主体，服务 AID 来自部署发现。
+
+```typescript
+import type { CredentialSigner, JsonObject } from '@agentunion/fastaun';
+declare const orgParams: JsonObject;
+declare const memberSigner: CredentialSigner;
+declare const orgServiceAid: string;
+const prepared = client.org.prepareRequest(
+  'org.member.list', orgParams, orgServiceAid, memberSigner,
+);
+const members = await client.org.member.list(prepared);
+```
+
+先准备完整授权包，再由 helper 生成 AAD、request binding 等材料；已签请求按原参数重试，不能签后修改业务字段。首次 join/inviteAccept 使用 admission 流程，目标成员仍须本人签名；owner 的代表证明不能替代成员签名。
+
+| 场景 | 接入要求 |
+| --- | --- |
+| 创建组织 | 使用 `client.createOrg(params, { aidStore: store })` 等高层入口，持久保存组织实体密钥和创建 checkpoint |
+| 入组/邀请 | 使用双方签署的 membership binding、成员 CAP 和登记授权；回执验证完成后才最终化 |
+| 成员续期 | 保留原成员关系及版本，新 CAP 登记确认后再撤旧 CAP；使用 `renewCredential` 或原自动续期流程 |
+| 转让组织 | 专属两阶段转让、rekey 和新证书；恢复同一 proposal、身份及原请求，不复制旧私钥给新 owner |
+| 组织名片 | 实体私钥主签，当前 owner 以本人 token 上传；可选 owner 附签，保留完整原文及原 CAS |
+
+`org.resource.create`、`org.task.create`、`org.host.add`、`org.workflow.create` 当前为 `NOT_IMPLEMENTED` 占位，不据此构建已可用功能。完整流程见 [凭证与组织应用指南](凭证与组织服务SDK应用集成指南.md)；本版续期、撤销及恢复变化以本文和 `python/CHANGES_FOR_PARITY.md` 的 0.5.21 章节补充。
+
+## 7. 诊断与错误处理
+
+```typescript
+const report = await client.debug.diag('message.*');
+console.log(report.passed, report.failed, report.skipped);
+for (const check of report.checks) {
+  console.log(check.method, check.status, check.stage, check.reason);
+}
+```
+
+scope 为空或 `*` 检查全部，`message` / `message.*` 选命名空间，完整 RPC 名精确选择，`debug` 显示用法。报告含当前 AID、分项阶段、耗时和汇总；缺少真实业务材料会 skipped。
+
+SDK 要求服务端确认 `dry_run=true`、`executed=false`。诊断通过说明对应 dry-run 阶段通过，不代表发送、审批、Storage 写入或完整跨域业务已执行成功；skipped 也不是通过。
+
+| 失败入口 | 应用处理 |
+| --- | --- |
+| Store 的 `Result.ok=false` | 读取 `error.code/message`，保留原始失败，不继续使用缺失的身份或名片 |
+| RPC/工作流抛异常 | 按 `AUNError` 数字 `code`、字符串 `stringCode` 及 `retryable` 分类；不解析错误文本 |
+| 共识 unavailable | 展示当前不可确认，待恢复后查询；不将其改成 unbound 或授权成功 |
+| CAS/目标/幂等键冲突 | 核对原任务及权威事实，停止盲重试；不刷新条件覆盖后续状态 |
+| CAP/成员状态未知或已撤销 | 停止依赖授权的操作，恢复受信状态与验证链 |
+| 消息持久化失败 | 让处理器失败并保留重放责任，以相同业务键恢复 |
+
+## 8. 升级、重启与验收
+
+从 0.5.20 升级时按以下顺序接入：
+
+1. 核对服务端 peer 能力及目标 SDK 产物；保留原 `aunPath`、设备、slot 和解密配置。
+2. 选择 batch 或原逐条消费，确保入库 Promise 与幂等键正确；移除应用自己提前 ACK 的逻辑。
+3. 将 P2P 主动历史与指定游标调用绑定到 sender；聚合 Pull 按 `peers/partial` 处理，目录估计仅用于展示。
+4. 名片页面改用 `agent_md.frontmatter`，需要 owner 展示时才启用 ownership；执行权限继续新鲜校验。
+5. 恢复原 Ownership、组织和续期 checkpoint，不通过清库、重注册或启动 reset 来“修复”失败。
+6. 请求前取得当前托管 CAP 及匹配 binding，保留真实登记回执和原已签请求。
+
+上线验收至少覆盖：消息批次入库失败和整批重放、断线后补拉、撤回重复、volatile-only peer、不同 sender 并行、身份切换旧响应隔离；名片缺字段和扩展类型、owner 缓存刷新及 unavailable；审批后崩溃、历史任务恢复与 reset 保留远端文件；凭证续期、撤销坏页、组织转让恢复，以及诊断 skipped。
+
+正常退出时停止业务入口，再释放订阅和客户端：
+
+```typescript
+for (const subscription of subscriptions) subscription.unsubscribe();
+await client.close();
+```
+
+本指南的短示例用于说明公开调用方式；完整业务函数及授权材料由应用实现。单域、跨 SDK、浏览器联网和双域验收分别记录，不能用类型检查或 dry-run 替代。
+
+## 9. 按领域继续查阅
+
+| 需求 | 文档 |
+| --- | --- |
+| 全部公开输入输出与事件 | [API 手册](06-API手册.md) |
+| peer、Pull/History/ACK、TTL 和目录 | [Message RPC](09-message-rpc-manual.md) |
+| 群生命周期、消息、成员与 Group FS | [Group RPC](09-group-rpc-manual.md) |
+| Ownership 审批、签验与恢复 | [Ownership 应用指南](Ownership2.1-SDK应用集成指南.md) |
+| CAP、成员及组织业务闭环 | [凭证与组织应用指南](凭证与组织服务SDK应用集成指南.md) |
+| 文件、ACL、上传下载 | [Storage RPC](09-storage-rpc-manual.md) |
+| 文档协作与流 | [Collab RPC](09-collab-rpc-manual.md)、[Stream RPC](09-stream-rpc-manual.md) |
+| 实现其它语言 SDK 或检查语义差异 | [0.5.21 开发与移植指南](0.5.21-SDK开发与移植指南.md) |