把脚本全迁到 CLI-Anything 后,我踩了 6 个坑:权限、沙箱与路径地狱
把脚本全迁到 CLI-Anything 后,我踩了 6 个坑:权限、沙箱与路径地狱
把散落在 ~/bin、/usr/local/bin、项目根目录甚至 README 里的几十个脚本,统一迁到 CLI-Anything 体系下,听起来是一劳永逸的解法:一个 cli-hub install 装完所有工具,一套 --json 输出喂给 Agent,一条命令就能让 AI 接管 Blender、GIMP、LibreOffice 乃至 Calibre。社区里对这套"命令行调度框架"的讨论热度不减——统一入口、YAML 声明式配置、安全沙箱执行、配置分层(CLI 参数/环境变量/配置文件)被反复提及,公共注册表 也确实把 pip、npm、brew、bundled 四类来源的 CLI 全部纳管。
然而真实迁移过程中,真正消耗时间的从来不是"装不装得上",而是迁完之后的权限、沙箱与路径问题。我整理了迁移中踩过的 6 个坑,全部对应仓库源码里的真实行为——它们不是玄学,每一个都能在 cli-hub 或 HARNESS.md 中找到根源。
坑 1:cli-hub install 成功了,命令却不在 PATH 上
这是迁移后最先遇到的怪事。cli-hub install gimp 返回 Installed ...,但紧接着 cli-hub launch gimp 在 subprocess.run 时直接抛 FileNotFoundError。
根源在 installer.py 的安装策略分派逻辑。_install_strategy() 会根据 registry 条目返回 pip、npm、uv、command、bundled 五种策略之一,而每种策略对环境的前置依赖完全不同:
def _install_strategy(cli):
strategy = cli.get("install_strategy")
if strategy:
return strategy
if cli.get("_source", "harness") == "harness":
return "pip"
if cli.get("npm_package") or cli.get("package_manager") == "npm":
return "npm"
if cli.get("package_manager") == "uv":
return "uv"
...
_pip_install 用 sys.executable -m pip install 装进当前解释器的 site-packages,命令落在该解释器的 bin 目录;_npm_install 装进 Node 全局目录;_uv_install 更是要求机器上先有 uv,否则直接返回一段安装提示。换句话说,同一个 cli-hub install 命令,到底装进哪个目录,完全取决于 registry 条目声称的包管理器和你的环境里哪个解释器先被解析到。
我的排查路径是:先 cli-hub info <name> 看 entry_point 与 strategy,再用 doctor_matrix() 那套"记录为已安装但 entry_point 不在 PATH"的判定逻辑去核对。仓库里 matrix doctor 就是为此设计的——它在 installer.py 里对每个成员做 _command_exists(entry_point) 检查,命中就把状态标成 broken,并给出 cli-hub install <name> 的修复命令。坑 1 的教训:迁移前先统一解释器与包管理器,pip 装的命令和 npm 装的命令不会自动出现在同一条 PATH 上。
坑 2:系统包依赖是"硬依赖",缺了直接报错——沙箱误伤的起点
CLI-Anything 的每个 harness 都默认假定上游软件已安装。以 calibre_backend.py 为例,定位 calibredb 时一旦 shutil.which 落空,直接 raise RuntimeError 并附上 apt/brew 安装指引;qgis_backend.py 的 find_qgis_process() 同样如此。这是 HARNESS.md 里明文写死的铁律:
The real software is a hard dependency. The CLI MUST invoke the actual application for rendering and export. Do NOT gracefully degrade to a fallback library.
这本身是好的工程纪律,但在沙箱环境里就成了误伤重灾区。如果你用容器或 bwrap 这类限制性沙箱跑迁移后的 CLI,沙箱内的 PATH 裁剪、$HOME 重定向、只读文件系统会让两个前提同时崩溃:一是 shutil.which 找不到上游二进制(因为 PATH 被清空),二是 harness 运行时想写的 ~/.cli-hub/installed.json、matrix_state.json(见 installer.py 顶部的 INSTALLED_FILE、MATRIX_STATE_FILE)落到沙箱外的真实家目录。
我最终在沙箱配置里显式放行 cli-anything-*、calibredb、qgis_process 等二进制,并把 $HOME/.cli-hub 和 $HOME/.codex(CC Switch 迁移时写配置的目标,见下文坑 6)挂载为可写卷。坑 2 的教训:迁移进沙箱前,先列一份"harness 需要的宿主能力清单"(上游软件、家目录写入点),而不是盲信"框架自带安全沙箱执行"的宣传。
坑 3:_resolve_cli 的三级回退,把测试和 Agent 引向不同的命令
迁移后我同时用两种方式调用 CLI:CI 里跑 pytest,Agent 里直接敲命令。结果两边行为不一致——CI 全绿,Agent 却偶发 command not found。
原因在 harness 测试的统一解析器 HARNESS.md 中定义的 _resolve_cli()。它的解析顺序是:先找 sys.executable 同级目录下的同名兄弟命令,再 shutil.which 全局 PATH,最后回退到 python -m cli_anything.<software>;只有当环境变量 CLI_ANYTHING_FORCE_INSTALLED=1 时才强制要求 PATH 上的已安装命令。QGIS 的实际实现见 test_full_e2e.py。
force = os.environ.get("CLI_ANYTHING_FORCE_INSTALLED", "").strip() == "1"
sibling = Path(sys.executable).parent / name
if sibling.exists():
return [str(sibling)] # 1. 兄弟命令
path = shutil.which(name)
if path:
return [path] # 2. PATH 上的已安装命令
if force:
raise RuntimeError(...)
return [sys.executable, "-m", module] # 3. 模块回退
这解释了那个诡异现象:CI 里没设置 CLI_ANYTHING_FORCE_INSTALLED,测试静默走模块回退,测的是源码;Agent 走的是 PATH 上的安装产物,测的是打包结果。版本不同步时,两套行为自然不一致。坑 3 的教训:迁移后的测试与发布必须统一加 CLI_ANYTHING_FORCE_INSTALLED=1,让 CI 测的就是 Agent 跑的同一个二进制;同时不要在 subprocess 测试里硬编码 cwd——HARNESS 明确规定"installed commands must work from any directory"。
坑 4:多语言执行器的路径语义不同——Windows 的 cygpath 地狱
CLI-Anything 的 harness 不只调 Python。按 HARNESS.md 的"应用此方法到其他软件"表格,后端执行器五花八门:LibreOffice 用 libreoffice --headless,Blender 用 blender --background --python script.py,Inkscape 用 inkscape --actions=...,Shotcut/Kdenlive 用 melt,浏览器自动化走 npx @apireno/domshell。跨平台时,路径语义在解释器之间完全不一致:bash 下的 /c/Users/...、Git Bash 的 /tmp 映射、npm 全局目录、Windows 反斜杠路径,在 Click 参数、subprocess 参数和 JSON 输出里会被不同执行器以不同方式解释。
仓库对这个坑的处理是显式的:README 的 Windows 注意事项写明 Claude Code 通过 bash 执行命令,Windows 下必须装 Git for Windows(含 bash 和 cygpath)或 WSL,否则报 cygpath: command not found;setup-cli-anything.sh 在开头就做 Windows bash 环境检测,发现缺 cygpath 直接红字告警。我的迁移教训是:把路径参数统一在 harness 层解析成绝对路径(Path(path).expanduser().resolve() 是 backend 层的标配,见 qgis_backend.py 的 _normalize_path),不要依赖单个执行器的相对路径语义;跨平台测试要专门覆盖路径转换路径。
坑 5:配置分层的"最后一层"是环境变量,它可能来自你没想到的地方
CLI-Anything 类框架的配置遵循"CLI 参数 > 环境变量 > 配置文件"的优先级。多数时候这是优点,但迁移脚本时它制造了最难排查的隐性冲突:某个行为差异既不在参数里、也不在配置文件里,你改哪儿都不生效——因为它来自环境变量。
仓库里可以找到大量证据证明环境变量是刻意设计的一等公民:CI 里的 CLI_ANYTHING_FORCE_INSTALLED(坑 3)、QGIS backend 的 QGIS_PREFIX_PATH、测试夹具里 monkeypatch 的 HOME/USERPROFILE/QT_QPA_PLATFORM、calibre_backend.py 为稳定解析输出而强制注入的 CALIBRE_OVERRIDE_LANG=en。特别是 HOME 重定向:QGIS 测试通过临时 HOME 隔离用户状态,这意味着生产环境里 HOME 一旦被容器编排或 CI 改写,所有写到 ~/.cli-hub 的安装状态和 session 文件都会静默换个位置。
我的调试方法是二分法:先 env | grep -i -E 'qgis|calibre|cli_anything|home' 列出可疑变量,再逐个清空对比行为。坑 5 的教训:排查行为差异时,把"环境变量"当作配置层级的最高优先级来怀疑,而不是最后一步;Agent 执行时尤其要注意 HOME 与 locale 类变量对输出解析的影响——Calibre 强制英文输出就是为解析稳定性做的反例式设计。
坑 6:写宿主配置文件的 harness 会撞上权限与沙箱双墙
这是最隐蔽的一个:不是所有 CLI 都只读自己的目录。cc-switch 这类 harness 会直接改写 AI 编码工具的配置。在 test_core.py 里可以看到它的 _write_live_config("codex", db) 会向 $HOME/.codex/config.toml 写入并合并内容,测试里刻意构造了 sandbox_mode = "workspace-write"、provider、mcp_servers 等片段来验证"保留用户已有配置、只做增量合并"。这意味着迁移脚本后,一条 CLI 命令就可能触碰 Codex、Claude Code 等工具的家目录配置——在只读沙箱里直接 PermissionError,在普通用户下可能没有权限,在 sudo 下又可能写进 root 的家目录。
更麻烦的是这类写入通常还带并发风险。HARNESS 专门给 session 保存定义了 _locked_save_json 模式(session-locking.md):禁止裸 open("w") + json.dump(),因为 open("w") 会在加锁前就截断文件;正确做法是 open("r+") 后先 flock(LOCK_EX),再在锁内 seek(0) + truncate() + dump,Windows 等无 fcntl 平台则优雅降级为不加锁。QGIS 的 session.py 已按此实现。坑 6 的教训:迁移前逐条核对 harness 会写哪些宿主文件;对写 $HOME 配置的命令,要么给沙箱开白名单写挂载,要么用独立 HOME 隔离;session 类文件务必走加锁保存模式,否则多 Agent 并发时 json 文件会被截断写坏。
附:一份避坑清单
把这 6 个坑压缩成一张迁移前 checklist:
- 统一运行时:先确认所有 CLI 走同一条
pip/npm/uv链路,用cli-hub info核对entry_point与strategy,再决定PATH需要包含哪些 bin 目录;装完用matrix doctor自动体检。 - 列宿主依赖清单:逐条记录每个 harness 需要的上游软件(LibreOffice、Blender、
qgis_process、calibredb、sox…)与家目录写入点(~/.cli-hub、~/.codex、session 文件),沙箱按清单开白名单,而不是整体放行。 - 测试与运行同构:CI 一律
CLI_ANYTHING_FORCE_INSTALLED=1,杜绝模块回退;subprocess 测试不设cwd,确保"任何目录都能跑"是真实承诺。 - 路径全部绝对化:跨执行器传递路径前统一
expanduser().resolve();Windows 环境预先验证cygpath,别让 Git Bash 的路径映射在渲染环节炸掉。 - 怀疑环境变量:行为差异查不出参数与配置文件原因时,把
HOME、locale、QGIS_PREFIX_PATH之类的变量当作头号嫌疑人。 - 写配置要增量 + 加锁:会改写宿主配置的 CLI 只做合并式更新;session 持久化用
_locked_save_json,拒绝裸截断写。
最后补充一个心态层面的建议:CLI-Anything 的价值在于把"脚本散落、风格不一"的存量世界收敛成结构化命令树,但收敛不等于自动解决环境差异——坑 1 到坑 6 的本质,都是"框架负责调度语义,环境责任仍在你这一侧"。把这份清单跑一遍,迁移才算真正完成。