前言¶

在 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