@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.0

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

@@ -0,0 +1,93 @@
+# 文件分析示例
+
+以下代码通过 `marivo_python` 执行，两例都使用 `datasources: []`。将 `path` 替换为 Harness 提供的附件可读路径或用户指定的 Workspace 文件，列名按实际结构调整。
+
+## pandas
+
+```python
+import pandas as pd
+
+path = "/actual/readable/file.csv"
+frame = pd.read_csv(path)
+result = frame.groupby("category", dropna=False)["amount"].sum().reset_index()
+print(result.to_string(index=False))
+```
+
+JSON、JSON Lines 和 Parquet 可分别使用 `pd.read_json`、`pd.read_json(..., lines=True)` 和 `pd.read_parquet`；读取选项由实际文件决定。默认 Runtime 未提供 `openpyxl`，`.xlsx` 可用下例的 DuckDB reader 后转成 DataFrame。
+
+## 原生 DuckDB
+
+```python
+import duckdb
+
+path = "/actual/readable/file.csv"
+with duckdb.connect(":memory:") as con:
+    result = con.execute(
+        "SELECT category, SUM(amount) AS amount "
+        "FROM read_csv_auto(?) GROUP BY category ORDER BY amount DESC LIMIT 20",
+        [path],
+    ).df()
+print(result.to_string(index=False))
+```
+
+按文件改用 `read_json_auto(?)`、`read_parquet(?)` 或 `read_xlsx(?)`。`.xlsx` 的指定工作表可用 `read_xlsx(?, sheet = ?)` 并传入路径与 sheet 名；首次加载 `excel` 扩展需要获取官方扩展。参数避免将路径或 sheet 名直接拼入 SQL；reader 支持 glob，含通配符的文件名需先确认只命中目标文件。
+
+原生连接支持同一调用内的多条 SQL 和临时表，无需另建 Marivo datasource。需要交互表格或报告时，使用展示 Skill 的 computed 示例；写入当前 Workspace，`sourceIds` 可为空，dataset 的 `codeRefs` 使用本次成功执行返回的实际引用。
+
+## 导出 CSV 或 JSON
+
+仅在用户要求实际文件时执行；`result` 是本次调用内已计算的 DataFrame。使用当前绑定 Workspace 的实际路径，不把附件路径当输出目录。
+
+```python
+from pathlib import Path
+
+output_dir = Path("/actual/workspace/exports")
+output_dir.mkdir(parents=True, exist_ok=True)
+csv_path = output_dir / "summary.csv"
+result.to_csv(csv_path, index=False)
+# 用户要求 JSON 时可改为：
+# json_path = output_dir / "summary.json"
+# result.to_json(json_path, orient="records", force_ascii=False)
+print(str(csv_path.resolve()))
+```
+
+执行成功后，将实际输出路径交给当前 Harness 原生 `present`（参数以当前工具契约为准）：
+
+```json
+{"files":[{"path":"/actual/workspace/exports/summary.csv","description":"按类别汇总的金额"}]}
+```
+
+无需加载展示 Skill 或调用 `marivo_present`。只交付用户要求的文件；当前没有 `present` 时报告已生成文件的准确路径和原生交付能力缺失。
+
+## 导出 PNG
+
+不要假设 Runtime 安装了 matplotlib 或 Pillow。以下标准库示例生成无文字的简单条形缩略图，适用于用户明确要求 PNG；颜色、顺序、数值和分析范围应在回复中说明。复杂交互图表使用展示 Skill。
+
+```python
+from pathlib import Path
+import struct
+import zlib
+
+# 替换为本次分析得出的非负数值；依次为 A、B、C。
+values = [11, 23, 37]
+width, height = 240, 120
+pixels = bytearray([255] * (width * height * 3))
+for index, value in enumerate(values):
+    bar_height = round(value / max(values, default=1) * 100) if max(values, default=0) else 0
+    for y in range(height - 10 - bar_height, height - 10):
+        for x in range(20 + index * 70, 60 + index * 70):
+            offset = (y * width + x) * 3
+            pixels[offset:offset + 3] = bytes((45, 110, 210))
+def chunk(kind, data):
+    return struct.pack(">I", len(data)) + kind + data + struct.pack(">I", zlib.crc32(kind + data))
+rows = b"".join(b"\x00" + pixels[y * width * 3:(y + 1) * width * 3] for y in range(height))
+png = (b"\x89PNG\r\n\x1a\n"
+       + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0))
+       + chunk(b"IDAT", zlib.compress(rows)) + chunk(b"IEND", b""))
+output = Path("/actual/workspace/exports/amounts.png")
+output.parent.mkdir(parents=True, exist_ok=True)
+output.write_bytes(png)
+print(str(output.resolve()))
+```
+
+成功后通过原生 `present` 交付实际 PNG 路径。文件生成失败不调用 `present`；声明失败仅修复交付，不重新计算。

package/skills/dsh-data-analysis-presentation/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: dsh-data-analysis-presentation
-description: 将 Marivo 分析结果或已有 Workspace 数据展示为图表、表格、报告、看板或来源面板，并一次交付可打开的 reader 与离线 HTML。适用于需要可视展示或保存分析快照的请求；普通事实问答使用文字。
+description: 将 Marivo 分析结果或已有 Workspace 数据展示为图表、表格、报告、看板或来源面板，并交付在右侧 tab 打开的 reader。适用于需要可视展示或保存分析快照的请求；普通事实问答使用文字。
 ---
 
 # Marivo 分析展示
 
-用一份 JSON 草稿组织已有结果，再调用一次 `marivo_present` 完成检查、Web 阅读与离线 HTML。单图、表格、报告和看板使用同一流程。
+用 JSON 草稿组织已有结果，调用 `marivo_present` 保存并打开阅读器。
 
 ## 从问题到交付
 
-1. 先确定问题、数据范围和要表达的结论。需要新分析时，按需使用当前 Runtime 挂载的 `marivo-analysis`、`marivo-semantic` 与 `marivo_help` 了解公开能力；通过 `marivo_python` 执行，声明本次精确 datasource names，凭据准备由该调用完成。已有结果可直接展示，无需先激活分析 Skill。此 Skill 只定义展示，不代替 live Help 或 Marivo 的分析、质量与 lineage 契约。
-2. 选数据。已有可恢复 Artifact 用 owning `sessionId` + `artifactRef` 引用，分别取实际 `session.id` 和 `artifact.ref`，不要从 Session 名称或日志标题猜测；必要时加 `findingId`，不重复导出同一份数据。需要计算后的 DataFrame 时，在绑定 Runtime 的 Python 中用 `dsh_data_analysis_presentation.write_dataset(frame, path)` 写纯 JSON；中文报告通过 `labels={列名: 中文展示名}` 设置表头、图例和 tooltip，Draft 字段绑定仍使用原列名，未映射列沿用列名。computed 的来源只在草稿声明，可为零个或多个 Artifact；不要求转换代码、字段映射、hash 或输入输出证明。来源 Quality/issues 仍属于原 Artifact，不证明 computed 的计算正确。
+1. 先确定问题、数据范围和要表达的结论。报告语言优先遵循用户明确要求，否则根据当前问题和上下文决定；不以 DSH 系统界面语言作为默认。Draft 必须填写 `schemaVersion: 2` 与 `locale: "zh-CN"` 或 `"en-US"`，按该语言编写标题、正文、图表及字段展示名。直接分析文件时使用 `dsh-data-analysis-files`；涉及 Marivo 分析语义或建模时，按需使用 `marivo-analysis`、`marivo-semantic` 与 `marivo_help`。通过 `marivo_python` 执行：纯本地 pandas／原生 DuckDB 使用 `datasources: []`，访问 Marivo datasource 才声明其精确名称。已有结果可直接展示，无需先激活分析 Skill。此 Skill 只定义展示，不代替 Marivo 的分析、质量与 lineage 契约。
+2. 选数据。已有可恢复 Artifact 用 owning `sessionId` + `artifactRef` 引用，分别取实际 `session.id` 和 `artifact.ref`，不要从 Session 名称或日志标题猜测；必要时加 `findingId`，不重复导出同一份数据。需要计算后的 DataFrame 时，在绑定 Runtime 的 Python 中用 `dsh_data_analysis_presentation.write_dataset(frame, path)` 写纯 JSON；通过 `labels={列名: 报告语言展示名}` 设置表头、图例和 tooltip，Draft 字段绑定仍使用原列名，未映射列沿用列名。computed 的来源只在草稿声明，可为零个或多个 Artifact；文件分析在正文说明文件与读取范围，关联实际 `codeRef`，不构造 Artifact 来源。不要求转换代码、字段映射、hash 或输入输出证明。来源 Quality/issues 仍属于原 Artifact，不证明 computed 的计算正确。
 3. 根据报告需要决定是否启用全局筛选；默认不添加。需要按维度交互时，先读 [全局筛选与动态指标](references/interaction.md)，准备每种单选组合（含全部）的 KPI、图表与表格结果，全部受影响组件放进同一区域。缺少组合数据就减少筛选或回到分析阶段准备，不交付局部响应的全局控件。写草稿前读 [schema 与文件边界](references/schema.md)；报告、看板及比较型展示还必须先读 [叙事与证据检查](references/narrative.md)，按需读 [图形配置](references/charts.md)与[可改写示例](references/examples.md)。逐项对应用户问题，确定各比较的两侧、方向、分母及尚缺分支；核对原值、差值、比例、合计和余项，让正文结论与证据强度一致。用普通文件能力在当前 Workspace 写草稿；草稿与 computed 路径都相对于 Workspace 根目录。来源事实与 unavailable 状态由 builder 读取，不手填。
-4. 手写 computed JSON 时可先运行 `dsh-data-analysis-presentation-lint analysis/presentation.draft.json`，检查草稿结构和 computed 文件；int64 用精确字符串（如 `"42"`）。静态预检不验证 Artifact、codeRefs 或最终渲染，详见 [静态预检](references/schema.md#草稿静态预检)。分析和草稿就绪后调用 `marivo_present({"draft_path":"analysis/presentation.draft.json"})`。成功已同时生成 `presentation.json` 与 `index.html`。失败按诊断的 `code`、`path`、原因和建议修正草稿或数据，再重试；没有成功 receipt 就不宣称交付完成。缺少 Artifact 保存数据时报告缺失，不为完成展示自动重新查询、observe 或 revalidate。修复展示错误也不自动重放分析。
-5. 交付主要结论、未完成分支、实质限制和 receipt 的打开/下载入口；headless 时给出 receipt 的精确文件路径。computed 来源不可恢复时如实保留 unavailable；区分 Agent 预筛选与 writer 截断，局部展示不能冒充全量总计或排名。只声明实际做过的浏览器检查。用户可在宿主阅读器编辑呈现并保存同一报告，支持 cell 移动、删除（可删空）及撤销。原卡片重开时解析当前保存构建；固定 Build 链接和离线 HTML 保留原快照。筛选选择只是临时展示，不进入保存或下载；动态指标选取已准备的组合结果，reader 不重算。
+4. 手写 computed JSON 时可先运行 `dsh-data-analysis-presentation-lint analysis/presentation.draft.json`，检查草稿结构和 computed 文件；int64 用精确字符串（如 `"42"`）。静态预检不验证 Artifact、codeRefs 或最终渲染，详见 [静态预检](references/schema.md#草稿静态预检)。分析和草稿就绪后调用 `marivo_present({"draft_path":"analysis/presentation.draft.json"})`。成功只保存 `presentation.json` 并打开右侧 tab；普通展示不额外生成 HTML 或挂报告 block。用户可在阅读器按配置发布或下载 HTML。失败按诊断的 `code`、`path`、原因和建议修正草稿或数据，再重试；没有成功 receipt 就不宣称交付完成。缺少 Artifact 保存数据时报告缺失，不为完成展示自动重新查询、observe 或 revalidate。修复展示错误也不自动重放分析。
+5. 交付主要结论、未完成分支、实质限制和 报告已在右侧 tab 打开的简短说明；headless 时给出 receipt 的精确文件路径。computed 来源不可恢复时如实保留 unavailable；区分 Agent 预筛选与 writer 截断，局部展示不能冒充全量总计或排名。只声明实际做过的浏览器检查。用户可在宿主阅读器编辑呈现并保存同一报告，支持 cell 移动、删除（可删空）及撤销。报告重开时解析当前保存构建；固定 Build 链接和离线 HTML 保留原快照。筛选选择只是临时展示，不进入保存或下载；动态指标选取已准备的组合结果，reader 不重算。
 
 ## 修改已有报告
 
@@ -22,3 +22,7 @@ description: 将 Marivo 分析结果或已有 Workspace 数据展示为图表、
 ## 来源追问
 
 简短来源问题可通过 Marivo 公开 Python API 回答。需要可视来源面板时，使用 `datasets: []` 与 `source` block，无需制造图表或 dataset。需要保留生成脚本时，将成功 `marivo_python` 返回的 `codeRef` 写入相应 dataset 的 `codeRefs`，详见 [生成代码](references/schema.md#生成代码)；Artifact 执行 SQL 自动读取，执行记录与数据集的关联不构成计算正确性证明。打开、下载和来源展开读取生成时保存的快照；用户要求新范围、刷新或进一步分析时回到普通分析流程。
+
+用户要求发布对象存储链接时，按[发布报告](references/publishing.md)使用实时披露的 `marivo_publish_report`。
+
+离线 HTML 文件按[导出与原生交付](references/export-html.md)处理：`marivo_export_html` 成功后调用 `present`。

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

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

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

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "title": "图表与探索样例（全部为合成演示数据）",
   "datasets": [
     {
@@ -388,5 +388,6 @@
       "y": ["amount"],
       "numericMode": "approximate"
     }
-  ]
+  ],
+  "locale": "zh-CN"
 }

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

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "title": "演示：减少项与其他项抵消后的净变化",
   "datasets": [
     {
@@ -75,5 +75,6 @@
       "datasetId": "full",
       "columns": ["category", "baseline", "current", "delta_current_minus_baseline"]
     }
-  ]
+  ],
+  "locale": "zh-CN"
 }

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

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "title": "演示：computed 的多个声明来源",
   "datasets": [
     {
@@ -20,7 +20,10 @@
     },
     {
       "id": "accounts",
-      "ref": { "sessionId": "example-accounts-session", "artifactRef": "example-accounts-artifact" }
+      "ref": {
+        "sessionId": "example-accounts-session",
+        "artifactRef": "example-accounts-artifact"
+      }
     }
   ],
   "blocks": [
@@ -29,7 +32,11 @@
       "kind": "markdown",
       "text": "演示草稿：来源引用需替换为实际引用。声明多个 Artifact 不表示 computed 计算已经过验证；不可恢复的来源由 reader 如实显示。"
     },
-    { "id": "values", "kind": "table", "datasetId": "quarter" },
-    { "id": "sources", "kind": "source", "sourceIds": ["sales", "accounts"] }
-  ]
+    {
+      "id": "values",
+      "kind": "table",
+      "datasetId": "quarter"
+    }
+  ],
+  "locale": "zh-CN"
 }

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

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "title": "演示：季度已有数量与精确金额",
   "datasets": [
     {
@@ -53,5 +53,6 @@
       "datasetId": "quarter",
       "columns": ["month", "count", "amount"]
     }
-  ]
+  ],
+  "locale": "zh-CN"
 }

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

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "title": "查询运行概览 · 全局筛选演示",
   "sources": [],
   "datasets": [
@@ -274,5 +274,6 @@
         ]
       }
     ]
-  }
+  },
+  "locale": "zh-CN"
 }

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

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

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

@@ -10,6 +10,8 @@
 
 使用 [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` 后调用：
@@ -18,7 +20,7 @@
 {"draft_path":"analysis/presentation.draft.json"}
 ```
 
-一个成功的 `marivo_present` 已完成 reader 与离线 HTML 构建；根据 receipt 交付，不能把示例数据解释成用户的真实业务结论。
+一个成功的 `marivo_present` 已完成 reader 构建；离线 HTML 在用户下载时生成；根据 receipt 交付，不能把示例数据解释成用户的真实业务结论。
 
 ## 比较与抵消项
 

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

@@ -8,7 +8,7 @@
 
 ## 声明
 
-Draft schemaVersion 1、Document schemaVersion 2 均支持以下可选字段：
+Draft schemaVersion 2、Document schemaVersion 3 均支持以下可选字段：
 
 ```typescript
 interaction?: {

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

@@ -24,7 +24,7 @@ Top N、过滤或预聚合必须说明选取规则、排序方向与覆盖范围
 
 先给已经得到的主要结论，再放最能支撑它的数据和比较。结论尚未成立时说明现有证据和缺口，不用图形复杂度替代分析。
 
-正文使用 markdown，关键单值用 metric，变化或比较用 line/bar，需要核对原值时用 table。来源面板提供精确 Artifact 和公开事实；只为当前问题读取必要 Finding，不强制遍历整个 SessionGraph。
+正文使用 markdown，关键单值用 metric，变化或比较用 line/bar，需要核对原值时用 table。各图表、表格和指标的数据源入口提供精确 Artifact 和公开事实，报告末尾默认不再添加独立的数据源段落或 `source` block；用户明确要求独立来源面板时再添加。保留 dataset 的来源声明与关联；只为当前问题读取必要 Finding，不强制遍历整个 SessionGraph。
 
 ## 看板
 

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

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

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

@@ -2,9 +2,13 @@
 
 这是插件的 presentation v1 写入契约。所有对象只接受列出的字段；不要把生成文档或 receipt 当作草稿。Marivo 的分析 API 与 semantic schema 以 bound Runtime 的 Skill 和 live Help 为准。
 
+## 报告语言与版本
+
+报告展示语言由 Draft 的 `locale` 决定，Document 使用 `schemaVersion: 3` 并原样保留语言。系统语言仅控制插件操作界面。保存、重开、打印和离线 HTML 均保持报告语言；用户要求改语言时更新完整 Draft，并按既有并发保存契约生成新 Build。旧 Draft v1、Document v2 或缺少语言的报告不受支持，必须重新生成；不修改已有不可变 Build。
+
 ## 顶层与引用
 
-顶层必须有 `schemaVersion: 1`、非空 `title`、`datasets`、`sources`、`blocks`。即使没有 dataset 或来源，也保留空数组；至少一个 block。datasets、sources、blocks 各自的 `id` 不重复，所有引用必须存在。
+顶层必须有 `schemaVersion: 2`、`locale: "zh-CN" | "en-US"`、非空 `title`、`datasets`、`sources`、`blocks`。即使没有 dataset 或来源，也保留空数组；至少一个 block。datasets、sources、blocks 各自的 `id` 不重复，所有引用必须存在。
 
 | 对象 | 必填字段 | 可选字段 |
 | --- | --- | --- |
@@ -16,6 +20,26 @@
 
 `draft_path` 与 computed 的 `path` 均相对于当前绑定 Workspace 根目录，**不是相对于草稿文件目录**。使用根目录内的 JSON 文件；不使用绝对路径、`..`、`.` 路径段、反斜杠、空路径段或通向 Workspace 外的符号链接。不从其他项目、解释器或数据源补齐失败的引用。
 
+## 从报告 cell 引用继续
+
+Ask DSH 与离线复制提供所属 Workspace、Report ID、实际显示的 Build ID、Cell ID，以及
+相对于该 Workspace 的固定 Build `presentation.json` 路径。先用普通文件读取该路径，核对身份，
+再按 `blocks[].id` 定位 cell；正文、数据、单位、精确值、比较和来源限制均从文件读取，不依赖旧对话。
+`Workspace`、`Cell` 和 `Prepared view` 的字段值使用 JSON 字符串编码；先按 JSON 解码再精确匹配，
+保留 ID 中的换行、引号和反斜杠，不取首行、不做 trim。`Report title` 仅为辅助标题，不参与身份匹配。
+文件较长时按读取工具的分页提示继续；单行被截断时使用已有 Workspace 文件能力定向读取 JSON 字段，
+不将截断内容当成完整文档。路径属于原 Workspace，单独分享 HTML 不授予访问原文件的能力。
+
+引用的 Filters 按 filter ID 与 option ID 匹配该 Build 的 `interaction.slices`，从对应 dataset 的
+`rowIndices` 取已有数据。Prepared view 按目标 chart 的 `preparedViews[].id` 读取；若附有
+Current chart view override，则替换显示配置，再应用 Hidden series。Table sort 只改变显示顺序；
+表格引用包含全部筛选结果，不限当前分页。未附覆盖时沿用保存配置。这些均为临时显示状态，不能宣称已保存。
+
+解释时以引用 Build 为准，不能静默换成 current。修改时还需按下面的报告更新契约读取 current，
+比较引用与当前内容，保留已有编辑；有歧义时澄清具体修改目标，不能只替换 expected ID 重试。
+临时探索状态只有在用户要求保存或据此修改时才进入修改范围。目标 Workspace 或文件不可访问时明确说明，
+不猜测其他报告、不通过重新查询或执行分析补齐。
+
 ## 报告更新
 
 新建报告调用 `marivo_present({ draft_path })`。修改已有报告时使用：

package/lib/types/client/presentation/install.d.ts

@@ -1,15 +0,0 @@
-export declare function PresentationCards({ matched, sessionId, workspaces, model }: {
-    matched: any;
-    sessionId: any;
-    workspaces: any;
-    model: any;
-}): import("react").JSX.Element | null;
-export declare function PresentationOverlay({ model, sessionId, workspaceId, workspaceUnavailable, openSemanticObject, onAskDsh, }: {
-    model: any;
-    sessionId: any;
-    workspaceId: any;
-    workspaceUnavailable?: boolean | undefined;
-    openSemanticObject: any;
-    onAskDsh: any;
-}): import("react").JSX.Element | null;
-export declare function installPresentation(ctx: any, rpc: any, openSemanticObject: any): void;