大家好，我是AI淇橦学。
上期我们给 Agent 装上了规划能力：智谱批量分析任务、匹配客户、制定带备注的执行计划，你确认后自动生成所有报价单。
但跑完批量任务之后，你有没有逐一打开每份报价单检查过？
报价金额有没有填到了联系电话那一栏？客户名称有没有张冠李戴？日期格式对不对？
如果你有 10 份报价单，逐一检查要花不少时间。如果没检查就直接发给客户——发出去之后才发现金额写错了，那就麻烦了。
这期我们来解决这个问题：在每份报价单保存之前，让智谱先审查一遍，发现问题自动拦截，不让错误的文件进入 output 文件夹。
做完这期，你会得到：
- 一个
validator.py自检模块，保存前自动执行两层检查 - 第一层：程序规则检查（快速扫描有没有未填写的占位符）
- 第二层：智谱智能审查（理解字段内容是否合理，发现规则检测不到的问题）
- 实际演示：故意制造两种错误，看智谱能不能发现并拦截
一、最重要的认知：没有报错 ≠ 做对了
很多人默认「程序没报错，就说明成功了」。这个逻辑在传统软件里大致成立，但 Agent 不一样——它可以完美地「执行成功」一件错误的事。
来看一个我们场景里真实可能发生的情况：
你让 Agent 批量处理 3 份报价单，它告诉你：「✅ 全部完成，成功 3 份，失败 0 份。」
你打开第一份报价单……
字段内容都是真实的，都来自客户资料——但全部填错了位置。Agent 没有报错，因为它确实把每个字段都写入了内容，每一步都「执行成功」了。
「执行成功」说的是步骤完成了，不是结果正确了。 这两件事必须分开验证。
坦白说，这个问题如果不解决，Agent 批量处理的越多，出错的概率就越大，最后可能还不如手动填单。
二、为什么用智谱来做自检，而不是规则
你可能会想：用正则表达式也能检查字段格式，为什么要用智谱？
规则检查的局限在于：它只能检查你预先想到的情况。
比如金额字段，规则可以检查「必须包含数字」，但检查不了这些：
- 「2025年6月15日」——包含数字，但明显是日期不是金额
- 「李总」——纯文字，规则能发现，但不知道这是联系人名字填错了位置
- 「XS-2000B」——包含数字，规则认为通过，但这是产品型号不是金额
智谱（大模型）不一样。它理解字段含义——「报价金额字段里填了一个日期」这件事，智谱一眼就能看出来是错的，不需要你提前写规则覆盖每种情况。
所以这期的自检设计是两层结合：
- 第一层：程序规则检查（快、不消耗 API）——检查有没有未替换的占位符，这种明确的问题用规则检查最高效
- 第二层：智谱智能审查（慢一点、消耗 API）——把填好的报价单内容发给智谱，让它判断每个字段的内容是否合理，覆盖规则检测不到的问题
两层都通过，才保存文件。
我觉得这个设计挺巧妙的——规则检查过滤掉低级错误，智谱处理复杂问题，既节省 API 费用，又能保证质量。
三、报价单场景的 4 种常见错误
了解具体会出什么错，才能理解为什么需要两层检查。
① 字段遗漏：有些占位符没被替换，还是 【产品名称】 这种原始状态。规则检查能发现。
② 字段错位：内容是真实的，但填错了位置——联系人填到了联系电话那栏。规则难以发现，智谱能发现。
③ 格式错误：内容位置都对，但格式不符合要求——金额写成了「58000」而不是「¥58,000.00元」。智谱能判断。
④ 内容异常：字段里填了明显不合逻辑的内容——金额字段填了「待定」、日期字段填了产品型号。规则难以完全覆盖，智谱能理解。
这四种错误，我在实际测试中真的都遇到过。所以这期的自检不是过度设计，而是实打实的需要。
四、实操开始：给 Agent 加上两层自检
在第3、4、5期的项目基础上继续。
这期的实操分 3 步：
- 用 Codex 生成
validator.py（两层检查：规则 + 智谱） - 把自检接入批量处理流程
- 故意制造错误，测试智谱能否发现并拦截
第一步：用 Codex 生成自检模块
打开 Codex，发送以下提示词：
📋 发给 Codex 的提示词（直接复制使用）：
12345678910111213141516171819202122232425262728293031323334我在做一个销售报价单 Agent，需要一个自检模块，文件名 validator.py。
已有 llm.py（提供 ask_zhipu、ask_zhipu_json）可以调用智谱 API。
自检分两层：第一层用程序规则检查，第二层用智谱做智能审查。
【需要实现的功能】
1. check_completeness(doc)
【第一层：程序规则检查】
- 扫描整个 Word 文档（doc 对象）的所有段落和表格单元格
- 找出所有仍然包含【和】的文本（说明占位符未被替换）
- 返回：{"passed": True/False, "missing_fields": [未替换的占位符列表]}
- 打印：✅ 完整性检查通过 / ❌ 发现未填写字段：【xxx】
2. check_by_zhipu(doc, customer_name, field_data)
【第二层：智谱智能审查】
- 参数：doc、customer_name、field_data
- 把 field_data 格式化成清单文本
- 构造发给智谱的 prompt，让它检查字段内容是否合理
- 调用 ask_zhipu_json 获取智谱的判断
- 打印智谱的审查结果
- 返回：{"passed": True/False, "issues": [...]}
3. validate(doc, customer_name, field_data)
- 依次执行两层检查
- 第一层失败直接返回，不调用第二层
- 两层都通过才返回 valid=True
【技术要求】
- 从 llm.py 导入：ask_zhipu_json
- 使用 python-docx 操作 Word 文档对象
- 代码有清晰的中文注释
- 每个函数要有错误处理
- 第一层失败时不调用智谱（节省 API 费用）
Codex 生成后写入 validator.py。 
第二步：把自检接入批量处理流程
修改 planner.py，在每份报价单保存之前插入自检步骤。
打开 Codex 对话框，发送以下提示词：
📋 发给 Codex 的提示词（直接复制使用）：
12345678910111213141516171819202122请帮我修改 planner.py 的 execute_plan 函数，
在每份报价单保存之前加入两层自检。
【修改逻辑】
原来的流程：
组装 field_data → write_content → save_file
修改后的流程：
组装 field_data → write_content → validate（两层自检）→ 根据结果决定是否 save_file
【具体规则】
1. 调用 write_content 得到填写好的文档对象 doc
2. 调用 validator.py 的 validate(doc, customer_name, field_data) 执行自检
3. 如果 validate 返回 {"valid": True}：调用 save_file 保存文件
4. 如果 validate 返回 {"valid": False}：不保存文件，记录失败原因，继续处理下一个任务
【汇总报告修改】
在 generate_summary_report 里，统计分三类：
- 成功：两层自检通过并已保存
- 自检失败：自检未通过，附上智谱发现的具体问题
- 执行失败：程序报错
第三步：故意制造错误，测试智谱自检效果
这是这期最重要的一步——不实际测试，你不知道智谱自检是否真的在工作。
我们分别制造两种错误，分别触发两层检查。
测试一：触发第一层（完整性检查）
打开 批量任务.json，把第一个任务的 product_name 改成空字符串：
12345678{
"customer_keyword": "深圳科技",
"product_name": "",
"product_model": "XS-2000B",
"quantity": 1,
"unit_price": 58000,
"notes": "含安装调试服务"
}
【产品名称】 占位符不会被替换，完整性检查应该在第一层就拦截，不需要调用智谱。
测试二：触发第二层（智谱审查）
把第二个任务的 unit_price 改成日期字符串（模拟字段错位）：
12345678{
"customer_keyword": "上海贸易",
"product_name": "基础套件",
"product_model": "XS-1000",
"quantity": 10,
"unit_price": "2025年6月15日",
"notes": "批量采购"
}
金额字段填了日期——这个完整性检查会通过（占位符已被替换），但智谱审查时应该发现「报价金额字段里填了一个日期，不是金额」。
运行测试：
1python agent.py --batch 批量任务.json
期望看到的结果：
123456789101112131415161718192021222324252627282930🚀 开始执行批量任务...
[1/3] 处理中：深圳科技有限公司...
===== 自检报告：深圳科技有限公司 =====
第一层（完整性）：❌ 失败 — 发现未填写字段：【产品名称】
=====================================
⚠️ [1/3] 深圳科技有限公司：自检未通过，已跳过保存
（第一层失败，未调用智谱，节省 API 费用）
[2/3] 处理中：上海贸易集团...
===== 自检报告：上海贸易集团 =====
第一层（完整性）：✅ 通过
🤖 正在调用智谱审查报价单内容...
第二层（智谱审查）：❌ 失败
智谱发现问题：报价金额字段填入了「2025年6月15日×10」，
这是日期格式而非金额，疑似字段错位
=====================================
⚠️ [2/3] 上海贸易集团：自检未通过，已跳过保存
[3/3] 处理中：北京智能装备公司...
===== 自检报告：北京智能装备公司 =====
第一层（完整性）：✅ 通过
🤖 正在调用智谱审查报价单内容...
第二层（智谱审查）：✅ 通过 — 所有字段内容合理
=====================================
✅ [3/3] 北京智能装备公司 → output/报价单_北京智能装备公司_20250615.docx
📊 汇总报告已生成：output/批量报价汇总_20250615.txt
✅ 执行完成：成功 1 份，自检失败 2 份，执行失败 0 份
注意两个细节：
第一，测试一在第一层就被拦截了，没有调用智谱。这很重要——完整性这种简单问题不应该浪费 API 费用，先用规则快速过滤。
第二，测试二第一层通过了，智谱才被调用，而且智谱发现了「金额字段填了日期」这种规则写不出来的问题，说清楚了原因。
坦白说，第一次看到这个输出时，我觉得挺震撼的——智谱真的能发现这种隐藏很深的错误。
测试完成后，把 批量任务.json 改回正确数据，再跑一遍，确认 3 份全部通过两层自检并保存成功。 
第四步：验收结果
功能验收：
字段遗漏测试：product_name 为空时，第一层拦截，智谱未被调用，文件不被保存
字段错位测试：金额填日期时，第一层通过，智谱发现问题，文件不被保存
正常数据测试：所有字段正确时，两层全部通过，文件正常保存
自检失败不影响其他任务：前两份失败，第三份仍然正常处理
汇总报告里包含自检失败的具体原因（智谱说的是什么）
output 文件夹里没有自检失败的报价单文件
templates/ 和 customers/ 里的原始文件未被修改
五、遇到问题怎么办
情况一：第一层明明有未替换的占位符，但没被检测到
在 Codex 对话框里说：「check_completeness 没有检测到【产品名称】这个未替换的占位符，请检查扫描文档的逻辑，确认同时遍历了所有 paragraphs 和 tables 里的 cells」
情况二：智谱审查总是通过，连明显错误也没拦截
把具体情况告诉 Codex：「check_by_zhipu 里，报价金额填了『2025年6月15日』这个日期，但智谱返回了 passed: true，请检查发给智谱的 prompt，确认字段清单格式是否正确」
情况三：智谱审查太严格，正确的内容也被标记为失败
把具体误判发给 Codex：「智谱把『¥58,000.00元』这个正确的金额标记为有问题，请修改发给智谱的 prompt，明确说明报价金额的合法格式」
情况四：API 费用问题——每份报价单都要调用智谱，费用会不会很高
不用担心。每次智谱审查一份报价单大约消耗 500-800 个 Token，用 glm-4-flash 模型的费用很低。处理 100 份报价单的智谱审查费用不到 1 元人民币。
六、这期做了什么——小结
这期你给 Agent 装上了两层自检：
- 第一层（程序规则） ：快速扫描有没有未替换的占位符，有问题直接拦截，不调用智谱
- 第二层（智谱审查） ：理解每个字段的内容是否合理，发现规则检测不到的字段错位、内容异常等问题
- 两层都通过，才保存文件
现在你的 Agent 有了真正的自我保护能力——不只是「有没有报错」，而是智谱真正读懂了报价单内容，判断填写是否正确。
坦白说，做完这个功能之后，我觉得心里踏实多了。以前批量生成报价单，总是担心万一填错了怎么办，现在有智谱帮我把关，质量有保障了。
到这里，所有模块全部做完了：
| 模块 | 文件 | AI 参与了什么 |
|---|---|---|
| 工具 | agent.py | 文件读写（无需 AI） |
| 大模型接口 | llm.py | 封装智谱 API，供所有模块调用 |
| 记忆 | memory.py | 智谱做语义理解，匹配客户描述 |
| 规划 | planner.py | 智谱分析任务，制定执行计划 |
| 自检 | validator.py | 智谱审查报价单，判断内容合理性 |
| 配置 | config.json | 长期偏好设置（无需 AI） |
现在这 6 个模块全部在终端里运行——下期我们做最后一步：把它们装进一个桌面窗口应用，有界面、有按钮、有进度条，任何人打开就能用。
下期预告： 第7期是整个系列最后的整合。我们把前6期的所有模块装进一个 tkinter 桌面窗口应用——有界面、有按钮、有进度条、有结果展示。做完之后，你把这个程序发给完全不懂技术的同事，他打开就能用，不需要任何命令行操作。
思考题： 你让智谱审查报价单时，它发现了什么你没想到的问题？还是有什么明显的错误它没发现？评论告诉我，我会在下期开头汇总。
关注公众号「AI淇橦学」，和 AI 一起成长。
有问题或建议？后台留言即可。
后台回复“Agent”，领取课程讲义文件。
