feat(workbench): live selection smoke, F02 agent e2e, DocumentView CLI

Hoist llm.ask prompt binding to avoid elevated `p`; prefer reasoning_content
when content is empty; point live/tests at in-tree MARQDO_EXT; add USTC live
gates and mock agent.step selection+resume evidence; view document --out for
read-only browser embed checks. Design stays Partial (not Verified).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-10-25 23:05:28 +08:00
1 parent 8cf5288481
commit c7c329341b
8 files changed
+467 -5

No files matched your search

@@ -1,6 +1,6 @@
# qdagent 知识工作台所需的多模型运行与 View 嵌入支持
日期:2026-10-25。状态:Partial / in progress(M00–M06 脚手架与合同门禁已落地;F 矩阵仍有缺口,不得整文宣称 Verified;原生非兼容适配器仍 unavailable)。
日期:2026-10-25。状态:Partial / in progress(M00–M06 合同门禁 + F02 agent.step/resume 假模型 e2e + USTC live selection smoke + DocumentView 浏览器只读核对已落地;F 矩阵未全绿,不得整文宣称 Verified;原生非兼容适配器仍 unavailable)。
源码基线:Marqdo `dc853fb`(2.1.2),qdagent `643dd31`,已同步远端。应用侧配套:[qdagent 多提供商与知识工作台](../../../qdagent/doc/design/multi-provider-and-knowledge-workbench-2026-10-25.md)。跨仓相对链接以兄弟仓库工作区布局为准。
@@ -416,18 +416,19 @@ cargo test --offline --locked --test executable_knowledge f1_agent_eng_bind_gate
| 切片 | 证据 |
|---|---|
| M00 | fixtures + JSON Schema 消费;`capabilities`;`force_unloaded` / `force_*_off`(F16) |
| M01 | strict selection;`RunContextV1` 并行不串扰;llm plugin messages/roles;workbook 禁 `llm.llm` |
| M01 | strict selection;`RunContextV1` 并行不串扰;llm plugin messages/roles;workbook 禁 `llm.llm`;**F02** `m01_f02_agent_step_selection_and_resume`(mock HTTP + `llm.create` 抗 env poison + resume save/load) |
| M02 | usage null≠0;revision 替换(F05);cancel token(F06/F07);event_sink;web `sse-live` 断连 cancel |
| M03 | `view.document`;CJK outline/nodes;path escape;静态 a11y 子集;F08 无副作用标记 |
| M03 | `view.document`;CJK outline/nodes;path escape;静态 a11y 子集;F08 无副作用标记;**浏览器** `workbench-docview.html`(`article.mq-document`、0 script、无 `javascript:`) |
| M04 | stale / version_unavailable / **ambiguous**;`SnapshotManifestV1` 输出(retention=application);`artifact.version_mismatch`;embed strict SSE |
| M05 | extract `:B`;analysis_cache begin/finish;**F14 并发 100** 同 snapshot + 跨 project 隔离 |
| M06 | CI 预构建 agent+llm + `workbench_contracts`;Go `drainForward` / cancel-token 桥 |
| Live | `tests/workbench_live.rs`:USTC OpenAI-compatible(`OPENAI_*` env only)`qwen3.8-chat` / `deepseek-flash` selection ask → `pong` + usage;`MARQDO_EXT` 指向仓内 `ext/` 避免 `~/.marqdo/ext` 陈旧遮蔽 |
已知限制(发版前须书面接受或继续补):
- Agent resume/repair **全路径 e2e**(假模型)仍薄;F02 现有 RunContext 三级继承 + skeleton 禁 `llm.llm` + 子任务 env。
- F02 repair/plan **全路径**假模型仍薄于 step+resume;RunContext 三级继承 + skeleton 禁 `llm.llm` + 子任务 env 已有。
- 历史正文由应用按 SnapshotManifest 保留;框架缺快照 → `version_unavailable`(不静默降级)。
- 完整浏览器 F12 留给 qdagent;原生适配器 / PDF/OCR 仍 unavailable;未调用付费供应商。
- 完整宿主嵌入 F12 / 产品鉴权留给 qdagent;原生适配器 / PDF/OCR 仍 unavailable。
### 12.2 历史基线记录(设计起草时)
+2
View File
@@ -156,6 +156,7 @@ Prompt artifact helper: `path=` loads a file; `text=` strips `type: prompt` fron
Module convenience: create a default handle and return **answer text**. Pass `path=` to load a prompt document, `prompt=` text, or omit both to use the entry `.mq.md` as a prompt artifact (`type: prompt` body via `sys.module_source`).
**p = `prompt`**
1. `path`
**p = > prompt_load path=`path`**
2. `prompt`
@@ -274,6 +275,7 @@ Prefer declaring `model` / `api_key` / `base_url` in frontmatter Binding, then u
Semantic ask → **LLMResult** (`text`, `model`, `finish`, `backend`, `usage`, `name`, `tool_calls`). Prefer `[text](result)` for the answer string. Omit `prompt=` / `path=` to use the entry document (`sys.module_source` + `prompt_body`). Pass `messages=` for multi-turn history (M01). `selection=` + `strict_selection=True` freeze request identity without env fallback.
**p = `prompt`**
1. `messages`
**p = None**
2. `path`
+3
View File
@@ -363,9 +363,12 @@ fn chat_completions(args: &Value) -> Result<Value, String> {
.and_then(|c0| c0.get("message"))
.cloned()
.unwrap_or(json!({}));
// Some gateways (reasoning models) return null content + reasoning_content.
let content = msg
.get("content")
.and_then(|v| v.as_str())
.filter(|s| !s.is_empty())
.or_else(|| msg.get("reasoning_content").and_then(|v| v.as_str()))
.unwrap_or("")
.to_string();
let fr = data
+67
View File
@@ -529,6 +529,23 @@ enum ViewAction {
#[arg(short = 'o', long = "out", required = true)]
out: PathBuf,
},
/// Read-only DocumentViewV1 (never executes). JSON to stdout or `--out`.
Document {
/// Project root (defaults to cwd / CLI path)
#[arg(long)]
project: Option<PathBuf>,
/// Document path relative to project
#[arg(long)]
document: String,
#[arg(long)]
json: bool,
/// Optional HTML wrapper for browser inspection (embed fragment only)
#[arg(long, value_name = "FILE")]
out: Option<PathBuf>,
},
}
fn main() -> ExitCode {
@@ -1105,6 +1122,56 @@ fn try_main(cli: Cli) -> Result<i32> {
})?;
Ok(0)
}
Some(ViewAction::Document {
project,
document,
json,
out,
}) => {
let project = project
.or(path)
.unwrap_or_else(|| PathBuf::from("."));
let req = marqdo::workbench::DocumentViewRequest {
project,
document,
revision: None,
generation: None,
node_id: None,
include: vec![
"fragment".into(),
"outline".into(),
"nodes".into(),
"refs".into(),
"diagnostics".into(),
],
};
let view = marqdo::workbench::build_document_view(&req).map_err(|e| {
anyhow::anyhow!("{}", e)
})?;
if let Some(out_path) = out {
let fragment = view
.pointer("/render/fragment")
.and_then(|v| v.as_str())
.unwrap_or("");
let title = view
.pointer("/document/title")
.and_then(|v| v.as_str())
.unwrap_or("DocumentView");
let html = format!(
"<!doctype html><html><head><meta charset=\"utf-8\"/><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"/><title>{title}</title><style>:root{{--mq-bg:#f7f5f0;--mq-text:#1a1a1a;--mq-muted:#5c5c5c;--mq-border:#d0cbc2;--mq-accent:#0b5fff;--mq-font-body:\"Iowan Old Style\",\"Palatino Linotype\",Palatino,serif;--mq-font-code:ui-monospace,Consolas,monospace}}body{{margin:0;background:var(--mq-bg);color:var(--mq-text);font:16px/1.75 var(--mq-font-body)}}.wrap{{max-width:46rem;margin:0 auto;padding:1.5rem}} .mq-document a{{color:var(--mq-accent)}}</style></head><body><div class=\"wrap\">{fragment}</div></body></html>"
);
std::fs::write(&out_path, html)?;
if json {
println!("{}", serde_json::to_string_pretty(&view)?);
} else {
println!("wrote {}", out_path.display());
}
} else {
println!("{}", serde_json::to_string_pretty(&view)?);
}
let _ = json;
Ok(0)
}
None => {
serve(ViewOptions {
path: path.unwrap_or_else(|| PathBuf::from(".")),
+81
View File
@@ -0,0 +1,81 @@
---
markup: occlusion
title: workbench F02 agent selection (mock upstream)
description: >-
Explicit llm.create selection must drive agent.step; process env default model
must not win. Upstream URL/key/model come from env set by the Rust harness.
import:
llm: ext/ai/llm.mq.md
agent: ext/ai/agent.mq.md
sys: lib/sys.mq.md
json: lib/json.mq.md
---
# main
**base = > sys.env_get name="OPENAI_BASE_URL"**
**key = > sys.env_get name="OPENAI_API_KEY"**
**mdl = > sys.env_get name="OPENAI_MODEL"**
1. not `base`
> print text=missing-OPENAI_BASE_URL
> sys.exit code=2
2. *
**_ = 1**
1. not `key`
> print text=missing-OPENAI_API_KEY
> sys.exit code=2
2. *
**_ = 1**
1. not `mdl`
> print text=missing-OPENAI_MODEL
> sys.exit code=2
2. *
**_ = 1**
Poison ambient default — selection on the handle must still win at the plugin.
> sys.env_set name="OPENAI_MODEL" value="env-poison-model"
**model = > llm.create model=`mdl` base_url=`base` api_key=`key` backend="openai-compatible" name=f02-agent**
`tools` =
| 工具 |
|------|
**ag = > agent.agent model=`model` tools=`tools` standing="F02 selection probe; answer with one word only"**
**step = > `ag`.step task="Reply with exactly one English word pong" writeback=False max_reads=1**
**st = > json.get value=`step` key="status"**
**ans = > json.get value=`step` key="result"**
1. not `ans`
**ans = > json.get value=`step` key="answer"**
2. *
**_ = 1**
1. not `ans`
**ans = > json.get value=`step` key="text"**
2. *
**_ = 1**
> print text=`st`
> print text=`ans`
**dir = ".marqdo/workbench-f02-resume"**
**saved = > agent.resume_save id="f02-sel" goal="pong" status="running" round=1 resume_dir=`dir`**
**ok = > json.get value=`saved` key="ok"**
1. `ok`
> print text=resume-save-ok
2. *
> print text=resume-save-fail
> print text=`saved`
> sys.exit code=1
**loaded = > agent.resume id="f02-sel" resume_dir=`dir`**
**found = > json.get value=`loaded` key="found"**
1. `found`
> print text=resume-load-ok
2. *
> print text=resume-load-fail
> print text=`loaded`
> sys.exit code=1
> agent.resume_clear id="f02-sel" resume_dir=`dir`
> print text=f02-agent-selection-ok
+43
View File
@@ -0,0 +1,43 @@
---
markup: occlusion
title: workbench M01 live selection (USTC-compatible)
description: Explicit ModelSelection via llm.create; no llm.llm. Credentials from process env only.
import:
llm: ext/ai/llm.mq.md
sys: lib/sys.mq.md
json: lib/json.mq.md
---
# main
**base = > sys.env_get name="OPENAI_BASE_URL"**
**key = > sys.env_get name="OPENAI_API_KEY"**
**mdl = > sys.env_get name="OPENAI_MODEL"**
1. not `base`
> print text=missing-OPENAI_BASE_URL
> sys.exit code=2
2. *
**_ = 1**
1. not `key`
> print text=missing-OPENAI_API_KEY
> sys.exit code=2
2. *
**_ = 1**
1. not `mdl`
**mdl = "qwen3.8-chat"**
2. *
**_ = 1**
**model = > llm.create model=`mdl` base_url=`base` api_key=`key` backend="openai-compatible" name=workbench-live**
**q = "Reply with exactly one English word pong"**
**reply = > model.ask prompt=`q`**
**text = > json.get value=`reply` key="text"**
**usage = > json.get value=`reply` key="usage"**
**pt = > json.get value=`usage` key="prompt_tokens"**
> print text=`text`
1. `pt`
> print text=usage-present
2. *
> print text=usage-unknown
+125
View File
@@ -688,3 +688,128 @@ fn m04_f11_ambiguous_same_name() {
let cands = resp["result"]["candidates"].as_array().unwrap();
assert!(cands.len() >= 2, "{resp}");
}
/// F02: agent.step + resume with explicit llm.create selection against a local mock.
/// Env poison model must not appear in the upstream request body.
#[test]
fn m01_f02_agent_step_selection_and_resume() {
use std::io::{Read, Write};
use std::net::TcpListener;
use std::process::Command;
use std::sync::{Arc, Mutex};
use std::thread;
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let ext = root.join("ext");
let status = Command::new("cargo")
.args(["build", "-p", "marqdo_plugin_llm", "-p", "marqdo_plugin_agent", "--locked"])
.current_dir(&root)
.status()
.expect("build plugins");
assert!(status.success(), "plugin build failed");
let llm_so = root.join("target/debug/libllm.so");
let agent_so = root.join("target/debug/libagent.so");
assert!(llm_so.is_file(), "missing {llm_so:?}");
assert!(agent_so.is_file(), "missing {agent_so:?}");
let seen = Arc::new(Mutex::new(Vec::new()));
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let addr = listener.local_addr().unwrap();
let seen_bg = seen.clone();
thread::spawn(move || {
// Agent may deepen once (READ) then answer — accept a few requests.
for _ in 0..4 {
let Ok((mut stream, _)) = listener.accept() else {
break;
};
let mut raw = Vec::new();
let mut buf = [0u8; 4096];
loop {
let n = stream.read(&mut buf).unwrap_or(0);
if n == 0 {
break;
}
raw.extend_from_slice(&buf[..n]);
if let Some(pos) = raw.windows(4).position(|w| w == b"\r\n\r\n") {
let header = String::from_utf8_lossy(&raw[..pos]);
let cl = header
.lines()
.find_map(|l| l.strip_prefix("Content-Length:"))
.and_then(|v| v.trim().parse::<usize>().ok())
.unwrap_or(0);
let body_start = pos + 4;
while raw.len() < body_start + cl {
let n = stream.read(&mut buf).unwrap_or(0);
if n == 0 {
break;
}
raw.extend_from_slice(&buf[..n]);
}
break;
}
}
let req = String::from_utf8_lossy(&raw).to_string();
seen_bg.lock().unwrap().push(req);
let body = r#"{"choices":[{"message":{"content":"pong"},"finish_reason":"stop"}],"usage":{"prompt_tokens":3,"completion_tokens":1,"total_tokens":4}}"#;
let resp = format!(
"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
body.len(),
body
);
let _ = stream.write_all(resp.as_bytes());
}
});
let base = format!("http://{addr}/v1");
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", "tests/ext/workbench-agent-selection.mq.md"])
.current_dir(&root)
.env("MARQDO_EXT", &ext)
.env("MARQDO_LLM_PLUGIN", &llm_so)
.env("MARQDO_AGENT_PLUGIN", &agent_so)
.env("OPENAI_BASE_URL", &base)
.env("OPENAI_API_KEY", "f02-key")
.env("OPENAI_MODEL", "f02-selected-model")
.output()
.expect("run workbench-agent-selection");
let stdout = String::from_utf8_lossy(&output.stdout);
let stderr = String::from_utf8_lossy(&output.stderr);
assert_eq!(
output.status.code().unwrap_or(1),
0,
"stderr={stderr}\nstdout={stdout}"
);
assert!(
stdout.contains("f02-agent-selection-ok"),
"stdout={stdout}"
);
assert!(stdout.contains("resume-save-ok") && stdout.contains("resume-load-ok"));
let captured = seen.lock().unwrap().join("\n");
assert!(
!captured.is_empty(),
"mock received no HTTP; stdout={stdout}"
);
// Body may embed the .mq.md source (which mentions the poison string in prose).
// Assert the OpenAI `model` field itself — not a raw substring of the whole HTTP dump.
let model_field = captured
.split("\r\n\r\n")
.nth(1)
.unwrap_or("")
.lines()
.next()
.unwrap_or("");
let body: Value = serde_json::from_str(model_field).unwrap_or_else(|_| {
// Some captures concatenate multiple HTTP messages; take last `{...}` blob.
let start = captured.rfind('{').expect("json body");
serde_json::from_str(&captured[start..]).expect("parse chat body")
});
assert_eq!(
body["model"].as_str(),
Some("f02-selected-model"),
"upstream model field: {body}"
);
assert_ne!(body["model"].as_str(), Some("env-poison-model"));
}
+140
View File
@@ -0,0 +1,140 @@
//! Live workbench gates — skipped unless OPENAI_API_KEY is set (never commit secrets).
use std::process::Command;
fn live_key() -> Option<String> {
for k in ["OPENAI_API_KEY", "MARQDO_LLM_API_KEY"] {
if let Ok(v) = std::env::var(k) {
let t = v.trim();
if !t.is_empty() && t != "sk-test" {
return Some(t.to_string());
}
}
}
None
}
fn repo_ext() -> std::path::PathBuf {
std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("ext")
}
fn ensure_llm_plugin() {
let status = Command::new("cargo")
.args(["build", "-p", "marqdo_plugin_llm", "--locked"])
.current_dir(env!("CARGO_MANIFEST_DIR"))
.status()
.expect("build llm plugin");
assert!(status.success());
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let so = root.join("target/debug/libllm.so");
if so.is_file() {
std::env::set_var("MARQDO_LLM_PLUGIN", &so);
}
// Prefer in-tree ext/ over ~/.marqdo/ext (search roots list user install first).
std::env::set_var("MARQDO_EXT", repo_ext());
}
#[test]
fn live_selection_ask_pong() {
let Some(_key) = live_key() else {
eprintln!("skip live_selection_ask_pong: no API key");
return;
};
ensure_llm_plugin();
if std::env::var_os("OPENAI_BASE_URL").is_none() {
eprintln!("skip: set OPENAI_BASE_URL (e.g. https://api.llm.ustc.edu.cn/v1)");
return;
}
if std::env::var_os("OPENAI_MODEL").is_none() {
std::env::set_var("OPENAI_MODEL", "qwen3.8-chat");
}
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", "tests/ext/workbench-selection-live.mq.md"])
.current_dir(env!("CARGO_MANIFEST_DIR"))
.env("MARQDO_EXT", repo_ext())
.env("MARQDO_LLM_PLUGIN", std::env::var_os("MARQDO_LLM_PLUGIN").unwrap_or_default())
.output()
.expect("run workbench-selection-live");
let code = output.status.code().unwrap_or(1);
let stdout = String::from_utf8_lossy(&output.stdout);
let stderr = String::from_utf8_lossy(&output.stderr);
assert_eq!(code, 0, "stderr={stderr}\nstdout={stdout}");
let lower = stdout.to_lowercase();
assert!(lower.contains("pong"), "expected pong, got {stdout:?}");
assert!(
stdout.contains("usage-present") || stdout.contains("usage-unknown"),
"expected usage line, got {stdout:?}"
);
}
#[test]
fn live_dual_model_isolation_via_plugin() {
let Some(key) = live_key() else {
eprintln!("skip live_dual_model_isolation_via_plugin: no API key");
return;
};
let base = match std::env::var("OPENAI_BASE_URL") {
Ok(v) if !v.trim().is_empty() => v,
_ => {
eprintln!("skip: OPENAI_BASE_URL required");
return;
}
};
ensure_llm_plugin();
// Two sequential asks with different model ids — both must succeed without env clobber.
for model in ["qwen3.8-chat", "deepseek-flash"] {
std::env::set_var("OPENAI_MODEL", model);
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", "tests/ext/workbench-selection-live.mq.md"])
.current_dir(env!("CARGO_MANIFEST_DIR"))
.env("OPENAI_API_KEY", &key)
.env("OPENAI_BASE_URL", &base)
.env("OPENAI_MODEL", model)
.env("MARQDO_EXT", repo_ext())
.env(
"MARQDO_LLM_PLUGIN",
std::env::var_os("MARQDO_LLM_PLUGIN").unwrap_or_default(),
)
.output()
.expect("run");
let stdout = String::from_utf8_lossy(&output.stdout);
let stderr = String::from_utf8_lossy(&output.stderr);
assert_eq!(
output.status.code().unwrap_or(1),
0,
"model={model} stderr={stderr} stdout={stdout}"
);
assert!(
stdout.to_lowercase().contains("pong"),
"model={model} stdout={stdout}"
);
}
}
#[test]
fn cli_view_document_writes_embed_html() {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let out = root.join("target/workbench-docview.html");
let _ = std::fs::remove_file(&out);
let status = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args([
"view",
"document",
"--project",
root.join("tests/executable_knowledge/baseline/02-extract")
.to_str()
.unwrap(),
"--document",
"main.mq.md",
"--out",
out.to_str().unwrap(),
])
.current_dir(&root)
.status()
.expect("view document");
assert!(status.success());
let html = std::fs::read_to_string(&out).expect("read html");
assert!(html.contains("mq-document"));
assert!(!html.contains("<script"));
assert!(html.contains("execution") || html.contains("mq-document"));
}