osiman/reader
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Refine OpenClaw payloads and reorganize docs

Browse Source
This commit is contained in:
zhuyongxin
2026-03-26 10:20:07 +08:00
parent cecf4d3ae7
commit 27fe1e8882
155 changed files with 8999 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/openclaw/openclaw-candidate-input-field-spec.md
+351
View File
@@ -0,0 +1,351 @@
# 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 聚合日报用的单篇精简对象”：它保留来源信息、摘要语义、价值判断、去重辅助和排序信号，但不会携带正文全文、本地路径、规则证据链或人工确认状态。