earnings-watch

Earnings Watch

通过命令行、Python API 和 MCP 服务访问经验证的发行方财报日历与业绩文件。模型会提出日期；确定性检查要求提供引用证据，并确保发行方、期间和时间信息一致。电话会议时间绝不会被静默转换为发布时间。

日历更新为可选功能。Earnings Watch 会生成操作计划；你的 MCP 客户端使用其外部 Outlook 应用执行计划，并确认已完成的写入。此软件包无需 Microsoft 凭据或日历 SDK。

维护的源代码与贡献：benjamin-di/earnings-watch。请参阅源代码与发行版本。

需要 Python 3.12+。使用 uv tool install earnings-watch 安装已发布的软件包，或从源代码检出版本开始开发：

make bootstrap
uv run earnings-watch init
uv run earnings-watch doctor
uv run earnings-watch sources import examples/sources.yaml
uv run earnings-watch watch EXAMPLE
uv run earnings-watch upcoming --format json

此示例使用保留域名和虚构数据；获取数据前，请替换其中的来源 URL 和发行方元数据。本软件包不包含发行方列表或市场数据订阅。

维护与模型

服务端会读取 SQLite 并更新个人关注项/台账；它不会获取发行方网页或调用模型。请单独运行维护任务：

uv run earnings-watch sweep --dry-run
uv run earnings-watch sweep
uv run earnings-watch sweep --docs-only
uv run earnings-watch worker

默认后端为 none：它会保留现有日期，并继续轮询官方发布源。若要提取新日期，请安装并登录自己的 Claude Code 或 Codex CLI，然后在 earnings-watch.toml 中进行配置：

[llm]
backends = ["claude-code", "codex", "none"]
max_calls_per_run = 20

支持的最低版本为 Claude Code 2.1.312 和 Codex 0.164.0。运行 earnings-watch doctor --live 以检查功能以及可选的模型试运行。此软件包不提供登录流程。模型用量遵循你的 CLI 账户限额和条款。只有在明确拒绝登录或账户限额，或已配置的 Codex 端点不可访问或在产生任何输出前出现故障时，才会尝试下一个后端；超时运行不会在同一轮中重试。

Codex 在 --ignore-user-config 模式下运行。若要通过兼容 OpenAI Responses 的端点向其发送请求，请在 [llm] 下同时设置 codex_base_url 和 codex_key_env（保存其密钥的环境变量名称）；密钥本身绝不能写入文件。任何不在本地主机上的端点都必须使用 https://。Claude Code 会从环境中接收 ANTHROPIC_BASE_URL 和 CLAUDE_CODE_MAX_RETRIES，因此设置有界的重试次数，可让不可用的端点在任务超时前失败。

MCP

初始化后的本地客户端配置：

{"mcpServers":{"earnings":{"command":"earnings-watch","args":["serve","--stdio"]}}}

工具	用途
earnings_upcoming	有界范围内的近期日期及时间不确定性
earnings_get_events	证据、修订记录和近期历史
earnings_documents	官方业绩文件链接及验证状态
earnings_changes	基于游标的公开变更源
earnings_watchlist	你的关注项和注册状态
earnings_watch	关注发行方；排队注册或消除歧义
earnings_unwatch	移除手动关注项
earnings_calendar_plan	规划可选的外部日历操作
earnings_calendar_ack	记录已确认的计划操作
earnings_status	目录和维护状态

提示词：earnings_briefing、results_brief、sync_to_my_outlook。资源：earnings://upcoming.ics。精确时间需要经验证的时钟和时区证据；否则日历条目均为全天事件。Outlook 操作绝不包含与会者。

HTTP 独立模式在 /users/<id>/mcp 为每个人使用单独的 bearer token。网关模式接受已配置的后端 bearer token，以及来自准入网关的不可变主体标头，路径为 /mcp。这两种模式属于独立的信任边界；请参阅权限。

连接页面与通知

可选的连接页面将即将到来的事项、你的公司、通知和日历集中在一处。登录、添加公司或预览持仓导入，然后订阅你的私人日历订阅源。事实信息为共享内容；持仓、观察列表、静音设置、偏好设置和回执均为个人内容。

新用户默认启用结果发布通知。每日简报和紧急变更通知为可选项。提交邮件需要单独配置传输方式；服务和采集工作进程本身不会发送消息。

Docker Compose

cp earnings-watch.example.toml earnings-watch.toml
docker compose build
docker compose run --rm server init
docker compose run --rm server users add example
docker compose up -d

请私下保存返回的令牌，并且仅将其用于该用户的 HTTP 路径。服务器默认绑定到环回地址。两个镜像都以 uid 1000 运行；Compose 会丢弃功能、阻止权限提升，并以只读方式挂载根文件系统。工作进程镜像包含固定版本的模型 CLI；在 backends=["none"] 时，其身份验证卷为可选项。启用模型维护前，请在只读工作进程之外配置 CLI 登录。请保护身份验证文件和数据卷，避免其他用户访问。

CLI 支持使用 --config PATH、--person ID 和 --json。设置来自 TOML 和 EARNINGS_WATCH_* 环境变量。请参阅运维、架构、提供方和设计决策。

开发

make check 会验证锁文件是否存在偏差、代码检查、格式、类型、依赖边界、离线测试以及 wheel/源代码构建。测试使用合成发行方和伪造的网络、模型及账户边界。真实模型和真实页面检查是单独的运维审批环节。请阅读 CONTRIBUTING.md 和 SECURITY.md。

请参阅实现状态，了解已完成的功能、发布门槛，以及切换前仍需完成的生产适配器工作。