From f3c49e86aebc62bb668226be45a27c8afc195ede Mon Sep 17 00:00:00 2001 From: cflmy Date: Mon, 7 Sep 2026 15:52:46 +0800 Subject: [PATCH] feat(linalg): F2 declare from GFM table and lecture example Add la.declare for batch MatrixSymbol from @-record tables, ship examples/linalg-transpose, and mark formula-doc F2 done. Co-authored-by: Cursor --- .cursor/skills/marqdo/reference.md | 3 +- CHANGELOG.md | 2 +- README.md | 2 +- doc/design/ext-linalg-formula-doc.md | 2 +- doc/roadmap/ext-linalg.md | 6 ++-- examples/linalg-transpose/README.md | 11 ++++++++ examples/linalg-transpose/index.mq.md | 30 ++++++++++++++++++++ ext/linalg/linalg.mq.md | 8 ++++++ ext/linalg/线性代数.mq.md | 8 ++++++ plugins/linalg/src/lib.rs | 40 +++++++++++++++++++++++++++ tests/ext/linalg-doc-smoke.mq.md | 17 ++++++++++++ tests/gold.rs | 2 +- 12 files changed, 123 insertions(+), 8 deletions(-) create mode 100644 examples/linalg-transpose/README.md create mode 100644 examples/linalg-transpose/index.mq.md diff --git a/.cursor/skills/marqdo/reference.md b/.cursor/skills/marqdo/reference.md index cb59ff5..c5d7f2d 100644 --- a/.cursor/skills/marqdo/reference.md +++ b/.cursor/skills/marqdo/reference.md @@ -107,7 +107,7 @@ Install: `marqdo ext add linalg` (`线性代数`). Native: `cargo build --releas |-----------|-----------|-------| | `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | Top-level `symbol`/`mul`/`factorize`/`draw` | -Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc/design/ext-linalg.md` · roadmap: `doc/roadmap/ext-linalg.md`. +Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc/design/ext-linalg.md` · formula-doc: `doc/design/ext-linalg-formula-doc.md` · roadmap: `doc/roadmap/ext-linalg.md`. ## Formula + plot (math) @@ -190,4 +190,5 @@ See `doc/design/call-arguments.md`. | `doc/design/ext-quantum-q7.md` | Q7 density linear algebra + advanced SVG | | `doc/design/ext-quantum-viz-style.md` | Q8 themed SVG (`dark`/`light`/`bw`; circuit/probs/bloch) | | `doc/design/ext-linalg.md` | `ext/linalg` formula MatExpr + factorize/draw | +| `doc/design/ext-linalg-formula-doc.md` | 公式文档面:跑通即正确 · 代数/计算两面 | | `doc/design/view-debug.md` | view / debug hosts | diff --git a/CHANGELOG.md b/CHANGELOG.md index a7d4f70..808a7e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ ## Unreleased ### Added -- **`ext/linalg`**:L0–L6 + 中缀/`# matrix`;**公式文档面** [ext-linalg-formula-doc.md](doc/design/ext-linalg-formula-doc.md)(跑通即正确);F1 展示默认 simplify(`raw=` 可关);金样含 `linalg-doc-smoke` · `linalg-infix-smoke`。设计:[ext-linalg.md](doc/design/ext-linalg.md)。 +- **`ext/linalg`**:L0–L6 + 中缀/`# matrix`;公式文档面 [ext-linalg-formula-doc.md](doc/design/ext-linalg-formula-doc.md);F1 展示默认 simplify;F2 `declare`(GFM 表声明符号)+ 示例 `linalg-transpose`;金样 `linalg-doc-smoke` · `linalg-infix-smoke`。设计:[ext-linalg.md](doc/design/ext-linalg.md)。 ### Fixed diff --git a/README.md b/README.md index 9326c59..d29cdf5 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,7 @@ marqdo catalog public -o .marqdo - **官方扩展库 `ext/`**(**非** stdlib,本版收口): - **`web`**:W0–W7 + P3 + **W8**;**定制 C0–C4**(admin 前缀/gates/`shell_css`/`layout`/样式 strict/脚本 defer·version/条件导航,见 [ext-web-customization](doc/design/ext-web-customization/));示例 [marqdo-blog](examples/marqdo-blog/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md) - **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/) - - **`linalg`**:L0–L6 公式 MatExpr + 稠密/`factorize`/`lstsq`/`draw theme`;示例 [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/) + - **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/) - **`agent`**:A1–A4(OKF 复用、过程事件、上下文预算、RAG/MCP fixture);下一波缺口 [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md) - **`llm`**:OpenAI 兼容对话 - 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add` diff --git a/doc/design/ext-linalg-formula-doc.md b/doc/design/ext-linalg-formula-doc.md index 9d7e906..b9c69af 100644 --- a/doc/design/ext-linalg-formula-doc.md +++ b/doc/design/ext-linalg-formula-doc.md @@ -174,7 +174,7 @@ | 稠密 / 分解 / 度量 / draw theme | done(L2–L6) | | 中缀 `+` `-` `*` + `# matrix` 方法 | done(v1) | | `ascii`/`latex`/`show` 默认 simplify | **done(F1)** | -| 更少噪音的符号引入 | F2 | +| 更少噪音的符号引入 | **done(F2:`declare` + 表)** | | 更紧凑转置 / 混合公式书写 | F3 | | 矩阵微积分等 | L7+ / 规则表扩展 | diff --git a/doc/roadmap/ext-linalg.md b/doc/roadmap/ext-linalg.md index d41c5c1..fbb94b2 100644 --- a/doc/roadmap/ext-linalg.md +++ b/doc/roadmap/ext-linalg.md @@ -31,7 +31,7 @@ | **L5** | `heatmap`/`hinton`;examples(最小二乘 / SVD 示意);public + skill 摘要 | **done** | | **L6** | 复数 dtype;`lstsq`;`norm`/`cond`;主题令牌对齐 | **done** | | **F1** | 展示路径默认 simplify;公式文档金样 | **done** | -| **F2** | 符号引入降噪;examples 讲义化 | **pending** | +| **F2** | 符号引入降噪;examples 讲义化 | **done** | | **F3** | 紧凑糖 + public「如何写公式文档」 | **pending** | | **L7+** | 矩阵微积分 / 更大 BLAS 依赖(仅当用户明确要求) | **deferred** | @@ -91,8 +91,8 @@ ### F2 -- [ ] 符号引入降噪(选定候选) -- [ ] 至少 1 个 example 以代数面为主叙述 +- [x] 符号引入降噪(选定候选) — GFM `@` 表 + `la.declare` +- [x] 至少 1 个 example 以代数面为主叙述 — `examples/linalg-transpose/` --- diff --git a/examples/linalg-transpose/README.md b/examples/linalg-transpose/README.md new file mode 100644 index 0000000..0927dc6 --- /dev/null +++ b/examples/linalg-transpose/README.md @@ -0,0 +1,11 @@ +# linalg-transpose + +Formula-document example: declare symbols with a GFM table, check \((AB)^\top = B^\top A^\top\) via `ascii` (auto-simplify). + +```bash +cargo build --release -p marqdo_plugin_linalg +marqdo ext add linalg +marqdo run examples/linalg-transpose/index.mq.md +``` + +Design: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md). diff --git a/examples/linalg-transpose/index.mq.md b/examples/linalg-transpose/index.mq.md new file mode 100644 index 0000000..1c3653c --- /dev/null +++ b/examples/linalg-transpose/index.mq.md @@ -0,0 +1,30 @@ +--- +title: Transpose identity (formula document) +description: (AB)^T = B^T A^T as a runnable lecture fragment. +import la:ext/linalg/linalg.mq.md +--- + +# Transpose reverses products + +Declare shapes in a table, form \(P = AB\), then check \((AB)^\top = B^\top A^\top\) by running the document. + +# main + +`shapes` = + +| @ | name | rows | cols | +|---|------|------|------| +| 1 | A | 2 | 3 | +| 2 | B | 3 | 2 | + +*`env` = > la.declare table=`shapes`* +*`A` = env[^A]* +*`B` = env[^B]* +*`P` = `A` * `B`* +*`Pt` = > `P`.T* +*`t` = > `Pt`.ascii* +> print text=`t` +1. `t` == "B^T*A^T" + > print text=identity-ok +2. * + > print text=identity-fail diff --git a/ext/linalg/linalg.mq.md b/ext/linalg/linalg.mq.md index a4d01b9..dc86f2e 100644 --- a/ext/linalg/linalg.mq.md +++ b/ext/linalg/linalg.mq.md @@ -246,6 +246,14 @@ Numerical rank (SVD). > ensure_plugin **> linalg_rank expr=`expr`** +## declare + + `table` + +Declare several matrix symbols from an `@` record table (`name` / `rows` / `cols`). Returns a map env. + +> ensure_plugin +**> linalg_declare table=`table`** + ## symbol + `name` + `rows` diff --git a/ext/linalg/线性代数.mq.md b/ext/linalg/线性代数.mq.md index 6523944..1d03d38 100644 --- a/ext/linalg/线性代数.mq.md +++ b/ext/linalg/线性代数.mq.md @@ -240,6 +240,14 @@ import sys:lib/sys.mq.md > 确保插件 **> linalg_rank expr=`式`** +## 声明 + + `表` + +用 `@` 记录表一次声明多个符号矩阵(`名` / `行` / `列`)。返回环境 map。 + +> 确保插件 +**> linalg_declare table=`表`** + ## 符号 + `名` + `行` diff --git a/plugins/linalg/src/lib.rs b/plugins/linalg/src/lib.rs index 7638bb0..7fadaf6 100644 --- a/plugins/linalg/src/lib.rs +++ b/plugins/linalg/src/lib.rs @@ -232,6 +232,7 @@ la_ffi!(linalg_ping, |_args: &Value| { "cond", "rank", "complex", + "declare", ], })) }); @@ -272,6 +273,44 @@ la_ffi!(linalg_from_list, |args: &Value| { 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 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); + out.insert(name, expr.to_value()?); + } + Ok(Value::Object(out)) +}); + la_ffi!(linalg_mul, |args: &Value| { let a = arg_expr_opt(args, &["a", "左"])?; let b = arg_expr_opt(args, &["b", "右"])?; @@ -601,6 +640,7 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("linalg_eye", "n", linalg_eye as PluginFn), ("linalg_zeros", "rows,cols", linalg_zeros as PluginFn), ("linalg_from_list", "data", linalg_from_list as PluginFn), + ("linalg_declare", "table", linalg_declare as PluginFn), ("linalg_from_formula", "formula", linalg_from_formula as PluginFn), ("linalg_mul", "a,b", linalg_mul as PluginFn), ("linalg_add", "a,b", linalg_add as PluginFn), diff --git a/tests/ext/linalg-doc-smoke.mq.md b/tests/ext/linalg-doc-smoke.mq.md index d12d08a..4641d09 100644 --- a/tests/ext/linalg-doc-smoke.mq.md +++ b/tests/ext/linalg-doc-smoke.mq.md @@ -21,6 +21,23 @@ Narration: \((AB)^\top = B^\top A^\top\). The identity is checked by running thi 2. * > print text=identity-fail +`shapes` = + +| @ | name | rows | cols | +|---|------|------|------| +| 1 | X | 2 | 2 | +| 2 | Y | 2 | 2 | + +*`env` = > la.declare table=`shapes`* +*`X` = env[^X]* +*`Y` = env[^Y]* +*`S` = `X` + `Y`* +*`st` = > la.ascii expr=`S`* +1. `st` == "X + Y" + > print text=declare-ok +2. * + > print text=declare-fail + *`raw` = > la.ascii expr=`Pt` raw=True* 1. `raw` == "(A*B)^T" > print text=raw-ok diff --git a/tests/gold.rs b/tests/gold.rs index 7108910..e0bc892 100644 --- a/tests/gold.rs +++ b/tests/gold.rs @@ -2474,7 +2474,7 @@ fn ext_linalg_doc_smoke() { assert!(status.success(), "failed to build marqdo_plugin_linalg"); assert_out( "tests/ext/linalg-doc-smoke.mq.md", - "B^T*A^T\nidentity-ok\nraw-ok", + "B^T*A^T\nidentity-ok\ndeclare-ok\nraw-ok", ); }