Files
marqdo/plugins/linalg/src/lib.rs
cflmy fb135ae2f8 refactor(plugins): 抽出 marqdo-plugin-sdk — ABI 前言从 5 份变 1 份
新增工作区成员 crates/marqdo-plugin-sdk:ABI 类型、HOST_* 静态回调、
host_strdup/set_out/set_err/parse_args/reply/host_query_json(_with)/
take_host_string/init_plugin,以及生成四个 #[no_mangle] 导出的
marqdo_plugin! 宏。ABI 常量、符号名、结构体布局一律未变。

5 个插件改为依赖 SDK + 一行宏调用:
  agent  1237 → 929  (-308)
  quantum 1045 → 835 (-210)
  linalg  688 → 524  (-164)
  llm     405 → 278  (-127)
  demo    170 → 73   (-97)
  SDK 新增 232 行 → 净减约 674 行

迁移中发现并修正三次"编译通过但语义已变":
1. 注册项抽取漏 11 项 —— 正则 [a-z_0-9]+ 匹配不到 mcp_server::agent_mcp_serve、
   sandbox::* 这类路径限定函数名;改为允许 :: 后重抽。
   已用脚本逐项比对 (名称, 参数串, 函数) 三元组:agent 63/63、quantum 41/41、
   linalg 31/31、llm 2/2、demo 2/2,全部 0 差异。
2. mcp_client 被误判死模块(删 327 行后才发现 agent_mcp_client 正注册它)→ 恢复。
3. 量子插件两个"未使用"函数删除时连带吃掉 density_from_amps/flat_to_nested
   → 恢复原文件并改为 #[allow(dead_code)]。

验证:cargo build --release(含 5 个插件)零警告;
cargo test --release 609 passed / 0 failed;
量子金样实跑 p00-ok / p11-ok / ping-ok。

文档:doc/design/change-plugin-sdk.md
2026-10-22 15:49:13 +08:00

525 lines
16 KiB
Rust

//! Marqdo linalg plugin (C ABI v2): formula-first matrix expressions.
mod complex;
mod dense;
mod draw;
mod factor;
mod matexpr;
mod metrics;
use std::os::raw::{c_char, c_int};
use serde_json::{json, Value};
use marqdo_plugin_sdk::*;
use matexpr::{Dim, Expr};
macro_rules! la_ffi {
($name:ident, $body:expr) => {
unsafe extern "C" fn $name(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
let args = match parse_args(args_json) {
Ok(v) => v,
Err(e) => {
set_err(err_msg, &format!("{}: {e}", stringify!($name)));
return 1;
}
};
let r: Result<Value, String> = (|| $body(&args))();
reply(
out_json,
err_msg,
r.map_err(|e| format!("{}: {e}", stringify!($name))),
)
}
};
}
fn record_plot(svg: &str, path: Option<&str>) -> Result<(), String> {
let mut args = json!({ "svg": svg });
if let Some(p) = path {
if !p.is_empty() {
args.as_object_mut()
.unwrap()
.insert("path".into(), json!(p));
}
}
host_query_json_with("record_plot", &args)?;
Ok(())
}
fn arg_dim(v: &Value, key: &str) -> Result<Dim, String> {
Dim::from_json(v.get(key).ok_or_else(|| format!("missing `{key}`"))?)
}
fn arg_expr_opt(v: &Value, keys: &[&str]) -> Result<Expr, String> {
for k in keys {
if let Some(e) = v.get(*k) {
if !e.is_null() {
return coerce_expr(e);
}
}
}
Err(format!("missing one of {:?}", keys))
}
fn coerce_expr(v: &Value) -> Result<Expr, String> {
if let Ok(e) = Expr::from_value(v) {
return Ok(e);
}
let data = dense::from_value(v)?;
Ok(Expr::Dense { data })
}
fn wrap(expr: Expr) -> Result<Value, String> {
expr.to_value()
}
la_ffi!(linalg_ping, |_args: &Value| {
Ok(json!({
"ok": true,
"name": "linalg",
"abi": ABI_VERSION,
"features": [
"matexpr",
"simplify",
"dense",
"solve",
"block",
"kron",
"factorize",
"draw",
"lstsq",
"norm",
"cond",
"rank",
"complex",
"declare",
],
}))
});
la_ffi!(linalg_symbol, |args: &Value| {
let name = args
.get("name")
.or_else(|| args.get("名"))
.and_then(|x| x.as_str())
.ok_or_else(|| "missing `name`".to_string())?;
let rows = arg_dim(args, "rows").or_else(|_| arg_dim(args, "行"))?;
let cols = arg_dim(args, "cols").or_else(|_| arg_dim(args, "列"))?;
wrap(matexpr::symbol(name, rows, cols))
});
la_ffi!(linalg_eye, |args: &Value| {
let n = arg_dim(args, "n")
.or_else(|_| arg_dim(args, "阶"))
.or_else(|_| arg_dim(args, "rows"))?;
wrap(matexpr::eye(n))
});
la_ffi!(linalg_zeros, |args: &Value| {
let rows = arg_dim(args, "rows").or_else(|_| arg_dim(args, "行"))?;
let cols = arg_dim(args, "cols").or_else(|_| arg_dim(args, "列"))?;
wrap(matexpr::zeros(rows, cols))
});
la_ffi!(linalg_from_list, |args: &Value| {
let data = args
.get("data")
.or_else(|| args.get("数据"))
.ok_or_else(|| "missing `data`".to_string())?;
if complex::data_has_complex(data) {
return complex::to_dense_value(&complex::from_data(data)?);
}
let m = dense::from_value(data)?;
wrap(matexpr::from_list(m)?)
});
la_ffi!(linalg_declare, |args: &Value| {
let table = args
.get("table")
.or_else(|| args.get("rows"))
.or_else(|| args.get("表"))
.or_else(|| args.get("行"))
.ok_or_else(|| "missing `table` (list of {name,rows,cols})".to_string())?;
let rows = table
.as_array()
.ok_or_else(|| "`table` must be a list of row maps".to_string())?;
let tag = args
.get("type_tag")
.or_else(|| args.get("类型标签"))
.and_then(|x| x.as_str())
.unwrap_or("matrix");
let mut out = serde_json::Map::new();
out.insert("_type".into(), json!("matrix_env"));
for (i, row) in rows.iter().enumerate() {
let obj = row
.as_object()
.ok_or_else(|| format!("declare row {i} must be a map"))?;
let name = obj
.get("name")
.or_else(|| obj.get("名"))
.and_then(|x| x.as_str())
.ok_or_else(|| format!("declare row {i} missing name"))?
.to_string();
let r = Dim::from_json(
obj.get("rows")
.or_else(|| obj.get("行"))
.ok_or_else(|| format!("declare `{name}` missing rows"))?,
)?;
let c = Dim::from_json(
obj.get("cols")
.or_else(|| obj.get("列"))
.ok_or_else(|| format!("declare `{name}` missing cols"))?,
)?;
let expr = matexpr::symbol(&name, r, c);
let mut v = expr.to_value()?;
if let Some(m) = v.as_object_mut() {
m.insert("_type".into(), json!(tag));
}
out.insert(name, v);
}
Ok(Value::Object(out))
});
la_ffi!(linalg_mul, |args: &Value| {
let a = arg_expr_opt(args, &["a", "左"])?;
let b = arg_expr_opt(args, &["b", "右"])?;
wrap(matexpr::mul(a, b)?)
});
la_ffi!(linalg_add, |args: &Value| {
let a = arg_expr_opt(args, &["a", "左"])?;
let b = arg_expr_opt(args, &["b", "右"])?;
wrap(matexpr::add(a, b)?)
});
la_ffi!(linalg_sub, |args: &Value| {
let a = arg_expr_opt(args, &["a", "左"])?;
let b = arg_expr_opt(args, &["b", "右"])?;
wrap(matexpr::sub(a, b)?)
});
la_ffi!(linalg_transpose, |args: &Value| {
let e = arg_expr_opt(args, &["expr", "a", "式"])?;
wrap(matexpr::transpose(e)?)
});
la_ffi!(linalg_inv, |args: &Value| {
let e = arg_expr_opt(args, &["expr", "a", "式"])?;
wrap(matexpr::inv(e)?)
});
la_ffi!(linalg_simplify, |args: &Value| {
let e = arg_expr_opt(args, &["expr", "a", "式"])?;
wrap(matexpr::simplify(e)?)
});
fn display_expr(args: &Value, e: matexpr::Expr) -> Result<matexpr::Expr, String> {
let raw = args
.get("raw")
.or_else(|| args.get("原始"))
.and_then(|v| match v {
Value::Bool(b) => Some(*b),
Value::String(s) => Some(matches!(s.to_ascii_lowercase().as_str(), "true" | "1" | "yes")),
_ => v.as_bool(),
})
.unwrap_or(false);
if raw {
Ok(e)
} else {
matexpr::simplify(e)
}
}
la_ffi!(linalg_ascii, |args: &Value| {
let e = arg_expr_opt(args, &["expr", "a", "式"])?;
let e = display_expr(args, e)?;
Ok(json!(e.ascii()))
});
la_ffi!(linalg_latex, |args: &Value| {
let e = arg_expr_opt(args, &["expr", "a", "式"])?;
let e = display_expr(args, e)?;
Ok(json!(e.latex()))
});
la_ffi!(linalg_shape, |args: &Value| {
let e = arg_expr_opt(args, &["expr", "a", "式"])?;
let (r, c) = e.shape()?;
Ok(json!([r.to_json(), c.to_json()]))
});
la_ffi!(linalg_show, |args: &Value| {
let e = arg_expr_opt(args, &["expr", "a", "式"])?;
let e = display_expr(args, e)?;
let latex = e.latex();
let ascii = e.ascii();
let path = args
.get("path")
.or_else(|| args.get("路径"))
.and_then(|x| x.as_str())
.filter(|s| !s.is_empty());
// Minimal SVG so view/plot channel can embed the formula text.
let escaped = latex
.replace('&', "&amp;")
.replace('<', "&lt;")
.replace('>', "&gt;");
let svg = format!(
"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"480\" height=\"64\" data-linalg=\"formula\">\
<text x=\"12\" y=\"40\" font-size=\"18\" font-family=\"serif\">{escaped}</text></svg>"
);
let _ = record_plot(&svg, path);
let mut out = e.to_value()?;
if let Some(obj) = out.as_object_mut() {
obj.insert("shown".into(), json!(true));
obj.insert("ascii".into(), json!(ascii));
obj.insert("latex".into(), json!(latex));
}
Ok(out)
});
la_ffi!(linalg_from_formula, |args: &Value| {
let f = args
.get("formula")
.or_else(|| args.get("公式"))
.or_else(|| args.get("expr"))
.or_else(|| args.get("式"))
.ok_or_else(|| "missing `formula`".to_string())?;
wrap(coerce_expr(f)?)
});
la_ffi!(linalg_explicit, |args: &Value| {
let e = arg_expr_opt(args, &["expr", "a", "式"]).or_else(|_| {
let f = args
.get("formula")
.or_else(|| args.get("公式"))
.ok_or_else(|| "missing `expr`".to_string())?;
coerce_expr(f)
})?;
let e = display_expr(args, e)?;
let m = dense::explicit(&e)?;
dense::to_dense_value(&m)
});
la_ffi!(linalg_det, |args: &Value| {
let m = dense_arg(args, &["expr", "a", "matrix", "式", "矩阵"])?;
Ok(json!(dense::det(&m)?))
});
la_ffi!(linalg_trace, |args: &Value| {
let m = dense_arg(args, &["expr", "a", "matrix", "式", "矩阵"])?;
Ok(json!(dense::trace(&m)?))
});
la_ffi!(linalg_solve, |args: &Value| {
let b = dense_arg(args, &["b", "B", "rhs", "右"])?;
if let Some(f) = args
.get("factor")
.or_else(|| args.get("分解"))
.filter(|v| !v.is_null())
{
let x = factor::solve_lu_factor(f, &b)?;
return dense::to_dense_value(&x).map(|xv| {
json!({
"_type": "linalg_solve",
"method": "lu",
"x": xv,
})
});
}
let a = dense_arg(args, &["a", "A", "matrix", "矩阵", "左"])?;
dense::solve_result(&a, &b)
});
la_ffi!(linalg_matmul, |args: &Value| {
let a = dense_arg(args, &["a", "左"])?;
let b = dense_arg(args, &["b", "右"])?;
dense::to_dense_value(&dense::matmul(&a, &b)?)
});
la_ffi!(linalg_kron, |args: &Value| {
let a = arg_expr_opt(args, &["a", "左"])?;
let b = arg_expr_opt(args, &["b", "右"])?;
wrap(matexpr::kron(a, b)?)
});
la_ffi!(linalg_block, |args: &Value| {
let blocks_v = args
.get("blocks")
.or_else(|| args.get("块"))
.ok_or_else(|| "missing `blocks`".to_string())?;
let grid = blocks_v
.as_array()
.ok_or_else(|| "`blocks` must be a list of rows".to_string())?;
let mut blocks = Vec::new();
for row in grid {
let cells = row
.as_array()
.ok_or_else(|| "each block row must be a list".to_string())?;
let mut r = Vec::new();
for c in cells {
r.push(coerce_expr(c)?);
}
blocks.push(r);
}
wrap(matexpr::block(blocks)?)
});
la_ffi!(linalg_collapse, |args: &Value| {
let e = arg_expr_opt(args, &["expr", "a", "式"])?;
wrap(matexpr::collapse(e)?)
});
la_ffi!(linalg_factorize, |args: &Value| {
let m = dense_arg(args, &["matrix", "expr", "a", "矩阵", "式"])?;
let kind = args
.get("kind")
.or_else(|| args.get("类型"))
.and_then(|x| x.as_str())
.unwrap_or("lu");
factor::factorize(&m, kind)
});
la_ffi!(linalg_draw, |args: &Value| {
let factor_v = args
.get("factor")
.or_else(|| args.get("分解"))
.or_else(|| args.get("expr"))
.or_else(|| args.get("matrix"))
.or_else(|| args.get("式"))
.or_else(|| args.get("矩阵"))
.ok_or_else(|| "missing `factor`".to_string())?;
let kind = args
.get("kind")
.or_else(|| args.get("类型"))
.and_then(|x| x.as_str());
let path = args
.get("path")
.or_else(|| args.get("路径"))
.and_then(|x| x.as_str())
.filter(|s| !s.is_empty());
let theme = args
.get("theme")
.or_else(|| args.get("主题"))
.and_then(|x| x.as_str())
.map(draw::ThemeName::parse)
.transpose()?
.unwrap_or(draw::ThemeName::Light);
let svg = draw::draw_factor(factor_v, kind, path, theme)?;
let _ = record_plot(&svg, path);
Ok(json!({
"_type": "linalg_svg",
"kind": kind
.or_else(|| factor_v.get("kind").and_then(|k| k.as_str()))
.unwrap_or("structure"),
"theme": theme.as_str(),
"svg": svg,
}))
});
la_ffi!(linalg_lstsq, |args: &Value| {
let a = dense_arg(args, &["a", "A", "matrix", "矩阵", "左"])?;
let b = dense_arg(args, &["b", "B", "rhs", "右"])?;
metrics::lstsq(&a, &b)
});
la_ffi!(linalg_norm, |args: &Value| {
let ord = args
.get("ord")
.or_else(|| args.get("order"))
.or_else(|| args.get("范数"))
.and_then(|x| x.as_str())
.unwrap_or("fro");
if let Some(v) = args
.get("expr")
.or_else(|| args.get("a"))
.or_else(|| args.get("matrix"))
.or_else(|| args.get("式"))
.or_else(|| args.get("矩阵"))
{
if v.get("dtype").and_then(|d| d.as_str()) == Some("complex")
|| complex::from_value(v).is_ok()
{
if !matches!(ord, "fro" | "frobenius" | "f" | "") {
return Err("complex norm only supports fro for now".into());
}
let cm = complex::from_value(v).or_else(|_| {
v.get("data")
.ok_or_else(|| "missing complex data".to_string())
.and_then(complex::from_data)
})?;
return Ok(json!(complex::frobenius_norm(&cm)?));
}
}
let m = dense_arg(args, &["expr", "a", "matrix", "式", "矩阵"])?;
Ok(json!(metrics::norm(&m, ord)?))
});
la_ffi!(linalg_cond, |args: &Value| {
let m = dense_arg(args, &["expr", "a", "matrix", "式", "矩阵"])?;
metrics::cond(&m)
});
la_ffi!(linalg_rank, |args: &Value| {
let m = dense_arg(args, &["expr", "a", "matrix", "式", "矩阵"])?;
Ok(json!(metrics::rank(&m)?))
});
fn dense_arg(args: &Value, keys: &[&str]) -> Result<dense::Mat, String> {
for k in keys {
if let Some(v) = args.get(*k) {
if v.is_null() {
continue;
}
if v.get("dtype").and_then(|d| d.as_str()) == Some("complex") {
return Err("real dense op got dtype=complex (use norm fro on complex; factorize/solve stay real)".into());
}
if let Ok(e) = Expr::from_value(v) {
return dense::explicit(&e);
}
return dense::from_value(v);
}
}
Err(format!("missing dense matrix among {:?}", keys))
}
marqdo_plugin!(marqdo_plugin_sdk::ABI_VERSION, [
("linalg_ping", "", linalg_ping),
("linalg_symbol", "name,rows,cols", linalg_symbol),
("linalg_eye", "n", linalg_eye),
("linalg_zeros", "rows,cols", linalg_zeros),
("linalg_from_list", "data", linalg_from_list),
("linalg_declare", "table,type_tag", linalg_declare),
("linalg_from_formula", "formula", linalg_from_formula),
("linalg_mul", "a,b", linalg_mul),
("linalg_add", "a,b", linalg_add),
("linalg_sub", "a,b", linalg_sub),
("linalg_transpose", "expr", linalg_transpose),
("linalg_inv", "expr", linalg_inv),
("linalg_simplify", "expr", linalg_simplify),
("linalg_ascii", "expr,raw", linalg_ascii),
("linalg_latex", "expr,raw", linalg_latex),
("linalg_shape", "expr", linalg_shape),
("linalg_show", "expr,path,raw", linalg_show),
("linalg_explicit", "expr,raw", linalg_explicit),
("linalg_det", "expr", linalg_det),
("linalg_trace", "expr", linalg_trace),
("linalg_solve", "a,b,factor", linalg_solve),
("linalg_matmul", "a,b", linalg_matmul),
("linalg_kron", "a,b", linalg_kron),
("linalg_block", "blocks", linalg_block),
("linalg_collapse", "expr", linalg_collapse),
("linalg_factorize", "matrix,kind", linalg_factorize),
("linalg_draw", "factor,kind,path,theme", linalg_draw),
("linalg_lstsq", "a,b", linalg_lstsq),
("linalg_norm", "expr,ord", linalg_norm),
("linalg_cond", "expr", linalg_cond),
("linalg_rank", "expr", linalg_rank),
]);