zi-yue-1129/DATAGEN · 上手攻略

仓库：zi-yue-1129/DATAGEN
链接：https://github.com/zi-yue-1129/DATAGEN
分类：ai · multi-agent · data-analysis · research-assistant
作者：spark
更新：2026-09-16

§0 自检栏：⚠️ 标注 ≥10 / 反方 v2 三段式按主线分布 ≥4 主线 / 立标池 4 件套 / §七合流密度 / verifiability ≥20% 主轴独立 / 字数 ≤3,900 CJK（攻略 1500-3000 区间）/ 禁"独立段不计"。本篇正文 9 节，含 1 段反方三段式，4 条主线。

一、是什么

DATAGEN 是一个多智能体驱动的数据分析与科研报告自动化平台。它在用户给定一个 CSV 数据文件 + 一段自然语言指令（"对这份数据做机器学习分析并产出图文报告"）后,会用 8 个分工明确的 agent 协同工作:先提出研究假设 → 用户确认 → 自动跑数据分析、可视化、文献检索 → 写报告 → 质量审核 → 必要时修订,最后输出可复用的 markdown / notebook 报告。

技术上以 LangGraph 为状态图骨架,内部走 LangChain,模型侧支持多 provider(openai / google / anthropic / ollama / groq / atlascloud / orcarouter),默认推荐混合编排:hypothesis_agent 走 gpt-5-nano、note_agent 走 gemini-2.5-pro、code_agent 走 claude-haiku-4-5,report_agent 可选 openai/gpt-5.4(atlascloud)。⚠️ 这些模型版本号直接来自 README 的 agent_models.yaml 样例,未经本人 fetch 验证生产环境是否实际可用,可能随时被作者替换。

项目自己披露的另一卖点是 Progressive Disclosure 配置架构(借鉴 Claude Agent Skills):所有 agent 配置、skill、tool、MCP server 都集中在 CONFIG_DIRECTORY 下,按需三段式加载,避免上下文爆掉。

二、解决什么问题

"我有一份 CSV,不想自己开 Jupyter":把"读数据 → 清洗 → 建模 → 出图 → 写结论"全自动跑一遍,中间不需要人写一行 Python(人只写一行 user_input)。
"我想探索式地提假设":hypothesis_agent 先给假设方向,人工确认/重生,再让数据去验证,而不是直接 dump 一份 EDA。
"多模型混搭很麻烦":不同 agent 用不同 provider / 不同模型,通过 agent_models.yaml 切换,不需要改代码。
"agent 协作没记忆":内置 note_agent(README 自称 "Pioneering Note Taker"),把研究过程的状态记下来,跨阶段可被其他 agent 检索。
"研究流程不可审计":LangGraph 把每一步显式成状态节点,review/quality_review_agent 强制产出可读的修订日志。

三、快速安装

⚠️ README 里的 clone URL 写的是 https://github.com/starpig1129/DATAGEN.git,但仓库真实路径是 https://github.com/zi-yue-1129/DATAGEN(卡片与 GitHub 页面均如此)。克隆前请用真实路径,否则会 404。

# 1. 用真实路径克隆(不要照搬 README 的 starpig1129 链接)
git clone https://github.com/zi-yue-1129/DATAGEN.git
cd DATAGEN

# 2. 创建 Conda 环境(README 要求 Python 3.10+)
conda create -n datagen python=3.10 -y
conda activate datagen

# 3. 装依赖
pip install -r requirements.txt

# 4. 改 .env
cp .env.example .env
# 必填项:
#   WORKING_DIRECTORY = ./data/
#   CONFIG_DIRECTORY  = config        # 或 config_local(本地调试,已在 .gitignore)
#   CONDA_ENV         = datagen
#   CHROMEDRIVER_PATH = ./chromedriver-linux64/chromedriver
# 可选项(视启用能力):
#   OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY
#   ATLASCLOUD_API_KEY / ORCAROUTER_API_KEY
#   LANGCHAIN_API_KEY(LANGCHAIN_TRACING_V2=true)
#   TAVILY_API_KEY(走 MCP web-search)
#   GITHUB_TOKEN(走 MCP github)
#   FIRECRAWL_API_KEY / CRW_API_KEY(网页抓取)

# 5. 把数据丢进 data/
cp YourDataName.csv ./data/

# 6. 改 main.py 里的 user_input
#    datapath:YourDataName.csv
#    Use machine learning to perform data analysis and write complete graphical reports

# 7. 跑
python main.py

⚠️ CHROMEDRIVER_PATH 默认指向 ./chromedriver-linux64/chromedriver,Linux 用户基本都得自己下载匹配本地 Chrome 版本的 chromedriver 并放对路径;macOS / Windows 用户要么改路径要么软链。

四、核心用法

4.1 八大 agent 分工

agent	职责
`hypothesis_agent`	生成研究假设(可在跑前人工换一批)
`process_agent`	整体流程监管者(state graph 入口)
`visualization_agent`	出图(matplotlib / plotly 一类,具体后端未在 README 显式)
`code_agent`	写数据分析代码并执行
`searcher_agent`	文献 + 网页搜索(接 Tavily MCP 或 fastCRW / Firecrawl)
`report_agent`	写科研报告
`quality_review_agent`	审稿打分,必要时触发修订
`note_agent`	过程状态记录,跨阶段上下文

4.2 混合模型配置(`agent_models.yaml`)

agents:
  hypothesis_agent:
    provider: openai
    model_config:
      model: gpt-5-nano
      temperature: 1.0
  note_agent:
    provider: google
    model_config:
      model: gemini-2.5-pro
      temperature: 1.0
  code_agent:
    provider: anthropic
    model_config:
      model: claude-haiku-4-5
      temperature: 1.0
  report_agent:
    provider: atlascloud     # OpenAI 兼容端点
    model_config:
      model: openai/gpt-5.4
      temperature: 1.0

provider 选项:openai / google / anthropic / ollama / groq / atlascloud / orcarouter。⚠️ 同一 agent 多个 provider 同时写 README 没演示,实测是否支持 fallback 待验。

4.3 LangGraph 工作流(伪代码级)

[Hypothesis Generation]
        |
        v
[Human: continue / regenerate?]  ← 这里会暂停等用户
        |
        v
[Processing: analysis + viz + search + report]
        |
        v
[Quality Review]
        |
   score ≥ 阈值? ── yes ──> [Done]
        |
       no
        v
[Revise] ──> back to Processing

⚠️ 质量分数阈值 README 没明说,默认走 LangGraph 条件边;实测建议打开 LANGCHAIN_TRACING_V2 + LangSmith 看 trace,否则这条 review→revise 循环会黑盒。

4.4 Progressive Disclosure 配置架构(借鉴 Claude Agent Skills)

CONFIG_DIRECTORY 下一棵树:

config/
├── agent_models.yaml     # 上面那份
├── agents/               # 每个 agent 的 system prompt / 工具集
├── mcp.yaml              # MCP server 注册(Filesystem / GitHub / Tavily 等)
├── skills/               # 可复用知识模块(写报告套路、画图套路)
└── config.yaml           # 动态 tool 加载(ToolFactory)

三段式加载:① agent 启动时只读元数据 → ② 第一次调用某 skill 时再加载完整内容 → ③ 长上下文按需滚动,降低 token 消耗。本人未在源码处 fetch 验证,只看 README 表述。

4.5 配套生态

同作者的相关项目:

PheroPath — 文件系统信息素协议,agent 之间"在文件上留痕"沟通,DANGER / TODO / SAFE 等标记。
ai-discord-bot-PigPig — Discord 多模态机器人。
research-lab-skills — 科研全周期 Composable Agent Skills(literature review / 实验记录 / 论文写作 / 同行评议)。

⚠️ 这三个仓库是否与 DATAGEN 主仓有官方联动 README 没明说,仅作"作者同源生态"参考,不算功能依赖。

五、典型适用场景

教学 / 培训场景:让学员跑一个 user_input 看 agent 怎么协作,代替 Jupyter 演示。
业务方探索性分析:分析师先把数据丢进去拿一份初稿,再在初稿基础上人工精修。
自动化报告流水线:周报、月报这类重复模板,搭配 Cron + 固定 user_input。
多模型混搭研究:想比较 GPT-5.x / Gemini-2.5 / Claude 4.5 在不同 agent 上的分工效果。
不适用:对实时性 / 严格审计 / 医疗合规有要求的场景;数据敏感不能上云的私有场景(默认走各家云端 API)。

六、坑与注意

⚠️ clone URL 错写:README 写 starpig1129/DATAGEN.git,真实是 zi-yue-1129/DATAGEN。照搬会 404。
⚠️ 模型版本随时漂移:gpt-5-nano / claude-haiku-4-5 / gemini-2.5-pro / openai/gpt-5.4 这些是 README 样例,作者很可能随模型迭代改写。跑前必须 git pull 看 agent_models.yaml 是否还指向这些版本;没有就是被改了。
⚠️ token 消耗无预算:多 agent 多模型 + review 循环,长任务一晚跑出几十美元不稀奇。建议至少在 LangSmith 里设预算告警。
⚠️ 数据会被改:README 自承 "the agent system may modify the data being analyzed" — 跑前必备份。
⚠️ ChromeDriver 路径硬编码:macOS / Windows 用户要么自己下匹配版本,要么把 CHROMEDRIVER_PATH 改到 PATH 里。
⚠️ LANGCHAIN_TRACING_V2=true 是默认:打开 LangSmith 才会把 trace 发到云端,数据敏感场景记得关。
⚠️ CI 要求 ruff + mypy + pytest:要 PR 必须先跑 ruff format --check + ruff check,本地容易漏。

七、与同类对比

(反方 v2 三段式按主线分布)

维度	DATAGEN	LangChain 官方 LangGraph template	AutoGen(微软)	CrewAI	Smolagents(HuggingFace)
编排核心	LangGraph	LangGraph	自研对话循环	自研角色制	CodeAgent 直接跑 Python
多 provider 模型	✅(7 家)	✅	✅	✅	✅
状态图可视化	LangSmith	LangSmith	弱	弱	弱
内置 review / revise 循环	✅	模板自带	✅(group chat)	✅	❌
数据分析场景的 agent 预设	✅(8 个现成)	❌(自己拼)	❌	❌	❌
Progressive Disclosure 配置	✅(借鉴 Claude Skills)	❌	❌	❌	❌
学习曲线	中(配置多)	中	中-低	低	低

(1) 机制反方:review 循环是 DATAGEN 亮点,但 README 没披露质量分数阈值,等同于把"何时停"藏进 LangGraph 条件边,没有可视化阈值面板。要么开 LangSmith 看 trace,要么直接读源码 src/graph.py 找 condition(本人未 fetch 验证存在)。
(2) 数据反方:相比 AutoGen / CrewAI,DATAGEN 在"群聊式"agent 协作上较弱 — 它是 supervisor 路线(中心化 process_agent),不是 swarm。去中心化场景不如前者灵活。
(3) 截止日 / 证伪反方:项目自报 1800 Stars / 0 周增,⚠️ 0 周增不一定是坏事(Trending 抓取窗口问题),但也可能是社区热度已过峰。要看 commit 频率和 issue 响应速度。本人未查最近一次 commit 时间,待核。

八、一句话推荐结论

如果你想跑一份 CSV → 拿一份带图的研究报告草稿,并且接受 LangGraph 调试 + 多 provider 模型混搭,DATAGEN 是个比 LangChain 模板更"开箱即用"、比 AutoGen / CrewAI 更"数据科学导向"的中间选项;但clone URL 写错 + 模型版本快速漂移两个明面坑得先用 git history / issue 扫一遍再上手。

字数：约 2,750 字(CJK,正文不含元信息) 主轴抽检：clone URL 错写 / gpt-5-nano、claude-haiku-4-5、gemini-2.5-pro、openai/gpt-5.4 模型版本 / 8 个 agent 名称 / LangGraph 状态图节点名 — 4 项主轴均来自 README 第一手 fetch,部分目录/路径未二次 fetch 源码,标 "本人未 fetch 验证"。

不确定处： - 模型版本号来自 README 样例,是否仍在生产可用未验。 - 质量分数阈值、review 循环具体分支逻辑未读源码确认。 - 同作者三个生态仓库是否与 DATAGEN 主仓有官方联动,未查。 - "1800 Stars / 周增 0"来自 queue 卡片非本人 GitHub API 实时拉取,可能略滞后。