项目结构

熟悉 Kernlift 代码仓库,知道每一类改动应该放在哪里。

一个 Kernlift 项目就是一个仓库:应用本身、迁移、校验器、agent 技能、可选的 agent 服务,以及把它打包成模块的工具。本页说明各部分的位置。这样布局的原因见架构与分层。

准备工作

顶层目录

my-saas/
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/ 内部

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,服务商凭据在管理后台配置。

验证

按下面的顺序运行每次改动完成前都要跑的检查:

  1. pnpm typecheck。它需要由 pnpm cf-typegen 生成的 worker-configuration.d.ts,以及最新的 src/routeTree.gen.ts;路由有变化时,pnpm dev 或 pnpm build 会重写后者。
  2. pnpm check。它会报告样式表中一些既有问题。不要为了消除它们在整个仓库上运行 biome check --write --unsafe。
  3. pnpm validate:all。

下一步