Files
marqdo/doc/roadmap/agent-streaming.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

7.9 KiB
Executable File
Raw Blame History

智能体流式输出(未来规划)

状态 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 / 调用方回调)。

约束回顾(不得破坏):

  1. 文件子任务默认静默:答案走 # main 返回值(stdlib-subtask.md)。
  2. ext/** 不直调 host_*;流式原语进 ext/ai/llm + 必要时薄 host/net。
  3. 多轮哲学仍是模式 C(子文件接力 + OKF),不是把 transcript 堆进单文件。

2. 目标

  1. 可选流式看到:模型增量文本、(可选)工具调用开始/结束、plan 轮次边界。
  2. 默认保持今日语义:未开流式 = 整段 complete / 整包 result。
  3. 流式是呈现与旁路,不替代 **返回** / plan.result / 写回。
  4. 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):

  1. reasoning → 可折叠 Thinking;delta → 主文 Answer(连续拼接)。
  2. round → 独立 Child/Workbook 卡(路径链 + 可选 result);不与父 Answer 混排。
  3. decision → 时间线条目标记。
  4. 视觉跟 view HIG 浅色壳,不用深色终端底。
  5. 传输: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)

  1. Eager 事件列表(非惰性句柄):complete stream=True 返回 List of maps,可用今日 foreach。
  2. 默认不自动 print:echo=False;需要边读边打时传 echo=True / 打印增量=真。
  3. 中文:## 运行 用 流式= / 打印增量=。

开放点决议(S2)

  1. plan / 多步 增加 stream / echo / trace(中文 流式 / 打印增量 / 轨迹)。
  2. 事件挂在返回 map 的 events;父 complete 只冒泡 delta/error(嵌套 done 不进列表)。
  3. trace=True → 写回槽 trace(与 TTY echo 可分立)。
  4. 体验(父先子后):非命中路径先 decompose(SSE + 可选 TTY plan:decompose),再 await(SSE 占位 + 可选 TTY plan:await),子 quiet。修订轮仍是观察后父决策。SSE 本身用 tests/ext/llm-stream-live.mq.md。

验收:

  1. 未传 stream 的金样零 diff。
  2. stream=True 时用户在首包 token 到达前不应长时间无输出(允许短连接建立延迟)。
  3. 最终 result 与非流式路径一致(同 prompt fixture)。
  4. quiet 子任务仍不污染父 TTY。

6. 开放点

  1. Eager vs 惰性 → S0 选 eager;惰性句柄可后补。
  2. delta 默认 print → 默认关;echo=True 可选。
  3. 中文面 → 流式= / 打印增量=。
  4. S2 → plan stream=True:round / 父 delta / decision / done;可选 trace。
  5. S3 → marqdo view:进程内 EventBus;GET /api/events(SSE);POST /api/run 后台执行;Execution 区 EventSource 面板。CLI 默认不订阅。

S0 可与 okf-near-match.md 并行,互不阻塞。