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

把「已验证的量化数据与公式」沉淀成一个公开可分享、实时取数的网页看板/落地页。本技能不做一次性行情查询或回测探索；默认执行路线是：

已有文件交付例外（含增强后版本）：本流程链接统一称“可分享活页”，不强制称“实时”；数据状态另外如实说明。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。

最高优先级：既有活页解读。 用户给出 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 链接给用户。

0. 除上述既有活页解读分支外，在任何后端请求前运行 scripts/trace_context.py begin，保存唯一 task_id 并在后续命令中复用。这步本身就是后端写入调用，必须和后续命令带同一个身份（QBV_API_KEY 环境变量或参数里的 api_key），不带会被记成 skill 默认账号。
1. 若用户只是要简单分析一只 A 股并返回页面，且没有定制栏目/版式、额外指标/公式/图表、对比或多标的要求，直接运行一次 scripts/static_page.py new_asset_page。成功结果包含完整数据草稿 agent_reply_markdown_draft；当前 Agent只需依据用户原问题和草稿前五章数据补写综合观察，不再查 templates，也不另跑 QBS 验证或注册 Grant。
2. 除上述快速场景外，运行一次 scripts/static_page.py templates，查询统一 public 命中池（服务端一次返回官方精选+社区）。
3. direct 只有在范式、范围和全部请求维度三轴均有证据时成立；direct_deliver 必须提交 dimension_check。缺维度改走 fork + same_paradigm_augment_dimension。
4. fork/unmatched 调用 new_page 时由 Agent 根据 items_summary 显式传 routing_decision；fork 还必须声明 borrow_mode=inherit|inherit_augment|compose。fork 一旦判定只能继承、增强继承或 Compose，禁止改判 unmatched。
5. 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 必须拒绝。

Compose 参数交接

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。
• 要一个能反复看、能发给别人、数据会自动更新的页面 → 切到 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_model":"当前真实运行模型（明确知道时才传）"}'

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

agent_model 是纯可选审计字段：明确知道当前 Agent 的真实运行模型时建议传入；不确定时直接省略，禁止猜测，也不要询问用户。宿主也可通过可选环境变量 QBV_AGENT_MODEL 注入。模型名按“显式参数 → QBV_AGENT_MODEL → 当前 task_id 的任务临时上下文 → 空”解析；缺失、纯空白或上下文读写失败都不得中断任务，非空值会通过 x-agent-model 自动贯穿后续命令与 QBS bridge。

保存返回的 task_id，并把它加入本次任务后续每个 static_page.py、formula_package.py、data_grant.py 参数。脚本会通过 x-task-id 请求头透传，使后台能从提问一直聚合到最终活页链接。new_asset_page / templates / upload / update / publish_final / publish_verified 缺少 Trace Context 时必须停止执行。QBV 编排中的 quant-buddy-skill 工具统一通过 scripts/qbs_bridge.py <tool> @params.json 调用，并显式传同一 task_id + user_query；bridge 会用 task-scoped session 继承 task_id，禁止生成第二个 session id。

build_dashboard.py 也属于上述“后续每个命令”：只要 spec 含 upload:true 或 update_page_id，必须写入同一 task_id。成功结果会返回 hash-bound reply_draft_file + reply_validation_command；公网验收后必须写草稿并运行该命令，只有 valid:true 才能最终回复，之后停止工具调用。

计划与恢复：普通研究页按计划驱动交付执行。借鉴范围、目标运行角色及构建模式必须一致；Compose返回的params文件用于完整候选构建，随后publish_verified。update_progress必须使用page_status/current_step；技术失败不是用户确认，已有可读内容不得被失败进度页覆盖。 登记运行凭据需对应验证收据；静态金融页用materialize_snapshot及计划snapshot_roles，不手填数据绕过验证。

具体资产证据闸门：已有文件转活页先执行静态交付，本闸门仅在其后实时增强阶段生效。除 new_asset_page 固定场景外，只要用户点名具体资产，就在 Trace 后、解释资产身份或提交 routing_decision 前，按「Trace → 资产映射 → 最小接口验证 → 页面路由」的顺序完成验证：调用 scripts/qbs_bridge.py resolve_asset_data 得到平台 ticker 映射，并按页面实际需要探测所需数据角色是否可取数，只记录接口成功/失败、可用字段和结构化错误。页面结构与 direct/fork/unmatched 判断只依据"用户所需能力 × 已验证的平台能力"，不得依据 Agent 对公司上市状态、所有权、资产名称或市场惯例的记忆。验证前不得引入"上市/未上市、公开/私营、代理资产、无行情、只能静态"等限制性前提；若用户没有询问这些身份属性，也不要把它们扩展成分析主线。

resolve_asset_data 的输入合同必须直接按下面形状写入新的 output/*.json，不要先猜 schema、不要把多只资产拼成一个 asset 字符串，也不要为每只资产各写一份参数文件：

{
  "task_id": "<同一 task_id>",
  "user_query": "<当前用户原问题>",
  "assets": ["贵州茅台", "五粮液", "泸州老窖"],
  "required_roles": {
    "snapshot": ["close", "pct_chg", "pe_ttm", "pb", "market_cap"]
  },
  "optional_fields": ["turnover_rate"]
}

• 单资产用 "asset":"贵州茅台"；多资产用 "assets":[...]，二者不能并存。多资产由 bridge 在一次 CLI 调用内逐资产验证并聚合收据。
• required_roles 只需写实际需要的 role；省略的 profile/snapshot/report/formula 自动视为空数组。每个 role 的规范值是字符串数组，也兼容 {"fields":[...]}。
• 多资产探测阶段的 formula 必须留空或省略；跨资产公共公式只在探测后用 validate_package_set 验证一次，禁止每个资产重复验证/注册同一公式包。
• output/ 是跨会话残留的 scratch，不是示例库：禁止 Grep/Read 旧 output/*.json 来拼本次参数，尤其禁止复制其中旧 task_id、旧凭证、旧公式或损坏 JSON；参数形状只从当前 SKILL.md / tools/*.md / workflows/*.md 获取。
• 含双引号的公式必须写成合法 JSON 转义；优先使用无嵌套引号的等价公式（如 mt_close = 收盘价(贵州茅台)）。写入后直接执行对应 CLI，让 JSON parser 作为反馈，不要读取旧 scratch 文件“找范例”。
• 多资产累计收益/回撤优先走标准看板：同一组价格 outputs 分别配置 transform:"cumulative_return_pct" 与 transform:"drawdown_pct"，估值另用 Data Grant table。此能力已由 build_dashboard 内置，禁止为它 Grep/Read assets/data-kernel.js 或手写 bespoke SSE/Grant runtime；详见 workflows/dashboard-end-to-end.md 的最短路径。

已有 URL 修改按写权限原位更新或 Fork

只有用户明确要求“解读/查看当前页面”且不要求修改时，才使用不带 task_id 的纯只读 interpret，读取后即可按返回证据回答，不进入建页流程。

用户要求修改已有 QuantBuddy URL 时，先 trace_context.py begin，再带同一 task_id 调用 static_page.py interpret。必须按返回的 existing_page_route.mode 分流，不能把所有已有页一律判成 Fork：

• mode="in_place"：调用者是 owner/page admin，或旧版详情合同返回 resource_role="existing_page"、由 updateStaticPage 在写入时做最终权限校验。保持原 page_id、公开 URL、包/Grant、Share Shell 与运行时身份，使用 static_page.py update（以及需要时的 update_progress / publish_verified）写回原页。禁止 new_page、new_asset_page、upload 创建替代链接，也不需要再次查询 templates。若 chart_edit.py 返回 LEGACY_PAGE / NO_RENDER_JS_MARKER，而用户已明确要求修改本人页面并保持原链接，则必要的技术性结构升级已获授权：立即按 workflows/edit-existing-chart.md 的 legacy fallback 下载、最小重建、浏览器预检并 update 同一页，不得二次询问是否升级，也不得停在本地 HTML。只有缺失信息会改变业务语义时才询问。若服务端返回 FORBIDDEN，停止写入并转入下述 Fork 路径，不得伪造 is_page_admin。
• mode="fork"：当前详情明确 can_update_in_place=false，或该页是不可直接写入的 source_template。依次执行 templates(recommend="all") → new_page(mode=fork, source_template_id=<interpret 返回>) → fork_prepare；templates 只补齐范式池凭据，不能覆盖 interpret 已绑定的来源。

可信权限字段由服务端 getPageDetail 返回：can_update_in_place 与 access_role=owner|page_admin|reader。客户端不得相信调用参数里自报的 is_page_admin；旧服务端尚未返回 capability 时，只允许尝试写回 interpret 绑定的同一个 page_id，并以 updateStaticPage 的 owner/page-admin 鉴权结果为准。

Fork 路径在决策绑定前禁止 new_asset_page、build_dashboard、bespoke upload 或任何 regenerated page；不得改判 unmatched 或偷换来源。只有 fork_prepare 明确返回结构化不可复制错误后，才允许评估降级，并显式声明 page_context_mode=regenerated 与 source_page_context_inherited=false。

从 QBS 并行交接进入（薄适配，不改变 QBV 独立 SOP）

当父任务提供 qbs_qbv_handoff_v1 文件时，不再执行 begin，而是：

python scripts/trace_context.py beginHandoff '{"handoff_file":"D:/.../handoff.json"}'
python scripts/qbs_handoff_adapter.py evaluate '{"handoff_file":"D:/.../handoff.json","qbv_job_id":"qbvjob_xxx","qbv_job_file":"D:/.../job.json"}'

trace_context.py 原样复用 QBS 的 task_id + turn_id；Adapter 校验可选 qbs_computation_capsule_v1，并在发现对应 qbs_qbv_job_v2 时确定性把 Job 从 queued 写为 running。QBV standalone 没有该 Job 时为无副作用 no-op：

• coverage=covered：禁止再次调用 resolve_asset_data 或其它 QBS 工具重算 covered_roles；直接消费胶囊里的资产映射、合同、artifact、字段映射、结论和收据，然后继续 QBV 页面 SOP。
• coverage=partial：只允许通过 qbs_bridge.py 补 missing_roles，不得重复已覆盖 role。
• coverage=unusable：无损回退本节原有 Trace → qbs_bridge → 路由流程，不得降低验证门禁。
• Adapter 返回 formula_runtime_action=register_exact 时：把 formula_runtime_contract.formulas 按原顺序、原字面注册为 Formula Package，并按合同中的 reads 首次查询；禁止缩写指标名、合并公式、重新推导或再次调用 QBS 验证 covered 公式。fingerprint、左值或 reads 校验失败时按 coverage=unusable 安全回退，不得注册被篡改合同。旧 Handoff 没有 formula_runtime_contract 时保持原 standalone/兼容流程。

这里跳过的只是本轮重复计算。direct/fork/unmatched、本人原位更新/他人复制、Grant/Package 注册、运行时首次查询、页面构建、Card Runtime、发布和公网验收仍由 QBV 完整执行。QBS Job 只做旁路审计：publish_verified 同时取得 published=true + verified=true + page_id + public_url，或 direct_deliver 取得字段一致的强终态 direct_finalize contract 后，会自动写回 completed；无法继续且确定终止时执行 python scripts/qbs_handoff_adapter.py fail-job '{"qbv_job_id":"qbvjob_xxx","qbv_job_file":"D:/.../job.json","failure_code":"<CODE>","retryable":true}'，不得手改 Job JSON。用户直接使用 QBV 时没有 Handoff，继续走原 SOP，不依赖 QBS 胶囊。source_skill_id=null + source_skill_id_status=unavailable 是合法审计状态，不得阻断页面流程，也不得猜测历史 skill_*。

单一 A 股简单分析快速通道

用户只要求分析一只 A 股并给出可分享页面，且没有定制栏目/版式、指定额外指标/公式/图表、对比、多标的、指数或港美股要求时，直接执行：

python scripts/static_page.py new_asset_page '{"task_id":"task_xxx","asset":"贵州茅台","user_query":"分析贵州茅台"}'

该命令调用服务端固定场景，并在内部读取 SHA256 绑定 evidence、生成前五个数据章节、上报终态和清理临时文件。数据章节按有数据才生成表格、整篇最多五表；计算维度以 stock profile 的稳定画像维度为主证据、有效收盘价 CSV 的日涨跌/均线/价格位置为补充，两路均无可核验字段时才整节省略，且后续可见章节自动连续编号。消息面章节暂不输出。成功结果包含 agent_reply_markdown_draft + agent_summary_request：草稿第一至第五章就是交给当前 Agent的完整可见证据，第六章只有唯一 summary_marker。Agent必须结合本轮真实用户问题，用自己的语言直接回答用户目的，只引用草稿已有数据，提炼结论和关键依据；走势类问题使用条件式判断，财报点评聚焦报告表现，其他问题同样按原意组织，不需要关键词分类器或专用生成器。完成后只替换 marker，不改前五章、免责声明和最终链接块，不运行 validator 或其它工具，立即发送完整 Markdown。公开链接和“若效果不满意，页面可进一步升级”仍是最后两行。CSV 单项失败只删除对应字段并写 warning；完全没有可核验证据或草稿生成失败时 fail closed，不得退化成一句链接或重复调用。后续若用户要改这张自有页面，继续使用 update 保持同一个 page_id / URL。

不满足上述窄条件时，只运行一次 scripts/static_page.py templates。它调用统一 public 列表，由服务端完成官方精选+社区的去重、排序和分页；不要再手工重复调用。返回值是 item_count + 覆盖全部候选的 items_summary（不再是原始 items 全量打印），完整候选落盘在 full_result_file；正常路由判断只需要读 items_summary，不需要也不应该去读 full_result_file。

• ① 直接命中（范式匹配、范围一致，且候选真实 runtime 输出覆盖用户请求的每个维度）：
  • templates 一旦给出精确命中，普通渠道的下一条用户可见消息必须立即发送现成 download_url/public_url，中间不允许任何工具调用。推荐文案：已直接命中现成活页：[标题](URL)。我继续核对实时数据并补充分析。；若 agent_reply_hint.delivery_policy.emit_intermediate_url=false（即 feishu-group），禁止发送该 URL，直接继续。
  • 普通渠道发出链接后、feishu-group 不发链接而是立即运行一次：python scripts/static_page.py direct_deliver '{"task_id":"task_xxx","page_id":"page_xxx","template_revision":"sha256","dimension_check":{"coverage":[{"dimension":"用户维度","covered_by":["card_required_outputs:真实输出"]}]}}'。标题和简介只能作辅助证据；每个维度至少需要 card_required_outputs，或由 runtime 合同派生的 page_context.primary_outputs 权威证据。
  • 不 new_page、不注册、不 fork、不研究脚本源码、不先跑 --help。direct_deliver 的公式结果固定为 summary；grant 完整结果只写 %TEMP%，最终回复不得暴露本地路径或凭证。
  • 只有返回 agent_reply_contract.terminal=true 且 operation=direct_finalize 才允许最终收口；失败时说明具体错误，不得用已发送的链接绕过终态门禁。回复模板和 page_context 沿用原页。
  • direct_deliver 会返回真实 contract、草稿、校验参数的 %TEMP%\qbv_<完整 task_id>_* 文件路径及 reply_validation_command。只把 Markdown 写入返回的 reply_draft_file，执行返回的命令一次；valid=true 后立即最终回复，禁止再次校验、运行 --help、扫描临时目录或继续搜索 memory。成功校验会统一清理 contract、draft、params 和 grant 临时结果。
  • 公网浏览器验收成功后的下一步必须是最终回复；不得再调用 Read/Grep/Bash/浏览器或进入新的研究轮次。若浏览器验收是最后一个可用工具轮次，也必须用已验证 contract/URL 直接收口。
  • 用户之后说"要改这个页面内容" → 转 ② fork（官方/社区链接不能直接改，只能新建自己的链接后改）。
  • 边界：范式匹配但标的/股票池/指数/市场范围不一致（如命中的是茅台估值页、用户问的是宁德时代；命中沪深300异动页、用户问中证500）不算直接命中，落到 ②。只有资产无关且市场范围一致的全市场范式，才可不依赖具体标的直接命中。
• ② fork（范式命中但标的不符，或用户要改内容）：

  • 先运行 new_page，传 routing_decision:{"mode":"fork","source_template_id":"page_xxx","reason_code":"same_paradigm_different_asset","borrow_mode":"inherit"}。inherit_augment 用于模板结构可沿用但缺分析维度；compose 用于合同无法逐项继承、但布局/样式/渲染函数/公式思路或 Grant 形状仍可借鉴。

  • fork_prepare 是一次性 task 绑定：重复执行返回 FORK_ALREADY_BOUND；确需整体重建必须传 force_rebuild:true + rebuild_reason，同 task 禁止换来源模板。

  • fork_prepare 返回 publish_command 后 即进入发布收敛阶段：只填写返回的 review 文件并执行该命令，禁止读取 scripts/*.py、运行 --help 或探索 publish_workflow.py / fork_runtime_contract.py 实现；命令失败只按结构化错误修正输入。已创建首链时必须完成 terminal 或明确失败收口，不得让进度页长期停留在 running。

  • inherit_augment 向 fork_prepare 传 augmentation_spec，新增 package/grant 角色与来源角色物理隔离。新增公式必须通过 QBS 验证，marker 必须恰好出现一次且输出必须被实际渲染。

  • compose 先运行 intent_profile 做 user_term/platform_dimensions/method_terms 三层映射，再用 research_templates 提取 credential-free 的栏目 HTML、CSS、渲染函数及合同形状，最后 fork_compose 提交借鉴清单。收据及 SHA256 绑定后才允许发布；全部 original 的零借鉴 Compose 被拒绝。 fork_compose 必须传 borrow_plan.modules（不是顶层 borrowed_refs），并逐项认领 intent profile 的每个 user_term；优先复制 research_templates.templates_summary[].fork_compose_example 后修改，遇到 COMPOSE_BORROW_PLAN_REQUIRED 必须按返回示例重试，不得停在 running 进度页。

  • Compose 参数必须一次写完整：intent_profile 至少传 {"task_id":"task_xxx","asset_scope":{"kind":"sector","name":"目标资产组","market":"A股"},"dimensions":[{"user_term":"实时行情","platform_dimensions":["close","pct_chg"],"method_terms":["横向比较"]}]}；research_templates 传 {"task_id":"task_xxx","template_ids":["page_source"]}。任一结构化错误若返回 example_intent_profile、example_research_templates 或 fork_compose_example，必须直接复制该完整示例后修改并重试，不能逐字段猜测。 - 资产替换的职责分工：Agent 说清楚"换成哪只标的"，脚本负责"这只标的在页面里写成什么样"。来源主资产由脚本从模板公式词频 + 标题推导，代码的实际写法（SH600900 / 600900.SH / 裸 600900）由脚本扫描来源 HTML 得出，只替换真实存在的写法——不要去猜来源 HTML 里代码写成什么样，你看不到那个文件。多资产/指数类范式推不出唯一主资产时，不得用标题或研究ID拼造 source_asset；只借布局或重组多资产时转 research_templates → fork_compose → compose_page，真正单资产替换才补经核验的来源身份。asset_replacements 仅作可选覆盖。替换后主资产若仍有残留，在写出工作 HTML 前就返回 FORK_SOURCE_ASSET_RESIDUAL，不会等到发布后才发现。

  • Agent只在 fork_prepare 生成的 review_update_params_file.decisions 中填写 required_decisions 声明的业务决策：规则性同业矩阵填 target_slots，复杂跨资产公式填 target_formulas，标签替换填 page_label_replacements。decisions 已按角色预生成嵌套占位骨架（{"roles":{"<role_id>":{...}}}），只需要在骨架里补全空值，不要新增/改写顶层字段，也不要把 required_decisions 里的扁平 decision_id（如 roles.package.package_001.target_formulas）当成提交用的 key。禁止直接编辑标准 fork HTML/review。

  • Grant按来源角色完整继承 kind/query_type/fields/dimensions/window_days/result_mode 与 CSV/inline 合同，只允许自动修改 manifest 声明的资产范围字段；其他变化必须填写 contract_change_reason。

  • 继承 Grant 的数据级失败可降级并继续发布存活角色；鉴权/配额/协议等系统级失败仍阻断。若页面仍用 queryDataGrant 无条件消费失败 Grant，返回 GRANT_DEGRADATION_UNSAFE，不得用空凭证假降级。

  • 先运行 fork_prepare 返回的 review_update_command；只有 review_state.status=complete 且生成 review receipt 后，才运行 publish_command。发布器从同一 canonical package/Grant 合同派生 QBS 验证与注册，自动检查 required outputs、公式左值、reads、PE/PB 水位公式具有明确算法与正整数窗口、Grant fingerprint、Marker 唯一性与 Card Runtime 结构，并让一次注册结果扇出到页面/Card全部位置。

  • fork_manifest_v2 禁止手工传 packages、grants、Marker 或完整 workflow JSON，出现 MANUAL_RUNTIME_BINDINGS_FORBIDDEN 时回到生成的 publish plan，不要写临时替换脚本。v1 prepared task 继续按旧接口发布。

  • 这不是建议——publish_verified 服务端会按 fork manifest 里的凭证数量强制核验：手工分步调用 publish_verified(task_id, page_id, html_file, source_template_id, fork_manifest_file, validation_receipt_files) 只有在这个页面零凭证（纯静态改造）时才会放行，否则直接拒绝并返回 error:"PUBLISH_WORKFLOW_REQUIRED"；出现该错误时改走 publish_workflow.py，不要绕过。

  • 回复 = 回复模板格式 + 自己的新链接（数值同样用自己的包/grant query 填）。

• ③ 未命中（无匹配范式）：Agent 根据 items_summary 调 new_page 时传 routing_decision:{"mode":"unmatched","closest_template_id":"page_xxx","reason_code":"required_capability_missing","reason":"候选缺少用户要求的核心能力"}；存在候选却只因标的/范围不同而判 unmatched 会被提示改走 fork。记录成功后继续 build_dashboard / bespoke 自建 → 其余同 ②；feishu-group 同样不发送进度链接。

后续追问：自己的链接 → update 同 page_id；命中的官方/社区链接要改 → 只能转 ② fork 成自己的链接后再改。

默认路由

• 简单单一 A 股综合分析（无定制、额外指标/图表、对比或多标的要求）：trace_context begin 后直接 new_asset_page 返回自有实时页面。
• 其他固定页面形态（定制个股页、成分股异动榜、多因子选股看板、商品日报等）：先 templates 查询官方精选+社区命中池；direct 直接用列表 URL + revision，fork 才读取和改写模板详情。
• 宽宝活卡 / 精华卡 / 封面卡（范式卡 artifact）：把页面精华做成独立 card runtime artifact（embedded-card-v1：页面内嵌 <template data-qb-card-template> + data-qb-card-manifest + QBCardRuntimeV1 runtime），供官网卡片流在空白宿主中独立 hydrate。静态首帧 card_snapshot_url 由 skill_server 按 artifact hash 生成，是页面封面的唯一来源（整页缩略图能力已下线）。按 guides/essence-cover-card.md 生成；已发布页优先用 preserve_visual:true 只升级协议。完整重建必须显式传 visual_contract，否则 CARD_VISUAL_REQUIRED 停止；用 verify_page.mjs --card-runtime-only --require-card-visual-contract 验收新 artifact。卡片必须官网浅色系、固定信息骨架、可变核心可视化；不再用旧的 ?cover=1 URL 模式。
• 没有合适在线模板：再走 workflows/dashboard-end-to-end.md，用 build_dashboard 生成声明式实时看板。
• 声明式看板也不够：才走 guides/bespoke-page.md 写 bespoke 主体 HTML，并用公共 shell 编译成自包含页面。
• 改一个已有图表（叠加/去掉一条线、改时间窗口、查真实数据）：优先 workflows/edit-existing-chart.md + scripts/chart_edit.py，只动被要求的那一处、不重新验证/计算页面上其它无关系列；只有目标页面是 legacy （chart_edit.py inspect 判定，多为本次改动之前生成的老页面）或改动本质上要求整页重算/换版式，才落回 下面的整页重建。
• 改造已发布/已生成页面：优先 scripts/retrofit_share_shell.py，再 static_page.py update 保持同一个 page_id / URL；正式 update 应传具体 change_note，版式变化显式传 change_aspect:"layout"，其它类型可让服务端推断。
• Share Shell revision 4 页面问答边界：可见页头由官网 /embed/live-page-header iframe 托管，活页 Parent Bridge 只执行刷新、收藏、分享、认证导航和移动 WebAgent 动作、页面问题携题自动发送并校验 qb-live-page-header-v1 / qb-web-agent-v1；官网 WebAgent Preview 注入 qb-live-page-embed-context=webagent-preview 时不得加载页头或预加载收藏 iframe。官网只改页头视觉不要求逐页刷新；Parent Bridge、通信协议或能力契约变化才提升 revision。
• 用户可见链接策略：普通渠道 direct 在 templates 命中后、下一次工具调用前发现成 URL，fork/unmatched 在 new_page 返回后立即发首链；feishu-group 看到 delivery_policy.emit_intermediate_url=false 后禁止发送任何非终态 URL，只在 validator 通过后发送 terminal contract 的 playground public_url。进度页仍用 update_progress 和 publish_final 更新同一 page_id；未显式传 change_note 时，版本修改描述按“状态 + 中文阶段标题 + 用户可见 message”自动生成，正式发布版本默认记录“完成发布：正式活页内容已发布”。
• Agent 回复模板：活页 metadata 可带 agent_reply_template 指向本技能 reply-templates/ 下的回复骨架。reply-templates/ 是 Agent 最终回复格式，不是活页 HTML 页面模板；不要和在线 templates / template API 混用。
• 本 skill 不再内置本地页面样板，不能从本地历史样板目录或低质 HTML 骨架起步。

Agent 回复模板（agent_reply_template）

活页用同级 page_context 描述用途/模块/输出，用 agent_reply_template.template_ref 指向 reply-templates/ 的 Markdown 骨架。字段契约、hybrid 规则和发布继承见 tools/static_page.md。

• page_context 不得包含实时数值、api_key、signature、Bearer token 或本地路径；fork 后必须按最终页面重建，direct 才沿用原页。
• 读取型命令返回 agent_reply_hint.terminal=false；new_page/update_progress 也不是终态。成功的 new_asset_page/direct_deliver/direct_finalize/upload/update/publish_final/publish_verified 可返回 agent_reply_contract.terminal=true；其中 new_asset_page 返回含唯一综合观察 marker 的 agent_reply_markdown_draft 和面向当前 Agent的 agent_summary_request。
• fork/unmatched 遇到必须由用户决定的口径时，用同一 task_id/page_id 进入 waiting_input，用户回答后继续原任务；不要重新建 Trace 或首链。feishu-group 的 waiting hint 不含 public_url，提问时也不得附带进度链接。
• fork 必须使用 fork_prepare 绑定来源和 manifest，最终 publish_final 保持首链 URL、移除来源凭证并保留必需栏目/输出/Card Runtime；详细门禁见 workflows/new-session-paradigm-routing.md。
• prepared fork task 禁止 build_dashboard；v2只填写生成的 review-update 决策文件，依次运行 review_update_command 和 publish_command。只有旧 v1任务继续使用手工 fork_validate 路径。
• 带 task_id 的进度从 package_register 起必须传同任务的结构化验证证据：实时页提交 route_receipt、grant_receipts、formula_receipts，且 selected_routes 必须逐项对应实际注册凭证；自由文本 validation_not_required_reason 不再放行。纯静态内容只能用 static_content_only；资产实时探测全部数据级失败时只能凭 live_data_route_receipt_v1 使用 static_after_live_probe。
• new_asset_page 的最终回复只允许把 agent_reply_markdown_draft 的唯一 summary_marker 替换为 Agent撰写的综合观察；不得改写、删减或重排其它内容，也不得把 marker 发给用户。综合观察首句直接回答本轮用户目的，后续只选最相关证据解释，避免复述全部五章；没有足够证据时明确说明边界，不得补造事实。该分支不返回 evidence 路径或校验命令。其他终态回复必须按回复模板输出并且只能使用 contract 的 public_url；feishu-group 下该字段必须是 https://www.quantbuddy.cn/playground/<owner>/<page_id>。**只要终态回复包含 public_url，必须把 可分享实时活页：[{public_url}]({public_url}) 作为最后倒数第二行，最后一行固定为“若效果不满意，页面可进一步升级”；链接不得在正文、章节或免责声明中提前出现。**一般模板依据 reply_render_policy 与 reply_data_availability 删除结构性不存在的字段、整列、整行和空可选章节。single_stock_deep_dive_v1 还必须读取 SHA256 绑定的 reply_data_evidence_file，保留全部七节标题，有数据的模板字段全部输出，整节无数据使用标准说明；只有有效结构中的偶发缺值才写 --。若 delivery_policy.max_markdown_tables 存在，整篇不得超过该表格数，超出的结构改用列表或行内文本且不得丢数据。validator 返回 valid=true 后原样发送 validated_markdown，不得再次压缩或改写，也不得暴露原始托管 URL、本地路径、凭证或内部日志。
• 除 new_asset_page 外，最终回复前只运行一次发布器返回的 reply_validation_command。reply_validation_env 是进程内执行专用值，CLI 与持久化报告只允许返回 [REDACTED] 和 reply_validation_env_keys，禁止输出真实凭证。若发布时显式设置了 QBV_API_KEY，validator 命令必须继承同一个现有环境变量；未显式覆盖时由 config.json/config.local.json 解析默认账号，发布器返回中不携带默认配置 key。禁止把 key 拼进命令串或另写参数文件。validator 必须读取发布器生成的 contract_file + contract_sha256，不得手工重建精简 contract。direct 使用 direct_deliver 返回的完整 task ID 路径和命令，成功后自动清理。valid=true 后不再执行任何工具调用。
• 没有 terminal contract 禁止完成任务。唯一例外是成功的 waiting_input checkpoint。
• 性能门槛：普通渠道模板命中到首链不超过 5 秒；所有渠道 terminal 到最终回复不超过 45 秒，完整活页任务以 10 分钟内完成为常态目标，用户可见消息间隔不超过 60 秒。回复证据补读不设额外人工截止时间，但必须按模板字段过滤、相同模式批量读取且每批最多10个；禁止公式重算和 package/grant 重查。
• 逐指标声明最新可得日期和实际覆盖范围。未做浏览器验收时，只能声明公开 URL 和实时接口可访问。

前置依赖：公式必须先验证

本技能运行时自包含：注册/生成/发布只凭本技能 config.json 的 api_key。但注册公式包前，每组公式必须先在 quant-buddy-skill 里用 runMultiFormulaBatchStream 跑通确认出数；服务端试读只是兜底，不替代这一步。

如果当前环境没有 quant-buddy-skill，Agent 不要跳过验证或直接注册公式包。