UnifiedQuantum Skill
当用户在使用当前 UnifiedQuantum 的公开 API、CLI 或示例时，使用这个 skill。
默认处理思路
优先采用当前的高层工作流：
- 用
uniqc.circuit_builder.Circuit构建线路 - 导出
circuit.originir或circuit.qasm - 用
uniqcCLI 或uniqc.task_manager执行 - 只为确实需要的功能安装额外 extras
当用户给的是一段 QASM 线路时，更稳妥的处理路径通常是：
- 先用
uniqc circuit转成 OriginIR - 再对这份归一化后的 OriginIR 做模拟或提交
这样可以减少不同输入路径带来的行为差异。
环境与安装处理
- 不要默认用户已经先决定好如何安装
unified-quantum，也不要默认用户已经选好了 CLI 入口。 - 先检查用户环境里已经有什么：解释器、已安装包、模块路径、CLI 是否可用，以及相关 extras 是否存在。
- 需要安装时，不要直接替用户决定安装路径。先给出简短可选项，让用户选择，再执行。
- 决定安装方式前，先识别用户当前是在
venv、Conda、Pixi 还是系统 Python 中工作。 - 默认把安装选项整理成 2 到 3 个最相关方案，并说明各自取舍；推荐项放第一，但不要静默直接执行。
- 常见可选项：
uv tool install：适合偏 CLI 的隔离安装，命令可跨目录直接使用。uv venv或普通venv：适合项目内或 Python API 场景，依赖与仓库隔离。- 当前已激活环境里的
pip install：适合用户明确希望复用现有venv、Conda 或 Pixi 环境。
- 如果用户已经在 Pixi 生态里工作，
pixi global也是可接受的选项，但通常只在用户明确偏好 Pixi 时再列出。 - 如果当前环境是已激活的 Conda 环境，默认不要直接改它。把“装进当前 Conda 环境”作为一个可选项交给用户决定。
- 如果唯一可写目标是系统 Python，安装前必须明确征求用户同意。
- 如果用户没有明确偏好，再给出推荐：
- 偏 CLI：优先推荐
uv tool install - 偏 Python API / 示例：优先推荐
uv venv - 已在现有虚拟环境里工作：可推荐装进当前环境
- 偏 CLI：优先推荐
- 如果
uv不可用或不合适，再提供pip/venv方案作为替代。 - 只有在用户已经明确要求某种安装路径，或者当前会话上下文已经表达了稳定偏好时，才可以不再重复询问。
几个容易混淆但要记清的点
- 包名：
unified-quantum - CLI 名：
uniqc - 主 Python 包名：
uniqc - 配置文件：
~/.uniqc/uniqc.yml - 本地任务缓存：
~/.uniqc/cache/tasks.sqlite - 如果主题 reference 仍然解释不了问题，再回到 references/troubleshooting.md 做通用诊断。
依赖边界
不要默认基础安装就包含所有功能。
- 核心包：
pip install unified-quantum - 本地模拟 / dummy 模式常见需要：
pip install "unified-quantum[simulation]" - OriginQ 适配器：
pip install "unified-quantum[originq]" - Quafu 适配器：
pip install "unified-quantum[quafu]" - IBM 适配器：
pip install "unified-quantum[qiskit]" - PyTorch 辅助工具：
pip install "unified-quantum[pytorch]" - TorchQuantum 集成：
pip install "unified-quantum[torchquantum]"
如果用户提到 qutip、torch、qiskit、quafu 或 pyqpanda3 相关导入失败，先把它当成缺少可选依赖，而不是先判断核心包坏了。
CLI 指引
当前 CLI 主要分组有：
uniqc circuituniqc simulateuniqc submituniqc resultuniqc taskuniqc config
当用户要在 shell 里做格式转换、本地执行或云任务管理时，优先用 uniqc，不要先写临时辅助脚本。
当前有几个细节要特别注意：
uniqc submit使用--platform，并可选搭配--backend- 对 OriginQ，当前 CLI 选项是
--backend，不是旧的--chip-id - 对 Quafu，
chip_id在 Python API 中仍然相关，但当前 CLI 没有单独暴露--chip-id simulate最稳妥的输入仍是 OriginIR；如果手里是 QASM，先做归一化
Python API 指引
如果是编程式的任务工作流，优先使用：
from uniqc import submit_task, submit_batch, query_task, wait_for_result
构造 ansatz 时，优先使用当前公开导出：
from uniqc.algorithmics.ansatz import hea, qaoa_ansatz, uccsd_ansatz
不要再使用像 uccsd 这样的旧名字。
PyTorch 集成优先使用：
from uniqc.pytorch import (
QuantumLayer,
batch_execute,
batch_execute_with_params,
parameter_shift_gradient,
compute_all_gradients,
)
接下来读什么
- 线路构建与导出：references/circuit-building.md
- CLI 用法：references/cli-guide.md
- 本地模拟与 dummy 模式：references/simulators.md
- 配置、云端后端与任务缓存：references/cloud-platforms.md
- ansatz 与变分工作流：references/variational-algorithms.md
- PyTorch 辅助接口：references/pytorch-integration.md
- H2 风格的 VQE 任务：references/h2-molecular-simulation.md
- 主题检查之后仍然不清楚的通用排障：references/troubleshooting.md
回答启发式
- 如果用户想要一个快速起步，先从
Circuit -> originir -> uniqc开始。 - 如果用户卡在云端执行，先检查配置和后端特有 kwargs；如果仍然不清楚，再回到 references/troubleshooting.md。
- 如果用户问的是本地模拟失败，先检查
simulation相关依赖；必要时再回到 references/troubleshooting.md。 - 如果用户提到缺命令、缺导入、缺 extra、缺配置路径，或者文档与本地行为不一致，先拍安装快照，再判断是不是版本漂移导致，然后查同类 issue，最后再进入 references/troubleshooting.md 的完整通用排障流程。
- 如果需要安装，先用简短选项问清用户想装到哪里，再执行；不要直接替用户选安装路径。
- 如果用户想看现代的变分示例，优先从
hea、qaoa_ansatz或uccsd_ansatz开始，不要从旧 helper 名称起步。 - 如果用户想走 shell 工作流，优先给
uniqcCLI 方案，而不是自定义 wrapper。