大家好，我是AI淇橦学。
前六期，我们逐步做出了五个模块：
- 第3期
agent.py：三个工具函数——读文件、填内容、保存 - 第4期
llm.py+memory.py：接入智谱 API；客户知识库，智谱做语义搜索 - 第5期
planner.py：智谱分析批量任务，自主制定执行计划 - 第6期
validator.py：两层自检——规则检查完整性，智谱审查内容合理性
这五个模块现在都能在终端里独立跑通，智谱也真正参与到了每个关键决策里。但「能在终端跑通」和「真正能用」之间，还差最后一步——你需要记住命令、手动输入参数，不懂技术的人根本没法用。
这期我们做最后的整合：把所有模块装进一个 tkinter 桌面窗口应用，有界面、有按钮、有进度条、有结果展示。做完之后，你把这个程序发给完全不懂技术的同事，他打开就能用。
这期结束时，你会得到：
- 一个可以双击打开的桌面窗口应用
- 界面分三个区域：操作区（选文件、输入客户）、进度区（实时进度和智谱分析日志）、结果区（汇总报告）
- 支持单个模式和批量模式，全程不需要打命令行
- 通过 MVP 验收清单，确认这个 Agent 真正做完了
一、整合前的关键一步：确认模块间数据格式对齐
很多人整合时的第一反应是「把代码全复制到一起跑一下看看」——结果跑出一堆报错，不知道从哪里改起。
正确的做法是：先列出每个模块的输入和输出格式，逐一对比，找出不一致的地方，再动手整合。
我们的五个模块，核心数据交换点是这样的：
坦白说，这个数据格式对齐的工作我在设计模块时就想好了，所以整合时比较顺利。如果你在实际操作中发现对不上的，用 Codex 描述具体问题，它都能帮你修复。
二、界面设计：三个区域，够用就好
桌面界面不需要做得漂亮，第一版只需要三个区域，每个区域职责清晰：
区域一：操作区（顶部）
- 模板文件路径 + 「选择文件」按钮
- 运行模式切换：单个客户 / 批量模式
- 单个模式：客户描述输入框（支持自然语言）+ 产品名称、型号、金额输入框
- 批量模式：批量任务文件路径 + 「选择文件」按钮
- 「开始执行」按钮 + 「停止」按钮
区域二：进度区（中部）
- 进度条：显示当前处理进度
- 日志窗口：实时滚动显示每一步，包括智谱的分析过程和自检结果
- 「停止」按钮：批量执行中途可以随时叫停
区域三：结果区（底部）
- 执行结果摘要：成功 X 份 / 自检失败 X 份 / 执行失败 X 份
- 「打开输出文件夹」按钮
- 「查看汇总报告」按钮
我觉得这个设计够用了——不追求花哨，只追求实用。
三、实操开始：用 Codex 做桌面窗口应用
这期的实操分 4 步：
- 用 Codex 生成 tkinter 界面主文件
- 安装依赖并运行
- 逐项功能测试
- 真实用户测试
第一步：生成 tkinter 界面主文件
打开 Codex，新建文件 app.py，打开 AI 对话框（Ctrl+L / Cmd+L），发送提示词（提示词内容后台回复“Agent‘，获取）。
Codex 会生成一个完整的 app.py，这个文件比之前几期的都要长——tkinter 界面代码本身就比较多，不用担心，跟着后面的步骤验证就好。
💡 如果 Codex 一次生成的代码不完整（提示「继续？」），在对话框里说「继续生成剩余部分」，它会接着补完。
第二步：安装依赖并运行
tkinter 是 Python 内置的，不需要额外安装。确认之前所有依赖都装好了：
1pip install python-docx requests
然后运行：
1python app.py
如果一切正常，会看到桌面窗口弹出，日志区域显示：
12✅ 配置加载完成
✅ 已加载 3 个客户，智谱语义搜索就绪
第三步：逐项功能测试
测试一：选择模板文件
点击「选择模板」按钮，找到 templates/报价单模板.docx，选择后路径显示在输入框里。
测试二：单个客户模式——用自然语言描述客户
- 模式选「单个客户」
- 客户描述输入「南山区那家做传感器的」（故意用模糊描述，测试智谱语义理解）
- 产品名称「工业传感器套件」、型号「XS-2000B」、金额「¥58,000元」
- 点击「开始执行」
- 观察日志窗口
期望看到智谱的完整处理过程：
结果区显示「✅ 完成：成功 1 份」，「打开输出文件夹」和「查看汇总报告」按钮变为可点击。
测试三：批量模式
- 切换到「批量模式」，确认界面输入行正确切换
- 选择
批量任务.json - 点击「开始执行」
- 日志窗口显示智谱分析计划的过程
- 弹出确认对话框，点「是」
- 观察进度条从 0 推进到 100%，日志实时滚动
期望结果：3 份报价单全部完成，结果区显示汇总，output 文件夹里有 3 个新文件。
测试四：智谱自检拦截测试
把 批量任务.json 里某个任务的 unit_price 改成日期字符串「2025年6月15日」，再跑一次批量模式。
期望：日志里显示智谱发现了报价金额字段填了日期，该任务被跳过，其他任务正常完成。
测试五：停止按钮
批量模式执行中途点「停止」，确认程序停下，已完成的文件保留在 output 文件夹。
测试六：错误处理
- 不选模板文件直接执行 → 弹出警告
- 客户描述留空直接执行 → 弹出警告
- 输入「火星科技公司」 → 日志提示智谱未找到匹配客户
第四步：做一次真实用户测试
这是这期最重要的环节——很多人会跳过，但跳过了就错过了最有价值的反馈。
找一个没有参与过这套课程的人（同事、朋友都行），让他完成这个任务：
「用这个程序，给深圳科技有限公司生成一份报价单，产品是工业传感器套件，金额 58000 元，保存到 output 文件夹。」
当他卡住的时候，不要说话。 只观察和记录——他在哪里停下来了、他尝试了什么、为什么不知道该怎么做。
测试结束后，把卡点整理成一段话发给 Codex，让它修复界面问题。
根据你自己测试时发现的真实卡点调整内容，发给 Codex 修复。
四、遇到问题怎么办
情况一：运行 python app.py 窗口一闪而过或直接报错
把终端里的完整报错复制，发给 Codex：「运行 app.py 时报错，错误信息：[粘贴报错内容]，请修复」
情况二：点「开始执行」后界面卡死
在 Codex 对话框里说：「点击开始执行后界面卡死无法操作，请检查 run_single 和 run_batch 是否在独立的 threading.Thread 里运行」
情况三：日志不实时更新，执行完才全部显示
在 Codex 对话框里说：「日志窗口不实时更新，请检查 check_queue 是否通过 root.after(100, self.check_queue) 循环调用」
情况四：批量模式确认弹窗有问题
在 Codex 对话框里说：「批量模式的确认弹窗点确认后程序卡住不继续执行，请检查线程同步逻辑，messagebox 必须在主线程里调用」
五、MVP 验收清单
做完之后，用这张清单逐项确认。验收标准必须是「是/否」，不接受「差不多」「基本上」这种模糊答案。
6项通过5项，MVP 完成。 允许有1项「尚待优化」，但核心流程（第1项）必须通过。
六、这期做了什么——小结
这期你完成了整个系列最后的整合：
app.py：tkinter 桌面窗口，把五个后端模块全部接入- 后台线程运行所有智谱 API 调用，界面不卡死
- 日志窗口实时显示智谱的分析过程，用户看得见 AI 在做什么
- 通过真实用户测试，修复了界面引导问题
- 通过 MVP 验收清单，确认核心功能完整
你的项目最终文件结构：
123456789101112131415sales-agent/
├── templates/
│ └── 报价单模板.docx ← 报价单模板
├── output/ ← 所有生成的报价单
├── customers/
│ ├── 客户资料.json ← 客户知识库
│ └── 报价历史.json ← 操作历史记录
├── config.json ← 长期配置（含 API Key）
├── 批量任务.json ← 批量任务清单
├── agent.py ← 工具模块（第3期）
├── llm.py ← 智谱 API 封装（第4期）
├── memory.py ← 记忆 + 客户搜索（第4期）
├── planner.py ← 智谱规划 + 批量执行（第5期）
├── validator.py ← 两层自检（第6期）
└── app.py ← 桌面界面（第7期）
6个 Python 文件，每个只做一件事，智谱贯穿其中——搜索客户、制定计划、审查结果，组合在一起是一个完整的、有真正 AI 大脑的销售报价单 Agent。
坦白说，做到这一步，我觉得挺有成就感的。从一个模糊的想法，到一个可以真实运行的、有界面的应用程序，这个过程本身就很值得。
下期预告： 第8期是这个系列的最后一期。我不讲新的技术内容——我们来做两件事：第一，把8期学到的东西整理成你自己的「Agent 知识地图」；第二，规划接下来3个月怎么继续迭代这个 Agent，以及怎么用同样的方法论做第二个 Agent。一个系列结束，不是「学完了放一边」，而是「下一段路的起点」。
思考题： 你把做好的应用给身边的人试用了吗？他在哪里卡住了，你是怎么发现这个问题的？评论告诉我，我会在第8期开头汇总大家遇到的最常见问题。
关注公众号「AI淇橦学」，和 AI 一起成长。
有问题或建议？后台留言即可。
