dsh-data-insight 0.1.2 → 0.1.3

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 (3) hide show
  1. package/CHANGELOG.md +43 -39
  2. package/README.md +94 -89
  3. package/package.json +62 -61
package/CHANGELOG.md CHANGED
@@ -1,39 +1,43 @@
1
- # Changelog
2
-
3
- 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/) 约定。
4
-
5
- ## [Unreleased]
6
-
7
- ### 新增
8
- - `prepublishOnly` 钩子：npm 发布前自动运行测试门禁。
9
-
10
- ## [0.1.2] - 2026-09-02
11
-
12
- ### 新增
13
- - `package.json` 补充 `repository` / `bugs` / `homepage` 元数据。
14
- - GitHub Actions CI（`.github/workflows/ci.yml`）：ubuntu + windows 矩阵运行 csv-profile 契约测试。
15
- - `.editorconfig`：统一缩进 / 换行 / 编码基线（PowerShell 脚本保持 CRLF）。
16
- - README「排障」章节：DuckDB 只读模式、CLI 缺失、GBK 编码、脏数据核对、Mermaid 本地渲染。
17
- - `test/fixtures/README.md`：三个 fixture 的场景与验证点说明。
18
-
19
- ## [0.1.1] - 2026-08-16
20
-
21
- ### 修复
22
- - DuckDB 直连调用方式（SKILL.md / README）：CSV/Parquet 无库查询去掉 `-readonly`——v1.5.5 实测不带库文件时 CLI 打开内存库，`-readonly` 会报 `Cannot launch in-memory database in read-only mode`；`-readonly` 保留用于库文件 / 远程库连接（实测 INSERT 等写语句被拦截）。
23
-
24
- ### 新增
25
- - `scripts/setup-duckdb.sh`：macOS/Linux 安装脚本（brew / GitHub release / `~/.local/bin`），与 Windows 版 `setup-duckdb.ps1` 对齐。
26
- - `test/csv-profile.test.mjs`：csv-profile CLI 契约测试（`node:test` 零依赖，10 例：分隔符探测 / 引号与转义 / 千分位 / 混合类型降级 / 残缺行 / `--limit` / BOM / 退出码），`npm test` 运行。
27
- - runbook：CLI 缺失时引导运行对应平台的安装脚本。
28
-
29
- ## [0.1.0] - 2026-08-16
30
-
31
- ### 新增
32
- - 主技能 `data-insight-runbook`：五阶段数据洞察流水线（受理 → 探查 → 指标 → 图表 → 报告），每阶段硬门槛。
33
- - 四种数据源接入：CSV、粘贴表格、SQL 查询结果、DuckDB 直连（可选，强制只读）。
34
- - 三通道图表规范（`docs/chart-spec.md`）：Markdown 表格 + Mermaid + ASCII。
35
- - 报告模板与严谨性检查清单（`docs/report-template.md`）。
36
- - 零依赖 CSV 探查脚本 `scripts/csv-profile.mjs`。
37
- - 可选 DuckDB CLI 安装脚本 `scripts/setup-duckdb.ps1`（winget / GitHub 直链，UTF-8 BOM）。
38
- - 样例 CSV 与样例报告（`examples/`）。
39
- - 发布与分发指南 `PUBLISHING.md`。
1
+ # Changelog
2
+
3
+ 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/) 约定。
4
+
5
+ ## [Unreleased]
6
+
7
+ ## [0.1.3] - 2026-09-06
8
+
9
+ ### 新增
10
+ - 固定 `@deepseek-ai/dsh@0.1.2-rc.1` 的 `npm run test:compat` 门禁及 Windows/Ubuntu Node 22.19 CI，覆盖隔离 profile 的 add、配置 dump 和有限时长启动。
11
+ - README 将依赖示例更新为 `^0.1.3`，并区分独立脚本与 DSH 宿主的 Node 兼容要求。
12
+ - `prepublishOnly` 钩子：npm 发布前自动运行测试门禁。
13
+
14
+ ## [0.1.2] - 2026-09-02
15
+
16
+ ### 新增
17
+ - `package.json` 补充 `repository` / `bugs` / `homepage` 元数据。
18
+ - GitHub Actions CI（`.github/workflows/ci.yml`）：ubuntu + windows 矩阵运行 csv-profile 契约测试。
19
+ - `.editorconfig`：统一缩进 / 换行 / 编码基线（PowerShell 脚本保持 CRLF）。
20
+ - README「排障」章节：DuckDB 只读模式、CLI 缺失、GBK 编码、脏数据核对、Mermaid 本地渲染。
21
+ - `test/fixtures/README.md`：三个 fixture 的场景与验证点说明。
22
+
23
+ ## [0.1.1] - 2026-08-16
24
+
25
+ ### 修复
26
+ - DuckDB 直连调用方式（SKILL.md / README）：CSV/Parquet 无库查询去掉 `-readonly`——v1.5.5 实测不带库文件时 CLI 打开内存库，`-readonly` 会报 `Cannot launch in-memory database in read-only mode`；`-readonly` 保留用于库文件 / 远程库连接（实测 INSERT 等写语句被拦截）。
27
+
28
+ ### 新增
29
+ - `scripts/setup-duckdb.sh`：macOS/Linux 安装脚本（brew / GitHub release / `~/.local/bin`），与 Windows 版 `setup-duckdb.ps1` 对齐。
30
+ - `test/csv-profile.test.mjs`：csv-profile CLI 契约测试（`node:test` 零依赖，10 例：分隔符探测 / 引号与转义 / 千分位 / 混合类型降级 / 残缺行 / `--limit` / BOM / 退出码），`npm test` 运行。
31
+ - runbook：CLI 缺失时引导运行对应平台的安装脚本。
32
+
33
+ ## [0.1.0] - 2026-08-16
34
+
35
+ ### 新增
36
+ - 主技能 `data-insight-runbook`：五阶段数据洞察流水线（受理 → 探查 → 指标 → 图表 → 报告），每阶段硬门槛。
37
+ - 四种数据源接入：CSV、粘贴表格、SQL 查询结果、DuckDB 直连（可选，强制只读）。
38
+ - 三通道图表规范（`docs/chart-spec.md`）：Markdown 表格 + Mermaid + ASCII。
39
+ - 报告模板与严谨性检查清单（`docs/report-template.md`）。
40
+ - 零依赖 CSV 探查脚本 `scripts/csv-profile.mjs`。
41
+ - 可选 DuckDB CLI 安装脚本 `scripts/setup-duckdb.ps1`（winget / GitHub 直链，UTF-8 BOM）。
42
+ - 样例 CSV 与样例报告（`examples/`）。
43
+ - 发布与分发指南 `PUBLISHING.md`。
package/README.md CHANGED
@@ -1,89 +1,94 @@
1
- # dsh-data-insight
2
-
3
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
4
- [![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4c1d95)](https://github.com/topics/dsh-plugin)
5
- [![dsh-index](https://img.shields.io/badge/dsh--index-dsh--data--insight-blue)](https://dsh-index.xlings.org/packages/dsh-data-insight/)
6
- [![version](https://img.shields.io/badge/version-0.1.2-green)](CHANGELOG.md)
7
-
8
- DSH（DeepSeek Harness）**数据洞察技能插件**：把原始数据变成「业务结论 + 指标数据 + 图表」的结构化 Markdown 分析报告。
9
-
10
- 纯指令型技能插件，零依赖、零构建。计算由宿主已提供的文件 / Shell 工具驱动的 LLM 完成，包内附带一个零依赖的 CSV 探查脚本与完整图表 / 报告规范。
11
-
12
- ## 功能
13
-
14
- - **四种数据源**：CSV 文件、粘贴表格文本、SQL 查询结果、DuckDB 直连数据库（可选）。
15
- - **五阶段流水线**（每阶段带硬门槛）：输入受理 → 数据探查 → 指标计算 → 图表呈现 → 报告产出。
16
- - **三类指标**：汇总统计、同环比（基准期规则写死）、TopN、异常值（Z-score / IQR）。
17
- - **三通道图表**（全零依赖）：Markdown 表格 + 数字 / Mermaid / ASCII 条形图。
18
- - **严谨性保障**：结论必有数字支撑、事实与推断分离、口径可复现、不编造数据。
19
-
20
- ## 安装
21
-
22
- ```sh
23
- dsh plugin --profile web add dsh-data-insight
24
- ```
25
-
26
- 或手动两步（在目标 profile 目录下）：
27
-
28
- 1. `package.json` 的 `dependencies` 加 `"dsh-data-insight": "^0.1.1"`；
29
- 2. `dsh.profile.bundles` 数组加 `"dsh-data-insight"`。
30
-
31
- 重启 profile 后，技能 `data-insight-runbook` 出现在技能列表即可用。
32
-
33
- ## 使用
34
-
35
- 在会话中说「分析这份 CSV 出报告」「看看这个数据」「帮我算一下指标」并附上数据源（文件路径 / 粘贴表格 / DuckDB 连接），模型会加载 `data-insight-runbook` 并按五阶段执行。产物是一份 Markdown 报告，落盘到工作区。
36
-
37
- ### 快速示例
38
-
39
- ```sh
40
- node scripts/csv-profile.mjs examples/sample-sales.csv
41
- ```
42
-
43
- 会输出 `examples/sample-sales.csv` 的探查报告（schema / 缺失 / 分布 / 异常），对应报告样例见 `examples/sample-report.md`。
44
-
45
- ## 目录结构
46
-
47
- ```
48
- dsh-data-insight/
49
- ├── plugin/index.js # 插件入口：注册 skills/ 为技能根
50
- ├── cordis.patch.yml # bundle patch（dsh plugin add 时注入）
51
- ├── skills/data-insight-runbook/SKILL.md # 主技能：五阶段 runbook
52
- ├── docs/chart-spec.md # 三通道图表规范与示例
53
- ├── docs/report-template.md # 报告骨架 + 严谨性检查清单
54
- ├── scripts/csv-profile.mjs # 零依赖 CSV 探查脚本
55
- ├── scripts/setup-duckdb.ps1 # DuckDB CLI 安装脚本（Windows）
56
- ├── scripts/setup-duckdb.sh # DuckDB CLI 安装脚本（macOS/Linux）
57
- └── examples/ # 样例 CSV + 样例报告
58
- ```
59
-
60
- ## DuckDB 直连（可选）
61
-
62
- 默认零依赖；如需直连数据库，安装 [DuckDB](https://duckdb.org/) 单文件 CLI（加入 PATH）。可使用安装脚本：Windows `scripts/setup-duckdb.ps1`，macOS/Linux `scripts/setup-duckdb.sh`。
63
-
64
- ```sh
65
- # CSV/Parquet 直接查：无库文件，不加 -readonly（v1.5.5 实测 -readonly 打不开内存库会报错）
66
- duckdb -csv -c "SELECT * FROM read_csv_auto('data.csv') LIMIT 100"
67
- # 库文件 / 远程库：连接串走环境变量，强制只读（POSIX shell 为 "$DATA_INSIGHT_DB_URL"）
68
- duckdb -readonly -csv -c "SELECT ... LIMIT 5000" "$env:DATA_INSIGHT_DB_URL"
69
- ```
70
-
71
- 安全红线：连接库一律 `-readonly`（写语句会被拦截）；连接串走环境变量 `DATA_INSIGHT_DB_URL`；查询默认 `LIMIT 5000`。
72
-
73
- ## 排障
74
-
75
- - **DuckDB 报 `Cannot launch in-memory database in read-only mode`**：无库文件查询（CSV/Parquet）不要加 `-readonly`，见上方示例；`-readonly` 仅用于库文件 / 远程库。
76
- - **`duckdb: command not found`**：CLI 未安装或不在 PATH，运行对应平台安装脚本（`scripts/setup-duckdb.ps1` / `setup-duckdb.sh`）后重开终端。
77
- - **CSV 中文乱码**：优先 UTF-8（带 BOM 也能正确处理）；GBK 编码文件先用 `iconv -f GBK -t UTF-8` 转码再探查。
78
- - **指标结论与预期不符**：先用 `node scripts/csv-profile.mjs <file>` 看探查报告里的缺失值 / 重复行 / 异常值分布——样例数据实测中发现过单行脏数据驱动整体暴增、重复行抬高计数、缺失值拉低均值三类问题，探查阶段都能暴露。
79
- - **Mermaid 图在本地 Markdown 预览不渲染**：`file://` 协议下 CDN 加载的 mermaid.js 受同源策略限制，用 Typora 等本地渲染编辑器打开，或参考 `docs/chart-spec.md` 换用 Markdown 表格 / ASCII 条形图通道。
80
-
81
- ## 参考文档
82
-
83
- - `skills/data-insight-runbook/SKILL.md` — 完整流程与门槛
84
- - `docs/chart-spec.md`、`docs/report-template.md` — 图表与报告规范
85
- - `examples/` — 输入 / 输出样例
86
-
87
- ## 开源协议
88
-
89
- [MIT](LICENSE)
1
+ # dsh-data-insight
2
+
3
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
4
+ [![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4c1d95)](https://github.com/topics/dsh-plugin)
5
+ [![dsh-index](https://img.shields.io/badge/dsh--index-dsh--data--insight-blue)](https://dsh-index.xlings.org/packages/dsh-data-insight/)
6
+ [![version](https://img.shields.io/badge/version-0.1.3-green)](CHANGELOG.md)
7
+
8
+ DSH（DeepSeek Harness）**数据洞察技能插件**：把原始数据变成「业务结论 + 指标数据 + 图表」的结构化 Markdown 分析报告。
9
+
10
+ 纯指令型技能插件，零依赖、零构建。计算由宿主已提供的文件 / Shell 工具驱动的 LLM 完成，包内附带一个零依赖的 CSV 探查脚本与完整图表 / 报告规范。
11
+
12
+ ## 功能
13
+
14
+ - **四种数据源**：CSV 文件、粘贴表格文本、SQL 查询结果、DuckDB 直连数据库（可选）。
15
+ - **五阶段流水线**（每阶段带硬门槛）：输入受理 → 数据探查 → 指标计算 → 图表呈现 → 报告产出。
16
+ - **三类指标**：汇总统计、同环比（基准期规则写死）、TopN、异常值（Z-score / IQR）。
17
+ - **三通道图表**（全零依赖）：Markdown 表格 + 数字 / Mermaid / ASCII 条形图。
18
+ - **严谨性保障**：结论必有数字支撑、事实与推断分离、口径可复现、不编造数据。
19
+
20
+ ## 安装
21
+
22
+ ```sh
23
+ dsh plugin --profile web add dsh-data-insight
24
+ ```
25
+
26
+ 或手动两步（在目标 profile 目录下）：
27
+
28
+ 1. `package.json` 的 `dependencies` 加 `"dsh-data-insight": "^0.1.3"`；
29
+ 2. `dsh.profile.bundles` 数组加 `"dsh-data-insight"`。
30
+
31
+ 重启 profile 后，技能 `data-insight-runbook` 出现在技能列表即可用。
32
+
33
+ ## 使用
34
+
35
+ 在会话中说「分析这份 CSV 出报告」「看看这个数据」「帮我算一下指标」并附上数据源（文件路径 / 粘贴表格 / DuckDB 连接），模型会加载 `data-insight-runbook` 并按五阶段执行。产物是一份 Markdown 报告，落盘到工作区。
36
+
37
+ ### 快速示例
38
+
39
+ ```sh
40
+ node scripts/csv-profile.mjs examples/sample-sales.csv
41
+ ```
42
+
43
+ 会输出 `examples/sample-sales.csv` 的探查报告（schema / 缺失 / 分布 / 异常），对应报告样例见 `examples/sample-report.md`。
44
+
45
+ ## 目录结构
46
+
47
+ ```
48
+ dsh-data-insight/
49
+ ├── plugin/index.js # 插件入口：注册 skills/ 为技能根
50
+ ├── cordis.patch.yml # bundle patch（dsh plugin add 时注入）
51
+ ├── skills/data-insight-runbook/SKILL.md # 主技能：五阶段 runbook
52
+ ├── docs/chart-spec.md # 三通道图表规范与示例
53
+ ├── docs/report-template.md # 报告骨架 + 严谨性检查清单
54
+ ├── scripts/csv-profile.mjs # 零依赖 CSV 探查脚本
55
+ ├── scripts/setup-duckdb.ps1 # DuckDB CLI 安装脚本（Windows）
56
+ ├── scripts/setup-duckdb.sh # DuckDB CLI 安装脚本（macOS/Linux）
57
+ └── examples/ # 样例 CSV + 样例报告
58
+ ```
59
+
60
+ ## DuckDB 直连（可选）
61
+
62
+ 默认零依赖；如需直连数据库，安装 [DuckDB](https://duckdb.org/) 单文件 CLI（加入 PATH）。可使用安装脚本：Windows `scripts/setup-duckdb.ps1`，macOS/Linux `scripts/setup-duckdb.sh`。
63
+
64
+ ```sh
65
+ # CSV/Parquet 直接查：无库文件，不加 -readonly（v1.5.5 实测 -readonly 打不开内存库会报错）
66
+ duckdb -csv -c "SELECT * FROM read_csv_auto('data.csv') LIMIT 100"
67
+ # 库文件 / 远程库：连接串走环境变量，强制只读（POSIX shell 为 "$DATA_INSIGHT_DB_URL"）
68
+ duckdb -readonly -csv -c "SELECT ... LIMIT 5000" "$env:DATA_INSIGHT_DB_URL"
69
+ ```
70
+
71
+ 安全红线：连接库一律 `-readonly`（写语句会被拦截）；连接串走环境变量 `DATA_INSIGHT_DB_URL`；查询默认 `LIMIT 5000`。
72
+
73
+ ## 环境要求
74
+
75
+ - 独立 CSV / DuckDB 脚本：Node.js >= 18。
76
+ - DSH 0.1.2-rc.1 宿主：Node.js >= 22.19。
77
+
78
+ ## 排障
79
+
80
+ - **DuckDB 报 `Cannot launch in-memory database in read-only mode`**：无库文件查询（CSV/Parquet）不要加 `-readonly`，见上方示例；`-readonly` 仅用于库文件 / 远程库。
81
+ - **`duckdb: command not found`**：CLI 未安装或不在 PATH，运行对应平台安装脚本（`scripts/setup-duckdb.ps1` / `setup-duckdb.sh`）后重开终端。
82
+ - **CSV 中文乱码**：优先 UTF-8（带 BOM 也能正确处理）；GBK 编码文件先用 `iconv -f GBK -t UTF-8` 转码再探查。
83
+ - **指标结论与预期不符**：先用 `node scripts/csv-profile.mjs <file>` 看探查报告里的缺失值 / 重复行 / 异常值分布——样例数据实测中发现过单行脏数据驱动整体暴增、重复行抬高计数、缺失值拉低均值三类问题，探查阶段都能暴露。
84
+ - **Mermaid 图在本地 Markdown 预览不渲染**：`file://` 协议下 CDN 加载的 mermaid.js 受同源策略限制，用 Typora 等本地渲染编辑器打开，或参考 `docs/chart-spec.md` 换用 Markdown 表格 / ASCII 条形图通道。
85
+
86
+ ## 参考文档
87
+
88
+ - `skills/data-insight-runbook/SKILL.md` — 完整流程与门槛
89
+ - `docs/chart-spec.md`、`docs/report-template.md` — 图表与报告规范
90
+ - `examples/` — 输入 / 输出样例
91
+
92
+ ## 开源协议
93
+
94
+ [MIT](LICENSE)
package/package.json CHANGED
@@ -1,61 +1,62 @@
1
- {
2
- "name": "dsh-data-insight",
3
- "version": "0.1.2",
4
- "description": "DSH (DeepSeek Harness) data-insight skill plugin: turn raw data (CSV / pasted table / SQL results / DuckDB) into a structured Markdown report with business conclusions, metrics and charts.",
5
- "license": "MIT",
6
- "type": "module",
7
- "repository": {
8
- "type": "git",
9
- "url": "git+https://github.com/duyanta123/dsh-data-insight.git"
10
- },
11
- "bugs": {
12
- "url": "https://github.com/duyanta123/dsh-data-insight/issues"
13
- },
14
- "homepage": "https://github.com/duyanta123/dsh-data-insight#readme",
15
- "scripts": {
16
- "test": "node --test test/csv-profile.test.mjs",
17
- "prepublishOnly": "npm test"
18
- },
19
- "main": "./plugin/index.js",
20
- "exports": {
21
- ".": "./plugin/index.js",
22
- "./package.json": "./package.json"
23
- },
24
- "dsh": {
25
- "bundle": {
26
- "patch": "./cordis.patch.yml"
27
- }
28
- },
29
- "files": [
30
- "plugin/index.js",
31
- "cordis.patch.yml",
32
- "skills/",
33
- "docs/",
34
- "scripts/",
35
- "examples/",
36
- "README.md",
37
- "CHANGELOG.md",
38
- "PUBLISHING.md",
39
- "LICENSE"
40
- ],
41
- "peerDependencies": {
42
- "@deepseek-ai/dsh-skill-filesystem": "*"
43
- },
44
- "peerDependenciesMeta": {
45
- "@deepseek-ai/dsh-skill-filesystem": {
46
- "optional": true
47
- }
48
- },
49
- "keywords": [
50
- "dsh",
51
- "dsh-plugin",
52
- "deepseek-harness",
53
- "data-analysis",
54
- "data-insight",
55
- "analytics",
56
- "report",
57
- "csv",
58
- "duckdb",
59
- "skills"
60
- ]
61
- }
1
+ {
2
+ "name": "dsh-data-insight",
3
+ "version": "0.1.3",
4
+ "description": "DSH (DeepSeek Harness) data-insight skill plugin: turn raw data (CSV / pasted table / SQL results / DuckDB) into a structured Markdown report with business conclusions, metrics and charts.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/duyanta123/dsh-data-insight.git"
10
+ },
11
+ "bugs": {
12
+ "url": "https://github.com/duyanta123/dsh-data-insight/issues"
13
+ },
14
+ "homepage": "https://github.com/duyanta123/dsh-data-insight#readme",
15
+ "scripts": {
16
+ "test": "node --test test/csv-profile.test.mjs",
17
+ "test:compat": "node test/dsh-compat.test.mjs",
18
+ "prepublishOnly": "npm test"
19
+ },
20
+ "main": "./plugin/index.js",
21
+ "exports": {
22
+ ".": "./plugin/index.js",
23
+ "./package.json": "./package.json"
24
+ },
25
+ "dsh": {
26
+ "bundle": {
27
+ "patch": "./cordis.patch.yml"
28
+ }
29
+ },
30
+ "files": [
31
+ "plugin/index.js",
32
+ "cordis.patch.yml",
33
+ "skills/",
34
+ "docs/",
35
+ "scripts/",
36
+ "examples/",
37
+ "README.md",
38
+ "CHANGELOG.md",
39
+ "PUBLISHING.md",
40
+ "LICENSE"
41
+ ],
42
+ "peerDependencies": {
43
+ "@deepseek-ai/dsh-skill-filesystem": "*"
44
+ },
45
+ "peerDependenciesMeta": {
46
+ "@deepseek-ai/dsh-skill-filesystem": {
47
+ "optional": true
48
+ }
49
+ },
50
+ "keywords": [
51
+ "dsh",
52
+ "dsh-plugin",
53
+ "deepseek-harness",
54
+ "data-analysis",
55
+ "data-insight",
56
+ "analytics",
57
+ "report",
58
+ "csv",
59
+ "duckdb",
60
+ "skills"
61
+ ]
62
+ }