ephron-ren-prd/prd-ai-daily-full-chain-optimization-audit.md

# AI 日报定时任务全链路优化审计

## 0. 文档信息

- 审计对象：Hermes cron job `76297415d88d`，名称 `AI日报单任务09:30`
- 实际调度：`0 10 * * *`，每天北京时间 10:00
- 审计范围：定时触发、采集、生成、去重、异常、日志、发布、告警、稳定性、近期内容质量
- 主要证据：本地运行产物 `~/.hermes/scripts/ai_morning_out/2026-06-04` 至 `2026-06-10`，cron 输出 `~/.hermes/cron/output/76297415d88d/`，代码仓库 `~/.hermes/scripts/ai-daily-report`

---

## 1. 总结

当前 AI 日报链路已经完成了从多源采集、LLM 改写分类、导览生成到博客发布的自动化闭环，但近期运行暴露出三个 P0 级问题：

1. **语义去重召回失效**：Stage 3 语义去重完全依赖 Stage 2 的标题相似候选。6/10 的 `stage2.possible_duplicates=[]`，导致 `stage3.candidate_group_count=0`，实际没有进行语义审查。
2. **源失败仍静默发布**：6/9、6/10 橘鸦源连续失败，状态为 `error`、数量为 0，但任务仍发布成功，回执没有突出“关键补充源缺失”。
3. **发布前质量门禁不足**：近期日报中多天出现同事件重复，如 6/4 OpenClaw/Suno、6/5 Magenta、6/6 Open Code Review、6/8 OpenAI 芯片、6/9 高德 ABot、6/10 Claude Fable/Mythos。

整体判断：链路不是不可用，而是处于“能发布，但缺少质量防线和可观测性”的状态。优先改造方向应是：保存中间产物、增强候选召回、增加发布前质量门禁、补齐重试/告警/幂等。

## 2. 当前链路现状

### 2.1 定时触发

- Cron job ID：`76297415d88d`
- 名称：`AI日报单任务09:30`
- 实际 schedule：`0 10 * * *`
- 模式：`no_agent: true`
- 脚本：`ai_daily_report_cron.py`
- 投递：`origin`
- 工具集：`terminal`
- 最近状态：6/10 10:02:46 运行成功，下一次为 6/11 10:00

问题：任务名仍写 09:30，但实际为 10:00；这会误导运维判断，尤其橘鸦源约 09:34 更新后，调度时间曾多次调整。

### 2.2 Wrapper 执行流程

Wrapper 文件：`~/.hermes/scripts/ai_daily_report_cron.py`

流程：

1. 进入仓库 `~/.hermes/scripts/ai-daily-report`
2. 执行 `git pull --ff-only`
3. 设置 `PYTHONPATH`
4. 调用 `run_daily_report(mode='publish', source_mode='live', llm_mode='live')`
5. 打印采集数量、去重数量、发布 URL

问题：`git pull` 失败只打印 stderr，不阻断；最终可能继续用旧代码发布。

### 2.3 数据源配置

配置文件：`config/sources.json`

当前源：

| 源 | 类型 | 角色 | timeout | retries | 状态 |
|---|---|---|---:|---:|---|
| AI HOT | `aihot` | primary | 25s | 2 | 正常 |
| InfoQ AI | `rss` | supplement | 25s | 1 | 正常，3 天年龄过滤 |
| MIT 科技评论 AI | `rss` | supplement | 25s | 1 | 正常，5 天年龄过滤 |
| 量子位 | `rss` | supplement | 25s | 1 | 正常 |
| 橘鸦AI早报 | `juya_rss` | supplement | 45s | 2 | 6/9 起 404/错误 |

注意：`retries` 字段存在于配置，但当前采集代码没有真正按配置重试。

### 2.4 生成发布管线

核心文件：`ai_daily_report/pipeline.py`

当前阶段：

| Stage | 模块 | 说明 |
|---|---|---|
| 0 | `collect.py` | 并发采集 |
| 1 | `normalize.py` | 清洗、canonical URL、质量 flags |
| 2 | `dedupe.py` | URL/标题硬去重 + 标题相似候选 |
| 2.5 | `dedupe.py` | 跨天 URL 去重 |
| 3 | `semantic_dedupe.py` | LLM 语义去重，仅审 Stage 2 候选 |
| 4 | `rewrite.py` | LLM 改写 + 分类 |
| 5 | `classify.py` | 分类校验/兜底 |
| 6 | `guide.py` | LLM 导览 |
| 7 | `assemble.py` | Markdown 组装和基础校验 |
| 8 | `publish.py` | 创建、发布、更新 URL 历史 |

### 2.5 近期运行数据

本地完整 `run_report.json` 覆盖 2026-06-04 至 2026-06-10。

| 日期 | 原始条数 | 最终条数 | 橘鸦 | Stage2 候选 | Stage3 删除 | 发布 |
|---|---:|---:|---:|---:|---:|---|
| 6/4 | 90 | 89 | 23 | 1 | 0 | ok，slug 为 `ai-2026-06-04-2` |
| 6/5 | 88 | 82 | 24 | 0 | 0 | ok |
| 6/6 | 86 | 82 | 21 | 1 | 1 | ok |
| 6/7 | 53 | 52 | 5 | 0 | 0 | ok |
| 6/8 | 53 | 52 | 5 | 0 | 0 | ok |
| 6/9 | 51 | 51 | 0/error | 0 | 0 | ok |
| 6/10 | 50 | 41 | 0/error | 0 | 0 | ok |

结论：Stage 3 多数日期没有候选，语义去重实际经常没有工作。

## 3. 发现的问题

### 3.1 P0：语义去重候选召回失效

证据：

- 6/5、6/7、6/8、6/9、6/10 的 `stage3.candidate_group_count=0`
- 6/10 明显存在 Claude Fable/Mythos 同事件多条，但 `stage2.possible_duplicates=[]`
- `semantic_dedupe.py` 在 candidates 为空时直接返回，不会主动审查所有 items

涉及代码：

- `ai_daily_report/pipeline.py`：Stage 3 candidates 只来自 `stage2.possible_duplicates`
- `ai_daily_report/dedupe.py`：候选召回只基于标题相似度

影响：重复新闻会绕过去重直接发布；用户看到的是同一事件拆成多条，日报质量下降。

### 3.2 P0：发布前质量门禁过弱

当前 `validate.py` 只检查：空 items、Markdown 太短、无章节、JSON 碎片、无 URL、非法 section。

缺失检查：

- 同实体高频出现
- 同标题高相似度
- 同一源失败导致覆盖缺口
- Stage 3 候选为 0 的异常状态
- 最终 Markdown 中重复标题/同事件重复

近期扫描样本：

| 日期 | 可疑重复 |
|---|---|
| 6/4 | OpenClaw 两条、Suno 融资两条 |
| 6/5 | Google Magenta RealTime 2 两条 |
| 6/6 | Open Code Review 两条 |
| 6/8 | OpenAI 芯片核心成员跳槽 Anthropic 两条 |
| 6/9 | 高德 ABot-Earth0.5 两条 |
| 6/10 | Claude Fable/Mythos 多条 |

### 3.3 P0：源失败仍发布，告警不充分

证据：

- 6/9、6/10 橘鸦源状态为 `error`，条数为 0
- Stage 8 仍 `status=ok`
- cron 回执只展示采集数量，不突出源异常原因

影响：用户不知道日报缺失一个重要补充源，也无法判断当天内容覆盖是否可靠。

### 3.4 P1：配置项未全部生效

`config/pipeline.json` 中存在：

```json
"rewrite_batch_size": 10
```

但 `pipeline.py` 调用 `rewrite_items()` 时未传入该配置，实际使用 `rewrite.py` 默认 `batch_size=30`。

影响：配置与真实行为不一致；后续调参容易误判。

### 3.5 P1：HTTP fetch 无统一重试/backoff

`clients.py::fetch_text()` 只做单次 `urllib.request.urlopen`。虽然 `sources.json` 有 `retries` 字段，但 `collect.py` 没有按配置重试。

影响：临时网络波动会直接变成源失败；错误类型也未细分为 404、timeout、parse_error、empty。

### 3.6 P1：发布流程缺少幂等保护

`publish.py` 直接 `create_post` 再 `publish_post`。如果同日重复运行，平台可能生成 `ai-YYYY-MM-DD-2` 这类 slug。

证据：6/4 发布 URL 为 `https://blog.ephron.ren/posts/ai-2026-06-04-2`。

影响：同一天可能出现多个日报版本；历史 URL 与预期 slug 不一致。

### 3.7 P1：中间产物不足，回放困难

当前输出只有：

- `blog_markdown.md`
- `run_report.json`

缺少：

- `stage1_items.json`
- `stage2_items.json`
- `stage2_5_items.json`
- `stage3_items.json`
- `stage4_items.json`
- LLM prompt/response 摘要或 hash

影响：一旦用户反馈重复/幻觉/分类错误，很难还原某条新闻在每个阶段的标题、摘要、URL、候选关系。

### 3.8 P2：cron wrapper 与包内配置割裂

Wrapper 固定传：

- `mode='publish'`
- `source_mode='live'`
- `llm_mode='live'`
- `base_url='https://blog.ephron.ren'`

同时 `pipeline.json` 又有 `default_mode='dry-run'`。配置来源不统一。

影响：调试和生产行为容易混淆。

### 3.9 P2：Skill 文档与代码阈值曾出现不一致

技能文档曾记录 title Jaccard 阈值为 0.25，但代码实际为 0.40。该问题说明“运维知识库”和代码配置缺少自动校验。

影响：排障时容易根据过期文档做错误判断。

## 4. 问题影响

| 问题 | 直接影响 | 长期影响 |
|---|---|---|
| 语义去重候选为 0 | 重复新闻发布 | 用户对日报质量信任下降 |
| 源失败静默发布 | 内容覆盖缺口不可见 | 误以为日报完整 |
| 发布前门禁弱 | 明显质量问题进入公开博客 | 后续需要人工返工或删除重发 |
| 配置不生效 | 运维调参无效 | 形成错误排障经验 |
| 无重试/backoff | 临时波动放大成源失败 | 稳定性依赖运气 |
| 发布不幂等 | 同日多 slug | 历史链接、引用和 SEO 混乱 |
| 中间产物缺失 | 排查成本高 | 无法建立可靠回归测试集 |

---

## 5. 优先级排序

| 优先级 | 事项 | 原因 |
|---|---|---|
| P0 | 新增 Stage 2.8 语义候选召回 | 当前 Stage 3 经常没有候选，语义去重实际失效 |
| P0 | 发布前质量门禁 | 阻止明显重复、源失败、空候选直接发布 |
| P0 | 保存中间 item 快照 | 支撑回放、调试、回归测试 |
| P1 | 统一重试/backoff 与错误分类 | 提升源稳定性，减少静默失败 |
| P1 | 发布幂等保护 | 避免同日多版本和 slug 漂移 |
| P1 | 让 pipeline 配置真实生效 | 消除配置与行为不一致 |
| P2 | 统一 wrapper 与包内 CLI 配置 | 降低维护成本 |
| P2 | 技能文档自动校验 | 防止知识库漂移 |

## 6. 具体优化建议与改造方案

### 6.1 新增 Stage 2.8：语义候选召回

新增文件：`ai_daily_report/candidate_recall.py`

目标：不新增 LLM 调用，先用规则扩大 Stage 3 的候选池。

建议召回特征：

- 标题字符相似度
- 标题 token Jaccard
- 摘要 token Jaccard
- 公司/产品/模型实体重叠
- URL 域名与来源类型
- 事件阶段词：发布、即将发布、爆料、上线、开源、融资、收购

输出示例：

```json
{
  "item_ids": ["item_a", "item_b"],
  "reason": "entity_overlap",
  "score": 0.78,
  "shared_entities": ["Claude Mythos", "Claude Fable"]
}
```

接入位置：`pipeline.py` 中 Stage 2.5 之后、Stage 3 之前。

### 6.2 增强 Stage 3：支持同事件合并

当前 Stage 3 只有 `duplicate_groups`。建议增加：

```json
{
  "duplicate_groups": [],
  "merge_groups": [],
  "not_duplicates": [],
  "uncertain": []
}
```

策略：

- `duplicate_groups`：同一新闻，删除重复项
- `merge_groups`：同一事件不同角度，保留主条目，把其他来源作为补充来源
- `uncertain`：默认保留，避免误删

### 6.3 新增发布前质量门禁

建议新增模块：`ai_daily_report/quality_gate.py`

检查项：

- Stage 3 候选为 0 且 item 数大于 30：warning
- 任一强实体出现 3 次以上：warning 或 block
- 最终标题相似度高于 0.55：warning
- 任一 enabled source 状态为 error：warning
- required source 失败：block
- publish 前 `blocking_errors` 非空：阻断发布

### 6.4 保存中间产物

在 `runner.py` 中输出：

```text
stage0_sources.json
stage1_items.json
stage2_items.json
stage2_5_items.json
stage2_8_candidates.json
stage3_items.json
stage4_items.json
quality_gate.json
```

每条 item 至少保留：id、title_raw、title、summary_raw、summary、url、canonical_url、source_group、source_label、section、quality_flags、entities。

### 6.5 实现统一重试/backoff

改造位置：

- `clients.py::fetch_text`
- `collect.py::_collect_one`

建议：

- 按 `config.retries` 重试
- 对 429/500/502/503/504/timeout 使用指数退避
- 对 404 直接失败，不重试
- report 记录 `attempts`、`error_type`、`http_status`

### 6.6 发布幂等保护

改造位置：`publish.py`

建议：

- 发布前查询目标 slug 是否已存在
- 如果存在且内容 hash 相同：返回 `status=already_published`
- 如果存在但内容不同：默认阻断，除非显式 `allow_republish=true`
- 避免自动生成 `-2` slug 后误以为正常

### 6.7 让 pipeline 配置生效

改造位置：`runner.py`、`pipeline.py`

建议把以下配置传入实际函数：

- `rewrite_batch_size`
- `semantic_dedup_max_deletion_ratio`
- `quality_gate` 配置
- `semantic_candidate_recall` 配置

### 6.8 改进 cron 回执与失败告警

Wrapper 回执应包含：

- 每个源状态、条数、错误类型
- Stage 2/2.5/2.8/3 删除与候选数量
- 质量门禁结果
- 发布结果与实际 slug
- 如果源失败或质量 warning，必须在回执中显式显示

对于 no_agent cron：脚本 stdout 就是告警内容，应避免只输出“发布成功”。

## 7. 可执行改造计划

### Phase 1：可观测性与安全网

1. 在 `runner.py` 保存各阶段 item 快照。
2. 在 `validate.py` 或新增 `quality_gate.py` 增加重复/源失败 warning。
3. 修改 wrapper 回执，展示源失败和质量门禁结果。
4. 修正 cron job 名称为与实际时间一致。

交付标准：不改变内容生成结果，但能解释每条新闻的处理路径。

### Phase 2：去重召回升级

1. 新增 `candidate_recall.py`。
2. 在 `pipeline.py` 增加 Stage 2.8。
3. Stage 3 prompt 增加 `merge_groups`。
4. 建立 6/10 回归 fixtures。

交付标准：Claude Fable/Mythos 三条不再全部独立出现；Gemini/Gemma 仍保留。

### Phase 3：稳定性与发布治理

1. 实现 fetch retry/backoff。
2. 发布前做 slug 幂等检查。
3. 让 `pipeline.json` 配置真实生效。
4. 对 required source 失败设置阻断或 draft 降级策略。

交付标准：临时源波动不再轻易导致内容缺失；同日重复运行不会生成 `-2` 版本。

### Phase 4：长期维护

1. 建立 `tests/fixtures/recent_daily_reports/`。
2. 每次调整去重逻辑跑历史回放。
3. 将技能文档中的阈值、阶段说明改为从代码/配置生成或定期校验。
4. 增加每周自动审计报告，统计源失败率、重复候选、最终条数、fallback ratio。

---

## 8. 涉及文件和代码位置

| 文件 | 作用 | 建议动作 |
|---|---|---|
| `~/.hermes/scripts/ai_daily_report_cron.py` | cron wrapper | 阻断 git pull 失败、增强回执、展示 warning |
| `config/sources.json` | 源配置 | 明确 required/min_items/retries 语义 |
| `config/pipeline.json` | 管线配置 | 增加 quality_gate、candidate_recall、publish_idempotency |
| `ai_daily_report/clients.py` | HTTP/LLM/Blog client | 增加 retry/backoff、HTTP 错误分类 |
| `ai_daily_report/collect.py` | Stage 0 | 使用 config.retries，记录 attempts/error_type |
| `ai_daily_report/dedupe.py` | Stage 2/2.5 | 保留硬去重，减少标题候选职责 |
| `ai_daily_report/candidate_recall.py` | 新增 Stage 2.8 | 实体/摘要/标题综合召回 |
| `ai_daily_report/semantic_dedupe.py` | Stage 3 | 支持 merge_groups 和候选审计 |
| `ai_daily_report/rewrite.py` | Stage 4 | 配置 batch_size 生效，避免伪独立标题 |
| `ai_daily_report/validate.py` | Stage 7 校验 | 扩展质量门禁或迁移到 quality_gate |
| `ai_daily_report/publish.py` | Stage 8 | 增加 slug 幂等检查 |
| `ai_daily_report/runner.py` | orchestration | 保存中间产物，传递配置 |
| `tests/` | 测试 | 增加历史回放与重复回归测试 |

---

## 9. 验收标准

### 9.1 功能验收

- 6/10 回放中，Stage 3 `candidate_group_count` 不再为 0。
- Claude Fable/Mythos 三条不会全部独立发布。
- 6/4 OpenClaw/Suno、6/5 Magenta、6/6 Open Code Review、6/8 OpenAI 芯片、6/9 高德 ABot 样本能进入候选或被合并。
- Gemini/Gemma、Cursor Evals/Cursor 欧洲总部这类同公司不同事件不被误删。

### 9.2 稳定性验收

- 源 timeout/5xx 会按配置重试。
- 404 不重复重试，并在 report 中记录为 `http_404`。
- enabled source 失败会在 cron 回执中显著显示。
- required source 失败会阻断发布或降级为 draft。

### 9.3 发布验收

- 同日重复运行不会默认生成 `ai-YYYY-MM-DD-2`。
- publish result 明确区分 `ok`、`blocked`、`failed`、`already_published`。
- run_report 中包含实际 slug 和公开 URL。

### 9.4 可维护性验收

- 每次运行保存完整阶段快照。
- 新增测试覆盖 6/10 语义重复事故。
- `pipeline.json` 中配置项都有测试证明实际生效。
- 文档与代码阈值不再长期漂移。

---

## 10. 建议配置草案

```json
{
  "semantic_candidate_recall": {
    "enabled": true,
    "max_pairs": 80,
    "max_pairs_per_item": 5,
    "title_similarity_threshold": 0.45,
    "title_jaccard_threshold": 0.25,
    "summary_jaccard_threshold": 0.18,
    "strong_entity_overlap_threshold": 2
  },
  "quality_gate": {
    "block_on_required_source_failure": true,
    "warn_on_enabled_source_failure": true,
    "warn_when_stage3_candidates_zero_min_items": 30,
    "warn_on_final_title_similarity": 0.55,
    "warn_on_entity_frequency": 3
  },
  "publish_idempotency": {
    "enabled": true,
    "allow_republish": false
  }
}
```

---

## 11. 结论

当前 AI 日报定时任务的主链路已经能稳定产出，但质量治理还停留在“发布是否成功”的层面，没有充分检查“内容是否应该发布”。

最优先的改造不是继续调 LLM prompt，而是补齐工程链路：

1. 让每个阶段可回放；
2. 让语义去重有足够候选；
3. 让明显质量问题不能直接发布；
4. 让源失败、重复发布、配置不生效这类运维问题能被及时发现。