- 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。
8.9 KiB
Executable File
调研:宿主集成缺口(浏览器中继 · 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) |
✅ 已关闭 |
旁路脚本名来自下游集成仓库;本仓库 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.沉淀 等,需要同进程执行用户函数。今天只有:
- 页面装配期
call_lib_path(compose,非每请求); /_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 可发现性
问题
- 类型分发: 插件对象依赖
_type/ 方法表;跨模块传回的 store 若丢类型或未注册方法,报unknown object type db。同文件db/index.mq.md内## recent再导出 JSON 是现行绕过。 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 内 |