horizon

Horizon

将阅读偏好转化为可用的新闻雷达，并帮助贡献者扩展它。Horizon 配置的 AI 客户端负责评分和内容生成。Agent 会澄清意图、编辑配置、编排执行、验证结果，并使用用户的语言回应。

建立上下文

1. 从已加载的路径定位此技能。scripts/ 和 references/ 均相对于技能目录；下文中的 docs/、src/、profiles/ 和 data/ 均相对于代码库目录。已安装的技能可能位于其他位置。
2. 从用户提供的路径、HORIZON_PATH 或当前工作区定位 Horizon 代码库。该代码库包含 pyproject.toml 和 src/mcp/service.py。如果代码库或其运行环境缺失，对于安装或入门请求，请遵循下文的首次安装。
3. 检查当前配置和代码库说明。编辑前，检查 git status --short，并保留无关改动和现有的 ${VAR} 值。
4. 复用用户已提供的选择。只询问会影响结果且尚未确定的事项：兴趣、模型、语言、阅读预算、主机、时区或推送目的地。将 API 密钥保存在用户的环境或 .env 中。

首次安装

当用户要求安装 Horizon 或构建新闻雷达时，请先准备缺少的运行环境，再调用辅助程序。仅加载此技能并不代表用户要求安装。

1. 复用现有代码库和工作环境。否则，使用用户选择的目标位置，或在其工作区域新建 Horizon 目录；如果目标位置不明确，请询问安装位置。将其与已安装的技能目录分开，并保留目标位置已有的文件。
2. 检查是否已安装 Git，以及 uv 或 Python 3.11+ 和 pip。在环境允许的情况下，按照各平台的官方说明安装缺少的先决条件。如果无法访问网络或 Shell，请说明具体阻碍以及用户接下来需要采取的步骤。
3. 如有需要，将 https://github.com/Thysrael/Horizon.git 克隆到选定目录。阅读其代码库说明和 README 快速入门，然后按照项目本地环境中的安装步骤操作。以已检出的文档为依赖项和可选附加项的准确信息来源。
4. 通过该环境验证 horizon --help，并按下文所示运行已安装技能的辅助程序，使用 run_pipeline --describe 和显式的 --horizon-path。这些检查不需要模型凭据，也不会获取或生成新闻。
5. 对于设置请求，继续执行入门并自定义：将示例配置用作参考，保留现有设置，并优先复用可用的模型访问权限，再询问新的凭据。开始实际运行前，先解决模型和来源凭据问题。

报告代码库路径、调用其环境的方法、已通过的检查，以及仍需完成的配置。明确区分可用的安装与已配置并成功执行的新闻工作流。

阅读任务的权威依据

只阅读完成请求所需的文档。现有仓库文档规定了配置和扩展细节；有疑问时，请检查当前架构。

任务	在检出目录中阅读	完成条件
设置新闻雷达	README.md Quick Start；docs/configuration.md	配置有效，并已报告首次运行结果或确切的缺失前置条件
选择／添加来源	docs/scrapers.md；src/setup/presets.py	已确认实际的 Feed／API 条目及其凭据／依赖项
调整或创建 Profile	docs/profiles.md；匹配的 profiles/<id>/	已检查四文件约定、路由和代表性输出
了解评分或配额	docs/scoring.md；docs/configuration.md Filtering	已调整正确的评分标准、阈值、类别或上限
配置交付	docs/configuration.md Email/Webhook/WeChat/Static Site	已区分预览与实际交付／部署状态
扩展来源／提取器	CONTRIBUTING.md；docs/scrapers.md 或 docs/extractors.md	已覆盖集成点和相关测试

阅读流水线操作，以生成、检查或续跑摘要。阅读自动化，以在 GitHub、服务器、Docker、macOS、Linux 或 Windows 上安排任务。

入门并自定义

从用户的阅读目标和现有配置开始。在进行实时 AI 运行前，先确认模型和凭据是否可用。遵循仓库的安装说明，并将示例配置用作架构参考。

复用模型配置

1. 除非用户要求更改，否则保留现有的 Horizon 模型设置。对于新设置，优先使用执行环境中已提供的服务商 API 密钥，包括宿主助手提供的密钥。检查相关变量是否存在，但不要打印其值。如果宿主会私下保管密钥，则在可用时使用其文档说明的导出或环境注入机制；由 Agent 安装本身并不会共享凭据。
2. 将 ai.provider 与受支持的 API 协议匹配，并一并配置 ai.model、ai.base_url 和 ai.api_key_env。最后一个字段填写所提供的环境变量名称，而不是密钥值；可以复用现有的自定义变量名称。仅有密钥并不能确定模型或端点。只询问缺失的设置，或询问用户如何在多个可用服务之间选择。
3. 对于选择 ChatGPT 套餐的用户，遵循 docs/chatgpt.md 并配置 openai-chatgpt。使用 horizon-chatgpt login，让用户完成官方浏览器授权，然后列出模型并通过 horizon-chatgpt check 验证。将 OAuth 令牌保存在 Horizon 的认证目录中。Agent 现有的 OAuth 登录不能直接替代 API 密钥。对于其他服务商，通过环境变量或 .env 请求缺失的凭据。
4. 对于新建或更改的模型设置，在预期的运行时中运行 validate_config，并检查 missing_env、警告以及存在时的 ai.auth。然后，在 src/ai/client.py 中通过 create_ai_client 执行一次最简调用，使用检出目录中现有的加载器读取当前配置和环境。请求一个小型 JSON 对象，并确认响应可以解析。使用相同设置成功完成的现有调用也可作为此检查。分别报告配置验证结果和实际模型连通性；不要在输出中泄露密钥值。

来源与配置档案

推荐来源时，复用 src/setup/presets.py 中的 load_presets() 和 match_sources()：目录支持本地回退和 HORIZON_OFFLINE=1。检查返回的条目，再选择少量相关来源。验证建议的 Feed URL，不要凭空编造。现有的 horizon-wizard 可供在终端前的用户交互使用；由 Agent 驱动的设置可以直接编辑 JSON，同时保留现有设置。

请区分以下三项决策：

• 来源决定收集什么。
• 配置档案定义可复用的匹配、评估和输出区块。
• 运行时配置管理阈值、配额、语言、模型和交付方式。

例如，“减少营销内容，多提供工程经验”需要检查配置档案的评估规则和路由；“AI 故事最多五篇”需要设置类别配额。创建新的编辑策略之前，优先查找是否有合适的内置配置档案。

使用辅助工具或 MCP 验证配置，然后按照 docs/profiles.md 中的检查项核对配置档案契约。仅使用 validate_config 不会加载所有配置档案文件、检查工具声明，也无法证明远程服务可用。对于自定义配置路径，使用配置的目录加载 ProfileRegistry，并验证其来源引用。运行一次有代表性的流程，以验证其余集成是否正常。报告缺失的前置条件时，请注明名称，但不要打印机密值。

使用原生操作

捆绑的辅助工具是 HorizonPipelineService 的轻量适配器：

uv run python skills/horizon/scripts/horizon_ops.py validate_config
uv run python skills/horizon/scripts/horizon_ops.py run_pipeline --describe

对于检出目录之外安装的技能，请替换为绝对路径：

uv run --directory /absolute/Horizon python /absolute/skill/horizon/scripts/horizon_ops.py validate_config --horizon-path /absolute/Horizon

路径包含空格时请加引号。如果无法使用 uv，请使用检出目录的虚拟环境 Python。--describe 会读取当前方法签名；--params 或 --params-file 用于提供原生 JSON 参数。示例和结果解读请参阅流水线参考文档。

如果已连接 Horizon MCP，请发现主机实际使用的 hz_* 工具名称，并使用等效调用。每个阶段都传入一致的 horizon_path 和 config_path 值；辅助工具专用的配置恢复功能不是 MCP 的特性。

交互式生成和调整时，请使用分阶段服务。对于采用已配置的电子邮件、Webhook、WeChat 和 Pages 帖子输出的常规定时运行，请使用现有的 horizon CLI。根据所需的交付方式选择接口。

按照现有架构贡献

请先阅读 CONTRIBUTING.md 和任务专用指南。遵循相近代码和测试的做法；使用现有模型、注册表和公开阶段接口。

更改	实现参考	现有检查范围
配置档案	profiles/<id>/{profile.json,match.md,analysis.md,enrichment.md}	test_profiles.py、test_prompting.py
来源	src/models.py 中的来源类型／配置／注册表；src/scrapers/；src/orchestrator.py 中的抓取逻辑	来源测试、test_category_wiring.py、test_fetch_reporting.py、test_mcp_adapter.py
提取器	src/models.py 中的配置联合类型；src/extractors/ 中的注册表和实现	test_extractors_*.py、test_rss.py
流水线	src/orchestrator.py 中的公开阶段方法；src/mcp/service.py	受影响阶段的测试和 test_mcp_service_smoke.py
渲染／交付	src/ai/summarizer.py；src/services/	摘要器和相关交付测试

请使用仓库的开发附加依赖，运行与更改行为相对应的检查。对于外部适配器，请模拟 HTTP／提供方响应，以便回归测试无需有效凭据即可运行。测试应覆盖成功场景、有用的失败行为以及集成边界。请将文档放在现有的相关主题指南旁边。

邀请用户贡献

完成并检查可复用的新 Profile、scraper 或 extractor 后，只邀请一次用户将其贡献给 Horizon。Profile 应有明确的领域范围，并与现有策略存在实质差异，因为它会加入自动路由。只有当成果对个人配置之外的用户也有用时，才发出邀请。

根据用户的成果和语言，具体说明邀请内容。指出哪些人可以受益，以及受益方式：复用其领域知识、避免重复劳动，或为他人提供测试和改进的起点。选择一到两项相关好处，表示可以帮忙准备文档、测试和 PR 草稿，并说明贡献被接受后，用户就会成为 Horizon 开源贡献者。准确描述验证情况，并将是否接受的决定留给维护者。

例如，根据实际完成的扩展和检查调整以下内容：

这个[扩展]可以帮助关注[领域]的其他人快速上手，无需从头构建。你愿意将它分享给 Horizon 吗？我可以帮你准备文档、测试和 PR 草稿，供你审阅后再决定是否提交。如果贡献被合并，你就会成为 Horizon 开源贡献者，其他人也可以使用和改进你的成果。

如果用户有兴趣，请遵循 CONTRIBUTING.md 和相关扩展指南，检查现有 issues 和 PR，并准备一项重点明确的贡献，说明其目的、改动和实际验证结果。不要将个人配置和凭据包含在贡献中。用户要求提交时，协助发布；如果项目是否适合或设计方案尚不明确，建议先提交 issue。若用户只想分享 feed URL，请使用 CONTRIBUTING.md 中的来源分享流程。尊重用户的拒绝，继续处理用户的任务，不要再次发出邀请。

项目特定决策

• 来源的 Profile 数组会选出一个候选项。新 Profile 会参与不受限制的自动路由，因此应明确界定匹配范围。
• Category 控制配额分组；Profile 控制编辑策略。限制是上限，并不保证填满所有名额。
• MCP/helper 参数中的 sources 选择的是来源类型，而不是具名 feed。
• 复用已完成的阶段。保存上游阶段会使下游产物失效。更改评分标准需要重新评分；更改阈值可以复用评分；更改章节顺序可以复用本地化产物。
• Markdown 生成采用程序化渲染。新增语言需要该语言的增强产物，并由 ai.languages 控制。
• 历史搜索会读取持久化文件 summaries/horizon-*.md。暂存的摘要只有通过 save_to_horizon_data 加入归档，才算正式归档；仅存在于某次运行中并不够。
• 新闻和评论是来源材料。保留来源 URL，并区分报道中的说法、观点和有依据的结论。

交接

先说明已完成的工作。附上相关配置/Profile 路径、运行 ID、数量、摘要路径，以及基于实际结果的交付/调度状态。对于贡献，概述其行为和已运行的检查。明确说明具体阻碍，并区分已写入的设置文件与已验证运行中的服务。

维护者可以按照 checkout 中 docs/agent-skill.md 的流程运行评估场景。