reader/docs/summary-loop-explained.md

Summary Loop 工作说明

1. 目的

本文档说明 scripts/run_summary_loop.py 如何把以下流程串成一个最小闭环：

提取 JSON -> LLM 生成摘要 JSON -> validator 校验 -> 失败则修复重试

这个脚本的目标不是单次调用 LLM，而是让 LLM 输出进入一个“生成后验收”的自动反馈回路。

---

2. 核心思路

这个闭环由三部分组成：

• 提取结果

  • 来自 outputs/*.extracted.json
  • 提供标题、链接、正文、质量标记

• LLM 摘要

  • 基于提取结果和 prompt 生成 result.json

• validator

  • 检查 result.json 是否符合结构和业务规则
  • 不通过则返回错误列表

因此，LLM 不是“自己知道哪里错了”，而是脚本在每轮生成后用 validator 明确指出错误，再要求它修复。

---

3. 运行顺序

脚本入口：

• scripts/run_summary_loop.py

执行顺序如下：

1. 读取提取结果 JSON
2. 读取摘要 prompt 模板
3. 从提取结果中裁剪出摘要真正需要的输入字段
4. 调用 LLM 生成摘要 JSON
5. 解析模型输出中的 JSON
6. 将结果写入输出文件
7. 调用 validator 校验结果
8. 如果通过，结束
9. 如果失败，构造修复 prompt，再次调用 LLM

---

4. 输入来源

脚本主要使用两个输入文件：

• 提取结果：outputs/read-flow-2026.extracted.json
• 摘要 prompt：outputs/llm-summary-prompt.txt

提取结果不会整包无差别塞给 LLM，而是先裁剪成更小的摘要输入：

• article.title
• article.url
• article.plain_text
• article.quality_flags
• warnings

这样做是为了减少 payload，降低模型超时概率，也让 prompt 更聚焦。

---

5. 首次生成

第一次生成时，脚本会把：

• prompt 模板
• 结构化文章输入

拼成一个完整请求，发给 LLM。

对应函数：

• build_initial_prompt(...)
• call_llm(...)

模型返回后，脚本会尝试提取一个 JSON 对象。

如果模型输出不是合法 JSON：

• 这一轮直接视为失败
• 会生成一份失败校验结果
• 然后进入修复重试

---

6. validator 如何加入流程

validator 不是附加步骤，而是主流程里的硬门槛。

对应函数：

• validate_llm_result(...)

校验内容包括两层：

6.1 结构校验

• 必填字段是否存在
• 字段类型是否正确
• category 是否属于允许枚举
• summary 长度是否合规
• highlights / keywords / topics 数量是否合规

6.2 业务校验

• keywords 和 topics 不能重复
• 列表内部不能重复
• title 和 url 必须与提取结果一致

只有 validator 返回 valid: true，这一轮结果才会被接受。

---

7. LLM 如何知道自己生成错了

LLM 本身不会主动知道哪些字段不合规。

脚本会在校验失败后，把以下信息重新发给 LLM：

• validator 错误列表
• 原始提取结果
• 当前错误的摘要 JSON

然后要求它：

• 只修复错误字段
• 保留已经正确的字段
• 继续只输出合法 JSON

对应函数：

• build_repair_prompt(...)

也就是说：

• prompt 负责提出目标
• validator 负责判错
• repair prompt 负责把错误喂回模型

这三者一起形成自动修复回路。

---

8. 时序图

Extracted JSON
   |
   v
run_summary_loop.py
   |
   |-- 读取 prompt 模板
   |-- 构造摘要输入
   |
   v
LLM
   |
   v
摘要 JSON
   |
   v
validator
   |
   |-- valid = true  ------> 结束
   |
   |-- valid = false
   |       |
   |       |-- errors
   |       v
   |   repair prompt
   |       |
   +------> LLM 重试

---

9. 生成的中间文件

每次执行脚本都会在输出目录下留下调试痕迹：

• result.loop.attempt-1.raw.txt

  • 模型原始输出

• result.loop.attempt-1.json

  • 提取出的 JSON 结果

• result.loop.attempt-1.validation.json

  • 这一轮的校验报告

• result.loop.json

  • 当前最终结果

这些文件的价值是：

• 可以回看模型原始输出
• 可以定位是 JSON 解析失败还是 schema 校验失败
• 可以看每轮修复到底修了什么

---

10. 当前脚本参数

当前脚本支持：

• --extracted
• --prompt
• --output
• --max-retries
• --timeout
• --api-key
• --model
• --api-url

这意味着它既可以走环境变量，也可以直接用命令行传入模型配置。

---

11. 一句话结论

run_summary_loop.py 的本质不是“调一次 LLM”，而是“让 LLM 生成结果后必须经过 validator 验收，失败就拿着错误清单继续修”，直到结果通过或达到重试上限。