dsh-data-insight 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/) 约定。
+
+## [0.1.0] - 2026-08-16
+
+### 新增
+- 主技能 `data-insight-runbook`：五阶段数据洞察流水线（受理 → 探查 → 指标 → 图表 → 报告），每阶段硬门槛。
+- 四种数据源接入：CSV、粘贴表格、SQL 查询结果、DuckDB 直连（可选，强制只读）。
+- 三通道图表规范（`docs/chart-spec.md`）：Markdown 表格 + Mermaid + ASCII。
+- 报告模板与严谨性检查清单（`docs/report-template.md`）。
+- 零依赖 CSV 探查脚本 `scripts/csv-profile.mjs`。
+- 可选 DuckDB CLI 安装脚本 `scripts/setup-duckdb.ps1`（winget / GitHub 直链，UTF-8 BOM）。
+- 样例 CSV 与样例报告（`examples/`）。
+- 发布与分发指南 `PUBLISHING.md`。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 duyanta123
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISHING.md

@@ -0,0 +1,79 @@
+# 发布与分发指南（PUBLISHING）
+
+本文档记录 `dsh-data-insight` 从源码到分发的完整步骤，供维护者在有网终端执行。
+
+## 当前状态（构建侧已就绪）
+
+- 包结构 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）。
+
+## 前置条件
+
+- 一个有网、能访问 github.com 与 registry.npmjs.org 的终端。
+- 已登录 npm：`npm login`（需要 npm 账号 + 2FA）。
+- GitHub 账号（用于建仓库与 push）。
+
+## 步骤 1：发布到 GitHub
+
+```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
+```
+
+推送后打一个版本 tag（可选但推荐，供 `dsh plugin add github:...#vX.Y.Z` 引用）：
+
+```powershell
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+## 步骤 2：发布到 npm
+
+```powershell
+cd D:\Agent预设\UI\dsh-data-insight
+npm view dsh-data-insight version   # 再次确认包名可用（应 404）
+npm login                           # 首次需要；已登录可跳过
+npm publish --access public
+```
+
+## 步骤 3：安装到 profile（二选一）
+
+发布后，任选一种分发形态安装：
+
+```powershell
+# npm 形态
+dsh plugin --profile web add 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：验证
+
+1. 重启 profile（`dsh web` 重开），技能列表应出现 `data-insight-runbook`。
+2. 说「分析 examples/sample-sales.csv 出报告」，确认五阶段执行并产出报告。
+3. 可选：`scripts/setup-duckdb.ps1` 装 DuckDB 后，验证直连只读查询。
+
+## 常见问题
+
+- **`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

@@ -0,0 +1,73 @@
+# dsh-data-insight
+
+DSH（DeepSeek Harness）**数据洞察技能插件**：把原始数据变成「业务结论 + 指标数据 + 图表」的结构化 Markdown 分析报告。
+
+纯指令型技能插件，零依赖、零构建。计算由宿主已提供的文件 / Shell 工具驱动的 LLM 完成，包内附带一个零依赖的 CSV 探查脚本与完整图表 / 报告规范。
+
+## 功能
+
+- **四种数据源**：CSV 文件、粘贴表格文本、SQL 查询结果、DuckDB 直连数据库（可选）。
+- **五阶段流水线**（每阶段带硬门槛）：输入受理 → 数据探查 → 指标计算 → 图表呈现 → 报告产出。
+- **三类指标**：汇总统计、同环比（基准期规则写死）、TopN、异常值（Z-score / IQR）。
+- **三通道图表**（全零依赖）：Markdown 表格 + 数字 / Mermaid / ASCII 条形图。
+- **严谨性保障**：结论必有数字支撑、事实与推断分离、口径可复现、不编造数据。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-data-insight
+```
+
+或手动两步（在目标 profile 目录下）：
+
+1. `package.json` 的 `dependencies` 加 `"dsh-data-insight": "^0.1.0"`；
+2. `dsh.profile.bundles` 数组加 `"dsh-data-insight"`。
+
+重启 profile 后，技能 `data-insight-runbook` 出现在技能列表即可用。
+
+## 使用
+
+在会话中说「分析这份 CSV 出报告」「看看这个数据」「帮我算一下指标」并附上数据源（文件路径 / 粘贴表格 / DuckDB 连接），模型会加载 `data-insight-runbook` 并按五阶段执行。产物是一份 Markdown 报告，落盘到工作区。
+
+### 快速示例
+
+```sh
+node scripts/csv-profile.mjs examples/sample-sales.csv
+```
+
+会输出 `examples/sample-sales.csv` 的探查报告（schema / 缺失 / 分布 / 异常），对应报告样例见 `examples/sample-report.md`。
+
+## 目录结构
+
+```
+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 探查脚本
+└── examples/                # 样例 CSV + 样例报告
+```
+
+## DuckDB 直连（可选）
+
+默认零依赖；如需直连数据库，安装 [DuckDB](https://duckdb.org/) 单文件 CLI（加入 PATH）：
+
+```sh
+# 连接串走环境变量，强制只读
+duckdb -readonly -csv -c "SELECT * FROM read_csv_auto('data.csv') LIMIT 100"
+duckdb -readonly -csv -c "SELECT ... LIMIT 5000" "$env:DATA_INSIGHT_DB_URL"
+```
+
+安全红线：一律 `-readonly`；连接串走环境变量 `DATA_INSIGHT_DB_URL`；查询默认 `LIMIT 5000`。
+
+## 参考文档
+
+- `skills/data-insight-runbook/SKILL.md` — 完整流程与门槛
+- `docs/chart-spec.md`、`docs/report-template.md` — 图表与报告规范
+- `examples/` — 输入 / 输出样例
+
+## 开源协议
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-data-insight — DSH bundle patch.
+#
+# 当某个 profile 在 dsh.profile.bundles 中列出本包时（dsh plugin add 即完成此事），
+# dsh 启动时把本补丁打入配置树：插入本包插件行，加载 package.json 的 main
+# （plugin/index.js），将自带 skills/ 注册为技能根。
+#
+# 人设与工具不在此处重复声明——宿主 profile（web/standard）已提供文件、shell、
+# 计划模式、web 搜索、子代理等 runbook 引用的全部工具。
+- insert:
+    - id: dsh-data-insight
+      name: dsh-data-insight

package/docs/chart-spec.md

@@ -0,0 +1,67 @@
+# 三通道图表规范（chart-spec）
+
+数据洞察报告的图表采用三通道策略，全部零依赖。**核心原则：图表只是呈现，数字才是根基——任何图表都必须能在正文/附录表格中找到对应数据点。**
+
+## 通道选择
+
+| 通道 | 用途 | 渲染环境 | 优先级 |
+|---|---|---|---|
+| 主通道：Markdown 表格 + 关键数字 | 指标、TopN、占比、对比 | 任何查看器 | 必须 |
+| 次通道：Mermaid | 趋势、占比、流程的可视化增强 | GitHub / VS Code 等支持 Mermaid 的渲染器 | 可选 |
+| 兜底：ASCII 条形图 | 量级对比的纯文本可视化 | 任何查看器（含 DSH Web GUI） | 可选 |
+
+> ⚠️ DSH Web GUI 的 Markdown 渲染**不支持 Mermaid**（会显示为代码块）。因此主通道表格必须能独立撑起报告；Mermaid 仅作为「贴到 GitHub/文档平台」时的增强，正文要标注「需 Mermaid 渲染器」。
+
+## 主通道：Markdown 表格
+
+用 GFM 表格，数字右对齐，统一千分位与小数位（默认保留 2 位小数，金额类可保留 0 位并注明单位）。
+
+```markdown
+| 渠道 | 销售额（万元） | 环比 | 占比 |
+|---:|---:|---:|---:|
+| 线上直营 | 1,234.56 | +12.3% | 45.2% |
+| 线下门店 | 987.65 | -3.1% | 36.1% |
+| 分销 | 512.30 | +1.5% | 18.7% |
+```
+
+## 次通道：Mermaid
+
+### 趋势（xychart-beta）
+```mermaid
+xychart-beta
+    title "月度销售额趋势（万元）"
+    x-axis ["1月","2月","3月","4月","5月","6月"]
+    y-axis "销售额" 0 --> 1500
+    line [980, 1120, 1050, 1280, 1340, 1420]
+```
+
+### 占比（pie）
+```mermaid
+pie title 渠道销售占比
+    "线上直营" : 45.2
+    "线下门店" : 36.1
+    "分销" : 18.7
+```
+
+### 注意
+- 数据点必须与附录表格完全一致。
+- Mermaid 语法错一个字符整段不渲染，生成后自查：标签无未转义引号、百分比为纯数字、`xychart-beta` 系列括号匹配。
+
+## 兜底：ASCII 条形图
+
+用 code block 画，纯文本处处可读。
+
+```
+渠道销售对比（万元）
+线上直营  ████████████████████ 1234.56
+线下门店  ████████████████      987.65
+分销      ████████              512.30
+```
+
+条形宽度按「值 / 最大值 × 20」取整（最大 20 格），保证比例可读。
+
+## 禁止事项
+
+- ❌ 手写 SVG：模型手写 SVG 易错、体积大、难维护。
+- ❌ 图表数字与表格不一致（这是最严重的可信度问题）。
+- ❌ 用图片外链代替本地可复现的表格数据。

package/docs/report-template.md

@@ -0,0 +1,72 @@
+# 报告模板与严谨性检查清单（report-template）
+
+数据洞察报告的固定骨架。产出时严格按此结构，并在交付前过完下方的严谨性检查清单。
+
+## 报告骨架
+
+```markdown
+# {主题}数据洞察报告
+
+> 数据源：{文件路径 / 粘贴 / DuckDB 连接类型}
+> 时间范围：{起止}　粒度：{日/周/月}
+> 生成时间：{时间}　工具：dsh-data-insight v{版本}
+
+## 一、核心结论
+1. **{结论}**：{具体数字支撑}（见「三/四/五」节）
+2. …
+（3–5 条，每条带数字）
+
+## 二、数据概况
+- 行数 / 列数 / 编码 / 分隔符
+- 缺失值概览（哪些列缺失、缺失率）
+- 数据质量问题与处置（重复、单位、异常格式）
+
+## 三、关键指标
+| 指标 | 值 | 口径 |
+|---|---|---|
+| … | … | … |
+（汇总统计：总数/均值/中位数/环比/同比…）
+
+## 四、趋势与对比
+- 趋势图（三通道，见 docs/chart-spec.md）
+- 解读：涨跌与关键拐点，附数据表格
+
+## 五、TopN 与异常
+- TopN 表（N=5，并列标注）
+- 异常值表（值 + 所属维度 + 判定依据）
+
+## 六、风险与建议
+- 【事实】…（纯数据陈述）
+- 【推断】…（模型分析，标注依据与置信度）
+- 建议（可执行、对应到具体数字）
+
+## 附录 A：口径与可复现说明
+- 数据源、过滤条件、缺失/重复处置
+- 算法与参数（同环比基准期、TopN 取值、异常阈值 Z=3 / IQR）
+- 核心指标计算公式
+- 图表数据表（每个图的数据源）
+
+## 附录 B：探查记录
+- Schema（列名 + 推断类型）
+- 值分布摘要
+```
+
+## 严谨性检查清单（交付前逐项过）
+
+| # | 检查项 | 通过标准 |
+|---|---|---|
+| 1 | 结论有数字 | 每条核心结论引用至少一个具体数字，数字可在正文/附录查到 |
+| 2 | 事实/推断分离 | 「风险与建议」用【事实】【推断】明确标注；推断给出依据 |
+| 3 | 口径可复现 | 附录含过滤条件、聚合方式、计算公式、算法参数 |
+| 4 | 图数一致 | 每个图表数据点都能在附录表格找到 |
+| 5 | 不编造 | 无探查依据的数字不出现；缺失值处置如实记录 |
+| 6 | 单位与小数位 | 全文单位统一（万元/元/人…），小数位一致 |
+| 7 | 时间口径明确 | 起止日期、粒度、时区（如涉及时区）写明 |
+| 8 | 脱敏 | 附录不含密码/密钥；连接串脱敏 |
+
+任一条不过，回到对应阶段返工，禁止「应该没问题」式收尾。
+
+## 精简版（用户要求「快速看一眼」时）
+
+保留：核心结论 + 数据概况 + 关键指标表 + 一个图表（趋势或 TopN）。
+豁免：完整趋势解读、附录 B。**不豁免**：检查项 1（结论有数字）、2（事实/推断分离）、8（脱敏）。

package/examples/sample-report.md

@@ -0,0 +1,102 @@
+# 电商销售数据洞察报告（示例）
+
+> 数据源：`examples/sample-sales.csv`
+> 时间范围：2025-01-01 ~ 2025-01-10　粒度：日
+> 生成时间：示例　工具：dsh-data-insight v0.1.0
+
+## 一、核心结论
+
+1. **线上直营是绝对主力渠道**：销售额占比 **60.3%**，日均约 **2.58 万元**，是线下门店（约 0.99 万元）的 **2.6 倍**（见「四、趋势与对比」）。
+2. **1 月 9 日出现销售尖峰**：当日销售额 **138,600 元**（其中线上直营华北单笔 120,000 元），为日均（42,767 元）的 **3.2 倍**，属显著异常值（Z-score > 3），需核实是否为大促/错单（见「五、TopN 与异常」）。
+3. **数据存在少量质量问题**：`orders` 列缺失 3 行（缺失率 9.7%），并存在 1 条重复行（01-03 分销华南），已按「保留首条」去重处置（见「二、数据概况」）。
+4. **剔除异常后整体趋势平稳上行**：1 月 5 日后销售额由 31,890 元温和爬升至 36,100 元（见「四」）。
+
+## 二、数据概况
+
+- 行数 31（含 1 条重复）→ 去重后 **30**；列数 **5**；编码 UTF-8；分隔符逗号。
+- 缺失值：`orders` 缺失 3 行（9.7%，去重后 2 行），`revenue` 无缺失。
+- 质量处置：1 条重复行按「保留首条」去重；`orders` 缺失行在订单类聚合中排除，并如实记录。
+
+## 三、关键指标
+
+| 指标 | 值 | 口径 |
+|---|---:|---|
+| 总销售额 | 427,671.25 元 | 去重后 30 行 revenue 求和 |
+| 总订单 | 2,636 单 | 去重后 orders 求和（排除 2 个缺失） |
+| 日均销售额 | 42,767.13 元 | 总销售额 / 10 天 |
+| 客单价 | 162.24 元 | 总销售额 / 总订单 |
+| 环比（第 10 日 vs 第 9 日） | -73.9% | 受 1/9 异常尖峰回落影响 |
+
+## 四、趋势与对比
+
+### 渠道销售额占比
+| 渠道 | 销售额（元） | 占比 |
+|---:|---:|---:|
+| 线上直营 | 257,801.25 | 60.3% |
+| 线下门店 | 99,400.00 | 23.2% |
+| 分销 | 70,470.00 | 16.5% |
+
+```mermaid
+pie title 渠道销售占比
+    "线上直营" : 60.3
+    "线下门店" : 23.2
+    "分销" : 16.5
+```
+
+### 渠道日均销售额对比（ASCII）
+```
+线上直营  ████████████████████ 25780
+线下门店  ████████              9940
+分销      █████                 7047
+```
+
+### 日销售额趋势（Mermaid，需 Mermaid 渲染器）
+```mermaid
+xychart-beta
+    title "日销售额趋势（元）"
+    x-axis ["01","02","03","04","05","06","07","08","09","10"]
+    y-axis "销售额" 0 --> 140000
+    line [30641, 30040, 30241, 31480, 31890, 32480, 33800, 32400, 138600, 36100]
+```
+
+## 五、TopN 与异常
+
+### Top 5 销售额日
+| 日期 | 销售额（元） |
+|---|---:|
+| 2025-01-09 | 138,600.00 |
+| 2025-01-10 | 36,100.00 |
+| 2025-01-07 | 33,800.00 |
+| 2025-01-06 | 32,480.00 |
+| 2025-01-08 | 32,400.00 |
+
+### 异常值
+| 值 | 所属 | 判定 |
+|---|---:|---|
+| 120,000.00（revenue） | 2025-01-09 线上直营华北 | Z-score > 3，需核实大促/错单 |
+| 900（orders） | 2025-01-09 线上直营华北 | Z-score > 3，同上 |
+
+## 六、风险与建议
+
+- 【事实】线上直营贡献 60.3% 销售额，渠道集中度偏高。
+- 【事实】1/9 出现 138,600 元销售额尖峰，显著偏离日均值。
+- 【推断】尖峰可能为大促活动或数据录入错误，需业务侧核实（置信度：中）。
+- 【建议】① 核实 1/9 订单真实性，避免结论被异常值带偏；② 分销占比仅 16.5%，若为增长目标，建议补充渠道运营动作；③ 修复 `orders` 缺失，保证口径一致。
+
+## 附录 A：口径与可复现说明
+
+- 数据源：`examples/sample-sales.csv`（UTF-8，逗号分隔）。
+- 过滤：无；重复行去重（保留首条）。
+- 缺失处置：`orders` 缺失行在订单类聚合中排除；`revenue` 无缺失。
+- 算法与参数：占比 = 渠道销售额 / 总销售额；环比 = (本期−上期)/上期；异常阈值 Z-score |z|>3；TopN = 5。
+- 客单价 = 总销售额 / 总订单；日均销售额 = 总销售额 / 天数。
+
+## 附录 B：探查记录（节选，见 `node scripts/csv-profile.mjs examples/sample-sales.csv`）
+
+| 列名 | 类型 | 缺失 | 摘要 |
+|---|---|---|---|
+| date | date | 0 | 2025-01-01 ~ 2025-01-10，唯一值 10 |
+| channel | text | 0 | 唯一值 3：分销/线上直营/线下门店 |
+| region | text | 0 | 唯一值 3：华东/华南/华北 |
+| orders | number | 3 | min=30 max=900 mean≈94.1（含异常） |
+| revenue | number | 0 | min=6,120 max=120,000 mean≈14,018 |

package/examples/sample-sales.csv

@@ -0,0 +1,32 @@
+date,channel,region,orders,revenue
+2025-01-01,线上直营,华东,120,15600.50
+2025-01-02,线上直营,华东,98,12890.00
+2025-01-03,线上直营,华东,105,14120.75
+2025-01-01,线下门店,华东,45,8920.00
+2025-01-02,线下门店,华东,52,10100.00
+2025-01-03,线下门店,华东,47,9230.00
+2025-01-01,分销,华南,30,6120.00
+2025-01-02,分销,华南,35,7050.00
+2025-01-03,分销,华南,,6890.00
+2025-01-04,线上直营,华东,110,14980.00
+2025-01-04,线下门店,华东,50,9800.00
+2025-01-04,分销,华南,33,6700.00
+2025-01-05,线上直营,华东,115,15230.00
+2025-01-05,线下门店,华东,48,9450.00
+2025-01-05,分销,华南,36,7210.00
+2025-01-06,线上直营,华东,118,15680.00
+2025-01-06,线下门店,华东,51,9900.00
+2025-01-06,分销,华南,34,6900.00
+2025-01-07,线上直营,华东,122,16000.00
+2025-01-07,线下门店,华东,53,10400.00
+2025-01-07,分销,华南,37,7400.00
+2025-01-08,线上直营,华东,,16500.00
+2025-01-08,线下门店,华东,49,9600.00
+2025-01-08,分销,华南,31,6300.00
+2025-01-09,线上直营,华北,900,120000.00
+2025-01-09,线下门店,华北,55,10800.00
+2025-01-09,分销,华北,39,7800.00
+2025-01-10,线上直营,华北,126,16800.00
+2025-01-10,线下门店,华北,57,11200.00
+2025-01-10,分销,华北,40,8100.00
+2025-01-03,分销,华南,,6890.00

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "dsh-data-insight",
+  "version": "0.1.0",
+  "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",
+  "main": "./plugin/index.js",
+  "exports": {
+    ".": "./plugin/index.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "plugin/index.js",
+    "cordis.patch.yml",
+    "skills/",
+    "docs/",
+    "scripts/",
+    "examples/",
+    "README.md",
+    "CHANGELOG.md",
+    "PUBLISHING.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-skill-filesystem": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-skill-filesystem": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "data-analysis",
+    "data-insight",
+    "analytics",
+    "report",
+    "csv",
+    "duckdb",
+    "skills"
+  ]
+}

package/plugin/index.js

@@ -0,0 +1,41 @@
+/**
+ * dsh-data-insight — DSH (DeepSeek Harness) 插件入口。
+ *
+ * 复用官方 @deepseek-ai/dsh-skill-filesystem 提供者，把本包自带的 skills/
+ * 目录注册为技能根（includeDefaultRoots: false，避免与宿主 profile 的
+ * 技能根重复）。零构建：本 ESM 模块由 harness 直接加载。
+ *
+ * 本包为纯指令型技能插件：它只注入 runbook 指令，计算由宿主已提供的
+ * 文件 / shell 工具驱动的 LLM 完成；csv-profile.mjs 脚本由 runbook 指引
+ * 通过 shell 直接调用（Node 内建能力，零依赖，不 spawn 子进程）。
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { FileSystemSkillProvider } from "@deepseek-ai/dsh-skill-filesystem";
+
+export const name = "dsh-data-insight";
+export const inject = ["skills"];
+
+const rootDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+const skillsDir = join(rootDir, "skills");
+
+export function apply(ctx, config = {}) {
+  let provider;
+  ctx.skills.registerProvider((control) => {
+    provider = new FileSystemSkillProvider(ctx, control, {
+      providerName: "dsh-data-insight",
+      includeDefaultRoots: false,
+      customSkillDirs: [skillsDir],
+      ...config,
+    });
+    return provider;
+  });
+  ctx.effect(
+    function* () {
+      yield async () => {
+        await provider?.dispose();
+      };
+    },
+    "dsh-data-insight skill provider"
+  );
+}

package/scripts/csv-profile.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+/**
+ * csv-profile.mjs — 零依赖 CSV 数据探查脚本（纯 Node 内建，不 spawn 子进程）。
+ *
+ * 用途：读取一个 CSV/TSV 文件，输出结构化探查报告（schema / 缺失值 /
+ * 值分布 / 重复行 / 数值统计 / 异常值），供 data-insight-runbook 阶段 1 使用。
+ *
+ * 用法：
+ *   node csv-profile.mjs <file> [--sep <分隔符>] [--encoding <utf8|utf16le|latin1>] [--limit <N>] [--json]
+ *
+ * 说明：
+ *   - 默认自动探测分隔符（, \t ;）。
+ *   - 编码默认 utf8；GBK 文件请先转码（PowerShell:  Get-Content -Encoding GBK file | Set-Content -Encoding UTF8 out）。
+ *   - --limit 限制读取行数（默认 0 = 全部），用于超大数据集抽样探查。
+ */
+
+import { readFileSync } from "node:fs";
+
+// ── 参数解析 ────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const file = args.find((a) => !a.startsWith("--"));
+const getArg = (name, def) => {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] ? args[i + 1] : def;
+};
+const limit = Number(getArg("--limit", "0")) || 0;
+const encoding = getArg("--encoding", "utf8");
+const asJson = args.includes("--json");
+const forcedSep = getArg("--sep", null);
+
+if (!file) {
+  console.error("用法: node csv-profile.mjs <file> [--sep <分隔符>] [--encoding utf8|utf16le|latin1] [--limit N] [--json]");
+  process.exit(2);
+}
+
+// ── 读取与编码 ─────────────────────────────────────────────────────────────
+let text;
+try {
+  const buf = readFileSync(file);
+  if (buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) text = buf.slice(3).toString(encoding);
+  else text = buf.toString(encoding);
+} catch (e) {
+  console.error(`读取失败: ${e.message}`);
+  process.exit(1);
+}
+
+// ── 分隔符探测 ──────────────────────────────────────────────────────────────
+function detectSep(line) {
+  if (forcedSep) return forcedSep;
+  const cands = [",", "\t", ";", "|"];
+  // 只在引号外计数
+  let best = ",";
+  let bestCount = -1;
+  for (const c of cands) {
+    let count = 0;
+    let inQ = false;
+    for (const ch of line) {
+      if (ch === '"') inQ = !inQ;
+      else if (ch === c && !inQ) count++;
+    }
+    if (count > bestCount) {
+      bestCount = count;
+      best = c;
+    }
+  }
+  return best;
+}
+
+// ── CSV 解析（支持引号包裹与转义引号）──────────────────────────────────────
+function parseCsv(text, sep) {
+  const rows = [];
+  let field = "";
+  let row = [];
+  let inQ = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inQ) {
+      if (ch === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else inQ = false;
+      } else field += ch;
+    } else {
+      if (ch === '"') inQ = true;
+      else if (ch === sep) {
+        row.push(field);
+        field = "";
+      } else if (ch === "\n" || ch === "\r") {
+        if (ch === "\r" && text[i + 1] === "\n") i++;
+        row.push(field);
+        field = "";
+        if (row.some((c) => c.trim() !== "")) rows.push(row);
+        row = [];
+      } else field += ch;
+    }
+  }
+  if (field !== "" || row.length) {
+    row.push(field);
+    if (row.some((c) => c.trim() !== "")) rows.push(row);
+  }
+  return rows;
+}
+
+const sampleLine = text.split(/\r?\n/).find((l) => l.trim() !== "") || "";
+const sep = detectSep(sampleLine);
+const rows = parseCsv(text, sep);
+if (rows.length === 0) {
+  console.error("未解析到数据行。");
+  process.exit(1);
+}
+
+const header = rows[0].map((h) => h.trim());
+let data = rows.slice(1);
+if (limit > 0) data = data.slice(0, limit);
+const nRows = data.length;
+const nCols = header.length;
+
+// ── 类型推断 ────────────────────────────────────────────────────────────────
+const numRe = /^[-+]?\d[\d,]*(\.\d+)?$/;
+const dateRe = /^\d{4}[-/]\d{1,2}[-/]\d{1,2}/;
+const boolRe = /^(true|false|yes|no|是|否|y|n)$/i;
+
+function inferType(vals) {
+  const nonEmpty = vals.filter((v) => v.trim() !== "");
+  if (nonEmpty.length === 0) return "empty";
+  if (nonEmpty.every((v) => numRe.test(v.replace(/,/g, "")))) return "number";
+  if (nonEmpty.every((v) => dateRe.test(v.trim()))) return "date";
+  if (nonEmpty.every((v) => boolRe.test(v.trim()))) return "boolean";
+  return "text";
+}
+
+function toNum(v) {
+  return Number(v.replace(/,/g, ""));
+}
+
+// ── 统计计算 ────────────────────────────────────────────────────────────────
+function quantile(sorted, q) {
+  if (sorted.length === 0) return null;
+  const pos = (sorted.length - 1) * q;
+  const base = Math.floor(pos);
+  const rest = pos - base;
+  return sorted[base] + (sorted[base + 1] !== undefined ? (sorted[base + 1] - sorted[base]) * rest : 0);
+}
+function mean(arr) {
+  return arr.reduce((a, b) => a + b, 0) / arr.length;
+}
+function stddev(arr) {
+  const m = mean(arr);
+  return Math.sqrt(arr.reduce((a, b) => a + (b - m) ** 2, 0) / arr.length);
+}
+
+const cols = header.map((name, i) => {
+  const vals = data.map((r) => (r[i] !== undefined ? r[i].trim() : ""));
+  const type = inferType(vals);
+  const missing = vals.filter((v) => v === "").length;
+  const missingRate = nRows ? ((missing / nRows) * 100).toFixed(1) : "0.0";
+  const info = { name, type, missing, missingRate };
+  if (type === "number") {
+    const nums = vals.filter((v) => v.trim() !== "").map(toNum).sort((a, b) => a - b);
+    info.min = nums[0];
+    info.max = nums[nums.length - 1];
+    info.mean = mean(nums);
+    info.median = quantile(nums, 0.5);
+    info.stddev = stddev(nums);
+    info.p25 = quantile(nums, 0.25);
+    info.p75 = quantile(nums, 0.75);
+    info.p90 = quantile(nums, 0.9);
+    // Z-score 异常值 (|z| > 3)
+    const m = info.mean;
+    const s = info.stddev || 1;
+    const outliers = [];
+    vals.forEach((v, idx) => {
+      if (v.trim() === "") return;
+      const x = toNum(v);
+      if (Math.abs((x - m) / s) > 3) outliers.push({ row: idx + 2, value: x });
+    });
+    info.outliers = outliers.slice(0, 20);
+    info.outlierCount = outliers.length;
+  } else if (type === "text") {
+    const freq = new Map();
+    vals.forEach((v) => {
+      if (v.trim() === "") return;
+      freq.set(v, (freq.get(v) || 0) + 1);
+    });
+    info.unique = freq.size;
+    info.top = [...freq.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+  } else if (type === "date") {
+    const dates = vals.filter((v) => v.trim() !== "").map((v) => v.trim());
+    info.min = dates.sort()[0];
+    info.max = dates.sort()[dates.length - 1];
+    info.unique = new Set(dates).size;
+  } else if (type === "boolean") {
+    const freq = new Map();
+    vals.forEach((v) => {
+      if (v.trim() === "") return;
+      freq.set(v.trim().toLowerCase(), (freq.get(v.trim().toLowerCase()) || 0) + 1);
+    });
+    info.top = [...freq.entries()];
+  }
+  return info;
+});
+
+// ── 重复行 ──────────────────────────────────────────────────────────────────
+const seen = new Set();
+let dupCount = 0;
+data.forEach((r) => {
+  const key = r.join("\u0001");
+  if (seen.has(key)) dupCount++;
+  else seen.add(key);
+});
+
+// ── 输出 ────────────────────────────────────────────────────────────────────
+const fmt = (n) => (typeof n === "number" ? (Math.round(n * 100) / 100).toLocaleString() : String(n ?? ""));
+const report = {
+  file,
+  encoding,
+  delimiter: sep === "\t" ? "TAB" : sep,
+  rows: nRows,
+  columns: nCols,
+  duplicateRows: dupCount,
+  columnsDetail: cols,
+};
+
+if (asJson) {
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(0);
+}
+
+const out = [];
+out.push(`# CSV 数据探查报告`);
+out.push(``);
+out.push(`- 文件：\`${file}\``);
+out.push(`- 编码：${encoding}　分隔符：${report.delimiter}`);
+out.push(`- 数据行数（不含表头）：${nRows}　列数：${nCols}　重复行：${dupCount}`);
+out.push(``);
+out.push(`## Schema 与质量`);
+out.push(`| 列名 | 类型 | 缺失数 | 缺失率 | 摘要 |`);
+out.push(`|---|---|---|---|---|`);
+for (const c of cols) {
+  let summary = "";
+  if (c.type === "number")
+    summary = `min=${fmt(c.min)} max=${fmt(c.max)} mean=${fmt(c.mean)} median=${fmt(c.median)} std=${fmt(c.stddev)} P25=${fmt(c.p25)} P75=${fmt(c.p75)} P90=${fmt(c.p90)}`;
+  else if (c.type === "text")
+    summary = `唯一值=${c.unique} Top=${(c.top || []).map(([k, v]) => `${k}(${v})`).join(", ")}`;
+  else if (c.type === "date") summary = `范围=${c.min} ~ ${c.max} 唯一值=${c.unique}`;
+  else if (c.type === "boolean") summary = (c.top || []).map(([k, v]) => `${k}=${v}`).join(", ");
+  else summary = "（全空列）";
+  out.push(`| ${c.name} | ${c.type} | ${c.missing} | ${c.missingRate}% | ${summary} |`);
+}
+out.push(``);
+const hasOutliers = cols.some((c) => c.type === "number" && c.outlierCount > 0);
+if (hasOutliers) {
+  out.push(`## 数值异常值（Z-score |z|>3）`);
+  for (const c of cols) {
+    if (c.type === "number" && c.outlierCount > 0) {
+      out.push(`- **${c.name}**：${c.outlierCount} 个异常值，示例：${c.outliers.map((o) => `行${o.row}=${fmt(o.value)}`).join(", ")}`);
+    }
+  }
+  out.push(``);
+}
+out.push(`> 说明：缺失值按空字符串判定；数值型已去除千分位逗号。GBK 文件请先转码为 UTF-8。`);
+console.log(out.join("\n"));

package/scripts/setup-duckdb.ps1

@@ -0,0 +1,83 @@
+# setup-duckdb.ps1 — 安装 DuckDB CLI（可选依赖，用于 dsh-data-insight 直连数据库路径）
+#
+# 用法：
+#   powershell -ExecutionPolicy Bypass -File scripts/setup-duckdb.ps1            # 安装最新稳定版
+#   powershell -ExecutionPolicy Bypass -File scripts/setup-duckdb.ps1 -Version 1.5.5   # 指定版本
+#
+# 安装位置：$env:LOCALAPPDATA\DuckDB\cli\duckdb.exe，并写入用户 PATH（持久）。
+# 安全红线由 runbook 保证：调用时一律 -readonly，连接串走环境变量。
+
+param(
+  [string]$Version = ""   # 留空则自动取 duckdb.org 最新稳定版
+)
+
+$ErrorActionPreference = "Stop"
+
+function Get-LatestVersion {
+  try {
+    $v = (Invoke-WebRequest -Uri "https://duckdb.org/data/latest_stable_version.txt" -UseBasicParsing -TimeoutSec 20).Content.Trim()
+    if ($v -match '^\d+\.\d+\.\d+$') { return $v }
+  } catch {
+    Write-Warning "无法获取最新版本号：$($_.Exception.Message)"
+  }
+  return "1.5.5"
+}
+
+if (-not $Version) { $Version = Get-LatestVersion }
+Write-Host "目标 DuckDB 版本：$Version"
+
+$installDir = Join-Path $env:LOCALAPPDATA "DuckDB\cli"
+$exe = Join-Path $installDir "duckdb.exe"
+
+# 已安装且版本匹配则跳过
+if (Test-Path $exe) {
+  $installed = (& $exe --version 2>$null | Select-Object -First 1)
+  if ($installed -match [regex]::Escape($Version)) {
+    Write-Host "已安装 DuckDB $Version（$exe）"
+    Write-Host "确认 PATH 已包含：$installDir"
+    exit 0
+  }
+}
+
+# ── 方案 1：winget ──────────────────────────────────────────────────────────
+$winget = Get-Command winget -ErrorAction SilentlyContinue
+if ($winget) {
+  Write-Host "尝试 winget 安装 DuckDB.cli $Version ..."
+  winget install --id DuckDB.cli --version $Version --accept-source-agreements --accept-package-agreements --silent
+  if ($LASTEXITCODE -eq 0) {
+    Write-Host "winget 安装完成。若 PATH 未更新，请重开终端或手动添加：$installDir"
+    exit 0
+  }
+  Write-Warning "winget 安装未成功（exit $LASTEXITCODE），回退到直接下载。"
+}
+
+# ── 方案 2：直接下载 GitHub release ────────────────────────────────────────
+New-Item -ItemType Directory -Force -Path $installDir | Out-Null
+$zip = Join-Path $env:TEMP "duckdb_cli-windows-amd64-$Version.zip"
+$url = "https://github.com/duckdb/duckdb/releases/download/v$Version/duckdb_cli-windows-amd64.zip"
+
+Write-Host "下载 $url ..."
+Invoke-WebRequest -Uri $url -OutFile $zip -UseBasicParsing -TimeoutSec 120
+
+Write-Host "解压到 $installDir ..."
+Expand-Archive -Path $zip -DestinationPath $installDir -Force
+Remove-Item $zip -Force -ErrorAction SilentlyContinue
+
+if (-not (Test-Path $exe)) {
+  Write-Error "安装失败：未找到 $exe。请手动从 https://duckdb.org/docs/stable/clients/cli/overview 安装。"
+  exit 1
+}
+
+# ── 写入用户 PATH（持久）───────────────────────────────────────────────────
+$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+if ($userPath -notlike "*$installDir*") {
+  [Environment]::SetEnvironmentVariable("Path", "$userPath;$installDir", "User")
+  Write-Host "已写入用户 PATH：$installDir（重开终端后生效）"
+}
+
+# ── 验证 ───────────────────────────────────────────────────────────────────
+Write-Host "验证安装："
+& $exe --version
+Write-Host "`n完成。用法示例（只读）："
+Write-Host "  duckdb -readonly -csv -c ""SELECT * FROM read_csv_auto('data.csv') LIMIT 100"""
+Write-Host "  duckdb -readonly -csv -c ""SELECT ... LIMIT 5000"" `"`$env:DATA_INSIGHT_DB_URL`""

package/skills/data-insight-runbook/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: data-insight-runbook
+description: 数据洞察报告：输入原始数据（CSV 文件 / 粘贴表格 / SQL 查询结果 / DuckDB 直连数据库）→ 输出带图表与业务结论的结构化 Markdown 分析报告。覆盖数据探查、指标计算、同环比、TopN、异常值、图表生成与严谨性检查。需要做数据分析、出报告、看数据、算指标、画图时加载本技能。
+---
+
+# 数据洞察 Runbook
+
+把原始数据变成「业务结论 + 指标数据 + 图表」的结构化 Markdown 报告。
+
+## 执行原则（贯穿全程，违反即返工）
+
+1. **每个数字必须有口径**：时间范围、过滤条件、聚合方式、计算公式都要写清楚。
+2. **每条结论必须有数字支撑**：禁止无依据的推断；结论引用的数字必须在正文或附录可查到。
+3. **区分事实与推断**：数据事实（GMV 环比 -12%）与模型推断（可能受大促错期影响）分开标注，推断要给出依据与置信度。
+4. **报告可复现**：附录记录原始数据、处理步骤、算法参数，任何人能按附录重算得到同样数字。
+5. **不编造数据**：探查不到的数字不猜；缺失值按下方规则处置并如实记录。
+
+按阶段执行，每阶段有硬性门槛；未过门槛不得进入下一阶段。
+
+---
+
+## 阶段 0：输入受理与口径确认
+
+识别数据源类型，确认分析口径。**门槛：数据已加载 + 口径已确认，才进入探查。**
+
+### 0.1 识别数据源
+- **CSV 文件**：用户给路径，或在工作区找 `.csv`/`.tsv`。
+- **粘贴表格**：用户直接粘贴的表格文本（含 SQL 查询结果导出）。约定：列用 `|` 或制表符分隔，首行为表头；NULL 写 `NULL`/`null`/空值需说明。
+- **DuckDB 直连**：见下方「数据源接入细则·DuckDB」。
+
+### 0.2 确认口径（缺失就用 ask_user_question 一次问清）
+- **分析目标**：要回答什么业务问题？（看趋势 / 找异常 / 做对比 / 找 TopN / 综合体检）
+- **指标定义**：核心指标（GMV、转化率、留存…）的确切计算公式。
+- **时间范围与粒度**：起止日期、聚合粒度（日/周/月）。
+- **维度**：按什么分组（渠道/地区/品类…）。
+- **过滤条件**：排除哪些脏数据 / 测试数据。
+
+用户说「随便 / 你定」时采用默认：全量数据、日粒度、核心指标按列名语义推断并在报告中明确写出推断依据。
+
+---
+
+## 阶段 1：数据探查
+
+**门槛：探查记录完成，异常数据有处置决定。**
+
+### 1.1 加载与解析
+- CSV：用 `scripts/csv-profile.mjs` 探查（优先），或 read 头几行确认结构。
+- 编码：优先 UTF-8；出现乱码再按 GBK 重读。分隔符：`,` > `\t` > `;` 依次尝试，以「列数一致且无单列吞并」为准。
+- 记录：文件路径、行数（不含表头）、列数、编码、分隔符。
+
+### 1.2 探查内容（写入探查记录，供附录引用）
+- **Schema**：列名、每列推断类型（数值/文本/日期/布尔/ID）。
+- **缺失值**：每列缺失数、缺失率；>20% 的列标注。
+- **值分布**：数值列（min/max/mean/median/分位数）、文本列（唯一值数、Top 高频值）、日期列（范围与粒度）。
+- **脏数据**：重复行、异常格式（日期不统一、数字带单位/千分位）、明显错误值（负数年龄、未来日期）。
+
+### 1.3 异常处置（必须明确决定，写进报告附录）
+- 缺失值：删除 / 填 0 / 填均值 / 单独标记——按列语义决定并记录。
+- 重复行：去重（保留规则）或保留（说明）。
+- 单位不一致：统一单位并记录换算。
+
+---
+
+## 阶段 2：指标计算
+
+**门槛：每个输出数字都有明确口径与计算公式。**
+
+用确定性规则计算，禁止每轮自创算法。可用 `scripts/csv-profile.mjs` 或让 LLM 按规则手算（大数据量优先脚本，避免算错与上下文爆掉）。
+
+### 2.1 汇总统计
+总数、求和、均值、中位数、标准差、min/max、分位数（P25/P50/P75/P90）。
+
+### 2.2 同环比（基准期规则写死）
+- 环比：本期 vs 上一期（日环比=昨天；周环比=上周；月环比=上月）。
+- 同比：本期 vs 去年同期；跨年数据缺失时降级为「不可算，记录原因」。
+- 增长率公式：`(本期 − 基期) / 基期 × 100%`；基期为 0 时标注「不适用（基期为 0）」。
+
+### 2.3 TopN
+- N 默认 5（报告空间有限），用户可指定 5/10/20。
+- 按指标降序；并列时都列出并标注并列名次。
+
+### 2.4 异常值
+- 数值列：Z-score 法 `|z| > 3` 判定异常，同时给出 IQR（1.5×IQR）对照；口径写进附录。
+- 报告中异常值列出「值 + 所属维度 + 判定依据」，不做无依据的归因猜测。
+
+---
+
+## 阶段 3：图表呈现（三通道）
+
+**门槛：图中每个数据点都能在正文或附录表格找到，禁止图表与数字不一致。**
+
+三通道规则见 `docs/chart-spec.md`，要点：
+1. **主通道**：Markdown 表格 + 关键数字——永远可靠，任何查看器都渲染。
+2. **次通道**：Mermaid（趋势用 `xychart-beta`、占比用 `pie`），标注「需 Mermaid 渲染器」；DSH Web GUI 不渲染 Mermaid，主通道表格必须能独立撑起报告。
+3. **兜底**：ASCII 条形图（code block 内），纯文本处处可读。
+- **禁止**手写 SVG（易错、难维护）。
+
+---
+
+## 阶段 4：报告产出
+
+**门槛：严谨性检查清单全过。**
+
+### 4.1 模板与检查清单
+严格按 `docs/report-template.md` 的骨架与严谨性检查清单产出，固定结构：
+核心结论 → 数据概况 → 关键指标 → 趋势与对比 → TopN 与异常 → 风险与建议 → 附录（口径与可复现说明）。
+
+### 4.2 硬性要求
+- 核心结论 3–5 条，每条带具体数字。
+- 「风险与建议」中事实与推断分开标注。
+- 附录含：数据源、时间范围、过滤条件、缺失/重复处置、算法与参数、图表数据表。
+- 报告以 Markdown 文件落盘到工作区（文件名如 `data-insight-report.md`），并汇报路径。
+
+---
+
+## 数据源接入细则
+
+### CSV 文件
+- 优先 `node scripts/csv-profile.mjs <file.csv>` 出探查报告，再按口径计算。
+- 大文件（>2000 行）：先探查，指标计算交给脚本/DuckDB，不要让 LLM 逐行读全文（会爆上下文）。
+
+### 粘贴表格 / SQL 查询结果
+- 直接按上述阶段 1 解析（表头 + 分隔符 + 类型推断）。
+- 若来自 SQL：记录来源查询（脱敏后写入附录），确认是否已聚合。
+
+### DuckDB 直连
+- **启用检测**：`duckdb --version` 可用才走直连；不可用时 CSV/粘贴仍全功能，直连路径明确告知「需安装 DuckDB（见 scripts/setup-duckdb.ps1）」，不静默降级。
+- **安全红线（必须遵守）**：
+  - 一律 `-readonly`，禁止任何写库 / 建表 / `INSTALL`/`LOAD` 之外的破坏性语句。
+  - 连接串走环境变量 `DATA_INSIGHT_DB_URL`，禁止把密码写进命令或报告。
+  - 查询加 `LIMIT`（默认 5000），列宽截断；超限提示分批。
+- **调用方式（直接调 CLI，勿写 Node spawn 包装——规避沙箱子进程管道 EPERM）**：
+  - CSV/Parquet 直接查：`duckdb -readonly -csv -c "SELECT * FROM read_csv_auto('data.csv') LIMIT 100"`
+  - 远程库：`duckdb -readonly -csv -c "SELECT ... LIMIT 5000" "$env:DATA_INSIGHT_DB_URL"`
+
+---
+
+## 沙箱与环境约束（重要）
+
+- 运行环境受 DSH 文件沙箱限制：读写尽量落在工作区内；`workdir` 必须指向已存在目录。
+- **不要写 Node 脚本去 spawn 子进程**（如脚本内调用 duckdb/ffmpeg）：confined 模式下子进程管道捕获会报 `EPERM`。duckdb 由 runbook 指引通过 shell 工具直接调用；`csv-profile.mjs` 只做纯文件读写与计算，不 spawn 子进程。
+- 需要联网查数据字典 / 口径时用 web_search，不臆造。
+
+## 例外与裁剪
+
+- 极小数据（≤50 行、≤10 列）：可跳过脚本，LLM 直接探查与计算，但五阶段门槛不豁免。
+- 用户明确只要「快速看一眼」：产出精简版（核心结论 + 关键指标表 + 一个图表），但严谨性清单中「结论有数字、区分事实/推断」不豁免。
+
+## 参考文档
+
+- `docs/chart-spec.md`：三通道图表规范与代码示例。
+- `docs/report-template.md`：报告骨架与严谨性检查清单。
+- `scripts/csv-profile.mjs`：零依赖 CSV 探查脚本。