跨平台话题日报 — Agent Reach

你现在运行 agent-reach 技能。目标：给你一个公开话题（关键词、品牌名、开源项目），agent 在本地用 agent-reach 的 zero-key 通道并行扫一遍公开互联网，按通道分章节写出一份 Markdown 日报 + 一份自包含 HTML 预览：每条都有原文摘要、出处链接、平台 badge、抓取时间，开箱即读。课程主页：https://clawvard.school/courses/agent-reach 。

底层就是 agent-reach（MIT，作者 Panniantong）。本课程直接消费上游 PyPI/GitHub 项目。

这门课做什么（边界写在第一屏）

• ✅ 做：给一个话题 → agent 在本地启动 zero-key 通道 → 落 out/digest.md（YAML frontmatter + section-per-channel 卡片）+ out/agent-reach-<slug>-weekly.html（自包含、内联 CSS、详情页 iframe 直接渲染的卡片化预览）。
• ✅ Zero-key 通道（主路径，选 ≥ 3 个并行抓）：
  • Web via Jina Reader：curl -sS https://r.jina.ai/<URL> 读任意公开网页（Anthropic blog / 官方 docs / OSS README / 公众号公开文章页 / GitHub release page），返回 Markdown 正文，零 key、零登录。任何话题/项目都适用。
  • RSS via feedparser：用 Python 标准 feedparser 解析任何 atom/rss feed（GitHub releases.atom / commits.atom / tags.atom、官方 newsroom、PyPI release feed、Anthropic blog feed 等）。任何有公开 feed 的话题/项目都适用。
  • Hacker News via Algolia public API：https://hn.algolia.com/api/v1/search?query=<keyword>&tags=story 是公开免 key 的 HN 搜索 API，返回 JSON（title / url / points / num_comments / created_at / objectID）。适合宽口径热门话题（如 "Model Context Protocol"、"Cursor"、"vibe coding"）—— 这种话题在 HN 上有大量真实讨论；不适合冷门或长尾仓库名（Algolia 会把关键词拆 token 返回 broad noise，例如 query=agent-reach 命中的全部是 "AI Agents reach 100 members" 这类不相关 story）。判定标准：先用关键词跑一次，目测 title 是否真带主题词；若 ≥ 3 条不相关就不要用 HN，改用下面这一条。
  • GitHub via public REST API（OSS 项目主路径）：https://api.github.com/repos/<owner>/<repo> 拿 metadata（stars / forks / open_issues / pushed_at / language / license / subscribers_count），https://api.github.com/repos/<owner>/<repo>/issues?state=all&per_page=5&sort=updated 拿最近 issues + PRs（PR 也在 issues endpoint 返回，看 pull_request 字段区分），https://api.github.com/repos/<owner>/<repo>/releases?per_page=3 拿带完整 body 的 release notes。匿名 rate limit 60 req/h 对一次跑够用；不需要 GitHub token。这条是「冷门 OSS 项目」场景的 HN 替代。
  • 选哪 3 个：宽口径热门话题用 Jina + RSS + HN；单一 OSS 项目 用 Jina + RSS + GitHub REST。当 HN 对你的话题命中真实匹配 ≥ 2 条时可以同时用 HN + GitHub REST 凑 4 通道。
• ✅ agent-as-LLM：决定「下一步抓哪个 URL、怎么摘要」的"LLM"就是你（用户 session 里的 Claude Code / Cursor / Codex CLI / VS Code + Copilot 等）。所有摘要由 agent 用上下文窗口里的真实抓取内容现写。
• ✅ Markdown + 预览 HTML 两件套真的能复用：digest.md 是 RAG / 二次写作友好；agent-reach-<slug>-weekly.html 是自包含 SPA-style 单文件，详情页 iframe / object 直接渲染，无外链依赖（CSS 内联、字体走系统栈）。
• ❌ 不做：把整个文档站抓成 Markdown 知识库（→ web-to-knowledge-base）；让 agent 自己点点点登录后台（→ browser-agent）；写一封 HTML 邮件 newsletter（→ ai-newsletter）；写一篇小红书种草文（→ xiaohongshu）。
• 🔒 agent 自带模型即可：本课主路径不需要额外的 LLM 客户端 SDK。可选的「本周亮点 LLM 总结段落」走 Clawvard SDK 的 service method（需用户已配 Clawvard API key），缺 key 时课程仍然 fallback 跑通。

一句话定位：web-to-knowledge-base = 写入式，把一个文档站一次性 crawl 成本地 markdown 知识库；browser-agent = 行动式，让 agent 真的去登录/点击/填表；agent-reach = 阅读式，给一个话题，跨多个公开平台读回来，整理成一份按通道分章节的日报。三门正交。

前置条件

• Python ≥ 3.10（agent-reach 1.4.x 要求；python3 --version 检查）
• 能访问公开 PyPI / GitHub（一次性安装 ≈ 30 MB 上游工具，之后离线复跑只需要网络出向，不需要 token）
• 任一带 agent 能力的 IDE 做推理引擎：Claude Code / Cursor / Codex CLI / VS Code + Copilot Chat / Cline 等
• CPU 即可，没有 GPU；课程在本机离线运行
• 用 venv 或 pipx 安装（Ubuntu 24+ 的 PEP 668 会拒绝直接 pip install 到系统 Python）

安装（一次到位）

强烈建议在 venv 里装，避免和系统 Python 打架：

python3 -m venv .arv
source .arv/bin/activate
pip install --upgrade pip
# 上游 PyPI 包名 = agent-reach；GitHub 源码地址 = Panniantong/agent-reach
pip install agent-reach
agent-reach --version
agent-reach doctor          # 列出所有通道状态：✅ / ⚠️ / ❌

🛡️ 安全模式（不自动装系统包，只告诉你需要什么）：agent-reach install --safe。

📦 PyPI 名称暂未发布？ 用 editable clone：git clone --depth 1 https://github.com/Panniantong/Agent-Reach.git && pip install -e ./Agent-Reach。不要走 pip install "git+https://github.com/Panniantong/Agent-Reach.git" 或 pipx install "https://github.com/Panniantong/Agent-Reach/archive/main.zip" —— 上游 pyproject.toml 的 hatchling [tool.hatch.build.targets.wheel.force-include] 会与 packages = ["agent_reach"] 在 wheel 元数据阶段冲突，报 A second file is being added to the wheel archive at the same path: agent_reach/guides/setup-exa.md.（上游已立 issue #308 追踪）。editable 安装不会走 wheel build，绕过这条故障。

装完会有 agent-reach CLI（doctor / install 等子命令）+ Python 依赖 feedparser / yt-dlp / requests。skill 会被写到 ~/.claude/skills/agent-reach（Claude Code）或同等位置——这是上游自带 SOP，本课在它之上加 「跨平台话题日报」语义层：一次跑、按通道分章节、产出 Markdown + 自包含 HTML。

主路径（Zero-key channels）

agent-reach doctor 输出里 ✅ 装好即用的零 key 通道里，选 ≥ 3 个并行扫。下面是验证过的四条主线，按话题类型选 3 条组合：

1. Web via Jina Reader（任意公开网页）

curl -sS -L "https://r.jina.ai/<https://公开页面的完整URL>" -o out/raw/jina-01.md
# 返回 Markdown 正文 + 元数据 header；可直接读，零 key、零登录、自动跳过 cookies/JS gate

挑 4 个左右对话题最有信号的公开页面：官方 announcement、官方 docs introduction、OSS 仓库 README、一段重量级公开讨论（HN story page / 官方 blog comment）。每条提取 title + 30–60 字摘要 + source URL + platform badge + 抓取时间。

2. RSS via feedparser

import feedparser, json, datetime
feeds = [
  ("MCP spec releases",    "https://github.com/modelcontextprotocol/modelcontextprotocol/releases.atom"),
  ("MCP servers releases", "https://github.com/modelcontextprotocol/servers/releases.atom"),
]
items = []
for name, url in feeds:
    d = feedparser.parse(url)
    for e in d.entries[:5]:
        items.append({
            "feed": name,
            "title": e.get("title"),
            "link": e.get("link"),
            "published": e.get("published") or e.get("updated"),
        })
print(json.dumps(items, ensure_ascii=False, indent=2))

GitHub 给每个仓库自动暴露 <repo>/releases.atom、<repo>/commits.atom、<repo>/tags.atom，零 key、零 token，足够做"上周新动作"基线。同样的 feedparser.parse(...) 适用于 PyPI release feed、官方 newsroom feed、社区聚合 feed。

3a. Hacker News (Algolia public API) — 宽口径话题首选

curl -sS "https://hn.algolia.com/api/v1/search?query=<URL-encoded keyword>&tags=story&hitsPerPage=10" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); [print(h['title'], h.get('url') or 'item?id='+h['objectID'], 'pts', h.get('points'), 'cmts', h.get('num_comments')) for h in d['hits']]"

`hn.algolia.com/api/v1/{search,search_by_date}` 是 HN 官方搜索的免 key 公开 API，返回 JSON 包含 title / url / author / points / num_comments / created_at / objectID。挑 3 条「points 最高」或「最近一周新发」的真实讨论，每条放进 digest 时同时给出"872 ↑ · 258 comments"这种社交信号。

⚠️ 冷门话题陷阱：Algolia 会把 `agent-reach`、`Panniantong/agent-reach` 这种长尾 token 拆开，命中 "AI Agents reach 100 members" / "Reaching #86 on HackerOne" 这种 broad noise（实测：`query=agent-reach` 5 命中全部不相关）。判定标准：先跑一次，目测 `title` 是否真带主题词；若 ≥ 3 条不相关就换 GitHub REST 通道，不要硬塞不相关条目进 digest。

3b. GitHub via public REST API — 单一 OSS 项目首选

# 1) Repo metadata：一条 "Project pulse" 卡（stars / forks / open_issues / pushed_at / language / license）
curl -sS "https://api.github.com/repos/<owner>/<repo>" -o out/raw/gh-repo.json

# 2) 最近 issues + PRs（API 把 PR 也作为 issue 返回，看 pull_request 字段区分）
curl -sS "https://api.github.com/repos/<owner>/<repo>/issues?state=all&per_page=5&sort=updated" \
  | python3 -c "import json,sys; [print(i['number'], i['state'], i['title'][:70], i['html_url']) for i in json.load(sys.stdin)]"

# 3) Release notes 详细 body（与 RSS 通道不冲突 —— REST 返回完整正文，RSS 只能拿到标题 + 日期）
curl -sS "https://api.github.com/repos/<owner>/<repo>/releases?per_page=3" \
  | python3 -c "import json,sys; [print(r['tag_name'], '|', (r.get('name') or '')[:60], '|', r['published_at']) for r in json.load(sys.stdin)]"

api.github.com/repos/<owner>/<repo>{,/issues,/releases,/contributors} 全部零 key、零 token；匿名 rate limit 60 req/h，对一次跑足够。对单一 OSS 项目最稳：HN 对冷门仓库名通常无真实命中，GitHub REST 永远能拿到 repo metadata + 最近 issues/PRs + 完整 release notes 三类不可替代的 first-party 数据。每条卡片 platform badge 写 `GitHub Issues` / `GitHub Releases` / `GitHub Repo` 区分。

输出契约（落盘 schema）

每次跑都必须落到 ./out/：

out/
├── raw/                            # 原始抓取材料（Jina markdown / RSS json / HN json）
├── digest.md                       # 主交付物
├── digest.json                     # 结构化 mirror（详情页 / 二次写作友好）
└── agent-reach-<topic-slug>-weekly.html  # 自包含 HTML 预览

digest.md 一定要有 YAML frontmatter（字段固定）+ 按通道分 section + 每条卡片字段齐全：

---
topic: <topic name>
date_range: 2026-05-29 → 2026-06-05
channels:
  - Web via Jina Reader
  - RSS via feedparser
  - Hacker News (Algolia search)
total_items: 11
created: 2026-06-05T08:19:30Z
---

# <topic name> — weekly digest

## Web via Jina Reader (4 items)

### <Title>
<30–60 字中文或英文摘要，写人话，不要把 URL 当摘要>

Source: <URL> · Platform: <name> · Fetched: <ISO-8601>

…

agent-reach-<topic-slug>-weekly.html 必须满足：

1. 顶栏出现 Topic + 日期窗口 + 通道 chip（每个 chip 上的条数必须与下方实际条目对得上）
2. 至少 3 个 zero-key 通道 section（任 3 of {Jina / RSS / HN / GitHub REST}）
3. 总条目 ≥ 8 条
4. 每条卡片字段齐全：title / summary（30–60 字） / source URL / platform badge / fetched_at
5. source URL 必须可点开，落地页与 summary 内容对得上
6. 底栏 source attribution 出现 Panniantong/agent-reach 仓库链接 + MIT license
7. 自包含、内联 CSS、详情页 iframe 直接渲染、无外链脚本依赖

Prompt 模板（话题 → 报告）

复制改写：

启动 agent-reach skill。我要"<话题>"的最近 <N> 天跨平台 digest，只走 zero-key 通道（不要碰 cookie 通道）：

1. 跑 `agent-reach doctor`，告诉我 zero-key 通道现在哪些 ✅。
2. 根据话题类型选 3 个 zero-key 通道并行抓素材：
   - **宽口径热门话题**（产品类 / 概念类 / Show HN 出过的项目）用 Jina + RSS + HN；
   - **单一 OSS 项目 / 冷门长尾仓库** 用 Jina + RSS + **GitHub REST**（HN 对长尾仓库名通常 0 真实命中，会带 broad noise；GitHub REST 永远能拿 repo metadata + 最近 issues/PRs + 完整 release notes）；
   - 两类都需要可同时跑 4 通道。

   - Web via Jina Reader：自己挑 4 个左右对这个话题最有信号的公开 URL（官方 announcement / 官方 docs / 公开 GitHub README / 一段重量级公开讨论），`curl https://r.jina.ai/<URL>` 抓回 Markdown 正文。
   - RSS via feedparser：用 2 个 GitHub `releases.atom`（或 `commits.atom` / 官方 newsroom）或同等公开 atom feed，各取最近 ≤ 4 条。
   - Hacker News (Algolia)：`curl "https://hn.algolia.com/api/v1/search?query=<URL-encoded keyword>&tags=story&hitsPerPage=10"`，挑 points 最高的前 3 条 story；若返回 ≥ 3 条与话题无真实关联（title 不带主题词）就**切到 GitHub REST**。
   - GitHub REST：`curl "https://api.github.com/repos/<owner>/<repo>"` 拿 metadata 写一条 Project pulse 卡；`curl "https://api.github.com/repos/<owner>/<repo>/issues?state=all&per_page=5&sort=updated"` 取 ≥ 2 条最近 issues/PRs；可选 `curl "https://api.github.com/repos/<owner>/<repo>/releases?per_page=3"` 补一条完整 release notes。

3. 把结果落盘到 ./out/digest.md：YAML frontmatter（topic / date_range / channels[] / total_items / created），正文按通道分 section，每条 `### <title>` + 30–60 字摘要 + `Source: <URL> · Platform: <name> · Fetched: <ISO>`。同时落一份 ./out/digest.json mirror。
4. 再生成一份 ./out/agent-reach-<topic-slug>-weekly.html：顶栏 Topic + 日期窗口 + 通道 chip（标真实命中条数），主体卡片化渲染同一份 digest，每条至少有 title / summary / source URL / platform badge / fetched_at；底栏 source attribution 写 "Built with agent-reach (https://github.com/Panniantong/agent-reach) · MIT"。CSS 必须内联，不外链任何资源。
5. 课程主路径不需要额外的 LLM key；如果你想给 digest 加一段"本周亮点"总结，**只在用户已配 Clawvard API key 时**走 Clawvard SDK，缺 key 时 fallback 跑通。

最后打印通道命中数、总条目数、./out 目录树。

自检（task 结束前一定要做）

跑完一次，agent 必须自检：

1. out/digest.md YAML frontmatter 五个字段齐全（topic / date_range / channels / total_items / created）；每个 section 至少 2 条；每条卡片有 title + summary + Source + Platform + Fetched。
2. out/agent-reach-<topic-slug>-weekly.html ≥ 12 KB、顶栏通道 chip 与下方 section 条数一致、底栏出现 https://github.com/Panniantong/agent-reach 和 MIT。
3. 用 head -1 out/agent-reach-*.html 检查无 <script src="...外链..." 或 <link rel="stylesheet" href="...外链..." 出现（自包含约束）。
4. 抽查至少 3 个不同通道的 Source URL 在浏览器或 curl -I 下可解析；若某条返回 4xx/5xx，按"通道总数与最低条目数不可降级"原则换一条等价的 URL 补上。
5. HN 相关性闸：用了 HN 通道时，每条卡的 title 必须真带主题词（关键词、品牌名、项目名出现至少一次）；若 Algolia 返回 broad 命中（例如 query=agent-reach 命中的 "AI Agents reach 100 members"），视为 0 命中并切换到 GitHub REST 通道，绝不把不相关条目塞进 digest 凑数。
6. 域名扫描：grep -E "clawvard\.com|clawvard\.co|api\.clawvard|token\.clawvard|https://[^\"]*/v1" out/* 必须空集；命中即修（HN Algolia 的 hn.algolia.com/api/v1/search 是合法零 key 公开 API，不在禁用列表内）。课程允许的 host 只有 clawvard.school 与 service.clawvard / Clawvard SDK 命名空间。
7. 目标站尊重：每个抓取动作之间 ≥ 300 ms；遵守 robots.txt 与公开 ToS；Jina Reader 是公开代理，不替你处理目标站的速率约束，得自己控。GitHub 匿名 REST limit 60 req/h，一次跑务必合理调用。

Advanced Section — 非默认主路径

下面这些通道不进 popularTasks、不进 showcase，仅验证「文档可达 + 命令可读」。日常使用时若用户已经一次性配好 cookie / API key，可以按需启用。

yt-dlp（YouTube / Bilibili 字幕 + 元数据）

# YouTube 标题 + 自动字幕（首次需 Chrome cookies 或 JS runtime；CI/sandbox 通常被反爬挡）
yt-dlp --skip-download --write-auto-sub --sub-lang en \
  --convert-subs vtt --no-warnings \
  --print "%(.{id,title,uploader,duration,upload_date})j" "<YouTube URL>"

⚠️ 现实约束：纯 headless / 数据中心 IP 下 YouTube 经常返回 "Video unavailable" 反爬，需要 --cookies-from-browser=firefox 或 --cookies cookies.txt（用户在本地浏览器登录一次性导出）。不要把私人 cookie checkin 任何代码仓库；Cookie 文件只放 ~/.agent-reach/ 或本地 .gitignore 路径。Vimeo / 大多数 1800+ 站点不需要这层 cookie。

WeChat 公开公众号文章（via Jina）

curl -sS -L "https://r.jina.ai/https://mp.weixin.qq.com/s/<article_id>" -o out/raw/wx-01.md

走 Jina Reader 是为了避开微信对 headless 抓取的 anti-bot 校验。只用公开可访问的文章 URL（不要 "Parameter error" 落地页）。agent-reach doctor 里 wechat 通道（mcporter + Exa MCP）是搜索 + 阅读的合并实现，需要 npm i -g mcporter && mcporter config add exa https://mcp.exa.ai/mcp 一次性配置，零 key。

Cookie 通道（X / Reddit / 小红书 / Bilibili / 微博 / 雪球 / 抖音 / LinkedIn / 小宇宙）

# 装可选通道（举例）
agent-reach install --env=auto --channels=twitter,xiaohongshu

# 一次性 cookie 注入：用 Chrome 插件 Cookie-Editor 导出 → 发给 agent → agent 写到 ~/.agent-reach/

这些通道要求用户在本地浏览器登录一次（可信账号），用 Cookie-Editor 导出 cookie，发给 agent 即可。本课程不要求用户配这些，也不会把它们写进 popularTasks 主线或 showcase。配好后，twitter search "<topic>" / rdt search "<topic>" / xhs note "<URL>" 等命令即可加入 digest。请把 cookie 当作敏感凭据：不要 commit 到仓库，不要写进 dom_summary，不要分享给第三方。

与相邻课的边界

• 想把一个文档站抓成 markdown 知识库 → web-to-knowledge-base（静态、写入式）。
• 想让 agent 真的去登录 + 点击 + 抓登录后页面 → browser-agent（行动式）。
• 想把 digest 写成一封 HTML 邮件发出去 → ai-newsletter（写一封信）。
• 想把 digest 直接发成小红书图文 → xiaohongshu（生产内容）。
• 本课服务：一个公开话题 → 一份按通道分章节、自包含 HTML 可分享的跨平台 Markdown 日报，全程零商业 key。

学习完成后

告诉用户：

我已经学会了 agent-reach。给我一个话题（关键词、品牌名、开源项目），我在本地用 zero-key 通道（Jina Reader / RSS / Hacker News Algolia / GitHub public REST）并行扫一遍公开互联网，落 out/digest.md + out/digest.json + out/agent-reach-<slug>-weekly.html 三件套：YAML frontmatter 齐全、按通道分章节、每条都有原文摘要 + 出处链接 + 平台 badge + 抓取时间；同名自包含 HTML 可直接发链接给同事或丢进任何 docs 站 iframe。宽口径热门话题（产品类 / 概念类）用 Jina + RSS + HN；单一 OSS 项目（有具体 owner/repo）用 Jina + RSS + GitHub REST——HN 通道对冷门长尾仓库名常 0 真实命中。课程在本机离线运行；可选「本周亮点」总结仅在你配了 Clawvard API key 时走 Clawvard SDK。