ai-zero-token 1.0.9 → 1.0.10

package/docs/PRODUCT_UPDATE_DESKTOP_TOOLBOX.md

@@ -0,0 +1,429 @@
+# AI Zero Token 产品更新规划：桌面端与工具箱
+
+## 1. 更新目标
+
+本次产品更新的第一目标不是先做工具市场，也不是先重写全部前端，而是先把现有 `AI Zero Token` 从 CLI + 本地网页管理页升级为跨平台桌面端程序。
+
+桌面端完成后，再在桌面端内部增加工具箱模块。工具箱首先服务于本地网关能力，让用户更方便地使用已经生成的 OpenAI-compatible API 接口；之后再逐步加入其他内置工具和社区共建工具。
+
+## 2. 产品阶段
+
+### 2.1 第一阶段：现有网关桌面化
+
+目标是把当前已经可用的本地网关能力包装成桌面端应用。
+
+第一阶段不改变核心业务逻辑，重点是把现有能力变成一个用户可以直接打开、配置和使用的桌面程序。
+
+必须包含：
+
+- 桌面应用窗口
+- 启动和停止本地网关
+- 显示网关运行状态
+- 显示本地 API Base URL
+- 打开或内嵌当前管理页
+- OAuth 登录和账号管理
+- 模型列表和默认模型配置
+- 上游代理配置
+- 图像接口测试能力
+- 本地日志查看
+- 托盘常驻和退出控制
+
+这一阶段的原则：
+
+- 保留现有 `core`、`server`、`cli` 能力
+- 不重写网关核心逻辑
+- 不先做复杂工具市场
+- 不把社区 HTML 工具直接接入主应用
+- 先让普通用户可以不碰终端完成启动、登录、配置和调用
+
+### 2.2 第二阶段：桌面端 React 管理台
+
+当前管理页是服务端字符串 HTML，适合验证功能，但不适合长期维护桌面端和工具箱。
+
+第二阶段将管理界面迁移为 React/Vite 应用，但迁移范围只限 UI 层。
+
+需要完成：
+
+- 新建 `admin-ui`
+- 用 React 复刻当前管理页功能
+- 封装 `/_gateway/*` 管理接口客户端
+- 网关生产环境托管前端静态构建产物
+- 桌面端加载同一套管理台 UI
+- 移除或降级当前 `admin-page.ts` 的职责
+
+这一阶段结束后，项目形态应变为：
+
+```text
+core              核心业务能力
+server            本地 HTTP 网关
+cli               命令行入口
+desktop           桌面端入口
+admin-ui          React 管理台
+```
+
+### 2.3 第三阶段：网关工具箱
+
+工具箱的第一定位是服务当前网关，而不是做泛用插件平台。
+
+工具箱里的工具应该帮助用户更快地使用本地 API，例如：
+
+- API 调试器
+- Responses 请求构建器
+- Chat Completions 请求构建器
+- 图片生成工具
+- 图片编辑工具
+- Prompt 调试工具
+- 模型能力对比工具
+- 账号额度状态查看工具
+- 请求历史和复用工具
+- SDK 示例生成器
+- curl / JavaScript / Python 调用代码生成器
+
+这一阶段的工具优先做成官方内置工具，由项目直接维护，统一 UI、统一权限、统一调用链路。
+
+### 2.4 第四阶段：其他内置工具
+
+在网关工具箱稳定后，可以加入不完全依赖网关 API 的本地工具。
+
+候选方向：
+
+- Prompt 管理
+- 文本处理
+- JSON 格式化
+- 图片 base64 转换
+- Token 和上下文估算
+- 本地文件辅助处理
+- 常用 AI 工作流模板
+
+这些工具仍然应该围绕 AI 网关的使用场景展开，避免过早变成泛用工具集合。
+
+### 2.5 第五阶段：社区共建工具
+
+社区工具不作为第一阶段目标。
+
+当桌面端、React 管理台和官方工具箱稳定后，再允许用户通过 GitHub 提交工具。
+
+推荐机制：
+
+```text
+用户提交 GitHub PR 或工具仓库
+        ↓
+项目方审核代码和权限声明
+        ↓
+CI 打包工具包
+        ↓
+发布到工具 registry
+        ↓
+桌面端热更新工具列表
+        ↓
+高价值工具转为官方内置工具
+```
+
+社区工具不能直接获得本地 token、桌面端 IPC 或无限制网关调用权限。所有工具都必须通过受控工具运行时调用网关。
+
+## 3. 桌面端产品形态
+
+### 3.1 桌面端定位
+
+桌面端不是聊天软件的第一版，也不是完整 AI 工作站的第一版。
+
+第一版桌面端应该是本地 AI 网关控制台。
+
+核心价值：
+
+- 用户不用记命令
+- 用户不用手动打开终端
+- 用户可以直观看到网关是否运行
+- 用户可以复制 API Base URL 给其他 AI 工具
+- 用户可以在桌面端完成登录、切换账号、选择模型和测试接口
+
+### 3.2 首页信息架构
+
+桌面端首页建议包含：
+
+- 当前服务状态
+- 本地 API Base URL
+- 当前账号
+- 当前默认模型
+- 支持的接口
+- 最近请求状态
+- 快捷操作
+
+快捷操作：
+
+- 启动网关
+- 停止网关
+- OAuth 登录
+- 刷新模型
+- 复制 Base URL
+- 打开工具箱
+- 查看日志
+
+### 3.3 常驻能力
+
+桌面端需要支持托盘常驻。
+
+托盘菜单建议包含：
+
+- 打开主窗口
+- 启动网关
+- 停止网关
+- 复制 API Base URL
+- 查看日志
+- 退出应用
+
+### 3.4 默认监听策略
+
+桌面端第一版沿用现有网关默认监听策略：
+
+```text
+0.0.0.0:8787
+```
+
+这样可以保持 CLI、本地服务和桌面端行为一致，也不会破坏已有局域网调用习惯。
+
+桌面窗口中展示给本机用户复制的默认地址仍然使用：
+
+```text
+http://127.0.0.1:8787/v1
+```
+
+后续可增加“仅本机访问”和“允许局域网访问”开关，让用户在安全性和局域网访问之间显式选择。
+
+## 4. 技术路线
+
+### 4.1 第一阶段推荐实现
+
+第一阶段优先考虑最小改造成本。
+
+由于当前项目已经是 Node.js + Fastify + TypeScript，桌面端 MVP 使用 Electron：
+
+- Electron 主进程负责启动和停止本地网关
+- Electron 渲染进程第一版直接加载当前管理页
+- 当前 `core`、`server`、`cli` 基本保持不变
+- 打包时把网关代码和桌面壳一起发布
+
+这样能最快把现有工具变成桌面端，并保持当前 UI 效果不变。
+
+如果后续更重视安装包体积和系统资源占用，可以在桌面端稳定后评估 Tauri。但 Tauri 需要处理 Node sidecar、跨平台二进制和打包链路，第一阶段成本更高。
+
+### 4.2 第一阶段建议目录
+
+```text
+src/
+  core/
+  server/
+  cli/
+  desktop/
+    main.ts
+```
+
+如果第二阶段引入 React/Vite，可演进为：
+
+```text
+admin-ui/
+  src/
+  vite.config.ts
+src/
+  desktop/
+    main.ts
+    preload.ts
+```
+
+### 4.3 网关启动方式
+
+桌面端启动网关建议有两种模式：
+
+#### 内嵌模式
+
+桌面主进程直接调用现有 `startServer()`。
+
+优点：
+
+- 集成简单
+- 状态可控
+- 不需要额外进程管理
+
+缺点：
+
+- 主进程和网关同生命周期
+- 崩溃隔离较弱
+
+#### 子进程模式
+
+桌面主进程启动一个独立网关子进程。
+
+优点：
+
+- 网关和桌面壳隔离
+- 后续更容易做重启、日志采集和崩溃恢复
+
+缺点：
+
+- 打包和进程管理更复杂
+
+第一版使用内嵌模式，后续再切换为子进程模式。
+
+## 5. 工具箱产品定义
+
+### 5.1 工具箱第一目标
+
+工具箱首先是本地网关的使用加速器。
+
+它不是独立插件市场，也不是泛用工具平台。
+
+第一批工具必须围绕当前已支持的接口：
+
+- `GET /v1/models`
+- `POST /v1/responses`
+- `POST /v1/chat/completions`
+- `POST /v1/images/generations`
+- `POST /v1/images/edits`
+
+### 5.2 官方内置工具优先级
+
+第一批官方工具建议：
+
+1. API Playground
+2. 图片生成器
+3. 图片编辑器
+4. Prompt 调试器
+5. 请求历史
+6. SDK 示例生成器
+7. 模型和账号状态面板
+
+### 5.3 工具调用链路
+
+工具不应该直接绕过网关调用 provider。
+
+标准链路应为：
+
+```text
+工具 UI
+  ↓
+桌面端受控调用层
+  ↓
+本地网关 API
+  ↓
+core services
+  ↓
+provider
+```
+
+这样可以保证：
+
+- 账号管理统一
+- 模型选择统一
+- 代理配置统一
+- 日志统一
+- 请求历史统一
+- 权限控制统一
+
+## 6. 社区工具原则
+
+社区工具后置，不进入桌面端第一版。
+
+未来社区工具需要满足：
+
+- 有工具清单文件
+- 有固定版本
+- 有权限声明
+- 有构建产物校验
+- 不能访问本地 token
+- 不能直接访问桌面端高权限 API
+- 只能通过受控 bridge 调用允许的网关能力
+
+工具清单示例：
+
+```json
+{
+  "id": "prompt-polisher",
+  "name": "Prompt Polisher",
+  "version": "1.0.0",
+  "entry": "index.html",
+  "apiVersion": "1",
+  "permissions": {
+    "gateway": ["models:read", "responses:create"],
+    "storage": "tool-local",
+    "network": []
+  }
+}
+```
+
+社区工具成熟后，可以转为官方内置工具。
+
+## 7. 里程碑
+
+### M1：桌面端 MVP
+
+- 能启动桌面应用
+- 能启动和停止本地网关
+- 能显示服务状态
+- 能加载现有管理页
+- 能完成 OAuth 登录
+- 能复制 API Base URL
+- 能查看基础日志
+
+### M2：桌面端可用版
+
+- 托盘常驻
+- 启动时自动恢复网关状态
+- 端口冲突检测
+- 局域网访问开关
+- 网关异常提示
+- 打包 macOS、Windows、Linux
+
+### M3：React 管理台
+
+- React/Vite 管理台替换字符串 HTML
+- 管理接口客户端封装
+- 当前管理页功能完整迁移
+- 桌面端和浏览器端共用管理台
+
+### M4：官方工具箱
+
+- 工具箱入口
+- API Playground
+- 图片生成器
+- 图片编辑器
+- Prompt 调试器
+- 请求历史
+- SDK 示例生成器
+
+### M5：社区工具预览
+
+- 工具 manifest
+- 工具 registry
+- 工具包下载和校验
+- sandbox 运行时
+- 权限弹窗
+- GitHub 提交流程
+
+## 8. 非目标
+
+第一阶段不做：
+
+- 多用户系统
+- 云端账号体系
+- 在线插件市场
+- 社区 HTML 直接热执行
+- 完整聊天应用
+- 大规模 UI 重写
+- 多 provider 深度扩展
+
+这些能力可以后续做，但不应该阻塞桌面端 MVP。
+
+## 9. 当前结论
+
+产品更新顺序应调整为：
+
+```text
+1. 现有网关桌面化
+2. 桌面端稳定和打包发布
+3. React 管理台迁移
+4. 网关工具箱
+5. 其他官方内置工具
+6. 社区工具和热更新
+```
+
+这条路线能最大化复用当前已经完成的网关能力，同时为后续工具箱和社区扩展留下清晰边界。

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "ai-zero-token",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Local-first OpenAI-compatible AI CLI and gateway with Codex OAuth, multi-account management, and gpt-image-2 image generation/editing.",
   "license": "MIT",
+  "author": "AI Zero Token Contributors",
   "type": "module",
   "repository": {
     "type": "git",
@@ -40,8 +41,19 @@
     "ask": "bun src/cli.ts ask",
     "start": "bun src/cli.ts start",
     "serve": "bun src/cli.ts serve",
-    "build": "tsup",
-    "typecheck": "bunx tsc -p tsconfig.json --noEmit",
+    "dev": "node scripts/dev.mjs web",
+    "build": "npm run build:ui && npm run build:server",
+    "build:server": "tsup",
+    "build:ui": "vite build --config admin-ui/vite.config.ts",
+    "desktop": "npm run build && electron dist/desktop/main.js",
+    "desktop:dev": "node scripts/dev.mjs desktop",
+    "dist": "npm run build && electron-builder",
+    "dist:dir": "npm run build && electron-builder --dir",
+    "dist:mac": "npm run build && electron-builder --mac",
+    "dist:win": "npm run build && electron-builder --win",
+    "typecheck": "npm run typecheck:server && npm run typecheck:ui",
+    "typecheck:server": "bunx tsc -p tsconfig.json --noEmit",
+    "typecheck:ui": "tsc -p admin-ui/tsconfig.json --noEmit",
     "prepack": "npm run build",
     "pack:dry": "npm pack --dry-run"
   },
@@ -52,13 +64,67 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "electron": "^41.3.0",
+    "electron-builder": "^26.8.1",
+    "lucide-react": "^1.14.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vite": "^8.0.10"
+  },
+  "build": {
+    "appId": "com.aizerotoken.desktop",
+    "productName": "AI Zero Token",
+    "directories": {
+      "output": "release"
+    },
+    "files": [
+      "dist/**/*",
+      "admin-ui/dist/**/*",
+      "build/icon.*",
+      "package.json",
+      "README.md",
+      "README.zh-CN.md",
+      "LICENSE"
+    ],
+    "extraMetadata": {
+      "main": "dist/desktop/main.js"
+    },
+    "asar": true,
+    "mac": {
+      "icon": "build/icon.icns",
+      "category": "public.app-category.developer-tools",
+      "target": [
+        "dmg",
+        "zip"
+      ]
+    },
+    "win": {
+      "icon": "build/icon.ico",
+      "target": [
+        "nsis",
+        "zip"
+      ]
+    },
+    "nsis": {
+      "oneClick": false,
+      "allowToChangeInstallationDirectory": true
+    }
   },
   "files": [
     "dist",
+    "admin-ui/dist",
+    "build/icon.png",
+    "build/icon.icns",
+    "build/icon.ico",
     "CHANGELOG.md",
     "docs/API_USAGE.md",
+    "docs/DESKTOP_RELEASE.md",
+    "docs/PRODUCT_UPDATE_DESKTOP_TOOLBOX.md",
     "README.md",
     "README.zh-CN.md",
     "package.json"