feat(linalg): L5 examples, public feature pages, and skill docs

Ship SVD / least-squares examples, heatmap-hinton draw paths, coerce
dense factors into MatExpr ops, and document ext/linalg in skill/README.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-09-07 14:36:17 +08:00
1 parent 70fb2fbfb2
commit 01287d9e7e
15 files changed
+238 -26

No files matched your search

+21 -6
View File
@@ -4,10 +4,11 @@ description: >-
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
syntax (functions, calls, statements, returns, control flow). Use when writing
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
importing lib/* or ext/web or ext/quantum, running marqdo CLI, building dynamic
sites with ext/web, quantum circuits with ext/quantum, or when the user
mentions Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, or
quantum/量子 extension.
importing lib/* or ext/web or ext/quantum or ext/linalg, running marqdo CLI,
building dynamic sites with ext/web, quantum circuits with ext/quantum,
formula-first linear algebra with ext/linalg, or when the user mentions
Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, quantum/量子,
or linalg/线性代数 extension.
---
# Marqdo development
@@ -141,7 +142,7 @@ import clock:lib/time.mq.md
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
@@ -225,6 +226,19 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
## Official extension: `ext/linalg` (formula-first LA)
Install: `marqdo ext add linalg` (ZH id: `线性代数`). Build: `cargo build --release -p marqdo_plugin_linalg`, then **`marqdo ext add linalg` again** so view loads the new native lib.
- EN: `import la:ext/linalg/linalg.mq.md`
- ZH: `导入 la:ext/linalg/线性代数.mq.md`
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; prefer top-level `la.symbol` (not `matrix.symbol` without a receiver); quote `kind=` strings; dense `explicit` / factorize obey size guards.
APIs (EN): `symbol` / `mul` / `simplify` / `ascii` / `show` · `from_formula` / `explicit` / `det` / `solve` · `block` / `kron` / `collapse` · `factorize` / `draw` (`eig|svd|qr|lu|heatmap|hinton`).
Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../../examples/linalg-least-squares/). Design: [ext-linalg.md](../../doc/design/ext-linalg.md).
## AI authoring workflow
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
@@ -252,7 +266,8 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
| Bare `kind=hinton` inside `*…*` | `kind="hinton"` — quote text literals |
| Call `host_*` from `ext/linalg` | Use `la.*` L1 wrappers; plugin ABI only |
| Bare `kind=eig` inside `*…*` | `kind="eig"` — quote text literals |
| Bare `theme=dark` inside `*…*` | `theme="dark"` — quote; ZH `主题="dark"` |
| Rebuild plugin but skip `ext add` | `cargo build -p marqdo_plugin_quantum` then `marqdo ext add quantum` (or set `MARQDO_QUANTUM_PLUGIN`) |
+23
View File
@@ -326,3 +326,26 @@ import quantum:ext/quantum/quantum.mq.md
- Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`.
- `theme="dark"|"light"|"bw"` (default dark) on `circuit` / `probs` / `bloch`. Quote `kind=` / `theme=`.
- After rebuilding the plugin: `marqdo ext add quantum` so view loads the new native lib.
## 15. Linear algebra (ext/linalg)
```markdown
---
import la:ext/linalg/linalg.mq.md
---
# main
`M` =
$$
\begin{bmatrix}2&0\\0&3\end{bmatrix}
$$
*`M` = > la.from_formula formula=`M`*
*`f` = > la.factorize matrix=`M` kind="eig"*
*_ = > la.draw factor=`f` kind="eig" path="eig.svg"*
> print text=ok
```
- Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`.
- After rebuilding: `marqdo ext add linalg` (or `MARQDO_LINALG_PLUGIN`).
+14 -2
View File
@@ -12,8 +12,8 @@ marqdo view PATH # docs browser, default port 7429
marqdo debug PATH # debugger UI, default port 7430
marqdo catalog PATH -o .marqdo
marqdo ext list
marqdo ext add llm|agent|web|quantum
marqdo ext remove llm|agent|web|quantum
marqdo ext add llm|agent|web|quantum|linalg
marqdo ext remove llm|agent|web|quantum|linalg
```
Diagnostics look like `path:line:col: message` (1-based line/col).
@@ -57,6 +57,7 @@ Import one file; use **that** file’s function names.
| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) |
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | formula MatExpr + factorize/draw — see **ext/linalg** below |
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
@@ -98,6 +99,16 @@ Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p
Examples: `examples/quantum-bell/`, `examples/quantum-entanglement/`. Design: `doc/design/ext-quantum.md` · Q7: `doc/design/ext-quantum-q7.md` · Q8: `doc/design/ext-quantum-viz-style.md`.
## ext/linalg (formula-first linear algebra)
Install: `marqdo ext add linalg` (`线性代数`). Native: `cargo build --release -p marqdo_plugin_linalg`, then re-run `ext add`.
| EN import | ZH import | Notes |
|-----------|-----------|-------|
| `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`.
## Formula + plot (math)
```markdown
@@ -178,4 +189,5 @@ See `doc/design/call-arguments.md`.
| `doc/design/ext-quantum.md` | `ext/quantum` circuits |
| `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/view-debug.md` | view / debug hosts |
+3
View File
@@ -66,6 +66,9 @@ plugins/*/tmp/
/tests/ext/linalg-*.svg
/examples/quantum-*/**/*.svg
/examples/quantum-*/*.svg
/examples/linalg-*/**/*.svg
/examples/linalg-*/*.svg
/examples/linalg-*.svg
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
/ext/native/
+1 -1
View File
@@ -3,7 +3,7 @@
## Unreleased
### Added
- **`ext/linalg` L0–L4**:公式 MatExpr(含分块/`kron`)+ 稠密 `explicit`/`det`/`trace`/`solve`;`collapse` 分块乘;`factorize`(LU/QR/SVD/eig/chol)+ 结构 SVG `draw`;金样 `linalg-formula-smoke` · `linalg-zh-smoke` · `linalg-basic-smoke` · `linalg-block-kron` · `linalg-factor-smoke`。设计:[ext-linalg.md](doc/design/ext-linalg.md)。
- **`ext/linalg` L0–L5**:公式 MatExpr(含分块/`kron`)+ 稠密 `explicit`/`det`/`trace`/`solve`;`collapse` 分块乘;`factorize`(LU/QR/SVD/eig/chol)+ 结构/`heatmap`/`hinton` SVG;示例 `linalg-svd` · `linalg-least-squares`;金样 `linalg-formula-smoke` · `linalg-zh-smoke` · `linalg-basic-smoke` · `linalg-block-kron` · `linalg-factor-smoke`。设计:[ext-linalg.md](doc/design/ext-linalg.md)。
### Fixed
+3 -1
View File
@@ -111,10 +111,11 @@ 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–L5 公式 MatExpr + 稠密/`factorize`/`draw`;示例 [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`
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}`
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg}`
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
@@ -142,6 +143,7 @@ marqdo catalog public -o .marqdo
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native
marqdo ext add agent # 或:智能体
marqdo ext add quantum # 或:量子
marqdo ext add linalg # 或:线性代数
marqdo ext add llm # 或:大模型(纯 .mq.md)
# 开发者也可:cargo build --release -p marqdo_plugin_* 后在本机 target/ 安装
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1
+1 -1
View File
@@ -2,7 +2,7 @@
| | |
|---|---|
| 状态 | **Draft · L0–L4 已落地** |
| 状态 | **Draft · L0–L5 已落地** |
| 日期 | 2026-09-07 |
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
+5 -5
View File
@@ -2,7 +2,7 @@
| | |
|---|---|
| 状态 | **L0–L4 已落地 · L5+ 待做** |
| 状态 | **L0–L5 已落地 · L6+ 待做** |
| 日期 | 2026-09-07 |
| **锁定设计** | [design/ext-linalg.md](../design/ext-linalg.md) |
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
@@ -28,7 +28,7 @@
| **L2** | `explicit` / 小阵 gemm·解系·`det`·`trace`;维数护栏;金样 `linalg-basic-smoke` | **done** |
| **L3** | `block` + `collapse`;`kron` 惰性 + R7;金样 `linalg-block-kron` | **done** |
| **L4** | `factorize` LU/QR/SVD/eig(+ 可选 chol);结构 SVG `svd|qr|ge|eig`;金样 `linalg-factor-smoke` | **done** |
| **L5** | `heatmap`/`hinton`;examples(最小二乘 / SVD 示意);public + skill 摘要 | **pending** |
| **L5** | `heatmap`/`hinton`;examples(最小二乘 / SVD 示意);public + skill 摘要 | **done** |
| **L6** | 复数 dtype;`lstsq`;`norm`/`cond`;主题令牌对齐 | **pending** |
| **L7+** | 矩阵微积分 / 更大 BLAS 依赖(仅当用户明确要求) | **deferred** |
@@ -70,9 +70,9 @@
### L5
- [ ] 至少 1 个 examples 可 `marqdo run`
- [ ] public/features 或 tutorial 短页
- [ ] skill / CHANGELOG Unreleased 条目
- [x] 至少 1 个 examples 可 `marqdo run`
- [x] public/features 或 tutorial 短页
- [x] skill / CHANGELOG Unreleased 条目
---
+12
View File
@@ -0,0 +1,12 @@
# linalg-least-squares
Overdetermined least squares via `ext/linalg`: `factorize kind=qr`, `Qᵀb`, solve `R`, plus a heatmap SVG of `A`.
```bash
cargo build --release -p marqdo_plugin_linalg
marqdo ext add linalg # once (re-run after rebuilding the plugin)
marqdo run examples/linalg-least-squares/index.mq.md
# optional: marqdo view examples/linalg-least-squares/
```
Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · sibling: [linalg-svd](../linalg-svd/).
+45
View File
@@ -0,0 +1,45 @@
---
title: Least squares via QR
description: Overdetermined Ax≈b with ext/linalg QR + heatmap.
import la:ext/linalg/linalg.mq.md
import math:lib/math.mq.md
---
# Least squares from a runnable document
Fit a line through three points with an overdetermined `A x ≈ b`. Factor `A = QR`, form `Qᵀ b`, then solve the square upper-triangular `R`. A heatmap makes the design matrix visible in `view`.
# main
`A` =
$$
\begin{bmatrix}1&0\\1&1\\1&2\end{bmatrix}
$$
`b` =
$$
\begin{pmatrix}1\\2\\2\end{pmatrix}
$$
*`A` = > la.from_formula formula=`A`*
*`b` = > la.from_formula formula=`b`*
*`_` = > la.draw factor=`A` kind="heatmap" path="ls-heatmap.svg"*
*`qr` = > la.factorize matrix=`A` kind="qr"*
*`Q` = qr[^Q]*
*`R` = qr[^R]*
*`Qt` = > la.transpose expr=`Q`*
*`Qtb` = > la.matmul a=`Qt` b=`b`*
*`sol` = > la.solve a=`R` b=`Qtb`*
*`x` = sol[^x]*
*`Ax` = > la.matmul a=`A` b=`x`*
*`r0` = > at value=Ax[^data] index=0*
*`ax0` = > at value=`r0` index=0*
*`diff` = > math.sub a=`ax0` b=1*
*`diff` = > math.abs value=`diff`*
> print text=`x`
> print text=`diff`
> print text=ls-ok
+12
View File
@@ -0,0 +1,12 @@
# linalg-svd
Dense SVD via `ext/linalg`: singular values + structure / hinton SVG.
```bash
cargo build --release -p marqdo_plugin_linalg
marqdo ext add linalg
marqdo run examples/linalg-svd/index.mq.md
# optional: marqdo view examples/linalg-svd/
```
Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · sibling: [linalg-least-squares](../linalg-least-squares/).
+25
View File
@@ -0,0 +1,25 @@
---
title: SVD structure demo
description: Diagonal SVD + structure SVG via ext/linalg.
import la:ext/linalg/linalg.mq.md
---
# SVD from a runnable document
A diagonal matrix has singular values on the diagonal. `factorize kind=svd` returns `U`, `S`, `Vt`; `draw kind=svd` writes a teaching structure SVG for `view`.
# main
`M` =
$$
\begin{bmatrix}4&0\\0&2\end{bmatrix}
$$
*`M` = > la.from_formula formula=`M`*
*`f` = > la.factorize matrix=`M` kind="svd"*
*`S` = f[^S]*
*`_` = > la.draw factor=`f` kind="svd" path="svd-structure.svg"*
*`hm` = > la.draw factor=`M` kind="hinton" path="svd-hinton.svg"*
> print text=`S`
> print text=svd-ok
+9 -10
View File
@@ -192,13 +192,21 @@ 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 Expr::from_value(e);
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()
}
@@ -349,15 +357,6 @@ la_ffi!(linalg_show, |args: &Value| {
Ok(out)
});
fn coerce_expr(v: &Value) -> Result<Expr, String> {
if let Ok(e) = Expr::from_value(v) {
return Ok(e);
}
// Formula Matrix / nested list / linalg_dense → dense leaf
let data = dense::from_value(v)?;
Ok(Expr::Dense { data })
}
la_ffi!(linalg_from_formula, |args: &Value| {
let f = args
.get("formula")
+32
View File
@@ -0,0 +1,32 @@
---
title: Linear algebra (ext/linalg)
description: Formula MatExpr, dense eval, factorize, structure SVG
import la:ext/linalg/linalg.mq.md
---
# main
Optional package (not stdlib). Install: `marqdo ext add linalg` (or build `marqdo_plugin_linalg`).
Formula-first: symbols stay symbolic until `explicit` / `factorize`. `(AB)^T` simplifies to `B^T*A^T` without dense data.
L4–L5: `factorize kind=eig|svd|qr|lu|chol`, `draw kind=eig|svd|heatmap|hinton`, examples `examples/linalg-svd/` · `examples/linalg-least-squares/`.
*`A` = > la.symbol name="A" rows=2 cols=2*
*`B` = > la.symbol name="B" rows=2 cols=2*
*`P` = > la.mul a=`A` b=`B`*
*`Pt` = > la.transpose expr=`P`*
*`s` = > la.simplify expr=`Pt`*
*`t` = > la.ascii expr=`s`*
`M` =
$$
\begin{bmatrix}2&0\\0&3\end{bmatrix}
$$
*`M` = > la.from_formula formula=`M`*
*`f` = > la.factorize matrix=`M` kind="eig"*
*`_` = > la.draw factor=`f` kind="eig"*
> print text=`t`
> print text=linalg-feature-ok
+32
View File
@@ -0,0 +1,32 @@
---
title: 线性代数(ext/linalg)
description: 公式 MatExpr、稠密求值、分解与结构 SVG
导入 la:ext/linalg/线性代数.mq.md
---
# main
可选扩展(非 stdlib)。安装:`marqdo ext add linalg`(中文 id:`线性代数`),或先编译 `marqdo_plugin_linalg`。
公式优先:符号式在 `求值` / `分解` 前保持惰性。`(AB)^T` 化简为 `B^T*A^T`,不生成稠密数据。
L4–L5:`分解`、`绘图`(`eig`/`svd`/`heatmap`/`hinton`);示例 `examples/linalg-svd/` · `examples/linalg-least-squares/`。
*`A` = > la.符号 名="A" 行=2 列=2*
*`B` = > la.符号 名="B" 行=2 列=2*
*`P` = > la.乘 左=`A` 右=`B`*
*`Pt` = > la.转置 式=`P`*
*`s` = > la.化简 式=`Pt`*
*`t` = > la.文本 式=`s`*
`M` =
$$
\begin{bmatrix}2&0\\0&3\end{bmatrix}
$$
*`M` = > la.自公式 公式=`M`*
*`f` = > la.分解 矩阵=`M` 类型="eig"*
*`_` = > la.绘图 分解=`f` 类型="eig"*
> 打印 内容=`t`
> 打印 内容=linalg-feature-ok