From 14b0df1a7314f9928cce5dc1847019501e9ac61c Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Mon, 7 Sep 2026 14:43:36 -0700 Subject: [PATCH 01/12] docs: lead docsite with convention-first plugin authoring and delivery --- website/docs/en/guide/distribution/index.mdx | 250 ++++++++---- website/docs/en/guide/start/index.mdx | 119 +++--- .../docs/en/guide/start/project-structure.mdx | 355 +++++++++++------- website/docs/en/guide/start/quick-start.mdx | 267 ++++++++----- website/docs/zh/guide/distribution/index.mdx | 202 +++++++--- website/docs/zh/guide/start/index.mdx | 106 +++--- .../docs/zh/guide/start/project-structure.mdx | 312 +++++++++------ website/docs/zh/guide/start/quick-start.mdx | 236 ++++++++---- 8 files changed, 1171 insertions(+), 676 deletions(-) diff --git a/website/docs/en/guide/distribution/index.mdx b/website/docs/en/guide/distribution/index.mdx index c1d46e1c2..f8f3d869e 100644 --- a/website/docs/en/guide/distribution/index.mdx +++ b/website/docs/en/guide/distribution/index.mdx @@ -1,104 +1,194 @@ --- -description: 'How an agent-bundle project becomes something a host can install: build, validate, and ship the one composite plugin root every selected host reads.' +description: 'Build and validate a composite plugin, pack the generated npm root when needed, and give consumers an explicit installation path without a second compiler.' --- # Shipping a bundle -`agent-bundle build` emits **one composite plugin root** — `artifact/` by default — and that root -is the unit of distribution. There is no packaging step after the build and no per-host -repackaging script: the root is the directory you copy, publish, or hand to a host CLI, and every -host `targets` selected reads the same directory as its plugin root. +There are two delivery forms, with the same compiled plugin inside them: -```sh -npx agent-bundle build --root . --output artifact -``` +| Deliverable | Use it for | +| --- | --- | +| Composite artifact, `artifact/` by default | Copying a built plugin or following its generated native installation instructions. | +| Generated npm root, `dist/` when package output is enabled | Packing an npm tarball with the artifact, package metadata, and any package-only entries. | + +Neither form needs a handwritten host repackager. npm still needs its normal **packaging step**; +that step must use the generated package root, not the source project or a second implementation +of the application. + +The following `npx --no-install` commands run the compiler already installed in the developer +project. They deliberately do not fetch a package by the unqualified `agent-bundle` name. See +[framework installation](../start/installation.mdx) for the supported preview/release selector. ## The pipeline -| Step | Command | What it produces | -| --- | --- | --- | -| Build | `agent-bundle build` | One composite plugin root carrying every selected host projection, plus the `dist/` package build when the project declares `bin`/`lib`. | -| Validate | `agent-bundle validate --artifact --strict` | Content-addressed proof that the emitted bytes match the manifest, plus host-tool findings where a selected host publishes a validator. | -| Install | `agent-bundle install --from ` | The bundle registered in Claude, Codex, or Cursor — all three from the same root. | +```sh +npx --no-install agent-bundle build --output artifact +npx --no-install agent-bundle validate --artifact artifact --strict +``` -The build already validates the project before it writes anything, so a separate `validate` run -against source is a fast pre-flight rather than a required stage. Validating the **artifact** is -the interesting one, because it needs no project sources at all. +| Step | What it establishes | +| --- | --- | +| Source validation / build | The authored declarations can be compiled into the selected projections. A successful build is not native-host execution evidence. | +| Artifact validation | The bare composite artifact's files and digests agree with its manifest and the applicable validation rules. Host-tool checks depend on the selected validation options and available tools. | +| Application and integration tests | The operations behave as expected; stronger packed-process/native-host claims need their own tests. | +| Explicit installation | The chosen host receives the intended projection under its supported scope and ownership rules. | + +A source `validate` run is useful before a typecheck or while editing, but it is not a substitute +for validating the deliverable. `validate --artifact` does not require the source project. +Installation is a separate operator action; building a plugin must not register it globally. ### How the root compiles -The build plans every selected host projection first and merges them by path into one tree — -two projections may share a path only when their bytes agree (`AB4103`), and a component scoped -to some hosts may not sit where another selected host would discover it (`AB4105`). It then -lowers the compiled surfaces in at most two stages into one staged root, published atomically -once the artifact validates: - -1. **MCP Apps** — the browser environment, compiled through `@rsbuild/core`. Present only when - the project declares App routes, and always first: the MCP entries embed its HTML. -2. **Agent-host surfaces** — the routed CLI bin, bundled scripts, hook wrappers, MCP stdio - entries, and each surface's react-server Flight worker, lowered together through **one Rslib - instance** (one Rsbuild environment per output, one Rspack multi-compiler). A surface reaches - its worker by file name at run time, so nothing orders the two within the stage, and each - surface keeps its own source evidence for the manifest. - -Compiled surfaces are built once and attributed to the **composite identity** — the selected -hosts sorted and joined by `+`, such as `claude+codex` — never once per host. Both stages and the -package-only library and authored-bin entries compose their bundler config the same way — -profile, `tools.rsbuild`, `tools.rspack`, then the framework invariants — as described under -[`tools`](../../reference/configuration.mdx#tools). `agent-bundle inspect --bundler` prints the -lowered Rspack configuration of every compiled output; its `output.path` is the artifact output itself. +The compiler discovers the application, resolves selected host projections, compiles the +required browser/server entries, and assembles one validated tree. Shared paths must have +compatible bytes, and a host must not accidentally discover another host's components. + +The generated manifest, not a consumer's filename probe, identifies the executable, its launch +arguments, and its owning server or App. Do not reconstruct a server command from the first +argument in a native `mcp.json`, guess an `artifact//` directory, or rename generated +executables after compilation. Advanced compiler details belong in +[architecture](../concepts/architecture.mdx) and +[artifact validation](./validation.mdx). ## What ships inside the root -Amp's directory plugin lives at `.amp/plugins//`; other host manifests live in their -dotfolders at the root (`.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, and the portable -`plugin.json`), each pointing at its own hook and MCP -documents, while `skills/`, `hooks/`, `mcp/`, `scripts/`, `bin/`, and `assets/` are shared and -emitted once. The full tree and the per-host document locations are in -[Targets and artifacts](../../reference/targets-artifacts.mdx). - -Whenever a built-in host is selected the root carries one generated `INSTALL.md`, a section per -selected host, written with the bundle's **real** plugin and marketplace names — not placeholders -— so the file can be followed verbatim. - -The Claude and Codex projections always include local marketplace manifests, which is what lets -their public CLIs install the root directly. Selecting `cursor` or `portable` adds a standalone -`install.mjs`, because Cursor exposes marketplace management but no non-interactive plugin -install verb. - -`agent-bundle.manifest.json` records every emitted file with its SHA-256, so validation compares -real bytes rather than checking that a path exists. - -Builds are reproducible: two builds of one unchanged source tree emit byte-identical artifacts — -the same manifest and the same digests — whatever `--output` names, however `targets` is ordered, -and however the per-build staging directory is named. The module identifiers the bundler writes -into compiled entries derive from the project root only, never from the staging or output -directory or from any absolute path of the building machine, so installed copies, preview -packages, and [`doctor`](./installation.mdx) comparisons see the same bytes from the same source. -The generated modules those identifiers name are served from memory under the reserved -`.agent-bundle-virtual/` directory of the project root; the build refuses to compile while anything -occupies that directory. +The composite includes the selected native manifests, shared component files, compiled entries, +`agent-bundle.manifest.json`, persisted compile evidence, and generated `INSTALL.md` where +applicable. It contains the plugin's actual names, not a template name consumers must replace. +The [project-structure guide](../start/project-structure.mdx) shows the output layout. + +**The composite root and a host's native install root are not always identical.** Amp's directory +plugin is nested at `.amp/plugins//`; the other built-in native projections read their +manifests from the composite root. The framework's manifest-aware `install --from` command +accepts the composite root and resolves the selected host's layout. Use its generated +instructions rather than requiring end users to learn the nesting. + +Selecting `cursor` or `portable` includes the standalone `install.mjs` path described in +[host installation](./installation.mdx). That is a documented installation mechanism, not a +universal claim that every portable client supports every native hook or App capability. + +Treat delivered code as immutable. Writable framework state is resolved independently of the +installed code directory. Domain data, including refreshed sessions and application databases, +needs a deliberate application-owned location and migration policy. Do not package live +credentials, mutable caches, or operator data as assets. ## The npm-facing half -A project that also ships as an npm package has a second output, `dist/`, but it is not a second -plugin build. `dist/` is the npm package root: it contains the complete composite artifact, -`package.json`, the standard package documentation files, and any package-only library or -authored-bin entries described in [Package entries](../authoring/package-entries.mdx). -`validate --artifact` and other artifact-only commands still take the bare composite artifact; -the manifest-aware `install --from` path accepts the npm root. +For a project with package output enabled, such as the MCP starter, `dist/` contains the complete +npm root: the validated artifact copied unchanged, generated `package.json`, standard package +documentation, and declared package-only bins/library output. There is no nested `artifact/` +inside the tarball. + +For a generated routed CLI, `package.json.bin` points directly at `bin/.mjs` from the +artifact. It has the same operation surface as the artifact CLI, including `web` when declared. +An **explicit authored package bin** instead compiles to `bin/.js`; these are different +entry kinds, not two versions of the same routed CLI. + +Run the framework gate, then pack the generated directory: + +```sh +npx --no-install agent-bundle prepack --json +npm pack ./dist --ignore-scripts +``` -For a generated routed CLI, the installed package's `bin` points directly at -`bin/.mjs`, copied unchanged from the validated artifact. The npm CLI therefore has the -same commands — including `web` — and the same bytes as the artifact CLI. The tarball has no -nested `artifact/` directory, and the framework does not compile a parallel `dist/bin/.js` -application or generate a package-relative installer bin. +`prepack` performs the release build and validates the dry-run package inventory, entry paths, +artifact hashes, versions, and declared runtime dependencies. The second command creates the +actual tarball. `--ignore-scripts` here prevents pack-time scripts from rebuilding a different +product; it is not a promise that consumer install scripts are ignored during installation. + +Check the generated `dist/package.json`, its `bin`/`exports`, and the tarball file list. Do not +patch the generated manifest by hand. Update authored package/configuration inputs and rebuild. +The starters are private development packages; an intentional public release also needs suitable +authored package metadata and removal of `private: true` before rebuilding. This guide does not +publish anything automatically. + +A static plugin distributed as a built directory does not need to invent a library or executable +just to use native installation. See [package entries](../authoring/package-entries.mdx) when +choosing npm delivery and its optional entry points. + +### Consumer install scripts and dependencies + +Build tools are not automatically runtime dependencies. Self-contained generated JavaScript +must not depend on the source checkout, workspace aliases, or the consumer installing the +compiler. A prebuilt payload or an explicitly retained consumer install script may have real +runtime dependencies; declare those accurately instead of externalizing ordinary generated +entries to make the package smaller. + +Do not carry source-relative shell scripts into the installed package by accident. The package +builder supports a bounded relocation of documented script forms and diagnoses unsupported +ones. A package that passes only with `--ignore-scripts` during consumer installation has not +proved its promised install lifecycle. Use isolated fixtures when testing scripts with side +effects; never use real credentials or global host configuration for that test. + +### An optional package-bound installer + +For a consumer-friendly `my-plugin-install install ` command, declare a package-only bin +and delegate its implementation to the public framework entry. Merge this entry into the +existing config rather than replacing unrelated entries: + +```ts twoslash +import { defineConfig } from 'agent-bundle/config'; + +export default defineConfig({ + plugin: { name: 'my-plugin', description: 'Project tools for an agent.' }, + targets: ['claude', 'codex', 'cursor'], + bin: { 'my-plugin-install': './src/install-bin.ts' }, +}); +``` + +```ts +// src/install-bin.ts +import { fileURLToPath } from 'node:url'; +import { runInstallCli } from 'agent-bundle/install'; + +export const main = (argv: readonly string[]): Promise => + runInstallCli(argv, { + from: fileURLToPath(new URL('..', import.meta.url)), + name: 'my-plugin-install', + }); +``` + +The parent-directory binding refers to the **emitted** `bin/` entry in the npm root. Run its +built/installed form, not the source file as a substitute for an installation proof. The package +build bundles the lifecycle implementation, so the consumer does not install the compiler just +to use this bin. + +This is an opt-in entry, not an installer automatically added to every plugin. It reuses +`install`, `uninstall`, and `doctor` with the package root bound once. There is no consumer-owned +argv parser, native config merger, root-search loop, or private framework import. Supported +flags and scopes are in [host installation](./installation.mdx). + +### Prove the installed package + +Install the actual tarball in a fresh temporary consumer and test its declared bin or named MCP +server. Move or remove the source fixture, use a different working directory, and give it a +separate writable state root. Confirm the expected tools and representative results. A test +that launches the source tree's `artifact/` is useful, but it is not an npm-install test. + +Artifact-only commands such as `validate --artifact` take the **bare composite artifact**. +The manifest-aware `install --from` path accepts an npm root as well and excludes npm-only +metadata from host ownership comparisons. Do not interchange those roots merely because both +contain `agent-bundle.manifest.json`. + +Use public [packed test helpers](../development/testing.mdx) and the canonical manifest rather +than copying a private installer or native-document parser into the plugin's test harness. +Native account authorization and host execution remain separately qualified evidence. + +## Install explicitly + +Consumers follow the delivered `INSTALL.md`, or invoke the package-bound installer when the +plugin provides one. Developers who already have the compiler can use: + +```sh +npx --no-install agent-bundle install claude --from artifact --scope user +``` -`agent-bundle prepack` is the gate for that half: it runs the release build, dry-runs `npm pack` -without scripts, and verifies packaged outputs, artifact hashes, bins, and versions. +Use only the intended host and scope. npm package installation is not host registration; +framework build/prepack does not imply consent to modify a host. Read-only `doctor` and planned +uninstall behavior are documented in [host installation](./installation.mdx). ## In this section -- [Artifact validation](./validation.mdx) — source and artifact validation, and what each host's own tooling contributes. -- [Host installation](./installation.mdx) — installing into Claude, Codex, and Cursor, and the install scopes each one accepts. -- [Preview packages](./preview-packages.mdx) — the pkg.pr.new release channel that stands in for npm today. +- [Artifact validation](./validation.mdx): source checks, artifact checks, and host validators. +- [Host installation](./installation.mdx): native roots, scopes, receipts, replacement, and removal. +- [Preview packages](./preview-packages.mdx): the current development distribution channel. diff --git a/website/docs/en/guide/start/index.mdx b/website/docs/en/guide/start/index.mdx index 73807da98..360af482b 100644 --- a/website/docs/en/guide/start/index.mdx +++ b/website/docs/en/guide/start/index.mdx @@ -1,95 +1,96 @@ --- -description: 'agent-bundle compiles one typed config into one installable plugin root for Claude Code, Codex, Cursor, and the portable Agent Plugins format.' +description: 'Build one agent-host plugin with conventional routes, typed results, and framework-owned host projections, development, and packaging.' --- # Introduction -agent-bundle compiles an agent plugin — Skills, hooks, MCP servers, and scripts, described -by one typed config — into installable output for Amp, Claude Code, Codex, and Cursor, plus -the portable Agent Plugins format. You write the plugin once; the compiler emits each host's -manifests and wrappers into that root. +Agent Bundle is a meta-framework for **building plugins for agent hosts**. Write your tools, +Skills, hooks, and views once. The framework discovers conventional source files, builds the +executable entries, and emits the manifests required by your selected hosts. -Node.js 22.19 or later is required. +Start with the [quick start](./quick-start.mdx): create a project, add a tool, see its rendered +result in Workbench, and test it. You do not need to write an MCP server or learn the compiler's +internal architecture first. The compiler and Workbench require Node.js 22.19 or later. ## The problem it solves -Every agent host wants the same plugin expressed in its own layout: its own manifest -filenames, its own placeholder spellings for the plugin install root, its own hook document -shape, its own MCP server declaration. Writing that by hand means maintaining the same plugin -several times and discovering the disagreements after installation. +A **host** is the application loading the plugin, such as Claude Code, Codex, Cursor, or Amp. +An **MCP server** exposes tools, resources, and prompts through the Model Context Protocol. +An **MCP App** is a browser view associated with an MCP resource/tool. These are different parts +of the system, not three names for your application. -agent-bundle inverts that. Host-specific layout is the compiler's job, so it stays out of your -source tree: +Without the framework, a composite plugin can accumulate separate tool registries, native hook +wrappers, CLI handlers, browser message plumbing, and installation scripts. Agent Bundle owns +those integration boundaries so application code can concentrate on what the plugin does. -```sh -npx agent-bundle build --root . +The useful analogy to a convention-based app framework is **a file declares a route**: + +```text +src/mcp/status/tools/hello.tsx + ↓ + hello tool on the status server + ↓ + generated MCP entry · Workbench · tests ``` -That single command emits one composite root at `artifact/`: Amp's `.amp/plugins//` -directory and the manifests of every other selected host (`.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, the portable -`plugin.json`) over shared `skills/`, `hooks/`, `mcp/`, `bin/`, and `scripts/` directories, -plus one `INSTALL.md`. `targets` selects which host projections the root carries — `amp`, -`claude`, `codex`, `cursor`, `portable`; omitted, it selects `portable` alone. Amp installs its -nested generated directory; the other hosts install the composite root. +Add a colocated CLI projection to expose that same operation as a command. Add an App when it +needs an interactive browser view. Neither requires a second implementation of the operation. ## What the config owns -One `agent-bundle.config.ts` at the project root describes the whole plugin: +A conventional project needs a small `agent-bundle.config.ts`: ```ts twoslash import { defineConfig } from 'agent-bundle/config'; export default defineConfig({ - plugin: { name: 'my-plugin', description: 'What it does.' }, // [!code highlight] + plugin: { name: 'my-plugin', description: 'Project tools for an agent.' }, targets: ['claude', 'codex', 'cursor'], - skills: ['src/skills/*'], - hooks: { sessionStart: { handler: './src/session-start.ts' } }, - mcp: { servers: { tools: { entry: './src/mcp.ts' } } }, }); ``` -The same config also owns the npm package build — no second bundler config, no bin shims, no -hand-rolled stdio lifecycles. `bin` and `lib` entries (or the conventions `src/cli.ts`, -`src/index.ts`, and `src/mcp/.ts`) emit executable `dist/bin/.js` bundles and a -library output beside the plugin root. An MCP entry that default-exports a server factory -runs under a framework-owned stdio lifecycle. `tools.rsbuild` / `tools.rspack` is the one -bundler escape hatch. +The plugin name is its host-facing slug; the npm package name may differ. The release version +comes from `package.json`. Target selection does not require repeating the source tree in config. +Custom MCP servers, remote endpoints, prebuilt payloads, and package entries remain supported +when the conventions do not fit; they are not required setup for your first tool. + +`targets` selects projections: `amp`, `claude`, `codex`, `cursor`, or `portable`. Omitted, it +selects `portable` alone. A selected host does not necessarily support every component or live +development feature. Consult [host capabilities](../../reference/targets-artifacts.mdx) before +adding a host-specific surface. ## The authoring model -agent-bundle has one newcomer model, and it fits on four lines: +| Concept | What you write | +| --- | --- | +| Routes | Files under conventional roots such as `src/mcp//tools/`. The path supplies identity. | +| Configuration | Project identity, selected hosts, policy, and explicit exceptions. | +| Rendering | Rendered routes return `Agent.*` elements describing agent-facing content and structured results. Browser Apps use browser UI code. | +| Context, when needed | `await agent()` inside a request gives access to framework-provided context and providers. Unavailable host information is not fabricated. | -1. **Authored source lives under `src/`.** Skills, commands, rules, scripts, MCP routes, state, - and providers all have conventional `src/` roots. A path is an identity: a module at - `src/mcp/curator/tools/status.tsx` *is* the `status` tool of the `curator` server. -2. **One small flat config.** `agent-bundle.config.ts` holds project identity, targets, and the - policy that no route file can own. -3. **JSX means rendering.** An executable route is one async default Server Component that does - the work and returns `Agent.*` nodes. There is no public `execute`/`render` split. -4. **Opt in to context.** Call `await agent()` inside that component only when you need host, - session, actor, workspace, capability, or state context. +A static Skills plugin does **not** need a React runtime or an MCP server. A plain hook can use +the public hook contract without JSX. Providers, state, and browser Apps are optional features, +not boilerplate to copy into every project. -Everything above that line is power-tier reference: custom and remote MCP server modes, -prebuilt payloads, request-context providers, and the bundler escape hatch. +The framework owns discovery, host translation, execution plumbing, devtools, and packaging. +Your plugin still owns its domain services, authorization rules, storage model, and workflows. +It does not need to turn its scheduler, database, or login flow into a framework subsystem. ## Evidence, not vibes -A plugin that builds is not a plugin that works. agent-bundle ships separate proof levels — -route-unit, in-memory MCP, CLI dispatch, packed stdio, packed with source deleted, and -host-install — and each helper stamps the level it carried into its provenance. A pass at one -level is never reported as a receipt for another, and an assertion that needs stronger evidence -than the harness produced is `inconclusive` rather than silently passing. +Use the scaffold's `check` command for its complete deterministic suite. A route test proves +application behavior; a packed-process test additionally checks the installed executable; +a native-host test checks the host integration. These are separate claims. See +[testing](../development/testing.mdx) when adding coverage beyond the starter. ## Where to go next -- [Installation](./installation.mdx) — install the preview tarballs that CI publishes today. -- [Quick start](./quick-start.mdx) — scaffold a project, or write the config by hand. -- [Project structure](./project-structure.mdx) — the conventional `src/` roots and the output layout. -- [Compiler architecture](../concepts/architecture.mdx) — how one route becomes MCP, CLI, and hooks. -- [Authoring](../authoring/index.mdx) — the configuration model and every authorable surface. - -The repository documents the same contracts in more depth: -[Framework mode](https://github.com/ScriptedAlchemy/agent-bundle/blob/main/docs/framework-mode.md) -is the whole authoring model on one screen, and -[Entry conventions](https://github.com/ScriptedAlchemy/agent-bundle/blob/main/docs/entry-conventions.md) -is the full package-build contract. +- [Quick start](./quick-start.mdx): one tool from source file to visible result and test. +- [Project structure](./project-structure.mdx): a composite plugin's authored files and the + distinct source, generated, package, and writable-state roots. +- [Shipping a bundle](../distribution/index.mdx): build, validate, pack the generated npm root, + and install explicitly. + +[Installation](./installation.mdx) explains the framework preview channel. +[Authoring](../authoring/index.mdx) and [compiler architecture](../concepts/architecture.mdx) +are the detailed references, not prerequisites for the first working plugin. diff --git a/website/docs/en/guide/start/project-structure.mdx b/website/docs/en/guide/start/project-structure.mdx index 1f6bc95f8..c36c8e57c 100644 --- a/website/docs/en/guide/start/project-structure.mdx +++ b/website/docs/en/guide/start/project-structure.mdx @@ -1,194 +1,269 @@ --- -description: 'The conventional src/ roots agent-bundle discovers, how config and conventions interact, and where build output lands.' +description: 'A convention-first composite plugin: which files declare routes, how tools and browser views share contracts, and where generated output and writable state belong.' --- # Project structure -An agent-bundle project is an ordinary Node package with one extra file at the root and a -conventional `src/` tree. Nothing here is mandatory: conventions fill the config in when it is -silent, and config always wins when both describe the same thing. +An Agent Bundle project is an ordinary Node package with `agent-bundle.config.ts` and a +conventional source tree. Start with the files your plugin needs. A static Skill does not need +an MCP server; a tool does not need a browser App; an App does not need its own server registry. + +Conventions discover the application. Configuration supplies identity, policy, and explicit +exceptions. Conflicting declarations are diagnosed rather than universally resolved by +"config always wins." ## The layout +This is an **illustrative composite plugin**, not a minimum template. The opening paths are +ordinary authored source; host manifests and executable wrappers belong in generated output. + ```text my-plugin/ -├── agent-bundle.config.ts # project identity, targets, and policy -├── package.json # authoritative release version and package identity -├── assets/ # static files copied byte-for-byte into the artifact root -└── src/ - ├── skills//SKILL.md # one Skill per directory, with its own resources - ├── commands/*.md # host slash-command documents - ├── rules/*.mdc # host rule documents - ├── hooks/*.ts # lifecycle hook handlers referenced from config - ├── mcp/.ts # a handwritten stdio MCP server entry - ├── mcp// # or a generated server, one module per route - │ ├── tools/*.tsx - │ ├── resources/*.tsx - │ ├── prompts/*.tsx - │ ├── apps/*.tsx # browser MCP Apps compiled to self-contained HTML - │ └── layout.tsx # optional per-server layout around this server's routes - ├── scripts/.ts # artifact scripts (.tsx renders via the Agent renderer) - ├── cli.ts # a single package bin - ├── cli/**/*.ts # or a routed CLI, where nesting is the command path - ├── index.ts # the library entry - ├── layout.tsx # optional shared layout around every rendered route - ├── state.ts # project state definition - └── providers/.ts # request-context providers +├── agent-bundle.config.ts +├── package.json +├── tsconfig.json +├── assets/ # optional static assets +├── src/ +│ ├── mcp/ops/ +│ │ ├── tools/ +│ │ │ ├── inspect.tsx # canonical operation + schemas + Agent document +│ │ │ └── inspect.cli.ts # optional CLI projection of that operation +│ │ ├── resources/policy.tsx # an MCP resource +│ │ ├── prompts/review.tsx # an MCP prompt +│ │ ├── apps/dashboard.tsx # browser entry, not an Agent Server Component +│ │ └── layout.tsx # optional shared agent-facing presentation +│ ├── events/tool/ +│ │ ├── before.tsx # semantic tool/before event route +│ │ └── before.preflight.ts # only a gate explicitly re-exported by the route +│ ├── hooks/session-start.ts # optional plain hook referenced from config +│ ├── skills/review/SKILL.md +│ ├── commands/review.md # optional native prompt/command document +│ ├── rules/project.mdc # optional host-supported rule +│ ├── cli/doctor.tsx # a genuinely independent CLI workflow +│ ├── scripts/check-service.ts # plain artifact script +│ ├── providers/project.ts # optional request dependency +│ ├── state.ts # optional framework state definition +│ ├── layout.tsx # optional root document layout +│ ├── components/ # ordinary reusable presentation +│ ├── domain/ # ordinary business logic, clients, policies +│ └── install-bin.ts # optional package-bound installer delegation +└── tests/ + ├── route-unit/ + └── projection/ ``` +There is no authored `application.ts` registry, generated MCP entry, or native hook JSON in this +layout. The compiler derives them where needed. `domain/` and `components/` are organizational +choices, not new framework conventions. Use an explicit `payload` declaration for prebuilt +non-TypeScript assets or native executables; do not assume an arbitrary source directory ships. + ## What each root means -| Path | Surface | Opt out | +| Path | Meaning | Important boundary | | --- | --- | --- | -| `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. 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 `_`. | -| `src/scripts/.ts` | A plain script compiled once to `scripts/.mjs` at the artifact root, shared by every selected host. Nested modules are a hard error (`AB4808`). | Prefix a path segment with `_`, or claim the file with an explicit `scripts` entry. | -| `src/scripts/.tsx` | A rendered script: the async default component receives `argv` and `signal` and renders through the Agent renderer with the CLI output contract. | Rename to `.ts`, prefix a path segment with `_`, or claim the file. | -| `src/cli.ts` | A package bin named after `plugin.name`. | `bin: false` | -| `src/cli/**/*.{ts,tsx}` | Routed CLI commands compiled into one collision-checked command graph and one executable. Nesting is identity: `src/cli/library/audit.ts` runs as ` library audit`. Supersedes the `src/cli.ts` convention. | `bin: false`, `routes.cli: 'conventional'`, or prefix a path segment with `_`. | -| `src/index.ts` | The library output, with declarations. | `lib: false` | -| `src/layout.{ts,tsx}` | Shared document layout: default-exports one component receiving `{ children, route, signal }` that renders `Agent.Result` around every rendered route — generated MCP tools, resources, and prompts, rendered routed-CLI commands, projected MCP commands, and rendered scripts. Event routes and browser Apps are never wrapped. | Rename to `_layout.tsx`. | -| `src/mcp//layout.{ts,tsx}` | Per-server layout nested inside the root layout for that generated server's routes. | Rename to `_layout.tsx`, or set `routes.servers.` to a non-generated mode. | -| `src/state.ts` | Project state: default-exports `defineState`. Generated MCP, routed-CLI, and rendered-script request scopes mount it. | `state: false`, or rename to `_state.ts`. | -| `src/providers/.{ts,tsx}` | A request-context provider mounted at `providers.` on the request handle; its factory receives the request's identity, lineage, and read-only state/notice handles. | Prefix the file with `_`. | -| `assets/` | Static resources copied byte-for-byte into the artifact root's `assets/` directory, once for every selected host. | Declare a top-level `assets` list instead. | - -Route and package entry conventions match `.ts` and `.tsx` files exactly; the state convention -is specifically `src/state.ts`. Discovered entries carry `provenance.kind: 'conventional'` in the -normalized model, so `agent-bundle inspect` tells you whether a file was picked up by convention -or claimed by config. +| `src/mcp//tools/*.{ts,tsx}` | Tools on the generated server. | A rendered tool exports schemas, optional static `config`, and its default component. No manual registration. | +| `src/mcp//tools/.cli.ts` | Named CLI projection of the sibling tool. | Reuses the tool; it is not another MCP route. Optional `mapInput` changes CLI input mapping, not the operation registry. | +| `src/mcp//resources/*` and `prompts/*` | MCP resources and prompts. | These are not tools; their protocol metadata and result contracts differ. | +| `src/mcp//apps/*.{ts,tsx}` | Browser App entries. | Declare `config.resourceUri`; the framework compiles and registers self-contained HTML. | +| `src/events/**` | Supported semantic event routes, such as `tool/before`. | The path names a supported event family, not an arbitrary event bus topic. Native envelopes are adapter-owned. | +| `src/hooks/*.ts` | Plain handlers referenced by `hooks` configuration. | The directory alone does not register them. Use the public `HookHandler` contract; no JSX or custom stdin wrapper is required. | +| `src/skills//SKILL.md` | Static Skill plus its resource files. | A Skill can ship without the rendered runtime. See [Skills](../authoring/skills.mdx) for rendered and host-specific forms. | +| `src/commands/*.md` | Native command/prompt documents. | These are not `src/cli/` commands. Availability and frontmatter are host-specific. | +| `src/rules/*.mdc` | Rule documents where the host supports them. | A selected target is not a promise that it supports rules. | +| `src/cli/**/*.{ts,tsx}` | Independent routed CLI commands. | Nesting is the command path. Prefer a tool's `.cli.ts` projection when it is the same operation. | +| `src/scripts/.ts` / `.tsx` | Plain / rendered artifact scripts. | Scripts are flat. Put shared helpers outside this conventional root or under a private path. Rendered scripts receive `argv` and `signal`. | +| `src/providers/.{ts,tsx}` | Request-context provider. | Read the generated provider value through `agent()`; do not add another global service registry. | +| `src/state.ts` | Optional `defineState` declaration. | Framework state is optional and does not take ownership of your domain database. `state: false` disables discovery. | +| `src/layout.{ts,tsx}` | Root agent-document layout. | Wraps rendered routes, not native event responses or browser Apps. | +| `src/mcp//layout.{ts,tsx}` | Server document layout inside the root layout. | Applies to that generated server's routes. | +| `assets/` | Conventional static assets. | Copied under the artifact's `assets/`; explicit configuration can narrow the selection. | + +Private path segments beginning with `_` or `.` and declaration files are excluded from route +discovery. A `before.preflight.ts` file is not special merely because of its name: the event +route must re-export its gate through the supported preflight contract. Do not register a plain +hook and a semantic route for the same event as two accidental implementations. See +[hooks](../authoring/hooks.mdx) for runtime, target, provider, and preflight choices. + +Route-specific `config` exports use a bounded static grammar. Keep runtime work in the handler +or domain module; do not execute it to populate metadata. Keep schemas authoritative rather +than reconstructing protocol types independently in the CLI and browser. + +### Adding an interactive App + +A tool's `Agent.*` JSX describes the agent-facing document. An MCP App entry runs in the +browser and owns its DOM or React UI. Do not import a server route into the browser: that can +pull Node APIs, domain services, and server-only dependencies into the wrong runtime. + +Connect the two through the existing App resource binding. For a browser entry at +`src/mcp/ops/apps/dashboard.tsx`, declare its resource URI in that entry: + +```ts +import type { AppRouteConfig } from 'agent-bundle'; + +export const config = { + resourceUri: 'ui://my-plugin/dashboard.html', +} satisfies AppRouteConfig; +``` + +This is metadata for the browser entry, not a complete UI. The default HTML provides `#root`; +use an explicit template when your bootstrap needs a different shell. The tool can reference +the App without repeating the URI string: + +```ts +// Metadata in src/mcp/ops/tools/inspect.tsx +import type { ToolConfig } from 'agent-bundle'; +import { appResourceUri } from 'agent-bundle/routes'; + +export const config = { + description: 'Inspect project status.', + annotations: { readOnlyHint: true }, + _meta: { ui: { resourceUri: appResourceUri('dashboard') } }, +} satisfies ToolConfig; +``` + +Use `createAppClient` from `agent-bundle/app` in the browser. Its opening-input/result/error +listeners and tool calls are the integration boundary; do not recreate `postMessage` transport, +request-ID maps, or an MCP client. Register opening listeners before connecting. Render the +opening result supplied by the host instead of automatically calling a mutation again on mount. +Dispose the client and subscriptions when the owning UI is retired. + +Generated route declarations supply App call types. They must be current and included in the +browser's TypeScript project; they do not replace validation of untrusted data. Pure +presentation components and validated data can be shared where their imports are browser-safe. +A Node-rendered document component is not automatically a DOM component just because both use +JSX. + +To expose the same App through the optional production browser surface, configure `web.apps` +with its existing `server/app` identity and opening tool. There is no second `src/web/` registry. +See [MCP servers and Apps](../authoring/mcp.mdx), +[the working App example](../../examples/mcp-app.mdx), and +[`web` configuration](../../reference/configuration.mdx#web) for complete examples and policy. +Browser presentation and the host projection that launches its server are separate choices. ## Config versus conventions -The config holds what no single file can own — project identity, target selection, policy, and -which declared MCP Apps the artifact-resident [`web`](../../reference/configuration.mdx#web) -host exposes: +The conventional starting point remains: ```ts twoslash import { defineConfig } from 'agent-bundle/config'; export default defineConfig({ - plugin: { description: 'Evidence-backed project tools.', name: 'my-plugin' }, - targets: ['portable', 'codex', 'claude'], + plugin: { name: 'my-plugin', description: 'Project tools for an agent.' }, + targets: ['portable', 'claude', 'codex'], }); ``` -Add an explicit declaration only when you need something the convention cannot express — a -different path, a target restriction, or an opt-out: +Add explicit configuration only for something the convention cannot express: a target-scoped +plain hook, prebuilt payload, remote server, nonstandard path, package-only bin, or policy. +Required capabilities still need a supported host or an explicit restriction. -```ts twoslash -import { defineConfig } from 'agent-bundle/config'; +A handwritten `src/mcp/.ts` entry is an interoperability path for a declared server. +Combining it with generated routes for the same server needs an explicit mode decision; do +not rely on filesystem order. Likewise, `src/cli.ts` and `src/cli/` are alternative CLI modes. +`src/index.ts` is an optional library entry, not application registration. `bin: false` and +`lib: false` opt out of those package conventions. -export default defineConfig({ - plugin: { description: 'Evidence-backed project tools.', name: 'my-plugin' }, - scripts: { - // Restricted to one target, so it cannot ride the convention. - 'detect-risk': { entry: './src/scripts/detect-risk.ts', targets: ['portable'] }, - }, - targets: ['portable', 'codex', 'claude'], -}); +For declarations that intentionally differ from conventions, inspect the resulting graph rather +than guessing which file won: + +```sh +npx --no-install agent-bundle inspect --routes +npx --no-install agent-bundle validate ``` -Source validation reports **informational** nudges — never errors — when a project shows a -pre-convention pattern: `AB4730` for a self-connecting stdio entry that a default-exported -factory would upgrade to the framework lifecycle shell, and `AB4731` / `AB4732` / `AB4733` when -`src/cli.ts`, `src/index.ts`, or `src/mcp/.ts` exists but explicit configuration -shadows it. The `bin: false` and `lib: false` opt-outs stay silent. +The compiler must already be installed in this project. Details of source selection and +migration diagnostics are in [configuration](../authoring/index.mdx) and +[package entries](../authoring/package-entries.mdx). ## Where output lands -`agent-bundle build` writes two independent things. +Keep these responsibilities separate: + +| Location | Owner and purpose | +| --- | --- | +| `src/`, config, `package.json` | Authored application and package identity. | +| `.agent-bundle/` | Generated route declarations and development machinery. Do not treat it as an authored registry or a durable application-data contract. | +| `artifact/` by default | The validated composite plugin tree. | +| `dist/` when package output is enabled | The generated npm root: artifact bytes plus package metadata and package-only entries. | +| Resolved writable state root | Framework state and deliberately selected application-owned data; separate from installed code. | ### The composite plugin root -One directory at the artifact output, whatever `targets` selects. The CLI defaults that output to -`artifact/`, so it never collides with the package build below; `output.distPath` or `--output` -moves it. Amp reads its nested `.amp/plugins//` directory; the other selected hosts read the -composite root as their plugin root. There is no `artifact//` partition. Omit `targets` and -the root carries the `portable` projection alone. +A schematic output is: ```text artifact/ -├── .amp/plugins//index.js # amp directory-plugin factory -├── .claude-plugin/plugin.json # claude, with marketplace.json beside it -├── .codex-plugin/plugin.json # codex, with hooks.json and mcp.json beside it -├── .agents/plugins/marketplace.json # codex marketplace -├── .cursor-plugin/plugin.json # cursor, with hooks.json and mcp.json beside it -├── .mcp.json # claude MCP document -├── plugin.json # portable (Agent Plugins) manifest -├── mcp.json # portable MCP document -├── hooks/ -│ ├── hooks.json # claude hook document -│ ├── .mjs # wrapper for a hook one selected host reaches -│ ├── ..mjs # one wrapper per host for a hook several reach -│ └── hooks-flight.mjs -├── mcp/mcp--.mjs # compiled MCP entries, emitted once -├── bin/.mjs # routed CLI and/or web -├── scripts/, skills/, commands/, rules/, assets/, mcp-apps/ # components, emitted once -├── INSTALL.md # one section per selected host -├── install.mjs # when cursor or portable is selected -└── agent-bundle.manifest.json # artifact index: identity, projections, executables +├── agent-bundle.manifest.json +├── agent-bundle.compile-evidence.json +├── INSTALL.md +├── .claude-plugin/ # selected host manifests +├── .codex-plugin/ +├── .cursor-plugin/ +├── .amp/plugins// # Amp's native directory plugin, when selected +├── plugin.json # portable manifest, when selected +├── mcp/ # compiled server entries and their runtime files +├── hooks/ # generated native wrappers and hook documents +├── bin/.mjs # routed CLI / web executable, when declared +└── skills/, scripts/, assets/, mcp-apps/, ... ``` -Host manifests live in their dotfolders; `skills/`, `hooks/`, `mcp/`, `scripts/`, `bin/`, and -`assets/` are emitted once and shared. Hook and MCP documents appear when the project declares -hooks or MCP servers — plus one empty Codex or Cursor document when a Hook or MCP server reaches -another selected host's conventional `hooks/hooks.json`, `.mcp.json`, or `mcp.json` path, so folder -discovery never loads the other host's file — and `bin/` when it has a routed CLI, when -[`web`](../../reference/configuration.mdx#web) is configured, or both. Two selected hosts that -would write the same path with different bytes cannot share the root, and the build fails with -`AB4103`; a command or rule scoped to some of the selected hosts but sitting in a -directory another selected host scans is `AB4105`. Both recover by making the component -identical for every selected host, or by building those hosts into separate artifacts. - -`agent-bundle.manifest.json` records every emitted file with its SHA-256, so artifact validation -is content-addressed rather than a guess. Compiled surfaces are attributed to the composite -identity — the selected hosts sorted and joined with `+`, such as `claude+codex` — and the order -of `targets` never changes the output. - -`output.distPath` moves the root; it never changes the framework-owned layout inside it. -Precedence is the CLI `--output`, then `output.distPath`, then the default — `artifact` for -`agent-bundle build`, which also emits the package build, and `dist` for the programmatic -`build()` without `packageOutputs`. Values must be non-empty, project-root-contained relative -POSIX paths. +Only relevant declared surfaces are emitted. Exact native documents and additional runtime +files are recorded by the manifest; this tree is not an inventory to reconstruct in application +code. There is no `artifact//` partition. Amp uses its nested native directory, while the +framework's manifest-aware installation entry accepts the composite root and selects the +correct host surface. + +`output.distPath` or CLI `--output` moves the composite root without changing its internal +layout. CLI precedence is `--output`, then configuration, then `artifact/`. The programmatic +`build()` API has separate package-output/default semantics; use its reference rather than +copying a CLI default into a custom build harness. + +The manifest records file digests and canonical executable identities. Reordering targets does +not create another application. Conflicting bytes or unintended cross-host discovery are +validation problems, not a reason to hand-edit the emitted manifests. See +[targets and artifacts](../../reference/targets-artifacts.mdx). ### The npm package build -When the project declares `bin`/`lib` — or provides them by convention — the same build also -writes the node-consumable package build under `dist/`: +`dist/` is the **complete generated npm package root**, not merely a folder of JavaScript: ```text dist/ -├── bin/.js # self-executing ESM, shebang, executable bit -├── .js # the library entry -└── **/*.d.ts # declarations, when lib.dts is on +├── package.json # generated package-relative paths and bin map +├── agent-bundle.manifest.json +├── INSTALL.md +├── ... # the composite artifact copied unchanged +├── bin/.mjs # the same generated routed CLI, if present +├── bin/.js # optional explicit package-only executable +└── .js, .d.ts # optional library output ``` -`dist` is a mandatory-ignored directory: package outputs never enter project source snapshots or -Skill and asset discovery. The two outputs must not overlap: pointing `output.distPath` or -`--output` at `dist` on a project with package entries is `AB4706`. The default already keeps -them apart, and spelling it out is harmless: +A routed CLI is not rebuilt into a competing `.js` implementation for npm. The generated +`package.json` points at the artifact executable. Explicit package-only bins and library entries +are different outputs and keep their own compilation. -```ts twoslash -import { defineConfig } from 'agent-bundle/config'; +The composite and npm outputs must not overlap; putting the artifact at `dist/` when package +output also occupies it is invalid. Build outputs are not source inputs. Pack the generated +npm root, not the source repository or a guessed nested `dist/artifact/` directory. Follow +[shipping a bundle](../distribution/index.mdx) for validation and installation. -export default defineConfig({ - output: { distPath: 'artifact' }, - plugin: { description: 'A CLI plus a plugin.', name: 'my-plugin' }, - targets: ['portable', 'claude'], -}); -``` +### Writable state is not installed code + +Inside a request, use the framework-provided plugin/context binding. Standalone code can use +the documented public `resolvePluginRoot` runtime resolver, which distinguishes `root` from +`stateRoot`; `AGENT_BUNDLE_STATE_ROOT` is independent of the code-root override. + +Do not place runtime caches, refreshed credentials, or databases under the installed code tree +just because their loader lives there. Application-owned data keeps its own schema and explicit +migration/override policy, and must not collide with framework storage. The framework does not +implicitly adopt or purge arbitrary plugin data. See +[configuration and state](../authoring/index.mdx) and +[installation lifecycle](../distribution/installation.mdx). ## Next steps -- [Compiler architecture](../concepts/architecture.mdx) — how these roots - become a route graph, host projections, and one composite artifact. -- [Configuration model](../authoring/index.mdx) — the full config surface. -- [Skills](../authoring/skills.mdx), [Hooks](../authoring/hooks.mdx), - [MCP servers and Apps](../authoring/mcp.mdx) — one page per surface. -- [Scripts and assets](../authoring/scripts-assets.mdx) and - [Package entries](../authoring/package-entries.mdx) — the rest of the build output. +[Quick start](./quick-start.mdx) exercises a real conventional route. +[Skills](../authoring/skills.mdx), [hooks](../authoring/hooks.mdx), +[MCP](../authoring/mcp.mdx), and [scripts/assets](../authoring/scripts-assets.mdx) specify each +surface. Read [compiler architecture](../concepts/architecture.mdx) for implementation details, +not as another setup step. diff --git a/website/docs/en/guide/start/quick-start.mdx b/website/docs/en/guide/start/quick-start.mdx index 55be5353c..ed8297f05 100644 --- a/website/docs/en/guide/start/quick-start.mdx +++ b/website/docs/en/guide/start/quick-start.mdx @@ -1,138 +1,233 @@ --- -description: 'Scaffold an agent-bundle project or write agent-bundle.config.ts by hand, then build and run the developer Workbench.' +description: 'Create a plugin, add one conventional MCP tool, inspect its rendered result, test it, and expose the same operation as a CLI command.' --- # Quick start -There are two ways in. The scaffolder emits a project that already passes its own `check`; the -manual path is four lines of config in an existing repository. +This walkthrough uses the MCP starter. It adds one tool without a server factory, registration +array, custom transport, or second build configuration. The example needs no agent account. + +Install [Node.js 22.19 or later](./installation.mdx) and choose a commit whose **Package preview** +workflow succeeded. Use that commit's immutable preview SHA below, not an npm package selected +only by the unqualified `agent-bundle` name. ## Scaffold a project -The fastest start is `create-agent-bundle`. It prompts for a name, a template, and the host -targets: +Replace `` with that commit SHA: ```sh -npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@ \ - my-plugin +AB_SHA='' +npx "https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@${AB_SHA}" \ + my-plugin --template mcp-server --targets portable,claude,codex +cd my-plugin +npm install +npm run check +``` + +Naming both the directory and template selects the scripted path. The preview scaffolder +chooses the compiler/runtime pair from the same commit. Commit the generated lockfile; later +clean checkouts can use `npm ci`. The [installation guide](./installation.mdx) explains preview +selection and the separately versioned compiler/runtime pairing used by released scaffolders. + +### Templates + +| Template | Use it for | +| --- | --- | +| `minimal` | Static Skills. No MCP server or React runtime is required. | +| `mcp-server` | Conventional MCP tools with route/projection tests. The current starter also demonstrates an optional library export and an artifact script. | +| `cli-tool` | A standalone routed CLI, with a script and library example. | + +The current scaffolder accepts `portable`, `claude`, `codex`, and `cursor`. The compiler also +supports `amp`; select an accepted scaffold target, then explicitly set the desired targets in +`agent-bundle.config.ts` when using Amp. Adding a native target does not imply support for that +host in the live-development proxy. See [host installation](../distribution/installation.mdx). + +## Add your first tool + +The starter already has a `status` server with a `report-status` tool. Add +`src/mcp/status/tools/hello.tsx` beside it: + +```tsx +import { Agent } from '@agent-bundle/runtime'; +import type { ToolConfig, ToolRouteProps } from 'agent-bundle'; +import { z } from 'zod'; + +export const config = { + description: 'Return a greeting without changing anything.', + annotations: { readOnlyHint: true }, +} satisfies ToolConfig; + +export const inputSchema = z.object({ name: z.string().min(1) }).strict(); +export const resultSchema = z.object({ message: z.string() }).strict(); + +export default async function Hello({ input }: ToolRouteProps) { + const result = { message: `Hello, ${input.name}.` }; + return ( + + {result.message} + + ); +} ``` -Once npm releases exist, this becomes `npm create agent-bundle`. Until then, use a commit SHA or -PR number from the [preview channel](./installation.mdx). +The path declares the `hello` tool on the `status` server; its framework route ID is +`tool:status/hello`. `value` is the structured result, while the children describe its +agent-facing presentation. Keep the result JSON-compatible and describe its actual shape with +`resultSchema`. -A run that names both a directory and a template is treated as scripted and asks nothing — the -remaining values fall back to their defaults: +Do not add this tool to `agent-bundle.config.ts` or call `registerTool`. Adding the route file +is the registration. Your domain implementation can live outside the route directory and be +imported normally; it does not need another operation registry. + +## Build, or work interactively ```sh -npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@ \ - my-plugin \ - --template mcp-server \ - --targets portable,codex,claude +npm run dev -- --open ``` -### Templates +In Workbench's **Application** tree, select the `hello` tool on `status`, enter the input, and +invoke it: -| Template | What you get | -| --- | --- | -| `minimal` | A Skills-only plugin: one `src/skills//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 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 -against the entry conventions from the start. The `mcp-server` template also starts with the -consumer test harness, each pool labeled with the proof level it carries. - -Preview scaffolders pin `agent-bundle` and `@agent-bundle/runtime` to one commit SHA. An -npm-installed scaffolder instead reads the exact compiler/runtime pair from its packed optional -peer metadata; those versions are independent, so a compiler `0.2.0` release can correctly select -runtime `0.1.0`. A `--framework-version` used with a runtime template must match that recorded -compiler version, or scaffolding stops before writing files. See the -[create-agent-bundle README](https://github.com/ScriptedAlchemy/agent-bundle/blob/main/packages/create-agent-bundle/README.md) -for every flag. +```json +{ "name": "Ada" } +``` -## Or write the config by hand +The rendered document should say `Hello, Ada.` and its structured result should contain +`{"message":"Hello, Ada."}`. **Trace** shows invocations, **Problems** shows build diagnostics, +and **Advanced** holds lower-level inspection. A normal route invocation is not proof that an +external host has installed or called the plugin. -Describe the plugin in `agent-bundle.config.ts` at the project root: +Edit the greeting and let the rebuild complete before invoking it again. An invalid edit keeps +the last good build available with diagnostics; previous output is not evidence that the new +source compiled. Workbench does not need to repeat a mutation automatically to refresh a view. -```ts twoslash -import { defineConfig } from 'agent-bundle/config'; +For a one-off build instead of the dev server: -export default defineConfig({ - plugin: { name: 'my-plugin', description: 'What it does.' }, - targets: ['claude', 'codex', 'cursor'], - skills: ['src/skills/*'], - hooks: { sessionStart: { handler: './src/session-start.ts' } }, - mcp: { servers: { tools: { entry: './src/mcp.ts' } } }, -}); +```sh +npm run build ``` -Most projects need even less than that, because the `src/` conventions fill the config in when -it is silent: +## Test the route -```ts twoslash -import { defineConfig } from 'agent-bundle/config'; +Add `tests/route-unit/hello.test.ts`: -export default defineConfig({ - plugin: { description: 'Evidence-backed project tools.', name: 'my-plugin' }, - targets: ['portable', 'codex', 'claude'], +```ts +import { expect, it } from '@rstest/core'; +import { renderRoute } from 'agent-bundle/test'; + +it('returns the greeting as structured data', async () => { + const rendered = await renderRoute('tool:status/hello', { + input: { name: 'Ada' }, + }); + expect(rendered.result).toEqual({ message: 'Hello, Ada.' }); }); ``` -`targets` selects the host projections the one artifact root carries — `amp`, `claude`, `codex`, -`cursor`, `portable`; omit it and the root carries `portable` alone. The release version comes -from `package.json`. A `plugin.version` field still works as a deprecated compatibility axis, but -a value that disagrees with `package.json` reports the `AB4008` warning. +Run the existing aggregate command: -## Build, or work interactively +```sh +npm run check +``` + +In the current MCP starter, `npm test` alone excludes route and projection tests. `check` runs +validation, build, typecheck, and all three test groups. Use it for the complete starter gate; +`npm run test:routes` is the focused route loop. More proof levels, including real MCP processes +and browser Apps, are covered in [testing](../development/testing.mdx). + +The generated `.agent-bundle/routes.d.ts` must be included in the TypeScript project consuming +route/provider/App types. It is generated, not an authored registry. For a standalone typecheck +from a clean tree or after adding/renaming routes, refresh it first: ```sh -npx agent-bundle build --root . # write the composite plugin root to artifact/ -npx agent-bundle dev --root . # local workbench with live rebuilds +npm run validate +npm run typecheck ``` -`build` validates the project and writes the artifact root, plus the `bin`/`lib` package build when -declared. `dev` serves the loopback developer Workbench and rebuilds as inputs change. Use its -Application tree to select a tool, event, CLI command, script, App, Skill, rule, or command; run -executable leaves and inspect the rendered Agent Document first. Trace shows this session's -invocations, Problems holds diagnostics, and Advanced contains evals, artifact inspection, -protocol inspection, host diagnostics, and raw logs. +An old declaration file merely existing is not a freshness check. The starter's full `check` +already puts generation ahead of typechecking. -## Inspect what the compiler decided +## Reuse the tool as a CLI command + +Add `src/mcp/status/tools/hello.cli.ts`: + +```ts +import type { CliProjectionConfig } from 'agent-bundle/routes'; + +export const config = { + command: ['hello'], +} satisfies CliProjectionConfig; +``` + +This is a projection of the sibling tool, not another tool or handler. Rebuild, then run the +artifact's generated executable: ```sh -npx agent-bundle inspect --root . # normalized config and host projection plans -npx agent-bundle inspect --root . --skills # add the skill focus -npx agent-bundle validate --root . # check project source +npm run build +node artifact/bin/my-plugin.mjs hello --name Ada ``` -`inspect` reads source configuration and shows the normalized model — which is where you confirm -that a convention was actually picked up. +The same `inputSchema`, route implementation, and result are used. No extra `src/cli/hello.ts` +is needed. Use `src/cli/` for a genuinely independent CLI workflow. -## Install the result +Automatic flags support a bounded schema grammar. A rich nested/union schema is not guaranteed +to support this named projection; do not copy or weaken the tool schema to make flags work. +See [package entries](../authoring/package-entries.mdx) for the supported grammar and the +existing bulk MCP-command JSON-input path. + +## Or write the config by hand -The artifact root carries one generated `INSTALL.md`, a section per selected host, with commands -that use the bundle's real plugin and marketplace names. Every host installs the same directory, -so `--from` always names the root. With the `portable`, `codex`, and `claude` targets built -above, the host installs are: +In an existing package, install a matched [framework/runtime pair](./installation.mdx) and the +rendering/schema dependencies used by your code. A conventional route does not require a +`mcp.servers` entry: + +```ts twoslash +import { defineConfig } from 'agent-bundle/config'; + +export default defineConfig({ + plugin: { name: 'my-plugin', description: 'Project tools for an agent.' }, + targets: ['portable', 'claude', 'codex'], +}); +``` + +Keep the version in `package.json`. Omitted targets select only `portable`. Custom local, +prebuilt, and remote servers remain [explicit modes](../authoring/mcp.mdx); do not combine a +handwritten server and generated routes under one name and rely on silent precedence. + +## Inspect what the compiler decided + +Run these from a project where the intended compiler is already installed: ```sh -npx agent-bundle install claude --from artifact --scope user -npx agent-bundle install codex --from artifact -node artifact/install.mjs # the portable pack, via its generated installer +npx --no-install agent-bundle inspect --routes +npx --no-install agent-bundle validate +npx --no-install agent-bundle validate --artifact artifact ``` -Add `cursor` to `targets` and the same root gains `.cursor-plugin/`; `npx agent-bundle install -cursor --from artifact` installs it the same way. +The first two read the authored project. The last checks the built composite artifact without +needing its source. Use the route ID to connect source, Workbench, and test output. + +## Install the result -For an install-free development loop against Claude Code: +Read the generated `artifact/INSTALL.md`. It contains installation commands for the selected +hosts and the plugin's actual names. From this developer project, the installed compiler can +also perform an explicit installation: ```sh -claude --plugin-dir artifact plugin list --json +npx --no-install agent-bundle install claude --from artifact --scope user ``` +This is a host mutation, not part of `build` or `dev`. Choose the host and scope intentionally. +Amp's native plugin lives in a nested directory; the framework installer resolves that from +the composite root. Follow the generated instructions rather than assuming identical native +install roots across hosts. + +For npm delivery, use the [generated npm root and prepack gate](../distribution/index.mdx). +Consumers can follow the delivered `INSTALL.md` or use a package-bound installer the plugin +explicitly supplies. They should not need to fetch an unrelated npm package to install it. + ## Next steps -- [Project structure](./project-structure.mdx) — what each `src/` root means and where output lands. -- [Configuration model](../authoring/index.mdx) — every config field and what owns it. -- [Skills](../authoring/skills.mdx) — the first surface most plugins author. +[Project structure](./project-structure.mdx) shows how tools, CLI projections, hooks, providers, +state, Skills, and browser Apps fit together. The [MCP App example](../../examples/mcp-app.mdx) +shows an interactive view over a real tool result; [hooks](../authoring/hooks.mdx) explains when +to use a plain handler versus a semantic event route. diff --git a/website/docs/zh/guide/distribution/index.mdx b/website/docs/zh/guide/distribution/index.mdx index 228033a87..a1a22240c 100644 --- a/website/docs/zh/guide/distribution/index.mdx +++ b/website/docs/zh/guide/distribution/index.mdx @@ -1,88 +1,170 @@ --- -description: 'agent-bundle 项目如何变成宿主可以安装的东西：构建、校验，并交付每个所选宿主都读取的那一个组合插件根目录。' +description: '构建并校验组合插件，按需打包生成的 npm 根目录，并提供无需第二套编译器的显式安装路径。' --- # 交付捆绑包 -`agent-bundle build` 输出**一个组合插件根目录**——默认是 `artifact/`——这个根目录就是分发单位。构建之后 -没有额外的打包步骤，也没有逐宿主的重新打包脚本：根目录就是你复制、发布或交给宿主 CLI 的那个目录， -`targets` 选中的每个宿主都把同一个目录当作自己的插件根目录来读取。 +有两种分发形式，它们包含同一份编译后的插件： -```sh -npx agent-bundle build --root . --output artifact -``` +| 交付物 | 用途 | +| --- | --- | +| 默认位于 `artifact/` 的组合产物 | 复制已构建插件，或遵循生成的原生安装说明。 | +| 启用包输出时位于 `dist/` 的生成式 npm 根 | 打包 npm tarball，其中包含产物、包元数据和包专用入口。 | + +两者都不需要手写逐宿主重新打包器。npm 仍然需要正常的**打包步骤**； +该步骤必须针对生成的包根执行，而不是源码项目或另一份应用实现。 + +下面的 `npx --no-install` 命令运行已经安装在开发项目中的编译器，刻意避免按未限定的 `agent-bundle` +名称下载包。支持的预览或正式版本选择方式见[框架安装](../start/installation.mdx)。 ## 流水线 -| 步骤 | 命令 | 产出什么 | -| --- | --- | --- | -| 构建 | `agent-bundle build` | 一个承载全部所选宿主投影的组合插件根目录；当项目声明了 `bin`/`lib` 时，还有 `dist/` 包构建。 | -| 校验 | `agent-bundle validate --artifact --strict` | 内容寻址地证明输出字节与清单一致，外加在所选宿主发布了校验器时的宿主工具结论。 | -| 安装 | `agent-bundle install --from ` | 把捆绑包注册进 Claude、Codex 或 Cursor——三者都从同一个根目录安装。 | +```sh +npx --no-install agent-bundle build --output artifact +npx --no-install agent-bundle validate --artifact artifact --strict +``` + +| 步骤 | 能说明什么 | +| --- | --- | +| 源码校验与构建 | 声明可以编译为所选投影；成功构建不是原生宿主执行证据。 | +| 产物校验 | 纯组合产物的文件和摘要与清单及适用规则一致；宿主工具检查取决于校验选项和可用工具。 | +| 应用与集成测试 | 操作行为符合预期；更强的打包进程或原生宿主结论需要各自的测试。 | +| 显式安装 | 所选宿主按支持的作用域与所有权规则获得正确投影。 | -构建在写出任何东西之前就已经校验过项目，因此针对源码单独运行一次 `validate` 更像是快速的预检，而不是 -必需的阶段。真正有意思的是校验**产物**，因为它完全不需要项目源码。 +源码 `validate` 对编辑和类型检查很有用，但不能代替校验交付物。 +`validate --artifact` 不需要源码项目。安装是独立的操作者动作，构建插件不应把它注册到全局宿主。 ### 根目录如何编译 -构建先为每个所选宿主投影做规划，再按路径把它们合并成一棵树——两个投影只有在字节一致时才能共享同一路径 -（`AB4103`），而只面向部分宿主的组件不能放在另一个所选宿主会发现它的位置（`AB4105`）。随后它把编译产出面 -最多分两个阶段降级到同一个暂存根目录，待产物校验通过后原子地发布： - -1. **MCP Apps**——浏览器环境，通过 `@rsbuild/core` 编译。只有当项目声明了 App 路由时这一阶段才存在，并且 - 始终最先运行：MCP 入口会内嵌它产出的 HTML。 -2. **智能体宿主面**——路由式 CLI bin、打包的脚本、hook 包装器、MCP stdio 入口，以及每个面各自的 - react-server Flight worker，全部一起通过**一个 Rslib 实例**降级（每个输出一个 Rsbuild environment， - 一个 Rspack 多编译器）。宿主面在运行时按文件名找到它的 worker，因此阶段内二者无需排序；每个面为清单 - 保留各自的源码证据。 +编译器发现应用、解析所选宿主投影、编译所需浏览器和服务器入口，并组装成一棵已校验的树。 +共享路径的字节必须兼容，宿主不能意外发现另一个宿主的组件。 -编译产出面只构建一次，归属于**组合身份**——所选宿主按名称排序并以 `+` 连接，例如 `claude+codex`—— -绝不会逐宿主各编译一次。两个阶段与包专用的库入口、手写 bin 以同样的方式合成打包器配置——profile、 -`tools.rsbuild`、`tools.rspack`，最后是框架不变量——见 -[`tools`](../../reference/configuration.mdx#tools)。 -`agent-bundle inspect --bundler` 会打印每个编译输出降级后的 Rspack 配置；它的 `output.path` 就是产物输出本身。 +可执行文件、启动参数以及所属服务器或 App 由生成清单确定，不应由消费者探测文件名来重建。 +不要从原生 `mcp.json` 的第一个参数推断服务器命令，不要猜测 `artifact//` 目录， +也不要在编译后重命名生成的可执行文件。 +进阶编译细节见[架构](../concepts/architecture.mdx)和[产物校验](./validation.mdx)。 ## 根目录里发布了什么 -Amp 目录插件位于 `.amp/plugins//`；其他宿主清单位于根目录下各自的点目录中 -（`.claude-plugin/`、`.codex-plugin/`、`.cursor-plugin/`，以及 portable 的 `plugin.json`），各自指向 -自己的钩子与 MCP 文档；而 `skills/`、`hooks/`、`mcp/`、`scripts/`、`bin/` 与 -`assets/` 是共享的，只输出一次。完整的目录树与各宿主的文档位置见 -[Target 与产物](../../reference/targets-artifacts.mdx)。 +组合产物包含所选原生清单、共享组件文件、编译入口、`agent-bundle.manifest.json`、持久化编译证据， +以及适用时生成的 `INSTALL.md`。它使用插件的真实名称，而不是消费者需要替换的模板名称。 +输出布局见[项目结构](../start/project-structure.mdx)。 -只要选中了内置宿主，根目录就会携带一份生成的 `INSTALL.md`——每个所选宿主一节，使用捆绑包**真实的** -插件名与市场名，而不是占位符——因此这份文件可以逐字照做。 +**组合根不一定等于宿主的原生安装根。** Amp 目录插件位于 `.amp/plugins//`， +其他内置原生投影从组合根读取各自清单。框架的清单感知 `install --from` 接受组合根， +并解析所选宿主的布局。使用生成的说明，不要要求最终用户理解嵌套目录结构。 -Claude 与 Codex 投影始终包含本地市场清单，正是这一点让它们的公开 CLI 能够直接安装该根目录。选中 `cursor` -或 `portable` 时还会加上一个独立的 `install.mjs`，因为 Cursor 提供了市场管理能力，却没有非交互式的插件 -安装动词。 +选择 `cursor` 或 `portable` 会包含[宿主安装](./installation.mdx)所述的独立 `install.mjs` 路径。 +它是一种有明确说明的安装机制，不代表每个 portable 客户端都支持所有原生钩子或 App 能力。 -`agent-bundle.manifest.json` 记录每个输出文件及其 SHA-256，因此校验比对的是真实字节，而不是检查某个 -路径是否存在。 - -构建是可复现的：对同一份未改动的源码树构建两次，会得到逐字节相同的产物——相同的清单、相同的摘要—— -无论 `--output` 叫什么名字、`targets` 以什么顺序书写，也无论每次构建的暂存目录叫什么名字。打包器写进 -编译入口里的模块标识只由项目根目录推导，绝不会来自暂存目录、输出目录或构建机器上的任何绝对路径，因此 -已安装的副本、预览包与 [`doctor`](./installation.mdx) 的比对在同一源码下看到的都是相同的字节。这些标识 -所命名的生成模块从内存中提供，位于项目根目录下保留的 `.agent-bundle-virtual/` 目录；只要有任何东西占用 -该目录，构建就会拒绝编译。 +把交付代码视为不可变内容。可写框架状态独立于安装代码目录解析。 +领域数据，包括刷新后的会话和应用数据库，需要明确的应用自有位置与迁移策略。 +不要把真实凭据、可变缓存或操作者数据打包成 assets。 ## 面向 npm 的那一半 -同时作为 npm 包发布的项目还有第二份输出 `dist/`，但它不是第二次插件构建。`dist/` 就是 npm 包根目录： -它包含完整的组合产物、`package.json`、标准包文档，以及[包入口](../authoring/package-entries.mdx)所述的 -包专用库入口或手写 bin。 -`validate --artifact` 等仅面向产物的命令仍应接收纯组合产物；清单感知的 `install --from` 路径则接受 npm 根目录。 +对于启用了包输出的项目，例如 MCP starter，`dist/` 包含完整 npm 根：原样复制的已校验产物、 +生成的 `package.json`、标准包文档及声明的包专用 bin 或库输出。 +Tarball 内不会再嵌套一层 `artifact/`。 + +生成式路由 CLI 的 `package.json.bin` 直接指向产物中的 `bin/.mjs`， +操作表面与产物 CLI 相同，包括声明后的 `web`。 +**显式手写的包 bin** 则编译为 `bin/.js`；它们是不同入口种类，不是同一路由 CLI 的两份版本。 + +先运行框架门禁，再打包生成目录： + +```sh +npx --no-install agent-bundle prepack --json +npm pack ./dist --ignore-scripts +``` + +`prepack` 执行发布构建，并校验 dry-run 包清单、入口路径、产物摘要、版本及声明的运行时依赖。 +第二条命令创建实际 tarball。这里的 `--ignore-scripts` 防止打包期间的脚本再次构建另一种产物； +它不表示消费者安装时也会忽略安装脚本。 + +检查生成的 `dist/package.json`、`bin` / `exports` 和 tarball 文件清单。 +不要手改生成清单；修改手写的包或配置输入，再重新构建。 +Starter 是私有开发包；有意进行公开发布时，还需要合适的包元数据，并在重新构建前移除 +`private: true`。本指南不会自动发布任何内容。 + +以构建目录分发的静态插件不需要为了原生安装而虚构一个库或可执行入口。 +选择 npm 分发及其可选入口时，请阅读[包入口](../authoring/package-entries.mdx)。 + +### 消费者安装脚本与依赖 + +构建工具不会自动成为运行时依赖。自包含的生成式 JavaScript 不应依赖源码检出、workspace 别名， +或要求消费者安装编译器。预构建 payload 或明确保留的消费者安装脚本可能确实需要运行时依赖； +应准确声明，而不是为了缩小包体积就把普通生成入口的依赖 externalize。 -对于生成的路由式 CLI，已安装包的 `bin` 直接指向 `bin/.mjs`；该文件从已校验产物原样复制。因此 -npm CLI 与产物 CLI 拥有完全相同的命令（包括 `web`）和完全相同的字节。tarball 中没有嵌套的 -`artifact/` 目录；框架不会并行编译另一份 `dist/bin/.js` 应用，也不会生成相对包的安装器 bin。 +不要意外把相对源码路径的 shell 脚本带入安装包。包构建器支持有界的已记录脚本形式重定位， +并会诊断不支持的形式。如果消费者安装只有加 `--ignore-scripts` 才能通过， +就没有证明承诺的安装生命周期。测试有副作用的脚本时使用隔离 fixture， +不要使用真实凭据或全局宿主配置。 + +### 可选的包绑定安装器 + +要给消费者提供 `my-plugin-install install `，声明一个包专用 bin，并把实现委托给公开框架入口。 +将该入口合并到现有配置，不要覆盖无关条目： + +```ts twoslash +import { defineConfig } from 'agent-bundle/config'; + +export default defineConfig({ + plugin: { name: 'my-plugin', description: 'Project tools for an agent.' }, + targets: ['claude', 'codex', 'cursor'], + bin: { 'my-plugin-install': './src/install-bin.ts' }, +}); +``` + +```ts +// src/install-bin.ts +import { fileURLToPath } from 'node:url'; +import { runInstallCli } from 'agent-bundle/install'; + +export const main = (argv: readonly string[]): Promise => + runInstallCli(argv, { + from: fileURLToPath(new URL('..', import.meta.url)), + name: 'my-plugin-install', + }); +``` + +父目录绑定指向 npm 根中**输出后的** `bin/` 入口。 +运行构建或安装后的形式，不要把直接运行源码文件当作安装证明。 +包构建会打包生命周期实现，消费者无需仅为使用该 bin 而安装编译器。 + +这是显式启用的入口，不是自动添加到每个插件中的安装器。 +它复用 `install`、`uninstall` 和 `doctor`，只绑定一次包根。 +不需要消费者自有的 argv parser、原生配置合并器、根目录搜索循环或私有框架导入。 +支持的 flag 和作用域见[宿主安装](./installation.mdx)。 + +### 证明安装后的包 + +在全新的临时消费者目录中安装实际 tarball，测试它声明的 bin 或指定 MCP 服务器。 +移动或删除源码 fixture，使用不同工作目录，并提供独立可写状态根。 +确认预期工具和代表性结果。直接启动源码树中 `artifact/` 的测试有价值，但不是 npm 安装测试。 + +`validate --artifact` 等仅面向产物的命令应接收**纯组合产物**。 +清单感知的 `install --from` 也接受 npm 根，并在宿主所有权比较中排除 npm 专用元数据。 +不要仅因为两种根目录都含有 `agent-bundle.manifest.json` 就互换使用。 + +使用公开的[打包测试辅助函数](../development/testing.mdx)和规范清单， +不要把私有安装器或原生文档 parser 复制进插件测试 harness。 +原生账号授权与宿主执行仍然需要单独限定证据。 + +## 显式安装 + +消费者遵循交付的 `INSTALL.md`，或者调用插件明确提供的包绑定安装器。 +已经安装编译器的开发者可以使用： + +```sh +npx --no-install agent-bundle install claude --from artifact --scope user +``` -`agent-bundle prepack` 是这一半的门禁：它运行发布构建、以不执行脚本的方式 dry-run `npm pack`，并核实 -打包后的输出、产物哈希、bin 与版本号。 +只选择预期的宿主与作用域。安装 npm 包不等于注册宿主插件；框架 build/prepack 不代表同意修改宿主。 +只读 `doctor` 和卸载计划的行为见[宿主安装](./installation.mdx)。 ## 本章内容 -- [产物校验](./validation.mdx) —— 源码与产物校验，以及各宿主自有工具的贡献。 -- [宿主安装](./installation.mdx) —— 安装到 Claude、Codex 与 Cursor，以及各自接受的安装作用域。 -- [预览包](./preview-packages.mdx) —— 目前代替 npm 的 pkg.pr.new 发布通道。 +- [产物校验](./validation.mdx)：源码检查、产物检查与宿主校验器。 +- [宿主安装](./installation.mdx)：原生根、作用域、凭据、替换和移除。 +- [预览包](./preview-packages.mdx)：当前开发分发通道。 diff --git a/website/docs/zh/guide/start/index.mdx b/website/docs/zh/guide/start/index.mdx index 7df719e37..931453240 100644 --- a/website/docs/zh/guide/start/index.mdx +++ b/website/docs/zh/guide/start/index.mdx @@ -1,89 +1,89 @@ --- -description: 'agent-bundle 将一份带类型的配置编译为 Amp、Claude Code、Codex、Cursor 与可移植 Agent Plugins 格式可安装的产物。' +description: '用约定路由和带类型的结果构建一个智能体宿主插件；宿主投影、开发工具和打包由框架负责。' --- # 介绍 -agent-bundle 把一个智能体插件——由一份带类型的配置描述的 Skills、钩子、MCP 服务器与脚本——编译为 -可安装到 Amp、Claude Code、Codex 与 Cursor 的产物，外加可移植的 Agent Plugins 格式。插件只写 -一次，编译器负责把每个宿主各自的清单与包装层生成到这同一个根目录中。 +Agent Bundle 是用于**构建智能体宿主插件**的元框架。工具、Skills、钩子和视图只编写一次。 +框架发现约定位置的源码，构建可执行入口，并生成所选宿主需要的清单。 -需要 Node.js 22.19 或更高版本。 +从[快速开始](./quick-start.mdx)入手：创建项目，添加一个工具，在 Workbench 中查看渲染结果， +再测试它。不需要先编写 MCP 服务器，也不需要先理解编译器内部架构。 +编译器和 Workbench 需要 Node.js 22.19 或更高版本。 ## 它解决的问题 -每个智能体宿主都想要同一个插件、但要按自己的布局表达：自己的清单文件名、自己表示插件安装根目录的 -占位符写法、自己的钩子文档形状、自己的 MCP 服务器声明。手工维护这些，等于把同一个插件维护好几遍， -而且只有在安装之后才会发现它们互相不一致。 +**宿主（host）**是加载插件的应用，例如 Claude Code、Codex、Cursor 或 Amp。 +**MCP 服务器**通过 Model Context Protocol 暴露工具、资源和提示。 +**MCP App** 是与 MCP 资源或工具关联的浏览器视图。它们是系统中的不同部分，而不是应用的三个别名。 -agent-bundle 把这件事反转过来。宿主专属布局是编译器的职责，因此它不会出现在你的源码树中： +手写复合插件容易积累彼此独立的工具注册表、原生钩子包装器、CLI 处理器、浏览器消息协议和安装脚本。 +Agent Bundle 负责这些集成边界，让应用代码专注于插件本身的功能。 -```sh -npx agent-bundle build --root . +它与约定式应用框架最重要的相似之处是：**文件声明路由**。 + +```text +src/mcp/status/tools/hello.tsx + ↓ + status 服务器上的 hello 工具 + ↓ + 生成的 MCP 入口 · Workbench · 测试 ``` -这一条命令会在 `artifact/` 生成一个复合根目录：Amp 的 `.amp/plugins//` 目录与其他宿主清单 -（`.claude-plugin/`、`.codex-plugin/`、`.cursor-plugin/` -以及可移植格式的 `plugin.json`）覆盖在共享的 `skills/`、`hooks/`、 -`mcp/`、`bin/` 与 `scripts/` 目录之上，外加一份 `INSTALL.md`。`targets` 选择根目录承载哪些宿主投影 -——`amp`、`claude`、`codex`、`cursor`、`portable`；省略时只选择 `portable`。Amp 安装嵌套的生成目录， -其他宿主安装组合根目录。 +添加同目录的 CLI 投影，即可把同一个操作暴露为命令。需要交互式浏览器视图时再添加 App。 +两者都不要求重新实现这个操作。 ## 配置负责什么 -项目根目录下的一份 `agent-bundle.config.ts` 描述整个插件： +约定式项目只需要一份小型 `agent-bundle.config.ts`： ```ts twoslash import { defineConfig } from 'agent-bundle/config'; export default defineConfig({ - plugin: { name: 'my-plugin', description: 'What it does.' }, // [!code highlight] + plugin: { name: 'my-plugin', description: 'Project tools for an agent.' }, targets: ['claude', 'codex', 'cursor'], - skills: ['src/skills/*'], - hooks: { sessionStart: { handler: './src/session-start.ts' } }, - mcp: { servers: { tools: { entry: './src/mcp.ts' } } }, }); ``` -同一份配置还负责 npm 包构建——不需要第二份打包器配置、不需要 bin 垫片、也不需要手写 stdio 生命周期。 -`bin` 与 `lib` 条目（或 `src/cli.ts`、`src/index.ts`、`src/mcp/.ts` 这几个约定）会在插件 -根目录之外一并生成可执行的 `dist/bin/.js` 包与库输出。默认导出服务器工厂函数的 MCP 入口会运行在 -框架自有的 stdio 生命周期之下。`tools.rsbuild` / `tools.rspack` 是唯一的打包器逃生舱。 +插件名是宿主使用的标识，npm 包名可以不同。发布版本来自 `package.json`。 +选择 target 不意味着要在配置中重复声明源码树。 +自定义 MCP 服务器、远程端点、预构建 payload 和包入口仍然受支持，适用于约定无法覆盖的场景； +它们不是编写第一个工具的必需步骤。 + +`targets` 选择投影：`amp`、`claude`、`codex`、`cursor` 或 `portable`；省略时只选择 `portable`。 +选中了某个宿主，不代表它支持所有组件或实时开发功能。 +添加宿主专属能力前，请查看[宿主能力](../../reference/targets-artifacts.mdx)。 ## 编写模型 -agent-bundle 只有一个面向新手的模型，四行就能写完： +| 概念 | 编写内容 | +| --- | --- | +| 路由 | 放在 `src/mcp//tools/` 等约定目录下的文件；路径提供身份。 | +| 配置 | 项目标识、所选宿主、策略与显式例外。 | +| 渲染 | 渲染式路由返回 `Agent.*` 元素，描述面向智能体的内容和结构化结果；浏览器 App 使用浏览器 UI 代码。 | +| 按需使用上下文 | 在请求内部调用 `await agent()`，读取框架上下文与 provider；宿主未提供的信息不会被伪造。 | -1. **编写的源码放在 `src/` 下。** Skills、命令、规则、脚本、MCP 路由、状态与 provider 都有各自约定的 - `src/` 根目录。路径即身份：位于 `src/mcp/curator/tools/status.tsx` 的模块*就是* `curator` 服务器的 - `status` 工具。 -2. **一份小而扁平的配置。** `agent-bundle.config.ts` 只保存项目标识、targets，以及任何单个路由文件都 - 无法拥有的策略。 -3. **JSX 意味着渲染。** 一个可执行路由就是一个 async 默认导出的 Server Component：它完成工作并返回 - `Agent.*` 节点。不存在公开的 `execute`/`render` 分裂。 -4. **按需接入上下文。** 只有在需要 host、session、actor、workspace、capability 或 state 上下文时， - 才在该组件内部调用 `await agent()`。 +静态 Skills 插件**不需要** React runtime 或 MCP 服务器。 +普通钩子可以使用公开的钩子契约，不必使用 JSX。 +Provider、状态和浏览器 App 都是可选能力，而不是每个项目都要复制的样板。 -这条线以上的内容都属于进阶参考：自定义与远程 MCP 服务器模式、预构建 payload、请求上下文 provider， -以及打包器逃生舱。 +框架负责发现、宿主转换、执行基础设施、开发工具和打包。 +插件仍然负责自己的领域服务、授权规则、数据模型与工作流。 +不需要把调度器、数据库或登录流程改造成框架子系统。 ## 证据，而不是感觉 -能构建的插件不等于能工作的插件。agent-bundle 提供彼此独立的证明级别——route-unit、内存内 MCP、 -CLI 派发、打包后的 stdio、删除源码后的打包运行，以及宿主安装——每个辅助函数都会把自己所承载的级别 -写进 provenance。某一级别的通过绝不会被当作另一级别的凭据；当断言所需的证据强于该 harness 实际产生的 -证据时，结果是 `inconclusive`，而不是悄悄通过。 +使用脚手架的 `check` 命令运行完整的确定性测试流程。 +路由测试证明应用行为；打包后的进程测试进一步检查已安装的可执行文件；原生宿主测试检查宿主集成。 +这些是不同的结论。需要扩展 starter 以外的覆盖范围时，请阅读[测试](../development/testing.mdx)。 ## 下一步 -- [安装](./installation.mdx) —— 安装 CI 目前发布的预览包。 -- [快速开始](./quick-start.mdx) —— 使用脚手架，或手写配置。 -- [项目结构](./project-structure.mdx) —— 约定的 `src/` 根目录与输出布局。 -- [编译器架构](../concepts/architecture.mdx) —— 一条路由如何变成 MCP、CLI 与钩子。 -- [编写](../authoring/index.mdx) —— 配置模型与每一种可编写的表面。 - -仓库中对同样的契约有更深入的说明： -[Framework mode](https://github.com/ScriptedAlchemy/agent-bundle/blob/main/docs/framework-mode.md) -用一屏讲完整个编写模型， -[Entry conventions](https://github.com/ScriptedAlchemy/agent-bundle/blob/main/docs/entry-conventions.md) -则是完整的包构建契约。 +- [快速开始](./quick-start.mdx)：从一个工具文件走到可见结果和测试。 +- [项目结构](./project-structure.mdx)：复合插件的源码，以及源码、生成文件、npm 包和可写状态根目录的区别。 +- [交付捆绑包](../distribution/index.mdx)：构建、校验、打包生成的 npm 根目录，并显式安装。 + +[安装](./installation.mdx)说明框架预览通道。 +[编写](../authoring/index.mdx)和[编译器架构](../concepts/architecture.mdx)是详细参考， +不是让第一个插件工作的前置知识。 diff --git a/website/docs/zh/guide/start/project-structure.mdx b/website/docs/zh/guide/start/project-structure.mdx index 9d690b2de..40e721ebb 100644 --- a/website/docs/zh/guide/start/project-structure.mdx +++ b/website/docs/zh/guide/start/project-structure.mdx @@ -1,181 +1,243 @@ --- -description: 'agent-bundle 识别的约定 src/ 根目录、配置与约定之间的关系，以及构建输出的落点。' +description: '约定优先的复合插件：哪些文件声明路由、工具如何与浏览器视图共享契约，以及生成产物和可写状态应该放在哪里。' --- # 项目结构 -一个 agent-bundle 项目就是普通的 Node 包，只是在根目录多了一个文件，并采用约定的 `src/` 目录树。 -这里没有任何东西是强制的：配置沉默时由约定补齐，而当两者描述同一件事时，配置总是胜出。 +Agent Bundle 项目就是普通的 Node 包，加上一份 `agent-bundle.config.ts` 和约定式源码树。 +只创建插件需要的文件：静态 Skill 不需要 MCP 服务器，工具不需要浏览器 App，App 也不需要自己的服务器注册表。 + +约定负责发现应用，配置提供身份、策略和显式例外。 +冲突声明会产生诊断，而不是一律按“配置总是胜出”静默处理。 ## 目录布局 +下面是**复合插件的示意结构**，不是最小模板。这里是普通的手写源码；宿主清单和可执行包装器属于生成输出。 + ```text my-plugin/ -├── agent-bundle.config.ts # 项目标识、targets 与策略 -├── package.json # 权威的发布版本号与包标识 -├── assets/ # 按字节复制到产物根目录中的静态文件 -└── src/ - ├── skills//SKILL.md # 每个目录一个 Skill，并带有自己的资源 - ├── commands/*.md # 宿主斜杠命令文档 - ├── rules/*.mdc # 宿主规则文档 - ├── hooks/*.ts # 由配置引用的生命周期钩子处理器 - ├── mcp/.ts # 手写的 stdio MCP 服务器入口 - ├── mcp// # 或生成式服务器，每个路由一个模块 - │ ├── tools/*.tsx - │ ├── resources/*.tsx - │ ├── prompts/*.tsx - │ ├── apps/*.tsx # 编译为自包含 HTML 的浏览器 MCP App - │ └── layout.tsx # 可选的按服务器布局，包裹该服务器的路由 - ├── scripts/.ts # 产物脚本（.tsx 通过 Agent 渲染器渲染） - ├── cli.ts # 单个包 bin - ├── cli/**/*.ts # 或路由式 CLI，嵌套即命令路径 - ├── index.ts # 库入口 - ├── layout.tsx # 可选的共享布局，包裹每个渲染式路由 - ├── state.ts # 项目状态定义 - └── providers/.ts # 请求上下文 provider +├── agent-bundle.config.ts +├── package.json +├── tsconfig.json +├── assets/ # 可选静态资源 +├── src/ +│ ├── mcp/ops/ +│ │ ├── tools/ +│ │ │ ├── inspect.tsx # 唯一操作实现、schema 和 Agent 文档 +│ │ │ └── inspect.cli.ts # 该操作的可选 CLI 投影 +│ │ ├── resources/policy.tsx # MCP 资源 +│ │ ├── prompts/review.tsx # MCP 提示 +│ │ ├── apps/dashboard.tsx # 浏览器入口，不是 Agent Server Component +│ │ └── layout.tsx # 可选的共享智能体文档布局 +│ ├── events/tool/ +│ │ ├── before.tsx # tool/before 语义事件路由 +│ │ └── before.preflight.ts # 必须由路由显式重导出的预检 gate +│ ├── hooks/session-start.ts # 由配置引用的可选普通钩子 +│ ├── skills/review/SKILL.md +│ ├── commands/review.md # 可选原生提示或命令文档 +│ ├── rules/project.mdc # 可选且宿主支持的规则 +│ ├── cli/doctor.tsx # 真正独立的 CLI 工作流 +│ ├── scripts/check-service.ts # 普通产物脚本 +│ ├── providers/project.ts # 可选请求依赖 +│ ├── state.ts # 可选框架状态定义 +│ ├── layout.tsx # 可选根文档布局 +│ ├── components/ # 普通可复用呈现代码 +│ ├── domain/ # 普通业务逻辑、客户端与策略 +│ └── install-bin.ts # 可选包绑定安装器的委托入口 +└── tests/ + ├── route-unit/ + └── projection/ ``` +这份结构中没有手写的 `application.ts` 注册表、生成式 MCP 入口或原生钩子 JSON；框架按需生成它们。 +`domain/` 和 `components/` 只是代码组织方式，不是新的框架约定。 +预构建的非 TypeScript 资源或原生可执行文件应显式声明为 `payload`，不能假定任意源码目录都会被交付。 + ## 各个根目录的含义 -| 路径 | 表面 | 如何退出 | +| 路径 | 含义 | 重要边界 | | --- | --- | --- | -| `src/skills//SKILL.md` | 一个 Skill。目录中其余内容都作为它的资源随行。完全不需要任何声明即可随产物发布。 | 删除该目录，或收窄 `skills` 配置中的 glob。 | -| `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`。 | 使用自定义服务器，或给文件名加 `_` 前缀。 | -| `src/scripts/.ts` | 一个普通脚本，只编译一次，输出为产物根目录下的 `scripts/.mjs`，所有所选宿主共用。嵌套模块是硬错误（`AB4808`）。 | 给某一段路径加 `_` 前缀，或用显式 `scripts` 条目认领该文件。 | -| `src/scripts/.tsx` | 渲染式脚本：async 默认组件接收 `argv` 与 `signal`，并按 CLI 输出契约通过 Agent 渲染器渲染。 | 改名为 `.ts`、给某一段路径加 `_` 前缀，或认领该文件。 | -| `src/cli.ts` | 一个以 `plugin.name` 命名的包 bin。 | `bin: false` | -| `src/cli/**/*.{ts,tsx}` | 路由式 CLI 命令，编译进一张做过冲突检查的命令图与一个可执行文件。嵌套即身份：`src/cli/library/audit.ts` 以 ` library audit` 运行。它取代 `src/cli.ts` 约定。 | `bin: false`、`routes.cli: 'conventional'`，或给某一段路径加 `_` 前缀。 | -| `src/index.ts` | 库输出，带声明文件。 | `lib: false` | -| `src/layout.{ts,tsx}` | 共享文档布局：默认导出一个接收 `{ children, route, signal }` 的组件，在每个渲染式路由——生成式 MCP 工具、资源与提示、渲染式路由 CLI 命令、投影的 MCP 命令与渲染式脚本——外层渲染 `Agent.Result`。事件路由与浏览器 App 永不被包裹。 | 重命名为 `_layout.tsx`。 | -| `src/mcp//layout.{ts,tsx}` | 按服务器的布局，嵌套在根布局之内，包裹该生成式服务器的路由。 | 重命名为 `_layout.tsx`，或把 `routes.servers.` 设为非生成模式。 | -| `src/state.ts` | 项目状态：默认导出 `defineState`。生成的 MCP、路由式 CLI 与渲染式脚本的请求作用域都会挂载它。 | `state: false`，或改名为 `_state.ts`。 | -| `src/providers/.{ts,tsx}` | 一个请求上下文 provider，挂载在请求句柄的 `providers.` 上；其工厂会收到请求的身份、lineage 以及只读的 state/notices 句柄。 | 给文件名加 `_` 前缀。 | -| `assets/` | 静态资源，按字节复制到产物根目录的 `assets/` 目录，所有所选宿主共用一份。 | 改为声明顶层 `assets` 列表。 | - -路由与包入口约定精确匹配 `.ts` 与 `.tsx` 文件；state 约定则专指 `src/state.ts`。被发现的条目在 -规范化模型中带有 `provenance.kind: 'conventional'`，因此 `agent-bundle inspect` 能告诉你某个文件 -是被约定识别的，还是被配置认领的。 +| `src/mcp//tools/*.{ts,tsx}` | 生成式服务器上的工具。 | 渲染式工具导出 schema、可选静态 `config` 和默认组件，不需要手工注册。 | +| `src/mcp//tools/.cli.ts` | 同目录工具的命名 CLI 投影。 | 复用工具，不是另一条 MCP 路由；可选 `mapInput` 改变 CLI 输入映射，而不是操作注册表。 | +| `src/mcp//resources/*` 与 `prompts/*` | MCP 资源与提示。 | 它们不是工具，协议元数据和结果契约不同。 | +| `src/mcp//apps/*.{ts,tsx}` | 浏览器 App 入口。 | 声明 `config.resourceUri`，框架编译并注册自包含 HTML。 | +| `src/events/**` | 已支持的语义事件路由，例如 `tool/before`。 | 路径必须对应支持的事件族，不是任意事件总线主题；原生 envelope 由 adapter 负责。 | +| `src/hooks/*.ts` | `hooks` 配置引用的普通处理器。 | 目录本身不会注册它们；使用公开的 `HookHandler` 契约，不需要 JSX 或自定义 stdin 包装器。 | +| `src/skills//SKILL.md` | 静态 Skill 及其资源文件。 | 不需要渲染 runtime 即可交付；渲染式和宿主专属形式见 [Skills](../authoring/skills.mdx)。 | +| `src/commands/*.md` | 原生命令或提示文档。 | 不是 `src/cli/` 命令；可用性和 frontmatter 取决于宿主。 | +| `src/rules/*.mdc` | 宿主支持的规则文档。 | 选中了 target，不代表它支持规则。 | +| `src/cli/**/*.{ts,tsx}` | 独立的路由式 CLI 命令。 | 嵌套就是命令路径；如果是同一个工具操作，优先用工具的 `.cli.ts` 投影。 | +| `src/scripts/.ts` / `.tsx` | 普通或渲染式产物脚本。 | 脚本是扁平的；共享辅助代码放在约定根之外或私有路径下；渲染式脚本接收 `argv` 和 `signal`。 | +| `src/providers/.{ts,tsx}` | 请求上下文 provider。 | 通过 `agent()` 读取生成的 provider 值，不再添加全局服务注册表。 | +| `src/state.ts` | 可选 `defineState` 声明。 | 框架状态是可选能力，不接管领域数据库；`state: false` 禁用发现。 | +| `src/layout.{ts,tsx}` | 根 Agent 文档布局。 | 包裹渲染式路由，不包裹原生事件响应或浏览器 App。 | +| `src/mcp//layout.{ts,tsx}` | 根布局内的服务器文档布局。 | 作用于该生成式服务器的路由。 | +| `assets/` | 约定式静态资源。 | 复制到产物的 `assets/` 下；显式配置可以收窄选择。 | + +以 `_` 或 `.` 开头的私有路径段和声明文件不参与路由发现。 +`before.preflight.ts` 不会仅因为文件名而成为特殊入口，事件路由必须通过支持的 preflight 契约重导出它。 +不要为同一事件同时注册普通钩子和语义路由，形成两份意外实现。 +运行模式、target、provider 与 preflight 的选择见[钩子](../authoring/hooks.mdx)。 + +路由 `config` 导出使用有界静态语法。运行时工作保留在处理器或领域模块中，不要为了获取元数据而执行它。 +Schema 保持唯一权威定义，不要在 CLI 和浏览器里分别重建协议类型。 + +### 添加交互式 App + +工具中的 `Agent.*` JSX 描述面向智能体的文档；MCP App 入口在浏览器中运行，拥有自己的 DOM 或 React UI。 +不要把服务器路由导入浏览器，这会把 Node API、领域服务和仅供服务器使用的依赖带入错误的运行环境。 + +使用已有的 App 资源绑定连接两者。对于 `src/mcp/ops/apps/dashboard.tsx`，在浏览器入口中声明资源 URI： + +```ts +import type { AppRouteConfig } from 'agent-bundle'; + +export const config = { + resourceUri: 'ui://my-plugin/dashboard.html', +} satisfies AppRouteConfig; +``` + +这只是浏览器入口的元数据，不是完整 UI。默认 HTML 提供 `#root`；启动代码需要其他外壳时使用显式模板。 +工具可以引用 App，而不重复写 URI 字符串： + +```ts +// Metadata in src/mcp/ops/tools/inspect.tsx +import type { ToolConfig } from 'agent-bundle'; +import { appResourceUri } from 'agent-bundle/routes'; + +export const config = { + description: 'Inspect project status.', + annotations: { readOnlyHint: true }, + _meta: { ui: { resourceUri: appResourceUri('dashboard') } }, +} satisfies ToolConfig; +``` + +浏览器使用 `agent-bundle/app` 的 `createAppClient`。 +它的 opening-input、result、error 监听器及工具调用就是集成边界；不要重新实现 `postMessage` 传输、 +请求 ID 映射或 MCP 客户端。在连接之前注册 opening 监听器。 +使用宿主提供的初始调用结果进行渲染，不要在挂载时自动重跑一次修改性操作。 +所属 UI 退役时释放客户端和订阅。 + +生成的路由声明提供 App 调用类型；它们必须是最新的，并且被浏览器的 TypeScript 项目包含。 +这不能替代对不可信数据的运行时校验。导入是浏览器安全的前提下，可以共享纯呈现组件与已验证数据。 +Node 渲染的文档组件不会仅因为也使用 JSX，就自动成为 DOM 组件。 + +要通过可选的生产浏览器表面暴露同一个 App，在 `web.apps` 中配置已有的 `server/app` 身份和初始工具。 +不存在第二份 `src/web/` 注册表。完整示例与策略见 +[MCP 服务器与 Apps](../authoring/mcp.mdx)、[可工作的 App 示例](../../examples/mcp-app.mdx)及 +[`web` 配置](../../reference/configuration.mdx#web)。浏览器呈现方式与启动服务器的宿主投影是两个不同选择。 ## 配置与约定 -配置保存任何单个文件都无法拥有的内容——项目标识、target 选择、策略，以及产物内 -[`web`](../../reference/configuration.mdx#web) 宿主要暴露哪些已声明的 MCP App： +约定式起点仍然很小： ```ts twoslash import { defineConfig } from 'agent-bundle/config'; export default defineConfig({ - plugin: { description: 'Evidence-backed project tools.', name: 'my-plugin' }, - targets: ['portable', 'codex', 'claude'], + plugin: { name: 'my-plugin', description: 'Project tools for an agent.' }, + targets: ['portable', 'claude', 'codex'], }); ``` -只有当你需要约定无法表达的东西时才添加显式声明——不同的路径、target 限制，或退出约定： +仅对约定无法表达的内容增加显式配置，例如指定 target 的普通钩子、预构建 payload、远程服务器、 +非标准路径、包专用 bin 或策略。必需能力仍需要支持它的宿主，或者明确限制目标范围。 -```ts twoslash -import { defineConfig } from 'agent-bundle/config'; +手写的 `src/mcp/.ts` 是已声明服务器的互操作路径。 +与同名生成式路由共存时，需要明确决定模式，而不是依赖文件系统顺序。 +同理，`src/cli.ts` 与 `src/cli/` 是两种备选 CLI 模式。 +`src/index.ts` 是可选库入口，不是应用注册入口；`bin: false` 和 `lib: false` 可以退出这些包约定。 -export default defineConfig({ - plugin: { description: 'Evidence-backed project tools.', name: 'my-plugin' }, - scripts: { - // Restricted to one target, so it cannot ride the convention. - 'detect-risk': { entry: './src/scripts/detect-risk.ts', targets: ['portable'] }, - }, - targets: ['portable', 'codex', 'claude'], -}); +声明故意偏离约定时，检查实际路由图，而不是猜测哪个文件胜出： + +```sh +npx --no-install agent-bundle inspect --routes +npx --no-install agent-bundle validate ``` -当项目呈现出前约定时代的写法时，源码校验会报告**信息级**提示，而不是错误：`AB4730` 对应一个自行连接 -传输层的 stdio 入口（改为默认导出工厂函数即可升级到框架生命周期外壳），`AB4731` / `AB4732` / -`AB4733` 对应 `src/cli.ts`、`src/index.ts` 或 `src/mcp/.ts` 存在、但被显式配置遮蔽的情形。 -`bin: false` 与 `lib: false` 这两个退出方式则完全静默。 +正确的编译器必须已经安装到当前项目中。 +源码选择与迁移诊断的细节见[配置](../authoring/index.mdx)和[包入口](../authoring/package-entries.mdx)。 ## 输出落在哪里 -`agent-bundle build` 会写出两类彼此独立的东西。 +区分以下职责： + +| 位置 | 所有者与用途 | +| --- | --- | +| `src/`、配置、`package.json` | 手写应用与包身份。 | +| `.agent-bundle/` | 生成的路由声明与开发基础设施，不是手写注册表，也不是持久化应用数据的契约。 | +| 默认的 `artifact/` | 已校验的组合插件树。 | +| 启用包输出时的 `dist/` | 生成的 npm 根目录：产物字节，加上包元数据和包专用入口。 | +| 解析后的可写状态根 | 框架状态与应用明确选择的数据位置，和已安装代码分离。 | ### 复合插件根目录 -无论 `targets` 选择了什么，产物输出位置都只有一个目录。命令行把该输出默认为 `artifact/`，因此它永远 -不会与下文的包构建冲突；`output.distPath` 或 `--output` 可以移动它。Amp 读取嵌套的 -`.amp/plugins//`，其他所选宿主把组合根当作插件根。不存在 `artifact//` 这样的分区。 -省略 `targets` 时，根目录只承载 `portable` 投影。 +产物示意如下： ```text artifact/ -├── .amp/plugins//index.js # amp 目录插件工厂 -├── .claude-plugin/plugin.json # claude，旁边是 marketplace.json -├── .codex-plugin/plugin.json # codex，旁边是 hooks.json 与 mcp.json -├── .agents/plugins/marketplace.json # codex marketplace -├── .cursor-plugin/plugin.json # cursor，旁边是 hooks.json 与 mcp.json -├── .mcp.json # claude MCP 文档 -├── plugin.json # portable（Agent Plugins）清单 -├── mcp.json # portable MCP 文档 -├── hooks/ -│ ├── hooks.json # claude 钩子文档 -│ ├── .mjs # 只到达一个所选宿主的钩子的包装脚本 -│ ├── ..mjs # 到达多个宿主的钩子，每个宿主一个包装脚本 -│ └── hooks-flight.mjs -├── mcp/mcp--.mjs # 编译后的 MCP 入口，只输出一次 -├── bin/.mjs # 路由式 CLI 和/或 web -├── scripts/, skills/, commands/, rules/, assets/, mcp-apps/ # 组件目录，只输出一次 -├── INSTALL.md # 每个所选宿主一节 -├── install.mjs # 选择了 cursor 或 portable 时出现 -└── agent-bundle.manifest.json # 产物索引：身份、投影、可执行文件、摘要 +├── agent-bundle.manifest.json +├── agent-bundle.compile-evidence.json +├── INSTALL.md +├── .claude-plugin/ # 所选宿主清单 +├── .codex-plugin/ +├── .cursor-plugin/ +├── .amp/plugins// # 选择 Amp 时的原生目录插件 +├── plugin.json # 选择 portable 时的清单 +├── mcp/ # 编译后的服务器入口及其 runtime 文件 +├── hooks/ # 生成的原生包装器与钩子文档 +├── bin/.mjs # 声明后生成的路由 CLI / web 可执行文件 +└── skills/, scripts/, assets/, mcp-apps/, ... ``` -宿主清单位于各自的点目录中；`skills/`、`hooks/`、`mcp/`、`scripts/`、`bin/` 与 `assets/` 只输出一次、 -所有宿主共用。钩子与 MCP 文档在项目声明了钩子或 MCP 服务器时出现——此外，当钩子或 MCP 服务器到达 -另一个所选宿主的约定路径 `hooks/hooks.json`、`.mcp.json` 或 `mcp.json` 时，Codex 或 Cursor 会额外输出一份 -空文档，使目录发现不会加载其他宿主的文件——`bin/` 在项目有路由式 CLI、配置了 -[`web`](../../reference/configuration.mdx#web)，或两者兼有时出现。两个所选宿主若要以不同字节写出同一路径，就无法共用根目录，构建会以 `AB4103` 失败；一个只面向 -部分所选宿主的命令或规则，却位于另一个所选宿主会扫描的目录中，则是 `AB4105`。两者的恢复方式 -相同：让该组件对每个所选宿主都完全一致，或把这些宿主分别构建到不同的产物中。 +只有已声明的相关表面才会输出。精确的原生文档和其他 runtime 文件由清单记录； +应用代码不应该根据这张示意图重新推断可执行文件清单。 +不存在 `artifact//` 分区。Amp 使用嵌套的原生目录，而框架的清单感知安装入口接受组合根， +并选择正确的宿主表面。 -`agent-bundle.manifest.json` 记录了每个产出文件及其 SHA-256，因此产物校验是内容寻址的，而不是猜测。 -编译后的表面归属于复合身份——所选宿主按名称排序后以 `+` 连接，例如 `claude+codex`——`targets` 的 -书写顺序永远不会改变输出。 +`output.distPath` 或 CLI `--output` 移动组合根，不改变其内部布局。 +CLI 优先级是 `--output`、配置、默认 `artifact/`。 +编程式 `build()` API 的包输出与默认行为另有约定；应查阅它的参考，不要把 CLI 默认值复制到自定义构建中。 -`output.distPath` 只移动根目录；它从不改变根目录内部由框架拥有的布局。优先级是 CLI `--output`， -然后 `output.distPath`，最后是默认值——对同时输出包构建的 `agent-bundle build` 是 `artifact`，对不带 -`packageOutputs` 的编程式 `build()` 是 `dist`。取值必须是非空、限定在项目根目录内的相对 POSIX 路径。 +清单记录文件摘要和规范的可执行文件身份。重排 targets 不会创建另一个应用。 +字节冲突或意外的跨宿主发现应通过校验解决，不应通过手改生成清单修复。 +见 [Target 与产物](../../reference/targets-artifacts.mdx)。 ### npm 包构建 -当项目声明了 `bin`/`lib`——或通过约定提供了它们——同一次构建还会在 `dist/` 下写出可供 node 消费的 -包构建： +`dist/` 是**完整的生成式 npm 包根目录**，不只是 JavaScript 文件夹： ```text dist/ -├── bin/.js # 自执行 ESM、shebang、可执行位 -├── .js # 库入口 -└── **/*.d.ts # 声明文件，当 lib.dts 开启时 +├── package.json # 生成的包相对路径与 bin 映射 +├── agent-bundle.manifest.json +├── INSTALL.md +├── ... # 原样复制的组合产物 +├── bin/.mjs # 同一个生成式路由 CLI（如果存在） +├── bin/.js # 可选的显式包专用可执行文件 +└── .js, .d.ts # 可选库输出 ``` -`dist` 是强制忽略的目录：包输出永远不会进入项目源码快照，也不会进入 Skill 与资源发现。两类输出不得重叠： -在带有包入口的项目上把 `output.distPath` 或 `--output` 指向 `dist` 就是 `AB4706`。默认值已经把二者分开， -显式写出也无妨： +路由式 CLI 不会为 npm 再编译一份竞争的 `.js` 实现；生成的 `package.json` 指向产物中的可执行文件。 +显式包专用 bin 与库入口是不同的输出，仍有自己的编译过程。 -```ts twoslash -import { defineConfig } from 'agent-bundle/config'; +组合输出与 npm 输出不得重叠：包输出已使用 `dist/` 时，再把产物放到那里是无效配置。 +构建输出不是源码输入。应打包生成的 npm 根，而不是源码仓库或猜测的 `dist/artifact/` 嵌套目录。 +校验与安装流程见[交付捆绑包](../distribution/index.mdx)。 -export default defineConfig({ - output: { distPath: 'artifact' }, - plugin: { description: 'A CLI plus a plugin.', name: 'my-plugin' }, - targets: ['portable', 'claude'], -}); -``` +### 可写状态不是已安装代码 + +请求内部使用框架提供的 plugin/context 绑定。独立代码可使用公开的 runtime `resolvePluginRoot`， +它区分 `root` 与 `stateRoot`；`AGENT_BUNDLE_STATE_ROOT` 独立于代码根覆盖值。 + +不要因为加载器位于已安装代码树中，就把运行时缓存、刷新后的凭据或数据库也放在那里。 +应用数据保留自己的 schema、显式迁移和覆盖策略，并且不能与框架存储冲突。 +框架不会自动接管或清除任意插件数据。 +见[配置与状态](../authoring/index.mdx)和[安装生命周期](../distribution/installation.mdx)。 ## 下一步 -- [编译器架构](../concepts/architecture.mdx) —— 这些根目录如何变成路由图、 - 宿主投影与一份复合产物。 -- [配置模型](../authoring/index.mdx) —— 完整的配置表面。 -- [Skills](../authoring/skills.mdx)、[钩子](../authoring/hooks.mdx)、 - [MCP 服务器与 MCP App](../authoring/mcp.mdx) —— 每种表面一页。 -- [脚本与资源](../authoring/scripts-assets.mdx) 与 - [包入口](../authoring/package-entries.mdx) —— 其余的构建输出。 +[快速开始](./quick-start.mdx)运行一条真实约定路由。 +[Skills](../authoring/skills.mdx)、[钩子](../authoring/hooks.mdx)、[MCP](../authoring/mcp.mdx)和 +[脚本与资源](../authoring/scripts-assets.mdx)说明各表面契约。 +[编译器架构](../concepts/architecture.mdx)用于理解实现细节，不是额外的设置步骤。 diff --git a/website/docs/zh/guide/start/quick-start.mdx b/website/docs/zh/guide/start/quick-start.mdx index 6f0042ee1..de6ab02f4 100644 --- a/website/docs/zh/guide/start/quick-start.mdx +++ b/website/docs/zh/guide/start/quick-start.mdx @@ -1,126 +1,216 @@ --- -description: '用脚手架创建 agent-bundle 项目，或手写 agent-bundle.config.ts，然后构建并运行开发者 Workbench。' +description: '创建插件，添加一个约定式 MCP 工具，查看渲染结果并测试，再把同一个操作暴露为 CLI 命令。' --- # 快速开始 -有两条入门路径。脚手架生成的项目本身就能通过自带的 `check`；手写路径则只需要在已有仓库里加四行配置。 +本教程使用 MCP starter。添加工具不需要服务器工厂、注册数组、自定义传输层或第二份构建配置。 +这个示例也不需要智能体账号。 + +先安装 [Node.js 22.19 或更高版本](./installation.mdx)，并选择一个 **Package preview** 工作流 +已经成功的提交。下面使用该提交不可变的预览 SHA，而不是仅凭 `agent-bundle` 这个未限定名称选择 npm 包。 ## 用脚手架创建项目 -最快的方式是 `create-agent-bundle`。它会依次询问名称、模板与宿主 targets： +把 `` 替换为该提交的 SHA： ```sh -npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@ \ - my-plugin +AB_SHA='' +npx "https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@${AB_SHA}" \ + my-plugin --template mcp-server --targets portable,claude,codex +cd my-plugin +npm install +npm run check ``` -等到 npm 正式发布之后，这条命令会变成 `npm create agent-bundle`。在此之前，请使用 -[预览通道](./installation.mdx)中的提交 SHA 或 PR 编号。 +同时指定目录与模板会使用脚本化路径。预览脚手架从同一提交选择 compiler/runtime 配对。 +提交生成的锁文件；后续干净检出可以使用 `npm ci`。 +[安装指南](./installation.mdx)说明预览选择，以及正式发布的脚手架如何配对版本号独立的 compiler/runtime。 -同时指定目录与模板的运行会被视为脚本化调用，不再询问任何问题——其余取值回退到各自的默认值： +### 模板 -```sh -npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@ \ - my-plugin \ - --template mcp-server \ - --targets portable,codex,claude +| 模板 | 用途 | +| --- | --- | +| `minimal` | 静态 Skills，不需要 MCP 服务器或 React runtime。 | +| `mcp-server` | 约定式 MCP 工具及路由、投影测试；当前 starter 还演示了可选的库导出与产物脚本。 | +| `cli-tool` | 独立的路由式 CLI，附带脚本和库示例。 | + +当前脚手架接受 `portable`、`claude`、`codex` 和 `cursor`。编译器还支持 `amp`；使用 Amp 时， +先选择脚手架接受的 target，再在 `agent-bundle.config.ts` 中显式设置需要的 targets。 +添加原生 target 不代表实时开发代理也支持该宿主。见[宿主安装](../distribution/installation.mdx)。 + +## 添加第一个工具 + +Starter 已包含一个 `status` 服务器及其 `report-status` 工具。在旁边新增 +`src/mcp/status/tools/hello.tsx`： + +```tsx +import { Agent } from '@agent-bundle/runtime'; +import type { ToolConfig, ToolRouteProps } from 'agent-bundle'; +import { z } from 'zod'; + +export const config = { + description: 'Return a greeting without changing anything.', + annotations: { readOnlyHint: true }, +} satisfies ToolConfig; + +export const inputSchema = z.object({ name: z.string().min(1) }).strict(); +export const resultSchema = z.object({ message: z.string() }).strict(); + +export default async function Hello({ input }: ToolRouteProps) { + const result = { message: `Hello, ${input.name}.` }; + return ( + + {result.message} + + ); +} ``` -### 模板 +路径声明了 `status` 服务器上的 `hello` 工具；它的框架路由 ID 是 `tool:status/hello`。 +`value` 是结构化结果，子节点描述面向智能体的呈现方式。 +结果应保持 JSON 兼容，并用 `resultSchema` 描述它的真实形状。 -| 模板 | 你会得到什么 | -| --- | --- | -| `minimal` | 一个纯 Skills 插件：一个 `src/skills//SKILL.md` 目录，此外别无他物。 | -| `mcp-server` | 由一个 `src/mcp//tools/.tsx` 路由模块构成的 stdio MCP 服务器，外加一个产物脚本，并已接好框架测试 harness。 | -| `cli-tool` | 可安装的路由式 CLI（`src/cli/greet.ts`），外加一个约定式脚本（`src/scripts/hello.ts`）与带声明文件的 `src/index.ts` 库导出，并由生成的 projection 测试池在 `cli-dispatch` 与 `script-dispatch` 级别加以证明。 | +不要再把这个工具加入 `agent-bundle.config.ts`，也不要调用 `registerTool`。 +添加路由文件就是注册。领域实现可以放在路由目录以外并正常导入，不需要另一份操作注册表。 -每个模板都自带 `check` 脚本（validate、build、typecheck、tests），并且校验时零诊断——包括 `AB473x` -迁移提示，因为这些模板从一开始就是按照 entry 约定编写的。`mcp-server` 模板还自带消费者测试 harness， -每个测试池都标注了自己承载的证明级别。 +## 构建，或交互式开发 -预览脚手架会把 `agent-bundle` 与 `@agent-bundle/runtime` 固定到同一个提交 SHA。通过 npm 安装的脚手架则 -从自身打包后的可选 peer 元数据读取精确的 compiler/runtime 配对；两者版本彼此独立，因此 compiler `0.2.0` -可以正确选择 runtime `0.1.0`。对需要 runtime 的模板使用 `--framework-version` 时，取值必须与记录的 -compiler 版本一致，否则脚手架会在写入文件之前停止。全部参数见 -[create-agent-bundle README](https://github.com/ScriptedAlchemy/agent-bundle/blob/main/packages/create-agent-bundle/README.md)。 +```sh +npm run dev -- --open +``` -## 或者手写配置 +在 Workbench 的 **Application** 树中选择 `status` 下的 `hello` 工具，输入参数并调用： -在项目根目录的 `agent-bundle.config.ts` 中描述插件： +```json +{ "name": "Ada" } +``` -```ts twoslash -import { defineConfig } from 'agent-bundle/config'; +渲染文档应显示 `Hello, Ada.`，结构化结果应包含 `{"message":"Hello, Ada."}`。 +**Trace** 展示调用，**Problems** 展示构建诊断，**Advanced** 提供底层检视。 +普通路由调用并不能证明外部宿主已经安装或调用了插件。 -export default defineConfig({ - plugin: { name: 'my-plugin', description: 'What it does.' }, - targets: ['claude', 'codex', 'cursor'], - skills: ['src/skills/*'], - hooks: { sessionStart: { handler: './src/session-start.ts' } }, - mcp: { servers: { tools: { entry: './src/mcp.ts' } } }, -}); +修改问候语，等待本次重建完成后再调用。无效修改会保留上一个可用构建并显示诊断； +之前的输出不是新源码已成功编译的证据。Workbench 不需要为了刷新视图而自动重复执行修改性操作。 + +不启动开发服务器、只构建一次时运行： + +```sh +npm run build ``` -大多数项目需要的比这还少，因为配置沉默时 `src/` 约定会自动补齐： +## 测试路由 -```ts twoslash -import { defineConfig } from 'agent-bundle/config'; +新增 `tests/route-unit/hello.test.ts`： -export default defineConfig({ - plugin: { description: 'Evidence-backed project tools.', name: 'my-plugin' }, - targets: ['portable', 'codex', 'claude'], +```ts +import { expect, it } from '@rstest/core'; +import { renderRoute } from 'agent-bundle/test'; + +it('returns the greeting as structured data', async () => { + const rendered = await renderRoute('tool:status/hello', { + input: { name: 'Ada' }, + }); + expect(rendered.result).toEqual({ message: 'Hello, Ada.' }); }); ``` -`targets` 选择这一个产物根目录承载哪些宿主投影——`amp`、`claude`、`codex`、`cursor`、`portable`；省略它时 -根目录只承载 `portable`。发布版本号来自 `package.json`。`plugin.version` 字段仍然可用，但它是已废弃的 -兼容轴；取值与 `package.json` 不一致时会报告 `AB4008` 警告。 +运行现有的聚合命令： -## 构建，或交互式开发 +```sh +npm run check +``` + +当前 MCP starter 的 `npm test` 单独运行时会排除路由和投影测试。 +`check` 执行校验、构建、类型检查及全部三组测试；完整门禁使用它，聚焦路由时使用 +`npm run test:routes`。真实 MCP 进程和浏览器 App 等进一步的证明级别见[测试](../development/testing.mdx)。 + +消费路由、provider 或 App 类型的 TypeScript 项目必须包含生成的 `.agent-bundle/routes.d.ts`。 +它是生成文件，不是手写注册表。在干净目录中单独检查类型，或添加、重命名路由后，先刷新它： ```sh -npx agent-bundle build --root . # 把复合插件根目录写到 artifact/ -npx agent-bundle dev --root . # 带实时重建的本地 Workbench +npm run validate +npm run typecheck ``` -`build` 会校验项目并写出产物根目录；声明了 `bin`/`lib` 时还会一并完成包构建。`dev` 在 loopback 上提供 -开发者 Workbench，并随输入变化持续重建。用它的 Application 树选择工具、事件、CLI 命令、脚本、App、 -Skill、规则或命令；运行可执行叶子，并首先检视渲染出的 Agent Document。Trace 展示本次会话的调用， -Problems 保存诊断，Advanced 则包含 eval、产物检视、协议检视、宿主诊断与原始日志。 +旧声明文件存在，不等于它是最新的。Starter 的完整 `check` 已把生成放在类型检查之前。 -## 查看编译器的判断 +## 把工具复用为 CLI 命令 + +新增 `src/mcp/status/tools/hello.cli.ts`： + +```ts +import type { CliProjectionConfig } from 'agent-bundle/routes'; + +export const config = { + command: ['hello'], +} satisfies CliProjectionConfig; +``` + +它是同目录工具的投影，不是另一条工具路由或处理器。重新构建，再运行产物中生成的可执行文件： ```sh -npx agent-bundle inspect --root . # 规范化配置与每个宿主投影的计划 -npx agent-bundle inspect --root . --skills # 加上 skill focus -npx agent-bundle validate --root . # 检查项目源码 +npm run build +node artifact/bin/my-plugin.mjs hello --name Ada ``` -`inspect` 读取源码配置并展示规范化后的模型——这正是确认某个约定是否真的被识别的地方。 +使用的仍然是同一份 `inputSchema`、路由实现和结果，不需要再创建 `src/cli/hello.ts`。 +`src/cli/` 留给真正独立的 CLI 工作流。 -## 安装结果 +自动 flag 推导只支持有界的 schema 语法。复杂嵌套或 union schema 不保证能使用这种命名投影； +不要为了生成 flag 而复制或削弱工具 schema。 +[包入口](../authoring/package-entries.mdx)说明了支持的语法和已有的批量 MCP 命令 JSON 输入路径。 + +## 或者手写配置 -产物根目录带有一份生成的 `INSTALL.md`，每个所选宿主一节，其中的命令使用该捆绑包真实的插件名与市场名。 -所有宿主安装的都是同一个目录，因此 `--from` 始终指向根目录。按上文构建出 `portable`、`codex` 与 -`claude` 三个 target 后，宿主安装命令是： +在已有包中安装匹配的[框架/runtime 配对](./installation.mdx)，以及代码使用的渲染和 schema 依赖。 +约定式路由不需要 `mcp.servers` 条目： + +```ts twoslash +import { defineConfig } from 'agent-bundle/config'; + +export default defineConfig({ + plugin: { name: 'my-plugin', description: 'Project tools for an agent.' }, + targets: ['portable', 'claude', 'codex'], +}); +``` + +版本保留在 `package.json` 中。省略 targets 时只选择 `portable`。 +自定义本地服务器、预构建服务器和远程服务器仍可通过[显式模式](../authoring/mcp.mdx)使用； +不要在同一个名称下混合手写服务器和生成式路由，并依赖静默优先级。 + +## 查看编译器的判断 + +在已经安装了正确编译器的项目中运行： ```sh -npx agent-bundle install claude --from artifact --scope user -npx agent-bundle install codex --from artifact -node artifact/install.mjs # portable 包，通过生成的安装器 +npx --no-install agent-bundle inspect --routes +npx --no-install agent-bundle validate +npx --no-install agent-bundle validate --artifact artifact ``` -把 `cursor` 加入 `targets`，同一个根目录就会多出 `.cursor-plugin/`；然后用 `npx agent-bundle install -cursor --from artifact` 以同样方式安装。 +前两个命令读取源码项目，最后一个无需源码即可检查构建后的组合产物。 +用路由 ID 关联源码、Workbench 与测试输出。 + +## 安装结果 -若想在 Claude Code 上进行免安装的开发循环： +读取生成的 `artifact/INSTALL.md`，其中包含所选宿主的安装命令和插件真实名称。 +在当前开发项目中，已安装的编译器也能执行显式安装： ```sh -claude --plugin-dir artifact plugin list --json +npx --no-install agent-bundle install claude --from artifact --scope user ``` +这是对宿主状态的修改，不是 `build` 或 `dev` 的一部分。请明确选择宿主与作用域。 +Amp 的原生插件位于嵌套目录中；框架安装器从组合根解析该目录。 +遵循生成的说明，不要假定所有宿主的原生安装根都相同。 + +npm 分发应使用[生成的 npm 根目录和 prepack 门禁](../distribution/index.mdx)。 +消费者可以遵循交付的 `INSTALL.md`，或使用插件显式提供的包绑定安装器， +不应为了安装插件而下载一个无关的同名 npm 包。 + ## 下一步 -- [项目结构](./project-structure.mdx) —— 每个 `src/` 根目录的含义，以及输出落在哪里。 -- [配置模型](../authoring/index.mdx) —— 每个配置字段及其归属。 -- [Skills](../authoring/skills.mdx) —— 大多数插件最先编写的表面。 +[项目结构](./project-structure.mdx)展示工具、CLI 投影、钩子、provider、状态、Skills 和浏览器 App +如何组合。[MCP App 示例](../../examples/mcp-app.mdx)展示真实工具结果上的交互视图； +[钩子](../authoring/hooks.mdx)解释何时使用普通处理器，何时使用语义事件路由。 From fb48a79d82f38e00990df7ed0795befe6329b4ba Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:10:15 -0700 Subject: [PATCH 02/12] docs: add target capability map, reuse recipes, and troubleshooting in both locales --- website/docs/en/guide/authoring/_meta.json | 2 +- .../en/guide/authoring/reuse-framework.mdx | 205 ++++++++++++ website/docs/en/guide/development/_meta.json | 2 +- .../en/guide/development/troubleshooting.mdx | 113 +++++++ website/docs/en/guide/start/_meta.json | 2 +- website/docs/en/guide/start/capabilities.mdx | 167 ++++++++++ website/docs/en/reference/index.mdx | 88 ++--- .../docs/en/reference/targets-artifacts.mdx | 315 ++++++++---------- website/docs/zh/guide/authoring/_meta.json | 2 +- .../zh/guide/authoring/reuse-framework.mdx | 173 ++++++++++ website/docs/zh/guide/development/_meta.json | 2 +- .../zh/guide/development/troubleshooting.mdx | 106 ++++++ website/docs/zh/guide/start/_meta.json | 2 +- website/docs/zh/guide/start/capabilities.mdx | 151 +++++++++ website/docs/zh/reference/index.mdx | 82 +++-- .../docs/zh/reference/targets-artifacts.mdx | 288 ++++++++-------- 16 files changed, 1308 insertions(+), 392 deletions(-) create mode 100644 website/docs/en/guide/authoring/reuse-framework.mdx create mode 100644 website/docs/en/guide/development/troubleshooting.mdx create mode 100644 website/docs/en/guide/start/capabilities.mdx create mode 100644 website/docs/zh/guide/authoring/reuse-framework.mdx create mode 100644 website/docs/zh/guide/development/troubleshooting.mdx create mode 100644 website/docs/zh/guide/start/capabilities.mdx diff --git a/website/docs/en/guide/authoring/_meta.json b/website/docs/en/guide/authoring/_meta.json index ae2a9e0d3..4f5a704e7 100644 --- a/website/docs/en/guide/authoring/_meta.json +++ b/website/docs/en/guide/authoring/_meta.json @@ -1 +1 @@ -["index", "skills", "hooks", "mcp", "scripts-assets", "package-entries"] +["index", "reuse-framework", "skills", "hooks", "mcp", "scripts-assets", "package-entries"] diff --git a/website/docs/en/guide/authoring/reuse-framework.mdx b/website/docs/en/guide/authoring/reuse-framework.mdx new file mode 100644 index 000000000..ae547f3da --- /dev/null +++ b/website/docs/en/guide/authoring/reuse-framework.mdx @@ -0,0 +1,205 @@ +--- +description: 'Practical recipes for one tool with CLI and App surfaces, shared contracts, event preflight, request context, writable state, payloads, and supported installation without handwritten framework glue.' +--- + +# Reuse the framework + +Start with the smallest authored surface that does the job. A route is the operation; a CLI +projection or browser App is another way to use it. The framework owns registration, transport, +compilation, and installation. Your plugin owns its product behavior. + +For the complete source tree, see [Project structure](../start/project-structure.mdx). For which +hosts can consume a surface, use the [capability map](../start/capabilities.mdx). + +## One tool, one operation + +Put the operation in its conventional route and move substantial domain computation into an +ordinary imported module when that makes the code easier to read. A registration array, generated +route-file script, custom `McpServer`, or string-keyed dispatcher is not required. + +```tsx +// src/mcp/tools/tools/hello.tsx +import React from 'react'; +import { Agent } from '@agent-bundle/runtime'; +import type { ToolConfig, ToolRouteProps } from 'agent-bundle'; +import { z } from 'zod'; + +export const config = { + description: 'Greet a person.', + annotations: { readOnlyHint: true }, +} satisfies ToolConfig; +export const inputSchema = z.object({ name: z.string().min(1) }).strict(); +export const resultSchema = z.object({ greeting: z.string() }).strict(); + +export default async function Hello({ input }: ToolRouteProps) { + const result = { greeting: `Hello, ${input.name}.` }; + return ( + + {result.greeting} + + ); +} +``` + +Here the server name is `tools`, the protocol tool name is `hello`, and the canonical route ID +is `tool:tools/hello`. You do not separately register those identities. A meaningful server name +can group the tools your plugin actually provides; creating one server per operation is not +required. + +`readOnlyHint` is descriptive metadata, not enforcement of a security policy. Keep validation, +permission-sensitive decisions and side-effect guards in the operation's actual execution path. + +## Expose that tool as a CLI command + +Add a sibling projection, not a second handler: + +```ts +// src/mcp/tools/tools/hello.cli.ts +import type { CliProjectionConfig } from 'agent-bundle/routes'; + +export const config = { + command: ['hello'], + confirm: false, +} satisfies CliProjectionConfig; +``` + +`confirm: false` is intentional for this read-only greeting. Do not copy it to a mutation without +reviewing the intended confirmation policy. The generated command calls the same tool and +validates against its canonical schema. + +Use the supported aliases, flags, positionals and synchronous `mapInput` only to translate CLI +syntax. Do not repeat the domain operation or its result renderer inside the mapper. Keep a +separate `src/cli/**` route for a genuinely independent aggregate workflow. + +Automatic flag inference has a bounded schema grammar. A rich nested/union schema remains a +valid tool even when it cannot be projected into named flags. The documented bulk MCP command +path supports JSON input; named projections do not yet acquire that mode merely by adding a +`mapInput` function. Use the actual supported path described in +[package entries](./package-entries.mdx), rather than weakening the tool schema or pretending +an unimplemented option exists. + +## Share contracts, not a second schema registry + +A route may import a supported locally declared schema and export it as `inputSchema` or +`resultSchema`. Keep one authoritative domain contract. The generated declaration file supplies +route IDs, App result types and provider types; it does not improve a deliberately loose schema +into a precise one. + +Validate untrusted external responses at their domain boundary, then render the normalized +receipt. Success, partial data, and expected failure may need distinct variants. Do not force +success-only fields onto an error branch, fabricate a missing identifier, or parse a previously +rendered text report to recover data the operation already had. + +Caller input and parsed handler input are conceptually different: defaults and transformations +run during parsing. The current generated invocation types still use schema output for some +caller-facing contracts. That limitation does not justify a second browser schema or a broad +`as any`; see [troubleshooting](../development/troubleshooting.mdx) and the schema discussion in +[configuration](./index.mdx). + +## Add a browser App without rebuilding its transport + +A browser App lives under `src/mcp//apps/*`. Its `config` declares the resource URI and, +when used, the HTML template. Associate a tool with that App through the supported metadata +and `appResourceUri` helper. The compiler registers the resource and bundles its assets. + +In the browser entry, use the generated tool ID and the public client: + +```ts +import { createAppClient } from 'agent-bundle/app'; +import { name, version } from 'agent-bundle/meta'; + +const client = createAppClient({ appInfo: { name, version } }); +const result = await client.call('tool:tools/hello', { name: 'Ada' }); +``` + +This excerpt illustrates the typed call, not a complete App startup sequence. In a real App, +register opening-input, result, error and cancellation handlers before connecting, call +`client.connect()`, and dispose the client with the view's lifecycle. The complete +[MCP App example](../../examples/mcp-app.mdx) demonstrates that sequence and a real tool/resource. +Opening notifications are distinct from the result of a subsequent `client.call`. + +Do not implement parent-message RPC, a second initialization handshake, another pending-request +map, or a manual `AppRegister` for conventional routes. Your App still owns local selection, +formatting, polling policy, and its loading/error UI. TypeScript does not validate arbitrary +external messages merely because a local variable has a generated type. + +An `Agent.*` tree is agent-facing output, not browser DOM. The browser App can use normal DOM or +React code; sharing domain contracts does not mean importing server modules into the browser +at runtime. Generated type-only imports must remain type-only. + +## Choose semantic events or a plain hook deliberately + +Use `src/events/**` for a canonical event route with Agent output, request context, and optional +preflight. Use a config-declared plain handler with the public `HookHandler`/`HookEvent` types +when simple execution and a small result are enough. Do not duplicate native stdin/stdout +wrappers in either case. + +A preflight gate belongs before expensive or side-effecting work. Native payload fields are +not uniform across hosts; consume the canonical fields where available and preserve unknown or +absent evidence honestly. A stop, deny, continue, or rewritten input must retain the host's +actual decision semantics. An unrelated logging failure must not silently turn an already +established protective decision into permission to continue. + +Capability-based `requires` and explicit target scoping serve different purposes. Consult the +[hook guide](./hooks.mdx) and [event matrix](../../reference/events.md) before selecting an event, +matcher, provider subset, or native-only behavior. Native hook documents are an explicit +advanced escape hatch, not the default way to recreate semantic events. + +## Use observed context and keep code separate from data + +Use `await agent()` inside an executing route only when it needs request identity, providers, +capabilities, lineage, state or notices. Declare shared request dependencies in `src/providers/*` +instead of mounting another application-global service locator. A provider's value should have +the request lifetime the operation expects. + +The request's plugin binding already separates code and writable framework state. Do not rebuild +a precedence chain of `CLAUDE_PLUGIN_ROOT`, `CURSOR_PLUGIN_ROOT` and guessed artifact directories. +Standalone code can use the documented public resolver with an explicit fallback policy. + +An asset is immutable code-side input. A cache, database, acquired login session, or operational +receipt is mutable data. Choose a deliberate application-owned writable location, preserve +explicit operator overrides, and keep its migration/retention policy in the plugin. Do not +rewrite the installed package's `.env` during ordinary execution or use the framework's kernel +files as an unstructured domain directory. See +[runtime environment](../../reference/runtime-environment.mdx). + +Notices use the framework ledger and the supported channels in the +[notice matrix](../../reference/notices.md). Publishing, attempting delivery, and acknowledging +receipt are different states; a successful write is not proof that an agent saw the notice. + +## Package assets and executables through declarations + +Use Skills' own resource directories, `assets`, conventional scripts, or `definePrebuilt` for +the appropriate kind of input. A prebuilt payload is copied, not converted into a compiled +TypeScript dependency. Declare packages required by that payload at consumer runtime through +its supported dependency declaration; do not externalize ordinary generated code by default. + +The compiler's manifest owns generated executable paths, launch arguments and projection +bindings. A consumer should not scan `mcp/` for a likely file, assume the first `args` value is +always a Node entry, rewrite emitted JavaScript strings, or repair permissions from an +unvalidated manifest. + +Use generated native installation instructions or the public package-bound +`agent-bundle/install` entry. A branded installer can be a thin binding; it must not become a +second native-cache manager, receipt database, or lifecycle parser. See +[shipping](../distribution/index.mdx). + +## Test the layer you changed + +| Change | Smallest useful proof, followed by stronger proof where needed | +| --- | --- | +| Domain computation | Deterministic domain tests with external services injected. | +| Route rendering, schemas or context | Public route tests using the actual generated graph and declarations. | +| MCP registration or CLI projection | The framework's protocol/CLI helpers, plus one compiled parity case. | +| Browser App behavior | The public browser harness, including opening success/error/cancellation, then an actual generated-server journey. | +| Packaging, paths or installation | Actual packed/source-free execution and receipt-owned install tests. | +| Host behavior | A separately labelled native host test with real authorization; mocks are not an authenticated model turn. | + +Keep independent expected identities and safety outcomes in tests. Deriving every expectation +from the same output under test cannot detect a wrong rename or missing annotation. Conversely, +do not copy the framework's whole transport implementation into a test fixture merely to test +a plugin's domain behavior. + +The goal is deletion of duplicated ownership: one route graph, one set of domain contracts, +one supported client bridge and one lifecycle implementation. A useful domain helper is not +a defect merely because the framework also has helpers. diff --git a/website/docs/en/guide/development/_meta.json b/website/docs/en/guide/development/_meta.json index 019782edf..8f0cba67a 100644 --- a/website/docs/en/guide/development/_meta.json +++ b/website/docs/en/guide/development/_meta.json @@ -1 +1 @@ -["index", "workbench", "testing", "evaluations"] +["index", "workbench", "testing", "evaluations", "troubleshooting"] diff --git a/website/docs/en/guide/development/troubleshooting.mdx b/website/docs/en/guide/development/troubleshooting.mdx new file mode 100644 index 000000000..aa2b46c63 --- /dev/null +++ b/website/docs/en/guide/development/troubleshooting.mdx @@ -0,0 +1,113 @@ +--- +description: 'Diagnose missing routes, weak generated types, incompatible targets, App launch problems, package-root mistakes, runtime state, and test evidence without inventing another registry or installer.' +--- + +# Troubleshooting + +Start with the failing boundary: authored source, compiled artifact, installed package, or running +host. Do not repair generated files by hand; correct the owning source declaration and rebuild. +The [capability map](../start/capabilities.mdx) distinguishes supported output from supported +client behavior. + +## Establish the version and the object being inspected + +After installing the intended framework package locally: + +```sh +npx --no-install agent-bundle --version +npx --no-install agent-bundle validate +npx --no-install agent-bundle inspect --json +``` + +For a copied artifact, inspect that artifact instead of an unrelated checkout: + +```sh +npx --no-install agent-bundle inspect --artifact artifact --json +npx --no-install agent-bundle validate --artifact artifact +``` + +`inspect --artifact` is not combined with source `--root` or `--config`. `validate --artifact` +takes the bare composite artifact; the manifest-aware installation path also understands an npm +root. Those roots have different inventory responsibilities. See [shipping](../distribution/index.mdx). + +Record the compiler/runtime package selectors and the artifact/application version when reporting +a problem. Preview packages should come from one immutable build. Published compiler/runtime +versions can differ; use the pair recorded by the matching scaffolder, not an assumption that +their numeric versions must be equal. + +## Find the smallest correction + +| Symptom | Check and correction | +| --- | --- | +| A file is not a tool or is missing from Workbench | Check the actual route path, supported extension, private `_`/`.` segments, ignore rules, and explicit server mode. Inspect the route graph. A custom/command/remote server is not a generated route server; do not create a second registration list to compensate. | +| A supported target is rejected by project creation | Compare the scaffolder's choices with the compiler's target catalog. The current Amp choice gap does not mean the Amp adapter is absent. Use a compatible source project/configuration and consult Amp's MCP limits rather than assuming every starter works for it. | +| A composite fails with a path/discovery conflict | Read `AB4103`, `AB4105`, or `AB4106` and the affected components. Make shared content compatible or build deliberately incompatible projections separately. Changing target order or overwriting emitted files is not a resolution. | +| A hook is absent or its native decision differs | Check the generated event/hook matrix, selected host, matcher, required capabilities, and the exact native payload. Use `hooks list` and the documented host-specific simulation. Do not replace missing evidence with a fabricated allow/deny value. | +| TypeScript accepts an invalid App route ID or loses provider/result types | Check that generation ran successfully and that `.agent-bundle/routes.d.ts` belongs to the actual browser/server/test program consuming it. Inclusion in one sibling tsconfig is not proof of inclusion in another. | +| A defaulted input field is unexpectedly required by an App type | The current generator uses parsed schema output for some caller contracts. Do not interpret the type error as proof that runtime defaults are unsupported. Keep the canonical schema and distinguish this known type boundary from invalid runtime input. | +| Adding a named CLI projection rejects a rich schema | Automatic flags use a bounded grammar. Consult the supported canonical-JSON bulk command path; a mapper alone does not extend the named projection grammar. Do not flatten the real domain contract just to satisfy flag extraction. | +| An App resource exists but the host shows no browser UI | Distinguish serving MCP Apps from rendering them in the particular client/version. Use the MCP App reference and local preview as a separately labelled check; the presence of HTML is not native display proof. | +| App preview selects a host that cannot launch its server | A build-wide target list is not that server's eligible launch list. Select an actual eligible projection. Never add a fake portable server solely to satisfy the UI. | +| An App stays loading, or an error looks like an empty success | Register input/result/error/cancellation handling before connecting the public client. Expected tool errors do not necessarily reach the success-result callback. Check the actual opening invocation, not just a subsequent manual call. | +| An App preview appears only after the opening call completes | The primary Workbench App workspace currently awaits completion. The lower-level pending bridge and browser harness do not by themselves make that workspace a live pending preview. Do not add another client transport to work around the UI lifecycle gap. | +| npm installation succeeds but the executable is missing | Pack the intended generated npm root and inspect its actual `package.json.bin` and tarball inventory. Generated routed bins use the manifest executable; authored package bins have a different output path. Do not assume the old nested `artifact/` layout. | +| Installation rejects a manifest revision or changed digest | Align the emitting compiler and consuming lifecycle implementation. Keep public packages coherent; do not independently update a private source reader or edit the closed manifest version/digests. | +| A read-only installed plugin fails on a write | Keep code/assets immutable and use the observed framework state location plus an explicit domain-data policy. An acquired session or cache is not a packaged asset or a reason to rewrite the installed `.env`. | +| MCP stdio fails to parse output | Keep application logs off the JSON-RPC stdout channel. Use the generated lifecycle or a correctly scoped custom-server entry, and send diagnostics to stderr. | +| A green default test did not catch a broken route | Check which tests the script collects. The current MCP starter's `check` includes route/projection pools, while its `npm test` alone excludes them. Use the full documented check until the script contract changes. | +| A native test was skipped or an account is unavailable | Record the missing prerequisite and the proof not performed. A successful mock, build, or install is not authenticated tool/hook execution; unverified is not the same as unsupported. | + +## Generated types on a clean checkout + +Generated declarations are intentionally not authored source. Run the current supported generation +path before a standalone typecheck, and stop if it fails: + +```sh +npx --no-install agent-bundle validate +npm run typecheck +``` + +The project needs its own `typecheck` script and correct tsconfig inclusion. A previous generated +file can remain after failed preparation; do not describe it as current. The present inclusion +warning is not a complete audit of every project reference. For solution-style configurations, +verify each consuming program rather than adding a file to an unrelated root program merely to +silence a warning. Do not import server implementations into browser runtime code to get types. + +The starter's current complete check is: + +```sh +npm run check +``` + +See [testing](./testing.mdx) for focused pools and [reuse recipes](../authoring/reuse-framework.mdx) +for canonical contracts. Static-only plugins should not gain a React/MCP testing dependency solely +to imitate the MCP starter. + +## Installation and replacement + +Use the delivered `INSTALL.md` or the supported package-bound installer. Native registration, +file placement, enablement, and a live running session are distinct states. Read the +[installation guide](../distribution/installation.mdx) before interpreting a receipt or reload step. + +Use `doctor` for a read-only installed-state check. A different version or foreign directory may +require a deliberate operator decision; do not start with `rm -rf`, global cache edits, or +pre-validation permission repair. Keep-data and purge have different ownership requirements. +Missing historical ownership is not authority to delete an inferred directory. + +Run packaging tests with temporary data and isolated host roots. Do not put real passwords, +tracker sessions, private keys, or live operator data in a reproducible fixture. + +## Useful bug-report evidence + +Include the package selectors and Node version, the smallest relevant config and route, the +exact command, structured diagnostic, and whether it ran from source, an artifact, an installed +package, or a native host. Include the expected behavior and actual terminal outcome. + +For App/session problems, note the chosen server, tool, launch projection and browser profile +separately. For a rebuild problem, identify the old and new revision without attaching unrelated +raw logs. Redact credentials, authorization headers, session cookies, and private command data. +Do not include an entire environment dump. + +Link the [diagnostic reference](../../reference/diagnostics.md) or capability row when applicable. +A test failure, a documented limitation, and an unexecuted acceptance case require different +follow-up work; report which one the evidence establishes. diff --git a/website/docs/en/guide/start/_meta.json b/website/docs/en/guide/start/_meta.json index 7d40fbbbd..7a0868d5a 100644 --- a/website/docs/en/guide/start/_meta.json +++ b/website/docs/en/guide/start/_meta.json @@ -1 +1 @@ -["index", "installation", "quick-start", "project-structure"] +["index", "installation", "quick-start", "capabilities", "project-structure"] diff --git a/website/docs/en/guide/start/capabilities.mdx b/website/docs/en/guide/start/capabilities.mdx new file mode 100644 index 000000000..4e4e28b30 --- /dev/null +++ b/website/docs/en/guide/start/capabilities.mdx @@ -0,0 +1,167 @@ +--- +description: 'Choose among all five built-in output targets, find the generated capability matrices, and distinguish plugin emission, client compatibility, browser presentation, and verified execution.' +--- + +# Targets and capability map + +Use this page to answer **what to author, which output to select, and where the limits are**. +For a first working tool, start with [Quick start](./quick-start.mdx). For the precise, +versioned host behavior, use the generated matrices rather than assuming every host implements +the same plugin interface. + +## All built-in output targets + +These are the five built-in values of `targets` in `agent-bundle.config.ts`. They select what +the compiler emits, not an account, a model, or a running development session. + +| Target | Output and intended reader | Important boundary | +| --- | --- | --- | +| `amp` | A native directory plugin at `.amp/plugins//`, with an `index.js` PluginAPI factory, explicitly registered Skills, and mapped event callbacks. | Its MCP configuration is skill-scoped. The adapter accepts supported remote or globally resolvable command servers beside exactly one bundled Skill, not compiler-owned local MCP entries. Amp installation and live account execution are different proof levels. | +| `claude` | Claude Code: `.claude-plugin/plugin.json`, the generated marketplace entry, `hooks/hooks.json`, and `.mcp.json` where applicable. | Compiled semantic hooks and explicitly authored native hooks have different authoring contracts. Native additions such as LSP declarations stay Claude-specific. | +| `codex` | Codex: `.codex-plugin/plugin.json` and explicit pointers to its own hook/MCP documents, plus `.agents/plugins/marketplace.json`. | CLI, editor, and desktop behavior must be qualified separately. Serving an MCP App resource does not imply that every Codex client displays it. | +| `cursor` | Cursor: `.cursor-plugin/plugin.json` and its own hook/MCP documents; an optional marketplace document. | The owned local-copy installation path differs from native marketplace CLI installation. Do not write Cursor's global hook configuration by hand. | +| `portable` | Agent Plugins 1.0.0: root `plugin.json`, Skills, and `mcp.json` where authored. | This is a format target, not a universal host. It does not define native hooks, rules, or slash-command documents. Each reader's supported subset is recorded separately. | + +Omitting `targets` selects `portable` alone. Explicit selection replaces that default: + +```ts twoslash +import { defineConfig } from 'agent-bundle/config'; + +export default defineConfig({ + plugin: { name: 'project-tools', description: 'Tools for this project.' }, + targets: ['claude', 'codex', 'cursor'], +}); +``` + +To select different projections for one build, repeat `--target`. Run this only after installing +the intended framework package in the project: + +```sh +npx --no-install agent-bundle build --target claude --target codex +``` + +A combination is valid only when its actual components can coexist. Different bytes at the same +path, or a component accidentally discovered by another host, are build errors—not permission +to overwrite one projection with another. Reordering the target list does not resolve a conflict. +See [composition rules](../../reference/targets-artifacts.mdx). + +The current scaffolder's target choices lag the compiler's Amp support. To build for Amp, use +an appropriate existing/static project and set `targets` explicitly; do not assume the generated +MCP starter's local server is compatible with Amp's skill-scoped MCP contract. See the current +[installation guide](../distribution/installation.mdx) for the nested install root and reload +procedure. + +## The authoritative capability matrices + +The following pages are generated from the same pinned capability records used by the adapters. +They include the source documents, observed versions, detailed restrictions, and reasons for +omissions. Do not maintain a second checklist of native support in a plugin repository. + +| Question | Read | +| --- | --- | +| Which components, transports, path tokens, native metadata and install methods does a target support? | [Host capability matrix](../../reference/hosts.md) | +| Which semantic events and plain-hook events exist, which payload fields are present, and how are tool selectors mapped? | [Event and hook matrix](../../reference/events.md) | +| Which notice channels and recipient identities are supported, and what counts as delivery? | [Notice delivery matrix](../../reference/notices.md) | +| Which files and executable records are emitted? | [Targets and artifacts](../../reference/targets-artifacts.mdx) and [artifact manifest](../../reference/artifact-manifest.mdx) | +| Which component did this particular build select or omit? | `agent-bundle inspect --json`; its plans report selected/skipped components, reasons, and per-kind capability judgments. | + +A capability judgment is scoped to a feature and its recorded evidence: + +| State | Meaning for an author | +| --- | --- | +| `supported` | The declared behavior has supporting evidence for the recorded target/version. It is not proof that your operation has been run successfully in that host. | +| `degraded` | A restricted or translated behavior is available. Read the reason before depending on it. | +| `unavailable` | The framework has no supported path for the requested behavior under that record. The reason may identify a missing host feature or missing evidence; those are not the same claim. | +| `prohibited` | The contract explicitly refuses this use. Do not bypass the diagnostic by copying a private implementation. | + +Runtime verification is a separate axis. A record may describe an implemented adapter while +account-dependent activation remains **unverified**. Absence of an account is not evidence that +that host cannot perform the operation. Conversely, successful file placement is not proof that +the host enabled the plugin or invoked a tool. + +## What the framework can build + +This is an authoring map, not a promise that every target accepts every component. The host +matrices and the actual build's inspection decide availability. + +| Need | Ordinary authoring path | Framework responsibility / guide | +| --- | --- | --- | +| Reusable instructions and resources | `src/skills//SKILL.md` | Discover, validate, package, and project Skills; [Skills](../authoring/skills.mdx). Static Skills need no server. | +| Generated instruction content | A documented rendered Skill source | Render at build time into the Skill artifact, not an always-running host service; [Skills](../authoring/skills.mdx). | +| Host slash commands or rules | `src/commands/*.md`, `src/rules/*.mdc` | Validate supported frontmatter and native discovery; [configuration](../authoring/index.mdx). A Markdown command is not an executable CLI route. | +| Callable tools, resources, or prompts | `src/mcp//{tools,resources,prompts}/*` | Generate registration, server lifecycle, contracts, and protocol projection; [MCP](../authoring/mcp.mdx). | +| Reuse a tool from a terminal | A sibling `.cli.ts` | Project argv into the canonical operation; [package entries](../authoring/package-entries.mdx). | +| An independent terminal workflow | `src/cli/**` | Generate the command tree, argument handling, output, and exit semantics. Use this for a different workflow, not another copy of a tool. | +| Agent-facing structured and readable output | `Agent.*` elements from an executable route | Compose the Agent Document and its surface output. Domain computation stays in the plugin. | +| A browser view for a tool | `src/mcp//apps/*` with an explicit tool association | Compile an MCP App and connect it through `agent-bundle/app`; [MCP Apps example](../../examples/mcp-app.mdx). | +| Open that App without an agent UI | `serve-app`, or declared `web` exposure | Reuse the local browser host and consent boundary; [CLI](../../reference/cli.mdx). This is not a new deployment target. | +| Cross-host event behavior | `src/events/**`, optionally with preflight | Normalize the event and project the supported decision/context; [hooks](../authoring/hooks.mdx). | +| A lightweight plain hook | A config-declared handler using the public hook type | Own native stdin/stdout and result encoding without requiring an Agent renderer; [hooks and scripts example](../../examples/hooks-and-scripts.mdx). | +| Shared rendering and request dependencies | `src/layout.tsx`, server layouts, `src/providers/*` | Compose supported routes and mount observed request context; [project structure](./project-structure.mdx). Browser Apps and events are not automatically document-layout children. | +| Framework state and notices | `src/state.ts` and the public request handle | Supply the declared lifetimes, journal/notice machinery and honest availability; [runtime environment](../../reference/runtime-environment.mdx) and [notices](../../reference/notices.md). | +| Scripts, static assets, or an opaque executable payload | `src/scripts/*`, assets, or `definePrebuilt` | Bundle or copy according to the declaration; [scripts/assets](../authoring/scripts-assets.mdx) and [payloads](../authoring/package-entries.mdx). Declare real payload runtime dependencies. | +| npm bins/library output and installation | `bin`/`lib` where needed; optional `agent-bundle/install` entry | Assemble the canonical package root and reuse lifecycle ownership; [shipping](../distribution/index.mdx). | +| Tests and agent evaluations | Public test/browser/Rstest and eval helpers | Keep route, protocol, packed and native evidence distinct; [development](../development/index.mdx). | + +Advanced custom/command/remote MCP servers, native metadata, native hook documents, prebuilt +payloads, and bundler overrides remain supported where documented. They are escape hatches for +real integration needs, not setup required for a normal tool. + +## Compatible clients are not additional targets + +The host matrix's **Recorded third-party clients** section describes readers of an existing +output format. Its client names are not additional values for `targets`. A research issue for +a host is also not an installed adapter. + +Read each client's tier and surface rows together. A skills-only reader may not read `plugin.json`. +A reader of `mcp.json` may not expand the path tokens needed to start its server. An installation +command may register a directory rather than copy it. A higher-priority manifest may redirect +component paths; a per-file MCP override need not shadow unrelated Skills. Conditional components +are absent from a plugin that never authored them. + +Use the dated source links in [the generated client records](../../reference/hosts.md) for those +details. A generic statement that a client supports plugins is not enough to claim compatibility +with this exact artifact. Hosts without a current implemented/recorded path are not advertised +here as supported targets. + +## Build, development, and display are separate + +| Surface | Selection | What it does not imply | +| --- | --- | --- | +| Compilation | `targets` / build `--target` | All selected hosts expose identical features or share one native installation root. | +| Development installation | `dev --install-host claude`, `codex`, or `cursor` | Every native target supports the live development proxy. Amp uses its documented copy/reload path. | +| Embedded host terminal | The installed, supported Claude/Codex host-session integration | Authentication, trust, and successful model execution are supplied by the real host, not simulated by the Workbench. | +| App presentation | A supported browser-host `--profile` | That profile is a native output target or the correct server launch projection. | +| npm distribution | Pack the generated npm root | Installing the npm package automatically registers it with an agent host. | + +Third-party adapters registered through the advanced `TargetRegistry` build alone under the +current composite contract. They do not automatically inherit the built-in targets' discovery +isolation guarantees. + +## Check your own plugin + +Run separate inspection focuses; do not combine them into one invocation: + +```sh +npx --no-install agent-bundle inspect --json +npx --no-install agent-bundle inspect --routes --json +npx --no-install agent-bundle inspect --hooks --json +npx --no-install agent-bundle inspect --state --json +npx --no-install agent-bundle validate +``` + +After building, inspect and validate the deliverable without rediscovering source: + +```sh +npx --no-install agent-bundle inspect --artifact artifact --json +npx --no-install agent-bundle validate --artifact artifact +``` + +For event routes, use supported `config.requires` capability declarations when the requirement +is semantic, or explicit host selection when the behavior is intentionally native-specific. +Do not claim support by dropping a blocking decision, fabricating context, or broadening approval. +See the event guide for mutually exclusive declarations and unavailable-capability diagnostics. + +Keep the generated `INSTALL.md` with the deliverable and follow its actual host/root/scope +instructions. A successful compile, a packed-process test, a native install, and an authenticated +agent turn establish different things; document which ones were actually exercised. diff --git a/website/docs/en/reference/index.mdx b/website/docs/en/reference/index.mdx index 1219a8ec3..12b8bf0f6 100644 --- a/website/docs/en/reference/index.mdx +++ b/website/docs/en/reference/index.mdx @@ -1,53 +1,65 @@ --- -description: 'agent-bundle reference: the CLI, configuration fields, target artifacts, runtime environment, security boundaries, limitations, and the generated type API.' +description: 'Exact Agent Bundle CLI, configuration, artifact and runtime contracts, plus generated host/event/notice capability maps, diagnostics, public APIs and practical troubleshooting.' --- # Reference -The Guide explains how to build and ship a bundle. This section is the lookup half: exact flags, -exact field names, exact defaults, and the boundaries the framework refuses to cross. - -Nothing here repeats a walkthrough. Where a concept is already explained in the Guide — the -configuration model, the seven hook events, the proof levels — these pages link to it and record -only the contract. +Use the Guide to build a plugin and this section to check exact fields, flags, defaults and +boundaries. The [target and capability map](../guide/start/capabilities.mdx) is the short route +to all five built-in outputs and the functionality they can project. | Page | Answers | | --- | --- | -| [CLI](./cli.mdx) | Every command, argument, option, default, and exit code. | -| [Configuration](./configuration.mdx) | Every `agent-bundle.config.ts` field, its type, and its validation rule. | -| [Targets and artifacts](./targets-artifacts.mdx) | The composite plugin root, what each host projection adds to it, and the artifact manifest contract. | -| [Host capability matrix](./hosts.md) | The pinned per-host capability tables: versions, manifests, install surfaces, path tokens, MCP transports, plugin components. Generated at build time. | -| [Event and hook matrix](./events.md) | Canonical events to native events per host, tool selectors to native matchers, deferred native events. Generated at build time. | -| [Notice delivery matrix](./notices.md) | Which notice channels each host supports and why the rest are unavailable. Generated at build time. | -| [Diagnostics reference](./diagnostics.md) | Every `AB` code family, trigger, severity, and recovery hint. Generated at build time from the repository contract. | -| [Development-server HTTP](./dev-server-http.mdx) | Browser-facing invocation, trace, raw-log, and host hook-receipt routes and wire shapes. | -| [Runtime environment](./runtime-environment.mdx) | Node floors, path tokens, environment variables, `.env` layering, and durable state locations. | -| [Security](./security.mdx) | The credential, network, and trust boundaries. | -| [Limitations](./limitations.mdx) | What the framework does not currently do or prove. | -| [Type API](./api.mdx) | The generated symbol reference for every public export. | +| [Target and capability map](../guide/start/capabilities.mdx) | Which surface to author; native target versus compatible reader versus development/display support. | +| [CLI](./cli.mdx) | Commands, arguments, options, defaults and exit codes, including inspection, hooks, MCP, installation and local App hosting. | +| [Configuration](./configuration.mdx) | `agent-bundle.config.ts` fields, types and validation rules. | +| [Targets and artifacts](./targets-artifacts.mdx) | All five built-in projection layouts, composition constraints, distribution forms and executable ownership. | +| [Artifact manifest](./artifact-manifest.mdx) | The canonical application, route, executable, launch, distribution and compiler record shapes. | +| [Host capability matrix](./hosts.md) | Pinned versions, native documents, installation, path tokens, MCP behavior, lineage, plugin components and recorded compatible clients. Generated from adapter capability data. | +| [Event and hook matrix](./events.md) | Canonical event families, native events, payload-field provenance, tool selectors and deferred native events. Generated from the same records. | +| [Notice delivery matrix](./notices.md) | Recipient axes, supported channels, sensitivity constraints and unavailable-delivery reasons. Generated from the same records. | +| [Diagnostics reference](./diagnostics.md) | Diagnostic codes, severity, trigger and recovery. Generated from the repository contract. | +| [Development-server HTTP](./dev-server-http.mdx) | Invocation, trace, raw-log and hook-receipt routes for advanced integrations. | +| [Runtime environment](./runtime-environment.mdx) | Node floors, path tokens, environment layering, observed context and writable state. | +| [Security](./security.mdx) | Credential, network, sandbox, consent and trust boundaries. | +| [Limitations](./limitations.mdx) | What is unsupported, deliberately constrained, or not established by available proof. | +| [Type API](./api.mdx) | Generated symbols for the public package exports. | +| [Troubleshooting](../guide/development/troubleshooting.mdx) | Missing routes/types, target mismatches, App lifecycle, package roots and qualification problems. | + +The generated matrices are not another manually curated compatibility list. Their dated source +links explain the recorded behavior. `supported`, `degraded`, `unavailable` and `prohibited` +are feature judgments; an unperformed account-dependent runtime test is a separate verification +limit. Consult the actual component and client/version rather than assuming one host-level badge +covers every operation. + +For authoring patterns, use [Reuse the framework](../guide/authoring/reuse-framework.mdx): one +tool with CLI and App surfaces, canonical schemas, semantic/plain hooks, request dependencies, +state, payloads and installation. Custom server factories and raw native documents remain +advanced integration paths, not the minimum code required for a plugin. ## Reading the diagnostics -Every command reports structured diagnostics rather than prose errors. One diagnostic is a stable -`AB` code, a severity, a message, and usually a `sourcePath` and a `recovery` hint. For the -diagnostic-gated commands — `build`, `prepack`, `validate`, `doctor`, `install`, and `dev` — only -an **error** severity makes the command exit nonzero; warnings and infos never gate a build, a -validation, or a dev rebuild. `eval` and `inspect` have an extra, non-diagnostic reason to exit -`1`: a failing or inconclusive trial, or an invalid model — see the -[CLI exit codes](./cli.mdx#exit-codes). +A structured diagnostic identifies a code, severity, message and, when available, source path +and recovery. Read the current command's final outcome as well: a parser usage error, a failing +or inconclusive eval, and an invalid inspection model are different failure paths. -The full code catalog is the [Diagnostics reference](./diagnostics.md), rendered at build time -from the repository's -[`docs/diagnostics.md`](https://github.com/ScriptedAlchemy/agent-bundle/blob/main/docs/diagnostics.md). +Only an error diagnostic gates the diagnostic-based checks. Options such as `--strict` can +promote applicable host-tool warnings to errors, so do not discard a nonzero result merely +because an earlier unpromoted warning was informational to your workflow. Exact command +behavior is in [CLI exit codes](./cli.mdx#exit-codes). | Family | Area | | --- | --- | -| `AB30xx` | Skill documents: Markdown parsing and rendered-skill compilation. | -| `AB40xx`–`AB47xx` | Plugin metadata, normalized model invariants, hooks, MCP, scripts, assets, package build, and the bundler escape hatch. | -| `AB48xx`–`AB49xx` | Route graph, state, layout, and provider conventions: route module discovery, `config` extraction, shared layouts (`AB4830`–`AB4832`), and the compiled command surface. | -| `AB5000` | General CLI and adapter failures. | -| `AB60xx` | Built-artifact validation, including host schema documents and referenced files. | -| `AB700x`–`AB7015` | Host installation and the npm prepack gate (`AB7014`/`AB7015`: installed-dependency hygiene). | -| `AB7xxx` | Project preparation and development rebuilds, plus the read-only Doctor at `AB7300`–`AB7320`. | -| `AB8xxx` | Development server configuration and Workbench routes. | -| `AB9xxx` | Eval selection, harnesses, and persisted runs. | +| `AB30xx` | Skill parsing and rendered content. | +| `AB40xx`–`AB47xx` | Identity, target composition, hooks, MCP, assets, package output and bundler policy. | +| `AB48xx`–`AB49xx` | Conventional routes, contracts, layouts, providers, state and generated command surfaces. | +| `AB5000` | General command/adapter boundary failures. | +| `AB60xx` | Artifact, native document, referenced-file and compiler-evidence validation. | +| `AB7xxx` | Package/install checks, project preparation, rebuilds and Doctor. | +| `AB8xxx` | Development server and Workbench boundaries. | +| `AB9xxx` | Evaluations and persisted runs. | + +These families are navigation, not a replacement for the [full generated diagnostic +reference](./diagnostics.md). Correct the owning declaration or input; do not change generated +manifest fields, invent missing runtime evidence, or widen native permissions to suppress a +failure. diff --git a/website/docs/en/reference/targets-artifacts.mdx b/website/docs/en/reference/targets-artifacts.mdx index 1c58c54ef..d836e7f58 100644 --- a/website/docs/en/reference/targets-artifacts.mdx +++ b/website/docs/en/reference/targets-artifacts.mdx @@ -1,218 +1,199 @@ --- -description: 'The composite plugin root agent-bundle build emits: where each host projection places its manifest, hook, and MCP documents, the hook wrapper naming rule, the AB4103/AB4105/AB4106 composition rules, the optional manifest web section, and the artifact manifest contract.' +description: 'All five built-in output projections, their native discovery paths, composite constraints, canonical artifact/npm roots, and manifest-owned executable and web bindings.' --- # Targets and artifacts -The target table — what each host projection carries, and why the portable standard omits rules, -commands, and hooks — is in [Configuration model](../guide/authoring/index.mdx). The source-tree -layout is in [Project structure](../guide/start/project-structure.mdx). This page is the output -contract: the one directory `build` emits, and the artifact manifest its bytes have to satisfy. +Start with the [target and capability map](../guide/start/capabilities.mdx) to choose a surface. +The [generated host matrix](./hosts.md) records feature support and evidence. This page describes +what is emitted and which object downstream tools consume. ## The composite plugin root -`agent-bundle build` writes **one directory** at the artifact output — `artifact/` by default; -`output.distPath` or `--output` moves it. `targets` selects the **host projections** laid into -that root: `amp`, `claude`, `codex`, `cursor`, and `portable`, in any combination. Claude Code, -Codex, Cursor, and portable read the root as their plugin root; Amp reads the one generated -directory at `.amp/plugins//`. +`agent-bundle build` writes one composite artifact root, `artifact/` by default. +`output.distPath` or CLI `--output` moves the root; it does not redesign the layout inside it. +The five built-in projections are **`amp`, `claude`, `codex`, `cursor`, and `portable`**. -- Omit `targets` — in config and on the command line — and the build emits only the `portable` - projection. -- Order does not matter. `['codex', 'claude']` and `['claude', 'codex']` produce byte-identical - output, and the normalized model, the artifact manifest, and `inspect` list the selection - sorted by name. -- `plugin` is not a target. `targets: ['plugin']` or `--target plugin` is an unknown target - (`AB4100`): the composite root is already the output of every build. +Omitting `targets` selects only `portable`. An explicit selection can combine built-in projections +when the authored components satisfy their compatibility rules. Target order does not change the +result. `plugin`, `web`, `npm`, and browser presentation profiles are not extra built-in targets. -Built with all four projections, the host-test example's root looks like this (component -directories appear only when the project authors them): +The following is an illustrative combined layout, not a promise that an empty plugin emits +every file. Read the generated manifest for the actual executable names and included components. ```text artifact/ -├── .amp/plugins//index.js # Amp PluginAPI factory -├── .amp/plugins//skills/ # explicitly registered Amp skills -├── .amp/plugins//hooks/.mjs # Amp event callback wrappers -├── .amp/plugins//hooks/hooks-flight.mjs # sibling standalone event worker -├── .agents/plugins/marketplace.json # Codex marketplace -├── .claude-plugin/plugin.json # Claude Code manifest +├── .amp/plugins// +│ ├── index.js # native Amp factory +│ ├── skills/ # explicitly registered Skills +│ └── hooks/ # mapped callbacks' executable support +├── .claude-plugin/plugin.json ├── .claude-plugin/marketplace.json -├── .codex-plugin/plugin.json # Codex manifest -├── .codex-plugin/hooks.json # Codex hook document -├── .codex-plugin/mcp.json # Codex MCP document -├── .cursor-plugin/plugin.json # Cursor manifest -├── .cursor-plugin/marketplace.json -├── .cursor-plugin/hooks.json # Cursor hook document -├── .cursor-plugin/mcp.json # Cursor MCP document -├── .mcp.json # Claude Code MCP document -├── plugin.json # portable (Agent Plugins) manifest -├── mcp.json # portable MCP document -├── hooks/hooks.json # Claude Code hook document -├── hooks/.mjs # wrapper, hook selected for ONE host -├── hooks/..mjs # wrappers, hook shared by >1 selected host -├── hooks/hooks-flight.mjs -├── mcp/mcp--.mjs # compiled MCP entries (+ -flight.mjs) -├── bin/.mjs, bin/-flight.mjs # routed CLI and/or web -├── scripts/, skills/, commands/, rules/, assets/, mcp-apps/ # emitted once -├── INSTALL.md # when any built-in host is selected -├── install.mjs # when cursor or portable is selected -├── agent-bundle.manifest.json # the artifact index (manifestVersion 4) -└── agent-bundle.compile-evidence.json # compiler record per compiled file +├── .codex-plugin/plugin.json +├── .codex-plugin/hooks.json +├── .codex-plugin/mcp.json +├── .agents/plugins/marketplace.json +├── .cursor-plugin/plugin.json +├── .cursor-plugin/hooks.json +├── .cursor-plugin/mcp.json +├── .mcp.json # Claude MCP document +├── plugin.json # portable manifest +├── mcp.json # portable MCP document +├── hooks/hooks.json # Claude hook document +├── hooks/ # compiled, host-bound wrappers/workers +├── mcp/ # compiled MCP entries and workers +├── bin/ # generated CLI / configured web command +├── skills/, commands/, rules/ +├── scripts/, assets/, mcp-apps/ +├── INSTALL.md +├── install.mjs # selected Cursor/portable install path +├── agent-bundle.manifest.json +└── agent-bundle.compile-evidence.json ``` -`agent-bundle.compile-evidence.json` is the compiler's record of each compiled -(`bundle`) file; `validate --artifact` re-checks a listed record against the -file table (`AB6039`). +Shared root components are emitted once. Amp's directory plugin keeps its registered Skills and +execution support inside its nested directory so the installed copy is self-contained. The +native Amp install root is therefore not the same directory as the composite artifact root. -Host manifests live in their dotfolders at the root. Root-level `skills/`, `hooks/`, `mcp/`, -`scripts/`, `bin/`, and `assets/` are shared and emitted **once**. Amp's registered skills, -event wrappers, and the standalone worker beside those wrappers in each directory stay inside -`.amp/plugins//` so the installed plugin remains self-contained. Nothing else appears at -the root: no generated `AGENTS.md`, no `hooks/hooks-cursor.json`, no `web/` directory. The browser -host for configured MCP Apps ships inside `bin/.mjs` as the framework-owned `web` command. -That bin is emitted when `src/cli/**` compiled at least one command, when -[`web`](./configuration.mdx#web) is configured (even with no authored CLI commands), or both. +A static Skills-only plugin does not need empty MCP servers or a Flight/state process. Some empty +native hook/MCP documents are intentional discovery-isolation barriers when another selected +host has content at a conventional fallback path. Do not delete those barriers as unused files. ### Where each host reads its documents -| Host | Manifest | Hook document | MCP document | Marketplace | +| Target | Entry or manifest | Hook registration | MCP configuration | Marketplace | | --- | --- | --- | --- | --- | -| Amp | —; `index.js` is recorded as `documents.entry` | callbacks registered with `amp.on` | flat `skills//mcp.json` beside the registered skill | — | -| Claude Code | `.claude-plugin/plugin.json` | `hooks/hooks.json` | `.mcp.json` | `.claude-plugin/marketplace.json` | -| Codex | `.codex-plugin/plugin.json` | `.codex-plugin/hooks.json` | `.codex-plugin/mcp.json` | `.agents/plugins/marketplace.json` | -| Cursor | `.cursor-plugin/plugin.json` | `.cursor-plugin/hooks.json` | `.cursor-plugin/mcp.json` | `.cursor-plugin/marketplace.json` when `marketplace: true` | -| portable | `plugin.json` | — | `mcp.json` | — | - -The paths are fixed whatever the selection, so a single-host root and a five-host root share one -layout. Amp's directory is isolated under `.amp/plugins//`; Claude Code and the portable Agent Plugins format load their documents from the -conventional plugin-root locations and cannot be redirected; Codex and Cursor manifests carry -explicit `hooks` and MCP pointers, so their documents sit beside their manifests. Both of those -hosts also fall back to folder discovery of the conventional paths when the pointer is absent, so -a Codex or Cursor projection with no document of its own still points at an empty one when a Hook -or MCP server reaches another selected host's conventional path — Cursor never loads Claude -Code's `hooks/hooks.json`. +| `amp` | `.amp/plugins//index.js` | Native PluginAPI callbacks | Skill-scoped `mcp.json` beside an explicitly registered Skill | None generated | +| `claude` | `.claude-plugin/plugin.json` | `hooks/hooks.json` | `.mcp.json` | `.claude-plugin/marketplace.json` | +| `codex` | `.codex-plugin/plugin.json` | `.codex-plugin/hooks.json` | `.codex-plugin/mcp.json` | `.agents/plugins/marketplace.json` | +| `cursor` | `.cursor-plugin/plugin.json` | `.cursor-plugin/hooks.json` | `.cursor-plugin/mcp.json` | `.cursor-plugin/marketplace.json` when requested | +| `portable` | `plugin.json` | No native-hook component in the format | `mcp.json` | None generated | -### Hook wrappers +Paths are stable across valid single-target and multi-target selections. Codex and Cursor use +explicit pointers to avoid loading another projection's fallback documents. A third-party +portable client can have different precedence and supported subsets; consult its individual +record in the [host matrix](./hosts.md), not this native-layout table. -A hook wrapper bakes in the host it was planned for (its codec, its `target`, its host contract -revision), so one wrapper cannot serve two hosts: +### Hook wrappers -- A hook that reaches exactly one selected host keeps the plain name, `hooks/.mjs`. -- A hook that reaches several selected hosts is emitted once per host as - `hooks/..mjs`, and each host's hook document points at its own wrapper. +A compiled hook wrapper belongs to its selected host codec and contract. The same source hook +can therefore produce several wrappers. Config-declared hooks reaching one host use the plain +name; those reaching multiple hosts use host-qualified names. Conventional semantic events and +standalone workers are also recorded in `executables.hooks`. -Which hosts a config hook reaches is its `targets` (every target, by default) intersected with -the selection. An event route may instead declare `requires`; the compiler intersects the -selection with the hosts that support every named capability row. Thus the same source hook is -`hooks/audit.mjs` in a `claude`-only root and -`hooks/audit.claude.mjs` plus `hooks/audit.cursor.mjs` in a `claude` + `cursor` root. Native hooks -are preserved for every selected host. The manifest's `executables.hooks[]` carries one row per -wrapper per host — there is no separate hook index file — and `hooks list`, `hooks simulate`, and -artifact validation (`AB6018`) read those rows. +Use `hooks list` and the manifest rather than constructing wrapper filenames. The native event, +payload provenance, matcher and return semantics are in the [event matrix](./events.md). Explicit +targets and supported event `requires` declarations affect selection; neither can manufacture +an event or decision the host cannot express. ### Compiled surfaces -MCP entries, scripts, routed CLI bins, and MCP Apps are compiled **once** and attributed to the -**composite identity** — the selected host names, sorted and joined by `+`, such as -`claude+codex` — rather than to any one host. `agent-bundle inspect --bundler` shows the same -thing: its `output.path` is the artifact output, ``, with no host segment beneath it. +Generated MCP entries, scripts, CLI bins and browser Apps are attributed to the composite +selection, not independently rebuilt as unrelated applications for each host. An Agent Document +renderer and a browser App compilation are distinct environments. -Amp's MCP surface is the exception: it is skill-scoped, not a plugin-root runtime document. -The Amp adapter accepts relocatable remote servers and globally resolvable commands beside exactly -one bundled skill. It rejects compiler-owned local MCP entries because Amp documents neither a -plugin-root path token nor an execution cwd for resolving such an entry. +Amp's MCP projection is skill-scoped. Its current adapter permits supported remote servers and +globally resolvable command servers associated with exactly one bundled Skill; it rejects +compiler-owned local MCP entries without a supported native path/cwd contract. Listing Amp as a +target does not make the ordinary local generated-MCP starter valid for Amp. -### One root, one set of bytes +A configured `web` surface adds the framework-owned command to `bin/.mjs`, even without +an authored CLI command. It is a local browser host for declared MCP Apps, not a `web` output +target, a separate generated `web/` application, or permission to bypass App consent. -Merging projections by path only works when the hosts agree on the bytes. Three rules keep the -root honest; all are errors, and `validate` and `inspect` report them exactly where `build` -refuses: +### One root, one set of bytes -| Code | Rule | +| Diagnostic | Constraint and recovery | | --- | --- | -| `AB4103` | Two selected projections plan the same path with different bytes. Projections are compared in host-name order and paths in path order, so a given selection reports the same collision however `targets` is written. The usual cause is a Skill whose frontmatter carries a host extension (`targets: { claude: … }`), which lowers to different `skills//SKILL.md` bytes for Claude Code than for the other hosts. Make the component identical for every selected host, or build the conflicting hosts into separate artifacts. | -| `AB4105` | A component scoped to a subset of the selected hosts — a command or rule with frontmatter `targets` — sits in a conventional directory another selected host scans (`commands/` for Claude Code and Cursor, `rules/` for Cursor). Inside one root the file cannot be hidden from that host, so the build refuses rather than leaking it. Extend `targets` to every selected host that discovers the directory, or build those hosts separately. Skills are never host-scoped: every skill ships to every selected host, and a per-host frontmatter extension that changes its bytes is an `AB4103` collision instead. | -| `AB4106` | The selection mixes an adapter registered on an advanced `TargetRegistry` — any target whose adapter is not one of the shipped `amp`, `claude`, `codex`, `cursor`, `portable` adapters, judged by adapter identity, so a custom adapter registered under one of those names counts as advanced — with another target. Only the built-in hosts agree on where their unshared documents live, which directories each discovers, and one install surface, so a third-party adapter is built alone: `targets: ['']` into its own `--output`. A single-target selection never triggers it. | +| `AB4103` | Selected projections disagree on the bytes at a shared path. Make the shared component compatible or build the conflicting projections separately. Target ordering never authorizes overwriting it. | +| `AB4105` | A host-scoped command/rule would be discovered by another selected host. Correct the scope/content or separate the artifacts. Distinct filenames alone do not prove discovery isolation. | +| `AB4106` | An advanced third-party adapter is combined with another target. The current custom-adapter contract requires an isolated single-target build; registering an adapter under a built-in name does not grant the built-in layout guarantees. | -All three are listed with `AB4100` in the [Diagnostics reference](./diagnostics.md). +Skills are shared by the selected targets. A host extension that changes the generated Skill +bytes can still produce a real `AB4103` conflict. An explicit rejection is safer than shipping a +composite whose effective behavior depends on which host discovers it first. ## The root is distributable -The composite root is the unit of distribution: no packaging step follows the build. It carries -the components the selected hosts read, one generated `INSTALL.md` — a section per selected host, -written with the bundle's real plugin and marketplace names — and the install surface those hosts -require, emitted once for the whole selection: +A copied composite artifact needs no per-host recompilation. It carries its generated installation +instructions and the required installation support. **npm delivery still needs an npm packaging +step** using the generated npm root; a directory build is not already a tarball. -| Selected host | Marketplace manifest | Install surface | -| --- | --- | --- | -| `amp` | — | Copy `.amp/plugins//` to the project or system plugin root. | -| `claude` | `.claude-plugin/marketplace.json`. | `claude plugin marketplace add` + `claude plugin install`. | -| `codex` | `.agents/plugins/marketplace.json`. | `codex plugin marketplace add` + `codex plugin add`. | -| `cursor` | `.cursor-plugin/marketplace.json` when `marketplace: true`. | `install.mjs`. | -| `portable` | — | `install.mjs`. | - -`INSTALL.md` is written whenever a built-in host is selected; `install.mjs` when `cursor` or -`portable` is among them. Artifact validation errors when a required install-surface file is -missing, so a root cannot ship without the installer its `INSTALL.md` promises. The npm pack -inventory checks the same paths (`AB7010`). +| Selected target | Supported installation direction | +| --- | --- | +| `amp` | Install the nested generated directory under the documented project/user plugin location; reload through the host's documented interactive action. | +| `claude` | Native marketplace registration and plugin installation from the declared composite root. | +| `codex` | Native marketplace registration and plugin addition from the declared composite root. | +| `cursor` | Receipt-owned local copy or the explicitly selected marketplace workflow. | +| `portable` | Follow the recorded reader's instructions. The included `install.mjs` is the documented Cursor-compatible path, not a universal installer for every portable reader. | + +The framework's `install --from` resolves the selected native location from the composite root. +Consumers can follow `INSTALL.md` without installing the compiler. A plugin may additionally +provide a thin package-bound bin through `agent-bundle/install`; that entry is opt-in, not +automatically generated for every package. + +With package output enabled, `dist/` is a complete npm root: a copy of the validated composite, +`package.json`, standard package documents, and declared package-only entries. A generated routed +CLI is copied unchanged and referenced as `bin/.mjs`. An authored package bin instead +compiles to `bin/.js`. There is no required nested `artifact/` directory inside the tarball. +See [shipping](../guide/distribution/index.mdx) for `prepack`, actual `npm pack`, and installed-bin +proof. npm installation does not automatically register a plugin with a host. ## agent-bundle.manifest.json -One manifest is emitted per root (`manifestVersion: 4`). It is the root's **index** — the one -document every consumer reads to learn what the root contains — and the input to every later -integrity check: `validate --artifact`, `prepack`, `install`, `doctor --from`, `serve-app`, `mcp`, -`hooks`, and the packed and installed-host proof levels. The full field reference is the -[Artifact manifest](./artifact-manifest.mdx) page; in outline: +The current closed artifact contract is **`manifestVersion: 4`**. It is the index of the built +application, not another file the plugin author maintains. -| Section | Contents | +| Section | Responsibility | | --- | --- | -| `manifestVersion`, `runtime` | `4`, and `{ node }`, the consumer-facing generated-executable floor. | -| `application` | The identity, once and host-independent: `id`, `name`, `version`, optional `description`. What `install`, `doctor`, and `uninstall` act on. | -| `files[]` | Every emitted file: `path`, `bytes`, `sha256`, `kind` (`bundle`, `copy`, `generated`, `prebuilt`), optional `mode`. | -| `projections[]` | One row per selected host, sorted by `host`: `host`, optional `builtInHost`, the `documents` pointers to the host plugin, marketplace, MCP, and hooks documents the projection emitted, and its `marketplace` name. | -| `routes` | The compiled route graph: `servers[]`, `events[]`, `scripts[]`, `cli`, `providers[]`, `layouts[]`, `contracts[]` (when a route binds one), and its `digest`. A bound route names its contract with `route.contract`. | -| `executables` | Every process the root can start: `bins[]`, `hooks[]` (one row per wrapper per host), `mcpServers[]` with their `entry` and `apps[]`, and `scripts[]`. | -| `distribution` | `channels` (`local`, plus `npm` when `compiler.project.packageName` is present), the `install` pointers to `INSTALL.md` / `install.mjs`, and `payloads[]` — each prebuilt payload directory with the hosts it was packaged for and its declared `runtimeDependencies`. | -| `compiler` | Operational record, versioned by `recordVersion` independently of `manifestVersion`: `producer`, `project` (`configPath`, `configDigest`, `modelDigest`, `revision`, `sourceInputs`, optional `packageName` / `packageVersion`), `provenance[]` (one `{ path, sourceInputs[] }` per `files[]` row), `adapters[]` (`adapterRevision`, `observedVersion`, pinned `schemas` per projection), `agentSkills`, and `validation`. | -| `web` | **Absent unless [`web`](./configuration.mdx#web) is configured.** `{ open, apps[] }` where each app is `{ allow, app, args, entry, env, name, resourceUri, server, tool?, input? }`. `entry` is the root-relative compiled MCP executable and must name a `files[]` row; `args` are the server's declared `mcp.servers..args` after the entry and `env` its declared static env, both with `agent-bundle:path:*` tokens left unexpanded. Apps are sorted by `app`; an exposed App whose `targets` fall outside the root's selection is omitted (and the section with it when none remain). The ` web` command, `agent-bundle dev` `/web//`, and `doctor` read this section and never rediscover Apps from `src/**`. | - -Only `build` writes it; everything in it is derived from the configuration, the conventional -filesystem, and the compiled model, and its bytes are canonical — every reader rejects a -hand-edited copy. Because every file carries a digest, validation compares **real bytes** rather -than checking that a path exists, and a hand-edited generated file fails. That contract is what -makes `validate --artifact`, `mcp`, and `hooks` work against an artifact whose project sources -have been deleted. The host documents and manifest are serialized from the same compiled model -in one build, and every host document is a digest-pinned `files[]` row, so a hand edit fails the -digest check. +| `application`, `runtime` | Plugin identity/version and the selected generated-executable Node floor. | +| `files` | Emitted file inventory, kinds, sizes, digests and applicable modes. | +| `projections` | Selected host bindings and pointers to native documents/entries. | +| `routes` | Canonical operation, contract, CLI projection, event, layout and provider records. | +| `executables` | The exact bins, hooks, MCP servers and scripts, including canonical launch bindings where applicable. | +| `distribution` | Channels, installation support and declared prebuilt payload requirements. | +| `compiler` | Producer, source/provenance, adapter and validation evidence, separately versioned from the public artifact contract. | +| `web` | Optional declared App exposure and policy referencing the existing server/App records. It does not contain a second copy of the server entry, argv or environment. | + +For compiled/prebuilt MCP servers, canonical launch arguments distinguish **artifact references** +from **literal values**. A slash in a literal does not make it a relocatable artifact path. +The launcher expands only the supported declared tokens at the appropriate boundary. + +The `web.apps` rows contain App identity, server association, allowed capabilities and optional +opening tool/input. Launch selection comes from the corresponding executable/projection record. +Do not reconstruct it from browser-profile selection or add `entry`, `args`, and `env` to each +web App. The exact field definitions are in [Artifact manifest](./artifact-manifest.mdx). + +The compiler emits both the native documents and the canonical manifest. Structural validation, +canonical representation, referenced-file checks and content digests have distinct roles; a +reader that parses the manifest is not necessarily running every artifact-validation check. +Use the appropriate public validation command, and do not change digests to bless modified output. + +Persisted `agent-bundle.compile-evidence.json` binds compiler evidence to emitted bytes. +A matching hash is not a universal proof about reflective or unanalyzed runtime loading. +Residual checks and prebuilt dependency declarations remain necessary where compiler evidence +cannot establish self-containment. See [validation](../guide/distribution/validation.mdx). ## Versions and revisions -Four version axes are tracked separately and are expected to agree: - -- **Source** — the project's `package.json` release version. -- **Built artifact** — `compiler.project.packageVersion` in the manifest. -- **Installed artifact** — the manifest found under a host's installed root. -- **Running process** — the version a live MCP `initialize` reports. +Keep source package version, built artifact version, installed artifact version and observed +running-server version distinct when collecting evidence. The installed-host proof compares the +relevant observations; absent observations must not be invented. -The `host-install` proof level records all four and fails closed when any is missing or differs. -`prepack` gates the first two plus normalized plugin metadata and host manifests (`AB7013`), and -refuses a `package.json` whose installed-dependency fields name packages no packed declaration, -consumer install script, or prebuilt `runtimeDependencies` proves a consumer needs (`AB7014`) — or that a consumer's npm cannot fetch from a registry -(`AB7015`). A package merely inlined into a compiled bundle does not count as used. The -[validation guide](../guide/distribution/validation.mdx) lists every source of evidence. +An adapter revision and its observed native-host version describe a different contract from the +plugin's own release version. The compiler record also has an independently versioned shape. +Do not update a private manifest reader independently of the compiler that emits its input. +Use a compatible public compiler/runtime/lifecycle package set and validate the actual deliverable. -`compiler.adapters[]` records an `adapterRevision` (monotonic, repository-owned) and an -`observedVersion` (the host version the capability evidence was recorded against). Neither is -hashed: Git already versions repository-owned content, and hashing it again inside the repository -causes churn on every table edit. Hash pins are reserved for vendored external content — host -document schemas under `src/adapters/schemas/*` with their `PROVENANCE.json`, the Agent Skills -schema pin, and emitted files and source inputs. +`prepack` checks the applicable package/manifest version and dependency evidence. A dependency +inlined into generated JavaScript is not automatically a consumer runtime dependency; prebuilt +payloads, declarations and supported install scripts can establish real requirements. ## Next -- [Artifact manifest](./artifact-manifest.mdx) — every field of `agent-bundle.manifest.json`, who writes it, who reads it. -- [Compiler architecture](../guide/concepts/architecture.mdx) — the three - compiler layers and which production readers consume each manifest field. -- [Artifact validation](../guide/distribution/validation.mdx) — the checks that read this manifest. -- [Host installation](../guide/distribution/installation.mdx) — installing the root into each host. -- [Runtime environment](./runtime-environment.mdx) — what the emitted executables assume at run time. +- [Capability map](../guide/start/capabilities.mdx): supported targets, feature navigation and proof boundaries. +- [Artifact manifest](./artifact-manifest.mdx): exact fields and canonical ownership. +- [Compiler architecture](../guide/concepts/architecture.mdx): implementation stages and readers. +- [Artifact validation](../guide/distribution/validation.mdx): checks over the delivered root. +- [Host installation](../guide/distribution/installation.mdx): scopes, ownership, replacement and removal. +- [Runtime environment](./runtime-environment.mdx): execution assumptions and writable state. diff --git a/website/docs/zh/guide/authoring/_meta.json b/website/docs/zh/guide/authoring/_meta.json index ae2a9e0d3..4f5a704e7 100644 --- a/website/docs/zh/guide/authoring/_meta.json +++ b/website/docs/zh/guide/authoring/_meta.json @@ -1 +1 @@ -["index", "skills", "hooks", "mcp", "scripts-assets", "package-entries"] +["index", "reuse-framework", "skills", "hooks", "mcp", "scripts-assets", "package-entries"] diff --git a/website/docs/zh/guide/authoring/reuse-framework.mdx b/website/docs/zh/guide/authoring/reuse-framework.mdx new file mode 100644 index 000000000..4d8c36d9c --- /dev/null +++ b/website/docs/zh/guide/authoring/reuse-framework.mdx @@ -0,0 +1,173 @@ +--- +description: '用同一个工具提供 CLI 与 App 表面，复用契约、事件 preflight、请求上下文、可写状态、payload 和安装能力，而不是手写框架胶水代码。' +--- + +# 复用框架 + +从能解决问题的最小编写表面开始。路由就是操作；CLI 投影或浏览器 App 是使用它的另一种方式。 +框架负责注册、传输、编译和安装，插件负责自己的产品行为。 + +完整源码树见[项目结构](../start/project-structure.mdx)。哪些宿主能消费某个表面，见 +[能力地图](../start/capabilities.mdx)。 + +## 一个工具，一个操作 + +把操作放在约定路由中；当领域计算较复杂时，将它移到普通的导入模块中以便阅读。 +不需要注册数组、生成路由文件的脚本、自定义 `McpServer` 或按字符串名字派发的执行器。 + +```tsx +// src/mcp/tools/tools/hello.tsx +import React from 'react'; +import { Agent } from '@agent-bundle/runtime'; +import type { ToolConfig, ToolRouteProps } from 'agent-bundle'; +import { z } from 'zod'; + +export const config = { + description: 'Greet a person.', + annotations: { readOnlyHint: true }, +} satisfies ToolConfig; +export const inputSchema = z.object({ name: z.string().min(1) }).strict(); +export const resultSchema = z.object({ greeting: z.string() }).strict(); + +export default async function Hello({ input }: ToolRouteProps) { + const result = { greeting: `Hello, ${input.name}.` }; + return ( + + {result.greeting} + + ); +} +``` + +这里服务器名是 `tools`，协议工具名是 `hello`，规范路由 ID 是 `tool:tools/hello`。 +不需要再次注册这些身份。可以按产品的实际工具分组选择有意义的服务器名，不必每个操作创建一个服务器。 + +`readOnlyHint` 是描述性元数据，不会替代安全策略执行。校验、权限敏感决定和副作用保护仍必须存在于 +操作真正执行的路径中。 + +## 将同一个工具暴露为 CLI 命令 + +添加同目录投影，而不是第二个处理器： + +```ts +// src/mcp/tools/tools/hello.cli.ts +import type { CliProjectionConfig } from 'agent-bundle/routes'; + +export const config = { + command: ['hello'], + confirm: false, +} satisfies CliProjectionConfig; +``` + +此处 `confirm: false` 是对只读问候操作的明确选择。不要未经审核就把它复制到修改型操作。 +生成的命令调用同一工具，并使用它的规范 schema 校验。 + +受支持的 aliases、flags、positionals 和同步 `mapInput` 仅用于转换 CLI 语法。 +不要在 mapper 中重复领域操作或结果渲染器。真正独立的聚合工作流仍可使用单独的 `src/cli/**` 路由。 + +自动 flag 推导使用有界 schema 语法。复杂嵌套或 union schema 即使不能投影为命名 flags，仍然可以是有效工具。 +已有批量 MCP 命令路径支持 JSON 输入；给命名投影添加 `mapInput` 不会让它自动获得该模式。 +请使用[包入口](./package-entries.mdx)记录的实际支持路径，不要削弱工具 schema，也不要假装未实现的选项存在。 + +## 共享契约，而不是再建 schema 注册表 + +路由可以导入受支持的本地 schema，并导出为 `inputSchema` 或 `resultSchema`。 +维护一份权威领域契约。生成的声明文件提供路由 ID、App 结果类型与 provider 类型，但不会把刻意宽松的 schema +自动变成精确契约。 + +在领域边界校验不可信外部响应，然后渲染规范化后的 receipt。成功、部分数据与预期失败可能需要不同分支。 +不要要求错误分支包含成功字段，不要虚构缺失标识，也不要从已渲染的文本报告中反向解析操作本来就有的数据。 + +调用方输入与处理器接收到的解析后输入在概念上不同：默认值和转换在解析时执行。 +当前生成的调用类型仍在部分调用方契约中使用 schema 输出。这个限制不意味着应该增加另一份浏览器 schema +或使用宽泛的 `as any`；参见[故障排查](../development/troubleshooting.mdx)与 +[配置](./index.mdx)中的 schema 说明。 + +## 添加浏览器 App，不重做传输层 + +浏览器 App 位于 `src/mcp//apps/*`。其 `config` 声明资源 URI，以及需要时的 HTML 模板。 +使用受支持的元数据与 `appResourceUri` 辅助函数将工具关联到 App。编译器负责资源注册与资源打包。 + +浏览器入口使用生成的工具 ID 和公开客户端： + +```ts +import { createAppClient } from 'agent-bundle/app'; +import { name, version } from 'agent-bundle/meta'; + +const client = createAppClient({ appInfo: { name, version } }); +const result = await client.call('tool:tools/hello', { name: 'Ada' }); +``` + +这个片段只说明类型化调用，不是完整 App 启动顺序。在真正的 App 中，先注册 opening-input、result、error +与 cancellation 处理器，再调用 `client.connect()`，并在视图生命周期结束时释放客户端。 +完整的 [MCP App 示例](../../examples/mcp-app.mdx)展示了该顺序及真实工具/资源。 +首次打开通知与后续 `client.call` 的返回结果是不同来源。 + +不要实现父窗口消息 RPC、第二套初始化握手、另一个 pending-request map，或为约定路由手工声明 `AppRegister`。 +App 仍然负责本地选择、格式化、轮询策略，以及 loading/error 界面。给变量添加生成类型，不会让 TypeScript +自动校验任意外部消息。 + +`Agent.*` 树是面向智能体的输出，不是浏览器 DOM。浏览器 App 可以使用普通 DOM 或 React。 +共享领域契约不意味着在浏览器运行时导入服务器模块；生成的仅类型导入必须保持仅类型。 + +## 有意识地选择语义事件或普通 hook + +需要 Agent 输出、请求上下文和可选 preflight 时，使用 `src/events/**` 规范事件路由。 +简单执行加小结果已经足够时，使用配置声明的普通处理器及公开 `HookHandler`/`HookEvent` 类型。 +两种情况下都不需要重复原生 stdin/stdout 包装层。 + +preflight 门禁应位于昂贵操作或有副作用的工作之前。原生 payload 字段并不跨宿主统一； +可用时读取规范字段，并如实保留 unknown 或缺失证据。stop、deny、continue 或更新输入必须保留宿主的真实决定语义。 +无关的日志失败不能悄悄把已确定的保护决定变成允许继续。 + +基于能力的 `requires` 与显式 target 范围解决不同问题。在选择事件、matcher、provider 子集或原生专属行为前， +查阅[hook 指南](./hooks.mdx)与[事件矩阵](../../reference/events.md)。 +原生 hook 文档是明确的高级扩展路径，不是重建语义事件的默认方式。 + +## 使用观测到的上下文，分开代码和数据 + +只有执行中的路由需要请求身份、provider、capability、lineage、state 或 notice 时，才调用 `await agent()`。 +在 `src/providers/*` 声明共享请求依赖，不要另建应用级全局服务定位器。 +provider 值应具有操作预期的请求生命周期。 + +请求中的插件绑定已经区分代码与框架可写状态。不要再拼接 `CLAUDE_PLUGIN_ROOT`、`CURSOR_PLUGIN_ROOT` +与猜测的产物目录优先级链。真正独立运行的代码可以使用文档中的公开 resolver，并明确 fallback 策略。 + +asset 是代码侧不可变输入。缓存、数据库、登录后取得的 session 与操作 receipt 是可变数据。 +选择明确的应用所有可写位置，保留显式 operator override，并由插件管理迁移/保留策略。 +不要在普通执行期间改写已安装包的 `.env`，也不要把框架 kernel 文件当作无结构的领域数据目录。 +参见[运行环境](../../reference/runtime-environment.mdx)。 + +notice 使用框架 ledger 及[notice 矩阵](../../reference/notices.md)中的受支持通道。 +发布、尝试投递和确认接收是不同状态；写入成功不证明智能体已经看到了 notice。 + +## 通过声明打包资源和可执行文件 + +根据输入类型使用 Skill 自带资源目录、`assets`、约定脚本或 `definePrebuilt`。 +预构建 payload 是复制进去的，不会变成编译后的 TypeScript 依赖。 +使用受支持的依赖声明记录 payload 在消费者运行时真正需要的包；不要默认 externalize 普通生成代码。 + +生成的可执行路径、启动参数和投影绑定由编译器清单拥有。 +消费者不应扫描 `mcp/` 猜文件、假定 `args` 首项始终是 Node 入口、替换输出 JavaScript 字符串， +或根据未经校验的清单修复权限。 + +使用生成的原生安装说明或公开的包绑定 `agent-bundle/install` 入口。 +带品牌的 installer 可以是一层薄绑定，但不能再变成原生 cache 管理器、receipt 数据库或生命周期参数解析器。 +参见[交付](../distribution/index.mdx)。 + +## 测试你改动的那一层 + +| 改动 | 最小有用证明，以及需要时的更强证明 | +| --- | --- | +| 领域计算 | 注入外部服务的确定性领域测试。 | +| 路由渲染、schema 或上下文 | 使用真实生成图与声明的公开路由测试。 | +| MCP 注册或 CLI 投影 | 框架协议/CLI 辅助函数，加至少一个编译后的一致性用例。 | +| 浏览器 App 行为 | 公开浏览器 harness，覆盖 opening 成功/错误/取消，再加真实生成服务器流程。 | +| 打包、路径或安装 | 真实打包后/删除源码运行，以及基于 receipt 所有权的安装测试。 | +| 宿主行为 | 单独标注的、使用真实授权的原生宿主测试；mock 不是已认证的模型调用。 | + +测试应保留独立的预期身份和安全结果。所有预期都从被测输出本身推导，无法发现错误改名或缺失 annotation。 +反过来，也不应仅为测试插件领域行为，就把框架整个传输实现复制进测试 fixture。 + +目标是删除重复的所有权：一张路由图、一套领域契约、一个受支持的客户端桥接，以及一套生命周期实现。 +一个有用的领域辅助函数，不会因为框架也有辅助函数就变成缺陷。 diff --git a/website/docs/zh/guide/development/_meta.json b/website/docs/zh/guide/development/_meta.json index 019782edf..8f0cba67a 100644 --- a/website/docs/zh/guide/development/_meta.json +++ b/website/docs/zh/guide/development/_meta.json @@ -1 +1 @@ -["index", "workbench", "testing", "evaluations"] +["index", "workbench", "testing", "evaluations", "troubleshooting"] diff --git a/website/docs/zh/guide/development/troubleshooting.mdx b/website/docs/zh/guide/development/troubleshooting.mdx new file mode 100644 index 000000000..88fb5cf46 --- /dev/null +++ b/website/docs/zh/guide/development/troubleshooting.mdx @@ -0,0 +1,106 @@ +--- +description: '排查路由缺失、生成类型变弱、target 不兼容、App 启动、包根目录、运行状态和测试证据问题，而不是再写注册表或安装器。' +--- + +# 故障排查 + +先确定失败的边界：编写的源码、编译产物、已安装包，还是正在运行的宿主。 +不要手工修复生成文件；修改拥有该行为的源声明，再重新构建。 +[能力地图](../start/capabilities.mdx)区分受支持输出与受支持的客户端行为。 + +## 确认版本和正在检查的对象 + +在项目中安装正确的框架包后： + +```sh +npx --no-install agent-bundle --version +npx --no-install agent-bundle validate +npx --no-install agent-bundle inspect --json +``` + +对于复制来的产物，应检查该产物，而不是无关的源码工作区： + +```sh +npx --no-install agent-bundle inspect --artifact artifact --json +npx --no-install agent-bundle validate --artifact artifact +``` + +`inspect --artifact` 不与源码 `--root` 或 `--config` 组合。 +`validate --artifact` 接收纯组合产物；清单感知的安装路径也能理解 npm 根目录。 +这些根目录的 inventory 职责不同，参见[交付](../distribution/index.mdx)。 + +报告问题时记录 compiler/runtime 包选择器，以及 artifact/application 版本。 +预览包应来自同一个不可变构建。正式 compiler/runtime 版本号可以不同； +使用匹配脚手架记录的配对，不要假定数字版本号必须相同。 + +## 找到最小修正 + +| 症状 | 检查与修正 | +| --- | --- | +| 文件没有成为工具，或没有出现在 Workbench | 检查实际路由路径、受支持扩展名、私有 `_`/`.` 路径段、ignore 规则和显式服务器模式。检查路由图。custom/command/remote 服务器不是生成路由服务器；不要为补偿它再建一份注册清单。 | +| 创建项目时拒绝一个受支持 target | 对照脚手架选项与编译器 target 目录。当前 Amp 选项缺口不意味着 Amp 适配器不存在。使用兼容源码项目/配置并查阅 Amp 的 MCP 限制，不要假定每个 starter 都适用。 | +| 组合因路径或发现冲突失败 | 阅读 `AB4103`、`AB4105` 或 `AB4106` 及受影响组件。让共享内容兼容，或有意分开构建不兼容投影。调整 target 顺序或覆盖生成文件不能解决问题。 | +| hook 缺失，或原生决定与预期不同 | 检查生成的事件/hook 矩阵、选中宿主、matcher、能力需求及精确原生 payload。使用 `hooks list` 和文档中的宿主专属模拟。不要用虚构 allow/deny 代替缺失证据。 | +| TypeScript 接受无效 App 路由 ID，或丢失 provider/结果类型 | 确认生成成功，并且 `.agent-bundle/routes.d.ts` 属于实际消费它的浏览器/服务器/测试程序。某个兄弟 tsconfig 包含它，不证明另一个也包含。 | +| 带默认值的输入字段在 App 类型中意外变成必填 | 当前生成器对部分调用方契约使用了解析后的 schema 输出。不要把这个类型错误当作运行时不支持默认值的证据。保留规范 schema，区分已知类型边界与无效运行输入。 | +| 添加命名 CLI 投影后复杂 schema 被拒绝 | 自动 flags 使用有界语法。查阅受支持的 canonical-JSON 批量命令路径；单独添加 mapper 不会扩展命名投影语法。不要仅为提取 flags 而拍平真实领域契约。 | +| App 资源存在，但宿主没有显示浏览器界面 | 区分提供 MCP App 与特定客户端/版本渲染它。按 MCP App 参考使用单独标注的本地预览检查；HTML 存在不是原生展示证据。 | +| App 预览选择了无法启动该服务器的宿主 | 构建级 target 列表不等于该服务器的合格启动列表。选择实际合格投影。不要仅为满足界面而添加虚假的 portable 服务器。 | +| App 一直 loading，或错误看起来像空成功 | 连接公开客户端之前注册 input/result/error/cancellation 处理器。预期工具错误不一定进入成功结果回调。检查实际 opening 调用，而不只是后续手工调用。 | +| App 预览直到 opening 调用结束才出现 | 主要 Workbench App workspace 当前会等待完成。底层 pending bridge 和浏览器 harness 本身不会使该 workspace 成为实时 pending 预览。不要为 UI 生命周期缺口再建客户端传输层。 | +| npm 安装成功，但可执行文件缺失 | 打包正确的生成 npm 根目录，检查实际 `package.json.bin` 和 tarball inventory。生成路由 bin 使用清单可执行路径；手写包 bin 使用另一种输出路径。不要沿用旧的嵌套 `artifact/` 假设。 | +| 安装拒绝清单版本或变动的摘要 | 对齐发射编译器与消费它的生命周期实现，保持公开包配对一致。不要独立升级私有源码 reader，也不要编辑封闭的清单版本或 digest。 | +| 只读安装插件在写入时失败 | 保持代码/assets 不可变，使用观测到的框架 state 位置和明确的领域数据策略。取得的 session 或 cache 不是打包 asset，也不是改写已安装 `.env` 的理由。 | +| MCP stdio 无法解析输出 | 不要向 JSON-RPC stdout 通道写应用日志。使用生成生命周期或正确限定的自定义服务器入口，诊断写 stderr。 | +| 默认测试通过，却没发现路由损坏 | 检查脚本收集哪些测试。当前 MCP starter 的 `check` 包含 route/projection pools，但单独 `npm test` 不包含。在脚本契约更新前使用完整的文档 check。 | +| 原生测试被跳过，或账户不可用 | 记录缺失前提和未完成证明。mock、构建或安装成功不是已认证的工具/hook 执行；unverified 与 unsupported 不同。 | + +## 全新工作区中的生成类型 + +生成声明不是手写源码。在独立 typecheck 前运行当前受支持的生成路径，失败时停止： + +```sh +npx --no-install agent-bundle validate +npm run typecheck +``` + +项目需要自己的 `typecheck` 脚本和正确的 tsconfig inclusion。 +准备失败后可能保留旧生成文件，不要把它描述为最新。 +当前 inclusion 警告并非所有 project references 的完整审计。 +对于 solution-style 配置，验证每个实际消费程序；不要只把文件加进无关根程序以消除警告。 +不要为获取类型而把服务器实现导入浏览器运行时代码。 + +starter 当前完整检查命令是： + +```sh +npm run check +``` + +按需测试池见[测试](./testing.mdx)，规范契约见[复用框架](../authoring/reuse-framework.mdx)。 +纯静态插件不应只为模仿 MCP starter 就增加 React/MCP 测试依赖。 + +## 安装与替换 + +使用交付的 `INSTALL.md` 或受支持的包绑定安装器。 +原生注册、文件放置、启用和实时会话是不同状态。 +解释 receipt 或重新加载步骤前，请阅读[安装指南](../distribution/installation.mdx)。 + +使用 `doctor` 做只读安装状态检查。 +不同版本或外来目录可能要求明确的 operator 决定；不要从 `rm -rf`、全局 cache 编辑或校验前权限修复开始。 +keep-data 与 purge 的所有权要求不同。 +缺少历史所有权，不代表可以删除推导出来的目录。 + +打包测试使用临时数据和隔离宿主根目录。 +不要把真实密码、tracker session、私钥或正在使用的 operator 数据放进可复现 fixture。 + +## 有用的问题报告证据 + +记录包选择器、Node 版本、最小相关配置与路由、精确命令、结构化诊断，以及运行来自源码、artifact、 +已安装包还是原生宿主。写清预期行为与实际终态。 + +App/session 问题中，分别记录服务器、工具、启动投影和浏览器 profile。 +重建问题标明新旧 revision，不必附上无关原始日志。 +隐藏凭据、authorization header、session cookie 和私有命令数据，不要上传整个环境变量转储。 + +适用时链接[诊断参考](../../reference/diagnostics.md)或对应能力记录。 +测试失败、文档中的限制与未执行的验收用例，需要不同的后续工作；写明证据实际确立的是哪一种。 diff --git a/website/docs/zh/guide/start/_meta.json b/website/docs/zh/guide/start/_meta.json index 7d40fbbbd..7a0868d5a 100644 --- a/website/docs/zh/guide/start/_meta.json +++ b/website/docs/zh/guide/start/_meta.json @@ -1 +1 @@ -["index", "installation", "quick-start", "project-structure"] +["index", "installation", "quick-start", "capabilities", "project-structure"] diff --git a/website/docs/zh/guide/start/capabilities.mdx b/website/docs/zh/guide/start/capabilities.mdx new file mode 100644 index 000000000..8df13dd6e --- /dev/null +++ b/website/docs/zh/guide/start/capabilities.mdx @@ -0,0 +1,151 @@ +--- +description: '选择全部五个内置输出 target，查阅自动生成的能力矩阵，并区分插件生成、客户端兼容性、浏览器展示与经过验证的执行。' +--- + +# Target 与能力地图 + +本页回答三个问题：**该编写什么、该选择哪种输出，以及能力边界在哪里**。 +要先做出一个可用工具，请从[快速开始](./quick-start.mdx)入手。精确且带版本记录的宿主行为由 +自动生成的矩阵说明；不要假定所有宿主都实现同一种插件接口。 + +## 全部内置输出 target + +以下是 `agent-bundle.config.ts` 的 `targets` 支持的五个内置值。它们选择编译器生成的内容， +不是账户、模型或正在运行的开发会话。 + +| Target | 输出与预期读取方 | 重要边界 | +| --- | --- | --- | +| `amp` | `.amp/plugins//` 下的原生目录插件：`index.js` PluginAPI 工厂、显式注册的 Skills，以及映射后的事件回调。 | MCP 配置属于 Skill。适配器支持单个捆绑 Skill 旁边的、受支持的远程服务器或全局可解析命令，不支持编译器拥有的本地 MCP 入口。Amp 安装与真实账户执行是不同的证明级别。 | +| `claude` | Claude Code：`.claude-plugin/plugin.json`、生成的市场条目，以及适用时的 `hooks/hooks.json` 与 `.mcp.json`。 | 编译后的语义 hook 与显式编写的原生 hook 使用不同的编写契约。LSP 等原生扩展仍是 Claude 专属配置。 | +| `codex` | Codex：`.codex-plugin/plugin.json`、指向自身 hook/MCP 文档的显式路径，以及 `.agents/plugins/marketplace.json`。 | CLI、编辑器和桌面客户端的行为需要分别限定。提供 MCP App 资源不意味着每个 Codex 客户端都会显示它。 | +| `cursor` | Cursor：`.cursor-plugin/plugin.json`、自身 hook/MCP 文档，以及可选的市场文档。 | 具有所有权记录的本地复制安装路径不同于原生市场 CLI 安装。不要手工改写 Cursor 的全局 hook 配置。 | +| `portable` | Agent Plugins 1.0.0：根目录 `plugin.json`、Skills，以及编写了 MCP 时的 `mcp.json`。 | 这是格式 target，不是通用宿主。它不定义原生 hooks、rules 或斜杠命令文档。每个读取客户端支持的子集单独记录。 | + +省略 `targets` 时只选择 `portable`。显式配置会替换这个默认值： + +```ts twoslash +import { defineConfig } from 'agent-bundle/config'; + +export default defineConfig({ + plugin: { name: 'project-tools', description: 'Tools for this project.' }, + targets: ['claude', 'codex', 'cursor'], +}); +``` + +只为某次构建选择其他投影时，重复使用 `--target`。请先在项目中安装正确的框架包： + +```sh +npx --no-install agent-bundle build --target claude --target codex +``` + +只有实际组件能够共存时，组合才有效。同一路径的不同内容、或某个宿主意外发现另一个宿主的组件， +都会导致构建错误，而不是允许后一个投影覆盖前一个。改变 target 顺序不能解决冲突。 +参见[组合规则](../../reference/targets-artifacts.mdx)。 + +当前脚手架的 target 选项尚未跟上编译器的 Amp 支持。构建 Amp 插件时，请在适合的现有项目或静态项目中 +显式设置 `targets`；不要假设生成式 MCP 模板的本地服务器符合 Amp 的 Skill 级 MCP 契约。 +嵌套安装根目录和重新加载步骤见[安装指南](../distribution/installation.mdx)。 + +## 权威能力矩阵 + +以下页面从适配器使用的同一组固定能力记录生成，包含原始文档、观测版本、详细限制和省略原因。 +不要在插件仓库中再维护一套原生支持清单。 + +| 问题 | 查阅位置 | +| --- | --- | +| target 支持哪些组件、传输方式、路径占位符、原生元数据和安装方式？ | [宿主能力矩阵](../../reference/hosts.md) | +| 有哪些语义事件和普通 hook 事件、哪些 payload 字段存在、工具选择器如何映射？ | [事件与 hook 矩阵](../../reference/events.md) | +| 支持哪些 notice 通道与接收方身份，什么才算送达？ | [Notice 投递矩阵](../../reference/notices.md) | +| 会生成哪些文件和可执行记录？ | [Target 与产物](../../reference/targets-artifacts.mdx)和[产物清单](../../reference/artifact-manifest.mdx) | +| 这一次实际构建选择或省略了哪个组件？ | `agent-bundle inspect --json`；计划记录 selected/skipped 组件、原因和按组件种类划分的能力判断。 | + +每项能力判断都限定到具体功能及其证据： + +| 状态 | 对作者的含义 | +| --- | --- | +| `supported` | 记录的 target/版本有证据支持该行为；不等于你的操作已经在该宿主成功运行。 | +| `degraded` | 可用的是受限或经转换的行为。依赖它之前先阅读原因。 | +| `unavailable` | 当前记录下，框架没有受支持的实现路径。原因可能是宿主缺少功能，也可能是缺少证据；两者不是同一结论。 | +| `prohibited` | 契约明确拒绝这种用法。不要复制私有实现来绕开诊断。 | + +运行验证是另一个维度。适配器可以已经实现，但依赖账户的激活仍然是 **unverified**。 +没有账户不是宿主无法执行操作的证据；反过来，文件放置成功也不证明宿主已启用插件或调用工具。 + +## 框架能构建什么 + +下表是编写导航，不承诺每个 target 都接受每一种组件。可用性由宿主矩阵和实际构建的 inspection 决定。 + +| 需求 | 常规编写路径 | 框架职责 / 指南 | +| --- | --- | --- | +| 可复用指令与资源 | `src/skills//SKILL.md` | 发现、校验、打包和投影 Skills；[Skills](../authoring/skills.mdx)。静态 Skill 不需要服务器。 | +| 生成指令内容 | 文档支持的 rendered Skill 源码 | 构建时渲染为 Skill 产物，不是常驻宿主服务；[Skills](../authoring/skills.mdx)。 | +| 宿主斜杠命令或规则 | `src/commands/*.md`、`src/rules/*.mdc` | 校验受支持的 frontmatter 与原生发现行为；[配置](../authoring/index.mdx)。Markdown 命令不是可执行 CLI 路由。 | +| 可调用工具、资源或提示 | `src/mcp//{tools,resources,prompts}/*` | 生成注册、服务器生命周期、契约和协议投影；[MCP](../authoring/mcp.mdx)。 | +| 从终端复用工具 | 同目录的 `.cli.ts` | 将 argv 投影到规范操作；[包入口](../authoring/package-entries.mdx)。 | +| 独立终端工作流 | `src/cli/**` | 生成命令树、参数处理、输出和退出语义。用于不同的工作流，而不是再复制一遍工具。 | +| 面向智能体的结构化与可读输出 | 可执行路由返回 `Agent.*` 元素 | 组合 Agent Document 及各表面的输出；领域计算仍属于插件。 | +| 工具的浏览器视图 | `src/mcp//apps/*`，加显式工具关联 | 编译 MCP App，通过 `agent-bundle/app` 连接；[MCP Apps 示例](../../examples/mcp-app.mdx)。 | +| 不通过智能体界面打开 App | `serve-app` 或声明的 `web` 暴露 | 复用本地浏览器宿主和同意边界；[CLI](../../reference/cli.mdx)。它不是新的部署 target。 | +| 跨宿主事件行为 | `src/events/**`，可选 preflight | 规范化事件并投影受支持的决定/上下文；[hooks](../authoring/hooks.mdx)。 | +| 轻量普通 hook | 使用公开 hook 类型的配置声明处理器 | 管理原生 stdin/stdout 与结果编码，不要求 Agent renderer；[hooks 与脚本示例](../../examples/hooks-and-scripts.mdx)。 | +| 共享渲染与请求依赖 | `src/layout.tsx`、服务器布局、`src/providers/*` | 组合受支持的路由并挂载观测到的请求上下文；[项目结构](./project-structure.mdx)。浏览器 App 和事件不会自动成为文档布局的子节点。 | +| 框架 state 与 notices | `src/state.ts` 和公开请求句柄 | 提供声明的生命周期、journal/notice 机制与真实可用性；[运行环境](../../reference/runtime-environment.mdx)和[notices](../../reference/notices.md)。 | +| 脚本、静态资源或不透明可执行 payload | `src/scripts/*`、assets 或 `definePrebuilt` | 按声明打包或复制；[脚本/资源](../authoring/scripts-assets.mdx)和[payload](../authoring/package-entries.mdx)。声明 payload 真正需要的运行依赖。 | +| npm bin/库输出与安装 | 按需使用 `bin`/`lib`；可选 `agent-bundle/install` 入口 | 组装规范包根并复用生命周期所有权；[交付](../distribution/index.mdx)。 | +| 测试与智能体评估 | 公开 test/browser/Rstest 与 eval 辅助函数 | 区分路由、协议、打包与原生证据；[开发](../development/index.mdx)。 | + +高级 custom/command/remote MCP 服务器、原生元数据、原生 hook 文档、预构建 payload 和打包器覆盖仍按文档支持。 +它们解决真实的集成需求，不是编写普通工具之前必须完成的设置。 + +## 兼容客户端不是额外 target + +宿主矩阵中的 **Recorded third-party clients** 部分描述现有输出格式的读取方。 +这些客户端名称不是 `targets` 的额外取值。某宿主的研究 issue 也不代表已经存在可安装的适配器。 + +同时阅读客户端的 tier 与各表面记录。仅支持 Skills 的客户端可能不读取 `plugin.json`。 +能读取 `mcp.json` 的客户端不一定展开启动服务器所需的路径占位符。安装命令可能只是注册目录， +而不是复制目录。高优先级清单可能重定向组件路径；单独的 MCP 文件覆盖不一定遮蔽无关的 Skills。 +插件未编写的可选组件不会凭空出现。 + +详情以[生成的客户端记录](../../reference/hosts.md)中的带日期来源为准。 +笼统地说某客户端“支持插件”，不足以证明它能消费这个具体产物。 +这里不会把尚无已实现或已记录路径的宿主宣传为受支持 target。 + +## 构建、开发与展示是不同维度 + +| 表面 | 如何选择 | 不意味着什么 | +| --- | --- | --- | +| 编译 | `targets` / 构建 `--target` | 所有选中宿主提供相同功能，或共享完全相同的原生安装根目录。 | +| 开发安装 | `dev --install-host claude`、`codex` 或 `cursor` | 每个原生 target 都支持实时开发代理。Amp 使用文档中的复制/重新加载路径。 | +| 嵌入式宿主终端 | 已安装且受支持的 Claude/Codex 会话集成 | 身份验证、信任和成功的模型执行由真实宿主提供，不是 Workbench 模拟出来的。 | +| App 展示 | 受支持的浏览器宿主 `--profile` | 该 profile 是原生输出 target，或它就是正确的服务器启动投影。 | +| npm 分发 | 打包生成的 npm 根目录 | 安装 npm 包会自动把插件注册到智能体宿主。 | + +通过高级 `TargetRegistry` 注册的第三方适配器，在当前组合契约下单独构建。 +它们不会自动继承内置 target 之间的发现隔离保证。 + +## 检查自己的插件 + +各 inspection focus 分开运行，不要在同一次调用中组合多个 focus： + +```sh +npx --no-install agent-bundle inspect --json +npx --no-install agent-bundle inspect --routes --json +npx --no-install agent-bundle inspect --hooks --json +npx --no-install agent-bundle inspect --state --json +npx --no-install agent-bundle validate +``` + +构建之后，不需要重新发现源码即可检查和校验交付物： + +```sh +npx --no-install agent-bundle inspect --artifact artifact --json +npx --no-install agent-bundle validate --artifact artifact +``` + +事件需求是语义性的时，使用受支持的 `config.requires` 能力声明；刻意面向原生行为时，使用显式宿主选择。 +不要通过丢弃阻止决定、虚构上下文或扩大批准范围来宣称支持。 +互斥声明和能力不可用诊断见事件指南。 + +交付物应保留生成的 `INSTALL.md`，并遵循其中真实的宿主、根目录与 scope 指令。 +成功编译、打包进程测试、原生安装与经过身份验证的智能体调用证明的是不同事情；记录实际执行过的级别。 diff --git a/website/docs/zh/reference/index.mdx b/website/docs/zh/reference/index.mdx index c470afb57..2a52bc800 100644 --- a/website/docs/zh/reference/index.mdx +++ b/website/docs/zh/reference/index.mdx @@ -1,50 +1,60 @@ --- -description: 'agent-bundle 参考资料：命令行表面、配置字段、target 产物、运行时环境、安全边界、已知限制，以及生成的类型 API。' +description: 'Agent Bundle 的精确 CLI、配置、产物与运行契约，以及生成的宿主/事件/notice 能力地图、诊断、公开 API 和实用故障排查。' --- # 参考 -指南讲的是如何构建并交付一份捆绑包。本章是查阅用的那一半：确切的标志、确切的字段名、确切的默认值， -以及框架拒绝跨越的那些边界。 - -这里不重复任何教程。凡是指南中已经解释过的概念——配置模型、七个钩子事件、证明级别——本章只链接过去， -并仅记录契约本身。 +指南用于构建插件，本章用于核对精确字段、参数、默认值和边界。 +[Target 与能力地图](../guide/start/capabilities.mdx)集中列出全部五个内置输出及其可投影功能。 | 页面 | 回答什么 | | --- | --- | -| [命令行](./cli.mdx) | 每条命令、参数、选项、默认值与退出码。 | -| [配置](./configuration.mdx) | `agent-bundle.config.ts` 的每个字段、类型与校验规则。 | -| [Target 与产物](./targets-artifacts.mdx) | 复合插件根目录、各宿主投影向其中添加什么，以及产物清单契约。 | -| [宿主能力矩阵](./hosts.md) | 固定的各宿主能力表：版本、清单、安装方式、路径 token、MCP 传输、插件组件。构建时生成。 | -| [事件与钩子矩阵](./events.md) | 各宿主的规范事件到原生事件、工具选择器到原生匹配器、被推迟的原生事件。构建时生成。 | -| [通知投递矩阵](./notices.md) | 每个宿主支持哪些通知通道，其余通道为何不可用。构建时生成。 | -| [诊断参考](./diagnostics.md) | 每个 `AB` 代码族、触发条件、严重级别与恢复提示。构建时从仓库契约生成。 | -| [开发服务器 HTTP](./dev-server-http.mdx) | 浏览器侧调用、Trace、Raw-log 与宿主钩子收据路由及其 wire 形状。 | -| [运行时环境](./runtime-environment.mdx) | Node 版本下限、路径 token、环境变量、`.env` 分层与持久状态位置。 | -| [安全](./security.mdx) | 凭据、网络与信任边界。 | -| [已知限制](./limitations.mdx) | 框架目前不做什么、不能证明什么。 | -| [类型 API](./api.mdx) | 全部公开导出的生成式符号参考。 | +| [Target 与能力地图](../guide/start/capabilities.mdx) | 该编写哪个表面；原生 target、兼容读取方、开发/展示支持之间的区别。 | +| [CLI](./cli.mdx) | 命令、参数、选项、默认值和退出码，包括 inspection、hook、MCP、安装与本地 App 托管。 | +| [配置](./configuration.mdx) | `agent-bundle.config.ts` 的字段、类型和校验规则。 | +| [Target 与产物](./targets-artifacts.mdx) | 全部五个内置投影布局、组合约束、分发形式及可执行文件所有权。 | +| [产物清单](./artifact-manifest.mdx) | 规范 application、route、executable、launch、distribution 与 compiler 记录形状。 | +| [宿主能力矩阵](./hosts.md) | 固定版本、原生文档、安装、路径 token、MCP 行为、lineage、插件组件和已记录兼容客户端。由适配器能力数据生成。 | +| [事件与 hook 矩阵](./events.md) | 规范事件族、原生事件、payload 字段来源、工具选择器和推迟的原生事件。由相同记录生成。 | +| [Notice 投递矩阵](./notices.md) | 接收方身份维度、支持通道、敏感度约束和无法投递原因。由相同记录生成。 | +| [诊断参考](./diagnostics.md) | 诊断代码、级别、触发条件和恢复方式。由仓库契约生成。 | +| [开发服务器 HTTP](./dev-server-http.mdx) | 高级集成使用的 invocation、trace、raw-log 和 hook-receipt 路由。 | +| [运行环境](./runtime-environment.mdx) | Node 最低版本、路径 token、环境分层、观测上下文和可写状态。 | +| [安全](./security.mdx) | 凭据、网络、沙箱、同意与信任边界。 | +| [限制](./limitations.mdx) | 不支持、有意受限或现有证据尚未建立的行为。 | +| [类型 API](./api.mdx) | 公开包导出的生成符号参考。 | +| [故障排查](../guide/development/troubleshooting.mdx) | 路由/类型缺失、target 不匹配、App 生命周期、包根目录和验证问题。 | + +生成矩阵不是另一套手工维护的兼容列表。带日期的来源链接说明记录的行为。 +`supported`、`degraded`、`unavailable` 和 `prohibited` 是功能判断； +尚未执行的账户相关运行测试属于独立的验证限制。 +应查阅具体组件与客户端/版本，不要假定一个宿主徽标涵盖全部操作。 + +编写模式见[复用框架](../guide/authoring/reuse-framework.mdx)： +同一工具的 CLI 与 App 表面、规范 schema、语义/普通 hook、请求依赖、state、payload 与安装。 +自定义服务器工厂和原生文档仍是高级集成路径，不是插件的最小必需代码。 ## 如何读诊断 -每条命令报告的都是结构化诊断，而不是散文式错误。一条诊断包含稳定的 `AB` 代码、一个严重级别、一条消息， -通常还有 `sourcePath` 与一条 `recovery` 提示。对于由诊断把关的命令——`build`、`prepack`、`validate`、 -`doctor`、`install` 与 `dev`——只有 **error** 级别才会让命令以非零退出；warning 与 info -绝不会为构建、校验或 dev 重建把关。`eval` 与 `inspect` 还有一个与诊断无关的以 `1` 退出的理由： -失败或无定论的试验，或者无效的模型——见[命令行退出码](./cli.mdx#退出码)。 +结构化诊断包含代码、严重级别、消息，以及可用时的源码位置与恢复提示。 +也要阅读命令的最终结果：参数解析错误、失败或 inconclusive 的 eval，以及无效 inspection model +属于不同失败路径。 -完整的代码目录见[诊断参考](./diagnostics.md)，它在构建时由仓库中的 -[`docs/diagnostics.md`](https://github.com/ScriptedAlchemy/agent-bundle/blob/main/docs/diagnostics.md) -渲染而来。 +只有 error 诊断会阻断由诊断决定的检查。 +`--strict` 等选项可以把适用的宿主工具 warning 提升为 error， +因此不能仅因先前未提升的 warning 对某工作流只是信息，就忽略当前非零结果。 +精确命令行为见 [CLI 退出码](./cli.mdx#退出码)。 -| 家族 | 领域 | +| 代码族 | 领域 | | --- | --- | -| `AB30xx` | Skill 文档：Markdown 解析与渲染式 skill 编译。 | -| `AB40xx`–`AB47xx` | 插件元数据、规范化模型不变式、钩子、MCP、脚本、资源、包构建，以及打包器逃生舱。 | -| `AB48xx`–`AB49xx` | 路由图、state、布局与 provider 约定：路由模块发现、`config` 提取、共享布局（`AB4830`–`AB4832`），以及编译后的命令表面。 | -| `AB5000` | 通用的命令行与适配器失败。 | -| `AB60xx` | 已构建产物校验，包括宿主 schema 文档与被引用的文件。 | -| `AB700x`–`AB7015` | 宿主安装与 npm prepack 门禁（`AB7014`/`AB7015`：安装期依赖卫生）。 | -| `AB7xxx` | 项目准备与开发期重建，其中 `AB7300`–`AB7320` 为只读 Doctor。 | -| `AB8xxx` | 开发服务器配置与 Workbench 路由。 | -| `AB9xxx` | eval 选择、harness 与持久化运行记录。 | +| `AB30xx` | Skill 解析与渲染内容。 | +| `AB40xx`–`AB47xx` | 身份、target 组合、hook、MCP、assets、包输出和打包器策略。 | +| `AB48xx`–`AB49xx` | 约定路由、契约、布局、provider、state 和生成命令表面。 | +| `AB5000` | 通用命令/适配器边界失败。 | +| `AB60xx` | 产物、原生文档、引用文件和编译证据校验。 | +| `AB7xxx` | 包/安装检查、项目准备、重建和 Doctor。 | +| `AB8xxx` | 开发服务器与 Workbench 边界。 | +| `AB9xxx` | 评估与持久运行记录。 | + +这些代码族只是导航，不替代[完整生成诊断参考](./diagnostics.md)。 +修正拥有该行为的声明或输入；不要为压下错误而改写生成清单、虚构运行证据或扩大原生权限。 diff --git a/website/docs/zh/reference/targets-artifacts.mdx b/website/docs/zh/reference/targets-artifacts.mdx index fd2dbf232..57f291fb1 100644 --- a/website/docs/zh/reference/targets-artifacts.mdx +++ b/website/docs/zh/reference/targets-artifacts.mdx @@ -1,194 +1,192 @@ --- -description: 'agent-bundle build 输出的组合插件根目录：各宿主投影把清单、钩子与 MCP 文档放在何处、钩子 wrapper 的命名规则、AB4103/AB4105/AB4106 组合规则、可选的清单 web 节，以及产物清单契约。' +description: '全部五种内置输出投影、各自的原生发现路径、组合约束、规范 artifact/npm 根目录，以及由清单拥有的执行与 web 绑定。' --- # Target 与产物 -target 表格——各宿主投影携带什么，以及 portable 标准为何省略规则、命令与钩子——在 -[配置模型](../guide/authoring/index.mdx)中。源码树布局在[项目结构](../guide/start/project-structure.mdx)中。 -本页讲的是输出契约：`build` 输出的那一个目录，以及其中的字节必须满足的产物清单。 +先用[Target 与能力地图](../guide/start/capabilities.mdx)选择表面。 +[生成的宿主矩阵](./hosts.md)记录功能支持及证据。 +本页描述实际输出，以及下游工具消费的对象。 -## 组合插件根目录 +## 复合插件根目录 -`agent-bundle build` 在产物输出位置写出**一个目录**——默认是 `artifact/`；`output.distPath` 或 `--output` -可以移动它。`targets` 选择铺进该根目录的**宿主投影**：`amp`、`claude`、`codex`、`cursor` 与 `portable`， -可任意组合。Claude Code、Codex、Cursor 与 portable 把根目录当作插件根；Amp 则读取生成在 -`.amp/plugins//` 的那一个目录。 +`agent-bundle build` 写出一个组合产物根目录，默认是 `artifact/`。 +`output.distPath` 或 CLI `--output` 可以移动根目录，但不会重新设计内部布局。 +五种内置投影是 **`amp`、`claude`、`codex`、`cursor` 和 `portable`**。 -- 省略 `targets`——配置与命令行都省略——时，构建只输出 `portable` 投影。 -- 顺序无关。`['codex', 'claude']` 与 `['claude', 'codex']` 产出逐字节相同的输出，规范化模型、产物清单与 - `inspect` 都按名称排序列出所选宿主。 -- `plugin` 不是 target。`targets: ['plugin']` 或 `--target plugin` 是未知 target（`AB4100`）：组合根目录 - 本来就是每次构建的输出。 +省略 `targets` 时只选择 `portable`。 +显式选择可以组合内置投影，但编写的组件必须符合兼容性规则。 +target 顺序不改变结果。`plugin`、`web`、`npm` 和浏览器展示 profile 不是额外的内置 target。 -以全部五个投影构建时，host-test 示例的根目录如下（组件目录只在项目编写了对应组件时才会出现）： +以下是组合布局示意，不承诺空插件也会输出每个文件。 +实际可执行名称及包含的组件以生成清单为准。 ```text artifact/ -├── .amp/plugins//index.js # Amp PluginAPI 工厂 -├── .amp/plugins//skills/ # 显式注册的 Amp Skill -├── .amp/plugins//hooks/.mjs # Amp 事件回调 wrapper -├── .amp/plugins//hooks/hooks-flight.mjs # 同目录的独立事件 worker -├── .agents/plugins/marketplace.json # Codex 市场 -├── .claude-plugin/plugin.json # Claude Code 清单 +├── .amp/plugins// +│ ├── index.js # 原生 Amp 工厂 +│ ├── skills/ # 显式注册的 Skills +│ └── hooks/ # 映射回调的可执行支持 +├── .claude-plugin/plugin.json ├── .claude-plugin/marketplace.json -├── .codex-plugin/plugin.json # Codex 清单 -├── .codex-plugin/hooks.json # Codex 钩子文档 -├── .codex-plugin/mcp.json # Codex MCP 文档 -├── .cursor-plugin/plugin.json # Cursor 清单 -├── .cursor-plugin/marketplace.json -├── .cursor-plugin/hooks.json # Cursor 钩子文档 -├── .cursor-plugin/mcp.json # Cursor MCP 文档 -├── .mcp.json # Claude Code MCP 文档 -├── plugin.json # portable（Agent Plugins）清单 -├── mcp.json # portable MCP 文档 -├── hooks/hooks.json # Claude Code 钩子文档 -├── hooks/.mjs # wrapper：钩子只被一个所选宿主选中 -├── hooks/..mjs # wrapper：钩子被多个所选宿主共享 -├── hooks/hooks-flight.mjs -├── mcp/mcp--.mjs # 编译后的 MCP 入口（+ -flight.mjs） -├── bin/.mjs, bin/-flight.mjs # 路由式 CLI 和/或 web -├── scripts/, skills/, commands/, rules/, assets/, mcp-apps/ # 只输出一次 -├── INSTALL.md # 选中了任一内置宿主时 -├── install.mjs # 选中了 cursor 或 portable 时 -├── agent-bundle.manifest.json # 产物索引（manifestVersion 4） -└── agent-bundle.compile-evidence.json # 每个已编译文件的编译器记录 +├── .codex-plugin/plugin.json +├── .codex-plugin/hooks.json +├── .codex-plugin/mcp.json +├── .agents/plugins/marketplace.json +├── .cursor-plugin/plugin.json +├── .cursor-plugin/hooks.json +├── .cursor-plugin/mcp.json +├── .mcp.json # Claude MCP 文档 +├── plugin.json # portable 清单 +├── mcp.json # portable MCP 文档 +├── hooks/hooks.json # Claude hook 文档 +├── hooks/ # 编译后的宿主绑定 wrapper/worker +├── mcp/ # 编译后的 MCP 入口及 worker +├── bin/ # 生成 CLI / 配置的 web 命令 +├── skills/, commands/, rules/ +├── scripts/, assets/, mcp-apps/ +├── INSTALL.md +├── install.mjs # 所选 Cursor/portable 安装路径 +├── agent-bundle.manifest.json +└── agent-bundle.compile-evidence.json ``` -`agent-bundle.compile-evidence.json` 是编译器对每个已编译（`bundle`）文件的记录； -`validate --artifact` 把已列入清单的记录对照文件表复核（`AB6039`）。 +根目录共享组件只输出一次。 +Amp 目录插件把已注册的 Skills 和执行支持保留在自身嵌套目录中，以保证安装副本自包含。 +因此，原生 Amp 安装根并不是组合产物根。 -宿主清单位于根目录下各自的点目录中。根级 `skills/`、`hooks/`、`mcp/`、`scripts/`、`bin/` 与 `assets/` -是共享的，只输出**一次**。Amp 注册的 Skill、事件 wrapper，以及各目录内与这些 wrapper 同级的独立 -worker 都保留在 `.amp/plugins//` 内，使安装后的插件保持自包含。根目录下不会出现其他任何东西： -没有生成的 `AGENTS.md`，也没有 `hooks/hooks-cursor.json`，也没有 `web/` 目录。已配置 MCP App 的浏览器 -宿主作为框架拥有的 `web` 命令装在 `bin/.mjs` 里。该 bin 在 `src/cli/**` 编译出至少一条命令时、 -在配置了 -[`web`](./configuration.mdx#web) 时（即使没有手写 CLI 命令），或两者兼有时输出。 +纯静态 Skills 插件不需要空 MCP 服务器，也不需要 Flight/state 进程。 +当另一个所选宿主在约定 fallback 路径上有内容时，某些空原生 hook/MCP 文档是有意设置的发现隔离屏障。 +不要把它们当作未使用文件删除。 ### 各宿主从哪里读取文档 -| 宿主 | 清单 | 钩子文档 | MCP 文档 | 市场 | +| Target | 入口或清单 | Hook 注册 | MCP 配置 | Marketplace | | --- | --- | --- | --- | --- | -| Amp | ——；`index.js` 记录为 `documents.entry` | 由 `amp.on` 注册回调 | 已注册 Skill 旁的扁平 `skills//mcp.json` | —— | -| Claude Code | `.claude-plugin/plugin.json` | `hooks/hooks.json` | `.mcp.json` | `.claude-plugin/marketplace.json` | -| Codex | `.codex-plugin/plugin.json` | `.codex-plugin/hooks.json` | `.codex-plugin/mcp.json` | `.agents/plugins/marketplace.json` | -| Cursor | `.cursor-plugin/plugin.json` | `.cursor-plugin/hooks.json` | `.cursor-plugin/mcp.json` | `marketplace: true` 时为 `.cursor-plugin/marketplace.json` | -| portable | `plugin.json` | —— | `mcp.json` | —— | +| `amp` | `.amp/plugins//index.js` | 原生 PluginAPI 回调 | 显式注册的 Skill 旁边、Skill 级别的 `mcp.json` | 不生成 | +| `claude` | `.claude-plugin/plugin.json` | `hooks/hooks.json` | `.mcp.json` | `.claude-plugin/marketplace.json` | +| `codex` | `.codex-plugin/plugin.json` | `.codex-plugin/hooks.json` | `.codex-plugin/mcp.json` | `.agents/plugins/marketplace.json` | +| `cursor` | `.cursor-plugin/plugin.json` | `.cursor-plugin/hooks.json` | `.cursor-plugin/mcp.json` | 按需生成 `.cursor-plugin/marketplace.json` | +| `portable` | `plugin.json` | 格式没有原生 hook 组件 | `mcp.json` | 不生成 | -无论选择了哪些宿主，这些路径都是固定的，因此单宿主根目录与五宿主根目录共用同一种布局。Amp 的目录隔离在 -`.amp/plugins//` 下；Claude Code 与 -portable 的 Agent Plugins 格式从约定的插件根位置加载文档，无法重定向；Codex 与 Cursor 的清单携带显式的 -`hooks` 与 MCP 指针，因此它们的文档紧挨着各自的清单。这两个宿主在指针缺失时还会回退到对约定路径的目录 -发现，因此当钩子或 MCP 服务器到达另一个所选宿主的约定路径时，没有自己文档的 Codex 或 Cursor 投影仍会 -指向一份空文档——Cursor 绝不会加载 Claude Code 的 `hooks/hooks.json`。 +有效的单 target 与多 target 选择使用稳定路径。 +Codex 和 Cursor 通过显式指针避免读取其他投影的 fallback 文档。 +第三方 portable 客户端可能有不同优先级和支持子集；应查阅[宿主矩阵](./hosts.md)中的独立记录， +而不是把本表当作其原生布局。 -### 钩子 wrapper +### Hook 包装器 -钩子 wrapper 会把它所面向的宿主（该宿主的编解码、`target`、宿主契约修订）烤进自身，因此一个 wrapper -无法同时服务两个宿主： +编译 hook wrapper 绑定所选宿主的 codec 与契约。 +同一份 hook 源码因此可能生成多个 wrapper。 +配置声明的 hook 只到达一个宿主时使用普通名称，到达多个宿主时使用宿主限定名称。 +约定语义事件和独立 worker 同样记录在 `executables.hooks` 中。 -- 只触达一个所选宿主的钩子保留普通名字 `hooks/.mjs`。 -- 触达多个所选宿主的钩子按宿主各输出一次，即 `hooks/..mjs`，各宿主的钩子文档指向自己的 - 那个 wrapper。 +使用 `hooks list` 和清单，不要自己构造 wrapper 文件名。 +原生事件、payload 来源、matcher 与返回语义见[事件矩阵](./events.md)。 +显式 targets 和受支持的事件 `requires` 声明影响选择，但都不能制造宿主无法表达的事件或决定。 -配置钩子触达哪些宿主，由它的 `targets`（默认是全部 target）与所选宿主取交集决定。事件路由也可以改为 -声明 `requires`；编译器会把所选宿主与支持全部指定能力行的宿主取交集。因此同一个源钩子在仅 `claude` -的根目录中是 `hooks/audit.mjs`，在 `claude` + `cursor` 的根目录中则是 `hooks/audit.claude.mjs` -加 `hooks/audit.cursor.mjs`。每个所选宿主的原生钩子都会保留。清单的 `executables.hooks[]` 为每个宿主的每个 -wrapper 各记一行——没有单独的钩子索引文件——`hooks list`、`hooks simulate` 与产物校验（`AB6018`）读的就是 -这些行。 +### 编译表面 -### 编译产出面 +生成的 MCP 入口、脚本、CLI bin 和浏览器 App 归属于组合选择，不会为每个宿主重新构建成互不相关的应用。 +Agent Document renderer 与浏览器 App 编译使用不同环境。 -MCP 入口、脚本、路由式 CLI bin 与 MCP App 只编译**一次**，归属于**组合身份**——所选宿主名按名称排序、以 -`+` 连接，例如 `claude+codex`——而不是归属于任何单个宿主。`agent-bundle inspect --bundler` 显示的是同一 -件事：它的 `output.path` 就是产物输出 ``，其下没有宿主段。 +Amp 的 MCP 投影属于 Skill。 +当前适配器允许与恰好一个捆绑 Skill 关联的、受支持的远程服务器及全局可解析命令服务器； +对于没有受支持原生路径/cwd 契约的编译器自有本地 MCP 入口，则予以拒绝。 +把 Amp 列为 target，不会使普通本地生成 MCP starter 自动兼容 Amp。 -Amp 的 MCP 是例外：它位于 Skill 范围，而非插件根 MCP 文档。适配器只在恰有一个捆绑 Skill 时接受可搬迁的 -远程服务器与全局可解析命令。Amp 未文档化插件根 token 或执行 `cwd`，所以编译器拥有的本地 MCP 入口会被拒绝。 +配置 `web` 表面后，即使没有手写 CLI 命令，框架也会向 `bin/.mjs` 加入自有 web 命令。 +它是声明的 MCP App 的本地浏览器宿主，不是 `web` 输出 target、另一份生成的 `web/` 应用， +也不是绕过 App 同意机制的许可。 ### 一个根目录，一套字节 -按路径合并投影，只有在各宿主对字节达成一致时才行得通。三条规则守住根目录的诚实，它们都是错误，且 -`validate` 与 `inspect` 会在 `build` 拒绝的同一位置报告它们： - -| 代码 | 规则 | +| 诊断 | 约束与恢复 | | --- | --- | -| `AB4103` | 两个所选投影为同一路径规划了不同的字节。投影按宿主名顺序比较、路径按路径顺序比较，因此无论 `targets` 怎么写，同一选择报告的都是同一处冲突。常见原因是 frontmatter 带有宿主扩展（`targets: { claude: … }`）的 Skill：它为 Claude Code 降级出的 `skills//SKILL.md` 字节与其他宿主不同。请让该组件对每个所选宿主都一致，或把冲突的宿主构建进单独的产物。 | -| `AB4105` | 一个只面向部分所选宿主的组件——frontmatter 带 `targets` 的命令或规则——位于另一个所选宿主会扫描的约定目录中（Claude Code 与 Cursor 的 `commands/`、Cursor 的 `rules/`）。在同一个根目录里无法把该文件对那个宿主隐藏起来，因此构建宁可拒绝也不泄漏它。请把 `targets` 扩展到每个会发现该目录的所选宿主，或把这些宿主分开构建。Skill 从不按宿主限定：每个 skill 都会交付给所有所选宿主，会改变其字节的按宿主 frontmatter 扩展属于 `AB4103` 冲突。 | -| `AB4106` | 所选目标把注册在高级 `TargetRegistry` 上的适配器——即任何其适配器不是随框架发布的 `amp`、`claude`、`codex`、`cursor`、`portable` 适配器的目标，按适配器身份而非名称判断，因此以这些名字注册的自定义适配器同样算作高级适配器——与另一个目标混在一起。只有内建宿主就各自不共享的文档放在何处、各自扫描哪些目录以及同一套安装面达成了一致，因此第三方适配器要单独构建：`targets: ['']` 输出到自己的 `--output`。只选一个目标时永不触发。 | - -三者与 `AB4100` 一起列在[诊断参考](./diagnostics.md)中。 +| `AB4103` | 所选投影对共享路径的内容有分歧。让共享组件兼容，或分别构建冲突投影。target 顺序从不授权覆盖。 | +| `AB4105` | 面向部分宿主的 command/rule 会被另一个所选宿主发现。修正范围/内容，或分离产物。不同文件名本身不证明发现隔离。 | +| `AB4106` | 高级第三方适配器与另一 target 组合。当前自定义适配器契约要求隔离的单 target 构建；用内置名称注册适配器不会自动获得内置布局保证。 | -## 根目录即可分发 +Skills 由所选 targets 共享。宿主扩展若改变生成的 Skill 内容，仍可能触发真正的 `AB4103` 冲突。 +明确拒绝，比交付一个行为取决于谁先发现它的组合更安全。 -组合根目录就是分发单位：构建之后没有打包步骤。它携带所选宿主要读取的组件、一份生成的 `INSTALL.md` -——每个所选宿主一节，以捆绑包真实的插件名与市场名写成——以及这些宿主所需的安装表面，为整个选择只输出 -一次： +## 根目录可直接分发 -| 所选宿主 | 市场清单 | 安装表面 | -| --- | --- | --- | -| `amp` | —— | 把 `.amp/plugins//` 复制到项目或系统插件根。 | -| `claude` | `.claude-plugin/marketplace.json`。 | `claude plugin marketplace add` + `claude plugin install`。 | -| `codex` | `.agents/plugins/marketplace.json`。 | `codex plugin marketplace add` + `codex plugin add`。 | -| `cursor` | `marketplace: true` 时为 `.cursor-plugin/marketplace.json`。 | `install.mjs`。 | -| `portable` | —— | `install.mjs`。 | +复制组合产物不需要逐宿主重新编译。 +它包含生成的安装说明和必要安装支持。 +**npm 分发仍需要基于生成 npm 根目录的 npm 打包步骤**；目录构建不等于已经生成 tarball。 -只要选中了内置宿主就会写出 `INSTALL.md`；其中包含 `cursor` 或 `portable` 时还会写出 `install.mjs`。 -当必需的安装表面文件缺失时，产物校验会报错，因此根目录不可能在缺少其 `INSTALL.md` 所承诺的安装器的 -情况下发布。npm pack 清单会检查同样的路径（`AB7010`）。 +| 所选 target | 支持的安装方向 | +| --- | --- | +| `amp` | 把嵌套生成目录安装到文档规定的 project/user 插件位置；使用宿主文档中的交互操作重新加载。 | +| `claude` | 从声明的组合根进行原生市场注册和插件安装。 | +| `codex` | 从声明的组合根进行原生市场注册和插件添加。 | +| `cursor` | 基于 receipt 所有权的本地复制，或显式选择的市场工作流。 | +| `portable` | 遵循记录的读取方说明。内含 `install.mjs` 是文档中的 Cursor 兼容路径，不是所有 portable 读取方的通用安装器。 | + +框架的 `install --from` 从组合根解析所选原生位置。 +消费者可以遵循 `INSTALL.md` 而不安装编译器。 +插件还可通过 `agent-bundle/install` 提供薄包绑定 bin；它是显式选择，不会为每个包自动生成。 + +启用包输出时，`dist/` 是完整 npm 根：已校验组合产物的副本、`package.json`、标准包文档，以及声明的包专用入口。 +生成路由 CLI 原样复制，并由 `bin/.mjs` 引用；手写包 bin 则编译为 `bin/.js`。 +tarball 内不要求嵌套 `artifact/`。 +`prepack`、实际 `npm pack` 与安装 bin 的证明见[交付](../guide/distribution/index.mdx)。 +npm 安装不会自动将插件注册到宿主。 ## agent-bundle.manifest.json -每个根目录输出一份清单（`manifestVersion: 4`）。它是根目录的**索引**——每个消费者都通过这一份文档了解 -根目录包含什么——也是之后每一项完整性检查的输入：`validate --artifact`、`prepack`、`install`、 -`doctor --from`、`serve-app`、`mcp`、`hooks`，以及 packed 与 installed-host 证明级别。完整的字段参考见 -[产物清单](./artifact-manifest.mdx)页；概要如下： +当前封闭产物契约为 **`manifestVersion: 4`**。 +它是构建应用的索引，不是另一份需要插件作者维护的文件。 -| 分节 | 内容 | +| 部分 | 职责 | | --- | --- | -| `manifestVersion`、`runtime` | `4`，以及 `{ node }`，即面向消费者的生成式可执行文件下限。 | -| `application` | 身份，只记录一次且与宿主无关：`id`、`name`、`version`，可选的 `description`。这是 `install`、`doctor` 与 `uninstall` 作用的对象。 | -| `files[]` | 每个输出文件：`path`、`bytes`、`sha256`、`kind`（`bundle`、`copy`、`generated`、`prebuilt`）、可选的 `mode`。 | -| `projections[]` | 每个所选宿主一行，按 `host` 排序：`host`、可选的 `builtInHost`、指向该投影输出的宿主插件、市场、MCP 与钩子文档的 `documents` 指针，以及它的 `marketplace` 名。 | -| `routes` | 编译后的路由图：`servers[]`、`events[]`、`scripts[]`、`cli`、`providers[]`、`layouts[]`、`contracts[]`（当有路由绑定时）及其 `digest`。绑定了契约的路由用 `route.contract` 命名它。 | -| `executables` | 根目录能启动的每个进程：`bins[]`、`hooks[]`（每个宿主的每个 wrapper 一行）、带 `entry` 与 `apps[]` 的 `mcpServers[]`，以及 `scripts[]`。 | -| `distribution` | `channels`（`local`，当 `compiler.project.packageName` 存在时再加 `npm`）、指向 `INSTALL.md` / `install.mjs` 的 `install` 指针，以及 `payloads[]`——每个预构建负载目录、它所打包的宿主及其声明的 `runtimeDependencies`。 | -| `compiler` | 运行记录，由 `recordVersion` 独立于 `manifestVersion` 版本化：`producer`、`project`（`configPath`、`configDigest`、`modelDigest`、`revision`、`sourceInputs`，可选的 `packageName` / `packageVersion`）、`provenance[]`（每个 `files[]` 行一条 `{ path, sourceInputs[] }`）、`adapters[]`（每个投影的 `adapterRevision`、`observedVersion`、固定的 `schemas`）、`agentSkills` 与 `validation`。 | -| `web` | **除非配置了 [`web`](./configuration.mdx#web)，否则不出现。** `{ open, apps[] }`，每个 app 为 `{ allow, app, args, entry, env, name, resourceUri, server, tool?, input? }`。`entry` 是根相对的已编译 MCP 可执行文件，必须对应一行 `files[]`；`args` 是该服务器在 entry 之后声明的 `mcp.servers..args`，`env` 是其已声明的静态 env，二者的 `agent-bundle:path:*` 令牌都保持未展开。App 按 `app` 排序；`targets` 落在本根选择范围之外的已暴露 App 会被省略（若一个都不剩则整个小节省略）。` web` 命令、`agent-bundle dev` 的 `/web//` 与 `doctor` 读取这一节，绝不会从 `src/**` 重新发现 App。 | - -只有 `build` 写它；其中的一切都派生自配置、约定文件系统与编译后的模型，字节是规范的——每个读取方都会拒绝 -被手工改过的副本。由于每个文件都携带摘要，校验比对的是**真实字节**，而不是检查路径是否存在，因此被手工 -改过的生成文件会失败。正是这一契约，让 `validate --artifact`、`mcp` 与 `hooks` 能在项目源码已被删除的产物 -上工作。根目录中的宿主文档与清单在同一次构建中由同一个编译模型序列化而成；每份宿主文档都是带摘要固定的 -`files[]` 行，因此手工编辑会使摘要校验失败。 +| `application`、`runtime` | 插件身份/版本，以及生成可执行文件所选的 Node 最低版本。 | +| `files` | 输出文件 inventory、种类、大小、digest 和适用的 mode。 | +| `projections` | 所选宿主绑定，以及指向原生文档/入口的指针。 | +| `routes` | 规范操作、契约、CLI 投影、事件、布局和 provider 记录。 | +| `executables` | 精确的 bin、hook、MCP 服务器和脚本，适用时包括规范启动绑定。 | +| `distribution` | 通道、安装支持和预构建 payload 的依赖声明。 | +| `compiler` | Producer、源码/provenance、适配器与校验证据，其版本独立于公开产物契约。 | +| `web` | 可选的 App 暴露及策略，引用已有服务器/App 记录；不再复制一份服务器 entry、argv 或 env。 | + +对于编译或预构建 MCP 服务器，规范启动参数区分**产物引用**与**字面值**。 +字面值带斜杠并不意味着它是可重定位产物路径。 +启动器只在正确边界展开受支持的声明占位符。 + +`web.apps` 记录包含 App 身份、服务器关联、允许能力及可选 opening tool/input。 +启动选择来自对应 executable/projection 记录。 +不要从浏览器 profile 推导启动，也不要把 `entry`、`args` 和 `env` 再加到每个 web App 中。 +精确字段定义见[产物清单](./artifact-manifest.mdx)。 + +原生文档与规范清单都由编译器生成。 +结构校验、规范表示、引用文件检查与内容摘要承担不同职责；仅解析清单的 reader 不一定正在运行全部产物校验。 +使用适当的公开验证命令，不要改写 digest 来认可被修改的输出。 + +持久化的 `agent-bundle.compile-evidence.json` 把编译器证据绑定到输出字节。 +摘要一致不等于对反射加载或未分析运行时加载的通用证明。 +编译器无法建立自包含证据的地方，仍需要剩余检查和预构建依赖声明。 +参见[校验](../guide/distribution/validation.mdx)。 ## 版本与修订 -有四条版本轴被分别追踪，并且被期望彼此一致： - -- **源码** —— 项目 `package.json` 中的发布版本。 -- **已构建产物** —— 清单中的 `compiler.project.packageVersion`。 -- **已安装产物** —— 在宿主已安装根目录下找到的那份清单。 -- **运行中的进程** —— 活跃的 MCP `initialize` 所报告的版本。 +收集证据时，区分源码包版本、构建产物版本、已安装产物版本和实际运行服务器版本。 +installed-host 证明比较相关观测；缺失的观测不能被编造。 -`host-install` 证明级别会记录全部四者，并在任何一项缺失或不一致时以失败告终。`prepack` 则为前两者，外加 -规范化后的插件元数据与宿主清单把关（`AB7013`），并拒绝这样的 `package.json`：安装期依赖字段点名了 -打包后声明文件、消费者安装脚本或预构建 `runtimeDependencies` 都不能证明消费者需要的包 -（`AB7014`），或消费者的 npm 无法从注册表抓取的包（`AB7015`）。仅仅内联进已编译 bundle 的包不算已使用。 -[验证指南](../guide/distribution/validation.mdx)列出了每一种证据来源。 +adapter revision 与 observed native-host version 描述的契约不同于插件自己的 release version。 +compiler record 的形状也独立版本化。 +不要只更新私有 manifest reader，而不更新生成其输入的编译器。 +使用兼容的公开 compiler/runtime/lifecycle 包组合，并验证实际交付物。 -`compiler.adapters[]` 记录 `adapterRevision`（单调递增，仓库自有）与 `observedVersion`（记录该能力证据时所观察到的 -宿主版本）。两者都不做哈希：Git 已经为仓库自有内容做了版本管理，在仓库内部再哈希一遍会让每次编辑表格 -都产生变动噪声。哈希固定只保留给 vendored 的外部内容 —— `src/adapters/schemas/*` 下带 `PROVENANCE.json` -的宿主文档 schema、Agent Skills schema 固定值，以及输出文件与源输入。 +`prepack` 检查适用的 package/manifest 版本与依赖证据。 +内联进生成 JavaScript 的依赖不会自动变成消费者运行依赖； +预构建 payload、声明文件和受支持安装脚本则可能证明真实需求。 ## 下一步 -- [产物清单](./artifact-manifest.mdx) —— `agent-bundle.manifest.json` 的每个字段、由谁写入、由谁读取。 -- [编译器架构](../guide/concepts/architecture.mdx) —— 编译器的三层，以及哪些 - 生产读者消费清单的每个字段。 -- [产物校验](../guide/distribution/validation.mdx) —— 读取这份清单的那些检查。 -- [宿主安装](../guide/distribution/installation.mdx) —— 把根目录安装进各个宿主。 -- [运行时环境](./runtime-environment.mdx) —— 输出的可执行文件在运行时假定了什么。 +- [能力地图](../guide/start/capabilities.mdx)：受支持 targets、功能导航和证明边界。 +- [产物清单](./artifact-manifest.mdx)：精确字段与规范所有权。 +- [编译器架构](../guide/concepts/architecture.mdx)：实现阶段与读取方。 +- [产物校验](../guide/distribution/validation.mdx)：交付根目录上的检查。 +- [宿主安装](../guide/distribution/installation.mdx)：scope、所有权、替换与移除。 +- [运行环境](./runtime-environment.mdx)：执行假设与可写状态。 From 36a18979c6c3169d771c21b289312592915f19cf Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:15:53 -0700 Subject: [PATCH 03/12] docs: keep the introductory route diagram identical across locales --- website/docs/zh/guide/start/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/zh/guide/start/index.mdx b/website/docs/zh/guide/start/index.mdx index 931453240..11d228bd5 100644 --- a/website/docs/zh/guide/start/index.mdx +++ b/website/docs/zh/guide/start/index.mdx @@ -25,9 +25,9 @@ Agent Bundle 负责这些集成边界，让应用代码专注于插件本身的 ```text src/mcp/status/tools/hello.tsx ↓ - status 服务器上的 hello 工具 + hello tool on the status server ↓ - 生成的 MCP 入口 · Workbench · 测试 + generated MCP entry · Workbench · tests ``` 添加同目录的 CLI 投影，即可把同一个操作暴露为命令。需要交互式浏览器视图时再添加 App。 From a952c3046a3fa41f30e43541d16e3a9fe46f143e Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:23:05 -0700 Subject: [PATCH 04/12] docs: add target and capability map --- website/docs/en/reference/capabilities.mdx | 82 ++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 website/docs/en/reference/capabilities.mdx diff --git a/website/docs/en/reference/capabilities.mdx b/website/docs/en/reference/capabilities.mdx new file mode 100644 index 000000000..ec2e2f50d --- /dev/null +++ b/website/docs/en/reference/capabilities.mdx @@ -0,0 +1,82 @@ +--- +description: 'A practical capability map for every built-in output target, the framework surfaces that vary by host, and how to read supported, degraded, unavailable, prohibited, and unverified evidence.' +--- + +# Targets and capabilities + +Agent Bundle has **five built-in output targets**. A target is a compiler projection, not a host session, package format, or proof that every feature works identically everywhere: + +| Target | Primary generated form | Installation model | Important boundary | +| --- | --- | --- | --- | +| `amp` | `.amp/plugins//index.js` directory plugin | Framework copies the generated Amp directory to the project or user plugin root; reload remains interactive. | Amp MCP is skill-scoped. Generated local MCP entries are rejected because the pinned contract exposes no plugin-root token/cwd for a relocatable entry. | +| `claude` | `.claude-plugin/plugin.json`, `hooks/hooks.json`, `.mcp.json` | Claude Code marketplace + plugin CLI. | Use the dedicated target for Claude-native hooks, commands, output styles, LSP/settings, and other Claude extensions. | +| `codex` | `.codex-plugin/plugin.json` with adjacent hooks/MCP documents | Codex marketplace + plugin CLI. | Codex-native metadata, hook contracts, Apps compatibility, and marketplace policy stay in the Codex projection. | +| `cursor` | `.cursor-plugin/plugin.json` with adjacent hooks/MCP documents | Receipt-owned local copy, or the documented local-marketplace flow. | Cursor can also read a portable Agent Plugins pack, but the native target is what emits Cursor-specific manifests, hooks, MCP documents, rules, and metadata. | +| `portable` | root `plugin.json` + `mcp.json` using Agent Plugins 1.0.0 | The generated standalone installer is available when selected; other Agent Plugins clients may consume the built root according to their own support. | The standard intentionally does not make every native host feature portable. Skills and MCP are the core portable surfaces; native hooks/rules/commands require a target that actually supports them. | + +Omit `targets` and only `portable` is selected. `plugin` is **not** a target. Target order does not change output. The [Targets and artifacts](./targets-artifacts.mdx) page is the byte/layout contract for the composite root. + +## Capability map + +The table below answers the author question: “I wrote this kind of thing; where does support come from?” It deliberately does not copy hundreds of versioned host rows. The generated [Host capability matrix](./hosts.md), [Event and hook matrix](./events.md), and [Notice delivery matrix](./notices.md) are the exact evidence-backed sources. + +| Authoring surface | Framework responsibility | Host-dependent part | Exact source of truth | +| --- | --- | --- | --- | +| Skills and Skill resources | Discover, validate, copy/render, preserve resources, compose the selected projections. | Skill metadata/features, discovery, registration, interpolation, skill-scoped MCP. | [Hosts](./hosts.md) plus [Skills](../guide/authoring/skills.mdx). | +| MCP tools, resources, prompts | Compile conventional routes into one generated server, validate schemas/results, own stdio lifecycle and manifest executable records. | Whether/how the target can launch or register the server, transports, path tokens, tasks and structured-result behavior. | [Hosts](./hosts.md) plus [MCP servers and Apps](../guide/authoring/mcp.mdx). | +| MCP Apps | Compile the browser App, bind it to a declared server/resource/tool, generate typed App contracts, expose declared web launches. | Native App/resource support and host presentation behavior. | [Hosts](./hosts.md), [MCP servers and Apps](../guide/authoring/mcp.mdx), and the [MCP App example](../examples/mcp-app.mdx). | +| Canonical event routes and hooks | Normalize canonical events, compile wrappers, run preflight/handler logic, record exact executable ownership. | Native event availability, payload fields, matchers, blocking/rewriting semantics, supported result channels. | [Events](./events.md) and [Hooks](../guide/authoring/hooks.mdx). | +| Commands and rules | Parse/validate authored documents and place them into compatible selected projections. | Which hosts discover the component and which frontmatter/features survive. | [Hosts](./hosts.md) and [Project structure](../guide/start/project-structure.mdx). | +| Routed CLI and CLI projections | Build one command graph/bin, validate argv against the canonical route schema, reuse a tool through `.cli.ts` when it is the same operation. | Whether the selected target admits the routed CLI in its plugin root. Rich schemas may require canonical JSON input or a genuinely separate workflow. | [Hosts](./hosts.md), [Package entries](../guide/authoring/package-entries.mdx), and [CLI](./cli.mdx). | +| Scripts and assets | Compile/copy once into the composite artifact with manifest ownership and provenance. | Host discovery only matters when a component is also projected into a native host surface. | [Scripts and assets](../guide/authoring/scripts-assets.mdx) and [Targets and artifacts](./targets-artifacts.mdx). | +| Layouts, providers, state, request lineage and terminal context | Wrap framework-executed routes with shared application behavior and request-scoped context. | These are framework execution capabilities, not native manifest components; they exist where the operation executes through the generated runtime. | [Project structure](../guide/start/project-structure.mdx) and [Runtime environment](./runtime-environment.mdx). | +| Notices | Normalize notice delivery and intersect what selected hosts can advertise/deliver. | Channel availability and delivery semantics. | [Notices](./notices.md). | +| Native host extensions | Keep host-specific configuration inside its adapter and validate it against pinned evidence. | Everything: the extension exists only for the host that owns it. | [Configuration](./configuration.mdx) and [Hosts](./hosts.md). | +| Prebuilt payloads | Package opaque bytes and declared runtime dependencies without pretending the compiler analyzed their internals. | Which selected hosts receive the payload and whether the external runtime requirements are present. | [Configuration](./configuration.mdx), [Targets and artifacts](./targets-artifacts.mdx), and [Validation](../guide/distribution/validation.mdx). | + +### A useful rule + +If two surfaces are **the same operation**, author the operation once and project it. A tool plus an idiomatic CLI command normally means one MCP tool route plus a colocated `.cli.ts` projection. If they are different workflows, keep separate routes. Do not build a second application registry just to feed another surface. + +## How to read capability states + +The adapter contract has four states: + +| State | Meaning | +| --- | --- | +| `supported` | The pinned host evidence supports the capability and records the observed host/adapter version. | +| `degraded` | A useful subset is available, with a recorded limitation. Do not present it as full support. | +| `unavailable` | The pinned host contract does not provide the capability. | +| `prohibited` | The host contract or framework policy explicitly forbids the capability. | + +A separate **unverified** statement can appear in host evidence or acceptance notes. That does not mean “unsupported.” It means the static/type/fake-host contract may be implemented while live authenticated execution has not been demonstrated in the available environment. Amp live activation is a current example: installation and generated contract behavior are tested, while account-dependent live execution remains unverified. + +Do not turn `degraded` or `unverified` into a green “supported” badge, and do not turn `unverified` into “unavailable.” + +## Built-in targets versus recorded clients + +The five names above are the built-in compiler targets. The [Hosts](./hosts.md) reference also records clients that can consume some portable components. Those rows are **compatibility evidence**, not additional output targets. + +For example, a client may read Skills but not hooks, or recognize an MCP document while lacking proof that Agent Bundle path placeholders launch correctly. Select `portable` when the standard is the intended contract; add a native target only when Agent Bundle has a real adapter for the host-specific behavior you need. + +This distinction prevents a misleading support count: “recorded client,” “portable reader,” “native compiler target,” “installable native plugin,” and “authenticated runtime proof” are different claims. + +## Choose targets from requirements, not popularity + +1. Start with `portable` when Skills/MCP through the open format are enough. +2. Add a native target when the plugin needs that host's hooks, rules, commands, native metadata, installation semantics, or another capability the portable format cannot express. +3. Check the generated capability matrices for the exact host version before relying on a native event or field. +4. Use `config.requires` on event routes when the route should exist only where every named capability is supported. +5. Split builds only when the composite rules require it (`AB4103`, `AB4105`, `AB4106`) or when the product intentionally ships different plugins. + +`agent-bundle inspect --root .` shows the normalized selection and planned projections. `validate` checks source declarations; `validate --artifact` checks the emitted bytes. Neither command turns missing native evidence into runtime proof. + +## What is not a capability claim + +- A successful **build** proves compilation and artifact assembly, not native execution. +- A successful **route-unit** test proves the route contract at that harness level, not installation. +- A successful **fake-host** or protocol test proves the simulated contract, not authenticated host behavior. +- An **npm install** installs package files; it does not register the plugin into an agent host. +- A browser **MCP App** is not the same JSX surface as an Agent Document. Browser Apps use browser code and `agent-bundle/app`; agent-facing JSX renders `Agent.*` nodes through the server runtime. + +Use the proof level that matches the claim, and keep stronger native acceptance separately labelled. \ No newline at end of file From 43ec7b7c708a9740a4146f7240ce78e4e545ba61 Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:23:35 -0700 Subject: [PATCH 05/12] docs: add target and capability map zh --- website/docs/zh/reference/capabilities.mdx | 82 ++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 website/docs/zh/reference/capabilities.mdx diff --git a/website/docs/zh/reference/capabilities.mdx b/website/docs/zh/reference/capabilities.mdx new file mode 100644 index 000000000..41769c9ab --- /dev/null +++ b/website/docs/zh/reference/capabilities.mdx @@ -0,0 +1,82 @@ +--- +description: '全部内置输出 target 的实用能力地图：哪些框架表面因宿主而异，以及如何解读 supported、degraded、unavailable、prohibited 与 unverified 证据。' +--- + +# Target 与能力 + +Agent Bundle 有 **五个内置输出 target**。target 是编译器投影，不等于宿主会话、包格式，也不表示每项能力在每个宿主上都完全相同： + +| Target | 主要生成形式 | 安装模型 | 重要边界 | +| --- | --- | --- | --- | +| `amp` | `.amp/plugins//index.js` 目录插件 | 框架把生成的 Amp 目录复制到项目或用户插件根；reload 仍是交互式操作。 | Amp MCP 是 Skill 作用域。固定契约没有为可搬迁本地入口提供插件根 token/cwd，因此编译器生成的本地 MCP 入口会被拒绝。 | +| `claude` | `.claude-plugin/plugin.json`、`hooks/hooks.json`、`.mcp.json` | Claude Code marketplace + plugin CLI。 | Claude 原生钩子、命令、output styles、LSP/settings 等扩展需要专用 target。 | +| `codex` | `.codex-plugin/plugin.json` 及相邻 hooks/MCP 文档 | Codex marketplace + plugin CLI。 | Codex 原生元数据、钩子契约、Apps 兼容与 marketplace policy 都留在 Codex 投影中。 | +| `cursor` | `.cursor-plugin/plugin.json` 及相邻 hooks/MCP 文档 | 收据归属的本地复制，或文档化的本地 marketplace 流程。 | Cursor 也能读取 portable Agent Plugins 包；原生 target 才会输出 Cursor 专属清单、钩子、MCP 文档、规则与元数据。 | +| `portable` | 根级 `plugin.json` + `mcp.json`，遵循 Agent Plugins 1.0.0 | 选中时可带生成的独立安装器；其他 Agent Plugins 客户端按各自支持程度消费该根目录。 | 标准并不试图把所有原生宿主能力都变成 portable。Skills 与 MCP 是核心 portable 表面；原生 hooks/rules/commands 需要真正支持它们的 target。 | + +省略 `targets` 时只选择 `portable`。`plugin` **不是** target。target 顺序不会改变输出。[Target 与产物](./targets-artifacts.mdx)记录组合根目录的字节与布局契约。 + +## 能力地图 + +下面这张表回答作者最常见的问题：“我写了这种东西，支持能力从哪里来？”它不会复制几百行带版本的宿主数据。构建时生成的[宿主能力矩阵](./hosts.md)、[事件与钩子矩阵](./events.md)与[通知投递矩阵](./notices.md)才是精确、带证据的事实来源。 + +| 编写表面 | 框架负责什么 | 因宿主而异的部分 | 精确事实来源 | +| --- | --- | --- | --- | +| Skills 与 Skill 资源 | 发现、校验、复制/渲染、保留资源，并组合进所选投影。 | Skill 元数据/特性、发现、注册、插值、Skill 作用域 MCP。 | [宿主](./hosts.md) + [Skills](../guide/authoring/skills.mdx)。 | +| MCP tools/resources/prompts | 把约定路由编译成一个生成式服务器，校验 schema/result，拥有 stdio 生命周期与清单 executable 记录。 | target 如何启动/注册服务器、传输、路径 token、Tasks 与 structured-result 行为。 | [宿主](./hosts.md) + [MCP servers 与 Apps](../guide/authoring/mcp.mdx)。 | +| MCP Apps | 编译浏览器 App，把它绑定到声明的 server/resource/tool，生成带类型 App 契约并暴露声明的 web launch。 | 原生 App/resource 支持与宿主展示行为。 | [宿主](./hosts.md)、[MCP servers 与 Apps](../guide/authoring/mcp.mdx)、[MCP App 示例](../examples/mcp-app.mdx)。 | +| 规范事件路由与 hooks | 规范化事件、编译 wrapper、运行 preflight/handler，并记录精确 executable 归属。 | 原生事件是否存在、payload 字段、matcher、阻断/改写语义、可返回通道。 | [事件](./events.md) + [Hooks](../guide/authoring/hooks.mdx)。 | +| Commands 与 rules | 解析/校验文档，并只把它们放入兼容的所选投影。 | 哪些宿主会发现组件、哪些 frontmatter/特性可以保留。 | [宿主](./hosts.md) + [项目结构](../guide/start/project-structure.mdx)。 | +| 路由式 CLI 与 CLI projection | 构建一张命令图和一个 bin，用规范路由 schema 校验 argv；同一操作通过 `.cli.ts` 复用 tool。 | 所选 target 是否允许路由式 CLI 存在于插件根。复杂 schema 可能需要规范 JSON 输入或真正独立的 workflow。 | [宿主](./hosts.md)、[Package entries](../guide/authoring/package-entries.mdx)、[CLI](./cli.mdx)。 | +| Scripts 与 assets | 编译/复制一次，以清单归属和 provenance 放入组合产物。 | 只有当组件同时投影成原生宿主表面时，宿主发现规则才相关。 | [Scripts 与 assets](../guide/authoring/scripts-assets.mdx) + [Target 与产物](./targets-artifacts.mdx)。 | +| Layouts、providers、state、request lineage、terminal context | 为框架执行的路由提供共享应用行为与请求作用域上下文。 | 这些是框架执行能力，不是原生清单组件；它们存在于通过生成运行时执行的表面。 | [项目结构](../guide/start/project-structure.mdx) + [运行时环境](./runtime-environment.mdx)。 | +| Notices | 规范化通知投递，并求出所选宿主可以广告/投递能力的交集。 | 通道可用性与投递语义。 | [Notices](./notices.md)。 | +| 原生宿主扩展 | 把宿主专属配置留在对应 adapter 内，并按固定证据校验。 | 全部；扩展只属于拥有它的宿主。 | [配置](./configuration.mdx) + [宿主](./hosts.md)。 | +| Prebuilt payload | 打包不透明字节与声明的 runtime dependencies，不假装编译器分析过其内部。 | 哪些所选宿主收到 payload，以及外部运行时要求是否存在。 | [配置](./configuration.mdx)、[Target 与产物](./targets-artifacts.mdx)、[校验](../guide/distribution/validation.mdx)。 | + +### 一个实用规则 + +如果两个表面是**同一个操作**，只编写一次操作再做 projection。一个 tool 加一条惯用 CLI 命令，通常应是一个 MCP tool route 加同目录 `.cli.ts` projection。如果它们真的是不同 workflow，就保留不同路由。不要为了另一个表面再建第二套应用 registry。 + +## 如何解读能力状态 + +adapter 契约只有四种状态： + +| 状态 | 含义 | +| --- | --- | +| `supported` | 固定的宿主证据支持该能力，并记录观测到的宿主/adapter 版本。 | +| `degraded` | 有用的子集可用，同时记录明确限制。不能把它展示成完整支持。 | +| `unavailable` | 固定宿主契约没有提供该能力。 | +| `prohibited` | 宿主契约或框架策略明确禁止该能力。 | + +宿主证据或验收记录中还可能出现独立的 **unverified** 描述。它不等于“不支持”。它表示静态/type/fake-host 契约可能已经实现，但当前环境没有证明真实认证后的执行。Amp 的 live activation 就是当前例子：安装与生成契约行为有测试，而需要账户的 live execution 仍是 unverified。 + +不要把 `degraded` 或 `unverified` 变成绿色“supported”，也不要把 `unverified` 写成 `unavailable`。 + +## 内置 target 与记录到的客户端不是一回事 + +上面的五个名字才是内置编译 target。[宿主](./hosts.md)参考还记录了能够消费部分 portable 组件的客户端。这些行是**兼容性证据**，不是额外的输出 target。 + +例如，一个客户端可能读取 Skills 却不读取 hooks；也可能识别 MCP 文档，却没有证明 Agent Bundle 路径占位符能够成功启动。标准契约足够时选择 `portable`；只有当 Agent Bundle 对所需宿主专属行为拥有真正 adapter 时，才添加原生 target。 + +因此“记录到的客户端”“portable reader”“原生编译 target”“可安装原生插件”“已认证 runtime proof”是五种不同的声明，不能用一个支持数量替代。 + +## 按需求选择 target，而不是按流行度 + +1. 如果 Agent Plugins 的 Skills/MCP 已足够，从 `portable` 开始。 +2. 当插件需要某宿主的 hooks、rules、commands、原生元数据、安装语义或 portable 无法表达的其他能力时，再添加原生 target。 +3. 依赖某个原生事件或字段前，先看生成能力矩阵中固定的宿主版本。 +4. 当事件路由只应存在于同时支持若干能力的宿主时，用 `config.requires`。 +5. 只有组合规则要求（`AB4103`、`AB4105`、`AB4106`）或产品本来就要发布不同插件时，才拆分构建。 + +`agent-bundle inspect --root .` 会展示规范化选择与规划出的投影。`validate` 校验源码声明；`validate --artifact` 校验已输出字节。两者都不会把缺失的原生证据变成 runtime proof。 + +## 哪些东西不构成能力证明 + +- **build** 成功证明编译与产物组装，不证明原生执行。 +- **route-unit** 成功证明该 harness 级别的路由契约，不证明安装。 +- **fake-host** 或协议测试证明模拟契约，不证明认证后的宿主行为。 +- **npm install** 安装包文件，不会把插件注册进 agent host。 +- 浏览器 **MCP App** 与 Agent Document JSX 不是同一种 JSX 表面。浏览器 App 使用浏览器代码与 `agent-bundle/app`；agent-facing JSX 通过 server runtime 渲染 `Agent.*` 节点。 + +声明什么，就使用匹配该声明的 proof level；更强的原生验收必须单独标注。 \ No newline at end of file From bb536d4c0a1a84aaeb5b70ab7b16937c727c2c23 Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:23:48 -0700 Subject: [PATCH 06/12] docs: surface capability map in reference nav --- website/docs/en/reference/_meta.json | 1 + 1 file changed, 1 insertion(+) diff --git a/website/docs/en/reference/_meta.json b/website/docs/en/reference/_meta.json index fbea230e6..98def9978 100644 --- a/website/docs/en/reference/_meta.json +++ b/website/docs/en/reference/_meta.json @@ -3,6 +3,7 @@ "cli", "configuration", "targets-artifacts", + "capabilities", "artifact-manifest", "hosts", "events", From 52b5aef3a74c3385ccfaa93a1f0028f58272d094 Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:23:58 -0700 Subject: [PATCH 07/12] docs: surface capability map in reference nav zh --- website/docs/zh/reference/_meta.json | 1 + 1 file changed, 1 insertion(+) diff --git a/website/docs/zh/reference/_meta.json b/website/docs/zh/reference/_meta.json index fbea230e6..98def9978 100644 --- a/website/docs/zh/reference/_meta.json +++ b/website/docs/zh/reference/_meta.json @@ -3,6 +3,7 @@ "cli", "configuration", "targets-artifacts", + "capabilities", "artifact-manifest", "hosts", "events", From 6cacdb185ca0ce153d9f627afde469e8249797b3 Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:24:50 -0700 Subject: [PATCH 08/12] docs: avoid duplicate capability reference --- website/docs/en/reference/capabilities.mdx | 82 ---------------------- 1 file changed, 82 deletions(-) delete mode 100644 website/docs/en/reference/capabilities.mdx diff --git a/website/docs/en/reference/capabilities.mdx b/website/docs/en/reference/capabilities.mdx deleted file mode 100644 index ec2e2f50d..000000000 --- a/website/docs/en/reference/capabilities.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -description: 'A practical capability map for every built-in output target, the framework surfaces that vary by host, and how to read supported, degraded, unavailable, prohibited, and unverified evidence.' ---- - -# Targets and capabilities - -Agent Bundle has **five built-in output targets**. A target is a compiler projection, not a host session, package format, or proof that every feature works identically everywhere: - -| Target | Primary generated form | Installation model | Important boundary | -| --- | --- | --- | --- | -| `amp` | `.amp/plugins//index.js` directory plugin | Framework copies the generated Amp directory to the project or user plugin root; reload remains interactive. | Amp MCP is skill-scoped. Generated local MCP entries are rejected because the pinned contract exposes no plugin-root token/cwd for a relocatable entry. | -| `claude` | `.claude-plugin/plugin.json`, `hooks/hooks.json`, `.mcp.json` | Claude Code marketplace + plugin CLI. | Use the dedicated target for Claude-native hooks, commands, output styles, LSP/settings, and other Claude extensions. | -| `codex` | `.codex-plugin/plugin.json` with adjacent hooks/MCP documents | Codex marketplace + plugin CLI. | Codex-native metadata, hook contracts, Apps compatibility, and marketplace policy stay in the Codex projection. | -| `cursor` | `.cursor-plugin/plugin.json` with adjacent hooks/MCP documents | Receipt-owned local copy, or the documented local-marketplace flow. | Cursor can also read a portable Agent Plugins pack, but the native target is what emits Cursor-specific manifests, hooks, MCP documents, rules, and metadata. | -| `portable` | root `plugin.json` + `mcp.json` using Agent Plugins 1.0.0 | The generated standalone installer is available when selected; other Agent Plugins clients may consume the built root according to their own support. | The standard intentionally does not make every native host feature portable. Skills and MCP are the core portable surfaces; native hooks/rules/commands require a target that actually supports them. | - -Omit `targets` and only `portable` is selected. `plugin` is **not** a target. Target order does not change output. The [Targets and artifacts](./targets-artifacts.mdx) page is the byte/layout contract for the composite root. - -## Capability map - -The table below answers the author question: “I wrote this kind of thing; where does support come from?” It deliberately does not copy hundreds of versioned host rows. The generated [Host capability matrix](./hosts.md), [Event and hook matrix](./events.md), and [Notice delivery matrix](./notices.md) are the exact evidence-backed sources. - -| Authoring surface | Framework responsibility | Host-dependent part | Exact source of truth | -| --- | --- | --- | --- | -| Skills and Skill resources | Discover, validate, copy/render, preserve resources, compose the selected projections. | Skill metadata/features, discovery, registration, interpolation, skill-scoped MCP. | [Hosts](./hosts.md) plus [Skills](../guide/authoring/skills.mdx). | -| MCP tools, resources, prompts | Compile conventional routes into one generated server, validate schemas/results, own stdio lifecycle and manifest executable records. | Whether/how the target can launch or register the server, transports, path tokens, tasks and structured-result behavior. | [Hosts](./hosts.md) plus [MCP servers and Apps](../guide/authoring/mcp.mdx). | -| MCP Apps | Compile the browser App, bind it to a declared server/resource/tool, generate typed App contracts, expose declared web launches. | Native App/resource support and host presentation behavior. | [Hosts](./hosts.md), [MCP servers and Apps](../guide/authoring/mcp.mdx), and the [MCP App example](../examples/mcp-app.mdx). | -| Canonical event routes and hooks | Normalize canonical events, compile wrappers, run preflight/handler logic, record exact executable ownership. | Native event availability, payload fields, matchers, blocking/rewriting semantics, supported result channels. | [Events](./events.md) and [Hooks](../guide/authoring/hooks.mdx). | -| Commands and rules | Parse/validate authored documents and place them into compatible selected projections. | Which hosts discover the component and which frontmatter/features survive. | [Hosts](./hosts.md) and [Project structure](../guide/start/project-structure.mdx). | -| Routed CLI and CLI projections | Build one command graph/bin, validate argv against the canonical route schema, reuse a tool through `.cli.ts` when it is the same operation. | Whether the selected target admits the routed CLI in its plugin root. Rich schemas may require canonical JSON input or a genuinely separate workflow. | [Hosts](./hosts.md), [Package entries](../guide/authoring/package-entries.mdx), and [CLI](./cli.mdx). | -| Scripts and assets | Compile/copy once into the composite artifact with manifest ownership and provenance. | Host discovery only matters when a component is also projected into a native host surface. | [Scripts and assets](../guide/authoring/scripts-assets.mdx) and [Targets and artifacts](./targets-artifacts.mdx). | -| Layouts, providers, state, request lineage and terminal context | Wrap framework-executed routes with shared application behavior and request-scoped context. | These are framework execution capabilities, not native manifest components; they exist where the operation executes through the generated runtime. | [Project structure](../guide/start/project-structure.mdx) and [Runtime environment](./runtime-environment.mdx). | -| Notices | Normalize notice delivery and intersect what selected hosts can advertise/deliver. | Channel availability and delivery semantics. | [Notices](./notices.md). | -| Native host extensions | Keep host-specific configuration inside its adapter and validate it against pinned evidence. | Everything: the extension exists only for the host that owns it. | [Configuration](./configuration.mdx) and [Hosts](./hosts.md). | -| Prebuilt payloads | Package opaque bytes and declared runtime dependencies without pretending the compiler analyzed their internals. | Which selected hosts receive the payload and whether the external runtime requirements are present. | [Configuration](./configuration.mdx), [Targets and artifacts](./targets-artifacts.mdx), and [Validation](../guide/distribution/validation.mdx). | - -### A useful rule - -If two surfaces are **the same operation**, author the operation once and project it. A tool plus an idiomatic CLI command normally means one MCP tool route plus a colocated `.cli.ts` projection. If they are different workflows, keep separate routes. Do not build a second application registry just to feed another surface. - -## How to read capability states - -The adapter contract has four states: - -| State | Meaning | -| --- | --- | -| `supported` | The pinned host evidence supports the capability and records the observed host/adapter version. | -| `degraded` | A useful subset is available, with a recorded limitation. Do not present it as full support. | -| `unavailable` | The pinned host contract does not provide the capability. | -| `prohibited` | The host contract or framework policy explicitly forbids the capability. | - -A separate **unverified** statement can appear in host evidence or acceptance notes. That does not mean “unsupported.” It means the static/type/fake-host contract may be implemented while live authenticated execution has not been demonstrated in the available environment. Amp live activation is a current example: installation and generated contract behavior are tested, while account-dependent live execution remains unverified. - -Do not turn `degraded` or `unverified` into a green “supported” badge, and do not turn `unverified` into “unavailable.” - -## Built-in targets versus recorded clients - -The five names above are the built-in compiler targets. The [Hosts](./hosts.md) reference also records clients that can consume some portable components. Those rows are **compatibility evidence**, not additional output targets. - -For example, a client may read Skills but not hooks, or recognize an MCP document while lacking proof that Agent Bundle path placeholders launch correctly. Select `portable` when the standard is the intended contract; add a native target only when Agent Bundle has a real adapter for the host-specific behavior you need. - -This distinction prevents a misleading support count: “recorded client,” “portable reader,” “native compiler target,” “installable native plugin,” and “authenticated runtime proof” are different claims. - -## Choose targets from requirements, not popularity - -1. Start with `portable` when Skills/MCP through the open format are enough. -2. Add a native target when the plugin needs that host's hooks, rules, commands, native metadata, installation semantics, or another capability the portable format cannot express. -3. Check the generated capability matrices for the exact host version before relying on a native event or field. -4. Use `config.requires` on event routes when the route should exist only where every named capability is supported. -5. Split builds only when the composite rules require it (`AB4103`, `AB4105`, `AB4106`) or when the product intentionally ships different plugins. - -`agent-bundle inspect --root .` shows the normalized selection and planned projections. `validate` checks source declarations; `validate --artifact` checks the emitted bytes. Neither command turns missing native evidence into runtime proof. - -## What is not a capability claim - -- A successful **build** proves compilation and artifact assembly, not native execution. -- A successful **route-unit** test proves the route contract at that harness level, not installation. -- A successful **fake-host** or protocol test proves the simulated contract, not authenticated host behavior. -- An **npm install** installs package files; it does not register the plugin into an agent host. -- A browser **MCP App** is not the same JSX surface as an Agent Document. Browser Apps use browser code and `agent-bundle/app`; agent-facing JSX renders `Agent.*` nodes through the server runtime. - -Use the proof level that matches the claim, and keep stronger native acceptance separately labelled. \ No newline at end of file From f833e914bb4f385578ae7b98c7789be6d078a953 Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:24:58 -0700 Subject: [PATCH 09/12] docs: avoid duplicate capability reference zh --- website/docs/zh/reference/capabilities.mdx | 82 ---------------------- 1 file changed, 82 deletions(-) delete mode 100644 website/docs/zh/reference/capabilities.mdx diff --git a/website/docs/zh/reference/capabilities.mdx b/website/docs/zh/reference/capabilities.mdx deleted file mode 100644 index 41769c9ab..000000000 --- a/website/docs/zh/reference/capabilities.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -description: '全部内置输出 target 的实用能力地图：哪些框架表面因宿主而异，以及如何解读 supported、degraded、unavailable、prohibited 与 unverified 证据。' ---- - -# Target 与能力 - -Agent Bundle 有 **五个内置输出 target**。target 是编译器投影，不等于宿主会话、包格式，也不表示每项能力在每个宿主上都完全相同： - -| Target | 主要生成形式 | 安装模型 | 重要边界 | -| --- | --- | --- | --- | -| `amp` | `.amp/plugins//index.js` 目录插件 | 框架把生成的 Amp 目录复制到项目或用户插件根；reload 仍是交互式操作。 | Amp MCP 是 Skill 作用域。固定契约没有为可搬迁本地入口提供插件根 token/cwd，因此编译器生成的本地 MCP 入口会被拒绝。 | -| `claude` | `.claude-plugin/plugin.json`、`hooks/hooks.json`、`.mcp.json` | Claude Code marketplace + plugin CLI。 | Claude 原生钩子、命令、output styles、LSP/settings 等扩展需要专用 target。 | -| `codex` | `.codex-plugin/plugin.json` 及相邻 hooks/MCP 文档 | Codex marketplace + plugin CLI。 | Codex 原生元数据、钩子契约、Apps 兼容与 marketplace policy 都留在 Codex 投影中。 | -| `cursor` | `.cursor-plugin/plugin.json` 及相邻 hooks/MCP 文档 | 收据归属的本地复制，或文档化的本地 marketplace 流程。 | Cursor 也能读取 portable Agent Plugins 包；原生 target 才会输出 Cursor 专属清单、钩子、MCP 文档、规则与元数据。 | -| `portable` | 根级 `plugin.json` + `mcp.json`，遵循 Agent Plugins 1.0.0 | 选中时可带生成的独立安装器；其他 Agent Plugins 客户端按各自支持程度消费该根目录。 | 标准并不试图把所有原生宿主能力都变成 portable。Skills 与 MCP 是核心 portable 表面；原生 hooks/rules/commands 需要真正支持它们的 target。 | - -省略 `targets` 时只选择 `portable`。`plugin` **不是** target。target 顺序不会改变输出。[Target 与产物](./targets-artifacts.mdx)记录组合根目录的字节与布局契约。 - -## 能力地图 - -下面这张表回答作者最常见的问题：“我写了这种东西，支持能力从哪里来？”它不会复制几百行带版本的宿主数据。构建时生成的[宿主能力矩阵](./hosts.md)、[事件与钩子矩阵](./events.md)与[通知投递矩阵](./notices.md)才是精确、带证据的事实来源。 - -| 编写表面 | 框架负责什么 | 因宿主而异的部分 | 精确事实来源 | -| --- | --- | --- | --- | -| Skills 与 Skill 资源 | 发现、校验、复制/渲染、保留资源，并组合进所选投影。 | Skill 元数据/特性、发现、注册、插值、Skill 作用域 MCP。 | [宿主](./hosts.md) + [Skills](../guide/authoring/skills.mdx)。 | -| MCP tools/resources/prompts | 把约定路由编译成一个生成式服务器，校验 schema/result，拥有 stdio 生命周期与清单 executable 记录。 | target 如何启动/注册服务器、传输、路径 token、Tasks 与 structured-result 行为。 | [宿主](./hosts.md) + [MCP servers 与 Apps](../guide/authoring/mcp.mdx)。 | -| MCP Apps | 编译浏览器 App，把它绑定到声明的 server/resource/tool，生成带类型 App 契约并暴露声明的 web launch。 | 原生 App/resource 支持与宿主展示行为。 | [宿主](./hosts.md)、[MCP servers 与 Apps](../guide/authoring/mcp.mdx)、[MCP App 示例](../examples/mcp-app.mdx)。 | -| 规范事件路由与 hooks | 规范化事件、编译 wrapper、运行 preflight/handler，并记录精确 executable 归属。 | 原生事件是否存在、payload 字段、matcher、阻断/改写语义、可返回通道。 | [事件](./events.md) + [Hooks](../guide/authoring/hooks.mdx)。 | -| Commands 与 rules | 解析/校验文档，并只把它们放入兼容的所选投影。 | 哪些宿主会发现组件、哪些 frontmatter/特性可以保留。 | [宿主](./hosts.md) + [项目结构](../guide/start/project-structure.mdx)。 | -| 路由式 CLI 与 CLI projection | 构建一张命令图和一个 bin，用规范路由 schema 校验 argv；同一操作通过 `.cli.ts` 复用 tool。 | 所选 target 是否允许路由式 CLI 存在于插件根。复杂 schema 可能需要规范 JSON 输入或真正独立的 workflow。 | [宿主](./hosts.md)、[Package entries](../guide/authoring/package-entries.mdx)、[CLI](./cli.mdx)。 | -| Scripts 与 assets | 编译/复制一次，以清单归属和 provenance 放入组合产物。 | 只有当组件同时投影成原生宿主表面时，宿主发现规则才相关。 | [Scripts 与 assets](../guide/authoring/scripts-assets.mdx) + [Target 与产物](./targets-artifacts.mdx)。 | -| Layouts、providers、state、request lineage、terminal context | 为框架执行的路由提供共享应用行为与请求作用域上下文。 | 这些是框架执行能力，不是原生清单组件；它们存在于通过生成运行时执行的表面。 | [项目结构](../guide/start/project-structure.mdx) + [运行时环境](./runtime-environment.mdx)。 | -| Notices | 规范化通知投递，并求出所选宿主可以广告/投递能力的交集。 | 通道可用性与投递语义。 | [Notices](./notices.md)。 | -| 原生宿主扩展 | 把宿主专属配置留在对应 adapter 内，并按固定证据校验。 | 全部；扩展只属于拥有它的宿主。 | [配置](./configuration.mdx) + [宿主](./hosts.md)。 | -| Prebuilt payload | 打包不透明字节与声明的 runtime dependencies，不假装编译器分析过其内部。 | 哪些所选宿主收到 payload，以及外部运行时要求是否存在。 | [配置](./configuration.mdx)、[Target 与产物](./targets-artifacts.mdx)、[校验](../guide/distribution/validation.mdx)。 | - -### 一个实用规则 - -如果两个表面是**同一个操作**，只编写一次操作再做 projection。一个 tool 加一条惯用 CLI 命令，通常应是一个 MCP tool route 加同目录 `.cli.ts` projection。如果它们真的是不同 workflow，就保留不同路由。不要为了另一个表面再建第二套应用 registry。 - -## 如何解读能力状态 - -adapter 契约只有四种状态： - -| 状态 | 含义 | -| --- | --- | -| `supported` | 固定的宿主证据支持该能力，并记录观测到的宿主/adapter 版本。 | -| `degraded` | 有用的子集可用，同时记录明确限制。不能把它展示成完整支持。 | -| `unavailable` | 固定宿主契约没有提供该能力。 | -| `prohibited` | 宿主契约或框架策略明确禁止该能力。 | - -宿主证据或验收记录中还可能出现独立的 **unverified** 描述。它不等于“不支持”。它表示静态/type/fake-host 契约可能已经实现，但当前环境没有证明真实认证后的执行。Amp 的 live activation 就是当前例子：安装与生成契约行为有测试，而需要账户的 live execution 仍是 unverified。 - -不要把 `degraded` 或 `unverified` 变成绿色“supported”，也不要把 `unverified` 写成 `unavailable`。 - -## 内置 target 与记录到的客户端不是一回事 - -上面的五个名字才是内置编译 target。[宿主](./hosts.md)参考还记录了能够消费部分 portable 组件的客户端。这些行是**兼容性证据**，不是额外的输出 target。 - -例如，一个客户端可能读取 Skills 却不读取 hooks；也可能识别 MCP 文档，却没有证明 Agent Bundle 路径占位符能够成功启动。标准契约足够时选择 `portable`；只有当 Agent Bundle 对所需宿主专属行为拥有真正 adapter 时，才添加原生 target。 - -因此“记录到的客户端”“portable reader”“原生编译 target”“可安装原生插件”“已认证 runtime proof”是五种不同的声明，不能用一个支持数量替代。 - -## 按需求选择 target，而不是按流行度 - -1. 如果 Agent Plugins 的 Skills/MCP 已足够，从 `portable` 开始。 -2. 当插件需要某宿主的 hooks、rules、commands、原生元数据、安装语义或 portable 无法表达的其他能力时，再添加原生 target。 -3. 依赖某个原生事件或字段前，先看生成能力矩阵中固定的宿主版本。 -4. 当事件路由只应存在于同时支持若干能力的宿主时，用 `config.requires`。 -5. 只有组合规则要求（`AB4103`、`AB4105`、`AB4106`）或产品本来就要发布不同插件时，才拆分构建。 - -`agent-bundle inspect --root .` 会展示规范化选择与规划出的投影。`validate` 校验源码声明；`validate --artifact` 校验已输出字节。两者都不会把缺失的原生证据变成 runtime proof。 - -## 哪些东西不构成能力证明 - -- **build** 成功证明编译与产物组装，不证明原生执行。 -- **route-unit** 成功证明该 harness 级别的路由契约，不证明安装。 -- **fake-host** 或协议测试证明模拟契约，不证明认证后的宿主行为。 -- **npm install** 安装包文件，不会把插件注册进 agent host。 -- 浏览器 **MCP App** 与 Agent Document JSX 不是同一种 JSX 表面。浏览器 App 使用浏览器代码与 `agent-bundle/app`；agent-facing JSX 通过 server runtime 渲染 `Agent.*` 节点。 - -声明什么，就使用匹配该声明的 proof level；更强的原生验收必须单独标注。 \ No newline at end of file From 23d6bdc343722cabe32559d06e421c15732a9add Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:25:09 -0700 Subject: [PATCH 10/12] docs: keep capability guide in start section --- website/docs/en/reference/_meta.json | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/en/reference/_meta.json b/website/docs/en/reference/_meta.json index 98def9978..fbea230e6 100644 --- a/website/docs/en/reference/_meta.json +++ b/website/docs/en/reference/_meta.json @@ -3,7 +3,6 @@ "cli", "configuration", "targets-artifacts", - "capabilities", "artifact-manifest", "hosts", "events", From 72411bf9907d2b77c66d547ed030a505d169220a Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:25:17 -0700 Subject: [PATCH 11/12] docs: keep capability guide in start section zh --- website/docs/zh/reference/_meta.json | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/zh/reference/_meta.json b/website/docs/zh/reference/_meta.json index 98def9978..fbea230e6 100644 --- a/website/docs/zh/reference/_meta.json +++ b/website/docs/zh/reference/_meta.json @@ -3,7 +3,6 @@ "cli", "configuration", "targets-artifacts", - "capabilities", "artifact-manifest", "hosts", "events", From 867d3787fbdc97525a99beef0e1b773eea66c40e Mon Sep 17 00:00:00 2001 From: ScriptedAlchemy Date: Mon, 7 Sep 2026 23:40:01 +0000 Subject: [PATCH 12/12] docs: correct Amp starter retargeting and starter privacy claims --- website/docs/en/guide/authoring/reuse-framework.mdx | 11 +++++------ website/docs/en/guide/distribution/index.mdx | 7 ++++--- website/docs/en/guide/start/capabilities.mdx | 5 +++-- website/docs/en/guide/start/quick-start.mdx | 9 ++++++--- website/docs/zh/guide/authoring/reuse-framework.mdx | 9 ++++----- website/docs/zh/guide/distribution/index.mdx | 5 +++-- website/docs/zh/guide/start/capabilities.mdx | 3 ++- website/docs/zh/guide/start/quick-start.mdx | 9 ++++++--- 8 files changed, 33 insertions(+), 25 deletions(-) diff --git a/website/docs/en/guide/authoring/reuse-framework.mdx b/website/docs/en/guide/authoring/reuse-framework.mdx index ae547f3da..45a574f70 100644 --- a/website/docs/en/guide/authoring/reuse-framework.mdx +++ b/website/docs/en/guide/authoring/reuse-framework.mdx @@ -18,8 +18,7 @@ ordinary imported module when that makes the code easier to read. A registration route-file script, custom `McpServer`, or string-keyed dispatcher is not required. ```tsx -// src/mcp/tools/tools/hello.tsx -import React from 'react'; +// src/mcp/greeter/tools/hello.tsx import { Agent } from '@agent-bundle/runtime'; import type { ToolConfig, ToolRouteProps } from 'agent-bundle'; import { z } from 'zod'; @@ -41,8 +40,8 @@ export default async function Hello({ input }: ToolRouteProps