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,195 @@
+# OpenClaw Delivery Payload 字段说明
+
+## 1. 文档目的
+
+本文档定义当前项目批量投递给 OpenClaw 的外层 envelope：`OpenClawDeliveryPayload`。
+
+它不是单篇 candidate 对象，而是承载一批 `OpenClawCandidateInput` 的批次对象。
+
+---
+
+## 2. 完整 JSON 示例
+
+```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[]` 承载真正的单篇候选输入。