echopai 2.3.0 → 2.5.0

package/README.md

@@ -1,398 +1,113 @@
 # echopai
 
-> **v2.0.0**: npm package renamed from `@echopai/cli` → `echopai` to match
-> the binary name. The scoped package has been unpublished — update your
-> installer to `npm install -g echopai`.
-
-Command-line interface for the EchoPai Open Platform. Programmatic access
-to stock-market data, news, analyst views, sentiment indicators, signals,
-and backtests over `https://api.echopai.com`.
-
-## Features
-
-- **11 curated agent verbs** at the top level (`lookup`, `digest`, `quote`,
-  `views`, `research`, `news`, `sentiment`, `hot`, `chart`, `bars-batch`,
-  `scan`) with task-level defaults, agent-ready outputs, and product-priority
-  encoding (`views` is the PRIMARY research source; `news` is supplementary).
-- **`digest`**: one HTTP call returns views + research-entity performance +
-  quote + sentiment + news for a single security; server-side composite
-  with `meta.partial_failures[]` tolerance; falls back to client-side
-  fan-out if `/v1/digest/{code}` is rolling.
-- **Built-in MCP stdio server** (`echopai mcp serve`) exposing curated verbs
-  to Claude Desktop / Cursor / Claude Code; `tools/list` filtered to the
-  subset your token can actually call.
-- **37 OpenAPI operations as raw mirror** under `echopai raw <noun> <verb>`,
-  auto-generated from `docs/api-contract/openapi.yaml`.
-- **Capability introspection** — `echopai whoami` (token kind / scopes /
-  available verbs / rate limits) + `echopai doctor` (3-state diagnostics).
-- **Write safety** — non-TTY writes refuse without `--yes`
-  (`confirmation_required`); `--dry-run` sends `X-Dry-Run: 1` for ops the
-  server advertises support for; auto `Idempotency-Key` UUIDv4 on every
-  `x-idempotency-required: true` endpoint.
-- **Local trace** — `~/.echopai/trace.ndjson` (50 MB ring buffer);
-  `echopai trace tail` / `trace get <request_id>` for post-hoc inspection.
-- **JSON-first I/O** — JSON envelope on stdout, JSON error on stderr,
-  three-state exit codes (0 / 1 / 2); six output formats
-  (`json` / `ndjson` / `table` / `csv` / `tsv` / `yaml`).
-- **JMESPath filter** — global `--jq <expr>`, `--fields`, `--max-bytes`
-  for shaping responses without piping to `jq`.
-- **Pagination** — `--all` for cursor/offset endpoints, bounded by
-  `--max-pages` / `--max-items`.
-- **Multi-profile config** TOML at `~/.config/echopai/config.toml` (mode 0600).
-- **Shell completion** for bash / zsh / fish.
-
-## Requirements
-
-Node.js 20 or later.
-
-## Installation
+Command-line interface for the [EchoPai Open Platform](https://echopai.com).
+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.echopai.com`.
 
-```bash
-npm install -g echopai
-echopai --version
-```
-
-Or invoke without installation:
-
-```bash
-npx -y echopai market status
-```
-
-## Authentication
+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.
 
-Credentials take the form `eps_live_<lookup>_<secret>` and are issued via the
-EchoPai admin console.
+## Install
 
-Resolution order (highest precedence first):
+Two ways — pick whichever fits.
 
-1. `ECHOPAI_KEY` environment variable
-2. `--profile <name>` flag (on subcommands that accept it)
-3. Default profile in `~/.config/echopai/config.toml`
-
-Persist a credential locally:
+**A. npm (Node.js 20+)**
 
 ```bash
-echopai login --key eps_live_<lookup>_<secret>
-echopai status
+npm install -g echopai
+echopai --version
 ```
 
-Manage multiple profiles:
+Or run without installing:
 
 ```bash
-echopai config profile add prod \
-    --key eps_live_<lookup>_<secret> \
-    --base-url https://api.echopai.com
-echopai config profile switch prod
-echopai config profile list
+npx -y echopai market status
 ```
 
-## AI agent integration (MCP)
+**B. Standalone binary (no Node required) — 一键安装**
 
-The CLI doubles as a Model Context Protocol (MCP) stdio server, exposing
-curated agent verbs as MCP tools to Claude Desktop, Cursor, Claude Code, or
-any MCP-compatible host. The server filters its `tools/list` to the subset
-your token can actually call (intersection of curated-verb scopes with token
-scopes).
-
-Run as an MCP server:
+自带 Bun runtime，无需 Node。安装器自动判平台（AVX2→baseline / musl / Rosetta）并
+强制 sha256 校验：
 
 ```bash
-ECHOPAI_KEY=eps_live_... echopai mcp serve
-```
-
-Claude Desktop / Cursor / Claude Code config (`~/.config/claude/...` or
-equivalent):
-
-```json
-{
-  "mcpServers": {
-    "echopai": {
-      "command": "echopai",
-      "args": ["mcp", "serve"],
-      "env": {
-        "ECHOPAI_KEY": "eps_live_<lookup>_<secret>"
-      }
-    }
-  }
-}
+curl -fsSL https://downloads.echopai.com/echopai-cli-releases/install.sh | bash
+# 指定版本：
+curl -fsSL https://downloads.echopai.com/echopai-cli-releases/install.sh | bash -s -- 2.4.0
 ```
 
-Available MCP tools (subset shown to LLM depends on token scopes):
-
-| Tool | Purpose | Backing API |
-|---|---|---|
-| `lookup` | Resolve Chinese name / code / pinyin → canonical_code | `semantic.find` |
-| `digest` | One-shot research digest: 5 buckets in one call | `digest.get` + fan-out fallback |
-| `quote` | Real-time quote for 1-200 codes | `quote` |
-| `views` | **PRIMARY** research source (analyst views w/ entity attribution) | `views.recent` |
-| `news` | **SUPPLEMENTARY** news / market briefs | `news.search` / `news.feed` |
-| `sentiment` | Aggregate market sentiment | `sentiment.overview` |
-| `hot` | Today's hot-stock leaderboard | `stocks.hot` |
-| `chart` | Single-security K-line (daily / minute) | `bars.daily` / `bars.minute` |
-| `bars_batch` | Batch K-line (≤100 codes × 1yr daily; ≤20 × 7d minute) | `bars.daily-batch` / `bars.minute-batch` |
-| `scan` | Full-market quote snapshot (~5800 securities) | `quote.scan` |
-| `financials_quote_snapshot` | **Headline** valuation snapshot (PE / PB / PS / 换手率 / 股息率 / 量比 14 fields, TDX + Sina 自算) | `financials.quote-snapshot` |
-| `financials_pit` | Point-in-time financial indicators at a given trade_date (anti-future-fn for backtests) | `financials.pit` |
-| `financials_reports` | Last N report-period snapshots (~25 fields × period, filter by Q1/H1/Q3/annual) | `financials.reports` |
-| `financials_series` | Time series of a single financial metric across report periods | `financials.series` |
-
-The agent should prefer `views` over `news` when forming an investment
-opinion (views carries research-entity attribution; news is breadth-only).
-
-The MCP transport sends `X-Client-Channel: mcp` upstream so server-side
-audit / per-channel rate limiting can distinguish MCP traffic from CLI.
-
-## Common usage
-
-```bash
-# Market session state
-echopai market status
-
-# Real-time quotes (CSV codes)
-echopai quote --codes "SSE:600519,SZSE:000001"
-
-# News search with table output
-echopai news search --query "AI" --since-hours 24 --output table
-
-# Daily bars for a security over a date range
-echopai chart --code SSE:600519 --from 2026-01-01 --to 2026-05-01
-
-# Iterate all pages of analyst views (NDJSON one item per line)
-echopai raw views feed --since-days 7 --all | jq '.title'
+默认装到 `~/.local/bin/echopai`（可用 `ECHOPAI_INSTALL_DIR` 改）。Windows 用户手动下载
+`echopai-windows-x64.exe`。平台矩阵、CDN 布局与发布流程见
+[docs/CLI_RELEASE_AND_DISTRIBUTION.md](../docs/CLI_RELEASE_AND_DISTRIBUTION.md)。
 
-# One-shot research digest (server-side composite, 5 buckets, partial-failure tolerant)
-echopai digest --code SSE:600519
-
-# Headline valuation snapshot: 14 fields (PE / PB / PS / 换手率 / 股息率 / 量比 ...)
-echopai financials quote-snapshot --code SSE:600519
-echopai financials quote-snapshot --code SSE:600519 --date 2026-05-13  # historical
-
-# Deeper fundamentals
-echopai financials pit     --code SSE:600519 --date 2024-11-01
-echopai financials reports --code SSE:600519 --kind annual --limit 5
-echopai financials series  --code SSE:600519 --metric roe_simple
-```
-
-## Output formats
+## Auth
 
 ```bash
-echopai news search --query AI --output json     # default; pretty in TTY
-echopai news search --query AI --output ndjson   # one JSON object per line
-echopai news search --query AI --output table    # ASCII table
-echopai news search --query AI --output csv      # RFC-4180
-echopai news search --query AI --output tsv
-echopai news search --query AI --output yaml
-```
-
-## Pagination
-
-Endpoints that declare `x-cli-pagination: cursor|offset` accept `--all`:
+# Save key to ~/.config/echopai/config.toml (mode 0600)
+echopai login --key eps_live_<lookup>_<secret>
 
-```bash
-echopai news feed --all --since-hours 168 | jq '.title'
-echopai news feed --all --max-pages 10 --max-items 500
+# Or pass per-invocation via env (CI / agent)
+ECHOPAI_KEY=eps_live_xxx echopai market status
 ```
 
-## WebSocket streaming
-
-The CLI does **not** expose `/v1/ws/{news,views}` directly. Those upstream
-handlers gate on user-JWT JSON-auth, which is incompatible with the CLI's
-partner static-key bearer-subprotocol model. Partner SDKs that need WS
-should target the endpoints directly (the OpenAPI ops are still public);
-the CLI sticks to HTTP for now.
+Get a key at the [EchoPai admin console](https://console.echopai.com).
 
-## Write safety and dry-run
-
-Curated verbs are all read-only. The raw mirror surfaces a handful of
-writes (e.g. `agent.session-start`); these are gated:
+## Highlights
 
 ```bash
-# In a non-TTY (script / CI / agent), writes refuse without --yes:
-$ echo "" | echopai raw agent session-start --agent-id my-agent
-{"error":{"code":"confirmation_required","message":"Operation agent.session-start is a write (side-effect=write) and stdout is not a TTY. Pass --yes to confirm."}}
-
-# --dry-run sends X-Dry-Run:1 on ops the server advertises support for.
-# Useful for previewing what a write would do without persisting.
-echopai --yes --dry-run raw agent session-start --agent-id my-agent --budget-usd 1.0
-
-# --dry-run on a write op that doesn't advertise support → refused
-$ echopai --yes --dry-run raw agent session-end <session_id>
-{"error":{"code":"dry_run_unsupported","message":"..."}}
-```
+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 字段估值快照
 
-## Channel enforcement
-
-Every outbound HTTP request carries `X-Client-Channel: cli` (or `mcp`
-when running under `echopai mcp serve`). Tokens may carry an
-`allowed_clients` JWT claim restricting which channels the token may use,
-plus `client_overrides` for per-channel `rate_limit_qps` tightening,
-`extra_scopes_deny`, or `read_only` on non-GET methods. Configure these
-on the credential when issuing through admin console.
-
-## Idempotency
-
-For endpoints that declare `x-idempotency-required: true` (for example,
-`agent session-start`), the CLI generates a UUIDv4 `Idempotency-Key` and
-echoes it to stderr so it can be reused on retry:
-
-```text
-$ echopai agent session-start
-[idempotency-key] agent.session-start: 7d8f2c00-3b9a-4f1d-8e2c-9c0a1b2d3e4f
-[idempotency-key] retry: pass --idempotency-key 7d8f2c00-... to dedupe.
-{"data":{"session_id":"sess_..."}}
-```
-
-Provide an explicit key with `--idempotency-key <uuid>` to dedupe at the
-server.
-
-## Exit codes
-
-| Code | Meaning |
-|------|---------|
-| 0    | Success |
-| 1    | User error (4xx, invalid arguments, authentication or scope failure) |
-| 2    | Service error (5xx, network failure, internal error) |
-
-Error envelope (single line on stderr):
-
-```json
-{"error":{"code":"scope_insufficient","message":"...","recovery_hint":"...","request_id":"req_...","http_status":403}}
+echopai mcp serve                                    # 起 MCP stdio 服务给 Claude/Cursor
 ```
 
-In a TTY the same envelope is rendered as a coloured, multi-line message
-with the `recovery_hint` highlighted. Non-TTY environments (CI, pipelines)
-always receive single-line JSON.
+`echopai welcome` 显示完整命令面板 + 鉴权状态。
 
-## Global flags
+## Documentation
 
-| Flag | Description |
-|------|-------------|
-| `--debug` | Print HTTP wire trace to stderr; the bearer token is redacted |
-| `--raw` | Skip envelope unwrapping; emit the raw response body |
-| `--jq <expr>` | JMESPath transform applied to `data` (renamed from `--query` in v2.0 to avoid clashing with subcommand `--query` body params, e.g. `news.search`) |
-| `--fields <a,b,c>` | Keep only listed top-level fields per item |
-| `--max-bytes <n>` | Truncate serialised envelope; sets `meta.truncated=true` |
-| `--yes` | Confirm a write op in non-TTY mode (required for `sideEffect=write` ops) |
-| `--dry-run` | Send `X-Dry-Run: 1` on writes where the server advertises support |
-| `--output <format>` | Override per-command default output format |
+📖 **[docs/CLI.md](https://github.com/evanzhangx/EchoPulse/blob/main/docs/CLI.md)**
+—— install / auth / persona / verb 总览 / MCP / I/O 约定 / pagination /
+write safety / 设计原则 / 版本号约定 全在这里。
 
-Profile and credential overrides are exposed on the relevant subcommands
-(`echopai status --profile <name>`, `echopai login --key ...`); they are
-intentionally not declared as global options to avoid conflicting with
-subcommand parameters of the same name.
-
-## Schema introspection
-
-```bash
-echopai schema list           # one line per command (cliKey, method, path, summary)
-echopai schema get news.search
-echopai schema export         # full surface as NDJSON, including JSON Schemas
-```
-
-## Raw HTTP passthrough
-
-For arbitrary requests (debugging, unmirrored endpoints):
-
-```bash
-echopai raw call GET /v1/some/path -q since_hours=24
-echopai raw call POST /v1/some/path -d '{"key":"value"}'
-```
+📋 **[docs/partner-api/cli-reference.md](https://github.com/evanzhangx/EchoPulse/blob/main/docs/partner-api/cli-reference.md)**
+—— 自动生成的完整 endpoint 参数表，每个 op 的 inputSchema / scopes / 示例 /
+输出 schema。
 
-`echopai api call` is a deprecated alias of `raw call`; it will be removed
-in the next major.
+📝 **[CHANGELOG.md](./CHANGELOG.md)** —— 版本变更记录。
 
-## Shell completion
+## Self-update
 
 ```bash
-echopai completion bash > ~/.local/share/bash-completion/completions/echopai
-echopai completion zsh  > "${fpath[1]}/_echopai"
-echopai completion fish > ~/.config/fish/completions/echopai.fish
+echopai upgrade           # cache 命中即打印 npm i 命令（24h cache）
+echopai upgrade --check   # 强制刷 npm registry
+echopai upgrade --exec    # 真跑 npm i -g echopai@latest
 ```
 
-## Architecture
-
-```
-docs/api-contract/openapi.yaml                  (single source of truth)
-                 │
-                 ▼  scripts/codegen/generate_cli_v2.py
-src/_generated/  (operations + command tree + help text)
-                 │
-                 ▼
-src/runtime/     (invoker, auth, http, envelope, errors, filters,
-                  trace, paginator, verb_runner, verb_cmd, whoami_cache)
-                 │
-                 ▼
-src/tools/       (login, status, config, raw, schema, completion,
-                  whoami, doctor, trace, mcp)
-src/verbs/       (lookup, digest, quote, views, research, news,
-                  sentiment, hot, chart, bars_batch, scan + _spec)
-                 │
-                 ▼
-src/bin.ts
-```
-
-New raw mirror endpoints are added by setting `x-cli-key` (and optionally
-`x-cli-pagination`, `x-cli-output-default`) on the OpenAPI operation; the
-command tree is regenerated automatically. Curated verbs (`src/verbs/`)
-are hand-written task-level wrappers that can fan-out over multiple raw
-ops; each declares a `VerbSpec` shared by CLI and MCP entries.
+CLI 启动时后台 detached 子进程检查 npm registry，下次启动若有新版本会在
+stderr 打一行 dim banner。`ECHOPAI_DISABLE_UPDATE_CHECK=1` / `CI=1` 关掉。
 
 ## Development
 
-```bash
-cd cli
-npm install
-npm run codegen   # regenerate src/_generated/ from the OpenAPI spec
-npm test          # vitest: codegen, runtime, paginator, idempotency, tools
-npx tsx src/bin.ts --help
-
-# Run against the staging environment
-ECHOPAI_BASE_URL=https://staging.echopai.com \
-ECHOPAI_KEY=eps_live_<lookup>_<secret> \
-  npx tsx src/bin.ts news search --query AI --output table
-
-# HTTP wire trace (bearer redacted)
-npx tsx src/bin.ts market status --debug
-```
-
-## Releasing
-
-Two paths are supported. Both are documented in `docs/PLAN_CLI_V2_REWRITE.md`.
-
-### Tag-triggered release (recommended)
-
-After a version bump is merged to `main`, push a tag named `cli-v<version>`:
+工具链是 [Bun](https://bun.sh)（install / test / build / compile 全用 bun；
+codegen 仍是 Python）。npm 包产物 `dist/bin.js` 仍 node ≥20 兼容。
 
 ```bash
-git tag cli-v2.0.0
-git push origin cli-v2.0.0
+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/
 ```
 
-`.github/workflows/release-cli.yml` builds, tests, runs `npm publish
---access public --provenance`, and verifies the new version on the registry.
-The workflow requires a repository secret named `NPM_ACCESS_TOKEN` (an npm
-granular access token with the *Bypass 2FA* flag enabled).
-
-### Local script
-
-For ad-hoc releases without GitHub Actions:
-
-```bash
-bash scripts/publish-cli.sh             # publish the current cli/package.json version
-bash scripts/publish-cli.sh --dry-run   # inspect the tarball without publishing
-```
-
-The script reads `NPM_ACCESS_TOKEN` from `server/.env`, writes it to a
-temporary `.npmrc` (mode 0600), invokes `npm publish`, then deletes the
-file via a shell `trap` (the token never appears on the command line).
-
-## Links
-
-- Platform overview: `https://echopai.com`
-- Partner documentation: `docs/partner-api/`
-- Source: `https://github.com/evanzhangx/EchoPulse/tree/main/cli`
-- Issues: `https://github.com/evanzhangx/EchoPulse/issues`
-
 ## License
 
 MIT