bestblogs-content-reviewer

BestBlogs 内容评分 Review (Content Score Reviewer)

每日早晚 review BestBlogs 系统中已评分但未 review 的文章和推特，评估 AI 评分是否准确，纠正偏差，并推荐值得深度阅读的内容，为 deep-reading 和 bestblogs-article-recommender 工作流提供输入。

评分标准基于统一评分规则（docs/scoring-rubric.md），Review 时参照其中的分段定义、来源优先级、原创性评估和交叉校准机制。完整 API 参数详情见 references/api_reference.md。

认证

所有请求使用 Admin API 认证：

-H "Authorization: Bearer $BESTBLOGS_ADMIN_JWT_TOKEN"
-H "User-Id: $BESTBLOGS_ADMIN_USER_ID"
-H "Content-Type: application/json"

若环境变量未设置，提示用户配置。

接口地址：https://api.bestblogs.dev

可用端点

工作流概览

- [ ] 阶段零（可选）: 学习评分偏好 — 用户要求"学习偏好"或"分析评分规律"时执行
- [ ] 阶段一: 拉取待 review 内容（文章 + 推特并行）
- [ ] 阶段二: AI 评审与分类
- [ ] 阶段三: 输出 review 表格 ⚠️ 等待用户确认调整
- [ ] 阶段四: 批量执行标记 ⛔ BLOCKING — 写操作

默认从阶段一开始执行。阶段零仅在用户明确要求时执行。

---

阶段零（可选）: 学习评分偏好

用户要求"学习偏好"、"分析评分规律"、"看看精选标准"时执行。通过分析历史精选/非精选内容，建立评分偏好模型。

并行发起两个请求:

# 过去一个月的精选文章（学习"好内容"的特征）
curl -s -X POST https://api.bestblogs.dev/api/admin/article/list \
  -H "Authorization: Bearer $BESTBLOGS_ADMIN_JWT_TOKEN" \
  -H "User-Id: $BESTBLOGS_ADMIN_USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"currentPage":1,"pageSize":100,"keyword":"","category":"","language":"","priority":"","sourceId":"","type":"ARTICLE","qualifiedFilter":"true","stickTopFilter":"ALL","timeFilter":"1m","startDate":"","endDate":"","mainDomainFilter":"ALL","aiSubCategoryFilter":"","flowStatusFilter":"","sort":null,"sortOrder":null,"userLanguage":"zh"}'

# 过去三天的非精选文章（学习"被淘汰"的特征）
curl -s -X POST https://api.bestblogs.dev/api/admin/article/list \
  -H "Authorization: Bearer $BESTBLOGS_ADMIN_JWT_TOKEN" \
  -H "User-Id: $BESTBLOGS_ADMIN_USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"currentPage":1,"pageSize":100,"keyword":"","category":"","language":"","priority":"","sourceId":"","type":"ARTICLE","qualifiedFilter":"false","stickTopFilter":"ALL","timeFilter":"3d","startDate":"","endDate":"","mainDomainFilter":"ALL","aiSubCategoryFilter":"","flowStatusFilter":"","sort":null,"sortOrder":null,"userLanguage":"zh"}'

分析维度:

精选内容的分数分布（最低分、平均分、中位数）

精选 vs 非精选的分数分界线

各领域（AI、编程、商业、产品）的精选比例

来源质量分布（哪些源的内容更容易被精选）

内容类型和深度偏好（字数、阅读时间分布）

输出偏好摘要给用户确认，例如：

📊 评分偏好分析:
- 精选文章分数范围: 85-98，中位数 90
- 非精选文章分数范围: 65-88，中位数 78
- AI 领域精选率较高，商业资讯精选率较低
- 偏好深度技术文章（>2000 字），短资讯类倾向非精选

---

阶段一：拉取待 review 内容

并行发起两个请求（qualifiedFilter: "unknown" = 待 review）:

# 待 review 文章
curl -s -X POST https://api.bestblogs.dev/api/admin/article/list \
  -H "Authorization: Bearer $BESTBLOGS_ADMIN_JWT_TOKEN" \
  -H "User-Id: $BESTBLOGS_ADMIN_USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"currentPage":1,"pageSize":200,"keyword":"","category":"","language":"","priority":"","sourceId":"","type":"ARTICLE","qualifiedFilter":"unknown","stickTopFilter":"ALL","timeFilter":"1w","startDate":"","endDate":"","mainDomainFilter":"","aiSubCategoryFilter":"","flowStatusFilter":"","sort":null,"sortOrder":null,"userLanguage":"zh"}'

# 待 review 推特
curl -s -X POST https://api.bestblogs.dev/api/admin/article/list \
  -H "Authorization: Bearer $BESTBLOGS_ADMIN_JWT_TOKEN" \
  -H "User-Id: $BESTBLOGS_ADMIN_USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"currentPage":1,"pageSize":200,"keyword":"","category":"","language":"","priority":"","sourceId":"","type":"TWITTER","qualifiedFilter":"unknown","stickTopFilter":"ALL","timeFilter":"1w","startDate":"","endDate":"","mainDomainFilter":"","aiSubCategoryFilter":"","flowStatusFilter":"","sort":null,"sortOrder":null,"userLanguage":"zh"}'

数据预处理:

过滤掉 processFlowStatus == "CANCELLED" 的内容（已取消，跳过并计数）

按 totalScore 从高到低排序

统计：总数、已过滤数、分数分布、领域分布

每次最多 review 200 条（取 totalScore 最高的前 200 条），超出部分下次 review

---

阶段二：AI 评审与分类

读取用户画像（按需）: 从 /Users/gino/Documents/Github/gino-bot/USER.md 获取用户关注领域和偏好，辅助判断"推荐阅读"的相关性。

基于内容元数据对每条内容进行评审分类。

评审维度

基于统一评分规则（docs/scoring-rubric.md）进行系统性检查：

来源优先级校验（最重要，同时检查天花板和地板）:

- 天花板：LOW 来源上限 89，MEDIUM 上限 93，HIGH 可触及 95+
- 地板：HIGH 来源常规内容通常不低于 80 分（除非内容确实差）
- LOW 来源评分 90+ → 几乎必定偏高
- HIGH 来源评分 <80 → 可能偏低，需检查是否为重要行业事件被低估

评分分段匹配检查:

- 95+（里程碑 <1%）：是否为行业里程碑事件？
- 90-94（顶级 ~5%）：是否同时具备深度 + 实用 + 创新？
- 85-89（优质推荐 ~15%）：是否有明确的深度或实用性亮点？
- 80-84（合格展示 ~25%）：信息完整但深度有限？
- 75-79（边缘 ~20%）：基础信息传递？
- <75（低质量 ~35%）：营销/错误/浅薄？

减分项红旗检查:

- 编译转述类（翻译、书评、课程笔记）：上限 89，评分超过时下调
- 教程入门类（Hello World、"X 分钟学会"）：应在 75-79 区间
- 营销导向类（产品推广、PR 软文）：应在 <75 区间
- 低质聚合类（无筛选标准的链接堆砌）：应在 70-76 区间
- 例外：优质策展（阮一峰周刊、HackerNews 精选等）不适用聚合减分

内容质量信号:

- 标题是否清晰、description 是否有实质内容
- wordCount/readTime 是否与评分匹配（短文高分需警惕）
- sourceName 的历史质量和可信度

时效与领域价值:

- publishDate 与当前时间的关系
- 在其所属 mainDomain 中的价值

推特特有检查（仅推特类型）:

- 极短推文（<50 字）不应超过 82 分，除非是官方首发里程碑
- 新闻转述类（非一手来源对已知事件的简单转述）上限 78，LOW 来源上限 75
- 同一事件的多条推文，仅官方首发可获高分，后续转述应递减
- 领域偏离（纯政治、纯金融预测）应大幅下调
- 推文评分应整体低于同主题文章 5-10 分

分类标准

分类指导原则:

🌟 推荐阅读：分数 ≥ 80 的内容都应纳入候选池，从中筛选 20-30 条值得阅读的内容。筛选维度：内容深度、与用户关注领域的相关性、来源可信度、时效性、独特视角。文章推荐 15-20 篇，推特推荐 5-10 条

⬆️ 评分偏低（上调候选）：HIGH 来源评分 <80 的行业重要事件、HIGH/MEDIUM 来源的深度内容被低估、独特视角被忽略、优质策展类被当作低质聚合

⬇️ 评分偏高（下调候选）：LOW 来源评分 90+、编译转述类评分超过 89、标题党高分、纯新闻聚合高分、营销内容高分、同质化内容扎堆高分；推特专项：新闻转述 LOW 来源评分 >78、同事件重复转述评分未递减、极短推文（<50 字）评分 >82、领域偏离（政治/金融预测）评分 >75

✅ 评分合理：大多数内容应属于此类，分数与质量基本匹配

评分调整幅度参考:

微调：±1~2（小偏差）

中等调整：±3~5（明显偏差）

大幅调整：±6~10（严重偏差，罕见）

---

阶段三：输出 review 表格

分别输出文章和推特的 review 结果，按分类分组展示。

输出格式

## 📋 文章 Review（共 X 篇，跳过 Y 篇已取消）

### 🌟 推荐阅读（N 篇）

| # | 标题 | 来源 | 评分 | 建议调整 | 理由 |
|---|------|------|------|----------|------|
| 1 | [标题](https://admin.bestblogs.dev/article/review/RAW_xxx) | 来源名 | 89 | +3 | 深度好文，值得精读 |

### ⬇️ 评分偏高（N 篇）

| # | 标题 | 来源 | 评分 | 建议调整 | 理由 |
|---|------|------|------|----------|------|
| 1 | [标题](https://admin.bestblogs.dev/article/review/RAW_xxx) | 来源名 | 85 | -5 | 标题党，实际内容空洞 |

### ⬆️ 评分偏低（N 篇）

| # | 标题 | 来源 | 评分 | 建议调整 | 理由 |
|---|------|------|------|----------|------|

### ✅ 评分合理（N 篇）

| # | 标题 | 来源 | 评分 | 建议调整 | 理由 |
|---|------|------|------|----------|------|

推特部分使用相同结构，标题列额外显示 @作者名。

## 📋 推特 Review（共 X 条，跳过 Y 条已取消）

（同上表格结构，标题格式：[@作者](https://admin.bestblogs.dev/article/review/RAW_xxx): 标题）

## 📚 推荐阅读清单（共 N 篇文章 + M 条推特）

以下内容建议进入 deep-reading 工作流，按推荐优先级排序：

### 🔥 必读（N 篇）— 强烈推荐深度阅读

| # | 标题 | 来源 | 评分 | 领域 | 字数/时长 | 推荐理由 |
|---|------|------|------|------|-----------|----------|
| 1 | [标题](https://admin.bestblogs.dev/article/review/RAW_xxx) | 来源名 | 92 | AI | 5.2K 字 ~15min | 深度技术分析，提出独特框架... |
| 2 | [标题](https://admin.bestblogs.dev/article/review/RAW_xxx) | 来源名 | 89 | 编程 | 3.8K 字 ~10min | 实战经验总结，可直接应用... |

### ⭐ 推荐（N 篇）— 值得阅读

| # | 标题 | 来源 | 评分 | 领域 | 字数/时长 | 推荐理由 |
|---|------|------|------|------|-----------|----------|
| 1 | [标题](https://admin.bestblogs.dev/article/review/RAW_xxx) | 来源名 | 86 | 产品 | 2.1K 字 ~6min | 产品思维方法论，有借鉴价值... |

### 📌 可选（N 篇）— 时间充裕时阅读

| # | 标题 | 来源 | 评分 | 领域 | 字数/时长 | 推荐理由 |
|---|------|------|------|------|-----------|----------|

### 🐦 推荐推特（M 条）

| # | 作者 | 内容摘要 | 评分 | 互动 | 推荐理由 |
|---|------|----------|------|------|----------|
| 1 | [@作者](https://admin.bestblogs.dev/article/review/RAW_xxx) | 推文内容前 80 字... | 94 | 💬120 🔁85 | 行业洞察，引发深度讨论 |

推荐阅读分层标准:

🔥 必读（3-5 篇）: 评分 ≥ 88 且与用户核心关注领域（AI/编程）高度相关的深度内容

⭐ 推荐（8-12 篇）: 评分 ≥ 83 的优质内容，或评分稍低但视角独特的内容

📌 可选（5-8 篇）: 评分 ≥ 80 的有价值内容，非核心领域但有启发

🐦 推特（5-10 条）: 评分 ≥ 85 的高质量推特，优先选择有深度讨论的

推荐理由要求: 每条理由 15-30 字，说明为什么值得读（独特视角/实用技巧/行业趋势/认知升级），不要泛泛而谈。

输出完整性规则

所有链接统一使用 admin review 格式: https://admin.bestblogs.dev/article/review/{id}，包括 review 表格和推荐阅读清单。禁止使用原文 URL（如 mp.weixin.qq.com、x.com 等）作为链接地址

authors 为 null/空时省略来源中的作者信息

description 为 null/空时，理由中仅基于标题和元数据判断

tags 为 null/空时不展示标签

大数字用 K/M 格式化（如 12.9K 字）

所有标题完整输出，不截断

📊 评分统计概览

Review 表格和推荐阅读清单之间，输出评分统计：

## 📊 评分统计

| 指标 | 文章 | 推特 |
|------|------|------|
| 待 review 总数 | X | Y |
| 已过滤（取消） | X | Y |
| 分数范围 | 65-98 | 70-96 |
| 平均分 | 82.3 | 79.5 |
| ≥90 分 | X 篇 | Y 条 |
| 80-89 分 | X 篇 | Y 条 |
| <80 分 | X 篇 | Y 条 |

**领域分布**: AI X 篇 | 编程 X 篇 | 商业 X 篇 | 产品 X 篇 | 其他 X 篇
**评分偏差发现**: ⬇️偏高 X 篇（占比 X%） | ⬆️偏低 X 篇（占比 X%）

⚠️ 输出后等待用户确认。用户可能会：

调整某些内容的分类（如把"评分合理"改为"推荐阅读"）

修改建议的调整分数

确认执行或取消

---

阶段四：批量执行标记

⛔ 写操作 — 必须在用户明确确认后才能调用

用户确认后，对所有非"推荐阅读"的内容调用 markNotQualified 接口：

# 标记为非精选并调整分数（adjustScore 为相对值）
curl -s -X POST "https://api.bestblogs.dev/api/admin/article/markNotQualified?id=RAW_xxx&adjustScore=-3" \
  -H "Authorization: Bearer $BESTBLOGS_ADMIN_JWT_TOKEN" \
  -H "User-Id: $BESTBLOGS_ADMIN_USER_ID" \
  -H "Content-Type: application/json"

接口返回 data 字段为调整后的新分数（int）。

执行规则:

每批最多 5 个请求，并行执行

逐批输出进度：✅ [1/30] RAW_xxx — 标题 — adjustScore: -3 → 新分数: 82

单个失败记录 ❌ 并继续，不中断整批

连续 3 次失败暂停，提示用户可能是系统性问题（Token 过期等）

adjustScore 为 0 时也要调用（仅标记为已 review，不调整分数）

推荐阅读项目处理:

不调用 markNotQualified，保持 qualified: null 状态

输出干净的阅读清单，作为 deep-reading 工作流的输入

用户后续通过 deep-reading 阅读后，再通过 bestblogs-article-recommender 标记为精选

执行完成后输出汇总:

📊 Review 完成:
- 文章: 已标记 X 篇（⬇️ N 篇, ⬆️ N 篇, ✅ N 篇），🌟 推荐阅读 N 篇待处理
- 推特: 已标记 X 条（⬇️ N 条, ⬆️ N 条, ✅ N 条），🌟 推荐阅读 N 条待处理
- 失败: N 个（列出失败项）

错误处理

重要: 始终先检查 response.success 再处理 response.data。部分错误返回 HTTP 200 但 success: false — 不要仅依赖 HTTP 状态码。