pseudo-longinus/quant-buddy-skills/quant-buddy-skill

筛选正确性与交付恢复

涉及选股、TopN、确认后的过滤条件时，先阅读 研究合同与恢复。研究与页面状态分开记录；缺数据或结果为空仍交付可读研究页，不得把未验证写成零命中。

观照量化投研

WebAgent 宿主交付约定优先：宿主要求金融问题统一“完整问答＋活页”时，所有金融问题先实际 route，再由 QBS 查询验证并发送非终止首答，同轮继续 QBV。包括具体字段、概念解释和“601137 最近如何？”，不依赖建页关键词。Worker 的 QBS_DEFAULT_PAGE_REQUESTED=1 由脚本自动继承；本文件及 leaf workflow 的“只回答/结束/不建页”默认仅适用于独立 QBS。明确不要网页/只回复文字、已有页面只读解读、文件托管与纯维护按各自规则处理。详见 宿主默认建页。

建页意图持续保留：普通“个股分析”与“综合分析”使用同一分类器；附加日期窗口、指标或展示要求不套固定快页。已有显式 QBV/活页意图时传 page_requested:true，查数结束不清除它；非终止首答后执行交接下一步，直至页面与回复验收通过或实际恢复后报告具体阻断。取数 success 不代表页面已交付，详见 先答后建页。

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

本地交付必须复用工具返回的真实路径；不得加 sandbox: 或猜测 Skill 安装目录。排名表逐列核对数据 ID、单位和日期；比值列不能抄到 PE 列。参见 全局执行规则。

个股画像与综合分析的内容合同见 workflows/stock-profile.md：默认交付五个数据章节与综合观察，用户明确要求简短或限定字段时才缩减。读取 Skill 后必须继续读取匹配工作流、实际查询并回复；“将读取文档/准备查询”不是业务交付，不可作为最终答案。明确不要网页只取消建页，不取消上述查询和完整分析。

常见请求的默认口径

• 中文股票全市场排名、未指定市场的涨幅前N热力图，默认 A 股并在首答声明；行业分组默认申万一级，颜色保留股票原涨跌幅、面积或数量明确含义。用户指定其他市场时遵从，不因为这些可披露默认值就停止澄清。
• 已给出“白酒股”等行业范围的刷新看板，先核验平台对应板块及成分，默认 PE TTM、PB；按 quant-standard.md 查询并给出实际行情、成交量、估值首答，再按 answer-first.md 继续 QBV。刷新意图不允许先注册公式包，也不能只回复看板设计。不要先要求用户列股票名单。精确板块不存在或确有同名歧义时才澄清，不用几只龙头冒充全部行业。
• 常见单均线回测可采用 quant-standard 的披露默认值继续执行；用户明确不要网页时不建页。

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

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

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

回测口径硬规则：回测() 的交易时机同时决定成交时点与收益率记账口径。当天开盘买入 / 第二天开盘买入 按开盘到开盘收益记账（今日开盘/昨日开盘-1，含隔夜跳空，跨长假后可超过常规涨跌停）；当天收盘买入 按预物化日收益率记账。看到极端单日收益先跑同交易时机基准，不用涨跌停直觉直接判错。信号按列归一适合每日总权重为1的等权/因子组合；信号不归一表示输入原值就是目标仓位/目标暴露，0-1 择时与0.3等目标仓位不得强制归一。

美股及国内商品期权对应合约查询

用户问槽位对应合约、换约/换月，或要解释期权IV、价格、持仓量变化时，读取 tools/query_option_contracts.md，使用 query_option_contracts。参数为 asset + query_type：snapshot查最新已生效映射，window用lookback_days查自然日窗口。美股按纽约日期，国内按北京时间及品种夜盘归属交易日；国内empty为空槽，不能补旧合约，E1/E2不等同于期货主力/次主力。支持QBV option_contracts 动态授权。保留实际trade_date，按行情实际日与选约生效日对齐，不把拼接价格当持有收益。skill_server将公开参数转换为各市场Celery五字段日期查询；国内依赖新增dataServer查询任务，未部署不得假装成功。

连续期货研究与局部数据差异

外盘换月事件仅适用于分钟：Range返回roll_events，RangeMulti仅解析去重后单资产时返回同结构roll_events，多资产与market请求不附事件。外盘日频换月信息当前缺失，不能用分钟事件解释日频换月、复权或合约；详见换月频率边界。

主连/次主连的跨日、跨频、指标或回测任务，先读 连续期货换月与数据口径。新版事件保留 decision_trade_date（决策日/原始参考价取价日）和 effective_trade_date（生效日），按返回 columns 解析；日频复权价格、原始分钟和未复权换月参考价须统一尺度，派生分钟参考序列按文档的加法价差算法计算。

少量分钟缺失、端点差异、日分钟价格/成交量未对齐，默认按日期、字段和计算路径记录告警，继续可用部分和原定交付；不得把跨频严格相等自行升级为整段窗口或全年数据的通过条件。只有确实依赖缺失输入的结果才标未知或不可计算，其他分析继续。保留原始缺口和有效样本数，不补0、不删端点凑量、不将未知收益当0；日分钟可能来自不同来源，不承诺无条件重聚合相等。

已有文件转活页：先交 QBV 静态托管

用户提供 JPG/PNG、HTML、PDF 等已有文件并要求转活页或公开分享时，优先进入 QBV workflows/existing-file-static-first.md：先 file_prepare 保存原件、生成原始承载页和持久发布参数，保留 file_publish_dir 执行静态发布，验收后在下一次工具调用前先向用户发送链接，file_confirm_delivery确认实际发出的消息，再自动继续已授权的研究、纠错、补指标和QBS接入。复合需求也不能先研究再发布。此顺序高于资产映射、查数、公式验证、图表分类器及“先计算再Handoff”；首版不要求计算胶囊，不先改写原报告。复用真实 task_id/turn_id 和同一个 page_id，不能另建用户可见任务。QBS查询/接入失败只影响增强，保留线上成功版本；未查到不等于平台不支持。纯文件分析、明确不发布不触发；真实公开授权、不可读文件、转换/首次托管问题须如实说明。不得将快照标为实时或已核验。

硬规则（违反必失败）

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

• 公式执行唯一可调用工具名：runMultiFormulaBatchStream。
• 禁止调用或重试旧名/错名：runMultiFormulaBatch / runMultiFormula / run_multi_formula。
• 任何工具返回 未知工具 / Unknown tool / tool not found 后，同名工具 0 次重试，也不得尝试名称变体。
• 若 workflow 已声明唯一正确原生工具，只允许切换到该工具 1 次；仍失败则立即输出受控失败答复。
• 若上一步结果已足够回答用户问题，立即给出业务答案，不再升级查数链；已有明确建页意图时，先发送非终止首答，再按 workflows/answer-first.md 同轮继续 QBV。

1. 认证后验与 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。

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

• 平台已有原生工具时，必须直接调用原生工具：fast_query、fast_query_minute、fast_query_minute_range、fast_query_minute_range_multi、confirmDataMulti、selectByComposition、runMultiFormulaBatchStream、resumeJob、readData、renderKLine、renderChart 等；但普通K线活页必须先走 kline-page-fast-path.md，不可调用 renderKLine。
• 禁止用 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 产物（平台无等价原生解析工具），不算"包装原生工具"。历史分钟长表使用 scripts/fetch_minute_range_csv.py @output/minute-manifest.json --output output/minute-data.json，不能套用日频宽表解析器。但仍禁止用裸 curl / 自写临时脚本替代该脚本。
• 涉及资产时仍需先用 grep presets/assets_db/{类型}.yaml 搜索本地资产库，禁止整文件读取；命中多条先澄清，未命中再交给服务端兜底解析。
• 英文代码无市场后缀时必须先 grep 对应资产库确认 ticker 格式。

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

• 本地 RESUME_CONTEXT_MISMATCH 可按工具返回的唯一 resume_params 修正一次；UNIVERSE_SCOPE_MISMATCH 可在核对目录后修正为精确行业一次。这两类尚未提交网络请求，不得用这个例外重复真实查询错误。
• 同一工具、同一参数结构、同一错误类型出现第 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，禁止重提原批次。

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

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

1. 先读 workflow 再操作：按下方「场景路由」表加载对应 workflow，不要自行猜测参数格式。
2. 配置/认证错误立即停止，不得在普通查数流程中转为认证收集：

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

1. 最终答案首句必须是数据结论：回答用户时，第一句话必须直接给出数据结论（如资产名+数值、表格、或"符合条件的共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 时才进入自愈/排错流程。

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

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

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

⚠️ 模糊词处理规则（先判断是否真歧义，再决定反问还是默认口径直行）：

下列词在量化语义中存在多种定义，必须正确处理：

• 技术分析类：支撑位 / 阻力位 / 压力位 / 颈线位 / 关键位 / 关键点位 / 突破位
• 走势判断类：趋势 / 趋势预测 / 后市判断 / 还能不能涨 / 会不会跌 / 短期看法 / 中线看法
• 盘面定性类：异动 / 主力 / 主力流向 / 庄家动向 / 强势 / 弱势 / 抗跌 / 抗跌性
• 健康度类：基本面好不好 / 估值贵不贵 / 财务健康 / 业绩怎么样 / 基本面

判定流程（按顺序匹配，命中即停）：

1. 综合分析请求 → 用默认口径直行，禁止反问阻塞。

判定：用户在一句话里列出 ≥2 个分析维度（如"基本面 + 技术指标 + 趋势"、"估值 + 财务 + 走势"），或明确说"全面分析 / 综合看一下 / 给一份报告"。 做法：直接走 stockProfile（综合画像）+ 常规技术指标 + 默认趋势口径，报告首句告知用户使用的口径（例："本次按以下默认口径输出：基本面=综合画像（估值+财务+资金流+波动率），技术=MACD/KDJ/RSI/布林带，趋势=MA20/MA60 排列方向。如需调整口径请告诉我。"）。

1. 孤立的单点定义性请求 → 必须反问。

判定：触发词单独出现，且其定义直接决定结论数值（如"贵州茅台支撑位是多少"、"宁德时代趋势怎么样"，无任何其他维度上下文）。 做法：反问 ① 口径定义（如"支撑位"=近N日最低/布林下轨/均线密集区）；② 时间窗口；③ 输出格式。

1. 触发词只是修饰语 → 直行。

判定：用户主体诉求清晰，触发词只是顺带描述（如"找最近基本面改善的股票"主体是筛选，"基本面改善"已隐含"营收/净利同比上升"等可执行口径）。 做法：用最常见的可执行口径执行，并在结果中标注口径。

实测教训（T-036）：用户问"贵州茅台支撑位"，模型擅自用"60日最低价附近"作为定义直接执行——这是孤立单点请求，应走流程 2 反问。 反例（不要再犯）：用户问"分析东方财富的基本面、技术指标、趋势预测"，模型反问 4 个问题阻塞——这是综合分析请求，应走流程 1 默认口径直行。

1. 工具返回 `SKILL_VERSION_MISMATCH` 时必须自愈，不得继续执行原任务：当任何工具调用的输出中出现 "error": "SKILL_VERSION_MISMATCH" 时，说明当前对话上下文中的工具签名/参数格式已过时。此时必须执行以下自愈流程（每步不得省略）：
2. 立即停止当前任务，不得再调用任何平台工具；
3. 调用 newSession（新建 session，获取新 task_id）；
4. 强制重读 SKILL.md（本文件）+ 当前场景对应的 workflow 文档 + 涉及的 tools/*.md；
5. 以新读取的工具签名和参数格式重新执行用户原始任务；
6. 禁止询问用户"是否继续"或解释版本升级过程——直接静默完成自愈并返回结果。
7. CHANGELOG / skill-changelog 仅作为审计，不作为规则源：CHANGELOG.md、skill-changelog/** 是按时间叠加的变更记录，包含已被后续版本反转或废弃的旧口径。任何「执行顺序、字段名、协议块语义、工具签名、参数格式」相关的判断，必须以 SKILL.md + workflows/** + tools/** + references/troubleshooting.md 为唯一权威；CHANGELOG 描述与上述文件冲突时，以上述文件为准。CHANGELOG 仅可用于：① 排查问题时回看「哪一版动过什么」；② 升级成功后做 5 条以内的版本上下文摘要。禁止：把 CHANGELOG 某条历史叙述当作当前执行规则、依据 CHANGELOG 推断现行参数格式、或在 CHANGELOG 与 SKILL.md 冲突时偏向 CHANGELOG。
8. 判断工具成败看返回 body 的 `code`/`success`，不看 HTTP 状态码：HTTP 200 不代表业务成功——body 里出现 "code": -1 / "success": false 即为业务错误，必须按失败处理（读 error/message 再决定重试/改参/走排查表），禁止「HTTP 通了就当成功」继续往下走。另：call.py 返回 "error": "INVALID_TOOL_NAME" 表示工具名写错或缺失（工具名必须排在命令最前、且为已注册工具名），属可立即修正的本地错误。详见 references/troubleshooting.md 顶部「成败判定通则」。
9. 先答后建页：每日/定期复盘、行情监控、画线/画图、执行回测、看 K 线等操作请求，以及已登记的稳定榜单（低 PE + 高 ROE + 选股/排名 + TopN）必须实际执行 scripts/live_page_routing.py route，不能把普通 TopN 全部升级为活页。上述操作本身构成活页意图，不要求用户另说“网页”；纯概念解释不建页。上下文中的真实建页意图可传 --page-requested，明确不要网页/暂不发布仍优先；不要画图只约束表现形式，不能否决表格型活页。按 先答后建页 执行：QBS 查询验证后先发完整非终止业务答案，再准备 Capsule/Handoff/Job，默认 same_turn 进入 QBV；可靠内部委派是可选分支，不得重复执行。prepare-validated-page 接受 answer_structure；未传时按首答顺序的 validated_roles 生成保守表格结构。全量计算规模与页面展示规模分离：排名未指定数量时默认 Top20，页面只渲染 Top20；Formula Package/Data Grant 负责服务端缓存和动态取数，不能因为参与计算的股票多就把页面降级成静态快照。只有用户明确要求固定快照，或动态数据路由经过验证确实不可用时，才使用 `validated_snapshot`，并在回复中如实说明不会自动更新。成功后按 next_action 继续，不重复 handoff/prepare。prepare 不是图表或页面完成，QBV 不可访问时必须用本 Skill 的 update 写回返回的 on_unavailable 失败字段，不得留 queued 或假称后台执行。路由/页面失败不撤销正常首答；无中途可见消息能力时如实记录限制。页面路由、权限、同页更新和公开验收仍由 QBV 负责。单资产多标准字段同图、近N日行业排名分别沿专用快路径，快路径也必须先答后准备页面。