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

> 本文是对现有 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
```

**关键设计选择**：

1. **模块自治**。每个板块封装为 `run_xxx_section(...) -> (markdown, error)`，板块内部从抓取、enrich、LLM 总结全包；板块互不感知。
2. **sentinel 由 push_job 统一包**。模块返回**裸 markdown**（不含 sentinel），由上游 `_assemble_with_sentinels()` 包入 `<!-- SECTION:xxx BEGIN/END -->`。这样模块不需要知道自己的板块标识，便于后续替换或加新板块。
3. **失败自吞**。模块内部捕获异常，返回 `("", error)`；上游根据返回值决定是否在最终 push 中省略该段、是否走告警通道。
4. **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 渲染中不显示，机器可解析，下游做"按段查重"时能精确切片。

```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 新增）

```python
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)` |

### 4.3 trending-history.json

```json
{
  "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"
}
```

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

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

1. 加载 history，剔除 `last_seen_date < today - filter.keep_days` 的条目
2. 抓 trending 页 → 得到 `all_repos`
3. 对 `all_repos` 中每个 url：
   - 若已在 history → `history.touch(url, today)`（更新日期），**从候选移除**
   - 不在 history → 进入 `candidates`
4. 把 `candidates` 中每个 url 也 `history.touch(url, today)` 写入 history
5. 持久化 history（覆盖写）
6. 对 `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）**：

```json
{
  "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：

```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）**：

```json
{
  "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）

```python
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 调用顺序与并发

```python
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 增量

```json
{
  "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. 早报判定逻辑

```python
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：

1. **storage 层**：sentinel 切片、`trending-history.json` 读写、`load_recent_section_titles`、`save_push_file` profile 字段、`cleanup_old_files` 对 history 文件的处理 + 单测
2. **RSS 模块迁移**：把现有 `run_push_job` 中的 RSS 流程提取为 `run_rss_section`，验证行为不变
3. **GitHub 模块**：trending scraper → history → enricher → section 入口 + 单测 + fixture
4. **Hacker News 模块**：frontpage scraper → Algolia enricher → section 入口 + 单测 + fixture
5. **LLM 函数 + Prompt 文件**：4 个新 LLM 函数 + 4 个 prompt
6. **Insights 模块**：依赖 §5.4，相对简单
7. **push_job 升级**：早报判定 + 四模块编排 + sentinel 拼装 + 失败隔离
8. **配置 schema 升级**：`config.json.example` 与 `config.json` 同步；README 配置详解章节补全
9. **文档同步**：`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    │
└─────────────┴──────────┴──────────────┴────────────────┴──────────┘