For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/zh/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/zh/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/zh/reference/cli.md.
agent-bundle
  • 简体中文

      • 命令行 

      npx agent-bundle --help
npx agent-bundle --version

      命令

      命令用途
      agent-bundle dev在 loopback 上提供打包好的开发 workbench。
      agent-bundle dev proxy把宿主的 stdio MCP 流量桥接到正在运行的开发服务器。
      agent-bundle build构建一份已校验的 Agent Bundle 产物。
      agent-bundle prepack构建并校验 npm pack 清单。
      agent-bundle install <host>把已构建的捆绑包安装进受支持的宿主。
      agent-bundle doctor在不做任何改动的前提下检查宿主安装与运行时端点。
      agent-bundle validate校验项目源码或某一份产物。
      agent-bundle eval针对已构建产物运行确定性或原生 eval 套件。
      agent-bundle eval compare对比两次已持久化的 eval 运行。
      agent-bundle inspect检查规范化后的 target 与适配器计划。
      agent-bundle mcp list / invoke / run从产物中操作某个 MCP 服务器。
      agent-bundle hooks list / simulate检查并模拟生成的钩子。

      共享选项组

      源码命令 —— build、prepack、validate、eval：

      选项默认值含义
      --root <root>process.cwd()项目根目录。
      --config <path>——相对 --root 的配置文件。
      --mode <mode>production配置模式。
      --target <target>全部已配置要选择的 target。可重复。
      --json关闭写出一份机器可读的 JSON 文档。

      产物命令 —— mcp list、mcp invoke、mcp run、hooks list、hooks simulate：同样的 --root、--config、--mode 与 --json，外加 --artifact <path>（精确使用某一份已构建产物）与 --target <target>（选择产物 target）。对 mcp list、mcp invoke、mcp run 与 hooks simulate 来说，--target 是必填的。

      dev

      选项默认值含义
      --root <root>process.cwd()项目根目录。
      --port <port>临时端口Loopback TCP 端口。
      --agent-api / --no-agent-api配置中的 dev.agentApi启用或禁用 /mcp 上经过认证的 Agent API。
      --install-host <host>无安装并重新同步一个开发期宿主。可重复；取值为 claude、codex 或 cursor。
      --open / --no-open--no-open前台服务器启动后是否打开 workbench。

      dev 在前台运行，并在收到终止信号时关闭会话。见 开发者 Workbench。

      dev proxy

      选项默认值含义
      --server <server>必填生成的 MCP 服务器名。
      --target <target>portable包含该 MCP 服务器的生成式 target。
      --url <url>自动发现显式指定 loopback 开发服务器 origin。

      proxy 从父命令 dev 继承 --root，并把诊断写到 stderr。

      build 与 prepack

      两者都接受源码选项组，外加：

      选项默认值含义
      --output <path>配置中的 output.distPath，否则为 artifact相对 --root 的产物输出路径。dist 属于包构建。

      当项目声明了 bin 或 lib 时，两者都会构建包输出。

      install

      agent-bundle install <host> [--from <bundle-dir>] [--scope <scope>] [--mode <mode>] [--replace] [--json]
      选项默认值含义
      <host>必填claude、codex 或 cursor。
      --from <bundle-dir>process.cwd()target 捆绑包目录或产物根目录。
      --scope <scope>useruser、project 或 local。Claude 接受全部三种；Codex 与 Cursor 是 user 作用域。
      --mode <mode>local仅限 Cursor。local 把捆绑包复制到 ~/.cursor/plugins/local/<name>；marketplace 在 ~/.cursor/agent-bundle/marketplaces/<name> 下暂存一个已提交的本地市场仓库，并打印 Customize → Plugins →“Add Plugins from Local Repository”这一步，让 Cursor 把该插件当作市场安装来管理。
      --replace（别名 --force）关闭即使版本不同，也替换该插件已有的 agent-bundle 安装。不带它时，内容完全相同的副本是 already-installed 空操作，版本相同但内容哈希不同的副本会被自动替换，版本不同则为 AB7005。外来目录总是被拒绝（AB7005）。

      输出的独立 install.mjs 与相对包的安装器 bin 接受同样的 --replace。Cursor 副本携带安装回执 （.agent-bundle-install.json），替换只触碰归属文件，--replace 会接管回执出现之前的副本；Claude 的替换 先运行 claude plugin uninstall --keep-data 再重新安装，Codex 则先 codex plugin remove 再 add。

      doctor

      选项默认值含义
      --host <host>全部受支持的宿主要检查的宿主。可重复；取值为 claude、codex 或 cursor。
      --from <bundle-dir>——用于比对的 target 捆绑包目录或产物根目录。
      --json关闭写出一份机器可读的 JSON 文档。

      当 Doctor 报告任何 error 级诊断时以 1 退出，并且绝不修改任何东西。带 --from 时，它按宿主把已安装副本报告为 current、stale（版本相同、内容不同——AB7308）、version-mismatch（AB7309）、foreign（AB7321）或 not-installed（AB7307）。对 Cursor，它还会根据已安装清单证明插件级 hook 的注册（AB7322），在 ~/.cursor/hooks.json 会把某个插件 hook 再投递一次时发出警告（AB7323），并跟踪暂存的市场从 unregistered 到 Cursor 导入后的 registered（AB7324）。

      validate

      选项默认值含义
      --artifact <path>——精确校验这份已构建产物，而不是项目源码。
      --host-validation / --no-host-validation开启为兼容的已构建 target 运行已安装的宿主开发者工具。
      --strict关闭把宿主工具的 warning 提升为 error。

      eval

      选项默认值含义
      --artifact <path>从源码构建精确评测这份已构建产物。
      --case <case>全部要运行的 eval case id。可重复。
      --suite <suite>全部要运行的 eval 套件名。可重复。
      --harness <harness>deterministicdeterministic、claude 或 codex。
      --trials <count>套件声明值为每个所选 case 运行这么多次试验。正整数，最大 100。

      eval compare <baseline> <candidate> 接受两个已持久化的运行 id，并从 eval 继承源码选项。

      inspect

      inspect 接受 --root、--config、--mode、--json 与单个 --target <target> 过滤器 （不可重复），外加至多一个聚焦标志：

      标志聚焦于
      --bundler合成出来的打包器配置。
      --hooks钩子。
      --routes编译后的路由图。
      --skillsSkill。
      --state状态生命期。

      传入多个聚焦标志是错误。当规范化模型无效时，inspect 以 1 退出。

      每份检查计划都会以规范组件类型报告每个组件——agent、cli、command、event-route、hook、lsp、 mcp-app、mcp-server、native-diagnostics、native-extension、rule、script、skill（来自 agent-bundle/api 的 AgentComponentKind）——标为 selected 或带原因的 skipped，并附一份 kinds 矩阵： 每种类型一条，包含该 target 自己的四态能力判定以及选中/省略计数。人类可读输出为每个 target 打印一行、每条 省略及其原因，然后是 kinds this host cannot emit:。文件系统 src/events 路由报告为 event-route，按宿主的 event:<规范事件> 行判定，而不是 hook。

      mcp

      mcp list 需要 --server <server>。mcp invoke 需要 --server 与 --tool <tool>，并且只接受 --input <json> 与 --input-file <path> 二者之一；解析出的值必须是 JSON 对象，而不是数组或标量。

      mcp run 需要 --server，并以继承的 stdio 在前台运行一个 stdio 服务器：

      选项默认值含义
      --env-file <path>约定集合精确加载这个 .env 文件，替换项目根目录的那一组。可重复。
      --no-env关闭不加载任何 .env 文件即启动。与 --env-file 互斥。
      --plugin-root <path>项目根目录让 env 中的 plugin-root 锚点相对这个根展开。

      由于在整个前台运行期间由服务器持有 JSON-RPC 通道，mcp run 自身不向 stdout 写任何东西。.env 优先级 规则，以及 plugin-root 锚点改变了什么，见运行时环境。

      hooks

      hooks list 报告某份产物中的钩子。hooks simulate 需要 --hook <hook>（id 或名字），以及与 mcp invoke 相同的 --input / --input-file 二选一。

      退出码

      退出码含义
      0成功，包括 --help 与 --version。
      1一次被报告的失败：一条 error 级诊断、inspect 得到的无效模型、失败或结论不明的 eval 运行，或者被作为一条 AB5000 诊断写到 stderr 的未捕获错误。
      2来自命令行解析器的参数解析失败。

      当任何一次试验失败或结论不明时，eval 运行以 1 退出——结论不明的试验没有产生证据，因此它同样不能 报告成功。