把一次评审导出成单文件快照:不装环境也能传阅的评审记录
把一次评审导出成单文件快照:不装环境也能传阅的评审记录
当编码智能体替你写完一个 PR 之后,评审环节绕不开一个尴尬的场景:评审发生在某台机器上跑着的 Plannotator 会话里,但需要看结论、需要补刀的人往往只想要"那个页面"。装 Bun、装 Plannotator、把仓库 clone 下来、重放一遍 diff——对一次只需要传阅的评审记录来说,成本严重不对称。
Plannotator 的答案是 Portable Guided Review:把一次 Guided Review 导出为一个小的 HTML 文件,文件里装下评审的全部内容,渲染器则从 guides.show(一个 Cloudflare Worker + R2 站点)按需拉取。这份能力的决策记录是 adr/decisions/007-portable-guided-reviews-20260815.md,实现规格在 adr/implementation/portable-guided-reviews.md,格式代码在 packages/core/guide-format.ts,宿主服务在 apps/guides-show。下面拆开看:快照里到底打包了什么、渲染器怎么部署、以及把它当评审留痕时的边界。
一、单文件快照里到底打包了哪些内容
1. 一个版本化、严格解析的 snapshot 文档
导出的 HTML 不是一个"截图",而是一份自描述的 JSON 文档嵌在页面里。核心逻辑在 packages/core/guide-format.ts:快照带 kind: "plannotator-guided-review" 和 version,parseGuideSnapshot 是严格解析器——任何一层出现未知字段都会带 JSON path 报错拒绝,而不是静默丢弃。字段大致分五块:
guide:title、intent、sections[{ title, overview, diffs[{ file, summary }] }]、unplacedFiles、reviewed[]——评审的章节化叙述本身;review:rawPatch(完整的 unified diff)、gitRef、diffType、base——评审针对的变更本体;source:kind(local/pr/workspace/commit)、repo、branch、headSha、pr{ url, number, title, platform }等——这份评审是"评的什么",页头必须如实写明;generator:engine、model、generatedAt、customInstructions——provenance,说明是哪种智能体、什么模型、在什么时间生成的;theme?:导出器的调色板提示。
格式本身也在演进:v1 是基础形态,后续版本按需叠加 overview(v2,带 Mermaid/HTML 图)、diff 行级 notes(v4)、章节 diagram(v5)。关键纪律是升版才升号:guideSnapshotVersionFor 保证没有新内容的指南仍然构建出与旧版逐字节一致的 v1 文档,这样"旧版本导出的 HTML 里钉着的旧查看器"永远不会收到它解析不了的字段。每个版本在 guide-format 下有 fixture,兼容性测试要求当前解析器必须能解析所有已发布的 fixture——这是格式向后兼容的机器保证。
2. 文件大小 ≈ diff 大小,而不是应用大小
规格里 D1 的措辞很直白:the artifact is one small HTML file whose size is the diff, never the app。这背后有一段失败史:更早的尝试把整个评审应用打进 HTML(17–18 MB),或引用营销 CDN 上一个会变的 v1/viewer.js,且只能导出内存中当前的 guide。新方案里:
- diff 不设上限——大 diff 产生大文件,那是用户的决策;被明确拒绝的是"应用基线"带来的多 MB 常数开销;
- 结构上的健全性上限只有
sections ≤ 100、diff refs≤ 50,000,保证解析有界; - 语法高亮的语言列表不存,而是从
rawPatch的文件扩展名推导(detectGuideLanguages),HTML 里只为这些语言modulepreload对应 chunk。
3. diff 在"任务启动时"被捕获,而不是导出时
一个容易踩坑的问题:用户发起 Guided Review 之后、导出之前,工作区里的 diff 可能已经变了。规格 D6 的对策是:在 guide 任务 launch 时就捕获 launch-time patch(buildCommand 的 guide 分支返回 launchReview: { rawPatch, gitRef, diffType, base, source }),服务端随 guide 一起落盘为 {id}.patch(原子写、与 {id}.json 同生共死),导出时永远读这份落盘的 patch,绝不读屏幕上当前的 diff。集成测试专门覆盖了"launch → 切换 diff → 导出 → 快照 patch 等于 launch 时 patch"这条链路。
4. 离线可读的兜底正文
createGuideHtml 在 <div id="root"> 里先渲染一份纯文本版评审——标题、meta、intent、每章标题+overview+文件清单+摘要,全部 HTML 转义——然后才挂 <script id="plannotator-guided-review" type="application/json"> 的完整快照和外部 viewer 脚本。断网、被拦截或禁 JS 时,读者看到的是可读的章节化摘要而不是白屏。一个细节:兜底正文通过 CSS 动画在前 2.5 秒保持透明(纯 CSS,无脚本),冷缓存下下载 viewer 的人看到的是主题底色 → 骨架 → 正式页面,而不会先闪一下兜底文字再"跳变"。
二、轻量查看器的部署方式与访问成本
1. 一个渲染器,两个宿主:漂移在结构上不可能
D2 的决定是把应用内评审用的整条渲染链(GuideView → GuideSectionCard → GuideFileCard → GuideViewportManager → AllFilesCodeView,底层是 @pierre/diffs 的只读模式)搬进独立包 @plannotator/guide-viewer。Plannotator 的评审应用从那里 import 回来,导出的 CDN viewer 打的是同一条链。"应用内和导出文件长得一样"因此不是承诺,是结构事实。只读宿主的标注/编辑机构(CommentPopover、FileCommentBanner 等)在构建期被 stub 掉(apps/guides-show/viewer/stubs),不会进包。
2. guides.show:Cloudflare Worker + R2,内容寻址、永不覆写
apps/guides-show/worker/index.ts 的 Worker 做三件事:从 R2 的 guides-show-viewer bucket 发 /v1/* 静态资产;从 guides-show-guides bucket 发共享指南(/g/<id> 与 /api/g*);其余落到静态落地页。为什么 /v1/ 必须用 R2 而不是 Workers Static Assets?代码注释说得很清楚:Static Assets 是每次部署的快照,下一个部署缺少的文件会消失;而每一个历史导出的 HTML 都按 URL + SRI 钉死了某个 viewer 构建,必须永远能打开。所以部署脚本是 add-only 的:只添加内容哈希命名的文件,同名不同内容直接失败。
资产头(viewerAssetHeaders)针对 file:// 场景做了完整配置:
Cache-Control: public, max-age=31536000, immutable;Access-Control-Allow-Origin: *——file://文档的 Origin 是null,没有这条 CORS,本地打开的 HTML 根本拉不到 viewer;Cross-Origin-Resource-Policy: cross-origin。
3. 按需拉取:每语言一个 chunk,字体按子集发
CDN 构建(apps/guides-show/vite.viewer.config.ts)是多文件构建:inlineDynamicImports: false,Shiki 的语法懒加载器让 Rollup 自动把每种语言切成一个 /v1/langs/<lang>.<hash>.js chunk(实测 235 个语法 chunk)。导出的 HTML 只 modulepreload 自己 patch 里实际出现的语言。字体是 Inter + Geist Mono 的 latin 子集(约 78 KB)。CI 有硬预算:viewer.js ≤ 1.2 MB raw / 400 KB gzip,viewer.css ≤ 120 KB / 30 KB,HTML 壳(快照以外的一切)≤ 25 KB——也就是说,一个"应用"的成本被压到了几百 KB gzip 量级,且被浏览器按语言子集进一步裁剪。
4. 高亮 worker:现场探测,而不是猜浏览器行为
导出文件跑在 file:// 下时是独立 origin,worker 脚本必须从 guides.show fetch 回来在本地构造。但各浏览器对 file:// 下 blob/data worker 的态度不一致——Chrome 会异步地拒绝 blob module worker(控制台报 "cross-origin redirects of the top-level worker script"),却接受 classic blob worker;而带 --allow-file-access-from-files 的无头测试会把这个差异掩盖掉。所以 apps/guides-show/viewer/portablePool.tsx 的做法是每次页面加载做活体探测:按 blob classic → blob module → data classic → data module 顺序试,worker bundle 本身是 import-free 的(构建期断言)才能以 classic 运行;池子 4 秒内没初始化就被 PoolWatchdog 丢弃,指南回退到主线程渲染——死掉的 worker 池永远不会让 diff 空白。
5. 共享链接:默认端到端加密,部署成本是一个 Worker
同一套设施还支撑"发链接而不是发文件"。契约在 adr/implementation/guide-share-hosting.md:
POST /api/g两种模式。encrypted(默认):上传的是encrypt(compress(snapshot))(复用@plannotator/core/crypto+compress),密钥只存在于 URL 片段#key=…——浏览器从不把 fragment 发给服务器,所以宿主拿到的只是读不懂的密文,页面只是个 fetch/api/g/<id>后在浏览器里解密的 shell。plain(--public/ "允许链接预览"):明文存快照 JSON,服务器端校验后页面才能带og:title等标签,供聊天软件 unfurl。- 访问控制只有两样:25 MiB 存储上限(
413)和仅针对创建的每 IP 限速(Cloudflare 原生[[ratelimits]]绑定,20 次/分钟,超限429 + Retry-After: 60;读、删除、预检、/v1/资产一律不限)。限速是 WorkerEnv里的可选绑定,任何解析不了的方向都 fail-open——"坏掉的刹车不能是阻止分享的东西"。 - 删除用一次性
deleteToken(16 随机字节 base64url,服务端只存 SHA-256);无默认过期——"一条定时死掉的评审链接比一个文件更糟糕",保留期是刻意决定;只有上传方自己带ttlSeconds才过期,且过期在读取时惰性执行。 - 自托管就是部署同一个 Worker:在自己的 Cloudflare 账号下建两个 R2 bucket,
bun run build:viewer && bun run deploy:viewer加wrangler deploy(apps/guides-show/README.md),然后把PLANNOTATOR_GUIDE_SHARE_URL/PLANNOTATOR_GUIDE_VIEWER_URL指过去;PLANNOTATOR_SHARE=disabled一键关分享。托管页面带 hosted meta 和客户端 Download 按钮——按钮用 DOM 里反推的 viewer pin 在本地重建那个可下载文件,"链接永远不会把指南困在宿主上"。
6. 导出本身是一个纯函数,三个调用方
(snapshot) → HTML 只存在一份(createGuideHtml,无 I/O),调用方有三个(D9):应用内 Share 菜单的 "Download portable guide (N KB)";CLI 的 plannotator guide export;以及 agent 路径。CLI 的三种输入形态(packages/server/guide/guide-cli.ts):
# 导出 Plannotator 保存过的 guide
plannotator guide list
plannotator guide export --id <savedGuideId>
# agent 形态:agent 只写 guide.json 并交出 git diff,
# CLI 严格校验 guide 对 patch(未知文件/重复文件都是报错并列出 patch 里有哪些文件),
# 从当前目录的 git 推断 repo/branch/headSha,再走严格 parser round-trip
plannotator guide export --guide guide.json --patch guide.patch --out -
# 完整 snapshot 文档
plannotator guide export --snapshot snapshot.json
退出码统一为 0 成功 / 1 未找到、不可导出、校验失败 / 2 用法错误。这个"agent 只负责写讲解,CLI 负责校验和打包"的分工,让没有装 Plannotator 的人也能通过智能体技能拿到指南文件——规格里原本规划为第三个调用方,后来以独立 skill 仓库(plannotator/guides,不随主仓库分发)的形式落地,且"无需重新设计"。
三、把快照当成评审留痕时的边界与局限
1. 只读,且 v1 明确不带标注。 D3 决定了导出是 read-only:能滚、能折叠章节、能跳文件、能切深浅色、有会话内不持久化的 "reviewed" 勾选;但评审者的标注和 PR 评论线程不进导出。格式为 v2 保留了 annotations 块,viewer 也留着标注槽位(codeViewProps 的类型仍然携带 annotations 字段),后续加共享反馈不破格式。作为"留痕",它留的是"这次评审是怎么讲解的",不是"评审过程中发生了什么争论"。
2. 只渲染 guide 屏幕,永不发服务器调用。 D4 规定文件里只出现 guide 界面——没有文件树、all-files 视图、搜索、approve/反馈。CSP 是 default-src 'none',connect-src 只有 viewer origin(共享托管页再加自身 origin),form-action 'none'、base-uri 'none'、frame-src 'none'。Playwright 在 file:// 导出上验证过:除 guides.show 外零请求。
3. 它不是自包含的——这是刻意的取舍。 完全离线看完整的 diff 视图是做不到的:渲染器在 guides.show,文件只带纯文本兜底。规格里明确拒绝了 17 MB 的"fully self-contained"路线。作为留痕时这意味着两点:接收方打开完整体验需要能访问 guides.show(或你的自托管 viewer base,可用 PLANNOTATOR_GUIDE_VIEWER_URL / --viewer-url 指);以及留痕的可用性依赖 CDN 的存续——缓解措施是内容寻址 + add-only 部署让每个历史导出钉的 URL 永远有效,加上托管页/导出文件可互相转存。自托管场景下这条依赖可以完全移除。
4. 严格的版本化是双刃剑。 严格解析器 + 未知字段即拒绝 + 每版本 fixture 的兼容测试,保证了旧文件永远被新代码正确理解、新内容绝不会被旧渲染器错误解释。代价是格式演进必须走"升版号 + 双解析"流程,快照文档不能携带任意扩展字段。
5. 托管链接的保留策略偏"永久"。 无默认 TTL、无 operator 寿命上限、过期指南直到被打开才删除。对个人留痕是优点(链接不会神秘地失效),但对含敏感代码的 plain 共享是需要注意的:默认 encrypted 模式是主防线(宿主只持有密文),--public 一旦开出去,快照 JSON 就是明文躺在 R2 上,删除只能靠那个只显示一次、建议立刻存好的 deleteToken(plannotator guide unshare <id> --token <t>)。另外每个已保存 guide 在同一时间只允许一条分享链接(第二次上传 409),因为 envelope 记录是 token 的唯一存放处。
6. provenance 是数据不是水印。 快照里记录 engine、model、generatedAt、customInstructions,页头如实声明 source kind 与 git 坐标(launch-time 的 headSha,不是导出时的)。它回答"这份评审评的哪一版",但不防篡改——文件本身没有签名机制,SRI 校验的是 viewer 构建而不是你的快照内容。需要防篡改的场景,快照 JSON 是可单独审计的纯文本,可以走自己的哈希存档流程。
结语
这套设计里值得注意的其实不是"导出一个 HTML"本身,而是几条工程纪律:文件大小等于内容大小(拒绝应用基线开销)、一个渲染器两个宿主(拒绝"轻量版"漂移)、内容寻址 + SRI 钉死(历史文件永久可开)、严格版本化格式(兼容是测试出来的不是承诺出来的)、默认加密 + fail-open 的刹车(匿名分享服务的安全下限)。评审记录从"会话里的一个页面"变成"一个可以进邮件、进归档、跨组织传阅的文件",靠的不是加功能,而是在这些约束下把功能做出来。对正在做"智能体产出物可分享化"的团队来说,adr/decisions/007-portable-guided-reviews-20260815.md 里 D1–D12 每条决策都带可验证的 check(见实现规格 §Verification matrix),本身就是一份可直接抄的决策记录模板。
