用途：面向已安装多套 AI CLI 的用户，以可重复方式审计、预演（dry-run）或升级本地 AI 与开发者命令行工具，并输出日志与完成回执。不适用于只询问单个已知 CLI 如何安装、且无需版本审计或批量流程的场景。
主要能力：引擎为纯 Python 标准库单文件 scripts/upgrade_ai_clis.py（v2.2.0），由同名 bash 引擎逐行移植，对外契约（环境变量、表格列、状态字、退出码、日志命名与轮转）由仓级契约测试锁定。覆盖 codex、claude、agy、gemini（非消费级通道，需显式 TOOLS=gemini）、kimi、qwen、mmx、opencode、qodercli、deepcode、pi、cursor（仅版本审计）。自动探测 native/brew/npm 等安装通道并选择对应升级方式；输出含 TOOL、COMMAND、OLD、NEW、STATUS、NOTE 的表格，状态包括 INSTALLED、UPDATED、ALREADY_LATEST、NOT_INSTALLED、SKIP_DRY_RUN、MANUAL、FAILED。
使用方式：默认先 DRY_RUN=1 审计，例如 DRY_RUN=1 python3 skills/soia-env-ai-cli-upgrade/scripts/upgrade_ai_clis.py；升级全部支持工具则去掉 DRY_RUN。可用 TOOLS="codex,claude,agy" 限定范围。安装推荐整插件：claude plugin marketplace add soia-team/soia-open-skills 与 claude plugin install soia-env@soia；单技能可用 npx skills add soia-team/soia-open-env-skills -g -a '*' -s soia-env-ai-cli-upgrade -y。配置位于 ~/.config/soia-skills/soia-env-ai-cli-upgrade/config.yml，支持 schema_version: 2 及 LOG_DIR、TOOLS、NPM_PREFIX、CLAUDE_CHANNEL、AGY_INSTALL、AGY_INSTALL_DIR、CURSOR_UPGRADE_CMD 等变量。
安全与限制：默认保留 Claude 已装的 Homebrew cask，仅在单独授权后设 CLAUDE_CHANNEL=latest 迁移；不自动改 shell profile 或 PATH；缺失 agy 仅在 AGY_INSTALL=1 时安装；不写密钥、token、cookie 到日志；CURSOR_UPGRADE_CMD 视为用户提供代码，需明确批准。不首次安装缺失 CLI（agy 除外），不升级桌面应用，不判断新版本优劣，不代做认证。日志默认落 ${TMPDIR:-/tmp}/soia-env-ai-cli-upgrade/logs/ 并按 LOG_KEEP（默认 10）轮转。