cq-lib · Mrhhhhhhx · Jun 26, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,121 @@
+name: "\U0001F41B Bug Report / 缺陷报告"
+description: "Report a bug or unexpected behavior in cqlib / 报告 cqlib 的功能异常或错误"
+title: "[BUG] "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Thank you for reporting a bug! / 感谢你报告 Bug！**
+
+        Before submitting / 提交前请确认：
+        - Search [existing issues](https://github.com/cq-lib/cqlib/issues) to avoid duplicates / 已搜索[现有 Issue](https://github.com/cq-lib/cqlib/issues)，避免重复提交
+        - Security vulnerabilities → email <tianyan@chinatelecom.cn> (see [SECURITY.md](SECURITY.md)) / 安全漏洞请发送邮件至 <tianyan@chinatelecom.cn>（参考 [SECURITY.CN.md](SECURITY.CN.md)）
+
+  - type: input
+    id: version
+    attributes:
+      label: "cqlib version / cqlib 版本"
+      description: "Run `pip show cqlib` or check `cargo.toml` / 运行 `pip show cqlib` 或检查 `cargo.toml`"
+      placeholder: "e.g. 0.1.0, commit a1b2c3d"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: "Which component? / 涉及哪个组件？"
+      options:
+        - "cqlib-core (Rust core / Rust 核心库)"
+        - "binding-python (Python bindings / Python 绑定)"
+        - "binding-c (C bindings / C 绑定)"
+        - "cqlib (public Rust crate / Rust 对外 crate)"
+        - "Other / Not sure / 其他 / 不确定"
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: "Environment / 运行环境"
+      description: "OS, architecture, Rust version, Python version / 操作系统、CPU 架构、Rust 版本、Python 版本"
+      placeholder: |
+        - OS / 操作系统：Ubuntu 22.04 / macOS 14 / Windows 11
+        - Architecture / CPU 架构：x86_64 / ARM64
+        - Rust：1.85.0
+        - Python：3.12.0
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: "Steps to reproduce / 复现步骤"
+      description: "Minimal code to reproduce the bug / 提供最小复现代码"
+      placeholder: |
+        **Python：**
+        ```python
+        from cqlib import Circuit
+        qc = Circuit(2)
+        qc.h(0)
+        qc.cx(0, 1)
+        # bug happens here / 此处出现 Bug
+        ```
+
+        **Rust：**
+        ```rust
+        use cqlib_core::circuit::{Circuit, Qubit};
+        let mut qc = Circuit::new(2);
+        // bug happens here / 此处出现 Bug
+        ```
+
+        **C：**
+        ```c
+        #include <cqlib/circuit.h>
+        cqlib_circuit_t *qc = cqlib_circuit_new(2);
+        // bug happens here / 此处出现 Bug
+        ```
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: "Expected behavior / 期望行为"
+      placeholder: "What did you expect to happen? / 你期望发生什么？"
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: "Actual behavior / 实际行为"
+      placeholder: "What actually happened? Include full error messages, logs, or stack traces. / 实际发生了什么？请附上完整的错误信息、日志或堆栈跟踪。"
+      render: text
+    validations:
+      required: true
+
+  - type: textarea
+    id: quantum_context
+    attributes:
+      label: "Quantum-specific context (if applicable) / 量子计算相关上下文（如适用）"
+      description: "For issues related to simulation, noise, or numerical computation / 如果问题涉及模拟、噪声或数值计算，请补充以下信息"
+      placeholder: |
+        - Input circuit / gates / 输入线路 / 量子门
+        - Parameters used (theta, random seed, etc.) / 使用的参数（theta、随机种子等）
+        - Simulator / backend configuration / 模拟器 / 后端配置
+        - Noise model parameters / 噪声模型参数
+        - Expected vs actual tolerance / precision / 预期与实际误差范围 / 精度
+      render: markdown
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: "Additional context / 补充信息"
+      placeholder: "Screenshots, related issues, workarounds tried, etc. / 截图、相关 Issue、尝试过的解决方案等"
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: "\uD83D\uDCAC Ask a question in Discussions"
+    url: https://github.com/cq-lib/cqlib/discussions
+    about: "Please use Discussions for general questions and community conversation"
+  - name: "\uD83D\uDCD6 Read the documentation"
+    url: https://qc.zdxlz.com/
+    about: "Check the official cqlib documentation before opening an issue"
+  - name: "\u270D\uFE0F Contribution guide (\u4E2D\u6587)"
+    url: https://github.com/cq-lib/cqlib/blob/main/CONTRIBUTING.CN.md
+    about: "Read the contributing guide before submitting code"
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,85 @@
+name: "\U0001F680 Feature Request / 功能建议"
+description: "Suggest a new feature or enhancement for cqlib / 为 cqlib 提出新功能或改进建议"
+title: "[FEATURE] "
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Thank you for suggesting a feature! / 感谢你提出功能建议！**
+
+        Before proceeding / 提交前请确认：
+        - Search [existing issues](https://github.com/cq-lib/cqlib/issues) to check if this has already been proposed / 已搜索[现有 Issue](https://github.com/cq-lib/cqlib/issues)，确认未被提出过
+        - Major API changes should be discussed in an Issue first (see [CONTRIBUTING.md](CONTRIBUTING.md)) / 涉及重大 API 变更的建议，请先提 Issue 讨论方案（参考 [CONTRIBUTING.CN.md](CONTRIBUTING.CN.md)）
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: "Problem statement / 问题描述"
+      description: "What problem does this feature solve? Describe your use case. / 这个功能解决什么问题？描述你的使用场景。"
+      placeholder: "E.g., I want to run VQE on custom Hamiltonians but the current API requires... / 例如：我想用 VQE 求解自定义哈密顿量，但当前 API 无法直接传入..."
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: "Which area does this affect? / 涉及的功能模块（可多选）"
+      multiple: true
+      options:
+        - "Circuit Construction / 量子线路构建（线路构造 / 参数化）"
+        - "Intermediate Representation / 中间表示（IR / 优化）"
+        - "Compiler Passes / 编译优化（门分解 / 路由 / 调度）"
+        - "Device Model / 设备模型（校准数据 / 拓扑 / 噪声）"
+        - "Simulation / 量子态模拟（态矢量 / 噪声模型）"
+        - "Error Mitigation / 误差缓解（ZNE / Virtual Distillation）"
+        - "Visualization / 可视化（线路图 / 结果图）"
+        - "Python Bindings / Python 绑定"
+        - "C Bindings / C 绑定"
+        - "Documentation / Examples / 文档 / 示例"
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: "Proposed solution / 方案建议"
+      description: "Describe what you would like to see. Code snippets or pseudo-code are welcome. / 描述你期望的功能。欢迎附上代码片段或伪代码。"
+      placeholder: |
+        ```python
+        # Example of how the API might look / 期望的 API 示例
+        from cqlib import Circuit, VQE
+
+        qc = Circuit(4)
+        ...
+        result = VQE(qc, hamiltonian).run()
+        ```
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: "Alternatives considered / 替代方案"
+      description: "What workarounds have you tried? Are there existing libraries that solve this? / 你尝试过哪些替代方案？是否有其他库已经实现了类似功能？"
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: "Scope check / 范围确认"
+      options:
+        - label: "This is within cqlib's scope (quantum computing SDK: circuits, IR, compilation, simulation, error mitigation) / 该功能属于 cqlib 的项目范围（量子计算 SDK：线路、IR、编译、模拟、误差缓解）"
+          required: false
+        - label: "I am willing to contribute a PR for this feature / 我愿意为这个功能提交 PR"
+          required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: "Additional context / 补充信息"
+      placeholder: "References, papers, similar features in other frameworks (Qiskit, Cirq, PennyLane, etc.) / 参考文献、论文、其他框架的类似功能（Qiskit、Cirq、PennyLane 等）"
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml
@@ -0,0 +1,60 @@
+name: "\u2753 Question / 使用咨询"
+description: "Ask a question about using cqlib / 提出关于 cqlib 的使用问题"
+title: "[QUESTION] "
+labels: ["question", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Welcome! / 欢迎提问！** This template is for usage questions, troubleshooting help, and general inquiries. / 本模板用于使用问题、故障排查和一般咨询。
+
+        Before asking / 提问前请先：
+        - Check the [README](README.md) and [documentation](https://qc.zdxlz.com/) / 查阅 [README.CN.md](README.CN.md) 和[技术文档](https://qc.zdxlz.com/)
+        - Search [existing questions](https://github.com/cq-lib/cqlib/issues?q=label%3Aquestion) / 搜索[已有问题](https://github.com/cq-lib/cqlib/issues?q=label%3Aquestion)
+
+  - type: dropdown
+    id: topic
+    attributes:
+      label: "What is your question about? / 你的问题属于哪类？"
+      options:
+        - "Installation / Build / 安装 / 构建"
+        - "API Usage / API 使用"
+        - "Quantum Computing Theory / 量子计算理论"
+        - "Performance / Optimization / 性能 / 优化"
+        - "Documentation / 文档问题"
+        - "Other / 其他"
+    validations:
+      required: true
+
+  - type: textarea
+    id: question
+    attributes:
+      label: "Your question / 你的问题"
+      description: "Describe what you are trying to do and what you need help with. / 描述你在做什么、遇到了什么困难。"
+      placeholder: |
+        I am trying to... / 我正在尝试...
+        I have read / tried... / 我已经阅读 / 尝试了...
+        I expected..., but got... / 我期望...，但实际上...
+    validations:
+      required: true
+
+  - type: textarea
+    id: code
+    attributes:
+      label: "Relevant code (if applicable) / 相关代码（如有）"
+      description: "Paste the code or circuit you are working with. / 贴出你正在使用的代码或线路。"
+      render: markdown
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: "Environment / 运行环境"
+      description: "If relevant: cqlib version, OS, Python/Rust version / 如有需要：cqlib 版本、操作系统、Python / Rust 版本"
+      placeholder: |
+        - cqlib version / 版本：0.1.0
+        - Python：3.12.0
+        - OS / 操作系统：Ubuntu 22.04
+    validations:
+      required: false
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,58 @@
+## Description / 变更说明
+
+<!-- Describe what this PR does and why. / 说明这个 PR 做了什么变更以及为什么。 -->
+
+## Related Issues / 关联 Issue
+
+<!-- Link related issues: Closes #123, Related to #456 / 关联的 Issue 编号 -->
+
+## Changes / 具体改动
+
+<!-- List key changes / 列出主要改动点 -->
+-
+
+## Component Impact / 影响范围
+
+<!-- Check affected components / 勾选涉及的组件 -->
+- [ ] `cqlib-core` (Rust core / 核心库)
+- [ ] `binding-python` (Python bindings / Python 绑定)
+- [ ] `binding-c` (C bindings / C 绑定)
+- [ ] `cqlib` (public Rust crate / 对外 crate)
+- [ ] Documentation / 文档
+- [ ] CI / Build / 构建系统
+
+## Testing / 测试
+
+<!-- Describe how you tested your changes / 说明你是如何测试这些改动的 -->
+
+### Commands run / 运行的测试命令
+
+```bash
+# Rust tests
+cargo test --all
+cargo test -p cqlib-core
+cargo test -p binding-c
+
+# Python tests
+maturin develop -m crates/binding-python/Cargo.toml
+pytest tests/python/
+```
+
+### Test results / 测试结果
+
+<!-- Paste test output or describe results / 贴出测试结果或描述大致情况 -->
+
+## Checklist / 检查清单
+
+- [ ] My change is based on the latest `main` branch / 改动基于最新 `main` 分支
+- [ ] I have read the [Contributing Guide](CONTRIBUTING.md) / 已阅读贡献指南
+- [ ] Code style checks pass (`cargo fmt`, `cargo clippy`, `ruff check`) / 代码风格检查通过
+- [ ] I have added tests that prove my fix/feature works / 已添加测试验证
+- [ ] New and existing tests pass locally / 新旧测试全部通过
+- [ ] I have updated documentation as needed / 已更新相关文档
+- [ ] No unrelated files, debug code, or temporary output / 无无关文件或调试代码
+- [ ] Commit messages follow [conventional format](https://www.conventionalcommits.org/) / 提交信息遵循规范格式
+
+## Notes for Reviewers / 评审提示
+
+<!-- Anything reviewers should pay attention to / 需要评审者关注的点 -->