前言¶
DeepSeek Harness 的核心理念是“一切皆插件”，開發者可以通過插件擴展智能體的數據處理能力。在本地資費數據分析場景中，原始數據結構不統一、分析腳本難以複用、質量校驗難以追溯是常見痛點。針對這些需求，下面介紹 dsh-plugin-csv-report 插件，它將數據準備和描述統計流程封裝爲兩個 dsh 工具。
是什麼¶
該插件由 SUFE-Chaoyi 維護，旨在將資費數據分析流程重構爲可安裝、可複用、可審計的 DSH 插件。它解決了原始表結構不統一、分析腳本難複用、質量問題難追溯以及結果缺少上下游哈希鏈路的問題。
核心功能¶
插件提供以下核心能力：
- 數據準備 (
tariff_prepare)： 支持讀取dataDir內的 XLSX、XLSM 和 CSV；進行標準化（用戶標識、入網日期、數值字段）；生成 19 個字段的字段字典；校驗必填字段、重複用戶、非法數值、品牌枚舉等；輸出標準化 CSV 與準備階段清單。 - 描述統計 (
tariff_describe)： 生成逐字段數據質量報告；生成數值字段的均值、標準差、中位數、四分位數等統計；生成分類字段 Top N 分佈；生成價值合約、異網主卡和寬帶等二元特徵彙總；按套餐名稱、用戶屬地、品牌系列輸出分組統計；生成報告清單與 Markdown 索引。 - 數據安全： 工具僅讀取
dataDir內的相對路徑，返回不含用戶級記錄。 - 可復現： 通過 SHA-256 串聯原始文件、標準化數據與報告，鎖定 Node.js 與 Python 依賴。
安裝與啓用¶
- 確保已安裝 dsh、Node.js、pnpm 和 Python 3。
- 執行安裝命令：
dsh plugin --profile demo add github:SUFE-Chaoyi/dsh-plugin-csv-report
- 從 GitHub 安裝時，pnpm 可能要求允許插件執行
prepare構建腳本。僅在對源碼信任的情況下，在 profile 的pnpm-workspace.yaml中添加：
allowBuilds:
dsh-plugin-csv-report: true
- 重新運行安裝並驗證：
dsh --profile demo --dump-config
典型用法¶
安裝後，需在 dsh profile 的 cordis.patch.yml 中配置路徑。核心配置項如下：
- insert:
- id: csv-report
name: dsh-plugin-csv-report
config:
dataDir: /absolute/path/to/data
outputDir: /absolute/path/to/reports
pythonPath: /absolute/path/to/python
defaultSheet: 數據
dictionarySheet: 字段說明
preparedSubdir: prepared
minimumGroupSize: 30
topCategoryLimit: 20
maxInputBytes: 52428800
timeoutMs: 120000
配置完成後，典型的使用流程如下：
- 數據準備： 將原始資費表放入
dataDir/raw/目錄，在 dsh 對話中調用tariff_prepare。
請調用 tariff_prepare，處理 raw/老舊資費特徵.xlsx。
主數據工作表是“數據”，字段說明工作表是“字段說明”。
請返回數據質量狀態、樣本量、字段數、標準化 CSV 相對位置和警告摘要。
處理成功後，標準化文件位於 `dataDir/prepared/<原文件名>-<原始文件哈希前12位>/normalized_tariff.csv`。
- 描述統計： 使用上一步生成的相對路徑，調用
tariff_describe。
請調用 tariff_describe，分析：
prepared/<原文件名>-<哈希>/normalized_tariff.csv
請只基於聚合結果總結樣本規模、數據質量、套餐費用、話費、流量使用、分類構成和分組差異；不要輸出用戶級記錄，不做運營決策。
tariff_describe 會在 outputDir 下生成包含數據質量、數值彙總、分類分佈、二元特徵彙總、分組統計以及 Markdown 報告的文件集合。
適用場景與注意¶
- 適用場景： 適合需要進行本地資費數據處理、標準化字段定義、生成描述性統計報告且需保證數據可復現性的場景。
- 注意事項：
- 本插件不自動做業務決策，不提供因果推斷或用戶運營動作建議。
- 需信任源碼以允許 pnpm prepare 腳本執行。
- 數據安全邊界爲只讀取指定
dataDir內的相對路徑。 - 數據標識僅用於去重和質量校驗，不返回用戶級記錄。
經過上面的步驟，數據準備與描述統計的流程已被封裝爲標準化的工具調用。該插件通過鎖定環境依賴與哈希校驗，確保了分析結果的可復現性。相關目錄與源碼請參考：插件目錄 | GitHub 倉庫。
