stock-data-skill

# 实时股票数据 Skill 通过腾讯行情/新浪财经/腾讯自选股获取A股、港股、美股、指数的实时行情、历史数据、财务报表、技术指标及市场数据。所有调用走 `python3 bin/_cli_wrapper.py`（内部转发到 `bin/stock-cli`），agent 不需要知道 HTTP 细节。 > **网关说明**：所有请求通过 data-provider 网关（`COZE_DATA_GATEWAY_URL`）转发到上游数据源，用于计费和鉴权。 ## 何时使用 - 查询个股实时行情（价格、涨跌幅、成交量、市值、PE） - 获取历史K线数据（日/周/月/分钟级，支持前复权/后复权） - 按名称或拼音搜索股票代码 - 查看当日分时走势 - 技术面分析（MA/MACD/RSI/支撑压力位/缺口/综合信号） - 查询财务报表（利润表/资产负债表/现金流量表） - 查询技术指标（MA/MACD/KDJ/RSI/BOLL等） - 查询ETF基金数据（详情/持仓/净值） - 查询股东结构、分红数据、筹码成本 - 查询龙虎榜、大宗交易、融资融券 - 查看热搜股票/板块、投资日历、新股日历、板块行情 - 公司简况、业绩预告 ## 何时不使用 - 需要新闻资讯 → 使用新闻类 skill - 需要期货/期权数据 → 本 skill 不覆盖 ## 快速开始 ```bash # 列出所有可用 operation python3 ./bin/_cli_wrapper.py list # 查看某个 op 的入参 schema python3 ./bin/_cli_wrapper.py schema quote # 查询贵州茅台实时行情 python3 ./bin/_cli_wrapper.py call quote --param code=sh600519 # 搜索股票 python3 ./bin/_cli_wrapper.py call search --param keyword=茅台 # 技术分析 python3 ./bin/_cli_wrapper.py call analyze --param code=sh600519 # 查询财务报表 python3 ./bin/_cli_wrapper.py call finance --param code=sh600519 # 查询技术指标 python3 ./bin/_cli_wrapper.py call technical --param code=sh600519 # 查询ETF详情 python3 ./bin/_cli_wrapper.py call etf --param code=sh510300 # 查询龙虎榜 python3 ./bin/_cli_wrapper.py call lhb --param code=sh600519 # 查看热搜 python3 ./bin/_cli_wrapper.py call hot --param type=stock ``` > 本地联调时也可以直接运行 local-dev 构建的 `./bin/stock-cli-local list`，但 **coze claw 部署必须走 `python3 bin/_cli_wrapper.py`**。Coze 托管凭证环境变量只在 Python 执行上下文注入，由 wrapper 透传给 Go CLI。 ## 环境变量 | 变量 | 必填 | 默认 | 说明 | |------|------|------|------| | `COZE_DATA_PROVIDER_API_KEY_NEW_7639319066594918410` | Coze 生产必填 | — | Coze 托管凭证运行时注入的 data-provider 网关鉴权密钥；凭证名称/变量名配置为 `DATA_PROVIDER_API_KEY_NEW` | | `COZE_DATA_GATEWAY_URL` | ❌ | `https://data.coze.cn` | 网关地址，通常无需修改 | | `COZE_DATA_PROVIDER` | ❌ | `stock` | 网关路由 provider 名称 | | `COZE_DATA_TIMEOUT_SEC` | ❌ | `15` | 请求超时（秒） | > 本地联调二进制必须使用 `-ldflags "-X code.byted.org/stone/data-provider/pkg/dataproxy.BuildMode=local"` 构建，读取 `DATA_PROVIDER_API_KEY`。Coze 生产二进制不加该 ldflags，读取 `COZE_DATA_PROVIDER_API_KEY_NEW_7639319066594918410`。 Coze 凭证配置要求：凭证名称 `DATA_PROVIDER_API_KEY_NEW`，变量名 `DATA_PROVIDER_API_KEY_NEW`，Header API Key 类型，域名 `data.coze.cn`，请求头位置 `Authorization: Bearer <key>`。 ## 支持市场 | 前缀 | 市场 | 示例 | |------|------|------| | sh | 上交所 A 股 | sh600519（贵州茅台） | | sz | 深交所 A 股 | sz000001（平安银行） | | hk | 港股 | hk00700（腾讯控股） | | us | 美股 | usAAPL（苹果） | 常用指数：`sh000001`（上证指数）、`sz399001`（深证成指）、`hkHSI`（恒生指数） ## Operations ### 行情与分析（原有） | Operation | 用途 | 主数据源 | 详情 | |-----------|------|---------|------| | `quote` | 实时行情（价格/涨跌/量/市值/PE） | 腾讯→新浪 | [references/quote.md](references/quote.md) | | `kline` | 历史K线（日/周/月/分钟，支持复权） | 腾讯 | [references/kline.md](references/kline.md) | | `search` | 按名称/拼音搜索股票 | 腾讯 | [references/search.md](references/search.md) | | `minute` | 当日分时数据 | 腾讯自选股 | [references/minute.md](references/minute.md) | | `analyze` | 技术分析（MA/MACD/RSI/支撑压力/缺口/综合信号） | 内置计算 | [references/analyze.md](references/analyze.md) | > **港股实时行情选择指南**： > - `quote` 查港股有 **~15 分钟延迟**（受港交所免费行情授权限制），但字段丰富（涨跌幅、换手率、市值、PE 等）。 > - `minute` 查港股 **无延迟**（走腾讯自选股内部接口，有实时授权），但仅返回时间、价格、累计成交量/成交额。 > - **优先级**：查港股实时股价时优先用 `minute`（取最后一条即为最新价）；如果需要市值、PE、换手率等扩展指标且对时效无严格要求，再用 `quote`。 > - A 股不受此限制，`quote` 和 `minute` 均为实时。 ### 财务与公司信息 | Operation | 用途 | 主数据源 | 详情 | |-----------|------|---------|------| | `finance` | 财务报表（三大报表，支持多期，A/港/美股） | 腾讯自选股 | [references/finance.md](references/finance.md) | | `profile` | 公司简况 | 腾讯自选股 | [references/finance.md](references/finance.md) | | `reserve` | 业绩预告 | 腾讯自选股 | [references/finance.md](references/finance.md) | ### 技术指标与筹码 | Operation | 用途 | 主数据源 | 详情 | |-----------|------|---------|------| | `technical` | 技术指标（MA/MACD/KDJ/RSI/BOLL/BIAS/WR/DMI） | 腾讯自选股 | [references/technical.md](references/technical.md) | | `chip` | 筹码成本（仅沪深京A股） | 腾讯自选股 | [references/technical.md](references/technical.md) | ### 股东与分红 | Operation | 用途 | 主数据源 | 详情 | |-----------|------|---------|------| | `shareholder` | 股东结构（仅A股和港股） | 腾讯自选股 | [references/shareholder.md](references/shareholder.md) | | `dividend` | 分红数据 | 腾讯自选股 | [references/shareholder.md](references/shareholder.md) | ### 资金流向（按市场） | Operation | 用途 | 主数据源 | 详情 | |-----------|------|---------|------| | `asfund` | A股资金流向 | 腾讯自选股 | [references/trading.md](references/trading.md) | | `hkfund` | 港股资金流向 | 腾讯自选股 | [references/trading.md](references/trading.md) | | `usfund` | 美股卖空数据 | 腾讯自选股 | [references/trading.md](references/trading.md) | ### 交易数据 | Operation | 用途 | 主数据源 | 详情 | |-----------|------|---------|------| | `lhb` | 龙虎榜（仅沪深） | 腾讯自选股 | [references/trading.md](references/trading.md) | | `blocktrade` | 大宗交易（仅沪深） | 腾讯自选股 | [references/trading.md](references/trading.md) | | `margintrade` | 融资融券（仅沪深） | 腾讯自选股 | [references/trading.md](references/trading.md) | ### ETF基金 | Operation | 用途 | 主数据源 | 详情 | |-----------|------|---------|------| | `etf` | ETF详情 | 腾讯自选股 | [references/etf.md](references/etf.md) | | `etf-holdings` | ETF持仓明细 | 腾讯自选股 | [references/etf.md](references/etf.md) | | `etf-nav` | ETF净值历史 | 腾讯自选股 | [references/etf.md](references/etf.md) | ### 市场总览 | Operation | 用途 | 主数据源 | 详情 | |-----------|------|---------|------| | `hot` | 热搜（股票/板块/ETF） | 腾讯自选股 | [references/market.md](references/market.md) | | `board` | 板块行情 | 腾讯自选股 | [references/market.md](references/market.md) | | `calendar` | 投资日历 | 腾讯自选股 | [references/market.md](references/market.md) | | `ipo` | 新股日历（沪深/港股） | 腾讯自选股 | [references/market.md](references/market.md) | | `exdiv` | 分红除权日历 | 腾讯自选股 | [references/market.md](references/market.md) | | `suspension` | 停复牌信息 | 腾讯自选股 | [references/market.md](references/market.md) | ## Exit Code | code | 含义 | |------|------| | 0 | 成功 | | 1 | 客户端用法错误（未知子命令 / 缺参 / 格式错） | | 2 | 鉴权失败（env 缺失或上游 401/403） | | 3 | 上游业务错误（4xx）| | 4 | 上游服务错误（5xx）| | 5 | 网络 / 超时 / 协议错 | ## 错误处理范式 ```bash output=$(python3 ./bin/_cli_wrapper.py call quote --param code=sh600519 2>err.log) case $? in 0) echo "$output" | jq . ;; 3|4) echo "上游错误"; cat err.log ;; 5) echo "网络异常，建议重试"; cat err.log ;; *) echo "用法错"; cat err.log ;; esac ``` ## 调用约定 - **股票代码格式**：`{市场前缀}{代码}`，如 `sh600519`、`hk00700`、`usAAPL`。前缀小写，美股 ticker 保留大写 - **多数据源自动切换**：quote 操作依次尝试多个数据源，任一成功即返回。kline/search/minute 同理 - **技术分析两步走**：`analyze` 内部自动获取 K 线数据再计算指标，无需手动传入 K 线文件 - **派生指标**：本 skill 未直接提供的指标（如 PB、PCF、PS、股息率等）可通过组合现有接口数据计算得出。例如： - PB（市净率）= 总市值（`quote`）÷ 净资产（`finance` 资产负债表） - PCF（市现率）= 总市值（`quote`）÷ 经营现金流净额（`finance` 现金流量表） - PS（市销率）= 总市值（`quote`）÷ 营业收入（`finance` 利润表） - 股息率 = 每股分红（`dividend`）÷ 当前股价（`quote`） ## 已知限制 ### 行情与分析 - **quote** 依次尝试多个数据源，任一成功即返回；**港股行情有 ~15 分钟延迟**，查港股实时价格应优先用 `minute` - **minute** 走腾讯自选股接口，A 股和港股均为实时无延迟，但字段仅含时间/价格/累计量 - **kline** 日/周/月走 fqkline，分钟线走 mkline；历史数据量上限约 120 根 - **search** 结果约 10 条，适合精确匹配/自动补全场景 - 技术分析至少需要 20 根 K 线才能给出有效信号 ### 数据覆盖范围 - **龙虎榜（lhb）/大宗交易（blocktrade）/融资融券（margintrade）**：仅支持沪深市场 - **筹码成本（chip）**：仅支持沪深京A股 - **股东结构（shareholder）**：仅支持A股和港股 - **货币单位**：港股返回港元/美元，美股返回美元 ## 不要做 - ❌ 不要试图绕过 CLI 直接 curl 数据源：所有请求必须通过网关转发，否则无法计费和鉴权 ## 服务端配置（TCC） 需要在 TCC 的 `http_proxy_config` 中添加 provider 为 `stock` 的配置项： ```json { "provider_name": "stock", "base_url": "http://placeholder.stock", "description": "Stock data multi-upstream proxy" } ``` - ❌ 不要修改 `bin/stock-cli` 的源码（源码在 `tools/stock-cli/`） - ❌ 不要修改 `bin/_cli_wrapper.py`：该脚本是 coze claw env 注入的唯一桥接入口，任何修改都可能导致凭证注入失败 - ❌ 不要修改 `bin/_gateway_proxy.py`（如存在）：该脚本是 skill 网关计费集成的唯一入口 - ❌ 不要把生产二进制编成本地模式（`BuildMode=local` 仅限本机联调） - ❌ 不要在 coze claw 部署时直接运行 `./bin/stock-cli`（会读不到托管密钥），必须走 `python3 bin/_cli_wrapper.py`