项目结构
熟悉 Kernlift 代码仓库,知道每一类改动应该放在哪里。
一个 Kernlift 项目就是一个仓库:应用本身、迁移、校验器、agent 技能、可选的 agent 服务,以及把它打包成模块的工具。本页说明各部分的位置。这样布局的原因见架构与分层。
准备工作
- 一个按快速开始克隆并安装好的项目。
顶层目录
src/ Web 应用(路由、组件、插件、服务端代码、文案)
packages/ workspace 包:beui(设计系统)、kernlift-skills,以及 agent-* 系列包
apps/agent-service/ 可选的 agent 服务,独立进程(agent-starter 模块)
drizzle/migrations/ 手工维护的迁移,每种方言一个目录:sqlite/ 和 postgres/
scripts/ db/、jobs/、validate/、registry/、assets/、skills/,以及 Node 与 Worker 冒烟测试
modules/ 每个模块一个 module.json,另有底座清单
skills/ 开发项目时使用的 agent 技能(quick-start、new-page、deploy 等)
agent-skills/ agent 自身运行的技能(agent-starter 模块)
tools/kernlift/ kernlift CLI 包
openspec/ 规格与变更提案(openspec/changes/)
docs/ 维护者笔记与设计参考
public/ 图标、分享图和占位素材
deploy.config.json 这份构建面向的平台、数据库以及是否带 agent
wrangler.jsonc Cloudflare Worker 入口与绑定(仅 Cloudflare 项目)
Dockerfile 其他平台运行的 Node 镜像
.env.example 源代码读取的全部环境变量项目只带自己所选平台的部署文件:Cloudflare 是 wrangler.jsonc,Fly.io 是 fly.toml,Railway 是 .railway/railway.ts,Docker 是 compose.yaml。kernlift deploy-target <platform> 负责在它们之间切换,并重写 deploy.config.json。你正在阅读的产品文档由商店项目发布,不在你的仓库里。
src/ 内部
routes/{-$locale}/ 页面;可选的语言段用于提供 /zh 路由
app.tsx, app/ 登录后的工作台(/app/*),在布局处统一守卫
admin.tsx, admin/ 管理后台(/admin/*),在布局处统一守卫
routes/api/ API 处理器,例如 /api/billing/*、/api/chat 和 /api/agent/*
components/ 按能力分组的 UI
motion/ 页面导入的 beUI 组件
admin/ 后台页面模式(记录列表、指标、面板、配置表单)
marketing/ 公开站:外壳、page-shell 原语、落地页、定价页
layout/ AppShell 与工作台侧边栏
plugins/ 后台插件:底座插件和每个模块各一个,以及它们填充的插槽
(admin.nav、app.nav、工作台首页卡片、账单页操作)
i18n/ locales/{en,zh}/messages.ts,以及按功能拆分的文案文件
config/site.ts 站点名称、规范 URL、描述和社交分享图
styles/app.css 挂在 :root 上、全站共用的产品令牌
server/
auth/ 唯一读取会话的代码:身份上下文、守卫、API 边界
functions/ 供路由和组件调用的服务端函数
services/ 跨能力的编排
db/repositories/ 所有数据库访问
db/schema/ sqlite.ts 与 postgres.ts,两种方言下相同的表
jobs/ 定时任务:runScheduledJobs() 和进程内循环
agent-host/ agent 在 Web 一侧的部分:可用性判断、传输、积分、存储
plugins/ 插件状态,以及插件贡献的 API 路由
platform/ 运行时能力:缓存后端、存储驱动、绑定、部署信息
server-entry.ts wrangler.jsonc 中指定的 Worker 入口
server-entry.node.ts Node 构建(pnpm build:node)的服务端入口服务端每一层只调用下一层,因此业务代码从不接触 SQL 方言。Web 应用不依赖 apps/agent-service 运行。没有部署它时,agent 入口会提示服务未部署。
改动放在哪里
| 你想要 | 修改 |
|---|---|
| 重命名产品 | src/config/site.ts 和 public/ 下的素材;见换成自己的品牌 |
| 替换首页 | src/components/marketing/example-landing.tsx;见替换落地页和定价页 |
| 修改配色或搭建页面 | src/styles/app.css 和 src/components/motion;见使用设计系统 |
| 修改或新增文案 | 同时修改 src/i18n/locales/en/messages.ts 和 src/i18n/locales/zh/messages.ts;见新增与修改文案 |
| 新增后台或工作台页面 | 在 src/routes/{-$locale}/admin/ 或 app/ 下新增路由,并在 src/plugins/foundation/plugin.ts 中加导航入口;见新增后台或工作台页面 |
| 接入服务商 | 不需要改代码:使用 /admin/config/*,见管理配置 |
| 新增数据库表 | 同时修改两个 schema 文件,再为每种方言各写一条迁移 |
| 新增周期性后台任务 | 在 src/server/jobs/scheduled.ts 中加一个任务;见后台任务 |
| 新增功能检查 | 在 scripts/validate/ 下新增校验器,并接入 pnpm validate:all |
| 新增模块 | 按 new-module 技能操作;见构建模块 |
服务商设置不要放进环境变量
环境变量只用于启动与基础设施。功能代码不读取 process.env,服务商凭据在管理后台配置。
验证
按下面的顺序运行每次改动完成前都要跑的检查:
pnpm typecheck。它需要由pnpm cf-typegen生成的worker-configuration.d.ts,以及最新的src/routeTree.gen.ts;路由有变化时,pnpm dev或pnpm build会重写后者。pnpm check。它会报告样式表中一些既有问题。不要为了消除它们在整个仓库上运行biome check --write --unsafe。pnpm validate:all。