企业官网建设流程全解析

• 人工智能
• 大模型
• AI 应用
• 交互助手
• 本地部署

本文基于 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也升级为聚合检查的一部分。

除腐烂外，提案还列出另外三个相互关联的缺陷：

1. 层级在误导读者：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是一对措辞分叉的近似副本。
2. 决策在蒸发：理由与被否决的替代方案只存在于 PR 讨论串和聊天里；多个 agent 并行工作时，同一个被否决的主意会被反复提出、反复争论，因为没有任何记录说明它"输过、为什么输"。
3. 文档是产品，却缺了一半：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 执行）。下表完整继承该决策，并标注当前仓库的实际落点：

对 P1 的落地修订：Phase 0b 审计结果

.agents/notes/implemented/process/2026-08-19-phase-0b-doc-audit-outcomes.zh.md（Status: 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/**只要求description；
• Agent Notes 不用 frontmatter——路径与 header block 已编码元数据，与 dsh（deepseek-harness）一致；
• docs/sponsor.md不在任何门禁的扫描范围内（门禁只覆盖references/与contrib/），也不进双语配对。

sources的语义是路径前缀匹配：当某个 diff 路径等于该条或位于其下时，即归属该文档——因此目录条目覆盖其全部子孙。这正是 Phase 4 反向查询（"这个 PR 本应更新哪些文档"）能对子树改动生效的原因；也正因如此，条目过宽会稀释信号，每条应写仍能覆盖该文档全部主题的最窄目录。

提案还给出了未来任何字段的准入标准：它必须承载路径、H1、git 都承载不了的信息，并且说得出消费它的脚本。据此当场拒绝了一批常见字段，每个都有明确的归属理由：

当前仓库中的实际样例可参考 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/**强制要求sources（requireSources: true），contrib/**不要求；
• 每条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：

• 标题取文档的 H1（docTitle函数用/^# (.+)$/m正则提取，无 H1 时回退到文件名 stem）；
• 域章节标题由SECTION_TITLES映射（ai→AI、ipc→IPC 等特例）+ 默认的连字符转驼峰规则；
• 排序规则（domainOrder）：README 优先、浅层优先、字母序；
• --check模式下逐字节比对现有文件与生成结果，漂移即失败（"docs/README.md is stale — runpnpm docs:indexand commit the result."）。

这彻底退役了手工维护索引，把"索引与树同步"变成机器可验证的不变量。

4.4 聚合与 CI 接线：pnpm docs:check

提案的接线方案在当前 package.json 中已完整落地：

• 新聚合命令pnpm docs:check=docs:check-links+ 上述三个脚本，并替换build:check里的裸docs:check-links；
• ci: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与中英两份 README，proposed/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、## Proposal（proposed）或## Decision（implemented，现在时）、自由的技术小节、强制的## Alternatives considered，再然后## Acceptance criteria+## Risks（proposed）或## Consequences（implemented）。提案的原话掷地有声："不记录赢过谁的决策，就是在邀请重新争论。"
• 决策永不被原地改写成另一个决策：用新 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

范围内的每篇文档都是英文/中文对照加一个一致性 sidecar：

foo.md + foo.zh.md + foo.i18n.yaml

foo.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：六阶段推进计划

提案的推进计划以表格呈现，当前仓库的落地进度已在各章标注：

贯穿全程的质量原则：质量先于翻译——一篇文档先审定为现行，再进入配对；翻译腐烂内容等于把它固化成两种语言，纠错成本翻倍。

九、被否决的替代方案：为什么不这么做

提案完整记录了自己拒绝的六条路径，这本身就是"决策有档案"的示范：

1. 零 frontmatter、纯路径编码元数据（dsh 的设计）——拒绝：两个最迫切的需求（sources腐烂门禁、description生成式索引）都需要逐文件的机器可读字段；dsh 用字数预算、verify-doc-refs和手工层级维护覆盖，而那套机械并不整体移植。
2. 给过时文档打status: deprecated标记——拒绝：要么是现行事实，要么删除；弃用标记是给腐烂发的留存许可证。
3. 先翻译、后审计——拒绝：此后每次纠错都要付两种语言的成本外加一次配对重录。
4. 保留guides/与references/的二分——拒绝：分类已名存实亡；按用途分类（tutorial = 有序步骤走到可观察结果）一照，几乎全是 reference 或流程材料。
5. 现在就整体移植 dsh 的翻译机械（merge driver、gen-translation-brief、doc budgets）——缓行：dsh 自己也把重型路径标为仅显式调用；在失同步冲突成为真实成本之前，常规的单遍对照更新就够了。
6. dsh 的逐 PR note 强制令——修订为 P4 的决策门槛；以这里的修复流量，强制令会沦为仪式。
7. 现在就做网站投影——缓行：docs.cherry-ai.com 在独立仓库；等语料被治理之后，投影是另一个独立决策。

十、验收标准与风险

提案的验收标准（当前大部分已达成，可作为读者自查当前仓库治理状态的 checklist）：

• references/顶层是封闭的域目录集，每域有 README 之家；verify-doc-structure绿；
• 三篇死/重复文档已删除；每篇存活的 reference 文档断言都对照现行代码验证过；
• 每篇references/**文档带description+ 存在的sources；verify-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 churn）：docs: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 逐域小步推进，不搞一次性大搬家。
• 双语维护成本：每次编辑配对文档都要同步另一侧并重录；高频变动的文档付出最多。有意接受——文档在这里是产品——并通过只配对审定为现行的材料来控制上限。
• 翻译评审负担：配对门禁校验的是结构而非忠实度；中文质量仍需评审者投入，而术语表起点很薄。

十一、给读者的一线实践建议

1. 写新文档前先读目标树的域 README：一个事实只住一个家，先确认事实是否已有归属，再决定是新建还是补充。
2. 新文档必带description（单行）+ 尽可能窄的sources目录：前者喂生成式索引，后者决定 Phase 4 反向查询的精度。
3. 任何非平凡的维护决策（架构、契约、格式、被否决方案）都应写一条 Agent Note，放对{lifecycle}/{class}/，## Alternatives considered不可省略；决策被取代时新建 note 互相链接，不原地改写。
4. 本地提交前跑pnpm docs:check，并记住它在 CI 中的真实接线是.github/workflows/ci.yml的basic-checksjob，而不是 package.json 里的聚合 script。

这套方案的可贵之处在于它为"文档是产品"建立了三层可执行防线：结构门禁保证树形正确、frontmatter 门禁保证描述与代码存在、Agent Notes保证决策不蒸发——配合双语配对与流程 Skills，构成一套从预防腐烂到记录历史、再到多语言分发的完整治理闭环。

• 人工智能
• 大模型
• AI 应用
• 交互助手
• 本地部署