Files
marqdo/doc/next/003.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

33 KiB
Executable File
Raw Blame History

可以。基于你现在的 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 不应该只是:

Task
 ↓
LLM
 ↓
Tool
 ↓
Answer

而应该变成:

                 ┌─────────────────────┐
                 │      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

解决当前任务:

Resolve → Execute → Verify → Return

Offline / Background

从历史经验中学习:

Collect → Cluster → Generalize → Validate → Compile

这是整个设计最重要的结构。


2. Agent 的四种“记忆”

我建议不要把所有东西都叫 Memory。

实际上应该有四层。

2.1 Episode Memory

记录:

“这一次具体发生了什么?”

例如:

episode/
    20260924-001.mq.md
    20260924-002.mq.md
    20260924-003.mq.md

它是情景记忆。

记录:

task
context
decision
actions
tool_calls
observations
errors
result
verification
cost

它不需要漂亮,也不需要高度抽象。


3. Experience Memory

Episode 多了以后,系统开始发现:

Episode 1
Episode 2
Episode 3
Episode 4
     ↓
这些任务其实属于同一个模式

于是形成:

experience/<slug>.mq.md

例如:

experience/
    extract-json-from-response.mq.md
    search-local-corpus.mq.md
    repair-invalid-json.mq.md

Experience 是:

多次执行中发现的稳定模式。


4. Skill Memory

Experience 进一步经过验证以后,变成:

skills/<slug>.mq.md

这个文件已经不是“记录”。

它是:

可以直接执行的程序。

例如:

---
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,但可以让一个小模型决定:

if task.kind == "json":
    use json-repair
elif task.kind == "search":
    use corpus-search
else:
    use llm

于是形成:

policy/
    router.mq.md
    json-router.mq.md

所以最终可以形成:

Episode
   ↓
Experience
   ↓
Skill
   ↓
Policy

6. Agent 的核心状态机

我建议 Agent 明确定义以下状态:

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 从现在的:

agent.plan(goal)

逐渐扩展成:

agent.run(task)
agent.learn(task)
agent.compile(skill)
agent.verify(skill)
agent.inspect(task)
agent.forget(skill)

核心接口:

## run
    + `task`
    + `context`=None
    + `mode`=auto
    + `budget`=None
    + `learn`=True
    + `verify`=True

语义:

run()
    ↓
resolve()
    ↓
execute()
    ↓
verify()
    ↓
record_episode()
    ↓
maybe_learn()

8. agent.run

这是用户唯一需要经常调用的接口。

*> agent.run task=`task`*

返回:

{
  "status": "ok",
  "result": "...",

  "execution": {
    "mode": "compiled",
    "skill": "json-repair",
    "llm_calls": 0,
    "tool_calls": 1
  },

  "learning": {
    "episode": "...",
    "skill_updated": false
  }
}

或者第一次:

{
  "status": "ok",
  "result": "...",

  "execution": {
    "mode": "explore",
    "llm_calls": 5
  },

  "learning": {
    "episode": "episode-001",
    "candidate": "json-repair"
  }
}

9. agent.step

你现在的 step 应该保留。

它是 Agent 最基础的 primitive。

当前 step 已经承担:

context assembly
→ LLM
→ READ
→ CALL
→ history
→ writeback

这正适合作为底层执行单元。

建议正式定义:

## step
    + `task`
    + `context`=None
    + `skill`=None
    + `tools`=None
    + `model`=auto
    + `budget`=None
    + `mode`=reason

其中:

mode =
    deterministic
    rule
    small_model
    llm
    explore

10. agent.resolve

这是新版 Agent 最重要的函数之一。

## resolve
    + `task`
    + `kb_dir`
    + `near_match`=True
    + `threshold`=0.78

返回:

{
  "mode": "near",
  "skill": "json-repair",
  "resource": ".marqdo/agent-kb/skills/json-repair.mq.md",
  "score": 0.91,
  "confidence": 0.97
}

Resolver 应该按:

1. exact
2. alias
3. canonical
4. near
5. semantic
6. policy
7. unknown

寻找技能。

你现在已经实现了:

exact
alias
canonical
near
soft

所以这一部分可以直接演进,而不是重写。


11. agent.execute

Resolver 决定怎么执行之后:

## execute
    + `task`
    + `resolution`

例如:

resolution.mode == compiled

直接:

await_workbook(skill)

而不是:

LLM → 再想一遍

如果:

resolution.mode == near

则:

skill
 ↓
parameter adaptation
 ↓
execute
 ↓
verify

如果:

resolution.mode == unknown

则:

LLM exploration

12. Cognitive Cost Ladder

我非常建议把它正式加入框架。

L0  deterministic
        ↓
L1  Marqdo rule / branch
        ↓
L2  small decision model
        ↓
L3  small LLM
        ↓
L4  full LLM
        ↓
L5  exploration / multi-step reasoning

每一个任务都应该有:

cost_level

例如:

cost_level: 0
llm_calls: 0

或者:

cost_level: 4
llm_calls: 7

学习的本质就是:

L5
 ↓
L4
 ↓
L3
 ↓
L2
 ↓
L1
 ↓
L0

这会成为 Marqdo Agent 非常漂亮的研究指标。


13. agent.verify

不能:

成功一次
→ 自动成为 skill

否则很容易错误泛化。

所以必须有:

## verify
    + `task`
    + `result`
    + `skill`=None
    + `evidence`=None

验证包括:

13.1 Execution verification

有没有报错?

13.2 Structural verification

输出格式是否正确?

13.3 Semantic verification

结果是否真正解决 task?

13.4 Regression verification

过去的任务还能不能通过?

14. Skill 学习不能简单使用“3 次”

你之前提出:

三次调用之后自动总结。

我建议语义上改成:

三次触发 Candidate Learning,而不是三次直接成为 Skill。

也就是:

1 execution
    ↓
episode

2 execution
    ↓
episode

3 execution
    ↓
LEARNING TRIGGER
    ↓
candidate skill

但是:

candidate
    ↓
historical replay
    ↓
held-out test
    ↓
verification

成功以后才:

compiled

15. agent.record_episode

每次执行都应该记录。

## record_episode
    + `task`
    + `context`
    + `actions`
    + `observations`
    + `result`
    + `verification`
    + `metrics`

生成:

.marqdo/agent-memory/
    episodes/
        2026/
            09/
                episode-0001.mq.md
                episode-0002.mq.md

推荐格式:

---
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。

因此:

## cluster_episodes
    + `episodes`
    + `threshold`=0.82

目标:

episode 1 ─┐
episode 2 ─┤
episode 3 ─┤→ cluster A
episode 4 ─┘

episode 5 ─┐
episode 6 ─┤→ cluster B
episode 7 ─┘

可以先使用:

canonicalized task
+
tool sequence
+
input/output schema
+
success pattern

做廉价聚类。

不要一开始就让大模型处理所有历史。


17. agent.extract_pattern

从 cluster 中提取共同结构:

## extract_pattern
    + `episodes`

输入:

A:
    parse
    validate
    repair
    return

B:
    parse
    validate
    repair
    return

C:
    parse
    validate
    repair
    return

输出:

Pattern:

1. Parse
2. Validate
3. Repair if invalid
4. Return

同时识别:

invariants
variables
exceptions
preconditions
postconditions

18. agent.generalize

这个函数非常重要。

## generalize
    + `pattern`
    + `episodes`

例如:

三个任务:

修复 JSON
修复 YAML
修复 TOML

可能共同形成:

parse structured data
→ validate
→ locate syntax error
→ repair
→ validate again

但是:

JSON/YAML/TOML

应该成为:

format

而不是写死。

最终:

input:
  format
  text

procedure:
  parse(format)
  validate()
  repair()
  validate()

这才叫 Generalization。


19. agent.synthesize_skill

然后:

## synthesize_skill
    + `pattern`
    + `episodes`

生成:

candidate/<slug>.mq.md

例如:

---
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

然后:

## validate_skill
    + `skill`
    + `episodes`
    + `test_cases`

执行:

candidate
    ↓
historical tests
    ↓
held-out tests
    ↓
edge cases

得到:

{
  "passed": true,
  "success_rate": 0.96,
  "regression_rate": 1.0,
  "confidence": 0.94
}

21. 为什么一定需要 Held-out Test?

否则:

Episode A
Episode B
Episode C

→ 从 A/B/C 总结 Skill

→ 再用 A/B/C 测试

这会产生:

训练数据泄漏。

所以应该:

A B C D E F G
│ │ │ │ │ │ │
├─┴─┴── training
│
└────── validation

例如:

5 个 episode
→ 3 个学习
→ 2 个测试

当数据不足时:

candidate

而不是:

compiled

22. agent.compile

验证成功:

## compile
    + `candidate`
    + `validation`

生成:

skills/<slug>.mq.md

并修改:

status: compiled
llm_free: true

这时候才允许:

Resolver
 ↓
Skill
 ↓
await_workbook

而无需 parent LLM。

你当前系统已经存在这个思想:命中 llm_free skill 后直接执行 workbook,而不是再次调用 parent LLM。

所以 v2 实际上是在把现有的 llm_free 从一个优化选项提升成:

编译后的技能执行模式。


23. agent.promote

建议把:

promote

明确分成:

candidate
experience
validated
compiled
deprecated

状态:

candidate
   ↓
validated
   ↓
compiled
   ↓
stable

失败:

candidate
   ↓
rejected

原 skill 变差:

stable
   ↓
degraded
   ↓
rollback

24. Skill Versioning

这是非常重要但容易被忽略的。

不要直接覆盖:

json-repair.mq.md

而应该:

skills/
    json-repair/
        v1.mq.md
        v2.mq.md
        manifest.mq.md

manifest:

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

## rollback
    + `skill`
    + `version`

例如:

v3
 ↓
regression
 ↓
rollback
 ↓
v2

这是 Agent 自动学习系统必须有的安全阀。


26. agent.observe

所有执行都应该产生统一 Event。

你现在的 plan 已经记录:

decision
round
done
tool events

并支持 stream / trace / echo。

建议升级成统一事件:

{
  "type": "decision",
  "timestamp": "...",
  "run_id": "...",
  "phase": "resolve",
  "decision": "REUSE",
  "skill": "json-repair"
}

事件类型:

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

最终:

trace

应该成为完整的 Agent execution graph。

例如:

run
│
├── resolve
│    └── near skill=json-repair
│
├── adapt
│
├── execute
│    ├── parse
│    ├── validate
│    └── repair
│
├── verify
│
└── record_episode

这样你的 UI 就可以直接展示 Agent 是怎么“学会”的。


28. agent.learn

最后把整个学习流程封装:

## learn
    + `episode`
    + `threshold`=3

内部:

record_episode
      ↓
cluster
      ↓
pattern
      ↓
generalize
      ↓
synthesize
      ↓
validate
      ↓
compile

也就是:

learn()

不是一个 LLM prompt。

它应该是一个完整的 Learning Pipeline。


29. agent.maybe_learn

run() 不应该每次都学习。

因此:

## maybe_learn
    + `task`
    + `episode`

判断:

是否存在类似任务?
是否达到 evidence threshold?
是否出现稳定 tool sequence?
是否成功率足够?
是否值得编译?

例如:

episode_count >= 3
AND
similarity >= 0.85
AND
success_rate >= 0.90

才触发。


30. improve_every 的重新定义

你现在已经有:

improve_every=3

当前语义更接近:

命中一定次数之后进行改进。

我建议升级成:

learning:
  trigger_every: 3
  validation_min: 3
  confidence_min: 0.90
  success_rate_min: 0.92

然后:

trigger_every

只代表:

什么时候重新检查技能。

而不是:

什么时候自动修改技能。


31. explore_n 重新定义

你当前:

explore_n=3

会在任务文件不足时强制探索不同 variant。

这个设计其实非常好,但应该明确:

explore_n = exploration budget

而不是简单:

没有 skill → 多跑三次

建议:

exploration strategy:
    variant A
    variant B
    variant C

比如:

A: tool-first
B: code-first
C: LLM-first

然后比较:

success
latency
tokens
tool calls
robustness

最终选择。


32. Agent 的 Exploration

我甚至建议单独增加:

## explore
    + `task`
    + `n`=3
    + `strategies`=None

输出:

{
  "candidates": [
    {
      "strategy": "tool-first",
      "success": true,
      "cost": 2
    },
    {
      "strategy": "llm-first",
      "success": true,
      "cost": 8
    },
    {
      "strategy": "code-first",
      "success": true,
      "cost": 1
    }
  ]
}

然后:

select_strategy()

选择未来的执行路径。


33. agent.select_strategy

## select_strategy
    + `candidates`

不是简单按照:

success

而是:

utility =
    correctness
    - λ * token_cost
    - μ * latency
    - ν * tool_cost

例如:

A:
success = 0.96
tokens = 8000

B:
success = 0.94
tokens = 1000

C:
success = 0.99
tokens = 3000

系统可以保存:

strategy profile

而不是每次重新思考。


34. 这就引出你之前说的 Jev

你之前提到:

“Jev 决策模型”

我认为它非常适合放在这里。

架构变成:

Task
 ↓
Jev Router
 ↓
┌──────────────┬──────────────┬──────────────┐
│ deterministic│ small model  │ large LLM    │
└──────────────┴──────────────┴──────────────┘

Jev 不负责解决问题。

它只负责:

决定应该用什么成本解决问题。

这是非常关键的职责分离。


35. agent.route

## route
    + `task`
    + `skills`
    + `policy`

输出:

{
  "mode": "skill",
  "skill": "json-repair",
  "confidence": 0.96
}

或者:

{
  "mode": "small_model",
  "model": "jev-small",
  "confidence": 0.71
}

或者:

{
  "mode": "llm",
  "model": "large",
  "reason": "unknown task"
}

36. Skill 的 MQ 文件结构

这是我最建议你统一下来的部分。

每个 Skill:

---
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 同时具有:

Documentation
+
Knowledge
+
Program
+
Execution
+
Verification
+
Provenance

这正好和你整个 Marqdo 的论文方向统一起来。


37. Agent Memory 的目录

最终建议:

.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

不应该每次扫描整个目录。

所以需要:

## index

维护:

skills:
  - name: json-repair
    version: 2
    status: stable
    embedding: ...
    keywords: ...
    success_rate: 0.97

experiences:
  - ...

Resolver 首先查询 index。


39. agent.kb_lookup

你当前已经有:

agent_kb_lookup

应该升级成统一:

## kb_lookup
    + `task`
    + `mode`=auto

内部:

exact
→ alias
→ canonical
→ lexical near
→ semantic near
→ policy

返回统一结构:

{
  "match": "near",
  "resource": "...",
  "score": 0.91,
  "confidence": 0.95,
  "status": "stable",
  "llm_free": true
}

40. Near Match 之后不要直接执行

这是一个非常重要的改进。

现在:

near match
 ↓
skill
 ↓
execute

容易出现:

相似 ≠ 相同

所以应该:

near match
 ↓
skill applicability check
 ↓
adapt
 ↓
execute

增加:

## adapt_skill

输入:

task
skill

输出:

binding

例如:

format: yaml
text: ...

41. Skill Applicability

Skill 应该有:

applicability:
  domain: structured-data
  input_types:
    - json
    - yaml
  constraints:
    - has_text_input

Resolver 不仅问:

“像不像?”

还要问:

“这个技能能不能合法处理这个输入?”


42. Failure Learning

Agent 不应该只保存成功经验。

应该记录:

成功:
A → B → C

失败:
A → D → C

这样才能学习:

不要 D

因此 Episode:

status: failed

failure:
  phase: validate
  reason: invalid_schema

然后 Learning Pipeline 可以提取:

negative pattern

43. agent.extract_failure

增加:

## extract_failure
    + `episodes`

输出:

avoid:
  - call X before validation
  - use Y when input is binary

然后写入:

# Exceptions

- Do not use X when ...
- If Y fails, fallback to ...

44. Self-Improvement

已有 skill:

Skill v1

运行几十次后:

发现:
98% 成功
2% 某种边缘输入失败

Agent 不应该立即改变 v1。

应该:

v1
 ↓
failure cluster
 ↓
candidate v2
 ↓
regression tests
 ↓
benchmark
 ↓
v2

这就是:

Skill Evolution


45. agent.evolve

最终:

## evolve
    + `skill`

执行:

collect failures
↓
extract pattern
↓
patch candidate
↓
run regression
↓
compare
↓
promote / reject

这比简单的:

improve_every=3

更完整。


46. 最终函数清单

我建议最终把 Agent API 控制在这些核心函数。

Runtime

agent.run
agent.step
agent.plan
agent.execute
agent.route

Resolution

agent.resolve
agent.kb_lookup
agent.skill_match
agent.adapt_skill

Execution

agent.execute_skill
agent.execute_policy
agent.explore
agent.select_strategy

Verification

agent.verify
agent.verify_output
agent.verify_skill
agent.regression_test

Memory

agent.record_episode
agent.get_episode
agent.cluster_episodes
agent.extract_pattern
agent.extract_failure

Learning

agent.learn
agent.maybe_learn
agent.generalize
agent.synthesize_skill

Compilation

agent.compile
agent.promote
agent.rollback
agent.evolve

Observation

agent.event
agent.trace
agent.inspect
agent.metrics

47. plan() 最终应该变成什么

这是最重要的一点。

你现在的 plan() 实际上已经非常庞大,因为它同时承担:

reuse
explore
decompose
execute
await
revise
promote
stream
trace

当前实现中 plan 已经包含这些职责,例如 reuse 命中后直接 await workbook、探索新 variant、执行后 revise,以及成功后的 KB promotion。

v2 不应该继续往 plan() 里面塞逻辑。

应该把:

plan()

变成 orchestrator:

## plan

resolve
↓
route
↓
execute
↓
verify
↓
record
↓
learn
↓
finish

真正的逻辑全部下沉到函数。

即:

plan
 ├── resolve
 ├── route
 ├── execute
 ├── verify
 ├── record_episode
 └── maybe_learn

这样 plan 才会重新变得可读。


48. 一个完整执行例子

假设用户第一次说:

把这个 JSON 字符串修复成合法 JSON

第一次:

run
 ↓
resolve
 ↓
MISS
 ↓
explore
 ↓
LLM
 ↓
tool
 ↓
verify
 ↓
success
 ↓
episode-001

第二次:

run
 ↓
near match
 ↓
explore variant
 ↓
success
 ↓
episode-002

第三次:

run
 ↓
near match
 ↓
explore
 ↓
success
 ↓
episode-003
 ↓
maybe_learn

触发:

cluster
 ↓
pattern extraction
 ↓
generalization
 ↓
candidate skill

然后:

historical test
+
held-out test

通过:

candidate
 ↓
compile
 ↓
json-repair/v1.mq.md
 ↓
llm_free=true

第四次:

run
 ↓
exact/near
 ↓
compiled skill
 ↓
Marqdo execution
 ↓
verify
 ↓
result

:

LLM calls = 0

这就是你最开始提出的:

第一次会思考,后来逐渐不需要思考。


49. 最重要的指标:Reasoning Amortization

我认为这个设计真正厉害的地方,不只是 Agent。

它可以形成一个非常明确的实验指标:

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

于是:

Experience ↑
Reasoning Cost ↓

这条曲线实际上就是你整个 Agent framework 的核心。


50. Marqdo Agent 的最终定义

我会把整个系统概括成:

                    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

先实现:

run
step
plan
record_episode
trace
metrics

让每一次执行都产生 .mq.md episode。


Phase 2:Experience Mining

增加:

cluster_episodes
extract_pattern
generalize
synthesize_skill

实现:

3+ executions
→ candidate.mq.md

Phase 3:Skill Compiler

增加:

verify_skill
compile
promote
rollback

实现:

candidate
→ validation
→ compiled
→ llm_free

这一步完成以后,你的 Agent 才真正具备“学习”。


Phase 4:Jev Router

增加:

route
select_strategy
policy

形成:

L0 deterministic
L1 rule
L2 small model
L3 small LLM
L4 large LLM
L5 exploration

这一步解决的是:

学会以后如何自动降低推理成本。


Phase 5:Skill Evolution

最后:

failure mining
→ candidate v2
→ regression
→ benchmark
→ promote
→ rollback

形成真正的:

Self-Evolving Executable Knowledge Base


52. 最终我建议把整个模块重新命名

现在的:

ext/ai/agent

可以继续保留,但内部概念最好从:

agent
├── step
└── plan

升级成:

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 的实际格式。这样就可以直接进入实现,而不是停留在架构层。