diff --git a/doc/design/qdagent-workbench-runtime-and-view-2026-10-25.md b/doc/design/qdagent-workbench-runtime-and-view-2026-10-25.md index 8494657..2e96f38 100644 --- a/doc/design/qdagent-workbench-runtime-and-view-2026-10-25.md +++ b/doc/design/qdagent-workbench-runtime-and-view-2026-10-25.md @@ -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 历史基线记录(设计起草时) diff --git a/ext/ai/llm.mq.md b/ext/ai/llm.mq.md index 5932827..d50187b 100644 --- a/ext/ai/llm.mq.md +++ b/ext/ai/llm.mq.md @@ -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` diff --git a/plugins/llm/src/lib.rs b/plugins/llm/src/lib.rs index 2a668ca..2182cfd 100644 --- a/plugins/llm/src/lib.rs +++ b/plugins/llm/src/lib.rs @@ -363,9 +363,12 @@ fn chat_completions(args: &Value) -> Result { .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 diff --git a/src/main.rs b/src/main.rs index df87243..a16ed72 100644 --- a/src/main.rs +++ b/src/main.rs @@ -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, + + /// 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, + }, } fn main() -> ExitCode { @@ -1105,6 +1122,56 @@ fn try_main(cli: Cli) -> Result { })?; 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!( + "{title}
{fragment}
" + ); + 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(".")), diff --git a/tests/ext/workbench-agent-selection.mq.md b/tests/ext/workbench-agent-selection.mq.md new file mode 100644 index 0000000..cddf2c0 --- /dev/null +++ b/tests/ext/workbench-agent-selection.mq.md @@ -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 diff --git a/tests/ext/workbench-selection-live.mq.md b/tests/ext/workbench-selection-live.mq.md new file mode 100644 index 0000000..996e60b --- /dev/null +++ b/tests/ext/workbench-selection-live.mq.md @@ -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 diff --git a/tests/workbench_contracts.rs b/tests/workbench_contracts.rs index 2873dac..daecfa2 100644 --- a/tests/workbench_contracts.rs +++ b/tests/workbench_contracts.rs @@ -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::().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")); +} diff --git a/tests/workbench_live.rs b/tests/workbench_live.rs new file mode 100644 index 0000000..73f76ec --- /dev/null +++ b/tests/workbench_live.rs @@ -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 { + 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("