Files
streamline/docs/逼近AI实现报告可读性的极限.md
2026-11-16 17:26:44 -08:00

17 KiB
Raw Permalink Blame History

逼近 AI 代码实现报告可读性的极限

一份关于「如何科学地把 AI 生成的代码实现/修复报告,逼近可读性的极致边界」的工程方法论。

素材来源:本仓库中 readable-report 管线的完整演进史(shared/src/readable_prompt.ts、control-server/src/lab_db.ts、satellite/src/{runner,feature_runner}.ts),以及 jingyuan.yi 名下从 0584742(管线雏形)到 5ce7596(demo 视频成为核心证据)的一连串提交。本文把这些提交里的「为什么」抽象成可迁移的原则。


0. 先把问题的形状看清楚

我们要优化的不是「一段 prompt」,而是一条两段式管线:

 [Runner Agent]                         [Readable Generator]              [Host 渲染]
 干活的 agent  ──写──►  FixReport.md ──喂──►  第二个 LLM  ──产出──►  llm-report HTML ──►  reviewer 眼睛
 ImplReport.md         (verbose 工程原文)     (pixel-blind)      (封闭 class 词表)
   ▲                                              ▲
   生产者:证据、根因、验证都在这里产生            格式化者:只做「压缩 + 结构化」,看不见像素

目标函数(写死在 prompt 里,shared/src/readable_prompt.ts:54):

reviewer 在 60 秒内理解:用户/评审关心什么 · 根因 · 改了什么 · 怎么证明的 · 验证的局限与回归风险。

注意读者是 reviewer 而不是终端用户。这决定了「可读性」在这里的定义不是「好看」,而是 信息密度 × 可信度 / 阅读时间。后面所有 know-how 都是这个分式的因式分解。


1. 第一性原理:可读性 = 信息密度 × 可信度,不是排版

把目标函数拆成三个可优化的乘子,逐个击破:

① 提升信息密度 —— skip-don't-pad。 prompt 里反复强调的一句话是「ONLY when the source actually has that data — skip a block entirely rather than padding it with an empty card」(readable_prompt.ts:82)。空卡片、凑数的段落是负信息:它稀释密度、还骗过读者以为「覆盖全了」。 → 宁可少一个 block,不要一个注水的 block。

② 保护可信度 —— 反过度声称。 「never overclaim validation; when live/E2E proof is missing, say so via the note block」。系统专门给「验证被阻塞/缺失」造了一个视觉出口:琥珀色 llm-report__note + ⚠ 阻塞 的 metric。给诚实一个专门的位置,模型才不会用乐观的措辞去填补空白。对 reviewer 而言,一份敢说「活体复现环境离线、我没能证明」的报告,比一份滴水不漏的漂亮报告更可信。

③ 压缩阅读时间 —— 分层 + 渐进式披露。(见 §5)

这三条是纲。剩下的章节都是在讲「怎么在工程上真的做到」。


2. 决定性洞察:下游的天花板在上游(pixel-blind 定律)

这是整条管线里最重要、也最反直觉的一条,值得单独成章。

格式化者是 pixel-blind 的——它拿到的是一堆截图文件名和报告里对每张图的文字描述,它从来没有、也不可能「看见」像素。提交 d2934ed / 520412d 的 message 把这句话钉死了:

The readable-report generator is pixel-blind … so ImplReport quality is the ceiling.

推论极其锋利:你无法把第 N 段打磨到超过第 N-1 段给它的信息量。 当读者觉得报告「说不清这张图证明了什么」,99% 的情况不是格式化 prompt 不行,而是上游的 runner 根本没在原文里讲清楚这张图证明了什么。

所以这两个提交做的事,不是改 readable prompt,而是回头去改「干活的 agent」的 prompt(buildSinglePrompt / buildFeatureFirstPrompt):

  • 要求 runner 用语义化证据命名;
  • 要求 runner 产出一份测试图清单;
  • 把 FixReport 的章节结构重排成与下游 block 一一对应。

工程 know-how #1:要提升第 N 阶段的产出,先去优化第 N-1 阶段。 在 prompt 上反复微调下游,收益会迅速见顶;真正的边界由上游的信息供给决定。定位问题时永远先问一句:「下游想渲染的这个东西,上游到底喂给它了没有?」


3. 把每一次跨阶段交接,变成一份被校验的契约

既然两个阶段之间是「盲」的,那它们之间传递的每一个 bit 都必须是显式契约,而不是靠模型「悟」。

3.1 语义化证据命名 = 盲阶段之间的唯一带宽

命名约定:<phase>-<round>[-NN]-<slug>.<ext>,phase ∈ before / after / flow / mech / edge / demo。 对一个看不见像素的格式化者,文件名本身就是它能读到的最结构化的信息。before-1-xxx.png 和 after-1-xxx.png 同名同场景配对,格式化者才能把它们拼成决定性的「修复前/修复后」对比(readable_prompt.ts 的 测试图对比 block)。

3.2 测试图清单(shot index)= 把「文字描述」也变成契约

520412d 要求 runner 额外产出一份清单:每张截图 + 一句「它证明了什么」+ 角色。commit message 里那句话是点睛:

the only thing the generator can read to pick and caption images.

这就是在承认「你看不见图,所以我把图的语义先替你写成结构化文本」。

3.3 URL-free 证据契约:不让模型 mint 自己无法核实的标识符

格式化者绝不允许输出 <img> / src / href / 任何 URL——因为它一定会幻觉出不存在的路径。取而代之:模型只在 <figure> 上写 data-evidence="<精确文件名>",host 拿这个文件名去解析成真实 URL,幻觉出的名字直接被丢弃(16feaaa:hydrateShots/injectShots)。

工程 know-how #2:凡是模型无法自行核实的标识符(URL、ID、路径),都给它一个封闭清单 + 占位符间接层,最终在宿主侧做校验丢弃。 幻觉不是靠「叮嘱模型别幻觉」消除的,是靠「让幻觉在架构上无处可去」消除的。

这条同样体现在 runner 侧:run 的成败靠终止哨兵(STATUS / ASSESSMENT)判定,而不是退出码——9776cd1 揭示,pty wrapper 会给 API Error 合成一个假的 success 帧,只有显式哨兵才能区分「agent 真的下了结论」和「基础设施把它打断了」。契约要显式,不要从副信号里猜。


4. 约束输出空间:封闭词表 > 开放建议

这是把「格式化者耦合到渲染器」这件事做到底的一步,也是可读性从「像 AI 随手写的」跃迁到「像人精心排的」的关键。

对比 v0(0584742)和 v1(9dc9abb)的措辞:

v0(雏形) v1(现行 SSOT)
class 约束 「class names must be prefixed with llm-report」 「Use ONLY these classes. NEVER invent — an unknown class has zero styling and renders bare」
结构 「Suggested class structure」 「MUST use the structural markup … Do NOT collapse into plain <p>」

为什么这个改动是决定性的?因为 host 页面的 CSS 只给一组固定的 class 上了样式。模型一旦发挥创意造一个新 class,那段内容就以零样式的裸文本渲染出来——排版当场崩掉。开放式的「建议」必然导致漂移;封闭词表把输出空间收缩到「渲染器真的能渲染」的那个子集。

同理,「结构化标记 vs 裸 prose」也是一条硬规则:模型的默认倾向是写段落,而段落在这个 host 上「completely unstyled」。所以 prompt 用大量篇幅给出 timeline / cards / steps / metrics 的逐字模板,堵死「塌回 prose」这个失败模式。

工程 know-how #3:生成结构化 UI 时,prompt 必须精确暴露「渲染器能渲染的那张表面」,并显式禁止一切表面之外的发挥。 生成器与渲染器是一对必须同步演进的耦合体——每加一个 CSS class,就得同步进封闭词表;每进一个词表项,host 就得有对应样式。二者漂移,报告立刻裸奔。


5. 分层与渐进式披露:为「60 秒」做减法

阅读时间这个分母,靠两件事压下来。

① 双语域分层——同一份报告服务两类读者。

  • 大白话总结:写给零 Android/Compose 背景的 PM/设计,禁止出现任何方法/变量/框架/OS 名,允许一个类比,把唯一的关键修复思路包进一个 <em>。
  • 其余 block:给工程师看,标识符一律 <code> 保留原文。

一个 artifact,两个寄存器,读者各取所需,谁都不用读对自己是噪声的那半。

② 渐进式披露——把「crux」浮上来,把「全量」折下去。

  • 关键代码变更 只放 单个最决定性的 hunk,≤25 行,其余用一行 … 省略,且强制装进默认折叠的 <details>(4436c40)。全量 diff 是噪声,crux 才是信号;默认收起,让报告的「阅读海拔」始终保持在高处。

③ 证据分级——最有力的证据顶到最前。 证据形态经历了三次进化,每次都把「更决定性的证据」往前提:

截图 (16feaaa) ──►  before/after 英雄对比 + 验证画廊 (16feaaa/7ff55d4) ──►  端到端 demo MP4 置顶 (5ce7596)

5ce7596 让 demo 录屏成为「核心证据」,排在前后对比截图之前。值得学的实现细节:media-hero 模板是用字符串手术从 baseline 派生的(readable_prompt.ts:315),共享 block 一个字节都不会漂移,只有媒体那一段不同——变体不靠复制粘贴,靠从 SSOT 派生。


6. 决定论与鲁棒性:容易被忽视的底座

可读性的边界,一半输在这些「不性感」的底层细节上。

① 语言必须是无条件显式指令。 527a2db 的教训:prompt 里没写死输出语言时,只要上下文是英文,模型就漂移到英文。修复是加一条无条件指令 + 列清例外(<code> 里的标识符、固定中文标签保持原文)。凡是「希望模型总是 X」的属性,都不能靠上下文暗示,必须显式写死并枚举例外。

② 替换层要抗污染。 renderReadablePrompt(readable_prompt.ts:363)有三个刻意设计:源 markdown 最后才替换(防止其中的 {{...}} 或 $ 破坏后续替换);用函数式 replace(绕开 $&/$1 的特殊模式解释);超长显式截断并留 [TRUNCATED] 标记。不可信内容永远最后注入,是模板拼装的基本卫生。

③ 警惕「数据缺失」伪装成「prompt 不行」。 1b1db98 是最好的反面教材:多轮修复的 修复历程 timeline 一直渲染不出来,看起来像 prompt 问题。真相是——磁盘上每轮只保留一个 FixReport.md,agent 每轮覆盖它,所以下游根本没收到多轮数据。commit message 一针见血:

The prod prompt template is already multi-round-aware … so no prompt change was needed — it just never received the data.

修复在数据管线(按轮归档进 fix_report_versions),不在 prompt。

工程 know-how #4:调 prompt 之前,先确认 prompt 真的收到了它索要的数据。 「prompt 已经会渲染 X,只是从没拿到 X」是这类系统里最高频、最费解的一类 bug。

④ 生产者的鲁棒性 = 报告的保真度。 9776cd1:API Error 打断的 run 会缺终止哨兵,旧逻辑把「没有哨兵」误读成真实结论(假的 fix_failed),污染源报告。让生产者能从基础设施抖动里恢复(in-session 续跑 + 有界重试),下游报告才有干净的原料。


7. 让「逼近极限」变成可操作的闭环,而不是玄学调参

前面都是「怎么写得更好」,这一章是**「怎么科学地知道自己写得更好」**——没有这个闭环,所谓「逼近极限」只是碰运气。

7.1 把 prompt 当成版本化的生产制品

77ca594 之后,prompt 不再是散落在代码里的字符串,而是一套完整的制品体系(lab_db.ts):

  • SSOT:模板只有一份权威源(shared/src/readable_prompt.ts),control plane 和 satellite 都 import 同一段文本,两个构建之间零漂移。
  • 生产只跑代码:新任务永远用 DEFAULT_READABLE_PROMPT_TEMPLATE 渲染,改它 + 部署即生效,回滚就是 revert。readable_prompts 表只存实验室里的草稿版本(试跑、批量重刷、对比用),每次生成的 run 都快照了当时的正文。曾经有一个 readableActivePromptId 指针决定生产用哪一行、新基线「插入但不自动激活」——结果代码基线两次在库里躺了数周没人切(2026-07-31、2026-09-11),2026-10-12 拆掉。

7.2 一个便宜、可逆的实验台

Lab(owner-only)提供真正的实验能力:

  • test / compare / save:拿候选 prompt 在真实 target 上跑,readable-over-raw 并排对比。
  • adhoc 无 workspace:候选 prompt 能在任意在线节点上跑,不需要 checkout 工作区——实验成本被压到最低。
  • 批量存量更新(4436c40):选一批历史报告,用新版本一次性异步重刷,有界并发 min(liveNodes,3)、单活跃任务锁、重启后 orphan 回收。让「换一版 prompt」能立刻在整个存量上看到效果。
  • 每版本归档 + 决定论排序(6fa1af0):生产生成会按 prompt 版本归档每次 run,按 finishedAt 排序取「该版本最新代表」,即使两次 run 同一毫秒也能确定性地选出代表——版本之间才能公平 diff。

工程 know-how #5:要逼近一个没有解析解的边界,你需要的不是更聪明的一次尝试,而是一个「改一版 → 在真实存量上立刻可见 → 可确定性对比 → 可一键回滚」的短反馈环。 方法论的重心从「设计完美 prompt」转移到「让糟糕 prompt 的代价趋近于零」。


8. Know-how 速查表

# 原则 一句话
1 上游即天花板 下游 pixel-blind,要提升第 N 段先改第 N-1 段
2 交接即契约 语义化命名 + shot index + data-evidence,盲阶段之间只走显式契约
3 幻觉无处可去 模型无法核实的标识符 → 封闭清单 + 占位符 + 宿主侧校验丢弃
4 封闭词表 只暴露渲染器能渲染的表面,禁止一切发挥;生成器与 CSS 同步演进
5 结构 > prose 逐字给结构模板,堵死「塌回段落」这个默认失败模式
6 skip-don't-pad 没数据就整块跳过,空卡片是负信息
7 给诚实留位置 造一个「验证阻塞」的专属视觉出口,模型才不用乐观措辞填空
8 分层双语域 大白话(零术语)+ 工程层(<code>)服务两类读者
9 渐进式披露 crux ≤25 行浮上来,全量 diff 折叠下去,保持阅读海拔
10 证据分级 最决定性的证据顶到最前(demo MP4 > 前后对比 > 画廊)
11 语言写死 无条件输出语言指令 + 枚举例外,别靠上下文暗示
12 替换抗污染 不可信内容最后注入、函数式替换、显式截断
13 先查数据再改 prompt 「模板已会渲染 X,只是从没收到 X」是最高频的伪 prompt bug
14 SSOT 一份权威模板(代码常量)就是生产;实验版本只在实验室里跑;回滚 = git revert
15 短反馈环 存量批量重刷 + 决定论归档,让换一版 prompt 的代价趋近于零

9. 边界在哪里,以及下一步往哪走

诚实地标出这套方法还没触达的边界:

  1. 真正的 pixel-aware。 当前整条链路的根本约束仍是「格式化者看不见图」。所有的语义化命名、shot index,本质都是在绕过这个约束而非解除它。下一个数量级的提升,来自让报告生成真的具备多模态读图能力——那时 §3 的一大半契约可以退化简化。
  2. 目标函数仍靠人眼评测。 「60 秒读懂」目前没有自动度量。真正把「逼近极限」做成科学,缺的最后一块是一个自动可读性评分器(哪怕是一个 LLM judge:给它报告,问它能否在约束内答出影响/根因/改动/验证/局限)——有了它,§7 的实验台就能从「人肉并排看」升级成「跑分驱动的搜索」。
  3. 证据形态还会继续进化。 从截图到 demo MP4 是一条清晰的上升曲线,下一站可能是可交互的复现步骤、或把 trace/日志作为一等证据。

结语

「逼近可读性的极致边界」听起来像一个措辞问题,做下来发现它几乎全是工程问题:把目标函数写清楚、认清下游的天花板在上游、把每次盲交接变成被校验的契约、把输出空间收缩到渲染器的真实表面、再用一个便宜可逆的实验闭环把每一次改动的代价压到趋近于零。prompt 措辞只是浮在最上面那一层——底下真正决定边界的,是契约、数据完整性、和反馈环的工程。

演进轨迹一览:0584742(管线雏形) → 9dc9abb(封闭词表 + 结构模板) → 527a2db(语言写死) → 77ca594(版本化 lab) → 16feaaa(测试图契约) → d2934ed/520412d(上游即天花板) → 1b1db98(数据 > prompt) → 4436c40(折叠 crux + 批量重刷) → 6fa1af0(决定论归档) → 5ce7596(demo 视频成为核心证据)。