dsh-data-insight 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/) 约定。
 
+## [0.1.1] - 2026-08-16
+
+### 修复
+- DuckDB 直连调用方式（SKILL.md / README）：CSV/Parquet 无库查询去掉 `-readonly`——v1.5.5 实测不带库文件时 CLI 打开内存库，`-readonly` 会报 `Cannot launch in-memory database in read-only mode`；`-readonly` 保留用于库文件 / 远程库连接（实测 INSERT 等写语句被拦截）。
+
+### 新增
+- `scripts/setup-duckdb.sh`：macOS/Linux 安装脚本（brew / GitHub release / `~/.local/bin`），与 Windows 版 `setup-duckdb.ps1` 对齐。
+- `test/csv-profile.test.mjs`：csv-profile CLI 契约测试（`node:test` 零依赖，10 例：分隔符探测 / 引号与转义 / 千分位 / 混合类型降级 / 残缺行 / `--limit` / BOM / 退出码），`npm test` 运行。
+- runbook：CLI 缺失时引导运行对应平台的安装脚本。
+
 ## [0.1.0] - 2026-08-16
 
 ### 新增

package/README.md

@@ -20,7 +20,7 @@ dsh plugin --profile web add dsh-data-insight
 
 或手动两步（在目标 profile 目录下）：
 
-1. `package.json` 的 `dependencies` 加 `"dsh-data-insight": "^0.1.0"`；
+1. `package.json` 的 `dependencies` 加 `"dsh-data-insight": "^0.1.1"`；
 2. `dsh.profile.bundles` 数组加 `"dsh-data-insight"`。
 
 重启 profile 后，技能 `data-insight-runbook` 出现在技能列表即可用。
@@ -47,20 +47,23 @@ dsh-data-insight/
 ├── 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 + 样例报告
 ```
 
 ## DuckDB 直连（可选）
 
-默认零依赖；如需直连数据库，安装 [DuckDB](https://duckdb.org/) 单文件 CLI（加入 PATH）：
+默认零依赖；如需直连数据库，安装 [DuckDB](https://duckdb.org/) 单文件 CLI（加入 PATH）。可使用安装脚本：Windows `scripts/setup-duckdb.ps1`，macOS/Linux `scripts/setup-duckdb.sh`。
 
 ```sh
-# 连接串走环境变量，强制只读
-duckdb -readonly -csv -c "SELECT * FROM read_csv_auto('data.csv') LIMIT 100"
+# 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"
 ```
 
-安全红线：一律 `-readonly`；连接串走环境变量 `DATA_INSIGHT_DB_URL`；查询默认 `LIMIT 5000`。
+安全红线：连接库一律 `-readonly`（写语句会被拦截）；连接串走环境变量 `DATA_INSIGHT_DB_URL`；查询默认 `LIMIT 5000`。
 
 ## 参考文档
 

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "dsh-data-insight",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
+  "scripts": {
+    "test": "node --test test/csv-profile.test.mjs"
+  },
   "main": "./plugin/index.js",
   "exports": {
     ".": "./plugin/index.js",

package/scripts/setup-duckdb.sh

@@ -0,0 +1,90 @@
+#!/bin/sh
+# setup-duckdb.sh — 安装 DuckDB CLI（可选依赖，用于 dsh-data-insight 直连数据库路径；macOS / Linux）
+#
+# 用法：
+#   sh scripts/setup-duckdb.sh                    # 安装最新稳定版
+#   sh scripts/setup-duckdb.sh 1.5.5              # 指定版本
+#
+# 安装位置：$HOME/.local/bin/duckdb，并提示加入 PATH。
+# 安全红线由 runbook 保证：连接库一律 -readonly，连接串走环境变量 DATA_INSIGHT_DB_URL。
+
+set -eu
+
+VERSION="${1:-}"
+
+get_latest_version() {
+  v=$(curl -fsSL --max-time 20 https://duckdb.org/data/latest_stable_version.txt 2>/dev/null || true)
+  case "$v" in
+    [0-9]*.[0-9]*.[0-9]*) echo "$v" ;;
+    *) echo "1.5.5" ;;
+  esac
+}
+
+[ -z "$VERSION" ] && VERSION=$(get_latest_version)
+echo "目标 DuckDB 版本：$VERSION"
+
+INSTALL_DIR="$HOME/.local/bin"
+EXE="$INSTALL_DIR/duckdb"
+
+# 已安装且版本匹配则跳过
+if [ -x "$EXE" ]; then
+  installed=$("$EXE" --version 2>/dev/null | head -n 1 || true)
+  case "$installed" in
+    "v$VERSION "*|*" $VERSION "*)
+      echo "已安装 DuckDB $VERSION（$EXE）"
+      exit 0
+      ;;
+  esac
+fi
+
+# ── 方案 1：macOS 用 Homebrew ────────────────────────────────────────────────
+if command -v brew >/dev/null 2>&1; then
+  echo "尝试 brew 安装 duckdb ..."
+  if brew install duckdb; then
+    echo "brew 安装完成。验证："
+    duckdb --version
+    exit 0
+  fi
+  echo "brew 安装未成功，回退到直接下载。" >&2
+fi
+
+# ── 方案 2：直接下载 GitHub release ─────────────────────────────────────────
+OS=$(uname -s)
+ARCH=$(uname -m)
+case "$OS:$ARCH" in
+  Darwin:*) ASSET="duckdb_cli-osx-universal.zip" ;;
+  Linux:x86_64) ASSET="duckdb_cli-linux-amd64.zip" ;;
+  Linux:arm64|Linux:aarch64) ASSET="duckdb_cli-linux-arm64.zip" ;;
+  *)
+    echo "不支持的平台：$OS $ARCH。请手动安装：https://duckdb.org/docs/stable/clients/cli/overview" >&2
+    exit 1
+    ;;
+esac
+
+URL="https://github.com/duckdb/duckdb/releases/download/v$VERSION/$ASSET"
+mkdir -p "$INSTALL_DIR"
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+echo "下载 $URL ..."
+curl -fSL --max-time 120 -o "$TMP/duckdb.zip" "$URL"
+
+unzip -o "$TMP/duckdb.zip" -d "$TMP" >/dev/null
+mv "$TMP/duckdb" "$EXE"
+chmod +x "$EXE"
+
+# ── PATH 提示（不擅改 shell 配置）──────────────────────────────────────────
+case ":$PATH:" in
+  *":$INSTALL_DIR:"*) ;;
+  *)
+    echo "提示：$INSTALL_DIR 不在 PATH。请在 ~/.profile 或 ~/.zshrc 添加："
+    echo "  export PATH=\"\$HOME/.local/bin:\$PATH\""
+    ;;
+esac
+
+echo "验证安装："
+"$EXE" --version
+echo ""
+echo "完成。用法示例（只读）："
+echo "  duckdb -csv -c \"SELECT * FROM read_csv_auto('data.csv') LIMIT 100\""
+echo "  duckdb -readonly -csv -c \"SELECT ... LIMIT 5000\" \"\$DATA_INSIGHT_DB_URL\""

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

@@ -124,14 +124,16 @@ description: 数据洞察报告：输入原始数据（CSV 文件 / 粘贴表格
 - 若来自 SQL：记录来源查询（脱敏后写入附录），确认是否已聚合。
 
 ### DuckDB 直连
-- **启用检测**：`duckdb --version` 可用才走直连；不可用时 CSV/粘贴仍全功能，直连路径明确告知「需安装 DuckDB（见 scripts/setup-duckdb.ps1）」，不静默降级。
+- **启用检测**：`duckdb --version` 可用才走直连；不可用时 CSV/粘贴仍全功能，直连路径明确告知「需安装 DuckDB（Windows：scripts/setup-duckdb.ps1，macOS/Linux：scripts/setup-duckdb.sh）」，并引导用户运行对应平台的安装脚本，不静默降级。
 - **安全红线（必须遵守）**：
-  - 一律 `-readonly`，禁止任何写库 / 建表 / `INSTALL`/`LOAD` 之外的破坏性语句。
+  - 连接库文件 / 远程库时一律 `-readonly`（v1.5.5 实测会拦截 INSERT/CREATE 等写语句），禁止任何写库 / 建表 / 破坏性语句。
   - 连接串走环境变量 `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"`
+- **调用方式（直接调 CLI，勿写 Node spawn 包装——规避沙箱子进程管道 EPERM；已在 v1.5.5 实测）**：
+  - CSV/Parquet 直接查（无库文件，**不加 `-readonly`**——不带库文件时 CLI 打开内存库，`-readonly` 会报 `Cannot launch in-memory database in read-only mode`；仅执行 SELECT，无持久化写入）：
+    `duckdb -csv -c "SELECT * FROM read_csv_auto('data.csv') LIMIT 100"`
+  - 库文件 / 远程库（`-readonly` 强制只读，连接串走环境变量）：
+    `duckdb -readonly -csv -c "SELECT ... LIMIT 5000" "$env:DATA_INSIGHT_DB_URL"`（POSIX shell 为 `"$DATA_INSIGHT_DB_URL"`）
 
 ---