my-daily/ai-daily-main/docs/extra-sections-design.md at main

Files

T

poiuy 54ca4b1b6a feat: 军事科技每日资讯推送系统 - Docker部署 + 日志系统 + 数据目录重组

2026-07-12 20:01:02 +08:00

35 KiB

Raw Permalink Blame History

本文是对现有 push job 的能力扩展设计。在保持 RSS 主流程不变的前提下，新增三个板块仅在「早报」时段输出：GitHub 趋势、Hacker News 热议、跨板块行业洞察。

配套修改的源码模块、配置字段、数据契约见各章节。落地后需要把架构层结论合并回 docs/tech-spec.md，运行参数变更同步 README.md，进度记录写入 docs/plan.md。

created: 2026-05-16 updated: 2026-05-16（按用户决策重写：四模块独立、单页 GH trending、HN 单选 K=1、insights 结构由 prompt 决定）

1. 目标与范围

在每天的早报推送中，除了现有的 RSS 精选 digest，再加入：
- GitHub Trending：当日热门开源项目中筛选 1-3 个 AI 相关项目
- Hacker News：HN 首页中筛选 1 个最有讨论价值的 AI 相关热议（带评论与外链正文摘要）
- 行业洞察：基于上述三个板块 + 历史 insights 段做一段跨板块趋势小结
这三段内容只在早报时段生成（当天 schedule.push_cron 列表里最早那次触发），其余时段维持现有纯 RSS digest 行为
单板块失败 → 降级推送其他板块，整体任务仍算成功；RSS 失败 → 同现有行为，任务非 0 退出
不引入数据库；状态全部落到 news-data/ 的本地文件

2. 架构总览

push_job (cron 触发)
│
├─ Step 1: 早报判定
│      └─ 否 → 走原有纯 RSS digest 流程，结束
│
├─ Step 2: 四模块编排（前三路 asyncio.gather 并发，insights 串行后置）
│      ├─ run_rss_section(config, now)
│      ├─ run_github_section(config, now)
│      └─ run_hackernews_section(config, now)
│              ↓
│      └─ run_insights_section(rss_md, gh_md, hn_md, config, now)
│
└─ Step 3: push_job 上游
       └─ sentinel 包裹四段 → 拼装 markdown → 推送 → 写 push-*.md

关键设计选择：

模块自治。每个板块封装为 run_xxx_section(...) -> (markdown, error)，板块内部从抓取、enrich、LLM 总结全包；板块互不感知。
sentinel 由 push_job 统一包。模块返回裸 markdown（不含 sentinel），由上游 _assemble_with_sentinels() 包入 。这样模块不需要知道自己的板块标识，便于后续替换或加新板块。
失败自吞。模块内部捕获异常，返回 ("", error)；上游根据返回值决定是否在最终 push 中省略该段、是否走告警通道。
RSS 是核心。其他三个模块失败都是降级；RSS 模块失败仍按现有行为整体退出非 0。

并发模型：asyncio.gather，与项目通体异步风格一致。

3. 模块结构

src/
├── sections/                       ← 新增
│   ├── __init__.py                 # 暴露 run_rss_section / run_github_section / ...
│   ├── rss/
│   │   ├── __init__.py
│   │   └── section.py              # 把现有 collect_entries_for_push + compose_digest 流程搬入
│   ├── github/
│   │   ├── __init__.py
│   │   ├── trending_scraper.py     # HTML 抓取 + 解析(单页 https://github.com/trending)
│   │   ├── repo_enricher.py        # GitHub REST API:metadata + README
│   │   ├── history.py              # trending-history.json 读写 + 过期清理
│   │   └── section.py              # run_github_section 入口
│   ├── hackernews/
│   │   ├── __init__.py
│   │   ├── frontpage_scraper.py    # HTML 抓首页 30 条
│   │   ├── item_enricher.py        # Algolia /items/{id} + 外链正文(html_to_markdown)
│   │   └── section.py              # run_hackernews_section 入口
│   └── insights/
│       ├── __init__.py
│       └── section.py              # run_insights_section 入口
├── llm.py                          # 新增 4 个函数(GH/HN select/HN summarize/insights)
├── storage.py                      # 新增:sentinel 切片、trending-history、profile 字段
├── main.py                         # push_job 升级:早报判定 + 四模块编排
└── push/                           # 不变,平台层无感知

prompts/                            ← 新增 4 个
├── section_github.md               # 输入 enriched repo 数组 → 选 1-3 + 写 markdown
├── section_hackernews_select.md    # 30 条 frontpage 元数据 → 选 K 个 id(默认 K=1)
├── section_hackernews.md           # enriched story → 写 markdown(K=1 时不挑选,只行文)
└── insights.md                     # 输入三段成品 + 近 N 天 insights 段历史 → 写洞察段

news-data/
├── fetch-*.json                    # 不变
├── notify-*.md                     # 不变
├── push-*.md                       # 内容升级:含 sentinel 与 profile frontmatter
└── trending-history.json           # 新增:GH 已查阅 repo 索引

4. 数据契约

4.1 push 文件分段 sentinel

push 文件保留完整拼接写入磁盘和发送各平台，但用 HTML 注释 sentinel 划分板块边界。HTML 注释在 markdown 渲染中不显示，机器可解析，下游做"按段查重"时能精确切片。

---
pushDate: "2026-05-16T08:00:03+08:00"
profile: "morning"
sourceCount: 12
totalEntries: 12
---

<!-- SECTION:rss BEGIN -->
# 📰 AI Daily 每日精选 | 2026-05-16

*开头一句定调...*

### 1️⃣ ...
<!-- SECTION:rss END -->

<!-- SECTION:github BEGIN -->
## ⭐ GitHub 趋势

- **owner/repo** ⭐234 — 一句话价值定位
<!-- SECTION:github END -->

<!-- SECTION:hackernews BEGIN -->
## 🟧 Hacker News 热议

### 标题 (120 pts · 45 comments)
- 链接: url
- 要点:...
- HN 讨论: comments_url
<!-- SECTION:hackernews END -->

<!-- SECTION:insights BEGIN -->
## 💡 今日洞察

(行文结构由 prompts/insights.md 决定,代码不强加格式)
<!-- SECTION:insights END -->

某板块 markdown 为空 → 对应 sentinel 段整段省略（不留空标记，不留空 SECTION）。

4.2 分段提取函数（storage.py 新增）

def extract_section(push_md: str, section: str) -> str:
    """从 push 文件内容中切出 <!-- SECTION:{section} BEGIN/END --> 之间的 markdown。

    向后兼容:
    - 新 push 文件(带 sentinel): 按 sentinel 边界切片
    - 老 push 文件(无 sentinel) 且 section=='rss': 返回整个 body(老文件视为全 RSS)
    - 老 push 文件且 section in {github, hackernews, insights}: 返回空字符串
    """

def load_recent_section_titles(section: str, days: int, data_dir="news-data") -> str:
    """汇总近 days 天 push-*.md 的指定板块,提取标题级别清单(沿用 _extract_push_titles 思路)。

    仅 insights 板块在新增模块中使用本函数加载历史。
    GH/HN 板块按用户决策不传历史上下文给 LLM,不调用本函数。
    """

四个 LLM 与历史上下文的关系：

LLM 调用	recent context 数据源
`compose_digest` (RSS)	维持现有 `load_recent_push_titles(filter.push_context_days)`（老接口在 sentinel 升级后等价于 `load_recent_section_titles("rss", ...)`）
`summarize_github_trending`	不传
`select_ai_related_hn`	不传
`summarize_hackernews`	不传
`generate_trend_insights`	`load_recent_section_titles("insights", filter.push_context_days)`

{
  "repos": {
    "https://github.com/owner/repo-a": "2026-05-15",
    "https://github.com/owner/repo-b": "2026-05-12"
  },
  "updated_at": "2026-05-16T08:00:01+08:00"
}

写入语义（用户决策的精确语义）：

每次早报触发，按下列顺序处理：

加载 history，剔除 last_seen_date < today - filter.keep_days 的条目
抓 trending 页 → 得到 all_repos
对 all_repos 中每个 url：
- 若已在 history → history.touch(url, today)（更新日期），从候选移除
- 不在 history → 进入 candidates
把 candidates 中每个 url 也 history.touch(url, today) 写入 history
持久化 history（覆盖写）
对 candidates（即今日新出现的 repo）做后续 deep-dive 与 LLM 总结

效果：repo 在 trending 上挂多久就被屏蔽多久；过 keep_days 天没再出现则可重新推荐。

5. 模块详设

5.1 RSS 模块（迁移既有逻辑）

src/sections/rss/section.py::run_rss_section(config, now) -> (str, Optional[str])：

把现有 run_push_job 中"收集 + compose_digest"的部分原样迁过来，返回裸 markdown（不含 sentinel）+ 错误信息。无新增功能。

5.2 GitHub 模块

src/sections/github/section.py::run_github_section(config, now) -> (str, Optional[str])：

1. 抓取 trending 单页(HTML)
   GET https://github.com/trending
   解析 → all_repos: [{url, full_name, description, language, stars_today, stars_total}]

2. 加载 history 并清理
   history = load_trending_history(sections.github_trending.history_file)
   history.cleanup(keep_days=filter.keep_days)

3. 候选筛选(按 §4.3 语义)
   candidates = []
   for repo in all_repos:
       if repo.url in history:
           history.touch(repo.url, today)
       else:
           candidates.append(repo)

4. 候选写回 history + 持久化
   for repo in candidates:
       history.touch(repo.url, today)
   history.save()

5. 数量护栏
   if not candidates: return ("", None)              # 静默
   if len(candidates) > max_deep_dive:
       candidates = candidates[:max_deep_dive]        # 截断,默认 10

6. 并发 deep-dive(REST API)
   async for repo in candidates:
       meta = await fetch_repo_metadata(owner, repo)   # GET /repos/{o}/{r}
       readme = await fetch_readme(owner, repo)         # GET /repos/{o}/{r}/readme
   enriched = [{...repo, topics, license, pushed_at, readme_excerpt}]
   - 单 repo 任一请求失败 → 该 repo 跳过 + 错误聚合,不阻塞其他

7. LLM:summarize_github_trending(enriched, config)
   prompt: 候选数组(含 readme_excerpt) → 选 1-max_items + 写 markdown
   不传 recent_section_titles

8. 返回 (markdown, error)

REST API 调用细节：

调用	路径	取什么
metadata	`GET /repos/{owner}/{repo}`	`description, topics, language, license.spdx_id, pushed_at, stargazers_count, archived`
readme	`GET /repos/{owner}/{repo}/readme`	`content` (base64) → decode → 截断到 `readme_max_chars`

archived=true 的 repo 从候选剔除（trending 偶尔出现僵尸归档项目）
README 截断策略：前 readme_max_chars 字符（默认 10000，基于 trending 页 README 长度分布 p50≈25k 选定，详见 §14 决策记录）
鉴权：config.sections.github_trending.tokenName（默认 "GITHUB_TOKEN"）对应的环境变量存在时走 Authorization: Bearer {token}，否则匿名调用并接受 60 req/hr 上限（日 10 个 repo × 2 calls = 20 calls，匿名安全）

enriched repo 字段（喂给最终 LLM）：

{
  "url": "https://github.com/owner/repo",
  "full_name": "owner/repo",
  "description": "(来自 trending 页)",
  "language": "Python",
  "stars_today": 234,
  "stars_total": 12340,
  "topics": ["llm", "rag", "agent"],
  "license": "MIT",
  "pushed_at": "2026-05-15",
  "readme_excerpt": "(前 3000 chars)"
}

5.3 Hacker News 模块

src/sections/hackernews/section.py::run_hackernews_section(config, now) -> (str, Optional[str])：

1. 抓首页(HTML)
   GET https://news.ycombinator.com/news
   解析 30 条 → front: [{id, title, url, site, points, comments, comments_url}]

2. 轻 LLM 初筛:select_ai_related_hn
   输入: 30 条 frontpage 元数据(无正文)
   输出: K = sections.hackernews.select_k 个 story id(默认 K=1)
   if K 个为空 → return ("", None)                    # 静默

3. 并发 enrich 选中的 K 个 story
   async for story in selected:
     - 评论树:Algolia GET /api/v1/items/{id}
         → 取前 top_comments 条 L1(默认 30,按 HN ranking)
         → 每条 L1 下挂前 top_l2_per_l1 条 L2 回复(默认 3)
         → 每条 text 过 html_to_markdown,单条截断到 comment_max_chars(默认 2000)
         → 累计达 comments_total_chars(默认 60000) 立即停止,防离群 story 撑爆 prompt
         → 输出 tree JSON: [{"l1": "...", "replies": ["...", "..."]}, ...]
     - 外链正文:
         if story.url 指向 https://news.ycombinator.com/item?id=... (Show HN/Ask HN):
             从 Algolia 同次返回的 root.text 字段取(无外部请求)
         else:
             GET story.url → html_to_markdown → 截断到 link_content_max_chars(默认 50000,p50≈10k)
     - 单 story 任一失败 → 字段留空,metadata 仍传给最终 LLM

4. LLM:summarize_hackernews(enriched_stories, config)
   prompt: 对输入的 K 个 story 全部行文（K 通常 = 1）
   不传 recent_section_titles

5. 返回 (markdown, error)

Algolia API 接口：

GET https://hn.algolia.com/api/v1/items/{id}

返回 JSON：

{
  "id": 12345678,
  "title": "...",
  "url": "...",
  "points": 120,
  "author": "...",
  "text": null,                      // Show HN/Ask HN 的正文在这里
  "children": [                       // 顶层评论数组(按 HN ranking 排序)
    {"id": ..., "text": "<HTML>", "author": "...", "children": [...]},
    ...
  ]
}

优势 vs HTML 解析：免去 HN 的 td.ind[indent="0"] indent-tree 解析；评论文本是干净 HTML 字符串，直接 html_to_markdown。

Show HN / Ask HN 特例：

首页解析时 url 字段就是 https://news.ycombinator.com/item?id=X，作为"非外链"标记
enrich 时只调一次 Algolia（覆盖评论 + post 正文 text 字段），不再发外部请求

enriched story 字段（喂给最终 LLM）：

{
  "id": "12345678",
  "title": "...",
  "url": "...",
  "site": "example.com",
  "points": 120,
  "comments": 45,
  "comments_url": "https://news.ycombinator.com/item?id=12345678",
  "link_content": "(markdown, ≤3000 chars; Show HN 时是 post 正文)",
  "top_comments": [
    {"l1": "(markdown, ≤comment_max_chars)", "replies": ["(markdown, ≤comment_max_chars)", "..."]},
    ...
  ]
}

5.4 Insights 模块

src/sections/insights/section.py::run_insights_section(rss_md, gh_md, hn_md, config, now) -> (str, Optional[str])：

1. 加载历史
   recent = load_recent_section_titles("insights", filter.push_context_days)

2. LLM:generate_trend_insights
   输入: {"rss": rss_md, "github": gh_md, "hackernews": hn_md} + recent
   输出: insights 段 markdown
   注:行文结构、bullet 数量、风格约束等全部交给 prompts/insights.md,
      代码层不强加固定格式

3. 返回 (markdown, error)

如果某板块返回空（失败或本日无内容），prompt 里对应键标记 "(本次无内容)"，LLM 自行适配。

6. LLM 调用与 Prompt 策略

6.1 新增 LLM 函数（src/llm.py）

async def select_ai_related_hn(
    candidates: list[dict],     # 首页 30 条元数据(无正文)
    k: int,                      # 期望返回数量,默认 1
    config: dict,
) -> tuple[list[str], Optional[str]]:
    """轻量 LLM:从 HN 首页候选中挑出 k 个 AI 相关的 story id,只读 title/site/points/comments。
    返回 ([id1, ...], error)。"""

async def summarize_github_trending(
    enriched_repos: list[dict],   # 已 deep-dive 的 repo 候选(含 readme_excerpt + topics)
    config: dict,
) -> tuple[str, Optional[str]]:
    """选 1-max_items + 写 markdown 段。不传历史上下文。"""

async def summarize_hackernews(
    enriched_stories: list[dict], # 已 enrich(含 link_content 与 top_comments)
    config: dict,
) -> tuple[str, Optional[str]]:
    """对输入的 K 个 enriched stories 全部行文。K 由配置 select_k 决定，默认 1。
    不传历史上下文。"""

async def generate_trend_insights(
    sections: dict[str, str],   # {"rss": md, "github": md, "hackernews": md}
    recent_insights: str,        # load_recent_section_titles("insights", days)
    config: dict,
) -> tuple[str, Optional[str]]:
    """输入三段成品 + 近期 insights 标题,返回洞察段 markdown。"""

返回风格沿用 generate_immediate_push：成功返回 (content, None)，失败返回 ("", error_msg)。

单次早报推送的 LLM 调用预算：

调用	输入规模	用途
`compose_digest`	当日符合条件的 RSS 条目	现有，RSS digest 主体
`select_ai_related_hn`	30 条 HN 首页元数据	轻量；只读 title/site/points/comments
`summarize_github_trending`	≤ `max_deep_dive`=10 个 enriched repos	选 1-3 + 行文
`summarize_hackernews`	`K = select_k` 个 enriched stories（默认 1）	行文 K 条
`generate_trend_insights`	三段已生成 markdown + 近期 insights 标题	一段洞察

合计 5 次 / 早报。晚报维持现有 1 次。

6.2 关注领域（GitHub / HN 共用）

为避免领域定义在 3 个 prompt 里漂移，统一在此沉淀；各 prompt 在自身骨架里直接引用本节，不做重新发明。

正面关注：

AI Agent：智能体架构、工具链、多智能体、自主规划、Agent 框架
AI 模型：训练、推理、微调、量化部署、模型服务、语音 / 多模态 / 视觉模型
AI 基础设施：GPU 调度、芯片硬件、数据中心、推理优化、分布式训练、向量数据库、RAG 框架
大厂 / 前沿动态：Apple、Google、Meta、OpenAI、Anthropic、Microsoft、xAI 等公司的官方动作与战略
AI 集成的开发者工具：API 网关、自动化脚本、低代码平台等明确与 AI 协同的工具
有创新性的开源产品：日增长显著且有清晰用户价值（GH 板块专属）

负面排除（一律剔除）：

嵌入式开发（Arduino、ESP32、树莓派、单片机）
底层系统编程（内存分配器、编译器、链接器，与 AI 工作负载无明显关联时）
通用开发工具（命名规范、代码风格、纯前端模板、UI 组件库、管理后台模板、静态网站主题）
学习资源（纯教程仓库、面试题合集、Roadmap，除非是含实用代码的深度技术指南）
配置文件集合（Dotfiles、配置模板）
与 AI / 科技无关的内容（电子书、资源搬运、刷榜项目、明星项目搬运）
纯娱乐 / 高风险误用（deepfake 等无明确基础设施价值的项目）

6.3 Prompt 文件

prompts/section_github.md（骨架）

角色定位（"开源情报分析师"）
输入 schema 说明（JSON 数组：url / full_name / description / language / stars_today / stars_total / topics / license / pushed_at / readme_excerpt）
关注领域：引用 §6.2（正面列表与负面排除完整复制进 prompt）
选项规则：
- 从候选中挑 1-max_items 个最值得关注的项目
- 优先信号：stars_today 高 + topics 含 AI 标签（agent/llm/rag/inference/training 等）+ readme 描述明确 + 非纯模板/教程仓库
- 必跳过：archived=true（理论上已在 enricher 剔除，prompt 层兜底）、纯 awesome-list、个人配置 dotfiles
输出格式（markdown 列表）：
- - **owner/repo** ⭐{stars_today} — 一句话价值定位 [link]
- 一句话需点明"解决什么问题"，避免营销语
风格约束：与 prompts/digest.md 同源；负面句式（"震撼""炸裂""革命性"）禁用；避免套话

prompts/section_hackernews_select.md（骨架）

角色定位（"HN 早间选题人"）
输入：JSON 数组（30 条 frontpage 元数据：id / title / site / points / comments）
关注领域：引用 §6.2
任务：挑 k 个最符合关注领域的 story id（K 默认 1）
决策原则：title + site 不足以判定 AI 相关时，宁可漏选不可错选（错选会让最终 LLM 写出与 AI Daily 调性无关的内容）
输出：纯 JSON id 数组，如 ["12345"] 或 []（无任何匹配时返回空数组）
严禁输出任何解释性文字

prompts/section_hackernews.md（骨架）

角色定位（"HN 早间编辑"）
输入 schema 说明（K 个 enriched story，含 link_content 与 top_comments）
关注领域：引用 §6.2（K=1 时通常无需筛选，仅作为行文背景参考）
任务：对输入的 K 个 enriched stories 全部行文（不再二次挑选）
内容要求（每条 story）：
- 提炼原文核心（背景 / 要点 / 结论）
- 汇总 HN 评论区的有价值观点（支持 / 反对 / 补充），不是简单复述
- 若评论中出现明显反驳原文的观点，必须保留并标注

输出格式建议（最终以 prompt 实测为准）：

### 标题 (N pts · M comments)
- 链接: url
- 内容总结: 2-3 条核心要点
- 💬 HN 讨论: 1-2 条最有价值的观点（含反对意见）
- 🔗 HN 讨论页: comments_url

风格约束：客观、犀利、克制；避免与 RSS digest 句式雷同；不做宏大叙事

prompts/insights.md（骨架）

角色定位（"AI 行业观察员"）
输入：三段成品 markdown + 近 N 天 insights 板块清单
任务：基于三段产出做跨板块小结
风格约束：避免与 RSS digest 句式雷同；避免简单复述已经在其他板块出现过的具体新闻
结构与 bullet 数量交由 prompt 内部约定，code 层不限制

6.4 调用顺序与并发

async def _run_morning_push(config):
    rss_md, gh_md, hn_md = await asyncio.gather(
        run_rss_section(config, now),
        run_github_section(config, now),
        run_hackernews_section(config, now),
        return_exceptions=False,            # 各 section 自吞异常,不抛
    )

    insights_md, _ = await run_insights_section(rss_md, gh_md, hn_md, config, now)

    final = _assemble_with_sentinels({
        "rss": rss_md,
        "github": gh_md,
        "hackernews": hn_md,
        "insights": insights_md,
    })

    await send_to_platforms(final, config["push"])
    save_push_file(get_push_file(), final, profile="morning", ...)

_assemble_with_sentinels(sections: dict[str, str]) -> str 的契约：

按固定顺序拼装 rss → github → hackernews → insights
空 markdown 段整段省略（连同 sentinel）
段间留一个空行

7. 行业洞察板块设计

按用户决策，本节不在 code 层规定 insights 的格式：

bullet 数量、子标题、字数限制、固定栏目等都属于 prompt 工程范畴
调整方法：编辑 prompts/insights.md 而非改代码
输入合同（code 层保证）：
- sections["rss" | "github" | "hackernews"] 三个键的 markdown
- 任一板块为空时该键值为 "(本次无内容)"
- recent_insights：近 filter.push_context_days 天 insights 段标题清单（防风格趋同）
输出合同（code 层不校验）：直接作为 markdown 段插入

8. 配置 schema 增量

{
  "filter": {
    "min_score": 60,
    "hot_threshold": 90,
    "context_days": 2,
    "keep_days": 7,
    "push_context_days": 5,
    "no_content_marker": "[NO_NEW_CONTENT]"
  },
  "schedule": {
    "fetch_interval_minutes": 30,
    "fetch_lookback_minutes": 120,
    "push_cron": ["0 8 * * *", "0 17 * * *"],
    "timezone_hours": 8
  },
  "sections": {
    "github_trending": {
      "enabled": true,
      "max_items": 3,
      "max_deep_dive": 10,
      "readme_max_chars": 10000,
      "history_file": "news-data/trending-history.json",
      "request_timeout": 10,
      "tokenName": "GITHUB_TOKEN"
    },
    "hackernews": {
      "enabled": true,
      "select_k": 1,
      "top_comments": 30,
      "top_l2_per_l1": 3,
      "comment_max_chars": 2000,
      "comments_total_chars": 60000,
      "link_content_max_chars": 50000,
      "request_timeout": 10,
      "algolia_base": "https://hn.algolia.com/api/v1"
    },
    "insights": {
      "enabled": true
    }
  },
  "llm": {
    "prompts": {
      "score_batch": "prompts/score_batch.md",
      "immediate_push": "prompts/immediate_push.md",
      "digest": "prompts/digest.md",
      "section_github": "prompts/section_github.md",
      "section_hackernews_select": "prompts/section_hackernews_select.md",
      "section_hackernews": "prompts/section_hackernews.md",
      "insights": "prompts/insights.md"
    }
  }
}

向后兼容：

sections 整段缺失 → 等价于全部 enabled=false → push_job 走原有纯 RSS 路径
push_cron 为空 → 无早报触发,不生成新板块
旧 push 文件没有 sentinel → extract_section("rss", ...) 返回整个 body，其他 section 返回空字符串
GITHUB_TOKEN 未设 → GH 模块匿名调用，照常运行

9. 失败隔离与降级策略

失败位置	行为
`run_rss_section` 失败	整个 push_job 退出非 0（核心承诺不变）
GH trending 抓取 / 解析失败	`run_github_section` 返回 `("", error)` → 板块整段省略 → 告警
GH 单 repo metadata/readme 失败	该 repo 跳过 + 错误聚合，不阻塞其他 repo
GH summarize LLM 失败	板块整段省略，告警 `notify_llm_errors("section_github", ...)`
HN 首页抓取失败	同 GH
HN 轻 LLM 初筛失败或返回空	板块整段省略，告警（初筛失败）或静默（结果为空）
HN 单 story enrich 失败	字段留空，metadata 仍传给最终 LLM
HN summarize LLM 失败	板块整段省略，告警
insights LLM 失败	洞察段省略，其他板块照常推送，告警
早报判定为否	完全跳过 GH/HN/insights，不消耗任何额外 API
`sections.xxx.enabled=false`	对应模块直接返回 `("", None)`，静默跳过

整体准则：RSS 是核心，其余是增强。除 RSS 外的任何失败都不阻塞推送，但都通过现有 notify_llm_errors 通道发简单告警，方便事后排查。

10. 早报判定逻辑

def is_morning_push(now: datetime, config: Dict) -> bool:
    cron_list = config.get("schedule", {}).get("push_cron", [])
    if not cron_list:
        return False
    if len(cron_list) == 1:
        return True  # 唯一定时即"最早",任何触发都视为早报

    base = now.replace(hour=0, minute=0, second=0, microsecond=0)
    today_fires = [croniter(c, base).get_next(datetime) for c in cron_list]
    closest = min(today_fires, key=lambda f: abs(now - f))
    return closest == min(today_fires)

规则:push_cron 中 now 离哪条 cron 最近就归为那条;最近的那条若是当天最早的 cron,则视为早报。

为什么不再用单独的 morning_cron + 容差:

复用 push_cron,少一个配置项,加 cron 自动延展
「最近匹配」自动等价于容差 = 到次近 cron 距离的一半,systemd timer 漂移更稳健
单条 cron 部署自然变成"每次推送都是早报",与用户预期一致

11. 与现有模块的集成点

src/main.py::run_push_job 改造：
1. 开头加 is_morning = is_morning_push(now, config)
2. is_morning=False 时走原路径（compose_digest only）
3. is_morning=True 时进入 _run_morning_push 编排（四模块 + sentinel 拼装）
src/storage.py 新增：
- extract_section(content, section) + load_recent_section_titles(section, days, data_dir)
- load_trending_history(path) -> TrendingHistory、TrendingHistory.cleanup/touch/save
save_push_file 微调：frontmatter 带上 profile: "morning"|"default"，方便后续按 profile 分析
cleanup_old_files 增加对 trending-history.json 的"过期条目剪枝"（不删整个文件）
src/push/ 不动，平台层无感知
src/llm.py 新增 4 个函数：select_ai_related_hn / summarize_github_trending / summarize_hackernews / generate_trend_insights
src/sections/ 全新模块树（4 个子包）

12. 测试策略

新增单元测试：

tests/pytest/test_sections_github_scraper.py：本地 HTML fixture（保存几个真实 trending 页面快照）→ 测试解析
tests/pytest/test_sections_github_history.py：测试 TrendingHistory.touch/cleanup、URL 已存在/不存在分支
tests/pytest/test_sections_github_enricher.py：mock aiohttp → 测试 REST API 字段映射、archived 过滤、token 鉴权头
tests/pytest/test_sections_hackernews_scraper.py：HN 首页 fixture → 测试 30 条解析
tests/pytest/test_sections_hackernews_enricher.py：mock Algolia → 测试评论 top_comments 截断、Show HN 特例
tests/pytest/test_storage_sections.py：sentinel 切片（含老文件 fallback）、load_recent_section_titles
tests/pytest/test_morning_detection.py：cron 边界、容差、跨时区

新增交互式脚本（与现有 tests/*.py 风格一致）：

tests/run_morning_push.py：模拟一次完整早报，强制 is_morning=True
tests/fetch_trending.py：单独跑 GH 抓取 + deep-dive
tests/fetch_hackernews.py：单独跑 HN 抓取 + enrich

13. 实施步骤建议

按依赖顺序实施，每步可独立 PR / commit：

storage 层：sentinel 切片、trending-history.json 读写、load_recent_section_titles、save_push_file profile 字段、cleanup_old_files 对 history 文件的处理 + 单测
RSS 模块迁移：把现有 run_push_job 中的 RSS 流程提取为 run_rss_section，验证行为不变
GitHub 模块：trending scraper → history → enricher → section 入口 + 单测 + fixture
Hacker News 模块：frontpage scraper → Algolia enricher → section 入口 + 单测 + fixture
LLM 函数 + Prompt 文件：4 个新 LLM 函数 + 4 个 prompt
Insights 模块：依赖 §5.4，相对简单
push_job 升级：早报判定 + 四模块编排 + sentinel 拼装 + 失败隔离
配置 schema 升级：config.json.example 与 config.json 同步；README 配置详解章节补全
文档同步：docs/tech-spec.md 把架构升级合并；docs/plan.md 写进度

14. 关键决策记录

决策	方案	原因
新板块时机	仅早报（当天最早一次 `push_cron` 触发）	板块价值更适合一日一报；晚报维持原有 RSS 节奏；复用 push_cron 不引入新配置
模块边界	`src/sections/<board>/` 各自封装抓取+LLM+总结	模块自治便于扩展、替换、单测；上游编排极简
sentinel 归属	push_job 上游统一包	模块不感知自己的板块标识；新增板块零修改成本
GH trending 数据源	单页 HTML `https://github.com/trending`，无语言/since 过滤	用户决策：最简、最稳；语言过滤靠 topics + readme 在 LLM 层判
GH deep-dive 内容	REST API 拿 metadata + topics + README	topics 是 AI 相关性最强信号；metadata 补 license/pushed_at；README 给内容深度
GH 鉴权	GITHUB_TOKEN 可选	日 ~20 calls 远低于匿名 60 req/hr 上限；零配置即可跑
GH 筛选策略	history 过滤 → 全部 deep-dive → 一次 LLM 选 1-3	候选量小（5-15）；单次 LLM 比两阶段简单且选择质量高
GH 候选护栏	`max_deep_dive=10`	极端日（trending 大改）限制 HTTP 与 token 消耗
HN 数据源	首页 HTML + 评论/正文 Algolia	首页要"现场感"走 HTML；Algolia 评论 JSON 结构清晰，免去 indent-tree 解析
HN 筛选策略	30 条 → 轻 LLM 选 K=1 → enrich → 最终 LLM 行文	用户决策：把 enrich 工作量压到 1 个 story；轻 LLM 用 title 已足够判 AI 相关
HN 评论结构	L1 + 每个 L1 下挂 N 条 L2 回复,tree JSON 喂 LLM	真实数据:L2 信息量与 L1 持平(24 条/8k chars vs 18/6k);拍平丢失父子关系,LLM 无法识别"回复反驳了顶层"。Tree 结构让 LLM 看清论辩链
HN 评论上限	`top_comments=30`(L1)+ `top_l2_per_l1=3` + `comments_total_chars=60000`(总预算)	真实平均:L1 18 条/6k chars,L2 24 条/8k。30+3 给足余量但平均只跑 ~14k。总预算硬上限拦住离群 story(309 评论那种)
无历史上下文	GH / HN 板块均不传 recent_section_titles	用户决策：避免不必要的上下文污染；GH/HN 风格与 RSS digest 差异已足够大
insights 历史窗口	复用 `filter.push_context_days`	不引入新字段；insights 段需要历史防风格趋同
insights 输出结构	由 prompt 决定，code 不强加	用户决策：bullet 数量与栏目属于 prompt 工程，便于迭代
GH / HN 关注领域沉淀	在 §6.2 集中定义正面列表 + 负面排除，3 个 prompt 引用	避免领域定义在 prompt 间漂移；用户已明确兴趣边界（AI Agent / 模型 / 基础设施 / 大厂动态），排除嵌入式、底层系统、纯前端模板、学习资源等
板块 sentinel 用 HTML 注释	`<!-- SECTION:xxx BEGIN/END -->`	markdown 渲染不显示；机器易解析；老 push 文件零冲突
失败降级粒度	单板块失败省略本段；RSS 失败整体退出	RSS 是核心承诺，其他是增强
早报判定	cron + 容差，而非"今天第一次"	早报失败时晚报不会错误升级为长版本
截断参数初始值（2026-05-17 合入）	`readme_max_chars=3000` / `top_comments=20` / `comment_max_chars=500` / `link_content_max_chars=3000`	凭直觉给出的保守默认；上线后通过真实数据校准
截断参数校准（2026-05-17 合入后,激进路径）	`readme_max_chars: 5000→10000` / `top_comments: 20→50` / `link_content_max_chars: 6000→50000` / `comment_max_chars: 800` 不变 / `max_prompt_chars: 64000→150000`	用户决策:把 LLM 上下文用到 DeepSeek v4 flash 128k tokens 限的合理水平,优先内容深度而非 API 成本。Worst-case 单次 LLM prompt:GH≈110k chars / HN≈95k chars,均在 150k budget 内。中英混合 100k chars ≈ 30-50k tokens,远低于 128k 模型限
单板块 CLI（2026-05-17 合入后）	`python -m src.main github` / `hackernews`	便于 prompt 调优期反复跑单板块而不消耗全套 LLM 调用

hacker news 评论统计

┌─────────────┬──────────┬──────────────┬────────────────┬──────────┐ │ 层级 │ 平均条数 │ 平均 md 字符 │ 平均单条 chars │ 最大单条 │ ├─────────────┼──────────┼──────────────┼────────────────┼──────────┤ │ L1 顶层评论 │ 18 │ 5,952 │ ~330 │ 1,755 │ ├─────────────┼──────────┼──────────────┼────────────────┼──────────┤ │ L2 一级回复 │ 24 │ 8,166 │ ~340 │ 2,381 │ ├─────────────┼──────────┼──────────────┼────────────────┼──────────┤ │ L3+ 更深层 │ 41 │ 13,048 │ ~315 │ 2,291 │ ├─────────────┼──────────┼──────────────┼────────────────┼──────────┤ │ ALL 全部 │ 83 │ 27,166 │ ~330 │ 2,381 │ └─────────────┴──────────┴──────────────┴────────────────┴──────────┘

35 KiB Raw Permalink Blame History Unescape Escape

extra-sections-design.md — GitHub Trending / Hacker News / 行业洞察 板块设计