feat(agent): Skill Compilation + Adaptive Routing (v2/P4)
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 <cursoragent@cursor.com>
This commit is contained in:
1 parent
8489d90926
commit
a9ee858f53
14 files changed
+5785
-7
No files matched your search
@@ -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)
|
||||
|
||||
|
||||
@@ -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:<slug>` / `EXPLORE`)落到 kb 技能 |
|
||||
| `## 编译策略` | `## compile_policy` | Policy Compilation → `policies/router.mq.md` |
|
||||
| `## 记录情景` | `## record_episode` | 每次执行沉淀为 `.mq.md` episode(`.marqdo/agent-memory/`) |
|
||||
| `## 尝试学习` | `## maybe_learn` | 情景足够时归纳 → 合成 → 编译技能,并尝试编译策略 |
|
||||
| `## 编译` | `## compile` | 候选技能 → 版本化 `skills/<slug>/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):
|
||||
|
||||
| 参数 | 说明 |
|
||||
|
||||
+2626
File diff suppressed because it is too large.
Load diff
+541
@@ -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** 路线。
|
||||
@@ -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)。
|
||||
+303
-1
@@ -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:<slug>` / `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/<slug>/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
|
||||
|
||||
+110
-1
@@ -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=`强制`*
|
||||
+107
-1
@@ -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
|
||||
}
|
||||
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -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<PolicyRule> {
|
||||
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<PathBuf, String> {
|
||||
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<PolicyRule> {
|
||||
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<PolicyRule> {
|
||||
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:<slug>\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<Vec<Value>, 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<Value, String> {
|
||||
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<Value, String> {
|
||||
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<Value, String> {
|
||||
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<Value, String> {
|
||||
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<Value, String> {
|
||||
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<Value, String> {
|
||||
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<Value> = 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:<slug>` / `EXPLORE`) to a concrete skill hit.
|
||||
pub fn route_apply(args: &Value) -> Result<Value, String> {
|
||||
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<Value, String> {
|
||||
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<String, HashMap<String, (i64, String, String)>> = 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<PolicyRule> = 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<String> {
|
||||
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<Value, String> {
|
||||
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);
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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`
|
||||
@@ -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`
|
||||
@@ -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");
|
||||
|
||||
Reference in new issue
Block a user