开篇：那个让人抓狂的 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 对话单元格关掉了自己的"嘴巴"（自动回复），但保留了"字幕屏"（流式渲染）。服务端命令每写一块数据，字幕屏就多一行------看起来就跟开着自动回复一模一样。
⚠️ 三个容易踩的坑
- 两个开关必须成对出现。只勾服务端命令、忘了勾「禁用 AI 自动回复」，结果就是单元格自己回一遍、服务端命令又回一遍，两条输出叠在一起。
- 「输出流式结果至」只能选当前页面上的 AI 对话单元格，跨页面选不到，别在弹窗里白找半天。
- 最终返回值不会自动补上 。从官方示例可以看到，
return new ExecuteResult()并不会把返回值追加到单元格里------需要流式展示的内容，必须显式调用写入方法逐块写出（见第五节代码）。
四、前端 AI 助手命令：2 步就够了
如果你的流程不经过服务端（比如纯前端的简单编排），用前端 AI 助手命令同样支持，操作更简单：
- 勾选 返回流式结果；
- 调用时把 「输出流式结果至」 指向对应的 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）
关掉自动回复，不再等于放弃流式输出。 流程可控性和交互体验，这次终于能同时要了。