- 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。
11 KiB
Executable File
11 KiB
Executable File
设计:宿主集成缺口补齐(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 |
禁止:
- 为中继在浏览器手写业务 JS。
json=继续塞「任意##」语义(保持 DB-only;新能力用独立装配名)。- MCP Server 把向量库升为权威真相(工具结果可带
authority=workbook)。 - 无白名单的「任意文件系统路径 + 任意
##」远程触发。
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 安全默认(锁定)
- 仅解析入口 workbook 已导入的
bind路径,或invoke_allow=显式前缀列表。 - 单请求超时 + 可选并发上限(防 listen 线程饿死)。
- 默认不启;作者显式
invoke/configure invoke=。 - 错误:
{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 验收
POSTJSON → 用户##写入临时文件 + 返回{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 句柄(扩展约定 + 运行时)
作者约定(立即文档化):
- 跨模块优先传
url字符串,调用方*store = > web.db url=…*再select。 - 若传对象:必须保留
_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. 完成定义(整包)
- 无 Python 旁路即可:浏览器同域 SSE 对话 + HTTP 触发沉淀
##+(可选)MCP stdio 暴露同一批##。 - 金样覆盖 proxy / invoke / cross-db / corpus / mcp-server(stdio)。
doc/research/ext-hosting-gaps.md各 GAP 标为关闭或降级为「备选副端口不做」。- 发版说明指向
ext/web·ext/ai新作者面,不指向scripts/*.py。