@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chengxianglibra/dsh-data-analysis",
   "description": "Marivo runtime, live Help, secure datasource execution and presentation delivery for DeepSeek Harness",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chengxianglibra/dsh-data-analysis.git",
@@ -14,7 +14,7 @@
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.19.0 || >=24.0.0"
   },
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -54,9 +54,11 @@
     "lib/**/*.js",
     "lib/types/**/*.d.ts",
     "skills/dsh-data-analysis-presentation/**",
+    "skills/dsh-data-analysis-files/**",
     "python/presentation-kit/dist/dsh_data_analysis_presentation_kit-1.1.0-py3-none-any.whl",
     "cordis.patch.yml",
-    "README.md"
+    "README.md",
+    "README.en.md"
   ],
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/finalize-build.mjs",
@@ -72,11 +74,11 @@
     "schema": "dsh-data-analysis-compatibility/v2",
     "dsh": {
       "distribution": "@deepseek-ai/dsh",
-      "peerRange": "0.1.1-rc.2"
+      "peerRange": ">=0.1.5-rc.1"
     },
     "marivo": {
-      "version": "0.5.4",
-      "packageSpec": "marivo[duckdb,trino,clickhouse]==0.5.4"
+      "version": "0.5.5",
+      "packageSpec": "marivo[duckdb,trino,clickhouse]==0.5.5"
     },
     "contracts": {
       "runtimeInstallation": "dsh-data-analysis-runtime/v3",
@@ -87,13 +89,19 @@
     "client": {
       "inject": [
         "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-api-gateway",
         "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-api-workspace-controller",
+        "@deepseek-ai/dsh-client-ui-chat",
         "@deepseek-ai/dsh-client-ui-conversation",
         "@deepseek-ai/dsh-client-ui-tool",
         "@deepseek-ai/dsh-client-ui-input-trigger",
         "@deepseek-ai/dsh-client-ui-sidebar",
-        "@deepseek-ai/dsh-client-ui-layout"
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-plugins"
       ],
       "platform": "web"
     },
@@ -102,72 +110,96 @@
     }
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1129.0",
     "@deepseek-ai/schemastery": "^3.18.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent-loop": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-anonymous-user-id": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-bash-local": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-code-runtime": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-code-runtime-worker-thread": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-credentials-local": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-fs-local": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-fs-observation-policy": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm-deepseek": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-scope": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-skill": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-tool-bash": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-tool-fs": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-loop": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-anonymous-user-id": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-bash-local": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-store": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-code-runtime": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-code-runtime-worker-thread": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-credentials-local": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-fs-local": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-fs-observation-policy": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-launch-environment": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm-deepseek": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-scope": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-projection": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-skill": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-storage": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-storage-json": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-subprocess-local": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-tool-bash": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-tool-fs": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-tool-present": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-tool-skill": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-util-workspace-path": "0.1.5-rc.1",
+    "@shikijs/core": "4.4.3",
+    "@shikijs/engine-javascript": "4.4.3",
+    "@shikijs/langs": "4.4.3",
     "@types/react": "^18.3.31",
-    "react": "^18.3.1",
-    "typescript": "^6.0.3",
-    "esbuild": "^0.28.2",
-    "@deepseek-ai/dsh-storage": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-storage-json": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.1-rc.2",
     "@types/react-dom": "18.3.7",
+    "@wasm-fmt/ruff_fmt": "0.15.20",
+    "esbuild": "^0.28.2",
+    "immer": "10.1.1",
     "playwright": "1.63.0",
+    "react": "^18.3.1",
     "react-dom": "18.3.1",
     "react-is": "18.3.1",
     "recharts": "3.8.1",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-tool-skill": "^0.1.1-rc.2",
-    "@shikijs/core": "4.4.3",
-    "@shikijs/engine-javascript": "4.4.3",
-    "@shikijs/langs": "4.4.3",
-    "@wasm-fmt/ruff_fmt": "0.15.20",
-    "sql-formatter": "15.8.2"
+    "sql-formatter": "15.8.2",
+    "typescript": "^6.0.3",
+    "zustand": "4.4.7",
+    "@deepseek-ai/dsh-settings": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-settings-file": "0.1.5-rc.1"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-connection": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-locale": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-tool": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-credentials": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-home-paths": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-shell-env": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-skill-filesystem": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-scope": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-api-gateway": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-api-session-controller": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-api-workspace-controller": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-atomic-write": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-connection": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-chat": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-input-trigger": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-layout": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-tool": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-credentials": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-home-paths": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-sandbox": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-scope": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell-env": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-skill-filesystem": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-storage-domain": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-system-prompt": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-typert-registry": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-util-values": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-workspace": ">=0.1.5-rc.1",
     "react": "^18.3.1",
-    "@deepseek-ai/dsh-storage-domain": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-input-trigger": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-workspace": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-sidebar": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-layout": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-shell": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-sandbox": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-atomic-write": "0.1.1-rc.2"
+    "@deepseek-ai/dsh-settings": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": ">=0.1.5-rc.1"
   }
 }

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

@@ -0,0 +1,44 @@
+---
+name: dsh-data-analysis-files
+description: 分析附件或 Workspace 中的 CSV、JSON、Parquet、Excel 数据，回答问题或交付 CSV、JSON、PNG 文件。可接续报告展示，无需先建立 Marivo datasource 或语义模型。
+---
+
+# 文件分析
+
+本 Skill 负责文件读取、计算、分析核对与普通文件交付。按用户问题选择方法；需要保存报告或交互展示时，完成分析后交给 `dsh-data-analysis-presentation`。
+
+## 确认输入与执行
+
+使用 Harness 提供的当前附件可读路径，或用户指定的 Workspace 文件；同名附件按消息和完整路径区分。路径不可读时报告实际问题，不猜测 Host 缓存位置。
+在实际读取代码中使用该完整路径，使执行记录保留输入身份；不为缩短路径而复制成 Workspace 同名文件，以免覆盖或在后续追问中读到旧副本。
+
+文件读取、计算和最终文件生成均通过 `marivo_python` 在绑定 Runtime 中执行，不改走 Bash 的 `python`／`python3` 或其他解释器。纯本地文件分析可直接使用 pandas 或原生 `duckdb`，传 `datasources: []`；无需 `md.raw_sql`、Marivo 分析 Skill、live Help 或语义建模。只有实际访问 Marivo datasource 时才声明其精确名称并查询相关契约。
+
+使用现有 reader，保留回答所需的 sheet、字段和解析范围；区分样本与全量。Excel `.xlsx` 可用 DuckDB `read_xlsx`，首次使用可能联网获取官方扩展；不承诺旧 `.xls` 或冷缓存离线读取，不临时安装 Python 依赖。
+
+每次 `marivo_python` 都是独立进程。原生 DuckDB 连接可在本次调用内复用、创建临时表，并及时关闭；后续追问重新读取原文件或已有结果，不依赖上次内存状态。按问题控制读取和输出规模，SQL `LIMIT` 不代表仅扫描这些行。
+
+## 计算与核对
+
+按问题确认粒度、单位、时间范围与比较基准；检查会影响计算的解析类型、缺失值、重复记录及连接基数。合并同名文件、筛选或去重时说明实际规则，不把缺失值当零，不把样本当全量。
+
+完成文字答案或生成交付物前，逐项核对用户问题及各比较分支。保留比较两侧、变化方向和比例分母，从原值核对差值、比例与合计；Top N 或子集不能替代全量结论。观测和数值贡献不自动证明原因；结论措辞应体现实际证据强度。
+最后核对解释文字中的比较名称与涨跌方向是否和表中同一项一致；基准不同可以解释比率差异，本身不能证明业务变化的原因。
+
+某个基准或分支缺数据时，交付已有支持的答案，并明确缺失范围及影响，不用另一项成功比较替代。所需答案已有支持或已明确阻塞时结束，不为完善展示额外扩展分析。
+
+## 可复用语义与停止条件
+
+分析中发现可供后续任务复用的业务定义或语义缺口时，先区分共享口径与本次结果：指标定义、维度含义或业务关系可作为语义候选；观测数值、临时筛选与未验证假设保留在当前分析中，不自动成为共享定义。
+
+仅当当前问题需要该共享定义，或用户已授权语义沉淀时，加载 `marivo-semantic`，携带复用用途、已有依据、适用范围和未决含义，按其 Skill 与实时 Help 检查并优先复用已有对象。需要新增或修正时只处理最小必要缺口；业务含义与授权已明确则继续，实质歧义按语义 Skill 澄清，不自行猜测定义，也不重复请求已有授权。
+
+收到经验证的对象引用后继续原问题；必要对象已完成且原问题已回答，或阻塞已明确时停止。不递归扩展相邻指标、实体或业务域。顺带发现的范围外机会只在答复中简要说明用途与依据，不自动建模、另建记录文件或继续探索。普通文件计算仍无需语义建模；展示流程不承担语义沉淀。
+
+## 按用户目标交付
+
+普通答案和简短比较表格直接在聊天中回答，不额外创建文件。用户要求 CSV、JSON、PNG 等实际文件时，先读[文件交付](references/delivery.md)，通过 `marivo_python` 生成最终文件，优先写入当前绑定 Workspace；确认执行成功、文件存在后，调用实际可用的 Harness 原生 `present`，再回复用户。文件生成和原生声明分别核对，路径或代码块不能替代交付。
+
+需要交互图表、表格、报告或看板时加载 `dsh-data-analysis-presentation`，将 DataFrame 交给现有 writer，关联实际返回的 `codeRef`，用 `marivo_present` 保存固定 Build。在正文说明文件名与分析范围，不将文件结果冒充 Marivo Artifact 或 Evidence。普通 `present` 不赋予文件 Report/Build 或 Evidence 身份。
+
+需要起步代码时读[简短示例](references/examples.md)；其中提供无需额外依赖的 PNG 写入代码，也通过 `marivo_python` 执行。

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

@@ -0,0 +1,15 @@
+# 文件交付与恢复
+
+用户要求 CSV、JSON、PNG 等实际文件时读取本页。生成最终文件后，按当前 Harness 原生 `present` 工具契约交付；不猜测附件缓存或 Shell 私有临时目录。工具拥有路径与类型校验，详见 Harness [present 契约](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.5-rc.1/packages/fs/tool-present/README.md)。
+
+## 生成与声明
+
+只交付用户要求的最终文件。报告内部的 `presentation.json`、computed 数据和 receipt 不作为默认附件；用户另行要求时，先确认实际文件已经存在且当前 Session 可访问。浏览器内生成的下载不伪装成 Session 文件；报告 HTML 交给展示 Skill 的导出或发布流程。
+
+文件生成成功后调用 `present`，分别核对生成与声明结果。当前缺少 `present` 时，说明“文件已生成，原生交付能力不可用”，并提供准确路径；不虚构卡片，不安装工具或改写 profile。
+
+## 失败与再次交付
+
+生成失败不声明成功；声明失败区分“文件已生成”和“交付未完成”。修复路径或可见性后只重试交付，不为补卡片重跑分析。响应不确定时先核对已有调用结果和事件，不盲目重复声明。原生打开失败时使用 Host 的预览或错误反馈，不绕过权限。
+
+卡片读取当前源文件，不保存内容版本；修改、移动或删除会影响后续读取。成功声明的持久事件属于 Harness，即使 PTC 外层程序随后失败，也不撤销已成功的声明。子代理产物属于其调用 Session；父 Agent 如需交付，先确认自己能访问文件，再在父 Session 显式调用 `present`，不自动跨 Session 转投递。

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,24 +1,24 @@
 ---
 name: dsh-data-analysis-presentation
-description: 将 Marivo 分析结果或已有 Workspace 数据展示为图表、表格、报告、看板或来源面板，并一次交付可打开的 reader 与离线 HTML。适用于需要可视展示或保存分析快照的请求；普通事实问答使用文字。
+description: 将已有分析结果保存为右侧阅读器中的交互图表、表格、报告、看板或来源面板，并支持报告更新、HTML 导出与按需发布。普通文字、简短聊天表格及 CSV、PNG 文件交付无需此 Skill。
 ---
 
-# Marivo 分析展示
+# 分析展示与报告交付
 
-用一份 JSON 草稿组织已有结果，再调用一次 `marivo_present` 完成检查、Web 阅读与离线 HTML。单图、表格、报告和看板使用同一流程。
+本 Skill 负责把已有结果组织为 JSON Draft，通过 `marivo_present` 保存并打开阅读器。分析方法、业务语义、质量与 lineage 由分析流程和 Marivo Runtime 契约拥有；展示不能补造缺失证据。
 
-## 从问题到交付
+## 生成报告
 
-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 的计算正确。
-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 不重算。
+1. 确认展示目标与已有结果。报告语言遵循用户要求，否则根据问题和上下文决定，不跟随系统界面语言。已有结果可直接展示；缺少计算时，文件分析交给 `dsh-data-analysis-files`，Marivo 分析或建模交给对应 Runtime Skill 与 live Help。只补所需分支。
+2. 选择数据与来源。可恢复 Artifact 用实际 `session.id` 和 `artifact.ref` 引用，按需加 `findingId`，不重复导出。同一问题需要计算后的 DataFrame 时，通过 `marivo_python` 在绑定 Runtime 使用 `dsh_data_analysis_presentation.write_dataset`；纯本地 pandas／原生 DuckDB 传 `datasources: []`，访问 Marivo datasource 才声明其精确名称。文件结果注明文件名与分析范围，关联实际返回的 `codeRef`，不构造 Marivo Artifact 或 Evidence 身份。
+3. 写草稿前读 [schema 与文件边界](references/schema.md)。使用完整 Draft、Workspace 相对路径和实际来源身份；来源事实与 unavailable 状态由 builder 读取。报告、看板及比较型展示还需读 [叙事与证据检查](references/narrative.md)，核对展示中的数值、范围、方向、分母和文字与已有结果一致。需要图表时读 [图形配置](references/charts.md)，需要起步草稿或 writer 用法时读 [可改写示例](references/examples.md)。
+4. 用普通文件能力在当前 Workspace 写 Draft。手写 computed JSON 时可按 [静态预检](references/schema.md#草稿静态预检)检查结构，再调用 `marivo_present`。成功 receipt 才表示已保存交付；失败按诊断修正草稿或引用，不为修复展示自动重新查询、observe、revalidate 或重放分析。缺失数据交回原分析流程。
+5. 回复主要结论、未完成分支和实质限制，简短说明报告已在右侧 tab 打开；headless 时提供 receipt 的准确路径。保留来源 unavailable、Agent 预筛选与 writer 截断的区别。只声明实际完成的浏览器检查，不把构建成功视为计算或业务结论已验证。
 
-## 修改已有报告
+## 按操作读取
 
-用户要求修改、合并 KPI 或刷新这份报告时，修改完整 Draft，并向 `marivo_present` 成对传入实际 `report_id` 与本次修改基于的 `expected_build_id`，保存为同一 Report 的新 Build。以已读取的保存内容为基准，保留用户需要的阅读器编辑；不按标题或草稿路径猜身份，不修改生成文件。新建独立报告时才省略这两个参数。更新前读取方式与冲突处理见 [报告更新](references/schema.md#报告更新)；冲突时核对当前内容，不能仅替换 expected ID 强行重试。
-
-## 来源追问
-
-简短来源问题可通过 Marivo 公开 Python API 回答。需要可视来源面板时，使用 `datasets: []` 与 `source` block，无需制造图表或 dataset。需要保留生成脚本时，将成功 `marivo_python` 返回的 `codeRef` 写入相应 dataset 的 `codeRefs`，详见 [生成代码](references/schema.md#生成代码)；Artifact 执行 SQL 自动读取，执行记录与数据集的关联不构成计算正确性证明。打开、下载和来源展开读取生成时保存的快照；用户要求新范围、刷新或进一步分析时回到普通分析流程。
+- **修改、合并或刷新已有报告**：先读 [报告更新](references/schema.md#报告更新)。基于已读取内容修改完整 Draft，保留用户需要的编辑；成对传入实际 `report_id` 与 `expected_build_id`，保存同一 Report 的新 Build。冲突时读取并核对当前版本，不仅替换 expected ID 重试。
+- **筛选与动态指标**：默认不添加全局筛选。需要共同维度交互时，先读 [全局筛选与动态指标](references/interaction.md)，准备所有可选组合所需结果；reader 不重算，缺组合时减少筛选或回到分析流程。
+- **来源与生成代码追问**：简短问题可用 Marivo 公开 Python API 回答；需要来源面板时用 `datasets: []` 与 `source` block。脚本关联方式见 [生成代码](references/schema.md#生成代码)，从报告 cell 继续见 [引用恢复](references/schema.md#从报告-cell-引用继续)。已有快照不证明当前数据新鲜度。
+- **离线 HTML 文件**：读 [导出与原生交付](references/export-html.md)，使用保存的 Build 导出，再调用原生 `present`。普通报告交付不额外生成 HTML 或附件。
+- **对象存储链接**：用户要求发布时读 [发布报告](references/publishing.md)，使用实时可用的 `marivo_publish_report`；成功后返回其确认的 URL。

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；完整报告保留全部已保存筛选组合，不是数据权限隔离副本。