dsh-plugin-csv-report

一个面向 CSV 描述统计与可复现报告的 DeepSeek Harness 插件。它把本地 CSV 的数据质量检查、连续变量描述统计、分类变量分布、二元特征占比与分组统计封装为 dsh 工具 tariff_describe。

快速了解

项目维度	内容
项目目标	将数据分析脚本重构为可安装、可复用的 dsh 插件。
解决的问题	数据分析脚本难复用、分析过程难审计、Agent 容易混入用户级数据。
核心实现	使用 TypeScript/Cordis 注册 Agent 工具；使用 Python/pandas 生成结构化统计报告；限制工具只能读取指定数据目录中的相对 CSV 路径。
可复现机制	记录输入 SHA-256、样本与字段规模、Python/pandas 版本；同一环境重复运行可核验报告文件哈希。
数据实践	基于 11,729 行、19 字段的运营商资费套餐脱敏数据完成验证；仓库仅展示演示行和完整聚合报告。
技术栈	DeepSeek Harness、Cordis、TypeScript、Node.js、Python、pandas、Git。

项目开发过程及 AI 协作记录见 开发日记。

适用场景

• 需要让 Agent 在本地对 CSV 执行描述统计，而不是把整份数据粘贴进提示词；
• 需要输出均值、标准差、中位数、四分位数、分类频数、二元特征占比和分组统计；
• 需要为分析结果保留输入哈希、依赖版本和可复现报告；
• 需要以插件形式复用既有的 pandas 分析工作流。

本插件是描述性分析工具，暂不提供因果推断、用户价值判断或自动决策。

安装

前提：已安装 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

配置

安装后，在 profile 的 cordis.patch.yml 覆盖路径。示例见 example/config/cordis.example.yml。

- insert:
    - id: csv-report
      name: dsh-plugin-csv-report
      config:
        dataDir: /absolute/path/to/csv-data
        outputDir: /absolute/path/to/reports
        pythonPath: /absolute/path/to/python

安装 Python 依赖：

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

调用

启动对应 profile 后，在 dsh Web UI 中输入：

请调用 tariff_describe 工具分析 old_tariff.csv。
只使用聚合结果总结样本规模、数据质量、套餐费用、话费、流量使用和分组差异；不要输出任何用户级信息。

工具只接受 dataDir 下的相对 .csv 文件名，并返回报告目录、样本量与输入 SHA-256。报告目录包含：

• data_quality.csv
• numeric_summary.csv
• categorical_distribution.csv
• binary_feature_summary.csv
• grouped_numeric_summary.csv
• manifest.json
• report.md

示例与复现

example/ 提供脱敏字段样例、少量数据值与对完整脱敏数据生成的原始聚合报告。复现步骤见 docs/REPRODUCIBILITY.zh-CN.md。

dsh对话示例 该文件记录了作者使用该插件与 dsh 的对话完整内容。