30 分钟跑通第一份双语简报:只做必要动作的最小路径

原创2026-11-05 18:15:591,978 阅读
文章标签:人工智能AI 应用大模型AI 技能MCP 服务网页爬虫CLI

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。因此"跑通"的判定标准只有三行:

  1. 两个文件都存在;
  2. 文件里有真实条目(不是那句"今日暂无重要动态");
  3. 中文文件的标题是中文,英文文件的标题是英文。

第三条尤其容易被忽略。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" 的,多写一个不认识的字

登录后查看全文
Horizon