@chengxianglibra/dsh-data-analysis 0.1.1

package/lib/types/plugin.d.ts

@@ -0,0 +1,43 @@
+/** Cordis lifecycle adapter for the Web-profile shared Marivo Runtime. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
+import z from '@deepseek-ai/schemastery';
+import { type MarivoHelpBridgeSource } from './disclosure/bridge.ts';
+import { type MarivoDisclosureOptions } from './disclosure/index.ts';
+import { MarivoEnvironment } from './environment/index.ts';
+/** Cordis plugin name used by loader diagnostics and lifecycle logs. */
+export declare const name = "dsh-data-analysis";
+/** Services that must exist before the plugin binds and watches Agent scopes. */
+export declare const inject: string[];
+export declare const MARIVO_DATASOURCE_CREDENTIAL_PROMPT: string;
+export declare const MARIVO_EVIDENCE_SOURCES_PROMPT: string;
+export declare const MARIVO_REPORT_PROMPT: string;
+/** Loader-safe configuration for the shared Runtime and per-Workspace bindings. */
+export interface Config {
+    /** Explicit project root override; otherwise each Agent uses session.header.cwd. */
+    readonly projectRoot?: string;
+    /** Administrator-provided shared interpreter; must already contain an importable Marivo. */
+    readonly pythonExecutable?: string;
+    /** Shared Runtime root; defaults below $DSH_HOME. */
+    readonly runtimeRoot?: string;
+    /** Local uv executable; an explicit value must be absolute. */
+    readonly uvExecutable?: string;
+    /** Maximum time for installation and lock acquisition. */
+    readonly installTimeoutMs?: number;
+}
+/** Cordis loader schema. Runtime defaults are resolved in {@link apply}. */
+export declare const Config: z<Config>;
+export type MarivoPluginEnvironmentResolver = (agent: Agent) => MarivoEnvironment | Promise<MarivoEnvironment>;
+/**
+ * Install one already-bound environment into every live or subsequently published Agent scope.
+ * Installation is transactional for existing Agents and is disposed with the Cordis plugin.
+ */
+export declare function installMarivoPlugin(ctx: Context, environmentOrResolver: MarivoEnvironment | MarivoPluginEnvironmentResolver, options?: MarivoDisclosureOptions & {
+    /** Override used by focused tests; normal plugin installation uses ctx.credentials. */
+    credentials?: Pick<CredentialProvider, 'resolve'>;
+    /** Runtime-scoped Help source; normal plugin installation never binds Help to a Workspace. */
+    helpBridgeSource?: MarivoHelpBridgeSource;
+}): () => void;
+/** Ensure the shared Runtime once, mount its skills, then bind each Workspace lazily. */
+export declare function apply(ctx: Context, config?: Config): Promise<() => void>;

package/package.json

@@ -0,0 +1,149 @@
+{
+  "name": "@chengxianglibra/dsh-data-analysis",
+  "description": "Marivo runtime, live-help, datasource, and on-demand Evidence source integration for DeepSeek Harness",
+  "version": "0.1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chengxianglibra/dsh-data-analysis.git",
+    "directory": "packages/dsh-data-analysis"
+  },
+  "homepage": "https://github.com/chengxianglibra/dsh-data-analysis#readme",
+  "bugs": {
+    "url": "https://github.com/chengxianglibra/dsh-data-analysis/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "bin": {
+    "dsh-data-analysis-env": "./lib/bin/environment.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./environment": {
+      "types": "./lib/types/environment/index.d.ts",
+      "default": "./lib/environment/index.js"
+    },
+    "./disclosure": {
+      "types": "./lib/types/disclosure/index.d.ts",
+      "default": "./lib/disclosure/index.js"
+    },
+    "./datasource": {
+      "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"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts",
+    "python/report-kit/dist/dsh_data_analysis_report_kit-3.0.0-py3-none-any.whl",
+    "skills/**/*",
+    "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"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dshDataAnalysisCompatibility": {
+    "schema": "dsh-data-analysis-compatibility/v2",
+    "dsh": {
+      "distribution": "@deepseek-ai/dsh",
+      "peerRange": "0.1.1-rc.2"
+    },
+    "marivo": {
+      "version": "0.5.3",
+      "packageSpec": "marivo[duckdb,trino,clickhouse]==0.5.3"
+    },
+    "contracts": {
+      "runtimeInstallation": "dsh-data-analysis-runtime/v2",
+      "subprocessPolicy": "direct-argv-inherited-env-snapshot-overlay-v2"
+    }
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-tool"
+      ],
+      "platform": "web"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "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",
+    "@types/react": "^18.3.31",
+    "react": "^18.3.1",
+    "typescript": "^6.0.3"
+  },
+  "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",
+    "react": "^18.3.1"
+  }
+}

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

@@ -0,0 +1,57 @@
+---
+name: dsh-data-analysis-report
+description: Create or revise a Workspace HTML analysis report only when the user explicitly requests HTML/web or a durable report file, accepts a proposal to create one, or asks to revise an existing report bundle.
+---
+
+# DSH data-analysis report
+
+本 Skill 只提供报告原则、数据读取接线与 Marivo 专属组件。页面、图表、样式、交互和通用检查由 Agent 使用普通文件与代码能力完成；插件不提供模板、chart helper、可视化 DSL、HTML Checker、通用 renderer 或 publisher。
+
+## 分析事实与 Marivo 投影
+
+### 取得报告数据
+
+先加载 `marivo-analysis`，按实时 Help 使用当前 Runtime。已有分析应恢复精确 persisted Artifacts；仅在当前有效性会影响结论时执行 identity-matched revalidation。不得只为生成页面或 DAG 重新执行 `observe`。
+
+| 输入 | Python 发射入口 | 语义边界 |
+| --- | --- | --- |
+| Marivo `BaseFrame` Artifact | `emit_dataset(artifact, target, detail="reader", revalidation=...)` | `reader` 默认只保留读者摘要与实质提示；明确审计请求才使用 `detail="audit"` 投影公共详情。 |
+| pandas `DataFrame` 计算结果 | `emit_computed(frame, target)` | 仅表示 computed snapshot，不声明 Artifact、Evidence、lineage、freshness 或 revalidation。 |
+
+两个 emitter 都生成由 `ReportData` 注册的数据文件。不要把 DataFrame 传给 `emit_dataset`，不要手写 `ReportData.register(...)` payload，也不要从浏览器 validator 反推 schema。浏览器通过 `ReportData.get(...)` 读取快照，或通过 `ReportData.records(...)` 取得行对象；图表库和 DOM/SVG/Canvas 实现仍由 Agent 自主选择。
+
+每个可见 KPI、图表和表格都要映射到一个已注册 dataset。Artifact 映射在轻量来源说明或审计区体现；computed 映射保留必要的输入与转换说明。机器 identity 不进入主叙事。
+
+### 添加 Marivo 组件
+
+- `MarivoArtifact.render(container, dataset_id)` 展示面向读者的 Artifact 摘要：正常状态仅含类型、semantic shape、行数和结果生成时间；仅在截断、Evidence 不完整、revalidation 异常、质量检查或 issues 会改变判断时追加提示。它不是 metadata inspector，不展示机器 identity、hash、Job、Finding 数量或完整 lineage。
+- 对每个实质支撑报告内容的 Marivo Session，分别用公开 `session.graph(...)` 取得聚焦 `SessionGraph`，再调用 `emit_session_trace(graph, target, report_artifact_refs=[...], detail="reader")`。只有明确审计、Lineage、质量详情、可追溯性或 action SQL/Query 请求才改用 `detail="audit"`；DAG 详情只展示投影中已有的公开 Query，bind values 仍必须省略。`report_artifact_refs` 只列该 Graph 内实际支撑可见内容的本地 Artifacts；不得跨 Session 合并、读取私有 Store 或补造事实。
+- DAG 中需要预览的本地 Frame，必须从所属精确 Session 恢复并 `emit_dataset(...)`。浏览器按 `session_id + artifact_ref` 关联；缺少快照时明确显示未注册。Artifact 详情复用 `MarivoArtifact`，Frame 节点只显示 family 与行数。
+- Graph 超出 emitter 限制时，为同一 Session 输出多个具有唯一 `trace_id` 的聚焦 Graph。`ReportTrace.renderSessionGraphs(...)` 单次最多接收 20 个 trace；超出时分批渲染，不得静默遗漏实际使用的 Session。
+
+### 装配浏览器资源
+
+按需复制 `assets/report-data.js`、`assets/marivo-artifact.js`、`assets/marivo-session-dag.js`。经典脚本顺序固定为：`report-data.js` → dataset snapshots → Marivo components → trace snapshots → Agent 自有 chart/runtime/app。使用 DAG 时必须同时加载 Artifact component，最后调用 `ReportTrace.renderSessionGraphs(container[, trace_ids])`。页面内 `dataset_id` 与 `trace_id` 必须唯一。
+
+## 内容组织
+
+- 先明确受众、决策问题、范围和约束。开头直接给答案和最重要证据，正文解释驱动因素，结尾只保留影响行动的限制与后续步骤。
+- 明确区分观测事实、Agent 推断和建议；因果与置信措辞必须匹配证据。不要用固定 KPI、摘要、方法或附录章节填充内容。
+- 每张图只回答一个问题并在附近解释；详细表格、方法和 DAG 放在可展开或靠后的区域。
+- 对范围、口径、单位、时间边界、freshness、coverage、null、截断、revalidation、失败检查和不确定性，只披露会改变解读或行动的部分。
+
+## 布局与样式
+
+- 建立清晰标题层级和阅读顺序；宽屏可分栏，窄屏回到单列。关键结论不能只靠颜色、位置、hover 或动画表达。
+- Marivo 组件只输出语义化 DOM/SVG 与 class hooks，不携带页面主题；使用 `MarivoArtifact` 或 `ReportTrace` 时，必须为生成内容补齐可读的文本、节点 fill/stroke、连线、状态、键盘焦点、详情面板与窄屏样式，并保留组件对 audit SQL 的确定性格式化。
+- 优先使用语义化结构、可读字号、充足行距、稳定留白和高对比度。颜色用于编码而非装饰；同一含义保持一致，并提供文字、图例或形状冗余。
+- 图表必须有标题、单位、时间范围、刻度与数据缺失说明；表格提供明确表头和适合内容的对齐。避免 3D、双轴、过密标签和无解释的视觉噪声。
+- 所有图表坐标轴在各目标宽度下都不得出现刻度标签彼此重叠、被裁切、侵入绘图区，或与轴标题、图例等元素重叠。按轴类型、标签长度与可用空间选择合适的格式、刻度密度、换行、方向、边距和图表尺寸；空间不足时不要强行显示每个刻度。只有保持可读时才旋转标签，完整标签与数值保留在数据表、可访问文本或按需提示中。
+- 交互只在能降低认知负担时加入；核心结论、关键数值与限制在 JavaScript 失败时仍应可读。打印或导出场景不得截断关键内容。
+
+## 生成与检查
+
+1. 新报告使用新的 Workspace 目录；修订使用用户指定或已确认的现有目录，只有需要隔离构建时才另建 staging 目录。所有资源置于目录内并使用相对路径；先写数据与资源，最后写 `index.html`。
+2. 自查内容：问题是否被直接回答；数字、单位、口径和时间是否一致；事实、推断和建议是否混淆；重要限制、截断和未知项是否可见。
+3. 自查页面：资源能否离线解析；外部输入是否安全转义；是否意外包含 credential、环境值、私有路径或其他敏感查询内容；窄屏、键盘、无脚本、打印和空/错误状态是否可用。
+4. Native/both 模式在所有资源完成后，以顶层文件 Tool 对 `index.html` 做 bundle 最后一次 mutation；资源再变化时须再次 mutation 入口。最终回答以 Markdown 行内代码逐字复制该调用使用的完整绝对 `file_path`，不得缩短为相对路径、basename、`file://` 或 Markdown 链接。Produced Files 与 Host opening 只是导航，不代表发布、不可变、可恢复或验证通过。

package/skills/dsh-data-analysis-report/assets/marivo-artifact.js

@@ -0,0 +1,113 @@
+;(function installMarivoArtifact(scope) {
+  class MarivoArtifactError extends Error {
+    constructor(code, message) {
+      super(`${code}: ${message}`)
+      this.name = 'MarivoArtifactError'
+      this.code = code
+    }
+  }
+
+  function fail(code, message) {
+    throw new MarivoArtifactError(code, message)
+  }
+
+  function text(tag, value, className) {
+    const element = document.createElement(tag)
+    if (className) element.className = className
+    element.textContent = String(value)
+    return element
+  }
+
+  function notice(message, level) {
+    const item = text('li', message, 'marivo-artifact-notice')
+    item.dataset.level = level
+    return item
+  }
+
+  function artifactDataset(datasetId) {
+    const registry = scope.ReportData
+    if (!registry || typeof registry.get !== 'function') {
+      fail('report-data-unavailable', 'ReportData must be loaded before MarivoArtifact')
+    }
+    const dataset = registry.get(datasetId)
+    if (dataset.source.kind !== 'marivo_artifact') {
+      fail('artifact-dataset-required', 'dataset must be a Marivo Artifact snapshot')
+    }
+    return dataset
+  }
+
+  function summary(dataset) {
+    const parts = [dataset.source.artifact.kind]
+    if (dataset.table.semantic_shape !== null) parts.push(dataset.table.semantic_shape)
+    parts.push(`${dataset.table.total_rows} 行`)
+    parts.push(`结果生成于 ${dataset.source.artifact.created_at}`)
+    return parts.join(' · ')
+  }
+
+  function notices(dataset) {
+    const source = dataset.source
+    const result = []
+    if (dataset.table.omitted_rows > 0) {
+      result.push(
+        notice(
+          `展示数据已截断：显示 ${dataset.table.written_rows} 行，共 ${dataset.table.total_rows} 行。`,
+          'warning',
+        ),
+      )
+    }
+    if (source.artifact.evidence_status === 'partial') {
+      result.push(notice('分析依据不完整。', 'warning'))
+    } else if (source.artifact.evidence_status === 'unavailable') {
+      result.push(notice('分析依据不可用。', 'blocking'))
+    }
+    if (source.revalidation.status === 'checked') {
+      if (source.revalidation.result === 'stale') {
+        result.push(notice('当前有效性复核结果为 stale。', 'warning'))
+      } else if (source.revalidation.result === 'indeterminate') {
+        result.push(notice('当前有效性复核结果无法确定。', 'warning'))
+      }
+    }
+    const quality = source.quality_summary
+    if (quality !== null) {
+      if (quality.failed_check_count > 0) {
+        result.push(notice(`存在 ${quality.failed_check_count} 项未通过的质量检查。`, 'blocking'))
+      }
+      if (quality.warning_check_count > 0) {
+        result.push(notice(`存在 ${quality.warning_check_count} 项质量警告。`, 'warning'))
+      }
+    }
+    const blocking = source.issues.filter((issue) => issue.severity === 'blocking').length
+    const warnings = source.issues.filter((issue) => issue.severity === 'warning').length
+    if (blocking > 0) result.push(notice(`存在 ${blocking} 个阻断问题。`, 'blocking'))
+    if (warnings > 0) result.push(notice(`存在 ${warnings} 个警告问题。`, 'warning'))
+    if (source.issues_omitted > 0) {
+      result.push(notice(`另有 ${source.issues_omitted} 个问题未在快照中展开。`, 'warning'))
+    }
+    return result
+  }
+
+  function render(container, datasetId) {
+    if (!(container instanceof Element)) fail('container-invalid', 'container must be an Element')
+    const dataset = artifactDataset(datasetId)
+    const article = document.createElement('article')
+    article.className = 'marivo-artifact'
+    article.append(text('p', summary(dataset), 'marivo-artifact-summary'))
+    const material = notices(dataset)
+    if (material.length > 0) {
+      const list = document.createElement('ul')
+      list.className = 'marivo-artifact-notices'
+      list.append(...material)
+      article.append(list)
+    }
+    container.replaceChildren(article)
+    return container
+  }
+
+  const api = Object.freeze({ render })
+  Object.defineProperty(scope, 'MarivoArtifact', {
+    configurable: false,
+    enumerable: true,
+    value: api,
+    writable: false,
+  })
+})(globalThis)