dsh-plugin-csv-report
一个面向本地资费数据准备、描述统计与可复现报告的 DeepSeek Harness 插件。
插件将业务数据分析中“运营决策之前”的数据处理流程封装为两个 dsh 工具：
原始 XLSX / CSV
-> tariff_prepare：标准化、字段字典、数据质量校验
-> tariff_describe：聚合描述统计与可复现报告
-> 为分析人员或决策者提供数据支撑
本插件不自动做业务决策，不提供因果推断或用户运营动作建议。
HR 快速了解
| 项目维度 | 内容 |
|---|
| 项目目标 | 将资费数据分析流程重构为可安装、可复用、可审计的 dsh 插件。 |
| 解决的问题 | 原始表结构不统一、分析脚本难复用、质量问题难追溯、结果缺少上下游哈希链路。 |
| 核心实现 | TypeScript/Cordis 注册 dsh 工具；Python/pandas 执行数据准备和描述统计；SHA-256 串联原始文件、标准化数据与报告。 |
| 数据安全边界 | 工具只读取指定 dataDir 内的相对路径；工具返回不含用户级记录；用户标识仅用于去重和质量校验。 |
| 可复现机制 | 锁定 Node.js 与 Python 依赖；记录输入哈希、样本规模、字段、参数和运行环境；支持重复运行哈希核验。 |
| 数据实践 | 已对 11,729 行、19 字段的本地脱敏资费数据完成验证。 |
| 技术栈 | DeepSeek Harness、Cordis、TypeScript、Vitest、Node.js、Python、pandas、openpyxl。 |
开发过程见 开发日记。
功能
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
| 配置项 | 说明 |
|---|
dataDir | 原始文件与标准化 CSV 所在目录。工具仅可读取该目录内的相对路径。 |
outputDir | 描述统计报告输出目录。 |
pythonPath | Python 可执行文件路径。建议指向插件专用虚拟环境。 |
defaultSheet | XLSX 主数据工作表名称，默认 数据。 |
dictionarySheet | XLSX 字段说明工作表名称，默认 字段说明。 |
preparedSubdir | dataDir 内标准化数据输出子目录，默认 prepared。 |
minimumGroupSize | 纳入分组统计的最小样本量，默认 30。 |
topCategoryLimit | 每个分类字段输出的最多类别数，默认 20。 |
maxInputBytes | 单个输入文件最大字节数，默认 50 MB。 |
timeoutMs | 单次工具调用超时时间，默认 120 秒。 |
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。
