一句话定位

quantum-practices 是 DeepSeek Harness 的一个只读工具包，给 DSH Agent 配一本"量子算法最佳实践手册"。安装后，Agent 在回答 HHL、QPE、Shor、VQE、Trotter 等量子算法相关提问时，可以先去查这本内置手册再作答，避免给出错的实现或选错模拟器。

核心能力

• 列出全部指南：调用 action="list" 可拿到当前打包好的 60 个 SKILL 概览（id + 名称 + 一句话简介）
• 按关键词搜索：调用 action="search" 并给一个自然语言 query（最长 256 字符），按词频打分排序，返回最相关的若干条
• 按 id 或 query 读全文：调用 action="get"，传入精确 id（如 algorithms/linear-systems/hhl）或自然语言 query，返回该 SKILL 的 markdown 内容
• 渐进式内容裁剪：默认只返回"目的/前置/选型/常见误解"等关键小节以省 token，需要时再请求 detail="full" 获取完整内容
• 覆盖十大算法领域：基础量子算法、线性系统、密码学、哈密顿模拟、Schrodingerization、本征求解器、梯度方法、量子机器学习、态制备、量子纠错
• 覆盖三种量子模拟器：UnitaryLab（推荐默认）、Qiskit、PennyLane 的选型与安装指引

技术实现

• 语言: TypeScript（ESM 模块），构建产物输出到 lib/
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-tools（均为 peerDependencies），无运行时第三方依赖
• 架构模式: Profile Bundle 注入——通过 cordis.patch.yml 往宿主 profile 插入 tool-quantum-practices 行，再由 src/index.ts 在 apply(ctx) 里用 ctx.tools.register(defineTool(...)) 把名为 quantum_practices 的工具挂到宿主
• 入口文件: src/index.ts（编译后对应 lib/index.js），工具调用核心在 src/skill-store.ts
• 数据来源: 构建时由 scripts/generate-skill-catalog.mjs 扫描仓库下所有 SKILL.md，嵌入到 skill-catalog.ts 一起发布，运行期不可改

适用场景

DSH 用户在做量子算法相关的对话或代码生成时（比如请教 HHL 对矩阵 A 的约束、Trotter 与 QDrift 的差别、变分算法该用哪个模拟器），希望 Agent 先查一份权威的内部手册再回答，而不是凭通用知识随便猜。教学、写代码、code review、PDE 量子化工作流都适用。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:unitarylab/quantum-practices

配置项

本插件无需额外配置。安装后重启 profile 即可生效，工具注册由 cordis.patch.yml 自动完成。

常见问题

Q: 安装后需要重启 DSH 才能用吗？

A: 需要。package.json 的 dshWorkshop.lifecycle.activation 声明为 restart-profile，安装后必须重启对应 profile（Web/headless）才会注册 quantum_practices 工具。

Q: 这个插件会执行 Python 代码吗？

A: 不会。dshWorkshop.permissions 明确声明 python:none、subprocess:none、shell:none 和 filesystem:none，algorithms/**/scripts/*.py 只是给阅读参考，运行时不会调用。

Q: 用 get 时为什么默认只返回简短内容？

A: 默认 detail 为 brief，工具只会从 SKILL.md 中挑出"目的/前置/常见误解/选型"等小节以省 token；只有当你确实需要完整实现代码或示例时，模型才应该请求 detail="full"。

Q: 我可以自己加新的算法文档吗？

A: 可以但要重新构建。运行 npm run build 会扫描仓库里所有 SKILL.md 并重新生成 src/generated/skill-catalog.ts；直接编辑该文件无效，会被覆盖。

Q: 安装后如何验证它真的注册了？

A: 运行 dsh --profile headless --dump-config | rg "tool-quantum-practices|dsh-unitarylab-quantum-practices"，输出中应出现一行 id: tool-quantum-practices。

Q: 这个插件和 unitarylab 的 Python 包是什么关系？

A: 这是基于 unitarylab/quantum-skills 语料改编的 DSH 工具包，本身不发布 Python 包也不内置运行时。Python 环境属于另起的运行环境，与本插件安装路径无关。

Q: 工具超时了怎么办？

A: 工具设置了 1000ms 超时（src/index.ts:51）。若返回超时，多半是查询特别长或者 60 条索引还没加载完；可缩短 query 或把 limit 调小再试。

Q: 调用 get 时 id 参数从哪来？

A: id 形如 algorithms/linear-systems/hhl。可先用 action="search" 或 "list" 拿到，再用 id 精确读取；按工具 description 的指示，模型不应让用户手动提供 id。

上手难度

入门 — 装上即用、不需要写配置、不需要 Python 环境，普通用户只需在 DSH 里正常提问量子算法相关问题即可。

已知问题与限制

• 输出截断：skill-store.ts:409-416 会在 brief 模式超过 12,000 字符或 full 模式超过 40,000 字符时硬截断，长文档需要 detail="full" 才能拿全
• 工具单次调用超时 1 秒（src/index.ts:51 的 timeoutMs: 1000），冷启动或首次全表扫描可能贴边
• dshWorkshop.lifecycle.dispose 标记为 unknown，卸载生命周期尚无独立证据
• 仓库内禁止 root requirements.txt、.whl 等制品（scripts/verify-package.mjs:111-126 会拒绝通过），因此任何 Python 依赖必须放在外部项目里
• 工具运行时无网络/无写盘，模型若需要回写或调用外部 API，得另装其他插件，不能指望这个

---

English

What is this?

Quantum-Practices is a DeepSeek Harness tool bundle for quantum algorithm best practices. It provides structured, reviewable guidance to DeepSeek Harness agents through a read-only model-facing tool.

As a DeepSeek Harness plugin, it registers one read-only quantum_practices tool for listing, searching, and reading packaged quantum algorithm practice guides from an immutable build-time catalog.

Quantum-Practices is based on and adapted from the GitHub project unitarylab/quantum-skills. The original project provides the quantum algorithm guide corpus; this repository reworks that foundation into a DeepSeek Harness tool bundle with a generated, read-only practice catalog.

---

✨ Key Features

• Progressive Disclosure — Root SKILL.md is lightweight; algorithm and simulator guides load only when needed.
• DeepSeek Harness Tool Bundle — quantum_practices exposes list, search, and get without executing code.
• Read-Only Runtime — No network, subprocess, filesystem writes, Python execution, credentials, or native code.
• Best-Practice Coverage — Primitives, linear systems, cryptography, Hamiltonian simulation, Schrodingerization, eigensolvers, gradients, quantum machine learning, state preparation, and quantum error correction.
• Multi-Simulator Support — UnitaryLab (recommended), Qiskit, and PennyLane, with clear selection rules.
• GitHub-Sourced Corpus — Practice guides are synchronized from the public GitHub upstream only.
• Education-Friendly — Suitable for concept explanation, circuit design, code review, and hands-on demos.

---

🌟 Algorithms Covered

---

💻 Supported Simulators

---

📁 Repository Structure

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 Plugin

For most users, install Quantum-Practices into the DeepSeek Harness profile you use, then ask your agent to consult Quantum-Practices before answering quantum algorithm questions.

If you use the Web UI:

npx @deepseek-ai/[email protected] plugin --profile web add \
  github:unitarylab/quantum-practices#main

Restart DeepSeek Harness Web after installation.

If you use the headless CLI:

npx @deepseek-ai/[email protected] plugin --profile headless add \
  github:unitarylab/quantum-practices#main

For local development, install this checkout directly:

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

For review or release evidence, replace main with a pinned 40-character commit SHA.

Verify that the profile contains the inserted row:

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

Expected output:

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

Run a functional test:

npx @deepseek-ai/[email protected] --profile headless \
  "Use the quantum_practices tool to find the HHL practice guide and explain the required matrix constraints."

After installation, users can ask naturally. The model should call quantum_practices in the background:

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.

By default, get returns a brief, token-conscious view with the most relevant sections. The model should request detail="full" only when the user needs full implementation notes, complete examples, or debugging context.

Developers can also inspect the tool contract directly:

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")

The DSH plugin never executes algorithms/**/scripts/*.py and never installs or imports Python dependencies.

---

Build and Verify

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

npm run build regenerates src/generated/skill-catalog.ts and compiles the committed lib/ release artifact.

---

Python Runtime

Quantum-Practices does not ship a root requirements.txt, bundled wheels, or a Python runtime. Any Python setup belongs to the separate project where you choose to run generated examples; it is not part of the DeepSeek Harness plugin install path.

License

This repository source is licensed under the MIT License.

Attribution

Quantum-Practices is a derivative adaptation of unitarylab/quantum-skills. See NOTICE for attribution details.

---

中文

这是什么？

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 上游同步。
• 教学友好 — 适用于概念解释、电路设计、代码审查和动手实验。

---

🌟 算法覆盖范围

---

💻 支持的模拟器

---

📁 仓库结构

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：

npx @deepseek-ai/[email protected] plugin --profile web add \
  github:unitarylab/quantum-practices#main

安装后重启 DeepSeek Harness Web。

如果你使用 headless CLI：

npx @deepseek-ai/[email protected] plugin --profile headless add \
  github:unitarylab/quantum-practices#main

本地开发时，可以直接安装当前 checkout：

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：

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/[email protected] --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。