默认模板已经包含多种插件。开发应用时，通常直接使用它们提供的认证、用户、权限、文件等能力；只有确认当前应用缺少所需能力时，才需要增加插件。任务和项目这类应用自己的业务代码仍放在应用目录，不必先拆成插件。
本篇说明应用如何管理插件，不是插件开发教程，也不是所有可用插件的产品目录。命令以示例应用已安装的 CLI 为准，执行前可用 --help 确认当前版本支持的选项。
使用 Agent
请检查当前应用已经具备哪些插件能力，以及现有业务实际使用了哪些。
先查看已安装依赖、实际注册和相关使用指引，不要仅凭插件名称判断能力，也不要重复实现已有功能。
本轮先不新增、升级或移除插件。
告诉我每项业务依赖哪些插件、通过什么公开入口使用，以及哪些管理页面或必要配置尚未接通。
如果发现必须变更依赖，请说明具体原因、兼容版本和受影响功能，再给出可检查的改动方案。
不要改变现有用户权限或清理业务数据。需要真正变更插件时，把目标说清楚，例如“把当前应用的定时任务插件更新到已确认兼容的版本，并验证现有任务定义与执行功能”。是否注册、更新或移除由这次任务决定，不让一次能力检查顺便改变应用依赖。
不使用 Agent
查看安装与注册
先查看 package.json 中的 @nocobase/app-plugin-* 依赖，以及锁文件中的实际解析版本。再检查三个组合入口：
| 文件 | 注册内容 |
|---|---|
client/plugins.ts |
浏览器中的插件贡献 |
server/plugins.ts |
服务端的 Provider、路由等贡献 |
cli/plugins.ts |
命令行贡献 |
包出现在依赖中不等于已注册到运行时；三个入口也不要求完全相同，例如只提供命令的插件只需相应 CLI 入口。数组顺序影响贡献顺序，不应为了排序好看而随意重排。
.agents/skills/ 中存在某个 Skill 也不证明插件已经启用：Skills 可以从直接依赖同步。实际注册以组合入口为准。插件包通常放在应用的 dependencies，以便进入部署产物；不要把客户端插件误认为只能放进 devDependencies。
使用已有能力
先读已安装插件的 Skill，确认公开服务 token、客户端 hooks、组件、路由与管理能力。业务功能通过公开导出调用它们，不直接写插件内部表，也不从插件内部源码路径导入实现。
例如项目功能使用权限插件声明“查看、新建、修改任务项目”，复用用户和角色管理；不需要再安装一套权限包，也不应自己实现另一份角色存储。应用还要把用到的能力接入真实页面和业务接口，安装依赖本身不会自动完成业务功能。
注册确实缺少的插件
下面以定时任务插件为命令示例。若应用已经注册了它，跳过注册；换成目标插件前先确认它的可用性、版本要求和所需配置：
pnpm nocobase plugin register @nocobase/app-plugin-scheduler --dry-run
pnpm nocobase plugin register @nocobase/app-plugin-scheduler命令负责安装依赖、接入插件导出的组合入口并同步 Skills。检查 package.json、锁文件和实际 Client／Server／CLI 注册变化。需要固定兼容版本时使用 --version，不要把一个新包的默认版本当成一定与当前应用兼容。
单独运行 pnpm add 只解决包安装，不能替代运行时注册。--no-install 需要依赖已经可解析；--disabled 用于安装而不接入运行贡献，不等于现有功能已可使用。根据命令输出检查实际处理了哪些入口。
更新插件
先查看单个插件的更新计划，再执行：
pnpm nocobase plugin update @nocobase/app-plugin-scheduler --dry-run
pnpm nocobase plugin update @nocobase/app-plugin-scheduler包名是位置参数，不是 --plugin。不提供名称时会更新所有已注册插件，因此只改一项能力时应明确包名。
pnpm 的更新遵循项目声明的版本范围；范围固定时不保证得到更高版本。需要跨范围升级时先确定兼容目标，调整依赖范围并同步锁文件和 Skills，再检查变化。插件更新不等于合并新模板，也不能替代升级 NocoBase Core的整体流程。
更新后检查插件可能带来的迁移、配置和公开接口变化，验证使用它的功能并重新构建应用。已经部署的旧产物不会因为开发目录更新依赖就自动改变。
区分停用功能与移除插件
暂时不展示某个功能时，先决定只是隐藏入口，还是禁止使用。只隐藏菜单不能阻止直接页面或 API 请求；停用策略应覆盖实际操作入口，并保留需要恢复的代码与数据。
彻底移除插件前，查找应用中的 import、Client／Server／CLI 注册、路由、配置、服务、测试，以及其他能力对它的依赖。迁移或移除这些引用后，才执行卸载。
下面的 <name> 是占位符，替换为已经确认不再使用的插件；不要对仍承担业务功能的插件直接执行：
pnpm nocobase plugin unregister '@nocobase/app-plugin-<name>' --dry-run
pnpm nocobase plugin unregister '@nocobase/app-plugin-<name>'也可以通过 pnpm nocobase package remove <完整包名> 移除直接 NocoBase 依赖；插件包会交给插件注销流程处理。不要只手动删除 package.json 中一行，否则注册和同步文件可能残留。
注销命令不替你决定如何处理历史业务数据，也不是数据库回滚方案。需要保留、迁移或删除数据时，单独设计数据处理；不要顺手删除插件目录或表来“清理干净”。
扩展插件提供的界面
| 需求 | 优先使用 |
|---|---|
| 插件已有配置选项 | 注册时传入公开 options |
| 插件提供可组合组件或源码扩展点 | 使用组件，或按约定在 client/extensions/ 接入 |
| 替换插件某个页面的呈现 | 已支持的 client/route-overrides.ts 或插件提供的覆盖方式 |
| 完全属于应用的业务页面 | 在 client/routes.ts 注册自己的页面 |
页面覆盖应保持原路由身份、路径和访问条件，按合同替换懒加载组件；不要再声明一个相同路径制造冲突，同一路由也不要叠加多个覆盖来源。当前模板的登录、注册等页面属于应用源码，不能仅因使用认证插件就把它们当作插件拥有的路由。
不要编辑 node_modules/ 或 .agents/skills/ 中的包内容。应用特有约定放入 .agents/rules/；共享插件本身的问题在它的源码仓库修复。
验证结果
检查依赖与锁文件、三个组合入口、同步 Skills 和实际消费者。运行受影响的类型检查、测试和构建；涉及迁移时验证升级后的旧数据，涉及 API 时检查应用 API 文档。浏览器里同时验证正常访问和普通用户的权限边界。
如果手动修改依赖或中途失败导致 Skills 不一致，可以重新同步：
pnpm nocobase skills sync