@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

package/skills/dsh-data-analysis-presentation/references/examples/interaction-summary.dataset.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "columns": [
+    { "id": "query_count", "label": "query_count", "type": "int64", "nullable": false },
+    { "id": "failed_count", "label": "failed_count", "type": "int64", "nullable": false },
+    { "id": "failure_rate", "label": "failure_rate", "type": "decimal", "nullable": false }
+  ],
+  "rows": [
+    ["550", "15", "2.73"],
+    ["330", "6", "1.82"],
+    ["220", "9", "4.09"],
+    ["250", "8", "3.20"],
+    ["150", "3", "2.00"],
+    ["100", "5", "5.00"],
+    ["300", "7", "2.33"],
+    ["180", "3", "1.67"],
+    ["120", "4", "3.33"]
+  ],
+  "rowCount": 9,
+  "limit": 5000,
+  "truncated": false
+}

package/skills/dsh-data-analysis-presentation/references/examples/interaction.draft.json

@@ -0,0 +1,279 @@
+{
+  "schemaVersion": 2,
+  "title": "查询运行概览 · 全局筛选演示",
+  "sources": [],
+  "datasets": [
+    {
+      "id": "summary",
+      "kind": "computed",
+      "path": "presentation-example/interaction-summary.dataset.json",
+      "sourceIds": []
+    },
+    {
+      "id": "detail",
+      "kind": "computed",
+      "path": "presentation-example/interaction-detail.dataset.json",
+      "sourceIds": []
+    }
+  ],
+  "blocks": [
+    {
+      "id": "intro",
+      "kind": "markdown",
+      "text": "## 两日查询概览\n\n这是合成测试数据，用于验证全局筛选；不代表真实 Trino 查询结果。全量包含 550 次查询、15 次失败。下方可按日期和集群查看预先计算的结果。"
+    },
+    {
+      "id": "fixed",
+      "kind": "metric",
+      "datasetId": "summary",
+      "columnId": "query_count",
+      "rowIndex": 0,
+      "label": "完整快照查询数"
+    },
+    {
+      "id": "count",
+      "kind": "metric",
+      "datasetId": "summary",
+      "columnId": "query_count",
+      "rowSelection": "slice",
+      "label": "当前查询数"
+    },
+    {
+      "id": "failed",
+      "kind": "metric",
+      "datasetId": "summary",
+      "columnId": "failed_count",
+      "rowSelection": "slice",
+      "label": "当前失败数"
+    },
+    {
+      "id": "rate",
+      "kind": "metric",
+      "datasetId": "summary",
+      "columnId": "failure_rate",
+      "rowSelection": "slice",
+      "label": "当前失败率（%）"
+    },
+    {
+      "id": "chart",
+      "kind": "chart",
+      "datasetId": "detail",
+      "chart": "bar",
+      "x": "category",
+      "y": ["query_count"],
+      "numericMode": "exact",
+      "preparedViews": [
+        {
+          "id": "horizontal",
+          "label": "横向比较",
+          "datasetId": "detail",
+          "chart": "horizontalBar",
+          "x": "category",
+          "y": ["query_count"],
+          "numericMode": "exact"
+        }
+      ]
+    },
+    {
+      "id": "table",
+      "kind": "table",
+      "datasetId": "detail"
+    },
+    {
+      "id": "limitations",
+      "kind": "markdown",
+      "text": "## 口径说明\n\n失败率由 Python 按当前组合的失败数 / 查询数预先计算，单位为 %。每个筛选组合均有完整快照，阅读器不重新求和或计算比例。"
+    }
+  ],
+  "interaction": {
+    "title": "交互分析",
+    "blockIds": ["count", "failed", "rate", "chart", "table"],
+    "filters": [
+      {
+        "id": "day",
+        "label": "日期",
+        "allOptionId": "any",
+        "options": [
+          {
+            "id": "any",
+            "label": "全部"
+          },
+          {
+            "id": "mon",
+            "label": "周一"
+          },
+          {
+            "id": "tue",
+            "label": "周二"
+          }
+        ]
+      },
+      {
+        "id": "cluster",
+        "label": "集群",
+        "allOptionId": "any",
+        "options": [
+          {
+            "id": "any",
+            "label": "全部"
+          },
+          {
+            "id": "a",
+            "label": "甲集群"
+          },
+          {
+            "id": "b",
+            "label": "乙集群"
+          }
+        ]
+      }
+    ],
+    "slices": [
+      {
+        "selection": {
+          "day": "any",
+          "cluster": "any"
+        },
+        "datasets": [
+          {
+            "datasetId": "summary",
+            "rowIndices": [0]
+          },
+          {
+            "datasetId": "detail",
+            "rowIndices": [0, 1]
+          }
+        ]
+      },
+      {
+        "selection": {
+          "day": "any",
+          "cluster": "a"
+        },
+        "datasets": [
+          {
+            "datasetId": "summary",
+            "rowIndices": [1]
+          },
+          {
+            "datasetId": "detail",
+            "rowIndices": [2, 3]
+          }
+        ]
+      },
+      {
+        "selection": {
+          "day": "any",
+          "cluster": "b"
+        },
+        "datasets": [
+          {
+            "datasetId": "summary",
+            "rowIndices": [2]
+          },
+          {
+            "datasetId": "detail",
+            "rowIndices": [4, 5]
+          }
+        ]
+      },
+      {
+        "selection": {
+          "day": "mon",
+          "cluster": "any"
+        },
+        "datasets": [
+          {
+            "datasetId": "summary",
+            "rowIndices": [3]
+          },
+          {
+            "datasetId": "detail",
+            "rowIndices": [6, 7]
+          }
+        ]
+      },
+      {
+        "selection": {
+          "day": "mon",
+          "cluster": "a"
+        },
+        "datasets": [
+          {
+            "datasetId": "summary",
+            "rowIndices": [4]
+          },
+          {
+            "datasetId": "detail",
+            "rowIndices": [8, 9]
+          }
+        ]
+      },
+      {
+        "selection": {
+          "day": "mon",
+          "cluster": "b"
+        },
+        "datasets": [
+          {
+            "datasetId": "summary",
+            "rowIndices": [5]
+          },
+          {
+            "datasetId": "detail",
+            "rowIndices": [10, 11]
+          }
+        ]
+      },
+      {
+        "selection": {
+          "day": "tue",
+          "cluster": "any"
+        },
+        "datasets": [
+          {
+            "datasetId": "summary",
+            "rowIndices": [6]
+          },
+          {
+            "datasetId": "detail",
+            "rowIndices": [12, 13]
+          }
+        ]
+      },
+      {
+        "selection": {
+          "day": "tue",
+          "cluster": "a"
+        },
+        "datasets": [
+          {
+            "datasetId": "summary",
+            "rowIndices": [7]
+          },
+          {
+            "datasetId": "detail",
+            "rowIndices": [14, 15]
+          }
+        ]
+      },
+      {
+        "selection": {
+          "day": "tue",
+          "cluster": "b"
+        },
+        "datasets": [
+          {
+            "datasetId": "summary",
+            "rowIndices": [8]
+          },
+          {
+            "datasetId": "detail",
+            "rowIndices": [16, 17]
+          }
+        ]
+      }
+    ]
+  },
+  "locale": "zh-CN"
+}

package/skills/dsh-data-analysis-presentation/references/examples/source-only.draft.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": 2,
+  "title": "演示：只读来源面板",
+  "datasets": [],
+  "sources": [
+    {
+      "id": "analysis",
+      "ref": {
+        "sessionId": "example-session",
+        "artifactRef": "example-artifact"
+      }
+    }
+  ],
+  "blocks": [
+    {
+      "id": "scope",
+      "kind": "markdown",
+      "text": "演示草稿：替换实际引用后，查看生成时可恢复的公开来源事实。"
+    },
+    {
+      "id": "sources",
+      "kind": "source",
+      "sourceIds": ["analysis"]
+    }
+  ],
+  "locale": "zh-CN"
+}

package/skills/dsh-data-analysis-presentation/references/examples/write-charts.py

@@ -0,0 +1,73 @@
+"""合成图表样例：在分析阶段计算统计量，写入当前 Workspace。"""
+
+from dataclasses import asdict
+from decimal import Decimal
+import json
+from pathlib import Path
+
+import pandas as pd
+
+from dsh_data_analysis_presentation import write_dataset
+
+
+frames = {}
+frames["charts-series"] = pd.DataFrame({
+    "period": [f"2026-{i:02d}" for i in range(1, 13)],
+    "a": [12., 18., 15., 24., 19., 30., 28., 34., 31., 42., 39., 45.],
+    "b": [8., 11., 10., 14., 13., 17., 19., 18., 22., 25., 24., 28.],
+    "coordinate": [float(i) for i in range(1, 13)],
+    "volume": [float(i * 10) for i in range(1, 13)],
+    "segment": ["B" if i % 2 else "A" for i in range(12)],
+})
+denominators = [100., 200., 50.]
+a_values = [60., 60., 40.]
+frames["charts-shares"] = pd.DataFrame({
+    "category": ["A", "B", "C"],
+    "a": [value / total for value, total in zip(a_values, denominators)],
+    "b": [(total - value) / total for value, total in zip(a_values, denominators)],
+    "denominator": denominators,
+})
+observations = pd.Series([.2, .8, 1.5, 2., 2.8, 5.])
+bounds = [0., 1., 3., 6.]
+frames["charts-bins"] = pd.DataFrame({
+    "bin": ["0–1", "1–3", "3–6"],
+    "lower": bounds[:-1], "upper": bounds[1:],
+    "frequency": [float(((observations >= lo) & (observations < hi)).sum())
+                  for lo, hi in zip(bounds[:-1], bounds[1:])],
+})
+summary = []
+for name, values in [("A", [1., 2., 3., 4., 5.]), ("B", [2., 3., 4., 5., 6.])]:
+    series = pd.Series(values)
+    summary.append([name, series.min(), series.quantile(.25), series.median(),
+                    series.quantile(.75), series.max()])
+frames["charts-boxes"] = pd.DataFrame(summary, columns=[
+    "group", "minimum", "q1", "median", "q3", "maximum"])
+values = [60., 30., 10.]
+frames["charts-composition"] = pd.DataFrame({
+    "category": ["A", "B", "C"], "value": values,
+    "share": [value / sum(values) for value in values], "rank": [1., 2., 3.],
+})
+stages = [100., 60., 20.]
+frames["charts-funnel"] = pd.DataFrame({
+    "stage": ["访问", "注册", "购买"], "value": stages,
+    "share": [value / stages[0] for value in stages],
+})
+initial, decreases, increases = 100., -20., 30.
+after_decrease = initial + decreases
+final = after_decrease + increases
+frames["charts-waterfall"] = pd.DataFrame({
+    "step": ["期初", "减少", "增加", "期末"],
+    "change": [initial, decreases, increases, final],
+    "start": [0., initial, after_decrease, 0.],
+    "end": [initial, after_decrease, final, final],
+    "role": ["start", "delta", "delta", "total"],
+})
+frames["charts-precision"] = pd.DataFrame({
+    "label": ["精确值", "缺失", "长小数"],
+    "amount": [Decimal("0.1000"), None, Decimal("12345678901234.5678")],
+})
+root = Path("presentation-example")
+root.mkdir(parents=True, exist_ok=True)
+receipts = [asdict(write_dataset(frame, root / f"{name}.dataset.json"))
+            for name, frame in frames.items()]
+print(json.dumps(receipts, ensure_ascii=False))

package/skills/dsh-data-analysis-presentation/references/examples/write-comparison.py

@@ -0,0 +1,42 @@
+"""仅演示已有数据的比较展示，不是业务分析流程。"""
+
+from dataclasses import asdict
+import json
+from pathlib import Path
+
+import pandas as pd
+
+from dsh_data_analysis_presentation import write_dataset
+
+
+full = pd.DataFrame({
+    "category": ["A", "B", "C"],
+    "baseline": [100, 80, 20],
+    "current": [50, 50, 50],
+})
+full["delta_current_minus_baseline"] = full["current"] - full["baseline"]
+ranked = full.assign(decrease_baseline_minus_current=-full["delta_current_minus_baseline"])
+# 这是 Agent 侧预选：writer 收到两行，truncated=False 不表示原始范围只有两项。
+selected = ranked.sort_values("decrease_baseline_minus_current", ascending=False).head(2)
+other = full.loc[~full["category"].isin(selected["category"])]
+summary = pd.DataFrame([
+    {
+        "scope": scope,
+        "baseline": int(frame["baseline"].sum()),
+        "current": int(frame["current"].sum()),
+        "delta_current_minus_baseline": int(frame["delta_current_minus_baseline"].sum()),
+    }
+    for scope, frame in [("全量", full), ("选中 A、B", selected), ("其他 C", other)]
+])
+
+output_dir = Path("presentation-example")
+output_dir.mkdir(parents=True, exist_ok=True)
+receipts = [
+    asdict(write_dataset(frame, output_dir / filename))
+    for filename, frame in [
+        ("comparison.dataset.json", full),
+        ("comparison-selected.dataset.json", selected),
+        ("comparison-summary.dataset.json", summary),
+    ]
+]
+print(json.dumps(receipts, ensure_ascii=False))

package/skills/dsh-data-analysis-presentation/references/examples/write-computed.py

@@ -0,0 +1,21 @@
+"""演示数据：通过 marivo_python 在当前绑定 Workspace 执行。"""
+
+from dataclasses import asdict
+from decimal import Decimal
+import json
+from pathlib import Path
+
+import pandas as pd
+
+from dsh_data_analysis_presentation import write_dataset
+
+
+frame = pd.DataFrame({
+    "month": ["2026-01", "2026-02", "2026-03"],
+    "count": [12, 18, 9],
+    "amount": [Decimal("120.5000"), None, Decimal("90.0000")],
+})
+output = Path("presentation-example/computed.dataset.json")
+output.parent.mkdir(parents=True, exist_ok=True)
+receipt = write_dataset(frame, output, labels={"month": "月份", "count": "数量", "amount": "金额"})
+print(json.dumps(asdict(receipt), ensure_ascii=False))

package/skills/dsh-data-analysis-presentation/references/examples/write-interaction.py

@@ -0,0 +1,33 @@
+"""全局筛选的合成测试数据；所有汇总均在 Python 中准备，不代表真实业务。"""
+from dataclasses import asdict
+from decimal import Decimal
+import json
+from pathlib import Path
+
+import pandas as pd
+from dsh_data_analysis_presentation import write_dataset
+
+# 日期、集群、查询类别、查询数、失败数。
+raw = [
+    ("mon", "a", "交互查询", 100, 2), ("mon", "a", "批量查询", 50, 1),
+    ("mon", "b", "交互查询", 80, 4), ("mon", "b", "批量查询", 20, 1),
+    ("tue", "a", "交互查询", 120, 3), ("tue", "a", "批量查询", 60, 0),
+    ("tue", "b", "交互查询", 90, 2), ("tue", "b", "批量查询", 30, 2),
+]
+summary, detail = [], []
+for day in ["any", "mon", "tue"]:
+    for cluster in ["any", "a", "b"]:
+        selected = [r for r in raw if (day == "any" or r[0] == day) and (cluster == "any" or r[1] == cluster)]
+        total = sum(r[3] for r in selected)
+        failures = sum(r[4] for r in selected)
+        summary.append({"query_count": total, "failed_count": failures,
+                        "failure_rate": (Decimal(failures) * 100 / Decimal(total)).quantize(Decimal("0.01"))})
+        for category in ["交互查询", "批量查询"]:
+            detail.append({"category": category,
+                           "query_count": sum(r[3] for r in selected if r[2] == category)})
+output_dir = Path("presentation-example")
+output_dir.mkdir(parents=True, exist_ok=True)
+receipts = [asdict(write_dataset(pd.DataFrame(rows), output_dir / filename)) for filename, rows in [
+    ("interaction-summary.dataset.json", summary), ("interaction-detail.dataset.json", detail),
+]]
+print(json.dumps(receipts, ensure_ascii=False))

package/skills/dsh-data-analysis-presentation/references/examples.md

@@ -0,0 +1,44 @@
+# 可改写的完整示例
+
+这些文件都是**演示内容，不是真实业务结果**。先按任务修改，再用普通文件能力写入当前 Workspace；不要在 Skill 安装目录生成分析产物。带 `example-` 的 Session/Artifact 引用仅演示字段位置，使用时替换为当前 Workspace 中实际取得的精确引用。
+
+## 已有 Artifact
+
+读取 [artifact.draft.json](examples/artifact.draft.json)，替换来源引用、列名和范围。草稿直接选择 Artifact 保存数据，不需要先调用 Python helper。示例使用 table，适用于尚未确认数值列是否适合绘图的已有结果。
+
+## computed 数据
+
+使用 [write-computed.py](examples/write-computed.py) 了解 helper 的完整用法。通过 `marivo_python` 在绑定 Runtime 执行改写后的代码；示例本身只有演示数据，可用 `datasources: []`。代码把文件写入 Workspace 的 `presentation-example/computed.dataset.json`，与 [computed.draft.json](examples/computed.draft.json) 中的路径一致。父目录由 Python 示例创建。已有 computed 文件可直接使用，无需重新计算。
+
+文件分析得到的 pandas DataFrame 或原生 DuckDB `.df()` 结果可直接替换示例数据，无需 Marivo datasource 或语义模型。读取指引见 `dsh-data-analysis-files`；草稿正文说明实际文件名、sheet／字段选择及样本或全量范围，`sourceIds` 无 Artifact 时保持空数组，`codeRefs` 关联生成该数据的实际执行引用。
+
+[computed.dataset.json](examples/computed.dataset.json) 是该示例的实际 typed JSON 输出，含精确金额、整数和 null；[computed.draft.json](examples/computed.draft.json) 同时展示单值、趋势、分组、原值表格，未声明来源。需要声明多个 Artifact 来源时参考 [computed-sources.draft.json](examples/computed-sources.draft.json)，只增加声明与关联，不提交转换信息。无法恢复的声明来源由 present 标记 unavailable，不删除声明来隐藏缺失。
+
+将选定草稿写成 `analysis/presentation.draft.json` 后调用：
+
+```json
+{"draft_path":"analysis/presentation.draft.json"}
+```
+
+一个成功的 `marivo_present` 已完成 reader 构建；离线 HTML 在用户下载时生成；根据 receipt 交付，不能把示例数据解释成用户的真实业务结论。
+
+## 比较与抵消项
+
+[write-comparison.py](examples/write-comparison.py) 使用完整演示数据：baseline `[100, 80, 20]`、current `[50, 50, 50]`。它仅演示已有数据的展示，不是业务分析流程。可用 `datasources: []` 运行；写出路径与[比较草稿](examples/comparison.draft.json)一致。
+
+完整[明细](examples/comparison.dataset.json)保留三项原值与 `current - baseline` 的差值 `[-50, -30, +30]`；[Top 2 数据](examples/comparison-selected.dataset.json)按减少量降序预选 A、B，writer 收到两行，因此 `rowCount: 2` 且 `truncated: false`。[汇总](examples/comparison-summary.dataset.json)保留全量、选中项、其他项的两侧原值与净差。
+
+草稿的正文、图和表统一变化方向：全量 200 → 150，净变化 -50（以 baseline 总量 200 为分母，-25%）；两项减少量 80，其他项增加 30，抵消后净减少 50。80 / 50 = 160% 是选中减少量与全量净减少的比值，不能称为覆盖率。示例只证明数值关系，没有原因或联合关系证据。
+
+## 仅展示来源
+
+[全部图形样例](chart-examples.md)另提供 18 类图形、bar/line 变体、预计算数据和探索配置。
+
+[source-only.draft.json](examples/source-only.draft.json) 的 datasets 为空，直接用 source block。替换精确引用后提交即可；无须生成 computed 文件、图或虚构单值。
+
+## 可选全局筛选与动态 KPI
+
+既有 computed 示例不声明筛选，可直接作为固定报告。需要交互时，参考[全局筛选契约](interaction.md)与[双筛选草稿](examples/interaction.draft.json)。
+[生成脚本](examples/write-interaction.py)使用合成测试数据，在 Python 中准备日期 × 集群的九个组合，每个维度均含“全部”。
+脚本生成[指标数据](examples/interaction-summary.dataset.json)和[类别数据](examples/interaction-detail.dataset.json)，路径与草稿一致。
+完整范围为 550 次查询、15 次失败；周一甲集群为 150 次查询、3 次失败、2.00% 失败率。区域外指标始终为 550，区域内三个 KPI、图表及表格一起切换。

package/skills/dsh-data-analysis-presentation/references/export-html.md

@@ -0,0 +1,7 @@
+# 导出完整 HTML
+
+用户要求离线 HTML 文件时，调用 `marivo_export_html({"report_id":"实际 Report ID","build_id":"实际 Build ID","output_path":"reports/analysis.html"})`。从成功 receipt 或已读取报告取得身份；基于固定报告上下文时始终传 `build_id`，仅在用户要求当前版本时省略。路径相对于当前 Workspace，必须为新的 `.html` 文件，可自动创建父目录；已有文件不会覆盖，不能写入 `.dsh-data-analysis`。
+
+成功后必须使用返回的实际 `path` 调用原生 `present({ files: [{ path, description: "离线 HTML 报告" }] })`，再给出最终回复；不把 JSON 路径当成 HTML，也不以仅提及路径代替文件交付。若当前 Agent 未提供 `present`，如实报告已导出文件和交付能力缺失，不宣称已生成文件卡片。
+
+导出复用已保存快照，不访问 Python 或数据源，不更新报告，不包含未保存编辑或临时筛选。需要先修改内容时，先完成报告保存再导出对应 Build。导出不依赖发布配置，也不生成外部 URL；完整报告保留全部已保存筛选组合，不是数据权限隔离副本。

package/skills/dsh-data-analysis-presentation/references/interaction.md

@@ -0,0 +1,56 @@
+# 全局筛选与动态指标
+
+## 何时启用
+
+由 Agent 根据报告问题和数据条件决定；仅有固定结论、单图或不能形成共同筛选范围时省略 `interaction`。reader 不根据 dataset 自动生成筛选，也不推断跨 dataset 的关系。
+
+需要启用时，将所有受影响的 metric/chart/table 连续放入 `blocks`。固定正文、固定 KPI 和 source 放在区外；区内只能有共同响应的组件。每个筛选字段固定，读者对每个字段选择一个值或“全部”，多个字段共同决定唯一组合。没有局部数据行筛选入口。
+
+## 声明
+
+Draft schemaVersion 2、Document schemaVersion 3 均支持以下可选字段：
+
+```typescript
+interaction?: {
+  title: string
+  blockIds: string[]
+  filters: {
+    id: string
+    label: string
+    allOptionId: string
+    options: { id: string; label: string }[]
+  }[]
+  slices: {
+    selection: Record<string, string>
+    datasets: { datasetId: string; rowIndices: number[] }[]
+  }[]
+}
+```
+
+`blockIds` 唯一、按正文顺序排列且连续。一份报告只有一个区域。`filters` 的顺序决定控件顺序；每个字段至少包含“全部”和一个具体选项。`allOptionId` 明确指出“全部”，显示标签使用“全部”；普通业务值或标签 `all` 没有特殊含义。选项 ID 是稳定标识，不是 reader 执行的表达式或字段名。
+
+每个 `selection` 为全部 filter ID 到 option ID 的完整映射。每一种可选组合必须恰好有一个 slice，含多个字段均为“全部”及部分字段为“全部”的组合。初始、重置、重新打开、打印和禁用脚本均采用全“全部”组合。
+
+`datasets` 必须覆盖区域内全部组件实际使用的数据集，包括 chart 的全部 `preparedViews`。每个 dataset 恰好一个绑定；`rowIndices` 为该 dataset 原始快照的零起始行索引，不是排序后或分页后的索引。可以跨组合复用行，但同一绑定不能重复索引。表格与图表允许 `[]`，表示明确准备的空结果；不能用遗漏 dataset 代替空结果。
+
+## 动态 KPI
+
+固定 metric 继续使用 `rowIndex`。区域内 metric 改用 `rowSelection: "slice"`，与 `rowIndex` 互斥：
+
+```json
+{"id":"count","kind":"metric","datasetId":"summary","columnId":"query_count","rowSelection":"slice","label":"当前查询数"}
+```
+
+每种组合对该 dataset 必须唯一选择一行；同一行可包含多个 KPI 的不同列。不要将需要多行的 chart/table 和动态 metric 强行绑定到同一个 dataset。无数据指标显式准备 nullable 单元格 `null`，与数值零区分。
+
+先在分析阶段按业务口径计算总计、去重、比率、排名、占比与分母，再构造各组合的展示数据。尤其“全部”必须选择预计算的全量结果，不能把汇总行与明细行一起选择，或期待 reader 累加各组选项。
+
+既有行数、dataset 数、Draft/Document/HTML 字节预算仍适用。组合过多时减少字段或选项；不扩张预算、不静默截断、不回退到全量值。Draft 检查结构与引用，投影后检查实际行索引与 KPI 唯一性，失败按诊断修正。
+
+## 阅读与编辑
+
+区域边界清楚区分固定内容；区域内指标、图表、表格、来源数据预览共同切换。复制上下文包含筛选条件、原始行索引和当前指标值，来源 identity 不变。
+
+宿主编辑可改现有呈现字段、区域内部顺序和删除组件，不能跨区域移动或编辑筛选声明。删除最后一个交互组件会移除声明，撤销可恢复。当前选择不保存，不进入下载或浏览器存储；保存的声明和全部组合仍包含在离线 HTML 中。
+
+参见[双筛选完整示例](examples.md)。示例为合成数据，不能当成真实业务结果。

package/skills/dsh-data-analysis-presentation/references/narrative.md

@@ -0,0 +1,37 @@
+# 叙事与证据检查
+
+报告、看板及比较型展示在写草稿前读取本页。按用户问题选信息密度，不要求固定章节、图数或 KPI 数量；以下检查用于表达已有分析，不代替 Runtime Skill 的分析与质量契约。
+
+## 保持问题与比较范围
+
+逐项对应用户的问题与比较范围：每组比较明确两侧的时间或群体、粒度、单位、方向和比例分母。不同基准分别回答，不能用一个成功比较替代另一个；某分支未取得数据时，在正文说明已回答范围、尚缺证据及其影响。
+
+以 `current - baseline` 表示变化时，表头、图例和正文统一该方向；若另用 `baseline - current` 表示减少量，明确命名。发布前从原值核对差值、比例、全量合计与余项，核对文字中的大小、方向和量级；占比的分母不能在正文中悄然换成另一个比较或筛选后子集。
+
+## 让结论匹配证据
+
+区分观测事实、数值贡献分解、解释与待验证假设。分解能说明哪些项贡献了净变化；原因、角色推断及“排除某原因”的结论需要相应证据，未观察到不能直接当成不存在。两个维度各自的边际分布不能证明它们的联合关系；需要交叉证据才能描述组合群体或共同驱动。
+
+把实质限制落实到对应结论的范围和措辞，不能只在末尾加免责声明后仍作强断言。证据不足时交付已支持的答案和明确的未决问题，不让展示文案补造缺失分析。
+
+## 说明选取与未展示部分
+
+Top N、过滤或预聚合必须说明选取规则、排序方向与覆盖范围。Agent 在传给 writer 前选取的子集，与 writer 因预算截断不同；`rowCount` 和 `truncated` 只描述 writer 收到的输入，`truncated: false` 不证明业务数据全量。
+
+当结论涉及全量归因，保留可核对的全量基准和未展示项的净贡献，校验“展示项净变化 + 其他项净变化 = 全量净变化”。部分减少项之和可能超过全量净减少，因为其他项抵消；不要将局部和称为总差或把它与全量净差的比值当成覆盖率。可改写的[比较示例](examples.md#比较与抵消项)展示原值、净差、减少量和抵消量的关系。
+
+## 报告
+
+先给已经得到的主要结论，再放最能支撑它的数据和比较。结论尚未成立时说明现有证据和缺口，不用图形复杂度替代分析。
+
+正文使用 markdown，关键单值用 metric，变化或比较用 line/bar，需要核对原值时用 table。各图表、表格和指标的数据源入口提供精确 Artifact 和公开事实，报告末尾默认不再添加独立的数据源段落或 `source` block；用户明确要求独立来源面板时再添加。保留 dataset 的来源声明与关联；只为当前问题读取必要 Finding，不强制遍历整个 SessionGraph。
+
+## 看板
+
+先列要回答的运营问题，再选已计算的关键指标、趋势或分组比较。对比区间、分母、单位与目标如果未从分析取得，就明确缺失；不要让展示层补造。metric 指向一格已有数据，不自动计算总计、达成率或同比。
+
+用 blocks 顺序表达优先级，适配布局由 reader 决定。这是生成时的数据快照；当前范围、生成时间和实质限制应让读者可见。新的范围或刷新需要新分析和一次新的 present。
+
+## 交付说明
+
+简要回答问题，附 receipt 的打开/下载入口或 headless 精确路径。说明会影响结论的截断、来源 unavailable、近似绘图或未完成验证。present 的结构与来源读取成功不等于统计正确、业务口径正确或 computed 转换已获验证；只报告已取得的证据。

package/skills/dsh-data-analysis-presentation/references/publishing.md

@@ -0,0 +1,3 @@
+# 发布报告链接
+
+当用户明确要求发布到对象存储且实时工具中存在 `marivo_publish_report` 时，用已保存 receipt 的 `report_id` 和 `build_id` 调用。成功后返回工具确认的 URL；凭据缺失时引导用户到“数据源与凭证 → 报告发布凭证”配置，不索取或传递密钥。上传结果未确认不宣称成功；可重试同一保存版本。开启发布时，在线报告菜单将完整报告和当前视图的 HTML 下载替换为上传；当前筛选视图由用户在阅读器发布，不通过 Tool 猜测。