@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

package/lib/types/semantic-reference/contracts.d.ts

@@ -0,0 +1,54 @@
+/** Browser-safe wire contracts. These bounds do not reimplement Marivo's domain grammar. */
+export declare const CHANNEL = "/dsh-data-analysis";
+export declare const SOURCE = "marivo-semantic";
+export declare const MAX_WIRE_BYTES: number;
+export interface SemanticRef {
+    readonly schema: 'marivo.semantic_ref/v1';
+    readonly kind: string;
+    readonly path: string;
+}
+export interface Envelope {
+    readonly schema: 'dsh-data-analysis-semantic-reference/v1';
+    readonly sessionId: string;
+    readonly environmentFingerprint: string;
+    readonly ref: SemanticRef;
+}
+export interface Candidate {
+    readonly ref: SemanticRef;
+    readonly refKey: string;
+    readonly name: string;
+    readonly businessDefinition: string | null;
+}
+export interface Projection {
+    readonly kinds: readonly string[];
+    readonly items: readonly Candidate[];
+}
+export interface RankedCandidate extends Candidate {
+    readonly section: 'recent' | 'kind' | 'strict' | 'fuzzy';
+}
+export interface CandidatesResponse {
+    readonly environmentFingerprint: string;
+    readonly items: readonly RankedCandidate[];
+}
+export declare function closed(value: unknown, keys: readonly string[]): Record<string, unknown>;
+export declare function boundedText(value: unknown, max: number, empty?: boolean): string;
+export declare function parseJson(value: unknown, max?: number): unknown;
+export declare function parseRef(value: unknown): SemanticRef;
+export declare function refKey(ref: SemanticRef): string;
+export declare function parseEnvelope(value: unknown): Envelope;
+export declare function envelopeJson(envelope: Envelope): string;
+export declare function modelMarker(envelope: Envelope): string;
+export declare function parseCandidate(value: unknown): Candidate;
+export declare function parseProjection(value: unknown): Projection;
+export declare function parseCandidatesRequest(value: unknown): {
+    version: number;
+    sessionId: string;
+    query: string;
+    quoted: boolean;
+};
+export declare function parseCandidatesResponse(value: unknown): CandidatesResponse;
+/** Browser selection identity only; preparation never reloads semantic content. */
+export declare function parsePrepareRequest(value: unknown): {
+    workspaceId: string;
+    envelope: Envelope;
+};

package/lib/types/semantic-reference/environment.d.ts

@@ -0,0 +1,22 @@
+import type { MarivoCheckedRunner } from '../environment/types.ts';
+import type { EnvironmentResolver } from './rpc.ts';
+interface Workspace {
+    id: string;
+    path: string;
+}
+interface Binding {
+    root: string;
+    environment: Promise<MarivoCheckedRunner>;
+}
+export interface ReferenceEnvironmentHost<A extends object> {
+    agent(sessionId: string): A | undefined;
+    binding(agent: A): Binding | undefined;
+    projectRoot(agent: A): string;
+    resolve(agent: A): Promise<MarivoCheckedRunner>;
+    workspace(sessionId: string): Workspace;
+}
+/** Reference identity includes Harness ownership; the underlying Runtime stays unchanged. */
+export declare function semanticEnvironmentFingerprint(workspaceId: string, runtimeFingerprint: string): string;
+/** Explicit selection establishes ownership; serialization never repairs it. */
+export declare function referenceEnvironmentResolver<A extends object>(host: ReferenceEnvironmentHost<A>): EnvironmentResolver;
+export {};

package/lib/types/semantic-reference/index.d.ts

@@ -0,0 +1,3 @@
+export { SemanticReferenceBridge } from './bridge.ts';
+export { registerSemanticReferenceRpc, SemanticReferenceService } from './rpc.ts';
+export { SemanticReferenceUsage } from './usage.ts';

package/lib/types/semantic-reference/labels.d.ts

@@ -0,0 +1,16 @@
+/** Shared display labels and search aliases; object kinds still come from the live Catalog. */
+export declare const semanticKindLabels: {
+    readonly domain: "业务域";
+    readonly datasource: "数据源";
+    readonly entity: "实体";
+    readonly dimension: "维度";
+    readonly measure: "度量";
+    readonly time_dimension: "时间维度";
+    readonly metric: "指标";
+    readonly relationship: "关系";
+    readonly event: "事件";
+    readonly state_model: "状态模型";
+    readonly period_calendar: "周期日历";
+    readonly temporal_set: "时间集合";
+    readonly work_schedule: "工作日程";
+};

package/lib/types/semantic-reference/rpc.d.ts

@@ -0,0 +1,15 @@
+import type { ConnectionRpcHandler, HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
+import type { MarivoCheckedRunner } from '../environment/types.ts';
+import { SemanticReferenceBridge } from './bridge.ts';
+import { type SemanticReferenceUsage } from './usage.ts';
+export type EnvironmentResolver = (sessionId: string, purpose: 'candidates' | 'reference' | 'prepare', workspaceId?: string) => Promise<MarivoCheckedRunner>;
+/** Abort the caller's wait, without pretending to cancel the shared Environment resolver. */
+export declare function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;
+export declare class SemanticReferenceService {
+    #private;
+    constructor(resolve: EnvironmentResolver, usage: SemanticReferenceUsage, bridge?: SemanticReferenceBridge);
+    handle(endpoint: string, payload: unknown, caller: AbortSignal): Promise<unknown>;
+    stop(): void;
+    close(): Promise<void>;
+}
+export declare function registerSemanticReferenceRpc(connection: HostConnectionHandle, service: SemanticReferenceService, browser?: ConnectionRpcHandler): () => Promise<void>;

package/lib/types/semantic-reference/search.d.ts

@@ -0,0 +1,10 @@
+import type { Projection, RankedCandidate } from './contracts.ts';
+export interface UsageScore {
+    readonly count: number;
+    readonly last: number;
+}
+export type UsageScores = ReadonlyMap<string, UsageScore>;
+export declare function normalize(text: string): string;
+export declare function compareText(a: string, b: string): number;
+export declare function dice(a: string, b: string): number;
+export declare function search(projection: Projection, rawQuery: string, usage?: UsageScores): readonly RankedCandidate[];

package/lib/types/semantic-reference/usage.d.ts

@@ -0,0 +1,43 @@
+import { type DomainFacility } from '@deepseek-ai/dsh-storage-domain';
+import { z } from 'zod';
+import { type SemanticRef } from './contracts.ts';
+import type { UsageScores } from './search.ts';
+export declare const usageSchema: z.ZodObject<{
+    entries: z.ZodRecord<z.ZodString, z.ZodObject<{
+        ref: z.ZodPipe<z.ZodUnknown, z.ZodTransform<SemanticRef, unknown>>;
+        days: z.ZodArray<z.ZodObject<{
+            day: z.ZodISODate;
+            count: z.ZodNumber;
+        }, z.core.$strict>>;
+        lastSelectedAt: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type UsageWorkspace = z.infer<typeof usageSchema>;
+export declare const usageSpec: {
+    name: string;
+    version: number;
+    tables: {
+        workspaces: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            entries: Record<string, {
+                ref: SemanticRef;
+                days: {
+                    day: string;
+                    count: number;
+                }[];
+                lastSelectedAt: number;
+            }>;
+        }>;
+    };
+};
+export declare function workspaceKey(canonicalRoot: string): string;
+export declare function localDay(date: Date): string;
+export declare function windowDays(now: number): string[];
+export declare function increment(row: UsageWorkspace, input: SemanticRef, now: number): UsageWorkspace;
+/** Only admitted mutations join the per-Workspace queue; close drains those jobs. */
+export declare class SemanticReferenceUsage {
+    #private;
+    constructor(facility: Pick<DomainFacility, 'open'>, clock?: () => number, diagnostic?: () => void);
+    scores(key: string): Promise<UsageScores>;
+    selected(key: string, ref: SemanticRef, signal: AbortSignal): Promise<void>;
+    close(): Promise<void>;
+}

package/lib/types/tool-lifecycle.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+/** A plugin tool owns its execution promises; withdrawing its schema is not a drain. */
+export declare function registerMarivoTool(ctx: Context, tool: ToolDefinition): () => Promise<void>;

package/lib/types/workspace-identity.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Resolve only Harness-owned, header-validated Workspace membership; never infer it from a path. */
+export declare function resolvePresentationWorkspace(ctx: Context, sessionId: string): {
+    id: string;
+    path: string;
+};

package/lib/workspace-identity.js

@@ -0,0 +1,9 @@
+/** Resolve only Harness-owned, header-validated Workspace membership; never infer it from a path. */
+export function resolvePresentationWorkspace(ctx, sessionId) {
+    const matches = ctx.workspaceRegistry
+        .list()
+        .filter((workspace) => workspace.sessionIds.some((id) => String(id) === sessionId));
+    if (matches.length !== 1)
+        throw new Error('Presentation requires one current Session Workspace');
+    return { id: String(matches[0].id), path: matches[0].path };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chengxianglibra/dsh-data-analysis",
-  "description": "Marivo runtime, live-help, datasource, and on-demand Evidence source integration for DeepSeek Harness",
-  "version": "0.1.1",
+  "description": "Marivo runtime, live Help, secure datasource execution and presentation delivery for DeepSeek Harness",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chengxianglibra/dsh-data-analysis.git",
@@ -14,12 +14,13 @@
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.19.0 || >=24.0.0"
   },
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
   "bin": {
-    "dsh-data-analysis-env": "./lib/bin/environment.js"
+    "dsh-data-analysis-env": "./lib/bin/environment.js",
+    "dsh-data-analysis-presentation-lint": "./lib/bin/presentation-lint.js"
   },
   "exports": {
     ".": {
@@ -42,10 +43,6 @@
       "types": "./lib/types/datasource/index.d.ts",
       "default": "./lib/datasource/index.js"
     },
-    "./evidence": {
-      "types": "./lib/types/evidence/index.d.ts",
-      "default": "./lib/evidence/index.js"
-    },
     "./compatibility": {
       "types": "./lib/types/compatibility.d.ts",
       "default": "./lib/compatibility.js"
@@ -56,16 +53,17 @@
   "files": [
     "lib/**/*.js",
     "lib/types/**/*.d.ts",
-    "python/report-kit/dist/dsh_data_analysis_report_kit-3.0.0-py3-none-any.whl",
-    "skills/**/*",
+    "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"
   ],
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/finalize-build.mjs",
-    "build:report-kit": "node scripts/build-report-kit.mjs",
     "clean": "node scripts/clean.mjs",
-    "prepack": "npm run build:report-kit && npm run build"
+    "prepack": "npm run build:presentation-kit && npm run build",
+    "build:presentation-kit": "node scripts/build-presentation-kit.mjs"
   },
   "publishConfig": {
     "access": "public",
@@ -75,14 +73,14 @@
     "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.3",
-      "packageSpec": "marivo[duckdb,trino,clickhouse]==0.5.3"
+      "version": "0.5.5",
+      "packageSpec": "marivo[duckdb,trino,clickhouse]==0.5.5"
     },
     "contracts": {
-      "runtimeInstallation": "dsh-data-analysis-runtime/v2",
+      "runtimeInstallation": "dsh-data-analysis-runtime/v3",
       "subprocessPolicy": "direct-argv-inherited-env-snapshot-overlay-v2"
     }
   },
@@ -90,10 +88,17 @@
     "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-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-sidebar-right"
       ],
       "platform": "web"
     },
@@ -102,48 +107,89 @@
     }
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@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",
-    "ajv": "^8.20.0",
+    "@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",
+    "@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",
-    "typescript": "^6.0.3"
+    "react-dom": "18.3.1",
+    "react-is": "18.3.1",
+    "recharts": "3.8.1",
+    "sql-formatter": "15.8.2",
+    "typescript": "^6.0.3",
+    "zustand": "4.4.7"
   },
   "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"
   }
 }

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

@@ -0,0 +1,32 @@
+---
+name: dsh-data-analysis-files
+description: 分析已上传或 Workspace 中的 CSV、JSON、Parquet、Excel 文件，使用 pandas 或 DuckDB 计算，按需导出 CSV、JSON、PNG 等普通文件或接入报告。无需先建立 Marivo datasource 或语义模型。
+---
+
+# 文件分析
+
+使用 Harness 提供的当前附件可读路径，或用户指定的 Workspace 文件；同名附件按消息和完整路径区分。路径不可读时报告实际问题，不猜测 Host 缓存位置。
+
+文件读取、计算和最终文件生成（包括 CSV、JSON、PNG）均通过 `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` 不代表仅扫描这些行。
+
+## 按用户目标交付
+
+普通答案直接用文字，不为结论额外创建文件。用户要求 CSV、JSON、PNG 等实际文件时，先通过 `marivo_python` 生成最终文件，优先写入当前绑定 Workspace；确认执行成功、文件存在后，调用当前实际可用的 Harness 原生 `present`，再回复用户。回复前分别核对文件生成与原生声明状态：生成文件、回复路径或展示代码块均不能替代原生交付。缺少 `present` 时，最终回复必须说明“文件已生成，原生交付能力不可用”，并提供准确路径；不能只说文件已生成。不猜测附件缓存或 Shell 私有临时目录。
+
+需要交互图表、表格、报告或看板时加载 `dsh-data-analysis-presentation`，将 DataFrame 交给现有 writer，并关联实际返回的 `codeRef`，使用 `marivo_present` 保存固定 Build。在正文说明文件名与分析范围，不将文件结果冒充 Marivo Artifact 或 Evidence。普通 `present` 不赋予文件 Report/Build 或 Evidence 身份。
+
+报告内部的 `presentation.json`、computed 数据和 receipt 不作为默认附件；只有用户另行要求实际文件且文件已经存在于 Session 文件系统可访问位置时，才调用 `present`。阅读器下载／发布 HTML 沿用现有流程，浏览器内生成的下载不伪装成 Session 文件。
+
+## 能力与失败
+
+遵循 Harness [present 契约](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.5-rc.1/packages/fs/tool-present/README.md)，由工具验证路径和文件类型。当前工具集中缺少 `present` 时，明确说明“文件已生成，原生交付能力不可用”，提供实际准确路径供手动使用，不虚构卡片，不安装工具或改写 profile。
+
+生成失败不声明成功；声明失败区分“文件已生成”和“交付未完成”，修复路径或可见性后只重试交付，不为补卡片重跑分析。响应不确定时先核对已有调用结果和事件，不盲目重复声明。原生打开失败时使用 Host 的预览或错误反馈，不绕过权限。
+
+卡片打开当前源文件，不保存内容版本；修改、移动或删除会影响后续读取。成功声明的持久事件属于 Harness，即使 PTC 外层程序随后失败，也不撤销已成功的声明。子代理产物属于其调用 Session；父 Agent 如需交付，先确认自己能访问文件，再在父 Session 显式调用 `present`，不自动跨 Session 转投递。
+
+需要起步代码时读[简短示例](references/examples.md)；其中提供无需额外依赖的 PNG 写入代码，也通过 `marivo_python` 执行。

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

@@ -0,0 +1,28 @@
+---
+name: dsh-data-analysis-presentation
+description: 将 Marivo 分析结果或已有 Workspace 数据展示为图表、表格、报告、看板或来源面板，并交付在右侧 tab 打开的 reader。适用于需要可视展示或保存分析快照的请求；普通事实问答使用文字。
+---
+
+# Marivo 分析展示
+
+用 JSON 草稿组织已有结果，调用 `marivo_present` 保存并打开阅读器。
+
+## 从问题到交付
+
+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` 并打开右侧 tab；普通展示不额外生成 HTML 或挂报告 block。用户可在阅读器按配置发布或下载 HTML。失败按诊断的 `code`、`path`、原因和建议修正草稿或数据，再重试；没有成功 receipt 就不宣称交付完成。缺少 Artifact 保存数据时报告缺失，不为完成展示自动重新查询、observe 或 revalidate。修复展示错误也不自动重放分析。
+5. 交付主要结论、未完成分支、实质限制和 报告已在右侧 tab 打开的简短说明；headless 时给出 receipt 的精确文件路径。computed 来源不可恢复时如实保留 unavailable；区分 Agent 预筛选与 writer 截断，局部展示不能冒充全量总计或排名。只声明实际做过的浏览器检查。用户可在宿主阅读器编辑呈现并保存同一报告，支持 cell 移动、删除（可删空）及撤销。报告重开时解析当前保存构建；固定 Build 链接和离线 HTML 保留原快照。筛选选择只是临时展示，不进入保存或下载；动态指标选取已准备的组合结果，reader 不重算。
+
+## 修改已有报告
+
+用户要求修改、合并 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/publishing.md)使用实时披露的 `marivo_publish_report`。
+
+离线 HTML 文件按[导出与原生交付](references/export-html.md)处理：`marivo_export_html` 成功后调用 `present`。

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

@@ -0,0 +1,18 @@
+# 全部图形的可运行样例
+
+全部数据为合成演示，不是真实业务结论。在当前 Workspace 运行 [write-charts.py](examples/write-charts.py)，使用已有 bound Runtime 和 presentation writer，再将[完整草稿](examples/charts.draft.json)写入 Workspace 并调用 marivo_present。
+
+示例包含 18 个类型、bar/line 变体、数据点、参考线和精确小数。line 的 preparedViews 可以切换为已准备的散点、分箱、比例、箱线和瀑布数据；不在浏览器计算统计量。
+
+| 数据文件 | 内容 |
+| --- | --- |
+| [charts-series.dataset.json](examples/charts-series.dataset.json) | 12 个有序时点、两列指标、散点坐标、大小和分类 |
+| [charts-shares.dataset.json](examples/charts-shares.dataset.json) | 两列占比及分母 |
+| [charts-bins.dataset.json](examples/charts-bins.dataset.json) | 明确区间边界与频数 |
+| [charts-boxes.dataset.json](examples/charts-boxes.dataset.json) | 已计算五数摘要 |
+| [charts-composition.dataset.json](examples/charts-composition.dataset.json) | 原值、占比和排名 |
+| [charts-funnel.dataset.json](examples/charts-funnel.dataset.json) | 有序阶段、原值和首阶段占比 |
+| [charts-waterfall.dataset.json](examples/charts-waterfall.dataset.json) | 步骤角色、变化量与累计坐标 |
+| [charts-precision.dataset.json](examples/charts-precision.dataset.json) | 精确 decimal 与 null，显式近似绘图 |
+
+Python 示例演示分析阶段的数据准备。真实任务先核实粒度、范围、分母和来源，再填写可恢复 Artifact 引用。computed 路径相对于 Workspace 根目录。