# DSH 交接准备与恢复 (https://powercontext.oceanbase.io/zh/development/dsh-handoff-delivery/)

此组件实现 [RFC #2528](https://powercontext.oceanbase.io/zh/llms.mdx/rfcs/2528-dsh-plugin-ui-and-agent-handoff/content.md) 的交接准备和本地交付记录。DSH Host
认证、目标预检和启动由各自的服务处理。此组件本身不注册浏览器路由，也不会在 DSH 界面启用交付。

## 准备交付 [#准备交付]

使用 `integrations/dsh/plugins/powercontext/src/handoff/delivery.ts` 中的 `LocalDeliveryService`，传入交付目录的
绝对路径、Host 的真实 `PreflightGate` 和连接解析器。共用类型见 `handoff/contracts.ts`。Host 通过
`CallContext` 传入认证后的所有者和本次调用的取消信号。预检核对选中的会话、消息、包含该事件的截止点、目录和
工作区观测时间。连接解析器必须使用验证过的 Server、连接代次和 Scope；无法匹配时拒绝请求。绑定中只保存标识，
凭据由解析器保留在内存中。

首次请求等待准备结束；并发重复请求可以读到同一交付的 `preparing`，随后通过 `get` 查看状态。幂等键绑定一个
所有者和一份输入，携带不同输入重放时会拒绝。同一已验证绑定下的等价请求复用交付。用户明确选择创建新版本时，
使用新的请求键并传入旧交付的 `supersedesDeliveryId`。旧结果和接收尝试仍可通过原 ID 查看。

| 可用输入 | 准备路径 |
| --- | --- |
| 经检查的 `workInput` | 按现有 `CurrentWorkHandoff` 字段、证据规则和 32 KiB 输入上限校验；调用一次 `handoff_current_work`，保存完整 Prepared 和 boundary receipt。 |
| 已配置生成流程和可信边界读取器 | 通过 Source API 保存有界任务证据，调用一次 `prepare_handoff`，校验 draft 后原样发送给 `finalize_handoff`。保存完整结果和实际采集回执。 |
| 用户明确选择的精确 Handoff Revision | 在已验证的 Scope 中核对精确的 `ArtifactReference` 并保存该引用，沿用整数 `revision` 字段。 |
| 没有可用的生成流程或经检查的字段 | 返回 `needs_input`；用户补充并检查工作字段后创建新版本。 |

Host 的 `BoundaryReader` 提供选定回复和该边界的观测。底层读取必须遵守传入的限制；采集器也会限制总事件数
（含选定回复，最多 512 个）、总量（最多 256 KiB）和工作区证据（最多 32 KiB），并遵守更低的 Source 或模型
输入预算。采集器保留已知测试状态、提供的精确证据引用、revision 和工作区观测。最多处理 16 条 Host 遗漏说明；
如果有说明未能纳入，则记录一条汇总说明。未捕获检查证据时结果未知；
明确未运行、失败、中断和证据缺失各有不同含义。读取器不运行测试，也不能用当前工作区替代缺失的历史观测。
生成路径需要配置适合生成的客户端超时；服务给模型调用设置 90 秒上限。生成失败后不自动切换路径，
也不会自动提交里程碑。

## 包完整性与恢复 [#包完整性与恢复]

Host 在本地文件系统的用户数据下使用私有目录。交付服务对已打开的目录持有内核独占锁，直到服务关闭或 Host 进程
退出。macOS 使用系统文件锁，Linux 使用 util-linux 的 `/usr/bin/flock`；无法获取锁时不会打开交付存储。旧的
PID 标记文件会被忽略。打开同一目录前，先停止仍在使用 PID 标记的旧 Host。

交付记录和包使用 `powercontext.dsh-delivery.v1`，按交付 ID 分开保存。远端调用前先保存身份、绑定和类型为 `content` 的 ACK
source ID。原子发布完整包之前先持久化预期大小和文件校验和。恢复时校验文件字节以及原始边界、绑定、接收尝试
和载体，通过后才发布 `prepared`。中断时没有有效包则记为 `unknown`；已有 Source 或重新 finalize 无法恢复
原包。发送前取消会停止准备；发送后中断可能留下未知结果。取消不会删除已经保存的完整包。

`getForLaunch` 校验所有者和包完整性，返回已保存的精确绑定、载体选择、路径、校验和及 ACK 身份。Prepared
digest 是 Core Work 对规范化 Prepared 值计算的摘要；包的 SHA-256 校验整个 JSON 文件的字节。两者分别保留。
导出返回校验后的完整字节。如果启动流程要异步使用路径，请在 `withLaunchBundle` 中读取或复制到验证过的共享位置；
持有路径期间禁止显式删除和自动清理。Host 关闭时调用 `close`。

默认上限为 100 个载体记录或 50 MiB，并为正在准备的交付预留空间。容量不足时不会淘汰待接收或固定保留的包。
所有者可以固定、导出或显式删除交付。删除后保留幂等键标记 30 天。自动清理需要后续的精确 ACK 验证服务为该接收
尝试提供确认时间；已确认且未固定的包可在七天后清理，元数据保留到确认后 30 天。清理不删除 Server 记录或写入
接收状态。不支持的记录版本会被拒绝，原文件保留。

Host 联调还需接入真实认证、边界读取和连接解析，将交付错误映射到 Host 响应，并协调启动读取与删除。原生目标
启动和接收验证需要单独验收。
