From 1a39a53d93c0f0e707c43181afa19f370544aa2c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:30:03 +0800 Subject: [PATCH 01/74] feat(agent): add fail-closed small-model choice parser and tests --- plugins/agent/src/choice.rs | 152 ++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 plugins/agent/src/choice.rs diff --git a/plugins/agent/src/choice.rs b/plugins/agent/src/choice.rs new file mode 100644 index 0000000..5a4e300 --- /dev/null +++ b/plugins/agent/src/choice.rs @@ -0,0 +1,152 @@ +//! Fail-closed choice parsing for small-model routing. +//! This module only extracts a value; it never resolves or executes a SKILL. + +use serde_json::{json, Value}; + +fn canonical(s: &str) -> String { + s.trim() + .trim_matches(|c: char| matches!(c, '"' | '\'' | '`' | '“' | '”' | '‘' | '’')) + .trim() + .to_lowercase() +} + +fn strip_fence(s: &str) -> &str { + let s = s.trim(); + if !s.starts_with("```") { + return s; + } + let Some(start) = s.find('\n') else { + return s; + }; + let body = &s[start + 1..]; + let Some(end) = body.find("```") else { + return s; + }; + if !body[end + 3..].trim().is_empty() { + return s; + } + body[..end].trim() +} + +fn strip_label(s: &str) -> &str { + let s = s.trim(); + let Some((head, tail)) = s.split_once([':', ':']) else { + return s; + }; + if matches!( + head.trim().to_lowercase().as_str(), + "choice" | "option" | "selected" | "选择" | "选项" | "答案" + ) { + tail.trim() + } else { + s + } +} + +fn single_choice(options: &[String], reply: &str) -> Option { + let raw = strip_label(strip_fence(reply)); + let value = canonical(raw); + // Never infer a routing decision from arbitrary prose. + let matches: Vec<&String> = options + .iter() + .filter(|opt| canonical(opt) == value) + .collect(); + if matches.len() == 1 { + return Some(matches[0].clone()); + } + // A bare number denotes a 1-based index into the allowed list. + if let Ok(index) = value.parse::() { + if index > 0 && index <= options.len() { + return Some(options[index - 1].clone()); + } + } + None +} + +/// Parse one permitted option from a small model response. +/// Returns a status rather than treating arbitrary prose as a tool target. +pub fn parse_choice(args: &Value) -> Result { + let reply = args + .get("reply") + .and_then(Value::as_str) + .ok_or_else(|| "missing text `reply`".to_string())?; + let options = args + .get("options") + .and_then(Value::as_array) + .ok_or_else(|| "options must be an array of strings".to_string())?; + if options.is_empty() || options.len() > 64 { + return Err("options must contain 1..=64 entries".to_string()); + } + let mut allowed = Vec::with_capacity(options.len()); + for option in options { + let name = option + .as_str() + .ok_or_else(|| "each option must be a string".to_string())?; + if name.trim().is_empty() || name.len() > 128 { + return Err("each option must contain 1..=128 UTF-8 bytes".to_string()); + } + if allowed.iter().any(|p: &String| canonical(p) == canonical(name)) { + return Err("options must be unique after normalization".to_string()); + } + allowed.push(name.to_string()); + } + if let Some(value) = single_choice(&allowed, reply) { + Ok(json!({"ok": true, "value": value, "status": "accepted"})) + } else { + Ok(json!({ + "ok": false, + "value": null, + "status": "invalid", + "error": { + "code": "model.invalid_choice", + "category": "invalid_output", + "retryable": false, + "recovery_action": "repair_output" + } + })) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn check(reply: &str) -> Value { + parse_choice(&json!({"options": ["chat", "office"], "reply": reply})).unwrap() + } + + #[test] + fn accepts_exact_label_fence_and_number() { + assert_eq!(check("chat")["value"], "chat"); + assert_eq!(check(" CHAT ")["value"], "chat"); + assert_eq!(check("选择:office")["value"], "office"); + assert_eq!(check("```text\nchat\n```")["value"], "chat"); + assert_eq!(check("2")["value"], "office"); + } + + #[test] + fn refuses_prose_conflicts_and_out_of_range() { + for reply in ["请选择 chat", "chat 或 office", "choice: chat,因为更合适", "3", ""] { + let result = check(reply); + assert_eq!(result["ok"], false, "accepted {reply:?}"); + assert_eq!(result["value"], Value::Null); + } + } + + #[test] + fn rejects_invalid_options_before_parsing() { + for options in [ + json!([]), + json!(["chat", "CHAT"]), + json!(["chat", 10]), + json!([""]), + ] { + assert!(parse_choice(&json!({"options": options, "reply": "chat"})).is_err()); + } + } + + #[test] + fn never_extracts_arbitrary_skill_path() { + assert_eq!(check("../../private.mq.md")["ok"], false); + } +} From b3867c46dbaee154ed710e26f390a8c14226e297 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:30:10 +0800 Subject: [PATCH 02/74] feat(agent): register native choice parser in plugin ABI --- plugins/agent/src/lib.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 1bcabef..23783c6 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -1,5 +1,6 @@ //! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb + v2 memory + adaptive route. +mod choice; mod context_pack; mod corpus; mod effects; @@ -834,6 +835,7 @@ kb_ffi!(agent_resume_save, resume::resume_save, "agent_resume_save"); kb_ffi!(agent_resume_load, resume::resume_load, "agent_resume_load"); kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear"); kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list"); +kb_ffi!(agent_choice_parse, choice::parse_choice, "agent_choice_parse"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -963,6 +965,7 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_resume_load", "id,resume_dir", agent_resume_load), ("agent_resume_clear", "id,resume_dir", agent_resume_clear), ("agent_resume_list", "resume_dir", agent_resume_list), + ("agent_choice_parse", "reply,options", agent_choice_parse), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From c299efe58971134b8af63508e31e7ca0a50d8c99 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:30:22 +0800 Subject: [PATCH 03/74] feat(ai): add thin model-choice and parallel-document flow library --- ext/ai/flow.mq.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 ext/ai/flow.mq.md diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md new file mode 100644 index 0000000..123f4a4 --- /dev/null +++ b/ext/ai/flow.mq.md @@ -0,0 +1,83 @@ +--- +markup: occlusion +title: AI flow — small-model choices and bounded subtasks +description: Short model decisions, verified options and concurrent Marqdo documents. +import: + llm: ext/ai/llm.mq.md + json: lib/json.mq.md + plugin: lib/plugin.mq.md + subtask: lib/subtask.mq.md +--- + +This is the thin author-facing layer. A model returns a candidate; Marqdo checks +it before routing. Invalid choices are not SKILL paths and never execute. +Only the requested function and its inputs need to be in the model prompt. + +## parse_choice + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| reply | text | required | Raw model reply, treated as data | +| options | list | required | Allowed names, not paths or commands | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | {ok,value,status} or {ok:false,error} | + +Parsing accepts one exact name, a labeled name, a fenced name or a 1-based +index. Ambiguous prose fails closed. Parsing never runs a tool or SKILL. + +We retain **p = [Locate the installed agent plugin](plugin.native_path(name="agent"))**. +1. p + We **[Load the agent plugin](plugin.load(path=`p`))**. +2. * + Return *[Missing native parser](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"value\":null}"))*. + +Return *[Parse and verify the choice](agent_choice_parse(reply=`reply`, options=`options`))*. + +## choose + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| input | text | required | Current user request or local decision | +| options | list | required | Small list of registered option names | +| model | any | None | Existing provider model identifier | +| repair | bool | True | Allow one format-only repair attempt | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Verified choice result, or explicit failure | + +Only ask for the option name. A failed first parse can receive one short +format correction; never silently select the nearest-looking option. + +We retain **opts = [Encode allowed values](json.stringify(value=`options`))**. +We retain **prompt = "Choose exactly one of these options. Return its name only, no explanation:\n" + opts + "\nInput:\n" + input**. +We retain **reply = [Ask the model once](llm.ask(prompt=`prompt`, model=`model`))**. +We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**. +We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. +1. ok + Return *parsed*. +2. `repair` + We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**. + We retain **again = [Retry the format only once](llm.ask(prompt=`fix`, model=`model`))**. + Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*. +3. * + Return *parsed*. + +## parallel + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| tasks | list | required | Existing .mq.md file tasks with arguments | +| limit | number | 2 | Maximum simultaneously running tasks | +| timeout_ms | number | 30000 | Execution timeout in milliseconds | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | list | Ordered child outcomes, including failures | + +Reuse the built-in subtask scheduler. Each child document returns via its +# main, and successful siblings remain visible if another child fails. + +Return *[Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))*. From 7fdd97f675e25d0bba358d6352151c175931f0df Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:30:33 +0800 Subject: [PATCH 04/74] feat(agent): classify invalid model output and bound local recovery --- plugins/agent/src/error.rs | 41 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/plugins/agent/src/error.rs b/plugins/agent/src/error.rs index 5223b82..d9a6317 100644 --- a/plugins/agent/src/error.rs +++ b/plugins/agent/src/error.rs @@ -82,6 +82,10 @@ pub fn decide_retry(args: &Value) -> Result { .get("max_arg_repairs") .and_then(|v| v.as_u64()) .unwrap_or(1) as u32; + let max_output_repair = args + .get("max_output_repairs") + .and_then(|v| v.as_u64()) + .unwrap_or(1) as u32; let effect_class = args .get("effect_class") .and_then(|v| v.as_str()) @@ -145,6 +149,12 @@ pub fn decide_retry(args: &Value) -> Result { "invalid_arguments" if recovery == "repair_args" && attempts < max_arg_repair => Ok( decision("repair_args", "one_arg_repair", attempts, max_arg_repair), ), + "invalid_output" if recovery == "repair_output" && attempts < max_output_repair => Ok( + decision("repair_output", "one_format_repair", attempts, max_output_repair), + ), + "context_overflow" if recovery == "compact_context" && attempts == 0 => Ok( + decision("compact_context", "one_bounded_compaction", attempts, 1), + ), "auth" | "forbidden" | "policy_denied" => Ok(decision( "needs_input", category, @@ -172,13 +182,17 @@ fn decision(action: &str, reason: &str, attempts: u32, max_attempts: u32) -> Val "reason": reason, "attempts_used": attempts, "max_attempts": max_attempts, - "auto": matches!(action, "retry_step" | "repair_args"), + "auto": matches!(action, "retry_step" | "repair_args" | "repair_output" | "compact_context"), }) } fn infer_category(code: &str) -> &'static str { let c = code.to_ascii_lowercase(); - if c.contains("timeout") || c.contains("429") || c.contains("5xx") || c.contains("connect") { + if c.contains("context_overflow") || c.contains("context_length") { + "context_overflow" + } else if c.contains("invalid_choice") || c.contains("invalid_output") { + "invalid_output" + } else if c.contains("timeout") || c.contains("429") || c.contains("5xx") || c.contains("connect") { "transient" } else if c.contains("schema") || c.contains("argument") { "invalid_arguments" @@ -212,6 +226,8 @@ fn default_recovery(category: &str, effect_state: &str) -> &'static str { match category { "transient" => "retry_step", "invalid_arguments" => "repair_args", + "invalid_output" => "repair_output", + "context_overflow" => "compact_context", "auth" | "forbidden" | "policy_denied" | "needs_input" => "needs_input", "budget_exhausted" => "return_partial", "cancelled" => "stop", @@ -259,6 +275,27 @@ mod tests { assert_eq!(d["auto"], false); } + #[test] + fn output_repair_is_bounded_and_read_only() { + let err = make_error(&json!({"code": "model.invalid_choice"})).unwrap(); + assert_eq!(err["category"], "invalid_output"); + let first = decide_retry(&json!({"error": err, "attempts": 0})).unwrap(); + assert_eq!(first["action"], "repair_output"); + let next = decide_retry(&json!({"error": err, "attempts": 1})).unwrap(); + assert_eq!(next["action"], "stop"); + let write = decide_retry(&json!({ + "error": err, "attempts": 0, "effect_class": "write" + })).unwrap(); + assert_eq!(write["action"], "manual_review"); + } + + #[test] + fn compaction_is_not_an_unbounded_model_loop() { + let err = make_error(&json!({"code": "model.context_overflow"})).unwrap(); + assert_eq!(decide_retry(&json!({"error": err, "attempts": 0})).unwrap()["action"], "compact_context"); + assert_eq!(decide_retry(&json!({"error": err, "attempts": 1})).unwrap()["action"], "stop"); + } + #[test] fn fingerprint_loop_stops() { let err = make_error(&json!({"code": "tool.timeout"})).unwrap(); From d88ed274ed1a9368ef828909dcca3e388f240e19 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:30:49 +0800 Subject: [PATCH 05/74] feat(ai): expose short checkpoint and bounded recovery functions --- ext/ai/recovery.mq.md | 64 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 ext/ai/recovery.mq.md diff --git a/ext/ai/recovery.mq.md b/ext/ai/recovery.mq.md new file mode 100644 index 0000000..c38867e --- /dev/null +++ b/ext/ai/recovery.mq.md @@ -0,0 +1,64 @@ +--- +markup: occlusion +title: AI recovery — safe defaults for short SKILL functions +description: Reuse the native error policy, durable checkpoints and effect ledger. +import: + agent: ext/ai/agent.mq.md +--- + +Error handling belongs to Marqdo, not the model's prompt. The native policy +never blindly repeats uncertain writes. Every resume must revalidate the +current permission and source revision; a saved checkpoint is not authorization. + +## decide + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| error | map | required | Structured AgentErrorV1 | +| attempts | number | 0 | Number of attempts already made | +| effect_class | text | "read" | Declared tool effect | +| cancelled | bool | False | Parent cancellation status | +| fingerprint_repeats | number | 0 | Identical failures without new evidence | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Safe recovery action with budget | + +This returns an action, not an automatic retry or permission to execute. For +write or unknown effect, consult the effect ledger before taking another step. + +Return *[Select a bounded recovery action](agent.error_decide_retry(error=`error`, attempts=`attempts`, effect_class=`effect_class`, cancelled=`cancelled`, fingerprint_repeats=`fingerprint_repeats`))*. + +## save + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable logical run ID | +| task | any | None | Current task or user request | +| status | text | "waiting_input" | Current run status | +| effect_ledger_watermark | any | None | Durable ledger boundary if available | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | CheckpointV2 write result | + +Use the existing atomic checkpoint writer. When ledger evidence is absent, +a resumed writer requires manual review rather than automatic repetition. +This function saves metadata; it does not suspend a Rust execution frame. + +Return *[Save a versioned checkpoint](agent.resume_save(id=`id`, task=`task`, status=`status`, checkpoint_v2=True, effect_ledger_watermark=`effect_ledger_watermark`))*. + +## load + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Previously saved logical run ID | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Checkpoint or missing/unsafe recovery status | + +Loading a checkpoint does not execute any saved step. The caller must inspect +recovery_mode and write_auto_resume before dispatching any effectful operation. + +Return *[Inspect the saved checkpoint](agent.resume_load(id=`id`))*. From eed4f05ea465a5497ff16ecb54b79ceaa3a11a71 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:31:14 +0800 Subject: [PATCH 06/74] ci(agent): test native parser and check the new Marqdo flow modules --- .github/workflows/executable-knowledge.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index 2dcecd5..b44ef1f 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -15,6 +15,12 @@ jobs: run: | cargo build -p marqdo_plugin_agent --locked cargo build -p marqdo_plugin_llm --locked + - name: Native agent choice and bounded recovery unit tests + run: cargo test -p marqdo_plugin_agent --locked + - name: Check short AI flow documents + run: | + cargo run --locked -- check ext/ai/flow.mq.md + cargo run --locked -- check ext/ai/recovery.mq.md - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate From e64f6b23b4eae5e78756e69d945f5d833bd82f64 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:32:04 +0800 Subject: [PATCH 07/74] fix(ai): use valid Marqdo branch expressions and literal main reference --- ext/ai/flow.mq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 123f4a4..972f722 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -28,7 +28,7 @@ Parsing accepts one exact name, a labeled name, a fenced name or a 1-based index. Ambiguous prose fails closed. Parsing never runs a tool or SKILL. We retain **p = [Locate the installed agent plugin](plugin.native_path(name="agent"))**. -1. p +1. `p` We **[Load the agent plugin](plugin.load(path=`p`))**. 2. * Return *[Missing native parser](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"value\":null}"))*. @@ -56,7 +56,7 @@ We retain **prompt = "Choose exactly one of these options. Return its name only, We retain **reply = [Ask the model once](llm.ask(prompt=`prompt`, model=`model`))**. We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**. We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. -1. ok +1. `ok` Return *parsed*. 2. `repair` We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**. @@ -78,6 +78,6 @@ We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. | result | list | Ordered child outcomes, including failures | Reuse the built-in subtask scheduler. Each child document returns via its -# main, and successful siblings remain visible if another child fails. +`# main`, and successful siblings remain visible if another child fails. Return *[Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))*. From b0ee958fcf131f8282645df79f29cb34f6fa9fb1 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:32:48 +0800 Subject: [PATCH 08/74] feat(ai): add explicit small-model file/class/function context pack --- ext/ai/context.mq.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 ext/ai/context.mq.md diff --git a/ext/ai/context.mq.md b/ext/ai/context.mq.md new file mode 100644 index 0000000..a99ef71 --- /dev/null +++ b/ext/ai/context.mq.md @@ -0,0 +1,41 @@ +--- +markup: occlusion +title: AI context — short, explicit source scopes +description: Pack user input and caller-provided file/class/function excerpts. +import: + agent: ext/ai/agent.mq.md +--- + +Pass only the documentation that the next model decision needs. The supplied +file/class/function snippets are data; they do not execute as Marqdo source. +A future compiler-backed selector can supply these arguments from AST spans. +This helper does not yet infer class/function scopes automatically. + +## pack + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| user | text | required | Latest user input | +| file | text | "" | File-level description excerpt | +| class | text | "" | Current class excerpt | +| function | text | "" | Current function excerpt | +| budget_tokens | number | 2048 | Small-model context budget | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Bounded ContextPackV2 and compaction evidence | + +Keep the latest request and current function first. Low-priority file context +may be dropped under pressure; any important constraint must be in a retained +field, not in a discardable tool transcript. + +`items` = + +| @ | origin | trust | priority | text | retain | +|---|---|---|---|---|---| +| 1 | user | user | 0 | `user` | True | +| 2 | function | unknown | 1 | `function` | True | +| 3 | class | unknown | 2 | `class` | False | +| 4 | file | unknown | 3 | `file` | False | + +Return *[Pack the supplied scopes and compact redundant context](agent.context_pack_compact(items=`items`, budget_tokens=`budget_tokens`, goal=`user`))*. From bdedf3ecd86efc19768274489d3846830b5cbfe8 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:32:55 +0800 Subject: [PATCH 09/74] ci(ai): include scoped context pack in syntax gates --- .github/workflows/executable-knowledge.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index b44ef1f..6d3882d 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -21,6 +21,7 @@ jobs: run: | cargo run --locked -- check ext/ai/flow.mq.md cargo run --locked -- check ext/ai/recovery.mq.md + cargo run --locked -- check ext/ai/context.mq.md - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate From f56deffefeafd6a5c1bee15cf97fc906fdba4b6d Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:33:28 +0800 Subject: [PATCH 10/74] test(agent): isolate EffectLedger tests without process-global cwd races --- plugins/agent/src/effects.rs | 64 +++++++++++++++++------------------- 1 file changed, 30 insertions(+), 34 deletions(-) diff --git a/plugins/agent/src/effects.rs b/plugins/agent/src/effects.rs index bd80c0f..8c4ff03 100644 --- a/plugins/agent/src/effects.rs +++ b/plugins/agent/src/effects.rs @@ -425,12 +425,16 @@ fn fnv64(s: &str) -> u64 { mod tests { use super::*; + // Avoid process-global set_current_dir: Rust executes tests concurrently. + // Keep each ledger in its own repository-relative, unique directory. + static SCRATCH_SEQ: std::sync::atomic::AtomicU64 = + std::sync::atomic::AtomicU64::new(0); + fn scratch(tag: &str) -> PathBuf { - let dir = std::env::temp_dir().join(format!( + let seq = SCRATCH_SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed); + let dir = PathBuf::from("target").join(format!( "mq-effects-{}-{}-{}", - tag, - std::process::id(), - now_rfc3339().replace(':', "") + tag, std::process::id(), seq )); let _ = fs::remove_dir_all(&dir); fs::create_dir_all(&dir).unwrap(); @@ -440,14 +444,13 @@ mod tests { #[test] fn prepare_dedupe_and_collision() { let dir = scratch("prep"); - let prev = std::env::current_dir().unwrap(); - std::env::set_current_dir(&dir).unwrap(); + let ledger_dir = dir.join("led").to_string_lossy().to_string(); let a = effects_prepare(&json!({ "operation_id": "op1", "idempotency_key": "idem1", "args_digest": "sha256:a", "effect_class": "write", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run1", })) .unwrap(); @@ -458,7 +461,7 @@ mod tests { "operation_id": "op1", "idempotency_key": "idem1", "args_digest": "sha256:a", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); assert_eq!(again["deduped"], true); @@ -467,43 +470,41 @@ mod tests { "operation_id": "op2", "idempotency_key": "idem1", "args_digest": "sha256:b", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })); assert!(clash.unwrap_err().contains("collision")); - std::env::set_current_dir(prev).unwrap(); let _ = fs::remove_dir_all(&dir); } #[test] fn transition_and_watermark_gates_write_resume() { let dir = scratch("wm"); - let prev = std::env::current_dir().unwrap(); - std::env::set_current_dir(&dir).unwrap(); + let ledger_dir = dir.join("led").to_string_lossy().to_string(); effects_prepare(&json!({ "operation_id": "op_w", "idempotency_key": "idem_w", "args_digest": "sha256:w", "effect_class": "write", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run1", })) .unwrap(); effects_transition(&json!({ "operation_id": "op_w", "state": "started", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); // Crash window: unknown — write auto-resume must stay closed. effects_transition(&json!({ "operation_id": "op_w", "state": "unknown", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); let wm1 = effects_watermark(&json!({ - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run1", })) .unwrap(); @@ -513,12 +514,12 @@ mod tests { effects_reconcile(&json!({ "operation_id": "op_w", "outcome": "committed", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "result_ref": "receipt:1", })) .unwrap(); let wm2 = effects_watermark(&json!({ - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run1", })) .unwrap(); @@ -526,7 +527,6 @@ mod tests { assert_eq!(wm2["open_unknown"], 0); assert!(wm2["watermark"].as_str().unwrap().starts_with("sha256-lite:")); - std::env::set_current_dir(prev).unwrap(); let _ = fs::remove_dir_all(&dir); } @@ -535,32 +535,31 @@ mod tests { // Write "succeeds" locally only after reconcile; retry while unknown must not // look write_auto_resume_safe (MA-T03 watermark gate). let dir = scratch("mat03"); - let prev = std::env::current_dir().unwrap(); - std::env::set_current_dir(&dir).unwrap(); + let ledger_dir = dir.join("led").to_string_lossy().to_string(); effects_prepare(&json!({ "operation_id": "op_kill", "idempotency_key": "run|s|write_probe|sha256-lite:1", "args_digest": "sha256-lite:1", "effect_class": "write", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run_kill", })) .unwrap(); effects_transition(&json!({ "operation_id": "op_kill", "state": "started", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); // Crash before commit: effects_transition(&json!({ "operation_id": "op_kill", "state": "unknown", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); let wm = effects_watermark(&json!({ - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run_kill", })) .unwrap(); @@ -572,7 +571,7 @@ mod tests { "idempotency_key": "run|s|write_probe|sha256-lite:1", "args_digest": "sha256-lite:1", "effect_class": "write", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run_kill", })) .unwrap(); @@ -582,42 +581,39 @@ mod tests { effects_reconcile(&json!({ "operation_id": "op_kill", "outcome": "committed", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "result_ref": "effect:op_kill", })) .unwrap(); let wm2 = effects_watermark(&json!({ - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), "logical_run_id": "run_kill", })) .unwrap(); assert_eq!(wm2["write_auto_resume_safe"], true); assert_eq!(wm2["pending_writes"], 0); - std::env::set_current_dir(prev).unwrap(); let _ = fs::remove_dir_all(&dir); } #[test] fn illegal_skip_started() { let dir = scratch("bad"); - let prev = std::env::current_dir().unwrap(); - std::env::set_current_dir(&dir).unwrap(); + let ledger_dir = dir.join("led").to_string_lossy().to_string(); effects_prepare(&json!({ "operation_id": "op_x", "idempotency_key": "idem_x", "args_digest": "sha256:x", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap(); let err = effects_transition(&json!({ "operation_id": "op_x", "state": "committed", - "ledger_dir": "led", + "ledger_dir": ledger_dir.clone(), })) .unwrap_err(); assert!(err.contains("illegal transition")); - std::env::set_current_dir(prev).unwrap(); let _ = fs::remove_dir_all(&dir); } } From 9564dff777d1aca972ae4af4679c40021efad8fc Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:34:13 +0800 Subject: [PATCH 11/74] docs(ai): link the new native flow, context and recovery modules --- ext/ai/index.mq.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/ext/ai/index.mq.md b/ext/ai/index.mq.md index 70ac986..197615e 100644 --- a/ext/ai/index.mq.md +++ b/ext/ai/index.mq.md @@ -9,7 +9,11 @@ Start here to choose an AI task. [Model calls](llm.mq.md) own prompts, model con stream collection and usage; [provider adapters](llm/index.mq.md) describe OpenAI-compatible and Ollama requests. [Agents](agent.mq.md) own call-site context, the explicit tool registry, policy routing, observations, workbook planning and continuation. [CoW trials](sandbox.mq.md) -own isolated file changes and promotion. [Step routing](policies/step-route.mq.md) is readable +own isolated file changes and promotion. [Native flow](flow.mq.md) provides short, verified model choices and bounded document +concurrency; [context](context.mq.md) packs explicit source scopes; [recovery](recovery.mq.md) +uses the native error policy and versioned checkpoints. These are lightweight +interfaces, not a second agent runtime. +[Step routing](policies/step-route.mq.md) is readable policy data, not a second agent language. Chinese users can start at [索引](索引.mq.md). Begin with this offline stream example; it does not request credentials, install a plugin or From 3613ed7c4eb12225f129e59caabe323bc0be5310 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:36:26 +0800 Subject: [PATCH 12/74] fix(ai): declare function parameters in Marqdo prose syntax --- ext/ai/flow.mq.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 972f722..3741f8c 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -24,6 +24,8 @@ Only the requested function and its inputs need to be in the model prompt. |---|---|---| | result | map | {ok,value,status} or {ok:false,error} | +Use `reply`, `options` as the inputs for this operation. + Parsing accepts one exact name, a labeled name, a fenced name or a 1-based index. Ambiguous prose fails closed. Parsing never runs a tool or SKILL. @@ -48,6 +50,8 @@ Return *[Parse and verify the choice](agent_choice_parse(reply=`reply`, options= |---|---|---| | result | map | Verified choice result, or explicit failure | +Use `input`, `options`, `model`=None, `repair`=True as the inputs for this operation. + Only ask for the option name. A failed first parse can receive one short format correction; never silently select the nearest-looking option. @@ -77,6 +81,8 @@ We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. |---|---|---| | result | list | Ordered child outcomes, including failures | +Use `tasks`, `limit`=2, `timeout_ms`=30000 as the inputs for this operation. + Reuse the built-in subtask scheduler. Each child document returns via its `# main`, and successful siblings remain visible if another child fails. From a82b6fdde1c706cd2becc3d0191a8255f2835418 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:36:28 +0800 Subject: [PATCH 13/74] fix(ai): declare function parameters in Marqdo prose syntax --- ext/ai/context.mq.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ext/ai/context.mq.md b/ext/ai/context.mq.md index a99ef71..c564cc5 100644 --- a/ext/ai/context.mq.md +++ b/ext/ai/context.mq.md @@ -25,6 +25,8 @@ This helper does not yet infer class/function scopes automatically. |---|---|---| | result | map | Bounded ContextPackV2 and compaction evidence | +Use `user`, `file`="", `class`="", `function`="", `budget_tokens`=2048 as the inputs for this operation. + Keep the latest request and current function first. Low-priority file context may be dropped under pressure; any important constraint must be in a retained field, not in a discardable tool transcript. From a0c779e022e42b862b3da566692786285a04c45b Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:36:31 +0800 Subject: [PATCH 14/74] fix(ai): declare function parameters in Marqdo prose syntax --- ext/ai/recovery.mq.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ext/ai/recovery.mq.md b/ext/ai/recovery.mq.md index c38867e..afe2e47 100644 --- a/ext/ai/recovery.mq.md +++ b/ext/ai/recovery.mq.md @@ -24,6 +24,8 @@ current permission and source revision; a saved checkpoint is not authorization. |---|---|---| | result | map | Safe recovery action with budget | +Use `error`, `attempts`=0, `effect_class`="read", `cancelled`=False, `fingerprint_repeats`=0 as the inputs for this operation. + This returns an action, not an automatic retry or permission to execute. For write or unknown effect, consult the effect ledger before taking another step. @@ -42,6 +44,8 @@ Return *[Select a bounded recovery action](agent.error_decide_retry(error=`error |---|---|---| | result | map | CheckpointV2 write result | +Use `id`, `task`=None, `status`="waiting_input", `effect_ledger_watermark`=None as the inputs for this operation. + Use the existing atomic checkpoint writer. When ledger evidence is absent, a resumed writer requires manual review rather than automatic repetition. This function saves metadata; it does not suspend a Rust execution frame. @@ -58,6 +62,8 @@ Return *[Save a versioned checkpoint](agent.resume_save(id=`id`, task=`task`, st |---|---|---| | result | map | Checkpoint or missing/unsafe recovery status | +Use `id` as the inputs for this operation. + Loading a checkpoint does not execute any saved step. The caller must inspect recovery_mode and write_auto_resume before dispatching any effectful operation. From 0d9bd99fc012474adc976c3fd6e6b0ad0a9977e2 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:36:52 +0800 Subject: [PATCH 15/74] feat(agent): add Markdown heading-scoped bounded file/class/function prompt projection with tests --- plugins/agent/src/context_scope.rs | 201 +++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 plugins/agent/src/context_scope.rs diff --git a/plugins/agent/src/context_scope.rs b/plugins/agent/src/context_scope.rs new file mode 100644 index 0000000..bb9a148 --- /dev/null +++ b/plugins/agent/src/context_scope.rs @@ -0,0 +1,201 @@ +//! Markdown-heading-backed, bounded context projection for Marqdo SKILLs. +//! This is source selection, not execution: quoted text never becomes tool authority. +//! Markdown events ignore fenced-code headings; ambiguous functions fail closed. + +use pulldown_cmark::{Event, HeadingLevel, Parser, Tag, TagEnd}; +use serde_json::{json, Value}; + +#[derive(Clone, Debug)] +struct Section { + level: u8, + title: String, + start: usize, +} + +fn level_num(h: HeadingLevel) -> u8 { + match h { + HeadingLevel::H1 => 1, + HeadingLevel::H2 => 2, + HeadingLevel::H3 => 3, + HeadingLevel::H4 => 4, + HeadingLevel::H5 => 5, + HeadingLevel::H6 => 6, + } +} + +fn headings(source: &str) -> Vec
{ + let mut out = Vec::new(); + let mut pending: Option
= None; + for (event, range) in Parser::new(source).into_offset_iter() { + match event { + Event::Start(Tag::Heading { level, .. }) => { + pending = Some(Section { + level: level_num(level), + title: String::new(), + start: range.start, + }); + } + Event::Text(text) | Event::Code(text) => { + if let Some(section) = pending.as_mut() { + section.title.push_str(&text); + } + } + Event::End(TagEnd::Heading(_)) => { + if let Some(mut section) = pending.take() { + section.title = section.title.trim().to_string(); + out.push(section); + } + } + _ => {} + } + } + out +} + +fn class_for(headings: &[Section], index: usize) -> Option<&str> { + headings[..index] + .iter() + .rev() + .find(|h| h.level == 1) + .map(|h| h.title.as_str()) +} + +fn frontmatter_end(source: &str) -> usize { + if !source.starts_with("---\n") { + return 0; + } + let mut pos = 4; + for line in source[4..].split_inclusive('\n') { + pos += line.len(); + if line.trim() == "---" { + return pos; + } + } + 0 +} + +fn truncate_chars(text: &str, max_chars: usize) -> (&str, bool) { + let Some((end, _)) = text.char_indices().nth(max_chars) else { + return (text, false); + }; + (&text[..end], true) +} + +pub fn project(args: &Value) -> Result { + let source = match args.get("source").and_then(Value::as_str) { + Some(s) => s.to_string(), + None => crate::host_query_json("module_source")? + .as_str() + .ok_or_else(|| "module_source unavailable".to_string())? + .to_string(), + }; + let scope = args.get("scope").and_then(Value::as_str).unwrap_or("function"); + let class = args.get("class").and_then(Value::as_str); + let function = args.get("function").and_then(Value::as_str); + let maximum = args + .get("max_chars") + .and_then(Value::as_u64) + .unwrap_or(1600) + .clamp(32, 16000) as usize; + let marks = headings(&source); + let results: Vec<(usize, usize)> = match scope { + "file" => { + let end = marks.first().map_or(source.len(), |h| h.start); + let start = frontmatter_end(&source).min(end); + vec![(start, end)] + } + "class" | "function" | "tool" => { + let level = match scope { + "class" => 1, + "function" => 2, + _ => 3, + }; + let target = if level == 1 { class } else { function }; + let wanted = target.ok_or_else(|| format!("{scope} selector required"))?; + marks + .iter() + .enumerate() + .filter(|(i, h)| { + h.level == level + && h.title == wanted + && (level == 1 || class.is_none() || class_for(&marks, *i) == class) + }) + .map(|(i, h)| { + let end = marks[i + 1..] + .iter() + .find(|next| next.level <= level) + .map_or(source.len(), |next| next.start); + let end = if level == 1 { + marks[i + 1..] + .iter() + .find(|next| next.level <= 2) + .map_or(end, |next| next.start) + } else { + end + }; + (h.start, end) + }) + .collect() + } + _ => return Err("scope must be file, class, function or tool".to_string()), + }; + if results.len() != 1 { + return Ok(json!({ + "ok": false, + "status": if results.is_empty() { "not_found" } else { "ambiguous" }, + "scope": scope, + "matches": results.len(), + "text": null + })); + } + let (start, end) = results[0]; + let (slice, truncated) = truncate_chars(source[start..end].trim(), maximum); + let line_start = source[..start].bytes().filter(|c| *c == b'\n').count() + 1; + Ok(json!({ + "ok": true, "status": "accepted", "scope": scope, + "text": slice, "truncated": truncated, + "start_byte": start, "end_byte": end, + "start_line": line_start, + "source_kind": "markdown_headings" + })) +} + +#[cfg(test)] +mod tests { + use super::*; + + const DOC: &str = "---\ntitle: example\n---\nEntry instructions.\n\n# main\nClass instructions.\n\n## route\nReal body.\n```md\n## route\nfake\n```\n\n## other\nOther body.\n\n# helper\nHelper prose.\n\n## route\nSecond body.\n"; + + #[test] + fn scope_is_bounded_and_fenced_headings_ignored() { + let v = project(&json!({"source": DOC, "scope": "function", "class": "main", "function": "route"})).unwrap(); + assert_eq!(v["ok"], true); + assert!(v["text"].as_str().unwrap().contains("Real body.")); + assert!(v["text"].as_str().unwrap().contains("fake")); + assert!(!v["text"].as_str().unwrap().contains("Other body.")); + assert!(!v["text"].as_str().unwrap().contains("Second body.")); + } + + #[test] + fn ambiguous_function_fails_closed() { + let v = project(&json!({"source": DOC, "scope": "function", "function": "route"})).unwrap(); + assert_eq!(v["status"], "ambiguous"); + assert_eq!(v["text"], Value::Null); + } + + #[test] + fn file_scope_removes_frontmatter_and_class_prose_excludes_functions() { + let a = project(&json!({"source": DOC, "scope": "file"})).unwrap(); + assert_eq!(a["text"], "Entry instructions."); + let b = project(&json!({"source": DOC, "scope": "class", "class": "main"})).unwrap(); + assert!(b["text"].as_str().unwrap().contains("Class instructions.")); + assert!(!b["text"].as_str().unwrap().contains("Real body.")); + } + + #[test] + fn unicode_truncation_does_not_split_characters() { + let v = project(&json!({"source": "汉".repeat(100), "scope": "file", "max_chars": 32})).unwrap(); + assert_eq!(v["text"].as_str().unwrap().chars().count(), 32); + assert_eq!(v["truncated"], true); + } +} From 393558ca971355466adb2702334a2516c1a5d0bf Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:36:59 +0800 Subject: [PATCH 16/74] feat(agent): register scoped context projection in native plugin --- plugins/agent/Cargo.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/agent/Cargo.toml b/plugins/agent/Cargo.toml index 663e5b8..4965693 100644 --- a/plugins/agent/Cargo.toml +++ b/plugins/agent/Cargo.toml @@ -13,4 +13,5 @@ crate-type = ["cdylib"] [dependencies] marqdo-plugin-sdk = { path = "../../crates/marqdo-plugin-sdk" } serde_json = "1" +pulldown-cmark = "0.12" chrono = { version = "0.4", default-features = false, features = ["clock", "std"] } From f63b7ef48d869ce58473aac2b7bacf4755b104c8 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:37:02 +0800 Subject: [PATCH 17/74] feat(agent): register scoped context projection in native plugin --- plugins/agent/src/lib.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 23783c6..b40587e 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -2,6 +2,7 @@ mod choice; mod context_pack; +mod context_scope; mod corpus; mod effects; mod eng; @@ -836,6 +837,7 @@ kb_ffi!(agent_resume_load, resume::resume_load, "agent_resume_load"); kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear"); kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list"); kb_ffi!(agent_choice_parse, choice::parse_choice, "agent_choice_parse"); +kb_ffi!(agent_context_scope, context_scope::project, "agent_context_scope"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -966,6 +968,7 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_resume_clear", "id,resume_dir", agent_resume_clear), ("agent_resume_list", "resume_dir", agent_resume_list), ("agent_choice_parse", "reply,options", agent_choice_parse), + ("agent_context_scope", "source,scope,class,function", agent_context_scope), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From 905a67df32afa6595f457c1c1e88b64fa696db25 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:37:18 +0800 Subject: [PATCH 18/74] feat(ai): expose native Markdown scope selection to Marqdo authors --- ext/ai/context.mq.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/ext/ai/context.mq.md b/ext/ai/context.mq.md index c564cc5..3905067 100644 --- a/ext/ai/context.mq.md +++ b/ext/ai/context.mq.md @@ -4,6 +4,8 @@ title: AI context — short, explicit source scopes description: Pack user input and caller-provided file/class/function excerpts. import: agent: ext/ai/agent.mq.md + plugin: lib/plugin.mq.md + json: lib/json.mq.md --- Pass only the documentation that the next model decision needs. The supplied @@ -41,3 +43,32 @@ field, not in a discardable tool transcript. | 4 | file | unknown | 3 | `file` | False | Return *[Pack the supplied scopes and compact redundant context](agent.context_pack_compact(items=`items`, budget_tokens=`budget_tokens`, goal=`user`))*. + + +## scope + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| scope | text | "function" | file / class / function / tool | +| class | text | None | Class heading for disambiguation | +| function | text | None | Function/tool heading | +| source | text | None | Source override; otherwise current entry module | +| max_chars | number | 1600 | Maximum Unicode characters | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Exact source excerpt, line range, or explicit ambiguity | + +Use `scope`="function", `class`=None, `function`=None, `source`=None, `max_chars`=1600 as the inputs for this operation. + +The native selector respects Markdown headings and ignores fenced-code heading +lookalikes. Repeated function names require a class; missing/ambiguous scopes +return an error value, never an unrelated or whole-file fallback. + +We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load native agent plugin](plugin.load(path=`p`))**. +2. * + Return *[No native parser available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"text\":null}"))*. + +Return *[Project the requested document scope](agent_context_scope(source=`source`, scope=`scope`, class=`class`, function=`function`, max_chars=`max_chars`))*. From afe31cb2a8f879877a0d52a54056ea0de7feb0b8 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:37:35 +0800 Subject: [PATCH 19/74] feat(agent): durable user-input gate with idempotent reply, revision and session checks --- plugins/agent/src/input.rs | 248 +++++++++++++++++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 plugins/agent/src/input.rs diff --git a/plugins/agent/src/input.rs b/plugins/agent/src/input.rs new file mode 100644 index 0000000..8100f23 --- /dev/null +++ b/plugins/agent/src/input.rs @@ -0,0 +1,248 @@ +//! Durable input gates for document-native SKILLs. +//! Pausing is a committed *step boundary*, not serialization of a Rust stack. +//! The caller resumes the next documented step with the saved answer. + +use std::fs::{self, OpenOptions}; +use std::path::PathBuf; +use serde_json::{json, Value}; + +use crate::resume; + +struct GateLock(PathBuf); +impl Drop for GateLock { + fn drop(&mut self) { + let _ = fs::remove_file(&self.0); + } +} + +fn text_arg<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> { + args.get(key) + .and_then(Value::as_str) + .filter(|s| !s.is_empty()) + .ok_or_else(|| format!("missing text `{key}`")) +} + +fn valid_id(s: &str) -> bool { + !s.is_empty() + && s.len() <= 100 + && s.bytes().all(|c| c.is_ascii_alphanumeric() || c == b'-' || c == b'_') +} + +fn root(args: &Value) -> Result { + let name = args + .get("resume_dir") + .and_then(Value::as_str) + .unwrap_or(".marqdo/agent-resume"); + let path = PathBuf::from(name); + if path.is_absolute() + || path.components().any(|part| matches!(part, std::path::Component::ParentDir)) + { + return Err("resume_dir must be a relative path without '..'".to_string()); + } + fs::create_dir_all(&path).map_err(|e| format!("input gate mkdir: {e}"))?; + Ok(path) +} + +fn lock(args: &Value, id: &str) -> Result { + if !valid_id(id) { + return Err("input gate id must be 1..=100 ASCII letters, numbers, '_' or '-'".into()); + } + let path = root(args)?.join(format!("{id}.input-lock")); + OpenOptions::new() + .write(true) + .create_new(true) + .open(&path) + .map_err(|e| format!("input gate is busy or needs reconciliation: {e}"))?; + Ok(GateLock(path)) +} + +fn options(args: &Value) -> Result { + let choices = args.get("options").and_then(Value::as_array) + .ok_or_else(|| "options must be a list of 1..=32 short labels".to_string())?; + if choices.is_empty() || choices.len() > 32 { + return Err("options must contain 1..=32 choices".into()); + } + for v in choices { + let Some(s) = v.as_str() else { + return Err("every option must be text".into()); + }; + if s.is_empty() || s.len() > 256 { + return Err("each option must contain 1..=256 bytes".into()); + } + } + let empty = crate::choice::parse_choice(&json!({ + "options": choices, "reply": "__invalid_choice_probe__" + }))?; + // The parser checks duplicates and option size; the probe must not be accepted. + if empty["ok"] == true { + return Err("invalid reserved choice option".into()); + } + Ok(Value::Array(choices.to_vec())) +} + +/// Create a durable waiting-input checkpoint. Repeated open never resets a +/// previously answered gate. No external effect is performed. +pub fn input_open(args: &Value) -> Result { + let id = text_arg(args, "id")?; + let _lock = lock(args, id)?; + let labels = options(args)?; + let query = text_arg(args, "question")?; + let version = text_arg(args, "source_revision")?; + let read_args = json!({"id": id, "resume_dir": args.get("resume_dir")}); + let existing = resume::resume_load(&read_args)?; + if existing["found"] == true { + let meta = &existing["meta"]; + let same = meta["question"] == query + && meta["options"] == labels + && meta["source_revision"] == version + && meta["session_id"] == args.get("session_id").unwrap_or(&Value::Null) + && meta["principal_ref"] == args.get("principal_ref").unwrap_or(&Value::Null); + if same && existing["ok"] == true { + let status = existing["status"].as_str().unwrap_or("unknown"); + return Ok(json!({ + "ok": true, "id": id, "status": status, + "value": existing["result"], "reused": true, + "question": query, "options": labels + })); + } + return Ok(json!({"ok":false,"id":id,"status":"conflict", + "error":{"code":"input.stale_or_reused_gate"}})); + } + let saved = resume::resume_save(&json!({ + "id": id, "resume_dir": args.get("resume_dir"), + "checkpoint_v2": true, + "status": "waiting_input", + "task": query, + "meta": { + "question": query, + "options": labels, + "source_revision": version, + "session_id": args.get("session_id").unwrap_or(&Value::Null), + "principal_ref": args.get("principal_ref").unwrap_or(&Value::Null), + "freeform": args.get("freeform").and_then(Value::as_bool).unwrap_or(true) + } + }))?; + if saved["ok"] != true { + return Err("unable to save input checkpoint".into()); + } + Ok(json!({"ok": true, "id":id, "status":"waiting_input", "value":null, + "question":query,"options":labels,"reused":false})) +} + +/// Resume a specific gate with a user response. Only a committed answer can be +/// replayed: different duplicate replies conflict instead of re-triggering work. +pub fn input_resume(args: &Value) -> Result { + let id = text_arg(args, "id")?; + let _lock = lock(args, id)?; + let reply = text_arg(args, "reply")?; + if reply.len() > 4096 { + return Err("input reply must not exceed 4096 bytes".into()); + } + let version = text_arg(args, "source_revision")?; + let read_args = json!({"id": id, "resume_dir": args.get("resume_dir")}); + let existing = resume::resume_load(&read_args)?; + if existing["ok"] != true || existing["schema"] != "CheckpointV2" { + return Ok(json!({"ok":false,"status":"not_found_or_corrupt","id":id})); + } + let meta = &existing["meta"]; + if meta["source_revision"] != version + || meta["session_id"] != *args.get("session_id").unwrap_or(&Value::Null) + || meta["principal_ref"] != *args.get("principal_ref").unwrap_or(&Value::Null) + { + return Ok(json!({"ok":false,"status":"conflict","id":id, + "error":{"code":"input.scope_or_revision_changed"}})); + } + if existing["status"] == "resumed" { + if existing["result"] == reply { + return Ok(json!({"ok":true,"status":"resumed","id":id, + "value":reply,"reused":true})); + } + return Ok(json!({"ok":false,"status":"conflict","id":id, + "error":{"code":"input.already_answered"}})); + } + if existing["status"] != "waiting_input" { + return Ok(json!({"ok":false,"status":"conflict","id":id})); + } + let allowed = crate::choice::parse_choice(&json!({ + "options": meta["options"], "reply": reply + }))?; + let normalized = if allowed["ok"] == true { + allowed["value"].clone() + } else if meta["freeform"] == true && !reply.trim().is_empty() { + json!(reply.trim()) + } else { + return Ok(json!({"ok":false,"status":"invalid","id":id, + "error":{"code":"input.invalid_choice"}})); + }; + let saved = resume::resume_save(&json!({ + "id": id, "resume_dir": args.get("resume_dir"), + "checkpoint_v2": true, + "status": "resumed", + "task": existing["task"], + "meta": meta, + "result": normalized + }))?; + if saved["ok"] != true { + return Err("unable to commit resumed input".into()); + } + Ok(json!({"ok":true,"status":"resumed","id":id, + "value":normalized,"reused":false})) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::sync::atomic::{AtomicU64, Ordering}; + static SEQ: AtomicU64 = AtomicU64::new(0); + + fn fixture() -> (String, String) { + let id = format!("gate_{}_{}",std::process::id(),SEQ.fetch_add(1,Ordering::Relaxed)); + let dir = format!("target/mq-gate-test-{id}"); + (id, dir) + } + + #[test] + fn persists_answer_without_duplicate_side_effect_or_changed_reply() { + let (id, dir) = fixture(); + let initial = json!({"id":id,"resume_dir":dir,"question":"Choose?", + "options":["chat","office"],"source_revision":"v1", + "session_id":"s1","principal_ref":"u1","freeform":false}); + assert_eq!(input_open(&initial).unwrap()["status"], "waiting_input"); + assert_eq!(input_open(&initial).unwrap()["reused"], true); + let v = json!({"id":id,"resume_dir":dir,"reply":"2", + "source_revision":"v1","session_id":"s1","principal_ref":"u1"}); + assert_eq!(input_resume(&v).unwrap()["value"], "office"); + assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir, + "reply":"office","source_revision":"v1","session_id":"s1", + "principal_ref":"u1"})).unwrap()["reused"], true); + assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir, + "reply":"chat","source_revision":"v1","session_id":"s1", + "principal_ref":"u1"})).unwrap()["status"], "conflict"); + assert_eq!(input_open(&initial).unwrap()["status"], "resumed"); + } + + #[test] + fn prevents_changed_source_or_unauthorized_session() { + let (id, dir) = fixture(); + let initial = json!({"id":id,"resume_dir":dir,"question":"Proceed?", + "options":["yes","no"],"source_revision":"v1", + "session_id":"s1","principal_ref":"u1"}); + input_open(&initial).unwrap(); + for (rev,session) in [("v2","s1"),("v1","other")] { + assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,"reply":"yes", + "source_revision":rev,"session_id":session, + "principal_ref":"u1"})).unwrap()["status"], "conflict"); + } + } + + #[test] + fn invalid_choice_keeps_gate_open_and_no_freeform_is_enforced() { + let (id, dir) = fixture(); + input_open(&json!({"id":id,"resume_dir":dir,"question":"Pick", + "options":["a","b"],"freeform":false, + "source_revision":"v1"})).unwrap(); + assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,"reply":"??", + "source_revision":"v1"})).unwrap()["status"], "invalid"); + assert_eq!(resume::resume_load(&json!({"id":id,"resume_dir":dir})).unwrap()["status"], "waiting_input"); + } +} From e8d6dc92fc9c307a9709284355cf0dd5f5bfb442 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:37:44 +0800 Subject: [PATCH 20/74] feat(agent): register user-input pause/reply gate primitives --- plugins/agent/src/lib.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index b40587e..4adf061 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -7,6 +7,7 @@ mod corpus; mod effects; mod eng; mod error; +mod input; mod kb; mod mcp_client; mod mcp_server; @@ -838,6 +839,8 @@ kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear"); kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list"); kb_ffi!(agent_choice_parse, choice::parse_choice, "agent_choice_parse"); kb_ffi!(agent_context_scope, context_scope::project, "agent_context_scope"); +kb_ffi!(agent_input_open, input::input_open, "agent_input_open"); +kb_ffi!(agent_input_resume, input::input_resume, "agent_input_resume"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -969,6 +972,8 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_resume_list", "resume_dir", agent_resume_list), ("agent_choice_parse", "reply,options", agent_choice_parse), ("agent_context_scope", "source,scope,class,function", agent_context_scope), + ("agent_input_open", "id,question,options,source_revision", agent_input_open), + ("agent_input_resume", "id,reply,source_revision", agent_input_resume), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From 5795236d1f0ea945b2860d32d1eb5ec0f413a34a Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:37:56 +0800 Subject: [PATCH 21/74] feat(ai): expose durable step-boundary input/reply in flow SKILL --- ext/ai/flow.mq.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 3741f8c..463c63b 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -87,3 +87,61 @@ Reuse the built-in subtask scheduler. Each child document returns via its `# main`, and successful siblings remain visible if another child fails. Return *[Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))*. + + +## input + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable step ID | +| question | text | required | User-visible question | +| options | list | required | User-visible choices | +| source_revision | text | required | Pinned Marqdo source revision | +| session_id | text | None | Host-attested session | +| principal_ref | text | None | Host-attested user scope | +| freeform | bool | True | Allow custom user reply | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | waiting_input or previously committed reply | + +Use `id`, `question`, `options`, `source_revision`, `session_id`=None, `principal_ref`=None, `freeform`=True as the inputs for this operation. + +This does not park an interpreter stack. The caller persists a step-boundary +checkpoint, displays the question, and on a new turn uses reply to continue. +The host, not the LLM, must attest session and principal IDs. + +We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load native agent plugin](plugin.load(path=`p`))**. +2. * + Return *[No native gate available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +Return *[Persist one waiting input gate](agent_input_open(id=`id`, question=`question`, options=`options`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, freeform=`freeform`))*. + +## reply + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Existing waiting step | +| reply | text | required | New user response | +| source_revision | text | required | Current pinned source revision | +| session_id | text | None | Host-attested session | +| principal_ref | text | None | Host-attested user scope | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Resolved answer, invalid reply or explicit conflict | + +Use `id`, `reply`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +Matching repeated replies are idempotent. A conflicting reply, changed document +or changed session fails without executing any SKILL or side effect. + +We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load native agent plugin](plugin.load(path=`p`))**. +2. * + Return *[No native gate available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +Return *[Commit the verified user reply](agent_input_resume(id=`id`, reply=`reply`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. From d5ab9daebba9df6d234289de381d670e72d6c451 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:38:26 +0800 Subject: [PATCH 22/74] feat(agent): classify parallel child successes, failures and unknown outcomes --- plugins/agent/src/parallel.rs | 81 +++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 plugins/agent/src/parallel.rs diff --git a/plugins/agent/src/parallel.rs b/plugins/agent/src/parallel.rs new file mode 100644 index 0000000..e5d6ad2 --- /dev/null +++ b/plugins/agent/src/parallel.rs @@ -0,0 +1,81 @@ +//! Deterministic fan-out results: never discard a successful sibling and never +//! infer success from a completed wait protocol alone. + +use serde_json::{json, Value}; + +pub fn report(args: &Value) -> Result { + let results = args + .get("results") + .and_then(Value::as_array) + .ok_or_else(|| "results must be ordered subtask result list".to_string())?; + if results.len() > 10_000 { + return Err("parallel result count exceeds scheduler limit".into()); + } + let mut passed = 0usize; + let mut failed = 0usize; + let mut unknown = 0usize; + let mut entries = Vec::with_capacity(results.len()); + for (index, child) in results.iter().enumerate() { + let transport = child.get("ok").and_then(Value::as_bool); + let body = child.get("value").unwrap_or(&Value::Null); + let status = match (transport, body.get("code").and_then(Value::as_i64)) { + (Some(true), Some(0)) => { passed += 1; "succeeded" } + (Some(true), Some(_)) | (Some(false), _) => { failed += 1; "failed" } + _ => { unknown += 1; "uncertain" } + }; + // Raw child result is kept as data; the model sees only an optional + // bounded summary. The host may store detailed output as an artifact. + let detail = child.get("error") + .and_then(Value::as_str) + .or_else(|| body.get("stderr").and_then(Value::as_str)) + .unwrap_or(""); + let brief: String = detail.chars().take(280).collect(); + entries.push(json!({ + "index": index, + "status": status, + "summary": brief, + "result": child + })); + } + let status = if unknown != 0 { + "uncertain" + } else if failed == 0 { + "succeeded" + } else if passed > 0 { + "partial" + } else { + "failed" + }; + Ok(json!({ + "ok": failed == 0 && unknown == 0, + "schema": "AgentParallelResultV1", + "status": status, + "succeeded": passed, + "failed": failed, + "uncertain": unknown, + "items": entries + })) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn preserves_success_and_exposes_failed_child() { + let result = report(&json!({"results":[ + {"ok":true,"value":{"code":0,"value":"good"}}, + {"ok":true,"value":{"code":2,"stderr":"failed"}}, + {"ok":false,"error":"timeout"} + ]})).unwrap(); + assert_eq!(result["status"], "partial"); + assert_eq!(result["succeeded"], 1); + assert_eq!(result["failed"], 2); + assert_eq!(result["items"][0]["status"], "succeeded"); + } + #[test] + fn unknown_child_cannot_be_mislabeled_successful() { + let value = report(&json!({"results":[{"ok":true,"value":{"value":"no code"}}]})).unwrap(); + assert_eq!(value["status"], "uncertain"); + assert_eq!(value["ok"], false); + } +} From c7c0f66d1f94580543c70836cec30e2830372e71 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:38:33 +0800 Subject: [PATCH 23/74] feat(agent): register typed concurrent task result aggregator --- plugins/agent/src/lib.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 4adf061..9c210c8 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -13,6 +13,7 @@ mod mcp_client; mod mcp_server; mod memory; mod output; +mod parallel; mod resume; mod route; mod sandbox; @@ -841,6 +842,7 @@ kb_ffi!(agent_choice_parse, choice::parse_choice, "agent_choice_parse"); kb_ffi!(agent_context_scope, context_scope::project, "agent_context_scope"); kb_ffi!(agent_input_open, input::input_open, "agent_input_open"); kb_ffi!(agent_input_resume, input::input_resume, "agent_input_resume"); +kb_ffi!(agent_parallel_report, parallel::report, "agent_parallel_report"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -974,6 +976,7 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_context_scope", "source,scope,class,function", agent_context_scope), ("agent_input_open", "id,question,options,source_revision", agent_input_open), ("agent_input_resume", "id,reply,source_revision", agent_input_resume), + ("agent_parallel_report", "results", agent_parallel_report), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From b2f97e72c3678e8fa9ebca444389777b97b1a4dc Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:38:58 +0800 Subject: [PATCH 24/74] build(agent): lock pulldown-cmark dependency for native scoped context --- Cargo.lock | 1 + 1 file changed, 1 insertion(+) diff --git a/Cargo.lock b/Cargo.lock index cc963b5..8c8fce1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -668,6 +668,7 @@ version = "0.1.0" dependencies = [ "chrono", "marqdo-plugin-sdk", + "pulldown-cmark", "serde_json", ] From e48fd5b0f4b8dc1e4411b2d409d9034087c02390 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:39:06 +0800 Subject: [PATCH 25/74] feat(ai): aggregate concurrent child status without losing successful siblings --- ext/ai/flow.mq.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 463c63b..26c1c1b 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -79,14 +79,20 @@ We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. | 返回 | 类型 | 说明 | |---|---|---| -| result | list | Ordered child outcomes, including failures | +| result | map | Succeeded, partial, failed or uncertain child outcomes | Use `tasks`, `limit`=2, `timeout_ms`=30000 as the inputs for this operation. Reuse the built-in subtask scheduler. Each child document returns via its `# main`, and successful siblings remain visible if another child fails. -Return *[Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))*. +We retain **results = [Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))**. +We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load native agent plugin](plugin.load(path=`p`))**. + Return *[Preserve success, failure and uncertain child outcomes](agent_parallel_report(results=`results`))*. +2. * + Return *[Native result classifier unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. ## input From cf73fcf1efc33ab534fa9ac3ba9ee0683339f0d0 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:39:37 +0800 Subject: [PATCH 26/74] feat(ai): add allowlisted SKILL enter via standard Marqdo subtasks --- ext/ai/flow.mq.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 26c1c1b..cc7d786 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -151,3 +151,28 @@ We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))** Return *[No native gate available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. Return *[Commit the verified user reply](agent_input_resume(id=`id`, reply=`reply`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + + +## enter + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| skill | text | required | Model-selected registered name | +| registry | map | required | Trusted name → path mapping | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Subtask result, or blocked unknown skill | + +Use `skill`, `registry` as the inputs for this operation. + +Never execute a raw model-generated path. Resolve a registered skill name to +an author-controlled document, then call its `# main` through the normal Marqdo +subtask and effect permissions. The caller must provide a trusted registry. + +We retain **path = [Resolve registered SKILL](json.get(value=`registry`, key=`skill`))**. +1. not `path` + Return *[Unknown skill is blocked](json.parse(text="{\"ok\":false,\"status\":\"unsupported_skill\"}"))*. +2. * + We retain **task = [Spawn registered Marqdo document](subtask.spawn(path=`path`))**. + Return *[Await the subtask result](subtask.wait(id=`task`))*. From 633436e40fbbd94ee574532ff08eef4b5cfa4377 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:39:53 +0800 Subject: [PATCH 27/74] fix(agent): compare owned JSON values with dereferenced optional identity values --- plugins/agent/src/input.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/agent/src/input.rs b/plugins/agent/src/input.rs index 8100f23..f01a935 100644 --- a/plugins/agent/src/input.rs +++ b/plugins/agent/src/input.rs @@ -95,8 +95,8 @@ pub fn input_open(args: &Value) -> Result { let same = meta["question"] == query && meta["options"] == labels && meta["source_revision"] == version - && meta["session_id"] == args.get("session_id").unwrap_or(&Value::Null) - && meta["principal_ref"] == args.get("principal_ref").unwrap_or(&Value::Null); + && meta["session_id"] == *args.get("session_id").unwrap_or(&Value::Null) + && meta["principal_ref"] == *args.get("principal_ref").unwrap_or(&Value::Null); if same && existing["ok"] == true { let status = existing["status"].as_str().unwrap_or("unknown"); return Ok(json!({ From 9031c106a147d9ca188453db734331dbc4466e6c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:40:08 +0800 Subject: [PATCH 28/74] test(ai): add offline Marqdo interpreter smoke for native choice and scoped context --- tests/ext/ai-native-flow.mq.md | 46 ++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 tests/ext/ai-native-flow.mq.md diff --git a/tests/ext/ai-native-flow.mq.md b/tests/ext/ai-native-flow.mq.md new file mode 100644 index 0000000..194e205 --- /dev/null +++ b/tests/ext/ai-native-flow.mq.md @@ -0,0 +1,46 @@ +--- +markup: occlusion +title: AI native flow offline smoke +import: + flow: ext/ai/flow.mq.md + context: ext/ai/context.mq.md + json: lib/json.mq.md + sys: lib/sys.mq.md +--- + +# main + +This fixture tests the real Marqdo interface without a model provider. +It refuses an invalid choice and retrieves only the designated function +rather than guessing another SKILL or importing the full document. + +**opts = > json.parse text=["chat","office"]** +**pick = > flow.parse_choice reply="选择:office" options=`opts`** +**value = > json.get value=`pick` key="value"** +1. `value` == "office" + **_ = 1** +2. * + > sys.exit code=11 + +**invalid = > flow.parse_choice reply="chat 或 office" options=`opts`** +**not_ok = > json.get value=`invalid` key="ok"** +1. `not_ok` + > sys.exit code=12 +2. * + **_ = 1** + +**ctx = > context.scope scope="function" class="main" function="probe" max_chars=200** +**ok = > json.get value=`ctx` key="ok"** +1. `ok` + **_ = 1** +2. * + > sys.exit code=13 + +Return *"ai-flow-native-ok"*. + +## probe + +This private helper's narrative should be extracted by the scoped selector +without including the root SKILL or neighboring function definitions. + +Return *"probe"*. From 88490e3092d7a97b7e4cab86bdb4de4fd2fcac7c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:40:15 +0800 Subject: [PATCH 29/74] ci(ai): execute real native choice and scoped-context Marqdo smoke --- .github/workflows/executable-knowledge.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index 6d3882d..eec00f9 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -22,6 +22,9 @@ jobs: cargo run --locked -- check ext/ai/flow.mq.md cargo run --locked -- check ext/ai/recovery.mq.md cargo run --locked -- check ext/ai/context.mq.md + cargo run --locked -- check tests/ext/ai-native-flow.mq.md + - name: Native AI flow interpreter smoke (offline) + run: cargo run --locked -- run tests/ext/ai-native-flow.mq.md - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate From 02a4f2d20dde223edacbcd9d374869ccdaed9936 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:40:50 +0800 Subject: [PATCH 30/74] fix(agent): skip YAML setext lookalikes in document-scope parser --- plugins/agent/src/context_scope.rs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/plugins/agent/src/context_scope.rs b/plugins/agent/src/context_scope.rs index bb9a148..b970d57 100644 --- a/plugins/agent/src/context_scope.rs +++ b/plugins/agent/src/context_scope.rs @@ -97,7 +97,13 @@ pub fn project(args: &Value) -> Result { .and_then(Value::as_u64) .unwrap_or(1600) .clamp(32, 16000) as usize; - let marks = headings(&source); + // YAML frontmatter may look like a setext Markdown heading; never treat it + // as a Marqdo class or function boundary. + let front_end = frontmatter_end(&source); + let marks: Vec
= headings(&source) + .into_iter() + .filter(|heading| heading.start >= front_end) + .collect(); let results: Vec<(usize, usize)> = match scope { "file" => { let end = marks.first().map_or(source.len(), |h| h.start); From 60a3b84a84de9c005d47b23e88ab505bb70607f9 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:41:08 +0800 Subject: [PATCH 31/74] test(ai): exercise durable input and reply from a real Marqdo program --- tests/ext/ai-native-flow.mq.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tests/ext/ai-native-flow.mq.md b/tests/ext/ai-native-flow.mq.md index 194e205..85a699d 100644 --- a/tests/ext/ai-native-flow.mq.md +++ b/tests/ext/ai-native-flow.mq.md @@ -36,6 +36,14 @@ rather than guessing another SKILL or importing the full document. 2. * > sys.exit code=13 +**gate = > flow.input id="ai_native_flow_ci_gate" question="Continue?" options=`opts` source_revision="fixture-v1" freeform=False** +**answered = > flow.reply id="ai_native_flow_ci_gate" reply="office" source_revision="fixture-v1"** +**answer = > json.get value=`answered` key="value"** +1. `answer` == "office" + **_ = 1** +2. * + > sys.exit code=14 + Return *"ai-flow-native-ok"*. ## probe From c64ec99115f33b87e3f363dcde9cbc35ab3cf37f Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:41:28 +0800 Subject: [PATCH 32/74] feat(ai): expose minimal ask/start/wait on top of native LLM and subtask APIs --- ext/ai/flow.mq.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index cc7d786..b431cb4 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -176,3 +176,60 @@ We retain **path = [Resolve registered SKILL](json.get(value=`registry`, key=`sk 2. * We retain **task = [Spawn registered Marqdo document](subtask.spawn(path=`path`))**. Return *[Await the subtask result](subtask.wait(id=`task`))*. + + +## ask + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| prompt | text | required | Short local prompt | +| model | any | None | Configured model selection | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | text | Model reply (not yet a verified tool call) | + +Use `prompt`, `model`=None as the inputs for this operation. + +Ask only what the current function needs. The reply remains data until an +explicit verifier accepts it. The LLM adapter owns provider configuration. + +Return *[Ask the configured model](llm.ask(prompt=`prompt`, model=`model`))*. + +## start + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| path | text | required | Trusted registered Marqdo document | +| args | list | None | Optional child CLI arguments | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | number | Child task handle | + +Use `path`, `args`=None as the inputs for this operation. + +Start an isolated SKILL document asynchronously, after the calling host has +validated its path and required process.exec permission. No model-generated +raw path is a valid grant. + +Return *[Start one Marqdo document](subtask.spawn(path=`path`, args=`args`))*. + +## wait + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | number | required | Child task handle | +| timeout_ms | number | 30000 | Maximum wait time | +| cancel | bool | False | Cancel on timeout | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Child result, timeout or cancellation | + +Use `id`, `timeout_ms`=30000, `cancel`=False as the inputs for this operation. + +A successful wait protocol is not proof of a successful child execution: +inspect the child exit code before using its result. + +Return *[Wait for the child](subtask.wait_timeout(id=`id`, timeout_ms=`timeout_ms`, cancel=`cancel`))*. From add6a7d32ca84eb369ebc13d6965ea1223057871 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:42:07 +0800 Subject: [PATCH 33/74] docs(agent): record implemented contracts and precise VM/runtime completion gates --- doc/design/native-agent-flow-v3.md | 91 ++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 doc/design/native-agent-flow-v3.md diff --git a/doc/design/native-agent-flow-v3.md b/doc/design/native-agent-flow-v3.md new file mode 100644 index 0000000..d4b37c3 --- /dev/null +++ b/doc/design/native-agent-flow-v3.md @@ -0,0 +1,91 @@ +# Marqdo native agent flow — implementation contract + +Status: **incremental, draft**. This document distinguishes implemented interfaces from +the required interpreter/runtime changes. Do not claim stack-level suspension or +exactly-once external writes based on a checkpoint file. + +## Author surface (implemented in this branch) + +| Module | Function | Contract | +|---|---|---| +| ext/ai/context.mq.md | scope | Select a bounded source excerpt using parsed Markdown headings; ambiguous names fail closed | +| ext/ai/context.mq.md | pack | Compact caller-provided file/class/function text via ContextPackV2 | +| ext/ai/flow.mq.md | ask/choose/parse_choice | One short decision, allowed-choice verification, at most one format repair | +| ext/ai/flow.mq.md | input/reply | Durable step-boundary user-input gate keyed by id + source revision and scope | +| ext/ai/flow.mq.md | start/wait/parallel | Existing Marqdo subtask scheduler, failure-preserving parallel result aggregation | +| ext/ai/flow.mq.md | enter | Resolve only author-supplied registered skill name, run via standard subtask path | +| ext/ai/recovery.mq.md | decide/save/load | Native error policy and CheckpointV2; no implicit unsafe re-execution | + +The native agent plugin provides `agent_choice_parse`, `agent_context_scope`, +`agent_input_open`, `agent_input_resume` and `agent_parallel_report`. +Plugin errors must be visible, never converted into a fabricated successful answer. + +## Invariants + +- A model choice is untrusted data until verified against an explicit option list. +- An imported module is **not** automatically part of a model prompt. +- The requested heading scope, not the entire source file, is the prompt source. +- A pending user-input gate owns a persistent checkpoint, not a blocked interpreter thread. +- The same answer may be returned repeatedly; a competing answer or stale revision conflicts. +- A completed subtask wait is distinct from a successful child exit. +- Existing successful siblings remain visible when one subtask fails. +- Writes, executable effects and external writes remain under ToolSpec permissions, + the EffectLedger and source-version checks. +- No component may silently broaden a tool's authorization on failure. + +## Important limitations in this branch + +The input/reply gate stores an explicit **step boundary**. It does not yet persist +an arbitrary bytecode interpreter frame. Applications must choose and re-enter +their next Marqdo function explicitly after receiving a verified input answer. +The current source selector relies on a Markdown parser plus Marqdo heading +conventions, not on the compiler's resolved module/class/function AST and symbols. +Host identity inputs are supplied by the caller; production applications must +attest them from their authenticated session, never use model-generated identity. +The parallel wrapper reuses `subtask.run_many` and does not add durable child +lease orchestration. Live provider tests and real 1B-model benchmarking remain open. + +## Required VM/runtime completion: suspended execution + +1. Introduce `WaitingInput` as a scheduler state, distinct from terminal failure. + Save the logical run, program counter at a safe suspension boundary, bound + inputs, variable snapshot, module and tool digests, and effect watermark. +2. Resume via a new attempt linked to the original logical run, but never + automatically repeat committed effects. Preserve cancellation and budget. +3. The resume endpoint must be atomic (revision CAS), authenticate principal + and workspace, verify source and tool schema revisions, and deduplicate + repeated reply requests. Do not trust IDs inside model text. +4. Handle interrupted worker, partial snapshot, stale input, invalid choice and + unknown external write as separate outcomes. Treat unknown writes as + reconciliation-required; do not invent exactly-once guarantees. +5. Persist only serializable language values at declared safe points. If a + foreign kernel, socket or native handle is live, explicitly refuse + transparent frame recovery and preserve a safe step-level restart option. + +## Required durable parallel execution + +A parent dispatches child `.mq.md` functions using registered paths, grants +minimal capabilities, shares budget and rate limits, and persists a child task +manifest. Child completion records a status, value ref, output digest and ledger +watermark before the parent merges results. For same-resource writes, use +serialized revisions and explicit commit order. On parent cancellation, stop +new children and request child cancellation; do not assume remote writes rolled +back. On recovery, reconcile child attempts and reuse successful results. + +## Release gates + +| Test | Required observation | +|---|---| +| compiler/import check | All new `.mq.md` functions pass contract checks and execute via ABI | +| small model outputs | Exact, labeled, fenced and numeric options normalize; mixed options fail | +| input gate crash | After checkpoint, reply is committed once; alternate reply conflicts | +| source drift | Original gate cannot resume against changed source revision | +| context isolation | Class/function selectors reject ambiguity and ignore fenced headings | +| concurrent partial | Failed/uncertain child never discards successful siblings | +| unknown write | Neither retry nor recovered child duplicates an unconfirmed effect | +| long-run cancellation | Worker/child task termination preserves usable artifacts and receipts | +| compatibility | Existing `agent.step/plan/run` and workbooks remain callable | +| model evaluation | Tokens/decision, semantic validity, end-to-end completion, recovery overhead | + +Do not merge the branch as a completed runtime refactor until the relevant +runtime gates, including crash injection and multi-worker concurrency, pass. From edbf241d99e863752fac64d11dc19678b290490c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:43:24 +0800 Subject: [PATCH 34/74] feat(ai): compose current user and scoped file/class/function source into a bounded context pack --- ext/ai/context.mq.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/ext/ai/context.mq.md b/ext/ai/context.mq.md index 3905067..375ba07 100644 --- a/ext/ai/context.mq.md +++ b/ext/ai/context.mq.md @@ -72,3 +72,42 @@ We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))** Return *[No native parser available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"text\":null}"))*. Return *[Project the requested document scope](agent_context_scope(source=`source`, scope=`scope`, class=`class`, function=`function`, max_chars=`max_chars`))*. + + +## compose + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| user | text | required | Latest user input | +| class | text | required | Current class name | +| function | text | required | Current function name | +| source | text | None | Override current entry source | +| budget_tokens | number | 2048 | Small-model context budget | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | ContextPackV2 or an explicit failed selector | + +Use `user`, `class`, `function`, `source`=None, `budget_tokens`=2048 as the inputs for this operation. + +Project file, class and function scopes independently. Refuse ambiguous names +rather than silently importing an unrelated class or the entire source. The +latest user input stays in the retained portion of the resulting context pack. + +We retain **f = [Select file preface](scope(scope="file", source=`source`, max_chars=500))**. +We retain **c = [Select current class](scope(scope="class", class=`class`, source=`source`, max_chars=800))**. +We retain **n = [Select current function](scope(scope="function", class=`class`, function=`function`, source=`source`, max_chars=1500))**. +We retain **f_ok = [Check file selection](json.get(value=`f`, key="ok"))**. +We retain **c_ok = [Check class selection](json.get(value=`c`, key="ok"))**. +We retain **n_ok = [Check function selection](json.get(value=`n`, key="ok"))**. +1. not `f_ok` + Return *f*. +2. not `c_ok` + Return *c*. +3. not `n_ok` + Return *n*. +4. * + We retain **ft = [Read file preface](json.get(value=`f`, key="text"))**. + We retain **ct = [Read class explanation](json.get(value=`c`, key="text"))**. + We retain **nt = [Read function explanation](json.get(value=`n`, key="text"))**. + Return *[Compact only the selected scopes](pack(user=`user`, file=`ft`, class=`ct`, function=`nt`, budget_tokens=`budget_tokens`))*. From ee677478be37fe30fc3e238d1b929183ae3bc2bf Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:43:30 +0800 Subject: [PATCH 35/74] test(ai): verify file/class/function context composition in Marqdo interpreter --- tests/ext/ai-native-flow.mq.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/tests/ext/ai-native-flow.mq.md b/tests/ext/ai-native-flow.mq.md index 85a699d..cce2a01 100644 --- a/tests/ext/ai-native-flow.mq.md +++ b/tests/ext/ai-native-flow.mq.md @@ -36,6 +36,13 @@ rather than guessing another SKILL or importing the full document. 2. * > sys.exit code=13 +**packed = > context.compose user="Test the route" class="main" function="probe" budget_tokens=2048** +**pack_schema = > json.get value=`packed` key="schema"** +1. `pack_schema` == "ContextPackV2" + **_ = 1** +2. * + > sys.exit code=15 + **gate = > flow.input id="ai_native_flow_ci_gate" question="Continue?" options=`opts` source_revision="fixture-v1" freeform=False** **answered = > flow.reply id="ai_native_flow_ci_gate" reply="office" source_revision="fixture-v1"** **answer = > json.get value=`answered` key="value"** From 629ad8ed39177951569514a88e84379c9de377f3 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:43:59 +0800 Subject: [PATCH 36/74] feat(agent): tolerate short deterministic small-model selection phrases --- plugins/agent/src/choice.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/plugins/agent/src/choice.rs b/plugins/agent/src/choice.rs index 5a4e300..b3b8db7 100644 --- a/plugins/agent/src/choice.rs +++ b/plugins/agent/src/choice.rs @@ -45,6 +45,12 @@ fn strip_label(s: &str) -> &str { fn single_choice(options: &[String], reply: &str) -> Option { let raw = strip_label(strip_fence(reply)); + // Small models often prepend a short selection verb. Accept only the + // verb followed by a complete allowed value; explanations stay invalid. + let raw = raw.trim(); + let raw = ["我选择", "我选", "I choose ", "I pick ", "选中"].iter() + .find_map(|p| raw.strip_prefix(p).map(str::trim)) + .unwrap_or(raw); let value = canonical(raw); // Never infer a routing decision from arbitrary prose. let matches: Vec<&String> = options @@ -122,6 +128,8 @@ mod tests { assert_eq!(check("选择:office")["value"], "office"); assert_eq!(check("```text\nchat\n```")["value"], "chat"); assert_eq!(check("2")["value"], "office"); + assert_eq!(check("我选择 chat")["value"], "chat"); + assert_eq!(check("I choose office")["value"], "office"); } #[test] From 2dfa0b2a5becb347f67efac08aeac899c4e4ba8f Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:46:24 +0800 Subject: [PATCH 37/74] fix(ai): do not mistake LLM transport errors for choices or trigger format repair --- ext/ai/flow.mq.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index b431cb4..346fd69 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -57,15 +57,26 @@ format correction; never silently select the nearest-looking option. We retain **opts = [Encode allowed values](json.stringify(value=`options`))**. We retain **prompt = "Choose exactly one of these options. Return its name only, no explanation:\n" + opts + "\nInput:\n" + input**. -We retain **reply = [Ask the model once](llm.ask(prompt=`prompt`, model=`model`))**. -We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**. +We retain **m = [Build one model handle](llm.create(model=`model`))**. +We retain **turn = [Ask the model once](m.ask(prompt=`prompt`))**. +We retain **err = [Check model transport error](json.get(value=`turn`, key="error"))**. +1. `err` + Return *turn*. +2. * + We retain **reply = [Read model answer](json.get(value=`turn`, key="text"))**. + We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**. We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. 1. `ok` Return *parsed*. 2. `repair` We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**. - We retain **again = [Retry the format only once](llm.ask(prompt=`fix`, model=`model`))**. - Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*. + We retain **fixed = [Retry the format only once](m.ask(prompt=`fix`))**. + We retain **repair_error = [Read transport error](json.get(value=`fixed`, key="error"))**. + 1. `repair_error` + Return *fixed*. + 2. * + We retain **again = [Read corrected answer](json.get(value=`fixed`, key="text"))**. + Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*. 3. * Return *parsed*. From 06e61efc51d62e2bcd3c8c6ee6fa950b358b9a0d Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:51:51 +0800 Subject: [PATCH 38/74] feat(agent): implement plugin-only durable step workflow with deterministic next/commit/cancel and tests --- plugins/agent/src/workflow.rs | 346 ++++++++++++++++++++++++++++++++++ 1 file changed, 346 insertions(+) create mode 100644 plugins/agent/src/workflow.rs diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs new file mode 100644 index 0000000..d96b174 --- /dev/null +++ b/plugins/agent/src/workflow.rs @@ -0,0 +1,346 @@ +//! Plugin-only durable step workflow. +//! No interpreter-frame serialization: every model/tool decision is a checkpointed +//! transition. This state machine issues actions but never executes arbitrary code. + +use std::fs::{self, OpenOptions}; +use std::path::PathBuf; +use serde_json::{json, Value}; + +use crate::{choice, parallel, resume}; + +const MAX_STEPS: usize = 128; + +struct Guard(PathBuf); +impl Drop for Guard { + fn drop(&mut self) { let _ = fs::remove_file(&self.0); } +} + +fn field<'a>(v: &'a Value, key: &str) -> Result<&'a str, String> { + v.get(key).and_then(Value::as_str).filter(|x| !x.is_empty()) + .ok_or_else(|| format!("workflow requires text {key}")) +} + +fn safe_key(s: &str) -> bool { + !s.is_empty() && s.len() <= 100 + && s.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_') +} + +fn storage(args: &Value) -> Result { + let rel = args.get("resume_dir").and_then(Value::as_str) + .unwrap_or(".marqdo/agent-resume"); + let path = PathBuf::from(rel); + if path.is_absolute() || path.components().any(|part| + matches!(part, std::path::Component::ParentDir | std::path::Component::Prefix(_))) + { + return Err("resume_dir must be relative with no parent traversal".into()); + } + let base = crate::host_query_json("cwd").ok() + .and_then(|v| v.as_str().map(PathBuf::from)) + .unwrap_or(std::env::current_dir().map_err(|e| e.to_string())?); + let dir = base.join(path); + fs::create_dir_all(&dir).map_err(|e| format!("workflow mkdir: {e}"))?; + Ok(dir) +} + +fn lock(args: &Value, id: &str) -> Result { + if !safe_key(id) { + return Err("workflow id must be <=100 ASCII letters, numbers, - or _".into()); + } + let path = storage(args)?.join(format!("{id}.flow-lock")); + OpenOptions::new().write(true).create_new(true).open(&path) + .map_err(|e| format!("workflow busy or stale lock; review before recovering: {e}"))?; + Ok(Guard(path)) +} + +fn checkpoint_args(args: &Value, id: &str) -> Value { + json!({"id": id, "resume_dir": args.get("resume_dir")}) +} + +fn read(args: &Value, id: &str) -> Result { + resume::resume_load(&checkpoint_args(args,id)) +} + +fn context(args: &Value) -> Value { + json!({ + "source_revision": args.get("source_revision").cloned().unwrap_or(Value::Null), + "session_id": args.get("session_id").cloned().unwrap_or(Value::Null), + "principal_ref": args.get("principal_ref").cloned().unwrap_or(Value::Null) + }) +} + +fn check_context(args: &Value, ckpt: &Value) -> bool { + ckpt["meta"]["identity"] == context(args) +} + +fn validate_steps(args: &Value) -> Result { + let steps = args.get("steps").and_then(Value::as_array) + .ok_or_else(|| "steps must be a list".to_string())?; + if steps.is_empty() || steps.len() > MAX_STEPS { + return Err("steps must contain 1..=128 items".into()); + } + let mut seen = std::collections::HashSet::new(); + for s in steps { + let id = field(s, "id")?; + if !safe_key(id) || !seen.insert(id) { + return Err("step ids must be unique safe identifiers".into()); + } + let kind = field(s, "kind")?; + if !matches!(kind, "model" | "input" | "skill" | "parallel" | "return") { + return Err(format!("unsupported step kind: {kind}")); + } + if matches!(kind, "model" | "input") { + let options = s.get("options").and_then(Value::as_array) + .ok_or_else(|| "choice step requires options list".to_string())?; + let _ = choice::parse_choice(&json!({"reply":"","options":options}))?; + if kind == "input" { let _ = field(s, "question")?; } + } + if kind == "skill" { let _ = field(s, "skill")?; } + if kind == "parallel" && !s.get("tasks").is_some_and(Value::is_array) { + return Err("parallel step requires tasks array".into()); + } + } + Ok(Value::Array(steps.clone())) +} + +fn state(ckpt: &Value) -> Result<(&Value,usize),String> { + let meta = ckpt.get("meta").ok_or("missing workflow metadata")?; + if meta.get("kind").and_then(Value::as_str) != Some("MarqdoAgentFlowV1") { + return Err("checkpoint is not a workflow".into()); + } + let index = meta.get("cursor").and_then(Value::as_u64) + .ok_or("missing workflow cursor")? as usize; + Ok((meta,index)) +} + +fn save(args: &Value, id: &str, meta: &Value, status: &str) -> Result<(),String> { + let result = resume::resume_save(&json!({ + "id": id, + "resume_dir": args.get("resume_dir"), + "checkpoint_v2": true, + "status": status, + "meta": meta, + "completed_steps": meta["completed"], + "step_id": meta["steps"].get(meta["cursor"].as_u64().unwrap_or(0) as usize) + .and_then(|x| x.get("id")).cloned().unwrap_or(Value::Null) + }))?; + if result["ok"] != true { return Err("workflow checkpoint write failed".into()); } + Ok(()) +} + +/// Register a bounded, frozen plan. Re-opening never resets a progressed plan. +pub fn open(args: &Value) -> Result { + let id = field(args,"id")?; + let _guard = lock(args,id)?; + let revision = field(args,"source_revision")?; + if revision.len()>256 { return Err("source_revision too long".into()); } + let steps = validate_steps(args)?; + let existing = read(args,id)?; + let identity = context(args); + if existing["found"] == true { + if existing["ok"] == true + && existing["meta"]["identity"] == identity + && existing["meta"]["steps"] == steps + { + return next_doc(&existing,id,true); + } + return Ok(json!({"ok":false,"status":"conflict","error":"workflow.id_or_revision_reused"})); + } + let meta = json!({ + "kind":"MarqdoAgentFlowV1", + "identity":identity, + "steps":steps, + "cursor":0, + "completed":[], + }); + save(args,id,&meta,"running")?; + Ok(json!({"ok":true,"id":id,"status":"created","cursor":0})) +} + +fn next_doc(ckpt: &Value, id: &str, reused: bool) -> Result { + let (meta,index)=state(ckpt)?; + let steps = meta["steps"].as_array().ok_or("invalid steps")?; + if index>=steps.len() { + return Ok(json!({"ok":true,"id":id,"status":"succeeded", + "cursor":index,"completed":meta["completed"],"reused":reused})); + } + let step=&steps[index]; + let status=ckpt["status"].as_str().unwrap_or("running"); + if status=="blocked" || status=="uncertain" || status=="cancelled" { + return Ok(json!({"ok":false,"id":id,"status":status, + "cursor":index,"step":step,"completed":meta["completed"]})); + } + let waiting=match step["kind"].as_str().unwrap_or("") { + "model"=>"waiting_model", + "input"=>"waiting_input", + "skill" | "parallel"=>"ready_tool", + "return"=>"ready_return", + _=>"blocked" + }; + Ok(json!({"ok":true,"id":id,"status":waiting, + "cursor":index,"step":step,"completed":meta["completed"],"reused":reused})) +} + +/// Query the durable next action. This is non-blocking and does not invoke LLM. +pub fn next(args: &Value) -> Result { + let id=field(args,"id")?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"id":id,"status":"not_found_or_mismatched"})); + } + next_doc(&ckpt,id,false) +} + +/// Commit a verified result for the exact current step. All mutations are +/// serialized with a lock; a completed step cannot be committed a second time. +pub fn commit(args: &Value) -> Result { + let id=field(args,"id")?; + let _guard=lock(args,id)?; + let step_id=field(args,"step_id")?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"status":"not_found_or_mismatched"})); + } + let (meta,index)=state(&ckpt)?; + let steps=meta["steps"].as_array().ok_or("invalid steps")?; + let response=args.get("response").ok_or("missing response")?; + if index>=steps.len() { + let previous = meta["completed"].as_array().ok_or("invalid completed")?; + if previous.iter().any(|x|x["step_id"]==step_id && x["value"]==*response) { + return Ok(json!({"ok":true,"status":"succeeded","reused":true})); + } + return Ok(json!({"ok":false,"status":"already_finished"})); + } + let step=&steps[index]; + if step["id"]!=step_id { + if meta["completed"].as_array().is_some_and(|list| + list.iter().any(|x|x["step_id"]==step_id && x["value"]==*response)) + { + return Ok(json!({"ok":true,"status":"already_committed","reused":true})); + } + return Ok(json!({"ok":false,"status":"step_conflict"})); + } + if ckpt["status"]!="running" { + return Ok(json!({"ok":false,"status":"blocked","reason":ckpt["status"]})); + } + let kind=field(step,"kind")?; + let value = match kind { + "model" | "input" => { + let reply = response.as_str().ok_or("model/input response must be text")?; + let valid=choice::parse_choice(&json!({"options":step["options"],"reply":reply}))?; + if valid["ok"]!=true { + return Ok(json!({"ok":false,"status":"invalid_choice", + "error":valid["error"]})); + } + valid["value"].clone() + } + "skill" => { + if response["ok"]!=true { + return Ok(json!({"ok":false,"status":"tool_not_verified", + "reason":"only verified successful tool result may be committed"})); + } + response.clone() + } + "parallel" => { + let report=parallel::report(&json!({"results":response}))?; + if report["ok"]!=true { + return Ok(json!({"ok":false, + "status": if report["uncertain"].as_u64().unwrap_or(0)>0 { + "uncertain" } else {"partial"}, + "report":report, + "reason":"preserve successful children; reconcile or retry failed children separately"})); + } + report + } + "return" => response.clone(), + _ => return Err("invalid step kind".into()), + }; + let mut new_meta=meta.clone(); + new_meta["cursor"]=json!(index+1); + new_meta["completed"].as_array_mut().ok_or("completed not array")? + .push(json!({"step_id":step_id,"value":value})); + let terminal=index+1==steps.len(); + save(args,id,&new_meta,if terminal {"succeeded"} else {"running"})?; + Ok(json!({"ok":true,"id":id, + "status":if terminal {"succeeded"} else {"advanced"}, + "cursor":index+1,"value":value,"reused":false})) +} + +pub fn cancel(args: &Value) -> Result { + let id=field(args,"id")?; + let _guard=lock(args,id)?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"status":"not_found_or_mismatched"})); + } + if ckpt["status"]=="succeeded" { + return Ok(json!({"ok":false,"status":"already_finished"})); + } + let (meta,_)=state(&ckpt)?; + save(args,id,meta,"cancelled")?; + Ok(json!({"ok":true,"id":id,"status":"cancelled"})) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::sync::atomic::{AtomicU64,Ordering}; + static SEQ: AtomicU64=AtomicU64::new(0); + fn fixture()->Value { + let n=SEQ.fetch_add(1,Ordering::Relaxed); + json!({"id":format!("wf-{}-{n}",std::process::id()), + "resume_dir":format!("target/workflow-test-{}-{n}",std::process::id()), + "source_revision":"v1", + "steps":[ + {"id":"choose","kind":"model","options":["chat","office"]}, + {"id":"answer","kind":"input","question":"OK?","options":["yes","no"]}, + {"id":"end","kind":"return"} + ]}) + } + + #[test] + fn nonblocking_model_then_input_then_terminal() { + let a=fixture(); + assert_eq!(open(&a).unwrap()["status"],"created"); + assert_eq!(next(&a).unwrap()["status"],"waiting_model"); + let mut c=a.clone(); + c["step_id"]=json!("choose"); + c["response"]=json!("office"); + assert_eq!(commit(&c).unwrap()["status"],"advanced"); + assert_eq!(next(&a).unwrap()["status"],"waiting_input"); + assert_eq!(commit(&c).unwrap()["status"],"already_committed"); + c["step_id"]=json!("answer"); + c["response"]=json!("yes"); + assert_eq!(commit(&c).unwrap()["status"],"advanced"); + c["step_id"]=json!("end"); + c["response"]=json!("ok"); + assert_eq!(commit(&c).unwrap()["status"],"succeeded"); + assert_eq!(next(&a).unwrap()["status"],"succeeded"); + assert_eq!(open(&a).unwrap()["status"],"succeeded"); + } + + #[test] + fn source_change_conflict_and_invalid_model_choice() { + let a=fixture(); + open(&a).unwrap(); + let mut bad=a.clone(); + bad["source_revision"]=json!("v2"); + assert_eq!(next(&bad).unwrap()["status"],"not_found_or_mismatched"); + assert_eq!(open(&bad).unwrap()["status"],"conflict"); + let mut c=a.clone(); + c["step_id"]=json!("choose"); + c["response"]=json!("chat or office"); + assert_eq!(commit(&c).unwrap()["status"],"invalid_choice"); + assert_eq!(next(&a).unwrap()["status"],"waiting_model"); + } + + #[test] + fn explicit_cancel_stops_future_commits() { + let a=fixture(); + open(&a).unwrap(); + assert_eq!(cancel(&a).unwrap()["status"],"cancelled"); + let mut c=a.clone(); + c["step_id"]=json!("choose"); + c["response"]=json!("chat"); + assert_eq!(commit(&c).unwrap()["status"],"blocked"); + } +} From 1e1f05c087e91da15b36f7310fba7a7ac965e542 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:51:59 +0800 Subject: [PATCH 39/74] feat(agent): register ABI workflow state transitions and cancellation --- plugins/agent/src/lib.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 9c210c8..829ccac 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -18,6 +18,7 @@ mod resume; mod route; mod sandbox; mod tools; +mod workflow; use std::collections::HashMap; use std::ffi::CString; @@ -843,6 +844,10 @@ kb_ffi!(agent_context_scope, context_scope::project, "agent_context_scope"); kb_ffi!(agent_input_open, input::input_open, "agent_input_open"); kb_ffi!(agent_input_resume, input::input_resume, "agent_input_resume"); kb_ffi!(agent_parallel_report, parallel::report, "agent_parallel_report"); +kb_ffi!(agent_workflow_open, workflow::open, "agent_workflow_open"); +kb_ffi!(agent_workflow_next, workflow::next, "agent_workflow_next"); +kb_ffi!(agent_workflow_commit, workflow::commit, "agent_workflow_commit"); +kb_ffi!(agent_workflow_cancel, workflow::cancel, "agent_workflow_cancel"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -977,6 +982,10 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_input_open", "id,question,options,source_revision", agent_input_open), ("agent_input_resume", "id,reply,source_revision", agent_input_resume), ("agent_parallel_report", "results", agent_parallel_report), + ("agent_workflow_open", "id,steps,source_revision", agent_workflow_open), + ("agent_workflow_next", "id,source_revision", agent_workflow_next), + ("agent_workflow_commit", "id,step_id,response,source_revision", agent_workflow_commit), + ("agent_workflow_cancel", "id,source_revision", agent_workflow_cancel), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From 8d47507d15573defcddc139e7bcead1f1826fe1c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:52:13 +0800 Subject: [PATCH 40/74] feat(ai): expose a concise ABI-backed durable workflow library --- ext/ai/workflow.mq.md | 105 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 ext/ai/workflow.mq.md diff --git a/ext/ai/workflow.mq.md b/ext/ai/workflow.mq.md new file mode 100644 index 0000000..56ef207 --- /dev/null +++ b/ext/ai/workflow.mq.md @@ -0,0 +1,105 @@ +--- +markup: occlusion +title: Native AI workflow — durable, short, one-step-at-a-time execution +description: Plugin-managed checkpointed decision flow without an external agent runtime. +import: + plugin: lib/plugin.mq.md + json: lib/json.mq.md + flow: ext/ai/flow.mq.md +--- + +Every step is an explicit commit boundary. The plugin stores accepted outputs, +refuses stale documents and conflicting decisions, and exposes the next action. +The caller must supply trusted session, principal and source revision fields; +model text is never an identity or permission token. + +## open + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable run ID | +| steps | list | required | 1–128 ordered step records | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Created, resumed, or explicit conflict | + +Use `id`, `steps`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Open durable workflow](agent_workflow_open(id=`id`, steps=`steps`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## next + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable run ID | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Current action or terminal state | + +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Find the next committed boundary](agent_workflow_next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## commit + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable run ID | +| step_id | text | required | Exact current step | +| response | any | required | Completed step output | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Committed next step or explicit failure | + +Use `id`, `step_id`, `response`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Validate and commit one step](agent_workflow_commit(id=`id`, step_id=`step_id`, response=`response`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## cancel + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable run ID | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Cancelled checkpoint status | + +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Commit cancellation](agent_workflow_cancel(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. From f818834ec1565ecff1cd3971eb5d84318d4c0bbf Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:52:35 +0800 Subject: [PATCH 41/74] test(ai): exercise ABI-only durable workflow in actual Marqdo interpreter --- tests/ext/ai-native-workflow.mq.md | 59 ++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 tests/ext/ai-native-workflow.mq.md diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md new file mode 100644 index 0000000..b643ce8 --- /dev/null +++ b/tests/ext/ai-native-workflow.mq.md @@ -0,0 +1,59 @@ +--- +markup: occlusion +title: ABI-native durable agent workflow test +import: + workflow: ext/ai/workflow.mq.md + json: lib/json.mq.md + sys: lib/sys.mq.md +--- + +# main + +Offline test: the same Marqdo program advances through model choice, user +input and terminal state with plugin-owned durable checkpoints. + +**steps = > json.parse text=[{"id":"intent","kind":"model","options":["chat","office"]},{"id":"confirm","kind":"input","question":"Continue?","options":["yes","no"]},{"id":"end","kind":"return"}]** +**opened = > workflow.open id="abi_flow_ci_20261118" steps=`steps` source_revision="flow-v1"** +**o = > json.get value=`opened` key="ok"** +1. `o` + **_ = 1** +2. * + > sys.exit code=21 + +**first = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**first_state = > json.get value=`first` key="status"** +1. `first_state` == "waiting_model" + **_ = 1** +2. * + > sys.exit code=22 + +**c1 = > workflow.commit id="abi_flow_ci_20261118" step_id="intent" response="chat" source_revision="flow-v1"** +**done1 = > json.get value=`c1` key="ok"** +1. `done1` + **_ = 1** +2. * + > sys.exit code=23 + +**second = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**second_state = > json.get value=`second` key="status"** +1. `second_state` == "waiting_input" + **_ = 1** +2. * + > sys.exit code=24 + +**c2 = > workflow.commit id="abi_flow_ci_20261118" step_id="confirm" response="yes" source_revision="flow-v1"** +**done2 = > json.get value=`c2` key="ok"** +1. `done2` + **_ = 1** +2. * + > sys.exit code=25 + +**c3 = > workflow.commit id="abi_flow_ci_20261118" step_id="end" response="finished" source_revision="flow-v1"** +**complete = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**status = > json.get value=`complete` key="status"** +1. `status` == "succeeded" + **_ = 1** +2. * + > sys.exit code=26 + +Return *"durable-agent-flow-ok"*. From 981faac022511bee9528b5b92ee8023a3a14c59b Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:52:42 +0800 Subject: [PATCH 42/74] ci(ai): test native workflow plugin through actual Marqdo interpreter --- .github/workflows/executable-knowledge.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index eec00f9..24a25d7 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -23,8 +23,12 @@ jobs: cargo run --locked -- check ext/ai/recovery.mq.md cargo run --locked -- check ext/ai/context.mq.md cargo run --locked -- check tests/ext/ai-native-flow.mq.md + cargo run --locked -- check ext/ai/workflow.mq.md + cargo run --locked -- check tests/ext/ai-native-workflow.mq.md - name: Native AI flow interpreter smoke (offline) - run: cargo run --locked -- run tests/ext/ai-native-flow.mq.md + run: | + cargo run --locked -- run tests/ext/ai-native-flow.mq.md + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate From 0cd64a74507b41e78ccbf2c3689eb9052a6b00ac Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:53:02 +0800 Subject: [PATCH 43/74] fix(agent): persist partial child outcomes and require verified process success before workflow commit --- plugins/agent/src/workflow.rs | 53 ++++++++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 10 deletions(-) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index d96b174..f56a126 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -167,7 +167,8 @@ fn next_doc(ckpt: &Value, id: &str, reused: bool) -> Result { let status=ckpt["status"].as_str().unwrap_or("running"); if status=="blocked" || status=="uncertain" || status=="cancelled" { return Ok(json!({"ok":false,"id":id,"status":status, - "cursor":index,"step":step,"completed":meta["completed"]})); + "cursor":index,"step":step,"completed":meta["completed"], + "partial": meta.get("partial").cloned().unwrap_or(Value::Null)})); } let waiting=match step["kind"].as_str().unwrap_or("") { "model"=>"waiting_model", @@ -234,20 +235,33 @@ pub fn commit(args: &Value) -> Result { valid["value"].clone() } "skill" => { - if response["ok"]!=true { - return Ok(json!({"ok":false,"status":"tool_not_verified", - "reason":"only verified successful tool result may be committed"})); + // A completed wait is not equivalent to a successful child process. + let exit = response.get("value").and_then(|v| v.get("code")) + .or_else(|| response.get("code")).and_then(Value::as_i64); + if response["ok"]==false || exit != Some(0) { + return Ok(json!({"ok":false, + "status":if exit.is_none() {"uncertain"} else {"failed"}, + "reason":"child process exit code zero is required before commit"})); } response.clone() } "parallel" => { - let report=parallel::report(&json!({"results":response}))?; + let report=if response["schema"]=="AgentParallelResultV1" { + response.clone() + } else { + parallel::report(&json!({"results":response}))? + }; if report["ok"]!=true { - return Ok(json!({"ok":false, - "status": if report["uncertain"].as_u64().unwrap_or(0)>0 { - "uncertain" } else {"partial"}, - "report":report, - "reason":"preserve successful children; reconcile or retry failed children separately"})); + let status=if report["uncertain"].as_u64().unwrap_or(0)>0 { + "uncertain" + } else {"blocked"}; + // Save the full manifest of successful and failed siblings before + // returning. Do not run failed/unknown children automatically. + let mut frozen=meta.clone(); + frozen["partial"]=report.clone(); + save(args,id,&frozen,status)?; + return Ok(json!({"ok":false,"status":status, + "report":report,"reason":"child results retained for reconciliation"})); } report } @@ -333,6 +347,25 @@ mod tests { assert_eq!(next(&a).unwrap()["status"],"waiting_model"); } + #[test] + fn partial_children_remain_durable_and_unknown_requires_reconciliation() { + let mut a=fixture(); + a["steps"]=json!([{"id":"batch","kind":"parallel","tasks":[{"skill":"a"},{"skill":"b"}]}]); + open(&a).unwrap(); + let mut c=a.clone(); + c["step_id"]=json!("batch"); + c["response"]=json!([ + {"ok":true,"value":{"code":0,"value":"useful"}}, + {"ok":false,"error":"connection lost"} + ]); + assert_eq!(commit(&c).unwrap()["status"],"blocked"); + let after=next(&a).unwrap(); + assert_eq!(after["status"],"blocked"); + assert_eq!(after["partial"]["succeeded"],1); + assert_eq!(after["partial"]["failed"],1); + assert_eq!(commit(&c).unwrap()["status"],"blocked"); + } + #[test] fn explicit_cancel_stops_future_commits() { let a=fixture(); From 643ea06340ae6127093ae9744e33cddd61b9e12c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:53:17 +0800 Subject: [PATCH 44/74] feat(ai): add one-step native workflow driver for model input and bounded child tasks --- ext/ai/workflow.mq.md | 58 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/ext/ai/workflow.mq.md b/ext/ai/workflow.mq.md index 56ef207..078b28c 100644 --- a/ext/ai/workflow.mq.md +++ b/ext/ai/workflow.mq.md @@ -103,3 +103,61 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* Return *[Commit cancellation](agent_workflow_cancel(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. 2. * Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + + +## tick + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Running workflow | +| source_revision | text | required | Pinned source revision | +| registry | map | None | Trusted SKILL registry | +| model | any | None | Configured LLM | +| session_id | text | None | Host-attested session | +| principal_ref | text | None | Host-attested principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | New checkpoint state, or waiting_input for the UI | + +Use `id`, `source_revision`, `registry`=None, `model`=None, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +Advance at most one step. Model text is a candidate, never direct +execution. Waiting for a user returns immediately without holding a thread. +A caller repeats tick after verified completion; UI replies use commit. + +We retain **state = [Load the next action](next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))**. +We retain **status = [Read action status](json.get(value=`state`, key="status"))**. +1. `status` == "waiting_model" + We retain **step = [Read model step](json.get(value=`state`, key="step"))**. + We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**. + We retain **prompt = [Read local prompt](json.get(value=`step`, key="prompt"))**. + We retain **options = [Read allowed decisions](json.get(value=`step`, key="options"))**. + We retain **answer = [Make a bounded choice](flow.choose(input=`prompt`, options=`options`, model=`model`))**. + We retain **valid = [Check model decision](json.get(value=`answer`, key="ok"))**. + 1. `valid` + We retain **chosen = [Read verified model answer](json.get(value=`answer`, key="value"))**. + Return *[Commit the model choice](commit(id=`id`, step_id=`step_id`, response=`chosen`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + 2. * + Return *answer*. +2. `status` == "ready_tool" + We retain **step = [Read tool step](json.get(value=`state`, key="step"))**. + We retain **kind = [Read operation kind](json.get(value=`step`, key="kind"))**. + We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**. + 1. `kind` == "parallel" + We retain **tasks = [Read child tasks](json.get(value=`step`, key="tasks"))**. + We retain **report = [Run bounded parallel documents](flow.parallel(tasks=`tasks`))**. + Return *[Commit all child outcomes](commit(id=`id`, step_id=`step_id`, response=`report`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + 2. `kind` == "skill" + We retain **name = [Read registered skill name](json.get(value=`step`, key="skill"))**. + We retain **out = [Run registered SKILL only](flow.enter(skill=`name`, registry=`registry`))**. + Return *[Commit verified child result](commit(id=`id`, step_id=`step_id`, response=`out`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + 3. * + Return *state*. +3. `status` == "ready_return" + We retain **step = [Read return step](json.get(value=`state`, key="step"))**. + We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**. + We retain **value = [Read final value](json.get(value=`step`, key="value"))**. + Return *[Commit the completed workflow](commit(id=`id`, step_id=`step_id`, response=`value`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +4. * + Return *state*. From f6612813e3b3630a230805c13d43c8f34c9d10f4 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:53:58 +0800 Subject: [PATCH 45/74] fix(agent): remove resume test global cwd races and make atomic temp names unique --- plugins/agent/src/resume.rs | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/plugins/agent/src/resume.rs b/plugins/agent/src/resume.rs index 25835fa..821aec1 100644 --- a/plugins/agent/src/resume.rs +++ b/plugins/agent/src/resume.rs @@ -85,6 +85,8 @@ fn ensure_dir(root: &Path) -> Result<(), String> { } /// Atomic durable write: unique temp → write → flush/fsync → rename. +static TEMP_SEQUENCE: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> { let parent = path .parent() @@ -96,7 +98,8 @@ fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> { .and_then(|s| s.to_str()) .unwrap_or("ckpt.json"), std::process::id(), - now_rfc3339().replace(':', "") + format!("{}-{}", now_rfc3339().replace(':', ""), + TEMP_SEQUENCE.fetch_add(1, std::sync::atomic::Ordering::Relaxed)) ); let tmp = parent.join(tmp_name); let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?; @@ -396,7 +399,8 @@ mod tests { .duration_since(UNIX_EPOCH) .unwrap() .as_nanos(); - let dir = std::env::temp_dir().join(format!("marqdo-resume-{label}-{nanos}")); + // Do not mutate process-wide cwd from concurrent Rust unit tests. + let dir = PathBuf::from("target").join(format!("marqdo-resume-{label}-{nanos}")); fs::create_dir_all(&dir).unwrap(); dir } @@ -410,10 +414,7 @@ mod tests { #[test] fn atomic_v2_roundtrip_and_legacy_manual_review() { let dir = scratch("v2"); - // Use relative path via env cwd — chdir into scratch for this test. - let prev = std::env::current_dir().unwrap(); - std::env::set_current_dir(&dir).unwrap(); - let rel = "ckpts"; + let rel = dir.join("ckpts").to_string_lossy().to_string(); let saved = resume_save(&json!({ "id": "run1", "schema": "CheckpointV2", @@ -491,23 +492,20 @@ mod tests { assert_eq!(unsafe_ck["recovery_mode"], "checkpoint_v2_read_only"); assert_eq!(unsafe_ck["write_auto_resume"], false); - std::env::set_current_dir(prev).unwrap(); let _ = fs::remove_dir_all(&dir); } #[test] fn corrupt_checkpoint_reports_error() { let dir = scratch("corrupt"); - let prev = std::env::current_dir().unwrap(); - std::env::set_current_dir(&dir).unwrap(); - fs::create_dir_all("ckpts").unwrap(); - fs::write("ckpts/bad.json", "{not-json").unwrap(); - let loaded = resume_load(&json!({"id": "bad", "resume_dir": "ckpts"})).unwrap(); + let ckpts = dir.join("ckpts"); + fs::create_dir_all(&ckpts).unwrap(); + fs::write(ckpts.join("bad.json"), "{not-json").unwrap(); + let loaded = resume_load(&json!({"id": "bad", "resume_dir": ckpts.to_string_lossy()})).unwrap(); assert_eq!(loaded["found"], true); assert_eq!(loaded["ok"], false); assert_eq!(loaded["error"]["code"], "checkpoint.corrupt"); assert_eq!(loaded["recovery_mode"], "manual_review"); - std::env::set_current_dir(prev).unwrap(); let _ = fs::remove_dir_all(&dir); } } From 770dee519972f7d8f9c2d1ae4d5f3b1cb481c050 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:54:06 +0800 Subject: [PATCH 46/74] fix(agent): prevent EffectLedger atomic temp collisions under parallel operations --- plugins/agent/src/effects.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/plugins/agent/src/effects.rs b/plugins/agent/src/effects.rs index 8c4ff03..0cc35ed 100644 --- a/plugins/agent/src/effects.rs +++ b/plugins/agent/src/effects.rs @@ -91,6 +91,8 @@ fn ensure_dir(root: &Path) -> Result<(), String> { fs::create_dir_all(root).map_err(|e| format!("effects mkdir: {e}")) } +static EFFECT_TEMP_SEQUENCE: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> { let parent = path .parent() @@ -102,7 +104,8 @@ fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> { .and_then(|s| s.to_str()) .unwrap_or("op.json"), std::process::id(), - now_rfc3339().replace(':', "") + format!("{}-{}", now_rfc3339().replace(':', ""), + EFFECT_TEMP_SEQUENCE.fetch_add(1, std::sync::atomic::Ordering::Relaxed)) ); let tmp = parent.join(tmp_name); let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?; From 19f986953a4041d9e946a4b7af5bfc7fa4fbf689 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:54:21 +0800 Subject: [PATCH 47/74] test(ai): prove successful parallel child outputs survive failed sibling and checkpoint reload --- tests/ext/ai-native-workflow.mq.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md index b643ce8..0895e1c 100644 --- a/tests/ext/ai-native-workflow.mq.md +++ b/tests/ext/ai-native-workflow.mq.md @@ -56,4 +56,16 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=26 +**partial_steps = > json.parse text=[{"id":"children","kind":"parallel","tasks":[]}]** +**new_batch = > workflow.open id="abi_flow_partial_ci_20261118" steps=`partial_steps` source_revision="flow-v1"** +**parts = > json.parse text=[{"ok":true,"value":{"code":0,"value":"useful"}},{"ok":false,"error":"timeout"}]** +**stopped = > workflow.commit id="abi_flow_partial_ci_20261118" step_id="children" response=`parts` source_revision="flow-v1"** +**reloaded = > workflow.next id="abi_flow_partial_ci_20261118" source_revision="flow-v1"** +**partial = > json.get value=`reloaded` key="partial"** +**survivors = > json.get value=`partial` key="succeeded"** +1. `survivors` == 1 + **_ = 1** +2. * + > sys.exit code=27 + Return *"durable-agent-flow-ok"*. From cc48bf6d05ed442c0774d5cff079a9e45ae5940a Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:54:45 +0800 Subject: [PATCH 48/74] docs(agent): document plugin-only durable step state engine and safety boundaries --- doc/design/native-agent-flow-v3.md | 46 ++++++++++++++++++++++++++++-- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/doc/design/native-agent-flow-v3.md b/doc/design/native-agent-flow-v3.md index d4b37c3..54b6cf7 100644 --- a/doc/design/native-agent-flow-v3.md +++ b/doc/design/native-agent-flow-v3.md @@ -1,8 +1,9 @@ # Marqdo native agent flow — implementation contract -Status: **incremental, draft**. This document distinguishes implemented interfaces from -the required interpreter/runtime changes. Do not claim stack-level suspension or -exactly-once external writes based on a checkpoint file. +Status: **incremental, draft**. The core orchestration now has a plugin-only +alternative to interpreter-stack suspension: a durable finite step state machine +with explicit safe commit boundaries. Do not claim arbitrary stack-level +continuation or exactly-once external writes based on a checkpoint file. ## Author surface (implemented in this branch) @@ -89,3 +90,42 @@ back. On recovery, reconcile child attempts and reuse successful results. Do not merge the branch as a completed runtime refactor until the relevant runtime gates, including crash injection and multi-worker concurrency, pass. + + +## Plugin-only workflow (November 18 revision) + +The Agent ABI plugin implements `agent_workflow_open/next/commit/cancel`. +The small `ext/ai/workflow.mq.md` library wraps these primitives and provides +`tick` to execute exactly one safe decision or document task per call. +Source definitions have only five step kinds: `model`, `input`, `skill`, +`parallel` and `return`. Model text is verified against declared options. +`input` intentionally returns a waiting status; the UI supplies an answer +through `commit` on a later invocation. There is no interpreter thread to +hold and no need for a separate qdagent orchestration server. + +The checkpoint records the source revision, caller-provided session and +principal scope, next step index and the completed outputs. The same step +cannot be silently committed twice. Mixed child outcomes preserve completed +siblings in the checkpoint and **block** further automatic execution until +the unknown/failed child operations are reconciled. + +The state engine does not execute arbitrary unregistered tools directly: +`tick` delegates to existing Marqdo ABI-backed SKILL/subtask functions. +This is an implementation of **durable step-state recovery**, not a claim +of transparent recovery for a suspended foreign function or native call. +It provides the practical workflow needed for short qdagent SKILLs without +altering the Marqdo interpreter. + +### Security/reliability boundary still required for production + +- The host must attest source digest, principal, session, permissions and + registry, rather than accepting values copied from an LLM response. +- Effectful child tools must use the existing EffectLedger and external + receipt reconciliation; no automatic re-dispatch after an uncertain write. +- Cancelling a workflow checkpoint does not automatically cancel previously + spawned external children; the supervisor must propagate cancellation. +- The current task runner is step-atomic, not a durable parallel child lease + scheduler. A future plugin-only child manifest may use the host's existing + `runtime` query API, but must not bypass process.exec or file-root grants. +- Cross-process locks need a lease/owner-aware stale-lock recovery path; + a stale lock currently fails closed and requires operator review. From dd2218026976f12f89121b537ea0d71cb49a2552 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:55:11 +0800 Subject: [PATCH 49/74] feat(agent): recover failed read-only children only, preserving successful subtask results --- plugins/agent/src/workflow.rs | 125 ++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index f56a126..62eff3c 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -279,6 +279,107 @@ pub fn commit(args: &Value) -> Result { "cursor":index+1,"value":value,"reused":false})) } +/// Produce a plan containing only previously failed *read-only* child tasks. +/// "uncertain" children and effectful plans cannot be blindly retried. +pub fn retry_plan(args: &Value) -> Result { + let id=field(args,"id")?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"status":"not_found_or_mismatched"})); + } + let (meta,index)=state(&ckpt)?; + if ckpt["status"]!="blocked" { + return Ok(json!({"ok":false,"status":"not_retryable"})); + } + let step=&meta["steps"][index]; + if step["kind"]!="parallel" || step["effect_class"]!="read" + || meta["partial"]["uncertain"].as_u64().unwrap_or(1)!=0 + { + return Ok(json!({"ok":false,"status":"manual_reconciliation_required"})); + } + let Some(items)=meta["partial"]["items"].as_array() else { + return Err("partial report has no items".into()); + }; + let Some(tasks)=step["tasks"].as_array() else { + return Err("parallel plan has no tasks".into()); + }; + if items.len()!=tasks.len() { + return Err("partial report task count mismatch".into()); + } + let mut failed=Vec::new(); + let mut indices=Vec::new(); + for (i,item) in items.iter().enumerate() { + if item["index"]!=i { + return Err("out-of-order child result index".into()); + } + if item["status"]=="failed" { + failed.push(tasks[i].clone()); + indices.push(i); + } else if item["status"]!="succeeded" { + return Ok(json!({"ok":false,"status":"manual_reconciliation_required"})); + } + } + Ok(json!({"ok":true,"status":"retry_read_only", + "id":id,"step_id":step["id"],"tasks":failed,"indices":indices})) +} + +/// Merge only the failed child slots with verified new outcomes. +/// Successful results and their order remain untouched. +pub fn retry_commit(args: &Value) -> Result { + let id=field(args,"id")?; + let _guard=lock(args,id)?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"status":"not_found_or_mismatched"})); + } + let (meta,index)=state(&ckpt)?; + if ckpt["status"]!="blocked" { + return Ok(json!({"ok":false,"status":"not_retryable"})); + } + let step=&meta["steps"][index]; + if step["kind"]!="parallel" || step["effect_class"]!="read" + || meta["partial"]["uncertain"].as_u64().unwrap_or(1)!=0 + { + return Ok(json!({"ok":false,"status":"manual_reconciliation_required"})); + } + let items=meta["partial"]["items"].as_array() + .ok_or("invalid partial report")?; + let incoming=args.get("results").and_then(Value::as_array) + .ok_or("retry_commit requires results list")?; + let expected=items.iter().filter(|it|it["status"]=="failed").count(); + if incoming.len()!=expected { + return Err("retry result count differs from failed child count".into()); + } + let mut next=Vec::with_capacity(items.len()); + let mut replacement=incoming.iter(); + for item in items { + if item["status"]=="succeeded" { + next.push(item["result"].clone()); + } else if item["status"]=="failed" { + next.push(replacement.next().ok_or("missing retry result")?.clone()); + } else { + return Ok(json!({"ok":false,"status":"manual_reconciliation_required"})); + } + } + let report=parallel::report(&json!({"results":next}))?; + let mut updated=meta.clone(); + if report["ok"]==true { + updated["cursor"]=json!(index+1); + updated["partial"]=Value::Null; + updated["completed"].as_array_mut().ok_or("completed not list")? + .push(json!({"step_id":step["id"],"value":report})); + let finished=index+1==updated["steps"].as_array().ok_or("steps missing")?.len(); + save(args,id,&updated,if finished {"succeeded"} else {"running"})?; + Ok(json!({"ok":true,"status":if finished {"succeeded"} else {"advanced"}, + "cursor":index+1,"result":report})) + } else { + updated["partial"]=report.clone(); + save(args,id,&updated,if report["uncertain"].as_u64().unwrap_or(0)>0 { + "uncertain" } else {"blocked"})?; + Ok(json!({"ok":false,"status":"blocked","report":report})) + } +} + pub fn cancel(args: &Value) -> Result { let id=field(args,"id")?; let _guard=lock(args,id)?; @@ -366,6 +467,30 @@ mod tests { assert_eq!(commit(&c).unwrap()["status"],"blocked"); } + #[test] + fn retries_only_failed_read_only_children_without_redoing_successes() { + let mut a=fixture(); + a["steps"]=json!([{"id":"batch","kind":"parallel","effect_class":"read", + "tasks":[{"path":"a.mq.md"},{"path":"b.mq.md"}]}]); + open(&a).unwrap(); + let mut c=a.clone(); + c["step_id"]=json!("batch"); + c["response"]=json!([ + {"ok":true,"value":{"code":0,"value":"keep"}}, + {"ok":false,"error":"temporary timeout"} + ]); + assert_eq!(commit(&c).unwrap()["status"],"blocked"); + let plan=retry_plan(&a).unwrap(); + assert_eq!(plan["indices"],json!([1])); + assert_eq!(plan["tasks"].as_array().unwrap().len(),1); + let mut retry=a.clone(); + retry["results"]=json!([{"ok":true,"value":{"code":0,"value":"fixed"}}]); + assert_eq!(retry_commit(&retry).unwrap()["status"],"succeeded"); + let out=next(&a).unwrap(); + assert_eq!(out["completed"][0]["value"]["items"][0]["result"]["value"]["value"],"keep"); + assert_eq!(out["completed"][0]["value"]["items"][1]["result"]["value"]["value"],"fixed"); + } + #[test] fn explicit_cancel_stops_future_commits() { let a=fixture(); From 6f929dc2dae8410abd8367a597c070df919f9055 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:55:19 +0800 Subject: [PATCH 50/74] feat(agent): publish safe partial fan-out recovery through Agent ABI --- plugins/agent/src/lib.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 829ccac..eaac5a9 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -848,6 +848,8 @@ kb_ffi!(agent_workflow_open, workflow::open, "agent_workflow_open"); kb_ffi!(agent_workflow_next, workflow::next, "agent_workflow_next"); kb_ffi!(agent_workflow_commit, workflow::commit, "agent_workflow_commit"); kb_ffi!(agent_workflow_cancel, workflow::cancel, "agent_workflow_cancel"); +kb_ffi!(agent_workflow_retry_plan, workflow::retry_plan, "agent_workflow_retry_plan"); +kb_ffi!(agent_workflow_retry_commit, workflow::retry_commit, "agent_workflow_retry_commit"); kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry"); kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register"); @@ -986,6 +988,8 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_workflow_next", "id,source_revision", agent_workflow_next), ("agent_workflow_commit", "id,step_id,response,source_revision", agent_workflow_commit), ("agent_workflow_cancel", "id,source_revision", agent_workflow_cancel), + ("agent_workflow_retry_plan", "id,source_revision", agent_workflow_retry_plan), + ("agent_workflow_retry_commit", "id,results,source_revision", agent_workflow_retry_commit), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), From 8085d06124fe139f15e90d095ab84c9f20ceb417 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:55:30 +0800 Subject: [PATCH 51/74] feat(ai): expose failed-only read-only child recovery as a short Marqdo workflow --- ext/ai/workflow.mq.md | 82 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/ext/ai/workflow.mq.md b/ext/ai/workflow.mq.md index 078b28c..352b8ce 100644 --- a/ext/ai/workflow.mq.md +++ b/ext/ai/workflow.mq.md @@ -6,6 +6,7 @@ import: plugin: lib/plugin.mq.md json: lib/json.mq.md flow: ext/ai/flow.mq.md + subtask: lib/subtask.mq.md --- Every step is an explicit commit boundary. The plugin stores accepted outputs, @@ -161,3 +162,84 @@ We retain **status = [Read action status](json.get(value=`state`, key="status")) Return *[Commit the completed workflow](commit(id=`id`, step_id=`step_id`, response=`value`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. 4. * Return *state*. + + +## retry_plan + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Blocked workflow ID | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Failed-only read-task list or manual_review | + +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +Only a parallel step explicitly declared read-only and with no uncertain +effects may return a retry plan. Completed siblings are not included. + +We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Select failed read-only children](agent_workflow_retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## retry_commit + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Blocked workflow ID | +| results | list | required | New outcomes for failed children only | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Merged persistent report, or still blocked | + +Use `id`, `results`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. + +Re-use successful child results from the checkpoint. New results fill failed +slots only, in original order; a newly uncertain outcome blocks further work. + +We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Merge verified read-only retries](agent_workflow_retry_commit(id=`id`, results=`results`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## retry_failed + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Blocked workflow ID | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | +| limit | number | 2 | Max concurrent failed children | +| timeout_ms | number | 30000 | Child timeout | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Recovered workflow, partial results or manual review | + +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `limit`=2, `timeout_ms`=30000 as the inputs for this operation. + +Run only the failed read-only tasks returned by the native checkpoint checker. +Unknown external writes never reach this path. + +We retain **plan = [Inspect safe retry manifest](retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))**. +We retain **can_retry = [Check permitted recovery](json.get(value=`plan`, key="ok"))**. +1. `can_retry` + We retain **tasks = [Read failed-only children](json.get(value=`plan`, key="tasks"))**. + We retain **outcomes = [Execute failed read-only children only](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))**. + Return *[Merge with preserved completed children](retry_commit(id=`id`, results=`outcomes`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. +2. * + Return *plan*. From 8ea56cbe308cab939b17430435b9ff34cb4c43b1 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:55:42 +0800 Subject: [PATCH 52/74] test(ai): exercise ABI failed-only recovery without executing already successful children --- tests/ext/ai-native-workflow.mq.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md index 0895e1c..ac1b0a7 100644 --- a/tests/ext/ai-native-workflow.mq.md +++ b/tests/ext/ai-native-workflow.mq.md @@ -56,7 +56,7 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=26 -**partial_steps = > json.parse text=[{"id":"children","kind":"parallel","tasks":[]}]** +**partial_steps = > json.parse text=[{"id":"children","kind":"parallel","effect_class":"read","tasks":[{"path":"worker-a.mq.md"},{"path":"worker-b.mq.md"}]}]** **new_batch = > workflow.open id="abi_flow_partial_ci_20261118" steps=`partial_steps` source_revision="flow-v1"** **parts = > json.parse text=[{"ok":true,"value":{"code":0,"value":"useful"}},{"ok":false,"error":"timeout"}]** **stopped = > workflow.commit id="abi_flow_partial_ci_20261118" step_id="children" response=`parts` source_revision="flow-v1"** @@ -68,4 +68,18 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=27 +**retry_plan = > workflow.retry_plan id="abi_flow_partial_ci_20261118" source_revision="flow-v1"** +**allowed = > json.get value=`retry_plan` key="ok"** +1. `allowed` + **_ = 1** +2. * + > sys.exit code=28 +**repaired = > json.parse text=[{"ok":true,"value":{"code":0,"value":"repaired"}}]** +**merged = > workflow.retry_commit id="abi_flow_partial_ci_20261118" results=`repaired` source_revision="flow-v1"** +**merged_ok = > json.get value=`merged` key="ok"** +1. `merged_ok` + **_ = 1** +2. * + > sys.exit code=29 + Return *"durable-agent-flow-ok"*. From e8f1a3e126bef1e8becf3a9db2345a3edaa067a5 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:56:16 +0800 Subject: [PATCH 53/74] fix(agent): deduplicate equivalent numbered and labeled user replies --- plugins/agent/src/input.rs | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/plugins/agent/src/input.rs b/plugins/agent/src/input.rs index f01a935..7e11b1e 100644 --- a/plugins/agent/src/input.rs +++ b/plugins/agent/src/input.rs @@ -152,17 +152,8 @@ pub fn input_resume(args: &Value) -> Result { return Ok(json!({"ok":false,"status":"conflict","id":id, "error":{"code":"input.scope_or_revision_changed"}})); } - if existing["status"] == "resumed" { - if existing["result"] == reply { - return Ok(json!({"ok":true,"status":"resumed","id":id, - "value":reply,"reused":true})); - } - return Ok(json!({"ok":false,"status":"conflict","id":id, - "error":{"code":"input.already_answered"}})); - } - if existing["status"] != "waiting_input" { - return Ok(json!({"ok":false,"status":"conflict","id":id})); - } + // Normalize the answer before duplicate detection: the index "2" and + // the selected label "office" must be the same committed response. let allowed = crate::choice::parse_choice(&json!({ "options": meta["options"], "reply": reply }))?; @@ -174,6 +165,17 @@ pub fn input_resume(args: &Value) -> Result { return Ok(json!({"ok":false,"status":"invalid","id":id, "error":{"code":"input.invalid_choice"}})); }; + if existing["status"] == "resumed" { + if existing["result"] == normalized { + return Ok(json!({"ok":true,"status":"resumed","id":id, + "value":normalized,"reused":true})); + } + return Ok(json!({"ok":false,"status":"conflict","id":id, + "error":{"code":"input.already_answered"}})); + } + if existing["status"] != "waiting_input" { + return Ok(json!({"ok":false,"status":"conflict","id":id})); + } let saved = resume::resume_save(&json!({ "id": id, "resume_dir": args.get("resume_dir"), "checkpoint_v2": true, @@ -212,6 +214,7 @@ mod tests { let v = json!({"id":id,"resume_dir":dir,"reply":"2", "source_revision":"v1","session_id":"s1","principal_ref":"u1"}); assert_eq!(input_resume(&v).unwrap()["value"], "office"); + assert_eq!(input_resume(&v).unwrap()["reused"], true); assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir, "reply":"office","source_revision":"v1","session_id":"s1", "principal_ref":"u1"})).unwrap()["reused"], true); From 398a0b7222e33acc046fb5801f01f7da8253152f Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:56:28 +0800 Subject: [PATCH 54/74] ci(agent): introduce focused plugin-only native workflow gate separate from long EK suite --- .github/workflows/native-ai-flow.yml | 34 ++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 .github/workflows/native-ai-flow.yml diff --git a/.github/workflows/native-ai-flow.yml b/.github/workflows/native-ai-flow.yml new file mode 100644 index 0000000..2a63f3d --- /dev/null +++ b/.github/workflows/native-ai-flow.yml @@ -0,0 +1,34 @@ +name: native-ai-flow + +on: + push: + branches: + - feat/native-ai-flow-recovery-20261118 + pull_request: + paths: + - 'plugins/agent/**' + - 'ext/ai/flow.mq.md' + - 'ext/ai/context.mq.md' + - 'ext/ai/recovery.mq.md' + - 'ext/ai/workflow.mq.md' + - 'tests/ext/ai-native-*.mq.md' + - '.github/workflows/native-ai-flow.yml' + +jobs: + agent: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - name: Build plugin and run native tests + run: cargo test -p marqdo_plugin_agent --locked + - name: Check the public Marqdo ABI libraries + run: | + cargo run --locked -- check ext/ai/flow.mq.md + cargo run --locked -- check ext/ai/context.mq.md + cargo run --locked -- check ext/ai/recovery.mq.md + cargo run --locked -- check ext/ai/workflow.mq.md + - name: Exercise offline integration through Marqdo + run: | + cargo run --locked -- run tests/ext/ai-native-flow.mq.md + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md From 6e8a62928bf0b646df1c47fcbeab1e3a8c14da60 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:56:39 +0800 Subject: [PATCH 55/74] test(ai): verify plugin-only tick returns waiting input and commits final step --- tests/ext/ai-native-workflow.mq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md index ac1b0a7..35cccb4 100644 --- a/tests/ext/ai-native-workflow.mq.md +++ b/tests/ext/ai-native-workflow.mq.md @@ -34,7 +34,7 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=23 -**second = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**second = > workflow.tick id="abi_flow_ci_20261118" source_revision="flow-v1"** **second_state = > json.get value=`second` key="status"** 1. `second_state` == "waiting_input" **_ = 1** @@ -48,7 +48,7 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=25 -**c3 = > workflow.commit id="abi_flow_ci_20261118" step_id="end" response="finished" source_revision="flow-v1"** +**c3 = > workflow.tick id="abi_flow_ci_20261118" source_revision="flow-v1"** **complete = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** **status = > json.get value=`complete` key="status"** 1. `status` == "succeeded" From 6705e2e6b7443cf4a375bffa6f60176dd1730864 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:56:49 +0800 Subject: [PATCH 56/74] fix(agent): require explicit local prompt for model workflow steps --- plugins/agent/src/workflow.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index 62eff3c..7d9f6bc 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -93,6 +93,7 @@ fn validate_steps(args: &Value) -> Result { .ok_or_else(|| "choice step requires options list".to_string())?; let _ = choice::parse_choice(&json!({"reply":"","options":options}))?; if kind == "input" { let _ = field(s, "question")?; } + if kind == "model" { let _ = field(s, "prompt")?; } } if kind == "skill" { let _ = field(s, "skill")?; } if kind == "parallel" && !s.get("tasks").is_some_and(Value::is_array) { @@ -406,7 +407,7 @@ mod tests { "resume_dir":format!("target/workflow-test-{}-{n}",std::process::id()), "source_revision":"v1", "steps":[ - {"id":"choose","kind":"model","options":["chat","office"]}, + {"id":"choose","kind":"model","prompt":"Choose a skill","options":["chat","office"]}, {"id":"answer","kind":"input","question":"OK?","options":["yes","no"]}, {"id":"end","kind":"return"} ]}) From f859e6eeea650744f5e9adb1b4132e1a621346de Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:56:55 +0800 Subject: [PATCH 57/74] test(ai): include required short model prompt in workflow fixture --- tests/ext/ai-native-workflow.mq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md index 35cccb4..418f787 100644 --- a/tests/ext/ai-native-workflow.mq.md +++ b/tests/ext/ai-native-workflow.mq.md @@ -12,7 +12,7 @@ import: Offline test: the same Marqdo program advances through model choice, user input and terminal state with plugin-owned durable checkpoints. -**steps = > json.parse text=[{"id":"intent","kind":"model","options":["chat","office"]},{"id":"confirm","kind":"input","question":"Continue?","options":["yes","no"]},{"id":"end","kind":"return"}]** +**steps = > json.parse text=[{"id":"intent","kind":"model","prompt":"Choose next skill","options":["chat","office"]},{"id":"confirm","kind":"input","question":"Continue?","options":["yes","no"]},{"id":"end","kind":"return"}]** **opened = > workflow.open id="abi_flow_ci_20261118" steps=`steps` source_revision="flow-v1"** **o = > json.get value=`opened` key="ok"** 1. `o` From 70b88b376734be54e76a99de9cda49aea71c0cfc Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:57:06 +0800 Subject: [PATCH 58/74] security(agent): require explicit read-only classification before automatic SKILL/parallel dispatch --- plugins/agent/src/workflow.rs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index 7d9f6bc..41a7862 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -171,6 +171,16 @@ fn next_doc(ckpt: &Value, id: &str, reused: bool) -> Result { "cursor":index,"step":step,"completed":meta["completed"], "partial": meta.get("partial").cloned().unwrap_or(Value::Null)})); } + // Never auto-dispatch effectful or unclassified child documents. + // Those must be executed using the existing EffectLedger policy and an + // independently verified receipt, not an arbitrary model instruction. + if (step["kind"]=="skill" || step["kind"]=="parallel") + && step["effect_class"]!="read" + { + return Ok(json!({"ok":false,"id":id,"status":"manual_review", + "cursor":index,"step":step, + "reason":"automatic child dispatch requires an explicit read-only effect class"})); + } let waiting=match step["kind"].as_str().unwrap_or("") { "model"=>"waiting_model", "input"=>"waiting_input", @@ -434,6 +444,14 @@ mod tests { assert_eq!(open(&a).unwrap()["status"],"succeeded"); } + #[test] + fn unknown_and_write_effects_never_auto_dispatch() { + let mut a=fixture(); + a["steps"]=json!([{"id":"publish","kind":"skill","skill":"office"}]); + open(&a).unwrap(); + assert_eq!(next(&a).unwrap()["status"],"manual_review"); + } + #[test] fn source_change_conflict_and_invalid_model_choice() { let a=fixture(); From 90688741c5232440760b4d6c6f061d4b4645a268 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:57:37 +0800 Subject: [PATCH 59/74] feat(agent): parse bounded JSON choice envelopes without relaxing skill allowlist --- plugins/agent/src/choice.rs | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/plugins/agent/src/choice.rs b/plugins/agent/src/choice.rs index b3b8db7..cb63e68 100644 --- a/plugins/agent/src/choice.rs +++ b/plugins/agent/src/choice.rs @@ -43,8 +43,35 @@ fn strip_label(s: &str) -> &str { } } +fn structured_reply(raw: &str) -> Option { + let parsed: Value = serde_json::from_str(raw).ok()?; + if let Some(s) = parsed.as_str() { + return Some(s.to_string()); + } + if let Some(list) = parsed.as_array() { + if list.len() == 1 { + return list[0].as_str().map(str::to_string); + } + return None; + } + let map = parsed.as_object()?; + // Refuse conflicting structured decisions instead of choosing first. + let values: Vec<&str> = ["choice", "selected", "option", "选择"] + .iter() + .filter_map(|key| map.get(*key).and_then(Value::as_str)) + .collect(); + if values.is_empty() || values.iter().any(|s| *s != values[0]) { + return None; + } + Some(values[0].to_string()) +} + fn single_choice(options: &[String], reply: &str) -> Option { let raw = strip_label(strip_fence(reply)); + // Structured single-choice replies are accepted only through known fields, + // and then still validated against the caller's exact allowlist. + let decoded = structured_reply(raw); + let raw = decoded.as_deref().unwrap_or(raw); // Small models often prepend a short selection verb. Accept only the // verb followed by a complete allowed value; explanations stay invalid. let raw = raw.trim(); @@ -130,6 +157,9 @@ mod tests { assert_eq!(check("2")["value"], "office"); assert_eq!(check("我选择 chat")["value"], "chat"); assert_eq!(check("I choose office")["value"], "office"); + assert_eq!(check(r#"{"choice":"chat"}"#)["value"], "chat"); + assert_eq!(check("[\"office\"]")["value"], "office"); + assert_eq!(check("```json\n{\"selected\":\"office\"}\n```")["value"], "office"); } #[test] @@ -141,6 +171,13 @@ mod tests { } } + #[test] + fn refuses_conflicting_structured_decisions() { + assert_eq!(check(r#"{"choice":"chat","option":"office"}"#)["ok"], false); + assert_eq!(check(r#"{"choice":"../private.mq.md"}"#)["ok"], false); + assert_eq!(check(r#"["chat","office"]"#)["ok"], false); + } + #[test] fn rejects_invalid_options_before_parsing() { for options in [ From 3ce59a4da8f6e72d5a91daa44cad8a62d935d39a Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:57:47 +0800 Subject: [PATCH 60/74] test(ai): verify JSON-formatted small-model option parsing from Marqdo --- tests/ext/ai-native-flow.mq.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/tests/ext/ai-native-flow.mq.md b/tests/ext/ai-native-flow.mq.md index cce2a01..c8fa5aa 100644 --- a/tests/ext/ai-native-flow.mq.md +++ b/tests/ext/ai-native-flow.mq.md @@ -22,6 +22,13 @@ rather than guessing another SKILL or importing the full document. 2. * > sys.exit code=11 +**structured = > flow.parse_choice reply="{\"choice\":\"chat\"}" options=`opts`** +**structure_value = > json.get value=`structured` key="value"** +1. `structure_value` == "chat" + **_ = 1** +2. * + > sys.exit code=16 + **invalid = > flow.parse_choice reply="chat 或 office" options=`opts`** **not_ok = > json.get value=`invalid` key="ok"** 1. `not_ok` From 8a66f803cb88c49a1af3c1a549ae51434217edcf Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:59:16 +0800 Subject: [PATCH 61/74] feat(agent): add validated forward-only branching from model choices to registered SKILL steps --- plugins/agent/src/workflow.rs | 80 ++++++++++++++++++++++++++++++++--- 1 file changed, 74 insertions(+), 6 deletions(-) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index 41a7862..dff495e 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -100,9 +100,52 @@ fn validate_steps(args: &Value) -> Result { return Err("parallel step requires tasks array".into()); } } + // Resolve all branch targets against frozen, forward-only step IDs. + for (i, s) in steps.iter().enumerate() { + let targets = s.get("next").and_then(Value::as_str).into_iter() + .chain(s.get("routes").and_then(Value::as_object) + .into_iter().flat_map(|m| m.values().filter_map(Value::as_str))); + for target in targets { + let position = steps.iter().position(|x|x["id"]==target) + .ok_or_else(|| format!("unknown workflow target: {target}"))?; + if position <= i { + return Err("workflow routes must move forward to avoid loops".into()); + } + } + if let Some(routes)=s.get("routes").and_then(Value::as_object) { + if !matches!(s["kind"].as_str(),Some("model"|"input")) { + return Err("only choice steps may declare routes".into()); + } + for key in routes.keys() { + if !s["options"].as_array().is_some_and(|opts| + opts.iter().any(|x|x==key.as_str())) { + return Err("route label is not a declared choice".into()); + } + } + } + } Ok(Value::Array(steps.clone())) } +fn advance_cursor(step:&Value, value:&Value, steps:&[Value], current:usize)->Result { + let target=if let Some(routes)=step.get("routes").and_then(Value::as_object) { + let label=value.as_str().ok_or("routed choice must return a text label")?; + Some(routes.get(label).and_then(Value::as_str) + .ok_or("chosen option is missing a declared route")?) + } else { + step.get("next").and_then(Value::as_str) + }; + match target { + None=>Ok(current+1), + Some(name)=> { + let n=steps.iter().position(|s|s["id"]==name) + .ok_or("unknown target after checkpoint recovery")?; + if n<=current {return Err("cyclic route refused".into())} + Ok(n) + } + } +} + fn state(ckpt: &Value) -> Result<(&Value,usize),String> { let meta = ckpt.get("meta").ok_or("missing workflow metadata")?; if meta.get("kind").and_then(Value::as_str) != Some("MarqdoAgentFlowV1") { @@ -279,15 +322,16 @@ pub fn commit(args: &Value) -> Result { "return" => response.clone(), _ => return Err("invalid step kind".into()), }; + let target=advance_cursor(step,&value,steps,index)?; let mut new_meta=meta.clone(); - new_meta["cursor"]=json!(index+1); + new_meta["cursor"]=json!(target); new_meta["completed"].as_array_mut().ok_or("completed not array")? .push(json!({"step_id":step_id,"value":value})); - let terminal=index+1==steps.len(); + let terminal=target==steps.len(); save(args,id,&new_meta,if terminal {"succeeded"} else {"running"})?; Ok(json!({"ok":true,"id":id, "status":if terminal {"succeeded"} else {"advanced"}, - "cursor":index+1,"value":value,"reused":false})) + "cursor":target,"value":value,"reused":false})) } /// Produce a plan containing only previously failed *read-only* child tasks. @@ -375,14 +419,16 @@ pub fn retry_commit(args: &Value) -> Result { let report=parallel::report(&json!({"results":next}))?; let mut updated=meta.clone(); if report["ok"]==true { - updated["cursor"]=json!(index+1); + let target=advance_cursor(step,&report, + updated["steps"].as_array().ok_or("steps missing")?,index)?; + updated["cursor"]=json!(target); updated["partial"]=Value::Null; updated["completed"].as_array_mut().ok_or("completed not list")? .push(json!({"step_id":step["id"],"value":report})); - let finished=index+1==updated["steps"].as_array().ok_or("steps missing")?.len(); + let finished=target==updated["steps"].as_array().ok_or("steps missing")?.len(); save(args,id,&updated,if finished {"succeeded"} else {"running"})?; Ok(json!({"ok":true,"status":if finished {"succeeded"} else {"advanced"}, - "cursor":index+1,"result":report})) + "cursor":target,"result":report})) } else { updated["partial"]=report.clone(); save(args,id,&updated,if report["uncertain"].as_u64().unwrap_or(0)>0 { @@ -452,6 +498,28 @@ mod tests { assert_eq!(next(&a).unwrap()["status"],"manual_review"); } + #[test] + fn routes_skip_unselected_skill_branches() { + let mut a=fixture(); + a["steps"]=json!([ + {"id":"decide","kind":"model","prompt":"Pick","options":["chat","office"], + "routes":{"chat":"chat_skill","office":"office_skill"}}, + {"id":"chat_skill","kind":"skill","skill":"chat","effect_class":"read","next":"done"}, + {"id":"office_skill","kind":"skill","skill":"office","effect_class":"read","next":"done"}, + {"id":"done","kind":"return"} + ]); + open(&a).unwrap(); + let mut c=a.clone(); + c["step_id"]=json!("decide"); + c["response"]=json!("office"); + assert_eq!(commit(&c).unwrap()["cursor"],2); + assert_eq!(next(&a).unwrap()["step"]["id"],"office_skill"); + c["step_id"]=json!("office_skill"); + c["response"]=json!({"ok":true,"value":{"code":0}}); + assert_eq!(commit(&c).unwrap()["cursor"],3); + assert_eq!(next(&a).unwrap()["step"]["id"],"done"); + } + #[test] fn source_change_conflict_and_invalid_model_choice() { let a=fixture(); From 92c3f800554adb44a6205ebbc88a713de07812c1 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 09:59:27 +0800 Subject: [PATCH 62/74] fix(agent): compare branch labels using explicit text conversion --- plugins/agent/src/workflow.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index dff495e..5e10548 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -118,7 +118,7 @@ fn validate_steps(args: &Value) -> Result { } for key in routes.keys() { if !s["options"].as_array().is_some_and(|opts| - opts.iter().any(|x|x==key.as_str())) { + opts.iter().any(|x|x.as_str()==Some(key.as_str()))) { return Err("route label is not a declared choice".into()); } } From 58b65215a1bd14c65aaa2433feb18e38955c49fa Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 10:16:43 +0800 Subject: [PATCH 63/74] test(agent): show the failed native choice result in interpreter smoke diagnostics --- tests/ext/ai-native-flow.mq.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/ext/ai-native-flow.mq.md b/tests/ext/ai-native-flow.mq.md index c8fa5aa..f5598c5 100644 --- a/tests/ext/ai-native-flow.mq.md +++ b/tests/ext/ai-native-flow.mq.md @@ -20,6 +20,8 @@ rather than guessing another SKILL or importing the full document. 1. `value` == "office" **_ = 1** 2. * + **debug_pick = > json.stringify value=`pick`** + > print text=`debug_pick` > sys.exit code=11 **structured = > flow.parse_choice reply="{\"choice\":\"chat\"}" options=`opts`** From 23229a6ac97d928fd7a02f0fdeb02564dbd5b20d Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 10:17:44 +0800 Subject: [PATCH 64/74] ci(agent): permit native ABI loading in offline Agent integration tests --- .github/workflows/native-ai-flow.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/native-ai-flow.yml b/.github/workflows/native-ai-flow.yml index 2a63f3d..7496adc 100644 --- a/.github/workflows/native-ai-flow.yml +++ b/.github/workflows/native-ai-flow.yml @@ -30,5 +30,5 @@ jobs: cargo run --locked -- check ext/ai/workflow.mq.md - name: Exercise offline integration through Marqdo run: | - cargo run --locked -- run tests/ext/ai-native-flow.mq.md - cargo run --locked -- run tests/ext/ai-native-workflow.mq.md + cargo run --locked -- run tests/ext/ai-native-flow.mq.md --effects plugin,fs.write + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write From 8e437e2cd361bce7f9a98c034500cdb0655bdb1c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 10:17:47 +0800 Subject: [PATCH 65/74] ci(agent): permit native ABI loading in offline Agent integration tests --- .github/workflows/executable-knowledge.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index 24a25d7..430e086 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -27,8 +27,8 @@ jobs: cargo run --locked -- check tests/ext/ai-native-workflow.mq.md - name: Native AI flow interpreter smoke (offline) run: | - cargo run --locked -- run tests/ext/ai-native-flow.mq.md - cargo run --locked -- run tests/ext/ai-native-workflow.mq.md + cargo run --locked -- run tests/ext/ai-native-flow.mq.md --effects plugin,fs.write + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate From 38c07d9a0e710190f1be58af0c2c567c9fdaa84c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 11:57:12 +0800 Subject: [PATCH 66/74] feat(agent): add workflow inspection and durable isolation - add agent_workflow_inspect/list primitives and ext/ai wrappers - expose host-relative resume_dir on every workflow operation - make offline workflow fixture repeatable with a timestamped run id - fix flow.choose branch scoping contract diagnostic - build the agent cdylib and drop the removed run --effects flag in CI --- .github/workflows/executable-knowledge.yml | 6 +- .github/workflows/native-ai-flow.yml | 12 ++- .gitignore | 2 + CHANGELOG.md | 15 +++ doc/design/native-agent-flow-v3.md | 17 ++- ext/ai/flow.mq.md | 28 ++--- ext/ai/index.mq.md | 4 +- ext/ai/workflow.mq.md | 120 +++++++++++++++++---- plugins/agent/src/lib.rs | 16 +-- plugins/agent/src/workflow.rs | 88 +++++++++++++++ tests/ext/ai-native-workflow.mq.md | 65 ++++++++--- 11 files changed, 308 insertions(+), 65 deletions(-) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index 430e086..e6cc297 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -26,9 +26,11 @@ jobs: cargo run --locked -- check ext/ai/workflow.mq.md cargo run --locked -- check tests/ext/ai-native-workflow.mq.md - name: Native AI flow interpreter smoke (offline) + env: + MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so run: | - cargo run --locked -- run tests/ext/ai-native-flow.mq.md --effects plugin,fs.write - cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write + cargo run --locked -- run tests/ext/ai-native-flow.mq.md + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md - name: Workbench contracts (M00–M06 / F-subset) run: cargo test --test workbench_contracts --locked - name: Offline executable-knowledge gate diff --git a/.github/workflows/native-ai-flow.yml b/.github/workflows/native-ai-flow.yml index 7496adc..da1c944 100644 --- a/.github/workflows/native-ai-flow.yml +++ b/.github/workflows/native-ai-flow.yml @@ -20,7 +20,9 @@ jobs: steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@stable - - name: Build plugin and run native tests + - name: Build the agent plugin + run: cargo build -p marqdo_plugin_agent --locked + - name: Run native agent and workflow tests run: cargo test -p marqdo_plugin_agent --locked - name: Check the public Marqdo ABI libraries run: | @@ -28,7 +30,11 @@ jobs: cargo run --locked -- check ext/ai/context.mq.md cargo run --locked -- check ext/ai/recovery.mq.md cargo run --locked -- check ext/ai/workflow.mq.md + cargo run --locked -- check tests/ext/ai-native-flow.mq.md + cargo run --locked -- check tests/ext/ai-native-workflow.mq.md - name: Exercise offline integration through Marqdo + env: + MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so run: | - cargo run --locked -- run tests/ext/ai-native-flow.mq.md --effects plugin,fs.write - cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write + cargo run --locked -- run tests/ext/ai-native-flow.mq.md + cargo run --locked -- run tests/ext/ai-native-workflow.mq.md diff --git a/.gitignore b/.gitignore index 919c8d5..94642b7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ /target/ /dist/ +# Plugin unit tests use package-relative scratch checkpoints. +/plugins/agent/target/ # Copied by gold harness for ABI plugins /tests/lib/demo.dll diff --git a/CHANGELOG.md b/CHANGELOG.md index b910e1a..5f3f859 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,21 @@ ## Unreleased +### Added + +- `ext/ai/workflow` now exposes read-only `inspect`/`list`, a host-relative + `resume_dir` on every operation, and repeatable offline workflow fixtures. +- Agent ABI registers `agent_workflow_inspect` and `agent_workflow_list`. +- AI 工作流拓展库新增只读 `inspect`/`list`、各操作的 `resume_dir` 隔离, + 离线集成夹具改为按时间戳生成运行 ID,可重复执行。 + +### Fixed + +- `flow.choose` no longer leaks a branch-local `parsed` value into the function + contract; the repaired-choice path is fully scoped. +- CI builds the agent cdylib and runs offline integration without the removed + `run --effects` flag, using `MARQDO_AGENT_PLUGIN` instead. + ## v2.7.1 — 2026-11-11 CLI 修复发布:View 实际逻辑的手动开合不再被布局重排或运行结果刷新覆盖;函数、链接、列表和记录按内容排版,手机详情整行展示。核心仍为 19 个构造;拓展库保留 2.7.0。 diff --git a/doc/design/native-agent-flow-v3.md b/doc/design/native-agent-flow-v3.md index 54b6cf7..ce85b0c 100644 --- a/doc/design/native-agent-flow-v3.md +++ b/doc/design/native-agent-flow-v3.md @@ -16,10 +16,16 @@ continuation or exactly-once external writes based on a checkpoint file. | ext/ai/flow.mq.md | start/wait/parallel | Existing Marqdo subtask scheduler, failure-preserving parallel result aggregation | | ext/ai/flow.mq.md | enter | Resolve only author-supplied registered skill name, run via standard subtask path | | ext/ai/recovery.mq.md | decide/save/load | Native error policy and CheckpointV2; no implicit unsafe re-execution | +| ext/ai/workflow.mq.md | open/next/commit/cancel | Durable forward-only step machine with per-step commit boundaries | +| ext/ai/workflow.mq.md | inspect/list | Read-only progress summary and checkpoint discovery scoped by session/principal | +| ext/ai/workflow.mq.md | tick/retry_plan/retry_commit/retry_failed | One-step execution and failed-only read-only recovery | The native agent plugin provides `agent_choice_parse`, `agent_context_scope`, -`agent_input_open`, `agent_input_resume` and `agent_parallel_report`. +`agent_input_open`, `agent_input_resume`, `agent_parallel_report`, and the +`agent_workflow_*` primitives including `inspect` and `list`. Plugin errors must be visible, never converted into a fabricated successful answer. +All workflow wrappers accept a host-relative `resume_dir`, so tests and callers +can isolate checkpoints instead of sharing the default `.marqdo/agent-resume`. ## Invariants @@ -94,9 +100,12 @@ runtime gates, including crash injection and multi-worker concurrency, pass. ## Plugin-only workflow (November 18 revision) -The Agent ABI plugin implements `agent_workflow_open/next/commit/cancel`. -The small `ext/ai/workflow.mq.md` library wraps these primitives and provides -`tick` to execute exactly one safe decision or document task per call. +The Agent ABI plugin implements +`agent_workflow_open/next/inspect/list/commit/cancel` plus the failed-only +retry primitives. The small `ext/ai/workflow.mq.md` library wraps these +primitives and provides `tick` to execute exactly one safe decision or document +task per call. `inspect` and `list` are strictly read-only: they report progress +or discover checkpoints without advancing a cursor or running a step. Source definitions have only five step kinds: `model`, `input`, `skill`, `parallel` and `return`. Model text is verified against declared options. `input` intentionally returns a waiting status; the UI supplies an answer diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 346fd69..a005f15 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -65,20 +65,20 @@ We retain **err = [Check model transport error](json.get(value=`turn`, key="erro 2. * We retain **reply = [Read model answer](json.get(value=`turn`, key="text"))**. We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**. -We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. -1. `ok` - Return *parsed*. -2. `repair` - We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**. - We retain **fixed = [Retry the format only once](m.ask(prompt=`fix`))**. - We retain **repair_error = [Read transport error](json.get(value=`fixed`, key="error"))**. - 1. `repair_error` - Return *fixed*. - 2. * - We retain **again = [Read corrected answer](json.get(value=`fixed`, key="text"))**. - Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*. -3. * - Return *parsed*. + We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**. + 1. `ok` + Return *parsed*. + 2. `repair` + We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**. + We retain **fixed = [Retry the format only once](m.ask(prompt=`fix`))**. + We retain **repair_error = [Read transport error](json.get(value=`fixed`, key="error"))**. + 1. `repair_error` + Return *fixed*. + 2. * + We retain **again = [Read corrected answer](json.get(value=`fixed`, key="text"))**. + Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*. + 3. * + Return *parsed*. ## parallel diff --git a/ext/ai/index.mq.md b/ext/ai/index.mq.md index 197615e..0015ff9 100644 --- a/ext/ai/index.mq.md +++ b/ext/ai/index.mq.md @@ -10,7 +10,9 @@ stream collection and usage; [provider adapters](llm/index.mq.md) describe OpenA and Ollama requests. [Agents](agent.mq.md) own call-site context, the explicit tool registry, policy routing, observations, workbook planning and continuation. [CoW trials](sandbox.mq.md) own isolated file changes and promotion. [Native flow](flow.mq.md) provides short, verified model choices and bounded document -concurrency; [context](context.mq.md) packs explicit source scopes; [recovery](recovery.mq.md) +concurrency; [workflow](workflow.mq.md) drives a durable forward-only step plan with +`inspect`/`list` progress queries and failed-only read recovery; [context](context.mq.md) +packs explicit source scopes; [recovery](recovery.mq.md) uses the native error policy and versioned checkpoints. These are lightweight interfaces, not a second agent runtime. [Step routing](policies/step-route.mq.md) is readable diff --git a/ext/ai/workflow.mq.md b/ext/ai/workflow.mq.md index 352b8ce..52014df 100644 --- a/ext/ai/workflow.mq.md +++ b/ext/ai/workflow.mq.md @@ -12,7 +12,8 @@ import: Every step is an explicit commit boundary. The plugin stores accepted outputs, refuses stale documents and conflicting decisions, and exposes the next action. The caller must supply trusted session, principal and source revision fields; -model text is never an identity or permission token. +model text is never an identity or permission token. `resume_dir` is a +host-relative checkpoint directory, never an absolute client path. ## open @@ -23,17 +24,22 @@ model text is never an identity or permission token. | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Created, resumed, or explicit conflict | -Use `id`, `steps`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `steps`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +Opening the same ID with the same steps, source revision, session and principal +returns the current action instead of resetting progress. Reusing an ID with a +different plan or identity fails closed. We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Open durable workflow](agent_workflow_open(id=`id`, steps=`steps`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Open durable workflow](agent_workflow_open(id=`id`, steps=`steps`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -45,17 +51,75 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Current action or terminal state | -Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +`next` is read-only: it does not call a model, run a child document or consume +the current step. Stopped states (`blocked`, `uncertain`, `cancelled`) and +unclassified child effects are reported explicitly. We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Find the next committed boundary](agent_workflow_next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Find the next committed boundary](agent_workflow_next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## inspect + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| id | text | required | Stable run ID | +| source_revision | text | required | Pinned source revision | +| session_id | text | None | Trusted session | +| principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Progress summary with cursor, step and partial results | + +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +Use inspect for a UI progress panel or an operator audit. It returns the +durable checkpoint `status`, the next `action` (for example `waiting_model`), +cursor, total and completed step counts, the current step, and retained partial +child results without advancing the workflow. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[Read workflow progress](agent_workflow_inspect(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. +2. * + Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. + +## list + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| session_id | text | None | Trusted session filter | +| principal_ref | text | None | Trusted principal filter | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | + +| 返回 | 类型 | 说明 | +|---|---|---| +| result | map | Workflow summaries, newest metadata included separately | + +Use `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +Only native workflow checkpoints are listed; unrelated resume records and +corrupt files are omitted. Pass host-attested filters to keep one session or +principal from seeing another's run identifiers. + +We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. +1. `p` + We **[Load Agent ABI plugin](plugin.load(path=`p`))**. + Return *[List workflow checkpoints](agent_workflow_list(session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -69,17 +133,21 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Committed next step or explicit failure | -Use `id`, `step_id`, `response`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `step_id`, `response`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +A completed step cannot be committed twice. Replaying the same value returns +the already-committed result; a different value for the same step conflicts. We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Validate and commit one step](agent_workflow_commit(id=`id`, step_id=`step_id`, response=`response`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Validate and commit one step](agent_workflow_commit(id=`id`, step_id=`step_id`, response=`response`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -91,17 +159,21 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Cancelled checkpoint status | -Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. + +Cancelling prevents future commits. It does not claim that children already +started by the supervisor were rolled back. We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Commit cancellation](agent_workflow_cancel(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Commit cancellation](agent_workflow_cancel(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -116,18 +188,19 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | model | any | None | Configured LLM | | session_id | text | None | Host-attested session | | principal_ref | text | None | Host-attested principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | New checkpoint state, or waiting_input for the UI | -Use `id`, `source_revision`, `registry`=None, `model`=None, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `source_revision`, `registry`=None, `model`=None, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. Advance at most one step. Model text is a candidate, never direct execution. Waiting for a user returns immediately without holding a thread. A caller repeats tick after verified completion; UI replies use commit. -We retain **state = [Load the next action](next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))**. +We retain **state = [Load the next action](next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))**. We retain **status = [Read action status](json.get(value=`state`, key="status"))**. 1. `status` == "waiting_model" We retain **step = [Read model step](json.get(value=`state`, key="step"))**. @@ -138,7 +211,7 @@ We retain **status = [Read action status](json.get(value=`state`, key="status")) We retain **valid = [Check model decision](json.get(value=`answer`, key="ok"))**. 1. `valid` We retain **chosen = [Read verified model answer](json.get(value=`answer`, key="value"))**. - Return *[Commit the model choice](commit(id=`id`, step_id=`step_id`, response=`chosen`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Commit the model choice](commit(id=`id`, step_id=`step_id`, response=`chosen`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *answer*. 2. `status` == "ready_tool" @@ -148,18 +221,18 @@ We retain **status = [Read action status](json.get(value=`state`, key="status")) 1. `kind` == "parallel" We retain **tasks = [Read child tasks](json.get(value=`step`, key="tasks"))**. We retain **report = [Run bounded parallel documents](flow.parallel(tasks=`tasks`))**. - Return *[Commit all child outcomes](commit(id=`id`, step_id=`step_id`, response=`report`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Commit all child outcomes](commit(id=`id`, step_id=`step_id`, response=`report`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. `kind` == "skill" We retain **name = [Read registered skill name](json.get(value=`step`, key="skill"))**. We retain **out = [Run registered SKILL only](flow.enter(skill=`name`, registry=`registry`))**. - Return *[Commit verified child result](commit(id=`id`, step_id=`step_id`, response=`out`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Commit verified child result](commit(id=`id`, step_id=`step_id`, response=`out`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 3. * Return *state*. 3. `status` == "ready_return" We retain **step = [Read return step](json.get(value=`state`, key="step"))**. We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**. We retain **value = [Read final value](json.get(value=`step`, key="value"))**. - Return *[Commit the completed workflow](commit(id=`id`, step_id=`step_id`, response=`value`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Commit the completed workflow](commit(id=`id`, step_id=`step_id`, response=`value`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 4. * Return *state*. @@ -172,12 +245,13 @@ We retain **status = [Read action status](json.get(value=`state`, key="status")) | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Failed-only read-task list or manual_review | -Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. Only a parallel step explicitly declared read-only and with no uncertain effects may return a retry plan. Completed siblings are not included. @@ -185,7 +259,7 @@ effects may return a retry plan. Completed siblings are not included. We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Select failed read-only children](agent_workflow_retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Select failed read-only children](agent_workflow_retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -198,12 +272,13 @@ We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. | source_revision | text | required | Pinned source revision | | session_id | text | None | Trusted session | | principal_ref | text | None | Trusted principal | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Merged persistent report, or still blocked | -Use `id`, `results`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation. +Use `id`, `results`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. Re-use successful child results from the checkpoint. New results fill failed slots only, in original order; a newly uncertain outcome blocks further work. @@ -211,7 +286,7 @@ slots only, in original order; a newly uncertain outcome blocks further work. We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. 1. `p` We **[Load Agent ABI plugin](plugin.load(path=`p`))**. - Return *[Merge verified read-only retries](agent_workflow_retry_commit(id=`id`, results=`results`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Merge verified read-only retries](agent_workflow_retry_commit(id=`id`, results=`results`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*. @@ -225,21 +300,22 @@ We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. | principal_ref | text | None | Trusted principal | | limit | number | 2 | Max concurrent failed children | | timeout_ms | number | 30000 | Child timeout | +| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory | | 返回 | 类型 | 说明 | |---|---|---| | result | map | Recovered workflow, partial results or manual review | -Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `limit`=2, `timeout_ms`=30000 as the inputs for this operation. +Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `limit`=2, `timeout_ms`=30000, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation. Run only the failed read-only tasks returned by the native checkpoint checker. Unknown external writes never reach this path. -We retain **plan = [Inspect safe retry manifest](retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))**. +We retain **plan = [Inspect safe retry manifest](retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))**. We retain **can_retry = [Check permitted recovery](json.get(value=`plan`, key="ok"))**. 1. `can_retry` We retain **tasks = [Read failed-only children](json.get(value=`plan`, key="tasks"))**. We retain **outcomes = [Execute failed read-only children only](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))**. - Return *[Merge with preserved completed children](retry_commit(id=`id`, results=`outcomes`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*. + Return *[Merge with preserved completed children](retry_commit(id=`id`, results=`outcomes`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*. 2. * Return *plan*. diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index eaac5a9..9234f45 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -846,6 +846,8 @@ kb_ffi!(agent_input_resume, input::input_resume, "agent_input_resume"); kb_ffi!(agent_parallel_report, parallel::report, "agent_parallel_report"); kb_ffi!(agent_workflow_open, workflow::open, "agent_workflow_open"); kb_ffi!(agent_workflow_next, workflow::next, "agent_workflow_next"); +kb_ffi!(agent_workflow_inspect, workflow::inspect, "agent_workflow_inspect"); +kb_ffi!(agent_workflow_list, workflow::list, "agent_workflow_list"); kb_ffi!(agent_workflow_commit, workflow::commit, "agent_workflow_commit"); kb_ffi!(agent_workflow_cancel, workflow::cancel, "agent_workflow_cancel"); kb_ffi!(agent_workflow_retry_plan, workflow::retry_plan, "agent_workflow_retry_plan"); @@ -984,12 +986,14 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_input_open", "id,question,options,source_revision", agent_input_open), ("agent_input_resume", "id,reply,source_revision", agent_input_resume), ("agent_parallel_report", "results", agent_parallel_report), - ("agent_workflow_open", "id,steps,source_revision", agent_workflow_open), - ("agent_workflow_next", "id,source_revision", agent_workflow_next), - ("agent_workflow_commit", "id,step_id,response,source_revision", agent_workflow_commit), - ("agent_workflow_cancel", "id,source_revision", agent_workflow_cancel), - ("agent_workflow_retry_plan", "id,source_revision", agent_workflow_retry_plan), - ("agent_workflow_retry_commit", "id,results,source_revision", agent_workflow_retry_commit), + ("agent_workflow_open", "id,steps,source_revision,session_id,principal_ref,resume_dir", agent_workflow_open), + ("agent_workflow_next", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_next), + ("agent_workflow_inspect", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_inspect), + ("agent_workflow_list", "session_id,principal_ref,resume_dir", agent_workflow_list), + ("agent_workflow_commit", "id,step_id,response,source_revision,session_id,principal_ref,resume_dir", agent_workflow_commit), + ("agent_workflow_cancel", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_cancel), + ("agent_workflow_retry_plan", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_retry_plan), + ("agent_workflow_retry_commit", "id,results,source_revision,session_id,principal_ref,resume_dir", agent_workflow_retry_commit), ("agent_error_make", "code,message,category", agent_error_make), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_tools_register", "spec,specs", agent_tools_register), diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs index 5e10548..f7d3578 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -245,6 +245,71 @@ pub fn next(args: &Value) -> Result { next_doc(&ckpt,id,false) } +/// Read a workflow summary without advancing it or running any step. +/// The caller-supplied identity must match the checkpoint, exactly like next. +pub fn inspect(args:&Value)->Result { + let id=field(args,"id")?; + let ckpt=read(args,id)?; + if ckpt["ok"]!=true || !check_context(args,&ckpt) { + return Ok(json!({"ok":false,"id":id,"status":"not_found_or_mismatched"})); + } + let (meta,index)=state(&ckpt)?; + let steps=meta["steps"].as_array().ok_or("invalid steps")?; + let completed=meta["completed"].as_array().ok_or("invalid completed")?; + // `status` is the durable checkpoint status; `action` is what tick would + // observe next (waiting_model, waiting_input, ready_tool, ...). + let action=next_doc(&ckpt,id,false)?.get("status").cloned().unwrap_or(Value::Null); + Ok(json!({ + "ok":true,"id":id, + "status":ckpt["status"].as_str().unwrap_or("running"), + "action":action, + "cursor":index, + "total_steps":steps.len(), + "completed_steps":completed.len(), + "completed":meta["completed"], + "step":steps.get(index).cloned().unwrap_or(Value::Null), + "partial":meta.get("partial").cloned().unwrap_or(Value::Null), + "identity":meta["identity"], + "updated_at":ckpt.get("updated_at").cloned().unwrap_or(Value::Null) + })) +} + +/// List workflow checkpoints in the (host-relative) resume directory. +/// Non-workflow checkpoints and corrupt entries are omitted. When the caller +/// supplies an attested session or principal, only matching runs are returned. +pub fn list(args:&Value)->Result { + let dir=storage(args)?; + let session=args.get("session_id").and_then(Value::as_str); + let principal=args.get("principal_ref").and_then(Value::as_str); + let mut items=Vec::new(); + let rd=fs::read_dir(&dir).map_err(|e|format!("workflow list: {e}"))?; + for ent in rd.flatten() { + let path=ent.path(); + if path.extension().and_then(|x|x.to_str())!=Some("json") { continue; } + if path.file_name().and_then(|x|x.to_str()) + .map(|x|x.starts_with('.')).unwrap_or(false) { continue; } + let Ok(text)=fs::read_to_string(&path) else { continue }; + let Ok(doc)=serde_json::from_str::(&text) else { continue }; + let meta=&doc["meta"]; + if meta["kind"].as_str()!=Some("MarqdoAgentFlowV1") { continue; } + if session.is_some() && meta["identity"]["session_id"].as_str()!=session { continue; } + if principal.is_some() && meta["identity"]["principal_ref"].as_str()!=principal { continue; } + let steps=meta["steps"].as_array().map(|x|x.len()).unwrap_or(0); + let completed=meta["completed"].as_array().map(|x|x.len()).unwrap_or(0); + items.push(json!({ + "id":doc.get("id").cloned().unwrap_or(Value::Null), + "status":doc.get("status").cloned().unwrap_or(Value::Null), + "cursor":meta.get("cursor").cloned().unwrap_or(Value::Null), + "total_steps":steps, + "completed_steps":completed, + "source_revision":meta["identity"]["source_revision"], + "updated_at":doc.get("updated_at").cloned().unwrap_or(Value::Null) + })); + } + items.sort_by(|a,b| a["id"].as_str().cmp(&b["id"].as_str())); + Ok(json!({"ok":true,"items":items,"resume_dir":dir.to_string_lossy()})) +} + /// Commit a verified result for the exact current step. All mutations are /// serialized with a lock; a completed step cannot be committed a second time. pub fn commit(args: &Value) -> Result { @@ -578,6 +643,29 @@ mod tests { assert_eq!(out["completed"][0]["value"]["items"][1]["result"]["value"]["value"],"fixed"); } + #[test] + fn inspect_and_list_are_read_only_and_session_scoped() { + let mut a=fixture(); + a["session_id"]=json!("s1"); + a["principal_ref"]=json!("u1"); + open(&a).unwrap(); + let seen=inspect(&a).unwrap(); + assert_eq!(seen["status"],"running"); + assert_eq!(seen["action"],"waiting_model"); + assert_eq!(seen["total_steps"],3); + assert_eq!(seen["completed_steps"],0); + assert_eq!(seen["step"]["id"],"choose"); + // Inspection must not consume the current step. + assert_eq!(next(&a).unwrap()["status"],"waiting_model"); + let listed=list(&a).unwrap(); + assert!(listed["items"].as_array().unwrap() + .iter().any(|x|x["id"]==a["id"])); + let mut other=a.clone(); + other["session_id"]=json!("s2"); + assert_eq!(inspect(&other).unwrap()["status"],"not_found_or_mismatched"); + assert!(list(&other).unwrap()["items"].as_array().unwrap().is_empty()); + } + #[test] fn explicit_cancel_stops_future_commits() { let a=fixture(); diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md index 418f787..83d8ca0 100644 --- a/tests/ext/ai-native-workflow.mq.md +++ b/tests/ext/ai-native-workflow.mq.md @@ -5,51 +5,89 @@ import: workflow: ext/ai/workflow.mq.md json: lib/json.mq.md sys: lib/sys.mq.md + time: lib/time.mq.md --- # main Offline test: the same Marqdo program advances through model choice, user -input and terminal state with plugin-owned durable checkpoints. +input and terminal state with plugin-owned durable checkpoints. The run ID and +checkpoint directory include the current millisecond so repeated local runs +start clean instead of reopening yesterday's completed workflow. + +**now = > time.now_ms** +**stamp = > json.stringify value=`now`** +**rid = "abi_flow_ci_" + stamp** +**dir = ".marqdo/ai-native-workflow-" + stamp** **steps = > json.parse text=[{"id":"intent","kind":"model","prompt":"Choose next skill","options":["chat","office"]},{"id":"confirm","kind":"input","question":"Continue?","options":["yes","no"]},{"id":"end","kind":"return"}]** -**opened = > workflow.open id="abi_flow_ci_20261118" steps=`steps` source_revision="flow-v1"** +**opened = > workflow.open id=`rid` steps=`steps` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **o = > json.get value=`opened` key="ok"** 1. `o` **_ = 1** 2. * > sys.exit code=21 -**first = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**seen = > workflow.inspect id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** +**seen_status = > json.get value=`seen` key="action"** +**seen_total = > json.get value=`seen` key="total_steps"** +1. `seen_status` == "waiting_model" + 1. `seen_total` == 3 + **_ = 1** + 2. * + > sys.exit code=30 +2. * + > sys.exit code=31 + +**listed = > workflow.list session_id="ci-session" resume_dir=`dir`** +**listed_ok = > json.get value=`listed` key="ok"** +**listed_items = > json.get value=`listed` key="items"** +**listed_n = > len value=`listed_items`** +1. `listed_ok` + 1. `listed_n` > 0 + **_ = 1** + 2. * + > sys.exit code=32 +2. * + > sys.exit code=33 + +**first = > workflow.next id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **first_state = > json.get value=`first` key="status"** 1. `first_state` == "waiting_model" **_ = 1** 2. * > sys.exit code=22 -**c1 = > workflow.commit id="abi_flow_ci_20261118" step_id="intent" response="chat" source_revision="flow-v1"** +**c1 = > workflow.commit id=`rid` step_id="intent" response="chat" source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **done1 = > json.get value=`c1` key="ok"** 1. `done1` **_ = 1** 2. * > sys.exit code=23 -**second = > workflow.tick id="abi_flow_ci_20261118" source_revision="flow-v1"** +**progress = > workflow.inspect id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** +**progress_done = > json.get value=`progress` key="completed_steps"** +1. `progress_done` == 1 + **_ = 1** +2. * + > sys.exit code=34 + +**second = > workflow.tick id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **second_state = > json.get value=`second` key="status"** 1. `second_state` == "waiting_input" **_ = 1** 2. * > sys.exit code=24 -**c2 = > workflow.commit id="abi_flow_ci_20261118" step_id="confirm" response="yes" source_revision="flow-v1"** +**c2 = > workflow.commit id=`rid` step_id="confirm" response="yes" source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **done2 = > json.get value=`c2` key="ok"** 1. `done2` **_ = 1** 2. * > sys.exit code=25 -**c3 = > workflow.tick id="abi_flow_ci_20261118" source_revision="flow-v1"** -**complete = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**c3 = > workflow.tick id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** +**complete = > workflow.next id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **status = > json.get value=`complete` key="status"** 1. `status` == "succeeded" **_ = 1** @@ -57,10 +95,11 @@ input and terminal state with plugin-owned durable checkpoints. > sys.exit code=26 **partial_steps = > json.parse text=[{"id":"children","kind":"parallel","effect_class":"read","tasks":[{"path":"worker-a.mq.md"},{"path":"worker-b.mq.md"}]}]** -**new_batch = > workflow.open id="abi_flow_partial_ci_20261118" steps=`partial_steps` source_revision="flow-v1"** +**prid = "abi_flow_partial_ci_" + stamp** +**new_batch = > workflow.open id=`prid` steps=`partial_steps` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **parts = > json.parse text=[{"ok":true,"value":{"code":0,"value":"useful"}},{"ok":false,"error":"timeout"}]** -**stopped = > workflow.commit id="abi_flow_partial_ci_20261118" step_id="children" response=`parts` source_revision="flow-v1"** -**reloaded = > workflow.next id="abi_flow_partial_ci_20261118" source_revision="flow-v1"** +**stopped = > workflow.commit id=`prid` step_id="children" response=`parts` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** +**reloaded = > workflow.next id=`prid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **partial = > json.get value=`reloaded` key="partial"** **survivors = > json.get value=`partial` key="succeeded"** 1. `survivors` == 1 @@ -68,14 +107,14 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=27 -**retry_plan = > workflow.retry_plan id="abi_flow_partial_ci_20261118" source_revision="flow-v1"** +**retry_plan = > workflow.retry_plan id=`prid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **allowed = > json.get value=`retry_plan` key="ok"** 1. `allowed` **_ = 1** 2. * > sys.exit code=28 **repaired = > json.parse text=[{"ok":true,"value":{"code":0,"value":"repaired"}}]** -**merged = > workflow.retry_commit id="abi_flow_partial_ci_20261118" results=`repaired` source_revision="flow-v1"** +**merged = > workflow.retry_commit id=`prid` results=`repaired` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`** **merged_ok = > json.get value=`merged` key="ok"** 1. `merged_ok` **_ = 1** From 87cfe0509509a27b7904adcc63fa8d61b5418e1f Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 12:40:41 +0800 Subject: [PATCH 67/74] docs(next): add 014 knowledge-anchor compilation direction Co-authored-by: Cursor --- doc/next/014.md | 575 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 575 insertions(+) create mode 100644 doc/next/014.md diff --git a/doc/next/014.md b/doc/next/014.md new file mode 100644 index 0000000..a2c727d --- /dev/null +++ b/doc/next/014.md @@ -0,0 +1,575 @@ +我会在后续继续完成开发,接下来我比较关心marqdo的知识编译的问题,你认为我将marqdo的函数内的语句成为锚点,或者说带标记的内容都成为锚点,方便使用[]()引用,成为知识编译的一种可行吗? + +**我认为完全可行,而且这可能是 Marqdo 实现“知识编译”最有价值的方向之一。** + +但我建议对你的设想做一个关键调整: + +> **所有可执行语句都成为编译器内部可定位的节点;所有具有明确标记的内容,都可以提升为稳定、可引用的知识锚点。** +> +> 锚点不仅用于跳转,还应该具备语义身份、依赖关系、执行能力、版本和验证状态。 + +这样,Marqdo 的函数就不再是一个只能整体调用的黑盒,而是一组能够逐层寻址、复用、验证和追溯的知识节点。 + +## **一、你的设想实际上已经有实现基础** + +我重新查看了 Marqdo `main` 分支的代码,发现你的想法与仓库已有设计高度一致,并不需要从零开始。 + +在 [可执行知识系统设计](https://github.com/cflmy/marqdo/blob/main/doc/design/executable-knowledge-system.md?utm_source=chatgpt.com) 中,你已经提出: + +- `#`:知识命名空间、类或知识实体。 +- `##`:具备参数和返回契约的可复用函数。 +- `[]()`:为函数内部的知识步骤命名,并保留原有执行语义。 +- 编译器将命名步骤转化为 `KnowledgeStep`,关联依赖、类型、来源和效果。 + +更重要的是,这不只是文档构想。目前 `src/sema/ir.rs` 已经实现了 `KnowledgeRef`、`KnowledgeStep` 和 `collect_named_steps`,并且能够识别部分遮蔽表达式、函数调用、循环和正文知识引用。 + +不过,现在的内部步骤 ID 采用类似 `#step-1`、`#step-2` 的序号形式。这种身份适合单次编译,却不适合长期知识引用:在函数前面插入一条新步骤,就可能改变后面所有步骤的编号。 + +因此,我认为下一阶段的重点不是“再增加一种锚点语法”,而是: + +**将已有的 KnowledgeStep 从编译期记录,升级为具备稳定身份的知识制品。** + +## **二、建议采用“两级锚点体系”** + +这比“把每一条语句都暴露为知识”更合理。 + +| 层级 | 生成规则 | 作用 | +| ------ | -------------------------- | ------------------ | +| 内部锚点 | 所有可执行 AST 语句自动生成 | 调试、数据流、执行追踪、增量编译 | +| 公共知识锚点 | `#`、`##`、带标记的表达式、显式标记的知识内容 | 跨函数引用、搜索、依赖分析、知识复用 | + +例如: + +``` + +# 订单定价 + +## 计算税额 + +根据订单地区查询税率,再计算应缴税额。 + +**税率 = [查询适用税率](税率库.查询(地区))** + +**税额 = [计算应缴税额](金额 * 税率)** + +*税额* + +``` + +编译器可以从这段普通 Marqdo 文档中建立以下结构: + +**订单定价** + +Class · 知识命名空间 + +**计算税额** + +Function · 公开可调用知识单元 + +**查询适用税率** + +Observe / Reuse + +**计算应缴税额** + +Derive + +数据依赖:税率 → 税额 + +**返回税额** + +Return · 函数结果 + +在这个结构中,两个标记步骤各有自己的地址,并且可以独立被查询、检查来源、进行影响分析。 + +这和普通代码索引有根本区别:它不仅知道“这个函数在哪里”,还知道**函数为什么得到这个结果,以及结果依赖哪些知识**。 + +## **三、最关键的语义区分:可引用不等于可执行** + +我认为这里必须制定严格的语义规范。 + +假设一个函数内部存在名为“查询适用税率”的锚点。 + +那么,其他文档引用它时,实际上存在三种不同需求: + +| 操作 | 期望行为 | +| ---- | --------------------- | +| 引用知识 | 找到该步骤,读取说明、实现和出处 | +| 获取结果 | 在已知输入和执行环境中取得该步骤的计算结果 | +| 复用执行 | 重新执行该步骤,产生新的计算结果 | + +**不能因为一个锚点存在,就允许它在任何地方被直接执行。** + +例如,函数内部的“计算应缴税额”依赖局部变量 `金额` 和 `税率`。假如其他函数直接引用这个步骤,编译器必须确认它需要哪些输入。 + +有两种合理的处理方式: + +- 默认只允许引用它的定义、来源和契约。 +- 需要独立执行时,必须拥有完整输入绑定;否则将它提取为独立 `##` 函数。 + +后续可以考虑由编译器自动将满足纯度、闭包与输入条件的知识步骤提升为可调用能力。但这应是第二阶段,不能在最初就隐式执行任何锚点。 + +### **不必重新设计 **`[]()`** 的基本语法** + +可以继续保留现有语义: + +``` +**税额 = [计算应缴税额](金额 * 税率)** +``` + +这里 `[]` 提供知识描述,`()` 保留表达式的执行含义。 + +另外,知识定位可以使用编译后的稳定地址,例如以下**拟议形式**: + +``` +[查看税率依据](mq://pricing/订单定价/计算税额#查询适用税率) +``` + +这应当被解释为知识引用,而不是自动重新执行“查询适用税率”。这里的 `mq://` 是建议的地址表示,不是说当前版本已经支持这样的写法。 + +我建议将 `KnowledgeRef` 按所在上下文分为: + +- 正文:解析目标和展示证据,不产生副作用。 +- 可执行表达式:按原有求值语义执行,并附带引用元数据。 +- 工具或智能体调用:额外要求可调用契约、输入闭合与权限验证。 + +这样 `[]()` 就能成为统一引用形式,同时不破坏现有 Markdown 的可读性。 + +## **四、怎样让锚点稳定** + +这是整个方案技术上最难、也最重要的地方。 + +**知识锚点不能用行号或内容哈希直接作为永久身份。** + +因为代码修改时: + +- 插入语句会改变行号。 +- 修改公式会改变哈希,但可能仍是同一个知识概念。 +- 修改描述名称不一定意味着知识实体改变。 +- 两个函数可能有相同的步骤名称。 + +因此,建议将三个概念拆开: + +| 概念 | 意义 | 变化规则 | +| ---------------- | --------- | --------- | +| `AnchorId` | 知识单元的稳定身份 | 尽量跨版本保持 | +| `ContentDigest` | 当前定义与实现 | 实现发生变化就更新 | +| `EvidenceDigest` | 来源与验证证据 | 证据变化时更新 | + +对于自动生成的锚点,可以先根据模块身份、所属函数、局部名称和结构位置确定候选身份,再通过上一版编译产物中的映射记录保持身份连续。 + +对于需要长期跨文档引用的公共知识锚点,可以允许显式稳定 ID,或者由编译器自动登记到知识索引中。**显式 ID 不必强制写在每个 **`[]()`** 中**,这样才能保持 Marqdo 的简洁性。 + +如果两个同级锚点都叫“查询适用税率”,编译器必须报告歧义,要求进一步限定,不能按出现顺序选择。 + +## **五、知识编译的最终产物应该是什么** + +我认为一个知识锚点至少需要这些字段: + +``` + +{ + "anchor_id": "pricing.tax.lookup", + "owner": "订单定价.计算税额", + "label": "查询适用税率", + "kind": "observe", + "inputs": ["地区"], + "outputs": ["税率"], + "dependencies": ["税率库.查询"], + "effects": ["read"], + "source_span": { + "file": "pricing.mq.md", + "line": 8 + }, + "content_digest": "...", + "evidence": [], + "verification": { + "resolved": true, + "tested": false, + "source_verified": false + } +} + +``` + +这是一份拟议的数据结构,`anchor_id` 仅为示例。 + +这里还有一项值得强调的区别:**知识可以编译成功,但并不代表知识在事实上正确。** + +例如读取“某地区税率”,编译器可以验证依赖、参数、数据类型、调用目标,却无法仅凭这些信息证明外部税率数据仍然有效。 + +所以应当把编译状态、测试状态、来源验证状态和领域正确性分别记录,而不能用一个 `verified=true` 概括所有问题。 + +### **推荐的编译流水线** + +1\. Parse + +读取 Markdown 与 Marqdo AST + +2\. Anchor + +为语句与标记内容建立地址和身份 + +3\. Resolve + +绑定函数、变量、知识引用和依赖 + +4\. Verify + +检查类型、契约、权限、来源和版本 + +5\. Emit + +生成知识图、锚点索引、引用锁与执行制品 + +这基本可以落在当前 `src/sema/` 和 `src/knowledge/` 的基础上,不需要开发第二套语言执行器。特别是现有 `SemanticProject` 已能导出 `steps.json`、`refs.json` 和 `artifacts`;真正需要扩展的是步骤的稳定身份、数据依赖、引用绑定以及验证信息。 + +## **六、我建议下一步怎么实现** + +优先做三个阶段,而不是一下将所有 Markdown 内容变成公开知识。 + +| 阶段 | 主要工作 | 验收 | +| ------- | ---------------------------------------- | ------------------ | +| M1:锚点身份 | 扩展 `KnowledgeStep`,建立稳定 `AnchorId` 和增量映射 | 插入其他语句后,原引用不漂移 | +| M2:锚点引用 | 扩展 `KnowledgeRef` 和语义解析,支持跨函数、跨文档的知识定位 | 能解析、检测歧义、建立反向依赖 | +| M3:知识制品 | 生成可查询的知识图、版本锁、验证与影响分析 | 改一条规则,可定位受影响的结果与叙述 | + +之后再增加局部知识步骤的独立执行、缓存、自动提取为函数,以及智能体按需发现知识的能力。 + +## **七、这对 Marqdo 的真正价值** + +我觉得这一方向比单纯强调“Markdown 可以执行”更有研究价值。 + +传统函数提供的是函数级抽象。你现在提出的机制则能够把抽象进一步下沉: + +**文档 → 类 → 函数 → 知识步骤 → 依赖与证据。** + +当智能体发现某个已有知识满足任务需求时,不需要再次生成代码,也不需要复制一段函数实现。它能够先定位知识节点,查询其契约与依据,再决定是引用现有结果、调用已有函数,还是创建新的知识。 + +但需要避免一个研究上的陷阱:**把语句赋予 ID 本身,不足以构成有说服力的知识编译创新。** 它仍可能被认为只是代码索引或细粒度程序分析。 + +真正值得验证的主张是: + +> **Marqdo 能否把自然语言标记与可执行语义编译为统一、稳定、可验证的知识节点,并在知识发生改变时,自动维护其引用、依赖和可信状态?** + +如果能够证明这件事,就形成了一条从可读 Markdown 到可执行知识库的清晰技术路径。 + +因此,我最推荐你的方案是:**函数内所有语句可定位,带标记的内容可公开引用,经过契约验证的知识节点才可独立复用执行。** + +这比让所有语句无差别地成为公共锚点更严谨,也更符合 Marqdo“代码即文档,文档即知识库,知识即可执行”的设计理念。 + +现在的marqdo更新到了2.8.0,我觉得自动证明和上面的知识编译有关系,你怎么看,可以给我什么建议? + +我认为 **Marqdo 2.8.0 的自动证明,与我们此前讨论的知识锚点和知识编译,实际上是同一技术体系中缺失的两块拼图**。 + +而且在重新阅读 2.8.0 的实现之后,我认为可以提出比“把代码变成知识图,再给函数附加证明”更进一步的目标: + +> **将 **`.mq.md`** 编译为可寻址、可执行、可组合,并携带机器可核验证据的知识制品。** + +这与 Marqdo 原来的“代码即文档,文档即知识库,知识即可执行”并不矛盾,而是让“知识”拥有了可以接受形式化检查的语义。 + +不过,我不建议把它直接表述为“Marqdo 自动证明知识正确”。当前 2.8.0 证明的是限定语义模型下的程序性质,而不是自然语言知识的全部真实性。 + +## **一、2.8.0 已经完成了哪些关键基础** + +我检查了 [2.8.0 发布说明](https://github.com/cflmy/marqdo/blob/main/doc/releases/v2.8.0.md?utm_source=chatgpt.com)、`src/prove/`、`src/sema/ir.rs` 和相关测试。 + +| 能力 | 2.8.0 的实际情况 | 与知识编译的关系 | +| ---- | ---------------------------------------------- | ----------------- | +| 语义编译 | 已有 SemanticArtifact、KnowledgeRef、KnowledgeStep | 知识的身份与结构 | +| 自动证明 | `marqdo prove` 将定理表及函数降级为 Lean 4 | 知识的形式化约束 | +| 离线判定 | F1–F5 符号执行;`checked` 不等于 `proved` | 快速、低成本检查 | +| 证明证书 | 记录证明状态、源码与工具链哈希 | 知识的可核验证据 | +| 反例 | 部分假命题能得到路径或区间见证 | 知识修复依据 | +| 组合证明 | 同模块简单纯函数有限内联 | 已有基础,但尚未形成模块化证明体系 | + +当前最值得注意的是:**语义编译器与证明编译器还没有围绕知识锚点形成完整的统一体系。** + +知识编译能够生成步骤和依赖,证明编译能够生成定理和证书,但尚不能自然地表达: + +“这个知识步骤依赖哪些已经证明的知识?证明依赖的知识修改后,哪些证书需要失效?调用者能否直接复用被调用知识的证明,而不必重新展开整个函数?” + +我认为,这就是 Marqdo 2.9 最值得解决的问题。 + +## **二、从知识锚点到可证明知识图** + +我建议让知识编译和证明编译共享同一套稳定的语义身份。 + +**Marqdo **`.mq.md` + +叙述、类、函数、`[]()`、定理表 + +**统一知识语义 IR** + +稳定身份 · 知识锚点 · 数据依赖 · 效果 · 契约 + +**知识编译** + +知识图、引用解析、影响分析、执行绑定 + +**证明编译** + +Proof IR、Lean、反例、证书 + +**可验证知识制品** + +Artifact + Contract + Proof Certificate + Dependencies + +关键变化不是简单地增加几条图上的 `proved_by` 边,而是让编译器能够基于同一份语义结构,分别生成执行内容、知识引用和证明义务。 + +我建议采用这样的分工: + +- `#`、`##` 为知识提供作用域和可调用边界。 +- `[]()` 为内部知识步骤提供可读名称和可寻址身份。 +- 现有契约表定义输入、输出及其他约束。 +- 现有定理表表达需要成立的命题。 +- `prove` 为满足证明条件的命题生成证书。 +- 知识编译器关联上述信息,生成统一知识制品。 + +**不需要为知识证明额外发明一套 Markdown 标记。** + +## **三、最值得实现的功能:证明能够沿知识引用传播** + +假设有三个知识单元: + +**A · 查询适用税率** + +契约:根据地区和时间,返回适用税率 + +证明:在已声明的数据有效性条件下,返回值满足范围约束 + +**B · 计算税额** + +依赖 A,并根据金额和税率进行计算 + +证明:假设 A 的契约成立,B 满足自己的计算性质 + +**C · 订单结算** + +依赖 B,并生成最终金额 + +证明:在 B 的前提与其他结算条件成立时,满足结算约束 + +现在修改 A 的内部实现。 + +传统方式下,B、C 可能要重新进行大量测试,或者依赖开发者人工检查。 + +我希望 Marqdo 能够做到: + +1. 重新编译 A,确认其契约与实现发生了哪些变化。 +2. 如果 A 的实现改变,但原契约仍被新证明支持,B 可以在依赖和证明上下文未变时继续复用已有证明。 +3. 如果 A 的契约不再得到支持,则 B 的相关证明变成 `stale` 或 `unverified`,并进一步影响 C。 +4. 只对受影响的证明义务重新运行 Lean,而不是重新证明所有知识。 + +**这就让知识图成为证明依赖图,同时使证明能够参与增量知识编译。** + +它与 2.8.0 当前的证书缓存有明显区别。当前缓存主要根据源码、Proof IR、库和工具链版本等生成复合键;未来应该进一步细化为: + +- 某个知识锚点的实现指纹。 +- 该锚点的公开契约。 +- 证明依赖的其他知识及其契约指纹。 +- 使用的假设和证明规则。 +- Lean 内核接受的证明及其环境身份。 + +这样才能精确控制哪些结果可以复用。 + +## **四、证明不一定只属于函数,也可以属于知识步骤** + +这是我认为你原先“所有带标记的内容成为锚点”构想最有价值的延伸。 + +2.8.0 的定理表目前属于函数级声明,位于函数首条可执行语句之前。这很合理,也应该保留为默认的公开契约。 + +例如: + +``` +# 审批 + +## 审批订单 + +| 定理 | 结论 | 前提 | 策略 | +|---|---|---|---| +| 大额必经人工 | 包含(轨迹, "人工审核") | 金额 > 10000 | auto | + +1. `金额` > 10000 + **回执 = [提交人工审核](人工审核(金额=`金额`))** +2. * + **回执 = [小额自动处理](自动处理(金额=`金额`))** + +*回执* +``` + +这个示例主要展示已有的定理表与遮蔽表达式如何结合,具体调用仍需要项目中的函数定义和类型契约。 + +现在证明的对象主要是 `## 审批订单` 的行为性质。 + +我认为将来可以增加一步: + +**把函数证明所涉及的知识步骤,映射到相应的锚点与依赖边。** + +例如,“大额必经人工”定理可以关联到“提交人工审核”知识锚点,同时记录证明是在什么输入条件和语义模型下成立的。 + +但是这里必须非常严格: + +- 证明整个函数满足某个性质,不意味着函数内部每个步骤都被单独证明正确。 +- `[提交人工审核]` 这个自然语言标签,不能自动当成形式化命题。 +- 证明轨迹包含“人工审核”,也不能证明外部审核服务真的完成了审核。 + +因此,**先做函数级证明向锚点的精确关联,再考虑锚点级局部证明**,会更稳妥。 + +## **五、建议的统一知识制品结构** + +我建议在现有 `SemanticArtifact`、`KnowledgeStep`、`KnowledgeRef` 之上增加证明关联层,而不是让 `src/prove` 生成第二套互不相认的知识身份。 + +下面是建议结构,并非 2.8.0 已有的完整 Schema。 + +``` + +{ + "anchor_id": "pricing.tax.calculate", + "symbol_id": "mq://project/pricing/function/calculate", + "kind": "derive", + "contract": { + "inputs": ["amount", "rate"], + "outputs": ["tax"] + }, + "dependencies": [ + "pricing.tax.lookup" + ], + "verification": { + "parse": "valid", + "resolve": "valid", + "proof": { + "status": "proved", + "claims": ["tax_formula"], + "certificate": "sha256:...", + "assumptions": [], + "scope": "function" + }, + "source": "unverified" + }, + "hashes": { + "interface": "...", + "implementation": "...", + "proof_dependencies": "..." + } +} + +``` + +一个很重要的设计是:`proof`** 不应该只是一个全局布尔值**。 + +不同知识锚点可能有不同性质:某个命题已经证明,另一个命题尚未证明,还有一个证明依赖不可靠的外部假设。 + +因此最小证明单元应当是: + +`(AnchorId, ClaimId, Assumptions, SemanticDigest, ProofCertificate)` + +而不是: + +`AnchorId → proved: true` + +这样调用者才能明确知道自己究竟复用了什么保证。 + +## **六、2.9 最应该优先实现的四项工作** + +| 优先级 | 工作 | 为什么重要 | +| --- | ----------------------------------------- | -------------- | +| P0 | 统一 `SymbolId`、`AnchorId`、定理身份 | 解决知识与证明的长期稳定绑定 | +| P1 | 将证明证书关联到 SemanticArtifact / KnowledgeStep | 建立知识与证明的直接关系 | +| P2 | 跨模块 assume-guarantee 证明组合 | 使证明可以跨知识引用传播 | +| P3 | 证明依赖图与增量失效分析 | 使大型知识库不必每次全量重证 | + +我尤其强调 P2。 + +因为从 2.8.0 发布说明可以看到,**跨模块调用目前仍视为不透明操作,而 assume-guarantee 后置条件复用明确延期到 2.9**。 + +这恰好是知识编译与自动证明结合的突破点。 + +假设 Marqdo 有两个函数: + +- `A` 已经证明后置条件 \\(Q_A\\)。 +- `B` 调用 `A`,希望证明自己的后置条件 \\(Q_B\\)。 + +那么 B 不必知道 A 的完整实现,只需要建立调用点的输入满足 A 前置条件,并利用 A 已经证明的后置条件完成自己的证明。 + +这正是契约组合推理的基本思路。 + +但证明必须明确依赖:A 的证书、其适用条件、A 与 B 的语义模型是否一致,以及任何外部假设。不能把未经验证的函数描述当作公理。 + +### **还需要优先修复两个证明语义边界** + +2.8.0 有两项已记录的差异,我建议不要在强化知识证明时忽略: + +- **i64 溢出**:解释器按有界整数处理并可能报错,而当前 Lean 模型使用无界 `Int`。 +- **除零/模零**:解释器产生运行时错误,Lean 底座目前存在返回 `.int 0` 的建模差异。 + +这意味着证明证书必须记录实际覆盖的数值范围和语义前提。未修复或没有证明等价的部分,不能被上层知识引用当成无条件可信的计算保证。 + +## **七、与智能体结合后,会产生什么变化?** + +这部分可能最符合你未来做科研智能体的方向。 + +过去智能体调用知识库时,主要依据名字、描述、检索相似度来选择已有能力。 + +未来可以让它先查询知识图,获得知识制品的: + +- 可执行入口与输入契约。 +- 形式化证明过的性质。 +- 来源与版本。 +- 未证明的假设和适用边界。 +- 是否受到近期源码或依赖修改的影响。 + +于是智能体不再只是“找到一个看起来相关的 SKILL”,而是可以选择一个**在当前任务条件下,拥有足够验证依据的知识能力**。 + +例如,量子科研智能体在寻找电路优化方法时,可以优先寻找具有等价性证明的电路变换,而不是每次重新生成并尝试未经验证的优化。 + +当然,这需要专门定义量子电路语义、等价关系和可信的验证过程;现有 2.8.0 的控制流证明还不能直接证明任意量子电路等价。 + +## **八、研究上怎样证明这条路线有价值?** + +我建议至少设计三个实验,不要只展示“Lean 可以证明 Marqdo”。 + +**实验 E1:知识修改与证明增量失效** + +在拥有大量相互引用的知识函数的项目中,修改其中某个函数,对比全量重新证明和基于锚点依赖的增量重新证明。 + +指标:重新证明的命题数、证明耗时、失效检测准确率,以及错误复用证书的次数(目标为零)。 + +**实验 E2:跨函数与跨文档证明复用** + +与 2.8.0 通过内联或不透明调用处理函数的方案相比,验证契约组合是否显著提升可证覆盖率。 + +指标:proved 比例、unverified/rejected 比例、证明时间、需要人工声明的假设数量。 + +**实验 E3:证明感知的智能体知识复用** + +让相同模型完成知识检索、函数复用与程序修改任务,对比普通语义检索、只使用知识图、知识图加证明证书三种方案。 + +指标:错误知识复用率、任务成功率、人工审核量、输入 Token 和总执行成本。 + +这三个实验分别验证“知识编译”、“证明组合”和“智能体使用价值”,能够避免把三个研究主张混成一个难以检验的宏大叙事。 + +## **我的总体判断** + +如果按照技术潜力排序,我会这样看: + +| 方向 | 评价 | +| ----------------- | ---------------- | +| 给所有语句生成锚点 | 必要的基础设施,但单独创新性有限 | +| 让 `[]()` 成为稳定知识引用 | 很有价值,能形成统一知识身份 | +| 让知识锚点携带可验证契约和证书 | 更有研究深度 | +| 让证明沿知识依赖传播并支持增量复用 | 我认为是最值得集中攻关的核心 | + +而且现在你拥有了一个很好的技术条件:**2.8.0 已经实现了真正的 Lean 证明路径,不再只是设计中的设想。** + +我建议将 Marqdo 2.9 的主线收敛成: + +**Proof-Carrying Executable Knowledge(携带证明的可执行知识)** + +但需要注意,Proof-Carrying Code、契约式程序验证和模块化证明本身都是已有研究。Marqdo 真正需要体现的区别,是它如何把 Markdown 原生描述、稳定知识锚点、可执行语义、证明义务与增量知识依赖统一编译为同一个制品体系,而非仅仅给代码加上证明。 + +一句话总结我的建议: + +**2.8.0 实现了“文档中的程序可以被证明”;2.9 应当实现“证明可以成为知识的一部分,并随着知识被引用、组合、验证和复用”。** + +我认为,这比单纯继续扩展 `marqdo prove` 可支持的表达式范围,更符合 Marqdo 的长期方向。 \ No newline at end of file From 166b01c86b1a373141ad6f1ca7f21d8aa73ec14c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 12:41:57 +0800 Subject: [PATCH 68/74] release(ext-2.8.1): AI native durable workflow pack notes and VERSION --- CHANGELOG.md | 36 ++++++++++++++++++------ README.md | 6 +++- doc/releases/ext-2.8.1.md | 59 +++++++++++++++++++++++++++++++++++++++ ext/VERSION | 2 +- 4 files changed, 92 insertions(+), 11 deletions(-) create mode 100644 doc/releases/ext-2.8.1.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7676640..0e78f77 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,13 +2,31 @@ ## Unreleased +## Ext pack v2.8.1 — 2026-11-18 + +### Highlights + +**AI native durable workflow(CLI 仍为 v2.8.0)**:`ext/ai` 以插件侧步骤机交付持久化 +工作流(`workflow`/`flow`/`context`/`recovery`),含有界模型选择、作用域上下文、 +只读失败恢复、`inspect`/`list` 与可隔离 `resume_dir`。不改解释器栈挂起,不宣称 +外部写 exactly-once。详见 [双语发布说明](doc/releases/ext-2.8.1.md)。 + +```bash +marqdo ext add agent # CDN latest → 2.8.1 +# 或:MARQDO_EXT_VERSION=2.8.1 marqdo ext add agent +``` + +**核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime。 + ### Added -- `ext/ai/workflow` now exposes read-only `inspect`/`list`, a host-relative - `resume_dir` on every operation, and repeatable offline workflow fixtures. -- Agent ABI registers `agent_workflow_inspect` and `agent_workflow_list`. -- AI 工作流拓展库新增只读 `inspect`/`list`、各操作的 `resume_dir` 隔离, - 离线集成夹具改为按时间戳生成运行 ID,可重复执行。 +- `ext/ai/workflow`:`open/next/commit/cancel/tick/retry_*`,以及只读 `inspect`/`list` + 与各操作的 host-relative `resume_dir`。 +- `ext/ai/flow` · `context` · `recovery`:ask/choose、作用域打包、CheckpointV2 恢复面。 +- Agent ABI:`agent_workflow_*`、`agent_choice_parse`、`agent_context_scope`、 + `agent_input_*`、`agent_parallel_report`。 +- Offline fixtures:`tests/ext/ai-native-flow.mq.md`、`tests/ext/ai-native-workflow.mq.md`; + CI:`.github/workflows/native-ai-flow.yml`。 ### Fixed @@ -16,13 +34,13 @@ contract; the repaired-choice path is fully scoped. - CI builds the agent cdylib and runs offline integration without the removed `run --effects` flag, using `MARQDO_AGENT_PLUGIN` instead. +- Atomic checkpoint/effect temp names no longer collide under parallel writes; + resume tests no longer race on process-wide cwd. ### Changed -- 分支已合并 v2.8.0:`Cargo.toml`/`Cargo.lock`、发布工作流与全部拓展包 - 统一到 2.8.0 依赖锁,后续发版不再从 2.7.1 基线分叉。 -- The branch now includes v2.8.0, so its crate versions, lockfile and release - workflows match the current release line instead of the 2.7.1 baseline. +- 扩展包 SemVer **2.8.1**(`ext/VERSION`);与 CLI **v2.8.0** 可独立安装。 +- 分支已合并 v2.8.0 依赖锁后的 AI 工作流增量,不再从 2.7.1 基线分叉。 ## v2.8.0 — 2026-11-17 diff --git a/README.md b/README.md index 09a02bd..5f92763 100755 --- a/README.md +++ b/README.md @@ -117,7 +117,7 @@ marqdo view examples/procurement --no-open Agent Skills already support scripts; Marqdo's claim is **one document-native language surface** for authoring, inspecting, executing and reusing functions. This is **not** a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior. -**Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/) +**Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Ext pack 2.8.1](https://github.com/cflmy/marqdo/releases/tag/ext-v2.8.1) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/) --- @@ -128,8 +128,12 @@ Agent Skills already support scripts; Marqdo's claim is **one document-native la 当前 CLI **2.8.0** 新增 `marqdo prove`:知识文件的定理表编译为 Lean 4 并自动判定真假——没有 Lean 工具链也能离线符号执行(诚实降级,绝不冒充证明),有 Lean 时全链路证明并给出反例见证。参见[发布说明](doc/releases/v2.8.0.md)。 +独立拓展包 **2.8.1**(CLI 仍为 2.8.0):`ext/ai` 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / `inspect`)。`marqdo ext add agent` → CDN latest。参见[拓展包说明](doc/releases/ext-2.8.1.md)。 + CLI **2.8.0** adds `marqdo prove`: theorem tables in knowledge files compile to Lean 4 and are judged automatically — offline symbolic execution without a toolchain (honest degradation, never impersonating a proof), full proofs with counterexample witnesses when Lean is available. +Ext pack **2.8.1** (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and `inspect`. + ## 核心优势:可执行知识(Executable Knowledge) > **Knowledge That Can Run —— 知识即可执行。** diff --git a/doc/releases/ext-2.8.1.md b/doc/releases/ext-2.8.1.md new file mode 100644 index 0000000..3a21632 --- /dev/null +++ b/doc/releases/ext-2.8.1.md @@ -0,0 +1,59 @@ +# Ext pack v2.8.1 发布说明 · Release Notes(AI native flow) + +## 1. 一句话 + +独立拓展包 **2.8.1**(CLI 仍为 **2.8.0**):`ext/ai` 交付插件侧持久化工作流——显式 `open/next/commit/cancel`、 +有界模型选择、作用域上下文、只读失败恢复,以及 `inspect/list` 与可隔离的 `resume_dir`。 +不改解释器栈挂起语义,也不宣称外部写的 exactly-once。 + +Independent extension pack **2.8.1** (CLI remains **2.8.0**): `ext/ai` ships a plugin-only +durable workflow — explicit `open/next/commit/cancel`, bounded model choice, scoped +context packing, failed-only read-only recovery, plus `inspect/list` and isolatable +`resume_dir`. No interpreter-stack suspension and no exactly-once external-write claim. + +## 2. 亮点(Highlights) + +| | | +|---|---| +| 持久步骤机 | `plugins/agent` `workflow`:`open/next/commit/cancel/retry_*`,CheckpointV2,逐步提交边界 | +| 作者面 | `ext/ai/workflow` · `flow` · `context` · `recovery`;`tick` 单步执行,等待输入不阻塞解释器线程 | +| 选择解析 | 精确 / 编号 / 标签 / 短中英句 / JSON 信封;歧义与未知路径失败关闭 | +| 作用域上下文 | Markdown 感知的 file/class/function 摘录;歧义拒绝;不把整库 import 塞进提示 | +| 安全并行恢复 | 保留成功兄弟结果;仅重试已分类为只读的失败子任务;写/未知效应不自动派发 | +| 可观测性 | `inspect`/`list` 只读进度;测试与调用方可传入 host-relative `resume_dir` | + +设计契约:[native-agent-flow-v3.md](../design/native-agent-flow-v3.md)。 + +## 3. 安装(Install) + +```bash +marqdo ext add agent # CDN / Releases → 2.8.1 +# 或:MARQDO_EXT_VERSION=2.8.1 marqdo ext add agent +marqdo ext add llm +``` + +产物:`marqdo-2.8.1-ext.zip` 与双平台 native ZIP(含 agent / llm 等既有原生库)。 + +## 4. 验证(Validation) + +```bash +cargo test -p marqdo_plugin_agent --locked +cargo run --locked -- check ext/ai/flow.mq.md +cargo run --locked -- check ext/ai/context.mq.md +cargo run --locked -- check ext/ai/recovery.mq.md +cargo run --locked -- check ext/ai/workflow.mq.md +cargo run --locked -- run tests/ext/ai-native-flow.mq.md +cargo run --locked -- run tests/ext/ai-native-workflow.mq.md +``` + +CI:`.github/workflows/native-ai-flow.yml` 与 `extension-release.yml`(`ext-v2.8.1`)。 + +## 5. 已知限制(Known limitations) + +- 输入闸门保存的是**步骤边界**,不是任意字节码解释器帧;回复后须显式进入下一 Marqdo 函数。 +- 作用域选择依赖 Markdown 标题约定,不是编译器已解析的 AST 符号表。 +- 调用方提供的 principal/session/source revision 须由已认证宿主证明,不能来自模型文本。 +- 并行复用 `subtask.run_many`;跨进程子任务租约与已在跑外部进程的取消传播仍待专项注入验证。 +- 实时大模型与目标 1B 本地模型评测仍开放;写效应自动重试仍被拒绝,直至 EffectLedger 对账完成。 + +**核心表面 Δ**:无增删——19 个核心构造不变;本包为 Extension / Agent Runtime。 diff --git a/ext/VERSION b/ext/VERSION index 24ba9a3..dbe5900 100755 --- a/ext/VERSION +++ b/ext/VERSION @@ -1 +1 @@ -2.7.0 +2.8.1 From 9ce2ae10374ce8317e7174685bf57ce5c3ecd9b7 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 13:08:59 +0800 Subject: [PATCH 69/74] release(ext-2.8.2): fix Windows packs.ci root and ship AI durable workflow --- .github/workflows/extension-release.yml | 14 +++--- CHANGELOG.md | 17 ++++---- README.md | 6 +-- doc/releases/ext-2.8.2.md | 58 +++++++++++++++++++++++++ ext/VERSION | 2 +- ext/engineering/index.mq.md | 2 +- plugins/engineering/src/lib.rs | 28 ++++++++++-- skills/marqdo-release/packs.mq.md | 3 +- 8 files changed, 108 insertions(+), 22 deletions(-) create mode 100644 doc/releases/ext-2.8.2.md diff --git a/.github/workflows/extension-release.yml b/.github/workflows/extension-release.yml index 21cb812..d9240e3 100755 --- a/.github/workflows/extension-release.yml +++ b/.github/workflows/extension-release.yml @@ -32,11 +32,15 @@ jobs: cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering bash scripts/build-web-plugin.sh - name: Build and validate the runner's exact pack bytes - shell: pwsh - run: ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.write,environment.read --fs-root . --require-ok --json + shell: bash + run: | + set -euo pipefail + ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json - name: Attach source and Windows native packs without replacement - shell: pwsh - run: ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json + shell: bash + run: | + set -euo pipefail + ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json linux: runs-on: ubuntu-latest @@ -59,6 +63,6 @@ jobs: cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering bash scripts/build-web-plugin.sh - name: Build and validate the runner's exact pack bytes - run: target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.write,environment.read --fs-root . --require-ok --json + run: target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json - name: Attach Linux native pack without replacement run: target/release/marqdo call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e78f77..d4227e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,18 +2,17 @@ ## Unreleased -## Ext pack v2.8.1 — 2026-11-18 +## Ext pack v2.8.2 — 2026-11-18 ### Highlights -**AI native durable workflow(CLI 仍为 v2.8.0)**:`ext/ai` 以插件侧步骤机交付持久化 -工作流(`workflow`/`flow`/`context`/`recovery`),含有界模型选择、作用域上下文、 -只读失败恢复、`inspect`/`list` 与可隔离 `resume_dir`。不改解释器栈挂起,不宣称 -外部写 exactly-once。详见 [双语发布说明](doc/releases/ext-2.8.1.md)。 +**AI native durable workflow + Windows pack CI fix(CLI 仍为 v2.8.0)**:能力同 2.8.1; +修复 Windows `packs.ci` 的 engineering root 解析(`root does not exist`),双平台 +可发布。`ext-v2.8.1` 已打标但未完成资产。详见 [双语发布说明](doc/releases/ext-2.8.2.md)。 ```bash -marqdo ext add agent # CDN latest → 2.8.1 -# 或:MARQDO_EXT_VERSION=2.8.1 marqdo ext add agent +marqdo ext add agent # CDN latest → 2.8.2 +# 或:MARQDO_EXT_VERSION=2.8.2 marqdo ext add agent ``` **核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime。 @@ -36,10 +35,12 @@ marqdo ext add agent # CDN latest → 2.8.1 `run --effects` flag, using `MARQDO_AGENT_PLUGIN` instead. - Atomic checkpoint/effect temp names no longer collide under parallel writes; resume tests no longer race on process-wide cwd. +- Windows `extension-release`:engineering root 使用 `path.join` / cwd 回退, + `packs.ci` 传入绝对 checkout,并授予 `fs.read`。 ### Changed -- 扩展包 SemVer **2.8.1**(`ext/VERSION`);与 CLI **v2.8.0** 可独立安装。 +- 扩展包 SemVer **2.8.2**(`ext/VERSION`);与 CLI **v2.8.0** 可独立安装。 - 分支已合并 v2.8.0 依赖锁后的 AI 工作流增量,不再从 2.7.1 基线分叉。 ## v2.8.0 — 2026-11-17 diff --git a/README.md b/README.md index 5f92763..86372a3 100755 --- a/README.md +++ b/README.md @@ -117,7 +117,7 @@ marqdo view examples/procurement --no-open Agent Skills already support scripts; Marqdo's claim is **one document-native language surface** for authoring, inspecting, executing and reusing functions. This is **not** a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior. -**Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Ext pack 2.8.1](https://github.com/cflmy/marqdo/releases/tag/ext-v2.8.1) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/) +**Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Ext pack 2.8.2](https://github.com/cflmy/marqdo/releases/tag/ext-v2.8.2) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/) --- @@ -128,11 +128,11 @@ Agent Skills already support scripts; Marqdo's claim is **one document-native la 当前 CLI **2.8.0** 新增 `marqdo prove`:知识文件的定理表编译为 Lean 4 并自动判定真假——没有 Lean 工具链也能离线符号执行(诚实降级,绝不冒充证明),有 Lean 时全链路证明并给出反例见证。参见[发布说明](doc/releases/v2.8.0.md)。 -独立拓展包 **2.8.1**(CLI 仍为 2.8.0):`ext/ai` 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / `inspect`)。`marqdo ext add agent` → CDN latest。参见[拓展包说明](doc/releases/ext-2.8.1.md)。 +独立拓展包 **2.8.2**(CLI 仍为 2.8.0):`ext/ai` 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / `inspect`)。`marqdo ext add agent` → CDN latest。参见[拓展包说明](doc/releases/ext-2.8.2.md)。 CLI **2.8.0** adds `marqdo prove`: theorem tables in knowledge files compile to Lean 4 and are judged automatically — offline symbolic execution without a toolchain (honest degradation, never impersonating a proof), full proofs with counterexample witnesses when Lean is available. -Ext pack **2.8.1** (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and `inspect`. +Ext pack **2.8.2** (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and `inspect`. ## 核心优势:可执行知识(Executable Knowledge) diff --git a/doc/releases/ext-2.8.2.md b/doc/releases/ext-2.8.2.md new file mode 100644 index 0000000..36e551c --- /dev/null +++ b/doc/releases/ext-2.8.2.md @@ -0,0 +1,58 @@ +# Ext pack v2.8.2 发布说明 · Release Notes(AI native flow) + +## 1. 一句话 + +独立拓展包 **2.8.2**(CLI 仍为 **2.8.0**):在 2.8.1 的 AI 持久化工作流之上,修复 Windows +`extension-release` 打包根路径(`root does not exist`),使双平台 ZIP 可发布。 +`ext-v2.8.1` 标签保留但未形成完整 Release 资产。 + +Independent extension pack **2.8.2** (CLI remains **2.8.0**): AI durable workflows from +2.8.1, plus a Windows `extension-release` checkout-root fix (`root does not exist`) so +both-platform ZIPs can publish. Tag `ext-v2.8.1` remains but did not complete assets. + +## 2. 亮点(Highlights) + +| | | +|---|---| +| 持久步骤机 | `plugins/agent` `workflow`:`open/next/commit/cancel/retry_*`,CheckpointV2,逐步提交边界 | +| 作者面 | `ext/ai/workflow` · `flow` · `context` · `recovery`;`tick` 单步执行,等待输入不阻塞解释器线程 | +| 选择解析 | 精确 / 编号 / 标签 / 短中英句 / JSON 信封;歧义与未知路径失败关闭 | +| 作用域上下文 | Markdown 感知的 file/class/function 摘录;歧义拒绝;不把整库 import 塞进提示 | +| 安全并行恢复 | 保留成功兄弟结果;仅重试已分类为只读的失败子任务;写/未知效应不自动派发 | +| 可观测性 | `inspect`/`list` 只读进度;测试与调用方可传入 host-relative `resume_dir` | + +设计契约:[native-agent-flow-v3.md](../design/native-agent-flow-v3.md)。 + +## 3. 安装(Install) + +```bash +marqdo ext add agent # CDN / Releases → 2.8.2 +# 或:MARQDO_EXT_VERSION=2.8.2 marqdo ext add agent +marqdo ext add llm +``` + +产物:`marqdo-2.8.2-ext.zip` 与双平台 native ZIP(含 agent / llm 等既有原生库)。 + +## 4. 验证(Validation) + +```bash +cargo test -p marqdo_plugin_agent --locked +cargo run --locked -- check ext/ai/flow.mq.md +cargo run --locked -- check ext/ai/context.mq.md +cargo run --locked -- check ext/ai/recovery.mq.md +cargo run --locked -- check ext/ai/workflow.mq.md +cargo run --locked -- run tests/ext/ai-native-flow.mq.md +cargo run --locked -- run tests/ext/ai-native-workflow.mq.md +``` + +CI:`.github/workflows/native-ai-flow.yml` 与 `extension-release.yml`(`ext-v2.8.2`)。 + +## 5. 已知限制(Known limitations) + +- 输入闸门保存的是**步骤边界**,不是任意字节码解释器帧;回复后须显式进入下一 Marqdo 函数。 +- 作用域选择依赖 Markdown 标题约定,不是编译器已解析的 AST 符号表。 +- 调用方提供的 principal/session/source revision 须由已认证宿主证明,不能来自模型文本。 +- 并行复用 `subtask.run_many`;跨进程子任务租约与已在跑外部进程的取消传播仍待专项注入验证。 +- 实时大模型与目标 1B 本地模型评测仍开放;写效应自动重试仍被拒绝,直至 EffectLedger 对账完成。 + +**核心表面 Δ**:无增删——19 个核心构造不变;本包为 Extension / Agent Runtime。 diff --git a/ext/VERSION b/ext/VERSION index dbe5900..1817afe 100755 --- a/ext/VERSION +++ b/ext/VERSION @@ -1 +1 @@ -2.8.1 +2.8.2 diff --git a/ext/engineering/index.mq.md b/ext/engineering/index.mq.md index f3f73df..1e96cdd 100755 --- a/ext/engineering/index.mq.md +++ b/ext/engineering/index.mq.md @@ -71,7 +71,7 @@ authentication is resolved inside the plugin from existing stores. We **loaded = [Load this package's native boundary](_load())** and **base = [Read the granted runtime working root](sys.cwd())** and **resolved_root = root**. 1. not [The requested root is already absolute](paths.is_absolute(path=`root`)) - We **resolved_root = base + "/" + root** so process and native filesystem locations agree. + We **resolved_root = [Join the runtime cwd with the relative grant](paths.join(a=`base`, b=`root`))** so Windows and Unix separators stay native. `request_data` = diff --git a/plugins/engineering/src/lib.rs b/plugins/engineering/src/lib.rs index f0c5ffc..50ac2ff 100755 --- a/plugins/engineering/src/lib.rs +++ b/plugins/engineering/src/lib.rs @@ -32,10 +32,16 @@ fn read_bounded(mut r: impl Read, max: u64) -> Result, String> { if b.len() as u64 > max { return Err("bounded input limit exceeded".into()); } Ok(b) } +fn strip_verbatim(path: &Path) -> &Path { + path.strip_prefix(r"\\?\").unwrap_or(path) +} + fn scoped(root: &Path, relative: &str) -> Result { let p = root.join(relative).canonicalize().map_err(|_| "path does not exist")?; - if !p.starts_with(root) { return Err("artifact path escapes the selected root".into()); } - Ok(p) + if p.starts_with(root) || strip_verbatim(&p).starts_with(strip_verbatim(root)) { + return Ok(p); + } + Err("artifact path escapes the selected root".into()) } fn homes(root: &Path) -> Vec { let mut out = Vec::new(); @@ -498,8 +504,24 @@ fn gzip_text(p: &Value) -> Answer { Ok(json!(String::from_utf8(plain).map_err(|_| "gzip text is not UTF-8")?)) } +fn resolve_root(request: &Value) -> Result { + let raw = request.get("root").and_then(Value::as_str).unwrap_or("."); + let selected = PathBuf::from(raw); + if let Ok(path) = selected.canonicalize() { + return Ok(path); + } + // Relative grants must still resolve when the caller only passed "." and the + // process cwd is the intended checkout (Windows runners are sensitive here). + if raw == "." || raw.is_empty() { + return std::env::current_dir() + .and_then(|p| p.canonicalize()) + .map_err(|e| format!("root does not exist ({raw}: {e})")); + } + Err(format!("root does not exist ({raw})")) +} + fn dispatch(request:&Value)->Answer { - let root=PathBuf::from(request.get("root").and_then(Value::as_str).unwrap_or(".")).canonicalize().map_err(|_|"root does not exist")?; + let root=resolve_root(request)?; let op=field(request,"operation")?; let empty=json!({});let p=request.get("payload").unwrap_or(&empty); match op { diff --git a/skills/marqdo-release/packs.mq.md b/skills/marqdo-release/packs.mq.md index a10f1b7..6189b11 100755 --- a/skills/marqdo-release/packs.mq.md +++ b/skills/marqdo-release/packs.mq.md @@ -102,7 +102,8 @@ We **destination = [Resolve the new archive inside the granted root](fs.resolve( | `destination` | | `entry` | -Return *[Encode only the explicitly staged format subtree](engineering.checked(argv=`argv`, cwd=`stage`, timeout_ms=300000, max_output=65536))*. +We **checkout = [Use the absolute runtime checkout as the plugin root](sys.cwd())**. +Return *[Encode only the explicitly staged format subtree](engineering.checked(argv=`argv`, cwd=`stage`, timeout_ms=300000, max_output=65536, root=`checkout`))*. ## _receipt From e5580d9640fe512c9d9ea0837254980a577dedab Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 13:25:09 +0800 Subject: [PATCH 70/74] release(ext-2.8.3): use Windows System32 tar for pack ZIP encoding --- CHANGELOG.md | 13 +++---- README.md | 6 ++-- doc/releases/ext-2.8.3.md | 60 +++++++++++++++++++++++++++++++ ext/VERSION | 2 +- skills/marqdo-release/packs.mq.md | 2 +- 5 files changed, 72 insertions(+), 11 deletions(-) create mode 100644 doc/releases/ext-2.8.3.md diff --git a/CHANGELOG.md b/CHANGELOG.md index d4227e7..75f2368 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,17 +2,17 @@ ## Unreleased -## Ext pack v2.8.2 — 2026-11-18 +## Ext pack v2.8.3 — 2026-11-18 ### Highlights **AI native durable workflow + Windows pack CI fix(CLI 仍为 v2.8.0)**:能力同 2.8.1; -修复 Windows `packs.ci` 的 engineering root 解析(`root does not exist`),双平台 -可发布。`ext-v2.8.1` 已打标但未完成资产。详见 [双语发布说明](doc/releases/ext-2.8.2.md)。 +修复 Windows engineering root,以及 Git Bash 下误用 GNU `tar` 导致 zip 失败——改用 +`C:\Windows\System32\tar.exe`。详见 [双语发布说明](doc/releases/ext-2.8.3.md)。 ```bash -marqdo ext add agent # CDN latest → 2.8.2 -# 或:MARQDO_EXT_VERSION=2.8.2 marqdo ext add agent +marqdo ext add agent # CDN latest → 2.8.3 +# 或:MARQDO_EXT_VERSION=2.8.3 marqdo ext add agent ``` **核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime。 @@ -37,10 +37,11 @@ marqdo ext add agent # CDN latest → 2.8.2 resume tests no longer race on process-wide cwd. - Windows `extension-release`:engineering root 使用 `path.join` / cwd 回退, `packs.ci` 传入绝对 checkout,并授予 `fs.read`。 +- Windows ZIP 编码显式调用 `System32\tar.exe`(bsdtar),避免 Git Bash GNU tar。 ### Changed -- 扩展包 SemVer **2.8.2**(`ext/VERSION`);与 CLI **v2.8.0** 可独立安装。 +- 扩展包 SemVer **2.8.3**(`ext/VERSION`);与 CLI **v2.8.0** 可独立安装。 - 分支已合并 v2.8.0 依赖锁后的 AI 工作流增量,不再从 2.7.1 基线分叉。 ## v2.8.0 — 2026-11-17 diff --git a/README.md b/README.md index 86372a3..11a6b66 100755 --- a/README.md +++ b/README.md @@ -117,7 +117,7 @@ marqdo view examples/procurement --no-open Agent Skills already support scripts; Marqdo's claim is **one document-native language surface** for authoring, inspecting, executing and reusing functions. This is **not** a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior. -**Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Ext pack 2.8.2](https://github.com/cflmy/marqdo/releases/tag/ext-v2.8.2) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/) +**Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Ext pack 2.8.3](https://github.com/cflmy/marqdo/releases/tag/ext-v2.8.3) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/) --- @@ -128,11 +128,11 @@ Agent Skills already support scripts; Marqdo's claim is **one document-native la 当前 CLI **2.8.0** 新增 `marqdo prove`:知识文件的定理表编译为 Lean 4 并自动判定真假——没有 Lean 工具链也能离线符号执行(诚实降级,绝不冒充证明),有 Lean 时全链路证明并给出反例见证。参见[发布说明](doc/releases/v2.8.0.md)。 -独立拓展包 **2.8.2**(CLI 仍为 2.8.0):`ext/ai` 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / `inspect`)。`marqdo ext add agent` → CDN latest。参见[拓展包说明](doc/releases/ext-2.8.2.md)。 +独立拓展包 **2.8.3**(CLI 仍为 2.8.0):`ext/ai` 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / `inspect`)。`marqdo ext add agent` → CDN latest。参见[拓展包说明](doc/releases/ext-2.8.3.md)。 CLI **2.8.0** adds `marqdo prove`: theorem tables in knowledge files compile to Lean 4 and are judged automatically — offline symbolic execution without a toolchain (honest degradation, never impersonating a proof), full proofs with counterexample witnesses when Lean is available. -Ext pack **2.8.2** (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and `inspect`. +Ext pack **2.8.3** (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and `inspect`. ## 核心优势:可执行知识(Executable Knowledge) diff --git a/doc/releases/ext-2.8.3.md b/doc/releases/ext-2.8.3.md new file mode 100644 index 0000000..6fd12f4 --- /dev/null +++ b/doc/releases/ext-2.8.3.md @@ -0,0 +1,60 @@ +# Ext pack v2.8.3 发布说明 · Release Notes(AI native flow) + +## 1. 一句话 + +独立拓展包 **2.8.3**(CLI 仍为 **2.8.0**):交付 `ext/ai` 插件侧持久化工作流,并修复 +Windows `extension-release` 打包(engineering root + 强制使用 `System32\tar.exe` +bsdtar)。`ext-v2.8.1` / `ext-v2.8.2` 标签保留但未形成完整 Release 资产。 + +Independent extension pack **2.8.3** (CLI remains **2.8.0**): ships `ext/ai` plugin-only +durable workflows and fixes Windows `extension-release` packaging (engineering root +plus explicit `System32\tar.exe` bsdtar). Tags `ext-v2.8.1` / `ext-v2.8.2` remain +without complete release assets. + +## 2. 亮点(Highlights) + +| | | +|---|---| +| 持久步骤机 | `plugins/agent` `workflow`:`open/next/commit/cancel/retry_*`,CheckpointV2,逐步提交边界 | +| 作者面 | `ext/ai/workflow` · `flow` · `context` · `recovery`;`tick` 单步执行,等待输入不阻塞解释器线程 | +| 选择解析 | 精确 / 编号 / 标签 / 短中英句 / JSON 信封;歧义与未知路径失败关闭 | +| 作用域上下文 | Markdown 感知的 file/class/function 摘录;歧义拒绝;不把整库 import 塞进提示 | +| 安全并行恢复 | 保留成功兄弟结果;仅重试已分类为只读的失败子任务;写/未知效应不自动派发 | +| 可观测性 | `inspect`/`list` 只读进度;测试与调用方可传入 host-relative `resume_dir` | +| Windows CI | `path.join` 根路径;`C:\Windows\System32\tar.exe --format=zip` | + +设计契约:[native-agent-flow-v3.md](../design/native-agent-flow-v3.md)。 + +## 3. 安装(Install) + +```bash +marqdo ext add agent # CDN / Releases → 2.8.3 +# 或:MARQDO_EXT_VERSION=2.8.3 marqdo ext add agent +marqdo ext add llm +``` + +产物:`marqdo-2.8.3-ext.zip` 与双平台 native ZIP(含 agent / llm 等既有原生库)。 + +## 4. 验证(Validation) + +```bash +cargo test -p marqdo_plugin_agent --locked +cargo run --locked -- check ext/ai/flow.mq.md +cargo run --locked -- check ext/ai/context.mq.md +cargo run --locked -- check ext/ai/recovery.mq.md +cargo run --locked -- check ext/ai/workflow.mq.md +cargo run --locked -- run tests/ext/ai-native-flow.mq.md +cargo run --locked -- run tests/ext/ai-native-workflow.mq.md +``` + +CI:`.github/workflows/native-ai-flow.yml` 与 `extension-release.yml`(`ext-v2.8.3`)。 + +## 5. 已知限制(Known limitations) + +- 输入闸门保存的是**步骤边界**,不是任意字节码解释器帧;回复后须显式进入下一 Marqdo 函数。 +- 作用域选择依赖 Markdown 标题约定,不是编译器已解析的 AST 符号表。 +- 调用方提供的 principal/session/source revision 须由已认证宿主证明,不能来自模型文本。 +- 并行复用 `subtask.run_many`;跨进程子任务租约与已在跑外部进程的取消传播仍待专项注入验证。 +- 实时大模型与目标 1B 本地模型评测仍开放;写效应自动重试仍被拒绝,直至 EffectLedger 对账完成。 + +**核心表面 Δ**:无增删——19 个核心构造不变;本包为 Extension / Agent Runtime。 diff --git a/ext/VERSION b/ext/VERSION index 1817afe..9f8d8a9 100755 --- a/ext/VERSION +++ b/ext/VERSION @@ -1 +1 @@ -2.8.2 +2.8.3 diff --git a/skills/marqdo-release/packs.mq.md b/skills/marqdo-release/packs.mq.md index 6189b11..0a2c67b 100755 --- a/skills/marqdo-release/packs.mq.md +++ b/skills/marqdo-release/packs.mq.md @@ -96,7 +96,7 @@ We **destination = [Resolve the new archive inside the granted root](fs.resolve( | argument | |---| - | tar | + | "C:\\Windows\\System32\\tar.exe" | | "--format=zip" | | "-cf" | | `destination` | From 8db699191e0ca309752e66c3d55da9c65f9bcd5b Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 13:37:02 +0800 Subject: [PATCH 71/74] release(ext-2.8.1): AI durable workflow pack with Windows packaging fixes --- CHANGELOG.md | 20 ++++++------- README.md | 6 ++-- doc/releases/ext-2.8.1.md | 19 ++++++++----- doc/releases/ext-2.8.2.md | 58 ------------------------------------- doc/releases/ext-2.8.3.md | 60 --------------------------------------- ext/VERSION | 2 +- 6 files changed, 26 insertions(+), 139 deletions(-) delete mode 100644 doc/releases/ext-2.8.2.md delete mode 100644 doc/releases/ext-2.8.3.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 75f2368..c2867e8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,17 +2,18 @@ ## Unreleased -## Ext pack v2.8.3 — 2026-11-18 +## Ext pack v2.8.1 — 2026-11-18 ### Highlights -**AI native durable workflow + Windows pack CI fix(CLI 仍为 v2.8.0)**:能力同 2.8.1; -修复 Windows engineering root,以及 Git Bash 下误用 GNU `tar` 导致 zip 失败——改用 -`C:\Windows\System32\tar.exe`。详见 [双语发布说明](doc/releases/ext-2.8.3.md)。 +**AI native durable workflow(CLI 仍为 v2.8.0)**:`ext/ai` 以插件侧步骤机交付持久化 +工作流(`workflow`/`flow`/`context`/`recovery`),含有界模型选择、作用域上下文、 +只读失败恢复、`inspect`/`list` 与可隔离 `resume_dir`。Windows 打包使用 `path.join` +根路径与 `System32\tar.exe`。详见 [双语发布说明](doc/releases/ext-2.8.1.md)。 ```bash -marqdo ext add agent # CDN latest → 2.8.3 -# 或:MARQDO_EXT_VERSION=2.8.3 marqdo ext add agent +marqdo ext add agent # CDN latest → 2.8.1 +# 或:MARQDO_EXT_VERSION=2.8.1 marqdo ext add agent ``` **核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime。 @@ -35,13 +36,12 @@ marqdo ext add agent # CDN latest → 2.8.3 `run --effects` flag, using `MARQDO_AGENT_PLUGIN` instead. - Atomic checkpoint/effect temp names no longer collide under parallel writes; resume tests no longer race on process-wide cwd. -- Windows `extension-release`:engineering root 使用 `path.join` / cwd 回退, - `packs.ci` 传入绝对 checkout,并授予 `fs.read`。 -- Windows ZIP 编码显式调用 `System32\tar.exe`(bsdtar),避免 Git Bash GNU tar。 +- Windows `extension-release`:engineering root 使用 `path.join` / cwd 回退; + ZIP 显式调用 `System32\tar.exe`(bsdtar);`packs.ci` 授予 `fs.read`。 ### Changed -- 扩展包 SemVer **2.8.3**(`ext/VERSION`);与 CLI **v2.8.0** 可独立安装。 +- 扩展包 SemVer **2.8.1**(`ext/VERSION`);与 CLI **v2.8.0** 可独立安装。 - 分支已合并 v2.8.0 依赖锁后的 AI 工作流增量,不再从 2.7.1 基线分叉。 ## v2.8.0 — 2026-11-17 diff --git a/README.md b/README.md index 11a6b66..5f92763 100755 --- a/README.md +++ b/README.md @@ -117,7 +117,7 @@ marqdo view examples/procurement --no-open Agent Skills already support scripts; Marqdo's claim is **one document-native language surface** for authoring, inspecting, executing and reusing functions. This is **not** a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior. -**Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Ext pack 2.8.3](https://github.com/cflmy/marqdo/releases/tag/ext-v2.8.3) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/) +**Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Ext pack 2.8.1](https://github.com/cflmy/marqdo/releases/tag/ext-v2.8.1) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/) --- @@ -128,11 +128,11 @@ Agent Skills already support scripts; Marqdo's claim is **one document-native la 当前 CLI **2.8.0** 新增 `marqdo prove`:知识文件的定理表编译为 Lean 4 并自动判定真假——没有 Lean 工具链也能离线符号执行(诚实降级,绝不冒充证明),有 Lean 时全链路证明并给出反例见证。参见[发布说明](doc/releases/v2.8.0.md)。 -独立拓展包 **2.8.3**(CLI 仍为 2.8.0):`ext/ai` 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / `inspect`)。`marqdo ext add agent` → CDN latest。参见[拓展包说明](doc/releases/ext-2.8.3.md)。 +独立拓展包 **2.8.1**(CLI 仍为 2.8.0):`ext/ai` 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / `inspect`)。`marqdo ext add agent` → CDN latest。参见[拓展包说明](doc/releases/ext-2.8.1.md)。 CLI **2.8.0** adds `marqdo prove`: theorem tables in knowledge files compile to Lean 4 and are judged automatically — offline symbolic execution without a toolchain (honest degradation, never impersonating a proof), full proofs with counterexample witnesses when Lean is available. -Ext pack **2.8.3** (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and `inspect`. +Ext pack **2.8.1** (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and `inspect`. ## 核心优势:可执行知识(Executable Knowledge) diff --git a/doc/releases/ext-2.8.1.md b/doc/releases/ext-2.8.1.md index 3a21632..2f86a4b 100644 --- a/doc/releases/ext-2.8.1.md +++ b/doc/releases/ext-2.8.1.md @@ -2,14 +2,18 @@ ## 1. 一句话 -独立拓展包 **2.8.1**(CLI 仍为 **2.8.0**):`ext/ai` 交付插件侧持久化工作流——显式 `open/next/commit/cancel`、 -有界模型选择、作用域上下文、只读失败恢复,以及 `inspect/list` 与可隔离的 `resume_dir`。 -不改解释器栈挂起语义,也不宣称外部写的 exactly-once。 +独立拓展包 **2.8.1**(CLI 仍为 **2.8.0**):`ext/ai` 交付插件侧持久化工作流——显式 +`open/next/commit/cancel`、有界模型选择、作用域上下文、只读失败恢复,以及 +`inspect/list` 与可隔离的 `resume_dir`。Windows `extension-release` 使用原生 +`path.join` 根路径与 `C:\Windows\System32\tar.exe`(bsdtar)打包。不改解释器栈 +挂起语义,也不宣称外部写的 exactly-once。 -Independent extension pack **2.8.1** (CLI remains **2.8.0**): `ext/ai` ships a plugin-only -durable workflow — explicit `open/next/commit/cancel`, bounded model choice, scoped -context packing, failed-only read-only recovery, plus `inspect/list` and isolatable -`resume_dir`. No interpreter-stack suspension and no exactly-once external-write claim. +Independent extension pack **2.8.1** (CLI remains **2.8.0**): `ext/ai` ships a +plugin-only durable workflow — explicit `open/next/commit/cancel`, bounded model +choice, scoped context packing, failed-only read-only recovery, plus +`inspect/list` and isolatable `resume_dir`. Windows `extension-release` packs +with native `path.join` roots and `C:\Windows\System32\tar.exe` (bsdtar). No +interpreter-stack suspension and no exactly-once external-write claim. ## 2. 亮点(Highlights) @@ -21,6 +25,7 @@ context packing, failed-only read-only recovery, plus `inspect/list` and isolata | 作用域上下文 | Markdown 感知的 file/class/function 摘录;歧义拒绝;不把整库 import 塞进提示 | | 安全并行恢复 | 保留成功兄弟结果;仅重试已分类为只读的失败子任务;写/未知效应不自动派发 | | 可观测性 | `inspect`/`list` 只读进度;测试与调用方可传入 host-relative `resume_dir` | +| Windows CI | engineering root 用 `path.join`;ZIP 用 `System32\tar.exe --format=zip` | 设计契约:[native-agent-flow-v3.md](../design/native-agent-flow-v3.md)。 diff --git a/doc/releases/ext-2.8.2.md b/doc/releases/ext-2.8.2.md deleted file mode 100644 index 36e551c..0000000 --- a/doc/releases/ext-2.8.2.md +++ /dev/null @@ -1,58 +0,0 @@ -# Ext pack v2.8.2 发布说明 · Release Notes(AI native flow) - -## 1. 一句话 - -独立拓展包 **2.8.2**(CLI 仍为 **2.8.0**):在 2.8.1 的 AI 持久化工作流之上,修复 Windows -`extension-release` 打包根路径(`root does not exist`),使双平台 ZIP 可发布。 -`ext-v2.8.1` 标签保留但未形成完整 Release 资产。 - -Independent extension pack **2.8.2** (CLI remains **2.8.0**): AI durable workflows from -2.8.1, plus a Windows `extension-release` checkout-root fix (`root does not exist`) so -both-platform ZIPs can publish. Tag `ext-v2.8.1` remains but did not complete assets. - -## 2. 亮点(Highlights) - -| | | -|---|---| -| 持久步骤机 | `plugins/agent` `workflow`:`open/next/commit/cancel/retry_*`,CheckpointV2,逐步提交边界 | -| 作者面 | `ext/ai/workflow` · `flow` · `context` · `recovery`;`tick` 单步执行,等待输入不阻塞解释器线程 | -| 选择解析 | 精确 / 编号 / 标签 / 短中英句 / JSON 信封;歧义与未知路径失败关闭 | -| 作用域上下文 | Markdown 感知的 file/class/function 摘录;歧义拒绝;不把整库 import 塞进提示 | -| 安全并行恢复 | 保留成功兄弟结果;仅重试已分类为只读的失败子任务;写/未知效应不自动派发 | -| 可观测性 | `inspect`/`list` 只读进度;测试与调用方可传入 host-relative `resume_dir` | - -设计契约:[native-agent-flow-v3.md](../design/native-agent-flow-v3.md)。 - -## 3. 安装(Install) - -```bash -marqdo ext add agent # CDN / Releases → 2.8.2 -# 或:MARQDO_EXT_VERSION=2.8.2 marqdo ext add agent -marqdo ext add llm -``` - -产物:`marqdo-2.8.2-ext.zip` 与双平台 native ZIP(含 agent / llm 等既有原生库)。 - -## 4. 验证(Validation) - -```bash -cargo test -p marqdo_plugin_agent --locked -cargo run --locked -- check ext/ai/flow.mq.md -cargo run --locked -- check ext/ai/context.mq.md -cargo run --locked -- check ext/ai/recovery.mq.md -cargo run --locked -- check ext/ai/workflow.mq.md -cargo run --locked -- run tests/ext/ai-native-flow.mq.md -cargo run --locked -- run tests/ext/ai-native-workflow.mq.md -``` - -CI:`.github/workflows/native-ai-flow.yml` 与 `extension-release.yml`(`ext-v2.8.2`)。 - -## 5. 已知限制(Known limitations) - -- 输入闸门保存的是**步骤边界**,不是任意字节码解释器帧;回复后须显式进入下一 Marqdo 函数。 -- 作用域选择依赖 Markdown 标题约定,不是编译器已解析的 AST 符号表。 -- 调用方提供的 principal/session/source revision 须由已认证宿主证明,不能来自模型文本。 -- 并行复用 `subtask.run_many`;跨进程子任务租约与已在跑外部进程的取消传播仍待专项注入验证。 -- 实时大模型与目标 1B 本地模型评测仍开放;写效应自动重试仍被拒绝,直至 EffectLedger 对账完成。 - -**核心表面 Δ**:无增删——19 个核心构造不变;本包为 Extension / Agent Runtime。 diff --git a/doc/releases/ext-2.8.3.md b/doc/releases/ext-2.8.3.md deleted file mode 100644 index 6fd12f4..0000000 --- a/doc/releases/ext-2.8.3.md +++ /dev/null @@ -1,60 +0,0 @@ -# Ext pack v2.8.3 发布说明 · Release Notes(AI native flow) - -## 1. 一句话 - -独立拓展包 **2.8.3**(CLI 仍为 **2.8.0**):交付 `ext/ai` 插件侧持久化工作流,并修复 -Windows `extension-release` 打包(engineering root + 强制使用 `System32\tar.exe` -bsdtar)。`ext-v2.8.1` / `ext-v2.8.2` 标签保留但未形成完整 Release 资产。 - -Independent extension pack **2.8.3** (CLI remains **2.8.0**): ships `ext/ai` plugin-only -durable workflows and fixes Windows `extension-release` packaging (engineering root -plus explicit `System32\tar.exe` bsdtar). Tags `ext-v2.8.1` / `ext-v2.8.2` remain -without complete release assets. - -## 2. 亮点(Highlights) - -| | | -|---|---| -| 持久步骤机 | `plugins/agent` `workflow`:`open/next/commit/cancel/retry_*`,CheckpointV2,逐步提交边界 | -| 作者面 | `ext/ai/workflow` · `flow` · `context` · `recovery`;`tick` 单步执行,等待输入不阻塞解释器线程 | -| 选择解析 | 精确 / 编号 / 标签 / 短中英句 / JSON 信封;歧义与未知路径失败关闭 | -| 作用域上下文 | Markdown 感知的 file/class/function 摘录;歧义拒绝;不把整库 import 塞进提示 | -| 安全并行恢复 | 保留成功兄弟结果;仅重试已分类为只读的失败子任务;写/未知效应不自动派发 | -| 可观测性 | `inspect`/`list` 只读进度;测试与调用方可传入 host-relative `resume_dir` | -| Windows CI | `path.join` 根路径;`C:\Windows\System32\tar.exe --format=zip` | - -设计契约:[native-agent-flow-v3.md](../design/native-agent-flow-v3.md)。 - -## 3. 安装(Install) - -```bash -marqdo ext add agent # CDN / Releases → 2.8.3 -# 或:MARQDO_EXT_VERSION=2.8.3 marqdo ext add agent -marqdo ext add llm -``` - -产物:`marqdo-2.8.3-ext.zip` 与双平台 native ZIP(含 agent / llm 等既有原生库)。 - -## 4. 验证(Validation) - -```bash -cargo test -p marqdo_plugin_agent --locked -cargo run --locked -- check ext/ai/flow.mq.md -cargo run --locked -- check ext/ai/context.mq.md -cargo run --locked -- check ext/ai/recovery.mq.md -cargo run --locked -- check ext/ai/workflow.mq.md -cargo run --locked -- run tests/ext/ai-native-flow.mq.md -cargo run --locked -- run tests/ext/ai-native-workflow.mq.md -``` - -CI:`.github/workflows/native-ai-flow.yml` 与 `extension-release.yml`(`ext-v2.8.3`)。 - -## 5. 已知限制(Known limitations) - -- 输入闸门保存的是**步骤边界**,不是任意字节码解释器帧;回复后须显式进入下一 Marqdo 函数。 -- 作用域选择依赖 Markdown 标题约定,不是编译器已解析的 AST 符号表。 -- 调用方提供的 principal/session/source revision 须由已认证宿主证明,不能来自模型文本。 -- 并行复用 `subtask.run_many`;跨进程子任务租约与已在跑外部进程的取消传播仍待专项注入验证。 -- 实时大模型与目标 1B 本地模型评测仍开放;写效应自动重试仍被拒绝,直至 EffectLedger 对账完成。 - -**核心表面 Δ**:无增删——19 个核心构造不变;本包为 Extension / Agent Runtime。 diff --git a/ext/VERSION b/ext/VERSION index 9f8d8a9..dbe5900 100755 --- a/ext/VERSION +++ b/ext/VERSION @@ -1 +1 @@ -2.8.3 +2.8.1 From afbb9f191cdd3831a9aff403238a591dc938d47a Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 13:41:29 +0800 Subject: [PATCH 72/74] ci: retrigger EK for ext-v2.8.1 release gate Co-authored-by: Cursor From 24959a0ba83984455c99a087d80ccbbc84a80f34 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 14:40:07 +0800 Subject: [PATCH 73/74] fix: validate Windows extension packs with 7-Zip --- .github/workflows/extension-release.yml | 16 ++++++++++++++-- skills/marqdo-release/packs.mq.md | 10 +++++----- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/.github/workflows/extension-release.yml b/.github/workflows/extension-release.yml index d9240e3..aa2c0ce 100755 --- a/.github/workflows/extension-release.yml +++ b/.github/workflows/extension-release.yml @@ -2,7 +2,15 @@ name: Extension Release on: + workflow_dispatch: + inputs: + version: + description: Extension version to validate + required: true + type: string push: + branches: + - codex/ext-release-validation tags: - "ext-v*" @@ -14,6 +22,7 @@ jobs: runs-on: windows-latest env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_REF_NAME_OVERRIDE: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || format('ext-v{0}', inputs.version || '2.8.1') }} steps: - uses: actions/checkout@v4 with: @@ -35,8 +44,9 @@ jobs: shell: bash run: | set -euo pipefail - ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json + GITHUB_REF_NAME="$GITHUB_REF_NAME_OVERRIDE" ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json - name: Attach source and Windows native packs without replacement + if: startsWith(github.ref, 'refs/tags/ext-v') shell: bash run: | set -euo pipefail @@ -47,6 +57,7 @@ jobs: needs: windows env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_REF_NAME_OVERRIDE: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || format('ext-v{0}', inputs.version || '2.8.1') }} steps: - uses: actions/checkout@v4 with: @@ -63,6 +74,7 @@ jobs: cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering bash scripts/build-web-plugin.sh - name: Build and validate the runner's exact pack bytes - run: target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json + run: GITHUB_REF_NAME="$GITHUB_REF_NAME_OVERRIDE" target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json - name: Attach Linux native pack without replacement + if: startsWith(github.ref, 'refs/tags/ext-v') run: target/release/marqdo call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json diff --git a/skills/marqdo-release/packs.mq.md b/skills/marqdo-release/packs.mq.md index 0a2c67b..a4aff3d 100755 --- a/skills/marqdo-release/packs.mq.md +++ b/skills/marqdo-release/packs.mq.md @@ -15,7 +15,7 @@ import: This leaf builds source and one platform's native extension archives for an authorized version. It does not publish, choose a version, create a tag or edit version files. The extension-release workflow runs the same tasks on Windows and Linux after local.tag pushes ext-vX.Y.Z. Its attach_ci task creates the exact tagged release through the native service boundary and attaches three assets with the existing gh upload tool; assets.publish subsequently verifies those exact bytes before R2 publication. -Build all six maintained native plugins first. The native_dir contract is a directory containing their platform library names, normally target/release. Source discovery and staging use native Marqdo filesystem operations. Only ZIP encoding uses the existing platform tool: Info-ZIP on Linux, the installed bsdtar on Windows. Compiler and format boundaries do not require Python or a generated shell program. +Build all six maintained native plugins first. The native_dir contract is a directory containing their platform library names, normally target/release. Source discovery and staging use native Marqdo filesystem operations. Only ZIP encoding uses the existing platform tool: Info-ZIP on Linux, 7-Zip on Windows. Compiler and format boundaries do not require Python or a generated shell program. ## libraries @@ -74,7 +74,7 @@ Return *[Reject an unsupported native target](result.error(code="packs.platform" Use `stage`, `entry`, `output` and `platform` only after build preflight. Native resolution validates the stage and output paths first; the encoder receives individual arguments and one named staging subtree. It cannot expand a generated shell expression. A failed encoder can leave the selected incomplete archive for inspection; this task never reuses it as successful output or deletes unrelated files. -The Windows runner supplies bsdtar with ZIP format support; Linux supplies Info-ZIP. Format encoding is the only external operation here. Reads, directory creation, copies, hashes and final ZIP validation remain separate explicit native tasks. The caller removes only its owned temporary stage after the child exits. Existing archives require inspection or a different output directory, keeping reruns from silently replacing publication candidates. +The Windows runner supplies 7-Zip with ZIP format support; Linux supplies Info-ZIP. Format encoding is the only external operation here. Reads, directory creation, copies, hashes and final ZIP validation remain separate explicit native tasks. The caller removes only its owned temporary stage after the child exits. Existing archives require inspection or a different output directory, keeping reruns from silently replacing publication candidates. 1. [This output already belongs to an earlier attempt](fs.exists(path=`output`)) Return *[Preserve the existing archive](result.error(code="packs.output_exists", message=`output`, operation="_archive"))*. @@ -96,9 +96,9 @@ We **destination = [Resolve the new archive inside the granted root](fs.resolve( | argument | |---| - | "C:\\Windows\\System32\\tar.exe" | - | "--format=zip" | - | "-cf" | + | "C:\\Program Files\\7-Zip\\7z.exe" | + | a | + | "-tzip" | | `destination` | | `entry` | From a3948dbe0d669b2d597d43fbc9187020987b8ff0 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 14:53:54 +0800 Subject: [PATCH 74/74] ci: remove temporary extension validation trigger --- .github/workflows/extension-release.yml | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/.github/workflows/extension-release.yml b/.github/workflows/extension-release.yml index aa2c0ce..d9240e3 100755 --- a/.github/workflows/extension-release.yml +++ b/.github/workflows/extension-release.yml @@ -2,15 +2,7 @@ name: Extension Release on: - workflow_dispatch: - inputs: - version: - description: Extension version to validate - required: true - type: string push: - branches: - - codex/ext-release-validation tags: - "ext-v*" @@ -22,7 +14,6 @@ jobs: runs-on: windows-latest env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - GITHUB_REF_NAME_OVERRIDE: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || format('ext-v{0}', inputs.version || '2.8.1') }} steps: - uses: actions/checkout@v4 with: @@ -44,9 +35,8 @@ jobs: shell: bash run: | set -euo pipefail - GITHUB_REF_NAME="$GITHUB_REF_NAME_OVERRIDE" ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json + ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json - name: Attach source and Windows native packs without replacement - if: startsWith(github.ref, 'refs/tags/ext-v') shell: bash run: | set -euo pipefail @@ -57,7 +47,6 @@ jobs: needs: windows env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - GITHUB_REF_NAME_OVERRIDE: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || format('ext-v{0}', inputs.version || '2.8.1') }} steps: - uses: actions/checkout@v4 with: @@ -74,7 +63,6 @@ jobs: cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering bash scripts/build-web-plugin.sh - name: Build and validate the runner's exact pack bytes - run: GITHUB_REF_NAME="$GITHUB_REF_NAME_OVERRIDE" target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json + run: target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json - name: Attach Linux native pack without replacement - if: startsWith(github.ref, 'refs/tags/ext-v') run: target/release/marqdo call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json