docs: add TradeCat Sheets API usage guide
This commit is contained in:
tukuaiai
parent
d1466fc77e
commit
63513e553a
|
|
@ -337,6 +337,7 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真
|
|||
* [**通用项目架构模板**](./assets/documents/principles/fundamentals/通用项目架构模板.md): 多种项目类型的标准目录结构。
|
||||
* [**Augment MCP 配置文档**](./assets/documents/guides/playbook/auggie-mcp配置文档.md): Augment 上下文引擎配置说明。
|
||||
* [**系统提示词集合**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): AI 开发的系统提示词，含多版本开发规范（云端表格）。
|
||||
* [**TradeCat Sheets API 使用说明**](./assets/documents/guides/playbook/tradecat-sheets-api-usage.md): 把公开 Google Sheet 当作 API 注册表与数据面（Data Plane），供 Agent/服务端消费结构化 JSON。
|
||||
* [**外部资源（在线表格）**](./assets/README.md): 外部资源的唯一真相源（按类型分表），本地 Markdown 保留为历史参考。
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -13,6 +13,7 @@
|
|||
- [LazyVim 快捷键大全](./LazyVim快捷键大全.md) - Neovim 配置框架
|
||||
- [Augment MCP 配置](./auggie-mcp配置文档.md) - 上下文引擎配置
|
||||
- [ProxyCast 配置](./ProxyCast配置文档.md) - AI 凭证代理服务配置
|
||||
- [TradeCat Sheets API 使用说明](./tradecat-sheets-api-usage.md) - 把公开 Google Sheet 当作 API 注册表与数据面（Data Plane）
|
||||
- [手机远程 Vibe Coding](./关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md) - 基于 frp 的远程开发
|
||||
- [VS Code Remote Tunnel（WSL）](./REMOTE_TUNNEL_GUIDE.md) - 在 WSL 内开通 VS Code Tunnel 供远程访问
|
||||
- [GEMINI-HEADLESS](./GEMINI-HEADLESS.md) - Gemini 无头模式配置
|
||||
|
|
|
|||
|
|
@ -0,0 +1,167 @@
|
|||
# TradeCat Sheets API 使用说明（公开表格 + API 注册表）
|
||||
|
||||
本文档用于把 TradeCat 的公开 Google Sheet 当作 **Agent 可消费的数据面（Data Plane）**：通过 `API` 表（注册表）发现端点，并用表内提供的请求命令拉取结构化 JSON（行情/指标/预测市场/实时新闻）。
|
||||
|
||||
> 更新时间：2026-03-17（以 `API` 表导出时间为准）
|
||||
|
||||
---
|
||||
|
||||
## 1. 公共链接
|
||||
|
||||
- 在线表格（含 `API` 注册表页）：
|
||||
`https://docs.google.com/spreadsheets/d/1q-2sXGsFYsKf3nV5u5golTVrLH5sfc0doiWwz_kavE4/edit?usp=sharing`
|
||||
|
||||
---
|
||||
|
||||
## 2. 你得到的是什么
|
||||
|
||||
### 2.1 `API` 表 = Endpoint Registry（端点注册表）
|
||||
|
||||
`API` 表每一行对应一个端点，包含三列：
|
||||
|
||||
- `jsonl`：端点返回的 JSON（通常包含压缩 payload）
|
||||
- `说明`：端点用途/结构（人读）
|
||||
- `请求命令`：可复制执行的命令（机器读/人也可直接复制）
|
||||
|
||||
### 2.2 推荐用法：直接复制 `请求命令`
|
||||
|
||||
表中 `请求命令` 通常是 `curl ... | python3 -c ...`：
|
||||
|
||||
- `curl` 从 Google Sheets gviz 接口取出该行 `jsonl`
|
||||
- `python3 -c` 负责解析 JSON、解压 `gzip_b64`（如存在）并输出最终结构化 JSON
|
||||
|
||||
这样做的好处：
|
||||
- 不需要你自己实现 gzip_base64 解码逻辑
|
||||
- 输出格式相对稳定（以表内命令为准）
|
||||
|
||||
---
|
||||
|
||||
## 3. 快速开始
|
||||
|
||||
### 3.1 拉取 API 注册表（CSV）
|
||||
|
||||
```bash
|
||||
SHEET_ID="1q-2sXGsFYsKf3nV5u5golTVrLH5sfc0doiWwz_kavE4"
|
||||
curl -fsSL "https://docs.google.com/spreadsheets/d/${SHEET_ID}/gviz/tq?tqx=out:csv&sheet=API&headers=0" > api.csv
|
||||
```
|
||||
|
||||
### 3.2 列出端点标题（从 `jsonl` 里解析）
|
||||
|
||||
```bash
|
||||
python3 - <<'PY'
|
||||
import csv, io, json, sys
|
||||
raw=open("api.csv","r",encoding="utf-8",errors="replace").read()
|
||||
rows=list(csv.reader(io.StringIO(raw)))
|
||||
for r in rows[3:]: # 跳过 banner/导出信息/表头
|
||||
if len(r) < 1 or not r[0].strip().startswith("{"):
|
||||
continue
|
||||
try:
|
||||
obj=json.loads(r[0])
|
||||
except Exception:
|
||||
continue
|
||||
sheet=(obj.get("data") or {}).get("sheet") or {}
|
||||
title=sheet.get("title")
|
||||
gid=sheet.get("gid")
|
||||
payload=(obj.get("data") or {}).get("payload") or {}
|
||||
schema=payload.get("schema") or payload.get("facts_schema") or ""
|
||||
if title:
|
||||
print(f"- {title} (gid={gid} schema={schema})")
|
||||
PY
|
||||
```
|
||||
|
||||
### 3.3 拉取某个端点（推荐）
|
||||
|
||||
到表格 `API` 页，找到目标端点行，复制其 `请求命令` 直接执行即可。
|
||||
|
||||
---
|
||||
|
||||
## 4. 返回格式（Envelope）
|
||||
|
||||
端点 JSON 通常遵循如下“信封”结构（字段名以实际返回为准）：
|
||||
|
||||
- `code` / `msg` / `success`：状态
|
||||
- `data.banner`：公告/广告位等文本（消费方可选择忽略）
|
||||
- `data.meta`：生成时间、生产者、语言等
|
||||
- `data.sheet`：来源表格信息（`spreadsheet_id/gid/title`）
|
||||
- `data.payload`：**真正的数据**（可能包含压缩编码或已解码后的事实列表）
|
||||
|
||||
强烈建议消费方至少校验：
|
||||
- `data.payload.schema`（或 `facts_schema`）是否是预期的 schema
|
||||
- `data.meta.generated_at` / `export_time` 是否足够新鲜
|
||||
|
||||
---
|
||||
|
||||
## 5. Schema 说明（当前已观察到）
|
||||
|
||||
> 以 `API` 表当前内容为准；未来可能新增 schema。
|
||||
|
||||
### 5.1 `table_rows_v2`
|
||||
|
||||
用于“表格快照”类数据（看板/Polymarket/新闻）。
|
||||
|
||||
典型用途：
|
||||
- 看板总览、Top 列表、统计表、新闻流
|
||||
|
||||
消费建议：
|
||||
- 以 `facts[]`（如存在）为单一事实来源
|
||||
- 每条 fact 通常包含维度（dims）与字段（fields_text/fields_num）等
|
||||
|
||||
### 5.2 `symbol_query_v2`
|
||||
|
||||
用于“单币种多周期指标面板”类数据（BTC/ETH/BNB/SOL）。
|
||||
|
||||
典型用途：
|
||||
- 单币画像、指标诊断、策略特征输入、AI 分析上下文
|
||||
|
||||
消费建议：
|
||||
- 以 `facts[]`（如存在）为单一事实来源
|
||||
- 不要依赖 UI 文案；依赖结构化指标字段
|
||||
|
||||
---
|
||||
|
||||
## 6. 端点清单（2026-03-17 快照）
|
||||
|
||||
以下端点来自 `API` 表当前解析结果（title/gid/schema）：
|
||||
|
||||
### 市场总览（table_rows_v2）
|
||||
|
||||
- 加密货币看板（gid=1277788455, schema=table_rows_v2）
|
||||
- 宏观大宗看板（gid=1931661963, schema=table_rows_v2）
|
||||
|
||||
### 单币画像（symbol_query_v2）
|
||||
|
||||
- 币种查询_BTCUSDT（gid=1325757221, schema=symbol_query_v2）
|
||||
- 币种查询_ETHUSDT（gid=904473439, schema=symbol_query_v2）
|
||||
- 币种查询_BNBUSDT（gid=78880380, schema=symbol_query_v2）
|
||||
- 币种查询_SOLUSDT（gid=208400041, schema=symbol_query_v2）
|
||||
|
||||
### 预测市场（table_rows_v2）
|
||||
|
||||
- PolymarketTop15（gid=1715937602, schema=table_rows_v2）
|
||||
- Polymarket时段分布（gid=333189916, schema=table_rows_v2）
|
||||
- Polymarket类别偏好（gid=1923964075, schema=table_rows_v2）
|
||||
|
||||
### 实时新闻（table_rows_v2）
|
||||
|
||||
- 实时新闻（gid=1419246950, schema=table_rows_v2）
|
||||
|
||||
---
|
||||
|
||||
## 7. 可靠性与调用建议（给 Agent/服务端）
|
||||
|
||||
由于底层是公开 Google Sheet：
|
||||
|
||||
- 建议做 **缓存**（例如 5～60 秒，按业务容忍度）
|
||||
- 建议做 **退避重试**（遇到 429/5xx 时指数退避）
|
||||
- 建议做 **降级策略**
|
||||
- 表不可用：降级为“只读旧缓存”
|
||||
- 新闻不可用：只跑行情/指标
|
||||
- schema 不匹配：拒绝消费该批数据
|
||||
|
||||
---
|
||||
|
||||
## 8. 合规与安全边界
|
||||
|
||||
- 本接口与本文档不构成投资建议；仅用于研究与协作交流。
|
||||
- 不要在任何公开场合贴出内部密钥/Token（本表为公开资产，不应包含密钥；但消费方也不应添加敏感头部到公开日志里）。
|
||||
|
||||
Loading…
Reference in New Issue