From c36383bf28123fa4d0ccfa1bbb514df6ea7a10aa Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 28 Aug 2026 16:06:11 +0800 Subject: [PATCH] docs(agent): research frameworks vs Marqdo document-driven advantages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add detailed survey of LangGraph/CrewAI/SDK landscape, lock Marqdo differentiators, and sketch A0–A4 optimize roadmap for ext/agent. Co-authored-by: Cursor --- README.md | 2 + doc/design/ext-agent-plan.md | 2 +- doc/design/ext-agent.md | 2 +- doc/research/agent-frameworks-and-marqdo.md | 532 ++++++++++++++++++++ doc/roadmap/ext-agent-optimize.md | 33 ++ 5 files changed, 569 insertions(+), 2 deletions(-) create mode 100644 doc/research/agent-frameworks-and-marqdo.md create mode 100644 doc/roadmap/ext-agent-optimize.md diff --git a/README.md b/README.md index 3016801..2981111 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,8 @@ marqdo sync [PATH] -o OUT_DIR # catalog 的别名 产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。 +智能体框架横向调研(LangGraph / CrewAI / 厂商 SDK 等 vs Marqdo 文档驱动优势):[agent-frameworks-and-marqdo.md](doc/research/agent-frameworks-and-marqdo.md) · 优化路线 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md)。 + ```bash cargo run -- catalog public -o .marqdo # 或已安装二进制时: diff --git a/doc/design/ext-agent-plan.md b/doc/design/ext-agent-plan.md index 42c926a..e43dd31 100644 --- a/doc/design/ext-agent-plan.md +++ b/doc/design/ext-agent-plan.md @@ -5,7 +5,7 @@ | 状态 | **Accepted;D2a–D2f 已落地;父 Plan-and-Move / OKF 软命中见配套文档** | | 日期 | 2026-08-11 | | 父文档 | [ext-agent.md](ext-agent.md) | -| 相关 | [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move 行动面**) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [module-namespace.md](module-namespace.md) · [ai-skill.md](ai-skill.md) · [objects.md](objects.md) | +| 相关 | [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move 行动面**) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [module-namespace.md](module-namespace.md) · [ai-skill.md](ai-skill.md) · [objects.md](objects.md) · [调研:主流框架与 Marqdo](../research/agent-frameworks-and-marqdo.md) | --- diff --git a/doc/design/ext-agent.md b/doc/design/ext-agent.md index 6935fc8..10b909e 100644 --- a/doc/design/ext-agent.md +++ b/doc/design/ext-agent.md @@ -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 / 任务知识包**) · [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) · [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. 为什么要改掉旧方案 diff --git a/doc/research/agent-frameworks-and-marqdo.md b/doc/research/agent-frameworks-and-marqdo.md new file mode 100644 index 0000000..fc96df6 --- /dev/null +++ b/doc/research/agent-frameworks-and-marqdo.md @@ -0,0 +1,532 @@ +# 调研:主流智能体开发框架与 Marqdo「代码即文档 / 文档即知识库」优势 + +| | | +|---|---| +| 状态 | **调研笔记 · 供 `ext/agent` 深入优化参考** | +| 日期 | 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) | +| 外部对照(抽样) | [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 公开文档 | + +--- + +## 0. 一句话结论 + +主流智能体框架几乎都在解决同一组工程问题——**编排、工具、状态、记忆、可观测、人机协同**——但它们的「权威真相」默认落在 **Python/TS 对象图 + 会话 transcript + 外部 Store/向量库** 上。 + +Marqdo 的宪法把权威真相定在 **可执行 Markdown(`.mq.md`)**:人写的程序、模型读的提示、执行后的写回、可复用的任务技能,是**同一份文档的不同生命阶段**。这不是「又一个 Agent SDK」,而是把 **Agent 开发本身做成文档工程**。 + +由此产生的突出优势(后文展开): + +1. **编排可读 = 提示词不再黑盒**(源码即上下文) +2. **过程可审 = 写回进源文件,而不是只进遥测平台** +3. **记忆可 git = 成功经验晋升为任务知识包(OKF),审计=仓库历史** +4. **复杂任务=子程序,而不是无限加长的 chat**(工作簿 + `subtask`) +5. **确定步骤固化为代码,不确定步骤才问模型**(父 Plan-and-Move) +6. **语言与知识形态同构**(与 Google OKF「Markdown 知识包」同向,但多走「可执行」一步) + +**优化 `ext/agent` 时应守住这些差异化,而不是向 LangChain 类「隐藏循环 + TOOL: 协议」回退。** + +--- + +## 1. 调研方法与边界 + +### 1.1 做了什么 + +| 动作 | 说明 | +|------|------| +| 横向扫盘 | 2026 年主流开源框架:LangGraph / LangChain DeepAgents、CrewAI、OpenAI Agents SDK、Claude Agent SDK、Google ADK、Microsoft Agent Framework(AutoGen 继承者)、Pydantic AI、LlamaIndex、Strands、Mastra / Vercel AI SDK、smolagents 等 | +| 结构抽象 | 抽取「框架如何形成」的共性分层,而不是比 GitHub stars | +| 对照本仓 | 精读 `ext-agent*`、`okf`、`writeback`、`subtask`、parent Plan-and-Move;对照旧 TOOL: 薄循环为何被否定 | +| 找优越点 | 只保留 **Marqdo 结构上必然领先**、而非「以后可以加插件追上」的点 | + +### 1.2 不做的 + +- 不宣称 Marqdo 在吞吐、多模态、托管运维上已全面领先(这些不是当前差异化)。 +- 不把「有没有向量检索」当成胜负手——那是应用层可加能力。 +- 不做厂商营销话术复读;优缺点按**开发者体验与系统真相源**评。 + +--- + +## 2. 智能体框架是怎么「形成」的 + +无论品牌如何包装,成熟框架通常收敛为同一条装配线: + +```text +┌─────────────────────────────────────────────────────────────┐ +│ 1. Model I/O │ +│ 补全 / 工具调用 / 流式 / 多模供应商适配 │ +├─────────────────────────────────────────────────────────────┤ +│ 2. Agent 单元 │ +│ 指令(system) + 工具表 + 可选角色/人设 │ +├─────────────────────────────────────────────────────────────┤ +│ 3. 编排(Orchestration) │ +│ 图 / 角色队 / 对话群 / 工作流 API / supervisor │ +├─────────────────────────────────────────────────────────────┤ +│ 4. 状态与记忆 │ +│ 短:thread checkpoint / 会话历史 │ +│ 长:Store / 向量 RAG / 用户偏好库 │ +├─────────────────────────────────────────────────────────────┤ +│ 5. 工具与行动面 │ +│ 函数 schema、MCP、沙箱、权限、CodeAct │ +├─────────────────────────────────────────────────────────────┤ +│ 6. 可观测与治理 │ +│ Trace、评测、护栏、HITL、配额 │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 2.1 三种主流「编排哲学」 + +| 范式 | 核心隐喻 | 代表 | 可预测性 | 原型速度 | +|------|----------|------|----------|----------| +| **图 / 状态机** | 节点=步骤,边=转移,状态显式 | LangGraph、Google ADK workflow、MAF workflows | 高 | 中–慢(先画图) | +| **角色协作** | Agent=工种,Crew=班组 | CrewAI、早期 AutoGen 群聊 | 中 | 快 | +| **薄循环 + 工具** | 「模型自己决定下一步」 | OpenAI Agents SDK、Claude Agent SDK、Strands、smolagents | 低–中(靠护栏) | 最快 | + +2026 年的趋势不是「哪个范式消灭其它」,而是: + +- **生产复杂流** → 图(可控、可恢复、HITL)。 +- **内容/研究班组** → 角色。 +- **编码助手 / 生态绑定** → 厂商 SDK 自带 hardened loop。 +- **LangChain DeepAgents** 等开始把「规划器 + 子代理 + 文件记忆」打包成 opinionated harness——说明业界也意识到:纯 chat 不够,需要**文件与子上下文**。 + +### 2.2 记忆层的行业共识(与 Marqdo 对照的关键) + +以 LangGraph 文档为代表(行业事实上的标准划分): + +| 层 | 行业做法 | 作用 | +|----|----------|------| +| **短时** | Checkpointer / thread_id | 会话续跑、崩溃恢复、time-travel | +| **长时** | BaseStore / 向量库 / Mem0·Zep 等 | 跨会话事实、偏好 | +| **检索知识** | RAG corpus | 领域文档,不与会话状态混用 | + +常见架构错误:把 checkpointer 当成长时记忆——换 `thread_id` 就「失忆」。 + +**这一点对 Marqdo 极关键:** +行业把「记忆」拆成多个后端;Marqdo 默认把**任务级成功经验**落成 **`.mq.md` + agent-kb(OKF)**,用文件系统与 git 当记忆平面——见 §7。 + +### 2.3 框架「形成产品」的路径 + +```text +PoC(脚本循环) + → SDK(Agent + tools) + → 编排(图 / 多代理) + → 持久化(checkpoint / store) + → 平台(托管、评测、护栏、计费) +``` + +越往后,**编排源码与运行时真相越分离**:提示在字符串常量或 Prompt Hub,状态在 DB,轨迹在 Langfuse,知识在向量库。人要复盘一次失败,往往要开四个系统。 + +Marqdo 的赌注是:**尽量把真相拉回单一 `.mq.md` 时间线**。 + +--- + +## 3. 代表框架解剖(如何形成 + 优缺点) + +### 3.1 LangGraph(显式状态图) + +**如何形成** + +- 把 Agent 步骤建模为 **有向图**:节点读/写共享 state,条件边决定下一跳。 +- 编译为可执行应用;挂 checkpointer → 持久化、HITL interrupt、故障续跑。 +- 长时记忆另挂 Store;生态上接 LangChain 工具与 LangSmith/Langfuse 轨迹。 + +**优点** + +- 生产向可控性最强;分支、重试、并行边清晰。 +- 状态类型化后,测试与回放(time-travel)可行。 +- 云中立:图在你自己的进程里跑。 + +**缺点** + +- 上手成本高:先设计图,再写节点。 +- 「提示词 / 业务说明」仍常散落在 Python 字符串;**图代码 ≠ 给人读的说明书**。 +- 记忆与知识仍依赖外置 Store/RAG;审计链路长。 +- DeepAgents 等上层 harness 说明:光有图仍不够「文件化协作」。 + +**对 Marqdo 的启示** + +- 要学其「显式控制与可恢复」;不要学其「状态默认在对象里」。 +- Marqdo 多步的工作簿修订环 ≈ **把图展开成磁盘上的可执行文档**。 + +--- + +### 3.2 CrewAI(角色班组 + Flows) + +**如何形成** + +- Agent = role / goal / backstory;Crew 协调任务;近年加 **Flows** 把确定性业务逻辑包住自治班组。 + +**优点** + +- 多代理叙事直观,原型极快。 +- 适合内容流水线、调研班组。 + +**缺点** + +- 协作转移大量靠描述,**可预测性弱于图**。 +- 过程真相仍是运行时对象与日志;与「文档即程序」无关。 +- HITL / 企业治理相对弱。 + +**对 Marqdo 的启示** + +- 「多角色」可用多个 `# 智能体` / 多个工作簿表达,但应以**可跑文档**为边界,而不是隐式群聊。 + +--- + +### 3.3 AutoGen → Microsoft Agent Framework(MAF) + +**如何形成** + +- AutoGen:对话对 / 群聊驱动;历史在内存。 +- 2026:AutoGen **维护模式**;能力并入 **Microsoft Agent Framework**(与 Semantic Kernel 合流):ChatAgent + 多种编排(sequential / concurrent / handoff / group / Magentic)+ 工作流图 + Azure Foundry 治理面。 + +**优点** + +- 企业栈(.NET / Azure)一体;A2A、MCP、护栏、托管轨迹。 +- CodeAct 等模式:让 Agent **写代码执行**而非只吐 JSON——与「固化为代码」方向有共鸣。 + +**缺点** + +- 生产治理深度常绑定云平台;开源核心与托管能力分层。 +- 编排语言仍是通用编程语言;**业务知识与程序不同构**。 +- 对话范式易导致「无限闲聊」式多代理。 + +**对 Marqdo 的启示** + +- CodeAct / 固化步骤:与 Marqdo「确定步骤写成 `##`」同向,但 MAF 写的是 Python;Marqdo 写的是**人与模型共用的 `.mq.md`**。 + +--- + +### 3.4 OpenAI Agents SDK / Claude Agent SDK / Google ADK / Strands + +**如何形成(共性)** + +- 提供 **hardened agent loop**(工具、handoff、权限、会话)。 +- 深度绑定自家模型或云(OpenAI / Anthropic Claude Code harness / Gemini+ADK / Bedrock)。 + +**优点** + +- 最快接入「能干活的助手」;权限与工具路径经过产品锤炼(尤其 Claude Code 同源 SDK)。 +- 官方 tracing、realtime 等增值。 + +**缺点** + +- 编排与提示仍在宿主语言;**跨团队知识复用靠复制仓库或 Prompt 平台**。 +- 供应商锁定风险;换模时常换范式。 +- 「记忆」默认会话式;企业知识仍外挂。 + +**对 Marqdo 的启示** + +- 模型 I/O 应继续放在 `ext/llm`,**不要**在 agent 里重造聊天栈。 +- 不要把「官方 loop」当哲学:Marqdo 的哲学是文档驱动,不是 SDK 驱动。 + +--- + +### 3.5 LlamaIndex / Haystack(文档与 RAG 优先) + +**如何形成** + +- 以索引、检索、查询引擎为中心;Agent 是检索之上的编排层。 + +**优点** + +- 企业文档智能、多格式摄取成熟。 +- 「知识」有一等公民地位。 + +**缺点** + +- 知识默认是 **被检索的被动语料**,不是 **可执行的任务程序**。 +- Agent 编排能力弱于 LangGraph 系;常需再叠一层框架。 +- 索引与源文档易漂移(双源真相)。 + +**对 Marqdo 的启示(尖锐对比)** + +- LlamaIndex:**文档 → 向量 → 检索 → 回答**。 +- Marqdo:**文档 → 可执行语法 → 运行 → 写回 →(可选)晋升为任务知识包**。 + 同一「Markdown 知识」在 Marqdo 里可以是 **会跑的技能**,而不仅是 chunk。 + +--- + +### 3.6 Pydantic AI / Mastra / Vercel AI SDK + +**如何形成** + +- 强调类型安全(Pydantic)或 TS 全栈 DX(Mastra / Vercel)。 +- 把 Agent 当普通后端组件:校验、otel、耐久执行。 + +**优点** + +- 工程化体验好;与现有 Web/API 栈融合。 + +**缺点** + +- 仍是「代码库里的 Agent」;非技术干系人无法直接打开同一份编排当说明书。 +- 知识沉淀路径仍外置。 + +--- + +### 3.7 横向对比表(开发者真相源) + +| 维度 | 典型框架落点 | Marqdo 落点 | +|------|--------------|-------------| +| 编排定义 | Python/TS 图或类 | `.mq.md` 标题/表/调用 | +| 系统提示 | 字符串 / Prompt Hub | 站立提示写在同一文档 | +| 工具 | 装饰器函数 / MCP | runbook 内 `##` + `subtask` | +| 短时状态 | checkpoint / session | 工作簿文件 + 写回块 + view | +| 长时记忆 | Store / 向量 | agent-kb(OKF)+ git | +| 复杂任务 | 子图 / 子代理上下文窗 | **子 `.mq.md` 程序** `spawn path=` | +| 复盘 | Langfuse trace | `git log` + 打开工作簿 + view output-card | +| 成功复用 | 手工抽 prompt / 存 Store | **固化 + OKF 晋升 / lookup** | + +--- + +## 4. 行业共性痛点(框架越强,痛点越清晰) + +下列痛点在 LangGraph、CrewAI、厂商 SDK 文档与实践文章中反复出现;它们正是 Marqdo 要正面打穿的: + +### 4.1 提示词与编排分离 + +- 行为由 system prompt + 隐藏模板决定;code review 审不到「模型真正看见什么」。 +- Prompt 漂移与代码漂移双轨发生。 + +### 4.2 过程不透明或只对平台透明 + +- 本地只有最终返回值;细节在 SaaS trace。 +- 合规团队要的「这份文档当时怎么决策的」难以直接交付。 + +### 4.3 记忆碎片化 + +- thread / store / RAG / 日志四套系统;「上次同类任务怎么做成的」检索成本高。 +- 成功经验很少自动变成**可再执行资产**。 + +### 4.4 多步任务变成超长 transcript + +- 上下文窗口被工具输出撑爆;DeepAgents 才开始「卸到文件系统」。 +- 说明业界被迫走向 **文件化**——而 Marqdo **一开始就以文件为执行边界**。 + +### 4.5 确定性逻辑仍反复问模型 + +- 已验证的步骤下一轮又被重新「推理」,浪费且不稳。 +- 缺少「晋升为普通代码」的一等路径。 + +### 4.6 Agent 框架与知识格式断裂 + +- Google OKF 等推动「知识用 Markdown 包交换」,但主流 Agent 框架并不把 **可执行程序** 当作知识页。 +- 结果:知识包给人策展,Agent 另跑一套 Python。 + +--- + +## 5. Marqdo 在智能体域的设计思想(必须找准) + +### 5.1 宪法重申 + +| 口号 | 在 Agent 语境下的含义 | +|------|------------------------| +| **代码即文档** | 智能体编排、工具表、站立提示、任务叙述写在同一份 `.mq.md`;打开即读、即可跑 | +| **文档即知识库** | 写回块、工作簿、OKF 任务页都是知识;Agent 与人共用同一交换面 | +| **文档能跑通 = 约定成立** | 金样 / `marqdo run` / view 是验收,不是「旁边另有一份真实现状」 | + +旧「TOOL: 黑盒循环」被官方设计明确否定,正是因为它把 Marqdo **降级成了 LangChain 的薄壳**。 + +### 5.2 两级执行(与业界范式对齐但不抄袭) + +| Marqdo | 业界近似 | 关键差异 | +|--------|----------|----------| +| `## step` 单步 | 薄 Agent loop | 注入**本文件源码 + 调用位置 + Skill**;默认写回 | +| `## plan` 多步 | 规划器 + 子代理 | 产物是 **工作簿 `.mq.md`**;经 `subtask` 整文件执行;父以补丁演进 | +| 父 Plan-and-Move | supervisor / orchestrator | 行动面:READ/CALL/DECISION;**禁止整文件 LLM 重写** | +| OKF agent-kb | long-term store | 命中的是 **可再跑的任务技能**,不是抽象 embedding 片段(可再叠加 soft near) | + +### 5.3 执行与隔离 + +- 工具与子工作簿走 `lib/subtask`(`spawn fn=` / `spawn path=`),与主推理隔离——对应业界「子代理独立上下文」,但边界是 **文件与子进程语义**,不是仅换一个 message list。 + +--- + +## 6. Marqdo 的必要突出优势(核心章节) + +下列优势要求满足:**若取消「可执行 Markdown 为权威」,优势即消失**。这才是「必要」优越点,而不是功能清单攀比。 + +### 6.1 单一真相源:编排 / 提示 / 结果共址 + +**优势陈述** +模型在 `step`/`plan` 中看到的上下文,可以就是**人类正在编辑的那份源码**(及调用点)。站立提示不是隐藏 system blob,而是文档段落。 + +**为何必要** +消除「提示词仓库 vs 代码仓库」双源;code review、教学、合规审计面对同一人造物。 + +**相对框架** +LangGraph/CrewAI/SDK:提示常在字符串或控制台配置;trace 在另一系统。Marqdo:`view` 在语句下挂 output-card,与源同行。 + +### 6.2 写回 = 内建的「Notebook 输出单元」式过程记忆 + +**优势陈述** +`lib/writeback` 把成功/失败写入 ``,锚在调用行下。智能体默认写回后,**过程留在源文件**,不是只留在遥测。 + +**为何必要** +教学与调试要「看见刚才那一步」;失败成为可读避坑记录;成功可被后续命中。 + +**相对框架** +业界靠 Langfuse/LangSmith;本地仓库往往是空的。Marqdo 仓库本身就是过程库(可再导出到 trace,但不依赖它才能复盘)。 + +### 6.3 复杂任务 = 生成并演进子程序,而不是堆 transcript + +**优势陈述** +`plan` 创建 `.marqdo/agent-runs/*.mq.md`,用 `spawn path=` 跑完整 `# main`。父观察**真实退出码、返回值、写回、源码**,再 FIND/REPLACE 补丁。 + +**为何必要** +上下文窗口有限;长工具输出必须卸出。DeepAgents 用「文件系统抽象」补课;Marqdo **语言层原生就是文件程序**。 + +**相对框架** +子代理多是「新对话 + 摘要」;Marqdo 子任务是 **可独立 `marqdo run` 的文档**,可被人类直接打开修改后重跑。 + +### 6.4 确定步骤固化为代码;模型只处理不确定残差 + +**优势陈述** +父作为「智能体开发大师」:能写成 `##` 的就固化;子智能体只跑不确定的 `step`。`DECISION: DONE` 可 solidify + OKF 晋升。 + +**为何必要** +降本、降方差、形成组织资产。业界常把每次任务重新推理;Marqdo 把「学会的技能」编译回语言。 + +**相对框架** +MAF CodeAct 写出的是通用语言脚本;Marqdo 固化的是 **仍保持文档属性的 `.mq.md` 技能**——人不用会 Python 也能读懂并改。 + +### 6.5 文档即知识库 + OKF:记忆可交换、可策展、可信任 + +**优势陈述** +任务知识包(`.marqdo/agent-kb/`)以 OKF 形承载 `Marqdo Task` / skill,`resource:` 必须指向可执行 `.mq.md`。lookup / near / soft_match 走插件,不进核心 host。 + +**为何必要** +Google OKF 证明行业需要「Markdown 知识包」;Marqdo 多走一步:**知识页声明的可执行资源真能跑**。记忆不是不可解释的向量命中,而是 **带路径的技能复用**。 + +**相对框架** +LlamaIndex 检索散文块;Store 存 JSON 事实。Marqdo agent-kb:**命中 → 再跑同一技能路径**(精确 / 规范化 / near / 父裁决)。 + +### 6.6 审计与协作默认路径 = Git + +**优势陈述** +工作簿演进、写回、晋升都是文件变更 → `git log` / PR / blame。 + +**为何必要** +企业已有代码治理;不必为 Agent 另建「提示治理平台」才能起步。 + +**相对框架** +多数框架的状态在 DB;要审计得接专用平台。Marqdo 从第一天就兼容软件工程工作流。 + +### 6.7 中英双面 API 与「说明书即程序」教学属性 + +**优势陈述** +`# 智能体` / `# agent`、`单步`/`step`、`多步`/`plan` 对称;教程文档可以直接是金样。 + +**为何必要** +智能体开发教育成本高;Marqdo 把教材和运行物合一(与 quantum/math 扩展同一哲学)。 + +### 6.8 分层纪律:扩展不脏核心 + +**优势陈述** +`ext/**` 禁 `host_*`;agent-kb 在 `plugins/agent`;核心保持瘦。 + +**为何必要** +避免「Agent 框架把语言运行时变成巨石」——这是许多 Python Agent 栈的终局病。 + +--- + +## 7. 优势地图(一图看懂定位) + +```text + 可预测性 / 生产控制 + ▲ + │ LangGraph / MAF workflows + │ + │ ★ Marqdo plan + │ (workbook = program) + │ + 角色班组 ──────────┼────────────── 薄循环 SDK + CrewAI │ OpenAI / Claude SDK + │ + │ LlamaIndex (RAG) + │ + └────────────────────────────► + 文档/知识一等公民程度 + +★ Marqdo 同时偏右上:控制来自「可执行文档+补丁环」, + 知识来自「同源 Markdown + OKF」,而非向量库单独称王。 +``` + +--- + +## 8. 诚实边界:什么时候不该硬吹 Marqdo + +| 场景 | 更合适的选择 | 原因 | +|------|--------------|------| +| 超大规模并行图、成熟 Python 数据栈 | LangGraph + 现有 infra | 生态与库广度 | +| 强绑定 Azure 治理 / .NET | MAF | 平台一体 | +| 纯文档问答 / 海量非结构化语料 | LlamaIndex 等 | 摄取与检索成熟;Marqdo 可 **调用** 它们作工具,不必重造 | +| 只要一个 ChatGPT 式助手周末原型 | 厂商 Agents SDK | 启动最快 | +| 需要强实时语音 / 多模原生 | 厂商 SDK | 非 Marqdo 当前主场 | + +Marqdo 的正确叙事不是「取代所有 Agent 框架」,而是: + +> **当你希望智能体开发成果沉淀为组织可维护的文档资产,并且编排本身必须可教、可审、可跑时——选 Marqdo。** + +--- + +## 9. 对 `ext/agent` 深入优化的建议方向(调研导出) + +优化应强化 §6 优势,避免回退到「隐藏 TOOL 循环」。 + +| 优先级 | 方向 | 理由 | +|--------|------|------| +| P0 | **工作簿质量与补丁可靠性**(精确 FIND/REPLACE、固化、观察切片) | 直接决定「子程序演进」是否优于 transcript | +| P0 | **OKF 命中体验**(精确 / near / soft_match 默认真策略、策展 UX) | 落实「文档即知识库」的复用飞轮 | +| P1 | **过程可见**(streaming / view 过程卡,见 [agent-streaming.md](../roadmap/agent-streaming.md)) | 对标 Langfuse,但真相仍写回文档 | +| P1 | **Skill / 源码注入的预算与渐进披露** | 避免上下文爆炸,同时保持「源码即提示」 | +| P2 | **与外部 RAG/MCP 的工具化接入** | 补齐语料检索,但不把向量库升为权威真相 | +| P2 | **评测金样:同类任务二次 plan 应命中 kb 快路径** | 用测试锁住差异化 | +| 避免 | 再引入私有 JSON 工具协议作主路径 | 与宪法冲突 | +| 避免 | 整文件 LLM 重写工作簿 | 已在 parent 设计禁止 | + +验收提问(产品自评): + +1. 新人能否只读一份 `.mq.md` 理解 Agent 在干什么? +2. 失败后能否在 git 与 view 内完成复盘,不强制打开外部 trace? +3. 成功任务下周能否以 **跑同一技能** 的方式复用,而不是「再聊一遍」? +4. 确定步骤是否越来越多地变成普通 `##`,模型调用是否下降? + +若四问皆是——优化方向正确。 + +--- + +## 10. 结论 + +2026 年的智能体框架市场在 **图控、角色班组、厂商 hardened loop、RAG 知识** 四条线上分化;共同短板是 **真相源碎片化** 与 **成功经验难以变成可执行组织资产**。 + +Marqdo 用「代码即文档、文档即知识库」把 Agent 开发收束到 **可执行 Markdown 生命循环**: + +**书写 → 注入模型 → 执行 → 写回 →(多步)补丁演进 → 固化 → OKF 晋升 → 再命中。** + +这不是功能点堆砌,而是架构级选择。深入优化 `ext/agent` 时,应把资源砸在 **工作簿、写回、固化、知识包命中、过程可视** 上,把「文档驱动的智能体开发框架」做成可感知的产品体验——这才是相对 LangGraph / CrewAI / 厂商 SDK **不可替代** 的优越点。 + +--- + +## 11. 参考与延伸阅读 + +### 本仓 + +- [ext-agent.md](../design/ext-agent.md) — 框架总设计(否定 TOOL 薄循环) +- [ext-agent-plan.md](../design/ext-agent-plan.md) — 多步工作簿 +- [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) + +### 外部(抽样,2025–2026) + +- Langfuse: *Comparing Open-Source AI Agent Frameworks*(2026-07 更新盘点) +- LangGraph docs: Persistence(checkpointer vs store) +- Microsoft: AutoGen maintenance → Agent Framework migration +- CrewAI: Crews + Flows +- OpenAI Agents SDK / Claude Agent SDK / Google ADK 公开 README +- Google OKF SPEC v0.2(知识包形态;与 Marqdo 可执行源对照) diff --git a/doc/roadmap/ext-agent-optimize.md b/doc/roadmap/ext-agent-optimize.md new file mode 100644 index 0000000..41c14c8 --- /dev/null +++ b/doc/roadmap/ext-agent-optimize.md @@ -0,0 +1,33 @@ +# `ext/agent` 深入优化(调研驱动) + +| | | +|---|---| +| 状态 | **规划中**(以调研结论为输入) | +| 日期 | 2026-08-28 | +| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.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) | + +--- + +## 1. 优化原则(来自调研) + +1. **强化差异化,不向 LangChain 薄循环回退**(禁止隐藏 TOOL: 主路径、禁止整文件 LLM 重写工作簿)。 +2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视**。 +3. 外部 RAG/MCP 只作**工具**,不升为权威真相源。 + +自评四问见调研 §9。 + +--- + +## 2. 建议分期(摘要) + +| 波次 | 主题 | 验收线索 | +|------|------|----------| +| **A0** | 工作簿补丁 / 固化可靠性 | 金样:多轮 CONTINUE 后源码可跑;禁止整文件重写 | +| **A1** | OKF 复用飞轮(lookup / near / soft_match UX) | 二次同类 `plan` 走快路径;策展可读 | +| **A2** | 过程可见(stream + view 过程卡) | 对齐 [agent-streaming.md](agent-streaming.md);真相仍可写回 | +| **A3** | 上下文预算(源码/Skill 渐进披露) | 长 runbook 不爆窗,仍保持「源码即提示」 | +| **A4** | 可选:RAG/MCP 工具适配器 | 金样调用外置检索,权威仍是 `.mq.md` | + +细节与行业对照以调研正文为准;本文件只跟踪实现分期。