@chengxianglibra/dsh-data-analysis 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. package/README.md +83 -34
  2. package/lib/bin/environment.js +1 -1
  3. package/lib/bin/presentation-lint.js +21 -0
  4. package/lib/bridges.js +2 -2
  5. package/lib/client/credentials/create-datasource.js +67 -0
  6. package/lib/client/credentials/install.js +191 -0
  7. package/lib/client/credentials/model.js +494 -0
  8. package/lib/client/credentials/styles.js +17 -0
  9. package/lib/client/workspace-header-action.js +11 -0
  10. package/lib/client.js +1133 -736
  11. package/lib/compatibility.js +1 -1
  12. package/lib/datasource/authoring.js +70 -0
  13. package/lib/datasource/bridge-programs.js +30 -18
  14. package/lib/datasource/bridge.js +100 -8
  15. package/lib/datasource/index.js +3 -2
  16. package/lib/datasource/python.js +115 -0
  17. package/lib/datasource/resolver-program.js +112 -0
  18. package/lib/datasource/rpc.js +88 -0
  19. package/lib/datasource/service.js +687 -0
  20. package/lib/datasource/shell-env.js +2 -333
  21. package/lib/datasource/test.js +24 -51
  22. package/lib/environment/binding.js +54 -9
  23. package/lib/environment/runtime.js +89 -78
  24. package/lib/environment/subprocess.js +6 -1
  25. package/lib/environment/summary.js +3 -3
  26. package/lib/environment/workspace.js +5 -0
  27. package/lib/index.js +1 -1
  28. package/lib/plugin.js +168 -51
  29. package/lib/presentation/assets/portable.js +606 -0
  30. package/lib/presentation/assets/static.js +945 -0
  31. package/lib/presentation/build/index.js +71 -0
  32. package/lib/presentation/commit.js +156 -0
  33. package/lib/presentation/contracts/charts.js +476 -0
  34. package/lib/presentation/contracts/editing.js +58 -0
  35. package/lib/presentation/contracts/index.js +651 -0
  36. package/lib/presentation/contracts/interaction.js +62 -0
  37. package/lib/presentation/contracts/types.js +15 -0
  38. package/lib/presentation/contracts/values.js +28 -0
  39. package/lib/presentation/delivery.js +56 -0
  40. package/lib/presentation/files.js +83 -0
  41. package/lib/presentation/index.js +6 -0
  42. package/lib/presentation/lint.js +46 -0
  43. package/lib/presentation/projection/files.js +85 -0
  44. package/lib/presentation/projection/index.js +195 -0
  45. package/lib/presentation/projection/program.js +144 -0
  46. package/lib/presentation/projection/sql-code.js +79 -0
  47. package/lib/presentation/receipt.js +34 -0
  48. package/lib/presentation/reports.js +122 -0
  49. package/lib/presentation/rpc.js +148 -0
  50. package/lib/presentation/tool.js +122 -0
  51. package/lib/python-execution-contracts.js +1 -0
  52. package/lib/python-execution.js +232 -0
  53. package/lib/semantic-browser/contracts.js +80 -0
  54. package/lib/semantic-browser/definition.js +64 -0
  55. package/lib/semantic-browser/program.js +119 -0
  56. package/lib/semantic-browser/service.js +72 -0
  57. package/lib/semantic-reference/bridge.js +118 -0
  58. package/lib/semantic-reference/contracts.js +113 -0
  59. package/lib/semantic-reference/index.js +3 -0
  60. package/lib/semantic-reference/rpc.js +122 -0
  61. package/lib/semantic-reference/search.js +94 -0
  62. package/lib/semantic-reference/usage.js +143 -0
  63. package/lib/types/bridges.d.ts +2 -2
  64. package/lib/types/client/credentials/create-datasource.d.ts +5 -0
  65. package/lib/types/client/credentials/install.d.ts +1 -0
  66. package/lib/types/client/credentials/model.d.ts +59 -0
  67. package/lib/types/client/credentials/styles.d.ts +1 -0
  68. package/lib/types/client/presentation/ask-dsh.d.ts +9 -0
  69. package/lib/types/client/presentation/chart-explorer.d.ts +12 -0
  70. package/lib/types/client/presentation/chart-geometry.d.ts +30 -0
  71. package/lib/types/client/presentation/chart-renderer.d.ts +10 -0
  72. package/lib/types/client/presentation/chart-specials.d.ts +10 -0
  73. package/lib/types/client/presentation/chart-styles.d.ts +1 -0
  74. package/lib/types/client/presentation/chart-tooltip.d.ts +13 -0
  75. package/lib/types/client/presentation/chart-view.d.ts +23 -0
  76. package/lib/types/client/presentation/copy-context.d.ts +5 -0
  77. package/lib/types/client/presentation/delivery-model.d.ts +54 -0
  78. package/lib/types/client/presentation/delivery.d.ts +77 -0
  79. package/lib/types/client/presentation/editor-controls.d.ts +12 -0
  80. package/lib/types/client/presentation/global-filters.d.ts +6 -0
  81. package/lib/types/client/presentation/host-entry.d.ts +12 -0
  82. package/lib/types/client/presentation/icons.d.ts +4 -0
  83. package/lib/types/client/presentation/install.d.ts +15 -0
  84. package/lib/types/client/presentation/markdown.d.ts +5 -0
  85. package/lib/types/client/presentation/model.d.ts +62 -0
  86. package/lib/types/client/presentation/reader.d.ts +11 -0
  87. package/lib/types/client/presentation/source-code-model.d.ts +16 -0
  88. package/lib/types/client/presentation/source-code.d.ts +11 -0
  89. package/lib/types/client/presentation/source-dialog.d.ts +13 -0
  90. package/lib/types/client/presentation/source-facts.d.ts +20 -0
  91. package/lib/types/client/presentation/source-format.d.ts +5 -0
  92. package/lib/types/client/presentation/source-highlight.d.ts +7 -0
  93. package/lib/types/client/presentation/sources.d.ts +13 -0
  94. package/lib/types/client/presentation/styles.d.ts +1 -0
  95. package/lib/types/client/presentation/table.d.ts +12 -0
  96. package/lib/types/client/presentation/use-element-width.d.ts +5 -0
  97. package/lib/types/client/workspace-header-action.d.ts +7 -0
  98. package/lib/types/client.d.ts +4 -122
  99. package/lib/types/compatibility.d.ts +2 -2
  100. package/lib/types/datasource/authoring.d.ts +25 -0
  101. package/lib/types/datasource/bridge.d.ts +21 -3
  102. package/lib/types/datasource/index.d.ts +3 -5
  103. package/lib/types/datasource/python.d.ts +4 -0
  104. package/lib/types/datasource/resolver-program.d.ts +6 -0
  105. package/lib/types/datasource/rpc.d.ts +4 -0
  106. package/lib/types/datasource/service.d.ts +112 -0
  107. package/lib/types/datasource/shell-env.d.ts +0 -29
  108. package/lib/types/datasource/test.d.ts +6 -29
  109. package/lib/types/environment/binding.d.ts +5 -1
  110. package/lib/types/environment/errors.d.ts +1 -1
  111. package/lib/types/environment/runtime.d.ts +5 -5
  112. package/lib/types/environment/types.d.ts +13 -2
  113. package/lib/types/index.d.ts +1 -1
  114. package/lib/types/plugin.d.ts +11 -5
  115. package/lib/types/presentation/build/index.d.ts +11 -0
  116. package/lib/types/presentation/commit.d.ts +4 -0
  117. package/lib/types/presentation/contracts/charts.d.ts +13 -0
  118. package/lib/types/presentation/contracts/editing.d.ts +8 -0
  119. package/lib/types/presentation/contracts/index.d.ts +11 -0
  120. package/lib/types/presentation/contracts/interaction.d.ts +8 -0
  121. package/lib/types/presentation/contracts/types.d.ts +252 -0
  122. package/lib/types/presentation/contracts/values.d.ts +9 -0
  123. package/lib/types/presentation/delivery.d.ts +3 -0
  124. package/lib/types/presentation/files.d.ts +7 -0
  125. package/lib/types/presentation/index.d.ts +6 -0
  126. package/lib/types/presentation/lint.d.ts +13 -0
  127. package/lib/types/presentation/projection/files.d.ts +2 -0
  128. package/lib/types/presentation/projection/index.d.ts +20 -0
  129. package/lib/types/presentation/projection/program.d.ts +2 -0
  130. package/lib/types/presentation/projection/sql-code.d.ts +2 -0
  131. package/lib/types/presentation/receipt.d.ts +14 -0
  132. package/lib/types/presentation/reports.d.ts +5 -0
  133. package/lib/types/presentation/rpc.d.ts +24 -0
  134. package/lib/types/presentation/tool.d.ts +12 -0
  135. package/lib/types/python-execution-contracts.d.ts +10 -0
  136. package/lib/types/python-execution.d.ts +10 -0
  137. package/lib/types/semantic-browser/contracts.d.ts +40 -0
  138. package/lib/types/semantic-browser/definition.d.ts +20 -0
  139. package/lib/types/semantic-browser/program.d.ts +2 -0
  140. package/lib/types/semantic-browser/service.d.ts +20 -0
  141. package/lib/types/semantic-reference/bridge.d.ts +11 -0
  142. package/lib/types/semantic-reference/contracts.d.ts +51 -0
  143. package/lib/types/semantic-reference/index.d.ts +3 -0
  144. package/lib/types/semantic-reference/rpc.d.ts +15 -0
  145. package/lib/types/semantic-reference/search.d.ts +10 -0
  146. package/lib/types/semantic-reference/usage.d.ts +43 -0
  147. package/package.json +43 -19
  148. package/python/presentation-kit/dist/dsh_data_analysis_presentation_kit-1.1.0-py3-none-any.whl +0 -0
  149. package/skills/dsh-data-analysis-presentation/SKILL.md +24 -0
  150. package/skills/dsh-data-analysis-presentation/references/chart-examples.md +18 -0
  151. package/skills/dsh-data-analysis-presentation/references/charts.md +55 -0
  152. package/skills/dsh-data-analysis-presentation/references/examples/artifact.draft.json +27 -0
  153. package/skills/dsh-data-analysis-presentation/references/examples/charts-bins.dataset.json +33 -0
  154. package/skills/dsh-data-analysis-presentation/references/examples/charts-boxes.dataset.json +45 -0
  155. package/skills/dsh-data-analysis-presentation/references/examples/charts-composition.dataset.json +33 -0
  156. package/skills/dsh-data-analysis-presentation/references/examples/charts-funnel.dataset.json +27 -0
  157. package/skills/dsh-data-analysis-presentation/references/examples/charts-precision.dataset.json +21 -0
  158. package/skills/dsh-data-analysis-presentation/references/examples/charts-series.dataset.json +58 -0
  159. package/skills/dsh-data-analysis-presentation/references/examples/charts-shares.dataset.json +33 -0
  160. package/skills/dsh-data-analysis-presentation/references/examples/charts-waterfall.dataset.json +44 -0
  161. package/skills/dsh-data-analysis-presentation/references/examples/charts.draft.json +392 -0
  162. package/skills/dsh-data-analysis-presentation/references/examples/comparison-selected.dataset.json +24 -0
  163. package/skills/dsh-data-analysis-presentation/references/examples/comparison-summary.dataset.json +22 -0
  164. package/skills/dsh-data-analysis-presentation/references/examples/comparison.dataset.json +18 -0
  165. package/skills/dsh-data-analysis-presentation/references/examples/comparison.draft.json +79 -0
  166. package/skills/dsh-data-analysis-presentation/references/examples/computed-sources.draft.json +35 -0
  167. package/skills/dsh-data-analysis-presentation/references/examples/computed.dataset.json +12 -0
  168. package/skills/dsh-data-analysis-presentation/references/examples/computed.draft.json +57 -0
  169. package/skills/dsh-data-analysis-presentation/references/examples/interaction-detail.dataset.json +30 -0
  170. package/skills/dsh-data-analysis-presentation/references/examples/interaction-summary.dataset.json +22 -0
  171. package/skills/dsh-data-analysis-presentation/references/examples/interaction.draft.json +278 -0
  172. package/skills/dsh-data-analysis-presentation/references/examples/source-only.draft.json +19 -0
  173. package/skills/dsh-data-analysis-presentation/references/examples/write-charts.py +73 -0
  174. package/skills/dsh-data-analysis-presentation/references/examples/write-comparison.py +42 -0
  175. package/skills/dsh-data-analysis-presentation/references/examples/write-computed.py +21 -0
  176. package/skills/dsh-data-analysis-presentation/references/examples/write-interaction.py +33 -0
  177. package/skills/dsh-data-analysis-presentation/references/examples.md +42 -0
  178. package/skills/dsh-data-analysis-presentation/references/interaction.md +56 -0
  179. package/skills/dsh-data-analysis-presentation/references/narrative.md +37 -0
  180. package/skills/dsh-data-analysis-presentation/references/schema.md +138 -0
  181. package/lib/datasource/access.js +0 -60
  182. package/lib/datasource/credentials.js +0 -24
  183. package/lib/evidence/bridge-program.js +0 -153
  184. package/lib/evidence/bridge.js +0 -166
  185. package/lib/evidence/index.js +0 -2
  186. package/lib/evidence/sources.js +0 -263
  187. package/lib/types/datasource/access.d.ts +0 -27
  188. package/lib/types/evidence/bridge.d.ts +0 -40
  189. package/lib/types/evidence/index.d.ts +0 -4
  190. package/lib/types/evidence/sources.d.ts +0 -57
  191. package/python/report-kit/dist/dsh_data_analysis_report_kit-3.0.0-py3-none-any.whl +0 -0
  192. package/skills/dsh-data-analysis-report/SKILL.md +0 -57
  193. package/skills/dsh-data-analysis-report/assets/marivo-artifact.js +0 -113
  194. package/skills/dsh-data-analysis-report/assets/marivo-session-dag.js +0 -1201
  195. package/skills/dsh-data-analysis-report/assets/report-data.js +0 -449
@@ -0,0 +1,43 @@
1
+ import { type DomainFacility } from '@deepseek-ai/dsh-storage-domain';
2
+ import { z } from 'zod';
3
+ import { type SemanticRef } from './contracts.ts';
4
+ import type { UsageScores } from './search.ts';
5
+ export declare const usageSchema: z.ZodObject<{
6
+ entries: z.ZodRecord<z.ZodString, z.ZodObject<{
7
+ ref: z.ZodPipe<z.ZodUnknown, z.ZodTransform<SemanticRef, unknown>>;
8
+ days: z.ZodArray<z.ZodObject<{
9
+ day: z.ZodISODate;
10
+ count: z.ZodNumber;
11
+ }, z.core.$strict>>;
12
+ lastSelectedAt: z.ZodNumber;
13
+ }, z.core.$strict>>;
14
+ }, z.core.$strict>;
15
+ export type UsageWorkspace = z.infer<typeof usageSchema>;
16
+ export declare const usageSpec: {
17
+ name: string;
18
+ version: number;
19
+ tables: {
20
+ workspaces: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
21
+ entries: Record<string, {
22
+ ref: SemanticRef;
23
+ days: {
24
+ day: string;
25
+ count: number;
26
+ }[];
27
+ lastSelectedAt: number;
28
+ }>;
29
+ }>;
30
+ };
31
+ };
32
+ export declare function workspaceKey(canonicalRoot: string): string;
33
+ export declare function localDay(date: Date): string;
34
+ export declare function windowDays(now: number): string[];
35
+ export declare function increment(row: UsageWorkspace, input: SemanticRef, now: number): UsageWorkspace;
36
+ /** Only admitted mutations join the per-Workspace queue; close drains those jobs. */
37
+ export declare class SemanticReferenceUsage {
38
+ #private;
39
+ constructor(facility: Pick<DomainFacility, 'open'>, clock?: () => number, diagnostic?: () => void);
40
+ scores(key: string): Promise<UsageScores>;
41
+ selected(key: string, ref: SemanticRef, signal: AbortSignal): Promise<void>;
42
+ close(): Promise<void>;
43
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@chengxianglibra/dsh-data-analysis",
3
- "description": "Marivo runtime, live-help, datasource, and on-demand Evidence source integration for DeepSeek Harness",
4
- "version": "0.1.1",
3
+ "description": "Marivo runtime, live Help, secure datasource execution and presentation delivery for DeepSeek Harness",
4
+ "version": "0.1.2",
5
5
  "repository": {
6
6
  "type": "git",
7
7
  "url": "git+https://github.com/chengxianglibra/dsh-data-analysis.git",
@@ -19,7 +19,8 @@
19
19
  "main": "lib/index.js",
20
20
  "types": "lib/types/index.d.ts",
21
21
  "bin": {
22
- "dsh-data-analysis-env": "./lib/bin/environment.js"
22
+ "dsh-data-analysis-env": "./lib/bin/environment.js",
23
+ "dsh-data-analysis-presentation-lint": "./lib/bin/presentation-lint.js"
23
24
  },
24
25
  "exports": {
25
26
  ".": {
@@ -42,10 +43,6 @@
42
43
  "types": "./lib/types/datasource/index.d.ts",
43
44
  "default": "./lib/datasource/index.js"
44
45
  },
45
- "./evidence": {
46
- "types": "./lib/types/evidence/index.d.ts",
47
- "default": "./lib/evidence/index.js"
48
- },
49
46
  "./compatibility": {
50
47
  "types": "./lib/types/compatibility.d.ts",
51
48
  "default": "./lib/compatibility.js"
@@ -56,16 +53,16 @@
56
53
  "files": [
57
54
  "lib/**/*.js",
58
55
  "lib/types/**/*.d.ts",
59
- "python/report-kit/dist/dsh_data_analysis_report_kit-3.0.0-py3-none-any.whl",
60
- "skills/**/*",
56
+ "skills/dsh-data-analysis-presentation/**",
57
+ "python/presentation-kit/dist/dsh_data_analysis_presentation_kit-1.1.0-py3-none-any.whl",
61
58
  "cordis.patch.yml",
62
59
  "README.md"
63
60
  ],
64
61
  "scripts": {
65
62
  "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/finalize-build.mjs",
66
- "build:report-kit": "node scripts/build-report-kit.mjs",
67
63
  "clean": "node scripts/clean.mjs",
68
- "prepack": "npm run build:report-kit && npm run build"
64
+ "prepack": "npm run build:presentation-kit && npm run build",
65
+ "build:presentation-kit": "node scripts/build-presentation-kit.mjs"
69
66
  },
70
67
  "publishConfig": {
71
68
  "access": "public",
@@ -78,11 +75,11 @@
78
75
  "peerRange": "0.1.1-rc.2"
79
76
  },
80
77
  "marivo": {
81
- "version": "0.5.3",
82
- "packageSpec": "marivo[duckdb,trino,clickhouse]==0.5.3"
78
+ "version": "0.5.4",
79
+ "packageSpec": "marivo[duckdb,trino,clickhouse]==0.5.4"
83
80
  },
84
81
  "contracts": {
85
- "runtimeInstallation": "dsh-data-analysis-runtime/v2",
82
+ "runtimeInstallation": "dsh-data-analysis-runtime/v3",
86
83
  "subprocessPolicy": "direct-argv-inherited-env-snapshot-overlay-v2"
87
84
  }
88
85
  },
@@ -93,7 +90,10 @@
93
90
  "@deepseek-ai/dsh-client-locale",
94
91
  "@deepseek-ai/dsh-client-runtime",
95
92
  "@deepseek-ai/dsh-client-ui-conversation",
96
- "@deepseek-ai/dsh-client-ui-tool"
93
+ "@deepseek-ai/dsh-client-ui-tool",
94
+ "@deepseek-ai/dsh-client-ui-input-trigger",
95
+ "@deepseek-ai/dsh-client-ui-sidebar",
96
+ "@deepseek-ai/dsh-client-ui-layout"
97
97
  ],
98
98
  "platform": "web"
99
99
  },
@@ -102,7 +102,8 @@
102
102
  }
103
103
  },
104
104
  "dependencies": {
105
- "@deepseek-ai/schemastery": "^3.18.1"
105
+ "@deepseek-ai/schemastery": "^3.18.1",
106
+ "zod": "^4.4.3"
106
107
  },
107
108
  "devDependencies": {
108
109
  "@deepseek-ai/dsh-agent-loop": "^0.1.1-rc.2",
@@ -121,10 +122,25 @@
121
122
  "@deepseek-ai/dsh-subprocess-local": "^0.1.1-rc.2",
122
123
  "@deepseek-ai/dsh-tool-bash": "^0.1.1-rc.2",
123
124
  "@deepseek-ai/dsh-tool-fs": "^0.1.1-rc.2",
124
- "ajv": "^8.20.0",
125
125
  "@types/react": "^18.3.31",
126
126
  "react": "^18.3.1",
127
- "typescript": "^6.0.3"
127
+ "typescript": "^6.0.3",
128
+ "esbuild": "^0.28.2",
129
+ "@deepseek-ai/dsh-storage": "^0.1.1-rc.2",
130
+ "@deepseek-ai/dsh-storage-json": "^0.1.1-rc.2",
131
+ "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.1-rc.2",
132
+ "@types/react-dom": "18.3.7",
133
+ "playwright": "1.63.0",
134
+ "react-dom": "18.3.1",
135
+ "react-is": "18.3.1",
136
+ "recharts": "3.8.1",
137
+ "@deepseek-ai/dsh-launch-environment": "^0.1.1-rc.2",
138
+ "@deepseek-ai/dsh-tool-skill": "^0.1.1-rc.2",
139
+ "@shikijs/core": "4.4.3",
140
+ "@shikijs/engine-javascript": "4.4.3",
141
+ "@shikijs/langs": "4.4.3",
142
+ "@wasm-fmt/ruff_fmt": "0.15.20",
143
+ "sql-formatter": "15.8.2"
128
144
  },
129
145
  "peerDependencies": {
130
146
  "@deepseek-ai/dsh-agent": "0.1.1-rc.2",
@@ -144,6 +160,14 @@
144
160
  "@deepseek-ai/dsh-system-prompt": "0.1.1-rc.2",
145
161
  "@deepseek-ai/cordis": "^4.0.1",
146
162
  "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
147
- "react": "^18.3.1"
163
+ "react": "^18.3.1",
164
+ "@deepseek-ai/dsh-storage-domain": "0.1.1-rc.2",
165
+ "@deepseek-ai/dsh-client-ui-input-trigger": "0.1.1-rc.2",
166
+ "@deepseek-ai/dsh-workspace": "0.1.1-rc.2",
167
+ "@deepseek-ai/dsh-client-ui-sidebar": "0.1.1-rc.2",
168
+ "@deepseek-ai/dsh-client-ui-layout": "0.1.1-rc.2",
169
+ "@deepseek-ai/dsh-shell": "0.1.1-rc.2",
170
+ "@deepseek-ai/dsh-sandbox": "0.1.1-rc.2",
171
+ "@deepseek-ai/dsh-atomic-write": "0.1.1-rc.2"
148
172
  }
149
173
  }
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: dsh-data-analysis-presentation
3
+ description: 将 Marivo 分析结果或已有 Workspace 数据展示为图表、表格、报告、看板或来源面板,并一次交付可打开的 reader 与离线 HTML。适用于需要可视展示或保存分析快照的请求;普通事实问答使用文字。
4
+ ---
5
+
6
+ # Marivo 分析展示
7
+
8
+ 用一份 JSON 草稿组织已有结果,再调用一次 `marivo_present` 完成检查、Web 阅读与离线 HTML。单图、表格、报告和看板使用同一流程。
9
+
10
+ ## 从问题到交付
11
+
12
+ 1. 先确定问题、数据范围和要表达的结论。需要新分析时,按需使用当前 Runtime 挂载的 `marivo-analysis`、`marivo-semantic` 与 `marivo_help` 了解公开能力;通过 `marivo_python` 执行,声明本次精确 datasource names,凭据准备由该调用完成。已有结果可直接展示,无需先激活分析 Skill。此 Skill 只定义展示,不代替 live Help 或 Marivo 的分析、质量与 lineage 契约。
13
+ 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 的计算正确。
14
+ 3. 根据报告需要决定是否启用全局筛选;默认不添加。需要按维度交互时,先读 [全局筛选与动态指标](references/interaction.md),准备每种单选组合(含全部)的 KPI、图表与表格结果,全部受影响组件放进同一区域。缺少组合数据就减少筛选或回到分析阶段准备,不交付局部响应的全局控件。写草稿前读 [schema 与文件边界](references/schema.md);报告、看板及比较型展示还必须先读 [叙事与证据检查](references/narrative.md),按需读 [图形配置](references/charts.md)与[可改写示例](references/examples.md)。逐项对应用户问题,确定各比较的两侧、方向、分母及尚缺分支;核对原值、差值、比例、合计和余项,让正文结论与证据强度一致。用普通文件能力在当前 Workspace 写草稿;草稿与 computed 路径都相对于 Workspace 根目录。来源事实与 unavailable 状态由 builder 读取,不手填。
15
+ 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。修复展示错误也不自动重放分析。
16
+ 5. 交付主要结论、未完成分支、实质限制和 receipt 的打开/下载入口;headless 时给出 receipt 的精确文件路径。computed 来源不可恢复时如实保留 unavailable;区分 Agent 预筛选与 writer 截断,局部展示不能冒充全量总计或排名。只声明实际做过的浏览器检查。用户可在宿主阅读器编辑呈现并保存同一报告,支持 cell 移动、删除(可删空)及撤销。原卡片重开时解析当前保存构建;固定 Build 链接和离线 HTML 保留原快照。筛选选择只是临时展示,不进入保存或下载;动态指标选取已准备的组合结果,reader 不重算。
17
+
18
+ ## 修改已有报告
19
+
20
+ 用户要求修改、合并 KPI 或刷新这份报告时,修改完整 Draft,并向 `marivo_present` 成对传入实际 `report_id` 与本次修改基于的 `expected_build_id`,保存为同一 Report 的新 Build。以已读取的保存内容为基准,保留用户需要的阅读器编辑;不按标题或草稿路径猜身份,不修改生成文件。新建独立报告时才省略这两个参数。更新前读取方式与冲突处理见 [报告更新](references/schema.md#报告更新);冲突时核对当前内容,不能仅替换 expected ID 强行重试。
21
+
22
+ ## 来源追问
23
+
24
+ 简短来源问题可通过 Marivo 公开 Python API 回答。需要可视来源面板时,使用 `datasets: []` 与 `source` block,无需制造图表或 dataset。需要保留生成脚本时,将成功 `marivo_python` 返回的 `codeRef` 写入相应 dataset 的 `codeRefs`,详见 [生成代码](references/schema.md#生成代码);Artifact 执行 SQL 自动读取,执行记录与数据集的关联不构成计算正确性证明。打开、下载和来源展开读取生成时保存的快照;用户要求新范围、刷新或进一步分析时回到普通分析流程。
@@ -0,0 +1,18 @@
1
+ # 全部图形的可运行样例
2
+
3
+ 全部数据为合成演示,不是真实业务结论。在当前 Workspace 运行 [write-charts.py](examples/write-charts.py),使用已有 bound Runtime 和 presentation writer,再将[完整草稿](examples/charts.draft.json)写入 Workspace 并调用 marivo_present。
4
+
5
+ 示例包含 18 个类型、bar/line 变体、数据点、参考线和精确小数。line 的 preparedViews 可以切换为已准备的散点、分箱、比例、箱线和瀑布数据;不在浏览器计算统计量。
6
+
7
+ | 数据文件 | 内容 |
8
+ | --- | --- |
9
+ | [charts-series.dataset.json](examples/charts-series.dataset.json) | 12 个有序时点、两列指标、散点坐标、大小和分类 |
10
+ | [charts-shares.dataset.json](examples/charts-shares.dataset.json) | 两列占比及分母 |
11
+ | [charts-bins.dataset.json](examples/charts-bins.dataset.json) | 明确区间边界与频数 |
12
+ | [charts-boxes.dataset.json](examples/charts-boxes.dataset.json) | 已计算五数摘要 |
13
+ | [charts-composition.dataset.json](examples/charts-composition.dataset.json) | 原值、占比和排名 |
14
+ | [charts-funnel.dataset.json](examples/charts-funnel.dataset.json) | 有序阶段、原值和首阶段占比 |
15
+ | [charts-waterfall.dataset.json](examples/charts-waterfall.dataset.json) | 步骤角色、变化量与累计坐标 |
16
+ | [charts-precision.dataset.json](examples/charts-precision.dataset.json) | 精确 decimal 与 null,显式近似绘图 |
17
+
18
+ Python 示例演示分析阶段的数据准备。真实任务先核实粒度、范围、分母和来源,再填写可恢复 Artifact 引用。computed 路径相对于 Workspace 根目录。
@@ -0,0 +1,55 @@
1
+ # 图形配置与数值表达
2
+
3
+ 所有图形共享 `datasetId`、`chart`、`x`、`y`、`numericMode`。字段绑定使用列 ID,名称和单位来自 dataset;图前说明用 markdown。reader 保留输入行顺序,统计计算先在分析阶段完成。
4
+
5
+ ## 图形选择与字段
6
+
7
+ | chart | x / y | bindings 与数据要求 |
8
+ | --- | --- | --- |
9
+ | `line`、`area` | 有序 x,多列 y | 无;固定 monotone |
10
+ | `stackedArea` | 有序 x,同单位多列 y | 无;先对齐系列,不补零 |
11
+ | `sparkline` | 有序 x,单列 y | 无;紧凑趋势 |
12
+ | `bar`、`horizontalBar` | 类别 x,单列或多列 y | 无;单系列或并列比较 |
13
+ | `stackedBar`、`horizontalStackedBar` | 类别 x,同单位多列 y | 无;普通堆叠 |
14
+ | `stackedBar100`、`horizontalStackedBar100` | 类别 x,预计算比例 y | `denominator`:分母列;比例为 0–1 |
15
+ | `histogram` | 区间标签 x,频数 y(单列) | `binStart`、`binEnd`:已排序、不重叠的区间边界 |
16
+ | `boxPlot` | 分组 x,中位数 y(单列) | `minimum`、`q1`、`q3`、`maximum`:五数摘要 |
17
+ | `scatter` | 数值 x,数值 y(单列) | 可选 `size`、`label`、`color`:点大小、标签、分类字段 |
18
+ | `heatmap` | 行类别 x,矩阵各列 y | 无;每行是已准备矩阵行 |
19
+ | `pie` | 切片标签 x,原值 y(单列) | `share`:预计算占比;默认环形 |
20
+ | `leaderboard` | 类别 x,数值 y(单列) | `rank`:预计算排名;先确定排序和 Top N |
21
+ | `funnel` | 有序阶段 x,原值 y(单列) | `share`:相对于明确首阶段分母的预计算占比 |
22
+ | `waterfall` | 有序步骤 x,变化量/锚点值 y(单列) | `start`、`end`:已有坐标;`role` 列取 start、delta、subtotal、total |
23
+
24
+ `bindings` 的值都是同一 dataset 的列 ID,不是数值或公式。例如箱线图:
25
+
26
+ ```json
27
+ {"id":"distribution","kind":"chart","datasetId":"summary","chart":"boxPlot","x":"group","y":["median"],"numericMode":"exact","bindings":{"minimum":"min","q1":"p25","q3":"p75","maximum":"max"}}
28
+ ```
29
+
30
+ 堆叠系列与 heatmap 必须同单位;普通多系列图的不同单位分图展示。没有双轴或单位推断。100% 堆叠的分母为零/null 时比例也必须 null。pie/funnel 仅绑定预计算 share,作者须说明分母;share 范围为 [0,1],pie 完整快照的已知 share 总和不超过 1,允许不足 1。null share 不绘制切片;share 已知但原值缺失时保留该角度空位。瀑布 delta 步的 end - start 必须等于 y;锚点从零绘制,不重新累计。reader 不把缺失值补为零,不修正不合法统计量。
31
+
32
+ ## 受限选项
33
+
34
+ `options` 只接受以下声明,各类型仅接受适用选项:
35
+
36
+ - `showPoints: "auto" | "always" | "never"`:趋势图数据点,默认 auto 保留孤立观测。
37
+ - `series`:以 y 列 ID 为 key,值可有 `lineStyle: "solid" | "dashed" | "dotted"` 与 `role: "actual" | "baseline" | "target" | "forecast" | "plan" | "comparison"`。计划/目标/基线/预测默认为中性虚线,显式线型优先。
38
+ - `valueLabels: "none" | "auto" | "all"`:数值标签;原值始终保留在 tooltip。
39
+ - `referenceLines: [{"axis":"y","value":20,"label":"参考值"}]`:数值轴参考线。axis 是物理轴;横向柱形和箱线图的数值轴为 x。pie、funnel、heatmap、sparkline 不提供参考线。普通多系列图若含不同单位,该系列数值轴不接受参考线,须为各单位分别声明图表或已准备视图;scatter、histogram 的两个独立数值轴可各自设置参考线。
40
+
41
+ 不写 linear/step、任意配置、前端 aggregate 或时间分粒度。
42
+
43
+ ## 探索与已准备视图
44
+
45
+ chart 可有 `preparedViews`:每项包含唯一 `id`、说明性 `label` 和完整 `datasetId`、`chart`、`x`、`y`、`numericMode` 及适用 bindings/options。它不包含 kind,不嵌套 preparedViews;dataset 必须已在草稿声明。
46
+
47
+ 普通图形可以选择当前数值列和适用类型。需要另一组分箱、分位数、分母或累计值时,先准备 dataset,再声明视图。reader 不按列名猜统计角色,不能使用的类型显示缺少的数据。
48
+
49
+ cell 菜单“探索图表”提供图形、字段、系列、方向/模式、线型、分类过滤和恢复原图。过滤与显隐只改变当前可见内容,原始排名、占比和分母保持不变。来源预览和复制上下文跟随当前视图;下载和打印使用原始快照。重新打开恢复作者配置,不保存探索状态。
50
+
51
+ ## 精度与叙事
52
+
53
+ `exact` 适用于 float64 和 JS 安全整数范围内的 int64。decimal 或较大 int64 只用表格,或显式 `approximate` 绘图;所有数值坐标必须有限。tooltip、来源预览和静态表格保留原始精确文本。null 是缺失,不是 0;空数据展示空状态。
54
+
55
+ 比较图先读[叙事与证据检查](narrative.md),核对字段、方向、单位、分母、范围与正文一致。Top N 保留选取范围与其他项贡献;截断数据不代表全量,绘制成功不证明计算或因果结论成立。完整示例见[图形样例](chart-examples.md)。
@@ -0,0 +1,27 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "title": "演示:已有 Artifact 表格",
4
+ "datasets": [
5
+ {
6
+ "id": "result",
7
+ "kind": "artifact",
8
+ "sourceId": "analysis",
9
+ "rowLimit": 100,
10
+ "columns": ["region", "revenue"]
11
+ }
12
+ ],
13
+ "sources": [
14
+ {
15
+ "id": "analysis",
16
+ "ref": { "sessionId": "example-session", "artifactRef": "example-artifact" }
17
+ }
18
+ ],
19
+ "blocks": [
20
+ {
21
+ "id": "scope",
22
+ "kind": "markdown",
23
+ "text": "演示草稿:请替换实际来源、列名和分析范围。展示最多 100 行,不据此声称全量总计。"
24
+ },
25
+ { "id": "values", "kind": "table", "datasetId": "result", "columns": ["region", "revenue"] }
26
+ ]
27
+ }
@@ -0,0 +1,33 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "columns": [
4
+ {
5
+ "id": "bin",
6
+ "label": "bin",
7
+ "type": "string",
8
+ "nullable": false
9
+ },
10
+ {
11
+ "id": "lower",
12
+ "label": "lower",
13
+ "type": "float64",
14
+ "nullable": false
15
+ },
16
+ {
17
+ "id": "upper",
18
+ "label": "upper",
19
+ "type": "float64",
20
+ "nullable": false
21
+ },
22
+ {
23
+ "id": "frequency",
24
+ "label": "frequency",
25
+ "type": "float64",
26
+ "nullable": false
27
+ }
28
+ ],
29
+ "rows": [["0–1", 0, 1, 2], ["1–3", 1, 3, 3], ["3–6", 3, 6, 1]],
30
+ "rowCount": 3,
31
+ "limit": 5000,
32
+ "truncated": false
33
+ }
@@ -0,0 +1,45 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "columns": [
4
+ {
5
+ "id": "group",
6
+ "label": "group",
7
+ "type": "string",
8
+ "nullable": false
9
+ },
10
+ {
11
+ "id": "minimum",
12
+ "label": "minimum",
13
+ "type": "float64",
14
+ "nullable": false
15
+ },
16
+ {
17
+ "id": "q1",
18
+ "label": "q1",
19
+ "type": "float64",
20
+ "nullable": false
21
+ },
22
+ {
23
+ "id": "median",
24
+ "label": "median",
25
+ "type": "float64",
26
+ "nullable": false
27
+ },
28
+ {
29
+ "id": "q3",
30
+ "label": "q3",
31
+ "type": "float64",
32
+ "nullable": false
33
+ },
34
+ {
35
+ "id": "maximum",
36
+ "label": "maximum",
37
+ "type": "float64",
38
+ "nullable": false
39
+ }
40
+ ],
41
+ "rows": [["A", 1, 2, 3, 4, 5], ["B", 2, 3, 4, 5, 6]],
42
+ "rowCount": 2,
43
+ "limit": 5000,
44
+ "truncated": false
45
+ }
@@ -0,0 +1,33 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "columns": [
4
+ {
5
+ "id": "category",
6
+ "label": "category",
7
+ "type": "string",
8
+ "nullable": false
9
+ },
10
+ {
11
+ "id": "value",
12
+ "label": "value",
13
+ "type": "float64",
14
+ "nullable": false
15
+ },
16
+ {
17
+ "id": "share",
18
+ "label": "share",
19
+ "type": "float64",
20
+ "nullable": false
21
+ },
22
+ {
23
+ "id": "rank",
24
+ "label": "rank",
25
+ "type": "float64",
26
+ "nullable": false
27
+ }
28
+ ],
29
+ "rows": [["A", 60, 0.6, 1], ["B", 30, 0.3, 2], ["C", 10, 0.1, 3]],
30
+ "rowCount": 3,
31
+ "limit": 5000,
32
+ "truncated": false
33
+ }
@@ -0,0 +1,27 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "columns": [
4
+ {
5
+ "id": "stage",
6
+ "label": "stage",
7
+ "type": "string",
8
+ "nullable": false
9
+ },
10
+ {
11
+ "id": "value",
12
+ "label": "value",
13
+ "type": "float64",
14
+ "nullable": false
15
+ },
16
+ {
17
+ "id": "share",
18
+ "label": "share",
19
+ "type": "float64",
20
+ "nullable": false
21
+ }
22
+ ],
23
+ "rows": [["访问", 100, 1], ["注册", 60, 0.6], ["购买", 20, 0.2]],
24
+ "rowCount": 3,
25
+ "limit": 5000,
26
+ "truncated": false
27
+ }
@@ -0,0 +1,21 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "columns": [
4
+ {
5
+ "id": "label",
6
+ "label": "label",
7
+ "type": "string",
8
+ "nullable": false
9
+ },
10
+ {
11
+ "id": "amount",
12
+ "label": "amount",
13
+ "type": "decimal",
14
+ "nullable": true
15
+ }
16
+ ],
17
+ "rows": [["精确值", "0.1000"], ["缺失", null], ["长小数", "12345678901234.5678"]],
18
+ "rowCount": 3,
19
+ "limit": 5000,
20
+ "truncated": false
21
+ }
@@ -0,0 +1,58 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "columns": [
4
+ {
5
+ "id": "period",
6
+ "label": "period",
7
+ "type": "string",
8
+ "nullable": false
9
+ },
10
+ {
11
+ "id": "a",
12
+ "label": "a",
13
+ "type": "float64",
14
+ "nullable": false
15
+ },
16
+ {
17
+ "id": "b",
18
+ "label": "b",
19
+ "type": "float64",
20
+ "nullable": false
21
+ },
22
+ {
23
+ "id": "coordinate",
24
+ "label": "coordinate",
25
+ "type": "float64",
26
+ "nullable": false
27
+ },
28
+ {
29
+ "id": "volume",
30
+ "label": "volume",
31
+ "type": "float64",
32
+ "nullable": false
33
+ },
34
+ {
35
+ "id": "segment",
36
+ "label": "segment",
37
+ "type": "string",
38
+ "nullable": false
39
+ }
40
+ ],
41
+ "rows": [
42
+ ["2026-01", 12, 8, 1, 10, "A"],
43
+ ["2026-02", 18, 11, 2, 20, "B"],
44
+ ["2026-03", 15, 10, 3, 30, "A"],
45
+ ["2026-04", 24, 14, 4, 40, "B"],
46
+ ["2026-05", 19, 13, 5, 50, "A"],
47
+ ["2026-06", 30, 17, 6, 60, "B"],
48
+ ["2026-07", 28, 19, 7, 70, "A"],
49
+ ["2026-08", 34, 18, 8, 80, "B"],
50
+ ["2026-09", 31, 22, 9, 90, "A"],
51
+ ["2026-10", 42, 25, 10, 100, "B"],
52
+ ["2026-11", 39, 24, 11, 110, "A"],
53
+ ["2026-12", 45, 28, 12, 120, "B"]
54
+ ],
55
+ "rowCount": 12,
56
+ "limit": 5000,
57
+ "truncated": false
58
+ }
@@ -0,0 +1,33 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "columns": [
4
+ {
5
+ "id": "category",
6
+ "label": "category",
7
+ "type": "string",
8
+ "nullable": false
9
+ },
10
+ {
11
+ "id": "a",
12
+ "label": "a",
13
+ "type": "float64",
14
+ "nullable": false
15
+ },
16
+ {
17
+ "id": "b",
18
+ "label": "b",
19
+ "type": "float64",
20
+ "nullable": false
21
+ },
22
+ {
23
+ "id": "denominator",
24
+ "label": "denominator",
25
+ "type": "float64",
26
+ "nullable": false
27
+ }
28
+ ],
29
+ "rows": [["A", 0.6, 0.4, 100], ["B", 0.3, 0.7, 200], ["C", 0.8, 0.2, 50]],
30
+ "rowCount": 3,
31
+ "limit": 5000,
32
+ "truncated": false
33
+ }
@@ -0,0 +1,44 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "columns": [
4
+ {
5
+ "id": "step",
6
+ "label": "step",
7
+ "type": "string",
8
+ "nullable": false
9
+ },
10
+ {
11
+ "id": "change",
12
+ "label": "change",
13
+ "type": "float64",
14
+ "nullable": false
15
+ },
16
+ {
17
+ "id": "start",
18
+ "label": "start",
19
+ "type": "float64",
20
+ "nullable": false
21
+ },
22
+ {
23
+ "id": "end",
24
+ "label": "end",
25
+ "type": "float64",
26
+ "nullable": false
27
+ },
28
+ {
29
+ "id": "role",
30
+ "label": "role",
31
+ "type": "string",
32
+ "nullable": false
33
+ }
34
+ ],
35
+ "rows": [
36
+ ["期初", 100, 0, 100, "start"],
37
+ ["减少", -20, 100, 80, "delta"],
38
+ ["增加", 30, 80, 110, "delta"],
39
+ ["期末", 110, 0, 110, "total"]
40
+ ],
41
+ "rowCount": 4,
42
+ "limit": 5000,
43
+ "truncated": false
44
+ }