PocketOracle 的 AI 解卦是个违和感很强的功能:一块 200×200 的黑白墨水屏、一颗 4MB flash 的 ESP32-C3,摇一摇签,然后让大模型给你解卦。实现上没有魔法——一块 ESP32-C3 完全当得起一个合格的 HTTPS 客户端——但有几个决策值得展开:TLS 证书怎么塞、SSE 为什么要自己解析、以及一条最容易被忽略的约束:AI 的输出必须落在字库的字集里。
总体形状
流程是一次标准的 OpenAI 兼容调用:检查 NVS 里的 API key → 连 WiFi、SNTP 对时 → POST /chat/completions,"stream": true → worker 任务收 SSE 流 → 进度屏上字数跳动 → 答案分页上屏。
重活全部压在 worker 任务自己的栈上,UI 线程只碰几个静态变量,遵守一条单核 C3 上的朴素规则:s_state 最后写,UI 只在状态离开 RUNNING 后才读答案缓冲——单核的任务切换本身就是内存屏障,不需要锁。
TLS:证书是打包问题,不是代码问题
mbedtls 握手是这套流程里最重的单项:worker 栈给到 12KB(LLM_STACK = 12288,注释原话:mbedtls handshake + cJSON churn)。证书校验用 esp_crt_bundle——把 Mozilla 根证书集打进固件,crt_bundle_attach = esp_crt_bundle_attach 一行接上。自己的代码里没有一行证书逻辑,这是「打包问题,不是代码问题」的典型:flash 里多花一点空间,换掉「跳过证书校验」这个在消费设备上不可接受的选择。
为什么手写 SSE 解析
答案也可以不流式:发个普通请求,转个圈,等完整 JSON。但一个 200 字的答案在移动网络下要等十几秒,墨水屏设备上「转圈」是一块静止的屏幕——不可接受。流式的真正价值是进度可见:答案一边到,进度屏上的字数一边涨。
SSE 的格式简单到不需要库。整个解析器就是一个逐字符状态机:
static void sse_feed(sse_t *sse, const char *data, int len)
{
for (int i = 0; i < len && !sse->done; i++) {
char c = data[i];
if (c == '\n') {
sse->line[sse->len] = 0;
if (strncmp(sse->line, "data:", 5) == 0) {
const char *p = sse->line + 5;
while (*p == ' ') p++;
sse_line(sse, p); // cJSON 解析,取 delta.content
}
sse->len = 0; // event:/id:/注释行全部忽略
} else if (c != '\r' && sse->len < LLM_LINE_MAX - 1) {
sse->line[sse->len++] = c;
}
}
}行缓冲 + data: 前缀 + [DONE] 终止符,三十行搞定。模型输出的每个 delta.content 片段不落盘、不拼接原始 JSON——收到即消毒:
if (cp > 0xFFFF) continue; // emoji / Ext-B:字库里没有,丢
if (cp < 0x20 && cp != '\n') continue;
if (cp == '*' || cp == '#' || cp == '`') continue; // markdown 碎渣
if (cp == 0x3000) cp = ' '; // 全角空格 → ASCII每个码点当场 UTF-8 重编码进答案缓冲,超长截断。流式解析和消毒在同一趟里做完,不给他们分开的机会。
进度屏:慢显示上的流式反馈
这里有个小的自相矛盾:答案流式到达是为了「有反馈」,可墨水屏恰恰是个慢显示。解法是重绘节流——llm_poll() 返回已收到的字数,攒够 24 个新字才重画一次进度屏,走 DU 快刷(约 0.3s,见刷新那篇):
if (chars >= shown + 24) { // gate redraws: fast refresh ≈0.3s
shown = chars;
draw_ai_status(S_AI_THINK, "N 字");
ui_fast_refresh_or_sleep(sleep_us);
}流式到达的每个字节都被计数,但只有整数步进会惊动玻璃。期间任意 SW2 取消——等待必须可打断,这是给慢设备做等待界面的底线。
会认字的提示词
最有意思的约束藏在 system prompt 里:
只用简体中文常用字,不用生僻字、繁体字、emoji、markdown 符号或英文,全文不超过 180 字。
这不是文风偏好,是字库覆盖约束。CJK 字形表是按「UI 文案 + 语料」收编的固定子集(7131 字),AI 信口说一个子集外的字,屏幕上就是一个空心框。与其在解码侧兜底(能兜,但框终究难看),不如在源头让模型自己避开字库外的字——提示词工程的第一性原理在这里具象化:系统提示词是输出通道的规格说明书,通道只支持字库子集里的字,规格就照着字库子集写。
配套的还有双层保险:提示词要求「一句话点明吉凶,再分事业/感情/财运/健康各一句,一句暖心收束」——结构化输出让 180 字的答案在墨水屏上天然分页;max_tokens = 300 是硬闸,答案缓冲 3072 字节永远够。
小结
一次 4MB 设备上的 LLM 调用,拆开是四件小事:证书 bundle 解决 TLS 打包、三十行状态机解决 SSE、字数节流解决慢显示反馈、提示词解决字库覆盖。没有一件需要「端侧大模型」那种剑拔弩张——客户端的门槛从来不在算力,在于你有没有把通道的物理约束翻译成协议层的规格。