quant-buddy-skill

观照量化投研

首屏优先：先读本文件前部的「平台工具参数速查」「硬规则」和「场景路由」。简单行情、窗口序列、最近报告期、固定区间收益、K 线图等高频任务命中 Fast Path 时，无需继续整本通读。

平台工具参数速查（高频踩坑，先看这一段）

下表是 LLM 最容易写错的三个 schema。任何调用前先核对，不要凭"看起来合理"猜参数名。

口径转换（confirmDataMulti 查询词）：用户写 PE(TTM) / 归母净利润 等英文或缩写时，查询词应使用中文规范名（如 市盈率 TTM / 归母净利润），而不是把用户原文照抄进 data_desc。详细规则见 workflows/global-rules.md#指标口径精确匹配。

硬规则（违反必失败）

1. 工具名与 unknown-tool 红线（最高优先级）：

   • 公式执行唯一可调用工具名：runMultiFormulaBatchStream。
   • 禁止调用或重试旧名/错名：runMultiFormulaBatch / runMultiFormula / run_multi_formula。
   • 任何工具返回 未知工具 / Unknown tool / tool not found 后，同名工具 0 次重试，也不得尝试名称变体。
   • 若 workflow 已声明唯一正确原生工具，只允许切换到该工具 1 次；仍失败则立即输出受控失败答复。
   • 若上一步结果已足够回答用户问题，必须直接收敛回答，禁止继续升级工具链。

2. 认证后验与 session 初始化：

   • 不要在普通查数题第一步读取 config.json，也不要检查 .session.json、output/.session*.json 或任何本地 session 文件。
   • 只要本轮准备调用平台原生工具，先直接调用原生 newSession；不得用 Bash / Glob / Read / ls 做 session 存在性探测。
   • quant-buddy-view 上游继承例外：若当前任务由 quant-buddy-view 编排，且上游已经通过 trace_context.py begin 创建 task_id，不得再生成第二个 task_id。优先由 QBV 的 scripts/qbs_bridge.py 调用本技能；bridge 会传 {"task_mode":"inherit","task_id":"<上游 task_id>","task_source":"quant-buddy-view","user_query":"<用户原始问题>"} 并用 QBS_SESSION_KEY=<task_id> 隔离并发 session。此例外只用于跨 Skill 会话绑定。
   • 继承 task_id 时必须使用显式 task_mode=inherit，不要通过 qbv_ 等字符串前缀猜测来源。继承 session 会锁定 task_id；后续参数若传入不同值，必须按 TASK_ID_CONTEXT_MISMATCH 停止，不能静默拆链。
   • quant-buddy-skill 独立使用时保持原行为：不传 task_mode/task_id，由 newSession 自动生成新的 UUID 并上报 session begin。
   • 工具实际返回 api_key 为空 / code: 1 / 401/402 时才进入认证引导并停止当前查数任务。
   • 同一对话追问可复用当前 session；新问题必须新建 session。
   • 所有业务 HTTP/SSE 请求统一携带 x-skill-name: quant-buddy-skill 与当前 x-task-id，用于跨 Skill Trace 聚合；quant-buddy-view 上游任务不得切换 task_id。

3. 原生工具优先，禁止脚本包装：

   • 平台已有原生工具时，必须直接调用原生工具：fast_query、fast_query_minute、confirmDataMulti、selectByComposition、runMultiFormulaBatchStream、resumeJob、readData、renderKLine、renderChart 等。
   • 禁止用 Bash / shell / Python / scripts/call.py / run_skill_script 包装已有原生平台工具。唯一编排例外是 quant-buddy-view 的 qbs_bridge.py，它只负责继承 task_id 和隔离 session，不改写业务参数或结果。
   • 只有平台明确不存在等价原生工具，且 workflow 明确允许脚本兜底时，才可使用本地脚本。
   • 许可例外（csv 解析）：当 fast_query 返回 mode:"csv" + csv_url（数据点 > 500 的正常交付）时，调用 python scripts/fetch_fastquery_csv.py "<csv_url>" 下载并解析该 csv 属于许可路径——这是消费工具返回的 OSS 产物（平台无等价原生解析工具），不算"包装原生工具"。但仍禁止用裸 curl / 自写临时脚本替代该脚本。
   • 涉及资产时仍需先用 grep presets/assets_db/{类型}.yaml 搜索本地资产库，禁止整文件读取；命中多条先澄清，未命中再交给服务端兜底解析。
   • 英文代码无市场后缀时必须先 grep 对应资产库确认 ticker 格式。

4. 工具失败熔断：同类错误不得重复

   • 同一工具、同一参数结构、同一错误类型出现第 1 次后，只能按 workflow 声明的备用路径切换；无备用路径则受控失败。
   • 禁止无新信息地重复调用失败工具；禁止尝试名称变体；禁止读更多文档代替执行；禁止用 shell/Python 包装绕过失败工具。
   • runMultiFormulaBatchStream / resumeJob 只有最终 completed 且全部结果成功时才返回 validation_receipt_file；failed、部分失败、deferred 均不生成收据。QBV 编排必须以该收据作为进度完成证据。长结果可传 output_mode:"summary"：completed 保留 data_id/expression_id/status；deferred 额外完整保留 status/task_id/trace_id/job_id/stream_url/_deferred。deferred 缺 task_id/trace_id 时返回 DEFERRED_CONTINUATION_MISSING，禁止重提原批次。

5. 任何 workflow 失败退出时必须输出受控失败答复：禁止以空白或纯过程日志结束对话。失败答复必须包含：

   • ①用户的原始问题（一句话复述）
   • ②失败卡在哪一步（工具名 + 错误摘要）
   • ③给用户的一句话说明（"当前无法获取…，原因：…"）
   • 可选④：用户可采取的下一步（如"稍后重试"或"换用完整链路"）

6. 先读 workflow 再操作：按下方「场景路由」表加载对应 workflow，不要自行猜测参数格式。

7. 配置/认证错误立即停止，不得在普通查数流程中转为认证收集：

   • 工具返回 API Key 缺失错误（含 api_key 为空 消息 / code: 1）：立即停止查数，输出新用户引导消息（格式见「前置条件」章节模板），禁止继续执行查数；等待用户粘贴 Key 后再执行配置向导。
   • 其他工具报错（网络、服务端错误等）：直接报告"内部工具异常"，不做认证相关引导。

8. 最终答案首句必须是数据结论：回答用户时，第一句话必须直接给出数据结论（如资产名+数值、表格、或"符合条件的共N只"），绝对禁止以"已成功获取""数据已获取""根据返回结果""让我来"等过程性陈述开头。违反此规则 = 必须删除过程话术后重新输出。

   • 禁止原样粘贴工具 JSON：工具返回 code:0 / success:true 后，最终答复必须把 data.results 等业务字段转写成人类可读结论（一句话、短表格或名单）。除非用户明确要求"给我原始 JSON / 调试输出"，否则不得把完整工具响应原样发给用户。
   • 隐藏运行态字段：最终答案默认忽略 code、success、task_id、_quota、skill_latest_version、skill_update_available、skill_update_enforced、skill_self_update、auto_upgrade*、version_check 等运行态/升级字段；这些字段只供 Agent 判断流程，不是给普通用户看的答案内容。
   • 版本心跳不打断业务回答：若业务 data 已成功返回，即使响应体带版本心跳，也必须先回答用户问题；只有工具明确返回业务失败或 SKILL_VERSION_MISMATCH 时才进入自愈/排错流程。

9. 用户条件冻结，不得改写：执行前必须逐字核对用户原始条件，以下改写行为均属违规（一旦发现必须回退并重新确认）：

   • 百分比↔小数互转（如"股息率>3%"禁止改写为 >0.03）
   • 相对时间改为年份区间（如"过去10年"禁止改写为"2015-2025"）
   • 资产宇宙替换（如"普通股票"禁止改写为"万得全A成分股"或"非ST股"）
   • 事件口径扩大（如"年报/半年报"禁止扩大为全部业绩披露类型）
   • 卡片附加条件继承：命中知识卡片后，若卡片含用户未明确提出的"首次/非ST/封板/流动性门槛"等附加条件，必须先删除再执行，禁止默默继承进最终答案

10. 任务含糊时先反问，禁止猜测开干：若用户的指令有 2 种以上合理解读（如"批量确认X"不清楚是确认指数本身还是全部成分股、"分析一下Y"不清楚要哪个维度），第一步必须向用户提问澄清，不得凭推测选择一种解读自行执行。反问应简洁列出各种可能（例："您的意思是 ① … 还是 ② …？"），等用户确认后再继续。唯一例外：用户语义明确无歧义（如"给我贵州茅台今日收盘价"），无需反问。