前言¶

在 DSH 工作流中，Agent 常常从 CSV / JSON 提取出数值数组后，需要继续计算均值、分位数、频数和相关性。单表达式求值不足以完成分位数和相关性，模型心算也不便于复现。dsh-tool-stat 注册 stat 工具，接收显式传入的有限数值数组或成对观测值，返回结构化输出。

这是什么¶

omdsh-dev/dsh-tool-stat 是 DSH 统计工具插件，许可为 MIT。它围绕一组有限数值提供描述统计、百分位数、频数分布和相关性计算。

这里的“零依赖”指无第三方数值库；package.json 仍声明 peerDependencies 与 devDependencies。插件按纯函数、确定性方式执行：不读取文件、不访问网络、不创建进程、不保存状态。

核心功能¶

describe：描述统计¶

对显式传入的 values 数组计算以下字段：

• count
• sum
• min
• max
• mean
• median
• variance
• standardDeviation
• q1
• q3
• iqr

sample=true 时使用样本方差，分母为 n-1；默认 sample=false，分母为 n。

percentile：百分位数¶

percentiles 为 0..100 的数组，最多 100 项。计算使用线性插值：

h = (n - 1) * p

输出按请求顺序返回，重复百分位保留。

frequency：频数分布¶

按严格相等值分组，输出 value / count / ratio，并按 value 升序输出。ratio 的分母为原始计数。

当 distinct 输出超过 10,000 时，插件按确定规则截断并标注。

correlation：相关性¶

计算 Pearson 或 Spearman 相关系数。method 可选：

• pearson，默认
• spearman，使用 midrank 平均秩

other 是与 values 等长的配对观测。若配对出现零方差，返回：

defined: false
reason: zero-variance

不会返回 NaN 或 ±Infinity。

数值约束与安全¶

• 观测值数量范围为 1..100,000，超限直接报错。
• 百分位请求不超过 100 个。
• 拒绝 NaN / Infinity。
• -0 在输入与输出中均规范化为 0。
• 中间或最终结果返回前做有限数回检。
• timeoutMs 为 2000。
• 工具参数会记入会话日志，不要传入敏感数据。

安装与启用¶

安装到 web profile¶

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

web 与 headless 是不同 profile。web 安装不会自动覆盖 headless；dsh run 默认使用 headless profile。若要使用对应 profile，需要确保该 profile 中已安装插件。

启动 web¶

npx -p @deepseek-ai/dsh@next dsh web

资料建议不要使用 install -g 全局安装。

验证安装¶

dsh --profile web --dump-config | grep tool-stat

运行验证¶

dsh run "使用 stat 工具计算 [1,2,3,4,5] 的描述统计"

典型用法¶

下面按 action 说明调用要点。

action=describe¶

可先用上面的 dsh run 示例计算 [1,2,3,4,5] 的描述统计。输出包含：

count / sum / min / max / mean / median / variance / standardDeviation / q1 / q3 / iqr

action=percentile¶

需要传入：

values
percentiles

percentiles 是 0..100 的数组。输出按请求顺序返回，重复百分位保留。

action=frequency¶

需要传入：

values

输出按严格相等值分组，字段为：

value / count / ratio

action=correlation¶

需要传入：

values
other
method

other 必须与 values 等长。method 可选 pearson 或 spearman。零方差时返回：

defined: false
reason: zero-variance

适用场景与注意¶

适合以下场景：

• 已在 Agent 或脚本中得到一组有限数值，需要在 DSH 中做可复现统计。
• 需要计算均值、中位数、四分位数、IQR、频数分布和相关系数。
• 需要明确拒绝非有限数值，并避免依赖模型心算。

使用前注意：

• 插件会以当前 dsh 进程权限运行，安装前应检查源码与许可证。
• 参数会进入会话日志，不要传入敏感数据。
• values 数量、百分位数量和 distinct 输出都有预算，超限或截断时会按插件规则报错或标注。
• package.json 声明 Node 引擎为：

^22.19.0 || >=24.0.0

• package.json 声明 peerDependencies：

@deepseek-ai/cordis ^4.0.1
@deepseek-ai/dsh-tools >=0.0.1-rc.1 <0.2.0
@deepseek-ai/dsh-invariants >=0.0.1-rc.1 <0.2.0

• “零依赖”指无第三方数值库，不代表没有任何 peerDependencies 或 devDependencies。

结尾¶

dsh-tool-stat 的价值在于把一组有限数值统计成结构化、可验证、可复现的结果，而不是依赖模型即时心算。

GitHub 仓库：https://github.com/omdsh-dev/dsh-tool-stat