CSV 统计报告SUFE-Chaoyi/dsh-plugin-csv-report

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/-/normalized_tariff.csv

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

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

请调用 tariff_describe，分析：
prepared/-/normalized_tariff.csv

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

输出文件

tariff_describe 会在 outputDir 下生成：

normalized_tariff-/
├── 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。