feat: 提供 HTTP API，支持第三方系统获取每日日报

[okatu-loli]

Is your feature request related to a problem? Please describe.

是的。我希望将 Horizon 集成到第三方系统中，由第三方系统主动调用 API 获取每日生成的日报内容。

目前 Horizon 已经支持 GitHub Pages、Webhook、Email、MCP 等输出和集成方式。但是对于一些已有的内部系统、企业后台或门户系统来说，它们可能不是 MCP Client，也不适合通过 Webhook 被动接收推送。

在这种情况下，目前似乎还没有一个比较直接的 HTTP API，可以让第三方系统按需获取日报内容。

这会导致以下集成场景不够方便：

• 按日期主动拉取日报
• 获取最新一次生成的日报
• 将日报同步到内部系统、知识库或门户
• 对日报内容进行归档、检索、展示或二次分发
• 在同步失败后按日期重试补拉

Describe the solution you'd like

希望 Horizon 能提供一个标准的 HTTP API，允许第三方系统获取已生成的日报。

例如：

GET /api/daily-report?date=2026-05-24&lang=zh

返回示例：

{
  "date": "2026-05-24",
  "language": "zh",
  "format": "markdown",
  "content": "# Daily Report..."
}

也希望支持获取最新生成的日报：

GET /api/daily-report/latest?lang=zh

返回示例：

{
  "run_id": "xxx",
  "date": "2026-05-24",
  "language": "zh",
  "format": "markdown",
  "content": "# Daily Report..."
}

可以考虑的实现方式：

• 增加一个轻量级 HTTP API 服务
• 直接读取 data/summaries/ 下已生成的日报文件
• 或复用现有 MCP 能力，例如 hz_list_runs 和 hz_get_run_summary
• 支持 Docker 部署时暴露 API 端口
• 可选支持 token-based authentication，避免接口被公开访问
• 支持按日期获取历史日报，以及获取 latest report

Describe alternatives you've considered

我考虑过以下替代方案：

1. Webhook

   Horizon 可以通过 Webhook 将日报推送到第三方系统。
   但在我的场景中，第三方系统更倾向于主动拉取，而不是被动接收推送。

   主动拉取更方便控制同步时机、失败重试，以及按日期补拉历史日报。

2. GitHub Pages / 静态文件

   GitHub Pages 或静态文件可以用于公开或半公开地访问日报。
   但对于私有部署、需要鉴权、或需要结构化返回结果的系统来说，标准 HTTP API 会更合适。

3. MCP

   MCP 对 AI Agent 集成很有用。
   但并不是所有第三方系统都是 MCP Client。对于普通后端服务、内部管理后台或企业门户来说，HTTP API 会更容易集成，也更通用。

Additional context

主要使用场景是：

• Horizon 每天生成新闻日报
• 第三方系统通过 API 主动获取 latest report 或指定日期的 report
• 第三方系统将日报内容进行存储、展示、索引、归档或内部分发

希望能增加这个能力，或者在文档中补充说明：如果第三方系统需要主动获取日报，推荐的集成方式是什么。

如果这个功能符合项目方向，并且维护者认为可行的话，我也可以尝试贡献一个 PR。

[Thysrael]

我有个问题没有弄清楚，就是如果我们加了一个 WEB API，让大家可以调用这个 API 获得新闻，那么这个新闻的新闻源是什么？

如果开发者搭建了一个服务器来提供这种 API，那么新闻源就是开发者的新闻源了，那这个功能是不是可以直接被目前 Demo （也就是开发者的新闻源）中的 RSS 解决，用户只要订阅这个 RSS 就好了。顶多是查询历史 summary 有些麻烦，毕竟 RSS 只提供一个近期窗口的新闻。

如果是每个用户用自己的新闻源，都可以构建一个自己的 WEB API，那么具体该怎么实现呢？不能要求用户都有一个站点来部署这种 API。Horizon 目前是一个运行一次就结束的 cli 程序，是否要改造它成为一个持续运行的 Server？

[okatu-loli]

感谢回复，我理解你的顾虑。

我刚看了一下现有 RSS 的实现，理解下来它其实也是基于 GitHub Pages / Jekyll 的静态产物：Horizon 运行后把 summary 写到 docs/_posts/，然后 Pages 构建出 feed.xml、feed-zh.xml、feed-en.xml。

所以我觉得这个需求不一定要一开始就做成常驻 Web Server，也不是希望 Horizon 官方或 Demo 提供一个统一的公共新闻 API。新闻源还是每个用户自己的配置，暴露的也只是用户自己运行 Horizon 后生成的 summary。

我觉得可以分层提供：

1. 一次性运行时生成 JSON

Horizon 继续保持现在 CLI 的使用方式：运行一次，生成一次，然后退出。

只是在生成 summary 的同时，额外输出一份稳定的、机器可读的 JSON 文件，比如：

data/api/latest.json
data/api/summaries/2026-05-24.zh.json
data/api/summaries/2026-05-24.en.json

这样不想部署服务的用户，也可以直接拿这些 JSON 文件给第三方系统用，或者通过 GitHub Pages、Nginx、对象存储、内网文件服务等方式暴露出去。

这和现在 RSS 的思路其实是类似的：RSS 适合人订阅和阅读近期 summary，JSON 更适合第三方系统同步、按日期读取、归档和检索。

2. 可选的 Web API 服务

对有能力部署服务的开发者，可以额外提供一个可选的 horizon serve 模式。

这个服务可以分成两类接口：

• 读取接口：读取本地已经生成好的 summary / JSON 文件
• 触发接口：触发一次新的抓取和 summary 生成流程

比如读取接口：

GET /api/summary/latest?lang=zh
GET /api/summary?date=2026-05-24&lang=zh

再比如触发接口：

POST /api/runs

它可以触发一次新的 pipeline，使用当前用户自己的配置去抓取新闻源、生成 summary，并返回一个 run id：

{
  "run_id": "xxx",
  "status": "queued"
}

然后第三方系统可以继续查询运行状态或结果：

GET /api/runs/{run_id}
GET /api/runs/{run_id}/summary?lang=zh

这样需要 HTTP API 的用户可以自己部署，不需要 Horizon 官方或 Demo 提供统一的公共新闻 API。API 使用的新闻源仍然是用户自己部署时配置的 sources。

当然这个触发能力可以是可选的，甚至可以先只支持读取本地 JSON，后续再支持通过 API 触发 pipeline。这样实现上会更稳妥一些。

所以我的想法是可以同时支持：

• 默认 CLI 模式：一次性生成 summary，同时输出 JSON
• 可选 Server 模式：给有部署能力的用户提供 HTTP API
• 可选触发接口：允许第三方系统通过 API 触发一次新的抓取和生成流程

这样既不会破坏 Horizon 现在轻量的 CLI 形态，也能在现有 RSS/Pages 发布能力之外，增加一个更适合机器集成的输出格式。

[Thysrael]

那我有点不理解为什么要要用 JSON 而不是原本的 markdown 呢？这不会引入一致性的隐患吗？

另外你能再解释一下为什么会有私有部署和结构化的问题吗？我理解其实写一个独立于 Horizon 的 Server 就可以解决这个问题了。Server 不仅提供了 HTTP API ，还解决了私有部署和结构化的问题？

[okatu-loli]

感谢回复。

抱歉，我之前的表达不够准确，我的意思不是用 JSON 替代 Markdown，也不是让 Horizon 同时维护两份正文。现在 Markdown 作为 summary 正文已经挺清楚了，JSON 更像是一个索引文件，而不是另一份 summary 内容。

比如可以是：

{
  "date": "2026-05-24",
  "lang": "zh",
  "title": "Horizon Summary: 2026-05-24 (ZH)",
  "summary_path": "data/summaries/2026-05-24-summary-zh.md",
  "post_path": "docs/_posts/2026-05-24-summary-zh.md",
  "public_url": "/2026/05/24/summary-zh.html",
  "created_at": "2026-05-24T10:00:00Z"
}

这样正文还是 Markdown，不会有 Markdown 和 JSON 内容不一致的问题。JSON 只是告诉外部系统：最新 summary 是哪篇、有哪些语言、对应文件在哪里、公开 URL 是什么。

关于独立 Server，我同意完全可以写一个独立于 Horizon 的 Server。我的想法不是说 Horizon 必须内置完整 Server，而是如果完全让每个 Server 自己去适配 Horizon 的输出，它们就都要自己处理这些约定：

• summary 文件在哪个目录
• 文件名怎么拼
• zh/en 怎么区分
• latest 应该指向哪篇
• 历史 summary 怎么枚举
• GitHub Pages 的 URL 怎么对应到本地 post

这些信息现在其实已经分散在生成逻辑和 Jekyll/RSS 逻辑里了。比如 docs/_posts/{date}-summary-{lang}.md 是在 orchestrator 里拼出来的，RSS 又是通过 site.posts 和 lang 过滤出来的。

所以我想要的不是“再造一份内容”，而是 Horizon 在生成 Markdown 时，顺手把这些已经知道的信息写成一个稳定的 index/manifest。

比如：

data/api/index.json
data/api/latest.zh.json
data/api/latest.en.json
data/api/summaries/2026-05-24.zh.json
data/api/summaries/2026-05-24.en.json

外部 Server 当然还是可以自己写，但它可以直接读这些 manifest，而不是自己猜 Horizon 的目录和文件名。

至于 Web API，我觉得可以分两步看：

1. Horizon 默认还是 CLI：运行一次，生成 Markdown，同时生成 manifest JSON；
2. 有需要的人可以自己写 Server，或者以后再加一个可选的 horizon serve，只负责读取这些已经生成好的 Markdown/manifest 并提供 HTTP API。

如果以后做 horizon serve，它也可以顺便提供一个触发接口，例如：

POST /api/runs
GET /api/runs/{run_id}
GET /api/runs/{run_id}/summary?lang=zh

但这个不是我觉得第一步必须做的。第一步只要有稳定的 manifest，第三方系统集成就会简单很多。

所以总结一下，我现在的想法是：

• Markdown 仍然是 summary 正文；
• JSON 不存另一份正文，只做 index/manifest；
• 独立 Server 仍然可以由用户自己实现；
• Horizon 只需要提供一个稳定的机器可读出口，避免每个集成都去解析内部目录和文件名；
• 后续如果项目觉得合适，再考虑可选的 Web API / horizon serve。

[Thysrael]

嗷嗷，感谢您耐心的解释。可能上次是因为你提到了 data/api/summaries/2026-05-24.zh.json 这个文件，才让我觉得是需要维护 markdown 和 json 两种格式的文件，而并非你的表达不清楚。

即使 JSON 作为索引文件，我也不太理解是否有这个必要，因为目前 markdown 的文件路径和文件名，还有 public 部分都是硬编码的，所以并不会存在不同的两份。而且 summary 的搜索并不是一个传统的大工程，似乎没啥必要建立索引。

就算有必要建立索引，那完全可以交给写 Server 的人，而不是 Horizon 内部。

我觉得可能我对于这个问题认识不太深刻，是因为我没有搞懂您说的到底是什么具体的私有场景，导致必须要有这样一个深入 horizon 内部的改动呢？您可以给我一个例子吗？

[Thysrael]

我倒不是排斥 HTTP Server 这种 design，实际上 Horizon 已经集成了一个 MCP Server 了，只是我担心引入如此大的一个变动，会产生类似于咱们刚才讨论的“JSON”这样的会导致污染 Horizon CLI 的问题（而且实际上，我觉得你给出的解决方案，已经很有这个趋势了）。

我担心是我有什么地方没有考虑到，请你谅解。