fix: resolve bundled KataGo runtime paths

Author: haoc

.gitignore

@@ -4,6 +4,8 @@ dist
 website/.astro
 release
 .release
+.dev-release
+.dev-cache
 .DS_Store
 *.log
 .goagent

docs/RELEASE_NOTES_v0.4.14.md

@@ -0,0 +1,154 @@
+# GoAgent v0.4.14
+
+GoAgent v0.4.14 is a Windows KataGo startup hotfix. It fixes a packaged-resource path bug where Windows portable builds could try to launch KataGo from `resources/app.asar/data/katago/...`, which cannot contain a runnable executable. GoAgent now resolves bundled KataGo from `resources/data/katago` or `resources/app.asar.unpacked/data/katago`, and never tries to spawn a binary from inside `app.asar`.
+
+QQ 群：1030632742，欢迎一起交流、提建议、完善 GoAgent。
+
+## v0.4 系列延续能力
+
+This release keeps the broader v0.4 foundation: grounded shape recognition engine, local pattern matcher, knowledge source-policy gates, optimized move-range review, quality checks and eval gates, Real Eval / engine silver fixture gate, KataGo engine pool telemetry, Release artifact smoke, student level, student age, teacher persona style settings with evidence boundary, teacher sessions, selective PR #6 integration, Tool-first Agent runtime, Kokoro selected-provider TTS with offline synthesis, Windows OpenCL runtime bundle, KataGo OpenCL adjacent runtime files, GPU vendor OpenCL drivers, and the community contribution path from layiku and wimi321.
+
+## 中文
+
+### 下载前先选版本
+
+| 平台 / 场景 | 推荐下载 |
+| --- | --- |
+| macOS Apple Silicon（M 系列） | GoAgent-0.4.14-mac-arm64.dmg |
+| macOS Intel | GoAgent-0.4.14-mac-x64.dmg |
+| Windows x64 安装版，普通用户推荐 | GoAgent-0.4.14-win-x64.exe |
+| Windows x64 免安装版 | GoAgent-0.4.14-win-x64-portable.zip |
+| Windows x64 NVIDIA 专版安装版 | GoAgent-0.4.14-win-x64-nvidia.exe |
+| Windows x64 NVIDIA 专版免安装包 | GoAgent-0.4.14-win-x64-nvidia-portable.7z.001 and all following split parts |
+| 校验文件 | SHA256SUMS.txt |
+
+### 本版重点
+
+- 修复 Windows 免安装包 / 安装包中 KataGo 路径误指向 `app.asar` 的问题。
+- GoAgent 会优先从 `resources/data/katago` 和 `resources/app.asar.unpacked/data/katago` 查找内置 KataGo。
+- 明确禁止从 `app.asar` 内部启动 KataGo，避免 `spawn ... ENOENT`。
+- 默认仍使用本机 KataGo 分析；智子云远程算力只有用户在设置里显式启用才会使用。
+- 设置页文案继续面向普通用户，减少开发者式说明。
+
+## 繁體中文
+
+### 下載前先選版本
+
+| 平台 / 使用情境 | 建議下載 |
+| --- | --- |
+| macOS Apple Silicon | GoAgent-0.4.14-mac-arm64.dmg |
+| macOS Intel | GoAgent-0.4.14-mac-x64.dmg |
+| Windows x64 安裝版 | GoAgent-0.4.14-win-x64.exe |
+| Windows x64 免安裝版 | GoAgent-0.4.14-win-x64-portable.zip |
+| Windows x64 NVIDIA 專版 | GoAgent-0.4.14-win-x64-nvidia.exe |
+| Windows x64 NVIDIA 免安裝包 | GoAgent-0.4.14-win-x64-nvidia-portable.7z.001 and all following split parts |
+| 校驗檔 | SHA256SUMS.txt |
+
+### 本版重點
+
+- 修復 Windows 套件中 KataGo 路徑誤指向 `app.asar` 的問題。
+- 內建 KataGo 會從 `resources/data/katago` 或 `resources/app.asar.unpacked/data/katago` 啟動。
+- GoAgent 不會從 `app.asar` 內部執行 KataGo。
+- 預設仍使用本機 KataGo；智子雲只有手動啟用時才會使用。
+
+## English
+
+### Pick the right package before downloading
+
+| Platform / use case | Recommended download |
+| --- | --- |
+| macOS Apple Silicon | GoAgent-0.4.14-mac-arm64.dmg |
+| macOS Intel | GoAgent-0.4.14-mac-x64.dmg |
+| Windows x64 installer | GoAgent-0.4.14-win-x64.exe |
+| Windows x64 portable ZIP | GoAgent-0.4.14-win-x64-portable.zip |
+| Windows x64 NVIDIA installer | GoAgent-0.4.14-win-x64-nvidia.exe |
+| Windows x64 NVIDIA portable package | GoAgent-0.4.14-win-x64-nvidia-portable.7z.001 and all following split parts |
+| Checksums | SHA256SUMS.txt |
+
+### Highlights
+
+- Fixes Windows packaged KataGo resolution when the app is installed or extracted as a portable ZIP.
+- GoAgent now resolves bundled KataGo from `resources/data/katago` or `resources/app.asar.unpacked/data/katago`.
+- GoAgent never tries to spawn KataGo from inside `app.asar`, preventing `spawn ... ENOENT`.
+- Local KataGo remains the default analysis engine; Zhizi Cloud is used only when the user explicitly enables it.
+- Settings copy remains user-facing and avoids developer-oriented configuration wording.
+
+## 日本語
+
+### ダウンロード前に選ぶもの
+
+| 環境 | 推奨ファイル |
+| --- | --- |
+| macOS Apple Silicon | GoAgent-0.4.14-mac-arm64.dmg |
+| macOS Intel | GoAgent-0.4.14-mac-x64.dmg |
+| Windows x64 インストーラー | GoAgent-0.4.14-win-x64.exe |
+| Windows x64 ポータブル ZIP | GoAgent-0.4.14-win-x64-portable.zip |
+| Windows x64 NVIDIA 版 | GoAgent-0.4.14-win-x64-nvidia.exe |
+| Windows x64 NVIDIA ポータブル | GoAgent-0.4.14-win-x64-nvidia-portable.7z.001 and all following split parts |
+| チェックサム | SHA256SUMS.txt |
+
+### 主な変更
+
+- Windows パッケージで KataGo のパスが `app.asar` 内を指す問題を修正しました。
+- KataGo は `resources/data/katago` または `resources/app.asar.unpacked/data/katago` から起動します。
+- 既定ではローカル KataGo を使います。Zhizi Cloud はユーザーが明示的に有効化した場合のみ使われます。
+
+## 한국어
+
+### 다운로드 전 선택
+
+| 환경 | 권장 다운로드 |
+| --- | --- |
+| macOS Apple Silicon | GoAgent-0.4.14-mac-arm64.dmg |
+| macOS Intel | GoAgent-0.4.14-mac-x64.dmg |
+| Windows x64 설치 프로그램 | GoAgent-0.4.14-win-x64.exe |
+| Windows x64 포터블 ZIP | GoAgent-0.4.14-win-x64-portable.zip |
+| Windows x64 NVIDIA 설치 프로그램 | GoAgent-0.4.14-win-x64-nvidia.exe |
+| Windows x64 NVIDIA 포터블 | GoAgent-0.4.14-win-x64-nvidia-portable.7z.001 and all following split parts |
+| 체크섬 | SHA256SUMS.txt |
+
+### 이번 버전
+
+- Windows 패키지에서 KataGo 경로가 `app.asar` 내부를 가리키는 문제를 수정했습니다.
+- KataGo는 `resources/data/katago` 또는 `resources/app.asar.unpacked/data/katago`에서 실행됩니다.
+- 기본값은 로컬 KataGo이며, Zhizi Cloud는 사용자가 직접 켠 경우에만 사용됩니다.
+
+## ภาษาไทย
+
+### เลือกไฟล์ก่อนดาวน์โหลด
+
+| แพลตฟอร์ม | ไฟล์ที่แนะนำ |
+| --- | --- |
+| macOS Apple Silicon | GoAgent-0.4.14-mac-arm64.dmg |
+| macOS Intel | GoAgent-0.4.14-mac-x64.dmg |
+| Windows x64 installer | GoAgent-0.4.14-win-x64.exe |
+| Windows x64 portable ZIP | GoAgent-0.4.14-win-x64-portable.zip |
+| Windows x64 NVIDIA installer | GoAgent-0.4.14-win-x64-nvidia.exe |
+| Windows x64 NVIDIA portable | GoAgent-0.4.14-win-x64-nvidia-portable.7z.001 and all following split parts |
+| Checksums | SHA256SUMS.txt |
+
+### จุดสำคัญของรุ่นนี้
+
+- แก้ปัญหา Windows package ชี้ path ของ KataGo เข้าไปใน `app.asar`
+- GoAgent จะเรียก KataGo จาก `resources/data/katago` หรือ `resources/app.asar.unpacked/data/katago`
+- ค่าเริ่มต้นยังใช้ KataGo ในเครื่อง; Zhizi Cloud จะใช้เมื่อผู้ใช้เปิดเองเท่านั้น
+
+## Tiếng Việt
+
+### Chọn gói tải xuống
+
+| Nền tảng | Gói khuyến nghị |
+| --- | --- |
+| macOS Apple Silicon | GoAgent-0.4.14-mac-arm64.dmg |
+| macOS Intel | GoAgent-0.4.14-mac-x64.dmg |
+| Windows x64 installer | GoAgent-0.4.14-win-x64.exe |
+| Windows x64 portable ZIP | GoAgent-0.4.14-win-x64-portable.zip |
+| Windows x64 NVIDIA installer | GoAgent-0.4.14-win-x64-nvidia.exe |
+| Windows x64 NVIDIA portable | GoAgent-0.4.14-win-x64-nvidia-portable.7z.001 and all following split parts |
+| Checksums | SHA256SUMS.txt |
+
+### Điểm mới
+
+- Sửa lỗi gói Windows trỏ đường dẫn KataGo vào bên trong `app.asar`.
+- GoAgent chạy KataGo từ `resources/data/katago` hoặc `resources/app.asar.unpacked/data/katago`.
+- Mặc định vẫn dùng KataGo cục bộ; Zhizi Cloud chỉ chạy khi người dùng bật rõ ràng.

docs/ZHIZI_CLOUD_ENGINE.md

@@ -19,17 +19,21 @@ GoAgent -> 智子云登录 -> Socket.IO 远程 KataGo -> GTP kata-analyze
 在 GoAgent 设置页打开“分析引擎”：
 
 1. 引擎模式选择 `智子云远程算力：直连`。
-2. 填写智子云账号和密码，点击“登录并连接智子云”。
+2. 算力类型默认选择 `VIP 共享引擎`，GoAgent 会提交 `--gpu-type vip-share`。这是智子管理员确认的 VIP 包月引擎，不会额外按时间扣独享费用。
+   - `独享 1x / 3x / 6x` 对应 `--gpu-type 1x / 3x / 6x`，属于按算力和时间计费的独享 worker。
+   - 如果你只是购买了 VIP，请不要选择独享档位。
+3. 填写智子云主账号手机号或邮箱和密码，点击“登录并连接智子云”。
    - GoAgent 会调用智子云登录接口获取 token。
    - 登录成功后，GoAgent 会把 token 保存到本地加密存储。
    - 登录成功后，引擎模式会自动切到 `智子云远程算力：直连`。
    - 后续只需要启动 GoAgent，不需要先启动其它应用。
-3. 如果密码登录提示密码不正确，可以点击“发送验证码”，收到短信后用“验证码登录”。
+   - `zz-` 开头的是智子连接账号，不是主账号登录 token。它需要先在智子官方账号体系里绑定，不能直接填在 GoAgent 的登录框里换取远程算力 token。
+4. 如果密码登录提示密码不正确，可以点击“发送验证码”，收到短信后用“验证码登录”。
    - 这和智子 Web 端的 `send-code` / `fast-login` 流程一致。
    - 验证码只用于本次登录；GoAgent 不会长期保存验证码。
-4. Token 通常不需要手动填写。只有你已经从其它方式拿到了 token，才使用“高级：Token”。
-5. `zz-ikatago 路径` 是兼容旧连接器的高级选项，普通用户可以不填。
-6. 附加参数一般留空；只有你明确知道智子云 Socket.IO 连接参数时再填写。
+5. Token 通常不需要手动填写。只有你已经从其它方式拿到了 token，才使用“高级：Token”。
+6. `zz-ikatago 路径` 是兼容旧连接器的高级选项，普通用户可以不填。
+7. 附加参数一般留空；只有你明确知道智子云 Socket.IO 连接参数时再填写。算力类型优先用设置页下拉框选择，避免把 VIP 共享误写成独享计费参数。
 
 `自动` 模式现在是本机优先的默认模式，不会因为本机分析失败就自动上传局面到智子云。需要远程算力时，请手动启用 `智子云远程算力：直连`。
 
@@ -65,9 +69,12 @@ GoAgent 不会把智子 token 写入普通设置文件，也不会在日志中
 
 - `智子云未配置完整`：还没有在 GoAgent 中登录智子云，请输入账号密码或短信验证码登录。
 - `智子云未登录`：当前选择了 `智子云远程算力：直连`，但本地没有可用 token。请在设置页用账号密码或短信验证码登录；普通用户不需要填写 `zz-ikatago` 路径。
+- `这是智子云连接账号，不是可直接登录的主账号`：请改用智子云主账号手机号或邮箱登录。`zz-` 连接账号不能直接换取 GoAgent 远程算力 token。
 - `密码不正确`：智子官方密码接口拒绝了这组密码。可以改用“发送验证码”再“验证码登录”。
 - `验证码不正确或已过期`：重新发送验证码后再登录。
-- `智子云余额不足或当前没有可用算力`：先确认智子云套餐或余额已经生效；如果刚充值，点击 `退出智子云登录` 后重新登录，让 GoAgent 刷新 token 和远程会话。
+- `智子云远程 worker 返回额度不足或不可分配`：如果你是 VIP 用户，请先确认算力类型选择的是 `VIP 共享引擎（--gpu-type vip-share）`。如果选择 `1x / 3x / 6x`，智子云会按独享 worker 计费，并可能因为独享余额不足返回 `not_enough_credit`。如果刚充值或刚购买 VIP，点击 `退出智子云登录` 后重新登录，让 GoAgent 刷新 token 和远程会话。
+- 如果检测连接显示 `主账号 token 有效`、`会员有效`、`连接账号已绑定`，但远端仍返回 `not_enough_credit`，说明 GoAgent 已完成官方公开流程：`fetch-socketio-token` 成功、Socket.IO 收到 `ready`，但智子 worker 在执行 GTP 初始化时拒绝分配算力。此时请把这段状态反馈给智子官方，让官方检查连接账号的远程 worker/GPU 权益是否已经实际生效。
+- 官方 Postman 中的 `connectAccount/login` 只用于验证连接账号凭据，不返回 GoAgent 直连所需的 token，也不会替代主账号登录流程。
 - `智子云 KataGo 启动超时`：检查 token 是否有效，或在 GoAgent 中重新登录。
 - `智子云 GTP 命令失败`：可能是远端引擎尚未 ready、账号状态异常，或智子云当前连接不可用。
 - 如果本机 KataGo 可用，且不是强制智子云模式，GoAgent 会在智子云失败后回退本机 KataGo。

package.json

@@ -1,6 +1,6 @@
 {
   "name": "goagent",
-  "version": "0.4.13",
+  "version": "0.4.14",
   "description": "Agentic AI teacher for Go / Weiqi / Baduk, powered by KataGo and multimodal LLMs.",
   "main": "out/main/index.js",
   "type": "module",
@@ -16,10 +16,11 @@
   },
   "packageManager": "pnpm@10.30.3",
   "scripts": {
-    "dev": "electron-vite dev",
+    "dev": "node scripts/start_dev_app.mjs",
+    "dev:vite": "electron-vite dev",
     "build": "electron-vite build",
     "typecheck": "tsc --noEmit -p tsconfig.node.json && tsc --noEmit -p tsconfig.web.json",
-    "preview": "electron-vite preview",
+    "preview": "node scripts/start_dev_app.mjs --skip-build",
     "lint": "pnpm typecheck",
     "test": "node --test tests/*.test.mjs",
     "check": "pnpm test && pnpm typecheck && pnpm build",

scripts/start_dev_app.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const root = resolve(new URL('..', import.meta.url).pathname)
+const args = new Set(process.argv.slice(2))
+const skipBuild = args.has('--skip-build')
+const devOutputDir = join(root, '.dev-release')
+const builderCacheDir = join(root, '.dev-cache', 'electron-builder')
+
+function run(command, commandArgs, options = {}) {
+  const result = spawnSync(command, commandArgs, {
+    cwd: root,
+    stdio: 'inherit',
+    env: process.env,
+    ...options
+  })
+  if (result.error) {
+    throw result.error
+  }
+  if (typeof result.status === 'number' && result.status !== 0) {
+    process.exit(result.status)
+  }
+}
+
+function findFirstApp(directory) {
+  if (!existsSync(directory)) {
+    return null
+  }
+  const entries = readdirSync(directory, { withFileTypes: true })
+  for (const entry of entries) {
+    const fullPath = join(directory, entry.name)
+    if (entry.isDirectory() && entry.name.endsWith('.app')) {
+      return fullPath
+    }
+    if (entry.isDirectory()) {
+      const nested = findFirstApp(fullPath)
+      if (nested) {
+        return nested
+      }
+    }
+  }
+  return null
+}
+
+if (process.platform === 'darwin') {
+  if (!skipBuild) {
+    run('pnpm', ['exec', 'electron-vite', 'build'])
+    run(
+      'pnpm',
+      [
+        'exec',
+        'electron-builder',
+        '--mac',
+        'dir',
+        '--publish',
+        'never',
+        '-c.directories.output=.dev-release',
+        '-c.mac.target=dir',
+        '-c.mac.notarize=false',
+        '-c.mac.identity=null'
+      ],
+      {
+        env: {
+          ...process.env,
+          ELECTRON_BUILDER_CACHE: builderCacheDir
+        }
+      }
+    )
+  }
+
+  const appPath = findFirstApp(devOutputDir)
+  if (!appPath) {
+    throw new Error('GoAgent dev app was not found. Run `pnpm dev` once before `pnpm preview`.')
+  }
+  run('open', ['-n', appPath])
+  console.log(`GoAgent dev app launched from ${appPath}`)
+} else {
+  run('pnpm', ['exec', 'electron-vite', skipBuild ? 'preview' : 'dev'])
+}