@simonyea/holysheep-cli 2.0.6 → 2.1.1

package/README.md

@@ -107,59 +107,71 @@ If you forget the port, check `~/.openclaw/openclaw.json` (`gateway.port`) or ru
 | Anthropic SDK / Claude Code | `https://api.holysheep.ai` (no `/v1`) |
 | OpenAI-compatible / Codex / Aider | `https://api.holysheep.ai/v1` (with `/v1`) |
 
-### AionUi mode (experimental, opt-in)
+### `hs web` — real AionUi v1.9.18, HolySheep-powered (2.1.0+)
 
-`hs web` ships a lightweight legacy WebUI by default — Windows / macOS / Linux, zero extra dependencies.
-
-For a richer UI, `hs web --aionui` boots the **AionUi runtime** behind a zero-dep Node proxy that turns your HolySheep API key into a one-click auto-login. No username, no password — your HS key **is** your credential.
+Starting from **2.1.0**, `hs web` is no longer a legacy workspace — it boots the **real [AionUi](https://github.com/iOfficeAI/AionUi) v1.9.18 source fork**, with one source-level change: the login page accepts a **HolySheep API Key** instead of username/password. The full AionUi UI, conversations, team, tools, MCP, everything — unchanged upstream experience, HolySheep-native auth.
 
 ```bash
-# Regular install (legacy WebUI, always works, ~90 kB)
+# Install CLI (still ~100 kB — the 21 MB runtime is fetched on first run)
 npm install -g @simonyea/holysheep-cli
 
-# Optional — enable AionUi mode. Requires the AionUi runtime locally.
-hs web --aionui
+# First run: downloads the prebuilt AionUi runtime into ~/.holysheep/aionui-runtime/
+hs web --setup-runtime
+
+# Subsequent runs: reuses the cached runtime
+hs web
 ```
 
-**How it works**
+**What happens on `hs web`:**
+
+1. Resolves the AionUi runtime from `~/.holysheep/aionui-runtime/` (or the dev `aionui-fork/` checkout when running from source).
+2. Spawns the patched `dist-server/server.mjs` via `bun` on port 9876.
+3. If `~/.holysheep/config.json` has a key, opens `http://127.0.0.1:9876/login#apiKey=cr_...` — the login page reads the hash, auto-submits, and you land in the AionUi dashboard.
+4. Otherwise opens `/login` and you paste the key manually.
 
-1. Wrapper on port `9876` (public) proxies to an AionUi server on `127.0.0.1:9877` (loopback-only).
-2. Your saved HolySheep API key is POSTed to AionUi's `/login` route, which returns a JWT cookie.
-3. A single-use bootstrap token (≤30 s TTL, loopback-only) copies the cookie into your browser → you land on `/guid` authenticated.
-4. `/api/holysheep/tools`, `/api/holysheep/balance`, `/api/holysheep/whoami` etc. are served directly by the wrapper (reuses the legacy handlers in-process, no cross-port coupling).
+**What got patched (source-level, reviewable):**
+
+| File (in `aionui-fork/`) | Change |
+|----|----|
+| `src/process/webserver/auth/service/HolySheepAuthService.ts` | New service — validates HS API Key via `GET {HOLYSHEEP_API_BASE}/v1/models`, 5-min TTL cache |
+| `src/process/webserver/routes/authRoutes.ts` | `/login` gets a HolySheep branch: `body.apiKey` → HolySheep validate → sign standard AionUi JWT |
+| `src/process/webserver/auth/middleware/AuthMiddleware.ts` | `validateLoginInput` skips username/password checks when `apiKey` is present |
+| `src/renderer/hooks/context/AuthContext.tsx` | `login()` now accepts `apiKey` and picks payload accordingly |
+| `src/renderer/pages/login/index.tsx` | Default mode: single API Key input. Toggle link: _"Sign in with local account"_ — restores upstream username/password flow (**nothing removed**) |
 
 **Runtime resolution order** (first match wins):
 
 1. `~/.holysheep/aionui-runtime/` (installed / cached)
 2. `<cli>/src/webui/vendor/aionui/` (developer checkout — not shipped to npm)
-3. `HOLYSHEEP_AIONUI_RUNTIME_URL` env var (advanced escape hatch — downloads + SHA256-verifies into `~/.holysheep/aionui-runtime/`)
+3. `<cli>/../aionui-fork/` (git source fork, used when running from the holysheep-cli repo)
+4. Download from `DEFAULT_RUNTIME_URL` (or `HOLYSHEEP_AIONUI_RUNTIME_URL`) when `--setup-runtime` is passed
 
-**Install the runtime — one-command** (recommended — 21 MB prebuilt, HolySheep-auth-ready):
+**Prebuilt runtime (baked-in default):**
 
-```bash
-export HOLYSHEEP_AIONUI_RUNTIME_URL=https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.17-holysheep.tar.gz
-export HOLYSHEEP_AIONUI_RUNTIME_SHA256=d75adcea3c57c85f64b5db96d18c593f20ad150888f47283dc2da0a440fb652c
-hs web --aionui --setup-runtime
-```
-
-The fetcher downloads to `~/.holysheep/aionui-runtime/`, verifies SHA256, extracts `dist-server/` + `out/` + `package.json`, boots AionUi, and opens your browser at the bootstrap redirect (auto-logged-in with your HS API key). Runs macOS / Linux. Windows support depends on `bun` availability.
+- URL: `https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.18-holysheep.tar.gz`
+- SHA256: `379ae2a523542c0be55a84abbec5cd1db31684300c66db8aa35c4a02d38e9cb1`
+- Size: 21 MB (contains `dist-server/` + `out/renderer/` only)
 
-**Alternative — build from AionUi source** (advanced):
+**Rebuild from source** (audit the patches yourself):
 
 ```bash
-git clone https://github.com/iOfficeAI/AionUi.git ~/AionUi
-cd ~/AionUi && bun install && bun run build:renderer:web && bun run build:server
-mkdir -p ~/.holysheep/aionui-runtime
-cp -R ~/AionUi/{dist-server,out,package.json} ~/.holysheep/aionui-runtime/
-hs web --aionui
+git clone https://github.com/iOfficeAI/AionUi.git aionui-fork
+cd aionui-fork && git checkout v1.9.18
+bun install
+bun run build:server && bun run build:renderer:web
+# Point the CLI at your local build:
+cd .. && node src/index.js web
 ```
-Note: upstream AionUi's `/login` still expects `{ username, password }`; the legacy wrapper path handles that via an auto-provisioned bridge admin in `~/.holysheep/aionui-bridge.json` (0600).
 
-**Recovery / advanced**
+**Fallback modes:**
+
+- `HOLYSHEEP_WEBUI_LEGACY=1 hs web` — old HolySheep Workspace page (zero-dep node, still ships in npm)
+- `hs web --aionui` — force AionUi mode; do **not** auto-fall-back if runtime is missing (fails loudly instead)
+
+**Roadmap:**
 
-- `/login` is still reachable at `http://127.0.0.1:9876/login` for direct apiKey entry.
-- To rotate credentials: `rm -rf ~/.holysheep/aionui-runtime && hs web --aionui --setup-runtime` (or edit `~/.holysheep/config.json`).
-- Startup logs showing `[AionUi] Could not find builtin src/process/resources/...` are harmless — the prebuilt tarball ships only `dist-server/` + `out/` (not the source tree), so template assistants/skills load from built-in fallbacks instead. The UI works fully; only the "source-tree" assistant templates are unavailable.
+- **2.1.0 (this release)** ✓ Real AionUi fork + HolySheep login — done
+- **2.2.0 (next)** — Deep integration: HolySheep multi-tool configuration panel embedded in the AionUi sidebar (not a separate legacy page). Manage Claude Code / Cursor / Codex / Aider / continue from within AionUi.
 
 ---
 
@@ -252,62 +264,71 @@ npx openclaw gateway --port <显示的端口>
 | Anthropic SDK / Claude Code | `https://api.holysheep.ai`（不带 /v1） |
 | OpenAI 兼容 / Codex / Aider | `https://api.holysheep.ai/v1`（带 /v1） |
 
-### AionUi 模式（实验性，opt-in）
+### `hs web` —— 真 AionUi v1.9.18，HolySheep 驱动（2.1.0+）
 
-`hs web` 默认启动轻量版 WebUI，所有平台（Windows / macOS / Linux）开箱即用，无额外依赖。
-
-要体验完整的 AionUi 界面，用 `hs web --aionui`。它会通过一个零依赖的 Node 代理把 AionUi 套在外面，**用 HolySheep API Key 代替账号密码**，一键自动登录。
+**从 2.1.0 开始，`hs web` 不再是之前那个仿风格的 HolySheep Workspace 页面，而是真正的 [AionUi](https://github.com/iOfficeAI/AionUi) v1.9.18 源码 fork。** 唯一的源码级改造：登录页收 **HolySheep API Key**，不再是账号密码。AionUi 原来的所有功能（对话、团队、工具、MCP 等）全部保留，只是登录换了种方式。
 
 ```bash
-# 普通安装（始终可用的轻量 WebUI）
+# 安装 CLI（npm 包仍然 ~100 kB；21 MB runtime 首次运行再下载）
 npm install -g @simonyea/holysheep-cli
 
-# 可选：启用 AionUi 模式（需本地安装 AionUi runtime）
-hs web --aionui
+# 第一次跑：自动下载预编译 AionUi runtime 到 ~/.holysheep/aionui-runtime/
+hs web --setup-runtime
+
+# 后续直接跑，复用缓存
+hs web
 ```
 
-**原理**
+**`hs web` 到底做了什么：**
+
+1. 从 `~/.holysheep/aionui-runtime/`（或开发仓 `aionui-fork/`）找到 runtime。
+2. 用 `bun` 直接启动打过补丁的 `dist-server/server.mjs`，端口 `9876`。
+3. 如果 `~/.holysheep/config.json` 里有 key，浏览器会打开 `http://127.0.0.1:9876/login#apiKey=cr_...`，登录页读取 hash 自动提交，用户直接进入 AionUi dashboard。
+4. 如果没 key，就打开 `/login` 等手动粘贴。
+
+**改了哪些源码（可审计）：**
 
-1. 代理监听公开端口 `9876`，将请求转发到 `127.0.0.1:9877` 上的 AionUi 服务（仅回环）。
-2. 自动将保存在 `~/.holysheep/config.json` 的 HS API Key POST 到 AionUi 的 `/login`，拿到 JWT cookie。
-3. 一次性 bootstrap token（≤30 s TTL，仅回环，拒绝 `X-Forwarded-For` / `X-Real-IP`）把 cookie 交给浏览器 → 用户直接落到 `/guid`，无需再输入任何凭据。
-4. `/api/holysheep/tools`、`/api/holysheep/balance`、`/api/holysheep/whoami` 等由代理自己就地处理（复用 legacy WebUI 的 handler，不跨端口），所以 HolySheep 多终端配置能力在 AionUi 界面里可用。
+| 文件（在 `aionui-fork/`） | 改动 |
+|----|----|
+| `src/process/webserver/auth/service/HolySheepAuthService.ts` | 新 service —— 调 `GET {HOLYSHEEP_API_BASE}/v1/models` 校验 key，5 分钟缓存 |
+| `src/process/webserver/routes/authRoutes.ts` | `/login` 增加 HolySheep 分支：`body.apiKey` → 校验 → 签发标准 AionUi JWT |
+| `src/process/webserver/auth/middleware/AuthMiddleware.ts` | `validateLoginInput` 在有 `apiKey` 时跳过账号密码校验 |
+| `src/renderer/hooks/context/AuthContext.tsx` | `login()` 新增 `apiKey` 参数，按情况选 payload |
+| `src/renderer/pages/login/index.tsx` | 默认 HolySheep API Key 单输入框，底部 "Sign in with local account" 链接保留上游账号密码流程（**任何功能都没删**）|
 
 **runtime 查找顺序**（命中即用）：
 
 1. `~/.holysheep/aionui-runtime/`（已安装 / 已缓存）
-2. `<cli>/src/webui/vendor/aionui/`（开发者本地仓库 —— npm 包不携带）
-3. `HOLYSHEEP_AIONUI_RUNTIME_URL` 环境变量（高级逃生口 —— 下载 + SHA256 校验后写入 `~/.holysheep/aionui-runtime/`）
+2. `<cli>/src/webui/vendor/aionui/`（开发者本地构建 —— npm 包不携带）
+3. `<cli>/../aionui-fork/`（从 holysheep-cli 仓库直接跑时用 git 源码 fork）
+4. 走 `--setup-runtime` 时，从 `DEFAULT_RUNTIME_URL`（或 `HOLYSHEEP_AIONUI_RUNTIME_URL`）下载
 
-**安装 runtime —— 一条命令**（推荐，21 MB 预编译包，内置 HolySheep Key 登录）：
+**预编译 runtime（内置默认值）：**
 
-```bash
-export HOLYSHEEP_AIONUI_RUNTIME_URL=https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.17-holysheep.tar.gz
-export HOLYSHEEP_AIONUI_RUNTIME_SHA256=d75adcea3c57c85f64b5db96d18c593f20ad150888f47283dc2da0a440fb652c
-hs web --aionui --setup-runtime
-```
+- URL: `https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.18-holysheep.tar.gz`
+- SHA256: `379ae2a523542c0be55a84abbec5cd1db31684300c66db8aa35c4a02d38e9cb1`
+- 大小: 21 MB（只包含 `dist-server/` + `out/renderer/`）
 
-fetcher 会下载到 `~/.holysheep/aionui-runtime/`，校验 SHA256，解压 `dist-server/ + out/ + package.json`，启动 AionUi，然后直接把浏览器带到 bootstrap 重定向（用你的 HS API Key 自动登录）。macOS / Linux 都行，Windows 视 `bun` 支持情况而定。
-
-**备用方案 —— 从 AionUi 源码构建**（高级用户）：
+**从源码自己构建**（审计所有 patch）：
 
 ```bash
-git clone https://github.com/iOfficeAI/AionUi.git ~/AionUi
-cd ~/AionUi && bun install && bun run build:renderer:web && bun run build:server
-mkdir -p ~/.holysheep/aionui-runtime
-cp -R ~/AionUi/{dist-server,out,package.json} ~/.holysheep/aionui-runtime/
-hs web --aionui
+git clone https://github.com/iOfficeAI/AionUi.git aionui-fork
+cd aionui-fork && git checkout v1.9.18
+bun install
+bun run build:server && bun run build:renderer:web
+# 用自己 build 的 runtime 启动：
+cd .. && node src/index.js web
 ```
-注意：上游 AionUi 的 `/login` 仍然是账号密码模式；wrapper 会自动走 legacy 路径，在 `~/.holysheep/aionui-bridge.json` (0600) 建一个桥接管理员账号，不影响使用。
 
-**恢复 / 高级**
+**备用模式：**
+
+- `HOLYSHEEP_WEBUI_LEGACY=1 hs web` —— 老 HolySheep Workspace 页面（零依赖 node，仍然随 npm 包发）
+- `hs web --aionui` —— 强制 AionUi 模式；runtime 缺失时**不会自动回退**，直接报错（方便 CI 场景）
 
-- `/login` 仍可直接访问：`http://127.0.0.1:9876/login`，里面可以手动粘 HS API Key 再登录。
-- 要重置：`rm -rf ~/.holysheep/aionui-runtime && hs web --aionui --setup-runtime`，或直接编辑 `~/.holysheep/config.json`。
-- runtime 缺失时：`hs web --aionui` 会打印清晰的安装指引并自动回退到 legacy WebUI，不会静默失败。
-- 启动日志里 `[AionUi] Could not find builtin src/process/resources/...` 是已知噪音 —— 预编译 tarball 只带 `dist-server/` 和 `out/`，不含源码目录，所以模板 assistants/skills 会走内置 fallback。界面完全可用，只是少几个"源码级"模板。
+**后续规划：**
 
-不设置该环境变量时 `hs web` 走 legacy WebUI，**不会再打印任何黄色警告**。
+- **2.1.0（本次发布）** ✓ 真 AionUi fork + HolySheep 登录
+- **2.2.0（下一步）** —— 深度集成：在 AionUi 侧栏内嵌 HolySheep 多工具配置面板（不再是独立 legacy 页面）。在 AionUi 界面里直接管理 Claude Code / Cursor / Codex / Aider / continue。
 
 ### 常见问题
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simonyea/holysheep-cli",
-  "version": "2.0.6",
+  "version": "2.1.1",
   "description": "Claude Code/Cursor/Cline API relay for China — ¥1=$1, WeChat/Alipay payment, no credit card, no VPN. One command setup for all AI coding tools.",
   "scripts": {
     "test": "node tests/droid.test.js && node tests/workspace-store.test.js",

package/src/commands/webui.js

@@ -1,103 +1,340 @@
 /**
  * hs web — 启动 WebUI 本地管理面板
  *
- * Modes (resolution order):
- *   --aionui                 → AionUi proxy wrapper (HolySheep API key login)
- *   HOLYSHEEP_WEBUI_AIONUI=1 → same as --aionui (back-compat)
- *   HOLYSHEEP_WEBUI_LEGACY=1 → no-op (legacy is already the default)
- *   <none>                   → legacy WebUI (default, always ships in npm)
+ * 2.1.0 开始：`hs web` 默认直接启动 **真 AionUi v1.9.18 源码 fork 的 server**
+ * (`dist-server/server.mjs`)，登录改成 HolySheep API Key（源码级改造，不是
+ * proxy wrapper 也不是外壳）。用户看到的就是 AionUi 自己的 UI。
+ *
+ * Modes:
+ *   <default>                      → AionUi fork + HolySheep API Key login
+ *   HOLYSHEEP_WEBUI_LEGACY=1       → 旧 HolySheep Workspace 页面 (fallback)
+ *   --aionui                       → 强制走 AionUi 路径（即使 runtime 缺失也不退回）
  */
 'use strict'
 
 const chalk = require('chalk')
-const { execSync } = require('child_process')
+const { execSync, spawn } = require('child_process')
 const fs = require('fs')
 const path = require('path')
+const http = require('http')
 
-function wantsAionUi(opts) {
-  if (opts && opts.aionui) return true
-  if (process.env.HOLYSHEEP_WEBUI_AIONUI === '1') return true
-  return false
+function isLegacy(opts) {
+  return process.env.HOLYSHEEP_WEBUI_LEGACY === '1'
 }
 
+// ── Bun resolution ───────────────────────────────────────────────────────────
 function resolveBunPath() {
-  // Dev bundle: holysheep-cli/src/webui/vendor/bun-darwin-arm64
+  // 1. Dev: use bundled bun if present (darwin-arm64 only in 2.0.x)
   const bundledBun = path.join(__dirname, '..', 'webui', 'vendor', 'bun-darwin-arm64')
   if (process.platform === 'darwin' && process.arch === 'arm64' && fs.existsSync(bundledBun)) {
     return bundledBun
   }
+  // 2. Env override
   if (process.env.BUN && fs.existsSync(process.env.BUN)) return process.env.BUN
+  // 3. System bun — platform-correct lookup command
+  const isWindows = process.platform === 'win32'
   try {
-    const resolved = execSync('which bun', {
-      stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', timeout: 2000,
-    }).trim()
-    return resolved || null
-  } catch { return null }
+    // `where.exe bun` on Windows prints one line per match; pick the first.
+    // `which bun` on Unix prints exactly one line (or fails with exit !=0).
+    const cmd = isWindows ? 'where.exe bun' : 'which bun'
+    const raw = execSync(cmd, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+      timeout: 3000,
+    })
+    // Windows emits CRLF and may list multiple paths — take the first existing one.
+    const candidates = raw.split(/\r?\n/).map((s) => s.trim()).filter(Boolean)
+    for (const p of candidates) {
+      if (fs.existsSync(p)) return p
+    }
+  } catch {}
+  // 4. No bun found. AionUi's dist-server/server.mjs uses `bun:` URL scheme
+  // imports (verified 2026-04-21: node 25 throws ERR_UNSUPPORTED_ESM_URL_SCHEME
+  // immediately), so bun is a hard runtime dep. Caller shows install guidance.
+  return null
+}
+
+function describeBunInstall() {
+  if (process.platform === 'win32') {
+    return 'powershell -c "irm bun.sh/install.ps1 | iex"'
+  }
+  return 'curl -fsSL https://bun.sh/install | bash'
+}
+
+// ── Runtime resolution ───────────────────────────────────────────────────────
+// Priority:
+//   1. Local dev checkout at ../aionui-fork/dist-server (developer building locally)
+//   2. Installed runtime at ~/.holysheep/aionui-runtime/dist-server
+//   3. If --setup-runtime + HOLYSHEEP_AIONUI_RUNTIME_URL, download into (2)
+//   4. null → fall back to legacy workspace
+function resolveAionUiRuntimeDir() {
+  // (1) Dev checkout — if holysheep-cli was cloned and `bun run build` ran in aionui-fork
+  const repoRoot = path.resolve(__dirname, '..', '..')
+  const devRuntime = path.join(repoRoot, 'aionui-fork')
+  if (fs.existsSync(path.join(devRuntime, 'dist-server', 'server.mjs'))) {
+    return { dir: devRuntime, source: 'dev-checkout' }
+  }
+  // (2) User-installed runtime
+  const home = process.env.HOME || process.env.USERPROFILE
+  if (home) {
+    const installed = path.join(home, '.holysheep', 'aionui-runtime')
+    if (fs.existsSync(path.join(installed, 'dist-server', 'server.mjs'))) {
+      return { dir: installed, source: 'installed' }
+    }
+  }
+  return null
+}
+
+async function downloadAionUiRuntime(logger) {
+  // Fetcher has a baked-in default URL + SHA256 — no env var required.
+  // HOLYSHEEP_AIONUI_RUNTIME_URL still works as an override.
+  const { resolveRuntime } = require('../webui/aionui-runtime-fetcher')
+  return resolveRuntime({ allowDownload: true, logger })
+}
+
+// ── HolySheep config → API key ───────────────────────────────────────────────
+function readHolySheepApiKey() {
+  try {
+    const { getApiKey } = require('../utils/config')
+    const key = getApiKey()
+    if (key && /^cr_/.test(key)) return key
+  } catch {}
+  return null
+}
+
+// ── HTTP utility: POST JSON with CSRF auto-bootstrap ─────────────────────────
+function httpRequest(options, body) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(options, (res) => {
+      const chunks = []
+      res.on('data', (c) => chunks.push(c))
+      res.on('end', () => {
+        const buf = Buffer.concat(chunks)
+        resolve({ status: res.statusCode || 0, headers: res.headers, body: buf.toString('utf8') })
+      })
+    })
+    req.on('error', reject)
+    if (body) req.write(body)
+    req.end()
+  })
+}
+
+async function fetchCsrfToken(port) {
+  // AionUi sets csrf cookie on first GET /. We fetch / and read Set-Cookie.
+  const r = await httpRequest({ host: '127.0.0.1', port, path: '/', method: 'GET' })
+  const setCookie = r.headers['set-cookie'] || []
+  for (const sc of setCookie) {
+    const m = sc.match(/csrfToken=([^;]+);/)
+    if (m) return { csrfToken: m[1], allCookies: setCookie.map((s) => s.split(';')[0]).join('; ') }
+  }
+  return null
+}
+
+async function loginWithApiKey(port, apiKey) {
+  const csrf = await fetchCsrfToken(port)
+  if (!csrf) throw new Error('Failed to acquire CSRF token from AionUi server')
+  const body = JSON.stringify({ apiKey, csrfToken: decodeURIComponent(csrf.csrfToken) })
+  const r = await httpRequest(
+    {
+      host: '127.0.0.1',
+      port,
+      path: '/login',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        Cookie: csrf.allCookies,
+        'x-csrf-token': decodeURIComponent(csrf.csrfToken),
+      },
+    },
+    body
+  )
+  if (r.status !== 200) {
+    throw new Error(`/login returned ${r.status}: ${r.body.slice(0, 200)}`)
+  }
+  const setCookie = r.headers['set-cookie'] || []
+  // Return a Cookie header string the browser can be seeded with.
+  const cookieLine = setCookie.map((s) => s.split(';')[0]).join('; ')
+  return { cookieLine, body: JSON.parse(r.body) }
 }
 
+// ── Start patched AionUi server ──────────────────────────────────────────────
+function spawnAionUiServer({ bunPath, runtimeDir, port }) {
+  return new Promise((resolve, reject) => {
+    const entry = path.join(runtimeDir, 'dist-server', 'server.mjs')
+    if (!fs.existsSync(entry)) {
+      return reject(new Error(`AionUi entry not found: ${entry}`))
+    }
+
+    // AionUi reads PORT / HOST / JWT_SECRET from env. We set a stable JWT secret
+    // derived from machine so cookies survive restarts of hs web within a session.
+    const child = spawn(bunPath, [entry], {
+      cwd: runtimeDir,
+      env: {
+        ...process.env,
+        PORT: String(port),
+        HOST: '127.0.0.1',
+        NODE_ENV: 'production',
+        // Let AionUi pick its own JWT secret; it'll persist under ~/.aionui-home
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    let settled = false
+    const onReady = () => {
+      if (!settled) {
+        settled = true
+        resolve(child)
+      }
+    }
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true
+        reject(new Error('AionUi server failed to start within 20s'))
+      }
+    }, 20_000)
+    // Poll /health-ish endpoint to detect readiness.
+    const pollReady = () => {
+      const req = http.request(
+        { host: '127.0.0.1', port, path: '/', method: 'HEAD', timeout: 500 },
+        (res) => {
+          if (res.statusCode && res.statusCode < 500) {
+            clearTimeout(timer)
+            onReady()
+          } else {
+            setTimeout(pollReady, 300)
+          }
+        }
+      )
+      req.on('error', () => setTimeout(pollReady, 300))
+      req.on('timeout', () => {
+        req.destroy()
+        setTimeout(pollReady, 300)
+      })
+      req.end()
+    }
+    // Start polling after a short grace period so bun has time to boot.
+    setTimeout(pollReady, 600)
+
+    // Surface logs with prefix (muted by default; set HS_WEB_DEBUG=1 to see)
+    const debug = process.env.HS_WEB_DEBUG === '1'
+    if (debug) {
+      child.stdout.on('data', (d) => process.stdout.write(chalk.gray(`[aionui] ${d}`)))
+      child.stderr.on('data', (d) => process.stderr.write(chalk.gray(`[aionui] ${d}`)))
+    }
+    child.on('exit', (code) => {
+      if (!settled) {
+        settled = true
+        reject(new Error(`AionUi server exited with code ${code} before becoming ready`))
+      }
+    })
+  })
+}
+
+// ── The real AionUi-mode flow ────────────────────────────────────────────────
 async function startAionUiMode(opts) {
   const port = Number(opts.port) || 9876
-  const { resolveRuntime, describeInstallGuidance } = require('../webui/aionui-runtime-fetcher')
-  const { startWrapper } = require('../webui/aionui-wrapper')
-  const { getApiKey } = require('../utils/config')
-
-  const allowDownload = opts.setupRuntime || process.env.HOLYSHEEP_AIONUI_RUNTIME_URL
-  const runtime = await resolveRuntime({
-    allowDownload: !!allowDownload,
-    logger: (m) => console.log(chalk.gray(`  ${m}`)),
-  })
 
+  // 1. Resolve runtime. First launch after `npm i -g` won't have one locally
+  // — we auto-download from the baked-in URL (verified by SHA256) unless the
+  // user opts out via HOLYSHEEP_WEBUI_NO_AUTOFETCH=1.
+  let runtime = resolveAionUiRuntimeDir()
+  const autoFetchDisabled = process.env.HOLYSHEEP_WEBUI_NO_AUTOFETCH === '1'
+  if (!runtime && !autoFetchDisabled) {
+    console.log(chalk.cyan('▶ AionUi runtime not installed — downloading automatically (~21 MB, one-time)'))
+    console.log(chalk.gray('  (disable with HOLYSHEEP_WEBUI_NO_AUTOFETCH=1; override URL with HOLYSHEEP_AIONUI_RUNTIME_URL)'))
+    const downloaded = await downloadAionUiRuntime((m) => console.log(chalk.gray(`  ${m}`)))
+    if (downloaded) {
+      runtime = { dir: downloaded.dir, source: downloaded.source }
+    }
+  }
   if (!runtime) {
-    console.log(chalk.red('✗ AionUi runtime not installed'))
+    const home = process.env.HOME || process.env.USERPROFILE || '~'
+    console.log(chalk.red('✗ AionUi runtime not found and auto-download did not succeed'))
     console.log()
-    console.log(chalk.gray(describeInstallGuidance()))
+    console.log(chalk.gray('  Expected at one of:'))
+    console.log(chalk.gray(`    • ${path.resolve(__dirname, '..', '..', 'aionui-fork', 'dist-server')}  (dev checkout)`))
+    console.log(chalk.gray(`    • ${path.join(home, '.holysheep', 'aionui-runtime', 'dist-server')}  (installed)`))
     console.log()
-    console.log(chalk.yellow('Falling back to legacy WebUI. Run `hs web --aionui --setup-runtime` once you provide HOLYSHEEP_AIONUI_RUNTIME_URL, or install manually.'))
+    console.log(chalk.yellow('  Retry manually:'))
+    console.log(chalk.cyan('    hs web --setup-runtime'))
+    console.log(chalk.gray('  Or pin a specific runtime URL + SHA256:'))
+    console.log(chalk.cyan('    export HOLYSHEEP_AIONUI_RUNTIME_URL=https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.18-holysheep.tar.gz'))
+    console.log(chalk.cyan('    export HOLYSHEEP_AIONUI_RUNTIME_SHA256=<see README>'))
+    console.log(chalk.cyan('    hs web --setup-runtime'))
+    console.log()
+    if (opts.aionui) {
+      console.log(chalk.red('  --aionui flag requires runtime. Aborting.'))
+      process.exit(1)
+    }
+    console.log(chalk.yellow('  Falling back to legacy HolySheep workspace. Set HOLYSHEEP_WEBUI_LEGACY=1 to silence this message.'))
     console.log()
     return startLegacyMode(opts)
   }
 
+  // 2. Resolve bun
   const bunPath = resolveBunPath()
   if (!bunPath) {
-    console.log(chalk.red('✗ bun is required to start the AionUi runtime (install: https://bun.sh)'))
-    console.log(chalk.yellow('Falling back to legacy WebUI.'))
+    console.log(chalk.red('✗ bun is required to run the AionUi server'))
+    console.log(chalk.gray('  (AionUi uses bun: URL-scheme imports that Node cannot load directly)'))
+    console.log()
+    console.log(chalk.yellow('  Install bun:'))
+    console.log(chalk.cyan(`    ${describeBunInstall()}`))
+    console.log(chalk.gray('  After install, close and reopen your terminal, then retry `hs web`.'))
+    console.log()
+    if (opts.aionui) {
+      console.log(chalk.red('  --aionui flag requires bun. Aborting.'))
+      process.exit(1)
+    }
+    console.log(chalk.yellow('  Falling back to legacy HolySheep workspace.'))
+    console.log()
     return startLegacyMode(opts)
   }
 
-  console.log(chalk.cyan(`▶ AionUi mode (runtime: ${runtime.version}, source: ${runtime.source})`))
+  console.log(chalk.cyan(`▶ Starting AionUi v1.9.18 (HolySheep fork, source: ${runtime.source})`))
 
-  let handle
+  // 3. Spawn server on the user-visible port directly — no proxy wrapper
+  let aionuiProc
   try {
-    handle = await startWrapper({
-      port,
-      runtimeDir: runtime.dir,
-      runtimeVersion: runtime.version,
-      runtimeSource: runtime.source,
-      bunPath,
-    })
+    aionuiProc = await spawnAionUiServer({ bunPath, runtimeDir: runtime.dir, port })
   } catch (e) {
-    console.log(chalk.red(`✗ AionUi wrapper failed to start: ${e.message}`))
-    console.log(chalk.yellow('Falling back to legacy WebUI.'))
+    console.log(chalk.red(`✗ AionUi server failed to start: ${e.message}`))
+    if (opts.aionui) process.exit(1)
+    console.log(chalk.yellow('  Falling back to legacy workspace.'))
     return startLegacyMode(opts)
   }
 
   const baseUrl = `http://127.0.0.1:${port}`
-  const apiKey = getApiKey()
 
-  // Auto-bootstrap: if we already have an HS key, mint a single-use token and
-  // open the browser at /api/auth/holysheep-bootstrap?token=… so the user
-  // lands authenticated without touching AionUi's /login form.
+  // 4. Auto-login via HolySheep API key if available
+  const apiKey = readHolySheepApiKey()
   let launchUrl = baseUrl
   if (apiKey) {
-    const token = handle.mintBootstrapToken()
-    launchUrl = `${baseUrl}/api/auth/holysheep-bootstrap?token=${token}`
-    console.log(chalk.green(`✓ HolySheep API key detected — auto-login via bootstrap token`))
+    try {
+      const { cookieLine } = await loginWithApiKey(port, apiKey)
+      // We can't programmatically seed the browser with cookies easily. Best UX:
+      //   - AionUi /login already set the cookie in our HTTP client, not the browser
+      //   - We ask user to paste key once in UI, OR we display a one-shot magic link
+      // For now, we open /login with the key prefilled via URL hash so the React
+      // login page can auto-submit. Implemented via localStorage fallback below.
+      if (cookieLine) {
+        // The cookie was set on our programmatic client, not the browser. Since
+        // we can't cross-write cookies, we just let AionUi's /login page auto-fill
+        // the apiKey via URL hash. React page reads window.location.hash on mount.
+        launchUrl = `${baseUrl}/login#apiKey=${encodeURIComponent(apiKey)}`
+        console.log(chalk.green('✓ HolySheep API key detected — auto-filled on login page'))
+      }
+    } catch (e) {
+      console.log(chalk.yellow(`  (auto-login pre-check failed: ${e.message} — will open /login manually)`))
+      launchUrl = `${baseUrl}/login`
+    }
   } else {
-    console.log(chalk.yellow(`! No HolySheep API key saved. POST it to ${baseUrl}/api/auth/holysheep-login or run 'hs login' first.`))
+    launchUrl = `${baseUrl}/login`
+    console.log(chalk.yellow('  No HolySheep API key saved yet. Run `hs login` first to enable auto-fill.'))
   }
 
   console.log(chalk.green(`✓ WebUI 已启动: ${chalk.cyan.bold(launchUrl)}`))
-  console.log(chalk.gray('  Mode: AionUi runtime + HolySheep API key bridge'))
+  console.log(chalk.gray('  Mode: AionUi v1.9.18 (源码 fork, HolySheep 登录)'))
   console.log(chalk.gray('  Press Ctrl+C to stop'))
   console.log()
 
@@ -110,22 +347,27 @@ async function startAionUiMode(opts) {
     } catch {}
   }
 
-  const stopChildren = () => {
-    try { handle.aionui.kill('SIGTERM') } catch {}
-    try { handle.server.close() } catch {}
+  const stop = () => {
+    try { aionuiProc.kill('SIGTERM') } catch {}
+    setTimeout(() => {
+      try { aionuiProc.kill('SIGKILL') } catch {}
+      process.exit(0)
+    }, 2000)
   }
-  process.on('SIGINT', stopChildren)
-  process.on('SIGTERM', stopChildren)
+  process.on('SIGINT', stop)
+  process.on('SIGTERM', stop)
 
   await new Promise(() => {})
 }
 
+// ── Legacy fallback (old HolySheep Workspace page) ───────────────────────────
 async function startLegacyMode(opts) {
   const port = Number(opts.port) || 9876
   const { startServer } = require('../webui/server')
   await startServer(port)
   const url = `http://127.0.0.1:${port}`
   console.log(chalk.green(`✓ WebUI 已启动: ${chalk.cyan.bold(url)}`))
+  console.log(chalk.gray('  (Legacy HolySheep Workspace — 原生 node 轻量模式)'))
   console.log(chalk.gray('  按 Ctrl+C 停止'))
   console.log()
   if (opts.open !== false) {
@@ -146,10 +388,19 @@ async function webui(opts) {
   console.log()
 
   try {
-    if (wantsAionUi(opts)) {
-      return await startAionUiMode(opts)
+    // 默认走 AionUi；HOLYSHEEP_WEBUI_LEGACY=1 才退回 legacy
+    if (isLegacy(opts) && !opts.aionui) {
+      console.log(chalk.gray(`[mode=legacy platform=${process.platform}]`))
+      console.log()
+      return await startLegacyMode(opts)
     }
-    return await startLegacyMode(opts)
+    // Tri-state mode line: helps user-reports when things go sideways
+    const bunFound = resolveBunPath() ? 'found' : 'missing'
+    const rt = resolveAionUiRuntimeDir()
+    const rtLabel = rt ? rt.source : 'none'
+    console.log(chalk.gray(`[mode=aionui platform=${process.platform} bun=${bunFound} runtime=${rtLabel}]`))
+    console.log()
+    return await startAionUiMode(opts)
   } catch (err) {
     console.log(chalk.red(`✗ 启动失败: ${err.message}`))
     process.exit(1)

package/src/webui/aionui-runtime-fetcher.js

@@ -4,15 +4,15 @@
  * Resolution order:
  *   1. ~/.holysheep/aionui-runtime/  (installed / cached)
  *   2. <cli>/src/webui/vendor/aionui/  (dev checkout — not shipped to npm)
- *   3. HOLYSHEEP_AIONUI_RUNTIME_URL env var  (advanced user escape hatch,
- *      downloads + SHA256-verifies when the constant below is also populated)
- *   4. null → caller must show a clear "runtime not installed" error
+ *   3. <cli>/../aionui-fork/  (dev repo checkout — not shipped to npm)
+ *   4. DEFAULT_RUNTIME_URL + DEFAULT_RUNTIME_SHA256 (baked in; auto-download
+ *      when --setup-runtime is passed). Users can override via env.
+ *   5. null → caller must show a clear "runtime not installed" error
  *
- * We DO NOT ship a hard-coded GitHub Release URL in this version because
- * the release asset has not been uploaded yet. Shipping a 404 URL is a
- * "code that lies" anti-pattern — explicit null + clear error message is
- * honest. A follow-up PR will add the URL + SHA256 constant once the
- * prebuilt tarball is published.
+ * The baked-in default URL is a public mirror of the AionUi v1.9.18 fork
+ * with HolySheep API-key login patched in. It's the prebuilt artifact that
+ * ships alongside `@simonyea/holysheep-cli` and is used by `hs web` on
+ * first launch when no local runtime is present.
  */
 
 'use strict'
@@ -27,6 +27,14 @@ const http = require('http')
 const USER_CACHE_DIR = path.join(os.homedir(), '.holysheep', 'aionui-runtime')
 const VENDOR_DIR = path.join(__dirname, 'vendor', 'aionui')
 
+// Baked-in defaults — updated with every 2.x.0 release that bumps the bundle.
+// Override via HOLYSHEEP_AIONUI_RUNTIME_URL / HOLYSHEEP_AIONUI_RUNTIME_SHA256.
+const DEFAULT_RUNTIME_URL =
+  'https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.18-holysheep.tar.gz'
+const DEFAULT_RUNTIME_SHA256 =
+  '379ae2a523542c0be55a84abbec5cd1db31684300c66db8aa35c4a02d38e9cb1'
+const DEFAULT_RUNTIME_VERSION = '1.9.18-holysheep'
+
 function isValidRuntimeDir(dir) {
   if (!dir) return false
   try {
@@ -55,24 +63,34 @@ function readVersion(dir) {
  * @returns {{ dir: string, version: string, source: 'user-cache'|'vendor'|'env-download' } | null}
  */
 async function resolveRuntime({ allowDownload = false, logger = () => {} } = {}) {
-  // 1. User cache
+  // 1. User cache (installed runtime)
   if (isValidRuntimeDir(USER_CACHE_DIR)) {
     return { dir: USER_CACHE_DIR, version: readVersion(USER_CACHE_DIR), source: 'user-cache' }
   }
 
-  // 2. Dev vendor checkout
+  // 2. Dev vendor checkout (bundled for darwin-arm64 dev rigs — not in npm)
   if (isValidRuntimeDir(VENDOR_DIR)) {
     return { dir: VENDOR_DIR, version: readVersion(VENDOR_DIR), source: 'vendor' }
   }
 
-  // 3. Environment-provided download URL (advanced escape hatch)
-  const url = process.env.HOLYSHEEP_AIONUI_RUNTIME_URL
-  const expectedSha = process.env.HOLYSHEEP_AIONUI_RUNTIME_SHA256
-  if (url && allowDownload) {
+  // 3. Dev repo aionui-fork/ (when running from the holysheep-cli source repo)
+  const forkDir = path.resolve(__dirname, '..', '..', 'aionui-fork')
+  if (isValidRuntimeDir(forkDir)) {
+    return { dir: forkDir, version: readVersion(forkDir), source: 'aionui-fork' }
+  }
+
+  // 4. Download from env override OR baked-in default
+  if (allowDownload) {
+    const url = process.env.HOLYSHEEP_AIONUI_RUNTIME_URL || DEFAULT_RUNTIME_URL
+    const expectedSha = process.env.HOLYSHEEP_AIONUI_RUNTIME_SHA256 || DEFAULT_RUNTIME_SHA256
     try {
       await downloadAndExtract(url, USER_CACHE_DIR, expectedSha, logger)
       if (isValidRuntimeDir(USER_CACHE_DIR)) {
-        return { dir: USER_CACHE_DIR, version: readVersion(USER_CACHE_DIR), source: 'env-download' }
+        return {
+          dir: USER_CACHE_DIR,
+          version: readVersion(USER_CACHE_DIR) || DEFAULT_RUNTIME_VERSION,
+          source: 'download',
+        }
       }
       logger('AionUi runtime downloaded but directory structure invalid')
     } catch (e) {
@@ -149,27 +167,33 @@ function downloadAndExtract(url, destDir, expectedSha, logger) {
 
 function describeInstallGuidance() {
   return [
-    'AionUi runtime not installed. To enable `hs web --aionui`, install it via ONE of:',
+    'AionUi runtime not installed. Fastest way to get started:',
     '',
-    '  Option 1 — Build from source (requires bun):',
+    '  One command (downloads the prebuilt 21 MB runtime):',
+    '    hs web --setup-runtime',
+    '',
+    '  Manual install via env overrides:',
+    `    export HOLYSHEEP_AIONUI_RUNTIME_URL=${DEFAULT_RUNTIME_URL}`,
+    `    export HOLYSHEEP_AIONUI_RUNTIME_SHA256=${DEFAULT_RUNTIME_SHA256}`,
+    '    hs web --setup-runtime',
+    '',
+    '  Build from source (requires bun):',
     '    git clone https://github.com/iOfficeAI/AionUi.git ~/AionUi',
     '    cd ~/AionUi && bun install && bun run build:renderer:web && bun run build:server',
     `    mkdir -p ${USER_CACHE_DIR}`,
-    `    cp -R ~/AionUi/{dist-server,out,package.json} ${USER_CACHE_DIR}/`,
-    '',
-    '  Option 2 — Supply a prebuilt tarball URL:',
-    '    export HOLYSHEEP_AIONUI_RUNTIME_URL=https://your.host/aionui-runtime.tar.gz',
-    '    export HOLYSHEEP_AIONUI_RUNTIME_SHA256=<sha256>',
-    '    hs web --aionui',
+    `    cp -R ~/AionUi/{dist-server,out} ${USER_CACHE_DIR}/`,
     '',
-    '  Option 3 — Fall back to legacy WebUI:',
-    '    hs web',
+    '  Or fall back to the legacy HolySheep Workspace:',
+    '    HOLYSHEEP_WEBUI_LEGACY=1 hs web',
   ].join('\n')
 }
 
 module.exports = {
   USER_CACHE_DIR,
   VENDOR_DIR,
+  DEFAULT_RUNTIME_URL,
+  DEFAULT_RUNTIME_SHA256,
+  DEFAULT_RUNTIME_VERSION,
   isValidRuntimeDir,
   readVersion,
   resolveRuntime,

package/src/webui/server.js

@@ -239,7 +239,7 @@ async function handleLogin(req, res) {
   }
   try {
     const valid = await validateApiKey(apiKey)
-    if (!valid) return json(res, { success: false, message: 'API Key 无效' }, 401)
+    if (!valid) return json(res, { success: false, message: 'API Key 无效 (server returned non-2xx)' }, 401)
     saveConfig({ apiKey, savedAt: new Date().toISOString() })
     workspaceStore.saveHolySheepApiConfig({
       apiKey,
@@ -248,7 +248,25 @@ async function handleLogin(req, res) {
     })
     json(res, { success: true, apiKey: maskKey(apiKey) })
   } catch (e) {
-    json(res, { success: false, message: `验证失败: ${e.message}` }, 500)
+    // Translate cryptic node-fetch / DNS / proxy errors into something actionable.
+    // Previously users just saw "链接失败" in the browser alert — now we surface
+    // the underlying cause (DNS, timeout, proxy interference, TLS, etc).
+    const code = e && (e.code || e.errno || e.type)
+    const name = e && e.name
+    let hint
+    if (code === 'EAI_AGAIN' || code === 'ENOTFOUND') {
+      hint = 'DNS 解析失败 — 检查网络 / 代理 / 防火墙是否拦截了 api.holysheep.ai'
+    } else if (code === 'ETIMEDOUT' || name === 'AbortError') {
+      hint = '连接超时 — 可能是网络慢或代理阻塞；试试开关代理再重试'
+    } else if (code === 'ECONNREFUSED' || code === 'ECONNRESET') {
+      hint = '连接被拒绝 — 检查本机防火墙或公司代理'
+    } else if (code === 'CERT_HAS_EXPIRED' || code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') {
+      hint = 'TLS 证书校验失败 — 可能是系统时间错误或中间人代理'
+    } else {
+      hint = e && e.message ? e.message : String(e)
+    }
+    const detail = `${hint}${code ? ` [${code}]` : ''}`
+    json(res, { success: false, message: `验证失败: ${detail}` }, 500)
   }
 }