pp-yahoo-finance

Yahoo Finance — Printing Press CLI

前提条件：安装 CLI

此技能由 yahoo-finance-pp-cli 二进制文件驱动。**在调用此技能中的任何命令之前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install yahoo-finance --cli-only
   

2. 验证：yahoo-finance-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果通过 npx 安装失败（没有 Node、处于离线状态等），请改用直接 Go 安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/commerce/yahoo-finance/cmd/yahoo-finance-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法通过 $PATH 找到二进制文件目录。在验证成功之前，请勿继续执行技能命令。

何时使用此 CLI

当 Agent 需要以确定性 JSON 格式获取 Yahoo Finance 市场数据、需要可跨调用累积数据的本地存储（投资组合、自选列表、历史缓存），或需要在受速率限制的主机上开展工作会话时，请使用此 CLI。它是唯一能将你的成本基础与实时数据相结合，并在遇到 429 时通过 Chrome Cookie 回退的 Yahoo Finance 工具。

何时不使用此 CLI

对于需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或更改远程状态的请求，请勿使用此 CLI。此 Printing Press CLI 仅提供用于检查、导出、同步和分析的只读命令。

独特功能

其他任何用于此 API 的工具都不具备这些功能。

可累积的本地状态

• portfolio perf — 跟踪你持仓的年初至今、一年期和历史总回报，已纳入成本基础、股息和当前价格。

  当 Agent 需要报告“用户今年的投资组合表现如何”时，请使用此功能——没有任何单个 Yahoo Finance 端点会包含成本基础。

  yahoo-finance-pp-cli portfolio perf --agent
  

• digest — 一条命令即可汇总隔夜新闻、涨跌幅最大的股票、当日财报，以及自选列表中所有股票的除息日期。

  当需要针对一组指定股票生成“每日市场简报”时，可将其作为一次 Agent 调用——无需再分别调用 4 个以上的端点。

  yahoo-finance-pp-cli digest --watchlist tech --agent
  

• portfolio dividends — 查看今年的股息总收入、各持仓明细以及成本收益率。

  当用户询问“我今年赚了多少股息”或“我的 JNJ 持仓实际收益率是多少”时，请使用此功能。

  yahoo-finance-pp-cli portfolio dividends --year 2026 --agent
  

• insiders-net-buying — 筛选过去 N 天内部人士净买入的公司，并可按你的自选列表过滤。

  当 Agent 需要查看用户自选列表中“内部人士实际在买入哪些股票”时，可将此功能用作信号层。

  yahoo-finance-pp-cli insiders-net-buying --recent 30d --watchlist tech --agent
  

面向 Agent 的计算功能

• options-chain — 在指定的到期天数范围内，将期权链筛选为平值、虚值或实值合约。

  当 Agent 需要筛选“财报发布前 AAPL 的虚值周度看跌期权”，又不想解析数千行期权链时，请使用此功能。

  yahoo-finance-pp-cli options-chain AAPL --moneyness otm --max-dte 45 --agent
  

• screen-local — 根据已同步到本地的数据，运行任意市盈率、市净率、收益率、利润率和增长率筛选条件。

  用于组合自定义价值或增长筛选，供 Agent 在已同步的股票范围内应用，远超 Yahoo 提供的 12 种预设筛选。

  yahoo-finance-pp-cli screen-local --pe-max 15 --roe-min 0.15 --agent
  

• compare — 对多个标的在一段时间内的价格加股息总回报进行排名。

  比较实际持有期回报而非仅看价格变化时，请使用此功能——这是唯一支持离线计算此指标的 Yahoo CLI。

  yahoo-finance-pp-cli compare AAPL MSFT NVDA --range 1y --include-divs --agent
  

• options-covered-calls — 根据年化收益率和到期天数，扫描你的持仓以寻找备兑看涨期权候选标的。

  用于从用户实际持有的股票中筛选“轮动策略”的备兑看涨期权候选标的。

  yahoo-finance-pp-cli options-covered-calls --min-yield-annualized 0.10 --max-dte 45 --agent
  

• watchlist correlate — 计算指定自选列表中各标的在某个日期范围内的两两 Pearson 相关系数。

  当 Agent 需要标记自选列表中的集中度风险时，请使用此功能——例如：“这个‘科技’自选列表是否有 80% 的风险敞口集中在 AAPL？”

  yahoo-finance-pp-cli watchlist correlate tech --range 6m --agent
  

缓解连接问题

• auth login --chrome — 当 Yahoo 的 crumb 握手被你的 IP 阻止时，导入当前 Chrome 会话 Cookie。

  当 Agent 的 doctor 报告来自主机 IP 的 429 错误时，可使用此方法；Chrome 会话 Cookie 可以解除 crumb 握手阻碍。

  yahoo-finance-pp-cli auth login --chrome
  

命令参考

autocomplete — 旧版自动补全（速度快于搜索）

• yahoo-finance-pp-cli autocomplete — 自动补全股票代码和公司名称

chart — 历史 OHLCV 价格数据

• yahoo-finance-pp-cli chart <symbol> — 获取某个股票代码的历史价格图表数据

fundamentals — 基本面时间序列数据（季度／年度）

• yahoo-finance-pp-cli fundamentals <symbol> — 获取基本面时间序列数据（EPS、营收、利润率、现金流等）

insights — 公司洞察、估值和技术事件

• yahoo-finance-pp-cli insights — 获取某个股票代码的洞察：技术事件、估值、研究报告

lookup — 股票代码搜索和查询

• yahoo-finance-pp-cli lookup — 搜索与查询相符的股票代码、新闻和基金

options — 股票和 ETF 的期权链

• yahoo-finance-pp-cli options <symbol> — 获取某个股票代码的期权链（看涨期权和看跌期权）

quote — 实时报价和报价摘要

• yahoo-finance-pp-cli quote list — 获取一个或多个股票代码的当前报价
• yahoo-finance-pp-cli quote summary — 获取详细的报价摘要，包括价格、基本面、所有权和申报文件

recommendations — 根据分析师评级关联的股票代码

• yahoo-finance-pp-cli recommendations <symbol> — 获取与指定股票代码具有相同评级的股票代码

screener — 预设和自定义股票筛选器

• yahoo-finance-pp-cli screener — 按 ID 运行预设筛选器

trending — 按地区查看热门股票代码

• yahoo-finance-pp-cli trending <region> — 获取当前某个地区最热门的股票代码

查找合适的命令

如果你知道要做什么，但不知道该用哪个命令，可以直接询问 CLI：

yahoo-finance-pp-cli which "<capability in your own words>"

which 会根据此 CLI 精选的功能索引，将自然语言功能查询匹配到最合适的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有可信的匹配项，此时可改用 --help，或使用范围更窄的查询。

操作示例

获取自选股列表的每日市场简报

yahoo-finance-pp-cli digest --watchlist tech --agent

单条命令即可返回指定自选股列表中股票的隔夜新闻、最大涨跌幅、当日财报和除息日期。

年初至今的投资组合表现

yahoo-finance-pp-cli portfolio perf --agent --select symbol,unrealized_pl,total_return_pct

将成本基础与实时报价和再投资股息合并。--select 可缩小负载范围，避免 Agent 在每一行上消耗上下文。

查找 AAPL 到期约 30 天的价外看跌期权

yahoo-finance-pp-cli options-chain AAPL --moneyness otm --max-dte 45 --type puts --agent

在客户端按价内／价外程度和 DTE 筛选完整期权链；Yahoo 的端点不支持筛选。

使用自定义 SQL 筛选低价大型股

yahoo-finance-pp-cli screen-local --pe-max 15 --roe-min 0.15 --market-cap-min 10000000000 --agent

对本地同步的基本面数据运行查询；Yahoo 的远程筛选器只有 12 个预设 ID。

对本地存储执行原始 SQL

yahoo-finance-pp-cli sql "SELECT symbol, ROUND(AVG(close), 2) AS avg_close FROM history WHERE date > date('now','-30 days') GROUP BY symbol ORDER BY avg_close DESC LIMIT 10"

演示 SQLite 用法；当 Agent 需要运行任何预设命令都无法满足的聚合查询时，此方法很有用。

身份验证设置

Yahoo Finance 没有 API 密钥；它需要进行 crumb+cookie 握手。CLI 会在首次调用时自动获取 crumb，并将 Cookie 保存到 ~/.config/yahoo-finance-pp-cli/。如果你的 IP 受到速率限制（云主机和许多国际 IP 都可能遇到这种情况），请运行 auth login --chrome，导入已登录的 Chrome 会话，以便成功完成 crumb 握手。

运行 yahoo-finance-pp-cli doctor 以验证设置。

Agent 模式

在任意命令后添加 --agent。相当于添加：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。这对于精简冗长 API 的上下文至关重要：

  yahoo-finance-pp-cli autocomplete --query example-value --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不会发送

• 支持离线 — 有本地 SQLite 存储时，同步／搜索命令可使用该存储

• 非交互式 — 从不提示输入，每项输入都通过标志提供

• 只读 — 请勿使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会产生更改的请求

响应信封

从本地存储或 API 读取数据的命令会将输出封装在一个来源信息信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并通过 .meta.source 判断数据来自实时来源还是本地。只有当 stdout 连接到终端，且未设置机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会向 stderr 输出易读的 N results (live) 摘要；通过管道使用的 Agent 以及显式指定格式的运行会在 stdout 输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

yahoo-finance-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
yahoo-finance-pp-cli feedback --stdin < notes.txt
yahoo-finance-pp-cli feedback list --json --limit 10

条目保存在本地的 ~/.local/share/yahoo-finance-pp-cli/feedback.jsonl。只有设置了 YAHOO_FINANCE_FEEDBACK_ENDPOINT，且传入了 --send 或设置了 YAHOO_FINANCE_FEEDBACK_AUTO_SEND=true，才会发送 POST 请求。默认行为仅保存到本地。

请写下让你感到意外的地方，而不是提交 Bug 报告。简短、具体，写成一行：这才是会不断积累价值的部分。

输出交付

每条命令都接受 --deliver <sink>。除 stdout 外（或替代 stdout），输出还会发送到指定的目标，以便 Agent 路由命令结果，无需手动通过管道传输。支持三种目标：

目标	效果
stdout	默认；仅写入 stdout
file:<path>	以原子方式将输出写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到 URL（当使用 --compact 时，内容类型为 application/json 或 application/x-ndjson）

遇到未知协议时，会拒绝请求并返回结构化错误，其中列出受支持的协议。Webhook 请求失败时会返回非零退出码，并在 stderr 记录 URL 和 HTTP 状态码。

命名配置

配置是保存的一组标志值，可在多次调用间重复使用。当定时运行的 Agent 每次都以相同配置调用同一命令时，可使用配置——即 HeyGen 的 “Beacon” 模式。

yahoo-finance-pp-cli profile save briefing --json
yahoo-finance-pp-cli --profile briefing autocomplete --query example-value
yahoo-finance-pp-cli profile list --json
yahoo-finance-pp-cli profile show briefing
yahoo-finance-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便 Agent 在运行时发现它们。

退出码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
5	API 错误（上游问题）
7	受到速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 yahoo-finance-pp-cli --help 的输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 请参阅上文的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并添加 --agent）

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/commerce/yahoo-finance/cmd/yahoo-finance-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add yahoo-finance-pp-mcp -- yahoo-finance-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which yahoo-finance-pp-cli 如果未找到，请提供安装选项（参阅本技能顶部的先决条件）。
2. 根据用户查询，从上文的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   yahoo-finance-pp-cli <command> [subcommand] [args] --agent
   

4. 如果有歧义，请查看子命令帮助：yahoo-finance-pp-cli <command> --help。