echopai

Command-line interface for the EchoPai Open Platform. Programmatic access to A-share stock-market data, news, analyst views, sentiment, financials, concepts, limit-up board, announcements, and digest fan-out over https://api.huishengpai.com, with automatic failover to the mirror domain https://api.echopai.com when the primary is unreachable.

AI-first: JSON envelope on stdout, JSON error envelope on stderr, three-state exit codes — suitable for scripts, CI pipelines, Claude Desktop / Cursor / Claude Code MCP integration, and agent loops.

Install

Two ways — pick whichever fits.

A. npm (Node.js 20+)

npm install -g echopai
echopai --version

Or run without installing:

npx -y echopai market status

B. Standalone binary (no Node required) — 一键安装

自带 Bun runtime，无需 Node。安装器自动判平台（AVX2→baseline / musl / Rosetta）并 强制 sha256 校验：

curl -fsSL https://downloads.huishengpai.com/echopai-cli-releases/install.sh | bash
# 指定版本：
curl -fsSL https://downloads.huishengpai.com/echopai-cli-releases/install.sh | bash -s -- 2.4.0

主域连不上时换镜像域，同一个 R2 桶，内容完全一样（echopai.com 域族在中国大陆的 入境 TLS 按 SNI 被重置，境内请用上面的主域）：

curl -fsSL https://downloads.echopai.com/echopai-cli-releases/install.sh | bash

脚本跑起来之后的下载会在两个域之间自动互备；但脚本本身也托管在 CDN 上， 主域拉不到 install.sh 时只能直接用上面这条镜像域命令。

默认装到 ~/.local/bin/echopai（可用 ECHOPAI_INSTALL_DIR 改）。装到临时目录做验证时 带上 ECHOPAI_SKIP_MCP=1，否则末尾的 MCP 自动注册会把全局 ~/.claude.json 指到那个 一次性路径。Windows 用户手动下载 echopai-windows-x64.exe。平台矩阵、CDN 布局与发布 流程见 docs/CLI_RELEASE_AND_DISTRIBUTION.md。

Auth

# Save key to ~/.config/echopai/config.toml (mode 0600)
echopai login --key eps_live_<lookup>_<secret>

# Or pass per-invocation via env (CI / agent)
ECHOPAI_KEY=eps_live_xxx echopai market status

Get a key at the EchoPai agent console.

Endpoints & failover

Two official API domains back each other up. They front the same origin and return byte-identical responses, so the CLI is free to switch between them:

| Domain | Role | |---|---| | https://api.huishengpai.com | primary (default) — reachable from mainland China | | https://api.echopai.com | mirror — used when the primary is unreachable |

When a request fails at the transport layer (DNS, connection reset, TLS handshake, timeout), hits a Cloudflare per-zone TLS edge error (525 / 526), or hits the EdgeOne rate-limit block page (567), the CLI retries it on the other domain. Those three statuses are per-domain by construction — 525 / 526 can only come from the Cloudflare-fronted mirror, 567 only from the EdgeOne-fronted primary — so switching domains actually gets around them, rather than asking the same question twice. The working domain is remembered in ~/.config/echopai/endpoint_state.json for 24h so a blocked network costs you one failed attempt, not one per command. Failover is bidirectional — if the mirror goes down, requests fall back to the primary.

Every other HTTP error (4xx, and 5xx outside the three above) is not retried on the other domain: same origin, same answer, and a pointless retry would burn credits twice.

echopai doctor                 # per-domain reachability + which one is in use
echopai --debug quote --codes SSE:600519   # prints `! failover <from> → <to>` when it happens

| Env var | Effect | |---|---| | ECHOPAI_BASE_URL | Entry domain. An official domain still gets failover; a custom one (staging / self-hosted) never does — it stays pinned so a network blip can't silently redirect you to production. | | ECHOPAI_NO_FAILOVER=1 | Pin to a single domain. For diagnosing one domain in isolation. | | ECHOPAI_MAX_RETRIES | How many times a 429 rate_limited is retried (default 2, max 5, 0 disables). | | ECHOPAI_QUOTA_COOLDOWN_SEC | Local cooldown after a quota_exceeded (default 600, max 3600, 0 disables). See below. |

Quota cooldown latch

quota_exceeded means your credits are gone — replaying the request cannot succeed until you buy a credit pack or the monthly reset arrives. Retry loops outside the CLI (agents, cron, shell while) don't know that: each iteration is a fresh process, so per-process backoff can't stop them, and hammering the API with deterministic 429s only risks tripping server-side abuse protection for your IP (and everyone sharing it). After one quota_exceeded, the CLI persists a short cooldown (quota_latch.json in the config dir): further data commands fail fast locally — same error code, no request sent — until the cooldown lapses. It re-probes after ~10 minutes, and any successful billable response clears the latch immediately, so a credit-pack purchase is picked up within minutes. whoami/auth commands are never latched — use them to inspect your quota while latched.

Rate-limit backoff

Rate limiting is a per-second window, so a 429 says "try again in about a second", not "you're out of quota". The CLI retries it automatically (default twice), waiting for Retry-After plus jitter. Jitter matters: agents fan out several tool calls at once, they all get the same Retry-After, and without it they'd wake up together and collide again.

Two things are never retried: a 429 the server marks non-retryable — quota / budget exhaustion (quota_exceeded, agent_budget_exhausted) is a definite failure, not a transient one — and any other status. Retrying a 429 is safe on writes too: the gateway rejects before forwarding upstream, so nothing happened, and the Idempotency-Key is reused across attempts either way.

echopai --debug quote --codes SSE:600519   # prints `< 429 rate limited; retry 1/2 in 1032ms`

Highlights

echopai lookup --text 贵州茅台                       # 中文名 → canonical_code
echopai digest --code SSE:600519                     # 一键研究摘要（A 股 6 桶 fan-out）
echopai digest --code HK:00700                        # 港股/中概 digest（仅 views+news）
echopai quote --codes SSE:600519,SZSE:000001         # 1-200 只实时报价
echopai market movers --sort speed --top 20          # 3-min 涨速榜
echopai sentiment overview --date 2026-05-20         # 任意历史日的情绪聚合
echopai concepts alerts                              # 概念异动 (big_move / limit_up_cluster)
echopai limit-up summary                             # 涨停数 / 炸板数 / 连板梯队
echopai financials quote-snapshot --code SSE:600519  # PE/PB/PS/换手率/股息率 14 字段估值快照

echopai init --key <eps_live_...> --all --all-agents # 一条命令全接入：密钥持久化 + skill×2 + 三家项目 MCP + AGENTS.md
echopai init                                         # 最小接入：装 base skill + Claude Code 项目 MCP + AGENTS.md
echopai mcp install --all-agents                     # 把 MCP 写进本机所有 agent 的全局配置
echopai mcp serve                                    # 起 MCP stdio 服务给 Claude/Cursor
echopai skill install                                # 装 agent skill 到 ~/.claude/skills（用法策略+坑）
echopai skill install --all                          # 另装 echopai-analyst（A股盘面研究策略层）

echopai welcome 显示完整命令面板 + 鉴权状态。

Documentation

📖 设计文档（install / auth / persona / MCP / I/O 约定 / pagination / write safety） 与自动生成的完整 endpoint 参数表维护在私有 monorepo 的 docs/（公众暂不可见）； 公开可用的等价物：echopai --help / echopai schema list / echopai skill print （用法方法论 + 每个 verb 的参考随 skill 分发，echopai init 即装）。

📝 CHANGELOG.md —— 版本变更记录。

Self-update

echopai upgrade           # 读取 stable policy，显示当前/最新/最低支持版本
echopai upgrade --check   # 跳过本地 cache，强制刷新 R2 stable policy
echopai upgrade --exec    # 立即按当前安装方式升级

普通命令和 mcp serve 会在写任何结果/协议输出前检查更新（5 分钟 cache，失败同窗退避）； 发现已晋级版本时自动升级，成功后用原参数重跑一次。策略不可达或升级失败但版本仍 ≥ minimum_supported 时放行并提示手动升级；仅低于最低支持版本且过了 published_at + grace_period_hours 宽限窗才返回 cli_update_required 阻断。 Windows standalone 与项目内 node_modules 安装不做自动升级（只提示手动命令）。 可用 ECHOPAI_UPDATE_MODE=notify|off 降级，CI=1 默认关闭。 源码开发时建议显式设置 ECHOPAI_UPDATE_MODE=off。

Development

工具链是 Bun（install / test / build / compile 全用 bun； codegen 仍是 Python）。npm 包产物 dist/bin.js 仍 node ≥20 兼容。

bun install            # 装依赖（bun.lock）
bun run dev -- --help  # 直接跑 TS 源（含 codegen）
bun test               # 跑测试（bun:test）
bun run typecheck      # tsc --noEmit（仅 src）
bun run build          # 产 node 兼容 dist/bin.js（bun build --target=node）
bun run compile        # 产各平台 standalone 二进制到 dist/bin/

源码与反馈

本目录是开发真相源（私有 monorepo 的 cli/——codegen 依赖仓内 OpenAPI 契约）。 公开镜像仓曾于 2026-07 短暂上线，现已转 private，待以后再开源；恢复方式与 历史都还在，见 #936。二进制与安装脚本一律从 R2 分发 （downloads.huishengpai.com / 镜像域 downloads.echopai.com），不依赖 GitHub。

问题反馈：https://app.echopai.com/agent 或工单渠道。

License

MIT