跳到主要内容

CLI 快速开始

hithink-finance CLI 适合人类终端、AI Agent、CI 和自动化脚本。它提供远程取数、本地 DuckDB、认证、能力发现和稳定 JSON 输出。

完成后你将拥有​

  • 可在任意目录运行的 hithink-finance 命令。
  • 随 CLI 自动安装的 10 个 Agent 领域 Skills。
  • 安全保存在系统凭据库中的 API Key。
  • 一次可重复执行的真实行情查询。
  • 用于自动化的稳定 JSON 结果与明确退出码。

前置条件​

  • Windows、macOS 或 Linux。
  • Node.js 22.12 或更高版本。
  • 可用的 npm。
  • 从 API Key 管理 创建的 Key。

先检查环境：

node --version
npm --version

node --version 应返回 v22.12.0 或更高版本。

第 1 步：安装 CLI​

通过 npm 全局安装官方包：

npm install -g @hithink-tech/hithink-finance-cli

国内网络可使用 npmmirror：

npm install -g @hithink-tech/hithink-finance-cli --registry=https://registry.npmmirror.com

检查命令是否已加入 PATH：

hithink-finance --version
hithink-finance version --format json

如果第一条命令不存在，重新打开终端，并确认 npm 全局 bin 目录已加入 PATH。如果 npm 返回 E404，请检查当前 registry 是否可访问公开 npm 包，不要改用未知来源的同名包。

第 2 步：配置 API Key​

交互式终端直接运行：

hithink-finance auth login

CLI 会隐藏 API Key 输入，并将凭据保存到当前用户的系统凭据库。登录后检查状态：

hithink-finance auth status --format json

Agent 或 CI 应使用 HITHINK_FINANCE_API_KEY 或 stdin。POSIX Shell 示例：

printf '%s' "$HITHINK_FINANCE_API_KEY" | \
  hithink-finance auth login --api-key-stdin --format json

PowerShell 可以使用隐藏输入，且不把 Key 写入命令历史：

$secureKey = Read-Host 'API Key' -AsSecureString
$key = [System.Net.NetworkCredential]::new('', $secureKey).Password
$key | hithink-finance auth login --api-key-stdin --format json
Remove-Variable key, secureKey
注意

不要使用 --api-key <value>。该参数仅为旧脚本兼容保留，可能将 Key 暴露在 Shell 历史和进程列表中。

第 3 步：运行诊断​

先检查运行时、认证、配置和本地数据环境：

hithink-finance doctor --format json
hithink-finance capabilities --format json

doctor 和 capabilities 通过只能证明 CLI 本地环境基本正常，不能代替真实线上请求。

第 4 步：完成首次真实查询​

先搜索标的，避免猜测交易所后缀：

hithink-finance symbol search --q "贵州茅台" --limit 1 --format json

确认结果中的标准证券代码为 600519.SH 后，查询最新行情：

hithink-finance market snapshot --thscodes 600519.SH --format json

成功判定​

同时满足以下条件，才说明首次接入完成：

  1. 进程退出码为 0。
  2. JSON 顶层包含 "ok": true。
  3. 结果中存在 600519.SH 的真实记录，而不是空数组或静态示例。

如果只有 doctor、--help 或离线 schema 通过，还不能证明当前 Key 有权限访问线上数据。

第 5 步：发现更多命令​

不要从旧示例猜测参数。先查看能力目录，再查看目标命令的 schema 或帮助：

hithink-finance capabilities --format json
hithink-finance schema market.snapshot --format json
hithink-finance market snapshot --help

常用入口：

# 最近四期利润表
hithink-finance financials income --thscode 600519.SH --limit 4 --format json

# 沪深 300 当前成分股
hithink-finance index constituents --thscode 000300.SH --format json

# 查看本地数据库状态
hithink-finance data status --format json

机器处理时显式使用 --format json。全市场、多标的、多年或分页全集不应全部打印到终端；使用目标命令支持的 --output 落盘，只在终端保留路径、行数、时间窗口和摘要。

让 Agent 使用 CLI​

CLI 会自动安装配套 Skills​

通过 npm install -g @hithink-tech/hithink-finance-cli 全局安装时，CLI 的 postinstall 脚本会尝试将包内 10 个领域 Skills 复制到受支持 Agent 的全局 Skills 发现目录：

Skill主要用途
hithink-finance-shared认证、配置、诊断和安全规则
hithink-finance-symbol标的搜索、代码表与消歧
hithink-finance-marketA 股行情、历史 K 线、竞价、日历与复权
hithink-finance-financials财务报表与财务指标
hithink-finance-valuationA 股最新估值快照
hithink-finance-index指数、板块、成分股与指数行情
hithink-finance-special-data涨跌停、炸板、异动、热榜与龙虎榜
hithink-finance-fund公募基金资料、经理、持仓、净值与场内行情
hithink-finance-data本地 DuckDB 初始化、同步、校验、查询与导出
hithink-finance-research基于本地数据的中立研究准备

自动安装是 best-effort：CLI 安装成功不代表每种 Agent 都已找到自己的 Skills 目录。如果安装日志出现 Skills sync incomplete，或 Agent 不能识别上述 Skills，运行：

hithink-finance skills sync --repair --format json

可以查看 CLI 包内的规范 Skill 来源和版本：

hithink-finance skills status --format json
警告

skills status 只能证明 CLI 包含哪些规范 Skills，不能单独证明当前 Agent 已发现或加载它们。最终以 Agent 自身的 Skills 目录和新会话中的实际加载结果为准。

重新打开 Agent 会话​

多数 Agent 只在会话启动时扫描 Skills。CLI 安装或 Skills 修复完成后，新建一个 Agent 会话，再进行首次调用。

在新会话中，可以直接说：

请使用 hithink-finance CLI 查询贵州茅台的最新行情。
先用标的搜索确认唯一 thscode，再查询行情；
使用 JSON 输出，并报告实际执行的命令、数据时间和数据源。

Agent 应按任务选择对应领域 Skill，并在执行前使用当前 CLI 自省契约：

hithink-finance capabilities --format json
hithink-finance schema market.snapshot --format json

随后执行有界真实请求，而不是只读 README 或返回静态示例。

Agent 使用规则​

  • CLI 已可用时，不重复安装或升级。
  • 优先复用 HITHINK_FINANCE_API_KEY 或已有 CLI 系统凭据，不重复向用户索取 Key。
  • 不在命令参数、对话、日志或项目文件中暴露 Key。
  • 机器处理显式使用 --format json，并以退出码 0 且 ok=true 判定 CLI 成功。
  • 不猜测证券代码后缀或命令参数；先做标的消歧，再读取 schema。
  • 全市场、多年或多标的结果必须落盘，对话中只返回路径、行数、时间窗口和摘要。

如何判定 Agent 接入成功​

  1. 新会话能根据任务选择对应 CLI 领域 Skill。
  2. Agent 能运行 hithink-finance 命令，而不是只生成建议命令。
  3. 真实请求的退出码为 0、JSON 中 ok=true，且返回非空数据。
  4. Agent 报告实际使用的命令、数据时间、数据源和未完成的验证。

与统一 hithink-finance Skill 的关系​

CLI 自动安装的 10 个 Skills 专门描述 CLI 命令、参数、输出和本地数据工作流。独立的 Agent Skill 则是 REST API、MCP、CLI 和 Python SDK 之间的统一路由入口。

如果已经确定只使用 CLI，配套的 10 个领域 Skills 就能指导 Agent 完成任务；如果希望 Agent 根据环境在多种接入方式之间自动选择，再安装统一 hithink-finance Skill。

常见问题​

安装后找不到 hithink-finance​

重新打开终端，然后检查 npm 全局安装目录是否在 PATH 中。不要只根据文件夹存在就认为命令已安装。

认证失败​

运行：

hithink-finance auth status --format json

如果统一 Key 已更新，通过 stdin 执行 auth login --api-key-stdin --replace --format json，不需要先 logout。

结果为空​

先检查标的、交易日、报告期和筛选条件。空数据不一定表示服务故障，不要用静态示例数据代替。

下一步​