量子算法实践指南 unitarylab/quantum-practices

⚛ Quantum-Practices

Quantum Algorithms Best Practices
量子算法 最佳实践

What is this?

Quantum-Practices 是一个 DeepSeek Harness 工具包，专注量子算法最佳实践。它通过一个只读的、面向模型的工具，为 DeepSeek Harness 智能体提供结构化、可审查的指导。

作为 DeepSeek Harness 插件，它注册了一个只读工具 quantum_practices，用来列出、搜索和读取打包好的量子算法实践指南。这些指南来自构建时生成的不可变目录。

Quantum-Practices 基于 GitHub 项目 unitarylab/quantum-skills 改编而来。原项目提供量子算法指南语料；本仓库在此基础上重新打磨，做成 DeepSeek Harness 工具包，并附带一份生成的只读实践目录。

✨ Key Features

- 渐进式披露 — 根目录的 SKILL.md 很轻量；算法与模拟器指南只在需要时加载。
- DeepSeek Harness 工具包 — quantum_practices 暴露 list、search、get，不执行任何代码。
- 只读运行时 — 不联网，不起子进程，不写文件系统，不执行 Python，不用凭据，不跑原生代码。
- 最佳实践覆盖 — 基础原语、线性系统、密码学、哈密顿量模拟、Schrodingerization、特征求解器、梯度、量子机器学习、态制备、量子纠错。
- 多模拟器支持 — UnitaryLab（推荐）、Qiskit、PennyLane，并给出明确的选择规则。
- 语料来自 GitHub — 实践指南只从公开的 GitHub 上游同步。
- 适合教学 — 可用于概念讲解、线路设计、代码审查和动手演示。

🌟 Algorithms Covered

| Category | Algorithms |
| Primitives | Grover, QPE, Hadamard Test, Hadamard Transform, Amplitude Amplification, Amplitude Estimation |
| Linear Systems | HHL, LCU, AQC, VQLS, QSVT-QLSA, QFT, Quantum Signal Processing (QSP) |
| Cryptography | Shor's Algorithm, Discrete Logarithm, Simon's Algorithm |
| Hamiltonian Simulation | Cartan decomposition, Trotter, QDrift, Taylor Series, QSP |
| Schrodingerization | Advection, Heat (1D/2D) |
| Eigensolvers | NumPyEigensolver, VQD |
| 梯度 | Parameter-shift、Finite-difference、Linear-combination、SPSA、Reverse-mode、QFI |
| 量子机器学习 | VQE、VQC、QAOA、QCBM、CVQNN、Fermi-Hubbard VQE |
| 态制备 | Mottonen、MPS、Multiplexer、Pauli、Superposition |
| 量子纠错 | qLDPC、CSS Codes、Hypergraph Product Codes |

💻 支持的模拟器

| 模拟器 | 适用场景 | 平台 |
| UnitaryLab （默认） | 学习、算法演示、PDE 工作流 | Win / macOS / Linux |
| Qiskit | 噪声模型、IBM 硬件工作流 | Win / macOS / Linux |
| PennyLane | 可微分混合优化 | Win / macOS / Linux |

📁 仓库结构

quantum-practices/
+-- SKILL.md # Root practice index used by the catalog
+-- README.md
+-- package.json # DeepSeek Harness tool-bundle metadata
+-- cordis.patch.yml # Profile Bundle patch
+-- src/ # DSH plugin source
+-- lib/ # Built release artifact
+-- algorithms/ # Quantum algorithm skills
| +-- primitives/ # Grover, QPE, Hadamard test/transform, AA, AE
| +-- linear-systems/ # HHL, LCU, AQC, VQLS, QSVT-QLSA, QFT, QSP
| +-- cryptography/ # Shor, discrete logarithm, Simon
| +-- hamiltonian-simulation/ # Cartan, Trotter, QDrift, Taylor, QSP
| +-- schrodingerization/ # Advection and heat-equation workflows
| +-- eigensolvers/ # NumPyEigensolver, VQD
| +-- gradients/ # Parameter-shift, finite-diff, SPSA, reverse, QFI
| +-- quantum-machine-learning/ # VQE, VQC, QAOA, QCBM, CVQNN
| +-- state-preparation/ # Mottonen, MPS, multiplexer, Pauli, superposition
| +-- quantum-error-correction/ # qLDPC, CSS codes
+-- simulators/ # Simulator selection & installation guides
+-- unitarylab/ # Recommended simulator guide
+-- qiskit/
+-- pennylane/

DeepSeek Harness 插件

多数用户只需把 Quantum-Practices 装进你使用的 DeepSeek Harness 配置档，之后让智能体在回答量子算法问题前先查阅 Quantum-Practices。

如果你用 Web UI：

npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add \
github:unitarylab/quantum-practices#main

安装完成后重启 DeepSeek Harness Web。

如果你用无头命令行：

npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile headless add \
github:unitarylab/quantum-practices#main

本地开发时，直接安装当前检出目录：

dsh plugin --profile web add "/path/to/quantum-practices"
dsh plugin --profile headless add "/path/to/quantum-practices"

如需审查或发布留证，把 main 换成固定的 40 位 commit SHA。

确认配置档里已插入对应行：

dsh --profile headless --dump-config | \bash
rg "tool-quantum-practices|dsh-unitarylab-quantum-practices"

预期输出： text

== dsh-unitarylab-quantum-practices

- id: tool-quantum-practices
name: dsh-unitarylab-quantum-practices

跑一次功能测试： bash
npx @deepseek-ai/dsh@0.1.0-rc.6 --profile headless \
"Use the quantum_practices tool to find the HHL practice guide and explain the required matrix constraints."

安装完成后，用户可以直接用自然语言提问。模型会在后台调用 quantum_practices： text Use Quantum-Practices to review HHL before explaining the matrix constraints on A. Before writing Grover code, check Quantum-Practices and list the common implementation pitfalls. Use Quantum-Practices to compare quantum phase estimation and the quantum Fourier transform. Consult Quantum-Practices and recommend a simulator for a variational quantum algorithm. Check Quantum-Practices and explain how Trotter and QDrift differ for Hamiltonian simulation.

默认情况下，get 返回一份精简、节省 token 的视图，只包含最相关的章节。只有当用户需要完整实现说明、完整示例或调试上下文时，模型才应请求 detail="full"。

开发者也可以直接查看工具契约： text
quantum_practices(action="list")
quantum_practices(action="search", query="HHL linear system")
quantum_practices(action="get", id="algorithms/linear-systems/hhl")
quantum_practices(action="get", query="Explain HHL matrix constraints")
quantum_practices(action="get", query="Implement HHL with a 2x2 example", detail="full")

DSH 插件从不执行 algorithms//scripts/.py，也从不安装或导入 Python 依赖。

构建与验证 bash
npm ci
npm run check
npm pack --dry-run --json

npm run build 会重新生成 src/generated/skill-catalog.ts，并编译已提交的 lib/ 发布产物。

Python 运行时

Quantum-Practices 不附带根目录 requirements.txt、预打包的 wheel，也不附带 Python 运行时。任何 Python 环境配置都属于另一个项目，也就是你选择运行生成示例的地方；它不在 DeepSeek Harness 插件的安装路径里。

许可证

本仓库源码采用 MIT License 授权。

署名

Quantum-Practices 改编自 unitarylab/quantum-skills。署名详情见 NOTICE。

这是什么？

Quantum-Practices 是一个面向量子算法最佳实践的 DeepSeek Harness 工具包。它通过一个只读模型工具，为 DeepSeek Harness Agent 提供结构化、可审查的量子算法实践指南。

作为 DeepSeek Harness 插件，它注册一个只读 quantum_practices 工具，用于从构建期固化的 Practice Catalog 中列出、搜索和读取量子算法实践指南。

Quantum-Practices 基于 GitHub 项目 unitarylab/quantum-skills 进行二次创作。原项目提供了量子算法指南语料；本仓库在此基础上改造为 DeepSeek Harness 工具包，并生成只读的 Practice Catalog。

✨ 核心特性

- 渐进式加载 — 根 SKILL.md 轻量，算法与模拟器指南仅在需要时才加载。
- DeepSeek Harness 工具包 — quantum_practices 提供 list、search、get，不执行代码。
- 只读运行时 — 无网络、无 subprocess、无写盘、无 Python 执行、无 credentials、无 native code。
- 最佳实践覆盖 — 基元、线性系统、密码学、哈密顿量模拟、Schrodingerization、本征求解器、梯度方法、量子机器学习、态制备与量子纠错一应俱全。
- 多模拟器支持 — UnitaryLab（推荐）、Qiskit、PennyLane，附明确选型规则。
- GitHub 来源语料 — Practice guides 仅从公开 GitHub 上游同步。
- 教学友好 — 适用于概念解释、电路设计、代码审查和动手实验。

🌟 算法覆盖范围

| 分类 | 算法 |
| 基础量子算法 | Grover、QPE、Hadamard 测试、Hadamard 变换、振幅放大、振幅估计 |
| 线性系统 | HHL、LCU、AQC、VQLS、QSVT-QLSA、QFT、量子信号处理（QSP） |
| 密码学 | Shor 算法、离散对数、Simon 算法 |
| 哈密顿量模拟 | Cartan 分解、Trotter、QDrift、Taylor 级数、QSP |
| Schrodingerization | 对流、热方程（一维/二维） |
| 本征求解器 | NumPyEigensolver、VQD |
| 梯度方法 | 参数位移、有限差分、线性组合、SPSA、反向模式、QFI |
| 量子机器学习 | VQE、VQC、QAOA、QCBM、CVQNN、Fermi-Hubbard VQE |
| 态制备 | Mottonen、MPS、Multiplexer、Pauli、Superposition |
| 量子纠错 | qLDPC、CSS 码、超图乘积码 |

💻 支持的模拟器

| 模拟器 | 适用场景 | 平台 |
| UnitaryLab (默认) | 学习、算法演示、PDE 工作流 | Win / macOS / Linux |
| Qiskit | 噪声模型、IBM 硬件工作流 | Win / macOS / Linux |
| PennyLane | 可微分混合优化 | Win / macOS / Linux |

📁 仓库结构

quantum-practices/

+-- SKILL.md # Catalog 使用的根实践索引 +-- README.md +-- package.json # DeepSeek Harness tool-bundle 元数据 +-- cordis.patch.yml # Profile Bundle patch +-- src/ # DSH 插件源码 +-- lib/ # 编译后的 release artifact

+-- algorithms/ # 量子算法技能
| +-- primitives/ # Grover、QPE、Hadamard 测试/变换、振幅放大与估计
| +-- linear-systems/ # HHL、LCU、AQC、VQLS、QSVT-QLSA、QFT、QSP
| +-- cryptography/ # Shor、离散对数、Simon
| +-- hamiltonian-simulation/ # Cartan、Trotter、QDrift、Taylor、QSP
| +-- schrodingerization/ # 对流与热方程工作流
| +-- eigensolvers/ # NumPyEigensolver、VQD
| +-- gradients/ # 参数位移、有限差分、SPSA、反向模式、QFI
| +-- quantum-machine-learning/ # VQE、VQC、QAOA、QCBM、CVQNN
| +-- state-preparation/ # Mottonen、MPS、Multiplexer、Pauli、Superposition
| +-- quantum-error-correction/ # qLDPC、CSS 码

+-- simulators/ # 模拟器选型与安装指南 +-- unitarylab/ # 推荐模拟器指南 +-- qiskit/ +-- pennylane/

DeepSeek Harness 插件

普通用户不需要理解底层 action。把 Quantum-Practices 安装进正在使用的 DeepSeek Harness profile 之后，直接让 Agent 先查 Quantum-Practices，再回答量子算法问题即可。

如果你使用 Web UI： bash
npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add \
github:unitarylab/quantum-practices#main

安装后重启 DeepSeek Harness Web。

如果你使用 headless CLI： bash
npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile headless add \
github:unitarylab/quantum-practices#main

本地开发时，可以直接安装当前 checkout： bash
dsh plugin --profile web add "/path/to/quantum-practices"
dsh plugin --profile headless add "/path/to/quantum-practices"

审核或 release evidence 建议把 main 换成固定的 40 位 commit SHA。

验证 profile 中是否出现插入的 row： bash
dsh --profile headless --dump-config | \
rg "tool-quantum-practices|dsh-unitarylab-quantum-practices"

期望输出：

== dsh-unitarylab-quantum-practices
- id: tool-quantum-practices
name: dsh-unitarylab-quantum-practices

做一次真实功能测试：

npx @deepseek-ai/dsh@0.1.0-rc.6 --profile headless \
"Use the quantum_practices tool to find the HHL practice guide and explain the required matrix constraints."

安装完成后，用户可以直接自然提问；模型应在后台调用 quantum_practices：

请先查 Quantum-Practices，再解释 HHL 对矩阵 A 的约束。
写 Grover 代码前，请查 Quantum-Practices 并列出常见实现错误。
请根据 Quantum-Practices 比较量子相位估计和量子傅里叶变换。
请查 Quantum-Practices，并建议变分量子算法应该使用哪个 simulator。
请参考 Quantum-Practices，说明 Trotter 和 QDrift 在哈密顿量模拟中的区别。

默认情况下，get 返回省 token 的 brief 视图，只包含最相关的章节。只有当用户需要完整实现说明、完整示例或调试上下文时，模型才应该请求 detail="full"。

开发者也可以直接查看工具接口：

quantum_practices(action="list")
quantum_practices(action="search", query="HHL linear system")
quantum_practices(action="get", id="algorithms/linear-systems/hhl")
quantum_practices(action="get", query="Explain HHL matrix constraints")
quantum_practices(action="get", query="Implement HHL with a 2x2 example", detail="full")

DSH 插件不会执行 algorithms//scripts/.py，也不会安装或导入 Python 依赖。

构建与验证

npm ci
npm run check
npm pack --dry-run --json

npm run build 会重新生成 src/generated/skill-catalog.ts，并编译需要提交的 lib/ release artifact。

Python 运行时

Quantum-Practices 不发布根 requirements.txt、内置 wheel 或 Python runtime。任何 Python 环境都应属于你实际运行示例的独立项目，不属于 DeepSeek Harness 插件安装路径。

License

本仓库源码采用 MIT License。

Attribution

Quantum-Practices 是基于 unitarylab/quantum-skills 的二次创作。来源说明详见 NOTICE。