easyai 1.7.0 → 2.0.0

data/README.md

@@ -1,75 +1,215 @@
 # EasyAI
 
-简化 AI 命令行工具使用的 Ruby 包装器，支持 Claude、Gemini 和 OpenAI。
+Claude / Gemini / Codex 三家 AI CLI 的本地化统一入口。通过单一 `~/.easyai/config.json` 管理凭证、代理与多平台切换；运行时把环境变量仅注入子进程，不污染当前 shell。
+
+- 单机本地配置，零远程依赖
+- 同一工具下保存多个平台，运行时一键切换
+- 凭证只入子进程 ENV，不写入 shell rc
+- 内置通用文件加解密工具 `utils encry / decry`
 
 ## 安装
 
 ```bash
-gem install easyai
+gem install easyai            # Ruby >= 3.0
+easyai setup                  # 首次运行：交互式生成本地配置
 ```
 
-或从源码安装：
+各家 AI CLI 由使用方预先安装：
+
+| 工具 | 安装命令 |
+|------|----------|
+| Claude | `npm install -g @anthropic-ai/claude-code` |
+| Gemini | `npm install -g @google/gemini-cli` |
+| Codex  | 参考 OpenAI Codex 官方文档 |
+
+## 快速开始
+
 ```bash
-gem build easyai.gemspec
-gem install easyai-*.gem
+easyai setup                   # 1. 选择工具 → 选择平台 → 填写凭证
+easyai claude                  # 2. 启动；多平台时交互选择
+easyai gemini --platform=google_official
+easyai codex
 ```
 
-## 快速开始
+## 命令参考
+
+### 启动 AI 工具
 
-### Claude
 ```bash
-easyai claude                    # 启动 Claude CLI
-easyai claude ./config.json      # 使用本地配置文件
+easyai claude                            # 列出 claude 平台并交互选择
+easyai claude --platform=kimi            # 显式指定平台
+easyai claude ./adhoc.json               # 一次性 JSON 覆盖（位置参数，单平台扁平 schema）
+easyai claude --verbose                  # 详细信息
+
+easyai gemini                            # 同上
+easyai codex                             # 替代 v1.x 的 easyai gpt
+```
+
+> 一次性 JSON 是**位置参数**（不是 `--config=` 选项）；该模式下 `--platform` 被忽略，未识别的位置参数透传给目标 CLI。
+
+单平台扁平 schema（`adhoc.json` 用）：
+
+```json
+{
+  "env":   { "ANTHROPIC_AUTH_TOKEN": "sk-..." },
+  "proxy": { "HTTP_PROXY": "http://127.0.0.1:7890" }
+}
 ```
 
-### Gemini
+### 配置管理
+
 ```bash
-easyai gemini                    # 启动 Gemini CLI
-easyai gemini chat               # 开始聊天会话
+easyai setup                                  # 首次：全量交互；已存在：进入 upsert 选择菜单
+easyai setup --tool=claude                    # 仅配置某个工具
+easyai setup --add=kimi --tool=claude         # 追加或覆盖单平台
+easyai setup --remove=kimi --tool=claude      # 删除单平台（platforms 删空时自动清理 tool 键）
+easyai setup --list                           # 脱敏概览
+easyai setup --edit                           # 用 $EDITOR / $VISUAL 直接编辑 config.json
+easyai setup --reset                          # 删除现有 config.json 后重走全量交互
 ```
 
-### OpenAI GPT
+> 敏感字段输入时 `IO#noecho` 不回显；`--list` 输出对 key 名包含 `TOKEN` / `KEY` / `SECRET` / `PASSWORD` 的字段做"前 4 + 后 4 + 长度"脱敏。
+
+### 清理 AI CLI 缓存
+
 ```bash
-easyai gpt                       # 启动 OpenAI CLI
-easyai gpt api chat.completions  # 调用 API
+easyai clean                  # 默认清 claude
+easyai clean codex            # 单工具
+easyai clean all              # 三家一起清
+easyai clean all --dry-run    # 仅预览将删除的路径
+easyai clean all --force      # 跳过交互确认
 ```
 
-## 实用工具
+清理目标（不含 `~/.easyai/config.json`，重置 EasyAI 自身配置请用 `easyai setup --reset`）：
+
+| 工具 | 路径 |
+|------|------|
+| claude | `~/.claude`、`~/.claude.json`、`~/.config/claude` |
+| gemini | `~/.gemini`、`~/.config/gemini` |
+| codex  | `~/.codex`、`~/.config/codex` |
+
+### 自更新
 
-### 文件加密解密
 ```bash
-easyai utils encry file.txt     # 加密文件
-easyai utils decry file.encrypted # 解密文件
+easyai update                 # 调用 gem update easyai
+easyai update --verbose       # 显示 gem 命令完整输出
 ```
 
-### 配置清理
+`update` 子命令本身会被启动版本检查跳过，避免"过期 → 强制更新 → 更新命令本身被阻塞"的死循环。
+
+### 通用加解密工具
+
 ```bash
-easyai clean                     # 清理 Claude 配置
-easyai clean all                 # 清理所有配置
+easyai utils encry <path>     # AES-128-ECB 加密单文件或目录
+easyai utils decry <path>     # 与 encry 配对解密
+```
+
+与 EasyAI 的配置体系彼此独立，可作为通用工具使用。
+
+## 配置 schema
+
+`~/.easyai/config.json`（v2.0）：
+
+```json
+{
+  "version": "2.0.0",
+  "claude": {
+    "platforms": {
+      "claude_official": {
+        "env": {
+          "ANTHROPIC_AUTH_TOKEN": "sk-ant-...",
+          "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
+        },
+        "proxy": {
+          "HTTP_PROXY": "http://127.0.0.1:7890",
+          "HTTPS_PROXY": "http://127.0.0.1:7890"
+        }
+      },
+      "kimi": {
+        "env": {
+          "ANTHROPIC_AUTH_TOKEN": "sk-...",
+          "ANTHROPIC_BASE_URL": "https://api.moonshot.cn/anthropic"
+        }
+      }
+    }
+  },
+  "gemini": {
+    "platforms": {
+      "google_official": { "env": { "GEMINI_API_KEY": "AIza..." } }
+    }
+  },
+  "codex": {
+    "platforms": {
+      "openai_official": { "env": { "OPENAI_API_KEY": "sk-..." } }
+    }
+  }
+}
 ```
 
-## 系统要求
+要点：
+
+- `platforms` 字典即真相：runtime 不维护硬编码白名单，可手编 `config.json` 添加任何自定义平台名（仅 `setup` 内置 `KNOWN_PLATFORMS` 用于交互引导）
+- `env` 透传不限制，可塞任意 KV（如 `ANTHROPIC_LOG=debug`）
+- `proxy` 可省略；同时设大小写 `HTTP_PROXY` / `http_proxy`
+- `PATH` / `HOME` / `USER` / `SHELL` 不会被 config 覆盖
+- `save` 后自动 `chmod 600`（非 Windows）
+
+详见 [docs/设计文档.md](docs/设计文档.md) 第 3 章。
 
-- Ruby >= 2.7.0
-- 对应的 AI CLI 工具：
-  - Claude: `npm install -g @anthropic-ai/claude-code`
-  - Gemini: `npm install -g @google/gemini-cli`
-  - OpenAI: `pip install openai`
+## 调试与环境变量
 
-## 特性
+| 变量 | 作用 |
+|------|------|
+| `EASYAI_DEBUG=1` | 启用调试日志 |
+| `EASYAI_VERBOSE=1` | 等价于 `--verbose` |
+| `EASYAI_SKIP_FORCE_UPDATE=1` | 跳过启动时的强制版本检查（网络不通时使用） |
 
-- 🔐 环境隔离，不影响系统配置
-- 🌐 支持远程配置自动下载
-- 🔄 透传所有参数到原生 CLI
-- 🛠 包含实用工具集
+## 从 v1.x 升级
+
+v2.0 是破坏性升级：
+
+- `easyai gpt` 重命名为 `easyai codex`（子进程命令也是 `codex`）
+- 配置位置：`~/.easyai/config.yml` → `~/.easyai/config.json`，**不会自动迁移**，需手动 `easyai setup` 重建（保留旧 yml 不会冲突）
+- 删除：远程加密配置仓库、JPS 登录、`easyai utils export`、`easyai setup --branch / --list-users`、Claude 官方认证环境检查、系统钥匙串密码缓存
+- 运行时依赖 `webrick` / `jpsclient` 已删除
+- Ruby 最低版本：`>= 3.0.0`
+
+升级步骤：
+
+```bash
+gem update easyai
+easyai setup                  # 重新交互配置
+```
+
+需保留 v1.x：`gem install easyai -v 1.7.0`。
 
 ## 开发
 
 ```bash
-./test_local.sh      # 本地测试
-./release_remote.sh  # 发布到 RubyGems
+bundle install                # 装开发依赖
+bundle exec rspec             # 运行测试套件（发布前必跑）
+./script/install_local.sh     # 本地构建并安装（冒烟）
 ```
 
+新增功能遵循 TDD：先在 `spec/` 下补测试 → 实现 → 全绿后提交。
+
+发布脚本：
+
+| 脚本 | 用途 |
+|------|------|
+| `script/local_release.sh` | 本地完整发布：提交 → 合并到 master → 打 tag → `gem push` |
+| `script/autoci_release.sh` | 仅本地提交 / 打 tag / 推送，由 Gitee CI 完成构建与推送 |
+
+## 文档索引
+
+| 文档 | 说明 |
+|------|------|
+| [docs/需求文档.md](docs/需求文档.md) | 功能与非功能需求（v2.0） |
+| [docs/设计文档.md](docs/设计文档.md) | 架构、模块与关键流程（v2.0） |
+| [docs/plan.md](docs/plan.md) | v2.0 重构实施计划 |
+| [CLAUDE.md](CLAUDE.md) | 给 Claude Code 的工程约定 |
+| [AGENTS.md](AGENTS.md) | 团队协作与提交规范 |
+
 ## License
 
-MIT
+MIT

data/easyai.gemspec

@@ -6,23 +6,26 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Wade']
   spec.email         = ['wade@example.com']
   
-  spec.summary       = 'Easy AI CLI tool wrapper'
-  spec.description   = 'A CLI tool that simplifies running AI tools like Claude, Gemini, and GPT with environment configuration'
+  spec.summary       = 'Claude / Gemini / Codex 三家 AI CLI 的本地化统一入口'
+  spec.description   = <<~DESC
+    EasyAI 是一个 Ruby CLI 包装器，为 Anthropic Claude、Google Gemini、OpenAI Codex 三家命令行工具提供统一入口。
+    v2.0 起聚焦单机本地化：无远程下发链路，通过单一 ~/.easyai/config.json 集中管理多家 CLI 与多平台凭证、代理；
+    运行时仅向子进程注入环境变量，不污染当前 shell。
+  DESC
   spec.homepage      = 'https://github.com/wade/easyai'
   spec.license       = 'MIT'
-  
-  spec.required_ruby_version = '>= 2.7.0'
-  
+
+  spec.required_ruby_version = '>= 3.0.0'
+
   spec.files         = Dir['lib/**/*', 'bin/*', '*.md', '*.gemspec']
   spec.bindir        = 'bin'
   spec.executables   = ['easyai']
   spec.require_paths = ['lib']
-  
+
   spec.add_dependency 'claide', '~> 1.0'
   spec.add_dependency 'colored2', '~> 3.1'
-  spec.add_dependency 'webrick', '~> 1.9'
-  spec.add_runtime_dependency 'jpsclient', '~> 1.4', '>= 1.4.0'
-  
+  spec.add_dependency 'base64', '~> 0.2'
+
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.0'

data/lib/easyai/base/secret_masker.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module EasyAI
+  module Base
+    # 敏感字段脱敏工具。
+    #
+    # 凡是 key 名包含 TOKEN / KEY / SECRET / PASSWORD（大小写不敏感）的环境变量，
+    # 在向 stdout 打印时都应通过本模块脱敏，避免 API Key 明文出现在终端历史 / 截图 / 日志。
+    #
+    # 脱敏规则：
+    #   - 长度 ≤ 8：完全隐藏，仅保留长度
+    #   - 长度 > 8：前 4 + "..." + 后 4 + 长度
+    module SecretMasker
+      SENSITIVE_KEY_PATTERN = /(TOKEN|KEY|SECRET|PASSWORD)/i.freeze
+
+      module_function
+
+      def sensitive_key?(key)
+        SENSITIVE_KEY_PATTERN.match?(key.to_s)
+      end
+
+      def mask(value)
+        s = value.to_s
+        len = s.length
+        return "*** (len=#{len})" if len <= 8
+
+        "#{s[0, 4]}...#{s[-4, 4]} (len=#{len})"
+      end
+
+      # 按 key 是否敏感，决定原样返回还是脱敏返回
+      def format_value(key, value)
+        return value.to_s unless value.is_a?(String)
+        return value unless sensitive_key?(key)
+
+        mask(value)
+      end
+    end
+  end
+end

data/lib/easyai/base/system_info.rb

@@ -1,11 +1,21 @@
+# frozen_string_literal: true
+
 require 'rbconfig'
 require 'etc'
 
 module EasyAI
   module Base
+    # 跨平台 OS 判定与命令检测。
+    #
+    # v2.0 起仅保留单机本地化运行所需能力：
+    #   - 平台判定：macos? / windows? / linux?
+    #   - PATH 检测：which_command(cmd)
+    #
+    # v1.x 中用于远程模式的方法（claude_auth_check_details / region_info /
+    # is_us_region? / is_english_environment? / shell_config_files 等）已删除。
     class SystemInfo
       class << self
-        # === 平台检测 ===
+        # 返回平台符号：:macos / :windows / :linux / :bsd / :unknown
         def platform
           @platform ||= detect_platform
         end
@@ -22,75 +32,7 @@ module EasyAI
           platform == :linux
         end
 
-        # === 用户和环境 ===
-        def current_user
-          @current_user ||= Etc.getlogin || ENV['USER'] || ENV['LOGNAME']
-        end
-
-        def current_shell
-          @current_shell ||= ENV['SHELL']&.split('/')&.last || 'bash'
-        end
-
-        def shell_config_files
-          @shell_config_files ||= detect_shell_config_files
-        end
-
-        # === 地区和语言检测（仅在需要时调用）===
-        def region_info
-          @region_info ||= detect_region_info
-        end
-
-        def is_us_region?
-          region_info[:is_us]
-        end
-
-        # 检查是否为英语环境
-        def is_english_environment?
-          info = region_info
-
-          case platform
-          when :macos
-            # macOS: 检查 locale 和首选语言
-            locale_english = info[:locale].to_s.start_with?('en_') || info[:locale].to_s.start_with?('en.')
-            apple_locale_english = info[:apple_locale].to_s.start_with?('en_')
-            first_lang_english = info[:apple_languages].to_s.start_with?('en')
-
-            # 任一为英语即可
-            locale_english || apple_locale_english || first_lang_english
-          when :windows
-            # Windows: 检查系统和用户地区
-            system_english = info[:system_locale].to_s.start_with?('en-')
-            user_english = info[:user_locale].to_s.start_with?('en-')
-            locale_english = info[:locale].to_s.start_with?('en_') || info[:locale].to_s.start_with?('en.')
-
-            # 任一为英语即可
-            system_english || user_english || locale_english
-          else
-            # Linux/其他: 检查 LANG 环境变量
-            locale = info[:locale].to_s
-            locale.start_with?('en_') || locale.start_with?('en.')
-          end
-        end
-
-        # 检查是否满足 claude_auth 的环境要求
-        def meets_claude_auth_requirements?
-          !windows? && is_us_region? && is_english_environment?
-        end
-
-        # 获取 claude_auth 环境检查详情
-        def claude_auth_check_details
-          {
-            os_supported: !windows?,
-            os_name: platform.to_s.capitalize,
-            is_us_region: is_us_region?,
-            region: region_info[:region],
-            is_english: is_english_environment?,
-            locale: region_info[:locale],
-            meets_requirements: meets_claude_auth_requirements?
-          }
-        end
-
-        # === 命令检测 ===
+        # 检测命令是否存在于 PATH。返回 true / false
         def which_command(cmd)
           if windows?
             system("where #{cmd} >nul 2>&1")
@@ -113,143 +55,15 @@ module EasyAI
           when /bsd/i
             :bsd
           else
-            # 回退到 RUBY_PLATFORM
             case RUBY_PLATFORM
-            when /darwin/
-              :macos
-            when /mswin|mingw|cygwin/
-              :windows
-            when /linux/
-              :linux
-            else
-              :unknown
-            end
-          end
-        end
-
-        def detect_shell_config_files
-          files = []
-
-          case current_shell
-          when 'zsh'
-            files << File.expand_path("~/.zshrc")
-          when 'bash'
-            bash_profile = File.expand_path("~/.bash_profile")
-            bashrc = File.expand_path("~/.bashrc")
-            files << (File.exist?(bash_profile) ? bash_profile : bashrc)
-          when 'fish'
-            fish_config = File.expand_path("~/.config/fish/config.fish")
-            files << fish_config
-
-            # 确保 fish 配置目录存在
-            fish_dir = File.dirname(fish_config)
-            unless File.exist?(fish_dir)
-              require 'fileutils'
-              FileUtils.mkdir_p(fish_dir)
+            when /darwin/    then :macos
+            when /mswin|mingw|cygwin/ then :windows
+            when /linux/     then :linux
+            else :unknown
             end
-          else
-            files << File.expand_path("~/.profile")
-          end
-
-          # 总是添加 ~/.profile 作为备份
-          profile_file = File.expand_path("~/.profile")
-          files << profile_file unless files.include?(profile_file)
-
-          files
-        end
-
-        def detect_region_info
-          case platform
-          when :macos
-            detect_macos_region
-          when :windows
-            detect_windows_region
-          when :linux
-            detect_linux_region
-          else
-            detect_generic_region
           end
         end
-
-        def detect_macos_region
-          locale = ENV['LANG'] || ENV['LC_ALL'] || ''
-          apple_locale = `defaults read -g AppleLocale 2>/dev/null`.chomp
-          apple_languages = `defaults read -g AppleLanguages 2>/dev/null`.chomp
-
-          # 解析语言列表
-          first_language = apple_languages.match(/"([^"]+)"/)&.captures&.first || ''
-
-          # 判断是否为美国地区
-          is_us = apple_locale.start_with?('en_US') ||
-                  locale.start_with?('en_US') ||
-                  first_language.start_with?('en-US')
-
-          {
-            locale: locale,
-            apple_locale: apple_locale,
-            apple_languages: first_language,
-            region: apple_locale.split('_').last || 'Unknown',
-            is_us: is_us,
-            platform: 'macOS'
-          }
-        end
-
-        def detect_windows_region
-          locale = ENV['LANG'] || ''
-
-          # Windows PowerShell 命令获取地区
-          system_locale = `powershell -Command "Get-WinSystemLocale | Select-Object -ExpandProperty Name" 2>nul`.chomp
-          user_locale = `powershell -Command "Get-Culture | Select-Object -ExpandProperty Name" 2>nul`.chomp
-
-          # 判断是否为美国地区
-          is_us = system_locale.start_with?('en-US') ||
-                  user_locale.start_with?('en-US') ||
-                  locale.start_with?('en_US')
-
-          {
-            locale: locale,
-            system_locale: system_locale,
-            user_locale: user_locale,
-            region: (system_locale.split('-').last || user_locale.split('-').last || 'Unknown'),
-            is_us: is_us,
-            platform: 'Windows'
-          }
-        end
-
-        def detect_linux_region
-          locale = ENV['LANG'] || ENV['LC_ALL'] || ''
-
-          # 尝试读取 /etc/locale.conf
-          locale_conf = File.exist?('/etc/locale.conf') ? File.read('/etc/locale.conf').strip : ''
-
-          # 使用 localectl 命令
-          system_locale = `localectl status 2>/dev/null | grep "System Locale" | cut -d= -f2`.chomp
-
-          # 判断是否为美国地区
-          is_us = locale.start_with?('en_US') ||
-                  system_locale.start_with?('en_US') ||
-                  locale_conf.include?('en_US')
-
-          {
-            locale: locale,
-            system_locale: system_locale || locale_conf,
-            region: locale.split('_').last&.split('.').first || 'Unknown',
-            is_us: is_us,
-            platform: 'Linux'
-          }
-        end
-
-        def detect_generic_region
-          locale = ENV['LANG'] || ENV['LC_ALL'] || 'Unknown'
-
-          {
-            locale: locale,
-            region: locale.split('_').last&.split('.').first || 'Unknown',
-            is_us: locale.start_with?('en_US'),
-            platform: 'Unknown'
-          }
-        end
       end
     end
   end
-end
+end