harness-dock 为产品、Agent 和自动化流程提供跨设备原生 Harness 接入与执行管理。这层基础设施分为 client、server、daemon、drivers 和 protocol 五个模块。设备使用具名 dock 集成层调用 ACPX：Codex 经 codex-acp 接入；dsh 实验路径经原生 dsh --profile acp 接入。跨机器通信和设备内部协议分为两个范围。
部署与连接方向#
应用与设备都主动连接 Server。两者通过 JSON-RPC / WebSocket 传递设备请求和执行回调；远程使用经过证书校验的 WSS，设备通常不需要开放公网入站端口。模型请求由设备上所选的原生 Harness 按其配置发起，图中以 Codex 为例。
职责与信任#
| 模块 | 拥有的状态 | 边界 |
|---|---|---|
| client | 连接、请求关联、回调有效期 | 不管理 Provider 进程、登录或本机目录 |
| server | 设备配对、应用授权范围、连接转发 | 不承接业务调度或替设备裁决执行完成 |
| daemon | 准入、Provider 进程、待批请求、执行记录和托管文件 | 生命周期独立于连接 |
| drivers | Codex 与实验 dsh 的 dock 集成：环境选择、回调、事件与结果差异 | 复用 Harness 原生工具和权限 |
| protocol | 公共 JSON 类型、版本、身份和预算 | 不引入调用方业务模型 |
server 是受信任的转发节点，TLS 不提供针对 server 的端到端内容保密。配对凭据分别用于设备接入和应用访问。远程传输必须校验证书和节点身份，明文仅限回环。
设备协议为 v3，server-client 协议为 v1；版本不匹配明确拒绝。每台设备绑定一个控制方，应用授权声明可访问的节点。
身份与状态#
- nodeId：稳定的设备身份；daemonId：本次 Daemon 实例身份。
- runId：调用方生成的单轮执行身份，与原输入绑定并持久去重。
- sessionKey：dock 托管会话身份，与原生 thread/session ID 分离。
- 原生续接身份：由已支持后端返回，后续执行显式提交。
执行状态为 running、completed、failed、cancelled 或 unknown。缺少权威完成证据时保持 unknown；取消请求、观察文本或传输成功不能替代终态证据。
一轮执行如何发生#
prepare准备本轮附加 skills 与输出目录，工作目录取自设备本地配置。execute校验输入、Provider 能力、设备容量与会话互斥，先持久化 runId 和输入指纹，再启动原生执行。- dock 集成层通过 ACPX 的
ensureSession、配置与startTurn接入 Codex。审批和应用工具通过原连接回调；原生工具与模型循环由 Codex 执行。 - Daemon 保存原生结果后返回；未取得可靠完成证据或结果无法保存时保留
unknown。应用继续验收业务结果。 - 确认结束后调用
collect验收、收存需要的输出，再release。释放托管资源不撤销文件修改或外部操作。
输入持久去重用于防止同一轮被重复派发，不承诺任务内部的所有外部操作天然只发生一次。工作目录与附加文件边界见 执行生命周期。
执行与恢复#
调用方先 prepare，再显式 execute。Daemon 负责准入、设备容量与本机会话互斥；相同原生会话不并发续接，不同会话按设备容量隔离。
Provider 进程与待批审批归 Daemon 所有。SDK/server 连接断开不会转移所有权，也不重放请求或决定。依赖应用响应的工具或审批仍可能因失联而失败或被拒绝。迟到审批失效，调用方必须响应 AbortSignal。
原生恢复上下文由 dock 集成层产生和解释，Daemon 只保存不透明内容。reconcile 从原记录选择 Provider 与上下文，只读查询原执行，不重新发现安装、不建立替代会话或发送 prompt。没有证据时仍为 unknown。
原生环境#
Codex 使用设备明确选择的安装、home、配置与登录。dock 状态独立保存，不改写原生认证或配置；调用方 skills 通过受支持的附加根增量接入。
Harness 拥有内部 Agent、模型循环、原生工具、MCP、插件、skills、memory 与权限规则。dock 连接必要宿主并转发原生交互，不能把共享 home、设备配对或新进程视为继承所有系统授权。
应用承担业务授权、数据来源授权、审批界面和最终结果验收。dock 不提供聊天、IDE、插件商店或业务权限系统。设备面板是持有人的轻量接入、状态与维护入口，正常任务、原生审批与业务结果仍在调用方应用中处理。App v0.1.3 提供按 Harness 区分的详情、固定回显与诊断，包含 Codex 支持与 dsh 实验适配。这些 Harness 测试是受保护管理 socket 上的固定诊断：Daemon 按 Harness 与测试 UUID 保存收据，复用相同 DeviceHost/ACPX 执行链，不接受任意 prompt、不增加通用执行入口，也不改变远程应用归属或原生权限所有权。Codex 测试使用原生只读模式；dsh 实验固定回显沿用原生权限配置，不提供只读保证，工具与业务授权仍由应用分别验收。
Codex 集成与 ACP 分层#
本仓库的 Driver 指 packages/drivers 中的 dock 集成层。ACPX 是它调用的 ACP 客户端运行库，codex-acp 是下层的 ACP Agent 端协议适配器；原生 Codex 持有模型循环、工具与权限。
Codex 使用上述固定执行路径。App v0.1.3 与开发者 SDK sdk-v0.1.2 的配套 macOS arm64 Daemon/CLI 另含 dsh 实验路径。Codex 各层职责与代码对应关系见 Codex 与 ACP 分层；发行物与能力边界见 支持范围。