claude360 0.2.7 → 0.2.9

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude360",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "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";
 
@@ -186,8 +186,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 +243,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 } = {}) {

package/src/cc-switch.js

@@ -4,6 +4,11 @@
 import { chmod, mkdir, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { colorLevel } from "./colors.js";
+import { createMessenger } from "./messages.js";
+
+// 语义消息器工厂：真实终端着色，测试/管道（writeLine 被替换）下无色。
+const mk = (writeLine) => createMessenger({ writeLine, color: writeLine === console.log ? colorLevel() : 0 });
 
 function normalizeBaseUrl(baseUrl = "https://claude360.xyz") {
   return String(baseUrl).replace(/\/+$/, "");
@@ -134,9 +139,10 @@ export async function runCcSwitchGenerator({
     throw new Error("缺少菜单选择输入");
   }
 
+  const msg = mk(writeLine);
   let apiKey = config.apiKey;
   if (!apiKey) {
-    writeLine("当前没有可用 API Key，需要先创建 Claude360 API Key。");
+    msg.warn("当前没有可用 API Key，需要先创建 Claude360 API Key。");
     if (typeof ensureApiKey !== "function") {
       return { done: false, reason: "no_key" };
     }
@@ -150,7 +156,7 @@ export async function runCcSwitchGenerator({
     const token = await ensureApiKey();
     apiKey = token?.apiKey;
     if (!apiKey) {
-      writeLine("未获取到可用 API Key，已取消生成。");
+      msg.info("未获取到可用 API Key，已取消生成。");
       return { done: false, reason: "no_key" };
     }
   }
@@ -185,12 +191,12 @@ export async function runCcSwitchGenerator({
   if (reveal === "masked") {
     const maskedConfig = maskCcSwitchConfig(fullConfig, apiKey);
     writeLine(JSON.stringify(maskedConfig, null, 2));
-    writeLine("提示：脱敏配置仅用于预览，无法直接使用，也不会保存到文件。");
+    msg.hint("提示：脱敏配置仅用于预览，无法直接使用，也不会保存到文件。");
     return { done: true, target, masked: true, saved: false };
   }
 
   writeLine(JSON.stringify(fullConfig, null, 2));
-  writeLine("请将以上配置复制到 cc-switch 中使用。");
+  msg.info("请将以上配置复制到 cc-switch 中使用。");
 
   const saveChoice = await promptSelect("是否保存到本地文件？", [
     { label: "保存到 ~/.claude360/cc-switch-claude360.json", value: "save" },
@@ -201,6 +207,6 @@ export async function runCcSwitchGenerator({
   }
 
   const savedPath = await save(fullConfig);
-  writeLine(`已保存到：${savedPath}（文件权限 0600）`);
+  msg.success(`已保存到：${savedPath}（文件权限 0600）`);
   return { done: true, target, masked: false, saved: true, savedPath };
 }

package/src/colors.js

@@ -91,3 +91,34 @@ export function fg(r, g, b, level = 2) {
   }
   return "";
 }
+
+// ──────────────────────────────────────────────
+// 语义调色板（单一事实源）
+// ──────────────────────────────────────────────
+// 全 CLI 的角色配色统一在此定义，banner / menu / prompts / ui / messages
+// 都从这里取色，杜绝各文件重复硬编码同一组 RGB（色值沿用 Tailwind 体系）。
+// 设计目标：状态色（绿/红/黄）醒目、信息色（天蓝）中性、进行色（紫）区别于
+// 信息、标题白做强调、两级灰（path/hint）用于回显与次要说明 —— 形成层级。
+export const PALETTE = {
+  title: [240, 246, 255], // 强调白：页面/品牌标题、回显值
+  heading: [34, 211, 238], // 亮青：章节标题、品牌高亮
+  info: [125, 211, 252], // 天蓝：中性信息、表头、选择键
+  success: [74, 222, 128], // 绿：操作成功
+  warn: [250, 204, 21], // 黄：警告 / 降级
+  error: [248, 113, 113], // 红：失败 / 危险操作
+  step: [167, 139, 250], // 紫：进行中 / 步骤（与 info 拉开区分）
+  path: [148, 163, 184], // 灰蓝：路径 / 命令 / URL 回显
+  hint: [100, 116, 139], // 暗灰：次要说明 / 帮助 / 未选中项
+  border: [71, 85, 105], // 青灰：边框 / 分隔线
+};
+
+// 按色彩深度 level 现算各语义角色的前景 SGR（真彩色保留 RGB，256 色量化）。
+// level=0 时全部为空串，调用方据此走无色路径。
+export function theme(level) {
+  const t = {};
+  for (const name of Object.keys(PALETTE)) {
+    const [r, g, b] = PALETTE[name];
+    t[name] = fg(r, g, b, level);
+  }
+  return t;
+}