BTST 后端插件开发（btst-backend-plugin-dev）提供在 monorepo 内编写 BTST 后端插件时应遵循的模式与规则。
用途 该技能面向需要在 BTST 单体仓库中新增或维护后端插件的开发者，用于统一插件的目录组织、数据访问分层、业务操作定义、路由绑定与生命周期钩子命名，避免把校验、权限与生命周期逻辑散落到各处。
文件结构 插件位于 src/plugins/{name}/ 目录下，包含：
- api/plugin.ts：defineBackendPlugin 入口。
- api/getters.ts：只读数据库函数，不含 HTTP 上下文。
- api/mutations.ts：更底层的写数据库函数。
- api/operations.ts：经过校验的操作、权限事实与生命周期。
- api/index.ts：重新导出 getters、mutations 与类型。
- query-keys.ts：React Query key 工厂。
主要规则
- getters.ts：只放纯异步数据库函数，不含 HTTP 上下文，不含生命周期钩子，始终以 adapter 作为第一个参数。
- mutations.ts：只放底层写原语，不含 HTTP 上下文或生命周期组合；需注明调用方自行负责校验与生命周期。
- api/index.ts：从 getters 与 mutations 重新导出全部内容，供服务端直接导入。
- operations.ts：定义唯一维护的业务清单，包含输入校验、精确的权限描述符、权威事实、领域执行与生命周期钩子。
- 将 HTTP 路由绑定到同名 operation；仅当真实路由名不匹配时才使用 operationRouteMap。
- 可选的 raw 工厂范围很窄：一方插件只暴露 prefetchForRoute 用于 SSG。不要在 createBackendStack().raw 上重复业务 getters 或 mutations。
- 请求工作使用 myStack.forRequest(request).operations.，显式受信任务使用 myStack.trusted.。
关键模式
- 从 "@btst/stack/plugins/api" 导入 defineBackendPlugin 与 createEndpoint（不是 @btst/stack/plugins）。
- 以 import type { DBAdapter as Adapter } from "@btst/db" 导入 adapter 类型。
- 路由使用 createEndpoint(path, { method, query?, body? }, handler) 定义，而不是字符串键的 "GET /path" 对象。
- 路由处理器直接返回数据（return item），没有 ctx.json()。
- 使用 throw ctx.error(statusCode, { message }) 抛出错误。
- routes 工厂返回具名对象：return { listItems, createItem } as const。
- 导出路由类型为 ReturnType<ReturnType<typeof myBackendPlugin>["routes"]>。
生命周期钩子命名 命名模式为 onBefore{Action}{Entity}、onAfter{Action}{Entity}、onError{Action}{Entity}，例如 onBeforeListPosts、onAfterListPosts、onErrorListPosts，以及 onBeforeCreatePost、onAfterCreatePost、onErrorCreatePost 等。应保留有意义的领域事件，而不是生造 CRUD 阶段，例如 onBeforeChat、onAfterChat、onErrorChat、onBeforeActivateTools。规范化名称时不要添加插件本身尚不支持的生命周期阶段。
AI 工具 execute 函数中的受信操作 myStack 是模块级常量。execute 闭包惰性执行（仅在 HTTP 请求时运行），因此到那时 myStack 一定已初始化。示例： import { createBackendStack } from "@btst/stack/api" export const myStack = createBackendStack({ ... }) const myTool = tool({ execute: async (params) => { await myStack.trusted.kanban.createTask({ title: params.title, columnId: "col-id", }) return { success: true } } })
常见错误
- 导入路径错误：始终从 "@btst/stack/plugins/api" 导入，而不是 "@btst/stack/plugins"。
- adapter 类型错误：在 getters、mutations、plugin 文件中使用 import type { DBAdapter as Adapter } from "@btst/db"。
- 使用 "GET /path" 字符串键：路由应使用 createEndpoint()，而不是字符串键的 method/path 对象。
- 使用 ctx.json()：它不存在；应从路由处理器直接返回数据。
- 在 createBackendStack().raw 上添加业务方法：不要这样做。通过 forRequest(request).operations 或 trusted 保持组合生命周期显式，raw 仅保留给范围较窄的底层或 SSG 辅助函数。
- 在生命周期钩子中做授权：常规访问控制应放在 operation 描述符与唯一共享规则中；钩子接收的已是授权后的上下文。
- 在 getters.ts 中写写操作：写函数应放在 mutations.ts，而不是 getters.ts。
完整代码模式 完整的 defineBackendPlugin、getters、mutations 与 api/index.ts 代码形态见 REFERENCE.md。
适用场景与限制 该技能适用于在 BTST monorepo 内开发后端插件的场景，尤其是需要统一数据访问分层、业务操作定义与生命周期钩子的项目。资料未提供该技能的收费、价格、平台支持范围或效果数据。