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

215 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 逼近 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 视频成为核心证据)。