215 lines
17 KiB
Markdown
215 lines
17 KiB
Markdown
# 逼近 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 视频成为核心证据)。
|