Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
55f1a37b3d | ||
|
|
58dff0a1e9 | ||
|
|
fc543f1ca5 | ||
|
|
2e068e66d4 | ||
|
|
a4c346d4a2 | ||
|
|
fe14d1f7e3 | ||
|
|
f4b39dfe80 | ||
|
|
7d86ed1d9c | ||
|
|
506de65dae | ||
|
|
08384c7540 | ||
|
|
94ae6713aa | ||
|
|
838a2b425a | ||
|
|
1a5ee57a6f | ||
|
|
d539e6b96b | ||
|
|
3ade036d34 | ||
|
|
f3c49e86ae | ||
|
|
b2401b8458 | ||
|
|
51bb8767e3 | ||
|
|
c0fbe9b182 | ||
|
|
01287d9e7e | ||
|
|
70fb2fbfb2 | ||
|
|
b6f116108c | ||
|
|
03aca7cdac | ||
|
|
96da88e168 | ||
|
|
b6cceab218 |
No files matched your search
@@ -166,7 +166,7 @@ git checkout vVER
|
||||
cargo build --release
|
||||
./target/release/marqdo version
|
||||
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
|
||||
marqdo ext add web && marqdo ext add agent && marqdo ext add quantum
|
||||
# 中文 id:网页 / 智能体 / 量子
|
||||
```
|
||||
|
||||
@@ -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` → `# matrix`;中缀 `+`/`-`/`*`;方法 `` `A`.T `` / ``.simplify`` / ``.ascii`` · `from_formula` / `explicit` / `factorize` / `draw` · `lstsq` / `norm` / `cond` / `rank`.
|
||||
|
||||
Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../../examples/linalg-least-squares/). Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · formula-doc: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.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`) |
|
||||
|
||||
|
||||
@@ -149,6 +149,39 @@ import text:lib/text.mq.md
|
||||
> print text=`parts`
|
||||
```
|
||||
|
||||
## 7b. Mid M1 — regex + encoding (no plugin)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import re:lib/re.mq.md
|
||||
import enc:lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`ok` = > re.is_match text="a@b.c" pattern="@"*
|
||||
*`b64` = > enc.base64_encode text="hi"*
|
||||
> print text=`ok`
|
||||
> print text=`b64`
|
||||
```
|
||||
|
||||
## 7c. Mid M6 — log + uuid
|
||||
|
||||
```markdown
|
||||
---
|
||||
import log:lib/log.mq.md
|
||||
import uuid:lib/uuid.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> log.info text="start"
|
||||
> log.set_level level="debug"
|
||||
> log.debug text="detail"
|
||||
*id = > uuid.v4*
|
||||
> print text=`id`
|
||||
```
|
||||
|
||||
## 8. Comment paragraphs (blank-line rule)
|
||||
|
||||
```markdown
|
||||
@@ -326,3 +359,31 @@ 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
|
||||
|
||||
*`A` = > la.symbol name="A" rows=2 cols=2*
|
||||
*`B` = > la.symbol name="B" rows=2 cols=2*
|
||||
*`C` = `A` + `B`*
|
||||
*`P` = `A` * `B`*
|
||||
*`s` = > `P`.T.simplify* <!-- prefer: *`Pt` = > `P`.T* then simplify -->
|
||||
```
|
||||
|
||||
Prefer:
|
||||
|
||||
```markdown
|
||||
*`env` = > la.declare table=`shapes`*
|
||||
*`P` = env[^A] * env[^B]*
|
||||
*`t` = > `P`.T_ascii*
|
||||
```
|
||||
|
||||
- Infix `+` / `-` / `*`;`ascii` / `T_ascii` 默认化简(`raw=True` 可关)。
|
||||
- Formula-doc design: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
|
||||
- Examples: `examples/linalg-transpose/`, `examples/linalg-svd/`, `examples/linalg-least-squares/`.
|
||||
@@ -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).
|
||||
@@ -44,6 +44,15 @@ Import one file; use **that** file’s function names.
|
||||
|-----------|-----------|-------------------------|
|
||||
| `lib/text.mq.md` | `lib/文本.mq.md` | text helpers / 去空白·拆分·拼接… |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | `put`/`改` + list/map(见 `doc/design/stdlib-table.md`) |
|
||||
| `lib/re.mq.md` | `lib/正则.mq.md` | Mid:`is_match`/`find`/`replace`/… |
|
||||
| `lib/encoding.mq.md` | `lib/编码.mq.md` | Mid:base64/hex |
|
||||
| `lib/path.mq.md` | `lib/路径.mq.md` | Mid:join/normalize/… |
|
||||
| `lib/hash.mq.md` | `lib/哈希.mq.md` | Mid:sha256/hmac/… |
|
||||
| `lib/secrets.mq.md` | `lib/机密.mq.md` | Mid:token_hex/urlsafe |
|
||||
| `lib/csv.mq.md` | `lib/逗号表.mq.md` | Mid:parse/stringify |
|
||||
| `lib/cli.mq.md` | `lib/命令行.mq.md` | Mid:`parse` flags |
|
||||
| `lib/log.mq.md` | `lib/日志.mq.md` | Mid:level-filtered one-line logs |
|
||||
| `lib/uuid.mq.md` | `lib/标识.mq.md` | Mid:UUID v4 |
|
||||
| `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM client effect helpers(GFM + `set_text`/`canvas`/…;见 marqdo-dev) |
|
||||
| `lib/fs.mq.md` | `lib/文件.mq.md` | filesystem |
|
||||
| `lib/sys.mq.md` | `lib/系统.mq.md` | process / cwd / load_dotenv |
|
||||
@@ -57,6 +66,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 +108,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` · formula-doc: `doc/design/ext-linalg-formula-doc.md` · roadmap: `doc/roadmap/ext-linalg.md`.
|
||||
|
||||
## Formula + plot (math)
|
||||
|
||||
```markdown
|
||||
@@ -178,4 +198,6 @@ 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/ext-linalg-formula-doc.md` | 公式文档面:跑通即正确 · 代数/计算两面 |
|
||||
| `doc/design/view-debug.md` | view / debug hosts |
|
||||
@@ -28,7 +28,7 @@ jobs:
|
||||
- name: Build release CLI + official plugins
|
||||
run: |
|
||||
cargo build --release
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
|
||||
|
||||
- name: Checkout extension sources (branch vscode-extension only)
|
||||
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
|
||||
@@ -75,6 +75,7 @@ jobs:
|
||||
Copy-Item target/release/web.dll "$stageNative/native/web.dll"
|
||||
Copy-Item target/release/agent.dll "$stageNative/native/agent.dll"
|
||||
Copy-Item target/release/quantum.dll "$stageNative/native/quantum.dll"
|
||||
Copy-Item target/release/linalg.dll "$stageNative/native/linalg.dll"
|
||||
if (Test-Path "dist/$nativeZip") { Remove-Item "dist/$nativeZip" -Force }
|
||||
Compress-Archive -Path "$stageNative/*" -DestinationPath "dist/$nativeZip" -Force
|
||||
$stage = "dist/stage-bundle"
|
||||
@@ -87,6 +88,7 @@ jobs:
|
||||
Copy-Item target/release/web.dll "$stage/ext/native/web.dll"
|
||||
Copy-Item target/release/agent.dll "$stage/ext/native/agent.dll"
|
||||
Copy-Item target/release/quantum.dll "$stage/ext/native/quantum.dll"
|
||||
Copy-Item target/release/linalg.dll "$stage/ext/native/linalg.dll"
|
||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
||||
$stageLib = "dist/stage-stdlib"
|
||||
@@ -111,10 +113,9 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **`marqdo ext add` 无需本机 Rust**:发布附带预编译 native 插件;`ext add` 可自动下载
|
||||
- **Prebuilt native plugins**: `marqdo-*-native-*.zip`; Windows zip includes `ext/native/`
|
||||
- Install: `marqdo ext add web|agent|quantum|llm`(零源码编译)
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-cli.md](https://github.com/cflmy/marqdo/blob/main/doc/design/ext-cli.md)
|
||||
- **宿主 H1–H4**:`app.proxy` 同域 SSE 中继 · `app.invoke` HTTP→`##` · MCP Server stdio · 跨模块 db
|
||||
- **Hosting H1–H4**: same-origin SSE proxy, HTTP→user `##`, MCP stdio server, cross-module db methods
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-hosting.md](https://github.com/cflmy/marqdo/blob/main/doc/roadmap/ext-hosting.md)
|
||||
|
||||
### Downloads
|
||||
|
||||
@@ -152,7 +153,7 @@ jobs:
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Build official plugins (release)
|
||||
run: cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
|
||||
run: cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
|
||||
|
||||
- name: Package native zip
|
||||
run: |
|
||||
@@ -163,6 +164,7 @@ jobs:
|
||||
cp target/release/libweb.so dist/stage-native/native/libweb.so
|
||||
cp target/release/libagent.so dist/stage-native/native/libagent.so
|
||||
cp target/release/libquantum.so dist/stage-native/native/libquantum.so
|
||||
cp target/release/liblinalg.so dist/stage-native/native/liblinalg.so
|
||||
(cd dist/stage-native && zip -r "../marqdo-${VER}-native-${TARGET}.zip" .)
|
||||
echo "NATIVE=marqdo-${VER}-native-${TARGET}.zip" >> "$GITHUB_ENV"
|
||||
|
||||
|
||||
@@ -63,8 +63,12 @@ plugins/*/tmp/
|
||||
|
||||
# Quantum draw/SVG runtime outputs (sources & gold .mq.md stay tracked)
|
||||
/tests/ext/quantum-*.svg
|
||||
/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/
|
||||
@@ -8,6 +8,57 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## v0.3.7 — 2026-09-07
|
||||
|
||||
### Highlights
|
||||
|
||||
**宿主集成 H1–H4**:浏览器同域 SSE/HTTP 流式中继(`app.proxy`)、HTTP→用户 `##`(`app.invoke`)、跨模块 db 方法分发、`corpus_search` 可发现、MCP Server stdio——下游可去掉 Python 旁路。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.7
|
||||
# 或下载 Release 的 exe / zip
|
||||
marqdo ext add web && marqdo ext add agent
|
||||
# *app*.proxy / *app*.invoke · agent.mcp_server
|
||||
```
|
||||
|
||||
### Added
|
||||
- **宿主集成 H1–H4**:`ext/web` `app.proxy`(同域 SSE/HTTP 流式中继)与 `app.invoke`(HTTP→`lib.member`);跨模块 `#` 对象方法查找;`agent.corpus_search` 自动加载插件;`agent.mcp_server` stdio。金样 `web-proxy-invoke-smoke` · `web-hosting-live` · `web-db-cross-module-smoke` · `agent-mcp-server-smoke`。设计 [ext-hosting-fill.md](doc/design/ext-hosting-fill.md) · [ext-hosting.md](doc/roadmap/ext-hosting.md)。
|
||||
- **文档**:宿主集成缺口盘点——[ext-hosting-gaps.md](doc/research/ext-hosting-gaps.md)。
|
||||
|
||||
### Fixed
|
||||
- **方法分发**:`find_object_type` 沿导入树传递查找,跨模块拿到的 `web.db` 等句柄可再调方法。
|
||||
|
||||
### Changed
|
||||
|
||||
## v0.3.6 — 2026-09-07
|
||||
|
||||
### Highlights
|
||||
|
||||
**中层标准库 Mid M1–M6 收口**:通用原语沉入 `lib/`(正则、编解码、路径、哈希、机密、CSV、加厚文本/集合、CLI、日志、UUID),写日常脚本与多数扩展库不再需要原生插件。另含 `ext/linalg` 公式文档面与 agent/llm 稳健性修复。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.6
|
||||
# 或下载 Release 的 exe / zip
|
||||
marqdo run public/features/13-log-uuid.mq.md
|
||||
marqdo ext add linalg # 可选:公式文档 / 线性代数
|
||||
```
|
||||
|
||||
|
||||
### Added
|
||||
- **中层标准库 M6**:`lib/log` / `日志`(级别过滤的一行日志)与 `lib/uuid` / `标识`(v4);金样与 public `13-log-uuid`。设计 [stdlib-log-uuid.md](doc/design/stdlib-log-uuid.md)。**Mid M1–M6 收口。**
|
||||
- **中层标准库 M5**:`table`/`表` 加厚(sort/sort_by/unique/chunk/zip/flatten)与 `lib/cli`/`命令行`(parse);金样与 public `12-list-cli`。设计 [stdlib-list-cli.md](doc/design/stdlib-list-cli.md)。
|
||||
- **中层标准库 M4**:`lib/csv` / `逗号表`(parse/stringify)与 `lib/text` / `文本` 加厚(contains/replace/case/pad/…);金样与 public `11-csv-text`。设计 [stdlib-csv.md](doc/design/stdlib-csv.md) · [stdlib-text-mid.md](doc/design/stdlib-text-mid.md)。
|
||||
- **中层标准库 M3**:`lib/hash` / `哈希`(sha256/sha1/md5/hmac_sha256)与 `lib/secrets` / `机密`(token_hex/token_urlsafe);金样与 public `10-hash-secrets`。设计 [stdlib-hash.md](doc/design/stdlib-hash.md) · [stdlib-secrets.md](doc/design/stdlib-secrets.md)。
|
||||
- **中层标准库 M2**:`lib/path` / `lib/路径`(join/split/normalize/…)与 `fs`/`文件` 加厚(`copy_file`/`move`/`make_temp`);金样与 public `09-path-fs`。设计 [stdlib-path.md](doc/design/stdlib-path.md) · [stdlib-fs-mid.md](doc/design/stdlib-fs-mid.md)。
|
||||
- **中层标准库 M1**:`lib/re` / `lib/正则`(`is_match`/`find`/`find_all`/`replace`/`split`)与 `lib/encoding` / `lib/编码`(base64/hex);host `host_re_*` + `host_encoding_*`;金样与 public `08-re-encoding`。设计 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-re.md](doc/design/stdlib-re.md) · [stdlib-encoding.md](doc/design/stdlib-encoding.md)。
|
||||
- **`ext/linalg`**:L0–L6 + 公式文档面 **F1–F3**(中缀、`declare`、展示/`explicit` 默认化简、`T_ascii`、public「如何写公式文档」);示例 `linalg-transpose` · `linalg-svd` · `linalg-least-squares`。设计:[ext-linalg-formula-doc.md](doc/design/ext-linalg-formula-doc.md)。
|
||||
|
||||
### Fixed
|
||||
- **`ext/agent`**:写回改走 `wb.record`(避免 `writeback` 形参遮蔽模块名),不再直调 `host_*`。
|
||||
- **`ext/llm`**:`stream_result` 忽略未知 SSE 类型(如 `reasoning`),不再因此退出。
|
||||
|
||||
### Changed
|
||||
|
||||
## v0.3.5 — 2026-09-04
|
||||
|
||||
### Highlights
|
||||
|
||||
Generated
+292
-10
@@ -317,6 +317,12 @@ version = "1.0.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
|
||||
|
||||
[[package]]
|
||||
name = "cfg_aliases"
|
||||
version = "0.2.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
|
||||
|
||||
[[package]]
|
||||
name = "chacha20"
|
||||
version = "0.10.2"
|
||||
@@ -465,9 +471,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "crossbeam-utils"
|
||||
version = "0.8.22"
|
||||
version = "0.8.21"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
|
||||
checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
|
||||
|
||||
[[package]]
|
||||
name = "crypto-common"
|
||||
@@ -631,6 +637,12 @@ version = "0.3.33"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
|
||||
|
||||
[[package]]
|
||||
name = "futures-io"
|
||||
version = "0.3.34"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"
|
||||
|
||||
[[package]]
|
||||
name = "futures-macro"
|
||||
version = "0.3.33"
|
||||
@@ -661,9 +673,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
|
||||
dependencies = [
|
||||
"futures-core",
|
||||
"futures-io",
|
||||
"futures-macro",
|
||||
"futures-sink",
|
||||
"futures-task",
|
||||
"memchr",
|
||||
"pin-project-lite",
|
||||
"slab",
|
||||
]
|
||||
@@ -694,8 +708,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"js-sys",
|
||||
"libc",
|
||||
"wasi 0.11.1+wasi-snapshot-preview1",
|
||||
"wasm-bindgen",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -717,9 +733,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"js-sys",
|
||||
"libc",
|
||||
"r-efi 6.0.0",
|
||||
"rand_core 0.10.1",
|
||||
"wasm-bindgen",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -848,6 +866,23 @@ dependencies = [
|
||||
"pin-project-lite",
|
||||
"smallvec",
|
||||
"tokio",
|
||||
"want",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "hyper-rustls"
|
||||
version = "0.27.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
|
||||
dependencies = [
|
||||
"http",
|
||||
"hyper",
|
||||
"hyper-util",
|
||||
"rustls 0.23.44",
|
||||
"tokio",
|
||||
"tokio-rustls",
|
||||
"tower-service",
|
||||
"webpki-roots 1.0.9",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -856,13 +891,21 @@ version = "0.1.20"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
|
||||
dependencies = [
|
||||
"base64",
|
||||
"bytes",
|
||||
"futures-channel",
|
||||
"futures-util",
|
||||
"http",
|
||||
"http-body",
|
||||
"hyper",
|
||||
"ipnet",
|
||||
"libc",
|
||||
"percent-encoding",
|
||||
"pin-project-lite",
|
||||
"socket2 0.6.5",
|
||||
"tokio",
|
||||
"tower-service",
|
||||
"tracing",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -939,6 +982,12 @@ dependencies = [
|
||||
"quote",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "ipnet"
|
||||
version = "2.12.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0"
|
||||
|
||||
[[package]]
|
||||
name = "is_terminal_polyfill"
|
||||
version = "1.70.2"
|
||||
@@ -1022,22 +1071,34 @@ version = "0.4.33"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "lru-slab"
|
||||
version = "0.1.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "0.3.5"
|
||||
version = "0.3.7"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
"chrono",
|
||||
"clap",
|
||||
"futures-util",
|
||||
"getrandom 0.2.17",
|
||||
"hmac 0.12.1",
|
||||
"idna_adapter",
|
||||
"include_dir",
|
||||
"libc",
|
||||
"libloading",
|
||||
"md-5 0.10.6",
|
||||
"predicates",
|
||||
"pulldown-cmark",
|
||||
"regex",
|
||||
"serde_json",
|
||||
"sha1",
|
||||
"sha2 0.10.9",
|
||||
"thiserror 1.0.69",
|
||||
"tiny_http",
|
||||
"tokio",
|
||||
@@ -1049,7 +1110,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "0.3.5"
|
||||
version = "0.3.7"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
@@ -1070,6 +1131,14 @@ dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_linalg"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"serde",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_quantum"
|
||||
version = "0.1.0"
|
||||
@@ -1084,6 +1153,7 @@ version = "0.1.0"
|
||||
dependencies = [
|
||||
"argon2",
|
||||
"axum",
|
||||
"bytes",
|
||||
"futures-util",
|
||||
"getrandom 0.2.17",
|
||||
"hex",
|
||||
@@ -1091,6 +1161,7 @@ dependencies = [
|
||||
"postgres",
|
||||
"pulldown-cmark",
|
||||
"redis",
|
||||
"reqwest",
|
||||
"rusqlite",
|
||||
"serde",
|
||||
"serde_json",
|
||||
@@ -1107,6 +1178,16 @@ version = "0.8.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
|
||||
|
||||
[[package]]
|
||||
name = "md-5"
|
||||
version = "0.10.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"digest 0.10.7",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "md-5"
|
||||
version = "0.11.0"
|
||||
@@ -1337,7 +1418,7 @@ dependencies = [
|
||||
"bytes",
|
||||
"fallible-iterator 0.2.0",
|
||||
"hmac 0.13.0",
|
||||
"md-5",
|
||||
"md-5 0.11.0",
|
||||
"memchr",
|
||||
"rand 0.10.2",
|
||||
"sha2 0.11.0",
|
||||
@@ -1424,6 +1505,62 @@ version = "0.11.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
|
||||
|
||||
[[package]]
|
||||
name = "quinn"
|
||||
version = "0.11.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0c1a41e437b6bbd489372cd4971de128e85c855f56c57f283d20ff016cf7c0a8"
|
||||
dependencies = [
|
||||
"bytes",
|
||||
"cfg_aliases",
|
||||
"pin-project-lite",
|
||||
"quinn-proto",
|
||||
"quinn-udp",
|
||||
"rustc-hash",
|
||||
"rustls 0.23.44",
|
||||
"socket2 0.6.5",
|
||||
"thiserror 2.0.20",
|
||||
"tokio",
|
||||
"tracing",
|
||||
"web-time",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "quinn-proto"
|
||||
version = "0.11.17"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "04759210543be93709136e28212294a659ef5001836ff4eab4d663e4529bba83"
|
||||
dependencies = [
|
||||
"bytes",
|
||||
"getrandom 0.4.3",
|
||||
"lru-slab",
|
||||
"rand 0.10.2",
|
||||
"rand_pcg",
|
||||
"ring",
|
||||
"rustc-hash",
|
||||
"rustls 0.23.44",
|
||||
"rustls-pki-types",
|
||||
"slab",
|
||||
"thiserror 2.0.20",
|
||||
"tinyvec",
|
||||
"tracing",
|
||||
"web-time",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "quinn-udp"
|
||||
version = "0.5.15"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694"
|
||||
dependencies = [
|
||||
"cfg_aliases",
|
||||
"libc",
|
||||
"once_cell",
|
||||
"socket2 0.6.5",
|
||||
"tracing",
|
||||
"windows-sys 0.61.2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "quote"
|
||||
version = "1.0.47"
|
||||
@@ -1521,6 +1658,15 @@ version = "0.10.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
|
||||
|
||||
[[package]]
|
||||
name = "rand_pcg"
|
||||
version = "0.10.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "caa0f4137e1c0a72f4c651489402276c8e8e1cf081f3b0ba156d2cbeef09e86a"
|
||||
dependencies = [
|
||||
"rand_core 0.10.1",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "redis"
|
||||
version = "0.27.6"
|
||||
@@ -1577,6 +1723,47 @@ version = "0.8.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
|
||||
|
||||
[[package]]
|
||||
name = "reqwest"
|
||||
version = "0.12.28"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
|
||||
dependencies = [
|
||||
"base64",
|
||||
"bytes",
|
||||
"futures-core",
|
||||
"futures-util",
|
||||
"http",
|
||||
"http-body",
|
||||
"http-body-util",
|
||||
"hyper",
|
||||
"hyper-rustls",
|
||||
"hyper-util",
|
||||
"js-sys",
|
||||
"log",
|
||||
"percent-encoding",
|
||||
"pin-project-lite",
|
||||
"quinn",
|
||||
"rustls 0.23.44",
|
||||
"rustls-pki-types",
|
||||
"serde",
|
||||
"serde_json",
|
||||
"serde_urlencoded",
|
||||
"sync_wrapper",
|
||||
"tokio",
|
||||
"tokio-rustls",
|
||||
"tokio-util",
|
||||
"tower",
|
||||
"tower-http",
|
||||
"tower-service",
|
||||
"url",
|
||||
"wasm-bindgen",
|
||||
"wasm-bindgen-futures",
|
||||
"wasm-streams",
|
||||
"web-sys",
|
||||
"webpki-roots 1.0.9",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "ring"
|
||||
version = "0.17.14"
|
||||
@@ -1605,6 +1792,12 @@ dependencies = [
|
||||
"smallvec",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustc-hash"
|
||||
version = "2.1.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
|
||||
|
||||
[[package]]
|
||||
name = "rustls"
|
||||
version = "0.22.4"
|
||||
@@ -1614,7 +1807,21 @@ dependencies = [
|
||||
"log",
|
||||
"ring",
|
||||
"rustls-pki-types",
|
||||
"rustls-webpki",
|
||||
"rustls-webpki 0.102.8",
|
||||
"subtle",
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustls"
|
||||
version = "0.23.44"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "6725596c3f2c3a0aef021139e145d4eafe314a6623e4680ca83852b2c67ab2ba"
|
||||
dependencies = [
|
||||
"once_cell",
|
||||
"ring",
|
||||
"rustls-pki-types",
|
||||
"rustls-webpki 0.103.15",
|
||||
"subtle",
|
||||
"zeroize",
|
||||
]
|
||||
@@ -1625,6 +1832,7 @@ version = "1.15.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
|
||||
dependencies = [
|
||||
"web-time",
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
@@ -1639,6 +1847,17 @@ dependencies = [
|
||||
"untrusted",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustls-webpki"
|
||||
version = "0.103.15"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f3c3cf1d8b1e7d4927e2d154c3fcb02979afb9939629c62cd9048d4f07b60ac2"
|
||||
dependencies = [
|
||||
"ring",
|
||||
"rustls-pki-types",
|
||||
"untrusted",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustversion"
|
||||
version = "1.0.23"
|
||||
@@ -1725,9 +1944,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "sha1"
|
||||
version = "0.10.7"
|
||||
version = "0.10.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8"
|
||||
checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"cpufeatures 0.2.17",
|
||||
@@ -1878,6 +2097,9 @@ name = "sync_wrapper"
|
||||
version = "1.0.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
|
||||
dependencies = [
|
||||
"futures-core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "termtree"
|
||||
@@ -2005,6 +2227,16 @@ dependencies = [
|
||||
"whoami",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tokio-rustls"
|
||||
version = "0.26.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b0c85f2c3ef0b1cd58b36682f4b17aaa995f0e5db534d85692b4903abce21f67"
|
||||
dependencies = [
|
||||
"rustls 0.23.44",
|
||||
"tokio",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tokio-tungstenite"
|
||||
version = "0.24.0"
|
||||
@@ -2081,9 +2313,11 @@ dependencies = [
|
||||
"pin-project-lite",
|
||||
"tokio",
|
||||
"tokio-util",
|
||||
"tower",
|
||||
"tower-layer",
|
||||
"tower-service",
|
||||
"tracing",
|
||||
"url",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -2118,6 +2352,12 @@ dependencies = [
|
||||
"once_cell",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "try-lock"
|
||||
version = "0.2.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
|
||||
|
||||
[[package]]
|
||||
name = "tungstenite"
|
||||
version = "0.24.0"
|
||||
@@ -2219,9 +2459,9 @@ dependencies = [
|
||||
"flate2",
|
||||
"log",
|
||||
"once_cell",
|
||||
"rustls",
|
||||
"rustls 0.22.4",
|
||||
"rustls-pki-types",
|
||||
"rustls-webpki",
|
||||
"rustls-webpki 0.102.8",
|
||||
"url",
|
||||
"webpki-roots 0.26.11",
|
||||
]
|
||||
@@ -2277,6 +2517,15 @@ dependencies = [
|
||||
"libc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "want"
|
||||
version = "0.3.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
|
||||
dependencies = [
|
||||
"try-lock",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasi"
|
||||
version = "0.11.1+wasi-snapshot-preview1"
|
||||
@@ -2323,6 +2572,16 @@ dependencies = [
|
||||
"wasm-bindgen-shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-futures"
|
||||
version = "0.4.77"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "6b7777d5cc23d0e91404e53ce2d5e8ec7acae3026b16233dba62cd3246457950"
|
||||
dependencies = [
|
||||
"js-sys",
|
||||
"wasm-bindgen",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro"
|
||||
version = "0.2.127"
|
||||
@@ -2355,6 +2614,19 @@ dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-streams"
|
||||
version = "0.4.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65"
|
||||
dependencies = [
|
||||
"futures-util",
|
||||
"js-sys",
|
||||
"wasm-bindgen",
|
||||
"wasm-bindgen-futures",
|
||||
"web-sys",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "web-sys"
|
||||
version = "0.3.104"
|
||||
@@ -2365,6 +2637,16 @@ dependencies = [
|
||||
"wasm-bindgen",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "web-time"
|
||||
version = "1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
|
||||
dependencies = [
|
||||
"js-sys",
|
||||
"wasm-bindgen",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "webpki-roots"
|
||||
version = "0.26.11"
|
||||
|
||||
+9
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.3.5"
|
||||
version = "0.3.7"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -32,6 +32,13 @@ pulldown-cmark = "0.12"
|
||||
serde_json = "1"
|
||||
thiserror = "1"
|
||||
tiny_http = { version = "0.12", optional = true }
|
||||
sha2 = { version = "=0.10.9", default-features = false }
|
||||
sha1 = { version = "=0.10.6", default-features = false }
|
||||
md-5 = { version = "=0.10.6", default-features = false }
|
||||
hmac = { version = "=0.12.1", default-features = false }
|
||||
getrandom = { version = "=0.2.17", default-features = false, features = ["std"] }
|
||||
# Mid M1: Unicode regex for lib/re (no backrefs; RE2-like).
|
||||
regex = { version = "=1.13.1", default-features = false, features = ["std", "unicode"] }
|
||||
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"], optional = true }
|
||||
idna_adapter = { version = "=1.1.0", optional = true }
|
||||
@@ -52,6 +59,7 @@ members = [
|
||||
"plugins/agent",
|
||||
"plugins/web",
|
||||
"plugins/quantum",
|
||||
"plugins/linalg",
|
||||
"crates/marqdo-wasm",
|
||||
]
|
||||
resolver = "2"
|
||||
|
||||
@@ -99,7 +99,7 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.3.5)
|
||||
## 现状(v0.3.7)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
@@ -107,25 +107,26 @@ marqdo catalog public -o .marqdo
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
|
||||
- **`marqdo version --check`**:与 GitHub 最新 release 对比
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6**(`re`/`encoding`/`path`/`hash`/`secrets`/`csv`/`cli`/`log`/`uuid` 及中英对称库,见 [stdlib-mid.md](doc/design/stdlib-mid.md))
|
||||
- **官方扩展库 `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)
|
||||
- **`web`**:W0–W7 + P3 + **W8**;**定制 C0–C4**;**宿主 H1–H2**(`proxy`/`invoke`,见 [ext-hosting.md](doc/roadmap/ext-hosting.md));示例 [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/)
|
||||
- **`agent`**:A1–A4(OKF 复用、过程事件、上下文预算、RAG/MCP fixture);下一波缺口 [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
|
||||
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
|
||||
- **`agent`**:A1–A4 + **MCP Server stdio**(`mcp_server`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [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))
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
|
||||
|
||||
### 如何使用最新 Marqdo(v0.3.5)
|
||||
### 如何使用最新 Marqdo(v0.3.7)
|
||||
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v0.3.5 # 或留在 main
|
||||
git checkout v0.3.7 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -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
|
||||
@@ -155,7 +157,7 @@ marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v0.3.5
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v0.3.7
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "0.3.5"
|
||||
version = "0.3.7"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
@@ -71,6 +71,9 @@
|
||||
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
|
||||
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
|
||||
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
|
||||
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
|
||||
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
@@ -82,6 +82,9 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
| **regex** (=1.13.1) | 正则 | Mid M1 `lib/re`;`default-features=false` + `std`/`unicode`;无回溯引用 |
|
||||
| **sha2** (=0.10.9) / **sha1** (=0.10.6) / **md-5** (=0.10.6) / **hmac** (=0.12.1) | 摘要 | Mid M3 `lib/hash` |
|
||||
| **getrandom** (=0.2.17) | OS 熵 | Mid M3 `lib/secrets` |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
|
||||
@@ -0,0 +1,306 @@
|
||||
# 设计:宿主集成缺口补齐(`ext/web` · `ext/ai`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · H1–H4 stdio 已落地**(H4b HTTP 可选) |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 缺口盘点 | [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) |
|
||||
| 路线图 | [ext-hosting.md](../roadmap/ext-hosting.md) |
|
||||
| 边界 | [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) |
|
||||
| 目标 | 用**扩展库一等 API**关闭 GAP-01–05,取代下游 Python 旁路 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**服务器中继与「请求→`##`」进 `ext/web`;MCP Server 与 corpus 可发现进 `ext/ai`;标准库只保留已有客户端 SSE。** 作者用 GFM 表声明路由/工具,不写 JS、不启第二语言运行时。
|
||||
|
||||
---
|
||||
|
||||
## 1. 分层与禁止项
|
||||
|
||||
| 层 | 职责 | 落点 |
|
||||
|----|------|------|
|
||||
| 作者面 | 声明路径、上游、函数名、工具表 | `ext/web/web.mq.md` · `ext/ai/agent.mq.md`(+ 中文对偶) |
|
||||
| ABI | axum 流式代理、每请求 interp 调用、MCP 传输 | `plugins/web` · `plugins/agent` |
|
||||
| 标准库 | 不变:缓冲客户端 SSE / 解析 | `lib/net`(**不**加中继) |
|
||||
| 核心 host | **禁止**新增 agent/web 领域 `host_*` | 见 Skill 硬规则 9 |
|
||||
|
||||
**禁止:**
|
||||
|
||||
1. 为中继在浏览器手写业务 JS。
|
||||
2. `json=` 继续塞「任意 `##`」语义(保持 DB-only;新能力用独立装配名)。
|
||||
3. MCP Server 把向量库升为权威真相(工具结果可带 `authority=workbook`)。
|
||||
4. 无白名单的「任意文件系统路径 + 任意 `##`」远程触发。
|
||||
|
||||
---
|
||||
|
||||
## 2. GAP-01 · `app.proxy` 流式反向代理
|
||||
|
||||
### 2.1 作者 API
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.proxy path="/v1/chat/completions" upstream=$OPENAI_BASE_URL*
|
||||
*应用 = > `应用`.proxy path="/llm/stream" upstream="https://api.example.com" strip_prefix="/llm" stream=True*
|
||||
```
|
||||
|
||||
或装配表(一次挂多条):
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.configure proxy=`代理表`*
|
||||
|
||||
| path | upstream | stream | strip_prefix | headers_from_env |
|
||||
|------|----------|--------|--------------|------------------|
|
||||
| /proxy/chat | $OPENAI_BASE_URL | True | | OPENAI_API_KEY=Authorization |
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 含义 |
|
||||
|------|------|------|
|
||||
| `path` | 必填 | 浏览器同域路径 |
|
||||
| `upstream` | 必填 | 上游根或完整 URL;支持 `$ENV` |
|
||||
| `stream` | `True` | `True`:响应按上游 `Content-Type` 管道转发(含 `text/event-stream`) |
|
||||
| `strip_prefix` | 空 | 转发前去掉本站前缀 |
|
||||
| `methods` | `POST` | 允许方法 |
|
||||
| `headers_from_env` | 空 | `ENV=Header-Name` 注入(密钥不进前端) |
|
||||
| `timeout_ms` | 插件默认 | 上游超时 |
|
||||
|
||||
中文:`## 代理` / `流式=` / `上游=` / `去前缀=`。
|
||||
|
||||
### 2.2 ABI / 插件行为
|
||||
|
||||
| 步骤 | 行为 |
|
||||
|------|------|
|
||||
| 注册 | `web_app_proxy` 写入 `AppState` 路由表 |
|
||||
| 请求 | 读 body + 过滤危险 hop-by-hop 头;合并 env 注入头 |
|
||||
| 上游 | `reqwest`/`hyper` 流式客户端(插件内,不进核心) |
|
||||
| 响应 | 复制状态码与 `content-type`;`body` 为 stream;SSE 不整段缓冲 |
|
||||
| CORS | 仍走既有 `configure cors=`(同域调用时浏览器不依赖上游 CORS) |
|
||||
|
||||
### 2.3 与 `lib/net.http_post_sse` 关系
|
||||
|
||||
| API | 角色 |
|
||||
|-----|------|
|
||||
| `http_post_sse` | **出站消费者**(CLI/agent 侧收齐 events) |
|
||||
| `app.proxy` | **入站中继**(浏览器 ← Marqdo ← 上游) |
|
||||
|
||||
二者互补,不互相替代。
|
||||
|
||||
### 2.4 验收
|
||||
|
||||
- 金样:mock 上游发两帧 SSE,浏览器侧(或 `curl -N`)收到两帧且中间无全缓冲延迟门槛。
|
||||
- 密钥仅出现在服务端 env 注入头。
|
||||
- 金样名建议:`tests/ext/web-proxy-sse-smoke.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. GAP-02 · `app.invoke` / `configure invoke=`(HTTP → `##`)
|
||||
|
||||
### 3.1 作者 API
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.invoke path="/api/沉淀" method=POST fn="run.沉淀"*
|
||||
```
|
||||
|
||||
表形式:
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.configure invoke=`调用表`*
|
||||
|
||||
| path | method | fn | body | return |
|
||||
|------|--------|-----|------|--------|
|
||||
| /api/note | POST | run.写出 | json | json |
|
||||
| /api/search | GET | db.recent | query | json |
|
||||
```
|
||||
|
||||
| 列 / 参数 | 含义 |
|
||||
|-----------|------|
|
||||
| `path` / `method` | HTTP 路由 |
|
||||
| `fn` | `库.成员`(入口模块已 `import`)或 `模块路径##标题`(白名单前缀内) |
|
||||
| `body` | `json` \| `form` \| `query` \| `raw` → 映射到 `##` 形参(同名优先;其余进 `payload` 袋) |
|
||||
| `return` | `json`(默认)\| `text` \| `status` |
|
||||
|
||||
中文:`## 调用` / `函数=` / `正文=` / `返回=`。
|
||||
|
||||
### 3.2 安全默认(锁定)
|
||||
|
||||
1. **仅**解析入口 workbook 已导入的 `bind` 路径,或 `invoke_allow=` 显式前缀列表。
|
||||
2. 单请求超时 + 可选并发上限(防 listen 线程饿死)。
|
||||
3. 默认不启;作者显式 `invoke` / `configure invoke=`。
|
||||
4. 错误:`{ok:false, error}` + HTTP 4xx/5xx;不把内部路径栈默认回传生产模式。
|
||||
|
||||
### 3.3 ABI / 插件行为
|
||||
|
||||
| 步骤 | 行为 |
|
||||
|------|------|
|
||||
| 注册 | `web_app_invoke` 存 `(path, method, FnRef)` |
|
||||
| 命中 | 解析 body → Value 袋;`call_lib_path` / 等价「同步调用已加载模块的 `##`」 |
|
||||
| 返回 | Value → JSON(复用现有 host JSON 通路);侧效(写盘)在同一解释器事务语义内尽最大努力 |
|
||||
|
||||
**不**把 `json=` DB 路由改语义;`invoke` 是平行装配。
|
||||
|
||||
### 3.4 与 compose 期 `call_lib_path` 关系
|
||||
|
||||
| 时机 | API |
|
||||
|------|-----|
|
||||
| 装配页 | 现有 compose / `call_lib_path` |
|
||||
| **每个 HTTP 请求** | 本设计 `invoke` |
|
||||
|
||||
### 3.5 验收
|
||||
|
||||
- `POST` JSON → 用户 `##` 写入临时文件 + 返回 `{ok:true,…}`。
|
||||
- 未导入路径 → 4xx,不执行。
|
||||
- 金样:`tests/ext/web-invoke-smoke.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 4. GAP-03 · MCP Server(`ext/ai`)
|
||||
|
||||
### 4.1 作者 API
|
||||
|
||||
```markdown
|
||||
*服务 = > agent.mcp_server name="marqdo-qd"*
|
||||
*服务 = > `服务`.tool name="qd_search" fn="求道.搜索" description="关键词检索"*
|
||||
*服务 = > `服务`.tool name="qd_capture" fn="求道.捕捉"*
|
||||
*服务 = > `服务`.serve transport=stdio*
|
||||
# 或
|
||||
*服务 = > `服务`.serve transport=http host=127.0.0.1 port=7433*
|
||||
```
|
||||
|
||||
工具表:
|
||||
|
||||
| name | fn | description |
|
||||
|------|-----|-------------|
|
||||
| qd_search | 求道.搜索 | … |
|
||||
| qd_list | 求道.列出 | … |
|
||||
|
||||
### 4.2 传输
|
||||
|
||||
| transport | 用途 |
|
||||
|-----------|------|
|
||||
| `stdio` | Cursor / Claude Desktop 拉起 |
|
||||
| `http` | Streamable HTTP(与官方 MCP 演进对齐;首版可先 SSE+POST 子集) |
|
||||
|
||||
### 4.3 与 A4 fixture 客户端关系
|
||||
|
||||
| API | 方向 |
|
||||
|-----|------|
|
||||
| `mcp_list_tools` / `mcp_call` | **出站**(Agent 调外部 MCP;现 fixture) |
|
||||
| `mcp_server` + `serve` | **入站**(外部调 Marqdo) |
|
||||
|
||||
客户端「真 MCP」仍见 agent 缺口文;本设计先交 Server,fixture 可保留测客户端。
|
||||
|
||||
### 4.4 ABI
|
||||
|
||||
- `plugins/agent`:`agent_mcp_server_*`(注册工具、stdio loop、可选 HTTP)。
|
||||
- 工具实现:复用 GAP-02 同款「调用 `##`」内核(可抽共享 `invoke_fn`),避免两套分发。
|
||||
- 返回包装:可含 `authority=workbook`。
|
||||
|
||||
### 4.5 验收
|
||||
|
||||
- 金样:stdio 夹具发 `tools/list` + `tools/call`,断言 JSON-RPC 形结果。
|
||||
- 可选:`tests/ext/agent-mcp-server-smoke.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 5. GAP-04 · 同寿副端口
|
||||
|
||||
### 5.1 关闭策略(优先)
|
||||
|
||||
GAP-01 + GAP-02 挂在**同一** `app.listen` → **不实现副端口**,文档宣布 GAP-04 关闭。
|
||||
|
||||
### 5.2 备选 API(仅当必须隔离)
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.listen host=127.0.0.1 port=18081 also_port=7432 also_routes=`中继表`*
|
||||
```
|
||||
|
||||
`also_routes` 仅允许 `proxy` / `invoke` 已注册子集。实现成本高,**默认不做**。
|
||||
|
||||
---
|
||||
|
||||
## 6. GAP-05 · 跨模块 `db` 与 corpus 可发现
|
||||
|
||||
### 6.1 `db` 句柄(扩展约定 + 运行时)
|
||||
|
||||
**作者约定(立即文档化):**
|
||||
|
||||
1. 跨模块优先传 **`url` 字符串**,调用方 `*store = > web.db url=…*` 再 `select`。
|
||||
2. 若传对象:必须保留 `_type` 为插件注册名(与 `web.db` 构造一致)。
|
||||
|
||||
**运行时修补(H 波次):**
|
||||
|
||||
| 选项 | 做法 | 选用 |
|
||||
|------|------|------|
|
||||
| A | 跨模块返回插件对象时规范 `_type` + 全局方法表查找 | **首选**(一次修好所有插件对象) |
|
||||
| B | `db.open` 只返回 `{url}` 朴素 map,禁止「裸 select」跨文件 | 文档契约;体验较差 |
|
||||
|
||||
金样:模块 A `open` → 返回 → 模块 B `select` 成功。
|
||||
`tests/ext/web-db-cross-module-smoke.mq.md`。
|
||||
|
||||
### 6.2 `corpus_search` 可发现
|
||||
|
||||
```markdown
|
||||
## corpus_search
|
||||
+ `query`
|
||||
+ `root`=".marqdo/agent-kb"
|
||||
|
||||
* > plugin.load name=agent *
|
||||
** > agent_corpus_search query=`query` root=`root` **
|
||||
```
|
||||
|
||||
或在 `# agent` / `## corpus_search` 入口统一 `ensure_plugin`(与现 `agent` 构造对齐),保证 **纯 `marqdo run` + import agent** 即可用。
|
||||
|
||||
**不**把 `agent_corpus_search` 搬进 `src/host/`。
|
||||
|
||||
### 6.3 验收
|
||||
|
||||
- 无显式手工 ABI 名的情况下,`marqdo run` 金样调用 `agent.corpus_search` 成功。
|
||||
- 跨模块 `db.select` 金样绿。
|
||||
|
||||
---
|
||||
|
||||
## 7. 扩展库表面清单(落地时改这些文件)
|
||||
|
||||
| 文件 | 增补 |
|
||||
|------|------|
|
||||
| `ext/web/web.mq.md` · `网页.mq.md` | `## proxy` / `## invoke`;`configure` 增 `proxy`/`invoke` 列 |
|
||||
| `plugins/web/src/http.rs` · `middleware.rs` · 新 `proxy.rs` / `invoke.rs` | 路由注册与流式/调用 |
|
||||
| `ext/ai/agent.mq.md` · `智能体.mq.md` | `# mcp_server` · `## tool` · `## serve`;`corpus_search` ensure_plugin |
|
||||
| `plugins/agent/` | MCP Server 传输 + 共享 invoke |
|
||||
| `tests/ext/web-proxy-sse-smoke.mq.md` 等 | 见上 |
|
||||
| `doc/roadmap/ext-web.md` | 链到 H 波次(不重开 W0–W7) |
|
||||
| `public/` / Skill | 发版时补「同域 LLM 代理 / HTTP 调用 ##」短节 |
|
||||
|
||||
**不**新增 `lib/run` 作为核心依赖:用户业务 `##` 仍在其自己的 `lib/*.mq.md`;Marqdo 只提供 **invoke 管道**。
|
||||
|
||||
---
|
||||
|
||||
## 8. 迁移:下游旁路 → 扩展 API
|
||||
|
||||
| 旁路(下游) | 替换为 |
|
||||
|--------------|--------|
|
||||
| `llm_proxy.py` `/proxy/stream` | `app.proxy` / `configure proxy=` |
|
||||
| `llm_proxy.py` `/store/*` + `marqdo run` | `app.invoke` → 用户 `##` |
|
||||
| `mq_bridge.py` 仅过滤 | 用户 `##` 内 `table`/`re` 过滤,或修复后的 `corpus_search` |
|
||||
| `qdagent_mcp.py` | `agent.mcp_server` + `serve` |
|
||||
| `mq.sh` 双进程 | 单 `marqdo run index.mq.md`(proxy+invoke 同端口) |
|
||||
|
||||
---
|
||||
|
||||
## 9. 开放点(实现前拍板)
|
||||
|
||||
| # | 问题 | 默认倾向 |
|
||||
|---|------|----------|
|
||||
| 1 | `invoke` 的 `fn` 是否允许 `path.mq.md##标题` 字面量 | 允许但必须 `invoke_allow` 前缀 |
|
||||
| 2 | MCP HTTP 首版范围 | stdio 先交;HTTP 跟一波 |
|
||||
| 3 | 代理是否缓冲「非 SSE」大 body | 非流式可限长缓冲;SSE 禁止整段缓冲 |
|
||||
| 4 | GAP-05 选项 A vs B | **A** |
|
||||
|
||||
---
|
||||
|
||||
## 10. 完成定义(整包)
|
||||
|
||||
1. 无 Python 旁路即可:浏览器同域 SSE 对话 + HTTP 触发沉淀 `##` +(可选)MCP stdio 暴露同一批 `##`。
|
||||
2. 金样覆盖 proxy / invoke / cross-db / corpus / mcp-server(stdio)。
|
||||
3. `doc/research/ext-hosting-gaps.md` 各 GAP 标为关闭或降级为「备选副端口不做」。
|
||||
4. 发版说明指向 `ext/web` · `ext/ai` 新作者面,不指向 `scripts/*.py`。
|
||||
@@ -0,0 +1,235 @@
|
||||
# `ext/linalg` — 公式文档面(跑通即正确)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Draft · 锁定作者面哲学与分期** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 父设计 | [ext-linalg.md](ext-linalg.md) |
|
||||
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
|
||||
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
|
||||
| 对照 | [stdlib-math.md](stdlib-math.md)(高中标量公式) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**`.mq.md` 里的线性代数应当读起来像一份可运行的公式讲义**:式子能跑通,就在库承诺的规则与维数下代表正确;`lib/math` 守高中边界,大学符号矩阵与更深层计算由 **`ext/linalg` 正当承担**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 产品哲学
|
||||
|
||||
### 1.1 与 Marqdo 总原则对齐
|
||||
|
||||
| Marqdo | 在线性代数上的含义 |
|
||||
|--------|-------------------|
|
||||
| 代码即文档 | 矩阵代数段落用数学式书写,而不是 API 调用清单 |
|
||||
| 标记即语法 | `$$`、中缀、`# matrix` 方法都是可读标记,不是「库胶水」 |
|
||||
| 跑通可验收 | 金样 / 课堂作业:文件 exit 0 + 断言化简结果 = 式子合法 |
|
||||
|
||||
### 1.2 「跑通即正确」的精确定义
|
||||
|
||||
**不是**「任意高深定理自动证明」。
|
||||
**是**在声明的能力边界内,下列任一成立则文档该段视为正确:
|
||||
|
||||
1. **形状层**:不相容维数的乘加在构造时硬错误(写不出可运行的坏式)。
|
||||
2. **恒等式层**:文档断言的规范形(如 `(AB)^\top → B^\top A^\top`)经规则集得到。
|
||||
3. **数值核对层**(可选):小 `$$` 数值阵 `explicit` 后与手算一致——验算,不是符号证明。
|
||||
|
||||
更高深主题(矩阵微积分、表示、特殊函数矩阵等)通过**扩展同一公式面的规则表**分期加入,而不是另起一套函数库叙事。
|
||||
|
||||
### 1.3 与 `lib/math` 的边界(再次锁定)
|
||||
|
||||
| | `lib/math` | `ext/linalg` |
|
||||
|--|------------|--------------|
|
||||
| 教育边界 | 高中标量公式 | 大学经典线性代数及更深(官方 ext) |
|
||||
| 值类型 | `Value::Formula`(标量 AST) | `_type=matrix` / `矩阵`(MatExpr + 稠密) |
|
||||
| 作者感觉 | `$$sin(x)+x$$` + `diff` / `plot` | `A*B`、`(AB)^T`、分块、分解图 |
|
||||
| 是否「数学库」 | 是(stdlib) | **是数学库的官方扩展**,不是旁路工具箱 |
|
||||
|
||||
把大学 LA 塞进 `lib/math` ❌;在 `ext/linalg` 做大学符号计算乃至更深 ✅。
|
||||
|
||||
---
|
||||
|
||||
## 2. 两面模型:代数面 vs 计算面
|
||||
|
||||
文档里应能一眼分清「推导」与「动手算」。
|
||||
|
||||
### 2.1 代数面(默认;公式文档)
|
||||
|
||||
| 意图 | 写法(目标) | 语义 |
|
||||
|------|--------------|------|
|
||||
| 引入符号阵 | 见 §3 | 惰性 `MatrixSymbol` |
|
||||
| 加减乘 | `` `C` = `A` + `B` `` · `` `P` = `A` * `B` `` | 建树 + 形状检查 |
|
||||
| 转置 / 逆 | `` `At` = > `A`.T `` · `` `Ai` = > `A`.inv `` | 惰性节点 |
|
||||
| 化简 / 展示 | 见 §4(默认化简策略) | 规则不动点 → ASCII / KaTeX |
|
||||
| 分块 / Kronecker | 表或 `block` / `kron`(可保留具名,但结果仍是公式) | 惰性 |
|
||||
|
||||
**读者感受**:像在抄黑板,而不是在调 `la.mul`。
|
||||
|
||||
### 2.2 计算面(显式步骤;可单独成段)
|
||||
|
||||
| 意图 | 写法 | 语义 |
|
||||
|------|------|------|
|
||||
| 稠密求值 | `` `E` = > `A`.explicit `` / `la.explicit` | 展开数值 |
|
||||
| 分解 | `` `f` = > la.factorize matrix=`A` kind="svd" `` | `linalg_factor` |
|
||||
| 求解 / 最小二乘 | `solve` / `lstsq` | 数值解 |
|
||||
| 度量 | `norm` / `cond` / `rank` / `det`(数值路径) | 标量或条件对象 |
|
||||
| 作图 | `draw` / `show` | SVG / 公式卡 |
|
||||
|
||||
**读者感受**:「于是我们计算 / 画出…」——与纯代数叙述分段书写。
|
||||
|
||||
---
|
||||
|
||||
## 3. 目标作者语法(公式文档优先)
|
||||
|
||||
### 3.1 已落地(v1 中缀 / 方法)
|
||||
|
||||
```markdown
|
||||
*`A` = > la.symbol name="A" rows=2 cols=2*
|
||||
*`B` = > la.symbol name="B" rows=2 cols=2*
|
||||
*`C` = `A` + `B`*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`s` = > `Pt`.simplify*
|
||||
*`t` = > `s`.ascii*
|
||||
```
|
||||
|
||||
数值 `$$` 矩阵可直接参与 `+` / `*`(经插件吸收为稠密叶)。
|
||||
|
||||
### 3.2 目标形态(文档感更强;分期实现)
|
||||
|
||||
**叙事理想(不必一次做完):**
|
||||
|
||||
```markdown
|
||||
# 正规方程
|
||||
|
||||
令 \(A\) 为 \(m\times n\) 设计矩阵,\(b\) 为观测。
|
||||
|
||||
*`AtA` = > `A`.T * `A`* # 或未来更紧凑的 postfix / 混合写法
|
||||
*`xty` = > `A`.T * `b`*
|
||||
*`xhat` = > `AtA`.solve b=`xty`* # 计算面
|
||||
```
|
||||
|
||||
**符号引入(减少 `la.symbol` 噪音)——候选(F2 选定一种):**
|
||||
|
||||
| 候选 | 例 | 利 | 弊 |
|
||||
|------|----|----|-----|
|
||||
| A. 构造糖 | `` `A` = > la.matrix name=A rows=m cols=n `` | 已有 `# matrix` | 仍是调用 |
|
||||
| B. 维数表 | GFM 表声明符号与形状,一行绑定 | 很「文档」 | 需新约定 |
|
||||
| C. `$$` 符号方言 | `$$A_{m\times n}$$` → MatExpr | 最像讲义 | 解析歧义;勿污染标量 formula |
|
||||
| D. 保持 `symbol` + 短别名 | `` `A` = > la.A rows=m cols=n `` | 实现便宜 | 文档感一般 |
|
||||
|
||||
**锁定倾向:** 短期 **A + 默认化简(F1)**;**F2 采用 B(GFM `@` 表 + `la.declare`)**;受限 C(`$$` 符号方言)仍待评估且不得污染核心 formula。
|
||||
|
||||
### 3.3 明确不做(本波语法)
|
||||
|
||||
- 把符号 MatExpr 塞进核心 `formula::Expr`
|
||||
- 发明与 Markdown 列表冲突的行首 `+` 矩阵语法
|
||||
- 用未定义的 `$$矩阵A$$` 伪方言冒充已实现语义
|
||||
|
||||
---
|
||||
|
||||
## 4. 默认化简与「写出即规范」
|
||||
|
||||
### 4.1 策略
|
||||
|
||||
| 操作 | 是否自动 `simplify` | 理由 |
|
||||
|------|---------------------|------|
|
||||
| `ascii` / `latex` / `show` | **是(F1 done)** | 展示面应接近讲义规范形;`raw=True` 可关 |
|
||||
| 中缀 `+` `*` `-` 的构造结果 | **否** | 保留用户书写结构;需要时再化简 |
|
||||
| `.simplify` | 显式不动点 | 文档断言 / 金样 |
|
||||
| `explicit` 前 | 可选先 simplify(F1.1) | 减少无效稠密路径 |
|
||||
|
||||
### 4.2 验收句式(金样)
|
||||
|
||||
```markdown
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`t` = > `Pt`.ascii* # F1:无需再 .simplify 即得 B^T*A^T
|
||||
1. `t` == "B^T*A^T"
|
||||
> print text=ok
|
||||
```
|
||||
|
||||
「跑通 + 断言」= 这段公式文档正确。
|
||||
|
||||
---
|
||||
|
||||
## 5. 正确性分层与错误体验
|
||||
|
||||
| 层 | 失败时 | 作者应看到 |
|
||||
|----|--------|------------|
|
||||
| 形状 | `A*B` 列行不配 | 含双方 shape 的硬错误,指向调用点 |
|
||||
| 规则 | 无法化到文档期望形 | 金样失败;或 `ascii` 仍为未化简形(需补规则) |
|
||||
| 插件未加载 | 中缀矩阵运算 | 提示 `ext add linalg` / `ensure_plugin` |
|
||||
| 超维 | `explicit` / 分解 | 护栏错误,建议保持符号 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 与实现现状的对照
|
||||
|
||||
| 能力 | 状态 |
|
||||
|------|------|
|
||||
| MatExpr 惰性树 + R1–R5 / 分块 / kron | done(L1–L3) |
|
||||
| 稠密 / 分解 / 度量 / draw theme | done(L2–L6) |
|
||||
| 中缀 `+` `-` `*` + `# matrix` 方法 | done(v1) |
|
||||
| `ascii`/`latex`/`show` 默认 simplify | **done(F1)** |
|
||||
| 更少噪音的符号引入 | **done(F2:`declare` + 表)** |
|
||||
| 更紧凑转置 / 混合公式书写 | **done(F3:`T_ascii`)** |
|
||||
| `explicit` 前可选 auto-simplify | **done(F3,默认开)** |
|
||||
| public「如何写公式文档」 | **done(F3)** |
|
||||
| 矩阵微积分等 | L7+ / 规则表扩展 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 分期(公式文档面)
|
||||
|
||||
| 阶段 | 内容 | 出口 |
|
||||
|------|------|------|
|
||||
| **F1** | 展示路径默认 simplify;金样「`.T` + `ascii` → 规范形」;设计本文落地 | **done** |
|
||||
| **F2** | 符号引入降噪(选定 §3.2 候选);更新 examples 使其读起来像讲义 | **done**(`declare` + `linalg-transpose`) |
|
||||
| **F3** | 可选 postfix / 链式糖;`explicit` 前可选 auto-simplify;public 短文「如何写公式文档」 | **done** |
|
||||
| **F4+** | 新规则(伴随、多项式矩阵…);矩阵微积分仅当明确需要 | 规则表可测 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 示例叙事(目标文档骨架)
|
||||
|
||||
````markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# 转置反序
|
||||
|
||||
*`A` = > la.symbol name="A" rows=2 cols=3*
|
||||
*`B` = > la.symbol name="B" rows=3 cols=2*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
|
||||
叙述:\((AB)^\top = B^\top A^\top\)。
|
||||
|
||||
*`t` = > `Pt`.ascii*
|
||||
1. `t` == "B^T*A^T"
|
||||
> print text=identity-ok
|
||||
2. *
|
||||
> print text=identity-fail
|
||||
````
|
||||
|
||||
计算面示例保持 `examples/linalg-least-squares/`(`lstsq` + heatmap),与代数面示例分目录或分章节。
|
||||
|
||||
---
|
||||
|
||||
## 9. 开放问题
|
||||
|
||||
1. **自动 simplify 是否改变 `ascii` 金样**——凡依赖「未化简乘积串」的测试需改期望或改调 `repr_raw`(若提供)。
|
||||
2. **中文 `_type=矩阵` 与展示**——方法链已 retag;view 是否统一显示英文 kind。
|
||||
3. **`$$` 符号方言**——若做,必须经 `from_formula` 扩展,禁止改核心高中 formula 语义。
|
||||
|
||||
---
|
||||
|
||||
## 10. 收束
|
||||
|
||||
`ext/linalg` 的北极星不是「功能最多的矩阵库」,而是:
|
||||
|
||||
> **让大学线性代数(及更深)以可运行公式文档的形式存在于 Marqdo;跑通即在规则集内正确;计算与作图是显式步骤,不淹没代数叙述。**
|
||||
@@ -0,0 +1,345 @@
|
||||
# `ext/linalg` — 公式优先的线性代数扩展
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Draft · L0–L6 + 中缀 v1 · 公式文档面见专文** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
|
||||
| **公式文档面** | [ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)(跑通即正确 · 代数面/计算面) |
|
||||
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [view.md](view.md) · [ext-quantum-q7.md](ext-quantum-q7.md) |
|
||||
| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**经典线性代数以「矩阵公式」为一等公民**:抽象表达式可化简、可展示、可选求值;稠密数值与分解图走 ABI 插件——**不**并入 `lib/math`,**不**挂在 `ext/quantum` 作者面。
|
||||
|
||||
作者面北极星见 **[ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)**:跑通即正确;代数面像讲义,计算面是显式步骤。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与非目标
|
||||
|
||||
### 1.1 目标
|
||||
|
||||
1. **公式类扩展**:在现有标量 `formula` 之上,引入 **矩阵表达式(MatExpr)**——`MatrixSymbol`、乘加、转置、逆、迹、行列式、分块、Kronecker——默认**不展开**。
|
||||
2. **大规模优化**:形状检查 + 重写规则 + 惰性求值 + 分解对象复用(见 §5)。
|
||||
3. **易于展示**:KaTeX 公式卡、结构 SVG(SVD/QR/消元/特征)、数值热力图;CLI 可断言的 ASCII。
|
||||
4. **文档即实验**:GFM 表声明矩阵 / 步骤;`.mq.md` 可读可跑。
|
||||
|
||||
### 1.2 非目标(首版)
|
||||
|
||||
| 不做 | 原因 |
|
||||
|------|------|
|
||||
| 塞进 `lib/math` | 高中标量范围已锁定;大学 LA 属官方 ext |
|
||||
| 复用 `quantum.*` 作者 API | 领域混淆;量子 Q7 保持量子语义 |
|
||||
| 完整 SymPy / Mathematica | 规则表可控子集即可 |
|
||||
| 稀疏格式 / GPU / 分布式 | 超出文档语言定位 |
|
||||
| 矩阵微积分闭式(Jacobian 积木) | 记入路线图远期 |
|
||||
| 在 `ext/**` 调 `host_*` | 硬约束;数值走插件名 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层架构
|
||||
|
||||
```text
|
||||
作者 .mq.md
|
||||
│ import la:ext/linalg/linalg.mq.md
|
||||
▼
|
||||
L1 官方 ext(GFM + ## 包装,中英分文件)
|
||||
│ plugin.load name=linalg
|
||||
▼
|
||||
plugins/linalg(ABI v2)
|
||||
├── matexpr:符号树构造 / 重写 / latex
|
||||
├── dense:稠密 f64(可选复数)运算与分解
|
||||
└── draw:结构 SVG / heatmap
|
||||
│
|
||||
▼(可选)
|
||||
核心 Value::Formula 仅保留「数值矩阵字面量」现状;
|
||||
符号 MatExpr 以 **map `_type=matrix`(中文构造为 `矩阵`)** 承载,避免撑爆高中 formula AST;遗留标签 `linalg_expr` / `linalg_dense` 仍可解析。
|
||||
```
|
||||
|
||||
### 2.1 为何 MatExpr 不直接塞进 `formula::Expr`
|
||||
|
||||
| 方案 | 利 | 弊 | 决策 |
|
||||
|------|----|----|------|
|
||||
| 扩展 `formula::Expr` | 与 `$$` 一体 | 核心膨胀;高中/大学边界糊 | ❌ |
|
||||
| 插件侧表达式 + L1 对象 | 核心干净;可独立发版 | 需稳定 `_type` 与 latex 桥 | ✅ **采用** |
|
||||
| 仅 list-of-list 数值 | 简单 | 无法公式优化与符号展示 | ❌ 仅作 `explicit` 结果 |
|
||||
|
||||
**既有** `formula::Expr::Matrix`(数值 `$$`)继续服务量子门 / 小例子;`ext/linalg` 通过 `la.matrix` / `la.from_formula` 吸收为稠密叶子。
|
||||
|
||||
### 2.2 与量子的边界
|
||||
|
||||
| | `ext/linalg` | `ext/quantum` Q7 |
|
||||
|--|--------------|------------------|
|
||||
| 域 | 经典实/复矩阵 | 态 / 密度 / Pauli |
|
||||
| Kronecker | 经典 ⊗ | 复合量子系统 |
|
||||
| 图 | SVD/QR/GE/heatmap | hinton/city/qsphere/… |
|
||||
| 复用 | 插件**私有**可共享 Jacobi/SVD 代码 | 作者面 API **分离** |
|
||||
|
||||
---
|
||||
|
||||
## 3. 运行时对象(锁定草案)
|
||||
|
||||
全部经插件构造,L1 返回 **map**(`_type` 稳定,金样可断言):
|
||||
|
||||
| `_type`(英) | 中文标签 | 字段(最小) | 含义 |
|
||||
|---------------|----------|--------------|------|
|
||||
| `linalg_expr` | `线性式` | `repr`(S-expr 或内部 id)、`shape`=`[m,n]` 或符号维、`latex`、`ascii` | 抽象矩阵公式 |
|
||||
| `linalg_dense` | `稠密阵` | `rows`, `cols`, `data`(行主 list[list])、`dtype`=`real`\|`complex` | 显式数值 |
|
||||
| `linalg_factor` | `分解` | `kind`=`lu`\|`qr`\|`svd`\|`eig`\|`chol`,因子字段,`latex`,可选 `svg` | 分解结果 |
|
||||
| `linalg_svg` | — | `kind`, `svg` 文本 | 与 quantum_svg 同构展示约定 |
|
||||
| `linalg_solve` | `求解` | `x`, `residual`, `method` | 线性系 / 最小二乘 |
|
||||
|
||||
形状:`shape` 允许整数或符号维名(字符串 `"n"`);不相容 → 硬错误。
|
||||
|
||||
---
|
||||
|
||||
## 4. 作者面 API(英文 `ext/linalg/linalg.mq.md`)
|
||||
|
||||
中文镜像:`ext/linalg/线性代数.mq.md`(`矩阵` / `化简` / `求值` / `绘图`…)。
|
||||
|
||||
### 4.1 构造
|
||||
|
||||
```markdown
|
||||
# matrix
|
||||
|
||||
## symbol
|
||||
+ `name`
|
||||
+ `rows`
|
||||
+ `cols`
|
||||
# → linalg_expr MatrixSymbol
|
||||
|
||||
## eye / zeros / ones / diag
|
||||
+ …
|
||||
|
||||
## from_list
|
||||
+ `data` # list[list] 或 table
|
||||
|
||||
## from_formula
|
||||
+ `formula` # 吸收 Value::Formula Matrix 字面量
|
||||
|
||||
## block
|
||||
+ `blocks` # 表或嵌套 list of expr
|
||||
```
|
||||
|
||||
文档写法偏好:
|
||||
|
||||
````markdown
|
||||
`A` = > la.symbol name=A rows=n cols=n
|
||||
|
||||
`b` =
|
||||
$$
|
||||
\begin{pmatrix}1\\0\\0\end{pmatrix}
|
||||
$$
|
||||
|
||||
*`b` = > la.from_formula formula=`b` *
|
||||
````
|
||||
|
||||
作者面优先顶层 `la.symbol` / `la.mul`(`la.matrix.symbol` 无接收者会硬错误,见 [module-namespace.md](module-namespace.md) §4.3)。
|
||||
### 4.2 公式代数(返回 `linalg_expr`,惰性)
|
||||
|
||||
| 英文 | 中文 | 语义 |
|
||||
|------|------|------|
|
||||
| `mul` / `add` / `sub` | `乘` / `加` / `减` | 形状检查后建树 |
|
||||
| `transpose` / `T` | `转置` | |
|
||||
| `inv` | `逆` | 符号逆;不立即求数值 |
|
||||
| `pow` | `幂` | 整数幂 |
|
||||
| `trace` / `det` | `迹` / `行列式` | 可得到标量 expr 或数值 |
|
||||
| `kron` | `克罗内克` | **禁止**默认 expand |
|
||||
| `simplify` | `化简` | 应用 §5 规则集 |
|
||||
| `collapse` | `分块化简` | 对标 `block_collapse` |
|
||||
| `latex` / `ascii` | `乳胶` / `文本` | 展示字符串 |
|
||||
| `shape` | `形状` | |
|
||||
|
||||
链式 / 中缀(v1 已落地):
|
||||
|
||||
```markdown
|
||||
*`C` = `A` + `B`*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`s` = > `Pt`.simplify*
|
||||
```
|
||||
|
||||
运行时对双方为 `matrix` / `矩阵` / 数值 `$$` 矩阵 / 遗留 `linalg_expr` 的 `+` `-` `*` 分派到插件;结果保留左操作数 `_type` 以便中英方法链。
|
||||
### 4.3 求值与分解(热路径 → 稠密)
|
||||
|
||||
| 英文 | 说明 |
|
||||
|------|------|
|
||||
| `eval` / `explicit` | 符号树 + 绑定表 → `linalg_dense`;超维硬错误 |
|
||||
| `factorize` | `kind=lu\|qr\|svd\|eig\|chol` → `linalg_factor` |
|
||||
| `solve` | `A`,`b`;或 `factor` + `b` |
|
||||
| `lstsq` | 最小二乘 |
|
||||
| `rank` / `norm` / `cond` | 数值度量 |
|
||||
| `matmul` | 稠密乘(已 explicit 时) |
|
||||
|
||||
维数上限(草案,可配置):
|
||||
|
||||
| 操作 | 默认上限 |
|
||||
|------|----------|
|
||||
| `explicit` 稠密元素总数 | \(n\cdot m \le 10^4\)(如 100×100) |
|
||||
| SVD / eig 方阵边长 | \(\le 64\)(与 quantum 密度同级) |
|
||||
| 结构 SVG(无元素) | 边长示意可达数百(只画框) |
|
||||
| KaTeX 完整数字阵 | \(\le 8\times 8\);更大只出摘要 + 结构图 |
|
||||
|
||||
### 4.4 展示
|
||||
|
||||
| 英文 | `kind` | 说明 |
|
||||
|------|--------|------|
|
||||
| `show` | — | 写入 view:优先 `latex` 公式卡 |
|
||||
| `draw` | `structure` | 形状/分块矩形(drawmatrix 风格) |
|
||||
| `draw` | `heatmap` / `hinton` | 数值幅度 |
|
||||
| `draw` | `svd` / `qr` / `ge` / `eig` | 分解结构图(对标 LAFigureSpecs) |
|
||||
| `draw` | `path`= | 可选落盘 SVG |
|
||||
|
||||
`show` 应对符号式**始终可用**(无需 `eval`)。
|
||||
|
||||
### 4.5 最小可运行示例(设计验收叙事)
|
||||
|
||||
````markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`A` = > la.symbol name=A rows=3 cols=3 *
|
||||
*`x` = > la.symbol name=x rows=3 cols=1 *
|
||||
*`b` = > la.mul a=`A` b=`x` *
|
||||
|
||||
*`s` = > la.simplify expr=`b` *
|
||||
> la.show expr=`s`
|
||||
|
||||
`M` =
|
||||
$$
|
||||
\begin{bmatrix}2&0\\0&3\end{bmatrix}
|
||||
$$
|
||||
|
||||
*`M` = > la.from_list data=[[2,0],[0,3]] *
|
||||
*`f` = > la.factorize matrix=`M` kind=eig *
|
||||
> la.draw factor=`f` kind=eig path=eig.svg
|
||||
````
|
||||
---
|
||||
|
||||
## 5. 公式重写与「大规模优化」(核心)
|
||||
|
||||
### 5.1 原则
|
||||
|
||||
1. **构造便宜,展开昂贵**——乘加只分配节点。
|
||||
2. **形状是类型系统**——`(m×k)·(k×n)` 合法;否则错误指向调用点。
|
||||
3. **化简是规则不动点**——有限规则表,可测、可文档化。
|
||||
4. **expand 显式开启**——`expand=True` 才对 Kronecker / 多项式矩阵做爆炸性展开。
|
||||
5. **数值路径旁路符号**——已 `explicit` 的叶子用稠密核,不再走规则。
|
||||
|
||||
### 5.2 v1 规则集(最小够用)
|
||||
|
||||
| ID | 规则 | 例 |
|
||||
|----|------|-----|
|
||||
| R1 | 单位元 | `I*A → A`,`A*I → A`,`A+0 → A` |
|
||||
| R2 | 双逆 | `(A^{-1})^{-1} → A` |
|
||||
| R3 | 转置反序 | `(AB)^\top → B^\top A^\top`,`(A^\top)^\top → A` |
|
||||
| R4 | 逆转置 | `(A^{-1})^\top → (A^\top)^{-1}` |
|
||||
| R5 | 结合扁平 | `MatMul` 链扁平化 |
|
||||
| R6 | 分块塌缩 | 对标 `block_collapse`(乘/加在块级分配) |
|
||||
| R7 | Kronecker 结合 | `(A⊗B)⊗C → A⊗B⊗C`;**不**展开成元素 |
|
||||
| R8 | 标量提出 | `c*(A+B) → c*A+c*B`(可选;默认关以免树变宽) |
|
||||
|
||||
### 5.3 数值侧优化
|
||||
|
||||
| 策略 | 说明 |
|
||||
|------|------|
|
||||
| `factorize` 一次 | 多 RHS `solve` 复用 |
|
||||
| 小阵专用核 | 2×2 / 3×3 闭式逆 / det(教学友好、可对照公式) |
|
||||
| 复杂度护栏 | 超限错误信息建议「保持符号 / 降维 / 分块」 |
|
||||
| 禁止静默降精度 | 病态 `cond` 可警告(stderr 或结果字段) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 展示设计(效果)
|
||||
|
||||
### 6.1 通道
|
||||
|
||||
| 通道 | 符号 MatExpr | 稠密 | 分解 |
|
||||
|------|--------------|------|------|
|
||||
| view Structure | KaTeX `latex` 卡 | 小阵 KaTeX;大阵摘要 | 公式 + 可选 SVG |
|
||||
| view Execution plots | — | heatmap SVG | `kind=svd|…` SVG |
|
||||
| CLI `print` | `ascii` | `[[…],…]` 或摘要 | `svd(U,S,V)` 摘要 |
|
||||
| writeback | 可选记录 latex | 可选 | 可选 |
|
||||
|
||||
### 6.2 LaTeX 约定
|
||||
|
||||
- 符号:`A`,`A^{\top}`,`A^{-1}`,`AB`,`A \otimes B`
|
||||
- 数值小阵:`\begin{bmatrix}…\end{bmatrix}`
|
||||
- 分块:`\begin{bmatrix} A & B \\ C & D \end{bmatrix}`
|
||||
- 喂给既有 view:与 `formula-card` / KaTeX 同源路径(L1 `show` → `host_query("record_plot")` 或扩展「record_math」若已有;无则复用 writeback + plot 列表)
|
||||
|
||||
### 6.3 结构 SVG(教学主视觉)
|
||||
|
||||
对标 LAFigureSpecs / drawmatrix,**不**依赖 Matplotlib:
|
||||
|
||||
| `kind` | 画什么 |
|
||||
|--------|--------|
|
||||
| `structure` | 矩形块 + 标签(零块灰色) |
|
||||
| `svd` | \(U\Sigma V^{\top}\) 块布局 + 秩分隔 |
|
||||
| `qr` | 瘦/胖 QR 示意 |
|
||||
| `ge` | 消元后上三角高亮 |
|
||||
| `eig` | \(A=PDP^{-1}\) 或谱列表 + 对角 |
|
||||
| `heatmap` | 单元填色(实数蓝红;复数幅值) |
|
||||
|
||||
主题:`theme=light|dark|bw`(与 quantum Q8 令牌对齐;默认 `light`)。
|
||||
|
||||
---
|
||||
|
||||
## 7. L1 / 插件 / CLI 约定
|
||||
|
||||
1. **`ext/linalg/**` 禁止 `host_*`**;只调 `plugin.*` 注册名(如 `linalg_simplify`)。
|
||||
2. **中英分文件**,CATALOG 双 id:`linalg` / `线性代数`。
|
||||
3. **`marqdo ext add linalg`**:与 web/agent/quantum 相同——优先 Release 预编译 native zip。
|
||||
4. **金样**:离线、确定性;SVG 断言含关键子串或稳定 hash 前缀。
|
||||
5. **依赖**:插件内自研稠密核(或慎重引入单一 crate,如 `nalgebra`——**实现期再议**;设计默认「可自研小维 + 可选 crate」)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分期(摘要;细节见路线图)
|
||||
|
||||
| 阶段 | 交付 |
|
||||
|------|------|
|
||||
| **L0** | CATALOG + ping + L1 `ensure_plugin` |
|
||||
| **L1** | `matrix.symbol` / dense 构造 / `mul`·`T`·`inv` 树 + `simplify` R1–R5 + `latex`/`show` |
|
||||
| **L2** | `explicit` / 小阵运算 / `solve` / `det`·`trace` 数值 |
|
||||
| **L3** | 分块 + `collapse`;Kronecker 惰性 |
|
||||
| **L4** | `factorize` LU/QR/SVD/eig + 结构 SVG |
|
||||
| **L5** | heatmap/hinton;examples + public 文档 + skill 摘要 |
|
||||
| **L6+** | 矩阵微积分 / 更大 BLAS(仅当用户明确要求);复数全路径算子 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收标准(设计级)
|
||||
|
||||
1. 符号式 `(AB)^\top` 经 `simplify` 得 `B^\top A^\top`,**不**产生稠密数据。
|
||||
2. 不相容形状在符号 `mul` 即失败。
|
||||
3. `$$` 数值阵 → `from_formula` → `factorize kind=eig` → view 含 SVG 或 latex。
|
||||
4. Kronecker 默认不 expand;显式 `expand` 受维数护栏。
|
||||
5. 中英 L1 金样各至少一条;`ext add linalg` 路径文档化。
|
||||
6. 与 `ext/quantum` 无作者面符号冲突。
|
||||
|
||||
---
|
||||
|
||||
## 10. 风险与开放问题
|
||||
|
||||
| 项 | 备注 |
|
||||
|----|------|
|
||||
| MatExpr 序列化 | 金样 / write:倾向可打印 S-expr 或稳定 latex+shape,避免不透明指针跨进程 |
|
||||
| 与标量 `formula` 混运算 | v1:标量只作 `c*A` 系数;`det` 结果若符号则另型或降为 `formula` 文本 |
|
||||
| nalgebra 等依赖 | 实现 L2 时评估二进制体积与 ABI 体积 |
|
||||
| record_math vs plot | 若仅 SVG/KaTeX 字符串,可先复用 plot/writeback |
|
||||
|
||||
---
|
||||
|
||||
## 11. 一句话(收束)
|
||||
|
||||
**`ext/linalg` 让线性代数公式保持可优化的表达式,用规则与结构图服务文档阅读,用受控稠密核服务验算——公式优先,数值可选,展示分层。**
|
||||
@@ -210,7 +210,7 @@
|
||||
- >6 qubit 稠密 ρ 的谱 / Hinton(请用态向量 API)
|
||||
- Matplotlib / WebGL / 交互拖拽
|
||||
- 量子线性系统算法(HHL)、QSVT 电路构造
|
||||
- 把线性代数并入 `lib/math`
|
||||
- 把线性代数并入 `lib/math`(经典公式优先的 LA 见规划 [ext-linalg.md](ext-linalg.md),作者面与 quantum 分离)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# `lib/csv` — 逗号表(Mid M4)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M4)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-text-mid.md](stdlib-text-mid.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 导入 | `lib/csv.mq.md` · `lib/逗号表.mq.md` |
|
||||
| Host | `host_csv_*`(RFC4180 最小集,无第三方 crate) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `parse` | `解析` | `text` | **list of maps**:首行为表头 |
|
||||
| `stringify` | `序列化` | `rows` | CSV 文本(表头 = 首行 map 的键顺序) |
|
||||
|
||||
## 2. 方言(v1)
|
||||
|
||||
- 分隔符 `,`;引号 `"`;`""` 转义。
|
||||
- 换行 `\n` / `\r\n`;忽略末尾空行。
|
||||
- 字段内可含逗号与换行(须加引号)。
|
||||
- **不**支持自定义分隔符 / 无表头模式(可后续加)。
|
||||
|
||||
## 3. 刻意不做
|
||||
|
||||
流式大文件、类型推断、Excel 方言。
|
||||
@@ -0,0 +1,32 @@
|
||||
# `lib/encoding` — 编解码(Mid M1)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M1)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [stdlib-re.md](stdlib-re.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 导入 | `lib/encoding.mq.md` · `lib/编码.mq.md` |
|
||||
| Host | `host_encoding_*`(无第三方 crate:标准 Base64 / hex) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `base64_encode` | `基64编码` | `text` | 文本(UTF-8 字节 → 标准 Base64,含 `=` 填充) |
|
||||
| `base64_decode` | `基64解码` | `text` | 文本(解码后须为合法 UTF-8) |
|
||||
| `hex_encode` | `十六进制编码` | `text` | 小写 hex |
|
||||
| `hex_decode` | `十六进制解码` | `text` | 文本(偶数字节;合法 UTF-8) |
|
||||
|
||||
## 2. 与 `net.url_encode` 的边界
|
||||
|
||||
| 能力 | 归属 |
|
||||
|------|------|
|
||||
| `application/x-www-form-urlencoded` 风格 | `net.url_encode` |
|
||||
| Base64 / hex | **本库** |
|
||||
| 百分号编解码通用版 | 可日后加 `encoding.percent_*`;本波不做 |
|
||||
|
||||
## 3. 刻意不做(v1)
|
||||
|
||||
URL-safe Base64 变体开关、忽略空白的宽松解码、二进制 `bytes` 类型(仍经 UTF-8 文本往返)。
|
||||
@@ -0,0 +1,24 @@
|
||||
# `lib/fs` 加厚 — 复制 / 移动 / 临时文件(Mid M2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M2)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-path.md](stdlib-path.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 边界 | **文本与普通文件**;不引入 `bytes` 类型(`read_bytes` 延后) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 新增 API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `copy_file` | `复制文件` | `src`, `dest` | `None`(覆盖已存在的目标文件) |
|
||||
| `move` | `移动` | `src`, `dest` | `None`(rename;跨设备失败则报错) |
|
||||
| `make_temp` | `建临时` | 可选 `prefix` | 相对 `cwd`/`fs_root` 的新空文件路径文本 |
|
||||
|
||||
均走现有 `resolve_path` 沙箱;写操作受 `fs_write` 策略约束。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
目录树 `copy_tree`、原子替换、`read_bytes`、权限 chmod。
|
||||
@@ -0,0 +1,26 @@
|
||||
# `lib/hash` — 摘要与 HMAC(Mid M3)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M3)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [stdlib-secrets.md](stdlib-secrets.md) |
|
||||
| 导入 | `lib/hash.mq.md` · `lib/哈希.mq.md` |
|
||||
| Host | `host_hash_*`(`sha2` / `sha1` / `md-5` / `hmac`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `sha256` | `哈希256` | `text` | 小写 hex |
|
||||
| `sha1` | `哈希1` | `text` | 小写 hex |
|
||||
| `md5` | `md5` | `text` | 小写 hex |
|
||||
| `hmac_sha256` | `密钥哈希256` | `key`, `text` | 小写 hex |
|
||||
|
||||
输入按 **UTF-8 字节**摘要。文档标明:用于完整性标识 / 缓存键,**不是**密码存储(无 Argon2/bcrypt)。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
密码哈希、流式大文件哈希 API、非 UTF-8 二进制类型。
|
||||
@@ -0,0 +1,36 @@
|
||||
# `lib/table` 集合加厚 + `lib/cli`(Mid M5)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M5)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 集合 | 加厚现有 `lib/table` / `lib/表`(不另开 `listx`) |
|
||||
| CLI | `lib/cli.mq.md` / `lib/命令行.mq.md` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 集合新增
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `sort` | `排序` | `list` | 升序列表(int/num/text 优先;其它按显示文本) |
|
||||
| `sort_by` | `按键排序` | `list`, `key` | 对 **map 列表**按键值排序 |
|
||||
| `unique` | `去重` | `list` | 保序去重 |
|
||||
| `chunk` | `分块` | `list`, `size` | 列表的列表 |
|
||||
| `zip` | `拉链` | `a`, `b` | `[[a0,b0], …]`(取较短长度) |
|
||||
| `flatten` | `展平` | `list` | 一层展平 |
|
||||
|
||||
`reverse` 已有。
|
||||
|
||||
## 2. CLI
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `parse` | `解析` | 可选 `args` | map:`--k v` / `--k=v` → 文本;裸 `--flag` → `True`;位置参 → 键 `_` 列表 |
|
||||
|
||||
`args` 缺省时用 `sys.args`(经宿主 `argv`)。
|
||||
|
||||
## 3. 刻意不做
|
||||
|
||||
稳定自定义比较器、惰性迭代器、完整 argparse 互斥组。
|
||||
@@ -0,0 +1,30 @@
|
||||
# `lib/log` + `lib/uuid`(Mid M6)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 日志 `lib/log` / `lib/日志`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `set_level` | `设级别` | `level`(`debug`/`info`/`warn`/`error`) | `None` |
|
||||
| `debug` / `info` / `warn` / `error` | `调试` / `信息` / `警告` / `错误` | `text` | 达级别则 `print` 一行 `LEVEL message`;否则无输出 |
|
||||
|
||||
默认级别:`info`(隐藏 `debug`)。中文级别别名:`调试`/`信息`/`警告`/`错误`。
|
||||
|
||||
实现:宿主记最小级别;`host_log_line` 返回待打印文本或 `None`;L1 再 `print`(接入现有 stdout / capture)。
|
||||
|
||||
## 2. UUID `lib/uuid` / `lib/标识`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `v4` | `版本4` | (无) | 标准 8-4-4-4-12 小写 hex(`getrandom`) |
|
||||
|
||||
## 3. 刻意不做
|
||||
|
||||
结构化 JSON 日志、远程 sink、UUID v1/v7、yaml。
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | **已实现(M1–M4)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) · 大学线性代数见规划 [ext-linalg.md](ext-linalg.md) |
|
||||
| 导入 | `lib/math.mq.md`(英)· `lib/数学.mq.md`(中) |
|
||||
| 范围 | **高中数学**(初等函数、导数、圆锥曲线、简单方程);非大学 CAS |
|
||||
|
||||
@@ -92,7 +92,7 @@ $$
|
||||
| 代入求值 | `subs` → `num` 或公式 |
|
||||
| 求解 | 一元一次 / 二次闭式;其它用数值求根并标明 |
|
||||
|
||||
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、矩阵、复数完备、任意证明。
|
||||
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、**大学线性代数**(符号矩阵表达式 / 分解 —— 见 [ext-linalg.md](ext-linalg.md))、复数完备、任意证明。数值小矩阵字面量可在 `$$` 中解析为 `formula::Matrix`,但符号 MatExpr 与分解不在 `lib/math`。
|
||||
|
||||
### 3.2 作图(P)
|
||||
|
||||
@@ -210,6 +210,7 @@ Interpreter.plots: Vec<Stringimport math:lib/math.mq.md · lib/数学.mq.md
|
||||
- `$$:name` 模块级具名绑定(已废除)。
|
||||
- 无名 `$$` 自动进运行时。
|
||||
- 大学级数 / 完备积分 / 定理证明。
|
||||
- **大学线性代数扩展**(见 [ext-linalg.md](ext-linalg.md);不在本库做符号 MatExpr)。
|
||||
- 通用隐函数作图引擎。
|
||||
- 3D、交互式图表库。
|
||||
|
||||
|
||||
@@ -0,0 +1,170 @@
|
||||
# 中层标准库(Mid Stdlib)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **M1–M6 已落地** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 目标 | 在接下来数个发版周期内,把「通用编程」能力沉到 **L0.5 宿主 + L1 `.mq.md`**,减少「凡是稍有能力就必须 ABI 插件」的路径依赖 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么现在做
|
||||
|
||||
现状分层(已落地):
|
||||
|
||||
```text
|
||||
L0 内置 print / len / split / …
|
||||
L0.5 宿主原语 src/host/*(供 L1 包装,作者原则上不直调)
|
||||
L1 官方库 lib/*.mq.md(嵌入二进制 / 可覆盖)
|
||||
ext 官方扩展 .mq.md + 可选 cdylib(web / agent / quantum / linalg)
|
||||
```
|
||||
|
||||
痛点:
|
||||
|
||||
1. **通用语言能力缺口**:`lib/text` 几乎只是 `trim/split/join`;无正则、无编解码、无哈希、无路径代数、无 CSV……日常脚本要么外联 Python,要么新开插件。
|
||||
2. **插件路径过重**:ABI 插件适合**领域热路径**(量子核、公式矩阵、HTTP 服务+SQLite),不适合「再来一个 base64」。每加一个插件都要:crate、Release 资产、`ext add`、CI、WASM 缺口。
|
||||
3. **扩展作者被逼进插件**:`ext/**` 禁止 `host_*`。若 L1 没有正则 / 哈希 / 路径,扩展只能 `plugin.load`,导致「库」与「原生模块」边界模糊。
|
||||
4. **对照成熟语言**:Go 的 `strings` / `regexp` / `encoding/*` / `crypto` / `path/filepath`、Python 的「难写对才进 stdlib」标准——都把**通用原语**留在语言自带层,把**领域产品**留给第三方。Marqdo 的「通用」应对齐前者;`ext/` 对齐后者。
|
||||
|
||||
中层标准库 = **在现有 L1 之上、在官方 ext 之下**,专门补「写通用程序必备、又不该做成插件」的那一档。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层命名(本波约定)
|
||||
|
||||
| 名称 | 位置 | 用户导入 | 实现形态 |
|
||||
|------|------|----------|----------|
|
||||
| **核心 L1** | 已有 `lib/{fs,sys,time,json,net,math,…}` | 是 | 薄包装 → 已有 `host_*` |
|
||||
| **中层 L1(Mid)** | 新增 / 加厚 `lib/{re,encoding,hash,path,…}` | 是(仍属 `lib/` / `std/`) | **优先**薄 `host_*` + L1;能纯 `.mq.md` 则纯库 |
|
||||
| **官方 ext** | `ext/{web,agent,quantum,linalg,ai}` | 显式 `ext/` | `.mq.md`;**仅**领域热路径允许 ABI 插件 |
|
||||
| **catalog / 用户库** | 发版外收录 | 各自约定 | 应能主要靠 Mid + 核心 L1 写成,**默认无插件** |
|
||||
|
||||
> **不**新开第三棵目录树。中层仍落在 `lib/`,用文档与路线图分期交付,避免 `lib/` vs `lib-mid/` 分裂。
|
||||
|
||||
---
|
||||
|
||||
## 3. 准入 / 不准入(宪法)
|
||||
|
||||
### 3.1 进入中层的条件(须同时满足多数)
|
||||
|
||||
| # | 条件 | 说明 |
|
||||
|---|------|------|
|
||||
| 1 | **跨领域高频** | 脚本、站点、智能体、教学示例都会用到 |
|
||||
| 2 | **难写对或不可移植** | 正则、Unicode、密码学、路径跨平台——纯 Marqdo 成本过高 |
|
||||
| 3 | **解锁「无插件写库」** | 有了它,更多 `ext/` / catalog 可用纯 `.mq.md` |
|
||||
| 4 | **宿主面积极小** | 一个或少数 `host_*` + 稳定 crate;不把巨型框架链进主二进制 |
|
||||
| 5 | **API 可长期冻住** | 宁可窄接口,也不提前做成第二个 Requests |
|
||||
|
||||
参考(外部):
|
||||
|
||||
- Python:[stdlib 准入](https://devguide.python.org/developer-workflow/stdlib/) 与 [Language Summit:stdlib 何用](https://blog.python.org/2023/05/the-python-language-summit-2023-what-is.html)——偏「启动器 / 新手脚本 / 难写对的协议」,而非「万物入 std」。
|
||||
- Go:日常几乎离不开的 `strings`、`regexp`、`encoding/*`、`crypto`、`path/filepath`、`slices`——对标我们的 Mid 候选,而非 `database/sql` 驱动全家桶。
|
||||
- 反面:PEP 594「死电池」——过窄协议、过时格式、与生态脱节的模块不要进 Mid。
|
||||
|
||||
### 3.2 明确不准入(继续走 ext + 可选插件)
|
||||
|
||||
| 领域 | 原因 |
|
||||
|------|------|
|
||||
| HTTP **服务端** / ASGI / 路由框架 | 产品面;已有 `ext/web` |
|
||||
| SQLite / ORM / 管理后台 | 同上 |
|
||||
| LLM / 智能体编排 / OKF | `ext/ai` · `ext/agent` |
|
||||
| 量子线路 / 密度矩阵核 | `ext/quantum` |
|
||||
| 大学线性代数 CAS / 分解可视化 | `ext/linalg`(公式文档面) |
|
||||
| 完整图像 / 音视频 / ML | 体积与依赖爆炸 |
|
||||
| 任意第三方云 SDK | 不属于语言 |
|
||||
|
||||
### 3.3 插件仍保留的边界
|
||||
|
||||
ABI 插件 **不废除**。规则收紧为:
|
||||
|
||||
```text
|
||||
若能力可用「少量 host_* + lib/*.mq.md」表达 → 必须走中层,禁止新开官方插件。
|
||||
若能力是领域数值核 / 长生命周期服务 / 可选重依赖 → 才允许官方插件。
|
||||
```
|
||||
|
||||
`lib/plugin` 继续服务:本地实验、第三方原生、官方领域包。
|
||||
|
||||
---
|
||||
|
||||
## 4. 实现分工(怎么长)
|
||||
|
||||
```text
|
||||
用户 / catalog / 官方 ext(纯 mq 优先)
|
||||
│ import re:lib/re.mq.md
|
||||
▼
|
||||
中层 L1(.mq.md,中英分文件,除 json 类共用外)
|
||||
│ **> host_re_find …**
|
||||
▼
|
||||
L0.5 宿主(Rust:regex / sha2 / …)
|
||||
│
|
||||
▼
|
||||
OS / 算法库(精选 crate,默认 features 最小化)
|
||||
```
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| `ext/**` 仍禁止 `host_*` | 中层补齐后,ext 经 `lib/re` 等调用 |
|
||||
| 每个新 `host_*` | 必须有 L1 包装 + 金样 + 中英对称(见 [stdlib-i18n.md](stdlib-i18n.md)) |
|
||||
| 能纯 mq 的 | 例如在 `table` 上的 `sort_by` 若性能可接受,可先纯库;热路径再下沉 host |
|
||||
| WASM | 新 host 须标注是否进浏览器构建;不能 WASM 的在文档标 `host-only` |
|
||||
| 依赖 | 新增 crate 写进 [dependencies.md](dependencies.md) 动机;禁止「顺手」拉大型框架 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 模块候选总表(按优先级波次)
|
||||
|
||||
完整排期与验收见 [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。摘要:
|
||||
|
||||
| 波次 | 模块(英 / 中) | 典型能力 | 主要形态 |
|
||||
|------|-----------------|----------|----------|
|
||||
| **M1** | `re` / `正则` · `encoding` / `编码` | match / find / replace;base64 / hex | **done** |
|
||||
| **M2** | `path` / `路径` · `fs` 加厚 | join / normalize;copy / move / temp | **done** |
|
||||
| **M3** | `hash` / `哈希` · `secrets` / `机密` | sha256 / hmac;token | **done** |
|
||||
| **M4** | `csv` / `逗号表` · `text` 加厚 | parse / stringify;contains / replace | **done** |
|
||||
| **M5** | `table` 加厚 · `cli` / `命令行` | sort / zip;flags | **done** |
|
||||
| **M6** | `log` / `日志` · `uuid` / `标识` | level 日志;v4 | 薄 host 或纯 mq |
|
||||
| **可选** | `yaml` / `Toml` | 仅当 public/catalog 强需求 | 慎入 |
|
||||
|
||||
**刻意延后:** 完整 `datetime` 时区库、连接池、异步 runtime、模板引擎、完整 `collections` 类型系统——等中层前几波用起来再议。
|
||||
|
||||
---
|
||||
|
||||
## 6. 与现有库的关系
|
||||
|
||||
| 现有 | 中层策略 |
|
||||
|------|----------|
|
||||
| `lib/text` | **加厚**,不另起 `strings` 英文名(保持 Marqdo 习惯);中文 `文本` |
|
||||
| `lib/table` | Mid 集合算法优先挂这里或薄 `listx`;避免与 GFM 表语义打架 |
|
||||
| `lib/net` | HTTP 客户端保留;编解码类能力与 `encoding` 边界写清(url 组件归谁) |
|
||||
| `lib/math` | 保持**高中**;哈希 / 安全随机不进 math |
|
||||
| `lib/json` | 仍只 parse/stringify/quote;CSV/YAML 另库 |
|
||||
| `lib/plugin` | 不变;文档写明「通用能力请先查 Mid」 |
|
||||
| `ext/*` | 逐步**改写依赖**:能改用 `lib/re` 的路由/校验,去掉不必要的原生 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 文档与工程节奏
|
||||
|
||||
每个 Mid 波次固定流水线(与现有发版习惯对齐):
|
||||
|
||||
1. 本设计不变的前提下,在 roadmap 勾选该波次工作项。
|
||||
2. `doc/design/stdlib-<module>.md`(可短)→ `host_*` → `lib/` 中英 → `tests/lib/*` 金样 → `public/features` 短文。
|
||||
3. 更新 [stdlib-modules.md](stdlib-modules.md) 模块表。
|
||||
4. **不**为 Mid 单开 SemVer 故事;随正常产品发版收进 CHANGELOG「标准库」小节。
|
||||
5. 发版技能 / Release 资产:仅当新增 **必须** 随 CLI 分发的东西时改 release 脚本——Mid 默认已嵌入 stdlib,**无** native zip。
|
||||
|
||||
---
|
||||
|
||||
## 8. 成功标准(数个版本后)
|
||||
|
||||
1. 用 Mid + 核心 L1 **不加载任何插件**,能写:日志采集脚本、CSV 清洗、带正则的文本管线、带哈希校验的下载器、简单 CLI 工具。
|
||||
2. 新的官方 **非领域** 能力默认进 `lib/`,评审时问:「能否不做成插件?」
|
||||
3. `ext/web` / `ext/agent` 等仍可有插件,但依赖面写进文档:哪些能力已改走 Mid。
|
||||
4. 主二进制体积与依赖可解释;WASM 可用性有清单。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话
|
||||
|
||||
**中层标准库把「通用原语」沉回语言自带层,让插件专属于真正的领域引擎——这样 Marqdo 才像一门通用语言,而不是「Markdown + 一堆 .so」。**
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin**/browser |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
|
||||
| 状态 | **核心已落地**;**中层 Mid:M1–M6 已落地** · [stdlib-mid.md](stdlib-mid.md) / [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精;**通用能力优先 Mid,插件留给领域核** |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-mid.md](stdlib-mid.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
|
||||
|
||||
---
|
||||
|
||||
@@ -15,10 +15,19 @@
|
||||
|
||||
| 模块族 | 英文库 | 中文库 | 状态 |
|
||||
|--------|--------|--------|------|
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有(`put`/`改` + list/map;见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 + **Mid M4** 加厚 |
|
||||
| **正则** | `lib/re.mq.md` | `lib/正则.mq.md` | **Mid M1** |
|
||||
| **编解码** | `lib/encoding.mq.md` | `lib/编码.mq.md` | **Mid M1** |
|
||||
| **路径** | `lib/path.mq.md` | `lib/路径.mq.md` | **Mid M2** |
|
||||
| **哈希** | `lib/hash.mq.md` | `lib/哈希.mq.md` | **Mid M3** |
|
||||
| **机密** | `lib/secrets.mq.md` | `lib/机密.mq.md` | **Mid M3** |
|
||||
| **逗号表** | `lib/csv.mq.md` | `lib/逗号表.mq.md` | **Mid M4** |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有 + Mid M4/M5:`sort`/`unique`/`zip`/… |
|
||||
| **命令行** | `lib/cli.mq.md` | `lib/命令行.mq.md` | **Mid M5** |
|
||||
| **日志** | `lib/log.mq.md` | `lib/日志.mq.md` | **Mid M6** |
|
||||
| **标识** | `lib/uuid.mq.md` | `lib/标识.mq.md` | **Mid M6** |
|
||||
| 浏览器效应 | `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM 客户端效应助手(GFM + helpers;勿用 `json.set` 链) |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 + Mid M2:`copy_file` / `move` / `make_temp` |
|
||||
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
|
||||
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
|
||||
| JSON | `lib/json.mq.md` | **同文件** | **仅** parse / stringify / quote;集合请用 table / GFM |
|
||||
@@ -29,7 +38,9 @@
|
||||
| **自写回** | `lib/writeback.mq.md` | `lib/自写回.mq.md` | **已有**(Jupyter 式输出写回) |
|
||||
| **子任务** | `lib/subtask.mq.md` | `lib/子任务.mq.md` | **已有**(OS 子进程 + KillOnDrop) |
|
||||
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` — 见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` · `ext/web` · `ext/quantum` · `ext/linalg` — 见各 `ext-*.md`。
|
||||
|
||||
**中层已落地:** M1–M6(含 log / uuid)— 见 [stdlib-mid.md](stdlib-mid.md) · [stdlib-log-uuid.md](stdlib-log-uuid.md)。
|
||||
|
||||
设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
|
||||
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
# `lib/path` — 路径代数(Mid M2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M2)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 导入 | `lib/path.mq.md` · `lib/路径.mq.md` |
|
||||
| Host | `host_path_*`(`std::path`;无 I/O、不经 `fs_root`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `join` | `拼接` | `a`, `b` | 文本路径 |
|
||||
| `split` | `拆分` | `path` | 组件文本列表(去空段) |
|
||||
| `file_name` | `文件名` | `path` | 最后一段;根路径可为空文本 |
|
||||
| `parent` | `父目录` | `path` | 父路径文本;无父则 `"."` |
|
||||
| `extension` | `扩展名` | `path` | 不含点;无扩展名为 `""` |
|
||||
| `normalize` | `规范化` | `path` | 清理 `.` / `..`(纯字符串,不访问磁盘) |
|
||||
| `is_absolute` | `是绝对` | `path` | 布尔 |
|
||||
|
||||
## 2. 语义
|
||||
|
||||
- 分隔符与绝对路径判定跟随 **宿主 OS**(Linux CI 为 `/`)。
|
||||
- **不做** I/O;逃逸检查仍由 `lib/fs` 在读写时执行。
|
||||
- `join`:若 `b` 为绝对路径,结果为 `b`(同 `Path::join`)。
|
||||
|
||||
## 3. 刻意不做(v1)
|
||||
|
||||
`glob`、符号链接解析、`relative_to`、Windows UNC 专项文档。
|
||||
@@ -0,0 +1,33 @@
|
||||
# `lib/re` — 正则(Mid M1)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M1)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 导入 | `lib/re.mq.md` · `lib/正则.mq.md` |
|
||||
| Host | `host_re_*`(`regex` crate,默认 Unicode) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `is_match` | `匹配` | `text`, `pattern` | 布尔 |
|
||||
| `find` | `查找` | `text`, `pattern` | 首个匹配文本,或 `None` |
|
||||
| `find_all` | `查找全部` | `text`, `pattern` | 文本列表 |
|
||||
| `replace` | `替换` | `text`, `pattern`, `with`, 可选 `count` | 文本(`count` 缺省 = 全部) |
|
||||
| `split` | `拆分` | `text`, `pattern` | 文本列表 |
|
||||
|
||||
非法 pattern → 诊断失败(含 crate 错误信息)。
|
||||
|
||||
## 2. 语义
|
||||
|
||||
- 引擎:Rust [`regex`](https://docs.rs/regex)(无回溯引用;与 RE2 同族限制)。
|
||||
- 按 **UTF-8 文本**匹配,不做字节模式。
|
||||
- `find` / `find_all` 返回整段匹配(不含捕获组拆分;捕获组 v1 不做)。
|
||||
|
||||
## 3. 刻意不做(v1)
|
||||
|
||||
命名捕获、替换回调、`Regex` 对象缓存 API、字节模式。
|
||||
@@ -0,0 +1,24 @@
|
||||
# `lib/secrets` — 安全随机令牌(Mid M3)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M3)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-hash.md](stdlib-hash.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 导入 | `lib/secrets.mq.md` · `lib/机密.mq.md` |
|
||||
| Host | `host_secrets_*`(`getrandom`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `token_hex` | `十六进制令牌` | 可选 `n`(字节数,默认 16) | 小写 hex,长度 `2*n` |
|
||||
| `token_urlsafe` | `网址安全令牌` | 可选 `n`(字节数,默认 16) | URL-safe Base64(无填充) |
|
||||
|
||||
**不要**用 `math.random` / `math.seed` 生成令牌。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
密钥派生、加密/解密、密码哈希。
|
||||
@@ -0,0 +1,30 @@
|
||||
# `lib/text` 加厚(Mid M4)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M4)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-csv.md](stdlib-csv.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 导入 | `lib/text.mq.md` · `lib/文本.mq.md` |
|
||||
| Host | `host_text_*`(Unicode 大小写 / 子串;非正则替换) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 新增 API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `contains` | `包含` | `text`, `sub` | 布尔 |
|
||||
| `starts_with` | `开头是` | `text`, `prefix` | 布尔 |
|
||||
| `ends_with` | `结尾是` | `text`, `suffix` | 布尔 |
|
||||
| `replace` | `替换` | `text`, `old`, `new`, 可选 `count` | 文本(字面替换,非正则) |
|
||||
| `to_upper` | `大写` | `text` | 文本(Unicode) |
|
||||
| `to_lower` | `小写` | `text` | 文本 |
|
||||
| `repeat` | `重复` | `text`, `n` | 文本 |
|
||||
| `pad` | `填充` | `text`, `width`, 可选 `fill`=`" "`,可选 `align`=`left`/`right`/`center` | 文本 |
|
||||
|
||||
保留原有 `str_trim` / `str_split` / `str_join`(及中文去空白/拆分/拼接)。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
正则替换(用 `lib/re`)、完整 `format` 模板引擎。
|
||||
@@ -2,12 +2,13 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 + L1 全模块落地** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
|
||||
| 状态 | **S0–S3 + 核心 L1 已落地 · 中层 L1(Mid)规划中** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [**stdlib-mid.md**](stdlib-mid.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
|
||||
|
||||
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
|
||||
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
> **中层标准库(数个版本)**:通用原语沉 `lib/`、减少「事事插件」——设计 [stdlib-mid.md](stdlib-mid.md) · 路线 [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。
|
||||
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
---
|
||||
@@ -17,9 +18,10 @@
|
||||
| 层 | 内容 |
|
||||
|----|------|
|
||||
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
|
||||
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
|
||||
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
|
||||
| **L2** | catalog / 用户站收录(随发版) |
|
||||
| **L1 核心** | 已有 [`lib/`](../../lib/):fs/sys/time/json/net/math/foreign/plugin/table/text/… |
|
||||
| **L1 中层(Mid)** | 规划中:re / encoding / path / hash / csv / … — 仍在 `lib/`,见 [stdlib-mid.md](stdlib-mid.md) |
|
||||
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1;插件仅领域热路径 |
|
||||
| **L2** | catalog / 用户站收录(随发版);应主要靠核心+中层、默认无插件 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -13,6 +13,8 @@
|
||||
|
||||
**`ext/web` + `plugins/web` 已完成 W0–W7 + P3 路线图**:中间件/JSON API、数据层(连接池/事务/分页/FTS/迁移/外键/审计时间戳)、安全硬化(argon2/CSRF/会话持久化/限速/RBAC)、内容站点标配(SEO/RSS/Markdown/分页 UI)、上传下载/相册/ETag、sitemap/robots/错误页/重定向、WebSocket 广播与访问日志。足以在 Marqdo 上实现博客/CMS/中小型 API 站点;**未内置**的仅剩标签页模板(D6,可用路由+`db.count` 自建)与应用层反垃圾。边界不变:**纯解析进 `lib/net`,HTTP 服务器与领域能力进 `plugins/web` + `ext/web` 作者面**。
|
||||
|
||||
**宿主集成下一刀**(同域 LLM SSE 中继、HTTP→用户 `##`、与 MCP Server 协作)不在本 W 表内,见 [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) · [ext-hosting-fill.md](ext-hosting-fill.md) · [ext-hosting.md](../roadmap/ext-hosting.md)。
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -70,6 +70,7 @@
|
||||
| **高** | 官方端到端示例 + 文档新鲜度 | 无独立 `examples/agent-*`;Skill/参考里仍有「layout / roadmap」陈旧表述;外人难「照抄即跑通 plan→固化→二次命中」 | `examples/agent-pong`(或同类)+ README;Skill 专节与 A0–A4 对齐 |
|
||||
| **高** | Agent 评测 / 回归 harness | 有离线金样,缺成本·恢复·命中率·补丁质量的系统评测;业界强调 evaluation 先于上线 | `tests/` 或脚本:命中率、llm_free 占比、失败恢复、可选 live 预算 |
|
||||
| **高** | 真 MCP(HTTP/SSE)与凭证 | A4 仅 JSON fixture;缺 streamable HTTP、鉴权、resources/prompts | 金样打 mock MCP server;返回仍带 `authority=workbook` |
|
||||
| **高** | **MCP Server 宿主**(stdio / HTTP) | Agent 只能当客户端 fixture;IDE 无法把 `.mq.md` `##` 暴露为 MCP 工具 | 见 [ext-hosting-gaps.md](ext-hosting-gaps.md) GAP-03 · [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
|
||||
| **中** | Plan 断点续跑 | 工作簿在盘上,缺显式 checkpoint / resume(对标 LangGraph checkpointer) | `plan resume=` 从第 N 轮 DECISION 继续;进程崩溃可恢复 |
|
||||
| **中** | 人机协同(HITL)加深 | 仅有 `confirm=True` 建簿即停;缺审批卡、拒绝重开、view 一键继续 | view 审批控件 + 金样 |
|
||||
| **中** | 飞轮可观测指标 | `hits` / `improve_every` / `llm_free` 有字段,缺汇总与 CLI/view 报表 | `agent_kb_stats` 或 view 面板:命中率、探索浪费 |
|
||||
|
||||
@@ -0,0 +1,156 @@
|
||||
# 调研:宿主集成缺口(浏览器中继 · HTTP→`##` · MCP Server · 同寿副端口 · 跨模块 DB/检索)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 缺口盘点(H1–H4 stdio 已落地;H4b HTTP 可选)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 触发 | 下游应用(对话站 / 求道类 Agent)在真实集成中被迫旁路 Python 脚本 |
|
||||
| 基线版本 | **v0.3.6+**(宿主波次 H1–H4 见 [ext-hosting.md](../roadmap/ext-hosting.md)) |
|
||||
| 相关设计 | [ext-web.md](../design/ext-web.md) · [ext-web-net.md](../design/ext-web-net.md) · [web-net-capabilities.md](../design/web-net-capabilities.md) · [ext-agent.md](../design/ext-agent.md) · [ext-abi.md](../design/ext-abi.md) |
|
||||
| 邻近缺口 | [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md)(真 MCP **客户端**) |
|
||||
| 补齐设计 | [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
|
||||
| 实现路线 | [ext-hosting.md](../roadmap/ext-hosting.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
`ext/web` 已能做**内容站 / CRUD / JSON-DB API / WS**;`ext/ai` 已能做**工作簿 Agent + 客户端 SSE 消费**。下游要把「浏览器同域流式 LLM」「请求触发任意 `##`」「MCP Server 被 IDE 拉起」合进**单一 Marqdo 进程**时,现有扩展**没有一等装配**——只能外挂缓冲代理 / CLI 子进程。缺口集中在 **扩展库作者面 + `plugins/web|agent` ABI**,不是语法层,也不是再开一套标准库。
|
||||
|
||||
**原则:** 旁路脚本只证明需求;关闭缺口必须把能力沉进 `ext/*` + `plugins/*`(可选极薄 `lib/` 编排),禁止把领域逻辑塞进 `src/host/`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 已有基线(不是缺口)
|
||||
|
||||
| 能力 | 现状 | 文档 / 金样 |
|
||||
|------|------|-------------|
|
||||
| CORS / 安全头 / gzip / body limit | `app.configure` | `tests/ext/web-middleware-smoke.mq.md` |
|
||||
| JSON **DB select** 路由 | `configure json=` | `plugins/web/src/middleware.rs` |
|
||||
| `/_form/*` SQL CRUD | `mount_form` | `plugins/web/src/form.rs` |
|
||||
| 客户端缓冲 SSE | `lib/net.http_post_sse` → `ext/llm.complete stream=` | `tests/lib/net-openai-sse.mq.md` |
|
||||
| 执行过程 SSE(非 LLM 中继) | `marqdo view` `/api/run` | [view.md](../design/view.md) §5 |
|
||||
| Agent 证据工具(fixture MCP) | `corpus_search` / `mcp_list_tools` / `mcp_call` | A4;[agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
|
||||
| 同模块 `# db` CRUD | `ext/web` `# db` | `examples/web-site/db/` |
|
||||
|
||||
---
|
||||
|
||||
## 2. 缺口总表
|
||||
|
||||
| ID | 缺口 | 需要 | Marqdo 现状 | 典型旁路 | 解除条件 |
|
||||
|----|------|------|-------------|----------|----------|
|
||||
| **GAP-01** | 浏览器 → 上游 LLM **同域流式中继** | 绕过对方 CORS;**SSE 原样转发** | **`app.proxy` / `configure proxy=`**(H1) | ~~`llm_proxy.py`~~ | ✅ 已关闭 |
|
||||
| **GAP-02** | HTTP 处理函数可调用用户 `##` | 请求内执行用户 `##`,返回 JSON | **`app.invoke` / `configure invoke=`**(H2) | ~~外挂 `marqdo run`~~ | ✅ 已关闭 |
|
||||
| **GAP-03** | **MCP Server** 宿主 | IDE 拉起暴露工具 | **`agent.mcp_server` + `serve` stdio**(H4);HTTP=H4b | ~~`qdagent_mcp.py`~~ | ✅ stdio;HTTP 可选 |
|
||||
| **GAP-04** | 同寿「第二监听端口」 | 与 `listen` 同寿中继 | 并入主端口(H1+H2) | ~~`mq.sh` 双进程~~ | ✅ won't |
|
||||
| **GAP-05** | 跨模块 `db`;纯 run 用 corpus | 跨文件 `select`;CLI 检索 | 传递归查找 + `corpus_search` ensure_plugin(H3) | ~~db/index 导出~~ | ✅ 已关闭 |
|
||||
|
||||
旁路脚本名来自下游集成仓库;**本仓库 `scripts/` 不含这些文件**——它们是需求证据,不是上游实现。
|
||||
|
||||
---
|
||||
|
||||
## 3. 分项说明
|
||||
|
||||
### 3.1 GAP-01 · 同域 SSE 中继
|
||||
|
||||
**问题**
|
||||
浏览器页面跑在 `ext/web` 源上时,直连 OpenAI 兼容上游会撞 CORS;`lib/net.http_post_sse` 只在 **CLI/宿主侧缓冲整段流**,不能把字节边收边推回浏览器。
|
||||
|
||||
**现状边界**
|
||||
|
||||
| 已有 | 缺什么 |
|
||||
|------|--------|
|
||||
| `app.configure cors=` | 解决的是**本站对外** CORS,不是替上游开 CORS |
|
||||
| `http_post_sse` → `{status, events}` | **客户端消费**,非服务器中继 |
|
||||
| `app.download` 对象流 | 存储下载,非上游 SSE |
|
||||
| view `/api/run` SSE | Marqdo **执行事件**,非 LLM token 流 |
|
||||
|
||||
**解除形态(产品)**
|
||||
作者声明:`path` + `upstream`(或 env)+ 可选 header 白名单;监听端对浏览器返回 `Content-Type: text/event-stream`,chunk 原样或按 OpenAI SSE 帧转发。
|
||||
|
||||
### 3.2 GAP-02 · 路由 → `##`
|
||||
|
||||
**问题**
|
||||
对话沉淀、表单后写 `data/runs/*.mq.md`、触发 `lib/run.沉淀` 等,需要**同进程**执行用户函数。今天只有:
|
||||
|
||||
1. 页面装配期 `call_lib_path`(compose,非每请求);
|
||||
2. `/_form` / `json=` 的 **DB 专用** handler。
|
||||
|
||||
**解除形态(产品)**
|
||||
声明式:`path` · `method` · `fn=lib.member` 或 `file=… ## name` · body→形参映射 · 返回值序列化为 JSON(错误码约定)。安全默认:仅允许入口模块已导入路径;禁止任意路径注入。
|
||||
|
||||
### 3.3 GAP-03 · MCP Server
|
||||
|
||||
**问题**
|
||||
A4 解决的是 Agent **调用** MCP 工具(且仍是 fixture)。下游要把 Marqdo 工作簿 **暴露为** MCP Server(stdio / Streamable HTTP),IDE 拉起后调 `qd_*`。
|
||||
|
||||
与 [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md)「真 MCP 客户端」正交:本缺口是 **Server 宿主**。
|
||||
|
||||
**解除形态(产品)**
|
||||
`ext/ai`(或 `ext/mcp`)提供:`server tools=` 表(name → `.mq.md`/`##`);`serve stdio=` / `serve http port=`;工具结果仍可带 `authority=workbook`。
|
||||
|
||||
### 3.4 GAP-04 · 同寿副端口
|
||||
|
||||
**问题**
|
||||
在 GAP-01/02 未并入主端口前,下游用第二端口跑代理。`app.listen` 同步阻塞,无「同进程再绑一个 TcpListener」的作者 API;只能 shell 并起另一运行时。
|
||||
|
||||
**解除形态(产品)**
|
||||
优先:GAP-01/02 挂在同一 `listen` → **本缺口关闭**。备选:`app.attach` / `listen also=` 同 tokio 运行时附加服务(仅当必须隔离路径树)。
|
||||
|
||||
### 3.5 GAP-05 · 跨模块 DB 句柄与 corpus 可发现性
|
||||
|
||||
**问题**
|
||||
|
||||
1. **类型分发:** 插件对象依赖 `_type` / 方法表;跨模块传回的 store 若丢类型或未注册方法,报 `unknown object type db`。同文件 `db/index.mq.md` 内 `## recent` 再导出 JSON 是现行绕过。
|
||||
2. **`agent_corpus_search`:** 注册在 `plugins/agent`;普通 `marqdo run` 未 `plugin.load` / 未构造 `# agent` 时不可用。导入 `ext/ai/agent.mq.md` 文本本身不保证原生插件已加载。
|
||||
|
||||
**解除形态(产品)**
|
||||
句柄:跨模块返回值保留 `_type=db` 且方法分发查全局/插件表(修运行时或约定「只返回 url,调用方再 `web.db`」二选一,见补齐设计)。corpus:`plugin.load` 自动路径,或 `ext/ai` 导出独立 `## corpus_search` 并在调用前 `ensure_plugin`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 归属判定(标准库 vs 扩展)
|
||||
|
||||
沿用 [ext-web-net.md](../design/ext-web-net.md) / [web-net-capabilities.md](../design/web-net-capabilities.md) 边界:
|
||||
|
||||
| 能力 | 归属 | 理由 |
|
||||
|------|------|------|
|
||||
| SSE **中继**路由、HTTP→`##`、副端口 | **`plugins/web` + `ext/web`** | 服务器结构 / 网站领域;axum 已在依赖链 |
|
||||
| MCP **Server**、corpus 可发现 | **`plugins/agent` + `ext/ai`** | Agent/工具宿主;禁止塞 `src/host/` |
|
||||
| 缓冲 SSE 客户端、解析 | 已有 **`lib/net`** | 不新增中继到 stdlib |
|
||||
| 任意路径 shell 出去跑 `marqdo` | **刻意不做进核心** | 旁路脚本可留在下游;上游给一等 API 后废弃 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 优先级建议
|
||||
|
||||
| 优先级 | ID | 理由 |
|
||||
|--------|-----|------|
|
||||
| **高** | GAP-01 + GAP-02 | 去掉 Python 中继的主路径;浏览器站 + 沉淀闭环 |
|
||||
| **高** | GAP-03 | IDE 生态入口;与「真 MCP 客户端」可并行设计、分波交付 |
|
||||
| **中** | GAP-05 | 减少 `db/index` 与 bridge 胶水;影响面偏语言/插件加载 |
|
||||
| **低(可随 01/02 关闭)** | GAP-04 | 并入主端口后自然消失 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 明确「不是缺口」
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 内容站 W0–W7+P3 | 已完结;本清单不重开上传/RSS/RBAC |
|
||||
| Mid M1–M6 | 通用原语已够;本清单不是再开 `lib/re` 一类 |
|
||||
| 隐藏 JSON TOOL 主循环 | 与 Agent 宪法冲突 |
|
||||
| Dense embedding 默认化 | 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) |
|
||||
| 浏览器手写业务 JS 代理 | 与 WASM 路线「作者零 JS」冲突;中继应在服务端 `ext/web` |
|
||||
|
||||
---
|
||||
|
||||
## 7. 与其它文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [ext-hosting-fill.md](../design/ext-hosting-fill.md) | **补齐设计(作者 API + ABI)** |
|
||||
| [ext-hosting.md](../roadmap/ext-hosting.md) | 实现波次 H0–H4 |
|
||||
| [ext-web.md](../roadmap/ext-web.md) | 站点主线完结;本缺口为后续宿主波次 |
|
||||
| [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) | 客户端真 MCP;与 GAP-03 Server 互补 |
|
||||
| [web-asgi-servers-and-marqdo.md](../design/web-asgi-servers-and-marqdo.md) | 反代模型;中继仍在 Marqdo `listen` 内 |
|
||||
@@ -0,0 +1,113 @@
|
||||
# 调研:线性代数 × 公式类 × 展示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 调研纪要(为 [ext-linalg](../design/ext-linalg.md) 供输入) |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-math.md](../design/stdlib-math.md) · [ext-quantum-q7.md](../design/ext-quantum-q7.md) · SymPy MatrixExpr · Symbolics.jl · LAFigureSpecs |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题陈述
|
||||
|
||||
Marqdo 已有:
|
||||
|
||||
- `Value::Formula` + `` `f` = `` + `$$…$$`(高中标量符号)
|
||||
- `formula::Expr::Matrix`:**数值**稠密矩阵字面量(`[[…]]` / `\begin{pmatrix}`),供量子门核对与 view KaTeX
|
||||
- `ext/quantum` Q7:**量子语境**下的密度矩阵 / Kronecker / 谱 / SVD 风格图(ABI)
|
||||
|
||||
缺口:一门**经典线性代数**扩展——作者用**公式级矩阵表达式**写 \(A^\top A\)、\((X^\top X)^{-1}X^\top y\)、分块、Kronecker,在**不立刻展开成巨大稠密矩阵**的前提下做重写与化简,并在文档 / view 中**好看地呈现**分解与结构。
|
||||
|
||||
---
|
||||
|
||||
## 2. 业界对照
|
||||
|
||||
### 2.1 符号矩阵表达式(大规模优化的关键)
|
||||
|
||||
| 系统 | 模型 | 对 Marqdo 的启示 |
|
||||
|------|------|------------------|
|
||||
| **SymPy `MatrixExpr`** | `MatrixSymbol(name, n, m)` + `MatMul` / `MatAdd` / `Inverse` / `Transpose` / `Trace` / `Determinant` / `BlockMatrix` / `KroneckerProduct`;`as_explicit()` 才展开 | **默认保持抽象**;形状元数据传播;显式求值是可选动作 |
|
||||
| SymPy `block_collapse` | 分块表达式在块级化简,避免整块稠密展开 | 分块是教学与优化的第一公民 |
|
||||
| SymPy Kronecker | `KroneckerProduct` 惰性 + `combine_kronecker` 规则 | Kronecker **绝不能**默认 `expand`(维数爆炸) |
|
||||
| SymPy 矩阵求导 | 经 array expr 再收回 MatrixExpr;闭式导数 | v1 **不做**;记入远期 |
|
||||
| **Symbolics.jl** | 「数组的符号」vs「符号数组」:后者 O(1) 表示整阵,保留 `A*B` 不展开 | 与 MatrixExpr 同构;强调 **shape / eltype 元数据** |
|
||||
| NumPy / Eigen / nalgebra | 数值热路径,无公式树 | 对应 Marqdo **插件数值层**,不是文档作者主路径 |
|
||||
|
||||
**结论:** 「公式类线性代数」= **抽象表达式 DAG + 形状检查 + 重写规则**;稠密数值是 `eval` / `as_explicit` 的终点,不是默认形态。
|
||||
|
||||
### 2.2 教学与展示(效果最好的做法)
|
||||
|
||||
| 做法 | 来源 | 效果 | Marqdo 映射 |
|
||||
|------|------|------|-------------|
|
||||
| KaTeX / MathJax 渲染 `bmatrix` / `pmatrix` | SymPy `latex()` + Jupyter `init_printing` | 公式即排版;多式用 `display` 并列 | 既有 view `formula-card` + KaTeX |
|
||||
| 标签化等式 `A = UΣV^\top` | 教材 / Qiita display+Math | 步骤可读 | `show` / writeback 多卡片 |
|
||||
| **结构图**(SVD / QR / 消元轨) | [LAFigureSpecs](https://github.com/ea42gh/LAFigureSpecs) + matrixlayout;TeX `drawmatrix` | 比数字表更能讲「秩 / 零空间 / 对角结构」 | SVG `kind=svd|qr|ge|eig` |
|
||||
| 热力图 / Hinton | Qiskit / QuTiP / 既有 quantum | 稠密数值矩阵的幅度/符号 | `kind=heatmap|hinton`(经典实/复) |
|
||||
| 分块着色矩形 | CTAN `drawmatrix` | 零块 / 三角 / 带状一目了然 | `kind=structure`(形状示意图,可无元素值) |
|
||||
| 仅打印 ASCII | CLI 默认 | 金样可断言 | `str` / `print` → 规范 ASCII / LaTeX 源 |
|
||||
|
||||
**展示优先级(锁定建议):**
|
||||
|
||||
1. **符号式**:始终可 `latex` → view KaTeX(不依赖数值)
|
||||
2. **结构式 SVG**:分解 / 分块 / 秩示意(教学主图)
|
||||
3. **数值热力图**:仅在 `eval` 后、维数可控时
|
||||
4. CLI:短 ASCII;大矩阵默认摘要 `m×n …` + 可选 `preview=`
|
||||
|
||||
### 2.3 一门「够用」的线性代数库需要什么
|
||||
|
||||
按大学一学期 + 数据科学入门,能力桶:
|
||||
|
||||
| 桶 | 内容 | 符号层 | 数值层 |
|
||||
|----|------|--------|--------|
|
||||
| A 构造 | 符号阵、常数阵、单位/零/对角、从 `$$` / 表 / list | ✅ | ✅ |
|
||||
| B 代数 | 加减乘、转置、逆、伴随、幂、Kronecker、分块 | ✅ 重写 | ✅ |
|
||||
| C 分解 | LU / QR / 特征 / SVD / Cholesky(对称) | 结果对象 + 结构图 | ✅ |
|
||||
| D 系统 | `Ax=b`、最小二乘、伪逆 | 公式写法 + 数值解 | ✅ |
|
||||
| E 度量 | 行列式、迹、秩、范数、条件数 | 部分可符号 | ✅ |
|
||||
| F 展示 | latex / ASCII / SVG 结构 / heatmap | ✅ | ✅ |
|
||||
| G 微积分 | 矩阵导数、Jacobian 积木 | 远期 | — |
|
||||
|
||||
**不做(首版):** 稀疏专用格式、GPU、分布式、完整 CAS 证明、通用张量网络、与 `lib/math` 高中标量混成一个巨模块。
|
||||
|
||||
---
|
||||
|
||||
## 3. 与现有 Marqdo 的衔接点
|
||||
|
||||
| 已有 | 用法 | 扩展时注意 |
|
||||
|------|------|------------|
|
||||
| `$$` + Matrix 数值字面量 | 小门矩阵、手算核对 | 保留;符号阵用 `MatrixSymbol` 或 `matrix.symbol`,勿与数值 Matrix 混为一谈 |
|
||||
| `lib/math` formula | 标量 simplify/diff/plot | **不**把大学线性代数塞进 `lib/math`(与 Q7 结论一致) |
|
||||
| view KaTeX | formula-card | 符号 MatExpr 的 `latex` 字符串直接喂 KaTeX |
|
||||
| `ext/quantum` Q7 linop | 量子密度 / 纠缠 | **经典 API 不复用 quantum 命名空间**;共享算法可在插件内私有复用,作者面分离 |
|
||||
| `plugins/*` ABI | 重数值 / SVG | 稠密分解与大图走 `plugins/linalg` |
|
||||
| GFM 表 | 数据即代码 | 矩阵输入:表或 `$$`;分解步骤:`@` 记录表 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 「大规模优化」具体指什么
|
||||
|
||||
在公式类语境下,优化 ≠ BLAS 微内核,而是:
|
||||
|
||||
1. **惰性**:`A*B*C` 保持乘积树,直到 `eval` / `explicit`
|
||||
2. **形状短路**:不相容维数在符号阶段报错,不跑数值
|
||||
3. **代数恒等**:`(A^{-1})^{-1}→A`,`(AB)^\top→B^\top A^\top`,`I*A→A`,分块 `block_collapse`
|
||||
4. **禁止爆炸展开**:Kronecker / 高维符号积默认不 `expand`
|
||||
5. **数值批处理**:同形状多 RHS、分解一次多用(`factorize` 对象)
|
||||
6. **展示成本**:大矩阵不默认内嵌完整 KaTeX 数字阵;结构图 + 摘要
|
||||
|
||||
---
|
||||
|
||||
## 5. 推荐产品叙事(一句)
|
||||
|
||||
**线性代数文档用公式写变换,用规则做化简,用结构图讲分解,用可控数值做验算——公式是一等公民,稠密矩阵是可选终点。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 参考链接
|
||||
|
||||
- SymPy Matrix Expressions: https://docs.sympy.org/latest/modules/matrices/expressions.html
|
||||
- SymPy Matrix derivatives (远期): https://docs.sympy.org/dev/explanation/modules/matrices/matrixderivatives.html
|
||||
- Symbolics.jl Symbolic Arrays: https://docs.sciml.ai/Symbolics/v6.54/manual/arrays/
|
||||
- LAFigureSpecs(教学结构图): https://github.com/ea42gh/LAFigureSpecs
|
||||
- CTAN drawmatrix: 矩阵形状示意
|
||||
- 既有:`doc/design/stdlib-math.md` · `doc/design/ext-quantum-q7.md`
|
||||
@@ -0,0 +1,102 @@
|
||||
# 路线图:宿主集成补齐(H0–H4)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active · 规划** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 缺口 | [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) |
|
||||
| 设计 | [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
|
||||
| 相关 | [ext-web.md](ext-web.md)(W/C 完结)· [ext-agent-optimize.md](ext-agent-optimize.md) · [agent-streaming.md](agent-streaming.md) |
|
||||
| 基线 | v0.3.6+ |
|
||||
|
||||
本文只跟踪**实现波次**。作者 API、ABI 边界、禁止项以设计文为准。
|
||||
|
||||
---
|
||||
|
||||
## 0. 目标回顾
|
||||
|
||||
让 `ext/web` + `ext/ai` 具备:同域 SSE 中继、HTTP→用户 `##`、MCP Server(至少 stdio)、跨模块 db/corpus 可发现——从而下游无需 Python 旁路进程。
|
||||
|
||||
---
|
||||
|
||||
## 1. 波次总表
|
||||
|
||||
| 波次 | 内容 | 关闭缺口 | 状态 |
|
||||
|------|------|----------|------|
|
||||
| **H0** | 文档契约:跨模块 `db` 传 `url`;`corpus_search` 调用前 `ensure_plugin` 说明;缺口索引进 `doc/README` | GAP-05 文档侧 | **done** |
|
||||
| **H1** | `app.proxy` / `configure proxy=`:上游 SSE/HTTP **流式**转发 | GAP-01 | **done** |
|
||||
| **H2** | `app.invoke` / `configure invoke=`:请求 → 白名单 `##` → JSON | GAP-02 | **done** |
|
||||
| **H3** | 跨模块插件对象 `_type` 分发修补 + `corpus_search` 自动 `ensure_plugin` | GAP-05 运行时 | **done** |
|
||||
| **H4** | `agent.mcp_server` + `serve transport=stdio`(HTTP 可选 H4b) | GAP-03 | **done**(stdio) |
|
||||
| **H4b** | MCP Streamable HTTP | GAP-03 余量 | **todo**(可选) |
|
||||
| **—** | 副端口 API | GAP-04 | **won't**:H1+H2 同端口关闭 |
|
||||
|
||||
建议顺序:**H1 → H2 → H3 → H4**(H2 的 invoke 内核可被 H4 工具复用,故 H2 不宜晚于 H4)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分波工作项
|
||||
|
||||
### H1 — 流式代理
|
||||
|
||||
1. `plugins/web`:`proxy.rs` + `web_app_proxy`;listen 挂流式 handler。
|
||||
2. `ext/web`:`## proxy` + `configure proxy=` 表。
|
||||
3. 金样 `web-proxy-sse-smoke`(mock 上游)。
|
||||
4. 教程/public 短节:「浏览器同域调 LLM」。
|
||||
|
||||
**完成定义:** `curl -N` 同域 path 收到多帧 SSE;密钥仅 env 注入。
|
||||
|
||||
### H2 — HTTP invoke
|
||||
|
||||
1. 共享或插件内 `invoke_fn`(解析 `库.成员`、映射 body)。
|
||||
2. `web_app_invoke` + 白名单。
|
||||
3. 金样:临时 `##` 写文件 + JSON 响应;拒绝未允许路径。
|
||||
4. 迁移说明:替换 `/store/*` + 外挂 `marqdo run`。
|
||||
|
||||
**完成定义:** 单进程 `listen` 下表单/fetch 可触发用户 `##`。
|
||||
|
||||
### H3 — db / corpus
|
||||
|
||||
1. 复现并修跨模块 `unknown object type db`(设计选项 A)。
|
||||
2. `ext/ai` `corpus_search` 路径 `ensure_plugin`。
|
||||
3. 金样 `web-db-cross-module-smoke` + corpus CLI run 金样。
|
||||
|
||||
### H4 — MCP Server
|
||||
|
||||
1. `plugins/agent` stdio JSON-RPC 最小子集:`initialize` / `tools/list` / `tools/call`。
|
||||
2. `ext/ai` `# mcp_server` · `## tool` · `## serve`。
|
||||
3. 工具调用复用 H2 `invoke_fn`。
|
||||
4. 金样夹具;文档对接 Cursor `mcp.json` 示例。
|
||||
|
||||
**H4b:** Streamable HTTP 与鉴权;不阻塞 H4 stdio 发版。
|
||||
|
||||
---
|
||||
|
||||
## 3. 刻意不做
|
||||
|
||||
| 项 | 原因 |
|
||||
|----|------|
|
||||
| 默认开启任意 `##` 远程执行 | 安全 |
|
||||
| 中继进 `lib/net` / `src/host` | 边界 |
|
||||
| 重开 W0–W7 内容站清单 | 已完结 |
|
||||
| 以副端口为推荐架构 | H1+H2 同端口即可 |
|
||||
| Dense embedding 默认 | OKF 路线不变 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 与发版
|
||||
|
||||
- 每波可随小版本发布;H1+H2 建议同一版本对外宣传「可去掉 llm_proxy」。
|
||||
- H4 可标 `ext/ai` 能力点,与「真 MCP 客户端」分列 Release notes。
|
||||
|
||||
---
|
||||
|
||||
## 5. 进度勾选(落地时改)
|
||||
|
||||
- [x] H0 缺口 + 补齐文档
|
||||
- [x] H1 proxy SSE
|
||||
- [x] H2 invoke
|
||||
- [x] H3 db/corpus
|
||||
- [x] H4 mcp_server stdio
|
||||
- [ ] H4b mcp http(可选)
|
||||
- [x] 研究文 GAP 状态改为 closed(H4b 除外)
|
||||
@@ -0,0 +1,126 @@
|
||||
# 官方扩展:`ext/linalg` 实现路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **L0–L6 + 公式文档面 F1–F3 已落地 · L7+ 远期** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| **锁定设计** | [design/ext-linalg.md](../design/ext-linalg.md) · [design/ext-linalg-formula-doc.md](../design/ext-linalg-formula-doc.md) |
|
||||
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) · [ext-quantum-q7.md](../design/ext-quantum-q7.md) |
|
||||
| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) |
|
||||
|
||||
本文只跟踪**实现阶段**。作者面、公式规则、展示以设计文为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标回顾(一句)
|
||||
|
||||
**可运行的线性代数公式文档**:矩阵公式可化简、可 KaTeX 展示;跑通即在规则集内正确;需要时再稠密求值与分解,并内嵌结构 SVG。
|
||||
|
||||
---
|
||||
|
||||
## 2. 落地阶段
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **L0** | CATALOG + `plugins/linalg` ping + L1 `ensure_plugin`;`ext add` 条目 | **done** |
|
||||
| **L1** | MatExpr:`symbol` / 稠密叶子 / `mul`·`add`·`T`·`inv`;`simplify` R1–R5;`latex`·`ascii`·`show` | **done** |
|
||||
| **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 摘要 | **done** |
|
||||
| **L6** | 复数 dtype;`lstsq`;`norm`/`cond`;主题令牌对齐 | **done** |
|
||||
| **F1** | 展示路径默认 simplify;公式文档金样 | **done** |
|
||||
| **F2** | 符号引入降噪;examples 讲义化 | **done** |
|
||||
| **F3** | 紧凑糖 + public「如何写公式文档」 | **done** |
|
||||
| **L7+** | 矩阵微积分 / 更大 BLAS 依赖(仅当用户明确要求) | **deferred** |
|
||||
|
||||
验收金样(规划路径):`tests/ext/linalg-*-smoke.mq.md`;示例:`examples/linalg-least-squares/`、`examples/linalg-svd/`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 每阶段出口检查
|
||||
|
||||
### L0
|
||||
|
||||
- [x] `ext/linalg` CATALOG 含 `linalg`
|
||||
- [x] 插件 `ping` → ok
|
||||
- [x] 文档:`marqdo ext add linalg`
|
||||
|
||||
### L1
|
||||
|
||||
- [x] `(AB)^\top` → `simplify` → `B^T*A^T`(无 dense)
|
||||
- [x] 形状错误含行列信息
|
||||
- [x] CLI `ascii` / `show` SVG 通道
|
||||
- [x] 中英 L1 各一 smoke
|
||||
|
||||
### L2
|
||||
|
||||
- [x] `from_formula` 吸收 `$$` 数值阵
|
||||
- [x] `solve` 与手算 2×2 一致
|
||||
- [x] 超维 `explicit` 硬错误(单元测护栏)
|
||||
|
||||
### L3
|
||||
|
||||
- [x] 分块乘 `collapse` 后块级正确
|
||||
- [x] Kronecker 默认不膨胀元素个数(惰性 `A⊗B`)
|
||||
|
||||
### L4
|
||||
|
||||
- [x] SVD/特征结果对象字段稳定
|
||||
- [x] SVG 含可断言标记(如 `data-linalg="eig"`)
|
||||
- [x] `factorize` + 二次 `solve` 复用(LU)
|
||||
|
||||
### L5
|
||||
|
||||
- [x] 至少 1 个 examples 可 `marqdo run`
|
||||
- [x] public/features 或 tutorial 短页
|
||||
- [x] skill / CHANGELOG Unreleased 条目
|
||||
|
||||
### L6
|
||||
|
||||
- [x] `lstsq` / `norm` / `cond` / `rank` 金样
|
||||
- [x] `dtype=complex` 基线(Frobenius;分解仍为实数)
|
||||
- [x] `draw theme=light|dark|bw` 与 quantum Q8 令牌对齐(`data-theme`)
|
||||
|
||||
### F1
|
||||
|
||||
- [x] `ascii` / `latex` / `show` 默认 simplify
|
||||
- [x] 金样:`.T` 后直接 `ascii` 得 `B^T*A^T`(无需显式 simplify)
|
||||
- [x] 设计文 [ext-linalg-formula-doc.md](../design/ext-linalg-formula-doc.md) 落地
|
||||
|
||||
### F2
|
||||
|
||||
- [x] 符号引入降噪(选定候选) — GFM `@` 表 + `la.declare`
|
||||
- [x] 至少 1 个 example 以代数面为主叙述 — `examples/linalg-transpose/`
|
||||
|
||||
### F3
|
||||
|
||||
- [x] `T_ascii` / `转置文本` 一步展示糖
|
||||
- [x] `explicit` 默认先 simplify(`raw=` 可关)
|
||||
- [x] public `07-linalg` / `07-线性代数`「如何写公式文档」
|
||||
|
||||
---
|
||||
|
||||
## 4. 依赖与并行
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| ABI v2 + ext CLI | 已有 |
|
||||
| view KaTeX / plot | 已有;L1 `show` 接现成通道 |
|
||||
| Release native zip | 随首次含 `plugins/linalg` 的发版接入 |
|
||||
| quantum 数值核 | **可选**私有复用;不阻塞 L1–L2 |
|
||||
|
||||
不阻塞项:浏览器 WASM 上的 linalg(默认 host/native;WASM 另议)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议开发顺序(下一手)
|
||||
|
||||
1. **L7+** 仅当用户明确要求更深符号(微积分等)。公式文档面 F1–F3 已收口。
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话
|
||||
|
||||
**代数面像讲义、计算面是步骤;跑通即在规则集内正确;每阶段都有可跑金样。**
|
||||
@@ -69,3 +69,4 @@
|
||||
| [design/ext-web.md](../design/ext-web.md) | **真理** |
|
||||
| [user-site.md](../design/user-site.md) | 静态站互补 |
|
||||
| [ext-quantum.md](ext-quantum.md) | 同属官方 ext + ABI + `ext add` |
|
||||
| [ext-hosting.md](ext-hosting.md) · [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) | **W/C 之后**:同域 SSE 中继、HTTP→`##`(不重开本表 W0–W7) |
|
||||
@@ -18,7 +18,7 @@
|
||||
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
|
||||
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
|
||||
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
|
||||
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
|
||||
| **标准库** | 核心 L1 已完成([stdlib-modules.md](../design/stdlib-modules.md));下一主线 = **中层 Mid**([stdlib-mid.md](../design/stdlib-mid.md) · [stdlib-mid 路线](stdlib-mid.md)) | **P2 完成;Mid M1–M6 规划中** |
|
||||
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
|
||||
|
||||
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
|
||||
|
||||
@@ -0,0 +1,199 @@
|
||||
# 路线图:中层标准库(数个版本)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **M1–M6 已落地** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 设计 | [stdlib-mid.md](../design/stdlib-mid.md) |
|
||||
| 相关 | [stdlib-modules.md](../design/stdlib-modules.md) · [next-phase.md](next-phase.md) · [ext-cli.md](../design/ext-cli.md) |
|
||||
|
||||
> **不预标 SemVer。** 每一波随当时产品发版合入;下文用 **M1…M6** 波次名。每波须可单独演示、可回滚。
|
||||
|
||||
---
|
||||
|
||||
## 0. 总序
|
||||
|
||||
```text
|
||||
M1 文本与编解码地基 re + encoding ← 最先解锁「无插件写库」
|
||||
M2 路径与文件中层 path + fs 加厚
|
||||
M3 完整性与机密 hash + secrets
|
||||
M4 表格数据与文本加厚 csv + text++
|
||||
M5 集合与 CLI 糖 table/listx + cli
|
||||
M6 可观测与标识 log + uuid(+ 可选 yaml)
|
||||
```
|
||||
|
||||
原则:
|
||||
|
||||
1. **先原语、后糖**:正则 / 编解码 / 路径先于 CLI 糖与日志格式。
|
||||
2. **每波必须有金样 + public 短页**;无文档不算完成。
|
||||
3. **并行约束**:不阻塞 `ext/linalg` 等已定领域工作;但新官方能力评审优先问 Mid。
|
||||
4. **插件冻结规则**:自 M1 起,官方新增「通用」ABI 插件默认 **拒绝**,除非设计文档论证无法用 host+L1。
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状缺口(开工依据)
|
||||
|
||||
| 能力 | 现状 | 后果 |
|
||||
|------|------|------|
|
||||
| 正则 | 无 | 校验、替换、简单解析只能 foreign 或插件 |
|
||||
| base64 / hex | 无(仅有 `url_encode`) | 令牌、摘要、嵌二进制文本困难 |
|
||||
| 路径代数 | `fs` 只做 I/O | 拼接靠字符串,跨平台易错 |
|
||||
| 哈希 / HMAC | 无 | 校验、缓存键、签名只能外联 |
|
||||
| CSV | 无 | 数据脚本推向外联 Python |
|
||||
| `lib/text` | 3 个包装函数 | 「有 text 库」名不副实 |
|
||||
| 安全随机 | 仅 `math.random` | 易误用于 token |
|
||||
| 结构化日志 / flags | 无 | 每个脚本自造 |
|
||||
|
||||
对照:Go 日常高频包(`regexp`、`encoding/*`、`crypto`、`path/filepath`、`slices`)与 Python「难写对才进 stdlib」——正是 M1–M5 的选型来源;**不**把 HTTP 服务端、数据库驱动塞进 Mid(见设计文 §3.2)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 波次明细
|
||||
|
||||
### M1 — 正则与编解码(最高优先) — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/re.mq.md` / `lib/正则.mq.md` | `is_match` / `find` / `find_all` / `replace` / `split` |
|
||||
| `lib/encoding.mq.md` / `lib/编码.mq.md` | `base64_*` / `hex_*` |
|
||||
| Host | `host_re_*`(`regex`)、`host_encoding_*`(无第三方编解码 crate) |
|
||||
| 金样 | `tests/lib/re-smoke` · `正则-烟测` · `encoding-smoke` · `编码-烟测` |
|
||||
| 文档 | [stdlib-re.md](../design/stdlib-re.md) · [stdlib-encoding.md](../design/stdlib-encoding.md) · public `08-re-encoding` |
|
||||
| 验收 | 无插件:邮箱式校验 + base64/hex 往返 |
|
||||
|
||||
**刻意不做:** 回溯引用极致兼容、替换回调、完整 PCRE 方言文档化——先 RE2/ Rust `regex` 语义并写清。
|
||||
|
||||
---
|
||||
|
||||
### M2 — 路径与文件中层 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/path.mq.md` / `lib/路径.mq.md` | `join` / `split` / `file_name` / `parent` / `extension` / `normalize` / `is_absolute` |
|
||||
| `lib/fs` 加厚 | `copy_file` / `move` / `make_temp`(文本边界;无 `read_bytes`) |
|
||||
| Host | `host_path_*`、`host_copy_file` / `host_move` / `host_make_temp` |
|
||||
| 金样 | `path-smoke` · `路径-烟测` · `fs-copy-move` · `文件-复制` |
|
||||
| 文档 | [stdlib-path.md](../design/stdlib-path.md) · [stdlib-fs-mid.md](../design/stdlib-fs-mid.md) · public `09-path-fs` |
|
||||
| 验收 | 规范化 + 沙箱内复制/移动 |
|
||||
|
||||
**刻意不做:** 完整 `shutil`、监视 `inotify`、权限 ACL 全家桶。
|
||||
|
||||
---
|
||||
|
||||
### M3 — 哈希与机密 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/hash.mq.md` / `lib/哈希.mq.md` | `sha256` / `sha1` / `md5` / `hmac_sha256` |
|
||||
| `lib/secrets.mq.md` / `lib/机密.mq.md` | `token_hex` / `token_urlsafe` |
|
||||
| Host | `host_hash_*`、`host_secrets_*`(`sha2`/`sha1`/`md-5`/`hmac`/`getrandom`) |
|
||||
| 金样 | `hash-smoke` · `哈希-烟测` · `secrets-smoke` · `机密-烟测` |
|
||||
| 文档 | [stdlib-hash.md](../design/stdlib-hash.md) · [stdlib-secrets.md](../design/stdlib-secrets.md) · public `10-hash-secrets` |
|
||||
| 验收 | 已知向量 + 令牌长度 |
|
||||
|
||||
**刻意不做:** 密码哈希(Argon2/bcrypt)、完整 TLS、证书管理——仍属服务端/安全产品。
|
||||
|
||||
---
|
||||
|
||||
### M4 — CSV 与文本加厚 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/csv.mq.md` / `lib/逗号表.mq.md` | `parse` / `stringify`(首行表头 → list of maps) |
|
||||
| `lib/text` / `文本` 加厚 | `contains` / `starts_with` / `ends_with` / `replace` / `to_upper`/`to_lower` / `repeat` / `pad` |
|
||||
| Host | `host_csv_*`、`host_text_*` |
|
||||
| 金样 | `csv-smoke` · `逗号表-烟测` · `text-mid-smoke` · `文本-加厚-烟测` |
|
||||
| 文档 | [stdlib-csv.md](../design/stdlib-csv.md) · [stdlib-text-mid.md](../design/stdlib-text-mid.md) · public `11-csv-text` |
|
||||
| 验收 | CSV 往返 + 文本清洗小例 |
|
||||
|
||||
**可选同波:** 极简 `format`(`{name}` 替换),若与引用语法冲突则延后。
|
||||
|
||||
---
|
||||
|
||||
### M5 — 集合算法与 CLI — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/table` / `表` 加厚 | `sort` / `sort_by` / `unique` / `chunk` / `zip` / `flatten`(`reverse` 已有) |
|
||||
| `lib/cli.mq.md` / `lib/命令行.mq.md` | `parse`(`--k v` / `--k=v` / `--flag`;位置参 `_`) |
|
||||
| Host | `host_list_sort*` / `unique` / `chunk` / `zip` / `flatten`、`host_cli_parse` |
|
||||
| 金样 | `table-list-mid` · `cli-sort-smoke` · `表-命令行-烟测` |
|
||||
| 文档 | [stdlib-list-cli.md](../design/stdlib-list-cli.md) · public `12-list-cli` |
|
||||
| 验收 | CSV 按键排序 + 参数解析 |
|
||||
|
||||
**刻意不做:** 泛型迭代器协议、惰性流、完整 argparse 互斥组。
|
||||
|
||||
---
|
||||
|
||||
### M6 — 日志、UUID、收口 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/log.mq.md` / `lib/日志.mq.md` | `debug`/`info`/`warn`/`error`;level 过滤;一行文本 |
|
||||
| `lib/uuid.mq.md` / `lib/标识.mq.md` | `v4` |
|
||||
| Host | `host_log_set_level` / `host_log_line`、`host_uuid_v4` |
|
||||
| 金样 | `log-uuid-smoke` · `日志-标识-烟测` |
|
||||
| 文档 | [stdlib-log-uuid.md](../design/stdlib-log-uuid.md) · public `13-log-uuid` |
|
||||
| 文档收口 | `stdlib-modules.md` 总表;设计文状态 → **M1–M6 已落地** |
|
||||
| 可选未做 | `yaml` 只读子集(默认不做) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 跨波次工程清单
|
||||
|
||||
每波共用:
|
||||
|
||||
- [ ] 中英 L1 对称([stdlib-i18n.md](../design/stdlib-i18n.md))
|
||||
- [ ] `host_*` 形参在 L1 **全量转发**([stdlib-modules.md](../design/stdlib-modules.md) §2.1)
|
||||
- [ ] 双后端金样(tree + bytecode,若该 host 已接线)
|
||||
- [ ] WASM:标注 `host-only` 或实现 stub
|
||||
- [ ] CHANGELOG「标准库」条目
|
||||
- [ ] skill `examples.md` 增加 Mid 惯用写法(GFM 优先)
|
||||
|
||||
宿主膨胀守卫:
|
||||
|
||||
- 新增 crate 须在 PR/设计中写清:**为何不能纯 mq**、**features 如何裁剪**、**许可证**。
|
||||
- 禁止借 Mid 把 `ext/web` 的服务端栈链进主二进制。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与官方扩展的互动(减插件)
|
||||
|
||||
| 扩展 | Mid 落地后可做的减负 |
|
||||
|------|----------------------|
|
||||
| `ext/web` | 路由/校验用 `re`;ETag/缓存键用 `hash`;静态路径用 `path` |
|
||||
| `ext/agent` | 工具参数校验、密钥材料用 `secrets`/`hash`(领域核仍插件) |
|
||||
| `ext/ai/llm` | 头/体编解码走 `encoding` |
|
||||
| `ext/linalg` / `quantum` | **不**迁入 Mid;继续插件;仅共用 `path`/`hash` 等通用面 |
|
||||
|
||||
跟踪方式:某波完成后,开短 issue/清单「ext X 可删除的原生辅助」,不强迫同波大改。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议人力切分(示意)
|
||||
|
||||
| 波次 | 大致体量 | 可演示产物 |
|
||||
|------|----------|------------|
|
||||
| M1 | 中 | 「正则替换 + base64 往返」用户页 |
|
||||
| M2 | 中 | 「安全拼接路径写文件」 |
|
||||
| M3 | 小–中 | 「下载内容 sha256 校验」 |
|
||||
| M4 | 中 | 「CSV → 表 → 打印」 |
|
||||
| M5 | 小–中 | 「零插件数据 CLI」 |
|
||||
| M6 | 小 | 「带 log level 的脚本」 |
|
||||
|
||||
若只能开一条线:**M1 → M3 → M2 → M4 → M5 → M6**(完整性校验常比路径代数更刚需时,M3 可紧贴 M1)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 完成定义(整条 Mid 叙事)
|
||||
|
||||
当 M1–M6 完成时,对外可宣称:
|
||||
|
||||
> Marqdo 自带中层标准库:正则、编解码、路径、哈希、CSV、加厚文本与集合/CLI 糖,以及日志与 UUID;**写通用脚本与多数扩展库不再需要原生插件。**
|
||||
> 插件保留给 web 运行时、智能体、量子与线性代数等**领域引擎**。
|
||||
|
||||
---
|
||||
|
||||
## 7. 一句话
|
||||
|
||||
**按 M1→M6 把通用原语沉进 `lib/`,用数个发版周期换掉「事事插件」——领域 `ext/` 继续尖,语言本体变宽。**
|
||||
@@ -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/).
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Least squares via lstsq
|
||||
description: Overdetermined Ax≈b with ext/linalg lstsq + 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` using `lstsq` (QR path). 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" theme="light" path="ls-heatmap.svg"*
|
||||
|
||||
*`ls` = > la.lstsq a=`A` b=`b`*
|
||||
*`x` = ls[^x]*
|
||||
*`resid` = ls[^residual_fro]*
|
||||
|
||||
> print text=`x`
|
||||
> print text=`resid`
|
||||
> print text=ls-ok
|
||||
@@ -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/).
|
||||
@@ -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. Prefer matrix values and methods; `factorize` / `draw` stay explicit for teaching SVGs.
|
||||
|
||||
# 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" theme="light" path="svd-structure.svg"*
|
||||
*`hm` = > la.draw factor=`M` kind="hinton" path="svd-hinton.svg"*
|
||||
|
||||
> print text=`S`
|
||||
> print text=svd-ok
|
||||
@@ -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).
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
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`*
|
||||
*`t` = > `P`.T_ascii*
|
||||
> print text=`t`
|
||||
1. `t` == "B^T*A^T"
|
||||
> print text=identity-ok
|
||||
2. *
|
||||
> print text=identity-fail
|
||||
+64
-12
@@ -6,7 +6,7 @@ import json:lib/json.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
import time:lib/time.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
import wb:lib/writeback.mq.md
|
||||
import subtask:lib/subtask.mq.md
|
||||
import plugin:lib/plugin.mq.md
|
||||
---
|
||||
@@ -130,7 +130,7 @@ Allowlist check, then invoke the runbook `##` via `lib/subtask` (`spawn fn=` →
|
||||
Build a runnable workbook. `skeleton=single` (default): one worker `step`. `skeleton=dual`: research then write agents. On success the parent chooses DONE; runtime `agent_workbook_solidify` freezes the answer.
|
||||
|
||||
*q = > json.quote text=`goal`*
|
||||
*esc = > json.parse text={"h":"---\ntitle: agent workbook\nimport llm:ext/ai/llm.mq.md\nimport agent:ext/ai/agent.mq.md\nimport json:lib/json.mq.md\nimport sys:lib/sys.mq.md\nimport writeback:lib/writeback.mq.md\nimport subtask:lib/subtask.mq.md\n---\n\n# Goal\n\nParent goal is embedded as JSON in # main.\n\n## Solidify\n\nWhen the child returns a good value, parent DECISION: DONE — runtime agent_workbook_solidify freezes the answer as **return** (do not invent long FIND/REPLACE).\n\n# main\n\n> llm.load_env\n\n","s1":"\u002a\u0060model\u0060 = > llm.llm \u002a\n","s2":"\u002a\u0060tools\u0060 = > json.parse text=[] \u002a\n","s3":"\u002a\u0060worker\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You are a workbook worker. tools=[] means never CALL. Finish the task with a direct final answer; do not invent tools. \u002a\n","s4":"\u002a\u0060wrap\u0060 = > json.parse text={\"task\":","s5":"} \u002a\n","s6":"\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task \u002a\n","s7":"\u002a\u0060out\u0060 = > \u0060worker\u0060.step task=\u0060task\u0060 stream=True \u002a\n","s7b":"\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result \u002a\n","s8":"\u002a\u002a\u0060text\u0060\u002a\u002a\n","d3":"\u002a\u0060research\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You gather facts for the goal. Be concise. Do not invent tools. \u002a\n","d3b":"\u002a\u0060writer\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You write the final answer from research notes. Do not invent tools. \u002a\n","d4":"\u002a\u0060wrap\u0060 = > json.parse text={\"task\":","d5":"} \u002a\n","d6":"\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task \u002a\n","d7":"\u002a\u0060notes\u0060 = > \u0060research\u0060.step task=\u0060task\u0060 stream=True \u002a\n","d8":"\u002a\u0060ns\u0060 = > json.stringify value=\u0060notes\u0060 \u002a\n","d9":"\u002a\u0060wt\u0060 = Write the final answer. Research notes: \u002a\n","d10":"\u002a\u0060wt\u0060 = \u0060wt\u0060 + \u0060ns\u0060 \u002a\n","d11":"\u002a\u0060out\u0060 = > \u0060writer\u0060.step task=\u0060wt\u0060 stream=True \u002a\n","d11b":"\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result \u002a\n","d12":"\u002a\u002a\u0060text\u0060\u002a\u002a\n"}*
|
||||
*esc = > json.parse text={"h":"---\ntitle: agent workbook\nimport llm:ext/ai/llm.mq.md\nimport agent:ext/ai/agent.mq.md\nimport json:lib/json.mq.md\nimport sys:lib/sys.mq.md\nimport wb:lib/writeback.mq.md\nimport subtask:lib/subtask.mq.md\n---\n\n# Goal\n\nParent goal is embedded as JSON in # main.\n\n## Solidify\n\nWhen the child returns a good value, parent DECISION: DONE — runtime agent_workbook_solidify freezes the answer as **return** (do not invent long FIND/REPLACE).\n\n# main\n\n> llm.load_env\n\n","s1":"\u002a\u0060model\u0060 = > llm.llm \u002a\n","s2":"\u002a\u0060tools\u0060 = > json.parse text=[] \u002a\n","s3":"\u002a\u0060worker\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You are a workbook worker. tools=[] means never CALL. Finish the task with a direct final answer; do not invent tools. \u002a\n","s4":"\u002a\u0060wrap\u0060 = > json.parse text={\"task\":","s5":"} \u002a\n","s6":"\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task \u002a\n","s7":"\u002a\u0060out\u0060 = > \u0060worker\u0060.step task=\u0060task\u0060 stream=True \u002a\n","s7b":"\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result \u002a\n","s8":"\u002a\u002a\u0060text\u0060\u002a\u002a\n","d3":"\u002a\u0060research\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You gather facts for the goal. Be concise. Do not invent tools. \u002a\n","d3b":"\u002a\u0060writer\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You write the final answer from research notes. Do not invent tools. \u002a\n","d4":"\u002a\u0060wrap\u0060 = > json.parse text={\"task\":","d5":"} \u002a\n","d6":"\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task \u002a\n","d7":"\u002a\u0060notes\u0060 = > \u0060research\u0060.step task=\u0060task\u0060 stream=True \u002a\n","d8":"\u002a\u0060ns\u0060 = > json.stringify value=\u0060notes\u0060 \u002a\n","d9":"\u002a\u0060wt\u0060 = Write the final answer. Research notes: \u002a\n","d10":"\u002a\u0060wt\u0060 = \u0060wt\u0060 + \u0060ns\u0060 \u002a\n","d11":"\u002a\u0060out\u0060 = > \u0060writer\u0060.step task=\u0060wt\u0060 stream=True \u002a\n","d11b":"\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result \u002a\n","d12":"\u002a\u002a\u0060text\u0060\u002a\u002a\n"}*
|
||||
*h = > json.get value=`esc` key="h"*
|
||||
*s1 = > json.get value=`esc` key="s1"*
|
||||
*s2 = > json.get value=`esc` key="s2"*
|
||||
@@ -171,7 +171,7 @@ Build a runnable workbook. `skeleton=single` (default): one worker `step`. `skel
|
||||
Structured observation for the parent developer-agent: source, named writeback slots, exit code, optional child return value, and quiet-captured I/O.
|
||||
|
||||
*source = > fs.read_text path=`path`*
|
||||
*slots = > writeback.scan_path path=`path`*
|
||||
*slots = > wb.scan_path path=`path`*
|
||||
*obs = > json.parse text={"path":""}*
|
||||
*obs = > json.set map=`obs` key="path" value=`path`*
|
||||
*obs = > json.set map=`obs` key="source" value=`source`*
|
||||
@@ -388,6 +388,15 @@ Callable dotted names (whitelist for `CALL:lib…`) plus static module file list
|
||||
|
||||
Local keyword search over `.md` / `.mq.md` / `.txt` under `root`. Returns ranked excerpts. **Evidence only** — runnable workbook / OKF skill stays authority (`authority=workbook`).
|
||||
|
||||
Ensures the native agent plugin is loaded so plain `marqdo run` (without constructing `# agent`) can call this.
|
||||
|
||||
*p = > plugin.native_path name="agent"*
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent)
|
||||
> sys.exit code=1
|
||||
|
||||
**> agent_corpus_search query=`query` root=`root` limit=`limit`**
|
||||
|
||||
---
|
||||
@@ -1463,7 +1472,7 @@ Always append `done` and attach `events` on the result map (process audit even w
|
||||
|
||||
1. `trace`
|
||||
*body = > json.stringify value=`events`*
|
||||
> host_writeback_record value=`body` key="trace"
|
||||
> wb.record value=`body` key="trace"
|
||||
2. *
|
||||
*_ = 1*
|
||||
|
||||
@@ -1606,9 +1615,9 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st
|
||||
*body = > json.stringify value=`out`*
|
||||
*st = > json.get value=`out` key="status"*
|
||||
1. `st` == "ok"
|
||||
> host_writeback_record value=`body` key="ok"
|
||||
> wb.record value=`body` key="ok"
|
||||
2. *
|
||||
> host_writeback_record value=`body` key="error"
|
||||
> wb.record value=`body` key="error"
|
||||
2. *
|
||||
*_ = 1*
|
||||
|
||||
@@ -1711,7 +1720,7 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
|
||||
*events = > plan_append_round events=`events` round=1 workbook=`path` exit_code=`code` result=`child_val` stream=`stream` echo=`echo`*
|
||||
1. `writeback`
|
||||
*body = > json.stringify value=`out`*
|
||||
> host_writeback_record value=`body` key="ok"
|
||||
> wb.record value=`body` key="ok"
|
||||
2. *
|
||||
*_ = 1*
|
||||
*out = > plan_finish_stream out=`out` events=`events` stream=`stream` trace=`trace` result=`child_val`*
|
||||
@@ -1768,7 +1777,7 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
|
||||
*events = > plan_append_round events=`events` round=1 workbook=`path` exit_code=`code` result=`child_val` stream=`stream` echo=`echo`*
|
||||
1. `writeback`
|
||||
*body = > json.stringify value=`out`*
|
||||
> host_writeback_record value=`body` key="ok"
|
||||
> wb.record value=`body` key="ok"
|
||||
2. *
|
||||
*_ = 1*
|
||||
*out = > plan_finish_stream out=`out` events=`events` stream=`stream` trace=`trace` result=`child_val`*
|
||||
@@ -1832,7 +1841,7 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
|
||||
*events = > plan_append_round events=`events` round=1 workbook=`path` exit_code=`code` result=`child_val` stream=`stream` echo=`echo`*
|
||||
1. `writeback`
|
||||
*body = > json.stringify value=`out`*
|
||||
> host_writeback_record value=`body` key="ok"
|
||||
> wb.record value=`body` key="ok"
|
||||
2. *
|
||||
*_ = 1*
|
||||
*out = > plan_finish_stream out=`out` events=`events` stream=`stream` trace=`trace` result=`child_val`*
|
||||
@@ -1910,7 +1919,7 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
|
||||
*out = > json.set map=`out` key="cache" value="bypass"*
|
||||
1. `writeback`
|
||||
*body = > json.stringify value=`out`*
|
||||
> host_writeback_record value=`body` key="ok"
|
||||
> wb.record value=`body` key="ok"
|
||||
2. *
|
||||
*_ = 1*
|
||||
*out = > plan_finish_stream out=`out` events=`events` stream=`stream` trace=`trace`*
|
||||
@@ -2091,11 +2100,54 @@ Deterministic success stop (loop engineering): when the child already returned a
|
||||
1. `writeback`
|
||||
*body = > json.stringify value=`out`*
|
||||
1. `status` == "ok"
|
||||
> host_writeback_record value=`body` key="ok"
|
||||
> wb.record value=`body` key="ok"
|
||||
2. *
|
||||
> host_writeback_record value=`body` key="error"
|
||||
> wb.record value=`body` key="error"
|
||||
2. *
|
||||
*_ = 1*
|
||||
|
||||
*out = > plan_finish_stream out=`out` events=`events` stream=`stream` trace=`trace` result=`plan_result`*
|
||||
**out**
|
||||
|
||||
---
|
||||
|
||||
# mcp_server
|
||||
+ `name`=marqdo
|
||||
|
||||
Minimal MCP **Server** host (stdio JSON-RPC). Tools point at entry-module `lib.member` functions (same bridge as `ext/web` invoke). Evidence/results may carry `authority=workbook`.
|
||||
|
||||
*p = > plugin.native_path name="agent"*
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/ai/agent: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent)
|
||||
> sys.exit code=1
|
||||
|
||||
*h = > json.parse text={"_type":"mcp_server","tools":[]}*
|
||||
*h = > json.set map=`h` key="name" value=`name`*
|
||||
**h**
|
||||
|
||||
## tool
|
||||
+ `name`
|
||||
+ `fn`
|
||||
+ `description`=""
|
||||
|
||||
Register one tool. `fn` must be `lib.member` imported on the entry workbook.
|
||||
|
||||
*tools = > json.get value=`self` key="tools"*
|
||||
*row = > json.parse text={"name":"","fn":"","description":""}*
|
||||
*row = > json.set map=`row` key="name" value=`name`*
|
||||
*row = > json.set map=`row` key="fn" value=`fn`*
|
||||
*row = > json.set map=`row` key="description" value=`description`*
|
||||
*tools = > json.append list=`tools` item=`row`*
|
||||
*h = > json.set map=`self` key="tools" value=`tools`*
|
||||
**h**
|
||||
|
||||
## serve
|
||||
+ `transport`=stdio
|
||||
|
||||
Block on stdio MCP (`initialize` / `tools/list` / `tools/call`). HTTP transport is H4b.
|
||||
|
||||
*name = > json.get value=`self` key="name"*
|
||||
*tools = > json.get value=`self` key="tools"*
|
||||
**> agent_mcp_serve name=`name` tools=`tools` transport=`transport`**
|
||||
+2
-4
@@ -17,7 +17,7 @@ Load `.env` from cwd (optional named arg `path=`). Does not override existing va
|
||||
## stream_result
|
||||
+ `events`
|
||||
|
||||
Reduce a `complete stream=True` event list to the final `done.result` text (or `error.message`). Unknown event types abort.
|
||||
Reduce a `complete stream=True` event list to the final `done.result` text (or `error.message`). Unknown types (e.g. `reasoning`) are ignored.
|
||||
|
||||
*answer = ""*
|
||||
|
||||
@@ -29,9 +29,7 @@ Reduce a `complete stream=True` event list to the final `done.result` text (or `
|
||||
*answer = ev[^message]*
|
||||
3. `t` == "delta"
|
||||
4. *
|
||||
> print text=ext/ai/llm: unexpected SSE event type
|
||||
> print text=`t`
|
||||
> sys.exit code=1
|
||||
*_ = 1*
|
||||
|
||||
**answer**
|
||||
|
||||
|
||||
+2
-4
@@ -17,7 +17,7 @@ import json:lib/json.mq.md
|
||||
## 流式结果
|
||||
+ `事件`
|
||||
|
||||
把 `运行 流式=真` 的事件列表收成最终 `done.result`(或 `error.message`)。未知事件类型直接失败。
|
||||
把 `运行 流式=真` 的事件列表收成最终 `done.result`(或 `error.message`)。未知类型(如 `reasoning`)忽略。
|
||||
|
||||
*answer = ""*
|
||||
|
||||
@@ -29,9 +29,7 @@ import json:lib/json.mq.md
|
||||
*answer = ev[^message]*
|
||||
3. `t` == "delta"
|
||||
4. *
|
||||
> 打印 内容=ext/ai/大模型: 未预期的 SSE 事件类型
|
||||
> 打印 内容=`t`
|
||||
> 系统.退出 码=1
|
||||
*_ = 1*
|
||||
|
||||
**answer**
|
||||
|
||||
|
||||
+2
-2
@@ -175,9 +175,9 @@ import json:lib/json.mq.md
|
||||
*body = > json.stringify value=`out`*
|
||||
*st = > json.get value=`out` key="status"*
|
||||
1. `st` == "ok"
|
||||
> host_writeback_record value=`body` key="ok"
|
||||
> 自写回.写回 值=`body` 键="ok"
|
||||
2. *
|
||||
> host_writeback_record value=`body` key="error"
|
||||
> 自写回.写回 值=`body` 键="error"
|
||||
2. *
|
||||
*_ = 1*
|
||||
|
||||
|
||||
@@ -0,0 +1,372 @@
|
||||
---
|
||||
title: ext/linalg/linalg
|
||||
description: Formula-first linear algebra (English). MatExpr simplify + display; ABI plugin.
|
||||
import plugin:lib/plugin.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
---
|
||||
|
||||
## ensure_plugin
|
||||
|
||||
Load the ABI v2 `linalg` plugin once.
|
||||
|
||||
*p = > plugin.native_path name="linalg"*
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/linalg: native linalg plugin not found (build marqdo_plugin_linalg or marqdo ext add linalg)
|
||||
> sys.exit code=1
|
||||
****
|
||||
|
||||
## ping
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_ping**
|
||||
|
||||
## mul
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
Matrix product (lazy MatMul; shape-checked).
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_mul a=`a` b=`b`**
|
||||
|
||||
## add
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_add a=`a` b=`b`**
|
||||
|
||||
## sub
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_sub a=`a` b=`b`**
|
||||
|
||||
## transpose
|
||||
+ `expr`
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_transpose expr=`expr`**
|
||||
|
||||
## inv
|
||||
+ `expr`
|
||||
|
||||
Symbolic inverse (lazy).
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_inv expr=`expr`**
|
||||
|
||||
## simplify
|
||||
+ `expr`
|
||||
|
||||
Apply MatExpr rewrite rules (R1–R5).
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_simplify expr=`expr`**
|
||||
|
||||
## ascii
|
||||
+ `expr`
|
||||
+ `raw`=False
|
||||
|
||||
Display ASCII (default **simplify** first). Pass `raw=True` to keep the written tree.
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_ascii expr=`expr` raw=`raw`**
|
||||
|
||||
## latex
|
||||
+ `expr`
|
||||
+ `raw`=False
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_latex expr=`expr` raw=`raw`**
|
||||
|
||||
## shape
|
||||
+ `expr`
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_shape expr=`expr`**
|
||||
|
||||
## show
|
||||
+ `expr`
|
||||
+ `path`=None
|
||||
+ `raw`=False
|
||||
|
||||
Record a formula SVG via host plot channel (default simplify). Returns the expr map.
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_show expr=`expr` path=`path` raw=`raw`**
|
||||
|
||||
## eye
|
||||
+ `n`
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_eye n=`n`**
|
||||
|
||||
## zeros
|
||||
+ `rows`
|
||||
+ `cols`
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_zeros rows=`rows` cols=`cols`**
|
||||
|
||||
## from_list
|
||||
+ `data`
|
||||
|
||||
Dense leaf from nested list.
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_from_list data=`data`**
|
||||
|
||||
## from_formula
|
||||
+ `formula`
|
||||
|
||||
Absorb a `$$` numeric matrix formula (or nested list / dense map) as a dense leaf.
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_from_formula formula=`formula`**
|
||||
|
||||
## explicit
|
||||
+ `expr`
|
||||
+ `raw`=False
|
||||
|
||||
Evaluate to dense (default **simplify** first).
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_explicit expr=`expr` raw=`raw`**
|
||||
|
||||
## det
|
||||
+ `expr`
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_det expr=`expr`**
|
||||
|
||||
## trace
|
||||
+ `expr`
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_trace expr=`expr`**
|
||||
|
||||
## solve
|
||||
+ `a`=None
|
||||
+ `b`
|
||||
+ `factor`=None
|
||||
|
||||
Solve `a x = b` (Gaussian elimination), or reuse `factorize kind=lu` via `factor` + `b`.
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_solve a=`a` b=`b` factor=`factor`**
|
||||
|
||||
## matmul
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
Dense matrix product → `linalg_dense`.
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_matmul a=`a` b=`b`**
|
||||
|
||||
## kron
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
Lazy Kronecker product (does not expand).
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_kron a=`a` b=`b`**
|
||||
|
||||
## block
|
||||
+ `blocks`
|
||||
|
||||
Block matrix from a nested list of expressions.
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_block blocks=`blocks`**
|
||||
|
||||
## collapse
|
||||
+ `expr`
|
||||
|
||||
Block-level collapse (`Block*Block` → block of products).
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_collapse expr=`expr`**
|
||||
|
||||
## factorize
|
||||
+ `matrix`
|
||||
+ `kind`="lu"
|
||||
|
||||
Dense factorization → `linalg_factor` (`kind` = `lu` | `qr` | `svd` | `eig` | `chol`).
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_factorize matrix=`matrix` kind=`kind`**
|
||||
|
||||
## draw
|
||||
+ `factor`
|
||||
+ `kind`=None
|
||||
+ `path`=None
|
||||
+ `theme`="light"
|
||||
|
||||
Structure SVG (`eig` | `svd` | `qr` | `lu` | `ge` | `chol` | `structure` | `heatmap` | `hinton`). Theme tokens match quantum Q8: `light` | `dark` | `bw`.
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_draw factor=`factor` kind=`kind` path=`path` theme=`theme`**
|
||||
|
||||
## lstsq
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
Least squares `min ||a x - b||` (QR if tall, SVD if wide).
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_lstsq a=`a` b=`b`**
|
||||
|
||||
## norm
|
||||
+ `expr`
|
||||
+ `ord`="fro"
|
||||
|
||||
Matrix norm: `fro` | `1` | `inf` | `2`. Complex dense supports `fro` only.
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_norm expr=`expr` ord=`ord`**
|
||||
|
||||
## cond
|
||||
+ `expr`
|
||||
|
||||
Spectral condition number via SVD (`ord=2`).
|
||||
|
||||
> ensure_plugin
|
||||
**> linalg_cond expr=`expr`**
|
||||
|
||||
## rank
|
||||
+ `expr`
|
||||
|
||||
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` type_tag="matrix"**
|
||||
|
||||
## symbol
|
||||
+ `name`
|
||||
+ `rows`
|
||||
+ `cols`
|
||||
|
||||
Abstract matrix symbol. Returns a `# matrix` instance (supports `+` / `*` and methods).
|
||||
|
||||
> ensure_plugin
|
||||
**> matrix name=`name` rows=`rows` cols=`cols`**
|
||||
|
||||
# matrix
|
||||
+ `name`=None
|
||||
+ `rows`=None
|
||||
+ `cols`=None
|
||||
+ `data`=None
|
||||
+ `formula`=None
|
||||
+ `n`=None
|
||||
|
||||
Matrix value (`_type=matrix`). Prefer infix `A + B` / `A * B`, or methods `` `A`.T ``.
|
||||
|
||||
> ensure_plugin
|
||||
1. `formula`
|
||||
**> linalg_from_formula formula=`formula`**
|
||||
2. `data`
|
||||
**> linalg_from_list data=`data`**
|
||||
3. `name`
|
||||
**> linalg_symbol name=`name` rows=`rows` cols=`cols`**
|
||||
4. `n`
|
||||
**> linalg_eye n=`n`**
|
||||
5. `rows`
|
||||
**> linalg_zeros rows=`rows` cols=`cols`**
|
||||
6. *
|
||||
> print text=ext/linalg: matrix needs name= / data= / formula= / n= / rows=
|
||||
**None**
|
||||
|
||||
## T
|
||||
|
||||
**> linalg_transpose expr=`self`**
|
||||
|
||||
## T_ascii
|
||||
|
||||
Transpose then display ASCII (auto-simplified). Handy for lecture identities.
|
||||
|
||||
*`Pt` = > linalg_transpose expr=`self`*
|
||||
**> linalg_ascii expr=`Pt` raw=False**
|
||||
|
||||
## add
|
||||
+ `b`
|
||||
|
||||
**> linalg_add a=`self` b=`b`**
|
||||
|
||||
## sub
|
||||
+ `b`
|
||||
|
||||
**> linalg_sub a=`self` b=`b`**
|
||||
|
||||
## mul
|
||||
+ `b`
|
||||
|
||||
**> linalg_mul a=`self` b=`b`**
|
||||
|
||||
## inv
|
||||
|
||||
**> linalg_inv expr=`self`**
|
||||
|
||||
## simplify
|
||||
|
||||
**> linalg_simplify expr=`self`**
|
||||
|
||||
## ascii
|
||||
|
||||
**> linalg_ascii expr=`self` raw=False**
|
||||
|
||||
## latex
|
||||
|
||||
**> linalg_latex expr=`self` raw=False**
|
||||
|
||||
## explicit
|
||||
|
||||
**> linalg_explicit expr=`self` raw=False**
|
||||
|
||||
## det
|
||||
|
||||
**> linalg_det expr=`self`**
|
||||
|
||||
## trace
|
||||
|
||||
**> linalg_trace expr=`self`**
|
||||
|
||||
## show
|
||||
+ `path`=None
|
||||
+ `raw`=False
|
||||
|
||||
**> linalg_show expr=`self` path=`path` raw=`raw`**
|
||||
|
||||
## eye
|
||||
+ `n`
|
||||
|
||||
**> linalg_eye n=`n`**
|
||||
|
||||
## zeros
|
||||
+ `rows`
|
||||
+ `cols`
|
||||
|
||||
**> linalg_zeros rows=`rows` cols=`cols`**
|
||||
|
||||
## from_list
|
||||
+ `data`
|
||||
|
||||
**> linalg_from_list data=`data`**
|
||||
|
||||
## from_formula
|
||||
+ `formula`
|
||||
|
||||
**> linalg_from_formula formula=`formula`**
|
||||
@@ -0,0 +1,367 @@
|
||||
---
|
||||
title: ext/linalg/线性代数
|
||||
description: 公式优先的线性代数(中文)。矩阵表达式化简与展示;ABI 插件。
|
||||
import plugin:lib/plugin.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
---
|
||||
|
||||
## 确保插件
|
||||
|
||||
加载 ABI v2 `linalg` 插件一次。
|
||||
|
||||
*p = > plugin.native_path name="linalg"*
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/linalg: 未找到原生 linalg 插件(请 build marqdo_plugin_linalg 或 marqdo ext add linalg)
|
||||
> sys.exit code=1
|
||||
****
|
||||
|
||||
## 探测
|
||||
|
||||
> 确保插件
|
||||
**> linalg_ping**
|
||||
|
||||
## 乘
|
||||
+ `左`
|
||||
+ `右`
|
||||
|
||||
矩阵乘(惰性;检查形状)。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_mul a=`左` b=`右`**
|
||||
|
||||
## 加
|
||||
+ `左`
|
||||
+ `右`
|
||||
|
||||
> 确保插件
|
||||
**> linalg_add a=`左` b=`右`**
|
||||
|
||||
## 减
|
||||
+ `左`
|
||||
+ `右`
|
||||
|
||||
> 确保插件
|
||||
**> linalg_sub a=`左` b=`右`**
|
||||
|
||||
## 转置
|
||||
+ `式`
|
||||
|
||||
> 确保插件
|
||||
**> linalg_transpose expr=`式`**
|
||||
|
||||
## 逆
|
||||
+ `式`
|
||||
|
||||
> 确保插件
|
||||
**> linalg_inv expr=`式`**
|
||||
|
||||
## 化简
|
||||
+ `式`
|
||||
|
||||
应用矩阵表达式重写规则(R1–R5)。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_simplify expr=`式`**
|
||||
|
||||
## 文本
|
||||
+ `式`
|
||||
+ `原始`=False
|
||||
|
||||
展示 ASCII(默认先 **化简**)。`原始=True` 保留书写树。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_ascii expr=`式` raw=`原始`**
|
||||
|
||||
## 乳胶
|
||||
+ `式`
|
||||
+ `原始`=False
|
||||
|
||||
> 确保插件
|
||||
**> linalg_latex expr=`式` raw=`原始`**
|
||||
|
||||
## 形状
|
||||
+ `式`
|
||||
|
||||
> 确保插件
|
||||
**> linalg_shape expr=`式`**
|
||||
|
||||
## 展示
|
||||
+ `式`
|
||||
+ `路径`=None
|
||||
+ `原始`=False
|
||||
|
||||
写入公式 SVG(默认化简)。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_show expr=`式` path=`路径` raw=`原始`**
|
||||
|
||||
## 单位
|
||||
+ `阶`
|
||||
|
||||
> 确保插件
|
||||
**> linalg_eye n=`阶`**
|
||||
|
||||
## 零阵
|
||||
+ `行`
|
||||
+ `列`
|
||||
|
||||
> 确保插件
|
||||
**> linalg_zeros rows=`行` cols=`列`**
|
||||
|
||||
## 自列表
|
||||
+ `数据`
|
||||
|
||||
> 确保插件
|
||||
**> linalg_from_list data=`数据`**
|
||||
|
||||
## 自公式
|
||||
+ `公式`
|
||||
|
||||
吸收 `$$` 数值矩阵公式为稠密叶。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_from_formula formula=`公式`**
|
||||
|
||||
## 求值
|
||||
+ `式`
|
||||
+ `原始`=False
|
||||
|
||||
求成稠密(默认先 **化简**)。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_explicit expr=`式` raw=`原始`**
|
||||
|
||||
## 行列式
|
||||
+ `式`
|
||||
|
||||
> 确保插件
|
||||
**> linalg_det expr=`式`**
|
||||
|
||||
## 迹
|
||||
+ `式`
|
||||
|
||||
> 确保插件
|
||||
**> linalg_trace expr=`式`**
|
||||
|
||||
## 求解
|
||||
+ `左`=None
|
||||
+ `右`
|
||||
+ `分解`=None
|
||||
|
||||
解 `左 · x = 右`,或复用 `分解`(`kind=lu`)+ `右`。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_solve a=`左` b=`右` factor=`分解`**
|
||||
|
||||
## 稠密乘
|
||||
+ `左`
|
||||
+ `右`
|
||||
|
||||
> 确保插件
|
||||
**> linalg_matmul a=`左` b=`右`**
|
||||
|
||||
## 克罗内克
|
||||
+ `左`
|
||||
+ `右`
|
||||
|
||||
惰性 Kronecker 积(默认不展开)。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_kron a=`左` b=`右`**
|
||||
|
||||
## 分块
|
||||
+ `块`
|
||||
|
||||
由嵌套表达式列表构造分块矩阵。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_block blocks=`块`**
|
||||
|
||||
## 分块化简
|
||||
+ `式`
|
||||
|
||||
分块级塌缩(`Block*Block` → 块乘加)。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_collapse expr=`式`**
|
||||
|
||||
## 分解
|
||||
+ `矩阵`
|
||||
+ `类型`="lu"
|
||||
|
||||
稠密分解 → `linalg_factor`(`类型` = `lu` | `qr` | `svd` | `eig` | `chol`)。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_factorize matrix=`矩阵` kind=`类型`**
|
||||
|
||||
## 绘图
|
||||
+ `分解`
|
||||
+ `类型`=None
|
||||
+ `路径`=None
|
||||
+ `主题`="light"
|
||||
|
||||
结构 SVG(`eig` | `svd` | `qr` | `lu` | `ge` | `chol` | `structure` | `heatmap` | `hinton`)。主题与 quantum Q8 对齐:`light` | `dark` | `bw`。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_draw factor=`分解` kind=`类型` path=`路径` theme=`主题`**
|
||||
|
||||
## 最小二乘
|
||||
+ `左`
|
||||
+ `右`
|
||||
|
||||
最小二乘 `min ||左 · x - 右||`(高瘦用 QR,宽用 SVD)。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_lstsq a=`左` b=`右`**
|
||||
|
||||
## 范数
|
||||
+ `式`
|
||||
+ `范数`="fro"
|
||||
|
||||
矩阵范数:`fro` | `1` | `inf` | `2`。复数稠密暂仅 `fro`。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_norm expr=`式` ord=`范数`**
|
||||
|
||||
## 条件数
|
||||
+ `式`
|
||||
|
||||
谱条件数(SVD,`ord=2`)。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_cond expr=`式`**
|
||||
|
||||
## 秩
|
||||
+ `式`
|
||||
|
||||
数值秩(SVD)。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_rank expr=`式`**
|
||||
|
||||
## 声明
|
||||
+ `表`
|
||||
|
||||
用 `@` 记录表一次声明多个符号矩阵(`名` / `行` / `列`)。返回环境 map。
|
||||
|
||||
> 确保插件
|
||||
**> linalg_declare table=`表` type_tag="矩阵"**
|
||||
|
||||
## 符号
|
||||
+ `名`
|
||||
+ `行`
|
||||
+ `列`
|
||||
|
||||
抽象矩阵符号。返回 `# 矩阵` 实例(可用 `+` / `*` 与方法)。
|
||||
|
||||
> 确保插件
|
||||
**> 矩阵 名=`名` 行=`行` 列=`列`**
|
||||
|
||||
# 矩阵
|
||||
+ `名`=None
|
||||
+ `行`=None
|
||||
+ `列`=None
|
||||
+ `数据`=None
|
||||
+ `公式`=None
|
||||
+ `阶`=None
|
||||
|
||||
矩阵值(`_type=矩阵`)。优先中缀 `A + B` / `A * B`,或 `` `A`.转置 ``。
|
||||
|
||||
> 确保插件
|
||||
1. `公式`
|
||||
**> linalg_from_formula formula=`公式`**
|
||||
2. `数据`
|
||||
**> linalg_from_list data=`数据`**
|
||||
3. `名`
|
||||
**> linalg_symbol name=`名` rows=`行` cols=`列`**
|
||||
4. `阶`
|
||||
**> linalg_eye n=`阶`**
|
||||
5. `行`
|
||||
**> linalg_zeros rows=`行` cols=`列`**
|
||||
6. *
|
||||
> print text=ext/linalg: 矩阵需要 名= / 数据= / 公式= / 阶= / 行=
|
||||
**None**
|
||||
|
||||
## 转置
|
||||
|
||||
**> linalg_transpose expr=`self`**
|
||||
|
||||
## 转置文本
|
||||
|
||||
转置后输出 ASCII(默认化简)。适合讲义恒等式验收。
|
||||
|
||||
*`转` = > linalg_transpose expr=`self`*
|
||||
**> linalg_ascii expr=`转` raw=False**
|
||||
|
||||
## 加
|
||||
+ `右`
|
||||
|
||||
**> linalg_add a=`self` b=`右`**
|
||||
|
||||
## 减
|
||||
+ `右`
|
||||
|
||||
**> linalg_sub a=`self` b=`右`**
|
||||
|
||||
## 乘
|
||||
+ `右`
|
||||
|
||||
**> linalg_mul a=`self` b=`右`**
|
||||
|
||||
## 逆
|
||||
|
||||
**> linalg_inv expr=`self`**
|
||||
|
||||
## 化简
|
||||
|
||||
**> linalg_simplify expr=`self`**
|
||||
|
||||
## 文本
|
||||
|
||||
**> linalg_ascii expr=`self` raw=False**
|
||||
|
||||
## 乳胶
|
||||
|
||||
**> linalg_latex expr=`self` raw=False**
|
||||
|
||||
## 求值
|
||||
+ `原始`=False
|
||||
|
||||
**> linalg_explicit expr=`self` raw=`原始`**
|
||||
|
||||
## 行列式
|
||||
|
||||
**> linalg_det expr=`self`**
|
||||
|
||||
## 迹
|
||||
|
||||
**> linalg_trace expr=`self`**
|
||||
|
||||
## 展示
|
||||
+ `路径`=None
|
||||
+ `原始`=False
|
||||
|
||||
**> linalg_show expr=`self` path=`路径` raw=`原始`**
|
||||
|
||||
## 单位
|
||||
+ `阶`
|
||||
|
||||
**> linalg_eye n=`阶`**
|
||||
|
||||
## 零阵
|
||||
+ `行`
|
||||
+ `列`
|
||||
|
||||
**> linalg_zeros rows=`行` cols=`列`**
|
||||
|
||||
## 自列表
|
||||
+ `数据`
|
||||
|
||||
**> linalg_from_list data=`数据`**
|
||||
|
||||
## 自公式
|
||||
+ `公式`
|
||||
|
||||
**> linalg_from_formula formula=`公式`**
|
||||
+29
-3
@@ -653,16 +653,42 @@ Register site icons from a GFM table (`|path|rel|type|sizes|url|` or ZH
|
||||
+ `json`=None
|
||||
+ `access_log`=None
|
||||
+ `cache_control`=None
|
||||
+ `proxy`=None
|
||||
+ `invoke`=None
|
||||
|
||||
Each capability is declared as a data table and assembled at listen time. The `cors` parameter takes a `|允许来源|方法|头|暴露头|凭证|` table (one row per origin; an empty `允许来源` column means any origin). The `security` parameter takes a `|头|值|` response-header table (e.g. `X-Frame-Options`, `Content-Security-Policy`, `X-Content-Type-Options`, `Referrer-Policy`, `Strict-Transport-Security`). Set `compress` to `True` to gzip response bodies. `body_limit` is the max request body bytes (e.g. `1048576`). The `json` parameter takes a `|路径|方法|表|条件|排序|上限|` table of JSON API endpoints backed by DB queries (each returns `application/json`). Set `access_log` to `True` to log `METHOD path status duration_ms` on stderr. `cache_control` sets a global `Cache-Control` header (e.g. `public, max-age=3600`).
|
||||
Each capability is declared as a data table and assembled at listen time. The `cors` parameter takes a `|允许来源|方法|头|暴露头|凭证|` table (one row per origin; an empty `允许来源` column means any origin). The `security` parameter takes a `|头|值|` response-header table (e.g. `X-Frame-Options`, `Content-Security-Policy`, `X-Content-Type-Options`, `Referrer-Policy`, `Strict-Transport-Security`). Set `compress` to `True` to gzip response bodies. `body_limit` is the max request body bytes (e.g. `1048576`). The `json` parameter takes a `|路径|方法|表|条件|排序|上限|` table of JSON API endpoints backed by DB queries (each returns `application/json`). Set `access_log` to `True` to log `METHOD path status duration_ms` on stderr. `cache_control` sets a global `Cache-Control` header (e.g. `public, max-age=3600`). `proxy` takes a `|路径|上游|流式|去前缀|方法|环境头|超时|` table of streaming reverse-proxy routes. `invoke` takes a `|路径|方法|函数|正文|返回|` table that calls entry-module `lib.member` handlers per request.
|
||||
|
||||
Tables stay as data; `configure` assembles them. 配置即数据、装配即函数.
|
||||
|
||||
**> web_app_middleware app=`self` cors=`cors` security=`security` compress=`compress` body_limit=`body_limit` json_routes=`json` access_log=`access_log` cache_control=`cache_control`**
|
||||
**> web_app_middleware app=`self` cors=`cors` security=`security` compress=`compress` body_limit=`body_limit` json_routes=`json` access_log=`access_log` cache_control=`cache_control` proxy=`proxy` invoke=`invoke`**
|
||||
|
||||
## proxy
|
||||
+ `path`
|
||||
+ `upstream`
|
||||
+ `stream`=True
|
||||
+ `strip_prefix`=None
|
||||
+ `methods`=None
|
||||
+ `headers_from_env`=None
|
||||
+ `timeout_ms`=120000
|
||||
|
||||
Same-origin reverse proxy to an upstream HTTP(S) URL. When `stream` is True (default), the response body — including `text/event-stream` SSE — is piped without buffering the full payload. `upstream` may contain `$ENV` / `${ENV}`. `headers_from_env` is `ENV=Header-Name` (comma-separated); secrets stay on the server. Prefer this over a side Python LLM proxy.
|
||||
|
||||
**> web_app_proxy app=`self` path=`path` upstream=`upstream` stream=`stream` strip_prefix=`strip_prefix` methods=`methods` headers_from_env=`headers_from_env` timeout_ms=`timeout_ms`**
|
||||
|
||||
## invoke
|
||||
+ `path`
|
||||
+ `fn`
|
||||
+ `method`=POST
|
||||
+ `body`=json
|
||||
+ `return`=json
|
||||
|
||||
Call a user `##` on each HTTP request. `fn` must be `lib.member` imported on the entry module. `body` is `json` / `form` / `query` / `raw`; object keys map to named params (plus `payload`). Returns JSON by default.
|
||||
|
||||
**> web_app_invoke app=`self` path=`path` method=`method` fn=`fn` body=`body` return=`return`**
|
||||
|
||||
## listen
|
||||
|
||||
Serve `/`, routed pages, `/_part/{id}` (home) and `{path}/_part/{id}` (routes), `/_form/{id}` (from mounts + page embeds), optional `/static` (or custom mount), optional `/admin`, upload/download/WebSocket/RSS/sitemap/robots routes, redirects, and a custom 404 fallback. Production HTTPS should terminate at a reverse proxy; set `cookie_secure=True` when serving over TLS.
|
||||
Serve `/`, routed pages, `/_part/{id}` (home) and `{path}/_part/{id}` (routes), `/_form/{id}` (from mounts + page embeds), optional `/static` (or custom mount), optional `/admin`, upload/download/WebSocket/RSS/sitemap/robots routes, redirects, proxy/invoke routes, and a custom 404 fallback. Production HTTPS should terminate at a reverse proxy; set `cookie_secure=True` when serving over TLS.
|
||||
|
||||
**> web_listen app=`self`**
|
||||
|
||||
|
||||
+29
-3
@@ -623,16 +623,42 @@ SEO / OpenGraph 元数据表(`|键|值|`)。如 `title`、`description`、`c
|
||||
+ `接口`=None
|
||||
+ `访问日志`=None
|
||||
+ `缓存控制`=None
|
||||
+ `代理`=None
|
||||
+ `调用`=None
|
||||
|
||||
每项能力用数据表声明,`监听` 时统一装配。`跨域` 参数接受 `|允许来源|方法|头|暴露头|凭证|` 表(每来源一行;`允许来源` 留空表示允许任意来源)。`安全` 参数接受 `|头|值|` 响应头表(如 `X-Frame-Options`、`Content-Security-Policy`、`X-Content-Type-Options`、`Referrer-Policy`、`Strict-Transport-Security`)。`压缩` 为 `真` 时对响应体做 gzip 压缩。`请求体上限` 是请求体最大字节数(如 `1048576`)。`接口` 参数接受 `|路径|方法|表|条件|排序|上限|` JSON API 端点表(每个返回 `application/json`)。`访问日志` 为 `真` 时在 stderr 打印 `METHOD path status duration_ms`。`缓存控制` 设置全局 `Cache-Control`(如 `public, max-age=3600`)。
|
||||
每项能力用数据表声明,`监听` 时统一装配。`跨域` 参数接受 `|允许来源|方法|头|暴露头|凭证|` 表(每来源一行;`允许来源` 留空表示允许任意来源)。`安全` 参数接受 `|头|值|` 响应头表(如 `X-Frame-Options`、`Content-Security-Policy`、`X-Content-Type-Options`、`Referrer-Policy`、`Strict-Transport-Security`)。`压缩` 为 `真` 时对响应体做 gzip 压缩。`请求体上限` 是请求体最大字节数(如 `1048576`)。`接口` 参数接受 `|路径|方法|表|条件|排序|上限|` JSON API 端点表(每个返回 `application/json`)。`访问日志` 为 `真` 时在 stderr 打印 `METHOD path status duration_ms`。`缓存控制` 设置全局 `Cache-Control`(如 `public, max-age=3600`)。`代理` 接受 `|路径|上游|流式|去前缀|方法|环境头|超时|` 流式反向代理表。`调用` 接受 `|路径|方法|函数|正文|返回|` 表,按请求调用入口模块已导入的 `库.成员`。
|
||||
|
||||
表仍是数据,`装配` 把它们变成能力。配置即数据、装配即函数。
|
||||
|
||||
**> web_app_middleware app=`self` cors=`跨域` security=`安全` compress=`压缩` body_limit=`请求体上限` json_routes=`接口` access_log=`访问日志` cache_control=`缓存控制`**
|
||||
**> web_app_middleware app=`self` cors=`跨域` security=`安全` compress=`压缩` body_limit=`请求体上限` json_routes=`接口` access_log=`访问日志` cache_control=`缓存控制` proxy=`代理` invoke=`调用`**
|
||||
|
||||
## 代理
|
||||
+ `路径`
|
||||
+ `上游`
|
||||
+ `流式`=真
|
||||
+ `去前缀`=None
|
||||
+ `方法`=None
|
||||
+ `环境头`=None
|
||||
+ `超时`=120000
|
||||
|
||||
同域反向代理到上游 HTTP(S)。`流式` 为真(默认)时管道转发响应体(含 `text/event-stream`),不整段缓冲。`上游` 可含 `$ENV` / `${ENV}`。`环境头` 为 `ENV=Header-Name`(逗号分隔),密钥留在服务端。
|
||||
|
||||
**> web_app_proxy app=`self` path=`路径` upstream=`上游` stream=`流式` strip_prefix=`去前缀` methods=`方法` headers_from_env=`环境头` timeout_ms=`超时`**
|
||||
|
||||
## 调用
|
||||
+ `路径`
|
||||
+ `函数`
|
||||
+ `方法`=POST
|
||||
+ `正文`=json
|
||||
+ `返回`=json
|
||||
|
||||
每个 HTTP 请求调用用户 `##`。`函数` 必须是入口模块已 `导入` 的 `库.成员`。`正文` 为 `json` / `form` / `query` / `raw`;对象键映射为具名形参(另有 `payload`)。默认返回 JSON。
|
||||
|
||||
**> web_app_invoke app=`self` path=`路径` method=`方法` fn=`函数` body=`正文` return=`返回`**
|
||||
|
||||
## 监听
|
||||
|
||||
提供 `/`、路由页、首页 `/_part/{id}`、路由 `{路径}/_part/{id}`、`/_form/{id}`、可选静态目录、可选 `/admin`,上传/下载/WebSocket/RSS/sitemap/robots、重定向,以及自定义 404。生产 HTTPS 请在反向代理终止;启用 TLS 时设 `cookie_secure`。
|
||||
提供 `/`、路由页、首页 `/_part/{id}`、路由 `{路径}/_part/{id}`、`/_form/{id}`、可选静态目录、可选 `/admin`,上传/下载/WebSocket/RSS/sitemap/robots、重定向、代理/调用路由,以及自定义 404。生产 HTTPS 请在反向代理终止;启用 TLS 时设 `cookie_secure`。
|
||||
|
||||
**> web_listen app=`self`**
|
||||
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: lib/cli
|
||||
description: Parse argv flags (Mid M5). --key value / --key=value / --flag; positionals under _.
|
||||
---
|
||||
|
||||
## parse
|
||||
+ `args`=None
|
||||
|
||||
Parse `--key value` / `--key=value` / `--flag`. A bare `--flag` must not be followed by a non-option token if you need it as boolean (put flags last, or use `--flag=true`). Positionals land under `_`.
|
||||
|
||||
**> host_cli_parse args=`args`**
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: lib/csv
|
||||
description: RFC4180-ish CSV parse/stringify (Mid M4). First row = headers → list of maps.
|
||||
---
|
||||
|
||||
## parse
|
||||
+ `text`
|
||||
|
||||
**> host_csv_parse text=`text`**
|
||||
|
||||
## stringify
|
||||
+ `rows`
|
||||
|
||||
**> host_csv_stringify rows=`rows`**
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: lib/encoding
|
||||
description: Base64 and hex encode/decode (Mid M1). UTF-8 text round-trip.
|
||||
---
|
||||
|
||||
## base64_encode
|
||||
+ `text`
|
||||
|
||||
**> host_encoding_base64_encode text=`text`**
|
||||
|
||||
## base64_decode
|
||||
+ `text`
|
||||
|
||||
**> host_encoding_base64_decode text=`text`**
|
||||
|
||||
## hex_encode
|
||||
+ `text`
|
||||
|
||||
**> host_encoding_hex_encode text=`text`**
|
||||
|
||||
## hex_decode
|
||||
+ `text`
|
||||
|
||||
**> host_encoding_hex_decode text=`text`**
|
||||
@@ -40,6 +40,29 @@ description: English filesystem wrappers
|
||||
|
||||
**> host_remove path=`path`**
|
||||
|
||||
## copy_file
|
||||
+ `src`
|
||||
+ `dest`
|
||||
|
||||
Copy a file (overwrites `dest` if it exists). Paths are sandboxed like other fs ops.
|
||||
|
||||
**> host_copy_file src=`src` dest=`dest`**
|
||||
|
||||
## move
|
||||
+ `src`
|
||||
+ `dest`
|
||||
|
||||
Rename / move within the sandbox.
|
||||
|
||||
**> host_move src=`src` dest=`dest`**
|
||||
|
||||
## make_temp
|
||||
+ `prefix`=None
|
||||
|
||||
Create an empty temp file under the program directory; return its relative path.
|
||||
|
||||
**> host_make_temp prefix=`prefix`**
|
||||
|
||||
## text_patch
|
||||
+ `path`
|
||||
+ `find`
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: lib/hash
|
||||
description: Digests and HMAC (Mid M3). Integrity / cache keys — not password hashing.
|
||||
---
|
||||
|
||||
## sha256
|
||||
+ `text`
|
||||
|
||||
**> host_hash_sha256 text=`text`**
|
||||
|
||||
## sha1
|
||||
+ `text`
|
||||
|
||||
**> host_hash_sha1 text=`text`**
|
||||
|
||||
## md5
|
||||
+ `text`
|
||||
|
||||
**> host_hash_md5 text=`text`**
|
||||
|
||||
## hmac_sha256
|
||||
+ `key`
|
||||
+ `text`
|
||||
|
||||
**> host_hash_hmac_sha256 key=`key` text=`text`**
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: lib/log
|
||||
description: Level-filtered one-line logs (Mid M6). Default level info.
|
||||
---
|
||||
|
||||
## set_level
|
||||
+ `level`
|
||||
|
||||
level is debug / info / warn / error.
|
||||
|
||||
**> host_log_set_level level=`level`**
|
||||
|
||||
## debug
|
||||
+ `text`
|
||||
|
||||
*line = > host_log_line level="debug" text=`text`*
|
||||
1. `line`
|
||||
> print text=`line`
|
||||
2. *
|
||||
****
|
||||
|
||||
## info
|
||||
+ `text`
|
||||
|
||||
*line = > host_log_line level="info" text=`text`*
|
||||
1. `line`
|
||||
> print text=`line`
|
||||
2. *
|
||||
****
|
||||
|
||||
## warn
|
||||
+ `text`
|
||||
|
||||
*line = > host_log_line level="warn" text=`text`*
|
||||
1. `line`
|
||||
> print text=`line`
|
||||
2. *
|
||||
****
|
||||
|
||||
## error
|
||||
+ `text`
|
||||
|
||||
*line = > host_log_line level="error" text=`text`*
|
||||
1. `line`
|
||||
> print text=`line`
|
||||
2. *
|
||||
****
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: lib/path
|
||||
description: Path algebra (Mid M2). No I/O; OS separators.
|
||||
---
|
||||
|
||||
## join
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_path_join a=`a` b=`b`**
|
||||
|
||||
## split
|
||||
+ `path`
|
||||
|
||||
**> host_path_split path=`path`**
|
||||
|
||||
## file_name
|
||||
+ `path`
|
||||
|
||||
**> host_path_file_name path=`path`**
|
||||
|
||||
## parent
|
||||
+ `path`
|
||||
|
||||
**> host_path_parent path=`path`**
|
||||
|
||||
## extension
|
||||
+ `path`
|
||||
|
||||
**> host_path_extension path=`path`**
|
||||
|
||||
## normalize
|
||||
+ `path`
|
||||
|
||||
**> host_path_normalize path=`path`**
|
||||
|
||||
## is_absolute
|
||||
+ `path`
|
||||
|
||||
**> host_path_is_absolute path=`path`**
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: lib/re
|
||||
description: Regular expressions (Mid M1). Unicode; no backreferences.
|
||||
---
|
||||
|
||||
## is_match
|
||||
+ `text`
|
||||
+ `pattern`
|
||||
|
||||
**> host_re_is_match text=`text` pattern=`pattern`**
|
||||
|
||||
## find
|
||||
+ `text`
|
||||
+ `pattern`
|
||||
|
||||
**> host_re_find text=`text` pattern=`pattern`**
|
||||
|
||||
## find_all
|
||||
+ `text`
|
||||
+ `pattern`
|
||||
|
||||
**> host_re_find_all text=`text` pattern=`pattern`**
|
||||
|
||||
## replace
|
||||
+ `text`
|
||||
+ `pattern`
|
||||
+ `with`
|
||||
+ `count`=None
|
||||
|
||||
Optional `count=` limits replacements (`None` = all).
|
||||
|
||||
**> host_re_replace text=`text` pattern=`pattern` with=`with` count=`count`**
|
||||
|
||||
## split
|
||||
+ `text`
|
||||
+ `pattern`
|
||||
|
||||
**> host_re_split text=`text` pattern=`pattern`**
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: lib/secrets
|
||||
description: Cryptographic tokens (Mid M3). Do not use math.random for secrets.
|
||||
---
|
||||
|
||||
## token_hex
|
||||
+ `n`=None
|
||||
|
||||
Byte length `n` (default 16). Returns lowercase hex of length `2*n`.
|
||||
|
||||
**> host_secrets_token_hex n=`n`**
|
||||
|
||||
## token_urlsafe
|
||||
+ `n`=None
|
||||
|
||||
Byte length `n` (default 16). URL-safe Base64 without padding.
|
||||
|
||||
**> host_secrets_token_urlsafe n=`n`**
|
||||
@@ -129,6 +129,49 @@ Zero-based index or `None`.
|
||||
|
||||
**> host_list_reverse list=`list`**
|
||||
|
||||
## sort
|
||||
+ `list`
|
||||
|
||||
Ascending sort (int/num/text preferred).
|
||||
|
||||
**> host_list_sort list=`list`**
|
||||
|
||||
## sort_by
|
||||
+ `list`
|
||||
+ `key`
|
||||
|
||||
Sort a list of maps by `key`.
|
||||
|
||||
**> host_list_sort_by list=`list` key=`key`**
|
||||
|
||||
## unique
|
||||
+ `list`
|
||||
|
||||
Stable unique (first wins).
|
||||
|
||||
**> host_list_unique list=`list`**
|
||||
|
||||
## chunk
|
||||
+ `list`
|
||||
+ `size`
|
||||
|
||||
**> host_list_chunk list=`list` size=`size`**
|
||||
|
||||
## zip
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
Pairs until the shorter list ends.
|
||||
|
||||
**> host_list_zip a=`a` b=`b`**
|
||||
|
||||
## flatten
|
||||
+ `list`
|
||||
|
||||
One-level flatten.
|
||||
|
||||
**> host_list_flatten list=`list`**
|
||||
|
||||
## clear
|
||||
+ `value`
|
||||
|
||||
|
||||
+55
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: lib/text
|
||||
description: English text helpers over trim / split / join
|
||||
description: Text helpers (Mid M4 thicken). Literal replace — use lib/re for regex.
|
||||
---
|
||||
|
||||
## str_trim
|
||||
@@ -19,3 +19,57 @@ description: English text helpers over trim / split / join
|
||||
+ `sep`
|
||||
|
||||
**> join value=`xs` sep=`sep`**
|
||||
|
||||
## contains
|
||||
+ `text`
|
||||
+ `sub`
|
||||
|
||||
**> host_text_contains text=`text` sub=`sub`**
|
||||
|
||||
## starts_with
|
||||
+ `text`
|
||||
+ `prefix`
|
||||
|
||||
**> host_text_starts_with text=`text` prefix=`prefix`**
|
||||
|
||||
## ends_with
|
||||
+ `text`
|
||||
+ `suffix`
|
||||
|
||||
**> host_text_ends_with text=`text` suffix=`suffix`**
|
||||
|
||||
## replace
|
||||
+ `text`
|
||||
+ `old`
|
||||
+ `new`
|
||||
+ `count`=None
|
||||
|
||||
Literal substring replace (`count` optional).
|
||||
|
||||
**> host_text_replace text=`text` old=`old` new=`new` count=`count`**
|
||||
|
||||
## to_upper
|
||||
+ `text`
|
||||
|
||||
**> host_text_to_upper text=`text`**
|
||||
|
||||
## to_lower
|
||||
+ `text`
|
||||
|
||||
**> host_text_to_lower text=`text`**
|
||||
|
||||
## repeat
|
||||
+ `text`
|
||||
+ `n`
|
||||
|
||||
**> host_text_repeat text=`text` n=`n`**
|
||||
|
||||
## pad
|
||||
+ `text`
|
||||
+ `width`
|
||||
+ `fill`=None
|
||||
+ `align`=None
|
||||
|
||||
align: left (default), right, or center.
|
||||
|
||||
**> host_text_pad text=`text` width=`width` fill=`fill` align=`align`**
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: lib/uuid
|
||||
description: UUID v4 (Mid M6). Cryptographic random via getrandom.
|
||||
---
|
||||
|
||||
## v4
|
||||
|
||||
**> host_uuid_v4**
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: lib/命令行
|
||||
description: 解析命令行参数(中层 M5)。--键 值 / --键=值 / --开关;位置参在 _。
|
||||
---
|
||||
|
||||
## 解析
|
||||
+ `参数`=None
|
||||
|
||||
省略 `参数` 时用进程 argv(系统.参数表)。
|
||||
|
||||
**> host_cli_parse args=`参数`**
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: lib/哈希
|
||||
description: 摘要与 HMAC(中层 M3)。完整性 / 缓存键 — 非密码存储。
|
||||
---
|
||||
|
||||
## 哈希256
|
||||
+ `内容`
|
||||
|
||||
**> host_hash_sha256 text=`内容`**
|
||||
|
||||
## 哈希1
|
||||
+ `内容`
|
||||
|
||||
**> host_hash_sha1 text=`内容`**
|
||||
|
||||
## md5
|
||||
+ `内容`
|
||||
|
||||
**> host_hash_md5 text=`内容`**
|
||||
|
||||
## 密钥哈希256
|
||||
+ `密钥`
|
||||
+ `内容`
|
||||
|
||||
**> host_hash_hmac_sha256 key=`密钥` text=`内容`**
|
||||
@@ -40,6 +40,29 @@ description: 中文文件系统包装
|
||||
|
||||
**> host_remove path=`路径`**
|
||||
|
||||
## 复制文件
|
||||
+ `源`
|
||||
+ `目标`
|
||||
|
||||
复制文件(目标已存在则覆盖)。路径沙箱同其他文件操作。
|
||||
|
||||
**> host_copy_file src=`源` dest=`目标`**
|
||||
|
||||
## 移动
|
||||
+ `源`
|
||||
+ `目标`
|
||||
|
||||
在沙箱内重命名 / 移动。
|
||||
|
||||
**> host_move src=`源` dest=`目标`**
|
||||
|
||||
## 建临时
|
||||
+ `前缀`=None
|
||||
|
||||
在程序目录下创建空临时文件,返回相对路径。
|
||||
|
||||
**> host_make_temp prefix=`前缀`**
|
||||
|
||||
## 文本补丁
|
||||
+ `路径`
|
||||
+ `查找`
|
||||
|
||||
+55
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: lib/文本
|
||||
description: 中文文本库:去空白 / 拆分 / 拼接
|
||||
description: 文本库加厚(中层 M4)。字面替换 — 正则请用 lib/正则。
|
||||
---
|
||||
|
||||
## 去空白
|
||||
@@ -19,3 +19,57 @@ description: 中文文本库:去空白 / 拆分 / 拼接
|
||||
+ `sep`
|
||||
|
||||
**> join value=`xs` sep=`sep`**
|
||||
|
||||
## 包含
|
||||
+ `内容`
|
||||
+ `子串`
|
||||
|
||||
**> host_text_contains text=`内容` sub=`子串`**
|
||||
|
||||
## 开头是
|
||||
+ `内容`
|
||||
+ `前缀`
|
||||
|
||||
**> host_text_starts_with text=`内容` prefix=`前缀`**
|
||||
|
||||
## 结尾是
|
||||
+ `内容`
|
||||
+ `后缀`
|
||||
|
||||
**> host_text_ends_with text=`内容` suffix=`后缀`**
|
||||
|
||||
## 替换
|
||||
+ `内容`
|
||||
+ `旧`
|
||||
+ `新`
|
||||
+ `次数`=None
|
||||
|
||||
字面子串替换(可选 `次数`)。
|
||||
|
||||
**> host_text_replace text=`内容` old=`旧` new=`新` count=`次数`**
|
||||
|
||||
## 大写
|
||||
+ `内容`
|
||||
|
||||
**> host_text_to_upper text=`内容`**
|
||||
|
||||
## 小写
|
||||
+ `内容`
|
||||
|
||||
**> host_text_to_lower text=`内容`**
|
||||
|
||||
## 重复
|
||||
+ `内容`
|
||||
+ `次数`
|
||||
|
||||
**> host_text_repeat text=`内容` n=`次数`**
|
||||
|
||||
## 填充
|
||||
+ `内容`
|
||||
+ `宽度`
|
||||
+ `填充符`=None
|
||||
+ `对齐`=None
|
||||
|
||||
对齐:left(默认)/ right / center。
|
||||
|
||||
**> host_text_pad text=`内容` width=`宽度` fill=`填充符` align=`对齐`**
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: lib/日志
|
||||
description: 按级别过滤的一行日志(中层 M6)。默认级别 info。
|
||||
---
|
||||
|
||||
## 设级别
|
||||
+ `级别`
|
||||
|
||||
级别:debug / info / warn / error(或 调试/信息/警告/错误)。
|
||||
|
||||
**> host_log_set_level level=`级别`**
|
||||
|
||||
## 调试
|
||||
+ `内容`
|
||||
|
||||
*line = > host_log_line level="debug" text=`内容`*
|
||||
1. `line`
|
||||
> 打印 内容=`line`
|
||||
2. *
|
||||
****
|
||||
|
||||
## 信息
|
||||
+ `内容`
|
||||
|
||||
*line = > host_log_line level="info" text=`内容`*
|
||||
1. `line`
|
||||
> 打印 内容=`line`
|
||||
2. *
|
||||
****
|
||||
|
||||
## 警告
|
||||
+ `内容`
|
||||
|
||||
*line = > host_log_line level="warn" text=`内容`*
|
||||
1. `line`
|
||||
> 打印 内容=`line`
|
||||
2. *
|
||||
****
|
||||
|
||||
## 错误
|
||||
+ `内容`
|
||||
|
||||
*line = > host_log_line level="error" text=`内容`*
|
||||
1. `line`
|
||||
> 打印 内容=`line`
|
||||
2. *
|
||||
****
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: lib/机密
|
||||
description: 安全随机令牌(中层 M3)。勿用 math.random 生成令牌。
|
||||
---
|
||||
|
||||
## 十六进制令牌
|
||||
+ `字节数`=None
|
||||
|
||||
字节长度(默认 16),返回长度为 `2*字节数` 的小写 hex。
|
||||
|
||||
**> host_secrets_token_hex n=`字节数`**
|
||||
|
||||
## 网址安全令牌
|
||||
+ `字节数`=None
|
||||
|
||||
字节长度(默认 16),URL-safe Base64(无填充)。
|
||||
|
||||
**> host_secrets_token_urlsafe n=`字节数`**
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: lib/标识
|
||||
description: UUID 版本 4(中层 M6)。经 getrandom 安全随机。
|
||||
---
|
||||
|
||||
## 版本4
|
||||
|
||||
**> host_uuid_v4**
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: lib/正则
|
||||
description: 正则表达式(中层 M1)。Unicode;无回溯引用。
|
||||
---
|
||||
|
||||
## 匹配
|
||||
+ `内容`
|
||||
+ `模式`
|
||||
|
||||
**> host_re_is_match text=`内容` pattern=`模式`**
|
||||
|
||||
## 查找
|
||||
+ `内容`
|
||||
+ `模式`
|
||||
|
||||
**> host_re_find text=`内容` pattern=`模式`**
|
||||
|
||||
## 查找全部
|
||||
+ `内容`
|
||||
+ `模式`
|
||||
|
||||
**> host_re_find_all text=`内容` pattern=`模式`**
|
||||
|
||||
## 替换
|
||||
+ `内容`
|
||||
+ `模式`
|
||||
+ `为`
|
||||
+ `次数`=None
|
||||
|
||||
可选 `次数=` 限制替换次数(缺省 = 全部)。
|
||||
|
||||
**> host_re_replace text=`内容` pattern=`模式` with=`为` count=`次数`**
|
||||
|
||||
## 拆分
|
||||
+ `内容`
|
||||
+ `模式`
|
||||
|
||||
**> host_re_split text=`内容` pattern=`模式`**
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: lib/编码
|
||||
description: Base64 与十六进制编解码(中层 M1)。UTF-8 文本往返。
|
||||
---
|
||||
|
||||
## 基64编码
|
||||
+ `内容`
|
||||
|
||||
**> host_encoding_base64_encode text=`内容`**
|
||||
|
||||
## 基64解码
|
||||
+ `内容`
|
||||
|
||||
**> host_encoding_base64_decode text=`内容`**
|
||||
|
||||
## 十六进制编码
|
||||
+ `内容`
|
||||
|
||||
**> host_encoding_hex_encode text=`内容`**
|
||||
|
||||
## 十六进制解码
|
||||
+ `内容`
|
||||
|
||||
**> host_encoding_hex_decode text=`内容`**
|
||||
+43
@@ -129,6 +129,49 @@ description: >-
|
||||
|
||||
**> host_list_reverse list=`list`**
|
||||
|
||||
## 排序
|
||||
+ `list`
|
||||
|
||||
升序(优先 int/num/text)。
|
||||
|
||||
**> host_list_sort list=`list`**
|
||||
|
||||
## 按键排序
|
||||
+ `list`
|
||||
+ `key`
|
||||
|
||||
对 map 列表按键排序。
|
||||
|
||||
**> host_list_sort_by list=`list` key=`key`**
|
||||
|
||||
## 去重
|
||||
+ `list`
|
||||
|
||||
保序去重(保留首次)。
|
||||
|
||||
**> host_list_unique list=`list`**
|
||||
|
||||
## 分块
|
||||
+ `list`
|
||||
+ `size`
|
||||
|
||||
**> host_list_chunk list=`list` size=`size`**
|
||||
|
||||
## 拉链
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
取较短长度配对。
|
||||
|
||||
**> host_list_zip a=`a` b=`b`**
|
||||
|
||||
## 展平
|
||||
+ `list`
|
||||
|
||||
一层展平。
|
||||
|
||||
**> host_list_flatten list=`list`**
|
||||
|
||||
## 清空
|
||||
+ `value`
|
||||
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: lib/路径
|
||||
description: 路径代数(中层 M2)。无 I/O;分隔符随宿主 OS。
|
||||
---
|
||||
|
||||
## 拼接
|
||||
+ `甲`
|
||||
+ `乙`
|
||||
|
||||
**> host_path_join a=`甲` b=`乙`**
|
||||
|
||||
## 拆分
|
||||
+ `路径`
|
||||
|
||||
**> host_path_split path=`路径`**
|
||||
|
||||
## 文件名
|
||||
+ `路径`
|
||||
|
||||
**> host_path_file_name path=`路径`**
|
||||
|
||||
## 父目录
|
||||
+ `路径`
|
||||
|
||||
**> host_path_parent path=`路径`**
|
||||
|
||||
## 扩展名
|
||||
+ `路径`
|
||||
|
||||
**> host_path_extension path=`路径`**
|
||||
|
||||
## 规范化
|
||||
+ `路径`
|
||||
|
||||
**> host_path_normalize path=`路径`**
|
||||
|
||||
## 是绝对
|
||||
+ `路径`
|
||||
|
||||
**> host_path_is_absolute path=`路径`**
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: lib/逗号表
|
||||
description: CSV 解析/序列化(中层 M4)。首行为表头 → 映射列表。
|
||||
---
|
||||
|
||||
## 解析
|
||||
+ `内容`
|
||||
|
||||
**> host_csv_parse text=`内容`**
|
||||
|
||||
## 序列化
|
||||
+ `行集`
|
||||
|
||||
**> host_csv_stringify rows=`行集`**
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
mod corpus;
|
||||
mod kb;
|
||||
mod mcp_server;
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::ffi::{CStr, CString};
|
||||
@@ -548,10 +549,18 @@ fn register(host: &MarqdoHostApi, name: &str, params: &str, fn_ptr: PluginFn) ->
|
||||
}
|
||||
|
||||
pub(crate) fn host_query_json(name: &str) -> Result<serde_json::Value, String> {
|
||||
host_query_json_args(name, &serde_json::json!({}))
|
||||
}
|
||||
|
||||
pub(crate) fn host_query_json_args(
|
||||
name: &str,
|
||||
args: &serde_json::Value,
|
||||
) -> Result<serde_json::Value, String> {
|
||||
let query = unsafe { HOST_QUERY }.ok_or_else(|| "host_query not available".to_string())?;
|
||||
let userdata = unsafe { HOST_USERDATA };
|
||||
let c_name = CString::new(name).map_err(|e| e.to_string())?;
|
||||
let c_args = CString::new("{}").unwrap();
|
||||
let args_s = serde_json::to_string(args).map_err(|e| e.to_string())?;
|
||||
let c_args = CString::new(args_s).map_err(|e| e.to_string())?;
|
||||
let mut out_ptr: *mut c_char = ptr::null_mut();
|
||||
let mut err_ptr: *mut c_char = ptr::null_mut();
|
||||
let rc = unsafe {
|
||||
@@ -987,6 +996,11 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
|
||||
if register(host, "agent_mcp_fixture", "action,fixture", agent_mcp_fixture) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_mcp_serve", "name,tools,transport", mcp_server::agent_mcp_serve)
|
||||
!= 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_kb_add_alias", "kb_dir,slug,alias", agent_kb_add_alias) != 0 {
|
||||
return 1;
|
||||
}
|
||||
|
||||
@@ -0,0 +1,212 @@
|
||||
//! Minimal MCP Server (stdio JSON-RPC) — tools map to `lib.member` via host `call_lib_path`.
|
||||
|
||||
use serde_json::{json, Map, Value};
|
||||
use std::ffi::CStr;
|
||||
use std::io::{BufRead, BufReader, Write};
|
||||
use std::os::raw::{c_char, c_int};
|
||||
|
||||
use crate::{host_query_json_args, parse_args, set_err, set_out};
|
||||
|
||||
fn read_line_message(reader: &mut impl BufRead) -> Result<Option<Value>, String> {
|
||||
let mut line = String::new();
|
||||
let n = reader
|
||||
.read_line(&mut line)
|
||||
.map_err(|e| format!("stdin: {e}"))?;
|
||||
if n == 0 {
|
||||
return Ok(None);
|
||||
}
|
||||
let line = line.trim();
|
||||
if line.is_empty() {
|
||||
return read_line_message(reader);
|
||||
}
|
||||
let v: Value = serde_json::from_str(line).map_err(|e| format!("json-rpc parse: {e}"))?;
|
||||
Ok(Some(v))
|
||||
}
|
||||
|
||||
fn write_message(msg: &Value) -> Result<(), String> {
|
||||
let mut out = std::io::stdout().lock();
|
||||
let s = serde_json::to_string(msg).map_err(|e| e.to_string())?;
|
||||
writeln!(out, "{s}").map_err(|e| format!("stdout: {e}"))?;
|
||||
out.flush().map_err(|e| format!("flush: {e}"))?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn rpc_result(id: &Value, result: Value) -> Value {
|
||||
json!({
|
||||
"jsonrpc": "2.0",
|
||||
"id": id,
|
||||
"result": result,
|
||||
})
|
||||
}
|
||||
|
||||
fn rpc_error(id: &Value, code: i64, message: &str) -> Value {
|
||||
json!({
|
||||
"jsonrpc": "2.0",
|
||||
"id": id,
|
||||
"error": { "code": code, "message": message },
|
||||
})
|
||||
}
|
||||
|
||||
fn tools_list(tools: &[Value]) -> Value {
|
||||
let mut arr = Vec::new();
|
||||
for t in tools {
|
||||
let name = t.get("name").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let desc = t
|
||||
.get("description")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("");
|
||||
if name.is_empty() {
|
||||
continue;
|
||||
}
|
||||
arr.push(json!({
|
||||
"name": name,
|
||||
"description": desc,
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {},
|
||||
"additionalProperties": true
|
||||
}
|
||||
}));
|
||||
}
|
||||
json!({ "tools": arr })
|
||||
}
|
||||
|
||||
fn call_tool(tools: &[Value], name: &str, arguments: &Value) -> Result<Value, String> {
|
||||
let tool = tools
|
||||
.iter()
|
||||
.find(|t| t.get("name").and_then(|v| v.as_str()) == Some(name))
|
||||
.ok_or_else(|| format!("unknown tool `{name}`"))?;
|
||||
let fn_path = tool
|
||||
.get("fn")
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| format!("tool `{name}` missing fn"))?
|
||||
.to_string();
|
||||
let result = host_query_json_args(
|
||||
"call_lib_path",
|
||||
&json!({
|
||||
"path": fn_path,
|
||||
"args": arguments,
|
||||
}),
|
||||
)?;
|
||||
Ok(json!({
|
||||
"content": [{
|
||||
"type": "text",
|
||||
"text": serde_json::to_string(&result).unwrap_or_else(|_| "{}".into())
|
||||
}],
|
||||
"isError": false,
|
||||
"authority": "workbook"
|
||||
}))
|
||||
}
|
||||
|
||||
/// Blocking stdio MCP loop. `tools` is a JSON array of `{name, fn, description}`.
|
||||
pub fn serve_stdio(name: &str, tools: Vec<Value>) -> Result<Value, String> {
|
||||
let stdin = std::io::stdin();
|
||||
let mut reader = BufReader::new(stdin.lock());
|
||||
loop {
|
||||
let Some(msg) = read_line_message(&mut reader)? else {
|
||||
break;
|
||||
};
|
||||
let id = msg.get("id").cloned().unwrap_or(Value::Null);
|
||||
let method = msg.get("method").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let params = msg.get("params").cloned().unwrap_or(json!({}));
|
||||
|
||||
if matches!(id, Value::Null) && method.starts_with("notifications/") {
|
||||
continue;
|
||||
}
|
||||
|
||||
let reply_msg = match method {
|
||||
"initialize" => rpc_result(
|
||||
&id,
|
||||
json!({
|
||||
"protocolVersion": "2024-11-05",
|
||||
"capabilities": { "tools": {} },
|
||||
"serverInfo": { "name": name, "version": "0.1.0" }
|
||||
}),
|
||||
),
|
||||
"tools/list" | "list_tools" => rpc_result(&id, tools_list(&tools)),
|
||||
"tools/call" | "call_tool" => {
|
||||
let tname = params.get("name").and_then(|v| v.as_str()).unwrap_or("");
|
||||
let args = params.get("arguments").cloned().unwrap_or(json!({}));
|
||||
match call_tool(&tools, tname, &args) {
|
||||
Ok(r) => rpc_result(&id, r),
|
||||
Err(e) => rpc_error(&id, -32000, &e),
|
||||
}
|
||||
}
|
||||
"ping" => rpc_result(&id, json!({})),
|
||||
"" => rpc_error(&id, -32600, "missing method"),
|
||||
other => rpc_error(&id, -32601, &format!("method not found: {other}")),
|
||||
};
|
||||
write_message(&reply_msg)?;
|
||||
}
|
||||
Ok(json!({ "ok": true, "transport": "stdio" }))
|
||||
}
|
||||
|
||||
pub fn tools_from_value(v: &Value) -> Vec<Value> {
|
||||
if let Some(arr) = v.as_array() {
|
||||
return arr.clone();
|
||||
}
|
||||
if let Value::Object(map) = v {
|
||||
let mut out = Vec::new();
|
||||
for (name, spec) in map {
|
||||
let mut m = Map::new();
|
||||
m.insert("name".into(), json!(name));
|
||||
if let Some(obj) = spec.as_object() {
|
||||
for (k, val) in obj {
|
||||
m.insert(k.clone(), val.clone());
|
||||
}
|
||||
} else if let Some(s) = spec.as_str() {
|
||||
m.insert("fn".into(), json!(s));
|
||||
}
|
||||
out.push(Value::Object(m));
|
||||
}
|
||||
return out;
|
||||
}
|
||||
Vec::new()
|
||||
}
|
||||
|
||||
pub unsafe extern "C" fn agent_mcp_serve(
|
||||
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, &e);
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let transport = args
|
||||
.get("transport")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("stdio");
|
||||
if transport != "stdio" {
|
||||
set_err(
|
||||
err_msg,
|
||||
&format!("mcp serve: transport `{transport}` not implemented yet (use stdio)"),
|
||||
);
|
||||
return 1;
|
||||
}
|
||||
let name = args
|
||||
.get("name")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("marqdo");
|
||||
let tools = args
|
||||
.get("tools")
|
||||
.map(tools_from_value)
|
||||
.unwrap_or_default();
|
||||
match serve_stdio(name, tools) {
|
||||
Ok(v) => {
|
||||
set_out(out_json, &v.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &e);
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Silence unused import if CStr unused in this module.
|
||||
#[allow(dead_code)]
|
||||
fn _unused(_: &CStr) {}
|
||||
@@ -0,0 +1,15 @@
|
||||
[package]
|
||||
name = "marqdo_plugin_linalg"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo linear algebra plugin — formula-first MatExpr (ABI v2)"
|
||||
publish = false
|
||||
|
||||
[lib]
|
||||
name = "linalg"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
@@ -0,0 +1,216 @@
|
||||
//! Complex dense baseline (L6): parse/store + Frobenius norm.
|
||||
//! Factorize / solve stay real-only for now.
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
use crate::dense::MAX_ELEMENTS;
|
||||
|
||||
pub type CMat = Vec<Vec<(f64, f64)>>;
|
||||
|
||||
pub fn shape(m: &CMat) -> Result<(usize, usize), String> {
|
||||
if m.is_empty() {
|
||||
return Err("empty complex matrix".into());
|
||||
}
|
||||
let r = m.len();
|
||||
let c = m[0].len();
|
||||
if c == 0 || m.iter().any(|row| row.len() != c) {
|
||||
return Err("complex matrix rows must have equal non-zero length".into());
|
||||
}
|
||||
Ok((r, c))
|
||||
}
|
||||
|
||||
fn check_elems(rows: usize, cols: usize) -> Result<(), String> {
|
||||
let n = rows.saturating_mul(cols);
|
||||
if n > MAX_ELEMENTS {
|
||||
return Err(format!(
|
||||
"complex matrix {rows}×{cols} has {n} elements > limit {MAX_ELEMENTS}"
|
||||
));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn parse_cell(c: &Value) -> Result<(f64, f64), String> {
|
||||
if let Some(n) = c
|
||||
.as_f64()
|
||||
.or_else(|| c.as_i64().map(|i| i as f64))
|
||||
.or_else(|| c.as_u64().map(|u| u as f64))
|
||||
{
|
||||
return Ok((n, 0.0));
|
||||
}
|
||||
if let Some(arr) = c.as_array() {
|
||||
if arr.len() == 2 {
|
||||
let re = arr[0]
|
||||
.as_f64()
|
||||
.or_else(|| arr[0].as_i64().map(|i| i as f64))
|
||||
.ok_or_else(|| "complex re must be number".to_string())?;
|
||||
let im = arr[1]
|
||||
.as_f64()
|
||||
.or_else(|| arr[1].as_i64().map(|i| i as f64))
|
||||
.ok_or_else(|| "complex im must be number".to_string())?;
|
||||
return Ok((re, im));
|
||||
}
|
||||
}
|
||||
if let Some(obj) = c.as_object() {
|
||||
let re = obj
|
||||
.get("re")
|
||||
.or_else(|| obj.get("real"))
|
||||
.and_then(|v| v.as_f64().or_else(|| v.as_i64().map(|i| i as f64)))
|
||||
.ok_or_else(|| "complex cell needs re/real".to_string())?;
|
||||
let im = obj
|
||||
.get("im")
|
||||
.or_else(|| obj.get("imag"))
|
||||
.and_then(|v| v.as_f64().or_else(|| v.as_i64().map(|i| i as f64)))
|
||||
.unwrap_or(0.0);
|
||||
return Ok((re, im));
|
||||
}
|
||||
Err("complex cell must be number, [re,im], or {re,im}".into())
|
||||
}
|
||||
|
||||
fn cell_looks_complex(c: &Value) -> bool {
|
||||
if let Some(arr) = c.as_array() {
|
||||
return arr.len() == 2
|
||||
&& arr.iter().all(|x| {
|
||||
x.is_number() || x.as_i64().is_some() || x.as_u64().is_some()
|
||||
});
|
||||
}
|
||||
c.as_object()
|
||||
.map(|o| o.contains_key("re") || o.contains_key("real") || o.contains_key("im"))
|
||||
.unwrap_or(false)
|
||||
}
|
||||
|
||||
/// True if nested list contains any complex-looking cell.
|
||||
pub fn data_has_complex(v: &Value) -> bool {
|
||||
let Some(rows) = v.as_array() else {
|
||||
return false;
|
||||
};
|
||||
rows.iter().any(|row| {
|
||||
row.as_array()
|
||||
.map(|cells| cells.iter().any(cell_looks_complex))
|
||||
.unwrap_or(false)
|
||||
})
|
||||
}
|
||||
|
||||
pub fn from_data(v: &Value) -> Result<CMat, String> {
|
||||
let rows = v
|
||||
.as_array()
|
||||
.ok_or_else(|| "complex data must be list of rows".to_string())?;
|
||||
let mut out = Vec::new();
|
||||
let mut width = None;
|
||||
for row in rows {
|
||||
let cells = row
|
||||
.as_array()
|
||||
.ok_or_else(|| "complex row must be a list".to_string())?;
|
||||
let mut r = Vec::new();
|
||||
for c in cells {
|
||||
r.push(parse_cell(c)?);
|
||||
}
|
||||
if let Some(w) = width {
|
||||
if r.len() != w {
|
||||
return Err("complex matrix rows must have equal length".into());
|
||||
}
|
||||
} else {
|
||||
width = Some(r.len());
|
||||
}
|
||||
out.push(r);
|
||||
}
|
||||
let (rows, cols) = shape(&out)?;
|
||||
check_elems(rows, cols)?;
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
pub fn from_value(v: &Value) -> Result<CMat, String> {
|
||||
if let Some(obj) = v.as_object() {
|
||||
if obj.get("dtype").and_then(|d| d.as_str()) == Some("complex") {
|
||||
if let Some(data) = obj.get("data") {
|
||||
return from_data(data);
|
||||
}
|
||||
}
|
||||
if let Some(data) = obj.get("data") {
|
||||
if data_has_complex(data) {
|
||||
return from_data(data);
|
||||
}
|
||||
}
|
||||
}
|
||||
if v.is_array() && data_has_complex(v) {
|
||||
return from_data(v);
|
||||
}
|
||||
Err("expected linalg_dense dtype=complex or nested complex list".into())
|
||||
}
|
||||
|
||||
fn format_c(z: (f64, f64)) -> String {
|
||||
let (re, im) = z;
|
||||
if im.abs() < 1e-15 {
|
||||
if re.fract() == 0.0 && re.abs() < 1e15 {
|
||||
format!("{}", re as i64)
|
||||
} else {
|
||||
format!("{re}")
|
||||
}
|
||||
} else if re.abs() < 1e-15 {
|
||||
format!("{im}i")
|
||||
} else {
|
||||
format!("{re}{im:+}i")
|
||||
}
|
||||
}
|
||||
|
||||
pub fn to_dense_value(m: &CMat) -> Result<Value, String> {
|
||||
let (rows, cols) = shape(m)?;
|
||||
check_elems(rows, cols)?;
|
||||
let data: Vec<Vec<Value>> = m
|
||||
.iter()
|
||||
.map(|row| {
|
||||
row.iter()
|
||||
.map(|&(re, im)| json!([re, im]))
|
||||
.collect()
|
||||
})
|
||||
.collect();
|
||||
let ascii_rows: Vec<String> = m
|
||||
.iter()
|
||||
.map(|row| {
|
||||
let cells: Vec<String> = row.iter().map(|&z| format_c(z)).collect();
|
||||
format!("[{}]", cells.join(","))
|
||||
})
|
||||
.collect();
|
||||
Ok(json!({
|
||||
"_type": "matrix",
|
||||
"kind": "dense",
|
||||
"rows": rows,
|
||||
"cols": cols,
|
||||
"data": data,
|
||||
"dtype": "complex",
|
||||
"ascii": format!("[{}]", ascii_rows.join(",")),
|
||||
"latex": format!(
|
||||
"\\begin{{bmatrix}}{}\\end{{bmatrix}}",
|
||||
m.iter()
|
||||
.map(|row| {
|
||||
row.iter()
|
||||
.map(|&z| format_c(z))
|
||||
.collect::<Vec<_>>()
|
||||
.join(" & ")
|
||||
})
|
||||
.collect::<Vec<_>>()
|
||||
.join(" \\\\ ")
|
||||
),
|
||||
}))
|
||||
}
|
||||
|
||||
pub fn frobenius_norm(m: &CMat) -> Result<f64, String> {
|
||||
let _ = shape(m)?;
|
||||
let mut s = 0.0;
|
||||
for row in m {
|
||||
for &(re, im) in row {
|
||||
s += re * re + im * im;
|
||||
}
|
||||
}
|
||||
Ok(s.sqrt())
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn fro_i() {
|
||||
let m = from_data(&json!([[[0.0, 1.0], [1.0, 0.0]], [[1.0, 0.0], [0.0, -1.0]]])).unwrap();
|
||||
assert!((frobenius_norm(&m).unwrap() - 2.0).abs() < 1e-12);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,583 @@
|
||||
//! Dense real matrix kernels for L2 (`explicit` / solve / det / trace).
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
use crate::matexpr::{Dim, Expr};
|
||||
|
||||
/// Max elements for `explicit` / dense ops (design default 10^4).
|
||||
pub const MAX_ELEMENTS: usize = 10_000;
|
||||
|
||||
pub type Mat = Vec<Vec<f64>>;
|
||||
|
||||
pub fn check_elems(rows: usize, cols: usize) -> Result<(), String> {
|
||||
let n = rows.saturating_mul(cols);
|
||||
if n > MAX_ELEMENTS {
|
||||
return Err(format!(
|
||||
"dense matrix {rows}×{cols} has {n} elements > limit {MAX_ELEMENTS}; keep symbolic or reduce size"
|
||||
));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn eye(n: usize) -> Mat {
|
||||
let mut m = vec![vec![0.0; n]; n];
|
||||
for i in 0..n {
|
||||
m[i][i] = 1.0;
|
||||
}
|
||||
m
|
||||
}
|
||||
|
||||
pub fn zeros(rows: usize, cols: usize) -> Mat {
|
||||
vec![vec![0.0; cols]; rows]
|
||||
}
|
||||
|
||||
pub fn shape(m: &Mat) -> Result<(usize, usize), String> {
|
||||
if m.is_empty() {
|
||||
return Err("empty dense matrix".into());
|
||||
}
|
||||
let r = m.len();
|
||||
let c = m[0].len();
|
||||
if c == 0 || m.iter().any(|row| row.len() != c) {
|
||||
return Err("dense matrix rows must have equal non-zero length".into());
|
||||
}
|
||||
Ok((r, c))
|
||||
}
|
||||
|
||||
pub fn to_dense_value(m: &Mat) -> Result<Value, String> {
|
||||
let (rows, cols) = shape(m)?;
|
||||
check_elems(rows, cols)?;
|
||||
Ok(json!({
|
||||
"_type": "matrix",
|
||||
"kind": "dense",
|
||||
"rows": rows,
|
||||
"cols": cols,
|
||||
"data": m,
|
||||
"dtype": "real",
|
||||
"ascii": format_ascii(m),
|
||||
"latex": format_latex(m),
|
||||
}))
|
||||
}
|
||||
|
||||
fn format_ascii(m: &Mat) -> String {
|
||||
let rows: Vec<String> = m
|
||||
.iter()
|
||||
.map(|row| {
|
||||
let cells: Vec<String> = row.iter().map(|x| format_num(*x)).collect();
|
||||
format!("[{}]", cells.join(","))
|
||||
})
|
||||
.collect();
|
||||
format!("[{}]", rows.join(","))
|
||||
}
|
||||
|
||||
fn format_latex(m: &Mat) -> String {
|
||||
let body: Vec<String> = m
|
||||
.iter()
|
||||
.map(|row| {
|
||||
row.iter()
|
||||
.map(|x| format_num(*x))
|
||||
.collect::<Vec<_>>()
|
||||
.join(" & ")
|
||||
})
|
||||
.collect();
|
||||
format!(
|
||||
"\\begin{{bmatrix}}{}\\end{{bmatrix}}",
|
||||
body.join(" \\\\ ")
|
||||
)
|
||||
}
|
||||
|
||||
fn format_num(n: f64) -> String {
|
||||
if n.fract() == 0.0 && n.abs() < 1e15 {
|
||||
format!("{}", n as i64)
|
||||
} else {
|
||||
format!("{n}")
|
||||
}
|
||||
}
|
||||
|
||||
pub fn from_value(v: &Value) -> Result<Mat, String> {
|
||||
if let Some(obj) = v.as_object() {
|
||||
if let Some(data) = obj.get("data") {
|
||||
return parse_data(data);
|
||||
}
|
||||
// linalg_expr kind=dense
|
||||
if obj.get("kind").and_then(|k| k.as_str()) == Some("dense") {
|
||||
if let Some(data) = obj.get("data") {
|
||||
return parse_data(data);
|
||||
}
|
||||
}
|
||||
}
|
||||
// Formula Matrix / raw nested list
|
||||
if v.is_array() {
|
||||
return parse_data(v);
|
||||
}
|
||||
Err("expected matrix dense, dense expr, or nested list".into())
|
||||
}
|
||||
|
||||
fn parse_data(v: &Value) -> Result<Mat, String> {
|
||||
let rows = v
|
||||
.as_array()
|
||||
.ok_or_else(|| "dense data must be list of rows".to_string())?;
|
||||
let mut out = Vec::new();
|
||||
let mut width = None;
|
||||
for row in rows {
|
||||
let cells = row
|
||||
.as_array()
|
||||
.ok_or_else(|| "dense row must be a list".to_string())?;
|
||||
let mut r = Vec::new();
|
||||
for c in cells {
|
||||
let n = c
|
||||
.as_f64()
|
||||
.or_else(|| c.as_i64().map(|i| i as f64))
|
||||
.or_else(|| c.as_u64().map(|u| u as f64))
|
||||
.or_else(|| c.as_str().and_then(|s| s.trim().parse().ok()))
|
||||
.ok_or_else(|| "dense cell must be a number".to_string())?;
|
||||
r.push(n);
|
||||
}
|
||||
if let Some(w) = width {
|
||||
if r.len() != w {
|
||||
return Err("dense matrix rows must have equal length".into());
|
||||
}
|
||||
} else {
|
||||
width = Some(r.len());
|
||||
}
|
||||
out.push(r);
|
||||
}
|
||||
let (rows, cols) = shape(&out)?;
|
||||
check_elems(rows, cols)?;
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
fn dim_usize(d: &Dim) -> Result<usize, String> {
|
||||
match d {
|
||||
Dim::Int(n) => Ok(*n),
|
||||
Dim::Sym(s) => Err(format!(
|
||||
"cannot explicit symbolic dim `{s}`; bind concrete sizes or use dense leaves only"
|
||||
)),
|
||||
}
|
||||
}
|
||||
|
||||
/// Evaluate MatExpr to dense; symbols are not allowed unless already dense leaves.
|
||||
pub fn explicit(expr: &Expr) -> Result<Mat, String> {
|
||||
match expr {
|
||||
Expr::Dense { data } => {
|
||||
let (r, c) = shape(data)?;
|
||||
check_elems(r, c)?;
|
||||
Ok(data.clone())
|
||||
}
|
||||
Expr::Eye { n } => {
|
||||
let n = dim_usize(n)?;
|
||||
check_elems(n, n)?;
|
||||
Ok(eye(n))
|
||||
}
|
||||
Expr::Zero { rows, cols } => {
|
||||
let r = dim_usize(rows)?;
|
||||
let c = dim_usize(cols)?;
|
||||
check_elems(r, c)?;
|
||||
Ok(zeros(r, c))
|
||||
}
|
||||
Expr::Symbol { name, .. } => Err(format!(
|
||||
"cannot explicit unbound symbol `{name}`; substitute a dense matrix first"
|
||||
)),
|
||||
Expr::Mul { factors } => {
|
||||
if factors.is_empty() {
|
||||
return Err("empty MatMul".into());
|
||||
}
|
||||
let mut acc = explicit(&factors[0])?;
|
||||
for f in &factors[1..] {
|
||||
acc = matmul(&acc, &explicit(f)?)?;
|
||||
}
|
||||
Ok(acc)
|
||||
}
|
||||
Expr::Add { terms } => {
|
||||
if terms.is_empty() {
|
||||
return Err("empty MatAdd".into());
|
||||
}
|
||||
let mut acc = explicit(&terms[0])?;
|
||||
for t in &terms[1..] {
|
||||
acc = mat_add(&acc, &explicit(t)?)?;
|
||||
}
|
||||
Ok(acc)
|
||||
}
|
||||
Expr::Sub { left, right } => mat_sub(&explicit(left)?, &explicit(right)?),
|
||||
Expr::Transpose { arg } => Ok(transpose(&explicit(arg)?)),
|
||||
Expr::Inv { arg } => invert(&explicit(arg)?),
|
||||
Expr::Kron { factors } => {
|
||||
if factors.is_empty() {
|
||||
return Err("empty Kronecker product".into());
|
||||
}
|
||||
let mut acc = explicit(&factors[0])?;
|
||||
for f in &factors[1..] {
|
||||
acc = kronecker(&acc, &explicit(f)?)?;
|
||||
}
|
||||
Ok(acc)
|
||||
}
|
||||
Expr::Block { blocks } => explicit_block(blocks),
|
||||
}
|
||||
}
|
||||
|
||||
fn explicit_block(blocks: &[Vec<Expr>]) -> Result<Mat, String> {
|
||||
if blocks.is_empty() || blocks[0].is_empty() {
|
||||
return Err("empty block matrix".into());
|
||||
}
|
||||
let br = blocks.len();
|
||||
let bc = blocks[0].len();
|
||||
let mut tiles: Vec<Vec<Mat>> = Vec::with_capacity(br);
|
||||
for i in 0..br {
|
||||
let mut row = Vec::with_capacity(bc);
|
||||
for j in 0..bc {
|
||||
row.push(explicit(&blocks[i][j])?);
|
||||
}
|
||||
tiles.push(row);
|
||||
}
|
||||
// Validate and assemble
|
||||
let mut row_heights = Vec::with_capacity(br);
|
||||
for i in 0..br {
|
||||
let (h, _) = shape(&tiles[i][0])?;
|
||||
for j in 1..bc {
|
||||
let (h2, _) = shape(&tiles[i][j])?;
|
||||
if h != h2 {
|
||||
return Err("block row height mismatch when explicit".into());
|
||||
}
|
||||
}
|
||||
row_heights.push(h);
|
||||
}
|
||||
let mut col_widths = Vec::with_capacity(bc);
|
||||
for j in 0..bc {
|
||||
let (_, w) = shape(&tiles[0][j])?;
|
||||
for i in 1..br {
|
||||
let (_, w2) = shape(&tiles[i][j])?;
|
||||
if w != w2 {
|
||||
return Err("block col width mismatch when explicit".into());
|
||||
}
|
||||
}
|
||||
col_widths.push(w);
|
||||
}
|
||||
let total_r: usize = row_heights.iter().sum();
|
||||
let total_c: usize = col_widths.iter().sum();
|
||||
check_elems(total_r, total_c)?;
|
||||
let mut out = zeros(total_r, total_c);
|
||||
let mut r0 = 0;
|
||||
for i in 0..br {
|
||||
let mut c0 = 0;
|
||||
for j in 0..bc {
|
||||
let tile = &tiles[i][j];
|
||||
let (h, w) = shape(tile)?;
|
||||
for ii in 0..h {
|
||||
for jj in 0..w {
|
||||
out[r0 + ii][c0 + jj] = tile[ii][jj];
|
||||
}
|
||||
}
|
||||
c0 += w;
|
||||
}
|
||||
r0 += row_heights[i];
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
pub fn kronecker(a: &Mat, b: &Mat) -> Result<Mat, String> {
|
||||
let (ar, ac) = shape(a)?;
|
||||
let (br, bc) = shape(b)?;
|
||||
let rows = ar.saturating_mul(br);
|
||||
let cols = ac.saturating_mul(bc);
|
||||
check_elems(rows, cols)?;
|
||||
let mut out = zeros(rows, cols);
|
||||
for i in 0..ar {
|
||||
for j in 0..ac {
|
||||
let aij = a[i][j];
|
||||
for ii in 0..br {
|
||||
for jj in 0..bc {
|
||||
out[i * br + ii][j * bc + jj] = aij * b[ii][jj];
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
pub fn matmul(a: &Mat, b: &Mat) -> Result<Mat, String> {
|
||||
let (ar, ac) = shape(a)?;
|
||||
let (br, bc) = shape(b)?;
|
||||
if ac != br {
|
||||
return Err(format!(
|
||||
"matmul shape mismatch: {ar}×{ac} · {br}×{bc}"
|
||||
));
|
||||
}
|
||||
check_elems(ar, bc)?;
|
||||
let mut out = zeros(ar, bc);
|
||||
for i in 0..ar {
|
||||
for k in 0..ac {
|
||||
let aik = a[i][k];
|
||||
if aik == 0.0 {
|
||||
continue;
|
||||
}
|
||||
for j in 0..bc {
|
||||
out[i][j] += aik * b[k][j];
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
pub fn mat_add(a: &Mat, b: &Mat) -> Result<Mat, String> {
|
||||
let (ar, ac) = shape(a)?;
|
||||
let (br, bc) = shape(b)?;
|
||||
if ar != br || ac != bc {
|
||||
return Err(format!("add shape mismatch: {ar}×{ac} vs {br}×{bc}"));
|
||||
}
|
||||
let mut out = zeros(ar, ac);
|
||||
for i in 0..ar {
|
||||
for j in 0..ac {
|
||||
out[i][j] = a[i][j] + b[i][j];
|
||||
}
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
pub fn mat_sub(a: &Mat, b: &Mat) -> Result<Mat, String> {
|
||||
let (ar, ac) = shape(a)?;
|
||||
let (br, bc) = shape(b)?;
|
||||
if ar != br || ac != bc {
|
||||
return Err(format!("sub shape mismatch: {ar}×{ac} vs {br}×{bc}"));
|
||||
}
|
||||
let mut out = zeros(ar, ac);
|
||||
for i in 0..ar {
|
||||
for j in 0..ac {
|
||||
out[i][j] = a[i][j] - b[i][j];
|
||||
}
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
pub fn transpose(m: &Mat) -> Mat {
|
||||
let (r, c) = shape(m).unwrap_or((0, 0));
|
||||
let mut out = zeros(c, r);
|
||||
for i in 0..r {
|
||||
for j in 0..c {
|
||||
out[j][i] = m[i][j];
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
pub fn trace(m: &Mat) -> Result<f64, String> {
|
||||
let (r, c) = shape(m)?;
|
||||
if r != c {
|
||||
return Err(format!("trace needs square matrix, got {r}×{c}"));
|
||||
}
|
||||
Ok((0..r).map(|i| m[i][i]).sum())
|
||||
}
|
||||
|
||||
pub fn det(m: &Mat) -> Result<f64, String> {
|
||||
let (n, c) = shape(m)?;
|
||||
if n != c {
|
||||
return Err(format!("det needs square matrix, got {n}×{c}"));
|
||||
}
|
||||
if n == 0 {
|
||||
return Ok(1.0);
|
||||
}
|
||||
if n == 1 {
|
||||
return Ok(m[0][0]);
|
||||
}
|
||||
if n == 2 {
|
||||
return Ok(m[0][0] * m[1][1] - m[0][1] * m[1][0]);
|
||||
}
|
||||
// Gaussian elimination with partial pivoting
|
||||
let mut a = m.clone();
|
||||
let mut det = 1.0;
|
||||
for k in 0..n {
|
||||
let mut piv = k;
|
||||
let mut best = a[k][k].abs();
|
||||
for i in (k + 1)..n {
|
||||
let v = a[i][k].abs();
|
||||
if v > best {
|
||||
best = v;
|
||||
piv = i;
|
||||
}
|
||||
}
|
||||
if best < 1e-15 {
|
||||
return Ok(0.0);
|
||||
}
|
||||
if piv != k {
|
||||
a.swap(k, piv);
|
||||
det = -det;
|
||||
}
|
||||
let akk = a[k][k];
|
||||
det *= akk;
|
||||
for i in (k + 1)..n {
|
||||
let f = a[i][k] / akk;
|
||||
for j in k..n {
|
||||
a[i][j] -= f * a[k][j];
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(det)
|
||||
}
|
||||
|
||||
pub fn invert(m: &Mat) -> Result<Mat, String> {
|
||||
let (n, c) = shape(m)?;
|
||||
if n != c {
|
||||
return Err(format!("inverse needs square matrix, got {n}×{c}"));
|
||||
}
|
||||
check_elems(n, n)?;
|
||||
// Augment [A|I]
|
||||
let mut a = zeros(n, 2 * n);
|
||||
for i in 0..n {
|
||||
for j in 0..n {
|
||||
a[i][j] = m[i][j];
|
||||
}
|
||||
a[i][n + i] = 1.0;
|
||||
}
|
||||
for k in 0..n {
|
||||
let mut piv = k;
|
||||
let mut best = a[k][k].abs();
|
||||
for i in (k + 1)..n {
|
||||
let v = a[i][k].abs();
|
||||
if v > best {
|
||||
best = v;
|
||||
piv = i;
|
||||
}
|
||||
}
|
||||
if best < 1e-15 {
|
||||
return Err("matrix is singular (not invertible)".into());
|
||||
}
|
||||
if piv != k {
|
||||
a.swap(k, piv);
|
||||
}
|
||||
let akk = a[k][k];
|
||||
for j in 0..(2 * n) {
|
||||
a[k][j] /= akk;
|
||||
}
|
||||
for i in 0..n {
|
||||
if i == k {
|
||||
continue;
|
||||
}
|
||||
let f = a[i][k];
|
||||
for j in 0..(2 * n) {
|
||||
a[i][j] -= f * a[k][j];
|
||||
}
|
||||
}
|
||||
}
|
||||
let mut out = zeros(n, n);
|
||||
for i in 0..n {
|
||||
for j in 0..n {
|
||||
out[i][j] = a[i][n + j];
|
||||
}
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
/// Solve A x = b. `b` may be n×1 or n×k; returns n×k.
|
||||
pub fn solve(a: &Mat, b: &Mat) -> Result<Mat, String> {
|
||||
let (n, ac) = shape(a)?;
|
||||
if n != ac {
|
||||
return Err(format!("solve needs square A, got {n}×{ac}"));
|
||||
}
|
||||
let (br, bc) = shape(b)?;
|
||||
if br != n {
|
||||
return Err(format!("solve rhs rows {br} != A rows {n}"));
|
||||
}
|
||||
// Augment [A|B]
|
||||
let mut m = zeros(n, n + bc);
|
||||
for i in 0..n {
|
||||
for j in 0..n {
|
||||
m[i][j] = a[i][j];
|
||||
}
|
||||
for j in 0..bc {
|
||||
m[i][n + j] = b[i][j];
|
||||
}
|
||||
}
|
||||
for k in 0..n {
|
||||
let mut piv = k;
|
||||
let mut best = m[k][k].abs();
|
||||
for i in (k + 1)..n {
|
||||
let v = m[i][k].abs();
|
||||
if v > best {
|
||||
best = v;
|
||||
piv = i;
|
||||
}
|
||||
}
|
||||
if best < 1e-15 {
|
||||
return Err("singular matrix in solve".into());
|
||||
}
|
||||
if piv != k {
|
||||
m.swap(k, piv);
|
||||
}
|
||||
let akk = m[k][k];
|
||||
for j in k..(n + bc) {
|
||||
m[k][j] /= akk;
|
||||
}
|
||||
for i in 0..n {
|
||||
if i == k {
|
||||
continue;
|
||||
}
|
||||
let f = m[i][k];
|
||||
for j in k..(n + bc) {
|
||||
m[i][j] -= f * m[k][j];
|
||||
}
|
||||
}
|
||||
}
|
||||
let mut x = zeros(n, bc);
|
||||
for i in 0..n {
|
||||
for j in 0..bc {
|
||||
x[i][j] = m[i][n + j];
|
||||
}
|
||||
}
|
||||
Ok(x)
|
||||
}
|
||||
|
||||
pub fn solve_result(a: &Mat, b: &Mat) -> Result<Value, String> {
|
||||
let x = solve(a, b)?;
|
||||
let ax = matmul(a, &x)?;
|
||||
let resid = mat_sub(&ax, b)?;
|
||||
let mut max_r = 0.0_f64;
|
||||
for row in &resid {
|
||||
for &v in row {
|
||||
max_r = max_r.max(v.abs());
|
||||
}
|
||||
}
|
||||
Ok(json!({
|
||||
"_type": "linalg_solve",
|
||||
"method": "gauss",
|
||||
"x": to_dense_value(&x)?,
|
||||
"residual_max": max_r,
|
||||
}))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn solve_2x2() {
|
||||
let a = vec![vec![2.0, 1.0], vec![1.0, 3.0]];
|
||||
let b = vec![vec![5.0], vec![5.0]];
|
||||
let x = solve(&a, &b).unwrap();
|
||||
assert!((x[0][0] - 2.0).abs() < 1e-9);
|
||||
assert!((x[1][0] - 1.0).abs() < 1e-9);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn det_2x2() {
|
||||
let m = vec![vec![1.0, 2.0], vec![3.0, 4.0]];
|
||||
assert!((det(&m).unwrap() + 2.0).abs() < 1e-9);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn explicit_mul() {
|
||||
let a = Expr::Dense {
|
||||
data: vec![vec![1.0, 2.0], vec![0.0, 1.0]],
|
||||
};
|
||||
let b = Expr::Dense {
|
||||
data: vec![vec![1.0, 0.0], vec![1.0, 1.0]],
|
||||
};
|
||||
let p = Expr::Mul {
|
||||
factors: vec![a, b],
|
||||
};
|
||||
let m = explicit(&p).unwrap();
|
||||
assert_eq!(m, vec![vec![3.0, 2.0], vec![1.0, 1.0]]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn oversize_guard() {
|
||||
assert!(check_elems(101, 100).is_err());
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,361 @@
|
||||
//! Structure SVG for factorizations (teaching layouts) with Q8-aligned themes.
|
||||
|
||||
use serde_json::Value;
|
||||
|
||||
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
||||
pub enum ThemeName {
|
||||
Dark,
|
||||
Light,
|
||||
Bw,
|
||||
}
|
||||
|
||||
impl ThemeName {
|
||||
pub fn parse(raw: &str) -> Result<Self, String> {
|
||||
match raw.trim().to_ascii_lowercase().as_str() {
|
||||
"dark" | "暗" => Ok(Self::Dark),
|
||||
"light" | "亮" | "浅" => Ok(Self::Light),
|
||||
"bw" | "mono" | "黑白" => Ok(Self::Bw),
|
||||
other => Err(format!("unknown theme `{other}` (dark|light|bw)")),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn as_str(self) -> &'static str {
|
||||
match self {
|
||||
Self::Dark => "dark",
|
||||
Self::Light => "light",
|
||||
Self::Bw => "bw",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
struct Theme {
|
||||
name: ThemeName,
|
||||
bg: &'static str,
|
||||
ink: &'static str,
|
||||
muted: &'static str,
|
||||
stroke: &'static str,
|
||||
box_a: &'static str,
|
||||
box_b: &'static str,
|
||||
box_c: &'static str,
|
||||
heat_neg: &'static str,
|
||||
heat_pos: &'static str,
|
||||
}
|
||||
|
||||
impl Theme {
|
||||
fn of(name: ThemeName) -> Self {
|
||||
match name {
|
||||
ThemeName::Dark => Self {
|
||||
name,
|
||||
bg: "#0a0e14",
|
||||
ink: "#e8eef6",
|
||||
muted: "#93a4b8",
|
||||
stroke: "#6b7f96",
|
||||
box_a: "#1e3a5f",
|
||||
box_b: "#3d2e14",
|
||||
box_c: "#1e3f2e",
|
||||
heat_neg: "#cc5555",
|
||||
heat_pos: "#4c8fff",
|
||||
},
|
||||
ThemeName::Light => Self {
|
||||
name,
|
||||
bg: "#eef3f9",
|
||||
ink: "#15202b",
|
||||
muted: "#5a6a7a",
|
||||
stroke: "#4a5a6a",
|
||||
box_a: "#e8f1ff",
|
||||
box_b: "#fff3d6",
|
||||
box_c: "#e8ffe8",
|
||||
heat_neg: "#cc3333",
|
||||
heat_pos: "#2266aa",
|
||||
},
|
||||
ThemeName::Bw => Self {
|
||||
name,
|
||||
bg: "#ffffff",
|
||||
ink: "#111111",
|
||||
muted: "#555555",
|
||||
stroke: "#222222",
|
||||
box_a: "#f0f0f0",
|
||||
box_b: "#e0e0e0",
|
||||
box_c: "#d0d0d0",
|
||||
heat_neg: "#000000",
|
||||
heat_pos: "#666666",
|
||||
},
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Draw a factor object or matrix as structure SVG.
|
||||
pub fn draw_factor(
|
||||
factor: &Value,
|
||||
kind: Option<&str>,
|
||||
path: Option<&str>,
|
||||
theme: ThemeName,
|
||||
) -> Result<String, String> {
|
||||
let kind = kind
|
||||
.or_else(|| factor.get("kind").and_then(|k| k.as_str()))
|
||||
.unwrap_or("structure");
|
||||
let th = Theme::of(theme);
|
||||
let svg = match kind {
|
||||
"eig" => draw_eig(factor, &th),
|
||||
"svd" => draw_svd(factor, &th),
|
||||
"qr" => draw_qr(factor, &th),
|
||||
"lu" | "ge" => draw_lu(factor, &th),
|
||||
"chol" => draw_chol(factor, &th),
|
||||
"structure" => draw_structure(factor, &th),
|
||||
"heatmap" | "hinton" => draw_heatmap(factor, kind == "hinton", &th),
|
||||
other => {
|
||||
return Err(format!(
|
||||
"unknown draw kind `{other}` (want eig|svd|qr|lu|ge|chol|structure|heatmap|hinton)"
|
||||
))
|
||||
}
|
||||
};
|
||||
let _ = path;
|
||||
Ok(svg)
|
||||
}
|
||||
|
||||
fn escape(s: &str) -> String {
|
||||
s.replace('&', "&")
|
||||
.replace('<', "<")
|
||||
.replace('>', ">")
|
||||
}
|
||||
|
||||
fn box_svg(x: f64, y: f64, w: f64, h: f64, label: &str, fill: &str, th: &Theme) -> String {
|
||||
format!(
|
||||
"<rect x=\"{x}\" y=\"{y}\" width=\"{w}\" height=\"{h}\" fill=\"{fill}\" stroke=\"{}\" stroke-width=\"1.5\" rx=\"4\"/>\
|
||||
<text x=\"{}\" y=\"{}\" text-anchor=\"middle\" dominant-baseline=\"middle\" font-size=\"16\" font-family=\"serif\" fill=\"{}\">{}</text>",
|
||||
th.stroke,
|
||||
x + w / 2.0,
|
||||
y + h / 2.0,
|
||||
th.ink,
|
||||
escape(label)
|
||||
)
|
||||
}
|
||||
|
||||
fn root(w: f64, h: f64, kind: &str, th: &Theme, body: &str) -> String {
|
||||
format!(
|
||||
"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{w}\" height=\"{h}\" data-linalg=\"{kind}\" data-theme=\"{}\" style=\"background:{}\">\
|
||||
{body}\
|
||||
</svg>",
|
||||
th.name.as_str(),
|
||||
th.bg
|
||||
)
|
||||
}
|
||||
|
||||
fn draw_eig(factor: &Value, th: &Theme) -> String {
|
||||
let latex = factor
|
||||
.get("latex")
|
||||
.and_then(|x| x.as_str())
|
||||
.unwrap_or("A = P D P^{-1}");
|
||||
let evals = factor
|
||||
.get("eigenvalues")
|
||||
.and_then(|x| x.as_array())
|
||||
.map(|a| {
|
||||
a.iter()
|
||||
.filter_map(|v| v.as_f64())
|
||||
.map(|v| format!("{v:.4}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join(", ")
|
||||
})
|
||||
.unwrap_or_default();
|
||||
let body = format!(
|
||||
"<text x=\"16\" y=\"28\" font-size=\"18\" font-family=\"serif\" fill=\"{}\">{}</text>\
|
||||
{}\
|
||||
{}\
|
||||
{}\
|
||||
<text x=\"16\" y=\"120\" font-size=\"13\" font-family=\"sans-serif\" fill=\"{}\">λ = [{}]</text>",
|
||||
th.ink,
|
||||
escape(latex),
|
||||
box_svg(40.0, 48.0, 70.0, 50.0, "P", th.box_a, th),
|
||||
box_svg(130.0, 48.0, 70.0, 50.0, "D", th.box_b, th),
|
||||
box_svg(220.0, 48.0, 90.0, 50.0, "P⁻¹", th.box_a, th),
|
||||
th.muted,
|
||||
escape(&evals)
|
||||
);
|
||||
root(520.0, 140.0, "eig", th, &body)
|
||||
}
|
||||
|
||||
fn draw_svd(factor: &Value, th: &Theme) -> String {
|
||||
let s = factor
|
||||
.get("S")
|
||||
.and_then(|x| x.as_array())
|
||||
.map(|a| {
|
||||
a.iter()
|
||||
.filter_map(|v| v.as_f64())
|
||||
.map(|v| format!("{v:.4}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join(", ")
|
||||
})
|
||||
.unwrap_or_default();
|
||||
let body = format!(
|
||||
"<text x=\"16\" y=\"28\" font-size=\"18\" font-family=\"serif\" fill=\"{}\">A = U Σ V⊤</text>\
|
||||
{}\
|
||||
{}\
|
||||
{}\
|
||||
<text x=\"16\" y=\"120\" font-size=\"13\" font-family=\"sans-serif\" fill=\"{}\">σ = [{}]</text>",
|
||||
th.ink,
|
||||
box_svg(40.0, 48.0, 70.0, 50.0, "U", th.box_a, th),
|
||||
box_svg(130.0, 48.0, 70.0, 50.0, "Σ", th.box_b, th),
|
||||
box_svg(220.0, 48.0, 80.0, 50.0, "V⊤", th.box_a, th),
|
||||
th.muted,
|
||||
escape(&s)
|
||||
);
|
||||
root(560.0, 140.0, "svd", th, &body)
|
||||
}
|
||||
|
||||
fn draw_qr(_factor: &Value, th: &Theme) -> String {
|
||||
let body = format!(
|
||||
"<text x=\"16\" y=\"28\" font-size=\"18\" font-family=\"serif\" fill=\"{}\">A = Q R</text>\
|
||||
{}\
|
||||
{}",
|
||||
th.ink,
|
||||
box_svg(40.0, 48.0, 70.0, 50.0, "Q", th.box_a, th),
|
||||
box_svg(130.0, 48.0, 70.0, 50.0, "R", th.box_b, th),
|
||||
);
|
||||
root(420.0, 120.0, "qr", th, &body)
|
||||
}
|
||||
|
||||
fn draw_lu(_factor: &Value, th: &Theme) -> String {
|
||||
let body = format!(
|
||||
"<text x=\"16\" y=\"28\" font-size=\"18\" font-family=\"serif\" fill=\"{}\">A = L U</text>\
|
||||
{}\
|
||||
{}",
|
||||
th.ink,
|
||||
box_svg(40.0, 48.0, 70.0, 50.0, "L", th.box_c, th),
|
||||
box_svg(130.0, 48.0, 70.0, 50.0, "U", th.box_b, th),
|
||||
);
|
||||
root(420.0, 120.0, "lu", th, &body)
|
||||
}
|
||||
|
||||
fn draw_chol(_factor: &Value, th: &Theme) -> String {
|
||||
let body = format!(
|
||||
"<text x=\"16\" y=\"28\" font-size=\"18\" font-family=\"serif\" fill=\"{}\">A = L L⊤</text>\
|
||||
{}\
|
||||
{}",
|
||||
th.ink,
|
||||
box_svg(40.0, 48.0, 70.0, 50.0, "L", th.box_c, th),
|
||||
box_svg(130.0, 48.0, 80.0, 50.0, "L⊤", th.box_c, th),
|
||||
);
|
||||
root(420.0, 120.0, "chol", th, &body)
|
||||
}
|
||||
|
||||
fn draw_structure(factor: &Value, th: &Theme) -> String {
|
||||
let label = if let (Some(r), Some(c)) = (factor.get("rows"), factor.get("cols")) {
|
||||
format!("{}×{}", r, c)
|
||||
} else if let Some(Value::Array(a)) = factor.get("shape") {
|
||||
if a.len() >= 2 {
|
||||
format!("{}×{}", a[0], a[1])
|
||||
} else {
|
||||
factor
|
||||
.get("kind")
|
||||
.and_then(|k| k.as_str())
|
||||
.unwrap_or("matrix")
|
||||
.to_string()
|
||||
}
|
||||
} else {
|
||||
factor
|
||||
.get("kind")
|
||||
.and_then(|k| k.as_str())
|
||||
.unwrap_or("matrix")
|
||||
.to_string()
|
||||
};
|
||||
let body = box_svg(40.0, 30.0, 160.0, 60.0, &label, th.box_a, th);
|
||||
root(280.0, 120.0, "structure", th, &body)
|
||||
}
|
||||
|
||||
fn draw_heatmap(factor: &Value, hinton: bool, th: &Theme) -> String {
|
||||
let data = factor
|
||||
.get("data")
|
||||
.or_else(|| factor.get("eigenvectors").and_then(|v| v.get("data")))
|
||||
.and_then(|d| d.as_array());
|
||||
let Some(rows) = data else {
|
||||
return draw_structure(factor, th);
|
||||
};
|
||||
let n = rows.len().min(16);
|
||||
let m = rows
|
||||
.first()
|
||||
.and_then(|r| r.as_array())
|
||||
.map(|r| r.len())
|
||||
.unwrap_or(0)
|
||||
.min(16);
|
||||
if n == 0 || m == 0 {
|
||||
return draw_structure(factor, th);
|
||||
}
|
||||
let mut max_abs: f64 = 1e-12;
|
||||
for row in rows.iter().take(n) {
|
||||
if let Some(cells) = row.as_array() {
|
||||
for c in cells.iter().take(m) {
|
||||
let v = cell_mag(c);
|
||||
max_abs = max_abs.max(v);
|
||||
}
|
||||
}
|
||||
}
|
||||
let cell = 18.0;
|
||||
let w = 40.0 + m as f64 * cell;
|
||||
let h = 40.0 + n as f64 * cell;
|
||||
let tag = if hinton { "hinton" } else { "heatmap" };
|
||||
let mut parts = vec![format!(
|
||||
"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{w}\" height=\"{h}\" data-linalg=\"{tag}\" data-theme=\"{}\" style=\"background:{}\">",
|
||||
th.name.as_str(),
|
||||
th.bg
|
||||
)];
|
||||
for (i, row) in rows.iter().take(n).enumerate() {
|
||||
let Some(cells) = row.as_array() else { continue };
|
||||
for (j, c) in cells.iter().take(m).enumerate() {
|
||||
let v = cell_signed(c);
|
||||
let x = 20.0 + j as f64 * cell;
|
||||
let y = 20.0 + i as f64 * cell;
|
||||
if hinton {
|
||||
let s = (v.abs() / max_abs).sqrt() * (cell - 4.0);
|
||||
let fill = if v >= 0.0 { th.heat_pos } else { th.heat_neg };
|
||||
parts.push(format!(
|
||||
"<rect x=\"{}\" y=\"{}\" width=\"{s}\" height=\"{s}\" fill=\"{fill}\"/>",
|
||||
x + (cell - s) / 2.0,
|
||||
y + (cell - s) / 2.0
|
||||
));
|
||||
} else {
|
||||
let t = ((v / max_abs) + 1.0) * 0.5;
|
||||
let r = (255.0 * (1.0 - t)) as u8;
|
||||
let b = (255.0 * t) as u8;
|
||||
let fill = if th.name == ThemeName::Bw {
|
||||
let g = (255.0 * (1.0 - v.abs() / max_abs)) as u8;
|
||||
format!("rgb({g},{g},{g})")
|
||||
} else {
|
||||
format!("rgb({r},80,{b})")
|
||||
};
|
||||
parts.push(format!(
|
||||
"<rect x=\"{x}\" y=\"{y}\" width=\"{cell}\" height=\"{cell}\" fill=\"{fill}\" stroke=\"{}\" stroke-width=\"0.5\"/>",
|
||||
th.bg
|
||||
));
|
||||
}
|
||||
}
|
||||
}
|
||||
parts.push("</svg>".into());
|
||||
parts.join("")
|
||||
}
|
||||
|
||||
fn cell_mag(c: &Value) -> f64 {
|
||||
if let Some(v) = c.as_f64() {
|
||||
return v.abs();
|
||||
}
|
||||
if let Some(a) = c.as_array() {
|
||||
if a.len() >= 2 {
|
||||
let re = a[0].as_f64().unwrap_or(0.0);
|
||||
let im = a[1].as_f64().unwrap_or(0.0);
|
||||
return (re * re + im * im).sqrt();
|
||||
}
|
||||
}
|
||||
0.0
|
||||
}
|
||||
|
||||
fn cell_signed(c: &Value) -> f64 {
|
||||
if let Some(v) = c.as_f64() {
|
||||
return v;
|
||||
}
|
||||
// complex: use real part for signed heatmap, magnitude for abs
|
||||
if let Some(a) = c.as_array() {
|
||||
if a.len() >= 2 {
|
||||
return a[0].as_f64().unwrap_or(0.0);
|
||||
}
|
||||
}
|
||||
0.0
|
||||
}
|
||||
@@ -0,0 +1,451 @@
|
||||
//! Dense factorizations for L4: LU, QR, eig (symmetric Jacobi), SVD, Cholesky.
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
use crate::dense::{self, Mat, MAX_ELEMENTS};
|
||||
|
||||
pub const FACTOR_MAX_SIDE: usize = 64;
|
||||
|
||||
fn check_side(n: usize, label: &str) -> Result<(), String> {
|
||||
if n > FACTOR_MAX_SIDE {
|
||||
return Err(format!(
|
||||
"{label} limited to side ≤ {FACTOR_MAX_SIDE} (got {n})"
|
||||
));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn check_side_limit(n: usize, label: &str) -> Result<(), String> {
|
||||
check_side(n, label)
|
||||
}
|
||||
|
||||
fn check_mat(m: &Mat) -> Result<(usize, usize), String> {
|
||||
let (r, c) = dense::shape(m)?;
|
||||
dense::check_elems(r, c)?;
|
||||
Ok((r, c))
|
||||
}
|
||||
|
||||
/// Factorize `kind` ∈ lu|qr|svd|eig|chol.
|
||||
pub fn factorize(m: &Mat, kind: &str) -> Result<Value, String> {
|
||||
let kind = kind.trim().to_ascii_lowercase();
|
||||
match kind.as_str() {
|
||||
"lu" => lu_value(m),
|
||||
"qr" => qr_value(m),
|
||||
"eig" => eig_value(m),
|
||||
"svd" => svd_value(m),
|
||||
"chol" | "cholesky" => chol_value(m),
|
||||
other => Err(format!(
|
||||
"unknown factorize kind `{other}` (want lu|qr|svd|eig|chol)"
|
||||
)),
|
||||
}
|
||||
}
|
||||
|
||||
fn lu_value(m: &Mat) -> Result<Value, String> {
|
||||
let (n, c) = check_mat(m)?;
|
||||
if n != c {
|
||||
return Err(format!("LU needs square matrix, got {n}×{c}"));
|
||||
}
|
||||
check_side(n, "LU")?;
|
||||
let (l, u, piv) = lu_decomp(m)?;
|
||||
Ok(json!({
|
||||
"_type": "linalg_factor",
|
||||
"kind": "lu",
|
||||
"L": dense::to_dense_value(&l)?,
|
||||
"U": dense::to_dense_value(&u)?,
|
||||
"pivots": piv,
|
||||
"latex": "A = LU",
|
||||
"ascii": "LU",
|
||||
}))
|
||||
}
|
||||
|
||||
fn qr_value(m: &Mat) -> Result<Value, String> {
|
||||
let (rows, cols) = check_mat(m)?;
|
||||
check_side(rows.max(cols), "QR")?;
|
||||
let (q, r) = qr_decomp(m)?;
|
||||
Ok(json!({
|
||||
"_type": "linalg_factor",
|
||||
"kind": "qr",
|
||||
"Q": dense::to_dense_value(&q)?,
|
||||
"R": dense::to_dense_value(&r)?,
|
||||
"latex": "A = QR",
|
||||
"ascii": "QR",
|
||||
}))
|
||||
}
|
||||
|
||||
fn eig_value(m: &Mat) -> Result<Value, String> {
|
||||
let (n, c) = check_mat(m)?;
|
||||
if n != c {
|
||||
return Err(format!("eig needs square matrix, got {n}×{c}"));
|
||||
}
|
||||
check_side(n, "eig")?;
|
||||
// Jacobi assumes symmetric; if nearly symmetric, symmetrize.
|
||||
let (evals, evecs) = jacobi_symm(m)?;
|
||||
let d = dense::zeros(n, n);
|
||||
let mut d = d;
|
||||
for i in 0..n {
|
||||
d[i][i] = evals[i];
|
||||
}
|
||||
Ok(json!({
|
||||
"_type": "linalg_factor",
|
||||
"kind": "eig",
|
||||
"eigenvalues": evals,
|
||||
"eigenvectors": dense::to_dense_value(&evecs)?,
|
||||
"D": dense::to_dense_value(&d)?,
|
||||
"latex": "A = P D P^{-1}",
|
||||
"ascii": "eig",
|
||||
}))
|
||||
}
|
||||
|
||||
fn svd_value(m: &Mat) -> Result<Value, String> {
|
||||
let (rows, cols) = check_mat(m)?;
|
||||
check_side(rows.max(cols), "SVD")?;
|
||||
let (u, s, vt) = svd_decomp(m)?;
|
||||
Ok(json!({
|
||||
"_type": "linalg_factor",
|
||||
"kind": "svd",
|
||||
"U": dense::to_dense_value(&u)?,
|
||||
"S": s,
|
||||
"Vt": dense::to_dense_value(&vt)?,
|
||||
"latex": "A = U \\Sigma V^{\\top}",
|
||||
"ascii": "SVD",
|
||||
}))
|
||||
}
|
||||
|
||||
fn chol_value(m: &Mat) -> Result<Value, String> {
|
||||
let (n, c) = check_mat(m)?;
|
||||
if n != c {
|
||||
return Err(format!("Cholesky needs square matrix, got {n}×{c}"));
|
||||
}
|
||||
check_side(n, "Cholesky")?;
|
||||
let l = cholesky(m)?;
|
||||
Ok(json!({
|
||||
"_type": "linalg_factor",
|
||||
"kind": "chol",
|
||||
"L": dense::to_dense_value(&l)?,
|
||||
"latex": "A = L L^{\\top}",
|
||||
"ascii": "chol",
|
||||
}))
|
||||
}
|
||||
|
||||
/// PA = LU with partial pivoting; returns (L, U, pivot row order).
|
||||
pub fn lu_decomp(a: &Mat) -> Result<(Mat, Mat, Vec<usize>), String> {
|
||||
let (n, _) = dense::shape(a)?;
|
||||
let mut m = a.clone();
|
||||
let mut piv: Vec<usize> = (0..n).collect();
|
||||
let mut l = dense::eye(n);
|
||||
for k in 0..n {
|
||||
let mut piv_row = k;
|
||||
let mut best = m[k][k].abs();
|
||||
for i in (k + 1)..n {
|
||||
let v = m[i][k].abs();
|
||||
if v > best {
|
||||
best = v;
|
||||
piv_row = i;
|
||||
}
|
||||
}
|
||||
if best < 1e-15 {
|
||||
return Err("LU failed: singular or near-singular matrix".into());
|
||||
}
|
||||
if piv_row != k {
|
||||
m.swap(k, piv_row);
|
||||
piv.swap(k, piv_row);
|
||||
for j in 0..k {
|
||||
let t = l[k][j];
|
||||
l[k][j] = l[piv_row][j];
|
||||
l[piv_row][j] = t;
|
||||
}
|
||||
}
|
||||
for i in (k + 1)..n {
|
||||
let f = m[i][k] / m[k][k];
|
||||
l[i][k] = f;
|
||||
m[i][k] = 0.0;
|
||||
for j in (k + 1)..n {
|
||||
m[i][j] -= f * m[k][j];
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok((l, m, piv))
|
||||
}
|
||||
|
||||
/// Thin QR via modified Gram-Schmidt. A is m×n with m≥n preferred.
|
||||
pub fn qr_decomp(a: &Mat) -> Result<(Mat, Mat), String> {
|
||||
let (m, n) = dense::shape(a)?;
|
||||
let mut v = a.clone();
|
||||
let mut q = dense::zeros(m, n);
|
||||
let mut r = dense::zeros(n, n);
|
||||
for j in 0..n {
|
||||
// orthogonalize against previous
|
||||
for i in 0..j {
|
||||
let mut dot = 0.0;
|
||||
for k in 0..m {
|
||||
dot += q[k][i] * v[k][j];
|
||||
}
|
||||
r[i][j] = dot;
|
||||
for k in 0..m {
|
||||
v[k][j] -= dot * q[k][i];
|
||||
}
|
||||
}
|
||||
let mut norm = 0.0;
|
||||
for k in 0..m {
|
||||
norm += v[k][j] * v[k][j];
|
||||
}
|
||||
norm = norm.sqrt();
|
||||
if norm < 1e-15 {
|
||||
return Err("QR failed: linearly dependent columns".into());
|
||||
}
|
||||
r[j][j] = norm;
|
||||
for k in 0..m {
|
||||
q[k][j] = v[k][j] / norm;
|
||||
}
|
||||
}
|
||||
Ok((q, r))
|
||||
}
|
||||
|
||||
/// Jacobi eigenvalue for symmetric (or symmetrized) real matrix.
|
||||
/// Returns eigenvalues (descending) and eigenvector matrix (columns).
|
||||
pub fn jacobi_symm(a: &Mat) -> Result<(Vec<f64>, Mat), String> {
|
||||
let (n, _) = dense::shape(a)?;
|
||||
// Symmetrize
|
||||
let mut s = dense::zeros(n, n);
|
||||
for i in 0..n {
|
||||
for j in 0..n {
|
||||
s[i][j] = 0.5 * (a[i][j] + a[j][i]);
|
||||
}
|
||||
}
|
||||
let mut v = dense::eye(n);
|
||||
for _ in 0..(n * n * 40).max(40) {
|
||||
// Find largest off-diagonal
|
||||
let mut p = 0usize;
|
||||
let mut q = 1usize;
|
||||
let mut best = 0.0;
|
||||
for i in 0..n {
|
||||
for j in (i + 1)..n {
|
||||
let v = s[i][j].abs();
|
||||
if v > best {
|
||||
best = v;
|
||||
p = i;
|
||||
q = j;
|
||||
}
|
||||
}
|
||||
}
|
||||
if best < 1e-12 {
|
||||
break;
|
||||
}
|
||||
let app = s[p][p];
|
||||
let aqq = s[q][q];
|
||||
let apq = s[p][q];
|
||||
let tau = (aqq - app) / (2.0 * apq);
|
||||
let t = if tau >= 0.0 {
|
||||
1.0 / (tau + (1.0 + tau * tau).sqrt())
|
||||
} else {
|
||||
-1.0 / (-tau + (1.0 + tau * tau).sqrt())
|
||||
};
|
||||
let c = 1.0 / (1.0 + t * t).sqrt();
|
||||
let sn = t * c;
|
||||
// Rotate S
|
||||
s[p][p] = app - t * apq;
|
||||
s[q][q] = aqq + t * apq;
|
||||
s[p][q] = 0.0;
|
||||
s[q][p] = 0.0;
|
||||
for i in 0..n {
|
||||
if i == p || i == q {
|
||||
continue;
|
||||
}
|
||||
let sip = s[i][p];
|
||||
let siq = s[i][q];
|
||||
s[i][p] = c * sip - sn * siq;
|
||||
s[p][i] = s[i][p];
|
||||
s[i][q] = c * siq + sn * sip;
|
||||
s[q][i] = s[i][q];
|
||||
}
|
||||
// Accumulate V
|
||||
for i in 0..n {
|
||||
let vip = v[i][p];
|
||||
let viq = v[i][q];
|
||||
v[i][p] = c * vip - sn * viq;
|
||||
v[i][q] = c * viq + sn * vip;
|
||||
}
|
||||
}
|
||||
let mut pairs: Vec<(f64, usize)> = (0..n).map(|i| (s[i][i], i)).collect();
|
||||
pairs.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
|
||||
let mut evals = Vec::with_capacity(n);
|
||||
let mut evecs = dense::zeros(n, n);
|
||||
for (col, &(ev, idx)) in pairs.iter().enumerate() {
|
||||
evals.push(ev);
|
||||
for row in 0..n {
|
||||
evecs[row][col] = v[row][idx];
|
||||
}
|
||||
}
|
||||
Ok((evals, evecs))
|
||||
}
|
||||
|
||||
/// Economy SVD via eig of AᵀA (n small).
|
||||
pub fn svd_decomp(a: &Mat) -> Result<(Mat, Vec<f64>, Mat), String> {
|
||||
let (m, n) = dense::shape(a)?;
|
||||
// Gram = Aᵀ A (n×n)
|
||||
let at = dense::transpose(a);
|
||||
let gram = dense::matmul(&at, a)?;
|
||||
let (evals, v) = jacobi_symm(&gram)?;
|
||||
let mut svals = Vec::with_capacity(n.min(m));
|
||||
let rank = n.min(m);
|
||||
for i in 0..rank {
|
||||
let s = if evals[i] > 0.0 { evals[i].sqrt() } else { 0.0 };
|
||||
svals.push(s);
|
||||
}
|
||||
// Vt = Vᵀ
|
||||
let vt = dense::transpose(&v);
|
||||
// U = A V S^{+}
|
||||
let mut u = dense::zeros(m, rank);
|
||||
for j in 0..rank {
|
||||
if svals[j] < 1e-15 {
|
||||
continue;
|
||||
}
|
||||
// u_j = A v_j / s_j
|
||||
for i in 0..m {
|
||||
let mut sum = 0.0;
|
||||
for k in 0..n {
|
||||
sum += a[i][k] * v[k][j];
|
||||
}
|
||||
u[i][j] = sum / svals[j];
|
||||
}
|
||||
}
|
||||
// Truncate Vt to rank rows
|
||||
let mut vt_r = dense::zeros(rank, n);
|
||||
for i in 0..rank {
|
||||
for j in 0..n {
|
||||
vt_r[i][j] = vt[i][j];
|
||||
}
|
||||
}
|
||||
let _ = MAX_ELEMENTS;
|
||||
Ok((u, svals, vt_r))
|
||||
}
|
||||
|
||||
pub fn cholesky(a: &Mat) -> Result<Mat, String> {
|
||||
let (n, _) = dense::shape(a)?;
|
||||
let mut l = dense::zeros(n, n);
|
||||
for i in 0..n {
|
||||
for j in 0..=i {
|
||||
let mut sum = 0.0;
|
||||
for k in 0..j {
|
||||
sum += l[i][k] * l[j][k];
|
||||
}
|
||||
if i == j {
|
||||
let v = a[i][i] - sum;
|
||||
if v <= 1e-15 {
|
||||
return Err("Cholesky failed: matrix not positive definite".into());
|
||||
}
|
||||
l[i][j] = v.sqrt();
|
||||
} else {
|
||||
if l[j][j].abs() < 1e-15 {
|
||||
return Err("Cholesky failed: zero pivot".into());
|
||||
}
|
||||
l[i][j] = (a[i][j] - sum) / l[j][j];
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(l)
|
||||
}
|
||||
|
||||
/// Forward/back-sub with LU from `factorize kind=lu` (pivots applied to rhs).
|
||||
pub fn solve_lu_factor(factor: &Value, b: &Mat) -> Result<Mat, String> {
|
||||
if factor.get("kind").and_then(|k| k.as_str()) != Some("lu") {
|
||||
return Err("solve(factor=…) needs kind=lu factor".into());
|
||||
}
|
||||
let l = dense::from_value(factor.get("L").ok_or_else(|| "factor missing L".to_string())?)?;
|
||||
let u = dense::from_value(factor.get("U").ok_or_else(|| "factor missing U".to_string())?)?;
|
||||
let piv = factor
|
||||
.get("pivots")
|
||||
.and_then(|p| p.as_array())
|
||||
.ok_or_else(|| "factor missing pivots".to_string())?;
|
||||
let (n, _) = dense::shape(&l)?;
|
||||
let (br, bc) = dense::shape(b)?;
|
||||
if br != n {
|
||||
return Err(format!("rhs rows {br} != factor size {n}"));
|
||||
}
|
||||
let mut pb = dense::zeros(n, bc);
|
||||
for (i, p) in piv.iter().enumerate() {
|
||||
let src = p
|
||||
.as_u64()
|
||||
.or_else(|| p.as_i64().map(|x| x as u64))
|
||||
.ok_or_else(|| "bad pivot".to_string())? as usize;
|
||||
if src >= n {
|
||||
return Err("pivot out of range".into());
|
||||
}
|
||||
for j in 0..bc {
|
||||
pb[i][j] = b[src][j];
|
||||
}
|
||||
}
|
||||
// Ly = Pb
|
||||
let mut y = dense::zeros(n, bc);
|
||||
for i in 0..n {
|
||||
for j in 0..bc {
|
||||
let mut s = pb[i][j];
|
||||
for k in 0..i {
|
||||
s -= l[i][k] * y[k][j];
|
||||
}
|
||||
y[i][j] = s / l[i][i];
|
||||
}
|
||||
}
|
||||
// Ux = y
|
||||
let mut x = dense::zeros(n, bc);
|
||||
for i in (0..n).rev() {
|
||||
for j in 0..bc {
|
||||
let mut s = y[i][j];
|
||||
for k in (i + 1)..n {
|
||||
s -= u[i][k] * x[k][j];
|
||||
}
|
||||
if u[i][i].abs() < 1e-15 {
|
||||
return Err("singular U in LU solve".into());
|
||||
}
|
||||
x[i][j] = s / u[i][i];
|
||||
}
|
||||
}
|
||||
Ok(x)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn eig_diag() {
|
||||
let m = vec![vec![2.0, 0.0], vec![0.0, 3.0]];
|
||||
let (ev, _) = jacobi_symm(&m).unwrap();
|
||||
assert!((ev[0] - 3.0).abs() < 1e-9);
|
||||
assert!((ev[1] - 2.0).abs() < 1e-9);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn qr_roundtrip() {
|
||||
let a = vec![vec![1.0, 1.0], vec![0.0, 1.0], vec![1.0, 0.0]];
|
||||
let (q, r) = qr_decomp(&a).unwrap();
|
||||
let recon = dense::matmul(&q, &r).unwrap();
|
||||
for i in 0..3 {
|
||||
for j in 0..2 {
|
||||
assert!((recon[i][j] - a[i][j]).abs() < 1e-9);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lu_roundtrip_no_pivot_needed() {
|
||||
let a = vec![vec![2.0, 1.0], vec![1.0, 3.0]];
|
||||
let (l, u, _) = lu_decomp(&a).unwrap();
|
||||
let recon = dense::matmul(&l, &u).unwrap();
|
||||
for i in 0..2 {
|
||||
for j in 0..2 {
|
||||
assert!((recon[i][j] - a[i][j]).abs() < 1e-9);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lu_solve_reuse() {
|
||||
let a = vec![vec![2.0, 1.0], vec![1.0, 3.0]];
|
||||
let b = vec![vec![5.0], vec![5.0]];
|
||||
let f = factorize(&a, "lu").unwrap();
|
||||
let x = solve_lu_factor(&f, &b).unwrap();
|
||||
assert!((x[0][0] - 2.0).abs() < 1e-9);
|
||||
assert!((x[1][0] - 1.0).abs() < 1e-9);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,688 @@
|
||||
//! Marqdo linalg plugin (C ABI v2): formula-first matrix expressions.
|
||||
|
||||
mod complex;
|
||||
mod dense;
|
||||
mod draw;
|
||||
mod factor;
|
||||
mod matexpr;
|
||||
mod metrics;
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ptr;
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
use matexpr::{Dim, Expr};
|
||||
|
||||
const ABI_VERSION: u32 = 2;
|
||||
|
||||
type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
type HostQueryFn = unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
pub host_query: Option<HostQueryFn>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
static mut HOST_QUERY: Option<HostQueryFn> = None;
|
||||
static mut HOST_USERDATA: *mut c_void = ptr::null_mut();
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_args(args_json: *const c_char) -> Result<Value, String> {
|
||||
if args_json.is_null() {
|
||||
return Ok(json!({}));
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(args_json) }
|
||||
.to_str()
|
||||
.map_err(|_| "args not utf-8".to_string())?;
|
||||
if s.trim().is_empty() {
|
||||
return Ok(json!({}));
|
||||
}
|
||||
serde_json::from_str(s).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
fn reply(out_json: *mut *mut c_char, err_msg: *mut *mut c_char, r: Result<Value, String>) -> c_int {
|
||||
match r {
|
||||
Ok(v) => {
|
||||
set_out(out_json, &v.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &e);
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
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 take_host_string(p: *mut c_char) -> Option<String> {
|
||||
if p.is_null() {
|
||||
return None;
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(p) }
|
||||
.to_str()
|
||||
.ok()
|
||||
.map(|s| s.to_string());
|
||||
unsafe {
|
||||
if let Some(free) = HOST_FREE {
|
||||
free(p as *mut c_void);
|
||||
}
|
||||
}
|
||||
s
|
||||
}
|
||||
|
||||
fn host_query_json(name: &str, args: &Value) -> Result<Value, String> {
|
||||
let query = unsafe { HOST_QUERY }.ok_or_else(|| "host_query not available".to_string())?;
|
||||
let userdata = unsafe { HOST_USERDATA };
|
||||
let c_name = CString::new(name).map_err(|e| e.to_string())?;
|
||||
let c_args = CString::new(args.to_string()).map_err(|e| e.to_string())?;
|
||||
let mut out_ptr: *mut c_char = ptr::null_mut();
|
||||
let mut err_ptr: *mut c_char = ptr::null_mut();
|
||||
let rc = unsafe {
|
||||
query(
|
||||
userdata,
|
||||
c_name.as_ptr(),
|
||||
c_args.as_ptr(),
|
||||
&mut out_ptr,
|
||||
&mut err_ptr,
|
||||
)
|
||||
};
|
||||
let err = take_host_string(err_ptr);
|
||||
let out = take_host_string(out_ptr);
|
||||
if rc != 0 {
|
||||
return Err(err.unwrap_or_else(|| format!("host_query `{name}` failed")));
|
||||
}
|
||||
let out = out.unwrap_or_else(|| "null".into());
|
||||
serde_json::from_str(&out).map_err(|e| format!("host_query `{name}` bad JSON: {e}"))
|
||||
}
|
||||
|
||||
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("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('&', "&")
|
||||
.replace('<', "<")
|
||||
.replace('>', ">");
|
||||
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))
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
ABI_VERSION
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
HOST_QUERY = host.host_query;
|
||||
HOST_USERDATA = host.userdata;
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let regs = [
|
||||
("linalg_ping", "", linalg_ping as PluginFn),
|
||||
("linalg_symbol", "name,rows,cols", linalg_symbol as PluginFn),
|
||||
("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,type_tag", 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),
|
||||
("linalg_sub", "a,b", linalg_sub as PluginFn),
|
||||
("linalg_transpose", "expr", linalg_transpose as PluginFn),
|
||||
("linalg_inv", "expr", linalg_inv as PluginFn),
|
||||
("linalg_simplify", "expr", linalg_simplify as PluginFn),
|
||||
("linalg_ascii", "expr,raw", linalg_ascii as PluginFn),
|
||||
("linalg_latex", "expr,raw", linalg_latex as PluginFn),
|
||||
("linalg_shape", "expr", linalg_shape as PluginFn),
|
||||
("linalg_show", "expr,path,raw", linalg_show as PluginFn),
|
||||
("linalg_explicit", "expr,raw", linalg_explicit as PluginFn),
|
||||
("linalg_det", "expr", linalg_det as PluginFn),
|
||||
("linalg_trace", "expr", linalg_trace as PluginFn),
|
||||
("linalg_solve", "a,b,factor", linalg_solve as PluginFn),
|
||||
("linalg_matmul", "a,b", linalg_matmul as PluginFn),
|
||||
("linalg_kron", "a,b", linalg_kron as PluginFn),
|
||||
("linalg_block", "blocks", linalg_block as PluginFn),
|
||||
("linalg_collapse", "expr", linalg_collapse as PluginFn),
|
||||
("linalg_factorize", "matrix,kind", linalg_factorize as PluginFn),
|
||||
("linalg_draw", "factor,kind,path,theme", linalg_draw as PluginFn),
|
||||
("linalg_lstsq", "a,b", linalg_lstsq as PluginFn),
|
||||
("linalg_norm", "expr,ord", linalg_norm as PluginFn),
|
||||
("linalg_cond", "expr", linalg_cond as PluginFn),
|
||||
("linalg_rank", "expr", linalg_rank as PluginFn),
|
||||
];
|
||||
for (name, params, f) in regs {
|
||||
let c_name = CString::new(name).unwrap();
|
||||
let c_params = CString::new(params).unwrap();
|
||||
if register(host.userdata, c_name.as_ptr(), c_params.as_ptr(), f) != 0 {
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
0
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,194 @@
|
||||
//! Real dense metrics: lstsq, norm, cond, rank (L6).
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
use crate::dense::{self, Mat};
|
||||
use crate::factor;
|
||||
|
||||
/// Least squares `min ||A x - b||_2`. Tall: thin QR; wide/square: SVD pseudoinverse.
|
||||
pub fn lstsq(a: &Mat, b: &Mat) -> Result<Value, String> {
|
||||
let (m, n) = dense::shape(a)?;
|
||||
let (br, bc) = dense::shape(b)?;
|
||||
if br != m {
|
||||
return Err(format!("lstsq: A is {m}×{n} but b has {br} rows"));
|
||||
}
|
||||
factor::check_side_limit(m.max(n), "lstsq")?;
|
||||
let (x, residual_fro, method) = if m >= n {
|
||||
lstsq_qr(a, b)?
|
||||
} else {
|
||||
lstsq_svd(a, b)?
|
||||
};
|
||||
let residual_fro = if bc == 1 {
|
||||
residual_fro
|
||||
} else {
|
||||
// recompute full residual for multi-RHS
|
||||
let ax = dense::matmul(a, &x)?;
|
||||
frobenius_diff(&ax, b)
|
||||
};
|
||||
Ok(json!({
|
||||
"_type": "linalg_lstsq",
|
||||
"method": method,
|
||||
"x": dense::to_dense_value(&x)?,
|
||||
"residual_fro": residual_fro,
|
||||
}))
|
||||
}
|
||||
|
||||
fn lstsq_qr(a: &Mat, b: &Mat) -> Result<(Mat, f64, &'static str), String> {
|
||||
let (q, r) = factor::qr_decomp(a)?;
|
||||
let qt = dense::transpose(&q);
|
||||
let qtb = dense::matmul(&qt, b)?;
|
||||
let x = dense::solve(&r, &qtb)?;
|
||||
let ax = dense::matmul(a, &x)?;
|
||||
Ok((x, frobenius_diff(&ax, b), "qr"))
|
||||
}
|
||||
|
||||
fn lstsq_svd(a: &Mat, b: &Mat) -> Result<(Mat, f64, &'static str), String> {
|
||||
let (m, n) = dense::shape(a)?;
|
||||
let (_, bc) = dense::shape(b)?;
|
||||
let (u, s, vt) = factor::svd_decomp(a)?;
|
||||
let rank = n.min(m);
|
||||
let mut s_inv = vec![0.0; rank];
|
||||
let smax = s.first().copied().unwrap_or(0.0);
|
||||
let tol = smax * (m.max(n) as f64) * f64::EPSILON * 100.0;
|
||||
for i in 0..rank {
|
||||
if s[i] > tol {
|
||||
s_inv[i] = 1.0 / s[i];
|
||||
}
|
||||
}
|
||||
// x = V Σ⁺ Uᵀ b ; U is m×rank, Vt is rank×n
|
||||
let ut = dense::transpose(&u);
|
||||
let utb = dense::matmul(&ut, b)?; // rank×bc
|
||||
let mut mid = dense::zeros(rank, bc);
|
||||
for i in 0..rank {
|
||||
for j in 0..bc {
|
||||
mid[i][j] = s_inv[i] * utb[i][j];
|
||||
}
|
||||
}
|
||||
let v = dense::transpose(&vt); // n×rank
|
||||
let x = dense::matmul(&v, &mid)?;
|
||||
let ax = dense::matmul(a, &x)?;
|
||||
Ok((x, frobenius_diff(&ax, b), "svd"))
|
||||
}
|
||||
|
||||
fn frobenius_diff(a: &Mat, b: &Mat) -> f64 {
|
||||
let mut s = 0.0;
|
||||
for (ra, rb) in a.iter().zip(b.iter()) {
|
||||
for (&x, &y) in ra.iter().zip(rb.iter()) {
|
||||
let d = x - y;
|
||||
s += d * d;
|
||||
}
|
||||
}
|
||||
s.sqrt()
|
||||
}
|
||||
|
||||
/// Matrix norm: `fro` (default), `1`, `inf`, `2`.
|
||||
pub fn norm(m: &Mat, ord: &str) -> Result<f64, String> {
|
||||
let (rows, cols) = dense::shape(m)?;
|
||||
match ord.trim().to_ascii_lowercase().as_str() {
|
||||
"fro" | "frobenius" | "f" | "" => {
|
||||
let mut s = 0.0;
|
||||
for row in m {
|
||||
for &v in row {
|
||||
s += v * v;
|
||||
}
|
||||
}
|
||||
Ok(s.sqrt())
|
||||
}
|
||||
"1" | "one" => {
|
||||
let mut best: f64 = 0.0;
|
||||
for j in 0..cols {
|
||||
let mut col = 0.0;
|
||||
for i in 0..rows {
|
||||
col += m[i][j].abs();
|
||||
}
|
||||
best = best.max(col);
|
||||
}
|
||||
Ok(best)
|
||||
}
|
||||
"inf" | "infty" | "∞" => {
|
||||
let mut best: f64 = 0.0;
|
||||
for row in m {
|
||||
let mut r = 0.0;
|
||||
for &v in row {
|
||||
r += v.abs();
|
||||
}
|
||||
best = best.max(r);
|
||||
}
|
||||
Ok(best)
|
||||
}
|
||||
"2" | "spectral" => {
|
||||
let (_, s, _) = factor::svd_decomp(m)?;
|
||||
Ok(s.first().copied().unwrap_or(0.0))
|
||||
}
|
||||
other => Err(format!(
|
||||
"unknown norm `{other}` (want fro|1|inf|2)"
|
||||
)),
|
||||
}
|
||||
}
|
||||
|
||||
/// 2-norm condition number σ_max / σ_min (∞ if rank-deficient).
|
||||
pub fn cond(m: &Mat) -> Result<Value, String> {
|
||||
let (rows, cols) = dense::shape(m)?;
|
||||
let (_, s, _) = factor::svd_decomp(m)?;
|
||||
let smax = s.first().copied().unwrap_or(0.0);
|
||||
let smin = s
|
||||
.iter()
|
||||
.copied()
|
||||
.filter(|&x| x > 0.0)
|
||||
.last()
|
||||
.unwrap_or(0.0);
|
||||
let tol = smax * (rows.max(cols) as f64) * f64::EPSILON * 100.0;
|
||||
let (value, infinite) = if smin <= tol {
|
||||
(f64::INFINITY, true)
|
||||
} else {
|
||||
(smax / smin, false)
|
||||
};
|
||||
Ok(json!({
|
||||
"_type": "linalg_cond",
|
||||
"ord": 2,
|
||||
"value": if infinite { Value::Null } else { json!(value) },
|
||||
"infinite": infinite,
|
||||
"sigma_max": smax,
|
||||
"sigma_min": smin,
|
||||
}))
|
||||
}
|
||||
|
||||
/// Numerical rank via SVD.
|
||||
pub fn rank(m: &Mat) -> Result<usize, String> {
|
||||
let (rows, cols) = dense::shape(m)?;
|
||||
let (_, s, _) = factor::svd_decomp(m)?;
|
||||
let smax = s.first().copied().unwrap_or(0.0);
|
||||
let tol = smax * (rows.max(cols) as f64) * f64::EPSILON * 100.0;
|
||||
Ok(s.iter().filter(|&&x| x > tol).count())
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn lstsq_line_fit() {
|
||||
// points (0,1), (1,2), (2,2) → line ≈ 1.1667 + 0.5 t
|
||||
let a = vec![vec![1.0, 0.0], vec![1.0, 1.0], vec![1.0, 2.0]];
|
||||
let b = vec![vec![1.0], vec![2.0], vec![2.0]];
|
||||
let out = lstsq(&a, &b).unwrap();
|
||||
let x = dense::from_value(out.get("x").unwrap()).unwrap();
|
||||
assert!((x[0][0] - 7.0 / 6.0).abs() < 1e-9);
|
||||
assert!((x[1][0] - 0.5).abs() < 1e-9);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn fro_identity() {
|
||||
let i = dense::eye(3);
|
||||
assert!((norm(&i, "fro").unwrap() - 3f64.sqrt()).abs() < 1e-12);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn cond_diag() {
|
||||
let m = vec![vec![2.0, 0.0], vec![0.0, 1.0]];
|
||||
let c = cond(&m).unwrap();
|
||||
assert_eq!(c["infinite"], false);
|
||||
assert!((c["value"].as_f64().unwrap() - 2.0).abs() < 1e-9);
|
||||
assert_eq!(rank(&m).unwrap(), 2);
|
||||
}
|
||||
}
|
||||
@@ -25,6 +25,8 @@ pulldown-cmark = "0.12"
|
||||
postgres = { version = "0.19", features = ["with-serde_json-1"] }
|
||||
redis = { version = "0.27", default-features = true }
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls"] }
|
||||
reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "stream", "json"] }
|
||||
bytes = "1"
|
||||
hmac = "0.12"
|
||||
sha2 = "0.10"
|
||||
hex = "0.4"
|
||||
@@ -281,6 +281,8 @@ pub fn listen(
|
||||
middleware: &Middleware,
|
||||
mut site_head: Vec<crate::assets::HeadLink>,
|
||||
mut icon_routes: Vec<crate::assets::IconRoute>,
|
||||
proxy_routes: Vec<(String, crate::proxy::ProxyRoute)>,
|
||||
invoke_routes: Vec<(String, crate::invoke::InvokeRoute)>,
|
||||
) -> Result<Value, String> {
|
||||
let mut form_owners = HashMap::new();
|
||||
collect_page_forms(page, &mut forms, &mut form_owners);
|
||||
@@ -601,6 +603,10 @@ pub fn listen(
|
||||
);
|
||||
}
|
||||
|
||||
// Streaming proxy + HTTP→## invoke (before fallback so paths are explicit).
|
||||
app = crate::proxy::mount_all(app, &proxy_routes);
|
||||
app = crate::invoke::mount_all(app, &invoke_routes);
|
||||
|
||||
app = app.fallback(get(fallback_404));
|
||||
|
||||
let app = crate::middleware::apply(app, middleware);
|
||||
|
||||
@@ -0,0 +1,332 @@
|
||||
//! HTTP → user `##` invoke routes for `app.invoke` / `configure invoke=`.
|
||||
|
||||
use std::sync::Arc;
|
||||
|
||||
use axum::extract::{Request, State};
|
||||
use axum::http::{header, HeaderValue, StatusCode};
|
||||
use axum::response::{IntoResponse, Response};
|
||||
use axum::routing::{get, post};
|
||||
use axum::Router;
|
||||
use serde_json::{json, Map, Value};
|
||||
|
||||
use crate::middleware::{cell_text, JsonBody};
|
||||
use crate::table;
|
||||
use crate::call_lib_with_args;
|
||||
|
||||
/// One declared invoke mount.
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct InvokeRoute {
|
||||
pub method: String,
|
||||
pub fn_path: String,
|
||||
pub body_mode: String,
|
||||
pub return_mode: String,
|
||||
}
|
||||
|
||||
impl InvokeRoute {
|
||||
pub fn from_json(v: &Value) -> Option<Self> {
|
||||
let obj = v.as_object()?;
|
||||
let fn_path = obj
|
||||
.get("fn")
|
||||
.or_else(|| obj.get("function"))
|
||||
.and_then(|x| x.as_str())?
|
||||
.trim()
|
||||
.to_string();
|
||||
if fn_path.is_empty() {
|
||||
return None;
|
||||
}
|
||||
let method = obj
|
||||
.get("method")
|
||||
.and_then(|x| x.as_str())
|
||||
.unwrap_or("POST")
|
||||
.to_uppercase();
|
||||
let body_mode = obj
|
||||
.get("body")
|
||||
.and_then(|x| x.as_str())
|
||||
.unwrap_or("json")
|
||||
.to_ascii_lowercase();
|
||||
let return_mode = obj
|
||||
.get("return")
|
||||
.and_then(|x| x.as_str())
|
||||
.unwrap_or("json")
|
||||
.to_ascii_lowercase();
|
||||
Some(Self {
|
||||
method,
|
||||
fn_path,
|
||||
body_mode,
|
||||
return_mode,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
/// Normalize invoke-routes GFM table into `app.invoke_routes` map.
|
||||
pub fn invoke_routes_from_table(table_v: &Value) -> Value {
|
||||
let rows = table::as_rows(table_v);
|
||||
let mut routes = Map::new();
|
||||
if let Some(arr) = rows.as_array() {
|
||||
for row in arr {
|
||||
let col = |keys: &[&str]| -> String {
|
||||
keys.iter()
|
||||
.find_map(|k| row.get(*k).map(cell_text))
|
||||
.unwrap_or_default()
|
||||
};
|
||||
let path = col(&["路径", "path", "Path"])
|
||||
.trim()
|
||||
.trim_start_matches('/')
|
||||
.to_string();
|
||||
if path.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let fn_path = col(&["函数", "fn", "function", "Function"]);
|
||||
if fn_path.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let method = {
|
||||
let m = col(&["方法", "method", "Method"]).to_uppercase();
|
||||
if m.is_empty() {
|
||||
"POST".into()
|
||||
} else {
|
||||
m
|
||||
}
|
||||
};
|
||||
let body = {
|
||||
let b = col(&["正文", "body", "Body"]).to_ascii_lowercase();
|
||||
if b.is_empty() {
|
||||
"json".into()
|
||||
} else {
|
||||
b
|
||||
}
|
||||
};
|
||||
let ret = {
|
||||
let r = col(&["返回", "return", "Return"]).to_ascii_lowercase();
|
||||
if r.is_empty() {
|
||||
"json".into()
|
||||
} else {
|
||||
r
|
||||
}
|
||||
};
|
||||
routes.insert(
|
||||
path,
|
||||
json!({
|
||||
"method": method,
|
||||
"fn": fn_path,
|
||||
"body": body,
|
||||
"return": ret,
|
||||
}),
|
||||
);
|
||||
}
|
||||
}
|
||||
Value::Object(routes)
|
||||
}
|
||||
|
||||
pub fn mount_all(
|
||||
mut app: Router<Arc<crate::http::AppState>>,
|
||||
routes: &[(String, InvokeRoute)],
|
||||
) -> Router<Arc<crate::http::AppState>> {
|
||||
for (path, route) in routes {
|
||||
app = mount_one(app, path, route.clone());
|
||||
}
|
||||
app
|
||||
}
|
||||
|
||||
fn mount_one(
|
||||
app: Router<Arc<crate::http::AppState>>,
|
||||
path: &str,
|
||||
route: InvokeRoute,
|
||||
) -> Router<Arc<crate::http::AppState>> {
|
||||
let r = route.clone();
|
||||
match route.method.as_str() {
|
||||
"GET" => app.route(
|
||||
path,
|
||||
get(move |State(st): State<Arc<crate::http::AppState>>, req: Request| {
|
||||
let r = r.clone();
|
||||
async move { invoke_handler(st, r, req).await }
|
||||
}),
|
||||
),
|
||||
_ => app.route(
|
||||
path,
|
||||
post(move |State(st): State<Arc<crate::http::AppState>>, req: Request| {
|
||||
let r = r.clone();
|
||||
async move { invoke_handler(st, r, req).await }
|
||||
}),
|
||||
),
|
||||
}
|
||||
}
|
||||
|
||||
async fn invoke_handler(
|
||||
_st: Arc<crate::http::AppState>,
|
||||
route: InvokeRoute,
|
||||
req: Request,
|
||||
) -> Response {
|
||||
let (parts, body) = req.into_parts();
|
||||
let query_map = query_to_map(parts.uri.query());
|
||||
|
||||
let payload = match route.body_mode.as_str() {
|
||||
"query" => Value::Object(query_map.clone()),
|
||||
"raw" => {
|
||||
let bytes = match axum::body::to_bytes(body, 8 * 1024 * 1024).await {
|
||||
Ok(b) => b,
|
||||
Err(e) => {
|
||||
return err_json(StatusCode::BAD_REQUEST, &format!("body: {e}"));
|
||||
}
|
||||
};
|
||||
json!({ "payload": String::from_utf8_lossy(&bytes).to_string() })
|
||||
}
|
||||
"form" => {
|
||||
let bytes = match axum::body::to_bytes(body, 8 * 1024 * 1024).await {
|
||||
Ok(b) => b,
|
||||
Err(e) => {
|
||||
return err_json(StatusCode::BAD_REQUEST, &format!("body: {e}"));
|
||||
}
|
||||
};
|
||||
form_to_map(&bytes)
|
||||
}
|
||||
_ => {
|
||||
// json (default)
|
||||
let bytes = match axum::body::to_bytes(body, 8 * 1024 * 1024).await {
|
||||
Ok(b) => b,
|
||||
Err(e) => {
|
||||
return err_json(StatusCode::BAD_REQUEST, &format!("body: {e}"));
|
||||
}
|
||||
};
|
||||
if bytes.is_empty() {
|
||||
Value::Object(query_map.clone())
|
||||
} else {
|
||||
match serde_json::from_slice::<Value>(&bytes) {
|
||||
Ok(Value::Object(mut m)) => {
|
||||
for (k, v) in query_map {
|
||||
m.entry(k).or_insert(v);
|
||||
}
|
||||
Value::Object(m)
|
||||
}
|
||||
Ok(other) => json!({ "payload": other }),
|
||||
Err(e) => {
|
||||
return err_json(StatusCode::BAD_REQUEST, &format!("json: {e}"));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// Bind JSON object keys as named args; always offer `payload` too.
|
||||
let mut args = Map::new();
|
||||
if let Value::Object(ref m) = payload {
|
||||
for (k, v) in m {
|
||||
args.insert(k.clone(), v.clone());
|
||||
}
|
||||
}
|
||||
if !args.contains_key("payload") {
|
||||
args.insert("payload".to_string(), payload.clone());
|
||||
}
|
||||
|
||||
let fn_path = route.fn_path.clone();
|
||||
let result = tokio::task::spawn_blocking(move || call_lib_with_args(&fn_path, &Value::Object(args)))
|
||||
.await;
|
||||
|
||||
let value = match result {
|
||||
Ok(Ok(v)) => v,
|
||||
Ok(Err(e)) => {
|
||||
let status = if e.contains("unknown library")
|
||||
|| e.contains("call_lib_path: need")
|
||||
|| e.contains("not allowed")
|
||||
|| e.contains("no site")
|
||||
{
|
||||
StatusCode::BAD_REQUEST
|
||||
} else {
|
||||
StatusCode::INTERNAL_SERVER_ERROR
|
||||
};
|
||||
return err_json(status, &e);
|
||||
}
|
||||
Err(e) => {
|
||||
return err_json(StatusCode::INTERNAL_SERVER_ERROR, &format!("join: {e}"));
|
||||
}
|
||||
};
|
||||
|
||||
match route.return_mode.as_str() {
|
||||
"text" => {
|
||||
let text = match &value {
|
||||
Value::String(s) => s.clone(),
|
||||
other => other.to_string(),
|
||||
};
|
||||
(
|
||||
StatusCode::OK,
|
||||
[(
|
||||
header::CONTENT_TYPE,
|
||||
HeaderValue::from_static("text/plain; charset=utf-8"),
|
||||
)],
|
||||
text,
|
||||
)
|
||||
.into_response()
|
||||
}
|
||||
"status" => StatusCode::NO_CONTENT.into_response(),
|
||||
_ => {
|
||||
// Wrap non-objects so clients always get JSON object when possible.
|
||||
let body = match value {
|
||||
Value::Null => json!({ "ok": true }),
|
||||
Value::Object(_) => value,
|
||||
other => json!({ "ok": true, "result": other }),
|
||||
};
|
||||
JsonBody(body).into_response()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn query_to_map(q: Option<&str>) -> Map<String, Value> {
|
||||
let mut m = Map::new();
|
||||
let Some(q) = q else {
|
||||
return m;
|
||||
};
|
||||
for pair in q.split('&') {
|
||||
if pair.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let (k, v) = pair.split_once('=').unwrap_or((pair, ""));
|
||||
let k = urlencoding_decode(k);
|
||||
let v = urlencoding_decode(v);
|
||||
if !k.is_empty() {
|
||||
m.insert(k, json!(v));
|
||||
}
|
||||
}
|
||||
m
|
||||
}
|
||||
|
||||
fn form_to_map(bytes: &[u8]) -> Value {
|
||||
let s = String::from_utf8_lossy(bytes);
|
||||
Value::Object(query_to_map(Some(&s)))
|
||||
}
|
||||
|
||||
fn urlencoding_decode(s: &str) -> String {
|
||||
let mut out = String::with_capacity(s.len());
|
||||
let b = s.as_bytes();
|
||||
let mut i = 0;
|
||||
while i < b.len() {
|
||||
match b[i] {
|
||||
b'+' => {
|
||||
out.push(' ');
|
||||
i += 1;
|
||||
}
|
||||
b'%' if i + 2 < b.len() => {
|
||||
let h = u8::from_str_radix(std::str::from_utf8(&b[i + 1..i + 3]).unwrap_or(""), 16);
|
||||
if let Ok(c) = h {
|
||||
out.push(c as char);
|
||||
i += 3;
|
||||
} else {
|
||||
out.push('%');
|
||||
i += 1;
|
||||
}
|
||||
}
|
||||
c => {
|
||||
out.push(c as char);
|
||||
i += 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn err_json(status: StatusCode, msg: &str) -> Response {
|
||||
(
|
||||
status,
|
||||
JsonBody(json!({ "ok": false, "error": msg })),
|
||||
)
|
||||
.into_response()
|
||||
}
|
||||
+292
-62
@@ -8,9 +8,11 @@ mod driver;
|
||||
mod form;
|
||||
mod http;
|
||||
mod cache;
|
||||
mod invoke;
|
||||
mod markdown;
|
||||
mod middleware;
|
||||
mod password;
|
||||
mod proxy;
|
||||
mod rate_limit;
|
||||
mod render;
|
||||
mod rss;
|
||||
@@ -156,6 +158,17 @@ fn call_lib(path: &str) -> Result<Value, String> {
|
||||
host_query_json("call_lib_path", &json!({ "path": path }))
|
||||
}
|
||||
|
||||
/// Call `lib.member` with a JSON object of named arguments (for HTTP invoke).
|
||||
pub(crate) fn call_lib_with_args(path: &str, args: &Value) -> Result<Value, String> {
|
||||
host_query_json(
|
||||
"call_lib_path",
|
||||
&json!({
|
||||
"path": path,
|
||||
"args": args,
|
||||
}),
|
||||
)
|
||||
}
|
||||
|
||||
/// Absolute directory of the entry `.mq.md` (falls back to process cwd).
|
||||
fn entry_dir() -> PathBuf {
|
||||
host_query_json("entry_dir", &json!({}))
|
||||
@@ -1507,74 +1520,245 @@ web_ffi!(web_app_static, |args: &Value| {
|
||||
// backed by db queries (method GET/POST, `表`=table name).
|
||||
web_ffi!(web_app_middleware, |args: &Value| {
|
||||
let mut app = args.get("app").cloned().unwrap_or(json!({}));
|
||||
{
|
||||
let obj = app
|
||||
.as_object_mut()
|
||||
.ok_or_else(|| "app must be a map".to_string())?;
|
||||
let mw = obj
|
||||
.entry("middleware".to_string())
|
||||
.or_insert_with(|| json!({}));
|
||||
let m = mw
|
||||
.as_object_mut()
|
||||
.ok_or_else(|| "app.middleware must be a map".to_string())?;
|
||||
|
||||
if let Some(cors) = args.get("cors") {
|
||||
m.insert("cors".into(), middleware::cors_from_table(cors));
|
||||
}
|
||||
if let Some(security) = args.get("security") {
|
||||
m.insert(
|
||||
"security".into(),
|
||||
middleware::security_from_table(security),
|
||||
);
|
||||
}
|
||||
if let Some(compress) = args.get("compress") {
|
||||
let on = match compress {
|
||||
Value::Bool(b) => *b,
|
||||
Value::String(s) => matches!(s.as_str(), "true" | "True" | "1" | "yes" | "on"),
|
||||
Value::Number(n) => n.as_i64().unwrap_or(0) != 0,
|
||||
_ => false,
|
||||
};
|
||||
m.insert("compress".into(), json!(on));
|
||||
}
|
||||
if let Some(al) = args.get("access_log").or_else(|| args.get("访问日志")) {
|
||||
let on = match al {
|
||||
Value::Bool(b) => *b,
|
||||
Value::String(s) => {
|
||||
matches!(s.as_str(), "true" | "True" | "1" | "yes" | "on" | "真")
|
||||
}
|
||||
Value::Number(n) => n.as_i64().unwrap_or(0) != 0,
|
||||
_ => false,
|
||||
};
|
||||
m.insert("access_log".into(), json!(on));
|
||||
}
|
||||
if let Some(cc) = args
|
||||
.get("cache_control")
|
||||
.or_else(|| args.get("缓存控制"))
|
||||
.and_then(|v| v.as_str())
|
||||
{
|
||||
let s = cc.trim();
|
||||
if !s.is_empty() {
|
||||
m.insert("cache_control".into(), json!(s));
|
||||
}
|
||||
}
|
||||
if let Some(bl) = args.get("body_limit") {
|
||||
let n = bl
|
||||
.as_u64()
|
||||
.or_else(|| bl.as_i64().map(|i| i as u64))
|
||||
.unwrap_or(0);
|
||||
if n > 0 {
|
||||
m.insert("body_limit".into(), json!(n));
|
||||
}
|
||||
}
|
||||
if let Some(routes) = args.get("json_routes") {
|
||||
m.insert(
|
||||
"json_routes".into(),
|
||||
middleware::json_routes_from_table(routes),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if let Some(proxy) = args
|
||||
.get("proxy")
|
||||
.or_else(|| args.get("proxy_routes"))
|
||||
.or_else(|| args.get("代理"))
|
||||
.filter(|v| !v.is_null())
|
||||
{
|
||||
let incoming = proxy::proxy_routes_from_table(proxy);
|
||||
let obj_app = app
|
||||
.as_object_mut()
|
||||
.ok_or_else(|| "app must be a map".to_string())?;
|
||||
let mut existing = obj_app
|
||||
.get("proxy_routes")
|
||||
.and_then(|v| v.as_object())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
if let Some(map) = incoming.as_object() {
|
||||
for (k, v) in map {
|
||||
existing.insert(k.clone(), v.clone());
|
||||
}
|
||||
}
|
||||
obj_app.insert("proxy_routes".into(), Value::Object(existing));
|
||||
}
|
||||
if let Some(inv) = args
|
||||
.get("invoke")
|
||||
.or_else(|| args.get("invoke_routes"))
|
||||
.or_else(|| args.get("调用"))
|
||||
.filter(|v| !v.is_null())
|
||||
{
|
||||
let incoming = invoke::invoke_routes_from_table(inv);
|
||||
let obj_app = app
|
||||
.as_object_mut()
|
||||
.ok_or_else(|| "app must be a map".to_string())?;
|
||||
let mut existing = obj_app
|
||||
.get("invoke_routes")
|
||||
.and_then(|v| v.as_object())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
if let Some(map) = incoming.as_object() {
|
||||
for (k, v) in map {
|
||||
existing.insert(k.clone(), v.clone());
|
||||
}
|
||||
}
|
||||
obj_app.insert("invoke_routes".into(), Value::Object(existing));
|
||||
}
|
||||
Ok(app)
|
||||
});
|
||||
|
||||
web_ffi!(web_app_proxy, |args: &Value| {
|
||||
let mut app = args.get("app").cloned().unwrap_or(json!({}));
|
||||
let path = normalize_route_path_in_app(
|
||||
arg_str(args, "path").or_else(|_| arg_str(args, "路径"))?,
|
||||
&app,
|
||||
)?;
|
||||
let upstream = arg_str(args, "upstream")
|
||||
.or_else(|_| arg_str(args, "上游"))?
|
||||
.to_string();
|
||||
if upstream.trim().is_empty() {
|
||||
return Err("proxy requires `upstream`".into());
|
||||
}
|
||||
let stream = match args
|
||||
.get("stream")
|
||||
.or_else(|| args.get("流式"))
|
||||
.cloned()
|
||||
.unwrap_or(json!(true))
|
||||
{
|
||||
Value::Bool(b) => b,
|
||||
Value::String(s) => matches!(
|
||||
s.as_str(),
|
||||
"true" | "True" | "1" | "yes" | "on" | "真"
|
||||
),
|
||||
Value::Number(n) => n.as_i64().unwrap_or(0) != 0,
|
||||
_ => true,
|
||||
};
|
||||
let strip_prefix = arg_str_opt(args, "strip_prefix")
|
||||
.or_else(|| arg_str_opt(args, "去前缀"))
|
||||
.unwrap_or("")
|
||||
.to_string();
|
||||
let methods = match args.get("methods").or_else(|| args.get("方法")) {
|
||||
Some(Value::Array(arr)) => arr
|
||||
.iter()
|
||||
.filter_map(|v| v.as_str().map(|s| s.to_uppercase()))
|
||||
.collect::<Vec<_>>(),
|
||||
Some(Value::String(s)) => s
|
||||
.split(',')
|
||||
.map(|m| m.trim().to_uppercase())
|
||||
.filter(|m| !m.is_empty())
|
||||
.collect(),
|
||||
_ => vec!["POST".into()],
|
||||
};
|
||||
let headers_from_env = arg_str_opt(args, "headers_from_env")
|
||||
.or_else(|| arg_str_opt(args, "环境头"))
|
||||
.unwrap_or("")
|
||||
.to_string();
|
||||
let timeout_ms = args
|
||||
.get("timeout_ms")
|
||||
.or_else(|| args.get("超时"))
|
||||
.and_then(|v| v.as_u64().or_else(|| v.as_i64().map(|i| i as u64)))
|
||||
.unwrap_or(120_000);
|
||||
let obj = app
|
||||
.as_object_mut()
|
||||
.ok_or_else(|| "app must be a map".to_string())?;
|
||||
let mw = obj
|
||||
.entry("middleware".to_string())
|
||||
.or_insert_with(|| json!({}));
|
||||
let m = mw
|
||||
.as_object_mut()
|
||||
.ok_or_else(|| "app.middleware must be a map".to_string())?;
|
||||
let mut routes = obj
|
||||
.get("proxy_routes")
|
||||
.and_then(|v| v.as_object())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
let key = path.trim_start_matches('/').to_string();
|
||||
routes.insert(
|
||||
key,
|
||||
json!({
|
||||
"upstream": upstream,
|
||||
"stream": stream,
|
||||
"strip_prefix": strip_prefix,
|
||||
"methods": methods,
|
||||
"headers_from_env": headers_from_env,
|
||||
"timeout_ms": timeout_ms,
|
||||
}),
|
||||
);
|
||||
obj.insert("proxy_routes".into(), Value::Object(routes));
|
||||
Ok(app)
|
||||
});
|
||||
|
||||
if let Some(cors) = args.get("cors") {
|
||||
m.insert(
|
||||
"cors".into(),
|
||||
middleware::cors_from_table(cors),
|
||||
);
|
||||
web_ffi!(web_app_invoke, |args: &Value| {
|
||||
let mut app = args.get("app").cloned().unwrap_or(json!({}));
|
||||
let path = normalize_route_path_in_app(
|
||||
arg_str(args, "path").or_else(|_| arg_str(args, "路径"))?,
|
||||
&app,
|
||||
)?;
|
||||
let fn_path = arg_str(args, "fn")
|
||||
.or_else(|_| arg_str(args, "function"))
|
||||
.or_else(|_| arg_str(args, "函数"))?
|
||||
.to_string();
|
||||
if fn_path.trim().is_empty() {
|
||||
return Err("invoke requires `fn`".into());
|
||||
}
|
||||
if let Some(security) = args.get("security") {
|
||||
m.insert(
|
||||
"security".into(),
|
||||
middleware::security_from_table(security),
|
||||
);
|
||||
}
|
||||
if let Some(compress) = args.get("compress") {
|
||||
let on = match compress {
|
||||
Value::Bool(b) => *b,
|
||||
Value::String(s) => matches!(s.as_str(), "true" | "True" | "1" | "yes" | "on"),
|
||||
Value::Number(n) => n.as_i64().unwrap_or(0) != 0,
|
||||
_ => false,
|
||||
};
|
||||
m.insert("compress".into(), json!(on));
|
||||
}
|
||||
if let Some(al) = args
|
||||
.get("access_log")
|
||||
.or_else(|| args.get("访问日志"))
|
||||
{
|
||||
let on = match al {
|
||||
Value::Bool(b) => *b,
|
||||
Value::String(s) => matches!(s.as_str(), "true" | "True" | "1" | "yes" | "on" | "真"),
|
||||
Value::Number(n) => n.as_i64().unwrap_or(0) != 0,
|
||||
_ => false,
|
||||
};
|
||||
m.insert("access_log".into(), json!(on));
|
||||
}
|
||||
if let Some(cc) = args
|
||||
.get("cache_control")
|
||||
.or_else(|| args.get("缓存控制"))
|
||||
.and_then(|v| v.as_str())
|
||||
{
|
||||
let s = cc.trim();
|
||||
if !s.is_empty() {
|
||||
m.insert("cache_control".into(), json!(s));
|
||||
}
|
||||
}
|
||||
if let Some(bl) = args.get("body_limit") {
|
||||
let n = bl
|
||||
.as_u64()
|
||||
.or_else(|| bl.as_i64().map(|i| i as u64))
|
||||
.unwrap_or(0);
|
||||
if n > 0 {
|
||||
m.insert("body_limit".into(), json!(n));
|
||||
}
|
||||
}
|
||||
if let Some(routes) = args.get("json_routes") {
|
||||
m.insert(
|
||||
"json_routes".into(),
|
||||
middleware::json_routes_from_table(routes),
|
||||
// Optional allowlist: only `lib.member` form for now (no arbitrary file paths).
|
||||
if !fn_path.contains('.') || fn_path.contains('/') || fn_path.contains('#') {
|
||||
return Err(
|
||||
"invoke `fn` must be `lib.member` (imported on the entry module)".into(),
|
||||
);
|
||||
}
|
||||
let method = arg_str_opt(args, "method")
|
||||
.or_else(|| arg_str_opt(args, "方法"))
|
||||
.unwrap_or("POST")
|
||||
.to_uppercase();
|
||||
let body = arg_str_opt(args, "body")
|
||||
.or_else(|| arg_str_opt(args, "正文"))
|
||||
.unwrap_or("json")
|
||||
.to_ascii_lowercase();
|
||||
let ret = arg_str_opt(args, "return")
|
||||
.or_else(|| arg_str_opt(args, "返回"))
|
||||
.unwrap_or("json")
|
||||
.to_ascii_lowercase();
|
||||
let obj = app
|
||||
.as_object_mut()
|
||||
.ok_or_else(|| "app must be a map".to_string())?;
|
||||
let mut routes = obj
|
||||
.get("invoke_routes")
|
||||
.and_then(|v| v.as_object())
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
let key = path.trim_start_matches('/').to_string();
|
||||
routes.insert(
|
||||
key,
|
||||
json!({
|
||||
"method": method,
|
||||
"fn": fn_path,
|
||||
"body": body,
|
||||
"return": ret,
|
||||
}),
|
||||
);
|
||||
obj.insert("invoke_routes".into(), Value::Object(routes));
|
||||
Ok(app)
|
||||
});
|
||||
|
||||
@@ -1737,6 +1921,8 @@ web_ffi!(web_listen, |args: &Value| {
|
||||
page_500,
|
||||
gates,
|
||||
gallery_routes,
|
||||
proxy_routes,
|
||||
invoke_routes,
|
||||
middleware,
|
||||
cookie_secure,
|
||||
site_head,
|
||||
@@ -1793,6 +1979,8 @@ web_ffi!(web_listen, |args: &Value| {
|
||||
None,
|
||||
Vec::<http::Gate>::new(),
|
||||
HashMap::new(),
|
||||
Vec::<(String, crate::proxy::ProxyRoute)>::new(),
|
||||
Vec::<(String, crate::invoke::InvokeRoute)>::new(),
|
||||
middleware::Middleware::default(),
|
||||
cookie_secure,
|
||||
Vec::<crate::assets::HeadLink>::new(),
|
||||
@@ -1943,6 +2131,34 @@ web_ffi!(web_listen, |args: &Value| {
|
||||
gallery_routes.insert(k.clone(), v.clone());
|
||||
}
|
||||
}
|
||||
let mut proxy_routes: Vec<(String, proxy::ProxyRoute)> = Vec::new();
|
||||
if let Some(obj) = app.get("proxy_routes").and_then(|v| v.as_object()) {
|
||||
for (k, v) in obj {
|
||||
if let Some(r) = proxy::ProxyRoute::from_json(v) {
|
||||
let path = if k.starts_with('/') {
|
||||
k.clone()
|
||||
} else {
|
||||
format!("/{k}")
|
||||
};
|
||||
proxy_routes.push((path, r));
|
||||
}
|
||||
}
|
||||
proxy_routes.sort_by(|a, b| a.0.cmp(&b.0));
|
||||
}
|
||||
let mut invoke_routes: Vec<(String, invoke::InvokeRoute)> = Vec::new();
|
||||
if let Some(obj) = app.get("invoke_routes").and_then(|v| v.as_object()) {
|
||||
for (k, v) in obj {
|
||||
if let Some(r) = invoke::InvokeRoute::from_json(v) {
|
||||
let path = if k.starts_with('/') {
|
||||
k.clone()
|
||||
} else {
|
||||
format!("/{k}")
|
||||
};
|
||||
invoke_routes.push((path, r));
|
||||
}
|
||||
}
|
||||
invoke_routes.sort_by(|a, b| a.0.cmp(&b.0));
|
||||
}
|
||||
if app.get("tls_cert").is_some() || app.get("tls_key").is_some() {
|
||||
eprintln!(
|
||||
"marqdo web: in-process TLS is not enabled; terminate HTTPS at a reverse proxy (nginx/caddy) and set cookie_secure=True"
|
||||
@@ -2026,6 +2242,8 @@ web_ffi!(web_listen, |args: &Value| {
|
||||
page_500,
|
||||
gates,
|
||||
gallery_routes,
|
||||
proxy_routes,
|
||||
invoke_routes,
|
||||
middleware,
|
||||
cookie_secure,
|
||||
site_head,
|
||||
@@ -2141,6 +2359,8 @@ web_ffi!(web_listen, |args: &Value| {
|
||||
&middleware,
|
||||
site_head,
|
||||
icon_routes,
|
||||
proxy_routes,
|
||||
invoke_routes,
|
||||
)
|
||||
});
|
||||
|
||||
@@ -2369,9 +2589,19 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
|
||||
),
|
||||
(
|
||||
"web_app_middleware",
|
||||
"app,cors,security,compress,body_limit,json_routes,access_log,cache_control",
|
||||
"app,cors,security,compress,body_limit,json_routes,access_log,cache_control,proxy,invoke",
|
||||
web_app_middleware as PluginFn,
|
||||
),
|
||||
(
|
||||
"web_app_proxy",
|
||||
"app,path,upstream,stream,strip_prefix,methods,headers_from_env,timeout_ms",
|
||||
web_app_proxy as PluginFn,
|
||||
),
|
||||
(
|
||||
"web_app_invoke",
|
||||
"app,path,method,fn,body,return",
|
||||
web_app_invoke as PluginFn,
|
||||
),
|
||||
("web_form_new", "table,action,id", web_form_new as PluginFn),
|
||||
("web_form_fields", "form,fields", web_form_fields as PluginFn),
|
||||
("web_form_rules", "form,rules", web_form_rules as PluginFn),
|
||||
|
||||
@@ -24,7 +24,7 @@ use tower_http::set_header::SetResponseHeaderLayer;
|
||||
use crate::db;
|
||||
|
||||
/// Render a cell value as text (strings stay, numbers/bools stringify).
|
||||
fn cell_text(v: &Value) -> String {
|
||||
pub fn cell_text(v: &Value) -> String {
|
||||
match v {
|
||||
Value::Null => String::new(),
|
||||
Value::String(s) => s.clone(),
|
||||
|
||||
@@ -0,0 +1,462 @@
|
||||
//! Streaming reverse proxy routes for `app.proxy` / `configure proxy=`.
|
||||
//!
|
||||
//! Browser → Marqdo (same origin) → upstream, piping response bodies
|
||||
//! (including `text/event-stream`) without buffering the full stream.
|
||||
|
||||
use std::sync::Arc;
|
||||
use std::time::Duration;
|
||||
|
||||
use axum::body::Body;
|
||||
use axum::extract::{Request, State};
|
||||
use axum::http::{header, HeaderMap, HeaderName, HeaderValue, StatusCode};
|
||||
use axum::response::{IntoResponse, Response};
|
||||
use axum::routing::{MethodFilter, MethodRouter};
|
||||
use axum::Router;
|
||||
use futures_util::TryStreamExt;
|
||||
use serde_json::{json, Map, Value};
|
||||
|
||||
use crate::middleware::cell_text;
|
||||
use crate::table;
|
||||
|
||||
/// One declared proxy mount.
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct ProxyRoute {
|
||||
pub upstream: String,
|
||||
pub stream: bool,
|
||||
pub strip_prefix: String,
|
||||
pub methods: Vec<String>,
|
||||
/// `ENV_NAME=Header-Name` pairs injected on the upstream request.
|
||||
pub headers_from_env: Vec<(String, String)>,
|
||||
pub timeout_ms: u64,
|
||||
}
|
||||
|
||||
impl ProxyRoute {
|
||||
pub fn from_json(v: &Value) -> Option<Self> {
|
||||
let obj = v.as_object()?;
|
||||
let upstream = obj.get("upstream")?.as_str()?.trim().to_string();
|
||||
if upstream.is_empty() {
|
||||
return None;
|
||||
}
|
||||
let stream = obj
|
||||
.get("stream")
|
||||
.and_then(|x| x.as_bool())
|
||||
.unwrap_or(true);
|
||||
let strip_prefix = obj
|
||||
.get("strip_prefix")
|
||||
.and_then(|x| x.as_str())
|
||||
.unwrap_or("")
|
||||
.to_string();
|
||||
let methods = obj
|
||||
.get("methods")
|
||||
.and_then(|x| x.as_array())
|
||||
.map(|arr| {
|
||||
arr.iter()
|
||||
.filter_map(|m| m.as_str().map(|s| s.to_uppercase()))
|
||||
.filter(|s| !s.is_empty())
|
||||
.collect::<Vec<_>>()
|
||||
})
|
||||
.filter(|v| !v.is_empty())
|
||||
.unwrap_or_else(|| vec!["POST".into()]);
|
||||
let headers_from_env = parse_headers_from_env_value(obj.get("headers_from_env"));
|
||||
let timeout_ms = obj
|
||||
.get("timeout_ms")
|
||||
.and_then(|x| x.as_u64().or_else(|| x.as_i64().map(|i| i as u64)))
|
||||
.unwrap_or(120_000)
|
||||
.max(1);
|
||||
Some(Self {
|
||||
upstream,
|
||||
stream,
|
||||
strip_prefix,
|
||||
methods,
|
||||
headers_from_env,
|
||||
timeout_ms,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_headers_from_env_value(v: Option<&Value>) -> Vec<(String, String)> {
|
||||
let Some(v) = v else {
|
||||
return Vec::new();
|
||||
};
|
||||
match v {
|
||||
Value::String(s) => parse_headers_from_env_str(s),
|
||||
Value::Array(arr) => arr
|
||||
.iter()
|
||||
.filter_map(|x| x.as_str())
|
||||
.flat_map(parse_headers_from_env_str)
|
||||
.collect(),
|
||||
_ => Vec::new(),
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_headers_from_env_str(s: &str) -> Vec<(String, String)> {
|
||||
s.split(|c| c == ',' || c == ';')
|
||||
.filter_map(|part| {
|
||||
let part = part.trim();
|
||||
if part.is_empty() {
|
||||
return None;
|
||||
}
|
||||
let (env, hdr) = part.split_once('=')?;
|
||||
let env = env.trim();
|
||||
let hdr = hdr.trim();
|
||||
if env.is_empty() || hdr.is_empty() {
|
||||
return None;
|
||||
}
|
||||
Some((env.to_string(), hdr.to_string()))
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Expand `$VAR` / `${VAR}` in upstream URL strings.
|
||||
pub fn expand_env(s: &str) -> String {
|
||||
let mut out = String::with_capacity(s.len());
|
||||
let bytes = s.as_bytes();
|
||||
let mut i = 0;
|
||||
while i < bytes.len() {
|
||||
if bytes[i] == b'$' {
|
||||
if i + 1 < bytes.len() && bytes[i + 1] == b'{' {
|
||||
if let Some(end) = s[i + 2..].find('}') {
|
||||
let name = &s[i + 2..i + 2 + end];
|
||||
out.push_str(&std::env::var(name).unwrap_or_default());
|
||||
i += 3 + end;
|
||||
continue;
|
||||
}
|
||||
} else {
|
||||
let start = i + 1;
|
||||
let mut end = start;
|
||||
while end < bytes.len()
|
||||
&& (bytes[end].is_ascii_alphanumeric() || bytes[end] == b'_')
|
||||
{
|
||||
end += 1;
|
||||
}
|
||||
if end > start {
|
||||
let name = &s[start..end];
|
||||
out.push_str(&std::env::var(name).unwrap_or_default());
|
||||
i = end;
|
||||
continue;
|
||||
}
|
||||
}
|
||||
}
|
||||
out.push(bytes[i] as char);
|
||||
i += 1;
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
/// Normalize a proxy-routes GFM table into `app.proxy_routes` map shape.
|
||||
pub fn proxy_routes_from_table(table_v: &Value) -> Value {
|
||||
let rows = table::as_rows(table_v);
|
||||
let mut routes = Map::new();
|
||||
if let Some(arr) = rows.as_array() {
|
||||
for row in arr {
|
||||
let col = |keys: &[&str]| -> String {
|
||||
keys.iter()
|
||||
.find_map(|k| row.get(*k).map(cell_text))
|
||||
.unwrap_or_default()
|
||||
};
|
||||
let path = normalize_path(&col(&["路径", "path", "Path"]));
|
||||
if path.is_empty() || path == "/" {
|
||||
continue;
|
||||
}
|
||||
let upstream = col(&["上游", "upstream", "Upstream"]);
|
||||
if upstream.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let stream = {
|
||||
let s = col(&["流式", "stream", "Stream"]);
|
||||
if s.is_empty() {
|
||||
true
|
||||
} else {
|
||||
matches!(
|
||||
s.to_ascii_lowercase().as_str(),
|
||||
"true" | "1" | "yes" | "on" | "真"
|
||||
)
|
||||
}
|
||||
};
|
||||
let strip_prefix = col(&["去前缀", "strip_prefix", "Strip-Prefix"]);
|
||||
let methods_raw = col(&["方法", "methods", "Methods"]);
|
||||
let methods: Vec<String> = if methods_raw.is_empty() {
|
||||
vec!["POST".into()]
|
||||
} else {
|
||||
methods_raw
|
||||
.split(',')
|
||||
.map(|m| m.trim().to_uppercase())
|
||||
.filter(|m| !m.is_empty())
|
||||
.collect()
|
||||
};
|
||||
let headers_from_env = col(&[
|
||||
"环境头",
|
||||
"headers_from_env",
|
||||
"Headers-From-Env",
|
||||
]);
|
||||
let timeout_ms = col(&["超时", "timeout_ms", "Timeout"])
|
||||
.parse::<u64>()
|
||||
.unwrap_or(120_000);
|
||||
routes.insert(
|
||||
path.trim_start_matches('/').to_string(),
|
||||
json!({
|
||||
"upstream": upstream,
|
||||
"stream": stream,
|
||||
"strip_prefix": strip_prefix,
|
||||
"methods": methods,
|
||||
"headers_from_env": headers_from_env,
|
||||
"timeout_ms": timeout_ms,
|
||||
}),
|
||||
);
|
||||
}
|
||||
}
|
||||
Value::Object(routes)
|
||||
}
|
||||
|
||||
fn normalize_path(raw: &str) -> String {
|
||||
let s = raw.trim();
|
||||
if s.is_empty() {
|
||||
return String::new();
|
||||
}
|
||||
if s.starts_with('/') {
|
||||
s.to_string()
|
||||
} else {
|
||||
format!("/{s}")
|
||||
}
|
||||
}
|
||||
|
||||
/// Mount all proxy routes onto the router.
|
||||
pub fn mount_all(
|
||||
mut app: Router<Arc<crate::http::AppState>>,
|
||||
routes: &[(String, ProxyRoute)],
|
||||
) -> Router<Arc<crate::http::AppState>> {
|
||||
for (path, route) in routes {
|
||||
app = mount_one(app, path, route.clone());
|
||||
}
|
||||
app
|
||||
}
|
||||
|
||||
fn mount_one(
|
||||
app: Router<Arc<crate::http::AppState>>,
|
||||
path: &str,
|
||||
route: ProxyRoute,
|
||||
) -> Router<Arc<crate::http::AppState>> {
|
||||
let mut filter: Option<MethodFilter> = None;
|
||||
for m in &route.methods {
|
||||
let f = match m.as_str() {
|
||||
"GET" => MethodFilter::GET,
|
||||
"POST" => MethodFilter::POST,
|
||||
"PUT" => MethodFilter::PUT,
|
||||
"PATCH" => MethodFilter::PATCH,
|
||||
"DELETE" => MethodFilter::DELETE,
|
||||
"HEAD" => MethodFilter::HEAD,
|
||||
"OPTIONS" => MethodFilter::OPTIONS,
|
||||
_ => continue,
|
||||
};
|
||||
filter = Some(match filter {
|
||||
None => f,
|
||||
Some(acc) => acc.or(f),
|
||||
});
|
||||
}
|
||||
let filter = filter.unwrap_or(MethodFilter::POST);
|
||||
let r = route.clone();
|
||||
let handler = MethodRouter::new().on(filter, move |State(_st): State<Arc<crate::http::AppState>>, req: Request| {
|
||||
let r = r.clone();
|
||||
async move { proxy_handler(r, req).await }
|
||||
});
|
||||
app.route(path, handler)
|
||||
}
|
||||
|
||||
async fn proxy_handler(route: ProxyRoute, req: Request) -> Response {
|
||||
let method = req.method().clone();
|
||||
let uri = req.uri().clone();
|
||||
let in_headers = req.headers().clone();
|
||||
let body_bytes = match axum::body::to_bytes(req.into_body(), 64 * 1024 * 1024).await {
|
||||
Ok(b) => b,
|
||||
Err(e) => {
|
||||
return (
|
||||
StatusCode::BAD_REQUEST,
|
||||
format!("read body: {e}"),
|
||||
)
|
||||
.into_response();
|
||||
}
|
||||
};
|
||||
|
||||
let target = match build_upstream_url(&route, uri.path(), uri.query()) {
|
||||
Ok(u) => u,
|
||||
Err(e) => return (StatusCode::BAD_GATEWAY, e).into_response(),
|
||||
};
|
||||
|
||||
let client = match reqwest::Client::builder()
|
||||
.timeout(Duration::from_millis(route.timeout_ms))
|
||||
.build()
|
||||
{
|
||||
Ok(c) => c,
|
||||
Err(e) => {
|
||||
return (
|
||||
StatusCode::INTERNAL_SERVER_ERROR,
|
||||
format!("client: {e}"),
|
||||
)
|
||||
.into_response();
|
||||
}
|
||||
};
|
||||
|
||||
let mut builder = client.request(
|
||||
reqwest::Method::from_bytes(method.as_str().as_bytes()).unwrap_or(reqwest::Method::POST),
|
||||
&target,
|
||||
);
|
||||
|
||||
// Forward selected inbound headers (skip hop-by-hop).
|
||||
for (name, value) in in_headers.iter() {
|
||||
let lname = name.as_str().to_ascii_lowercase();
|
||||
if is_hop_by_hop(&lname) || lname == "host" {
|
||||
continue;
|
||||
}
|
||||
if let Ok(v) = value.to_str() {
|
||||
builder = builder.header(name.as_str(), v);
|
||||
}
|
||||
}
|
||||
|
||||
// Inject secrets from env (never from the browser).
|
||||
for (env_name, header_name) in &route.headers_from_env {
|
||||
if let Ok(val) = std::env::var(env_name) {
|
||||
if !val.is_empty() {
|
||||
// Common pattern: Authorization Bearer
|
||||
let hdr_val = if header_name.eq_ignore_ascii_case("authorization")
|
||||
&& !val.to_ascii_lowercase().starts_with("bearer ")
|
||||
{
|
||||
format!("Bearer {val}")
|
||||
} else {
|
||||
val
|
||||
};
|
||||
builder = builder.header(header_name.as_str(), hdr_val);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if !body_bytes.is_empty() {
|
||||
builder = builder.body(body_bytes);
|
||||
}
|
||||
|
||||
let upstream = match builder.send().await {
|
||||
Ok(r) => r,
|
||||
Err(e) => {
|
||||
return (StatusCode::BAD_GATEWAY, format!("upstream: {e}")).into_response();
|
||||
}
|
||||
};
|
||||
|
||||
let status = StatusCode::from_u16(upstream.status().as_u16()).unwrap_or(StatusCode::BAD_GATEWAY);
|
||||
let mut out_headers = HeaderMap::new();
|
||||
for (name, value) in upstream.headers().iter() {
|
||||
let lname = name.as_str().to_ascii_lowercase();
|
||||
if is_hop_by_hop(&lname) {
|
||||
continue;
|
||||
}
|
||||
if let (Ok(n), Ok(v)) = (
|
||||
HeaderName::from_bytes(name.as_str().as_bytes()),
|
||||
HeaderValue::from_bytes(value.as_bytes()),
|
||||
) {
|
||||
out_headers.append(n, v);
|
||||
}
|
||||
}
|
||||
// Ensure SSE content-type is preserved if present.
|
||||
if !out_headers.contains_key(header::CONTENT_TYPE) {
|
||||
if let Some(ct) = upstream.headers().get(reqwest::header::CONTENT_TYPE) {
|
||||
if let Ok(v) = HeaderValue::from_bytes(ct.as_bytes()) {
|
||||
out_headers.insert(header::CONTENT_TYPE, v);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if route.stream {
|
||||
let stream = upstream.bytes_stream().map_err(|e| {
|
||||
std::io::Error::new(std::io::ErrorKind::Other, e)
|
||||
});
|
||||
let body = Body::from_stream(stream);
|
||||
let mut resp = Response::new(body);
|
||||
*resp.status_mut() = status;
|
||||
*resp.headers_mut() = out_headers;
|
||||
resp
|
||||
} else {
|
||||
let bytes = match upstream.bytes().await {
|
||||
Ok(b) => b,
|
||||
Err(e) => {
|
||||
return (StatusCode::BAD_GATEWAY, format!("upstream body: {e}")).into_response();
|
||||
}
|
||||
};
|
||||
let mut resp = Response::new(Body::from(bytes));
|
||||
*resp.status_mut() = status;
|
||||
*resp.headers_mut() = out_headers;
|
||||
resp
|
||||
}
|
||||
}
|
||||
|
||||
fn build_upstream_url(
|
||||
route: &ProxyRoute,
|
||||
req_path: &str,
|
||||
query: Option<&str>,
|
||||
) -> Result<String, String> {
|
||||
let base = expand_env(&route.upstream);
|
||||
if base.is_empty() {
|
||||
return Err("proxy upstream empty after env expand".into());
|
||||
}
|
||||
// If upstream already looks like a full URL with path (contains scheme and
|
||||
// more than origin), and strip_prefix empties the remainder, use base as-is.
|
||||
let mut path = req_path.to_string();
|
||||
let strip = route.strip_prefix.trim();
|
||||
if !strip.is_empty() {
|
||||
let strip_n = normalize_path(strip);
|
||||
if path.starts_with(&strip_n) {
|
||||
path = path[strip_n.len()..].to_string();
|
||||
if path.is_empty() {
|
||||
path = "/".into();
|
||||
} else if !path.starts_with('/') {
|
||||
path = format!("/{path}");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let url = if base.contains("://") {
|
||||
let trimmed = base.trim_end_matches('/');
|
||||
// If base has no path beyond origin, append path; if base includes a
|
||||
// path suffix, append remaining path.
|
||||
if let Some(idx) = trimmed.find("://") {
|
||||
let after = &trimmed[idx + 3..];
|
||||
if after.contains('/') {
|
||||
// base includes path — append only if remaining path is not "/"
|
||||
if path == "/" {
|
||||
trimmed.to_string()
|
||||
} else {
|
||||
format!("{trimmed}{path}")
|
||||
}
|
||||
} else {
|
||||
format!("{trimmed}{path}")
|
||||
}
|
||||
} else {
|
||||
format!("{trimmed}{path}")
|
||||
}
|
||||
} else {
|
||||
return Err(format!("proxy upstream must be absolute URL, got `{base}`"));
|
||||
};
|
||||
|
||||
Ok(match query {
|
||||
Some(q) if !q.is_empty() => {
|
||||
if url.contains('?') {
|
||||
format!("{url}&{q}")
|
||||
} else {
|
||||
format!("{url}?{q}")
|
||||
}
|
||||
}
|
||||
_ => url,
|
||||
})
|
||||
}
|
||||
|
||||
fn is_hop_by_hop(name: &str) -> bool {
|
||||
matches!(
|
||||
name,
|
||||
"connection"
|
||||
| "keep-alive"
|
||||
| "proxy-authenticate"
|
||||
| "proxy-authorization"
|
||||
| "te"
|
||||
| "trailers"
|
||||
| "transfer-encoding"
|
||||
| "upgrade"
|
||||
| "content-length"
|
||||
)
|
||||
}
|
||||
+3
-1
@@ -12,7 +12,9 @@
|
||||
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件/**自写回**/**子任务**;v0.1.2+ 内置于 CLI) |
|
||||
| [`features/`](features/) | 特性迭代(含对象、官方 `ext/`) |
|
||||
|
||||
官方扩展(非 stdlib):`ext/llm`、`ext/agent` — 见 `features/05-extensions.mq.md` / `05-扩展.mq.md` 与 `doc/design/ext-*.md`。
|
||||
官方扩展(非 stdlib):`ext/llm`、`ext/agent`、`ext/web`、`ext/quantum`、`ext/linalg` — 见 `features/05-*.mq.md`、`06-*.mq.md`、`07-linalg.mq.md` / `07-线性代数.mq.md` 与 `doc/design/ext-*.md`。
|
||||
|
||||
中层标准库(Mid):`08`–`12`(re/encoding · path/fs · hash/secrets · csv/text · list/cli;及对应中文页)。
|
||||
|
||||
**不放** `errors/`:失败样例只在 `tests/errors/`。
|
||||
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: How to write a linear-algebra formula document
|
||||
description: ext/linalg formula-doc — declare, infix, run-implies-correct
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# Formula documents with ext/linalg
|
||||
|
||||
Not stdlib. Install: `marqdo ext add linalg` (or build `marqdo_plugin_linalg`).
|
||||
|
||||
**Idea:** if the `.mq.md` runs and the asserted form matches, the identity holds under the library rules. Algebra reads like a lecture; `factorize` / `lstsq` / `draw` stay explicit calculation steps.
|
||||
|
||||
# main
|
||||
|
||||
Declare symbols in a table, multiply, transpose — `T_ascii` is one-step display (auto-simplify).
|
||||
|
||||
`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`*
|
||||
*`t` = > `P`.T_ascii*
|
||||
> print text=`t`
|
||||
1. `t` == "B^T*A^T"
|
||||
> print text=formula-doc-ok
|
||||
2. *
|
||||
> print text=formula-doc-fail
|
||||
|
||||
> print text=see-examples-linalg-transpose
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: 如何写线性代数公式文档
|
||||
description: ext/linalg 公式文档面 — 声明、中缀、跑通即正确
|
||||
导入 la:ext/linalg/线性代数.mq.md
|
||||
---
|
||||
|
||||
# 用 ext/linalg 写公式文档
|
||||
|
||||
可选扩展(非 stdlib)。安装:`marqdo ext add linalg`(中文 id:`线性代数`)。
|
||||
|
||||
**思想:** `.mq.md` 能跑通且断言的规范形一致,则在库规则下该恒等式成立。代数叙述像讲义;`分解` / `最小二乘` / `绘图` 才是显式计算步骤。
|
||||
|
||||
# main
|
||||
|
||||
用表声明符号,再乘与转置 — `转置文本` 一步展示(默认化简)。
|
||||
|
||||
`形状` =
|
||||
|
||||
| @ | 名 | 行 | 列 |
|
||||
|---|----|----|----|
|
||||
| 1 | A | 2 | 3 |
|
||||
| 2 | B | 3 | 2 |
|
||||
|
||||
*`环境` = > la.声明 表=`形状`*
|
||||
*`A` = 环境[^A]*
|
||||
*`B` = 环境[^B]*
|
||||
*`P` = `A` * `B`*
|
||||
*`t` = > `P`.转置文本*
|
||||
> 打印 内容=`t`
|
||||
1. `t` == "B^T*A^T"
|
||||
> 打印 内容=formula-doc-ok
|
||||
2. *
|
||||
> 打印 内容=formula-doc-fail
|
||||
|
||||
> 打印 内容=see-examples-linalg-transpose
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Mid stdlib — regex and encoding
|
||||
description: lib/re + lib/encoding without plugins (Mid M1)
|
||||
import re:lib/re.mq.md
|
||||
import enc:lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# Regex and encoding in lib/
|
||||
|
||||
Mid-tier stdlib: everyday primitives stay in `lib/`, not ABI plugins.
|
||||
|
||||
# main
|
||||
|
||||
*`ok` = > re.is_match text="user@example.com" pattern="^[^@]+@[^@]+$"*
|
||||
*`tok` = > enc.base64_encode text="marqdo"*
|
||||
*`hex` = > enc.hex_encode text="ok"*
|
||||
> print text=`ok`
|
||||
> print text=`tok`
|
||||
> print text=`hex`
|
||||
1. `ok`
|
||||
> print text=mid-m1-ok
|
||||
2. *
|
||||
> print text=mid-m1-fail
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: 中层标准库 — 正则与编解码
|
||||
description: lib/正则 + lib/编码,无需插件(中层 M1)
|
||||
导入 正则:lib/正则.mq.md
|
||||
导入 编码:lib/编码.mq.md
|
||||
---
|
||||
|
||||
# 标准库中的正则与编解码
|
||||
|
||||
中层标准库:日常原语进 `lib/`,不必 ABI 插件。
|
||||
|
||||
# main
|
||||
|
||||
*`ok` = > 正则.匹配 内容="user@example.com" 模式="^[^@]+@[^@]+$"*
|
||||
*`tok` = > 编码.基64编码 内容="marqdo"*
|
||||
*`hex` = > 编码.十六进制编码 内容="ok"*
|
||||
> 打印 内容=`ok`
|
||||
> 打印 内容=`tok`
|
||||
> 打印 内容=`hex`
|
||||
1. `ok`
|
||||
> 打印 内容=mid-m1-ok
|
||||
2. *
|
||||
> 打印 内容=mid-m1-fail
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: Mid stdlib — path and fs
|
||||
description: lib/path + fs copy/move/temp (Mid M2)
|
||||
import path:lib/path.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
---
|
||||
|
||||
# Path algebra and file mid-layer
|
||||
|
||||
Join and normalize without plugins; copy/move stay sandboxed under the program directory.
|
||||
|
||||
# main
|
||||
|
||||
*`p` = > path.join a="out" b="demo.txt"*
|
||||
*`n` = > path.normalize path="out/./x/../demo.txt"*
|
||||
> fs.write_text path=`p` text="path-m2"
|
||||
> fs.copy_file src=`p` dest="out/demo-copy.txt"
|
||||
*`body` = > fs.read_text path="out/demo-copy.txt"*
|
||||
> print text=`p`
|
||||
> print text=`n`
|
||||
> print text=`body`
|
||||
1. `body` == "path-m2"
|
||||
> print text=mid-m2-ok
|
||||
2. *
|
||||
> print text=mid-m2-fail
|
||||
> fs.remove path=`p`
|
||||
> fs.remove path="out/demo-copy.txt"
|
||||
Loaded 100 of 169 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user