ashareapi-pi 0.2.5 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.en.md +130 -130
  2. package/README.md +130 -130
  3. package/package.json +2 -2
  4. package/skills/ashareapi/SKILL.md +254 -244
  5. package/skills/ashareapi/references/endpoints.md +128 -127
  6. package/skills/ashareapi/references/errors.md +117 -113
  7. package/skills/ashareapi/references/sdk.md +204 -204
package/README.en.md CHANGED
@@ -1,130 +1,130 @@
1
- <div align="center">
2
-
3
- <a href="https://ashareapi.com/en/"><img src="https://ashareapi.com/icon-512.png" width="88" height="88" alt="ashareapi"></a>
4
-
5
- # ashareapi — Official Pi Package for the A-Share Data API
6
-
7
- 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**.
8
-
9
- 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**.
10
-
11
- ![Pi](https://img.shields.io/badge/Pi-pi.dev-6E56CF)
12
- ![Agent Skills](https://img.shields.io/badge/Agent%20Skills-spec-4D6BFE)
13
- [![npm](https://img.shields.io/npm/v/ashareapi-pi?label=npm)](https://www.npmjs.com/package/ashareapi-pi)
14
- ![License](https://img.shields.io/badge/license-MIT-green)
15
-
16
- **Runs on Pi (pi.dev)**:
17
-
18
- ![Pi package](https://img.shields.io/badge/pi.dev-package-6E56CF)
19
-
20
- [中文](README.md) · **English**
21
-
22
- [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/)
23
-
24
- [Source](https://github.com/ashareapi/ashareapi-skill) · [Issues](https://github.com/ashareapi/ashareapi-skill/issues) · [Changelog](https://ashareapi.com/en/changelog/)
25
-
26
- </div>
27
-
28
- ---
29
-
30
- ## What is this
31
-
32
- 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.
33
-
34
- 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.
35
-
36
- 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.
37
-
38
- ---
39
-
40
- ## Why use it
41
-
42
- - **One command to install**: `pi install npm:ashareapi-pi`, then `/reload` — no JSON to hand-edit, no script to run
43
- - **Free endpoints are genuinely key-free**: `/v1/quote` `/v1/kline` `/v1/hot` `/v1/changedist` `/v1/market-overview` work right after installation
44
- - **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**
45
- - **Fixed conventions, no post-processing**: K-lines are always **forward-adjusted (qfq)** (there is no `adjust` parameter), so there is no double-adjustment
46
- - **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
47
- - **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
48
- - **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
49
-
50
- ---
51
-
52
- ## Install
53
-
54
- ```bash
55
- pi install npm:ashareapi-pi
56
- ```
57
-
58
- Then `/reload` (or restart Pi). To try it once without touching your config:
59
-
60
- ```bash
61
- pi -e npm:ashareapi-pi
62
- ```
63
-
64
- Then just ask:
65
-
66
- | You ask | Endpoint used |
67
- |---|---|
68
- | What is 600667 trading at? | `/v1/quote` |
69
- | Pull the last 60 daily candles for 600667 | `/v1/kline` |
70
- | How is the market doing today? | `/v1/market-overview` |
71
- | What are people watching right now? | `/v1/hot` |
72
- | What is today's advance/decline distribution? | `/v1/changedist` |
73
-
74
- Uninstall:
75
-
76
- ```bash
77
- pi remove npm:ashareapi-pi
78
- ```
79
-
80
- ---
81
-
82
- ## API key setup
83
-
84
- The 5 endpoints above work with **no configuration at all**.
85
-
86
- 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).
87
-
88
- Put the key in the `ASHAREAPI_KEY` environment variable, or just tell Pi — the manual spells out how to send it:
89
-
90
- ```bash
91
- curl -H "Authorization: Bearer ct-your-key" "https://api.ashareapi.com/v1/quote?code=sh600667"
92
- ```
93
-
94
- ---
95
-
96
- ## What you can query
97
-
98
- **Free (no key)**
99
-
100
- Live quotes · candles · attention list · market breadth · market overview
101
-
102
- **Requires a key**
103
-
104
- 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
105
-
106
- Field meanings, parameters, and response samples are in the [docs](https://ashareapi.com/en/docs/).
107
-
108
- ---
109
-
110
- ## Related
111
-
112
- **Official SDKs**: Python `pip install ashareapi` · Node.js / TypeScript `npm install ashareapi`
113
-
114
- **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
115
-
116
- **Agent Skill** (an endpoint manual for AI agents): <https://ashareapi.com/en/skill/>
117
-
118
- **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.
119
-
120
- ---
121
-
122
- ## Version
123
-
124
- 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/).
125
-
126
- ---
127
-
128
- ## License
129
-
130
- MIT
1
+ <div align="center">
2
+
3
+ <a href="https://ashareapi.com/en/"><img src="https://ashareapi.com/icon-512.png" width="88" height="88" alt="ashareapi"></a>
4
+
5
+ # ashareapi — Official Pi Package for the A-Share Data API
6
+
7
+ 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 — **33 endpoints, and 5 of them need no key**.
8
+
9
+ 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**.
10
+
11
+ ![Pi](https://img.shields.io/badge/Pi-pi.dev-6E56CF)
12
+ ![Agent Skills](https://img.shields.io/badge/Agent%20Skills-spec-4D6BFE)
13
+ [![npm](https://img.shields.io/npm/v/ashareapi-pi?label=npm)](https://www.npmjs.com/package/ashareapi-pi)
14
+ ![License](https://img.shields.io/badge/license-MIT-green)
15
+
16
+ **Runs on Pi (pi.dev)**:
17
+
18
+ ![Pi package](https://img.shields.io/badge/pi.dev-package-6E56CF)
19
+
20
+ [中文](README.md) · **English**
21
+
22
+ [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/)
23
+
24
+ [Source](https://github.com/ashareapi/ashareapi-skill) · [Issues](https://github.com/ashareapi/ashareapi-skill/issues) · [Changelog](https://ashareapi.com/en/changelog/)
25
+
26
+ </div>
27
+
28
+ ---
29
+
30
+ ## What is this
31
+
32
+ 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.
33
+
34
+ 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 33 endpoints, unit conventions (`volume` is in lots / `amount` in yuan / ratios are percentages), date semantics, and common errors plus rate-limit handling.
35
+
36
+ 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.
37
+
38
+ ---
39
+
40
+ ## Why use it
41
+
42
+ - **One command to install**: `pi install npm:ashareapi-pi`, then `/reload` — no JSON to hand-edit, no script to run
43
+ - **Free endpoints are genuinely key-free**: `/v1/quote` `/v1/kline` `/v1/hot` `/v1/changedist` `/v1/market-overview` work right after installation
44
+ - **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**
45
+ - **Fixed conventions, no post-processing**: K-lines are always **forward-adjusted (qfq)** (there is no `adjust` parameter), so there is no double-adjustment
46
+ - **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
47
+ - **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
48
+ - **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
49
+
50
+ ---
51
+
52
+ ## Install
53
+
54
+ ```bash
55
+ pi install npm:ashareapi-pi
56
+ ```
57
+
58
+ Then `/reload` (or restart Pi). To try it once without touching your config:
59
+
60
+ ```bash
61
+ pi -e npm:ashareapi-pi
62
+ ```
63
+
64
+ Then just ask:
65
+
66
+ | You ask | Endpoint used |
67
+ |---|---|
68
+ | What is 600667 trading at? | `/v1/quote` |
69
+ | Pull the last 60 daily candles for 600667 | `/v1/kline` |
70
+ | How is the market doing today? | `/v1/market-overview` |
71
+ | What are people watching right now? | `/v1/hot` |
72
+ | What is today's advance/decline distribution? | `/v1/changedist` |
73
+
74
+ Uninstall:
75
+
76
+ ```bash
77
+ pi remove npm:ashareapi-pi
78
+ ```
79
+
80
+ ---
81
+
82
+ ## API key setup
83
+
84
+ The 5 endpoints above work with **no configuration at all**.
85
+
86
+ 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).
87
+
88
+ Put the key in the `ASHAREAPI_KEY` environment variable, or just tell Pi — the manual spells out how to send it:
89
+
90
+ ```bash
91
+ curl -H "Authorization: Bearer ct-your-key" "https://api.ashareapi.com/v1/quote?code=sh600667"
92
+ ```
93
+
94
+ ---
95
+
96
+ ## What you can query
97
+
98
+ **Free (no key)**
99
+
100
+ Live quotes · candles · attention list · market breadth · market overview
101
+
102
+ **Requires a key**
103
+
104
+ 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
105
+
106
+ Field meanings, parameters, and response samples are in the [docs](https://ashareapi.com/en/docs/).
107
+
108
+ ---
109
+
110
+ ## Related
111
+
112
+ **Official SDKs**: Python `pip install ashareapi` · Node.js / TypeScript `npm install ashareapi`
113
+
114
+ **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
115
+
116
+ **Agent Skill** (an endpoint manual for AI agents): <https://ashareapi.com/en/skill/>
117
+
118
+ **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.
119
+
120
+ ---
121
+
122
+ ## Version
123
+
124
+ 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/).
125
+
126
+ ---
127
+
128
+ ## License
129
+
130
+ MIT
package/README.md CHANGED
@@ -1,130 +1,130 @@
1
- <div align="center">
2
-
3
- <a href="https://ashareapi.com"><img src="https://ashareapi.com/icon-512.png" width="88" height="88" alt="ashareapi"></a>
4
-
5
- # ashareapi — A股数据 API 官方 Pi 包
6
-
7
- 让 **Pi**（[pi.dev](https://pi.dev)）直接查 A 股数据：行情 / K线 / **五档盘口** / 财务 / 资金 / 龙虎榜 / 板块 / 可转债 / 因子选股 / 宏观 —— **32 个端点，5 个免费无需 Key**。
8
-
9
- 一条命令装好 —— 装完 Pi 就知道**该调哪个端点、参数怎么填、字段什么单位、错了怎么处理**。
10
-
11
- ![Pi](https://img.shields.io/badge/Pi-pi.dev-6E56CF)
12
- ![Agent Skills](https://img.shields.io/badge/Agent%20Skills-spec-4D6BFE)
13
- [![npm](https://img.shields.io/npm/v/ashareapi-pi?label=npm)](https://www.npmjs.com/package/ashareapi-pi)
14
- ![License](https://img.shields.io/badge/license-MIT-green)
15
-
16
- **支持 Pi（pi.dev）**：
17
-
18
- ![Pi package](https://img.shields.io/badge/pi.dev-package-6E56CF)
19
-
20
- **中文** · [English](README.en.md)
21
-
22
- [官网](https://ashareapi.com) · [文档](https://ashareapi.com/docs/) · [端点清单](https://ashareapi.com/endpoints/) · [MCP 接入](https://ashareapi.com/mcp) · [Agent Skill](https://ashareapi.com/skill)
23
-
24
- [GitHub 源码](https://github.com/ashareapi/ashareapi-skill) · [问题反馈 Issues](https://github.com/ashareapi/ashareapi-skill/issues) · [更新日志](https://ashareapi.com/changelog)
25
-
26
- </div>
27
-
28
- ---
29
-
30
- ## 这是什么
31
-
32
- 一个 **A股数据 Pi 包**：装上之后，你在 Pi 里问「600667 现在多少钱」，它会自己去调接口拿**真实数据**，而不是编一个数给你。
33
-
34
- 里面是一份 **Agent Skill**（开放标准）—— Pi 与 Claude Code / Codex 用**同一套 skill 规范**，所以这份说明书在它们之间通用。内容 = 32 个端点的参数与字段语义、单位换算（`volume` 是手 / `amount` 是元 / 比率为百分数）、数据日期语义、常见错误与限流处理。
35
-
36
- 底层接的是 [ashareapi.com](https://ashareapi.com) 的 REST API（`https://api.ashareapi.com/v1/...`）—— Pi 直接 `curl` 调即可；也可以换成官方 SDK 或 MCP。
37
-
38
- ---
39
-
40
- ## 为什么用它
41
-
42
- - **一条命令装好**：`pi install npm:ashareapi-pi`，装完 `/reload` 即用，不用配 JSON、不用写脚本
43
- - **免费端点真的免 Key**：`/v1/quote` `/v1/kline` `/v1/hot` `/v1/changedist` `/v1/market-overview` 这 5 个装上就能调
44
- - **多源自动切换**：后端 70 个数据源互为备份，某个源出问题会自动换下一个，且**不扣调用次数**
45
- - **口径固定，不用二次处理**：K 线固定**前复权**（没有 `adjust` 参数），不会二次复权
46
- - **无数据 ≠ 失败**：停牌这类「市场真没数据」和「取数失败」分开返回 —— Agent 不会把停牌误判成故障
47
- - **说明书写给 AI 看**：讲清「什么时候用哪个端点 / 参数怎么填 / 字段什么单位 / 错了怎么处理」，Agent 不会调错
48
- - **不用你维护**：内容由脚本从 Agent Skill 生成（单一事实源），Pi 升级也不用跟着改
49
-
50
- ---
51
-
52
- ## 安装
53
-
54
- ```bash
55
- pi install npm:ashareapi-pi
56
- ```
57
-
58
- 装完 `/reload`（或重开 Pi）即可。想先试一次、不写进配置：
59
-
60
- ```bash
61
- pi -e npm:ashareapi-pi
62
- ```
63
-
64
- 然后在对话里直接问：
65
-
66
- | 你可以这样问 | 会用到的端点 |
67
- |---|---|
68
- | 600667 现在多少钱？ | `/v1/quote` |
69
- | 帮我拉一下 600667 最近 60 天的日 K | `/v1/kline` |
70
- | 今天市场什么情况？ | `/v1/market-overview` |
71
- | 现在大家都在看什么股票？ | `/v1/hot` |
72
- | 今天涨跌家数怎么分布？ | `/v1/changedist` |
73
-
74
- 卸载：
75
-
76
- ```bash
77
- pi remove npm:ashareapi-pi
78
- ```
79
-
80
- ---
81
-
82
- ## 配置 API Key
83
-
84
- 上面 5 个端点**不用配任何东西**就能用。
85
-
86
- 要用其余端点（盘口 / 财务 / 资金 / 龙虎榜 / 板块 / 选股 / 宏观…），需要一个 Key：[获取 Key](https://ashareapi.com/pricing)（体验版 ¥9.9 起）。
87
-
88
- 把 Key 放进环境变量 `ASHAREAPI_KEY`，或者直接告诉 Pi —— 说明书里写明了怎么带上：
89
-
90
- ```bash
91
- curl -H "Authorization: Bearer ct-你的Key" "https://api.ashareapi.com/v1/quote?code=sh600667"
92
- ```
93
-
94
- ---
95
-
96
- ## 能查什么
97
-
98
- **免费（无需 Key）**
99
-
100
- 实时行情 · K线 · 热搜榜 · 涨跌分布 · 市场总览
101
-
102
- **需 Key**
103
-
104
- 五档盘口 · 全字段画像 · 财务三表 · 资金流 · 技术指标 · 股东 · 事件 · 龙虎榜 · 因子选股 · 板块 · 板块估值 · 宏观 · 可转债 · ETF · 新股 · 分红 · 脱水研报 · 代码搜索 · 用量
105
-
106
- 字段含义、参数与返回样例见[文档](https://ashareapi.com/docs/)。
107
-
108
- ---
109
-
110
- ## 相关
111
-
112
- **官方 SDK**：Python `pip install ashareapi` · Node.js / TypeScript `npm install ashareapi`
113
-
114
- **MCP 服务器**：`https://api.ashareapi.com/mcp`（[配置说明](https://ashareapi.com/mcp)）—— Pi **内置 MCP**，填一条 URL 就能接；Claude Code / Codex / Cursor 等 19 家客户端同样
115
-
116
- **Agent Skill**（给 AI 读的接口说明书）：<https://ashareapi.com/skill>
117
-
118
- **本包内容**由脚本从 Agent Skill 生成（单一事实源：<https://github.com/ashareapi/ashareapi-skill>），不手工维护。
119
-
120
- ---
121
-
122
- ## 版本
123
-
124
- 最新版本见 [npm](https://www.npmjs.com/package/ashareapi-pi)。本包内容来自 Agent Skill，**版本号与 skill 一致**；变更见 [ashareapi.com/changelog](https://ashareapi.com/changelog)。
125
-
126
- ---
127
-
128
- ## License
129
-
130
- MIT
1
+ <div align="center">
2
+
3
+ <a href="https://ashareapi.com"><img src="https://ashareapi.com/icon-512.png" width="88" height="88" alt="ashareapi"></a>
4
+
5
+ # ashareapi — A股数据 API 官方 Pi 包
6
+
7
+ 让 **Pi**（[pi.dev](https://pi.dev)）直接查 A 股数据：行情 / K线 / **五档盘口** / 财务 / 资金 / 龙虎榜 / 板块 / 可转债 / 因子选股 / 宏观 —— **33 个端点，5 个免费无需 Key**。
8
+
9
+ 一条命令装好 —— 装完 Pi 就知道**该调哪个端点、参数怎么填、字段什么单位、错了怎么处理**。
10
+
11
+ ![Pi](https://img.shields.io/badge/Pi-pi.dev-6E56CF)
12
+ ![Agent Skills](https://img.shields.io/badge/Agent%20Skills-spec-4D6BFE)
13
+ [![npm](https://img.shields.io/npm/v/ashareapi-pi?label=npm)](https://www.npmjs.com/package/ashareapi-pi)
14
+ ![License](https://img.shields.io/badge/license-MIT-green)
15
+
16
+ **支持 Pi（pi.dev）**：
17
+
18
+ ![Pi package](https://img.shields.io/badge/pi.dev-package-6E56CF)
19
+
20
+ **中文** · [English](README.en.md)
21
+
22
+ [官网](https://ashareapi.com) · [文档](https://ashareapi.com/docs/) · [端点清单](https://ashareapi.com/endpoints/) · [MCP 接入](https://ashareapi.com/mcp) · [Agent Skill](https://ashareapi.com/skill)
23
+
24
+ [GitHub 源码](https://github.com/ashareapi/ashareapi-skill) · [问题反馈 Issues](https://github.com/ashareapi/ashareapi-skill/issues) · [更新日志](https://ashareapi.com/changelog)
25
+
26
+ </div>
27
+
28
+ ---
29
+
30
+ ## 这是什么
31
+
32
+ 一个 **A股数据 Pi 包**：装上之后，你在 Pi 里问「600667 现在多少钱」，它会自己去调接口拿**真实数据**，而不是编一个数给你。
33
+
34
+ 里面是一份 **Agent Skill**（开放标准）—— Pi 与 Claude Code / Codex 用**同一套 skill 规范**，所以这份说明书在它们之间通用。内容 = 33 个端点的参数与字段语义、单位换算（`volume` 是手 / `amount` 是元 / 比率为百分数）、数据日期语义、常见错误与限流处理。
35
+
36
+ 底层接的是 [ashareapi.com](https://ashareapi.com) 的 REST API（`https://api.ashareapi.com/v1/...`）—— Pi 直接 `curl` 调即可；也可以换成官方 SDK 或 MCP。
37
+
38
+ ---
39
+
40
+ ## 为什么用它
41
+
42
+ - **一条命令装好**：`pi install npm:ashareapi-pi`，装完 `/reload` 即用，不用配 JSON、不用写脚本
43
+ - **免费端点真的免 Key**：`/v1/quote` `/v1/kline` `/v1/hot` `/v1/changedist` `/v1/market-overview` 这 5 个装上就能调
44
+ - **多源自动切换**：后端 70 个数据源互为备份，某个源出问题会自动换下一个，且**不扣调用次数**
45
+ - **口径固定，不用二次处理**：K 线固定**前复权**（没有 `adjust` 参数），不会二次复权
46
+ - **无数据 ≠ 失败**：停牌这类「市场真没数据」和「取数失败」分开返回 —— Agent 不会把停牌误判成故障
47
+ - **说明书写给 AI 看**：讲清「什么时候用哪个端点 / 参数怎么填 / 字段什么单位 / 错了怎么处理」，Agent 不会调错
48
+ - **不用你维护**：内容由脚本从 Agent Skill 生成（单一事实源），Pi 升级也不用跟着改
49
+
50
+ ---
51
+
52
+ ## 安装
53
+
54
+ ```bash
55
+ pi install npm:ashareapi-pi
56
+ ```
57
+
58
+ 装完 `/reload`（或重开 Pi）即可。想先试一次、不写进配置：
59
+
60
+ ```bash
61
+ pi -e npm:ashareapi-pi
62
+ ```
63
+
64
+ 然后在对话里直接问：
65
+
66
+ | 你可以这样问 | 会用到的端点 |
67
+ |---|---|
68
+ | 600667 现在多少钱？ | `/v1/quote` |
69
+ | 帮我拉一下 600667 最近 60 天的日 K | `/v1/kline` |
70
+ | 今天市场什么情况？ | `/v1/market-overview` |
71
+ | 现在大家都在看什么股票？ | `/v1/hot` |
72
+ | 今天涨跌家数怎么分布？ | `/v1/changedist` |
73
+
74
+ 卸载：
75
+
76
+ ```bash
77
+ pi remove npm:ashareapi-pi
78
+ ```
79
+
80
+ ---
81
+
82
+ ## 配置 API Key
83
+
84
+ 上面 5 个端点**不用配任何东西**就能用。
85
+
86
+ 要用其余端点（盘口 / 财务 / 资金 / 龙虎榜 / 板块 / 选股 / 宏观…），需要一个 Key：[获取 Key](https://ashareapi.com/pricing)（体验版 ¥9.9 起）。
87
+
88
+ 把 Key 放进环境变量 `ASHAREAPI_KEY`，或者直接告诉 Pi —— 说明书里写明了怎么带上：
89
+
90
+ ```bash
91
+ curl -H "Authorization: Bearer ct-你的Key" "https://api.ashareapi.com/v1/quote?code=sh600667"
92
+ ```
93
+
94
+ ---
95
+
96
+ ## 能查什么
97
+
98
+ **免费（无需 Key）**
99
+
100
+ 实时行情 · K线 · 热搜榜 · 涨跌分布 · 市场总览
101
+
102
+ **需 Key**
103
+
104
+ 五档盘口 · 全字段画像 · 财务三表 · 资金流 · 技术指标 · 股东 · 事件 · 龙虎榜 · 因子选股 · 板块 · 板块估值 · 宏观 · 可转债 · ETF · 新股 · 分红 · 脱水研报 · 代码搜索 · 用量
105
+
106
+ 字段含义、参数与返回样例见[文档](https://ashareapi.com/docs/)。
107
+
108
+ ---
109
+
110
+ ## 相关
111
+
112
+ **官方 SDK**：Python `pip install ashareapi` · Node.js / TypeScript `npm install ashareapi`
113
+
114
+ **MCP 服务器**：`https://api.ashareapi.com/mcp`（[配置说明](https://ashareapi.com/mcp)）—— Pi **内置 MCP**，填一条 URL 就能接；Claude Code / Codex / Cursor 等 19 家客户端同样
115
+
116
+ **Agent Skill**（给 AI 读的接口说明书）：<https://ashareapi.com/skill>
117
+
118
+ **本包内容**由脚本从 Agent Skill 生成（单一事实源：<https://github.com/ashareapi/ashareapi-skill>），不手工维护。
119
+
120
+ ---
121
+
122
+ ## 版本
123
+
124
+ 最新版本见 [npm](https://www.npmjs.com/package/ashareapi-pi)。本包内容来自 Agent Skill，**版本号与 skill 一致**；变更见 [ashareapi.com/changelog](https://ashareapi.com/changelog)。
125
+
126
+ ---
127
+
128
+ ## License
129
+
130
+ MIT
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "ashareapi-pi",
3
- "version": "0.2.5",
4
- "description": "A股数据 API 官方 Pi 包 —— 装上即可查 A 股行情 / K线 / 财务 / 资金 / 龙虎榜（32 个端点说明书，开放标准 Agent Skills）",
3
+ "version": "0.2.7",
4
+ "description": "A股数据 API 官方 Pi 包 —— 装上即可查 A 股行情 / K线 / 财务 / 资金 / 龙虎榜（33 个端点说明书，开放标准 Agent Skills）",
5
5
  "keywords": [
6
6
  "pi-package",
7
7
  "pi",