宿主安装

每个已构建 target 目录都包含一份生成的 INSTALL.md，其中的命令使用捆绑包真实的插件名与市场名。框架 CLI 执行的正是同样的操作：

npx agent-bundle install claude --from artifact/claude --scope user
npx agent-bundle install codex --from artifact/codex
npx agent-bundle install cursor --from artifact/cursor

--from 既接受一个 target 捆绑包目录，也接受一个不含源码的产物根目录，只要该根目录包含所选宿主的 target 目录。

各宿主接受什么

宿主	机制	作用域
Claude Code	委托给 `claude plugin marketplace add` 与 `claude plugin install`。	`user`、`project`、`local`
Codex	委托给 `codex plugin marketplace add` 与 `codex plugin add`。	`user`
Cursor	把捆绑包复制到 `~/.cursor/plugins/local/<name>`（默认的 `--mode local`），因为 Cursor 未发布非交互式安装动词；`--mode marketplace` 则在 `~/.cursor/agent-bundle/marketplaces/<name>` 下暂存一个已提交的本地市场仓库，并打印 Customize → Plugins →“Add Plugins from Local Repository”这一步。无论哪种方式，Cursor 都从清单加载插件的 `hooks/hooks.json`，因此插件 hook 会在替换 `${CURSOR_PLUGIN_ROOT}` 后运行，无需 `~/.cursor/hooks.json` 条目。	`user`

由于 Claude 与 Codex target 始终随行本地市场清单，它们的公开 CLI 可以直接安装输出的目录。当所选宿主二进制文件不可用时，安装器会以一条带类型的诊断失败，而不是报告一次它并未完成的成功。宿主安装诊断属于 AB700x 家族：捆绑包标识、宿主可用性、作用域、命令失败与冲突检查。

独立安装器

Cursor、portable 与组合 target 包含一个 install.mjs，它把捆绑包复制到 ~/.cursor/plugins/local/<name>，且不会覆盖冲突内容：

npx agent-bundle install cursor --from artifact/cursor
# 或者，在输出的 target 目录中执行：
node ./install.mjs

它的分阶段复制对内容相同的情况是幂等的，并会拒绝版本或内容冲突。它绝不调用 sudo，也绝不修改 PATH。产物校验会拒绝缺少必需安装表面的内置 target，因此捆绑包不可能在缺少它所承诺的安装器的情况下发布。

相对包的安装器 bin

当包输出随行上述某个宿主包时，构建还会输出一个相对包的安装器 bin。当没有配置的 bin 占用该名字时，它使用插件名，否则使用 <plugin-name>-install（两者都被占用时追加数字后缀）。请在 package.json 中把这个名字映射到生成的 dist/bin/*.js 文件；消费者随后运行：

<bin> install <host> [--scope <scope>] [--json]

帮助信息只列出实际构建出来的宿主。该可执行文件通过 import.meta.url 在已安装包旁边定位产物目录，绝不依赖调用方的工作目录，因此无论从哪里调用，它在 node_modules 中都能工作。任何 npm 生命周期都不会执行安装——安装一个包绝不会改动宿主的插件状态。

开发期安装是另一回事

agent-bundle dev --install-host <host> 维护的是一个标记为开发用的安装，它跟随成功的重建 epoch，带有原子的世代切换与一条稳定的 proxy 命令。这部分内容在开发者 Workbench中，与 agent-bundle install 不是同一个操作。

重建后重新安装

每个输出的安装器——agent-bundle install <host>、相对包的 bin 与独立的 install.mjs——共用同一套替换策略。内容完全相同的副本是 already-installed 空操作。版本相同但内容哈希不同的副本会被自动替换，因此不升版本地重建不再需要卸载加 rm -rf。版本不同则以 AB7005 拒绝，除非传入 --replace（别名 --force）；外来目录 ——不是本插件安装器放置的——无论如何都会被拒绝。Cursor 副本携带安装回执（.agent-bundle-install.json：插件、版本、宿主、内容哈希、归属文件）；替换就地进行，只触碰归属文件，绝不动 state/ 之类的非归属条目， --replace 会接管回执出现之前的副本。Claude 的替换先运行 claude plugin uninstall --keep-data 再重新安装，因为 plugin update 受版本门控；Codex 先 codex plugin remove 再 add。输出的 INSTALL.md 按宿主记录了同样的步骤。

在不改动的前提下检查安装

npx agent-bundle doctor --host claude --host cursor --json
npx agent-bundle doctor --from artifact --json

Doctor 是只读的。它探测宿主、清点已安装的捆绑包、把它们与提供的捆绑包做比对、检查注册证明、采样运行时端点的健康状况与身份、清点持久状态，并对已安装的字节重新运行被固定的、无进程的文档与加载器校验器。它绝不修复任何东西。带 --from 时，它按宿主把已安装副本报告为 current、stale（AB7308）、version-mismatch （AB7309）、foreign（AB7321）或 not-installed（AB7307）。

代码	严重级别	含义
`AB7316`	warning	某个已安装捆绑包的 `state/` 目录，或它的某个 `*.sqlite`、`-wal`、`-shm` 文件无法通过文件系统元数据操作读取。Doctor 只按目录条目与元数据清点状态；它绝不打开数据库。
`AB7317`	info	某个活跃的事件运行时实现的是较旧的严格协议，不暴露运行时身份。
`AB7318`	error	在有界的只读身份探测过程中，某个活跃的事件运行时变为不可用、超时，或返回了无效的状态响应。
`AB7319`	error	由 `doctor --from` 解析出的宿主目录树违反了它被固定的文档 schema 或无进程加载器规则；消息中保留原始的构建校验器代码。
`AB7322`	info / error	已安装的 Cursor 插件从清单注册了插件级 hook 且每条命令的脚本都存在于插件根之下时为 info；声明的 hooks 文件缺失或格式错误、或被执行的脚本不存在时为 error。
`AB7323`	warning	`~/.cursor/hooks.json` 注册了指向某个已安装插件目录的命令，Cursor 会把该 hook 投递两次；仅靠清单注册就已足够。
`AB7324`	info / warning / error	由 `install cursor --mode marketplace` 暂存的市场已被导入（`registered`）、仍在等待 Customize 导入步骤（`unregistered`），或不完整（`corrupt`）。
`AB7320`	error / info	当某个 `.cursor-plugin/plugin.json` 安装违反 Cursor 被固定的文档 schema 或 token 位置规则，或某个本地插件包含逃逸出 `~/.cursor/plugins/local` 的符号链接时为 error，该清点条目被报告为 `corrupt`。当某个 `.claude-plugin/plugin.json` 或根 `plugin.json` 安装没有 Cursor 侧被固定的静态文档契约时为 info，被加载器识别的条目仍为 `installed`。

下一步

预览包 —— 目前可安装的 tarball 从哪里来。
产物校验 —— 在安装之前为捆绑包把关的那些检查。

#宿主安装

#各宿主接受什么

#独立安装器

#相对包的安装器 bin

#开发期安装是另一回事

#重建后重新安装

#在不改动的前提下检查安装

#下一步