上海交通大学工程学导论课程项目:自动溶液配制与滴定智能体。
当前仓库提供项目的软件 Agent 框架。现阶段已经拆分为两个任务入口:
Solution_Preparation_Agent.py:自动溶液配制 Agent,当前主要可运行版本。Titration_Agent.py:酸碱滴定曲线自动绘制 Agent,作为后续开发入口。
命令行智能体和桌面 GUI 的完整操作步骤见 USAGE_GUIDE.md。
现阶段重点是“自动溶液配制”。DeepSeek 大模型负责理解自然语言、完成浓度计算,并通过串口向 Arduino 发送蠕动泵控制指令。
当前 Solution_Preparation_Agent.py 支持:
- 使用 DeepSeek 在线模型解析自然语言实验任务
- 根据
C1V1 = C2V2完成基础稀释计算 - 调用工具控制蠕动泵抽取酸液或去离子水
- 通过串口向 Arduino 发送真实泵控指令
- 通过同一串口按需读取 pH 计数据
- 记录当前实验台中已加入的酸液、水和总液量
泵控和 pH 采集已经集成到同一个 Arduino 固件中。GUI 会在左侧状态区自动刷新最近 pH;自动滴定和滴定曲线绘制仍将在 Titration_Agent.py 中实现。
chem_auto_desktop.py # 桌面 GUI 控制台:配液配置、自然语言、手动泵控、实时 pH、设置与日志
Solution_Preparation_Agent.py # 溶液配制 Agent:DeepSeek + 共享串口泵控/pH
Titration_Agent.py # 滴定曲线 Agent:后续开发入口
USAGE_GUIDE.md # CLI 与桌面 GUI 完整使用说明
ino/AutoLab_Combined_Controller/ # 当前必须烧录的泵控与 pH 合并固件
AutoLab_Combined_Controller.ino
ino/peristaltic_pump_v2_1/peristaltic_pump_v2_1.ino # 独立泵控测试程序
ino/Calibrated_ph_meter/Calibrated_ph_meter.ino # 独立 pH 测试程序
ino/motor_readme.md # 蠕动泵驱动说明
ino/ph_readme.md # pH 计使用与校准说明
requirements.txt # 运行依赖
requirements-dev.txt # 打包依赖
scripts/build_macos_dmg.sh # macOS DMG 打包脚本
scripts/build_windows_exe.ps1 # Windows EXE 打包脚本
正式运行 Agent 时使用合并固件:
ino/AutoLab_Combined_Controller/AutoLab_Combined_Controller.ino
Arduino 串口设置:
baud rate: 9600
line ending: Newline
泵与 Arduino 轴的约定:
- X 轴泵:酸液泵,Agent 中的
pump_id="acid" - Y 轴泵:去离子水泵,Agent 中的
pump_id="water"。当前硬件接线下 Y 轴方向与 Arduino 默认方向相反,因此 Python 端已将 water 进液映射为yo。
Python 端发送的实际指令格式来自 Arduino v2.1:
xi 600 5.000
yo 600 5.000
s
e0
status
ph
phstatus
其中 xi 表示 X 轴酸液泵进液,yo 表示当前硬件下的 Y 轴去离子水泵进液,600 是步进速度,最后一个数字是运行秒数。
合并固件持续在后台采样 pH,但默认不自动向串口输出。Python 在需要读数时发送 ph,从而避免 pH 日志与泵命令响应混杂。
当前 Solution_Preparation_Agent.py 使用 DeepSeek 的 OpenAI-compatible API 实现工具调用循环,暴露给大模型的工具包括:
pump_liquid:控制酸液泵或去离子水泵抽取指定体积;长时间运行会按安全上限自动分段run_pump_seconds:按秒运行指定蠕动泵,用于排气、预灌、清洗和标定get_lab_state:查询当前实验台状态reset_lab_state:重置 Python 端记录的实验台状态stop_pumps:停止蠕动泵,普通停止会执行防滴漏回抽get_pump_controller_status:向 Arduino 发送status并读取返回read_ph:通过合并固件按需读取当前 pH
磁力搅拌器默认常开,不由 Agent 控制。
当前代码依赖 Python 3,以及以下库:
openaihttpx[socks]pyserial
可以直接安装仓库中的依赖文件:
python3 -m pip install -r requirements.txt在 macOS 上,如果 python3 指向没有 Tk 的 Anaconda 环境,请改为:
/usr/local/bin/python3 -m pip install -r requirements.txt如果不想使用纯 CLI,可以启动桌面版控制台:
python3 chem_auto_desktop.py建议使用 Python 3.11 或更新版本。macOS 自带的 /usr/bin/python3 可能会因为系统 Tcl/Tk 版本过旧而无法启动桌面窗口;如果遇到 Tk 报错,请改用 Homebrew 或 python.org 安装的 Python。
当前 GUI 会在检测到 Anaconda 缺少 _tkinter 时自动尝试切换到
/usr/local/bin/python3。也可以直接运行:
/usr/local/bin/python3 chem_auto_desktop.py桌面版包含:
- 自然语言实验指令面板
- 配液配置与示例计算面板
- 手动泵控面板
- 左侧实时 pH 数值区
- 串口、模型、API Key 设置页
- 实验台状态与安全停止按钮
当前项目允许在 Solution_Preparation_Agent.py 中配置默认 DeepSeek API Key。GUI 的 API Key 输入框留空时会使用代码内置值;填写后会优先使用 GUI 配置,也可以通过环境变量覆盖:
AUTOLAB_API_KEY=你的DeepSeekKey python3 chem_auto_desktop.py桌面 GUI 的入口文件是:
chem_auto_desktop.py
推荐完整启动流程如下。
- 确认 Arduino 已烧录泵控与 pH 合并程序:
ino/AutoLab_Combined_Controller/AutoLab_Combined_Controller.ino
-
确认 Arduino IDE 的 Serial Monitor 已关闭。Serial Monitor 如果占用串口,GUI 会无法连接 Arduino。
-
确认硬件连接符合当前约定:
acid -> X 轴泵,Python 发送 xi
water -> Y 轴泵,当前硬件方向反向,Python 发送 yo
baud rate -> 9600
line ending -> Newline
- 安装依赖并启动 GUI:
python3 -m pip install -r requirements.txt
python3 chem_auto_desktop.py如果当前 python3 无法启动窗口,可以直接使用本机带 Tk 的 Python:
/usr/local/bin/python3 -m pip install -r requirements.txt
/usr/local/bin/python3 chem_auto_desktop.py打开 GUI 后,先进入顶部标签页中的“设置”。
需要填写或确认:
串口设备:Arduino 对应串口,例如 /dev/cu.usbmodemXXXX
波特率:9600
超时秒数:0.2
启动等待:2.0
最长运行秒数:60
API Key:可留空,留空时使用代码内置值
Base URL:https://api.deepseek.com
模型:deepseek-chat
如果不知道 Arduino 串口名,可以点击“刷新”,再从串口设备下拉框选择。macOS 上通常类似:
/dev/cu.usbmodemXXXX
/dev/cu.usbserial-XXXX
Windows 上通常类似:
COM3
COM4
填写完成后,按顺序点击:
保存设置
测试合并控制器
初始化智能体
设置会保存到本机用户目录:
~/.chemauto_agent/config.json
这个文件不会提交到 GitHub。GUI 中填写的 API Key 会优先于代码内置值。
进入“配液配置”页,可以直接查看 README 示例对应的配液方案。
默认示例:
用现有的 1 mol/L 盐酸配制 50 mL 0.1 mol/L 稀盐酸
页面会按 C1V1 = C2V2 计算:
V1 = C2 x V2 / C1 = 0.1 x 50 / 1 = 5 mL
去离子水 = 50 - 5 = 45 mL
对应泵控计划:
acid -> 加入 5 mL 1 mol/L 盐酸母液
water -> 加入 45 mL 去离子水
如果某一泵的预计运行时间超过“最长运行秒数”,pump_liquid 会自动拆分为多段串口指令,避免单次运行被安全限制拦截。
点击“填入智能体”后,GUI 会把生成的自然语言指令填入“智能体”页。
进入“智能体”页,在输入框中输入自然语言实验任务,然后点击“运行”。
示例:
用现有的 1 mol/L 盐酸配制 50 mL 0.1 mol/L 稀盐酸
Agent 会完成以下流程:
- 调用 DeepSeek 理解任务。
- 根据
C1V1 = C2V2计算酸液和水的体积。 - 调用
pump_liquid工具。 - 按当前流量标定换算泵运行时间。
- 通过串口向 Arduino 发送泵控指令。
- 更新左侧实验台状态。
智能体页也提供几个快捷按钮:
运行:执行输入框中的自然语言指令
状态:查询当前 Python 端记录的酸液、水和总液量
查询控制器:向 Arduino 发送 status
读取 pH:读取当前 pH 传感器串口输出
停止泵:发送普通停止指令
常用自然语言指令:
状态
reset
查询泵控制器状态
读取当前 pH
停止泵
让酸液泵运行 1 秒
让水泵反向运行 1 秒
用现有的 1 mol/L 盐酸配制 50 mL 0.1 mol/L 稀盐酸
进入“手动泵控”页,可以直接调用底层泵控工具,适合排气、预灌、清洗、标定和单独测试。
按体积进液:
泵:acid 或 water
体积 mL:例如 5
点击:按体积进液
此模式会使用当前流量标定自动换算运行时间,例如酸泵 5 mL 会使用 5 mL 标定点。
按秒运行:
泵:acid 或 water
运行秒数:例如 1
方向:intake 或 reverse
速度 steps/s:默认 600
点击:按秒运行
参数含义:
acid:酸液泵
water:去离子水泵
intake:进液方向
reverse:反向运行
600:步进速度,单位 steps/s
手动泵控页不需要 DeepSeek API Key,但仍然需要串口设置正确。
GUI 左侧会在任意页面只显示最近一次 pH 数值,并以约 0.5 秒间隔尽可能快地自动刷新。需要立即更新时,点击“立即刷新 pH”;“智能体”页中的“刷新 pH”按钮也会直接调用同一串口上的 pH 工具,不经过大模型。
正式使用 GUI 或同时使用泵控与 pH 时,必须烧录合并固件。合并固件已经内置 ph_meter_2.0 的 RawAvg 分段校准;ino/ph_meter_2.0/ph_meter_2.0.ino 仅用于单独测试 pH 计。pH 模块接在当前代码约定的引脚:
firmware = ino/AutoLab_Combined_Controller/AutoLab_Combined_Controller.ino
PH_SENSOR_PIN = A3
baud rate = 9600
读取步骤:
自动刷新:打开 GUI 后自动开始
手动刷新:点击左侧“立即刷新 pH”或智能体页“刷新 pH”
GUI 会解析 Arduino 报告中的 RawAvg,按 ino/ph_meter_2.0/ph_meter_2.0.ino 的三点分段参数重新计算 pH,并应用代码中的 PH_DISPLAY_OFFSET 作为最终显示修正。界面只显示最终 pH 数值,不显示稳定状态、电压或更新时间。
泵控和 pH 读取必须由同一个 Agent/GUI 进程完成。不要同时打开 Arduino IDE Serial Monitor,也不要同时启动两个 Python 控制程序,否则它们会争用同一个串口。
当前 Titration_Agent.py 仍是后续开发入口,完整自动滴定序列尚未接入 GUI。
GUI 左侧会持续展示:
酸液:Python 端累计加入的 acid 体积
去离子水:Python 端累计加入的 water 体积
总液量:acid + water
实时 pH:最近一次 pH 数值
最近指令:最近一次发送给 Arduino 的串口命令
安全按钮:
停止泵:发送普通停止指令 s,执行正常停止逻辑
紧急停止:立即发送 e0,不等待 Arduino 返回
查询控制器:发送 status
刷新状态:读取 Python 端实验台状态
重置记录:清零 Python 端记录,不会抽液,也不会倒液
如果泵动作异常,优先点击“紧急停止”。
“运行日志”页会显示:
任务开始和结束时间
Python 端打印的串口通信记录
Arduino 返回内容
工具执行失败原因
如果实验没有按预期运行,优先查看这个页面。常见问题一般是串口被占用、串口名错误、Arduino 没有烧录对应程序、API Key 未填写。
通常是当前 Python 没有 Tk 支持。请直接使用本机 python.org Python:
/usr/local/bin/python3 chem_auto_desktop.py检查:
Arduino 是否连接
串口名是否正确
Arduino IDE Serial Monitor 是否关闭
是否有其他程序占用串口
检查“设置”页是否填写了 API Key,或者使用环境变量:
AUTOLAB_API_KEY=你的DeepSeekKey python3 chem_auto_desktop.py当前 Python 端不强依赖 Arduino 必须返回日志。只要串口写入成功,程序会根据运行时间等待泵动作完成。可以用“查询控制器”进一步检查 Arduino 状态。
确认烧录的是 AutoLab_Combined_Controller.ino,而不是独立泵控或独立 pH 测试程序。关闭 Serial Monitor 和其他串口程序后,只启动一个 Solution_Preparation_Agent.py 或 chem_auto_desktop.py 进程。
Agent 连接串口时会自动检查 status 和 phstatus。如果 Arduino 仍运行纯泵控固件,
程序会直接提示重新烧录合并固件,不再以“泵可用、pH 不可用”的半功能状态继续运行。
左侧状态只是 Python 端累计记录。点击“重置记录”只会清零软件记录,不会改变真实烧杯中的液体。正式实验前请确认烧杯状态和软件状态一致。
如果只想使用原来的命令行入口,可以按下面步骤运行。
将 ino/AutoLab_Combined_Controller/AutoLab_Combined_Controller.ino 上传到 Arduino,并确认 Serial Monitor 已关闭,否则 Python 可能无法打开串口。
默认串口配置在 Solution_Preparation_Agent.py 中:
SERIAL_PORT = os.getenv("AUTOLAB_SERIAL_PORT", "/dev/cu.usbmodem141011")
SERIAL_BAUD_RATE = int(os.getenv("AUTOLAB_SERIAL_BAUD_RATE", "9600"))如果 Arduino 串口不是 /dev/cu.usbmodem141011,可以用环境变量覆盖:
AUTOLAB_SERIAL_PORT=/dev/cu.usbmodemXXXX python3 Solution_Preparation_Agent.pypython3 Solution_Preparation_Agent.py程序启动后会进入 DeepSeek 在线工具调用模式。第一次真正调用泵控工具时,Python 会打开串口并发送 Arduino 指令。
注意:当前硬件测试中,Arduino 串口可以打开并接收命令,但不一定会返回文本回显。因此 Python 端以“串口写入成功 + 等待运行时间结束”作为泵控工具完成条件,不依赖 Arduino 必须返回日志。
本仓库已经加入 PyInstaller 打包脚本,可生成 GitHub Release 可用的桌面程序。
在 macOS 上运行:
bash scripts/build_macos_dmg.sh如果本机默认 python3 不是你想用于打包的版本,可以指定:
PYTHON_BIN=/usr/local/bin/python3 bash scripts/build_macos_dmg.sh产物位置:
dist/ChemAuto-Agent-macOS.dmg
在 Windows PowerShell 中运行:
.\scripts\build_windows_exe.ps1如果需要指定 Python:
$env:PYTHON_BIN="C:\Path\To\python.exe"
.\scripts\build_windows_exe.ps1产物位置:
dist\ChemAuto-Agent-Windows.zip
压缩包内包含 ChemAuto-Agent.exe。
推送形如 v0.1.0 的 tag 后,GitHub Actions 会自动构建 macOS DMG 和 Windows EXE,并发布到 GitHub Release:
git tag v0.1.0
git push origin v0.1.0也可以在 GitHub Actions 页面手动运行 Build desktop release workflow。
用现有的 1 mol/L 盐酸配制 50 mL 0.1 mol/L 稀盐酸
查询泵控制器状态
让酸液泵运行 1 秒
停止泵
状态
reset
当前 Python 端采用时间控制:
运行时间 = 目标体积 / 泵流速
当前已完成 5 mL 和 10 mL 两组标定。Python 端会根据目标运输体积选择更接近的标定点:
酸泵 acid:
5 mL -> 0.46 mL/s
10 mL -> 0.44 mL/s
水泵 water:
5 mL -> 0.50 mL/s
10 mL -> 0.46 mL/s
例如酸泵需要运输 6 mL,由于 6 更接近 5 而不是 10,因此运行时间为:
6 / 0.46 = 13.04 s
如果目标体积刚好位于两个标定点中间,例如 7.5 mL,程序默认选择 10 mL 标定点,因为较长时间标定通常受启动斜坡影响更小。
由于 Arduino 泵控程序带有加速斜坡,过短运行时间的剂量误差会比较明显。当前 Python 端会对低于 0.8 s 的泵运行给出提示;正式实验应优先完成流量标定,并避免依赖极短时间脉冲获得高精度体积。
后续更严谨的方案是改为“步数-体积”标定,即记录每个泵的 steps_per_ml,再由 Python 直接按目标体积换算步数。
- 完成酸液泵和水泵的流量标定
- 将溶液配制从时间控制升级为更可靠的步数-体积控制
- 在
Titration_Agent.py中复用当前 pH 读取工具并实现自动采样序列 - 实现酸碱滴定曲线自动采集与绘图
- 增加实验日志保存和异常保护机制