Files
marqdo/doc/research/ext-hosting-gaps.md
cflmyandCursor fc543f1ca5 feat(web,agent): hosting H1–H4 — proxy, invoke, MCP stdio, cross-module db
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>
2026-09-07 22:14:51 +08:00

8.9 KiB
Raw Permalink Blame History

调研:宿主集成缺口(浏览器中继 · HTTP→## · MCP Server · 同寿副端口 · 跨模块 DB/检索)

状态 调研笔记 · 缺口盘点(H1–H4 stdio 已落地;H4b HTTP 可选)
日期 2026-09-07
触发 下游应用(对话站 / 求道类 Agent)在真实集成中被迫旁路 Python 脚本
基线版本 v0.3.6+(宿主波次 H1–H4 见 ext-hosting.md)
相关设计 ext-web.md · ext-web-net.md · web-net-capabilities.md · ext-agent.md · ext-abi.md
邻近缺口 agent-framework-gaps-after-a4.md(真 MCP 客户端)
补齐设计 ext-hosting-fill.md
实现路线 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 §5
Agent 证据工具(fixture MCP) corpus_search / mcp_list_tools / mcp_call A4;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「真 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 / 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
浏览器手写业务 JS 代理 与 WASM 路线「作者零 JS」冲突;中继应在服务端 ext/web

7. 与其它文档

文档 关系
ext-hosting-fill.md 补齐设计(作者 API + ABI)
ext-hosting.md 实现波次 H0–H4
ext-web.md 站点主线完结;本缺口为后续宿主波次
agent-framework-gaps-after-a4.md 客户端真 MCP;与 GAP-03 Server 互补
web-asgi-servers-and-marqdo.md 反代模型;中继仍在 Marqdo listen 内