Close GAP-01–05 with ext/web streaming reverse proxy and HTTP→## invoke, transitive object method lookup, corpus_search plugin ensure, and agent MCP server stdio so downstream apps can drop Python side relays. Co-authored-by: Cursor <cursoragent@cursor.com>
157 lines
8.9 KiB
Markdown
157 lines
8.9 KiB
Markdown
# 调研:宿主集成缺口(浏览器中继 · HTTP→`##` · MCP Server · 同寿副端口 · 跨模块 DB/检索)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **调研笔记 · 缺口盘点(H1–H4 stdio 已落地;H4b HTTP 可选)** |
|
||
| 日期 | 2026-09-07 |
|
||
| 触发 | 下游应用(对话站 / 求道类 Agent)在真实集成中被迫旁路 Python 脚本 |
|
||
| 基线版本 | **v0.3.6+**(宿主波次 H1–H4 见 [ext-hosting.md](../roadmap/ext-hosting.md)) |
|
||
| 相关设计 | [ext-web.md](../design/ext-web.md) · [ext-web-net.md](../design/ext-web-net.md) · [web-net-capabilities.md](../design/web-net-capabilities.md) · [ext-agent.md](../design/ext-agent.md) · [ext-abi.md](../design/ext-abi.md) |
|
||
| 邻近缺口 | [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md)(真 MCP **客户端**) |
|
||
| 补齐设计 | [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
|
||
| 实现路线 | [ext-hosting.md](../roadmap/ext-hosting.md) |
|
||
|
||
---
|
||
|
||
## 0. 一句话结论
|
||
|
||
`ext/web` 已能做**内容站 / CRUD / JSON-DB API / WS**;`ext/ai` 已能做**工作簿 Agent + 客户端 SSE 消费**。下游要把「浏览器同域流式 LLM」「请求触发任意 `##`」「MCP Server 被 IDE 拉起」合进**单一 Marqdo 进程**时,现有扩展**没有一等装配**——只能外挂缓冲代理 / CLI 子进程。缺口集中在 **扩展库作者面 + `plugins/web|agent` ABI**,不是语法层,也不是再开一套标准库。
|
||
|
||
**原则:** 旁路脚本只证明需求;关闭缺口必须把能力沉进 `ext/*` + `plugins/*`(可选极薄 `lib/` 编排),禁止把领域逻辑塞进 `src/host/`。
|
||
|
||
---
|
||
|
||
## 1. 已有基线(不是缺口)
|
||
|
||
| 能力 | 现状 | 文档 / 金样 |
|
||
|------|------|-------------|
|
||
| CORS / 安全头 / gzip / body limit | `app.configure` | `tests/ext/web-middleware-smoke.mq.md` |
|
||
| JSON **DB select** 路由 | `configure json=` | `plugins/web/src/middleware.rs` |
|
||
| `/_form/*` SQL CRUD | `mount_form` | `plugins/web/src/form.rs` |
|
||
| 客户端缓冲 SSE | `lib/net.http_post_sse` → `ext/llm.complete stream=` | `tests/lib/net-openai-sse.mq.md` |
|
||
| 执行过程 SSE(非 LLM 中继) | `marqdo view` `/api/run` | [view.md](../design/view.md) §5 |
|
||
| Agent 证据工具(fixture MCP) | `corpus_search` / `mcp_list_tools` / `mcp_call` | A4;[agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
|
||
| 同模块 `# db` CRUD | `ext/web` `# db` | `examples/web-site/db/` |
|
||
|
||
---
|
||
|
||
## 2. 缺口总表
|
||
|
||
| ID | 缺口 | 需要 | Marqdo 现状 | 典型旁路 | 解除条件 |
|
||
|----|------|------|-------------|----------|----------|
|
||
| **GAP-01** | 浏览器 → 上游 LLM **同域流式中继** | 绕过对方 CORS;**SSE 原样转发** | **`app.proxy` / `configure proxy=`**(H1) | ~~`llm_proxy.py`~~ | ✅ 已关闭 |
|
||
| **GAP-02** | HTTP 处理函数可调用用户 `##` | 请求内执行用户 `##`,返回 JSON | **`app.invoke` / `configure invoke=`**(H2) | ~~外挂 `marqdo run`~~ | ✅ 已关闭 |
|
||
| **GAP-03** | **MCP Server** 宿主 | IDE 拉起暴露工具 | **`agent.mcp_server` + `serve` stdio**(H4);HTTP=H4b | ~~`qdagent_mcp.py`~~ | ✅ stdio;HTTP 可选 |
|
||
| **GAP-04** | 同寿「第二监听端口」 | 与 `listen` 同寿中继 | 并入主端口(H1+H2) | ~~`mq.sh` 双进程~~ | ✅ won't |
|
||
| **GAP-05** | 跨模块 `db`;纯 run 用 corpus | 跨文件 `select`;CLI 检索 | 传递归查找 + `corpus_search` ensure_plugin(H3) | ~~db/index 导出~~ | ✅ 已关闭 |
|
||
|
||
旁路脚本名来自下游集成仓库;**本仓库 `scripts/` 不含这些文件**——它们是需求证据,不是上游实现。
|
||
|
||
---
|
||
|
||
## 3. 分项说明
|
||
|
||
### 3.1 GAP-01 · 同域 SSE 中继
|
||
|
||
**问题**
|
||
浏览器页面跑在 `ext/web` 源上时,直连 OpenAI 兼容上游会撞 CORS;`lib/net.http_post_sse` 只在 **CLI/宿主侧缓冲整段流**,不能把字节边收边推回浏览器。
|
||
|
||
**现状边界**
|
||
|
||
| 已有 | 缺什么 |
|
||
|------|--------|
|
||
| `app.configure cors=` | 解决的是**本站对外** CORS,不是替上游开 CORS |
|
||
| `http_post_sse` → `{status, events}` | **客户端消费**,非服务器中继 |
|
||
| `app.download` 对象流 | 存储下载,非上游 SSE |
|
||
| view `/api/run` SSE | Marqdo **执行事件**,非 LLM token 流 |
|
||
|
||
**解除形态(产品)**
|
||
作者声明:`path` + `upstream`(或 env)+ 可选 header 白名单;监听端对浏览器返回 `Content-Type: text/event-stream`,chunk 原样或按 OpenAI SSE 帧转发。
|
||
|
||
### 3.2 GAP-02 · 路由 → `##`
|
||
|
||
**问题**
|
||
对话沉淀、表单后写 `data/runs/*.mq.md`、触发 `lib/run.沉淀` 等,需要**同进程**执行用户函数。今天只有:
|
||
|
||
1. 页面装配期 `call_lib_path`(compose,非每请求);
|
||
2. `/_form` / `json=` 的 **DB 专用** handler。
|
||
|
||
**解除形态(产品)**
|
||
声明式:`path` · `method` · `fn=lib.member` 或 `file=… ## name` · body→形参映射 · 返回值序列化为 JSON(错误码约定)。安全默认:仅允许入口模块已导入路径;禁止任意路径注入。
|
||
|
||
### 3.3 GAP-03 · MCP Server
|
||
|
||
**问题**
|
||
A4 解决的是 Agent **调用** MCP 工具(且仍是 fixture)。下游要把 Marqdo 工作簿 **暴露为** MCP Server(stdio / Streamable HTTP),IDE 拉起后调 `qd_*`。
|
||
|
||
与 [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md)「真 MCP 客户端」正交:本缺口是 **Server 宿主**。
|
||
|
||
**解除形态(产品)**
|
||
`ext/ai`(或 `ext/mcp`)提供:`server tools=` 表(name → `.mq.md`/`##`);`serve stdio=` / `serve http port=`;工具结果仍可带 `authority=workbook`。
|
||
|
||
### 3.4 GAP-04 · 同寿副端口
|
||
|
||
**问题**
|
||
在 GAP-01/02 未并入主端口前,下游用第二端口跑代理。`app.listen` 同步阻塞,无「同进程再绑一个 TcpListener」的作者 API;只能 shell 并起另一运行时。
|
||
|
||
**解除形态(产品)**
|
||
优先:GAP-01/02 挂在同一 `listen` → **本缺口关闭**。备选:`app.attach` / `listen also=` 同 tokio 运行时附加服务(仅当必须隔离路径树)。
|
||
|
||
### 3.5 GAP-05 · 跨模块 DB 句柄与 corpus 可发现性
|
||
|
||
**问题**
|
||
|
||
1. **类型分发:** 插件对象依赖 `_type` / 方法表;跨模块传回的 store 若丢类型或未注册方法,报 `unknown object type db`。同文件 `db/index.mq.md` 内 `## recent` 再导出 JSON 是现行绕过。
|
||
2. **`agent_corpus_search`:** 注册在 `plugins/agent`;普通 `marqdo run` 未 `plugin.load` / 未构造 `# agent` 时不可用。导入 `ext/ai/agent.mq.md` 文本本身不保证原生插件已加载。
|
||
|
||
**解除形态(产品)**
|
||
句柄:跨模块返回值保留 `_type=db` 且方法分发查全局/插件表(修运行时或约定「只返回 url,调用方再 `web.db`」二选一,见补齐设计)。corpus:`plugin.load` 自动路径,或 `ext/ai` 导出独立 `## corpus_search` 并在调用前 `ensure_plugin`。
|
||
|
||
---
|
||
|
||
## 4. 归属判定(标准库 vs 扩展)
|
||
|
||
沿用 [ext-web-net.md](../design/ext-web-net.md) / [web-net-capabilities.md](../design/web-net-capabilities.md) 边界:
|
||
|
||
| 能力 | 归属 | 理由 |
|
||
|------|------|------|
|
||
| SSE **中继**路由、HTTP→`##`、副端口 | **`plugins/web` + `ext/web`** | 服务器结构 / 网站领域;axum 已在依赖链 |
|
||
| MCP **Server**、corpus 可发现 | **`plugins/agent` + `ext/ai`** | Agent/工具宿主;禁止塞 `src/host/` |
|
||
| 缓冲 SSE 客户端、解析 | 已有 **`lib/net`** | 不新增中继到 stdlib |
|
||
| 任意路径 shell 出去跑 `marqdo` | **刻意不做进核心** | 旁路脚本可留在下游;上游给一等 API 后废弃 |
|
||
|
||
---
|
||
|
||
## 5. 优先级建议
|
||
|
||
| 优先级 | ID | 理由 |
|
||
|--------|-----|------|
|
||
| **高** | GAP-01 + GAP-02 | 去掉 Python 中继的主路径;浏览器站 + 沉淀闭环 |
|
||
| **高** | GAP-03 | IDE 生态入口;与「真 MCP 客户端」可并行设计、分波交付 |
|
||
| **中** | GAP-05 | 减少 `db/index` 与 bridge 胶水;影响面偏语言/插件加载 |
|
||
| **低(可随 01/02 关闭)** | GAP-04 | 并入主端口后自然消失 |
|
||
|
||
---
|
||
|
||
## 6. 明确「不是缺口」
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| 内容站 W0–W7+P3 | 已完结;本清单不重开上传/RSS/RBAC |
|
||
| Mid M1–M6 | 通用原语已够;本清单不是再开 `lib/re` 一类 |
|
||
| 隐藏 JSON TOOL 主循环 | 与 Agent 宪法冲突 |
|
||
| Dense embedding 默认化 | 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) |
|
||
| 浏览器手写业务 JS 代理 | 与 WASM 路线「作者零 JS」冲突;中继应在服务端 `ext/web` |
|
||
|
||
---
|
||
|
||
## 7. 与其它文档
|
||
|
||
| 文档 | 关系 |
|
||
|------|------|
|
||
| [ext-hosting-fill.md](../design/ext-hosting-fill.md) | **补齐设计(作者 API + ABI)** |
|
||
| [ext-hosting.md](../roadmap/ext-hosting.md) | 实现波次 H0–H4 |
|
||
| [ext-web.md](../roadmap/ext-web.md) | 站点主线完结;本缺口为后续宿主波次 |
|
||
| [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) | 客户端真 MCP;与 GAP-03 Server 互补 |
|
||
| [web-asgi-servers-and-marqdo.md](../design/web-asgi-servers-and-marqdo.md) | 反代模型;中继仍在 Marqdo `listen` 内 |
|