@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

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

@@ -0,0 +1,55 @@
+# 图形配置与数值表达
+
+所有图形共享 `datasetId`、`chart`、`x`、`y`、`numericMode`。字段绑定使用列 ID，名称和单位来自 dataset；图前说明用 markdown。reader 保留输入行顺序，统计计算先在分析阶段完成。
+
+## 图形选择与字段
+
+| chart | x / y | bindings 与数据要求 |
+| --- | --- | --- |
+| `line`、`area` | 有序 x，多列 y | 无；固定 monotone |
+| `stackedArea` | 有序 x，同单位多列 y | 无；先对齐系列，不补零 |
+| `sparkline` | 有序 x，单列 y | 无；紧凑趋势 |
+| `bar`、`horizontalBar` | 类别 x，单列或多列 y | 无；单系列或并列比较 |
+| `stackedBar`、`horizontalStackedBar` | 类别 x，同单位多列 y | 无；普通堆叠 |
+| `stackedBar100`、`horizontalStackedBar100` | 类别 x，预计算比例 y | `denominator`：分母列；比例为 0–1 |
+| `histogram` | 区间标签 x，频数 y（单列） | `binStart`、`binEnd`：已排序、不重叠的区间边界 |
+| `boxPlot` | 分组 x，中位数 y（单列） | `minimum`、`q1`、`q3`、`maximum`：五数摘要 |
+| `scatter` | 数值 x，数值 y（单列） | 可选 `size`、`label`、`color`：点大小、标签、分类字段 |
+| `heatmap` | 行类别 x，矩阵各列 y | 无；每行是已准备矩阵行 |
+| `pie` | 切片标签 x，原值 y（单列） | `share`：预计算占比；默认环形 |
+| `leaderboard` | 类别 x，数值 y（单列） | `rank`：预计算排名；先确定排序和 Top N |
+| `funnel` | 有序阶段 x，原值 y（单列） | `share`：相对于明确首阶段分母的预计算占比 |
+| `waterfall` | 有序步骤 x，变化量／锚点值 y（单列） | `start`、`end`：已有坐标；`role` 列取 start、delta、subtotal、total |
+
+`bindings` 的值都是同一 dataset 的列 ID，不是数值或公式。例如箱线图：
+
+```json
+{"id":"distribution","kind":"chart","datasetId":"summary","chart":"boxPlot","x":"group","y":["median"],"numericMode":"exact","bindings":{"minimum":"min","q1":"p25","q3":"p75","maximum":"max"}}
+```
+
+堆叠系列与 heatmap 必须同单位；普通多系列图的不同单位分图展示。没有双轴或单位推断。100% 堆叠的分母为零／null 时比例也必须 null。pie/funnel 仅绑定预计算 share，作者须说明分母；share 范围为 [0,1]，pie 完整快照的已知 share 总和不超过 1，允许不足 1。null share 不绘制切片；share 已知但原值缺失时保留该角度空位。瀑布 delta 步的 end - start 必须等于 y；锚点从零绘制，不重新累计。reader 不把缺失值补为零，不修正不合法统计量。
+
+## 受限选项
+
+`options` 只接受以下声明，各类型仅接受适用选项：
+
+- `showPoints: "auto" | "always" | "never"`：趋势图数据点，默认 auto 保留孤立观测。
+- `series`：以 y 列 ID 为 key，值可有 `lineStyle: "solid" | "dashed" | "dotted"` 与 `role: "actual" | "baseline" | "target" | "forecast" | "plan" | "comparison"`。计划／目标／基线／预测默认为中性虚线，显式线型优先。
+- `valueLabels: "none" | "auto" | "all"`：数值标签；原值始终保留在 tooltip。
+- `referenceLines: [{"axis":"y","value":20,"label":"参考值"}]`：数值轴参考线。axis 是物理轴；横向柱形和箱线图的数值轴为 x。pie、funnel、heatmap、sparkline 不提供参考线。普通多系列图若含不同单位，该系列数值轴不接受参考线，须为各单位分别声明图表或已准备视图；scatter、histogram 的两个独立数值轴可各自设置参考线。
+
+不写 linear/step、任意配置、前端 aggregate 或时间分粒度。
+
+## 探索与已准备视图
+
+chart 可有 `preparedViews`：每项包含唯一 `id`、说明性 `label` 和完整 `datasetId`、`chart`、`x`、`y`、`numericMode` 及适用 bindings/options。它不包含 kind，不嵌套 preparedViews；dataset 必须已在草稿声明。
+
+普通图形可以选择当前数值列和适用类型。需要另一组分箱、分位数、分母或累计值时，先准备 dataset，再声明视图。reader 不按列名猜统计角色，不能使用的类型显示缺少的数据。
+
+cell 菜单“探索图表”提供图形、字段、系列、方向／模式、线型、分类过滤和恢复原图。过滤与显隐只改变当前可见内容，原始排名、占比和分母保持不变。来源预览和复制上下文跟随当前视图；下载和打印使用原始快照。重新打开恢复作者配置，不保存探索状态。
+
+## 精度与叙事
+
+`exact` 适用于 float64 和 JS 安全整数范围内的 int64。decimal 或较大 int64 只用表格，或显式 `approximate` 绘图；所有数值坐标必须有限。tooltip、来源预览和静态表格保留原始精确文本。null 是缺失，不是 0；空数据展示空状态。
+
+比较图先读[叙事与证据检查](narrative.md)，核对字段、方向、单位、分母、范围与正文一致。Top N 保留选取范围与其他项贡献；截断数据不代表全量，绘制成功不证明计算或因果结论成立。完整示例见[图形样例](chart-examples.md)。

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

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": 2,
+  "title": "演示：已有 Artifact 表格",
+  "datasets": [
+    {
+      "id": "result",
+      "kind": "artifact",
+      "sourceId": "analysis",
+      "rowLimit": 100,
+      "columns": ["region", "revenue"]
+    }
+  ],
+  "sources": [
+    {
+      "id": "analysis",
+      "ref": {
+        "sessionId": "example-session",
+        "artifactRef": "example-artifact"
+      }
+    }
+  ],
+  "blocks": [
+    {
+      "id": "scope",
+      "kind": "markdown",
+      "text": "演示草稿：请替换实际来源、列名和分析范围。展示最多 100 行，不据此声称全量总计。"
+    },
+    {
+      "id": "values",
+      "kind": "table",
+      "datasetId": "result",
+      "columns": ["region", "revenue"]
+    }
+  ],
+  "locale": "zh-CN"
+}

package/skills/dsh-data-analysis-presentation/references/examples/charts-bins.dataset.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "columns": [
+    {
+      "id": "bin",
+      "label": "bin",
+      "type": "string",
+      "nullable": false
+    },
+    {
+      "id": "lower",
+      "label": "lower",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "upper",
+      "label": "upper",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "frequency",
+      "label": "frequency",
+      "type": "float64",
+      "nullable": false
+    }
+  ],
+  "rows": [["0–1", 0, 1, 2], ["1–3", 1, 3, 3], ["3–6", 3, 6, 1]],
+  "rowCount": 3,
+  "limit": 5000,
+  "truncated": false
+}

package/skills/dsh-data-analysis-presentation/references/examples/charts-boxes.dataset.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": 1,
+  "columns": [
+    {
+      "id": "group",
+      "label": "group",
+      "type": "string",
+      "nullable": false
+    },
+    {
+      "id": "minimum",
+      "label": "minimum",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "q1",
+      "label": "q1",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "median",
+      "label": "median",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "q3",
+      "label": "q3",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "maximum",
+      "label": "maximum",
+      "type": "float64",
+      "nullable": false
+    }
+  ],
+  "rows": [["A", 1, 2, 3, 4, 5], ["B", 2, 3, 4, 5, 6]],
+  "rowCount": 2,
+  "limit": 5000,
+  "truncated": false
+}

package/skills/dsh-data-analysis-presentation/references/examples/charts-composition.dataset.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "columns": [
+    {
+      "id": "category",
+      "label": "category",
+      "type": "string",
+      "nullable": false
+    },
+    {
+      "id": "value",
+      "label": "value",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "share",
+      "label": "share",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "rank",
+      "label": "rank",
+      "type": "float64",
+      "nullable": false
+    }
+  ],
+  "rows": [["A", 60, 0.6, 1], ["B", 30, 0.3, 2], ["C", 10, 0.1, 3]],
+  "rowCount": 3,
+  "limit": 5000,
+  "truncated": false
+}

package/skills/dsh-data-analysis-presentation/references/examples/charts-funnel.dataset.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": 1,
+  "columns": [
+    {
+      "id": "stage",
+      "label": "stage",
+      "type": "string",
+      "nullable": false
+    },
+    {
+      "id": "value",
+      "label": "value",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "share",
+      "label": "share",
+      "type": "float64",
+      "nullable": false
+    }
+  ],
+  "rows": [["访问", 100, 1], ["注册", 60, 0.6], ["购买", 20, 0.2]],
+  "rowCount": 3,
+  "limit": 5000,
+  "truncated": false
+}

package/skills/dsh-data-analysis-presentation/references/examples/charts-precision.dataset.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "columns": [
+    {
+      "id": "label",
+      "label": "label",
+      "type": "string",
+      "nullable": false
+    },
+    {
+      "id": "amount",
+      "label": "amount",
+      "type": "decimal",
+      "nullable": true
+    }
+  ],
+  "rows": [["精确值", "0.1000"], ["缺失", null], ["长小数", "12345678901234.5678"]],
+  "rowCount": 3,
+  "limit": 5000,
+  "truncated": false
+}

package/skills/dsh-data-analysis-presentation/references/examples/charts-series.dataset.json

@@ -0,0 +1,58 @@
+{
+  "schemaVersion": 1,
+  "columns": [
+    {
+      "id": "period",
+      "label": "period",
+      "type": "string",
+      "nullable": false
+    },
+    {
+      "id": "a",
+      "label": "a",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "b",
+      "label": "b",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "coordinate",
+      "label": "coordinate",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "volume",
+      "label": "volume",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "segment",
+      "label": "segment",
+      "type": "string",
+      "nullable": false
+    }
+  ],
+  "rows": [
+    ["2026-01", 12, 8, 1, 10, "A"],
+    ["2026-02", 18, 11, 2, 20, "B"],
+    ["2026-03", 15, 10, 3, 30, "A"],
+    ["2026-04", 24, 14, 4, 40, "B"],
+    ["2026-05", 19, 13, 5, 50, "A"],
+    ["2026-06", 30, 17, 6, 60, "B"],
+    ["2026-07", 28, 19, 7, 70, "A"],
+    ["2026-08", 34, 18, 8, 80, "B"],
+    ["2026-09", 31, 22, 9, 90, "A"],
+    ["2026-10", 42, 25, 10, 100, "B"],
+    ["2026-11", 39, 24, 11, 110, "A"],
+    ["2026-12", 45, 28, 12, 120, "B"]
+  ],
+  "rowCount": 12,
+  "limit": 5000,
+  "truncated": false
+}

package/skills/dsh-data-analysis-presentation/references/examples/charts-shares.dataset.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "columns": [
+    {
+      "id": "category",
+      "label": "category",
+      "type": "string",
+      "nullable": false
+    },
+    {
+      "id": "a",
+      "label": "a",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "b",
+      "label": "b",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "denominator",
+      "label": "denominator",
+      "type": "float64",
+      "nullable": false
+    }
+  ],
+  "rows": [["A", 0.6, 0.4, 100], ["B", 0.3, 0.7, 200], ["C", 0.8, 0.2, 50]],
+  "rowCount": 3,
+  "limit": 5000,
+  "truncated": false
+}

package/skills/dsh-data-analysis-presentation/references/examples/charts-waterfall.dataset.json

@@ -0,0 +1,44 @@
+{
+  "schemaVersion": 1,
+  "columns": [
+    {
+      "id": "step",
+      "label": "step",
+      "type": "string",
+      "nullable": false
+    },
+    {
+      "id": "change",
+      "label": "change",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "start",
+      "label": "start",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "end",
+      "label": "end",
+      "type": "float64",
+      "nullable": false
+    },
+    {
+      "id": "role",
+      "label": "role",
+      "type": "string",
+      "nullable": false
+    }
+  ],
+  "rows": [
+    ["期初", 100, 0, 100, "start"],
+    ["减少", -20, 100, 80, "delta"],
+    ["增加", 30, 80, 110, "delta"],
+    ["期末", 110, 0, 110, "total"]
+  ],
+  "rowCount": 4,
+  "limit": 5000,
+  "truncated": false
+}