Files
marqdo/doc/design/web-invoke-serialization.md
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.3 KiB
Executable File
Raw Permalink Blame History

Web 热路径:单解释器串行化(设计缺陷说明)

状态 Accepted(缺陷记录 + 缓解已落地)
日期 2026-10-26
规范决策 ADR 0008
相关 ext-web-go-rewrite.md · ext-abi.md · ADR 0004 · ADR 0007

本文把「页面卡死 / 像单线程」拆成可验证的架构事实、错误语义与演进边界。
结论先行:HTTP 是多线程的;卡住是因为所有 Endpoint 共享一把解释器锁。

增量实施提案见 隔离执行与响应式 Web 运行时(2026-10-26):独立进程池、控制/读取容量、请求级事件与取消、缓存和恢复。提案通过验收前,本文件及 ADR 0008 的现行单飞约束不变。


1. 问题陈述

1.1 用户可见症状

  1. 发起一次长对话(OpenAI 兼容 POST …/v1/chat/completions + stream:true / sse-live)。
  2. 对话尚未结束时,打开设置、拉 /v1/models、或其它短 JSON API。
  3. 旧行为:浏览器请求一直 pending,整页像死机;只能杀 marqdo run serve… 恢复。
  4. 目标行为:短请求在约 1.5s 内得到 HTTP 503,错误体标明 interpreter busy;对话 SSE 继续;结束后短请求立刻恢复 200。

1.2 错误归因(不要再说错)

错误说法 正确说法
「web 插件是单线程的」 Go net/http 与 SSE 刷写是多 goroutine
「忘记启动进程所以卡死」 进程在跑;是 锁争用 导致短请求永不返回
「把 SSE 的等待时间调大就能修好」 进程级拉长 MARQDO_INVOKE_WAIT_MS 会让短请求一起卡死
「去掉 INVOKE_LOCK 即可并行」 HostContext 非 Sync,无锁并行会数据竞争 / 未定义行为

2. 调用栈与锁边界

Browser
  │  GET /v1/models          POST /v1/chat/completions (SSE)
  ▼
Go plugins/web  (多 goroutine)
  handleInvoke / handleInvokeLiveSSE
  │
  ▼  C ABI host_query("call_lib_path", {path, args})
Rust src/host/plugin.rs
  ┌─────────────────────────────┐
  │  INVOKE_LOCK  (进程级 Mutex) │  ← 同一时刻只允许一个 worker 进入
  └─────────────────────────────┘
  │
  ▼
HostContext:装载/求值作者 .mq.md、写回、事件总线、LLM 插件回调…

要点:

  1. 锁在宿主,不在 Go 业务路由表。 增加更多 Go handler 不会自动并行执行 Marqdo。
  2. SSE 持锁时间 ≈ 整次 Endpoint 求值时间(含多次 LLM 往返),可达数十秒到数分钟。
  3. 事件转发(MARQDO_EVENT_FORWARD NDJSON)与 取消(MARQDO_CANCEL_TOKEN)在持锁期间仍可由其它 goroutine 写文件/读桥;它们不进入解释器,故不受 INVOKE_LOCK 保护,也不应误设长等待。

3. 为何不能简单「多线程跑 Marqdo」

HostContext 持有(非穷尽):

  • 当前模块图、函数表、写回缓冲与 FS 根;
  • 插件注册与 CURRENT_HOST / 全局 host 指针;
  • Agent / LLM 运行时与 stream 发布钩子;
  • 与文档写回、会话态相关的可变结构。

这些状态在实现上按单线程求值建模。把它标成 Sync 或去掉 INVOKE_LOCK 而没有隔离运行时,属于未定义行为,不是性能优化。

真并行的合法方向(未实现):

  1. 解释器池:每请求或每会话一个 HostContext(或可重置的 isolate),路由层选闲置实例;
  2. 只读快照 + 写队列:热路径只读克隆,写回串行合并(适合纯查询 Endpoint,不适合带写回的 agent);
  3. 把长任务移出解释器:Marqdo 只做编排,重活在独立进程/队列(与「代码即文档」主路径权衡后再定)。

在上述任一方案落地并经金样例验收前,产品必须以「单飞解释器」为约束设计 UX。


4. 缓解契约(已实现)

4.1 宿主:限时争锁

文件:src/host/plugin.rs

  • 仅当从 worker 线程进入(CURRENT_HOST 为空、走全局 host)时争 INVOKE_LOCK。
  • acquire_invoke_lock:try_lock 循环,预算默认 1500ms(MARQDO_INVOKE_WAIT_MS,最小 1)。
  • 超时:set_err("interpreter busy: another request holds the Marqdo invoke lock (waited …ms)"),返回非 0。
  • 不要在 SSE 入口把该环境变量设成数分钟:它是进程级的,会污染并发短请求。

4.2 Web 插件:503

文件:plugins/web/internal/httpx/routes_invoke.go

  • 普通 JSON invoke:错误信息含 interpreter busy → 503 + Retry-After: 2 + {ok:false, error:…}。
  • Live SSE:若启动时即 busy,以失败事件/错误结束该流,不得无限挂起握手。

4.3 客户端:超时与文案

短 API(模型列表、设置、registry 探测等)必须:

  • 设置合理 fetch 超时(秒级,例如 8s);
  • 将 503 / interpreter busy 展示为「服务正忙(对话进行中)」类可读提示,而不是空白转圈。

(qdagent 前端 frontend/src/lib/api.ts 已按此契约处理。)

4.4 验收探针

在本地 serve 上:

# 终端 A:启动长 SSE 对话(持锁)
curl -N -m 120 -H 'Authorization: Bearer …' -H 'Content-Type: application/json' \
  -d '{"stream":true,…}' http://127.0.0.1:PORT/v1/chat/completions

# 终端 B:对话进行中
curl -sS -w 'http=%{http_code} time=%{time_total}\n' --max-time 5 \
  -H 'Authorization: Bearer …' http://127.0.0.1:PORT/v1/models
# 期望:http=503,time≈1.5,body 含 interpreter busy

# 对话结束后再打同一 URL → http=200,time≪1s

5. 运维与调参

变量 默认 含义
MARQDO_INVOKE_WAIT_MS 1500 worker 进入解释器前最长等待;超时 → busy

建议:

  • 开发机 / 产品默认保持 1–3s。
  • 禁止为「让第二个聊天排队」而把默认调到分钟级——那等于恢复卡死。
  • 需要排队时,应在 应用层(会话队列、UI 禁用「再发一条」),而不是拉长宿主锁等待。

6. 与其它机制的边界

机制 与 INVOKE_LOCK 的关系
MARQDO_EVENT_FORWARD SSE 期间写 NDJSON;不替代争锁;不延长等待
MARQDO_CANCEL_TOKEN 断开连接时可取消 LLM;释放锁仍取决于解释器何时回到 FFI
web.serve / 静态资源 通常不经 call_lib_path,不受本锁影响
插件内部 Tokio/Go 并发 可以;只要不再次 call_lib_path 进同一 HostContext

7. 演进检查清单(根治前勿宣称「已支持并行 Endpoint」)

  • 多 HostContext 或 isolate 的生命周期与 ABI(装载、shutdown、写回冲突)有设计稿与金样例。
  • 池化后 call_lib_path 不再依赖进程级单锁,或锁粒度降到实例级。
  • 两个并发长 SSE + 一个短 /v1/models 的压力测试:短请求稳定 200,长请求互不污染会话写回。
  • 更新本文件与 ADR 0008 Status(例如改为 Superseded by ADR NNNN)。

在清单完成前,对外与文档中应明确:Marqdo Web Endpoint 求值在单进程内串行;HTTP 层并发,解释器层单飞。