Add net/llm SSE primitives and optional stream/echo/trace on step and plan so callers can watch deltas and rounds without changing final return values. Co-authored-by: Cursor <cursoragent@cursor.com>
6.6 KiB
6.6 KiB
智能体流式输出(未来规划)
| 状态 | S0–S2 已落地(S3 view 仍待做) |
| 日期 | 2026-08-10 |
| 相关 | ext-llm.md · ext-agent.md · ext-agent-plan.md · 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 |
含义 | 主要字段 |
|---|---|---|
delta |
模型增量文本 | text |
tool_start / tool_end |
工具轮 | name, result? |
round |
plan 轮次边界 | round, workbook, exit_code? |
decision |
DONE / CONTINUE | decision, summary? |
done |
本调用结束 | result(与今日返回值对齐) |
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前后发round。 - 父 LLM 的
complete若stream=True,delta冒泡到 plan 的 stream。 - 子文件 quiet 不变;若需看子内部模型吐字,由子工作簿自己
stream=True并把摘要 返回 或写回,而不是继承子 stdout。
3.4 呈现面
| 面 | 做法 |
|---|---|
| CLI | delta 直接写 stdout(无额外 JSON 包装);结构化事件可 --trace-events 走 stderr / 旁路文件 |
marqdo view |
调试/运行面板订阅同一事件(WebSocket 或 SSE) |
| 库调用方 | foreach 事件集合,自行决定 UI |
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 订阅 (待做)
开放点决议(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可分立)。
验收:
- 未传
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订阅同一事件模型。
S0 可与 okf-near-match.md 并行,互不阻塞。