SUFE-Chaoyi/dsh-tariff-analysis-bot

DSH 老旧资费数据分析 Bot

项目类型：个人项目 / 数据产品
项目周期：2026.09
我的角色：业务分析流程设计、需求确认、插件验收与项目发布
本项目主要证据等级：模拟数据验证
公开边界：代码、SOP、模拟数据与聚合报告公开；真实业务数据和用户级结果不公开

首屏摘要（HR 60 秒阅读区）

老旧资费用户分析往往横跨原始表清洗、质量核验、描述统计、分群标签和报告交付，任一步骤的字段漂移或数据版本错配都会影响后续判断。本项目将决策前流程拆为两个可独立安装的 DeepSeek Harness 插件，并由 Bot 组合层固化四步工具链、质量门禁、SHA-256 追溯、透明标签和人工交接规范。我负责业务目标与职责边界、分析 SOP、规则确认、插件验收、脱敏示例和 GitHub 发布；Bot 只提供数据事实与证据，不决定用户迁转、不推荐套餐。公开仓库使用 N=10 的完全模拟数据完成端到端复现，四阶段均按契约运行并生成 5 张图表、HTML、Excel 和聚合 CSV；两个插件共 57 个自动化测试通过。另在本地业务样本 N=11,729 上完成定向验收，但原始数据和用户级结果不公开，也不据此宣称生产效果。

模拟数据标签覆盖图

图示：两个插件对 10 行模拟数据实际生成的标签聚合图；只证明流程和中文可视化可运行，不代表真实业务分布。

1. 项目背景与目标

1.1 问题与目标用户

- 目标用户／业务角色：数据分析人员、用户运营人员、业务复核者和最终决策者。
- 原始问题：原始资费表需要经过标准化、质量检查、版本核验、用户与群体分析、可视化和证据归档，才能成为可复核的数据材料。
- 项目目标：用 DSH 对话统一触发上述流程，并确保每一步都有明确输入、状态、输出和停止条件。
- 不在本项目范围内：自动制定运营策略、决定用户迁转、推荐具体套餐、生成营销名单、因果推断或代替业务人员决策。

1.2 我的角色与职责边界

- 项目角色：个人项目发起者与业务分析流程负责人。
- 本人直接负责范围：提出业务场景、纠正决策边界、确认字段与入网日期口径、验收图表和 DSH 对话、整理公开证据并发布三个仓库。
- 实现方式：通过逐步需求确认和验收推进两个插件，使用 AI 编程助手协助代码与文档实现；所有业务边界和发布结果由本人确认。
- 协作接口：两个插件通过标准化 CSV、三份清单和哈希契约交接；业务人员在 Bot 输出之后进行人工解释和决策。
- 未负责范围：原始数据采集、真实运营执行、生产部署和业务效果评估。
- 成果归属说明：本仓库是项目组合与展示层；插件源码分别归档在两个独立仓库。

2. 整体方案与关键取舍

2.1 仓库组成

| 仓库 | 固定版本 | 职责 |
| --- | --- | --- |
| dsh-plugin-csv-report | v0.2.0 | 原始文件标准化、质量门禁和描述统计 |
| dsh-plugin-tariff-analysis | v0.1.0 | 哈希核验、用户/群体分析、透明标签和可视化 |
| dsh-tariff-analysis-bot | 当前仓库 | 组合配置、业务 SOP、提示词、脱敏证据和项目说明 |

当前仓库不是第三个插件，不复制两个插件的源码。

2.2 数据流

原始 XLSX / CSV
│
▼
tariff_prepare ── 标准化 + 第一层质量门禁
│ normalized_tariff.csv + prepare_manifest.json
▼
tariff_describe ─ 聚合描述统计 + 第二层质量门禁
│ manifest.json
▼
tariff_analyze ── 三方哈希核验 + 用户指标 + 透明标签 + 群体画像
│ analysis_manifest.json
▼
tariff_visualize ─ HTML + PNG + Excel + 透视式 CSV
│
▼
人工复核的数据支撑 ──► 由业务决策者自行决策

完整流程见 业务 SOP，文件和状态交接见 插件 SOP 与交互关系。

2.3 关键取舍

| 关键问题 | 判断依据 | 采用方案 | 替代方案及未采用原因 |
| --- | --- | --- | --- |
| Bot 是否直接给运营决策 | 当前数据只能支持描述分析，且最终决策还涉及政策、成本和用户权益 | 终点设为“决策前数据支撑” | 自动推荐会超出证据边界 |
| 一个还是多个插件 | 数据准备可复用，用户级分析权限和产物边界不同 | 拆为准备/描述插件与分析/可视化插件 | 单插件职责过重且难复用 |
| 如何避免错用不同批次文件 | 文件名不能证明内容一致 | 核对 CSV 实际哈希和两份上游清单哈希 | 仅按目录或时间匹配不可靠 |
| 用户标签如何解释 | 只有标签名无法审计 | 保留观察值、群体、阈值、样本量和规则版本 | 黑盒评分无法说明依据 |
| 入网日期如何使用 | 没有统一数据快照日期 | 只生成入网年份和批次 | 计算当前在网时长会引入错误基准 |
| 示例如何公开 | 真实报告含用户级数据和本机路径 | 使用完全模拟数据重新跑全流程，只提交聚合结果 | 直接上传真实结果存在隐私风险 |

3. 核心功能与交付

| 功能／交付 | 用户目标 | 输入 | 输出／决策支持 | 本人直接负责内容 | 验证证据 |
| --- | --- | --- | --- | --- | --- |
| 数据准备与质量门禁 | 获得字段稳定且有质量状态的数据 | XLSX/CSV、字段说明 | 标准化 CSV、字典、错误和警告 | 字段口径与状态验收 | 插件一测试 + 模拟数据 |
| 描述统计基线 | 理解样本、分布与可比条件 | 标准化 CSV | 质量、数值、分类、二元和分组统计 | 分析范围和输出边界确认 | 聚合示例报告 |
| 用户与群体分析 | 形成可追溯指标和标签 | CSV 与两份上游清单 | 标签证据、阈值、套餐/品牌/属地/批次画像 | 规则、样本门槛和决策边界确认 | 插件二测试 + 分析清单 |
| 可视化交付 | 让分析人员和决策者快速复核 | 分析清单和聚合 CSV | 5 类 PNG、HTML、Excel、透视式 CSV | 图表需求和中文显示验收 | 公开生成产物 |
| Bot 编排 | 减少调用顺序和路径交接错误 | 固定版本、profile 和提示词 | 四阶段对话流程和人工交接包 | SOP、提示词、版本和隐私规则 | 当前仓库 |

4. 成果与证据

4.1 关键结果

| 结果或观察 | 指标定义 | 数据来源 | 样本量／时间窗 | 基线／对照 | 证据等级 | 局限 |
| --- | --- | --- | --- | --- | --- | --- |
| 四阶段工具链按契约跑通 | 准备、描述、分析、可视化均生成约定状态与文件 | 完全模拟 CSV | N=10，2026.09 | 无 | 模拟数据验证 | 不能代表真实数据分布或生产性能 |
| 质量警告能够跨阶段保留 | 常量字段在准备阶段产生 warning，描述阶段保留质量状态 | 模拟 CSV 与清单 | N=10 | 人工可读取输入 | 模拟数据验证 | 只覆盖当前已实现的质量规则 |
| 分析产物可追溯 | 输入哈希、配置哈希和规则版本写入清单 | 公开清单 | 1 次完整运行 | 固定输入与配置 | 模拟数据验证 | 生成时间和环境信息可能变化 |
| 两插件自动化测试通过 | TypeScript 与 Python 测试通过数 | 两插件公开代码 | 57 个测试，2026.09 | 无 | 定向测试 | 单元/集成测试不等于生产验证 |
| 本地业务样本完成端到端运行 | 四阶段成功生成分析和可视化产物 | 不公开业务数据 | N=11,729，2026.09 | 无 | 定向测试 | 公开读者无法独立核验；不代表业务效果 |

这些结果证明流程具有可执行性和可追溯性，不证明其提升了迁转率、收入、留存或运营效率。

4.2 证据材料索引

| 材料 | 证明什么 | 访问方式 | 公开状态 |
| --- | --- | --- | --- |
| 模拟输入 | 字段结构与脱敏方式 | example/data/tariff_example.csv | 公开 |
| 描述统计报告 | 插件一的质量和聚合输出 | example/reports/descriptive/ | 公开 |
| 分析清单与聚合画像 | 插件二的哈希、规则和群体输出 | example/reports/analysis/ | 公开 |
| HTML 报告 | 图表和聚合表的组合交付 | visual_report.html | 公开 |
| Excel 汇总 | 多工作表分析交付 | analysis_summary.xlsx | 公开 |
| 自动化测试 | 插件行为边界 | 两个插件仓库的 tests/ 与 python/tests/ | 公开 |
| 业务 SOP 与提示词 | Bot 的调用和停止条件 | docs/ 与 prompts/ | 公开 |
| 本地业务验收 | 真实结构下的可运行性 | 原始数据与用户级结果不公开 | 不公开 |

4.3 公开示例图表

| 图表 | 访问 |
| --- | --- |
| 主要套餐用户数 | PNG |
| 品牌系列平均话费 | PNG |
| 用户属地用户数 | PNG |
| 入网批次用户数 | PNG |
| 标签覆盖用户数 | PNG |

5. 安装与复现

5.1 克隆组合仓库

git clone https://github.com/SUFE-Chaoyi/dsh-tariff-analysis-bot.git
cd dsh-tariff-analysis-bot

5.2 安装固定插件版本

dsh plugin --profile tariff-bot add \
github:SUFE-Chaoyi/dsh-plugin-csv-report#v0.2.0 \
github:SUFE-Chaoyi/dsh-plugin-tariff-analysis#v0.1.0

如果 pnpm 要求允许 Git 依赖执行 prepare，只在确认信任上述仓库和标签后，在 profile 的 pnpm-workspace.yaml 中加入：

allowBuilds:
dsh-plugin-csv-report: true
dsh-plugin-tariff-analysis: true

5.3 创建共享 Python 环境

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

两个插件都可以把 pythonPath 指向该环境。

5.4 配置 profile

1. 复制 config/cordis.example.yml 的内容到：

~/.dsh/profiles/tariff-bot/cordis.patch.yml

2. 把 /absolute/path/to/dsh-tariff-analysis-bot 替换为本仓库的真实绝对路径。
3. 为正式分析保留 minimumGroupSize: 30。
4. 仅复现 10 行示例时，可参考 config/cordis.demo.yml 使用 minimumGroupSize: 2。
5. 将示例文件复制到 .runtime/data/raw/，或把自己的授权数据放入该目录。

mkdir -p .runtime/data/raw .runtime/baseline-reports .runtime/analysis-reports
cp example/data/tariff_example.csv .runtime/data/raw/tariff_example.csv
dsh --profile tariff-bot --dump-config

5.5 在 DSH 中调用

推荐直接使用：

- 完整端到端分析提示词
- 数据准备与质量检查提示词
- 群体比较提示词

示例完整调用的第一个输入路径为：

raw/tariff_example.csv

6. 关键决策复盘

把项目终点设为“交付数据支撑”，而不是“自动做运营决定”

- 当时的选择：四个工具只生成数据、标签证据、群体画像和报告；最终步骤固定为人工复核与交接。
- 依据：当前是单期截面数据，没有实验、统一快照日期和完整业务约束。分位数、费用事实和群体差异不足以支持用户处置决定。
- 结果：工具描述、SOP、提示词、报告和 README 使用一致边界；任何 failed_quality、blocked 或无法解释的 warning 都有停止或复核路径。
- 复盘：即使未来增加预测模型，也应把模型分数、规则证据和人工决策分开记录，并通过额外评估证明适用性。

7. 局限与下一步

| 当前局限 | 对结论／产品的影响 | 当前约束 | 可执行的改善条件与下一步 |
| --- | --- | --- | --- |
| 单期截面数据 | 不能分析趋势、留存和运营效果 | 缺少连续快照 | 获得多期同口径数据后设计时间序列协议 |
| 无快照基准日 | 不计算当前在网时长 | 只有入网日期 | 上游明确提供分析基准日后增加口径 |
| 无权威品牌/套餐码表 | 编码和历史名称的业务解释有限 | 当前只保留原始值 | 增加版本化码表和未知编码告警 |
| 模拟示例规模小 | 只能展示流程与规则路径 | 公开边界优先 | 增加更丰富但完全合成的测试数据生成器 |
| 真实业务证据不公开 | 公开读者不能复核 N=11,729 的统计结果 | 隐私要求 | 继续以脱敏协议、测试和模拟证据替代 |
| 未做生产部署和压测 | 不能声明生产可用性和吞吐 | 当前为个人项目 | 建立脱敏性能基准、监控和部署说明 |

完整限制见 数据与分析限制。

8. 公开边界与隐私说明

- 已公开材料：两个插件源码、Bot SOP、提示词、配置、完全模拟输入、聚合报告、PNG、HTML 和 Excel。
- 脱敏处理：公开输入只使用 demo_* 用户标识、甲区至己区和带“演示”前缀的套餐名称。
- 不可公开材料：原始业务 Excel/CSV、真实用户标识、真实用户级指标和标签证据、未经脱敏的 DSH 对话截图。
- 替代证据：模拟数据端到端产物、自动化测试、哈希清单、规则文档和开发日志。
- 安全检查：.runtime/、.venv/、环境变量和日志均被 Git 忽略；公开清单不包含本机绝对路径。

9. 项目导航

dsh-tariff-analysis-bot/
├── README.md
├── docs/
│   ├── BUSINESS_SOP.zh-CN.md
│   ├── PLUGIN_INTERACTION.zh-CN.md
│   ├── DATA_LIMITATIONS.zh-CN.md
│   └── DEVELOPMENT_DIARY.zh-CN.md
├── config/
│   ├── cordis.example.yml
│   └── cordis.demo.yml
├── prompts/
│   ├── full-analysis.zh-CN.md
│   ├── quality-check.zh-CN.md
│   └── group-comparison.zh-CN.md
├── example/
│   ├── data/
│   ├── reports/
│   └── screenshots/
├── requirements.lock.txt
└── LICENSE

开发过程与问题修复见 Bot 集成仓库开发日志。

10. License

本组合仓库采用 MIT License。两个插件及 DeepSeek Harness 分别受各自仓库的许可证约束。