dsh-plugin-csv-report

Readme

# dsh-plugin-csv-report

一个面向本地资费数据准备、描述统计与可复现报告的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件。

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

```text
原始 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。 |

开发过程见 [开发日记](docs/DEVELOPMENT_DIARY.zh-CN.md)。

## 功能

### 1. 数据准备：`tariff_prepare`

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

### 2. 描述统计：`tariff_describe`

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

## 安装

前提：已安装 dsh、Node.js、pnpm 和 Python 3。

```bash
dsh plugin --profile demo add github:SUFE-Chaoyi/dsh-plugin-csv-report
```

从 GitHub 安装时，pnpm 可能要求允许插件执行 `prepare` 构建脚本。仅在信任对应提交时，在 profile 的 `pnpm-workspace.yaml` 中添加：

```yaml
allowBuilds:
  dsh-plugin-csv-report: true
```

然后重新运行安装，并验证配置：

```bash
dsh --profile demo --dump-config
```

## 配置

安装后，在 dsh profile 的 `cordis.patch.yml` 中配置路径。完整示例见 [example/config/cordis.example.yml](example/config/cordis.example.yml)。

```yaml
- 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 环境

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

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

然后将配置中的 `pythonPath` 设为：

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

## 调用示例

### 第一步：准备原始资费表

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

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

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

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

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

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

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

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

### 输出文件

`tariff_describe` 会在 `outputDir` 下生成：

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

完整参数、返回字段和每个文件的字段定义见 [工具与输出协议](docs/OUTPUT_CONTRACT.zh-CN.md)。

## 数据口径与质量状态

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

详见 [数据口径](docs/DATA_SCHEMA.zh-CN.md)。

## 示例与复现

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

从 XLSX 标准化到统计报告的复现与哈希核验方法见 [可复现说明](docs/REPRODUCIBILITY.zh-CN.md)。

## 开发与测试

```bash
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 子进程调用、工具注册、数据准备、质量校验和描述统计报告。

## 文档

- [架构说明](docs/ARCHITECTURE.zh-CN.md)
- [数据口径](docs/DATA_SCHEMA.zh-CN.md)
- [工具与输出协议](docs/OUTPUT_CONTRACT.zh-CN.md)
- [可复现说明](docs/REPRODUCIBILITY.zh-CN.md)
- [开发日记](docs/DEVELOPMENT_DIARY.zh-CN.md)

## 致谢与许可证

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