Files
marqdo/doc/design/ext-quantum-handbook.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

5.9 KiB
Executable File

Quantum:从「拆分过的库」到可执行开发手册

项目 内容
日期 2026-11-08
使用与开发真相源 英文根入口 · 中文根入口
回归门禁 quantum_handbook.rs
思想来源 next/010 · next/011 · next/012
本文定位 记录本次修正的原因与边界;日常使用无需先读本文

上一轮把量子库拆成了模块树,也加入了 call 与叙述比例,但没有形成「只沿 index 就能使用和开发」的闭环。问题出在验收标准:目录、工具和叙述存在,并不能证明一个陌生开发者能完成实验、理解结果,再正确扩展它。

已确认的缺口

缺口 后果 本轮修正
## For AI agents、## Package layout 等说明标题 解析成无业务意义的真实函数,污染工具树 说明用自然段,标题保留给工具/对象
裸 $qc、缺会话或只有消费者没有生产者 照抄命令失效,Rust argv 测试发现不了 shell 展开 每页完整实验;引用和文本字面量用 shell 单引号
字符串 kind="bitflip" 的双引号被 shell 去掉 CLI 拒绝未带字面量引号的文本 使用 'kind="bitflip"',通过真实 shell 测试
默认值后紧贴英文标点,如容差后的问号 标点被叙述扫描器纳入默认值,number 变成 text 标点与默认值分隔,实跑覆盖省略参数
旋转、自定义门应用、追加、矩阵导出藏在对象方法里 命令行只能走很窄的 Bell 演示路径 补齐自由工具,保留既有作者对象方法
重复「本方法返回句柄」等通用套话 满足比例却没有解释科学语义 移除旧填充,加入来源、单位、边界、预期和下一步
缺源码归属与验证方式 AI 知道怎么调用,却不知道怎么开发 各模块写新增配方/原语的修改位置、镜像和既有金样

同一个入口承担四个职责

使用路径是「打开根入口 → 根据科学问题选模块 → 复制完整实验 → 核对独立期望」。每个子入口也能单独冷启动,包括输入生产者、参数、结果形状、何时转到兄弟模块。

开发路径从最小必要变化开始:新实验组合已有工具;新酉矩阵使用 gate.custom;只有真实能力缺口才改原生实现。每个模块给出它负责的 Rust 文件、ABI 导出、中英镜像及应保留的测试。根入口的 bell_analysis 是这种开发方式的具体配方。

bell_circuit 返回可继续组合的电路;原有 bell_phi_plus / 贝尔态 保留概率结果;新增 bell_analysis / 纠缠分析 返回整体纯度、约化纯度、ZZ 关联和 Schmidt 数据。相同概率的经典混合不能冒充 Bell 纯态,所以不能只验证 00/11 概率。

工具入口继续是普通 .mq.md 函数。没有添加 Skill 编译器、MCP 包装、额外工具 manifest 或另一套 schema。符号与契约依靠现有解析和 knowledge inspect;符合 next/011 的简洁核心。

契约位置必须符合当前解析器

旧范式要求「返回表放在体末、返回标记前」,但 src/parse/mod.rs::extract_function_contract 只在首条可执行语句前提取参数与返回契约。放到 cap.load 之后的返回表会成为普通表,无法承担预期校验。

本轮以实现为准:参数表紧跟标题;返回表也位于首条执行语句之前;意图叙述仍可与后续执行步骤交错。对象构造器和方法同样补齐契约。叙述声明承载默认值,表说明类型和含义,不把 any 句柄伪装成新增的领域类型系统。

check --narrative-ratio 仍是最低门槛,但不再充当手册完成的唯一证据。测试同时检查每个可调用单元具有真正提取出的返回契约、参数无漂移,根符号只有三个实际实验工具。

只承诺已有能力

手册明确以下区别,而不把 next 的愿景写成已经实现的功能:

  • call、跨进程 journal 会话、双后端和稳定符号查询已有实现。
  • 状态向量默认 12 比特、硬上限 16;密度和 Schmidt 最多六比特。
  • 理想态与概率忽略教学噪声;只有 run 采样施噪。
  • 密度矩阵构造检查形状和厄米性,不认证半正定与归一化。
  • Schmidt 熵使用自然对数;局部纯度和关联需要结合整体态解释。
  • draw_state / 画态 补上现有 qsphere、multibloch 能力;高级态图换肤仍是 Q8c 规划。
  • call --effects plugin 允许绘图返回 SVG,但宿主仍禁文件写入;实际落盘走作者程序的 run。
  • 插件 journal 重放可能重复插件效果;会话不是无副作用的永久对象仓库。
  • 智能体决定持久交互分支和复杂自我改进并非本轮实现。

验证与推广条件

先构建 marqdo_plugin_quantum,再执行:

cargo test --locked --test quantum_handbook
cargo test --locked --test call_cli quantum_
cargo test --locked --test gold ext_quantum -- --test-threads=1

手册门禁直接提取双语源码中的 sh 围栏,经过 bash 执行原命令,逐次检查退出码与 JSON,不抄写另一份命令目录。作者程序也从 marqdo 围栏提取执行。两类示例都验证 Tree/Bytecode,并比较独立数学期望与中间结果;会话放在临时目录隔离。

组合工具另覆盖具名旋转门、矩阵导出、应用、追加和密度矩阵观察。既有 gold 继续覆盖公式、自定义门、噪声、振幅阻尼、作者方法与 SVG。

向其他扩展推广时,复用的是这些验证问题:陌生人能否独立启动、能否解释结果、能否找到修改归属、示例是否来自源码且持续执行。无需把 Quantum 的具体物理工具或新的模板套到每个库。