人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载Cherry Studio 是一个基于 Electron 的多 LLM 提供商桌面客户端其仓库根目录的 AGENTS.md 是面向 AI 编码代理Agent和协作者的一整套工程协作约定它规定了编码心智、提交纪律、测试哲学、目录结构与数据系统选型并链接到docs/references/下数十份权威文档。本文以 AGENTS.md 为骨架结合仓库源码与配置文件逐条展开帮助读者快速建立对 Cherry Studio 工程规范、工具链与架构决策的全局认知并能在参与开发时按同一套约定提交高质量代码。编码心智先思考、求简单、做外科手术式修改AGENTS.md 的第一部分 Guiding Principles 定义了四条编码心智它们决定了仓库里每一行代码的产出方式。Think Before Coding先思考再编码显式陈述假设不确定就先提问再实现存在多种解释时全部摊开不要默默选一个存在更简单的方案就直说必要时反驳有任何不清楚的地方就停下来指出困惑点并提问。Simplicity First简单优先只写解决当下问题的最小代码不做投机性扩展不为单次使用场景引入抽象不加未被要求的灵活性和可配置性不处理不可能发生的错误场景写了 200 行但 50 行就能解决就重写行内注释上限 2 行——注释超过 2 行说明实现本身就是补丁应该修复实现而不是叙述实现注释只说为什么从不复述是什么禁止 changelog、理由小作文和粘贴聊天/评审回复。唯一豁免是导出 API 的文档注释TSDocparam/returns/deprecated它们属于文档而非叙述。Surgical Changes外科手术式修改只触碰任务要求的代码不顺手改进相邻代码、注释或格式不重构没坏的东西即使你会有不同写法也要匹配现有风格发现无关的死代码只提一句不要删除但你自己的改动产生的孤儿 import/变量/函数必须清掉每一处改动都必须能直接追溯到用户请求。Goal-Driven Execution目标驱动执行把任务先转化为可验证的目标再动手加校验 → 为非法输入写测试然后让测试通过修 Bug → 写一个能复现它的测试然后让它通过重构 X → 重构前后都确保测试通过。多步任务要给出带验证点的简短计划1. [Step] → verify: [check] 2. [Step] → verify: [check]这套先测试后实现的思路与仓库的测试哲学一脉相承见下文测试规范。操作规则一条条可执行的仓库纪律Operational Rules 是把心智落到仓库的具体规则其中几条与源码强绑定先读本地 README在改动一个目录前先读该目录及父目录的README.md——这些文件记录了纯代码看不出的本地约定、不变式和入口点。仓库中src/main/core/lifecycle/README.md、src/main/core/paths/README.md、tests/__mocks__/README.md都是这样的存在。修上游不 hack 下游新功能撞上现有模块的局限时先向上游提出改进方案供用户决策再考虑下游 workaround。库优先自定义最后写自定义代码前先查库/框架文档是否有内置方案。UI 统一用 Shadcn Tailwind所有新 UI 组件都取自packages/ui下的cherrystudio/uiShadcn UI Tailwind CSS。日志集中所有日志走loggerService并带正确上下文禁止console.log。路径集中主进程所有文件系统路径都通过application.getPath(namespace.key, filename?)获取禁止直接调用app.getPath()、os.homedir()或临时拼路径单例通过import { application } from application导入。只检查自己改动的范围代码改动跑pnpm lint含 format typecheck i18n:check加上覆盖你改动的测试纯文档改动只需pnpm docs:check。Conventional Commits小而聚焦的提交scope 必须是具体的 kebab-case 模块如feat(data-api):、fix(lifecycle):、docs(testing):禁止宽泛的main——即使git log历史与这条规则冲突规则优先。签名提交每个提交都必须加密签名且带 DCO sign-off使用git commit -S --signoff不能只用--signoff并用git cat-file commit HEAD验证提交对象含gpgsig头。分支策略main是所有活跃开发的默认分支特性、重构、优化和修复都合入这里。开发命令速查pnpm 脚本矩阵与验证门禁AGENTS.md 要求先pnpm installNode 与 pnpm 版本在 package.json 的engines和packageManager字段钉死node 24.11.1 24.16.0、pnpm11.8.0其余脚本以package.json为准。必须掌握的脚本如下命令作用pnpm lintoxlint eslint fix typecheck i18n check format会写文件pnpm test跑全部 Vitest 测试按 main / renderer / aiCore / ui / shared / provider-registry / scripts / preload 分项目串行执行pnpm formatBiome format lint写模式pnpm docs:check文档门禁check-links 结构 closed-set frontmatter/sources存在性 生成索引新鲜度build:check相比linttest多出的就是它pnpm build:checklintdocs:check 全部test即一键跑完整门禁pnpm test:lintCI 等价 lint 门禁拒绝pnpm lint/build:check会静默容忍的 oxlint warning针对窄范围改动AGENTS.md 明确提示永远不要用pnpm test path——该脚本内部用串联多个 vitest 调用CLI 参数只会到达最后一个调用前面的项目会不加过滤地跑完整套件。正确做法是使用按项目包装的脚本pnpm test:main file、test:renderer、test:aicore、test:shared、test:pkg:ui、test:scripts或pnpm exec vitest run file跑少数文件。文档改动方面有个细节docs/references/**和docs/contrib/**下的文档带description/sourcesfrontmatterdocs/README.md 是生成的索引编辑 frontmatter 后要跑pnpm docs:index绝不能手改索引。此外若build:check挂在 i18n 排序上先跑pnpm i18n:sync挂在格式上先跑pnpm format挂在文档链接上就修链接。测试规范契约断言而非行为快照测试统一跑在 Vitest 3 上见各vitest.config.*。AGENTS.md 对测试提出了一条旗帜鲜明的红线禁止行为固定behavior-pinning测试——一个测试如果断言只是记录当前代码行为快照输出、mock 上的toHaveBeenCalled、按实现方式反推的期望值就没有价值它不会因真实原因失败、每次重构都会碎、还会把现有 Bug 认证成预期。要断言契约真实输入 → 特性承诺的结果外加失败与边界情况。写测试前先说出它能抓住的 Bug说不出就别写。另外三条具体规定前端测试必读 Frontend Testing Guidelines。统一 mock使用 tests/mocks/README.md 描述的统一 mock 系统禁止为application、服务或数据层临时造 ad-hoc mock。该目录按进程组织renderer 侧有CacheService、DataApiService、PreferenceService、useDataApi、usePreference、useCache的 mockmain 侧有application统一工厂、DbService、CacheService、DataApiService、PreferenceService分别经 tests/renderer.setup.ts 和 tests/main.setup.ts 全局配置并通过test-mocks/*别名导入。数据库测试任何读写 SQLite 的服务/处理器/seeder 都用test-helpers/db的setupTestDatabase()——它提供带生产迁移的真实文件数据库禁止手写CREATE TABLE、覆盖application或 stub Drizzle 链详见 database-testing.md。mock 系统还复刻了主进程容器语义application.getOptional(Name)对常规服务会抛错所有默认 mock 服务都是非条件服务未知名字返回undefined以此抓住不该从get()回退到getOptional()的代码若get/getOptional的选择是承重逻辑则要求补真实ServiceContainer冒烟测试参考 dataApiDataChange.container.test.ts。补丁依赖升级前先查 patches/仓库对一批依赖打了自定义补丁集中在 patches/ 目录如ai-sdk__anthropic.patch、ai6.0.185.patch、tiptap__markdown3.26.1.patch、onnxruntime-node1.25.1.patch等。AGENTS.md 明确规定升级任何依赖前先检查patches/下是否有针对它的补丁避免升级把补丁内容冲掉。GitHub 工作流skill 驱动与轻量评审PR使用gh-create-prskill兜底直接读 .agents/skills/gh-create-pr/SKILL.md。Code Review评审别人的 PR 时不要在本地跑pnpm lint/pnpm test/pnpm format——CI 已经跑过了用gh直接检查即可。Issues使用gh-create-issueskill兜底读 .agents/skills/gh-create-issue/SKILL.md。这套流程与签名 sign-off 提交配合保证合入main的每笔变更都可审计。编码约定从类型分层到 i18nTypeScript 分层跨进程类型放src/shared/仅渲染进程使用的共享类型放src/renderer/types/依据是 Shared Layer Architecture。命名规范AGENTS.md 将 docs/references/architecture/naming-conventions.md 标记为MUST READ。这份权威文档版本 1.1覆盖文件、目录、标识符与单复数规则核心要点包括业务 React 组件文件PascalCase.tsxpackages/ui/下 shadcn 组件kebab-case.tsxHook 文件useXxx.ts工具函数文件camelCase.ts类即默认导出的文件用PascalCase.ts如KnowledgeService.ts、WindowManager.ts桶目录bucket用 camelCase 复数名词services/、utils/、hooks/业务/领域模块用 camelCase 单数命名一致性优先于风格偏好跨平台大小写安全禁止同目录Foo.ts与foo.ts并存该规则由eslint.config.mjs内联的naming/path-case插件在pnpm lint/test:lint/ci:basic-check中以 error 级别强制。日志AGENTS.md 给出标准用法import { loggerService } from logger; const logger loggerService.withContext(moduleName); // Renderer only: loggerService.initWindowSource(windowName) first logger.info(message, CONTEXT); logger.warn(message); logger.error(message, error);其实现位于 src/main/core/logger/LoggerService.ts基于 winston winston-daily-rotate-file日志目录来自src/main/core/paths/constants.ts的LOGS_DIR与BootConfigService、pathRegistry共用同一真源开发/诊断模式下默认级别为SILLY生产默认INFO。该类只允许在主进程实例化worker 线程直接抛错。路径AGENTS.md 将 src/main/core/paths/README.md 标记为MUST READ。主进程所有文件系统路径统一在pathRegistry.ts注册通过application.getPath()访问import { application } from application const dir application.getPath(feature.files.data) // /Users/alice/Library/Application Support/CherryStudio/Data/Files const file application.getPath(feature.files.data, avatar.png) // .../Data/Files/avatar.png关键机制命名空间cherry.*通用基础设施、sys.*系统目录、app.*Electron 应用目录、feature.*Cherry 自有功能数据默认选择、v1.*仅清理用旧路径、external.*第三方路径只读不删。键格式/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)$/至少两段、每段字母开头、多词段用 snake_case由 ESLint 强制。文件 vs 目录目录键无后缀独立文件键用_file后缀有兄弟键的文件用.file结尾段。目录键绝不能以file结尾——auto-ensure 靠它区分。auto-ensuregetPath()首次访问自动建目录目录键mkdirSync递归文件键只建dirnameNO_ENSURE列表中的键如sys.、external.前缀或个别精确键跳过防止只读/第三方/清理目标被查找动作意外物化。.分隔符是语义而非物理路径feature.mcp.oauth实际在~/.cherrystudio/config/mcp/oauth下不能从键名推断磁盘嵌套一律查pathRegistry.ts。文件名第二参数会校验绝对路径、..、分隔符都会告警。i18n所有用户可见字符串必须走i18next禁止硬编码 UI 文案语言包在src/renderer/i18n/locales/与src/main/i18n/locales/都以en-us.json为真源新增/修改 key 时只编辑en-us.json然后跑pnpm i18n:sync其他语言填[to be translated]:占位符再逐条翻译pnpm lint内置了i18n:check会拒绝残留占位符、空值、插值/标签不匹配和未排序的 key。UI 设计任何 UI 组件或页面样式工作前先读 DESIGN.md严格遵循其中的颜色、字体、间距与组件规格。架构地图代码组织、数据系统与生命周期代码组织closed set 与 barrelAGENTS.md 规定每个进程根目录的顶层是封闭集合closed set新代码必须归入既有类别禁止新建顶层目录。目录的index.ts是barrel——强制封装边界只 re-export 一个内聚的公共 API内部私有、外部经 barrel 导入禁止export *、禁止嵌套 barrel只有当 lint 能封死深导入时才建 barrel否则不要。index.tsx永远被禁止见 Naming Conventions §6.4。三个进程的架构文档分别为Main Process Architecture——src/main/下的core/ipc/data/ai/features/services/utils/i18n及依赖方向Renderer Architecture——src/renderer/的类型 × 领域双轴布局与仅向下分层Shared Layer Architecture——shared放什么跨进程 无可变运行时状态及其封闭顶层集合。数据系统四子系统选型表AGENTS.md 把 docs/references/data/README.md 列为MUST READ并给出选型总表系统用途APIBootConfig早期启动设置生命周期前bootConfigService.get()、usePreference(BootConfig.*)Cache临时数据可丢失useCache、useSharedCache、useSharedCacheValue、usePersistCachePreference用户设置usePreferenceDataApi业务数据关键useQuery、useMutation范围边界BootConfig同步文件式生命周期前在主进程直读其余经usePreference(BootConfig.*)Cache内存 / 共享跨窗口/ 持久化三层内存与共享在主进程和渲染进程都有持久化两边是相互独立的存储渲染进程 localStorage主进程 {userData}/cache.jsonJSON 文件主进程额外在窗口间中继渲染进程的持久化同步Preference跨进程主 渲染窗口间自动同步DataApiSQLite 支撑无自动同步渲染进程按需拉取。数据库为better-sqlite3 Drizzle ORM驱动是同步的查询与事务内联执行、无await因此getDb()查询和withWriteTx(fn)回调必须同步书写schema 在src/main/data/db/schemas/迁移用pnpm db:migrations:generate生成。写原子性多写或读后写要全部提交或全部回滚时用application.get(DbService).withWriteTx(fn)单个BEGIN IMMEDIATE同步事务单条写不需要——better-sqlite3 在单连接上每条语句本身原子。DataApi 边界规则DataApi 只服务 SQLite 支撑的业务数据没有数据库表就没有 DataApi 端点否则走 IPC见 api-design-guidelines.md 的 Scope Boundaries 小节。IPCIpcApiAGENTS.md 把 docs/references/ipc/README.md 列为MUST READ。非数据类命令 IPC窗口/系统/Shell/通知/外部/文件走IpcApi——它是与 BootConfig/Cache/Preference/DataApi 并列的第五个子系统基于 RPC-over-IPC 的单点 schemaschema handler加路由ipcApi.request(namespace.action, input)调用IpcApiService.broadcast/senduseIpcOn收事件。旧式 command IPC 仍共存。决策口诀SQLite 数据 → DataApi用户设置 → Preference可丢失/共享 → Cache其余命令式 → IpcApi。Window ManagerMUST READdocs/references/window-manager/README.md生命周期模式、池机制、API 参考。所有BrowserWindow必须经WindowManager按src/main/core/window/windowRegistry.ts中声明的default/singleton/pooled三种模式之一管理业务代码只能用open()/close()绝不用create()/destroy()监听器挂在onWindowCreated里而不是open()之后——复用窗口会跳过后者渲染进程用useWindowInitData读初始化数据。主进程服务生命周期MUST READdocs/references/lifecycle/README.md。所有持有长期资源或注册持久副作用的主进程服务必须进生命周期系统继承BaseService加Injectable、ServicePhase、DependsOn装饰器在 src/main/core/application/serviceRegistry.ts 的services对象中登记——每个服务一行key 就是application.get(xxx)的名字DependsOn只能声明同阶段依赖禁止WhenReady 服务依赖 BeforeReady 服务PreferenceService、DbService、CacheService、DataApiService阶段排序由容器自动保证访问用application.get(Name)Conditional服务用getOptional()生命周期钩子与工具this.ipcHandle()/this.ipcOn()注册 IPC停止/销毁时自动清理并返回Disposable、this.registerInterval()注册定时器自动 unref、异常隔离、自动清理、this.registerDisposable()追踪清理项、EmitterT/EventT做服务间事件、SignalT做一次性完成重资源按需服务实现ActivatableonActivate()/onDeactivate()加载/释放资源IPC 保持注册禁止new或手写单例——容器管理实例化、排序与关闭。生命周期实现位于 src/main/core/lifecycle/types.ts定义阶段与状态Phase枚举含BeforeReady/Background/WhenReady优先级 0/1/2、decorators.ts提供装饰器、BaseService.ts提供钩子基类、ServiceContainer.ts是 IoC 容器、DependencyResolver.ts做拓扑排序与分层并行解析、LifecycleManager.ts做分阶段启动/关闭与暂停恢复。非生命周期服务直导入单例没有长期资源或持久副作用的服务用命名导出单例export const x new X()禁止getInstance()模式判据见 lifecycle-decision-guide.md判断标准是生命周期管理资源而非逻辑——拥有长期资源DB 连接、网络服务、原生/OS 资源、文件系统 watcher、定时器、子进程、有状态存储或注册持久副作用事件监听、全局快捷键、订阅、会话拦截器、IPC 处理器才进生命周期纯编排、DataApi 业务逻辑服务、请求级资源、无 init/cleanup、纯工具一律不进。Schema 与迁移规则v2 迁移链不可重写AGENTS.md 对数据迁移给出硬性规则v2 重构已落地v1 数据只能经src/main/data/migration/v2/下的 migrators 进入 v2绝不为 v1 的保存/读取/丢失加 fallback、双写或守卫。迁移链不再是可抛弃的它已合并成一条干净的首个迁移并随v2.0.0-rc.1发布migrations/sqlite-drizzle/现在跑在含真实用户行的数据库上。禁止抹掉或重写已发布的迁移禁止让用户删数据库schema 变更以追加新迁移的方式进入用pnpm db:migrations:generate生成。src/main/data/db/schemas/仍可自由改动但每次变更都必须能在已填充数据的数据库上向前迁移存活。解决迁移合并冲突重新生成绝不重命名上游迁移与你本地冲突时删除本地.sqlmeta/*_snapshot.json后重跑pnpm db:migrations:generate。重命名/重编号会静默复用 snapshot 的随机id让全链路分叉——而且drizzle-kit generate依然退出0只有pnpm db:migrations:check能抓到。CI 同时强制链检查和 schema↔migration 的 generate-and-diff 步骤。数据分类工具链v2-refactor-temp/tools/data-classify/ 是 v2 数据层的代码生成流水线classification.json是唯一真源。四个文件是自动生成的严禁手改src/shared/data/preference/preferenceSchemas.ts、src/shared/data/bootConfig/bootConfigSchemas.ts以及src/main/data/migration/v2/migrators/mappings/下的PreferencesMappings.ts和BootConfigMappings.ts。要改就改data/下的classification.json或target-key-definitions.json然后运行cd v2-refactor-temp/tools/data-classify npm run generateBreaking Changes Log当 v2 变更对用户可感知、影响使用方式时在v2-refactor-temp/docs/breaking-changes/下加一条记录规范见 v2-refactor-temp/docs/breaking-changes/README.md。本地私有指令CLAUDE.local.md 覆盖机制最后一条约定是覆盖机制若仓库根目录存在CLAUDE.local.md被 gitignore可能缺失执行任何操作前必须完整阅读它——它保存开发者的私有指令与 AGENTS.md 冲突时以它为准。自动加载该文件的工具如 Claude Code无需重复读取。小结一份可复用的 AI 协作仓库模板Cherry Studio 的 AGENTS.md 演示了如何把一套大型 Electron 应用的工程纪律结构化、可执行化以先思考、求简单、外科手术式修改、目标驱动为心智底座以命令矩阵、签名提交、Conventional Commits、契约式测试为强制约束再通过docs/references/下的系列权威文档把架构决策数据四子系统、生命周期容器、Window Manager、barrel 边界、路径注册表沉淀为可引用的规范。对参与 Cherry Studio 开发的 Agent 和人类开发者而言遵循这份约定意味着每一行改动都有据可依、每一笔提交都可审计、每一次迁移都安全可回滚——这也是开源仓库被 AI 高效协作的正确姿势。赞分享人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载相关推荐Screenpipe 仓库 AI Agent 协作开发规范全解读懂 AGENTS.md 的工程纪律与约束Screenpipe 仓库 AI Agent 协作开发规范全解读懂 AGENTS.md 的工程纪律与约束 导读 screenpipe 是一个本地优先的开源计AI 应用大模型本地部署AI AgentMCP 服务屏幕录制语音agent-browser 仓库的 AI 编码代理协作指南AGENTS.md 工程规范全解读agent browser 仓库的 AI 编码代理协作指南AGENTS.md 工程规范全解读 导读 本文围绕 agent browser面向 AI Agen浏览器控制CLIAI 应用GUI 自动化开发工具AI 技能MCP 服务Plate 开源仓库 AGENTS.md 深度解读为 AI Agent 与开发者设计的仓库协作规范Plate 开源仓库 AGENTS.md 深度解读为 AI Agent 与开发者设计的仓库协作规范 导读 AGENTS.md 是 Plate 富文本编辑器仓库前端富文本UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio 的 AI Agent 协作开发约定：解读 AGENTS.md 与仓库工程规范全貌
人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载Cherry Studio 是一个基于 Electron 的多 LLM 提供商桌面客户端其仓库根目录的 AGENTS.md 是面向 AI 编码代理Agent和协作者的一整套工程协作约定它规定了编码心智、提交纪律、测试哲学、目录结构与数据系统选型并链接到docs/references/下数十份权威文档。本文以 AGENTS.md 为骨架结合仓库源码与配置文件逐条展开帮助读者快速建立对 Cherry Studio 工程规范、工具链与架构决策的全局认知并能在参与开发时按同一套约定提交高质量代码。编码心智先思考、求简单、做外科手术式修改AGENTS.md 的第一部分 Guiding Principles 定义了四条编码心智它们决定了仓库里每一行代码的产出方式。Think Before Coding先思考再编码显式陈述假设不确定就先提问再实现存在多种解释时全部摊开不要默默选一个存在更简单的方案就直说必要时反驳有任何不清楚的地方就停下来指出困惑点并提问。Simplicity First简单优先只写解决当下问题的最小代码不做投机性扩展不为单次使用场景引入抽象不加未被要求的灵活性和可配置性不处理不可能发生的错误场景写了 200 行但 50 行就能解决就重写行内注释上限 2 行——注释超过 2 行说明实现本身就是补丁应该修复实现而不是叙述实现注释只说为什么从不复述是什么禁止 changelog、理由小作文和粘贴聊天/评审回复。唯一豁免是导出 API 的文档注释TSDocparam/returns/deprecated它们属于文档而非叙述。Surgical Changes外科手术式修改只触碰任务要求的代码不顺手改进相邻代码、注释或格式不重构没坏的东西即使你会有不同写法也要匹配现有风格发现无关的死代码只提一句不要删除但你自己的改动产生的孤儿 import/变量/函数必须清掉每一处改动都必须能直接追溯到用户请求。Goal-Driven Execution目标驱动执行把任务先转化为可验证的目标再动手加校验 → 为非法输入写测试然后让测试通过修 Bug → 写一个能复现它的测试然后让它通过重构 X → 重构前后都确保测试通过。多步任务要给出带验证点的简短计划1. [Step] → verify: [check] 2. [Step] → verify: [check]这套先测试后实现的思路与仓库的测试哲学一脉相承见下文测试规范。操作规则一条条可执行的仓库纪律Operational Rules 是把心智落到仓库的具体规则其中几条与源码强绑定先读本地 README在改动一个目录前先读该目录及父目录的README.md——这些文件记录了纯代码看不出的本地约定、不变式和入口点。仓库中src/main/core/lifecycle/README.md、src/main/core/paths/README.md、tests/__mocks__/README.md都是这样的存在。修上游不 hack 下游新功能撞上现有模块的局限时先向上游提出改进方案供用户决策再考虑下游 workaround。库优先自定义最后写自定义代码前先查库/框架文档是否有内置方案。UI 统一用 Shadcn Tailwind所有新 UI 组件都取自packages/ui下的cherrystudio/uiShadcn UI Tailwind CSS。日志集中所有日志走loggerService并带正确上下文禁止console.log。路径集中主进程所有文件系统路径都通过application.getPath(namespace.key, filename?)获取禁止直接调用app.getPath()、os.homedir()或临时拼路径单例通过import { application } from application导入。只检查自己改动的范围代码改动跑pnpm lint含 format typecheck i18n:check加上覆盖你改动的测试纯文档改动只需pnpm docs:check。Conventional Commits小而聚焦的提交scope 必须是具体的 kebab-case 模块如feat(data-api):、fix(lifecycle):、docs(testing):禁止宽泛的main——即使git log历史与这条规则冲突规则优先。签名提交每个提交都必须加密签名且带 DCO sign-off使用git commit -S --signoff不能只用--signoff并用git cat-file commit HEAD验证提交对象含gpgsig头。分支策略main是所有活跃开发的默认分支特性、重构、优化和修复都合入这里。开发命令速查pnpm 脚本矩阵与验证门禁AGENTS.md 要求先pnpm installNode 与 pnpm 版本在 package.json 的engines和packageManager字段钉死node 24.11.1 24.16.0、pnpm11.8.0其余脚本以package.json为准。必须掌握的脚本如下命令作用pnpm lintoxlint eslint fix typecheck i18n check format会写文件pnpm test跑全部 Vitest 测试按 main / renderer / aiCore / ui / shared / provider-registry / scripts / preload 分项目串行执行pnpm formatBiome format lint写模式pnpm docs:check文档门禁check-links 结构 closed-set frontmatter/sources存在性 生成索引新鲜度build:check相比linttest多出的就是它pnpm build:checklintdocs:check 全部test即一键跑完整门禁pnpm test:lintCI 等价 lint 门禁拒绝pnpm lint/build:check会静默容忍的 oxlint warning针对窄范围改动AGENTS.md 明确提示永远不要用pnpm test path——该脚本内部用串联多个 vitest 调用CLI 参数只会到达最后一个调用前面的项目会不加过滤地跑完整套件。正确做法是使用按项目包装的脚本pnpm test:main file、test:renderer、test:aicore、test:shared、test:pkg:ui、test:scripts或pnpm exec vitest run file跑少数文件。文档改动方面有个细节docs/references/**和docs/contrib/**下的文档带description/sourcesfrontmatterdocs/README.md 是生成的索引编辑 frontmatter 后要跑pnpm docs:index绝不能手改索引。此外若build:check挂在 i18n 排序上先跑pnpm i18n:sync挂在格式上先跑pnpm format挂在文档链接上就修链接。测试规范契约断言而非行为快照测试统一跑在 Vitest 3 上见各vitest.config.*。AGENTS.md 对测试提出了一条旗帜鲜明的红线禁止行为固定behavior-pinning测试——一个测试如果断言只是记录当前代码行为快照输出、mock 上的toHaveBeenCalled、按实现方式反推的期望值就没有价值它不会因真实原因失败、每次重构都会碎、还会把现有 Bug 认证成预期。要断言契约真实输入 → 特性承诺的结果外加失败与边界情况。写测试前先说出它能抓住的 Bug说不出就别写。另外三条具体规定前端测试必读 Frontend Testing Guidelines。统一 mock使用 tests/mocks/README.md 描述的统一 mock 系统禁止为application、服务或数据层临时造 ad-hoc mock。该目录按进程组织renderer 侧有CacheService、DataApiService、PreferenceService、useDataApi、usePreference、useCache的 mockmain 侧有application统一工厂、DbService、CacheService、DataApiService、PreferenceService分别经 tests/renderer.setup.ts 和 tests/main.setup.ts 全局配置并通过test-mocks/*别名导入。数据库测试任何读写 SQLite 的服务/处理器/seeder 都用test-helpers/db的setupTestDatabase()——它提供带生产迁移的真实文件数据库禁止手写CREATE TABLE、覆盖application或 stub Drizzle 链详见 database-testing.md。mock 系统还复刻了主进程容器语义application.getOptional(Name)对常规服务会抛错所有默认 mock 服务都是非条件服务未知名字返回undefined以此抓住不该从get()回退到getOptional()的代码若get/getOptional的选择是承重逻辑则要求补真实ServiceContainer冒烟测试参考 dataApiDataChange.container.test.ts。补丁依赖升级前先查 patches/仓库对一批依赖打了自定义补丁集中在 patches/ 目录如ai-sdk__anthropic.patch、ai6.0.185.patch、tiptap__markdown3.26.1.patch、onnxruntime-node1.25.1.patch等。AGENTS.md 明确规定升级任何依赖前先检查patches/下是否有针对它的补丁避免升级把补丁内容冲掉。GitHub 工作流skill 驱动与轻量评审PR使用gh-create-prskill兜底直接读 .agents/skills/gh-create-pr/SKILL.md。Code Review评审别人的 PR 时不要在本地跑pnpm lint/pnpm test/pnpm format——CI 已经跑过了用gh直接检查即可。Issues使用gh-create-issueskill兜底读 .agents/skills/gh-create-issue/SKILL.md。这套流程与签名 sign-off 提交配合保证合入main的每笔变更都可审计。编码约定从类型分层到 i18nTypeScript 分层跨进程类型放src/shared/仅渲染进程使用的共享类型放src/renderer/types/依据是 Shared Layer Architecture。命名规范AGENTS.md 将 docs/references/architecture/naming-conventions.md 标记为MUST READ。这份权威文档版本 1.1覆盖文件、目录、标识符与单复数规则核心要点包括业务 React 组件文件PascalCase.tsxpackages/ui/下 shadcn 组件kebab-case.tsxHook 文件useXxx.ts工具函数文件camelCase.ts类即默认导出的文件用PascalCase.ts如KnowledgeService.ts、WindowManager.ts桶目录bucket用 camelCase 复数名词services/、utils/、hooks/业务/领域模块用 camelCase 单数命名一致性优先于风格偏好跨平台大小写安全禁止同目录Foo.ts与foo.ts并存该规则由eslint.config.mjs内联的naming/path-case插件在pnpm lint/test:lint/ci:basic-check中以 error 级别强制。日志AGENTS.md 给出标准用法import { loggerService } from logger; const logger loggerService.withContext(moduleName); // Renderer only: loggerService.initWindowSource(windowName) first logger.info(message, CONTEXT); logger.warn(message); logger.error(message, error);其实现位于 src/main/core/logger/LoggerService.ts基于 winston winston-daily-rotate-file日志目录来自src/main/core/paths/constants.ts的LOGS_DIR与BootConfigService、pathRegistry共用同一真源开发/诊断模式下默认级别为SILLY生产默认INFO。该类只允许在主进程实例化worker 线程直接抛错。路径AGENTS.md 将 src/main/core/paths/README.md 标记为MUST READ。主进程所有文件系统路径统一在pathRegistry.ts注册通过application.getPath()访问import { application } from application const dir application.getPath(feature.files.data) // /Users/alice/Library/Application Support/CherryStudio/Data/Files const file application.getPath(feature.files.data, avatar.png) // .../Data/Files/avatar.png关键机制命名空间cherry.*通用基础设施、sys.*系统目录、app.*Electron 应用目录、feature.*Cherry 自有功能数据默认选择、v1.*仅清理用旧路径、external.*第三方路径只读不删。键格式/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)$/至少两段、每段字母开头、多词段用 snake_case由 ESLint 强制。文件 vs 目录目录键无后缀独立文件键用_file后缀有兄弟键的文件用.file结尾段。目录键绝不能以file结尾——auto-ensure 靠它区分。auto-ensuregetPath()首次访问自动建目录目录键mkdirSync递归文件键只建dirnameNO_ENSURE列表中的键如sys.、external.前缀或个别精确键跳过防止只读/第三方/清理目标被查找动作意外物化。.分隔符是语义而非物理路径feature.mcp.oauth实际在~/.cherrystudio/config/mcp/oauth下不能从键名推断磁盘嵌套一律查pathRegistry.ts。文件名第二参数会校验绝对路径、..、分隔符都会告警。i18n所有用户可见字符串必须走i18next禁止硬编码 UI 文案语言包在src/renderer/i18n/locales/与src/main/i18n/locales/都以en-us.json为真源新增/修改 key 时只编辑en-us.json然后跑pnpm i18n:sync其他语言填[to be translated]:占位符再逐条翻译pnpm lint内置了i18n:check会拒绝残留占位符、空值、插值/标签不匹配和未排序的 key。UI 设计任何 UI 组件或页面样式工作前先读 DESIGN.md严格遵循其中的颜色、字体、间距与组件规格。架构地图代码组织、数据系统与生命周期代码组织closed set 与 barrelAGENTS.md 规定每个进程根目录的顶层是封闭集合closed set新代码必须归入既有类别禁止新建顶层目录。目录的index.ts是barrel——强制封装边界只 re-export 一个内聚的公共 API内部私有、外部经 barrel 导入禁止export *、禁止嵌套 barrel只有当 lint 能封死深导入时才建 barrel否则不要。index.tsx永远被禁止见 Naming Conventions §6.4。三个进程的架构文档分别为Main Process Architecture——src/main/下的core/ipc/data/ai/features/services/utils/i18n及依赖方向Renderer Architecture——src/renderer/的类型 × 领域双轴布局与仅向下分层Shared Layer Architecture——shared放什么跨进程 无可变运行时状态及其封闭顶层集合。数据系统四子系统选型表AGENTS.md 把 docs/references/data/README.md 列为MUST READ并给出选型总表系统用途APIBootConfig早期启动设置生命周期前bootConfigService.get()、usePreference(BootConfig.*)Cache临时数据可丢失useCache、useSharedCache、useSharedCacheValue、usePersistCachePreference用户设置usePreferenceDataApi业务数据关键useQuery、useMutation范围边界BootConfig同步文件式生命周期前在主进程直读其余经usePreference(BootConfig.*)Cache内存 / 共享跨窗口/ 持久化三层内存与共享在主进程和渲染进程都有持久化两边是相互独立的存储渲染进程 localStorage主进程 {userData}/cache.jsonJSON 文件主进程额外在窗口间中继渲染进程的持久化同步Preference跨进程主 渲染窗口间自动同步DataApiSQLite 支撑无自动同步渲染进程按需拉取。数据库为better-sqlite3 Drizzle ORM驱动是同步的查询与事务内联执行、无await因此getDb()查询和withWriteTx(fn)回调必须同步书写schema 在src/main/data/db/schemas/迁移用pnpm db:migrations:generate生成。写原子性多写或读后写要全部提交或全部回滚时用application.get(DbService).withWriteTx(fn)单个BEGIN IMMEDIATE同步事务单条写不需要——better-sqlite3 在单连接上每条语句本身原子。DataApi 边界规则DataApi 只服务 SQLite 支撑的业务数据没有数据库表就没有 DataApi 端点否则走 IPC见 api-design-guidelines.md 的 Scope Boundaries 小节。IPCIpcApiAGENTS.md 把 docs/references/ipc/README.md 列为MUST READ。非数据类命令 IPC窗口/系统/Shell/通知/外部/文件走IpcApi——它是与 BootConfig/Cache/Preference/DataApi 并列的第五个子系统基于 RPC-over-IPC 的单点 schemaschema handler加路由ipcApi.request(namespace.action, input)调用IpcApiService.broadcast/senduseIpcOn收事件。旧式 command IPC 仍共存。决策口诀SQLite 数据 → DataApi用户设置 → Preference可丢失/共享 → Cache其余命令式 → IpcApi。Window ManagerMUST READdocs/references/window-manager/README.md生命周期模式、池机制、API 参考。所有BrowserWindow必须经WindowManager按src/main/core/window/windowRegistry.ts中声明的default/singleton/pooled三种模式之一管理业务代码只能用open()/close()绝不用create()/destroy()监听器挂在onWindowCreated里而不是open()之后——复用窗口会跳过后者渲染进程用useWindowInitData读初始化数据。主进程服务生命周期MUST READdocs/references/lifecycle/README.md。所有持有长期资源或注册持久副作用的主进程服务必须进生命周期系统继承BaseService加Injectable、ServicePhase、DependsOn装饰器在 src/main/core/application/serviceRegistry.ts 的services对象中登记——每个服务一行key 就是application.get(xxx)的名字DependsOn只能声明同阶段依赖禁止WhenReady 服务依赖 BeforeReady 服务PreferenceService、DbService、CacheService、DataApiService阶段排序由容器自动保证访问用application.get(Name)Conditional服务用getOptional()生命周期钩子与工具this.ipcHandle()/this.ipcOn()注册 IPC停止/销毁时自动清理并返回Disposable、this.registerInterval()注册定时器自动 unref、异常隔离、自动清理、this.registerDisposable()追踪清理项、EmitterT/EventT做服务间事件、SignalT做一次性完成重资源按需服务实现ActivatableonActivate()/onDeactivate()加载/释放资源IPC 保持注册禁止new或手写单例——容器管理实例化、排序与关闭。生命周期实现位于 src/main/core/lifecycle/types.ts定义阶段与状态Phase枚举含BeforeReady/Background/WhenReady优先级 0/1/2、decorators.ts提供装饰器、BaseService.ts提供钩子基类、ServiceContainer.ts是 IoC 容器、DependencyResolver.ts做拓扑排序与分层并行解析、LifecycleManager.ts做分阶段启动/关闭与暂停恢复。非生命周期服务直导入单例没有长期资源或持久副作用的服务用命名导出单例export const x new X()禁止getInstance()模式判据见 lifecycle-decision-guide.md判断标准是生命周期管理资源而非逻辑——拥有长期资源DB 连接、网络服务、原生/OS 资源、文件系统 watcher、定时器、子进程、有状态存储或注册持久副作用事件监听、全局快捷键、订阅、会话拦截器、IPC 处理器才进生命周期纯编排、DataApi 业务逻辑服务、请求级资源、无 init/cleanup、纯工具一律不进。Schema 与迁移规则v2 迁移链不可重写AGENTS.md 对数据迁移给出硬性规则v2 重构已落地v1 数据只能经src/main/data/migration/v2/下的 migrators 进入 v2绝不为 v1 的保存/读取/丢失加 fallback、双写或守卫。迁移链不再是可抛弃的它已合并成一条干净的首个迁移并随v2.0.0-rc.1发布migrations/sqlite-drizzle/现在跑在含真实用户行的数据库上。禁止抹掉或重写已发布的迁移禁止让用户删数据库schema 变更以追加新迁移的方式进入用pnpm db:migrations:generate生成。src/main/data/db/schemas/仍可自由改动但每次变更都必须能在已填充数据的数据库上向前迁移存活。解决迁移合并冲突重新生成绝不重命名上游迁移与你本地冲突时删除本地.sqlmeta/*_snapshot.json后重跑pnpm db:migrations:generate。重命名/重编号会静默复用 snapshot 的随机id让全链路分叉——而且drizzle-kit generate依然退出0只有pnpm db:migrations:check能抓到。CI 同时强制链检查和 schema↔migration 的 generate-and-diff 步骤。数据分类工具链v2-refactor-temp/tools/data-classify/ 是 v2 数据层的代码生成流水线classification.json是唯一真源。四个文件是自动生成的严禁手改src/shared/data/preference/preferenceSchemas.ts、src/shared/data/bootConfig/bootConfigSchemas.ts以及src/main/data/migration/v2/migrators/mappings/下的PreferencesMappings.ts和BootConfigMappings.ts。要改就改data/下的classification.json或target-key-definitions.json然后运行cd v2-refactor-temp/tools/data-classify npm run generateBreaking Changes Log当 v2 变更对用户可感知、影响使用方式时在v2-refactor-temp/docs/breaking-changes/下加一条记录规范见 v2-refactor-temp/docs/breaking-changes/README.md。本地私有指令CLAUDE.local.md 覆盖机制最后一条约定是覆盖机制若仓库根目录存在CLAUDE.local.md被 gitignore可能缺失执行任何操作前必须完整阅读它——它保存开发者的私有指令与 AGENTS.md 冲突时以它为准。自动加载该文件的工具如 Claude Code无需重复读取。小结一份可复用的 AI 协作仓库模板Cherry Studio 的 AGENTS.md 演示了如何把一套大型 Electron 应用的工程纪律结构化、可执行化以先思考、求简单、外科手术式修改、目标驱动为心智底座以命令矩阵、签名提交、Conventional Commits、契约式测试为强制约束再通过docs/references/下的系列权威文档把架构决策数据四子系统、生命周期容器、Window Manager、barrel 边界、路径注册表沉淀为可引用的规范。对参与 Cherry Studio 开发的 Agent 和人类开发者而言遵循这份约定意味着每一行改动都有据可依、每一笔提交都可审计、每一次迁移都安全可回滚——这也是开源仓库被 AI 高效协作的正确姿势。赞分享人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载相关推荐Screenpipe 仓库 AI Agent 协作开发规范全解读懂 AGENTS.md 的工程纪律与约束Screenpipe 仓库 AI Agent 协作开发规范全解读懂 AGENTS.md 的工程纪律与约束 导读 screenpipe 是一个本地优先的开源计AI 应用大模型本地部署AI AgentMCP 服务屏幕录制语音agent-browser 仓库的 AI 编码代理协作指南AGENTS.md 工程规范全解读agent browser 仓库的 AI 编码代理协作指南AGENTS.md 工程规范全解读 导读 本文围绕 agent browser面向 AI Agen浏览器控制CLIAI 应用GUI 自动化开发工具AI 技能MCP 服务Plate 开源仓库 AGENTS.md 深度解读为 AI Agent 与开发者设计的仓库协作规范Plate 开源仓库 AGENTS.md 深度解读为 AI Agent 与开发者设计的仓库协作规范 导读 AGENTS.md 是 Plate 富文本编辑器仓库前端富文本UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考