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