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。