From ca294f7b935cba869c6fb2c88dfe4e71d02e335c Mon Sep 17 00:00:00 2001 From: ScriptedAlchemy Date: Thu, 3 Sep 2026 16:26:09 +0000 Subject: [PATCH] docs(site): catch the docsite up with #414, #427, #398, #412, and #376 Document the user-facing behaviour that landed on main after the docsite PR (#384) merged, in both locales: - install: `agent-bundle install cursor --mode local|marketplace` and the Doctor findings for Cursor hook registration and marketplace staging (AB7322-AB7324) (#414) - project structure: per-host feature sets for src/commands and src/rules, with AB4907/AB4908 and AB4927/AB4928 (#427) - testing: the script-dispatch and workbench-surface proof levels, eleven in all, and the routed cli-tool template (#398) - notices reference: inbox and resources/updated wiring gated on the host's noticeDelivery advertisement (#412, #376) --- website/docs/en/guide/development/testing.mdx | 6 ++++-- website/docs/en/guide/distribution/installation.mdx | 5 ++++- website/docs/en/guide/start/project-structure.mdx | 4 ++-- website/docs/en/guide/start/quick-start.mdx | 2 +- website/docs/en/reference/cli.mdx | 8 ++++++-- website/docs/zh/guide/development/testing.mdx | 6 ++++-- website/docs/zh/guide/distribution/installation.mdx | 5 ++++- website/docs/zh/guide/start/project-structure.mdx | 4 ++-- website/docs/zh/guide/start/quick-start.mdx | 2 +- website/docs/zh/reference/cli.mdx | 7 +++++-- website/plugins/generated-reference.ts | 4 ++-- 11 files changed, 35 insertions(+), 18 deletions(-) diff --git a/website/docs/en/guide/development/testing.mdx b/website/docs/en/guide/development/testing.mdx index 5db4685ac..bc4821194 100644 --- a/website/docs/en/guide/development/testing.mdx +++ b/website/docs/en/guide/development/testing.mdx @@ -1,5 +1,5 @@ --- -description: 'Test agent-bundle routes through the framework harness: the rstest configuration helper, renderRoute, the nine proof levels, and the generated-plugin contract matrix.' +description: 'Test agent-bundle routes through the framework harness: the rstest configuration helper, renderRoute, the eleven proof levels, and the generated-plugin contract matrix.' --- # Testing @@ -79,11 +79,13 @@ and prints it in every failure, because a pass at one level is never a receipt f | `mcp-in-memory` | `openInMemoryMcpServer`, `invokeMcpTool`, `readMcpResource`, `getMcpPrompt`, `listMcpSurface`, `runContractMatrix` | The real generated MCP server's protocol contract, over the SDK's in-memory transport. | | `dev-epoch` | `runDevEpochContractMatrix` | An epoch-pinned generated stdio process opened through the Workbench session service; the caller owns the epoch lease and process lifetime, and MCP App routes are covered (surface plus `ui://` sweep). | | `cli-dispatch` | `invokeCli`, `cliJson`, `cliNdjson` | A plain or rendered argv vector resolved and run through the routed CLI's own shell — including rendered Markdown, explicit TTY, JSON, and NDJSON modes — in-process. | +| `script-dispatch` | `runScript`, `scriptJson`, `scriptNdjson` | A conventional `src/scripts/*` module run through its generated executable's contract, without bundling: a rendered `.tsx` script through the rendered-script shell in-process (piped Markdown, TTY, `--json`, `--ndjson`, with the project's conventional providers mounted), a plain `.ts` script as a Node process of its own through the `main` envelope — real `process.exit`, exit code, stdout, stderr, optional `stdin`. `testManifest().scripts` lists the scripts that ship; a nested (`AB4808`) or conflicting (`AB4809`) script is never a target. | +| `workbench-surface` | `inspectWorkbenchSurface` | What the dev server would hand the Workbench for this project — route manifest, grouped route catalog, state declaration, lifecycle-replay fixtures, page availability — from the same compiler pass, with no browser and no dev server; a project the compiler rejects reports `manifest-unavailable` with its error diagnostics. | | `packed-stdio` | `openPackedMcpServer`, `runPackedContractMatrix` | A built artifact's generated entry running as a real process over stdio. | | `packed-deleted-source` | `removeProjectSource`, `openPackedMcpServer({ deletedSource })`, `runPackedContractMatrix` | The packed stdio process still runs after project source and configuration are removed and verified absent. | | `host-install` | `openInstalledHostMcpServer`, `runInstalledHostContractMatrix` | A built bundle staged into an isolated host root, discovered in the emitted host format, and spawned from the installed layout. | -Two further levels sit alongside these seven, for nine in all. `agent-bundle/test/browser` supplies `mountBrowserApp` +Two further levels sit alongside these nine, for eleven in all. `agent-bundle/test/browser` supplies `mountBrowserApp` for the browser-safe `browser-app` level — production-compiled MCP App HTML mounted over the product bridge in a real browser page — and `simulated` reuses the installed-host helper `openInstalledHostMcpServer` without `sessionEvidence`: an emitted bundle staged directly into diff --git a/website/docs/en/guide/distribution/installation.mdx b/website/docs/en/guide/distribution/installation.mdx index 8c8d8ad7b..65927c36b 100644 --- a/website/docs/en/guide/distribution/installation.mdx +++ b/website/docs/en/guide/distribution/installation.mdx @@ -22,7 +22,7 @@ the root contains the selected host's target directory. | --- | --- | --- | | Claude Code | Delegates to `claude plugin marketplace add` and `claude plugin install`. | `user`, `project`, `local` | | Codex | Delegates to `codex plugin marketplace add` and `codex plugin add`. | `user` | -| Cursor | Copies the bundle into `~/.cursor/plugins/local/`, because Cursor publishes no non-interactive install verb. | `user` | +| Cursor | Copies the bundle into `~/.cursor/plugins/local/` (`--mode local`, the default), because Cursor publishes no non-interactive install verb; `--mode marketplace` instead stages a committed local marketplace repository under `~/.cursor/agent-bundle/marketplaces/` and prints the Customize → Plugins → "Add Plugins from Local Repository" step. Either way Cursor loads the plugin's `hooks/hooks.json` from its manifest, so plugin hooks run with `${CURSOR_PLUGIN_ROOT}` substituted and need no `~/.cursor/hooks.json` entry. | `user` | Because Claude and Codex targets always ship local marketplace manifests, their public CLIs can install the emitted directory directly. The installer fails with a typed diagnostic when the @@ -103,6 +103,9 @@ installed bytes. It never repairs anything. With `--from`, it reports the instal | `AB7317` | info | A live event runtime implements the older strict protocol and does not expose runtime identity. | | `AB7318` | error | A live event runtime became unavailable, timed out, or returned an invalid status response during the bounded read-only identity probe. | | `AB7319` | error | A host tree resolved from `doctor --from` violates its pinned document schemas or process-free loader rules; the message retains the originating build-validator code. | +| `AB7322` | info / error | Info when an installed Cursor plugin registers plugin-scoped hooks from its manifest and every command's script exists under the plugin root; error when the declared hooks file is missing or malformed, or an executed script is absent. | +| `AB7323` | warning | `~/.cursor/hooks.json` registers a command that points into an installed plugin directory, so Cursor would deliver that hook twice; manifest registration alone is sufficient. | +| `AB7324` | info / warning / error | A marketplace staged by `install cursor --mode marketplace` is imported (`registered`), still awaiting the Customize import step (`unregistered`), or incomplete (`corrupt`). | | `AB7320` | error / info | Error when a `.cursor-plugin/plugin.json` install violates Cursor's pinned document schemas or token-location rules, or when a local plugin contains a symlink escaping `~/.cursor/plugins/local`; the inventory entry is reported as `corrupt`. Info when a `.claude-plugin/plugin.json` or root `plugin.json` install has no Cursor-side pinned static document contract, and the loader-recognized entry stays `installed`. | ## Next diff --git a/website/docs/en/guide/start/project-structure.mdx b/website/docs/en/guide/start/project-structure.mdx index 43bcefe58..d7e04f5cc 100644 --- a/website/docs/en/guide/start/project-structure.mdx +++ b/website/docs/en/guide/start/project-structure.mdx @@ -41,8 +41,8 @@ my-plugin/ | Path | Surface | Opt out | | --- | --- | --- | | `src/skills//SKILL.md` | A Skill. Everything else in the directory ships as its resources. Ships with no declaration at all. | Remove the directory, or narrow the `skills` config globs. | -| `src/commands/*.md` | Flat host command documents. | Remove the file. | -| `src/rules/*.mdc` | Flat host rule documents. | Remove the file. | +| `src/commands/*.md` | Flat host command documents. Frontmatter is judged per host: Claude Code documents `description`, `argument-hint`, `allowed-tools`, `model`, and `disable-model-invocation`, while Cursor's pinned commands surface is frontmatter-free Markdown. A command that explicitly targets a host which cannot express a field it uses is `AB4927`; an implicitly selected host receives the body minus the field and `validate` warns `AB4928`. `inspect` lists the same omissions as `omittedFeatures`. | Remove the file. | +| `src/rules/*.mdc` | Flat host rule documents, emitted by Cursor, which keeps `description`, `globs`, and `alwaysApply`. The same per-host judgment applies: `AB4907` for an explicit target, `AB4908` as a warning for an implicit one. | Remove the file. | | `src/mcp/.ts` | Stdio entry for a declared MCP server that names no `entry`, `command`, or `url`. | Declare `entry` explicitly. | | `src/mcp//{tools,resources,prompts}/*` | Generated MCP server routes. The path supplies identity; each module supplies static `config`, schemas, and one async default Server Component. | Set `routes.servers.` to `custom`, `command`, or `remote`. | | `src/mcp//apps/*` | Browser MCP App entries compiled to self-contained HTML and registered on the generated server. Static `config.resourceUri` is required. | Use a custom server, or prefix the file with `_`. | diff --git a/website/docs/en/guide/start/quick-start.mdx b/website/docs/en/guide/start/quick-start.mdx index e79789f07..679b86bd1 100644 --- a/website/docs/en/guide/start/quick-start.mdx +++ b/website/docs/en/guide/start/quick-start.mdx @@ -34,7 +34,7 @@ npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@/SKILL.md` directory and nothing else. | | `mcp-server` | A stdio MCP server from one `src/mcp//tools/.tsx` route module plus one artifact script, with the framework test harness wired up. | -| `cli-tool` | An installable CLI through the `src/cli.ts` bin convention, plus a `src/index.ts` library export with declarations. | +| `cli-tool` | An installable routed CLI (`src/cli/greet.ts`) plus a conventional script (`src/scripts/hello.ts`) and a `src/index.ts` library export with declarations, proved by a generated projection pool at the `cli-dispatch` and `script-dispatch` levels. | Every template ships a `check` script (validate, build, typecheck, tests) and validates with zero diagnostics — including the `AB473x` migration nudges, because the templates are written diff --git a/website/docs/en/reference/cli.mdx b/website/docs/en/reference/cli.mdx index 086c2f08d..d082aa3de 100644 --- a/website/docs/en/reference/cli.mdx +++ b/website/docs/en/reference/cli.mdx @@ -79,7 +79,7 @@ Both build package outputs when the project declares `bin` or `lib`. ## install ```sh -agent-bundle install [--from ] [--scope ] [--replace] [--json] +agent-bundle install [--from ] [--scope ] [--mode ] [--replace] [--json] ``` | Option | Default | Meaning | @@ -87,6 +87,7 @@ agent-bundle install [--from ] [--scope ] [--replace] | `` | **required** | `claude`, `codex`, or `cursor`. | | `--from ` | `process.cwd()` | Target bundle directory or artifact root. | | `--scope ` | `user` | `user`, `project`, or `local`. Claude accepts all three; Codex and Cursor are user-scoped. | +| `--mode ` | `local` | Cursor only. `local` copies the bundle into `~/.cursor/plugins/local/`; `marketplace` stages a committed local marketplace repository under `~/.cursor/agent-bundle/marketplaces/` and prints the Customize → Plugins → "Add Plugins from Local Repository" step that makes Cursor manage the plugin as a marketplace install. | | `--replace` (alias `--force`) | off | Replace an existing agent-bundle install of this plugin even when its version differs. Without it, an identical copy is an `already-installed` no-op, a same-version copy whose content hash differs is replaced automatically, and a different version is `AB7005`. Foreign directories are always refused (`AB7005`). | The emitted standalone `install.mjs` and the package-relative installer bin accept the same @@ -105,7 +106,10 @@ before `add`. Doctor exits `1` when it reports any error diagnostic, and never modifies anything. With `--from`, it reports the installed copy per host as `current`, `stale` (same version, different content — -`AB7308`), `version-mismatch` (`AB7309`), `foreign` (`AB7321`), or `not-installed` (`AB7307`). +`AB7308`), `version-mismatch` (`AB7309`), `foreign` (`AB7321`), or `not-installed` (`AB7307`). For +Cursor it also proves plugin-scoped hook registration from the installed manifest (`AB7322`), warns +when `~/.cursor/hooks.json` would deliver a plugin hook a second time (`AB7323`), and tracks a +staged marketplace from `unregistered` to `registered` once Cursor imports it (`AB7324`). ## validate diff --git a/website/docs/zh/guide/development/testing.mdx b/website/docs/zh/guide/development/testing.mdx index e5c6eea09..5f7c40977 100644 --- a/website/docs/zh/guide/development/testing.mdx +++ b/website/docs/zh/guide/development/testing.mdx @@ -1,5 +1,5 @@ --- -description: '通过框架 harness 测试 agent-bundle 路由：rstest 配置辅助函数、renderRoute、九个证明级别，以及生成式插件的契约矩阵。' +description: '通过框架 harness 测试 agent-bundle 路由：rstest 配置辅助函数、renderRoute、十一个证明级别，以及生成式插件的契约矩阵。' --- # 测试 @@ -70,11 +70,13 @@ export const summarizes = async (): Promise => { | `mcp-in-memory` | `openInMemoryMcpServer`、`invokeMcpTool`、`readMcpResource`、`getMcpPrompt`、`listMcpSurface`、`runContractMatrix` | 真实生成式 MCP 服务器的协议契约，经由 SDK 的内存内传输。 | | `dev-epoch` | `runDevEpochContractMatrix` | 通过 Workbench 会话服务打开的、锁定到某个 epoch 的生成式 stdio 进程；调用方拥有 epoch 租约与进程生命周期，MCP App 路由被覆盖（表面加 `ui://` 扫描）。 | | `cli-dispatch` | `invokeCli`、`cliJson`、`cliNdjson` | 一个普通或渲染式 argv 向量在路由式 CLI 自己的 shell 中被解析并执行——包括渲染式 Markdown、显式 TTY、JSON 与 NDJSON 模式——全部在进程内完成。 | +| `script-dispatch` | `runScript`、`scriptJson`、`scriptNdjson` | 一个约定式 `src/scripts/*` 模块按其生成可执行文件的契约运行，无需打包：渲染式 `.tsx` 脚本在进程内经由渲染式脚本外壳运行（管道 Markdown、TTY、`--json`、`--ndjson`，并挂载项目的约定式 provider），普通 `.ts` 脚本则作为独立 Node 进程经由 `main` 封套运行——真实的 `process.exit`、退出码、stdout、stderr 与可选的 `stdin`。`testManifest().scripts` 列出实际发布的脚本；嵌套（`AB4808`）或冲突（`AB4809`）的脚本绝不会成为目标。 | +| `workbench-surface` | `inspectWorkbenchSurface` | dev 服务器会交给 Workbench 的本项目内容——路由清单、分组路由目录、state 声明、生命周期回放 fixture、页面可用性——来自同一次编译器处理，无需浏览器也无需 dev 服务器；被编译器拒绝的项目报告 `manifest-unavailable` 及其 error 诊断。 | | `packed-stdio` | `openPackedMcpServer`、`runPackedContractMatrix` | 已构建产物的生成入口作为真实进程通过 stdio 运行。 | | `packed-deleted-source` | `removeProjectSource`、`openPackedMcpServer({ deletedSource })`、`runPackedContractMatrix` | 在项目源码与配置被移除并核实缺失之后，打包后的 stdio 进程仍然可以运行。 | | `host-install` | `openInstalledHostMcpServer`、`runInstalledHostContractMatrix` | 一份已构建的捆绑包被投放到隔离的宿主根目录、以输出的宿主格式被发现，并从已安装布局中启动。 | -在这七个级别之外还有两个并列级别，共九个。`agent-bundle/test/browser` 为浏览器安全的 `browser-app` 级别 +在这九个级别之外还有两个并列级别，共十一个。`agent-bundle/test/browser` 为浏览器安全的 `browser-app` 级别 提供 `mountBrowserApp`，用于在真实浏览器页面中把生产编译的 MCP App HTML 挂载到产品桥接层之上； 而 `simulated` 复用不带 `sessionEvidence` 的已安装宿主辅助函数 `openInstalledHostMcpServer` —— 一份输出的捆绑包被直接投放到隔离的宿主形状根目录并在没有宿主自有安装的情况下启动，它比 diff --git a/website/docs/zh/guide/distribution/installation.mdx b/website/docs/zh/guide/distribution/installation.mdx index f3b34ce5c..9cc4910c7 100644 --- a/website/docs/zh/guide/distribution/installation.mdx +++ b/website/docs/zh/guide/distribution/installation.mdx @@ -22,7 +22,7 @@ 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/`，因为 Cursor 未发布非交互式安装动词。 | `user` | +| Cursor | 把捆绑包复制到 `~/.cursor/plugins/local/`（默认的 `--mode local`），因为 Cursor 未发布非交互式安装动词；`--mode marketplace` 则在 `~/.cursor/agent-bundle/marketplaces/` 下暂存一个已提交的本地市场仓库，并打印 Customize → Plugins →“Add Plugins from Local Repository”这一步。无论哪种方式，Cursor 都从清单加载插件的 `hooks/hooks.json`，因此插件 hook 会在替换 `${CURSOR_PLUGIN_ROOT}` 后运行，无需 `~/.cursor/hooks.json` 条目。 | `user` | 由于 Claude 与 Codex target 始终随行本地市场清单，它们的公开 CLI 可以直接安装输出的目录。当所选宿主 二进制文件不可用时，安装器会以一条带类型的诊断失败，而不是报告一次它并未完成的成功。宿主安装诊断属于 @@ -91,6 +91,9 @@ 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`。 | ## 下一步 diff --git a/website/docs/zh/guide/start/project-structure.mdx b/website/docs/zh/guide/start/project-structure.mdx index 859ea882a..61bd5d5a8 100644 --- a/website/docs/zh/guide/start/project-structure.mdx +++ b/website/docs/zh/guide/start/project-structure.mdx @@ -40,8 +40,8 @@ my-plugin/ | 路径 | 表面 | 如何退出 | | --- | --- | --- | | `src/skills//SKILL.md` | 一个 Skill。目录中其余内容都作为它的资源随行。完全不需要任何声明即可随产物发布。 | 删除该目录，或收窄 `skills` 配置中的 glob。 | -| `src/commands/*.md` | 扁平的宿主命令文档。 | 删除该文件。 | -| `src/rules/*.mdc` | 扁平的宿主规则文档。 | 删除该文件。 | +| `src/commands/*.md` | 扁平的宿主命令文档。frontmatter 按宿主逐一判定：Claude Code 记录了 `description`、`argument-hint`、`allowed-tools`、`model` 与 `disable-model-invocation`，而 Cursor 固定的命令表面是无 frontmatter 的 Markdown。显式指向某个无法表达其所用字段的宿主的命令是 `AB4927`；隐式选中的宿主收到去掉该字段的正文，`validate` 给出警告 `AB4928`。`inspect` 以 `omittedFeatures` 列出同样的省略。 | 删除该文件。 | +| `src/rules/*.mdc` | 扁平的宿主规则文档，由 Cursor 发射，保留 `description`、`globs` 与 `alwaysApply`。同样的按宿主判定适用：显式 target 为 `AB4907`，隐式 target 为警告 `AB4908`。 | 删除该文件。 | | `src/mcp/.ts` | 某个已声明、但未指定 `entry`、`command` 或 `url` 的 MCP 服务器的 stdio 入口。 | 显式声明 `entry`。 | | `src/mcp//{tools,resources,prompts}/*` | 生成式 MCP 服务器路由。路径提供身份；每个模块提供静态 `config`、schema，以及一个 async 默认 Server Component。 | 把 `routes.servers.` 设为 `custom`、`command` 或 `remote`。 | | `src/mcp//apps/*` | 浏览器 MCP App 入口，编译为自包含 HTML 并注册到生成的服务器上。必须提供静态 `config.resourceUri`。 | 使用自定义服务器，或给文件名加 `_` 前缀。 | diff --git a/website/docs/zh/guide/start/quick-start.mdx b/website/docs/zh/guide/start/quick-start.mdx index 1c96211bb..07fd8cfbc 100644 --- a/website/docs/zh/guide/start/quick-start.mdx +++ b/website/docs/zh/guide/start/quick-start.mdx @@ -31,7 +31,7 @@ npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@/SKILL.md` 目录，此外别无他物。 | | `mcp-server` | 由一个 `src/mcp//tools/.tsx` 路由模块构成的 stdio MCP 服务器，外加一个产物脚本，并已接好框架测试 harness。 | -| `cli-tool` | 通过 `src/cli.ts` bin 约定提供的可安装 CLI，外加一个带声明文件的 `src/index.ts` 库导出。 | +| `cli-tool` | 可安装的路由式 CLI（`src/cli/greet.ts`），外加一个约定式脚本（`src/scripts/hello.ts`）与带声明文件的 `src/index.ts` 库导出，并由生成的 projection 测试池在 `cli-dispatch` 与 `script-dispatch` 级别加以证明。 | 每个模板都自带 `check` 脚本（validate、build、typecheck、tests），并且校验时零诊断——包括 `AB473x` 迁移提示，因为这些模板从一开始就是按照 entry 约定编写的。`mcp-server` 模板还自带消费者测试 harness， diff --git a/website/docs/zh/reference/cli.mdx b/website/docs/zh/reference/cli.mdx index c74eb7658..528ffad2c 100644 --- a/website/docs/zh/reference/cli.mdx +++ b/website/docs/zh/reference/cli.mdx @@ -79,7 +79,7 @@ proxy 从父命令 `dev` 继承 `--root`，并把诊断写到 stderr。 ## install ```sh -agent-bundle install [--from ] [--scope ] [--replace] [--json] +agent-bundle install [--from ] [--scope ] [--mode ] [--replace] [--json] ``` | 选项 | 默认值 | 含义 | @@ -87,6 +87,7 @@ agent-bundle install [--from ] [--scope ] [--replace] | `` | **必填** | `claude`、`codex` 或 `cursor`。 | | `--from ` | `process.cwd()` | target 捆绑包目录或产物根目录。 | | `--scope ` | `user` | `user`、`project` 或 `local`。Claude 接受全部三种；Codex 与 Cursor 是 user 作用域。 | +| `--mode ` | `local` | 仅限 Cursor。`local` 把捆绑包复制到 `~/.cursor/plugins/local/`；`marketplace` 在 `~/.cursor/agent-bundle/marketplaces/` 下暂存一个已提交的本地市场仓库，并打印 Customize → Plugins →“Add Plugins from Local Repository”这一步，让 Cursor 把该插件当作市场安装来管理。 | | `--replace`（别名 `--force`） | 关闭 | 即使版本不同，也替换该插件已有的 agent-bundle 安装。不带它时，内容完全相同的副本是 `already-installed` 空操作，版本相同但内容哈希不同的副本会被自动替换，版本不同则为 `AB7005`。外来目录总是被拒绝（`AB7005`）。 | 输出的独立 `install.mjs` 与相对包的安装器 bin 接受同样的 `--replace`。Cursor 副本携带安装回执 @@ -103,7 +104,9 @@ agent-bundle install [--from ] [--scope ] [--replace] 当 Doctor 报告任何 error 级诊断时以 `1` 退出，并且绝不修改任何东西。带 `--from` 时，它按宿主把已安装副本报告为 `current`、`stale`（版本相同、内容不同——`AB7308`）、`version-mismatch`（`AB7309`）、`foreign`（`AB7321`）或 -`not-installed`（`AB7307`）。 +`not-installed`（`AB7307`）。对 Cursor，它还会根据已安装清单证明插件级 hook 的注册（`AB7322`），在 +`~/.cursor/hooks.json` 会把某个插件 hook 再投递一次时发出警告（`AB7323`），并跟踪暂存的市场从 `unregistered` +到 Cursor 导入后的 `registered`（`AB7324`）。 ## validate diff --git a/website/plugins/generated-reference.ts b/website/plugins/generated-reference.ts index 3c650c48c..380d60130 100644 --- a/website/plugins/generated-reference.ts +++ b/website/plugins/generated-reference.ts @@ -186,7 +186,7 @@ const messages = { noticesDescription: 'Which notice delivery channels each pinned host supports, with the recorded reason for every unavailable channel.', noticesIntro: - 'A notice is an entry in the append-only notice ledger co-mounted with project state (the reserved store id `@agent-bundle/runtime/agent-notice-ledger/v1`). It targets a recipient and moves only through evidenced states — `pending`, `attempted`, `acknowledged`, `expired`, `unavailable`, `withdrawn`. Delivery is attempted through the channels below; a recipient-scoped MCP inbox resource, `agent-bundle://notices/inbox`, exposes pending notices. No host delivery is claimed without a supported channel.', + 'A notice is an entry in the append-only notice ledger co-mounted with project state (the reserved store id `@agent-bundle/runtime/agent-notice-ledger/v1`). It targets a recipient and moves only through evidenced states — `pending`, `attempted`, `acknowledged`, `expired`, `unavailable`, `withdrawn`. Delivery is attempted through the channels below, and a generated MCP server wires each cross-request route only where its host advertises it: the recipient-scoped inbox resource `agent-bundle://notices/inbox` is registered for stateful projects on hosts advertising `mcp-inbox` (every built-in host), and `resources/subscribe` plus one `notifications/resources/updated` per newly eligible pending notice is offered only where the host additionally advertises `mcp-resource-updated` and the state lifetime is workspace-durable — recorded on the ledger as an availability receipt, never a delivery claim. No host delivery is claimed without a supported channel.', noticeChannels: 'Delivery channels', unavailableChannels: 'Why a channel is unavailable', diagnosticsTitle: 'Diagnostics reference', @@ -263,7 +263,7 @@ const messages = { noticesDescription: '每个固定宿主支持哪些通知投递通道，以及每个不可用通道的记录原因。', noticesIntro: - '通知是与项目状态共同挂载的只追加通知账本中的一条记录（保留的存储 id 为 `@agent-bundle/runtime/agent-notice-ledger/v1`）。它面向一个接收者，并且只会经历有证据的状态——`pending`、`attempted`、`acknowledged`、`expired`、`unavailable`、`withdrawn`。投递通过下列通道尝试；按接收者限定的 MCP 收件箱资源 `agent-bundle://notices/inbox` 会暴露待处理通知。没有受支持的通道时，绝不声称已投递到宿主。', + '通知是与项目状态共同挂载的只追加通知账本中的一条记录（保留的存储 id 为 `@agent-bundle/runtime/agent-notice-ledger/v1`）。它面向一个接收者，并且只会经历有证据的状态——`pending`、`attempted`、`acknowledged`、`expired`、`unavailable`、`withdrawn`。投递通过下列通道尝试，生成的 MCP 服务器只在宿主宣告了某条跨请求路由时才接线：按接收者限定的收件箱资源 `agent-bundle://notices/inbox` 会为宣告 `mcp-inbox` 的宿主（所有内置宿主）上的有状态项目注册；只有当宿主还宣告了 `mcp-resource-updated` 且 state 生命周期为工作区持久时，才提供 `resources/subscribe` 以及每条新近可用的待处理通知一次 `notifications/resources/updated`——它以可用性回执记录在账本上，绝不是投递声明。没有受支持的通道时，绝不声称已投递到宿主。', noticeChannels: '投递通道', unavailableChannels: '通道不可用的原因', diagnosticsTitle: '诊断参考',