开发一个模块
把一项功能做成仓库里的一个模块:代码、两种方言的 schema 与迁移、区域标记、清单和校验器。
模块是一项边界被仓库准确记录下来的功能:它的文件、它在共享文件里的区域、它的数据表和设置。把你自己的功能做成模块,就能与上游代码分开,合并时冲突更少,pnpm validate:registry 还能证明底座在没有它时仍然可以编译。本指南从头到尾添加一个模块。仓库自带的 affiliate 模块(modules/affiliate/module.json)是一个完整的例子,可以对照着看。
如果你使用编码 agent,new-module skill 包含同样的步骤,见使用编码 Agent 技能。
准备工作
- 一份
pnpm validate:registry能通过的仓库克隆。开始之前记下哪些校验器是通过的,之后才能确认没有让任何一个由通过变为失败。 - 一个 kebab-case 的 key,下文写作
<key>,例如reviews。清单目录和标记都用它命名。 - 模块拥有的数据表、新增的页面,以及需要的权限键。
- 它依赖的模块的 key。例如
image-agent依赖agent-starter。
添加模块
提出变更
openspec-cn new change "<key>"
openspec-cn validate "<key>"校验之前,先填好 openspec/changes/<key>/ 下的 proposal.md、design.md、specs/<key>/spec.md 和 tasks.md。
添加数据表,并为两种方言各生成迁移
在 src/server/db/schema/sqlite.ts 和 src/server/db/schema/postgres.ts 中都定义这些表,表名保持一致。然后为每种方言生成一个迁移:
pnpm db:generate:sqlite --name my-change
pnpm db:generate:postgres --name my-change
pnpm validate:migrationsPostgres 那一条需要设置 DATABASE_URL,但不会连接数据库。两种方言最终要有相同的迁移标签(例如 0018_<key>),分别位于 drizzle/migrations/sqlite 和 drizzle/migrations/postgres。
编写代码
| 内容 | 位置 |
|---|---|
| 数据访问 | src/server/db/repositories/<key>.repository.ts |
| 业务逻辑 | src/server/services/<key>.service.ts |
服务端函数,用 requireAdminPermission 检查权限 | src/server/functions/<key>.ts |
| 组件 | src/components/<key>/ |
| 页面 | src/routes/{-$locale}/admin/ 或 src/routes/{-$locale}/app/ |
插件:清单以及 admin.nav 导航项等贡献 | src/plugins/<key>/manifest.ts、src/plugins/<key>/plugin.ts |
所有数据库访问都经过 repository。业务代码不出现具体的 SQL 方言。/admin 和 /app 的布局已经保护了各自的路由树,新页面不需要自己加守卫。插件能贡献什么,见插件。
接入共享文件
模块还需要在底座拥有的文件里加几行:
src/plugins/installed.ts中的插件 import 和列表项;src/i18n/locales/en/messages.ts和src/i18n/locales/zh/messages.ts中的文案,两边的键必须一致;src/server/services/super-admin-bootstrap.service.ts中的权限行,以及src/server/db/repositories/users-rbac.repository.ts中的预设角色。
把这些片段,连同第 2 步的数据表,用标记行包起来:
// @module:<key>
import { reviewsPlugin } from "./reviews/plugin";
// @end-module:<key>注释语法跟随文件类型://、/* */、<!-- -->、-- 或 #,在 JSX 元素之间则写 {/* @module:<key> */}。区域不能嵌套,而且去掉所有区域后底座必须仍能编译。在 src/plugins/installed.ts 中保持 import 的排序,这样整理 import 时不会把某一行移出它的区域。
编写校验器
创建 scripts/validate/<key>.ts。断言行为和接线,不要只断言文件存在。用名称以 validate- 开头的测试数据调用 repository,检查结果,再把测试数据清理掉。然后在 package.json 中加上:
- 脚本
"validate:<key>": "tsx scripts/validate/<key>.ts"; validate:all链中的pnpm validate:<key>片段。
编写清单
创建 modules/<key>/module.json。目录名必须与 key 相同。
{
"key": "reviews",
"kind": "module",
"version": "0.1.0",
"requires": [],
"files": [
"src/plugins/reviews/**",
"src/components/reviews/**",
"src/routes/{-$locale}/admin/reviews.tsx",
"src/server/services/reviews.service.ts",
"src/server/db/repositories/reviews.repository.ts",
"src/server/functions/reviews.ts",
"scripts/validate/reviews.ts"
],
"fragments": [
"src/plugins/installed.ts",
"src/server/db/schema/sqlite.ts",
"src/server/db/schema/postgres.ts",
"src/i18n/locales/en/messages.ts",
"src/i18n/locales/zh/messages.ts",
"src/server/services/super-admin-bootstrap.service.ts",
"src/server/db/repositories/users-rbac.repository.ts"
],
"migrations": ["0018_reviews"],
"packages": [],
"validators": ["validate:reviews"],
"i18nNamespaces": ["reviewsCopy"],
"admin": { "routes": ["/admin/reviews"], "configPages": [] },
"screenshots": [],
"docs": [],
"tables": ["reviews"],
"configKeys": [],
"skillPackages": []
}| 字段 | 构建时强制的规则 |
|---|---|
files | 每个 glob 至少匹配一个文件;同一个文件不能被两个模块认领。以 ! 开头表示排除某个路径 |
fragments | 列出的每个文件都有 @module:<key> 区域;模块完全拥有的文件不带标记 |
migrations | 该标签在两种方言中都有 .sql 文件和 journal 条目 |
packages | name@range 形式,并且存在于 package.json 的 dependencies 中 |
validators、scripts | package.json 中存在的脚本名 |
tables | 与模块的文件和区域在两种方言中定义的表完全一致。模块有迁移时必须声明 |
configKeys | 模块自己的代码写入的后台配置键。以 . 结尾表示该前缀下的所有键 |
skillPackages | 模块自己的代码发布的 Skill 包 id,它自带的每个 Skill 目录对应一个 |
其余字段是描述性的。key 与目录名相同,version 是模块自己的版本。kind 对一项功能是 module,对自带运行时的条目是 template,例如 agent-starter。requires 列出它依赖的模块。i18nNamespaces 是它拥有的字典命名空间,admin、screenshots 和 docs 记录它的后台页面与素材。
tables、configKeys 和 skillPackages 说明模块拥有哪些数据,所以构建会把它们与代码核对。
用构建核对清单
pnpm registry:build构建按清单切分仓库,并写入 registry/dist/:index.json、每个条目一个 <key>@<version>.json,较大的条目还有 .files.<n>.json 分页。它为每个条目打印一行,包含文件数、片段数和迁移数。清单违反上面任何一条规则时,构建会停止,并在错误信息中指出模块和问题。
验证模块
pnpm validate:registry通过:底座加上所有模块能逐字节重现仓库,并且底座在没有任何模块时能通过类型检查。pnpm validate:<key>、pnpm validate:plugins、pnpm validate:app-i18n、pnpm validate:route-i18n、pnpm validate:auth-boundary和pnpm validate:migrations通过。pnpm typecheck、pnpm build和pnpm check没有新增问题,pnpm validate:all没有让原本通过的检查失败。pnpm validate:kernlift-lifecycle通过:它在一个临时项目里应用并移除构建出的条目,包括数据清除。
常见问题
「has migrations but declares no tables in module.json」
把模块创建的每一张表都列进 tables。
「module.json tables […] differ from the sqlite tables its files define […]」
tables 必须与模块自己的文件和标记区域中 sqliteTable(...)、pgTable(...) 的表名一致。要么有表定义落在了 @module 区域之外,要么列表过期了。
「no file matches …」
files 中有一个 glob 什么都没匹配到。修正路径或删掉这一项。
… has no @module:<key> region
fragments 中列出的某个文件没有该模块的区域。加上标记,或者把这个文件从 fragments 中去掉。
pnpm validate:registry 在底座类型检查时失败
底座中的某个文件引用了模块拥有的东西。把这个 import 移进 @module 区域,或者让底座通过插件插槽使用该功能。