赵华的个人博客

红外遥控 NEC 解码为什么必须用输入捕获：一次轮询丢码的排查

Fri, 30 Oct 2026 22:06:00 +0000

实验室搬家翻出一个旧空调遥控器，我想做个不联网的离线控制器：STM32F103C8T6 接一个 VS1838B 一体化红外接收头，按下遥控器就把键值打到串口，后面再映射成继电器动作。第一版代码很直白——PA0 配成输入，主循环里不断读电平，用 HAL_Delay(1) 数高电平持续了几个毫秒，据此判断是 0 还是 1。

单独跑一个只做解码的工程时它工作得不错，我一度以为这事已经完了。加上 OLED 刷新和串口上报之后，同一个键按三次，常常只有一次能解出来，另外两次不是校验失败，就是解出一个根本不存在的键值。换接收头、换遥控器电池、把发射距离从两米缩到半米，问题都在。

最后拿逻辑分析仪抓 PA0 的波形，才确认遥控器发得一点问题没有，是我这边在丢时间。

一、接收头输出的不是”有红外/没红外”

先要把这件事说清楚，否则后面的时序全是错的。VS1838B 这类一体化接收头内部集成了 38kHz 带通、AGC 和检波电路，它输出的已经是解调后的基带信号，不是载波。无信号时输出高电平，收到 38kHz 调制时会拉低。也就是说，MCU 看到的是反相的逻辑：有红外 = 低电平。

NEC 协议一帧的结构是固定的：

段	时长	说明
引导码低	9ms	帧开始标志
引导码高	4.5ms	引导码结束
逻辑 0	560us 低 + 560us 高	单个位总长约 1.12ms
逻辑 1	560us 低 + 1690us 高	单个位总长约 2.25ms
重复码	9ms 低 + 2.25ms 高 + 560us 低	长按时的短帧，不含键值

数据一共 32 位：地址 8 位、地址反码 8 位、命令 8 位、命令反码 8 位。每一位的低电平都是 560us，信息藏在高电平的长度里，560us 是 0，1690us 是 1。记住这一条，后面的状态机才有依据：我们要测的始终是上升沿到下降沿之间的那段宽度。

二、轮询丢码的根因：你测的不是边沿，是”碰巧看到的那一刻”

我当时用的是这样一段代码：

while (1) {
    if (HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0) == GPIO_PIN_RESET) {
        uint16_t us = 0;
        while (HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0) == GPIO_PIN_RESET) {
            HAL_Delay(1);   /* 1ms 粒度，还想量 560us */
            us += 1000;
        }
        /* 用 us 判断这是引导码还是数据位 */
    }
    OLED_Refresh();
    printf("key=%d\r\n", last_key);
}

问题出在三个地方，而且是叠在一起的。

第一，时间基准不是一个时钟，而是主循环本身。HAL_Delay(1) 给的是毫秒粒度，而 0 和 1 的差别只有 1130us，靠”数了几次 1ms”去分辨，余量薄得像纸。第二，主循环会被别的事情拉长。OLED 走软件 I2C 刷一屏要几毫秒，printf 在 115200 波特率下阻塞发送几十个字节约 5ms，一次刷新就比一个数据位（最长 2.25ms）还长，中间必然漏掉整位。第三，丢一位不会报错，只会让后面的 32 位整体错位，于是要么反码校验不过，要么凑出一个”看起来合理”的错误键值。

说到底，轮询得到的信息是”我在某个时刻看到高电平”，而 NEC 需要的是”这个边沿发生在哪个时刻”。这是两种完全不同的量。只要主循环有抖动，后者就测不准，再小心也没用。

三、把时间戳交给硬件：TIM2 输入捕获的状态机

换思路：让定时器自由计数，边沿到来时由硬件把计数值锁存进捕获寄存器（CCR）。中断延迟只影响我什么时候去读，不会改变读到的那个已经锁存的值。这就是输入捕获和轮询的本质差别。

先把定时器配成 1MHz 计数：72MHz 主频除以 72 的分频，1 个计数正好 1us。这个分频不是随手写的——如果用 72MHz 直接计数，16 位计数器每 0.91ms 就溢出一次，9ms 的引导码直接对不上；分到 1MHz 后，16 位可以量到 65.5ms，一帧 NEC 的任何一段都装得下。而且 CCR 相减用的是 16 位无符号减法，即使真的回绕也会自动得到正确的差值，不用额外处理。

/* PA0 -> TIM2_CH1；初始化时捕获极性设为下降沿 */
typedef enum { S_IDLE, S_LEADER_HIGH, S_BIT_FALL, S_BIT_RISE } ir_state_t;

static volatile ir_state_t s_state = S_IDLE;
static volatile uint16_t   s_last;      /* 上一次捕获的 CCR */
static volatile uint32_t   s_frame;
static volatile uint8_t    s_bits;
static volatile uint8_t    s_idle_ms;
volatile uint8_t  ir_ready;
volatile uint32_t ir_frame;

static void ir_pol(uint32_t p) { __HAL_TIM_SET_CAPTUREPOLARITY(&htim2, TIM_CHANNEL_1, p); }

static uint8_t rev8(uint8_t x)
{
    x = (uint8_t)((x & 0xF0) >> 4 | (x & 0x0F) << 4);
    x = (uint8_t)((x & 0xCC) >> 2 | (x & 0x33) << 2);
    return (uint8_t)((x & 0xAA) >> 1 | (x & 0x55) << 1);
}

void HAL_TIM_IC_CaptureCallback(TIM_HandleTypeDef *htim)
{
    if (htim->Instance != TIM2) return;

    uint16_t ccr = HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1);
    uint16_t dt  = (uint16_t)(ccr - s_last);   /* 16 位无符号相减，回绕自动正确 */
    s_last = ccr;
    s_idle_ms = 0;

    switch (s_state) {
    case S_IDLE:                       /* 任意下降沿都当作一次帧的起点 */
        ir_pol(TIM_ICPOLARITY_RISING);
        s_state = S_LEADER_HIGH;
        break;

    case S_LEADER_HIGH:                /* 上升沿，dt = 引导码低电平宽度 */
        ir_pol(TIM_ICPOLARITY_FALLING);
        if (dt > 8000 && dt < 10000) { s_frame = 0; s_bits = 0; s_state = S_BIT_FALL; }
        else                         { s_state = S_IDLE; }
        break;

    case S_BIT_FALL:                   /* 下降沿，dt = 上一位的高电平宽度 */
        ir_pol(TIM_ICPOLARITY_RISING);
        s_state = S_BIT_RISE;
        if (dt > 3000) break;          /* 这是引导码的 4.5ms 高电平，跳过 */
        if      (dt > 400  && dt < 800)  s_frame = (s_frame << 1) | 0u;
        else if (dt > 1400 && dt < 1900) s_frame = (s_frame << 1) | 1u;
        else { s_state = S_IDLE; break; }          /* 位宽不像 NEC，整帧作废 */
        if (++s_bits == 32) {
            s_state = S_IDLE;
            uint8_t a = rev8(s_frame >> 24), ai = rev8(s_frame >> 16);
            uint8_t c = rev8(s_frame >> 8),  ci = rev8(s_frame);
            if ((uint8_t)(a ^ ai) == 0xFF && (uint8_t)(c ^ ci) == 0xFF) {
                ir_frame = s_frame;            /* 主循环里再解析 */
                ir_ready = 1;
            }
        }
        break;

    case S_BIT_RISE:                   /* 上升沿，dt = 这一位的低电平，约 560us */
        ir_pol(TIM_ICPOLARITY_FALLING);
        s_state = (dt > 300 && dt < 900) ? S_BIT_FALL : S_IDLE;
        break;
    }
}

/* 放在 1ms 的 SysTick 回调里：帧间空闲超时复位，等下一帧 */
void IR_Tick1ms(void)
{
    if (s_state != S_IDLE && ++s_idle_ms > 20) {
        s_state = S_IDLE;
        ir_pol(TIM_ICPOLARITY_FALLING);
    }
}

这段代码里有几个决定成败的细节，值得单独说一下。

为什么要来回切捕获极性。 一个定时器通道在同一时刻只能捕获一种边沿。我让它先等下降沿，抓住位开始；再切成上升沿，量出高电平宽度；然后切回下降沿等下一位。每切一次，状态机就前进一格，逻辑上不会重复计同一条边沿。

为什么解码放在下降沿。 因为信息在高电平时长里，而高电平结束的那一刻正是下降沿。放在上升沿解，量到的是恒定的 560us 低电平，永远解不出 1。

LSB 先发带来的字节倒序。 NEC 每个字节都是低位先发，左移拼接之后，发出去的第一位会落在最高位，所以 s_frame >> 24 拿到的是位序颠倒的地址。校验反码时无所谓——反码再倒序仍是反码的倒序，异或一定是 0xFF；但你要是拿它去查键值表，就必须先 rev8() 翻回来，否则会得到一堆看似随机的映射。这个坑我在第二块板子上才意识到，因为校验一直是对的，只有键值对不上。

中断里只做算术。 回调里不 printf、不 HAL_Delay、不刷屏。硬件锁存的时间戳不怕中断进得晚，但怕进得太晚——如果下一条边沿在我切极性之前就到了，CCR 会被覆盖，边沿直接丢失。保持 ISR 短，帧完整后置一个标志，解析和打印都丢给主循环。

四、捕获之外还得处理的三件事

长按的重复码。 按住不放时，遥控器不再重发完整帧，只每隔约 108ms 发一个 9ms 低 + 2.25ms 高 + 560us 低 的短帧。它的引导码低电平同样是 9ms，会被我的状态机当成一帧的开头，然后卡在等数据位。所以必须有超时复位：上面 IR_Tick1ms() 的作用就是这个。要不要把重复码当成”上一次键值再触发一次”，取决于你的交互——做继电器开关时我选择忽略，做音量加减时就需要它。

接收头的供电和干扰。 VS1838B 的 AGC 会被环境光里的 38kHz 成分拉低增益，日光灯、节能灯都有这个成分。我第一次装的时候接收头跟继电器共用一路 5V，继电器一吸合距离立刻掉一半。后来在接收头 VCC 脚就近加 100nF 加 10uF 去耦，信号线加 10k 上拉，问题基本消失。这不是软件能补救的，别指望改阈值。

引导码窗口要留余量。 上面写的是 8000–10000us，而不是严格的 9000。遥控器的 455kHz 晶振本身有误差，接收头还有传输延迟，实测常常抓到 8.7ms 附近。窗口太窄会把正常帧判掉，太宽又容易把干扰当成帧头。8–10ms 是我试下来比较稳的范围。

五、什么时候其实不必上输入捕获

输入捕获不是万能钥匙，选型要看场景：

方案	时间基准	精度	抗主循环阻塞	代价
主循环轮询	循环次数 / `HAL_Delay`	毫秒级，抖动大	差	最简单，只适合学习或节奏极固定的场景
EXTI + DWT 微秒计时	CPU 周期计数器	微秒级	中，依赖中断响应	不需要占定时器，但要自己维护计时源
定时器输入捕获	硬件锁存 CCR	与中断延迟无关	好	占一个定时器通道，需要状态机
输入捕获 + DMA	硬件搬运	最好	最好	帧长不定时难处理，NEC 这种变长编码并不划算

如果只是读一个固定时序的传感器、或者按键消抖那种毫秒级的事，轮询完全够用，没必要上捕获。但只要碰上”位宽携带信息”的协议——红外、DHT11、WS2812 的单线时序——时间戳的准确性就是协议的一部分，这时候让硬件去记边沿，比在主循环里跟自己的调度搏斗要靠谱得多。

小结

轮询丢码不是因为代码写得不够仔细，而是因为它测的是”电平”而不是”时刻”，任何一次主循环阻塞都会污染时间基准。输入捕获把这件事交给定时器硬件：边沿到来时锁存计数值，软件只负责按状态机解释宽度。真正要小心的反倒是协议细节——反相输出、高电平携带信息、LSB 先发导致的字节倒序、长按重复码，以及必须在 1ms 节拍里做的超时复位。这几件事对齐之后，同一个遥控器连按几十次，键值都稳定了。

EasyEDA PCB 快速设计工作流：从零到打样的避坑指南

Fri, 30 Oct 2026 12:58:00 +0000

最近在嘉立创EDA（EasyEDA Pro）里连着画了几块板子——西电黑金纪念卡、红金NFC校园卡、六层立体校徽浮雕挂件。从一开始到处试错，到后来基本能一遍画对，中间踩的坑和总结的流程，整理成这篇工作流指南。

这篇不是 API 文档，而是实战避坑手册——记录的是那些官方文档里没写、但会让你卡半天的细节。

一、核心概念：先搞清楚再动手

坐标系统

PCB 域的单位是 mil（千分之一英寸），不是毫米：

1 mm = 39.37 mil
mm(v) = Math.round(v * 39.37 * 100) / 100

坐标原点在左下角，x 向右，y 向上。设计稿用 mm，API 用 mil，所有坐标必须转换。

最容易踩的坑：文字字号需要 ×1.25 补偿。EDA 的字形实际只占字号的 0.7 倍，不补偿的话字会比设计稿小 30%。

六层板层 ID 映射

这是画多层板的基础，记不住就存下来：

视觉层	铜层 ID	阻焊 ID	丝印 ID
L1 顶层	1 (TOP)	5	3
L2 内层1	15 (INNER_1)	—	—
L3 内层2	16 (INNER_2)	—	—
L4 内层3	17 (INNER_3)	—	—
L5 内层4	18 (INNER_4)	—	—
L6 底层	2 (BOTTOM)	6	4
板框	11 (BOARD_OUTLINE)	—	—

金色效果的原理：铜箔层画图案 + 阻焊层开窗同样图案 + 沉金工艺。开窗处露出金色，没开窗的地方是阻焊颜色（绿/红/黑）。

二、标准流程（7 步）

Step 1：环境检查

for port in $(seq 49620 49629); do
  resp=$(curl -s http://127.0.0.1:$port/health)
  if echo "$resp" | grep -q '"easyeda-bridge"'; then break; fi
done
# 确认文档类型必须是 3（PCB）

Step 2：建工程 + PCB

const projUuid = await eda.dmt_Project.createProject('名称', '代号');
await eda.dmt_Project.openProject(projUuid);
const pcbUuid = await eda.dmt_Pcb.createPcb();
await eda.dmt_EditorControl.openDocument(pcbUuid);

这步合计耗时超过 30 秒，单次请求会超时——给 90 秒 timeout。

Step 3：画板框（必须严格闭合）

这是最大的坑。板框首尾不重合的话，EDA 不把它当板子外形，3D 里板子会变成一个小圆饼（挂孔那个圆）。

// 四角圆弧采样后，必须手动回到起点
pts.push([pts[0][0], pts[0][1]]); // ← 这行不能少

Step 4：逐层绘制

分批写入，每批 ≤40 个图元。顺序：内层 → 顶层铜箔 → 底层铜箔 → 阻焊开窗。

Step 5：图像描摹（校徽/签名/Logo）

const blob = await (await fetch('data:image/png;base64,' + b64)).blob();
const cp = await eda.pcb_MathPolygon.convertImageToComplexPolygon(
  blob, 480, 480, 0.55, 0.35, 0.5, 1.5, true, false
);
await eda.pcb_PrimitiveImage.create(x, y, cp, layer, w, h, 0, false, false);

图片预处理用 PIL：灰度 → 二值化 → 裁白边 → 缩放。极性别搞反：笔迹=黑(0)，背景=白(255)。反了会描出白底方块。

描摹参数用 (0.55, 0.35, 0.5, 1.5)——试过 (0.6, 0.3, 0.45, 2.0) 会内部报错。

Step 6：过孔

await eda.pcb_PrimitiveVia.create('', x, y, drill, pad, 0);

参数别多传，传多了报”参数不正确”。

Step 7：保存 + 验证

三、避坑速查表

致命错误

问题	症状	解决
板框不闭合	3D 板子变小圆饼	首尾点重合
文档类型不对	所有 API 返回 null	先 `openDocument` 确认 type=3
底层不镜像	背面图案跑到板外	L6 的 x 用 `板宽 - x`
图片极性反	描出白底方块	笔迹=黑，背景=白
getAll 带 layer 参数	返回 null	用 `getAll()` 再自行 filter

常见错误

问题	解决
文字比设计稿小 30%	`size × 1.25`
填充矩形位置偏	‘R’ 的 y 是顶边不是底边
折线缺一条边	手动加回到起点的线段
描摹报 null	用参数 (0.55, 0.35, 0.5, 1.5)
‘L’ 模式填充失败	‘L’ 只能用于 Polyline
操作超时	分批，每批 ≤40 个
丝印被金块”吃掉”	文字放在阻焊区（红色/绿色底），不能压在开窗（金色）上

丝印文字的规则

这是做装饰板最容易忽略的：PCB 制造时丝印油墨不会印在裸露的铜箔/沉金表面上。

所以丝印文字必须放在阻焊层（红色/绿色底色区域）上，不能压在金色开窗区域。如果建筑/图案是金色的，文字要放到旁边的红色空位。

对于密集布局（建筑间距 <1mm），用碰撞检测自动找空位：默认放上方，检测到重叠就依次换到下→右→左→右上→右下。

四、底层镜像的原理

PCB 的底层（BOTTOM）在 2D 视图和 3D 背面视图中是镜像显示的——就像把板子翻过来看。

如果你在数据坐标 (x=551) 放一个图案，在顶层看是在左边，但在底层的 2D 视图里会跑到右边（镜像了）。

修正方法：底层图案的 x 坐标用 板宽mil - x 来补偿。比如板宽 80mm = 3150mil，顶层 x=551，底层就用 x=3150-551=2599。

但要小心：校徽这类左右对称的图案，镜像后 x 的数学结果恰好等于原值，看起来”没问题”但实际上位置偏了。这时候要用 3D 预览确认，不能只看 2D。

五、加速技巧

批量写入

const data = JSON.stringify(items); // ≤40个
const code = `const items = ${data}; /* 逐个创建 */ return ok;`;
await exec(code, 60000);

贴片元件封装（画建筑/装饰）

把建筑画成贴片电阻/电容的样子（两端焊盘+中间本体），道路用走线，就是”元器件建筑群”风格：

function smd(cx, cy, w, h) {
  const pad = Math.min(w*0.35, 1.2);
  return [
    fillRect(cx-w/2, cy-h/2, pad, h, 0.05),      // 左焊盘
    fillRect(cx+w/2-pad, cy-h/2, pad, h, 0.05),  // 右焊盘
    fillRect(cx-w/2+pad, cy-h/2+1, w-2*pad, h-2, 0.05), // 本体
  ];
}

自动化脚本结构

project.mjs → 建工程+PCB
outline.mjs → 板框+挂孔
layers.mjs  → 逐层绘制（分批）
images.mjs  → 校徽/签名描摹
vias.mjs    → 过孔
save.mjs    → 保存+统计

每个脚本开头都先 openDocument(pcbUuid) 确认文档类型。 文档状态经常被切走。

六、打样参数速查

项目	装饰卡	功能板	六层免费券
尺寸	86×54mm	自定义	≤100×100mm
层数	2	2	6
板厚	1.6mm	1.6mm	1.6mm
阻焊	红/黑	绿	绿
表面处理	沉金	HASL/沉金	沉金
DRC	可跳过	需通过	可跳过

装饰板的 DRC 会报”孤岛铜/无网络”——正常现象，不影响打样。

七、经验总结

画完三块板之后，最大的体会是：

先跑通最小流程（板框+一个矩形+保存），确认每一步都 OK 再批量画。不要一上来就写几百个图元。
每步都要验证。用 getCurrentRenderedAreaImage 抓画布看效果，比猜靠谱得多。
文档状态是最大的坑。EDA 会在你不知道的时候切走文档，操作前必须确认 type=3。
底层坐标要镜像，但对称图案看不出来错——用 3D 预览确认。
丝印不能压金块。做装饰板时，文字和金色图案必须分开在不同区域。

现在这些流程和避坑规则已经整理成了 skill，下次画板直接照着走。完整的 skill 文件在我的 GitHub 上开源了，有兴趣可以看看。

GitHub Actions 打包 Windows exe：中文编码与产物上传

Thu, 29 Oct 2026 22:03:00 +0000

我的 md-workflow-manager 是个 tkinter 小工具，用户下载的是 exe，不是源码。发版流程一直靠手：开虚拟环境、跑 PyInstaller、把 dist 里的 exe 改成带版本号的名字、在 GitHub 上新建 Release 再把文件拖上去。工具本身不大，整套动作十来分钟，但出过两次事故。

一次是忘了加 --noconsole，用户双击后命令行黑框跟着弹出来；另一次更麻烦，我在本地改完代码只打了 tag，忘记重新打包，Release 里的 exe 其实是上一个版本的。两次事故的共同点很清楚：产物是手工做的，它和源码之间没有任何约束，全凭我记得。

所以我把它搬上了 GitHub Actions，让「打 tag」这一个动作同时产出源码版本和可执行文件。这篇写的是过程中真正卡住我的几件事，不是一份照着抄就能跑的教程。

一、为什么必须是 windows-latest

第一反应是用 ubuntu runner，毕竟便宜又快。但这个念头很快被打掉：PyInstaller 不支持交叉编译，它产出的可执行文件要嵌入当前平台的 bootloader 和目标平台的依赖。在 Linux 上打 Windows exe 只能靠 Wine，遇到 pywin32、winreg 这类直接调 Win32 API 的模块基本必挂。我的工具要读写注册表、调系统对话框，属于这类。

主机的差异直接反映在计费上：

项	windows-latest	ubuntu-latest
能否原生产出 exe	能	不能，需 Wine
调用 Win32 API 的依赖	原生支持	大量失败
分钟计费倍率	约 2 倍	1 倍
公共仓库	免费	免费

私有仓库要按倍率算额度，但发版频率低，这点成本可以接受。真正劝退我的是「在 Wine 里调试 PyInstaller」这种时间黑洞。

二、workflow 的骨架

我的触发条件是推 tag，同时保留手动触发，方便发版失败后单独补跑：

name: build-windows-exe

on:
  push:
    tags: ["v*"]
  workflow_dispatch:

permissions:
  contents: write

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: pip

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt pyinstaller

      - name: Build
        env:
          PYTHONUTF8: "1"
          PYTHONIOENCODING: "utf-8"
        run: pyinstaller --noconfirm --clean app.spec

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: md-workflow-manager-win64
          path: dist/*.exe
          if-no-files-found: error

      - name: Publish release
        uses: softprops/action-gh-release@v2
        with:
          files: dist/*.exe

几个地方值得解释。permissions: contents: write 不能省：仓库默认给 GITHUB_TOKEN 的是只读权限，不声明这一行，最后一步会以 Resource not accessible by integration 收场。if-no-files-found: error 是我特意加的，默认行为是警告后继续，结果就是构建目录空着也能「成功」，比直接报错更难查。

cache: pip 只缓存依赖下载，不缓存 dist 和 build。PyInstaller 的中间产物和解释器版本、依赖树强相关，缓存它省不了多少时间，却容易把上一次的残留打进新 exe。发版讲究可复现，我宁可每次从干净目录开始。

文件名里的版本号我交给 tag 推导，不再手写。手写版本号是「产物和源码对不上」的另一个源头：改代码时记得改，打完包又忘了改回来，最后 Release 里躺着一个 1.4.0 名字、1.3.2 内容的 exe。做法是把 tag 去掉 v 前缀后塞进环境变量，PyInstaller 在 spec 里读它拼文件名，构建日志里也打印一遍，出问题能直接对账。同时我会在 pyproject.toml 里维护同一个版本号，测试里断言两者一致，这样「改版本」变成了一次提交，而不是两份手工记录。

三、中文编码出问题的地方有三处

日志乱码是我踩得最久的一个坑。现象很迷惑：同一个 print("开始打包")，本地跑得好好的，到了 Actions 页面变成一串问号，偶尔还直接抛 UnicodeEncodeError。

原因要分三层看，它们经常被混为一谈：

终端代码页：Windows 控制台默认用系统 ANSI 代码页（简中是 CP936）。本地运行时 Python 连着控制台，属于「交互式终端」；CI 里 run 的输出被重定向到管道和日志文件，属于「非交互」，Python 这时用的不是控制台编码，而是 locale 编码，两者不一致就出问题。
解释器的 IO 编码：stdout、open() 的默认编码都由它决定。
压缩包里的文件名编码：这是另一回事，exe 和 zip 里的中文名在不同解压工具下表现不同。

我的处理是同时固定前两层：

env:
  PYTHONUTF8: "1"
  PYTHONIOENCODING: "utf-8"

PYTHONUTF8=1 打开 Python 的 UTF-8 模式，让 open()、sys.stdout 等默认走 UTF-8，不看系统 locale；PYTHONIOENCODING 再把流编码钉死一次。只设后者也能救 print，但脚本里 open("配置.txt") 这类隐式编码的读写仍会按 locale 走，所以我两个都留着。

这么做的代价要提前想清楚：UTF-8 模式会让「读一个 GBK 编码的老文件」从静默乱码变成直接抛异常。对我来说这是好事——乱码比报错难查得多。相应地，我把所有源文件统一成 UTF-8，读文件时显式写 encoding="utf-8"，不留隐式默认。

第三层我干脆绕开：artifact 名、Release 资产名、版本号全部用纯 ASCII，比如 md-workflow-manager-1.4.0-win64.exe。中文名本身能上传，但用户下载后用什么工具解压不受我控制，与其解释乱码，不如不让它出现。

四、PyInstaller 在 CI 里的路径差异

本地打包时，当前目录就是项目根目录，所有相对路径都「碰巧」对。CI 里工作目录变成了 D:\a\md-workflow-manager\md-workflow-manager，任何写死盘符的路径都会失效，而且是在打包成功、运行才崩的那种失效。

我的做法是把配置收进 spec 文件，路径基于 spec 自身位置算：

# app.spec
from pathlib import Path

ROOT = Path(SPECPATH)

a = Analysis(
    ["app.py"],
    pathex=[str(ROOT)],
    datas=[(str(ROOT / "assets"), "assets")],
    hiddenimports=["pystray._win32"],
    excludes=["tkinter.test", "unittest"],
)
pyz = PYZ(a.pure)
exe = EXE(
    pyz, a.scripts, a.binaries, a.datas,
    name="md-workflow-manager",
    console=False,
    icon=str(ROOT / "assets" / "app.ico"),
)

SPECPATH 是 PyInstaller 注入的 spec 目录，比自己拼 os.getcwd() 可靠。datas 用列表套元组，比命令行 --add-data 少一层分隔符问题——那个参数在 Windows 上要求 源;目标，写成冒号会被当成路径的一部分，本地和 CI 都是 Windows 反倒不容易发现写错了。

运行时取资源更不能拼路径，exe 解压后的目录和源码目录不是一回事：

import sys
from pathlib import Path

BASE = Path(getattr(sys, "_MEIPASS", Path(__file__).parent))
ICON = BASE / "assets" / "app.ico"

另外两个高发问题。第一，图标文件被 .gitignore 排除：本地明明有，CI checkout 下来没有，PyInstaller 直接报 icon file not found 失败。押 tag 前我会先 git ls-files assets/ 看一眼。第二，动态 import 的模块静态分析不到，比如 pystray 的后端、某些插件的 driver，本地因为环境里装过所以能跑，exe 里就 ModuleNotFoundError。这类只能靠 hiddenimports 或 collect-all 补。

把这些现象归到一起，就是一张排查表：

现象	根因	处理
日志中文变问号或 `UnicodeEncodeError`	重定向后的 stdout 用 locale 编码	设 `PYTHONUTF8=1` 与 `PYTHONIOENCODING=utf-8`
`Artifact with the name ... already exists`	v4 的 artifact 不可变，同名不能二次上传	每个 job 用唯一名字，矩阵里拼上变量
`Resource not accessible by integration`	`GITHUB_TOKEN` 默认只读	声明 `permissions: contents: write`
`icon file not found`	资源文件被 gitignore 排除	先 `git ls-files` 确认，路径走 `SPECPATH`
exe 启动即 `ModuleNotFoundError`	动态 import 未被静态分析	补 `hiddenimports` / `collect-all`

五、产物上传与重跑的边界

upload-artifact v4 把产物改成了不可变的：同名 artifact 第二次上传会直接报错。这和 v3 的「追加合并」行为相反，网上很多老教程还停留在 v3。我只有一个 job，所以没撞上；如果以后拆成多架构矩阵，每个 job 的 name 必须带上矩阵变量。

Release 那边，softprops/action-gh-release 会按 tag 找 Release，没有就新建，所以失败重跑不会产生第二个 Release。但同名资产会被覆盖，意味着「重跑一次」等于「用新构建替换旧文件」。在这一点上，我把版本号放进 exe 文件名，让同名覆盖不会悄悄发生在两个不同版本之间。

artifact 和 Release 我两个都传，因为用途不同。artifact 是构建过程的副本，默认保留 90 天，私有仓库还占配额，我设成 7 天就够——它主要用来在 Release 上传失败时先保住产物，以及排查「构建成功但用户装不上」时对比文件。Release 才是长期归档，用户从这里下载，所以清单要干净：一个 exe，必要时加一个 SHA256 校验文件。把日志、spec、中间产物一起塞进 Release，只会让用户不知道该点哪个。

还有一件 CI 解决不了的事：代码签名。未签名的 exe 首次运行会被 SmartScreen 拦一道，用户要手动点「仍要运行」。CI 只保证「产物来自这个 tag」，不保证「系统信任这个程序」，这两件事别混在一起谈。

六、小结

现在的发版流程是：改版本号提交 → 打 tag 推送 → 等 Actions 跑完 → 在 Release 里下载 exe，在一台没装过 Python 的机器上双击试跑。本地仍然保留手动打包，只用于开发时快速验证，不再产出对外文件。

回头看，把打包搬进 CI 真正买到的不是那十分钟，而是三条可验证的约束：

tag 对应的源码和 exe 来自同一次构建，不存在「忘了重新打包」；
构建环境是干净的 Windows runner，不再依赖我本机装过什么；
编码、路径、权限这些隐性前提都写进了 workflow，换机器不会失效。

代价也很实在：调 workflow 本身要花时间，Windows runner 计费更高，失败时要多看一眼日志。所以我的判断标准是——只要这个东西会以 exe 形式发给别人，就值得上一次 CI；只在本地跑一跑的小脚本，反而没必要。

MySQL 给订单表加了索引反而更慢：回表、选择性与最左前缀

Wed, 28 Oct 2026 22:01:00 +0000

做 BookShop 课程设计的时候，后台有个订单列表页，条件是两个：按状态筛选、按时间倒序分页。前期数据少，怎么写都不卡；等订单表慢慢涨起来，翻到第二三十页就开始转圈。我第一反应很朴素——create_time 上没有索引，加一个不就完了。

加完索引，第一页确实快了。但翻到中后段反而比之前更卡，而且页码越大越明显。这件事让我第一次认真去看执行计划，也第一次意识到：索引不是”加了就快”的开关，它只是给了优化器一个新的选项，而这个选项有时候比全表扫更差。

一、先看执行计划，别对着 SQL 猜

我当时的 SQL 大概是这个样子：

SELECT id, order_no, user_id, total_amount, status, create_time
FROM order_info
WHERE status = 1
  AND create_time >= '2026-09-01'
ORDER BY create_time DESC
LIMIT 40 OFFSET 800;

问题在于这条语句有三个诉求同时存在：一个等值过滤（status = 1）、一个范围过滤（create_time >= ...）、一个排序（ORDER BY create_time DESC）。而我加的索引只有 create_time 一列。

用 EXPLAIN 看一眼就清楚了。MySQL 8 里我习惯用 EXPLAIN ANALYZE，它会把估算行数和实际行数一起打出来：

EXPLAIN ANALYZE
SELECT id, order_no, total_amount
FROM order_info
WHERE status = 1 AND create_time >= '2026-09-01'
ORDER BY create_time DESC
LIMIT 40 OFFSET 800;

几个字段要会读，其余的可以慢慢补：

字段	看什么
`type`	访问方式，`ALL` 是全表扫，`range` 是索引范围扫，`ref` 是等值匹配
`key`	实际用了哪个索引，为空说明没用索引
`rows`	优化器估算要扫多少行，注意是估算
`filtered`	扫出来的行里有多少能通过剩余条件
`Extra`	`Using index` 是覆盖索引，`Using filesort` 是额外排序，`Using index condition` 是索引条件下推

我那次的结果是 type=range、key=idx_create_time，但 rows 很大，Extra 里是 Using where。翻译一下：它确实走了我加的索引，沿着索引从新到旧扫，然后每扫到一条就回主键索引取整行，取回来再判断 status 是不是 1。扫描量一点没少，反而多了一层回表。

二、回表：二级索引里没有你要的列

InnoDB 的表是按主键组织的聚簇索引，叶子节点存的是完整行数据。二级索引（我们自己建的那些普通索引）的叶子节点只存两样东西：索引列的值，加上主键值。

所以走 idx_create_time 查 order_no、total_amount 这些列，必须拿主键再去聚簇索引里捞一次，这就是回表。回表的代价不在次数本身，而在它是随机 IO：索引按时间顺序扫，主键却可能是乱序的，每一条都可能落在不同的数据页上。

而全表扫虽然是顺序读，但读的是连续的页，还能被预读机制批量拉进 Buffer Pool。数据量大、过滤条件又筛不掉多少行的时候，”顺序全表扫”完全可能比”索引扫 + 大量随机回表”更快。这就是我遇到的情况。

想少回表，思路是让查询需要的列都在索引里，也就是覆盖索引。既然过滤条件有 status，排序有 create_time，那就把它们放进同一个联合索引：

ALTER TABLE order_info
  ADD INDEX idx_status_create (status, create_time);

-- 只取索引里已有的列，Extra 会出现 Using index
SELECT id, status, create_time
FROM order_info
WHERE status = 1 AND create_time >= '2026-09-01'
ORDER BY create_time DESC
LIMIT 40;

这里 id 也在索引里，因为二级索引叶子节点天然带主键，所以这个查询不需要回表。如果业务确实要 total_amount，那就把它也加进索引；但索引列越多，索引越大，写入越贵，这是后面要算的账。

三、选择性：优化器也会主动放弃索引

还有一种”加了索引却没用上”的情况更隐蔽：索引存在，possible_keys 里也有它，但 key 是空的。这不是 MySQL 出错，是它算过账，觉得不值。

优化器判断的依据是选择性，也就是”这个列能把数据筛到多细”。给 status 这种只有几个取值的列单独建索引，基本没有意义：如果九成订单都是已完成状态，走索引扫出来的行数接近全表，却还要逐条回表，不如直接顺序扫。

这个判断依赖统计信息里的基数（Cardinality），可以用 SHOW INDEX FROM order_info 看。它是采样估算出来的，不是精确值；大批量导入数据之后往往还没来得及更新，估算就会严重失真，优化器可能因此选错索引。

-- 大批量导入或删除数据后，刷新统计信息
ANALYZE TABLE order_info;

-- 确认基数是否合理
SHOW INDEX FROM order_info;

我吃过一次这个亏：批量灌了几万条测试订单之后，查询突然从走索引变成全表扫。当时以为是索引坏了，其实是统计信息还停留在”表里只有几百行”的状态。ANALYZE TABLE 之后执行计划立刻恢复正常。

所以要记住一点：低选择性的列不适合单独建索引，它更适合作为联合索引的前缀，用来缩小范围，而不是单独承担过滤。

四、联合索引的顺序决定它能干什么

联合索引 (a, b) 不是一个”包含 a 和 b 的索引”，它是一棵按 a 排序、a 相同再按 b 排序的树。这决定了它能支持哪些查询：

查询条件	`(status, create_time)`	`(create_time, status)`
`status = 1 AND create_time > ?`	能用，且排序可复用索引	只能用 `create_time` 范围
只有 `create_time > ?`	用不上	能用
只有 `status = 1`	能用（最左前缀）	用不上
`status = 1 ORDER BY create_time`	排序免费	需要额外排序

关键在”范围条件会截断后面的列”。在 (status, create_time) 里，status 是等值，定位到一段连续区间后，区间内部本来就是按 create_time 有序的，所以范围过滤和 ORDER BY 都能顺着索引走，Extra 里不会出现 Using filesort。

反过来，如果把范围列放在前面，create_time > ? 之后的那一段在索引里对 status 是无序的，后面的列就只能当作过滤条件逐条判断，排序也用不上索引。

这也是我最终选 (status, create_time) 而不是反过来的原因：等值列在前，范围列和排序列在后。

五、函数和隐式转换会让索引直接失效

有两类写法非常常见，而且一旦出现，索引基本等于白建。

第一类是在索引列上套函数。比如按天统计时写成 WHERE DATE(create_time) = '2026-10-01'，MySQL 必须对每一行先算 DATE() 才能比较，索引上的有序性用不上。改成范围查询就能走索引：

-- 不要这样：索引列被函数包住
SELECT COUNT(*) FROM order_info WHERE DATE(create_time) = '2026-10-01';

-- 改成左闭右开区间
SELECT COUNT(*) FROM order_info
WHERE create_time >= '2026-10-01'
  AND create_time <  '2026-10-02';

第二类是隐式类型转换。如果 order_no 是 VARCHAR，却写成 WHERE order_no = 20261029001，MySQL 会把列的值转成数字再比较，等于在列上套了一层转换函数，索引失效。反过来，INT 列和字符串比较时是把字符串转成数字，索引还能用。所以规则是：参数类型和列类型保持一致，不要指望数据库帮你兜。

顺带说一句，深分页本身也是这类问题的重灾区。LIMIT 40 OFFSET 800 的意思是”扫描 840 行，扔掉前 800 行”，页码越大扫得越多。用游标分页可以绕开：

-- 记住上一页最后一条的 create_time，下一页从它之后开始
SELECT id, order_no, total_amount
FROM order_info
WHERE status = 1 AND create_time < '2026-10-20 12:00:00'
ORDER BY create_time DESC
LIMIT 40;

六、小结：先算账，再建索引

最后要说清楚代价，否则很容易走向”到处加索引”的另一个极端。

每个二级索引都是一棵独立的 B+ 树。插入一行要维护所有相关索引；更新被索引的列，可能要删除再插入索引项；索引本身也占磁盘、占 Buffer Pool，挤占本该缓存数据页的内存。索引越多，写入越慢，这一点在批量导入时非常明显。

所以我的判断顺序是：先看这条查询跑得多不多，再决定要不要为它建索引；建之前先确认它真的走索引（看 key），建之后再看扫描行数有没有下降（看 rows 和 filtered）。如果优化器偶尔选错，USE INDEX 可以作为临时兜底，但它只是绕过统计信息，不解决根本问题——真正该做的是让统计信息保持新鲜、让索引顺序贴合查询。

回过头看，我第一次加索引的错误不在技术细节，而在思路上：把索引当成”加速按钮”，而不是”给优化器多一个选项，并为此付出写入代价”。

现在再遇到慢查询，我会按这个顺序走一遍，而不是先 ALTER TABLE：

用 EXPLAIN 确认是 type=ALL 还是走了索引，先分清”没索引”和”索引用错”；
看 rows × filtered 估算的扫描量，判断是扫得太多还是回表太重；
把等值过滤列放最前、范围列和排序列放后面，考虑能不能做成覆盖索引；
检查 SQL 里有没有在索引列上套函数、类型不一致的情况；
新建索引后用 EXPLAIN ANALYZE 对比实际行数，数据变动大时记得 ANALYZE TABLE。

想清楚这条查询的过滤列、排序列、返回列分别是什么，再决定索引怎么排，基本就不会出现”加了反而更慢”这种事。

FastAPI 同一个路由注册了两次：改了代码却不生效的排查

Tue, 27 Oct 2026 22:01:00 +0000

上个月给情绪记录项目改接口。原来的 GET /api/emotion/history 直接返回一个列表，前端自己算总数、自己分页；数据一多，前端每次都要把几百条记录全拿下来。我决定把返回结构改成 {total, page, items}，后端分页，前端只负责渲染。

改动不大：把查询函数加个 offset/limit，返回值包一层字典。改完保存，uvicorn --reload 打了重载日志，我用 curl 打了一次接口，返回的还是那个裸列表。我以为是重载没生效，手动重启；又怀疑是浏览器缓存了 GET，换了 Postman；再怀疑 __pycache__ 里的旧字节码，把目录删了重跑。折腾了快一个小时，前端那边一直在问“你确定改了吗”。

代码确实改了，但服务器上跑的不是它。问题出在同一个路径被注册了两次，而后注册的那份根本没机会执行。

一、先排掉三个“看起来很像”的原因

这类“改了不生效”的问题，最容易把人带偏的是几个常见解释。我按顺序验了一遍，结论都是否定的，但验证方式值得记下来，因为后面每次遇到同类现象都能用。

猜测	怎么验证	结果
热重载没触发	新增一个 `GET /api/_ver` 返回时间戳	时间戳是新的，重载正常
浏览器/客户端缓存	用 curl 加 `-H "Cache-Control: no-cache"` 直接打	返回结构仍旧
`__pycache__` 旧字节码	删掉所有 `__pycache__` 后重启	无变化
前端用了本地 mock	看 DevTools 的 Response 与服务器日志	请求确实到了后端

四个都排除之后，剩下的可能性只有一种：后端确实收到请求了，也确实执行了某个处理函数，但那个函数不是我以为的那个。这时候再盯着业务代码看已经没意义了，得去看“这个路径到底绑了几个函数”。

二、把 app.routes 打出来

FastAPI 的应用对象上有一个 routes 列表，所有注册过的路由都在里面，包括你自己写的和框架内置的 /docs、/openapi.json。把它按“路径 + 方法”分组，重复的自然就浮出来了。

from collections import defaultdict
import main  # 你的 FastAPI 实例所在模块

seen = defaultdict(list)
for route in main.app.routes:
    path = getattr(route, "path", "")
    methods = getattr(route, "methods", None)
    if not methods or not path.startswith("/api"):
        continue
    seen[(path, frozenset(methods))].append(route.endpoint)

for (path, methods), endpoints in seen.items():
    if len(endpoints) > 1:
        print("重复:", path, sorted(methods))
        for ep in endpoints:
            print("   ", ep.__module__ + "." + ep.__name__)

输出很直接：/api/emotion/history 出现了两次，一个来自 main.py 里的 @app.get，一个来自 routers/emotion.py 里的 @router.get，后者被 app.include_router(emotion_router, prefix="/api") 挂进来。而我改的是 Router 里那一份，执行的是 main.py 里那一份——那是两个月前写的第一版，改结构时忘了它还在。

这里有个细节值得注意：重复注册不会抛异常，也不会打警告。FastAPI 只是往列表里追加，两个函数都合法、都能被调用，只是永远只有第一个能匹配上。app.routes 和 app.router.routes 指向的是同一个列表，include_router 也不是把子路由“挂”成树，而是逐个复制进这个扁平列表，所以打印出来的顺序，就是真实的匹配顺序。

顺带说一个副作用：Swagger 会把两个同路径的操作都渲染出来。我当时代码里一处写了 tags=["情绪"]，另一处没写，于是同一个路径在文档里出现了两次、分组还不同，看着更像两个不同接口，进一步误导了排查方向。

三、十几行的最小复现

为了让团队里其他人相信这不是环境或配置问题，我把它压成了一个单文件示例：

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

@app.get("/api/demo")
def old_handler():
    return {"version": "old", "items": []}

@app.get("/api/demo")
def new_handler():
    return {"version": "new", "total": 0, "items": []}

client = TestClient(app)
print(client.get("/api/demo").json())   # {'version': 'old', 'items': []}

输出是 old，把两个函数调换位置就变成 new。这段代码同时说明了三件事：注册阶段不报错、后注册者永远得不到执行、代码顺序即优先级。TestClient 不需要真正监听端口，所以它很适合放进回归用例里，当作一条“这个错误应该被拦住”的证据。

四、为什么是“第一个”生效

要理解这个，得往下看一层。FastAPI 的 app 并不是自己处理请求，它把请求交给 Starlette 的 Router，而 Router 内部的匹配逻辑简化后是这样：

async def app(self, scope, receive, send):
    partial = None
    for route in self.routes:
        match, child_scope = route.matches(scope)
        if match == Match.FULL:
            await route.handle(scope, receive, send)
            return                      # 命中即返回，后面的路由不再看
        if match == Match.PARTIAL and partial is None:
            partial = route
    # 全部走完都没命中，才处理 405 / 重定向

顺序遍历、首个命中即返回。这意味着：路径和方法都相同的两个路由，排在后面的那个是死代码——它存在于 app.routes 里，出现在 /docs 里（Swagger 会把同路径的两个操作都列出来，看起来像两个接口），但永远不会被调用。这也解释了为什么我当时在 Swagger 里看到两行 /api/emotion/history，却没往重复注册上想，以为是 FastAPI 把操作拆成了两个标签页。

那顺序由什么决定。@app.get 在模块导入时就完成注册；include_router 则在被调用的那一刻把子路由批量追加进列表。所以顺序取决于代码执行的先后，而不是文件里的书写位置。常见的三种重复来源：

老代码留在 main.py，新逻辑搬进 Router，两处都没删；
include_router 被调了两次（比如在 create_app() 和模块级各调一次），整组路由翻倍；
多个 Router 用了同一个 prefix，各自的路径又重名。

五、几种“看着像重复”的相邻坑

排查过程中我还顺手确认了几个容易混淆的变体，它们的表现和重复注册很像，但根因不同，处理方式也不一样。

现象	根因	判断依据
405 Method Not Allowed	路径命中，但没有任何路由声明该 HTTP 方法	响应头里的 `Allow` 列出实际支持的方法
422 参数校验失败	`/history/{item_id}` 注册在 `/history/latest` 之前，`latest` 被当成 id 去校验	看报错字段名，是路径参数而不是查询参数
307 重定向后 401	请求带了尾斜杠，`redirect_slashes` 默认开启并返回 307，客户端跨域跟随重定向时丢掉 `Authorization`	响应里出现 307，且目标地址少了斜杠
请求打到旧逻辑	同一路径注册两次，先注册者生效	`app.routes` 里同路径同方法出现多次

第三行那个 307 值得多说一句。Starlette 默认 redirect_slashes=True，/api/emotion/history/ 会被重定向到不带斜杠的地址。307 会保留方法和请求体，看起来没问题，但浏览器的 fetch 在跟随跨域重定向时会剥掉 Authorization 头，于是 token 没了、接口返回 401，而你在后端只看到一个没带凭证的请求。我的做法是前端请求统一不带尾斜杠，路由也不要两个都定义。

六、两道防线

知道根因之后，改起来只要删掉 main.py 里那份旧实现。但这类问题会复发，尤其多人协作、代码搬来搬去的时候。我加了两道很轻的防线。

第一道是启动自检，在 create_app() 最后调用一次，重复直接抛错，让服务起不来——比让它带病运行强得多。

# app/route_guard.py
from collections import defaultdict
from fastapi import FastAPI

def assert_no_duplicate_routes(app: FastAPI, prefix: str = "/api") -> None:
    seen = defaultdict(list)
    for route in app.routes:
        path = getattr(route, "path", "")
        methods = getattr(route, "methods", None)
        if not methods or not path.startswith(prefix):
            continue
        seen[(path, frozenset(methods))].append(route.endpoint)

    dup = {k: v for k, v in seen.items() if len(v) > 1}
    if not dup:
        return
    lines = []
    for (path, methods), eps in dup.items():
        owners = [f"{ep.__module__}.{ep.__name__}" for ep in eps]
        lines.append(f"{path} {sorted(methods)} <- {owners}")
    raise RuntimeError("检测到重复路由:\n" + "\n".join(lines))

第二道是一个测试用例，把同一份检查跑在 CI 里。它本身没有新逻辑，价值在于“提交前就会被拦下”，而不是等线上发现改代码不生效。

def test_no_duplicate_api_routes():
    from app.route_guard import assert_no_duplicate_routes
    from main import app
    assert_no_duplicate_routes(app)

自检要注意两点。一是把范围限定在业务前缀（比如 /api），否则框架内置的 /openapi.json、/docs 之类会干扰判断；二是别在测试环境直接 raise 导致整个 suite 挂掉——如果项目里有很多历史重复，先 print 出清单，清完再改成抛错。

小结

这次踩的坑，本质是“配置型的错误伪装成了代码错误”。我一开始所有的排查动作都指向“新代码没跑起来”，而真实情况是“新代码根本没被选中”。两者的表现都是返回旧结构，但验证路径完全不同：前者查进程、查重载、查缓存，后者只需要把 app.routes 打出来看一眼。

现在我的习惯是，凡是“改了没反应”且确认请求确实打到后端，先花十秒枚举路由和方法的组合，再去看业务逻辑。这个动作成本极低，却能排掉一整类静默失效——路由重复、前缀拼错、方法声明错、路径参数抢占，全都能在这一步暴露出来。

STM32 采集 NTC 温度抖动：RC 硬件滤波与软件滑动平均怎么选

Mon, 26 Oct 2026 22:02:00 +0000

上周给实验室的小恒温箱换主控，方案很朴素：STM32F103C8T6 加一颗 10K 的 NTC（B 值 3950），和 10K 电阻分压后接 ADC1 的 PA0，12 位采样、1Hz 上报温度。硬件焊完，串口助手一看就傻眼了——室温明明稳定在 24 度出头，显示值却在 23.6 到 25.2 之间来回跳，小数点后一位完全没法看，加热继电器一吸合，跳得更凶。

第一反应是电源不干净，于是把 5V 换成一颗低压差 LDO，又在探头两端并了 100nF，没本质改善；接着怀疑 ADC 本身，换了块板子，抖动照旧。最后老老实实把 ADC 原始码值和换算后的温度一起打出来，才看清楚问题不是”ADC 不准”，而是我把三类完全不同的东西混在一起了：量化误差、随机噪声，还有一个来自继电器和工频的周期性干扰。这篇就把当时的判断顺序、计算过程和最后的取舍写清楚。

一、先把”抖”拆开，再谈滤波

很多教程一上来就教你写滑动平均，但滤波只能处理带内噪声，处理不了已经混叠的成分。所以第一步是分清抖动从哪来，我的做法是打印原始码值，而不是温度。

先算一笔账，看看 12 位 ADC 本身能有多细。参考电压 3.3V，一个 LSB 是：

LSB = 3.3 V / 4096 ≈ 0.806 mV

再看分压的灵敏度。25 度时 NTC 和上拉电阻都约 10K，分压点约 1.65V；NTC 的阻值温度系数大约每个摄氏度变化 4% 左右，换算到分压点，每摄氏度带来几十毫伏的变化（按 10K 分压估算约 36mV/℃）。也就是说，一个 LSB 大约对应 0.02 度。

那么显示抖动 ±0.8 度，对应几十个 LSB，绝不是量化误差造成的。这一步很关键，因为它直接排除了”ADC 位数不够、换 16 位 ADC”这个看起来最顺手的错误方向。

接着看抖动的时间特征。我在 1kHz 下连续采样，把数据丢到串口：

有一条固定周期约 20ms 的低幅波动，这是 50Hz 工频串进来的；
继电器吸合瞬间有几个码值的尖峰，是触点动作和线圈反向电动势引起的；
其余是围绕均值上下的小幅随机跳动。

这三种东西要用的手段不一样：工频靠硬件 RC 和屏蔽，尖峰靠中值滤波，随机噪声靠平均。如果只写一个滑动平均，尖峰会被”摊”成一个缓坡，工频则可能因为 1Hz 上报而混叠成慢漂移，看起来像温度真的在慢慢变，实际是采样率太低造成的假信号。

二、RC 低通放在 ADC 前面：算截止频率，也算建立时间

硬件滤波的价值有两个：压掉高频干扰，以及抗混叠。软件滤波再厉害，也没法把已经混叠进低频的成分分出来，所以只要条件允许，第一道滤波应该放在 ADC 之前。

一阶 RC 低通的截止频率是：

fc = 1 / (2πRC)

我实际试过的两组参数：

R	C	截止频率 fc	说明
1kΩ	100nF	≈ 1.59 kHz	只压高频，对 50Hz 几乎无作用
1kΩ	1µF	≈ 159 Hz	保留温度信号，工频衰减有限
10kΩ	1µF	≈ 15.9 Hz	工频压得下去，但建立时间变长

温度信号本身是慢变量，恒温箱的热时间常数是几十秒，带宽根本不需要超过几赫兹。理论上 15.9Hz 这组更合适。但我最后选的是 1kΩ + 1µF，串一个 100nF 到地做高频旁路，原因不在滤波效果，而在ADC 的源阻抗。

STM32 的 ADC 采样阶段，内部采样电容要在规定的采样时间内充电到足够精度。充电时间常数由源阻抗和采样电容共同决定，源电阻越大，需要的采样时间越长。10K 分压本身已经不算小，再串 10K，等效源阻抗就到 20K 量级；如果采样时间还按默认的最短档配，读数会系统性偏低。与其去改采样时间，不如把串联电阻压到 1K，让充电这件事变得无所谓，剩下的平滑交给软件——软件滤波不花钱、可调、还能顺便做异常值剔除。

这里有个容易被忽略的点：RC 的时间常数也决定了探头断线、接触不良时电压建立的速度。电容越大，”坏”的迹象被拖得越久。

三、软件侧三种滤波：原理、代价和固定点代码

软件滤波我用过三种，都在 100Hz 的采样节奏下跑，单片机是 Cortex-M3，有硬件除法，开销不是问题。

滑动平均最适合随机白噪声。N 点平均能把标准差压到原来的约 1/√N，代价是群延迟大约 (N-1)/2 个采样周期。也就是说，8 点平均在 100Hz 下有 35ms 的滞后。

#define WIN 8

static uint16_t buf[WIN];
static uint8_t  idx;
static uint32_t sum;          /* 必须用 32 位，见后面的坑 */

uint16_t moving_avg_push(uint16_t x)
{
    sum -= buf[idx];
    buf[idx] = x;
    sum += x;
    idx = (idx + 1) % WIN;
    return (uint16_t)(sum / WIN);
}

这段的关键是”进一个、出一个”，不用每次重新累加整个窗口，计算量和窗口大小无关。

中值滤波对付单点尖峰最有效。5 点窗口能干掉最多两个连续的异常值，而且不会像平均那样把尖峰摊开：

static uint16_t median5(const uint16_t *v)
{
    uint16_t s[5];
    for (int i = 0; i < 5; i++) s[i] = v[i];
    for (int i = 1; i < 5; i++) {
        uint16_t t = s[i];
        int j = i - 1;
        while (j >= 0 && s[j] > t) { s[j + 1] = s[j]; j--; }
        s[j + 1] = t;
    }
    return s[2];
}

一阶 IIR（指数滤波）内存最小，两个字节就够，适合 RAM 紧张或者需要随时调平滑程度的场合：

static uint16_t iir_update(uint16_t x)
{
    static int32_t y;
    /* y += (x - y) / 8，加 4 做四舍五入 */
    y += ((int32_t)x - y + 4) / 8;
    return (uint16_t)y;
}

注意这里必须先把 x 转成有符号再减，否则 x 小于 y 时无符号相减会回绕成一个巨大的正数，输出直接飞掉。

四、怎么选：把延迟预算摆到桌面上

三种方案没有绝对优劣，关键看你的系统能容忍多少延迟。我把它们放在一张表里对比，选型时按行对号入座：

方案	群延迟	抗单点尖峰	RAM	计算量	参数整定	适合场景
RC 一阶低通	约 1/(2πfc)	差	0	0	R、C	高频干扰、需要抗混叠
滑动平均 N 点	(N-1)/2 × Ts	一般，尖峰被摊平	2N 字节	每点两次加减	窗口长度	随机白噪声
中值 5 点	2 × Ts	强	10 字节	小数组排序	窗口长度	偶发毛刺、触点干扰
一阶 IIR	约 Ts/α	差	2 字节	两次运算	α	内存紧、需连续平滑

套到两个具体场景里，结论完全不同：

恒温箱：热时间常数几十秒，几十毫秒的延迟毫无影响，可以放心用 8 点甚至 16 点平均，换更小的抖动；
电机电流环：1kHz 采样，8 点平均就是 3.5ms 延迟，直接吃掉相位裕度，宁可只用 2 点平均或者一阶 IIR，甚至不滤。

这就是”设计取舍”的实质：不是找最强的滤波器，而是先算清楚系统还剩多少延迟预算，再往里填。

也顺便说一下为什么没上卡尔曼。卡尔曼需要状态方程和噪声统计，恒温箱这种一阶热系统当然能建模，但参数辨识和调参的成本远高于收益；而且模型一旦和实际箱子不一致，滤波反而会给出”看起来很平滑但系统性偏差”的结果，比抖动更难发现。

五、我最终的方案，和两个真实的坑

最后落地的链路是：NTC 分压 → 1kΩ + 1µF 的 RC → 定时器 1kHz 触发 ADC → DMA 循环搬运 16 点 → 中值 3 点 → 滑动平均 8 点 → 100Hz 得到温度，1Hz 上报一次。

为什么先中值再平均？因为中值先把偶发尖峰拿掉，平均再压随机噪声；顺序反过来，尖峰已经被平均”染”进窗口，中值就无能为力了。

第一个坑是累加变量溢出。我最初把窗口开到 32 点，sum 声明成 uint16_t，12 位满量程 4095，32 点累加远超 65535，直接回绕，温度偶尔跳到负数。改成 uint32_t 就没事了。这类错误不会报错，只会让数据”偶尔疯一下”，排查时优先怀疑。

第二个坑更值得说：滤波曾经帮我掩盖了硬件问题。探头引线在箱门铰链处被反复弯折，内部铜丝将断未断，表现为随机的大幅尖峰。中值滤波把它吃得干干净净，曲线看着很漂亮，但真实温度偶发偏差两三度。后来我在调试版本里额外输出窗口内的最大值和最小值，一眼就看出”极差远超正常噪声”，顺着查到线。滤波是让数据好看，不是让系统变好，极差、断线检测这类诊断量必须保留。

验证方法也很简单：用手指捏住探头，看滤波前后的阶跃响应。如果输出明显滞后或者有过冲，说明窗口太大或者 IIR 的 α 太小；如果响应正常但稳态还在抖，说明噪声没压够，再回头查干扰源。

小结

这件事我自己的执行顺序是固定的：先算量化误差，判断抖动是不是 ADC 分辨率的问题；再看时间特征，分清工频、尖峰和随机噪声；然后硬件上放一阶 RC，既压高频也抗混叠，同时注意源阻抗和采样时间；最后软件上按延迟预算选窗口，中值去尖峰、平均压噪声，累加一定要用够宽的整型。滤波解决的是”读数不好看”，接触不良、干扰源这类根因，还得靠硬件和诊断量去抓。

SpringBoot 三层架构里 DTO 该放哪一层：从鸿蒙登录接口返回密码说起

Sun, 25 Oct 2026 22:03:00 +0000

答辩前一周，我给鸿蒙 App 配的后端 lifeApp0110 已经跑通了登录、待办和图标三个模块。技术栈很普通：SpringBoot 2.3.4、MyBatis 2.1.4、MySQL 5.x，包名 com.qf.lifeapp0110，用 @Controller + @ResponseBody 把对象直接转成 JSON 回给客户端。答辩前一天我打开 Swagger 核对接口，/user/one 的响应示例里赫然列着 password。再看代码，这个登录接口连密码比对都没写，只按用户名查了一次，就把整行数据交了出去。

我一开始以为补一行密码判断就完了，真正改起来才发现问题不在那一行 if，而在接口的”形状”是由数据库表决定的：表里有什么列，客户端就能收到什么字段。这篇把那次改造完整写一遍，重点不是背分层口诀，而是说清每一类对象为什么只能待在一个地方。

一、实体为什么不能直接出网关

实体（Entity）的定义很简单：一个类对应一张表，一个对象对应一行记录。项目里 user 表只有 id、username、password 三列，MyBatis 的 queryByName 返回的就是这个实体。问题在于，实体一旦被 @ResponseBody 序列化，它就从”数据库的投影”变成了”对外契约”。当时的代码大致是这样：

@RequestMapping("/one")
@ResponseBody
public Map queryOne(@RequestBody User user1) {
    Map map = new HashMap();
    User user = userMapper.queryByName(user1.getUsername());
    if (user != null) {
        map.put("user", user);          // 整个实体进了 JSON
        map.put("message", "ok");
    } else {
        map.put("user", new User());    // 失败也用空对象兜底
        map.put("message", "error");
    }
    return map;
}

这段代码有三个隐患，而且都不是改一行能解决的。

第一，返回体里带着 password。只要字段在实体上，任何返回实体的接口都会带上它，今天是登录，明天是”查个人资料”，后天是”管理员看用户列表”。靠每个接口手动置空，迟早漏一个，而漏的那次通常没人发现。

第二，表结构和 API 绑死。以后给 user 加 phone、is_deleted，客户端收到的 JSON 立刻多出字段；反过来，客户端想要的”昵称 + 头像”如果不在表里，接口就拼不出来。接口本应描述业务能力，现在却成了 DDL 的镜像。

第三，new User() 把”没查到”编码成了”一个 id 为 0 的空对象”。鸿蒙端必须知道”id 为 0 就表示失败”这个隐含约定，编译器不检查，Swagger 也写不出来。这类约定一旦散落在客户端代码里，后端想改错误码都改不动。

二、三类对象，三种生命周期

改造时我先把对象按职责分开，而不是急着建一堆类：

对象	所在包	由谁创建	字段从哪来	能不能出网关
Entity / PO	`entity`	MyBatis 映射	数据库表的列	不能
DTO（入参）	`dto`	Spring MVC 反序列化	客户端请求体	只在入方向
VO（出参）	`vo`	Service 组装	业务需要展示的字段	可以，且只暴露必要字段

这张表里最关键的是最后一列。实体不能出网关，不是因为它”层次低”，而是它的字段集合由 DDL 决定，对外字段集合应该由接口设计决定，这两个集合的变更节奏根本不同。表可以为了查询性能加冗余列，接口却不能因为这个就把冗余列抖给客户端。

还要说明一点：不是每个接口都得配三个类。这个项目里我只有 LoginRequest 和 UserVO 两个，够用了。真正不能破的是方向——Controller 可以依赖 DTO 和 Service，Service 不能依赖 HttpServletRequest，Mapper 更不能认识 VO。

三、入参 DTO：校验注解跟着契约走

登录接口的入参单独抽出来，校验注解放这里：

public class LoginRequest {
    @NotBlank(message = "用户名不能为空")
    private String username;

    @NotBlank(message = "密码不能为空")
    private String password;

    // getter / setter 省略
}

@PostMapping("/login")
public UserVO login(@Valid @RequestBody LoginRequest req) {
    return userService.login(req);
}

为什么校验不写在 User 实体上？因为这个实体同时被注册、改资料、后台编辑复用，三处对字段的要求并不一样：注册时用户名密码都必填，改昵称时密码根本不该出现。注解写在实体上，就得引入 validation groups 按场景分组，分组一多，注解比字段还长，后来接手的人也不敢删。更重要的是，校验规则属于接口契约，接口改规则就改 DTO，不该逼着表一起动。

入参 DTO 还只放客户端能决定的东西。id、create_time 这类字段不要出现在请求对象里：它们要么由数据库生成，要么由服务端赋值。请求对象里没有这个字段，客户端就没法伪造，这比在 Service 里补一堆 if (id != null) throw 省事得多。

四、出参 VO：转换放在 Service

出参单独定义，并且把”哪些字段可以出门”这条规则收在一处：

public class UserVO {
    private Integer id;
    private String username;

    public static UserVO from(User user) {
        UserVO vo = new UserVO();
        vo.setId(user.getId());
        vo.setUsername(user.getUsername());
        return vo;
    }
}

@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;
    @Autowired
    private PasswordEncoder passwordEncoder;

    public UserVO login(LoginRequest req) {
        User user = userMapper.queryByName(req.getUsername());
        if (user == null || !passwordEncoder.matches(req.getPassword(), user.getPassword())) {
            throw new BizException("用户名或密码错误");
        }
        return UserVO.from(user);
    }
}

为什么转换放在 Service 而不是 Controller？因为 Controller 的职责是把 HTTP 翻译成方法调用，它不该知道”哪个字段敏感”。让 Controller 转换，每加一个接口就要重新判断一次该脱哪些字段，漏一次就是一次事故；放在 Service，规则只有一份，登录、资料页、后台列表都走同一个 UserVO.from。

这里有个我踩过的细节：一开始图省事用了 BeanUtils.copyProperties(user, vo)，后来 VO 的 id 写成 Long，实体是 Integer，类型不匹配时它直接静默跳过，id 一直是 null。接口返回 200，前端拿到空值，排查了半天。字段少的时候手写 from() 最稳；字段多了上 MapStruct，它是编译期生成代码，源字段对不上会给出警告，配置成 ERROR 就直接编译失败，比运行时才发现强。

顺带说密码。表里存的还是明文（列定义是 varchar(32)），这次我只把接口改造和密码存储拆成两件事：接口先改成不返回密码、比对走 PasswordEncoder.matches（引入 spring-security-crypto 这个独立包就够，不必把整个 Spring Security 拖进来），哈希迁移单独排期。两件事混在一个提交里，出问题很难判断是哪一步导致的。

五、包结构和依赖方向

改造后的目录是这样的，每个包只做一件事：

com.qf.lifeapp0110
├── controller     UserController   只依赖 dto 和 service
├── service        UserService      业务规则、实体转 VO
├── dao            UserMapper       只进出 Entity
├── entity         User             与表一一对应
├── dto            LoginRequest     入参 + 校验注解
├── vo             UserVO           出参
└── common         BizException     统一异常

依赖方向只有一条：controller → service → dao。dto 和 vo 被上层依赖，自己不反过来依赖 mapper。只要在 vo 包里看到 import com.qf.lifeapp0110.dao.UserMapper，分层就已经破了，而且这种破坏往往是从”顺手查一下”开始的。

DAO 的入参也要守住。queryByName(String username) 是对的，query(LoginRequest req) 就不对——DAO 一旦认识 HTTP 契约，将来接口从 REST 换成内部 RPC 或者定时任务调用，DAO 都得跟着改。

常见放错位置的现象，我整理成了这样一张表：

现象	根因	后果
Controller 直接返回 User 实体	出参用了 PO	表字段即 API，password 顺手带出
校验注解写在实体上	契约规则和表约束混在一起	改单个字段也要整对象校验
Service 返回 `Map`	没有出参类型	前端靠猜字段，Swagger 生成不出来
DTO 放进 `dao` 包	层间依赖反了	换调用方式要连 DAO 一起改
VO 里塞 `UserMapper`	出参层偷偷查库	循环依赖、事务边界混乱

六、改造顺序：先加，再切，最后删

这次改造最怕的不是写错，是鸿蒙端的老版本还在读 user.password 判断登录成功。所以我没做”一把梭”：

Service 新增 login 返回 UserVO，旧接口原样保留，先让新接口在 Swagger 里跑通；
鸿蒙端 LoginPage.ets 切到新接口，用 message 字段判断结果，不再看 id 是否为 0；
观察一段时间旧路径的调用日志，确认没有存量版本还在用，再删旧接口；
最后打开 /swagger-ui.html 搜一遍 password，响应示例里搜不到才算收尾。

兼容老客户端的原则是”加字段可以，改语义要慢”。给 VO 新增一个字段，老版本无感；把 user 从对象换成字符串，老版本立刻解析失败。判据不是”我这边编译通过”，而是”用户手机上的那个版本还认不认”。

小结

实体是表的影子，DTO 是接口的契约，VO 是业务的输出。三者混用时不会立刻报错，但每加一个字段、每改一次表、每上一个接口，风险都会沿着这条缝扩散。最小可行的做法就三条：Mapper 只碰实体；Controller 只收 DTO、只返回 VO；Service 负责把实体翻译成 VO，顺手把不该出门的字段留在里面。至于密码，它从始至终都不该出现在任何返回对象里——这一点靠纪律不如靠类型，因为类型不会忘。

AERO-6X 六轴机械臂数字孪生：关节联动、爆炸分层与实时剖面

Sun, 25 Oct 2026 02:07:00 +0000

上一篇里我做了个六轴机械臂的结构工作台，能转、能拆、能剖，但它不会动。学弟看完问了一句：”能不能让每个关节转起来，看看大臂和小臂怎么联动？”这个问题把我从”结构展示”推到了”数字孪生”。

这里说的数字孪生不是产线级仿真，而是一个能在浏览器里讲清运动关系的交互模型：六个关节可以独立驱动，爆炸图按总成分层，外壳能透视或剥离，剖面能实时切，点击标注还能看材料和规格。今天放上来的版本把 Three.js、Tailwind 运行时和字体全部本地化，下载后双击就能离线跑。

53 秒演示：关节驱动 → 自动巡航 → 爆炸分层 → 透明外壳 → Z 轴剖面 → 部件检视 → 复位

一、先把数字孪生拆成三层

最容易写乱的地方，是把模型、运动状态和界面混在一个函数里。我把它拆成三层：

模型层：底座、J1 回转台、J2 肩部、J3 肘部、J4 小臂、J5 腕部、J6 法兰和夹爪，各是一个 Group，子级继承父级的旋转。
状态层：joints、explodeFactor、shellMode、sectionEnabled、selectedPartId 等，所有 UI 只改这一层。
表现层：HUD、滑块读数、标注点、检视器卡片，只负责把状态画出来。

六轴的旋转轴和范围如下：

关节	旋转轴	作用	滑杆范围
J1	Y	腰部回转	−180° ~ 180°
J2	Z	肩部俯仰	−95° ~ 95°
J3	Z	肘部俯仰	−120° ~ 120°
J4	X	小臂回转	−180° ~ 180°
J5	Z	腕部摆动	−125° ~ 125°
J6	X	末端法兰旋转	−360° ~ 360°

1600×900 下的默认视图：左侧检视器，右侧四个控制标签页。

模型层里每个可拾取零件还带一份元数据：名称、材料、所属层级、峰值扭矩和重复定位精度。它不是渲染必需的，但决定了点选之后检视器里能显示什么。把元数据和几何分开，改文案不用动模型，换模型也不用重写信息卡。

这样分层以后，加一个视角预设不需要碰模型，改一个显示模式也不用重写 UI；反过来，模型换一套几何，状态和界面仍然能复用。

二、六轴联动：转 Group，不要逐个转 mesh

J1 转到 70°、J3 转到 75° 后的姿态，右侧滑杆与模型实时联动。

关节运动的核心只有几行：

function applyJointKinematics() {
  const deg2rad = Math.PI / 180;
  j1Group.rotation.y = state.joints.j1 * deg2rad;
  j2Group.rotation.z = state.joints.j2 * deg2rad;
  j3Group.rotation.z = state.joints.j3 * deg2rad;
  j4Group.rotation.x = state.joints.j4 * deg2rad;
  j5Group.rotation.z = state.joints.j5 * deg2rad;
  j6Group.rotation.x = state.joints.j6 * deg2rad;

  const strokeOffset = 0.05 + (state.joints.grip / 100) * 0.23;
  const baseL = explodableItems.find(it => it.mesh === fingerLeftGroup);
  const baseR = explodableItems.find(it => it.mesh === fingerRightGroup);
  if (baseL && baseR) {
    baseL.basePos.z = strokeOffset;
    baseR.basePos.z = -strokeOffset;
  }
  applyExplodedState();
}

关键是旋转的是 Group，不是某个外壳 mesh。J2 一转，挂在它下面的大臂、肘部、小臂和腕部都会跟着走；如果逐个转 mesh，零件之间的父子关系就会散掉，看起来像一堆零件在原地打转。夹爪的手指没有用旋转，而是改 basePos 的 z 偏移，再把结果交给爆炸函数，保证”开合”和”爆炸”能同时存在。

这里有个顺序问题：关节和爆炸都会改零件位置，所以必须先更新关节，再调用 applyExplodedState()。否则爆炸位移会基于上一帧的关节姿态，拖滑杆时零件会跳一下。数字孪生和普通动画的区别也在这里：动画可以随便摆姿势，孪生要保证每个零件的父子关系和装配基准始终一致。

自动巡航和归零姿态也复用同一套状态。巡航时动画循环用正弦函数连续写入六个关节角和夹爪行程，本质上还是改 state.joints；归零姿态则把关节角清零、夹爪回到 50%，再走一次 applyJointKinematics()。所以巡航、手动滑杆和归零不会各写一套旋转逻辑，停下来时状态也是连续的。

三、爆炸图：目标值加帧插值

100% 爆炸：外壳、减速器和末端按各自方向分离，虚线保留装配基准。

爆炸不是把零件随机推远，而是给每个可分离件一个 explodeVec，再乘上总体系和分组权重：

function applyExplodedState() {
  const f = state.explodeFactor;
  explodableItems.forEach((item) => {
    let mult = 1.0;
    if (item.explodeType === 'shell') mult = state.expShellMult;
    else if (item.explodeType === 'gear') mult = state.expGearMult;
    else if (item.explodeType === 'gripper') mult = state.expGripperMult;

    const eff = f * mult;
    item.mesh.position.copy(item.basePos)
      .addScaledVector(item.explodeVec, eff);

    if (item.guideLine) {
      const showLine = state.showExplodeLines && eff > 0.02 && item.mesh.visible;
      item.guideLine.visible = showLine;
      if (showLine) {
        const p = item.guideLine.geometry.attributes.position.array;
        p[0] = item.basePos.x; p[1] = item.basePos.y; p[2] = item.basePos.z;
        p[3] = item.mesh.position.x; p[4] = item.mesh.position.y; p[5] = item.mesh.position.z;
        item.guideLine.geometry.attributes.position.needsUpdate = true;
        item.guideLine.computeLineDistances();
      }
    }
  });
}

外壳、减速器、末端三组有独立的分离权重。这不是装饰：外壳是径向拆、减速器是轴向拆、末端是沿法兰方向拆，统一乘一个系数，某些零件就会穿模。引导虚线的两个端点也要每帧跟着更新，否则爆炸后线还停在原位，看起来像零件被”粘”在空气里。

需要说明的是，当前动画循环用的是固定插值系数 0.12：

state.explodeFactor += (state.targetExplodeFactor - state.explodeFactor) * 0.12;

它在 60 帧下很顺，但在低帧率设备上会明显变慢，因为每帧只追 12%，帧数少了收敛就慢。如果重写这一段，我会换成 1 - Math.exp(-k * delta)，让收敛速度和帧率无关。这也是我在录演示时把等待时间拉长的原因：不是模型卡，是插值在软件渲染下走得慢。

四、透明外壳：材质和图层分开管

22% 透视：外壳成为玻璃态，电机、减速器和线束保持不透明。

外壳有四种模式：实体、22% 透视、线框和剥离。实现上只改外壳材质和图层可见性，不碰内部零件：

function applyShellAndLayerState() {
  const mode = state.shellMode;
  const opacity = state.shellOpacity;

  shellMaterials.forEach((mat) => {
    if (mode === 'solid') {
      mat.wireframe = false;
      mat.transparent = opacity < 0.99;
      mat.opacity = opacity;
      mat.depthWrite = opacity > 0.65;
    } else if (mode === 'xray') {
      mat.wireframe = false;
      mat.transparent = true;
      mat.opacity = opacity;
      mat.depthWrite = false;
    } else if (mode === 'wireframe') {
      mat.wireframe = true;
      mat.transparent = true;
      mat.opacity = Math.max(0.35, opacity);
      mat.depthWrite = false;
    }
    mat.needsUpdate = true;
  });

  const showShell = (mode !== 'hidden') && (opacity > 0.01);
  layerGroups.shells.forEach(m => { m.visible = showShell; });
  layerGroups.motors.forEach(m => { m.visible = state.visMotors; });
  layerGroups.gears.forEach(m => { m.visible = state.visGears; });
  layerGroups.skeleton.forEach(m => { m.visible = state.visSkeleton; });
  layerGroups.cables.forEach(m => { m.visible = state.visCables; });
}

模式	外壳透明度	线框	适用场景
实体	100%	否	看外观和标注
透视	22%	否	看电机、减速器和线束
线框	55%	是	看外壳拓扑和分件
剥离	0%	否	只看骨架与内部件

透视时把 depthWrite 关掉，能减少多层外壳互相遮挡产生的排序闪烁；内部零件的 visible 则由四个图层开关单独控制。这样”外壳透明”和”内部件显隐”是两条独立的链路，不会出现打开电机就顺带把外壳也改掉的情况。

透明度滑杆也不是直接去改 scene 里的所有材质，而是只遍历 shellMaterials。因为每个外壳件在建模时就登记过，内部电机和减速器用的是另一组材质；如果图省事遍历全场景，拖到 22% 时连电机也变透明，透视就失去意义了。

五、剖面：一个平面挂到所有材质

Z 轴剖面：裁剪面切掉近侧壳体，配合剖面辅助面观察内腔。

剖面用的是 Three.js 的局部裁剪面。先算方向和偏移，再把同一个平面挂到场景里所有需要被切的材质上：

function applySectionState() {
  const enabled = state.sectionEnabled;
  const axis = state.sectionAxis;
  const sign = state.sectionFlip ? 1 : -1;
  const offset = state.sectionOffset;

  if (axis === 'x') clippingPlane.normal.set(sign, 0, 0);
  else if (axis === 'y') clippingPlane.normal.set(0, sign, 0);
  else clippingPlane.normal.set(0, 0, sign);

  clippingPlane.constant = -sign * offset;

  const activePlanes = enabled ? [clippingPlane] : [];
  allClipMaterials.forEach((mat) => {
    mat.clippingPlanes = activePlanes;
    mat.needsUpdate = true;
  });

  sectionHelperGroup.visible = enabled && state.showSectionHelper;
  if (enabled) {
    sectionHelperGroup.position.set(0, 3.0, 0);
    if (axis === 'x') {
      sectionHelperGroup.position.x = offset;
      sectionHelperGroup.rotation.y = Math.PI / 2;
    } else if (axis === 'y') {
      sectionHelperGroup.position.y = offset;
      sectionHelperGroup.rotation.x = Math.PI / 2;
    } else {
      sectionHelperGroup.position.z = offset;
    }
  }
}

裁剪面必须挂到 allClipMaterials，也就是包括外壳、电机、减速器和骨架在内的全部材质。只挂外壳的话，切完会看到一个空心壳，内部零件完好地悬在空中，反而更假。方向翻转只是把法线取反，同时把 constant 一起变号，这样滑杆的正负和屏幕上切掉的一侧才能对得上。

六、标注与检视：把 3D 点投到 2D

六个总成标注不是 3D 精灵，而是普通的 DOM 按钮。每帧把锚点的局部坐标转到世界坐标，再投影到屏幕：

function updateAnnotations() {
  const w = window.innerWidth;
  const h = window.innerHeight;
  const worldPos = new THREE.Vector3();

  annotationPins.forEach((pin) => {
    if (!state.showAnnotations) { pin.el.style.display = 'none'; return; }

    worldPos.copy(pin.localOffset);
    pin.anchorObj.localToWorld(worldPos);
    worldPos.project(camera);

    if (worldPos.z > 1.0 || worldPos.z < -1.0) {
      pin.el.style.display = 'none';
      return;
    }
    const x = (worldPos.x * 0.5 + 0.5) * w;
    const y = (-worldPos.y * 0.5 + 0.5) * h;
    pin.el.style.display = 'flex';
    pin.el.style.left = `${x}px`;
    pin.el.style.top = `${y}px`;
  });
}

用 DOM 的好处是文字始终清晰、能直接点击，也能被键盘访问；代价是每帧都要同步位置。点击标注或模型后，selectPart() 会把材料、层级、峰值扭矩等字段写进左下角的检视器。页面里的扭矩、负载和 ±0.02 mm 是演示用的标称字段，不是对实物的实测，这一点我在 README 里也写明了。

模型的点击用 Raycaster，命中后先过滤不可见物体，再判断命中点是否在裁剪面的保留侧。如果剖面已经切掉了这一块，但射线还打在被切掉的几何上，用户就会选中一个屏幕上根本不存在的零件。这一步和裁剪面共用同一个 clippingPlane.distanceToPoint()，所以透视、剖面和点选不会互相矛盾。

交付：依赖本地化，双击就能跑

点击“04 肘部”标注后，检视器显示材料、层级与峰值扭矩字段。

这个页面最初从 CDN 加载 Three.js r128、Tailwind 运行时和 Google Fonts。为了让实验室的离线机器和博客读者都能直接打开，我把三样都放进了 vendor/：Three.js 和 Tailwind 运行时是本地 JS，Inter 和 JetBrains Mono 只保留拉丁字形，中文回退到系统字体。改完后用 file:// 打开，监听网络面板确认没有外部请求，控制台也没有应用报错。

交付物是一个 53 秒的功能演示、一个约 16 秒的模式 GIF，以及仓库里的 index.html 和 vendor/。演示是在 1600×900 下逐项操作录的：关节滑杆、自动巡航、100% 爆炸、22% 透视、Z 轴剖面、部件检视和一键复位。

在线演示：https://blog.sakurajh.xyz/aero-6x-digital-twin/
源码与离线包：https://github.com/sakurajh/aero-6x-digital-twin
完整演示视频：https://blog.sakurajh.xyz/aero-6x-digital-twin/demo/aero-6x-demo.mp4

下一步我想把关节运动换成带加减速的轨迹规划，再补一个”示教点位”功能：把几个姿态存下来，按顺序回放。这样它会更像真正的数字孪生，而不只是一个能拖滑杆的模型。

把 OpenMV 的识别结果接到网页上：串口转 WebSocket 的最小闭环

Sat, 24 Oct 2026 22:02:00 +0000

上周调 OpenMV 的巡线，摄像头架在车上，笔记本离得很远。OpenMV IDE 里能看画面和色块框，但一旦把串口交给主控，IDE 就得断开，等于画面和实际运行状态二选一。我想要的其实很简单：板子照常跑自己的程序，笔记本浏览器里开一个页面，实时看到识别出的矩形框。不用装 Qt，不用写桌面程序，换台电脑打开网页就能看。

一开始我试着让浏览器直接读串口，很快就放弃了。Web Serial 只能用在那几个 Chromium 内核的浏览器里，页面必须是 localhost 或 HTTPS，而且串口在 Windows 上同一时刻只能被一个进程打开，OpenMV IDE 开着就抢不过来。更麻烦的是刷新页面之后端口要重新授权，调试时刷新是家常便饭。

最后的做法是把问题拆成两半：OpenMV 只管往串口写识别结果，Python 起一个小进程把串口数据转成 WebSocket 广播出去，网页只负责连上和画框。整个项目四个文件，加起来一百多行，跑起来就再没换过方案。

为什么不直接在浏览器里读串口

把识别结果送到浏览器，常见有三条路，我实际都试过，差别比想象中大。

方案	依赖	能否在画面上叠加框	页面刷新/断线	适合的场景
Web Serial	Chromium 内核浏览器、HTTPS 或 localhost	能，但要自己解析字节流	需要重新点选端口授权	临时调试，只在一台机器上
MJPEG 推流	OpenMV 端持续输出 JPEG、带宽较高	不能，得在 OpenMV 端把框画进图里	推流进程断了要重开	只想看画面，不需要结构化数据
串口转 WebSocket	Python + pyserial + websockets	能，拿到的是坐标	前端自动重连即可	长期运行、多台设备看同一份数据

我选第三条，核心理由是它保留了”结构化数据”这个属性。坐标是数字，网页想画框就画框，想画热力图就画热力图，想存下来做回放也行。MJPEG 把框烧进像素里，前端就再也拿不到坐标了，改一次样式要重新烧一次固件。Web Serial 虽然也是结构化数据，但它的授权模型和”同一时间只能有一个进程持有串口”这两点，让它在有 IDE 参与调试时很难用。

另外一个现实原因是解耦。桥接进程和网页之间走的是本机 WebSocket，同局域网里换一台机器，把地址里的 127.0.0.1 换掉就能看。OpenMV 那边完全不知道浏览器存在，它只是往串口写一行行文本。

协议：一行一个 JSON

协议定得好，后面两头都省事。我用的规则只有一条：一行一个 UTF-8 JSON，以换行结尾。

选行分隔而不是固定长度或二进制包头，是因为它自带同步能力。串口刚打开时双方状态不一致，读到的第一行很可能是半截，解析失败的丢掉就行，下一行自然从换行符之后开始，不需要额外的握手和对齐逻辑。我在串口助手里也能直接看明文，调阈值时不用另写解析工具。

代价是要防一行过长。如果波特率不匹配或者线接触不良，读到的可能是连续乱码，没有一个换行，缓存会一直涨。所以桥接进程里我限制单行最大长度，超过就直接丢，重新找下一个换行。

OpenMV 端用 MicroPython，把坐标归一化到 0 到 1，这样网页不用知道分辨率：

import sensor, image, time, json
from pyb import UART

sensor.reset()
sensor.set_pixformat(sensor.RGB565)
sensor.set_framesize(sensor.QVGA)
sensor.skip_frames(time=2000)

uart3 = UART(3, 115200)
thresholds = [(30, 100, 15, 127, 15, 127)]  # L A B 阈值，按现场光调
clock = time.clock()
frame = 0

while True:
    clock.tick()
    img = sensor.snapshot()
    blobs = img.find_blobs(thresholds, pixels_threshold=200,
                           area_threshold=200, merge=True)
    frame += 1
    if frame % 2:
        continue  # 每两帧发一次，给串口留余量

    w, h = img.width(), img.height()
    rects = []
    for b in blobs[:5]:
        rects.append({
            "x": round(b.x() / w, 3),
            "y": round(b.y() / h, 3),
            "w": round(b.w() / w, 3),
            "h": round(b.h() / h, 3),
        })
    uart3.write(json.dumps({"blobs": rects}) + "\n")

两处有意的克制。第一，最多只发 5 个框，色块一多，JSON 变长，串口带宽会被吃掉；真正的目标不会超过几个，多出来的对调试没有价值。第二，每两帧发一次。串口 115200 大约每秒能传一万多字节，一帧几 KB 的图传不了，但一行一百多字节的结果绰绰有余；限流是为了以后加字段时不至于把链路塞满。归一化还有个副作用：以后换 QQVGA 或 VGA，前端一行代码都不用改。

桥接进程：一个线程读串口，一个循环广播

桥接进程里最容易写错的是线程和事件循环的边界。pyserial 的 readline 是阻塞的，放进 asyncio 里会把整个循环卡住；但把整条链路都写成线程又很难处理多客户端广播。我的分工是：一个后台线程只负责读串口并解析，事件循环只负责分发。

从线程往事件循环塞数据必须用 loop.call_soon_threadsafe，不能直接操作 asyncio.Queue。队列本身不是线程安全的，直接 put 在调试时看似正常，压力一上来就会出现丢消息或者队列内部状态错乱。另外我给这个分发队列设了上限，满了就丢新帧——实时监控里，丢一帧的代价远小于积压十秒后突然把过期画面一股脑推给前端。

import asyncio, json, threading
import serial, websockets

PORT, BAUD = "COM5", 115200
clients = set()          # 每个客户端一个 asyncio.Queue
loop = None

def reader(q):
    ser = serial.Serial(PORT, BAUD, timeout=1)
    while True:
        raw = ser.readline()
        if not raw or len(raw) > 2048:
            continue
        try:
            msg = json.loads(raw.decode("utf-8", "ignore"))
        except ValueError:
            continue
        if isinstance(msg.get("blobs"), list):
            loop.call_soon_threadsafe(enqueue, q, msg)

def enqueue(q, msg):
    if q.full():
        return
    q.put_nowait(msg)

async def pump(ws, q):
    while True:
        await ws.send(await q.get())

async def handler(ws, path=None):
    q = asyncio.Queue(maxsize=16)
    clients.add(q)
    task = asyncio.create_task(pump(ws, q))
    try:
        await ws.recv()          # 只为感知断开，客户端不发数据
    except websockets.ConnectionClosed:
        pass
    finally:
        clients.discard(q)
        task.cancel()

async def main():
    global loop
    loop = asyncio.get_running_loop()
    q = asyncio.Queue(maxsize=4)
    threading.Thread(target=reader, args=(q,), daemon=True).start()

    async def fanout():
        while True:
            msg = await q.get()
            for cq in clients:
                if cq.full():
                    cq.get_nowait()
                cq.put_nowait(msg)

    async with websockets.serve(handler, "127.0.0.1", 8765):
        await fanout()

asyncio.run(main())

这里有几个决定值得说明。每个客户端单独一个队列，再加一个发送协程，是为了慢客户端不拖累别人：某个页面卡住导致 TCP 发送缓冲区满，ws.send 会挂起，但它挂起的只是自己那条协程，广播循环照常把帧分给别人。队列满了丢最旧的一帧（get_nowait 再 put），保证画面永远是最新的，延迟不会越积越大。handler 里 await ws.recv() 看着多余，其实是为了让协程一直活着并在客户端关闭时立刻收到异常；如果不读，服务端要等到下一次发送失败才知道对方走了。path=None 是为了兼容 websockets 12 之后只传一个参数的处理器签名，写成这样新旧版本都能跑。

监听地址写 127.0.0.1 而不是 0.0.0.0，默认只对本机开放。想让局域网其他设备看，再手动改成 0.0.0.0，同时清楚这个端口没有任何鉴权，别放在不可信的网段里。

前端：把归一化坐标画成框

网页其实只有一个 canvas 和一段连接逻辑。坐标是 0 到 1 的比例，乘上画布宽高就是像素位置，和摄像头分辨率完全解耦。

<!doctype html>
<meta charset="utf-8">
<title>OpenMV 识别结果</title>
<canvas id="view" width="640" height="480"></canvas>
<script>
const canvas = document.getElementById("view");
const ctx = canvas.getContext("2d");
let ws;

function connect() {
  ws = new WebSocket("ws://127.0.0.1:8765");
  ws.onmessage = (ev) => {
    const { blobs } = JSON.parse(ev.data);
    ctx.clearRect(0, 0, canvas.width, canvas.height);
    ctx.strokeStyle = "#22d3ee";
    ctx.lineWidth = 2;
    for (const b of blobs) {
      ctx.strokeRect(b.x * canvas.width, b.y * canvas.height,
                     b.w * canvas.width, b.h * canvas.height);
    }
  };
  ws.onclose = () => setTimeout(connect, 1000);
}
connect();
</script>

onclose 里重连，是因为桥接进程重启、笔记本休眠唤醒之后连接都会断，不重连就得手动刷新。没有做退避，一秒一次在本机场景下够用，也不会把日志刷爆。每次收到消息先清空画布再画，省掉维护上一帧状态的麻烦；如果以后要显示轨迹，就得改成渐变擦除或者独立图层，那是另一件事。

这个页面是”透明底”的画框层，不显示摄像头原图。这样做的好处是它可以直接叠在任意背景上，也能和 MJPEG 画面并排放在两个元素里对齐。真要画面加框，再加一个 <img> 指向 MJPEG 地址即可，但那时候两路数据的时间戳对不齐，框会略微滞后于画面，这是分开传输的固有代价，需要的话得在 OpenMV 端直接画框。

跑起来

目录结构很小：

openmv-web-bridge/
├── firmware/main.py     # 烧进 OpenMV 的程序
├── bridge.py            # 串口转 WebSocket
├── web/index.html       # 画框页面
└── requirements.txt     # pyserial, websockets

步骤只有四步：把 firmware/main.py 存到 OpenMV 的 SD 卡或闪存里运行；关掉 OpenMV IDE，否则 COM 口被占用，桥接进程会报 PermissionError；pip install pyserial websockets 后执行 python bridge.py；用浏览器打开 web/index.html。注意 bridge.py 里的 PORT 要改成设备管理器里实际的 COM 号，插不同 USB 口这个号会变。

几个我踩到的坑

现象	原因	处理
`PermissionError: could not open port`	OpenMV IDE 或串口助手占着端口，Windows 不允许多进程同时打开	关掉 IDE 和串口助手，再启动桥接
页面一直不显示框，控制台报连接失败	桥接进程没起来，或端口不是 8765	先 `curl http://127.0.0.1:8765` 确认进程活着（返回 426 也算正常）
框的位置整体偏移	网页没按原始分辨率放缩，或 OpenMV 端忘了归一化	检查是否除以了 `img.width()`、`img.height()`
偶发一整行丢失	波特率两端不一致，或串口线太长干扰	两边统一 115200，线尽量短，共地
长时间运行后页面越来越卡	客户端队列积压	确认队列有上限且满了丢旧帧，不要改成无界队列

还有一个和代码无关的坑：如果以后把页面放到 HTTPS 站点上，浏览器会因为混合内容拒绝连接 ws://。要么页面也用 HTTP，要么给桥接进程配证书走 wss://。我目前就是本机 HTTP 打开，不折腾证书。

小结

这个项目的价值不在代码量，而在把两件本来耦合的事切开了：OpenMV 只负责识别和输出结构化结果，浏览器只负责呈现，中间那层桥接进程可以随便换、随便改，两边都不用重新烧固件。协议用最朴素的一行一个 JSON，换来的是可读、可自同步、可人工排查；线程负责阻塞 IO、事件循环负责广播，是这个规模下最省心的分工。

下一步我打算在这条链路上加一个录制开关，把每帧结果和毫秒时间戳写进 JSONL，巡线跑完直接回放找丢线的位置。桥接层已经把数据变成干净的文本流了，加这个功能不需要动 OpenMV 一行代码。

Three.js 单文件离线机械臂工作台：爆炸图、透明外壳与剖面

Sat, 24 Oct 2026 06:25:00 +0000

上周给学弟讲实验室那台六轴机械臂，我指着肩部那圈橙色问他：”这是电机还是关节？”他犹豫了半天。我想打开 SolidWorks 转个角度，结果装配体在老机器上加载了好一会儿；就算打开了，也没法当场把外壳拆开，让他看到里面的减速器和传动轴。

这次之后我一直觉得，讲结构这件事，CAD 不是最合适的载体：文件重、依赖软件、发给别人还不一定打得开。我想要的是一个打开浏览器就能转、能拆、能剖的教具，最好断网也能用——实验室的工控机经常不联网。

于是有了这个项目：六轴机械臂结构工作台。48 个可点选零件、8 个总成，支持完整装配、爆炸图、透明外壳和 X/Y/Z 剖面，最后打成一个双击就能运行的 index.html。文末是在线演示和 33 秒录屏。

33 秒演示：旋转观察 → 零件拾取 → 总成聚焦 → 爆炸图 → 透明外壳 → Z 轴剖面 → 一键复位

一、先定边界：不做 CAD，只做教具

完整装配模式。左侧是 8 个总成，右侧切换四种查看方式。

动手前我把范围写死：模型程序化生成，不导入 GLB/STEP；不做关节运动仿真和物理仿真；不做后端和账号；最终产物是一个 HTML，运行时不发任何网络请求。

这个取舍很关键。如果一开始就想着”导入真实 CAD 模型”，光模型轻量化、材质、坐标系对齐就够耗一周，而且教学演示并不需要工程级尺寸精度。程序化模型反而有好处：每个零件的 ID、中文名、所属总成、爆炸方向都在代码里，点选和讲解可以精确到”肩部减速器”这种粒度，而不是”某个 mesh”。

模型按 8 个总成组织：固定底座、一轴回转台、二轴肩关节、大臂总成、三轴肘关节、四轴小臂总成、五轴腕关节、六轴末端夹具。每个总成是一个 Group，零件挂在下面；外壳零件在注册时单独记进 shellMeshes，后面透明模式要用。48 个零件都带 userData.partId，Raycaster 命中后就能反查到名称、总成和说明。

配色也没有散落在各处。整机只有五种基础材质：象牙白外壳、橙色关节环、深色金属、银色电机、黑色夹具。每个零件注册时克隆一份，所以 48 个零件仍然只有五套参数要维护，改配色不会牵一发动全身，同时又能单独改某个零件的透明度而不影响同材质的其他零件。

二、四个模式共用一个状态机

最容易写乱的地方，是四个模式各自改场景。爆炸图改了零件位置，透明模式改了材质，剖面模式又改了裁剪面，切换时如果没人负责清理，就会留下”半爆炸 + 透明 + 还在剖”的混合状态。我把它收成一个纯函数 reducer：

export const initialViewState = Object.freeze({
  mode: 'assembly', explosion: 0, shellTransparency: 0,
  clipAxis: 'x', clipPosition: 0, selectedPart: null
});

export function reduceViewState(state, action) {
  switch (action.type) {
    case 'SET_MODE': return { ...state, mode: modes.has(action.mode) ? action.mode : 'assembly' };
    case 'SET_EXPLOSION': return { ...state, explosion: clamp(action.value) };
    case 'SET_SHELL_TRANSPARENCY': return { ...state, shellTransparency: clamp(action.value) };
    case 'SET_CLIP_AXIS': return { ...state, clipAxis: axes.has(action.axis) ? action.axis : 'x' };
    case 'SET_CLIP_POSITION': return { ...state, clipPosition: clamp(action.value, -1, 1) };
    case 'SELECT_PART': return { ...state, selectedPart: action.partId ?? null };
    case 'RESET': return createViewState();
    default: return state;
  }
}

这样做有三个直接收益：所有越界值在入口就被夹住；”一键复位”只是 dispatch 一个 RESET，不用逐个模块清理；状态机不碰 DOM 和 Three.js，单元测试不需要 WebGL。

UI 层只负责把按钮和滑块翻译成 action，显示控制器只负责把 state 落到场景，两边都不保存自己的状态。这样从爆炸图直接切到剖面图，也不会出现”爆炸位移没归零”的残留；选中零件与当前模式解耦，切模式时说明面板不会被清空。

四个模式的分工如下：

模式	实际改动	可调参数
完整装配	不改几何，只做拾取与相机聚焦	无
爆炸图	零件位置 = 基准位置 + 爆炸向量 × 比例	爆炸距离 0–100%
透明外壳	外壳材质的透明度与 `depthWrite`	外壳透明度 0–100%
剖面图	所有材质的 `clippingPlanes`	X/Y/Z 轴、剖切位置

三、爆炸图：按装配方向走，不要随机散开

爆炸图 65%：总成沿各自的装配方向分离，底座保持不动。

随机给每个零件加一个方向，看起来也会”炸开”，但看不出装配关系。我的做法是给 8 个总成各定一个方向，例如回转台沿 Z 向后、肩关节沿 X 向左、大臂向上、肘关节向前、腕部和夹具向右，然后零件的爆炸向量 = 总成向量 + 自己的小偏移。底座固定不动，作为参照。

每帧只做一次插值，用指数阻尼让运动与帧率无关：

const target = basePosition.clone();
if (state.mode === 'exploded') {
  target.addScaledVector(part.explodeVector, explosion);
}
part.object.position.lerp(target, 1 - Math.exp(-12 * delta));

1 - Math.exp(-12 * delta) 这一项，在 60 帧和 120 帧下衰减速度一致；如果直接写 lerp(target, 0.2)，高刷屏上会明显更快。滑块拖动时只改比例，位移仍然由这条插值追上去，所以既有即时反馈，又不会瞬移。滑杆对外显示 0–100%，状态里存 0–1，单位转换只发生在 UI 边界，测试和渲染都用同一套数值，不会出现”65 还是 0.65”的歧义。

四、透明外壳：内部必须保持实体

透明外壳 75%：外壳变透明，内部电机、减速器和传动轴保持不透明。

透明模式失败最常见的样子，是整机一起变半透明，内部电机也跟着淡掉，最后什么都看不清。我在建模阶段就把外壳材质单独登记，切换时只动这一组：

const transparent = state.mode === 'shell' && transparency > 0;
for (const material of shellMaterials) {
  if (material.transparent !== transparent) {
    material.transparent = transparent;
    material.needsUpdate = true;
  }
  material.opacity = 1 - transparency;
  material.depthWrite = !transparent;
}
for (const material of internalMaterials) material.opacity = 1;

两个细节值得说。第一，每个零件的材质在注册时都 clone() 过，所以改外壳不会把内部零件一起染色；第二，透明时把 depthWrite 关掉，能减少多层外壳互相遮挡产生的闪烁，但内部材质始终 opacity = 1，电机、减速器和传动轴仍然是不透明的实体。needsUpdate 只在”是否透明”翻转时置位，拖滑块改透明度不需要反复重编译材质。

五、剖面图：裁剪面要挂到所有材质上

Z 轴剖面：裁剪面切掉近侧外壳，露出内部传动结构。

剖面用的是 Three.js 的局部裁剪面。渲染器先打开 localClippingEnabled，然后根据当前轴创建一个平面，法线取正轴的反方向，常数由滑杆位置映射到模型尺度：

plane.normal.set(...axisNormals[state.clipAxis]); // x:[−1,0,0] y:[0,−1,0] z:[0,0,−1]
plane.constant = state.clipPosition * 4;

const assigned = activeClipAxis ? [plane] : [];
for (const material of materials) {
  material.clippingPlanes = assigned;
  material.clipShadows = Boolean(activeClipAxis);
}

这里踩过一个坑：一开始我只把裁剪面挂给外壳，结果切开后内部零件完好无损地悬在空中，看起来像一个空心壳。裁剪必须覆盖场景里所有材质，包括内部电机和传动轴，切面才是真实的。另外 clipShadows 要跟着开，否则地面阴影还是完整的；剖面辅助线用 PlaneHelper 画出来，同时把它的 raycast 置空，避免点选时命中辅助线。

六、单文件与离线验证

构建用 esbuild 把 main.js、Three.js 和 OrbitControls 打成一个 IIFE，再把 CSS 和 JS 内联进模板。注意 replace 要传函数而不是字符串，否则压缩后的代码里出现 $& 这类片段时会被当成替换模式：

const result = await build({
  entryPoints: ['src/main.js'], bundle: true, minify: true,
  format: 'iife', target: ['es2020'], write: false
});
const js = result.outputFiles[0].text.replace(/<\/script/gi, '<\\/script');
const html = template
  .replace('/* INLINE_CSS */', () => css)
  .replace('/* INLINE_JS */', () => js);

“离线可用”不能只靠断网试一次。浏览器测试会把只有 index.html 的临时目录用 file:// 打开，监听所有请求并断言没有 http(s) 外部请求，同时收集 pageerror 和控制台错误；WebGL2 降级则用 addInitScript 让 getContext('webgl2') 返回 null，检查提示文案是否出现、有没有未捕获异常。测试结果：13 项单元测试、16 项真实浏览器测试全部通过。

检查项	验证方式
单文件	临时目录只复制 `index.html`，`file://` 打开
无外链	监听 request，断言不存在 http(s) 请求
四种模式	断言爆炸位移、外壳 0.25 / 内部 1、Z 轴裁剪生效
窄屏	390×844 下展开底部面板，复位按钮可达
WebGL 降级	屏蔽 `webgl2` 上下文，断言提示可见且无报错
空闲性能	断言无动画时停止 RAF，交互后恢复

390×844 窄屏：面板折叠为底部抽屉，3D 视口保持可见。

最后一项是我比较在意的：场景只在有动画或相机变化时渲染，静止时不空转。对教学演示这种”打开后放着讲”的场景，长期占用 GPU 没有意义。

拾取也做了同样的边界处理：pointerup 时如果指针移动超过 5 像素，就判定为拖拽旋转而不是点击，避免转完相机误选零件；点空白处则清空选中。高亮不是换材质，而是记录每个 mesh 原来的自发光颜色，选中时改成橙色，换选或复位时原样恢复，这样不会破坏外壳透明和剖面模式下的材质状态。

演示与使用

完整流程是：完整装配下旋转观察 → 点击零件看说明 → 左侧总成聚焦 → 爆炸图拉到 65% → 透明外壳拉到 75% → Z 轴剖面 → 一键复位。我录了一段 33 秒的无声演示，可以直接看操作节奏。

在线演示：https://blog.sakurajh.xyz/robot-arm-structure-workbench/
源码与单文件下载：https://github.com/sakurajh/robot-arm-structure-workbench
演示视频：https://blog.sakurajh.xyz/robot-arm-structure-workbench/demo/robot-arm-demo.mp4

如果只是想在课上或组会上讲结构，直接下载仓库里的 index.html 双击即可，不需要 Node.js、服务器或网络。模型是按教学示意生成的，不宣称工程级尺寸和装配精度；如果要继续做，我会先加关节运动学和 GLB 导入，让”看结构”和”看运动”能放在同一个页面里。

STM32F103 定时器的三种用法：PWM 输出、输入捕获与编码器接口

Sat, 24 Oct 2026 01:26:00 +0000

上个月把实验室那台老小车主控换成了 STM32F103C8T6，需求不复杂：两路 PWM 驱动 L298N 的两个电机，一路接红外接收头解 NEC 协议，另外还要读左右两个霍尔编码器测速。第一版代码写得很顺，想着 C8T6 上有四个定时器，一个功能分一个就够了。结果上车跑了十分钟，问题全来了——电机转速忽快忽慢，遥控十次里有两三次没反应，最要命的是里程数越跑越偏，直行两百米能歪出去半米。

一开始我以为是电机和编码器的机械问题，换了轮子、紧了联轴器都没用。后来把逻辑分析仪挂上去才看明白：不是代码逻辑写错了，而是 PWM、捕获、编码器这三种模式对定时器和引脚的要求完全不一样，我把它们当成三个可以随意摆放的模块，结果通道和引脚撞在了一起。

这篇把这件事拆开讲：三种模式在硬件上到底做了什么，HAL 该怎么写，以及各自有哪些不看手册就想不明白的坑。

一、三种模式共用一套时基，只是信号链不同

先建立一个统一的心智模型。一个定时器由计数单元和通道两部分组成：

计数单元：PSC 分频、CNT 计数、ARR 决定数到多少归零；
通道：每个通道有一个 CCR 寄存器，它和 CNT 比较，或者被外部边沿写入。

三种模式的区别，只是”谁在驱动谁”：

模式	数据方向	谁触发	典型用途
PWM 输出	CNT/CCR → 引脚	计数器自己	电机调速、LED 调光、舵机
输入捕获	引脚 → CCR 快照	外部边沿	测频率、测脉宽、解红外
编码器接口	引脚 → CNT 加减	A/B 相边沿	测转速、测位移

所以配置顺序永远是先时基（PSC/ARR）、再通道（CCR/极性），最后才是启动。很多人（包括当时的我）一上来就抄通道配置，忘了时基决定了后面所有数字的含义。

二、PWM：频率和占空比是两个独立的旋钮

先看公式，这三个式子决定了所有参数：

计数频率 f_cnt = f_timer / (PSC + 1)
PWM 频率 f_pwm = f_cnt / (ARR + 1)
占空比 = CCR / (ARR + 1)

我要 1 kHz 的 PWM 驱动 L298N。这里第一个坑就来了：F103 的 APB1 总线是 36 MHz，但挂在上面的定时器时钟会自动乘 2，是 72 MHz。如果按 36 MHz 去算分频，实际输出会差一倍，电机听起来会有一点点啸叫，用示波器一量才发现是 2 kHz。

#include "stm32f1xx_hal.h"

TIM_HandleTypeDef htim1;                // TIM1 是高级定时器，CH1/CH2 = PA8/PA9
TIM_OC_InitTypeDef sConfigOC = {0};

void MotorPWM_Init(void)
{
    htim1.Instance = TIM1;
    htim1.Init.Prescaler = 71;          // 72MHz / 72 = 1MHz 计数
    htim1.Init.CounterMode = TIM_COUNTERMODE_UP;
    htim1.Init.Period = 999;            // 1MHz / 1000 = 1kHz
    htim1.Init.ClockDivision = TIM_CLOCKDIVISION_DIV1;
    htim1.Init.AutoReloadPreload = TIM_AUTORELOAD_PRELOAD_ENABLE;
    HAL_TIM_PWM_Init(&htim1);

    sConfigOC.OCMode = TIM_OCMODE_PWM1;
    sConfigOC.Pulse = 0;
    sConfigOC.OCPolarity = TIM_OCPOLARITY_HIGH;
    sConfigOC.OCFastMode = TIM_OCFAST_DISABLE;
    HAL_TIM_PWM_ConfigChannel(&htim1, &sConfigOC, TIM_CHANNEL_1);
    HAL_TIM_PWM_ConfigChannel(&htim1, &sConfigOC, TIM_CHANNEL_2);

    HAL_TIM_PWM_Start(&htim1, TIM_CHANNEL_1);   // 内部会顺带打开 MOE
    HAL_TIM_PWM_Start(&htim1, TIM_CHANNEL_2);
}

/* 0~100 的百分比，转成 0~1000 的比较值 */
void Motor_SetSpeed(uint8_t percent)
{
    if (percent > 100) percent = 100;
    __HAL_TIM_SET_COMPARE(&htim1, TIM_CHANNEL_1, percent * 10);
}

void Motor_Stop(void)
{
    __HAL_TIM_SET_COMPARE(&htim1, TIM_CHANNEL_1, 0);
    __HAL_TIM_SET_COMPARE(&htim1, TIM_CHANNEL_2, 0);
}

把 PWM 放在 TIM1 上不是随手选的。高级定时器有主输出使能（MOE）和刹车、死区这些功能，HAL 的 HAL_TIM_PWM_Start 会顺带把 MOE 打开；哪天要换成 H 桥做互补输出，不用换定时器也不用改引脚，加上死区时间就行。

第二个坑藏在 __HAL_TIM_SET_COMPARE 里。HAL 在配置通道时默认打开了 CCR 预装载（OCxPE 位），也就是说你写进 CCR 的值不会立刻生效，而是等下一个更新事件（计数器归零）才搬进影子寄存器。好处是不会在周期中间改出半个脉冲的毛刺，坏处是：如果你在一个周期里连写两次，实际只有最后一次算数。我在加减速算法里连续调了两次占空比，还以为第一次被”吃掉”是硬件坏了。

还有一点，L298N 是双极性驱动，方向靠另外两根 IO 控制，PWM 只负责大小。如果直接给 0% 就相当于”滑行”，急停要改成两边都拉低或者用刹车模式，这个和定时器无关，但确实是我第一次调试时”电机停不下来”的原因。

三、输入捕获：轮询一定会漏，因为你的主循环不够快

红外接收头解 NEC，一帧大约 67.5 ms，其中最短的位间隔是 560 µs。我最初图省事，在主循环里读 GPIO 电平、用 HAL_GetTick() 算时间。只要主循环里加一句 OLED 刷新或者串口打印，一次就是几毫秒，560 µs 的位宽根本记不住，遥控自然时灵时不灵。

捕获模式的思路完全不同：边沿到来时，硬件把当前 CNT 的值直接抄进 CCR，CPU 只需要事后去取。误差只取决于定时器时钟，和主循环忙不忙毫无关系。

static volatile uint16_t lastEdge = 0;
static volatile uint8_t  phase = 0;     // 0: 等引导码下降沿，1: 已见到引导码
static volatile uint8_t  bitCount = 0;

void IR_Init(void)
{
    htim2.Instance = TIM2;
    htim2.Init.Prescaler = 71;          // 同样 1MHz，1 个计数 = 1us
    htim2.Init.CounterMode = TIM_COUNTERMODE_UP;
    htim2.Init.Period = 0xFFFF;
    HAL_TIM_IC_Init(&htim2);

    TIM_IC_InitTypeDef sIC = {0};
    sIC.ICPolarity  = TIM_INPUTCHANNELPOLARITY_FALLING;
    sIC.ICSelection = TIM_ICSELECTION_DIRECTTI;
    sIC.ICPrescaler = TIM_ICPSC_DIV1;
    sIC.ICFilter    = 10;               // 滤掉接收头上的毛刺
    HAL_TIM_IC_ConfigChannel(&htim2, &sIC, TIM_CHANNEL_1);
    HAL_TIM_IC_Start_IT(&htim2, TIM_CHANNEL_1);
}

void HAL_TIM_IC_CaptureCallback(TIM_HandleTypeDef *htim)
{
    if (htim->Instance != TIM2) return;

    uint16_t now   = (uint16_t)__HAL_TIM_GET_CAPTURE1(htim);
    uint16_t width = (uint16_t)(now - lastEdge);   // 无符号减法自动处理回绕
    lastEdge = now;

    if (phase == 0) {                   // 9ms 低电平引导码
        phase = 1;
    } else {
        NecBit_OnPulse(width);          // 560us 为 0，1690us 为 1
        if (++bitCount >= 32) {
            bitCount = 0;
            phase = 0;
        }
    }

    /* F103 的通用定时器没有 CCxNP 位，硬件双边沿只在 TIM1 上有，
       所以这里在中断里手动切换下一次要捕获的边沿 */
    __HAL_TIM_SET_CAPTUREPOLARITY(htim, TIM_CHANNEL_1,
        (phase & 1) ? TIM_INPUTCHANNELPOLARITY_RISING
                    : TIM_INPUTCHANNELPOLARITY_FALLING);
}

这段代码有三个值得说的地方。为了把重点放在捕获上，位判断只保留了骨架，实际解码时还要用宽度区分 4.5 ms 的引导高电平和 560/1690 µs 的数据位，这里用 NecBit_OnPulse 概括了。

第一，uint16_t 的无符号减法天然处理了 16 位计数器回绕。now - lastEdge 即使跨过了 0xFFFF 也是对的，不需要额外判断方向。

第二，切换极性是在中断里做的，这要求两次边沿之间的间隔大于中断响应时间。NEC 最短 560 µs，完全够用；但如果拿这套代码去解 38 kHz 载波或者更快的信号，就得上 TIM1 的硬件双边沿，或者干脆用 DMA 采样。

第三，帧与帧之间有 40 ms 以上的空闲。如果不处理，下一帧的第一个下降沿会被当成”上一帧最后一位的延续”，宽度算出来是个荒唐的大数。我的做法是开更新中断，在 HAL_TIM_PeriodElapsedCallback 里看计数是否超过某个阈值，超了就复位状态机。这也是我一开始漏掉的，表现是”按一次键出两个码”。

四、编码器模式：把计数交给硬件，别用 EXTI 硬扛

编码器最初我是用外部中断做的：A 相上升沿进一次中断，读 B 相电平判断方向，自己加一减一。台面上手拨轮子一切正常，装到车上跑起来里程就偏小，而且速度越快偏得越多。

原因很直接。第一，中断太频繁，两个轮子同时转，每转一圈几十个脉冲乘四倍频，CPU 大量时间在进出中断；第二，中断响应不及时就会漏掉边沿，而漏掉的计数补不回来。这类”低速准、高速偏小”的现象，基本可以直接怀疑是软件计数丢脉冲。

编码器模式是另一条路：A/B 两相的边沿直接驱动 CNT 加减，全程不经过 CPU。

void Encoder_Init(void)
{
    TIM_Encoder_InitTypeDef sEnc = {0};

    htim4.Instance = TIM4;
    htim4.Init.Prescaler = 0;              // 编码器不要分频
    htim4.Init.CounterMode = TIM_COUNTERMODE_UP;
    htim4.Init.Period = 0xFFFF;
    htim4.Init.ClockDivision = TIM_CLOCKDIVISION_DIV1;
    htim4.Init.AutoReloadPreload = TIM_AUTORELOAD_PRELOAD_DISABLE;

    sEnc.EncoderMode  = TIM_ENCODERMODE_TI12;   // 4 倍频
    sEnc.IC1Polarity  = TIM_ICPOLARITY_RISING;
    sEnc.IC1Selection = TIM_ICSELECTION_DIRECTTI;
    sEnc.IC1Prescaler = TIM_ICPSC_DIV1;
    sEnc.IC1Filter    = 10;
    sEnc.IC2Polarity  = TIM_ICPOLARITY_RISING;
    sEnc.IC2Selection = TIM_ICSELECTION_DIRECTTI;
    sEnc.IC2Prescaler = TIM_ICPSC_DIV1;
    sEnc.IC2Filter    = 10;

    HAL_TIM_Encoder_Init(&htim4, &sEnc);
    HAL_TIM_Encoder_Start(&htim4, TIM_CHANNEL_ALL);
}

/* 每 10ms 调一次，返回这 10ms 内的增量 */
int16_t Encoder_ReadDelta(void)
{
    int16_t delta = (int16_t)__HAL_TIM_GET_COUNTER(&htim4);  // 16 位读是单条指令
    __HAL_TIM_SET_COUNTER(&htim4, 0);
    return delta;
}

TIM_ENCODERMODE_TI12 是四倍频：A、B 两相各两个边沿都计数，所以一圈的计数是编码器线数的四倍。分辨率上去了，代价是低速时更容易被抖动误触发，所以滤波器 IC1Filter 不能省——我在电机静止时看到 CNT 偶尔自己跳一两个数，就是引脚上的噪声。

读计数这里也有个细节：读数用 int16_t 强制转换，是因为反向旋转时 CNT 会从 0 减到 65535，按有符号解释就是 -1。不清零、只算两次读数之差也完全可以，而且不会在”读”和”清”之间丢掉一个计数；但只要周期固定，每次最多丢 ±1，对测速几乎没影响。真正要小心的是长时间不清零导致 16 位回绕，跑了很久之后增量会突然变成一个大数，我一开始没做类型转换，看到速度表瞬间爆表就是这么来的。

五、我的定时器分配与选型对照

三个功能都理清之后，分配就变成了资源问题。F103C8T6 上能用的定时器就那几个，还要和引脚复用一起考虑。

功能	定时器	默认引脚	为什么选它
双电机 PWM	TIM1 CH1/CH2	PA8 / PA9	高级定时器，两通道同频，以后加死区不用换
红外 NEC 捕获	TIM2 CH1	PA0	16 位、1 MHz 计数足够，单独占用便于调状态机
左轮编码器	TIM3 CH1/CH2	PA6 / PA7	通用定时器，两通道刚好够一对 A/B 相
右轮编码器	TIM4 CH1/CH2	PB6 / PB7	同上，两个轮子必须各占一个定时器

两条硬约束必须记住：

编码器模式占用的是”通道对”。你不可能用 TIM3 的 CH1 输出 PWM、同时用 CH1 和 CH2 做编码器，因为 CH1 的 CCR 只能有一个用途。两个轮子也同理，一套 A/B 相就要吃掉一个定时器，这就是三个功能和四个定时器刚好对上的原因。这也是我第一版失败的直接原因——PWM 和左轮编码器都在 TIM3 上，编译没问题，运行起来就是互相抢通道。
PB6/PB7 默认还是 I2C1 的 SCL/SDA。如果板子上还挂着 OLED，要么把 I2C1 重映射到 PB8/PB9，要么把编码器换到 TIM2 的 CH1/CH2（PA0/PA1），然后红外改用别的口。这张引脚表建议在画板子之前就画完，别等焊完了才发现冲突。

调完之后还有一个不是定时器的问题值得提一句：电机在很低的占空比下不转。不是 PWM 配错了，而是这个占空比下电机绕组里的平均电流还克服不了静摩擦和 L298N 自身的压降。所以调速要给一个死区补偿，低于某个阈值直接给最小值，否则摇杆推了一小段车不动，推过某个点突然窜出去，手感非常差。

小结

三种模式看起来是三个外设功能，本质上是同一条信号链的三种方向：PWM 是计数器写引脚，捕获是引脚写寄存器，编码器是引脚直接驱动计数器。配置前先把时基算清楚（尤其别忘了 APB1 定时器时钟乘 2），再把”谁独占哪个通道”分配好，剩下的都是细节。至于那些不看手册绝对想不到的点——CCR 预装载、通用定时器没有 CCxNP、16 位 CNT 的回绕——踩过一次，下次画原理图的时候就会先想起来了。

给 FastAPI 接大模型：超时、重试和 token 成本该怎么管

Thu, 22 Oct 2026 22:01:00 +0000

上个月我在 python-emotion-system 的课堂答疑页接了一个大模型接口：学生上传的试卷解析成文本后，可以就某道题追问。演示时一切正常，到了真实课堂，老师反馈”点完答疑按钮一直转圈，最后报 504”。我翻日志才发现，同一个问题其实被后端发了三次，模型那边三次都生成了完整回答，而浏览器只等到一个超时页面。功能看起来只是”慢”，账单却实打实地多花了钱。

这件事让我重新梳理了从浏览器到模型服务商的整条链路。下面是我最后落下来的做法，重点不在某个模型，而在接口层怎么兜住超时、重试和成本这三件事。

一、先认清一次调用到底有几段

很多人写大模型接口时只有一行 client.post(...)，出问题却说不清卡在哪。实际上一次请求至少经过三段，每段都有自己的时间上限：

浏览器到我的 FastAPI 接口，受前端 fetch 超时、网关（Nginx）proxy_read_timeout、uvicorn worker 三者的最小值约束；
我的接口到模型服务商，受 HTTP 客户端超时约束；
模型服务商内部排队与生成，我只能通过响应状态码和 usage 间接观察。

第一段最容易被忽略：前端等了 60 秒才放弃，但网关 30 秒就断开，浏览器拿到的是 504，后端其实还在等模型。等模型返回时连接已经没人接收，日志里只留下一条”写响应失败”。所以我先把网关的超时调到比后端整体预算略大，前端再比网关大一点，让超时按照”前端 > 网关 > 后端总预算”的顺序逐级触发，这样报错会来自我自己写的业务代码，而不是一层看不懂的网关页。

二、超时不是一个数字，是四个

用 requests 时很多人不写 timeout，默认就是不设上限，模型一慢，worker 就被挂住。换成 httpx 之后至少有四个维度可以分别控制：

超时类型	管的是哪一段	设得过分小的后果	设得过分大的后果
`connect`	建立 TCP/TLS 连接	网络稍抖就失败	网络不通时白等
`read`	等下一块响应数据	正常生成长回答被腰斩	卡死的连接长期占用 worker
`write`	发送请求体	长上下文上传中断	几乎不会成为瓶颈
`pool`	等待连接池空位	并发稍高就排队失败	请求堆积，延迟雪崩

我的做法是：connect 给一个较短的值，因为连不上就是连不上，多等没有意义；read 给一个能覆盖”最长一次正常生成”的值，因为读超时一旦触发，服务商那边很可能已经算完并计费了；pool 必须设，否则高并发下请求会在池子里无声排队。

关键在于 read 超时的语义：它不代表”模型没开始干活”，只代表”我没再收到数据”。这两者的区别，直接决定了重试能不能做。

三、哪些错误能重试，哪些一重试就多花钱

我最初的错误就出在这里：把所有异常都当成”网络抖动”，while 循环重试三次。结果是读超时后重发，模型又生成一遍，token 又扣一遍。后来我给自己定了一张表：

情况	是否自动重试	原因
连接失败、连接超时	可以	请求没到达服务端，不会产生计费
429 限流	可以，且遵守 `Retry-After`	服务端明确表示没处理，退避后重发合理
5xx 网关错误	有限次重试	多数是上游临时故障，但要设上限
读超时	不要自动重试	请求可能已执行并计费，重发就是双倍成本
400 / 401 / 403 / 422	不重试	参数、鉴权、权限问题，重试只会重复报错
内容审核拒绝	不重试	同样的输入结果不会变

读超时这一行是整张表的重点。如果业务确实需要”再试一次”，我更倾向于把这个决定交还给用户：前端显示”生成超时，是否重新生成”，而不是后端偷偷重发。用户知道自己在为什么付第二次钱，也知道第一次可能已经生成了内容。

重试本身还要满足三个前提：幂等、退避、上限。退避用指数增长并加一点随机抖动，避免多个请求在同一时刻一起重发，把刚恢复的服务再打垮。

四、token 成本被什么放大了

解决了超时，账单问题才浮出水面。我把每轮调用的 usage 都记下来之后，发现三个放大器：

第一，多轮对话整段重发。 每一轮都把历史消息全部发一遍，第 n 轮要付前面所有轮次的输入 token。十轮对话的总输入量不是十份，而是接近五十五份。这不是模型的问题，是调用方式的问题。我的处理是只保留最近几轮，加上一份滚动摘要，把早期内容压缩成一段话。

第二，system prompt 和长文档重复上传。 我把整份试卷的解析文本塞进了每一轮请求。试卷内容不变，却每轮都按输入计费。后来改成首次调用生成结构化摘要，后续只带摘要和当前题目；如果服务商支持前缀缓存，就把稳定部分放在最前面，让缓存真正命中。

第三，流式响应默认不返回 usage。 这一点很隐蔽：为了打字机效果开了 stream: true，结果响应里没有 usage 字段，账单一度完全对不上。OpenAI 兼容接口需要在请求里显式打开统计选项，否则只能靠估算。

还有一个容易误判的点：max_tokens 设得大并不会直接多扣钱，它是上限不是定量。但它会拉长生成时间，让请求更容易撞上读超时；而输出 token 的单价通常高于输入，所以把回答长度约束在业务真正需要的范围内，既省钱也更快。

五、一个可以直接抄的封装

下面这段是我现在项目里用的调用封装，核心是三件事：只重试”没到达服务端”的错误、把每次 usage 落库、在调用前检查当日预算。

import asyncio
import random
import time

import httpx

RETRYABLE_STATUS = {429, 500, 502, 503, 504}


class LLMTimeout(Exception):
    pass


class LLMBudgetExceeded(Exception):
    pass


async def chat(
    client: httpx.AsyncClient,
    messages: list[dict],
    *,
    model: str,
    max_tokens: int = 800,
    budget: "TokenBudget",
) -> str:
    if budget.exceeded():
        raise LLMBudgetExceeded("今日 token 预算已用完")

    delay = 0.8
    for attempt in range(3):
        started = time.perf_counter()
        try:
            resp = await client.post(
                "/chat/completions",
                json={
                    "model": model,
                    "messages": messages,
                    "max_tokens": max_tokens,
                    "stream": False,
                },
            )
        except (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout) as exc:
            # 连接没建立，请求没到达服务端，重试不会重复计费
            if attempt == 2:
                raise LLMTimeout(f"连接模型服务失败: {exc}") from exc
        except httpx.ReadTimeout as exc:
            # 读超时可能已经生成并计费，绝不自动重发
            raise LLMTimeout("模型响应超时，请手动重新生成") from exc
        else:
            if resp.status_code in RETRYABLE_STATUS and attempt < 2:
                retry_after = resp.headers.get("Retry-After")
                wait = float(retry_after) if retry_after else delay
                await asyncio.sleep(wait + random.uniform(0, 0.3))
                delay *= 2
                continue
            resp.raise_for_status()

            data = resp.json()
            usage = data.get("usage") or {}
            budget.record(usage)
            budget.log(
                model=model,
                prompt=usage.get("prompt_tokens", 0),
                completion=usage.get("completion_tokens", 0),
                elapsed=round(time.perf_counter() - started, 3),
            )
            return data["choices"][0]["message"]["content"]

        await asyncio.sleep(delay + random.uniform(0, 0.3))
        delay *= 2

    raise LLMTimeout("重试次数已用尽")

配套的客户端是这样构造的，超时四个维度都显式给值，不依赖库的默认行为：

timeout = httpx.Timeout(connect=5.0, read=45.0, write=15.0, pool=5.0)
client = httpx.AsyncClient(
    base_url=settings.llm_base_url,
    timeout=timeout,
    limits=httpx.Limits(max_connections=20, max_keepalive_connections=10),
)

TokenBudget 我做得很简单：一个按日期分组的计数表，record 累加输入输出 token，exceeded 对比当日上限，log 写一条结构化日志。它不精确到分，但能在有人写死循环或者上下文失控时，第一时间把接口拦住，而不是等第二天看账单才发现。

六、上线前我会再确认的几件事

第一，超时链路是否逐级放大：前端、网关、后端预算必须满足从大到小的关系，否则用户看到的永远是网关错误页。

第二，日志里能不能回答”这次调用花了多少 token、等了多久、重试了几次”。这三项缺一项，出问题就只能猜。

第三，前端是否把”超时”和”失败”区分开。超时是”可能有结果也可能没有”，失败是”确定没成”，两者给用户的提示不一样，背后的计费风险也不一样。

第四，是否给历史对话设了长度上限。摘要不是可选项，是控制成本的必需品。

小结

把大模型接进后端，麻烦的从来不是那一行 POST，而是它周围的工程约束：超时要分段设置，read 超时不能随便重试，重试必须幂等且有退避上限，token 成本要从上下文长度和 usage 记录两头管。我这次的教训很直白——用户屏幕上的一次超时，在账单上可能是三次生成。把这些问题在接口层一次性收住，后面接什么模型、换什么服务商，改动都会小很多。