先按创建应用准备一个 App 并完成依赖安装。插件会生成在这个 App 的 packages/ 下，与应用一起开发和构建。
你可以让 Agent 帮你创建，也可以手动使用 pnpm create @nocobase/plugin@beta。两种方式都使用 @nocobase/create-plugin。
使用 Agent
插件开发指引由 App 的 @nocobase/app-skills 提供，同步到 .agents/skills/nocobase-app-plugin-development/SKILL.md，无需全局安装。若文件缺失，先检查已安装的包是否包含该 Skill；包含时运行 pnpm nocobase skills sync，否则按升级 NocoBase Core更新到兼容版本，不要单独更新某一个框架包。
在应用目录中打开 Agent，告诉它插件的名称和用途即可。例如：
帮我创建一个叫 demo-tools 的插件，用来扩展当前应用的命令行工具。
先生成基础结构，并检查它能否正常构建。Agent 使用 @nocobase/create-plugin 生成插件，并根据用途选择能力、处理依赖和检查结果。你可以把示例中的名称和用途换成自己的需求，无需逐项描述命令参数和文件改动。
不使用 Agent
以下命令都在 App 根目录执行，使用应用要求的 Node.js 和 pnpm 版本。创建工具和 App CLI 需要支持 App 工作区；@beta 选择创建工具的 beta 发布渠道。本篇以只选择 cli 能力的 demo-tools 为例，无需启动数据库或 Web 服务。
创建工具会完成什么
@nocobase/create-plugin 根据所选能力生成一个可继续开发的插件包，并接入当前 App 的工作区。
| 工作 | 自动完成的内容 |
|---|---|
| 插件骨架 | 生成包声明、开发指引、TypeScript、代码检查及构建配置 |
| 能力代码 | 按 --with 选择生成对应目录、声明、示例或草稿，以及相关测试 |
| 公开入口 | 按能力生成 Client、Server、CLI 或组件等导出，并配置源码与构建产物的导出映射 |
| 依赖 | 根据所选能力确定依赖分类，并从当前 App 已安装的包解析版本 |
| 工作区接入 | 将插件放到 App 的 packages/ 下，补充必要的工作区配置和 App 的本地依赖 |
| 安装 | 默认安装依赖并更新锁文件；可用 --no-install 推迟 |
创建完成后，继续实现业务逻辑、完善测试，并按插件提供的运行时入口注册到 App。工具不会自动完成业务页面、接口、权限规则，也不会自动发布插件或执行数据库迁移。
选择插件能力
基本用法：
pnpm create @nocobase/plugin@beta <name> --with <capability>--with 选择的是要生成的代码能力，不是安装已有插件，也不是启用某项业务功能。必须至少选择一种能力，或者使用 --empty 只生成包基础结构。多个能力通过重复 --with 组合，不使用逗号拼接。
客户端能力
--with 的值 |
生成内容 | 需要继续实现的内容 |
|---|---|---|
client.routes |
client/routes.ts 路由声明骨架及测试 |
页面组件、路由路径、导航与访问条件；不会自动生成业务页面 |
client.components |
client/components/plugin-component.tsx 示例组件、公开导出及测试 |
可复用组件的实际界面、属性和交互 |
client.service-providers |
client/providers/ 中的 ServiceProvider 骨架及测试 |
浏览器端服务注册和生命周期处理 |
client.react-providers |
client/contexts.ts、Provider 组件、client/react-providers/ 声明及测试 |
React 上下文的数据、状态与组件树组合 |
client.locales |
client/locales/ 中的语言文件和聚合入口 |
实际翻译内容，以及组件中的使用 |
ServiceProvider 用于应用服务与生命周期，React Provider 用于组件树中的上下文，两者按需要分别选择。带客户端代码时，工具还会生成 components.json 和 client/styles.css，准备 shadcn 配置与样式入口；需要的 UI 组件仍要按业务安装或编写。
服务端能力
--with 的值 |
生成内容 | 需要继续实现的内容 |
|---|---|---|
server.service-providers |
server/services/、server/providers/、server/tokens.ts 及测试 |
服务接口、业务逻辑和服务注册 |
server.routes |
server/routes/index.ts 路由声明骨架及测试 |
API 或 Root Route 的方法、路径、输入校验、认证授权和响应 |
server.jobs |
server/jobs/ 中的示例 Job、管理执行器的 Provider 及测试 |
任务逻辑、提交任务的位置、重试与幂等要求 |
server.locales |
server/locales/ 中的语言文件和聚合入口 |
服务端使用的实际翻译内容 |
server.routes 不会自动生成 CRUD 接口，也不要求一定同时选择 server.service-providers；需要独立业务服务时再组合。server.jobs 已包含管理任务执行器的 Provider，任务后端由 App 配置，具体何时提交任务需要自行实现。
数据库、CLI 与 Skills
--with 的值 |
生成内容 | 需要继续实现的内容 |
|---|---|---|
database |
database/migrations/、database/seeds/ 中的 .ts.example 草稿、服务端资源声明及测试；构建时生成数据库任务清单 |
具体表结构、迁移与种子逻辑；草稿完善并改为 .ts 后，才纳入数据库任务 |
cli |
cli/index.ts、示例 info 命令、./cli 导出及测试 |
实际命令、参数、结果和错误处理 |
skills |
skills/<插件技能名>/SKILL.md 草稿，并纳入包的分发文件 |
向使用插件的 Agent 说明触发条件、公开能力、前提和验证方式 |
skills 面向使用插件的应用 Agent。插件根目录的 AGENTS.md 则面向维护插件源码的开发者和 Agent，属于基础文件，不需要额外选择 skills。Skill 草稿应根据真实实现完善后再同步给应用使用。
运行时入口如何生成
工具会根据能力推导入口，不需要额外指定 --with client 或 --with server：
| 所选能力 | 自动生成的运行时入口 |
|---|---|
client.routes、client.service-providers、client.react-providers、client.locales 中任意一种 |
client/index.ts、client/plugin.ts 和 ./client 导出 |
任意 server.* 能力，或 database |
server/index.ts、server/plugin.ts 和 ./server 导出 |
cli |
cli/index.ts 和 ./cli 导出 |
仅 client.components |
组件的公开导出，不生成客户端插件注册入口 |
仅 skills 或 --empty |
不生成运行时入口 |
这些入口的生成与 App 中的注册是两个步骤。仅引用公开组件时，通过包导入使用即可；提供 Client、Server 或 CLI 贡献时，再注册对应入口。
常见组合
下面是相互独立的创建示例，按功能选择即可。
仅提供可复用组件：
pnpm create @nocobase/plugin@beta feature-card --with client.components需要页面、服务、接口和插件自有数据的业务模块：
pnpm create @nocobase/plugin@beta orders \
--with client.routes \
--with server.service-providers \
--with server.routes \
--with database提供工具命令，并附带 Agent 使用指引：
pnpm create @nocobase/plugin@beta audit-tools --with cli --with skills只建立包基础结构：
pnpm create @nocobase/plugin@beta shared-tools --empty--empty 不生成业务能力目录，不能与 --with 混用。--with all 会选择当前工具版本支持的全部能力，适合查看完整骨架；实际开发通常明确选择需要的能力即可。
1. 预览生成计划
pnpm create @nocobase/plugin@beta demo-tools --with cli --dry-run --jsondry-run 不生成插件文件、不修改 App，也不安装 App 的依赖；pnpm create 本身仍可能下载并缓存创建工具。返回的 JSON 中，ok 应为 true，status 为 success-noop，重点检查：
| 字段 | 应看到什么 |
|---|---|
result.project |
kind 为 application，root 为当前 App 根目录 |
result.plugin |
包名为 @nocobase/app-plugin-demo-tools，目标目录为 App 下的 packages/app-plugin-demo-tools/ |
result.requestedCapabilities、result.capabilities |
请求的能力与规范化后的选择结果 |
result.derivedStructure |
是否生成客户端或服务端插件入口；本例两者均为 false |
result.files |
文件路径和生成原因，包含 cli/index.ts、cli/info.ts 和对应测试 |
result.projectEdits |
计划修改的应用文件，例如 package.json，必要时还有 pnpm-workspace.yaml |
result.dependencies |
根据当前应用已安装的包解析出的插件依赖 |
result.nextSteps |
后续安装、检查和注册等建议；结合实际能力执行 |
创建工具通过应用 package.json 中的 nocobase.templateKind: "app" 识别 App。它读取现有工作区和已安装依赖，先检查路径、名称与版本，再生成文件。因此需要先完成应用的依赖安装。
2. 创建插件并接入工作区
使用相同的名称和能力执行创建：
pnpm create @nocobase/plugin@beta demo-tools --with cli创建工具会完成以下工作：
- 生成
packages/app-plugin-demo-tools/，包括包声明、CLI 实现、测试和开发配置；本地插件默认private: true。 - 确保应用的 pnpm 工作区包含插件目录，保留已有设置；仅在需要时补充
packages/*。 - 在应用
package.json的dependencies中加入"@nocobase/app-plugin-demo-tools": "workspace:*"。 - 根据应用已安装的包确定外部依赖版本，对实际存在的本地工作区包保留工作区引用，然后安装依赖并更新锁文件。
workspace:* 让应用使用本地插件包。创建工具不会把插件的外部依赖一律写成 workspace:*，也不会随意选择最新版本；它以应用实际安装的版本为依据，避免生成后找不到包或版本不兼容。
3. 检查生成结果
pnpm --filter @nocobase/app-plugin-demo-tools check检查通过后，插件骨架已经生成并成为 App 的本地依赖。各文件的职责见插件的结构。
安装依赖让应用能够解析这个包，运行时注册则决定应用加载哪些能力。创建工具不会自动注册运行时入口；后续通过 pnpm nocobase plugin register <完整包名> --no-install 注册实际提供的 Client、Server 或 CLI 入口。完整的实现、注册和验收流程见编写第一个插件。
名称与常用选项
短名称 demo-tools 默认生成 @nocobase/app-plugin-demo-tools。自己的插件可以使用完整包名保留组织 scope，例如：
pnpm create @nocobase/plugin@beta @my-company/app-plugin-audit-tools --with cli目录仍为 packages/app-plugin-audit-tools/，注册时使用完整包名。名称中的能力部分以小写字母开头，使用小写字母、数字和单连字符。创建工具拒绝已有目录或冲突的包名。本地插件不必发布；需要发布时，再检查 private、包名、导出、兼容性和发布内容。
| 选项 | 用途 |
|---|---|
--dir <directory> |
显式选择已有 App，例如从父目录传入 --dir ./my-app |
--dry-run --json |
只读预览生成文件、应用改动和依赖版本，便于人或 Agent 检查 |
--json |
输出结构化结果；安装过程的日志写入 stderr |
--no-install |
生成文件但暂不安装；注册前需在 App 根目录运行 pnpm install |
--display-name <name>、--description <text> |
设置插件的显示名称和描述，含空格时加引号 |
--help、-h |
查看当前版本支持的能力和参数 |
--version |
查看创建工具的版本 |
JSON 输出
--json 可以与实际创建或 --dry-run 组合，便于 Agent 和脚本读取。成功时查看 ok: true 和 result；失败时返回非零退出码，并在 error.code、error.message 和 error.suggestions 中说明原因与处理建议。安装日志写入 stderr，创建工具的 stdout 保持为一个 JSON 结果文档。
--dry-run 是预览，--no-install 则会真实写入插件和 App 文件，只推迟依赖安装，两者作用不同。
常见问题
| 现象 | 处理方式 |
|---|---|
| 找不到 App | 在 create-app 生成的应用根目录执行，或用 --dir 指向该应用；确认已安装依赖且工具版本支持 App 工作区 |
| 缺少依赖，或依赖版本不兼容 | 先完成 App 的依赖安装，按报错修复所需版本，再重新预览 |
| 目标目录、包名或应用依赖已存在 | 检查已有实现，或换用不冲突的名称，不要覆盖已有插件 |
| 工作区规则排除了插件目录 | 检查 pnpm-workspace.yaml 的排除规则，按项目需要调整后再预览 |
| 文件已生成，但安装失败 | 保留生成结果，解决安装错误后在 App 根目录重新运行 pnpm install，无需再次创建 |
| 想给已有插件增加一种能力 | 创建工具用于新建包，不会增量修改已有插件；按插件的结构补充实现、声明、导出、依赖和测试，再检查 App 注册 |
| 选择路由或数据库能力后没有业务功能 | 生成的是声明骨架或草稿，还需实现页面、接口或迁移，并完成接入与验证 |
| 包已安装，但命令不存在 | 检查 ./cli 导出和应用 cli/plugins.ts 注册，并从 App 根目录调用 |