diff --git a/doc/README.md b/doc/README.md index 52843d0..f04a05c 100644 --- a/doc/README.md +++ b/doc/README.md @@ -93,6 +93,8 @@ | [research/ai-agent-sandbox.md](research/ai-agent-sandbox.md) | **AI 扩展沙盒调研**:Wasm / OS / CoW / symlink 对比与 Marqdo 分层推荐 | | [design/ext-ai-sandbox.md](design/ext-ai-sandbox.md) | **`ext/ai/sandbox` 设计锁定**:CoW · 能力表 · agent ABI(非 stdlib) | | [roadmap/ext-ai-sandbox.md](roadmap/ext-ai-sandbox.md) | **`ext/ai/sandbox` 实现里程碑** S0–S4 | +| [research/ai-agent-llm-optimize-2026-10.md](research/ai-agent-llm-optimize-2026-10.md) | **2026-10 调研**:代码即文档×OKF×沙盒下的 Agent/LLM 优化与问题分析 | +| [design/ext-ai-optimize.md](design/ext-ai-optimize.md) | **方案**:Agent/LLM 优化可行方向全集与推荐波次 O1–O5 | | [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus | | [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) | | [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) | diff --git a/doc/design/ext-ai-optimize.md b/doc/design/ext-ai-optimize.md new file mode 100644 index 0000000..80a7fd5 --- /dev/null +++ b/doc/design/ext-ai-optimize.md @@ -0,0 +1,139 @@ +# 方案:智能体 / 大模型优化方向(代码即文档 · OKF · 沙盒) + +| | | +|---|---| +| 状态 | **Proposed · 方向全集(待选型排期)** | +| 日期 | 2026-10-16 | +| 调研 | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) | +| 相关 | [ext-ai-sandbox.md](ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [okf.md](okf.md) · [engineering-knowledge.md](engineering-knowledge.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) · [ai-stack.md](../roadmap/ai-stack.md) | + +--- + +## 0. 方案立场 + +1. **强化差异化**:可执行 `.mq.md` 为权威;OKF 为复用;沙盒为证明;LLM 为探索。 +2. **不向隐藏 TOOL: 循环 / 向量权威回退。** +3. 下列方向均为**可行**;推荐波次见 §3,最终裁剪由你选型。 +4. **不改** `doc/next/*`;落地时另开 roadmap 切片。 + +--- + +## 1. 架构愿景(闭环) + +```text +目标 / 任务 + │ + ▼ +EFI / OKF lookup ──hit──► llm_free / marqdo 执行 ──► writeback + │ miss + ▼ +small-llm 路由 / 父分解 + │ + ▼ +生成或修补 .mq.md(代码即文档风格) + │ + ▼ +sandbox.open → sandbox.run(caps)→ diff + │ + ├─ 失败 → writeback error / 隔离,不 promote + └─ 成功 → 人审或策略 → commit → solidify / OKF promote + │ + ▼ + 下次 REUSE(降本) +``` + +--- + +## 2. 可行方向全集 + +每个方向标注:解决的问题(Pn)、依赖、风险、粗粒度成本。 + +### A. 沙盒 × Agent 闭环 + +| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 | +|----|------|------|--------|------|------|------| +| **A1** | `step`/`plan` 默认经 sandbox 试跑再写实树 | P1 | 生成落 upper;绿才 `commit` | sandbox | 破坏现有金样默认 | 中 | +| **A2** | Promote / solidify 强制 sandbox proof | P1 | OKF 写入前要求 proof fixture 绿 | sandbox+OKF | 过严挡复用 | 中 | +| **A3** | Sandbox profile 表(caps 宣告) | P1/P3 | GFM 表声明 net/plugin/fs | sandbox | 表方言膨胀 | 低 | +| **A4** | Guest 风格门禁(表优先、禁 json 胶水) | P5 | commit 前 lint / preflight | sandbox+parser | 误杀合法 json.parse | 中 | +| **A5** | 会话 diff → view 审阅卡 | P1/P4 | HITL 看 CoW diff | view+sandbox | UI 工时 | 中高 | +| **A6** | 多会话并行 CoW(fan-out 实验) | — | 每假设一 session | sandbox | 隔离/合并复杂 | 高 | + +### B. OKF / EKC / 技能层 + +| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 | +|----|------|------|--------|------|------|------| +| **B1** | OKF 技能元数据:适用条件 / fixtures / sandbox_profile | P2 | frontmatter + 目录约定 | okf | 与 catalog 字段冲突 | 中 | +| **B2** | Progressive disclosure(索引轻、正文按需 READ) | P2/P6 | 对齐 Anthropic Skills 层级 | agent A3 | 实现重复 | 中 | +| **B3** | Skill Lift 评测(有/无技能配对) | P4 | harness 指标 | B1 评测 | 样本少噪声大 | 中 | +| **B4** | 失败技能隔离(quarantine)+ 回归用例跟随血缘 | P1 | ForgeAgent 式 | OKF | 状态机复杂 | 中高 | +| **B5** | near-match / soft_match 产品化默认开 | P6 | 已有 roadmap | okf-near | 误复用 | 低中 | +| **B6** | EKC preflight 默认硬门槛(REUSE→ADAPT→CREATE) | P6 | step 前强制 EFI | EKC | 拖慢探索 | 中 | +| **B7** | Capability 包与 `llm_free` 资源双向链接 | P2 | catalog L3↔任务包 | EKC+OKF | 图维护 | 中 | + +### C. 大模型 / 路由 / 成本 + +| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 | +|----|------|------|--------|------|------|------| +| **C1** | 步骤级路由(lookup / patch / sandbox_run / net) | P3 | 扩展 route policy 表 | routing | 策略过拟合 | 中 | +| **C2** | 总成本计量(含推理 token 膨胀)写回文档 | P7 | usage→writeback/metrics | llm result | 噪声 | 低中 | +| **C3** | 用强模型「反思」优化 standing / policy `.mq.md`(类 GEPA) | P3/P5 | 离线优化环,产物仍是文件 | llm | 需评测集 | 高 | +| **C4** | 高频 OKF 技能蒸馏/微调小模型(编译进权重) | — | 长期研究 | 数据+算力 | 运维重;偏离「源码权威」 | 很高 | +| **C5** | Named model 绑定任务类型(fast=路由,reasoning=分解) | P3 | 已有 named handles 加深 | llm | 配置漂移 | 低 | +| **C6** | Prompt document 强制:无参 ask 必须来自 type:prompt 文件 | P5 | 硬化 005 | llm | 破坏脚本式调用 | 低 | + +### D. 代码即文档(产出质量) + +| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 | +|----|------|------|--------|------|------|------| +| **D1** | 官方「可读 Marqdo」Skill 强化(表/链接取元/禁混名) | P5 | skills/marqdo 加厚 | skill | 模型仍违规 | 低 | +| **D2** | AST/结构 lint:json.set 链、混 EN/ZH API | P5 | `marqdo lint` 或 sandbox 钩子 | parser | 误报 | 中 | +| **D3** | 工作簿补丁只允许表驱动 / 命名槽写回 | P5 | 收紧 A0 补丁面 | agent | 表达力下降 | 中 | +| **D4** | 示例库:sandbox+OKF+表风格 canonical demos | P4/P5 | examples/ | 文档 | 维护 | 低 | + +### E. 评测与产品化 + +| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 | +|----|------|------|--------|------|------|------| +| **E1** | 完成 Wave B1 harness(constitution / writeback / call_site) | P4 | 已规划 | agent | — | 中 | +| **E2** | 指标面板:ReuseRate / ProofRate / TokenCost | P4/P7 | metrics 写回或 catalog | agent | 虚荣指标 | 中 | +| **E3** | Live 金样矩阵(sandbox 开/关 × 路由后端) | P4 | CI optional | CI | flaky | 中 | +| **E4** | 教程:「只读一份 .mq.md 理解 Agent」 | — | doc/tutorial | 文档 | — | 低 | + +### F. 明确不优先 / 需单独论证 + +| ID | 方向 | 理由 | +|----|------|------| +| **F1** | 第二套 Agent Framework(Python/TS 对象图权威) | 违宪 | +| **F2** | 向量库升为记忆权威 | 违宪;可作证据工具 | +| **F3** | 默认通用 shell Agent | 与 Marqdo-only 沙盒战略冲突 | +| **F4** | 整库 `ext/web` 进默认沙盒 | 已否决 | +| **F5** | 人人 microVM 本地默认 | DX 过重;留给 hosted | + +--- + +## 3. 推荐落地波次(默认建议,可改) + +| 波次 | 方向组合 | 为何先做 | +|------|----------|----------| +| **O1** | A1 轻量(opt-in `sandbox=True`)+ A3 + D1 + D4 | 立刻接上刚落地的沙盒,风险可控 | +| **O2** | A2 + B1 + B3 + E1 | 验证→晋升→可度量 Skill Lift | +| **O3** | C1 + C2 + B6 | 降本与 EFI 硬门槛 | +| **O4** | A4 + D2 + A5 | 质量门禁与人审 | +| **O5** | B4 + C3 | 失败隔离与离线提示优化 | +| **O∞** | C4 / A6 | 研究项,单独立项 | + +--- + +## 4. 验收原则(任一波次) + +- 金样:有/无沙盒、有/无 OKF hit、路由后端切换。 +- 指标:至少报告 ReuseRate 或 TokenCost 之一相对基线变化。 +- 文档:`.mq.md` 示例仍可读为 Markdown(表/链接取元,少 json 胶水)。 +- 红线:不改 `doc/next/*`;ext 不调 `host_*`。 + +--- + +## 5. 下一步 + +请从 §2 方向方向中圈选优先级(或确认 §3 默认 O1→O2)。确认后另开 `doc/roadmap/ext-ai-optimize.md` 做切片实现,**仍不改** `doc/next/*`。 diff --git a/doc/research/ai-agent-llm-optimize-2026-10.md b/doc/research/ai-agent-llm-optimize-2026-10.md new file mode 100644 index 0000000..c9584f1 --- /dev/null +++ b/doc/research/ai-agent-llm-optimize-2026-10.md @@ -0,0 +1,136 @@ +# 调研:代码即文档 × OKF × 沙盒 下的智能体 / 大模型优化(2026-10) + +| | | +|---|---| +| 状态 | **调研 + 问题分析 · 供方案 [ext-ai-optimize.md](../design/ext-ai-optimize.md) 参考** | +| 日期 | 2026-10-16 | +| 前置 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) · [agent-framework-2026-09.md](agent-framework-2026-09.md) · [ai-agent-sandbox.md](ai-agent-sandbox.md) · [okf-and-marqdo.md](okf-and-marqdo.md) | +| 本仓能力 | [ext-agent.md](../design/ext-agent.md) · [okf.md](../design/okf.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) · [ai-stack.md](../roadmap/ai-stack.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) | +| 外部抽样 | Anthropic Agent Skills · SoK Agentic Skills (arXiv 2602.20867) · ForgeAgent · ACES / Skill Lift · Switchcraft 路由 · DSPy/GEPA ·「工作流编译进权重」· MalSkillBench | + +--- + +## 0. 一句话 + +业界正把 Agent 优化从「更好的 chat loop」转向 **可验证、可复用、可隔离执行的技能层**;Marqdo 已具备 **可执行 Markdown(代码即文档)+ OKF/EKC 复用 + CoW 沙盒** 三件套,优化目标应是把这三件套焊成闭环:**试跑 → 证据 → 晋升 → 零/少 LLM 复用**,而不是追平 LangChain 功能清单。 + +--- + +## 1. 调研方法 + +| 动作 | 说明 | +|------|------| +| 扫业界技能层 | Anthropic Skills(渐进披露 `SKILL.md`);SoK Agentic Skills 生命周期;ForgeAgent「能力铸造」;ACES Skill Lift | +| 扫成本/路由 | Switchcraft 工具调用路由;DSPy+GEPA 提示优化;工作流编译进小模型权重 | +| 扫安全 | MalSkillBench 运行时验证恶意技能;沙盒粒度讨论(per-skill / per-session) | +| 对照本仓 | A0–A4 / Wave B 已落地;沙盒 S0–S4 已落地;OKF + EKC + adaptive routing 现状 | + +**不修改** `doc/next/*`(手写真相源);本文件只进 `doc/research/`。 + +--- + +## 2. 业界态势(与 Marqdo 相关的收敛点) + +### 2.1 技能层取代「纯工具调用叙事」 + +| 来源 | 要点 | 对 Marqdo | +|------|------|-----------| +| Anthropic Agent Skills | 目录 + `SKILL.md`;元数据预载、正文按需;脚本可执行 | 形态近 OKF 任务包,但 Marqdo 技能 **本身可跑** | +| SoK Agentic Skills | 发现→练习→蒸馏→存储→组合→评测→更新;代码技能需沙盒 | 生命周期与 OKF promote / sandbox.run 对齐 | +| ForgeAgent | 生成能力 → 沙盒证明 → 信任复用;失败进回归隔离 | **验证后晋升** 正是 solidify / `llm_free` 缺的硬闸 | +| ACES | 有/无技能配对试验 → Skill Lift | 可作 Marqdo 评测 harness 指标 | + +### 2.2 成本:路由 + 编译 + 小模型 + +| 来源 | 要点 | 对 Marqdo | +|------|------|-----------| +| Switchcraft | 工具调用场景路由到最便宜仍正确的模型;报道大幅降本 | 已有 `marqdo \| small-llm \| llm \| auto`;可加 **工具步/试跑步** 细分 | +| DSPy / GEPA | 用反馈改写指令,小模型追上大模型 | 优化对象应是 **`.mq.md` 提示文档 / standing / 路由策略文件**,不是黑盒字符串 | +| 工作流编译进权重 | 程序化流程进小模型权重,上下文常数级 | 长期对应「高频 OKF 技能 → 专用小模型」;短期优先 **llm_free 源码路径** | + +### 2.3 安全:技能不可信 + 沙盒必验 + +恶意技能基准与 SoK 均强调:**技能说明与代码默认不可信**,须运行时隔离。Marqdo 新沙盒(默认拒 plugin/net/exec)正好是技能晋升前的证明场。 + +--- + +## 3. Marqdo 已有资产(优化起点) + +| 资产 | 现状 | 优化杠杆 | +|------|------|----------| +| 代码即文档 | `.mq.md` = 程序 = 提示工作面;GFM 表 / 链接取元 | 减少 json 胶水;让模型「看见」结构 | +| 写回 | `marqdo-out` 槽;step 默认写回 | 晋升证据、失败避坑 | +| OKF / agent-kb | 命中 / near / promote / solidify / `llm_free` | 复用率、降本主轴 | +| EKC / EFI | L0–L4 catalog;preflight REUSE/ADAPT/CREATE | 生成前先查工程知识 | +| Adaptive routing | marqdo / small-llm / llm / auto + policy 文件 | 再细分 sandbox 试跑 vs 开放推理 | +| Sandbox | CoW + capped `run`;`ext/ai/sandbox` | **试跑闸门**;未 commit 不污染仓库 | +| MCP / corpus | 证据工具,`authority=workbook` | 保持不升权威 | + +--- + +## 4. 问题分析(差距,不是功能羡慕) + +### P1 — 试跑与晋升未焊死 + +沙盒已能 CoW 试跑,但 **`agent.step` / `plan` 默认仍可直接改真实树**;OKF `llm_free` 晋升不强制「沙盒金样绿」。 +→ 风险:未验证技能进入复用池(业界 ForgeAgent / MalSkillBench 已证明此问题)。 + +### P2 — 技能形态双轨 + +Anthropic Skills = 文件夹 + 渐进披露;Marqdo = 可执行 `.mq.md` + OKF 类型。 +→ 机会:用 **OKF frontmatter + 可执行体** 统一,不必引入第二套 SKILL.md 权威;缺的是 **披露层级与验证元数据**(适用条件、fixture、sandbox profile)。 + +### P3 — 路由粒度偏粗 + +现有路由偏「整任务后端」;未区分:查 OKF / 写补丁 / 沙盒 `run` / 对外 HTTP。 +→ Switchcraft 启示:按 **步骤类型** 选模型,且「便宜模型推理 token 爆炸」要计入总成本。 + +### P4 — 评测未锁差异化 + +Wave B1 仍 Active:缺稳定 **Skill Lift / 沙盒证明率 / llm_free 命中率 / 文档可读性** 指标。 +→ 没有指标,优化会滑回「多调几次模型」。 + +### P5 — 代码即文档在 Agent 产出侧仍易腐化 + +模型仍可能吐 `json.set` 链、混用 EN/ZH API、跳过表结构。 +→ 沙盒可跑通语法,但 **风格门禁**(lint / preflight)未默认卡在 commit 前。 + +### P6 — 上下文与 EKC 未默认进每步 + +EFI / catalog 能力在,但 step 默认上下文仍可能偏源码切片,缺少「先 REUSE」硬门槛。 + +### P7 — LLM 表面与 Agent 成本账未统一 + +`llm.ask` / `stream` / usage 已有;Agent 侧缺 **按会话/技能的成本仪表盘** 写回文档(可 git 审)。 + +--- + +## 5. 优化目标函数(建议) + +在固定任务集上最大化: + +\[ +\begin{align*} +& \text{ReuseRate}(\text{OKF hit} + \text{llm\_free}) \\ +&+ \text{SandboxProofRate}(\text{试跑绿再 commit/promote}) \\ +&- \lambda_1 \cdot \text{TokenCost} - \lambda_2 \cdot \text{HostMutationsWithoutCommit} +\end{align*} +\] + +约束:权威真相仍是 `.mq.md`;不引入隐藏 TOOL 主循环;不改 `doc/next/*`。 + +--- + +## 6. 外部资料索引(抽样) + +| 类型 | 链接 | +|------|------| +| Skills | [Anthropic engineering: Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) · [Claude Code skills](https://code.claude.com/docs/en/skills) · [agentskills / anthropics/skills](https://github.com/anthropics/skills) | +| 论文 | [SoK: Agentic Skills](https://arxiv.org/html/2602.20867) · [Skill Issue (repo SKILL 优化)](https://arxiv.org/html/2609.12742v1) · [ACES Skill Lift](https://arxiv.org/html/2608.20614) · [MalSkillBench](https://arxiv.org/html/2606.07131v3) · [Compiling workflows into weights](https://arxiv.org/html/2605.22502) | +| 开源/产品 | [ForgeAgent](https://github.com/Yashasm18/ForgeAgent) · [DSPy GEPA](https://dspy.ai/current/getting-started/gepa-optimization/) · [Switchcraft](https://www.microsoft.com/en-us/research/publication/switchcraft-ai-model-router-for-agentic-tool-calling/) | + +--- + +## 7. 结语 + +Marqdo 不缺「再一个 Agent SDK」;缺的是把 **文档真相、知识晋升、沙盒证明、模型路由** 收成可度量闭环。下一篇方案文档按问题编号给出可选方向与推荐波次,**不预设唯一银弹**。 diff --git a/doc/research/ai-agent-sandbox.md b/doc/research/ai-agent-sandbox.md index e6d9a79..0413b06 100644 --- a/doc/research/ai-agent-sandbox.md +++ b/doc/research/ai-agent-sandbox.md @@ -6,7 +6,7 @@ | 日期 | 2026-10-16 | | 范围 | 浏览器 WASM / WASI、OS 进程沙盒、容器 / microVM、CoW 叠加工作区、符号链接暂存方案;对照 Marqdo AI 栈 | | 相关设计 | **[ext-ai-sandbox.md](../design/ext-ai-sandbox.md)** · **[roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md)** · [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md) · [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [adr/0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-modules.md](../design/stdlib-modules.md) | -| 姊妹调研 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) | +| 姊妹调研 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) · [ai-agent-llm-optimize-2026-10.md](ai-agent-llm-optimize-2026-10.md) · [ext-ai-optimize.md](../design/ext-ai-optimize.md) | ---