身在内网,开发照常。
让没有公网出口的内网开发机,用上先进的云端大模型。
一根串口线接上 ESP32-S3,电脑上用原生模型接口继续原来的开发流程。
Windows 10/11 · 单文件 Agent · 不创建虚拟网卡 · OpenAI / Anthropic 原生接口 · MIT
这是什么 · 为什么需要它 · 设计出发点 · 工作方式 · 核心亮点 · 使用方式 · 当前状态 · 从源码构建 · 安全与合规边界
内网开发机上,日常写代码离不开大模型,但"让这台机器用上大模型"往往不是技术问题,而是通道问题。
uart2llm 的做法是:不碰电脑的网络,把出口搬到一根串口线另一端的 ESP32-S3 上。
- 电脑侧只多出一个串口设备:不装虚拟网卡、不改路由表、不注册网络驱动、不创建系统服务、不添加防火墙规则。
- 联网由设备完成:ESP32-S3 用 Wi-Fi 连接已配置的上游模型服务,只做 DNS 解析和 TCP 转发。
- 明文和密钥留在电脑上:TLS 在电脑进程内建立并终结,串口里流动的只有密文。
- 保留原生协议:一个本地 OpenAI Base URL 接收 Chat Completions 与 Responses,另提供 Anthropic 原生接口;支持自定义 Base URL 的客户端可以直接接入。
你的工具(IDE / 聊天客户端 / 脚本)
│ http://localhost:8765/v1 OpenAI 兼容
▼
uart2llm Agent(单个 EXE,Go)
│ · Chat / Responses / Anthropic 白名单转发
│ · 在电脑上完成 TLS —— 明文只存在于本机进程内
│ · 串口多路复用 / 流控 / 取消
▼
USB 串口(COMx)
▼
ESP32-S3(配套硬件)
│ · 只做 DNS + TCP,转发密文
│ · Wi-Fi 连接上游
▼
已配置的上游模型服务(官方或兼容供应商)
内网开发环境有一个结构性矛盾:开发离不开大模型,但开发机往往没有可用的公网出口。
常见替代路径的代价也不小:
| 路径 | 代价 |
|---|---|
| 内网自建推理服务 | 受内网算力限制,通常只能跑内网部署的模型,与先进云端模型的能力差距明显 |
| VPN / 虚拟网卡 / 私自加代理 | 新增网络接口、改动路由与系统网络配置,属于明显的对外联网行为 |
| 申请开通公网出口 | 流程长、审批不确定,解决不了"现在就要用"的问题 |
问题在于:这台电脑缺的从来不是算力,而是一条不需要改动系统网络形态的对外通道。
uart2llm 的通道选择不是随意的,而是针对内网开发机的一个工程约束:
- 让电脑自己联网,就要动电脑的网络。 VPN、虚拟网卡、代理都会新增网络接口、改动路由,或者产生新的对外连接。这是整条链路上唯一必须"改系统"的部分,也是内网管控真正盯住的部分。
- 串口本来就在这些机器上正常工作。 硬件调试与烧录、串口打印机、硬件远程控制卡(KVM)都要用串口,系统里存在一个 COM 设备是常态,不需要为它改变任何网络配置。
终端管控的关注点通常也很集中:大容量存储设备的接入与向外拷贝、未注册网卡或网卡状态变化、明显的数据外发行为。相比之下,串口、键盘鼠标、USB 耳机、蓝牙这类外设在多数配置下被当作"正常工作负载"处理——但是否产生告警最终取决于你所在环境的监控软件与组织策略,本项目不承诺免告警。
所以设计目标是:把"联网"这件事从电脑的网卡上移走,交给一根 USB 线另一端的小盒子。
- 电脑侧不新增网络接口、不改路由、不注册网络驱动;
- 对操作系统而言,这台电脑只是接了一个串口设备;
- 真正联网的是 ESP32-S3,它不持有上游 API key,也看不懂流经它的字节。
这个项目的创新点:用一根串口线,为没有公网出口的电脑补上对外模型访问能力——不改变电脑自身的网络形态,也不把明文和密钥交给外部硬件。
同时必须讲清它的边界:uart2llm 不修改、不关闭、不绕过任何安全软件,也不隐藏自身。 没有注入、没有提权、没有进程伪装;Agent 是一个可见的普通用户态进程,设备是一个可见的串口设备,链路上也没有为规避检测而设计的特性。请在允许使用的设备与外部服务范围内使用,并自行确认符合组织的安全政策与适用法律,详见安全与合规边界。
一次请求的完整旅程:
- IDE 或工具向
http://localhost:8765/v1/chat/completions发起一个标准 OpenAI 请求,用本地 token 认证。 - Agent 校验路径在白名单内,取出配置好的上游地址与凭据,在电脑上发起并终结 TLS。
- 加密后的字节流被封成串口帧,经 COM 口送往 ESP32;链路层负责分帧、确认、去重、流控、多路复用与取消。
- ESP32 解析 DNS 并转发 TCP,把密文送上 Wi-Fi 可达的上游服务——它看不到请求内容。
- 上游响应原路返回电脑,由 Agent 解密后以 SSE 流式(或非流式)交回客户端。
两个视角,同一根线:
| 视角 | 看到的东西 |
|---|---|
| 操作系统与监控软件 | 一个普通的 USB 串口设备(COMx),系统网络配置没有任何变化。原生 USB Serial/JTAG 固件下该设备同时提供调试接口 |
| 数据本身 | 密文:串口里只有 TLS 记录,prompt、工具参数、文件内容、SSE 事件和 API key 都不上串口 |
不安装虚拟网卡、不修改系统路由、不注册网络驱动、不创建系统服务、不添加防火墙规则。Agent 只是一个使用串口的普通用户态进程。结果是:它不会与既有的网络配置、VPN 客户端或网络策略管理器冲突,卸载时也不留残渣——因为系统网络层面本来就没有被改动过。
这是与"把请求交给外置设备处理"最本质的区别。TLS 连接在电脑上建立和终结,ESP32 只提供一条到上游的 DNS + TCP 通道,它无法解析 prompt、工具参数、文件内容或 SSE 事件,也无法读取你的上游 API key。结果是:提示词与响应正文只在电脑进程内出现,对外联网能力被限制在一个不持有秘密的转发器里;设备上只保留 Wi-Fi 凭据与设备配置,即使设备被别人拿走,也没有可提取的对话内容或上游 key。
日常运行只需要一个 uart2llm-agent-windows-x64.exe:Web 管理页、系统托盘和 CLI 全部内置,不需要安装 Python、Node.js、Go 或 ESP-IDF,也不需要联网获取运行依赖。提前把 EXE、设备工具和固件拷进内网,使用发布包时整个部署过程不需要外网。
首次源码构建需要拉取依赖,但使用不需要——两者的区别见发行说明。
一个 OpenAI 地址和当前密钥同时服务 Chat Completions、Responses、模型、文件与微调任务接口;Agent 按请求资源路径自动选择原生上游路径。Anthropic Messages、模型与文件白名单路由保持独立配置,可共享当前 OpenAI 密钥或使用专用密钥。
Agent 按原协议透传请求、原生错误与 SSE 事件,不在协议间转换,也不虚构上游能力。能力发现只使用不生成内容的 OPTIONS,并结合真实客户端请求的结果;“已通告”不等于生成接口“已验证”。某项路由已实现不等于每个供应商都支持该资源;模型列表、文件、compact、token count 或搜索等能力仍以上游实际响应为准。实现边界见架构说明。
| 环节 | 设计 |
|---|---|
| 设备配对 | Protocomm Security 2 握手,每台设备单独生成配对凭据 |
| 配对文件 | 保存在仓库之外,不提交 Git、不随安装包分发 |
| 上游 API key | 存放在 Windows 凭据管理器,不写入配置文件 |
| key 输入方式 | 管理页面密码框,或 CLI stdin(credentials set-upstream);不接受命令行明文值 |
| 本地访问控制 | 管理页面仅回环监听、面向本机用户;模型 API 使用独立的本地 token |
| 日志 | 默认不记录请求正文与秘密 |
结果是:模型 API 的 token、设备配对密码、上游 key 三者互不通用,任何一份泄露都不会直接等于另外两份泄露。
设备配置采用暂存 → 应用 → 确认流程。应用 Wi-Fi 后先检查是否取得 IP,再在 30 秒窗口内确认,超时自动回滚;配置变更前会等待活动请求结束。结果是:一次写错的网络配置不会把设备变成砖。
链路层实现分帧、确认、去重、流控、多路复用与取消,最多四条上游请求并发——也就是同时最多四个模型会话;第五个请求会立刻拿到 503 capacity_exceeded 与 Retry-After,而不是排队卡死等超时。
管理、遥测、日志、OTA 与四条 TCP 通道分别排队,链路层对端到端慢消费者施加有界队列背压,而不是无限缓冲。结果是:多个 IDE 会话同时工作时不会互相拖垮,中途取消后连接立即失效并可继续发起新请求。
写操作不自动重试——串口拔线或设备重启会让旧请求失败,后台不会重放可能已经发送出去的生成、上传或创建任务。
- 图形化数据看板:请求数量、成功与失败、响应时间、吞吐及 Token 用量。
- 设备实时状态:Wi-Fi 信号强度、IP、DNS、断开原因、重连次数、各通道状态与 TCP_NODELAY。
- 托盘快捷管理:查看连接与模型统计,暂停、恢复和管理服务。
统计以当前进程实际采集的数据为准,缺失值不视为零。
五步走完:
| 步骤 | 做什么 | 详细位置 |
|---|---|---|
| 1 | 准备硬件与文件:ESP32-S3(16 MiB Flash、8 MiB Octal PSRAM)、3.3 V USB-UART 转换器、Agent EXE | 第 1 步 |
| 2 | 烧录固件,并生成本机专属配对凭据 | 第 2 步 |
| 3 | 启动 Agent,连接串口并导入 pairing.json |
第 3 步 |
| 4 | 在管理页面填写 Wi-Fi,并配置要使用的上游协议与密钥 | 第 4 步 |
| 5 | 在客户端填写对应协议的本地 Base URL 和本地 token | 第 5 步 |
| 项目 | 要求 |
|---|---|
| 电脑 | Windows 10/11 x64 |
| 设备 | ESP32-S3,16 MiB Flash、8 MiB Octal PSRAM |
| 连接 | GPIO UART(外接 3.3 V USB-UART 转换器)或原生 USB Serial/JTAG |
| 网络 | ESP32 所连 Wi-Fi 必须能直接访问上游服务 |
| 文件 | 日常运行只需要 Agent EXE;首次烧录另需固件与设备工具(见发行说明下载项) |
GPIO UART 默认 TX17/RX18,需交叉接线并共地(ESP TX → 转换器 RX,ESP RX → 转换器 TX,GND ↔ GND)。原生 USB Serial/JTAG 需要烧录独立的 USB 验证固件,它与生产 GPIO UART 固件不同,两种构建的 bootloader、分区表与应用不可混用。
dist\uart2llm.exe与uart2llm-agent-windows-x64.exe是同一个程序的两种来源:前者是源码构建产物(见从源码构建),后者是发布包里的单文件 EXE。下面的命令对两者都适用,按你的实际文件名替换即可。
每台设备单独生成凭据,COMx 替换为实际烧录口。推荐用发布包的设备工具,它不依赖 ESP-IDF:
在解压后的固件目录中执行(C:/uart2llm-tools 替换为你的工具解压目录):
C:/uart2llm-tools/tools/provision-device.exe --output "$env:USERPROFILE/uart2llm-device-private"
C:/uart2llm-tools/tools/esptool.exe --chip esp32s3 --port COMx write-flash --flash-mode dio --flash-size 16MB --flash-freq 80m 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0xf000 ota_data_initial.bin 0x20000 uart2llm.bin 0x12000 "$env:USERPROFILE/uart2llm-device-private/pairing.bin"从源码构建固件时,改用 ESP-IDF 环境:
python scripts/provision-device.py --output "$env:USERPROFILE\uart2llm-device-private"
idf.py -C firmware -p COMx flash
python -m esptool --chip esp32s3 --port COMx write-flash 0x12000 "$env:USERPROFILE\uart2llm-device-private\pairing.bin"pairing.json 与 pairing.bin 保存在仓库外,不要提交或分享。重新烧录配对分区会更换设备配对身份。
最简单的方式是双击 EXE:它会自动启动后台、进入系统托盘并打开管理页面;重复启动会复用已有后台。也可以用命令行:
.\dist\uart2llm.exe init # 初始化配置目录与本地 token
.\dist\uart2llm.exe start # 启动后台(detached)
.\dist\uart2llm.exe ports # 列出可用串口
.\dist\uart2llm.exe connect --port COM5 --baud 115200
.\dist\uart2llm.exe pair "$env:USERPROFILE\uart2llm-device-private\pairing.json"
.\dist\uart2llm.exe status # 查看运行状态RTS/CTS 硬件流控可加 --rtscts。GPIO UART 每次启动回到 115200/8N1/无流控,连接后可协商提高速率;原生 USB Serial/JTAG 路径不受波特率设置影响——给 COM 端口设 2,000,000 波特率不会提高 USB 物理速率。
后台会独占串口,烧录前先断开后台的串口连接,否则烧录会失败。
打开管理页面 http://localhost:8766,在分组表单中填写:
| 分组 | 填写内容 |
|---|---|
| 网络 | Wi-Fi SSID、密码(可先扫描可用网络);固件支持时可启用 4G 并选择 Wi-Fi / 4G 优先级 |
| OpenAI | Chat Completions 与 Responses 共用的地址(如 https://api.deepseek.com 或 https://api.openai.com/v1)和当前 API key |
| Anthropic(默认关闭) | 精确命名空间:https://api.deepseek.com/anthropic/v1 或 https://api.anthropic.com/v1;可共享当前 OpenAI key 或使用专用 key |
上游 key 也可以在命令行写入 Windows 凭据管理器:
.\dist\uart2llm.exe credentials set-upstream < key.txt应用网络设置后检查 Wi-Fi 或 4G 任一上行是否已取得 IP,并在 30 秒内确认;超时自动回滚。所选上行必须能直连上游,电脑时间与根证书需支持 TLS 验证。4G 模块、接线、APN 与 USB/UART 限制见蜂窝网络指南。
| 客户端用途 | 本地 Base URL |
|---|---|
| OpenAI(Chat Completions / Responses / Codex) | http://localhost:8765/v1 |
| Anthropic SDK | http://localhost:8765/anthropic(SDK 自行追加 /v1) |
| Anthropic 直接 HTTP / Harness 原生搜索 | http://localhost:8765/anthropic/v1 |
API key 使用下面命令输出的本地 token;模型应从对应协议的上游列表中选择。
.\dist\uart2llm.exe token api
- 不要把设备配对密码当作 API key。
- 部分客户端要求地址不带
/v1,请按该客户端的拼接方式配置,避免出现/v1/v1。- 工具调用在客户端执行。Agent 只转发已列入白名单的模型协议路由,不是通用网络代理;客户端自己的插件下载与任意网页请求不会自动经过 ESP32。
uart2llm - UART OpenAI gateway
Commands:
init | serve | start | stop | status | tray | ports | version | licenses
connect --port COM3 --baud 115200 [--rtscts]
pair pairing.json
token api|admin
credentials set-upstream [--protocol openai|anthropic] < key.txt
config get|schema|confirm|rollback|set patch.json
firmware firmware.bin
admin METHOD /path [json-file|-]
Configuration directory: UART2LLM_DATA_DIR or %APPDATA%/uart2llm.
API defaults to http://localhost:8765/v1; management to http://localhost:8766.
还可以用 uart2llm help 查看同一份说明。模型 API 默认 http://localhost:8765/v1,管理页面默认 http://localhost:8766;配置目录默认为 %APPDATA%\uart2llm,可用环境变量 UART2LLM_DATA_DIR 覆盖。
credentials set-upstream 的当前名称使用 openai 或 anthropic;chat 与 responses 仍作为兼容别名接受,统一模式下都指向当前 OpenAI 凭据槽。
- 关闭浏览器不会停止代理。停止请用托盘退出或
uart2llm.exe stop。 - 串口拔线或设备重启会使旧 TCP/TLS 请求失败,重连后接受新请求;后台不会自动重放写操作。
- 升级前先结束活动请求,选择与连接方式匹配的固件镜像。候选固件需启动自检确认;SHA-256 与格式检查不等同于发布者签名,默认不烧写 Secure Boot / Flash Encryption eFuse。
| 现象 | 原因与处理 |
|---|---|
客户端报 /v1/v1 或 404 |
客户端自己会补 /v1,Base URL 里去掉 /v1 再试 |
| 模型 API 返回 401 | 用了设备配对密码,或用了上游 key。这里要填 token api 输出的本地 token |
同时开多个会话时返回 503 capacity_exceeded |
链路上限为四条并发上游请求。稍后重试,或在客户端侧限制并发 |
| 烧录失败 / 找不到端口 | 后台正独占串口,先 \dist\uart2llm.exe stop 或断开连接 |
| 应用 Wi-Fi 后设备失联 | 30 秒内没有确认,配置已自动回滚;重新连接后检查 SSID、密码与信道 |
| 上游连接失败 | ESP32 所连 Wi-Fi 必须能直连上游;同时检查电脑时间与根证书是否支持 TLS 验证 |
| 某些接口返回 404 | 本地路由不会虚构上游能力;已观测到部分供应商不实现某些文件、微调或扩展资源,见验证状态 |
| 模型目录为空或与预期不符 | 模型目录来自所选服务的上游。先用管理页面的“查看模型目录”确认通过 ESP32 可见的清单;目录成功不代表生成资源已经验证 |
Harness web_search 与 web_fetch 表现不同 |
原生 Anthropic 搜索已经由 /anthropic/v1 路由验证;通用 web_fetch 仍由客户端插件自行联网,不在模型协议转发范围内 |
当前发布为 v0.2.0-preview.2 预览版,全功能验收尚未通过。首次使用可在 Release 直接下载 uart2llm-windows-x64-offline.zip,内含 Agent EXE、ESP32 固件、配对与烧录工具及使用说明,无需拉取源码。
下面所有结论都来自特定开发设备、版本与负载,不是对任意模型、客户端或硬件的兼容保证;某项"已验证"只代表该项在它的测试范围内通过。
已验证(在各自测试范围内):
- 主机协议、CRC/去重、四路容量、取消、网关转发、安全握手与管理 API 有自动化测试。
- Windows 原生 USB Serial/JTAG 链路已通过 ESP32 实板测试,含双向大块校验、背压、配置回滚与 Wi-Fi 恢复。该结论不替代外接 GPIO UART 的接线、波特率与 RTS/CTS 验收。
- 已通过本地网关调用真实模型,覆盖 SSE、文件传输及客户端代理任务。
- 已在 DeepSeek Harness Web 中运行真实会话:standard 27 个工具中 25 个成功执行,子代理另执行了
structured_output。 - Harness 原生 Anthropic
web_search已通过 ESP32 实测:上游返回 8 个搜索来源,最终回答引用其中 2 个。该结果只证明本次上游、模型与客户端组合可用,不代表任意搜索请求都成功。 - 容量冲突实验:四个主会话加四个标题请求超过四路上限,加入客户端有界调度后,最终 8/8 请求成功、活动峰值 4,中途取消后可继续请求。这是该次实验的结论,不是持续保证。
尚未通过:
| 项目 | 状态 |
|---|---|
Harness web_fetch |
现有插件使用电脑 HTTP,ESP32 通道未提供 |
| Harness 页面交互与其他预设 | 后台认证接口已验证;浏览器完整交互及 PTC/minimal/cordis 预设尚未验收 |
| 全部上游 API 语义 | 上游各异;已观测到 DeepSeek 部分文件与微调操作返回 404 |
| Responses / Anthropic 完整客户端矩阵 | 原生路由已实现;Codex、Harness 与上游能力的当前验收边界见验证状态 |
| 电脑物理无其他网络出口 | 独立物理隔离验收未完成 |
| 24 小时四路混合负载 | 未完成 |
| 拔线、物理掉电、升级掉电恢复 | 完整矩阵未完成 |
| SPI / Linux / macOS | 首阶段不提供 |
完整结论与复验方法见验证状态。
运行不要求开发工具;首次源码构建需要下载锁定依赖,不能称为离线安装。
| 组件 | 构建环境 |
|---|---|
| 后台 | Go ≥ 1.24 |
| Web | Node.js 22.12+、npm |
| 原生 GUI(可选) | CMake ≥ 3.24、C++17、wxWidgets 3.2.8 |
| 固件 | ESP-IDF 6.0.1 及配套 Python 与工具链 |
| 离线工具 | Python 3.11 |
| 安装程序与发布包 | PowerShell 7、NSIS |
./scripts/build-ui.ps1
go test ./...
go vet ./...
New-Item -ItemType Directory -Force dist | Out-Null
go build -trimpath -ldflags "-s -w -X main.version=0.2.0-dev" -o dist/uart2llm.exe ./cmd/uart2llm上面得到的是开发版(版本号 0.2.0-dev)。要生成与发布包同源的版本化产物,用 ./scripts/build-agent.ps1 -Version 0.2.0-preview.1,输出在 dist/release。
固件(在 ESP-IDF 6.0.1 环境中):
idf.py -C firmware set-target esp32s3
idf.py -C firmware menuconfig # 在 "uart2llm board wiring" 配置 GPIO
idf.py -C firmware build无需硬件的完整检查:
go test ./... && go vet ./...
npm --prefix web ci && npm --prefix web test
node --test integrations/deepseek-harness/scheduler.test.mjs
python -m unittest discover -s scripts -p "*test*.py"
python scripts/check-source.py详见构建指南。
| 我想要… | 文档 |
|---|---|
| 烧录、配对和接入客户端 | 首次使用 |
| 下载单 EXE 和设备工具 | 发行说明 |
| 编译源码和生成 Windows 包 | 构建指南 |
| 理解模块边界 | 架构与项目结构 |
| 查看实际验证与未完成项 | 验证状态 |
| 调用管理 API | 接口契约 |
| 修改协议或固件 | 二进制协议、固件设计 |
| 运行硬件验收与 24 小时压力测试 | 硬件验收方法 |
| 接入 DeepSeek Harness | 可选集成 |
| 贡献或报告安全问题 | 贡献指南、安全说明 |
- Agent 通过串口与 ESP32 通信,不在 Windows 中创建网络接口、不安装虚拟网卡、不修改系统路由、不注册网络驱动、不创建系统服务、不添加防火墙规则。
- 管理网页免密码进入,只面向同一 Windows 用户的回环环境,不是远程多人控制面板;不要将管理端口暴露到局域网或互联网。模型 API 仍单独使用本地 token 认证。
- 是否产生安全告警取决于本机安全软件与组织策略,本项目不承诺免告警。EXE 当前未作 Authenticode 代码签名。
- 模型正文以密文穿过串口;设备不解析 prompt、工具参数、文件内容或 SSE 事件,也不持有上游 API key。设备上保留 Wi-Fi 凭据与设备配置。
- 上游 API key 保存在 Windows 凭据管理器;Wi-Fi 凭据保存在设备配置中;日志默认不记录正文与秘密。
- 请仅在所在环境允许使用的设备和外部服务访问范围内使用,并自行确认符合组织的安全政策与适用法律法规。本项目不用于规避你无权规避的安全管控。
原创代码采用 MIT。第三方组件保留各自许可,见 THIRD_PARTY.md。EXE 内嵌第三方通知,也可用 uart2llm licenses 读取。