dsh-data-insight 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -2,7 +2,23 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/) 约定。
 
-## [Unreleased]
+## [0.1.5] - 2026-09-17
+
+### 修复
+- **技能资源路径与 harness 的解析基准不一致，导致 `SKILL.md` 中全部相对路径失效。** harness 加载技能时注入「Base directory for this skill: `<skills>/<name>`」并指示按该基准解析相对路径，而 `docs/`、`scripts/`、`examples/` 原先位于包根，故 `SKILL.md` 里的 `scripts/csv-profile.mjs`、`docs/chart-spec.md`、`docs/report-template.md` 等引用在 agent 运行时一律解析到不存在的路径（阶段 1 的探查脚本与阶段 4 的报告骨架、图表规范因此全部不可达）。现将三者移入 `skills/data-insight-runbook/`，技能目录自包含；相对路径书写不变，`SKILL.md` 无需改动。
+- `package.json` 的 `files` 字段随之移除包根 `docs/`、`scripts/`、`examples/` 条目（嵌套目录已由 `skills/` 递归包含，已用 `npm pack --dry-run` 验证）。
+- 双语 README、`PUBLISHING.md` 中的路径引用与文档链接同步更新。
+- `test/dsh-compat.test.mjs` 新增回归断言：技能引用的资源若存在于包内却位于技能目录之外，立即失败并给出修复指引——原测试只校验 `SKILL.md` frontmatter，未校验其引用的资源可达性，故未能拦住此问题。
+
+### 变更
+- **包内脚本路径变更（影响直接调用者）**：`csv-profile.mjs`、`setup-duckdb.ps1`/`setup-duckdb.sh` 与 `docs/`、`examples/` 现位于 `skills/data-insight-runbook/` 下。按 0.1.4 README 硬编码路径的调用需同步调整，例如 `node node_modules/dsh-data-insight/scripts/csv-profile.mjs` → `node node_modules/dsh-data-insight/skills/data-insight-runbook/scripts/csv-profile.mjs`。技能加载路径不受影响：`SKILL.md` 的相对路径写法与 DSH 侧安装方式均未变。
+- `PLUGIN-MAINTENANCE.md` 的目录树、核心脚本引用与 `files` 白名单描述同步至新布局。
+
+## [0.1.4] - 2026-09-11
+
+### 变更
+- DSH 宿主兼容基线从 `0.1.2-rc.1` 迁移到 `0.1.5-rc.2`：`npm run test:compat` 与 CI compat job 固定安装 `@deepseek-ai/dsh@0.1.5-rc.2` + 同版本 `@deepseek-ai/dsh-skill-filesystem`。上游 0.1.3~0.1.5 的破坏性变更（`SessionHandle`、异步 `agentLoop.create()`、Session format v2/v3、`ctx.agent` 移除、Inbox API 变更）均不涉及本插件使用的技能 provider 路径，插件代码零改动。
+- 提示：DSH 宿主升级到 0.1.5 系后 Session format 迁移为 V3，不可逆；最终用户升级宿主前请备份会话日志。
 
 ## [0.1.3] - 2026-09-06
 

package/PUBLISHING.md

@@ -1,79 +1,61 @@
-# 发布与分发指南（PUBLISHING）
+# Publishing
 
-本文档记录 `dsh-data-insight` 从源码到分发的完整步骤，供维护者在有网终端执行。
+> 本文是 dsh-data-insight 的发布手册，结构遵循工作区顶层 docs/PUBLISHING-TEMPLATE.md 模板（该文件位于插件仓库之外，不在本仓库内）；其他插件仓库的 PUBLISHING.md 同构。
 
-## 当前状态（构建侧已就绪）
+## 1. 命名与分发身份
 
-- 包结构 14 个文件已建成；`node --check`、JSON、插件 API、SKILL.md frontmatter 均已校验通过。
-- `csv-profile.mjs` 已在 `examples/sample-sales.csv` 上跑通。
-- `setup-duckdb.ps1` 语法校验通过（UTF-8 BOM），版本探测数据源 `duckdb.org/data/latest_stable_version.txt` 实测返回 `1.5.5`。
-- 已 `git init` + 初始 commit（本地 `main` 分支）。
-- npm 包名 `dsh-data-insight` 已确认未被占用（`npm view` 返回 404）。
+- npm 包名：`dsh-data-insight`（与 GitHub 仓库名一致，2026-09 首发时经 `npm view` 确认未占用）。
+- GitHub 仓库名：`duyanta123/dsh-data-insight`。
+- exports 仅根路径（`./plugin/index.js`），无 bin 命令、无子路径导出。
+- cordis.patch.yml 插件行 id/name 为 `dsh-data-insight`。
+- README 双语：`README.md` 为英文、`README.zh-CN.md` 为中文，顶部互链；两者章节结构必须一致，改动描述时同步更新。
 
-## 前置条件
+## 2. 发布前检查清单
 
-- 一个有网、能访问 github.com 与 registry.npmjs.org 的终端。
-- 已登录 npm：`npm login`（需要 npm 账号 + 2FA）。
-- GitHub 账号（用于建仓库与 push）。
+1. 运行 `npm test`（`node --test test/csv-profile.test.mjs`，当前 10 例，全绿）。
+2. 运行 `node --check skills/data-insight-runbook/scripts/csv-profile.mjs` 与 `npm run test:compat`。
+3. 改动过 DuckDB 命令时，真机验证**两个模式**：无库文件（内存库，不加 `-readonly`）与有库文件（`-readonly` 只读）。历史教训：DuckDB v1.5.5 实测内存库加 `-readonly` 会报错。
+4. 运行 `npm pack --dry-run`，确认包含 `plugin/index.js`、`cordis.patch.yml`、`skills/`（技能目录自包含：`SKILL.md` + `docs/` + `scripts/` + `examples/` 均在其下）、双语 `README.md`/`README.zh-CN.md`、`CHANGELOG.md`、`PUBLISHING.md`、`LICENSE`。
+5. 版本一致性核对：`package.json` version、`CHANGELOG.md` 发布段、git tag 三处一致。
+6. 版本徽章同步：双语 README 的 version 徽章、安装示例 tag、手动安装依赖版本指向最新发布版本。
 
-## 步骤 1：发布到 GitHub
+## 3. DSH bundle 契约（对齐 2026-09 现行契约）
 
-```powershell
-# 1) 浏览器打开 https://github.com/new，仓库名 dsh-data-insight，公开，
-#    不要勾选 "Initialize with README / .gitignore / license"（本地已有）。
-cd D:\Agent预设\UI\dsh-data-insight
-git remote add origin https://github.com/<你的用户名>/dsh-data-insight.git
-git push -u origin main
-```
+- `package.json` 声明 `dsh.bundle.patch: ./cordis.patch.yml`——harness 只激活声明该字段的包。
+- `cordis.patch.yml` 为 config-tree `- insert:` 补丁格式；harness 加载 `main`（`plugin/index.js`）。
+- `plugin/index.js` 经官方 `@deepseek-ai/dsh-skill-filesystem` 的 `FileSystemSkillProvider` 注册 `skills/` 为技能根（includeDefaultRoots: false）。
+- `skills/data-insight-runbook/SKILL.md` frontmatter 必填 `name`（kebab-case）+ `description`。
+- 安装契约：`dsh plugin --profile <profile> add "github:owner/repo#ref"`；兼容基线 `@deepseek-ai/dsh@0.1.5-rc.2`（Node >= 22.19）。
 
-推送后打一个版本 tag（可选但推荐，供 `dsh plugin add github:...#vX.Y.Z` 引用）：
+## 4. 发布渠道
 
-```powershell
-git tag v0.1.0
-git push origin v0.1.0
-```
+### GitHub
 
-## 步骤 2：发布到 npm
+1. push `main`，确认 CI 全绿（ubuntu + windows × Node 22 回归 + Node 22.19 DSH compat job）。
+2. 打 tag `v0.x.y`（与 `package.json` version 一致，如当前 `v0.1.5`）并推送。
+3. 给仓库添加 GitHub topic `dsh-plugin`（awesome 收录门槛之一）。
 
-```powershell
-cd D:\Agent预设\UI\dsh-data-insight
-npm view dsh-data-insight version   # 再次确认包名可用（应 404）
-npm login                           # 首次需要；已登录可跳过
-npm publish --access public
-```
+### npm
 
-## 步骤 3：安装到 profile（二选一）
+1. `npm login`（需要 npm 账号 + 2FA）。
+2. `npm publish --access public`（`prepublishOnly` 会先跑 `npm test`）。
+3. 发布后核对 `npm view dsh-data-insight version` 与 dist-tags。
 
-发布后，任选一种分发形态安装：
+### awesome 列表收录（已收录，改描述时同步）
 
-```powershell
-# npm 形态
-dsh plugin --profile web add dsh-data-insight
+- awesome-dsh-plugin：同步 `data/plugins/duyanta123__dsh-data-insight.yml` 的描述与分类。
+- awesome-deepseek-harness：同步 README 条目（真实仓库 + 一句话 + 链接，en/zh 同 PR）。
+- dsh-index：已收录（`https://dsh-index.xlings.org/packages/dsh-data-insight/`），技能元数据变更时同步提交。
 
-# GitHub 形态（与 dsh-preset-scaffold 一致）
-dsh plugin --profile web add github:<你的用户名>/dsh-data-insight#v0.1.0
-```
-
-> 本地开发期可用 `file:` 链接（无需发布）：
-> 在 profile 的 `package.json` 里加 `"dsh-data-insight": "file:D:/Agent预设/UI/dsh-data-insight"`，
-> 并在 `dsh.profile.bundles` 数组加 `"dsh-data-insight"`，然后 `pnpm install`。
-
-## 步骤 4：验证
+## 5. 安装验证（发布后）
 
 1. 重启 profile（`dsh web` 重开），技能列表应出现 `data-insight-runbook`。
-2. 说「分析 examples/sample-sales.csv 出报告」，确认五阶段执行并产出报告。
-3. 可选：`scripts/setup-duckdb.ps1` 装 DuckDB 后，验证直连只读查询。
+2. 说「分析 skills/data-insight-runbook/examples/sample-sales.csv 出报告」，确认五阶段执行并产出报告。
+3. 可选：`skills/data-insight-runbook/scripts/setup-duckdb.ps1` 装 DuckDB 后，验证直连只读查询。
 
-## 常见问题
+## 6. 常见问题
 
 - **`npm publish` 报 403/404**：包名被占或未登录；用 `npm whoami` 检查登录态。
 - **`dsh plugin add` 报找不到包**：确认包已发布且 profile 的 `dsh.profile.bundles` 含包名。
 - **技能没出现**：重启 profile 才加载 bundle patch；确认 `cordis.patch.yml` 随包发布（`files` 字段已包含）。
 - **DuckDB 直连被拒**：runbook 强制 `-readonly`；连接串走环境变量 `DATA_INSIGHT_DB_URL`，不要写进命令/报告。
-
-## 本地开发循环（改技能内容后）
-
-1. 改 `skills/`、`docs/`、`scripts/` 下的文件。
-2. 本地 `file:` 链接形态下，改 `skills/` 无需重装（FileSystemSkillProvider 会 watch 技能根）。
-3. 改 `plugin/index.js` / `cordis.patch.yml` / `package.json` 后需 `pnpm install` 并重启 profile。
-4. 提交前：`node --check scripts/csv-profile.mjs`、PowerShell 语法校验、`git status` 确认。

package/README.md

@@ -1,94 +1,128 @@
 # dsh-data-insight
 
+English | [简体中文](README.zh-CN.md)
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4c1d95)](https://github.com/topics/dsh-plugin)
+[![CI](https://github.com/duyanta123/dsh-data-insight/actions/workflows/ci.yml/badge.svg)](https://github.com/duyanta123/dsh-data-insight/actions/workflows/ci.yml)
 [![dsh-index](https://img.shields.io/badge/dsh--index-dsh--data--insight-blue)](https://dsh-index.xlings.org/packages/dsh-data-insight/)
-[![version](https://img.shields.io/badge/version-0.1.3-green)](CHANGELOG.md)
+[![version](https://img.shields.io/badge/version-0.1.5-green)](CHANGELOG.md)
+
+A DSH (DeepSeek Harness) **data-insight skill plugin**: turns raw data into a structured Markdown analysis report of "business conclusions + metrics + charts".
+
+A pure instruction-type skill plugin with zero dependencies and zero build. Computation is done by the LLM driven by the host's file/shell tools; the package ships a zero-dependency CSV profiling script and full chart/report specifications.
 
-DSH（DeepSeek Harness）**数据洞察技能插件**：把原始数据变成「业务结论 + 指标数据 + 图表」的结构化 Markdown 分析报告。
+## Positioning
 
-纯指令型技能插件，零依赖、零构建。计算由宿主已提供的文件 / Shell 工具驱动的 LLM 完成，包内附带一个零依赖的 CSV 探查脚本与完整图表 / 报告规范。
+dsh-data-insight covers the "data → report" step: given a data source, it produces a reviewable Markdown report. It does not write or clean data back to storage, and it never sends data to any external service.
 
-## 功能
+It answers:
+- What does this data look like overall (schema / missing / duplicates / distribution)?
+- What are the core metrics, and how do they change period over period?
+- What are the TopN entries and outliers (Z-score / IQR)?
+- What numbers back each conclusion, and can they be recomputed?
 
-- **四种数据源**：CSV 文件、粘贴表格文本、SQL 查询结果、DuckDB 直连数据库（可选）。
-- **五阶段流水线**（每阶段带硬门槛）：输入受理 → 数据探查 → 指标计算 → 图表呈现 → 报告产出。
-- **三类指标**：汇总统计、同环比（基准期规则写死）、TopN、异常值（Z-score / IQR）。
-- **三通道图表**（全零依赖）：Markdown 表格 + 数字 / Mermaid / ASCII 条形图。
-- **严谨性保障**：结论必有数字支撑、事实与推断分离、口径可复现、不编造数据。
+Rigor guarantees (hard gates baked into the report template): every conclusion backed by numbers, facts separated from inference, reproducible metrics definitions, no fabricated data.
 
-## 安装
+## Installation
+
+As a DSH plugin (recommended):
 
 ```sh
-dsh plugin --profile web add dsh-data-insight
+dsh plugin --profile web add "github:duyanta123/dsh-data-insight#v0.1.5"
 ```
 
-或手动两步（在目标 profile 目录下）：
+Or from npm:
 
-1. `package.json` 的 `dependencies` 加 `"dsh-data-insight": "^0.1.3"`；
-2. `dsh.profile.bundles` 数组加 `"dsh-data-insight"`。
+```sh
+npm install dsh-data-insight
+```
 
-重启 profile 后，技能 `data-insight-runbook` 出现在技能列表即可用。
+Or manually in two steps (in the target profile directory): add `"dsh-data-insight": "^0.1.5"` to `dependencies` in `package.json`, and add `"dsh-data-insight"` to the `dsh.profile.bundles` array.
 
-## 使用
+Compatibility tiers: the standalone CSV / DuckDB scripts run on Node.js >= 18; as a DSH 0.1.5-rc.2 plugin it is verified with Node.js >= 22.19. Run `npm run test:compat` to execute an isolated-profile add, dump-config, and startup smoke test.
 
-在会话中说「分析这份 CSV 出报告」「看看这个数据」「帮我算一下指标」并附上数据源（文件路径 / 粘贴表格 / DuckDB 连接），模型会加载 `data-insight-runbook` 并按五阶段执行。产物是一份 Markdown 报告，落盘到工作区。
+After restarting the profile, the `data-insight-runbook` skill appears in the skill list and is ready to use.
 
-### 快速示例
+## Quick Start
 
-```sh
-node scripts/csv-profile.mjs examples/sample-sales.csv
-```
+### 1. Use as a DSH skill
 
-会输出 `examples/sample-sales.csv` 的探查报告（schema / 缺失 / 分布 / 异常），对应报告样例见 `examples/sample-report.md`。
+Say "analyze this CSV and give me a report", "take a look at this data", or "compute these metrics for me" with a data source attached (file path / pasted table / DuckDB connection). The model loads `data-insight-runbook` and runs the five-stage pipeline: input intake → data profiling → metric computation → chart rendering → report output (hard gates at each stage). The deliverable is a Markdown report written to the workspace.
 
-## 目录结构
+### 2. Use as a standalone profiling script
 
-```
-dsh-data-insight/
-├── plugin/index.js          # 插件入口：注册 skills/ 为技能根
-├── cordis.patch.yml         # bundle patch（dsh plugin add 时注入）
-├── skills/data-insight-runbook/SKILL.md   # 主技能：五阶段 runbook
-├── docs/chart-spec.md       # 三通道图表规范与示例
-├── docs/report-template.md  # 报告骨架 + 严谨性检查清单
-├── scripts/csv-profile.mjs  # 零依赖 CSV 探查脚本
-├── scripts/setup-duckdb.ps1 # DuckDB CLI 安装脚本（Windows）
-├── scripts/setup-duckdb.sh  # DuckDB CLI 安装脚本（macOS/Linux）
-└── examples/                # 样例 CSV + 样例报告
+```sh
+node skills/data-insight-runbook/scripts/csv-profile.mjs skills/data-insight-runbook/examples/sample-sales.csv
 ```
 
-## DuckDB 直连（可选）
+Prints a profiling report for the CSV (schema / missing / distribution / outliers); the corresponding full report sample is [examples/sample-report.md](skills/data-insight-runbook/examples/sample-report.md).
 
-默认零依赖；如需直连数据库，安装 [DuckDB](https://duckdb.org/) 单文件 CLI（加入 PATH）。可使用安装脚本：Windows `scripts/setup-duckdb.ps1`，macOS/Linux `scripts/setup-duckdb.sh`。
+### 3. DuckDB direct connection (optional)
+
+Zero dependencies by default; to query databases directly, install the [DuckDB](https://duckdb.org/) single-file CLI (on PATH). Install scripts: Windows `skills/data-insight-runbook/scripts/setup-duckdb.ps1`, macOS/Linux `skills/data-insight-runbook/scripts/setup-duckdb.sh`.
 
 ```sh
-# CSV/Parquet 直接查：无库文件，不加 -readonly（v1.5.5 实测 -readonly 打不开内存库会报错）
+# Query CSV/Parquet directly: no database file, no -readonly (v1.5.5: -readonly fails on in-memory databases)
 duckdb -csv -c "SELECT * FROM read_csv_auto('data.csv') LIMIT 100"
-# 库文件 / 远程库：连接串走环境变量，强制只读（POSIX shell 为 "$DATA_INSIGHT_DB_URL"）
+# Database file / remote DB: connection string via env var, forced read-only (POSIX shell: "$DATA_INSIGHT_DB_URL")
 duckdb -readonly -csv -c "SELECT ... LIMIT 5000" "$env:DATA_INSIGHT_DB_URL"
 ```
 
-安全红线：连接库一律 `-readonly`（写语句会被拦截）；连接串走环境变量 `DATA_INSIGHT_DB_URL`；查询默认 `LIMIT 5000`。
+## CLI Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `<file>` | - | Path to the CSV file to profile |
+| `--sep <char>` | auto-detect | Field separator (auto-detects `,`, `\t`, `;`) |
+| `--encoding <enc>` | utf8 | File encoding: utf8 / utf16le / latin1 (transcode GBK files first) |
+| `--limit <N>` | 0 (all) | Limit rows read, for sampling very large datasets |
+| `--json` | - | Output the profiling result as JSON |
+
+## Output
+
+The final artifact of the five-stage pipeline is a Markdown analysis report with a fixed skeleton defined in [docs/report-template.md](skills/data-insight-runbook/docs/report-template.md):
+
+- **Core conclusions** (each backed by numbers with cross-references)
+- **Data overview** (schema, missing values, duplicates, dispositions)
+- **Metric details** (summary stats, period-over-period, TopN, outliers)
+- **Trends & comparisons** (three-channel charts: Markdown tables + numbers first, Mermaid / ASCII bar charts as fallback)
+- **Definitions & recomputation** (facts separated from inference)
+
+## Safety Boundaries
+
+- **Read-only profiling**: the CSV profiling script only reads its input file — no writes, no network.
+- **DuckDB red lines**: database connections always use `-readonly` (write statements are blocked); connection strings go through the `DATA_INSIGHT_DB_URL` env var, never into commands, config, or reports; queries default to `LIMIT 5000`.
+- **No fabricated data**: report conclusions must be backed by numbers; missing data is stated as-is.
+
+## Troubleshooting
+
+**DuckDB says `Cannot launch in-memory database in read-only mode`?**
+Don't pass `-readonly` for file-less queries (CSV/Parquet) — see the example above; `-readonly` is only for database files / remote databases.
+
+**`duckdb: command not found`?**
+The CLI isn't installed or isn't on PATH; run the platform install script (`skills/data-insight-runbook/scripts/setup-duckdb.ps1` / `setup-duckdb.sh`) and reopen the terminal.
 
-## 环境要求
+**Garbled Chinese text in CSV?**
+Prefer UTF-8 (BOM is handled correctly); transcode GBK files first with `iconv -f GBK -t UTF-8`.
 
-- 独立 CSV / DuckDB 脚本：Node.js >= 18。
-- DSH 0.1.2-rc.1 宿主：Node.js >= 22.19。
+**Metrics don't match expectations?**
+Run `node skills/data-insight-runbook/scripts/csv-profile.mjs <file>` first and check the profiling report's missing values / duplicate rows / outlier distribution — real-world sample data has surfaced three classes of issues (a single dirty row driving a spike, duplicates inflating counts, missing values dragging averages), all exposed at the profiling stage.
 
-## 排障
+**Mermaid charts don't render in local Markdown preview?**
+Over `file://`, CDN-loaded mermaid.js is blocked by same-origin policy; open with a local renderer such as Typora, or switch to the Markdown table / ASCII bar chart channels per [docs/chart-spec.md](skills/data-insight-runbook/docs/chart-spec.md).
 
-- **DuckDB 报 `Cannot launch in-memory database in read-only mode`**：无库文件查询（CSV/Parquet）不要加 `-readonly`，见上方示例；`-readonly` 仅用于库文件 / 远程库。
-- **`duckdb: command not found`**：CLI 未安装或不在 PATH，运行对应平台安装脚本（`scripts/setup-duckdb.ps1` / `setup-duckdb.sh`）后重开终端。
-- **CSV 中文乱码**：优先 UTF-8（带 BOM 也能正确处理）；GBK 编码文件先用 `iconv -f GBK -t UTF-8` 转码再探查。
-- **指标结论与预期不符**：先用 `node scripts/csv-profile.mjs <file>` 看探查报告里的缺失值 / 重复行 / 异常值分布——样例数据实测中发现过单行脏数据驱动整体暴增、重复行抬高计数、缺失值拉低均值三类问题，探查阶段都能暴露。
-- **Mermaid 图在本地 Markdown 预览不渲染**：`file://` 协议下 CDN 加载的 mermaid.js 受同源策略限制，用 Typora 等本地渲染编辑器打开，或参考 `docs/chart-spec.md` 换用 Markdown 表格 / ASCII 条形图通道。
+**Old sessions won't open after upgrading the DSH host to 0.1.5.x?**
+The Session format V3 migration is irreversible and is host behavior; back up session logs before upgrading the host (see the 0.1.4 entry in [CHANGELOG.md](CHANGELOG.md)).
 
-## 参考文档
+## Documentation
 
-- `skills/data-insight-runbook/SKILL.md` — 完整流程与门槛
-- `docs/chart-spec.md`、`docs/report-template.md` — 图表与报告规范
-- `examples/` — 输入 / 输出样例
+- [docs/chart-spec.md](skills/data-insight-runbook/docs/chart-spec.md) — three-channel chart spec and examples (including the warning that the DSH Web GUI doesn't render Mermaid)
+- [docs/report-template.md](skills/data-insight-runbook/docs/report-template.md) — report skeleton + rigor checklist
+- [examples/](skills/data-insight-runbook/examples/) — sample CSV and full sample report
+- [CHANGELOG.md](CHANGELOG.md) — release notes
+- [PLUGIN-MAINTENANCE.md](PLUGIN-MAINTENANCE.md) — repo maintenance runbook
 
-## 开源协议
+## License
 
 [MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,128 @@
+# dsh-data-insight
+
+[English](README.md) | 简体中文
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4c1d95)](https://github.com/topics/dsh-plugin)
+[![CI](https://github.com/duyanta123/dsh-data-insight/actions/workflows/ci.yml/badge.svg)](https://github.com/duyanta123/dsh-data-insight/actions/workflows/ci.yml)
+[![dsh-index](https://img.shields.io/badge/dsh--index-dsh--data--insight-blue)](https://dsh-index.xlings.org/packages/dsh-data-insight/)
+[![version](https://img.shields.io/badge/version-0.1.5-green)](CHANGELOG.md)
+
+DSH（DeepSeek Harness）**数据洞察技能插件**：把原始数据变成「业务结论 + 指标数据 + 图表」的结构化 Markdown 分析报告。
+
+纯指令型技能插件，零依赖、零构建。计算由宿主已提供的文件 / Shell 工具驱动的 LLM 完成，包内附带一个零依赖的 CSV 探查脚本与完整图表 / 报告规范。
+
+## 定位
+
+dsh-data-insight 处理「数据 → 报告」这一步：输入数据源，产出可审查的 Markdown 报告；不负责数据写入或清洗落盘，也不负责把数据发送到任何外部服务。
+
+它回答：
+- 这份数据的整体情况是什么（schema / 缺失 / 重复 / 分布）？
+- 核心指标是多少，同比环比怎么变化？
+- TopN 和异常值有哪些（Z-score / IQR）？
+- 结论背后的数字是什么，能否复算？
+
+严谨性保障（写入报告模板的硬门槛）：结论必有数字支撑、事实与推断分离、口径可复现、不编造数据。
+
+## 安装
+
+作为 DSH 插件（推荐）：
+
+```sh
+dsh plugin --profile web add "github:duyanta123/dsh-data-insight#v0.1.5"
+```
+
+或从 npm 安装：
+
+```sh
+npm install dsh-data-insight
+```
+
+或手动两步（在目标 profile 目录下）：`package.json` 的 `dependencies` 加 `"dsh-data-insight": "^0.1.5"`，`dsh.profile.bundles` 数组加 `"dsh-data-insight"`。
+
+兼容性分层：独立 CSV / DuckDB 脚本可运行在 Node.js >= 18；作为 DSH 0.1.5-rc.2 插件验证统一使用 Node.js >= 22.19。运行 `npm run test:compat` 可执行隔离 profile 的 add、dump-config 和启动 smoke test。
+
+重启 profile 后，技能 `data-insight-runbook` 出现在技能列表即可用。
+
+## 快速开始
+
+### 1. 作为 DSH 技能使用
+
+在会话中说「分析这份 CSV 出报告」「看看这个数据」「帮我算一下指标」并附上数据源（文件路径 / 粘贴表格 / DuckDB 连接），模型会加载 `data-insight-runbook` 并按五阶段执行：输入受理 → 数据探查 → 指标计算 → 图表呈现 → 报告产出（每阶段带硬门槛）。产物是一份 Markdown 报告，落盘到工作区。
+
+### 2. 作为独立探查脚本使用
+
+```sh
+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](https://duckdb.org/) 单文件 CLI（加入 PATH）。可使用安装脚本：Windows `skills/data-insight-runbook/scripts/setup-duckdb.ps1`，macOS/Linux `skills/data-insight-runbook/scripts/setup-duckdb.sh`。
+
+```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 文件请先转码） |
+| `--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) — 本仓维护规则
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-data-insight",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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.",
   "license": "MIT",
   "type": "module",
@@ -31,10 +31,8 @@
     "plugin/index.js",
     "cordis.patch.yml",
     "skills/",
-    "docs/",
-    "scripts/",
-    "examples/",
     "README.md",
+    "README.zh-CN.md",
     "CHANGELOG.md",
     "PUBLISHING.md",
     "LICENSE"

package/{examples → skills/data-insight-runbook/examples}/sample-report.md

@@ -2,7 +2,7 @@
 
 > 数据源：`examples/sample-sales.csv`
 > 时间范围：2025-01-01 ~ 2025-01-10　粒度：日
-> 生成时间：示例　工具：dsh-data-insight v0.1.0
+> 生成时间：示例　工具：dsh-data-insight v0.1.5
 
 ## 一、核心结论