30 分钟跑通第一份双语简报:只做必要动作的最小路径
30 分钟跑通第一份双语简报:只做必要动作的最小路径
Horizon 的配置项很多:十类信息源、四种 Profile、四种分发渠道、两套并发参数。第一次上手的人最常见的结局是:花一小时把配置填得很满,运行后发现输出的是一份空简报,或者干脆一行内容都没抓取到。这类失败与你的信息源不够多、模型不够强无关,真正的原因往往是在还没验证主链路之前,就先叠加了太多变量。
这篇文章只做一件事:把第一份中英双语 Markdown 简报跑出来的最短路径拆解开,每一步都对应仓库里的真实代码行为,并明确告诉你哪些动作可以省略、哪些必须做、以及怎样才算真正跑通。
先定义"跑通":以产出物为准,而不是以配置完成为准
一次完整的 run 结束后,Horizon 会为 ai.languages 中的每种语言各写一份文件:
data/summaries/horizon-<YYYY-MM-DD>-zh.md
data/summaries/horizon-<YYYY-MM-DD>-en.md
写入由 src/storage/manager.py 的 save_daily_summary 负责,文件名格式固定为 horizon-{date}-{language}.md。因此"跑通"的判定标准只有三行:
- 两个文件都存在;
- 文件里有真实条目(不是那句"今日暂无重要动态");
- 中文文件的标题是中文,英文文件的标题是英文。
第三条尤其容易被忽略。Horizon 的双语能力来自富化阶段按语言生成内容块,而不是事后机器翻译:中文标题、正文区块都取自 item.processing.artifacts<a href="https://link.gitcode.com/i/6ceb78b5033bab5acefd4373b34a7fd8" target="_blank">"zh"](见 [src/ai/summarizer.py 中 _format_item 对 artifact 的取值)。如果 languages 没配对,你只会拿到一份英文简报,而流程依然显示 Horizon completed successfully!。
0–8 分钟:环境与模型接入,先跑通再谈调优
只需要 Python 3.11+ 和 uv
pyproject.toml 声明 requires-python = ">=3.11",入口脚本是 horizon = "src.main:main"。依赖里已经包含 trafilatura,基础安装不需要额外 extras:
git clone https://github.com/Thysrael/Horizon.git
cd Horizon
uv sync
不要在这一步顺手装 --extra openbb 或 --extra twitter。OpenBB 会拉入大量二进制依赖,Twitter 的 Playwright 模式还需要浏览器和系统库;它们与"第一份简报"毫无关系,只会把 8 分钟变成一小时。
密钥只写一行,且变量名不能写成密钥值
新建 .env,第一遍只填一个 key。.env.example 里列了十来个变量,但只有当前 ai.provider 对应的那一个是必需的:
OPENAI_API_KEY=sk-your-key
这里有个高频错误值得提前避开:api_key_env 里要填环境变量名,而不是密钥本身。填错的报错信息非常明确,写在 src/ai/client.py 的 _missing_api_key_message 里:
Missing API key: ai.api_key_env must be an environment variable name,
not the API key value. Set OPENAI_API_KEY=your_api_key in .env or your shell,
then set ai.api_key_env to "OPENAI_API_KEY" in data/config.json.
如果暂时没有云端 key,可以直接用 Ollama 走完全程:它的默认配置里 api_key_env 是空字符串,默认 base_url 为 http://localhost:11434/v1,src/models.py 的 AI_PROVIDER_DEFAULTS 中已给出。
ai 块只留四个关键字段
{
"ai": {
"provider": "openai",
"model": "gpt-4o-mini",
"api_key_env": "OPENAI_API_KEY",
"languages": ["zh", "en"],
"max_tokens": 8192,
"temperature": 0.3,
"analysis_concurrency": 2,
"enrichment_concurrency": 2
}
}
四个字段各有明确理由:
languages必须显式写。AIConfig.languages的默认值是<a href="https://link.gitcode.com/i/40e15e81906fce9a52143b6c0511833f" target="_blank">"en"],只有配置向导horizon-wizard才会默认问你zh,en(见 [src/setup/wizard.py 的configure_ai)。手写配置而漏掉这一项,是"双语变单语"的唯一原因。字段校验只接受形如zh、en、zh-CN的语言标签,带路径符号的写法会直接报invalid language code。max_tokens不要留在 4096。data/config.example.json 里是4096,而向导用的是8192。富化阶段要求模型一次性输出一个包含多个区块的 JSON(tech-news需要summary、background、可选impact、可选community_discussion,见 profiles/tech-news/profile.json)。token 上限被截断时,JSON 解析失败,该条目会因为校验不通过而被计入失败列表,最终表现就是"跑完了但少了好几条"。- 并发先给 2。
analysis_concurrency与enrichment_concurrency默认都是1(src/models.py 中AIConfig的字段默认值),也就是严格串行。第一遍跑通时给到 2 能明显压缩等待时间;如果是免费额度或限流严格的端点,就把它留在 1,并把ai.throttle_sec设成4.5之类的值,docs/configuration.md 里给的经验是"免费层约 15 RPM 时用 4.5 秒"。 provider_chain此时别碰。多提供商容灾(src/ai/client.py 的ChainedAIClient)是很实用的能力,但它会在第二个 provider 上再引入一套模型名、base_url 和 key 的组合问题。第一份简报只需要一条确定的路径。
8–15 分钟:信源只留三个,多一个都是负担
先关掉默认开着但你并不需要的东西
打开 data/config.example.json 会发现,hackernews、reddit、telegram 都是 enabled: true,Reddit 还带了一个 subreddit 和一个用户,Telegram 带了一个频道。更隐蔽的是模型层的默认值:RedditConfig.enabled 与 TelegramConfig.enabled 本身就是 True,所以即使你在配置里整段省略,它们也会被实例化成启用状态(只是列表为空、抓到 0 条)。
这不是致命问题,但会让第一次运行的日志里塞进一堆"Found 0 items from Reddit",让你误以为哪里配错了。最小路径的做法是显式关闭:
{
"sources": {
"hackernews": { "enabled": true, "fetch_top_stories": 20, "min_score": 100, "profile": "tech-news" },
"reddit": { "enabled": false },
"telegram": { "enabled": false },
"rss": [
{
"name": "Simon Willison",
"url": "https://simonwillison.net/atom/everything/",
"enabled": true,
"category": "ai-tools",
"profile": "tech-news"
}
],
"github": [
{ "type": "repo_releases", "owner": "astral-sh", "repo": "uv", "enabled": true, "profile": "tech-news" }
]
}
}
三个源的类型刻意不同:Hacker News 是热度排序的聚合入口,RSS 是单点深度的稳定输出,GitHub Release 是事件型的确定产出。这样的组合能在任何一天都保证"有内容可筛",而不会出现三个源同时安静导致空简报。
显式写 profile,省掉一次 AI 调用
profile 字段的三种取值在行为上差别很大(docs/configuration.md 的 Information Sources 一节有定义):
| 取值 | 行为 |
|---|---|
"tech-news" |
直接使用该 Profile,不做 AI 匹配调用 |
"auto" 或不写 |
让 AI 在全部已加载 Profile 中挑一个 |
["tech-news", "finance-news"] |
只在候选列表里挑一个 |
最小路径应当一律显式指定。省下的是每条内容一次分类调用,在 30 个条目量级上就是 30 次可以完全避免的请求。
阈值先放宽,别让第一次运行就撞墙
{
"processing": {
"profiles_dir": "profiles",
"default_profile": "tech-news",
"profile_settings": {
"tech-news": { "threshold": 6.5, "topic_dedup": true }
}
},
"collection": { "time_window_hours": 6 },
"digest": { "profile_order": ["tech-news"] }
}
tech-news 的评分规则里 7–8 分是"重要进展、技术深挖、新颖方法",7.0 是个合理的长期阈值,但它对 6 小时的窗口偏严。第一次跑用 6.5,等看到输出质量后再上调到 7.0 或 8.0,这比在空简报里猜原因要高效得多。阈值允许 0–10,也可以写 null 完全关闭分数过滤(此时仍会分析、仍会打分,只是不按分数剔除)。
profiles_dir 的相对路径相对于工作目录解析,因此在仓库根目录运行即可,不必改成绝对路径。
配置错误会在抓取之前暴露
把上面几段合并成 data/config.json 之后,直接运行。Horizon 的 Config 模型是 extra="forbid" 的,多写一个不认识的字