参与贡献

这一页是给改动 agent-bundle 本身的人看的。其中没有任何一项是编写插件的前提，插件作者只需要 agent-bundle 与 Node.js，本页内容一概不需要。

仓库是一个 pnpm 工作区。这里以 Node.js 22.19 为下限，原因和框架本身以它为下限是同一个。

从全新检出开始：

pnpm install
pnpm build

pnpm build 会构建其余脚本与每个示例都依赖的工作区包，因此全新安装之后先跑它。

三道门禁

命令	证明什么	何时运行
`pnpm check`	本地交付门禁：构建、单元、路由单元、投影与集成测试、lint、类型检查。	开发过程中，以及每次推送之前。
`pnpm check:release`	与 `pnpm check` 并列的打包证据：`npm pack` dry run、发布审计，以及含脚手架模板矩阵的打包测试池。	改动打包、导出或已发布表面之前。
`pnpm check:local-ci`	完整的托管 CI 门禁，三个 Node 版本的 verify 矩阵，加上示例、发布与微 eval 作业，在并行的本地 worktree 中运行。	作为合并门禁。

还有一些范围更小的脚本用于迭代：pnpm test:unit、pnpm test:route-unit、 pnpm test:projection、pnpm test:integration、pnpm lint 与 pnpm typecheck。它们是更快的信号，不是门禁。

本地合并循环

pnpm check:local-ci 存在的原因是托管 verify 腿很慢，而且在这个仓库里，本地绿灯才是分支合并的依据。它把每条腿放进一个隔离的 git worktree，钉在分支的 HEAD 提交上，各自拥有自己的 node_modules 与自己的临时目录根：

在分支的 HEAD 提交上运行 pnpm check:local-ci，未提交的改动不在覆盖范围内，运行器发现它们时会给出警告。
如果门禁是绿的，这个分支就可以合并。
托管 CI 仍会在合并后的提交上运行，并继续充当异步的合并后安全网。如果它与本地运行结论不一致，以托管结果为准，并为这次合并补一个后续修复。

想快速迭代，pnpm check:local-ci --current-node-only 会在当前激活的 Node 上运行一条等价于 verify 的腿。它跳过 Node 矩阵以及示例、发布与微 eval 门禁，因此是快速信号，而不是合并门禁。当怀疑复用的腿 worktree 已经陈旧时，用 --fresh 重建它们。

运行器按顺序从显式的 AGENT_BUNDLE_LOCAL_CI_NODE_22 / _24 / _26 覆盖项、mise、~/.nvm、当前进程中解析每条托管 Node 线（22.19.x、24.x、26.x），并在使用前对每个二进制做版本校验。缺少某条线时它会带上确切的安装命令失败，而不是悄悄用错运行时。腿的 worktree、逐步骤日志，以及“腿 × 步骤 × 状态 × 时长 × 测试普查”的汇总表都位于被 git 忽略的 .worktrees/local-ci/ 目录下。

docs/local-ci.md 是完整契约，包括本地门禁刻意不覆盖的那些内容。

Changesets

版本管理走 Changesets。对用户可见的改动，请在同一个提交里补上一条：

pnpm changeset

选择受影响的包与版本级别，并从读者的角度描述这次改动，changeset 是发布说明的文案，不是提交信息。 pnpm version-packages 应用待处理的 changeset；合并 Version Packages 后，会先解析 pkg.pr.new 预览，再运行 pnpm check:release。私有工作区包，包括示例与本站点，不参与版本管理。

包分发通道是 pkg.pr.new 预览 tarball，见预览包。每次 Release packages 运行都会在工作流摘要中写出明确结果：version-maintenance-only （刷新了 Version Packages PR）、preview-release（merge commit 通过发布门禁，且全部四个按 commit 固定的 pkg.pr.new URL 都可解析）或 failed。

原生宿主 smoke 需要显式开启

有些证据需要机器上已登录的 Claude 或 Codex CLI，因此它不可能成为门禁。这些 smoke 在本地需要显式开启，在 CI 中被刻意跳过；运行它们的托管工作流只能通过 workflow_dispatch 触发，并且要指明它演练哪个宿主。

pnpm test:packed:native:claude
pnpm test:packed:native:codex
pnpm test:host-install:session:claude

测试矩阵中的其余部分都不需要凭据。host-install 保留一条无条件的确定性适配器模拟通道，可用的宿主二进制还会额外证明它们各自的公开安装路径，而 Cursor 会显式记录它那条不可用的非交互宿主会话表面，而不是报告一个它没有挣到的通过。这条边界正是测试中证明级别的全部意义所在：一个级别绝不会被当作更强级别的收据来报告。

依赖审查、包预览与 Release packages 工作流出于结构性原因只在托管侧运行，第一项要针对 pull request 的 diff 查询 GitHub 的安全公告数据库，另外两项会发布到 pkg.pr.new；Release packages 还会验证远程 commit URL。

开发 Workbench 界面

packages/workbench 中的 Workbench 界面有自己的热更新循环：一个放行 Rsbuild 开发服务器 origin 的前台服务器，加上把 /api 代理到它的 Rsbuild 开发服务器。终端 A 请在某个插件项目根目录下运行，例如 examples/* 之一。

# 终端 A
npx agent-bundle dev --root . --port 3100 --no-open \
  --workbench-dev-origin http://localhost:3000
# 终端 B
AGENT_BUNDLE_WORKBENCH_API_PROXY=http://127.0.0.1:3100 \
  pnpm --filter agent-bundle-workbench dev

打开 http://localhost:3000。端口、代理范围，以及为什么必须带这个标志，见贡献者 UI 的 HMR。

文档站点

本站点是一个私有工作区包。请在仓库根目录运行：

pnpm docs:site:dev       # 带热更新的本地开发服务器
pnpm docs:site:build     # 类型检查、构建，并核实构建产物
pnpm docs:site:preview   # 提供已构建的站点

pnpm docs:site:build 就是门禁，Docs 工作流会在每个 pull request 上运行它，并把 main 部署到 GitHub Pages。遇到失效的站内链接、失效的锚点、缺失的图片，或某个页面只在一个语言下存在时，构建都会失败，最后这一条正是 guide/、reference/、examples/ 与 contributing/ 下每个英文页面都有一个结构相同的中文对照页的原因。TypeScript 示例在两个语言下保持一致；散文与代码注释需要翻译。生成的类型 API、宿主能力、事件、通知与诊断参考页在构建时由仓库中的事实来源渲染而来，只做镜像，不翻译。

仓库约定

有两条规则值得单独写出来，因为它们很容易被无意破坏：

examples/* 是面向用户的产品，不是测试夹具。 它们只能使用公开的 agent-bundle 导出与 workspace:* 依赖，并在桌面视口下验收。开发者 Workbench 是一个仅面向桌面的应用。
repos/ 下随仓库携带的参考材料是只读的。 不要编辑、格式化或从中导入。应用代码导入的是已发布的包。

框架自身的契约与代码一起放在仓库中： Framework mode 讲编写模型， Entry conventions 讲包构建， Diagnostics 是 AB 代码目录。

#参与贡献

#三道门禁

#本地合并循环

#Changesets

#原生宿主 smoke 需要显式开启

#开发 Workbench 界面

#文档站点

#仓库约定