开篇：那个让人抓狂的 30 秒

先说个场景，做过的同学一定秒懂。

页面上放了个「生成设备巡检报告」按钮，用户点下去之后——光标闪啊闪，屏幕一片空白，10 秒、20 秒、30 秒……然后「啪」的一下，2000 个字整整齐齐地砸在屏幕上。

用户的心路历程通常是这样的：

第 5 秒：在跑吧？ 第 15 秒：是不是卡死了？ 第 25 秒：我点错了吗？（开始狂点第二次）

问题从来不是"慢"，而是"不知道它在跑"。

更要命的是，这个坑是我们自己挖的：为了做 AI Workflow 范式的智能体，我们主动关掉了 AI 对话单元格的「自动回复」——结果连带着把流式输出也关掉了。

活字格 V12.1 就是来填这个坑的。

一、先说结论：V12.1 把流式输出"解耦"了

一句话概括这次增强：

V12.1 把「谁能产生流式结果」和「谁来显示流式结果」这两件事解耦了。

以前，流式输出是 AI 对话单元格「自动回复」的内置能力，开关一关就没了。

现在，流式输出变成了一条可被编排的管道：

• 服务端命令（AI 助手命令）能往管道里写
• 前端 AI 助手命令能往管道里写
• 你自己写的插件能往管道里写
• JavaScript（JSAPI）也能读这条管道
• AI 对话单元格只负责一件事：渲染

能力边界对比如下：

二、为什么会有这个问题：两种智能体范式的分岔

活字格里做 AI 智能体，基本就两条路。

路线 A：Agent 范式

• 一个大模型 + 一堆工具
• 让 AI 自己决定"下一步调哪个工具"
• 实现简单：AI 对话单元格开启自动回复即可
• 代价：流程不可控，同样的提问可能走出不同路径，排查问题时比较头疼

路线 B：AI Workflow 范式

• 开发者用命令把流程固定成节点：查数据库 → 拼 Prompt → 调模型 → 写回表 → 发通知
• 可控、可复现、好交付，企业场景里更吃香
• 实现方式：AI 对话单元格禁用自动回复 ​+ AI 助手命令编排各节点
• 代价：AI 助手命令要跑完整条链路才返回结果，用户只能干等

看出矛盾了吧？

你要流程可控，就得关掉自动回复；你关掉自动回复，就失去了流式输出。

而 AI 助手命令执行的恰恰是最耗时的那段逻辑（查库、调模型、写表），几十秒是常态。体验不好，锅却不在模型，在"过程不可见"。

V12.1 的解法很干脆：既然自动回复和流式输出绑定在一起不合理，那就拆开。

三、4 步配置：服务端命令 + AI 对话单元格

这是最常用的一条路径，建议收藏。

步骤 1｜ 服务端命令里勾选「返回流式结果」

打开服务端命令，找到 AI 助手命令，勾选 返回流式结果 选项。

步骤 2｜ 确认服务端命令的流式标识

勾选之后，服务端命令列表里这条命令会出现 「返回流式结果」 的标识，说明这条命令已经具备流式输出能力。

步骤 3｜ 页面上勾选「禁用 AI 自动回复」

在页面中放置 AI 对话单元格，勾选 禁用 AI 自动回复。

这一步是告诉单元格：你别自己回答了，等着别人喂给你。

步骤 4｜ 调用命令时绑定「输出流式结果至」

在页面里调用该服务端命令，在命令参数中把 「输出流式结果至」 选择为刚才那个 AI 对话单元格。

实现效果

配置速查表

一句话原理：AI 对话单元格关掉了自己的"嘴巴"（自动回复），但保留了"字幕屏"（流式渲染）。服务端命令每写一块数据，字幕屏就多一行——看起来就跟开着自动回复一模一样。

⚠️ 三个容易踩的坑

1. 两个开关必须成对出现。只勾服务端命令、忘了勾「禁用 AI 自动回复」，结果就是单元格自己回一遍、服务端命令又回一遍，两条输出叠在一起。
2. 「输出流式结果至」只能选当前页面上的 AI 对话单元格，跨页面选不到，别在弹窗里白找半天。
3. 最终返回值不会自动补上。从官方示例可以看到，return new ExecuteResult() 并不会把返回值追加到单元格里——需要流式展示的内容，必须显式调用写入方法逐块写出（见第五节代码）。

四、前端 AI 助手命令：2 步就够了

如果你的流程不经过服务端（比如纯前端的简单编排），用前端 AI 助手命令同样支持，操作更简单：

1. 勾选 返回流式结果；
2. 调用时把 「输出流式结果至」 指向对应的 AI 对话单元格。

配置和用法与服务端命令一致，不再赘述。

五、插件开发者：怎么实现自定义流式输出

如果你想通过插件实现自己的流式效果（比如接自研大模型、接 MQTT 数据、接工业协议采集结果），V12.1 提供了完整的扩展点。

5.1 服务端命令插件（C#）

三个关键点：

⚠️ 实践提醒：if (dataContext.ReturnStreamingResult) 为 false 的分支一定要写。否则非流式调用方（比如定时命令调用、其他页面调用）会拿到一个空结果。

5.2 单元格类型插件（TypeScript / JavaScript）

三个方法对应完整的流式生命周期：

两个实操要点：

• addStreamingMessage** 会被高频调用**。如果在里面做 DOM 重排、正则匹配、Markdown 渲染，逐字输出时很容易掉帧。建议做批量缓冲（攒够 N 个字符或每 50ms 渲染一次），或者用 requestAnimationFrame 合并。
• abortController** 要透传下去**。用户点"停止生成"时，框架通过它发出中断信号——你需要把它传给 fetch 的 signal 参数，才能真正取消掉尚未完成的请求，而不是"界面停了、后台还在烧 token"。

💡 提效小技巧：插件骨架这些活儿，现在可以让 AI 干。活字格 MCP（hzg-mcp）能让 AI 理解活字格的代码规则，你只要说"帮我生成一个支持流式输出的单元格类型插件"，骨架 + 属性配置就出来了，比从零手写快得多。

六、JSAPI 同步升级：executeServerCommand 也支持流式

为了让 JavaScript 侧也能灵活调用，V12.1 同步升级了 executeServerCommand JSAPI，现在它支持流式输出调用。

这个升级的价值在于自定义场景：流式结果不再只能渲染到 AI 对话单元格里，你可以把它接到任何地方——

• 自己写的 React 聊天面板
• 3D SCADA 设备监控组件（实时刷新设备状态）
• ECharts 图表（数据边算边画）
• 日志/控制台风格的调试面板

换句话说，V12.1 把流式能力从"单元格内部机制"开放成了"平台级 API"。

七、小结

回到开头那个"等 30 秒然后砸出 2000 字"的场景。

V12.1 做的这件事，本质上是把流式输出从 「AI 对话单元格的内置功能」，升级成了 「平台的通用能力」：

• 命令能写（服务端 / 前端 AI 助手命令）
• 单元格能收（AI 对话单元格）
• 插件能自定义（C# 服务端命令 + TS 单元格类型）
• JSAPI 能调（executeServerCommand）

关掉自动回复，不再等于放弃流式输出。 流程可控性和交互体验，这次终于能同时要了。