DSH 交接准备与恢复
此组件实现 RFC #2528 的交接准备和本地交付记录。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 响应,并协调启动读取与删除。原生目标 启动和接收验证需要单独验收。

