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

164 lines
7.3 KiB
Markdown
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Web 热路径:单解释器串行化(设计缺陷说明)
| | |
|---|---|
| 状态 | **Accepted**(缺陷记录 + 缓解已落地) |
| 日期 | 2026-10-26 |
| 规范决策 | [ADR 0008](../adr/0008-web-invoke-serialization.md) |
| 相关 | [ext-web-go-rewrite.md](ext-web-go-rewrite.md) · [ext-abi.md](ext-abi.md) · [ADR 0004](../adr/0004-web-plugin-go.md) · [ADR 0007](../adr/0007-web-document-endpoint.md) |
本文把「页面卡死 / 像单线程」拆成可验证的架构事实、错误语义与演进边界。
**结论先行:HTTP 是多线程的;卡住是因为所有 Endpoint 共享一把解释器锁。**
增量实施提案见 [隔离执行与响应式 Web 运行时(2026-10-26)](isolated-web-runtime-development-2026-10-26.md):独立进程池、控制/读取容量、请求级事件与取消、缓存和恢复。提案通过验收前,本文件及 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 上:
```bash
# 终端 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 层并发,解释器层单飞。**