AI-Harness桌面应用方案

nononoa_zoro 2026-10-29 14:02:57

AI-Harness 桌面应用方案

1. 目标与范围

将AI-Harness做成面向 Windows ARM64、免安装、开箱即用 的桌面应用。

桌面应用是网关的托管外壳，不重新实现网关功能：

启动、监控、重启、停止网关进程，并在窗口中显示网关自带的 Control UI。
首次运行时通过向导生成配置。
提供若干常用配置页（Provider、Agent、Orchestrator、本地模型），省去手改 openclaw.json。
随包携带便携 Node 与全部插件，目标机无需另装 Node 或 npm。

2. 总体架构

AI-Harness.exe                      Electron 35（内嵌 Node + Chromium）= 桌面外壳
resources\
  app.asar（或 app\）               外壳代码：dist/**、assets/**、package.json
  runtime\node.exe                  便携 Node 22（官方 win-arm64 构建），只用来跑网关
  harness\                          AI-Harness npm 包 + 生产依赖 + 全部插件

┌──────────────── Electron 主进程（内嵌 Node）────────────────┐
│ 单实例锁 · 托盘 · 菜单 · 窗口 · GatewayManager · 配置读写   │
│        │ spawn / taskkill                  ▲ IPC（仅 file: 页）│
│        ▼                                   │                  │
│  runtime\node.exe harness\openclaw.mjs     │  渲染进程         │
│  gateway run --port <p>   ◄── HTTP ──►     │  assets/*.html    │
│  （网关 + 插件，独立进程）                  │  http://127.0.0.1 │
└────────────────────────────────────────────┴──────────────────┘

3. 网关托管（`src/main/gateway.ts`）

启动：node openclaw.mjs gateway run --allow-unconfigured --port <p>，端口默认 18789，被占用时寻找空闲端口。
接管（adopt）：启动前先探测 18789 的 /healthz；若已有网关在运行则直接接管，此时不持有子进程，因此拒绝重启，状态里显示"非本应用启动"。
健康检查：用 /healthz（进程存活）判定可显示界面；不用 /readyz，因为后者要等所有 sidecar 就绪，冷启动 25–55 秒甚至更久。只要子进程仍存活就持续等待，不设固定超时。
崩溃恢复：意外退出后最多自动重启 3 次，之后进入 crashed 状态并显示加载页。
停止：taskkill /pid <pid> /T /F 杀整个进程树，避免遗留 node / geniex 孤儿进程。
日志：网关输出写入 %APPDATA%\ai-harness-desktop\logs\gateway.log；外壳诊断写入 desktop.log（5 MB 滚动）。

4. 配置

路径解析顺序：OPENCLAW_CONFIG_PATH → OPENCLAW_STATE_DIR → ~/.openclaw/openclaw.json。
启动时 checkConfig() 分三种结果：
- 可用（至少有一个 provider）→ 启动网关；
- 缺失或无 provider → 显示首次运行向导；
- 无法解析为 JSON → 显示提示页，不覆盖用户文件，由用户手工修复。

首次运行向导（`setup-window.ts` / `onboarding.ts`）

支持一次添加多个 provider，每个 provider 可有多个 model，且只能有一个 primary。
校验：provider id 正则、contextWindow ≥ 16000、id/model 不重复。
实际写入通过 openclaw onboard --non-interactive --auth-choice custom-api-key 完成（API key 经环境变量传入，不出现在命令行）；onboard 会改写 gateway.*，因此把原有 token / port / bind / tailscale 传回去，遇到 remote / password / SecretRef token 则拒绝，避免破坏。
之后合并其余 provider 与 model，并种入必需的 dt-* agent（见 §5）。
向导里可检测并安装 GenieX（本地推理）。
菜单 Config → Add Provider… 复用同一表单（append 模式），完成后恢复先前页面。

5. 设置页

菜单项	作用	要点
Add Provider…	追加 provider/model	同向导；追加时需选择 primary
Agent Settings…	编辑 `agents.list`	可改 id、systemPromptOverride、model、skills、tools（profile/allow/deny）；`dt-*` 只读；删除 agent 时同步清理 `agentDescriptions`，删除 Orchestrator 默认 agent 须先指定替代；保留未知字段
Orchestrator Settings…	配置 dragon-task-orchestrator	同时写 `plugins.entries.<id>.enabled` 与 `config.enabled`；各字段按 schema 范围校验；`agentDescriptions` 编辑器；高级限制；allow-list / 默认 agent 告警
Local Model Settings…	配置 GenieX 本地模型	单个开关同时控制 `geniex` 与 `geniex-manager`，显式写 `true/false`（因 GenieX 在 Windows ARM64 且 PATH 有 geniex 时会自动启用，不能靠"不写"表示关闭）；列出 `agents.defaults.models` 中所有 `geniex/…`；可编辑 compute、contextSize、gpuLayers 与投机解码参数（spec* 仅在设置 draft model 时保留）

6. 菜单与托盘

File：Exit（真正退出）。
Config：Open Config File | Add Provider… / Agent Settings… / Orchestrator Settings… / Local Model Settings…
Gateway：Restart Gateway | Gateway Status…（状态、地址、是否为本应用启动、PID、运行时长、配置与日志路径）
Help：Open Logs Folder、Open Config Folder | About AI-Harness（外壳版本、网关版本、Electron / Chromium / Node 版本、架构）
替换了 Electron 默认菜单，避免暴露刷新与开发者工具。
关闭窗口 = 隐藏到托盘；配置不完整时关闭窗口 = 退出。托盘菜单可显示窗口、打开日志、退出。
退出时先停止网关再退出（before-quit）。

7. 安全设计

每个设置窗口使用独立 preload，contextIsolation: true、nodeIntegration: false、sandbox: true。
IPC 处理函数校验 senderFrame.url 必须是对应的本地 file: 页面。
加载网关 Control UI 的页面不暴露 window.harness 桥。
外部 http(s) 链接一律交给系统浏览器，窗口内不打开。
配置写入保留未知字段；API key 只经环境变量传递。

8. 打包与分发

构建入口

pnpm dist  =  pnpm build  &&  pnpm prepare-stage  &&  electron-builder --win --arm64

tsc 把 src/ 编译到 dist/（入口 dist/main/index.js）。
scripts/stage.mjs（pnpm prepare-stage）生成 stage/：
- 下载并校验（SHA-256）官方 Node 22 win-arm64，复制 node.exe 到 stage/runtime；
- npm pack 仓库根目录（遵循根 package.json 的 files），解包为 stage/harness；
- 用便携 Node 执行 npm install --omit=dev --legacy-peer-deps，并显式安装对等依赖 @napi-rs/canvas。
electron-builder 按 electron-builder.yml 打包：files 含 dist/**、assets/**、package.json；extraResources 把 stage/ 复制到 resources/。

产物

只生成免安装 zip：release\AI-Harness-<version>-win-arm64.zip，另有未压缩目录 release\win-arm64-unpacked。
用户完整解压后运行 AI-Harness.exe。

注意事项

必须在 Windows ARM64 机器上构建，原生依赖才会解析到 win32-arm64 二进制。仓库根目录需先执行 pnpm build && pnpm ui:build。
pnpm v11 使用 allowBuilds，pnpm 10 使用 onlyBuiltDependencies，二者都写在 apps/desktop/pnpm-workspace.yaml。
未签名，首次运行可能触发 SmartScreen；对 zip 先"解除锁定"可避免。

...全文