From d489f7c088724893ae2416e87ef566407e44cb70 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 16 Oct 2026 12:54:00 +0800 Subject: [PATCH] =?UTF-8?q?fix(ext/ai):=20cold=20agent.run=20EFI=20?= =?UTF-8?q?=E2=80=94=20self.preflight=20and=20resolve=20llm=5Ffree?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Miss resolve omitted llm_free and run called bare preflight, which crashed qdagent on empty OKF. Align miss fields, use self.preflight + json.get, add regression gold and research note. Co-authored-by: Cursor --- CHANGELOG.md | 2 + .../agent-run-efi-resolve-bugs-2026-10.md | 117 ++++++++++++++++++ ext/ai/agent.mq.md | 50 ++++---- plugins/agent/src/memory.rs | 26 ++++ tests/ext/agent-run-cold-efi.mq.md | 76 ++++++++++++ 5 files changed, 247 insertions(+), 24 deletions(-) create mode 100644 doc/research/agent-run-efi-resolve-bugs-2026-10.md create mode 100644 tests/ext/agent-run-cold-efi.mq.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 58c1f45..6d4867a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,8 +3,10 @@ ## Unreleased ### Added +- Regression gold `tests/ext/agent-run-cold-efi.mq.md` + research note [`doc/research/agent-run-efi-resolve-bugs-2026-10.md`](doc/research/agent-run-efi-resolve-bugs-2026-10.md)(qdagent cold EFI)。 ### Fixed +- **`agent.run` / `agent_resolve`(qdagent 复现)**:miss resolve 补齐 `llm_free: false`;`## run` 改为 `` `self`.preflight ``,并对 `llm_free` / route 字段用 `json.get` 防御缺键硬崩。 ### Changed diff --git a/doc/research/agent-run-efi-resolve-bugs-2026-10.md b/doc/research/agent-run-efi-resolve-bugs-2026-10.md new file mode 100644 index 0000000..5a4c751 --- /dev/null +++ b/doc/research/agent-run-efi-resolve-bugs-2026-10.md @@ -0,0 +1,117 @@ +# 缺陷记录:`agent.run` EFI / resolve 在消费方崩溃(qdagent 复现) + +| | | +|---|---| +| 状态 | **Fixed(2026-10-16)** — 见 §3;金样 `tests/ext/agent-run-cold-efi.mq.md` | +| 日期 | 2026-10-16 | +| 发现方 | qdagent(`~/work/qdagent`)接通 Marqdo ≥1.4.2 Agent EFI 全路径时 | +| 影响面 | `ext/ai/agent` · `## run` · `plugins/agent` `agent_resolve` | +| 相关 | [ext-agent.md](../design/ext-agent.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [ai-agent-llm-optimize-2026-10.md](ai-agent-llm-optimize-2026-10.md) | + +--- + +## 0. 一句话 + +`agent.run` 在 **空 OKF / 无 skill 命中** 或 **`efi=True`** 时,会以硬错误退出,而不是降级到 `plan` 探索。 +这是 **Agent Runtime 契约不完整**,不是 qdagent 业务写错。 + +--- + +## 1. 复现(qdagent) + +环境:工作区 Marqdo `1.4.2` + `MARQDO_EXT=~/work/marqdo/ext`;qdagent 调用: + +```text +助手 = > agent.agent … +`助手`.run task=… efi=True # 或 efi=False 后仍进 resolve +``` + +本仓几乎没有 `.marqdo/agent-kb` 编译 skill。 + +### Bug A — `efi=True` → `unknown function preflight` + +**位置**:[`ext/ai/agent.mq.md`](../../ext/ai/agent.mq.md) `## run` + +```markdown +1. `efi` + **efi_pf = preflight task=`task`** +``` + +同文件其它同对象方法一律写 `` `self`.route `` / `` `self`.resolve ``。 +裸标识 `preflight` 在导入消费方(如 `cli/求道-构建.mq.md`)里被解析成**全局函数**,找不到 → 硬错。 + +**期望**:`` **efi_pf = > `self`.preflight task=`task`** ``(或等价 method call)。 + +### Bug B — miss resolve → `missing map key llm_free` + +**位置**: + +1. Plugin:[`plugins/agent/src/memory.rs`](../../plugins/agent/src/memory.rs) `resolve_task` + 当 `kb_lookup` 返回 null: + +```rust +Ok(json!({ + "mode": "unknown", + "skill": null, + "resource": null, + "confidence": 0.0, + // 缺 llm_free +})) +``` + +2. Facade:`## run` 在 resolve 之后: + +```markdown +**llm_free = [llm_free](resolved)** +``` + +脚注式取键在缺键时 **硬失败**,无法落到后面的 `plan` 探索臂。 + +**期望**: + +- miss 结果始终带 `"llm_free": false`(与命中路径字段集对齐) +- facade 侧对可选键用 `json.get`(缺省 `False`),防御其它调用方 + +--- + +## 2. 为何金样没拦住 + +| 金样 | 为何漏网 | +|------|----------| +| `tests/ext/agent-zero-llm.mq.md` | 先编译 skill / policy,再 `run`;resolve **命中** | +| `tests/ext/eng-preflight.mq.md` | 只测 `agent_eng_preflight`,**不**走 `agent.run efi=` | +| 多数 `agent-*-live` | 自带 kb 或 `efi=False` / 不经过 cold miss | + +qdagent 是第一个「冷库 + 产品 EFI + `run`」消费方,因此打穿。 + +--- + +## 3. 修复清单(本轮) + +| # | 改动 | 文件 | +|---|------|------| +| 1 | miss resolve 补 `llm_free: false` | `plugins/agent/src/memory.rs` | +| 2 | `` `self`.preflight ``;`llm_free`/`mode` 用 `json.get` | `ext/ai/agent.mq.md` | +| 3 | 回归金样:冷 kb + `run efi=True` 不崩溃,落到 explore/plan | `tests/ext/agent-run-cold-efi.mq.md` | +| 4 | 重建 `marqdo_plugin_agent` 并跑金样 | `cargo build -p marqdo_plugin_agent --release` | + +--- + +## 4. 对 qdagent 的含义 + +修复后 qdagent 可恢复: + +```text +product preflight → latch → agent.run (efi=True|False) / plan +``` + +而不必长期绕开 `agent.run`。 +在插件未装入新 so 前,qdagent 侧 EFI latch + `step`/`plan` 仍是合法降级。 + +--- + +## 5. 非目标 + +- 不改 EKC / `agent_eng_preflight` 语义 +- 不引入第二套 Agent loop +- 不把向量检索升为权威真相 diff --git a/ext/ai/agent.mq.md b/ext/ai/agent.mq.md index 8d7bf76..f23def1 100644 --- a/ext/ai/agent.mq.md +++ b/ext/ai/agent.mq.md @@ -1941,19 +1941,19 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o **efi_pf = None** 1. `efi` - **efi_pf = preflight task=`task`** + **efi_pf = > `self`.preflight task=`task`** 2. * **_ = 1** -**routed = `self`.route task=`task` backend=`router` kb_dir=`kb_dir` memory_dir=`memory_dir` threshold=`near_threshold`** -**route_matched = [matched](routed)** -**needs_llm = [needs_llm](routed)** +**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** **tokens = 0** **token_cost = 0** **out = None** -**route_backend = [backend](routed)** +**route_backend = > json.get value=`routed` key="backend"** 1. `route_matched` **path = > json.get value=`routed` key="resource"** @@ -1964,13 +1964,13 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o **last_obs = [observation](aw)** 1. `code` == 0 > agent_kb_record_hit kb_dir=`kb_dir` goal=`task` improve_every=`improve_every` - **lf = [llm_free](routed)** + **lf = > json.get value=`routed` key="llm_free"** 1. `lf` **exec_mode = "compiled"** 2. * **exec_mode = "routed"** - **rmode = [mode](routed)** - **sk = [skill](routed)** + **rmode = > json.get value=`routed` key="mode"** + **sk = > json.get value=`routed` key="skill"** **out = ** | status | goal | result | workbook | cache | match | skill | observation | summary | route | @@ -1989,22 +1989,22 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o **_ = 1** 2. `needs_llm` 1. `router_model` - **prompt = [prompt](routed)** + **prompt = > json.get value=`routed` key="prompt"** **turn = model_turn model=`router_model` prompt=`prompt` stream=`stream` echo=`echo`** - **reply = [text](turn)** - **llm_calls = [llm_calls](turn)** - **tokens = [tokens](turn)** - **applied = `self`.route_apply task=`task` reply=`reply` kb_dir=`kb_dir` backend=`router`** - **am = [matched](applied)** + **reply = > json.get value=`turn` key="text"** + **llm_calls = > json.get value=`turn` key="llm_calls"** + **tokens = > json.get value=`turn` key="tokens"** + **applied = > `self`.route_apply task=`task` reply=`reply` kb_dir=`kb_dir` backend=`router`** + **am = > json.get value=`applied` key="matched"** 1. `am` - **path = [resource](applied)** + **path = > json.get value=`applied` key="resource"** **aw = await_workbook path=`path` sandbox=`sandbox` sandbox_profile=`sandbox_profile`** **code = [code](aw)** **child_val = [value](aw)** **last_obs = [observation](aw)** 1. `code` == 0 **exec_mode = "routed"** - **sk = [skill](applied)** + **sk = > json.get value=`applied` key="skill"** **out = ** | status | goal | result | workbook | cache | match | skill | observation | summary | route | @@ -2025,9 +2025,9 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o **_ = 1** 2. * 1. `efi_pf` - **efi_st = [status](efi_pf)** - **efi_dec = [decision](efi_pf)** - **efi_allow = [create_allowed](efi_pf)** + **efi_st = > json.get value=`efi_pf` key="status"** + **efi_dec = > json.get value=`efi_pf` key="decision"** + **efi_allow = > json.get value=`efi_pf` key="create_allowed"** 1. `efi_st` == "missing_knowledge" **_ = 1** 2. `efi_dec` == "REUSE" @@ -2050,11 +2050,13 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o 1. `out` **_ = 1** 2. * - **resolved = `self`.resolve task=`task` kb_dir=`kb_dir` near_match=`near_match` near_threshold=`near_threshold`** - **mode = [mode](resolved)** - **llm_free = [llm_free](resolved)** + **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. not `llm_free` + **llm_free = False** 1. `llm_free` - **path = [resource](resolved)** + **path = > json.get value=`resolved` key="resource"** **aw = await_workbook path=`path` sandbox=`sandbox` sandbox_profile=`sandbox_profile`** **code = [code](aw)** **child_val = [value](aw)** @@ -2062,7 +2064,7 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o 1. `code` == 0 > agent_kb_record_hit kb_dir=`kb_dir` goal=`task` improve_every=`improve_every` **exec_mode = "compiled"** - **sk = [skill](resolved)** + **sk = > json.get value=`resolved` key="skill"** **out = ** | status | goal | result | workbook | cache | match | skill | observation | summary | diff --git a/plugins/agent/src/memory.rs b/plugins/agent/src/memory.rs index f53311a..9c86115 100644 --- a/plugins/agent/src/memory.rs +++ b/plugins/agent/src/memory.rs @@ -1038,10 +1038,17 @@ pub fn resolve_task(args: &Value) -> Result { "tools": args.get("tools").cloned().unwrap_or(Value::Null), }))?; if hit.is_null() { + // Keep field set aligned with hit path so facades can safely read llm_free + // (qdagent / agent.run crashed on missing key when OKF is cold). return Ok(json!({ "mode": "unknown", + "match": null, "skill": null, "resource": null, + "slug": null, + "status": null, + "llm_free": false, + "score": null, "confidence": 0.0, })); } @@ -1078,6 +1085,25 @@ pub fn resolve_task(args: &Value) -> Result { mod tests { use super::*; + #[test] + fn resolve_miss_includes_llm_free() { + let dir = std::env::temp_dir().join(format!( + "marqdo-resolve-miss-{}", + std::process::id() + )); + let _ = fs::remove_dir_all(&dir); + fs::create_dir_all(&dir).unwrap(); + let out = resolve_task(&json!({ + "task": "no-such-skill-cold-miss", + "kb_dir": dir.to_string_lossy(), + "near_match": false, + })) + .unwrap(); + assert_eq!(out.get("mode").and_then(|v| v.as_str()), Some("unknown")); + assert_eq!(out.get("llm_free").and_then(|v| v.as_bool()), Some(false)); + let _ = fs::remove_dir_all(&dir); + } + #[test] fn record_and_cluster_and_compile() { let dir = std::env::temp_dir().join(format!( diff --git a/tests/ext/agent-run-cold-efi.mq.md b/tests/ext/agent-run-cold-efi.mq.md new file mode 100644 index 0000000..9891a2a --- /dev/null +++ b/tests/ext/agent-run-cold-efi.mq.md @@ -0,0 +1,76 @@ +--- +title: agent.run cold OKF — resolve llm_free + self.preflight +description: >- + Regression for qdagent-facing bugs (2026-10): + (A) miss resolve must expose llm_free=false; + (B) `self`.preflight must resolve when agent is imported by a consumer. + Offline — dummy API key; no live network required for assertions A/B. +import agent:ext/ai/agent.mq.md +import fs:lib/fs.mq.md +import json:lib/json.mq.md +import llm:ext/ai/llm.mq.md +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +--- + +# main + +> sys.env_set name="OPENAI_API_KEY" value="offline-cold-efi-dummy" + +**p = > plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=no-agent-plugin + > sys.exit code=1 + +**kb = ".marqdo/agent-kb-cold-efi"** +**ex = > fs.exists path=`kb`** +1. `ex` + > fs.remove_tree path=`kb` +2. * + **_ = 1** +> fs.make_dir path=`kb` + +**resolved = > agent_resolve task="qdagent-cold-unknown-task-xyz-20261016" kb_dir=`kb`** +**lf = > json.get value=`resolved` key="llm_free"** +**mode = > json.get value=`resolved` key="mode"** +1. `lf` == False + > print text=resolve-miss-llm_free-ok +2. * + > print text=resolve-miss-llm_free-MISSING + > print text=`resolved` + > sys.exit code=1 + +1. `mode` == "unknown" + > print text=resolve-miss-mode-ok +2. * + > print text=resolve-miss-mode-unexpected + > sys.exit code=1 + +**model = > llm.llm** +`tools` = + +| 工具 | +|------| + +**ag = > agent.agent model=`model` tools=`tools` standing="cold efi preflight probe"** +**pf = > `ag`.preflight task="qdagent-cold-unknown-task-xyz-20261016" marqdo_dir=".marqdo"** +**st = > json.get value=`pf` key="status"** +1. `st` + > print text=self-preflight-ok + > print text=`st` +2. * + > print text=self-preflight-failed + > print text=`pf` + > sys.exit code=1 + +**via = > `ag`.resolve task="qdagent-cold-unknown-task-xyz-20261016" kb_dir=`kb`** +**via_lf = > json.get value=`via` key="llm_free"** +1. `via_lf` == False + > print text=method-resolve-llm_free-ok +2. * + > print text=method-resolve-llm_free-MISSING + > sys.exit code=1 + +*"agent-run-cold-efi-ok"*