Refine OpenClaw payloads and reorganize docs

2026-03-26 10:20:07 +08:00
parent cecf4d3ae7
commit 27fe1e8882
155 changed files with 8999 additions and 87 deletions
@@ -0,0 +1,488 @@
+# Article Candidate / OpenClaw Input / Daily Digest 设计
+
+## 1. 文档目的
+
+本文档正式定义 OpenClaw 日报链路中的三层对象：
+
+- `ArticleCandidateRecord`
+- `OpenClawCandidateInput`
+- `DailyDigest`
+
+目标不是只定义字段，而是明确每一层对象的职责边界，避免把“内部记录对象”和“发给 OpenClaw 的下游输入对象”混成同一个 payload。
+
+---
+
+## 2. 这次为什么要改
+
+前一版设计里，`article_candidate` 同时承担了三种职责：
+
+1. 本地审计与追溯
+2. 规则过滤后的内部候选记录
+3. 发给 OpenClaw 的下游输入
+
+这会直接带来三个问题：
+
+- 字段过重
+  - `article.plain_text` 这类正文内容会显著增加 token 消耗
+- 字段过细
+  - `filter_decision.matches`、`matched_rules`、`labels` 这类规则证据链更适合本地审计，不适合发给下游聚合器
+- 字段过耦合
+  - `source_refs` 是本地文件系统路径，对 OpenClaw 没有意义，反而会让上下游绑定内部实现
+
+批量跑完 `FreshRSS -> extraction -> LLM summary -> filter -> article_candidate` 后，这个问题已经非常清楚：
+
+- 本地对象需要尽量保留信息，便于追溯误判
+- OpenClaw 输入需要尽量精简，便于聚合日报和控制 token
+
+因此，正确改法不是继续给一个 `article_candidate` 做加减法，而是把对象拆层。
+
+---
+
+## 3. 设计结论
+
+建议正式拆成三层：
+
+### 3.1 `ArticleCandidateRecord`
+
+定位：
+
+- 内部候选记录对象
+- 面向本地留档、审计、调试、复跑
+
+它回答的问题是：
+
+- 这条候选内容从哪里来
+- 提取、摘要、过滤各阶段到底产出了什么
+- 为什么规则引擎会给出当前决策
+- 后续如果要重放或排查，该去哪里追溯
+
+### 3.2 `OpenClawCandidateInput`
+
+定位：
+
+- 发给 OpenClaw 的精简输入对象
+- 面向日报聚合与编排
+
+它回答的问题是：
+
+- 这条内容是什么
+- 为什么值得放进候选池
+- 应该如何排序和栏目化
+
+它不负责保存本地调试信息，也不负责承载完整正文。
+
+### 3.3 `DailyDigest`
+
+定位：
+
+- OpenClaw 聚合后的日级主产物
+- 面向日报汇报、知识沉淀、人工 review
+
+它回答的问题是：
+
+- 今天最值得关注的内容是什么
+- 这些内容能提炼出什么结论
+- 哪些内容值得进入长期知识库
+
+---
+
+## 4. 推荐链路
+
+推荐把链路明确为：
+
+`item -> article -> summary -> filter_result -> ArticleCandidateRecord -> OpenClawCandidateInput -> DailyDigest`
+
+这里有两个关键转换：
+
+1. `summary + filter_result` 先生成 `ArticleCandidateRecord`
+   - 这是内部标准记录
+2. `ArticleCandidateRecord` 再投影成 `OpenClawCandidateInput`
+   - 这是跨系统传输对象
+
+这样做的本质是：
+
+- 内部对象追求可追溯
+- 下游对象追求低耦合、低 token、高可消费性
+
+---
+
+## 5. `ArticleCandidateRecord` 设计
+
+### 5.1 角色定义
+
+`ArticleCandidateRecord` 是当前项目内部的正式候选记录对象。
+
+它不是：
+
+- 发给 OpenClaw 的最终 payload
+- 发给用户的日报消息
+- 最终知识库对象
+
+它是下游所有再加工动作之前的“内部事实底稿”。
+
+### 5.2 设计原则
+
+- 保留上游对象，便于调试和重放
+- 保留规则证据链，便于解释误判
+- 保留本地引用，便于审计
+- 允许后续重新生成不同版本的下游 payload
+
+### 5.3 建议字段
+
+```json
+{
+  "candidate_id": "cand:sha256:xxx",
+  "item": {"...": "Item"},
+  "article": {"...": "ExtractedArticle"},
+  "summary": {"...": "LlmSummaryResult"},
+  "filter_result": {"...": "FilterDecisionResult"},
+  "digest_section_hint": "insights",
+  "digest_rank": 60,
+  "review_state": "pending",
+  "rendered_markdown": null,
+  "metadata": {
+    "generated_at": "2026-03-25T10:00:00Z",
+    "pipeline_version": "v2",
+    "producer": "summary_mcp",
+    "run_id": "candidate-2026-03-25-001"
+  },
+  "source_refs": {
+    "item_path": "outputs/freshrss/items/batch/item-01.item.json",
+    "extracted_path": "outputs/freshrss/extracted/batch/item-01.extracted.json",
+    "summary_path": "outputs/freshrss/summary/batch/item-01/result.loop.json",
+    "filter_path": "outputs/freshrss/filter/batch/item-01.filter.json"
+  }
+}
+```
+
+### 5.4 字段说明
+
+- `candidate_id`
+  - 候选记录唯一标识
+  - 建议基于 `item_id` 或 `extract_id` 派生
+
+- `item`
+  - 保留来源、标题、发布时间、作者等上游元数据
+
+- `article`
+  - 保留正文提取结果与质量标记
+  - 供本地调试与重放使用
+
+- `summary`
+  - 保留结构化摘要结果
+  - 是后续 OpenClaw 输入映射的主要来源
+
+- `filter_result`
+  - 保留规则引擎的完整裁决与命中细节
+  - 主要用于解释和排查
+
+- `digest_section_hint`
+  - 给 OpenClaw 的栏目建议
+
+- `digest_rank`
+  - 给 OpenClaw 的排序信号
+
+- `review_state`
+  - 记录人工复核状态
+
+- `rendered_markdown`
+  - 可选的人类可读卡片
+  - 用于调试或 fallback 展示
+
+- `metadata`
+  - 记录运行时元信息
+
+- `source_refs`
+  - 仅用于本地追溯
+  - 不应进入跨系统 payload
+
+### 5.5 为什么内部对象要保留正文和完整过滤结果
+
+因为这层对象不是给 OpenClaw 直接消费的，而是给系统内部留档的。
+
+如果这里过早裁掉字段，会丢失两种关键能力：
+
+1. 误判排查能力
+   - 例如文章被误判为 `paywall` 时，必须能回看 `article` 与 `filter_result`
+2. 下游重放能力
+   - 后面如果调整了 OpenClaw payload 或摘要策略，可以从这层重新投影，而不必重新抓取全文
+
+---
+
+## 6. `OpenClawCandidateInput` 设计
+
+### 6.1 角色定义
+
+`OpenClawCandidateInput` 是当前项目发给 OpenClaw 的正式输入对象。
+
+它应当是：
+
+- 扁平化的
+- 精简的
+- 稳定的
+- 不依赖本地文件路径的
+
+### 6.2 设计原则
+
+- 不携带正文全文
+- 不携带规则引擎的完整证据链
+- 不携带本地 `source_refs`
+- 只保留 OpenClaw 聚合日报真正需要的字段
+
+### 6.3 建议字段
+
+```json
+{
+  "candidate_id": "cand:sha256:xxx",
+  "title": "套壳中国大模型撑起500亿美元估值？扒一扒 Cursor 的套壳疑云",
+  "url": "http://www.ruanyifeng.com/blog/2026/03/kimi-cursor.html",
+  "published_at": "2026-03-21T10:19:11Z",
+  "author": "阮一峰",
+  "source_name": "阮一峰博客",
+  "summary": "2 到 3 句话摘要",
+  "highlights": ["...", "...", "..."],
+  "keywords": ["Cursor", "Kimi K2.5"],
+  "topics": ["人工智能", "商业伦理"],
+  "category": "观点评论",
+  "worth_keeping": true,
+  "worth_reason": "有持续性的行业洞察价值",
+  "selection_decision": "review",
+  "selection_reason": "worth_keeping=true but no stronger keep rule matched",
+  "digest_section_hint": "insights",
+  "digest_rank": 60
+}
+```
+
+### 6.4 字段说明
+
+- `candidate_id`
+  - 与内部记录保持同一主键，便于回溯
+
+- `title` / `url` / `published_at` / `author` / `source_name`
+  - OpenClaw 做日报聚合所需的最小来源信息
+
+- `summary` / `highlights` / `keywords` / `topics` / `category`
+  - OpenClaw 聚合时真正需要的语义材料
+
+- `worth_keeping` / `worth_reason`
+  - 摘要层提供的长期价值判断信号
+
+- `selection_decision` / `selection_reason`
+  - 规则层的压缩结果
+  - 用于告诉 OpenClaw：这条为什么进入候选池，以及应该怎样对待
+
+- `digest_section_hint` / `digest_rank`
+  - OpenClaw 做栏目化和排序时最直接的信号
+
+### 6.5 为什么不用正文全文
+
+因为 OpenClaw 当前承担的是“日报聚合”角色，不是“再次全文阅读器”。
+
+如果把 `article.plain_text` 一并发给 OpenClaw，会出现三个问题：
+
+1. token 浪费
+   - 每条都携带全文，批量聚合时成本会迅速膨胀
+2. 角色混乱
+   - OpenClaw 会被迫重新阅读原文，而不是消费上游已经压缩好的摘要结果
+3. 输入不稳定
+   - 正文长度差异很大，会让聚合阶段的上下文更难控制
+
+因此，正文应保留在 `ArticleCandidateRecord`，而不是进入 `OpenClawCandidateInput`。
+
+### 6.6 为什么过滤结果要压缩
+
+完整的 `filter_result` 适合本地审计，不适合跨系统传输。
+
+OpenClaw 通常只需要知道：
+
+- 这条是 `keep / review / drop` 中的哪一种
+- 为什么会进入候选池
+- 优先级大概是多少
+
+它通常不需要知道：
+
+- 具体命中了哪几条规则
+- 每条规则携带了哪些 labels
+- 完整的 `matches` 证据链
+
+所以建议把规则层压缩为：
+
+- `selection_decision`
+- `selection_reason`
+- `digest_rank`
+
+### 6.7 为什么不要 `source_refs`
+
+因为 `source_refs` 是本地实现细节，不是业务语义。
+
+把它发给 OpenClaw 的问题有两个：
+
+1. 没价值
+   - OpenClaw 无法消费本地磁盘路径
+2. 高耦合
+   - 这会让 OpenClaw 输入隐式依赖当前项目的目录结构与输出命名方式
+
+因此，`source_refs` 应只保留在 `ArticleCandidateRecord`。
+
+---
+
+## 7. 两个对象之间的映射关系
+
+建议映射规则如下：
+
+- `OpenClawCandidateInput.candidate_id`
+  - 来自 `ArticleCandidateRecord.candidate_id`
+- `title` / `url` / `published_at` / `author`
+  - 优先来自 `item`
+- `source_name`
+  - 优先来自 `item.source_title`，没有时可退化为域名或作者来源
+- `summary` / `highlights` / `keywords` / `topics` / `category`
+  - 来自 `summary`
+- `worth_keeping` / `worth_reason`
+  - 来自 `summary.worth_keeping` 与 `summary.reason`
+- `selection_decision`
+  - 来自 `filter_result.decision`
+- `selection_reason`
+  - 可取 `filter_result.reasons[0]` 或压缩后的组合说明
+- `digest_section_hint`
+  - 来自 `ArticleCandidateRecord.digest_section_hint`
+- `digest_rank`
+  - 来自 `ArticleCandidateRecord.digest_rank`
+
+简化理解：
+
+- `ArticleCandidateRecord` 保留证据
+- `OpenClawCandidateInput` 保留结论
+
+---
+
+## 8. `DailyDigest` 设计
+
+### 8.1 角色定义
+
+`DailyDigest` 是 OpenClaw 聚合多个 `OpenClawCandidateInput` 后形成的日级主产物。
+
+它不应该再携带单篇全文，也不应该回退到内部调试结构。
+
+### 8.2 建议字段
+
+```json
+{
+  "digest_id": "digest:2026-03-25",
+  "date": "2026-03-25",
+  "title": "2026-03-25 阅读日报",
+  "summary": "今天的输入主要围绕 AI 工具、工程实践和软件产品策略展开。",
+  "sections": [
+    {
+      "section_id": "insights",
+      "title": "观察与判断",
+      "summary": "今天更值得关注的是 AI 对软件行业护城河和商业包装的影响。",
+      "items": [
+        {
+          "candidate_id": "cand:sha256:xxx",
+          "title": "文章标题",
+          "summary": "单篇摘要压缩版",
+          "why_it_matters": "为什么今天值得被放进这个栏目",
+          "action": "值得继续跟进"
+        }
+      ]
+    }
+  ],
+  "top_items": ["cand:sha256:xxx"],
+  "key_takeaways": [
+    "摘要层和知识沉淀层应分开。",
+    "规则证据链应保留在本地，而不是直接下发给聚合器。"
+  ],
+  "watchlist": [
+    "继续收敛 paywall 误判。"
+  ],
+  "candidate_ids": ["cand:sha256:xxx"],
+  "source_refs": [
+    {
+      "candidate_id": "cand:sha256:xxx",
+      "url": "https://example.com/post/1"
+    }
+  ],
+  "editor_notes": "今天的输入以观点和周刊类内容为主。",
+  "stats": {
+    "candidate_total": 12,
+    "kept_total": 4,
+    "review_total": 6,
+    "dropped_total": 2
+  },
+  "metadata": {
+    "generated_at": "2026-03-25T21:00:00Z",
+    "producer": "openclaw",
+    "pipeline_version": "v2"
+  }
+}
+```
+
+### 8.3 `sections.items[]` 子结构建议
+
+```json
+{
+  "candidate_id": "cand:sha256:xxx",
+  "title": "文章标题",
+  "summary": "单篇摘要压缩版",
+  "why_it_matters": "为什么这条内容今天值得看",
+  "action": "值得试用 / 值得跟进 / 值得收藏 / 待验证"
+}
+```
+
+这里最关键的不是原始摘要复述，而是 `why_it_matters`。
+
+因为日报的价值不在于再列一遍新闻，而在于表达“今天为什么值得看”。
+
+---
+
+## 9. 为什么这样设计更合理
+
+### 9.1 控制 token 成本
+
+把正文全文挡在 OpenClaw 之前，能显著降低聚合阶段的 token 开销。
+
+### 9.2 保持对象职责单一
+
+- `ArticleCandidateRecord` 负责本地审计
+- `OpenClawCandidateInput` 负责下游消费
+- `DailyDigest` 负责日级成品
+
+每层只做一件事，后续更容易演进。
+
+### 9.3 降低上下游耦合
+
+OpenClaw 不需要知道本地 `outputs/` 目录结构，也不应该依赖规则引擎的内部细节。
+
+### 9.4 保留调试与重放能力
+
+内部对象依然保留全文、质量标记、完整过滤证据链，因此不会因为“下游精简”而损失工程可维护性。
+
+### 9.5 为后续人审与知识库沉淀留出口
+
+当日报和知识库真正接起来时：
+
+- OpenClaw 基于精简输入做日报聚合
+- 人工基于日报成品做最终判断
+- 本地记录对象作为审计底稿长期保留
+
+这个边界是清晰且可持续的。
+
+---
+
+## 10. 当前阶段的实现建议
+
+建议按这个顺序推进：
+
+1. 在文档层正式采用这三个对象
+2. 将当前代码里的 `article_candidate` 重命名或重新定位为 `ArticleCandidateRecord`
+3. 新增 `OpenClawCandidateInput` 模型
+4. 增加 `ArticleCandidateRecord -> OpenClawCandidateInput` 的转换逻辑
+5. 让 OpenClaw 只消费精简输入对象
+6. 后续再补 `DailyDigest` 的真实生成逻辑
+
+---
+
+## 11. 一句话结论
+
+这次改动的本质，不是“删掉几个字段”，而是把“内部候选记录对象”和“发给 OpenClaw 的精简输入对象”彻底分层；只有这样，当前项目才能同时保留审计能力、控制 token 成本，并稳定服务 OpenClaw 的日报聚合。