Quickstart

longchina CLI 教程从安装到取数。

longchina CLI 用来查询 A 股数据。你先安装命令行工具，确认连接状态，再查看可用数据集，最后用 query 拉取需要的字段。

开始安装查看查询示例

use cases

什么时候用 longchina。

single stock

查一只股票

用证券代码、日期范围和字段列表取回行情、估值或基础信息。

scriptable

写进脚本

同一条命令可以在终端、shell 脚本、CI 或数据处理流程里复用。

export

导出结果

按场景选择 JSON 或 CSV，把结果交给表格工具、Notebook 或报告流程。

learning path

按这个顺序学。

安装 CLI

安装 native CLI，并把 longchina 放进 PATH。

检查状态

status 返回 API 健康状态、可用数据集和版本策略。

查看数据集

datasets --json 返回字段、过滤条件和更新说明。

跑第一条查询

query 返回结构化 JSON 或 CSV，方便检查和保存。

理解结果

用返回里的 columns、rows、meta 和 usage 核对本次查询。

installation

安装 CLI。

复制下面的命令到终端。安装完成后，先看版本号，再运行 status 确认 CLI 可以连接到 longchina API。

macOS / Linux / WSL2

curl -fsSL https://longchina.vercel.app/install.sh | sh
longchina --version
longchina status --json --skill-version 0.1.3

status

检查运行状态和版本策略。

status 会显示 API 是否可用、当前认证状态、可用数据集数量和版本策略。看到 authenticated: false 不代表安装失败；公开端点仍然可以完成基础检查。

Status check

longchina status --json --skill-version 0.1.3

first query

跑第一条查询。

先用一只股票和一个短日期范围跑通查询。这个例子从 daily-metrics 取估值和市值字段，输出 JSON。

Example query

longchina query daily-metrics \
  --symbol 000001.SZ \
  --start 20260513 \
  --end 20260515 \
  --fields symbol,date,pe,pb,total_market_value \
  --order-by date \
  --format json

cli tutorial

一步一步查询。

日常使用只需要记住三步：先检查状态，再查看数据集，最后提交查询。数据集名使用短横线格式，例如 daily-metrics；CLI 和 API 返回里都会保持同一个公开数据集名。

1. Check

先确认 CLI 能访问 longchina API，并查看当前版本策略。

Check status

longchina status --json --skill-version 0.1.3

2. Discover

查看可用数据集、字段、主键和支持的过滤条件。

List datasets

longchina datasets --json

3. Query

选择一个数据集，加上股票代码、日期范围和字段列表。

Query rows

longchina query daily-metrics \
  --symbol 000001.SZ \
  --fields symbol,date,pe,pb,total_market_value \
  --order-by date \
  --format json

output

理解返回结果。

JSON 输出主要看四块：columns 是字段顺序，rows 是数据行，meta 描述数据集、行数和缓存状态，usage 显示本次查询消耗。

Result metadata

{
  "columns": ["symbol", "date", "pe", "pb", "total_market_value"],
  "rows": [
    {
      "symbol": "000001.SZ",
      "date": "20260515",
      "pe": 5.82,
      "pb": 0.63,
      "total_market_value": 218430000000
    }
  ],
  "meta": {
    "dataset": "daily-metrics",
    "row_count": 3,
    "cached": false
  },
  "usage": {
    "points_charged": 3,
    "point_balance": 997
  }
}

statusstatus 输出里也会显示版本策略。

{
  "version": {
    "cli": {
      "current": "0.1.3",
      "latest": "0.1.3",
      "minimum": "0.1.0",
      "update_required": false
    },
    "skill": {
      "current": "0.1.3",
      "update_required": false
    }
  }
}

cache & auth

缓存、登录和 API 地址。

CLI 会把查询结果缓存在本机，重复查询会更快。缓存按 API 地址和登录身份隔离；需要访问受限数据时，再通过 LONGCHINA_API_KEY 登录。

Cache behavior

longchina query daily-metrics --symbol 000001.SZ --fields pe,pb,total_market_value
longchina query daily-metrics --symbol 000001.SZ --fields pe,pb,total_market_value
longchina cache clear

Optional login

if [ -n "${LONGCHINA_API_KEY:-}" ]; then
  echo "$LONGCHINA_API_KEY" | longchina login --with-token --json
fi
longchina status --json --skill-version 0.1.3

reference

命令和数据集参考。

commandsCLI commands

command	用途	示例
`login`	保存 API Key 或切换 API URL。	`longchina login --with-token --json`
`status`	检查健康状态、认证状态、数据集和版本策略。	`longchina status --json --skill-version 0.1.3`
`datasets`	列出可查询数据集和字段契约。	`longchina datasets --json`
`query`	按数据集契约拉取 A 股数据。	`longchina query daily-metrics --symbol 000001.SZ`
`usage`	查看账户用量和点数余额。	`longchina usage`
`cache clear`	清空本地查询缓存。	`longchina cache clear`

datasets当前常用数据集

dataset	用途	说明
`securities`	证券主数据	代码、名称、交易所
`trading-calendar`	交易日历	开市日、日期范围
`prices`	日线行情	开高低收、成交量、成交额
`daily-metrics`	每日指标	估值、换手、市值
`adjustments`	复权因子	复权计算所需因子

query options常用查询参数

option	说明
`--symbol CODE`	过滤证券代码，支持逗号分隔。
`--start / --end YYYYMMDD`	设置日期范围。
`--fields a,b,c`	选择返回字段。
`--order-by field,-field`	设置排序字段。
`--format json\|csv`	选择 JSON 或 CSV 输出。
`--filter key=value`	补充任意数据集过滤条件，可重复。
`--no-cache`	绕过本地 SQLite 查询缓存。

optional

让 Agent 使用 longchina。

如果你在 Codex、Claude Code 或 Cursor 里做数据分析，可以给它们安装 longchina skills。CLI 仍然是数据入口，skills 只是让 Agent 知道该如何调用它。

recommended

使用安装器

选择你的 Agent 工具，复制生成的安装指令。它会安装数据查询和可视化两个 skills。

manual

直接安装 skills

熟悉 skills CLI 的用户可以直接运行命令。示例使用 Codex 作为目标。

Skills install

npx -y skills add https://longchina.vercel.app --skill longchina-data -a codex -y
npx -y skills add https://longchina.vercel.app --skill stock-research-intake -a codex -y
npx -y skills add https://longchina.vercel.app --skill stock-visualization -a codex -y

workflow

Agent 集成后的工作流。

检查连接和版本策略。longchina status --json --skill-version 0.1.3
查看可用字段和数据集。longchina datasets --json
获取数据，再把结果交给分析或可视化流程。longchina query

visualization

把查询结果变成图表。

安装 stock-visualization 后，Agent 可以把 longchina 查询结果渲染成 K 线、年度表现、对比表或 HTML 报告。你也可以直接把 CLI 输出保存下来，用自己的工具处理。