chaoxin-market-data 0.1.1__tar.gz

chaoxin_market_data-0.1.1/CHANGELOG.md

@@ -0,0 +1,20 @@
+# 变更记录
+
+## 0.1.1 - 2026-09-03
+
+- MCP 和 CLI 输出中的 Unix 纳秒字段保留原整数，并追加带 `+08:00` 和 9 位纳秒精度的 `_shanghai` 可读时间字段；同步补充为后续开发规则。
+- 修正 MCP `trade_history.start` schema，将成交序号起始偏移从日期字符串改为非负整数。
+- 新增 `scripts/package-to-go-api.sh`，可将 MCP wheel、源码包和校验清单同步到 Go-api 前端下载目录。
+
+## 0.1.0 - 2026-09-02
+
+- K 线非 `raw` 结果新增 `KlineChunk.timestamps`，自动把 Unix 毫秒时间戳转换为 UTC+08:00 的 `datetime`；CLI 同步输出可读时间文本。
+- 新增批量技术指标资源 `indicators`，接入 `/api/v1/t/stream/indicators` Protobuf stream，支持批量代码和 MA/EMA/ATR 多周期查询；默认日线常用周期，单个指标周期限制为 `676`，未传复权时默认包装 `qfq`，主动传 `bfq` 才使用不复权。
+- 修正 K 线价格和金额的单位解码：非 `raw` 结果将服务端厘单位还原为元，避免将 `822400` 误读为 `82.24`。
+- 初始版本：提供可独立拆仓的 `chaoxin-market-data` Python SDK、CLI、`SKILL.md` 与参考文档。
+- 默认服务地址为 `https://api.3721.store`；市场数据资源固定使用 Protobuf stream，JSON 仅保留给没有业务数据流的公开探针。
+- 支持统一 JSON envelope、HTTP Protobuf stream、公开 SSE ping 和实时行情 WebSocket 订阅。
+- 新增 `python -m chaoxin_market_data capabilities` 能力发现命令，以“内置命令 + 用途”形式输出 CLI 能力，不暴露底层 API 路径；安装包后的 `chaoxin-market-data capabilities` 为等价别名。
+- 最近交易日窗口改为通过潮信 `workday` stream 分页解析，单次 `count` 最大 30，不再在客户端用自然日估算。
+- 公开能力限定为市场数据只读资源以及 `/health`、公开 ping、公开 SSE ping。
+- 不提供账户、凭据管理、管理员、任务控制、订阅、订单、支付和身份验证接口。

chaoxin_market_data-0.1.1/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 潮信数据贡献者
+
+特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人不受限制地处理软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和销售软件副本的权利，并允许向软件提供者授予上述权利的人这样做，但须符合以下条件：
+
+上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。
+
+软件按“现状”提供，不附带任何形式的明示或默示保证，包括但不限于适销性、特定用途适用性和不侵权保证。在任何情况下，作者或版权持有人均不对因软件或软件的使用或其他交易而产生的任何索赔、损害或其他责任负责，无论该责任是因合同、侵权还是其他原因引起。

chaoxin_market_data-0.1.1/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: chaoxin-market-data
+Version: 0.1.1
+Summary: 潮信数据独立市场数据 SDK
+License: MIT License
+        
+        Copyright (c) 2026 潮信数据贡献者
+        
+        特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人不受限制地处理软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和销售软件副本的权利，并允许向软件提供者授予上述权利的人这样做，但须符合以下条件：
+        
+        上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。
+        
+        软件按“现状”提供，不附带任何形式的明示或默示保证，包括但不限于适销性、特定用途适用性和不侵权保证。在任何情况下，作者或版权持有人均不对因软件或软件的使用或其他交易而产生的任何索赔、损害或其他责任负责，无论该责任是因合同、侵权还是其他原因引起。
+        
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jsonschema<5,>=4.20
+Requires-Dist: mcp<2,>=1.25
+Requires-Dist: protobuf<7,>=6.33.4
+Requires-Dist: websockets<17,>=12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# 潮信数据市场数据 Skill
+
+`chaoxin-market-data` 是面向 Agent 和自动化脚本的潮信数据市场数据只读 Skill，提供独立 Python SDK、CLI 和参考文档。它不只是把潮信接口搬进 Python，而是把股票分析常用的数据读取动作收敛成稳定能力：底层只覆盖当前服务 Swagger 中已经登记的市场数据路径，市场数据固定使用 Protobuf stream，不把客户端扩展成任意 HTTP 代理；上层则补充周期别名、最近交易日窗口和只读数据契约。最近交易日窗口固定通过潮信 `workday` stream 分页解析，不在客户端用自然日估算。
+
+## 能力范围
+
+- 市场数据读取：行情、K 线、批量 MA/EMA/ATR 技术指标、分时、成交、分类、ETF、公告、财务、交易日历、服务健康。
+
+- 股票分析封装：统一 K 线周期别名，并把最近 `5/10/20/30/60/90/120/250` 个交易日窗口包装成内置能力，自动换算 `start_date` 与 `end_date`。
+
+- 传输协议：市场数据使用 HTTP Protobuf stream，公开探针保留 JSON/SSE，实时行情使用 WebSocket 订阅。
+
+- 只读边界：不提供账户、管理员、任务、支付、订单、订阅和身份相关接口。
+
+旧复盘路径不是本 Skill 的默认能力，例如 `/api/v1/review-methodology/*`、`/api/v1/public/stocks/*`。这些旧复盘路径只允许在外部兼容层单独适配；当前包不承诺它们存在，也不会把相近接口伪装成兼容实现。
+
+## 安装与入口
+
+在 Skill 目录下执行：
+
+```bash
+pip install -e .
+python -m chaoxin_market_data health
+```
+
+查看本 Skill 已提供的全部能力（不访问服务，也不需要凭据）：
+
+```bash
+python -m chaoxin_market_data capabilities
+```
+
+该命令输出面向上层 Skill 的全部内置命令、参数签名和用途，覆盖行情、批量行情、实时聚合、历史/实时 K 线、指数、批量 MA/EMA/ATR 技术指标、分时、成交、历史成交、集合竞价、搜索、分类、股票/ETF 目录、F10、财务、公告、除权除息、市场统计、交易日历和健康探针。`kline` 会同时展示“显式日期范围”和“最近交易日窗口”两种用法。它只展示 CLI 命令，不展示底层 API 路径；具体参数可继续执行对应命令的 `--help`。安装包后也可使用等价别名 `chaoxin-market-data capabilities`。
+
+环境变量：
+
+```text
+CHAOXIN_DATA_BASE_URL=https://api.3721.store
+CHAOXIN_DATA_TOKEN=
+CHAOXIN_DATA_API_KEY=
+CHAOXIN_DATA_TIMEOUT=30
+CHAOXIN_DATA_MAX_FRAME_SIZE=67108864
+```
+
+受保护接口必须且只能提供一种凭据；`health`、`public-ping` 和 `public-sse-ping` 允许无凭据调用。
+
+## MCP stdio 服务
+
+安装本包后，可以让支持 MCP 的 AI 客户端通过本地 stdio 进程直接调用全部市场数据能力：
+
+```bash
+chaoxin-market-data-mcp
+```
+
+客户端配置示例：
+
+```json
+{
+  "mcpServers": {
+    "chaoxin-market-data": {
+      "command": "chaoxin-market-data-mcp",
+      "env": {
+        "CHAOXIN_DATA_BASE_URL": "https://api.3721.store",
+        "CHAOXIN_DATA_API_KEY": "从外部安全注入"
+      }
+    }
+  }
+}
+```
+
+## 同步到 Go-api 下载页
+
+MCP 仓库独立维护，发布前在本仓库根目录执行：
+
+```bash
+./scripts/package-to-go-api.sh
+```
+
+脚本会读取 `pyproject.toml` 的版本号，构建 wheel 和源码 tar.gz，并同步到同级 `Go-api/sdk/mcp-dist/<版本>/`，同时生成 `manifest.json` 和 `current.json`。Go-api 的 Docker 构建会把这些文件放到 `/static/sdk/mcp/`，前端下载页据此展示当前版本。重复执行同一版本只会更新该版本的构建产物，不会删除其他版本。
+
+MCP 入口完整暴露 40 个只读 tools：资源登记表中的 38 个市场数据接口，加上 `kline_recent` 和有界 `quote_stream`；能力说明可通过 `chaoxin://capabilities` 读取。所有 tools 都声明只读、幂等提示和统一输出 schema。除 `indicators.latest_count` 默认设为 `1` 以返回最新指标点外，MCP 不注入查询参数默认值、不增加本地结果上限，也不分页；`indicators.latest_count` 最大为 `240`，批量 `codes` 最多 `20` 个，调用方显式传入 `latest_count` 时按该值返回对应数量的最新指标点。`quote_stream` 使用 `max_updates`（默认 20，最大 500）和 `timeout_seconds`（默认 30）控制本次订阅边界，避免单次问答永久占用 stdio 通道。凭据只从环境变量读取，不作为 tool 参数传入。
+
+### 查看 MCP tools 能力
+
+查看 CLI 命令清单（不访问网络）：
+
+```bash
+python -m chaoxin_market_data capabilities
+```
+
+查看 MCP 暴露的全部工具名称、描述和完整输入 schema：
+
+```bash
+python - <<'PY'
+import json
+
+from chaoxin_market_data.mcp_server import get_tool_definitions
+
+print(json.dumps([
+    {
+        "name": tool.name,
+        "description": tool.description,
+        "inputSchema": tool.inputSchema,
+    }
+    for tool in get_tool_definitions()
+], ensure_ascii=False, indent=2))
+PY
+```
+
+MCP 客户端连接后会通过标准 `tools/list` 自动发现这些工具；能力说明也可以读取 `chaoxin://capabilities`。例如用户说“查询贵州茅台最新行情和 60 日 K 线”时，AI 可以先调用 `search` 找到证券代码，再调用 `quote` 和 `kline_recent`；用户说“查询贵州茅台 60 日均价”时，默认按 MA60 处理，应调用 `indicators(code="sh600519", ma_periods=[60], latest_count=1)`，而不是拉取 K 线后自行计算。
+
+## 最小示例
+
+```python
+import asyncio
+
+from chaoxin_market_data import MarketDataClient
+
+
+async def main() -> None:
+    async with MarketDataClient(api_key="请从外部注入") as client:
+        quote_messages = [message async for message in client.quote(code="sh600519")]
+        kline_messages = [message async for message in client.kline_recent(code="sh600519", type="day", days=60)]
+        print(quote_messages[0].payload)
+        print(kline_messages[-1].payload)
+
+
+asyncio.run(main())
+```
+
+```bash
+python -m chaoxin_market_data quote --code sh600519 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data kline --code sh600519 --type day --start-date 2026-01-01 --end-date 2026-09-02 --token "$CHAOXIN_DATA_TOKEN"
+python -m chaoxin_market_data kline --code sh600519 --type day --days 60 --end-date 2026-09-02 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data kline-now --code sh600519 --type 1m --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data minute --code sh600519 --date 2026-09-01 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data call-auction --code sh600519 --date 2026-09-01 --phase all --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data indicators --codes sh600519,sz000001 --type day --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data search --keyword 茅台 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data realtime-rank --category 沪深A股 --count 50 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data f10 --code sz000001 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data workday-range --start 2026-01-01 --end 2026-09-02 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data market-stats --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data health
+```
+
+## 从仓库内旧 SDK 迁移
+
+当前包面向开源复用，目的是把潮信市场数据能力收敛成稳定的只读 Skill 接口。迁移时保持两条原则：
+
+- 上层业务 Skill 只调用 `MarketDataClient`、CLI 或 `resources`，不依赖服务端内部模块和协议实现。
+
+- 同一路由存在 stream 时，`chaoxin-market-data` 只走 stream；JSON 只保留给 `health` 和 `public-ping` 这类没有业务数据流的探针接口。
+
+最小迁移示例：
+
+```python
+# 旧：from sdk.market_quote_sdk.client import ...
+from chaoxin_market_data import MarketDataClient
+
+
+async def load_quotes(api_key: str) -> list[dict]:
+    async with MarketDataClient(api_key=api_key) as client:
+        return [message.payload async for message in client.quote(code="sh600519")]
+```
+
+## 输出约定
+
+- 正常结果输出 UTF-8 JSON 到 stdout。
+
+- stream 命令按行输出 JSON，每行一条业务消息。
+
+- 错误输出到 stderr，结构为 `{"error":{"type":"...","message":"..."}}`。
+
+- 所有对外 JSON 输出中，凡字段名以 `_unix_nano` 结尾，都保留原纳秒整数，并追加同前缀的 `_shanghai` 字段；上海时间文本格式为 `YYYY-MM-DD HH:mm:ss.SSSSSSSSS+08:00`，不替换原字段。
+
+- 资源方法会先在本地校验参数白名单和必需参数，未登记参数会直接报错，不会静默透传到服务端。
+
+- `kline --days` 与 `MarketDataClient.kline_recent(...)` 只开放 `5/10/20/30/60/90/120/250` 八个常用交易日窗口，并且包含截止交易日；窗口通过潮信 `workday` stream 分页解析，单次 `count` 最多 30；若截止日期不是交易日，会自动落到该日期之前最近交易日。
+
+- 报告时必须区分事实与判断，并注明数据时间、查询窗口、transport 和截断状态。
+
+- `indicators` 默认使用 `type=day`。未传入任何指标周期时，使用 MA `5,10,20,60`、EMA `12,26`、ATR `7,14,20`；一旦显式传入任一指标族，只将该指标族转发至上游，不会额外补充其他指标族。MCP 未显式传入 `latest_count` 时返回 1 个最新指标点，最大为 `240`；批量 `codes` 最多为 `20` 个。每个指标周期最大为 `676`，超过时 Python 层直接拒绝。未显式传入 `dividend_type` 时默认包装为 `qfq`，主动传入 `bfq` 才使用不复权数据。带交易所前缀且可识别为指数、债券或基金的代码强制使用 `bfq`。
+
+- 指标摘要的 `ma_deviation_bp`、`ema_deviation_bp` 公式为 `(latest_close - indicator) / latest_close × 10000`，分母统一使用最新收盘价；`atr_vola_bp` 为 `ATR / latest_close × 10000`。
+
+- 行情字段要区分：`QuoteUpdate.last_price` 是最新成交价，`last_close_price` 是前一交易日收盘价；通用 JSON 的 `Kline.Last` 不要误认为当前价，通常对应前收，`Kline.Close` 对应当前交易日收盘值。
+
+- 非 `raw` K 线结果的 `KlineChunk.timestamps` 已自动转换为中国标准时间（UTC+08:00）的 `datetime`，无需上层再次手工换算 Unix 毫秒时间戳；`ts_unix_ms` 仍保留原始值。
+
+- 技术指标接口返回的价格类字段统一按服务端厘（1 元 = 1000 厘）解释；需要换算为元时除以 1000。
+
+- K 线非 `raw` 输出中的 `open`、`high`、`low`、`close`、`amount` 已统一使用元；服务端原始 `*_li` 字段使用厘（元乘以 1000），例如 `close_li=822400` 对应 `close=822.4`。需要查看原始字段时使用 `--raw`。
+
+## 参考文档
+
+- `references/api-map.md`
+
+- `references/data-contract.md`
+
+- `references/streaming.md`
+
+- `references/credentials.md`
+
+- `references/examples.md`
+
+- `docs/chaoxin-market-data-skill/design-spec.md`

chaoxin_market_data-0.1.1/README.md

@@ -0,0 +1,206 @@
+# 潮信数据市场数据 Skill
+
+`chaoxin-market-data` 是面向 Agent 和自动化脚本的潮信数据市场数据只读 Skill，提供独立 Python SDK、CLI 和参考文档。它不只是把潮信接口搬进 Python，而是把股票分析常用的数据读取动作收敛成稳定能力：底层只覆盖当前服务 Swagger 中已经登记的市场数据路径，市场数据固定使用 Protobuf stream，不把客户端扩展成任意 HTTP 代理；上层则补充周期别名、最近交易日窗口和只读数据契约。最近交易日窗口固定通过潮信 `workday` stream 分页解析，不在客户端用自然日估算。
+
+## 能力范围
+
+- 市场数据读取：行情、K 线、批量 MA/EMA/ATR 技术指标、分时、成交、分类、ETF、公告、财务、交易日历、服务健康。
+
+- 股票分析封装：统一 K 线周期别名，并把最近 `5/10/20/30/60/90/120/250` 个交易日窗口包装成内置能力，自动换算 `start_date` 与 `end_date`。
+
+- 传输协议：市场数据使用 HTTP Protobuf stream，公开探针保留 JSON/SSE，实时行情使用 WebSocket 订阅。
+
+- 只读边界：不提供账户、管理员、任务、支付、订单、订阅和身份相关接口。
+
+旧复盘路径不是本 Skill 的默认能力，例如 `/api/v1/review-methodology/*`、`/api/v1/public/stocks/*`。这些旧复盘路径只允许在外部兼容层单独适配；当前包不承诺它们存在，也不会把相近接口伪装成兼容实现。
+
+## 安装与入口
+
+在 Skill 目录下执行：
+
+```bash
+pip install -e .
+python -m chaoxin_market_data health
+```
+
+查看本 Skill 已提供的全部能力（不访问服务，也不需要凭据）：
+
+```bash
+python -m chaoxin_market_data capabilities
+```
+
+该命令输出面向上层 Skill 的全部内置命令、参数签名和用途，覆盖行情、批量行情、实时聚合、历史/实时 K 线、指数、批量 MA/EMA/ATR 技术指标、分时、成交、历史成交、集合竞价、搜索、分类、股票/ETF 目录、F10、财务、公告、除权除息、市场统计、交易日历和健康探针。`kline` 会同时展示“显式日期范围”和“最近交易日窗口”两种用法。它只展示 CLI 命令，不展示底层 API 路径；具体参数可继续执行对应命令的 `--help`。安装包后也可使用等价别名 `chaoxin-market-data capabilities`。
+
+环境变量：
+
+```text
+CHAOXIN_DATA_BASE_URL=https://api.3721.store
+CHAOXIN_DATA_TOKEN=
+CHAOXIN_DATA_API_KEY=
+CHAOXIN_DATA_TIMEOUT=30
+CHAOXIN_DATA_MAX_FRAME_SIZE=67108864
+```
+
+受保护接口必须且只能提供一种凭据；`health`、`public-ping` 和 `public-sse-ping` 允许无凭据调用。
+
+## MCP stdio 服务
+
+安装本包后，可以让支持 MCP 的 AI 客户端通过本地 stdio 进程直接调用全部市场数据能力：
+
+```bash
+chaoxin-market-data-mcp
+```
+
+客户端配置示例：
+
+```json
+{
+  "mcpServers": {
+    "chaoxin-market-data": {
+      "command": "chaoxin-market-data-mcp",
+      "env": {
+        "CHAOXIN_DATA_BASE_URL": "https://api.3721.store",
+        "CHAOXIN_DATA_API_KEY": "从外部安全注入"
+      }
+    }
+  }
+}
+```
+
+## 同步到 Go-api 下载页
+
+MCP 仓库独立维护，发布前在本仓库根目录执行：
+
+```bash
+./scripts/package-to-go-api.sh
+```
+
+脚本会读取 `pyproject.toml` 的版本号，构建 wheel 和源码 tar.gz，并同步到同级 `Go-api/sdk/mcp-dist/<版本>/`，同时生成 `manifest.json` 和 `current.json`。Go-api 的 Docker 构建会把这些文件放到 `/static/sdk/mcp/`，前端下载页据此展示当前版本。重复执行同一版本只会更新该版本的构建产物，不会删除其他版本。
+
+MCP 入口完整暴露 40 个只读 tools：资源登记表中的 38 个市场数据接口，加上 `kline_recent` 和有界 `quote_stream`；能力说明可通过 `chaoxin://capabilities` 读取。所有 tools 都声明只读、幂等提示和统一输出 schema。除 `indicators.latest_count` 默认设为 `1` 以返回最新指标点外，MCP 不注入查询参数默认值、不增加本地结果上限，也不分页；`indicators.latest_count` 最大为 `240`，批量 `codes` 最多 `20` 个，调用方显式传入 `latest_count` 时按该值返回对应数量的最新指标点。`quote_stream` 使用 `max_updates`（默认 20，最大 500）和 `timeout_seconds`（默认 30）控制本次订阅边界，避免单次问答永久占用 stdio 通道。凭据只从环境变量读取，不作为 tool 参数传入。
+
+### 查看 MCP tools 能力
+
+查看 CLI 命令清单（不访问网络）：
+
+```bash
+python -m chaoxin_market_data capabilities
+```
+
+查看 MCP 暴露的全部工具名称、描述和完整输入 schema：
+
+```bash
+python - <<'PY'
+import json
+
+from chaoxin_market_data.mcp_server import get_tool_definitions
+
+print(json.dumps([
+    {
+        "name": tool.name,
+        "description": tool.description,
+        "inputSchema": tool.inputSchema,
+    }
+    for tool in get_tool_definitions()
+], ensure_ascii=False, indent=2))
+PY
+```
+
+MCP 客户端连接后会通过标准 `tools/list` 自动发现这些工具；能力说明也可以读取 `chaoxin://capabilities`。例如用户说“查询贵州茅台最新行情和 60 日 K 线”时，AI 可以先调用 `search` 找到证券代码，再调用 `quote` 和 `kline_recent`；用户说“查询贵州茅台 60 日均价”时，默认按 MA60 处理，应调用 `indicators(code="sh600519", ma_periods=[60], latest_count=1)`，而不是拉取 K 线后自行计算。
+
+## 最小示例
+
+```python
+import asyncio
+
+from chaoxin_market_data import MarketDataClient
+
+
+async def main() -> None:
+    async with MarketDataClient(api_key="请从外部注入") as client:
+        quote_messages = [message async for message in client.quote(code="sh600519")]
+        kline_messages = [message async for message in client.kline_recent(code="sh600519", type="day", days=60)]
+        print(quote_messages[0].payload)
+        print(kline_messages[-1].payload)
+
+
+asyncio.run(main())
+```
+
+```bash
+python -m chaoxin_market_data quote --code sh600519 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data kline --code sh600519 --type day --start-date 2026-01-01 --end-date 2026-09-02 --token "$CHAOXIN_DATA_TOKEN"
+python -m chaoxin_market_data kline --code sh600519 --type day --days 60 --end-date 2026-09-02 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data kline-now --code sh600519 --type 1m --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data minute --code sh600519 --date 2026-09-01 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data call-auction --code sh600519 --date 2026-09-01 --phase all --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data indicators --codes sh600519,sz000001 --type day --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data search --keyword 茅台 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data realtime-rank --category 沪深A股 --count 50 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data f10 --code sz000001 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data workday-range --start 2026-01-01 --end 2026-09-02 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data market-stats --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data health
+```
+
+## 从仓库内旧 SDK 迁移
+
+当前包面向开源复用，目的是把潮信市场数据能力收敛成稳定的只读 Skill 接口。迁移时保持两条原则：
+
+- 上层业务 Skill 只调用 `MarketDataClient`、CLI 或 `resources`，不依赖服务端内部模块和协议实现。
+
+- 同一路由存在 stream 时，`chaoxin-market-data` 只走 stream；JSON 只保留给 `health` 和 `public-ping` 这类没有业务数据流的探针接口。
+
+最小迁移示例：
+
+```python
+# 旧：from sdk.market_quote_sdk.client import ...
+from chaoxin_market_data import MarketDataClient
+
+
+async def load_quotes(api_key: str) -> list[dict]:
+    async with MarketDataClient(api_key=api_key) as client:
+        return [message.payload async for message in client.quote(code="sh600519")]
+```
+
+## 输出约定
+
+- 正常结果输出 UTF-8 JSON 到 stdout。
+
+- stream 命令按行输出 JSON，每行一条业务消息。
+
+- 错误输出到 stderr，结构为 `{"error":{"type":"...","message":"..."}}`。
+
+- 所有对外 JSON 输出中，凡字段名以 `_unix_nano` 结尾，都保留原纳秒整数，并追加同前缀的 `_shanghai` 字段；上海时间文本格式为 `YYYY-MM-DD HH:mm:ss.SSSSSSSSS+08:00`，不替换原字段。
+
+- 资源方法会先在本地校验参数白名单和必需参数，未登记参数会直接报错，不会静默透传到服务端。
+
+- `kline --days` 与 `MarketDataClient.kline_recent(...)` 只开放 `5/10/20/30/60/90/120/250` 八个常用交易日窗口，并且包含截止交易日；窗口通过潮信 `workday` stream 分页解析，单次 `count` 最多 30；若截止日期不是交易日，会自动落到该日期之前最近交易日。
+
+- 报告时必须区分事实与判断，并注明数据时间、查询窗口、transport 和截断状态。
+
+- `indicators` 默认使用 `type=day`。未传入任何指标周期时，使用 MA `5,10,20,60`、EMA `12,26`、ATR `7,14,20`；一旦显式传入任一指标族，只将该指标族转发至上游，不会额外补充其他指标族。MCP 未显式传入 `latest_count` 时返回 1 个最新指标点，最大为 `240`；批量 `codes` 最多为 `20` 个。每个指标周期最大为 `676`，超过时 Python 层直接拒绝。未显式传入 `dividend_type` 时默认包装为 `qfq`，主动传入 `bfq` 才使用不复权数据。带交易所前缀且可识别为指数、债券或基金的代码强制使用 `bfq`。
+
+- 指标摘要的 `ma_deviation_bp`、`ema_deviation_bp` 公式为 `(latest_close - indicator) / latest_close × 10000`，分母统一使用最新收盘价；`atr_vola_bp` 为 `ATR / latest_close × 10000`。
+
+- 行情字段要区分：`QuoteUpdate.last_price` 是最新成交价，`last_close_price` 是前一交易日收盘价；通用 JSON 的 `Kline.Last` 不要误认为当前价，通常对应前收，`Kline.Close` 对应当前交易日收盘值。
+
+- 非 `raw` K 线结果的 `KlineChunk.timestamps` 已自动转换为中国标准时间（UTC+08:00）的 `datetime`，无需上层再次手工换算 Unix 毫秒时间戳；`ts_unix_ms` 仍保留原始值。
+
+- 技术指标接口返回的价格类字段统一按服务端厘（1 元 = 1000 厘）解释；需要换算为元时除以 1000。
+
+- K 线非 `raw` 输出中的 `open`、`high`、`low`、`close`、`amount` 已统一使用元；服务端原始 `*_li` 字段使用厘（元乘以 1000），例如 `close_li=822400` 对应 `close=822.4`。需要查看原始字段时使用 `--raw`。
+
+## 参考文档
+
+- `references/api-map.md`
+
+- `references/data-contract.md`
+
+- `references/streaming.md`
+
+- `references/credentials.md`
+
+- `references/examples.md`
+
+- `docs/chaoxin-market-data-skill/design-spec.md`

chaoxin_market_data-0.1.1/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: chaoxin-market-data
+description: 读取潮信数据市场业务接口；当任务涉及当前或近期股票行情、K 线、均线、趋势、风险和技术指标时使用，凡是存在 stream 的资源只使用 stream，不适用于账户、管理员、任务或支付接口。
+metadata:
+  short-description: 潮信数据市场只读技能
+---
+
+# 潮信数据市场数据 Skill
+
+## 何时使用
+
+- 当上层 Agent 需要读取潮信数据的市场数据时使用本 Skill。
+- 优先处理行情、K 线、批量 MA/EMA/ATR 技术指标、分时、成交、公告、财务、分类、ETF、交易日历和健康探针。
+- 若任务涉及账户、管理员、任务控制、支付、订阅、订单或身份接口，不要使用本 Skill。
+
+## 工作原则
+
+1. 同一业务资源只要存在 stream 路径，就优先使用 stream 并固定只接入 stream，不接入对应 JSON 路径。JSON 只用于 `health`、`public-ping` 这类无 stream 的公开探针；`public-sse-ping` 固定使用 SSE。
+2. 用户要求 N 日均价、N 日均线、MA、EMA 或 ATR 的最新值时，优先调用 `indicators`。例如“贵州茅台 60 日均价”默认按 MA60 处理，使用 `ma_periods=[60]` 和 `latest_count=1`；`latest_count` 最大为 `240`，批量 `codes` 最多为 `20` 个；不要先拉取 K 线再自行计算。
+3. 只有用户明确要求最近 N 个交易日收盘价的算术平均、K 线明细、OHLCV、K 线走势，或指定自定义均值公式时，才使用 `kline --days` 或 `MarketDataClient.kline_recent(...)`。
+4. `kline` 的周期统一使用 `minute1`、`minute5`、`minute15`、`minute30`、`hour`、`day`、`week`、`month`，CLI 同时接受 `1m`、`5m`、`15m`、`30m`、`60m` 别名。
+5. 使用最近交易日窗口时，截止日期默认是当前日期，也可显式传 `--end-date`；窗口必须通过潮信 `workday` stream 分页解析，单次 `count` 最大 30；若截止日不是交易日，自动落到此前最近交易日。
+6. 技术指标请求默认使用 `type=day` 和常用周期 MA `5,10,20,60`、EMA `12,26`、ATR `7,14,20`；任一指标周期最大为 `676`，超过时 Python 层直接拒绝，提示“超过最大计算周期，最大计算周期为 676”。未显式传入 `dividend_type` 时默认包装为 `qfq`，主动传入 `bfq` 才恢复上游不复权默认；指数、债券和基金类标的始终使用 `bfq`。
+7. 技术指标摘要中的 `ma_deviation_bp`、`ema_deviation_bp` 统一按 `(latest_close - indicator) / latest_close × 10000` 计算，分母是最新收盘价，不是 MA/EMA 本身；`atr_vola_bp` 同样按 `ATR / latest_close × 10000` 计算。
+8. 输出时区分事实与判断。事实来自接口返回值；判断必须明确标注为分析结论，不能伪装成原始数据。
+9. 报告数据时间、接收时间以及是否发生截断。若 stream `truncated`、JSON `limit` 或接口窗口导致结果不完整，必须显式说明。
+10. 区分“没有数据”和“取数失败”。异常、鉴权失败、协议错误和空结果不能混为一谈。
+11. 只在市场数据边界内工作，不提供账户、管理员、任务、支付、订阅和订单能力。
+
+## 当前行情强制数据源路由
+
+凡问题包含“现在、今日、当前、最新、收盘价、MA、均线、趋势、风险、技术指标”等实时或近期行情语义：
+
+1. 必须使用本项目 `chaoxin_market_data` Python SDK 或 CLI 获取数据。
+2. 问题包含“N 日均价”“N 日均线”“MA”“EMA”或“ATR”时，使用 `indicators`；未显式要求历史序列时，`latest_count=1`，其最大值为 `240`，`codes` 最多为 `20` 个。
+3. 问题明确要求 N 个交易日收盘价的算术平均、K 线明细或自定义计算公式时，使用 `kline_recent` 或 `kline`。
+4. 用户指定“只使用本项目技能”或“不要网页搜索”时，禁止调用网页搜索、Finance 工具或其他外部行情源。
+5. 本地接口、凭据或网络不可用时，必须报告“未校验”及原因，不得改用外部网页数据补齐。
+6. 分析结论必须注明数据截止日期、查询窗口和数据来源。
+
+### 行情字段语义
+
+- WebSocket `QuoteUpdate.last_price` 是最新成交价，`QuoteUpdate.last_close_price` 是前一交易日收盘价。
+- `quote` / `realtime` 的通用 JSON 中，`Kline.Last` 不要按字面理解为当前价；在当前服务端口径下它通常对应前一交易日收盘值，`Kline.Close` 才是当前交易日收盘值。需要判断实时成交价时优先使用 `QuoteUpdate.last_price`。
+
+### K 线单位
+
+- `raw=True` 返回的 `open_li`、`high_li`、`low_li`、`close_li`、`amount_li` 单位是厘，1 元 = 1000 厘。
+- 非 `raw` 返回的 `KlineChunk.open`、`high`、`low`、`close`、`amount` 已经是元。
+- 非 `raw` 返回的 `KlineChunk.timestamps` 已经把 `ts_unix_ms` 转换为带 `+08:00` 时区的 `datetime`；`ts_unix_ms` 仍保留原始毫秒值。
+- 例如：`close_li=822400` 等于 `822.40` 元。
+- 禁止再次除以 10000；计算均线时直接使用非 `raw` 的元价格字段。
+
+## 默认入口
+
+- Python SDK：`chaoxin_market_data.MarketDataClient`
+- CLI：`python -m chaoxin_market_data`
+
+默认服务地址为 `https://api.3721.store`。受保护接口必须且只能使用一种凭据：
+
+- `CHAOXIN_DATA_TOKEN`
+- `CHAOXIN_DATA_API_KEY`
+
+在调用前查看本 Skill 的完整能力清单：
+
+```bash
+python -m chaoxin_market_data capabilities
+```
+
+该命令只读取本地 CLI 登记表，不访问服务、不需要凭据，返回“命令 + 用途”的文本清单，供上层 Skill 按需选择内置命令。它不展示底层 API 路径。安装包后，`chaoxin-market-data capabilities` 是等价的 console script 别名。
+
+## 常用调用方式
+
+```python
+from chaoxin_market_data import MarketDataClient
+
+
+async with MarketDataClient(token="请从外部注入") as client:
+    messages = [message async for message in client.kline_recent(code="sh600519", type="day", days=60)]
+```
+
+```bash
+python -m chaoxin_market_data quote --code sh600519 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data kline --code sh600519 --type day --start-date 2026-01-01 --end-date 2026-09-02 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data kline --code sh600519 --type day --days 60 --end-date 2026-09-02 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data indicators --code sh600519 --ma-periods 60 --latest-count 1 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data indicators --codes sh600519,sz000001 --type day --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data kline-now --code sh600519 --type 1m --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data minute --code sh600519 --date 2026-09-01 --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data call-auction --code sh600519 --date 2026-09-01 --phase all --api-key "$CHAOXIN_DATA_API_KEY"
+python -m chaoxin_market_data health
+```
+
+## 输出要求
+
+- 正常数据输出 UTF-8 JSON。
+- 错误输出统一为 `{"error": {...}}`。
+- 所有对外 JSON 输出中，只要返回字段名以 `_unix_nano` 结尾的 Unix 纳秒时间戳，就必须保留原整数值，并追加同前缀的 `_shanghai` 字段；时间文本使用 `YYYY-MM-DD HH:mm:ss.SSSSSSSSS+08:00`，不得用上海时间文本替换原纳秒字段。
+- 引用原始 `raw=True` 数据时，保留服务端字段名和单位语义；引用非 `raw` 的 `KlineChunk` 时，价格和金额字段按元解释。
+- 当接口只返回窗口内数据时，在结论中注明窗口、limit、日期范围和截断状态。
+
+## 明确不提供
+
+- 账户与凭据管理：`/auth/*`
+- 管理员接口：`/api/v1/admin/*`
+- 任务控制：`/api/v1/t/tasks*`
+- 支付与订单：`/api/v1/me/orders*`、`/api/v1/t/payment/wechat/notify`
+- 身份验证示例：`/api/v1/private/me`、`/api/v1/service/ping`
+
+## 参考资料
+
+- `README.md`
+- `references/api-map.md`
+- `references/data-contract.md`
+- `references/streaming.md`
+- `references/credentials.md`
+- `references/examples.md`

chaoxin_market_data-0.1.1/chaoxin_market_data/__init__.py

@@ -0,0 +1,33 @@
+"""潮信数据统一异步 SDK。"""
+
+from .client import MarketDataClient
+from .credentials import Credentials
+from .errors import ConfigurationError, ConnectionError, ProtocolError, RemoteError
+from .models import ApiResponse, Ack, ConnectionStatus, KlineChunk, QuoteLevel, QuoteUpdate, SSEEvent, StreamEnd, StreamMessage, StreamRequestMeta
+from .resources import MarketDataResources, RESOURCE_REGISTRY
+from .time_utils import CHINA_TIMEZONE, unix_ms_to_datetime, unix_ms_to_text, unix_ns_to_text
+
+__all__ = [
+    "Ack",
+    "ApiResponse",
+    "ConfigurationError",
+    "ConnectionError",
+    "ConnectionStatus",
+    "Credentials",
+    "CHINA_TIMEZONE",
+    "KlineChunk",
+    "MarketDataClient",
+    "MarketDataResources",
+    "ProtocolError",
+    "QuoteLevel",
+    "QuoteUpdate",
+    "RESOURCE_REGISTRY",
+    "RemoteError",
+    "SSEEvent",
+    "StreamMessage",
+    "StreamEnd",
+    "StreamRequestMeta",
+    "unix_ms_to_datetime",
+    "unix_ms_to_text",
+    "unix_ns_to_text",
+]

chaoxin_market_data-0.1.1/chaoxin_market_data/__main__.py

@@ -0,0 +1,7 @@
+"""潮信数据市场数据包模块入口。"""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())