前言¶
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 仓库。
