pseudo-longinus/quant-buddy-skills/quant-buddy-view

页面研究合同（WebAgent 正式投研）

制作活页时，必须先参考用户提问的背景、关键矛盾点和潜在需求，再决定模块结构与信息层级，搜索到的背景信息要落到页面中。

• 页面开头说明“本页回答什么问题、核心矛盾是什么”，不要直接进入数据表。
• 外部背景信息必须带来源与发布日期，并与 QBS 数据分区展示；查无实据时写明缺口。
• 复杂研究页先给维度清单，标注“已有数据 / 待补采 / 缺数据”，再展开各模块。
• 搜索、分析、建模、建页形成一条链：搜索结果要转化为结论、页面模块和数据需求。
• 用户明确要求纯文字时不要建页；最终回复不超过 1200 字，不使用多级标题，不附页面链接。
• 页面构建最多重试 2 次；第 2 次验证失败后降级到最简可交付版本，保留已验证数据和结论，不得无限循环。
• 快速通道页面（new_asset_page）必须在页面末尾附两个轻量模块：「背景与关注点」（3 句以内，有可靠来源带链接与日期，无来源则如实写外部语境缺失）和「边界与风险」（1–2 句，说明不构成投资建议与主要不确定性）。

页面构建策略（自建整页一律模型手写）

自建 / unmatched / 研究分析 / 对比看板 → 模型手写自由 HTML

适用于：无匹配范式的自建页，以及个股分析、行业研究、深度报告、对比分析、对比看板、策略研究、供需因子分析等需要叙事结构和丰富视觉的场景。

• 只要本轮路由为 `unmatched`，整页必须由模型直接写 HTML + CSS + JS；build_dashboard 不得生成整页替代 bespoke 自建页。
• 页面布局、信息层级、图表组合、视觉语言由模型设计，不受标准面板卡片系统约束。
• 在 HTML 中嵌入 Data Grant（grant_id + signature）或 Formula Package（package_id + signature）实现实时数据绑定。
• 可使用 Chart.js、ECharts、自定义 SVG/Canvas 等交互式图表；build_dashboard.py 仅允许 emit:"panel_block" 生成局部图表脚本，外层页面仍必须模型手写。
• 设计原则：
• 首屏决策：最重要的结论和最关键数字必须在首屏可见，大字号高亮。
• 图文交替：标题 → 结论 → 图表 → 白话解读，避免连续表格或等权卡片堆叠。
• 每个图表配 1–2 句“怎么读这组数据”。
• 核心数字用大字号（≥28px）+ 高亮色；辅助信息弱化。
• 320px 不留横向滚动。
• 页面开头 2 句话说明“本页回答什么问题、核心结论是什么”。
• 构建流程：QBS 验证数据 → 模型手写完整主体 HTML → compile_bespoke_page.py 内联公共 shell / 数据内核 → upload 或同页 publish_verified 发布。

标准面板 / 局部图表组件 → build_dashboard 仅作组件工具

build_dashboard 不再作为新任务 unmatched 自建整页的渲染器。它只用于：

• 生成 emit:"panel_block" 的局部图表脚本，嵌入模型手写的 bespoke 页；
• 维护已存在且明确声明为标准面板的 legacy 页面；
• 无任务路由的本地工具化渲染场景。

不得因为用户说了“看板”“实时”“排名”就把 unmatched 自建整页降级为 research-v1 标准卡片页。若用户明确只要最简标准面板，也必须先手写 bespoke 主体，再按需嵌入声明式图表组件。

路由优先级

1. 已有文件 / 已有页面保留原布局，按各自维护合同执行。
2. 命中在线模板：direct / fork 按模板合同执行。
3. `unmatched` 自建：一律模型手写完整 HTML/CSS/JS。
4. build_dashboard 只能生成局部 panel_block，不得生成 unmatched 整页。
5. 不确定如何组织页面时，读取 bespoke 页指南 和 自建质量底线，仍走模型手写 HTML。

多资产对比表格格式

• 多资产对比时，表格必须用"透视格式"：指标名为行、资产名为列并排展示。
• 禁止使用 API 原始返回的长表格式（每行=标的+指标+值）；如原始数据是窄表，必须转为宽表后再渲染。
• 大额金额自动缩写为"亿元"或"万元"，保留两位小数；百分比保留两位小数带 %。
• 差异列用 +/− 前缀标明方向；末尾可选加"差异对比"列，展示两值之差。

筛选零结果降级

• 筛选结果为 0 只时，自动按预设顺序放宽非核心条件（如市值从 100 亿降至 50 亿再降至 30 亿），每次只放宽一个条件，最多 3 次。
• 放宽条件必须在页面上标注"已放宽：市值从 100 亿降至 50 亿"。
• 交付非 0 名单按综合得分排序，不按代码排序。仍为 0 则交付空结果并解释原因。

港股与美股页面最低质量标准

• 港股/美股页面必须至少包含 2 张图表（如估值走势、区间表现、财务趋势），不得只用表格交付。
• 即使 QBS 港股维度比 A 股少，也要用已有数据画图（如 PE(TTM) 近一年走势、近 20/60/250 日区间表现柱图）；数据不足时画已有部分并标注缺口。
• 港股/美股页面必须绑定至少 1 个实时数据模块（如最新行情 Data Grant），不能全部为静态快照。
• 港股/美股的图表标题和轴标签必须标注货币单位（港元/美元），不得与 A 股人民币混用。

数据动态化优先

• 建页时优先用 Data Grant / Formula Package 绑定实时数据，不把数字写死在 HTML 里。
• 多源数据日期不一致时，用"最近可得值填充"对齐到最新日期，并在页面上标注实际数据日期。
• 页面各模块标注 LIVE（打开时实时取数）或 SNAPSHOT（构建时快照）状态。

筛选正确性与交付恢复

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

quant-buddy-view · 量化看板发布

研究页标题合同：页面主标题、HTML <title> 与发布元数据 title 必须一致。标准生成、Compose 和 Fork 在构建候选时同步；Fork 保留“显式标题 → 目标页标题 → 替换后的来源标题”顺序。手工候选或原位维护省略 title 时从正文主标题补齐，显式冲突返回 PAGE_TITLE_MISMATCH 并在任何发布写入前停止。正文用 data-qb-page-title 标记唯一主标题文本节点；旧页只允许唯一有效 <h1>，不选择章节、卡片、模板及隐藏标题。定位不明返回 PAGE_TITLE_AMBIGUOUS；复杂 Fork 标题不能安全替换时保留结构并返回 PAGE_TITLE_REWRITE_REQUIRED，由 Agent 修正候选后继续。标题同步必须早于哈希、候选收据和浏览器验收；已绑定候选需重新构建或 prepare_maintenance，不能在验收后改字。公开验收检查真实 DOM、浏览器标题及回读元数据；发布后不一致为 published:true、verified:false，不得重发或输出成功合同。原文件忠实托管及保留原 HTML 增强沿原有受验证入口，不改源标题；历史页只读和 direct 复用不触发修复。

公开范围与能力边界：当前活页凭链接公开访问，不能承诺未经验证的私有权限。发布个人持仓、成本或交易记录前，须说明公开范围并取得相应授权；已明确授权则不重复确认，普通公开行情页面无需额外确认。页面打开/刷新取数不等于已启用每日定时任务、主动通知或自动交易；只有实际能力与创建/执行成功证据齐备，才能报告这些状态。缺少能力时如实说明，继续完成已授权且可实现的部分。

宿主约定优先于独立路由：WebAgent 的金融问题默认在 QBS 完整首答后继续本技能，不因“只查一个字段”“最近如何”或概念解释而取消建页。下文一次性查询只用 QBS 的规则仅适用于无此约定的独立使用。页面沿答案范围与结构生成，保留显式不要网页、原页身份和发布验收规则；详见 先答后建页。

把「已验证的量化数据与公式」沉淀成一个公开可分享、实时取数的网页看板/落地页。一次性行情与概念解释由 QBS 回答；执行回测、每日复盘、监控、画线画图和看 K 线默认先 QBS 后本技能，不要求用户另说“做网页”。默认执行路线是：

已有文件交付例外（含增强后版本）：本流程链接统一称“可分享活页”，不强制称“实时”；数据状态另外如实说明。file_prepare 可恢复流程的原始静态版验收后立即交付，不套用终态“实时活页”固定结尾，也不调用要求terminal=true的终态回复validator；说明静态性质并继续已授权增强。feishu-group使用playground链接。

feishu-group 渠道：打包渠道为 feishu-group 时，direct/fork/unmatched/update 等所有分支禁止发送非终态链接；终态 contract 统一把 pages.quantbuddy.cn/pages/<owner>/<page_id>.html 转成 www.quantbuddy.cn/playground/<owner>/<page_id>，内部发布与验收仍使用原始托管 URL。

量化建页时序：除已有文件托管、只读解读、纯展示维护外，先按 答案结构建页 完成 QBS 查询并发完整非终止首答，随后才执行下述快页/模板/建页路线。此顺序也适用于 new_asset_page 快页；不能让页面验收阻塞首答。

首答不是终态：显式调用 QBV 的建页请求在 bridge 参数中保留 page_requested:true。消费 page_delivery_required 与 after_business_answer，非终止首答后执行返回的页面步骤；status:live/success:true 仅表示数据就绪。额外日期窗口、资金指标或定制展示沿模板/Compose，不能手填快页标志省略请求内容。只有页面与回复验收通过，或实际执行既有恢复流程后报告具体阻断，才结束；宿主仅展示最终消息时继续建页后完整交付，不假设最终回复后自动续跑。

最高优先级：既有活页解读。 用户给出 pages.quantbuddy.cn/pages/... 的 QuantBuddy 活页 URL，且意图是“解读 / 分析当前活页 / 看这页数据”时，先且只运行：

python scripts/static_page.py interpret '{"url":"用户提供的页面 URL"}'

这是只读数据路径，不要运行 trace_context.py、templates、template、direct_deliver、new_page、fork、download、浏览器或 HTML 搜索，也不要创建、更新、发布页面。它调用 getPageDetail?need_data=true；服务端使用页面绑定的公式包和 Data Grant 取最新数据，并附加 interpretation_bundle，不返回 signature。直接按用户的自定义要求解读详情与 interpretation_bundle.runtime_data。未指定格式时，依次输出一句话结论、关键指标及变化、风险/异常、3 个继续追问方向。详见 workflows/interpret-existing-page.md。

若 interpretation_bundle.runtime_data.grants[].data.mode="csv"，先返回的 csv_fields[].csv_url 是短期下载链接而非可直接计算的数据。必须紧接着运行一次 python scripts/static_page.py interpret_csv '{}'：它只下载该次 interpret 已返回的 CSV、保留链接并补出 results[].fields[].series，然后再计算和解读；禁止重跑 interpret、另查数据接口或把 CSV 链接给用户。

1. 除上述既有活页解读分支外，在任何后端请求前运行 scripts/trace_context.py begin，保存唯一 task_id 并在后续命令中复用。这步本身就是后端写入调用，必须和后续命令带同一个身份（QBV_API_KEY 环境变量或参数里的 api_key），不带会被记成 skill 默认账号。
2. 所有量化建页先读 先答后建页。若 QBS 已在本轮交付有效完整画像首答，跳过再次取数，复用同一 task/turn，直接 new_asset_page(reply_mode:"page_followup")；不要重新 resolve_asset_data、stockProfile 或创建第二个 session。尚未取数时通过 qbs_bridge.py 查询业务数据，校验实际日期与单位，发送完整非终止业务答案。本步骤的下一次工具调用仍须继续页面流程，不能以无工具的最终消息结束。 若只是简单分析一只 A 股并返回页面，没有定制栏目/额外指标/对比，首答后运行一次 scripts/static_page.py new_asset_page，不用查 templates 或自行注册 Grant。成功草稿用于最终页面交付，不代替之前的 QBS 首答。
3. 其他量化建页也必须先完成第 1 步的业务首答，然后运行一次 scripts/static_page.py templates，查询统一 public 命中池（官方精选+社区）。已有文件托管与纯展示维护保持各自入口。
4. direct 只有在范式、范围和全部请求维度三轴均有证据时成立；direct_deliver 必须提交 dimension_check。缺维度改走 fork + same_paradigm_augment_dimension。
5. fork/unmatched 调用 new_page 时由 Agent 根据 items_summary 显式传 routing_decision；fork 还必须声明 borrow_mode=inherit|inherit_augment|compose。fork 一旦判定只能继承、增强继承或 Compose，禁止改判 unmatched。

定义研究范围前读取 研究与数据合同：只有市值筛选时标题必须限定为“市值候选/大盘代表股”；只有主连历史时标题必须含“主连参考”；来源没有缺失标记时不能将数值0解释为缺失。新组装页面再读取 自建质量，用安装包内的结构示例起步。

1. new_asset_page 成功后，按 agent_summary_request 用当前 Agent补写草稿中的唯一 summary_marker，保持其余内容不变并立即发送；direct、fork/unmatched 仍按 agent_reply_contract 和回复模板生成证据绑定草稿，再运行返回的 reply_validation_command，只有 valid=true 才最终回复。

多轮追问：首次用户消息运行 scripts/trace_context.py begin；同一 task_id 的每条后续用户消息先运行 scripts/trace_context.py beginTurn。正常 Agent 必须同时传本轮可选 agent_intent：简洁展开上下文指代并写清对象、动作、约束和期望页面/产物，推荐 20～160 字；不得复制用户原话、输出内部推理或提前编造结论。老调用方可省略并按 null 继续。一轮内所有 QBV/QBS 工具共享同一 turn_id。Turn 是审计旁路：服务端记录失败会返回 tracking_recorded:false，但不得阻断建页、更新、取数或发布；业务上下文继续切换到真实 user_query / agent_intent，attempted turn_id 不保存、不传播，后续按无 Turn 模式继续。更新既有活页必须继续复用原 page_id 与公开 URL。

QBS 先答 Handoff（默认同轮）：收到 qbs_qbv_handoff_v1 时运行 scripts/trace_context.py beginHandoff（兼容 begin-handoff），传入 Handoff object 或绝对 handoff_file。必须原样复用其中真实 task_id + turn_id + source_skill_id，不得再次 begin/beginTurn、不得在 QBV 重做 QBS 路由分类。create/existing_page 之后仍进入本 Skill 完整 SOP，由 QBV 判断 direct/fork/unmatched、查询 ownership 并执行本人原位更新或他人复制；高风险持久状态未确认时 beginHandoff 必须拒绝。

大样本排名的展示合同：universe_count 只表示参与计算的股票数，不表示页面需要渲染的行数。Handoff 没有明确展示数量时，排名页面默认 rank_limit=20，页面只渲染 Top20。默认消费 render_mode=dynamic：Formula Package/Data Grant 在服务端缓存和取数，浏览器只展示 Top20；不要因为参与计算的股票多就降级为静态页。只有用户明确要求固定快照，或动态数据路由经过验证确实不可用并已如实说明时，才消费 render_mode=validated_snapshot。

量化建页先答

量化查询型建页先用 QBS 验证数据并发送完整非终止业务答案，再查询模板、注册运行时和构建页面；默认同轮继续。收到 Handoff 时复用已有答案和计算，按 答案结构建页 消费可选 answer_structure。不要将已发首答当作任务结束。已有文件静态托管、只读解读、纯展示维护保持原入口；分钟公式验证成功不代表公式包支持分钟注册。

量化建页只在验收后补链接：该场景所有渠道均不发送模板、草稿或进度页链接，直至页面验收成功和适用回复校验通过。此规则优先于下文、工具文档及返回 hint 中的立即首链要求和首链耗时指标；模板匹配、创建和同页更新仍正常执行。已有文件托管保留自己的首链交付与确认流程。

验证结果直接交接：resolve_asset_data / validate_grant_set / validate_package_set 返回 registration_params_file 时，首答及页面路由完成后直接执行对应 registration_command；不要重写合同、抄指纹、重复查询或另调validate。publication_evidence 原样并入看板spec，注册返回的实际ID绑定面板。已有证据的字段/范围确需变化时重新验证新合同，不能沿用旧指纹。公式型行业页面先读 行业排名交接。

Compose 参数交接

LIVE / SNAPSHOT 兼容补标：标准生成器使用已有验证数据与模块绑定补标；最终验收的 data_labels 仅为非阻断诊断。缺标不能成为停止交付、重查、删减内容或静态降级的理由。旧页面保留原流程，详见 标签口径与兼容范围。

技术失败后继续生成：历史 CSV 验证、来源凭证或注册出错时，执行 同页恢复。优先修正原合同；已有完整验证结果但注册不可用时，使用 recover_snapshot 生成同页快照候选，再继续 compose_page → publish_verified。不把一次工具失败当作任务结束，不改用 static_content_only；用户明确要求实时的页面不能用静态结果冒充完整交付。

已公开验收的计划页面，仅修改正文/布局并保留标准看板取数合同和内核时，可按 interpret 确认同页 owner/page_admin 权限后运行 static_page.py prepare_maintenance @params.json。它从线上当前版本核验基线，生成独立的维护候选收据及 publish_verified 参数；不改写原 Compose 收据。首次建页、未完成公开验收、数据合同变化、版本冲突及未知写入结果不适用。具体约束见 浏览器批注维护。

自建与Compose的发布底线见自建质量；资产身份、研究定义、完整公式合同和最小取数范围见研究与数据合同。价格或榜单会变化的文字必须使用动态绑定或显式标注历史分析日，不把静态正文当成实时结论。

Compose 数据页默认补 Presentation Mode：模型手写安全的首屏叙事/布局 HTML，标准 renderer 继续消费已验证 runtime/snapshot 面板。自动 table 只是数据绑定起点；结果页首屏必须先给结论、核心指标和主图，长表折叠。用户要求 ECharts/缩放/悬停/时间窗时不得用 PNG 降级替代。

fork_compose 与 execution_plan 修订返回会话可写目录中的 next_action.params_file。编辑该草稿的标题和研究内容，不编辑内部 /tmp 收据；修订后使用新路径和当前 plan_hash。已注册角色自动生成数据面板，runtime_role_id 是受支持的角色引用；纯 text/image 不算数据消费。先处理 draft_diagnostics，不能通过清空角色或取消实时要求绕过错误。只有工具返回 publish_verified 才进入发布；缺路由时提供本任务已有的 route_receipt_file，不重复注册。失败回复保留“任务进度（构建失败）/（未完成）”链接，但不使用成品交付措辞；宿主卡片不作为成功证据。

何时用本技能 vs quant-buddy-skill

• 一次性查询/概念解释（“茅台今天涨跌幅”“什么是均线金叉回测”）→ 用 quant-buddy-skill。
• 执行型需求（“跑个均线金叉回测看看”“每日复盘”“监控走势”“画支撑线”“看 K 线”）→ QBS 验证并先答，再进入本技能；“不要画图、只要表格”仅改变页面呈现，明确不要网页则不建页。
• 要一个能反复看、能发给别人、数据会自动更新的页面 → 切到 quant-buddy-view；已有文件转活页先静态托管，其他从零研究建页再按探索流程。

已有文件转活页：静态托管优先（高于查数与范式路由）

用户提供已有 JPG/PNG、HTML、PDF 或其他可读取文件，并要求转活页、网页活化、用 QBV 做成可分享页面时，按语义触发，不依赖“转活页”固定词。即使同时要求检查错误、补充指标、研究或重做 HTML，也必须先把来源转换为可阅读的静态 HTML、发布并验收、先交付链接，再考虑 QBS 数据接入。不得先查数据、匹配资产、查询范式或等待 Handoff/计算胶囊；这些工作均移到静态交付之后。仅阅读/分析/导出文件、未要求发布，或明确“先不要发布”时不触发。

执行 已有文件静态优先工作流：先 static_page.py file_prepare 保存原件并生成最小承载HTML及可恢复发布参数，再原样使用返回的 file_publish_dir 与 snapshot_only:true 执行 upload/update；先验收原始静态版本；返回required_user_message后，下一次工具调用前先把该链接发给用户，再运行file_confirm_delivery确认，然后继续已授权的纠错、研究和数据增强。不得用虚假确认代替实际发消息。 用户要求重做内容时，主体HTML交给同页managed update（file_enhancement_mode:content）自动编译分享壳并验收，不转入bespoke/fork流程，不先对未编译主体跑ui-refinement或增加未要求的字号门槛。不等待查数、范式匹配、公式验证或内容重做。第一版与续跑绑定同一 page_id/URL，阶段记录留在当前任务持久工作区；增强失败不得先覆盖为旧快照。未知写入结果用 file_status 核对，禁止盲目重复创建。只读文件分析或明确不发布不触发；真实公开边界、文件读取、转换、首次托管问题如实处理，不许假称成功。

新会话路由：单股快速返回 / 其余查范式卡

先建立 Trace Context。begin 是真实的后端写入调用（落审计表），和后续命令一样需要本次任务的身份——必须与后续命令用同一个 key，否则这一步会被记到 skill 默认账号名下，任务链路从第一条记录起就归错人：

# 身份走环境变量（exec 日志里会脱敏）；不要把 key 拼进命令串，命令是原样记录的
QBV_API_KEY=<本次任务的 key> python scripts/trace_context.py begin '{"user_query":"那和五粮液比呢？","agent_intent":"延续上一轮贵州茅台分析，对比五粮液的盈利能力、估值水平与主要风险。"}'

agent_intent 与本轮 user_query 绑定：首问、每次追问分别保存，追问要展开“它/上一个/继续”等指代；缺失、空白或旧 Trace 文件均按 null，不能从 user_query 伪造。QBS Handoff 继续使用 qbs_qbv_handoff_v1，可选携带同一 Intent；Intent 差异不得制造第二个 Turn、拒绝 Handoff 或改变 Job 身份。