dsh-tool-stat/packages/dsh-tool-stat

一句话定位

DSH 的数值统计工具，让 AI 对一组显式传入的有限数算出描述统计、百分位、频数分布和相关系数，全程零依赖纯函数，相同输入永远得到相同输出。

核心能力

• 一站式描述统计：count / sum / min / max / mean / median / variance / standardDeviation / q1 / q3 / iqr 一次给出
• 百分位计算：单次最多 100 个百分位，线性插值 h=(n-1)*p，按请求顺序原样返回（重复项不去重）
• 频数分布：按数值严格相等分组，输出 value / count / ratio，超过 10000 项自动截断并标注
• 相关性分析：Pearson 或 Spearman（midrank 平均秩）相关系数；零方差配对返回 defined:false + reason:"zero-variance"
• 数值稳定性：Neumaier 补偿求和、Welford 在线方差，原始输入数组永不被修改
• 严格输入校验：拒绝 NaN/Infinity（错误信息带下标定位），-0 归一化为 0，溢出抛 numeric-overflow 错误

技术实现

• 语言: TypeScript（ESM 模式，tsc 编译到 lib/）
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-invariants
• 架构模式: Cordis 插件模型（name + inject: ['tools'] + apply(ctx)），在 apply 中通过 ctx.tools.register(defineTool(...)) 注册名为 stat 的工具，4 个 action 通过 runStatAction 统一分发；安装由 cordis.patch.yml 用 - insert: 列表把 tool-stat 条目插入目标 profile 的 layer 栈
• 入口文件: src/index.ts（Cordis 插件入口与工具声明）/ src/validate.ts（参数校验与 -0 归一化）/ src/describe.ts（Neumaier 求和 + Welford 方差 + 线性插值百分位）/ src/correlation.ts（Pearson + Spearman midrank）/ src/frequency.ts（频数分布与截断规则）

适用场景

AI 从 CSV/JSON 抽出一列数值后想快速看出"平均水平、波动范围、分布形状、两组数是否同向变化"时，本工具以毫秒级纯函数调用直接给出结构化 JSON 报告，避免 AI 心算统计量时浮点错算且无法复核。零依赖、纯函数、不读写文件网络的特性，也让它适合作为可复现的中间计算步骤放进自动化流水线。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:omdsh-dev/dsh-toolkit/packages/dsh-tool-stat

配置项

本插件无需额外配置。stat 工具自身的 6 个调用参数（action / values / other / percentiles / method / sample）随每次调用传入，不存在宿主级配置文件或环境变量。

常见问题

Q: 这个工具能直接读 CSV 或 JSON 文件吗？

A: 不能。本工具不读取文件、不访问网络、不创建进程——你需要先用 dsh-tool-csv 把数据读出来，再用本插件对那组数算聚合；它只接收显式传入的有限数值数组。

Q: 输入数组里有 NaN 或 Infinity 会怎么样？

A: 直接报错。校验层逐元素检查 Number.isFinite，违规抛 stat: values[i] must be a finite number (got ...)，错误信息带下标定位，方便定位脏数据。-0 会被静默归一化为 0。

Q: 计算结果会不会出现 NaN 或 Infinity？

A: 不会。所有数值结果在返回前再做一次有限数检查，溢出时抛 stat: numeric-overflow 错误；canonical JSON 输出绝不含非有限值。

Q: correlation 遇到零方差序列返回什么？

A: 不是 NaN 也不是 ±Infinity，而是结构化对象：defined: false, value: null, reason: "zero-variance"。这让你在提示词里能直接处理"无定义"语义，而不是被非有限数坑到。

Q: 一次能算多少数据？百分位请求有上限吗？

A: values 长度 1..100000；单次 percentile 最多 100 个百分位；frequency distinct 项最多输出 10000，超出按 count 降序→value 升序截断；工具 timeoutMs 2000。同步 CPU 计算无法被协作式 timeout 真正中断。

Q: 跟 calculator 工具怎么分工？dsh-tool-csv 的 stats 不是已经有了吗？

A: calculator 只能对单条表达式求值（算不出分布或相关系数）；dsh-tool-csv 的 stats 只报告行列结构而非对一组观测值做统计聚合。本插件填补了"对一组数值数组做描述/分位/频数/相关"这一档。

Q: 安装到 web profile 后 dsh run 能直接用吗？

A: 不能。web 与 headless 是两个独立 profile，本插件需要在 headless（dsh run 默认）里也单独装一次。

Q: 输出里的 sample 字段是什么意思？

A: 控制方差分母：false（默认）= 总体方差（n 分母），true = 样本方差（n-1 分母）；describe 与 correlation 的 variance/standardDeviation 都按此口径计算。

上手难度

入门 — AI 只需按 4 个 action（describe / percentile / frequency / correlation）传一组有限数即可拿到结构化报告，无需理解底层数值算法或编写任何配置。

已知问题与限制

• 资源硬上限：values 长度上限 100000，超出直接抛错（stat: values exceeds the 100000 observation limit）；单次最多 100 个百分位请求；frequency distinct 项最多 10000，超出按 count 降序→value 升序截断并返回 truncated: true
• 计算同步阻塞：timeoutMs: 2000 是协议层声明，但纯函数同步执行无法被协作式中断，单次超大数组可能卡满超时
• 缺失值不处理：输入必须全部为有限数，含 NaN/Infinity 直接报错，不提供"忽略缺失"或"分桶近似"等宽松模式
• 零方差相关性无定义：当任一序列方差为 0 时 correlation 返回 defined:false + reason:"zero-variance"（而非 ±1），调用方需自行处理
• 工具参数写入会话日志：源码与 README 均明确提示"工具参数会记入会话日志，不要传入敏感数据"
• 平台隔离：web 与 headless profile 互不覆盖，需分别安装才能在交互式 web 与 dsh run 默认 headless 下同时使用

English

DSH 零依赖工具包 collection —— time / encoding / json / calculator / csv / regex / markdown / diff / stat / schema 十个确定性工具，统一入口一键安装。

为什么

DSH 生态仓库持续增长，单插件在 hub 中容易被淹没；collection 分类是辨识度最高的形态。本仓库把 10 个工具插件 vendored 冻结为 pack artifact 快照（各子仓库独立演进，当前源位于 omdsh-dev 组织下），统一工程、统一测试、统一维护。

定位（官方 Profile Bundle 生态方向）：本仓库是 collection 与安装辅助仓库——每个子包都是可独立安装/启用/禁用/卸载的 bundle（dsh plugin --profile <p> add <子包>）；collection 提供目录、清单与批量安装脚本。meta 包 @deepseek-ai/dsh-toolkit 保留为可选的原子挂载模型（见下文两种运行模型）。

分发边界：根 meta 包保持 private: true，用于 Git/collection 分发，不代表会发布到 npm registry。根目录已提交由当前 src 构建出的 lib/index.js 与 lib/types/index.d.ts，因此从 Git 安装时不依赖消费端 lifecycle；prepack 仍会在生成 pack artifact 前执行完整构建。

工具一览

架构

dsh-toolkit/
├── src/index.ts          # meta 包：相对路径动态导入 10 个子包 apply()，聚合注册
├── packages/dsh-tool-*   # vendored 子包（pack artifact 快照，name 保持 @deepseek-ai/dsh-tool-*）
├── scripts/
│   ├── link-deps.sh      # 构建期 junction（cordis → vendor/cordis，dsh-tools → packages/core/tools）
│   ├── build-all.sh      # 一键构建 10 子包 + meta 包（tsc）
│   ├── test-all.sh       # 一键跑 10 子包 vitest（合计用例数）
│   ├── install.sh        # meta / 逐包两种挂载模式（含 dry-run）
│   ├── install-web.sh    # 独立 bundle 批量安装 → web profile
│   ├── install-headless.sh # 独立 bundle 批量安装 → headless profile
│   └── install-all.sh    # web + headless 都装
├── catalog.json          # collection 清单（hub collection 分类识别依据）
└── tsconfig.base.json    # 共享编译配置（固化踩坑经验）

与实施文档方案 A 的工程化适配：子包为私有 Git/collection 包，peer 名解析在 profile 内不可行， 故 meta 包采用相对路径动态导入（零解析魔法、打包自足）；子包 runtime 依赖 （@deepseek-ai/dsh-tools）在 npm 独立模式（默认）下不依赖 DSH monorepo，monorepo 模式经子包构建期 junction 解析。

安装

仓库位于 omdsh-dev/dsh-toolkit（public）。

独立 bundle 模型（推荐）

每个子包独立安装、启用、禁用、卸载：

# 安装单个工具到 web profile
dsh plugin --profile web add github:omdsh-dev/dsh-tool-csv
# 一次性任务（headless）profile
dsh plugin --profile headless add github:omdsh-dev/dsh-tool-diff

批量安装（collection 辅助脚本，幂等——重复执行不会重复添加）：

./scripts/install-web.sh       # 全部 10 工具 → web profile
./scripts/install-headless.sh  # 全部 10 工具 → headless profile（dsh run 使用面）
./scripts/install-all.sh       # 两个 profile 都装

验证与运行：

dsh --profile web --dump-config | grep tool-csv     # 行存在即安装成功
dsh run "使用 csv 工具解析 'a,b\n1,2'"               # headless 端到端

⚠️ web 与 headless 是不同 profile：web 安装不会自动覆盖 headless；dsh run 默认使用 headless。 Windows 路径使用正斜杠（C:/...）。

npm pack tarball 安装

本地构建后用 tarball 路径安装（不依赖 GitHub）：

# tarball 方式（web 为例；headless 同）
npm pack
dsh plugin --profile web add <npm pack 产物 tarball 路径>

meta bundle 模型（可选）

需要一次原子挂载全部工具时，挂载根 meta 包：

dsh plugin --profile web add github:omdsh-dev/dsh-toolkit
dsh --profile web --dump-config | grep tool-kit

⚠️ 若 profile 已单独挂载过同名插件（tool-time/.../tool-diff/tool-stat/tool-schema），挂 meta 包会注册重名报错—— 此时先移除旧插件，或用独立 bundle 模型。meta apply 具备原子性（任一子插件失败时 逆序回滚已注册工具，不残留部分状态）。

手动安装与旧版本兼容

旧场景（monorepo 集成、不支持 Profile Bundle 的旧快照或插件开发调试环境——本地 junction/symlink、手动编辑 profile 层）。

构建与测试

npm 独立模式（默认，推荐）：无需 DSH monorepo；npm install（devDependencies 自包含）后即可：

npm run build:all           # 10 子包 + meta 包 tsc + 产物完整性验证（无 .ts 残留导入、10+1 个 lib/index.js）
bash scripts/test-all.sh    # 10 子包 vitest 全量（723 用例）；任一失败整体非零退出
npm pack                    # prepack 自包含（build:all），tarball 含 lib + 10 个子包

monorepo 模式（可选：源码贡献/旧 snapshot）：显式提供 DSH monorepo 根：

export DSH_MONOREPO=<DSH 0.1.0-rc.8（npm）安装路径>   # 或作为第一个参数
bash scripts/build-all.sh   # link-deps + 10 子包 + meta 包 tsc + 产物完整性验证
bash scripts/test-all.sh

prepack 已指向 build:all（完整构建 10 子包 + meta），保证 pack artifact 含全部运行入口；根 Git 入口由当前 src 预构建并提交。 本仓库只在本地验证构建、测试与 pack artifact；不要将这些结果解读为 npm registry 发布或未实际执行的 consumer/profile 验证。

同步 vendored（子仓库有更新时）

把 packages/<name> 与源仓库重新同步（src/tests/package.json/tsconfig/cordis.patch.yml/LICENSE/README.md），并在 README 标注子包版本。

新增工具

见 docs/CONTRIBUTING.md：复制模板子包 → 实现 → 测试 → build-all 验证 → 更新 catalog.json。

许可

MIT