From a9ee858f53295d8dcd406e8d145079dff2d7e089 Mon Sep 17 00:00:00 2001 From: cflmy Date: Thu, 24 Sep 2026 13:28:50 +0800 Subject: [PATCH] feat(agent): Skill Compilation + Adaptive Routing (v2/P4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Episode → maybe_learn → llm_free skills, plus abstract router backends (marqdo/small-llm/jev?/llm/auto) via plugins/agent; no core host changes. Co-authored-by: Cursor --- .cursor/skills/marqdo/SKILL.md | 6 +- doc/design/ext-agent.md | 13 + doc/next/003.md | 2626 +++++++++++++++++++++++++++++ doc/next/004.md | 541 ++++++ doc/roadmap/ext-agent-optimize.md | 6 +- ext/ai/agent.mq.md | 304 +++- ext/ai/智能体.mq.md | 111 +- plugins/agent/src/lib.rs | 108 +- plugins/agent/src/memory.rs | 1135 +++++++++++++ plugins/agent/src/route.rs | 755 +++++++++ scripts/agent-harness.sh | 2 + tests/ext/agent-p4-route.mq.md | 60 + tests/ext/agent-v2-learn.mq.md | 56 + tests/gold.rs | 69 + 14 files changed, 5785 insertions(+), 7 deletions(-) create mode 100644 doc/next/003.md create mode 100644 doc/next/004.md create mode 100644 plugins/agent/src/memory.rs create mode 100644 plugins/agent/src/route.rs create mode 100644 tests/ext/agent-p4-route.mq.md create mode 100644 tests/ext/agent-v2-learn.mq.md diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index 3674754..e07eb42 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -217,10 +217,12 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas 1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag. 2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program. 3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only. +4. **Skill Compilation (v2)** — successful runs become `.mq.md` episodes; after enough evidence, `maybe_learn` compiles an executable skill (`llm_free`). Prefer `## run` over bare `## plan` when you want learning. +5. **Adaptive Routing (P4)** — router is abstract (`marqdo` / `small-llm` / optional `jev` / `llm` / `auto`); Jev is never required. Policy Compilation writes `policies/router.mq.md`. -APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import). +APIs: `# agent` / `# 智能体` → `## run` / `## route` / `## step` / `## plan` (+ `resolve` / `record_episode` / `maybe_learn` / `compile` / `compile_policy` / `metrics`). Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import). -Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored). +Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) · v2: [doc/next/003.md](../../doc/next/003.md) · P4: [doc/next/004.md](../../doc/next/004.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored). ## Official extension: `ext/web` (dynamic sites) diff --git a/doc/design/ext-agent.md b/doc/design/ext-agent.md index b4bcc5c..79503c2 100644 --- a/doc/design/ext-agent.md +++ b/doc/design/ext-agent.md @@ -180,11 +180,24 @@ ext/ | 中文 | 英文 | 角色 | |------|------|------| | `# 智能体` | `# agent` | 构造:`大模型`/`model`,`工具`/`tools`,可选 `站立提示`/`standing` | +| `## 运行` | `## run` | **v2 主入口**:Adaptive `route` → execute → record episode → maybe_learn(技能 + 策略) | | `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;返回结构化 map;**默认自动写回**(`写回=` / `writeback=` 可关) | | `## 多步` | `## plan` | 建/续工作簿 → subtask 跑文件 → 修订循环 → 汇总(见 [ext-agent-plan.md](ext-agent-plan.md)) | +| `## 解析` | `## resolve` | 技能解析:exact → alias → canonical → near | +| `## 路由` | `## route` | **P4 Adaptive Routing**:`marqdo` \| `small-llm` \| `jev` \| `llm` \| `auto`(Jev 可选,非必选) | +| `## 应用路由` | `## route_apply` | 将小模型/大模型路由回复(`SKILL:` / `EXPLORE`)落到 kb 技能 | +| `## 编译策略` | `## compile_policy` | Policy Compilation → `policies/router.mq.md` | +| `## 记录情景` | `## record_episode` | 每次执行沉淀为 `.mq.md` episode(`.marqdo/agent-memory/`) | +| `## 尝试学习` | `## maybe_learn` | 情景足够时归纳 → 合成 → 编译技能,并尝试编译策略 | +| `## 编译` | `## compile` | 候选技能 → 版本化 `skills//vN.mq.md` + 可选 OKF promote | +| `## 指标` | `## metrics` | Reasoning amortization(`avg_llm_calls` / `compiled_runs`) | | `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 | | `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 | +**Skill Compilation(v2)**:Agent 的记忆不是向量袋,而是可执行 `.mq.md`。路径:`episodes/` → `experiences/` → `candidates/` → `skills/vN.mq.md` → OKF `agent-kb`(`llm_free`)。 + +**Adaptive Routing(P4,原「Jev Router」更名)**:Router 是抽象能力,backend = `marqdo`(已编译 `policies/router.mq.md`)/ `small-llm`(用户自备小参数模型)/ `jev`(可选)/ `llm` / `auto` 级联。**不依赖 Jev**。热路径在 **`plugins/agent`**(`route.rs`);**禁止**向 `src/host/` 加领域原语。设计:[doc/next/003.md](../next/003.md) · [doc/next/004.md](../next/004.md)。 + 构造参数(v1): | 参数 | 说明 | diff --git a/doc/next/003.md b/doc/next/003.md new file mode 100644 index 0000000..66865c6 --- /dev/null +++ b/doc/next/003.md @@ -0,0 +1,2626 @@ +可以。基于你现在的 `ext/ai/agent` 实现,我建议不要把它继续做成一个“带缓存的 LLM Agent”,而是正式把它定义成: + +> **一个能够把执行经验逐渐编译成 `.mq.md` 可执行知识/技能的自学习智能体运行时。** + +你现在的框架其实已经有不少基础:`step` 负责单步 LLM/tool execution,`plan` 负责多步执行,并且已经有 `exact → alias → canonical → near` 的复用路径、`agent-kb`、`explore_n`、`improve_every`、`llm_free` 和执行事件记录。 + +下面我给你一套可以直接作为 **Marqdo Agent Framework v2 设计文档** 的方案。 + +--- + +# Marqdo Agent Framework v2 + +## 1. 核心目标 + +整个 Agent 不应该只是: + +```text +Task + ↓ +LLM + ↓ +Tool + ↓ +Answer +``` + +而应该变成: + +```text + ┌─────────────────────┐ + │ User Task │ + └──────────┬──────────┘ + ↓ + ┌───────────────┐ + │ Skill Resolver│ + └───────┬───────┘ + │ + ┌───────────────┼────────────────┐ + ↓ ↓ ↓ + Exact Skill Similar Skill Unknown + │ │ │ + ↓ ↓ ↓ + MQ Execution Adaptation Exploration + │ │ │ + └───────────────┼────────────────┘ + ↓ + Verification + ↓ + Result + ↓ + Episode Trace + ↓ + Experience Store + ↓ + Pattern / Skill Mining + ↓ + Candidate Skill + ↓ + Validation + ↓ + Skill Compile + ↓ + Executable .mq.md + │ + └───────────────→ 下一次调用 +``` + +因此 Agent 有两个完全不同的阶段: + +### Online + +解决当前任务: + +```text +Resolve → Execute → Verify → Return +``` + +### Offline / Background + +从历史经验中学习: + +```text +Collect → Cluster → Generalize → Validate → Compile +``` + +这是整个设计最重要的结构。 + +--- + +# 2. Agent 的四种“记忆” + +我建议不要把所有东西都叫 Memory。 + +实际上应该有四层。 + +## 2.1 Episode Memory + +记录: + +> “这一次具体发生了什么?” + +例如: + +```text +episode/ + 20260924-001.mq.md + 20260924-002.mq.md + 20260924-003.mq.md +``` + +它是**情景记忆**。 + +记录: + +```yaml +task +context +decision +actions +tool_calls +observations +errors +result +verification +cost +``` + +它不需要漂亮,也不需要高度抽象。 + +--- + +# 3. Experience Memory + +Episode 多了以后,系统开始发现: + +```text +Episode 1 +Episode 2 +Episode 3 +Episode 4 + ↓ +这些任务其实属于同一个模式 +``` + +于是形成: + +```text +experience/.mq.md +``` + +例如: + +```text +experience/ + extract-json-from-response.mq.md + search-local-corpus.mq.md + repair-invalid-json.mq.md +``` + +Experience 是: + +> 多次执行中发现的稳定模式。 + +--- + +# 4. Skill Memory + +Experience 进一步经过验证以后,变成: + +```text +skills/.mq.md +``` + +这个文件已经不是“记录”。 + +它是: + +> **可以直接执行的程序。** + +例如: + +```markdown +--- +type: skill +status: compiled +llm_free: true + +success_rate: 0.96 +confidence: 0.98 +evidence: 31 + +input: + - query + +output: + - result + +fallback: llm +--- + +## main + +1. `query` + > corpus_search query=`query` + +2. `result` + *result* +``` + +这才是 Marqdo 最特别的地方: + +> **Agent 的学习结果最终不是 embedding,而是 `.mq.md`。** + +--- + +# 5. Policy Memory + +这是进一步优化。 + +某些技能虽然不能完全 deterministic,但可以让一个小模型决定: + +```text +if task.kind == "json": + use json-repair +elif task.kind == "search": + use corpus-search +else: + use llm +``` + +于是形成: + +```text +policy/ + router.mq.md + json-router.mq.md +``` + +所以最终可以形成: + +```text +Episode + ↓ +Experience + ↓ +Skill + ↓ +Policy +``` + +--- + +# 6. Agent 的核心状态机 + +我建议 Agent 明确定义以下状态: + +```text +NEW + │ + ↓ +RESOLVE + │ + ├── EXACT HIT ────────→ EXECUTE + │ + ├── NEAR HIT ─────────→ ADAPT + │ + └── MISS ─────────────→ EXPLORE + │ + ↓ + EXECUTE + │ + ↓ + VERIFY + │ + ┌─────────┴─────────┐ + ↓ ↓ + FAIL PASS + │ │ + ↓ ↓ + REPAIR RECORD + │ │ + └───────→ ↓ + EPISODE + │ + enough evidence? + │ │ + no yes + │ │ + ↓ ↓ + DONE LEARN + │ + ↓ + CANDIDATE + │ + ↓ + VALIDATE + / \ + FAIL PASS + │ │ + ↓ ↓ + REJECT COMPILE + │ + ↓ + SKILL +``` + +这个状态机应该成为 `plan()` 的真正语义。 + +现在的 `plan()` 已经在做其中的一部分,例如 reuse、explore、await、revise 和 promote。 + +--- + +# 7. 顶层 Agent API + +我建议把 API 从现在的: + +```text +agent.plan(goal) +``` + +逐渐扩展成: + +```text +agent.run(task) +agent.learn(task) +agent.compile(skill) +agent.verify(skill) +agent.inspect(task) +agent.forget(skill) +``` + +核心接口: + +```text +## run + + `task` + + `context`=None + + `mode`=auto + + `budget`=None + + `learn`=True + + `verify`=True +``` + +语义: + +```text +run() + ↓ +resolve() + ↓ +execute() + ↓ +verify() + ↓ +record_episode() + ↓ +maybe_learn() +``` + +--- + +# 8. `agent.run` + +这是用户唯一需要经常调用的接口。 + +```text +*> agent.run task=`task`* +``` + +返回: + +```json +{ + "status": "ok", + "result": "...", + + "execution": { + "mode": "compiled", + "skill": "json-repair", + "llm_calls": 0, + "tool_calls": 1 + }, + + "learning": { + "episode": "...", + "skill_updated": false + } +} +``` + +或者第一次: + +```json +{ + "status": "ok", + "result": "...", + + "execution": { + "mode": "explore", + "llm_calls": 5 + }, + + "learning": { + "episode": "episode-001", + "candidate": "json-repair" + } +} +``` + +--- + +# 9. `agent.step` + +你现在的 `step` 应该保留。 + +它是 Agent 最基础的 primitive。 + +当前 `step` 已经承担: + +```text +context assembly +→ LLM +→ READ +→ CALL +→ history +→ writeback +``` + +这正适合作为底层执行单元。 + +建议正式定义: + +```text +## step + + `task` + + `context`=None + + `skill`=None + + `tools`=None + + `model`=auto + + `budget`=None + + `mode`=reason +``` + +其中: + +```text +mode = + deterministic + rule + small_model + llm + explore +``` + +--- + +# 10. `agent.resolve` + +这是新版 Agent 最重要的函数之一。 + +```text +## resolve + + `task` + + `kb_dir` + + `near_match`=True + + `threshold`=0.78 +``` + +返回: + +```json +{ + "mode": "near", + "skill": "json-repair", + "resource": ".marqdo/agent-kb/skills/json-repair.mq.md", + "score": 0.91, + "confidence": 0.97 +} +``` + +Resolver 应该按: + +```text +1. exact +2. alias +3. canonical +4. near +5. semantic +6. policy +7. unknown +``` + +寻找技能。 + +你现在已经实现了: + +```text +exact +alias +canonical +near +soft +``` + +所以这一部分可以直接演进,而不是重写。 + +--- + +# 11. `agent.execute` + +Resolver 决定怎么执行之后: + +```text +## execute + + `task` + + `resolution` +``` + +例如: + +```text +resolution.mode == compiled +``` + +直接: + +```text +await_workbook(skill) +``` + +而不是: + +```text +LLM → 再想一遍 +``` + +如果: + +```text +resolution.mode == near +``` + +则: + +```text +skill + ↓ +parameter adaptation + ↓ +execute + ↓ +verify +``` + +如果: + +```text +resolution.mode == unknown +``` + +则: + +```text +LLM exploration +``` + +--- + +# 12. Cognitive Cost Ladder + +我非常建议把它正式加入框架。 + +```text +L0 deterministic + ↓ +L1 Marqdo rule / branch + ↓ +L2 small decision model + ↓ +L3 small LLM + ↓ +L4 full LLM + ↓ +L5 exploration / multi-step reasoning +``` + +每一个任务都应该有: + +```text +cost_level +``` + +例如: + +```yaml +cost_level: 0 +llm_calls: 0 +``` + +或者: + +```yaml +cost_level: 4 +llm_calls: 7 +``` + +学习的本质就是: + +```text +L5 + ↓ +L4 + ↓ +L3 + ↓ +L2 + ↓ +L1 + ↓ +L0 +``` + +这会成为 Marqdo Agent 非常漂亮的研究指标。 + +--- + +# 13. `agent.verify` + +不能: + +```text +成功一次 +→ 自动成为 skill +``` + +否则很容易错误泛化。 + +所以必须有: + +```text +## verify + + `task` + + `result` + + `skill`=None + + `evidence`=None +``` + +验证包括: + +### 13.1 Execution verification + +```text +有没有报错? +``` + +### 13.2 Structural verification + +```text +输出格式是否正确? +``` + +### 13.3 Semantic verification + +```text +结果是否真正解决 task? +``` + +### 13.4 Regression verification + +```text +过去的任务还能不能通过? +``` + +--- + +# 14. Skill 学习不能简单使用“3 次” + +你之前提出: + +> 三次调用之后自动总结。 + +我建议语义上改成: + +> **三次触发 Candidate Learning,而不是三次直接成为 Skill。** + +也就是: + +```text +1 execution + ↓ +episode + +2 execution + ↓ +episode + +3 execution + ↓ +LEARNING TRIGGER + ↓ +candidate skill +``` + +但是: + +```text +candidate + ↓ +historical replay + ↓ +held-out test + ↓ +verification +``` + +成功以后才: + +```text +compiled +``` + +--- + +# 15. `agent.record_episode` + +每次执行都应该记录。 + +```text +## record_episode + + `task` + + `context` + + `actions` + + `observations` + + `result` + + `verification` + + `metrics` +``` + +生成: + +```text +.marqdo/agent-memory/ + episodes/ + 2026/ + 09/ + episode-0001.mq.md + episode-0002.mq.md +``` + +推荐格式: + +```markdown +--- +type: episode +id: episode-0001 +task_hash: ... +timestamp: ... +status: success + +skill: none +mode: explore + +llm_calls: 5 +tool_calls: 2 +tokens: 4210 +latency_ms: 3820 +--- + +# Task + +... + +# Context + +... + +# Decisions + +... + +# Actions + +... + +# Observations + +... + +# Result + +... + +# Verification + +status: passed + +# Errors + +none +``` + +--- + +# 16. `agent.cluster_episodes` + +Episode 太多以后不能每次全量交给 LLM。 + +因此: + +```text +## cluster_episodes + + `episodes` + + `threshold`=0.82 +``` + +目标: + +```text +episode 1 ─┐ +episode 2 ─┤ +episode 3 ─┤→ cluster A +episode 4 ─┘ + +episode 5 ─┐ +episode 6 ─┤→ cluster B +episode 7 ─┘ +``` + +可以先使用: + +```text +canonicalized task ++ +tool sequence ++ +input/output schema ++ +success pattern +``` + +做廉价聚类。 + +不要一开始就让大模型处理所有历史。 + +--- + +# 17. `agent.extract_pattern` + +从 cluster 中提取共同结构: + +```text +## extract_pattern + + `episodes` +``` + +输入: + +```text +A: + parse + validate + repair + return + +B: + parse + validate + repair + return + +C: + parse + validate + repair + return +``` + +输出: + +```text +Pattern: + +1. Parse +2. Validate +3. Repair if invalid +4. Return +``` + +同时识别: + +```text +invariants +variables +exceptions +preconditions +postconditions +``` + +--- + +# 18. `agent.generalize` + +这个函数非常重要。 + +```text +## generalize + + `pattern` + + `episodes` +``` + +例如: + +三个任务: + +```text +修复 JSON +修复 YAML +修复 TOML +``` + +可能共同形成: + +```text +parse structured data +→ validate +→ locate syntax error +→ repair +→ validate again +``` + +但是: + +```text +JSON/YAML/TOML +``` + +应该成为: + +```text +format +``` + +而不是写死。 + +最终: + +```yaml +input: + format + text + +procedure: + parse(format) + validate() + repair() + validate() +``` + +这才叫 **Generalization**。 + +--- + +# 19. `agent.synthesize_skill` + +然后: + +```text +## synthesize_skill + + `pattern` + + `episodes` +``` + +生成: + +```text +candidate/.mq.md +``` + +例如: + +```markdown +--- +type: skill +status: candidate + +evidence: 7 +confidence: 0.83 +--- + +## inputs + +- text +- format + +## procedure + +1. parse +2. validate +3. repair +4. validate + +## fallback + +CALL:llm +``` + +注意: + +> Candidate 不是正式 Skill。 + +--- + +# 20. `agent.validate_skill` + +然后: + +```text +## validate_skill + + `skill` + + `episodes` + + `test_cases` +``` + +执行: + +```text +candidate + ↓ +historical tests + ↓ +held-out tests + ↓ +edge cases +``` + +得到: + +```json +{ + "passed": true, + "success_rate": 0.96, + "regression_rate": 1.0, + "confidence": 0.94 +} +``` + +--- + +# 21. 为什么一定需要 Held-out Test? + +否则: + +```text +Episode A +Episode B +Episode C + +→ 从 A/B/C 总结 Skill + +→ 再用 A/B/C 测试 +``` + +这会产生: + +> 训练数据泄漏。 + +所以应该: + +```text +A B C D E F G +│ │ │ │ │ │ │ +├─┴─┴── training +│ +└────── validation +``` + +例如: + +```text +5 个 episode +→ 3 个学习 +→ 2 个测试 +``` + +当数据不足时: + +```text +candidate +``` + +而不是: + +```text +compiled +``` + +--- + +# 22. `agent.compile` + +验证成功: + +```text +## compile + + `candidate` + + `validation` +``` + +生成: + +```text +skills/.mq.md +``` + +并修改: + +```yaml +status: compiled +llm_free: true +``` + +这时候才允许: + +```text +Resolver + ↓ +Skill + ↓ +await_workbook +``` + +而无需 parent LLM。 + +你当前系统已经存在这个思想:命中 `llm_free` skill 后直接执行 workbook,而不是再次调用 parent LLM。 + +所以 v2 实际上是在把现有的 `llm_free` 从一个优化选项提升成: + +> **编译后的技能执行模式。** + +--- + +# 23. `agent.promote` + +建议把: + +```text +promote +``` + +明确分成: + +```text +candidate +experience +validated +compiled +deprecated +``` + +状态: + +```text +candidate + ↓ +validated + ↓ +compiled + ↓ +stable +``` + +失败: + +```text +candidate + ↓ +rejected +``` + +原 skill 变差: + +```text +stable + ↓ +degraded + ↓ +rollback +``` + +--- + +# 24. Skill Versioning + +这是非常重要但容易被忽略的。 + +不要直接覆盖: + +```text +json-repair.mq.md +``` + +而应该: + +```text +skills/ + json-repair/ + v1.mq.md + v2.mq.md + manifest.mq.md +``` + +manifest: + +```yaml +name: json-repair +version: 2 +status: stable + +success_rate: 0.97 +previous: 1 + +created_from: + - episode-001 + - episode-002 + - episode-003 +``` + +这样才能 rollback。 + +--- + +# 25. `agent.rollback` + +```text +## rollback + + `skill` + + `version` +``` + +例如: + +```text +v3 + ↓ +regression + ↓ +rollback + ↓ +v2 +``` + +这是 Agent 自动学习系统必须有的安全阀。 + +--- + +# 26. `agent.observe` + +所有执行都应该产生统一 Event。 + +你现在的 `plan` 已经记录: + +```text +decision +round +done +tool events +``` + +并支持 `stream / trace / echo`。 + +建议升级成统一事件: + +```json +{ + "type": "decision", + "timestamp": "...", + "run_id": "...", + "phase": "resolve", + "decision": "REUSE", + "skill": "json-repair" +} +``` + +事件类型: + +```text +run_start +resolve +decision +llm_start +llm_end +tool_start +tool_end +skill_start +skill_end +verify +episode_record +learning_trigger +candidate_created +validation +compile +promotion +rollback +run_end +``` + +--- + +# 27. `agent.trace` + +最终: + +```text +trace +``` + +应该成为完整的 Agent execution graph。 + +例如: + +```text +run +│ +├── resolve +│ └── near skill=json-repair +│ +├── adapt +│ +├── execute +│ ├── parse +│ ├── validate +│ └── repair +│ +├── verify +│ +└── record_episode +``` + +这样你的 UI 就可以直接展示 Agent 是怎么“学会”的。 + +--- + +# 28. `agent.learn` + +最后把整个学习流程封装: + +```text +## learn + + `episode` + + `threshold`=3 +``` + +内部: + +```text +record_episode + ↓ +cluster + ↓ +pattern + ↓ +generalize + ↓ +synthesize + ↓ +validate + ↓ +compile +``` + +也就是: + +```text +learn() +``` + +不是一个 LLM prompt。 + +它应该是一个完整的 **Learning Pipeline**。 + +--- + +# 29. `agent.maybe_learn` + +`run()` 不应该每次都学习。 + +因此: + +```text +## maybe_learn + + `task` + + `episode` +``` + +判断: + +```text +是否存在类似任务? +是否达到 evidence threshold? +是否出现稳定 tool sequence? +是否成功率足够? +是否值得编译? +``` + +例如: + +```text +episode_count >= 3 +AND +similarity >= 0.85 +AND +success_rate >= 0.90 +``` + +才触发。 + +--- + +# 30. `improve_every` 的重新定义 + +你现在已经有: + +```text +improve_every=3 +``` + +当前语义更接近: + +> 命中一定次数之后进行改进。 + + + +我建议升级成: + +```yaml +learning: + trigger_every: 3 + validation_min: 3 + confidence_min: 0.90 + success_rate_min: 0.92 +``` + +然后: + +```text +trigger_every +``` + +只代表: + +> 什么时候重新检查技能。 + +而不是: + +> 什么时候自动修改技能。 + +--- + +# 31. `explore_n` 重新定义 + +你当前: + +```text +explore_n=3 +``` + +会在任务文件不足时强制探索不同 variant。 + +这个设计其实非常好,但应该明确: + +```text +explore_n = exploration budget +``` + +而不是简单: + +```text +没有 skill → 多跑三次 +``` + +建议: + +```text +exploration strategy: + variant A + variant B + variant C +``` + +比如: + +```text +A: tool-first +B: code-first +C: LLM-first +``` + +然后比较: + +```text +success +latency +tokens +tool calls +robustness +``` + +最终选择。 + +--- + +# 32. Agent 的 Exploration + +我甚至建议单独增加: + +```text +## explore + + `task` + + `n`=3 + + `strategies`=None +``` + +输出: + +```json +{ + "candidates": [ + { + "strategy": "tool-first", + "success": true, + "cost": 2 + }, + { + "strategy": "llm-first", + "success": true, + "cost": 8 + }, + { + "strategy": "code-first", + "success": true, + "cost": 1 + } + ] +} +``` + +然后: + +```text +select_strategy() +``` + +选择未来的执行路径。 + +--- + +# 33. `agent.select_strategy` + +```text +## select_strategy + + `candidates` +``` + +不是简单按照: + +```text +success +``` + +而是: + +```text +utility = + correctness + - λ * token_cost + - μ * latency + - ν * tool_cost +``` + +例如: + +```text +A: +success = 0.96 +tokens = 8000 + +B: +success = 0.94 +tokens = 1000 + +C: +success = 0.99 +tokens = 3000 +``` + +系统可以保存: + +```text +strategy profile +``` + +而不是每次重新思考。 + +--- + +# 34. 这就引出你之前说的 Jev + +你之前提到: + +> “Jev 决策模型” + +我认为它非常适合放在这里。 + +架构变成: + +```text +Task + ↓ +Jev Router + ↓ +┌──────────────┬──────────────┬──────────────┐ +│ deterministic│ small model │ large LLM │ +└──────────────┴──────────────┴──────────────┘ +``` + +Jev 不负责解决问题。 + +它只负责: + +> **决定应该用什么成本解决问题。** + +这是非常关键的职责分离。 + +--- + +# 35. `agent.route` + +```text +## route + + `task` + + `skills` + + `policy` +``` + +输出: + +```json +{ + "mode": "skill", + "skill": "json-repair", + "confidence": 0.96 +} +``` + +或者: + +```json +{ + "mode": "small_model", + "model": "jev-small", + "confidence": 0.71 +} +``` + +或者: + +```json +{ + "mode": "llm", + "model": "large", + "reason": "unknown task" +} +``` + +--- + +# 36. Skill 的 MQ 文件结构 + +这是我最建议你统一下来的部分。 + +每个 Skill: + +```markdown +--- +type: skill + +name: json-repair +version: 1 + +status: compiled + +input: + - text + - format + +output: + - result + +preconditions: + - text != None + +postconditions: + - valid(result) + +confidence: 0.96 +success_rate: 0.97 +evidence: 21 + +cost: + level: 0 + llm_calls: 0 + avg_tokens: 0 + +created_from: + - episode-001 + - episode-002 + - episode-003 + +validated_at: 2026-09-24 +--- + +# Purpose + +... + +# Preconditions + +... + +# Procedure + +1. ... +2. ... +3. ... + +# Exceptions + +... + +# Verification + +... + +# Fallback + +... + +# Main + +... +``` + +这样 `.mq.md` 同时具有: + +```text +Documentation ++ +Knowledge ++ +Program ++ +Execution ++ +Verification ++ +Provenance +``` + +这正好和你整个 Marqdo 的论文方向统一起来。 + +--- + +# 37. Agent Memory 的目录 + +最终建议: + +```text +.marqdo/ +└── agent/ + ├── episodes/ + │ ├── 2026/ + │ │ └── 09/ + │ │ ├── ep-001.mq.md + │ │ └── ep-002.mq.md + │ + ├── experiences/ + │ ├── json-repair.mq.md + │ └── corpus-search.mq.md + │ + ├── candidates/ + │ └── json-repair/ + │ └── candidate.mq.md + │ + ├── skills/ + │ └── json-repair/ + │ ├── manifest.mq.md + │ ├── v1.mq.md + │ └── v2.mq.md + │ + ├── policies/ + │ └── router.mq.md + │ + ├── tests/ + │ └── json-repair/ + │ ├── test-001.mq.md + │ └── test-002.mq.md + │ + └── index.mq.md +``` + +--- + +# 38. `agent.index` + +不应该每次扫描整个目录。 + +所以需要: + +```text +## index +``` + +维护: + +```yaml +skills: + - name: json-repair + version: 2 + status: stable + embedding: ... + keywords: ... + success_rate: 0.97 + +experiences: + - ... +``` + +Resolver 首先查询 index。 + +--- + +# 39. `agent.kb_lookup` + +你当前已经有: + +```text +agent_kb_lookup +``` + +应该升级成统一: + +```text +## kb_lookup + + `task` + + `mode`=auto +``` + +内部: + +```text +exact +→ alias +→ canonical +→ lexical near +→ semantic near +→ policy +``` + +返回统一结构: + +```json +{ + "match": "near", + "resource": "...", + "score": 0.91, + "confidence": 0.95, + "status": "stable", + "llm_free": true +} +``` + +--- + +# 40. Near Match 之后不要直接执行 + +这是一个非常重要的改进。 + +现在: + +```text +near match + ↓ +skill + ↓ +execute +``` + +容易出现: + +```text +相似 ≠ 相同 +``` + +所以应该: + +```text +near match + ↓ +skill applicability check + ↓ +adapt + ↓ +execute +``` + +增加: + +```text +## adapt_skill +``` + +输入: + +```text +task +skill +``` + +输出: + +```text +binding +``` + +例如: + +```yaml +format: yaml +text: ... +``` + +--- + +# 41. Skill Applicability + +Skill 应该有: + +```yaml +applicability: + domain: structured-data + input_types: + - json + - yaml + constraints: + - has_text_input +``` + +Resolver 不仅问: + +> “像不像?” + +还要问: + +> “这个技能能不能合法处理这个输入?” + +--- + +# 42. Failure Learning + +Agent 不应该只保存成功经验。 + +应该记录: + +```text +成功: +A → B → C + +失败: +A → D → C +``` + +这样才能学习: + +```text +不要 D +``` + +因此 Episode: + +```yaml +status: failed + +failure: + phase: validate + reason: invalid_schema +``` + +然后 Learning Pipeline 可以提取: + +```text +negative pattern +``` + +--- + +# 43. `agent.extract_failure` + +增加: + +```text +## extract_failure + + `episodes` +``` + +输出: + +```yaml +avoid: + - call X before validation + - use Y when input is binary +``` + +然后写入: + +```markdown +# Exceptions + +- Do not use X when ... +- If Y fails, fallback to ... +``` + +--- + +# 44. Self-Improvement + +已有 skill: + +```text +Skill v1 +``` + +运行几十次后: + +```text +发现: +98% 成功 +2% 某种边缘输入失败 +``` + +Agent 不应该立即改变 v1。 + +应该: + +```text +v1 + ↓ +failure cluster + ↓ +candidate v2 + ↓ +regression tests + ↓ +benchmark + ↓ +v2 +``` + +这就是: + +> **Skill Evolution** + +--- + +# 45. `agent.evolve` + +最终: + +```text +## evolve + + `skill` +``` + +执行: + +```text +collect failures +↓ +extract pattern +↓ +patch candidate +↓ +run regression +↓ +compare +↓ +promote / reject +``` + +这比简单的: + +```text +improve_every=3 +``` + +更完整。 + +--- + +# 46. 最终函数清单 + +我建议最终把 Agent API 控制在这些核心函数。 + +### Runtime + +```text +agent.run +agent.step +agent.plan +agent.execute +agent.route +``` + +### Resolution + +```text +agent.resolve +agent.kb_lookup +agent.skill_match +agent.adapt_skill +``` + +### Execution + +```text +agent.execute_skill +agent.execute_policy +agent.explore +agent.select_strategy +``` + +### Verification + +```text +agent.verify +agent.verify_output +agent.verify_skill +agent.regression_test +``` + +### Memory + +```text +agent.record_episode +agent.get_episode +agent.cluster_episodes +agent.extract_pattern +agent.extract_failure +``` + +### Learning + +```text +agent.learn +agent.maybe_learn +agent.generalize +agent.synthesize_skill +``` + +### Compilation + +```text +agent.compile +agent.promote +agent.rollback +agent.evolve +``` + +### Observation + +```text +agent.event +agent.trace +agent.inspect +agent.metrics +``` + +--- + +# 47. `plan()` 最终应该变成什么 + +这是最重要的一点。 + +你现在的 `plan()` 实际上已经非常庞大,因为它同时承担: + +```text +reuse +explore +decompose +execute +await +revise +promote +stream +trace +``` + +当前实现中 `plan` 已经包含这些职责,例如 reuse 命中后直接 await workbook、探索新 variant、执行后 revise,以及成功后的 KB promotion。 + +**v2 不应该继续往 `plan()` 里面塞逻辑。** + +应该把: + +```text +plan() +``` + +变成 orchestrator: + +```text +## plan + +resolve +↓ +route +↓ +execute +↓ +verify +↓ +record +↓ +learn +↓ +finish +``` + +真正的逻辑全部下沉到函数。 + +即: + +```text +plan + ├── resolve + ├── route + ├── execute + ├── verify + ├── record_episode + └── maybe_learn +``` + +这样 `plan` 才会重新变得可读。 + +--- + +# 48. 一个完整执行例子 + +假设用户第一次说: + +```text +把这个 JSON 字符串修复成合法 JSON +``` + +第一次: + +```text +run + ↓ +resolve + ↓ +MISS + ↓ +explore + ↓ +LLM + ↓ +tool + ↓ +verify + ↓ +success + ↓ +episode-001 +``` + +第二次: + +```text +run + ↓ +near match + ↓ +explore variant + ↓ +success + ↓ +episode-002 +``` + +第三次: + +```text +run + ↓ +near match + ↓ +explore + ↓ +success + ↓ +episode-003 + ↓ +maybe_learn +``` + +触发: + +```text +cluster + ↓ +pattern extraction + ↓ +generalization + ↓ +candidate skill +``` + +然后: + +```text +historical test ++ +held-out test +``` + +通过: + +```text +candidate + ↓ +compile + ↓ +json-repair/v1.mq.md + ↓ +llm_free=true +``` + +第四次: + +```text +run + ↓ +exact/near + ↓ +compiled skill + ↓ +Marqdo execution + ↓ +verify + ↓ +result +``` + +: + +```text +LLM calls = 0 +``` + +这就是你最开始提出的: + +> **第一次会思考,后来逐渐不需要思考。** + +--- + +# 49. 最重要的指标:Reasoning Amortization + +我认为这个设计真正厉害的地方,不只是 Agent。 + +它可以形成一个非常明确的实验指标: + +```text +Reasoning Cost / Successful Task +``` + +例如: + +| Execution | Mode | LLM Calls | Tokens | Latency | +| --------- | ----------- | --------: | -----: | ------: | +| #1 | Explore | 7 | 8,200 | 6.1s | +| #2 | Explore | 5 | 5,900 | 4.3s | +| #3 | Candidate | 3 | 3,200 | 2.8s | +| #4 | Small Model | 1 | 500 | 0.9s | +| #5 | Compiled | 0 | 0 | 0.1s | +| #10 | Compiled | 0 | 0 | 0.1s | + +于是: + +```text +Experience ↑ +Reasoning Cost ↓ +``` + +这条曲线实际上就是你整个 Agent framework 的核心。 + +--- + +# 50. Marqdo Agent 的最终定义 + +我会把整个系统概括成: + +```text + MARQDO AGENT + │ + ┌───────────┴───────────┐ + │ │ + ONLINE RUNTIME LEARNING RUNTIME + │ │ + ┌─────┴─────┐ ┌─────┴─────┐ + │ │ │ │ + Resolve Execute Episodes Patterns + │ │ │ │ + ↓ ↓ ↓ ↓ + Route Verify Cluster Generalize + │ │ │ │ + └─────┬─────┘ └─────┬─────┘ + │ │ + ↓ ↓ + Result Candidate + │ + ↓ + Validate + │ + ↓ + Compile + │ + ↓ + Executable MQ + │ + └────→ ONLINE +``` + +所以它不是: + +> **Agent + Memory** + +而是: + +> **Agent = Runtime + Experience + Learning + Compiler** + +进一步说: + +> **Marqdo Agent 的“记忆”不是存储过去发生过什么,而是把过去发生过的事情编译成未来可以执行的知识。** + +这句话其实非常适合成为你整个 Agent Framework 的设计核心。 + +--- + +## 51. 我建议的 v2 最小实现路线 + +不要一次实现全部。 + +### Phase 1:Execution Trace + +先实现: + +```text +run +step +plan +record_episode +trace +metrics +``` + +让**每一次执行都产生 `.mq.md` episode**。 + +--- + +### Phase 2:Experience Mining + +增加: + +```text +cluster_episodes +extract_pattern +generalize +synthesize_skill +``` + +实现: + +```text +3+ executions +→ candidate.mq.md +``` + +--- + +### Phase 3:Skill Compiler + +增加: + +```text +verify_skill +compile +promote +rollback +``` + +实现: + +```text +candidate +→ validation +→ compiled +→ llm_free +``` + +这一步完成以后,你的 Agent 才真正具备“学习”。 + +--- + +### Phase 4:Jev Router + +增加: + +```text +route +select_strategy +policy +``` + +形成: + +```text +L0 deterministic +L1 rule +L2 small model +L3 small LLM +L4 large LLM +L5 exploration +``` + +这一步解决的是: + +> **学会以后如何自动降低推理成本。** + +--- + +### Phase 5:Skill Evolution + +最后: + +```text +failure mining +→ candidate v2 +→ regression +→ benchmark +→ promote +→ rollback +``` + +形成真正的: + +> **Self-Evolving Executable Knowledge Base** + +--- + +## 52. 最终我建议把整个模块重新命名 + +现在的: + +```text +ext/ai/agent +``` + +可以继续保留,但内部概念最好从: + +```text +agent +├── step +└── plan +``` + +升级成: + +```text +agent +├── runtime +│ ├── run +│ ├── step +│ ├── plan +│ └── execute +│ +├── resolver +│ ├── resolve +│ ├── kb_lookup +│ ├── route +│ └── adapt +│ +├── memory +│ ├── episode +│ ├── experience +│ └── skill +│ +├── learning +│ ├── cluster +│ ├── extract +│ ├── generalize +│ └── synthesize +│ +├── verifier +│ ├── verify +│ ├── regression +│ └── benchmark +│ +└── compiler + ├── compile + ├── promote + ├── evolve + └── rollback +``` + +这样一来,你原来已经实现的 `agent-kb / reuse / near_match / explore / improve_every / promote / llm_free` 都不是废掉,而是分别归入 **Resolver、Memory、Learning、Compiler** 四个层次。当前代码已经具备这些机制的雏形,所以这是一次架构升级,而不是推倒重写。 + +**我尤其建议下一步直接做一件具体的事:把这个设计进一步落成一份 `ext/ai/agent` v2 的 `.mq.md` 接口规范。** 也就是把上面每个函数具体写成 Marqdo 风格的 `## function`、参数、返回 JSON schema、状态转换以及 `episode.mq.md / skill.mq.md` 的实际格式。这样就可以直接进入实现,而不是停留在架构层。 diff --git a/doc/next/004.md b/doc/next/004.md new file mode 100644 index 0000000..e437ea1 --- /dev/null +++ b/doc/next/004.md @@ -0,0 +1,541 @@ +有时候可能用户不太好接入Jev,所以阶段4应该要允许用户使用小参数的模型代替,你认为呢? + +我非常赞同,而且我甚至建议**不要把 Jev 作为阶段 4 的必选组件**。 + +更准确的设计应该是: + +> **Jev 是一种可选的决策器(Decision Engine),小参数模型是另一种可选实现;Marqdo Agent 本身只规定“需要一个 Router/Policy”,而不规定 Router 必须由什么实现。** + +这样会让整个框架开放很多。 + +### 1. 阶段 4 应该改成“Adaptive Routing” + +原来的: + +```text +Phase 4 + ↓ +Jev Router +``` + +我建议改成: + +```text +Phase 4: Adaptive Routing + │ + ┌─────────┼─────────┐ + ↓ ↓ ↓ + Marqdo Rule Jev Small LLM + │ │ │ + └─────────┼─────────┘ + ↓ + Route Policy +``` + +甚至还可以允许: + +```text +Rule +Small Model +Jev +Full LLM +``` + +混合使用。 + +--- + +# 2. 为什么这个设计更合理 + +因为用户真正需要的不是: + +> “我要接入 Jev。” + +而是: + +> “我希望 Agent 学会以后,不要每次都调用大模型。” + +这两个概念应该分开。 + +所以 Marqdo 只定义接口: + +```text +agent.route(task, candidates) +``` + +至于内部怎么实现,可以是: + +### A. 纯 Marqdo + +```text +if task.type == "json": + return json-repair + +if task.type == "search": + return corpus-search +``` + +完全不需要模型。 + +--- + +### B. 小参数模型 + +比如用户已经有: + +```text +Qwen 0.5B +Qwen 1.5B +Llama 1B +某个本地模型 +``` + +就可以: + +```text +task + ↓ +small model + ↓ +"json-repair" +``` + +甚至可以让用户直接配置: + +```yaml +router: + type: llm + + provider: openai-compatible + base_url: ... + api_key: ... + model: ... +``` + +这和你之前设计 AI 斗蛐蛐时提出的 **OpenAI-compatible URL + Key** 思路其实也很契合。 + +--- + +### C. Jev + +如果用户安装了 Jev: + +```text +task + ↓ +Jev + ↓ +policy +``` + +那么就用 Jev。 + +--- + +### D. 大模型 + +甚至最开始没有任何 Router: + +```text +task + ↓ +large LLM + ↓ +decide +``` + +也是合法的。 + +所以: + +> **Router 是抽象能力,不是具体模型。** + +--- + +# 3. 更重要的是:Router 本身也可以被学习 + +这里我觉得还能进一步提升你的设计。 + +一开始: + +```text +Task + ↓ +Large LLM + ↓ +选择 skill +``` + +系统观察: + +```text +task A → json-repair +task B → json-repair +task C → json-repair +task D → corpus-search +``` + +之后可以自动生成: + +```text +router.mq.md +``` + +例如: + +```markdown +--- +type: policy +status: compiled +--- + +## route + +1. `task.type` == "json" + *"json-repair"* + +2. `task.type` == "search" + *"corpus-search"* + +3. * + *"llm"* +``` + +那么你甚至不需要 Jev。 + +**Marqdo 自己的控制流就是 Router。** + +--- + +# 4. 所以我会重新设计 Cost Ladder + +之前的: + +```text +L0 deterministic +L1 rule +L2 small model +L3 small LLM +L4 large LLM +L5 exploration +``` + +我建议改成: + +```text + ┌────────────────────────┐ + │ Adaptive Router │ + └───────────┬────────────┘ + │ + ┌─────────────────┼─────────────────┐ + ↓ ↓ ↓ + Deterministic Small Model Large LLM + │ │ │ + ↓ ↓ ↓ + L0/L1 L2/L3 L4 + │ + ↓ + Exploration L5 +``` + +这里最关键的是: + +> **L2/L3 不应该规定具体模型。** + +可以是: + +```text +Marqdo rules + OR +Jev + OR +0.5B model + OR +1B model + OR +3B model +``` + +--- + +# 5. 我甚至建议用户可以配置多个 Router + +例如: + +```yaml +router: + candidates: + + - name: rules + type: marqdo + + - name: local + type: llm + model: qwen-0.5b + + - name: jev + type: jev + + - name: cloud + type: llm + model: ... +``` + +然后 Agent 自己选择: + +```text +Task + ↓ +Router Resolver + ↓ +rules? + ↓ +confidence insufficient + ↓ +small model? + ↓ +confidence insufficient + ↓ +Jev? + ↓ +confidence insufficient + ↓ +large LLM +``` + +这就形成一个**分级决策系统**。 + +--- + +# 6. 最漂亮的地方:Router 也可以被编译 + +最终甚至可以: + +```text +第一次: + +LLM + ↓ +决定调用 Skill A + +第二次: + +LLM + ↓ +决定调用 Skill A + +第三次: + +LLM + ↓ +决定调用 Skill A + +Learning + ↓ +发现稳定模式 + +Compile + ↓ +router.mq.md +``` + +以后: + +```text +Task + ↓ +router.mq.md + ↓ +skill A + ↓ +execute +``` + +**0 LLM。** + +于是整个 Agent 的学习就不只是: + +```text +学习如何解决任务 +``` + +而是同时学习: + +```text +1. 学习如何解决任务 +2. 学习什么时候使用什么技能 +3. 学习什么时候需要大模型 +``` + +这三个层次组合起来,我认为比单纯引入 Jev 更有意思。 + +--- + +# 7. 最终可以形成三级编译 + +我现在反而觉得你的 Agent Framework 可以把整个“学习”定义成三个阶段: + +```text +Experience + ↓ +Skill Compilation + ↓ +Policy Compilation + ↓ +Execution Compilation +``` + +### 第一层:Skill Compilation + +```text +LLM experience + ↓ +skill.mq.md +``` + +解决: + +> **怎么做?** + +### 第二层:Policy Compilation + +```text +many task → skill mappings + ↓ +policy.mq.md +``` + +解决: + +> **什么时候做什么?** + +### 第三层:Execution Compilation + +```text +skill + policy + ↓ +pure Marqdo execution +``` + +解决: + +> **能不能完全不思考直接执行?** + +这时候整个 Agent 就变成: + +```text + Large LLM + │ + Exploration + ↓ + Experience + ↓ + ┌───────────────┐ + │ Skill Compile │ + └───────┬───────┘ + ↓ + Skill MQ + │ + ┌───────┴───────┐ + ↓ ↓ + Policy Compile Direct Execute + ↓ + Router MQ + │ + ↓ + Skill Selection + │ + ↓ + Execute +``` + +--- + +# 8. 因此 Phase 4 我建议正式改名 + +不要叫: + +> Jev Router + +而叫: + +> **Adaptive Policy / Routing Layer** + +然后提供四种 backend: + +```text +router.backend = marqdo +router.backend = small-llm +router.backend = jev +router.backend = llm +``` + +甚至: + +```text +router.backend = auto +``` + +让 Agent 根据可用环境自动选择。 + +--- + +## 9. 用户体验也会好很多 + +用户第一次安装 Marqdo: + +```text +marqdo agent run ... +``` + +没有 Jev,也没有小模型。 + +完全没问题: + +```text +→ 使用配置的大模型 +``` + +用户后来配置: + +```yaml +router: + backend: small-llm + provider: openai-compatible + model: qwen-0.5b +``` + +Agent 就自动变成: + +```text +大模型:负责复杂推理 / 学习 +小模型:负责日常路由 +Marqdo:负责确定性执行 +``` + +如果用户安装 Jev: + +```yaml +router: + backend: jev +``` + +则: + +```text +Jev:负责路由 +大模型:负责复杂任务 +Marqdo:负责执行 +``` + +**用户完全不需要改变 Agent 的上层 API。** + +--- + +我认为这个调整非常重要,因为它让 **Marqdo Agent 的核心创新从“依赖某个新模型”变成“模型无关的认知编译架构”**。 + +最终可以浓缩成一句话: + +> **大模型负责探索,小模型/Jev 负责决策,Marqdo 负责执行;随着经验积累,探索和决策逐渐被编译成可执行的 `.mq.md`。** + +这其实比“接入 Jev”本身更符合你最开始提出的 **Think → Execute → Learn → Compile → Reuse** 路线。 diff --git a/doc/roadmap/ext-agent-optimize.md b/doc/roadmap/ext-agent-optimize.md index 8e8f04a..f6bf0a6 100644 --- a/doc/roadmap/ext-agent-optimize.md +++ b/doc/roadmap/ext-agent-optimize.md @@ -39,6 +39,8 @@ | **B0** | 官方示例演示 call_site/源码/OKF;Skill/文档;上下文管道可读 | **done** | | **B0.5** | 本机 live(`.env` → 开发模型)验证「模型用上了文档」 | **done**(`AGENT_LIVE` / `AGENT_HARNESS_LIVE`) | | **B1** | 评测 harness 锁差异化指标(constitution / dump / writeback 遮蔽) | **Active** | -| **B2–B5** | 真 MCP / resume+HITL / stats / 并行 | 暂缓 | +| **B1.5** | **Skill Compilation v2(Phase 1–3)**:episode → maybe_learn → compile → `llm_free`;`agent.run` / `resolve` / `metrics`;ABI 在 `plugins/agent`(`memory.rs`);金样 `agent-v2-learn` | **done** | +| **B1.6 / P4** | **Adaptive Routing**(原 Jev Router 更名):`route` backends = `marqdo` \| `small-llm` \| `jev?` \| `llm` \| `auto`;Policy Compilation → `policies/router.mq.md`;金样 `agent-p4-route`;设计 [004.md](../next/004.md) | **done** | +| **B2–B5** | 真 MCP / resume+HITL / stats / 并行;小模型 live 路由;Jev 可选接线 | 暂缓 | -示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。 +示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。v2 设计:[doc/next/002.md](../next/002.md) · [doc/next/003.md](../next/003.md) · P4:[doc/next/004.md](../next/004.md)。 diff --git a/ext/ai/agent.mq.md b/ext/ai/agent.mq.md index 2265b31..6204b20 100644 --- a/ext/ai/agent.mq.md +++ b/ext/ai/agent.mq.md @@ -1,6 +1,6 @@ --- title: ext/ai/agent -description: Document-driven agent — step / plan; tools via lib/subtask; runtime via ABI v2 agent plugin. +description: Document-driven agent v2 — step / plan / run; Skill Compilation via ABI plugin (episodes → learn → llm_free). import llm:ext/ai/llm.mq.md import json:lib/json.mq.md import sys:lib/sys.mq.md @@ -1515,6 +1515,308 @@ Clear the plugin session bag for this agent id. > agent_history_clear id=`id` **** +## resolve + + `task` + + `kb_dir`=.marqdo/agent-kb + + `near_match`=True + + `near_threshold`=0.78 + +Skill resolver (v2): exact → alias → canonical → near. Returns `mode` / `resource` / `llm_free` / `confidence`. Plugin ABI — no core host_* calls. + +**tools = > json.get value=`self` key="tools"** +*> agent_resolve task=`task` kb_dir=`kb_dir` near_match=`near_match` near_threshold=`near_threshold` tools=`tools`* + +## route + + `task` + + `backend`=auto + + `kb_dir`=.marqdo/agent-kb + + `memory_dir`=.marqdo/agent-memory + + `threshold`=0.78 + +Adaptive Routing (Phase 4): abstract router — `marqdo` | `small-llm` | `jev` | `llm` | `auto`. Jev is optional. `auto` cascades policy → kb → optional jev → small-llm request. May return `needs_llm=True` + `prompt` for the caller to complete with a small/large model, then `route_apply`. + +**tools = > json.get value=`self` key="tools"** +*> agent_route task=`task` backend=`backend` kb_dir=`kb_dir` memory_dir=`memory_dir` threshold=`threshold` tools=`tools`* + +## route_apply + + `task` + + `reply` + + `kb_dir`=.marqdo/agent-kb + + `backend`=small-llm + +Apply a router model line (`SKILL:` / `EXPLORE`) to a kb skill hit. + +*> agent_route_apply task=`task` reply=`reply` kb_dir=`kb_dir` backend=`backend`* + +## compile_policy + + `memory_dir`=.marqdo/agent-memory + + `min_evidence`=3 + + `force`=False + +Policy Compilation: stable episode skill selections → `policies/router.mq.md` (deterministic Marqdo rules). + +*> agent_compile_policy memory_dir=`memory_dir` min_evidence=`min_evidence` force=`force`* + +## maybe_compile_policy + + `memory_dir`=.marqdo/agent-memory + + `min_evidence`=3 + +Learn gate for the Adaptive Router policy layer. + +*> agent_maybe_compile_policy memory_dir=`memory_dir` min_evidence=`min_evidence`* + +## record_episode + + `task` + + `status`=ok + + `result`=None + + `mode`=explore + + `skill`=none + + `observation`=None + + `workbook`=None + + `cache`=None + + `match`=None + + `llm_calls`=0 + + `tool_calls`=0 + + `error`=None + + `memory_dir`=.marqdo/agent-memory + +Persist one run as `.mq.md` under `memory_dir/episodes/YYYY/MM/` (v2 Phase 1). Memory is executable documentation, not a vector bag. + +*> agent_record_episode task=`task` status=`status` result=`result` mode=`mode` skill=`skill` observation=`observation` workbook=`workbook` cache=`cache` match=`match` llm_calls=`llm_calls` tool_calls=`tool_calls` error=`error` memory_dir=`memory_dir`* + +## maybe_learn + + `task` + + `kb_dir`=.marqdo/agent-kb + + `memory_dir`=.marqdo/agent-memory + + `improve_every`=3 + + `promote`=True + +Offline learn gate: when ≥ `improve_every` successful episodes share a task hash, generalize → synthesize → compile → optional OKF promote (`llm_free`). Also attempts Policy Compilation for Adaptive Routing. + +**skill_learn = > agent_maybe_learn task=`task` kb_dir=`kb_dir` memory_dir=`memory_dir` improve_every=`improve_every` promote=`promote`** +**policy_learn = > agent_maybe_compile_policy memory_dir=`memory_dir` min_evidence=`improve_every`** +**out = > json.parse text={"learned":false}** +**sl = > json.get value=`skill_learn` key="learned"** +**out = > json.set map=`out` key="learned" value=`sl`** +**out = > json.set map=`out` key="skill" value=`skill_learn`** +**out = > json.set map=`out` key="policy" value=`policy_learn`** +*out* + +## compile + + `task` + + `kb_dir`=.marqdo/agent-kb + + `memory_dir`=.marqdo/agent-memory + + `min_evidence`=3 + + `promote`=True + + `force`=False + +Compile a candidate skill into versioned `skills//vN.mq.md` and optionally promote into agent-kb. + +*> agent_compile_skill task=`task` kb_dir=`kb_dir` memory_dir=`memory_dir` min_evidence=`min_evidence` promote=`promote` force=`force`* + +## metrics + + `memory_dir`=.marqdo/agent-memory + +Reasoning amortization stats over recorded episodes (`avg_llm_calls`, `compiled_runs`, …). + +*> agent_metrics memory_dir=`memory_dir`* + +## run + + `task` + + `kb_dir`=.marqdo/agent-kb + + `memory_dir`=.marqdo/agent-memory + + `learn`=True + + `verify`=True + + `writeback`=True + + `reuse`=True + + `near_match`=True + + `near_threshold`=0.78 + + `promote`=True + + `improve_every`=3 + + `explore_n`=3 + + `max_rounds`=4 + + `stream`=False + + `echo`=False + + `trace`=False + + `force`=False + + `router`=auto + + `router_model`=None + +Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) or `plan` → record episode → maybe_learn (skill + policy). `router` = `auto`|`marqdo`|`small-llm`|`jev`|`llm`. Optional `router_model` (llm handle) answers `needs_llm` prompts — small models welcome; Jev is never required. + +**routed = > `self`.route task=`task` backend=`router` kb_dir=`kb_dir` memory_dir=`memory_dir` threshold=`near_threshold`** +**route_matched = > json.get value=`routed` key="matched"** +**needs_llm = > json.get value=`routed` key="needs_llm"** +**exec_mode = "explore"** +**llm_calls = 0** +**out = None** +**route_backend = > json.get value=`routed` key="backend"** + +1. `route_matched` + **path = > json.get value=`routed` key="resource"** + 1. `path` + **aw = > await_workbook path=`path`** + **code = > json.get value=`aw` key="code"** + **child_val = > json.get value=`aw` key="value"** + **last_obs = > json.get value=`aw` key="observation"** + 1. `code` == 0 + > agent_kb_record_hit kb_dir=`kb_dir` goal=`task` improve_every=`improve_every` + **lf = > json.get value=`routed` key="llm_free"** + 1. `lf` + **exec_mode = "compiled"** + 2. * + **exec_mode = "routed"** + **out = > json.parse text={"status":"ok"}** + **out = > json.set map=`out` key="status" value="ok"** + **out = > json.set map=`out` key="goal" value=`task`** + **out = > json.set map=`out` key="result" value=`child_val`** + **out = > json.set map=`out` key="workbook" value=`path`** + **out = > json.set map=`out` key="cache" value="hit"** + **rmode = > json.get value=`routed` key="mode"** + **out = > json.set map=`out` key="match" value=`rmode`** + **sk = > json.get value=`routed` key="skill"** + **out = > json.set map=`out` key="skill" value=`sk`** + **out = > json.set map=`out` key="observation" value=`last_obs`** + **out = > json.set map=`out` key="summary" value="adaptive route hit"** + **out = > json.set map=`out` key="route" value=`routed`** + **llm_calls = 0** + 2. * + **route_matched = False** + 2. * + **route_matched = False** +2. * + **_ = 1** + +1. `route_matched` + **_ = 1** +2. `needs_llm` + 1. `router_model` + **prompt = > json.get value=`routed` key="prompt"** + 1. `stream` + **evs = > router_model.complete prompt=`prompt` stream=True echo=`echo`** + **reply = > llm.stream_result events=`evs`** + 2. * + **reply = > router_model.complete prompt=`prompt`** + **applied = > `self`.route_apply task=`task` reply=`reply` kb_dir=`kb_dir` backend=`router`** + **llm_calls = 1** + **am = > json.get value=`applied` key="matched"** + 1. `am` + **path = > json.get value=`applied` key="resource"** + **aw = > await_workbook path=`path`** + **code = > json.get value=`aw` key="code"** + **child_val = > json.get value=`aw` key="value"** + **last_obs = > json.get value=`aw` key="observation"** + 1. `code` == 0 + **exec_mode = "routed"** + **out = > json.parse text={"status":"ok"}** + **out = > json.set map=`out` key="status" value="ok"** + **out = > json.set map=`out` key="goal" value=`task`** + **out = > json.set map=`out` key="result" value=`child_val`** + **out = > json.set map=`out` key="workbook" value=`path`** + **out = > json.set map=`out` key="cache" value="soft-hit"** + **out = > json.set map=`out` key="match" value="routed"** + **sk = > json.get value=`applied` key="skill"** + **out = > json.set map=`out` key="skill" value=`sk`** + **out = > json.set map=`out` key="observation" value=`last_obs`** + **out = > json.set map=`out` key="summary" value="router model selected skill"** + **out = > json.set map=`out` key="route" value=`applied`** + **route_matched = True** + 2. * + **route_matched = False** + 2. * + **route_matched = False** + 2. * + **route_matched = False** +3. * + **_ = 1** + +1. `route_matched` + **_ = 1** +2. * + **resolved = > `self`.resolve task=`task` kb_dir=`kb_dir` near_match=`near_match` near_threshold=`near_threshold`** + **mode = > json.get value=`resolved` key="mode"** + **llm_free = > json.get value=`resolved` key="llm_free"** + 1. `llm_free` + **path = > json.get value=`resolved` key="resource"** + **aw = > await_workbook path=`path`** + **code = > json.get value=`aw` key="code"** + **child_val = > json.get value=`aw` key="value"** + **last_obs = > json.get value=`aw` key="observation"** + 1. `code` == 0 + > agent_kb_record_hit kb_dir=`kb_dir` goal=`task` improve_every=`improve_every` + **exec_mode = "compiled"** + **out = > json.parse text={"status":"ok"}** + **out = > json.set map=`out` key="status" value="ok"** + **out = > json.set map=`out` key="goal" value=`task`** + **out = > json.set map=`out` key="result" value=`child_val`** + **out = > json.set map=`out` key="workbook" value=`path`** + **out = > json.set map=`out` key="cache" value="hit"** + **out = > json.set map=`out` key="match" value=`mode`** + **sk = > json.get value=`resolved` key="skill"** + **out = > json.set map=`out` key="skill" value=`sk`** + **out = > json.set map=`out` key="observation" value=`last_obs`** + **out = > json.set map=`out` key="summary" value="compiled skill (llm_free)"** + **llm_calls = 0** + 2. * + **out = > `self`.plan goal=`task` kb_dir=`kb_dir` writeback=`writeback` reuse=`reuse` near_match=`near_match` near_threshold=`near_threshold` promote=`promote` improve_every=`improve_every` explore_n=`explore_n` max_rounds=`max_rounds` stream=`stream` echo=`echo` trace=`trace` force=`force`** + **exec_mode = "explore"** + **llm_calls = 1** + 2. * + **out = > `self`.plan goal=`task` kb_dir=`kb_dir` writeback=`writeback` reuse=`reuse` near_match=`near_match` near_threshold=`near_threshold` promote=`promote` improve_every=`improve_every` explore_n=`explore_n` max_rounds=`max_rounds` stream=`stream` echo=`echo` trace=`trace` force=`force`** + **cache = > json.get value=`out` key="cache"** + 1. `cache` == hit + **exec_mode = "compiled"** + **llm_calls = 0** + 2. `cache` == soft-hit + **exec_mode = "near"** + **llm_calls = 0** + 3. * + **exec_mode = "explore"** + **llm_calls = 1** + +**st = > json.get value=`out` key="status"** +**res = > json.get value=`out` key="result"** +**wb_path = > json.get value=`out` key="workbook"** +**obs = > json.get value=`out` key="observation"** +**sk2 = > json.get value=`out` key="skill"** +**cache2 = > json.get value=`out` key="cache"** +**match2 = > json.get value=`out` key="match"** +**err = > json.get value=`out` key="error"** + +1. `verify` + 1. `st` == "ok" + **verification = "status: passed"** + 2. * + **verification = "status: failed"** +2. * + **verification = "status: skipped"** + +**ep = > `self`.record_episode task=`task` status=`st` result=`res` mode=`exec_mode` skill=`sk2` observation=`obs` workbook=`wb_path` cache=`cache2` match=`match2` llm_calls=`llm_calls` error=`err` memory_dir=`memory_dir`** + +**learning = None** +1. `learn` + 1. `st` == "ok" + **learning = > `self`.maybe_learn task=`task` kb_dir=`kb_dir` memory_dir=`memory_dir` improve_every=`improve_every` promote=`promote`** + 2. * + **learning = None** +2. * + **_ = 1** + +**execution = > json.parse text={"mode":"explore","llm_calls":0}** +**execution = > json.set map=`execution` key="mode" value=`exec_mode`** +**execution = > json.set map=`execution` key="llm_calls" value=`llm_calls`** +**execution = > json.set map=`execution` key="skill" value=`sk2`** +**execution = > json.set map=`execution` key="router" value=`route_backend`** +**out = > json.set map=`out` key="execution" value=`execution`** +**out = > json.set map=`out` key="episode" value=`ep`** +**out = > json.set map=`out` key="route" value=`routed`** +1. `learning` + **out = > json.set map=`out` key="learning" value=`learning`** +2. * + **_ = 1** + +*out* + ## step + `task` + `writeback`=True diff --git a/ext/ai/智能体.mq.md b/ext/ai/智能体.mq.md index e92d66d..8a3bef2 100644 --- a/ext/ai/智能体.mq.md +++ b/ext/ai/智能体.mq.md @@ -1,6 +1,6 @@ --- title: ext/ai/智能体 -description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务;运行时经 ABI v2 agent 插件。 +description: 文档驱动智能体 v2 — 单步 / 多步 / 运行;技能编译经 ABI v2 agent 插件(情景 → 学习 → llm_free)。 导入 大模型:ext/ai/大模型.mq.md import agent:ext/ai/agent.mq.md import json:lib/json.mq.md @@ -212,3 +212,112 @@ import json:lib/json.mq.md **standing = > json.get value=`self` key="standing"** **en = > agent.agent model=`model` tools=`tools` standing=`standing`** *> en.plan goal=`目标` workbook_dir=`工作簿目录` workbook=`工作簿` max_rounds=`最大轮次` confirm=`确认分解` writeback=`写回` skeleton=`骨架` reuse=`复用` optimize=`优化` force=`强制` soft_match=`软命中` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` kb_dir=`知识库目录` improve_every=`改进周期` explore_n=`探索次数` stream=`流式` echo=`打印增量` trace=`轨迹`* + +## 解析 + + `任务` + + `知识库目录`=.marqdo/agent-kb + + `近义命中`=True + + `近义阈值`=0.78 + +技能解析(v2):exact → alias → canonical → near。 + +**model = > json.get value=`self` key="model"** +**tools = > json.get value=`self` key="tools"** +**standing = > json.get value=`self` key="standing"** +**en = > agent.agent model=`model` tools=`tools` standing=`standing`** +*> en.resolve task=`任务` kb_dir=`知识库目录` near_match=`近义命中` near_threshold=`近义阈值`* + +## 记录情景 + + `任务` + + `状态`=ok + + `结果`=None + + `模式`=explore + + `技能`=none + + `观察`=None + + `工作簿`=None + + `缓存`=None + + `匹配`=None + + `大模型次数`=0 + + `工具次数`=0 + + `错误`=None + + `记忆目录`=.marqdo/agent-memory + +将一次执行沉淀为 `.mq.md` 情景记忆。 + +**model = > json.get value=`self` key="model"** +**tools = > json.get value=`self` key="tools"** +**standing = > json.get value=`self` key="standing"** +**en = > agent.agent model=`model` tools=`tools` standing=`standing`** +*> en.record_episode task=`任务` status=`状态` result=`结果` mode=`模式` skill=`技能` observation=`观察` workbook=`工作簿` cache=`缓存` match=`匹配` llm_calls=`大模型次数` tool_calls=`工具次数` error=`错误` memory_dir=`记忆目录`* + +## 尝试学习 + + `任务` + + `知识库目录`=.marqdo/agent-kb + + `记忆目录`=.marqdo/agent-memory + + `改进周期`=3 + + `晋升`=True + +情景足够时:归纳 → 合成候选 → 编译 → 可选晋升为 `llm_free` 技能。 + +**model = > json.get value=`self` key="model"** +**tools = > json.get value=`self` key="tools"** +**standing = > json.get value=`self` key="standing"** +**en = > agent.agent model=`model` tools=`tools` standing=`standing`** +*> en.maybe_learn task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` improve_every=`改进周期` promote=`晋升`* + +## 运行 + + `任务` + + `知识库目录`=.marqdo/agent-kb + + `记忆目录`=.marqdo/agent-memory + + `学习`=True + + `校验`=True + + `写回`=True + + `复用`=True + + `近义命中`=True + + `近义阈值`=0.78 + + `晋升`=True + + `改进周期`=3 + + `探索次数`=3 + + `最大轮次`=4 + + `流式`=False + + `打印增量`=False + + `轨迹`=False + + `强制`=False + + `路由`=auto + + `路由模型`=None + +v2+P4 主入口:自适应路由 → 执行 → 记录情景 → 尝试学习(技能 + 策略)。`路由`=`auto`|`marqdo`|`small-llm`|`jev`|`llm`;Jev 可选,小模型可作决策器。 + +**model = > json.get value=`self` key="model"** +**tools = > json.get value=`self` key="tools"** +**standing = > json.get value=`self` key="standing"** +**en = > agent.agent model=`model` tools=`tools` standing=`standing`** +*> en.run task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` learn=`学习` verify=`校验` writeback=`写回` reuse=`复用` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` improve_every=`改进周期` explore_n=`探索次数` max_rounds=`最大轮次` stream=`流式` echo=`打印增量` trace=`轨迹` force=`强制` router=`路由` router_model=`路由模型`* + +## 路由 + + `任务` + + `后端`=auto + + `知识库目录`=.marqdo/agent-kb + + `记忆目录`=.marqdo/agent-memory + + `阈值`=0.78 + +自适应路由(阶段 4):`marqdo` / `small-llm` / `jev` / `llm` / `auto`。 + +**model = > json.get value=`self` key="model"** +**tools = > json.get value=`self` key="tools"** +**standing = > json.get value=`self` key="standing"** +**en = > agent.agent model=`model` tools=`tools` standing=`standing`** +*> en.route task=`任务` backend=`后端` kb_dir=`知识库目录` memory_dir=`记忆目录` threshold=`阈值`* + +## 编译策略 + + `记忆目录`=.marqdo/agent-memory + + `最少证据`=3 + + `强制`=False + +策略编译:稳定的 task→skill 映射 → `policies/router.mq.md`。 + +**model = > json.get value=`self` key="model"** +**tools = > json.get value=`self` key="tools"** +**standing = > json.get value=`self` key="standing"** +**en = > agent.agent model=`model` tools=`tools` standing=`standing`** +*> en.compile_policy memory_dir=`记忆目录` min_evidence=`最少证据` force=`强制`* diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 2bef508..c4d2cee 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -1,8 +1,10 @@ -//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb. +//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb + v2 memory + adaptive route. mod corpus; mod kb; mod mcp_server; +mod memory; +mod route; use std::collections::HashMap; use std::ffi::{CStr, CString}; @@ -902,6 +904,26 @@ kb_ffi!( "agent_workbook_solidify" ); kb_ffi!(agent_kb_task_files, kb::kb_task_files, "agent_kb_task_files"); +kb_ffi!(agent_memory_ensure, memory::memory_ensure, "agent_memory_ensure"); +kb_ffi!(agent_record_episode, memory::record_episode, "agent_record_episode"); +kb_ffi!(agent_list_episodes, memory::list_episodes, "agent_list_episodes"); +kb_ffi!(agent_get_episode, memory::get_episode, "agent_get_episode"); +kb_ffi!(agent_cluster_episodes, memory::cluster_episodes, "agent_cluster_episodes"); +kb_ffi!(agent_extract_pattern, memory::extract_pattern, "agent_extract_pattern"); +kb_ffi!(agent_generalize, memory::generalize, "agent_generalize"); +kb_ffi!(agent_synthesize_skill, memory::synthesize_skill, "agent_synthesize_skill"); +kb_ffi!(agent_compile_skill, memory::compile_skill, "agent_compile_skill"); +kb_ffi!(agent_maybe_learn, memory::maybe_learn, "agent_maybe_learn"); +kb_ffi!(agent_metrics, memory::metrics, "agent_metrics"); +kb_ffi!(agent_resolve, memory::resolve_task, "agent_resolve"); +kb_ffi!(agent_route, route::route, "agent_route"); +kb_ffi!(agent_route_apply, route::route_apply, "agent_route_apply"); +kb_ffi!(agent_compile_policy, route::compile_policy, "agent_compile_policy"); +kb_ffi!( + agent_maybe_compile_policy, + route::maybe_compile_policy, + "agent_maybe_compile_policy" +); #[no_mangle] pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 { @@ -1022,6 +1044,90 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int if register(host, "agent_kb_task_files", "kb_dir,goal", agent_kb_task_files) != 0 { return 1; } + if register(host, "agent_memory_ensure", "memory_dir", agent_memory_ensure) != 0 { + return 1; + } + if register( + host, + "agent_record_episode", + "task,status,result,mode", + agent_record_episode, + ) != 0 + { + return 1; + } + if register(host, "agent_list_episodes", "memory_dir,task", agent_list_episodes) != 0 { + return 1; + } + if register(host, "agent_get_episode", "id", agent_get_episode) != 0 { + return 1; + } + if register( + host, + "agent_cluster_episodes", + "memory_dir,task,threshold", + agent_cluster_episodes, + ) != 0 + { + return 1; + } + if register(host, "agent_extract_pattern", "task", agent_extract_pattern) != 0 { + return 1; + } + if register(host, "agent_generalize", "task", agent_generalize) != 0 { + return 1; + } + if register(host, "agent_synthesize_skill", "task", agent_synthesize_skill) != 0 { + return 1; + } + if register( + host, + "agent_compile_skill", + "task,kb_dir,min_evidence", + agent_compile_skill, + ) != 0 + { + return 1; + } + if register( + host, + "agent_maybe_learn", + "task,kb_dir,improve_every", + agent_maybe_learn, + ) != 0 + { + return 1; + } + if register(host, "agent_metrics", "memory_dir", agent_metrics) != 0 { + return 1; + } + if register(host, "agent_resolve", "task,kb_dir", agent_resolve) != 0 { + return 1; + } + if register(host, "agent_route", "task,backend,kb_dir,memory_dir", agent_route) != 0 { + return 1; + } + if register(host, "agent_route_apply", "task,reply,kb_dir", agent_route_apply) != 0 { + return 1; + } + if register( + host, + "agent_compile_policy", + "memory_dir,min_evidence", + agent_compile_policy, + ) != 0 + { + return 1; + } + if register( + host, + "agent_maybe_compile_policy", + "memory_dir,min_evidence", + agent_maybe_compile_policy, + ) != 0 + { + return 1; + } 0 } diff --git a/plugins/agent/src/memory.rs b/plugins/agent/src/memory.rs new file mode 100644 index 0000000..814668d --- /dev/null +++ b/plugins/agent/src/memory.rs @@ -0,0 +1,1135 @@ +//! Agent Framework v2 memory: episodes → experience → compile (plugin-side). +//! Layout under `.marqdo/agent-memory/` (default). Does not touch `src/host`. + +use std::fs; +use std::path::{Path, PathBuf}; + +use chrono::Datelike; +use serde_json::{json, Value}; + +use crate::kb::{ + canonicalize_goal_str, char_bigram_tf, cosine_tf, goal_sig_hex, goal_slug_str, normalize_goal, +}; + +const DEFAULT_MEMORY_DIR: &str = ".marqdo/agent-memory"; +const DEFAULT_KB_DIR: &str = ".marqdo/agent-kb"; + +fn resolve_path(rel: &str) -> PathBuf { + let p = PathBuf::from(rel); + if p.is_absolute() { + return p; + } + // Already valid relative to process cwd (e.g. re-passed after prior join). + if p.exists() { + return p; + } + let base = (|| { + let q = crate::host_query_json("cwd")?; + q.as_str() + .map(PathBuf::from) + .ok_or_else(|| "cwd not text".to_string()) + })() + .or_else(|_| std::env::current_dir().map_err(|e| e.to_string())) + .unwrap_or_else(|_| PathBuf::from(".")); + let joined = base.join(&p); + if joined.exists() || !base.as_os_str().is_empty() { + return joined; + } + p +} + +fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> { + args.get(key) + .and_then(|v| v.as_str()) + .ok_or_else(|| format!("missing text `{key}`")) +} + +fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> { + args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty()) +} + +fn opt_i64(args: &Value, key: &str, default: i64) -> i64 { + match args.get(key) { + None | Some(Value::Null) => default, + Some(Value::Number(n)) => n.as_i64().unwrap_or(default), + Some(Value::String(s)) => s.parse().unwrap_or(default), + Some(Value::Bool(b)) => { + if *b { + 1 + } else { + 0 + } + } + _ => default, + } +} + +fn opt_bool(args: &Value, key: &str, default: bool) -> bool { + match args.get(key) { + None | Some(Value::Null) => default, + Some(Value::Bool(b)) => *b, + Some(Value::String(s)) => matches!(s.as_str(), "true" | "True" | "1" | "yes"), + Some(Value::Number(n)) => n.as_i64().unwrap_or(0) != 0, + _ => default, + } +} + +fn memory_root(args: &Value) -> PathBuf { + let rel = opt_text(args, "memory_dir").unwrap_or(DEFAULT_MEMORY_DIR); + resolve_path(rel) +} + +fn now_rfc3339() -> String { + chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true) +} + +fn yaml_escape(s: &str) -> String { + if s.is_empty() + || s.contains(':') + || s.contains('#') + || s.contains('"') + || s.contains('\'') + || s.contains('\n') + || s.starts_with(' ') + { + format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\"")) + } else { + s.to_string() + } +} + +fn marqdo_quoted(s: &str) -> String { + let mut out = String::from("\""); + for c in s.chars() { + match c { + '\\' => out.push_str("\\\\"), + '"' => out.push_str("\\\""), + '\n' => out.push_str("\\n"), + '\t' => out.push_str("\\t"), + c => out.push(c), + } + } + out.push('"'); + out +} + +fn value_brief(v: &Value) -> String { + match v { + Value::Null => String::new(), + Value::String(s) => s.clone(), + Value::Number(n) => n.to_string(), + Value::Bool(b) => { + if *b { + "true".into() + } else { + "false".into() + } + } + other => other.to_string(), + } +} + +fn ensure_layout(root: &Path) -> Result<(), String> { + for sub in [ + "episodes", + "experiences", + "candidates", + "skills", + "policies", + "tests", + ] { + fs::create_dir_all(root.join(sub)).map_err(|e| format!("mkdir {sub}: {e}"))?; + } + let index = root.join("index.mq.md"); + if !index.is_file() { + let body = "---\ntype: agent-memory-index\ntitle: agent-memory\n---\n\n# Agent memory\n\nEpisodes, experiences, and compiled skills.\n"; + fs::write(&index, body).map_err(|e| format!("write index: {e}"))?; + } + Ok(()) +} + +/// Ensure `.marqdo/agent-memory/` layout exists. +pub fn memory_ensure(args: &Value) -> Result { + let root = memory_root(args); + ensure_layout(&root)?; + Ok(json!({ + "ok": true, + "memory_dir": root.to_string_lossy(), + })) +} + +fn episode_dir(root: &Path) -> PathBuf { + let now = chrono::Utc::now(); + root.join("episodes") + .join(format!("{:04}", now.year())) + .join(format!("{:02}", now.month())) +} + +fn next_episode_id(dir: &Path) -> Result<(String, PathBuf), String> { + fs::create_dir_all(dir).map_err(|e| format!("mkdir episodes: {e}"))?; + let mut max = 0u64; + if let Ok(rd) = fs::read_dir(dir) { + for ent in rd.flatten() { + let name = ent.file_name().to_string_lossy().into_owned(); + if let Some(rest) = name.strip_prefix("episode-") { + if let Some(num) = rest.strip_suffix(".mq.md") { + if let Ok(n) = num.parse::() { + max = max.max(n); + } + } + } + } + } + let id_n = max + 1; + let id = format!("episode-{id_n:04}"); + let path = dir.join(format!("{id}.mq.md")); + Ok((id, path)) +} + +fn section(title: &str, body: &str) -> String { + let b = body.trim(); + if b.is_empty() { + format!("# {title}\n\nnone\n") + } else { + format!("# {title}\n\n{b}\n") + } +} + +/// Record one execution as a readable `.mq.md` episode (v2 Phase 1). +pub fn record_episode(args: &Value) -> Result { + let root = memory_root(args); + ensure_layout(&root)?; + let task = arg_text(args, "task").or_else(|_| arg_text(args, "goal"))?; + let task_n = normalize_goal(task); + let task_hash = goal_sig_hex(&task_n); + let slug = goal_slug_str(&task_n); + let status = opt_text(args, "status").unwrap_or("success"); + let mode = opt_text(args, "mode").unwrap_or("explore"); + let skill = opt_text(args, "skill") + .map(|s| s.to_string()) + .or_else(|| { + args.get("skill") + .filter(|v| !v.is_null()) + .map(value_brief) + .filter(|s| !s.is_empty() && s != "null") + }) + .unwrap_or_else(|| "none".into()); + let result = args + .get("result") + .map(value_brief) + .unwrap_or_default(); + let context = args + .get("context") + .map(value_brief) + .unwrap_or_default(); + let actions = args + .get("actions") + .map(value_brief) + .unwrap_or_default(); + let observations = args + .get("observations") + .or_else(|| args.get("observation")) + .map(value_brief) + .unwrap_or_default(); + let verification = args + .get("verification") + .map(value_brief) + .unwrap_or_else(|| { + if status == "ok" || status == "success" { + "status: passed".into() + } else { + "status: failed".into() + } + }); + let errors = args + .get("errors") + .or_else(|| args.get("error")) + .map(value_brief) + .unwrap_or_else(|| "none".into()); + let llm_calls = opt_i64(args, "llm_calls", 0); + let tool_calls = opt_i64(args, "tool_calls", 0); + let tokens = opt_i64(args, "tokens", 0); + let latency_ms = opt_i64(args, "latency_ms", 0); + let workbook = opt_text(args, "workbook").unwrap_or(""); + let cache = opt_text(args, "cache").unwrap_or(""); + let match_kind = opt_text(args, "match").unwrap_or(""); + + let ep_status = if status == "ok" || status == "success" { + "success" + } else { + "failure" + }; + + let dir = episode_dir(&root); + let (id, path) = next_episode_id(&dir)?; + let ts = now_rfc3339(); + + let mut fm = format!( + "---\ntype: episode\nid: {id}\ntask_hash: {task_hash}\nslug: {slug}\ntimestamp: {ts}\nstatus: {ep_status}\nskill: {}\nmode: {}\nllm_calls: {llm_calls}\ntool_calls: {tool_calls}\ntokens: {tokens}\nlatency_ms: {latency_ms}\n", + yaml_escape(&skill), + yaml_escape(mode), + ); + if !workbook.is_empty() { + fm.push_str(&format!("workbook: {}\n", yaml_escape(workbook))); + } + if !cache.is_empty() { + fm.push_str(&format!("cache: {}\n", yaml_escape(cache))); + } + if !match_kind.is_empty() { + fm.push_str(&format!("match: {}\n", yaml_escape(match_kind))); + } + fm.push_str("---\n\n"); + + let body = format!( + "{fm}{}\n{}\n{}\n{}\n{}\n{}\n{}\n", + section("Task", &task_n), + section("Context", &context), + section("Decisions", &actions), + section("Actions", &actions), + section("Observations", &observations), + section("Result", &result), + section("Verification", &verification), + ); + let body = if errors != "none" && !errors.is_empty() { + format!("{body}\n{}\n", section("Errors", &errors)) + } else { + format!("{body}\n{}\n", section("Errors", "none")) + }; + + fs::write(&path, body).map_err(|e| format!("write episode: {e}"))?; + let rel = path + .strip_prefix(resolve_path(".")) + .unwrap_or(&path) + .to_string_lossy() + .into_owned(); + + Ok(json!({ + "ok": true, + "id": id, + "path": path.to_string_lossy(), + "rel": rel, + "task_hash": task_hash, + "slug": slug, + "status": ep_status, + "mode": mode, + })) +} + +fn extract_fm_field(source: &str, key: &str) -> Option { + let source = source.strip_prefix('\u{feff}').unwrap_or(source); + let lines: Vec<&str> = source.lines().collect(); + if lines.first().map(|l| l.trim()) != Some("---") { + return None; + } + let prefix = format!("{key}:"); + for line in lines.iter().skip(1) { + let t = line.trim(); + if t == "---" { + break; + } + if let Some(rest) = t.strip_prefix(&prefix) { + return Some(rest.trim().trim_matches('"').to_string()); + } + } + None +} + +fn extract_section(source: &str, title: &str) -> String { + let marker = format!("# {title}"); + let mut lines = source.lines(); + while let Some(line) = lines.next() { + if line.trim() == marker { + let mut body = String::new(); + for l in lines.by_ref() { + if l.starts_with("# ") { + break; + } + if !body.is_empty() { + body.push('\n'); + } + body.push_str(l); + } + return body.trim().to_string(); + } + } + String::new() +} + +#[derive(Clone)] +struct EpisodeMeta { + id: String, + path: PathBuf, + task_hash: String, + slug: String, + status: String, + mode: String, + task: String, + result: String, + workbook: String, + llm_calls: i64, + tool_calls: i64, +} + +fn walk_episodes(root: &Path) -> Vec { + let mut out = Vec::new(); + let base = root.join("episodes"); + if !base.is_dir() { + return out; + } + walk_mq(&base, &mut out); + out.sort_by(|a, b| a.id.cmp(&b.id)); + out +} + +fn walk_mq(dir: &Path, out: &mut Vec) { + let Ok(rd) = fs::read_dir(dir) else { + return; + }; + for ent in rd.flatten() { + let p = ent.path(); + if p.is_dir() { + walk_mq(&p, out); + continue; + } + let name = p.file_name().and_then(|n| n.to_str()).unwrap_or(""); + if !name.ends_with(".mq.md") { + continue; + } + let Ok(src) = fs::read_to_string(&p) else { + continue; + }; + if extract_fm_field(&src, "type").as_deref() != Some("episode") { + continue; + } + let id = extract_fm_field(&src, "id").unwrap_or_else(|| name.trim_end_matches(".mq.md").into()); + let task_hash = extract_fm_field(&src, "task_hash").unwrap_or_default(); + let slug = extract_fm_field(&src, "slug").unwrap_or_default(); + let status = extract_fm_field(&src, "status").unwrap_or_default(); + let mode = extract_fm_field(&src, "mode").unwrap_or_default(); + let workbook = extract_fm_field(&src, "workbook").unwrap_or_default(); + let llm_calls = extract_fm_field(&src, "llm_calls") + .and_then(|s| s.parse().ok()) + .unwrap_or(0); + let tool_calls = extract_fm_field(&src, "tool_calls") + .and_then(|s| s.parse().ok()) + .unwrap_or(0); + let task = extract_section(&src, "Task"); + let result = extract_section(&src, "Result"); + out.push(EpisodeMeta { + id, + path: p, + task_hash, + slug, + status, + mode, + task, + result, + workbook, + llm_calls, + tool_calls, + }); + } +} + +/// List episodes, optionally filtered by task / task_hash / status. +pub fn list_episodes(args: &Value) -> Result { + let root = memory_root(args); + ensure_layout(&root)?; + let mut eps = walk_episodes(&root); + if let Some(th) = opt_text(args, "task_hash") { + eps.retain(|e| e.task_hash == th); + } else if let Ok(task) = arg_text(args, "task").or_else(|_| arg_text(args, "goal")) { + let th = goal_sig_hex(&normalize_goal(task)); + eps.retain(|e| e.task_hash == th); + } + if let Some(st) = opt_text(args, "status") { + eps.retain(|e| e.status == st); + } + let limit = opt_i64(args, "limit", 50).max(0) as usize; + let total = eps.len(); + eps.truncate(limit); + let items: Vec = eps + .into_iter() + .map(|e| { + json!({ + "id": e.id, + "path": e.path.to_string_lossy(), + "task_hash": e.task_hash, + "slug": e.slug, + "status": e.status, + "mode": e.mode, + "llm_calls": e.llm_calls, + "tool_calls": e.tool_calls, + }) + }) + .collect(); + Ok(json!({ "count": total, "episodes": items })) +} + +/// Read one episode by id or path. +pub fn get_episode(args: &Value) -> Result { + let root = memory_root(args); + if let Some(path) = opt_text(args, "path") { + let p = resolve_path(path); + let src = fs::read_to_string(&p).map_err(|e| format!("read episode: {e}"))?; + return Ok(json!({ + "ok": true, + "path": p.to_string_lossy(), + "source": src, + "id": extract_fm_field(&src, "id"), + "task_hash": extract_fm_field(&src, "task_hash"), + "status": extract_fm_field(&src, "status"), + "result": extract_section(&src, "Result"), + "task": extract_section(&src, "Task"), + })); + } + let id = arg_text(args, "id")?; + for e in walk_episodes(&root) { + if e.id == id { + let src = fs::read_to_string(&e.path).map_err(|e| format!("read episode: {e}"))?; + return Ok(json!({ + "ok": true, + "path": e.path.to_string_lossy(), + "source": src, + "id": e.id, + "task_hash": e.task_hash, + "status": e.status, + "result": e.result, + "task": e.task, + })); + } + } + Ok(Value::Null) +} + +fn near_score(a: &str, b: &str) -> f64 { + let q = canonicalize_goal_str(a); + let c = canonicalize_goal_str(b); + if q.is_empty() || c.is_empty() { + return 0.0; + } + cosine_tf(&char_bigram_tf(&q), &char_bigram_tf(&c)) +} + +/// Public near-score for Adaptive Routing policy match. +pub(crate) fn task_near_score(a: &str, b: &str) -> f64 { + near_score(a, b) +} + +/// Cheap cluster of episodes by task_hash first, then n-gram near-match (v2 Phase 2). +pub fn cluster_episodes(args: &Value) -> Result { + let root = memory_root(args); + ensure_layout(&root)?; + let threshold = match args.get("threshold") { + Some(Value::Number(n)) => n.as_f64().unwrap_or(0.82), + Some(Value::String(s)) => s.parse().unwrap_or(0.82), + _ => 0.82, + }; + let mut eps = walk_episodes(&root); + if let Ok(task) = arg_text(args, "task").or_else(|_| arg_text(args, "goal")) { + let th = goal_sig_hex(&normalize_goal(task)); + // Prefer same hash; also keep near-hash neighbors via task text. + let task_n = normalize_goal(task); + eps.retain(|e| e.task_hash == th || near_score(&task_n, &e.task) >= threshold); + } + // Group by task_hash. + let mut by_hash: Vec<(String, Vec)> = Vec::new(); + for e in eps { + if let Some((_, g)) = by_hash.iter_mut().find(|(h, _)| *h == e.task_hash) { + g.push(e); + } else { + by_hash.push((e.task_hash.clone(), vec![e])); + } + } + // Merge near groups when representatives are similar. + let mut clusters: Vec> = by_hash.into_iter().map(|(_, g)| g).collect(); + let mut merged = true; + while merged { + merged = false; + 'outer: for i in 0..clusters.len() { + for j in (i + 1)..clusters.len() { + let ai = clusters[i].first().map(|e| e.task.as_str()).unwrap_or(""); + let aj = clusters[j].first().map(|e| e.task.as_str()).unwrap_or(""); + if !ai.is_empty() && !aj.is_empty() && near_score(ai, aj) >= threshold { + let other = clusters.remove(j); + clusters[i].extend(other); + merged = true; + break 'outer; + } + } + } + } + let out: Vec = clusters + .into_iter() + .enumerate() + .map(|(i, g)| { + let ids: Vec = g.iter().map(|e| Value::String(e.id.clone())).collect(); + let sample = g.first().map(|e| e.task.clone()).unwrap_or_default(); + let success = g.iter().filter(|e| e.status == "success").count() as i64; + json!({ + "cluster": format!("cluster-{}", i + 1), + "size": g.len() as i64, + "success": success, + "sample_task": sample, + "task_hash": g.first().map(|e| e.task_hash.clone()).unwrap_or_default(), + "episodes": ids, + }) + }) + .collect(); + Ok(json!({ "count": out.len(), "clusters": out })) +} + +/// Extract a shared pattern from successful episodes (heuristic; no LLM). +pub fn extract_pattern(args: &Value) -> Result { + let root = memory_root(args); + let mut eps = walk_episodes(&root); + if let Ok(task) = arg_text(args, "task").or_else(|_| arg_text(args, "goal")) { + let th = goal_sig_hex(&normalize_goal(task)); + eps.retain(|e| e.task_hash == th); + } else if let Some(th) = opt_text(args, "task_hash") { + eps.retain(|e| e.task_hash == th); + } + eps.retain(|e| e.status == "success"); + if eps.is_empty() { + return Ok(json!({ + "ok": false, + "reason": "no_success_episodes", + })); + } + let results: Vec<&str> = eps.iter().map(|e| e.result.as_str()).collect(); + let same_result = results.iter().all(|r| *r == results[0]) && !results[0].is_empty() && results[0] != "none"; + let workbooks: Vec<&str> = eps + .iter() + .map(|e| e.workbook.as_str()) + .filter(|w| !w.is_empty()) + .collect(); + let avg_llm = { + let n = eps.len() as f64; + eps.iter().map(|e| e.llm_calls as f64).sum::() / n + }; + let steps = if same_result { + vec![ + "Return cached solidified answer".to_string(), + format!("result = {}", results[0]), + ] + } else if !workbooks.is_empty() { + vec![ + "Spawn solidified workbook resource".to_string(), + format!("workbook = {}", workbooks[0]), + ] + } else { + vec!["Replay last successful procedure".to_string()] + }; + Ok(json!({ + "ok": true, + "evidence": eps.len() as i64, + "same_result": same_result, + "result": if same_result { results[0] } else { "" }, + "workbook": workbooks.first().copied().unwrap_or(""), + "avg_llm_calls": avg_llm, + "steps": steps, + "invariants": if same_result { json!(["deterministic_result"]) } else { json!([]) }, + "variables": ["task"], + })) +} + +/// Write an experience note under `experiences/.mq.md`. +pub fn generalize(args: &Value) -> Result { + let root = memory_root(args); + ensure_layout(&root)?; + let pattern = extract_pattern(args)?; + if pattern.get("ok").and_then(|v| v.as_bool()) != Some(true) { + return Ok(pattern); + } + let task = arg_text(args, "task") + .or_else(|_| arg_text(args, "goal")) + .unwrap_or("task"); + let slug = goal_slug_str(task); + let path = root.join("experiences").join(format!("{slug}.mq.md")); + let evidence = pattern.get("evidence").and_then(|v| v.as_i64()).unwrap_or(0); + let steps = pattern + .get("steps") + .and_then(|v| v.as_array()) + .cloned() + .unwrap_or_default(); + let mut steps_md = String::new(); + for (i, s) in steps.iter().enumerate() { + if let Some(t) = s.as_str() { + steps_md.push_str(&format!("{}. {t}\n", i + 1)); + } + } + let ts = now_rfc3339(); + let body = format!( + "---\ntype: experience\nslug: {slug}\nevidence: {evidence}\ntimestamp: {ts}\nstatus: draft\n---\n\n# Experience: {slug}\n\n# Task\n\n{}\n\n# Pattern\n\n{steps_md}\n", + normalize_goal(task), + ); + fs::write(&path, body).map_err(|e| format!("write experience: {e}"))?; + Ok(json!({ + "ok": true, + "slug": slug, + "path": path.to_string_lossy(), + "evidence": evidence, + "pattern": pattern, + })) +} + +fn write_compiled_mq(result: &str, title: &str) -> String { + let lit = marqdo_quoted(result); + format!( + "---\ntitle: {title}\ntype: skill\nstatus: compiled\nllm_free: true\n---\n\nCompiled from successful episodes (deterministic return).\n\n# main\n\n*`result` = {lit} *\n**`result`**\n" + ) +} + +/// Synthesize a candidate skill `.mq.md` from pattern / episodes. +pub fn synthesize_skill(args: &Value) -> Result { + let root = memory_root(args); + ensure_layout(&root)?; + let pattern = extract_pattern(args)?; + if pattern.get("ok").and_then(|v| v.as_bool()) != Some(true) { + return Ok(pattern); + } + let task = arg_text(args, "task") + .or_else(|_| arg_text(args, "goal")) + .unwrap_or("task"); + let slug = goal_slug_str(task); + let cand_dir = root.join("candidates").join(&slug); + fs::create_dir_all(&cand_dir).map_err(|e| format!("mkdir candidates: {e}"))?; + let path = cand_dir.join("candidate.mq.md"); + let evidence = pattern.get("evidence").and_then(|v| v.as_i64()).unwrap_or(0); + let same = pattern.get("same_result").and_then(|v| v.as_bool()).unwrap_or(false); + let result = pattern + .get("result") + .and_then(|v| v.as_str()) + .unwrap_or(""); + let workbook = pattern + .get("workbook") + .and_then(|v| v.as_str()) + .unwrap_or(""); + + let (body, llm_free) = if same && !result.is_empty() && result != "none" { + (write_compiled_mq(result, &slug), true) + } else if !workbook.is_empty() { + let wb_path = resolve_path(workbook); + match fs::read_to_string(&wb_path) { + Ok(src) => { + let lf = !src.contains(".step") + && !src.contains(".单步") + && !src.contains("worker.step"); + (src, lf) + } + Err(_) => ( + format!( + "---\ntitle: {slug}\ntype: skill\nstatus: candidate\nllm_free: false\n---\n\n# main\n\n*\"candidate pending solidify\"*\n" + ), + false, + ), + } + } else { + ( + format!( + "---\ntitle: {slug}\ntype: skill\nstatus: candidate\nllm_free: false\n---\n\n# Purpose\n\nCandidate skill — needs further exploration.\n\n# Main\n\n# main\n\n*\"not yet compiled\"*\n" + ), + false, + ) + }; + fs::write(&path, &body).map_err(|e| format!("write candidate: {e}"))?; + Ok(json!({ + "ok": true, + "slug": slug, + "path": path.to_string_lossy(), + "llm_free": llm_free, + "evidence": evidence, + "status": if llm_free { "compiled" } else { "candidate" }, + })) +} + +/// Validate + compile candidate into `skills//vN.mq.md`, optionally promote to agent-kb. +pub fn compile_skill(args: &Value) -> Result { + let root = memory_root(args); + ensure_layout(&root)?; + let task = arg_text(args, "task") + .or_else(|_| arg_text(args, "goal")) + .unwrap_or("task"); + let slug = opt_text(args, "slug") + .map(|s| s.to_string()) + .unwrap_or_else(|| goal_slug_str(task)); + let cand = opt_text(args, "candidate") + .map(PathBuf::from) + .unwrap_or_else(|| root.join("candidates").join(&slug).join("candidate.mq.md")); + let cand = if cand.is_absolute() { + cand + } else { + resolve_path(&cand.to_string_lossy()) + }; + if !cand.is_file() { + // Try synthesize first. + let syn = synthesize_skill(args)?; + if syn.get("ok").and_then(|v| v.as_bool()) != Some(true) { + return Ok(json!({ + "ok": false, + "reason": "no_candidate", + "synthesize": syn, + })); + } + } + let cand_path = if cand.is_file() { + cand + } else { + root.join("candidates").join(&slug).join("candidate.mq.md") + }; + let src = fs::read_to_string(&cand_path).map_err(|e| format!("read candidate: {e}"))?; + let llm_free = extract_fm_field(&src, "llm_free") + .map(|s| s == "true" || s == "True") + .unwrap_or_else(|| { + !src.contains(".step") && !src.contains(".单步") && !src.contains("worker.step") + }); + if !llm_free && !opt_bool(args, "force", false) { + return Ok(json!({ + "ok": false, + "reason": "not_llm_free", + "slug": slug, + "candidate": cand_path.to_string_lossy(), + })); + } + // Held-out / historical gate: require min evidence unless forced. + let min_evidence = opt_i64(args, "min_evidence", 3); + let pattern = extract_pattern(args)?; + let evidence = pattern.get("evidence").and_then(|v| v.as_i64()).unwrap_or(0); + if evidence < min_evidence && !opt_bool(args, "force", false) { + return Ok(json!({ + "ok": false, + "reason": "insufficient_evidence", + "evidence": evidence, + "min_evidence": min_evidence, + })); + } + + let skill_dir = root.join("skills").join(&slug); + fs::create_dir_all(&skill_dir).map_err(|e| format!("mkdir skills: {e}"))?; + let mut ver = 1i64; + if let Ok(rd) = fs::read_dir(&skill_dir) { + for ent in rd.flatten() { + let name = ent.file_name().to_string_lossy().into_owned(); + if let Some(rest) = name.strip_prefix('v') { + if let Some(num) = rest.strip_suffix(".mq.md") { + if let Ok(n) = num.parse::() { + ver = ver.max(n + 1); + } + } + } + } + } + let out_path = skill_dir.join(format!("v{ver}.mq.md")); + let mut body = src.clone(); + if !body.contains("llm_free:") { + body = body.replacen("---\n", "---\nllm_free: true\nstatus: compiled\n", 1); + } else { + // Force compiled markers. + body = body + .lines() + .map(|l| { + if l.starts_with("status:") { + "status: compiled".to_string() + } else if l.starts_with("llm_free:") { + "llm_free: true".to_string() + } else { + l.to_string() + } + }) + .collect::>() + .join("\n"); + if !body.ends_with('\n') { + body.push('\n'); + } + } + fs::write(&out_path, &body).map_err(|e| format!("write skill: {e}"))?; + // Absolute workbook path so kb_promote's resolve_path does not re-join cwd. + let wb_abs = out_path + .canonicalize() + .unwrap_or_else(|_| std::env::current_dir().unwrap_or_default().join(&out_path)); + + let mut promoted = Value::Null; + if opt_bool(args, "promote", true) { + let kb = opt_text(args, "kb_dir").unwrap_or(DEFAULT_KB_DIR); + let prom_args = json!({ + "kb_dir": kb, + "goal": task, + "workbook": wb_abs.to_string_lossy(), + }); + match crate::kb::kb_promote(&prom_args) { + Ok(p) => promoted = p, + Err(e) => { + return Ok(json!({ + "ok": true, + "compiled": true, + "slug": slug, + "version": ver, + "path": out_path.to_string_lossy(), + "llm_free": true, + "evidence": evidence, + "promote_error": e, + })); + } + } + } + + Ok(json!({ + "ok": true, + "compiled": true, + "slug": slug, + "version": ver, + "path": out_path.to_string_lossy(), + "llm_free": true, + "evidence": evidence, + "promoted": promoted, + })) +} + +/// If enough successful episodes exist, generalize → synthesize → compile (v2 learn loop). +pub fn maybe_learn(args: &Value) -> Result { + let min_evidence = opt_i64(args, "improve_every", opt_i64(args, "min_evidence", 3)); + let root = memory_root(args); + ensure_layout(&root)?; + let mem_arg = opt_text(args, "memory_dir").unwrap_or(DEFAULT_MEMORY_DIR); + let task = match arg_text(args, "task").or_else(|_| arg_text(args, "goal")) { + Ok(t) => t.to_string(), + Err(_) => { + return Ok(json!({ + "learned": false, + "reason": "missing_task", + })); + } + }; + let th = goal_sig_hex(&normalize_goal(&task)); + let eps: Vec<_> = walk_episodes(&root) + .into_iter() + .filter(|e| e.task_hash == th && e.status == "success") + .collect(); + let evidence = eps.len() as i64; + if evidence < min_evidence { + return Ok(json!({ + "learned": false, + "reason": "insufficient_evidence", + "evidence": evidence, + "min_evidence": min_evidence, + "task_hash": th, + })); + } + // Skip if already llm_free in kb. + let kb = opt_text(args, "kb_dir").unwrap_or(DEFAULT_KB_DIR); + let lookup = crate::kb::kb_lookup(&json!({ + "kb_dir": kb, + "goal": task, + "near_match": true, + "near_threshold": 0.78, + })) + .unwrap_or(Value::Null); + if lookup.get("llm_free").and_then(|v| v.as_bool()) == Some(true) { + return Ok(json!({ + "learned": false, + "reason": "already_llm_free", + "evidence": evidence, + "skill": lookup.get("skill").cloned().unwrap_or(Value::Null), + })); + } + + // Pass the original memory_dir string (not resolved root) so nested + // resolve_path does not double-join against host cwd. + let exp = generalize(&json!({ + "memory_dir": mem_arg, + "task": task, + }))?; + let syn = synthesize_skill(&json!({ + "memory_dir": mem_arg, + "task": task, + }))?; + if syn.get("llm_free").and_then(|v| v.as_bool()) != Some(true) + && !opt_bool(args, "force", false) + { + return Ok(json!({ + "learned": false, + "reason": "candidate_not_llm_free", + "evidence": evidence, + "experience": exp, + "candidate": syn, + })); + } + let compiled = compile_skill(&json!({ + "memory_dir": mem_arg, + "task": task, + "kb_dir": kb, + "min_evidence": min_evidence, + "promote": opt_bool(args, "promote", true), + "force": opt_bool(args, "force", false), + }))?; + Ok(json!({ + "learned": compiled.get("ok").and_then(|v| v.as_bool()).unwrap_or(false), + "evidence": evidence, + "experience": exp, + "candidate": syn, + "compile": compiled, + })) +} + +/// Reasoning-amortization metrics over episodes (+ optional kb skill counts). +pub fn metrics(args: &Value) -> Result { + let root = memory_root(args); + ensure_layout(&root)?; + let eps = walk_episodes(&root); + let total = eps.len() as i64; + let success = eps.iter().filter(|e| e.status == "success").count() as i64; + let compiled_runs = eps + .iter() + .filter(|e| e.mode == "compiled" || e.llm_calls == 0) + .count() as i64; + let explore_runs = eps.iter().filter(|e| e.mode == "explore").count() as i64; + let sum_llm: i64 = eps.iter().map(|e| e.llm_calls).sum(); + let sum_tools: i64 = eps.iter().map(|e| e.tool_calls).sum(); + let avg_llm = if total > 0 { + sum_llm as f64 / total as f64 + } else { + 0.0 + }; + let mut by_mode: serde_json::Map = serde_json::Map::new(); + for e in &eps { + let entry = by_mode.entry(e.mode.clone()).or_insert_with(|| { + json!({ "count": 0, "llm_calls": 0 }) + }); + if let Some(obj) = entry.as_object_mut() { + let c = obj.get("count").and_then(|v| v.as_i64()).unwrap_or(0) + 1; + let l = obj.get("llm_calls").and_then(|v| v.as_i64()).unwrap_or(0) + e.llm_calls; + obj.insert("count".into(), json!(c)); + obj.insert("llm_calls".into(), json!(l)); + } + } + Ok(json!({ + "episodes": total, + "success": success, + "compiled_runs": compiled_runs, + "explore_runs": explore_runs, + "llm_calls_total": sum_llm, + "tool_calls_total": sum_tools, + "avg_llm_calls": avg_llm, + "reasoning_amortization": if success > 0 { + sum_llm as f64 / success as f64 + } else { + 0.0 + }, + "by_mode": by_mode, + "memory_dir": root.to_string_lossy(), + })) +} + +/// Resolve task → skill (thin wrapper around kb_lookup with mode labels). +pub fn resolve_task(args: &Value) -> Result { + let kb = opt_text(args, "kb_dir").unwrap_or(DEFAULT_KB_DIR); + let goal = arg_text(args, "task").or_else(|_| arg_text(args, "goal"))?; + let near = opt_bool(args, "near_match", true); + let thr = match args.get("threshold").or_else(|| args.get("near_threshold")) { + Some(Value::Number(n)) => n.as_f64().unwrap_or(0.78), + Some(Value::String(s)) => s.parse().unwrap_or(0.78), + _ => 0.78, + }; + let hit = crate::kb::kb_lookup(&json!({ + "kb_dir": kb, + "goal": goal, + "near_match": near, + "near_threshold": thr, + "tools": args.get("tools").cloned().unwrap_or(Value::Null), + }))?; + if hit.is_null() { + return Ok(json!({ + "mode": "unknown", + "skill": null, + "resource": null, + "confidence": 0.0, + })); + } + let match_kind = hit + .get("match") + .and_then(|v| v.as_str()) + .unwrap_or("exact"); + let llm_free = hit.get("llm_free").and_then(|v| v.as_bool()).unwrap_or(false); + let mode = if llm_free { + "exact" + } else if match_kind == "near" || match_kind == "soft" { + "near" + } else { + match_kind + }; + let confidence = hit + .get("score") + .and_then(|v| v.as_f64()) + .unwrap_or(if llm_free { 0.99 } else { 0.85 }); + Ok(json!({ + "mode": mode, + "match": match_kind, + "skill": hit.get("skill").cloned().unwrap_or(Value::Null), + "resource": hit.get("resource").cloned().unwrap_or(Value::Null), + "slug": hit.get("slug").cloned().unwrap_or(Value::Null), + "status": hit.get("status").cloned().unwrap_or(Value::Null), + "llm_free": llm_free, + "score": hit.get("score").cloned().unwrap_or(Value::Null), + "confidence": confidence, + })) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn record_and_cluster_and_compile() { + let dir = std::env::temp_dir().join(format!( + "marqdo-mem-{}", + std::process::id() + )); + let _ = fs::remove_dir_all(&dir); + fs::create_dir_all(&dir).unwrap(); + let mem = dir.join("agent-memory"); + let kb = dir.join("agent-kb"); + let mem_s = mem.to_string_lossy().into_owned(); + let kb_s = kb.to_string_lossy().into_owned(); + let task = "Reply with exactly the word pong and nothing else."; + for _ in 0..3 { + let out = record_episode(&json!({ + "memory_dir": mem_s, + "task": task, + "status": "ok", + "mode": "explore", + "result": "pong", + "llm_calls": 2, + })) + .unwrap(); + assert_eq!(out.get("ok").and_then(|v| v.as_bool()), Some(true)); + } + let listed = list_episodes(&json!({ + "memory_dir": mem_s, + "task": task, + })) + .unwrap(); + assert_eq!(listed.get("count").and_then(|v| v.as_i64()), Some(3)); + let cl = cluster_episodes(&json!({ + "memory_dir": mem_s, + "task": task, + })) + .unwrap(); + assert!(cl.get("count").and_then(|v| v.as_i64()).unwrap_or(0) >= 1); + let learned = maybe_learn(&json!({ + "memory_dir": mem_s, + "kb_dir": kb_s, + "task": task, + "improve_every": 3, + "promote": true, + })) + .unwrap(); + assert_eq!( + learned.get("learned").and_then(|v| v.as_bool()), + Some(true), + "{learned}" + ); + let m = metrics(&json!({ "memory_dir": mem_s })).unwrap(); + assert_eq!(m.get("episodes").and_then(|v| v.as_i64()), Some(3)); + let _ = fs::remove_dir_all(&dir); + } +} diff --git a/plugins/agent/src/route.rs b/plugins/agent/src/route.rs new file mode 100644 index 0000000..5553ea2 --- /dev/null +++ b/plugins/agent/src/route.rs @@ -0,0 +1,755 @@ +//! Adaptive Routing / Policy Compilation (Phase 4). +//! Router is abstract: marqdo | small-llm | jev | llm | auto — Jev is optional. + +use std::collections::HashMap; +use std::fs; +use std::path::{Path, PathBuf}; + +use serde_json::{json, Value}; + +use crate::kb::{goal_sig_hex, goal_slug_str, normalize_goal}; +use crate::memory::{self}; + +const DEFAULT_MEMORY_DIR: &str = ".marqdo/agent-memory"; +const DEFAULT_KB_DIR: &str = ".marqdo/agent-kb"; +const POLICY_NAME: &str = "router.mq.md"; + +fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> { + args.get(key) + .and_then(|v| v.as_str()) + .ok_or_else(|| format!("missing text `{key}`")) +} + +fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> { + args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty()) +} + +fn opt_i64(args: &Value, key: &str, default: i64) -> i64 { + match args.get(key) { + None | Some(Value::Null) => default, + Some(Value::Number(n)) => n.as_i64().unwrap_or(default), + Some(Value::String(s)) => s.parse().unwrap_or(default), + _ => default, + } +} + +fn opt_f64(args: &Value, key: &str, default: f64) -> f64 { + match args.get(key) { + None | Some(Value::Null) => default, + Some(Value::Number(n)) => n.as_f64().unwrap_or(default), + Some(Value::String(s)) => s.parse().unwrap_or(default), + _ => default, + } +} + +fn opt_bool(args: &Value, key: &str, default: bool) -> bool { + match args.get(key) { + None | Some(Value::Null) => default, + Some(Value::Bool(b)) => *b, + Some(Value::String(s)) => matches!(s.as_str(), "true" | "True" | "1" | "yes"), + Some(Value::Number(n)) => n.as_i64().unwrap_or(0) != 0, + _ => default, + } +} + +fn now_rfc3339() -> String { + chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true) +} + +fn yaml_escape(s: &str) -> String { + if s.is_empty() + || s.contains(':') + || s.contains('#') + || s.contains('|') + || s.contains('"') + || s.contains('\n') + { + format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\"")) + } else { + s.to_string() + } +} + +fn resolve_path(rel: &str) -> PathBuf { + let p = PathBuf::from(rel); + if p.is_absolute() { + return p; + } + if p.exists() { + return p; + } + let base = (|| { + let q = crate::host_query_json("cwd")?; + q.as_str() + .map(PathBuf::from) + .ok_or_else(|| "cwd not text".to_string()) + })() + .or_else(|_| std::env::current_dir().map_err(|e| e.to_string())) + .unwrap_or_else(|_| PathBuf::from(".")); + base.join(p) +} + +fn memory_root(args: &Value) -> PathBuf { + let rel = opt_text(args, "memory_dir").unwrap_or(DEFAULT_MEMORY_DIR); + resolve_path(rel) +} + +fn policy_path(root: &Path) -> PathBuf { + root.join("policies").join(POLICY_NAME) +} + +#[derive(Clone, Debug)] +struct PolicyRule { + task_hash: String, + slug: String, + skill: String, + task: String, + count: i64, + confidence: f64, +} + +fn parse_policy(src: &str) -> Vec { + let mut rules = Vec::new(); + let mut in_table = false; + let mut header_ok = false; + for line in src.lines() { + let t = line.trim(); + if t.starts_with("|") && t.contains("task_hash") { + in_table = true; + header_ok = true; + continue; + } + if in_table && t.starts_with("|") && t.contains("---") { + continue; + } + if in_table && t.starts_with("|") { + let cols: Vec<&str> = t + .trim_matches('|') + .split('|') + .map(|c| c.trim().trim_matches('"')) + .collect(); + if cols.len() >= 5 { + let count = cols[4].parse().unwrap_or(1); + let confidence = if cols.len() >= 6 { + cols[5].parse().unwrap_or(0.9) + } else { + 0.9 + }; + let task = if cols.len() >= 7 { + cols[6].to_string() + } else { + String::new() + }; + rules.push(PolicyRule { + task_hash: cols[0].to_string(), + slug: cols[1].to_string(), + skill: cols[2].to_string(), + count, + confidence, + task, + }); + } + continue; + } + if in_table && header_ok && !t.starts_with('|') && !t.is_empty() { + break; + } + } + rules +} + +fn write_policy(root: &Path, rules: &[PolicyRule]) -> Result { + fs::create_dir_all(root.join("policies")).map_err(|e| format!("mkdir policies: {e}"))?; + let path = policy_path(root); + let ts = now_rfc3339(); + let mut body = format!( + "---\ntype: policy\nstatus: compiled\nbackend: marqdo\ngenerated_at: {ts}\nrules: {}\n---\n\n# Adaptive router (compiled Marqdo policy)\n\nDeterministic task → skill routing. No LLM required.\n\n# Rules\n\n| task_hash | slug | skill | resource | count | confidence | task |\n|-----------|------|-------|----------|------:|-----------:|------|\n", + rules.len() + ); + for r in rules { + body.push_str(&format!( + "| {} | {} | {} | {} | {} | {:.2} | {} |\n", + r.task_hash, + yaml_escape(&r.slug), + yaml_escape(&r.skill), + yaml_escape(&r.skill), // resource often == skill path for OKF + r.count, + r.confidence, + yaml_escape(&r.task), + )); + } + body.push_str("\n# Fallback\n\nllm\n"); + fs::write(&path, body).map_err(|e| format!("write policy: {e}"))?; + Ok(path) +} + +fn load_rules(root: &Path) -> Vec { + let path = policy_path(root); + let Ok(src) = fs::read_to_string(&path) else { + return Vec::new(); + }; + parse_policy(&src) +} + +fn match_policy(rules: &[PolicyRule], task: &str, threshold: f64) -> Option { + let th = goal_sig_hex(&normalize_goal(task)); + if let Some(r) = rules.iter().find(|r| r.task_hash == th) { + return Some(r.clone()); + } + // Near-match on stored task text / slug. + let mut best: Option<(f64, PolicyRule)> = None; + for r in rules { + let score = memory::task_near_score(task, &r.task); + if score >= threshold { + if best.as_ref().map(|(s, _)| score > *s).unwrap_or(true) { + best = Some((score, r.clone())); + } + } + let slug_score = memory::task_near_score(task, &r.slug); + if slug_score >= threshold { + if best.as_ref().map(|(s, _)| slug_score > *s).unwrap_or(true) { + let mut rr = r.clone(); + rr.confidence = slug_score; + best = Some((slug_score, rr)); + } + } + } + best.map(|(s, mut r)| { + r.confidence = s; + r + }) +} + +fn jev_available() -> bool { + if let Ok(p) = std::env::var("MARQDO_JEV") { + if !p.is_empty() && p != "0" && p != "false" { + return PathBuf::from(&p).is_file() || p == "1" || p == "true"; + } + } + false +} + +fn build_route_prompt(task: &str, candidates: &[Value]) -> String { + let mut s = String::from( + "You are a Marqdo Agent router. Pick the best skill slug for the task, or say EXPLORE.\n\nReply with exactly one line:\nSKILL:\nor\nEXPLORE\n\nTask:\n", + ); + s.push_str(task); + s.push_str("\n\nCandidates:\n"); + for (i, c) in candidates.iter().enumerate() { + let slug = c + .get("slug") + .or_else(|| c.get("title")) + .and_then(|v| v.as_str()) + .unwrap_or("?"); + let title = c + .get("title") + .or_else(|| c.get("goal")) + .and_then(|v| v.as_str()) + .unwrap_or(""); + s.push_str(&format!("{}. {slug} — {title}\n", i + 1)); + } + s +} + +fn candidate_list(args: &Value) -> Result, String> { + if let Some(Value::Array(items)) = args.get("candidates") { + return Ok(items.clone()); + } + let kb = opt_text(args, "kb_dir").unwrap_or(DEFAULT_KB_DIR); + let listed = crate::kb::kb_list_tasks(&json!({ "kb_dir": kb }))?; + let tasks = listed + .get("tasks") + .and_then(|v| v.as_array()) + .cloned() + .unwrap_or_default(); + if !tasks.is_empty() { + return Ok(tasks); + } + let goal = arg_text(args, "task").or_else(|_| arg_text(args, "goal"))?; + let near = crate::kb::kb_near_match(&json!({ + "kb_dir": kb, + "goal": goal, + }))?; + Ok(near + .get("candidates") + .and_then(|v| v.as_array()) + .cloned() + .unwrap_or_default()) +} + +fn enrich_with_kb(rule: &PolicyRule, kb: &str, task: &str) -> Result { + let hit = crate::kb::kb_lookup(&json!({ + "kb_dir": kb, + "goal": task, + "slug": rule.slug, + "near_match": true, + "near_threshold": 0.5, + })) + .unwrap_or(Value::Null); + let resource = hit + .get("resource") + .cloned() + .unwrap_or_else(|| Value::String(rule.skill.clone())); + let skill = hit + .get("skill") + .cloned() + .unwrap_or_else(|| Value::String(rule.skill.clone())); + let llm_free = hit + .get("llm_free") + .and_then(|v| v.as_bool()) + .unwrap_or(true); + Ok(json!({ + "backend": "marqdo", + "mode": "policy", + "matched": true, + "needs_llm": false, + "slug": rule.slug, + "skill": skill, + "resource": resource, + "task_hash": rule.task_hash, + "confidence": rule.confidence, + "llm_free": llm_free, + "count": rule.count, + })) +} + +fn route_marqdo(args: &Value) -> Result { + let root = memory_root(args); + let _ = memory::memory_ensure(&json!({ + "memory_dir": opt_text(args, "memory_dir").unwrap_or(DEFAULT_MEMORY_DIR), + })); + let task = arg_text(args, "task").or_else(|_| arg_text(args, "goal"))?; + let threshold = opt_f64(args, "threshold", 0.78); + let kb = opt_text(args, "kb_dir").unwrap_or(DEFAULT_KB_DIR); + let rules = load_rules(&root); + if let Some(rule) = match_policy(&rules, task, threshold) { + if rule.confidence >= threshold { + return enrich_with_kb(&rule, kb, task); + } + } + Ok(json!({ + "backend": "marqdo", + "mode": "miss", + "matched": false, + "needs_llm": false, + "confidence": 0.0, + })) +} + +fn route_resolve_fallback(args: &Value) -> Result { + let resolved = memory::resolve_task(args)?; + let conf = resolved + .get("confidence") + .and_then(|v| v.as_f64()) + .unwrap_or(0.0); + let llm_free = resolved + .get("llm_free") + .and_then(|v| v.as_bool()) + .unwrap_or(false); + if conf >= opt_f64(args, "threshold", 0.78) || llm_free { + return Ok(json!({ + "backend": "kb", + "mode": resolved.get("mode").cloned().unwrap_or(Value::String("near".into())), + "matched": true, + "needs_llm": false, + "slug": resolved.get("slug").cloned().unwrap_or(Value::Null), + "skill": resolved.get("skill").cloned().unwrap_or(Value::Null), + "resource": resolved.get("resource").cloned().unwrap_or(Value::Null), + "confidence": conf, + "llm_free": llm_free, + })); + } + Ok(json!({ + "backend": "kb", + "mode": "miss", + "matched": false, + "needs_llm": false, + "confidence": conf, + "resolve": resolved, + })) +} + +fn route_model_request(args: &Value, level: &str) -> Result { + let task = arg_text(args, "task").or_else(|_| arg_text(args, "goal"))?; + let cands = candidate_list(args)?; + let prompt = build_route_prompt(task, &cands); + Ok(json!({ + "backend": level, + "mode": "needs_llm", + "matched": false, + "needs_llm": true, + "level": level, + "prompt": prompt, + "candidates": cands, + "confidence": 0.0, + })) +} + +fn route_jev(args: &Value) -> Result { + if !jev_available() { + return Ok(json!({ + "backend": "jev", + "mode": "unavailable", + "matched": false, + "needs_llm": false, + "confidence": 0.0, + "reason": "jev_not_configured", + })); + } + // Optional external binary path; without a stable Jev ABI we surface a model-shaped request + // so callers can treat Jev like a decision engine when wired later. + route_model_request(args, "jev") +} + +/// Cascade Adaptive Router (Phase 4). +/// +/// `backend`: `auto` | `marqdo` | `small-llm` | `jev` | `llm` +/// +/// `auto` order: marqdo policy → kb resolve → (optional jev) → small-llm request → llm request. +pub fn route(args: &Value) -> Result { + let backend = opt_text(args, "backend").unwrap_or("auto"); + let threshold = opt_f64(args, "threshold", 0.78); + + match backend { + "marqdo" => { + let hit = route_marqdo(args)?; + if hit.get("matched").and_then(|v| v.as_bool()) == Some(true) { + return Ok(hit); + } + route_resolve_fallback(args) + } + "small-llm" | "small_llm" | "small" => route_model_request(args, "small-llm"), + "llm" | "large" | "large-llm" => route_model_request(args, "llm"), + "jev" => route_jev(args), + "auto" | _ => { + let mut trace: Vec = Vec::new(); + let m = route_marqdo(args)?; + trace.push(json!({"try": "marqdo", "matched": m.get("matched")})); + if m.get("matched").and_then(|v| v.as_bool()) == Some(true) + && m.get("confidence").and_then(|v| v.as_f64()).unwrap_or(0.0) >= threshold + { + let mut out = m; + if let Some(obj) = out.as_object_mut() { + obj.insert("trace".into(), Value::Array(trace)); + obj.insert("backend".into(), Value::String("auto/marqdo".into())); + } + return Ok(out); + } + let kb = route_resolve_fallback(args)?; + trace.push(json!({"try": "kb", "matched": kb.get("matched")})); + if kb.get("matched").and_then(|v| v.as_bool()) == Some(true) { + let mut out = kb; + if let Some(obj) = out.as_object_mut() { + obj.insert("trace".into(), Value::Array(trace)); + obj.insert("backend".into(), Value::String("auto/kb".into())); + } + return Ok(out); + } + if jev_available() { + let j = route_jev(args)?; + trace.push(json!({"try": "jev", "mode": j.get("mode")})); + if j.get("needs_llm").and_then(|v| v.as_bool()) == Some(true) { + let mut out = j; + if let Some(obj) = out.as_object_mut() { + obj.insert("trace".into(), Value::Array(trace)); + } + return Ok(out); + } + } + // Prefer small-llm request in auto when nothing matched (caller may use large). + let mut req = route_model_request(args, "small-llm")?; + if let Some(obj) = req.as_object_mut() { + obj.insert("trace".into(), Value::Array(trace)); + obj.insert("backend".into(), Value::String("auto/small-llm".into())); + } + Ok(req) + } + } +} + +/// Apply a router model reply (`SKILL:` / `EXPLORE`) to a concrete skill hit. +pub fn route_apply(args: &Value) -> Result { + let reply = arg_text(args, "reply")?; + let kb = opt_text(args, "kb_dir").unwrap_or(DEFAULT_KB_DIR); + let task = arg_text(args, "task").or_else(|_| arg_text(args, "goal"))?; + let line = reply + .lines() + .map(|l| l.trim()) + .find(|l| !l.is_empty()) + .unwrap_or(""); + let upper = line.to_ascii_uppercase(); + if upper.starts_with("EXPLORE") || upper == "LLM" || upper == "NEW" { + return Ok(json!({ + "matched": false, + "mode": "explore", + "decision": "EXPLORE", + "needs_llm": false, + })); + } + let slug = if let Some(rest) = line.strip_prefix("SKILL:") { + rest.trim() + } else if let Some(rest) = line.strip_prefix("skill:") { + rest.trim() + } else if let Some(rest) = line.strip_prefix("调用:") { + rest.trim() + } else { + line.trim() + }; + if slug.is_empty() { + return Ok(json!({ + "matched": false, + "mode": "explore", + "decision": "EXPLORE", + "reason": "empty_slug", + })); + } + let hit = crate::kb::kb_lookup(&json!({ + "kb_dir": kb, + "goal": task, + "slug": slug, + "near_match": true, + "near_threshold": 0.5, + }))?; + if hit.is_null() { + return Ok(json!({ + "matched": false, + "mode": "miss", + "decision": "SKILL", + "slug": slug, + "reason": "slug_not_in_kb", + })); + } + Ok(json!({ + "matched": true, + "mode": "routed", + "decision": "SKILL", + "backend": opt_text(args, "backend").unwrap_or("llm"), + "slug": slug, + "skill": hit.get("skill").cloned().unwrap_or(Value::Null), + "resource": hit.get("resource").cloned().unwrap_or(Value::Null), + "llm_free": hit.get("llm_free").cloned().unwrap_or(Value::Bool(false)), + "confidence": 0.85, + "needs_llm": false, + })) +} + +/// Compile policy from successful episode skill selections (Policy Compilation). +pub fn compile_policy(args: &Value) -> Result { + let root = memory_root(args); + let mem_arg = opt_text(args, "memory_dir").unwrap_or(DEFAULT_MEMORY_DIR); + let _ = memory::memory_ensure(&json!({ "memory_dir": mem_arg })); + let min_evidence = opt_i64(args, "min_evidence", opt_i64(args, "improve_every", 3)); + let listed = memory::list_episodes(&json!({ + "memory_dir": mem_arg, + "status": "success", + "limit": 500, + }))?; + let eps = listed + .get("episodes") + .and_then(|v| v.as_array()) + .cloned() + .unwrap_or_default(); + + // task_hash → (slug → count, sample task, skill path) + let mut by_hash: HashMap> = HashMap::new(); + for e in &eps { + let id = e.get("id").and_then(|v| v.as_str()).unwrap_or(""); + if id.is_empty() { + continue; + } + let full = memory::get_episode(&json!({ + "memory_dir": mem_arg, + "id": id, + }))?; + if full.is_null() { + continue; + } + let src = full.get("source").and_then(|v| v.as_str()).unwrap_or(""); + let skill = extract_fm(src, "skill").unwrap_or_default(); + if skill.is_empty() || skill == "none" || skill == "null" { + continue; + } + let task_hash = extract_fm(src, "task_hash") + .or_else(|| e.get("task_hash").and_then(|v| v.as_str()).map(|s| s.to_string())) + .unwrap_or_default(); + if task_hash.is_empty() { + continue; + } + let task = full + .get("task") + .and_then(|v| v.as_str()) + .unwrap_or("") + .to_string(); + let slug = extract_fm(src, "slug") + .filter(|s| !s.is_empty()) + .unwrap_or_else(|| goal_slug_str(&task)); + // Prefer skill path as key when it looks like a path; else slug. + let key = if skill.contains('/') || skill.ends_with(".md") { + skill.clone() + } else { + slug.clone() + }; + let entry = by_hash.entry(task_hash).or_default(); + let cell = entry.entry(key).or_insert((0, task, skill)); + cell.0 += 1; + } + + let mut rules: Vec = Vec::new(); + for (task_hash, skills) in by_hash { + let Some((skill_key, (count, task, skill_path))) = + skills.into_iter().max_by_key(|(_, (c, _, _))| *c) + else { + continue; + }; + if count < min_evidence { + continue; + } + let slug = if skill_key.contains('/') { + Path::new(&skill_key) + .file_stem() + .and_then(|s| s.to_str()) + .unwrap_or(&skill_key) + .trim_end_matches(".mq") + .to_string() + } else { + skill_key + }; + let confidence = (count as f64 / (count as f64 + 1.0)).min(0.99); + rules.push(PolicyRule { + task_hash, + slug, + skill: skill_path, + task, + count, + confidence, + }); + } + rules.sort_by(|a, b| b.count.cmp(&a.count)); + + if rules.is_empty() && !opt_bool(args, "force", false) { + return Ok(json!({ + "ok": false, + "compiled": false, + "reason": "insufficient_stable_mappings", + "min_evidence": min_evidence, + })); + } + + let path = write_policy(&root, &rules)?; + Ok(json!({ + "ok": true, + "compiled": true, + "path": path.to_string_lossy(), + "rules": rules.len() as i64, + "min_evidence": min_evidence, + })) +} + +fn extract_fm(source: &str, key: &str) -> Option { + let source = source.strip_prefix('\u{feff}').unwrap_or(source); + let lines: Vec<&str> = source.lines().collect(); + if lines.first().map(|l| l.trim()) != Some("---") { + return None; + } + let prefix = format!("{key}:"); + for line in lines.iter().skip(1) { + let t = line.trim(); + if t == "---" { + break; + } + if let Some(rest) = t.strip_prefix(&prefix) { + return Some(rest.trim().trim_matches('"').to_string()); + } + } + None +} + +/// Learn gate for policy: compile when enough skill-tagged episodes exist. +pub fn maybe_compile_policy(args: &Value) -> Result { + let compiled = compile_policy(args)?; + Ok(json!({ + "policy_learned": compiled.get("ok").and_then(|v| v.as_bool()).unwrap_or(false), + "compile": compiled, + })) +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + #[test] + fn compile_and_route_marqdo() { + let dir = std::env::temp_dir().join(format!("marqdo-route-{}", std::process::id())); + let _ = fs::remove_dir_all(&dir); + fs::create_dir_all(&dir).unwrap(); + let mem = dir.join("agent-memory"); + let kb = dir.join("agent-kb"); + let mem_s = mem.to_string_lossy().into_owned(); + let kb_s = kb.to_string_lossy().into_owned(); + let task = "Reply with exactly the word pong and nothing else."; + + // Seed a solidified skill via memory compile path. + for _ in 0..3 { + memory::record_episode(&json!({ + "memory_dir": mem_s, + "task": task, + "status": "ok", + "mode": "explore", + "result": "pong", + "skill": "concepts/skills/reply-with-exactly-the-word-pong-and-nothing-els.md", + "llm_calls": 1, + })) + .unwrap(); + } + let learned = memory::maybe_learn(&json!({ + "memory_dir": mem_s, + "kb_dir": kb_s, + "task": task, + "improve_every": 3, + "promote": true, + })) + .unwrap(); + assert_eq!(learned.get("learned").and_then(|v| v.as_bool()), Some(true)); + + // Tag episodes with skill path for policy mining (re-record with skill). + for _ in 0..3 { + memory::record_episode(&json!({ + "memory_dir": mem_s, + "task": task, + "status": "ok", + "mode": "compiled", + "result": "pong", + "skill": "concepts/skills/reply-with-exactly-the-word-pong-and-nothing-els.md", + "llm_calls": 0, + })) + .unwrap(); + } + + let pol = compile_policy(&json!({ + "memory_dir": mem_s, + "min_evidence": 3, + })) + .unwrap(); + assert_eq!(pol.get("ok").and_then(|v| v.as_bool()), Some(true), "{pol}"); + + let routed = route(&json!({ + "memory_dir": mem_s, + "kb_dir": kb_s, + "task": task, + "backend": "auto", + })) + .unwrap(); + assert_eq!( + routed.get("matched").and_then(|v| v.as_bool()), + Some(true), + "{routed}" + ); + assert_eq!( + routed.get("needs_llm").and_then(|v| v.as_bool()), + Some(false), + "{routed}" + ); + let _ = fs::remove_dir_all(&dir); + } +} diff --git a/scripts/agent-harness.sh b/scripts/agent-harness.sh index b98c1b4..6ec127f 100755 --- a/scripts/agent-harness.sh +++ b/scripts/agent-harness.sh @@ -28,6 +28,8 @@ run tests/ext/agent-writeback-shadow.mq.md run tests/ext/agent-kb-plan-hit.mq.md run tests/ext/agent-context-budget-a3.mq.md run tests/ext/agent-workbook-patch-a0.mq.md +run tests/ext/agent-v2-learn.mq.md +run tests/ext/agent-p4-route.mq.md run examples/agent-okf-flywheel/index.mq.md run examples/agent-pong/index.mq.md diff --git a/tests/ext/agent-p4-route.mq.md b/tests/ext/agent-p4-route.mq.md new file mode 100644 index 0000000..be5f6ec --- /dev/null +++ b/tests/ext/agent-p4-route.mq.md @@ -0,0 +1,60 @@ +--- +title: Agent Framework P4 — Adaptive Routing + Policy Compilation (offline) +description: Learn skill, compile policy from skill-tagged episodes, route via marqdo backend without Jev/LLM. +import json:lib/json.mq.md +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +--- + +# main + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=no-agent-plugin + > sys.exit code=1 + +**paths = > json.parse text={"mem":".marqdo/agent-memory-p4-test","kb":".marqdo/agent-kb-p4-test","task":"Reply with exactly the word pong and nothing else.","skill":"concepts/skills/reply-with-exactly-the-word-pong-and-nothing-els.md"}** +**mem = > json.get value=`paths` key="mem"** +**kb = > json.get value=`paths` key="kb"** +**task = > json.get value=`paths` key="task"** +**skill = > json.get value=`paths` key="skill"** + +> agent_memory_ensure memory_dir=`mem` + +**ep1 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=2 memory_dir=`mem`** +**ep2 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=2 memory_dir=`mem`** +**ep3 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=2 memory_dir=`mem`** + +**learned = > agent_maybe_learn task=`task` memory_dir=`mem` kb_dir=`kb` improve_every=3 promote=True** +**did = > json.get value=`learned` key="learned"** +1. `did` + > print text=skill-learned +2. * + > print text=skill-skip + +**ep4 = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 memory_dir=`mem`** +**ep5 = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 memory_dir=`mem`** +**ep6 = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 memory_dir=`mem`** + +**pol = > agent_compile_policy memory_dir=`mem` min_evidence=3** +**pok = > json.get value=`pol` key="ok"** +1. `pok` + > print text=policy-ok +2. * + > print text=policy-fail + +**routed = > agent_route task=`task` backend="auto" memory_dir=`mem` kb_dir=`kb`** +**matched = > json.get value=`routed` key="matched"** +**needs = > json.get value=`routed` key="needs_llm"** +1. `matched` + 1. not `needs` + > print text=route-hit + 2. * + > print text=route-needs-llm +2. * + > print text=route-miss + +**backend = > json.get value=`routed` key="backend"** +> print text=`backend` diff --git a/tests/ext/agent-v2-learn.mq.md b/tests/ext/agent-v2-learn.mq.md new file mode 100644 index 0000000..da21e56 --- /dev/null +++ b/tests/ext/agent-v2-learn.mq.md @@ -0,0 +1,56 @@ +--- +title: Agent Framework v2 — episode → learn → compile (offline) +description: Record three identical successes, maybe_learn compiles llm_free skill, resolve hits compiled path. +import agent:ext/ai/agent.mq.md +import fs:lib/fs.mq.md +import json:lib/json.mq.md +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +--- + +# main + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=no-agent-plugin + > sys.exit code=1 + +**paths = > json.parse text={"mem":".marqdo/agent-memory-v2-test","kb":".marqdo/agent-kb-v2-test","task":"Reply with exactly the word pong and nothing else."}** +**mem = > json.get value=`paths` key="mem"** +**kb = > json.get value=`paths` key="kb"** +**task = > json.get value=`paths` key="task"** + +> agent_memory_ensure memory_dir=`mem` + +**ep1 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" llm_calls=2 memory_dir=`mem`** +**ep2 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" llm_calls=2 memory_dir=`mem`** +**ep3 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" llm_calls=2 memory_dir=`mem`** +**ok = > json.get value=`ep3` key="ok"** +1. `ok` + > print text=ep-ok +2. * + > print text=ep-fail + +**listed = > agent_list_episodes memory_dir=`mem` task=`task`** +**n = > json.get value=`listed` key="count"** +> print text=`n` + +**learned = > agent_maybe_learn task=`task` memory_dir=`mem` kb_dir=`kb` improve_every=3 promote=True** +**did = > json.get value=`learned` key="learned"** +1. `did` + > print text=learned +2. * + > print text=learn-skip + +**resolved = > agent_resolve task=`task` kb_dir=`kb`** +**lf = > json.get value=`resolved` key="llm_free"** +1. `lf` + > print text=llm-free +2. * + > print text=not-free + +**m = > agent_metrics memory_dir=`mem`** +**eps = > json.get value=`m` key="episodes"** +> print text=`eps` diff --git a/tests/gold.rs b/tests/gold.rs index 8d4700e..9e8c554 100644 --- a/tests/gold.rs +++ b/tests/gold.rs @@ -96,6 +96,50 @@ fn ensure_web_plugin_built() { } +/// Build `libagent` once per test process and prefer it over a stale `~/.marqdo/ext`. +fn ensure_agent_plugin_built() { + use std::sync::Once; + static ONCE: Once = Once::new(); + ONCE.call_once(|| { + let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")); + let status = Command::new("cargo") + .args(["build", "-p", "marqdo_plugin_agent"]) + .current_dir(&root) + .status() + .expect("build marqdo_plugin_agent"); + assert!(status.success(), "failed to build marqdo_plugin_agent"); + let lib = if cfg!(windows) { + root.join("target").join("debug").join("agent.dll") + } else if cfg!(target_os = "macos") { + root.join("target").join("debug").join("libagent.dylib") + } else { + root.join("target").join("debug").join("libagent.so") + }; + // Prefer release if newer / present (local `cargo build --release -p …`). + let release = if cfg!(windows) { + root.join("target").join("release").join("agent.dll") + } else if cfg!(target_os = "macos") { + root.join("target").join("release").join("libagent.dylib") + } else { + root.join("target").join("release").join("libagent.so") + }; + let chosen = if release.is_file() { + release + } else { + lib + }; + assert!(chosen.is_file(), "missing agent plugin at {}", chosen.display()); + // SAFETY: single-threaded Once; children inherit for the rest of the test process. + std::env::set_var("MARQDO_AGENT_PLUGIN", &chosen); + if std::env::var_os("MARQDO_EXT").is_none() { + let ext = root.join("ext"); + if ext.join("ai").join("agent.mq.md").is_file() { + std::env::set_var("MARQDO_EXT", &ext); + } + } + }); +} + /// Assert failure with `path:line:col:` prefix and message substring (both backends). fn assert_err(path: &str, line_col: &str, substr: &str) { for backend in ["tree", "bytecode"] { @@ -3733,6 +3777,31 @@ callable-ok", ); } +#[test] +fn ext_agent_v2_learn() { + ensure_agent_plugin_built(); + assert_out( + "tests/ext/agent-v2-learn.mq.md", + "ep-ok +3 +learned +llm-free +3", + ); +} + +#[test] +fn ext_agent_p4_route() { + ensure_agent_plugin_built(); + assert_out( + "tests/ext/agent-p4-route.mq.md", + "skill-learned +policy-ok +route-hit +auto/marqdo", + ); +} + #[test] fn lib_net_encode() { assert_out("tests/lib/net-encode.mq.md", "a%20b");