Cherry Studio 文档治理与 Spec 驱动工作流：从防腐烂门禁到 Agent Notes 决策记录的完整方案

人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载本文基于 CherryHQ/cherry-studio 仓库中的 Agent Note 提案文档 .agents/notes/proposed/process/2026-08-18-docs-governance-and-spec-workflow.zh.md 展开。该提案诊断了仓库开发者文档的四大系统性缺陷无声腐烂、层级误导、决策蒸发、双语缺失并提出一套六部分P1–P6 分阶段推进的治理方案目标目录树、frontmatter 契约、文档门禁脚本、Agent Notes 决策记录、双语配对与流程 Skills。读完本文你将理解 Cherry Studio 如何把文档是产品从口号变成可校验的工程约束并掌握每条门禁、每个文件命名规则的源码级依据与当前落地状态。一、背景开发者文档正在无声地腐烂且没有任何机制能发现提案首先指出一个尖锐的现实文档腐烂doc rot在本仓库是无声的——没有任何门禁能在代码已删除、文档还在教它时发出告警。文档列举了两个典型病例docs/guides/middleware.md在教一套已删除的 v1AiProviderMiddlewareTypes中间件系统而src/中对该类型零命中docs/references/messaging/message-system.md描述的 Redux IndexedDB 消息存储早已不存在仓库没有reduxjs/toolkit依赖、没有messageThunk.ts、没有src/renderer/store/目录。这两篇文档在贡献者和 AI agent 眼里仍是现行权威而当时唯一的文档门禁docs:check-links只校验链接目标是否存在这一件事且 CI 根本不运行它ci:basic-check覆盖 lint、format、typecheck、i18n 与 skills唯独不含文档检查。对照当前仓库可以确认这一诊断与后续修复均已落地今天src/main/ai/下已有完整的 AI 域实现见 docs/references/ai/README.md 的sources声明docs/guides/与docs/references/messaging/目录在仓库中已不存在取而代之的是按域组织的docs/references/domain/结构而package.json中ci:basic-check已经包含pnpm docs:check见下文 P3 章节docs:check-links也升级为聚合检查的一部分。除腐烂外提案还列出另外三个相互关联的缺陷层级在误导读者guides/与references/的二分名存实亡——guides/里大多是流程规范contributing、branching-strategy、test-plan和用法参考logging、i18n、diagnostics不是教程references/顶层是开放集17 个域目录与 10 个散文件混住代码里只有 chat 一个域文档却拆成chat/和messaging/两份。docs/README.md是手工维护的索引且已经漂移漏列 4 篇架构文档、错挂 1 篇 chat 文档根CONTRIBUTING.md与docs/guides/contributing.md是一对措辞分叉的近似副本。决策在蒸发理由与被否决的替代方案只存在于 PR 讨论串和聊天里多个 agent 并行工作时同一个被否决的主意会被反复提出、反复争论因为没有任何记录说明它输过、为什么输。文档是产品却缺了一半Cherry Studio 的用户与贡献者中有很大比例读中文而语料约 110 篇英文 markdown 只有一对中文对照。二、P1 — Target tree封闭的域目录集与一个事实一个家提案给出的目标树如下对照当前仓库该结构已基本落地docs/ README.md # thin index generated from frontmatter descriptions; never hand-edited contrib/ # process repo engineering: contributing pointers, branching-strategy, # development, linux-packaging, test-plan, feishu-notify, app-upgrade references/ architecture/ # architecture-overview, main-process-architecture, # renderer-architecture, shared-layer-architecture, naming-conventions domain/ # closed set; every domain directory has README.md as the domain home .agents/notes/ # Agent Notes (decision records) — see P4当前仓库docs/下确实只存在contrib/与references/两大分支references/顶层全部是域目录ai、api-gateway、architecture、binary-manager、chat、command、components、data、diagnostics、file、i18n、ipc、job-and-scheduler、knowledge、lan-transfer、lifecycle、logging、memory、mini-app、provider-model、security、testing、utility-process、window-manager每个域目录都有README.md作为域之家。目标树附带的四条规则是治理的基石references/顶层是封闭集只允许域目录、不许散文件——这条由门禁强制见 P3并与 docs/references/architecture/naming-conventions.md 中代码树已有的封闭集规则呼应。每个域目录必须有README.md作为域之家本域主题写全细节子级文档只做概括并链接。原则是一个事实一个家one fact, one home。域目录内文件名不重复域前缀如window-manager-usage.md→usage.md。提案同时明确这一决策已被后续落地的审计结果取代——.agents/notes/implemented/process/2026-08-19-phase-0b-doc-audit-outcomes.zh.md 规定除非搬家或歧义要求改名否则保留现有 basename当前仓库docs/references/window-manager/下仍可见window-manager-api-reference.md等带前缀文件名正是该修订的体现。与代码旁 README 的分工如src/main/core/paths/README.md、tests/__mocks__/README.md跨切面或多模块的内容归docs/模块私有事实住在模块旁边。docs/README.md改为生成式薄索引退役手工维护的表格——当前 docs/README.md 顶部已带注释!-- Generated by scripts/gen-doc-index.ts — do not edit by hand; runpnpm docs:index. --证明该规则已生效。提案还以表格形式逐文件规定了存量文档的处置方式Phase 0b 执行。下表完整继承该决策并标注当前仓库的实际落点原文件处置当前仓库落点references/messaging/message-system.md删除——描述的系统已被删除目录messaging/已不存在guides/middleware.md删除——现行中间件事实归src/main/ai域文档负责guides/已不存在guides/contributing.md删除——根CONTRIBUTING.md定为唯一家中文版在 Phase 2 以根CONTRIBUTING.zh.md落地根目录存在CONTRIBUTING.mdreferences/messaging/composer-rich-clipboard.md移动 →references/chat/现位于 docs/references/chat/composer-rich-clipboard.mdreferences/fuzzy-search.md移动 →references/file/现位于 docs/references/file/fuzzy-search.mdreferences/ui-semantic-contract.md移动 →references/components/现位于 docs/references/components/ui-semantic-contract.mdreferences/lan-transfer-protocol.md移动 →references/lan-transfer/协议规范自成一域域 README 即协议规范docs/references/lan-transfer/README.md5 篇references/*-architecture.md散文件移动 →references/architecture/现位于 docs/references/architecture/ 下guides/{logging,i18n}.md移动 → 各自主题域现为 docs/references/logging/README.md 与 docs/references/i18n/README.mdguides/diagnostics.md归属在 Phase 0b 审计时决定现为 docs/references/diagnostics/README.mddocs/sponsor.md留在docs/根——面向用户的页面不进参考树、不进双语配对根目录存在 docs/sponsor.mdreferences/chat/{adapters,conventions}.md原计划保持原位target-architecture 文档已被审计结果取代审计结果决定删除这两篇见下references/file/architecture.mdfile-manager-architecture.md两篇都保留——刻意分层且互相声明 SoT 边界不是腐烂均存在docs/references/file/architecture.md、docs/references/file/file-manager-architecture.md对 P1 的落地修订Phase 0b 审计结果.agents/notes/implemented/process/2026-08-19-phase-0b-doc-audit-outcomes.zh.mdStatus: implemented是这份提案的第一个后继决策记录它明确记录了两处偏离原提案的落地修订参考文档以现行实现为准原提案中标注为 target-architecture 的chat/adapters.md与chat/conventions.md描述的 API 与所有权边界从未落地因此 Phase 0b 直接删除两篇未来 adapter 契约实际落地时再新增现行文档。不批量改名存量带前缀文件审计完成后的树中仍有 24 个带域前缀的 basename一律保留域内最短且无歧义名称、避免重复域前缀的规则只在文档新增或改名时生效。这份 note 只取代上述两项 Phase 0b 决策原提案定义的目标树、frontmatter、门禁、Agent Notes 与推进阶段仍然有效——这正是 P4 决策记录机制用新 note 取代并互相链接不原地改写的直接示范。三、P2 — Frontmatter描述性与存在性元数据提案规定docs/references/**下每篇文档携带两块 frontmatter--- description: One-line summary (feeds the generated index and agent doc catalogs) sources: # code paths this document describes; directories preferred - src/main/services/file/tree/ ---适用范围与例外docs/contrib/**只要求descriptionAgent Notes 不用 frontmatter——路径与 header block 已编码元数据与 dshdeepseek-harness一致docs/sponsor.md不在任何门禁的扫描范围内门禁只覆盖references/与contrib/也不进双语配对。sources的语义是路径前缀匹配当某个 diff 路径等于该条或位于其下时即归属该文档——因此目录条目覆盖其全部子孙。这正是 Phase 4 反向查询这个 PR 本应更新哪些文档能对子树改动生效的原因也正因如此条目过宽会稀释信号每条应写仍能覆盖该文档全部主题的最窄目录。提案还给出了未来任何字段的准入标准它必须承载路径、H1、git 都承载不了的信息并且说得出消费它的脚本。据此当场拒绝了一批常见字段每个都有明确的归属理由被拒字段归属理由domain/category路径已承载titleH1 已承载updated/authorgit 已承载status: deprecated要么是现行事实、要么删除——弃用标记是给腐烂发的留存许可证tags无消费者sidebar_position站点导航集中在一个映射文件dsh 式翻译配对 hash把文件的 hash 写进文件本身会改变 hash——必须住在 sidecar 里当前仓库中的实际样例可参考 docs/references/ai/README.md 的 frontmatter--- description: Entry point mapping the AI pipeline docs, src/main/ai code layout, chat-turn flow, runtimes, and key invariants sources: - src/main/ai - src/renderer/services/aiTransport ---四、P3 — Gates三道门禁 一条聚合命令 CI 接线提案设计了三个新脚本全部是tsx scripts/*.ts遵循仓库较新的脚本惯例导出函数 scripts/__tests__/下的测试同i18n-check-values.ts。这三个脚本当前仓库均已存在可直接作为实现依据阅读4.1verify-doc-structure封闭集与 README 之家实现位于 scripts/verify-doc-structure.ts。它读取docs/references根目录逐项校验目录必须出现在REFERENCE_DOMAINS封闭集中该常量在脚本内硬编码了 24 个域新增域必须与创建目录的 PR 同步修改此列表每个域目录必须存在README.md根目录下不允许散文件loose file at the references root封闭集中的每个域必须真实存在于磁盘。值得注意的错误信息设计对于不在封闭集中的目录脚本会提示add it to REFERENCE_DOMAINS in scripts/verify-doc-structure.ts deliberately, or relocate the directory——**刻意性deliberate**被写进了错误文案新增域必须是显式决策而非顺手为之。4.2verify-doc-frontmatter必填字段与存在性检查实现位于 scripts/verify-doc-frontmatter.ts核心逻辑在checkFile函数description必须是非空字符串且为单行含换行即失败references/**强制要求sourcesrequireSources: truecontrib/**不要求每条sources必须是仓库相对路径拒绝空串、绝对路径、含..的路径并且用fs.existsSync校验路径真实存在——不存在即报错 the doc may describe deleted or moved code。提案特别强调它是存在性检查existence check不是新鲜度检查freshness check。它抓住的腐烂类型是主题已被删除或搬走——middleware.md与message-system.md正是此类——代码移动当天就会被抓住而主题原地变化、或文件在某个宽目录条目内部移动导致的过时门禁仍是绿的语义过时由 Phase 4 的反向查询与评审负责。这正是机器管得住什么、管不住什么的清醒边界。4.3gen-doc-index带--check防漂移的生成式索引实现位于 scripts/gen-doc-index.ts。它从每篇文档的 frontmatterdescription与正文 H1 重新生成 docs/README.md标题取文档的 H1docTitle函数用/^# (.)$/m正则提取无 H1 时回退到文件名 stem域章节标题由SECTION_TITLES映射ai→AI、ipc→IPC 等特例 默认的连字符转驼峰规则排序规则domainOrderREADME 优先、浅层优先、字母序--check模式下逐字节比对现有文件与生成结果漂移即失败docs/README.md is stale — runpnpm docs:indexand commit the result.。这彻底退役了手工维护索引把索引与树同步变成机器可验证的不变量。4.4 聚合与 CI 接线pnpm docs:check提案的接线方案在当前 package.json 中已完整落地新聚合命令pnpm docs:checkdocs:check-links 上述三个脚本并替换build:check里的裸docs:check-linksci:basic-checkscript 同步更新以保持本地等价物诚实。当前package.json中可见完整脚本链docs:check-links: tsx scripts/check-doc-links.ts, docs:check-structure: tsx scripts/verify-doc-structure.ts, docs:check-frontmatter: tsx scripts/verify-doc-frontmatter.ts, docs:check-index: tsx scripts/gen-doc-index.ts --check, docs:index: tsx scripts/gen-doc-index.ts, docs:check: pnpm docs:check-links pnpm docs:check-structure pnpm docs:check-frontmatter pnpm docs:check-index // build:check 与 ci:basic-check 均通过 pnpm docs:check 引用提案还强调了一个只改 script 改不掉的 CI 缺口.github/workflows/ci.yml并不调用pnpm ci:basic-check它的basic-checksjob 通过concurrently内联各条命令——因此docs:check必须加进那个步骤才会在 CI 里真正运行。这是本地脚本与 CI 工作流是两套东西的典型陷阱验证 CI 是否真的跑了门禁要看 .github/workflows/ci.yml 的basic-checksjob而不是看 package.json 里的聚合 script。sources的后续消费者是 Phase 4 的反向查询把 PR 的 diff 路径与全部sources清单求交集即可机械得出这个 PR 本应更新的文档接进gh-pr-reviewskill——这把改代码必须带文档从自觉守则变成可校验的规则。五、P4 — Agent Notes让决策有档案、让否决有墓碑决策记录住在.agents/notes/{lifecycle}/{class}/yyyy-mm-dd-topic.md当前仓库的骨架已落地.agents/notes/README.md与中英两份 READMEproposed/process/下两份提案、implemented/process/下两份审计结果生命周期proposed/实现前先评审→implemented/已落地与现实保持同步或rejected/被否决只要其理由还能防住一个诱人的错误就保留。dsh 的archived/层缓行等数量需要时再引入。类别feature、bug-fix、simplification、architecture、process、testing。刻意不设refactor类——simplification已覆盖它判据是可观察行为是否变化。格式header block# Agent Note: title、Status: lifecycle然后是## Problem、## Proposalproposed或## Decisionimplemented现在时、自由的技术小节、强制的## Alternatives considered再然后## Acceptance criteria## Risksproposed或## Consequencesimplemented。提案的原话掷地有声不记录赢过谁的决策就是在邀请重新争论。决策永不被原地改写成另一个决策用新 note 取代并互相链接——上文 Phase 0b 审计结果正是这条规则的实例它明确声明本 note 只取代上述两项 Phase 0b 决策。门槛对 dsh 的有意偏离dsh 要求每个非平凡 PR 必带 note只对维护者可能合理地重新质疑的决策要求 note——架构选择、跨模块契约、数据/磁盘/线上格式、流程变更、被否决的方案。理由是 Cherry Studio 的日常修复流量会让逐 PR 强制变成一种税而不是记录。Spec-first 的 feature 流程大型 feature 从一条proposed/note 开始实现前先评审按其自身的 acceptance criteria 验收落地后改写为implemented/。本 note 就是这个闭环的第一个实例。格式门禁移植 dsh 的verify-agent-note-format与完整的.agents/notes/README.md规则集在 Phase 1 落地。六、P5 — Bilingual pairing双语对照 hash sidecar范围内的每篇文档都是英文/中文对照加一个一致性 sidecarfoo.md foo.zh.md foo.i18n.yamlfoo.i18n.yaml记录两侧在最近一次确认一致时的 git blob hash移植 dsh 的verify-translation-pairing。任一语言都可以先写失同步的配对用被改一侧的 diff 去最小化修补另一侧永不整篇重翻。范围按发现根逐步扩——这是对 dsh不设灰度清单立场的有意偏离.agents/notes/**和根CONTRIBUTING.md先行新语料生而双语docs/**等 Phase 3 回填完成后再纳入。docs/i18n/terminology.md成为文档翻译的术语源以scripts/i18n-glossary.json为种子。术语表目前只有五条且不被强制——需要扩充但它记录的词汇选择Provider提供商、Agent智能体直接沿用。当前仓库.agents/notes/中每一份 note 都带.zh.md对照包括本提案文档自身与 phase-0b 审计结果正是该机制的早期落地实例。七、P6 — Skills把治理流程变成 agent 的能力把 dsh 的流程 skills 做成 cherry 版本适配本仓库领域find-simplifications skill把清理一下变成有证据支撑的 proposed notes调查领域换成 renderer hooks、四个数据层、IPC、lifecycle services、v1 迁移残留doc-standards/prose-standard skill层级详略规则、tutorial/reference 分类、slop 检查单gh-pr-review反向查询集成即 P3 中sources × PR diff的机械交集。八、Rollout六阶段推进计划提案的推进计划以表格呈现当前仓库的落地进度已在各章标注Phase工作验证0a本 PR方案本身带 stub README 的.agents/notes/骨架对本 note 的评审即是决策0b逐域搬家 审计 PR移动、改名、逐条对照代码验证、重写或删除。门禁最后落地在最后一次搬家之后——verify-doc-structure读整个references/根、verify-doc-frontmatter读每篇参考文档树迁移到一半时两者都不可能绿每个搬家 PRdocs:check-links绿门禁落地后完整pnpm docs:check绿1完整.agents/notes/README.md规则集 格式门禁 回填种子 notes双语格式门禁对全部 notes 绿2配对门禁移植发现根.agents/notesCONTRIBUTING.mdCONTRIBUTING.zh.mdverify-translation-pairing绿3只对审定为现行的文档做翻译回填配对范围扩到docs/**全语料配对绿4流程 skills gh-pr-review的 sources 集成Skill 评审贯穿全程的质量原则质量先于翻译——一篇文档先审定为现行再进入配对翻译腐烂内容等于把它固化成两种语言纠错成本翻倍。九、被否决的替代方案为什么不这么做提案完整记录了自己拒绝的六条路径这本身就是决策有档案的示范零 frontmatter、纯路径编码元数据dsh 的设计——拒绝两个最迫切的需求sources腐烂门禁、description生成式索引都需要逐文件的机器可读字段dsh 用字数预算、verify-doc-refs和手工层级维护覆盖而那套机械并不整体移植。给过时文档打status: deprecated标记——拒绝要么是现行事实要么删除弃用标记是给腐烂发的留存许可证。先翻译、后审计——拒绝此后每次纠错都要付两种语言的成本外加一次配对重录。保留guides/与references/的二分——拒绝分类已名存实亡按用途分类tutorial 有序步骤走到可观察结果一照几乎全是 reference 或流程材料。现在就整体移植 dsh 的翻译机械merge driver、gen-translation-brief、doc budgets——缓行dsh 自己也把重型路径标为仅显式调用在失同步冲突成为真实成本之前常规的单遍对照更新就够了。dsh 的逐 PR note 强制令——修订为 P4 的决策门槛以这里的修复流量强制令会沦为仪式。现在就做网站投影——缓行docs.cherry-ai.com 在独立仓库等语料被治理之后投影是另一个独立决策。十、验收标准与风险提案的验收标准当前大部分已达成可作为读者自查当前仓库治理状态的 checklistreferences/顶层是封闭的域目录集每域有 README 之家verify-doc-structure绿三篇死/重复文档已删除每篇存活的 reference 文档断言都对照现行代码验证过每篇references/**文档带description 存在的sourcesverify-doc-frontmatter绿docs/README.md是生成的gen-doc-index --check绿CI 跑pnpm docs:check——以.github/workflows/ci.yml的basic-checksjob 确实调用它为准而不是以ci:basic-checkscript 列出它为准.agents/notes/持有种子 notes双语格式门禁绿.agents/notes/**与CONTRIBUTING.md通过配对门禁Phase 3 之后docs/**也通过。主要风险及缓解措施入链翻新link churndocs:check-links只解析 Markdown 链接看不到其余消费者——CLAUDE.md正文、eslint.config.mjs里的 lint 规则消息、TypeScript 注释以及按路径读取文档的代码如scripts/uiContract/__tests__/maintainedAnchors.test.ts会打开ui-semantic-contract.md那里漏改会挂掉一个测试而不是一条链接。因此 Phase 0b 的每次移动都要对旧路径 grep整个仓库src/、scripts/、packages/、tests/、.github/、根配置。缓解按域原子化移动搬家 修复全部入链引用在同一个 PR。与进行中 PR 的冲突目录树移动会与触及相同文档的在途工作冲突。缓解Phase 0b 逐域小步推进不搞一次性大搬家。双语维护成本每次编辑配对文档都要同步另一侧并重录高频变动的文档付出最多。有意接受——文档在这里是产品——并通过只配对审定为现行的材料来控制上限。翻译评审负担配对门禁校验的是结构而非忠实度中文质量仍需评审者投入而术语表起点很薄。十一、给读者的一线实践建议写新文档前先读目标树的域 README一个事实只住一个家先确认事实是否已有归属再决定是新建还是补充。新文档必带description单行 尽可能窄的sources目录前者喂生成式索引后者决定 Phase 4 反向查询的精度。任何非平凡的维护决策架构、契约、格式、被否决方案都应写一条 Agent Note放对{lifecycle}/{class}/## Alternatives considered不可省略决策被取代时新建 note 互相链接不原地改写。本地提交前跑pnpm docs:check并记住它在 CI 中的真实接线是.github/workflows/ci.yml的basic-checksjob而不是 package.json 里的聚合 script。这套方案的可贵之处在于它为文档是产品建立了三层可执行防线结构门禁保证树形正确、frontmatter 门禁保证描述与代码存在、Agent Notes保证决策不蒸发——配合双语配对与流程 Skills构成一套从预防腐烂到记录历史、再到多语言分发的完整治理闭环。赞分享人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载相关推荐Cherry Studio 的 Agent Notes用决策记录机制对抗文档腐烂与决策蒸发Cherry Studio 的 Agent Notes用决策记录机制对抗文档腐烂与决策蒸发 导读 本文围绕 Cherry Studio 仓库中的 AgentAI 应用大模型桌面应用本地部署RAGCherry Studio 文档治理与 Spec-Driven 工作流Agent Note 决策记录体系全解析Cherry Studio 文档治理与 Spec Driven 工作流Agent Note 决策记录体系全解析 本文基于 Cherry Studio 仓库中的AI 应用大模型桌面应用本地部署RAGCherry Studio 文档治理落地实录Phase 0b 审计、Agent Notes 决策记录与门禁体系Cherry Studio 文档治理落地实录Phase 0b 审计、Agent Notes 决策记录与门禁体系 本文以 Cherry Studio 仓库中的AI 应用大模型桌面应用本地部署RAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考