feat: integrate official Zhizi Cloud API

docs/ZHIZI_CLOUD_ENGINE.md

@@ -1,90 +1,102 @@
-# 智子云远程算力
+# 智子云官方远程算力
 
-GoAgent 默认使用本机 KataGo 分析。智子云是手动启用的远程算力模式：只有你在设置里明确选择 `智子云远程算力：直连`，GoAgent 才会把当前局面发送到智子云。
-
-它和普通 iKataGo world 账号不是同一条登录路径：GoAgent 会调用智子云登录接口获取 token，再通过智子云 Socket.IO 通道启动远端 KataGo GTP，用 `kata-analyze` 读取候选点、胜率、目差和 PV。
+GoAgent 依据智子云公开的 OpenAPI 1.0、认证、引擎会话和支付规范接入远程 KataGo。**本机 KataGo 始终是默认引擎**。登录、购买 VIP 或充值后，GoAgent 都不会自动上传棋局；只有用户在“设置 → 智子云 → 算力”中确认启用，才会发送当前棋盘状态。
 
 ```text
-GoAgent -> 智子云登录 -> Socket.IO 远程 KataGo -> GTP kata-analyze
+登录智子云 → 查看账户和商品 → 可选购买/充值 → 检测远程算力 → 用户确认启用
 ```
 
-## 适合谁
+## 普通用户怎么用
+
+1. 打开“设置 → 智子云 → 账户与充值”。
+2. 使用手机号或邮箱进行密码登录；也可以发送验证码登录。验证码登录会在账号不存在时自动注册。
+3. 查看 VIP、余额、昨日消费和当前连接数。
+4. 如有需要，选择实时返回的 VIP 商品或充值金额，用微信扫描二维码。支付窗口每两秒更新一次状态，关闭窗口后立即停止查询。
+5. 打开“算力”，选择档位并点击检测。检测成功后，再确认启用智子云。
+6. 随时点击“回到本机分析”，立即停止远程任务并恢复本机 KataGo。
+
+账户或支付无法在 GoAgent 内处理时，可打开[智子官方 App 下载页](https://zhizigo.com/download)。
+
+## 算力选择
+
+GoAgent 只允许智子官方公开的参数，不接受任意命令行附加参数：
 
-- 本机 KataGo 速度慢，希望借用智子云算力的用户。
-- 不想额外安装或启动智子围棋电脑版，只希望在 GoAgent 里登录后直接使用远程算力的用户。
-- 想保持 GoAgent 老师讲解、棋谱库、知识库和胜率图流程不变，只把分析引擎换成远程算力的用户。
+| 项目 | 可选值 |
+| --- | --- |
+| GPU | `vip-share`、`1x`、`3x`、`6x`、`12x`、`24x` |
+| 引擎 | `katago-TENSORRT`、`katago-CUDA` |
+| 权重 | `18bnbt`、`fdx`、`28bnbt` |
 
-## 设置方式
+`platform=all` 和 `engine-type=go` 由程序固定设置。
 
-在 GoAgent 设置页打开“分析引擎”：
+- 有效 VIP 默认推荐 `vip-share`，使用 VIP 共享权益。
+- 非 VIP 默认推荐 `1x`，属于按量计费，启用前会显示余额并要求确认。
+- 更高独享档位必须由用户主动选择和确认，GoAgent 不会因为失败自动升级到更贵档位。
+- 通用 iKataGo 是独立的高级兼容能力，不是智子云的自动兜底。
 
-1. 算力类型默认选择 `VIP 共享引擎`，GoAgent 会提交 `--gpu-type vip-share`。这是智子管理员确认的 VIP 包月引擎，不会额外按时间扣独享费用。
-   - `独享 1x / 3x / 6x` 对应 `--gpu-type 1x / 3x / 6x`，属于按算力和时间计费的独享 worker。
-   - 如果你只是购买了 VIP，请不要选择独享档位。
-2. 填写智子云主账号手机号或邮箱和密码，点击“登录智子云”。
-   - GoAgent 会调用智子云登录接口获取 token。
-   - 登录成功后，GoAgent 会把 token 保存到本地加密存储。
-   - 登录本身不会中断当前本机分析，也不会立即上传局面。
-   - 后续只需要启动 GoAgent，不需要先启动其它应用。
-   - `zz-` 开头的是智子连接账号，不是主账号登录 token。它需要先在智子官方账号体系里绑定，不能直接填在 GoAgent 的登录框里换取远程算力 token。
-3. 点击“检测并启用”。GoAgent 会真实启动远程 KataGo，并等待候选点、胜率、目差和实时搜索速度返回。只有检测通过后才切换到智子云；检测失败时仍保持本机分析。
-4. 如果密码登录提示密码不正确，可以点击“发送验证码”，收到短信后用“验证码登录”。
-   - 这和智子 Web 端的 `send-code` / `fast-login` 流程一致。
-   - 验证码只用于本次登录；GoAgent 不会长期保存验证码。
-5. Token 通常不需要手动填写。只有你已经从其它方式拿到了 token，才使用“高级：Token”。
-6. `zz-ikatago 路径` 是兼容旧连接器的高级选项，普通用户可以不填。
-7. 附加参数一般留空；只有你明确知道智子云 Socket.IO 连接参数时再填写。算力类型优先用设置页下拉框选择，避免把 VIP 共享误写成独享计费参数。
+## 账户与支付
 
-`自动` 模式现在是本机优先的默认模式，不会因为本机分析失败就自动上传局面到智子云。需要远程算力时，请手动启用 `智子云远程算力：直连`。
+GoAgent 仅调用公开接口：
 
-## 连接与分析机制
+- 密码登录、验证码发送、验证码登录/注册、重置密码。
+- 账户资料、余额、使用记录和入账记录。
+- 实时会员商品目录。
+- 微信 Native Pay 订单创建和订单状态查询。
 
-- 检测通过后，GoAgent 会复用同一个远程 Socket.IO / GTP 会话，避免每次切换手数都重新排队启动 worker。
-- Socket 断线时会自动重连；局面同步或分析过程中断线，会重新建立会话并重新同步当前局面，旧结果不会覆盖新局面。
-- 分析按真实 `visits` 达到目标后停止，不再用固定等待时间猜测分析是否完成。
-- `stdout` / `stderr` 的字符串、Buffer、ArrayBuffer 和 Socket.IO Buffer JSON 都会按 UTF-8 解码。
-- VIP 共享会话空闲 5 分钟后释放；独享 1x / 3x / 6x 空闲 90 秒后释放，减少无效占用。
-- 切回本机分析或退出登录时，会立即停止任务并释放远程会话。
+VIP 商品名和价格每次从官方商品接口获取。VIP 订单严格使用接口返回的商品名和以分为单位的整数价格，不硬编码价格。余额充值支持 ¥10、¥30、¥50、¥100 和最多两位小数的自定义金额。
 
-## 退出和重新登录
+主进程将官方返回的 `codeURL` 原样编码成二维码图片；页面拿不到原始支付载荷。创建订单超时不会自动重试，以免生成重复订单。支付成功后会刷新账户、余额和推荐算力，但仍不会自动启用远程分析。
 
-如果刚购买套餐、充值或修改了智子云账号状态，但 GoAgent 仍提示额度不足或远程算力不可用，可以在设置页点击 `退出智子云登录`。GoAgent 会：
+## 远程分析协议
 
-1. 停止当前正在运行的 KataGo/智子云分析任务。
-2. 清除本地保存的智子云 token。
-3. 自动切回 `自动` 分析模式，并关闭“本机慢时自动使用智子云”，避免旧 token 或旧连接器路径继续重试。
+1. GoAgent 使用 Bearer Token 请求一次性的 Socket.IO 会话令牌。
+2. 使用官方返回的 URL、路径 `/socket.io.v4` 和查询参数 `zz-socketio-token` 建立连接。
+3. 只接受官方 `ready` 事件作为引擎就绪信号。
+4. 使用带数字 ID 的 GTP 命令逐条确认 `boardsize`、规则、贴目、清盘和完整手顺。
+5. 启动 `kata-analyze`，将候选点、胜率、目差、PV 和实时搜索速度转换成 GoAgent 的统一分析数据。
+6. 断线后废弃旧 Socket Token 和旧棋盘状态，获取新令牌、建立新连接并重放完整棋局。
 
-然后使用账号密码或短信验证码重新登录，再点击“检测并启用”。
+每个会话都有 generation。断线前迟到的输出不会写入新局面。用户取消、切回本机或退出登录时，会停止分析并释放远程会话。失败只进行有限重连，不会自动切换更贵的算力档位。
 
-## 和 iKataGo 的区别
+## 隐私与本地存储
 
-- iKataGo 路径使用 `ikatago -- analysis`，面向普通 iKataGo world / 自建远程服务。
-- 智子云路径优先使用 GoAgent 直连 Socket.IO；旧版 `zz-ikatago` 本地连接器仅作为兼容备选。
+- 默认 `auto` 模式只使用本机 KataGo。
+- 智子云密码和验证码只用于当前请求，不长期保存。
+- 登录 Token 保存在 GoAgent 的本地加密存储，不进入普通设置、renderer、日志或错误报告。
+- Socket Token 和支付原始响应只存在于主进程。
+- 只有用户明确启用智子云后，当前棋盘状态才会发送到智子云。
+- 退出登录会清除 Token、终止远程分析并切回本机 `auto` 模式。
 
-如果你把智子账号密码直接填到 iKataGo world，会出现用户配置 404 或无法登录，这是两套远程服务入口不同导致的。
+旧版本的 `zhiziClientBin`、`zhiziExtraArgs` 和“本机慢时自动切远程”设置会在迁移时清理，不再参与运行。
 
-## 隐私边界
+## 验证
 
-只有在以下情况，GoAgent 才会把局面发送到智子云：
+匿名契约检查不会登录或创建订单：
+
+```bash
+pnpm smoke:zhizi-public-api
+```
+
+真实远程 smoke 使用本机已经保存的登录状态，只读取账户/余额并执行一次 64 visits 分析，不创建支付订单：
+
+```bash
+GOAGENT_ZHIZI_REAL=1 pnpm smoke:zhizi-remote
+```
 
-- 引擎模式明确选择 `智子云远程算力：直连`。
-- 或者用户在高级选项中明确启用了“本机测速低于阈值时使用智子云”，并且本机测速低于阈值。
+真实支付验收只能由用户主动创建订单并扫码确认，自动化测试不得付款。
 
-默认安装、默认 `自动` 模式、以及旧版本升级后的首次启动，都会优先回到本机分析。
+## 故障处理
 
-GoAgent 不会把智子 token 写入普通设置文件，也不会在日志中打印 token。智子云密码只用于本次登录请求；登录成功后 GoAgent 保存 token，而不是长期保存密码。
+- **登录失效**：重新登录，旧 Token 会被替换。
+- **VIP 共享不可用**：确认 VIP 尚未过期，刷新账户后重试；持续失败时在智子官方 App 处理权益问题。
+- **余额不足**：独享档位按量计费，请充值或改用本机分析。
+- **暂无算力**：当前没有空闲资源，可以稍后重试；GoAgent 不会自动升级档位。
+- **网络中断**：GoAgent 会使用新会话令牌有限重连并重放棋局；失败后可重试或回到本机。
+- **支付状态不明**：不要重复点击创建订单，先保留当前二维码并刷新状态；关闭后再由用户决定是否创建新订单。
 
-## 故障排查
+官方依据：
 
-- `智子云未配置完整`：还没有在 GoAgent 中登录智子云，请输入账号密码或短信验证码登录。
-- `智子云未登录`：当前选择了 `智子云远程算力：直连`，但本地没有可用 token。请在设置页用账号密码或短信验证码登录；普通用户不需要填写 `zz-ikatago` 路径。
-- `这是智子云连接账号，不是可直接登录的主账号`：请改用智子云主账号手机号或邮箱登录。`zz-` 连接账号不能直接换取 GoAgent 远程算力 token。
-- `密码不正确`：智子官方密码接口拒绝了这组密码。可以改用“发送验证码”再“验证码登录”。
-- `验证码不正确或已过期`：重新发送验证码后再登录。
-- `当前没有空闲算力`：GoAgent 会按有限次数自动重试。这通常是 worker 暂时繁忙，不等于账号余额不足。
-- VIP 共享返回 `not_enough_credit`：GoAgent 会明确提示“VIP 权益/连接账号未同步”，不会把它误报成独享余额不足。先退出并重新登录；持续失败时请让智子官方检查 VIP 与连接账号的 worker 权益。
-- 独享 1x / 3x / 6x 返回 `not_enough_credit`：这是按量档位的余额或档位问题，请在智子官方 App 检查。设置页可直接打开 [智子官方 App 下载页](https://zhizigo.com/download)。
-- 官方 Postman 中的 `connectAccount/login` 只用于验证连接账号凭据，不返回 GoAgent 直连所需的 token，也不会替代主账号登录流程。
-- `智子云 KataGo 启动超时`：检查 token 是否有效，或在 GoAgent 中重新登录。
-- `智子云 GTP 命令失败`：可能是远端引擎尚未 ready、账号状态异常，或智子云当前连接不可用。
-- 如果本机 KataGo 可用，且不是强制智子云模式，GoAgent 会在智子云失败后回退本机 KataGo。
+- [OpenAPI 1.0](https://github.com/kinfkong/zhizi-open-api/blob/main/openapi/zhizi-public-api.yaml)
+- [认证规范](https://github.com/kinfkong/zhizi-open-api/blob/main/docs/zh-CN/guides/authentication.md)
+- [引擎会话规范](https://github.com/kinfkong/zhizi-open-api/blob/main/docs/zh-CN/guides/engine-sessions.md)
+- [支付规范](https://github.com/kinfkong/zhizi-open-api/blob/main/docs/zh-CN/guides/payments.md)

package.json

@@ -75,6 +75,7 @@
     "check:artifacts": "node scripts/package_artifact_smoke.mjs --mode=dev",
     "smoke:teacher-llm": "pnpm build && node scripts/teacher_llm_smoke.mjs",
     "smoke:teacher-llm:real": "pnpm build && node scripts/teacher_llm_real_smoke.mjs",
+    "smoke:zhizi-public-api": "node scripts/smoke_zhizi_public_api.mjs",
     "smoke:zhizi-remote": "node scripts/smoke_zhizi_remote.mjs",
     "rc:check": "node scripts/p0_release_candidate_check.mjs --mode=dev",
     "rc:artifacts": "node scripts/verify_release_artifacts.mjs --mode=dev",
@@ -84,13 +85,15 @@
     "electron-store": "^10.0.1",
     "kokoro-js": "^1.2.1",
     "openai": "^6.3.0",
+    "qrcode": "^1.5.4",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "socket.io-client": "^4.8.3",
     "zod": "^4.1.5"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
+    "@types/qrcode": "^1.5.6",
     "@types/react": "^19.1.13",
     "@types/react-dom": "^19.1.9",
     "@vitejs/plugin-react": "^5.0.2",
@@ -100,6 +103,7 @@
     "eslint": "^9.35.0",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.20",
+    "tsx": "^4.23.5",
     "typescript": "^5.9.2",
     "vite": "^7.1.5"
   },