agent-cli

一个用于集中管理多个 npm 全局 AI CLI 工具（如各大厂商的 Agent 命令行）的 Bash 脚本，支持交互式菜单选择、批量检查/更新/安装/卸载，并将统一的包列表与顺序持久化到本地配置。

用途

统一管理分散在 @qoder-ai/qodercli、@openai/codex、@anthropic-ai/claude-code 等包中的命令行工具，避免逐个手动 npm install -g。典型场景：

• 一次性检查所有 Agent CLI 是否有新版本（不安装）
• 在非交互环境（如 CI / 定时任务）中批量更新
• 在交互菜单中挑选要更新的包、调整顺序、增删包并保持配置

默认包

脚本内置 DEFAULT_PACKAGES（agent-cli.sh:4）：

@qoder-ai/qodercli
@qodercn-ai/qoderclicn
@openai/codex
@anthropic-ai/claude-code
@mimo-ai/cli

配置文件

所有用户状态持久化在 ~/.config/agent-cli/：

文件	作用
packages.conf	用户追加的自定义包列表
disabled.conf	被禁用的默认包列表（删除默认包不会真正删除，只是禁用）
order.conf	当前展示/操作顺序

脚本首次写入时自动 mkdir -p "$CONFIG_DIR"。

用法

agent-cli [选项]

选项:
  -c, --check           仅检查最新版本，不安装（非交互）
  -y, --yes             非交互，直接检查并更新默认+自定义包列表
  --add PKG             非交互，追加一个包并持久化（可多次使用）
  --delete PKG          非交互，删除一个包（默认或自定义）并持久化（可多次使用）
  -h, --help            显示帮助

无参数: 进入交互式菜单（空格勾选，↑/↓ 移动，←/→ 调整顺序，
         a 追加(持久化)，d 删除(任意包)，c 仅检查，Enter 更新）

示例

agent-cli                 # 进入交互菜单
agent-cli -c              # 仅打印各包最新版本对比
agent-cli -y              # 非交互，直接把所有选中包更新到最新
agent-cli --add @foo/cli  # 追加自定义包并写入 packages.conf
agent-cli --delete @openai/codex  # 从列表移除（默认包进 disabled.conf）

实现说明

脚本为纯 Bash（依赖 bash、npm），不引入第三方库。核心实现可划分为几个部分：

1. 全局状态（agent-cli.sh:11-19）

• packages / selected：当前包列表与对应的勾选状态（1 选中 / 0 取消），两数组下标对齐。
• custom / disabled：分别记录用户自定义包、被禁用的默认包，用于持久化判断。
• 标志位：CHECK_ONLY、NONINTERACTIVE、ADD_PKGS、DEL_PKGS。

2. 参数解析（agent-cli.sh:37-49）

使用 while [[ $# -gt 0 ]] + case 逐参数解析。--add/--delete 支持多次指定；未知参数直接报错退出。

3. 加载与持久化

• load_packages（agent-cli.sh:67）：读取三个配置文件，先过滤禁用项，再加入默认包与自定义包，最后按 order.conf 重排顺序。重排采用「先按 order 收集、再补剩余」的策略，保证配置顺序优先。
• save_custom / save_disabled / save_order（agent-cli.sh:111-136）：每次状态变更后清空重写对应文件（ : > file 截断后逐行 echo 追加）。

4. 增删包

• add_pkg（agent-cli.sh:138）：去重后加入 packages 与 custom，并从 disabled 中解除（如果存在），随后保存。
• delete_pkg_name（agent-cli.sh:159）：从列表中移除。若是自定义包则从 custom 删除；若是默认包则加入 disabled（软删除，保留默认定义）。

5. 版本获取

• get_installed_version（agent-cli.sh:185）：npm list -g <pkg> --depth=0 配合 grep/sed 提取已装版本。
• get_latest_version（agent-cli.sh:189）：npm view <pkg> version 获取远程最新版。
• 两者失败均返回空串，由调用方区分「未安装 / 无法获取 / 可更新」。

6. 检查与执行

• check_only（agent-cli.sh:193）：遍历选中包，输出 [未安装]/[可更新]/[最新]/[ERROR] 状态，不执行安装。
• run（agent-cli.sh:216）：对未安装或版本不一致的包执行 npm install -g <pkg>@latest，失败仅提示不中断。
• 这两个函数开头都 stty -echo 并在 RETURN/EXIT/INT/TERM 时 stty echo 恢复终端回显，避免交互混乱；结尾 while IFS= read -t 0 ... 清空残留输入缓冲。

7. 交互菜单

• read_line（agent-cli.sh:245）：自行逐字符读取用户输入，Esc 取消、退格删除，用于追加包名。
• checklist（agent-cli.sh:274）：方向键移动光标、空格切换勾选、左右键交换相邻包顺序（即时 save_order）、a 追加、d 删除、c 仅检查、Enter 确认后退出菜单进入 run。

8. 入口调度（agent-cli.sh:343-361）

1. load_packages 载入状态；
2. 若存在 --add/--delete，先批量处理并保持（除非同时 -y，否则直接退出）；
3. 否则：-c 走 check_only，-y 走 run，无参则 checklist 后 run。

依赖与限制

• 依赖 bash（非 sh）、npm 及可访问的 npm registry。
• 配置写入 $HOME/.config/agent-cli/，跨用户/环境不共享。
• get_* 版本解析依赖 npm 文本输出格式，升级 npm 后可能需要相应调整。