Fintel Data Skill 用于通过 Fintel（fintel.io）的 REST API 或官方 MCP 服务器查询机构级市场数据。Fintel 是机构级市场情报平台，其最强数据集是其他供应商普遍缺乏的：做空兴趣、借券费率、做空成交量、交割失败（fails-to-deliver）、13F 机构持仓和内部人交易。
用途
该技能在用户提及 Fintel 或询问相关市场数据时使用。它提供两个由同一数据契约支撑的访问面：REST（https://api.fintel.io/v1/*，使用 X-API-KEY 请求头，适合从任意 CLI 智能体用 curl 调用）和 MCP（https://mcp.fintel.io/mcp，使用 X-API-KEY 请求头，适合 MCP 原生客户端与工具自动发现）。两者均需 Fintel API 密钥。该技能为只读——只调用 GET 端点；API 也暴露写端点（创建/删除股票列表、警报订阅、团队），不要调用它们。
主要能力
技能按以下步骤工作：
第 1 步：解析 FINTEL_API_KEY。按顺序解析：FINTEL_API_KEY 环境变量；当前目录 .env 中的 FINTEL_API_KEY；git 仓库根目录 .env 中的 FINTEL_API_KEY（以便 worktree 从主检出继承密钥）。根据结果操作：KEY_FROM_ENV_VAR 直接在 curl 中使用 $FINTEL_API_KEY；KEY_FROM_LOCAL_DOTENV 或 KEY_FROM_ROOT_DOTENV 先加载再调用；KEY_NOT_SET 则向用户索取密钥。密钥随 Fintel API 计划提供（fintel.io，文档见 api.fintel.io/docs）。
第 2 步：解析证券。多数端点以 {country}/{symbol} 寻址——ISO 国家代码加股票代码，例如 us/AAPL。用户只给股票代码时默认 us。若股票代码有歧义，或用户给出公司名、CUSIP、ISIN、FIGI，先解析：可用 /v1/securities?query=apple&country=us 搜索，或用 /v1/identifiers/isin/US0378331005 做精确标识符查找（type: cusip, isin, ticker, id）。
第 3 步：将请求匹配到端点。支持的数据包括：做空兴趣与回补天数（/v1/securities/{country}/{symbol}/short-interest，过去一年，NYSE/NASDAQ 报告，可用性有限，需按账户启用，403 表示无权限）；借券费率、借券成本、可借股数（/borrow-rate）；每日做空成交量（/short-volume，过去一年：做空、做空豁免、总成交量）；交割失败 FTD（/fails-to-deliver，过去一年 SEC FTD 记录，仅美国）；机构持有人/13F 持有人（/owners，当前 SEC 13F 衍生持有人）；内部人交易/Form 4（/insiders，SEC Form 3/4/5 衍生，count 参数）；分析师目标价（/price-targets，高、低、均值、中位数）；分析师买入/持有/卖出评级（/analyst-ratings）；营收/EPS 预测（/forecast）；EOD 价格历史（/eod，period: 1m, 3m, 6m, 1y 默认, 2y, 3y, 5y, all）；最新价格与衍生统计（/last-price，52 周高低、WTD/MTD/YTD 变化，回退到 EOD 收盘并带 meta.warnings=["quote_stale"]）；股息历史（/dividends）；财报历史与超预期（/earnings）；即将到来的财报（单股 /calendar/earnings 或全市场 /v1/calendar/earnings，from/to ISO 日期，默认今天+7 天，最大 90 天窗口）；即将到来的股息（/calendar/dividends 或 /v1/calendar/dividends，同样窗口规则）；特定基本面指标（/data-points/{key}，通过 /v1/data-definitions?query=... 发现键）；排名靠前/靠后的股票（/v1/leaderboards 然后 /v1/leaderboards/{key}/entries，503 not_available 表示稍后重试，meta.status="beta" 表示存根数据）；证券档案、上市信息、标识符历史（/v1/securities/{country}/{symbol}）；用户自选股（/v1/stock-lists, /v1/stock-lists/{id}/items，以及每个列表的 /insiders, /owners, /filings）；用户警报（/v1/alerts, /v1/alert-messages）；账户/权限（/v1/account）。完整参数细节、国家/交易所发现端点及更多 curl 示例见 references/api-reference.md。
第 4 步：调用 API。例如：curl -s -H "X-API-KEY: $FINTEL_API_KEY" "https://api.fintel.io/v1/securities/us/AAPL/short-volume" | python3 -m json.tool。成功响应为 JSON，部分带 meta 对象（warnings、freshness、status），存在 meta.warnings 时向用户展示。错误返回 {"error": {"code": "...", "message": "..."}}，例如 unauthorized（密钥错误/缺失）、403（账户未启用该数据集，做空兴趣常见）、503 not_available（排名服务宕机——稍后重试，不要当作空数据）。使用按账户计量——谨慎批量，不要轮询。
第 5 步：MCP 替代方案（可选）。对于 MCP 原生设置，同一批工具可从官方服务器发现（工具名如 fintel.get_short_interest、fintel.get_security_owners——REST 对等，相同权限）：claude mcp add --transport http fintel https://mcp.fintel.io/mcp --header "X-API-KEY: your_key_here"。有 shell 访问时优先用 REST via curl——除密钥外无需设置。用户明确要求或 shell 访问受限时用 MCP（注意：两者在 Claude.ai 沙箱中均不可用）。
第 6 步：回复用户。数字格式整洁：价格保留 2 位小数，百分比保留 1-2 位小数，股数用逗号或缩写（2.3M, 1.1B）。做空数据要结合背景——做空兴趣占流通股比例、回补天数、借券费率趋势方向；高借券费率加可借股数下降是经典逼空形态，但只呈现数据，不做预测。持仓/内部人用表格（持有人、股数、变化、日期），区分 Form 4 数据中的买入与卖出及期权行权。注明数据来源为 "Fintel" 及数据集出处（SEC 13F、Form 3/4/5、NYSE/NASDAQ 做空报告）。绝不将数据转化为交易建议、目标价或逼空判断——呈现事实，让用户自行得出结论。
使用方式
需要 Fintel API 密钥（随 Fintel API 计划提供）。通过环境变量或 .env 文件提供密钥后，用 curl 调用 REST 端点，或通过 MCP 服务器接入 MCP 原生客户端。
适用场景
适用于查询机构级市场数据，尤其是做空兴趣、借券费率、做空成交量、交割失败、13F 机构持仓、内部人交易、分析师评级与目标价、盈利预测、价格历史、股息、财报日历、基本面指标、排行榜、自选股列表和警报等。
限制
该技能为只读，仅调用 GET 端点，不得调用写端点。使用按账户计量，需谨慎批量调用，不要轮询。部分数据集（如做空兴趣）可用性有限，需按账户启用，403 表示无权限。503 not_available 表示服务暂时不可用，应稍后重试而非视为空数据。REST 与 MCP 在 Claude.ai 沙箱中均不可用。不得将数据转化为交易建议、目标价或逼空判断。