claude360 0.2.8 → 0.3.0

package/README.md

@@ -1,10 +1,17 @@
 # Claude360 CLI
 
-面向 [Claude360](https://claude360.xyz) 已注册用户的跨平台命令行工具，让不熟悉终端配置的用户也能一行命令完成 Claude Code / Codex 的安装、授权、Key 选择、余额查询、微信扫码充值与日常启动。
+[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue)]()
+[![Tests](https://img.shields.io/badge/tests-232%20passing-success)]()
+
+面向 [Claude360](https://claude360.xyz) 已注册用户的跨平台命令行工具，让不熟悉终端配置的用户也能一行命令完成 **Claude Code / Codex** 的安装、授权、Key 选择、余额查询、微信扫码充值与日常启动。
 
 - 不要求用户在终端输入站点账号密码，授权全程在浏览器完成。
 - 不修改 shell profile / PowerShell profile / 全局环境变量。
-- 分组倍率、充值金额、API 凭证生命周期均以 NewAPI 后端为唯一来源，CLI 不内置任何业务口径。
+- 分组倍率、充值金额、API 凭证生命周期均以后端为唯一来源，CLI 不内置任何业务口径。
+- 全部交互文字采用**分层语义配色**，自动适配 truecolor / 256 色 / 无色终端。
+
+> 本仓库仅包含 **CLI 客户端**（Node.js）。其依赖的 `/api/cli/*` 后端接口由 Claude360 服务端提供，**不在本仓库内**。
 
 ## 目录
 
@@ -13,14 +20,14 @@
 - [快速开始](#快速开始)
 - [首次配置流程](#首次配置流程)
 - [日常使用](#日常使用)
+- [终端配色体系](#终端配色体系)
 - [本地配置](#本地配置)
-- [后端接口](#后端接口)
+- [后端接口契约](#后端接口契约)
 - [Claude Code 与 Codex 集成](#claude-code-与-codex-集成)
 - [诊断与故障排查](#诊断与故障排查)
 - [开发与测试](#开发与测试)
 - [项目结构](#项目结构)
 - [安全模型](#安全模型)
-- [已知风险与路线图](#已知风险与路线图)
 - [致谢](#致谢)
 - [许可证](#许可证)
 
@@ -30,20 +37,22 @@
 | --- | --- |
 | 一行命令安装 | Windows PowerShell / macOS / Linux bash 一行命令拉起 bootstrap，自动检测 Node/npm 与全局 npm 权限 |
 | 方向键交互 | 全部菜单 / 选择 / 确认使用方向键导航（↑↓ 移动、Enter 确认、Esc 返回、空格多选、←→ 切换 YES/NO），非 TTY / CI 环境自动降级为编号输入 |
+| 分层语义配色 | 成功 / 失败 / 警告 / 信息 / 步骤 / 键值回显 / 路径 / 标题等按角色着色，层次分明；自动适配 truecolor / 256 色 / `NO_COLOR` |
 | 真实模型选择 | 模型列表来自 `GET /api/cli/models`（用户可用分组 × 模型元数据），展示模型 ID / 名称 / 标签 / 说明，保存真实 model id |
 | 浏览器设备授权 | 通过 `/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` 启动 |
+| 启动 Codex | 写入隔离的 Claude360 provider / profile 覆盖层配置，并以 `codex --profile claude360` 启动 |
 | 工具更新 | 菜单内更新 `claude360` 自身、Claude Code、Codex，全部需要二次确认 |
-| 一键完整初始化 | Claude Code / Codex 完整初始化向导：登录、Key、安装/更新、API 注入、输出语言、提示词风格、工作流、MCP、模型、权限配置、连接测试、启动 |
+| 一键完整初始化 | 登录、Key、安装/更新、API 注入、输出语言、提示词风格、工作流、MCP、模型、权限配置、连接测试、启动一站式向导 |
 | 推荐工作流 / Skill | 六步工作流、Git 指令、功能规划 UX、BMad 安装器等，写入 `~/.claude/commands/claude360/` 与 `~/.codex/prompts/`，写前备份、冲突二次确认 |
 | 推荐 MCP | Context7 / Open Web Search / Spec 工作流 / DeepWiki / Playwright / Exa / Serena，多选安装、重依赖单独确认、同名去重 |
 | AI 输出语言 / 提示词风格 | 写入 `~/.claude/CLAUDE.md` 或 `~/.codex/AGENTS.md` 的 Claude360 标记区块，不覆盖用户内容 |
 | 配置备份 | 所有写入用户工具配置的操作先备份到 `~/.claude/backup/` 或 `~/.codex/backup/` 时间戳目录 |
-| 诊断报告 | OS/Node/npm/全局 npm 权限/工具版本/连通性/授权状态/余额/Key/支付端点一站式检查，按模块分组表格展示 |
+| 诊断报告 | OS/Node/npm/全局 npm 权限/工具版本/连通性/授权状态/余额/Key/支付端点一站式检查，按模块分组着色表格展示 |
+| cc-switch 配置生成 | 生成可导入 [cc-switch](https://github.com/farion1231/cc-switch) 的供应商配置，支持完整 / 脱敏预览与本地保存（0600） |
 
 ## 系统要求
 
@@ -55,33 +64,40 @@
 
 ## 快速开始
 
-### macOS / Linux
+### 一行命令安装（推荐）
+
+macOS / Linux：
 
 ```bash
 curl -fsSL https://claude360.xyz/install.sh | bash
 ```
 
-### Windows PowerShell
+Windows PowerShell：
 
 ```powershell
 irm https://claude360.xyz/install.ps1 | iex
 ```
 
-Bootstrap 脚本职责：
+Bootstrap 脚本职责：识别 OS / 架构 → 检查 Node.js 与 npm（缺失或 < 18 直接退出并给出修复建议）→ 展示影响范围并要求确认 → `npm install -g claude360@latest` → `claude360 setup` 进入首次配置向导。
 
-1. 识别 OS / 架构。
-2. 检查 Node.js 与 npm（缺失或 < 18 直接退出并给出修复建议）。
-3. 展示影响范围并要求确认。
-4. 执行 `npm install -g claude360@latest`。
-5. 执行 `claude360 setup` 进入首次配置向导。
-
-### 手动安装
+### 通过 npm 全局安装
 
 ```bash
 npm install -g claude360@latest
 claude360
 ```
 
+### 从源码运行（开发者）
+
+```bash
+git clone https://github.com/Johnhpure/claude360cli.git
+cd claude360cli
+npm install
+node ./bin/claude360.js          # 直接以源码模式运行
+# 或链接到全局命令：
+npm link && claude360
+```
+
 ## 首次配置流程
 
 ```
@@ -115,7 +131,7 @@ claude360
 
 ## 日常使用
 
-主菜单按分组展示，TTY 环境下用 **方向键 + Enter** 选择（Esc 返回）；非 TTY / CI 环境自动降级为编号输入，编号以实际输出为准：
+主菜单按分组展示，TTY 环境下用 **方向键 + Enter** 选择（Esc 返回）；非 TTY / CI 环境自动降级为编号输入：
 
 ```
 请选择功能：
@@ -140,18 +156,34 @@ claude360
   退出                    退出 claude360 CLI
 ```
 
-- **余额与充值**：调用 `GET /api/cli/me`，展示账号、余额、已用、当前 Key 名称与分组；充值先取 `/api/cli/topup/options`，按后端校验通过的金额或最低额提交，再用 `qrcode-terminal` 在终端渲染 `code_url`，渲染失败时降级为纯文本 URL。轮询 `/api/cli/topup/order?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` 注入。
+- **余额与充值**：调用 `GET /api/cli/me` 展示账号、余额、已用、当前 Key 名称与分组；充值先取 `/api/cli/topup/options`，按后端校验通过的金额或最低额提交，再用 `qrcode-terminal` 在终端渲染 `code_url`，渲染失败时降级为纯文本 URL。轮询订单状态，支付完成自动刷新余额。
+- **启动 Claude Code**：以 `claude` 子进程启动，并通过 `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` 注入。
+- **启动 Codex**：写入 `~/.codex/config.toml` 的 `[model_providers.claude360]` 与 profile 覆盖层 `~/.codex/claude360.config.toml`，发现冲突字段会先要求用户确认再覆盖，然后 `codex --profile claude360`，并通过 `CLAUDE360_API_KEY` 注入。
 - **安装或更新工具**：三选一菜单（仅 Claude Code / 仅 Codex / 两者），每步都需要确认。
 - **切换 Key / 模型**：重新进入 Token 向导，或从 `/api/cli/models` 拉取真实模型列表选择默认模型。
-- **诊断与修复**：见下方“诊断与故障排查”。
+
+## 终端配色体系
+
+CLI 的全部行内交互文字通过统一的语义消息层（`src/messages.js`）输出，每种角色有专属颜色与符号前缀，形成清晰层级；色值集中在 `src/colors.js` 的单一主题中：
+
+| 角色 | 符号 | 颜色 | 用途 |
+| --- | --- | --- | --- |
+| success | `✓` | 绿 | 操作成功 |
+| error | `×` | 红 | 失败 / 异常 |
+| warn | `!` | 黄 | 警告 / 降级 |
+| step | `→` | 紫 | 进行中 / 步骤 |
+| info | — | 天蓝 | 中性信息 |
+| result | — | 灰蓝标签 + 亮白值 | 键值回显 |
+| path / hint | — | 灰阶 | 路径 / 次要说明 |
+| title / heading | — | 白 / 亮青（加粗） | 标题 |
+
+着色能力自动探测：truecolor（24-bit）→ 256 色（量化）→ 无色。设置环境变量 `NO_COLOR=1` 可强制关闭颜色，`FORCE_COLOR=2` 可强制真彩色；非 TTY / 管道 / CI 输出默认为纯文本（不含 ANSI 序列），保证可被脚本解析。
 
 ## 本地配置
 
 | 平台 | 路径 |
 | --- | --- |
-| macOS / Linux | `~/.claude360/config.json` (权限 `0600`) |
+| macOS / Linux | `~/.claude360/config.json`（权限 `0600`） |
 | Windows | `%USERPROFILE%\.claude360\config.json` |
 
 示例：
@@ -169,36 +201,35 @@ claude360
 
 注意事项：
 
-- 第一版接受**本地明文**保存 `cliToken` 与 `apiKey`，CLI 仅收紧文件权限，不接入系统密钥链。
+- 当前版本接受**本地明文**保存 `cliToken` 与 `apiKey`，CLI 仅收紧文件权限，不接入系统密钥链。
 - CLI 日志与诊断输出会脱敏 API Key。
 - 若需要重置，删除 `~/.claude360/config.json` 即可触发完整重新授权。
 
-## 后端接口
+## 后端接口契约
 
-CLI 仅依赖一组隔离的 `/api/cli` 接口，由 `newapi/controller/cli.go` 提供：
+CLI 仅依赖一组隔离的 `/api/cli` 接口（由 Claude360 服务端提供，**后端代码不在本仓库**）：
 
 | 方法 | 路径 | 说明 |
 | --- | --- | --- |
 | POST | `/api/cli/auth/start` | 创建设备码授权会话 |
 | POST | `/api/cli/auth/confirm` | 浏览器端登录用户确认授权（站点 Web Session） |
-| POST | `/api/cli/auth/poll` | CLI 轮询授权结果，状态：`pending` / `approved` / `denied` / `expired` / `consumed` |
+| 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()` 约束） |
+| POST | `/api/cli/tokens` | 按分组创建新 Key |
 | GET | `/api/cli/groups` | 用户可用分组（含 `display_name`、`ratio`、`description`） |
-| GET | `/api/cli/models` | 当前用户可用模型列表（含 `display_name`、`tags`、`description`、`recommended`；`tool` 参数预留） |
+| GET | `/api/cli/models` | 当前用户可用模型列表（含 `display_name`、`tags`、`description`、`recommended`） |
 | GET | `/api/cli/topup/options` | 后端配置的充值金额选项与最低额，包含 WeChat 启用状态 |
 | POST | `/api/cli/topup/wechat` | 创建微信 Native 订单，返回 `code_url`、`order_id`、`pay_money` |
-| GET | `/api/cli/topup/:order_id` | 查询订单状态（仅订单所属用户） |
+| GET | `/api/cli/topup/order?order_id=` | 查询订单状态（仅订单所属用户） |
 
-实现要点：
+契约要点：
 
 - 设备码、user_code、CLI 凭证均有过期机制；CLI 凭证可后台吊销。
-- 已批准会话被消费后保持 `consumed` 状态，CLI 凭证有独立有效期，设备码窗口过期不影响已发出的凭证。
+- 已批准会话被消费后保持 `consumed`，CLI 凭证有独立有效期，设备码窗口过期不影响已发出的凭证。
 - Key reveal 强制鉴权 + 限频；后端日志不记录明文 Key。
 - 充值订单仅订单所属用户可查询。
-- 详细字段格式见 `prd/claude360-cli-prd.md` 第 7 章。
 
 ## Claude Code 与 Codex 集成
 
@@ -215,17 +246,15 @@ ANTHROPIC_AUTH_TOKEN=<selected_api_key>
 
 ### Codex
 
-写入 `~/.codex/config.toml`（仅修改 `model_providers.claude360` 与 `profiles.claude360` 两个表，不动其他 provider）：
+写入 `~/.codex/config.toml`（仅修改 `model_providers.claude360`，不动其他 provider），模型等覆盖项写入隔离的 profile 覆盖层 `~/.codex/claude360.config.toml`：
 
 ```toml
+# ~/.codex/config.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"
 ```
 
 启动命令：
@@ -236,22 +265,11 @@ 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”。
+> **风险说明**：Codex 自定义 provider 使用 Responses 协议（`wire_api = "responses"`）。后端网关必须支持 `/v1/responses` 或在网关层将 Responses 请求适配到现有模型能力，否则 Codex 调用会失败。
 
 ## 诊断与故障排查
 
-执行主菜单中“诊断”项，CLI 会汇报以下检查项：
-
-- 操作系统与架构。
-- 终端二维码渲染能力。
-- Node.js / npm 版本。
-- 全局 npm 安装权限。
-- Claude Code / Codex 是否安装及版本。
-- `https://claude360.xyz` API 连通性。
-- CLI 授权状态、账户余额、Key 列表拉取状态。
-- 微信支付端点可用性。
-
-常见异常及处理建议：
+主菜单“诊断与修复”会汇报：操作系统与架构、终端二维码渲染能力、Node.js / npm 版本、全局 npm 安装权限、Claude Code / Codex 安装与版本、API 连通性、CLI 授权状态、账户余额、Key 列表拉取状态、微信支付端点可用性。报告以分组着色表格展示，状态用绿 ✓ / 黄 ! / 红 × 区分，失败项附修复建议。
 
 | 现象 | 处理 |
 | --- | --- |
@@ -266,123 +284,86 @@ codex --profile claude360
 
 ## 开发与测试
 
-项目使用 Node 内置 test runner，避免引入额外测试框架。
-
-```bash
-# 进入 CLI 包
-cd claude360-cli
-
-# 安装依赖（qrcode-terminal、smol-toml）
-npm install
-
-# 跑全部测试
-npm test
-```
-
-期望结果：全部测试通过。
-
-后端 Go 测试（在仓库根目录执行）：
+项目使用 Node 内置 test runner，不引入额外测试框架。
 
 ```bash
-go test ./model ./middleware ./controller -run 'TestCli|TestGetUserTopUpByTradeNo' -count=1
+npm install        # 安装依赖（@inquirer/core、qrcode-terminal、smol-toml）
+npm test           # 跑全部测试（26 个测试文件 / 232 个用例）
+npm test messages  # 只跑某个测试文件（test/messages.test.js）
 ```
 
-### 调试入口
+调试入口：
 
 ```bash
-# 直接以源码模式运行
-node ./bin/claude360.js
+node ./bin/claude360.js     # 源码模式运行
+npm link && claude360       # 链接到全局命令
 ```
 
-修改源码后无需重启全局安装，可通过 `npm link` 把当前 CLI 包链到全局：
-
-```bash
-cd claude360-cli && npm link
-claude360
-```
-
-调试时可注入自定义提示器、API client、浏览器打开函数等：`src/index.js` 中 `runCli({...})` 全部依赖均可注入，便于自动化测试和插桩。
+`src/index.js` 的 `runCli({...})` 全部依赖（提示器、API client、浏览器打开函数、`writeLine`、`execCommand` 等）均可注入，便于自动化测试与插桩。
 
 ## 项目结构
 
 ```
-claude360-cli/
+claude360cli/
 ├── bin/
 │   └── claude360.js          # CLI 入口
 ├── install/
 │   ├── install.sh            # macOS / Linux bootstrap
 │   ├── install.ps1           # Windows PowerShell bootstrap
 │   └── verification-matrix.md
-├── scripts/                  # 测试与本地脚本
+├── scripts/
+│   └── test.js               # 测试运行器（node --test 包装）
 ├── src/
-│   ├── api-client.js         # HTTP + NewAPI 信封解析
-│   ├── auth.js               # 设备码授权流程
-│   ├── config-store.js       # 本地配置读写（0600）
-│   ├── diagnostics.js        # 诊断报告
-│   ├── group-manager.js      # 分组与倍率展示（无本地映射）
 │   ├── index.js              # 顶层编排：环境检查 → 工具引导 → 授权 → Key → 主菜单
-│   ├── menu.js               # 主菜单
-│   ├── platform.js           # 平台路径与能力探测
+│   ├── colors.js             # 色彩能力探测 + 单一语义主题（PALETTE / theme）
+│   ├── messages.js           # 语义消息层（formatMessage / createMessenger）
+│   ├── banner.js             # 品牌横幅与流光动效、环境检查行
+│   ├── menu.js               # 首次 / 日常菜单渲染与选择
+│   ├── prompts.js            # 方向键单选 / 多选 / 确认（@inquirer/core）+ 降级输入
+│   ├── ui.js                 # 表格 / 标题 / 信息盒子等结构化渲染
+│   ├── api-client.js         # HTTP + 后端信封解析
+│   ├── auth.js               # 设备码授权流程
 │   ├── token-manager.js      # Key 选择 / 创建 / reveal
+│   ├── account-status.js     # 主菜单账户状态面板
+│   ├── topup.js              # 微信 Native 充值流程
+│   ├── diagnostics.js        # 诊断报告
+│   ├── init-config.js        # 输出语言 / 提示词风格 / 默认模型 / 权限写入
+│   ├── init-flow.js          # 一键完整初始化编排
+│   ├── mcp-skill.js          # 推荐 MCP / Skill / AGENTS 安装
+│   ├── workflows.js          # 推荐工作流安装
 │   ├── tool-installer.js     # 全局 npm 安装 / 更新（需确认）
 │   ├── tool-launcher.js      # Claude Code / Codex 子进程启动与配置写入
-│   └── topup.js              # 微信 Native 充值流程
-├── test/                     # 11 个测试文件
+│   ├── cc-switch.js          # cc-switch 供应商配置生成
+│   ├── config-store.js       # 本地配置读写（0600）
+│   ├── group-manager.js      # 分组与倍率展示（无本地映射）
+│   ├── backup.js             # 写入前时间戳备份
+│   ├── sanitize.js           # 输出脱敏（Key / 错误信息）
+│   ├── onboarding.js         # 环境检查与工具安装引导
+│   ├── platform.js           # 平台路径与能力探测
+│   └── zcf-notice.js         # 开源参考声明
+├── test/                     # 26 个测试文件（与 src 一一对应）
 ├── 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。
+- 授权轮询限频；`POST /api/cli/tokens/:id/reveal` 强制鉴权 + 限频 + 禁用缓存。
+- 后端日志不记录明文 Key；CLI 日志不打印完整 Key（统一经 `sanitize.js` 脱敏）。
 - 充值订单只能被订单所属用户查询。
 - 本地配置文件 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`。
-
 ## 致谢
 
-本 CLI 的交互式初始化流程、工作流导入、MCP 推荐配置等设计，借鉴并参考了开源项目
-[NPX ZCF](https://github.com/UfoMiao/zcf) 的部分功能体验，感谢作者 UfoMiao 的开源贡献。
+本 CLI 的交互式初始化流程、工作流导入、MCP 推荐配置等设计，借鉴并参考了开源项目 [NPX ZCF](https://github.com/UfoMiao/zcf) 的部分功能体验，感谢作者 UfoMiao 的开源贡献。
 
 - 相关功能入口（完整初始化、推荐工作流 / MCP / Skill / AGENTS）会在终端展示开源参考声明。
 - 随 CLI 安装的推荐工作流文件均为 Claude360 自研改编内容，文件头保留对 NPX ZCF 的 attribution 注释。
-- 如后续直接引入 ZCF 的源码、配置文件或文档片段，需先核查其开源许可证并在此处补充对应声明。
 
 ## 许可证
 
-随仓库根目录 `LICENSE` 发布，未单独声明。
+本仓库尚未声明开源许可证。在对外公开分发前，建议补充一个 `LICENSE` 文件（如 MIT）。在添加许可证之前，默认保留所有权利（All Rights Reserved）。

package/bin/claude360.js

@@ -3,11 +3,15 @@
 import { runCli } from "../src/index.js";
 import { safeErrorMessage } from "../src/sanitize.js";
 
-const command = process.argv[2] || "";
+const rawArgs = process.argv.slice(2);
+const verbose = rawArgs.includes("--verbose") || rawArgs.includes("-v");
+// 仅取位置参数作为命令；--verbose/-v 等 flag 单独解析，避免 "doctor --verbose"
+// 被当成未知命令（现有命令均不以 - 开头，按 - 前缀剥离 flag 安全）。
+const command = rawArgs.filter((arg) => !arg.startsWith("-")).join(" ");
 
 try {
-  await runCli({ command, forceSetup: command === "setup" });
+  await runCli({ command, verbose, forceSetup: command === "setup" });
 } catch (error) {
-  console.error(safeErrorMessage(error));
+  console.error(verbose && error?.stack ? error.stack : safeErrorMessage(error));
   process.exitCode = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude360",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Interactive Claude360 CLI for browser auth, API key setup, balance checks, top-up, Claude Code and Codex launch.",
   "type": "module",
   "bin": {

package/src/account-status.js

@@ -6,6 +6,7 @@
 
 import { loadGroups } from "./group-manager.js";
 import { sanitizeError } from "./sanitize.js";
+import { formatMessage, formatResult } from "./messages.js";
 import { renderStatusTable } from "./ui.js";
 
 export async function loadAccountStatus({ api, config = {} } = {}) {
@@ -75,7 +76,7 @@ export function formatGroupRatio(groups, groupName) {
 
 const STATUS_HEAD = ["账号", "余额", "已用额度", "当前 Key", "分组", "倍率", "状态"];
 
-export function formatAccountStatus({ me, error, config = {}, groups = [], width = 0 } = {}) {
+export function formatAccountStatus({ me, error, config = {}, groups = [], width = 0, color = false } = {}) {
   const configured = config.configuredTools || {};
   const toolLine = `Claude Code：${configured.claudeCode ? "已配置" : "未配置"}    Codex：${configured.codex ? "已配置" : "未配置"}`;
   const tokenName = config.tokenName || "-";
@@ -89,7 +90,7 @@ export function formatAccountStatus({ me, error, config = {}, groups = [], width
   } else if (!me) {
     const reason = sanitizeError(error);
     row = [maskAccount(config.account), "-", "-", tokenName, group, formatGroupRatio(groups, group), "获取失败"];
-    extraLines = [`! 状态获取失败${reason ? `：${reason}` : ""}`, toolLine];
+    extraLines = [formatMessage("warn", `状态获取失败${reason ? `：${reason}` : ""}`, { color }), toolLine];
   } else {
     const account = me.email || me.display_name || me.username;
     const balance = me.balance_display ?? String(me.quota ?? "-");
@@ -103,12 +104,14 @@ export function formatAccountStatus({ me, error, config = {}, groups = [], width
       formatGroupRatio(groups, group),
       me.low_balance ? "余额较低" : "正常",
     ];
-    extraLines = [`今日用量：${usage}${me.low_balance ? "    ! 余额较低，建议充值" : ""}`, toolLine];
+    extraLines = me.low_balance
+      ? [formatResult("今日用量", usage, { color }), formatMessage("warn", "余额较低，建议充值", { color }), toolLine]
+      : [formatResult("今日用量", usage, { color }), toolLine];
   }
 
   return [
-    "Claude360 账户状态",
-    renderStatusTable({ head: STATUS_HEAD, row }, { width }),
+    formatMessage("heading", "Claude360 账户状态", { color }),
+    renderStatusTable({ head: STATUS_HEAD, row }, { width, color }),
     ...extraLines,
   ].join("\n");
 }

package/src/auth.js

@@ -1,3 +1,9 @@
+import { colorLevel } from "./colors.js";
+import { createMessenger } from "./messages.js";
+
+// 语义消息器工厂：真实终端着色，测试/管道（writeLine 被替换）下无色。
+const mk = (writeLine) => createMessenger({ writeLine, color: writeLine === console.log ? colorLevel() : 0 });
+
 const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 export async function startAuth({
@@ -14,6 +20,7 @@ export async function startAuth({
     throw new Error("缺少浏览器打开函数");
   }
 
+  const msg = mk(writeLine);
   const start = await api.post("/api/cli/auth/start");
   if (!start?.device_code || !start?.verification_url || !start?.user_code) {
     throw new Error("授权服务返回数据不完整");
@@ -22,8 +29,8 @@ export async function startAuth({
   const verificationUrl = withAuthCodes(start.verification_url, {
     userCode: start.user_code,
   });
-  writeLine(`授权地址：${verificationUrl}`);
-  writeLine(`用户码：${start.user_code}`);
+  msg.result("授权地址", verificationUrl);
+  msg.result("用户码", start.user_code);
   await openBrowser(verificationUrl);
 
   const intervalMs = secondsToMs(start.interval, 5);

package/src/banner.js

@@ -3,7 +3,7 @@
 // 渲染函数默认无色（color: false），保证测试与管道输出稳定；
 // 运行时由 index.js 通过 playBanner / 显式 color 参数开启彩色。
 
-import { BOLD, DIM, ESC, RESET, colorEnabled, colorLevel, fg, toLevel } from "./colors.js";
+import { BOLD, DIM, ESC, PALETTE, RESET, colorEnabled, colorLevel, fg, toLevel } from "./colors.js";
 
 export const BRAND_BASE_URL = "https://claude360.xyz";
 
@@ -46,7 +46,48 @@ function gradientAt(t) {
   ];
 }
 
+// 默认按 emoji 呈现（2 列宽）的 BMP 杂项符号（Unicode Emoji_Presentation=Yes 的 BMP 部分）。
+// 这些符号即便不带变体选择符，主流终端也按 2 列渲染：✅ U+2705、❌ U+274C、⏳ U+23F3 等。
+// 关键：同区间内的窄符号 —— ✓ U+2713、✔ U+2714、▶ U+25B6、○ U+25CB、→ U+2192、× U+00D7
+// —— 不在此集合，仍按 1 列处理，保证步骤标记与 messages 行内符号的既有对齐不变。
+const BMP_EMOJI_WIDE = new Set();
+for (const [start, end] of [
+  [0x231a, 0x231b], [0x23e9, 0x23ec], [0x23f0, 0x23f0], [0x23f3, 0x23f3],
+  [0x25fd, 0x25fe], [0x2614, 0x2615], [0x2648, 0x2653], [0x267f, 0x267f],
+  [0x2693, 0x2693], [0x26a1, 0x26a1], [0x26aa, 0x26ab], [0x26bd, 0x26be],
+  [0x26c4, 0x26c5], [0x26ce, 0x26ce], [0x26d4, 0x26d4], [0x26ea, 0x26ea],
+  [0x26f2, 0x26f3], [0x26f5, 0x26f5], [0x26fa, 0x26fa], [0x26fd, 0x26fd],
+  [0x2705, 0x2705], [0x270a, 0x270b], [0x2728, 0x2728], [0x274c, 0x274c],
+  [0x274e, 0x274e], [0x2753, 0x2755], [0x2757, 0x2757], [0x2795, 0x2797],
+  [0x27b0, 0x27b0], [0x27bf, 0x27bf], [0x2b1b, 0x2b1c], [0x2b50, 0x2b50],
+  [0x2b55, 0x2b55],
+]) {
+  for (let cp = start; cp <= end; cp += 1) {
+    BMP_EMOJI_WIDE.add(cp);
+  }
+}
+
 function charDisplayWidth(codePoint) {
+  // 变体选择符 VS16（U+FE0F）把前一个 BMP 符号强制为 emoji 呈现（2 列）。逐字符累加无法
+  // 回溯前字符，故给 VS16 计 1 列，补足基础符 1→2 的差值（⚙️ U+2699+FE0F、⚠️ ℹ️ 同理）。
+  if (codePoint === 0xfe0f) {
+    return 1;
+  }
+  // 零宽连接符（U+200D，emoji 序列拼接）不占列宽。
+  if (codePoint === 0x200d) {
+    return 0;
+  }
+  // SMP emoji 平面（🚀 🎉 📦 🔐 等 U+1Fxxx）与 CJK 扩展区按 2 列宽渲染。
+  if (
+    (codePoint >= 0x1f000 && codePoint <= 0x1faff) ||
+    (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+  ) {
+    return 2;
+  }
+  // BMP 默认 emoji 呈现的宽符号（✅ ❌ ⏳ 等）。
+  if (BMP_EMOJI_WIDE.has(codePoint)) {
+    return 2;
+  }
   return (
     (codePoint >= 0x1100 && codePoint <= 0x115f) ||
     (codePoint >= 0x2e80 && codePoint <= 0x303e) ||
@@ -186,8 +227,8 @@ export function renderBanner({
     return rows.map((row) => row.text).join("\n");
   }
   const styles = {
-    title: `${BOLD}${fg(240, 246, 255, level)}`,
-    sub: `${fg(148, 163, 184, level)}`,
+    title: `${BOLD}${fg(...PALETTE.title, level)}`,
+    sub: `${fg(...PALETTE.path, level)}`,
   };
   return rows.map((row) => {
     if (row.style === "footer") {
@@ -243,9 +284,9 @@ export const CHECK_WARN = "!";
 export const CHECK_FAIL = "×";
 
 const CHECK_COLORS = {
-  ok: [74, 222, 128],
-  warn: [250, 204, 21],
-  fail: [248, 113, 113],
+  ok: PALETTE.success,
+  warn: PALETTE.warn,
+  fail: PALETTE.error,
 };
 
 export function formatCheckLine(status, text, { color = false } = {}) {