企业官网建设流程全解析

本篇指南面向希望在 ChatLab 仓库中修改代码、提交 Pull Request 的贡献者，系统讲解本地环境要求、开发命令、平台术语、仓库结构与架构边界，并重点剖析数据目录兼容门禁（Data Directory Compatibility Gate）的实现原理与源码佐证。读完本文，你将掌握 ChatLab 多端（Electron 桌面端、CLI Web、Web WASM）工程的日常开发流程、改动入口定位方法，以及如何在不破坏旧版本用户数据的前提下安全提交涉及数据库迁移、配置与数据布局的变更。

先读这一页：公开协作基线

ChatLab 将公开开发指南与私有开发上下文做了明确区分：

• 开始贡献前，先阅读公开开发指南（即本文所在的docs/en/contributing/development.md，以及对应的中文版 docs/cn/contributing/development.md），了解公开协作的基线约定。
• 使用 AI 辅助贡献时，要求 AI 先读取仓库根目录的 AGENTS.md 和本页内容。根目录的 AGENTS.md 是仓库级协作规范（实现原则、审查判断、测试门槛、命令与验证、代码规范、日志、架构边界、兼容迁移、安全发布、提交规范），而本开发指南承载更细的架构说明，两者在根AGENTS.md中明确约定"更细的架构说明继续以docs/cn/contributing/development.md为准"，不重复维护。
• 如果工作区存在.docs/目录，可以阅读其中的.docs/README.md和相关文件。.docs/是个人或团队可选的私有开发上下文，可存放任务、决策、AI 协作记忆和临时计划；公开文档与公开 PR 不应依赖.docs/才能被理解——变更理由、测试推理和设计假设不能只写在私有.docs/文件中。

环境要求与依赖安装

ChatLab 使用 pnpm 管理 monorepo 工作区（见根目录 package.json 的engines字段），开发环境要求严格锁定：

安装全部依赖：

pnpm install

仓库通过 pnpm-workspace.yaml 组织多个工作区包，例如@openchatlab/core、@openchatlab/desktop、chatlab-cli、@openchatlab/docs等。package.json中声明packageManager: pnpm@11.21.0，建议使用相同或更高的大版本保持一致。

本地开发命令速查

下表来自开发指南并核对根 package.json 的 scripts 定义，是日常开发最常用的命令：

开发指南给出的使用原则是：小改动优先做针对性检查（只检查你改动的文件或包），跨模块、发版或架构级改动才运行更宽泛的检查。pnpm dev的交互式选择器在 scripts/dev-select.mjs 中支持 Desktop、CLI Web、API Server（仅 CLI Web 后端）、Web WASM、Docs 五种模式，其中 API Server 对应pnpm run dev:serve（脚本为bash scripts/dev-serve.sh）。

平台术语：先统一概念再写代码

开发指南专门定义了一套平台术语，避免跨端协作时产生歧义（根 AGENTS.md 也重申了这套命名规则）：

• CLI Web：通过clb web运行，包含 Node.js 后端 + Web UI，是"带后端的 Web"形态。
• Web WASM：没有 Node.js 后端，解析、存储、查询全部在浏览器内完成。
• Web：统称。当上下文无法区分平台时，默认指 Web WASM。
• Backend / API Server：仅指 Node.js 进程本身，不是完整的 CLI Web 平台。
• Browser Runtime：仅指技术能力集合（Workers、OPFS、SQLite WASM、浏览器 adapter 等），不是另一个平台名称。

平台命名规则约束到代码层：内部交流、开发菜单和平台级代码统一使用CLI Web与Web WASM两个词；只说Web且无法区分时默认 Web WASM。

仓库结构：一眼定位改动落点

开发指南给出了顶层目录职责表，结合实际仓库（见根目录 AGENTS.md 的"项目地图"和目录布局）整理如下：

常见改动入口速查

开发指南提供的"If you want to change → Start here"表是定位代码的最快路径：

架构边界：业务逻辑进共享层，入口保持轻薄

ChatLab 同时维护 Electron 桌面端、CLI Web 与 Web WASM 三端。开发指南明确了共享业务逻辑的放置原则：

• 先在packages/node-runtime/src/services/或packages/core/落地共享业务逻辑，入口保持轻薄。
• 不要在 Electron IPC handler 或 CLI HTTP route 里重复复杂的业务流——例如成员合并、删除、别名更新等核心 SQL 操作，禁止在入口绕过packages/core/直接写 SQL。
• 通过 adapter 或 service options 隔离平台差异，返回给前端的数据结构保持一致。
• 新增会话、成员、索引、摘要、导出或导入行为时，先检查现有共享 service 能否复用或扩展。

这一约束在 AGENTS.md 的"架构边界"一节同样出现：维护 Electron 和 CLI Web 的共享业务逻辑时，优先在packages/node-runtime/src/services/实现，禁止在路由/IPC handler 中绕过 core 直接写 SQL。从源码结构看，packages/node-runtime/src/services/（102 个 TS 文件）正是跨端复用的核心服务层，而apps/cli/src/http/、apps/desktop/main/均作为入口消费这些服务。

数据目录兼容门禁：多端共享 userDataDir 的安全闸门

这是本开发指南技术含量最高的部分。Electron 桌面端、CLI Web 和 MCP 可能共享同一个userDataDir。如果新版本运行时改变了数据库 schema、AI 数据、auth 配置或数据目录布局，旧版本运行时可能读到错误数据甚至损坏用户数据。因此，任何让旧版本运行时无法安全读写同一数据目录的变更，都必须经过"数据目录兼容门禁"。

兼容元数据文件

兼容元数据文件位于：

<userDataDir>/.chatlab-meta.json

原有的<userDataDir>/.chatlab文件继续仅作为目录标记（directory marker），不应被改造成 JSON。

何时必须提升门禁

通常需要提升minRuntimeVersion的情况：

• 数据库迁移删除、重命名或改变了旧版本可访问的表/列的语义；
• AI 聊天、assistant、skills、工具 allowlist、auth profiles 或配置文件发生了旧版本无法安全解析的变化；
• userDataDir布局变化导致旧版本会读写错误位置；
• 共享的跨运行时数据在 canonical 名称或结构上发生了不向后兼容的变化。

反之，新增旧版本能安全忽略的可选字段，或只修改可再生（regenerable）的派生数据，通常不需要提升门禁。

从源码可以印证"迁移驱动门禁"的机制：packages/node-runtime/src/migrations/chat-db-migrations.ts中定义了CHAT_DB_COMPATIBILITY_RAISES，当前条目把 schema 迁移版本 6 关联到minRuntimeVersion: '0.25.1'、dataCompatibilityVersion: 1、reason 为segment-schema；注释还特别说明 Migration 9 刻意不提升门禁——因为 0.34.2 起派生 FTS 表已被视为可选，搜索回退到 LIKE、增量写入器会跳过缺失表。

实现规则

• 使用packages/node-runtime/src/data-dir-compat.ts中的工具函数（assertDataDirCompatible、raiseDataDirMinRuntimeVersion、readDataDirCompatibilityMeta等），不要在入口手写 JSON 读写或 semver 比较。
• CLI、MCP、Desktop 启动时必须检查兼容性；DatabaseManager在打开数据库前也会检查（packages/node-runtime/src/database-manager.ts中的assertCompatible()），这样长期运行的过期服务能及时发现其他更新的运行时已提升门禁。
• 提升门禁的迁移只在迁移真正成功后写入.chatlab-meta.json；如果写 meta 文件失败，启动或打开数据库必须中止，不能继续对外服务。源码中raiseDataDirMinRuntimeVersion通过临时文件 +renameSync原子写入（writeMetaAtomic），测试data-dir-compat.test.ts也验证了替换失败时保留原元数据、目录中不残留临时文件。
• minRuntimeVersion必须是稳定 semver（如0.25.1）；prerelease 版本不能作为正式兼容版本。源码中isStableSemver使用/^\d+\.\d+\.\d+$/校验，而当前运行时的 prerelease 版本（如0.26.4-beta.1）会被normalizeRuntimeStableVersion归一化为稳定 core 版本后再比较；0.0.0带 prerelease 的版本会被拒绝。
• 门禁只能提高不能降低：若已有 meta 文件要求更高版本，则保留更高要求。源码中raiseDataDirMinRuntimeVersion对已有更高minRuntimeVersion或更高dataCompatibilityVersion的 meta 直接复用/取最大值，测试data-dir-compat.test.ts的"raising minRuntimeVersion writes atomically and never lowers existing requirements"验证了这一点。
• reasons需要合并去重，便于将来调试定位是哪次迁移提升了门禁（源码中mergeReasons使用Set去重，测试验证 reasons 数组为['future-schema', 'segment-schema']）。
• HTTP route 遇到数据目录兼容错误时返回DATA_DIR_INCOMPATIBLE且 HTTP 409，而不是通用 500。对应实现在 packages/http-routes/src/errors.ts：ApiErrorCode.DATA_DIR_INCOMPATIBLE映射到 409，apiErrorFromUnknown会沿error.cause链查找DataDirCompatibilityError（见 errors.test.ts 的映射测试与 server.test.ts 的 409 断言）。

隐藏的救援开关

CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR=1

该环境变量只绕过"当前运行时版本低于要求版本"这一种情况，必须不能绕过：损坏的 JSON、非法字段或非法版本。使用时运行时必须打印清晰的、关于数据损坏风险的警告。源码assertDataDirCompatible中该开关通过env.CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR === '1'生效并调用warn输出告警；测试override bypasses only version insufficiency and emits a warning验证警告包含0.25.0、0.25.1与数据目录路径，而override does not bypass malformed current runtime versions、broken JSON and invalid meta are blocked even with override验证了开关的能力边界。

兼容门禁的测试要求

兼容相关改动应覆盖以下场景（这些均在packages/node-runtime/src/data-dir-compat.test.ts中有对应用例）：

• 从上一个稳定版本及更早的已发布版本升级且数据不丢失；
• 缺失.chatlab-meta.json时旧数据目录可以正常启动（测试：missing data dir compatibility meta is compatible）；
• CLI/Desktop/MCP 或DatabaseManager在当前运行时低于minRuntimeVersion时阻止启动（测试：current runtime below minRuntimeVersion is blocked、prerelease current runtime is compared by its stable core version）；
• 成功的迁移写入或合并minRuntimeVersion、dataCompatibilityVersion、reasons；
• 已有的更高minRuntimeVersion不被降低；
• HTTP route 将兼容失败映射为DATA_DIR_INCOMPATIBLE。

测试与检查策略

开发指南对测试范围的分层要求很明确，与根 AGENTS.md 的"测试"原则一致：

• 修改 TypeScript/Vue 代码后，至少运行相关的类型检查（前端用pnpm run type-check:web，Node/CLI/Electron 主进程用pnpm run type-check:node，跨端或发版前用pnpm run type-check:all）。
• 修改公开文档后运行pnpm docs:build或对改动文件做针对性格式化检查（docs/**/*.md默认被 Prettier 忽略，需使用--ignore-path .gitignore显式格式化）。
• 修改共享跨平台逻辑后，确认 Electron 与 CLI Web 入口行为不产生分歧。
• 日常默认测试命令是pnpm test（根目录 scripts/run-tests.mjs）；想优先跑相关测试用pnpm test -- path/to/file.test.ts。
• pnpm test只包含单元/集成测试，不得依赖真实 LLM、真实 Electron、真实浏览器、真实网络或长时间运行的 E2E。真实环境的 Smoke/E2E（如test:e2e:launcher、test:e2e:smoke）只在相关功能需要时显式运行。
• 与单一业务模块紧耦合的单元测试放在被测文件旁，命名*.test.ts/*.test.js；跨模块、集成、E2E、测试工具或归属不明的测试放在根目录tests/。
• SQL 行为、数据库迁移、Fastify 路由、跨包服务应优先用轻量内存 SQLite 或临时文件 fixture 跑真实行为；adapter 层测试聚焦参数传递、权限过滤、错误映射与响应契约，不要重复下层算法矩阵。这一策略在数据目录兼容门禁测试中体现得很典型：data-dir-compat.test.ts用mkdtempSync建临时目录、用临时文件模拟 meta 文件来跑真实读写路径。

i18n 与文案规范

修改 UI 文案时，简体中文、英文、日文、繁体中文四种翻译必须同步更新（对应src/i18n/locales/zh-CN、en-US、ja-JP、zh-TW四个目录）。日志、代码注释、AI 工具描述、错误消息等非 UI 文本默认使用英文；当运行时 locale 可用时，支持中英双语响应。根 AGENTS.md 补充了 i18n 复用性规则：新增 UI 文案 key 前先判断是否为通用动作/状态/提示文案，能复用的优先放common.*共享命名空间，避免在业务模块命名空间重复定义同义 key。

用 AI 辅助贡献的正确姿势

AI 可以帮助读代码、起草补丁、补充测试，但公开 PR 必须能在公开上下文中被理解：

• 要求 AI 先读取根 AGENTS.md 与本开发指南；
• 如果维护自己的.docs/，可以把它作为额外上下文，但不要把变更理由、测试推理或设计假设只留在私有.docs/文件中。

PR 与提交规范

• 明显的 Bug 修复可以直接提交；
• 新功能先开 Issue 讨论，未讨论直接提交的功能 PR 可能被关闭；
• 使用Conventional Commits，例如fix(import): handle empty source或docs: add contributor guide；
• scope 规则：仅当改动是平台特有时才使用平台 scope（electron、cli、web），一般改动使用模块名作 scope。根 AGENTS.md 补充了分支规则：功能需求开发前必须新建或切换到功能分支，允许直接提交 main 的例外是发版工作流和.docs/私有文档仓库的日常维护。

小结：贡献 ChatLab 的五个要点

1. 环境与命令：Node>=24 <25、pnpm>=11 <12，小改动做针对性检查，跨模块改动跑全量type-check:all、lint、pnpm test。
2. 术语统一：CLI Web 与 Web WASM 是两个平台形态，Web默认指 Web WASM，Backend/API Server 仅指 Node 进程。
3. 架构纪律：共享业务逻辑先进packages/node-runtime/src/services/或packages/core/，入口保持轻薄，禁止在 IPC/HTTP 路由绕过 core 写 SQL。
4. 数据安全：任何让旧运行时无法安全读写userDataDir的变更必须通过.chatlab-meta.json兼容门禁，用>赞分享

• ChatLab 开发指南：多端架构、数据目录兼容门禁与贡献协作规范

  ChatLab 开发指南：多端架构、数据目录兼容门禁与贡献协作规范 ChatLab 是一个本地优先（Local first）的 AI 聊天记录分析工具，同时维护

• Streamlit 贡献指南与实践：从开发环境搭建到 CI 质量门禁的完整工程化手册

  Streamlit 贡献指南与实践：从开发环境搭建到 CI 质量门禁的完整工程化手册 本文基于 Streamlit 官方仓库根目录的 CONTRIBUTING.

  数据可视化后端前端

• Flink CDC 贡献指南：从环境搭建到代码评审的完整开发者手册

  Flink CDC 贡献指南：从环境搭建到代码评审的完整开发者手册 Flink CDC 是一个由开放社区共同维护的流式数据集成工具，本文基于官方文档 contr

  后端数据集成大数据流处理变更数据捕获数据同步