Forward quiet file-subtask EventBus frames while wait blocks, coalesce DOM updates per rAF, and keep one SSE write per event so Stream stays live during child work instead of freezing or dumping bursts. Co-authored-by: Cursor <cursoragent@cursor.com>
7.9 KiB
7.9 KiB
智能体流式输出(未来规划)
| 状态 | S0–S3 已落地(view SSE) |
| 日期 | 2026-08-10 |
| 相关 | ext-llm.md · ext-agent.md · ext-agent-plan.md · ext-agent-parent.md(父 Plan-and-Move / CALL·READ) · stdlib-subtask.md · view.md |
| 痛点 | complete / step / plan 均为整段返回;用户看不到思考与中间输出 |
1. 问题
当前体验:
| 路径 | 行为 | 体验问题 |
|---|---|---|
`model`.complete |
等 HTTP 整包结束再返回字符串 | 长推理「卡住」无反馈 |
`助手`.step |
拼提示 → complete → 解析 CALL/答案 | 工具轮次与模型吐字均不可见 |
`助手`.plan |
多轮 spawn + 父 LLM;子任务默认 quiet |
父侧只有最终 result map;过程静默 |
这与「文档驱动、过程可审计」并不矛盾——落盘真相仍可以是工作簿与写回;缺的是运行时的渐进呈现(TTY / view / 调用方回调)。
约束回顾(不得破坏):
- 文件子任务默认静默:答案走
# main返回值(stdlib-subtask.md)。 ext/**不直调host_*;流式原语进ext/ai/llm+ 必要时薄 host/net。- 多轮哲学仍是模式 C(子文件接力 + OKF),不是把 transcript 堆进单文件。
2. 目标
- 可选流式看到:模型增量文本、(可选)工具调用开始/结束、plan 轮次边界。
- 默认保持今日语义:未开流式 = 整段
complete/ 整包result。 - 流式是呈现与旁路,不替代
**返回**/plan.result/ 写回。 - CLI、
marqdo view、嵌入调用方可共用同一事件模型。
非目标(本规划):
- 把 Marqdo 做成聊天产品 UI 框架。
- 强制所有
print改流式 API。 - 在 quiet 子进程里把子
print默认真传父 TTY(与返回优先冲突)。
3. 分层设计
LLM 供应商 SSE / chunked
↓
ext/ai/llm stream=True → 事件迭代 / 回调 / 写 channel
↓
ext/ai/agent step/plan 订阅事件 → 可选透传或写回「过程槽」
↓
呈现面:TTY | view EventSource | 调用方 foreach 事件表
3.1 事件模型(锁定方向)
统一为可 JSON 化的小 map(便于写回与 view):
type |
含义 | 主要字段 |
|---|---|---|
reasoning |
模型思考增量(如 DeepSeek reasoning_content) |
text |
delta |
模型答案增量文本 | text |
tool_start / tool_end |
工具轮(父 plan CALL/READ 已发;view Tool 卡) | name, kind?, result? |
round |
plan 轮次边界(子工作簿跑完) | round, workbook, exit_code?, result?(子返回值摘要) |
decision |
DONE / CONTINUE / RUN | decision, summary? |
done |
本调用结束 | result(答案正文;不含 thinking) |
error |
失败 | message |
中英键名可在 L1 包装层镜像;插件/wire 先用英文 type。
3.2 llm:流式完成
*`model` = > llm *
*`stream` = > `model`.complete prompt=… stream=True *
- [`ev`](`stream`)
*`t` = > json.get value=`ev` key=type *
1. `t` == delta
*`chunk` = > json.get value=`ev` key=text *
> print text=`chunk`
2. `t` == done
*`answer` = > json.get value=`ev` key=result *
或回调形(若日后支持函数值作实参):on_delta= —— v1 优先 事件列表 / 可迭代句柄,少发明回调语法。
实现要点:
lib/net或 llm 插件支持 读 SSE / chunked body(今日http_post偏整包)。stream=False(默认)路径零行为变化。- 金样:mock SSE fixture,不强制打真网。
3.3 agent.step / plan:过程透传
| 开关(草案) | 默认 | 行为 |
|---|---|---|
stream=False |
✓ | 与今日相同 |
stream=True |
向当前进程呈现面推送事件;返回值仍是最终 map | |
trace=True |
可选 | 把事件追加写入调用行写回槽 trace(审计);与 TTY 流式可分立 |
plan 特有:
await_workbook前发await(view Child running 占位);结束后发round。- 父 pre-run 分解发
decompose。 - 父 LLM 的
complete若stream=True,delta冒泡到 plan 的 stream。 - 子文件 quiet 不变(TTY);默认骨架
step stream=True,子 EventBus 经MARQDO_EVENT_FORWARD实时转发到父 SSE(source=child)。答案仍以# main返回为准。
3.4 呈现面
| 面 | 做法 |
|---|---|
| CLI | delta 直接写 stdout(无额外 JSON 包装);结构化事件可 --trace-events 走 stderr / 旁路文件 |
marqdo view |
Execution 区 Stream 面板订阅 SSE(见 view.md §5.1):Thinking / Answer / Child 分栏,非混色日志 |
| 库调用方 | foreach 事件集合,自行决定 UI |
view Stream 锁定(S3 UI):
reasoning→ 可折叠 Thinking;delta→ 主文 Answer(连续拼接)。round→ 独立 Child/Workbook 卡(路径链 + 可选result);不与父 Answer 混排。decision→ 时间线条目标记。- 视觉跟 view HIG 浅色壳,不用深色终端底。
- 传输:
POST /api/run直接 SSE;前端fetch+ReadableStream(非页载 EventSource);rAF 合批;stick-to-bottom。
4. 与「返回优先」的关系
| 通道 | 职责 |
|---|---|
| stream / trace | 过程(体验、调试、审计) |
# main **…** / plan.result |
结果(编排、OKF、调用方消费) |
writeback ok/error |
落盘摘要(默认可关) |
禁止:仅靠 stream 文本当作子任务成功条件;DONE / 固化仍看退出码、返回值与源码形态。
5. 推荐落地顺序
S0 net/llm:SSE 读 + complete stream=True + 事件 foreach ✅
S1 step stream=True(echo 增量;返回 map 不变) ✅
S2 plan stream=True:round + 父 delta;trace 写回可选 ✅
S3 view 订阅(EventBus + GET /api/events + POST /api/run) ✅
开放点决议(S0)
- Eager 事件列表(非惰性句柄):
complete stream=True返回Listof maps,可用今日 foreach。 - 默认不自动 print:
echo=False;需要边读边打时传echo=True/打印增量=真。 - 中文:
## 运行用流式=/打印增量=。
开放点决议(S2)
plan/多步增加stream/echo/trace(中文流式/打印增量/轨迹)。- 事件挂在返回 map 的
events;父complete只冒泡delta/error(嵌套done不进列表)。 trace=True→ 写回槽trace(与 TTYecho可分立)。- 体验(父先子后):非命中路径先
decompose(SSE + 可选 TTYplan:decompose),再await(SSE 占位 + 可选 TTYplan:await),子 quiet。修订轮仍是观察后父决策。SSE 本身用tests/ext/llm-stream-live.mq.md。
验收:
- 未传
stream的金样零 diff。 stream=True时用户在首包 token 到达前不应长时间无输出(允许短连接建立延迟)。- 最终
result与非流式路径一致(同 prompt fixture)。 - quiet 子任务仍不污染父 TTY。
6. 开放点
Eager vs 惰性→ S0 选 eager;惰性句柄可后补。delta 默认 print→ 默认关;echo=True可选。中文面→流式=/打印增量=。S2→plan stream=True:round/ 父 delta /decision/done;可选trace。S3→marqdo view:进程内 EventBus;GET /api/events(SSE);POST /api/run后台执行;Execution 区 EventSource 面板。CLI 默认不订阅。
S0 可与 okf-near-match.md 并行,互不阻塞。