【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载导读本文围绕 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 它的后果与工具链ConsequencesConsequences 部分给出了两个落地点完整方法论见 Michael Nygard 的原文章仓库文档中以外部链接形式给出如需轻量级 ADR 命令行工具集可参考 Nat Pryce 的adr-toolsadr new、adr link等命令自动生成序号、维护决策间关联。二、仓库中 ADR 体系的真实落地情况ADR-0001 不是一份纸面规范——plannotator 在后续两个多月里把它执行成了一个相当完整的决策生态。截至当前仓库快照adr/目录包含7 份编号 ADRadr/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 模板直接复用段落作用典型内容# NNN. 标题编号 一句话决策主题如# 002. Warm PR Context CacheDate:决策日期如2026-06-30## Status决策状态Accepted/Proposed/Superseded等## Context背景与动机现状痛点、约束、候选方案、取舍考量## Decision明确的决策结论采用什么方案、明确不做什么、接口与流程约定## Consequences后果与代价收益、新增依赖、维护责任、后续演进方向下面逐一拆解这 7 份 ADR说明该模板在实际决策中的用法。四、ADR-001 ~ ADR-004功能类决策实例4.1 ADR-001删除的源文件在保存时重建2026-06-18adr/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-002PR 上下文预热缓存2026-06-30adr/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-003PR 上下文实时更新2026-06-30adr/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-30adr/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-006Guided Review 成为一等公民2026-07-02adr/decisions/006-guided-review-first-class-feature-20260702-192821.md主题把 Guided Review引导式评审从一次性实验升级为代码评审的一等特性。配套文档链完整adr/specs/guided-review-20260702-195351.md、adr/research/SPIKE-guide-*.mddiff 标注复用、启动设置复用、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 Reviews2026-08-15adr/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.mdspec与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.md2026-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 PTYonExit标记面板停止运行时架构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 / recapADR-0001 只定义了记录决策plannotator 进一步用一套配套文档类型把决策前、决策中、决策后都管理起来全部位于adr/目录内文档类型存放位置作用示例SPIKE 调研adr/research/决策前的技术验证与实验SPIKE-mobile-touch-range-selection-20260816.md、SPIKE-git-graph-view-20260618-220909.mdsynthesis 综合adr/research/把 SPIKE 结果收敛为结论synthesis-guided-review-20260702-195351.mdspec 规格adr/specs/把 ADR 落到接口/路由/数据结构级约定github-view-three-stack-20260701-222935.mdimplementationadr/implementation/实现期契约与关键说明guide-share-hosting.md、portable-guided-reviews.mdrecap 复盘adr/阶段收尾与经验沉淀recap-guided-review-20260702-220407.mdintent 意图adr/早期意图记录intent-description-annotation-phase1-20260630-180000.md这一生态的好处是每个重要决策都有为什么ADR 怎么做spec 验证过SPIKE/synthesis 做完了implementation/recap四件套任何接手的人都能在adr/目录里把一条决策的前世今生读完。八、为你的项目落地 ADR可直接套用的清单结合 ADR-0001 与仓库实践落地一套 ADR 治理可以按以下步骤推进建立编号体系adr/NNN-标题-YYYYMMDD-HHMMSS.mdplannotator 风格或adr/decisions/子目录用adr-tools可自动编号统一模板标题、Date:、Status、Context、Decision、Consequences六要素其中Decision务必写清采纳什么 明确不做什么plannotator 的 ADR 几乎都包含明确的非目标范围随代码入库ADR 与代码同 PR 合入保证代码演进决策同步演进允许互相引用与演进如 ADR-003 引用 ADR-002新决策说明对旧决策的继承与修正编号冲突时以标题日期为准仓库中两份 005 即为例证配套调研文档重要决策前先写 SPIKE 验证可行性如 WebTUI 在 Bun 下的 PTY 数据问题就是先在 ADR-0002 里记录了本地验证结论再拍板 sidecar 方案的把后果写透包括新增依赖、运行时的额外进程、失败降级策略如 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赞分享【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载相关推荐GetQzonehistory 完整指南如何三步扫码备份全部 QQ 空间说说GetQzonehistory 完整指南如何三步扫码备份全部 QQ 空间说说 QQ 空间没有面向个人的全量数据导出口你这些年积累的说说的文字、评论和图片都存网页爬虫数据分析Thunderbird for Android 的 ADR 决策记录体系架构决策记录ADR的完整实践指南Thunderbird for Android 的 ADR 决策记录体系架构决策记录ADR的完整实践指南 导读 本文基于 docs/engineering移动开发企业应用用 ADR 记录架构决策Fleet 的架构决策记录体系与实战指南用 ADR 记录架构决策Fleet 的架构决策记录体系与实战指南 Architectural Decision Records架构决策记录简称 ADR是后端前端企业应用运维网络安全上一篇游戏手柄延迟检测技术解析与实战应用下一篇打造高效AI AgentGitHub_Trending/ai/ai-agent-book中的混合检索技术创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考