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>
11 KiB
调研:ext/agent 在 A0–A4 之后还差什么
| 状态 | 调研笔记 · 缺口盘点(A0–A4 闭环之后) |
| 日期 | 2026-08-28 |
| 前置调研 | agent-frameworks-and-marqdo.md(优势与优化原则) |
| 已落地路线 | ext-agent-optimize.md(A0–A4 done) |
| 设计 | ext-agent.md · ext-agent-plan.md · ext-agent-parent.md · okf.md |
| 邻近规划 | agent-streaming.md · okf-near-match.md |
| 外部对照(2026) | LangGraph persistence / CrewAI+Flows / MCP 工具协议 / 业界 Agent 评测与记忆层讨论 |
0. 一句话结论
调研驱动的 A0–A4 已把 Marqdo 智能体的差异化内核补齐:工作簿补丁可靠、OKF 复用飞轮可读可用、过程事件可审、上下文有预算、外置检索/MCP 只作证据。
相对 2026 年主流框架(LangGraph、CrewAI、厂商 SDK、MCP 生态),Marqdo 不再缺「能跑的 Agent loop」;缺口集中在:
- 产品化与可发现性(示例、文档新鲜度、上手路径)
- 生产配套(评测 harness、真 MCP、断点续跑、HITL、飞轮指标)
- 可选扩展面(并行 fan-out、多 Agent/A2A、trace 外发)
不要用缺口清单去证明应回退到隐藏 TOOL: 循环或把向量库升为权威真相——那与宪法冲突,也抵消已落地的优势。
1. 已落地基线(A0–A4)
| 波次 | 主题 | 验收要点 |
|---|---|---|
| A0 | 工作簿补丁 / 固化 | 整文件 FIND 护栏;soft 仅 miss;workbook_solidify;金样 agent-workbook-patch-a0 |
| A1 | OKF 复用飞轮 | list_tasks 策展字段;plan 暴露 match/score;金样 agent-kb-plan-hit |
| A2 | 过程可见 | events 默认落盘;view plan 过程卡;SSE 仍仅 stream=True |
| A3 | 上下文预算 | source_brief / skill_brief;`READ:source |
| A4 | RAG/MCP 证据工具 | corpus_search;fixture mcp_*;authority=workbook |
原则回顾(见前置调研 §9):强化差异化;资源砸在工作簿 / 写回 / 固化 / OKF / 过程可视;外置 RAG/MCP 只作工具。
2. 相对业界:已经「够格」的部分
下列能力若取消「可执行 Markdown 为权威」即消失——这是护城河,不是功能点攀比:
| 能力 | Marqdo 形态 | 业界常见替代 |
|---|---|---|
| 单一真相源 | 源码即提示 + 调用点注入 | Prompt Hub / 字符串 system |
| 过程可审 | 写回块 + events + view 过程卡 |
Langfuse / LangSmith 外挂 |
| 成功可复用 | OKF 任务技能再跑 | transcript 再聊 / 向量片段召回 |
| 复杂任务边界 | 工作簿文件 + subtask |
无限加长 chat / 临时工具输出 |
| 确定步骤降本 | solidify → llm_free 快路径 |
每轮仍问模型 |
自评四问(前置调研 §9)粗判:
| 问 | 现状 |
|---|---|
新人能否只读一份 .mq.md 理解 Agent? |
部分 — 机制在,缺 canonical 示例教程 |
| 失败后能否在 git + view 复盘、不强制外部 trace? | 基本可以 |
| 成功任务下周能否以同一技能复用? | 可以(金样已锁二次命中) |
确定步骤是否越来越多变成普通 ##、模型调用下降? |
路径有(solidify / llm_free),缺量化看板证明 |
3. 缺口总表(按优先级)
| 优先级 | 缺口 | 为何还缺 | 建议验收线索 |
|---|---|---|---|
| 高 | 官方端到端示例 + 文档新鲜度 | 无独立 examples/agent-*;Skill/参考里仍有「layout / roadmap」陈旧表述;外人难「照抄即跑通 plan→固化→二次命中」 |
examples/agent-pong(或同类)+ README;Skill 专节与 A0–A4 对齐 |
| 高 | Agent 评测 / 回归 harness | 有离线金样,缺成本·恢复·命中率·补丁质量的系统评测;业界强调 evaluation 先于上线 | tests/ 或脚本:命中率、llm_free 占比、失败恢复、可选 live 预算 |
| 高 | 真 MCP(HTTP/SSE)与凭证 | A4 仅 JSON fixture;缺 streamable HTTP、鉴权、resources/prompts | 金样打 mock MCP server;返回仍带 authority=workbook |
| 高 | MCP Server 宿主(stdio / HTTP) | Agent 只能当客户端 fixture;IDE 无法把 .mq.md ## 暴露为 MCP 工具 |
见 ext-hosting-gaps.md GAP-03 · ext-hosting-fill.md |
| 中 | Plan 断点续跑 | 工作簿在盘上,缺显式 checkpoint / resume(对标 LangGraph checkpointer) | plan resume= 从第 N 轮 DECISION 继续;进程崩溃可恢复 |
| 中 | 人机协同(HITL)加深 | 仅有 confirm=True 建簿即停;缺审批卡、拒绝重开、view 一键继续 |
view 审批控件 + 金样 |
| 中 | 飞轮可观测指标 | hits / improve_every / llm_free 有字段,缺汇总与 CLI/view 报表 |
agent_kb_stats 或 view 面板:命中率、探索浪费 |
| 中 | 受控并行 fan-out | subtask 能并行,plan 主路径偏串行 |
父协议允许有界并行调研再合并 |
| 低 | 多 Agent / A2A | dual skeleton 有;缺角色班组、跨进程 A2A | 多数场景可用「多工作簿 + 父 CALL」覆盖;有明确跨组织需求再开 |
| 低 | Trace 外发(OTLP / Langfuse) | 本地复盘已够;外发是集成题 | 可选 adapter;默认不依赖 |
| 刻意不做 | Dense embedding 默认化 | okf-near-match.md E 仅在 n-gram 证据不足时评估 | 不宣传为默认向量库 |
| 刻意不做 | 私有 JSON TOOL 主路径 / 整文件 LLM 重写 | 与宪法及 parent 设计冲突 | 继续禁止 |
4. 分项说明
4.1 产品化(高)
问题
内核能力已超过「能演示」门槛,但可感知产品体验仍依赖读设计文档与翻 tests/ext/。对照 quantum / web 已有 examples/,agent 侧空白最明显。
建议
- 一份最小可运行示例:
step→plan→ promote → 二次plan打印cache=hit。 - 同步 Skill /
doc/README/ 公开页,删掉「仅 layout」类过时句。 - 示例强调「权威在
.mq.md」,corpus/mcp 仅作证据旁路。
4.2 评测 harness(高)
问题
金样锁行为正确性;不锁「飞轮是否在变好」「一次失败后能否恢复」「live 成本是否失控」。2026 多 Agent 讨论普遍把 evaluation 列为上线前缺失步骤。
建议
- 离线:命中路径、补丁护栏、预算截断(已有)再加 stats 断言。
- 半自动 / live:固定小 goal 集,记录 rounds、cache 分布、token 粗估(若可从供应商响应取得)。
- 明确:评测消费的是工作簿与 kb,而不是外部 transcript 库。
4.3 真 MCP(高)与「证据≠权威」(不变)
问题
Fixture 证明协议形状与权威字段;生产要接真实 MCP server(工具、资源、鉴权)。
约束
- 工具结果进入 observation / CALL 回执,不得静默写成 OKF 权威技能。
- 晋升仍走 promote / solidify / 人审(既有路径)。
4.4 断点续跑与 HITL(中)
问题
LangGraph 类框架的 checkpointer / interrupt 是生产差异点。Marqdo 已有文件化状态(工作簿、写回、events),差的是一等恢复 API与可视审批。
建议方向
- Resume:序列化「当前 round、path、last observation、events」到约定槽或旁路文件,重启后跳过已完成子跑。
- HITL:扩展
confirm语义(建簿 / 危险 PATCH / promote);view 展示 pending 卡。
4.5 飞轮指标与并行(中)
问题
第四问(模型调用是否下降)需要数字。并行能缩短探索,但须有界,避免工作簿爆炸(见 ext-agent.md §9)。
4.6 多 Agent / A2A / 外发 trace(低)
问题
业界热度高(Crews、A2A、共享记忆层)。Marqdo 的「父 + 多工作簿」已覆盖多数单组织编排;跨组织 A2A 与共享记忆库是另一产品层,可用 MCP/证据工具接入,而不必把记忆权威搬出 .mq.md。
5. 建议的下一波分期(草案 B)
非正式锁定;落地时再写入 ext-agent-optimize.md 或独立
ext-agent-productize.md。
| 波次 | 主题 | 验收线索 |
|---|---|---|
| B0 | 官方示例 + Skill/文档去陈 | examples/agent-* 可 marqdo run;Skill 与 A0–A4 一致 |
| B1 | 评测 harness | 命中率 / llm_free / 恢复用例可一键跑 |
| B2 | Live MCP 客户端 | mock server 金样;authority=workbook 不变 |
| B3 | Plan resume + HITL | 崩溃可续;view 审批 |
| B4 | kb stats 面板 | CLI 或 view 展示飞轮数字 |
| B5 | 有界并行(可选) | fan-out 上限 + 合并观察 |
6. 明确「不是缺口」的清单
避免把差异化优势误判为缺陷:
- 没有默认 dense 向量库 — 有意;OKF near 是稀疏词法;corpus 是关键词证据。
- 没有隐藏 TOOL: JSON 主协议 — 有意;CALL/READ/DECISION 与文档同构。
- 子任务默认 quiet — 有意;答案走返回值,过程走 events/stream。
- ext 不直调 host_* — 有意;Agent 域在插件,防核心膨胀。
- 不捆绑领域工单技能 — 有意;官方框架保持可教、可审、可扩展。
7. 结论与推荐下一刀
A0–A4 之后,Marqdo ext/agent 在「文档驱动智能体」叙事上已经自洽且可演示。相对业界,短板是 被人用起来的路径 与 生产级配套,不是再堆一条编排 DSL。
推荐下一刀顺序:
- B0 官方示例 + 文档去陈(最低成本、最高感知)
- B1 评测 harness(锁住飞轮与质量,防止回退)
- 按真实用户需求选 B2 live MCP 或 B3 resume/HITL
若四问在 B0–B1 后均可回答「是」,再考虑 B4/B5 与低优先级项。
8. 参考
本仓
- agent-frameworks-and-marqdo.md
- ext-agent-optimize.md
- okf-near-match.md(E dense 仍非默认)
- agent-streaming.md
外部(抽样,2026)
- LangGraph Persistence(checkpointer / store)
- CrewAI Crews + Flows;MCP 作为工具连接层而非编排本体
- 业界对 Agent evaluation、durable memory / A2A 状态层的讨论(共享记忆 ≠ 应取代可执行文档权威)