EasyAI

Claude / Gemini / Codex 三家 AI CLI 的本地化统一入口。通过单一 ~/.easyai/config.json 管理凭证、代理与多平台切换；运行时把环境变量仅注入子进程，不污染当前 shell。

• 单机本地配置，零远程依赖
• 同一工具下保存多个平台，运行时一键切换
• 凭证只入子进程 ENV，不写入 shell rc
• 内置通用文件加解密工具 utils encry / decry

安装

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 官方文档

快速开始

easyai setup                   # 1. 选择工具 → 选择平台 → 填写凭证
easyai claude                  # 2. 启动；多平台时交互选择
easyai gemini --platform=google_official
easyai codex

命令参考

启动 AI 工具

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 用）：

{
  "env":   { "ANTHROPIC_AUTH_TOKEN": "sk-..." },
  "proxy": { "HTTP_PROXY": "http://127.0.0.1:7890" }
}

配置管理

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 后重走全量交互

敏感字段输入时 IO#noecho 不回显；--list 输出对 key 名包含 TOKEN / KEY / SECRET / PASSWORD 的字段做"前 4 + 后 4 + 长度"脱敏。

清理 AI CLI 缓存

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

自更新

easyai update                 # 调用 gem update easyai
easyai update --verbose       # 显示 gem 命令完整输出

update 子命令本身会被启动版本检查跳过，避免"过期 → 强制更新 → 更新命令本身被阻塞"的死循环。

通用加解密工具

easyai utils encry <path>     # AES-128-ECB 加密单文件或目录
easyai utils decry <path>     # 与 encry 配对解密

与 EasyAI 的配置体系彼此独立，可作为通用工具使用。

配置 schema

~/.easyai/config.json（v2.0）：

{
  "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 第 3 章。

调试与环境变量

变量	作用
EASYAI_DEBUG=1	启用调试日志
EASYAI_VERBOSE=1	等价于 --verbose
EASYAI_SKIP_FORCE_UPDATE=1	跳过启动时的强制版本检查（网络不通时使用）

从 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

升级步骤：

gem update easyai
easyai setup                  # 重新交互配置

需保留 v1.x：gem install easyai -v 1.7.0。

开发

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	功能与非功能需求（v2.0）
docs/设计文档.md	架构、模块与关键流程（v2.0）
docs/plan.md	v2.0 重构实施计划
CLAUDE.md	给 Claude Code 的工程约定
AGENTS.md	团队协作与提交规范

License

MIT