---
name: liveppp-market-data
description: LivePPP 行情数据接入指引（支持 A 股与美股实时/历史行情）
version: 0.2.0
---

# LivePPP 行情数据智能助手接入指引

本指引适用于所有 AI 助手（包括腾讯 WorkBuddy、豆包、Coze、通义、Kimi、文心、Dify、Claude、Cursor 等），指导你通过 LivePPP 获取中国 A 股（沪深京）与美股的实时及历史行情数据。

---

### 0. 你能执行命令吗？
在开始前，请自检当前运行环境是否具备执行 Shell 命令的能力：
- **如果你不能执行命令**（例如纯文本对话界面或没有命令执行权限的沙箱）：
  **绝对不要假装执行命令或编造假输出**！请直接明确告知用户你无法在当前环境自动执行命令，并将下方步骤中的命令行原样提供给用户，提示用户在自己的终端中复制执行。
- **如果你能执行命令**：
  请由你（智能体）主动按序执行以下步骤，不要把本来该由你自动完成的操作推给用户。

---

### 1. 检查与安装 CLI
检查系统中是否已安装 `liveppp`：
```bash
command -v liveppp
```
如果命令未找到（返回值为空）：
1. 执行一键安装脚本：
   ```bash
   curl -fsSL https://app.liveppp.com/install.sh | sh
   ```
2. 将 `$HOME/.local/bin` 添加进当前 PATH：
   ```bash
   export PATH="$HOME/.local/bin:$PATH"
   ```

---

### 2. 配置与验证 API Key
如果当前环境尚未配置 API Key，请主动向用户索要 LivePPP API Key：
- **安全纪律**：绝对不要猜测 API Key；绝对不要在终端或对话中打印/回显 Key；绝对不要将 Key 写入任何临时文件或提示词中。
- 获得 Key 后，通过 CLI 登录保存凭证（配置文件会自动设置为 0600 严格权限）：
  ```bash
  liveppp login --key <用户提供的API Key>
  ```
- 运行状态查询命令确认额度：
  ```bash
  liveppp status
  ```
  确认账户处于有效状态且配额充足。

---

### 3. 注册 MCP（宿主支持时）
运行 MCP 注册命令：
```bash
liveppp connect
```
- 如果你所在的宿主环境支持 MCP（如 Claude Desktop、Claude Code、Cursor、VS Code、Cline 等），该命令会自动检测并完成配置写入与回读校验。
- 如果你所在的宿主助手**不支持 MCP 客户端协议**（如腾讯 WorkBuddy、豆包、Coze、通义、Kimi、文心、Dify 等大多数国内助手）：
  **请直接跳过此步骤**，并向用户明确说明当前环境无需配置 MCP 客户端，后续将通过 Shell 命令与 HTTP/curl 直接取数。

---

### 4. 连通性体检（Doctor）
执行全链路诊断检查：
```bash
liveppp doctor
```
- **全部 PASS 才继续**：只有当所有检查项（Key 检测、健康检查、MCP 初始化握手）均显示为 PASS 时，才允许继续后续的取数操作。
- **失败即停止**：若有任何一项检查失败，必须原样向用户报出失败项与对应的补救提示（Remedy），并立即停止操作，切勿盲目继续请求接口。

---

### 5. 不支持 MCP 的助手怎么取数（HTTP / curl 方式）
> **重要事实**：LivePPP 服务**没有**任何诸如 `GET /v1/bars` 的传统 REST 行情接口。所有行情数据统一通过 MCP JSON-RPC 端点提供：`POST https://api.liveppp.com/mcp`。

对于不支持 MCP 协议的智能体，使用 `curl` 直接调用 MCP JSON-RPC 端点取数：
- **请求端点**：`POST https://api.liveppp.com/mcp`
- **必需头部**：
  - `Authorization: Bearer $LIVEPPP_KEY`（或从 `~/.config/liveppp/config.json` 读取的 token，或用户传入的 key）
  - `Content-Type: application/json`
  - `accept: application/json, text/event-stream`
- **响应格式**：服务可能返回 `application/json`，也可能返回 `text/event-stream`（SSE 流）。若返回 SSE 流，请提取其中以 `data: ` 开头的行，并将其作为 JSON 解析。

标准调用流程分为三步：

#### 第一步：initialize 协议握手
```bash
curl -s -X POST https://api.liveppp.com/mcp \
  -H "Authorization: Bearer $LIVEPPP_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "curl-agent", "version": "1.0.0" }
    }
  }'
```

#### 第二步：获取可用工具列表（tools/list）
> **注意**：`tools/list` 会消耗少量配额。请仅在初次了解工具定义与参数 Schema 时调用一次，切勿每次查询行情都例行调用。
```bash
curl -s -X POST https://api.liveppp.com/mcp \
  -H "Authorization: Bearer $LIVEPPP_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'
```
从返回的工具列表中，查看各工具的 `name`、`description` 和 `inputSchema`（输入参数规范）。

#### 第三步：调用具体工具取数（tools/call）
按返回的 schema 与具体工具名称动态构建请求，切勿随意臆造工具名或参数名：
```bash
curl -s -X POST https://api.liveppp.com/mcp \
  -H "Authorization: Bearer $LIVEPPP_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "<tools/list 中返回的工具名>",
      "arguments": {
        "<参数名>": "<参数值>"
      }
    }
  }'
```
（注：若响应返回为 SSE 格式，提取 `data: ` 开头行的 JSON，读取 `result.content` 获得行情数据。）

---

### 6. 配额纪律
为保护你的账户额度，请严格遵守以下规则：
1. **不要循环轮询**：禁止编写死循环或定时轮询代码拉取行情。LivePPP 是按需查询服务，仅在回答用户具体问题时单次获取所需数据。
2. **不要例行 tools/list**：在初次了解工具列表后，应直接调用 `tools/call`，避免在每次查询前重复调用 `tools/list` 浪费配额。
3. **按需精准取数**：严格根据用户提问明确标的代码（A 股加 `.SH` 或 `.SZ`，美股加 `.US`）与合理的时间周期/数据条数，避免大范围拉取不必要的历史数据。