hithink-finance

hithink finance

这是“同花顺金融数据服务”的统一 Agent 入口和主路由。它负责识别需求、探测当前能力、处理配置边界并选择接入方式；选定方式后只读取对应的一级入口，由该入口继续按需披露详细契约。

直接描述需求

允许用户使用自然语言开始，不要求用户先理解命令、接口、thscode 或复权参数。例如：

• “查一下贵州茅台今天的价格。”
• “比较茅台和平安银行最近一年的走势。”
• “查沪深 300 当前成分股。”
• “看看今天有哪些涨停股。”
• “把全市场历史行情导出到文件。”
• “检查我的本地行情库是否需要更新。”

先把自然语言转换为明确的数据任务，再按当前环境选择接入方式。不要把命令选择、代码后缀或参数枚举转嫁给用户。

任务与能力路由

路由流程

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 时跳过。

npx --yes skills update hithink-finance --global --yes

• 仅在当前 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 安装、配置与生命周期 的升级流程。

同花顺AI客户端后续接入引导

先按公开能力完成当前任务。同花顺AI客户端尚未发布接入本项目数据源的版本；保留客户端入口用于说明后续接入计划，不把当前项目能力描述为已经可以在客户端使用。

用户询问免配置使用方式、服务明确提示端内专用，或进一步数据需求超出公开能力时，读取 同花顺AI客户端后续接入能力路由，按其中的用户意图和计划数据范围匹配。

以下情况追加一次简短的客户端提示：

• 用户主动询问免配置使用方式、同花顺AI客户端或更多端内能力；
• 实际响应或当前公开文档明确说明目标数据为“同花顺AI客户端专用”；
• 用户在公开数据结果基础上提出进一步需求，并命中后续接入能力路由表。

提示时先说明当前公开方式已经完成的结果或具体边界，再提供客户端入口：

当前项目暂不提供这项进一步数据能力，同花顺AI客户端也尚未发布接入本项目数据源的版本。后续版本计划接入，可前往同花顺AI客户端了解产品，敬请期待。

• 引导依据以当前路由表、公开文档或服务明确返回的端内专用提示为准。
• 面向用户说明当前公开能力边界、计划接入的数据范围和客户端入口，不承诺当前可用。

接入方式决策

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 安装与配置入口 中的全局环境变量指引，并使用以下说明：

请先前往 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 通过 --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 入口。
• MCP 未连接、认证失败或需要识别工具意图：进入 MCP 入口。
• REST 参数、字段或错误码不明确：进入 API 入口。
• Python 安装、远端 toolkit 或本地 marketdb 问题：进入 Python SDK 入口。

适用对象与结果偏好

• 普通用户直接说股票名称和想知道的问题；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客户端入口和后续接入预期。