ultrastiching-cli

UltraStiching 数据 API 的 Node.js 命令行入口。要求 Node.js 22.12 或更高版本。实现 update、doctor、list、info、docs api、call、arrow、ws newsflash、datasets 和 db。本地数据库与 Python SDK 共用 DuckDB 文件，同步与校验行为见下文。14 个预设的数据完整同步仍待服务端验证，现阶段不把单次成功响应当作完整历史。

发行包名为 ultrastiching-cli，安装后的命令为 ultrastiching。统一 Key 变量为 ULTRASTICHING_API_KEY，CLI、Python SDK 和 Claude Code 请求头助手其次读取 ~/.ultrastiching/credentials.env。安装时先下载官网凭据，再比较并设置私有文件与用户环境，供 CLI 和 Codex 原生 HTTP MCP 使用；WorkBuddy 单独在本机 MCP 配置保存直接鉴权头。数据库路径与地址变量保持既有约定。

更新 CLI 与 Skill

ultrastiching update
ultrastiching update --check
ultrastiching update --quiet --skill-dir "已安装 Skill 的完整目录"

update 通过 npm 的 latest 版本检查全局 ultrastiching-cli，有新版时安装检查到的精确版本并读回确认；相同或更高版本不重装、不降级。Skill 从官网 https://www.ultrastiching.com/sdk/skill-latest.json 读取版本、ZIP 地址与 SHA256，校验下载包后完整替换目录。默认检查已存在的 ~/.agents/skills/ultrastiching-skills、~/.codex/skills/ultrastiching-skills 和 ~/.claude/skills/ultrastiching-skills；项目级或其他客户端安装用 --skill-dir 指定实际目录，不创建未安装的 Skill。更新会移除旧 Skill 目录中的本地改动及额外文件。

--check 只检查，输出各组件的已安装版本、目标版本和状态；旧 Skill 没有版本信息时下载校验包并比较内容。发布器为新版 ZIP 的入口注入 metadata.version，以后直接比较版本。--quiet 抑制标准输出和错误输出，结果与原始失败仍记录在现有安装日志中，失败返回退出码 1。CLI 与 Skill 分别报告结果，一个失败仍尝试另一个；安装失败保留准确的暂存／恢复位置。Skill 的每会话首次加载指令使用这条静默命令；重新读取更新后的指令不会再次更新。本命令不需要 API Key。

凭据与统一安装

通过 统一安装指导 安装时，已有 CLI 只检查更新，覆盖前确认。以下新增命令不发起业务请求：

ultrastiching --version
ultrastiching auth status
ultrastiching auth diagnose
ultrastiching auth sync
ultrastiching auth download --ticket-file "私有临时票据文件的完整路径"
ultrastiching auth import --file "下载文件的完整路径"
ultrastiching auth configure
ultrastiching mcp configure-workbuddy --ticket-file "私有临时票据文件的完整路径"
# 主动替换 Key，需确认：ultrastiching auth configure --replace

所有客户端的统一安装流程每次都使用临时安装凭据下载官网文件，已有 ULTRASTICHING_API_KEY 或私有文件也不跳过下载。auth download --ticket-file 使用固定官网入口和 Authorization 请求头，不依赖浏览器 Cookie；票据一小时有效，必须先保存到本机私有文件，不放入命令参数、URL 或日志。auth import --file 也可以导入用户从凭据页面新下载的文件。

下载／导入先比较私有凭据、当前进程和用户持久环境；Windows 直接比较当前用户注册表的原值，macOS 另比较登录会话环境，POSIX 检查已识别的 Shell／environment.d 字面配置。相同位置跳过写入，缺失位置设置，任一位置不同都先停止，不修改现有 Key。命令返回 credential_replacement_required、差异位置和私有恢复路径，不返回 Key。用户确认后运行 auth import --file "保留的下载文件路径" --replace，不重新下载；成功才清理下载副本。成功结果 JSON 的 comparison 报告各位置的 same／missing／different，并报告实际文件和环境写入结果，提示及日志路径写到标准错误输出。

WorkBuddy 使用 mcp configure-workbuddy --ticket-file "私有票据文件路径"，下载后在任何 Key 写入前同时比较用户级 ~/.workbuddy/mcp.json。MCP 以 streamableHttp 直接连接 https://api.ultrastiching.com/mcp，保存实际鉴权头，不依赖环境占位符；同一 Key 的用户环境仍供 CLI 使用。不同 Key 或已有连接变更先确认，确认后用 mcp configure-workbuddy --file "保留的下载文件路径" --replace 继续。保留其他 MCP 和无关选项，相同内容不重写，使用私有权限并读回校验；MCP 与环境同步结果分别记录。--from-file 仅用于用户明确要求的本机 MCP 单独修复，不替代安装的下载比较。

auth status 只报告本地有值及来源，不证明在线鉴权。安装器提供 CLI、MCP 和 Skill 资源后报告凭据步骤待下载比较，不再自动复用本地 Key。独立的 auth sync --from-file 用于已确认来源的环境恢复，也执行比较；不同 Key 需经确认加 --replace。auth configure 是独立的手动隐藏输入入口，统一安装流程不使用它。不要在 Agent 对话中填写 Key；mcp headers 仅供客户端请求头助手消费，其输出不能展示给 Agent。

macOS 确认 zsh 后只写 .zshrc（遵循既有 ZDOTDIR），确认 bash 后只写 .bashrc，并同步当前登录会话；Linux 使用相同的 Shell 默认规则及用户 environment.d，有会话总线时同步服务环境。保留无关 Shell 内容，无法确定位置时报告原始原因，不猜测。POSIX 含 Key 的新文件使用 0600，Windows 使用私有 ACL。更新后重载 MCP，在新终端／新客户端会话验收。

本版为 0.3.0，不再检查或修改 Windows 目录 ACL，保留用户和宿主设置的目录权限，含 Key 的文件单独处理私有权限；沿用 WorkBuddy 直接鉴权、下载后 Key 比较及 Windows 环境同步。输入 API Key 时回显星号，退格同步擦除，实际 Key 不回显。

UltraStiching 自有文件统一使用 ~/.ultrastiching/：正式凭据为 credentials.env，日志为 logs/install-<timestamp>.jsonl，安装私有暂存为 private/，默认数据库为 data/marketdb.duckdb。CLI 每次下载使用独立 private/credential-<随机编号>/，成功清理，失败保留准确恢复路径；Agent 的票据、Skill 下载和解压暂存使用独立 private/install-<run_id>/。新产品不迁移旧目录。

auth 和 mcp configure-workbuddy 命令每次新建独立安装日志，本次诊断追加到同一文件。文件名按机器本地开始时间及其时区生成，例如 ~/.ultrastiching/logs/install-20261008T173000123+0800.jsonl；日志事件时间也使用本地时间并带时区。同毫秒启动追加序号，独占创建，不覆盖已有日志。每次运行开始按文件名中的时间自动清理超过 7 × 24 小时的普通安装日志，不以修改时间判断；清理结果和原始失败记录到本次日志。

安装日志记录运行环境、文件身份、凭据来源／保存与环境同步结果、MCP 保存与读回、下载错误及原始异常链，过滤 API Key、票据和鉴权值。日志路径及 run_id 写入标准错误输出，状态 JSON 的标准输出不变；不自动上传。日志失败不遮盖实际安装结果。常规数据查询不写安装日志。完整安装还包括 Agent 自行执行的步骤，Agent 日志关联各子命令的独立日志，见统一安装指导。

Windows 环境同步通过已有的 ULTRASTICHING_API_KEY 子进程环境传值，不使用标准输入管道，不把 Key 写入命令参数。用户环境写入及读回一致性先完成，再单独广播环境变更，分别记录结果。auth status 仅证明本地凭据存在；用户环境读回成功也不证明已运行的桌面客户端继承了新值，需要在新会话验收。

auth diagnose 在 Windows 对照六种 PowerShell 标准流／传值组合，使用固定假值，不读取真实凭据、不改用户环境、不发起网络请求。遇到 EBUSY 时保留各项原始错误、耗时及标准流配置，诊断某项失败时退出码为 1；其他系统报告不适用。它用于定位进程启动问题，不自动重试或重新下载 Key。

安装与离线发现

从 npm 安装指定版本：

npm install -g [email protected]
ultrastiching --help
ultrastiching list --search 交易日历
ultrastiching info trade_cal
ultrastiching docs api

docs api 只输出随包分发的 离线端点索引 的绝对路径，格式为一行普通文本，不读取凭据或发送请求。通常先用 list/info 查接口，需要浏览总表时才按标题、端点名或分类检索该文件。索引与注册表由同一份目录生成；Skill 按需从 CLI 获取文档路径。

list 和 info 使用随包携带的目录，不需要 API Key，不发送业务请求。也可安装维护者提供的包：npm install -g ./ultrastiching-cli-0.3.0.tgz。源码环境使用下面的安装方式：

cd meridian-cli
npm install
npm link
ultrastiching list --search 交易日历
ultrastiching info trade_cal
ultrastiching call trade_cal --start-date 20260901 --end-date 20260918 --out calendar.json
ultrastiching arrow get_s_stockname --args '{"params":{"code":["600745.SH"]},"fields":["code"]}' --out stockname.arrow
ultrastiching ws newsflash --limit 10 --count 10
ultrastiching datasets
ultrastiching db init
ultrastiching db sync --dataset concept_index_daily --concept-code '<实际概念指数代码>' --limit 100 --start 20260901 --end 20260918
ultrastiching db status
ultrastiching db validate
ultrastiching db repair --dataset concept_index_daily
ultrastiching db sql --query 'SELECT * FROM concept_index_daily LIMIT 5'
ultrastiching db export --table concept_index_daily --path concept.csv

call 按仓库根目录 registry/endpoints.json 中的真实路径和 payload 模板发起请求。参数名称与 Python SDK 方法一致：--start-date 和 --start_date 均映射到 start_date。--args 接收参数名到值的 JSON 对象；同名命令行参数覆盖 --args 中的值。对于请求模板中的 symbols，单个字符串会成为单元素数组，逗号分隔的字符串会拆为数组。其他参数依注册表中的类型解析；复杂值可直接在 --args 中使用 JSON 数组或对象。info 输出完整的字段、来源与验证标记，使用前请核对该端点的实际请求形状。

API Key 优先级为 --key、ULTRASTICHING_API_KEY、~/.ultrastiching/credentials.env。文件回退要求用户所有、权限为 0600 或更严，且 ~/.ultrastiching 不可由其他用户写入。HTTP 地址优先级为 --base-url、MERIDIAN_BASE_URL、https://api.ultrastiching.com。WebSocket 默认使用注册表中的 wss://ws.ultrastiching.com，可用 --ws-base-url 覆盖。doctor 默认只查本地 Key、注册表及 DuckDB 依赖/版本；doctor --probe 在有 Key 时调用一个已登记的示例端点，因而会产生真实 API 请求。

HTTP 结果按服务端 Content-Type 处理：JSON 输出到终端，已知数组超过 500 行时自动写入 meridian-out/；Arrow IPC 原始字节写入 --out 指定文件，未指定时写入 meridian-out/。call 和 arrow 保留原始 IPC，不解码。db sync 使用 apache-arrow 解码表格，并使用 @duckdb/node-api 写入与 Python 相同的数据库结构；WebSocket 使用 ws 在握手时发送 Bearer 头；Node 内建 fetch 负责 HTTP。三者是包的直接依赖。npm pack 时 prepack 从仓库根复制端点及数据集注册表快照到包内；发布前必须先运行生成链并核对快照。

数据库路径优先级为 --db、MERIDIAN_DB、~/.ultrastiching/data/marketdb.duckdb。db sync 保留每次请求的 run/chunk 日志；只有服务端给出的分页元数据与请求和行数逐页吻合，才将该请求范围内的数据写入类型化业务表。Arrow 流没有分页证明时返回 incomplete、写入 0 行，CLI 退出码为 2。Arrow int64 超出 JavaScript 精确整数范围时显式报错并记录 failed，避免改变数值类型或精度。当前同步在提交前把已验证的所有页保存在进程内存中；单个 run 超过 100,000 行或 64 MiB 规范 JSON 时显式失败，单次响应仍可能在检查前占用更多内存。db validate 有问题或 db repair 后仍未完整时也返回退出码 2。repair 仅重试每个数据集最新的失败或未完整请求，复用日志中的原参数。14 个预设的真实服务端分页、限行和键唯一性尚未逐项验证，真实完整历史能力仍需后续核实。

默认不自动重试。HTTP 非 2xx 错误保留状态、服务端 error、X-Meridian-Request-ID 和原始响应体；终端输出仅替换当前 API Key 的字面值。不要把含敏感信息的完整原始错误对象转存到公开日志。离线测试运行 npm test；设置 MERIDIAN_TEST_PYTHON 和可选的 MERIDIAN_TEST_PYTHON39 为装有本仓库 Python SDK 及 DuckDB 的解释器路径，可额外执行跨语言同文件测试。未配置时只跳过跨语言用例。尚未用测试或正式环境 Key 验收真实端点、WebSocket 和服务限制。

环境变量与私有凭据文件任选一种；CLI 不会自动加载项目 .env，.env.example 只是模板。用户在 CLI 执行环境配置现有 ULTRASTICHING_API_KEY，或使用前文说明的私有凭据文件。直接调用业务接口前需要配置有效 Key：

export ULTRASTICHING_API_KEY='<your-api-key>'
ultrastiching call list_tracer_newsflash --limit 20

许可证：Apache-2.0，见本目录 LICENSE。

2026-10-11-r1 目录

本版携带 2026-10-11-r1 批次的 2055 个 HTTP 与 1 个 WebSocket 端点（目录日期按实际 UTC 导出时间为 2026-10-10）。CLI 0.3.0 起使用新名称。升级自 0.2.9 时，214 个名称发生变化且不保留旧别名，例如 plasma_trade_cal 改为 trade_cal，tracer_feed 改为 get_tracer_feed；请同步修改 call／info 的端点名。Data API 名称取公开路径末段，重名补父路径；Tracer 使用 OpenAPI operationId 转 snake_case，例如 ultrastiching call list_tracer_newsflash --limit 20 --important-only false、ultrastiching call get_tracer_report --id 123。--from 对应 GET 时间下界（Python 使用 from_）；请求按公开契约编码路径／查询参数，不发送 GET 请求体。两个 SSE 可用 info 查契约，call 不支持持续流。金融 POST 使用平铺字段，Arrow 包装使用 handler/params/fields。

管理关注主题

ultrastiching call create_tracer_topic --query '跟踪国产芯片的技术与产业进展'
ultrastiching call list_tracer_topics
ultrastiching call follow_tracer_topic --id 'catalog:example'
ultrastiching call unfollow_tracer_topic --id '<关注列表返回的主题 UUID>'

创建并关注主题使用自然语言 query，可选 title、UUIDv4 request_id；202 表示已提交初始化任务。关注主题与取消关注主题使用关注列表返回的字符串 id：本人主题为 UUIDv4，公共主题为 catalog:<slug>。客户端负责路径编码，POST／DELETE 关注操作不带 JSON 请求体。主题管理使用同一个 API Key，不扣内容行数或数据积分，体验用户仍不能创建主题。