monorepo

脚本命令

该 monorepo 使用统一的脚本命名约定。

命令

命令	用途	适用时机
bun format	修复格式问题（biome）	开发
bun format:check	检查格式问题	CI
bun lint	修复 lint 问题（biome）	开发
bun lint:check	检查 lint 问题	CI
bun typecheck	类型检查（tsc、svelte-check、astro check）	两者均适用
bun test	运行单元测试（仅 *.test.ts）	两者均适用
bun bench	运行基准测试（*.bench.ts；生成报告，不做断言）	手动

约定

• 无后缀 = 修复（会修改文件）
• :check 后缀 = 仅检查（用于 CI，不做修改）
• 单独的 typecheck = 类型检查（单独处理，无法自动修复）
• test 仅运行 *.test.ts；bench 仅运行 *.bench.ts。一个文件只能 属于其中一种，不能两者皆是。基准测试会输出报告；测试会执行断言。

开发脚本

从仓库根目录启动应用，不要先 cd 进入应用目录。根目录的 bun dev:<app> 会运行应用所需的所有进程；对于会访问托管 API 的应用（honeycrisp、vocab、whispering 和 api dashboard），还会通过 bun run --filter 在 localhost:8787 启动 @epicenter/api。如果存在前后端拆分，根目录的 bun dev:<app>:ui 只运行应用的前端；对于 Tauri 应用，它会映射到包的 dev:web。bun dev:api 只运行后端。Local Books、Local Mail 和 Super Chat 有各自在 README 中说明的多进程流程； 它们没有根目录的 dev:* 目标。

在单个包内，约定如下：

非 Tauri 应用使用一个 dev 脚本，直接运行底层工具 （vite dev、astro dev、wrangler dev）。Tauri 桌面应用 （honeycrisp、whispering、matter）有两个开发入口，并明确命名：dev 会启动桌面外壳（指向 dev:desktop），dev:web 则单独运行 Vite；每个应用的 tauri.conf.json 都会通过 beforeDevCommand 调用它。后缀约定主要适用于数据库 命令：

脚本	含义
dev	默认的本地工作流。可能仍需登录 Infisical 才能获取应用密钥（例如 API 密钥），但运行时始终只访问本地基础设施。
dev:web	Tauri 应用：仅运行 Vite 开发服务器，不启动桌面外壳。由 tauri.conf.json 作为 beforeDevCommand 调用。
dev:desktop	Tauri 应用：启动原生桌面应用（tauri dev）。dev 指向此脚本。
db:*:local	使用本地 Postgres 运行。无需登录 Infisical。
db:*:remote	通过 infisical run --env=prod 包装运行。使用生产数据；请按管理员权限谨慎操作。

不存在 dev:remote。只能通过 :remote 数据库脚本和 deploy 访问生产数据，不能通过开发服务器访问。

完成代码修改后

运行类型检查进行验证：

bun typecheck

此命令会运行 bun run --filter '*' typecheck，在每个包中执行 typecheck 脚本（例如 tsc --noEmit、svelte-check）。

新建包的样板结构

在 packages/ 中创建新包时，请严格遵循以下结构。

package.json

{
  "name": "@epicenter/<package-name>",
  "version": "0.0.1",
  "exports": {
    ".": "./src/index.ts"
  },
  "license": "AGPL-3.0-or-later",
  "scripts": {
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {},
  "devDependencies": {
    "@types/bun": "catalog:",
    "typescript": "catalog:"
  }
}

主要约定：

• 只使用 exports，不使用 main/types：存在 exports 时，现代解析器会忽略 main/types。入口点为 ./src/index.ts；不需要构建步骤，使用方直接导入源代码。
• 内部依赖使用 "workspace:*"（例如 "@epicenter/workspace": "workspace:*"）。
• 共享版本使用 "catalog:"，由根目录 package.json 中的 catalogs 管理。
• 使用 peerDependencies 声明使用方也必须安装的包（例如 yjs）。
• license：默认使用 AGPL-3.0-or-later（Epicenter 发布或运行的所有内容）。仅当软件包旨在供第三方开发者嵌入自己的软件时（toolkit），才使用 MIT。参见 docs/licensing/licensing-strategy.md；如果某个 MIT 软件包可以依赖到 AGPL 软件包，bun run check:licenses 就会失败。

tsconfig.json

叶子配置选择一个层级，不添加与基础配置重复的内容。对于 Bun 库：

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "types": ["bun"],
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

Svelte 或浏览器库则扩展 ../../tsconfig.dom.json。有关全部八个叶子层级、禁止重新声明的列表以及模块策略，请参阅 tsconfig skill。

创建软件包后，从仓库根目录运行 bun install，将其注册到工作区。