dsh-data-insight

dsh plugin --profile web add dsh-data-insight

dsh-data-insight

[English](README.md) | 简体中文






DSH（DeepSeek Harness）数据洞察技能插件：把原始数据变成「业务结论 + 指标数据 + 图表」的结构化 Markdown 分析报告。

纯指令型技能插件，零依赖、零构建。计算由宿主已提供的文件 / Shell 工具驱动的 LLM 完成，包内附带一个零依赖的 CSV 探查脚本与完整图表 / 报告规范。

定位

dsh-data-insight 处理「数据 → 报告」这一步：输入数据源，产出可审查的 Markdown 报告；不负责数据写入或清洗落盘，也不负责把数据发送到任何外部服务。

它回答：

• 这份数据的整体情况是什么（schema / 缺失 / 重复 / 分布）？
• 核心指标是多少，同比环比怎么变化？
• TopN 和异常值有哪些（Z-score / IQR）？
• 结论背后的数字是什么，能否复算？

严谨性保障（写入报告模板的硬门槛）：结论必有数字支撑、事实与推断分离、口径可复现、不编造数据。

安装

作为 DSH 插件（推荐）：

dsh plugin --profile web add "github:duyanta123/dsh-data-insight#v0.1.7"

或从 npm 安装：

npm install dsh-data-insight

或手动两步（在目标 profile 目录下）：package.json 的 dependencies 加 "dsh-data-insight": "^0.1.7"，dsh.profile.bundles 数组加 "dsh-data-insight"。

兼容性分层：独立 CSV / DuckDB 脚本可运行在 Node.js >= 18；作为 DSH 0.2.1-rc.2 插件验证统一使用 Node.js >= 22.19。package.json 声明 engines: node >=18 作为安装期下限；DSH 宿主路径的 22.19 下限由 compat 测试强制。运行 npm run test:compat 可执行隔离 profile 的 add、dump-config 和启动 smoke test。

重启 profile 后，技能 data-insight-runbook 出现在技能列表即可用。

快速开始

1. 作为 DSH 技能使用

在会话中说「分析这份 CSV 出报告」「看看这个数据」「帮我算一下指标」并附上数据源（文件路径 / 粘贴表格 / DuckDB 连接），模型会加载 data-insight-runbook 并按五阶段执行：输入受理 → 数据探查 → 指标计算 → 图表呈现 → 报告产出（每阶段带硬门槛）。产物是一份 Markdown 报告，落盘到工作区。

2. 作为独立探查脚本使用

node skills/data-insight-runbook/scripts/csv-profile.mjs skills/data-insight-runbook/examples/sample-sales.csv

会输出该 CSV 的探查报告（schema / 缺失 / 分布 / 异常），对应完整报告样例见 [examples/sample-report.md](skills/data-insight-runbook/examples/sample-report.md)。

3. DuckDB 直连（可选）

默认零依赖；如需直连数据库，安装 DuckDB 单文件 CLI（加入 PATH）。可使用安装脚本：Windows skills/data-insight-runbook/scripts/setup-duckdb.ps1，macOS/Linux skills/data-insight-runbook/scripts/setup-duckdb.sh。

# CSV/Parquet 直接查：无库文件，不加 -readonly（v1.5.5 实测 -readonly 打不开内存库会报错）
duckdb -csv -c "SELECT * FROM read_csv_auto('data.csv') LIMIT 100"
# 库文件 / 远程库：连接串走环境变量，强制只读（POSIX shell 为 "$DATA_INSIGHT_DB_URL"）
duckdb -readonly -csv -c "SELECT ... LIMIT 5000" "$env:DATA_INSIGHT_DB_URL"

CLI 参数

参数 · 默认 · 说明

<file> · - · 要探查的 CSV 文件路径

--sep <分隔符> · 自动探测 · 字段分隔符（自动识别 ,、\t、;、 · ）

--encoding <enc> · utf8 · 文件编码：utf8 / utf16le / latin1（GBK 文件请先转码；UTF-16LE BOM 自动剥离；非法值退出码 2）

--limit <N> · 0（全部） · 限制读取行数，用于超大数据集抽样探查

--json · - · 以 JSON 输出探查结果

输出

五阶段流水线的最终产物是一份 Markdown 分析报告，固定骨架见 [docs/report-template.md](skills/data-insight-runbook/docs/report-template.md)：

• 核心结论（每条带数字支撑与交叉引用）
• 数据概况（schema、缺失、重复、处置记录）
• 指标明细（汇总统计、同环比、TopN、异常值）
• 趋势与对比（三通道图表：Markdown 表格 + 数字为主，Mermaid / ASCII 条形图兜底）
• 口径与复算说明（事实与推断分离）

安全边界

• 探查只读：CSV 探查脚本只读取输入文件，不写入、不联网。
• DuckDB 红线：连接库一律 -readonly（写语句会被拦截）；连接串走环境变量 DATA_INSIGHT_DB_URL，不写进命令、配置或报告；查询默认 LIMIT 5000。
• 不编造数据：报告结论必须有数字支撑，缺失数据如实标注。

排障

DuckDB 报 Cannot launch in-memory database in read-only mode？

无库文件查询（CSV/Parquet）不要加 -readonly，见上方示例；-readonly 仅用于库文件 / 远程库。

duckdb: command not found？

CLI 未安装或不在 PATH，运行对应平台安装脚本（skills/data-insight-runbook/scripts/setup-duckdb.ps1 / setup-duckdb.sh）后重开终端。

CSV 中文乱码？

优先 UTF-8（带 BOM 也能正确处理）；GBK 编码文件先用 iconv -f GBK -t UTF-8 转码再探查。

指标结论与预期不符？

先用 node skills/data-insight-runbook/scripts/csv-profile.mjs <file> 看探查报告里的缺失值 / 重复行 / 异常值分布——样例数据实测中发现过单行脏数据驱动整体暴增、重复行抬高计数、缺失值拉低均值三类问题，探查阶段都能暴露。

Mermaid 图在本地 Markdown 预览不渲染？

file:// 协议下 CDN 加载的 mermaid.js 受同源策略限制，用 Typora 等本地渲染编辑器打开，或参考 [docs/chart-spec.md](skills/data-insight-runbook/docs/chart-spec.md) 换用 Markdown 表格 / ASCII 条形图通道。

升级 DSH 宿主到 0.1.5 系后旧会话打不开？

Session format V3 迁移不可逆，属宿主行为；升级宿主前请先备份会话日志（见 [CHANGELOG.md](CHANGELOG.md) 0.1.4 条目）。

文档

• [docs/chart-spec.md](skills/data-insight-runbook/docs/chart-spec.md) — 三通道图表规范与示例（含 DSH Web GUI 不渲染 Mermaid 的警告）
• [docs/report-template.md](skills/data-insight-runbook/docs/report-template.md) — 报告骨架 + 严谨性检查清单
• [examples/](skills/data-insight-runbook/examples/) — 样例 CSV 与完整样例报告
• [CHANGELOG.md](CHANGELOG.md) — 版本变更记录
• [PLUGIN-MAINTENANCE.md](PLUGIN-MAINTENANCE.md) — 本仓维护规则
• [DSH-DATA-INSIGHT-开发计划.md](DSH-DATA-INSIGHT-开发计划.md) — 开发计划（回溯整理的审计基准）

License

[MIT](LICENSE)