Files
marqdo/doc/next/003.md
cflmyandCursor a9ee858f53 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>
2026-09-24 13:28:50 +08:00

2627 lines
33 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
可以。基于你现在的 `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/<slug>.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/<slug>.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/<slug>.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/<slug>.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` 的实际格式。这样就可以直接进入实现,而不是停留在架构层。