Ai News Radar

AI News Radar

First Reads

When this skill triggers inside the repo, read these files first:

• skills/ai-news-radar/README.md for the public-facing 伯乐Skill / Scout Skill positioning,

source-intake prompt, and install-after-first-message guidance.

• README.md for project usage and current commands.
• docs/GPT_HANDOFF.md before release-readiness checks or handing the project

to another agent.

• docs/SOURCE_COVERAGE.md before changing source strategy.
• docs/ROADMAP.md before changing Source Overlap Check, story merge, or version

planning.

• docs/V2_PRODUCT_BRIEF.md before changing product positioning or first-screen UX.
• scripts/update_news.py before changing data generation.
• assets/app.js, assets/styles.css, and index.html before changing the UI.
• references/source-intake.md when the user provides a new site, GitHub repo,

RSS feed, newsletter, X source, or asks whether a source can be ingested.

• references/v2-method.md when the user asks for product optimization, source

coverage strategy, Skill packaging, or "v2" direction.

V2 Workflow

Use this order for non-trivial product or source-strategy work:

1. Context pass: read the current docs, source status, recent commits, and the smallest relevant code surface before proposing changes. 2. Product diagnostic: identify the user, current workaround, signal-density problem, narrowest useful default, and what must stay in the advanced layer. 3. Coverage pass: classify each requested source as official feed, OPML, public GitHub-generated feed, public archive, static page, X bridge, optional API adapter, or private inbox/bridge. 4. Alternatives pass: when the choice is not obvious, present 2-3 approaches: minimal viable, durable architecture, and optional creative/packaged variant. 5. Implementation pass: make small diffs, reuse existing fetcher/UI patterns, add tests for behavior changes, and run the fastest relevant validation.

For detailed prompts and decision criteria, read references/v2-method.md.

Product Direction

Maintain a two-layer product:

• Default layer: a simple curated Signal view for ordinary AI enthusiasts.
• Advanced layer: custom OPML, source health, GitHub Actions, AgentMail email intelligence, and maintainer controls.

Avoid adding many reader-facing choices. Prefer better defaults, source quality, and clearer status output.

The v2 packaging goal is a forkable public site plus a reusable agent Skill. The public-facing Skill name is 伯乐Skill in Chinese and Scout Skill in English. It should feel concrete and easy to use: a scout that helps choose high-signal sources worth tracking, instead of implying that the system knows everything or blindly adding every noisy feed. Ordinary users should be able to browse the hosted page. Maintainers should be able to add their own sources with OPML, public generated feeds, or secret-backed optional adapters without changing the public default.

Safety Rules

• Never commit private feeds/follow.opml.
• Never paste secrets, tokens, cookies, browser exports, or .env values into code or logs.
• Keep the public repo runnable without API keys.
• Prefer official RSS/Atom/OPML sources over fragile scraping.
• Avoid account-bound social timelines as defaults.
• Prefer reading public generated feeds over reimplementing another project's

API or scraping pipeline.

• Treat X API, email, WeChat, private newsletters, and cookies as optional

advanced integrations. Store credentials only in environment variables or GitHub Secrets.

• Treat AgentMail as a private advanced source, not a public default source.

Never commit AGENTMAIL_API_KEY, AGENTMAIL_INBOX_ID, inbox addresses, full email bodies, raw emails, or private newsletter contents.

• Keep AgentMail disabled unless EMAIL_DIGEST_ENABLED=1 and both required

credentials are present. Only call the list-messages endpoint; do not call /raw or read text/html bodies.

• Do not publish data/email-digest.json to public Pages by default. Only allow

publication when the maintainer explicitly sets EMAIL_DIGEST_PUBLISH=1 and understands the site/repo privacy implications.

Add Personal Sources

When the user has installed or forked the project but does not know how to start, ask them for a source list first. A good kickoff prompt is:

请使用伯乐Skill，先问我要信息源清单，然后帮我判断每个信源该用 RSS、OPML、公开 feed、静态页面、Jina 兜底、AgentMail 邮箱还是跳过。目标是部署一个不需要服务器、能用 GitHub Actions 自动更新的 AI 日报网站。不要把任何 API Key、cookies、token、真实 OPML、邮箱正文或私有邮件内容写入仓库。

Use OPML for private customization:

cp feeds/follow.example.opml feeds/follow.opml
python scripts/update_news.py --output-dir data --window-hours 24 --rss-opml feeds/follow.opml

For GitHub Actions deployment, base64 encode feeds/follow.opml and save it as the repository secret FOLLOW_OPML_B64 to override the public demo OPML. If the secret is not configured, the workflow uses feeds/follow.example.opml as a small public RSS/OPML demo so the hosted page shows the OPML path working. Do not commit the private OPML file. For AgentMail, use EMAIL_DIGEST_ENABLED=1, AGENTMAIL_API_KEY, and AGENTMAIL_INBOX_ID only in environment variables or GitHub Secrets. Keep EMAIL_DIGEST_PUBLISH unset unless the maintainer explicitly wants a private Pages/repo to publish the metadata-only email digest.

Evaluate A New Source

When a user gives a source URL, first classify it:

• RSS/Atom/OPML: add privately through feeds/follow.opml unless it should help

every public visitor.

• GitHub project with generated feeds: inspect README, workflows, output files,

and raw JSON/RSS URLs; prefer consuming its public feed files.

• Official changelog or static page: add a focused fetcher only if stable.
• Newsletter: prefer public archive RSS or archive pages. Use AgentMail only for

private newsletter/product-update inboxes; keep it disabled by default and do not expose full bodies, raw emails, inbox ids, or private mailbox addresses.

• X/Twitter: prefer curated central feeds that already use official X API; direct

X API should be optional and secret-backed.

For detailed intake checks and implementation patterns, read references/source-intake.md.

Add A Built-In Source

Only add a built-in source when it is useful to most public visitors.

0. Run Source Overlap Check for candidate RSS/Atom sources before promoting them into the public default layer:

   python scripts/evaluate_source_overlap.py \
     --source-url https://example.com/feed.xml \
     --source-name "Example Source" \
     --site-id example_candidate \
     --baseline data/archive.json \
     --lookback-days 7 \
     --output reports/source-intake/example-overlap.json

Treat the report as advisory: low duplication supports accept_default, high duplication supports skip_duplicate, and small samples or medium duplication should stay watchlist / OPML advanced first. 1. Inspect existing fetchers in scripts/update_news.py. 2. Add fetch_<source>(session, now) returning list[RawItem]. 3. Use existing helpers for URL normalization, date parsing, and sessions. 4. Register the fetcher in the built-in task list. 5. Update docs/SOURCE_COVERAGE.md when coverage changes. 6. Add or update tests when behavior changes. 7. Run a local source-only probe before the full end-to-end generation.

GitHub Project Feed Pattern

For repos like follow-builders, look for public files such as:

• feed.json, feed-x.json, feed-blogs.json, latest.json
• state*.json for dedupe behavior
• .github/workflows/*.yml for schedules, secrets, and output commit paths
• config/*.json for source lists

If the generated feed is public, stable, timestamped, and low-noise, add a built-in fetcher that reads the raw GitHub URL. Do not copy its private tokens or rebuild its crawler unless the user explicitly wants a self-hosted variant.

Validate

Run the fastest relevant checks:

python -m py_compile scripts/update_news.py
python -m pytest -q
node --check assets/app.js
git diff --check
python "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" skills/ai-news-radar

For AgentMail changes, also verify default-off safety:

pytest -q tests/test_topic_filter.py -k agentmail

Confirm the checks cover: disabled AgentMail makes no network request, enabled but missing credentials makes no network request, the adapter only uses the list-messages endpoint, and email body/raw fields are not emitted.

When the Skill itself changes, validate the Skill package too:

python "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" skills/ai-news-radar

For an end-to-end local run:

python scripts/update_news.py --output-dir data --window-hours 24 --rss-opml feeds/follow.opml
python -m http.server 8080

Open http://localhost:8080 and confirm the Signal view, all-source view, WaytoAGI block, search, site filter, and source counts still work.

After pushing source changes, trigger and watch the workflow:

gh workflow run update-news.yml --repo LearnPrompt/ai-news-radar --ref master
gh run list --repo LearnPrompt/ai-news-radar --limit 5

<div align="center">

伯乐Skill

从一堆信源里选出千里马。

  

<br>

伯乐Skill is Scout Skill for AI News Radar.

它帮你判断哪些 AI 信息源值得长期追踪，并把它们接入一个自动更新的 AI 日报网站。

<br>

在线示例 · 安装 · 安装后第一句话 · 快速录入信息源 · 伯乐会选什么 · 工作原理

</div>

---

它解决什么问题

一到假期，信息焦虑就会变严重。

不是没东西看，而是东西太多了。

RSS里一堆更新，X上有人分享新工具，飞书知识库里还有资料，聚合站每天刷出几十页。真正的问题变成了：我到底该看什么？哪些源值得长期追？哪些源只是制造噪音？怎么把这些东西变成每天真的能看的AI日报？

AI News Radar原本是给自己用的AI日报网站，专门覆盖那些平时自然信息流里看不到的信息源。

但用了一段时间后，新的问题来了：如果一直往里面加信息源，它很快就会变成一天几千条、几万条更新。看起来很强，实际上还是看不完。

所以这次没有继续简单加源，而是在AI News Radar上做了一个Skill。

它叫：伯乐Skill。

伯乐Skill不是什么源都加。它只做一件事：

从乱七八糟的信源里，选出值得长期追踪的千里马。

---

在线示例

你可以先看公开版：

https://learnprompt.github.io/ai-news-radar/

这个页面会持续更新AI、开发者、官方博客、技术聚合站和公开日报类来源。

它不是最终答案，而是一个可以fork、可以改、可以接入你自己信息源的起点。

---

安装

如果你只是想看日报，不需要安装，直接打开在线页面即可：

https://learnprompt.github.io/ai-news-radar/

如果你想做自己的版本：

git clone https://github.com/LearnPrompt/ai-news-radar.git
cd ai-news-radar
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python scripts/update_news.py --output-dir data --window-hours 24
python -m http.server 8080

然后打开：

http://localhost:8080

如果你在Claude Code、Codex或其他支持Skill的Agent里使用，请让Agent读取：

skills/ai-news-radar/SKILL.md

---

安装后第一句话

安装或fork之后，不知道怎么开始，就直接对Agent说：

请使用伯乐Skill，先问我要信息源清单，然后帮我判断每个信源该用 RSS、OPML、公开 feed、静态页面、Jina 兜底、AgentMail 邮箱还是跳过。目标是部署一个不需要服务器、能用 GitHub Actions 自动更新的 AI 日报网站。不要把任何 API Key、cookies、token、真实 OPML、邮箱正文或私有邮件内容写入仓库。

这句话的作用是把Agent拉回正确路线：先判断来源，再决定接入方式，不要一上来乱抓网页。

---

快速录入信息源

你可以直接把信息源丢给伯乐Skill。

我想用伯乐Skill搭一个自己的AI日报网站。

这是我常看的信息源：

1. https://openai.com/news/
2. https://www.anthropic.com/news
3. https://huggingface.co/blog
4. https://news.ycombinator.com/
5. 一个OPML文件：feeds/follow.opml
6. 一个AgentMail收件箱：newsletter@你的inbox.agentmail.to
7. 一些我关注的X账号：karpathy、sama、nearcyan

请你帮我完成：

1. 判断每个源适合用RSS、OPML、公开页面、GitHub feed、AgentMail邮箱，还是需要跳过。
2. 能用RSS/OPML的优先用RSS/OPML。
3. AgentMail只作为私有进阶源，默认不发布完整正文。
4. 不要把需要登录、cookies、token的来源作为默认公共源。
5. 把适合公开内置的源加入项目。
6. 把私人订阅源放进本地OPML、AgentMail或GitHub Secret方案。
7. 本地跑一次数据生成。
8. 如果通过验证，指导我部署到GitHub Pages。

如果你想让用户按表格录入，可以用这个版本：

请使用伯乐Skill，帮我搭建自己的AI日报网站。

你先让我按下面格式填写信息源：

| 名称 | URL或账号 | 类型 | 是否私人 | 我为什么想看它 |
|---|---|---|---|---|
| OpenAI News | https://openai.com/news/ | 网站/RSS | 否 | 官方更新 |
| Karpathy | @karpathy | X账号 | 否 | AI观点 |
| 我的RSS列表 | follow.opml | OPML | 是 | 个人订阅 |
| Newsletter收件箱 | AgentMail inbox | 邮箱 | 是 | 产品周报和newsletter |

填完后，请你帮我判断哪些能直接接入、哪些应该进入OPML、哪些不适合接入、哪些需要Jina兜底、哪些需要以后用私有集成处理。然后生成本地日报数据，并指导我部署到GitHub Pages。

---

伯乐Skill会选什么

伯乐Skill主要会选五类东西。

伯乐Skill的目标不是让你看更多信息。

它的目标是让你少看垃圾信息。

---

支持的信息源类型

---

为什么不用Agent一直跑

AI日报不应该每次都依赖Agent临时执行。

伯乐Skill采用的是更稳定的路径：

信息源 → 抓取 → 去重 → 过滤 → 结构化JSON → GitHub Pages网页

数据更新可以交给GitHub Actions定时运行。

这意味着：

• 不需要买服务器
• 不需要每天手动运行
• 不需要每次消耗Agent额度
• 手机、iPad、电脑都能打开
• fork之后可以变成你自己的日报站

Agent负责帮你判断、配置和维护信息源。真正的日报更新，交给自动化流程。

---

工作原理

伯乐Skill处理信息源时，会做四步。

1. 来源分类

先判断来源属于哪一类：

RSS / Atom
OPML
公开GitHub feed
公开网页
聚合站分页
X桥接源
私有知识库
AgentMail邮箱
需要登录的来源

不同来源走不同策略。能用RSS就不用网页解析。能用公开feed就不重写爬虫。AgentMail只作为私有邮箱情报入口，适合newsletter和产品周报，不作为公共默认源。需要登录和cookies的来源，不放进公共默认配置。

2. 抓取和结构化

把不同来源抓到的数据统一整理成结构化JSON。

这样Agent可以读，网页也可以读。

3. 去重和AI过滤

对重复标题、重复链接、聚合站转载进行去重。

同时区分AI强相关、全量信息和原始覆盖池。宽泛词不会单独决定一条新闻是不是AI新闻。比如agent可能是AI Agent，也可能只是普通代理。

4. 静态部署

最后输出到data/*.json，再通过GitHub Pages展示。

默认数据由GitHub Actions定时更新。

---

源健康和信息密度

伯乐Skill不是只会加源，也会帮你淘汰源。

页面会展示源健康和信息密度，比如：

源是否正常
最近是否更新
每天贡献多少条信息
AI强相关内容占比

一个简单的淘汰标准：

如果一个源连续一周平均每天贡献不到1条有价值信息，就可以考虑移除。

这比无限加源更重要。

因为AI日报的敌人不是信息不够，而是噪音太多。

---

OPML支持

如果你是RSS老玩家，可以直接用OPML批量导入订阅源。

本地方式：

cp feeds/follow.example.opml feeds/follow.opml
# 把你的OPML内容放进 feeds/follow.opml
python scripts/update_news.py --output-dir data --window-hours 24 --rss-opml feeds/follow.opml

注意：

feeds/follow.opml 是你的私人订阅文件，不要提交到公开仓库。

如果要部署到GitHub Actions，建议把OPML转成base64，放进GitHub Secret：

base64 < feeds/follow.opml | pbcopy

然后在仓库Secrets里添加：

FOLLOW_OPML_B64

---

AgentMail邮箱情报入口

如果你希望Newsletter、产品周报、GitHub通知进入日报链路，可以创建一个专门给AI日报使用的AgentMail收件箱。

本地方式：

export EMAIL_DIGEST_ENABLED=1
export AGENTMAIL_API_KEY="你的AgentMail API Key"
export AGENTMAIL_INBOX_ID="你的Inbox ID"
python scripts/update_news.py --output-dir data --window-hours 24

安全默认值：

默认不启用AgentMail。
默认只调用 GET /v0/inboxes/{inbox_id}/messages。
默认不读取 /raw，不读取 text/html 正文。
默认只输出脱敏后的标题、预览片段、发件域名、链接、附件数量和时间。
GitHub Actions默认不会提交 data/email-digest.json；只有设置 EMAIL_DIGEST_PUBLISH=1 才会提交。

建议把AgentMail理解成“AI日报的专用情报收件箱”，不是读取你的私人邮箱。

---

安全边界

伯乐Skill默认不会要求你提供API Key。

公开仓库里也不应该出现：

API Key
cookies
token
.env
真实OPML订阅文件
邮箱正文或私有邮件内容
AgentMail API Key或Inbox ID
浏览器登录态

推荐做法：

• 公共默认源只使用稳定公开来源
• 私人订阅放进OPML
• AgentMail只作为私有进阶源，默认关闭
• OPML不要提交到仓库
• GitHub Actions里用Secret保存私有配置
• 需要登录的网站不要作为默认抓取源

一个AI日报项目，自己用可以粗糙一点。一旦开源，就要替fork用户提前挡坑。

---

适合谁

伯乐Skill适合这些人：

• 每天需要追AI新闻的人
• 有一堆RSS订阅但看不过来的人
• 想把X、博客、聚合站、Newsletter统一到一个页面的人
• 想fork一个自己的AI日报站的人
• 想让Codex或Claude Code长期维护信息源的人
• 想做自媒体选题雷达的人

不适合这些场景：

• 想实时监控所有新闻
• 想抓取需要登录的网站
• 想把私人邮箱、AgentMail API Key和cookies直接塞进公开项目
• 想用它替代完整RSS阅读器

伯乐Skill不是万能信息中台。它更像一个AI信号雷达。

---

仓库结构

ai-news-radar/
├── index.html
├── assets/
│   ├── app.js
│   └── styles.css
├── data/
│   ├── latest-24h.json
│   ├── latest-24h-all.json
│   ├── source-status.json
│   ├── email-digest.json  # 可选，AgentMail开启后生成
│   └── archive.json
├── feeds/
│   ├── follow.example.opml
│   └── social-x.example.opml
├── scripts/
│   └── update_news.py
├── docs/
│   ├── SOURCE_COVERAGE.md
│   ├── GPT_HANDOFF.md
│   └── V2_PRODUCT_BRIEF.md
└── skills/
    └── ai-news-radar/
        ├── SKILL.md
        ├── README.md
        └── references/

---

English

Find the thoroughbred sources before they enter the radar.

Scout Skill is the English-facing name for 伯乐Skill in AI News Radar. It helps you choose high-signal AI sources worth tracking instead of blindly adding every noisy feed.

It classifies and ingests sources from RSS, OPML, public websites, GitHub-generated feeds, newsletters, X-related feeds, and private knowledge bases, then deploys the result as a GitHub Pages site.

It does not try to know everything.

It only helps AI News Radar find sources worth tracking.

Live demo:

https://learnprompt.github.io/ai-news-radar/

Repository:

https://github.com/LearnPrompt/ai-news-radar

Quick prompt after install

Use Scout Skill to help me build my own AI daily radar.

First read README.md, docs/SOURCE_COVERAGE.md, docs/GPT_HANDOFF.md, and skills/ai-news-radar/SKILL.md.

Then ask me for my source list: websites, RSS feeds, OPML files, X accounts, newsletters, GitHub projects, or private knowledge bases.

For each source, classify whether it should be handled as RSS, OPML, public feed, static page, Jina fallback, optional private integration, or skipped.

Prefer stable public sources. Do not commit API keys, cookies, tokens, private OPML files, or email contents.

After classification, generate the local data, verify the JSON output, and guide me through GitHub Pages deployment.

---

背后的故事

伯乐Skill是在一次假期信息焦虑里做出来的。

我一边自驾，一边用语音把需求丢给Codex。想到一个源、一个过滤规则、一个页面问题，就让Agent继续改。

最后它变成了一个很适合AI时代的东西：不是让AI帮我多看一点信息，而是让AI帮我少看一点垃圾信息。

所以它叫伯乐Skill：先选千里马，再上雷达。

它看的不是天下大事。它先看的，是哪些信源值得进入雷达。

---

License

MIT — 随便用，随便改，随便让它帮你选千里马。

---

<div align="center">

RSS阅读器帮你订阅信息。 AI News Radar帮你展示AI信号。 伯乐Skill帮你判断哪些信源是值得长期追踪的千里马。

<br>

从一堆信源里选出千里马。

</div>

Source Intake Reference

Use this when evaluating a new information source for AI News Radar.

V2 Intake Questions

Before implementation, answer these from the URL, repo, or user's message:

• Who benefits: every public visitor, the maintainer, or one private fork?
• What signal does it add that stronger existing sources do not already cover?
• Does it publish stable timestamps and canonical URLs?
• Can GitHub Actions fetch it without login, cookies, or browser automation?
• Does it need secrets? If yes, can it skip cleanly when secrets are missing?
• Will it flood the Signal view with off-topic items?

Only ask the user when the answer changes default vs advanced routing.

Decision Order

1. Prefer official RSS/Atom/JSON feeds. 2. Prefer public GitHub-generated feeds over rebuilding another project's crawler. 3. Use OPML for private or user-specific feeds. 4. Before making a source public-default, run the Source Overlap Check against the recent archive. 5. Use a built-in fetcher only when the source improves the public default. 6. Avoid login, cookies, browser automation, private inboxes, and committed secrets.

Source Classes

GitHub Project Intake

When a user gives a GitHub repo:

1. Read README*, SKILL.md, config/*, and .github/workflows/*. 2. Look for generated outputs: feed*.json, latest*.json, rss.xml, atom.xml, state*.json, or a gh-pages branch. 3. Inspect output schema:

• title/text field
• canonical URL
• timestamp (createdAt, publishedAt, generatedAt, pubDate)
• source/person/feed name
• stable IDs for dedupe

4. Inspect workflow secrets and dependencies:

• If the repo uses API keys centrally but publishes public feed files, consume

the feed files.

• If every user must provide keys, treat it as an optional advanced source.

5. Test raw URLs from GitHub Actions-friendly locations:

• https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<file>
• public GitHub Pages URL if provided

6. Add a fetcher only after a source-only probe succeeds locally.

Treat public generated feed files as the durable path. If the repo has a stable GitHub Action that commits feed*.json using its own API credentials, consume those public outputs. Do not clone its token flow into this repo unless the user explicitly asks for a self-hosted variant.

X/Twitter Rules

Do not depend on public RSSHub/XCancel/Nitter routes as a default source unless the user explicitly accepts instability. They can work briefly and then time out.

Stable patterns:

• Read a curated central feed that already uses official X API, like

Follow Builders.

• Add a self-hosted optional X adapter using X_BEARER_TOKEN; skip cleanly when

the token is missing.

For optional X API adapters:

• Store tokens only in GitHub Secrets or environment variables.
• Never print or commit tokens.
• Exclude retweets/replies by default.
• Cap per-account items.
• Record rate-limit or permission failures in source-status.json.
• Skip cleanly when X_BEARER_TOKEN is missing; the public site must still run.

Newsletter Rules

Prefer public archive feeds:

• Substack RSS when available.
• Beehiiv/public archive pages when RSS is blocked.
• Jina Reader only when direct fetch is blocked and the archive is public.

Avoid private inbox ingestion as a default feature. Email requires OAuth, IMAP, App Passwords, forwarding, or third-party bridges and raises privacy concerns. If email support is requested, document it as an advanced private bridge and keep the public default independent from mailbox access.

Built-In Fetcher Pattern

Add focused code to scripts/update_news.py:

def fetch_example(session: requests.Session, now: datetime) -> list[RawItem]:
    resp = session.get("https://example.com/feed.json", timeout=20)
    resp.raise_for_status()
    data = resp.json()
    out: list[RawItem] = []
    for item in data.get("items", []):
        published = parse_date_any(item.get("publishedAt"), now)
        if not published:
            continue
        out.append(
            RawItem(
                site_id="example",
                site_name="Example",
                source=item.get("source") or "Example",
                title=maybe_fix_mojibake(item["title"]),
                url=item["url"],
                published_at=published,
                meta={},
            )
        )
    if not out:
        raise ValueError("No Example items parsed")
    return out

Then register it in collect_all, update docs, and add tests for parser behavior.

Source Overlap Check

Before promoting a candidate RSS/Atom source into the public default layer, run a recent-overlap report:

python scripts/evaluate_source_overlap.py \
  --source-url https://example.com/feed.xml \
  --source-name "Example Source" \
  --site-id example_candidate \
  --baseline data/archive.json \
  --lookback-days 7 \
  --output reports/source-intake/example-overlap.json

Interpretation:

• < 35% hard duplicate rate: usually accept_default.
• 35%–65%: keep as watchlist or OPML advanced source first.
• >= 65%: usually skip_duplicate unless the source is faster, more canonical, or has unusually valuable unique items.
• < 5 recent candidate items: treat as too small and keep on watchlist.

The report is advisory. Do not auto-delete existing sources or auto-promote a candidate solely from the score. Story-level merge / clustering is planned for a later version, not part of v0.3.0.

Validation Checklist

Run:

python -m py_compile scripts/update_news.py
pytest -q
python scripts/update_news.py --output-dir /tmp/ai-news-radar-data --window-hours 24 --archive-days 21

Inspect /tmp/ai-news-radar-data/source-status.json:

• source appears with ok: true
• failed_sites is empty or the failure is expected and documented
• item count is plausible
• AI-focused view is not flooded with off-topic items

V2 Method

Use this reference when AI News Radar work is about product direction, source coverage, or packaging the repo as a reusable Skill.

Method Inputs

• Office Hours style: understand demand, status quo, narrowest wedge, and

alternatives before committing to a product direction.

• Superpowers style: turn the chosen direction into a small spec, exact file

plan, tests, review, and verification before calling the work complete.

Product Diagnostic

Run this before expanding features:

1. User: ordinary AI enthusiast, maintainer, or agent using the Skill? 2. Current workaround: noisy timelines, manual site checks, RSS reader, email, or another aggregator? 3. Demand evidence: is the user asking for breadth, speed, trust, or fewer choices? 4. Narrowest useful default: what can ship without asking a new user to configure keys, inboxes, cookies, or many toggles? 5. Advanced escape hatch: what belongs in OPML, GitHub Secrets, or a local adapter instead of the public default? 6. Success signal: what should improve in source-status.json, the Signal view, or the maintainer workflow?

Ask the user only when a missing answer changes the implementation choice. For mobile users, prefer one short multiple-choice question.

Approach Selection

For unclear product choices, compare 2-3 approaches:

• Minimal viable: smallest diff, safest public default, fastest validation.
• Durable architecture: cleaner long-term extension point, better tests or

docs, more future-proof source coverage.

• Packaged variant: makes the project easier for Codex/Claude users to fork,

customize, and deploy as their own AI news radar.

Recommend one approach and state what evidence would make the recommendation wrong.

Source Coverage Ladder

Use the highest stable rung available:

1. Official RSS/Atom/JSON from the source owner. 2. Public GitHub-generated feed files produced by a maintained repo. 3. Public newsletter archive or archive RSS. 4. Public static page with stable timestamps and selectors. 5. OPML for personal or niche feeds. 6. Optional API adapter with user-owned secrets. 7. Private inbox, cookies, browser sessions, or unstable bridges.

Rungs 1-4 can become public defaults if they are useful to most visitors. Rungs 5-7 belong in advanced documentation unless the user explicitly wants a private fork.

GitHub Feed Intake

When given a GitHub repo that collects news:

1. Read README*, .github/workflows/*, config/*, and generated feed files. 2. Identify whether the repo already uses official APIs or cron jobs centrally. 3. Prefer consuming its public raw output instead of copying its crawler. 4. Verify schema fields: title/text, canonical URL, source/person, timestamp, stable ID, and generation cadence. 5. Add tests around parser behavior before relying on it as a built-in source.

This is the preferred pattern for X-heavy projects such as curated builder feeds: the public repo owns API credentials, this project consumes only public JSON.

Engineering Loop

Keep implementation disciplined:

1. Map files before editing. 2. For behavior changes, add focused parser/filter tests. 3. Implement the smallest code path that passes the test. 4. Run python -m py_compile scripts/update_news.py and pytest -q. 5. For Skill changes, run the Skill validator. 6. For source changes, run a local generation into /tmp and inspect source-status.json. 7. After push, watch GitHub Actions and Pages deployment when relevant.

Do not claim a source is covered until a fetcher, OPML path, public generated feed path, or optional-secret path is documented and validated.

V2 Definition Of Done

A v2 change is complete when:

• The default page remains simple for ordinary users.
• The first viewport shows source health and coverage as status signals, not a

pile of configuration controls.

• Source coverage is documented as public default vs advanced/private.
• New built-in sources have stable timestamps and do not require secrets.
• Failures are visible in source-status.json instead of silently disappearing.
• The Skill tells future agents how to add, reject, or route similar sources.