开发与验证

验证公开 SDK 下载到实际模型任务的最短路径见 第一个真实任务。同机隔离目录成功仅证明本机 SDK、server、Daemon 和原生 Codex 路径，不替代另一台 Mac 的首装、App 签名或全部工具验收。

设备 App 与 SDK 分别发行：App v0.1.3 与 SDK sdk-v0.1.2 均包含 Codex 支持和 dsh 实验适配。源码候选的界面、实验适配与验收记录不能直接推导某个已发布产物的能力。

验证分别覆盖源码、分发产物、真实 Harness 和目标设备。每项结论绑定实际测试的源码提交、平台及产物摘要，不由相邻版本或某一层通过推导全部能力。

验证层级#

确定性与离线检查#

pnpm check
pnpm smoke:source
# 先安装 Gitleaks（macOS：brew install gitleaks）：
pnpm check:privacy
# 如需验证可选离线运行包：
pnpm bundle .local/bundles/verify
node --import tsx scripts/accept-bundle.ts .local/bundles/verify --offline

每次使用新输出目录并串行构建。离线验收不使用原生登录或模型账户；SDK 不应带入 drivers、ACPX 或 Codex ACP 依赖。公开类型的正向及负向 fixture 在 pnpm check 中编译。

源码冒烟使用隔离 HOME 与临时端口，不使用原生账户或模型。隐私检查对工作区源码与本地可达 Git 历史运行 Gitleaks，输出隐藏命中值，并检查被强制加入 Git 的本机运行数据、个人 home 路径和非示例服务 IP。CI 拉取完整历史并校验固定版本扫描器摘要。语义隐私、业务内容和图片仍需人工复核；通过本地检查不表示远程 CI 已通过。

本机一键测试验收#

本节是 App v0.1.3 固定本机测试及后续源码变更的验收要求。Codex 与 dsh 的结果分别核对；dsh 保持实验性。验收要求不等于某次发布或全部目标设备已经验证通过。

确定性测试检查受支持的 Harness 与测试 UUID 请求边界、按 Harness 隔离历史与收据、持久化先于派发、重复与丢失收据不重派、重启转 unknown、写入故障不报告成功及回调隔离。真实 GUI 需核对首次邀请连接不受环境检查阻挡、首页 Harness 数量与安装列表、独立服务连接及正常回到调用方应用的路径；未知检测不误报为零，刷新失败标明上次结果，首页不常驻展示任务统计。点击 Harness 条目核对详情、固定回显、检查时间、原测试记录和历史不会跨环境复用；测试运行或启动收据待确认时，可只读查看其他详情，但原测试归属不变且不能另启测试或维护后台。关闭重开只查询原记录，原应用连接保持。面板品牌标识与 App 图标同源，强调色、系统浅深色外观与单一返回入口需实际检查。还需核对右上角收起按钮只隐藏弹层并保留菜单栏图标与 App，“退出 LaunchApp”只退出界面应用，“停止后台”才停止后台；安装或维护写操作期间可收起，App 与 helper 继续处理且真正退出被禁用。再在可返回首页的“设置与维护”独立页面核对日志、版本信息、自启、停止与版本切换。Codex 使用原生确认的只读模式；dsh 实验固定回显沿用原生权限配置，不提供只读保证。出现工具活动或额外审批不能判定通过；单次回显不替代下方应用侧两轮、工具、审批或独立安装验收。

真实模型验收#

pnpm accept:codex
# 或验证实际独立运行包：
node --import tsx scripts/accept-bundle.ts .local/bundles/verify

真实验收使用专门的设备/应用身份、端口、工作目录和新 runId，只提供无外部副作用的合成工具。模型请求会使用账户额度。验证应检查原生终态、会话/turn 身份、工具/审批计数与送达，不能只凭输出文本判成功。

响应未确认时保留原 runId，只读查询，不自动补发 prompt、决定或工具。显式 pre-admission busy 可以只重试同一 prepare；断线或未知响应立即停止。取消只在原生确认 cancelled 时成立。

只读恢复测试使用完成记录副本构造 unknown 时，应明确这是查询兼容性验证，不冒充真实崩溃。必须核对原输入、环境、thread/turn 和完整消息，阻止 session 创建与 prompt 路径。

执行 CLI：真实 Codex 验收记录#

以下记录按实际验证的源码提交分别说明通过项和边界，详细保留成功、SIGINT 与 SIGKILL 的结果。它们均为本机源码链路证据，不冒充 SDK 发行包、另一台设备或生产部署的实测结果。日常接入与命令用法见 SDK 调用端 CLI。

真实 Codex 验证结论与范围

2026-10-30，执行 CLI（提交 70918bc）已在同一台 macOS arm64 上，使用已安装的真实 Codex、隔离 Server、独立 Daemon 进程和应用身份验证通过：

• 任务提交：run 退出 0，取得原生 completed 结果。
• 原生审批：终端呈现一次真实命令审批，精确选择 allow_once，收到成功送达回执；对应原生命令退出 0，校验文件内容与最终回复均符合预期。
• 结果查询：另起 status --receipt CLI，按原 nodeId 和 runId 查询；返回的原 threadId、turnId 及完整结果一致，未重派任务。

上述首轮验证仅覆盖本机源码链路的一次成功执行、一次性命令审批和完成后只读查询；未覆盖跨机器、断线或重启恢复、两轮续接、全部工具或插件、独立发行包及生产部署。验证未改动原生配置和认证文件，隔离 Daemon 已通过受保护管理接口正常停止。原始配置、日志与验证记录仅留在 ignored .local/，不随文档提交。

CLI 中断后按 receipt 查回原执行

2026-10-30，执行 CLI（提交 4fcd3b8）在本机 macOS arm64 使用真实 Codex、隔离 Server、独立 Daemon 进程和专属应用身份追加验证通过：

• 中断观察：原生命令已开始且尚未完成时，向当前 CLI 子进程发送 SIGINT。CLI 退出 130，返回 unknown；Daemon 仍持有原活动执行，中断观察不代表取消任务。
• 查回原执行：CLI 连接关闭后，另起 status --receipt 按原 nodeId 和 runId 只读查询，先返回 running，随后取得 completed。原生 threadId、turnId 与中断前一致，最终结果包含预期标记，后续只读快照与完整结果一致；receipt 文件未改动。
• 未重复提交：真实 Server 入口被动计数显示 prepare、execute 各一次，后续连接仅调用 getExecution 和 events。原生 turn、命令执行、文件标记效果及设备持久化执行行均只有一次，原生命令退出 0。

上述 SIGINT 验证范围限于同一台 Mac 上，SIGINT 只中断 CLI 观察、Server 与 Daemon 持续运行时，按原 receipt 查回原执行；未覆盖 SIGKILL、Daemon 或 Server 重启、跨机器及真实网络故障恢复。验证未改动原生配置和认证文件，完成后已通过受保护管理接口正常停止隔离 Daemon。原始配置、日志与验证记录仅留在 ignored .local/，不随文档提交。

CLI 被 SIGKILL 后按 receipt 查回原执行

2026-10-30，执行 CLI（验证时提交 7a51fd1）在本机 macOS arm64 使用真实 Codex、隔离 Server、独立 Daemon 进程和专属应用身份追加验证通过：

• 强制退出：原生命令已开始且尚未完成时，仅向当前直接启动的 CLI 子进程发送 SIGKILL。系统退出记录为 code: null、signal: SIGKILL，stdout 为空，没有最终 JSON；Daemon 仍持有原活动执行。
• receipt 保留：Server 收到唯一 execute 入口消息时，receipt 已完整可读，原身份和输入匹配，权限为 0600。强杀前后及所有查询完成后，文件指纹保持一致。
• 查回原执行：CLI 连接关闭后，另起 status --receipt 按原 nodeId 和 runId 只读查询，先返回 running，随后取得原执行的 completed。原生 threadId、turnId 与强杀前一致，完整结果符合预期，并与后续只读快照一致。
• 未重复提交：真实 Server 入口被动计数显示 prepare、execute 各一次，后续连接仅调用 getExecution 和 events。原生 turn、命令执行、文件标记效果及设备持久化执行行均只有一次，原生命令退出 0。

范围限于同一台 Mac 上仅强杀 CLI、Server 与独立 Daemon 持续运行后，按原 receipt 查回原执行；未覆盖强杀或重启 Daemon/Server、整机断电、跨机器、真实网络故障、原生进程崩溃或强杀期间的新审批请求。验证未改动原生配置和认证文件，完成后已通过受保护管理接口正常停止隔离 Daemon。原始配置、日志与验证记录仅留在 ignored .local/，不随文档提交。

目标环境验证#

CI 状态和 artifact 页面提供源码提交与分发摘要，运行包内 release.json 和 SHA256SUMS 用于读回平台、版本、来源及传输完整性；摘要不单独认证发布者。

原始日志、配置、配对、模型正文和实验产物留在 ignored 的 .local/ 或受保护运维目录。共享结论只包含去标识结果与限制，不提交私人服务地址或运行清单。

独立设备升级前确认无活动/未决执行，保留恢复材料，通过受保护管理接口切换并读回版本、身份、连接、两轮执行和文件保留。程序回滚不撤销数据库变化或外部效果。

0.1.0 首版验收清单#

按同一候选源码 revision 与产物摘要记录以下结果。该清单列出交付要求，不代表所有目标环境与工具已全部验证；本机、独立设备和远端发行证据分别保留。

原始配置、日志、截图和真实验证输出留在 ignored 的 .local/；公共说明只记录去标识结论与未覆盖项。公开 Release、npm/镜像发布、站点发布或现用服务部署需各自明确执行。

开发者：从源码跑通完整链路#

以下是开发者在一台 Mac 上跑通完整链路的源码示例。使用菜单栏 App 接入已有服务的设备用户，无需执行这些源码命令。

当前支持 macOS arm64 + Codex，需要 Git、Node.js 22.19+ 和本机已安装、已登录的 Codex。从源码即可运行；所有命令从仓库根目录执行，首次使用新的 .local/quickstart 目录。

1. 获取并构建源码

git clone https://github.com/hutian-ai/harness-dock.git
cd harness-dock
npm install --global pnpm@12.15.0
pnpm install --frozen-lockfile
pnpm build
pnpm smoke:source

smoke:source 使用隔离 HOME、临时回环端口和禁用的 Codex，检查源码 CLI、SDK、后台启停与文件管理，不读取原生认证或调用模型。配置、配对与验证输出保存在 ignored 的 .local/ 中。

2. 启动本机 server

pnpm server init .local/quickstart/control
pnpm server run .local/quickstart/control/server.json

保持该终端运行。init 生成 server 配置、设备配对文件和应用凭据。回环 WS 适合本机验证；跨机器连接使用已配置、校验证书的 WSS，见 服务端部署。

3. 配对与启动设备

在第二个终端执行：

mkdir -p .local/quickstart/work
pnpm daemon init --cwd "$PWD/.local/quickstart/work" \
  --home "$PWD/.local/quickstart/device" \
  --pairing "$PWD/.local/quickstart/control/device-pairing.json"
pnpm daemon start .local/quickstart/device/config.json
pnpm daemon doctor .local/quickstart/device/config.json --json
pnpm client nodes .local/quickstart/control/client.json
pnpm client doctor .local/quickstart/control/client.json --probe --json

后台 Daemon 独立于终端和 SDK 连接。doctor 默认不发送模型 prompt；--probe 显式探测原生 ACP，可能建立协议会话。每台设备只有一个应用拥有者，每个应用身份只有一个活动连接。下方 CLI 只用于该应用身份没有其他活动连接时的首次验收；已有应用连接时，从原应用进行验证。需要独立实验时使用隔离的 server/设备身份。

4. 验证真实两轮执行与审批

pnpm client test .local/quickstart/control/client.json --approval

命令会发送两次合成模型请求并使用原生账户额度；带 --approval 时需交互终端。基础回显与同会话续接测试可省略 --approval。原生审批展示可用选项，由用户决定并返回精确 optionId。成功结果包含 state: completed、sameSessionVerified: true 与 approvalVerified: true。若需指定模型，增加 --model <可用模型>。

响应未确认时保存原 runs/runId，再查询原执行：

pnpm client status .local/quickstart/control/client.json \
  --node-id <设备UUID> --run-id <原执行UUID>

unknown 不代表成功或已取消，不换 runId 重发 prompt、工具或权限决定。原生桌面/浏览器能力仍由该设备原生安装与授权决定。

5. 独立设备连接已有 server

在独立 Mac 完成第 1 步。由 server 管理者为这台设备创建独立身份、授权给应用并加载配置，再安全提供专属 device-pairing.json，其中应包含已配置的 WSS 入口。保存为 .local/device-pairing.json，执行：

mkdir -p "$HOME/harness-work"
chmod 600 .local/device-pairing.json
pnpm daemon init --cwd "$HOME/harness-work" \
  --home "$PWD/.local/home-device" --pairing "$PWD/.local/device-pairing.json"
pnpm daemon start .local/home-device/config.json
pnpm daemon doctor .local/home-device/config.json --json
pnpm daemon status .local/home-device/config.json

私有 CA 可在 init 增加 --ca-file /absolute/trusted-ca.pem；保持证书验证。原生安装与登录属于当前 Mac 用户。应用 client.json 和设备配对凭据分别授权，不能混用。

持有应用凭据的控制端使用 status 返回的 nodeId 验收：

pnpm client doctor /private/client.json --node-id <设备UUID> --probe --json
pnpm client test /private/client.json --node-id <设备UUID> --approval

6. 停止与后续接入

pnpm daemon stop .local/quickstart/device/config.json
# 独立设备使用自己的配置路径：
pnpm daemon stop .local/home-device/config.json

管理命令通过受保护的本地 socket 寻址拥有者。源码启动不注册登录自启；版本化安装、自启、升级和回滚见 设备维护。更新前确认无活动或 unknown 执行并通过原入口停机，不在运行目录重装依赖或构建。应用通过 连接 SDK 接入。

dsh 真实本机验收#

在 macOS arm64 安装并配置原生 dsh 后，维护者可运行：

pnpm accept:dsh

该命令构建源码并使用原生账号和模型额度，通过本机隔离的 SDK → Server → DeviceHost fixture 验证 MCP 成功/错误与送达、调用方/原生项目 skills 共存，以及审批允许、拒绝、取消后旧决定失效和一次性授权作用域。测试输入、回调和原生结果及源码摘要保存在 ignored .local/dsh-acceptance-*。不在 CI 配置原生凭据，不上传真实验收产物。

审批 fixture 仅为被测试的原生子进程选择 read-only；只有实际观察到原生拒绝和审批回调才计为通过，不修改用户 settings 或现用 Daemon。MCP 错误结果在原生投影为 failed 时，其送达保持 unknown。本机 fixture 不替代独立 Daemon 进程、其他设备或新发行包验收。

Windows 原生候选验收#

Windows 11 x64 的 CLI/Daemon、Codex 和 dsh 接入需按源码版本进行实机验收，已完成的验收见下文。macOS 上的 pnpm check、类型检查或模拟 ACP 不等于 Windows 验证通过。现有全量 check 含 Unix/macOS fixture，尚未声明全量测试套件可在 Windows 运行。

• 按原生安装步骤构建、启动，确认私有 ACL、受保护命名管道、重复 start、status、stop 和重启后的原身份。错误 token 必须拒绝，篡改 PID 不改变管理目标。
• 用另一普通用户及网络登录确认无法访问控制/MCP 命名管道与私有配置；验证多次连接后的 ACL。权限工具不可用或 ACL 过宽必须失败。
• 分别确认 Codex/dsh 的安装发现、ACP inventory 和纯文本真实模型完成；连接、协议 ready 与模型执行分别记录。
• 从独立调用方选择 nodeId，验证原生工具、审批允许/拒绝、回调失效、按原执行查询及不重派。dsh 原生结果查询能力按适配器声明，不推断等同 Codex。
• 确认调用方 skills 与原生配置共存，拒绝 Windows 设备名、NTFS 备用数据流、大小写冲突与目录逃逸；验证产物读取及受保护清理。
• 同平台运行目录的固定入口安装、离线启动、升级、回滚与用户文件保留单独验收。Windows 自启、链接协议注册和归档发行不在本候选范围。

证据绑定源码 revision、Windows/Node/Harness 版本与候选摘要，保存在 ignored 的 .local/。不公开真实地址、配对身份、凭据、日志或模型输出；缺少完成证据时保留 unknown，不自动重复任务。

同一版本的跨设备产品验收#

记录源码 revision、Server/SDK/App 与已安装后台的版本和摘要，用真实 Linux Server 的受信任 WSS/HTTPS、独立 Mac 和应用完成同一条链路：管理员签发应用凭据与设备邀请 → 独立 Mac 首装并确认邀请 → 应用选择设备 → 原生任务及必要审批 → 收存结果/文件并业务验收 → 应用断线后按原 receipt 查回 → 明确释放托管文件。每步记录通过、失败或未验证；设备回显、localhost 连接和合成 fixture 不能代替整条链路。

本节是验收要求，不是通过记录。原始地址、身份、日志、截图与模型输出保存在 ignored .local/；对外只给绑定版本的去标识结论和未覆盖项。GPUI、Windows、新 SDK 接口与准入恢复分别按候选验收，不由公开 Swift App 或相邻版本推导。

Windows 源码真实验收#

2026-11-08 在 Windows 11 x64、Node.js 24.22.1 上完成原生验收：Codex 0.167.0-alpha.3.2 和 dsh 0.2.2-rc.1。结果属于本次源码变更，不代表已发布的 macOS App 或 SDK 包新增 Windows 发行。

• Codex：SDK → Server → 独立 daemon → ACPX/Codex ACP；模型、MCP 与审批投递、空闲释放后的同会话续接、重复请求与身份冲突、原生事件投影、断线观察不重派、遗忘保留用户文件。
• dsh：SDK → Server → DeviceConnection/DeviceHost → ACPX → 原生 dsh；MCP 成功和错误回传、原生与调用方 skills、写入审批允许/拒绝/取消后迟到决定，以及单次授权不扩大到后续写入。该脚本使用隔离的 DeviceHost；另以 pnpm accept:dsh:daemon 验证独立后台 CLI 启停、真实 MCP、空闲释放后同会话冷续接、去重与冲突、断线不重派和遗忘保留用户文件。
• 确定性 Windows 检查另覆盖私有 NTFS ACL、受保护命名管道、后台启停、安装/升级/回滚及超过 MAX_PATH 的两种 Harness 会话存储。修复只在系统临时目录创建调用处使用扩展路径，保留原有路径和身份校验。

使用自身已登录的 Codex 或已配置的 dsh 执行 pnpm accept:codex、pnpm accept:dsh 和 pnpm accept:dsh:daemon，会使用模型额度。dsh 可通过 HARNESS_DOCK_ACCEPT_DSH_MODEL 显式选择本机目录已广告的模型原始 ID；例如 ["deepseek-official","deepseek-flash"]。dsh 0.2.2-rc.1 要求 Node.js 24.9+，daemon 启动该 JavaScript 安装时也须满足其 Node 要求。

dsh 模型目录检查保持只读：只有当前原生模型的推理强度选项已读取，其他模型不推断强度列表，不通过切换默认模型探测。原始验收输入、配置、身份、地址、日志与证据留在 ignored .local/，不进入源码、补丁或发行包。

Windows GPUI 本地窗口验证#

本次 Windows x64 候选通过 Rust 原生编译和 9 个界面逻辑测试，实际打开“界舟 · Harness Dock”窗口，验证邀请输入、确认按钮状态和配对文件入口已呈现。另以打包后的完整 daemon 目录在独立本机服务器上验证配对文件摘要、安装后台、连接、停止、重启与移除连接；临时测试保留在独立私有目录，不使用客户端当前的服务器绑定。Windows 专项检查还验证许可原始字节、长路径私有 ACL 和随包 Node 的深路径安装/升级/回滚。服务器接入与模型执行属于独立证据，原始材料留在 ignored .local/。

Windows 窗口生命周期复核

本地候选已修复 GPUI Windows 应用级隐藏为空操作导致关闭按钮无响应的问题。关闭按钮、Control-W 与托盘收起使用同一个原生窗口隐藏入口；托盘恢复显式显示窗口后激活。托盘不可用时沿用有维护保护的退出界面逻辑，避免收起后无法找回。

本机运行复核已确认：点击 X 与 Control-W 收起窗口，托盘恢复由设备用户确认；关闭、恢复前后受保护本地接口读回同一个后台拥有者且连接保持。独立未绑定窗口验证最大化/还原、最小化、Control-2 设置、深色切换及配对文件对话框取消。Rust 构建与 9 项界面逻辑测试通过。托盘创建失败回退为代码复核，未模拟故障；最小窗口尺寸本轮未完成视觉验收。不据此宣称全部 Windows 环境已验收。

托盘临时界面收起

Windows GPUI 托盘小窗在打开时显式激活，以便点击外部或切换应用时触发失焦关闭；进入主面板前先移除小窗。直接激活主窗口或收到主窗口打开请求也清理现有小窗，不等待 Harness 发现完成。保留 Escape 和再次点击托盘图标收起。

本机独立未绑定窗口已通过界面操作及临时生命周期追踪确认：打开时得到激活，点击主窗口空白处或切换到另一应用时失焦、销毁并清理小窗句柄。临时追踪已从交付源码移除。最终构建与 9 项 Rust 界面逻辑测试通过，当前后台拥有者与连接保持。macOS 已核对为 AppKit 原生菜单路径，不使用这段 GPUI 小窗；本轮只有代码复核，没有 Mac 真机或 macOS 构建验证。

Windows 程序图标

Windows 构建从与 macOS 相同的 AppIcon.png 生成七种尺寸 ICO，作为 ID 1 图标资源嵌入 exe，由 GPUI 加载为窗口类图标。构建同时嵌入产品名称和版本信息；资源编译失败会阻止生成缺少图标的候选程序。本机已通过 Windows 图标提取接口读回界舟图案并核对 exe 产品信息，构建与 9 项 Rust 界面逻辑测试通过。

前述托盘小窗交互也已由设备用户确认：点击外部空白和选择 Codex 进入主面板时都会收起。此项确认仅覆盖 Windows，不代表完成 macOS 真机复测。