dsh-plugin-csv-report

一个面向本地资费数据准备、描述统计与可复现报告的 DeepSeek Harness 插件。

插件将业务数据分析中“运营决策之前”的数据处理流程封装为两个 dsh 工具：

原始 XLSX / CSV
  -> tariff_prepare：标准化、字段字典、数据质量校验
  -> tariff_describe：聚合描述统计与可复现报告
  -> 为分析人员或决策者提供数据支撑

本插件不自动做业务决策，不提供因果推断或用户运营动作建议。

HR 快速了解

开发过程见 开发日记。

功能

1. 数据准备：tariff_prepare

• 支持读取 dataDir 内的 XLSX、XLSM 和 CSV；
• 标准化用户标识、入网日期和数值字段；
• 生成 19 个字段的字段字典；
• 校验必填字段、重复用户标识、非法数值、品牌枚举、二元字段与饱和度范围；
• 输出标准化 CSV 与准备阶段清单。

2. 描述统计：tariff_describe

• 生成逐字段数据质量报告；
• 生成数值字段的均值、标准差、中位数、四分位数等统计；
• 生成分类字段 Top N 分布；
• 生成价值合约、异网主卡和宽带等二元特征汇总；
• 按套餐名称、用户属地、品牌系列输出分组统计；
• 生成报告清单与 Markdown 索引。

安装

前提：已安装 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 中配置路径。完整示例见 example/config/cordis.example.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

Python 环境

在插件源码目录创建虚拟环境并安装锁定依赖：

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock.txt

然后将配置中的 pythonPath 设为：

/插件绝对路径/.venv/bin/python

调用示例

第一步：准备原始资费表

将原始表放入 dataDir/raw/ 后，在 dsh 对话中输入：

请调用 tariff_prepare，处理 raw/老旧资费特征.xlsx。
主数据工作表是“数据”，字段说明工作表是“字段说明”。
请返回数据质量状态、样本量、字段数、标准化 CSV 相对位置和警告摘要。

成功后，标准化文件位于：

dataDir/prepared/<原文件名>-<原始文件哈希前12位>/normalized_tariff.csv

第二步：生成描述统计报告

使用上一步生成的相对路径：

请调用 tariff_describe，分析：
prepared/<原文件名>-<哈希>/normalized_tariff.csv

请只基于聚合结果总结样本规模、数据质量、套餐费用、话费、流量使用、分类构成和分组差异；不要输出用户级记录，不做运营决策。

输出文件

tariff_describe 会在 outputDir 下生成：

normalized_tariff-<标准化文件哈希前12位>/
├── data_quality.csv
├── numeric_summary.csv
├── categorical_distribution.csv
├── binary_feature_summary.csv
├── grouped_numeric_summary.csv
├── manifest.json
└── report.md

完整参数、返回字段和每个文件的字段定义见 工具与输出协议。

数据口径与质量状态

• 共定义 19 个标准字段；
• 入网日期 仅用于入网批次分析，不计算当前在网时长；
• 流量与语音饱和度使用比例值，1 表示 100%；
• pass 表示无质量问题；
• warning 表示存在非阻断性问题；
• failed_quality 表示存在阻断性质量错误。

详见 数据口径。

示例与复现

example/ 提供脱敏字段样例、少量演示数据和完整脱敏数据生成的聚合报告。完整原始业务数据不随仓库发布。

从 XLSX 标准化到统计报告的复现与哈希核验方法见 可复现说明。

开发与测试

pnpm install
pnpm run typecheck
pnpm run test:ts

.venv/bin/python -m unittest discover -s python/tests -p 'test_*.py'

pnpm test
pnpm run build

当前测试覆盖路径安全、配置校验、Python 子进程调用、工具注册、数据准备、质量校验和描述统计报告。

文档

• 架构说明
• 数据口径
• 工具与输出协议
• 可复现说明
• 开发日记

致谢与许可证

本插件使用 DeepSeek Harness 的插件接口构建；详情见 NOTICE.md。本仓库采用 MIT License。