business-report

用途

该技能用于生成可追溯的商业分析报告（Traceable Business Report），采用模板驱动方式。当用户要求分析报告、业务复盘、事后总结（post-mortem）或任何结构化多章节 HTML 交付物时使用。它是报告生成的默认路径，优先于手写 HTML。

主要能力

从模板加结构化数据渲染多章节分析报告，报告中每个数字由后端从已捕获的 artifact 结果解析，而非模型手写。
模型只提供指针（artifact_id 加结果路径），后端解析并格式化数值；错误指针会立即失败并给出需修正的确切选择器。
支持 KPI、章节、表格、图表、要点列表、建议、口径说明等报告结构。
表格通过 artifact_id 加 columns 展开行，避免逐单元格引用。
图表支持图片图表与 ECharts 宿主，可使用完整 JSON ECharts 配置，包括内置系列类型、组合系列、dataset/encode、多坐标与缩放控件。
支持分片构建长报告：先发送 REPORT_SPEC，再用 REPORT_SPEC_APPEND 扩展已保存的 spec。
支持在确实缺少派生结果时调用 request_report_calculation 请求计算。

使用方式

工具调用示例：

{
  "template_path": "business-report/templates/business_report.html",
  "title": "Olist 巴西站经营复盘报告",
  "data": {
    "REPORT_SPEC": { "...": "see below" }
  }
}

data.REPORT_SPEC 可以是 JSON 对象或 JSON 字符串。不要同时传入 html 和 template_path。优先使用对象形式，手工转义成 JSON 字符串是常见且致命的错误。

引用节点是向报告中放入数值的唯一方式，后端会将其替换为捕获值，并把渲染出的 span 绑定到产出 artifact：

{"artifact_id": "sql-f6f8810...", "path": ["rows", 0, "gmv"], "format": "money2"}
{"artifact_id": "sql-29da2e3...", "path": ["rows", 0, "product_gmv"], "format": "money2"}
{"artifact_id": "sql-7de826c...", "kind": "sql", "quote": "r.score <= 2"}
{"artifact_id": "reference-e7ae093...", "format": "text"}

format 支持：money2、num2、num1、int、pct（添加 %）、text/raw。

禁止内联字面数字。正文中的数字也必须是引用节点；若某章节文本包含数字，必须携带证据（KPI 引用、由 artifact_id 加 columns 构建的表格、图表或 intro/bullets 中的绑定值），否则渲染会在浏览器之前被拒绝。布局标签（标题、表头、章节标题）不得包含数字。

在编写 spec 前，先从 report_evidence_manifest 获取真实 artifact ID 和结果字段。先以 artifact_types=["sql", "python", "chart"] 开始，再用 detail=true 选择所需 artifact_ids（每次调用最多十二个）。

REPORT_SPEC 结构示例：

{
  "title": "…", "subtitle": "…", "scope": "分析窗口 ｜ 口径 ｜ 货币",
  "kpis": [{"label": "商品 GMV", "unit": "R$", "hint": "SUM(price)", "ref": <ref>}],
  "sections": [
    {"heading": "一、总体经营表现", "kpis": [...], "intro": [[part, …]], "table": {...},
     "chart": {...}, "bullets": [[part, …]], "list": [[part, …]],
     "recommendations": [{"badge": "P0", "cls": "p0", "title": "…",
                          "lines": [{"label": "依据", "parts": [part, …]}]}],
     "note": {"label": "口径说明", "parts": [part, …], "ref": <ref>}}
  ]
}

<part> 为无数字的纯字符串或引用节点。

表格示例：

{"artifact_id": "sql-f6f88101…", "label": "品类明细", "limit": 10,
 "columns": ["category", {"field": "gmv", "label": "GMV", "format": "money2"}, "orders_cnt"]}

图表仅在存在真实 ChartArtifact 时使用。图片图表：

{"refs": ["<sql-id>", "<chart-id>"], "img": "artifact://….json", "caption": "…"}

ECharts 宿主：

{"refs": ["<sql-id>", "<chart-id>"], "renderer": "echarts", "chart_id": "<chart-id>",  "host_id": "chart-1", "producer": {"artifact_id": "<python-id>", "field": "CHART_DATA_JSON"}, "caption": "…"}

图表配置可使用 chart.option 提供完整 JSON ECharts 配置，例如：

{"caption":"Composition","producer":{"artifact_id":"sql-real","path":[]},
 "option":{"series":[{"type":"pie","radius":["40%","70%"],
 "encode":{"itemName":"actual_category","value":"actual_measure"}}]}}

输出预算：整个 spec 在一次工具调用参数中传输，模型输出限制约 8k tokens，被截断的载荷无法解析。保持 spec 精简，表格用 artifact_id 加 columns，用 limit 而非粘贴行，intro/bullets 简短，不重复正文。

长报告可分片构建：先发送 data={"REPORT_SPEC": {...}}，再用 data={"REPORT_SPEC_APPEND": {...}} 扩展已保存的 spec（若已尝试渲染，用 retry_saved=true 再次调用）。sections 和 kpis 会追加，其他键覆盖。

KPI 值必须使用 ref，而非 value。段落使用 sections[].intro 作为 parts 数组；建议属于 sections[].recommendations，包含 title 和 lines[].parts。未知键会被拒绝。

预检（6）、文档组装（6）、实际渲染验证（3）和无效调用（3）有独立预算，报告调用总上限为 18。渲染前的 spec/选择器失败不消耗渲染尝试。

若确实缺少关键派生结果，调用 request_report_calculation，提供名称、公式和真实 SQL/Python source_artifact_ids，然后终止。

失败处理：对于大型嵌套结果，用 report_evidence_manifest(artifact_ids=["real-id"], detail=true, selectors={"real-id":{"field":"CHART_DATA_JSON","path":["stats_table"]}}) 只请求相关子树。渲染错误会指明确切的 artifact_id、选择器和容器。修正 spec（data.REPORT_SPEC），然后用 retry_saved=true 仅传修正后的数据，不要重发完整 HTML，也不要重跑已完成的分析。

适用场景

用户要求分析报告、业务复盘、事后总结。
需要结构化多章节 HTML 交付物的场景。
需要报告中每个数字可追溯到已捕获 artifact 的场景。

限制

禁止内联字面数字，正文数字也必须是引用节点。
布局标签不得包含数字。
图表仅在存在真实 ChartArtifact 时使用；JavaScript 回调和额外插件无法通过 JSON 选项执行。
模型输出限制约 8k tokens，spec 过大会被截断。
报告调用总上限为 18。
具体收费、价格、平台支持等信息暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制