企业官网建设流程全解析

导读

本文围绕 plannotator 仓库中的 ADR-0001《Record architecture decisions》展开，讲解该开源项目如何借助 Architecture Decision Records（架构决策记录，简称 ADR）这一轻量文档化方法，把"为什么这样设计"沉淀为可检索、可引用、可追溯的工程资产。通过本文，读者将掌握 plannotator 的 ADR 文档规范（Status/Context/Decision/Consequences 四段式）、编号体系与配套决策生态（SPIKE、spec、recap、implementation 等），并能对照仓库内 001~007 号真实 ADR 实例，学会在自己的项目里落地一套类似的架构决策治理流程。

一、ADR-0001：为决策建立"记录制度"

adr/0001-record-architecture-decisions.md是 plannotator 决策治理体系的第一份（也是奠基性的）文档。它发布于 2026-06-16，状态为Accepted（已被接受采纳）。

1.1 它解决的问题（Context）

这份 ADR 的 Context 只有一句话：

We need to record the architectural decisions made on this project.

（我们需要把本项目上做出的架构决策记录下来。）

听起来朴素，但它指向的是一个普遍存在的工程痛点：架构决策往往散落在会议纪要、PR 讨论、聊天记录和个人记忆里，时间一长，"当时为什么这么选、否决了什么方案"就完全不可考。ADR 方法正是为了对抗这种**决策失忆（decision amnesia）**而设计的。

1.2 它做出的决定（Decision）

决策本身同样简洁：采用 Michael Nygard 在 2011 年提出的 Architecture Decision Records 方法，即"一篇决策 = 一份结构化、短小精悍的 Markdown 文档"，并保持决策记录与代码一起入库、随项目版本演进。后续所有编号 ADR 均严格沿用了这一格式。

1.3 它的后果与工具链（Consequences）

Consequences 部分给出了两个落地点：

1. 完整方法论见 Michael Nygard 的原文章（仓库文档中以外部链接形式给出）；
2. 如需轻量级 ADR 命令行工具集，可参考 Nat Pryce 的adr-tools（adr new、adr link等命令，自动生成序号、维护决策间关联）。

二、仓库中 ADR 体系的真实落地情况

ADR-0001 不是一份"纸面规范"——plannotator 在后续两个多月里把它执行成了一个相当完整的决策生态。截至当前仓库快照，adr/目录包含：

• 7 份编号 ADR：adr/decisions/001~adr/decisions/007；
• 大量配套文档：adr/specs/（规格）、adr/research/（SPIKE 调研、synthesis 综合结论）、adr/implementation/（实现说明与复盘）、adr/intent-*.md（意图记录）、adr/recap-*.md（阶段回顾）等。

也就是说，ADR-0001 只规定"记录决策"，而仓库实际把它扩展为一条**从调研（SPIKE）→ 决策（ADR）→ 规格（spec）→ 实现（implementation）→ 复盘（recap）**的完整决策流水线。

三、编号 ADR 的统一模板（从 7 份实例归纳）

虽然 ADR-0001 原文没有给出本地模板，但仓库中 001~007 号决策记录在结构上高度一致，可作为"plannotator 风格的 ADR 模板"直接复用：

下面逐一拆解这 7 份 ADR，说明该模板在实际决策中的用法。

四、ADR-001 ~ ADR-004：功能类决策实例

4.1 ADR-001：删除的源文件在保存时重建（2026-06-18）

adr/decisions/001-source-file-deletion-recreates-on-save-20260618-105753.md

主题：annotate/编辑模式下，若用户（或外部工具）删除了正在编辑的源文件，Plannotator 在下次保存时将其重建，避免"编辑器持有内容、文件却不存在"的不一致状态。该决策与packages/shared/source-save.ts、packages/core/source-save.ts以及packages/editor/sourceDocumentReconciliation.ts等保存/对账逻辑直接相关。

4.2 ADR-002：PR 上下文预热缓存（2026-06-30）

adr/decisions/002-pr-context-warm-cache-20260630-110601.md

主题：在服务启动和 PR 切换时就开始预取 PR 上下文（描述、评论、checks、merge 状态），使/api/pr-context能够等待"已经开始的工作"而非串行拉取，降低 PR 概览面板的首屏等待。对应实现见packages/shared/pr-context-live.ts、packages/server/reference-watch.ts等。

4.3 ADR-003：PR 上下文实时更新（2026-06-30）

adr/decisions/003-live-pr-context-updates-20260630-114643.md

这份 ADR 是理解"ADR 如何互相引用、演进"的极佳案例。它的 Context 明确写到："ADR 002 added a warm PR context cache..."，即 002 引入的一次性会话缓存仍不够——评论或 checks 在评审期间变化时 UI 不会自动更新。于是 003 决定：

• 将 PR 上下文升级为服务端持有的实时缓存：每个 PR URL 一条缓存条目，跟踪最新上下文、版本、in-flight 刷新、watcher 数、刷新定时器与限流冷却；
• 新增 SSE 端点GET /api/pr-context/stream，客户端在 PR 模式下自动订阅；
• 每 30 秒按 PR URL 刷新一次，而非按浏览器标签页刷新；同一时刻绝不启动第二个并发刷新；
• 最后一个 watcher 断开时停止该 PR 的定时刷新；
• /api/pr-action成功发帖后立即刷新目标 PR 并广播；
• 遇到 GitHub/GitLab 限流错误时保留最后一次成功上下文，标记 stale/error，按 provider 重试时间或保守冷却后自动重试。

Consequences 明确记录了"未做什么"：本决策不实现双向评论，只建立服务端单一视图、写入后立即对账等基础，为将来"pending / posted / failed / synced"四种评论状态留出位置。

值得注意：003 同时提到了"两个 review server 实现"——仓库中 PR 相关逻辑分布在packages/shared/pr-github.ts、pr-gitlab.ts、pr-context-live.ts，以及服务端packages/server/live-proxy.ts等文件中，多运行时/多 provider 的一致性正是 ADR 反复强调的约束。

4.4 ADR-004：对 PR 描述与评论做标注，喂给 Agent 反馈管线（2026-06-30）

adr/decisions/004-annotate-pr-description-and-comments-20260630-155000.md

主题：把标注（annotation）能力从代码差异扩展到 PR 描述与评论本身，标注结果进入 agent-feedback 管线，供一键把评审意见反馈给编码 Agent。这与仓库核心定位"annotate and review coding agent plans and code diffs visually, ... send feedback to agents with one click"一脉相承，对应packages/server/annotate.ts、packages/shared/external-annotation.ts、pr-artifact-document.ts等实现。

五、ADR-005 ~ ADR-007：架构与产品方向决策实例

5.1 ADR-005 的两份同号文档：一次"纠偏"记录

有意思的是，adr/decisions/下存在两份 005 号 ADR，时间相近：

• 005-since-base-github-view-default-20260701-223706.md：# 005. "Since main" composite diff as the default code-review view——把"相对主分支的复合 diff"设为代码评审默认视图；
• 005-publish-document-ui-as-packages-20260701-150551.md：# 005. Publish the document UI as @plannotator/ui + @plannotator/core——把文档 UI 发布为两个 npm 包。

同号文档并存说明：ADR 编号并非严格串行，实践中可能出现并行起草后未重编号的情况。这对读者是一个真实提醒——ADR 编号出现冲突时，应以内容标题与日期为准，编号仅作索引参考。

5.2 ADR-006：Guided Review 成为一等公民（2026-07-02）

adr/decisions/006-guided-review-first-class-feature-20260702-192821.md

主题：把 Guided Review（引导式评审）从一次性实验升级为代码评审的一等特性。配套文档链完整：adr/specs/guided-review-20260702-195351.md、adr/research/SPIKE-guide-*.md（diff 标注复用、启动设置复用、provider tour 模式、布局接管等四份 SPIKE）与adr/implementation/portable-guided-reviews.md；代码侧有packages/core/guide.ts、guide-format.ts、packages/guide-viewer/、packages/review-editor/与packages/server/guide/目录支撑。

5.3 ADR-007：可移植的 Guided Reviews（2026-08-15）

adr/decisions/007-portable-guided-reviews-20260815.md

主题：让 Guided Review 可脱离原仓库导出/分享——下载便携式 guide 文件或生成分享链接（plannotator guide share --id <saved> | --guide g.json --patch p.patch | --snapshot s.json [--public] [--ttl 7d|24h|30m|3600] [--json]，以及plannotator guide unshare <id> --token <t>撤销分享）。配套文档：adr/specs/portable-guided-reviews.md（spec）与adr/implementation/guide-share-hosting.md（分享托管契约，明确"路由、形状与错误码在那里是最终的，改动必须先改文档"）。实现见packages/server/guide/、packages/shared/guide-store.ts、apps/guides-show/等。

六、ADR-0002：一份完整的落地样例

作为"从规范到实践"的最佳范本，adr/0002-add-webtui-agent-panel-for-annotate-mode.md（2026-06-16，状态 Accepted）演示了如何把 ADR-0001 的模板用于一个中等复杂度的架构决策——为 annotate 模式加入 WebTUI Agent 终端面板。其决策要点包括：

• 范围界定：仅适用于plannotator annotate（单文件与文件夹标注），不适用于 plan review、code review、archive、goal setup、annotate-last；
• 启动成本为零：打开 annotate 会话不启动 Agent、不分配 PTY，直到用户显式启动；首次打开显示启动视图，用户选择 Agent 并可保存为后续默认；
• 布局约定：[ Agent terminal panel ] [ Files/TOC sidebar ] [ Document ] [ Annotations/AI panel ]，终端面板与文件侧栏分离、可缩放可折叠；
• 进程与清理：在 Plannotator 原始启动目录启动所选 WebTUI 内置 Agent；停止/关闭时先发中断输入、必要时 kill PTY；onExit标记面板停止；
• 运行时架构：Bun annotate server 用 Bun WebSocket runtime 实现浏览器端 WebSocket 路由，并懒加载转发给 Node sidecar（绑定随机 loopback 内网端口、仅在启动终端时启动、不对浏览器暴露），Pi Node annotate server 则把 WebTUI Node WebSocket server 挂到既有 Node HTTP server 上——两个运行时暴露相同的浏览器端路径与能力形状；服务关闭必须清理 PTY 会话；
• 明确不做什么：v1 不提供任意命令框、不自动注入 prompt、不同步标注、不集成文件侧栏、不支持多 Agent 与后台 Agent 任务；
• 后果与风险：新增 WebTUI / node-pty 依赖；若 node-pty 无法加载，annotate 模式必须继续工作并禁用终端面板且给出清晰提示；Bun 运行时多一个 Node sidecar 进程是有意为之——本地验证显示NodePtyBackend在 Bun 下能启动 PTY 却不回传终端数据，而 Node 下 shell 与 Claude 输出均正常，sidecar 把这一风险边界隔离在终端传输层。

这份 ADR 的"Context → Decision（含明确的 In/Out 范围）→ Consequences（含风险与有意取舍）"结构，正是 ADR-0001 方法论的完整演绎。

七、配套决策生态：SPIKE / spec / implementation / recap

ADR-0001 只定义了"记录决策"，plannotator 进一步用一套配套文档类型把决策前、决策中、决策后都管理起来（全部位于adr/目录内）：

这一生态的好处是：每个重要决策都有"为什么（ADR）+ 怎么做（spec）+ 验证过（SPIKE/synthesis）+ 做完了（implementation/recap）"四件套，任何接手的人都能在adr/目录里把一条决策的前世今生读完。

八、为你的项目落地 ADR：可直接套用的清单

结合 ADR-0001 与仓库实践，落地一套 ADR 治理可以按以下步骤推进：

1. 建立编号体系：adr/NNN-标题-YYYYMMDD-HHMMSS.md（plannotator 风格）或adr/decisions/子目录；用adr-tools可自动编号；
2. 统一模板：标题、Date:、Status、Context、Decision、Consequences六要素，其中Decision务必写清"采纳什么 + 明确不做什么"（plannotator 的 ADR 几乎都包含明确的非目标范围）；
3. 随代码入库：ADR 与代码同 PR 合入，保证"代码演进，决策同步演进"；
4. 允许互相引用与演进：如 ADR-003 引用 ADR-002，新决策说明对旧决策的继承与修正；编号冲突时以标题+日期为准（仓库中两份 005 即为例证）；
5. 配套调研文档：重要决策前先写 SPIKE 验证可行性（如 WebTUI 在 Bun 下的 PTY 数据问题，就是先在 ADR-0002 里记录了本地验证结论再拍板 sidecar 方案的）；
6. 把后果写透：包括新增依赖、运行时的额外进程、失败降级策略（如 node-pty 不可用时的禁用提示）、以及未来演进方向。

九、总结

ADR-0001 用最少的文字为 plannotator 确立了"记录架构决策"的制度，而仓库随后用 7 份编号 ADR 与数十份配套文档证明了这套制度的价值：决策可追溯（Context）、边界清晰（Decision 中的 In/Out）、代价透明（Consequences）、方案可验证（SPIKE/synthesis）。对任何正在快速演进的工程而言，这都是一份成本极低、回报极高的治理模式——值得直接照搬。

参考文件索引（仓库内）

• ADR-0001 原始决策
• ADR-0002 WebTUI Agent 终端面板
• ADR 001~007 编号决策集
• ADR 规格集 · ADR 调研集（SPIKE/synthesis） · ADR 实现集
• 相关实现佐证：packages/shared/pr-context-live.ts · packages/server/pr.ts · packages/core/guide.ts · packages/shared/guide-store.ts · packages/server/annotate.ts