模板与派生产品

仓库里的模块和模板产品有什么不同,业务模板是什么,以及如何在底座上只加一个插件,做出自己的产品。

这个项目里的一切都建立在同一个底座上。模块给它加一个功能,模板产品给它加一整种产品形态和自己的运行时,派生产品是你在底座上加一个自己的插件做出的产品。它们的区别决定了要部署什么,以及你自己的代码放在哪里。

模块还是模板产品

两者都已经在仓库里,各自由 modules/<key>/module.json 里的清单描述。kind 字段说明它是哪一种。

模块模板产品
module.json 里的 kindmoduletemplate
增加什么一个功能:页面、服务端代码、自己的表、文案和一个校验器一种产品形态:工作区包、第二个进程、一个运行时,以及这个运行时需要的表和设置
仓库里的例子cms、newsletter、affiliate、image-agentagent-starter
是否改变部署方式否是:要在 Web 应用旁边多运行一个服务
是否有别的东西建立在它之上很少是:agent 能力插件都依赖它

agent-starter 是唯一的模板产品。它的清单里有功能模块不包含的内容:packages/agent-* 工作区包和 apps/agent-service,脚本 dev:agent、build:agent-service 和 agent:publish-skills,包含运行、线程、技能和工作区数据表的迁移 0016_agent_starter,以及六个校验器。相比之下,image-agent 是一个 requires: ["agent-starter"] 的模块:一个插件目录、两条路由、一个设置 key,没有数据表。

模板产品是其他条目的基础,模块之上通常不再建立别的东西。两者的清单见底座仓库里有什么。

业务模板就是做好的派生产品

与底座一起出售的业务模板(image-studio、video-studio、image-agent、video-agent)是已经做好的派生产品。每个都是独立的私有仓库:底座加上某一个产品的插件、页面和套餐。你克隆的是它而不是底座,之后用同样的方式同步更新。见获取 Kernlift。底座仓库里的 image-agent 插件是随仓库提供的 Agent 能力示例;同名的业务模板是另一个独立的仓库。

本页余下的部分说明这样一个产品是怎么搭起来的,你做自己的产品也是同样的做法。

派生产品 = 底座 + 一个插件

在模板上做产品(比如一个生成图片或视频的站点)不需要另起一套后台。登录、套餐与结账、积分账本、服务商配置、文件存储、管理后台和校验器,底座都已经有了。你的产品只需要增加一个向后台插槽贡献页面和入口的插件,加上自己的落地页和套餐。

有两种做法,区别在于产品是否需要 agent。

不带 agent带 agent
由什么生成渠道任务:POST /api/<scene>/generate,通过 GET /api/status 读取结果一次 agent 运行:在同样的场景上调用 model.generate,并发布产物
你的插件一个 local 后台插件:一个 app.nav 入口,一个在 image-creation 或 video-creation 上发起任务的页面,可选一张仪表盘卡片建立在 agent-starter 之上的 agent 插件:一个场景、一个 Skill、输入框控件,可选自己的卡片和面板
用到的插槽app.nav、app.dashboard.cards,可选 api.routes 和 billing.fulfilmentagent.host、agent.workbench,可选 api.routes
交互方式一个表单和一个结果一段对话:读者描述、修改,结果直接出现在消息里
数据库任何受支持的数据库,包括 Cloudflare D1Postgres,或 Node 上的 SQLite
部署只有 Web 应用Web 应用和 agent 服务

两种做法共用同一套服务商接线。图片或视频服务商只在 /admin/config/ai 配置一次。无论哪条路径发起,任务都以积分计价,结果都进入用户的文件。见跑通图片和视频生成。

不带 agent

没有 agent 服务时,底座本身就是完整的 Web 应用。/app/ai 已经能发起和跟踪渠道任务,所以一个生成类产品就是在同样的 server function 和 API 之上写一个自己的页面,并登记为 local 插件。外壳的其他部分都不用改,这个插件还可以在 设置 → 插件 里停用。见编写后台插件。

带 agent

先把 agent-starter 的 agent 服务跑起来,再加一个能力插件。图片 Agent 是仓库自带的例子:它声明 agent.image 场景,自带 Image Studio Skill,在输入框旁加上画幅选择,并渲染 image 产物。视频能力的做法相同,而且不需要自己的产物类型,因为 video 是核心类型,对话里已经可以直接播放。宿主代码不按名称引用任何插件,所以再加一项能力只是在已安装列表里增加一条,不需要改工作台。见 Agent 插件。

Agent 在运行时也是可选的,所以一套代码可以同时服务两种部署。没有部署 agent 服务的地方,带 requires: "agent" 的入口被隐藏,普通的渠道页面照常可用。

仍然由底座负责的事

无论走哪条路,下面这些都不需要为每个产品重做:

  • 计费。 套餐、结账和积分账本。需要为已支付订单交付东西的插件,向 billing.fulfilment 贡献一个履约器,不修改订单。
  • 配置。 服务商凭据放在 /admin/config/*,不放在环境变量里。
  • 访问控制。 受保护的路由树在布局层守卫,插件的新页面默认就是受保护的。
  • 校验。 插件自带校验器,其余由 pnpm validate:all 覆盖。

相关文件

modules/kernlift/module.json
modules/agent-starter/module.json
modules/image-agent/module.json
src/plugins/installed.ts
src/plugins/installed.server.ts
src/plugins/slots.ts
src/plugins/server-slots.ts
src/plugins/image-agent/plugin.ts
src/plugins/image-agent/plugin.server.ts
src/server/agent-host/availability.ts

下一步