Compare commits

..
3 Commits
Author SHA1 Message Date
cflmyandCursor c44ea38ae2 release: Ext pack 1.4.3 — agent.run cold EFI / resolve llm_free
Bump ext/VERSION only (CLI stays 1.4.2). Ships agent facade + native miss-field fix for qdagent cold OKF.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 12:56:40 +08:00
cflmyandCursor d489f7c088 fix(ext/ai): cold agent.run EFI — self.preflight and resolve llm_free
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 <cursoragent@cursor.com>
2026-10-16 12:54:00 +08:00
cflmyandCursor a993cfd76a chore: sync Cargo.lock package versions to 1.4.2
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 12:21:23 +08:00
8 changed files with 270 additions and 28 deletions

No files matched your search

+20
View File
@@ -8,6 +8,26 @@
### Changed
## Ext pack v1.4.3 — 2026-10-16
### Highlights
**Agent cold EFI / resolve 硬崩修复(CLI 仍为 v1.4.2)**:qdagent 接通 `agent.run` 时空 OKF 触发 `unknown function preflight` 与 `missing map key llm_free`。本包修复 `ext/ai/agent` facade 与 `agent` native;金样 `tests/ext/agent-run-cold-efi.mq.md`。说明:[`doc/research/agent-run-efi-resolve-bugs-2026-10.md`](doc/research/agent-run-efi-resolve-bugs-2026-10.md)。
```bash
marqdo ext add agent # CDN latest → 1.4.3
# 或:MARQDO_EXT_VERSION=1.4.3 marqdo ext add agent
```
**核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime 契约修补。
### Fixed
- **`agent.run`**:`efi=True` 改为 `` `self`.preflight ``(不再裸调全局 `preflight`)。
- **`agent_resolve` miss**:返回字段对齐命中路径,含 `llm_free: false`;facade 对 `llm_free` / route 字段改用 `json.get`。
### Changed
- 扩展包 SemVer **1.4.3**(`ext/VERSION`);与 CLI **v1.4.2** 可独立安装。
## v1.4.2 — 2026-10-16
### Highlights
Generated
+2 -2
View File
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "1.4.1"
version = "1.4.2"
dependencies = [
"anyhow",
"assert_cmd",
@@ -603,7 +603,7 @@ dependencies = [
[[package]]
name = "marqdo-wasm"
version = "1.4.1"
version = "1.4.2"
dependencies = [
"marqdo",
"serde_json",
+2 -1
View File
@@ -149,8 +149,9 @@ marqdo catalog public -o .marqdo
---
## 现状(v1.4.2)
## 现状(v1.4.2 · Ext pack **1.4.3**)
- **Ext pack 1.4.3**:修复 `agent.run` cold EFI(`` `self`.preflight `` + miss resolve `llm_free`);`marqdo ext add agent` → CDN latest · [agent-run-efi-resolve-bugs-2026-10.md](doc/research/agent-run-efi-resolve-bugs-2026-10.md)
- **Agent/LLM 优化 O1–O5(v1.4.2)**:`ext/ai/sandbox` CoW · `agent.trial` / `sandbox=` · promote sandbox proof · `step_route` / EFI / cost · style lint · quarantine · [ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)
- **view 标注连线(v1.4.1)**:underline→chip SVG mid→mid(底边中点→轨道→短竖线→顶边中点)· 帧 chip 共用 id · L→R 密度 · [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)
- **叙述统一 / 公式 meta / 图片自写回(v1.4.0)**:`% marqdo: var=` 块公式绑定 · 臂/循环体叙述与 foreach 中英糖 · `![marqdo-out](…)` 图片自写回 · view 推断形参实值 · [fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.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
- 不把向量检索升为权威真相
+1 -1
View File
@@ -1 +1 @@
1.4.2
1.4.3
+26 -24
View File
@@ -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 |
+26
View File
@@ -1038,10 +1038,17 @@ pub fn resolve_task(args: &Value) -> Result<Value, String> {
"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<Value, String> {
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!(
+76
View File
@@ -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"*