reader/docs/openclaw/openclaw-candidate-input-field-spec.md

# OpenClaw Candidate Input 字段说明

## 1. 文档目的

本文档定义当前项目输出给 OpenClaw 的结构化输入对象：`OpenClawCandidateInput`。

这是一份面向 OpenClaw 消费侧的接口说明文档，不要求了解本项目内部的 `item`、`article`、`filter_result` 等实现细节。

当前定位是：

- 单篇候选内容的精简输入
- 用于 OpenClaw 做日报聚合、排序、栏目分配和后续汇报
- 不承载正文全文、不承载本地文件路径、不承载规则引擎完整证据链

---

## 2. 设计原则

这个 payload 的设计遵循以下原则：

1. 足够轻
   - 不发送正文全文，避免浪费 token
2. 足够稳定
   - 不暴露本地目录结构和内部中间文件路径
3. 足够可消费
   - 字段扁平化，避免 OpenClaw 反复解析嵌套对象
4. 足够有判断信号
   - 保留摘要、主题、价值判断、筛选结果、排序信号
5. 足够可去重
   - 同时提供原始 `url` 与归一化后的 `canonical_url`

---

## 3. 完整 JSON 示例

```json
{
  "candidate_id": "cand:sha256:4139f277b8cb621b02b3398f8a7bd78e3f9eef7bcd320b70b8590e802540c6ca",
  "title": "套壳中国大模型撑起500亿美元估值？扒一扒 Cursor 的\"套壳\"疑云",
  "url": "http://www.ruanyifeng.com/blog/2026/03/kimi-cursor.html?utm_source=rss",
  "canonical_url": "http://www.ruanyifeng.com/blog/2026/03/kimi-cursor.html",
  "published_at": "2026-03-21T10:19:11Z",
  "author": "阮一峰",
  "source_name": "阮一峰的网络日志",
  "language": "zh-CN",
  "summary": "AI编程工具Cursor推出的Composer 2模型被证实套壳中国Kimi K2.5模型，引发侵权争议。Kimi官方确认Cursor通过Fireworks AI获得授权，不存在侵权。作者分析Cursor隐瞒事实是为了支撑其不断膨胀的估值，将其包装成大模型公司。",
  "highlights": [
    "Cursor的Composer 2模型被技术手段揭露实际调用的是Kimi K2.5模型。",
    "Kimi官方确认Cursor通过Fireworks AI获得授权，因此不构成侵权。",
    "Cursor隐瞒使用Kimi模型，被认为是为了支撑其高达500亿美元的估值。"
  ],
  "keywords": ["Cursor", "Composer 2", "Kimi K2.5", "Fireworks AI", "AI编程工具"],
  "topics": ["人工智能", "大模型", "商业伦理"],
  "category": "观点评论",
  "worth_keeping": true,
  "worth_reason": "文章深入剖析了AI行业的热点事件，涉及技术真相、商业动机和行业趋势，具有较高的参考价值。",
  "selection_decision": "review",
  "selection_reason": "Worth-keeping signal is positive but no stronger keep rule matched.",
  "digest_section_hint": "insights",
  "digest_rank": 60
}
```

---

## 4. 字段总览

| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `candidate_id` | `string` | 是 | 单篇候选内容唯一标识 |
| `title` | `string` | 是 | 文章或内容标题 |
| `url` | `string` | 是 | 原始链接 |
| `canonical_url` | `string \| null` | 否 | 归一化链接，用于更稳定的去重 |
| `published_at` | `string \| null` | 否 | 发布时间，ISO 8601 格式 |
| `author` | `string \| null` | 否 | 作者名 |
| `source_name` | `string \| null` | 否 | 来源名称，例如博客名、站点名、Feed 名 |
| `language` | `string \| null` | 否 | 语言标记，例如 `zh-CN`、`en` |
| `summary` | `string` | 是 | 2 到 3 句话的精简摘要 |
| `highlights` | `string[]` | 是 | 3 到 5 条单句要点 |
| `keywords` | `string[]` | 是 | 5 到 8 个关键词 |
| `topics` | `string[]` | 是 | 3 到 5 个高层主题标签 |
| `category` | `string` | 是 | 内容分类 |
| `worth_keeping` | `boolean` | 是 | 摘要层给出的长期保留判断 |
| `worth_reason` | `string` | 是 | 对 `worth_keeping` 的解释 |
| `selection_decision` | `string` | 是 | 规则层压缩后的筛选决策 |
| `selection_reason` | `string \| null` | 否 | 对 `selection_decision` 的简短解释 |
| `digest_section_hint` | `string \| null` | 否 | 建议栏目 |
| `digest_rank` | `integer` | 是 | 建议排序分值，范围 `0-100` |

---

## 5. 字段详细说明

### 5.1 `candidate_id`

含义：
- 单篇候选内容的稳定唯一标识

约束：
- 同一条上游内容在当前系统中应保持稳定
- OpenClaw 可以把它作为去重、回溯、引用的主键

### 5.2 `title`

含义：
- 候选内容标题

来源：
- 优先来自标准化 `item.title`
- 如果上游标题缺失，则退回摘要结果中的 `summary.title`

### 5.3 `url`

含义：
- 原始内容链接

用途：
- OpenClaw 在日报中回链原文
- 后续人工 review 或知识库引用时回溯来源

### 5.4 `canonical_url`

含义：
- 对原始 `url` 做轻量归一化后的链接

当前归一化策略：
- 去掉 fragment
- 去掉常见追踪参数，例如 `utm_*`、`fbclid`、`gclid`、`ref` 等
- 保留其他非追踪 query 参数

用途：
- 让 OpenClaw 在去重时更稳定
- 避免同一篇文章因为带不同追踪参数被当成两篇

说明：
- `url` 保留原始值，`canonical_url` 提供去重辅助
- OpenClaw 建议优先用 `canonical_url` 做去重键，不足时再结合 `candidate_id`

### 5.5 `published_at`

含义：
- 内容发布时间

格式：
- ISO 8601，例如 `2026-03-21T10:19:11Z`

### 5.6 `author`

含义：
- 作者名称

### 5.7 `source_name`

含义：
- 内容来源名称

常见示例：
- `阮一峰的网络日志`
- `FreshRSS`
- 某个 Feed 标题
- 某个站点域名

### 5.8 `language`

含义：
- 语言标记

常见示例：
- `zh`
- `zh-CN`
- `en`

用途：
- OpenClaw 后续处理多语言输入时做风格和分类控制
- 为知识库入库、多语言日报、翻译或过滤策略留出口

说明：
- 如果当前上游无法可靠识别语言，可以为 `null`

### 5.9 `summary`

含义：
- 摘要主文本

约束：
- 当前上游约束是 2 到 3 句话
- 长度不超过 140 个中文字符

### 5.10 `highlights`

含义：
- 关键要点列表

约束：
- 3 到 5 条
- 每条一条独立信息

### 5.11 `keywords`

含义：
- 具体实体、工具名、方法名、关键概念

约束：
- 5 到 8 个

### 5.12 `topics`

含义：
- 高层主题标签

约束：
- 3 到 5 个
- 语义层级高于 `keywords`

### 5.13 `category`

含义：
- 内容分类

当前允许值：
- `资讯`
- `方法论`
- `工具实践`
- `观点评论`

### 5.14 `worth_keeping`

含义：
- 这条内容是否具有持续保留价值

说明：
- 这是摘要层的价值判断，不是最终入库决定
- OpenClaw 可以把它当作优先筛选信号，而不是绝对真值

### 5.15 `worth_reason`

含义：
- 对 `worth_keeping` 的解释

### 5.16 `selection_decision`

含义：
- 规则引擎压缩后的筛选决策

当前允许值：
- `keep`
- `review`
- `drop`

### 5.17 `selection_reason`

含义：
- 对 `selection_decision` 的简短解释

说明：
- 当前一般取规则引擎 reasons 的第一条压缩说明
- 不承诺包含全部规则命中细节

### 5.18 `digest_section_hint`

含义：
- 建议日报栏目

当前允许值：
- `top_news`
- `tools_and_workflows`
- `risk_and_security`
- `open_source`
- `insights`
- `deep_dive`
- `null`

### 5.19 `digest_rank`

含义：
- 建议排序分值

范围：
- `0` 到 `100`

建议解释：
- `80-100`：高优先级，建议优先关注
- `50-79`：中优先级，建议正常进入候选池
- `0-49`：低优先级，建议降权或仅保留参考

---

## 6. OpenClaw 消费建议

推荐 OpenClaw 主要消费这几组信号：

### 6.1 语义聚合信号

- `summary`
- `highlights`
- `keywords`
- `topics`
- `category`

### 6.2 选择与排序信号

- `worth_keeping`
- `worth_reason`
- `selection_decision`
- `selection_reason`
- `digest_rank`
- `digest_section_hint`

### 6.3 来源展示信号

- `title`
- `url`
- `canonical_url`
- `published_at`
- `author`
- `source_name`
- `language`

---

## 7. 当前不会提供的字段

OpenClaw 当前不应期待以下字段：

- 正文全文，例如 `plain_text`
- 本地文件路径，例如 `source_refs`
- 完整规则证据链，例如 `filter_result.matches`
- 内部中间对象，例如完整的 `item`、`article`、`summary`、`filter_result`
- 人工确认状态，例如 `review_status`、`knowledge_decision`

最后一类字段不会放在这个对象中，原因是：

- `OpenClawCandidateInput` 表示的是上游候选事实
- 人工确认和知识沉淀属于下游流程状态
- 两者混在一起会让输入对象逐渐失真、变脏

---

## 8. 兼容性约定

当前版本约定：

- 这是单篇输入对象，不是批量 envelope
- 批量投递由上层 `OpenClawDeliveryPayload` 承载
- 本文档只约束 `candidates[]` 中单条对象的字段

---

## 9. 一句话结论

`OpenClawCandidateInput` 是“给 OpenClaw 聚合日报用的单篇精简对象”：它保留来源信息、摘要语义、价值判断、去重辅助和排序信号，但不会携带正文全文、本地路径、规则证据链或人工确认状态。