quantex-cli

v0.29.0

Published

4 days ago

Agent-friendly lifecycle CLI for AI coding assistant CLIs: install, inspect, update, uninstall, run, and automate Codex, Claude Code, Gemini, Cursor, OpenCode, and more

Quantex CLI

统一管理 AI 编程助手 CLI 的安装、检查、更新、卸载与启动。

English | 简体中文

Quantex 是一个 human-friendly + agent-friendly 的 AI 编程助手 CLI lifecycle manager。它帮你把 Codex CLI、Claude Code、Gemini CLI、Cursor CLI、OpenCode、Antigravity CLI、Command Code、MiMoCode、Amp、Kilo CLI 等终端 coding agent 的安装、检查、更新、卸载、启动和自动化调用统一到一组稳定命令里：人可以直接用，脚本和 coding agent 也可以通过结构化输出可靠调用。本文默认使用更短的 qtx 作为推荐入口，quantex 是完全等价的完整命令名。

为什么用 Quantex

一个生命周期命令管理多个 AI 编程助手 CLI：安装、确保可用、查询状态、更新、卸载、启动。
适合脚本和 agent 调用：支持 --json、--output ndjson、--non-interactive、--dry-run 等适合机器读取的稳定契约。
记住真实安装来源：update --all 会优先按已记录来源分组更新，避免混合安装环境下误用更新方式。
支持通过可用的 Bun、npm、Homebrew、Cargo、Deno、mise、pip、uv、winget provider 管理 agent 安装。
支持 Quantex 自升级：Bun、npm、独立二进制安装来源都有对应升级路径。

Agent 快速接入

如果你正在让 coding agent 使用 Quantex，可以先安装仓库里的面向用户的 Quantex CLI skill：

npx skills add Drswith/quantex-cli --skill quantex-cli -a codex -a claude-code -a opencode -y

只想先查看这个仓库暴露了哪些 skills：

npx skills add Drswith/quantex-cli --list

随后让 agent 发现 Quantex 的稳定命令和输出契约：

npm exec --yes --package quantex-cli -- qtx capabilities --json
npm exec --yes --package quantex-cli -- qtx commands --json
npm exec --yes --package quantex-cli -- qtx schema --json

如果 agent 正在这个仓库内参与开发，请把下面这段作为启动提示：

Activate Superpowers if available, then read AGENTS.md, openspec/README.md, skills/quantex-agent-runtime/SKILL.md, and skills/quantex-cli/SKILL.md.
For non-trivial changes, use OpenSpec through the Quantex agent runtime.
Before finishing, run bun run lint, bun run format:check, and bun run typecheck.
If command behavior changed, also run bun run test.

仓库内置的面向用户的 Quantex CLI skill 位于 skills/quantex-cli/。它可以通过 skills.sh 的 npx skills add 从 GitHub 安装，但仍然以本仓库为发布源，不是单独的 npm package。单独的 skills/quantex-agent-runtime/ 是面向本仓库开发协作的 contributor runtime，不是普通外部用户的默认 skill；安装和同步方式见 skill 分发说明。

安装

使用 Bun：

bun add -g quantex-cli

使用 npm（Node.js 20+）：

npm i -g quantex-cli

已发布的 JS CLI 在安装后通过 Node 运行。Bun 仍然是受支持的安装与自升级路径，而独立二进制仍然是完全不依赖额外运行时的选项。

也可以从 GitHub Releases 下载独立二进制，或使用安装脚本：

curl -fsSL https://raw.githubusercontent.com/Drswith/quantex-cli/main/install.sh | sh

Windows PowerShell：

irm https://raw.githubusercontent.com/Drswith/quantex-cli/main/install.ps1 | iex

安装后推荐直接使用 qtx；如果你更偏好完整命令名，也可以使用完全等价的 quantex。

免安装试用

如果你的环境已经有 Node.js 20 或更高版本，可以先不做全局安装，直接试用只读命令：

bunx quantex-cli list
npx --yes --package quantex-cli qtx capabilities --json
npm exec --yes --package quantex-cli -- qtx inspect codex --json
pnpm --package=quantex-cli dlx qtx doctor

注意事项：

这些命令适合 list、info、inspect、doctor、capabilities、commands、schema 这类只读或发现型操作。
npx、npm exec、pnpm dlx 会通过 Node 运行已发布的 JS CLI，不要求环境里存在 bun。
bunx 仍然需要 Bun，因为它本身就是 Bun 提供的启动器。
install、ensure、update、uninstall、upgrade 这类会写状态或依赖已记录安装来源的操作，仍然建议先按上面的方式正常安装再执行。

快速开始

安装并启动一个 agent：

qtx install claude codex
qtx exec claude --install if-missing -- --help

确保 agent 可用，适合脚本或其他 agent 调用：

qtx ensure codex --json

查看 agent 状态和可执行入口：

qtx inspect codex --json
qtx resolve codex --json

更新单个 agent 或全部已安装 agent：

qtx update claude
qtx update --all

升级 Quantex 自身：

qtx upgrade
qtx upgrade --check
qtx upgrade --channel beta

提示：qtx upgrade 会跟随当前 Bun/npm 自升级实际使用的 registry。若你使用镜像源，镜像未同步最新发布时，当前源可安装版本可能会暂时落后于官方 npm。此时可稍后重试，或单独设置 selfUpdateRegistry / QTX_SELF_UPDATE_REGISTRY 让 Quantex 自升级使用不同的 registry，而不影响其他项目。

常用命令

| 推荐命令 | 等价长命令 | 作用 | |------|------|------| | qtx i <agent> [more-agents...] | quantex install <agent> [more-agents...] | 安装一个或多个 agent | | qtx ensure <agent> | quantex ensure <agent> | 幂等确保 agent 已安装 | | qtx u <agent> | quantex update <agent> | 更新 agent | | qtx update --all | quantex update --all | 更新所有已安装 agent | | qtx rm <agent> | quantex uninstall <agent> | 卸载 agent | | qtx ls | quantex list | 列出所有支持的 agent | | qtx info <agent> | quantex info <agent> | 查看 agent 详情 | | qtx inspect <agent> | quantex inspect <agent> | 查看结构化状态 | | qtx resolve <agent> | quantex resolve <agent> | 解析可执行入口 | | qtx exec <agent> -- [args...] | quantex exec <agent> -- [args...] | 以显式策略运行 agent | | qtx <agent> [args...] | quantex <agent> [args...] | 快捷启动 agent | | qtx capabilities | quantex capabilities | 查看当前环境能力 | | qtx commands | quantex commands | 查看稳定命令目录 | | qtx schema | quantex schema | 查看结构化输出 schema | | qtx config | quantex config | 管理配置 | | qtx doctor | quantex doctor | 检查环境和恢复建议 |

支持的 Agent

| Agent | 启动命令 | 描述 | |-------|----------|------| | Antigravity CLI | qtx antigravity | Google Antigravity 终端编程 Agent CLI | | Auggie CLI | qtx auggie | Augment 官方终端编程 Agent CLI | | Autohand Code CLI | qtx autohand | Autohand 官方自主终端编程 Agent CLI | | Amp | qtx amp | Sourcegraph 前沿 AI 编程 Agent CLI | | Claude Code | qtx claude | Anthropic 官方 AI 编程助手 CLI | | CodeBuddy Code | qtx codebuddy | 腾讯官方 AI 编程助手 CLI | | Codex CLI | qtx codex | OpenAI 官方 AI 编程助手 CLI | | Command Code | qtx commandcode | Command Code AI 编程助手 CLI | | Crush | qtx crush | Charmbracelet 终端 AI 编程 Agent CLI | | Cursor CLI | qtx cursor | Cursor AI 编程助手命令行工具 | | Deep Code CLI | qtx deepcode | Deep Code 终端编程 Agent CLI | | CodeWhale | qtx codewhale | DeepSeek 优先的终端编程 Agent | | Devin for Terminal | qtx devin | Cognition 本地编程 Agent CLI | | Droid | qtx droid | Factory AI 软件工程 Agent CLI | | ForgeCode | qtx forgecode | Antinomy AI 编程助手 CLI | | Gemini CLI | qtx gemini | Google 开源 AI 编程助手 CLI | | Genie | qtx genie | 通过 Deno 分发的终端 LLM agent | | GitHub Copilot CLI | qtx copilot | GitHub Copilot 命令行工具 | | Goose | qtx goose | Block 开源可扩展 AI Agent CLI | | Grok Build | qtx grok | xAI 终端编程 Agent CLI | | Hermes Agent | qtx hermes | Nous Research 自我进化的 AI Agent CLI | | JCode | qtx jcode | 面向多 session 工作流的高性能编程 Agent harness | | Junie CLI | qtx junie | JetBrains 官方 AI 编程 Agent CLI | | Kilo CLI | qtx kilo | Kilo 官方 AI 编程助手 CLI | | Kimi Code | qtx kimi | Moonshot AI 编程助手 CLI | | Kiro CLI | qtx kiro | Amazon AI 编程 Agent CLI | | MiMoCode | qtx mimo | 小米终端原生 AI 编程助手 CLI | | Mistral Vibe | qtx vibe | Mistral 开源终端编程助手 | | OpenClaw | qtx openclaw | OpenClaw 开源 AI Agent 运行时 CLI | | OpenHands CLI | qtx openhands | OpenHands 开源软件开发 Agent CLI | | OpenCode | qtx opencode | 开源 AI 编程 CLI | | oh-my-pi (OMP) | qtx omp | oh-my-pi coding agent CLI | | Pi | qtx pi | 极简可扩展的终端编程 Agent | | Qoder CLI | qtx qoder | Qoder 官方 AI 编程助手 CLI | | Qwen Code | qtx qwen | Qwen AI 编程助手 CLI | | Reasonix | qtx reasonix | DeepSeek 原生终端编程 Agent | | VTCode | qtx vtcode | 开源终端编程 Agent，提供稳健 shell 安全能力 |

如果你更偏好显式长命令，上表里的 qtx 都可以直接替换成 quantex。

面向自动化和 Agent

Quantex 的主线不是工作流编排平台，而是稳定的 agent lifecycle surface。自动化场景建议显式使用结构化参数：

quantex inspect claude --json --refresh
quantex install claude --json --dry-run
quantex exec claude --install if-missing --yes -- --help

常用契约：

--json / --output <human|json|ndjson> 控制输出格式。
--non-interactive、--yes、--quiet 适合 CI 和 agent 调用。
--dry-run 用于预览安装或更新计划。
--refresh / --no-cache 控制版本和 release 元数据缓存。
stdout 用于结构化结果，stderr 用于日志、警告和底层安装器输出。

如果你正在为上层 agent 集成 Quantex，优先从这些命令发现能力和类型：

quantex capabilities --json
quantex commands --json
quantex schema --json

配置与状态

用户配置位于 ~/.quantex/config.json：

{
  "defaultPackageManager": "bun",
  "npmBunUpdateStrategy": "latest-major",
  "selfUpdateChannel": "stable",
  "networkRetries": 2,
  "networkTimeoutMs": 10000,
  "versionCacheTtlHours": 6
}

defaultPackageManager 可以是 bun、npm 或 mise。它只会在目标 agent 暴露对应 managed installer 时调整 agent 安装方式排序，不会让 Quantex 自动替你安装缺失的 package manager。

selfUpdateRegistry 默认不设置。未设置时，Quantex 自升级会跟随当前 Bun/npm 实际使用的 registry。设置 selfUpdateRegistry 后，它只影响 Quantex 自身通过 Bun/npm 执行 qtx upgrade 的 registry 选择，不会修改你其他项目的默认安装源。一次性覆盖可使用环境变量 QTX_SELF_UPDATE_REGISTRY。

运行时状态位于 ~/.quantex/state.json。Quantex 会记录 agent 和自身的实际安装来源，用于 update --all 分组更新、doctor 恢复建议和 self upgrade 来源判断。

发布

Quantex 使用 release-please 维护 Release PR，发布说明以 GitHub Releases 为准：

维护者与 Agent 协作

如果你要参与开发或让 coding agent 在本仓库内工作，请从这些入口开始：

AGENTS.md：仓库级 agent 执行手册，包含流程守卫、验证门槛和 trigger-based pointers。
docs/README.md：ADR、runbook、session、postmortem 等项目文档入口。
openspec/README.md：OpenSpec / OPSX 变更流程。
docs/github-collaboration.md：Issue、PR、Discussion 协作流程。
skills/quantex-cli/SKILL.md：面向 agent 使用 Quantex 的 repo-native skill。
skills/quantex-agent-runtime/SKILL.md：面向本仓库开发协作的 agent runtime。

本地开发常用命令：

bun install
bun run dev
bun run lint
bun run format:check
bun run typecheck
bun run test
bun run test:container
bun run test:sandbox
bun run build

bun run test:container 是本地隔离验证的首选路径，适合在不安装 Modal 的情况下，用干净 Linux 环境验证对宿主机敏感的生命周期检查。它运行的是 Quantex 针对所选 agent 的真实 CLI lifecycle smoke flow，包括采用已预装 agent 和 Quantex 独立二进制自检，不是单元测试套件。bun run test:sandbox 会通过 Modal 运行同一套 smoke flow，适合验证远程传输或专用 GitHub Actions workflow。

License

Apache-2.0