企业官网建设流程全解析

Agent Note: <标题>

【免费下载链接】cherry-studio🍒 Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio

Status: proposed

Problem # 问题陈述：这个决策要解决什么

Proposal # 提案内容（proposed 阶段使用）

Alternatives considered # 强制的：考虑过哪些替代方案，为何拒绝

Acceptance criteria # 验收标准：怎样算落地完成

Risks # 风险与缓解措施

### implemented/ 模板 ```markdown # Agent Note: <标题> Status: implemented ## Problem # 问题陈述 ## Decision # 已落地的决策（使用现在时，描述当前事实） ## Alternatives considered # 强制的：替代方案与拒绝理由 ## Consequences # 落地后果、对后续的约束

关键规则还有两条：

• 决策永不被原地改写成另一个决策：如果决策发生了变化，用一篇新 note 取代并互相交叉链接，而不是编辑旧 note 抹除历史——"发生变化的决策需要新的取代记录与交叉链接，而不是抹除历史"。
• Alternatives considered是强制的：不记录赢过谁的决策，就是在邀请重新争论。

双语镜像

每条 note 都有结构镜像的中文对照：foo.md+foo.zh.md，两侧共用同一套标题结构，仅语言不同。这符合仓库"文档是产品"的定位——用户和贡献者中有很大比例读中文。当前.agents/notes/下的所有 note（含 README）均已具备双语形态，可直接作为新 note 的模板参考。

实例拆解：从提案到落地的一次完整闭环

仓库内现存的两条 note 恰好演示了完整的生命周期流转，也印证了"本 note 就是这个闭环的第一个实例"。

实例一：文档治理提案（proposed/）

2026-08-18-docs-governance-and-spec-workflow.zh.md 是一篇典型的 proposed note，Status: proposed。它的## Problem部分系统列举了仓库开发者文档的四个缺陷：文档在无声地腐烂（教已删除的 v1 中间件系统）、层级在误导读者（guides/与references/二分不成立）、决策在蒸发（理由只存在于 PR 讨论串和聊天里）、文档是产品却缺了一半（约 110 篇英文 markdown，中文对照仅一对）。随后以## Proposal提出六部分方案（P1 目标树、P2 frontmatter、P3 门禁、P4 Agent Notes、P5 双语配对、P6 Skills），并在## Alternatives considered中逐一拒绝了六种替代路径（如零 frontmatter 纯路径编码、给过时文档打status: deprecated标记、先翻译后审计等），最后以## Acceptance criteria与## Risks收尾。

值得注意的实践细节：这篇 note 因为指向实现细节，内部还嵌入了变更决策的交叉链接——提案中两项 Phase 0b 决策被后续审计结果取代，便明确标注"已被已落地的审计结果取代"并给出相对链接。

实例二：Phase 0b 审计结果（implemented/）

2026-08-19-phase-0b-doc-audit-outcomes.zh.md 是已落地的 implemented note，Status: implemented。它演示了两点核心用法：

1. spec-first 流程的闭环：原提案（proposed）在 Phase 0b 执行中被发现有两处需要偏离（Chat adapter 与 UI 约定描述的 API 从未落地；提案要求改名全部带域前缀文件，但完成后仍有 24 个此类文件），于是这篇 implemented note 以## Decision明确记录偏离决定：参考文档以现行实现为准，删除两篇 target-architecture 文档；不批量改名现有域前缀文件。
2. 取代关系的显式化：note 明确声明"本 note 只取代上述两项 Phase 0b 决策。原治理提案仍定义目标树、frontmatter、门禁、Agent Notes 与后续推进阶段"——这就是"用新 note 取代并互相链接"的实践。

对照这两篇 note 的英文版（docs-governance 英文版、audit outcomes 英文版），可以看到.zh.md与英文版标题结构完全镜像，仅语言不同。

什么决策"值得"写 note：记录门槛

Agent Notes 体系有一个对 dsh 的有意偏离——dsh 要求每个非平凡 PR 必带 note，而 Cherry Studio 调整为只对"维护者可能合理地重新质疑的决策"要求 note，包括：

• 架构选择
• 跨模块契约
• 数据 / 磁盘 / 线上格式
• 流程变更
• 被否决的方案

理由也很直白：以 Cherry Studio 的日常修复流量，逐 PR 强制写 note 会变成一种"税"而不是记录。这一门槛决定了.agents/notes/下内容的稀缺性——它不是流水账，而是精心挑选的、值得被长期记住的决策。

Spec-first 的 feature 流程

大型 feature 从一条proposed/note 开始，实现前先评审，按其自身的 acceptance criteria 验收，落地后改写为implemented/。文档治理提案本身正是这条流程的第一个实例（Phase 0a 的评审即决策），而 Phase 0b 审计结果完成了它的落地闭环。

与文档治理门禁的联动

Agent Notes 并不是孤立的约定，它与仓库的文档治理体系（门禁脚本）配套运行。当前 package.json 中已经落地了聚合命令：

pnpm docs:check # = docs:check-links + docs:check-structure + docs:check-frontmatter + docs:check-index pnpm docs:index # 重新生成 docs/README.md pnpm docs:check-index # 校验索引是否漂移（--check 模式）

【免费下载链接】cherry-studio🍒 Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio