开发者中心

把"只写扩展"和"要看到它跑起来"这两种工作方式的最少依赖分清楚 —— 前者只需要 Node。

1. 1node -v

   要 Node ≥ 20。写包、校验清单、打包这三件事**只需要 Node**（引擎 CLI 是纯 Node 脚本 ✓），不需要数据库。

   照抄验证：打印 v20 或更高。低于 20 时 CLI 会因语法/API 不兼容直接报错。

2. 2npm ci

   装整站依赖。要"看到扩展真的在站点里跑起来"时才需要这一步（引擎的运行时编译依赖 esbuild 与 @vue/compiler-sfc ✓）。

   照抄验证：无 ERROR；node_modules 出现。

3. 3npm run engine:list

   列出仓库里的全部扩展包与清单校验结果。这是**不需要数据库**就能跑的 ✓。

   照抄验证：打印每个包的类型 / id / 版本 / 说明，末尾一行「共 N 个包，其中 0 个清单有问题 ✓」。

4. 4npm run dev（另开一个终端）

   要看到界面效果就得起整站，而起整站需要 PostgreSQL 与 Redis（见仓库 .env.example ✓）。

   照抄验证：打开 http://localhost:3000 能访问；终端里出现「Nitro built」。

5. 5npm run engine:validate

   每次改完包都先跑它。它同时校验规范快照与源码是否一致 ⇒ 也能挡住「文档过期」✓。

   照抄验证：「0 个清单有问题、0 处区域契约错误、0 处主题契约错误」——**有告警也要处理**，它是零告警口径。

深入参考：快速开始与命令速查目录结构

走通"生成骨架 → 写逻辑 → 启用 → 看到它生效"这一整条路。插件是最容易上手的类型。

1. 1npm run engine:new -- --type plugin --id my-plugin --name "我的插件"

   生成 engines/plugins/my-plugin/（manifest.json + hooks.ts + README.md ✓）。生成的骨架**本身是干净的**：零错误零告警。

   照抄验证：提示「生成」且 engine:validate 立刻通过。

2. 2编辑 manifest.json，把 "hooks": ["lead:created"] 填上

   声明与实现**必须一致**：声明了没实现会被拒绝；实现了没声明则不会被注册（最坑的一种，因为它不报错但什么都不发生 ✓）。

   照抄验证：engine:validate 仍通过；清单里 hooks 不再是空数组。

3. 3编辑 hooks.ts：on('lead:created', async ({ lead }) => { log('收到新线索 ' + lead.id) })

   log 会自动加 [engine:my-plugin] 前缀 ✓，这是后面"确认它真的跑了"的抓手。

   照抄验证：engine:validate 通过（它会检查 on() 用到的扩展点都在清单里声明过 ✓）。

4. 4后台 →「引擎与扩展」→ 重新扫描 → 启用

   新装的包**默认停用** ✓。插件与钩子是运行时加载的：改完源码只需再点一次「重新扫描」，不用重新构建、也不用重启。

   照抄验证：列表里出现我的插件，状态为已启用；重新扫描的返回里 uiErrors 为空。

5. 5前台打开 /contact，提交一条需求

   这一步才是真正的验收：**扩展点被触发**。

   照抄验证：服务端控制台出现 [engine:my-plugin] 开头的一行日志，里面带你刚才那条线索的 id ✓。

深入参考：hooks.ts 的接口与生命周期扩展点清单

做出"能在页面里放一块、参数后台可调、样式自己写的展示单元"。这是社区最容易被贡献的一类。

1. 1先读一个真实的：engines/themes/hejun-default/components/FeatureSteps.vue

   它就是"三步走"区块。要点只有两条：① 清单 settings 里的 key 与组件的 props **同名**就自动拿到值 ✓；② 只有 public: true 的设置项才会下发到前台 ✓。

   照抄验证：在后台「引擎与扩展 → 禾君默认主题」能看到它的设置项并改值，前台刷新后跟着变。

2. 2npm run engine:new -- --type theme --id my-block --name "我的区块"

   区块就是"只有组件、没有布局与页面的 theme"✓ —— 类型名仍是 theme ✓（历史上叫过 template，那个名字已经不用了 ✓）。

   照抄验证：engine:validate 通过，输出里出现 my-block。

3. 3在 manifest.json 里声明 regions，例如 ["home.after-systems"]

   区域是"页面留给扩展的位置"✓。站点里可用的区域清单在 engine:validate 输出的末尾 ✓；**声明了站点不存在的区域，校验会直接失败** ✓（宁可报错，也不让你做出一个永远不显示的区块 ✗）。

   照抄验证：engine:validate 通过；若故意写一个不存在的区域，它会报错并列出可用清单 ✓ —— 这一条建议你真试一次。

4. 4在站点页面里放 <TemplateSlots region="home.after-systems" />（或由主题自动注入）

   页面只留位置，谁声明了该区域谁就出现在那里 ✓；没有扩展声明时它渲染为空 ✓（不会留下空洞 ✓）。

   照抄验证：启用后前台对应位置出现你的区块；停用后立刻消失。

深入参考：包内部布局（名字是硬约束）在页面里使用扩展区块

一整套业务能力：后台能管、接口能用、权限可分配、数据可存。

1. 1npm run engine:new -- --type module --id my-module --name "我的模块"

   模块骨架比插件多几个位置：pages/admin/、server/api/、schema.example.prisma ✓。

   照抄验证：engine:validate 通过。

2. 2照 faq-manager 写后台页：engines/modules/faq-manager/pages/admin/faqs.vue

   这是"随源码交付"的真实模块 ✓（你也可以在开发者中心的「源码拉取」里直接下载它的源码 ✓）。后台页要完整语义（admin 布局 + 鉴权）就得随源码构建一次 ✓。

   照抄验证：重新扫描后后台侧边栏出现你的菜单项，能进页面。

3. 3在清单里声明 permissions，接口放进包内 server/api/admin/

   **不必改核心的 route-perms.ts** ✓：声明的权限点会自动出现在后台「角色权限」里等分配 ✓；包内 server/ 路径原样映射为 /api/… ✓。

   照抄验证：后台「角色权限」里能看到你声明的权限点；未分配时调接口返回 403，分配后通过 ✓。

4. 4要建表时：写 schema.prisma（只写自己的 model）→ npm run engine:schema → npx prisma db push → 停服 npx prisma generate → 重启

   这是**唯一绕不开重启**的部分 ✓：Prisma Client 由构建期生成，运行时加不了 model ✓。Windows 上 dev server 占着查询引擎 dll，不停服 generate 会 EPERM ✓。

   照抄验证：重启后接口里 prisma.你的模型 可用；后台「扩展详情」显示它带了数据表。

5. 5卸载时：npm run engine:remove -- --type module --id my-module

   它会先跑扩展自己的 onUninstall 清理数据，再删目录与状态记录 ✓。数据表要不要手动清，写在 README 里 ✓（审核表也查这一条 ✓）。

   照抄验证：提示卸载完成；engine:list 里不再出现它。

深入参考：模块自带后台接口与权限点数据模型

整套外观可切换：布局 + 样式（+ 新页面）。

1. 1读两份真实主题：engines/themes/hejun-default（禾君默认）、engines/themes/moderncommerce（Modern Commerce）

   两份都可以在开发者中心的「源码拉取」里浏览或下载 ✓（Modern Commerce 压缩后 21.68MB，超过后台上传上限 20MB ⇒ 它那条要**手工解压**到 engines/themes/ 下 ✓，页面会明确标出来 ✓）。

   照抄验证：后台「主题」页能看到它们，且**同时只能激活一个** ✓。

2. 2npm run engine:new -- --type theme --id my-theme --name "我的主题"

   主题可含 layouts/（引擎会用它接管站点布局 ✓）与 assets/*.css（构建期注入站点样式表 ✓）。

   照抄验证：engine:validate 通过；后台主题页出现你的主题。

3. 3在后台「主题」页切换激活

   切换是**可逆**的：未激活主题的页面与样式一律 404 ✓（有巡检闸门守着 ✓）。

   照抄验证：前台外观立刻改变；切回默认主题后完全恢复。

4. 4注意一条天花板：**扩展页面不能覆盖核心页面**

   核心页面是构建期注册的具体路由，扩展页面撞上它永远不会被渲染 ✓（这是"核心优先"的有意设计 ✓）。要改核心页面就改核心源码，而不是硬写扩展 ✓。

   照抄验证：试图用同名路径覆盖核心页面时，重新扫描的返回里会有告警 ✓。

深入参考：扩展能做到什么深度主题设计（离线文档）

把"改了没反应"变成"知道是哪一类没生效"。

1. 1看「重新扫描」的返回值（后台「引擎与扩展」页）

   接口、组件、页面的编译失败都会出现在 uiErrors 里 ✓。**编译失败的组件不会覆盖构建期那份** ⇒ 表现为"还是旧内容"✗ —— 这是最容易被误判成"热更新坏了"的一种 ✓。

   照抄验证：故意在组件模板里写一处语法错 → 重新扫描 → uiErrors 里出现该文件与错误行 ✓。

2. 2看服务端日志里 [engine:<包 id>] 开头的行

   钩子里的异常会被引擎吞掉并记日志（"顺带做的事"不该让主流程失败 ✓），所以**必须看日志**才知道钩子有没有跑、有没有报错 ✓。

   照抄验证：启用插件后提交一条线索，日志里出现对应的 [engine:...] 行。

3. 3看运行时产物目录 .engine-build/<包 id>@<版本>/

   引擎把包内 .vue 就地编译成 ESM 后放在这里 ✓。怀疑"编译出来的东西不对"时直接看它 ✓。

   照抄验证：该目录随包版本变化；engine:gc 会清掉旧版本（每包保留最近 2 个 ✓）。

4. 4改了什么之后要做什么（照这张表来）

   hooks.ts / 包内 server/api / 包内 components 与 pages / manifest.json ⇒ 点一次「重新扫描」✓；已有页面的模板（构建期注册的那份）⇒ 重新构建 + 重启 ✓；包内 schema.prisma ⇒ schema → db push → 停服 generate → 重启 ✓。

   照抄验证：按表操作后现象与预期一致；不一致时先怀疑"是不是改错了表里的那一格" ✓。

深入参考：改了什么之后要做什么（完整表）常见报错对照

把包交给别人装；付费包还能"装得上、看得见，但没授权就不跑"。

1. 1npm run engine:keygen

   生成一对 ed25519 密钥：私钥（ENGINE_PRIVATE_KEY）只留在你机器上 ✓，公钥交给站主加进「信任白名单」✓。**私钥绝不入库、绝不提交** ✓。

   照抄验证：打印出新生成的密钥标识（keyId）；再次执行会提示已有密钥。

2. 2npm run engine:pack -- --type module --id my-module --sign

   产出两个文件：包本体 .tar.gz（包内路径是 <id>/…✓）与同名描述文件 .json（含 sha256、作者、引擎兼容范围、签名与 keyId ✓）。

   照抄验证：打印 sha256；描述文件里有 signature 与 keyId 字段。

3. 3npx sha256sum dist/engines/<...>.tar.gz（或 certutil -hashfile ... SHA256）

   自己核对一遍摘要与描述文件是否一致 ✓ —— 站主装不上时的第一件事就是比对这两个数 ✓。

   照抄验证：算出来的摘要与描述文件里的 sha256 完全相同。

4. 4付费包：npm run engine:license -- issue --type module --id <id> --to "客户名" --per-major --days 365 --domain client-a.com

   三个收费选择都是签发参数、不用改代码 ✓（绑不绑域名、买断大版本还是永久、有效期 ✓）。签发完用 --verify 自查，--list 看台账 ✓。

   照抄验证：verify 输出"有效"；站主贴进后台时会**先校验再保存**，读不出来/不是给这个包的/签名对不上都会当场说明原因 ✓。

5. 5注意：它不是 DRM

   校验跑在站主自己的服务器上，他拥有代码与数据库 ⇒ 有能力改掉 ✓。它给的是"明确的契约状态 + 防误用" ✓，真正的约束力来自合同与交付关系 ✓。

   照抄验证：这一点值得写进你的交付说明里 ✓（免得客户以为它防得住有心人）。

深入参考：打包、分发与安装命令行速查

知道你的包走哪条路进来，以及要交什么。

1. 1纯前端型（主题 / 区块）→ 开发者中心的「上架」自助通道

   这是**唯一一条自助通道** ✓：只接受主题包（含只有组件的区块 ✓），且要求"签名者公钥已登记" ✓ —— 即站主的信任白名单里得有你的公钥 ✓（否则你会看到"信任表里还没有任何作者公钥"这句话 ✓，那就是原因本身 ✓）。

   照抄验证：先点「预检（不写入）」：它会解包、跑闸门，把"将写到哪里、覆盖什么、为什么不行"全摆出来 ✓；确认后才「发布」✓。

2. 2含服务端能力的（模块 / 插件）→ 把 .tar.gz + 描述文件 + 公钥交给站主，人工收录

   原因不是"我们不爱做工具"✗，而是隔离：扩展的服务端代码跑在与核心同一个进程里、拿到同一份 prisma ✓ ⇒ 装陌生人的服务端代码 = 把自己的数据库交给它 ✓。这条边界写在 docs/marketplace-selfserve.md ✓。

   照抄验证：站主侧会看到这包是谁签的（keyId）与从哪条通道进来的（installedFrom）✓ —— 出事时查得出"这个包是谁给的" ✓。

3. 3《上架清单》——作者要交什么

   ① 清单合法（engine:validate 通过）且 compat.engine 明确声明 ✓；② 语义化版本，破坏性变更必须升大版本 ✓；③ 包内必须有 README.md（后台扩展详情页直接显示它 ✓）✓；④ 声明清楚：自带几张表、用哪些权限点、注入哪些区域、是否联网、是否含定时任务 ✓；⑤ 签名与公钥随包提交 ✓。

   照抄验证：逐条对照一遍；缺 README 或声明不清的包，收录时会被退回 ✓。

4. 4《审核表》——站主收录时逐条过（你提前自查一遍）

   解包规则（无符号链接 / 无绝对路径 / 无 .. / 单顶层目录 = 包 id）✓；**不在运行时下载代码**（fetch 后 eval / 动态 import 远程 JS —— 这是绕过签名与审核的唯一路径 ✗）✓；不改核心表结构、不写别的模块的表 ✓；权限点粒度合理（不搞一个权限管全部 ✓）✓；联网地址白名单化写进 README ✓；有 README + 卸载说明（数据表要不要手动清 ✓）✓。

   照抄验证：把"联网地址"与"要动哪些表"写进 README 再交付 ✓ —— 这两条是站主最先问的 ✓。

深入参考：开发者上传入口（本页下方）接口变更记录

让你的扩展在引擎升级后不会突然不可用。

1. 1在清单里如实写 compat.engine 与 compat.nuxt

   引擎会**真的比对**这两个区间 ✓（nuxt 以前是死字段，现在会参与判断 ✓）。写宽了会在升级后炸、写窄了会白白不可用 ✓。

   照抄验证：engine:validate 不再给出"要求引擎 X，当前 Y"这类告警。

2. 2破坏性变更 = 老调用方或老扩展会坏

   删接口、删字段、可选字段变必填、字段类型变化、权限点变化、访问要求变严、删页面、扩展点或清单字段被移除 ✓；其余算兼容变更 ✓。**对扩展作者而言**：你的扩展如果依赖了某个扩展点或某个核心接口，那些东西被标记为破坏性时就要跟着改 ✓。

   照抄验证：升级前先跑一次 API 变更记录（下一节），只看 since 之后的部分 ✓。

3. 3GET /api/dev-docs?since=<你上次适配的引擎版本>

   只返回那之后的变化 ✓（返回里带 changelogSince ✓）。这是给扩展作者准备的机器可读入口 ✓。

   照抄验证：返回的 changelog 列表里能一眼看出有没有 breaking 项 ✓。

深入参考：接口变更记录（网页版）

把"没反应"拆成可检查的几类。

1. 1症状：后台启用了扩展，但前台没有任何变化

   按顺序查：① 扩展是否真的启用 ✓；② 它声明的扩展点是否"可用"（未实现的扩展点声明会被拒绝 ✓）；③ 设置项里是不是把功能关了 ✓。

   照抄验证：三步各有一条可观察的证据（列表状态 / 校验输出 / 设置值），别凭印象 ✓。

2. 2症状：组件在页面上没出现，或者还是旧内容

   先点一次「重新扫描」✓。返回里有 uiErrors ⇒ 编译失败 ⇒ 失败的组件**不会覆盖构建期那份** ⇒ 现象就是"还是旧的" ✓。另外用 <component :is="名字"> 渲染时，名字要和文件名一致 ✓。

   照抄验证：重新扫描的返回里 uiErrors 为空，且页面显示的是新内容。

3. 3症状：扩展接口 404 或报 xxx is not a function

   404 ⇒ 依次确认：文件在包内 server/api/ 下 ✓、做过一次重新扫描 ✓、没与核心接口重名（重名会被跳过并在服务端日志告警 ✓）。is not a function ⇒ 用了"可直接使用的名字"清单以外的标识符 ✓（用清单里的名字，或显式 import ✓）。

   照抄验证：日志里没有"跳过扩展接口"的告警；调用返回 200 而不是 404。

4. 4症状：我改了包内 server/ 下的新接口文件，但前台还是 404（实测踩过 ✓）

   **新加的服务端路由需要重启 dev server** ✓ —— 改动已有文件会热更新，但**新增**的路由文件在当前开发环境里要重启一次才注册 ✓。这一条是本站在做「源码拉取」时自己踩到的 ✓，写下来免得你也白查一轮 ✓。

   照抄验证：重启后同一个 URL 从 404 变成 200。

5. 5症状：包下载下来改完，后台上传被 413 挡住

   安装器有**自己的**体积上限（`LIMITS.maxTotalBytes`，当前 20MB ✓）。超过它的包（例如 Modern Commerce 主题，压缩后 21.68MB ✓）走不了上传通道 ✓ ⇒ 改成**手工解压**：把 tar.gz 解到你站点的 engines/<类型>/ 下（包内顶层目录就是包 id ✓），再点一次「重新扫描」✓。

   照抄验证：engine:list 里能看到它、后台能启用 ✓（这条不受上传上限约束 ✓）。

深入参考：常见报错对照（13 条）扩展的边界与生效时机

知道"引擎/接口/规范改了什么"，以及怎么只看自己关心的那一段。

1. 1网页版：/docs#changelog

   由脚本从**代码差异生成**（不是手写的 ✓），所以它不会过期 ✓。破坏性变更被单独标出来 ✓。

   照抄验证：能看到每次变更的日期、引擎版本、逐条变更与是否破坏性 ✓。

2. 2机器可读版：GET /api/dev-docs?since=<引擎版本>

   同上，但按 since 过滤 ✓，适合放进你的 CI 或适配清单 ✓。

   照抄验证：返回里 changelogSince 与请求的 since 一致。

3. 3维护者侧：npm run api:changelog -- --note "说明"

   改动核心接口/模型/页面/扩展规范后跑一次，把变化落账 ✓。有静态闸门守着接口快照与代码一致 ✓ —— 破坏性变更不走这一步会被拦下 ✓。

   照抄验证：报告里不再出现 api-drift 这类失败。

深入参考：接口变更记录门禁与巡检