之前在业务迭代中做数据分析最耗时的往往不是写 SQL也不是画图而是反复对齐口径、调试清洗逻辑、改报告。团队里每个人处理数据的方式都不一样产出的结果经常对不上。后来我把 DeepSeek V4 接入 Codex用提示词驱动一个数据分析 Agent 完成了 300 万行数据的清洗、聚合、可视化和报告生成整个过程经历了 40 轮提示词迭代最终数据和报告都能追溯到每一步操作后续复盘和汇报都轻松了很多。这篇文章会把整套方案完整拆开从 Codex 接入 DeepSeek V4 的配置方式到数据分析 Agent 的提示词设计再到 300 万行数据的实战代码和报告迭代机制。无论你是想给简历加一个能打的 AI Agent 项目还是想真正提升数据分析交付效率都可以照着做一遍。需要说明的是AI 编程工具和大模型版本迭代很快文中的配置项和模型名称请以你实际使用的版本为准。我会把工程思路和排错方法写清楚这部分比具体某个参数更有复用价值。1. 背景与核心概念1.1 这个项目要解决什么问题传统数据分析项目的交付链路通常是这样的业务方提需求。数据分析师从数据仓库取数。写 SQL 或 Python 做清洗和聚合。用图表展示结论。写一份几十页的报告。这条链路最大的问题是每一步都可能产生信息损耗。业务方说的“活跃用户”和数据分析师理解的“活跃用户”可能不是同一个口径清洗逻辑改了之后之前的图表和结论却没有同步更新报告是人工攒出来的原始数据、中间表、最终结论之间的对应关系很难追溯。我这次要做的就是把这个链路交给 AI Agent让 Codex 作为执行体DeepSeek V4 作为推理大脑通过 40 轮提示词把需求逐步拆解成可执行的数据分析任务并且每轮任务都记录输入、输出和处理逻辑。这样最终报告里的每一个数字都能回答“这个数是怎么算出来的”。1.2 Codex 和 DeepSeek V4 各自扮演什么角色先澄清一下这两个概念。Codex 是 OpenAI 推出的命令行编程工具它能够在终端里读取项目代码、执行命令、修改文件相当于把大模型接入了真实的开发环境。Codex 的特点是“会动手”而不只是“会聊天”。你可以让它写脚本、跑测试、修复报错甚至完成跨文件的代码重构。DeepSeek V4 是大语言模型。它擅长理解复杂指令、生成代码、分析数据和总结结论。在本文的架构里DeepSeek V4 负责理解提示词、生成数据处理代码、解释分析结果。两者组合起来的逻辑是Codex 提供“手”操作文件、执行命令、自动运行脚本。DeepSeek V4 提供“脑”理解任务、生成代码、给出分析结论。数据分析 Agent 是二者的统称它接受目标描述自主规划步骤产出可追溯的结果。需要特别说明的是Codex 默认连接的是 OpenAI 自己的模型但 Codex 在设计上允许通过配置文件接入第三方模型接口。本文要做的就是把 Codex 的模型后端切换到 DeepSeek V4 的接口上。1.3 适合哪些读者这篇文章适合三类人数据分析师想用 AI Agent 减少取数和清洗的重复劳动提升报告交付效率。后端或全栈开发者想了解 Codex 如何接入第三方模型以及如何设计一个可运行的 Agent 项目。准备求职跳槽的工程师需要一个完整、有量化指标、能讲清楚技术难点的 AI Agent 项目经验。如果你只是想要一个“自动写 SQL 的工具”本文的方案也能覆盖但真正有价值的是后面的提示词迭代机制和数据追溯设计。2. 环境准备与版本说明2.1 运行环境本文示例是在 Linux 服务器上完成的macOS 也完全兼容Windows 建议使用 WSL 2 或 Git Bash 保证命令行为一致。核心环境如下操作系统Ubuntu 22.04 / macOS 13Python3.10 及以上Node.jsCodex CLI 依赖 Node.js 环境建议 18 以上包管理器npm 或 HomebrewGit用于版本管理和报告追溯版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。2.2 安装 Codex CLI安装 Codex CLI 最常用的方式是通过 npm 全局安装# 使用 npm 安装 npm install -g openai/codex # 检查是否安装成功 codex --version如果使用 macOS 且已经安装了 Homebrew也可以尝试brew install codex安装完成后需要确认codex命令在 PATH 环境变量中。部分桌面版 Codex 工具会在安装后提供一个codex-cli可执行文件此时需要手动设置CODEX_CLI_PATH指向它。如果启动时报错unable to locate the codex cli binary基本就是 PATH 或 CODEX_CLI_PATH 没配置好。2.3 安装 Python 依赖数据分析部分需要以下 Python 库pandas2.0 duckdb0.9 matplotlib3.7 jinja23.1 numpy1.24创建虚拟环境并安装python -m venv .venv source .venv/bin/activate pip install -r requirements.txt这里推荐使用 DuckDB而不是纯 pandas 来处理 300 万行数据。原因后面会讲简单来说就是 DuckDB 能直接在 CSV 上跑 SQL内存占用更低速度也更快。2.4 项目目录结构整个项目建议按照下面的结构组织data-analysis-agent/ ├── .env # 环境变量存放 API Key ├── codex_config.toml # Codex 配置文件 ├── prompts/ │ ├── system_prompt.md # 系统提示词 │ └── tasks/ │ ├── round_01_explore.md │ ├── round_02_clean.md │ └── ... ├── scripts/ │ ├── generate_data.py # 模拟数据生成 │ ├── explore.py # 数据探查 │ ├── clean.py # 数据清洗 │ ├── analyze.py # 聚合分析 │ ├── visualize.py # 可视化 │ └── report.py # 报告生成 ├── audit/ # 审计日志 ├── report/ # 输出报告 │ └── charts/ # 图表 └── data/ └── orders.csv # 输入数据这个结构的好处是提示词、脚本、报告、审计日志彼此分离任何一步出现问题时都能快速定位。3. Codex 接入 DeepSeek V4 配置3.1 理解 Codex 的模型接入机制Codex 默认使用 OpenAI 的模型接口但它支持通过model_providers配置自定义模型服务商。接入 DeepSeek V4 的本质就是告诉 Codex模型请求发到哪个地址。使用哪个 API Key。默认使用哪个模型名称。这一步在网上资料比较少而且不同版本的 Codex 配置字段会有差异。下面给出一个比较通用的配置方式如果你安装的版本字段变了请以官方文档为准。3.2 编写 Codex 配置文件在用户根目录下创建 Codex 配置文件。CLI 版通常在~/.codex/config.toml桌面版可能在~/.codex/config.json具体取决于安装方式。本文以config.toml为例# 文件路径~/.codex/config.toml model deepseek-v4 model_providers { deepseek { name DeepSeek V4 base_url ${DEEPSEEK_BASE_URL}/v1 env_key DEEPSEEK_API_KEY } } model_provider deepseek简单解释几个关键配置项model对话默认使用的模型名称这里填 DeepSeek V4 对应的模型标识。model_providers定义自定义模型服务商。base_url模型接口地址。${DEEPSEEK_BASE_URL}表示从环境变量读取避免把地址写死在配置文件里。env_key指定从哪个环境变量读取 API Key。model_provider指定默认使用哪个服务商。然后在当前 shell 中设置环境变量export DEEPSEEK_BASE_URLhttps://your-deepseek-api-endpoint export DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxxxxxxbase_url的地址需要根据你自己的 API 服务商实际情况填写不同平台的路径规则可能不同。建议把这两个环境变量写入项目的.env文件并在启动前加载# 文件路径.env DEEPSEEK_BASE_URLhttps://your-deepseek-api-endpoint DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxxxxxx3.3 验证接入是否成功配置完成后在终端里执行一条最简单的 Codex 指令来验证codex exec 用中文回答11 等于几如果返回结果是“2”说明 Codex 已经成功通过 DeepSeek V4 模型响应。如果报错常见错误和解决办法在本文第 7 章会专门整理。这里有一个容易踩的坑DeepSeek 不同子模型的名称不同比如有的版本叫deepseek-v4有的版本叫deepseek-v4-pro还有面向多模态的deepseek-v4-flash-vision-exp。如果请求时报there is an issue with the selected model大概率是模型名称在接口里不存在需要去服务商平台确认准确名称或者查看日志里的model字段是否被正确传递。4. 数据分析 Agent 的提示词工程设计4.1 系统提示词先把规矩定好做数据分析 Agent 最容易翻车的点是模型自由发挥、口径混乱。比如你说“分析一下用户增长”它可能一会儿用“注册用户数”一会儿用“活跃用户数”最后报告里数字前后对不上。解决办法是在系统提示词里把规则写死让每一轮任务都在同一套规则下运行。下面是我使用的系统提示词模板# 文件路径prompts/system_prompt.md 你是资深数据分析工程师负责在终端中完成数据分析任务。 工作规则 1. 所有数据处理步骤必须记录输入、处理逻辑、输出记录到 audit/ 目录。 2. 涉及聚合、过滤、去重操作前必须先描述数据口径确认后再执行。 3. 数据口径定义 - 活跃用户近 30 天内至少下单 1 次的用户。 - GMV订单金额总和不含退款订单。 - 客单价GMV / 有效订单数。 4. 每个分析结论必须有代码执行结果支撑禁止猜测和估算。 5. 图表输出到 report/charts/报告输出到 report/文件名带日期。 6. 如果用户指令不明确先列出假设条件再开始执行。 7. 涉及删除数据或覆盖文件时先备份。这七条规则分别解决了数据分析中最常见的几类问题规则 1 保证可追溯。规则 3 统一口径。规则 4 防止模型“一本正经地胡说八道”。规则 7 保护生产数据安全。4.2 40 轮提示词把大任务拆成可执行单元项目标题里提到的“40 轮提示词”并不是一开始就规划好了 40 条而是在执行过程中逐步迭代出来的。大致分成六个阶段阶段轮次目标典型任务环境确认1-5确认数据和环境可用检查数据文件、Python 环境、依赖库数据探查6-10理解数据结构和质量字段类型、缺失值、重复值、分布情况口径确认11-15和“需求方”对齐口径明确筛选条件、聚合维度、指标定义数据清洗16-25产出可分析的干净数据去重、类型转换、异常值处理聚合分析26-32计算核心指标按渠道、按月聚合 GMV、订单量可视化与报告33-40输出可读的报告生成图表、撰写结论、补充建议这个拆解方式的好处是每一步的输入输出都很清晰即使中间某一步错了只需要回退到对应轮次重新执行而不需要推翻整份报告。4.3 每轮提示词的写法每轮提示词我都遵循同一个结构上下文 任务目标 输出要求 验收标准。举个例子第 1 轮的提示词如下# 文件路径prompts/tasks/round_01_explore.md 当前处于“环境确认”阶段前序任务已完成数据文件部署。 任务目标 查看 data/orders.csv 的字段结构确认数据可被正常读取。 输出要求 1. 打印前 5 行数据。 2. 输出字段名、字段类型、数据量。 3. 将结果记录到 audit/round_01.jsonl。 验收标准 - 数据能够被 pandas 或 DuckDB 成功读取。 - 记录字段结构供后续任务使用。这种写法让模型有明确的边界它知道自己在哪个阶段、要做什么、产出什么、怎么验证。40 轮迭代的核心不是每轮都生成新代码而是让每一轮的结果成为下一轮的输入像流水线一样推进。4.4 上下文管理和记忆大模型的上下文窗口是有限的。40 轮迭代如果每一轮都把全部历史对话塞进去后面肯定放不下。我的做法是每轮只保留当前任务提示词和最近 1-2 轮的结果。关键中间结果写入data/目录下的文件通过文件路径传递。数据口径和规则始终写在系统提示词里不依赖对话记忆。这样设计的好处是即使中途断线重来Agent 只需要读取最新的中间文件和审计日志就能恢复上下文。这也是“数据可追溯”在工程上的具体落地方式。5. 300 万行数据分析 Agent 实战5.1 准备模拟数据为了演示完整流程我先生成 300 万行订单数据。实际业务中你可以换成从数仓导出的真实数据代码逻辑是一样的。# 文件路径scripts/generate_data.py import pandas as pd import numpy as np np.random.seed(42) n 3_000_000 df pd.DataFrame({ order_id: range(1, n 1), user_id: np.random.randint(10000, 99999, n), order_date: pd.date_range(2023-01-01, periodsn, freqmin), channel: np.random.choice( [APP, Web, MiniProgram], n, p[0.5, 0.3, 0.2] ), amount: np.round(np.random.lognormal(mean4, sigma1, sizen), 2), status: np.random.choice( [completed, refunded, pending], n, p[0.95, 0.03, 0.02] ) }) df.to_csv(data/orders.csv, indexFalse) print(生成完成数据量, len(df))运行python scripts/generate_data.py这里有两点需要注意300 万行数据用freqmin生成时时间跨度大约覆盖 5.7 年符合“近 30 天活跃用户”这种口径的判断。amount使用对数正态分布更接近真实订单金额的右偏分布。5.2 数据探查脚本拿到数据后先用 DuckDB 快速探查数据而不是直接用 pandas 读入内存。DuckDB 可以直接在 CSV 文件上跑 SQL读取 300 万行数据只需要几秒钟。# 文件路径scripts/explore.py import duckdb con duckdb.connect(data/analysis.db) # 查看字段结构 print( 字段结构 ) print(con.execute(DESCRIBE SELECT * FROM read_csv_auto(data/orders.csv)).df()) # 查看整体数据量 print(\n 数据量 ) print(con.execute( SELECT COUNT(*) AS total_cnt, COUNT(DISTINCT user_id) AS user_cnt, COUNT(DISTINCT channel) AS channel_cnt FROM read_csv_auto(data/orders.csv) ).df()) # 查看缺失值 print(\n 缺失值统计 ) print(con.execute( SELECT COUNT(*) AS total, COUNT(order_id) AS order_id_cnt, COUNT(user_id) AS user_id_cnt, COUNT(order_date) AS order_date_cnt, COUNT(channel) AS channel_cnt, COUNT(amount) AS amount_cnt FROM read_csv_auto(data/orders.csv) ).df())DuckDB 的read_csv_auto会自动推断字段类型省去了手工指定 schema 的步骤。探查结果建议保存到data/explore_result.csv后续分析直接引用。5.3 数据清洗与口径落地清洗是数据分析里最容易出错、也最需要“可追溯”的环节。下面这段代码展示了如何用 DuckDB 完成一次基于口径的清洗# 文件路径scripts/clean.py import duckdb con duckdb.connect(data/analysis.db) # 口径 # 1. 仅保留 completed 状态的订单 # 2. 剔除 amount 0 的异常订单 # 3. 去除重复 order_id # 4. 生成唯一主键便于追溯 cleaned_sql CREATE OR REPLACE TABLE cleaned_orders AS SELECT order_id, user_id, order_date, channel, amount, completed AS valid_status, CURRENT_TIMESTAMP AS processed_at FROM ( SELECT *, ROW_NUMBER() OVER ( PARTITION BY order_id ORDER BY order_date DESC ) AS rn FROM read_csv_auto(data/orders.csv) WHERE status completed AND amount 0 ) WHERE rn 1 con.execute(cleaned_sql) print(清洗后数据量, con.execute(SELECT COUNT(*) FROM cleaned_orders).fetchone()[0]) print(订单金额统计) print(con.execute( SELECT MIN(amount) AS min_amt, MAX(amount) AS max_amt, AVG(amount) AS avg_amt FROM cleaned_orders ).df())这段代码里比较关键的是ROW_NUMBER() OVER (PARTITION BY order_id ...)窗口函数。它的作用是如果同一个订单 ID 出现多次只保留最新的一条这就处理了重复数据问题。而且整个清洗过程的所有规则都写在了 SQL 里任何人看到这段代码都能还原“干净数据是怎么来的”。清洗完成后建议把结果导出成中间表con.execute(COPY cleaned_orders TO data/cleaned_orders.csv (HEADER, DELIMITER ,))中间表的存在非常重要后续分析不会反复读取原始 CSV而是基于这份清洗后的数据。哪一步出了问题只需要对比原始表和清洗后的中间表就能定位。5.4 聚合分析与可视化数据处理完成后开始计算核心指标。这里以“月维度、渠道维度的 GMV 和客单价”为例# 文件路径scripts/analyze.py import duckdb con duckdb.connect(data/analysis.db) # 月度、渠道维度的核心指标 result con.execute( SELECT channel, DATE_TRUNC(month, order_date::DATE) AS month, COUNT(*) AS order_cnt, COUNT(DISTINCT user_id) AS user_cnt, SUM(amount) AS gmv, AVG(amount) AS avg_amount FROM cleaned_orders GROUP BY 1, 2 ORDER BY 2, 1 ).df() result.to_csv(data/monthly_channel_metrics.csv, indexFalse) print(result.head(10))拿到聚合结果后用 matplotlib 生成可视化图表# 文件路径scripts/visualize.py import pandas as pd import matplotlib.pyplot as plt # 设置中文字体避免图表乱码 plt.rcParams[font.sans-serif] [SimHei, Arial Unicode MS, DejaVu Sans] plt.rcParams[axes.unicode_minus] False df pd.read_csv(data/monthly_channel_metrics.csv) df[month] pd.to_datetime(df[month]) # 各渠道月度 GMV 趋势 pivot df.pivot(indexmonth, columnschannel, valuesgmv) pivot.plot(figsize(12, 6)) plt.title(各渠道月度 GMV 趋势) plt.xlabel(月份) plt.ylabel(GMV) plt.grid(True, linestyle--, alpha0.5) plt.tight_layout() plt.savefig(report/charts/gmv_trend.png, dpi150) print(图表已保存report/charts/gmv_trend.png)300 万行数据经过聚合之后画图用到的数据量已经非常小此时可以直接用 pandas matplotlib性能完全够用。5.5 自动化报告生成报告生成采用 Jinja2 模板好处是代码、数据和报告内容分离。分析结论变化时只需要重新渲染模板不需要手工改报告。# 文件路径scripts/report.py import pandas as pd from datetime import date from jinja2 import Template df pd.read_csv(data/monthly_channel_metrics.csv) # 计算汇总指标 total_gmv df[gmv].sum() total_orders df[order_cnt].sum() avg_amount total_gmv / total_orders channels df.groupby(channel)[gmv].sum().sort_values(ascendingFalse) template_text # 电商订单数据分析报告自动生成 生成日期{{ today }} ## 1. 核心指标 | 指标 | 数值 | | --- | --- | | 总 GMV | {{ total_gmv | round(2) }} | | 总订单量 | {{ total_orders }} | | 客单价 | {{ avg_amount | round(2) }} | ## 2. 渠道 GMV 占比 {% for channel, gmv in channels.items() %} - {{ channel }}{{ gmv | round(2) }} {% endfor %} ## 3. 结论 - 月度 GMV 趋势图见 charts/gmv_trend.png。 - 各渠道贡献排名稳定APP 渠道为主要营收来源。 - 本报告所有指标均可通过 data/monthly_channel_metrics.csv 复算。 template Template(template_text) report template.render( todaydate.today().isoformat(), total_gmvtotal_gmv, total_orderstotal_orders, avg_amountavg_amount, channelschannels ) with open(report/analysis_report.md, w, encodingutf-8) as f: f.write(report) print(报告已生成report/analysis_report.md)运行后report/analysis_report.md会自动生成包含日期、核心指标、渠道占比和图表路径的报告。由于报告是基于模板渲染的每次数据更新后重跑脚本就能得到最新版本。5.6 运行整个流程把所有脚本串起来用一行命令完成整个分析链路python scripts/generate_data.py \ python scripts/explore.py \ python scripts/clean.py \ python scripts/analyze.py \ python scripts/visualize.py \ python scripts/report.py这个流程跑通之后就可以让 Codex 接管了。把上面每一步作为一个提示词任务交给 Codex 执行它会根据当前项目结构自动调用对应脚本并在报错时尝试修复。这就是“数据分析 Agent”和普通脚本最大的区别普通脚本报错就停了Agent 会读日志、改代码、重新执行直到跑通。6. 数据可追溯与报告迭代6.1 审计日志让每一步都有据可查“数据可追溯”是这个项目最核心的工程点。我采用的方案是在系统提示词里硬性要求 Agent 将每一步处理写入审计日志。# 文件路径scripts/audit.py import json from datetime import datetime class AuditLogger: def __init__(self, log_pathaudit/audit_log.jsonl): self.log_path log_path def record(self, step, operation, input_path, output_path, paramsNone): entry { time: datetime.now().isoformat(), step: step, operation: operation, input: input_path, output: output_path, params: params or {} } with open(self.log_path, a, encodingutf-8) as f: f.write(json.dumps(entry, ensure_asciiFalse) \n) # 示例记录一次清洗过程 if __name__ __main__: logger AuditLogger() logger.record( stepdata_clean, operationfilter_and_dedup, input_pathdata/orders.csv, output_pathdata/cleaned_orders.csv, params{status: completed, amount: 0} ) print(审计日志已写入audit/audit_log.jsonl)审计日志使用 JSON Lines 格式每一行是一条独立的记录。这种格式的好处是可以不断追加写入也方便后续用grep或 Python 按步骤筛选。6.2 报告版本管理分析报告不是一次就能定稿的。第 33-40 轮提示词就是在反复修改报告补充图表、修正结论、调整排版。为了让这个迭代过程可管理我采用了两条规则报告文件名必须带版本号analysis_report_v1.md、analysis_report_v2.md。整个report/目录用 Git 管理每次修改提交一次。git init git add report/ audit/ scripts/ git commit -m feat: 完成第一版分析报告当第 40 轮结束你可以在 Git 历史里清楚看到报告从 v1 到 v8 的完整演进过程。这种习惯在真实业务场景里非常有用业务方说“还是觉得上一版好”你只需要git checkout到对应版本即可。6.3 让 Agent 基于反馈迭代报告报告迭代的提示词也有固定套路下面是一个示例# 文件路径prompts/tasks/round_35_refine_report.md 当前状态 - 第 34 轮已完成报告 v1文件位于 report/analysis_report_v1.md。 - 业务方反馈 1. 渠道占比希望用饼图展示。 2. 补充月度环比增长率。 3. 结论部分需要更口语化。 任务目标 针对反馈修改分析流程和报告生成 v2 版本。 输出要求 1. 新增环比增长率计算。 2. 新增渠道占比饼图。 3. 更新报告内容并保存为 report/analysis_report_v2.md。 4. 将修改内容记录到 audit/audit_log.jsonl。 验收标准 - 报告 v2 中包含新增图表和指标。 - 新指标可以从聚合结果中复算。这种“反馈-修改-验证-出新版本”的循环是 40 轮提示词能够产出高质量报告的核心原因。每一轮都有明确目标和验收标准模型不会漫无目的地“自由发挥”。7. 常见问题与排查思路实战过程中我踩过不少坑。下面把高频问题整理成表格方便检索。问题现象常见原因解决思路unable to locate the codex cli binaryCodex 不在 PATH 中或桌面版未指定 CLI 路径将 codex 加入 PATH或在环境变量中设置CODEX_CLI_PATH指向可执行文件there is an issue with the selected model模型名称填写错误或接口不支持该模型去模型服务商平台确认准确的模型标识检查配置中的model字段the agent execution provider did not respond in time请求超时、接口限流或网络波动降低并发请求增加超时重试检查代码中是否存在死循环读取 CSV 时内存不足一次性把 300 万行数据载入 pandas改用 DuckDB 或 pandas 分块读取先用采样数据探查报告中文字体乱码matplotlib 未配置中文字体设置plt.rcParams[font.sans-serif]或指定系统中文字体图表日期显示为时间戳日期列未被正确解析为 datetime使用pd.to_datetime()显式转换后再绘图每次跑脚本结果不一致随机种子未固定或清洗逻辑未排序固定random_state去重逻辑增加排序条件其中比较难排查的是“模型请求超时”问题。Codex 在调用外部模型时如果单次请求等待时间太长会直接报超时错误并不一定代表模型接口本身不可用。遇到这类问题建议先做一次简单的连通性测试curl -X POST ${DEEPSEEK_BASE_URL}/v1/chat/completions \ -H Authorization: Bearer ${DEEPSEEK_API_KEY} \ -H Content-Type: application/json \ -d {model: deepseek-v4, messages: [{role: user, content: ping}]}如果 curl 能返回结果说明网络和接口都正常问题大概率出在 Codex 的超时配置或模型名称上如果 curl 本身超时就需要检查网络和服务商状态了。另一个容易忽略的问题是数据清洗逻辑的顺序。比如先过滤status completed再去除重复和先去重再过滤最终的数据量可能会不一样。因此审计日志里必须记录每一步的先后顺序。这也是为什么我在系统提示词里要求“涉及聚合、过滤、去重操作前必须先描述数据口径”。8. 最佳实践与工程建议8.1 密钥与安全整个项目涉及 API Key 和大量数据安全底线必须遵守密钥不写进代码或配置文件统一使用环境变量或者加载.env文件。.env文件加入.gitignore防止误提交到代码仓库。演示数据使用模拟数据如果是真实业务数据则需要先脱敏并明确数据使用范围。删除或覆盖数据文件之前先备份原文件避免误操作导致数据丢失。8.2 让 Agent 更稳定的小技巧为了让 Codex 在 40 轮长任务中保持稳定有几点经验很实用每一轮任务的提示词尽量短小、聚焦一次只解决一个目标。给每一轮设置“验收标准”让模型知道什么时候算完成。中间数据全部落盘成文件不要只保存在内存里。这样 Agent 重启后也能恢复进度。如果某一轮任务执行结果异常直接让 Codex 读取审计日志和该轮提示词重新执行即可不需要从头再来。8.3 性能优化的常见策略针对 300 万行甚至更大的数据量性能优化可以从三个方向入手用 DuckDB 代替纯 pandas 做聚合。DuckDB 的 SQL 引擎对大数据量更友好代码也更简洁。大表处理时优先使用 SQL 的 WHERE 条件提前过滤而不是先读全量数据再在内存里过滤。可视化阶段只读取聚合后的结果不要用原始明细数据画图。8.4 如何把这个项目写进简历如果目标是拿这个项目面试建议按“项目背景-技术方案-量化结果-核心难点”的结构来写数据分析 Agent 项目使用 Codex CLI 接入 DeepSeek V4 模型通过 40 轮提示词迭代构建数据分析 Agent完成 300 万行订单数据的清洗、聚合、可视化与报告生成。技术栈Python、DuckDB、pandas、Jinja2、Codex CLI、DeepSeek V4。项目成果报告生成时间从人工 2 天缩短至 30 分钟所有数据指标可在 audit/ 审计日志中追溯报告支持版本迭代可快速回滚。核心难点多轮任务上下文管理、数据口径统一、长任务稳定性、大数据量下内存优化。面试时重点讲清楚“数据可追溯”的实现方案也就是审计日志、中间表、Git 版本管理这三层机制。这套设计比单纯“用 AI 写代码”更有工程价值。9. 总结与下一步建议整个项目跑通之后我最大的感受是AI Agent 真正的价值不在于替你写多少行代码而在于把数据分析过程变成一个可拆解、可迭代、可追溯的工程流程。DeepSeek V4 负责理解任务和生成代码Codex 负责在真实环境里执行和调试而提示词工程决定整个过程的上限。如果你准备动手实践我的建议是先不要追求 40 轮一步到位而是从 10 轮开始把系统提示词、审计日志、报告模板这三块基础能力搭好。跑通第一条链路之后再逐步增加指标维度、图表类型和报告章节让 Agent 在迭代中越来越接近你的分析习惯。下一步可以继续探索的方向包括把 Agent 接入定时调度让报告每天自动更新增加异常检测模块让 Agent 在数据量异常波动时主动告警或者把 CSV 数据源换成数据库连接让 Agent 直接对接数仓。无论如何先把本文的代码跑通再逐步扩展会比直接追求“一步到位”更靠谱。如果这篇文章对你有帮助建议收藏备用。实际动手过程中遇到问题欢迎在评论区交流你的报错信息我会尽力帮忙排查。 Codex接入DeepSeek V4：40轮提示词构建数据分析Agent
之前在业务迭代中做数据分析最耗时的往往不是写 SQL也不是画图而是反复对齐口径、调试清洗逻辑、改报告。团队里每个人处理数据的方式都不一样产出的结果经常对不上。后来我把 DeepSeek V4 接入 Codex用提示词驱动一个数据分析 Agent 完成了 300 万行数据的清洗、聚合、可视化和报告生成整个过程经历了 40 轮提示词迭代最终数据和报告都能追溯到每一步操作后续复盘和汇报都轻松了很多。这篇文章会把整套方案完整拆开从 Codex 接入 DeepSeek V4 的配置方式到数据分析 Agent 的提示词设计再到 300 万行数据的实战代码和报告迭代机制。无论你是想给简历加一个能打的 AI Agent 项目还是想真正提升数据分析交付效率都可以照着做一遍。需要说明的是AI 编程工具和大模型版本迭代很快文中的配置项和模型名称请以你实际使用的版本为准。我会把工程思路和排错方法写清楚这部分比具体某个参数更有复用价值。1. 背景与核心概念1.1 这个项目要解决什么问题传统数据分析项目的交付链路通常是这样的业务方提需求。数据分析师从数据仓库取数。写 SQL 或 Python 做清洗和聚合。用图表展示结论。写一份几十页的报告。这条链路最大的问题是每一步都可能产生信息损耗。业务方说的“活跃用户”和数据分析师理解的“活跃用户”可能不是同一个口径清洗逻辑改了之后之前的图表和结论却没有同步更新报告是人工攒出来的原始数据、中间表、最终结论之间的对应关系很难追溯。我这次要做的就是把这个链路交给 AI Agent让 Codex 作为执行体DeepSeek V4 作为推理大脑通过 40 轮提示词把需求逐步拆解成可执行的数据分析任务并且每轮任务都记录输入、输出和处理逻辑。这样最终报告里的每一个数字都能回答“这个数是怎么算出来的”。1.2 Codex 和 DeepSeek V4 各自扮演什么角色先澄清一下这两个概念。Codex 是 OpenAI 推出的命令行编程工具它能够在终端里读取项目代码、执行命令、修改文件相当于把大模型接入了真实的开发环境。Codex 的特点是“会动手”而不只是“会聊天”。你可以让它写脚本、跑测试、修复报错甚至完成跨文件的代码重构。DeepSeek V4 是大语言模型。它擅长理解复杂指令、生成代码、分析数据和总结结论。在本文的架构里DeepSeek V4 负责理解提示词、生成数据处理代码、解释分析结果。两者组合起来的逻辑是Codex 提供“手”操作文件、执行命令、自动运行脚本。DeepSeek V4 提供“脑”理解任务、生成代码、给出分析结论。数据分析 Agent 是二者的统称它接受目标描述自主规划步骤产出可追溯的结果。需要特别说明的是Codex 默认连接的是 OpenAI 自己的模型但 Codex 在设计上允许通过配置文件接入第三方模型接口。本文要做的就是把 Codex 的模型后端切换到 DeepSeek V4 的接口上。1.3 适合哪些读者这篇文章适合三类人数据分析师想用 AI Agent 减少取数和清洗的重复劳动提升报告交付效率。后端或全栈开发者想了解 Codex 如何接入第三方模型以及如何设计一个可运行的 Agent 项目。准备求职跳槽的工程师需要一个完整、有量化指标、能讲清楚技术难点的 AI Agent 项目经验。如果你只是想要一个“自动写 SQL 的工具”本文的方案也能覆盖但真正有价值的是后面的提示词迭代机制和数据追溯设计。2. 环境准备与版本说明2.1 运行环境本文示例是在 Linux 服务器上完成的macOS 也完全兼容Windows 建议使用 WSL 2 或 Git Bash 保证命令行为一致。核心环境如下操作系统Ubuntu 22.04 / macOS 13Python3.10 及以上Node.jsCodex CLI 依赖 Node.js 环境建议 18 以上包管理器npm 或 HomebrewGit用于版本管理和报告追溯版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。2.2 安装 Codex CLI安装 Codex CLI 最常用的方式是通过 npm 全局安装# 使用 npm 安装 npm install -g openai/codex # 检查是否安装成功 codex --version如果使用 macOS 且已经安装了 Homebrew也可以尝试brew install codex安装完成后需要确认codex命令在 PATH 环境变量中。部分桌面版 Codex 工具会在安装后提供一个codex-cli可执行文件此时需要手动设置CODEX_CLI_PATH指向它。如果启动时报错unable to locate the codex cli binary基本就是 PATH 或 CODEX_CLI_PATH 没配置好。2.3 安装 Python 依赖数据分析部分需要以下 Python 库pandas2.0 duckdb0.9 matplotlib3.7 jinja23.1 numpy1.24创建虚拟环境并安装python -m venv .venv source .venv/bin/activate pip install -r requirements.txt这里推荐使用 DuckDB而不是纯 pandas 来处理 300 万行数据。原因后面会讲简单来说就是 DuckDB 能直接在 CSV 上跑 SQL内存占用更低速度也更快。2.4 项目目录结构整个项目建议按照下面的结构组织data-analysis-agent/ ├── .env # 环境变量存放 API Key ├── codex_config.toml # Codex 配置文件 ├── prompts/ │ ├── system_prompt.md # 系统提示词 │ └── tasks/ │ ├── round_01_explore.md │ ├── round_02_clean.md │ └── ... ├── scripts/ │ ├── generate_data.py # 模拟数据生成 │ ├── explore.py # 数据探查 │ ├── clean.py # 数据清洗 │ ├── analyze.py # 聚合分析 │ ├── visualize.py # 可视化 │ └── report.py # 报告生成 ├── audit/ # 审计日志 ├── report/ # 输出报告 │ └── charts/ # 图表 └── data/ └── orders.csv # 输入数据这个结构的好处是提示词、脚本、报告、审计日志彼此分离任何一步出现问题时都能快速定位。3. Codex 接入 DeepSeek V4 配置3.1 理解 Codex 的模型接入机制Codex 默认使用 OpenAI 的模型接口但它支持通过model_providers配置自定义模型服务商。接入 DeepSeek V4 的本质就是告诉 Codex模型请求发到哪个地址。使用哪个 API Key。默认使用哪个模型名称。这一步在网上资料比较少而且不同版本的 Codex 配置字段会有差异。下面给出一个比较通用的配置方式如果你安装的版本字段变了请以官方文档为准。3.2 编写 Codex 配置文件在用户根目录下创建 Codex 配置文件。CLI 版通常在~/.codex/config.toml桌面版可能在~/.codex/config.json具体取决于安装方式。本文以config.toml为例# 文件路径~/.codex/config.toml model deepseek-v4 model_providers { deepseek { name DeepSeek V4 base_url ${DEEPSEEK_BASE_URL}/v1 env_key DEEPSEEK_API_KEY } } model_provider deepseek简单解释几个关键配置项model对话默认使用的模型名称这里填 DeepSeek V4 对应的模型标识。model_providers定义自定义模型服务商。base_url模型接口地址。${DEEPSEEK_BASE_URL}表示从环境变量读取避免把地址写死在配置文件里。env_key指定从哪个环境变量读取 API Key。model_provider指定默认使用哪个服务商。然后在当前 shell 中设置环境变量export DEEPSEEK_BASE_URLhttps://your-deepseek-api-endpoint export DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxxxxxxbase_url的地址需要根据你自己的 API 服务商实际情况填写不同平台的路径规则可能不同。建议把这两个环境变量写入项目的.env文件并在启动前加载# 文件路径.env DEEPSEEK_BASE_URLhttps://your-deepseek-api-endpoint DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxxxxxx3.3 验证接入是否成功配置完成后在终端里执行一条最简单的 Codex 指令来验证codex exec 用中文回答11 等于几如果返回结果是“2”说明 Codex 已经成功通过 DeepSeek V4 模型响应。如果报错常见错误和解决办法在本文第 7 章会专门整理。这里有一个容易踩的坑DeepSeek 不同子模型的名称不同比如有的版本叫deepseek-v4有的版本叫deepseek-v4-pro还有面向多模态的deepseek-v4-flash-vision-exp。如果请求时报there is an issue with the selected model大概率是模型名称在接口里不存在需要去服务商平台确认准确名称或者查看日志里的model字段是否被正确传递。4. 数据分析 Agent 的提示词工程设计4.1 系统提示词先把规矩定好做数据分析 Agent 最容易翻车的点是模型自由发挥、口径混乱。比如你说“分析一下用户增长”它可能一会儿用“注册用户数”一会儿用“活跃用户数”最后报告里数字前后对不上。解决办法是在系统提示词里把规则写死让每一轮任务都在同一套规则下运行。下面是我使用的系统提示词模板# 文件路径prompts/system_prompt.md 你是资深数据分析工程师负责在终端中完成数据分析任务。 工作规则 1. 所有数据处理步骤必须记录输入、处理逻辑、输出记录到 audit/ 目录。 2. 涉及聚合、过滤、去重操作前必须先描述数据口径确认后再执行。 3. 数据口径定义 - 活跃用户近 30 天内至少下单 1 次的用户。 - GMV订单金额总和不含退款订单。 - 客单价GMV / 有效订单数。 4. 每个分析结论必须有代码执行结果支撑禁止猜测和估算。 5. 图表输出到 report/charts/报告输出到 report/文件名带日期。 6. 如果用户指令不明确先列出假设条件再开始执行。 7. 涉及删除数据或覆盖文件时先备份。这七条规则分别解决了数据分析中最常见的几类问题规则 1 保证可追溯。规则 3 统一口径。规则 4 防止模型“一本正经地胡说八道”。规则 7 保护生产数据安全。4.2 40 轮提示词把大任务拆成可执行单元项目标题里提到的“40 轮提示词”并不是一开始就规划好了 40 条而是在执行过程中逐步迭代出来的。大致分成六个阶段阶段轮次目标典型任务环境确认1-5确认数据和环境可用检查数据文件、Python 环境、依赖库数据探查6-10理解数据结构和质量字段类型、缺失值、重复值、分布情况口径确认11-15和“需求方”对齐口径明确筛选条件、聚合维度、指标定义数据清洗16-25产出可分析的干净数据去重、类型转换、异常值处理聚合分析26-32计算核心指标按渠道、按月聚合 GMV、订单量可视化与报告33-40输出可读的报告生成图表、撰写结论、补充建议这个拆解方式的好处是每一步的输入输出都很清晰即使中间某一步错了只需要回退到对应轮次重新执行而不需要推翻整份报告。4.3 每轮提示词的写法每轮提示词我都遵循同一个结构上下文 任务目标 输出要求 验收标准。举个例子第 1 轮的提示词如下# 文件路径prompts/tasks/round_01_explore.md 当前处于“环境确认”阶段前序任务已完成数据文件部署。 任务目标 查看 data/orders.csv 的字段结构确认数据可被正常读取。 输出要求 1. 打印前 5 行数据。 2. 输出字段名、字段类型、数据量。 3. 将结果记录到 audit/round_01.jsonl。 验收标准 - 数据能够被 pandas 或 DuckDB 成功读取。 - 记录字段结构供后续任务使用。这种写法让模型有明确的边界它知道自己在哪个阶段、要做什么、产出什么、怎么验证。40 轮迭代的核心不是每轮都生成新代码而是让每一轮的结果成为下一轮的输入像流水线一样推进。4.4 上下文管理和记忆大模型的上下文窗口是有限的。40 轮迭代如果每一轮都把全部历史对话塞进去后面肯定放不下。我的做法是每轮只保留当前任务提示词和最近 1-2 轮的结果。关键中间结果写入data/目录下的文件通过文件路径传递。数据口径和规则始终写在系统提示词里不依赖对话记忆。这样设计的好处是即使中途断线重来Agent 只需要读取最新的中间文件和审计日志就能恢复上下文。这也是“数据可追溯”在工程上的具体落地方式。5. 300 万行数据分析 Agent 实战5.1 准备模拟数据为了演示完整流程我先生成 300 万行订单数据。实际业务中你可以换成从数仓导出的真实数据代码逻辑是一样的。# 文件路径scripts/generate_data.py import pandas as pd import numpy as np np.random.seed(42) n 3_000_000 df pd.DataFrame({ order_id: range(1, n 1), user_id: np.random.randint(10000, 99999, n), order_date: pd.date_range(2023-01-01, periodsn, freqmin), channel: np.random.choice( [APP, Web, MiniProgram], n, p[0.5, 0.3, 0.2] ), amount: np.round(np.random.lognormal(mean4, sigma1, sizen), 2), status: np.random.choice( [completed, refunded, pending], n, p[0.95, 0.03, 0.02] ) }) df.to_csv(data/orders.csv, indexFalse) print(生成完成数据量, len(df))运行python scripts/generate_data.py这里有两点需要注意300 万行数据用freqmin生成时时间跨度大约覆盖 5.7 年符合“近 30 天活跃用户”这种口径的判断。amount使用对数正态分布更接近真实订单金额的右偏分布。5.2 数据探查脚本拿到数据后先用 DuckDB 快速探查数据而不是直接用 pandas 读入内存。DuckDB 可以直接在 CSV 文件上跑 SQL读取 300 万行数据只需要几秒钟。# 文件路径scripts/explore.py import duckdb con duckdb.connect(data/analysis.db) # 查看字段结构 print( 字段结构 ) print(con.execute(DESCRIBE SELECT * FROM read_csv_auto(data/orders.csv)).df()) # 查看整体数据量 print(\n 数据量 ) print(con.execute( SELECT COUNT(*) AS total_cnt, COUNT(DISTINCT user_id) AS user_cnt, COUNT(DISTINCT channel) AS channel_cnt FROM read_csv_auto(data/orders.csv) ).df()) # 查看缺失值 print(\n 缺失值统计 ) print(con.execute( SELECT COUNT(*) AS total, COUNT(order_id) AS order_id_cnt, COUNT(user_id) AS user_id_cnt, COUNT(order_date) AS order_date_cnt, COUNT(channel) AS channel_cnt, COUNT(amount) AS amount_cnt FROM read_csv_auto(data/orders.csv) ).df())DuckDB 的read_csv_auto会自动推断字段类型省去了手工指定 schema 的步骤。探查结果建议保存到data/explore_result.csv后续分析直接引用。5.3 数据清洗与口径落地清洗是数据分析里最容易出错、也最需要“可追溯”的环节。下面这段代码展示了如何用 DuckDB 完成一次基于口径的清洗# 文件路径scripts/clean.py import duckdb con duckdb.connect(data/analysis.db) # 口径 # 1. 仅保留 completed 状态的订单 # 2. 剔除 amount 0 的异常订单 # 3. 去除重复 order_id # 4. 生成唯一主键便于追溯 cleaned_sql CREATE OR REPLACE TABLE cleaned_orders AS SELECT order_id, user_id, order_date, channel, amount, completed AS valid_status, CURRENT_TIMESTAMP AS processed_at FROM ( SELECT *, ROW_NUMBER() OVER ( PARTITION BY order_id ORDER BY order_date DESC ) AS rn FROM read_csv_auto(data/orders.csv) WHERE status completed AND amount 0 ) WHERE rn 1 con.execute(cleaned_sql) print(清洗后数据量, con.execute(SELECT COUNT(*) FROM cleaned_orders).fetchone()[0]) print(订单金额统计) print(con.execute( SELECT MIN(amount) AS min_amt, MAX(amount) AS max_amt, AVG(amount) AS avg_amt FROM cleaned_orders ).df())这段代码里比较关键的是ROW_NUMBER() OVER (PARTITION BY order_id ...)窗口函数。它的作用是如果同一个订单 ID 出现多次只保留最新的一条这就处理了重复数据问题。而且整个清洗过程的所有规则都写在了 SQL 里任何人看到这段代码都能还原“干净数据是怎么来的”。清洗完成后建议把结果导出成中间表con.execute(COPY cleaned_orders TO data/cleaned_orders.csv (HEADER, DELIMITER ,))中间表的存在非常重要后续分析不会反复读取原始 CSV而是基于这份清洗后的数据。哪一步出了问题只需要对比原始表和清洗后的中间表就能定位。5.4 聚合分析与可视化数据处理完成后开始计算核心指标。这里以“月维度、渠道维度的 GMV 和客单价”为例# 文件路径scripts/analyze.py import duckdb con duckdb.connect(data/analysis.db) # 月度、渠道维度的核心指标 result con.execute( SELECT channel, DATE_TRUNC(month, order_date::DATE) AS month, COUNT(*) AS order_cnt, COUNT(DISTINCT user_id) AS user_cnt, SUM(amount) AS gmv, AVG(amount) AS avg_amount FROM cleaned_orders GROUP BY 1, 2 ORDER BY 2, 1 ).df() result.to_csv(data/monthly_channel_metrics.csv, indexFalse) print(result.head(10))拿到聚合结果后用 matplotlib 生成可视化图表# 文件路径scripts/visualize.py import pandas as pd import matplotlib.pyplot as plt # 设置中文字体避免图表乱码 plt.rcParams[font.sans-serif] [SimHei, Arial Unicode MS, DejaVu Sans] plt.rcParams[axes.unicode_minus] False df pd.read_csv(data/monthly_channel_metrics.csv) df[month] pd.to_datetime(df[month]) # 各渠道月度 GMV 趋势 pivot df.pivot(indexmonth, columnschannel, valuesgmv) pivot.plot(figsize(12, 6)) plt.title(各渠道月度 GMV 趋势) plt.xlabel(月份) plt.ylabel(GMV) plt.grid(True, linestyle--, alpha0.5) plt.tight_layout() plt.savefig(report/charts/gmv_trend.png, dpi150) print(图表已保存report/charts/gmv_trend.png)300 万行数据经过聚合之后画图用到的数据量已经非常小此时可以直接用 pandas matplotlib性能完全够用。5.5 自动化报告生成报告生成采用 Jinja2 模板好处是代码、数据和报告内容分离。分析结论变化时只需要重新渲染模板不需要手工改报告。# 文件路径scripts/report.py import pandas as pd from datetime import date from jinja2 import Template df pd.read_csv(data/monthly_channel_metrics.csv) # 计算汇总指标 total_gmv df[gmv].sum() total_orders df[order_cnt].sum() avg_amount total_gmv / total_orders channels df.groupby(channel)[gmv].sum().sort_values(ascendingFalse) template_text # 电商订单数据分析报告自动生成 生成日期{{ today }} ## 1. 核心指标 | 指标 | 数值 | | --- | --- | | 总 GMV | {{ total_gmv | round(2) }} | | 总订单量 | {{ total_orders }} | | 客单价 | {{ avg_amount | round(2) }} | ## 2. 渠道 GMV 占比 {% for channel, gmv in channels.items() %} - {{ channel }}{{ gmv | round(2) }} {% endfor %} ## 3. 结论 - 月度 GMV 趋势图见 charts/gmv_trend.png。 - 各渠道贡献排名稳定APP 渠道为主要营收来源。 - 本报告所有指标均可通过 data/monthly_channel_metrics.csv 复算。 template Template(template_text) report template.render( todaydate.today().isoformat(), total_gmvtotal_gmv, total_orderstotal_orders, avg_amountavg_amount, channelschannels ) with open(report/analysis_report.md, w, encodingutf-8) as f: f.write(report) print(报告已生成report/analysis_report.md)运行后report/analysis_report.md会自动生成包含日期、核心指标、渠道占比和图表路径的报告。由于报告是基于模板渲染的每次数据更新后重跑脚本就能得到最新版本。5.6 运行整个流程把所有脚本串起来用一行命令完成整个分析链路python scripts/generate_data.py \ python scripts/explore.py \ python scripts/clean.py \ python scripts/analyze.py \ python scripts/visualize.py \ python scripts/report.py这个流程跑通之后就可以让 Codex 接管了。把上面每一步作为一个提示词任务交给 Codex 执行它会根据当前项目结构自动调用对应脚本并在报错时尝试修复。这就是“数据分析 Agent”和普通脚本最大的区别普通脚本报错就停了Agent 会读日志、改代码、重新执行直到跑通。6. 数据可追溯与报告迭代6.1 审计日志让每一步都有据可查“数据可追溯”是这个项目最核心的工程点。我采用的方案是在系统提示词里硬性要求 Agent 将每一步处理写入审计日志。# 文件路径scripts/audit.py import json from datetime import datetime class AuditLogger: def __init__(self, log_pathaudit/audit_log.jsonl): self.log_path log_path def record(self, step, operation, input_path, output_path, paramsNone): entry { time: datetime.now().isoformat(), step: step, operation: operation, input: input_path, output: output_path, params: params or {} } with open(self.log_path, a, encodingutf-8) as f: f.write(json.dumps(entry, ensure_asciiFalse) \n) # 示例记录一次清洗过程 if __name__ __main__: logger AuditLogger() logger.record( stepdata_clean, operationfilter_and_dedup, input_pathdata/orders.csv, output_pathdata/cleaned_orders.csv, params{status: completed, amount: 0} ) print(审计日志已写入audit/audit_log.jsonl)审计日志使用 JSON Lines 格式每一行是一条独立的记录。这种格式的好处是可以不断追加写入也方便后续用grep或 Python 按步骤筛选。6.2 报告版本管理分析报告不是一次就能定稿的。第 33-40 轮提示词就是在反复修改报告补充图表、修正结论、调整排版。为了让这个迭代过程可管理我采用了两条规则报告文件名必须带版本号analysis_report_v1.md、analysis_report_v2.md。整个report/目录用 Git 管理每次修改提交一次。git init git add report/ audit/ scripts/ git commit -m feat: 完成第一版分析报告当第 40 轮结束你可以在 Git 历史里清楚看到报告从 v1 到 v8 的完整演进过程。这种习惯在真实业务场景里非常有用业务方说“还是觉得上一版好”你只需要git checkout到对应版本即可。6.3 让 Agent 基于反馈迭代报告报告迭代的提示词也有固定套路下面是一个示例# 文件路径prompts/tasks/round_35_refine_report.md 当前状态 - 第 34 轮已完成报告 v1文件位于 report/analysis_report_v1.md。 - 业务方反馈 1. 渠道占比希望用饼图展示。 2. 补充月度环比增长率。 3. 结论部分需要更口语化。 任务目标 针对反馈修改分析流程和报告生成 v2 版本。 输出要求 1. 新增环比增长率计算。 2. 新增渠道占比饼图。 3. 更新报告内容并保存为 report/analysis_report_v2.md。 4. 将修改内容记录到 audit/audit_log.jsonl。 验收标准 - 报告 v2 中包含新增图表和指标。 - 新指标可以从聚合结果中复算。这种“反馈-修改-验证-出新版本”的循环是 40 轮提示词能够产出高质量报告的核心原因。每一轮都有明确目标和验收标准模型不会漫无目的地“自由发挥”。7. 常见问题与排查思路实战过程中我踩过不少坑。下面把高频问题整理成表格方便检索。问题现象常见原因解决思路unable to locate the codex cli binaryCodex 不在 PATH 中或桌面版未指定 CLI 路径将 codex 加入 PATH或在环境变量中设置CODEX_CLI_PATH指向可执行文件there is an issue with the selected model模型名称填写错误或接口不支持该模型去模型服务商平台确认准确的模型标识检查配置中的model字段the agent execution provider did not respond in time请求超时、接口限流或网络波动降低并发请求增加超时重试检查代码中是否存在死循环读取 CSV 时内存不足一次性把 300 万行数据载入 pandas改用 DuckDB 或 pandas 分块读取先用采样数据探查报告中文字体乱码matplotlib 未配置中文字体设置plt.rcParams[font.sans-serif]或指定系统中文字体图表日期显示为时间戳日期列未被正确解析为 datetime使用pd.to_datetime()显式转换后再绘图每次跑脚本结果不一致随机种子未固定或清洗逻辑未排序固定random_state去重逻辑增加排序条件其中比较难排查的是“模型请求超时”问题。Codex 在调用外部模型时如果单次请求等待时间太长会直接报超时错误并不一定代表模型接口本身不可用。遇到这类问题建议先做一次简单的连通性测试curl -X POST ${DEEPSEEK_BASE_URL}/v1/chat/completions \ -H Authorization: Bearer ${DEEPSEEK_API_KEY} \ -H Content-Type: application/json \ -d {model: deepseek-v4, messages: [{role: user, content: ping}]}如果 curl 能返回结果说明网络和接口都正常问题大概率出在 Codex 的超时配置或模型名称上如果 curl 本身超时就需要检查网络和服务商状态了。另一个容易忽略的问题是数据清洗逻辑的顺序。比如先过滤status completed再去除重复和先去重再过滤最终的数据量可能会不一样。因此审计日志里必须记录每一步的先后顺序。这也是为什么我在系统提示词里要求“涉及聚合、过滤、去重操作前必须先描述数据口径”。8. 最佳实践与工程建议8.1 密钥与安全整个项目涉及 API Key 和大量数据安全底线必须遵守密钥不写进代码或配置文件统一使用环境变量或者加载.env文件。.env文件加入.gitignore防止误提交到代码仓库。演示数据使用模拟数据如果是真实业务数据则需要先脱敏并明确数据使用范围。删除或覆盖数据文件之前先备份原文件避免误操作导致数据丢失。8.2 让 Agent 更稳定的小技巧为了让 Codex 在 40 轮长任务中保持稳定有几点经验很实用每一轮任务的提示词尽量短小、聚焦一次只解决一个目标。给每一轮设置“验收标准”让模型知道什么时候算完成。中间数据全部落盘成文件不要只保存在内存里。这样 Agent 重启后也能恢复进度。如果某一轮任务执行结果异常直接让 Codex 读取审计日志和该轮提示词重新执行即可不需要从头再来。8.3 性能优化的常见策略针对 300 万行甚至更大的数据量性能优化可以从三个方向入手用 DuckDB 代替纯 pandas 做聚合。DuckDB 的 SQL 引擎对大数据量更友好代码也更简洁。大表处理时优先使用 SQL 的 WHERE 条件提前过滤而不是先读全量数据再在内存里过滤。可视化阶段只读取聚合后的结果不要用原始明细数据画图。8.4 如何把这个项目写进简历如果目标是拿这个项目面试建议按“项目背景-技术方案-量化结果-核心难点”的结构来写数据分析 Agent 项目使用 Codex CLI 接入 DeepSeek V4 模型通过 40 轮提示词迭代构建数据分析 Agent完成 300 万行订单数据的清洗、聚合、可视化与报告生成。技术栈Python、DuckDB、pandas、Jinja2、Codex CLI、DeepSeek V4。项目成果报告生成时间从人工 2 天缩短至 30 分钟所有数据指标可在 audit/ 审计日志中追溯报告支持版本迭代可快速回滚。核心难点多轮任务上下文管理、数据口径统一、长任务稳定性、大数据量下内存优化。面试时重点讲清楚“数据可追溯”的实现方案也就是审计日志、中间表、Git 版本管理这三层机制。这套设计比单纯“用 AI 写代码”更有工程价值。9. 总结与下一步建议整个项目跑通之后我最大的感受是AI Agent 真正的价值不在于替你写多少行代码而在于把数据分析过程变成一个可拆解、可迭代、可追溯的工程流程。DeepSeek V4 负责理解任务和生成代码Codex 负责在真实环境里执行和调试而提示词工程决定整个过程的上限。如果你准备动手实践我的建议是先不要追求 40 轮一步到位而是从 10 轮开始把系统提示词、审计日志、报告模板这三块基础能力搭好。跑通第一条链路之后再逐步增加指标维度、图表类型和报告章节让 Agent 在迭代中越来越接近你的分析习惯。下一步可以继续探索的方向包括把 Agent 接入定时调度让报告每天自动更新增加异常检测模块让 Agent 在数据量异常波动时主动告警或者把 CSV 数据源换成数据库连接让 Agent 直接对接数仓。无论如何先把本文的代码跑通再逐步扩展会比直接追求“一步到位”更靠谱。如果这篇文章对你有帮助建议收藏备用。实际动手过程中遇到问题欢迎在评论区交流你的报错信息我会尽力帮忙排查。