From eba0d703c54c5d474febdfac2566475015c927c3 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 28 Aug 2026 15:54:47 +0800 Subject: [PATCH] docs(quantum): document Q8 themes in skill and user-facing pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align SKILL/reference/examples, design docs, CHANGELOG, and feature demos with theme=dark|light|bw and the rebuild → ext add reload note. Co-authored-by: Cursor --- .cursor/skills/marqdo/SKILL.md | 22 +++++++--- .cursor/skills/marqdo/examples.md | 6 ++- .cursor/skills/marqdo/reference.md | 11 ++--- CHANGELOG.md | 1 + README.md | 2 +- doc/design/ai-skill.md | 10 ++--- doc/design/ext-quantum-viz-style.md | 50 ++++++++++++----------- doc/design/ext-quantum.md | 14 +++++-- examples/quantum-bell/README.md | 5 ++- examples/quantum-entanglement/README.md | 9 ++-- examples/quantum-entanglement/index.mq.md | 4 +- public/features/05-extensions.mq.md | 2 +- public/features/05-扩展.mq.md | 2 +- public/features/06-quantum.mq.md | 8 ++-- public/features/06-量子.mq.md | 10 +++-- skills/marqdo/SKILL.md | 22 +++++++--- skills/marqdo/examples.md | 6 ++- skills/marqdo/reference.md | 10 +++-- 18 files changed, 119 insertions(+), 75 deletions(-) diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index 83a63cd..095fea9 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -134,7 +134,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: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz (see below). +- 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: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz + Q8 themed SVG (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`/`非`. @@ -178,22 +178,29 @@ Design: [ext-web.md](../../doc/design/ext-web.md) · capability matrix: [web-net Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md). -## Official extension: `ext/quantum` (circuits + Q7) +## Official extension: `ext/quantum` (circuits + Q7/Q8) -Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --release -p marqdo_plugin_quantum`. +Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --release -p marqdo_plugin_quantum`, then **`marqdo ext add quantum` again** so view loads the new `libquantum.so` (stale plugin = old black/white circuits). - EN: `import quantum:ext/quantum/quantum.mq.md` - ZH: `导入 量子:ext/quantum/量子.mq.md` -**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; ≤12 qubits for statevector; density-matrix ops ≤6 qubits; one language file per program. +**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; ≤12 qubits for statevector; density-matrix ops ≤6 qubits; one language file per program; quote draw string args (`kind="…"`, `theme="…"`). **Core:** `# circuit` / `# gate` / `# density` — table `steps=` or method chain; `simulate` / `probabilities` / `run` / `draw`. **Q7 linear algebra:** `density`, `partial_trace`, `eig`, `expect` (Pauli string, left=high bit), `purity`, `kron`, `schmidt`, `fidelity`. -**Q7 draw kinds:** `circuit|probs|bloch|hinton|city|density|paulivec|qsphere|multibloch` (quote string args: `kind="hinton"`). Optional `theme="dark"|"light"|"bw"` (default dark tech lab; fixes label/wire overlap). +**Draw kinds:** `circuit|probs|bloch|hinton|city|density|paulivec|qsphere|multibloch`. -Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · viz style: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/). +**Q8 themes (circuit / probs / bloch):** `theme="dark"|"light"|"bw"` (ZH `主题=`; **default `dark`** — slate lab look, gate-family colors, label chips so wires never cross `q0` text). View plot chrome follows `data-theme` on the SVG. Advanced kinds (hinton/…) still Q8c pending full re-skin. + +```markdown +*_ = > `qc`.draw kind="circuit" theme="dark"* +*_ = > `qc`.draw kind="probs" theme="light"* +``` + +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/). ## AI authoring workflow @@ -221,6 +228,8 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7 | 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 | +| 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`) | ## Checklist before finishing @@ -231,4 +240,5 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7 - [ ] Nested functions ended with `---` / `***` / `****` when needed - [ ] Imports and call names share the same language file - [ ] Web sites: tables + web classes only (no JSON glue); `data/` gitignored +- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view - [ ] `marqdo run` succeeds (or errors addressed) diff --git a/.cursor/skills/marqdo/examples.md b/.cursor/skills/marqdo/examples.md index d99288e..ead775b 100644 --- a/.cursor/skills/marqdo/examples.md +++ b/.cursor/skills/marqdo/examples.md @@ -272,7 +272,7 @@ import db:db/index.mq.md - Full blog/CMS patterns: `examples/marqdo-blog/` (routes, SEO, RSS, auth, upload, WS). - Run after `marqdo ext add web` and building `marqdo_plugin_web`. -## 14. Quantum entanglement lab (ext/quantum Q7) +## 14. Quantum entanglement lab (ext/quantum Q7/Q8) ```markdown --- @@ -292,9 +292,11 @@ import quantum:ext/quantum/quantum.mq.md *rho = > `qc`.density* *red = > `rho`.partial_trace keep=0* *sch = > `qc`.schmidt cut=1* +*_ = > `qc`.draw kind="circuit" theme="dark"* *_ = > `qc`.draw kind="hinton"* > print text=`red` ``` - Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`. -- Build `marqdo_plugin_quantum` then `marqdo ext add quantum`. +- `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. diff --git a/.cursor/skills/marqdo/reference.md b/.cursor/skills/marqdo/reference.md index 05c8a77..7f2c9ce 100644 --- a/.cursor/skills/marqdo/reference.md +++ b/.cursor/skills/marqdo/reference.md @@ -55,7 +55,7 @@ Import one file; use **that** file’s function names. | `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods | | `ext/agent.mq.md` | `ext/智能体.mq.md` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.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 — see **ext/quantum** below | +| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below | Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`. @@ -78,9 +78,9 @@ Drivers (Postgres / Redis / S3): `db url=postgres://…`, `cache url=memory:`, ` Example project: `examples/marqdo-blog/`. Capability matrix: `doc/design/web-net-capabilities.md`. -## ext/quantum (circuits + Q7) +## ext/quantum (circuits + Q7/Q8) -Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p marqdo_plugin_quantum`. +Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p marqdo_plugin_quantum`, then re-run `ext add` so view picks up the new `.so`. | EN import | ZH import | Core types | |-----------|-----------|------------| @@ -93,8 +93,9 @@ Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p | Density (Q7) | `purity`, `partial_trace`, `eig`, `expect`, `draw` | ≤6 qubits for dense ρ | | Free (Q7) | `kron`, `schmidt`, `fidelity` | top-level on import bind | | Draw kinds | `circuit\|probs\|bloch\|hinton\|city\|density\|paulivec\|qsphere\|multibloch` | quote `kind="…"` | +| Themes (Q8) | `theme="dark"\|"light"\|"bw"` (ZH `主题=`) | default **dark**; circuit/probs/bloch themed; SVG `data-theme` | -Examples: `examples/quantum-bell/`, `examples/quantum-entanglement/`. Design: `doc/design/ext-quantum-q7.md`. +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`. ## Formula + plot (math) @@ -175,5 +176,5 @@ See `doc/design/call-arguments.md`. | `doc/design/web-net-capabilities.md` | ext/web capability matrix (W0–W7 + P3) | | `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 circuit/plot themes (`dark`/`light`/`bw`) | +| `doc/design/ext-quantum-viz-style.md` | Q8 themed SVG (`dark`/`light`/`bw`; circuit/probs/bloch) | | `doc/design/view-debug.md` | view / debug hosts | diff --git a/CHANGELOG.md b/CHANGELOG.md index 9264c6c..afd4fe9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ - **网络能力调研(`doc/design/web-net-capabilities.md`)**: 盘点 `ext/web` + `plugins/web` + `lib/net` 现状,对照主流语言网络栈(FastAPI / Express / Flask / axum),给出「开发一个完整 Web 项目」所需能力的差距清单与分波次补强路线(W1–W7 + P3,**2026-08-28 已全部落地**)。 - **AI Skill + 文档(ext/web 完结复核)**: `skills/marqdo/` 与 `.cursor/skills/marqdo/` 增加 **ext/web 动态站** 专节(硬规则、API 摘要、§13 最小站点样例);`doc/design/web-net-capabilities.md` 结论/对照表与 W7+P3 实现对齐;`doc/design/ai-skill.md` 更新用途说明。 - **`ext/quantum` Q7(高阶线性代数 + 高级可视化)**: 密度矩阵 / 部分迹 / Hermitian 谱 / Schmidt / Pauli 期望 / 纯度;SVG:hinton、city、density、paulivec、qsphere、multibloch。全部经 `plugins/quantum` ABI。设计 [ext-quantum-q7.md](doc/design/ext-quantum-q7.md);金样 `quantum-linalg-smoke`、`quantum-viz-advanced-smoke`;示例 [quantum-entanglement](examples/quantum-entanglement/)。 +- **`ext/quantum` Q8a/Q8b(可视化美学)**: `draw theme=dark|light|bw`(默认 dark);标签芯片 + gutter 消除线穿字;门族分色;probs/bloch 共用令牌;view 对 `data-theme` 换图框。设计 [ext-quantum-viz-style.md](doc/design/ext-quantum-viz-style.md)。改插件后须 `marqdo ext add quantum` 再开 view。 ### Changed - **Frontmatter import syntax**: `import bind:target` / `导入 bind:target` (file `.mq.md` or short name `lib.member`). Removed legacy `> path.mq.md` / `> use` imports. See [module-namespace.md](doc/design/module-namespace.md). diff --git a/README.md b/README.md index a3aa17f..3016801 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ marqdo catalog public -o .marqdo - **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页 - **`marqdo version --check`**:与 GitHub 最新 release 对比 - 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务** -- **官方扩展库 `ext/`**(本版重点,**非** stdlib):`llm` · `agent` · **`web`(W0–W7 + P3 完结,见 [marqdo-blog](examples/marqdo-blog/))** · `quantum`。安装:`marqdo ext list` / `add …` / `remove`(见 [ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext` 或 `MARQDO_EXT`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`。设计:[ext-llm](doc/design/ext-llm.md) · [ext-agent](doc/design/ext-agent.md) · [ext-web](doc/design/ext-web.md) · [web-net-capabilities](doc/design/web-net-capabilities.md) · [ext-quantum](doc/design/ext-quantum.md) +- **官方扩展库 `ext/`**(本版重点,**非** stdlib):`llm` · `agent` · **`web`(W0–W7 + P3 完结,见 [marqdo-blog](examples/marqdo-blog/))** · **`quantum`(Q0–Q7 + Q8a/b 主题 SVG,见 [quantum-entanglement](examples/quantum-entanglement/))**。安装:`marqdo ext list` / `add …` / `remove`(见 [ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext` 或 `MARQDO_EXT`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`。设计:[ext-llm](doc/design/ext-llm.md) · [ext-agent](doc/design/ext-agent.md) · [ext-web](doc/design/ext-web.md) · [web-net-capabilities](doc/design/web-net-capabilities.md) · [ext-quantum](doc/design/ext-quantum.md) · [ext-quantum-viz-style](doc/design/ext-quantum-viz-style.md) - **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}` - **用户静态站**:`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` diff --git a/doc/design/ai-skill.md b/doc/design/ai-skill.md index 5dd2e4a..a354c54 100644 --- a/doc/design/ai-skill.md +++ b/doc/design/ai-skill.md @@ -3,22 +3,22 @@ | | | |---|---| | 状态 | 已提供 | -| 日期 | 2026-08-05(初版)· 2026-08-28(ext/web 完结复核) | +| 日期 | 2026-08-05(初版)· 2026-08-28(ext/web 完结复核 · ext/quantum Q8) | | 路径 | [`skills/marqdo/`](../../skills/marqdo/)(权威);Cursor 镜像 [`.cursor/skills/marqdo/`](../../.cursor/skills/marqdo/) | --- ## 目的 -让接入方(Cursor Agent、其它支持 Agent Skills 的模型宿主)在**加载本 skill 后**即可按 v0.2 语法正确编写 / 修改 `.mq.md`,并在使用 **`ext/web` 动态站** 时遵循 GFM 表 + 类方法作者面(不混中英 API、不写 JSON 袋胶水)。 +让接入方(Cursor Agent、其它支持 Agent Skills 的模型宿主)在**加载本 skill 后**即可按 v0.2 语法正确编写 / 修改 `.mq.md`,并在使用 **`ext/web` 动态站** 或 **`ext/quantum` 电路/可视化** 时遵循官方作者面(不混中英 API、不写 JSON 袋胶水;量子绘图须引用 `kind=`/`theme=` 字符串)。 ## 内容 | 文件 | 用途 | |------|------| -| `SKILL.md` | 必读:硬规则、标记表、**ext/web 动态站**、工作流、反模式 | -| `reference.md` | 按需:CLI、stdlib/ext 索引、**ext/web API 摘要** | -| `examples.md` | 按需:可复制样例(含 §13 最小站点) | +| `SKILL.md` | 必读:硬规则、标记表、**ext/web**、**ext/quantum(Q7/Q8)**、工作流、反模式 | +| `reference.md` | 按需:CLI、stdlib/ext 索引、web/quantum API 摘要 | +| `examples.md` | 按需:可复制样例(§13 最小站点 · §14 纠缠实验) | ## 使用 diff --git a/doc/design/ext-quantum-viz-style.md b/doc/design/ext-quantum-viz-style.md index a9f59c4..efedfc4 100644 --- a/doc/design/ext-quantum-viz-style.md +++ b/doc/design/ext-quantum-viz-style.md @@ -2,7 +2,7 @@ | | | |---|---| -| 状态 | **Accepted · Q8a/Q8b done · Q8c pending** | +| 状态 | **Accepted · Q8a/Q8b landed · Q8c pending** | | 日期 | 2026-08-28 | | 父设计 | [ext-quantum.md](ext-quantum.md) · [ext-quantum-q7.md](ext-quantum-q7.md) | | 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) | @@ -52,7 +52,20 @@ | `light` | 浅底文档打印 | | `bw` | 无彩色、高对比 | -作者面:`draw theme=dark|light|bw`(中文 `主题=`);缺省 `dark`。 +作者面: + +```markdown +*`svg` = > `qc`.draw kind="circuit" theme="dark"* +*`svg` = > `qc`.draw kind="probs" theme="light"* +``` + +| 参数 | 默认 | 说明 | +|------|------|------| +| `kind` | `circuit` | 既有枚举不变 | +| `theme` | `dark` | 新增;非法值报错 | +| `path` | — | 既有 | + +中文:`主题=dark|light|bw`。ABI:`quantum_draw_circuit` 增可选 `theme`(circuit/probs/bloch 已生效;gate/density 高级图见 Q8c)。 ### 3.2 Dark 色板(默认) @@ -74,20 +87,20 @@ Light / bw 在实现里各给一套平行表;金样以 dark 主断言(SVG ```text | pad | label_col | gutter | col0 | … | colN | pad | - ^q0 文字居中 ^导线从此开始(不穿过文字) + ^q0 芯片标签 ^导线从此开始(不穿过文字) ``` -| 常量 | 建议值 | +| 常量 | 实现值 | |------|--------| -| `LABEL_W` | 36 | -| `GUTTER` | 10(标签区右缘 → 第一门中心前的空档) | -| `PAD_X` / `PAD_Y` | 16 / 20 | -| `COL_W` | 64 | -| `ROW_H` | 48 | -| 门盒 | 32×32,`rx=6` | -| 线宽 | 导线 1.75;门描边 1.25;控制竖线 2 | +| `LABEL_W` | 52 | +| `GUTTER` | 20 | +| `PAD_X` / `PAD_Y` | 24 / 36 | +| `COL_W` | 80 | +| `ROW_H` | 64 | +| 门盒 | 40×40,`rx=8` | +| 线宽 | 导线双层 3.2+1.8;门描边 ~1.1;控制竖线 2.25 | -标签:`text-anchor="end"`,落在标签列右缘内侧;`dominant-baseline="middle"`;导线 `x1 = LABEL_W + GUTTER`。 +标签:圆角芯片 + 居中文字;导线 `x1 = PAD_X + LABEL_W + GUTTER`。 ### 3.4 门族映射 @@ -104,18 +117,7 @@ Light / bw 在实现里各给一套平行表;金样以 dark 主断言(SVG ## 4. 作者面(增量,向后兼容) -```markdown -*`svg` = > `qc`.draw kind="circuit" theme="dark" * -*`svg` = > `qc`.draw kind="probs" theme="light" * -``` - -| 参数 | 默认 | 说明 | -|------|------|------| -| `kind` | `circuit` | 既有枚举不变 | -| `theme` | `dark` | 新增;非法值报错 | -| `path` | — | 既有 | - -中文:`主题=dark|light|bw`。ABI:`quantum_draw_circuit` 增可选 `theme`;`quantum_density_draw` / `quantum_gate_draw` 同步。 +见 §3.1。字符串参数须加引号:`kind="circuit"`、`theme="dark"`(中文 `种类=` / `主题=`)。改插件后须 `marqdo ext add quantum` 再开 view,否则仍加载旧 `.so`。 --- diff --git a/doc/design/ext-quantum.md b/doc/design/ext-quantum.md index aac2876..d5195e6 100644 --- a/doc/design/ext-quantum.md +++ b/doc/design/ext-quantum.md @@ -2,8 +2,8 @@ | | | |---|---| -| 状态 | **Accepted · Q0–Q6 已落地 · Q7 进行中**([ext-quantum-q7.md](ext-quantum-q7.md):高阶线性代数 + 高级可视化) | -| 日期 | 2026-08-12(初版)· 2026-08-28(Q7) | +| 状态 | **Accepted · Q0–Q7 完结 · Q8a/Q8b 完结**([ext-quantum-q7.md](ext-quantum-q7.md) · [ext-quantum-viz-style.md](ext-quantum-viz-style.md);Q8c 高级态图换肤待做) | +| 日期 | 2026-08-12(初版)· 2026-08-28(Q7 · Q8 viz) | | 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [ext-web.md](ext-web.md) · [view.md](view.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) | | 安装(目标) | `marqdo ext add quantum`(中英:`quantum` / `量子`) | | 本文目的 | 锁定**作者面**、**模拟语义**、**view 可视化**与**分期**;指导 ABI 插件实现 | @@ -191,6 +191,8 @@ $$ + `seed`=None # → quantum_result(计数直方图) ## draw + `path`=None # SVG;无 path 时仍可进 view 产物 + + `kind`=circuit # circuit|probs|bloch|hinton|…(见 Q7) + + `theme`=dark # dark|light|bw(Q8;电路/概率/布洛赫) ## state # 当前缓存态(若已 simulate) ``` @@ -211,6 +213,8 @@ $$ | `probabilities` | `概率` | | `run` | `运行` | | `draw` | `绘图` | +| `kind` | `种类` | +| `theme` | `主题` | | `measure` | `测量` | | `qubits` | `比特数` | | `steps` | `步骤` | @@ -295,13 +299,14 @@ CLI:`draw path=bell.svg` 写沙箱文件;无 path 时不把整段 SVG 灌 st | 图 | v1 | 说明 | |----|----|------| -| 电路轨线(qubit 线 + 门盒 + 控点) | **必须** | `circuit.draw` | +| 电路轨线(qubit 线 + 门盒 + 控点) | **必须** | `circuit.draw`;Q8 默认 `theme=dark`(标签芯片 + 门族分色) | | 测量概率条形图 | **必须** | `probabilities` / `run` 后可 `draw kind=probs` | | 单比特布洛赫球(SVG) | 应有 | 仅 n=1 或指定 qubit 约化(纯态投影) | | 门矩阵热力图 | **必须** | `gate.draw kind=matrix`(幅值热图 + 小数标注) | +| 高级态图(hinton/city/…) | Q7 | 见 [ext-quantum-q7.md](ext-quantum-q7.md);换肤见 Q8c | | 交互拖拽编辑电路 | **不做** | 静态文档足够 | -视觉:内联 CSS;**无外链**字体/CDN(同 view 硬规则)。 +视觉:内联 SVG 色与字体栈;**无外链**字体/CDN(同 view 硬规则)。主题令牌与布局:[ext-quantum-viz-style.md](ext-quantum-viz-style.md)。view 对 `svg[data-theme=dark]` 使用深色图框。 --- @@ -325,6 +330,7 @@ Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext- | **Q5** | `noise` 轨迹;`barrier`/`measure`/`append`/`state` | `quantum-noise-smoke` / `quantum-author-api-smoke` | | **Q6** | 公式/`matrix=` 自定义门 | [ext-quantum-custom-gate.md](ext-quantum-custom-gate.md) | | **Q7** | 密度矩阵线性代数 + Hinton/City/QSphere 等 SVG + 纠缠示例 | [ext-quantum-q7.md](ext-quantum-q7.md) ✅ | +| **Q8** | 可视化美学:`theme` + 标签 gutter + 门族分色 | [ext-quantum-viz-style.md](ext-quantum-viz-style.md) · Q8a/Q8b ✅ · Q8c 待做 | 实现路线图跟踪见 [roadmap/ext-quantum.md](../roadmap/ext-quantum.md)。 diff --git a/examples/quantum-bell/README.md b/examples/quantum-bell/README.md index 242f760..9aec5b5 100644 --- a/examples/quantum-bell/README.md +++ b/examples/quantum-bell/README.md @@ -1,10 +1,11 @@ # quantum-bell -Bell |Φ⁺⟩ via `ext/quantum` circuit table + draw. +Bell |Φ⁺⟩ via `ext/quantum` circuit table + draw (default `theme=dark` tech lab SVG). ```bash cargo build -p marqdo_plugin_quantum +marqdo ext add quantum # after rebuild, so view loads the new .so marqdo run examples/quantum-bell/index.mq.md ``` -Writes `bell.svg` next to the program (sandbox cwd). +Writes `bell.svg` next to the program (sandbox cwd). Themes: `theme="dark"|"light"|"bw"` — see [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md). diff --git a/examples/quantum-entanglement/README.md b/examples/quantum-entanglement/README.md index 3c69a98..38a387b 100644 --- a/examples/quantum-entanglement/README.md +++ b/examples/quantum-entanglement/README.md @@ -1,13 +1,14 @@ # quantum-entanglement -Bell |Φ⁺⟩ **entanglement lab** via `ext/quantum` Q7: density matrix, partial trace, Schmidt entropy, and advanced SVG (hinton / qsphere / multibloch / city). +Bell |Φ⁺⟩ **entanglement lab** via `ext/quantum` Q7/Q8: density matrix, partial trace, Schmidt entropy, and SVG plots (circuit themed dark by default; hinton / qsphere / multibloch / city). ```bash cargo build --release -p marqdo_plugin_quantum -marqdo ext add quantum # once +marqdo ext add quantum # once (re-run after rebuilding the plugin) marqdo run examples/quantum-entanglement/index.mq.md +# optional: marqdo view examples/quantum-entanglement/ ``` -Prints probabilities, full/reduced purity, ⟨ZZ⟩, and Schmidt entropy; writes SVGs next to the program (sandbox cwd). +Prints probabilities, full/reduced purity, ⟨ZZ⟩, and Schmidt entropy; writes SVGs next to the program (sandbox cwd). Circuit/probs/bloch accept `theme="dark"|"light"|"bw"`. -Design: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · sibling demo: [quantum-bell](../quantum-bell/). +Design: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · sibling: [quantum-bell](../quantum-bell/). diff --git a/examples/quantum-entanglement/index.mq.md b/examples/quantum-entanglement/index.mq.md index 0b2601d..8ead944 100644 --- a/examples/quantum-entanglement/index.mq.md +++ b/examples/quantum-entanglement/index.mq.md @@ -1,6 +1,6 @@ --- title: Entanglement lab -description: Bell state — density, partial trace, Schmidt, advanced SVG (Q7). +description: Bell state — density, partial trace, Schmidt, themed SVG (Q7/Q8). import quantum:ext/quantum/quantum.mq.md import math:lib/math.mq.md --- @@ -32,7 +32,7 @@ Build |Φ⁺⟩ with H then CX. Full-state purity stays 1; tracing out one qubit *sch = > `qc`.schmidt cut=1* *ent = sch[^entropy]* -*_ = > `qc`.draw path="entangle-circuit.svg"* +*_ = > `qc`.draw path="entangle-circuit.svg" theme="dark"* *_ = > `qc`.draw kind="hinton" path="entangle-hinton.svg"* *_ = > `qc`.draw kind="qsphere" path="entangle-qsphere.svg"* *_ = > `qc`.draw kind="multibloch" path="entangle-multibloch.svg"* diff --git a/public/features/05-extensions.mq.md b/public/features/05-extensions.mq.md index 92a5a2a..dcce442 100644 --- a/public/features/05-extensions.mq.md +++ b/public/features/05-extensions.mq.md @@ -36,7 +36,7 @@ ext/agent — agent framework + native plugin. Design: doc/design/ext-agent.md ext/web — HTTP / SQLite·Postgres site helpers + native plugin. **W0–W7 + P3 complete** (middleware, CRUD+FTS, security, SEO/RSS, upload/gallery, RBAC, sitemap). Design: doc/design/ext-web.md · capabilities: doc/design/web-net-capabilities.md · example: examples/marqdo-blog/ -ext/quantum — circuits, draw, noise, formula matrix custom gates. Design: doc/design/ext-quantum.md +ext/quantum — circuits, draw, noise, formula matrix custom gates, Q7 density/viz, Q8 themed SVG (`theme=dark|light|bw`). Design: doc/design/ext-quantum.md · doc/design/ext-quantum-viz-style.md Installer: marqdo ext list / add / remove — doc/design/ext-cli.md diff --git a/public/features/05-扩展.mq.md b/public/features/05-扩展.mq.md index f92603e..48a1398 100644 --- a/public/features/05-扩展.mq.md +++ b/public/features/05-扩展.mq.md @@ -36,7 +36,7 @@ ext/agent(智能体)— 智能体框架 + 原生插件。设计:doc/design ext/web(网页)— HTTP / SQLite 站点助手 + 原生插件。设计:doc/design/ext-web.md -ext/quantum(量子)— 电路、绘图、噪声、公式矩阵自定义门。设计:doc/design/ext-quantum.md +ext/quantum(量子)— 电路、绘图、噪声、公式矩阵自定义门、Q7 密度/高级图、Q8 主题 SVG(`主题=dark|light|bw`)。设计:doc/design/ext-quantum.md · doc/design/ext-quantum-viz-style.md 安装器:marqdo ext list / add / remove — doc/design/ext-cli.md diff --git a/public/features/06-quantum.mq.md b/public/features/06-quantum.mq.md index 8e6c898..82140e8 100644 --- a/public/features/06-quantum.mq.md +++ b/public/features/06-quantum.mq.md @@ -1,6 +1,6 @@ --- title: Quantum circuits (ext/quantum) -description: Official quantum simulator — tables, gates, Q7 density and advanced SVG +description: Official quantum simulator — tables, gates, Q7 density, Q8 themed SVG import quantum:ext/quantum/quantum.mq.md --- @@ -10,7 +10,9 @@ Optional package (not stdlib). Install: `marqdo ext add quantum` (or build `marq GHZ (3 qubits): H on q0, then CX 0→1 and 0→2. Ideal |000⟩ / |111⟩ each ≈ 1/2. -Q7: Bell density, partial trace (mixed reduced state), Schmidt entropy, and `draw kind=hinton` / qsphere. See `examples/quantum-entanglement/`. +Q7: Bell density, partial trace, Schmidt, `draw kind=hinton` / qsphere — `examples/quantum-entanglement/`. + +Q8: `draw theme="dark"|"light"|"bw"` (default dark lab look) on circuit / probs / bloch. Rebuild plugin then `ext add` so view loads the new native lib. `steps` = @@ -22,7 +24,7 @@ Q7: Bell density, partial trace (mixed reduced state), Schmidt entropy, and `dra *`qc` = > quantum.circuit qubits=3 steps=`steps`* *`p` = > `qc`.probabilities* -*`_` = > `qc`.draw kind="probs"* +*`_` = > `qc`.draw kind="probs" theme="dark"* *`H` = > quantum.gate name="H"* *`__` = > `H`.draw kind="matrix"* diff --git a/public/features/06-量子.mq.md b/public/features/06-量子.mq.md index d863612..67d37c7 100644 --- a/public/features/06-量子.mq.md +++ b/public/features/06-量子.mq.md @@ -1,6 +1,6 @@ --- title: 量子电路(ext/quantum) -description: 官方量子模拟 — 表、门、概率/布洛赫/矩阵热图 SVG +description: 官方量子模拟 — 表、门、Q7 密度与高级图、Q8 主题 SVG 导入 量子:ext/quantum/量子.mq.md --- @@ -8,7 +8,11 @@ description: 官方量子模拟 — 表、门、概率/布洛赫/矩阵热图 SV 可选扩展(非 stdlib)。安装:`marqdo ext add quantum`(或编译 `marqdo_plugin_quantum`)。 -GHZ(3 比特):q0 哈达玛,再控非 0→1、0→2。理想 |000⟩ / |111⟩ 各约 1/2。`绘图 种类=probs` 嵌入概率条;`门.绘图 种类=matrix` 为矩阵热图。 +GHZ(3 比特):q0 哈达玛,再控非 0→1、0→2。理想 |000⟩ / |111⟩ 各约 1/2。 + +Q7:密度 / 部分迹 / Schmidt / `绘图 种类=hinton` 等 — `examples/quantum-entanglement/`。 + +Q8:`绘图 主题="dark"|"light"|"bw"`(默认 dark 科技感)作用于电路 / 概率 / 布洛赫。改插件后须再 `ext add`,view 才会加载新 `.so`。 `步骤` = @@ -20,7 +24,7 @@ GHZ(3 比特):q0 哈达玛,再控非 0→1、0→2。理想 |000⟩ / |1 *`qc` = > 量子.电路 比特数=3 步骤=`步骤`* *`p` = > `qc`.概率* -*`_` = > `qc`.绘图 种类="probs"* +*`_` = > `qc`.绘图 种类="probs" 主题="dark"* *`H` = > 量子.门 名="H"* *`__` = > `H`.绘图 种类="matrix"* diff --git a/skills/marqdo/SKILL.md b/skills/marqdo/SKILL.md index df8516c..095fea9 100644 --- a/skills/marqdo/SKILL.md +++ b/skills/marqdo/SKILL.md @@ -134,7 +134,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: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz (see below). +- 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: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz + Q8 themed SVG (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`/`非`. @@ -178,22 +178,29 @@ Design: [ext-web.md](../../doc/design/ext-web.md) · capability matrix: [web-net Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md). -## Official extension: `ext/quantum` (circuits + Q7) +## Official extension: `ext/quantum` (circuits + Q7/Q8) -Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --release -p marqdo_plugin_quantum`. +Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --release -p marqdo_plugin_quantum`, then **`marqdo ext add quantum` again** so view loads the new `libquantum.so` (stale plugin = old black/white circuits). - EN: `import quantum:ext/quantum/quantum.mq.md` - ZH: `导入 量子:ext/quantum/量子.mq.md` -**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; ≤12 qubits for statevector; density-matrix ops ≤6 qubits; one language file per program. +**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; ≤12 qubits for statevector; density-matrix ops ≤6 qubits; one language file per program; quote draw string args (`kind="…"`, `theme="…"`). **Core:** `# circuit` / `# gate` / `# density` — table `steps=` or method chain; `simulate` / `probabilities` / `run` / `draw`. **Q7 linear algebra:** `density`, `partial_trace`, `eig`, `expect` (Pauli string, left=high bit), `purity`, `kron`, `schmidt`, `fidelity`. -**Q7 draw kinds:** `circuit|probs|bloch|hinton|city|density|paulivec|qsphere|multibloch` (quote string args: `kind="hinton"`). +**Draw kinds:** `circuit|probs|bloch|hinton|city|density|paulivec|qsphere|multibloch`. -Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/). +**Q8 themes (circuit / probs / bloch):** `theme="dark"|"light"|"bw"` (ZH `主题=`; **default `dark`** — slate lab look, gate-family colors, label chips so wires never cross `q0` text). View plot chrome follows `data-theme` on the SVG. Advanced kinds (hinton/…) still Q8c pending full re-skin. + +```markdown +*_ = > `qc`.draw kind="circuit" theme="dark"* +*_ = > `qc`.draw kind="probs" theme="light"* +``` + +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/). ## AI authoring workflow @@ -221,6 +228,8 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7 | 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 | +| 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`) | ## Checklist before finishing @@ -231,4 +240,5 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7 - [ ] Nested functions ended with `---` / `***` / `****` when needed - [ ] Imports and call names share the same language file - [ ] Web sites: tables + web classes only (no JSON glue); `data/` gitignored +- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view - [ ] `marqdo run` succeeds (or errors addressed) diff --git a/skills/marqdo/examples.md b/skills/marqdo/examples.md index d99288e..ead775b 100644 --- a/skills/marqdo/examples.md +++ b/skills/marqdo/examples.md @@ -272,7 +272,7 @@ import db:db/index.mq.md - Full blog/CMS patterns: `examples/marqdo-blog/` (routes, SEO, RSS, auth, upload, WS). - Run after `marqdo ext add web` and building `marqdo_plugin_web`. -## 14. Quantum entanglement lab (ext/quantum Q7) +## 14. Quantum entanglement lab (ext/quantum Q7/Q8) ```markdown --- @@ -292,9 +292,11 @@ import quantum:ext/quantum/quantum.mq.md *rho = > `qc`.density* *red = > `rho`.partial_trace keep=0* *sch = > `qc`.schmidt cut=1* +*_ = > `qc`.draw kind="circuit" theme="dark"* *_ = > `qc`.draw kind="hinton"* > print text=`red` ``` - Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`. -- Build `marqdo_plugin_quantum` then `marqdo ext add quantum`. +- `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. diff --git a/skills/marqdo/reference.md b/skills/marqdo/reference.md index 163d7df..7f2c9ce 100644 --- a/skills/marqdo/reference.md +++ b/skills/marqdo/reference.md @@ -55,7 +55,7 @@ Import one file; use **that** file’s function names. | `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods | | `ext/agent.mq.md` | `ext/智能体.mq.md` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.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 — see **ext/quantum** below | +| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below | Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`. @@ -78,9 +78,9 @@ Drivers (Postgres / Redis / S3): `db url=postgres://…`, `cache url=memory:`, ` Example project: `examples/marqdo-blog/`. Capability matrix: `doc/design/web-net-capabilities.md`. -## ext/quantum (circuits + Q7) +## ext/quantum (circuits + Q7/Q8) -Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p marqdo_plugin_quantum`. +Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p marqdo_plugin_quantum`, then re-run `ext add` so view picks up the new `.so`. | EN import | ZH import | Core types | |-----------|-----------|------------| @@ -93,8 +93,9 @@ Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p | Density (Q7) | `purity`, `partial_trace`, `eig`, `expect`, `draw` | ≤6 qubits for dense ρ | | Free (Q7) | `kron`, `schmidt`, `fidelity` | top-level on import bind | | Draw kinds | `circuit\|probs\|bloch\|hinton\|city\|density\|paulivec\|qsphere\|multibloch` | quote `kind="…"` | +| Themes (Q8) | `theme="dark"\|"light"\|"bw"` (ZH `主题=`) | default **dark**; circuit/probs/bloch themed; SVG `data-theme` | -Examples: `examples/quantum-bell/`, `examples/quantum-entanglement/`. Design: `doc/design/ext-quantum-q7.md`. +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`. ## Formula + plot (math) @@ -175,4 +176,5 @@ See `doc/design/call-arguments.md`. | `doc/design/web-net-capabilities.md` | ext/web capability matrix (W0–W7 + P3) | | `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/view-debug.md` | view / debug hosts |