# 逼近 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 语义化证据命名 = 盲阶段之间的唯一带宽 命名约定:`-[-NN]-.`,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 自己无法核实的标识符 格式化者**绝不允许**输出 `` / `src` / `href` / 任何 URL——因为它一定会幻觉出不存在的路径。取而代之:模型只在 `
` 上写 `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 `

`」 | 为什么这个改动是决定性的?因为 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 名,允许一个类比,把**唯一**的关键修复思路包进一个 ``。 - 其余 block:给工程师看,标识符一律 `` 保留原文。 一个 artifact,两个寄存器,读者各取所需,谁都不用读对自己是噪声的那半。 **② 渐进式披露——把「crux」浮上来,把「全量」折下去。** - `关键代码变更` 只放 **单个最决定性的 hunk,≤25 行**,其余用一行 `…` 省略,且强制装进**默认折叠**的 `

`(`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 里没写死输出语言时,只要上下文是英文,模型就**漂移到英文**。修复是加一条无条件指令 + 列清例外(`` 里的标识符、固定中文标签保持原文)。凡是「希望模型总是 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 | **分层双语域** | 大白话(零术语)+ 工程层(``)服务两类读者 | | 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 视频成为核心证据)。