界舟Harness DockApp v0.1.3
文档 / 开发与参考

设备后台与升级

面向维护者：独立后台安装、升级、回滚和实验平台路径。

这页面向需要安装独立后台、管理版本或排查旧安装的开发者和维护者。普通设备用户只需安装与连接，日常操作见App 使用指南。

当前 App v0.1.3 适用于 macOS 15+、Apple 芯片，自带 Node.js 与独立后台。下载客户端。

安装或替换 App#

解压，将 Harness Dock.app 放入应用程序目录。关闭旧界面后再替换；不要直接修改现用后台的运行目录。替换 App 不会自动升级后台。

向管理员取得邀请或配对文件，在 App 核对服务器和执行目录后接入。已有设备 config.json 不是配对文件。

完成连接#

概览确认连接后回到调用方产品。安装状态、服务器连接和模型响应分别代表不同事情，不要把它们互相替代。

后台由谁维护#

App 管理的安装由随包 helper 通过受保护的本地控制接口维护；独立 CLI 安装沿用原安装入口。升级和回滚需要设备空闲，保留配置、身份和历史；不根据保存的 PID 发送信号，也不绕过后台持有的锁。

旧版升级与安装详情#

App v0.1.3 按后台发现结果逐项展示 Codex 与 dsh；每类使用后台选定的安装与原生 Home，不枚举任意 Home 或账号。测试类型来自后台能力元数据，展示安装条目不代表对应后台已经提供测试能力。

旧版 v0.1.1 的按钮位置见旧版操作对照；更新 App 与后台的顺序见更新与回滚。更新结果未确认时只读查询原状态，不自动重试维护或重发执行。

开发者：从源码安装#

以下命令仅供开发者或维护者使用，直接安装客户端的设备用户可跳过。

维护者可从固定源码构建供验证和发行的客户端；当前产物只有本地 ad-hoc 签名，尚未完成 Developer ID 签名与公证。维护者执行 pnpm panel:build 生成 App、ZIP、摘要和安装说明；用 --bundles .local/bundles/candidate --output .local/panel/candidate 可复用同平台运行包，输出目录必须不存在。边界与构建细节见面板维护说明。

sh
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

server 管理者需为这台设备生成独立身份、授权应用并加载配置。通过安全渠道取得专属配对文件，保存为 .local/device-pairing.json；文件应包含正确的 WSS 入口。

sh
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。不覆盖原生配置、认证或权限。先用 doctor/status 确认连接，再由持有应用凭据的调用方按 快速开始 验证两轮上下文、工具与审批。

开发者：源码运行维护#

sh
pnpm daemon logs .local/home-device/config.json
pnpm daemon stop .local/home-device/config.json
pnpm daemon start .local/home-device/config.json

源码后台启动不自动注册登录自启。升级前确认无活动与 unknown 执行，通过当前入口停机，保留配置、状态、原生 home 和用户工作目录。记录旧提交，在干净检出中更新源码、安装锁定依赖并构建，再用原配置启动和读回。源码回退不撤销数据库变化或已发生的外部效果。

如需固定安装入口、登录自启或受保护的版本切换，可选用下述运行包。包可按 构建与分发 从固定提交生成，无需 npm 发布。

维护者：独立运行包安装#

从 server 管理者取得本设备专属的 device-pairing.json，保持文件仅属主可读写。应用凭据与设备凭据分别发放，不要混用。

sh
mkdir -p "$HOME/harness-work"
node daemon/dist/cli.js setup \
  --cwd "$HOME/harness-work" --home "$HOME/.harness-dock/.local/device" \
  --pairing /private/device-pairing.json --bundle ./daemon

setup 安装到独立版本目录并启动设备；相同身份可以继续 setup，配置冲突拒绝覆盖。首次安装如需用户登录自启，显式增加 --autostart。

以下命令使用固定安装入口：

sh
node "$HOME/.harness-dock/.local/device/installation/launch.cjs" doctor
node "$HOME/.harness-dock/.local/device/installation/launch.cjs" status
node "$HOME/.harness-dock/.local/device/installation/launch.cjs" logs
node "$HOME/.harness-dock/.local/device/installation/launch.cjs" stop
node "$HOME/.harness-dock/.local/device/installation/launch.cjs" start

doctor 默认不发送模型。connected 只表示 server 连接，安装、原生 ACP、模型执行和工具可用性分别确认。管理通过设备受保护的本地 socket 完成，不按保存的 PID 发送信号。

维护者：命令行自启#

sh
node "$HOME/.harness-dock/.local/device/installation/launch.cjs" autostart
node "$HOME/.harness-dock/.local/device/installation/launch.cjs" autostart --disable

自启使用当前用户的 macOS LaunchAgent，在用户登录后生效；不提供登录前系统服务或唤醒休眠设备。正常 stop 不会被异常重启策略立即拉起。关闭自启会在安全停机后移除本设备注册，不删除配置或 Provider 数据。

维护者：命令行升级与回滚#

从可信来源取得或按构建指南生成匹配平台的 daemon 包，核对来源、版本和摘要：

sh
node "$HOME/.harness-dock/.local/device/installation/launch.cjs" upgrade --bundle /absolute/new/daemon
node "$HOME/.harness-dock/.local/device/installation/launch.cjs" status
# 显式切回 previous：
node "$HOME/.harness-dock/.local/device/installation/launch.cjs" rollback

活动执行、维护或 unknown 会阻止版本切换。不要清库、强杀或标记成功来绕过；先按原身份查询未确认执行。

升级校验并暂存产物，再由拥有者检查空闲并切换。启动失败会报告是否确认恢复原版本，结果未确认时查 status/logs，不重发任务。回滚仅切换程序，不回滚数据库、用户文件或已发生的外部效果；协议/状态格式不兼容时拒绝。

保持配置和安装路径稳定，不在封存的版本目录运行包管理器。替换 Node 时使用 upgrade --node /absolute/node 更新固定入口。原生 home、登录、配置、会话与用户工作目录独立于程序版本。

本机网络依赖#

设备配置的 providers.codex.environment 与 providers.dsh.environment 仅接受 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY 及其小写形式，以及 NODE_EXTRA_CA_CERTS、SSL_CERT_FILE、SSL_CERT_DIR、REQUESTS_CA_BUNDLE、CURL_CA_BUNDLE。每值最多 16 KiB 且不含 NUL；配置文件须由当前用户持有且无组/其他用户权限。

TLS 私有 CA 使用初始化的 --ca-file。不关闭证书验证，不复制整个终端环境，不将临时原生宿主端点写入自启配置。

后续源码与本地候选：代理自动识别

此项尚未进入已发布的 App v0.1.3。设备后台在启动时按设备显式代理配置、启动环境代理变量、macOS 固定系统代理的顺序选择。只传递代理白名单，其他网络依赖如证书文件仍需显式配置；不复制全部环境或改写原生 Harness 的登录与配置。

代理按来源成组选择，HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 及其小写形式归一；同一来源小写优先，显式代理空值阻止自动回退。NO_PROXY 可独立覆盖，自动设置包含本机地址的绕过项，系统例外列表由原生客户端解释。PAC 和自动发现不作猜测，无法读取或解释系统设置时诊断显示未验证，需填写明确的代理配置后执行。更改后在设备空闲、无待核对执行时重启后台；登录自启使用设备配置或当时的系统设置，不保存临时终端代理凭据。

候选 App 的安装与连接诊断显示运行中后台报告的代理来源与代理/直连状态，不显示代理地址和凭据。旧后台未报告时显示未验证；该配置检查不证明模型连通性，需单独运行固定回显。

Windows 11 x64：CLI/Daemon 源码候选#

此路径面向 Windows 11、Intel/AMD x64，连接该用户已有的 Codex 或 dsh 安装与登录。真实执行和本地 GPUI 窗口已分别验收；它仍为源码候选，不属于 App v0.1.3 或 sdk-v0.1.2 的已发布支持。当前提供 Daemon/CLI 手动启停及同平台运行目录安装、升级与回滚；Windows 桌面可按本页的 GPUI 源码候选步骤构建；登录自启和正式下载发行包尚未提供。Daemon 运行在 Windows 本机。

先在目标 Windows 上准备 Node.js 22.19+、仓库固定版本的 pnpm，以及所选 Harness 的原生安装和登录。在本仓库源码目录运行 PowerShell：

powershell
node --version
npm install --global pnpm@12.15.0
pnpm install --frozen-lockfile
pnpm build
Get-Command codex -ErrorAction SilentlyContinue
Get-Command dsh -ErrorAction SilentlyContinue

安装发现不代表 ACP 或模型就绪。使用 PATH 中的原生命令或本地配置的 providers.codex.executable / providers.dsh.executable 选择安装。桌面软件存在本身不保证可用的 ACP 命令入口；Dock 不改写原生配置与登录。

从服务管理员取得本设备独立的 device-pairing.json。以 $Pairing 指向这份新文件；下面仅重置该配对文件的 ACL 并授予当前用户访问，不应对原生 Harness 目录或其他文件执行：

powershell
$Pairing = Read-Host "设备配对 JSON 的绝对路径"
$DockSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
icacls $Pairing /reset
if ($LASTEXITCODE -ne 0) { throw "pairing_acl_reset_failed" }
icacls $Pairing /inheritance:r /grant:r "*${DockSid}:(F)"
if ($LASTEXITCODE -ne 0) { throw "pairing_acl_failed" }
$DeviceHome = Join-Path $env:LOCALAPPDATA "HarnessDock/.local/device"
$WorkDir = Join-Path $env:USERPROFILE "harness-work"
New-Item -ItemType Directory -Force -Path $WorkDir | Out-Null
node apps/daemon/dist/cli.js init --home $DeviceHome --cwd $WorkDir --pairing $Pairing
$DeviceConfig = Join-Path $DeviceHome "config.json"
node apps/daemon/dist/cli.js start $DeviceConfig
node apps/daemon/dist/cli.js status $DeviceConfig
node apps/daemon/dist/cli.js doctor $DeviceConfig --json

远端必须使用可验证的 WSS/TLS；设备身份沿用现有配对流程。新建 Dock 私有目录使用 NTFS ACL，配置和状态需属于当前用户，只允许当前用户、SYSTEM 与管理员访问；权限检查失败会拒绝启动。使用本机 NTFS 私有目录，不放在共享盘、FAT/exFAT 或同步目录。Windows PowerShell 及其标准安全 API 必须可用，受管设备禁止这些能力时会明确失败。

powershell
node apps/daemon/dist/cli.js logs $DeviceConfig
node apps/daemon/dist/cli.js stop $DeviceConfig
# 重新登录后手动启动：
node apps/daemon/dist/cli.js start $DeviceConfig

管理使用每次启动独立的命名管道，设置本地拥有者和 SYSTEM 的 ACL、拒绝网络登录，并校验设备 token 和 daemon 身份；不按保存 PID 发信号。当前 Windows 候选不提供 --autostart，该选项在写入安装状态前拒绝。doctor 的 Windows 平台项显示 unknown，直到完成目标平台验收。

如需固定入口，在目标 Windows 构建同平台运行目录，先停止当前后台，再安装：

powershell
pnpm bundle .local/bundles/windows-candidate
node apps/daemon/dist/cli.js stop $DeviceConfig
node apps/daemon/dist/cli.js install $DeviceConfig --bundle .local/bundles/windows-candidate/daemon
$Launcher = Join-Path $DeviceHome "installation/launch.cjs"
node $Launcher start
node $Launcher status

存在活动或 unknown 执行会阻止维护。后续使用固定入口的 upgrade --bundle 与 rollback；不能跨平台复制 node_modules。bundle 仅生成本地候选运行目录，package:local 与 App 构建不提供 Windows 归档。

调用方继续使用连接 SDK 或执行 CLI，按获授权 nodeId 选择这台 Windows，以 --provider codex 或 --provider dsh 分别运行纯文本回显，再验证原生工具和审批。具体业务软件、插件、skills 和工具由该机器上的 Harness 管理；Dock 不添加软件专用控制层。见Windows 验收边界。

当前 GPUI 客户端#

App v0.1.3 使用 GPUI Kit，面向 macOS 15+、Apple 芯片。安装与日常操作见App 使用指南；源码构建见构建与分发。Windows 界面尚未发布。

源码候选：安装中断与旧锁

当前候选用由操作系统持有的本地锁保护连接及安装；进程退出后由系统释放，不凭 PID 或锁文件时间猜测。首次安装的私有意图记录绑定原配置、设备身份、运行时与候选包摘要；异常后只有同一身份与同一包才能继续，不接管来源不明的已有目录。

connection_lock_legacy 或 installation_lock_legacy 表示旧版文件锁。当前候选提供显式恢复：先为桌面当前选中的原绑定创建对应 scope 的检查点，正常重启电脑，状态确认 canRecover 后，再用原 checkpointId 归档锁；会同时核对原锁身份和系统启动身份，锁变化时拒绝恢复。重开 App、仅重启 helper 或按时间猜测都不能替代这些证据。

# 执行设备，使用原入口及桌面当前选中绑定的配置。
# 安装锁将 connection 换为 installation；不跨界接管独立 CLI。
node daemon/dist/cli.js prepare-legacy-lock-recovery /private/device/config.json --scope connection
# 保存 checkpointId，正常重启电脑后再明确归档原锁：
node daemon/dist/cli.js recover-legacy-lock /private/device/config.json --scope connection --recovery-id <检查点UUID>

候选状态的 legacyLocks 分别报告 scope、supported、checkpointId、requiresRestart 与 canRecover。恢复只归档核验过的旧锁，不删除原文件或配置，不重领邀请，不重派任务；原来的安装或连接另行显式继续。installation_identity_conflict 应使用原配置与原候选包继续；installation_recovery_unavailable 表示无法确认原安装，保留目录并排查，不覆盖重装。独立 CLI 的目录与锁不由桌面绑定恢复接管。

管理员：旧后台不支持恢复时迁移到候选#

先在原应用按原 runId 查询，支持时只读 reconcile，收存可确认的结果；确认没有活动执行或等待审批，再保留原配置、设备身份、数据库、输出及安装记录。使用经核验、匹配平台的候选 Daemon 包和 Node.js 22.19+，不要在原封存版本目录安装依赖或覆盖文件。以下路径均为占位示例，替换成同一设备的原配置与原安装根目录：

DOCK_CANDIDATE=/absolute/candidate/daemon
DOCK_CONFIG=/private/device/config.json
DOCK_INSTALL=/private/device/installation

# 先读回原拥有者状态；原应用核对完成、无活动轮次后才继续。
node "$DOCK_CANDIDATE/dist/cli.js" status "$DOCK_CONFIG"
# 使用原配置经受保护 socket 请求旧拥有者正常停止，不按保存 PID 发信号。
node "$DOCK_CANDIDATE/dist/cli.js" stop "$DOCK_CONFIG"
node "$DOCK_CANDIDATE/dist/cli.js" status "$DOCK_CONFIG"

必须确认旧拥有者已经停止，再在终端 A 直接前台运行候选。不要用 start：现有安装的 start 会沿 installation 记录选择旧版本，不能证明新恢复能力已启用。正常停止后台也不证明原任务已取消；原结果继续保持 unknown。

# 终端 A，保持运行；沿用原 config 和 state，不重新初始化或领取邀请。
node "$DOCK_CANDIDATE/dist/cli.js" run "$DOCK_CONFIG"

在终端 B 设置同一组路径变量，确认 status 返回候选后台的 admissionRecovery，再创建检查点，保存 checkpointId。按 requiresRestart 提示正常重启电脑；旧记录没有原启动身份时，必须在检查点之后重启。

# 终端 B，路径变量与终端 A 相同。
node "$DOCK_CANDIDATE/dist/cli.js" status "$DOCK_CONFIG"
node "$DOCK_CANDIDATE/dist/cli.js" prepare-admission-recovery "$DOCK_CONFIG"
# 保存 admissionRecovery.checkpointId；requiresRestart=true 时正常重启电脑。

重启后先在相关终端重新设置上述路径变量。原来的登录自启可能再次启动旧版本。先查询实际拥有者；若旧版本正在运行，仍通过原配置的受保护 stop 正常停止并确认，再在终端 A 前台 run 候选。不要并行启动第二个拥有者，也不要假设登录后已经运行新版。终端 B 确认 canResume 后，用保存的检查点显式恢复新准入：

node "$DOCK_CANDIDATE/dist/cli.js" resume-admission "$DOCK_CONFIG" --recovery-id <检查点UUID>
node "$DOCK_CANDIDATE/dist/cli.js" status "$DOCK_CONFIG"
# 仍使用新候选 CLI 完成原安装根目录的版本切换；不要用旧 launcher upgrade。
node "$DOCK_CANDIDATE/dist/cli.js" upgrade "$DOCK_CONFIG" \
  --bundle "$DOCK_CANDIDATE" --install-dir "$DOCK_INSTALL"
# 切换成功后，才从原固定入口核对已安装和实际运行版本。
node "$DOCK_INSTALL/launch.cjs" status "$DOCK_CONFIG"

恢复只解除经过系统启动身份核验的旧执行对新准入的封锁；旧 unknown、runId、原生恢复上下文与输出保留，不重派、释放或报告取消。旧 CLI 的离线 unknown 检查不认识新恢复标记，因此升级这一步必须由新候选 CLI 执行。升级或状态未确认时保留原目录并诊断，不重复迁移。原生账号、登录、工具授权和进程链限制仍独立，不因迁移而获得新权限。此路径尚需在实际旧安装上分别验收，不能用未配置设备或源码构建成功作为迁移通过证明。

Windows daemon 源码#

Windows 11 x64 使用原生 Node.js 22.19+ 和 pnpm 12.15.0。当前提供 CLI 后台和 GPUI 桌面源码候选；登录自启与正式发行归档尚未提供。在仓库目录运行：

pnpm install --frozen-lockfile
pnpm check:windows

检查覆盖 NTFS 私有目录与文件、命名管道鉴权、CMD 启动器、后台启动/停止/重启、托管安装/升级/回滚和 SDK 连通性；不使用原生账号、不调用模型。真实执行已另行验收，见验证页的 Windows 源码记录；后续版本仍需分别验收，不能用连通性结果代替。

从管理员取得设备 pairing 文件后，将它放入仅当前用户和 SYSTEM 可访问的 NTFS 目录。不要放在公共下载或共享目录，也不要将内容贴入日志或支持报告。Dock 创建的设备 home 会自动设置私有 ACL；已有目录或 pairing 文件权限过宽会拒绝启动，不会静默修改。使用 PowerShell：

$deviceHome = Join-Path $env:LOCALAPPDATA 'HarnessDock\device'
# 工作目录必须已存在；pairing 文件须已移入私有目录。
pnpm daemon init --home $deviceHome --cwd (Get-Location).Path --pairing 'C:\private-transfer\device-pairing.json'
$config = Join-Path $deviceHome 'config.json'
pnpm daemon start $config
pnpm daemon status $config
pnpm daemon doctor $config --json
pnpm daemon logs $config
pnpm daemon stop $config

home 首次创建后保留身份，日常使用 start/status/stop，不要重复 init。退出终端不会停止后台；登录后需手动 start。先在 Windows 安装并登录所选 Codex/dsh，Dock 复用其安装与配置。远程 Server 必须使用已验证 TLS。doctor 的 Windows 支持状态仍为实验候选；实际模型执行可按验证页单独运行 pnpm accept:codex / pnpm accept:dsh，会使用模型额度。

Windows 桌面源码候选#

Windows 11 x64 已有 GPUI 原生窗口候选，提供邀请链接输入、服务器配对文件选择、连接复核、状态与后台控制。应用与后台独立，关闭窗口或退出界面不停止 daemon。新窗口默认显示接入服务器；永久 token 留在受保护的本机配置。

构建需要 Node.js 24.9+、固定版本 pnpm、Rust stable、MSVC C++ Build Tools 与 Windows SDK：

pnpm install --frozen-lockfile
pnpm check:windows
pnpm panel:windows:build --node-license 'C:\path-to-node\LICENSE' --output .local/windows-panel
Start-Process .local/windows-panel/HarnessDock.exe

输出包含 HarnessDock.exe、resources 下的 Node/daemon、离线连接帮助和依赖许可。保持整个目录一起移动；运行需要 Microsoft Visual C++ x64 运行库。--debug 生成本地调试候选，使用已缓存的必要 Node 依赖。首次连接仍需服务器管理员提供设备邀请或 pairing 文件；此构建不自动配对或提交模型任务。

本地候选没有代码签名或安装器；登录自启、URL 协议注册与单实例激活尚未实现。托盘与辅助技术兼容性需在目标环境继续检查，不由编译结果推断正式发行支持。

界舟 · Harness Dock · 原生 Harness 接入与执行管理更新于 2026-11-11
本地全文搜索↑ ↓ 选择 ↵ 打开