Document ext/quantum design and implementation roadmap.

Lock author API, simulator bounds, view SVG plan, and Q0–Q5 phases before coding the ABI plugin.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-08-12 10:21:07 +08:00
1 parent e4be0b0492
commit 25b6b86c26
3 files changed
+435 -182

No files matched your search

+1 -1
View File
@@ -50,7 +50,7 @@ Future optional ext domains get their own subdirs (e.g. `ext/web/`, `ext/quantum
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **`native/libagent.so`** (or `.dylib`) |
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **`native/libweb.so`** — 见 [ext-web.md](ext-web.md) · [roadmap](../roadmap/ext-web.md) |
| `quantum`(规划) | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](../roadmap/ext-quantum.md) |
| `quantum`(规划) | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](ext-quantum.md) · [roadmap](../roadmap/ext-quantum.md) |
`add agent` copies the built native plugin into `MARQDO_EXT/native/`. Build it first:
+402
View File
@@ -0,0 +1,402 @@
# 官方扩展:`ext/quantum` 量子计算模拟
| | |
|---|---|
| 状态 | **Accepted · 待实现**(作者面与分期已锁定;实现未开工) |
| 日期 | 2026-08-12 |
| 相关 | [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 插件实现 |
---
## 0. 一句话
`ext/quantum` 用 **GFM 表格 + 类方法 +(可选)`$$` 狄拉克/矩阵公式** 描述量子门与电路;**经典状态向量模拟**给出概率与采样。
文档能跑通,公式与电路约定就成立——这是 Marqdo「代码即文档」在量子教学上的最强展示位。
**不改 Marqdo 核心语法**;热路径只在 ABI 插件;**禁止**把量子核链进 `marqdo` 主二进制或在 `ext/**` 里调用 `host_*`。
---
## 1. 为何做量子扩展(与 math 的关系)
### 1.1 与 `lib/math` 的相似处
| math | quantum |
|------|---------|
| `` `f` = `` + `$$…$$` → `formula` | 门矩阵 / 态矢量可用 `$$` **展示与核对** |
| 库函数对公式求值、求导、作图 | 类方法对电路施门、模拟、画图 |
| view 内嵌 SVG;CLI 可 `path=` | view 内嵌**电路图 / 概率条 / 布洛赫**;CLI 可落盘 |
| 金样例失败 = 文档/公式错 | 金样例失败 = 门定义或电路叙述错 |
math 是**高中符号与曲线**;quantum 是**离散希尔伯特空间上的可执行电路文档**。两者都是「写出公式 → 跑通 → 证明文档正确」。
### 1.2 与 math 的刻意分界
| 做 | 不做 |
|----|------|
| 量子在 **`ext/quantum`**,经 `plugin.load` | **不**并进 `lib/math`(避免 stdlib 膨胀) |
| 复数振幅用 `{re, im}` map(与现有 `Value` 兼容) | **不**为量子在核心新增 `Value::Complex`(可二期) |
| 角度可用 `math.pi` 等常量 | **不**在 quantum 插件内重写 CAS |
### 1.3 「代码即文档」在这里的作用
典型教学页:
```markdown
# 贝尔态 |Φ+⟩
对 qubit 0 施 H,再 CNOT(0→1)。理想测量:`00` 与 `11` 各约 1/2。
# main
`steps` =
| 步 | 门 | 比特 |
|----|----|------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
*`p` = > `qc`.probabilities *
```
- 叙述与表格是**给人看的电路说明**;
- 同一文件是**可执行程序**;
- gold / CI 断言概率 → **文档与物理约定同步**,无需另维护「幻灯片公式」。
---
## 2. 硬约束(评审锁定)
1. **仅 ABI 插件接入**:`plugins/quantum` → `libquantum.so`;L1 在 `ext/quantum/*.mq.md`。
2. **`ext/quantum/**` 禁止 `host_*`**;经 `plugin.native_path` + `plugin.load`(同 web/agent)。
3. **中英分文件**:`quantum.mq.md` / `量子.mq.md`,**禁止**混排 API([stdlib-i18n.md](stdlib-i18n.md))。
4. **不改核心语法**;电路表单元格保持字面量;门名/比特下标由类方法解析。
5. **模拟器有硬上限**(默认 ≤ 12 qubits);超限报错,不静默截断。
6. **view 必须有专项展示**(结构卡 + 执行区 SVG),禁止只 dump JSON。
---
## 3. 布局与安装
```text
ext/quantum/
quantum.mq.md # 英文类 API
量子.mq.md # 中文类 API
plugins/quantum/
Cargo.toml
src/lib.rs # ABI v2:线性代数 / 施门 / 画 SVG
examples/quantum-bell/ # 规范示例(Q3)
tests/ext/quantum-*.mq.md
```
```bash
cargo build -p marqdo_plugin_quantum
marqdo ext add quantum
```
导入:
```markdown
---
> ext/quantum/quantum.mq.md
---
```
或中文:`> ext/quantum/量子.mq.md`。
---
## 4. 核心模型
### 4.1 运行时句柄(JSON map + `_type`)
| `_type`(英) | 中文类名 | 含义 |
|---------------|----------|------|
| `quantum_gate` | `量子门` | 具名门或自定义酉矩阵 |
| `quantum_circuit` | `量子电路` | n qubits + 有序门列表 |
| `quantum_state` | `量子态` | 状态向量(振幅列表) |
| `quantum_result` | `量子结果` | 概率 / 采样 / 可选坍缩态 |
| `quantum_svg` | (产物) | 带 `svg` 字段的可视化结果 |
插件返回 map;Marqdo 对象系统挂 `_type` 后可用方法链。
### 4.2 状态表示
- **纯态**状态向量:长度 `2^n`,每元 `{re, im}`(f64)。
- 默认初态:`|0…0⟩`(仅 index 0 振幅为 1)。
- 门作用后可选重归一化(阈值误差阈值,默认开)。
### 4.3 公式面(对齐 math 精神,不抢 math 实现)
允许用 `` `G` = `` + `$$…$$` 书写门矩阵或态(**展示 + 教学核对**):
````markdown
`H_matrix` =
$$
\frac{1}{\sqrt{2}}\begin{pmatrix}1&1\\1&-1\end{pmatrix}
$$
*`H` = > quantum.gate name=H *
*`ok` = > `H`.matches_matrix matrix=`H_matrix` *
````
- v1:**具名门**以插件内置酉矩阵为准;`matches_matrix` 为可选数值核对(容差)。
- 叙述区无名 `$$` 仍只是注释(同 [stdlib-math.md](stdlib-math.md) §2.4)。
- **不**要求核心 `Value::Formula` 理解量子;矩阵核对可走「公式 ASCII/LaTeX → 插件解析子集」或作者显式 `matrix=` 表。
**v1 优先路径:** 电路用**表 + 方法**;`$$` 作文档展示;矩阵核对可放 **Q3**。
---
## 5. 作者面 API(锁定草图)
### 5.1 英文 `ext/quantum/quantum.mq.md`
```markdown
# gate
+ `name`=None # H X Y Z S T I CX CZ SWAP …
+ `theta`=None # Rx/Ry/Rz
## matrix # → 振幅表 / 嵌套 list(文档与调试)
## draw # → quantum_svg(单门符号)
## matches_matrix
+ `matrix`
+ `tol`=1e-9
# circuit
+ `qubits`
+ `steps`=None # 可选:GFM 门序列表
## h / x / y / z / s / t
+ `qubit`
## rx / ry / rz
+ `qubit`
+ `theta`
## cx / cz
+ `control`
+ `target`
## swap
+ `a`
+ `b`
## barrier # 仅可视化分隔,不改变态
## measure # 标记测量(模拟时按计算基)
+ `qubits`=None # 默认全部
## append # 追加另一电路或门
+ `op`
## simulate # → quantum_state(不坍缩)
## probabilities # → map 基矢标签 → 概率
## run
+ `shots`=1024
+ `seed`=None # → quantum_result(计数直方图)
## draw
+ `path`=None # SVG;无 path 时仍可进 view 产物
## state # 当前缓存态(若已 simulate)
```
门方法返回**更新后的 circuit 句柄**(与 web `compose_*` 相同:`` `qc` = > `qc`.h qubit=0 *``)。
### 5.2 中文 `ext/quantum/量子.mq.md`
| 英文 | 中文 |
|------|------|
| `gate` | `门` |
| `circuit` | `电路` |
| `h` | `哈达玛` |
| `x` / `y` / `z` | `泡利X` / `泡利Y` / `泡利Z` |
| `cx` | `控非` |
| `cz` | `控相` |
| `rx`/`ry`/`rz` | `绕X`/`绕Y`/`绕Z` |
| `simulate` | `模拟` |
| `probabilities` | `概率` |
| `run` | `运行` |
| `draw` | `绘图` |
| `measure` | `测量` |
| `qubits` | `比特数` |
| `steps` | `步骤` |
| `shots` / `seed` | `次数` / `种子` |
插件 FFI 名稳定英文:`quantum_circuit_new`、`quantum_h`、`quantum_cx`、`quantum_simulate`、`quantum_draw_circuit`…
### 5.3 电路表(文档优先写法)
```markdown
`steps` =
| 步 | 门 | 比特 | 参数 |
|----|----|------|------|
| 1 | H | 0 | |
| 2 | CX | 0,1 | |
| 3 | RZ | 1 | pi/4 |
```
列名中英兼容:`步|step`、`门|gate`、`比特|qubits|qubit`、`参数|theta|params`。
*`qc` = > quantum.circuit qubits=2 steps=`steps` *` 与方法链**等价**;表更适合「整页即电路说明书」。
### 5.4 返回值形态
| 方法 | 返回 |
|------|------|
| `simulate` | `{_type, qubits, dim, amplitudes:[{re,im},…]}` |
| `probabilities` | `{ "00": 0.5, "11": 0.5 }`(标签为小端比特串,文档写死) |
| `run` | `{ counts: {…}, shots, seed }` |
| `draw` | `{_type: quantum_svg, kind: circuit\|gate\|probs\|bloch, svg: "…" }` |
---
## 6. 模拟器语义
| 项 | 锁定 |
|----|------|
| 模型 | 封闭系统纯态;计算基测量 |
| 默认上限 | **12 qubits**;`MARQDO_QUANTUM_MAX_QUBITS` 可下调(不可暗中上调超过编译期硬顶,硬顶建议 16) |
| 超限 | 错误信息含当前 n 与上限 |
| `simulate` / `probabilities` | **无 RNG**、确定性 |
| `run` | 多项式采样;`seed=` 可复现(金样必用) |
| 数值 | f64;门后 ‖ψ‖ 偏离阈值则重归一化并可选 warning 字段 |
实现:插件内 Kronecker / 按比特作用稀疏更新;可用 `nalgebra` 或手写,**不**捆绑外部量子云。
---
## 7. view 模式支持(专项)
对齐 [view.md](view.md) 与 math 作图:**Structure / Execution / Source 共用渲染**;禁止第二套皮肤。
### 7.1 Structure(结构区)
| 源形态 | 展示 |
|--------|------|
| `` `qc` = `` + 电路表 | **circuit-card**:比特数、门序列时间线(文本/紧凑 SVG) |
| `` `G` = `` + `$$` 门矩阵 | 沿用 **formula-card**(KaTeX);徽章可标 `gate`(若绑定来自 quantum.gate) |
| 方法链语句 | 普通调用行;不强制每步展开 |
### 7.2 Execution(执行区)
| 产物 | 展示 |
|------|------|
| `quantum_svg` | 与 math `plots` 同级:**内嵌 SVG**(电路轨线图 / 概率直方图 / 单比特布洛赫) |
| `probabilities` / `counts` | 表格 + 可选自动条形 SVG |
| `quantum_state` | 默认折叠振幅表;小 n(≤3)可并排显示基矢 |
### 7.3 产物如何进入 view(实现锁定)
插件**不能**直接碰核心 `HostContext.plots`。采用其一(实现时二选一,优先 A):
| 方案 | 做法 |
|------|------|
| **A(推荐)** | ABI `host_query("record_plot")`:参数 JSON `{svg}`;写入与 math 相同的 plots 列表([ext-abi.md](ext-abi.md) allowlist 增补一条) |
| **B** | 仅返回 `quantum_svg`;view 在渲染执行值时识别 `_type`/`svg` 字段并内嵌(不扩 ABI) |
CLI:`draw path=bell.svg` 写沙箱文件;无 path 时不把整段 SVG 灌 stdout(同 math §5)。
### 7.4 可视化内容(v1 必须 / 可后)
| 图 | v1 | 说明 |
|----|----|------|
| 电路轨线(qubit 线 + 门盒 + 控点) | **必须** | `circuit.draw` |
| 测量概率条形图 | **必须** | `probabilities` / `run` 后可 `draw kind=probs` |
| 单比特布洛赫球(SVG) | 应有 | 仅 n=1 或指定 qubit 约化(纯态投影) |
| 门矩阵热力图 | 可后 | Q4 |
| 交互拖拽编辑电路 | **不做** | 静态文档足够 |
视觉:内联 CSS;**无外链**字体/CDN(同 view 硬规则)。
---
## 8. 分期(开发计划)
```text
Q0 脚手架:CATALOG + plugins/quantum Hello + L1 ensure_plugin
Q1 态向量 + I/X/H/CX + simulate/probabilities;贝尔态 gold
Q2 Y/Z/S/T/Rx/Ry/Rz/CZ/SWAP + run(seed) + 中英 API 对齐
Q3 电路表 steps= + draw 电路 SVG + view record_plot/识别;examples/
Q4 概率/布洛赫图;matches_matrix;文档站 public/features
Q5 (可选,另文)噪声/密度矩阵;>12 qubits 张量网络——不挡 Accepted
```
| 阶段 | 交付物 | 验收 |
|------|--------|------|
| **Q0** | `marqdo_plugin_quantum` 注册 `quantum_ping`;L1 加载失败可读 | `ext add quantum` 路径通 |
| **Q1** | 贝尔态 `probabilities` ≈ 0.5/0.5 | `tests/ext/quantum-bell-smoke.mq.md` |
| **Q2** | 旋转门 + `run seed=` 计数稳定 | 中英双金样 |
| **Q3** | `steps=` 表;`draw` SVG 在 `view` HTML 含 `<svg` | 与 math-plot 同级断言 |
| **Q4** | 概率图 + 布洛赫;用户文档页 | `view output` 可浏览示例 |
实现路线图跟踪见 [roadmap/ext-quantum.md](../roadmap/ext-quantum.md)。
---
## 9. 规范示例(目标作者体验)
```markdown
---
title: Bell state
> ext/quantum/quantum.mq.md
---
# Bell |Φ+⟩
H on qubit 0, then CNOT. Expect |00⟩ and |11⟩ each with probability 1/2.
# main
`steps` =
| step | gate | qubits |
|------|------|--------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
*`p` = > `qc`.probabilities *
*`svg` = > `qc`.draw *
> print text=`p`
```
中文面对称:`量子.电路`、`哈达玛`、`控非`、`概率`、`绘图`。
---
## 10. 刻意不做(本 Accepted 范围)
- 真机 / 云后端(IBM、Braket…)
- 开放系统、完整噪声模型(可 Q5+)
- 符号电路编译优化器
- 交互式电路编辑器
- 把量子并入 `lib/math` 或核心 opcode
- 无上限比特的「生产级」模拟
---
## 11. 开放点(已收敛 / 剩余)
| 议题 | 结论 |
|------|------|
| 对象面 vs 自由函数 | **主推对象/方法链**;自由函数不平行提供 |
| 电路表 | **v1 纳入**(Q3),与方法链等价 |
| 振幅过大 | v1 全进 Value;n≤12 可接受;超限已挡 |
| view 产物 | **优先** `host_query("record_plot")` |
| 与 web | **不依赖** web 做可视化;SVG 自绘 |
---
## 12. 评审清单
1. ABI-only + 中英分文件是否认可?
2. 默认 12 qubits 上限是否合适?
3. 电路表列设计(步/门/比特/参数)是否够用?
4. view:电路轨线 + 概率条为 v1 必须,是否同意?
5. `$$` 矩阵核对放 Q4,是否同意先表驱动?
评审通过后:本文冻结为 Accepted → 按 §8 从 Q0 实现。
---
## 13. 一句话
**表格写出电路,类方法模拟与绘图;跑通金样即证明文档中的量子公式与步骤成立——math 管曲线,quantum 管希尔伯特空间上的可执行说明书。**
+32 -181
View File
@@ -1,203 +1,54 @@
# 官方扩展:量子计算模拟(未来规划)
# 官方扩展:`ext/quantum` 实现路线图
| | |
|---|---|
| 状态 | **规划 / 未开工** |
| 日期 | 2026-08-09 |
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [ext-web.md](ext-web.md) |
| 安装草案 | `marqdo ext add quantum`(中英面:`quantum` / `量子`) |
| 状态 | **Q0 未开工**(设计已 Accepted) |
| 日期 | 2026-08-12 |
| **锁定设计** | [design/ext-quantum.md](../design/ext-quantum.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) |
| 安装 | `marqdo ext add quantum`(`quantum` / `量子`) |
本文只跟踪**实现阶段**。作者面、模拟语义、view 可视化、分期以设计文为准。
---
## 1. 动机
## 1. 目标回顾(一句)
为教学、算法演示与智能体「可运行的量子电路文档」提供官方扩展:
- 在 `.mq.md` 里**声明量子比特与电路**(可读即文档)
- 支持**基础量子门**与常见电路写法
- **经典模拟**量子态在电路下的演化,输出状态向量 / 概率 /(可选)测量采样
- 重计算进 **ABI 插件**;安装走现有 `marqdo ext` 惯例
不宣称替代专业量子 SDK(Qiskit / Cirq 等),定位:**Marqdo 文档内可执行的最小量子模拟层**。
**可运行的量子电路文档**:表声明门序列 → ABI 模拟概率/采样 → view 内嵌电路/概率 SVG;文档跑通即公式约定成立。
---
## 2. 范围
## 2. 落地阶段
### 2.1 在范围内
| 阶段 | 内容 | 状态 |
|------|------|------|
| **Q0** | CATALOG + `plugins/quantum` ping + L1 `ensure_plugin` | pending |
| **Q1** | 态向量;I/X/H/CX;`simulate` / `probabilities`;贝尔态 gold | pending |
| **Q2** | Y/Z/S/T/R\* /CZ/SWAP;`run seed=`;中英 API | pending |
| **Q3** | `steps=` 电路表;`draw` 轨线 SVG;view `record_plot` 或值识别 | pending |
| **Q4** | 概率条 / 布洛赫;`matches_matrix`;examples + 用户文档 | pending |
| **Q5** | (可选)噪声 / 更大 n —— 另文 | pending |
| 能力 | 说明 |
|------|------|
| 状态表示 | 纯态状态向量(复数振幅);qubit 数有明确上限(见 §6) |
| 基础单比特门 | 至少:`I` `X` `Y` `Z` `H` `S` `T` 及 `Rx/Ry/Rz(θ)` |
| 基础多比特门 | 至少:`CNOT`(CX)、`CZ`;可选 `SWAP`、Toffoli(可用分解) |
| 电路构建 | 按序追加门;支持指定目标/控制比特下标 |
| 模拟 | 初态(默认 \|0…0⟩)→ 应用电路 → 返回状态或测量概率 |
| 测量 | 计算基概率;可选按概率采样坍缩(经典 RNG) |
| L1 API | `ext/quantum/quantum.mq.md` · `ext/quantum/量子.mq.md` |
| **ABI 插件** | `plugins/quantum`:线性代数与门作用热路径 |
| **CLI 安装** | `marqdo ext add quantum` / `remove` / `list` |
### 2.2 非目标(本规划)
- 真机 / 云量子后端调度
- 开放系统密度矩阵、噪声模型(可列二期)
- 符号电路优化编译器
- 把量子核链进 `marqdo` 主二进制
- 无上限比特数的「生产级」模拟器
验收金样(目标):`tests/ext/quantum-bell-smoke.mq.md`、`quantum-draw-smoke.mq.md`、中文对称样例。
---
## 3. 布局与安装(对齐惯例)
## 3. 已收敛的原开放点
```text
ext/
quantum/
quantum.mq.md
量子.mq.md
examples/ # 可选:贝尔态、量子传送草稿
plugins/
quantum/
Cargo.toml
src/lib.rs # ABI v2
```
```text
marqdo ext add quantum
marqdo ext remove quantum
```
安装:复制 L1 源 + `native/libquantum.so`(等)到 `MARQDO_EXT`,与 [ext-cli.md](../design/ext-cli.md) / agent 插件一致。
导入:
```markdown
---
> ext/quantum/quantum.mq.md
---
```
| 原疑问 | 锁定结论(见设计文) |
|--------|----------------------|
| 并进 math? | **否**,独立 `ext/quantum` |
| 电路表 | **要做**(Q3),与方法链等价 |
| view 图 | 自绘 SVG;优先 `host_query("record_plot")`;不依赖 web |
| 自由函数面 | **不**与对象面并行 |
---
## 4. API 外形(草案)
```markdown
---
> ext/quantum/quantum.mq.md
---
# main
*`qc` = > quantum.circuit qubits=2 *
> `qc`.h qubit=0
> `qc`.cx control=0 target=1
*`state` = > `qc`.simulate *
*`probs` = > `qc`.probabilities *
> print text=`probs`
```
中文面示例:
```markdown
*`电路` = > 量子.电路 比特数=2 *
> `电路`.哈达玛 比特=0
> `电路`.控非 控制=0 目标=1
*`概率` = > `电路`.概率 *
```
门命名中英对照表在落地时写入 L1 文档头;插件注册名建议稳定英文(`quantum_h`、`quantum_cx`、`quantum_simulate`)。
### 4.1 返回值形态
| 方法 | 建议返回 |
|------|----------|
| `simulate` | map:`qubits`、`amplitudes`(复数列表或 `{re,im}` 对)、可选 `dim` |
| `probabilities` | 列表或 map:基态标签 → 概率(如 `"00"` → 0.5) |
| `measure` | 采样得到的比特串 +(可选)坍缩后状态 |
复数如何进 Marqdo `Value`:优先 `{re, im}` map 列表,避免过早引入原生复数类型(若语言日后有复数,再收紧)。
---
## 5. 电路即文档
鼓励把电路写在可读段落旁:
```markdown
# 贝尔态
制备 `|Φ+⟩`:H 后 CNOT。
# main
*`qc` = > quantum.circuit qubits=2 *
…
```
可选:GFM 表描述门序列(与 [tables-maps-footnotes.md](tables-maps-footnotes.md) 横表字典对齐,**不阻塞**本扩展 v1——v1 以方法链为准)。
---
## 6. 模拟器约束
| 项 | 提案 |
|----|------|
| 默认上限 | **≤ 12 qubits**(状态 2^12;可 env `MARQDO_QUANTUM_MAX_QUBITS` 下调) |
| 超限 | 明确错误,不静默截断 |
| 数值 | `f64` 振幅;门后可选重归一化阈值 |
| 确定性 | `simulate` / `probabilities` 无 RNG;`measure` 可传 `seed=` |
实现放在插件内(`nalgebra` / 手写 Kronecker + 稀疏门作用均可);L1 只做参数校验与结果包装。
---
## 7. ABI 边界
| 插件 | `.mq.md` |
|------|----------|
| 分配/更新状态向量、施门、算概率 | 电路编排、打印、教学叙述 |
| 参数化旋转门 | `theta=` 从 Marqdo 传入 |
遵守:
- ABI v2 + JSON([ext-abi.md](../design/ext-abi.md))
- `ext/quantum/**` **禁止** `host_*`;经 `plugin.load`
- 与 [module-namespace.md](../design/module-namespace.md) / agent 硬规则一致:域逻辑不进核心 `HostFn`
---
## 8. 推荐落地顺序
```text
Q0 ext-cli 登记 quantum;插件注册 quantum_sim_version;L1 加载失败可读
Q1 n qubits 全零态 + H/X/CNOT + simulate/probabilities;金样贝尔态
Q2 Y/Z/S/T/Rz + measure seed=;中英 API
Q3 examples/ + catalog/OKF 可选 Module 页;文档
Q4 (可选)电路表语法糖;密度矩阵二期另文
```
验收:
1. `marqdo ext add quantum` 后可跑贝尔态金样,概率约 `00/11 ≈ 0.5`。
2. 无原生插件时错误指引 `ext add` / 构建 `marqdo_plugin_quantum`。
3. 超比特上限失败信息含上限值。
4. 双端(若金样走 tree)稳定;不强制 bytecode 同步若无量子 opcode(电路走插件即可)。
---
## 9. 开放点
1. 是否提供无对象的自由函数面(`## h circuit=…`)与对象面并行。
2. 振幅列表过大时是否写临时文件而非全进 Value。
3. 与 [stdlib-math.md](../design/stdlib-math.md) 复用:仅角度常数,不把量子并进 math 库。
4. 教学是否依赖 [ext-web.md](ext-web.md) 做布洛赫球可视化(可选、非阻塞)。
---
## 10. 与其它规划的关系
## 4. 与其它文档
| 文档 | 关系 |
|------|------|
| [ext-web.md](ext-web.md) | 同属「新域官方 ext + ABI + CLI」模板;可互为示例 |
| [object-inheritance.md](object-inheritance.md) | 可选:`# 变分电路 = > quantum.circuit`(不阻塞 Q1) |
| [agent-streaming.md](agent-streaming.md) | 无直接依赖;智能体可 `plan` 生成电路文件再 simulate |
| [design/ext-quantum.md](../design/ext-quantum.md) | **真理** |
| [stdlib-math.md](../design/stdlib-math.md) | 公式/作图精神对照;实现分离 |
| [ext-web.md](../design/ext-web.md) | 同属官方 ext + ABI + `ext add` 模板 |
| [view.md](../design/view.md) | 结构卡 + Execution 内嵌 SVG |