diff --git a/doc/roadmap/three-problems-plan.md b/doc/roadmap/three-problems-plan.md index 5e0b92d..b243ba7 100644 --- a/doc/roadmap/three-problems-plan.md +++ b/doc/roadmap/three-problems-plan.md @@ -162,3 +162,19 @@ T1.1 core-surface ─是─> T3.1 语言面 + T1.3 守卫 - 验收:`tests/contracts.rs` 12 例(提取 4 + 四边界 4 + check 3 + 正向对照 1)全绿; 全量回归零失败(含 262 gold)。 - **T2.6(契约导出 `get_schema`)**:按计划延后至 Phase 3 与 MLSP `schema` 一并实现。 + +### Phase 3 · MLSP(2026-09-22 完成 T3.1/T3.2 + T2.6;T3.3/T3.4 待做) + +- **T3.1** `marqdo mlsp` 子命令:行分隔 JSON over stdio,请求 `{"id","method","params"}` → + 响应 `{"id","ok","result"|"error"}`(永不 panic,错误也是结构化 JSON)。 +- **T3.2** 五个 handler 全部实现(`src/mlsp.rs`): + `locate`(构造卡片 / 符号定位 + 契约)、`syntax`(关键字/别名 → 卡片;语法唯一事实来源 = + `parse::CORE_CONSTRUCTS`,MLSP 只加检索别名不定义语法)、`validate`(parse + 契约 check → 结构化诊断数组)、 + `repair_targets`(有界修复靶点:`strategy=anchored-local`、`on_violation=abstain`——越界必拒护栏先行)、 + `schema`(**T2.6 完成**:单元名 → 形参/返回/字段契约 + 升参清单 + 锚点)。 +- 验收:`tests/mlsp.rs` 7 例全绿(语法问答/未知查询/符号定位/漂移校验/schema 导出/有界修复/结构化错误); + stdio 冒烟通过;全量回归零失败。 +- **T3.3(修复循环护栏 · golden 20 例 ≥80%)**:护栏策略字段已就位(anchored-local / abstain / + max_attempts=2);golden 实验需要模型调用,属验证实验性质,待做。 +- **T3.4(AI Skill 换骨:背语法 → 查 MLSP)**:待做——`.cursor/skills/marqdo*` 三件套改为 + 「写代码前先 `mlsp syntax/locate`、提交前 `mlsp validate`」的查询式工作流。 diff --git a/src/lib.rs b/src/lib.rs index cd4c92e..f097991 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -29,6 +29,7 @@ pub mod interp; pub mod lex; pub mod linalg_ops; pub mod load; +pub mod mlsp; pub mod parse; pub mod value; #[cfg(feature = "net-host")] diff --git a/src/main.rs b/src/main.rs index 93153f9..f4fd789 100644 --- a/src/main.rs +++ b/src/main.rs @@ -80,6 +80,8 @@ enum Commands { #[arg(long)] json: bool, }, + /// MLSP for AI: line-delimited JSON on stdio (locate / syntax / validate / repair_targets / schema) + Mlsp, /// Browse `.mq.md` structure + execution (live server or static output) View { #[command(subcommand)] @@ -281,6 +283,21 @@ fn try_main(cli: Cli) -> Result { } Ok(errors.min(1)) } + Commands::Mlsp => { + use std::io::{BufRead, Write}; + let stdin = std::io::stdin(); + let stdout = std::io::stdout(); + let mut out = stdout.lock(); + for line in stdin.lock().lines() { + let line = line?; + if line.trim().is_empty() { + continue; + } + writeln!(out, "{}", marqdo::mlsp::handle_line(&line))?; + out.flush()?; + } + Ok(0) + } Commands::View { action, path, diff --git a/src/mlsp.rs b/src/mlsp.rs new file mode 100644 index 0000000..23d17e8 --- /dev/null +++ b/src/mlsp.rs @@ -0,0 +1,277 @@ +//! Marqdo Language Server for AI(MLSP)—— AI 的可查询工具面(T3.1/T3.2,T2.6 并入 `schema`)。 +//! +//! 目标([three-problems.md](../../doc/roadmap/three-problems.md) §3):**AI 不必背 Marqdo +//! 语法细节**——把「记语法」换成「查工具」。语法唯一事实来源是 `parse::CORE_CONSTRUCTS` +//! (与 `doc/design/core-surface.md` 由 CI 守卫同步);本模块只加**检索别名**,不定义语法。 +//! +//! 行分隔 JSON 协议:每行一个请求 `{"id":…,"method":…,"params":{…}}`, +//! 每行一个响应 `{"id":…,"ok":true,"result":{…}}` / `{"id":…,"ok":false,"error":{…}}`。 +//! +//! | method | 作用 | +//! |--------|------| +//! | `locate` | 语法/符号定位:构造卡片,或定义位置 + 契约 | +//! | `syntax` | 语法问答:关键字/别名 → 构造卡片 | +//! | `validate` | 程序校验:结构化诊断数组(parse + 契约 check) | +//! | `repair_targets` | 修复靶点:错误 → **有界**修复目标(越界必拒,护栏) | +//! | `schema` | 契约查询(T2.6):单元名 → 形参/返回/字段契约 | + +use std::path::{Path, PathBuf}; + +use serde_json::{json, Value}; + +use crate::ast::{Function, Module}; +use crate::check::check_module; +use crate::contract::{Contract, Ty}; +use crate::diagnostics::Diagnostic; +use crate::load; +use crate::parse::CORE_CONSTRUCTS; + +/// 行分隔 JSON:一行请求 → 一行响应(永不 panic;错误也是结构化 JSON)。 +pub fn handle_line(line: &str) -> String { + let trimmed = line.trim(); + let id = match serde_json::from_str::(trimmed) { + Ok(req) => req.get("id").cloned().unwrap_or(Value::Null), + Err(e) => { + return json!({ + "id": null, + "ok": false, + "error": {"code": "mlsp.bad_request", "message": format!("请求不是合法 JSON: {e}")} + }) + .to_string(); + } + }; + let req: Value = serde_json::from_str(trimmed).expect("already parsed"); + match dispatch(&req) { + Ok(result) => json!({"id": id, "ok": true, "result": result}).to_string(), + Err(error) => json!({"id": id, "ok": false, "error": error}).to_string(), + } +} + +fn dispatch(req: &Value) -> Result { + let params = req.get("params").cloned().unwrap_or(json!({})); + match req.get("method").and_then(|m| m.as_str()) { + Some("locate") => locate(¶ms), + Some("syntax") => syntax(¶ms), + Some("validate") => validate(¶ms), + Some("repair_targets") => repair_targets(¶ms), + Some("schema") => schema(¶ms), + other => Err(err( + "mlsp.unknown_method", + format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / schema"), + )), + } +} + +fn err(code: &str, message: impl Into) -> Value { + json!({"code": code, "message": message.into()}) +} + +// ---------- 构造卡片(语法唯一事实来源 = CORE_CONSTRUCTS) ---------- + +/// 检索别名(中/英关键字)——只做匹配,不定义语法。 +const ALIASES: &[(&str, &[&str])] = &[ + ("narrative", &["叙述", "文字", "说明", "注释", "narrative", "prose"]), + ("blank", &["空行", "blank"]), + ("heading-unit", &["标题", "单元", "函数", "对象", "heading", "定义"]), + ("call-line", &["调用", "call"]), + ("branch-list", &["分支", "条件", "判断", "branch", "if"]), + ("loop-list", &["循环", "遍历", "loop", "for", "while"]), + ("param", &["参数", "形参", "param"]), + ("table", &["表", "表格", "table", "集合", "数据"]), + ("fence", &["代码块", "围栏", "fence", "公式", "code"]), + ("hr", &["分隔线", "水平线", "hr"]), + ("writeback", &["回写", "输出块", "writeback"]), + ("ident", &["变量", "标识符", "ident", "名字"]), + ("bold-code", &["粗体", "赋值", "语句", "bold", "执行"]), + ("italic-return", &["返回", "return", "斜体"]), + ("empty-return", &["空返回", "none", "结束", "副作用"]), + ("link-index", &["取元", "索引", "index", "键", "行"]), + ("bracket-call", &["修饰", "括号", "bracket", "开关参数"]), + ("footnote-index", &["脚注", "footnote", "取列", "列"]), + ("soft-emphasis", &["强调", "emphasis", "软强调"]), +]; + +fn card(id: &str) -> Value { + let form = CORE_CONSTRUCTS + .iter() + .find(|(cid, _)| *cid == id) + .map(|(_, f)| *f) + .unwrap_or("?"); + json!({ + "id": id, + "form": form, + "manual": "doc/design/core-surface.md", + }) +} + +fn match_constructs(query: &str) -> Vec { + let q = query.trim().to_lowercase(); + if q.is_empty() { + return ALIASES.iter().map(|(id, _)| card(id)).collect(); + } + ALIASES + .iter() + .filter(|(_, keys)| { + keys.iter() + .any(|k| k.to_lowercase().contains(&q) || q.contains(&k.to_lowercase())) + }) + .map(|(id, _)| card(id)) + .collect() +} + +fn syntax(params: &Value) -> Result { + let query = params.get("query").and_then(|q| q.as_str()).unwrap_or(""); + let cards = match_constructs(query); + if cards.is_empty() { + return Err(err( + "mlsp.no_match", + format!("没有匹配「{query}」的语法构造;换关键字(如 返回/表/调用)或省略 query 列出全部"), + )); + } + Ok(json!({"cards": cards})) +} + +fn locate(params: &Value) -> Result { + if params.get("path").is_some() || params.get("source").is_some() { + let (module, path) = module_from_params(params)?; + let symbol = params + .get("symbol") + .and_then(|s| s.as_str()) + .ok_or_else(|| err("mlsp.bad_request", "locate 定位符号需要 params.symbol"))?; + let fun = find_fn(&module, symbol) + .ok_or_else(|| err("mlsp.unknown_unit", format!("没有名为 `{symbol}` 的单元")))?; + return Ok(json!({ + "unit": fun.name, + "level": fun.level, + "span": span_json(path.as_deref(), fun.span), + "params": fun.params.iter().map(|p| p.name.clone()).collect::>(), + "contract": fun.contract.as_ref().map(|c| contract_json(c, path.as_deref())), + "manual": "doc/design/core-surface.md", + })); + } + Ok(json!({"cards": match_constructs( + params.get("query").and_then(|q| q.as_str()).unwrap_or("") + )})) +} + +fn validate(params: &Value) -> Result { + let (module, path) = module_from_params(params)?; + let mut diags = check_module(&module, path.as_deref()); + diags.sort_by_key(|d| (d.span.line, d.span.col)); + let jsons: Vec = diags.iter().map(|d| d.to_json()).collect(); + let ok = !diags + .iter() + .any(|d| matches!(d.severity, crate::diagnostics::Severity::Error)); + Ok(json!({"ok": ok, "diagnostics": jsons})) +} + +/// 修复靶点(T3.3 护栏):锚点局部修复,**越界必拒**(禁止整文件重写/无关重构)。 +fn repair_targets(params: &Value) -> Result { + let code = params.get("code").and_then(|c| c.as_str()).unwrap_or(""); + let anchor = params.get("doc_anchor").and_then(|a| a.as_str()); + let suggestion = params.get("suggestion").and_then(|s| s.as_str()); + if code.is_empty() { + return Err(err("mlsp.bad_request", "repair_targets 需要 params.code")); + } + Ok(json!({ + "targets": [{ + "code": code, + "doc_anchor": anchor, + "span": params.get("span").cloned().unwrap_or(Value::Null), + }], + "repair": { + "strategy": "anchored-local", + "bounded": true, + "max_attempts": 2, + "scope": "doc_anchor 所锚定的契约表/语句行", + "suggestion": suggestion, + "on_violation": "abstain", + "note": "只许改动锚定范围内的行;越界改动必须拒绝并报 abstain" + } + })) +} + +/// 契约查询(T2.6):单元名 → 形参/返回/字段契约。 +fn schema(params: &Value) -> Result { + let (module, path) = module_from_params(params)?; + let unit = params + .get("unit") + .and_then(|u| u.as_str()) + .ok_or_else(|| err("mlsp.bad_request", "schema 需要 params.unit"))?; + let fun = find_fn(&module, unit) + .ok_or_else(|| err("mlsp.unknown_unit", format!("没有名为 `{unit}` 的单元")))?; + let mut vars = serde_json::Map::new(); + for (name, c) in &fun.var_contracts { + vars.insert(name.clone(), contract_json(c, path.as_deref())); + } + Ok(json!({ + "unit": fun.name, + "contract": fun.contract.as_ref().map(|c| contract_json(c, path.as_deref())), + "vars": Value::Object(vars), + "params_inferred": fun.params.iter().map(|p| json!({ + "name": p.name, "inferred": p.inferred + })).collect::>(), + })) +} + +// ---------- 公共小工具 ---------- + +fn module_from_params(params: &Value) -> Result<(Module, Option), Value> { + if let Some(src) = params.get("source").and_then(|s| s.as_str()) { + let module = load::load_module_from_source(src) + .map_err(|e| diagnostic_err("mlsp.parse_error", &e))?; + return Ok((module, None)); + } + let path = params + .get("path") + .and_then(|p| p.as_str()) + .ok_or_else(|| err("mlsp.bad_request", "需要 params.path 或 params.source"))?; + let path = PathBuf::from(path); + let module = load::load_module(&path).map_err(|e| diagnostic_err("mlsp.parse_error", &e))?; + Ok((module, Some(path))) +} + +/// 错误链里有结构化诊断就原样透出(AI/MLSP 面不许拍平)。 +fn diagnostic_err(code: &str, e: &anyhow::Error) -> Value { + match Diagnostic::find(e) { + Some(d) => d.to_json(), + None => err(code, format!("{e:#}")), + } +} + +fn find_fn<'a>(module: &'a Module, name: &str) -> Option<&'a Function> { + fn walk<'a>(funs: &'a [Function], name: &str) -> Option<&'a Function> { + funs.iter().find(|f| f.name == name).or_else(|| { + funs.iter() + .find_map(|f| walk(&f.children, name)) + }) + } + walk(&module.functions, name) +} + +fn span_json(path: Option<&Path>, span: crate::diagnostics::Span) -> Value { + json!({ + "file": path.map(|p| p.display().to_string()), + "line": span.line, + "col": span.col, + }) +} + +fn ty_json(ty: &Ty) -> Value { + json!(ty.name()) +} + +fn contract_json(c: &Contract, path: Option<&Path>) -> Value { + json!({ + "params": c.params.iter().map(|p| json!({ + "name": p.name, "type": ty_json(&p.ty), "desc": p.desc + })).collect::>(), + "returns": c.returns.as_ref().map(|r| json!({ + "type": ty_json(&r.ty), "desc": r.desc + })), + "fields": c.fields.iter().map(|f| json!({ + "name": f.name, "type": ty_json(&f.ty), "nullable": f.nullable, "desc": f.desc + })).collect::>(), + "doc_anchor": c.anchor(path), + }) +} diff --git a/tests/mlsp.rs b/tests/mlsp.rs new file mode 100644 index 0000000..2536da8 --- /dev/null +++ b/tests/mlsp.rs @@ -0,0 +1,103 @@ +//! MLSP for AI(T3.1/T3.2 + T2.6):`locate` / `syntax` / `validate` / `repair_targets` / `schema`。 +//! +//! 验收对照 `doc/roadmap/three-problems-plan.md` Phase 3: +//! AI 不必背语法细节(syntax/locate 可查)、schema 可导出、修复靶点有界(越界必拒)。 + +use marqdo::mlsp::handle_line; + +fn call(req: &str) -> serde_json::Value { + serde_json::from_str(&handle_line(req)).expect("MLSP 响应必须是合法 JSON") +} + +#[test] +fn syntax_query_returns_construct_cards() { + let resp = call(r#"{"id":1,"method":"syntax","params":{"query":"返回"}}"#); + assert_eq!(resp["ok"], true, "{resp}"); + let ids: Vec<&str> = resp["result"]["cards"] + .as_array() + .unwrap() + .iter() + .map(|c| c["id"].as_str().unwrap()) + .collect(); + assert!(ids.contains(&"italic-return"), "「返回」应命中斜体返回卡片: {resp}"); + assert!(resp["result"]["cards"][0]["manual"] + .as_str() + .unwrap() + .contains("core-surface")); +} + +#[test] +fn syntax_unknown_query_structured_error() { + let resp = call(r#"{"id":2,"method":"syntax","params":{"query":"量子纠缠语法"}}"#); + assert_eq!(resp["ok"], false); + assert_eq!(resp["error"]["code"], "mlsp.no_match"); +} + +#[test] +fn locate_symbol_returns_span_and_contract() { + let src = "# main\n\n## 加一\n\n对于输入变量`n`,执行加一。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| n | number | 输入值 |\n\n*n+1*\n"; + let req = serde_json::json!({"id":3,"method":"locate","params":{"source": src, "symbol": "加一"}}); + let resp = call(&req.to_string()); + assert_eq!(resp["ok"], true, "{resp}"); + assert_eq!(resp["result"]["unit"], "加一"); + assert_eq!(resp["result"]["contract"]["params"][0]["type"], "number"); + assert!(resp["result"]["span"]["line"].as_u64().unwrap() >= 1); +} + +#[test] +fn validate_reports_contract_drift() { + let src = "# main\n\n## 加一\n\n对于输入变量`n`,执行加一。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| nn | number | 输入值 |\n\n*n+1*\n"; + let req = serde_json::json!({"id":4,"method":"validate","params":{"source": src}}); + let resp = call(&req.to_string()); + assert_eq!(resp["ok"], true, "{resp}"); + assert_eq!(resp["result"]["ok"], false, "漂移必须让 validate 不通过: {resp}"); + let codes: Vec<&str> = resp["result"]["diagnostics"] + .as_array() + .unwrap() + .iter() + .map(|d| d["code"].as_str().unwrap()) + .collect(); + assert!(codes.contains(&"contract.param_drift"), "{resp}"); +} + +#[test] +fn schema_exports_progressive_contract() { + let req = serde_json::json!({ + "id": 5, + "method": "schema", + "params": {"path": concat!(env!("CARGO_MANIFEST_DIR"), "/tests/contracts/ok_contract.mq.md"), "unit": "加一"} + }); + let resp = call(&req.to_string()); + assert_eq!(resp["ok"], true, "{resp}"); + assert_eq!(resp["result"]["contract"]["params"][0]["name"], "n"); + assert_eq!(resp["result"]["contract"]["params"][0]["type"], "number"); + assert_eq!(resp["result"]["contract"]["returns"]["type"], "number"); + assert!(resp["result"]["contract"]["doc_anchor"] + .as_str() + .unwrap() + .contains("#L")); +} + +#[test] +fn repair_targets_are_bounded() { + let resp = call( + r#"{"id":6,"method":"repair_targets","params":{"code":"contract.arg_mismatch","doc_anchor":"a.mq.md#L9-L15","suggestion":"把实参改为 number"}}"#, + ); + assert_eq!(resp["ok"], true, "{resp}"); + let repair = &resp["result"]["repair"]; + assert_eq!(repair["strategy"], "anchored-local"); + assert_eq!(repair["bounded"], true); + assert_eq!(repair["on_violation"], "abstain"); + assert_eq!(resp["result"]["targets"][0]["doc_anchor"], "a.mq.md#L9-L15"); +} + +#[test] +fn unknown_method_and_bad_json_are_structured() { + let resp = call(r#"{"id":7,"method":"divine","params":{}}"#); + assert_eq!(resp["ok"], false); + assert_eq!(resp["error"]["code"], "mlsp.unknown_method"); + + let resp = call("not json at all"); + assert_eq!(resp["ok"], false); + assert_eq!(resp["error"]["code"], "mlsp.bad_request"); +}