模板与派生产品
仓库里的模块和模板产品有什么不同,业务模板是什么,以及如何在底座上只加一个插件,做出自己的产品。
这个项目里的一切都建立在同一个底座上。模块给它加一个功能,模板产品给它加一整种产品形态和自己的运行时,派生产品是你在底座上加一个自己的插件做出的产品。它们的区别决定了要部署什么,以及你自己的代码放在哪里。
模块还是模板产品
两者都已经在仓库里,各自由 modules/<key>/module.json 里的清单描述。kind 字段说明它是哪一种。
| 模块 | 模板产品 | |
|---|---|---|
module.json 里的 kind | module | template |
| 增加什么 | 一个功能:页面、服务端代码、自己的表、文案和一个校验器 | 一种产品形态:工作区包、第二个进程、一个运行时,以及这个运行时需要的表和设置 |
| 仓库里的例子 | cms、newsletter、affiliate、image-agent | agent-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.fulfilment | agent.host、agent.workbench,可选 api.routes |
| 交互方式 | 一个表单和一个结果 | 一段对话:读者描述、修改,结果直接出现在消息里 |
| 数据库 | 任何受支持的数据库,包括 Cloudflare D1 | Postgres,或 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覆盖。