项目二|数据分析 Agent:自然语言 → 自动分析
2025.06 – 至今企业交付 本文件是该项目的完整版。主简历只保留 6 条能力点,其余细节、边界与追问预案在此。 仓库不在手边时,按本文件口径讲;不要引入未经核实的新数字。
一、完整叙述(主简历已压缩,此处为原稿)
业务背景:业务人员上传表格后用自然语言提问,Agent 先出分析计划、再逐步写代码在容器里跑,边跑边把每一步推给前端看,输出图表与结论;存文件这类写操作必须停下来等人确认。四个工具:跑 Python / 查只读 SQL / 出图 / 存报告。
核心难点:
- 「下一步去哪」不能埋在 if/else 里——失败后要能重试、跳步或收敛,线性流程表达不了。解法:7 节点图 + 3 处条件分派(观察节点单点 5 个出口),「重试上限」「待审批动作」「已执行步骤」全部进状态、由边读取后决定走向;另设工具调用累计 10 次硬上限,任意分支组合都不会原地空转。
- 生成的代码不可信——关键字黑名单换个写法就绕过。解法:执行前跑自写的 AST 扫描器,建作用域符号表而不是匹配字符串——
import x as y别名、赋值别名、链式别名、元组解包、字典与列表下标取值、dict.get/pop、getattr常量与动态两种形态、函数参数重绑定、内层函数遮蔽外层同名,都能追回最初那个危险符号;36 例单测逐类钉死绕过路径,同时保留os.path这类安全用法不误杀。 - 写操作不能全自动——解法:编译期声明
interrupt_before=["approve"],执行到审批节点前由框架硬停,状态落 SQLite 检查点(WAL);人工确认后从同一 thread 续跑到同一个节点,前序步骤不重跑,进程重启不丢进度。 - 模型会「只说不做」——让它调工具,它回一段「我打算这么做」的文本。解法:把「未调用任何工具」本身当成一次结构化失败写进工具结果,逼下一轮修正;连续两次仍不调则跳步收尾,而不是重试到上限——把模型的沉默也当成一种可观测的失败。
- 只读根会让「无辜」的写入也失败——matplotlib 默认往 HOME 写字体缓存、往工作目录写临时文件,容器根只读后直接抛 OSError,报错与代码逻辑毫无关系,模型会误判成自己写错了。解法:执行前注入环境垫片——缓存目录与
TMPDIR全指到 tmpfs 工作区、强制 Agg 后端、内置中文字体族并修负号乱码、拦截makedirs的只读异常降级;把「环境不适配」从模型要解决的问题里摘出去。
核心工作:
- 状态即决策依据:步骤索引 / 重试计数 / 待审批动作 / 工具结果全进
AgentState,节点只负责产出、走向交给条件边,避免同一个判断在两处各写一遍。 - 反思输出结构化:反思节点返回
{decision, reason, correction}三字段,correction直接拼进下一轮执行提示;配max_retries=2,防止无限自我否定。 - 沙箱六项约束:断网(
network_mode=none)、根只读、模型代码与业务数据全只读挂载、唯一可写卷是会话输出目录、工作区 tmpfs 限 64MB、1 核 / 256MB / 30s;内存超限单独识别(exit 137 + 日志特征)而不是笼统报错。 - 流式与恢复分离:按节点推进度事件;审批时主动结束流并把
thread_id交回前端,不让长连接干挂着;单条消息各截 2000 / 8000 字符控制体积;会话产物目录按 1 小时 TTL 清理。 - 长期记忆:ChromaDB 余弦检索相似历史分析、取前 3 条注入「理解」节点提示,让同类问题沿用上次的口径。
- 状态即决策依据:步骤索引 / 重试计数 / 待审批动作 / 工具结果全进
项目成果:7 节点 / 3 处条件分派;AST 扫描器 36 例单测覆盖别名链、容器间接取值、反射、作用域遮蔽五类绕过;沙箱六项约束 + 内存超限识别;1946 行 / 22 个源文件。
边界:单机部署、未做并发压测,每次执行新建容器、没有池化;反思虽约定
finish / retry / replan三态,代码只实现了前两条,replan实际落到「继续下一步」——prompt 与实现存在一处不一致;执行失败只有一个error字段,未按超时 / 可重试 / 需改计划分类,重试策略对一切失败一视同仁;SQL 只读靠语句前缀校验,不是数据库权限级隔离;静态扫描是纵深防御的一层,刻意混淆仍可能绕过。
二、主简历压缩版(6 条)
- 让走向成为可读的边:7 节点图(理解 / 计划 / 执行 / 观察 / 反思 / 审批 / 汇总)+ 3 处条件分派,观察节点单点 5 个出口;步骤索引、重试上限、待审批动作全放状态,节点只产出、边做决策;工具调用累计 10 次硬上限兜底,任何分支组合都不会原地空转。
- AST 扫描用符号表,不用关键字:执行前建作用域符号表追踪
import as别名、赋值别名、链式别名、元组解包、字典 / 列表下标取值、dict.get/pop、getattr常量与动态两种形态、函数参数重绑定、内层函数遮蔽外层——都能追回最初的危险符号;36 例单测逐类钉死绕过路径,同时保留os.path不误杀。 - 沙箱六项约束 + 内存超限单独识别:断网 / 根只读 / 代码与数据全只读挂载 / 唯一可写卷是会话输出目录 / 工作区 tmpfs 限 64MB / 1 核 256MB 30s;OOM 按 exit 137 与日志特征识别,不笼统报「执行失败」。
- 写操作靠框架硬停而不是自觉:编译期声明
interrupt_before=["approve"],审批节点前强制中断、状态落 SQLite 检查点(WAL);人工确认后同 thread 续跑到原节点,前序步骤不重跑、进程重启不丢进度。 - 模型的沉默也是失败:让它调工具它只回一段描述。把「未调用任何工具」写成一条结构化失败塞回结果逼其修正,连续两次则跳步收尾——不是重试到上限。
- 只读根会让无辜的写入也失败:matplotlib 往 HOME 写字体缓存、往工作目录写临时文件,根只读后直接 OSError,报错与代码逻辑无关、模型会误判成自己写错。解法:执行前注入环境垫片(缓存与
TMPDIR指到 tmpfs、强制 Agg、内置中文字体族、拦截makedirs只读异常)——把「环境不适配」从模型要解决的问题里摘出去。
三、面试追问预案
Q1:为什么不用 ReAct / Plan-and-Execute 的现成框架,自己画图?
因为要的不是「能跑」,是「能解释为什么这么跑」。现成 loop 里,重试上限、待审批动作这些都藏在框架内部或 prompt 里,出了问题只能看日志猜。画成图之后,「为什么这一步走了重试」是一个可以从状态里读出来的事实,不是一个推断。代价是要自己维护节点和边,节点一多会烦。
Q2:7 个节点是不是为了显得复杂?
不是,是被分支逼出来的。理解、计划、执行、观察、反思、审批、汇总这七件事的输入输出不一样,合并任何一个都会让「谁负责什么」变混。真正省钱的地方是观察节点有 5 个出口——这一个分派点就把重试、跳步、收敛、审批、收尾全接住了。
Q3:AST 扫描和黑名单到底差在哪?举一个黑名单拦不住的例子。
__import__("os").system("...")。黑名单会写"os.system"这个字符串,但这里没有这个字符串。符号表做法是:解析到__import__是危险调用 → 返回值的符号标记为「来自危险调用」→.system属性访问落在被标记的基对象上 → 拦。同样的机制还覆盖d = {"a": os}; d["a"].system(...)、(f,) = (os,); f.system(...)、getattr(os, "sys" + "tem")。36 个单测就是按这些路径一条条写的。
Q4:36 个单测里最有价值的是哪一条?
是「安全用法不误杀」那几条——
os.path.join必须放行。只拦不放的扫描器,最后要么被人关掉,要么逼着大家绕开它。做安全最容易犯的错是把自己人拦死。
Q5:审批中断为什么要用框架的 interrupt 而不是自己写个 waiting 状态?
自己写的话,进程重启后内存里的状态就没了,得重新序列化整个世界。用
interrupt_before+ checkpointer,状态落在 SQLite(WAL 模式),重启后从同一个 thread_id 接着跑。代价是状态必须可序列化,不能往里塞对象。
Q6:沙箱为什么是六项约束,哪一项是必需的?
必需的是「断网」。其他几项是纵深的层次:根只读防止改代码,数据只读防止污染源,唯一可写卷限制扩散范围,tmpfs 限 64MB 防止拿内存当硬盘,CPU 内存超时限制资源。断网这一项拦的是最严重的一类——把数据传出去。去掉任何一项,攻击面都会变宽,但只有断网是不可替代的。
Q7:模型只说不做,你怎么发现的?
跑批的时候发现某些 case 走了两轮就结束了、但什么都没执行。看 trace 发现 action 节点返回了纯文本、
tool_calls是空数组,然后流程把它当成「成功」继续往下走。这个 bug 有意思的地方是:它在日志里看起来一切正常。
Q8:这个项目最弱的地方?
三个,我都能说清楚:① 失败只有一个 error 字段,超时、可重试、需改计划全走同一条路,重试策略对一切失败一视同仁;②
replan在 prompt 里约定了但代码没实现,实际落到「继续下一步」;③ SQL 只读靠语句前缀校验(只看前 20 字符),SELECT ...; DROP这类是拦不住的,真正的解法是只给只读账号。
四、主动承认的边界(不要等被问)
| 边界 | 说明 |
|---|---|
| 单机 + 每次新建容器 | 没有池化,冷启动有开销;未做并发压测 |
| 失败未分类 | 只有一个 error 字段,重试策略对一切失败一视同仁 |
replan 未实现 | prompt 写了三态,代码只有 retry / finish |
| SQL 只读是前缀校验 | 不是数据库权限级隔离 |
| 静态扫描是纵深的一层 | 刻意混淆仍可能绕过,不宣称「绝对安全」 |
| 规模小 | 1946 行 / 22 个源文件,是原型级体量 |
五、数据出处
| 数字 | 出处 |
|---|---|
| 7 节点 / 3 处条件分派 | src/graph/builder.py add_node / add_conditional_edges |
| 观察节点 5 出口 | builder.py 条件边映射字典 |
| 10 次硬上限 | src/graph/edges.py len(results) > 10 |
| 36 例单测 | tests/test_code_scanner.py 的 test_ 函数计数 |
| 沙箱六项 | src/sandbox/docker_executor.py containers.run(...) 参数 |
| tmpfs 64MB | 同上 tmpfs={"/workspace": "size=64m"} |
| OOM 识别 | 同上 exit_code == 137 分支 |
interrupt_before | builder.py compile(interrupt_before=["approve"]) |
| WAL | builder.py PRAGMA journal_mode=WAL |
| 1946 行 / 22 文件 | find src -name "*.py" -size +0 计数 |
