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>
307 lines
11 KiB
Markdown
307 lines
11 KiB
Markdown
# 设计:宿主集成缺口补齐(`ext/web` · `ext/ai`)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **Accepted · H1–H4 stdio 已落地**(H4b HTTP 可选) |
|
||
| 日期 | 2026-09-07 |
|
||
| 缺口盘点 | [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) |
|
||
| 路线图 | [ext-hosting.md](../roadmap/ext-hosting.md) |
|
||
| 边界 | [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [ext-agent.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
|
||
|
||
```markdown
|
||
*应用 = > `应用`.proxy path="/v1/chat/completions" upstream=$OPENAI_BASE_URL*
|
||
*应用 = > `应用`.proxy path="/llm/stream" upstream="https://api.example.com" strip_prefix="/llm" stream=True*
|
||
```
|
||
|
||
或装配表(一次挂多条):
|
||
|
||
```markdown
|
||
*应用 = > `应用`.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
|
||
|
||
```markdown
|
||
*应用 = > `应用`.invoke path="/api/沉淀" method=POST fn="run.沉淀"*
|
||
```
|
||
|
||
表形式:
|
||
|
||
```markdown
|
||
*应用 = > `应用`.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
|
||
|
||
```markdown
|
||
*服务 = > 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(仅当必须隔离)
|
||
|
||
```markdown
|
||
*应用 = > `应用`.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` 可发现
|
||
|
||
```markdown
|
||
## 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`。
|