dataset-onboarding-graph-preprocess

Files (5)

• SKILL.md
• router_card.json
• dataset_onboarding_graph_preprocess_wrapper.py · scripts/
• generate_sample_phone_raw_data.py · scripts/
• test_dataset_onboarding_graph_preprocess.sh · scripts/

SKILL.md (first lines)

# dataset-onboarding-graph-preprocess

## 1. 技能定位

`dataset-onboarding-graph-preprocess` 是电话网络数据分析体系中的“数据接入 / 预处理 / 建图”技能。

它负责把前端上传的原始 CSV、Excel、Parquet 或 JSON 表格转换为后续电话网络分析技能统一使用的图结构数据：

```text
processed/<dataset>/user_nodes.csv
processed/<dataset>/call_edges.csv
processed/graph_views/<dataset>/edges_phone_imei.parquet
```

只要新上传的数据被转换成上述结构，后续就可以继续调用 `dataset-overview-analysis`、`single-number-analysis`、`topn-high-risk-discovery`、`condition-based-screening`、`shared-device-analysis`、`group-risk-analysis`、`gang-cluster-analysis`、`risk-evidence-pack`、`time-series-anomaly-analysis` 等技能。

## 2. 必须使用本技能的场景

只要用户提出下面任意需求，就必须优先使用本技能：

- 上传了新的电话网络原始 CSV / Excel / JSON / Parquet，需要转换成项目统一图结构；
- 希望把原始通话记录、用户标签表、设备绑定表接入现有电话网络分析链路；
- 希望生成 `user_nodes.csv`、`call_edges.csv`、`edges_phone_imei.parquet`；
- 希望检查上传数据字段能否被识别；
- 希望处理“不规整数据”“中文字段”“坏时间”“重复行”“缺失值”；
- 希望处理错误数据，并说明为什么不能建图；
- 用户提到“建图、预处理、数据接入、上传数据、原始数据、转成标准图结构、无法建图、质量检查、字段映射”等关键词。

如果用户只是想分析已经预处理好的 `unified` 数据，不需要调用本技能，应直接调用对应分析技能。

## 3. 前端调用原则

前端使用时必须优先运行正式 wrapper，**不要临时重写脚本，不要手写替代脚本**。

标准脚本路径：

```text
/mnt/skills/custom/phone-network-analysis/dataset-onboarding-graph-preprocess/scripts/dataset_onboarding_graph_preprocess_wrapper.py
```

如果运行环境是项目 Docker，路径通常是：

```text
/workspace/imiss-deer-flow-main/skills/custom/phone-network-analysis/dataset-onboarding-graph-preprocess/scripts/dataset_onboarding_graph_preprocess_wrapper.py
```

如果前端上传文件后不知道路径，先在常见上传目录中查找：

```bash
find /mnt/user-data -maxdepth 6 \( -name "*.csv" -o -name "*.xlsx" -o -name "*.xls" -o -name "*.json" -o -name "*.parquet" \) 2>/dev/null | head -80
```

然后把**真实包含上传文件的目录**作为 `--input-dir`。常见前端上传目录可能是：

```text
/mnt/user-data/uploads/
/mnt/user-data/workspace/
/mnt/user-data/workspace/onboarding_input/
```

不要直接使用不存在的占位路径，例如 `/workspace/imiss-deer-flow-main/uploads/new_phone_dataset`，除非你已经手动把文件放到了这个目录。

## 4. 用户可见输出规范

- 面向用户的最终回答必须使用中文。
- 不要输出英文说明句，例如 “Run the script”、“Read report”、“Generated files”。
- 可以保留命令、文件名、参数名本身的英文，例如 `user_nodes.csv`、`artifact_mode=essential`。
- 不要在最终回答正文里连续粘贴同一份 Markdown 报告两遍。
- 下载入口由前端附件卡片展示即可，正文只需要简要说明“报告和标准图结构文件已生成”。
- 如果已经展示了完整 Markdown 报告正文，就不要再把同一份报告全文复制一次。
- 如果输入文件缺少号码字段，也要运行本技能生成质量诊断报告，不要回复“找不到 skill”。

## 5. 输入数据要求

本技能支持一个目录或多个文件。支持格式：

- `.csv`
- `.xlsx` / `.xls`
- `.parquet`
- `.json`

可以接受以下几类表：

1. 用户标签表：包含号码、标签、省份等字段。
2. 通话明细表：包含主叫、被叫、时间、时长、设备等字段。
3. 设备绑定表：包含号码和设备 ID。
4. 混合明细表：一张表里同时包含号码、对端、设备、时间、标签。
5. 错误或不完整表：脚本会尽量读取并输出质量诊断，不会直接让前端无结果。

注意：设备绑定表没有“对端列”、用户标签表没有“对端列/设备列”是正常情况。脚本会把这类情况记录为“角色说明”，不当作质量错误。

## 6. 字段自动识别

脚本会自动识别常见中英文字段名：

| 标准含义 | 常见字段名 |
|---|---|
| 号码 | phone、phone_number、mobile、msisdn、caller、src_user_id、subscriber、main_number、主叫、主叫号码、手机号、手机号码、号码、用户号码 |
| 对端 | callee、called、counterparty、dst_counterparty_id、peer、target、peer_number、被叫、被叫号码、对端、对端号码、联系人号码 |
| 设备 | imei、device_id、terminal、terminal_id、设备号、终端、终端号、meid、imsi |
| 时间 | event_time、call_time、timestamp、start_datetime、通话时间、呼叫时间、开始时间 |
| 日期 | event_date、date、call_date、通话日期 |
| 小时 | event_hour、hour、call_hour、小时、时段 |
| 时长 | duration、duration_sec、call_duration、seconds、通话时长、时长、秒数 |
| 标签 | label、is_risk、risk_label、标签、风险标签、是否风险 |
| 子标签 | sub_label、risk_type、子标签、风险类型、标签类型 |
| 省份 | province、省份、归属省、归属地省、归属地、area_province |

如果自动识别不准，必须通过命令行显式指定字段，例如：

```bash
--source-col caller --target-col callee --device-col imei --time-col call_time
```

## 7. 输出 schema

### user_nodes.csv

```text

From bettercallfan/deerflow, MIT.

More from bettercallfan/deerflow