# OpenClaw 日报聚合改造说明

## 1. 为什么要改

当前项目已经跑通了：

`FreshRSS -> item -> extraction -> LLM summary -> validator -> filter -> Markdown sink`

这条链路证明了上游拉取、结构化提取、摘要校验和规则过滤都是可行的。

但如果最终目标是：

- 每日提炼总结进入知识库
- OpenClaw 向用户汇报今天的日报

那么当前“单篇过滤后直接写入本地 Markdown 知识库”的主路径就不够准确了。

原因有四点：

1. 单篇文章更像原材料，不是最终成品
2. 用户要的是“日报级总结 + 知识沉淀”，不是“每篇都直接入库”
3. 参考文章中真正的终态是 `Digest -> Daily Review -> 人工确认 -> Lumina`
4. 当前 `article_candidate` 如果同时承担内部记录和下游投递，会导致 payload 过重、token 过高、边界混乱

所以当前项目要从“单篇直接入库”切换为“单篇候选材料 -> 日报聚合 -> 人工确认 -> 知识沉淀”。

## 2. 参考文章给出的真实结构

参考文章里的关键分层是：

1. `Digest`
   - 去重、抓正文、质量检查、生成摘要
   - 产出可判断的候选内容
2. `Daily Review`
   - 从候选内容中做栏目化精选
   - 产出当天的日报
3. `Human in the loop`
   - 人工判断哪些内容值得长期保留
4. `Lumina`
   - 只承接真正值得长期保留的内容

这意味着：

- 日报不是知识库的替代品
- 知识库也不应该承接所有单篇文章
- 单篇内容更适合作为日报生成前的候选材料

## 3. 当前设计哪里不够

当前的不足主要在下游：

### 3.1 `sink` 语义过重

现在的 `Markdown sink` 更像“最终入库器”。

但在新的目标里，它最多只应扮演：

- debug sink
- fallback sink
- 审计/归档 sink

主路径不应再把它视为最终知识库形态。

### 3.2 缺少“日级对象”

当前项目有：

- `item`
- `article`
- `summary`
- `filter_decision`

但还没有：

- `ArticleCandidateRecord`
- `OpenClawCandidateInput`
- `DailyDigest`

如果没有这三个对象，就无法稳定表达：

- 单篇内容如何作为内部候选材料存在
- 单篇内容如何以低 token 的形式发给 OpenClaw
- 一天的内容如何被聚合为一个正式产物

### 3.3 缺少人工确认层

规则引擎的 `keep` 只能表示“值得进入下一步”，不能直接等价于“正式入知识库”。

如果没有人工确认层，系统就会退化成“规则命中即永久沉淀”，这和参考文章强调的 `Human in the loop` 不一致。

### 3.4 下游输入边界不清楚

如果把正文全文、完整规则证据链、本地文件路径都发给 OpenClaw，会出现三个直接问题：

- token 浪费
- 对象职责混乱
- OpenClaw 输入与本地实现耦合

所以必须把“内部记录对象”和“下游精简输入对象”分开。

## 4. 改造后的主路径

建议主路径调整为：

`FreshRSS/RSS -> extraction -> LLM summary -> validator -> rule engine -> ArticleCandidateRecord -> OpenClawCandidateInput -> OpenClaw -> DailyDigest -> human review -> knowledge base`

这里要注意几件事：

1. 当前项目负责生成高质量候选材料与精简输入
2. OpenClaw 负责按天聚合、生成日报、编排后续动作
3. 知识库只接收日报和人工确认后的长期内容

## 5. 新的对象分层

### 5.1 `ArticleCandidateRecord`

定位：

- 单篇内容的内部候选记录
- 用于留档、追溯、重放、审计

最少应包含：

- `item`
- `article`
- `summary`
- `filter_result`
- `metadata`
- 可选 `source_refs`
- 可选 `rendered_markdown`

### 5.2 `OpenClawCandidateInput`

定位：

- 当前项目发给 OpenClaw 的标准投递对象
- 用于日报聚合与排序

最少应包含：

- `candidate_id`
- `title`
- `url`
- `published_at`
- `author`
- `summary`
- `highlights`
- `topics`
- `category`
- `worth_keeping`
- `selection_decision`
- `selection_reason`
- `digest_section_hint`
- `digest_rank`

它不应包含：

- `article.plain_text`
- `filter_result.matches`
- `source_refs`

### 5.3 `DailyDigest`

定位：

- 一天的主产物
- 同时服务于“知识沉淀”和“日报汇报”

建议至少包含：

- `date`
- `sections`
- `top_items`
- `key_takeaways`
- `watchlist`
- `candidate_ids`
- `source_refs`
- `editor_notes`

## 6. 为什么这样更合理

这样改造有几个直接收益：

1. 知识库不会被大量单篇摘要污染
2. OpenClaw 不需要再次消费全文，token 更可控
3. OpenClaw 的输入边界更清晰，不依赖本地目录结构和规则证据链
4. 当前项目仍然保留完整候选记录，因此误判排查和重放能力不会丢
5. 未来扩展周报、专题文章和反馈回流会更自然

本质上，这是把当前系统从“单篇落库工具”调整为“日报生产链路中的候选记录生产器 + 精简投递器”。

## 7. 对当前实现的影响

不需要推翻已有能力，主要是重新定位：

- `extraction` 保留
- `LLM summary validator` 保留
- `rule engine` 保留
- `FreshRSS integration` 保留
- `Markdown sink` 保留，但降级为调试/回退能力

真正新增的是：

- `ArticleCandidateRecord` schema
- `OpenClawCandidateInput` schema
- `ArticleCandidateRecord -> OpenClawCandidateInput` 映射逻辑
- `DailyDigest` schema
- 人工确认后的状态流转

## 8. 下一步应该做什么

建议按这个顺序推进：

1. 在代码里把当前 `article_candidate` 重新定位为 `ArticleCandidateRecord`
2. 新增 `OpenClawCandidateInput` 模型
3. 增加精简 payload 的本地输出脚本或转换函数
4. 让 OpenClaw 只消费精简输入对象
5. 再设计批量聚合和 `DailyDigest` 生成

## 9. 一句话结论

如果最终目标是“每天有日报汇报，同时把日级提炼沉淀进知识库”，那么当前项目就不该继续围绕“单篇直接入库”演进，而应拆成“内部候选记录对象 + OpenClaw 精简输入对象 + 日级成品对象”三层结构。