17 KiB
逼近 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. 边界在哪里,以及下一步往哪走
诚实地标出这套方法还没触达的边界:
- 真正的 pixel-aware。 当前整条链路的根本约束仍是「格式化者看不见图」。所有的语义化命名、shot index,本质都是在绕过这个约束而非解除它。下一个数量级的提升,来自让报告生成真的具备多模态读图能力——那时 §3 的一大半契约可以退化简化。
- 目标函数仍靠人眼评测。 「60 秒读懂」目前没有自动度量。真正把「逼近极限」做成科学,缺的最后一块是一个自动可读性评分器(哪怕是一个 LLM judge:给它报告,问它能否在约束内答出影响/根因/改动/验证/局限)——有了它,§7 的实验台就能从「人肉并排看」升级成「跑分驱动的搜索」。
- 证据形态还会继续进化。 从截图到 demo MP4 是一条清晰的上升曲线,下一站可能是可交互的复现步骤、或把 trace/日志作为一等证据。
结语
「逼近可读性的极致边界」听起来像一个措辞问题,做下来发现它几乎全是工程问题:把目标函数写清楚、认清下游的天花板在上游、把每次盲交接变成被校验的契约、把输出空间收缩到渲染器的真实表面、再用一个便宜可逆的实验闭环把每一次改动的代价压到趋近于零。prompt 措辞只是浮在最上面那一层——底下真正决定边界的,是契约、数据完整性、和反馈环的工程。
演进轨迹一览:
0584742(管线雏形) →9dc9abb(封闭词表 + 结构模板) →527a2db(语言写死) →77ca594(版本化 lab) →16feaaa(测试图契约) →d2934ed/520412d(上游即天花板) →1b1db98(数据 > prompt) →4436c40(折叠 crux + 批量重刷) →6fa1af0(决定论归档) →5ce7596(demo 视频成为核心证据)。