reader/docs/openclaw/openclaw-delivery-payload-spec.md

OpenClaw Delivery Payload 字段说明

1. 文档目的

本文档定义当前项目批量投递给 OpenClaw 的外层 envelope：OpenClawDeliveryPayload。

它不是单篇 candidate 对象，而是承载一批 OpenClawCandidateInput 的批次对象。

---

2. 完整 JSON 示例

{
  "schema_version": "v1",
  "generated_at": "2026-03-26T10:15:30Z",
  "run_id": "openclaw-delivery-20260325-101530",
  "date": "2026-03-25",
  "candidates": [
    {
      "candidate_id": "cand:sha256:xxx",
      "title": "文章标题",
      "url": "https://example.com/post",
      "canonical_url": "https://example.com/post",
      "published_at": "2026-03-25T09:30:00Z",
      "author": "作者",
      "source_name": "来源",
      "language": "zh-CN",
      "summary": "2 到 3 句话摘要",
      "highlights": ["要点1", "要点2", "要点3"],
      "keywords": ["关键词1", "关键词2", "关键词3", "关键词4", "关键词5"],
      "topics": ["主题1", "主题2", "主题3"],
      "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
    }
  ],
  "stats": {
    "total": 1,
    "keep_total": 0,
    "review_total": 1,
    "drop_total": 0
  }
}

---

3. 字段总览

字段名	类型	必填	说明
schema_version	string	是	当前 envelope 的 schema 版本
generated_at	string	是	本批数据的生成时间，ISO 8601 格式
run_id	string	是	本次批量投递的唯一运行标识
date	string	是	本批次所属日期，格式 YYYY-MM-DD
candidates	OpenClawCandidateInput[]	是	单篇候选内容列表
stats	object	是	批次级统计信息

---

4. 字段详细说明

4.1 schema_version

含义：

• 当前批量 envelope 的结构版本

用途：

• 未来字段调整时做兼容处理
• 让 OpenClaw 能按版本选择不同解析逻辑

当前值：

• v1

4.2 generated_at

含义：

• 本批数据的实际生成时间

格式：

• ISO 8601，例如 2026-03-26T10:15:30Z

用途：

• 排查数据新旧
• 增量处理
• 失败重跑和批次比对

4.3 run_id

含义：

• 本次投递任务的唯一标识

用途：

• 失败重跑追踪
• 批次去重
• 运行日志关联

建议：

• 由上游在每次批量生成时唯一产生
• 例如：openclaw-delivery-20260325-101530

4.4 date

含义：

• 本批次所属日期

格式：

• YYYY-MM-DD

用途：

• OpenClaw 进行日报归档
• 将多次投递映射到同一天的 digest 流程

4.5 candidates

含义：

• 单篇候选输入对象列表

说明：

• 数组内每个元素都应满足 OpenClawCandidateInput 定义
• 单篇字段说明请参考：
  • docs/openclaw/openclaw-candidate-input-field-spec.md

4.6 stats

含义：

• 本批次的统计信息

当前字段包括：

• total
• keep_total
• review_total
• drop_total

用途：

• OpenClaw 在接收后快速感知这批输入的规模和分布
• 便于记录运行状态和对账

---

5. stats 子结构说明

字段名	类型	必填	说明
total	integer	是	candidate 总数
keep_total	integer	是	selection_decision=keep 的数量
review_total	integer	是	selection_decision=review 的数量
drop_total	integer	是	selection_decision=drop 的数量

说明：

• 这些统计值由上游根据 candidates[] 自动汇总
• OpenClaw 可以直接信任，也可以再次校验

---

6. 推荐消费方式

建议 OpenClaw 的批处理逻辑按以下顺序进行：

1. 先读取 schema_version
   • 选择对应版本的解析逻辑
2. 再读取 generated_at、run_id 和 date
   • 建立本次批处理上下文
3. 再读取 stats
   • 快速判断这批输入规模与分布
4. 最后逐条消费 candidates[]
   • 去重
   • 聚类
   • 分栏目
   • 排序
   • 产生日报和 review 清单

---

7. 当前不会放入 envelope 的字段

当前 envelope 不会额外放入：

• 完整内部候选记录列表
• 人工确认状态列表
• 知识库入库状态列表
• 执行日志文本

这些都属于其他层的对象，不应混进上游投递协议。

---

8. 一句话结论

OpenClawDeliveryPayload 是“给 OpenClaw 的批量投递对象”：它用 schema_version、generated_at、run_id、date、stats 管理批次上下文，用 candidates[] 承载真正的单篇候选输入。