financial-analysis

金融分析技能

一个多源金融分析引擎，聚合来自 14+ 个免费 API 和 20+ 个 RSS 源的数据，生成专业级股票分析，并提供可执行的买入／卖出评级和目标价。

首次设置

使用此技能前，请阅读 API 设置指南并配置 API 密钥：

Read references/api_setup_guide.md

然后初始化配置：

python scripts/api_config.py init
python scripts/api_config.py status

安装 Python 依赖项：

pip install yfinance feedparser pandas pandas-ta requests --break-system-packages

架构概览

financial-analysis/
├── SKILL.md                          # This file — main instructions
├── scripts/
│   ├── api_config.py                 # API registry, keys, fallback chains
│   ├── usage_tracker.py              # Rate limit enforcement, logging, reports
│   ├── api_caller.py                 # Resilient caller with auto-fallback
│   └── rss_feeds.py                  # RSS feed catalog and parser
└── references/
    └── api_setup_guide.md            # Step-by-step key setup + rate limits

API 系统的工作方式

每次 API 调用都会经过 scripts/api_caller.py，该脚本会：

1. 在调用前检查速率限制（每分钟、每天、每月）
2. 在调用之间强制延迟，以避免 IP 被封
3. 记录每次调用到 ~/.financial-analysis/logs/api_usage.jsonl
4. 调用失败时：记录到 error_log.jsonl，并尝试回退链中的下一个 API
5. 所有调用均失败时：返回错误，并附上每次尝试的详细信息

scripts/usage_tracker.py 中的跟踪器会汇总用量并生成：

• 每日用量报告，显示各 API 已消耗的免费额度百分比
• 错误报告，显示哪些 API 调用失败以及哪些回退 API 调用成功
• 当任何 API 的免费额度使用量超过 70% 时，提供付费套餐建议

回退链

每个数据类别都有一条按优先级排列的 API 链。如果主 API 调用失败或触及速率限制，系统会自动尝试下一个 API。回退链定义在 scripts/api_config.py → FALLBACK_CHAINS 中。主要回退链：

数据类别	主 API → 回退 API
历史价格	yfinance → Polygon → Alpha Vantage → FMP
财务报表	yfinance + SEC EDGAR → Finnhub → FMP
分析师评级	Finnhub → yfinance → SA RapidAPI → Mboum
内部人交易	SEC EDGAR → Finnhub → Mboum → yfinance
国会交易	Mboum → Quiver（付费）
技术指标	Alpha Vantage → Mboum → Polygon → FMP
新闻情绪	Finnhub → Alpha Vantage → Alpaca
Reddit 情绪	ApeWisdom → StockTwits

三种使用场景

此技能支持三种不同的工作流。用户会提出其中一种需求（或者你可以根据上下文建议合适的场景）。

---

使用场景 1：每周投资组合审查

触发条件：用户提供 PDF、CSV 或当前持仓列表，并要求审查、分析或提供买入／持有／卖出建议。

输入：投资组合持仓（股票代码 + 可选的持仓数量／成本基础） 输出：每只股票的评级（买入／持有／减持／卖出）及置信度评分、3 个入场价位、3 个卖出目标价和主要理由。 频率：每周一次（周日／周一）

工作流

按顺序执行以下阶段。每次 API 调用都使用 scripts/api_caller.py 中的 call_with_fallback()，以启用自动回退和日志记录。

阶段 A — 数据收集（针对投资组合中的每个股票代码）：

1. 获取当前价格和 1 年的每日 OHLCV 历史数据（yfinance）
2. 获取季度财务报表：损益表、资产负债表、现金流量表（yfinance + SEC EDGAR）
3. 获取分析师评级共识：买入／持有／卖出数量（Finnhub）
4. 扫描过去 90 天的内部人士活动：Form 4 文件（SEC EDGAR）
5. 获取内部人士情绪评分：MSPR（Finnhub）
6. 获取近月期权链（yfinance）
7. 获取新闻情绪（Finnhub + Alpha Vantage）
8. 单次调用：Reddit 热门股票代码及提及速度（ApeWisdom）
9. 单次调用：近期国会议员交易（Mboum）
10. 单次调用：即将公布的财报日历（Finnhub）

阶段 B — 技术分析（使用 pandas-ta 在本地计算，不调用 API）：

• SMA/EMA 指标组（10/20/50/100/200）
• RSI（14）、MACD（12,26,9）、布林带（20,2）
• 随机振荡指标、ADX
• 成交量分析 + OBV
• 枢轴点（经典 + 斐波那契）
• 根据近期波段计算斐波那契回撤位和扩展位
• 用于仓位规模计算的 ATR

阶段 C — 评分（全部在本地计算）：

• 基本面评分（0-100）：营收增长、利润率、FCF、比率、同行比较
• 技术面评分（0-100）：趋势、动量、波动性、支撑／阻力位情况
• 情绪评分（0-100）：分析师 + 内部人士 + 国会议员 + 新闻 + 社交媒体
• 综合评分：40% 基本面 + 30% 技术面 + 30% 情绪
• 评级：75-100 = 买入 · 40-74 = 持有 · 0-39 = 减持／卖出

阶段 D — 生成输出（每个股票代码）：

字段	描述
评级	买入 / 持有 / 减持 / 卖出
综合评分	0-100
置信度	高 / 中 / 低（根据各阶段的一致程度）
入场位 1（激进）	当前价格（高确信度）
入场位 2（适中）	最近支撑位 / 斐波那契 38.2%
入场位 3（保守）	强支撑位 / 斐波那契 61.8%
目标位 1（T1）	最近阻力位 / 斐波那契扩展位 127.2%
目标位 2（T2）	主要阻力位 / 斐波那契扩展位 161.8%
目标位 3（T3）	完整扩展位 / 斐波那契扩展位 261.8%
止损位	关键支撑位下方或 1.5× ATR
关键催化因素	最多 3-5 项看涨驱动因素
关键风险	最多 3-5 项看跌风险

分析完所有股票代码后，运行使用情况报告：

from scripts.usage_tracker import get_tracker
get_tracker().print_daily_report()
get_tracker().save_daily_summary()

---

用例 2：每日机会扫描器

触发条件：用户要求寻找新的股票创意、扫描投资机会或识别波段交易机会。

输入：用户关注的投资组合方向（例如“成长型”“价值型”“收益型”），以及可选的当前持仓，用于避免重复。 输出：前 5 个投资组合新增标的 + 前 5 个波段交易标的，每个标的都附带评分、3 个入场位和 3 个退出位。 频率：每日（开市前）

工作流

阶段 A — 来源汇总（广泛收集）：

1. 使用 scripts/rss_feeds.py → scan_all_feeds() 扫描所有 Tier 1+2 RSS Feed，提取所有 Feed 中提及的股票代码。
2. 为步骤 1 中排名前 5 的股票代码抓取 Seeking Alpha 按股票代码提供的 RSS。
3. 获取 Reddit 上热门的股票代码（ApeWisdom）——与 RSS 提及内容交叉比对。
4. 对重合度最高的 10 个股票代码进行 StockTwits 情绪扫描。
5. 检查最新的国会议员交易（Mboum）。
6. 获取未来 5 天内即将公布财报的公司（Finnhub）。

阶段 B — 筛选（缩小范围，选出排名前 20 的候选项）： 7. 对排名前 20 的候选项进行新闻情绪分析（Finnhub）。 8. 获取排名前 5 的候选项的 SA 量化评级和因子等级（SA RapidAPI）。 9. 获取排名前 5 的候选项的 AI 情绪评分（Alpha Vantage — 每日 25 次中的 5 次）。 10. 进行价格和成交量筛选（yfinance）——52 周区间位置、成交量与平均值的对比。 11. 检查排名前 10 的候选项的财务健康状况（yfinance）——营收增长、利润率、市盈率。 12. 获取排名前 10 的候选项的分析师共识（Finnhub）。 13. 检查排名前 10 的候选项的内部人士交易情况（SEC EDGAR）。

阶段 C — 分析（针对排名前 10 的入选者）： 14. 计算支撑位/阻力位及入场/离场目标（本地使用 pandas-ta）。 15. 检查排名前 5 的候选项是否存在异常期权活动（Mboum）。 16. 进行多因子评分并最终排名（本地计算）。

阶段 D — 输出：

提供两个列表：

投资组合新增标的（符合增长目标，投资周期较长）：

• 股票代码、评分、评级、3 个入场价位、3 个离场价位、止损价、风险回报比、催化因素

波段交易（基于动量，投资周期较短）：

• 股票代码、评分、评级、3 个入场价位、3 个离场价位、止损价、风险回报比、催化因素、时间周期

---

用例 3：按需深入分析股票

触发条件：用户要求分析某只特定股票、深入分析某个股票代码，或询问“我应该买入 X 吗？”

输入：1-10 个股票代码
输出：为每个股票代码生成完整的分析师级报告，包含买入 / 观望·持有 / 卖出评级、3 个入场价位、3 个离场价位及全面分析。

工作流

这是最全面的分析——会查询所有可用数据源。共分 4 个阶段，每个股票代码约调用 30 次 API。

阶段 A — 基本面（每个股票代码 11 个步骤）： 公司概况、5 年损益表、季度营收趋势、资产负债表、现金流、使用 SEC EDGAR 的 XBRL 交叉验证、关键比率计算（PE/PB/PS/PEG/EV-EBITDA/ROE/ROA/D-E/FCF 收益率）、同行比较（5 家）、财报历史及超预期情况、即将公布财报的日期、股息历史。

阶段 B — 技术面（17 个步骤，大多通过 pandas-ta 在本地完成）： 2 年每日 + 6 个月盘中价格历史、SMA/EMA 指标组、RSI、MACD、布林带、随机指标、ADX、成交量 + OBV、VWAP、枢轴点、斐波那契回撤、斐波那契扩展、成交量分布、ATR、一目均衡表。通过 Alpha Vantage API 对 2 个指标进行交叉验证。

阶段 C — 情绪与另类数据（16 个步骤）： 分析师评级共识（Finnhub）、目标价（yfinance）、内部人士 Form 4 申报文件（SEC EDGAR）、内部人士 MSPR（Finnhub）、国会议员交易（Mboum）、机构持仓者（yfinance）、空头持仓、新闻情绪（Finnhub + AV AI）、Reddit 提及（ApeWisdom）、StockTwits 情绪、SA 量化评级 + 因子等级（SA RapidAPI）、SA 按股票代码提供的文章（RSS）、期权流（yfinance）、异常期权（Mboum）、近期 SEC 申报文件扫描。

阶段 D — 评分与输出（12 个步骤，全部在本地完成）： 基本面评分（0-100）、技术面评分（0-100）、情绪评分（0-100）、综合评分（加权 40/30/30）、评级分配（买入 ≥75 / 观望·持有 40-74 / 卖出 <40）、3 个入场价位、3 个离场目标、止损价、风险回报比、置信度、关键催化因素、关键风险。

为每个股票代码输出包含所有发现的综合报告。仅推荐风险回报比 ≥ 2:1 的交易。

---

错误处理

任何 API 调用失败时，系统将：

1. 记录错误到 ~/.financial-analysis/logs/error_log.jsonl，包含时间戳、API、类别和错误消息
2. 尝试备用方案——使用该数据类别调用链中的下一个 API
3. 记录备用方案结果——记录使用了哪个备用方案，以及是否成功
4. 如果所有备用方案均失败，则使用可用数据继续，并在输出中注明数据缺失

查看错误

python scripts/usage_tracker.py errors      # Last 7 days
python scripts/usage_tracker.py errors 30   # Last 30 days

常见错误及修复方法

错误	API	修复方法
429 请求过多	yfinance	将延迟增加到 5s。减小批次大小。
429 速率受限	Alpha Vantage	已达到每日 25 次的限制。请等待，或在本地使用 pandas-ta。
403 禁止访问	SEC EDGAR	在配置中设置 User-Agent 邮箱。
API 密钥无效	任意	检查 ~/.financial-analysis/api_keys.json
连接超时	任意	会自动触发回退。请检查网络连接。

使用报告和付费套餐建议

每次工作流运行后，使用情况跟踪器都会保存每日摘要。当任何 API 的使用量超过免费限额的 70% 时，它会生成付费套餐建议：

python scripts/usage_tracker.py daily    # See today's report
python scripts/usage_tracker.py summary  # Save JSON summary

摘要包含每个 API 的以下信息：今天/本月的调用次数、免费限额占比、错误数和严重程度评级（SAFE / WARNING / CRITICAL）。

最有可能需要升级的 API（按顺序排列）：

1. Alpha Vantage（每日 25 次）——最先达到限额。升级：$29.99/月
2. Mboum（每月 600 次）——如果每天运行全部 3 种用例，限额会很紧。升级：$9.95/月
3. SA RapidAPI（每月 1K 次）——大量使用深度分析时限额会很紧。请查看 RapidAPI 定价。

重要说明

• 此技能提供基于数据的分析，而非财务建议。请务必自行尽职调查。
• yfinance 是一个非官方库——数据可能会延迟或暂时不可用。
• SEC EDGAR 数据具有权威性，但需要解析。
• 所有时间戳均采用所分析市场的时区（美国股票使用美国东部时间）。
• 可根据用户偏好调整评分系统的权重。