按决策难度匹配 Agent 介入方式 — 让数据分析师的业务经验从个人大脑中走出来，成为可复用、可追溯、越用越强的团队资产。
数据准备（探索分析、清洗、特征工程）占金融分析师 40–60% 的工作时间。团队虽然有代码模板能减少编码任务，但业务规则与领域判断等高价值经验仍然留在个人大脑中，难以共享复用，决策逻辑散落在各个 notebook 中难以回溯。
IDPA 把数据准备这个环节重新组织成一个"有决策能力 + 会学习"的 Agent，核心做三件事：
- 按决策难度分配介入方式 — 确定性规则由系统自动执行，需要判断的场景由 Agent 综合业务规则推荐方案，开放性问题在独立探索环境中人机协作
- 每次人工介入都在训练 Agent — 探索过程中的对话、代码与诊断结论，经人工确认后自动沉淀为可复用经验
- 所有处理步骤可追溯、可撤销 — 从原始数据到最终交付的每一步操作都有完整的 PARE 记录（Problem / Action / Result / Evidence）
IDPA 最核心的产品洞察是：Agent 产品的核心设计问题不是"AI 能做什么"，而是在每个环节 Agent 以何种角色参与、人承担什么职责。
按决策确定性把任务分成三类，每类匹配不同的 Agent 介入方式：
| 决策难度 | Agent 角色 | 人的角色 | 对应能力 |
|---|---|---|---|
| 确定性规则 | 执行者 — 自动处理 | 事前确认规则集 | L1 Rule Engine |
| 需要综合判断 | 提案者 — 带业务规则推荐方案 | 审查 / 修改 / 否决 | L2 LLM Reasoning |
| 开放性问题 | 助手 — 提供代码和假设 | 主导探索方向 | L4 Sandbox |
| 经验沉淀 | 提取者 — 从对话中总结 | 审核后入库 | Method 积累 |
实测 190 万行 CRSP 金融数据：约 85% 任务 Agent 自主完成，剩余 15% 的人工介入同时在训练 Agent。
IDPA 由五个相互配合的模块组成：
┌─────────────────────────────────────────────────────────┐
│ Task Context │
│ 目标 · 资源 · 规则 · 积累的经验 │
└─────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Scanner │ │ Planner │ │Validator │
│ 数据感知 │ ←→ │ LLM 决策 │ ←→ │ 三层校验 │
└──────────┘ └──────────┘ └──────────┘
│
▼
┌──────────┐
│ Executor │
│ 规则执行 │
└──────────┘
│
▼
┌──────────────────┐
│ State Manager │
│ 决策树 · 快照 · 回退 │
└──────────────────┘
- Scanner — 自动识别数据结构（面板/时序/截面）、列类型、质量问题
- Task Context — 四区块知识管理：任务目标、数据资源、领域规则、积累的经验
- Planner — LLM 驱动的决策大脑。推荐方案、接收人类 challenge、在沙盒中协作探索
- Executor — 按决策层级分工：L1 规则引擎、L2 LLM 策略、Custom（沙盒发现的自定义方法）
- Validator — 三层校验：操作层、阶段层、目标层
- State Manager — 决策树管理。支持非破坏性回退、分支对比、完整历史追溯
用 IDPA 处理 COVID 期间美股面板数据（190 万行 × 17 列），详见 docs/case-studies/crsp-190m.md。
流程概要：
Scanner 发现 13 个数据质量问题
↓
L1 Rules 自动处理 8 个确定性问题（inf → NaN、重复行、负 PERMNO 等）
↓
L2 Missing 5 层 MECE 分组识别出 6 个缺失模式
LLM 推荐 + 人工审查 5 个
Group 3 触发人工挑战 → 进入沙盒
↓
Sandbox 7 轮人机对话探索 ASK/BID 缺失的本质
发现可从 ASKHI/BIDLO 中间价推导
新方法 midprice_impute 进入 Method 库
↓
Outlier 识别异常值模式，推荐脱水策略
↓
Dehydration 极端值处理 + 对数变换（原始版与脱水版并存）
关键发现： 新方法 midprice_impute 是第一次运行时从人机对话中沉淀出来的。下次遇到类似缺失模式时，它会自动出现在候选策略列表里。这就是"每次人工介入都在训练 Agent"的具体机制。
idpa/
├── core/ # 共享数据结构（Operation, Snapshot, QualityScore）
├── scanner/ # 数据扫描器 — 感知层
├── task_context/ # 任务上下文 — 知识管理
├── state_manager/ # 状态管理 — 决策树 + 快照
├── executor/ # 执行器 — L1/L2/Custom
├── planner/ # 规划决策 — LLM 驱动
├── validator/ # 校验器 — 三层质检
└── helpers.py # Notebook 便捷工具
docs/
├── product/ # 产品设计文档
├── architecture/ # 架构文档
├── case-studies/ # 真实案例
├── versions/ # 设计文档迭代历史
└── guides/ # 使用指南
notebooks/ # 演示 notebook
- Python 3.10+
- pandas, numpy, scipy
- OpenAI-compatible LLM 客户端
git clone https://github.com/shuyul/intelligent-data-prep-agent.git
cd intelligent-data-prep-agent
pip install -e .export LLM_API_KEY="your-api-key"
export LLM_BASE_URL="https://api.anthropic.com/v1"
export LLM_MODEL="claude-sonnet-4-5"import pandas as pd
from idpa.scanner.scanner import DataScanner
from idpa.state_manager.manager import StateManager
from idpa.executor.executor import Executor
from idpa.executor.l1_rule_engine import L1RuleEngine, build_crsp_default_rules
from idpa.task_context.parser import build_crsp_context
from idpa.helpers import show_tree, show_node
# 加载数据
df = pd.read_csv("your_crsp_data.csv")
# Scanner 诊断
scanner = DataScanner()
scan_report = scanner.scan(df)
scanner.print_report(scan_report)
# 初始化 StateManager 和 TaskContext
sm = StateManager()
sm.init(df.copy(), id_col="PERMNO", time_col="date")
ctx = build_crsp_context(scan_report, df)
# L1 规则引擎
l1 = L1RuleEngine()
for rule in build_crsp_default_rules(id_col="PERMNO", time_col="date"):
l1.add_rule(rule)
executor = Executor(sm, l1)
executor.confirm_all_rules()
executor.run_l1()
# 查看决策树
show_tree(sm)
show_node(sm) # 展示当前节点的完整 PARE 记录更完整的示例见 notebooks/IDPA_Integrated_Pipeline.ipynb。
当前版本：v0.8（2026-03-28）
已实现：
- Scanner + Panel 结构检测
- L1 规则引擎（CRSP 默认规则 + 自定义规则）
- L2 Missing：5 层 MECE 分组 + 密度分布 +
drop_by_density策略 - L2 Outlier：诊断 + 策略推荐
- Planner 完整链路（challenge / sandbox / resolve / confirm）
- Executor SubOperation + 完整 PARE 记录聚合
run_custom— 沙盒发现的方案在主流程执行并记录- 三层 Validator（operation / side-effect / goal-alignment）
- 决策树可视化（
show_node,compare_nodes）
设计中（v0.9）：
- Method 库 + 信任升级机制（candidate → recommended → trusted → rule）
- Agent 心智模型（六大类 × 分型 × Method）
- Skill 层：基于 few-shot 案例的归纳演绎
路线图：
- TaskContext 多任务支持（OLS / Probit / K-means / PCA / DiD）
- Method PR 机制（用户贡献的方法流回主仓库）
- 多数据集 + 外部数据源支持
经过 v0.1 → v0.8 的迭代，以下原则被反复验证：
- 文档驱动开发 — 先写架构文档再编码
- 承诺先于功能 — 不在核心承诺未兑现的情况下增加新设计
- 用户视角驱动 — 作为"首位用户"亲自跑端到端测试
- 知识应该在知识库里，不在代码里 — 业务判断不应硬编码
- 分析师按实体思考，系统按行处理 — 系统需要同时支持两种视角
- 决策难度是动态的 — 同一个问题随着经验积累，决策层级会下降
- 产品 — 为什么需要 IDPA · 设计原则
- 架构 — 架构总览 · Method / Skill 设计
- 案例 — CRSP 190 万行
- 版本历史 — docs/versions/
欢迎以任何形式参与：
- Bug 报告 / 功能建议 — 通过 Issues
- 代码贡献 — 先读 CONTRIBUTING.md
- Method 贡献 — 如果你在使用 IDPA 过程中发现了新的数据处理方法，可以通过 PR 贡献到 Method 库
本项目采用 Apache 2.0 License。