Files
marqdo/doc/design/ext-hosting-fill.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

11 KiB
Executable File
Raw Permalink Blame History

设计:宿主集成缺口补齐(ext/web · ext/ai)

状态 Accepted · H1–H4 stdio 已落地(H4b HTTP 可选)
日期 2026-09-07
缺口盘点 ext-hosting-gaps.md
路线图 ext-hosting.md
边界 ext-web-net.md · ext-abi.md · ext-agent.md
目标 用扩展库一等 API关闭 GAP-01–05,取代下游 Python 旁路

0. 一句话

服务器中继与「请求→##」进 ext/web;MCP Server 与 corpus 可发现进 ext/ai;标准库只保留已有客户端 SSE。 作者用 GFM 表声明路由/工具,不写 JS、不启第二语言运行时。


1. 分层与禁止项

层 职责 落点
作者面 声明路径、上游、函数名、工具表 ext/web/web.mq.md · ext/ai/agent.mq.md(+ 中文对偶)
ABI axum 流式代理、每请求 interp 调用、MCP 传输 plugins/web · plugins/agent
标准库 不变:缓冲客户端 SSE / 解析 lib/net(不加中继)
核心 host 禁止新增 agent/web 领域 host_* 见 Skill 硬规则 9

禁止:

  1. 为中继在浏览器手写业务 JS。
  2. json= 继续塞「任意 ##」语义(保持 DB-only;新能力用独立装配名)。
  3. MCP Server 把向量库升为权威真相(工具结果可带 authority=workbook)。
  4. 无白名单的「任意文件系统路径 + 任意 ##」远程触发。

2. GAP-01 · app.proxy 流式反向代理

2.1 作者 API

*应用 = > `应用`.proxy path="/v1/chat/completions" upstream=$OPENAI_BASE_URL*
*应用 = > `应用`.proxy path="/llm/stream" upstream="https://api.example.com" strip_prefix="/llm" stream=True*

或装配表(一次挂多条):

*应用 = > `应用`.configure proxy=`代理表`*

| path | upstream | stream | strip_prefix | headers_from_env |
|------|----------|--------|--------------|------------------|
| /proxy/chat | $OPENAI_BASE_URL | True | | OPENAI_API_KEY=Authorization |
参数 默认 含义
path 必填 浏览器同域路径
upstream 必填 上游根或完整 URL;支持 $ENV
stream True True:响应按上游 Content-Type 管道转发(含 text/event-stream)
strip_prefix 空 转发前去掉本站前缀
methods POST 允许方法
headers_from_env 空 ENV=Header-Name 注入(密钥不进前端)
timeout_ms 插件默认 上游超时

中文:## 代理 / 流式= / 上游= / 去前缀=。

2.2 ABI / 插件行为

步骤 行为
注册 web_app_proxy 写入 AppState 路由表
请求 读 body + 过滤危险 hop-by-hop 头;合并 env 注入头
上游 reqwest/hyper 流式客户端(插件内,不进核心)
响应 复制状态码与 content-type;body 为 stream;SSE 不整段缓冲
CORS 仍走既有 configure cors=(同域调用时浏览器不依赖上游 CORS)

2.3 与 lib/net.http_post_sse 关系

API 角色
http_post_sse 出站消费者(CLI/agent 侧收齐 events)
app.proxy 入站中继(浏览器 ← Marqdo ← 上游)

二者互补,不互相替代。

2.4 验收

  • 金样:mock 上游发两帧 SSE,浏览器侧(或 curl -N)收到两帧且中间无全缓冲延迟门槛。
  • 密钥仅出现在服务端 env 注入头。
  • 金样名建议:tests/ext/web-proxy-sse-smoke.mq.md。

3. GAP-02 · app.invoke / configure invoke=(HTTP → ##)

3.1 作者 API

*应用 = > `应用`.invoke path="/api/沉淀" method=POST fn="run.沉淀"*

表形式:

*应用 = > `应用`.configure invoke=`调用表`*

| path | method | fn | body | return |
|------|--------|-----|------|--------|
| /api/note | POST | run.写出 | json | json |
| /api/search | GET | db.recent | query | json |
列 / 参数 含义
path / method HTTP 路由
fn 库.成员(入口模块已 import)或 模块路径##标题(白名单前缀内)
body json | form | query | raw → 映射到 ## 形参(同名优先;其余进 payload 袋)
return json(默认)| text | status

中文:## 调用 / 函数= / 正文= / 返回=。

3.2 安全默认(锁定)

  1. 仅解析入口 workbook 已导入的 bind 路径,或 invoke_allow= 显式前缀列表。
  2. 单请求超时 + 可选并发上限(防 listen 线程饿死)。
  3. 默认不启;作者显式 invoke / configure invoke=。
  4. 错误:{ok:false, error} + HTTP 4xx/5xx;不把内部路径栈默认回传生产模式。

3.3 ABI / 插件行为

步骤 行为
注册 web_app_invoke 存 (path, method, FnRef)
命中 解析 body → Value 袋;call_lib_path / 等价「同步调用已加载模块的 ##」
返回 Value → JSON(复用现有 host JSON 通路);侧效(写盘)在同一解释器事务语义内尽最大努力

不把 json= DB 路由改语义;invoke 是平行装配。

3.4 与 compose 期 call_lib_path 关系

时机 API
装配页 现有 compose / call_lib_path
每个 HTTP 请求 本设计 invoke

3.5 验收

  • POST JSON → 用户 ## 写入临时文件 + 返回 {ok:true,…}。
  • 未导入路径 → 4xx,不执行。
  • 金样:tests/ext/web-invoke-smoke.mq.md。

4. GAP-03 · MCP Server(ext/ai)

4.1 作者 API

*服务 = > agent.mcp_server name="marqdo-qd"*
*服务 = > `服务`.tool name="qd_search" fn="求道.搜索" description="关键词检索"*
*服务 = > `服务`.tool name="qd_capture" fn="求道.捕捉"*
*服务 = > `服务`.serve transport=stdio*
# 或
*服务 = > `服务`.serve transport=http host=127.0.0.1 port=7433*

工具表:

name fn description
qd_search 求道.搜索 …
qd_list 求道.列出 …

4.2 传输

transport 用途
stdio Cursor / Claude Desktop 拉起
http Streamable HTTP(与官方 MCP 演进对齐;首版可先 SSE+POST 子集)

4.3 与 A4 fixture 客户端关系

API 方向
mcp_list_tools / mcp_call 出站(Agent 调外部 MCP;现 fixture)
mcp_server + serve 入站(外部调 Marqdo)

客户端「真 MCP」仍见 agent 缺口文;本设计先交 Server,fixture 可保留测客户端。

4.4 ABI

  • plugins/agent:agent_mcp_server_*(注册工具、stdio loop、可选 HTTP)。
  • 工具实现:复用 GAP-02 同款「调用 ##」内核(可抽共享 invoke_fn),避免两套分发。
  • 返回包装:可含 authority=workbook。

4.5 验收

  • 金样:stdio 夹具发 tools/list + tools/call,断言 JSON-RPC 形结果。
  • 可选:tests/ext/agent-mcp-server-smoke.mq.md。

5. GAP-04 · 同寿副端口

5.1 关闭策略(优先)

GAP-01 + GAP-02 挂在同一 app.listen → 不实现副端口,文档宣布 GAP-04 关闭。

5.2 备选 API(仅当必须隔离)

*应用 = > `应用`.listen host=127.0.0.1 port=18081 also_port=7432 also_routes=`中继表`*

also_routes 仅允许 proxy / invoke 已注册子集。实现成本高,默认不做。


6. GAP-05 · 跨模块 db 与 corpus 可发现

6.1 db 句柄(扩展约定 + 运行时)

作者约定(立即文档化):

  1. 跨模块优先传 url 字符串,调用方 *store = > web.db url=…* 再 select。
  2. 若传对象:必须保留 _type 为插件注册名(与 web.db 构造一致)。

运行时修补(H 波次):

选项 做法 选用
A 跨模块返回插件对象时规范 _type + 全局方法表查找 首选(一次修好所有插件对象)
B db.open 只返回 {url} 朴素 map,禁止「裸 select」跨文件 文档契约;体验较差

金样:模块 A open → 返回 → 模块 B select 成功。
tests/ext/web-db-cross-module-smoke.mq.md。

6.2 corpus_search 可发现

## corpus_search
+ `query`
+ `root`=".marqdo/agent-kb"

* > plugin.load name=agent *
** > agent_corpus_search query=`query` root=`root` **

或在 # agent / ## corpus_search 入口统一 ensure_plugin(与现 agent 构造对齐),保证 纯 marqdo run + import agent 即可用。

不把 agent_corpus_search 搬进 src/host/。

6.3 验收

  • 无显式手工 ABI 名的情况下,marqdo run 金样调用 agent.corpus_search 成功。
  • 跨模块 db.select 金样绿。

7. 扩展库表面清单(落地时改这些文件)

文件 增补
ext/web/web.mq.md · 网页.mq.md ## proxy / ## invoke;configure 增 proxy/invoke 列
plugins/web/src/http.rs · middleware.rs · 新 proxy.rs / invoke.rs 路由注册与流式/调用
ext/ai/agent.mq.md · 智能体.mq.md # mcp_server · ## tool · ## serve;corpus_search ensure_plugin
plugins/agent/ MCP Server 传输 + 共享 invoke
tests/ext/web-proxy-sse-smoke.mq.md 等 见上
doc/roadmap/ext-web.md 链到 H 波次(不重开 W0–W7)
public/ / Skill 发版时补「同域 LLM 代理 / HTTP 调用 ##」短节

不新增 lib/run 作为核心依赖:用户业务 ## 仍在其自己的 lib/*.mq.md;Marqdo 只提供 invoke 管道。


8. 迁移:下游旁路 → 扩展 API

旁路(下游) 替换为
llm_proxy.py /proxy/stream app.proxy / configure proxy=
llm_proxy.py /store/* + marqdo run app.invoke → 用户 ##
mq_bridge.py 仅过滤 用户 ## 内 table/re 过滤,或修复后的 corpus_search
qdagent_mcp.py agent.mcp_server + serve
mq.sh 双进程 单 marqdo run index.mq.md(proxy+invoke 同端口)

9. 开放点(实现前拍板)

# 问题 默认倾向
1 invoke 的 fn 是否允许 path.mq.md##标题 字面量 允许但必须 invoke_allow 前缀
2 MCP HTTP 首版范围 stdio 先交;HTTP 跟一波
3 代理是否缓冲「非 SSE」大 body 非流式可限长缓冲;SSE 禁止整段缓冲
4 GAP-05 选项 A vs B A

10. 完成定义(整包)

  1. 无 Python 旁路即可:浏览器同域 SSE 对话 + HTTP 触发沉淀 ## +(可选)MCP stdio 暴露同一批 ##。
  2. 金样覆盖 proxy / invoke / cross-db / corpus / mcp-server(stdio)。
  3. doc/research/ext-hosting-gaps.md 各 GAP 标为关闭或降级为「备选副端口不做」。
  4. 发版说明指向 ext/web · ext/ai 新作者面,不指向 scripts/*.py。