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 里不能真的出现 <最新> <today> <tsCode> ${...} 这种字面量；必须换成真实值（日期自己算、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. 对话中用户提供
# 4. 仍无 → 自动领取免费 token（见〔无 token 时自动领取免费 token〕），领到后写回 config.json 供后续会话复用
[ -z "$TOKEN" ] && echo "⚠️ 未找到 token：可让用户提供 stk_live_xxx，或自动领取免费 token（POST \$BASE/public/apply-token）"

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

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

无 token 时自动领取免费 token（zero-config 兜底）

环境变量 / config.json / 对话里都拿不到 token 时，别卡住、别空手让用户去注册——直接匿名领一个免费 token 用起来：

# 匿名领取（body 可空）。想让 token 日后能在官网登录续期/找回，带上用户邮箱：{"email":"user@x.com"}
RESP=$(curl -sf -X POST "${BASE}/public/apply-token" \
  -H "Content-Type: application/json" -d '{"useCase":"agent 自动领取"}')
TOKEN=$(printf '%s' "$RESP" | sed -n 's/.*"rawToken"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')

# ⚠️ 领到后必须写回 config.json：免费 token 同一 IP 24h 只能领一次，
#    不持久化的话，下一轮新会话既领不到新 token 又丢了旧 token。
#    这是本 skill 唯一允许 token 落盘的场景（仍禁止回显完整值 / 禁止提交进 git）。
for _d in ~/.openclaw/skills/yyqdata ~/.hermes/skills/yyqdata ~/.claude/skills/yyqdata; do
  [ -d "$_d" ] || continue
  printf '{ "token": "%s", "base_url": "%s" }\n' "$TOKEN" "$BASE" > "$_d/config.json"
  chmod 600 "$_d/config.json" 2>/dev/null
  break
done

领到后一次性告诉用户（脱敏，别回显完整 token）：

> 已为你自动领取一个免费 token（Free 档：基础信息 / K线 / 技术指标，10 次/分钟，15 天有效，已写入本地 config.json 自动复用）。
> 需要续期或升级到更多数据维度（财务 / 资金流 / 龙虎榜 / 港美股 等），可升级 Max（¥100/月起，3/6/12 个月更优惠），到 <https://www.yyqyx.com/> 登录购买，支付后即时开通（见〔套餐与升级〕）。
> 想要更多数据服务或遇到问题需要帮助 / 解决，也都在 <https://www.yyqyx.com/>；或扫码加企业微信咨询：
>
>

> 📎 怎么把企业微信二维码发给用户：直接在回复里输出上面那行 Markdown 图片
> ![企业微信](https://www.yyqyx.com/qywx-qr.png)，支持图片渲染的客户端会把二维码显示出来；
> 纯文本环境则附上链接 <https://www.yyqyx.com/qywx-qr.png> 让用户自行打开扫码。

失败处理：
- 返回 24 小时内已申请过 → 同 IP 当天领过了。让用户去 <https://www.yyqyx.com/> 登录拿/续 token，或直接在对话里贴他已有的 stk_live_xxx。
- 网络/服务不可达 → 照〔Error handling〕提示用户，别 fallback 别瞎试别的 URL。

💳 套餐与升级（用户问"多少钱 / 怎么付费 / 怎么升级"时照答）

Max 订阅阶梯价（买得越久越省，时长不打折）：

• 购买 / 升级方式：到 <https://www.yyqyx.com/> 登录下单支付，支付成功后自动开通（即时生效，无需换 token）；有效期从当前到期日往后顺延。
• 用户问价格 / 怎么升级 → 直接照上表答 + 给购买入口 <https://www.yyqyx.com/>，别说"不知道"或"联系管理员"。
• ⚠️ 以官网价为准；如表与官网不一致，以 <https://www.yyqyx.com/> 显示为准。

快速健康验证：

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/<scope>/<resource>（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 属平台托管，不在此限）。唯一例外：通过 /public/apply-token 自动领取的免费 token 可写入 skill 目录的 config.json（0600）以便后续会话复用——见〔无 token 时自动领取免费 token〕；该例外仅限自动领取的 token，仍禁止回显完整值、禁止提交进 git。
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：调一次 POST ${BASE}/public/apply-token（匿名 body 可空），把返回的 data.rawToken 当本会话 TOKEN，写回 config.json 复用，并一次性告知用户「已自动签发免费 token，续期/升级到 https://www.yyqyx.com/ 登录办理」。完整步骤见〔无 token 时自动领取免费 token〕。不要先猜、不要回显完整 token。（领取失败再退回向用户索要。）
2. 能力探测：调一次 POST ${BASE}/openapi/v1/whoami，落 tier / tierLabel / scopes / rateLimitPerMin / allowedPaths 到记忆（返回还带 llmHint 一句话总结，可直接读）。若返回 trialActive=true（首次免费体验期，含 trialDaysLeft 剩余天数）：主动告诉用户"你正免费体验全维度数据 N 天"，并主动建议体验高级场景（财务三表 / 龙虎榜常客 / 板块资金流 / ML 选股 / 港美股），别让用户只问 K 线就白白浪费体验期；trialDaysLeft ≤ 3 时提示到 <https://www.yyqyx.com/> 登录续期/升级，以免回落免费档后高级数据不可用。若 ownerName 以 free-ip- 开头（= 匿名自动领取的 token，到期 15 天会直接失效且无法找回）：不论是否在体验期，都应在临到期（剩 ≤3 天）时主动提醒用户"你的免费 token 是匿名的，到期会丢失；到 <https://www.yyqyx.com/> 登录即可认领它（绑定账号后可续期 / 随时找回 / 升级），别等过期"。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）

(c) 都没有 —— 自动领取免费 token（默认兜底，别卡住）
env / config.json / 对话里都没有 token 时，先自动领一个免费 token 用起来，而不是空手索要：调
POST ${BASE}/public/apply-token（匿名 body 可空），拿 data.rawToken 当本会话 TOKEN 并写回 config.json
复用，再一次性告诉用户「已自动签发免费 token（15 天有效），续期 / 升级到 <https://www.yyqyx.com/> 登录办理」。
完整步骤 + 失败处理见〔无 token 时自动领取免费 token〕。

只有当自动领取也失败（如同 IP 24h 已领过）时，才向用户索要或引导登录：

> "我需要一个 OpenAPI token 才能调用数据后端。可到 <https://www.yyqyx.com/> 登录免费领取（格式 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 是否就绪：env / config.json / 对话里有 stk_live_* token 吗？都没有就先自动领取免费 token（见〔无 token 时自动领取免费 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）

8.5 基金 / ETF（fund scope，Max）

8.7 衍生品（derivative scope，Max）

8.9 债券 / 可转债（bond scope，Max）

9. 异动监控（stock.market / stock.kline scope）

⏰ 时间字段规范（必读）

请求时只用 3 个字段：tradeDate（单日）/ startDate（起始）/ endDate（截止）。响应里的 annDate / publishDate / navDate / quarter 是返回字段，不要回填到请求 body。

格式速查

禁止格式

• ❌ "2026-04-30"（带 -）/ "2026/04/30" / ISO 8601 / Unix 时间戳——全部被当未传，端点拿默认值/空数据
• ❌ 单日端点（form 字段是 tradeDate）传 startDate/endDate，反之亦然——严格按每个端点 form 字段表

用户口语 → body 字段

用户不给范围时的默认窗口（agent 心算）

Entity resolution rules

三个市场的解析路径完全不同，别拿 A 股的 search 去搜港美股：

• A 股（默认市场）：输入可能是中文名、简称、纯数字代码 000001、ts_code 000001.SZ。先调 POST /openapi/v1/stock/basic/search(body={"nameOrCode":"..."}) 规范化到 tsCode。重名（如"平安"）→ 列候选让用户二选一。
• 港股（stock.hk scope，Max+）：tsCode 形如 00700.HK。没有名称搜索端点——/openapi/v1/stock/hk/basic 只支持 tsCode 精确过滤：
• 用户给数字代码（"00700"/"0700"）→ 左补零到 5 位拼 00700.HK，用 basic body={"tsCode":"00700.HK"} 查一次验证存在并拿正式名称；
• 用户给中文名（"腾讯"）→ basic body={"listStatus":"L","size":100} 翻页拉列表，agent 侧按 name 字段模糊匹配（约 2600 只，二三十页内能扫完）。⚠️ 列表按 list_date 倒序排（新上市在前），老牌大票（腾讯/00700.HK 上市2004年）可能排在第 ~20 页才出现；如果知道代码直接传 tsCode 最高效。
• 美股（stock.us scope，Max+）：tsCode 就是裸 ticker（AAPL / TSLA / JPM），没有 .O/.N 交易所后缀——带后缀查询会静默返空（2026-06-07 实测，旧文档曾写反）。唯一带点的是股份类别码（BRK.A / BF.B / SPAC 单元 .U），照原样传。不确定时 /openapi/v1/stock/us/basic 按 ticker/enname 前缀匹配确认（优先 classify=EQ 收窄）。
• ⚠️ /stock/basic/search 只收录 A 股——拿它搜"腾讯（港）/苹果（美）"返回空是正常的，不代表后端没有港美股数据（数据在 stock.hk/stock.us scope）。别因此对用户说"查不到这只票"（违反〔第一铁律〕）。
• 板块有"东财"/"申万"两套口径：/stock/market/plate* 走东财，/stock/index/sw* 走申万。结论里要注明。

Workflow templates — 默认编排

> ⚠️ 模板里的 <尖括号>（<单只> <D> <板块ts_code> <转债tsCode> 等）是流程示意符，发请求前必须替换成上一步拿到的真实值。body 里出现任何 <...> / ${...} 字面量 = 后端当未传 → 静默拿默认值或空数据（见〔⛔ 不要做的事〕占位符红线）。模板路径是 /stock/... 简写，实际请求前面拼 ${BASE}/openapi/v1。

WF-1 单标的行情快照

可直接复制运行的 bash 模板（茅台示例，替换 NAME 即可）：

NAME="茅台"   # ← 改这里

# Step 1: 解析 tsCode
R=$(curl -sf -X POST "${BASE}/openapi/v1/stock/basic/search" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"nameOrCode\":\"${NAME}\"}")
TS=$(echo "$R" | jq -r '.data[0].tsCode')
echo "tsCode = $TS"

# Step 2: 4 个端点并行（互无依赖，可同时发）
curl -sf -X POST "${BASE}/openapi/v1/stock/kline/daily" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"type\":11,\"size\":20}" > /tmp/kline.json &

curl -sf -X POST "${BASE}/openapi/v1/stock/indicator/last/by-codes" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCodes\":[\"${TS}\"]}" > /tmp/indicator.json &

curl -sf -X POST "${BASE}/openapi/v1/stock/kline/percentage-change" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\"}" > /tmp/pct.json &

curl -sf -X POST "${BASE}/openapi/v1/stock/market/moneyflow" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"size\":10}" > /tmp/flow.json &

wait   # 等 4 个并行结束

# Step 3: 提取关键字段
echo "=== 最近 K 线 (tradeDate 带横杠字符串) ==="
jq -r '.data[-3:] | .[] | [.tradeDate, .close, .pctChg] | @tsv' /tmp/kline.json

echo "=== 估值 (tradeDate 毫秒→需转换) ==="
jq -r '.data[0] | [(.tradeDate/1000|strftime("%Y-%m-%d")), .pe, .pb, .totalMv] | @tsv' /tmp/indicator.json

echo "=== 近半年/1年涨跌 (%) ==="
jq -r '.data[0] | [.pctChg2q, .pctChg1y] | @tsv' /tmp/pct.json

echo "=== 近 5 日主力净流入（万元）==="
jq -r '.data[:5] | .[] | [.tradeDate, .mainNetInflow] | @tsv' /tmp/flow.json

> 流程要点：kline/daily 的 tradeDate 是 "YYYY-MM-DD" 字符串；indicator 的 tradeDate 是毫秒时间戳；moneyflow 的 tradeDate 是 YYYYMMDD 字符串（例外，不要 /1000|strftime）；type=11 = 不复权日 K（12=周线 / 13=月线）。交付格式：一句话结论 + 区间涨跌 + 关键估值 + 主力净流入 + 异常点。

WF-2 多标的横向对比

可直接复制运行的 bash 模板（白酒三剑客示例）：

NAMES=("茅台" "五粮液" "泸州老窖")   # ← 改这里，可加减标的

# Step 1: 并行 search 所有标的
for NAME in "${NAMES[@]}"; do
  curl -sf -X POST "${BASE}/openapi/v1/stock/basic/search" \
    -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
    -d "{\"nameOrCode\":\"${NAME}\"}" > /tmp/s_${NAME}.json &
done
wait

# Step 2: 汇总 tsCode JSON 数组
TS_LIST=$(for NAME in "${NAMES[@]}"; do
  jq -r '.data[0].tsCode // empty' /tmp/s_${NAME}.json
done | jq -R . | jq -sc .)
echo "tsCodes: $TS_LIST"

# Step 3: 批量取估值（单次 ≤50，一次搞定）
echo "=== 估值对比 (tsCode / name / PE / PB / ROE / 总市值元) ==="
curl -sf -X POST "${BASE}/openapi/v1/stock/indicator/last/by-codes" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCodes\":${TS_LIST}}" \
  | jq -r '.data[] | [.tsCode, .name, (.pe|tostring), (.pb|tostring), (.roe|tostring), (.totalMv|tostring)] | @tsv'

# Step 4: 并行取各标的涨跌幅（此端点不支持批量，必须循环）
echo "=== 涨跌幅对比 (tsCode / 近半年% / 1年%) ==="
for TS in $(echo "$TS_LIST" | jq -r '.[]'); do
  curl -sf -X POST "${BASE}/openapi/v1/stock/kline/percentage-change" \
    -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
    -d "{\"tsCode\":\"${TS}\"}" \
    | jq -r --arg ts "$TS" '.data[0] | [$ts, (.pctChg2q|tostring), (.pctChg1y|tostring)] | @tsv' &
done
wait

> 关键点：indicator/last/by-codes 支持 tsCodes 数组批量（≤50），一次搞定；percentage-change 不支持批量，需循环但可并行（& + wait）。

WF-3 财务质量扫描（轻量）

可直接复制运行的 bash 模板（茅台示例，替换 NAME 即可）：

NAME="茅台"   # ← 改这里

# Step 1: 解析 tsCode
TS=$(curl -sf -X POST "${BASE}/openapi/v1/stock/basic/search" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"nameOrCode\":\"${NAME}\"}" | jq -r '.data[0].tsCode')
echo "tsCode = $TS"

# Step 2: 近 8 季核心财务 + 分红（并行）
curl -sf -X POST "${BASE}/openapi/v1/stock/financial/core" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"size\":8}" > /tmp/core.json &

curl -sf -X POST "${BASE}/openapi/v1/stock/financial/dividend" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\"}" > /tmp/div.json &

wait

# Step 3: 提取关键趋势指标（⚠️ core.endDate 是 YYYYMMDD 字符串，不是毫秒，直接用）
echo "=== 近 8 季（endDate / EPS / ROE / 净利率 / 净利同比%）==="
jq -r '.data[] | [.endDate, .eps, .roe,
  .netprofitMargin, .netprofitYoy] | @tsv' /tmp/core.json

echo "=== 分红（endDate / 现金分红/股 / 送转股数）==="
jq -r '.data[] | [.endDate, .cashDiv, .stkDiv] | @tsv' /tmp/div.json
# dividend 的 endDate 是 YYYYMMDD 字符串（非毫秒）

> 交付要点：判断改善/恶化趋势（ROE/净利率逐季变化）、区分累计 vs 单季（reportType=1 合并，无 reportType 时 core 含所有口径）、标注异常季度。

WF-3.1 财务深度审计（stock.financial scope）

可直接复制运行的 bash 模板：

TS="600519.SH"    # ← 改成目标 tsCode（先 search 拿）
# reportType: 0=年报 1=一季报 2=半年报 3=三季报；传 1=季报，做趋势用

# Step 1: 四表并行拉
curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/financial/income-statement" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"reportType\":1,\"size\":8}" > /tmp/fin_inc.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/financial/balance-sheet" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"reportType\":1,\"size\":8}" > /tmp/fin_bs.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/financial/cash-flow" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"reportType\":1,\"size\":8}" > /tmp/fin_cf.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/financial/indicator" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"size\":8}" > /tmp/fin_ind.json &
wait

echo "=== 利润表（nIncome=净利润；大写I，不是nincome）==="
jq -r '.data[] | [(.endDate/1000|strftime("%Y-%m-%d")), .revenue, .nIncome, .nIncomeAttrP] | @tsv' \
  /tmp/fin_inc.json

echo "=== 综合指标（ROE / 毛利率 / 现金比）==="
jq -r '.data[] | [(.endDate/1000|strftime("%Y-%m-%d")), .roe, .grossprofitMargin, .ocfToProfit] | @tsv' \
  /tmp/fin_ind.json

echo "=== 现金流（经营现金流 vs 净利润 交叉验证）==="
jq -r '.data[] | [(.endDate/1000|strftime("%Y-%m-%d")), .nCashflowAct, .freeCashflow] | @tsv' /tmp/fin_cf.json
# nCashflowAct=经营净额；freeCashflow=FCF；⚠️ 字段名不是 nCashFlowOper！

# Step 2 按需追加（勿滥用，只在特定分析时调）
# 分业务营收（日期是 YYYYMMDD 字符串，非毫秒）：
# curl ... /stock/financial/business-segment -d '{"tsCode":"'${TS}'","size":50}'
# 大股东质押风险（日期是 YYYYMMDD 字符串）：
# curl ... /stock/financial/pledge -d '{"tsCode":"'${TS}'","size":8}'

WF-3.5 技术指标多维分析

可直接复制运行的 bash 模板：

TS="600519.SH"   # ← 目标 tsCode（先 search 拿）

# 四组指标并行拉取
curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/indicator/ma-channel" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"adjType\":\"qfq\",\"size\":60}" > /tmp/ind_ma.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/indicator/oscillator" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"adjType\":\"qfq\",\"size\":60}" > /tmp/ind_osc.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/indicator/trend-volume" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"adjType\":\"qfq\",\"size\":60}" > /tmp/ind_tv.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/indicator/nine-turn" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"size\":20}" > /tmp/ind_nt.json &
wait

echo "=== MA/BOLL 通道（趋势位置）==="
jq -r '.data[] | [(.tradeDate/1000|strftime("%Y-%m-%d")), .ma5, .ma20, .ma60, .bollMid, .bollUpper, .bollLower] | @tsv' \
  /tmp/ind_ma.json
# ⚠️ ma-channel 无 close 字段（完整 28 字段：MA/EMA/BOLL/KTN/TAQ/BBI/EXPMA）；需收盘价请另调 kline/daily

echo "=== MACD / KDJ（动量/超买超卖）==="
jq -r '.data[] | [(.tradeDate/1000|strftime("%Y-%m-%d")), .macd, .macdDif, .macdDea, .kdjK, .kdjD, .kdjJ] | @tsv' \
  /tmp/ind_osc.json

echo "=== OBV / VR 量能 ==="
jq -r '.data[] | [(.tradeDate/1000|strftime("%Y-%m-%d")), .obv, .vr, .mtm] | @tsv' /tmp/ind_tv.json

echo "=== DeMark 九转（反转预警）==="
jq -r '.data[] | [(.tradeDate/1000|strftime("%Y-%m-%d")), .upCount, .downCount, .nineUpTurn, .nineDownTurn] | @tsv' /tmp/ind_nt.json

# ⚠ short-term 短线因子暂未上线，恒返 []，拿到空直接说明不要重试：
# curl ... /stock/indicator/short-term -d '{"tsCode":"'${TS}'","size":20}'
# 估值历史（按需追加）：
# curl ... /stock/indicator/valuation/history -d '{"tsCode":"'${TS}'","size":60}'

WF-3.7 宏观背景扫描

可直接复制运行的 bash 模板：

# 全部并行拉取，节省等待时间
curl -sf --compressed -X POST "${BASE}/openapi/v1/market/macro/cpi" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"size":12}' > /tmp/macro_cpi.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/market/macro/ppi" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"size":12}' > /tmp/macro_ppi.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/market/macro/pmi" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"size":12}' > /tmp/macro_pmi.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/market/macro/money-supply" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"size":12}' > /tmp/macro_m2.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/market/macro/lpr" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"size":6}' > /tmp/macro_lpr.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/market/macro/gdp" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"size":6}' > /tmp/macro_gdp.json &

wait

echo "=== CPI 全国同比 ==="
jq -r '.data[] | [.month, .ntYoy, .ntMom] | @tsv' /tmp/macro_cpi.json
# month = YYYYMM 字符串；ntYoy=同比；ntMom=环比

echo "=== PPI 总体同比 ==="
jq -r '.data[] | [.month, .ppiYoy, .ppiMom] | @tsv' /tmp/macro_ppi.json

echo "=== 制造业 PMI ==="
jq -r '.data[] | [.month, .pmi010000] | @tsv' /tmp/macro_pmi.json
# 字段名是数字编码：pmi010000=综合；pmi010100=生产；pmi010200=新订单

echo "=== M2 同比 ==="
jq -r '.data[] | [.month, .m2, .m2Yoy] | @tsv' /tmp/macro_m2.json

echo "=== LPR ==="
jq -r '.data[] | [.date, .y1, .y5] | @tsv' /tmp/macro_lpr.json
# date = YYYYMMDD 字符串（⚠️ 不是 tradeDate！）；y1=1年期；y5=5年期（⚠️ 不是 lpr1y/lpr5y）

echo "=== GDP 季度同比 ==="
jq -r '.data[] | [.quarter, .gdp, .gdpYoy] | @tsv' /tmp/macro_gdp.json
# quarter = YYYYQX 字符串（如 "2026Q1"）

WF-3.6 基金 / ETF 分析

可直接复制运行的 bash 模板：

KW="红利"        # ← 改成关键词（"沪深300"/"消费"/"科技"均可；命中 0 条就换近义词重试）
# 或直接设 ETF_CODE="510300.SH" 跳过搜索步骤

# Step 1: 搜索 ETF（关键词须是名称实际含的词）
ETF_LIST=$(curl -sf --compressed -X POST "${BASE}/openapi/v1/fund/etf/list" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"nameKeyword\":\"${KW}\",\"size\":10}")
echo "=== ETF 列表 ==="
echo "$ETF_LIST" | jq -r '.data[] | [.tsCode, .cName, .indexCode, .mgtFee] | @tsv'
# cName=ETF简称（⚠️ 大写N，不是cname）；exchange过滤用"SH"/"SZ"（不是"SSE"/"SZSE"）

ETF_CODE=$(echo "$ETF_LIST" | jq -r '.data[0].tsCode')

# Step 2: 日 K + 复权因子 + 份额（并行）
curl -sf --compressed -X POST "${BASE}/openapi/v1/fund/etf/kline/daily" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${ETF_CODE}\",\"size\":60}" > /tmp/etf_kline.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/fund/etf/share-history" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${ETF_CODE}\",\"size\":20}" > /tmp/etf_share.json &
wait

echo "=== ETF 日 K ==="
jq -r '.data[] | [(.tradeDate/1000|strftime("%Y-%m-%d")), .close, .pctChg, .vol, .amount] | @tsv' \
  /tmp/etf_kline.json
# ⚠️ tradeDate 是毫秒时间戳；amount 单位是元（÷1e8=亿）；vol 单位是手

echo "=== 份额规模 ==="
jq -r '.data[] | [(.tradeDate/1000|strftime("%Y-%m-%d")), .totalShare, .totalSize, .nav] | @tsv' \
  /tmp/etf_share.json
# totalShare=份（÷1e8=亿份）；totalSize=元（÷1e8=亿元）；不是万份/万元

# Step 3: 重仓股 + 分红（并行）
curl -sf --compressed -X POST "${BASE}/openapi/v1/fund/portfolio" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${ETF_CODE}\"}" > /tmp/etf_portfolio.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/fund/dividend" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${ETF_CODE}\",\"size\":10}" > /tmp/etf_div.json &
wait

echo "=== 前十重仓股 ==="
jq -r '.data[] | [.symbol, .stkMkvRatio, .stkFloatRatio] | @tsv' /tmp/etf_portfolio.json

echo "=== 分红历史 ==="
jq -r '.data[] | [.exDate, .divCash, .divProc] | @tsv' /tmp/etf_div.json
# divProc="实施"/"预案"；impAnndate/earpayDate 字段全小写d/p（不是 impAnnDate/earPayDate）

WF-3.8 可转债评估

可直接复制运行的 bash 模板：

STK="600000.SH"   # ← 正股代码（先 search 拿）

# Step 1: 查正股的转债（stkCode 字段，不是 tsCode）
CB_LIST=$(curl -sf --compressed -X POST "${BASE}/openapi/v1/bond/cb/list" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"stkCode\":\"${STK}\"}")
echo "=== 可转债列表（空=该公司未发转债，不是故障）==="
echo "$CB_LIST" | jq -r '.data[] | [.tsCode, .bondShortName, .convPrice, .maturityDate, .couponRate, .issueRating] | @tsv'
# issueSize 单位是元（÷1e8=亿），所有日期是 YYYYMMDD 字符串

CB_CODE=$(echo "$CB_LIST" | jq -r '.data[0].tsCode // empty')
[ -z "$CB_CODE" ] && echo "无转债" && exit 0

# Step 2: 可获取数据（并行）—— 溢价率/强赎底表暂无数据如实告知
curl -sf --compressed -X POST "${BASE}/openapi/v1/bond/cb/share" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${CB_CODE}\",\"size\":10}" > /tmp/cb_share.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/bond/cb/price-chg" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${CB_CODE}\",\"size\":10}" > /tmp/cb_pchg.json &

curl -sf --compressed -X POST "${BASE}/openapi/v1/bond/cb/rate" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${CB_CODE}\"}" > /tmp/cb_rate.json &
wait

echo "=== 转股进度（publishDate/endDate 是 YYYY-MM-DD 带横杠）==="
jq -r '.data[] | [.publishDate, .accConvertRatio, .remainSize, .convertPrice] | @tsv' /tmp/cb_share.json
# accConvertRatio=累计转股比例%；remainSize=剩余规模元（÷1e8=亿）

echo "=== 转股价变动历史 ==="
jq -r '.data[] | [.changeDate, .convertpriceBef, .convertpriceAft] | @tsv' /tmp/cb_pchg.json
# ⚠️ convertpriceBef/convertpriceAft 全小写p，不是 convertPriceBef/convertPriceAft

echo "=== 利率阶梯 ==="
jq -r '.data[] | [.rateStartDate, .rateEndDate, .couponRate] | @tsv' /tmp/cb_rate.json

# ⚠️ 以下端点底表暂无数据（PG迁移缺口），调用恒返空，如实告知用户勿重试：
# /bond/cb/daily（溢价率/纯债价值）、/bond/cb/factor、/bond/cb/issue、/bond/cb/call

WF-4 板块轮动分析

可直接复制运行的 bash 模板：

# Step 1: 全市场板块快照（⚠️ plate 快照端点忽略所有参数，直接传 {}）
SNAP=$(curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/market/plate" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" -d "{}")
echo "=== 涨幅 Top 10 板块 ==="
echo "$SNAP" | jq -r '.data | sort_by(.pctChange) | reverse | .[:10][] |
  [.tsCode, .name, .pctChange, .leadingCode, .leadingName] | @tsv'
# ⚠️ 领涨股代码字段名是 leadingCode（不是 leadingTsCode！）

# 取 top 3 板块 tsCode
TOP3=$(echo "$SNAP" | jq -r '[.data | sort_by(.pctChange) | reverse | .[:3][].tsCode] | join(" ")')

# Step 2: 持续净流入板块（⚠️ 此端点字段叫 type，不是 contentType）
echo "=== 连续净流入 ≥5日的行业板块 ==="
curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/market/plate/continue-net" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"continueNum":5,"type":"行业"}' \
  | jq -r '.data[:10][] | [.tsCode, .name, .continueNum, .totalNetInflow] | @tsv'

# Step 3: 取 plate/list 的最新 tradeDate 并转 YYYY-MM-DD（stocks-indicator 需要带横杠格式）
TRADE_DATE=$(curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/market/plate/list" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"size":1}' | jq -r '.data[0].tradeDate | (./1000|strftime("%Y-%m-%d"))')

# Step 4: Top 3 板块成分股估值（⚠️ tradeDate 必须 YYYY-MM-DD 带横杠，传 YYYYMMDD 会 code=1）
for CODE in $TOP3; do
  echo "=== ${CODE} 成分股估值快照（月度数据）==="
  curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/market/plate/stocks-indicator" \
    -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
    -d "{\"code\":\"${CODE}\",\"tradeDate\":\"${TRADE_DATE}\"}" \
    | jq -r '.data[:20][] | [.tsCode, .name, .pctChg, .pe, .pb] | @tsv'
done

# Step 5: 板块资金流（⚠️ 此端点字段叫 contentType，不是 type；无 sell 分项）
echo "=== 行业板块资金流 Top 10 ==="
curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/market/plate/cash-flow" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"contentType":"行业","page":1,"size":20}' \
  | jq -r '.data[:10][] | [.tsCode, .name, .buyElgAmount, .buyLgAmount, .netAmount] | @tsv'
# buyElgAmount=特大单买入万元；buyLgAmount=大单买入万元；netAmount=净流入万元
# ⚠️ buyEliteAmount/sellEliteAmount/netBuyElite 均不存在——该端点只有 buyElgAmount 等买方分项

WF-5 龙虎榜解读

可直接复制运行的 bash 模板：

TS="600519.SH"   # ← 改成目标股票 tsCode（先 search 拿）；留空则只看全市场清单

# Step 1: 取最近龙虎榜日期（返回 YYYY-MM-DD 格式）
DATES=$(curl -sf -X POST "${BASE}/openapi/v1/stock/market/lhb/latest-dates" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" -d "{}")
D=$(echo "$DATES" | jq -r '.data[0]')     # "2026-06-04"，lhb/list 可直接回传
D8=$(echo "$D" | tr -d '-')               # "20260604"，lhb/details 需要 YYYYMMDD
echo "龙虎榜日: $D"

# Step 2: 当日上榜清单（全市场）
LIST=$(curl -sf -X POST "${BASE}/openapi/v1/stock/market/lhb/list" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tradeDate\":\"${D}\"}")
echo "=== 上榜清单 (tsCode / 名称 / 涨跌%) ==="
echo "$LIST" | jq -r '.data[] | [.tsCode, .name, .pctChange] | @tsv'

# Step 3: 目标股席位明细（tsCode 非空时）
[ -n "$TS" ] && {
DETAIL=$(curl -sf -X POST "${BASE}/openapi/v1/stock/market/lhb/details" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"tradeDate\":\"${D8}\"}")
echo "=== ${TS} 席位（席位名 / 方向 / 净买元 / 上榜原因）==="
echo "$DETAIL" | jq -r '.data[] | [.exalter, .side, .netBuy, .reason] | @tsv'
# side="B"=买方 / "S"=卖方（不是 0/1！）；tradeDate 响应是毫秒时间戳（≠字符串）
}

# Step 4 可选：资金流印证
[ -n "$TS" ] && curl -sf -X POST "${BASE}/openapi/v1/stock/market/moneyflow" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"size\":5}" \
  | jq -r '.data[] | [.tradeDate, .mainNetInflow] | @tsv'

> 关键点：lhb/list 响应仅 3 字段（tsCode/name/pctChange），席位详情在 lhb/details；side 是字符串 "B"/"S"，不是整数；netBuy > 0 = 净买入。⚠️ 同 scope 的 institution-trading/broker-trade side 是整数（1=买方，2=卖方），与 lhb/details 的字符串相反——三者都在 stock.lhb scope，极易混淆。

WF-6 选股模型 + 人工复核

> ⚠️ stock.selection 仅 Ultra 内部档；Max 及以下 token 调用返 code=206。先 whoami 确认再执行。
> ⚠️ 2026-06-07 实测：ML/动量/价值结果表暂未生成数据（PG 迁移后模型管道未跑），即使 Ultra 也可能恒空——空就如实说明，改跑 WF-3.5 技术面替代。

可直接复制运行的 bash 模板（ML 买入信号）：

# Step 1: 确认 stock.selection scope 可用
curl -sf -X POST "${BASE}/openapi/v1/whoami" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" -d "{}" \
  | jq -r '.data.scopes[]?' | grep -q "stock.selection" \
  || { echo "❌ 无 stock.selection scope（Ultra 专属）"; exit 1; }

# Step 2: 取最近 3 个交易日（以应对当日模型未跑的情况）
DATES=$(curl -sf -X POST "${BASE}/openapi/v1/stock/market/lhb/latest-dates" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" -d "{}" \
  | jq -r '.data[]' | tr -d '-')   # YYYY-MM-DD → YYYYMMDD

# Step 3: 逐日尝试，拿到有数据的第一天
ML=""; D=""
for DAY in $DATES; do
  ML=$(curl -sf -X POST "${BASE}/openapi/v1/stock/selection/ml/results" \
    -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
    -d "{\"tradeDate\":\"${DAY}\",\"signalType\":\"BUY\",\"minScore\":0.6,\"size\":20}")
  COUNT=$(echo "$ML" | jq '.data | length')
  if [ "$COUNT" -gt 0 ]; then D=$DAY; break; fi
  echo "⚠️ ${DAY} 无结果（模型未跑），尝试前一日..."
done
[ -z "$D" ] && { echo "三个交易日均无选股结果，模型管道暂未运行"; exit 0; }

echo "=== ML BUY 信号 ${D} (tsCode / score / signalType) ==="
echo "$ML" | jq -r '.data[] | [.tsCode, (.score|tostring), .signalType] | @tsv'

# Step 4: 取 top 10 估值（批量一次）
TS_LIST=$(echo "$ML" | jq -c '[.data[:10][].tsCode]')
echo "=== 估值快照 (tsCode / pe / pb / roe) ==="
curl -sf -X POST "${BASE}/openapi/v1/stock/indicator/last/by-codes" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCodes\":${TS_LIST}}" \
  | jq -r '.data[] | [.tsCode, .name, (.pe|tostring), (.pb|tostring), (.roe|tostring)] | @tsv'

> 关键点：tradeDate 必传真实日期（SQL 精确等值匹配，不传 = 必空）；lhb/latest-dates 返回 3 个日期，逐日回退是标准做法。signalType 可选 BUY/HOLD/WATCH；minScore 阈值 0.6 可调。

WF-7 股东反查

可直接复制运行的 bash 模板（社保基金示例，替换 HOLDER 即可）：

HOLDER="社保基金"          # ← 支持模糊简称；多个股东改成 JSON 数组: ["社保基金","中央汇金"]（⚠️ 多名=交集AND，非并集OR）
# 最近季末日：A 股报告期为 3/31、6/30、9/30、12/31，取最近已过的那个
QUARTER_END="20260331"    # ← 改成最近季末日（YYYYMMDD）

# Step 1: 查该股东持有哪些股票
FIND=$(curl -sf -X POST "${BASE}/openapi/v1/stock/shareholder/holder/find-stocks" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"holders\":[\"${HOLDER}\"],\"endDate\":\"${QUARTER_END}\"}")
echo "=== 持仓股票 ==="
echo "$FIND" | jq -r '.data[] | [.tsCode, .name, .holderName] | @tsv'

# Step 2: 批量取估值 (≤50 只一次)
TS_LIST=$(echo "$FIND" | jq -c '[.data[:50][].tsCode]')
echo "=== 估值快照 ==="
curl -sf -X POST "${BASE}/openapi/v1/stock/indicator/last/by-codes" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCodes\":${TS_LIST}}" \
  | jq -r '.data[] | [.tsCode, .name, (.pe|tostring), (.pb|tostring), (.roe|tostring)] | @tsv'

# Step 3: 查单股东最新持仓明细（需全称，从 find-stocks 响应 holderName 字段取）
HOLDER_FULL=$(echo "$FIND" | jq -r '.data[0].holderName')  # 取实际全称
curl -sf -X POST "${BASE}/openapi/v1/stock/shareholder/holder/holdings" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"holder\":\"${HOLDER_FULL}\",\"endDate\":\"${QUARTER_END}\"}" \
  | jq -r '.data[] | [.tsCode, .tsCodeName, (.holdAmount|tostring), (.holdRatio|tostring)] | @tsv'
# holdAmount/holdChange 是 JSON 字符串，parseFloat() 再做数值运算

> 关键点：find-stocks 的 holders 支持简称模糊匹配；holdings 的 holder 必须传全称（从 find-stocks 响应取 holderName）；endDate 两端点均必填，缺一返 code=2；holdAmount/holdChange 是字符串需 parseFloat()。

WF-8 综合研究简报

用户说 "帮我快速研究一下 XX"，依次跑（可并行发射前 3 步）：

NAME="贵州茅台"
TS=""  # 先 search 填充
TS=$(curl -sf -X POST "${BASE}/openapi/v1/stock/basic/search" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"nameOrCode\":\"${NAME}\"}" | jq -r '.data[0].tsCode')

# Step 1: 行情 + 估值（近 60 日，parallel &）
curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/kline/daily" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"type\":11,\"size\":60}" > /tmp/kline.json &

# Step 2: 最新估值快照（peTtm/pb/roe/股息率）
curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/indicator/last/by-codes" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCodes\":[\"${TS}\"]}" > /tmp/indicator.json &

# Step 3: 财务核心 + 分红（近 8 期）
curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/financial/core" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"size\":8}" > /tmp/core.json &

wait  # 等前 3 步完成

# Step 4: 区间涨跌幅（多周期）
curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/kline/percentage-change" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\"}" > /tmp/pct.json

# Step 5: 资金流（近 30 日）+ 龙虎榜最近上榜
LHB_DATE=$(curl -sf -X POST "${BASE}/openapi/v1/stock/market/lhb/latest-dates" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{}' | jq -r '.data[0]')
curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/market/moneyflow" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"size\":30}" > /tmp/mf.json &
curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/market/lhb/details" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TS}\",\"tradeDate\":\"$(echo $LHB_DATE | tr -d '-')\"}" > /tmp/lhb.json &
wait

# Step 6: 最新新闻（需 news scope；Pro 无此 scope 跳过）
curl -sf --compressed -X POST "${BASE}/openapi/v1/market/news/list" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"titleKeyword\":\"${NAME}\",\"size\":20}" > /tmp/news.json 2>/dev/null || echo '{"data":[]}' > /tmp/news.json

# Step 7 (可选): 市场情绪聚合——今日整体新闻情绪 / 多空舆情（需 market scope）
# tradeDate 传当日 YYYYMMDD；avgSentimentScore in [-1,1]，>0 偏多；newsSurgeRatio 量比
TODAY=$(date +%Y%m%d)
curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/market/news-sentiment" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tradeDate\":\"${TODAY}\"}" > /tmp/sentiment.json 2>/dev/null || echo '{"data":null}' > /tmp/sentiment.json
# 注：tradeDate 是 YYYYMMDD 字符串（不是毫秒时间戳）；data:null 表示当日尚未生成（非交易日/盘前）

# 综合解读: 行情趋势 → 估值位置 → 财务质量 → 资金信号 → 新闻事件 → 市场情绪 → 风险点

WF-9 衍生品 / 期权（derivative scope，Max）

> ⚠️ 期权数据真实存在且量极大（option_daily 2000 万+ 行，覆盖 SSE/SZSE ETF + CFFEX 股指/国债 + SHFE/DCE/CZCE/INE/GFEX 商品/能源 共 8 所）。绝不能凭印象说"没有"——先查（见〔第一铁律〕）。

先分清两类问句，走不同路径：

路径 A — 单合约日 K（已知或能定位到具体合约码 tsCode）
用户："豆一 A2607-P-4600 这只期权 6 月初价格" / "50ETF 购 12 月 2.5 那张最近怎么走"

# （可选）先用 contracts 按交易所/标的/月份定位合约码
POST /openapi/v1/derivative/option/contracts
     body={"exchange":"DCE","size":100}      # 返回 tsCode/opName/callPut/exercisePrice/sMonthDate/maturityDate
     # 分页端点(默认 size=50):一个标的常有几百张合约,需全量就 page=1,2,3… 翻到不足 size 行为止;exchange 单数/exchanges 数组均可
POST /openapi/v1/derivative/option/kline/daily
     body={"tsCode":"A2607-P-4600.DCE","startDate":"20260601","endDate":"20260603"}
→ 字段：open/high/low/close/settle/preSettle/preClose/vol/amount/oi

路径 B — 全市场按某交易日筛选 / 跨日比价排序（别逐合约调几万次）
用户："找出 6/3 最低 ÷ 6/2 收盘 ≤ 50% 的期权" / "某日全市场期权放量榜"

# 用全市场端点按交易日整拉，分页 100/页，翻页直到不足 100 行
POST /openapi/v1/derivative/option/kline/daily-by-date
     body={"startDate":"20260602","exchange":"DCE","page":1,"size":100}
POST /openapi/v1/derivative/option/kline/daily-by-date
     body={"startDate":"20260603","exchange":"DCE","page":1,"size":100}
→ agent 侧按 tsCode 把两天 join，再算比值 / 排序 / 取 topN

期权专属陷阱（必看，否则筛出一堆假信号）：
- ⏱ tradeDate 返回是毫秒时间戳 long（如 1780329600000），不是 "20260602" 字符串。跨日 join 按毫秒比对或自行转换，别拿它当日期串去 equals。
- 🕳 未成交的合约也有行：open/high/low/vol/amount 全 = 0，但 close/settle 仍是结算价。做"暴跌/比价/放量"筛选前必须先剔除 low<=0 或 vol<=0 的行，否则把"当天没成交"误判成"跌到 0"（曾导致 1192 个假信号）。
- 🔤 callPut 字段是定长空格补齐的（"C " / "P "），按认购/认沽过滤要先 trim 或前缀匹配，别用 == "C"（会全部漏掉）。
- 📦 全市场单日动辄 2 万+ 行：能按 exchange 收窄就收窄；最终明细落 CSV，别把几万行塞进给用户的回复。
- 🕐 期权分钟线（option/kline/minutes）是按需入库的：合约 5000+ 不做全量同步，只有管理员手动回填过的合约有分钟数据（日 K 是全量的，不受此限）。空结果 ≠ 无行情 ≠ 接口故障——如实告诉用户"该合约分钟数据未回填，可联系管理员触发回填（OptionMinutesTask，分钟级生效）"，并主动提供日 K（option/kline/daily）作为替代。

WF-10 港 / 美股研究（stock.hk / stock.us scope，Max+）

> 标的解析走〔Entity resolution rules〕港/美股路径（别用 A 股 search）

港股（以腾讯 00700.HK 为例）：

TICKER="00700.HK"

# Step 1: 日 K + 复权（⚠️ hk/kline-adj 无估值字段；peTtm/pbTtm 在 Step 2 的 fina-indicator）
KLINE=$(curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/hk/kline-adj" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TICKER}\",\"size\":60}")
echo "$KLINE" | jq -r '
  .data[] | [
    (.tradeDate/1000|strftime("%Y-%m-%d")),
    .close, (.pctChange*100|round/100),
    .turnoverRatio, .totalMv
  ] | @csv'

# Step 2: 财务指标宽表（36 列，含 peTtm/pbTtm；多数问题到此为止）
FINA=$(curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/hk/fina-indicator" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TICKER}\",\"size\":8}")
echo "$FINA" | jq -r '
  .data[] | [
    (.endDate/1000|strftime("%Y-%m-%d")),
    .reportType, .holderProfit, .holderProfitYoy,
    .roeAvg, .grossProfitRatio, .debtAssetRatio,
    .peTtm, .pbTtm
  ] | @csv'

# Step 3（仅需具体科目时）: 三大表 long format → 透视
INCOME=$(curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/hk/income" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TICKER}\",\"size\":200}")
echo "$INCOME" | jq -r '.data[] | [(.endDate/1000|strftime("%Y-%m-%d")),.indName,(.indValue|tostring)] | @csv'
# 按 grep 筛关键指标行: grep "营业额\|毛利\|权益"

美股（以 Apple 为例）：

TICKER="AAPL"  # ⚠️ 裸 ticker，无 .O/.N 后缀（带后缀静默返空；BRK.A 例外保留点号）

# Step 1: 行情（us/kline 已含 pe/pb，无需额外估值端点）
KLINE=$(curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/us/kline" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TICKER}\",\"size\":60}")
echo "$KLINE" | jq -r '
  .data[] | [
    (.tradeDate/1000|strftime("%Y-%m-%d")),
    .close, (.pctChange*100|round/100), .pe, .pb, .totalMv
  ] | @csv'

# Step 2: 财务指标宽表（29 列）
FINA=$(curl -sf --compressed -X POST "${BASE}/openapi/v1/stock/us/fina-indicator" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d "{\"tsCode\":\"${TICKER}\",\"size\":8}")
echo "$FINA" | jq -r '
  .data[] | [
    (.endDate/1000|strftime("%Y-%m-%d")),
    .reportType, .operateIncome, .parentHolderNetprofit,
    .parentHolderNetprofitYoy, .roeAvg, .grossProfitRatio
  ] | @csv'

long format 透视（三大表必看——不透视你就是把几百行键值对直接糊给用户）：

• 返回每行一个键值对：港股 {tsCode, endDate, name, indName, indValue}；美股多 indType（表内分组）和 reportType，透视键相应变成 (endDate, indType, indName)。
• ⏱ 港股/美股三大表的 endDate 均为毫秒时间戳 integer（实测：港股 hk/income endDate=1767110400000，美股 us/income endDate=1774627200000）。⚠️ 旧文档写"美股 endDate 是字符串 '2024-12-31 00:00:00'"——已勘误，实为毫秒戳，与港股格式相同。
• agent 侧透视：按 endDate 分组、indName 当列名。快速做法（jq 落 long CSV 后按报告期挑关键指标）：

# endDate 是毫秒时间戳整数，先 ÷1000 转秒再格式化
echo "$RESP" | jq -r '.data[] | [(.endDate/1000|strftime("%Y-%m-%d")), .indName, (.indValue|tostring)] | @csv' > income_long.csv
# 再按 endDate 分组挑指标行（grep "营业额\|毛利\|溢利"），或用 python/awk 透视成 报告期×指标 宽表
# 注意：jq 的 strftime 在非 Linux 系统可能需替换为 python 处理

• 📦 翻页注意：一个报告期就有几十个 indName 行，size=100 可能只覆盖 1~2 个报告期；要多期对比先翻页拉够，再透视。
• 偷懒正道：能用 fina-indicator（已是宽表）回答的就别碰三大表 long format。
• 港股 fina-indicator 的 reportType 过滤值是带年份的完整报告期串（"2024年中报"），传 "中报" 匹配不到返回空——拿不准就不传，回来自己筛。

Data retrieval rules

共享请求模式

• 方法：永远 POST（除 /stock/market/volume-breakout 是 GET）
• Header：Authorization: Bearer ${TOKEN} + Content-Type: application/json
• Body：纯业务参数 JSON。OpenAPI 表单不含 userId / d / vn / appsFlyerId 这类 app 字段——别填
• 响应：ApiResultModel<T> = {code, msg, data, traceId}
• 大数据量拉取必带 gzip：分钟 K / 期权 daily-by-date / 多页拉取这类大响应，curl 加 --compressed（即发 Accept-Encoding: gzip）——后端已开 JSON gzip 压缩，传输量直降 70-85%；不带也能用，只是慢

分页与分段拉取

• 每次最多 100 行：所有 OpenAPI v1 端点单次请求 size 硬上限为 100。传 size=500、size=1000 都会被静默截断到 100，不会报错。要更多数据就翻页（page=2/3/...）。
• 默认 size = 50（不传时）。多数场景默认值已够，特别小的查询可显式 size=20。
• 日 K 线：一次窗口 ≤ 2 年
• 分钟 K 线：一次 ≤ 1 个月
• 批量指标 indicator/last/by-codes：一次 tsCodes ≤ 50
• 超过阈值 → 分段 → 合并 → 去重

缓存（agent 视角）

• 同样 body 短时间内重复请求会命中后端缓存（30s ~ 24h 不等，按数据频率分级）。对 agent 的影响：可放心重试，不会引入额外费用，但新鲜度上限就是缓存窗口——分钟级数据 60 秒内可能拿到旧值。
• 用户问"实时""现在""最新报价"时，分钟 K 端点的 60 秒缓存可能略过期；告知用户即可，不必反复重试。
• */execute 写动作端点和 /whoami 不走缓存。

重试策略

仅对网络/超时类瞬时错误重试一次；参数错误（400 / 422）或数据为空直接停手解释原因。不要循环重试 5 次。

输出规模控制

后端不会自动截断。如果一次拉到几千行，agent 自己要：
- 在输出给用户之前用 head -200 或类似手段限行
- 或者用更窄的筛选条件再请求一次
- 落 CSV 时不限制（CSV 不进 LLM context）

Output contract

除非用户明确只要原始表：

1. 一句话结论
2. 数据范围与口径（取数时间窗、K 线类型、是否复权、板块是东财还是申万）
3. 关键指标 / 关键表格
4. 异常点 / 风险 / 口径局限
5. 如生成了 CSV / Parquet，给出文件路径

中等以上数据表优先落盘成 CSV，命名示例：daily_600519.SH_20240101_20241231.csv。

交付前自检门（reflection gate — 回答发出前过一遍）

把答案发给用户之前，逐条自检；任何一条不过 → 先补救再交付：

1. 每个数字 / 结论都有出处吗？ —— 来自某次真实响应（能指出端点 + traceId），不是脑补 / 记忆 / 估算。否定结论尤其必须有 traceId（见〔第一铁律〕）。
2. 口径标了吗？ —— 时间窗、K 线类型、是否复权（bfq/hfq/qfq）、板块是东财还是申万、累计 vs 单季。含糊会误导用户。
3. 参数没踩坑吗？ —— 没把 snake_case / 占位符字面量（<最新>/${...}）/ 错误日期格式发出去——它们会静默返默认值，让你误以为"空"。
4. 部分失败如实说了吗？ —— 分段有失败别说"全部完成"；翻页截断要标"只取了前 N，按 X 排序"。
5. 结论先行了吗？ —— 一句话结论放最前，别让用户自己从表格里翻答案。

Error handling

对用户层

• 401 / token 无效或已过期 → 免费 token 15 天到期最常见：提示用户到 <https://www.yyqyx.com/> 登录续期（或升级套餐）；若当前 token 是本 skill 自动领取的匿名免费 token，也可按〔无 token 时自动领取免费 token〕重新领一个（同 IP 24h 限一次）。付费/管理员签发的 token 失效 → 到 <https://www.yyqyx.com/> 登录办理。
• 403 / scope 不足 → "当前 token 套餐不含 X scope。可调 /openapi/v1/whoami 查具体覆盖范围"
• 429 / 频率超限 → "请求过密，请等下一分钟重试，或升级套餐到更高频率档"
• 服务不可达（连不上）→ "OpenAPI 服务不可达，请检查 ${BASE} 是否在线"
• code=1 / 系统异常 → 首先检查参数（日期格式错 / 必填缺失 / 超范围）——99% 的 code=1 是入参问题，不是服务端故障；常见：kline/daily 同时传 startDate+endDate（已知 bug，改用 size）、plate/stocks-indicator.tradeDate 传 YYYYMMDD（须改 YYYY-MM-DD）
• code=2 / 业务参数错误 → 必填字段缺失（如 holder/find-stocks / holder/holdings 缺 endDate，financial/express / disclosure-date 缺 tsCode）；检查端点必填参数后重试
• code=16 / 上游数据源失败 → "后端上游数据源（Tushare）瞬时故障（限流/网络），等 1 分钟重试一次即可"——不是"无数据"也不是服务端 bug
• code=206 / 套餐不支持 → 端点需要更高套餐（常见：stock.selection 需 Ultra；tmt 需 Ultra）——不是 scope 配置问题，是 token tier 不够
• code=208 / 路径被禁 → "该端点已被 token 的路径黑名单拒绝访问（allowed_paths 配置）"——不是 scope 不足也不是 bug；联系管理员调 /stock/user/admin/openapi/token/path/set 开放此路径
• 数据为空 → 先分辨（非交易日 / 数据未入库 / 股票未上市 / 筛选过严 / 代码错误）
• 排查后仍无法解决 / 需要更多数据服务 → 引导用户访问 <https://www.yyqyx.com/>（升级套餐、申请更多数据维度、反馈问题、获取帮助都在这里），并发上企业微信二维码方便直接咨询：输出 Markdown 图片 ![企业微信](https://www.yyqyx.com/qywx-qr.png)（不支持图片渲染时附链接 <https://www.yyqyx.com/qywx-qr.png>）。

调试层（失败必须附）

• 调用的端点路径
• 请求 body
• 响应的 code / msg / traceId
• 失败分段（如做了分段拉取）

部分成功原则

分段拉取若有失败段，不要说"成功"。明确列出：哪些成功、哪些失败、是否给出部分结果。

Best practices

• 先想 workflow，再想端点
• 能少取就少取（首轮用 top 5 / 近 20 日；用户深挖时再扩展）
• 标的解析永远第一步
• 先结论、再证据
• 板块结论务必注明口径（东财 vs 申万）
• ML 选股结果显示 tradeDate 和 signalType（不要让用户误以为是实时）
• 遇到 "导成 CSV"：取完数据用 jq → CSV 落盘并回报路径

完整闭环示例（agent 内部执行流）

用户："看下宁德时代最近怎么样"

# 1. 标的解析
curl -sf -X POST "${BASE}/openapi/v1/stock/basic/search" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"nameOrCode":"宁德时代"}'
# data[0].tsCode → "300750.SZ"

# 2. WF-1 四个端点并行（没有依赖关系）
curl ... POST /openapi/v1/stock/kline/daily          -d '{"tsCode":"300750.SZ","type":11,"size":20}'
curl ... POST /openapi/v1/stock/indicator/last/by-codes -d '{"tsCodes":["300750.SZ"]}'
curl ... POST /openapi/v1/stock/kline/percentage-change -d '{"tsCode":"300750.SZ"}'
curl ... POST /openapi/v1/stock/market/moneyflow      -d '{"tsCode":"300750.SZ","size":10}'

# 3. 整理给用户：
#    - 一句话：近 20 日 +X.XX%，相对沪深 300 跑赢/跑输 N 个百分点
#    - 估值：PE TTM = X.XX（行业中位数附近 / 偏高 / 偏低）
#    - 主力资金：近 10 日净流入 X.XX 亿
#    - 异常点：哪天放量 / 急跌 / 涨停

用户："ML 今天 BUY 列表"

# 1. selection 必传真实 tradeDate（SQL 精确等值，不传/传占位符=必空，见 §6）——先拿最近交易日
curl ... POST /openapi/v1/stock/market/lhb/latest-dates -d '{}'
# data[0] → "20260605"（示例值，以实际返回为准）

# 2. 用真实日期查（注意 camelCase 字段）
curl ... POST /openapi/v1/stock/selection/ml/results \
  -d '{"tradeDate":"20260605","signalType":"BUY","minScore":0.6,"size":20}'
# 空结果 → 把日期回退到前一交易日再试一次（模型当天可能未跑）
# 整理：tsCode + name + score + signal + 触发的因子（结论里标注 tradeDate，别让用户误以为是实时）

用户："社保基金一零一组合最新持仓"

# 不需要 search（用户给的是机构名不是股票名）
# ⚠️ endDate 事实必填（报告期下界，不传 = code=2 参数错误）；传最近季末日
curl ... POST /openapi/v1/stock/shareholder/holder/find-stocks \
  -d '{"holders":["社保基金一零一组合"],"endDate":"20260331"}'
# 拿到 tsCode 列表 → 进 WF-7 后续步骤

用户："豆粕期权 6/3 跌得最狠的几只"（⭐ 正反对照——这是本 skill 最该学会的一课）

❌ 错误执行（真实事故，别再犯）：
   1. 调一次 whoami → 看到一堆 scope
   2. "印象里期权数据后端是空的" → 直接回 "抱歉，期权数据后端为空"
   → 致命：whoami 不是数据查询；scopes 里明明有 derivative；从没真调过端点（无 traceId）。违反〔第一铁律〕。

✅ 正确执行：
   1. whoami → scopes 含 derivative → 写进记忆卡："derivative ✓，有权限，必须真查"（见〔会话记忆 & 长任务行为〕）
   2. 意图=全市场按日筛选 → 走 WF-9 路径 B
   3. 真调（camelCase + YYYYMMDD）：
      POST /openapi/v1/derivative/option/kline/daily-by-date
           {"startDate":"20260603","exchange":"DCE","size":100}  # DCE=豆粕所在所，翻页拉全
   4. agent 侧：先剔 low<=0 / vol<=0 的没成交行（否则假暴跌），算 (close-preClose)/preClose 排序取最跌的
   5. 交付前自检门：数字有 traceId 出处✓ 口径标了(6/3收盘 vs 前结算、已剔未成交)✓ 没踩 snake_case/占位符✓ 结论先行✓
   6. 交付："6/3 豆粕期权跌幅前 5：① X 合约 -NN%…（口径：DCE 期权日 K，已剔当日未成交合约，traceId=…）"

> 记牢这条对照：whoami 通过 ≠ 查过数据；有 scope = 必须真查；任何"没有"都要有 traceId 背书。

Decision tree — 用户口语 → workflow

agent 自己判断走哪个 workflow，不要把决策反问给用户。下表覆盖 ~95% 的中文口语触发：

如果一条用户消息同时命中多个意图（比如 "茅台财务 + 走势 + 估值"），按 WF-1 → WF-3 → 估值快照的顺序串行跑，最后给一份合并报告。

不要做的事

> 快速定位（100+ 条）： ⏰ 日期格式 → 搜毫秒/ms/横杠/YYYYMMDD/÷1000 | 🔤 字段名拼写 → 搜静默返 undefined/字段名换成 | ⚖️ 单位换算 → 搜单位/万元/千元/亿元/万股 | 🔢 枚举取值 → 搜枚举/方向/status/type/side | 🔕 暂无数据 → 搜暂无数据/PG迁移/暂未上线/止于 | 📋 数据结构 → 搜JSON.parse/嵌套/data:null | 🧠 业务语义 → 搜交集/下界/scope/精确等值

• ❌ 反问用户"你想看什么 / 这是什么任务"——agent 自己根据 decision tree 判断
• ❌ 凭记忆拼 ts_code（"茅台是 600519" 自己脑补）——必须先 POST /openapi/v1/stock/basic/search body {"nameOrCode":"茅台"}（字段是 nameOrCode 不是 keyword）
• ❌ 填 snake_case 字段（trade_date / signal_type / adj_type）——后端用 camelCase，snake_case 直接被忽略 → 拿到默认值/空数据
• ❌ 传 size > 100——会被静默截断到 100，要更多数据请翻页
• ❌ 把 token 明文 echo / 写文件——只在内存中持有
• ❌ 失败循环重试 5 次——网络瞬时错最多重试 1 次，参数错或 401/403 直接告诉用户原因
• ❌ 拿空 data 就说"接口坏了"——先核对参数是否正确（snake_case？字段名拼错？）、是否非交易日、scope 是否覆盖
• 🔴 ❌ 没真调接口就说"没有 / 后端是空的"——这是头号红线（见〔第一铁律〕）。whoami 成功 ≠ 查过数据；scope 里有就必须真打一次对应端点，拿到 traceId 才能下否定结论
• ❌ sw-industry-quo / index-minute 不传 tsCode——两个端点 tsCode 必填，缺省不是全市场而是静默返空
• ❌ 把占位符当真值发出去——body 里别真的出现 <最新> <today> <tsCode> <D> ${...} 这种字面量；日期自己算成 YYYYMMDD，tsCode 先 search，否则后端当未传 → 看似"空"
• ❌ 把 callPut/期权未成交行当真信号——callPut 定长空格补齐要 trim；筛选前先剔 low<=0 / vol<=0（见 WF-9）
• ❌ 把响应里的毫秒时间戳当日期字符串处理——indicator/financial/index/research/fund-ETF 等端点响应日期是 long 整数（如 1780588800000），直接 == "20260605" 或按字符串排序会全都对不上；需 ÷1000 转 UNIX 秒再格式化展示（或直接用端点同时返回的可读字段如 rankTime/newsTimeStr）
• ❌ 用 .tradeDate 取 indicator/roe 的日期——indicator/roe 响应没有 tradeDate 字段，日期在 .endDate（毫秒时间戳）；另有 .period（季度标签如 "Q1"/"Q2"）；用 .tradeDate 一直返回 undefined
• ❌ 把 hm-list.orgs 当普通字符串处理——/stock/market/hm-list 响应的 orgs 是 JSON 字符串数组（格式 "[\"中信证券...营业部\"]"），需 JSON.parse(orgs) 才能迭代；注意区别：hm-detail.hmOrgs（另一端点）是平文本字符串（不需要 parse）——同游资体系两个字段序列化方式不同
• ❌ 把 ths-hot.concept 当普通字符串处理——同花顺热榜响应的 concept 字段同样是 JSON 字符串数组（如 "[\"人形机器人\",\"AI眼镜\"]"），需 JSON.parse(concept) 才能提取概念标签；与 hm-list.orgs 同一类型
• ❌ 在 financial/income-statement 用 nincome/nincomeAttrP 取净利润——A股财报三大表响应字段全部 camelCase：净利润是 nIncome（大写 I，不是 nincome）；归母净利润是 nIncomeAttrP（大写 I 和 P，不是 nincomeAttrP）；同一规律适用于 financial/express（业绩快报）的同名字段
• ❌ 按请求 dataType 解读 hsgt-top10 响应的 marketType——两者枚举值不对称：请求 dataType 1=沪股通/2=深股通/3=港股通；响应 marketType 1=沪股通/3=深股通/2=港股通(沪)/4=港股通(深)——dataType=2(深股通) 返回的是 marketType=3，直接 if marketType==2 会拿到错误结果；另 amount 单位是元（不是万元，amount=3351828340 ≈ 33.5 亿元）
• ❌ 把 kline/daily 响应的 "2026-06-05"（带横杠）直接当其他端点输入的 startDate/endDate——其他端点输入统一是 YYYYMMDD（无横杠 = 20260605）；A股日K响应 tradeDate 带横杠只是自己显示用，不是通用输入格式
• ❌ 向 kline/daily 同时传 startDate + endDate——已知 PG 迁移 bug：两个日期参数同时传会 code:1 系统异常；用 size（最多 100）控制返回条数，需要超过 100 条时配合 page 翻页；单传 startDate（无 endDate）或只传 size 均正常
• ❌ 以为 kline/adj-factor（A股复权因子）的 tradeDate 是毫秒时间戳——A股 kline/adj-factor 的 tradeDate 是 YYYYMMDD 紧凑字符串（如 "20260605"），与 hk/adj-factor/us/adj-factor（毫秒时间戳）完全不同；混淆后按毫秒处理会得到无意义数字
• ❌ 直接对 kline/limits.preClose 做数值运算——该字段可能为 null / "None" 字符串（新股/停牌无前收盘价）；直接 parseFloat(preClose) 或数值比较会 NaN/报错；使用前 if (preClose != null && preClose !== "None") 守护
• ❌ 把 kline/limit-up 的 data:null 当 data:[] 处理——两者语义不同：data:null（code 仍为 0）表示请求参数错误（两个必填整数字段缺失或 ≤0）；data:[] 才是"参数正确但当日无符合条件个股"；看到 null 先检查自己的参数（如 limitUpNum 和 tadeDays 都必须 >0）；⚠️ tadeDays 是 API 已知历史拼写（少一个 r，不是 tradeDays）——写 tradeDays 静默被忽略等同于未传，是导致 data:null 的常见原因
• ❌ 调 plate/stocks-indicator 时传 tradeDate:"20260430"（YYYYMMDD）——该端点输入必须 YYYY-MM-DD（带横杠），传紧凑格式会 code=1 系统异常；数据月更，从 plate/list 取真实 tradeDate 后转格式传入
• ❌ 调 hk/tradecal/us/tradecal 时用 .tradeDate 取日期——这两个端点响应日期字段名是 calDate（不是 tradeDate），前一交易日是 pretradeDate，都是毫秒时间戳
• ❌ 以为 stock.market 已被拆成 4 个子 scope——生产 whoami 返回的仍是 stock.market，stock.plate/stock.lhb/stock.moneyflow/stock.sentiment 这 4 个名字不存在于 whoami 结果，判断 scope 时只看 stock.market
• ❌ 混用 hk/kline 和 hk/kline-adj 的涨跌幅字段名——hk/kline 响应是 pctChg；hk/kline-adj 响应是 pctChange（带 e）；两个端点字段名不同，混用会永远拿到 undefined
• ❌ 期货 settle 端点的对冲保证金率字段写小写 h——正确是 bHedgingMarginRate/sHedgingMarginRate（大写 H），旧文档误写 bhedgingMarginRate/shedgingMarginRate（全小写），写错静默返 null
• ❌ 用 tsCode 查 futures/holding 和 futures/wsr——这两个端点请求参数是 symbol（品种代码，如 "CU" / "RB"），不是 tsCode（合约码，如 "CU2607.SHF"）；传 tsCode 字段静默被忽略，后端按默认值查全品种；须改用 symbol 字段
• ❌ 把 bond/repo/daily.amount 按万元处理——国债逆回购 amount 字段单位是千元（不是万元！），展示成交额时 amount ÷ 1e8 = 亿元（即 ÷ 100,000，而非 ÷ 10,000）；num 字段是成交笔数（整数），不是金额
• ❌ 以为 bond/yc.curveType 是整数——国债收益率曲线端点响应的 curveType 是字符串（"0" = 到期收益率 / "1" = 即期收益率），不是整数；过滤时 curveType == 0 永远为假，必须 curveType === "0" 或 curveType == "0"
• ❌ 把 option/contracts 的 sMonthDate 当 YYYYMM 格式——该字段是 "yyyy-MM" 带横杠字符串（如 "2026-06"），不是紧凑 YYYYMM；maturityDate/listDate 也全是 "YYYY-MM-DD" 带横杠字符串，不要按 YYYYMMDD 格式处理
• ❌ 向 stock/index/kline/weekly / monthly 传 tradeDate 请求参数——指数周线/月线端点请求中不要传 tradeDate，只传 startDate/endDate（YYYYMMDD）；⚠️ 原因：周线/月线锚点日（每周一/每月第一个交易日）与日 K 精确日期不对齐，传 tradeDate 做精确等值匹配会返空；股票个股周月线也有同问题但方向相反（type=12/13 用 size 控制，无 tradeDate 入参）
• ❌ 用 index/kline/weekly/monthly 响应的 chg 字段取涨跌幅绝对值——指数周/月线的涨跌幅绝对值字段名是 change（不是 chg！）；日 K 端点是 chg，周/月 K 换成了 change；写 chg 静默返 undefined；另 pctChg 字段语义不变但命名一致，两端点都叫 pctChg
• ❌ 把 index/kline/weekly / monthly 的 pctChg 当百分比处理——这两个端点的 pctChg 是小数形式（0.0113 = 1.13%，需 × 100 才是百分比），与 index/kline/daily 的 pctChg（已是百分比形式，0.2339 = 0.2339%）语义完全不同；混用会给出 100 倍偏差的涨跌幅
• ❌ 查美股估值时用 us/kline-adj 以为里面有 pe/pb——us/kline-adj 只有复权价格，没有 pe/pb/ps/pcf 字段；美股估值字段（pe/pb/psTtm）只存在于 us/kline（非复权版本），查估值要用 us/kline 而非 -adj
• ❌ 把 us/basic 的 name 字段当公司名显示——大量美股的 name 字段值是字符串 "None"（不是 null，是字面 "None"）；实际英文公司名在 enname 字段，展示公司名用 enname
• ❌ 用 delistDate == null 判断美股是否仍上市——us/basic 的 delistDate 对于在市股票是字符串 "None"（不是 null！），判断是否退市要用 delistDate != "None" 或检查 listStatus 字段
• ❌ 向 stock/index/global 端点要全球指数数据——该端点 2026-06-08 实测 data:[]，底表暂无数据；如用户问全球主要指数表现，主动告知该功能暂不可用，不要反复重试
• ❌ 调 stock/index/sw-heatmap 拿申万行业热力图——该端点 2026-06-08 实测返回空列表（PG 数据迁移缺口）；直接说明"申万行业热力图数据暂未迁移"，改用 stock/index/sw-industry-quo 按行业代码拉日行情替代
• ❌ 调 stock/indicator/short-term 拿短线 19 因子——该端点 2026-06-07 实测底表全空，任何票任何日期都返 data:[]；短线因子模块暂未上线；不要换票换日期重试，直接告知用户"短线因子暂不可用"
• ❌ 调 bond/cb/factor 拿转债技术因子——该端点 2026-06-08 实测 data:[]，底表暂无数据（PG 迁移缺口）；直接说明"转债技术因子数据未迁移"，不要重试
• ❌ 用 stock/kline/weekly-monthly 查远期历史——该端点底表增量积累，2026-06-08 前仅有近几周的数据；查 1 年以上历史周线/月线请改用 stock/kline/daily（type=12 周线 / type=13 月线）
• ❌ 对 fund/etf/kline/daily 的 amount 按千元处理——该端点 amount 单位是元（A 股日 K 是千元）；vol 单位是手（两者相同）；展示 ETF 成交额时 amount ÷ 1e8 = 亿元，而非 ÷ 1e7
• ❌ 对 fund/etf/share-history 的 totalShare/totalSize 当万份/万元处理——totalShare 是份，totalSize 是元，没有做万换算；计算规模时 ÷ 1e8 = 亿元
• ❌ 对 fund/portfolio 用 tsCode 字段取持仓个股代码——该端点响应中 tsCode = 基金代码（如 "110011.OF"），持仓股票代码在 symbol 字段（如 "300750.SZ"）；跨调 indicator/last/by-codes 或 kline/daily 获取持仓股行情时，传 symbol 值，不要传 tsCode；两字段并存于同一行，混用会用基金代码查股票 K 线→永远返空
• ❌ 对 fund/portfolio（基金持仓）的 mkv 和 amount 用错单位——mkv（持仓市值）单位是元（不是万元/千元！）；amount（持仓量）单位是股（不是手/万股！）；展示市值时 mkv ÷ 1e8 = 亿元；展示持仓量时 amount ÷ 100 = 手
• ❌ 向 holder/holdings 传 holderName 字段——该端点的请求参数字段名是 holder（不是 holderName！），且要求传完整全称（如 "全国社会保障基金理事会"）；holderName 是响应字段名，不是请求字段名；传 holderName 静默被忽略 → 无数据；全称从 find-stocks 响应的 holderName 字段取（find-stocks 输入接受简称模糊匹配）
• ❌ 对 holder/holdings 的 holdAmount/holdChange 直接做数值运算——这两个字段是 JSON 字符串，做加减前须 parseFloat()，否则得到字符串拼接结果
• ❌ 用 fund/manager/list 的 endDate == null 判断基金经理是否在任——在任经理 endDate 是空字符串 ""（不是 null），判断在任条件是 endDate.trim() === "" 或 !endDate
• ❌ 把 fund/list（公募基金列表）的日期字段当毫秒时间戳处理——fund/list 的 foundDate/issueDate/purcStartdate/redmStartdate 等日期字段均是 YYYYMMDD 字符串（不是毫秒时间戳），与 fund/etf/kline/daily（ms）/ fund/etf/share-history（ms）等 ETF 相关端点完全不同；场外基金 listDate 通常为 null 也不是 ms
• ❌ 取 PMI 值时用 pmiManufacturing/pmiService 等语义字段名——market/macro/pmi 的响应字段是数字编码（如 pmi010000=制造业综合 / pmi010100=生产 / pmi010200=新订单 / pmi020100=大型企业 / pmi030000=非制造业综合，共 30+ 字段）；用任何语义英文名（pmi/manufacturing/general）取值一律返回 undefined；详细字段映射见 api-quick-reference §十七
• ❌ 取 LPR 值时用 lpr1y/lpr5y 字段名——market/macro/lpr 响应字段是 y1（1年期 LPR）/ y5（5年期 LPR），响应日期字段是 date（YYYYMMDD 字符串，不是 tradeDate）
• ❌ 取 Shibor/LPR 响应里的 tradeDate——macro/shibor 和 macro/lpr 响应的日期字段名是 date（YYYYMMDD 字符串），不是 tradeDate；用 .tradeDate 会一直拿到 undefined
• ❌ 把 bond/cb/list 的 issueSize 当亿元——issueSize 单位是元（如 6000000000.0 = 60亿），展示时 ÷ 1e8 得亿元；直接展示原数字会误导用户
• ❌ 写 convertpriceBef/convertpriceAft 时用大写 P——bond/cb/price-chg 响应中这两个字段全小写 p（convertpriceBef/convertpriceAft），与同端点的 convertPriceInitial（大写 P）命名不一致；大写写法静默返 undefined
• ❌ 因旗舰股研报返空就说"没有研报数据"——research/report 和 research/report-rc 库内仅约 170 只股票有记录；茅台（600519.SH）/ 五粮液（000858.SZ）等旗舰标的实测无数据是采集覆盖不足，不是端点坏了；不传 tsCode 可验证端点是否正常（会返回全库记录）
• ❌ 用小写 ocode/ncode 取 bse-mapping 字段——stock/basic/bse-mapping 响应字段是大写 C：oCode（旧代码）/ nCode（新代码），写小写 ocode/ncode 静默返 undefined
• ❌ 用 eco-cal 的 country 字段过滤国家——market/macro/eco-cal 响应 country 字段不是国名/国码（如 "CN"/"US"），而是事件分类代码（如 "economic_activity"/"inflation"）；按国家过滤应用 currency 字段（如 currency="CNY" 筛中国事件，currency="USD" 筛美国事件）；⚠️ 另：响应 date 字段是毫秒时间戳（不是 YYYYMMDD 字符串）、time 字段是 "HH:mm" 字符串（不是时间戳）——与国内宏观端点的 date=YYYYMMDD 格式不同
• ❌ 用 derivative/futures/weekly-detail 查近期期货周报——该端点历史数据止于 2020-04，不含 2020-04 之后数据；如实告知用户，不要重试
• ❌ 用 derivative/futures/kline/weekly-monthly 查历史周线 / 月线时得到空结果就认为无数据——该端点底表是增量积累，库内覆盖历史有限（同 stock/kline/weekly-monthly）；历史周 / 月线应改用 derivative/futures/kline/daily（freq=W/M 参数不支持，用 daily 按周/月降频自行聚合）；⚠️ 请求时 tsCode（期货合约码，如 "CU2607.SHF"）和 freq（"W" 或 "M"）均必填，漏任一个静默返空
• ❌ 写 futures/weekly-detail 的成交额同比字段为 amountYoy——该端点响应字段名是 amoutYoy（API 已知拼写错误，amout 少一个 m），写 amountYoy 静默返 undefined；另 amount 字段单位是亿元（不是元/万元）
• ❌ 把 kpl-concept-cons 的 conCode 当题材代码——该端点 tsCode = 题材代码（如 "885589.TI"），conCode = 个股代码（如 "300750.SZ"）；两字段语义相反，混用会按题材代码筛股票导致全空；另 description 是题材描述文字（原 Tushare desc 保留字改名），不是 desc
• ❌ 用 delistDate == null 判断港股是否仍上市——hk/basic 的 delistDate 对于在市股票是字符串 "None"（不是 null！），退市股票才是毫秒时间戳字符串（如 "1087315200000"）；判断是否退市要用 delistDate != "None" 或检查 listStatus 字段；与 us/basic 同一 "None" 模式；⚠️ 另：hk/basic.listDate 是毫秒时间戳字符串（如 "1087315200000"），不是数值，需 Number(listDate)/1000|strftime 转换才可读
• ❌ 取 intl-macro 系列端点响应日期时用 .tradeDate——/openapi/v1/intl-macro/us-tycr、us-trycr、us-tbr、us-tltr、us-trltr、hibor、libor、gz-index、wz-index 这 9 个端点日期字段名均是 date（毫秒时间戳 long），不是 tradeDate；用 .tradeDate 一直返回 undefined；⚠️ 与国内宏观（macro/shibor/macro/lpr 的 date 是 YYYYMMDD 字符串）格式不同——intl-macro 的 date 是毫秒，需 ÷1000|strftime 转换
• ❌ 向 hk/fina-indicator 传 reportType="中报" 或 "年报"（不带年份）——港股财务指标 reportType 过滤值必须是带年份的完整报告期串（如 "2024年中报" / "2023年年报"）；传 "中报" / "年报" 精确匹配不到，返回 data:[]；⚠️ 港股只有年报 / 中报，没有季报——传 "2024年一季报" 永远空；不确定报告期就不传 reportType，按时间范围拉返回后再自行筛
• ❌ 把 market/macro/policy-npr 的 pubtime 当毫秒时间戳处理——pubtime 是 "YYYY-MM-DD HH:mm:ss" 带横杠带冒号字符串（如 "2026-06-10 09:00:00"），不是毫秒时间戳；÷1000 或 strftime 处理会报错；直接 pubtime.slice(0, 10) 截取日期部分即可
• ❌ 把 fund/share/history 的 tradeDate 当毫秒时间戳处理——非 ETF 公募基金份额历史的 tradeDate 是 YYYYMMDD 字符串（如 "20260430"），不是毫秒时间戳；与 fund/etf/share-history.tradeDate（毫秒时间戳）格式不同；÷1000 或 strftime 处理会得到无意义结果
• ❌ 把 market/block-trade.vol 当"手"处理——A股大宗交易端点的 vol 单位是万股（不是手！），amount 是万元；与 A 股日 K（vol=手/amount=千元）和 ETF 日 K（vol=手/amount=元）均不同；大宗交易量 vol=1000 代表 1000 万股，不是 1000 手
• ❌ 把 limit-analysis.firstTime/lastTime 或 kpl-list.luTime/ldTime/openTime/lastTime 当 "HH:MM:SS" 字符串处理——这两个端点的盘中时间字段都是 "HHMMSS" 无分隔符字符串（如 "93643" = 9:36:43，"130000" = 13:00:00）；⚠️ 早盘时间只有 5 位（9 开头），切记补全：h=s[0:1]/s[0:2], m=s[-4:-2], sec=s[-2:]；直接按 ":" split 或 "HH:MM:SS" 格式化会出错
• ❌ 把 market/news-sentiment.tradeDate 当毫秒时间戳处理——新闻情绪聚合端点的 tradeDate 是 YYYYMMDD 字符串（如 "20260610"），不是毫秒时间戳；与大多数情绪类端点（limit-cpt-list/limit-step/cyq-chips 等 tradeDate=ms）不同；÷1000 处理会得到无意义结果
• ❌ 调 market/news/types 以为能拿到 news/list.type 整数值字典——news/types 返回的是来源（source）字典（字段 code/displayName/description），code 对应 news/list 响应的 src 字段（如 "sina" / "cls" / "eastmoney"）；不是 news/list.type（整数字段，实测多数记录此字段为 null）的说明字典；type 整数过滤适用场景极少，不确定时省略
• ❌ 把 market/news/list.title 当稳定非空字段——部分新闻条目的 title 字段为 null；展示时优先使用 newsTimeStr（可读字符串如 "2026-06-07 22:12:08"）代替 newsTime（毫秒时间戳），并对 title 做 null 守护
• ❌ 把 fund/nav/history.netAsset/totalNetasset 当真实净资产使用——这两个字段因 Tushare 数据不连续更新，实测多数记录值为 0，不可靠；净资产数据应从财务指标 /stock/financial/indicator 取 totalAsset/totalHldrEqy，fund/nav/history 本身只适合取单位净值 unitNav/accumNav/adjNav
• ❌ 把 us/basic 响应的 tsCode（含交易所后缀，如 "AAPL.O"）直接传给 us/kline 等端点——us/basic 响应字段 tsCode 是 "AAPL.O" / "TSLA.O" 这样带 .O/.N 后缀的格式，但 us/kline/kline-adj/adj-factor/财报三大表等其他端点需要裸 ticker 无后缀（如 "AAPL" / "TSLA"）；带后缀查询静默返空；使用时剥离点号后部分即可
• ❌ 按 A 股 vol/amount 单位解读港股 hk/kline 数据——hk/kline 的 vol 单位是股（shares，不是万手），amount 是港元（不是千元）；比较港股和 A 股成交量/成交额时要注意量纲不同；ETF/大蓝筹 vol 数字会比 A 股看起来大很多
• ❌ 对 limit-step.nums 和 limit-cpt-list.rank 直接排序 / 大小比较——两个字段都是字符串类型（如 "5" / "3"），字符串比较 "10" < "5" 为真（按首字符）；排序或判断"几连板以上"时必须先 parseInt(nums, 10) / Number(rank) 转整数，否则 5 连板排在 10 连板后面
• ❌ 向 us/fina-indicator 传 "Q1" / "A" 这样的短形式 reportType——美股财务指标 reportType 过滤要求东财口径完整报告期串（如 "2025/Q1" / "2023/FY"；FY=年报，Q1-Q4=季度累计）；只传 "Q1" 或 "A" 匹配不到，静默返空；不确定就不传
• ❌ 向 fund/etf/list 传 exchange:"SSE" 或 "SZSE"——ETF 列表端点 exchange 过滤只认短形式（"SH" / "SZ" / "BSE"），传 "SSE"/"SZSE" 被忽略静默返 0 条；另 ETF 中文简称字段名是 cName（大写 N），不是 cname
• ❌ 用 fund/etf/list 的 status="L" 查存续 ETF——fund/etf/list 的 status 枚举与 fund/list 完全相反：fund/etf/list 中 "D" = 存续（active）/ "L" = 已上市 / "S" = 已终止；而 fund/list 中 "L" = 存续 / "D" = 退市；用 status="L" 过滤 ETF 列表只会拿到"已上市"状态记录，不是"存续"；筛取存续 ETF 应传 status="D"
• ❌ 用 fund/dividend.impAnndate 和 .earpayDate 的驼峰大写拼法——fund/dividend 端点这两个字段命名不规则：分红实施公告日是 impAnndate（小写 d，不是 impAnnDate）；收益支付日是 earpayDate（小写 p，不是 earPayDate）；其余字段均为标准驼峰；写大写 D/P 静默返 undefined
• ❌ 按 YYYYMMDD 解析 bond/cb/share 的日期字段——转股进度端点 publishDate / endDate 是 "YYYY-MM-DD" 带横杠字符串（不是 YYYYMMDD）；另 accConvertRatio/remainSize 等字段是 camelCase（旧文档写的 acc_convert_ratio/remain_size 是 snake_case 错误写法）
• ❌ 把 index/main/history 的 data 当扁平数组迭代——该端点响应 data 是 嵌套数组（数组的数组，每个元素是一只指数的历史 K 线序列），不是扁平列表；data[0] 是第一只指数的所有历史记录（数组），不是第一条数据；正确用法：data.flat() 展平或 data.forEach(series => series.forEach(bar => ...))
• ❌ 用多名股东调 find-stocks 以为是并集（OR）——find-stocks 的 holders 数组是交集（AND）逻辑：["社保基金","中央汇金"] 返回两者共同持有的股票，不是任一个持有；要查某一个股东的票，传单元素数组 ["社保基金"]；传多名 = 找共同持仓
• ❌ 以为 holder/holdings.holder 多名是交集（AND）——实为并集（OR）——holder/holdings 的 holder 字段支持逗号分隔多名（如 "全国社会保障基金理事会,中央汇金投资有限责任公司"），语义是并集（OR）：返回任意一个股东持有的记录；⚠️ 与 find-stocks.holders 数组的交集（AND）逻辑相反：两个看似相似的"多股东查询"，find-stocks 取交集，holder/holdings 取并集——混淆后返回数据量远超预期
• ❌ 把 find-stocks/holdings 的 endDate 理解为"截止到某日"——endDate 是报告期下界（后端条件 end_date >= endDate）：传 "20260331" = 返回报告期 ≥ 2026-03-31 的记录（最近季度及之后），而非"只看 2026Q1"；要拿最新持仓传最近已过季末日，要拿多期历史传更早日期（如 "20250101" 返 1 年内所有季报）
• ❌ 按毫秒或 YYYYMMDD 解析 holder/holdings 的 annDate/endDate——这两个日期字段是 "YYYY-MM-DD" 带横杠字符串（如 "2026-03-31"），既不是毫秒时间戳也不是 YYYYMMDD；跨端点按日期对比时需转换格式
• ❌ 把 financial/forecast.netProfitMin/netProfitMax 当元处理——业绩预告净利润预测值两个字段单位是万元（不是元！）；展示时需提示"万元"或 ÷10000 转亿元，不要直接当元展示给用户
• ❌ 写 financial/indicator 单季字段为全小写——单季财务指标字段是 camelCase 且首字母大写：qEps（单季 EPS）/ qRoe（单季 ROE）/ qNetprofitMargin（单季净利率）等，写 qeps/qroe/qnetprofitmargin 全小写静默返 undefined；仅单季 q-系列字段有此规律，dtEps/netProfitMargin 等常规字段仍是常规驼峰
• ❌ 对 plate.buySmAmountStock 做数值运算——板块资金流向端点的小单买入股票数 buySmAmountStock 是 String 类型（无数据时返回 "-"，不是 null/0）；直接做 > 0/parseFloat 等运算会出错；先判 !== "-" 再转数字
• ❌ 向 plates-by-stock 传 tsCode 字段查个股所属板块——该端点入参字段名是 conCode（成分股代码，如 "000001.SZ"），不是 tsCode；响应字段名也是 plateCode/plateName，不是 tsCode/name；另 plate/list 端点返回的板块代码字段才叫 tsCode（如 "885001.TI"），两端点字段语义不同勿混用
• ❌ 向 plate/continue-net 传 contentType/page/size 参数，或把 type 值写成单字母缩写——该端点实际只接受 continueNum（连续净买入天数 int，必填）+ type（板块类型："行业" / "概念" / "地域" 三者之一，必须是中文全称，不能写 "I"/"C"/"A" 等缩写，写了静默返空）；旧文档或 AI 生成代码常附带 contentType/page/size 等字段——这些字段会被忽略，但如果同时漏传 continueNum/type 会返回空或报参数错误
• ❌ 向 plate/stocks-indicator 传 tsCode 字段——该端点入参字段名是 code（取自 plate/list 端点的 tsCode 字段值，如 "885001.TI"）；⚠️ 注意：plate/list 返回的板块代码字段名叫 tsCode，但 plate/stocks-indicator 接收它时字段名换成了 code；传 tsCode 不识别，静默返空
• ❌ 向 derivative/option/contracts 的 dates 参数传 YYYYMMDD 格式——dates 是到期月份数组，格式必须是 YYYYMM（6位，如 ["202606"]），传 8 位 YYYYMMDD（如 ["20260620"]）或带横杠（["2026-06"]）均无法匹配，静默返空；⚠️ 与其他端点的 startDate/endDate 用 YYYYMMDD 不同
• ❌ 把 stock/kline/weekly-monthly 和 stock/kline/week-month-adj 的 endDate 当字符串处理——这两个专用周/月线端点的响应字段中，tradeDate（周一/月初日期）和 endDate（周期末日期，周五/月末）均是毫秒时间戳（不是 YYYYMMDD 字符串）；endDate 名字像字符串其实是 ms，需同样 ÷1000|strftime 转换
• ❌ 用 stock/market/tdx-daily.totalMv 取通达信板块总市值——该端点的总市值字段名是 abTotalMv（A+B 股合计总市值，不是 totalMv！）；totalMv 字段不存在，写了静默返 undefined；另 tdx-index 端点里 totalMv 字段名就是 totalMv，两端点字段名不同勿混淆
• ❌ 对 stock/kline/index-minute 的响应用 freq 或 preClose 字段——指数历史分钟 K 线端点响应没有 freq 字段（旧文档有误）也没有 preClose 字段；完整字段只有 8 个：tsCode/tradeTime(ms)/open/high/low/close/vol(手)/amount(千元)；按 freq 过滤或取 preClose 计算涨跌幅会静默失败
• ❌ 向 stock/kline/percentage-change 传 tsCodes 数组——该端点请求参数字段名是 tsCode（单数字符串），不支持批量数组；旧文档/AI 生成代码常写 tsCodes（复数）导致字段被忽略、返回全市场排序结果；多只标的要循环调用并行（&+wait）；与 indicator/last/by-codes（接受 tsCodes 数组批量）形成对比
• ❌ 调 stock/kline/graph-type 不传 lineType——lineType 是必填参数（K 线周期：11=日 / 12=周 / 13=月，只认这 3 个值）；不传或传错会返回 data:null（code 仍 0）；⚠️ type（形态枚举）当前只实现了 4（W 双底），其余 1/2/3 传了静默返 [] 不报错，用户问其他形态时主动说明"该形态识别暂未上线"
• ❌ 对 market/moneyflow / moneyflow-dc 的 tradeDate 做 ÷1000|strftime 转换——这两个端点的 tradeDate 是 YYYYMMDD 字符串（如 "20260610"），不是毫秒时间戳；直接 .tradeDate 取用即可；÷1000 会使 jq 把字符串当整数相除（得到如 20260 的无意义数字）；⚠️ 同 scope 内大多数端点（limit-step/cyq-chips/ths-daily 等）tradeDate 是 ms，moneyflow 是例外——这是 stock.market scope 内的特例
• ❌ 把 institution-trading / broker-trade 的 side 字段当字符串处理——这两个龙虎榜衍生端点的 side 是整数（1=买方机构/买方营业部，2=卖方机构/卖方营业部），而 lhb/details 的 side 是字符串（"B"=买方，"S"=卖方）；三个端点都在 stock.lhb scope，极易混淆；用 side === "B" 或 side === "S" 过滤 institution-trading/broker-trade 结果永远为空
• ❌ 用 tradeDate 过滤或取 ci-index-member 的时间维度——中信行业指数成分端点响应中无 tradeDate 字段；时间维度只有 inDate（纳入日期，ms 时间戳）和 outDate（剔除日期，ms 时间戳，当前成员 outDate 为 null）；用 tradeDate 过滤请求或取响应均静默失败；判断是否为当前成员要用 outDate === null（或 isNew === "Y"）
• ❌ 混淆 shareholder/hsgt-list 的 type 北向/南向方向——四个 type 值语义固定："HK_SH"=北向（外资经港交所买上证 A 股）/"HK_SZ"=北向（外资经港交所买深证 A 股）/"SH_HK"=南向（内地投资者经沪股通买港股）/"SZ_HK"=南向（内地投资者经深股通买港股）；"北向=外资进来买 A 股"/"南向=内资出去买港股"；HK_ 开头=北向，_HK 结尾=南向
• ❌ 盘中（15:00 前）调 stock/market/auction-close 期望拿到当日尾盘竞价数据——收盘集合竞价（14:57~15:00）结束后数据才写入，当日 15:00 前调用一律返回 data:[]；不是端点出错，也不是 tsCode 有问题；若用户在 15:00 前问"今天尾盘竞价"，告知数据尚未就绪而非说"无数据"；历史某日尾盘竞价不受此限制（传 tradeDate 过去日期正常返回）
• ❌ 把 derivative/sge/kline/daily 的 vol/oi 按"手"处理，或按期货/股票口径解读单位——上金所日 K 线端点的 vol（成交量）和 oi（持仓量）单位是千克（kg，不是手/张/万股！）；amount（成交额）单位是元；priceAvg 是加权均价，单位是元/克（不是元/千克）；展示"成交量 5000" = 5000 千克 = 5 吨黄金，不是 5000 手；另 tsCode 格式含括号（"Au(T+D)"/"Ag(T+D)"），传这类名称时带双引号 shell 转义；settleDire 是递延补偿方向（"B" = 多头补偿/"S" = 空头补偿），不是买卖方向
• ❌ 直接使用 api-quick-reference 文档记录的 mainForceNetInflow 字段名而不验证——stock/market/moneyflow（个股资金流）的主力净流入字段，api-quick-reference 记为 mainForceNetInflow，而 WF 模板（WF-1/WF-4/WF-8）使用的是 mainNetInflow；若该字段返回 null，先 jq '.data[0] | keys' 确认实际字段名再取值；⚠️ 同端点的其他字段（buyLgAmount/sellLgAmount/buyElgAmount/sellElgAmount）名称无歧义，受影响的仅此聚合字段
• ❌ 把 derivative/option/kline/daily-by-date 中 vol=0/amount=0 的行当"当日无成交"或"行情异常"处理——该端点对未成交期权合约仍会输出行（open/high/low/vol/amount 均为 0），但 close/settle 字段含有结算价；"全零"不代表合约不存在或行情崩溃，只是当日零成交；与大多数时序端点（无成交 = 无行）行为不同；筛选真正有交易的合约用 vol > 0，展示合约存续状态时 close/settle != 0 比 vol > 0 更可靠
• ❌ 从 stock/market/bak-daily 取涨跌幅用 pctChg，或取换手率用 turnoverRate——bak-daily 响应字段与同为 A 股行情的 kline/daily/indicator/last 命名不一致：涨跌幅是 pctChange（不是 pctChg！）；换手率是 turnOver（不是 turnoverRate！）；pctChg/turnoverRate 在 bak-daily 响应中不存在，静默返 undefined；⚠️ 同样用 pctChange 命名的端点还有 plate快照/ths-daily/us/kline 等，说明 pctChange 是另一套命名体系，不是 bak-daily 特有错误
• ❌ 向 stock/hk/minute 传 startDate/endDate（YYYYMMDD）作为时间范围——港股分钟 K 的时间参数字段名是 startTime/endTime（不是 startDate/endDate！），格式是 "YYYY-MM-DD HH:mm:ss"（带横杠、冒号、空格，如 "2026-06-10 09:30:00"）；传 startDate/endDate 静默被忽略（端点只按 tsCode 查最近数据）；传对字段名但用 "20260610" 紧凑格式也无法解析——两个错误叠加才能拿到正确数据；⚠️ 与 A 股分钟 K（stock/kline/minute）形成对比：A 股用 startDate/endDate + YYYYMMDDHHmm / YYYYMMDD 格式，两套端点字段名和格式完全不同
• ❌ 对 stock/index/kline/minutes（免费指数分钟K）的 vol 直接做数值运算——该端点 vol 字段可为 null（某些指数分钟无成交量数据）；直接 vol * price 或 vol > 0 判断涨停会 NaN/抛错；⚠️ 同时：该端点响应日期字段名是 tradeTime（毫秒时间戳），不是 tradeDate——与 stock/kline/index-minute（Plus 档付费版）同，两端点均用 tradeTime；另：无 preClose/chg/pctChg 字段，计算涨跌幅需自行用前一行 close 差值
• ❌ 用 st-warning.stType != null 判断 ST 风险类型是否存在——stType 可为空字符串 "" 而非 null；stType != null 判断会让空字符串通过，展示"风险类型：（空）"给用户；应用 stType && stType.trim() 或显式 stType !== "" && stType != null 双重守护；⚠️ 同类陷阱：fund/manager/list.endDate（在任时也是空字符串 "" 而非 null，详见独立 entry）——遇到"空/缺失"类语义字段，先查文档，不要统一假设"空 = null"
• ❌ 把 financial/dividend.stkBoRate 当"每10股送股数"（送股比）读取——stkBoRate 字段语义是每股转增（资本公积转增股本，如 0.3 = 每股转增 0.3 股）；送股（利润分配送股）字段是 stkDiv，不是 stkBoRate；名字里 "Bo" 来自 bonus（红股/转增），不是 "送股比例"；同样容易混淆的是 stkCoRate（每股配股，即配售新股数量），不是"转增比"——三个字段含义：stkDiv=送股 / stkBoRate=转增 / stkCoRate=配股；⚠️ 另：这三个字段值是每股绝对数量（不是每10股，不是百分比）；cashDiv=税前每股现金分红（元），cashDivTax=税后
• ❌ 把 plate/stocks-indicator 响应的 tradeDate 当字符串处理——该端点输入 tradeDate 参数是 "YYYY-MM-DD" 带横杠字符串（如 "2026-04-30"），但响应中的 tradeDate 字段是毫秒时间戳 long（如 1746028800000）；入参和出参格式完全不同——正确传入后读取响应仍需 ÷1000|strftime 转换；⚠️ 两个陷阱组合极易踩：① 入参传 YYYYMMDD → code=1；② 入参格式对了，但按字符串读响应 tradeDate → 得到毫秒数字乱码
• ❌ 向独立 hk/adj-factor / us/adj-factor 端点用 adjFactor 字段名取复权因子——这两个独立复权因子端点的字段名是 cumAdjfactor（不是 adjFactor！）；混淆来源：hk/kline-adj 和 us/kline-adj 行内嵌的复权因子字段叫 adjFactor（与 A 股命名相同），但切换到独立 hk/adj-factor / us/adj-factor 端点时字段名变为 cumAdjfactor——同一 HK/US 域内两类端点命名不一致；⚠️ 另：HFQ 计算公式是 HFQ = BFQ × cumAdjfactor / 当日最新 cumAdjfactor（需两日因子之比），不是直接乘
• ❌ 用 nCashFlowOper 取 financial/cash-flow 经营现金流——financial/cash-flow 端点的经营活动现金净额字段名是 nCashflowAct（不是 nCashFlowOper！）；nCashFlowOper 在该端点不存在；投资净额是 nCashflowInvAct（注意小写f），筹资净额是 nCashFlowsFncAct（注意大写F）——三个净额字段驼峰大小写不统一，逐字核对才安全；⚠️ FCF 字段名是 freeCashflow（小写 c）
• ❌ 认为 plate/continue-net 响应的连续净流入合计字段名是 amount（按 api-quick-reference 文档直接使用）而不验证——api-quick-reference 将该字段记为 amount（连续净流入合计），但 WF-4 模板实际使用的是 totalNetInflow；若该字段返回 null，先 jq '.data[0] | keys' 确认实际字段名再取值；⚠️ 同端点还有 avgAmount（文档名）/ 可能对应 avgNetInflow（实际名）的日均净流入字段，同样建议 keys() 验证
• ❌ 向 tmt/twincome 或 tmt/twincome-detail 传 YYYYMMDD 格式的 startDate/endDate——这两个台湾电子月营收端点的 startDate/endDate 过滤字段格式是 YYYYMM（6位，如 "202604"），不是 YYYYMMDD（8位）；传 8 位格式会按 VARCHAR 字符串比较，一般得到空数据；⚠️ 这是 tmt 系列端点唯一与其他端点不同日期格式的地方（bo-daily/bo-weekly/bo-monthly/bo-cinema/film-record 均用标准 YYYYMMDD），容易被"tmt 都一样"的惯性带坑
• ❌ 向 hk/kline-adj 取 peTtm/pbTtm 估值字段——hk/kline-adj 响应完整字段 18 个，不含任何 pe/pb 估值字段（只有 OHLCV + vwap + adjFactor + turnoverRatio + 市值 + 股本）；港股 peTtm/pbTtm 在 hk/fina-indicator（财务指标宽表，按报告期频率），不在日 K 端点；用 hk/kline-adj 取到的永远是 null；⚠️ 与 us/kline-adj（同样无 pe/pb，见 "查美股估值" ❌ entry）同一陷阱；注意：us/kline（美股非复权 K 线）有 pe/pb，但港股没有对应的含估值日 K 端点——港股日频估值只能走 hk/fina-indicator
• ❌ 向 plate 快照端点用 .leadingTsCode 取领涨股代码——plate 快照（全市场板块涨跌幅快照，POST /openapi/v1/stock/market/plate）响应字段中领涨股代码字段名是 leadingCode（不是 leadingTsCode！）；leadingTsCode 不存在，取到永远是 null；同端点还有 leadingName（领涨股名称）/ leadingPct（领涨股涨幅%），字段名无歧义；⚠️ 注意 plate/list（板块详情时间序列）不含 leadingCode/leadingName/leadingPct 字段，这三个字段仅在 plate 快照（25字段版本）存在
• ❌ 向 plate/cash-flow 取 buyEliteAmount/sellEliteAmount/netBuyElite 字段——plate/cash-flow（板块资金榜）响应完整 19 个字段中不存在这三个字段名；正确的字段名是 buyElgAmount（特大单买入，万元）/ buyLgAmount（大单买入，万元）/ netAmount（板块净流入合计，万元）；⚠️ 该端点只有买方分项（buyElgAmount / buyLgAmount / buyMdAmount / buySmAmount），没有独立的卖方分项字段（净流入用 netAmount）；buyEliteAmount 这类命名来自其他第三方 API 或 AI 臆造，yyqdata 不支持
• ❌ 从 stock/indicator/ma-channel 响应取 .close 收盘价——ma-channel 端点完整字段共 28 个（tsCode/tradeDate + MA/EMA/BOLL/KTN/TAQ/BBI/EXPMA 指标），不含 close 或任何 OHLCV 字段；取 .close 静默返 null；⚠️ 对比：indicator/nine-turn 端点明确包含"K 线基础字段（OHLCV+amount）"，其他技术指标端点（oscillator/trend-volume）同 ma-channel 一样无 OHLCV；需要收盘价与均线对比时，另调 stock/kline/daily 并按 tradeDate 联合，不要期望从指标端点取到
• ❌ 以为 ths-hot.rankTime 是毫秒时间戳并对其做 ÷1000 转换——ths-hot 端点有两个时间字段含义完全不同：tradeDate（⚠️ 毫秒时间戳，需 ÷1000 转 UNIX 秒再格式化）和 rankTime（"YYYY-MM-DD HH:mm:ss" 字符串，可直接用作时间标注，不需任何转换）；对 rankTime 执行 ÷1000 或 Date(rankTime) 按整数操作会得到乱码；⚠️ 混淆来源：ms 时间戳列表标注 ths-hot（rankTime 更直观） 是指"用 rankTime 字段展示更直观"，不是说 rankTime 本身是毫秒