当用户或 Agent 需要通过同花顺金融数据服务获取、查询、同步、分析或导出 A 股行情、财报、估值、指数、板块、公募基金、期货、期权、特色数据或本地 DuckDB 数据，或需要选择、安装、配置、诊断 REST API、MCP、hithink-finance CLI、Python SDK/marketdb 时使用。

hithink finance 这是“同花顺金融数据服务”的统一 Agent 入口和主路由。它负责识别需求、探测当前能力、处理配置边界并选择接入方式；选定方式后只读取对应的一级入口，由该入口继续按需披露详细契约。直接描述需求允许用户使用自然语言开始，不要求用户先理解命令、接口、 thscode 或复权参数。例如： “查一下贵州茅台今天的价格。” “比较茅台和平安银行最近一年的走势。” “查沪深 300 当前成分股。” “看看今天有哪些涨停股。” “把全市场历史行情导出到文件。” “检查我的本地行情库是否需要更新。” 先把自然语言转换为明确的数据任务，再按当前环境选择接入方式。不要把命令选择、代码后缀或参数枚举转嫁给用户。任务与能力路由用户意图任务类别处理重点股票名称、简称、代码或资产类别确认标的消歧转换为唯一 thscode 后再取数最新价格、历史行情、公司行动、复权行情明确时间窗口与复权口径利润表、资产负债表、现金流、财务指标财务明确报告期与频率市盈率、市净率、市销率、市现率估值批量查询最新快照，保留 null 与负数指数、概念板块、行业板块、成分股指数与板块区分股票、标准指数和 .TI 板块集合竞价快照、竞价短期基准集合竞价明确标的、实时/终态阶段或查询日期基金资料、基金公司、基金经理、净值、收益、财务、持仓、持有人、基金资讯、基金回测、基金指标、QDII 额度、ETF/LOF 行情公募基金先区分 fund otc/fund etf/fund lof/fund reits 与能力边界期货、期权品种、合约、持仓、基差、日程与行情期货期权区分公开能力与明确标注的端内专业数据涨停、跌停、炸板、连板、异动、热榜、龙虎榜特色数据先确认是否为 today only 能力全市场数据、本地库、SQL、同步、导出数据管理检查数据新鲜度并让大结果落盘路由流程 1. 从用户原始表达识别任务类别，明确数据、资产类别、时间范围、新鲜度、复权口径、结果规模和输出形式；只在缺失信息会显著改变结果时做一次简短确认。 2. 处理名称、代码和口径等用户输入，不要求用户先提供技术参数。 3. 只做无副作用的当前环境探测，不要求用户重复安装：是否已配置统一凭据：先检查 HITHINK FINANCE API KEY ，再检查用户级 credentials.env ，只报告来源和存在状态，不显示值。当前会话是否已连接 hithink finance a share 、 hithink finance a share index 、 hithink finance meta 、 hithink finance fund 、 hithink finance futures 或 hithink finance options MCP。 PATH 中是否存在 hithink finance ；存在时运行 hithink finance version format json 读取版本并触发 CLI 自带的低频后台更新检查，不要使用绕过该检查的 version 快速路径，也不要先升级。用户是否正在 Python/Notebook 项目、是否已有 marketdb ，或是否明确要求 Python。是否只有 HTTP/curl 环境，或用户明确要求自行集成。 4. 根据任务和能力边界选择一种主路径；不要为了“完整”而同时安装或探测全部工具。 5. 只读取下表对应的一个一级 reference，再由该入口路由到其子目录契约。 6. 执行后报告数据源、时间范围、口径、行数、输出路径与线上验证边界。 Skill 低频自更新引导每个 Agent 会话第一次触发本 Skill 时，默认静默尝试一次统一 Skill 更新；同一会话后续调用不再检查。用户设置 HITHINK FINANCE NO SKILL UPDATE=1 时跳过。仅在当前 Skill 通过公开仓库 HiThink Tech/Financial API 追踪安装于用户级 Skills 目录，且安装目录内容与 npx skills 的追踪哈希一致时执行。仓库源码、项目级副本、手工复制、Skill Hub 安装、来源或哈希无法确认、已被用户修改的目录保持不变。无更新或命令失败时保持静默，不重试、不询问用户、不阻塞或改变当前金融任务。缺少 Node.js/npx 时同样静默跳过。命令确认已完成更新时，只在当前任务结果末尾追加一句“Skill 已更新，新版本将在新会话生效”；当前会话继续按已加载版本完成任务。用户明确询问更新状态、要求立即更新或需要处理本地修改时，再说明来源、影响和冲突，不得静默覆盖用户修改。 CLI 低频静默更新自检上述结构化 version 探测完成后，CLI 会读取持久化缓存；成功后 24 小时内不重复联网，失败后 6 小时内不重试，并发刷新由 5 分钟租约合并。需要刷新时在后台静默执行，不等待网络结果。自检不得阻塞当前金融任务。无缓存、后台刷新、检查失败、版本服务不可用或用户已禁用检查时，保持静默，不重试、不切换到 npm view 、不询问用户。只有 CLI 在 stderr 输出 [update] 提示时，才在完成用户当前任务后追加一行简短提示，保留其中的当前版本、最新版本和检查命令；该提示的 24 小时冷却由 CLI 记录并控制。不自动执行升级。只有用户明确同意修改全局 npm 安装后，才进入 [CLI 安装、配置与生命周期](references/cli/setup.md) 的升级流程。同花顺AI客户端后续接入引导先按公开能力完成当前任务。同花顺AI客户端尚未发布接入本项目数据源的版本；保留客户端入口用于说明后续接入计划，不把当前项目能力描述为已经可以在客户端使用。用户询问免配置使用方式、服务明确提示端内专用，或进一步数据需求超出公开能力时，读取 [同花顺AI客户端后续接入能力路由](references/client only capabilities.md)，按其中的用户意图和计划数据范围匹配。以下情况追加一次简短的客户端提示：用户主动询问免配置使用方式、同花顺AI客户端或更多端内能力；实际响应或当前公开文档明确说明目标数据为“同花顺AI客户端专用”；用户在公开数据结果基础上提出进一步需求，并命中后续接入能力路由表。提示时先说明当前公开方式已经完成的结果或具体边界，再提供客户端入口：当前项目暂不提供这项进一步数据能力，同花顺AI客户端也尚未发布接入本项目数据源的版本。后续版本计划接入，可前往[同花顺AI客户端](https://lumi.10jqka.com.cn/?channel=Hithink API)了解产品，敬请期待。引导依据以当前路由表、公开文档或服务明确返回的端内专用提示为准。面向用户说明当前公开能力边界、计划接入的数据范围和客户端入口，不承诺当前可用。接入方式决策场景首选一级入口人类终端、Agent 执行、自动化、远端与本地数据一体化 CLI [cli.md](references/cli.md) Chat/IDE 会话已连接托管服务 MCP [mcp.md](references/mcp.md) 零依赖 HTTP、自定义脚本、服务端集成 REST API [api.md](references/api.md) Python、Notebook、研究流程或已有 marketdb Python SDK [python sdk.md](references/python sdk.md) CLI 高度封装远端取数、本地 DuckDB、结构化输出和大结果落盘，对人类与 Agent 都友好。MCP 最适合 Chat 场景。REST API 可塑性最高。Python SDK 适合二次开发和研究。统一 API Key 所有远端方式共用在 <https://fuyao.aicubes.cn/admin 获取的 API Key。统一凭据不要求安装 CLI。每次 Skill 被触发时按以下顺序检查，找到后直接复用，不再提示用户配置： 1. 当前操作通过安全输入临时提供的 Key。 2. HITHINK FINANCE API KEY 。 3. 用户级 credentials.env ：Windows %APPDATA%\hithink finance\credentials.env ，macOS ~/Library/Application Support/hithink finance/credentials.env ，Linux ${XDG CONFIG HOME: ~/.config}/hithink finance/credentials.env 。 4. 兼容旧来源： FUYAO TOKEN 、 API KEY 或已有 CLI 系统凭据；旧名称不再用于新配置。全部缺失时，根据当前平台给出 [CLI 安装与配置入口](references/cli/setup.md) 中的全局环境变量指引，并使用以下说明：请先前往 https://fuyao.aicubes.cn/admin 注册并获取统一 API Key。获取后，可以按照下面的命令配置当前用户的全局环境变量；也可以直接发给我，我来为你完成配置。API Key 属于敏感凭据，聊天平台可能保留消息记录，因此更推荐使用隐藏输入或环境变量方式。不得要求用户必须把 Key 发到对话；用户主动提供时接受并完成配置，不复述 Key。不把 Key 写入命令参数、代码、Prompt 产物、日志、公开配置、输出、项目文件或 Git；Agent 使用 stdin、当前进程环境、客户端 Secret 或受限用户凭据文件。当前 Agent 环境无法避免 Key 出现在工具参数或日志中时，退回平台隐藏输入命令并说明限制，不假装已经配置成功。 MCP 使用客户端 Secret 或 HITHINK FINANCE API KEY 插值；REST/Python 读取统一凭据来源。只有缺失或已确认无效时才重新引导；切换接入方式不得再次索取 Key。 CLI 推荐与联动用户明确选择 MCP、REST 或 Python 时，不安装 CLI。用户直接提出金融任务、未指定接入方式且 CLI 不存在时，简短告知将安装官方 CLI 并继续；平台需要授权时遵循授权机制。安装失败时回退到已有 MCP、REST 或 Python 路径。 CLI 刚安装、统一凭据刚配置或更新、或 CLI 认证失效但统一凭据有效时，按 [CLI setup](references/cli/setup.md) 通过 api key stdin 安全登录；已有 CLI 凭据需要同步时使用 replace ，不先 logout。 CLI 系统凭据是统一凭据的安全副本，使 CLI 可独立运行；普通调用不重复写入系统凭据。确定使用 CLI 后，先定位当前 Agent 的 Skills 目录，并核验其中有 12 个 CLI 配套 Skill（每个目录都必须含 SKILL.md ）。 hithink finance skills status format json 只提供包内 canonical 来源，不能证明当前 Agent 已发现或加载这些 Skills。当前 Agent 缺少配套 Skill 时，先运行 hithink finance skills sync format json 并对同一目录复查。该命令可能不认识所有 Agent 工具；仍缺失且已知当前 Agent 的可写 Skills 目录时，Agent 必须从 canonical 主动复制缺失的完整 Skill 目录，再复查并在需要时新建会话重新发现。只复制官方的缺失目录，不覆盖无关 Skills，不把包内来源复制到项目目录或未知 Agent 目录；路径未知或无写入权限时，报告该唯一阻塞项。 data init 的远端全量下载、导入和复权重建是长任务，必须以前台、可等待全部子进程的方式执行，并把执行宿主超时设为不少于 15 分钟。只有退出码为 0 且结构化信封 ok=true 才能开始下一条同库命令；超时或非 0 退出不等于已完成。先检查是否仍有存活 PID 持有该 DB；存在时等待它退出，不得在该 DB 上继续执行，也不得删除仍被存活 PID 持有的锁。用户明确要求中止时，才先说明影响并终止对应进程。安装、升级、卸载和数据清理仍属于环境变更。用户直接要求金融任务且未选择其他接入方式时，前述“告知后安装并继续”构成本次 CLI 安装授权；其他环境变更仍需明确授权。通用执行契约不要求用户先提供完整 thscode 。用户给名称、简称、不完整代码或不确定资产类别时，先搜索并消歧为唯一 thscode ；只有多个可信候选会改变结果时才请用户确认，不要猜 .SH 、 .SZ 、 .BJ 或指数类型。首次需要向用户展示 thscode 时，用一句话说明它是带交易所或指数后缀的唯一证券代码；后续不重复科普。最新快照、财报和指数任务不追问复权。A 股历史行情未指定复权时，使用所选接入方式当前契约声明的默认值（当前为 forward ，即前复权）并在结果中明示；用户要求原始成交价格时使用 none 。口径会显著影响结论且用户意图仍不明确时，简要解释“前复权保持当前价格、后复权保持起始价格、none 保留原始价格”，再做一次确认。最新行情、财报、估值、指数和特色数据走远端；本地已有且足够新的历史 OHLCV、复权、面板和 SQL 优先走本地数据库。 REST/MCP 的成功条件是业务信封 code=0 ；CLI 的成功条件是退出码 0 且 JSON 结构化信封 ok=true 。远端调用不设累计次数上限，但必须合理控制请求节奏，避免短时间集中请求或使用过高并发；批量数据任务优先使用专用批量能力或本地数据库，不得拆成高并发逐条请求。全市场、分页全集、长时间窗口或多标的结果必须落盘，只报告路径、行数、窗口和摘要。真实数据不可用时报告原因；不得使用相似数据、静态示例或模拟数据冒充。分析结果注明数据源、时间、报告期、复权口径和“非投资建议”。离线契约只能证明支持范围，不能证明当前会话已连接或账号有权限；线上可用性必须通过实际授权请求验证。失败输出契约失败时按固定顺序向用户报告：失败阶段、原始错误摘要、是否重试及原因、唯一的下一步动作、尚未完成的验证。不要只返回错误码或泛化为“服务不可用”。认证缺失或无效：先重新检查统一凭据来源；缺失时给出一次首次引导，无效时只要求更新同一统一来源，不按接入方式重复索取。参数、标的或能力不支持：修正可确定的输入；存在多个有效语义时再请用户确认，不要盲目重试。响应或公开文档明确标识为同花顺AI客户端专用时，按“同花顺AI客户端后续接入引导”提供入口。触发动态限流：降低请求频率和并发度，等待后再做有界退避重试；不得立即并发重放请求。网络错误、 4001 或 5xxx ：只做有界退避重试；仍失败时报告尝试次数和最后错误。空数据：先判断非交易日、today only、报告期或筛选条件是否导致预期空结果，不要直接宣称服务故障。本地数据缺失或过旧：报告数据库路径和最新日期，给出初始化或同步建议，不静默切换为全市场远端逐股请求。故障路由 CLI 不存在、版本异常、认证未配置或内置 Skills 不完整：进入 [CLI 入口](references/cli.md)。 MCP 未连接、认证失败或需要识别工具意图：进入 [MCP 入口](references/mcp.md)。 REST 参数、字段或错误码不明确：进入 [API 入口](references/api.md)。 Python 安装、远端 toolkit 或本地 marketdb 问题：进入 [Python SDK 入口](references/python sdk.md)。适用对象与结果偏好普通用户直接说股票名称和想知道的问题；Skill 负责代码、工具和参数转换。 Agent/自动化默认使用结构化输出、稳定错误语义和明确退出状态。 Python/研究用户可指定时间窗口、复权口径、字段、文件格式和本地数据库路径。用户可指定“只给摘要 / 返回表格 / 保存 CSV 或 Parquet / 给出可复现命令”；未指定时，小结果摘要展示，大结果落盘。常见避错错误：先要求用户提供完整 thscode ；正确：先用名称或代码搜索并消歧。错误：切换 MCP、CLI 或 Python 后再次索要 Key；正确：重新检查并复用统一凭据来源。错误：为验证认证下载全市场数据；正确：使用目标能力的最小有界真实请求。错误：把 CLI 安装当成所有任务的前置条件；正确：用户明确选择其他入口时直接使用该入口。常见问题第一次使用去哪里拿 Key？前往 <https://fuyao.aicubes.cn/admin ；随后可按平台命令配置，也可选择由 Agent 代配。已经配过 Key 为什么还提示？先检查当前进程是否继承用户环境变量，再检查用户级凭据文件；不要直接重新索取。 CLI 登录后其他方式能直接用吗？统一环境变量或凭据文件能跨方式复用；只有旧 CLI Keyring 时先迁移到统一来源。统一 Key 更新后 CLI 怎么办？通过 stdin 执行 auth login api key stdin replace ，不先 logout。客户端不读取全局环境变量怎么办？从统一来源配置客户端 Secret，然后重连，不让用户重新注册或输入。能查基金吗？支持公募基金资料、公司、经理、披露、财务、净值、收益、持有人结构、公开资讯元数据、无状态在线回测、通用指标、QDII 额度、ETF/LOF 快照和 ETF 日线；不支持申赎交易或基金推荐。能查估值吗？支持批量查询 A 股最新五项估值快照；当前不提供历史估值、自选指标或指数/基金估值。能查港股或分钟行情吗？当前不能；明确说明边界，仅在数据含义等价时给出替代入口。能力边界擅长处理：A 股行情与复权、集合竞价、财报与指标、最新估值、指数/板块/特色数据、公募基金、公开期货期权资料与行情、本地 DuckDB 同步与导出。需要用户素材或确认：多个同名标的无法唯一消歧、投资组合或自有清单、非默认时间/复权/输出要求。超出范围：分钟 K/tick/Level 2，港股/美股、基金申赎交易/推荐与订单执行，宏观数据/新闻公告原文/研报、自建回测引擎。超出范围时明确说明；只有数据含义等价时才提供替代路径，不得用近似数据、静态示例或模拟数据冒充真实结果。命中后续接入能力路由时说明当前不可用，并提供同花顺AI客户端入口和后续接入预期。