claude360 0.1.0

package/README.md

@@ -0,0 +1,355 @@
+# Claude360 CLI
+
+面向 [Claude360](https://claude360.xyz) 已注册用户的跨平台命令行工具，让不熟悉终端配置的用户也能一行命令完成 Claude Code / Codex 的安装、授权、Key 选择、余额查询、微信扫码充值与日常启动。
+
+- 不要求用户在终端输入站点账号密码，授权全程在浏览器完成。
+- 不修改 shell profile / PowerShell profile / 全局环境变量。
+- 分组倍率、充值金额、API 凭证生命周期均以 NewAPI 后端为唯一来源，CLI 不内置任何业务口径。
+
+## 目录
+
+- [功能特性](#功能特性)
+- [系统要求](#系统要求)
+- [快速开始](#快速开始)
+- [首次配置流程](#首次配置流程)
+- [日常使用](#日常使用)
+- [本地配置](#本地配置)
+- [后端接口](#后端接口)
+- [Claude Code 与 Codex 集成](#claude-code-与-codex-集成)
+- [诊断与故障排查](#诊断与故障排查)
+- [开发与测试](#开发与测试)
+- [项目结构](#项目结构)
+- [安全模型](#安全模型)
+- [已知风险与路线图](#已知风险与路线图)
+- [许可证](#许可证)
+
+## 功能特性
+
+| 功能 | 说明 |
+| --- | --- |
+| 一行命令安装 | Windows PowerShell / macOS / Linux bash 一行命令拉起 bootstrap，自动检测 Node/npm 与全局 npm 权限 |
+| 浏览器设备授权 | 通过 `/api/cli/auth/*` 设备码流程换取受限 CLI 凭证，不接触账号密码 |
+| API Key 选择/创建 | 已有 Key 列表展示并选择；无 Key 时按后端分组倍率向导创建 |
+| 余额与分组展示 | 日常主菜单展示账户余额、当前 Key、当前分组与倍率（来自后端） |
+| 微信 Native 扫码充值 | 终端内渲染二维码；金额选项与最低充值额由后端返回，CLI 不内置 |
+| 启动 Claude Code | 自动注入 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`，以子进程启动 |
+| 启动 Codex | 写入隔离的 `[model_providers.claude360]` / `[profiles.claude360]` 配置，并以 `codex --profile claude360` 启动 |
+| 工具更新 | 菜单内更新 `claude360` 自身、Claude Code、Codex，全部需要二次确认 |
+| 诊断报告 | OS/Node/npm/全局 npm 权限/工具版本/连通性/授权状态/余额/Key/支付端点一站式检查 |
+
+## 系统要求
+
+- Node.js **18+** 与 npm（bootstrap 脚本仅检测，不自动安装系统运行时）。
+- 网络可达 `https://claude360.xyz`。
+- macOS / Linux：当前用户对其 `~/.claude360/` 拥有写权限。
+- Windows：当前用户对 `%USERPROFILE%\.claude360\` 拥有写权限。
+- 任何包管理或全局 npm 操作执行前都需要在 CLI 内显式确认。
+
+## 快速开始
+
+### macOS / Linux
+
+```bash
+curl -fsSL https://claude360.xyz/install.sh | bash
+```
+
+### Windows PowerShell
+
+```powershell
+irm https://claude360.xyz/install.ps1 | iex
+```
+
+Bootstrap 脚本职责：
+
+1. 识别 OS / 架构。
+2. 检查 Node.js 与 npm（缺失或 < 18 直接退出并给出修复建议）。
+3. 展示影响范围并要求确认。
+4. 执行 `npm install -g claude360@latest`。
+5. 执行 `claude360 setup` 进入首次配置向导。
+
+### 手动安装
+
+```bash
+npm install -g claude360@latest
+claude360
+```
+
+## 首次配置流程
+
+```
+┌───────────────────┐
+│ 启动 claude360    │
+└─────────┬─────────┘
+          ↓
+读取 ~/.claude360/config.json
+          ↓
+┌─ 无 cliToken ─┐   ┌─ 有 cliToken ─┐
+│ 设备码授权    │   │ 跳过授权步骤  │
+│ → 浏览器     │   └──────┬───────┘
+│ → 轮询批准   │          │
+└──────┬───────┘          │
+       ↓                   ↓
+读取或创建 API Key（按分组倍率向导）
+       ↓
+写入本地配置（mode 0600）
+       ↓
+进入主菜单
+```
+
+关键约束：
+
+- 授权码短期有效；CLI 仅在浏览器无法自动打开时把 `verification_url` 与 `user_code` 输出到终端。
+- 多个 Key 时展示：名称 / 脱敏 Key / 分组 / 状态 / 剩余额度（或无限额度）/ 过期时间。
+- 无 Key 时，CLI 通过 `/api/cli/groups` 拉取分组并按 `display_name（倍率 1.0x）` 风格展示，由用户选择后调用 `POST /api/cli/tokens` 创建。
+
+## 日常使用
+
+```
+Claude360
+1. 查看余额
+2. 微信扫码充值
+3. 启动 Claude Code
+4. 启动 Codex
+5. 安装或更新工具
+6. 切换 API Key / 分组
+7. 诊断
+8. 退出
+```
+
+- **查看余额**：调用 `GET /api/cli/me`，展示账号、余额、已用、当前 Key 名称与分组。
+- **微信扫码充值**：先取 `/api/cli/topup/options`，按后端校验通过的金额或最低额提交，再用 `qrcode-terminal` 在终端渲染 `code_url`，渲染失败时降级为纯文本 URL。轮询 `/api/cli/topup/:order_id`，支付完成自动刷新余额。
+- **启动 Claude Code**：调用 `claude` 子进程，并通过 `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` 注入。
+- **启动 Codex**：写入 `~/.codex/config.toml` 中 `[model_providers.claude360]` 与 `[profiles.claude360]`，发现既有冲突字段会先要求用户确认再覆盖，然后 `codex --profile claude360`，并通过 `CLAUDE360_API_KEY` 注入。
+- **安装或更新工具**：三选一菜单（仅 Claude Code / 仅 Codex / 两者），每步都需要确认。
+- **切换 API Key / 分组**：重新进入 Token 向导。
+- **诊断**：见下方“诊断与故障排查”。
+
+## 本地配置
+
+| 平台 | 路径 |
+| --- | --- |
+| macOS / Linux | `~/.claude360/config.json` (权限 `0600`) |
+| Windows | `%USERPROFILE%\.claude360\config.json` |
+
+示例：
+
+```json
+{
+  "baseUrl": "https://claude360.xyz",
+  "cliToken": "cli_xxx",
+  "apiKey": "sk-xxx",
+  "selectedTokenId": 456,
+  "tokenName": "daily-key",
+  "group": "default"
+}
+```
+
+注意事项：
+
+- 第一版接受**本地明文**保存 `cliToken` 与 `apiKey`，CLI 仅收紧文件权限，不接入系统密钥链。
+- CLI 日志与诊断输出会脱敏 API Key。
+- 若需要重置，删除 `~/.claude360/config.json` 即可触发完整重新授权。
+
+## 后端接口
+
+CLI 仅依赖一组隔离的 `/api/cli` 接口，由 `newapi/controller/cli.go` 提供：
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| POST | `/api/cli/auth/start` | 创建设备码授权会话 |
+| POST | `/api/cli/auth/confirm` | 浏览器端登录用户确认授权（站点 Web Session） |
+| POST | `/api/cli/auth/poll` | CLI 轮询授权结果，状态：`pending` / `approved` / `denied` / `expired` / `consumed` |
+| GET | `/api/cli/me` | 返回当前用户、分组、余额、已用额度、展示单位 |
+| GET | `/api/cli/tokens` | 当前用户 Key 列表（脱敏） |
+| POST | `/api/cli/tokens/:id/reveal` | 校验归属并返回明文 Key，被限频且禁用缓存 |
+| POST | `/api/cli/tokens` | 按分组创建新 Key（受 `operation_setting.GetMaxUserTokens()` 约束） |
+| GET | `/api/cli/groups` | 用户可用分组（含 `display_name`、`ratio`、`description`） |
+| GET | `/api/cli/topup/options` | 后端配置的充值金额选项与最低额，包含 WeChat 启用状态 |
+| POST | `/api/cli/topup/wechat` | 创建微信 Native 订单，返回 `code_url`、`order_id`、`pay_money` |
+| GET | `/api/cli/topup/:order_id` | 查询订单状态（仅订单所属用户） |
+
+实现要点：
+
+- 设备码、user_code、CLI 凭证均有过期机制；CLI 凭证可后台吊销。
+- 已批准会话被消费后保持 `consumed` 状态，CLI 凭证有独立有效期，设备码窗口过期不影响已发出的凭证。
+- Key reveal 强制鉴权 + 限频；后端日志不记录明文 Key。
+- 充值订单仅订单所属用户可查询。
+- 详细字段格式见 `prd/claude360-cli-prd.md` 第 7 章。
+
+## Claude Code 与 Codex 集成
+
+### Claude Code
+
+启动时注入：
+
+```bash
+ANTHROPIC_BASE_URL=https://claude360.xyz
+ANTHROPIC_AUTH_TOKEN=<selected_api_key>
+```
+
+依据 [Claude Code LLM gateway 官方文档](https://docs.anthropic.com/en/docs/claude-code/llm-gateway)，`ANTHROPIC_BASE_URL` 指向网关时，`ANTHROPIC_AUTH_TOKEN` 会作为 bearer token 发送到 `/v1/messages` 与 `/v1/messages/count_tokens`。
+
+### Codex
+
+写入 `~/.codex/config.toml`（仅修改 `model_providers.claude360` 与 `profiles.claude360` 两个表，不动其他 provider）：
+
+```toml
+[model_providers.claude360]
+name = "Claude360"
+base_url = "https://claude360.xyz/v1"
+env_key = "CLAUDE360_API_KEY"
+wire_api = "responses"
+
+[profiles.claude360]
+model_provider = "claude360"
+```
+
+启动命令：
+
+```bash
+codex --profile claude360
+```
+
+并通过子进程环境变量 `CLAUDE360_API_KEY=<selected_api_key>` 注入凭证。
+
+> **风险说明**：当前 Codex 自定义 provider 使用 Responses 协议（`wire_api = "responses"`）。Claude360 / NewAPI 必须支持 `/v1/responses` 或在网关层把 Responses 请求适配到现有模型能力，否则 Codex 调用会失败。详见 `prd/claude360-cli-verification.md` 中“Release Risks”。
+
+## 诊断与故障排查
+
+执行主菜单中“诊断”项，CLI 会汇报以下检查项：
+
+- 操作系统与架构。
+- 终端二维码渲染能力。
+- Node.js / npm 版本。
+- 全局 npm 安装权限。
+- Claude Code / Codex 是否安装及版本。
+- `https://claude360.xyz` API 连通性。
+- CLI 授权状态、账户余额、Key 列表拉取状态。
+- 微信支付端点可用性。
+
+常见异常及处理建议：
+
+| 现象 | 处理 |
+| --- | --- |
+| 浏览器未自动打开 | 复制终端打印的 `verification_url` 与 `user_code` 到任意浏览器 |
+| 授权超时 / 拒绝 / 过期 | 重新执行 `claude360`，会自动发起新的授权会话 |
+| 无可用 Key | 进入创建 Key 流程，按分组倍率提示完成 |
+| 二维码无法渲染 | CLI 自动降级为打印 `code_url` 文本 |
+| 启动 Claude Code 失败 | 检查 `claude` 是否在 PATH 中（`npm install -g @anthropic-ai/claude-code`） |
+| 启动 Codex 失败 | 检查 `codex` 是否在 PATH 中（`npm i -g @openai/codex`），并复核 `~/.codex/config.toml` |
+| Node 版本过低 | 升级到 Node.js 18 LTS 后重新运行 bootstrap |
+| 全局 npm 权限不足 | 修复 npm 全局目录权限，或使用 `nvm` 等用户级 Node 管理器 |
+
+## 开发与测试
+
+项目使用 Node 内置 test runner，避免引入额外测试框架。
+
+```bash
+# 进入 CLI 包
+cd claude360-cli
+
+# 安装依赖（仅 qrcode-terminal）
+npm install
+
+# 跑全部测试
+npm test
+```
+
+期望结果：全部测试通过。
+
+后端 Go 测试（在仓库根目录执行）：
+
+```bash
+go test ./model ./middleware ./controller -run 'TestCli|TestGetUserTopUpByTradeNo' -count=1
+```
+
+### 调试入口
+
+```bash
+# 直接以源码模式运行
+node ./bin/claude360.js
+```
+
+修改源码后无需重启全局安装，可通过 `npm link` 把当前 CLI 包链到全局：
+
+```bash
+cd claude360-cli && npm link
+claude360
+```
+
+调试时可注入自定义提示器、API client、浏览器打开函数等：`src/index.js` 中 `runCli({...})` 全部依赖均可注入，便于自动化测试和插桩。
+
+## 项目结构
+
+```
+claude360-cli/
+├── bin/
+│   └── claude360.js          # CLI 入口
+├── install/
+│   ├── install.sh            # macOS / Linux bootstrap
+│   ├── install.ps1           # Windows PowerShell bootstrap
+│   └── verification-matrix.md
+├── scripts/                  # 测试与本地脚本
+├── src/
+│   ├── api-client.js         # HTTP + NewAPI 信封解析
+│   ├── auth.js               # 设备码授权流程
+│   ├── config-store.js       # 本地配置读写（0600）
+│   ├── diagnostics.js        # 诊断报告
+│   ├── group-manager.js      # 分组与倍率展示（无本地映射）
+│   ├── index.js              # 顶层编排：授权 → Key → 主菜单
+│   ├── menu.js               # 主菜单
+│   ├── platform.js           # 平台路径与能力探测
+│   ├── token-manager.js      # Key 选择 / 创建 / reveal
+│   ├── tool-installer.js     # 全局 npm 安装 / 更新（需确认）
+│   ├── tool-launcher.js      # Claude Code / Codex 子进程启动与配置写入
+│   └── topup.js              # 微信 Native 充值流程
+├── test/                     # 11 个测试文件
+├── package.json
+└── README.md
+```
+
+后端配套文件（位于仓库根目录）：
+
+```
+controller/cli.go              # /api/cli/* handler
+controller/cli_test.go
+middleware/cli_auth.go         # CLI bearer 中间件
+middleware/cli_auth_test.go
+model/cli_auth.go              # CliAuthSession 模型
+model/cli_auth_test.go
+model/topup.go                 # 新增 GetUserTopUpByTradeNo
+model/main.go                  # 增加 CliAuthSession AutoMigrate
+router/api-router.go           # 注册 /api/cli/* 路由
+web/src/pages/CliAuthorize/    # 浏览器授权页
+```
+
+## 安全模型
+
+- CLI 不接收、不保存站点账号密码。
+- 设备码、user_code、CLI 凭证均短期有效；CLI 凭证可后台吊销。
+- 授权轮询限频（`middleware.CriticalRateLimit()`）。
+- `POST /api/cli/tokens/:id/reveal` 强制鉴权 + 限频 + 禁用缓存。
+- 后端日志不记录明文 Key；CLI 日志不打印完整 Key。
+- 充值订单只能被订单所属用户查询。
+- 本地配置文件 macOS/Linux 写入 mode `0600`；Windows 写入当前用户目录。
+- 任何全局 npm、系统运行时安装都需用户在终端显式确认。
+- CLI 不修改 shell profile / PowerShell profile / 全局环境变量。
+
+## 已知风险与路线图
+
+| 项 | 状态 |
+| --- | --- |
+| 自动化测试（Backend Go + CLI Node） | ✅ 全部通过（CLI Node + Go 后端 PASS） |
+| 真实站点手动端到端验证 | ⚠️ 待执行（见 `prd/claude360-cli-verification.md` Task 13 Step 3） |
+| Codex `wire_api = "responses"` 端到端兼容 | ⚠️ 需 NewAPI/Claude360 网关确认 `/v1/responses` 兼容性 |
+| 微信 Native 真实商户回调 | ⚠️ 需对接生产商户配置后验证 |
+| 系统密钥链保存 | ❌ 第一版不做 |
+| 新用户注册闭环 | ❌ 第一版不做 |
+| 多支付方式聚合 | ❌ 第一版不做 |
+| 多域名 / 私有部署切换 | ❌ 第一版不做 |
+
+完整需求边界见 `prd/claude360-cli-prd.md`。
+
+## 许可证
+
+随仓库根目录 `LICENSE` 发布，未单独声明。

package/bin/claude360.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/index.js";
+
+try {
+  await runCli();
+} catch (error) {
+  console.error(error?.message || String(error));
+  process.exitCode = 1;
+}

package/install/install.ps1

@@ -0,0 +1,57 @@
+# Website one-line command:
+# irm https://claude360.xyz/install.ps1 | iex
+
+$ErrorActionPreference = "Stop"
+
+function Confirm-Action {
+    param([string]$Message)
+    Write-Host $Message
+    $answer = Read-Host "输入 yes 确认继续"
+    return @("yes", "y", "Y", "YES", "是", "确认", "继续") -contains $answer
+}
+
+function Invoke-LoggedCommand {
+    param(
+        [string]$Command,
+        [string[]]$Arguments
+    )
+    Write-Host ("+ " + $Command + " " + ($Arguments -join " "))
+    & $Command @Arguments
+    if ($LASTEXITCODE -ne 0) {
+        throw "$Command exited with code $LASTEXITCODE"
+    }
+}
+
+$os = [System.Runtime.InteropServices.RuntimeInformation]::OSDescription
+$arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
+Write-Host "Claude360 bootstrap"
+Write-Host "OS: $os"
+Write-Host "Arch: $arch"
+
+$node = Get-Command "node" -ErrorAction SilentlyContinue
+$npm = Get-Command "npm" -ErrorAction SilentlyContinue
+if (-not $node -or -not $npm) {
+    Write-Host "未检测到 Node.js/npm。Claude360 CLI 需要 Node.js 18+ 和 npm。"
+    Write-Host "请先通过 winget、Node.js 官网安装 Node.js LTS 后重新运行本脚本。"
+    if (-not (Confirm-Action "本脚本不会自动安装系统运行时。确认已了解 Node.js/npm 前置要求？")) {
+        exit 1
+    }
+    exit 1
+}
+
+& "node" @("--version")
+& "npm" @("--version")
+$nodeVersion = (& "node" @("--version")).TrimStart("v")
+$nodeMajor = [int]($nodeVersion.Split(".")[0])
+if ($nodeMajor -lt 18) {
+    Write-Host "当前 Node.js 版本低于 18，请升级到 Node.js LTS 后重新运行本脚本。"
+    exit 1
+}
+
+if (-not (Confirm-Action "将执行全局 npm 操作：npm install -g claude360@latest`n影响范围：安装或更新 Claude360 CLI 到当前用户 npm 全局目录，并随后启动 claude360 setup 首次配置向导；配置向导可能打开浏览器授权并写入用户目录配置。是否继续？")) {
+    Write-Host "已取消安装。"
+    exit 0
+}
+
+Invoke-LoggedCommand "npm" @("install", "-g", "claude360@latest")
+Invoke-LoggedCommand "claude360" @("setup")

package/install/install.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Website one-line command:
+# curl -fsSL https://claude360.xyz/install.sh | bash
+
+confirm() {
+  local message="$1"
+  printf "%s\n" "$message"
+  printf "输入 yes 确认继续: "
+  if [ -r /dev/tty ]; then
+    read -r answer </dev/tty
+  else
+    read -r answer
+  fi
+  case "${answer}" in
+    yes|y|Y|YES|是|确认|继续) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+run_cmd() {
+  printf "+ %s\n" "$*"
+  "$@"
+}
+
+OS_NAME="$(uname -s)"
+ARCH_NAME="$(uname -m)"
+printf "Claude360 bootstrap\nOS: %s\nArch: %s\n" "$OS_NAME" "$ARCH_NAME"
+
+if ! command -v node >/dev/null 2>&1 || ! command -v npm >/dev/null 2>&1; then
+  cat <<'EOF'
+未检测到 Node.js/npm。Claude360 CLI 需要 Node.js 18+ 和 npm。
+请先通过系统包管理器或 Node.js 官网安装 Node.js LTS 后重新运行本脚本。
+EOF
+  if ! confirm "本脚本不会自动安装系统运行时。确认已了解 Node.js/npm 前置要求？"; then
+    exit 1
+  fi
+  exit 1
+fi
+
+node --version
+npm --version
+NODE_MAJOR="$(node --version | sed 's/^v//' | cut -d. -f1)"
+if [ "${NODE_MAJOR}" -lt 18 ]; then
+  printf "当前 Node.js 版本低于 18，请升级到 Node.js LTS 后重新运行本脚本。\n"
+  exit 1
+fi
+
+if ! confirm "将执行全局 npm 操作：npm install -g claude360@latest
+影响范围：安装或更新 Claude360 CLI 到当前用户 npm 全局目录，并随后启动 claude360 setup 首次配置向导；配置向导可能打开浏览器授权并写入用户目录配置。是否继续？"; then
+  printf "已取消安装。\n"
+  exit 0
+fi
+
+run_cmd npm install -g claude360@latest
+run_cmd claude360 setup

package/install/verification-matrix.md

@@ -0,0 +1,18 @@
+# Claude360 Bootstrap Manual Verification Matrix
+
+## One-Line Commands
+
+- Windows PowerShell: `irm https://claude360.xyz/install.ps1 | iex`
+- macOS/Linux bash: `curl -fsSL https://claude360.xyz/install.sh | bash`
+
+## Required Checks
+
+| Scenario | Expected result |
+| --- | --- |
+| Windows PowerShell | Detects OS/architecture, checks `"node"` and `"npm"`, asks confirmation before `npm install -g claude360@latest`, and confirmation text discloses that `claude360 setup` may open browser auth and write user config. |
+| macOS Terminal | Detects `uname -s`/`uname -m`, checks Node/npm, asks confirmation before global npm install, and confirmation text discloses that `claude360 setup` may open browser auth and write user config. |
+| Ubuntu bash | Same as macOS Terminal; failure messages should mention Node.js/npm prerequisite when missing. |
+| Node missing | Script explains Node.js 18+/npm requirement and exits without running npm install. |
+| Node present | Script prints Node/npm versions before asking for global npm install confirmation. |
+| Node present but version < 18 | Script exits before npm install and tells the user to upgrade to Node.js LTS. |
+| npm global permission missing | `npm install -g claude360@latest` failure is visible to the user; user should rerun after fixing npm global directory permissions. |

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "claude360",
+  "version": "0.1.0",
+  "description": "Interactive Claude360 CLI for browser auth, API key setup, balance checks, top-up, Claude Code and Codex launch.",
+  "type": "module",
+  "bin": {
+    "claude360": "bin/claude360.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "install/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0"
+  },
+  "scripts": {
+    "test": "node ./scripts/test.js"
+  }
+}

package/src/api-client.js

@@ -0,0 +1,80 @@
+export class ApiError extends Error {
+  constructor(message, { status, response } = {}) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.response = response;
+  }
+}
+
+export class ApiClient {
+  constructor({
+    baseUrl = "https://claude360.xyz",
+    cliToken = "",
+    fetch: fetchImpl = globalThis.fetch,
+  } = {}) {
+    if (typeof fetchImpl !== "function") {
+      throw new ApiError("当前 Node 环境不支持 fetch");
+    }
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.cliToken = cliToken;
+    this.fetch = fetchImpl;
+  }
+
+  async get(path) {
+    return this.request("GET", path);
+  }
+
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+
+  async request(method, path, body) {
+    const requestUrl = this.resolveUrl(path);
+    const headers = {};
+    const init = { method, headers };
+    if (this.cliToken && this.isSameOrigin(requestUrl)) {
+      headers.Authorization = `Bearer ${this.cliToken}`;
+    }
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      init.body = JSON.stringify(body);
+    }
+
+    const response = await this.fetch(requestUrl, init);
+    const text = typeof response.text === "function" ? await response.text() : "";
+    let envelope;
+    try {
+      envelope = text ? JSON.parse(text) : {};
+    } catch {
+      throw new ApiError(`响应不是有效 JSON${text ? `: ${text}` : ""}`, {
+        status: response.status,
+      });
+    }
+
+    if (!response.ok) {
+      throw new ApiError(`HTTP ${response.status}: ${envelope?.message || "请求失败"}`, {
+        status: response.status,
+        response: envelope,
+      });
+    }
+    if (!envelope?.success) {
+      throw new ApiError(envelope?.message || "请求失败", {
+        status: response.status,
+        response: envelope,
+      });
+    }
+    return envelope.data ?? null;
+  }
+
+  resolveUrl(path) {
+    if (/^https?:\/\//i.test(path)) {
+      return path;
+    }
+    return `${this.baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
+  }
+
+  isSameOrigin(requestUrl) {
+    return new URL(requestUrl).origin === new URL(this.baseUrl).origin;
+  }
+}

package/src/auth.js

@@ -0,0 +1,82 @@
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function startAuth({
+  api,
+  openBrowser,
+  writeLine = console.log,
+  sleep = defaultSleep,
+  now = Date.now,
+} = {}) {
+  if (!api || typeof api.post !== "function") {
+    throw new Error("缺少 API client");
+  }
+  if (typeof openBrowser !== "function") {
+    throw new Error("缺少浏览器打开函数");
+  }
+
+  const start = await api.post("/api/cli/auth/start");
+  if (!start?.device_code || !start?.verification_url || !start?.user_code) {
+    throw new Error("授权服务返回数据不完整");
+  }
+
+  const verificationUrl = withAuthCodes(start.verification_url, {
+    userCode: start.user_code,
+    deviceCode: start.device_code,
+  });
+  writeLine(`授权地址：${verificationUrl}`);
+  writeLine(`用户码：${start.user_code}`);
+  await openBrowser(verificationUrl);
+
+  const intervalMs = secondsToMs(start.interval, 5);
+  const expiresInMs = secondsToMs(start.expires_in, 600);
+  const deadline = now() + expiresInMs;
+
+  while (true) {
+    const beforePollAt = now();
+    if (beforePollAt >= deadline) {
+      throw new Error("授权超时");
+    }
+
+    const poll = await api.post("/api/cli/auth/poll", {
+      device_code: start.device_code,
+    });
+    const afterPollAt = now();
+    if (afterPollAt >= deadline) {
+      throw new Error("授权超时");
+    }
+
+    switch (poll?.status) {
+      case "approved":
+        if (!poll.cli_token) {
+          throw new Error("授权成功但未返回 CLI token");
+        }
+        return poll.cli_token;
+      case "pending":
+        await sleep(Math.min(intervalMs, Math.max(deadline - afterPollAt, 0)));
+        break;
+      case "denied":
+        throw new Error("用户拒绝授权");
+      case "expired":
+        throw new Error("授权已过期");
+      default:
+        throw new Error(`未知授权状态: ${poll?.status || "empty"}`);
+    }
+  }
+}
+
+export const authenticateWithBrowser = startAuth;
+
+function secondsToMs(value, fallback) {
+  const seconds = Number(value);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    return fallback * 1000;
+  }
+  return seconds * 1000;
+}
+
+function withAuthCodes(url, { userCode, deviceCode }) {
+  const parsed = new URL(url);
+  parsed.searchParams.set("user_code", userCode);
+  parsed.searchParams.set("device_code", deviceCode);
+  return parsed.toString();
+}