安装与兼容性

安装一致的发布包组合，按需选择适配器，并匹配运行时与传输协议要求。

本站渲染器是 @lenso/docs@0.1.0，初始化器是 create-lenso-docs@0.1.0。两个精确版本均存在于正规 npm。它们是独立文档包，不选择 Lenso 运行时版本。

从已发布 Core 开始

快速开始使用 Bun 1.4.2 与真实发布产物：

1bun add --exact @lenso/core@0.2.0

保留一个 bun.lock。Core 本身即可启动普通服务，无需 Engine 或 Web。browser 入口提供安全声明/辅助能力，不包含 startApp 或浏览器服务运行时。此版本已导出配置、logger 契约和应用 instanceId。

只添加实际需要的入口。CLI 工具使用：

1bun add --dev --exact @lenso/cli@0.19.02bunx --no-install lenso help --json

Web 包与两端协议 peer 必须匹配：

1bun add --exact @lenso/web@0.2.0 @orpc/client@2.0.0-beta.42 @orpc/server@2.0.0-beta.42

安装 Web 不选择 ingress、认证或对象策略。Web、Auth、数据库与 Manage说明各自可选适配器与 peer 要求。

已核实的包版本组合

2026-10-08 已检查正规 npm metadata、精确 tarball、integrity、公开 exports 与源码声明，源码审计基线为 549b9870acb6af239faf79245179a4f1f7e60cdb。这些是实际发布产物，不是根据源码合并推断的发布承诺：

包	精确版本	主要边界
@lenso/core、@lenso/engine	0.2.0	运行时与构建期有独立生命周期
@lenso/cli	0.19.0	独立版本；可信应用模块与显式操作
@lenso/web、@lenso/auth、@lenso/workers	0.2.0	平台专用公开入口与显式 evidence
@lenso/db、@lenso/storage	0.1.1	消费 Core ^0.2.0；原生资源与迁移归应用所有
@lenso/tasks、@lenso/manage、@lenso/mcp	0.2.0	持久任务、有限操作、stdio 暴露是不同契约
@lenso/log、@lenso/otel	0.2.0	可选宿主日志/遥测；不提供 collector 或查询服务

API 索引与产物清单列出实际 exports、peer 与 integrity。oRPC 仍固定预发行 2.0.0-beta.42。当前 Drizzle 示例使用 ORM 0.45.3、Kit 0.31.11。遵守所选适配器声明的 peer；optional peer 表示消费对应入口时安装，不表示缺少 peer 仍可用。

旧 Core 0.1.0 没有 config 子路径；旧 Web 0.1.0 使用 oRPC 1.15.5，且没有 /bun。不要将这些旧产物混入本组合或与 v2 client 混用。CLI 没有 0.1.0 发布版。升级提供迁移检查。

运行维护中的真实示例

完整 Notes/Tasks 应用位于审阅过的源码 checkout，其 workspace 脚本需要已构建框架包。通过 npm 消费的独立应用无需这个 checkout。

1git clone https://github.com/LioRael/lenso.git lenso-examples2cd lenso-examples3git checkout 549b9870acb6af239faf79245179a4f1f7e60cdb4bun install --frozen-lockfile5bun run build6bun dev

使用 checkout 声明的 Bun 1.4.2。bun dev 在 loopback 启动 greeting 并输出真实 URL。Notes、Tasks 和 Workers 各有显式数据库、迁移、身份或 binding 前置条件；见示例。不要假设启动 greeting 会配置这些应用。

第二终端在同一 checkout 根目录运行：

1bun run cli inspect greeting greet --root examples/greeting --json2bun run cli call greeting greet '{"name":"Ada"}' --root examples/greeting --json

Inspect 导入可信配置但不执行应用 setup。Call 校验输入、启动整个应用、提供可信 operation binding 后停止。副作用与失败说明见 CLI。

平台兼容与底层手动使用

宿主	适合的入口	边界
Bun	Core、Engine/CLI、Bun DB/storage/listener、PostgreSQL task worker	已用 Bun 1.4.2 验证；宿主拥有进程监管
Workers	Core、Workers、D1、R2、Fetch	每请求图；不运行 Bun 文件系统/socket 或 Engine dev
Browser/React	type-only 契约、browser 声明、Web client	不将 DB provider、服务端 secret 或 startApp 打包到客户端
文档站	Node 26.10+、生成的 Next 应用	静态 out，独立于应用运行时

公开 exports 是 import 边界。Auth 导出迁移资产子路径。Storage、Tasks SQL 资产随包发货，但没有 migration export 子路径；Tasks 通过 /postgres 公开 migratePostgresTaskQueue。不要猜测深路径。迁移归属见 Files与 Tasks。

应用可以直接使用原生 Fetch、Drizzle、storage client 或 OpenTelemetry。Engine 约定与配置 source 可替换，无需强制 Web。维护中的模板目前使用 vendor 包归档；在新目录遵循其显式 packing 指引，不要假设存在应用创建命令。归档、override 与间接 Core/Engine 依赖保持一致，不替换 latest，不深引框架源码，不手抄框架实现。