quant-buddy-skill
查询A股、港股、美股股票及指数的最新收盘价、开盘价、涨跌幅、成交额、成交量、换手率、PE、PB、市值等实时行情与估值数据;支持查询 A 股股票所属行业。 查询最近N个交易日的价格序列、日涨跌幅序列、窗口最高价、最低价、振幅等短期统计。 查询单个资产当前盘中或最近完整交易日的分钟频 OHLCVA 序列(开高低收、成交量、成交额)。 查询上市公司最近报告期的营业收入、净利润、归母净利润、ROE、总资产、资产负债率等财务指标(A股及部分港/美股字段,以工具返回为准)。 查询单只股票的预计算及千维动态指标画像,按估值、财务分析、资金流向、波动率、宏观胜率背景、资
Install
npx skills add https://github.com/pseudo-longinus/quant-buddy-skills/tree/main/skills/quant-buddy-skill
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install pseudo-longinus-quant-buddy-skills@llmmart
git clone https://github.com/pseudo-longinus/quant-buddy-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole pseudo-longinus/quant-buddy-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
筛选正确性与交付恢复
明确要求选股时附公司信息,且现有路由需要活页时,在 prepare-validated-page / Handoff 顶层增加可选 asset_info_request,引用已验证选股 selection_role;默认主营业务+近期事件、300字、text,自定义主题写入prompt并保留日期与来源要求。首答只交付量化名单、口径和量化分析,不逐股搜索或撰写主营与事件;公司资料由活页官方模块异步查询。按 交接说明 同轮交给QBV;模块成功接入并交付活页时,补充异步加载及卡片积分入口提示,聊天收费说明统一沿用QBV回执的 llm_billing/billing_notice,不重复编写规则。需求不进入已验证结论、不参与筛选和排名;普通选股不启用,“不要网页”优先。
涉及选股、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 的披露默认值继续执行;用户明确不要网页时不建页。
平台工具参数速查(高频踩坑,先看这一段)
取价函数盘中刷新:收盘价/开盘价/最高价/最低价(资产,最后一日分钟刷新) 保留日频序列,最近交易日使用盘中行情。use_minute_data:true 执行时服务端会为四类普通取价调用补上该参数,已带参数的调用不重复追加。做活页公式包时,从验证开始就显式保留参数,并使用普通执行合同(use_minute_data:false 或省略);A股结果及其派生结果应按 cn.chart:intra 刷新。不要把已验证的 true 合同直接删字段重登记。详见 盘中刷新模式。
活页资源归属:交接 QBV 前,数据授权和公式包须使用目标页面所有者的 API Key 注册。签名可公开取数不代表可跨用户复用;复制页面须为目标用户创建独立资源。遇到提交归属拒绝,按原有 message 更换注册身份、重建原口径资源并完整替换 ID 与 signature 后重提;不得只改页面用户名、只替换 ID 或删除分析内容。管理员也须先预览影响并取得明确确认后才转接,详见 公式包与页面归属。沙箱实例本身暂不处理归属。
下表是 LLM 最容易写错的三个 schema。任何调用前先核对,不要凭"看起来合理"猜参数名。
| 工具 | ✅ 正确参数 | ❌ 模型常见错误(已被 call.py 自动归一化或拦截,但仍应避免) |
|---|---|---|
confirmDataMulti |
{"data_desc": "市盈率 TTM,股息率"} — 逗号分隔字符串 |
{"queries": [...]} / {"query": "..."} / {"names": [...]} |
runMultiFormulaBatchStream 公式中引用 session 中间变量 |
必须用双引号包裹:排序値 = "A股股息率〔估値数据〕" * "条件合并" |
裸变量名相乘:"A股股息率…" * 条件合并 ← 平台直接报错 |
readData |
{"ids": ["69fe…<24位hex>"], "mode": "last_column_full"} — 必须是 runMultiFormulaBatchStream 返回的 data_id 字段(hex) |
传中文变量名 {"ids": ["Top10股息"]} / 用错参数名 {"index_title": "..."} / {"variable_names": [...]} / 传 expression_id 而非 data_id(两者相邻易混,传错会返回 "error": "IndexInfo {id}") |
口径转换(confirmDataMulti 查询词):用户写 PE(TTM) / 归母净利润 等英文或缩写时,查询词应使用中文规范名(如 市盈率 TTM / 归母净利润),而不是把用户原文照抄进 data_desc。详细规则见 workflows/global-rules.md#指标口径精确匹配。
回测口径硬规则:回测() 的交易时机同时决定成交时点与收益率记账口径。当天开盘买入 / 第二天开盘买入 按开盘到开盘收益记账(今日开盘/昨日开盘-1,含隔夜跳空,跨长假后可超过常规涨跌停);当天收盘买入 按预物化日收益率记账。看到极端单日收益先跑同交易时机基准,不用涨跌停直觉直接判错。信号按列归一适合每日总权重为1的等权/因子组合;信号不归一表示输入原值就是目标仓位/目标暴露,0-1 择时与0.3等目标仓位不得强制归一。
国内期货期权行情与合约映射
国内期货期权数据不只包含商品:现有槽位行情还包含沪深300(数据列 沪深300主连 / IF.CFE,期权代码 IO)、上证50(上证50主连 / IH.CFE,HO)、中证1000(中证1000主连 / IM.CFE,MO)。查询价格、IV、持仓量或成交额时先走 股指期权槽位行情,使用目录中的 国内期货期权-* 数据,不因合约映射接口限制直接答“没有股指期权数据”。32个目录字段不保证每个标的、每槽、每日都有有效值;完整期权链和具体合约映射须分别确认。
美股及国内商品期权对应合约查询
用户问槽位对应合约、换约/换月,或要解释期权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查询/接入失败只影响增强,保留线上成功版本;未查到不等于平台不支持。纯文件分析、明确不发布不触发;真实公开授权、不可读文件、转换/首次托管问题须如实说明。不得将快照标为实时或已核验。
硬规则(违反必失败)
工具名与 unknown-tool 红线(最高优先级):
- 公式执行唯一可调用工具名:
runMultiFormulaBatchStream。 - 禁止调用或重试旧名/错名:
runMultiFormulaBatch/runMultiFormula/run_multi_formula。 - 任何工具返回
未知工具/Unknown tool/tool not found后,同名工具 0 次重试,也不得尝试名称变体。 - 若 workflow 已声明唯一正确原生工具,只允许切换到该工具 1 次;仍失败则立即输出受控失败答复。
- 若上一步结果已足够回答用户问题,立即给出业务答案,不再升级查数链;已有明确建页意图时,先发送非终止首答,再按 workflows/answer-first.md 同轮继续 QBV。
- 公式执行唯一可调用工具名:
认证后验与 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。
- 不要在普通查数题第一步读取
原生工具优先,禁止脚本包装:
- 平台已有原生工具时,必须直接调用原生工具:
fast_query、query_kline、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 格式。
- 平台已有原生工具时,必须直接调用原生工具:
工具失败熔断:同类错误不得重复
- 本地
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,禁止重提原批次。
- 本地
任何 workflow 失败退出时必须输出受控失败答复:禁止以空白或纯过程日志结束对话。失败答复必须包含:
- ①用户的原始问题(一句话复述)
- ②失败卡在哪一步(工具名 + 错误摘要)
- ③给用户的一句话说明("当前无法获取…,原因:…")
- 可选④:用户可采取的下一步(如"稍后重试"或"换用完整链路")
先读 workflow 再操作:按下方「场景路由」表加载对应 workflow,不要自行猜测参数格式。
配置/认证错误立即停止,不得在普通查数流程中转为认证收集:
- 工具返回 API Key 缺失错误(含
api_key 为空消息 /code: 1):立即停止查数,输出新用户引导消息(格式见「前置条件」章节模板),禁止继续执行查数;等待用户粘贴 Key 后再执行配置向导。 - 其他工具报错(网络、服务端错误等):直接报告"内部工具异常",不做认证相关引导。
- 工具返回 API Key 缺失错误(含
最终答案首句必须是数据结论:回答用户时,第一句话必须直接给出数据结论(如资产名+数值、表格、或"符合条件的共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时才进入自愈/排错流程。
- 禁止原样粘贴工具 JSON:工具返回
用户条件冻结,不得改写:执行前必须逐字核对用户原始条件,以下改写行为均属违规(一旦发现必须回退并重新确认):
- 百分比↔小数互转(如"股息率>3%"禁止改写为
>0.03) - 相对时间改为年份区间(如"过去10年"禁止改写为"2015-2025")
- 资产宇宙替换(如"普通股票"禁止改写为"万得全A成分股"或"非ST股")
- 事件口径扩大(如"年报/半年报"禁止扩大为全部业绩披露类型)
- 卡片附加条件继承:命中知识卡片后,若卡片含用户未明确提出的"首次/非ST/封板/流动性门槛"等附加条件,必须先删除再执行,禁止默默继承进最终答案
- 百分比↔小数互转(如"股息率>3%"禁止改写为
任务含糊时先反问,禁止猜测开干:若用户的指令有 2 种以上合理解读(如"批量确认X"不清楚是确认指数本身还是全部成分股、"分析一下Y"不清楚要哪个维度),第一步必须向用户提问澄清,不得凭推测选择一种解读自行执行。反问应简洁列出各种可能(例:"您的意思是 ① … 还是 ② …?"),等用户确认后再继续。唯一例外:用户语义明确无歧义(如"给我贵州茅台今日收盘价"),无需反问。
⚠️ 模糊词处理规则(先判断是否真歧义,再决定反问还是默认口径直行):
下列词在量化语义中存在多种定义,必须正确处理:
- 技术分析类:支撑位 / 阻力位 / 压力位 / 颈线位 / 关键位 / 关键点位 / 突破位
- 走势判断类:趋势 / 趋势预测 / 后市判断 / 还能不能涨 / 会不会跌 / 短期看法 / 中线看法
- 盘面定性类:异动 / 主力 / 主力流向 / 庄家动向 / 强势 / 弱势 / 抗跌 / 抗跌性
- 健康度类:基本面好不好 / 估值贵不贵 / 财务健康 / 业绩怎么样 / 基本面
判定流程(按顺序匹配,命中即停):
综合分析请求 → 用默认口径直行,禁止反问阻塞。 判定:用户在一句话里列出 ≥2 个分析维度(如"基本面 + 技术指标 + 趋势"、"估值 + 财务 + 走势"),或明确说"全面分析 / 综合看一下 / 给一份报告"。 做法:直接走
stockProfile(综合画像)+ 常规技术指标 + 默认趋势口径,报告首句告知用户使用的口径(例:"本次按以下默认口径输出:基本面=综合画像(估值+财务+资金流+波动率),技术=MACD/KDJ/RSI/布林带,趋势=MA20/MA60 排列方向。如需调整口径请告诉我。")。孤立的单点定义性请求 → 必须反问。 判定:触发词单独出现,且其定义直接决定结论数值(如"贵州茅台支撑位是多少"、"宁德时代趋势怎么样",无任何其他维度上下文)。 做法:反问 ① 口径定义(如"支撑位"=近N日最低/布林下轨/均线密集区);② 时间窗口;③ 输出格式。
触发词只是修饰语 → 直行。 判定:用户主体诉求清晰,触发词只是顺带描述(如"找最近基本面改善的股票"主体是筛选,"基本面改善"已隐含"营收/净利同比上升"等可执行口径)。 做法:用最常见的可执行口径执行,并在结果中标注口径。
实测教训(T-036):用户问"贵州茅台支撑位",模型擅自用"60日最低价附近"作为定义直接执行——这是孤立单点请求,应走流程 2 反问。 反例(不要再犯):用户问"分析东方财富的基本面、技术指标、趋势预测",模型反问 4 个问题阻塞——这是综合分析请求,应走流程 1 默认口径直行。
工具返回
SKILL_VERSION_MISMATCH时必须自愈,不得继续执行原任务:当任何工具调用的输出中出现"error": "SKILL_VERSION_MISMATCH"时,说明当前对话上下文中的工具签名/参数格式已过时。此时必须执行以下自愈流程(每步不得省略):立即停止当前任务,不得再调用任何平台工具;
调用
newSession(新建 session,获取新 task_id);强制重读
SKILL.md(本文件)+ 当前场景对应的 workflow 文档 + 涉及的 tools/*.md;以新读取的工具签名和参数格式重新执行用户原始任务;
禁止询问用户"是否继续"或解释版本升级过程——直接静默完成自愈并返回结果。
CHANGELOG / skill-changelog 仅作为审计,不作为规则源:
CHANGELOG.md、skill-changelog/**是按时间叠加的变更记录,包含已被后续版本反转或废弃的旧口径。任何「执行顺序、字段名、协议块语义、工具签名、参数格式」相关的判断,必须以SKILL.md+workflows/**+tools/**+references/troubleshooting.md为唯一权威;CHANGELOG 描述与上述文件冲突时,以上述文件为准。CHANGELOG 仅可用于:① 排查问题时回看「哪一版动过什么」;② 升级成功后做 5 条以内的版本上下文摘要。禁止:把 CHANGELOG 某条历史叙述当作当前执行规则、依据 CHANGELOG 推断现行参数格式、或在 CHANGELOG 与 SKILL.md 冲突时偏向 CHANGELOG。判断工具成败看返回 body 的
code/success,不看 HTTP 状态码:HTTP 200 不代表业务成功——body 里出现"code": -1/"success": false即为业务错误,必须按失败处理(读error/message再决定重试/改参/走排查表),禁止「HTTP 通了就当成功」继续往下走。另:call.py返回"error": "INVALID_TOOL_NAME"表示工具名写错或缺失(工具名必须排在命令最前、且为已注册工具名),属可立即修正的本地错误。详见references/troubleshooting.md顶部「成败判定通则」。先答后建页:每日/定期复盘、行情监控、画线/画图、执行回测、看 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日行业排名分别沿专用快路径,快路径也必须先答后准备页面。QBS→QBV 只复用本轮已经算完的部分,不把 QBV 改成 QBS 专用渲染器:
create|existing_page在 Handoff 前优先运行scripts/qbv_computation_capsule.py build @capsule-input.json,生成qbs_computation_capsule_v1。胶囊必须同时包含用户核心问题/主图意图、资产规范化结果、可复现查询或公式合同及 fingerprint、结果快照或 artifact SHA256、字段映射、结论与验证收据;禁止只交 PNG 或一句总结。 同一业务 role 对应多个已物化结果时可传data_ids;构建器按原顺序展开为role__01、role__02…,保留原始 ID 字符串并同步required_roles,禁止 Agent 手工改写或复制 ID。QBV 的 thin adapter 判定covered时不得重复识别资产或重算相同 role,partial时只补missing_roles,unusable时无损回退原 QBV→QBS bridge;direct/fork/unmatched、ownership、构建、运行时注册、发布和验收仍完全归 QBV。用户直接使用 QBV 的量化建页同样先答;无胶囊时保留原查询能力,已有文件/解读/展示维护例外不变。已跑通的公式执行合同必须原样交给 QBV,禁止二次改写:
runMultiFormulaBatchStream成功后,原始执行以 Validation Receipt 的execution_contract为证,安全页面读取另用qbs_formula_runtime_contract_v1(可能缺省),不可混同,保留formulas的条数、顺序、完整指标名、引号、begin_date、include_description、use_minute_data、force_reusable_array、reads和 fingerprint。prepare-validated-page必须把该合同写入 computation capsule;不得把平台已确认的"A股市盈率(PE, TTM)〔估值数据〕"/"A股净资产收益率ROE"缩写成PE(TTM)/ROE后交给 QBV,也不得把多条已验证公式合并成一条新公式。显式合同与 Receipt 不一致、fingerprint 不一致或输出左值不完整时必须失败关闭,不得猜测修复。准备交接 JSON 时,Receipt 已含原始公式就不要在validated_roles[].formula手抄第二份,也不要在每个 role 重复同一 Receipt;优先在顶层validation_receipts传一次 Receipt 对象或 Receipt 文件路径字符串,也可以让prepare-validated-page按同任务全部data_id自动发现,避免引号转义失败和无效重试。
个人数据与执行能力边界:个人持仓、成本、份额和交易记录进入持久化活页前,说明当前活页凭链接公开访问;收集必要参数时一并确认是否允许公开这些信息。要求“记录持仓”不等于同意公开;已明确授权公开时不重复确认,普通公开行情查询不受此限制。不能承诺未经验证的私有访问。页面打开/刷新取数不等于每日定时执行、主动通知或自动交易;只有宿主具备相应能力且实际创建成功后才能承诺已启用。详见 能力与个人数据边界。
Fast Path / Leaf workflow 顶部硬闸门(每次进入 leaf 都生效)
修复 T-001 / T-011 / T-024 等 leaf 没把
newSession当成首条强制步骤、跳过直接调平台工具的问题。
无论路由进入 fast-snapshot / fast-window / fast-report-period / render-kline / 任何 leaf workflow:
- 当前 Skill Session 尚未建立时,调用任何平台原生工具前必须先调用
newSession;newSession同时登记本 Session 的首个 Turn。 - 同一 Session 收到新的用户消息(包括追问)时,必须先调用
beginTurn,参数中的user_query必须是本轮原话;同一 Turn 内连续调用多个工具时复用当前上下文,不重复beginTurn。- 正常 Agent 调用
newSession/beginTurn时必须同时生成可选agent_intent:用简短文字写清本轮要解决的对象、动作、约束和期望产物,推荐 20~160 字。追问中的“那它呢/和上一个比/继续”等指代必须结合已有上下文展开,但不得覆盖用户原话。 agent_intent示例:首问分析贵州茅台的盈利质量、估值水平与主要风险。;追问“那和五粮液比呢?” →延续上一轮贵州茅台分析,对比五粮液的盈利能力、估值水平与主要风险。;带约束问题“只要近三年,做成一张表” →整理目标公司近三年的核心指标并输出单表对比,不扩展到其他期间。- 禁止直接复制
user_query充当 Intent;禁止记录 Chain of Thought、内部推理步骤或未经数据分析的结论。老客户端、自动测试和无法生成 Intent 的旁路允许省略,服务端按null处理,不得阻断业务。
- 正常 Agent 调用
- 只有真正开始新的独立 Skill Session 才重新
newSession。不允许用“已读 SKILL.md / leaf workflow”跳过首个newSession,也不允许用重复newSession代替追问的beginTurn。- 新版
newSession的单次版本检查可能同时返回可选 companion(当前为quant-buddy-view):QBS 自身需要升级时必须先只升级 QBS 并 reload;QBS 已最新时才可安装、更新或补齐当前 Agent 的 companion 注册。companion 失败属于旁路错误,不得阻断当前 QBS 数据业务;只要返回reload_required=true,最终回复必须明确提示用户重新加载 Agent,禁止忽略该提示后声称活页能力已在当前会话生效。 - 建议在
newSession同时传agent_model:填入当前 Agent 的真实模型标识(例如gpt-4o/claude-sonnet-4/gemini-2.5-pro);拿不准就留空,禁止猜测。
- 新版
- 未建立 Session 直接调用平台工具仍会返回
MISSING_NEW_SESSION。若新问题未先beginTurn,或显式turn_id/user_query与当前 Turn 漂移,客户端必须取消不安全的 Turn 关联、保留本轮真实user_query并继续业务工具;仅输出追踪诊断,禁止因 Turn 记录失败停止回答用户,也禁止把调用错误挂到其他 Session。
最小充分原则(任何动作前自检)
默认走最窄路径;只在收到"明确不够用"的证据后,才扩大范围。
每次准备读文件、调工具、扩大读取范围前,回答三个问题:
- 这一步要解决的具体问题是什么? — 必须能用一句话写成"为了 X,所以做 Y",其中 X 是已经发生的需求,不能是"可能会需要 X"、"以防万一"、"先准备着"。
- 有没有更窄的选项能完成同样的 X? — 更下游的输出 / 更精简的文件 / 更少的字段 / 不调用这个工具直接构造。
- 当前选择如果失败,下一步是什么? — 如果答不上来,说明还没想清楚就在动手。
任一回答含糊 → 不做这一步。
扩大范围的唯一合法触发:上一步工具明确返回了"缺数据 / 字段不存在 / 失败",且失败原因可以追溯。不允许用"为了更全面"、"为了更准确"、"为了避免遗漏"作为理由。
这条原则覆盖:要不要多读一个文档;readData 读哪个变量;要不要为某个字段调 confirmDataMulti;公式自己写还是查现成数据集;以及所有未来出现的同类决策。
工具层面落地:调用 confirmDataMulti / readData / runMultiFormulaBatchStream 或加载额外文档前,必须在心里完成工具清单自检;不要为执行清单而搜索、加载或读取 recipes/tool-call-checklist.md。无论该文件是否已在上下文中,只在心里完成以下三条最小自检即可(这三条已是清单的浓缩版,不需要再去查原文):
- 这次调用是否直接服务于用户当前问题?
- 是否有更窄的输出或更少的字段可读?
- 如果调用失败,下一步是否明确且只改一个维度?
顶层原则管"要不要做",清单管"具体怎么做"。
Skill 包根目录
本 SKILL.md 所在目录即为 skill 根目录(SKILL_ROOT),下文所有相对路径均以此为基准。
脚本路径以本轮已读取的 Skill 实际位置为准:若文档来自 /work/<本会话>/project/.claude/skills/quant-buddy-skill/SKILL.md,可直接使用同目录 scripts/call.py 的完整绝对路径;不要猜会话 ID。只有 cwd 已是 Skill 根目录才用 python3 scripts/call.py ...,cwd 是 project 根目录时不能照抄该相对路径。不要使用 .claude/skills/... 相对前缀,也不要用 /opt/... 安装目录替代会话副本。路径拒绝后只根据已确认的工作目录修正一次,不反复尝试 /opt、.claude/skills、cd 的排列,不探测或放宽权限。
宿主已将命令工作目录(cwd)固定为本 Skill 根目录时,禁止再次执行 cd,直接使用相对路径运行;仅在人工终端或宿主没有设置 cwd 时,才先切换到本目录。
SKILL_ROOT/
├── config.json ← API Key 配置(按需读取;非每题必读)
├── SKILL.md ← 本文件(入口 + 路由)
│
├── workflows/ ← 业务流程编排(路由目标)
│ ├── fast-snapshot.md Fast Path:最新时点行情/估值(≤1000资产,标量/CSV)
│ ├── fast-window.md Fast Path:最近N日序列/窗口统计(≤2500日)
│ ├── fast-report-period.md Fast Path:最近报告期财务(≤1000资产)
│ ├── quick-lookup.md 快速查数路由器 + 共享基础规则
│ ├── quick-snapshot.md 最新时点行情/估值快照(字段齐即停)
│ ├── quick-window.md 最近N日短窗序列/窗口统计
│ ├── quick-report-period.md 最近报告期财务指标
│ ├── period-return-compare.md 固定区间累计涨跌幅对比
│ ├── stock-profile.md 单股预计算指标画像
│ ├── external-fact-verification.md 上市/退市/更名/换代码及知识冲突核验
│ ├── composition-select.md 已物化维度组合选股(selectByComposition 快路径)
│ ├── global-rules-lite.md 精简全局规则(quick-window/period-return-compare 专用)
│ ├── quant-standard.md 选股/回测/因子/图表标准流程
│ ├── live-page-routing.md QBS→QBV 非阻塞活页路由、Handoff 与 Job 合同
│ ├── visual-page-fast-path.md 单资产标准历史字段同图的取数复用快路径
│ ├── event-study.md 事件研究(给定或可识别事件后的窗口表现)
│ ├── regime-segmentation.md 阈值区间/连续阶段识别与区间统计
│ └── render-kline.md K线图渲染与交付
│
├── recipes/ ← 公式模板 & 工具用法(被 workflow 引用)
│ ├── ma-crossover-backtest.md 均线金叉策略
│ ├── value-pe-strategy.md PE估值选股
│ ├── upload-custom-data.md 上传自有数据
│ ├── render-chart.md 渲染图表
│ ├── download-data.md 下载数据
│ └── industry-aggregation.md 行业聚合排名
│
├── references/ ← 参考文档
│ ├── environment.md 环境依赖
│ ├── troubleshooting.md 故障排查
│ └── ru-billing.md RU 计费
│
├── tools/ ← API 工具完整参数文档(默认不读;workflow 标注「必读」或报错时再查)
│ │ ⚠️ 下表列出所有可用工具的**实际调用名**,调用时必须使用此名,不得变体
│ ├── fast_query.md → 工具名 `fast_query` 快速合并查询(行情/估值/财务,≤1000资产,支持CSV)
│ ├── fast_query_minute_range.md → 历史单资产跨日1分钟CSV全列(日期/自然日offset)
│ ├── fast_query_minute_range_multi.md → 多资产/全市场1分钟、每日时段、交易日滚动及JSON/CSV
│ ├── fast_query_minute.md → 工具名 `fast_query_minute` 单资产当前盘中/最近完整日分钟 OHLCVA 序列
│ ├── confirm_data_multi.md → 工具名 `confirmDataMulti` 批量确认数据项存在性与维度(写公式前必查)
│ ├── run_multi_formula.md → 工具名 `runMultiFormulaBatchStream` 执行公式批次(选股/回测/因子计算)
│ ├── read_data.md → 工具名 `readData` 读取公式计算结果(需传 data_id,非 expression_id)
│ ├── query_kline.md → 结构化日K线OHLCV与技术指标;基础2RU/含指标3RU,可授权活页
│ ├── render_kline.md → 工具名 `renderKLine` 渲染 K 线图(直接传 ticker,无需提前跑公式)
│ ├── stock_profile.md → 工具名 `stockProfile` 单股预计算指标画像(估值/财务/资金/波动/走势)
│ ├── select_by_composition.md → 工具名 `selectByComposition` 已物化维度组合选股/筛选(不走公式引擎)
│ ├── dimension_indicators.md → 工具名 `listDimensionIndicators` 按维度列出指标目录(细分+综合)
│ │ → 工具名 `getIndicatorFormulas` 按指标名取该指标的完整公式组
│ │ ⚠️ 二者非平台原生工具,走 `python scripts/call.py <工具名>`(硬规则 #2 许可路径)
│ ├── render_chart.md → 工具名 `renderChart` 渲染折线/柱状/面积图(需先有 data_id)
│ ├── get_card_formulas.md → 工具名 `getCardFormulas` 按卡片名拉取完整公式组(量化场景使用)
│ ├── scan_dimensions.md → 工具名 `scanDimensions` 九维度 IC 扫描(单股多维度预测力分析)
│ ├── search_similar_cases.md → 工具名 `searchSimilarCases` 向量检索相似案例(设计策略前的 fallback 查找)
│ ├── search_functions.md → 工具名 `searchFunctions` 检索平台函数名称与调用格式
│ ├── download_data.md → 工具名 `downloadData` 按 data_id 下载一维时序到 CSV/JSON
│ ├── upload_data.md → 工具名 `uploadData` 上传自有因子 CSV,上传后可在公式中引用
│ ├── refresh_snapshot_time.md → 工具名 `refreshSnapshotTime` 强制刷新分钟数据截止时间(盘中实时场景)
│ ├── resume_job.md → 工具名 `resumeJob` 续传 deferred 后台任务(配合 research_24h 使用)
│ └── formula_package.md → 脚本 `scripts/formula_package.py` 注册公式组为「任务包」→ 凭 package_id+signature 无 key 取数(对外只读/前端页面接入)
│
├── presets/ ← 已验证的常用数据(按需加载)
│ ├── cases_index.yaml 106 张案例卡片目录(量化标准场景必读,快速查数无需)
│ ├── assets.yaml 常用资产(99 行精选,可一次读完)
│ ├── assets_db/ 全量资产字典(按类型分文件,⚠️ 仅 grep 检索,禁止 read_file 整文件;不含指数成分股映射)
│ │ ├── stock_a.yaml A 股 5326 条(SH/SZ,含场内 ETF)
│ │ ├── stock_hk.yaml 港股 2854 条(HK 前缀;行情优先,财务以 fast_query 返回为准)
│ │ ├── stock_us.yaml 美股及境外ETF 1070 条(.N/.O/.A/.BAT;行情优先,财务以 fast_query 返回为准)
│ │ ├── index.yaml 指数 534 条
│ │ └── future.yaml 期货 237 条
│ ├── functions.yaml 常用函数(171 条)
│ ├── data_catalog.yaml 常用精选数据集(高频 index_title)
│ ├── index_info_catalog/ 系统支持数据名全量索引(2779 条,按业务分类分 YAML,grep 检索)
│ ├── dimensions.yaml 已物化指标候选的本地快照,用于 selectByComposition 的常见快速映射
│ │ ⚠️ 细分指标、快照未命中项和实时可选状态,用 `listDimensionIndicators` 在线确认;公式口径用 `getIndicatorFormulas`
│ ├── sectors.yaml 行业板块(742 条,10 个分类)
│ └── themes.yaml 题材板块
│
├── scripts/ ← 执行脚本
│ ├── call.py 工具统一入口(所有命令通过它调用)
│ ├── executor.py call.py 的底层(禁止直接调用)
│ ├── formula_package.py 公式任务包客户端(register/query/list/revoke/refresh,取数走 SSE)
│ ├── quant_api.py Python SDK(供其他脚本 import)
│ ├── auth/ 认证脚本
│ └── eval/ 评测脚本
│
└── output/ ← 输出目录(自动创建)
├── .session.<key>.json 当前 session task_id(按 QBS_SESSION_KEY 派生,多会话隔离)
├── ic_data/ IC 扫描结果
└── *.png / *.csv 图表和数据文件
全局 429 处理(所有路径均适用):
| error.code | 处理 |
|---|---|
RATE_LIMIT_EXCEEDED / CONCURRENT_LIMIT |
读 retryAfter 秒后静默重试,不向用户暴露 |
WINDOW_QUOTA_EXCEEDED |
立即停止,读 references/troubleshooting.md 配额限流段,输出提示 |
DAILY_QUOTA_EXCEEDED / DAILY_SCAN_EXCEEDED |
立即停止,输出:⚠️ 今日额度已满,次日 00:00 重置。 |
SERVICE_OVERLOADED(503) |
retryAfter 秒后静默重试 1 次,仍失败则告知"系统繁忙,请稍后重试" |
⛔ 执行顺序(路由前必读,所有场景必须遵守)
已有文件转活页先执行上方静态托管优先例外,不进入下表 QBS leaf;首次静态交付后的数据增强才按本节加载查询规则。
无论匹配到哪个 leaf workflow,执行顺序固定为:
① read_skill_file(global-rules 版本,见下表) → ② read_skill_file(leaf workflow) → ③ 执行
步骤 ① 全局规则文件选择(按目标 leaf workflow 确定):
| 目标 leaf workflow | 步骤 ① 读取的文件 |
|---|---|
fast-snapshot.md |
无(Fast Path,跳过步骤 ①,直接执行) |
fast-window.md |
无(Fast Path,跳过步骤 ①,直接执行) |
fast-report-period.md |
无(Fast Path,跳过步骤 ①,直接执行) |
quick-window.md |
workflows/global-rules-lite.md |
period-return-compare.md |
workflows/global-rules-lite.md |
| 其他所有 workflow | workflows/global-rules.md |
- 步骤 ① 是硬前置条件。确定目标 leaf 后,先按上表选择并读取对应 global-rules 版本,再读 leaf workflow,最后执行。
- Fast Path(fast-*.md)直接从步骤 ② 开始,无需步骤 ①。
场景路由
先识别用户意图,确定目标 leaf workflow;然后按上方执行顺序加载:
| 场景 | 触发词 | 目标 leaf workflow |
|---|---|---|
| 国内股指期权槽位行情 / 数据覆盖 | 沪深300/上证50/中证1000 + 期权/IV/隐含波动率/ATM/25C/25P/E1/E2;国内期货期权是否含股指 | global-rules.md → cn-index-options.md;槽位行情走数据目录与公式/读取,不用合约映射接口判断行情覆盖;完整链另行核验 |
| 单资产历史/跨日分钟 | 用户明确历史交易日或跨日区间的原始1分钟/分时CSV | 确认唯一资产 → tools/fast_query_minute_range.md → fast_query_minute_range;不传fields/format/remove_nan |
| 多资产/全市场分钟、每日时段或交易日滚动 | 多个资产、market、分钟范围、最近N个交易日或current_trade_day规则 | tools/fast_query_minute_range_multi.md → fast_query_minute_range_multi;用assets/asset/market三选一,不传tickers/fields/format |
| 单资产日内分钟 / 分时序列 | 明确要求分钟、分时、1分钟、每分钟、日内 OHLCV、逐分钟开高低收/成交量;不含历史日期、区间或多资产 | 先按资产库规则确认唯一资产 → 直接调用 fast_query_minute → 成功即停 |
| 最新时点行情 / 估值 / 基础信息(快照) | 最新价、今日收盘、最新涨跌幅、当前换手率、最新PE/PB/市值、所属行业… | Fast Path 条件满足 → 只读 fast-snapshot.md;不满足/无法查询 → global-rules.md → quick-snapshot.md |
| 最近N日序列 / 窗口统计 | 最近5日、最近20日、近N个交易日、窗口最高/最低/振幅…(仅单资产、最近N日) | Fast Path 条件满足 → 只读 fast-window.md;不满足/无法查询 → global-rules-lite.md → quick-window.md |
| 最近报告期财务 | 营收、净利润、归母净利润、ROE、总资产、总负债、资产负债率… | Fast Path 条件满足 → 只读 fast-report-period.md;不满足/无法查询 → global-rules.md → quick-report-period.md |
| 单只 A 股快速画像 | 贵州茅台、茅台、600519、SH600519;或“分析一下贵州茅台”“分析下深圳新星(SH:603978)”等简单综合分析,资产唯一且名称代码一致 | live-page-routing.md → single_a_stock_fast → QBV guides/answer-first.md,先答再 new_asset_page |
| 单股指标画像 / 个股综合分析 | 分析一下XX个股、看一下XX这只股票、个股画像、指标概览、估值财务资金走势综合看一下、基本面和估值怎么样… | global-rules.md → stock-profile.md |
| 最新上市/退市/更名/换代码或资产状态冲突 | 现在上市了吗、最新代码、是否退市;或本地资产库命中但平台返回 ASSET_NOT_FOUND |
global-rules.md → external-fact-verification.md;外部事实与 Quant Buddy 数据状态必须分开判断 |
| 单资产标准历史字段同图 | 一个资产 + 2~4 个价格/成交/估值标准历史字段 + “放在一张图里/画成图/同图比较” | 只读 visual-page-fast-path.md;先 route,再一次 fast_query,一次命令准备 capsule + Handoff + Job;禁止进入 quant-standard.md、render-kline.md 和静态渲染 |
| 申万一级行业近N日涨跌幅排名图 | 申万一级行业/行业板块 + 最近N日/最近一个月 + 涨跌幅 + 排名图/柱状图/可视化 | 只读 industry-ranking-fast.md;固定一条行业聚合公式,只读 indexinfo_id,直接准备已物化 QBV Job;禁止进入 global-rules.md、quant-standard.md、行业 recipe 和 renderChart |
| K线活页(可持续打开) | 明确出现 K线/K 线/蜡烛图/OHLC/开高低收,且没有明确只要图片 | 只读 kline-page-fast-path.md;QBS query_kline 验证 OHLCV 和所选指标后先答,再交给 QBV 的 candlestick 运行时面板;禁止调用图片型 renderKLine |
| K线图片(明确只要PNG/图片) | 用户明确不要网页、只要图片 artifact | global-rules.md → render-kline.md;此时才允许 renderKLine |
| 固定区间累计涨跌幅 | 从A到B、某年某月至某年某月、区间收益、累计涨跌幅、区间表现、多资产区间对比 | global-rules-lite.md → period-return-compare.md |
| 数据下载 / 导出本地 CSV | 下载成CSV、导出到本地、保存到本地、下载历史数据 | global-rules.md → recipes/download-data.md;单资产单字段时序优先 runMultiFormulaBatchStream → downloadData → write_skill_file,禁止 Bash 兜底 |
| 已物化指标选股 / 维度分或细分指标 TopN / 推荐股票 | 分数最高、综合分最高、维度分,或由已物化细分 score/screen 指标组成的推荐/选出/筛选 TopN | global-rules.md → composition-select.md(newSession → 本地快照匹配或在线目录确认 → selectByComposition) |
| 高频稳定因子榜单:低 PE + 高 ROE TopN | 同时出现低PE/低市盈率、高ROE/高净资产收益率、选股/筛选/排名、TopN/前N;即使没说图表或活页 | global-rules.md → quant-standard.md 的“高频默认口径”;验证 TopN 后必须实际 route,create 时用三个已物化 data_id 一次 prepare-validated-page,QBS 先答、QBV 同轮完成后补链接;明确不要网页则 none,只要表格且无其他建页意图也保持 none |
| 维度指标库查询 / 指标口径与公式 | 平台有哪些维度、XX 维度下有哪些指标、XX 指标怎么算的/口径是什么/公式是什么、想按现成指标改口径 | tools/dimension_indicators.md(用 scripts/call.py 调 listDimensionIndicators → getIndicatorFormulas,非平台原生工具;要拿改过的公式跑数再转 quant-standard.md) |
| 量化选股 / 回测 / 因子 / 图表 / 上传下载 | 选股、回测、均线、PE选股、因子、净值、上传CSV、下载数据、画图、多个指标放进同一张图…;或目录无匹配维度、需要临时构造指标/历史曲线/自定义公式 | global-rules.md → quant-standard.md;执行回测、监控、画线或任何图表 artifact 在首答前必须实际运行 live_page_routing.py route,命中 create 后非阻塞交接 QBV |
| 直接运行用户给定的公式链文件 | 「运行/跑一遍/执行这个文件里的全部公式」「公式链文件」「formula chain」「按这个 md/json 跑」 | global-rules.md → run-formula-chain.md |
| 事件研究 | 复盘、历次、涨价、降息、加息、事件窗口、随后表现、超预期、不及预期、政策后表现…(给定事件或需先识别事件日) | global-rules.md → event-study.md |
| 阈值区间统计 / 连续阶段 | 历次、每次、平均、回撤超过、从高点下跌超过、熊市区间、连续阶段、regime | global-rules.md → regime-segmentation.md |
| 每日复盘 / 持续监控 / 每天看行业股 | 每日或定期复盘、每天看、监控/盯盘、刷新看板、做个能直接打开的页面 | global-rules.md → quant-standard.md → answer-first.md;先原生查询和完整业务首答,再交 QBV;不进入先注册包的旧流程 |
| 明确开发接口 / 管理公式任务包 | 用户明确要求注册公式包、package_id、签名取数、对外只读接口或第三方接口接入 | tools/formula_package.md + recipes/formula-package.md;仅接口管理请求,普通研究看板走上一行;注册前仍须验证公式和运行时频率 |
上传、下载、画图不�
Files (quant-buddy-skills)
-
presets
-
assets_db
-
future.yaml 11.9 KB
Loading… -
index.yaml 30.9 KB
Loading… -
stock_a.yaml 245.2 KB
Loading… -
stock_hk.yaml 130.2 KB
Loading… -
stock_us.yaml 40.5 KB
Loading…
-
-
index_info_catalog
-
a_share_financials.yaml 112.7 KB
Loading… -
a_share_option_iv.yaml 384 B
Loading… -
a_share_trading_labels.yaml 6.3 KB
Loading… -
cn_future_option_market_data.yaml 3 KB
Loading… -
global_classification.yaml 297 B
Loading… -
global_financials.yaml 133.9 KB
Loading… -
macro_indicators.yaml 12.6 KB
Loading… -
macro_strategy.yaml 12.1 KB
Loading… -
manifest.yaml 1 KB
Loading… -
README.md 2.1 KB
Loading… -
us_option_market_data.yaml 4.2 KB
Loading…
-
-
cases_index.yaml 25.9 KB
Loading… -
data_catalog.yaml 15.5 KB
Loading… -
dimensions.yaml 165.3 KB
Loading… -
functions.yaml 14.9 KB
Loading… -
sectors.yaml 41.5 KB
Loading… -
themes.yaml 16.6 KB
Loading…
-
-
recipes
-
download-data.md 2.8 KB
Loading… -
event-study-formulas.md 2.2 KB
Loading… -
formula-package.md 7 KB
Loading… -
ic-factor-templates.md 3.1 KB
Loading… -
industry-aggregation.md 11.7 KB
Loading… -
ma-crossover-backtest.md 3.8 KB
Loading… -
render-chart.md 5.5 KB
Loading… -
tool-call-checklist.md 5.2 KB
Loading… -
topn-gainers.md 1.7 KB
Loading… -
upload-custom-data.md 3.1 KB
Loading… -
value-pe-strategy.md 3.4 KB
Loading…
-
-
references
-
continuous-futures.md 10.1 KB
Loading… -
environment.md 2.2 KB
Loading… -
minute-data-coverage.md 10 KB
Loading… -
ru-billing.md 1.7 KB
Loading… -
scripts-audit.md 4.8 KB
Loading… -
troubleshooting.md 11.8 KB
Loading…
-
-
scripts
-
answer_first.py 2.3 KB
Loading… -
answer_structure.py 5.4 KB
Loading… -
asset_info_request.py 2.3 KB
Loading… -
call.py 97.2 KB
Loading… -
companion_manager.py 29.1 KB
Loading… -
event_study_local.py 10.8 KB
Loading… -
executor.py 63.7 KB
Loading… -
fetch_fastquery_csv.py 14.7 KB
Loading… -
fetch_minute_range_csv.py 3.2 KB
Loading… -
formula_execution_contract.py 2.8 KB
Loading… -
formula_package.py 18.7 KB
Loading… -
live_page_routing.py 84.7 KB
Loading… -
minute_range_contract.py 6.3 KB
Loading… -
minute_range_csv.py 7 KB
Loading… -
profile_answer.py 3.8 KB
Loading… -
qbv_computation_capsule.py 38.4 KB
Loading… -
quant_api.py 51.8 KB
Loading… -
read_data_evidence.py 8.7 KB
Loading… -
resample_minute_bars.py 7 KB
Loading… -
research_contract.py 31.6 KB
Loading… -
sector_scope.py 2.1 KB
Loading… -
self_update.py 23.4 KB
Loading… -
task_context.py 15 KB
Loading… -
test_research_contract.py 17.7 KB
Loading… -
validation_receipt.py 20.7 KB
Loading…
-
-
tools
-
confirm_data_multi.md 4 KB
Loading… -
dimension_indicators.md 15.2 KB
Loading… -
download_data.md 2.7 KB
Loading… -
fast_query.md 16.7 KB
Loading… -
fast_query_minute.md 5.8 KB
Loading… -
fast_query_minute_range.md 8.1 KB
Loading… -
fast_query_minute_range_multi.md 7.4 KB
Loading… -
formula_package.md 9.8 KB
Loading… -
get_card_formulas.md 3.1 KB
Loading… -
query_kline.md 3.4 KB
Loading… -
query_option_contracts.md 4.8 KB
Loading… -
read_data.md 9.8 KB
Loading… -
refresh_snapshot_time.md 1.5 KB
Loading… -
render_chart.md 7.3 KB
Loading… -
render_kline.md 6.6 KB
Loading… -
resume_job.md 3.8 KB
Loading… -
run_multi_formula.md 26.2 KB
Loading… -
scan_dimensions.md 4.5 KB
Loading… -
search_functions.md 3.2 KB
Loading… -
search_similar_cases.md 2.2 KB
Loading… -
select_by_composition.md 7 KB
Loading… -
stock_profile.md 7.1 KB
Loading… -
upload_data.md 3.3 KB
Loading…
-
-
workflows
-
answer-first.md 14.1 KB
Loading… -
cn-index-options.md 3.5 KB
Loading… -
composition-select.md 5.6 KB
Loading… -
daily-financial-screen.md 2.9 KB
Loading… -
event-study.md 52.4 KB
Loading… -
external-fact-verification.md 4 KB
Loading… -
fast-report-period.md 7.6 KB
Loading… -
fast-snapshot.md 15.7 KB
Loading… -
fast-window.md 11.8 KB
Loading… -
global-rules-lite.md 3.1 KB
Loading… -
global-rules.md 49.3 KB
Loading… -
industry-ranking-fast.md 4.7 KB
Loading… -
kline-page-fast-path.md 3.4 KB
Loading… -
live-page-routing.md 24.4 KB
Loading… -
period-return-compare.md 8 KB
Loading… -
quant-standard.md 79.3 KB
Loading… -
quick-lookup.md 10.3 KB
Loading… -
quick-report-period.md 23.3 KB
Loading… -
quick-snapshot.md 19.5 KB
Loading… -
quick-window.md 26 KB
Loading… -
regime-segmentation.md 21.1 KB
Loading… -
render-kline.md 17 KB
Loading… -
research-contract-delivery.md 10.7 KB
Loading… -
run-formula-chain.md 6.7 KB
Loading… -
stock-profile.md 13.8 KB
Loading… -
visual-page-fast-path.md 6.3 KB
Loading…
-
-
CHANGELOG.md 128.9 KB
Loading… -
config.json 145 B
Loading… -
SKILL.md 84.5 KB
--- name: quant-buddy-skill slug: quant-buddy-skill displayName: QuantBuddy 宽宝量化技能 author: guanzhao version: 4.25.71 description: | 查询A股、港股、美股股票及指数的最新收盘价、开盘价、涨跌幅、成交额、成交量、换手率、PE、PB、市值等实时行情与估值数据;支持查询 A 股股票所属行业。 显式日期的单值快照可同时返回按实际更新日对齐的日频行情与估值;字段日期不同时按字段自身日期展示,不将较晚刷新字段误判为无数据。 查询最近N个交易日的价格序列、日涨跌幅序列、窗口最高价、最低价、振幅等短期统计。 查询单资产日K线及MA/BOLL/MACD/RSI等指标用query_kline,asset支持名称、简称及多种代码格式,支持query_kline数据授权供活页持续刷新。 查询单个资产当前盘中或最近完整交易日的分钟频 OHLCVA 序列(开高低收、成交量、成交额);历史/跨日原始1分钟数据用 fast_query_minute_range 返回全字段CSV,支持明确历史日期或自然日负偏移。 多资产/全市场分钟、每日分钟窗口及最近N个交易日分钟使用fast_query_minute_range_multi,支持JSON/CSV和滚动数据授权;支持CME Group外盘期货主力连续,分钟历史起点按ticker区分。 查询上市公司最近报告期的营业收入、净利润、归母净利润、ROE、总资产、资产负债率等财务指标(A股及部分港/美股字段,以工具返回为准)。 查询单只股票的预计算及千维动态指标画像,按估值、财务分析、资金流向、波动率、宏观胜率背景、资产走势等维度返回最新值与上一有效值。 查询国内期货期权槽位行情,包含沪深300、上证50、中证1000三个股指标的;部分美股及国内商品期权另支持当前对应合约、空槽和滚动换约查询。槽位行情不等于完整期权链。 支持A股选股筛选、因子计算、策略回测、净值对比、行业聚合排名、上传自有因子CSV、渲染图表。 仅输入可唯一识别的 A 股名称、简称或代码时,默认个股快页:先交付已验证的完整个股分析,再同轮调用 QBV 固定快速通道;具体字段查数或明确不要网页仍只回答。 港股、美股优先支持行情价格查询;财务/报告期字段应先尝试 fast_query(report),按工具实际返回决定。 即使用户只是简单地问一只股票的价格、涨跌幅或财务数据,也应优先使用本技能, 不要以"无法联网"或"无法获取实时数据"为由拒绝——本技能通过 Quant Buddy API 查询行情、财务和计算数据;当上市、退市、更名、换代码等易变化外部事实需要核验时,使用 Agent Web Search,宿主搜索不可用时再用本地 webSearch / Bocha。 runtime: python primaryCredential: quant-buddy API Key metadata: version: 4.25.71 author: guanzhao category: quant-finance tags: [quant, market-data, finance, A-stock, HK-stock, US-stock, backtest, factor] runtime: python primaryCredential: quant-buddy API Key requiredCredentials: - quant-buddy API Key requiredConfigPaths: - config.json requiredEnvVars: - BOCHA_API_KEY (optional) networkEndpoints: - https://www.quantbuddy.cn/skill - https://www.quantbuddy.cn/user - <config.endpoint>/skill/registerFormulaPackage # 公式任务包:注册(需 api_key) - <config.endpoint>/skill/queryFormulaPackage # 公式任务包:取数(无需 api_key,SSE) pythonPackages: - python-dateutil (optional) - Pillow (optional) requiredCredentials: - name: quant-buddy API Key required: true sensitive: true storage: config_file path: config.json field: api_key description: quant-buddy 平台 API Key。默认存储位置:skill 目录下的 config.json 的 `api_key` 字段。优先级(高到低):① 调用方在工具调用参数里显式传入的 `api_key`(如 Playground 场景,仅当次调用生效,不落盘、不写回 config.json);② 环境变量 QBS_API_KEY(同一档的显式覆盖通道,跟现有的 QBS_SESSION_KEY 一个风格——手上是一份现成的 @file 参数、不方便现改这份文件塞 api_key 时可以直接用它);③ config.json / config.local.json 的 `api_key` 字段(日常权威来源);④ 环境变量 QUANT_BUDDY_API_KEY(仅①②③都为空时才兜底生效,不作为常规覆盖手段,跟 QBS_API_KEY 语义完全不同,不要混用)。使用时作为 HTTP `Authorization` 头仅发送给 `networkEndpoints` 中声明的 quantbuddy 域名用于鉴权,不会被写入日志或转发给第三方主机。 how_to_get: "https://www.quantbuddy.cn/login" requiredConfigPaths: - path: config.json required: true description: Skill 目录下的 API Key 配置文件,仅包含 quant-buddy api_key 和两个公开端点配置,由 skill 本地脚本读取;api_key 仅作为 HTTP `Authorization` 头发给 `networkEndpoints` 中声明的 quantbuddy 域名,不发送给其他主机。 requiredEnvVars: - name: BOCHA_API_KEY required: false sensitive: true description: 可选。scripts/event_study_local.py 的通用外部事实搜索读取,用于事件研究以及上市、退市、更名、换代码等时效性事实核验;Agent 宿主搜索可用时优先使用宿主能力。未配置时本地 Bocha 兜底自动禁用,其它功能不受影响。 how_to_get: "https://open.bochaai.com" networkAccess: true networkEndpoints: - https://www.quantbuddy.cn/skill - https://www.quantbuddy.cn/user runtimeRequirements: python: "3.8+" packages: - name: python-dateutil version: ">=2.8" required: false description: Used by scripts/event_study_local.py for optional Bocha-backed external fact verification, including event study and asset status changes. Not needed if BOCHA_API_KEY is not configured. - name: Pillow version: ">=9.0" required: false description: Used by scripts/call.py saveChart command to convert chart images to JPEG. Falls back gracefully (writes raw bytes) if not installed; no credential exposure risk. --- ## 筛选正确性与交付恢复 明确要求选股时附公司信息,且现有路由需要活页时,在 `prepare-validated-page` / Handoff 顶层增加可选 `asset_info_request`,引用已验证选股 `selection_role`;默认主营业务+近期事件、300字、text,自定义主题写入prompt并保留日期与来源要求。首答只交付量化名单、口径和量化分析,不逐股搜索或撰写主营与事件;公司资料由活页官方模块异步查询。按 [交接说明](workflows/answer-first.md#选股页附公司信息) 同轮交给QBV;模块成功接入并交付活页时,补充异步加载及卡片积分入口提示,聊天收费说明统一沿用QBV回执的 `llm_billing/billing_notice`,不重复编写规则。需求不进入已验证结论、不参与筛选和排名;普通选股不启用,“不要网页”优先。 涉及选股、TopN、确认后的过滤条件时,先阅读 [研究合同与恢复](workflows/research-contract-delivery.md)。研究与页面状态分开记录;缺数据或结果为空仍交付可读研究页,不得把未验证写成零命中。 # 观照量化投研 **WebAgent 宿主交付约定优先**:宿主要求金融问题统一“完整问答+活页”时,所有金融问题先实际 route,再由 QBS 查询验证并发送非终止首答,同轮继续 QBV。包括具体字段、概念解释和“601137 最近如何?”,不依赖建页关键词。Worker 的 `QBS_DEFAULT_PAGE_REQUESTED=1` 由脚本自动继承;本文件及 leaf workflow 的“只回答/结束/不建页”默认仅适用于独立 QBS。明确不要网页/只回复文字、已有页面只读解读、文件托管与纯维护按各自规则处理。详见 [宿主默认建页](workflows/answer-first.md#webagent-宿主默认建页优先于独立-qbs-路由)。 **建页意图持续保留**:普通“个股分析”与“综合分析”使用同一分类器;附加日期窗口、指标或展示要求不套固定快页。已有显式 QBV/活页意图时传 `page_requested:true`,查数结束不清除它;非终止首答后执行交接下一步,直至页面与回复验收通过或实际恢复后报告具体阻断。取数 `success` 不代表页面已交付,详见 [先答后建页](workflows/answer-first.md)。 > **首屏优先**:先读本文件前部的「平台工具参数速查」「硬规则」和「场景路由」。简单行情、窗口序列、最近报告期、固定区间收益、K 线图等高频任务命中 Fast Path 时,无需继续整本通读。 本地交付必须复用工具返回的真实路径;不得加 `sandbox:` 或猜测 Skill 安装目录。排名表逐列核对数据 ID、单位和日期;比值列不能抄到 PE 列。参见 [全局执行规则](workflows/global-rules.md)。 个股画像与综合分析的内容合同见 `workflows/stock-profile.md`:默认交付五个数据章节与综合观察,用户明确要求简短或限定字段时才缩减。读取 Skill 后必须继续读取匹配工作流、实际查询并回复;“将读取文档/准备查询”不是业务交付,不可作为最终答案。明确不要网页只取消建页,不取消上述查询和完整分析。 ## 常见请求的默认口径 - 中文股票全市场排名、未指定市场的涨幅前N热力图,默认 A 股并在首答声明;行业分组默认申万一级,颜色保留股票原涨跌幅、面积或数量明确含义。用户指定其他市场时遵从,不因为这些可披露默认值就停止澄清。 - 已给出“白酒股”等行业范围的刷新看板,先核验平台对应板块及成分,默认 PE TTM、PB;按 `quant-standard.md` 查询并给出实际行情、成交量、估值首答,再按 `answer-first.md` 继续 QBV。刷新意图不允许先注册公式包,也不能只回复看板设计。不要先要求用户列股票名单。精确板块不存在或确有同名歧义时才澄清,不用几只龙头冒充全部行业。 - 常见单均线回测可采用 quant-standard 的披露默认值继续执行;用户明确不要网页时不建页。 ## 平台工具参数速查(高频踩坑,先看这一段) **取价函数盘中刷新**:`收盘价/开盘价/最高价/最低价(资产,最后一日分钟刷新)` 保留日频序列,最近交易日使用盘中行情。`use_minute_data:true` 执行时服务端会为四类普通取价调用补上该参数,已带参数的调用不重复追加。做活页公式包时,从验证开始就显式保留参数,并使用普通执行合同(`use_minute_data:false` 或省略);A股结果及其派生结果应按 `cn.chart:intra` 刷新。不要把已验证的 true 合同直接删字段重登记。详见 [盘中刷新模式](tools/run_multi_formula.md#盘中刷新模式)。 **活页资源归属**:交接 QBV 前,数据授权和公式包须使用目标页面所有者的 API Key 注册。签名可公开取数不代表可跨用户复用;复制页面须为目标用户创建独立资源。遇到提交归属拒绝,按原有 `message` 更换注册身份、重建原口径资源并完整替换 ID 与 signature 后重提;不得只改页面用户名、只替换 ID 或删除分析内容。管理员也须先预览影响并取得明确确认后才转接,详见 [公式包与页面归属](tools/formula_package.md#页面归属与提交拒绝恢复)。沙箱实例本身暂不处理归属。 > 下表是 LLM 最容易写错的三个 schema。任何调用前先核对,不要凭"看起来合理"猜参数名。 | 工具 | ✅ 正确参数 | ❌ 模型常见错误(已被 call.py 自动归一化或拦截,但仍应避免) | |------|------------|------------------------------------------------------------| | `confirmDataMulti` | `{"data_desc": "市盈率 TTM,股息率"}` — **逗号分隔字符串** | `{"queries": [...]}` / `{"query": "..."}` / `{"names": [...]}` | | `runMultiFormulaBatchStream` 公式中引用 session 中间变量 | 必须用**双引号**包裹:`排序値 = "A股股息率〔估値数据〕" * "条件合并"` | 裸变量名相乘:`"A股股息率…" * 条件合并` ← 平台直接报错 | | `readData` | `{"ids": ["69fe…<24位hex>"], "mode": "last_column_full"}` — **必须是 `runMultiFormulaBatchStream` 返回的 `data_id` 字段(hex)** | 传中文变量名 `{"ids": ["Top10股息"]}` / 用错参数名 `{"index_title": "..."}` / `{"variable_names": [...]}` / **传 `expression_id` 而非 `data_id`**(两者相邻易混,传错会返回 `"error": "IndexInfo {id}"`)| **口径转换(confirmDataMulti 查询词)**:用户写 `PE(TTM)` / `归母净利润` 等英文或缩写时,查询词应使用**中文规范名**(如 `市盈率 TTM` / `归母净利润`),而不是把用户原文照抄进 `data_desc`。详细规则见 `workflows/global-rules.md#指标口径精确匹配`。 **回测口径硬规则**:`回测()` 的交易时机同时决定成交时点与收益率记账口径。`当天开盘买入` / `第二天开盘买入` 按**开盘到开盘**收益记账(`今日开盘/昨日开盘-1`,含隔夜跳空,跨长假后可超过常规涨跌停);`当天收盘买入` 按预物化日收益率记账。看到极端单日收益先跑同交易时机基准,不用涨跌停直觉直接判错。`信号按列归一`适合每日总权重为1的等权/因子组合;`信号不归一`表示输入原值就是目标仓位/目标暴露,0-1 择时与0.3等目标仓位不得强制归一。 --- ## 国内期货期权行情与合约映射 **国内期货期权数据不只包含商品**:现有槽位行情还包含沪深300(数据列 `沪深300主连 / IF.CFE`,期权代码 IO)、上证50(`上证50主连 / IH.CFE`,HO)、中证1000(`中证1000主连 / IM.CFE`,MO)。查询价格、IV、持仓量或成交额时先走 [股指期权槽位行情](workflows/cn-index-options.md),使用目录中的 `国内期货期权-*` 数据,不因合约映射接口限制直接答“没有股指期权数据”。32个目录字段不保证每个标的、每槽、每日都有有效值;完整期权链和具体合约映射须分别确认。 ### 美股及国内商品期权对应合约查询 用户问槽位对应合约、换约/换月,或要解释期权IV、价格、持仓量变化时,读取 [tools/query_option_contracts.md](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请求不附事件。外盘日频换月信息当前缺失,不能用分钟事件解释日频换月、复权或合约;详见[换月频率边界](references/continuous-futures.md#外盘换月返回入口2026-10-28)。 主连/次主连的跨日、跨频、指标或回测任务,先读 [连续期货换月与数据口径](references/continuous-futures.md)。新版事件保留 `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查询/接入失败只影响增强,保留线上成功版本;未查到不等于平台不支持。纯文件分析、明确不发布不触发;真实公开授权、不可读文件、转换/首次托管问题须如实说明。不得将快照标为实时或已核验。 ## 硬规则(违反必失败) 0. **工具名与 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。 2. **原生工具优先,禁止脚本包装**: - 平台已有原生工具时,必须直接调用原生工具:`fast_query`、`query_kline`、`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 格式。 3. **工具失败熔断:同类错误不得重复** - 本地 `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`,禁止重提原批次。 4. **任何 workflow 失败退出时必须输出受控失败答复**:禁止以空白或纯过程日志结束对话。失败答复必须包含: - ①用户的原始问题(一句话复述) - ②失败卡在哪一步(工具名 + 错误摘要) - ③给用户的一句话说明("当前无法获取…,原因:…") - 可选④:用户可采取的下一步(如"稍后重试"或"换用完整链路") 5. **先读 workflow 再操作**:按下方「场景路由」表加载对应 workflow,不要自行猜测参数格式。 6. **配置/认证错误立即停止,不得在普通查数流程中转为认证收集**: - **工具返回 API Key 缺失错误**(含 `api_key 为空` 消息 / `code: 1`):立即停止查数,输出**新用户引导消息**(格式见「前置条件」章节模板),禁止继续执行查数;等待用户粘贴 Key 后再执行配置向导。 - **其他工具报错**(网络、服务端错误等):直接报告"内部工具异常",不做认证相关引导。 7. **最终答案首句必须是数据结论**:回答用户时,第一句话必须直接给出数据结论(如资产名+数值、表格、或"符合条件的共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` 时才进入自愈/排错流程。 8. **用户条件冻结,不得改写**:执行前必须逐字核对用户原始条件,以下改写行为均属违规(一旦发现必须回退并重新确认): - **百分比↔小数互转**(如"股息率>3%"禁止改写为 `>0.03`) - **相对时间改为年份区间**(如"过去10年"禁止改写为"2015-2025") - **资产宇宙替换**(如"普通股票"禁止改写为"万得全A成分股"或"非ST股") - **事件口径扩大**(如"年报/半年报"禁止扩大为全部业绩披露类型) - **卡片附加条件继承**:命中知识卡片后,若卡片含用户未明确提出的"首次/非ST/封板/流动性门槛"等附加条件,必须先删除再执行,禁止默默继承进最终答案 9. **任务含糊时先反问,禁止猜测开干**:若用户的指令有 **2 种以上合理解读**(如"批量确认X"不清楚是确认指数本身还是全部成分股、"分析一下Y"不清楚要哪个维度),**第一步必须向用户提问澄清,不得凭推测选择一种解读自行执行**。反问应简洁列出各种可能(例:"您的意思是 ① … 还是 ② …?"),等用户确认后再继续。**唯一例外**:用户语义明确无歧义(如"给我贵州茅台今日收盘价"),无需反问。 **⚠️ 模糊词处理规则(先判断是否真歧义,再决定反问还是默认口径直行)**: 下列词在量化语义中存在多种定义,必须正确处理: - **技术分析类**:支撑位 / 阻力位 / 压力位 / 颈线位 / 关键位 / 关键点位 / 突破位 - **走势判断类**:趋势 / 趋势预测 / 后市判断 / 还能不能涨 / 会不会跌 / 短期看法 / 中线看法 - **盘面定性类**:异动 / 主力 / 主力流向 / 庄家动向 / 强势 / 弱势 / 抗跌 / 抗跌性 - **健康度类**:基本面好不好 / 估值贵不贵 / 财务健康 / 业绩怎么样 / 基本面 **判定流程(按顺序匹配,命中即停)**: 1. **综合分析请求 → 用默认口径直行,禁止反问阻塞**。 判定:用户在一句话里列出 ≥2 个分析维度(如"基本面 + 技术指标 + 趋势"、"估值 + 财务 + 走势"),或明确说"全面分析 / 综合看一下 / 给一份报告"。 做法:直接走 `stockProfile`(综合画像)+ 常规技术指标 + 默认趋势口径,**报告首句**告知用户使用的口径(例:"本次按以下默认口径输出:基本面=综合画像(估值+财务+资金流+波动率),技术=MACD/KDJ/RSI/布林带,趋势=MA20/MA60 排列方向。如需调整口径请告诉我。")。 2. **孤立的单点定义性请求 → 必须反问**。 判定:触发词单独出现,且其定义直接决定结论数值(如"贵州茅台支撑位是多少"、"宁德时代趋势怎么样",无任何其他维度上下文)。 做法:反问 ① 口径定义(如"支撑位"=近N日最低/布林下轨/均线密集区);② 时间窗口;③ 输出格式。 3. **触发词只是修饰语 → 直行**。 判定:用户主体诉求清晰,触发词只是顺带描述(如"找最近基本面改善的股票"主体是筛选,"基本面改善"已隐含"营收/净利同比上升"等可执行口径)。 做法:用最常见的可执行口径执行,并在结果中标注口径。 **实测教训(T-036)**:用户问"贵州茅台支撑位",模型擅自用"60日最低价附近"作为定义直接执行——这是孤立单点请求,应走流程 2 反问。 **反例(不要再犯)**:用户问"分析东方财富的基本面、技术指标、趋势预测",模型反问 4 个问题阻塞——这是综合分析请求,应走流程 1 默认口径直行。 10. **工具返回 `SKILL_VERSION_MISMATCH` 时必须自愈,不得继续执行原任务**:当任何工具调用的输出中出现 `"error": "SKILL_VERSION_MISMATCH"` 时,说明当前对话上下文中的工具签名/参数格式已过时。此时必须执行以下自愈流程(每步不得省略): 1. **立即停止**当前任务,不得再调用任何平台工具; 2. 调用 `newSession`(新建 session,获取新 task_id); 3. **强制重读** `SKILL.md`(本文件)+ 当前场景对应的 workflow 文档 + 涉及的 tools/*.md; 4. 以**新读取**的工具签名和参数格式重新执行用户原始任务; 5. **禁止**询问用户"是否继续"或解释版本升级过程——直接静默完成自愈并返回结果。 11. **CHANGELOG / skill-changelog 仅作为审计,不作为规则源**:`CHANGELOG.md`、`skill-changelog/**` 是按时间叠加的变更记录,包含已被后续版本反转或废弃的旧口径。任何「执行顺序、字段名、协议块语义、工具签名、参数格式」相关的判断,**必须**以 `SKILL.md` + `workflows/**` + `tools/**` + `references/troubleshooting.md` 为唯一权威;CHANGELOG 描述与上述文件冲突时,以上述文件为准。CHANGELOG 仅可用于:① 排查问题时回看「哪一版动过什么」;② 升级成功后做 5 条以内的版本上下文摘要。**禁止**:把 CHANGELOG 某条历史叙述当作当前执行规则、依据 CHANGELOG 推断现行参数格式、或在 CHANGELOG 与 SKILL.md 冲突时偏向 CHANGELOG。 12. **判断工具成败看返回 body 的 `code`/`success`,不看 HTTP 状态码**:HTTP 200 不代表业务成功——body 里出现 `"code": -1` / `"success": false` 即为**业务错误**,必须按失败处理(读 `error`/`message` 再决定重试/改参/走排查表),禁止「HTTP 通了就当成功」继续往下走。另:`call.py` 返回 `"error": "INVALID_TOOL_NAME"` 表示工具名写错或缺失(工具名必须排在命令最前、且为已注册工具名),属可立即修正的本地错误。详见 `references/troubleshooting.md` 顶部「成败判定通则」。 13. **先答后建页**:每日/定期复盘、行情监控、画线/画图、执行回测、看 K 线等操作请求,以及已登记的稳定榜单(低 PE + 高 ROE + 选股/排名 + TopN)必须实际执行 `scripts/live_page_routing.py route`,不能把普通 TopN 全部升级为活页。上述操作本身构成活页意图,不要求用户另说“网页”;纯概念解释不建页。上下文中的真实建页意图可传 `--page-requested`,明确不要网页/暂不发布仍优先;不要画图只约束表现形式,不能否决表格型活页。按 [先答后建页](workflows/answer-first.md) 执行: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日行业排名分别沿专用快路径,快路径也必须先答后准备页面。 14. **QBS→QBV 只复用本轮已经算完的部分,不把 QBV 改成 QBS 专用渲染器**:`create|existing_page` 在 Handoff 前优先运行 `scripts/qbv_computation_capsule.py build @capsule-input.json`,生成 `qbs_computation_capsule_v1`。胶囊必须同时包含用户核心问题/主图意图、资产规范化结果、可复现查询或公式合同及 fingerprint、结果快照或 artifact SHA256、字段映射、结论与验证收据;禁止只交 PNG 或一句总结。 同一业务 role 对应多个已物化结果时可传 `data_ids`;构建器按原顺序展开为 `role__01`、`role__02`…,保留原始 ID 字符串并同步 `required_roles`,禁止 Agent 手工改写或复制 ID。QBV 的 thin adapter 判定 `covered` 时不得重复识别资产或重算相同 role,`partial` 时只补 `missing_roles`,`unusable` 时无损回退原 QBV→QBS bridge;direct/fork/unmatched、ownership、构建、运行时注册、发布和验收仍完全归 QBV。用户直接使用 QBV 的量化建页同样先答;无胶囊时保留原查询能力,已有文件/解读/展示维护例外不变。 15. **已跑通的公式执行合同必须原样交给 QBV,禁止二次改写**:`runMultiFormulaBatchStream` 成功后,原始执行以 Validation Receipt 的 `execution_contract` 为证,安全页面读取另用 `qbs_formula_runtime_contract_v1`(可能缺省),不可混同,保留 `formulas` 的条数、顺序、完整指标名、引号、`begin_date`、`include_description`、`use_minute_data`、`force_reusable_array`、`reads` 和 fingerprint。`prepare-validated-page` 必须把该合同写入 computation capsule;不得把平台已确认的 `"A股市盈率(PE, TTM)〔估值数据〕"` / `"A股净资产收益率ROE"` 缩写成 `PE(TTM)` / `ROE` 后交给 QBV,也不得把多条已验证公式合并成一条新公式。显式合同与 Receipt 不一致、fingerprint 不一致或输出左值不完整时必须失败关闭,不得猜测修复。准备交接 JSON 时,Receipt 已含原始公式就不要在 `validated_roles[].formula` 手抄第二份,也不要在每个 role 重复同一 Receipt;优先在顶层 `validation_receipts` 传一次 Receipt 对象或 Receipt 文件路径字符串,也可以让 `prepare-validated-page` 按同任务全部 `data_id` 自动发现,避免引号转义失败和无效重试。 **个人数据与执行能力边界**:个人持仓、成本、份额和交易记录进入持久化活页前,说明当前活页凭链接公开访问;收集必要参数时一并确认是否允许公开这些信息。要求“记录持仓”不等于同意公开;已明确授权公开时不重复确认,普通公开行情查询不受此限制。不能承诺未经验证的私有访问。页面打开/刷新取数不等于每日定时执行、主动通知或自动交易;只有宿主具备相应能力且实际创建成功后才能承诺已启用。详见 [能力与个人数据边界](workflows/answer-first.md#能力与个人数据边界)。 ## Fast Path / Leaf workflow 顶部硬闸门(每次进入 leaf 都生效) > 修复 T-001 / T-011 / T-024 等 leaf 没把 `newSession` 当成首条强制步骤、跳过直接调平台工具的问题。 无论路由进入 `fast-snapshot` / `fast-window` / `fast-report-period` / `render-kline` / 任何 leaf workflow: 1. 当前 Skill Session 尚未建立时,调用任何平台原生工具前必须先调用 `newSession`;`newSession` 同时登记本 Session 的首个 Turn。 2. 同一 Session 收到新的用户消息(包括追问)时,必须先调用 `beginTurn`,参数中的 `user_query` 必须是本轮原话;同一 Turn 内连续调用多个工具时复用当前上下文,不重复 `beginTurn`。 - 正常 Agent 调用 `newSession` / `beginTurn` 时必须同时生成可选 `agent_intent`:用简短文字写清本轮要解决的对象、动作、约束和期望产物,推荐 20~160 字。追问中的“那它呢/和上一个比/继续”等指代必须结合已有上下文展开,但不得覆盖用户原话。 - `agent_intent` 示例:首问 `分析贵州茅台的盈利质量、估值水平与主要风险。`;追问“那和五粮液比呢?” → `延续上一轮贵州茅台分析,对比五粮液的盈利能力、估值水平与主要风险。`;带约束问题“只要近三年,做成一张表” → `整理目标公司近三年的核心指标并输出单表对比,不扩展到其他期间。` - 禁止直接复制 `user_query` 充当 Intent;禁止记录 Chain of Thought、内部推理步骤或未经数据分析的结论。老客户端、自动测试和无法生成 Intent 的旁路允许省略,服务端按 `null` 处理,不得阻断业务。 3. 只有真正开始新的独立 Skill Session 才重新 `newSession`。不允许用“已读 SKILL.md / leaf workflow”跳过首个 `newSession`,也不允许用重复 `newSession` 代替追问的 `beginTurn`。 - 新版 `newSession` 的单次版本检查可能同时返回可选 companion(当前为 `quant-buddy-view`):QBS 自身需要升级时必须先只升级 QBS 并 reload;QBS 已最新时才可安装、更新或补齐当前 Agent 的 companion 注册。companion 失败属于旁路错误,不得阻断当前 QBS 数据业务;只要返回 `reload_required=true`,最终回复必须明确提示用户重新加载 Agent,禁止忽略该提示后声称活页能力已在当前会话生效。 - **建议在 `newSession` 同时传 `agent_model`**:填入当前 Agent 的真实模型标识(例如 `gpt-4o` / `claude-sonnet-4` / `gemini-2.5-pro`);拿不准就留空,禁止猜测。 4. 未建立 Session 直接调用平台工具仍会返回 `MISSING_NEW_SESSION`。若新问题未先 `beginTurn`,或显式 `turn_id/user_query` 与当前 Turn 漂移,客户端必须取消不安全的 Turn 关联、保留本轮真实 `user_query` 并继续业务工具;仅输出追踪诊断,禁止因 Turn 记录失败停止回答用户,也禁止把调用错误挂到其他 Session。 ## 最小充分原则(任何动作前自检) > 默认走最窄路径;只在收到"明确不够用"的证据后,才扩大范围。 **每次准备读文件、调工具、扩大读取范围前,回答三个问题**: 1. **这一步要解决的具体问题是什么?** — 必须能用一句话写成"为了 X,所以做 Y",其中 X 是**已经发生**的需求,不能是"可能会需要 X"、"以防万一"、"先准备着"。 2. **有没有更窄的选项能完成同样的 X?** — 更下游的输出 / 更精简的文件 / 更少的字段 / 不调用这个工具直接构造。 3. **当前选择如果失败,下一步是什么?** — 如果答不上来,说明还没想清楚就在动手。 任一回答含糊 → 不做这一步。 **扩大范围的唯一合法触发**:上一步工具明确返回了"缺数据 / 字段不存在 / 失败",且失败原因可以追溯。不允许用"为了更全面"、"为了更准确"、"为了避免遗漏"作为理由。 > 这条原则覆盖:要不要多读一个文档;readData 读哪个变量;要不要为某个字段调 confirmDataMulti;公式自己写还是查现成数据集;以及所有未来出现的同类决策。 **工具层面落地**:调用 `confirmDataMulti` / `readData` / `runMultiFormulaBatchStream` 或加载额外文档前,必须在心里完成工具清单自检;**不要为执行清单而搜索、加载或读取 `recipes/tool-call-checklist.md`**。无论该文件是否已在上下文中,只在心里完成以下三条最小自检即可(这三条已是清单的浓缩版,不需要再去查原文): 1. 这次调用是否直接服务于用户当前问题? 2. 是否有更窄的输出或更少的字段可读? 3. 如果调用失败,下一步是否明确且只改一个维度? 顶层原则管"要不要做",清单管"具体怎么做"。 ## Skill 包根目录 **本 SKILL.md 所在目录即为 skill 根目录(`SKILL_ROOT`)**,下文所有相对路径均以此为基准。 脚本路径以本轮已读取的 Skill 实际位置为准:若文档来自 `/work/<本会话>/project/.claude/skills/quant-buddy-skill/SKILL.md`,可直接使用同目录 `scripts/call.py` 的完整绝对路径;不要猜会话 ID。只有 cwd 已是 Skill 根目录才用 `python3 scripts/call.py ...`,cwd 是 project 根目录时不能照抄该相对路径。不要使用 `.claude/skills/...` 相对前缀,也不要用 `/opt/...` 安装目录替代会话副本。路径拒绝后只根据已确认的工作目录修正一次,不反复尝试 `/opt`、`.claude/skills`、`cd` 的排列,不探测或放宽权限。 宿主已将命令工作目录(cwd)固定为本 Skill 根目录时,**禁止再次执行 `cd`**,直接使用相对路径运行;仅在人工终端或宿主没有设置 cwd 时,才先切换到本目录。 ``` SKILL_ROOT/ ├── config.json ← API Key 配置(按需读取;非每题必读) ├── SKILL.md ← 本文件(入口 + 路由) │ ├── workflows/ ← 业务流程编排(路由目标) │ ├── fast-snapshot.md Fast Path:最新时点行情/估值(≤1000资产,标量/CSV) │ ├── fast-window.md Fast Path:最近N日序列/窗口统计(≤2500日) │ ├── fast-report-period.md Fast Path:最近报告期财务(≤1000资产) │ ├── quick-lookup.md 快速查数路由器 + 共享基础规则 │ ├── quick-snapshot.md 最新时点行情/估值快照(字段齐即停) │ ├── quick-window.md 最近N日短窗序列/窗口统计 │ ├── quick-report-period.md 最近报告期财务指标 │ ├── period-return-compare.md 固定区间累计涨跌幅对比 │ ├── stock-profile.md 单股预计算指标画像 │ ├── external-fact-verification.md 上市/退市/更名/换代码及知识冲突核验 │ ├── composition-select.md 已物化维度组合选股(selectByComposition 快路径) │ ├── global-rules-lite.md 精简全局规则(quick-window/period-return-compare 专用) │ ├── quant-standard.md 选股/回测/因子/图表标准流程 │ ├── live-page-routing.md QBS→QBV 非阻塞活页路由、Handoff 与 Job 合同 │ ├── visual-page-fast-path.md 单资产标准历史字段同图的取数复用快路径 │ ├── event-study.md 事件研究(给定或可识别事件后的窗口表现) │ ├── regime-segmentation.md 阈值区间/连续阶段识别与区间统计 │ └── render-kline.md K线图渲染与交付 │ ├── recipes/ ← 公式模板 & 工具用法(被 workflow 引用) │ ├── ma-crossover-backtest.md 均线金叉策略 │ ├── value-pe-strategy.md PE估值选股 │ ├── upload-custom-data.md 上传自有数据 │ ├── render-chart.md 渲染图表 │ ├── download-data.md 下载数据 │ └── industry-aggregation.md 行业聚合排名 │ ├── references/ ← 参考文档 │ ├── environment.md 环境依赖 │ ├── troubleshooting.md 故障排查 │ └── ru-billing.md RU 计费 │ ├── tools/ ← API 工具完整参数文档(默认不读;workflow 标注「必读」或报错时再查) │ │ ⚠️ 下表列出所有可用工具的**实际调用名**,调用时必须使用此名,不得变体 │ ├── fast_query.md → 工具名 `fast_query` 快速合并查询(行情/估值/财务,≤1000资产,支持CSV) │ ├── fast_query_minute_range.md → 历史单资产跨日1分钟CSV全列(日期/自然日offset) │ ├── fast_query_minute_range_multi.md → 多资产/全市场1分钟、每日时段、交易日滚动及JSON/CSV │ ├── fast_query_minute.md → 工具名 `fast_query_minute` 单资产当前盘中/最近完整日分钟 OHLCVA 序列 │ ├── confirm_data_multi.md → 工具名 `confirmDataMulti` 批量确认数据项存在性与维度(写公式前必查) │ ├── run_multi_formula.md → 工具名 `runMultiFormulaBatchStream` 执行公式批次(选股/回测/因子计算) │ ├── read_data.md → 工具名 `readData` 读取公式计算结果(需传 data_id,非 expression_id) │ ├── query_kline.md → 结构化日K线OHLCV与技术指标;基础2RU/含指标3RU,可授权活页 │ ├── render_kline.md → 工具名 `renderKLine` 渲染 K 线图(直接传 ticker,无需提前跑公式) │ ├── stock_profile.md → 工具名 `stockProfile` 单股预计算指标画像(估值/财务/资金/波动/走势) │ ├── select_by_composition.md → 工具名 `selectByComposition` 已物化维度组合选股/筛选(不走公式引擎) │ ├── dimension_indicators.md → 工具名 `listDimensionIndicators` 按维度列出指标目录(细分+综合) │ │ → 工具名 `getIndicatorFormulas` 按指标名取该指标的完整公式组 │ │ ⚠️ 二者非平台原生工具,走 `python scripts/call.py <工具名>`(硬规则 #2 许可路径) │ ├── render_chart.md → 工具名 `renderChart` 渲染折线/柱状/面积图(需先有 data_id) │ ├── get_card_formulas.md → 工具名 `getCardFormulas` 按卡片名拉取完整公式组(量化场景使用) │ ├── scan_dimensions.md → 工具名 `scanDimensions` 九维度 IC 扫描(单股多维度预测力分析) │ ├── search_similar_cases.md → 工具名 `searchSimilarCases` 向量检索相似案例(设计策略前的 fallback 查找) │ ├── search_functions.md → 工具名 `searchFunctions` 检索平台函数名称与调用格式 │ ├── download_data.md → 工具名 `downloadData` 按 data_id 下载一维时序到 CSV/JSON │ ├── upload_data.md → 工具名 `uploadData` 上传自有因子 CSV,上传后可在公式中引用 │ ├── refresh_snapshot_time.md → 工具名 `refreshSnapshotTime` 强制刷新分钟数据截止时间(盘中实时场景) │ ├── resume_job.md → 工具名 `resumeJob` 续传 deferred 后台任务(配合 research_24h 使用) │ └── formula_package.md → 脚本 `scripts/formula_package.py` 注册公式组为「任务包」→ 凭 package_id+signature 无 key 取数(对外只读/前端页面接入) │ ├── presets/ ← 已验证的常用数据(按需加载) │ ├── cases_index.yaml 106 张案例卡片目录(量化标准场景必读,快速查数无需) │ ├── assets.yaml 常用资产(99 行精选,可一次读完) │ ├── assets_db/ 全量资产字典(按类型分文件,⚠️ 仅 grep 检索,禁止 read_file 整文件;不含指数成分股映射) │ │ ├── stock_a.yaml A 股 5326 条(SH/SZ,含场内 ETF) │ │ ├── stock_hk.yaml 港股 2854 条(HK 前缀;行情优先,财务以 fast_query 返回为准) │ │ ├── stock_us.yaml 美股及境外ETF 1070 条(.N/.O/.A/.BAT;行情优先,财务以 fast_query 返回为准) │ │ ├── index.yaml 指数 534 条 │ │ └── future.yaml 期货 237 条 │ ├── functions.yaml 常用函数(171 条) │ ├── data_catalog.yaml 常用精选数据集(高频 index_title) │ ├── index_info_catalog/ 系统支持数据名全量索引(2779 条,按业务分类分 YAML,grep 检索) │ ├── dimensions.yaml 已物化指标候选的本地快照,用于 selectByComposition 的常见快速映射 │ │ ⚠️ 细分指标、快照未命中项和实时可选状态,用 `listDimensionIndicators` 在线确认;公式口径用 `getIndicatorFormulas` │ ├── sectors.yaml 行业板块(742 条,10 个分类) │ └── themes.yaml 题材板块 │ ├── scripts/ ← 执行脚本 │ ├── call.py 工具统一入口(所有命令通过它调用) │ ├── executor.py call.py 的底层(禁止直接调用) │ ├── formula_package.py 公式任务包客户端(register/query/list/revoke/refresh,取数走 SSE) │ ├── quant_api.py Python SDK(供其他脚本 import) │ ├── auth/ 认证脚本 │ └── eval/ 评测脚本 │ └── output/ ← 输出目录(自动创建) ├── .session.<key>.json 当前 session task_id(按 QBS_SESSION_KEY 派生,多会话隔离) ├── ic_data/ IC 扫描结果 └── *.png / *.csv 图表和数据文件 ``` --- **全局 429 处理(所有路径均适用)**: | error.code | 处理 | |---|---| | `RATE_LIMIT_EXCEEDED` / `CONCURRENT_LIMIT` | 读 `retryAfter` 秒后**静默重试**,不向用户暴露 | | `WINDOW_QUOTA_EXCEEDED` | **立即停止**,读 `references/troubleshooting.md` 配额限流段,输出提示 | | `DAILY_QUOTA_EXCEEDED` / `DAILY_SCAN_EXCEEDED` | **立即停止**,输出:`⚠️ 今日额度已满,次日 00:00 重置。` | | `SERVICE_OVERLOADED`(503) | `retryAfter` 秒后静默重试 1 次,仍失败则告知"系统繁忙,请稍后重试" | --- ## ⛔ 执行顺序(路由前必读,所有场景必须遵守) 已有文件转活页先执行上方静态托管优先例外,不进入下表 QBS leaf;首次静态交付后的数据增强才按本节加载查询规则。 **无论匹配到哪个 leaf workflow,执行顺序固定为:** ``` ① read_skill_file(global-rules 版本,见下表) → ② read_skill_file(leaf workflow) → ③ 执行 ``` **步骤 ① 全局规则文件选择(按目标 leaf workflow 确定)**: | 目标 leaf workflow | 步骤 ① 读取的文件 | |---|---| | `fast-snapshot.md` | 无(Fast Path,跳过步骤 ①,直接执行) | | `fast-window.md` | 无(Fast Path,跳过步骤 ①,直接执行) | | `fast-report-period.md` | 无(Fast Path,跳过步骤 ①,直接执行) | | `quick-window.md` | `workflows/global-rules-lite.md` | | `period-return-compare.md` | `workflows/global-rules-lite.md` | | 其他所有 workflow | `workflows/global-rules.md` | - **步骤 ① 是硬前置条件**。确定目标 leaf 后,先按上表选择并读取对应 global-rules 版本,再读 leaf workflow,最后执行。 - Fast Path(fast-*.md)直接从步骤 ② 开始,无需步骤 ①。 --- ## 场景路由 **先识别用户意图,确定目标 leaf workflow;然后按上方执行顺序加载**: | 场景 | 触发词 | 目标 leaf workflow | |------|--------|----------| | 国内股指期权槽位行情 / 数据覆盖 | 沪深300/上证50/中证1000 + 期权/IV/隐含波动率/ATM/25C/25P/E1/E2;国内期货期权是否含股指 | `global-rules.md` → `cn-index-options.md`;槽位行情走数据目录与公式/读取,不用合约映射接口判断行情覆盖;完整链另行核验 | | 单资产历史/跨日分钟 | 用户明确历史交易日或跨日区间的原始1分钟/分时CSV | 确认唯一资产 → `tools/fast_query_minute_range.md` → `fast_query_minute_range`;不传fields/format/remove_nan | | 多资产/全市场分钟、每日时段或交易日滚动 | 多个资产、market、分钟范围、最近N个交易日或current_trade_day规则 | `tools/fast_query_minute_range_multi.md` → `fast_query_minute_range_multi`;用assets/asset/market三选一,不传tickers/fields/format | | 单资产日内分钟 / 分时序列 | 明确要求分钟、分时、1分钟、每分钟、日内 OHLCV、逐分钟开高低收/成交量;不含历史日期、区间或多资产 | 先按资产库规则确认唯一资产 → 直接调用 `fast_query_minute` → 成功即停 | | 最新时点行情 / 估值 / 基础信息(快照) | 最新价、今日收盘、最新涨跌幅、当前换手率、最新PE/PB/市值、所属行业… | Fast Path 条件满足 → 只读 `fast-snapshot.md`;不满足/无法查询 → `global-rules.md` → `quick-snapshot.md` | | 最近N日序列 / 窗口统计 | 最近5日、最近20日、近N个交易日、窗口最高/最低/振幅…(仅单资产、最近N日) | Fast Path 条件满足 → 只读 `fast-window.md`;不满足/无法查询 → `global-rules-lite.md` → `quick-window.md` | | 最近报告期财务 | 营收、净利润、归母净利润、ROE、总资产、总负债、资产负债率… | Fast Path 条件满足 → 只读 `fast-report-period.md`;不满足/无法查询 → `global-rules.md` → `quick-report-period.md` | | 单只 A 股快速画像 | 贵州茅台、茅台、600519、SH600519;或“分析一下贵州茅台”“分析下深圳新星(SH:603978)”等简单综合分析,资产唯一且名称代码一致 | `live-page-routing.md` → `single_a_stock_fast` → QBV `guides/answer-first.md`,先答再 `new_asset_page` | | 单股指标画像 / 个股综合分析 | 分析一下XX个股、看一下XX这只股票、个股画像、指标概览、估值财务资金走势综合看一下、基本面和估值怎么样… | `global-rules.md` → `stock-profile.md` | | 最新上市/退市/更名/换代码或资产状态冲突 | 现在上市了吗、最新代码、是否退市;或本地资产库命中但平台返回 `ASSET_NOT_FOUND` | `global-rules.md` → `external-fact-verification.md`;外部事实与 Quant Buddy 数据状态必须分开判断 | | 单资产标准历史字段同图 | 一个资产 + 2~4 个价格/成交/估值标准历史字段 + “放在一张图里/画成图/同图比较” | **只读 `visual-page-fast-path.md`**;先 route,再一次 `fast_query`,一次命令准备 capsule + Handoff + Job;禁止进入 `quant-standard.md`、`render-kline.md` 和静态渲染 | | 申万一级行业近N日涨跌幅排名图 | 申万一级行业/行业板块 + 最近N日/最近一个月 + 涨跌幅 + 排名图/柱状图/可视化 | **只读 `industry-ranking-fast.md`**;固定一条行业聚合公式,只读 `indexinfo_id`,直接准备已物化 QBV Job;禁止进入 `global-rules.md`、`quant-standard.md`、行业 recipe 和 `renderChart` | | K线活页(可持续打开) | 明确出现 K线/K 线/蜡烛图/OHLC/开高低收,且没有明确只要图片 | **只读 `kline-page-fast-path.md`**;QBS `query_kline` 验证 OHLCV 和所选指标后先答,再交给 QBV 的 `candlestick` 运行时面板;禁止调用图片型 `renderKLine` | | K线图片(明确只要PNG/图片) | 用户明确不要网页、只要图片 artifact | `global-rules.md` → `render-kline.md`;此时才允许 `renderKLine` | | 固定区间累计涨跌幅 | 从A到B、某年某月至某年某月、区间收益、累计涨跌幅、区间表现、多资产区间对比 | `global-rules-lite.md` → `period-return-compare.md` | | 数据下载 / 导出本地 CSV | 下载成CSV、导出到本地、保存到本地、下载历史数据 | `global-rules.md` → `recipes/download-data.md`;单资产单字段时序优先 `runMultiFormulaBatchStream` → `downloadData` → `write_skill_file`,禁止 Bash 兜底 | | 已物化指标选股 / 维度分或细分指标 TopN / 推荐股票 | 分数最高、综合分最高、维度分,或由已物化细分 score/screen 指标组成的推荐/选出/筛选 TopN | `global-rules.md` → `composition-select.md`(`newSession` → 本地快照匹配或在线目录确认 → `selectByComposition`) | | 高频稳定因子榜单:低 PE + 高 ROE TopN | 同时出现低PE/低市盈率、高ROE/高净资产收益率、选股/筛选/排名、TopN/前N;即使没说图表或活页 | `global-rules.md` → `quant-standard.md` 的“高频默认口径”;验证 TopN 后必须实际 route,`create` 时用三个已物化 `data_id` 一次 `prepare-validated-page`,QBS 先答、QBV 同轮完成后补链接;明确不要网页则 `none`,只要表格且无其他建页意图也保持 `none` | | 维度指标库查询 / 指标口径与公式 | 平台有哪些维度、XX 维度下有哪些指标、XX 指标怎么算的/口径是什么/公式是什么、想按现成指标改口径 | `tools/dimension_indicators.md`(用 `scripts/call.py` 调 `listDimensionIndicators` → `getIndicatorFormulas`,非平台原生工具;要拿改过的公式跑数再转 `quant-standard.md`) | | 量化选股 / 回测 / 因子 / 图表 / 上传下载 | 选股、回测、均线、PE选股、因子、净值、上传CSV、下载数据、画图、多个指标放进同一张图…;或目录无匹配维度、需要临时构造指标/历史曲线/自定义公式 | `global-rules.md` → `quant-standard.md`;执行回测、监控、画线或任何图表 artifact 在首答前必须实际运行 `live_page_routing.py route`,命中 `create` 后非阻塞交接 QBV | | 直接运行用户给定的公式链文件 | 「运行/跑一遍/执行这个文件里的全部公式」「公式链文件」「formula chain」「按这个 md/json 跑」 | `global-rules.md` → `run-formula-chain.md` | | 事件研究 | 复盘、历次、涨价、降息、加息、事件窗口、随后表现、超预期、不及预期、政策后表现…(给定事件或需先识别事件日) | `global-rules.md` → `event-study.md` | | 阈值区间统计 / 连续阶段 | 历次、每次、平均、回撤超过、从高点下跌超过、熊市区间、连续阶段、regime | `global-rules.md` → `regime-segmentation.md` | | 每日复盘 / 持续监控 / 每天看行业股 | 每日或定期复盘、每天看、监控/盯盘、刷新看板、做个能直接打开的页面 | `global-rules.md` → `quant-standard.md` → `answer-first.md`;先原生查询和完整业务首答,再交 QBV;不进入先注册包的旧流程 | | 明确开发接口 / 管理公式任务包 | 用户明确要求注册公式包、package_id、签名取数、对外只读接口或第三方接口接入 | `tools/formula_package.md` + `recipes/formula-package.md`;仅接口管理请求,普通研究看板走上一行;注册前仍须验证公式和运行时频率 | > 上传、下载、画图不�
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.