【免费下载链接】ChatLabLocal-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具项目地址https://gitcode.com/gh_mirrors/cha/ChatLab点击查看免费下载本篇指南面向希望在 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字段开发环境要求严格锁定依赖版本范围Node.js24 25pnpm11 12安装全部依赖pnpm install仓库通过 pnpm-workspace.yaml 组织多个工作区包例如openchatlab/core、openchatlab/desktop、chatlab-cli、openchatlab/docs等。package.json中声明packageManager: pnpm11.21.0建议使用相同或更高的大版本保持一致。本地开发命令速查下表来自开发指南并核对根 package.json 的 scripts 定义是日常开发最常用的命令CommandPurposepnpm dev交互式选择 Desktop、CLI Web、Web WASM、API Server 或 docs 启动。实现见 scripts/dev-select.mjs上下箭头移动、回车确认并会把上次选择缓存在node_modules/.cache/dev-modepnpm dev:desktop以开发模式启动 Electron 桌面应用pnpm --filter openchatlab/desktop devpnpm dev:cli-web以开发模式启动 CLI WebNode 后端 Web UI默认访问http://127.0.0.1:3100/。注意该命令先执行ensure:server-native确保解析器原生模块可用pnpm dev:web-wasm启动 Web WASM纯浏览器运行时默认访问http://127.0.0.1:3130/pnpm docs:dev本地启动公开文档站VitePressopenchatlab/docspnpm build:desktop构建桌面应用pnpm build:cli-web构建 CLI Web UIpnpm build:web-wasm构建 Web WASMpnpm docs:build构建公开文档站pnpm run type-check:all同时运行 Web 与 Node 两侧类型检查内部依次执行type-check:web的vue-tsc和type-check:node的tscpnpm lint运行 ESLint 并自动修复eslint . --ext ... --fixpnpm format运行 Prettier 格式化全仓库开发指南给出的使用原则是小改动优先做针对性检查只检查你改动的文件或包跨模块、发版或架构级改动才运行更宽泛的检查。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 的项目地图和目录布局整理如下PathResponsibilitysrc/共享前端应用代码页面、组件、services、stores、i18nsrc/services/前端服务层封装 Electron、CLI Web API 与平台能力apps/desktop/Electron 主进程main/、preload、桌面端构建配置apps/cli/CLI、HTTP API、CLI Web 运行时与导入命令packages/core/平台无关数据模型、查询、导入、成员操作packages/node-runtime/Node.js 运行时服务SQLite 适配、数据库迁移、AI、导出、缓存、数据目录packages/tools/共享 AI 工具定义与数据访问适配器packages/parser/聊天导出格式解析与格式识别TS 实现packages/parser-native/napi-rs Rust 原生解析内核可选构建未构建时自动回退 TS 实现packages/http-routes/Electron 与 CLI Web 复用的 HTTP route 与错误映射docs/公开文档站源码VitePress配置见 docs/.vitepress/config.mtschangelogs/多语言 changelogcn/en/ja/tw供应用与发版使用.docs/可选的私有开发上下文公开贡献不依赖它常见改动入口速查开发指南提供的If you want to change → Start here表是定位代码的最快路径想改什么从哪里入手前端页面与组件src/pages/、src/components/图表分析src/components/analysis/、src/components/charts/数据、消息、会话相关 API 调用src/services/Electron 主进程apps/desktop/main/、apps/desktop/preload/CLI 与 Web APIapps/cli/共享业务逻辑packages/node-runtime/src/services/、packages/core/AI 工具与 Agentpackages/tools/、packages/node-runtime/src/ai/、src/services/ai*导入解析packages/core/、apps/cli/src/import/、src/services/import/文档站docs/、docs/.vitepress/config.mtsChangelogchangelogs/架构边界业务逻辑进共享层入口保持轻薄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.1prerelease 版本不能作为正式兼容版本。源码中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.tsApiErrorCode.DATA_DIR_INCOMPATIBLE映射到 409apiErrorFromUnknown会沿error.cause链查找DataDirCompatibilityError见 errors.test.ts 的映射测试与 server.test.ts 的 409 断言。隐藏的救援开关CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR1该环境变量只绕过当前运行时版本低于要求版本这一种情况必须不能绕过损坏的 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 compatibleCLI/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:webNode/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 guidescope 规则仅当改动是平台特有时才使用平台 scopeelectron、cli、web一般改动使用模块名作 scope。根 AGENTS.md 补充了分支规则功能需求开发前必须新建或切换到功能分支允许直接提交 main 的例外是发版工作流和.docs/私有文档仓库的日常维护。小结贡献 ChatLab 的五个要点环境与命令Node24 25、pnpm11 12小改动做针对性检查跨模块改动跑全量type-check:all、lint、pnpm test。术语统一CLI Web 与 Web WASM 是两个平台形态Web默认指 Web WASMBackend/API Server 仅指 Node 进程。架构纪律共享业务逻辑先进packages/node-runtime/src/services/或packages/core/入口保持轻薄禁止在 IPC/HTTP 路由绕过 core 写 SQL。数据安全任何让旧运行时无法安全读写userDataDir的变更必须通过.chatlab-meta.json兼容门禁用>赞分享【免费下载链接】ChatLabLocal-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具项目地址https://gitcode.com/gh_mirrors/cha/ChatLab点击查看免费下载相关推荐ChatLab 开发指南多端架构、数据目录兼容门禁与贡献协作规范ChatLab 开发指南多端架构、数据目录兼容门禁与贡献协作规范 ChatLab 是一个本地优先Local first的 AI 聊天记录分析工具同时维护Streamlit 贡献指南与实践从开发环境搭建到 CI 质量门禁的完整工程化手册Streamlit 贡献指南与实践从开发环境搭建到 CI 质量门禁的完整工程化手册 本文基于 Streamlit 官方仓库根目录的 CONTRIBUTING.数据可视化后端前端Flink CDC 贡献指南从环境搭建到代码评审的完整开发者手册Flink CDC 贡献指南从环境搭建到代码评审的完整开发者手册 Flink CDC 是一个由开放社区共同维护的流式数据集成工具本文基于官方文档 contr后端数据集成大数据流处理变更数据捕获数据同步创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考