鸿蒙 Agent 开发实录 Day 3:一个汉字被切成两半,和生图的三次翻车

0 阅读8分钟

"把功能交给别人的接口时,就得先想好它哪天会挂。"

大家好。在上一篇博客中(Day 2),我给这个 Agent 打通了多轮记忆,还手搓了一套"沉浸光感"的毛玻璃 UI。但那时的它依然只会聊天——一个不能动手的 Agent,本质上还是个美化过的聊天框。

今天是项目开发的第三天,目标有两件事:补掉上篇评论区指出的一处底层缺陷,然后给 Agent 装上第一只"眼睛"——多模态生图。

在动手之前,我给自己定下了今天的信条:能换的东西,绝不写死。

这篇文章,记录了我怎么在字节层重写流式解析,以及为了让 Agent 画出第一张图,连续翻车三次、最后把生图重构成可切换通道的全过程。


🔍 架构修补:被一针见血指出的"半个汉字"

我 Day 1 那篇文章下面,有一位叫网友留言,指出我的流式解析在多字节字符截断上有 bug。

他说得完全正确,而我自己测试时一次都没撞上——中文回答没乱码,纯粹是运气好。

现象

流式输出时,极偶尔会蹦出一个 �,或者整段回复突然错位。发生概率不高,但只要出现,后面的内容就全乱了。

原因:三个事实叠加

  1. UTF-8 里一个汉字占 3 个字节,不是 1 个。
  2. dataReceive 回调给的 ArrayBuffer 边界是随机的,它可能在任何一个字节位置切开,包括一个汉字的中间。
  3. 字符串解码是不可逆的。我原来的写法是"收到就 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. 三条工程约束

  1. 串行队列 + 4000 毫秒最小间隔:免费档并发限制很紧,UI 上连点两次就会撞上,队列保证任何时刻只有一个请求在飞。
  2. 明确超时与错误码翻译:connectTimeout 15 秒、readTimeout 90 秒,超时主动 destroy;429 翻译成"请求太频繁,被接口限流了",401/403 翻译成"API Key 无效"。用户看到的是人话,不是一个转不完的圈。
  3. 状态四态化:之前 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 感兴趣,欢迎关注我,我们评论区交流!