【免费下载链接】ChatLabLocal-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具项目地址https://gitcode.com/gh_mirrors/cha/ChatLab点击查看免费下载ChatLab本地优先的 AI 聊天记录分析工具在仓库根目录维护了一份AGENTS.md它是人类开发者与 AI 协作者共同遵守的工程协作契约覆盖开发流程、实现原则、审查标准、项目地图、测试门槛、命令验证、日志规范、兼容迁移与提交规范等完整环节。本文以该文件为骨架结合公开开发指南 docs/cn/contributing/development.md 与仓库源码实现逐节解读每一条规则背后的工程动机与落地方式帮助贡献者快速建立正确的协作心智并掌握可复制的验证命令与安全红线。AGENTS.md 的定位人类与 AI 协作者的统一指令入口AGENTS.md不是一份普通说明文档而是面向协作场景的指令文件。公开开发指南明确写道使用 AI 协作时应让 AI 先读根目录的AGENTS.md再读开发指南页这样 AI 生成的补丁、测试与变更说明才能符合仓库既有的约定reviewer 也无需依赖私有上下文即可理解 PR。它同时划清了公开上下文与私有上下文的边界工作区若存在.docs/它是可选的个人或团队私有开发上下文可承载任务记录、决策、AI 协作记忆和临时规划但公开文档与公开 PR 不应依赖.docs/才能理解。也就是说任何提交到公开仓库的变更其设计理由、测试依据都必须能在公开文档中自证。开发流程先读文档、最小改动、快速回归AGENTS.md 将开发流程压缩为三条硬性要求文档先行开始开发前先阅读公开开发指南如果存在.docs/再阅读其中与需求相关的文档。目标收敛用最小改动快速交付正确、可维护、可回归的业务结果。验证闭环每次完成任务后按修改文件的类型和改动范围执行适用的类型检查、lint 和 formatlint 与 format 优先指定修改文件类型检查按相关项目执行。如果执行检查时发现与本次修改无关的报错也需要一并修复。最小改动体现在 AGENTS.md 的实现原则上选择满足当前已确认需求的最简单实现不为假设中的未来需求预先增加抽象层、配置项、扩展点或防御逻辑较大功能优先交付最小、可验证的端到端闭环再基于真实需求逐步扩展不要为了尚未实现的复杂度拆掉已经稳定工作的链路。实现原则与模块组织按真实边界划分优先复用AGENTS.md 对代码组织提出了三条可操作的准则按真实的业务边界、平台边界和变化原因组织模块没有独立职责、复用价值或独立变化需求的少量逻辑不要拆成单函数文件、薄封装或纯转发层。复用优先实现新能力前先检查仓库已有代码、组件、service 和已安装依赖能否复用确需新增能力时优先选择成熟且持续维护的库并评估包体积、跨端兼容性和维护成本。遵守依赖变更确认规则修改依赖、lockfile、构建产物、发布脚本、版本号、changelog、npm publish、release 流程时必须先获得明确确认。这与仓库的多端架构直接相关。ChatLab 同时维护 Electron 桌面端、CLI WebNode 后端 Web UI与 Web WASM纯浏览器运行三种运行形态共享业务逻辑优先落在packages/node-runtime/src/services/或packages/core/入口层只做薄适配。例如 架构边界一节 明确禁止在路由/IPC handler 中绕过 core 直接写 SQL平台差异通过 adapter 或 service 参数隔离保证前端拿到的数据结构一致。审查与判断以代码事实为准拒绝听起来对AGENTS.md 对代码审查尤其是 AI review给出了严格的证据要求这是整份文件最有工程深度的一部分核对事实再表态处理外部 review、bug 报告或架构建议时必须先核对代码事实再决定接受或反驳不要因为 reviewer 表达确定就直接改代码。完整上下文判断问题是否成立时至少阅读相关函数、调用方、被调用方、相邻测试和现有文档不能只看 diff 或单行评论。外部行为查官方来源涉及依赖、框架、OpenAI/LLM SDK、数据库、打包发布等外部行为优先查官方文档、源码或类型定义不凭记忆判断。结论必须可复现审查结论必须说明涉及的文件/函数、当前行为和判断依据问题成立时补充用户影响、建议修复方式以及已运行或应运行的验证。对于异步、并发、缓存、性能、外部依赖或资源异常类问题AGENTS.md 特别强调完整因果链与现实可达性不能只凭Promise 理论上可永久 pending竞态在抽象状态中存在或极端环境可能失败就判定为严重 Bug。严重度要同时考虑触发概率、用户影响和可恢复性高影响后果不能单独替代可达性证据。多轮 AI review 应按根因和关键假设聚合若新评论只是把同一未证实假设传播到下游且没有新的独立证据默认降低优先级并停止无限追深。项目地图六大目录模块与职责边界AGENTS.md 的项目地图一节是理解仓库的捷径结合 development.md 可以还原出完整结构路径职责src/共享前端应用代码页面、组件、状态、服务封装和 i18napps/desktop/Electron 主进程、preload、桌面端构建与平台能力适配apps/cli/CLI、HTTP API、CLI Web 运行时、导入命令和本地服务入口packages/core/平台无关的核心模型、查询、导入去重、图表和 AI 静态定义packages/node-runtime/Node.js 运行时能力SQLite 适配、数据库迁移、AI 管理、导出、缓存和数据目录packages/tools/AI 工具定义、工具 registry 和数据访问 providerpackages/parser/聊天导出格式解析器和格式识别packages/parser-native/napi-rs Rust 原生解析内核可选本地构建未构建时 parser 自动回退 TS 实现packages/http-routes/Electron 和 CLI Web 复用的 HTTP routedocs/公开文档站源码其中packages/parser/与packages/parser-native/的关系值得展开parser 采用标准层—嗅探层—解析层三层架构parser 入口 从./sniffer创建全局嗅探器并批量注册全部格式模块嗅探器实现 通过扩展名、文件头签名默认读取前 64KB、文件名签名、必需字段与字段值模式逐级匹配格式。原生内核是可选构建未构建时自动回退 TS 实现这一机制保证了不同安装环境下导入解析行为的一致性也解释了为什么apps/cli的 dev 流程里要先执行ensure-native。命令与验证一套可复制的检查矩阵AGENTS.md 给出了完整的验证命令清单按改动范围选择类型检查Node/CLI/Electron 主进程相关改动运行pnpm run type-check:node前端/Vue 相关改动运行pnpm run type-check:web跨端或发布前改动运行pnpm run type-check:all。Lint优先对修改文件运行pnpm exec eslint files...需要全量修复时再运行pnpm lint。Format优先对修改文件运行pnpm exec prettier --write files...大范围格式化才运行pnpm format。注意docs/**/*.md被 Prettier 默认忽略格式化这些文件要使用pnpm exec prettier --write --ignore-path .gitignore files...。单元/集成测试按改动范围优先运行相关测试使用pnpm test -- path/to/file.test.ts需要全量回归时运行pnpm test或pnpm run test:unit。文档修改公开文档或 VitePress 配置后运行pnpm docs:build只改.docs/私有任务文档时不需要构建公开文档站。E2E/Smokepnpm run test:e2e:launcher、pnpm run test:e2e:smoke和真实 LLM/真实 Electron/真实网络测试只在相关功能需要时运行不加入默认pnpm test。最后检查提交前运行git diff --check确认没有空白错误。这些命令都能在根目录 package.json 中找到对应脚本环境要求为 Node.js24 25、pnpm11 12见engines字段依赖通过pnpm install安装。workspace 由 pnpm-workspace.yaml 定义覆盖packages/**、apps/*与docs。测试门槛先说明防止哪种回归再写测试AGENTS.md 对测试有一套价值门槛体系核心判断是新增测试前必须先说明它防止哪一种用户可见回归测试应验证行为、数据或公开契约如果测试失败不能说明产品行为出错就不应该新增。必须新增回归测试修复真实的行为 Bug或修改用户数据、数据库迁移、导入解析、去重、权限认证、配置/API Key 迁移、公开 API、跨端共享 service 等高风险逻辑时应优先补充能在修改前失败的回归测试已有测试完整覆盖时不重复新增。通常不新增文案、样式、类型、日志、注释、文档、常量、简单 getter、文件列表和无行为变化的重构。此时只运行相关类型检查、lint、format、构建或现有测试。避免机械测试不要通过扫描源码字符串、匹配完整 SQL、断言私有函数调用顺序、锁定日志文案或枚举每个常量来证明功能正确。Mock 调用次数只用于 adapter 的参数传递或权限边界。提高信息密度同一规则的多个输入优先使用表驱动测试下层已覆盖算法时上层只验证调用链和返回契约。测试分层纯函数和参数规范化使用单元测试SQL、迁移、导入写库、Fastify route 和跨包 service 优先使用轻量真实依赖或临时数据库真实 Electron、浏览器、LLM 和网络只用于少量显式启用的 Smoke/E2E。测试位置模块单元测试放在被测文件附近跨模块、集成、E2E 和测试工具放在根目录tests/或对应 app/package 的既有测试目录。仓库的测试运行器 scripts/run-tests.mjs 实现了这一分层默认测试收集会排除tests/e2e/、/smoke/、.smoke.test.与.e2e.test.文件只保留*.test.*/*.spec.*的单元与集成测试并要求 Node.js 主版本为 24。代码规范平台术语、多语言与 i18n 复用AGENTS.md 用一节专门统一术语避免多端协作中的命名混乱内部交流、开发菜单和平台级代码统一使用CLI WebNode 后端 Web UI与Web WASM纯浏览器运行只说Web且上下文无法区分时默认指 Web WASM。浏览器 Worker、OPFS 和浏览器 adapter 等技术能力使用Browser Runtime命名它不是独立平台。多语言代码中的日志、注释、AI 工具描述、错误消息等非 UI 文本默认使用英文当有运行时 locale 可用时如工具返回结果、AI 看到的文本通过isChineseLocale(locale)等机制支持中英双语。数据清洗中与聊天平台格式匹配的标签如[分享]、[图片]保持原始语言不变。i18n 复用性新增 UI 文案 key 前先判断是否是通用动作、状态、提示或组件文案能复用的优先放在common.*等共享命名空间避免在具体业务模块如members.*、records.*重复定义同义 key。日志规范统一入口、关键路径与级别语义ChatLab 的日志体系在 AGENTS.md 中被明确约束为统一入口 分级记录 适度原则统一入口Node 侧Electron 主进程 / CLI / CLI Web统一使用openchatlab/node-runtime的appLogger前端使用 src/services/log-report.ts 上报提供reportError、reportRuntimeLog、installGlobalErrorReporting等能力。不要新建通用 logger 或直接写日志文件AI 使用AiLogger、导入性能使用perf-logger。关键路径启动、迁移、数据库或配置变更、导入、认证、外部调用和后台任务等用户可感知流程应记录必要的开始、完成和失败节点帮助判断流程停在哪一步及其原始错误但不要机械记录每个函数或分支。日志级别低频且有诊断价值的成功节点使用info操作最终失败或功能不可用使用error已有重试、降级或回退且流程仍可继续使用warn轮询、缓存和状态快照等高频诊断使用debug。记录异常时直接传入原始Error避免丢失 stack。适度原则不要在循环或高频热路径写info不得记录聊天明文、API Key、token 等敏感信息。不要为具体日志文案、级别或调用方式机械增加业务测试。统一日志实现 印证了这些约定AppLogger将日志写入logsDir/app.log达到 10MB 后轮转到app.old.log级别按 DEBUG INFO WARN ERROR 过滤error(scope, message, data)会自动提取 Error 的 name/message/stack。架构边界共享逻辑下沉入口层只做薄适配AGENTS.md 的架构边界规则可以概括为一句话维护 Electron 和 CLI Web 的共享业务逻辑时优先在packages/node-runtime/src/services/下实现禁止在路由/IPC handler 中绕过 core 直接写 SQL。展开来看不要在 Electron IPC handler 或 CLI HTTP route 中重复实现复杂业务流程。不要在入口层绕过packages/core/直接写成员合并、删除、别名更新等核心 SQL 写操作。平台差异通过 adapter 或 service 参数隔离保持前端获得的数据结构一致。新增会话、成员、索引、摘要、导出、导入相关能力时先确认能否复用或扩展共享 service。这一边界与packages/http-routes/的存在互相印证Electron 与 CLI Web 复用的 HTTP route 被抽成独立包业务逻辑集中在 node-runtime services两端入口只负责平台适配。数据目录兼容门禁多端共享 userDataDir 的安全红线AGENTS.md 中兼容与迁移一节最重要的机制是数据目录兼容门禁data directory compatibility gate。由于 Electron 桌面端、CLI Web 和 MCP 会共享同一个userDataDir一旦新版 runtime 修改了数据库 schema、AI 数据、认证配置或数据目录布局旧 runtime 继续读写同一目录就可能读错数据甚至破坏用户数据。因此凡是会让旧版本无法安全访问同一数据目录的变更都必须提升门禁。兼容标记文件是userDataDir/.chatlab-meta.json现有userDataDir/.chatlab仍只作为目录 marker不承载 JSON 配置。AGENTS.md 定义了以下硬性要求何时需要提升数据库 schema 迁移会删除、重命名或改变旧版本会访问的表/字段语义AI 对话、助手、技能、工具 allowlist、认证 profile、配置文件格式发生旧版本无法安全解析的变化userDataDir内目录布局变化导致旧版本读写错误位置跨端共享数据的 canonical 命名或结构发生不向后兼容变化。如果只是新增旧版本会忽略的可选字段或修复不影响旧版本读写的数据派生逻辑通常不需要提升。实现要求使用>CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR1该开关只允许绕过当前版本低于最低版本的阻断不能绕过损坏 JSON、非法字段或非法版本使用时必须打印明确警告源码中会输出 Continuing may risk data corruption 之类的警告信息并说明可能有数据损坏风险。对应的>赞分享【免费下载链接】ChatLabLocal-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具项目地址https://gitcode.com/gh_mirrors/cha/ChatLab点击查看免费下载相关推荐进程管理实战如何在ad编辑器中运行、追踪与终止外部命令进程管理实战如何在ad编辑器中运行、追踪与终止外部命令 对于终端用户来说编辑器内执行外部命令一直是效率的关键。 ad编辑器 an adaptable数据分析人工智能AI 应用AI Agent桌面应用CLIMCP 服务AI 技能本地部署ChatLab 开发指南多端架构、数据目录兼容门禁与贡献协作规范ChatLab 开发指南多端架构、数据目录兼容门禁与贡献协作规范 ChatLab 是一个本地优先Local first的 AI 聊天记录分析工具同时维护n8n-mcp 的 WEBHOOK_SECURITY_MODEstrict/moderate/permissive怎么选n8n mcp 的 WEBHOOK_SECURITY_MODEstrict/moderate/permissive怎么选 n8n mcp 的 WEBHOO数据分析人工智能AI 应用AI Agent桌面应用CLIMCP 服务AI 技能本地部署上一篇从安装到精通ComfyUI Workspace Manager让你告别工作流混乱的10个技巧下一篇IBAnimatable高级遮罩动画使用CAShapeLayer实现路径动画的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考