ashareapi-pi 0.0.0-stage → 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ashareapi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,130 @@
+<div align="center">
+
+<a href="https://ashareapi.com/en/"><img src="https://ashareapi.com/icon-512.png" width="88" height="88" alt="ashareapi"></a>
+
+# ashareapi — Official Pi Package for the A-Share Data API
+
+Let **Pi** ([pi.dev](https://pi.dev)) query China A-share data directly: quotes / candles / **5-level order book** / financials / money flow / dragon-tiger list / sectors / convertible bonds / factor screening / macro — **32 endpoints, and 5 of them need no key**.
+
+One command to install — afterwards Pi knows **which endpoint to call, how to fill the parameters, what units the fields use, and what to do on errors**.
+
+![Pi](https://img.shields.io/badge/Pi-pi.dev-6E56CF)
+![Agent Skills](https://img.shields.io/badge/Agent%20Skills-spec-4D6BFE)
+[![npm](https://img.shields.io/npm/v/ashareapi-pi?label=npm)](https://www.npmjs.com/package/ashareapi-pi)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+**Runs on Pi (pi.dev)**:
+
+![Pi package](https://img.shields.io/badge/pi.dev-package-6E56CF)
+
+[中文](README.md) · **English**
+
+[Website](https://ashareapi.com/en/) · [Docs](https://ashareapi.com/en/docs/) · [Endpoint list](https://ashareapi.com/en/endpoints/) · [MCP](https://ashareapi.com/en/mcp/) · [Agent Skill](https://ashareapi.com/en/skill/)
+
+[Source](https://github.com/ashareapi/ashareapi-skill) · [Issues](https://github.com/ashareapi/ashareapi-skill/issues) · [Changelog](https://ashareapi.com/en/changelog/)
+
+</div>
+
+---
+
+## What is this
+
+An **A-share data Pi package**: once installed, asking Pi "what is 600667 trading at?" makes it call the API and answer with **real market data** instead of guessing.
+
+Inside is an **Agent Skill** (an open standard) — Pi and Claude Code / Codex use **the same skill specification**, so this manual is portable across them. It covers the parameters and field semantics of 32 endpoints, unit conventions (`volume` is in lots / `amount` in yuan / ratios are percentages), date semantics, and common errors plus rate-limit handling.
+
+Under the hood it talks to the REST API at [ashareapi.com](https://ashareapi.com/en/) (`https://api.ashareapi.com/v1/...`) — Pi can just `curl` it; the official SDKs or MCP are equally fine.
+
+---
+
+## Why use it
+
+- **One command to install**: `pi install npm:ashareapi-pi`, then `/reload` — no JSON to hand-edit, no script to run
+- **Free endpoints are genuinely key-free**: `/v1/quote` `/v1/kline` `/v1/hot` `/v1/changedist` `/v1/market-overview` work right after installation
+- **Automatic source failover**: 70 data sources back each other up on the backend; if one has a problem it switches to the next, and **your quota is not charged**
+- **Fixed conventions, no post-processing**: K-lines are always **forward-adjusted (qfq)** (there is no `adjust` parameter), so there is no double-adjustment
+- **No data ≠ failure**: "the market genuinely has no data" (e.g. a suspended stock) is returned separately from "the fetch failed" — the agent will not mistake a suspension for an outage
+- **Written for AI**: it states *when to use which endpoint / how to fill the parameters / what units the fields use / what to do on errors*, so the agent does not call it wrong
+- **Nothing for you to maintain**: the content is generated by a script from the Agent Skill (single source of truth), and a Pi upgrade needs no change here
+
+---
+
+## Install
+
+```bash
+pi install npm:ashareapi-pi
+```
+
+Then `/reload` (or restart Pi). To try it once without touching your config:
+
+```bash
+pi -e npm:ashareapi-pi
+```
+
+Then just ask:
+
+| You ask | Endpoint used |
+|---|---|
+| What is 600667 trading at? | `/v1/quote` |
+| Pull the last 60 daily candles for 600667 | `/v1/kline` |
+| How is the market doing today? | `/v1/market-overview` |
+| What are people watching right now? | `/v1/hot` |
+| What is today's advance/decline distribution? | `/v1/changedist` |
+
+Uninstall:
+
+```bash
+pi remove npm:ashareapi-pi
+```
+
+---
+
+## API key setup
+
+The 5 endpoints above work with **no configuration at all**.
+
+To use the rest (order book / financials / money flow / dragon-tiger list / sectors / screening / macro …) you need a key: [get one here](https://ashareapi.com/en/pricing/) (from ¥9.9).
+
+Put the key in the `ASHAREAPI_KEY` environment variable, or just tell Pi — the manual spells out how to send it:
+
+```bash
+curl -H "Authorization: Bearer ct-your-key" "https://api.ashareapi.com/v1/quote?code=sh600667"
+```
+
+---
+
+## What you can query
+
+**Free (no key)**
+
+Live quotes · candles · attention list · market breadth · market overview
+
+**Requires a key**
+
+Order book · full-field profile · financial statements · money flow · technical indicators · shareholders · events · dragon-tiger list · factor screening · sectors · sector valuation · macro · convertible bonds · ETFs · IPOs · dividends · research digest · symbol search · usage
+
+Field meanings, parameters, and response samples are in the [docs](https://ashareapi.com/en/docs/).
+
+---
+
+## Related
+
+**Official SDKs**: Python `pip install ashareapi` · Node.js / TypeScript `npm install ashareapi`
+
+**MCP server**: `https://api.ashareapi.com/mcp` ([configuration guide](https://ashareapi.com/en/mcp/)) — Pi has **MCP built in**, so a single URL is enough; Claude Code / Codex / Cursor and 15+ other clients work the same way
+
+**Agent Skill** (an endpoint manual for AI agents): <https://ashareapi.com/en/skill/>
+
+**This package's content** is generated by a script from the Agent Skill (single source of truth: <https://github.com/ashareapi/ashareapi-skill>), never maintained by hand.
+
+---
+
+## Version
+
+See [npm](https://www.npmjs.com/package/ashareapi-pi) for the latest version. The content comes from the Agent Skill and **the version tracks the skill**; see the [changelog](https://ashareapi.com/en/changelog/).
+
+---
+
+## License
+
+MIT

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<a href="https://ashareapi.com"><img src="https://ashareapi.com/icon-512.png" width="88" height="88" alt="ashareapi"></a>
+
+# ashareapi — A股数据 API 官方 Pi 包
+
+让 **Pi**（[pi.dev](https://pi.dev)）直接查 A 股数据：行情 / K线 / **五档盘口** / 财务 / 资金 / 龙虎榜 / 板块 / 可转债 / 因子选股 / 宏观 —— **32 个端点，5 个免费无需 Key**。
+
+一条命令装好 —— 装完 Pi 就知道**该调哪个端点、参数怎么填、字段什么单位、错了怎么处理**。
+
+![Pi](https://img.shields.io/badge/Pi-pi.dev-6E56CF)
+![Agent Skills](https://img.shields.io/badge/Agent%20Skills-spec-4D6BFE)
+[![npm](https://img.shields.io/npm/v/ashareapi-pi?label=npm)](https://www.npmjs.com/package/ashareapi-pi)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+**支持 Pi（pi.dev）**：
+
+![Pi package](https://img.shields.io/badge/pi.dev-package-6E56CF)
+
+**中文** · [English](README.en.md)
+
+[官网](https://ashareapi.com) · [文档](https://ashareapi.com/docs/) · [端点清单](https://ashareapi.com/endpoints/) · [MCP 接入](https://ashareapi.com/mcp) · [Agent Skill](https://ashareapi.com/skill)
+
+[GitHub 源码](https://github.com/ashareapi/ashareapi-skill) · [问题反馈 Issues](https://github.com/ashareapi/ashareapi-skill/issues) · [更新日志](https://ashareapi.com/changelog)
+
+</div>
+
+---
+
+## 这是什么
+
+一个 **A股数据 Pi 包**：装上之后，你在 Pi 里问「600667 现在多少钱」，它会自己去调接口拿**真实数据**，而不是编一个数给你。
+
+里面是一份 **Agent Skill**（开放标准）—— Pi 与 Claude Code / Codex 用**同一套 skill 规范**，所以这份说明书在它们之间通用。内容 = 32 个端点的参数与字段语义、单位换算（`volume` 是手 / `amount` 是元 / 比率为百分数）、数据日期语义、常见错误与限流处理。
+
+底层接的是 [ashareapi.com](https://ashareapi.com) 的 REST API（`https://api.ashareapi.com/v1/...`）—— Pi 直接 `curl` 调即可；也可以换成官方 SDK 或 MCP。
+
+---
+
+## 为什么用它
+
+- **一条命令装好**：`pi install npm:ashareapi-pi`，装完 `/reload` 即用，不用配 JSON、不用写脚本
+- **免费端点真的免 Key**：`/v1/quote` `/v1/kline` `/v1/hot` `/v1/changedist` `/v1/market-overview` 这 5 个装上就能调
+- **多源自动切换**：后端 70 个数据源互为备份，某个源出问题会自动换下一个，且**不扣调用次数**
+- **口径固定，不用二次处理**：K 线固定**前复权**（没有 `adjust` 参数），不会二次复权
+- **无数据 ≠ 失败**：停牌这类「市场真没数据」和「取数失败」分开返回 —— Agent 不会把停牌误判成故障
+- **说明书写给 AI 看**：讲清「什么时候用哪个端点 / 参数怎么填 / 字段什么单位 / 错了怎么处理」，Agent 不会调错
+- **不用你维护**：内容由脚本从 Agent Skill 生成（单一事实源），Pi 升级也不用跟着改
+
+---
+
+## 安装
+
+```bash
+pi install npm:ashareapi-pi
+```
+
+装完 `/reload`（或重开 Pi）即可。想先试一次、不写进配置：
+
+```bash
+pi -e npm:ashareapi-pi
+```
+
+然后在对话里直接问：
+
+| 你可以这样问 | 会用到的端点 |
+|---|---|
+| 600667 现在多少钱？ | `/v1/quote` |
+| 帮我拉一下 600667 最近 60 天的日 K | `/v1/kline` |
+| 今天市场什么情况？ | `/v1/market-overview` |
+| 现在大家都在看什么股票？ | `/v1/hot` |
+| 今天涨跌家数怎么分布？ | `/v1/changedist` |
+
+卸载：
+
+```bash
+pi remove npm:ashareapi-pi
+```
+
+---
+
+## 配置 API Key
+
+上面 5 个端点**不用配任何东西**就能用。
+
+要用其余端点（盘口 / 财务 / 资金 / 龙虎榜 / 板块 / 选股 / 宏观…），需要一个 Key：[获取 Key](https://ashareapi.com/pricing)（体验版 ¥9.9 起）。
+
+把 Key 放进环境变量 `ASHAREAPI_KEY`，或者直接告诉 Pi —— 说明书里写明了怎么带上：
+
+```bash
+curl -H "Authorization: Bearer ct-你的Key" "https://api.ashareapi.com/v1/quote?code=sh600667"
+```
+
+---
+
+## 能查什么
+
+**免费（无需 Key）**
+
+实时行情 · K线 · 热搜榜 · 涨跌分布 · 市场总览
+
+**需 Key**
+
+五档盘口 · 全字段画像 · 财务三表 · 资金流 · 技术指标 · 股东 · 事件 · 龙虎榜 · 因子选股 · 板块 · 板块估值 · 宏观 · 可转债 · ETF · 新股 · 分红 · 脱水研报 · 代码搜索 · 用量
+
+字段含义、参数与返回样例见[文档](https://ashareapi.com/docs/)。
+
+---
+
+## 相关
+
+**官方 SDK**：Python `pip install ashareapi` · Node.js / TypeScript `npm install ashareapi`
+
+**MCP 服务器**：`https://api.ashareapi.com/mcp`（[配置说明](https://ashareapi.com/mcp)）—— Pi **内置 MCP**，填一条 URL 就能接；Claude Code / Codex / Cursor 等 19 家客户端同样
+
+**Agent Skill**（给 AI 读的接口说明书）：<https://ashareapi.com/skill>
+
+**本包内容**由脚本从 Agent Skill 生成（单一事实源：<https://github.com/ashareapi/ashareapi-skill>），不手工维护。
+
+---
+
+## 版本
+
+最新版本见 [npm](https://www.npmjs.com/package/ashareapi-pi)。本包内容来自 Agent Skill，**版本号与 skill 一致**；变更见 [ashareapi.com/changelog](https://ashareapi.com/changelog)。
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "ashareapi-pi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.5",
+  "description": "A股数据 API 官方 Pi 包 —— 装上即可查 A 股行情 / K线 / 财务 / 资金 / 龙虎榜（32 个端点说明书，开放标准 Agent Skills）",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "agent-skills",
+    "ashareapi",
+    "a-share",
+    "stock-data"
+  ],
+  "license": "MIT",
+  "homepage": "https://ashareapi.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashareapi/ashareapi-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ashareapi/ashareapi-skill/issues"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "files": [
+    "skills",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/skills/ashareapi/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: ashareapi
+description: 用 ashareapi 获取 A 股数据：行情 / K线 / 财务三表 / 资金流 / 龙虎榜 / 板块 / 可转债 / 因子选股 / 宏观 / 产业链。当用户要查 A 股现价、K线走势、财报（营收净利毛利率）、主力资金、龙虎榜（机构/游资）、涨停、板块轮动、可转债条款（强赎/双低）、ETF、新股打新、指数估值、产业链上下游，或要写调用 A 股数据的代码、接 REST API / 官方 SDK（Python: pip install ashareapi · Node.js: npm install ashareapi）时使用。含 32 个端点的参数与字段语义、单位换算（volume 是手 / amount 是元 / 比率为百分数）、数据日期语义、常见错误与限流处理（匿名 5 次/分，解一次 PoW 挑战提到 60 次/分）。
+license: MIT
+metadata:
+  version: "0.2.5"
+  updated: "2026-10-02"
+  homepage: "https://ashareapi.com"
+  docs: "https://ashareapi.com/docs"
+  endpoints: "https://ashareapi.com/endpoints"
+  changelog: "https://ashareapi.com/changelog"
+---
+
+# ashareapi — A 股数据 API
+
+**32 个 HTTP 端点**（`https://api.ashareapi.com/v1/...`），覆盖行情 / K线 / **五档盘口** / 财务 / 资金 / 龙虎榜 / 板块 / 转债 / 选股 / 宏观 / 产业链。
+**5 个端点无需 Key**（装上就能调），其余需要 Key（¥9.9 起）。另有**官方 SDK**：Python `pip install ashareapi` · Node.js / TypeScript `npm install ashareapi`。
+
+---
+
+## 一、先判断：这个任务要不要 Key
+
+| 任务 | 免费端点够不够 |
+|---|---|
+| 现价 / K线 / 热搜 / 市场总览 / 涨跌分布 | ✅ **够，无需 Key**（先试这个）|
+| 财报 / 资金流 / 龙虎榜 / 板块 / 转债 / 选股 / 宏观 … | ❌ 需要 Key（`Authorization: Bearer <key>`）|
+
+**免费 5 个**：`/v1/quote`（行情）· `/v1/kline`（K线）· `/v1/hot`（热搜）· `/v1/market-overview`（大盘画像）· `/v1/changedist`（涨跌分布）
+**工具端点**（也免 Key）：`/v1/health`（健康检查）· `/v1/challenge`（PoW 提额）
+
+## 二、免费端点：直接调（无需任何鉴权）
+
+```bash
+# 行情：现价 / 开高低 / 成交量 / 换手率
+curl "https://api.ashareapi.com/v1/quote?code=sh600667"
+
+# K线（日/周/月）
+curl "https://api.ashareapi.com/v1/kline?code=sh600667&period=day&count=5"
+
+# 热搜榜
+curl "https://api.ashareapi.com/v1/hot?limit=10"
+```
+
+Python：
+
+```python
+import requests
+
+r = requests.get("https://api.ashareapi.com/v1/quote",
+                 params={"code": "sh600667"}, timeout=10)
+body = r.json()
+if not body.get("ok"):
+    raise RuntimeError(body)          # 上游取数失败（已自动换源，且不扣次数）
+bar = body["data"][0]                 # 最新一根（当日实时）
+print(bar["date"], bar["last"], bar["turnover"])
+```
+
+## 三、带 Key 调用
+
+```bash
+curl -H "Authorization: Bearer ct-你的Key" \
+     "https://api.ashareapi.com/v1/fund?code=sh600667"
+```
+
+Key 从 https://ashareapi.com/pricing 获取。**401 = 没带 Key 调了付费端点**。
+
+## 四、按任务找端点（决策树）
+
+| 用户想要 | 用这个端点 | 备注 |
+|---|---|---|
+| 现价 / 开高低 / 换手 | `/v1/quote` | 免费 |
+| **封单多少 / 买盘卖盘 / 盘口 / 挂单** | **`/v1/orderbook`** | **五档盘口**（买五卖五·秒级快照·**盘中才有意义**·量单位=手）|
+| **估值 / PE / PB / 市值 / 股本 / 涨停价** | **`/v1/snapshot`** | **全字段画像**（**仅A股**·付费·**要多项时比分别调更省次数**）|
+| 走势 / 历史 K线 | `/v1/kline` | 免费；**仅日/周/月，无分钟级**；价格口径固定**前复权**（除权除息日不跳空）——**不要再自己复权**（会二次复权）|
+| 什么股票热门 | `/v1/hot` | 免费 |
+| 大盘怎么样 / 风格轮动 / 估值分位 | `/v1/market-overview` | 免费；`type` 选 summary/trade/interval/technical/margin/valuation/rotation |
+| 涨跌家数 / 涨停家数 / 市场广度 | `/v1/changedist` | 免费；**当期口径**（别用 market-overview?type=updown，那是 T-1）|
+| 财报 / 营收 / 净利润 / 毛利率 | `/v1/finance` | 三表 |
+| 主力资金 / 资金流 / 龙虎榜 / 大宗 / 两融 | **`/v1/fund`** | **一个接口拿全交易面**（优先用）|
+| 龙虎榜分榜（机构 / 游资 / 席位）| `/v1/lhb` | `type=institution/hotmoney/activeseat` |
+| 技术面 / MACD / KDJ / RSI / BOLL | `/v1/technical` | |
+| 谁在持有 / 股东户数 / 机构持仓 | `/v1/shareholder` | |
+| 筹码 / 套牢盘 / 成本分布 | `/v1/chip` | |
+| 板块涨幅榜 / 轮动 | `/v1/sector` | |
+| 某板块贵不贵 / 估值分位 | `/v1/sector-valuation` | `code=pt01801780` 形式 |
+| 可转债 / 强赎 / 双低 / 溢价 | `/v1/bond` | `code=sh113052` 形式 |
+| ETF | `/v1/etf` | `code=sh510300` |
+| 新股 / 打新 | `/v1/ipo` | |
+| 分红送转 | `/v1/dividend` | |
+| 个股事件（42 类）/ 解禁 / 回购 | `/v1/events` | |
+| 个股事件日历（某日有什么事件）| `/v1/calendar` | **不是宏观日历**（宏观用 `/v1/macro`）|
+| 研报 / 机构观点 | `/v1/dehydrated` | `mode=list/detail` |
+| 宏观 / LPR / CPI / GDP | `/v1/macro` | `region=cn/us/...` |
+| 产业链 / 上下游 / 某公司链上位置 | `/v1/industry-chain` | `mode=list/graph/stock` |
+| 筛选股票 / 低估高 ROE | `/v1/screen` | `expr` 多因子交集 或 `preset`（22 个预设）|
+| 只知道名字，要代码 | `/v1/search` | **先搜代码再查数据** |
+| 公司是做什么的 | `/v1/profile` | |
+| 融资融券 | `/v1/margin-trade` | `code` 必填（支持批量）|
+| 大宗交易 | `/v1/block-trade` | |
+| 我的用量 / 额度 | `/v1/usage` | |
+
+**完整参数与返回字段** → 读 `references/endpoints.md`。
+
+## 五、四个必知语义（最常踩的坑）
+
+1. **单位不统一，先看清**
+   - `volume` 是**手**（×100 = 股）· `amount` 是**元**（不是万元）
+   - 比率字段是**百分数**：`instBuyRate: 20` 表示 **20%**（不是 0.2）
+   - 金额有时以**字符串**返回（`"135160431.2"`）→ **先 `float()` 再算**，否则 `+` 会拼字符串
+
+2. **数据日期语义**：休市日**不会**变成"今天"。看返回里的 `date` 字段判断数据属于哪个交易日（`quote` 的最新一根就是当日实时）。
+
+3. **返回结构：`data` 是主载荷，形状有 4 种**（统一信封 `{ok, endpoint, tier, elapsed_ms, source, data}`）
+   - `data` 可能是：**对象数组**（多数端点）/ **表列表**（`finance`）/ **多段结构**（`shareholder`·`calendar`）/ **Markdown 文本**（`bond`·`sector` 等 9 个）
+   - ⚠️ **`structured` / `tables` 是【条件字段】—— 不是每个端点都有**：**只有 `data` 是 Markdown 时才附**
+     ⇒ 代码里**一律写 `body.get("structured")`**；写 `body["structured"]` 在 `quote`/`kline`/`finance` 上会 **KeyError**
+   - ⚠️ `/v1/health` · `/v1/challenge` · `/v1/usage` 信封**没有 `data`**
+   - 四种形状怎么判别 + 通吃写法 → `references/endpoints.md` §返回形态
+
+4. **`ok:false` 不等于"我们写错了"**：那是**上游取数失败**（我们已自动换源，**不扣调用次数**）→ 重试一次通常就好。**空结果**（如当天没大宗交易）与"失败"是两件事。
+
+## 六、错误与限流
+
+| 现象 | 含义 | 怎么办 |
+|---|---|---|
+| **401** | 没带 Key 调了付费端点 | 拿 Key，或改用 5 个免费端点 |
+| **429** | 超出档位频率（匿名 5 次/分）| 降频；或**解一次 PoW 挑战提到 60 次/分**（见下）；或升级档位 |
+| **`ok:false`** | 上游取数失败（已自动换源）| **不扣次数**，重试一次 |
+| **200 但 data 为空** | 当前确实没有这类数据（如当天无大宗交易）| 换条件 / 稍后再试，**不是故障** |
+| **5xx** | 重试耗尽 | 稍后再试 |
+
+**匿名提额（PoW）**：
+
+```bash
+# 1) 拿挑战
+curl "https://api.ashareapi.com/v1/challenge"
+# → {challenge, difficulty, expires_in, how_to}
+# 2) 算 nonce（sha256(challenge.nonce) 前 difficulty 位为 0），然后：
+curl -H "X-PoW: <challenge>.<nonce>" "https://api.ashareapi.com/v1/quote?code=sh600667"
+```
+
+详细错误语义 → 读 `references/errors.md`。
+
+## 七、要写代码？用官方 SDK（Python / Node.js）
+
+**Python**：
+
+```bash
+pip install ashareapi            # 基础（返回 list[dict]）
+pip install "ashareapi[pandas]"  # 加 DataFrame 支持（推荐）
+```
+
+```python
+from ashareapi import AShareAPI
+
+cli = AShareAPI()                  # 免费端点无需 Key
+df = cli.quote("sh600667")         # → DataFrame
+print(df[["date", "last", "turnover"]])
+
+cli = AShareAPI("ct-你的Key")      # 付费端点
+print(cli.fund("sh600667"))        # 资金流 + 龙虎榜 + 大宗 + 两融
+print(cli.screen(preset="low_pe", limit=10))
+```
+
+**Node.js / TypeScript**：
+
+```bash
+npm install ashareapi            # 零运行时依赖（原生 fetch，需 Node ≥ 18）
+```
+
+```ts
+import { AShareAPI } from "ashareapi";
+
+const cli = new AShareAPI();                 // 免费端点无需 Key
+const bars = await cli.quote("sh600667");    // → 对象数组
+console.log(bars[0].last);
+
+const paid = new AShareAPI({ apiKey: "ct-你的Key" });
+console.log(await paid.screen("", "low_pe", 10, "ROETTM"));
+```
+
+> 两个 SDK **同 32 个方法 / 同 5 类异常 / 同重试策略**；差异只是语言惯例：
+> Python 用 `snake_case` 且返回 DataFrame，Node 用 `camelCase`（也认 `snake_case` 别名）且**全部返回 Promise**。
+
+**代码格式随便写**：`sh600667` / `600667.SH` / `600667` 都认（自动归一化）。
+**32 个端点 = 32 个方法**（`/v1/margin-trade` → Python `margin_trade()` / Node `marginTrade()`）。
+
+完整用法与 5 类异常 → 读 `references/sdk.md`。
+
+## 八、详细参考（按需读取，不要一次全读）
+
+| 文件 | 什么时候读 |
+|---|---|
+| [references/endpoints.md](references/endpoints.md) | 要确认某端点的**完整参数 / 返回字段** |
+| [references/fields.md](references/fields.md) | 要**算数**（单位换算、字段含义、字符串数字）|
+| [references/errors.md](references/errors.md) | 遇到 401/429/ok:false/空结果，或要处理限流 |
+| [references/sdk.md](references/sdk.md) | 用户要**写 Python / Node.js 代码**或问 SDK |
+
+---
+
+**边界（诚实）**：
+- K 线**只提供日/周/月**，**没有分钟级**
+- 新闻/公告**全文**不在 API 范围（有 `dehydrated` 研报摘要、`events` 事件标签、`calendar` 事件日历）
+- 数据仅供研究参考，**不构成投资建议** —— 本 skill 只讲怎么取数与计算，不给买卖建议
+
+---
+
+## 九、本 skill 版本
+
+**当前版本：`0.2.4`（2026-09-30）**
+
+### 怎么知道该更新
+
+本 skill 是**随 API 演进的快照** —— 每次新增端点/字段，`references/` 里的清单会同步但**你手上装的可能还是旧版**。判断方法：
+
+| 检查 | 说明 |
+|---|---|
+| `metadata.version` | 看本文件 frontmatter 的版本号 |
+| **端点总数** | 对比现实：**当前 32 个**（`endpoints.md` 标题也是这个数）|
+| **MCP 工具数** | 当前 **24 个**（`list_tools` 返回数量）|
+
+**任一项对不上 → 你装的是旧版。**
+
+### 怎么更新
+
+1. 重新下载：**https://ashareapi.com/skill**（页面有 zip 下载）
+2. 解压覆盖到你的 skills 目录（`.claude/skills/` · `.agents/skills/` · `.opencode/skills/` 等）
+3. 重启客户端
+
+> ⚠️ **API 本身不需要更新** —— 端点永远是最新的（服务端演进）；需要更新的是**这份说明**（否则你可能不知道新端点存在）。
+
+### 版本记录
+
+| 版本 | 日期 | 变化 |
+|---|---|---|
+| `0.2.4` | 2026-09-30 | **文档表述统一**：全文改为面向使用者的表述；**端点 / 字段 / 口径无任何变化** |
+| `0.2.3` | 2026-09-28 | **补 K 线价格口径**：`/v1/kline` 明确「口径**固定为前复权**（除权除息日不跳空）、**无 `adjust` 参数**、**不要再自己复权**（会二次复权）」（`SKILL.md` 速查表 + `references/endpoints.md` 同步）|
+| `0.2.2` | 2026-09-26 | 换手率字段统一为 **`turnover`**（%）—— 与 `/v1/snapshot` 同名同值（`references/fields.md` 字段表 · `endpoints.md` · `sdk.md` 示例同步）|
+| `0.2.1` | 2026-09-26 | **完善返回结构文档**：明确 `structured`/`tables` 是**条件字段**（仅 `data` 为 Markdown 时才附）· 新增「`data` 四种形状」速查表 + 通吃写法 · `snapshot` 字段数 → **35** · 补 `finance` 表列表 / `shareholder`·`calendar` 多段结构 / `fund` 扁平 dict · 补 `profile` 字段说明 |
+| `0.2.0` | 2026-09-23 | 新增 `/v1/snapshot`（全字段画像）· `/v1/orderbook`（五档盘口）· 端点数 30→32 · MCP 工具 22→24 · 补字段单位与"计费=次数"说明 |
+| `0.1.0` | 2026-09-20 | 首个版本（30 个端点 · 22 个 MCP 工具）|
+
+**完整更新日志（含字段级变更）→ https://ashareapi.com/changelog**
+

package/skills/ashareapi/references/endpoints.md

@@ -0,0 +1,127 @@
+# 端点清单（32 个）
+
+- **统一前缀**：`https://api.ashareapi.com/v1`
+- **统一信封**：`{ ok, endpoint, tier, elapsed_ms, source, data }` —— 只有这 6 个键
+  - ⚠️ **`structured` / `tables` 是【条件字段】，不是每个端点都有**：**只有 `data` 是 Markdown 文本时才附**
+    （`market-overview` · `changedist` · `lhb` · `sector` · `sector-valuation` · `bond` · `etf` · `screen` · `macro`）。
+    **其余端点没有这两个键** → `body["structured"]` 会 **KeyError**，**一律用 `body.get("structured")`**。
+  - ⚠️ **3 个端点信封不同**（都**没有 `data`**）：`/v1/health` = `{ok, uptime_s, data_ready, tiers}` ·
+    `/v1/challenge` = `{challenge, difficulty, expires_in, how_to}` · `/v1/usage` = `{ok, day, calls_today, tier, total_calls, total_quota, total_left, daily_quota, per_min}`
+- **参数带 `*` = 必填**
+- **实时规格**：`GET https://api.ashareapi.com/openapi.json`（本文件据其生成）
+
+---
+
+## 一、免费端点（无需 Key，5 个数据端点 + 2 个工具端点）
+
+| 端点 | 参数 | 返回要点 |
+|---|---|---|
+| `/v1/quote` | `code*` | 实时行情：`last` 现价 / `open/high/low` / `volume`（手）/ `amount`（元）/ `turnover` 换手率% / `date`。**最新一根 = 当日实时** |
+| `/v1/kline` | `code*` · `period`(day/week/month) · `count` | OHLCV 历史 K 线。**只有日/周/月，无分钟级**。价格口径**固定为前复权**（除权除息日不跳空；无 `adjust` 参数）—— **不要再自己复权**（会二次复权）|
+| `/v1/hot` | `limit`（默认 30，**上限 50**）| 全市场热搜榜（A股/美股/ETF）：关注度排名 + 涨跌幅 |
+| `/v1/market-overview` | `type`(summary/trade/interval/technical/margin/**valuation**/**rotation**) | 大盘画像。`valuation` = 中证全指 PE/PB/PS **历史百分位**；`rotation` = 风格轮动（大小盘/成长价值）。⚠️ `type=updown` 是 **T-1 口径**，涨跌家数请用 `/v1/changedist` |
+| `/v1/changedist` | 无 | **当期**涨跌家数 / 涨跌停家数 / 停牌 / 成交额 / 区间分布 —— **市场广度推荐入口** |
+| `/v1/health` | 无 | `data_ready=true` 表示数据通道可用（不含内部实现细节）|
+| `/v1/challenge` | `difficulty` | PoW 挑战（匿名提额用）。解 nonce 后带 `X-PoW: <challenge>.<nonce>`，匿名配额 5 → 60 次/分 |
+
+---
+
+## 二、行情与技术（需 Key）
+
+| 端点 | 参数 | 返回要点 |
+|---|---|---|
+| `/v1/technical` | `code*` | MA / MACD / KDJ / RSI / BOLL 全家桶 |
+| `/v1/chip` | `code*` | 筹码分布与持仓成本（获利盘 / 套牢盘比例）|
+| `/v1/orderbook` | `code*` | **五档盘口（order book）**：买一~买五 / 卖一~卖五的**价 + 挂单量（手）**。字段：`b1_p`/`b1_v`~`b5_p`/`b5_v`（买档）、`a1_p`/`a1_v`~`a5_p`/`a5_v`（卖档）。⚠️ **秒级快照（10 秒缓存）· 盘中才有意义**；量单位是**手**（×100 = 股）；**跌停买档全 0 / 涨停卖档全 0**（正常）|
+| `/v1/snapshot` | `code*` | **全字段行情画像（35 字段）**：`code/name/sec_type/currency/status` + 价格（`price/prev_close/open/high/low/avg_price/change/change_pct/amplitude/speed`）+ 量（`volume/amount/turnover/outer_vol/inner_vol/volume_ratio`）+ 估值（`pe_ttm/pe_dynamic/pe_static/pb`）+ 市值股本（`float_market_cap/total_market_cap/float_shares/total_shares`）+ 涨跌停（`limit_up/limit_down`）+ 盘口（`bid/ask/bid_ask_diff`）+ `time`。⚠️ **与 quote 分工**：quote 轻（8 字段）免费 / snapshot 全（**35 字段**）付费，**只要现价用 quote 更轻**；✅ **计费=次数**：要估值+市值+股本+涨停价**多项**时，本端点 1 次搞定——比分别调 quote/valuation/orderbook **更省次数**。⚠️ **仅 A 股**（港股/美股字段布局不同，用 quote）——**传其他市场返回空，不返回错数据**|
+| `/v1/search` | `q*` | 按名称/代码搜股票、基金、板块 —— **用户只给名称时先搜代码** |
+| `/v1/profile` | `code*` | 公司简况：上市日期 / 主营业务 / 所属行业 |
+
+## 三、财务
+
+| 端点 | 参数 | 返回要点 |
+|---|---|---|
+| `/v1/finance` | `code*` · `num`（期数）| 利润表 / 资产负债表 / 现金流量表（多期）。营收 / 净利 / 毛利率 / 负债。⚠️ **`data` 是【表列表】`[[行...], [行...], ...]`**（外层=表，内层=行）→ **先按表索引再按行**：`data[0][0]["..."]` |
+| `/v1/dividend` | `code*` · `years` | 分红送转历史：每股分红 / 送股 / 除权日 |
+| `/v1/shareholder` | `code*` | 十大股东 / **股东户数（筹码集中度）** / 机构持仓。⚠️ **`data` 是【多段结构】**：`{code, market, tables: [{title, slug, rows}], data: {slug: rows}}`，slug = `top10_holders` / `top10_float_holders` / `holder_count` |
+
+## 四、资金与交易（核心）
+
+| 端点 | 参数 | 返回要点 |
+|---|---|---|
+| **`/v1/fund`** | `code*` | ⭐ **一接口拿全交易面**：主力资金（当日/5/10/20 日净流入 + 全市场排名）+ 龙虎榜（上榜原因 / 买卖总额 / **营业部明细**）+ 大宗交易 + 融资融券。**问"主力资金/资金流/龙虎榜"优先用它**。⚠️ `data` 是**扁平 dict**（不是多段）：`{date, close, main_net, main_net_5d/10d/20d, main_rank, lhb, lhb_details, block_trades, margin, industry_rank}` |
+| `/v1/lhb` | `type`(institution/hotmoney/activeseat) · `date` | 龙虎榜**分榜**：机构榜（机构数 / 机构买入 / 净买）· 游资榜 · 活跃席位榜 |
+| `/v1/margin-trade` | `code`（**必填**，支持 `sh600667,sz000651` 批量）· `date` | 融资余额 / 买入 / 偿还 / 融券。未披露日上游会给出原因 |
+| `/v1/block-trade` | `code` · `date` | 大宗交易：成交价 / 折溢价 / 量 / 买卖方营业部 |
+| `/v1/events` | `code*` | 个股事件总览：**42 类**（大宗 / 龙虎榜 / 回购 / 定增 / 分红 / 业绩 / 解禁 …）|
+| `/v1/calendar` | `date` · `limit` | **个股**事件日历（分红派息 / 解禁 / 财报披露排期）。**不是宏观日历**（宏观用 `/v1/macro`）。⚠️ **`data` 是【多段结构】**：`{tables: [{title, slug, rows}], data: {slug: rows}}`，**按事件类型分段保序**；slug 取值 = `financial_report` / `dividend` / `ipo` / `meeting` / `lockup_release` / `rights_issue` |
+
+## 五、板块与产业链
+
+| 端点 | 参数 | 返回要点 |
+|---|---|---|
+| `/v1/sector` | 无 | 行业 / 概念 / 地域板块涨幅榜 + 领涨股 |
+| `/v1/sector-valuation` | `code*`（`pt01801780` 形式）| 申万板块 PE/PB/PS/PCF + 股息率 + **历史百分位** |
+| `/v1/industry-chain` | `mode`(list/graph/stock) · `topic` · `code` | `list` = **183 个主题** · `graph&topic=X` = 图谱（关联个股 + 节点 + 上中下游）· `stock&code=X` = 该股所属链（主题/节点/位置/**关联度**/业务描述）|
+
+## 六、可转债 / ETF / 新股
+
+| 端点 | 参数 | 返回要点 |
+|---|---|---|
+| `/v1/bond` | `code*`（`sh113052`）| 转债完整条款：溢价率 / 转股价值 / **双低值** / **强赎触发价** / 回售触发价 / 转股价 / 正股 / 到期日 / 信用评级 |
+| `/v1/etf` | `code*`（`sh510300`）| ETF 行情 / 规模 / 溢折率 / 资金流 |
+| `/v1/ipo` | `days` | 新股发行 / 申购 / 中签 / 上市日历 |
+
+## 七、选股与宏观
+
+| 端点 | 参数 | 返回要点 |
+|---|---|---|
+| `/v1/screen` | `expr` 或 `preset` · `limit` · `orderby` · `desc` · `market` | **因子选股**。`expr` 多因子交集：`intersect([PE_TTM > 0, PE_TTM < 20, ROETTM > 15])`；`preset` 22 个官方预设（**大小写/下划线不敏感**：`low_pe` = `LowPE`）。常用因子：PE_TTM / PB / PS_TTM / TotalMV / DividendRatioTTM（估值）· ROE / ROETTM / ROIC / GrossIncomeRatioTTM（盈利）· OperatingRevenueGrowRate / NPParentCompanyYOY（成长）· CurrentRatio / DebtAssetsRatio（负债）· NetOperateCashFlowTTM（现金流）|
+| `/v1/macro` | `region`(cn/us/jp/eu/hk) · `names` | 宏观：GDP / CPI / PMI / LPR / 国债收益率 / 财政 |
+| `/v1/dehydrated` | `mode`(list/detail) · `symbol` · `limit` | 券商研报脱水摘要 |
+| `/v1/usage` | 无 | 当前 Key 的今日调用次数 / 剩余总量 / 到期时间 / 限流额度 |
+
+---
+
+## 返回形态：`data` 有四种形状（32 端点全量）
+
+**程序化处理前必须先判形状** —— `data` **不是**永远同一个类型，写死 `data[0]["x"]` 会在 `finance` / `calendar` 上炸。
+
+| 形状 | 长这样 | 哪些端点 | 怎么读 |
+|---|---|---|---|
+| **① 对象数组** | `[{"col": val}, ...]` | 多数：`quote` `kline` `hot` `technical` `chip` `orderbook` `snapshot` `profile` `dividend` `margin-trade` `ipo` | `for row in data: row["field"]` |
+| **② 表列表** | `[[行...], [行...]]`（外层=表，内层=行）| `finance`（利润表 / 资产负债表 / 现金流量表）| `data[表号][行号]["字段"]` —— **先按表索引** |
+| **③ 多段结构** | `{"tables": [{"title","slug","rows"}], "data": {"<slug>": rows}}` | `shareholder`（另带 `code`/`market`）· `calendar` | `data["tables"]` 保序分段；`data["data"]["<slug>"]` 便捷索引 |
+| **④ Markdown 字符串** | `"\| 列 \| 列 \|\n..."` | 9 个（见信封说明）+ `events` · `dehydrated` | 优先读同响应的 `structured` / `tables`（**若存在**）；不存在才正则解析 |
+
+**特殊 dict（不属于上面四类）**：`fund` = 扁平 `{date, close, main_net, main_net_5d/10d/20d, main_rank, lhb, lhb_details, block_trades, margin, industry_rank}` ·
+`industry-chain?mode=list` = `{mode, topics}`。
+
+**空结果的三种表现**（都**不是**故障，`ok:true`）：`data = []`（如 `block-trade` 当天无成交）· `data` 是含"数据为空"的 Markdown（`events`）· 多段结构里 `tables = []`。
+
+**推荐写法（四种形状通吃）**：
+
+```python
+def rows_of(body):
+    d = body.get("data")
+    if isinstance(d, dict) and "tables" in d:      # ③ 多段结构
+        return [r for t in d["tables"] for r in (t.get("rows") or [])]
+    if isinstance(d, list) and d and isinstance(d[0], list):   # ② 表列表
+        return d[0]                                 # 或按表号取
+    return body.get("structured") or d              # ① / ④（④ 优先用 structured）
+```
+
+---
+
+## 代码格式（`code` 参数）
+
+| 写法 | 说明 |
+|---|---|
+| `sh600667` | 沪市（sh）· 深市（sz）· 北交所（bj）· 港股（hk）· 美股（us）|
+| `600667.SH` | 后缀写法 |
+| `600667` | 纯 6 位（按首位推断：5/6→sh · 0/3→sz · 4/8→bj）|
+| `pt01801780` | **板块**代码（申万板块，用于 `sector-valuation`）|
+| `sh113052` | **可转债**代码 |
+| `sh510300` | **ETF** 代码 |
+
+**官方 SDK 会自动归一化三种股票写法**；直接调 HTTP 时建议统一用 `sh600667` 形式。

package/skills/ashareapi/references/errors.md

@@ -0,0 +1,113 @@
+# 错误、限流与"无数据"
+
+**核心区分**（先记住这条）：**"取数失败" ≠ "当前没有这类数据"**。两者都有明确信号，不要混为一谈。
+
+---
+
+## 一、HTTP 状态码
+
+| 状态 | 含义 | 处理 |
+|---|---|---|
+| **200** | 成功（但要看 `ok` 字段，见下）| 读 `data` / `structured` |
+| **401** | 未授权 —— **没带 Key 调了付费端点**（或 Key 无效/已停用）| 拿 Key（https://ashareapi.com/pricing），或改用 5 个免费端点 |
+| **403** | 禁止 —— 常见于 **IP 维度限制**（一个 Key 被多个 IP 共用，超出该档位允许的 IP 数）| 别把 Key 共享给多人；升级档位 |
+| **404** | 路径不存在 | 核对端点名（见 `endpoints.md`）|
+| **422** | 参数错误（缺必填 / 值非法）| 看返回里的说明；常见是缺 `code` |
+| **429** | **超出限流** | 降频 · 解 PoW 提额 · 升级档位（见下）|
+| **5xx** | 服务端/上游异常 | 稍后重试 |
+
+## 二、`ok` 字段（HTTP 200 也要看它）
+
+```json
+{ "ok": false, "endpoint": "block-trade", "data": [] }
+```
+
+- **`ok:true`** = 取数成功
+- **`ok:false`** = **上游取数失败**（我们**已自动换源**，且 **不扣调用次数**）→ **重试一次通常就好**
+
+⚠️ **`ok:false` 不是"你写错了"** —— 是数据源那一侧的问题。所以**不要**因为 `ok:false` 就改代码逻辑。
+
+## 三、空结果（≠ 失败）
+
+**`ok:false` + `data: []`** 或 **`ok:true` 但列表为空** → 可能是"**当前确实没有这类数据**"：
+
+- 今天没有大宗交易
+- 这个时间段没有解禁事件
+- 该股今日不在龙虎榜
+
+**处理**：换条件 / 换日期 / 稍后再试 —— **不是故障，不会计费**。
+**不要**把它当成"上游挂了"去重试到超时。
+
+## 四、限流（匿名很紧，这是设计）
+
+| 档位 | 额度 |
+|---|---|
+| **匿名**（无 Key）| **5 次/分钟** |
+| **匿名 + PoW** | **60 次/分钟** |
+| 各付费档 | 见 https://ashareapi.com/pricing（含每分钟与总量限制）|
+
+**触发时**：返回 **429**。
+
+### 匿名提额：解一次 PoW 挑战
+
+```bash
+# 1) 取挑战
+curl "https://api.ashareapi.com/v1/challenge"
+# → { "challenge": "...", "difficulty": 18, "expires_in": 600, "how_to": "..." }
+
+# 2) 算 nonce：要求 sha256("<challenge>.<nonce>") 的十六进制前 difficulty 位为 '0'
+#    （普通电脑毫秒~秒级；难度由服务端定，只允许调高不允许调低）
+
+# 3) 带上去请求
+curl -H "X-PoW: <challenge>.<nonce>" \
+     "https://api.ashareapi.com/v1/quote?code=sh600667"
+```
+
+**要点**：
+- 挑战**有有效期**（`expires_in`，通常 600 秒），过期重新取
+- 挑战可以**预取 + 预解算 + 延后使用**（流水线化，不必每次现解）
+- **付费 Key 用户不需要 PoW**（额度已够）
+
+### 降频建议（比死磕 429 更实际）
+
+- 批量取数时**加 `time.sleep()`**（匿名至少 12 秒/次；PoW 后 1 秒/次）
+- **本地缓存**：同一标的一天内的行情/财务不必重复取
+- 需要**高频**就升级档位 —— 比反复解 PoW 省事
+
+## 五、官方 Python SDK 的 5 类异常（不用自己判状态码）
+
+```python
+from ashareapi import (AShareAPI, AuthError, RateLimitError,
+                       UpstreamError, EmptyResultError, APIError)
+
+try:
+    df = cli.fund("sh600667")
+except AuthError:        # 401 / 缺 Key
+    ...
+except RateLimitError:   # 429（含提额提示）
+    ...
+except UpstreamError:    # ok:false —— 上游失败，已换源，不扣次数 → 重试一次
+    ...
+except EmptyResultError: # 当前无数据（如当天无大宗交易）→ 不计费，换条件
+    ...
+except APIError:         # 其他（网络 / 5xx 重试耗尽）
+    ...
+```
+
+| SDK 异常 | 对应上面的情况 |
+|---|---|
+| `AuthError` | 401 / 403（鉴权与 IP 维度）|
+| `RateLimitError` | 429 |
+| `UpstreamError` | `ok:false` 且 `data` 非空（真失败）|
+| **`EmptyResultError`** | `ok:false` 且 `data` 为空（**无数据 ≠ 失败**）|
+| `APIError` | 网络异常 / 5xx 重试耗尽 |
+
+**这正是 SDK 的价值**：把"该重试"和"该换条件"分开，不用自己猜。
+
+## 六、排错顺序（省时间）
+
+1. **401 还是 429？** → 缺 Key 还是超频（两者处理完全不同）
+2. **HTTP 200 但没数据？** → 看 `ok` 与 `data`：`ok:false`+空 = 无数据（换条件）；`ok:false`+有内容 = 上游失败（重试）
+3. **403？** → 是不是把 Key 给多人用了（IP 维度）
+4. **422？** → 看返回说明，多半少传了必填参数（如 `code`）
+5. **数据看着不对？** → 先查单位与日期（见 `fields.md`），90% 是单位/日期问题，不是接口问题

package/skills/ashareapi/references/fields.md

@@ -0,0 +1,96 @@
+# 字段语义与单位（算数前必读）
+
+**为什么单独一份**：这些是最容易踩的坑 —— **不看会算错**（单位错 100 倍、`+` 拼成字符串）。
+
+---
+
+## 一、单位（最容易错）
+
+| 字段 | 单位 | 示例 |
+|---|---|---|
+| `volume` | **手**（1 手 = 100 股）| `volume: 12345` = 123.45 万股 |
+| `amount` | **元** | `amount: 135160431.2` = 1.35 亿元（**不是万元**！）|
+| `turnover` | **百分数**（换手率%）| `turnover: 1.88` = 换手 1.88%（与 `/v1/snapshot` **同名同值**）|
+| `instBuyRate` / `netBuyRate` | **百分数** | `20` 表示 **20%**（不是 0.2）|
+| `pe` / `pb` / `ps` | 倍数 | `pe: 18.5` = 18.5 倍 |
+| `totalMV` / 市值类 | 看字段名后缀 | 一般**元**或**亿元** —— 用前先看一条真实数据对量级 |
+
+**自检方法**：拿一个熟悉的股票对量级。比如茅台现价 ~1300 元、市值 ~1.6 万亿 —— 如果算出来是 1.6 亿，就是单位错了 10000 倍。
+
+## 二、数字常以**字符串**返回
+
+上游很多金额字段是**字符串**：
+
+```python
+net = row["netBuyAmt"]        # "135160431.2" ← 字符串！
+# ❌ net / 1e8                  → TypeError
+# ❌ "100" + net                → 拼字符串 "100135160431.2"
+net = float(row["netBuyAmt"]) # ✅ 先转 float 再算
+print(round(net / 1e8, 2), "亿元")
+```
+
+**通用做法**：拿不准就先 `float()`；用 pandas 时 `df["col"].astype(float)`。
+
+## 三、日期语义（别把昨天当今天）
+
+- **`date` 字段 = 数据所属交易日**（不是查询时间）
+- **休市日不会变成"今天"**：周六查 `quote`，返回的是**上一交易日**的数据，`date` 会如实标出
+- **`quote` 的最新一根**（`data[0]`）就是当日实时（交易时段内）或当日收盘（收盘后）
+- **`ok:false` 时 `data` 可能为空**（无数据），此时**没有** `date` 可读
+
+**用法**：要判断"这是不是今天的行情"，看 `date` **而不是**看"我刚查的"。
+
+## 四、返回结构：`data` 的四种形状（`structured` 是**条件字段**）
+
+统一信封**只有 6 个键**：
+
+```json
+{ "ok": true, "endpoint": "quote", "tier": "free", "elapsed_ms": 42, "source": "multi",
+  "data": [ {"date": "2026-09-24", "last": "19.41", "turnover": "0.54"}, ... ] }
+```
+
+⚠️ **`structured` / `tables` 不是标配** —— **只有 `data` 是 Markdown 文本时才附**
+（`market-overview` / `changedist` / `lhb` / `sector` / `sector-valuation` / `bond` / `etf` / `screen` / `macro`）。
+**其余端点没有这两个键** ⇒ **代码写 `body.get("structured")`，不要写 `body["structured"]`**（会 KeyError）。
+
+`data` 本身的形状有 **4 种**（判别 + 通吃写法见 `endpoints.md` §返回形态）：
+
+| `data` 形状 | 哪些端点 | 怎么读 |
+|---|---|---|
+| 对象数组 `[{"col": val}]` | 多数（`quote` `kline` `hot` `snapshot` `profile` …）| `data[0]["field"]` |
+| 表列表 `[[行...], [行...]]` | `finance` | `data[表号][行号]["字段"]`（先按表索引）|
+| 多段结构 `{tables:[{title,slug,rows}], data:{slug:rows}}` | `shareholder` · `calendar` | `data["tables"]` / `data["data"]["<slug>"]` |
+| Markdown 字符串 | 上述 9 个 + `events` · `dehydrated` | 优先读同响应的 `structured` / `tables`（若存在）|
+
+**纪律**：**程序化处理先判 `data` 形状**；**只有** Markdown 端点才退回 `structured`，**不要正则解析 Markdown**。
+
+## 五、字段命名规律（好记）
+
+| 后缀 / 词 | 含义 |
+|---|---|
+| `_TTM` | 滚动 12 个月（如 `ROETTM` / `PE_TTM`）|
+| `YOY` | 同比（`NPParentCompanyYOY` = 归母净利同比）|
+| `MOM` | 环比 |
+| `Amt` | 金额（amount）|
+| `Cnt` / `count` | 数量 |
+| `Rate` / `Ratio` | **比率（多為百分数）**|
+| `MV` | 市值（market value）|
+| `NAV` / `NAPS` | 净值 / 每股净资产 |
+
+## 六、几个具体端点的字段要点
+
+| 端点 | 要点 |
+|---|---|
+| `fund` | 主力的**当日/5/10/20 日**净流入是不同字段；龙虎榜营业部明细在子结构里 |
+| `lhb` | `activeseat` 的 `code` 与 `stockName` 是**分号分隔的等长列表**（`sh600127;sh600664`）→ `split(";")` 后按下标对应 |
+| `changedist` | 是**当期**口径；`market-overview?type=updown` 是 **T-1** 口径，**两者数值会不同**（别混用）|
+| `kline` | `period` 只支持 day/week/month；`count` 是根数 |
+| `screen` | 返回的是股票列表（含命中因子值），排序用 `orderby` |
+
+## 七、算数前检查清单
+
+1. 单位对不对？（手/股 · 元/万元/亿元 · 百分数/小数）
+2. 是不是字符串？（`float()` 了吗）
+3. 日期是哪一天？（看 `date`）
+4. 读的是 `structured` 还是 `data`？
+5. 空结果 ≠ 0 —— 是"没有数据"，不是"值为 0"

package/skills/ashareapi/references/sdk.md

@@ -0,0 +1,204 @@
+# 官方 SDK（Python `pip install ashareapi` · Node.js `npm install ashareapi`）
+
+**什么时候用 SDK 而不是直接打 HTTP**：
+- ✅ **要写代码**（Python 脚本 / notebook / 回测 · Node 服务 / Next.js / 脚本）→ 用 SDK（省掉重试、异常分类、字段解析）
+- ✅ Python 要成 **pandas DataFrame**（直接算 / 画图）→ 用 Python SDK
+- ✅ Node 要 **TypeScript 类型**（编辑器补全 32 个方法与参数）→ 用 Node SDK
+- ❌ 只是**取一个数看一眼** → 直接 `curl` / `fetch` 更快
+- ❌ 用 **Go / Java / C# 等**（暂无官方 SDK）→ 直接调 HTTP（见 `endpoints.md`）
+
+---
+
+## 一、安装
+
+**Python**（要求 3.9+；强依赖只有 `requests`，pandas 可选）：
+
+```bash
+pip install ashareapi            # 基础：返回 list[dict]
+pip install "ashareapi[pandas]"  # 加 DataFrame 支持（推荐）
+```
+
+**Node.js / TypeScript**（要求 Node ≥ 18；**零运行时依赖**，用原生 `fetch`）：
+
+```bash
+npm install ashareapi
+```
+
+> ⚠️ Node SDK **只在服务端用**（Node / Next.js 服务端 / 云函数）—— 浏览器里会暴露你的 API Key，它刻意不提供浏览器构建。
+
+## 二、快速开始
+
+**Python**：
+
+```python
+from ashareapi import AShareAPI
+
+cli = AShareAPI()                       # 免费端点无需 Key
+df = cli.quote("sh600667")              # 实时行情 → DataFrame
+print(df[["date", "last", "turnover"]])
+
+print(cli.kline("600667.SH", count=5))  # 代码格式随便写（自动归一化）
+print(cli.hot(limit=10))
+print(cli.changedist())                 # 涨跌分布（市场广度）
+```
+
+**Node.js / TypeScript**（ESM 与 CommonJS 都支持）：
+
+```ts
+import { AShareAPI } from "ashareapi";   // CJS: const { AShareAPI } = require("ashareapi")
+
+const cli = new AShareAPI();                  // 免费端点无需 Key
+const bars = await cli.quote("sh600667");     // → 对象数组
+console.log(bars[0]);                         // { date, open, last, high, low, volume, amount, turnover }
+
+console.log(await cli.kline("600667.SH", "day", 5));
+console.log(await cli.hot(10));
+console.log(await cli.changedist());
+```
+
+**付费端点**：
+
+```python
+# Python
+cli = AShareAPI("ct-你的Key")            # 或环境变量 ASHARE_API_KEY
+print(cli.fund("sh600667"))              # 资金流 + 龙虎榜 + 大宗 + 两融
+print(cli.finance("sh600667"))           # 三大报表
+print(cli.lhb("institution"))            # 龙虎榜机构榜
+print(cli.screen(preset="low_pe", orderby="ROETTM", limit=10))
+print(cli.industry_chain(mode="stock", code="sh600667"))
+```
+
+```ts
+// Node.js
+const cli = new AShareAPI({ apiKey: "ct-你的Key" });   // 或 process.env.ASHARE_API_KEY
+console.log(await cli.fund("sh600667"));
+console.log(await cli.finance("sh600667"));
+console.log(await cli.lhb("institution"));
+console.log(await cli.screen("", "low_pe", 10, "ROETTM"));  // expr, preset, limit, orderby
+console.log(await cli.industryChain("stock", "", "sh600667"));
+```
+
+**环境变量**（推荐，别把 Key 写死在代码里）：
+
+```bash
+export ASHARE_API_KEY=ct-你的Key          # Linux/macOS
+set ASHARE_API_KEY=ct-你的Key             # Windows cmd
+```
+
+## 三、代码格式：三种写法都认
+
+两个 SDK 内部都会把它们统一成 `sh600667`：
+
+| 你写的 | 结果 |
+|---|---|
+| `sh600667` | `sh600667` |
+| `600667.SH` | `sh600667` |
+| `600667` | `sh600667`（按首位推断：5/6→沪 · 0/3→深 · 4/8→北）|
+
+→ **从别处迁过来的代码基本不用改**。
+
+## 四、32 个方法（与 HTTP 端点 1:1）
+
+| 端点 | Python | Node.js |
+|---|---|---|
+| `/v1/quote` | `quote(code)` | `quote(code)` |
+| `/v1/kline` | `kline(code, period, count)` | `kline(code, period, count)` |
+| `/v1/hot` | `hot(limit)` | `hot(limit)` |
+| `/v1/market-overview` | `market_overview(type)` | `marketOverview(type)` · 别名 `market_overview` |
+| `/v1/changedist` | `changedist()` | `changedist()` |
+| `/v1/health` · `/v1/challenge` · `/v1/usage` | `health()` `challenge()` `usage()` | 同 |
+| `/v1/fund` | `fund(code)` | `fund(code)` |
+| `/v1/lhb` | `lhb(type, date)` | `lhb(type, date)` |
+| `/v1/margin-trade` | `margin_trade(code, date)` | `marginTrade(code, date)` · 别名 `margin_trade` |
+| `/v1/block-trade` | `block_trade(code, date)` | `blockTrade(code, date)` · 别名 `block_trade` |
+| `/v1/finance` | `finance(code, num)` | `finance(code, num)` |
+| `/v1/dividend` · `/v1/shareholder` | `dividend(code, years)` `shareholder(code)` | 同 |
+| `/v1/technical` · `/v1/chip` · `/v1/profile` · `/v1/search` | `technical(code)` `chip(code)` `profile(code)` `search(q)` | 同 |
+| **`/v1/orderbook`**｜`orderbook(code)` | 同（五档盘口·**盘中**·量单位=手）|
+| **`/v1/snapshot`**｜`snapshot(code)` | 同（全字段画像·**仅 A 股**·付费）|
+| `/v1/events` · `/v1/calendar` | `events(code)` `calendar(date, limit)` | 同 |
+| `/v1/sector` | `sector()` | `sector()` |
+| `/v1/sector-valuation` | `sector_valuation(code)` | `sectorValuation(code)` · 别名 `sector_valuation` |
+| `/v1/industry-chain` | `industry_chain(mode, topic, code)` | `industryChain(mode, topic, code)` · 别名 `industry_chain` |
+| `/v1/bond` · `/v1/etf` · `/v1/ipo` | `bond(code)` `etf(code)` `ipo(days)` | 同 |
+| `/v1/screen` | `screen(expr, preset, limit, orderby, desc, market)` | 同（位置参数）|
+| `/v1/macro` | `macro(region, names)` | `macro(region, names)` |
+| `/v1/dehydrated` | `dehydrated(mode, symbol, limit)` | `dehydrated(mode, symbol, limit)` |
+
+> **方法是否与线上一致？** 两个 SDK 都有**覆盖守护测试**：拉 `/openapi.json` 比对方法名，端点增减即测试红灯。
+
+## 五、返回形态（两者不同，注意）
+
+⚠️ **端点返回的不总是"一张表"** —— `data` 有 **4 种形状**（对象数组 / 表列表 / 多段结构 / Markdown 文本，见 `endpoints.md`）。
+SDK **只把「对象数组」转成 DataFrame**，其余**原样返回**（不强行套成 DataFrame）：
+
+| 返回形状 | Python | Node.js |
+|---|---|---|
+| 对象数组（多数端点）| `pandas.DataFrame`（装了 pandas）/ `list[dict]` | **对象数组 `Row[]`** |
+| 表列表（`finance`）| **`list[list[dict]]` 原样返回**（不套 DataFrame）| `TableList` = `Row[][]` |
+| 多段结构（`shareholder` · `calendar`）| **`dict` 原样返回** | `SectionedResult` = `{tables, data}` |
+| 完整信封 | `raw=True` | `new AShareAPI({ raw: true })` |
+| 同步性 | **同步** | **全部返回 Promise**（要 `await`）|
+
+**字段语义与单位**（手/元/百分数）见 `fields.md` —— 两个 SDK **都不会**帮你换算单位。
+
+## 六、异常（5 类，各自告诉你做什么）
+
+**Python**：
+
+```python
+from ashareapi import (AShareAPI, AShareError, AuthError, RateLimitError,
+                       UpstreamError, EmptyResultError, APIError)
+
+try:
+    df = cli.fund("sh600667")
+except AuthError as e:          # 401/403 → 付费端点缺 Key / IP 维度限制
+    print(e)
+except RateLimitError as e:     # 429 → 降频 · 解 PoW 提额 · 升级档位
+    print(e)
+except UpstreamError as e:      # ok:false → 上游失败（已换源、不扣次数）→ 重试一次
+    print(e)
+except EmptyResultError as e:   # 当前无数据（如当天无大宗交易）→ 不计费，换条件
+    print(e)
+except APIError as e:           # 网络 / 5xx 重试耗尽
+    print(e)
+```
+
+**Node.js**（同名 5 类，`instanceof` 判定）：
+
+```ts
+import { AShareAPI, AuthError, RateLimitError, UpstreamError, EmptyResultError } from "ashareapi";
+
+try {
+  const rows = await cli.fund("sh600667");
+} catch (e) {
+  if (e instanceof AuthError) console.log(e.message);            // 401/403
+  else if (e instanceof RateLimitError) console.log(e.message);  // 429
+  else if (e instanceof UpstreamError) console.log(e.message);   // ok:false → 重试一次
+  else if (e instanceof EmptyResultError) console.log(e.message);// 当前无数据 → 不计费
+  else throw e;
+}
+```
+
+全部继承自 `AShareError`（Python 要一把抓就 `except AShareError`）。
+
+**`EmptyResultError` 是 SDK 相对裸 HTTP 的独有改进**：把"**没有数据**"和"**取数失败**"分开，避免把"今天没大宗交易"当故障反复重试（细节见 `errors.md`）。
+
+## 七、SDK vs 直接 HTTP vs 其他数据源
+
+| | 官方 SDK | 自己 requests / fetch | 其他开源库 |
+|---|---|---|---|
+| 上手 | **装完即用** | 自己封装重试/异常 | 装完即用 |
+| 返回 | **DataFrame**（Python）/ **对象数组**（Node）| 自己解析 | DataFrame |
+| 免费试用 | **5 端点免 Key** | 同样免 Key | 视来源 |
+| 错误处理 | **5 类异常**（含"无数据≠失败"）| 自己判断 | 自己判断 |
+| 维护 | **我们维护**（多源自动切换）| 上游改了你改 | 上游改版常需跟进 |
+| 依赖 | Python: `requests`（pandas 可选）/ Node: **零依赖** | 同 | 视库 |
+
+## 八、边界（诚实）
+
+- **K 线只有日/周/月**，**没有分钟级**（`period` 仅 `day`/`week`/`month`）
+- **新闻/公告全文**不在 API 范围（有 `dehydrated` 研报摘要、`events` 事件标签）
+- **不含投资建议** —— SDK 只负责取数
+- **Node SDK 不要在浏览器里用**（会暴露 Key）
+- 版本记录与更新：https://ashareapi.com/changelog