Yyqdata Stock Skill

yyqdata

⚡ FIRST CALL — 第一个请求照抄这个，别探别猜

本服务是股票数据 REST API，不是 OpenAI/LLM 兼容端点。token 自查只有一个端点：

BASE="${YYQDATA_API_BASE_URL:-http://120.220.73.199}"      # base_url 只到主机，不含 /openapi
TOKEN="${YYQDATA_TOKEN:?把 stk_live_ token 填进来}"
curl -sf -X POST "${BASE}/openapi/v1/whoami" -H "Authorization: Bearer ${TOKEN}"
# 返回 tier / scopes / rateLimitPerMin / llmHint，证明 token 有效 + 拿到套餐

❌ 下面这些路径全都不存在，别去试（试了只会 404）： /v1/whoami · /v1/token/info · /token/info(无前缀) · /whoami(无前缀) · /auth/whoami · /v1/auth/whoami · /v1/models · /models · /v1/chat/completions

✅ 唯一正确的 token 自查 = POST /openapi/v1/whoami（别名 /openapi/v1/token/info，仍需 /openapi/v1 前缀）。 ✅ 所有数据接口也都在 /openapi/v1/** 下（如 /openapi/v1/stock/kline/daily）。 ⚠️ /openapi 是路径的一部分，不是 base_url 的一部分——base_url 只到 http://120.220.73.199，调用时务必拼成 ${BASE}/openapi/v1/...。误探无前缀路径会收到一段引导 JSON（hint 字段指回正确端点）。

🔴 第一铁律：没真调过接口，禁止下任何"没有数据"的结论

这是本 skill 优先级最高的规则，凌驾于下面所有内容之上。 LLM agent 最常见、对用户伤害最大的失败就是"没查就说没有"——本节专门根除它。

• "没有 / 查不到 / 后端是空的 / 不支持"这类否定结论，必须同时满足两条：① 你已用正确端点 + camelCase 字段 + 正确日期格式实际发过请求；② 你手里有那次请求返回的 traceId（或完整 {code,msg}）。拿不出 traceId，就不准对用户说"没有"。
• whoami 通过 ≠ 数据已验证。 whoami 只证明"token 有效 + 套餐 scope + 路径配置"，它不是任何业务数据的查询。看到 whoami 成功就回答"有/没有某某数据"是纯幻觉。
• scope 列表里有这个维度 = 你有权限查 = 你必须真去查一次再说。 例：whoami 的 scopes 含 derivative，用户问期权 → 你必须真打 /openapi/v1/derivative/option/* 才能下结论，不能凭印象说"期权数据是空的"。
• 空响应不是终点，是自检起点。 真拿到空 data 时，先走下面〔空结果 6 问自检〕逐条排除参数/日期/scope 错误，确认无误后才能向用户说"该条件下确实无数据"，并附上你试过的端点 + body + traceId。
• 📌 真实教训（2026-06）：某 agent 仅调了一次 whoami 就对用户说"期权数据后端是空的"。实际后端 option_daily 有 2000 万+ 行、恰好含用户要的交易日。这是本 skill 要根除的头号失败模式——你读到这里，就别再犯。

空结果 7 问自检（说"没有"之前逐条过一遍）

1. 我真的发请求了吗？ —— whoami / 看文档 / 凭记忆都不算。没有 traceId = 没查。

2. 字段是 camelCase 吗？ —— tradeDate 不是 trade_date，tsCode 不是 ts_code。snake_case 被忽略 → 端点拿默认值 → 看似"空"。

3. 日期格式对吗？ —— 必须 YYYYMMDD（宏观月度 YYYYMM / GDP YYYYQX）。带 - / / / ISO / 时间戳全被当未传。

4. 占位符替换了吗？ —— body 里不能真的出现 <最新> ${...} 这种字面量；必须换成真实值（日期自己算、tsCode 先 search）。

5. scope / 端点选对了吗？ —— market（国内宏观，URL /market/）vs stock.market（个股市场行为，URL /stock/market/）、单合约 option/kline/daily vs 全市场 option/kline/daily-by-date 别搞反；403 是没套餐（不是没数据），先看 whoami。

6. 省略的枚举字段补显式值了吗？ —— 个别 int 枚举字段（如 kline/daily 的 type）在老版本服务端缺省时不走文档默认值而静默返回空。空结果且 body 里省略过枚举字段时，补显式默认值（如 type:11）重试一次。

7. 返回值格式没踩坑吗？ —— 以下场景数据明明有但因格式误判漏掉：

   • ⚠️ K线系响应日期四种格式：stock/kline/daily 的 tradeDate 是 "YYYY-MM-DD" 带横杠字符串（非 YYYYMMDD！同时有 time 毫秒字段）；stock/index/kline/daily 和 stock/kline/percentage-change 的 tradeDate 是毫秒时间戳；stock/kline/limits 和 stock/kline/adj-factor 的 tradeDate 是 YYYYMMDD 紧凑字符串（⚠️ adj-factor 虽名字带 kline 但不是毫秒，与 hk/adj-factor、us/adj-factor 不同——后两者是毫秒时间戳）
   • 以下端点响应日期字段是毫秒时间戳 long（不是字符串，需 ÷1000 转秒或 ÷86400000 转天对比）：stock/indicator/ 整个 scope（含 roe.endDate） · financial/{income-statement,balance-sheet,cash-flow,indicator,repurchase,express,disclosure-date} annDate/endDate（⚠️ repurchase 还有 expDate 也是 ms；disclosure-date 的 preDate/actualDate/modifyDate 也是 ms） · stock/index/kline/daily · stock/index/kline/weekly · stock/index/kline/monthly · stock/index/dailybasic · stock/index/weight · stock/index/sw-industry-quo · stock/index/main/snapshot · stock/index/main/history · stock/indicator/idx-factor-pro · stock/kline/percentage-change · stock/kline/weekly-monthly(tradeDate+endDate 均 ms) · stock/kline/week-month-adj(tradeDate+endDate 均 ms) · option/kline/daily · option/kline/minutes · derivative/futures/kline/daily · derivative/futures/holding · derivative/futures/main-contract · derivative/futures/wsr · derivative/sge/kline/daily · hk/kline · hk/kline-adj · hk/adj-factor(tradeDate) · hk/minute · hk/fina-indicator endDate · hk/income/balance-sheet/cash-flow(endDate 均 ms) · us/kline(tradeDate) · us/kline-adj(tradeDate) · us/adj-factor(tradeDate) · us/income/balance-sheet/cash-flow(endDate 均 ms) · us/fina-indicator(endDate) · ths-hot（rankTime 更直观）· ths-daily · limit-step · limit-cpt-list · cyq-chips · hm-detail · forex/daily · plate（快照）/plate/list/plate/cash-flow tradeDate · plate/continue-net lastDate · plate/stocks-indicator(tradeDate 响应是 ms，入参用 YYYY-MM-DD) · intl-macro/ 全部9端点（字段 date）· fund/etf/kline/daily · fund/etf/share-history · research/report · research/report-rc(reportDate) · news/list newsTime · eco-cal（字段 date） · bak-daily(tradeDate) · bak-basic(tradeDate+listDate) · st-daily 响应(tradeDate) · st-warning(pubDate/impDate) · shareholder/ccass-hold(tradeDate) · shareholder/ccass-detail(tradeDate) · shareholder/hk-hold(tradeDate) · shareholder/ggt-daily(tradeDate) · shareholder/hsgt-list(tradeDate) · kpl/kpl-concept-cons(tradeDate) · market/tdx-daily(tradeDate) · market/tdx-index(tradeDate) · market/tdx-member(tradeDate) · market/ci-daily(tradeDate) · market/ci-index-member(inDate/outDate) · futures/weekly-detail(weekDate) · lhb/details(tradeDate)。financial/core · financial/business-segment · financial/pledge · dividend · macro系 · kline/limits · kline/adj-factor · futures/settle · futures/limit · option/contracts日期 等是字符串（YYYYMMDD 或 "YYYY-MM-DD"）。⚠️ 注意例外：mainboard/news-sentiment/moneyflow/moneyflow-dc/block-trade/cyq-perf/limit-analysis/hsgt-top10 的 tradeDate 是 YYYYMMDD 字符串（非毫秒，属于 stock.market scope 内例外）
   • ⚠️ stock/kline/index-minute 的响应日期字段名是 tradeTime（不是 tradeDate！） = 毫秒时间戳——代码里按 tradeDate 取值永远是 undefined/null
   • ⚠️ hk/tradecal 和 us/tradecal 的响应日期字段名是 calDate（不是 tradeDate！） = 毫秒时间戳；同时有 pretradeDate（也是毫秒）和 isOpen(0/1)
   • ⚠️ 港股/美股复权因子字段是 cumAdjfactor，A股是 adjFactor，两者字段名不同——混淆后永远拿不到正确的复权因子值
   • callPut 定长空格补齐（"C "），== "C" 全漏，先 trim()
   • index-minute（idx_mins）混传 tradeDate + startDate 时 tradeDate 做精确 AND → 返空；只传 startDate+endDate 或只传 tradeDate
   • bond/yc 不传日期 → 按全库无过滤返空；news/list type 传空 → 精确匹配 NULL → 空

7 条都排除、仍是空 → 才可以说"该条件下无数据"，并说明最可能原因（非交易日 / 未上市 / 未入库 / 筛选过严）。

🎯 操作主循环（每轮照此走 · 这是全文骨架）

本文档近千行，别从头读到尾。把下面 7 步当成你处理每个股票请求的骨架，哪一步拿不准再跳到对应章节深读。

0. 更新检查（每天一次，静默）            → 〔skill 自动更新〕
1. 备好 token+BASE，探 whoami 一次       → 落〔会话记忆卡〕，别反复探
2. 意图分类 → 选 WF-1~10                 → 〔Decision tree〕/〔意图到端点〕
3. 标的规范化：search 拿 tsCode          → 永不凭记忆拼码；已解析的复用记忆卡
4. 取数：camelCase + YYYYMMDD，真调接口   → 〔怎么发请求〕；铁律：没真调不下结论
5. 交付前自检门（reflection gate）        → 〔交付前自检门〕
6. 交付：结论先行 + 口径 + 异常 + CSV 路径 → 〔Output contract〕

长任务（全市场扫描 / 多页拉取）：边拉边落 CSV + 存进度检查点；上下文吃紧先写进度再续，别重拉 → 〔会话记忆 & 长任务行为〕。

---

🚀 平台快速启动（Platform Quick-Start）

Token 读取顺序（所有平台统一）

# 1. 环境变量（平台自动注入，如有）
TOKEN="${YYQDATA_TOKEN}"
BASE="${YYQDATA_API_BASE_URL:-http://120.220.73.199}"

# 2. skill 目录内的 config.json（推荐持久化方式，平台无关）
#    ⚠️ 不要假设 jq 存在（很多实例没装）：jq → python3 → sed 三级降级，保证一定能读出来
if [ -z "$TOKEN" ]; then
  for _d in ~/.openclaw/skills/yyqdata ~/.hermes/skills/yyqdata ~/.claude/skills/yyqdata; do
    _cfg="$_d/config.json"
    [ -f "$_cfg" ] || continue
    if command -v jq >/dev/null 2>&1; then
      TOKEN=$(jq -r '.token // empty' "$_cfg" 2>/dev/null)
      _b=$(jq -r '.base_url // empty' "$_cfg" 2>/dev/null)
    elif command -v python3 >/dev/null 2>&1; then
      TOKEN=$(python3 -c "import json,sys;print(json.load(open(sys.argv[1])).get('token') or '')" "$_cfg" 2>/dev/null)
      _b=$(python3 -c "import json,sys;print(json.load(open(sys.argv[1])).get('base_url') or '')" "$_cfg" 2>/dev/null)
    else
      TOKEN=$(sed -n 's/.*"token"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$_cfg" | head -1)
      _b=$(sed -n 's/.*"base_url"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$_cfg" | head -1)
    fi
    [ -n "$_b" ] && BASE="$_b"
    [ -n "$TOKEN" ] && break
  done
fi

# 3. 对话中用户提供（兜底）
[ -z "$TOKEN" ] && echo "⚠️ 未找到 token，请用户提供 stk_live_xxx 格式 token"

config.json 格式（放在 skill 安装目录内，不随 zip 发布）：

{ "token": "stk_live_xxx", "base_url": "http://120.220.73.199" }

快速健康验证：

curl -sf -X POST "${BASE}/openapi/v1/whoami" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '{tier: .data.tierLabel, scopes: .data.scopes}'

A · 通用 / 手动（Claude Code / API / 其他 agent）

用户在对话中提供 stk_live_xxx token；agent 在会话内存中持有，不落盘：

TOKEN="stk_live_<用户给的值>"
BASE="http://120.220.73.199"

curl -sf -X POST "${BASE}/openapi/v1/whoami" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '{tier: .data.tierLabel, scopes: (.data.scopes | length)}'

D · 受限环境（仅 GET / 无 curl / 沙箱）

GET ${BASE}/openapi/v1/stock/basic/search?nameOrCode=茅台&token=${TOKEN}

任何能发 HTTP GET 的工具（web_fetch / Invoke-WebRequest / Python requests）都可用；camelCase 字段拼 query param，?token= 等价于 Bearer header。

---

⛔ 硬性约束（必读，违反即失败）

1. 只能调用本文档明确列出的端点：所有数据请求都打到 ${BASE}/openapi/v1//（GET 或 POST 皆可，见第 3 条）。不要自创路径、不要从工具名拼 URL（如 /stock/api/getXxx 一定 404）。拿不准端点路径 / 字段名 → 先 grep references/api-quick-reference.md（速查表）确认再调，别凭记忆拼；速查表没有就当它不存在，不要臆造。
2. 每个请求必须带 token：首选 Authorization: Bearer ${TOKEN} 头；无法设请求头的环境用 ?token=${TOKEN} 查询参数（见第 3 条）。token 两种来源：①claw 托管实例——claw 在开通时已把 token 注入环境变量 $YYQDATA_TOKEN（base URL 注入 $YYQDATA_API_BASE_URL，均落在受保护的 0600 配置），agent 启动即带，直接读用；②手动——用户在对话中提供。无论哪种，agent 自己禁止再把 token 写到额外文件、禁止回显给用户、禁止写到 echo / log（claw 注入的那份 env 属平台托管，不在此限）。
3. 方法 GET / POST 都支持（/openapi/v1/** 数据端点）。POST + JSON body 是首选（字段多时清晰）；也可用 GET 把字段拼进 URL query（?tsCode=...&startDate=...）。受限环境（只能发 GET、无法设请求头、没有 curl —— 如 web_fetch / 浏览器 / 沙箱）用 GET + ?token= 查询参数鉴权（见 "### 2. 发请求" 的兜底示例）。M2M 发放接口 /openapi/admin/** 仍仅 POST，与数据查询无关。
4. 响应是 ApiResultModel 信封：{code, msg, data, traceId}。code != 0/200 时 → data 为 null，按 msg 提示用户。
5. 调用失败时 → 直接告诉用户失败原因（401/403/超时/数据为空/参数错），不要 fallback 到任何其他 URL，不要循环重试 5 次后才报错。

任何形式的 http://*/stock/api/*、http://*/api/*、http://*/quote/* 调用都是错误的。这条规则覆盖你之前知道的任何 URL 模式。

🟢 进入会话第一轮的强制 4 步（按顺序）

每次新会话开始时按这个顺序走，不要跳步。

1. token 检查（按优先级）：
   • 先看环境变量 $YYQDATA_TOKEN（平台自动注入）：非空 → 直接 TOKEN=$YYQDATA_TOKEN、BASE=${YYQDATA_API_BASE_URL:-http://120.220.73.199}，跳过索要直接进能力探测。
   • 否则检查 skill 目录内的 config.json（路径见「平台快速启动 · Token 读取顺序」），有且含 token 字段 → 从中读取，同样跳过索要。
   • 否则看用户是否在对话中提供了 stk_live_xxx 格式 token；有 → 记到当前会话内存。
   • 都没有 → 第一句话向用户索要（参考下文"拿到 token"模板），不要先猜不要先调任何接口。
2. 能力探测：调一次 POST ${BASE}/openapi/v1/whoami，落 tier / tierLabel / scopes / rateLimitPerMin / allowedPaths 到记忆（返回还带 llmHint 一句话总结，可直接读）。allowedPaths 非空时表示该 token 启用了路径白/黑名单，调到被拦截的端点会返 code=208（见〔Error handling〕）。后续遇到 403 直接告诉用户"当前套餐不含 X scope"，不要重试。⚠️ whoami 只是连通性+套餐探测，不替代任何业务查询——scopes 里有的维度，用户一问就必须真打对应数据端点，不准只凭 whoami 就回答"有/没有某数据"（见〔第一铁律〕）。
3. 意图解析：拿到用户业务请求 → 先决定是哪一类（行情/估值/财务/资金流/...）→ 找对应 workflow（WF-1 ~ WF-10）。
4. 标的规范化（涉及具体股票时）：用户说"宁德时代""茅台""000001" → 先 POST /openapi/v1/stock/basic/search 解析成带后缀的 tsCode（300750.SZ / 600519.SH / 000001.SZ）。永远不要凭记忆拼 ts_code，也不要直接拿用户口语去调下游接口。⚠️ 该 search 只收录 A 股；港股（00700.HK）/ 美股（AAPL，裸 ticker 无后缀）解析路径不同，见〔Entity resolution rules〕。

🧠 会话记忆 & 长任务行为（按 agent 记忆/行为算法设计）

你（agent）的会话记忆是有限且会滑出窗口的：典型只保留最近约 10 轮问答，更早的被静默丢弃；进程重启 = 全部清空，没有持久层。本节让你在这种约束下不丢状态、不重复劳动、不半路放弃。（这套规则借鉴了宿主 agent 的工作记忆 / 检查点压缩 / 执行偏向算法。）

1. 维护一张「会话记忆卡」（working memory）

首次探测后，在脑内维护一个紧凑状态块，并在它可能滑出窗口时主动复述刷新：

[yyqdata 记忆卡]
TOKEN: 已持有(env/对话)   BASE: http://...   tier: Max   rateLimit: 300/min
scopes: [stock.kline, derivative, ...]            # whoami 拿到一次就够，别反复探
已解析: 宁德时代=300750.SZ  茅台=600519.SH         # search 过的别再 search
最近交易日: 20260604                               # lhb/latest-dates 拿到就复用
本会话已查: kline/daily(300750)、moneyflow(300750)

• 先查记忆卡，再调接口：要用的 tsCode / 最近交易日 / scope 若卡里已有，直接复用，别重复 search / whoami / latest-dates（省限频、省轮次）。
• 但别赖记忆超过窗口：拿不准卡里的值是否还在上下文里，就重查一次——数据端点有缓存，重查不额外计费。

2. 长任务：检查点 + 增量落盘（别一次性扛在脑子里）

全市场扫描 / 多页拉取（期权 daily-by-date 翻几十页、多标的对比、龙虎榜全量）这类长任务：

• 边拉边落 CSV，不要把几千行积在上下文里——上下文是你最稀缺的资源。
• 维护进度检查点：已完成: SHFE 全量 + DCE page1-5；下一步: DCE page6，让自己（或下一轮）能续跑而非重来。
• 上下文吃紧（估算 >本轮预算 ~80%）时：先把"进度 + 已落盘路径"写进回复，再继续 / 交接，严禁从头重拉。
• 翻页有硬上限就显式告诉用户截断了多少（"只取了成交额前 500，按 X 排序"），不要假装拉全了。

3. 跨会话 / 定时任务：状态必须自包含

用户让你做定时 / 重复查询（"每天早上发我自选股表现"）时，牢记：定时任务在全新会话里触发，没有任何历史记忆。所以——

• token 走环境变量 $YYQDATA_TOKEN（平台注入，会持久）——别把 token 写进任务提示词。
• 业务状态必须写进任务提示词自包含：已解析的 tsCode 列表、查询参数、时间窗，以及（claw / hermes 环境下）回推消息用的 conversation_id（原样回显，别解析）。
• 别依赖"我上次记得用户要看哪几只"——那段记忆在新会话里根本不存在。

4. 执行偏向（behavior）

• 能动手就别只给计划：任务可执行时，本轮就发出真实调用，不要停在"我接下来会查…"。（呼应〔第一铁律〕：结论必须由真实响应支撑。）
• 多步任务给进度：3 步以上的活，中途留一行进度（"第 2/5 步：已取行情，正在拉资金流"），别长时间沉默。
• 失败优雅退化：分段拉取部分失败时，交付已成功的部分 + 明确标注哪段失败，不要因一段失败就放弃整单（见〔部分成功原则〕）。

🔄 skill 自动更新（每天第一轮静默检查一次）

每个新会话的第 0 步（在上面"4 步"之前，但只跑一次/天）：

# 异步、超时 5s、失败不阻塞业务流程。
curl -fsSL --max-time 5 "https://static.yyqyx.com/skill/yyqdata.manifest.json" 2>/dev/null \
  | grep -oE '"version"[[:space:]]*:[[:space:]]*"[^"]+"' \
  | head -1 \
  | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)"/\1/'

把返回的 version 与本 SKILL.md 顶部 frontmatter 的 version 字段对比：

• 相等 / 拉取失败 → 静默继续，不要打扰用户。

• 远端 > 本地 → 在当轮回复末尾追加一行温和提示，例如：

  📦 提示：检测到 yyqdata 新版本 v1.2.0（当前 v1.1.0）。可让用户跑 bash ~/.openclaw/skills/yyqdata/update.sh 升级（或回复"升级 skill"由我替您跑）。

规则：

• 每 24 小时检查一次（agent 自行记忆上次检查时间戳）；同一会话内不重复检查。
• 不要为了升级而中断用户当前任务；不要自动跑 update.sh（升级是用户决策，因为会覆盖本地修改）。
• 用户明确要求升级时，可代跑 bash ${SKILL_DIR}/update.sh（SKILL_DIR = 本 SKILL.md 所在目录）；失败回退到提示用户手动 curl + unzip。
• update.sh 自动备份旧版到 yyqdata.bak-<时间戳>/，安全可回滚。

⚠️ 极易混淆的 scope（只看这一次）

market（国内宏观）和 stock.market（个股市场行为）容易混。两者都是 Pro scope，URL 前缀不同：

⚠️ 2026-06-08 whoami 实测：生产 scope 名仍是 stock.market（单一 scope），并非 stock.plate/lhb/moneyflow/sentiment。文档中出现的 4 个子 scope 名是未落地的设计，实际 whoami 只会返回 stock.market。

记忆口诀：stock.market 的 URL 一定带 /stock/market/；market（宏观）只带 /market/。market 是"大盘宏观背景"，stock.market 是"个股市场行为"。

类似地：stock.minute（分钟 K 线，Plus）≠ stock.kline（日/周/月 K，免费）；fund（基金 / ETF，Max）≠ bond（债券 / 可转债，Max）。

2026-05-22 新加 scope 易混淆点：

• stock.hk（Max+，港股本身：基础 / K 线 / 财务）≠ stock.shareholder 下的 /openapi/v1/stock/shareholder/hk-hold（港股通南向持股，仍在 stock.shareholder scope）
• stock.intl-macro（Max，境外宏观：美债 / HIBOR / LIBOR；URL 前缀是 /openapi/v1/intl-macro/*，不带 stock/；scope 名仍是 stock.intl-macro，2026-06-08 whoami 实测）≠ market scope 下的 /openapi/v1/market/macro/*（国内宏观：CPI/PPI/GDP/M2/Shibor/LPR）
• stock.us / stock.hk 的 K 线端点（/openapi/v1/stock/us/kline 等）≠ A 股 stock.kline（/openapi/v1/stock/kline/daily），路径前缀完全不同
• forex（Max，境外外汇 / CFD）≠ 任何 A 股相关 scope

怎么发请求（核心范式）

1. 拿到 token + base URL（优先级：环境变量 → 对话）

首次进入会话时按顺序检查：

(a) 环境变量已注入（推荐路径） 两种部署都会把 token 落到同一个环境变量，agent 侧逻辑完全一致：

• claw 托管实例：claw-server 自动开通时把 token 写进 $YYQDATA_TOKEN、base URL 写进 $YYQDATA_API_BASE_URL（落在受保护的 0600 配置，agent 启动即带）。
• OpenClaw 自装用户：在 openclaw 配置里给本 skill 配 skills.entries.yyqdata.apiKey = "stk_live_xxx"，openclaw 运行时会自动把它注入为 $YYQDATA_TOKEN（本 skill frontmatter 已声明 primaryEnv）。配一次永久生效，新会话不用重新贴 token。

先探一下：

test -n "$YYQDATA_TOKEN" && echo "env token present: ${YYQDATA_TOKEN:0:12}..."

非空 → 直接 TOKEN=$YYQDATA_TOKEN、BASE=${YYQDATA_API_BASE_URL:-http://120.220.73.199}，不必向用户索要，直接进能力探测。

(b) 手动 —— 用户在对话里给 没有 env token 时：

• 用户是否已经告诉你 OpenAPI token？（格式：stk_live_<48 字符>）
• 是否给了自定义 base URL？（默认 http://120.220.73.199）

如果都没有，第一句话就向用户索要，例如：

"我需要你的 OpenAPI token 才能调用数据后端，请提供（格式 stk_live_xxx，由后端管理员签发）。如不知道哪里拿，请联系后端管理员。"

拿到后：

• 在当前会话内记忆变量 TOKEN 和 BASE
• agent 自己禁止再写入任何额外文件（~/.bashrc / 日志 / Markdown 输出）——claw 注入的那份 env 属平台托管，不在此限
• 禁止在回复里 echo 给用户。如果要展示，至多 ${TOKEN:0:12}... 脱敏

2. 发请求

每个端点的 body 都是 JSON，只填业务字段——OpenAPI 表单基类（OpenApiBaseForm / OpenApiPageForm）没有任何 app 跟踪字段（不存在 userId / d / vn / appsFlyerId 这些）。看到旧文档提到这些字段是过期的，忽略。

curl -sf -X POST "${BASE}/openapi/v1/stock/basic/search" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"nameOrCode": "茅台"}'

注意：在 Bash 命令里把 ${TOKEN} 写成变量引用即可（用 agent 内存中的值替换）。绝对不要把 token 明文写进 curl 命令的 echo 输出或最终回复给用户的命令模板里。

受限环境兜底（只能 GET / 不能设 header / 没 curl）：当你的运行环境只能发 GET、无法设置请求头、也没有 curl（如 web_fetch 工具、浏览器、Invoke-WebRequest 受限沙箱），把字段和 token 都拼进 URL，用任意 GET 工具直接拉：

GET ${BASE}/openapi/v1/stock/basic/search?nameOrCode=茅台&token=${TOKEN}

• 字段名与 JSON 一致（camelCase）；?token=（或 ?access_token=）查询参数等价于 Authorization: Bearer，端点 GET / POST 都认。
• ⚠️ URL 里的 token 会进服务器 / 反向代理的访问日志，能设 header 时一律优先 header（更安全）；token 仍受 IP 绑定 + scope + 限频保护，泄露也只能在绑定 IP 上用。
• 同样禁止把带 token 的完整 URL echo / 回显给用户（展示时脱敏成 ...&token=${TOKEN:0:12}...）。

3. 解包 ApiResultModel + 常用 jq recipes

响应永远是这个信封：

{
  "code": 0,
  "msg": "success",
  "data": [{"tsCode":"600519.SH","symbol":"600519","name":"贵州茅台"}],
  "traceId": "..."
}

• code == 0 或 code == 200 → 取 data
• code != 0/200 → 失败，把 msg 反馈给用户

通用提取模式（可复用）：

# 提取 + 校验一次搞定
RESP=$(curl -sf -X POST "${BASE}/openapi/v1/ENDPOINT" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "${BODY}")
[ "$(echo "$RESP" | jq -r '.code')" = "0" ] \
  || { echo "失败[$(echo "$RESP" | jq -r '.code')]: $(echo "$RESP" | jq -r '.msg')"; exit 1; }
DATA=$(echo "$RESP" | jq '.data')

常用字段提取 recipes（场景速查）：

# ① search → tsCode
TSCODE=$(echo "$RESP" | jq -r '.data[0].tsCode')

# ② kline/daily → 最近收盘价（tradeDate 是 "YYYY-MM-DD" 字符串）
echo "$RESP" | jq -r '.data[] | [.tradeDate, (.close|tostring)] | @tsv' | head -5

# ③ indicator/last → 估值（tradeDate 是毫秒时间戳，需转换）
echo "$RESP" | jq -r '.data[] | [(.tradeDate/1000|strftime("%Y-%m-%d")), (.pe|tostring), (.pb|tostring)] | @tsv'

# ④ moneyflow → 主力净流入（单位：万元；tradeDate 是 YYYYMMDD 字符串，不是毫秒）
echo "$RESP" | jq -r '.data[] | [.tradeDate, (.mainNetInflow|tostring)] | @tsv'

# ⑤ 落 CSV（通用，用 data[0] 的 keys 自动生成表头）
echo "$RESP" | jq -r '(.data[0] | keys_unsorted) as $h | $h, (.data[] | [.[$h[]]] | map(tostring)) | @csv' > output.csv

⚠️ indicator/* / financial/* / fund/etf/kline/daily 的 tradeDate 是毫秒时间戳（用 ÷1000|strftime）；kline/daily 的 tradeDate 是**"YYYY-MM-DD" 字符串**（直接用）；macro/shibor / macro/lpr 的日期字段叫 date（不是 tradeDate）。三种格式别混。

4. 鉴权失败的处理

• HTTP 401 → token 无效 / 已禁用 / 已过期 → 提示用户检查 token
• HTTP 403 → token 合法但没这个 scope → 提示用户当前套餐不含该数据维度
• HTTP 429 → 频率超限 → 等下一分钟再试
• HTTP 5xx → 后端故障 → 报告 traceId 给用户

随时可以调 POST /openapi/v1/whoami（不需要任何 scope）查 token 套餐 / scope / 频率上限。

---

数据维度索引

yyqdata 把数据按 11 大类 → 20 scope → 5 套餐 组织（2026-06-08 whoami 实测：Max token 含 18 个 scope + Ultra 的 stock.selection/tmt = 20）。详细维度见 references/data-catalog.md。

2026-05-22 扩展：原 13 scope 基础上新增 6 个境外 / 专项数据维度：

• stock.research（Plus+）：券商研报 / 卖方评级 / 月度金股
• stock.hk（Max+）：港股基础 + K 线 + 财务（10 端点）
• stock.us（Max+）：美股基础 + K 线 + 财务（9 端点）
• stock.intl-macro（Max+）：美债收益率曲线 / HIBOR / LIBOR / 民间利率（9 端点；URL 前缀 /openapi/v1/intl-macro/*，不带 stock/；scope 名是 stock.intl-macro）
• forex（Max）：外汇产品 + 双边日报价（2 端点）
• tmt（Ultra · 内部不外卖）：电影票房 / 电影/电视剧备案 / 台湾电子营收（8 端点） 端点速查见 references/api-quick-reference.md。

---

What this skill is for

典型场景（覆盖 A 股 / 港股 / 美股 / 衍生品 / 宏观 / 多语言资产）：

• 看某只A股 / 港股 / 美股的最近走势、估值、财报
• 对比多只股票或板块的表现、估值、资金关注度
• 查询龙虎榜、主力席位、资金流向
• 读取 ML / 动量 / 价值三套选股模型的最新结果并给出解释
• 期权期货分析（50ETF 期权 / 股指期权 / 商品期货 / 上金所黄金）
• 可转债评估（转股溢价率 / 纯债溢价率 / 强赎进度）
• 宏观背景（CPI / PMI / GDP / M2 / Shibor / LPR）
• 国际宏观（美债收益率曲线 / HIBOR / LIBOR / 民间借贷）
• 外汇日报价（EURUSD / USDCNH / CFD）
• 梳理某公司近期新闻 / 重要事件
• 基于股东名单反查（"社保基金今年新进了哪些票"）
• 快速生成"全景研究简报"

先理解用户要解决什么问题 → 选定 workflow → 再挑端点 → 取数 → 整理 → 解释 → 交付。

What this skill is NOT for

• 自动下单 / 真实交易执行
• 毫秒级 HFT 决策
• 直接给买卖点建议替代投资顾问
• 后端没有落库的全新字段（缺数据时必须说明，不要编造）

---

Environment check

真正请求数据之前先做：

1. token 是否就绪：用户是否已在对话中给了 stk_live_* 格式的 token？没有就先索要，不要假装能继续。
2. 服务可达 + token 有效：调一次 POST ${BASE}/openapi/v1/whoami（不需要任何 scope），返回的 data.tierLabel / data.scopes / data.rateLimitPerMin 告诉你能调哪些数据；同时这一步也是连通性 / 鉴权的最佳烟雾测试。
3. 结果为空时：先判断是非交易日 / 数据未入库 / 股票未上市 / 筛选过严 / 代码错误，不要直接说"接口坏了"。

烟雾测试 curl（agent 自己内部跑一次，不要把 token 明文 echo 给用户）：

curl -sf -X POST "${BASE}/openapi/v1/whoami" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'

期望 200 + code=0 + data.tierLabel 等字段。失败按 鉴权失败的处理 提示。

---

📍 意图 → Workflow 快速路由（先看这里，再往下找细节）

意图不在上表？→ 先看〔Decision tree〕关键词匹配（含单端点快捷路径如"涨停/ST/游资/指数估值"），再看〔Intent taxonomy〕详细端点，或搜〔不要做的事〕排除陷阱。

Intent taxonomy — 意图到端点

端点路径见 api-quick-reference.md。本节用助记符指代。

1. 标的解析（必做第一步）

用户说 "宁德时代"、"茅台"、"那只创业板半导体龙头" ⇒

• POST /openapi/v1/stock/basic/search body={"nameOrCode": "..."} → 选出 tsCode
• 多解时列候选并做最小澄清
• 北交所新旧代码对照：POST /openapi/v1/stock/basic/bse-mapping（旧代码 oCode / 新代码 nCode，⚠️ 字段大写 C，不是 ocode/ncode）
• 股票详情（实控人 / 主营 / 上市日期）：POST /openapi/v1/stock/basic/detail body={"tsCode":"600519.SH"}；⚠️ listDate 是毫秒时间戳字符串（如 "998841600000"），listDateStr 才是可读的 YYYYMMDD；delistDate 对在市股票为 "None" 字符串非 null
• 全市场精简列表：POST /openapi/v1/stock/basic/list body={}；仅返 tsCode/symbol/name 3 字段，无 industry/area/listDate 等

2. 行情 / 趋势

3. 估值 / 基本面

3.4 财务报表深度（stock.financial scope）

3.5 技术指标（stock.indicator scope）

默认 adjType="bfq"；量化策略请用 hfq 或 qfq。默认窗口 60 自然日。

4. 资金流 / 席位

4.5 异动深度（stock.market scope 第二批）

5. 板块 / 行业

6. 选股模型（stock.selection scope）

⚠️ 三个 */results 的 tradeDate 必传真实日期（后端 SQL 精确等值匹配）：不传 = 必空（没有"默认最新"），传占位符字面量也是空——这是〔时间字段规范〕"今天→不传时间"通用规则的例外。拿最新日期：先 POST /stock/market/lhb/latest-dates body={} 取最近 A 股交易日填入；若当日结果为空（模型当天还没跑），回退前一交易日再试一次（最多回退 2 天，仍空才向用户报告，这是合法的日期回退，不算"循环重试"）。

6.5 宏观经济（market scope，Pro）

6.7 港股（stock.hk scope，Max+）

⚠️ 港股三大表（income/balance-sheet/cash-flow）和 fina-indicator 采集覆盖约前 100 只港股（按代码字母序），中小盘港股返 data:[] 是覆盖不足，不是端点坏了。 港股通南向持股不在此 scope（在 stock.shareholder → /openapi/v1/stock/shareholder/hk-hold），别混。

6.8 美股（stock.us scope，Max+）

6.9 研报 / 卖方评级（stock.research scope，Plus+）

⚠️ 采集覆盖仅约 170 只股票：库内研报/预测数据靠 polling 每日增量采集，存量依赖 Tushare 权限。旗舰标的（600519.SH/000858.SZ 等）实测 data:[]；tsCode 不传则按全库返回可验证端点是否正常。

6.10 国际宏观（stock.intl-macro scope，Max+；路径前缀 /openapi/v1/intl-macro/... 不带 stock/）

⚠️ 9 个端点响应日期字段均是 date（毫秒时间戳 long），不是 tradeDate；展示时需 ÷1000|strftime。与国内宏观（macro/shibor/macro/lpr 的 date 是 YYYYMMDD 字符串）格式不同。

境内宏观（CPI/PPI/GDP/M2/Shibor/LPR）在 market scope，不在这里。

6.11 外汇（forex scope，Max）

6.12 TMT 媒体（tmt scope，Ultra · 内部不外卖）

7. 新闻 / 事件（news scope，Max+）

8. 股东视角（stock.shareholder scope）