easyai 1.7.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb64eed44834624ee484d3db907ff850bf76280a0a19f56370902a3e3832ddfc
-  data.tar.gz: e173b56ebc2e370631d245a1584ae01155652949bdc8659385683852286399bc
+  metadata.gz: e0e9e5abc64041d1ca3e0a9fb59a81aa3dcdd16edfdfa716069fa17a71df1f4b
+  data.tar.gz: b729e5453a287e1e7fb6908fba42bd4516e48800eafff811d4b0fea80bb83653
 SHA512:
-  metadata.gz: 9b050e5b6dc822af6886cfa9af53871f1027427e51bd509380c0f9842a0a70d16a9d4ce37d60479d20f61d3687fdb59d7a6505f225d4bf0b401ec01f5cf5ad37
-  data.tar.gz: 65a30d6e73f865564b8c1dfe8e7483ecdee4ac2d84e9b3af6f48116ad1144d09b0aafeed21c58e6dd766ffea632f8eb8b0d9884baedda0d29d9c04530184bfcd
+  metadata.gz: f5fa95bca000bf57323f11026e5392b90fa71d22f606e77ddf49e87420afe1b128ef8313e3c51e6940bec15a177df3bc1ba7b81de532613c23cd394556a1c2f4
+  data.tar.gz: a4b24f06ec5dfa6ea7ed8a7476619eb580f4b606151e22a0921ad7a6760775e8ee5202e7832d7bfca2a8c470664e57daa0be0ac1944ca55d3b82e502a0c779de

data/AGENTS.md

@@ -1,10 +1,10 @@
 # Repository Guidelines
 
 ## 项目结构与模块组织
-- Ruby 源码位于 `lib/` 根目录，核心入口在 `lib/easyai.rb`，基础能力集中于 `lib/easyai/base`，命令定义在 `lib/easyai/command` 及其子目录（如 `claude.rb`、`gemini.rb`）。
-- 配置读取逻辑保存在 `lib/easyai/config`，认证与第三方服务脚本位于 `lib/easyai/auth`; 版本号定义于 `lib/easyai/version.rb` 并由 `easyai.gemspec` 消费。
-- CLI 启动脚本是 `bin/easyai`；打包产物默认输出在项目根目录。辅助脚本 `test_local.sh` 和 `release_remote.sh` 承担本地测试与正式发布，请保留可执行权限并在修改后记录变更。
-- 未来添加测试文件时，统一放在 `spec/` 目录，可按模块建立 `spec/command`、`spec/base` 等子目录，以便快速定位；示例数据建议放入 `spec/support/fixtures`。
+- Ruby 源码位于 `lib/` 根目录，核心入口在 `lib/easyai.rb`，基础能力集中于 `lib/easyai/base`（`file_crypto` / `system_info` / `cross_platform` / `version_checker` / `update_notifier`），命令定义在 `lib/easyai/command` 及其子目录（`claude.rb` / `gemini.rb` / `codex.rb` / `setup.rb` / `clean.rb` / `update.rb` / `utils.rb` + `utils/{encry,decry}.rb`，公共基类 `ai_tool_base.rb`）。
+- 本地配置门面位于 `lib/easyai/config/local_config.rb`（管理 `~/.easyai/config.json`）；版本号定义于 `lib/easyai/version.rb` 并由 `easyai.gemspec` 消费。
+- CLI 启动脚本是 `bin/easyai`；打包产物默认输出在项目根目录。辅助脚本位于 `script/` 目录：`install_local.sh`/`install_local.bat` 承担本地构建安装，`local_release.sh` 负责本地完整发布，`autoci_release.sh` 将构建推送交由 Gitee CI 完成；请保留可执行权限并在修改后记录变更。
+- 测试位于 `spec/` 目录，已按模块拆分子目录：`spec/config`、`spec/command`（`spec/base` 将于阶段 9.1 补全），公共助手与 fixture 位于 `spec/support`（含 `tmpdir_helper.rb` / `stdin_helper.rb` / `fixtures/`）。
 
 ## 架构概览
 - `EasyAI::EasyAIApp` 负责命令调度、启动横幅与版本检查，所有 CLI 子命令最终由 `EasyAI::Command` 树处理。
@@ -15,7 +15,7 @@
 - `bundle install`：安装 Gemfile 中的开发依赖（Rake、RSpec 等），首次克隆或更新依赖后必须执行。
 - `bundle exec rspec`：运行整个测试套件；可通过 `bundle exec rspec spec/command/claude_spec.rb` 定位单个文件调试，或使用 `--format documentation` 获取更详细输出。
 - `bundle exec rake build` 或 `gem build easyai.gemspec`：构建 gem 包，常用于发布前的本地验证；`bundle exec rake install` 可直接将构建产物安装到本地。
-- `./test_local.sh`：自动执行打包并安装到本地 Ruby 环境，适合冒烟回归；`./release_remote.sh` 覆盖提交流程、分支同步和 `gem push`，仅在确认要发布时运行，并保证当前分支已同步远程。
+- `./script/install_local.sh`：自动执行打包并安装到本地 Ruby 环境，适合冒烟回归；`./script/local_release.sh` 覆盖提交流程、分支同步和 `gem push`，仅在确认要发布时运行，并保证当前分支已同步远程；`./script/autoci_release.sh` 仅负责提交与打 tag，构建推送由 Gitee CI 处理。
 
 ## 语言与风格规范
 - 本项目要求所有代码、注释、提交信息与文档统一使用中文，PR 描述与讨论亦应遵循；如必须引用英文原文，请附中文解释，确保沟通无障碍。
@@ -24,10 +24,12 @@
 - 新增命令时，参照现有文件创建 `lib/easyai/command/<name>.rb`，并在 `lib/easyai.rb` 中显式 `require`，确保自动加载链条完整；必要时补充文档说明。
 
 ## 测试准则
-- 使用 RSpec 进行行为驱动测试，文件命名为 `<feature>_spec.rb`；`describe` 中强调用户视角，例如 CLI 参数解析或远程更新提示。
-- 对加密、配置清理等高风险逻辑，建立 fixture（建议放在 `spec/support/fixtures`）并测试成功与失败路径；必要时模拟外部命令退出码。
+- `spec/` 已建立，**发布前必跑 `bundle exec rspec` 全绿（硬性门槛）**；新增 / 修改功能遵循 TDD：先在 `spec/<模块>/` 下补测试 → 实现 → 全绿后提交。
+- 使用 RSpec 进行行为驱动测试，文件命名为 `<feature>_spec.rb`；`describe` 中强调用户视角，例如 CLI 参数解析、配置加载或版本更新提示。
+- 隔离副作用：涉及 `~/.easyai/config.json` 的测试统一通过 `with_isolated_home` 把 `ENV['HOME']` 指向 tmpdir；交互输入用 `with_stdin`，输出抓取用 `capture_stdout`（均在 `spec/support/`）。
+- 对加密、配置清理等高风险逻辑，建立 fixture（统一放在 `spec/support/fixtures`）并测试成功与失败路径；必要时模拟外部命令退出码。
 - 目标是保持修改行的单元测试覆盖率不下降；若引入重要分支逻辑，请添加针对性例子并在 PR 中说明覆盖情况。
-- 提交前至少运行一次 `bundle exec rspec`；若修改了打包或权限脚本，请额外执行 `./test_local.sh` 验证安装流程，并记录输出结果。
+- 若修改了打包或权限脚本，除 `bundle exec rspec` 外请额外执行 `./script/install_local.sh` 验证安装流程，并记录输出结果。
 
 ## 提交与合并请求规范
 - 提交消息遵循 `feat:`、`fix:`、`refactor:`、`res x.y.z` 等前缀，小写冒号后加空格，主题控制在 72 字符以内，正文补充动机与影响面。

data/CLAUDE.md

@@ -4,186 +4,271 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **重要说明：此项目的所有回答和交流都应该使用中文。**
 
+## 文档索引
+
+| 文档 | 说明 |
+|------|------|
+| [README.md](README.md) | 项目入口，安装与常用命令 |
+| [docs/需求文档.md](docs/需求文档.md) | 功能与非功能需求（v2.0） |
+| [docs/设计文档.md](docs/设计文档.md) | 架构、模块与关键流程（v2.0） |
+| [docs/plan.md](docs/plan.md) | v2.0 重构实施计划（任务拆解 + 决策摘要） |
+| [AGENTS.md](AGENTS.md) | 团队协作与提交规范 |
+
 ## 项目概述
 
-EasyAI 是一个 Ruby CLI 工具，作为 AI 命令行工具（Claude、Gemini、GPT）的包装器。它提供环境隔离和配置管理功能，允许用户使用预配置的 API 令牌和代理设置运行 AI 工具，而不会影响系统环境变量。项目还包含实用工具集合，如文件加密解密和配置导出功能。
+EasyAI 是一个 Ruby CLI 包装器，为 Anthropic Claude、Google Gemini、OpenAI Codex 三家命令行工具提供统一入口。v2.0 起聚焦**单机本地化**：通过 `~/.easyai/config.json` 集中管理多家工具与多平台凭证、代理配置；运行时把环境变量仅注入子进程，不污染当前 shell。
 
 ## 常用命令
 
-### 开发和测试
+### 开发与测试
+
 ```bash
-# 本地开发测试
-./test_local.sh              # 本地构建和安装 gem（自动检测版本和项目名称）
-ruby bin/easyai --help       # 开发期间测试
+bundle install                # 安装开发依赖
+bundle exec rspec             # 运行测试套件（发布前必跑）
+bundle exec rspec spec/config # 跑某个目录
+./script/install_local.sh     # 本地构建并安装 gem（冒烟）
+ruby -Ilib bin/easyai --help  # 开发期手测
+
+# 调试相关环境变量
+EASYAI_DEBUG=1 ruby bin/easyai claude        # 调试日志
+EASYAI_VERBOSE=1 easyai claude               # 详细输出
+EASYAI_SKIP_FORCE_UPDATE=1 easyai claude     # 跳过版本强制阻塞
+```
 
-# 发布流程
-./release_remote.sh          # 完整发布：git 操作、gem 构建和发布到 RubyGems
+### AI 工具启动
 
-# 手动 gem 操作
-gem build easyai.gemspec     # 构建 gem 包
-gem install easyai-x.x.x.gem # 安装特定版本
+```bash
+easyai claude                            # 多平台时交互选择
+easyai claude --platform=kimi            # 显式指定平台
+easyai claude ./adhoc.json               # 位置参数：用一次性 JSON 覆盖（单平台扁平 schema）
+easyai gemini                            # 同上
+easyai codex                             # 替代 v1.x 的 easyai gpt
+```
 
-# 测试加密解密功能
-EASYAI_TEST_PASSWORD=testdir123 easyai utils encry /tmp/test_dir
-EASYAI_TEST_PASSWORD=testdir123 easyai utils decry /tmp/test_dir_encrypted
+> 一次性 JSON 是**位置参数**（不是 `--config=` 选项）；该模式下 `--platform` 被忽略。
 
-# 调试模式
-EASYAI_DEBUG=1 ruby bin/easyai claude  # 启用调试信息输出
-EASYAI_SKIP_FORCE_UPDATE=1 easyai claude  # 跳过版本更新检查
-EASYAI_VERBOSE=1 easyai claude  # 启用详细输出模式
-```
+> 上面的 `kimi` 仅为示例。`--platform` 可用值由用户 `~/.easyai/config.json` 的 `platforms` 字典决定；新增平台模板的权威列表见 `lib/easyai/command/setup.rb` 的 `KNOWN_PLATFORMS`。**不要在文档或代码注释里硬编码平台名清单**（如 `claude_official / kimi / deepseek`），会随模板更新漂移。
 
 ### 配置管理
-```bash
-# 交互式设置 API 令牌和初始化
-easyai setup                   # 一键配置初始化
-easyai --setup                 # 旧版设置命令
 
-# 显示配置文件位置
-easyai --config
+```bash
+easyai setup                             # 全量交互（首次）/ 选择菜单 upsert（已存在）
+easyai setup --tool=claude               # 只配置某个工具
+easyai setup --add=kimi --tool=claude    # 追加或覆盖单平台
+easyai setup --remove=kimi --tool=claude # 删除单平台
+easyai setup --list                      # 脱敏概览
+easyai setup --edit                      # 用 $EDITOR 直接编辑
+easyai setup --reset                     # 删除现有 config.json 后重走交互
+```
 
-# 配置文件位置：~/.easyai/config.yml
+> 配置位置：`~/.easyai/config.json`（v2.0 起）。v1.x 的 `~/.easyai/config.yml` 不会自动迁移。
 
-# 使用本地配置文件
-easyai claude ./config.json    # 加载指定的 JSON 配置文件
+### 清理 AI CLI 缓存
 
-# 导出配置信息
-easyai utils export            # 自动生成文件名（使用邮箱地址）
-easyai utils export --output=config.json  # 指定输出文件名
-```
-
-### 清理功能
 ```bash
-easyai clean                   # 清理 Claude 配置缓存
-easyai clean all               # 清理所有配置（Claude、Gemini、GPT）
+easyai clean                # 默认清 claude
+easyai clean codex          # 单工具
+easyai clean all            # 三家一起清
+easyai clean all --dry-run  # 预览
+easyai clean all --force    # 跳过确认
 ```
 
+> `clean` 只清各 AI CLI 自身缓存（如 `~/.claude.json`），不会动 `~/.easyai/config.json`（重置 EasyAI 自身配置请用 `easyai setup --reset`）。
+
 ## 架构设计
 
-代码库采用基于 CLAide 的模块化架构：
-
-- **应用入口 (`lib/easyai.rb`)**：`EasyAIApp` 类负责启动标志显示、版本检查和命令执行
-- **主命令 (`lib/easyai/command.rb`)**：抽象基础命令，处理全局选项和帮助信息
-- **AI 工具子命令 (`lib/easyai/command/*.rb`)**：每个 AI 工具（claude、gemini、gpt）都有自己的命令类，继承自主命令
-- **工具命令 (`lib/easyai/command/utils/`)**：实用工具集合，包括文件加密解密（encry/decry）和配置导出（export）功能
-- **设置命令 (`lib/easyai/command/setup.rb`)**：一键配置初始化命令
-- **认证模块 (`lib/easyai/auth/`)**：处理 AI 工具的认证配置
-  - `authclaude.rb`：Claude 认证管理
-  - `jpsloginhelper.rb`：JPS 客户端登录助手，提供统一的 JPS 认证接口
-- **配置管理 (`lib/easyai/config/`)**：管理配置文件的加载、保存和远程下载
-  - `config.rb`：传统配置管理
-  - `easyai_config.rb`：新一代配置仓库管理，支持自动下载、更新和解密远程配置
-- **基础模块 (`lib/easyai/base/`)**：
-  - `file_crypto.rb`：文件加密解密核心实现（AES-128-ECB）
-  - `system_keychain.rb`：系统钥匙串访问
-  - `version_checker.rb`：版本检查和更新
-  - `update_notifier.rb`：更新通知显示
-- **环境隔离**：使用 Ruby 的 `exec()` 替换当前进程为目标 AI 工具，在注入环境变量的同时保持交互性
-
-### 环境变量注入
-每个子命令在调用 `exec()` 前合并环境变量：
-- Claude: `CLAUDE_CODE_OAUTH_TOKEN`
-- Gemini: `GOOGLE_API_KEY`, `GEMINI_API_KEY`
-- OpenAI: `OPENAI_API_KEY`
-- 代理: `HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy`, `https_proxy`
-
-### 认证优先级机制
-AI 工具的认证令牌获取优先级：
-1. **远程配置**：首先尝试通过 `EasyAIConfig` 下载并解密远程配置文件
-2. **本地配置**：如果指定了本地 JSON 配置文件，加载该文件
-3. **系统钥匙串**：从系统钥匙串获取（macOS Keychain）
-4. **环境变量**：从环境变量读取（如 `CLAUDE_CODE_OAUTH_TOKEN`）
-5. **交互输入**：最后提示用户输入并保存到配置文件
-
-### 配置管理系统
-
-**EasyAIConfig** - 配置仓库管理：
-- 自动从 `https://gitee.com/goodtools/EasyAISetting.git` 下载和更新配置仓库
-- 智能分支选择：测试环境使用 dev 分支，生产环境使用 master 分支
-- 智能解密：对比文件时间戳，按需解密
-- 自动清理：使用后自动清理解密文件
-
-**ConfigManager** - 业务配置逻辑：
-- 支持多工具类型（claude、gemini、gpt）
-- 支持多认证平台（claude_auth、aliqwen_auth、kimi_auth、deepseek_auth）
-- 智能平台选择和用户交互
-- 复杂加密配置的密码验证机制
+代码库基于 CLAide 框架，v2.0 起采用单层 LocalConfig + AIToolBase 抽象的精简架构：
+
+```
+应用入口     EasyAI::EasyAIApp           (lib/easyai.rb)
+   │  · 启动 banner   · 强制版本检查（update 子命令时跳过）
+   ▼
+命令层       EasyAI::Command 树          (lib/easyai/command/)
+   ├── AIToolBase (抽象)                 公共流程（platform / env / proxy / exec）
+   │     ├── Claude / Gemini / Codex    每子类约 15 行
+   ├── Setup / Clean / Update
+   └── Utils (抽象) ← Encry / Decry
+   ▼
+配置层       EasyAI::Config::LocalConfig (lib/easyai/config/local_config.rb)
+   · load / save / resolve_platform / upsert / delete
+   ▼
+存储层       ~/.easyai/config.json       (用户私有，chmod 600)
+```
+
+**基础层** `lib/easyai/base/`：
+- `file_crypto.rb` — AES-128-ECB 加解密（仅供 `utils encry/decry`）
+- `system_info.rb` — 跨平台 OS 判定与 `which_command`
+- `cross_platform.rb` — Windows/Unix 命令差异封装
+- `secret_masker.rb` — 敏感字段脱敏（key 名含 `TOKEN`/`KEY`/`SECRET`/`PASSWORD` 时，按"前 4 + ... + 后 4 + 长度"脱敏；`--list` / `print_platform_env` 共用）
+- `version_checker.rb` / `update_notifier.rb` — RubyGems 版本检查与升级提示
+
+详细的模块职责、数据流、错误降级矩阵见 [docs/设计文档.md](docs/设计文档.md)。
+
+### AI 工具运行流程
+
+`AIToolBase#run` 模板：
+
+1. argv 解析：`--platform` / `--verbose` / **第一个 `.json` 位置参数 → 本地覆盖** / 其余透传给目标 CLI
+2. `validate!` 检查 `exec_command` 在 PATH 中
+3. `resolve_config`：本地覆盖文件优先；否则走 `LocalConfig.resolve_platform`
+4. `print_platform_env`：打印当前生效的 `env` / `proxy`（敏感字段经 `Base::SecretMasker` 脱敏），让用户在 exec 前肉眼确认
+5. `build_environment`：merge `env` + `proxy`（同时设大小写 `HTTP_PROXY/http_proxy`）
+6. `export_environment_variables`：写入当前进程 ENV，**保护 `PATH/HOME/USER/SHELL` 不被覆盖**
+7. `exec(env, exec_command, *@passthrough_args)` 进程替换
+
+### 配置 schema (v2.0.0)
+
+```json
+{
+  "version": "2.0.0",
+  "<tool>": {
+    "platforms": {
+      "<platform_name>": {
+        "env":   { "<KEY>": "<VALUE>", ... },
+        "proxy": { "HTTP_PROXY": "...", "HTTPS_PROXY": "..." }
+      }
+    }
+  }
+}
+```
+
+`<tool>` ∈ `claude` / `gemini` / `codex`；`platforms` 字典即真相，runtime 不维护硬编码白名单。**`setup.rb` 的 `KNOWN_PLATFORMS` 是唯一的平台模板权威列表**（用于 `setup` 交互引导）；代码注释、option 描述、文档都应避免另写一份平台名清单，需要举例时统一以"见 `setup.rb` 的 `KNOWN_PLATFORMS`"代替。
 
 ### 版本更新机制
-- **启动检查**：在 `EasyAIApp#run` 中自动执行版本检查
-- **强制更新**：`check_force_update!` 方法会阻塞执行直到检查完成
-- **跳过机制**：设置 `EASYAI_SKIP_FORCE_UPDATE=1` 环境变量或使用 `--help`、`--version` 命令时自动跳过
-- **更新命令**：`easyai update` 执行 `gem update easyai`
+
+- `EasyAIApp#run` 启动时同步检查 RubyGems 版本，过期则阻塞
+- 跳过条件：`--help` / `--version` / `--check-update` / `EASYAI_SKIP_FORCE_UPDATE=1` / **子命令为 `update`**（避免死循环）
+- `easyai update` 用 `system('gem','update','easyai')` 实现（非 `exec`，便于打印结尾提示）
+
+## 测试 (RSpec)
+
+v2.0 起 `spec/` 目录已建立，**发布前必须 `bundle exec rspec` 全绿**（硬性门槛）。
+
+### 目录结构
+
+```
+spec/
+├── spec_helper.rb              关闭 colored2 染色、注入 lib/、加载 support/、include 助手
+├── support/
+│   ├── tmpdir_helper.rb        with_isolated_home / install_fixture_config
+│   ├── stdin_helper.rb         with_stdin / capture_stdout
+│   └── fixtures/               config_v2_full.json / config_v2_minimal.json / config_corrupted.json
+├── config/
+│   └── local_config_spec.rb    LocalConfig 单测
+├── command/
+│   ├── ai_tool_base_spec.rb    AIToolBase 模板流程
+│   ├── claude_spec.rb / gemini_spec.rb / codex_spec.rb
+│   ├── setup_spec.rb           交互 / upsert / 脱敏 / 删除
+│   └── clean_spec.rb           CACHE_PATHS / --dry-run / --force
+└── base/
+    └── file_crypto_spec.rb     加解密 round-trip（阶段 9.1 补全）
+```
+
+### 助手快速参考
+
+- `with_isolated_home { |home| ... }` — 把 `ENV['HOME']` 重定向到 tmpdir，块结束自动清理
+- `install_fixture_config(name, home)` — 把 `support/fixtures/<name>` 复制为 `<home>/.easyai/config.json`
+- `with_stdin('a', 'b') { ... }` — 把多行内容注入 `$stdin`
+- `capture_stdout { ... }` — 收集 `$stdout` 输出并返回字符串
+
+### TDD 工作流
+
+新增 / 修改功能必须遵循：
+
+1. 先在 `spec/<模块>/` 下补 / 改测试，本地 `bundle exec rspec spec/<模块>` 看到红
+2. 编写或修改实现，跑到全绿
+3. 跑全量 `bundle exec rspec` 确认无回归
+4. 再提交（提交说明里附上测试结果）
 
 ## 版本管理
 
-版本在 `lib/easyai/version.rb` 中定义，只需更新 `VERSION` 常量即可。
+版本在 `lib/easyai/version.rb` 中定义，更新 `VERSION` 常量即可。
 
 ### 发布流程
-`release_remote.sh` 脚本完成以下步骤：
-1. 提交所有未提交的更改（提交信息：`res 版本号`）
-2. 合并到 master 分支
-3. 构建和安装 gem
-4. 创建并推送 Git 标签（格式：v版本号）
-5. 发布到 RubyGems
+
+`script/local_release.sh`（本地完整发布）：
+1. 提交所有未提交更改
+2. 合并到 master
+3. 构建 + 安装 gem
+4. 创建并推送 Git 标签 `v<版本号>`
+5. `gem push` 到 RubyGems
+
+`script/autoci_release.sh`（CI 自动发布）：
+1. 本地完成提交 / 合并 / 打 tag / 推送
+2. Tag 推送触发 `.workflow/EasyAIRelease.yml` 在 Gitee CI 上构建并 `gem push`
 
 ## CLAide 框架注意事项
 
-### argv.remainder! 调用时机
-**重要**：`argv.remainder!` 必须在调用 `super` 之后执行。
+### `argv.remainder!` 调用时机
+
+**重要**：`argv.remainder!` 必须在 `super` 之后执行。
 
-正确示例：
 ```ruby
 def initialize(argv)
   super
-  @args = @argv.remainder!  # ✅ 正确：super 之后调用，使用 @argv
+  @args = @argv.remainder!  # ✅ super 之后调用，使用 @argv
 end
 ```
 
-原因：`argv.remainder!` 会消耗并清空 argv 中的所有剩余参数，如果在 `super` 之前调用，父类就无法获取 `--help` 等标志。
+原因：`argv.remainder!` 会消耗并清空 argv，若在 `super` 之前调用，父类无法获取 `--help` 等标志。
 
 ### 命令类继承结构
+
 ```
 CLAide::Command
   └── EasyAI::Command (abstract_command = true)
-        ├── Claude
-        ├── Gemini
-        ├── GPT
+        ├── AIToolBase (abstract)        ← 公共流程
+        │     ├── Claude
+        │     ├── Gemini
+        │     └── Codex
+        ├── Setup
         ├── Clean
         ├── Update
-        ├── Setup
-        └── Utils (abstract_command = true)
+        └── Utils (abstract)
               ├── Encry
-              ├── Decry
-              └── Export
+              └── Decry
 ```
 
 ## 添加新命令的标准流程
 
-1. 创建命令文件 `lib/easyai/command/newcmd.rb`
-2. 继承自 `EasyAI::Command`
-3. 设置 `self.summary` 和 `self.description`（使用中文）
-4. 实现 `initialize` 方法（注意 `super` 和 `argv.remainder!` 的顺序）
-5. 实现 `validate!` 方法（可选，用于验证参数）
-6. 实现 `run` 方法（主要逻辑）
-7. 在 `lib/easyai.rb` 中 require 新命令文件
+### 添加新的 AI 工具子命令
+
+1. 创建 `lib/easyai/command/<name>.rb`，继承 `EasyAI::Command::AIToolBase`
+2. 实现三个抽象方法：`tool_name` / `exec_command` / `install_hint`
+3. 设置中文 `self.summary` / `self.description`
+4. 在 `lib/easyai.rb` 中 `require 'easyai/command/<name>'`
+5. 在 `lib/easyai/command/setup.rb` 的 `KNOWN_PLATFORMS` 中添加该工具的平台模板
+6. 在 `lib/easyai/command/clean.rb` 的 `CACHE_PATHS` 中添加该工具缓存路径
+7. 更新 README、设计文档命令矩阵
+8. 在 `spec/command/` 下补测试
+
+### 添加普通子命令（非 AI 工具）
+
+1. 创建 `lib/easyai/command/<name>.rb`，继承 `EasyAI::Command`
+2. 设置 `self.summary` / `self.description`（中文）
+3. 实现 `initialize`（注意 `super` 与 `argv.remainder!` 顺序）
+4. 实现 `validate!`（可选）+ `run`
+5. 在 `lib/easyai.rb` 中 require
+6. 在 `spec/command/` 下补测试
 
 ### 输出格式规范
-各命令使用统一的输出格式：
-- `print_status(icon_text, detail)`：状态信息，图标左对齐，详情用 cyan 色
-- `print_success(message)`：成功信息，绿色勾号
-- `print_warning(message)`：警告信息，黄色警告符
-- `print_error(message)`：错误信息，红色叉号
+
+各命令使用统一输出格式：
+
+- `print_status(icon_text, detail)` — 状态信息，图标左对齐，详情用 cyan
+- `print_success(message)` — 绿色 ✓
+- `print_warning(message)` — 黄色 ⚠
+- `print_error(message)` — 红色 ✗
 
 ## 中文化要求
 
-- **所有用户界面必须使用中文**：包括命令描述、选项说明、错误信息、交互提示、状态信息
-- **所有文档必须使用中文**：README.md、代码注释、提交信息、API 文档
+- **所有用户界面必须使用中文**：命令描述、选项说明、错误信息、交互提示、状态信息
+- **所有项目文档必须使用中文**：README.md、代码注释、提交信息
 
-## JPS 认证集成
+## 安全约束
 
-项目集成了 JPS 客户端认证系统（`lib/easyai/auth/jpsloginhelper.rb`）：
-- **统一认证接口**：兼容原 JPSLogin 的接口，提供 `login()` 和 `get_username()` 方法
-- **配置文件管理**：通过 `EasyAIConfig` 自动获取 `jps_client_config.json` 配置文件路径
-- **自动配置下载**：如果配置文件不存在，会自动触发配置仓库的下载和解密
-- **用户名提取**：自动从认证令牌中提取用户名信息
+- `~/.easyai/config.json` 包含 API Key 明文，`save` 后会自动 `chmod 600`（非 Windows）
+- 敏感字段（key 名含 `TOKEN` / `KEY` / `SECRET` / `PASSWORD`）：
+  - 输入用 `IO#noecho` 不回显
+  - `--list` 输出做"前 4 + 后 4 + 长度"脱敏
+- 不得把 `~/.easyai/config.json` 上传到代码仓库或日志服务