docs(agent): record post-A4 framework gaps and next-wave B0–B5
Capture productization, eval, live MCP, resume/HITL, and metrics gaps after the A0–A4 optimize loop; link from roadmap and doc index. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
9a8545b725
commit
4c37e79dae
6 files changed
+201
-6
No files matched your search
@@ -3,6 +3,7 @@
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
- **调研:`ext/agent` A0–A4 之后缺口** ([agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)):产品化示例、评测 harness、真 MCP、plan resume/HITL、飞轮指标与建议分期 B0–B5;挂到 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md) 与 [doc/README.md](doc/README.md)。
|
||||
- **`ext/agent` A4(RAG/MCP 证据工具)**: `corpus_search` 本地语料关键词检索;`mcp_list_tools` / `mcp_call` 读 JSON fixture;返回 `authority=workbook`。金样 `agent-tools-rag-a4`。
|
||||
- **`ext/agent` A3(上下文预算)**: `source_brief` / 加深版 `skill_brief`;`build_step_context` 默认截断并提示 `READ:source|skill`;`step` 支持最多 `max_reads` 次加深;父 `READ:skill`。金样 `agent-context-budget-a3`。
|
||||
- **`ext/agent` A2(过程可见)**: `plan` 过程事件默认写入返回 map 的 `events`(SSE 仍仅 `stream=True`);OKF 命中记 `REUSE` decision;view plan 卡渲染过程时间线。对齐 [agent-streaming.md](doc/roadmap/agent-streaming.md)。
|
||||
|
||||
@@ -60,6 +60,9 @@
|
||||
| [roadmap/ext-web.md](roadmap/ext-web.md) | **实现路线:`ext/web`**(W0–W4;设计见 [ext-web.md](../design/ext-web.md)) |
|
||||
| [roadmap/ext-quantum.md](roadmap/ext-quantum.md) | **规划:`ext/quantum` 量子模拟**(基础门·电路·ABI·`ext add`) |
|
||||
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
|
||||
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点**(产品化 / 评测 / MCP / resume) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` 深入优化 A0–A4**(已完成) |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
|
||||
## 0. 为什么要改掉旧方案
|
||||
|
||||
|
||||
@@ -0,0 +1,190 @@
|
||||
# 调研:`ext/agent` 在 A0–A4 之后还差什么
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 缺口盘点(A0–A4 闭环之后)** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 前置调研 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md)(优势与优化原则) |
|
||||
| 已落地路线 | [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)(**A0–A4 done**) |
|
||||
| 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) |
|
||||
| 邻近规划 | [agent-streaming.md](../roadmap/agent-streaming.md) · [okf-near-match.md](../roadmap/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」**;缺口集中在:
|
||||
|
||||
1. **产品化与可发现性**(示例、文档新鲜度、上手路径)
|
||||
2. **生产配套**(评测 harness、真 MCP、断点续跑、HITL、飞轮指标)
|
||||
3. **可选扩展面**(并行 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|skill`;`step max_reads` |
|
||||
| **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` |
|
||||
| **中** | 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](../roadmap/okf-near-match.md) **E** 仅在 n-gram 证据不足时评估 | 不宣传为默认向量库 |
|
||||
| **刻意不做** | 私有 JSON TOOL 主路径 / 整文件 LLM 重写 | 与宪法及 parent 设计冲突 | 继续禁止 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 分项说明
|
||||
|
||||
### 4.1 产品化(高)
|
||||
|
||||
**问题**
|
||||
内核能力已超过「能演示」门槛,但**可感知产品体验**仍依赖读设计文档与翻 `tests/ext/`。对照 quantum / web 已有 `examples/`,agent 侧空白最明显。
|
||||
|
||||
**建议**
|
||||
1. 一份最小可运行示例:`step` → `plan` → promote → 二次 `plan` 打印 `cache=hit`。
|
||||
2. 同步 Skill / `doc/README` / 公开页,删掉「仅 layout」类过时句。
|
||||
3. 示例强调「权威在 `.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](../design/ext-agent.md) §9)。
|
||||
|
||||
### 4.6 多 Agent / A2A / 外发 trace(低)
|
||||
|
||||
**问题**
|
||||
业界热度高(Crews、A2A、共享记忆层)。Marqdo 的「父 + 多工作簿」已覆盖多数单组织编排;跨组织 A2A 与共享记忆库是另一产品层,可用 MCP/证据工具接入,而不必把记忆权威搬出 `.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议的下一波分期(草案 B)
|
||||
|
||||
> 非正式锁定;落地时再写入 [ext-agent-optimize.md](../roadmap/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. 明确「不是缺口」的清单
|
||||
|
||||
避免把差异化优势误判为缺陷:
|
||||
|
||||
1. **没有默认 dense 向量库** — 有意;OKF near 是稀疏词法;corpus 是关键词证据。
|
||||
2. **没有隐藏 TOOL: JSON 主协议** — 有意;CALL/READ/DECISION 与文档同构。
|
||||
3. **子任务默认 quiet** — 有意;答案走返回值,过程走 events/stream。
|
||||
4. **ext 不直调 host_*** — 有意;Agent 域在插件,防核心膨胀。
|
||||
5. **不捆绑领域工单技能** — 有意;官方框架保持可教、可审、可扩展。
|
||||
|
||||
---
|
||||
|
||||
## 7. 结论与推荐下一刀
|
||||
|
||||
A0–A4 之后,Marqdo `ext/agent` 在「文档驱动智能体」叙事上已经**自洽且可演示**。相对业界,短板是 **被人用起来的路径** 与 **生产级配套**,不是再堆一条编排 DSL。
|
||||
|
||||
**推荐下一刀顺序:**
|
||||
|
||||
1. **B0 官方示例 + 文档去陈**(最低成本、最高感知)
|
||||
2. **B1 评测 harness**(锁住飞轮与质量,防止回退)
|
||||
3. 按真实用户需求选 **B2 live MCP** 或 **B3 resume/HITL**
|
||||
|
||||
若四问在 B0–B1 后均可回答「是」,再考虑 B4/B5 与低优先级项。
|
||||
|
||||
---
|
||||
|
||||
## 8. 参考
|
||||
|
||||
### 本仓
|
||||
|
||||
- [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md)
|
||||
- [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)
|
||||
- [okf-near-match.md](../roadmap/okf-near-match.md)(E dense 仍非默认)
|
||||
- [agent-streaming.md](../roadmap/agent-streaming.md)
|
||||
|
||||
### 外部(抽样,2026)
|
||||
|
||||
- LangGraph Persistence(checkpointer / store)
|
||||
- CrewAI Crews + Flows;MCP 作为工具连接层而非编排本体
|
||||
- 业界对 Agent evaluation、durable memory / A2A 状态层的讨论(共享记忆 ≠ 应取代可执行文档权威)
|
||||
@@ -6,7 +6,7 @@
|
||||
| 日期 | 2026-08-28 |
|
||||
| 范围 | 2025–2026 开源/厂商智能体框架形态;对照 Marqdo `ext/ai/agent` 设计 |
|
||||
| 相关设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) · [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md) |
|
||||
| 姊妹调研 | [okf-and-marqdo.md](okf-and-marqdo.md) |
|
||||
| 姊妹调研 | [okf-and-marqdo.md](okf-and-marqdo.md) · **A0–A4 后缺口** [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
|
||||
| 外部对照(抽样) | [Langfuse 框架对比(2026-07)](https://langfuse.com/blog/2025-03-19-ai-agent-comparison) · [LangGraph persistence](https://docs.langchain.com/oss/python/langgraph/persistence) · [Microsoft Agent Framework / AutoGen 维护模式](https://github.com/microsoft/autogen) · CrewAI / OpenAI Agents SDK / Claude Agent SDK / Google ADK / LlamaIndex 公开文档 |
|
||||
|
||||
---
|
||||
@@ -520,7 +520,8 @@ Marqdo 用「代码即文档、文档即知识库」把 Agent 开发收束到 **
|
||||
- [ext-agent-parent.md](../design/ext-agent-parent.md) — 父 Plan-and-Move
|
||||
- [okf.md](../design/okf.md) · [okf-and-marqdo.md](okf-and-marqdo.md)
|
||||
- [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md)
|
||||
- [roadmap/agent-streaming.md](../roadmap/agent-streaming.md) · [roadmap/okf-near-match.md](../roadmap/okf-near-match.md)
|
||||
- [roadmap/agent-streaming.md](../roadmap/agent-streaming.md) · [roadmap/okf-near-match.md](../roadmap/okf-near-match.md) · [roadmap/ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)
|
||||
- [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) — A0–A4 之后还差什么
|
||||
|
||||
### 外部(抽样,2025–2026)
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | **A0–A4 完成**(调研驱动优化闭环;A4:corpus/MCP 证据工具,权威仍是 `.mq.md`) |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) |
|
||||
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · **缺口盘点** [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) |
|
||||
| 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) |
|
||||
| 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) |
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视**。
|
||||
3. 外部 RAG/MCP 只作**工具**,不升为权威真相源。
|
||||
|
||||
自评四问见调研 §9。
|
||||
自评四问见调研 §9。A0–A4 之后的缺口与建议分期 **B0–B5** 见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -30,4 +30,4 @@
|
||||
| **A3** | 上下文预算(源码/Skill 渐进披露) | **done** — `source_brief` / 加深 `skill_brief`;`build_step_context` 默认预算 + `READ:source|skill`;`step max_reads`;父 `READ:skill`;金样 `agent-context-budget-a3` |
|
||||
| **A4** | 可选:RAG/MCP 工具适配器 | **done** — `corpus_search`(本地语料关键词);`mcp_list_tools` / `mcp_call`(JSON fixture);`authority=workbook`;金样 `agent-tools-rag-a4` |
|
||||
|
||||
细节与行业对照以调研正文为准;本文件只跟踪实现分期。
|
||||
细节与行业对照以调研正文为准;本文件只跟踪 **A0–A4** 实现分期。后续产品化 / 评测 / live MCP 等见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) §5(草案 B0–B5)。
|
||||
Reference in new issue
Block a user