"把功能交给别人的接口时,就得先想好它哪天会挂。"
大家好。在上一篇博客中(Day 2),我给这个 Agent 打通了多轮记忆,还手搓了一套"沉浸光感"的毛玻璃 UI。但那时的它依然只会聊天——一个不能动手的 Agent,本质上还是个美化过的聊天框。
今天是项目开发的第三天,目标有两件事:补掉上篇评论区指出的一处底层缺陷,然后给 Agent 装上第一只"眼睛"——多模态生图。
在动手之前,我给自己定下了今天的信条:能换的东西,绝不写死。
这篇文章,记录了我怎么在字节层重写流式解析,以及为了让 Agent 画出第一张图,连续翻车三次、最后把生图重构成可切换通道的全过程。
🔍 架构修补:被一针见血指出的"半个汉字"
我 Day 1 那篇文章下面,有一位叫网友留言,指出我的流式解析在多字节字符截断上有 bug。
他说得完全正确,而我自己测试时一次都没撞上——中文回答没乱码,纯粹是运气好。
现象
流式输出时,极偶尔会蹦出一个 �,或者整段回复突然错位。发生概率不高,但只要出现,后面的内容就全乱了。
原因:三个事实叠加
- UTF-8 里一个汉字占 3 个字节,不是 1 个。
dataReceive回调给的ArrayBuffer边界是随机的,它可能在任何一个字节位置切开,包括一个汉字的中间。- 字符串解码是不可逆的。我原来的写法是"收到就
toString('utf-8'),再按换行切",一旦切点落在汉字中间,�就已经变成字符串了,再往后拼也拼不回来。
所以这不是"偶发乱码",这是我在错误的层次上处理了协议。
破局方案:在字节层拼包,只解码完整的行
typescript
// 🚨 核心修复:字节层拼包(ChatService.ets)
private feed(chunk: ArrayBuffer): string {
const incoming: Uint8Array = new Uint8Array(chunk);
const merged: Uint8Array = new Uint8Array(this.pending.length + incoming.length);
merged.set(this.pending, 0);
merged.set(incoming, this.pending.length);
// 从后往前找最后一个换行符(0x0A):它之前的内容才是完整的
let cut: number = -1;
for (let i = merged.length - 1; i >= 0; i--) {
if (merged[i] === 0x0A) { cut = i; break; }
}
if (cut < 0) {
this.pending = merged; // 连一个换行都没有,全部留着等下一条
return '';
}
const complete: Uint8Array = merged.slice(0, cut + 1);
this.pending = merged.slice(cut + 1); // 剩下的半截留给下一次
return buffer.from(complete.buffer).toString('utf-8');
}
改动只有二十行,但它把整个模型换掉了:
- 旧模型是"字符串流" :收到什么都先转成文字再说。
- 新模型是"字节流 + 行协议" :字节是事实,字符串只是某一行的解释结果。
一句话总结:先按协议边界切,再按编码解码。顺序反了,就是两小时的代价。
🎨 多模态首战:一句话换一张图
债还完了,开始上功能。
我想做的最基础的多模态能力是:你描述一个画面,Agent 给你画出来。
最初的链路是两段:中文提示词 → 大模型翻译成英文 → 拿去调免费生图接口。第一次跑通时,图确实在气泡里渲染出来了,圆角、发光边框都在,我当时挺得意的——然后就开始连着翻车。
🕳️ 三次翻车实录
坎一:白图 —— 最安静的一次失败
现象:气泡里出现一个纯白的方框,没有任何报错。
原因:不是渲染错了,也不是接口挂了,而是链路上的翻译环节超时了。中文提示词没翻成英文,空字符串照样被传给生图接口——它不报错,它老老实实给你画了一张白板。
破局方案:换掉需要翻译的方案,改用智谱的 cogview-3-flash。它直接吃中文,链路从两段变一段,白图的根源被物理消除。
教训:一个链路里塞两次模型调用,失败会以"看起来正常"的方式出现。白色图片不是错误,它是一次语义上的空输入。
坎二:限流 —— HTTP 200,图是空的
现象:图能出了。我兴奋地连测几次,然后接口开始返回无效图。
原因:免费接口的限流不是"变慢",是直接装死。它依然返回 200,只是给你空的、或者一张 1×1 的图。
破局方案:两条防线。第一条是串行队列,所有生图请求排进一条静态 Promise 队列,同一时刻只有一个在飞,两次之间强制间隔 4000 毫秒;第二条是主备双通道,主通道被打回来就自动换备用通道再试一次。
教训:免费额度不是免费的,它用不稳定性收利息。你省下的是钱,付出的是调试时间。
坎三:它不知道"篮球场"是长方形的
现象:我输入"一个篮球场",它给我画了一个棕红色的圆形,中间几团说不清的色块。
原因:不是画质问题,不是提示词问题,是这代模型的常识问题。那个免费接口底层跑的是很老的 Stable Diffusion 版本,对"篮球场是长方形、有两个篮筐、地板有边线"几乎没有概念。
破局方案:换模型。这不是我能靠代码修的——我在优化代码,但问题不在代码里。换不换写法的区别,只是同样一张烂图出得更快一点。
教训:把架构限制当 bug 修,是新手最容易陷进去的坑。识别出"这不是我的代码问题",比修好十个 bug 值钱。
🔀 架构重构:把"用谁生图"变成可替换的通道
三次翻车之后,我做了一件比修 bug 更重要的事:不再把生图写死在任何一个接口上。
1. 双通道设计
- 主通道:智谱
cogview-3-flash,中文提示词直接可用,免费。 - 备用通道:硅基流动
Kwai-Kolors/Kolors,需要实名,免费。 - 切换策略:主通道超时、限流、额度用尽时,自动降级到备用通道重试一次。
2. 三条工程约束
- 串行队列 + 4000 毫秒最小间隔:免费档并发限制很紧,UI 上连点两次就会撞上,队列保证任何时刻只有一个请求在飞。
- 明确超时与错误码翻译:
connectTimeout15 秒、readTimeout90 秒,超时主动destroy;429翻译成"请求太频繁,被接口限流了",401/403翻译成"API Key 无效"。用户看到的是人话,不是一个转不完的圈。 - 状态四态化:之前 UI 只有一个
loading布尔值,于是出现了"图都出来了,圈还在转"这种荒唐状态。现在每条消息带一个status:streaming/loading-image/done/error,UI 按状态渲染。
状态机比布尔量诚实。
💻 阶段成果与核心代码
下面是这一天的两处核心改动。
1. 生图请求的超时与错误码兜底
typescript
// 统一的 POST 配置(ImageGenService.ets)
const options: http.HttpRequestOptions = {
method: http.RequestMethod.POST,
header: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${key}`
},
extraData: payload,
expectDataType: http.HttpDataType.STRING,
connectTimeout: 15000,
readTimeout: 90000
};
// 回调里按 responseCode 分流:429 限流 / 401 鉴权 / 其他 4xx 原样透出
2. 主备通道自动降级
typescript
// 主通道失败不抛异常,直接换备用通道再试一次
const first: ImageGenResult = req.provider === 'siliconflow'
? await this.callSiliconFlow(req)
: await this.callZhipu(req);
if (first.ok) { return first; }
const second: ImageGenResult = req.provider === 'siliconflow'
? await this.callZhipu(req)
: await this.callSiliconFlow(req);
return second.ok ? second : mergeFailure(first, second);
⚠️ 一个我必须写下来的限制
智谱和 Kolors 这两个免费模型,都是纯文生图,不支持图生图。
也就是说,"把上一张图改成印象派"这种需求,现在只能靠提示词拼接重新画一遍——画出来的不是同一张图的变体,只是风格相近的另一张。
我一开始想硬修,后来想清楚了:这是免费档的硬限制,不是我的 bug。把它写进文档,比假装它能用要诚实。
🚀 下一步计划:让它学会"动手"
现在,这个 Agent 已经能做到:
- 真机流式对话,中文零乱码(字节层拼包)。
- 记住上下文(
messages数组)。 - 深色沉浸 + 毛玻璃 + 呼吸光晕的 UI。
- 生成图片,且生图通道可切换、可降级。
但它现在依然只是个"会聊天的壳子"。
接下来的 Day 4-5,要真正触及 Agent 的灵魂:Tool Calling(工具调用)与 ReAct 循环。
- 在沙箱中搭建显式的
Map<string, ToolHandler>。 - 实现第一个本地工具(如获取时间、读取沙箱文件)。
- 跑通核心闭环:用户提问 -> 模型判断意图并返回 JSON -> 本地执行工具 -> 结果回传模型 -> 模型生成最终回复。
🌟 写在最后
今天下午,我对着一个白框改了两个多小时。有人可能会说:"一个学生项目,图能出来就行,别钻牛角尖。"
但我今天真正记住的,恰恰不是"图出来了"这件事。
三个坑里,没有一个是我代码写错,却全都由我的代码表现出来了。白图是翻译超时,限流是接口装死,篮球场是模型太老。如果我盯着自己那几百行改,改到天亮也改不出来。
所以今天学到的是两件事:一是分清"我的问题"和"别人的问题";二是依赖别人之前,先给自己留好退路——主备通道、超时、队列,都是这个意思。这两件事跟技术高低关系不大,跟能不能把项目做完关系很大。
对于这个端侧 Agent,我的想法很朴素:手机在手就能用,不欠谁的接口,也不怕哪天醒来它被关停。
这条路还很长,我会持续更新开发进度与踩坑记录。如果你也对鸿蒙原生开发、端侧 AI 感兴趣,欢迎关注我,我们评论区交流!