# 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[]` 承载真正的单篇候选输入。