1. 项目概述：一个为AI Agent打造的智能财报追踪技能
如果你和我一样，每天需要关注美股、港股、A股几十家公司的财报动态，手动去各个财经网站翻找、整理、筛选，那绝对是个耗时又容易出错的无底洞。尤其是在做量化分析或者投资决策时，错过一个关键财报或者信息滞后，代价可能不小。我之前就试过用Python脚本去爬取数据，但维护不同市场的API、处理时区、货币换算，还有那烦人的反爬机制，一套组合拳下来，脚本没写几个，头发倒是掉了不少。
后来接触到AI Agent框架，比如OpenClaw，我就琢磨着，能不能把“追踪财报”这个高频、刚需但又繁琐的任务，封装成一个标准化的“技能”（Skill），让我的AI助手去自动执行？这就是“Earnings Tracker”这个项目诞生的初衷。它本质上是一个专为AI Agent设计的插件或技能模块，核心目标就一个：让AI帮你自动、智能地追踪全球主要市场的上市公司财报日历和关键信息。
这个工具特别适合几类朋友：一是个人投资者或交易员，想第一时间获取持仓或关注公司的财报提醒；二是金融数据分析师或研究员，需要批量获取财报数据进行建模分析；三是任何对AI Agent应用开发感兴趣的朋友，想看看如何将一个具体的金融场景落地成一个可复用的Agent技能。它把复杂的多市场数据获取、清洗、摘要生成和消息推送都打包好了，你只需要通过简单的命令行指令，就能让你的AI助手化身成为你的专属财报小秘书。
2. 核心设计思路：模块化与数据源抽象
当我开始设计这个财报追踪器时，首要考虑的不是怎么把功能堆砌上去，而是如何构建一个灵活、健壮且易于扩展的架构。金融数据领域最大的特点就是“变”：数据源可能失效（比如某个免费API突然收费或限流），数据格式可能更新，用户的需求也可能从单纯看日历发展到需要深度分析。因此，整个项目的设计哲学可以概括为“以不变应万变”，这个“不变”的核心就是模块化和数据源抽象层。
2.1 为什么选择技能化（Skill）架构？
传统的财报工具可能是一个独立的网站或桌面应用。我选择将其构建为AI Agent的一个“技能”，是基于几个现实的考量：
- 场景融合：现代人的信息处理越来越依赖聚合平台。一个独立的财报App很容易被遗忘在手机角落，但如果财报提醒能直接推送到你日常使用的协作工具（如飞书/Lark）或由你的AI助手在对话中主动告知，信息的触达率和及时性会高得多。技能化架构让财报追踪能力可以无缝嵌入到你的AI工作流中。
- 能力复用：AI Agent本身具备自然语言理解、任务规划和执行的能力。财报追踪技能可以与其他技能联动。例如，Agent在回答“帮我分析一下下周科技股的投资机会”时，可以自动调用本技能获取财报日历，再调用数据分析技能进行初步筛选，最后生成一份综合报告。这种“1+1>2”的效应是独立应用难以实现的。
- 部署轻量：作为一个Skill，它通常以NPM包或Git仓库的形式存在，安装和更新一条命令搞定，无需复杂的服务器部署和维护，特别适合个人或小团队快速启用。
2.2 数据源抽象层：应对多变环境的基石
数据是这类工具的生命线，也是最不稳定的环节。项目支持从Mock、FMP到Yahoo Finance等多种数据源，其背后是一个精心设计的数据源抽象层（DataSource Abstraction Layer）。
这个抽象层定义了一套统一的数据接口（Interface），比如getEarningsCalendar(startDate, endDate, market),getCompanyProfile(symbol),getEarningsSummary(symbol, period)。所有具体的数据源提供商（FMP、Yahoo等）都需要实现这套接口。
这样做的好处非常明显：
- 对用户透明：用户通过
># 1. 检查Node.js版本，必须18.0或以上 node --version # 如果版本低于18，请去Node.js官网下载安装最新LTS版本。 # 2. 创建一个专门的工作目录并进入 mkdir -p ~/projects/ai-finance && cd ~/projects/ai-finance # 3. 克隆项目仓库（请将<your-github>替换为实际用户名或直接使用原始仓库路径） # 假设我们从示例仓库克隆 git clone https://github.com/Indomi/earnings-tracker.git cd earnings-tracker # 4. 安装项目依赖 npm install # 如果需要Yahoo Finance支持，额外安装其适配器（这是一个很好的可选依赖设计） npm install yahoo-finance2关键点解析：
- Node.js 18+：这个要求是因为项目可能使用了较新的JavaScript特性（如原生的Fetch API、ES模块等）。使用旧版本会导致语法错误。
- Optional Dependencies：项目将
yahoo-finance2列为可选依赖，这是一个很好的设计。它意味着核心功能不强制依赖这个库，只有当你切换到yahooFinance数据源时，才需要它。这保持了核心安装的轻量。你可以通过npm list查看哪些包是可选依赖。
4.2 数据源配置实战（以FMP为例）
项目默认使用Mock数据，方便测试，但真实使用必须配置真实数据源。我强烈推荐从Financial Modeling Prep (FMP)开始，它的免费层（250次/天）对于个人监控几十只股票来说完全足够，且数据质量非常稳定。
第一步：获取FMP API Key
- 访问 Financial Modeling Prep 开发者门户 。
- 注册一个免费账户。通常只需要邮箱和密码。
- 登录后，在Dashboard页面，你应该能看到你的API Key，一串长字符串（如
d1b3a9e5...）。复制它。
第二步：配置项目使用FMP项目配置通常放在
.config/目录下。你需要创建或编辑watchlist.json文件。# 确保配置目录存在 mkdir -p .config # 使用你喜欢的编辑器创建或编辑配置文件，例如用nano nano .config/watchlist.json将以下内容粘贴进去，并务必将
YOUR_ACTUAL_API_KEY_HERE替换为你刚才复制的真实API Key。{ "dataSource": { "provider": "financialModelingPrep", "options": { "financialModelingPrep": { "enabled": true, "apiKey": "d1b3a9e5yourrealapikeyhere" // 请替换！ } } }, // 你可以在这里添加你的自定义关注列表，这是一个高级功能示例 "watchlist": [ "AAPL", "MSFT", "NVDA", "00700.HK", "600519" ] }保存并退出编辑器（在nano中是
Ctrl+X，然后按Y确认，再按Enter）。第三步：切换并测试数据源
# 1. 列出所有可用的数据源，确认fmp在列表中 node scripts/index.js>node scripts/index.js preview这个命令会默认拉取未来7天内，所有支持市场（美、港、A）的财报发布日程。输出会是一个表格，包含公司名称、代码、市场、财报日期和预估EPS等信息。第一次运行如果看到真实公司数据（而不是Mock的“Example Inc.”），恭喜你，配置成功了！
场景二：我只关心美股科技巨头的财报
node scripts/index.js preview us tech这个命令做了两步过滤：先筛选市场为美股（
us），再在美股中筛选行业板块为科技（tech）。输出列表会精简很多，只包含像苹果、微软、谷歌这样的公司。场景三：深度查询某家特定公司的财报详情假设英伟达（NVDA）刚发了财报，你想快速获取AI总结。
node scripts/index.js summary NVDA这个命令会：
- 通过FMP获取NVDA最新季度的财报关键数据。
- 调用配置的AI模型（如Claude），生成一份结构化摘要。
- 在终端输出这份摘要，内容可能包括：“NVDA 2024 Q1 营收同比增长262%，大幅超预期。数据中心业务是核心增长引擎，贡献了XX%营收。管理层对下季度指引乐观，主要得益于AI芯片需求持续旺盛。”
场景四：查询港股或A股公司代码格式是关键：
# 查询腾讯控股（港股），代码需要加 .HK 后缀 node scripts/index.js query 00700.HK # 查询贵州茅台（A股），使用6位数字代码，并指定市场为‘cn’ node scripts/index.js query 600519 cn场景五：管理你的数据源
# 随时切换回模拟数据，用于功能测试而不消耗API额度 node scripts/index.js>问题现象可能原因 排查步骤与解决方案 运行任何命令都报错： Error: Cannot find module '...'1. 依赖未安装。
2. Node.js版本过低。
3. 项目路径不对。1. 在项目根目录执行 npm install。
2. 运行node --version确认版本≥18。如过低，请升级Node.js。
3. 确认终端当前目录是earnings-tracker/文件夹内。>1. API Key权限不足或额度用尽。
2. 请求参数（如日期范围）超出免费API限制。
3. 数据源本身暂时无数据。1. 登录FMP等数据源官网，检查Dashboard中的API调用次数和剩余额度。
2. 尝试缩小查询范围，如preview us只查美股，或指定具体日期。默认查询未来7天可能对某些免费API来说范围太大。
3. 切换到mock数据源测试命令本身是否正常：node scripts/index.js>查询港股或A股公司时提示“Stock not found”股票代码格式不正确。 港股：必须使用5位数字代码，并加上 .HK后缀，例如00700.HK。
A股：使用6位数字代码，并在命令中明确指定市场cn，例如query 600519 cn。沪市以6开头，深市以0或3开头。AI摘要生成失败或返回无意义内容 1. 未配置或错误配置了LLM API（如OpenAI/Claude）。
2. Prompt设计不佳，导致模型误解。
3. 网络问题导致API调用超时。1. 检查项目配置中是否有AI相关的设置项（可能在 .config/下的另一个文件如ai.json），确保API Key和Base URL正确。
2. 查看项目源码中关于摘要生成的Prompt模板，尝试简化你的查询或等待开发者优化Prompt。
3. 暂时关闭AI摘要功能，使用query命令只返回原始数据，确认问题是否出在AI环节。飞书/Lark消息推送失败 1. Webhook URL配置错误或已失效。
2. 消息格式不符合机器人要求。
3. 网络策略限制（如公司防火墙）。1. 在飞书群组中重新获取机器人的Webhook URL，确保完整复制。
2. 查阅飞书开放平台文档，检查你代码中构建的JSON消息体是否符合“卡片”或“文本”消息的格式规范。可以先用curl命令手动测试Webhook。
3. 尝试在另一网络环境（如手机热点）下测试，以排除网络策略问题。时区显示错误 项目内部时区处理逻辑有误，或服务器/本地环境时区设置不正确。 1. 在代码中关键位置打印UTC时间和转换后的本地时间，进行比对。
2. 确保你的服务器或本地系统时区设置正确。在Linux中可使用timedatectl status查看。
3. 在配置中显式指定你所在的时区（如Asia/Shanghai），而不是依赖系统设置。一些进阶的排查技巧：
- 开启调试日志：很多Node.js项目支持环境变量开启调试模式，例如在命令前加上
DEBUG=* node scripts/index.js ...。这会打印出详细的网络请求、参数和内部处理日志，对定位复杂问题非常有帮助。 - 模拟网络慢速或失败：使用
mock数据源是测试功能逻辑的绝佳方式，因为它不依赖外部网络，且返回确定性的数据。在开发新功能或排查问题时，先切到Mock源，确保核心流程正确。 - 关注数据源的更新日志：像Yahoo Finance这类免费源，其背后的数据接口可能在不通知的情况下发生变化。如果某天开始突然大量获取数据失败，第一反应应该是去相关社区（如GitHub issues）看看是否有其他人遇到同样问题。
6. 性能优化与扩展方向思考
当一个工具开始稳定运行后，我们自然会想让它更快、更强、更贴合个人需求。以下是我在实际使用中总结的一些优化点和未来可以扩展的思路。
1. 缓存策略：省钱又提速频繁调用数据源API，尤其是商用API，会产生费用。对于财报日历这类变化频率以天为单位的数据，实施缓存非常有效。
- 本地文件缓存：可以将
preview命令的结果按市场缓存到本地JSON文件中，并设置一个有效期（例如1小时）。下次请求时，如果缓存未过期且用户没有强制刷新（如--force参数），则直接读取缓存文件。这能极大减少对数据源API的调用。 - 内存缓存：对于在短时间内多次查询同一家公司财报摘要的请求（比如在调试时），可以使用内存缓存（如Node.js的
Map或node-cache包），设置一个短暂的过期时间（如5分钟），避免重复调用昂贵的LLM API。
2. 数据源熔断与降级我们不能假设任何一个数据源是100%可靠的。一个健壮的系统应该具备熔断机制。
- 失败计数：如果连续多次调用某个数据源失败（如网络超时、返回5xx错误），则暂时“熔断”该数据源，在接下来的一段时间内（如10分钟）自动将请求切换到备选源（如从FMP切换到Yahoo）。
- 健康检查：定期（如每30分钟）对当前活跃的数据源执行一次轻量级健康检查（如查询一只知名股票的基本信息），如果失败则触发降级。这可以防止在用户发起关键查询时才遭遇故障。
3. 扩展更多数据源与功能
- 数据源：可以集成更多免费或低成本的数据源，例如国内的AKShare、Tushare（针对A股数据更丰富），或者IEX Cloud、Twelve Data等。
- 分析功能：除了摘要，可以加入简单的财务比率计算（如PE、PB）、历史财报趋势对比图表生成（输出为图片或HTML片段）、或是基于历史数据的“财报后股价波动统计”等。
- 预警功能：不仅追踪已公布的日期，还可以设置自定义预警。例如，当某只关注股票的财报发布日期正式公布时，或财报发布前1小时，通过多个渠道（邮件、短信、App推送）进行强提醒。
4. 容器化与部署为了让这个技能更容易在服务器或云函数上持续运行（例如，每天定点推送财报日历），可以考虑将其容器化。
- Docker化：编写一个
Dockerfile，将Node.js环境、项目代码和依赖打包成一个镜像。这样可以确保在任何拥有Docker的环境下运行一致。 - 计划任务：结合Cron Job，在服务器上设置定时任务，每天特定时间执行
preview命令，并将结果通过消息推送技能发送出去，实现全自动的财报日历日报。
这个项目始于一个简单的需求，但通过模块化的设计和持续的迭代，它已经成长为一个相当实用的工具。最让我有成就感的是，它不仅仅是一段代码，而是真正融入了我的日常工作流，让AI Agent成为了我金融信息处理中一个可靠、高效的伙伴。如果你也正在构建自己的AI智能体，不妨从这样一个垂直领域的小技能开始，感受一下如何将想法通过代码和设计，变成一个能自动运转的数字助手。
