QCoder-chat · 量子编程小助手

中文： QCoder-chat 是面向量子编程的 VS Code 扩展：在侧栏用大模型完成量子概念讲解、电路与算法构思、生成 OpenQASM 2、Qiskit、QPanda 等多种量子代码，并提供文档式回答；通过 RAG 知识增强 提升领域专业性，结合 Agent 模式 强化工具使用能力；可与 QCoder-compiler 插件无缝协同，在同一工作区内编译、模拟电路，并顺畅接入 QLLVM 编译器，形成从代码生成到编译运行的完整闭环。

English: QCoder-chat is a VS Code extension for quantum programming: use the sidebar chat for quantum concepts explanation, circuit and algorithm design, generate OpenQASM 2, Qiskit, QPanda and other quantum code, and provide documentation-style answers; enhance domain expertise through RAG knowledge augmentation, strengthen tool usage capabilities with Agent mode; seamlessly collaborate with QCoder-compiler plugin to compile and simulate circuits in the same workspace, and smoothly integrate with QLLVM compiler, forming a complete closed-loop from code generation to compilation and execution.

中文 | English

中文

产品定位

QCoder-chat 将量子编程对话固定在写代码的同一侧栏：用大模型解释概念、推演算法与电路、生成 OpenQASM 2、Qiskit、QPanda 等多种量子代码，并配合本地 Markdown、LaTeX（KaTeX）、代码高亮 呈现。通过 RAG 知识增强 提供专业、准确的量子计算领域知识，结合 Agent 模式 强化工具使用能力。扩展面向「学—写—跑」全链路：先在 QCoder-chat 里把思路与代码落到文件，再通过 QCoder-compiler 插件 对同一工作区内的电路文件执行编译与模拟，其中QLLVM 编译器可作为默认或并行编译器之一，形成从生成到工具链落地的闭环。

能力架构总览

下图从用户视角概括各模块如何协作。

flowchart LR
  subgraph editor["VS Code 工作区"]
    QCoder-chat["QCoder-chat 侧栏聊天"]
    Files[".qasm / .py 等电路文件"]
  end
  subgraph toolchain["工具链层"]
    CompilePlugin["QCoder-compiler 插件"]
    QLLVM["QLLVM 编译器"]
    Other["其他编译器可选"]
  end
  QCoder-chat -->|"插入代码 / 复制"| Files
  Files --> CompilePlugin
  CompilePlugin --> QLLVM
  CompilePlugin --> Other

为何这样分层：对话与编辑在 QCoder-chat 内完成，避免在浏览器与 IDE 间切换；编译与后端适配由 QCoder-compiler 插件处理，避免在聊天扩展里重复实现整条 MLIR/LLVM 流水线，同时让 QLLVM 与既有工作流一致。

核心功能详解

界面与交互要点

下列能力对应插件内真实 UI，按「界面 → 行为」分条列出，便于首次安装后逐项对照。

1. 侧栏聊天 vs 编辑器旁面板

   • 默认从活动栏 QCoder-chat 打开侧栏聊天，与资源管理器同列。
   • 命令 与量子编程小助手聊天（qcoder.chatWithQwen）会在编辑器区域旁打开独立面板，便于与源码左右对照阅读与插入代码。
   • 命令面板中的 新建聊天 / 历史记录 / 设置 / 快速开始 等会向已打开的侧栏聊天视图发送消息；若你仅使用编辑器旁面板，请优先使用该面板或侧栏界面上的按钮完成对应操作。

2. 快速开始向导
   侧栏标题栏的 快速开始 会启动多步引导：依次说明 QLLVM 安装路径、问题输入框、模型选择、深度思考、在线服务、以及标题栏的 历史 / 新建聊天 / 设置。可跳过、上一步/下一步，适合首次安装后走一遍。

3. 空会话快捷开场
   尚无消息时，聊天区提供多条预设开场问题（如自我介绍、OpenQASM 示例、多前端多后端编译等），一键填入输入框，降低冷启动成本。

4. 输入与发送
   在输入框内：Enter 发送，Shift+Enter 换行（与常见聊天工具一致）。

5. 深度思考模式
   工具栏中可勾选 深度思考模式；开启后，模型倾向于输出更细的推理过程（具体行为因模型与后端而异）。若返回推理内容，会在气泡中以 「深度思考」 区块展示，再跟正式回答。

6. 在线服务开关
   与 RAG 知识增强（见下节）联动：在界面中开关「在线服务」，用于在纯模型与检索增强策略间切换（含义见该节，此处不展开实现细节）。

7. 历史与新建
   历史记录打开侧滑列表，可选中会话载入；新建聊天清空当前对话区，已保存条目仍保留在列表中直至你覆盖或清理。

8. 设置侧栏
   在设置中管理 API Key、自定义模型、界面语言、从选择器隐藏的模型等；内置三条 SCNet 模型在表格中展示，与自定义条目区分。

[!TIP] 使用 Ctrl+Shift+P（macOS：Cmd+Shift+P）打开命令面板，输入 QCoder-chat 或 与量子编程小助手聊天，可在编辑器旁打开聊天面板，与电路文件并排编辑，尤其适合从助手复制/插入代码后立即保存并用 QCoder-compiler 插件编译。

与 QCoder-compiler 插件和 QLLVM 编译器协同

设计意图：QCoder-chat 负责「生成与说明」，QCoder-compiler 插件负责「编译与运行」； QLLVM 编译器通过 QCoder-compiler 插件的多编译器能力接入，与商业或开源编译器并行或作为默认，无需在 QCoder-chat 内重复实现编译器 UI。

推荐闭环（生成 → 编译 → 运行）

┌─────────────────────┐     插入 / 保存      ┌──────────────────────┐
│  QCoder-chat 侧栏聊天     │ ──────────────────▶ │  工作区电路源文件       │
│  需求 · 代码 · 解释   │                     │  .qasm / .py 等       │
└─────────────────────┘                     └───────────┬────────────┘
                                                        │
                        「编译当前量子电路文件」            ▼
                                            ┌──────────────────────┐
                                            │ QCoder-compiler 插件   │
                                            ├──────────┬───────────┤
                                            │ QLLVM    │ 其他编译器  │
                                            │ (默认)    │ (可选)     │
                                            └──────────┴───────────┘

1. QCoder-chat：用自然语言描述电路或算法，获得 OpenQASM、Qiskit、QPanda 等形式输出，通过「插入代码」或复制写入工作区。
2. QCoder-compiler 插件：执行 编译当前量子电路文件，按你的配置调用一个或多个编译器。
3. QLLVM：在 QCoder-compiler 插件中将 QLLVM 设为默认或并行编译器之一即可接入；其基于 MLIR / LLVM IR 流水线，支持多种量子编程语言（Qiskit、Criq、Qpanda、OpenQASM），经优化与映射后可输出多种量子后端所需格式（qasm模拟器、本源OriginIR、天衍qcis），并可在 QCoder-compiler 插件内配合 QIR 模拟器 做测量统计。

QLLVM 架构、安装与 QCoder-compiler 插件多编译器配置等专题说明，见 GitHub 上仓库内 help 目录（示例：https://github.com/QCFlow；发布时请替换为组织实际仓库地址）。

RAG 知识增强

在聊天设置中可开关与 RAG 相关的在线服务选项。下面两点说明其作用方式（不涉及后端实现细节）：

1. 领域一致性：开启后，助手在回答前会结合量子计算相关知识库中与当前问题相关的材料，再与用户问题一并交给大模型生成回复，使输出更贴近教材、论文与工程表述，减少泛泛而谈的通用描述。
2. 与纯模型推理的切换：关闭该选项时，仅依赖大模型自身的知识与推理，对话与代码生成仍可正常使用；你可以按任务类型在「深度检索增强」与「轻量纯推理」之间切换，无需改动项目代码结构。

内置大模型与免费使用

扩展内置三条 SCNet 官方大模型，在模型选择器中直接选用即可：

上述三条模型使用扩展内嵌的 SCNet 访问凭据，无需在设置中填写 qcoder.scnetApiKey，也无需为这三条模型单独申请密钥，即可在合规使用前提下免费使用内置通道进行量子编程对话与代码生成。

若你在设置中自行添加其他 SCNet 自定义模型，则需配置 qcoder.scnetApiKey（命令：设置 QCoder-chat SCNet API Key）。使用**阿里云百炼（Qwen）**或 DeepSeek 时，仍需在扩展中配置各自的 qcoder.qwenApiKey / qcoder.deepseekApiKey。

快速开始

1. 安装：命令面板执行 Extensions: Install from VSIX... 选择 qcoder-chat-*.vsix，或从扩展市场安装。
2. 安装配套插件：安装 QCoder-compiler 插件，以支持完整的编译和运行流程。
3. 配置 QLLVM：按照 GitHub 上 help 目录的说明安装并配置 QLLVM 编译器，确保其能被 QCoder-compiler 插件识别。
4. 选模型：优先在模型列表中选择上述三条内置 SCNet 模型之一即可零密钥开始；若使用其他云服务商模型，再按需配置对应 API Key。
5. 打开聊天：活动栏点击 QCODER-chat（侧栏）；或命令 与量子编程小助手聊天 在编辑器旁打开面板（交互细节见上文「界面与交互要点」）。
6. 生成与编译：在 QCoder-chat 中生成电路文件，保存后使用 QCoder-compiler 插件编译并运行模拟。
7. Agent 自动流程：启用 Agent 模式，可自动完成从代码生成、QLLVM 编译到运行模拟的全流程，无需手动切换工具，提升开发效率。

常用命令与设置

常用命令

主要设置（qcoder.*）

如何阅读本文档

若你在 VS Code 资源管理器中打开本 README，可用 Ctrl+Shift+V（macOS：Cmd+Shift+V）预览 Markdown；侧边预览可用 Ctrl+K V。文中的 Mermaid 流程图在 GitHub 网页上通常可直接渲染；本地若需一致效果，可使用支持 Mermaid 的预览扩展。扩展上架后，市场详情页可放短摘要，完整说明以 GitHub 上本仓库首页与 help 目录为准（https://github.com/QCFlow）。

项目结构（概要）

开发与构建

npm install
npm run compile
npm run watch
npm run package
npm run lint
npm run test

使用 Run and Debug 启动 Extension Development Host 调试本扩展。

许可证

MIT。许可证全文见：https://github.com/QCFlow。

English

English

Product Positioning

QCoder-chat places quantum programming dialogue in the same sidebar as your code: use large models to explain concepts, derive algorithms and circuits, generate various quantum code such as OpenQASM 2, Qiskit, QPanda, etc., and present it with local Markdown, LaTeX (KaTeX), and code highlighting. Provide professional and accurate quantum computing domain knowledge through RAG knowledge augmentation, and strengthen tool usage capabilities with Agent mode. The extension covers the full "learn-write-run" workflow: first refine your ideas and code in QCoder-chat, then execute compilation and simulation on circuit files in the same workspace through the QCoder-compiler plugin, where the QLLVM compiler can be used as one of the default or parallel compilers, forming a closed loop from generation to toolchain implementation.

Capability Architecture Overview

The diagram below summarizes how each module collaborates from the user's perspective.

flowchart LR
  subgraph editor["VS Code Workspace"]
    QCoderChat["QCoder-chat Sidebar Chat"]
    Files[".qasm / .py and other circuit files"]
  end
  subgraph toolchain["Toolchain Layer"]
    CompilePlugin["QCoder-compiler Plugin"]
    QLLVM["QLLVM Compiler"]
    Other["Other compilers (optional)"]
  end
  QCoderChat -->|"Insert code / Copy"| Files
  Files --> CompilePlugin
  CompilePlugin --> QLLVM
  CompilePlugin --> Other

Why this layering: Dialogue and editing are completed within QCoder-chat, avoiding switching between browser and IDE; compilation and backend adaptation are handled by the QCoder-compiler plugin, avoiding redundant implementation of the entire MLIR/LLVM pipeline in the chat extension, while keeping QLLVM consistent with existing workflows.

Core Features Details

Interface and Interaction Points

The following capabilities correspond to the actual UI in the plugin, listed by "interface → behavior" to facilitate item-by-item comparison after first installation.

1. Sidebar Chat vs. Editor Side Panel

   • By default, open sidebar chat from the activity bar QCODER-chat Sidebar Chat, in the same column as the explorer.
   • The command Chat with Quantum Programming Assistant (qcoder.chatWithQwen) will open an independent panel next to the editor area, facilitating left-right comparison reading and code insertion with source code.
   • Commands in the command palette such as New Chat / History / Settings / Quick Start will send messages to the already opened sidebar chat view; if you only use the editor side panel, please prioritize using that panel or the buttons on the sidebar interface to complete corresponding operations.

2. Quick Start Wizard
   The Quick Start in the sidebar title bar will start a multi-step guide: sequentially explaining QLLVM installation path, question input box, model selection, deep thinking, online services, and the History / New Chat / Settings in the title bar. Can skip, go back/next, suitable for walking through after first installation.

3. Empty Session Quick Start
   When there are no messages, the chat area provides multiple preset opening questions (such as self-introduction, OpenQASM examples, multi-frontend multi-backend compilation, etc.), one-click filling into the input box, reducing cold start costs.

4. Input and Send
   In the input box: Enter to send, Shift+Enter to wrap (consistent with common chat tools).

5. Deep Thinking Mode
   Can check Deep Thinking Mode in the toolbar; when enabled, the model tends to output more detailed reasoning processes (specific behavior varies by model and backend). If reasoning content is returned, it will be displayed in the bubble as a "Deep Thinking" block, followed by the formal answer.

6. Online Service Switch
   Linked with RAG Knowledge Augmentation (see next section): toggle "Online Services" in the interface to switch between pure model and retrieval augmentation strategies (meaning see that section, implementation details not expanded here).

7. History and New
   History opens a side slide list, can select sessions to load; New Chat clears the current dialogue area, saved entries remain in the list until you overwrite or clean them.

8. Settings Sidebar
   Manage API Key, custom models, interface language, models hidden from selector, etc. in settings; three built-in SCNet models are displayed in the table, distinguished from custom entries.

[!TIP] Use Ctrl+Shift+P (macOS: Cmd+Shift+P) to open the command palette, enter QCoder-chat or Chat with Quantum Programming Assistant, to open the chat panel next to the editor, editing side by side with circuit files, especially suitable for immediately saving after copying/inserting code from the assistant and compiling with the QCoder-compiler plugin.

Collaboration with QCoder-compiler Plugin and QLLVM Compiler

Design Intent: QCoder-chat is responsible for "generation and explanation", QCoder-compiler plugin is responsible for "compilation and execution"; QLLVM compiler is accessed through the multi-compiler capability of the QCoder-compiler plugin, running in parallel with commercial or open-source compilers or as default, without the need to repeatedly implement compiler UI in QCoder-chat.

Recommended Closed Loop (Generate → Compile → Run)

┌─────────────────────┐     Insert / Save      ┌──────────────────────┐
│  QCoder-chat Sidebar Chat │ ──────────────────▶ │  Workspace Circuit Files │
│  Requirements · Code · Explanations │                     │  .qasm / .py etc.     │
└─────────────────────┘                     └───────────┬────────────┘
                                                        │
                        "Compile Current Quantum Circuit File"            ▼
                                            ┌──────────────────────┐
                                            │ QCoder-compiler Plugin │
                                            ├──────────┬───────────┤
                                            │ QLLVM    │ Other Compilers │
                                            │ (Default) │ (Optional)     │
                                            └──────────┴───────────┘

1. QCoder-chat: Describe circuits or algorithms in natural language, obtain output in forms such as OpenQASM, Qiskit, QPanda, etc., and write to the workspace through "Insert Code" or copy.
2. QCoder-compiler Plugin: Execute Compile Current Quantum Circuit File, call one or more compilers according to your configuration.
3. QLLVM: Set QLLVM as one of the default or parallel compilers in the QCoder-compiler plugin to access it; it is based on MLIR / LLVM IR pipeline, supports multiple quantum programming languages (Qiskit, Criq, Qpanda, OpenQASM), and after optimization and mapping, can output formats required by multiple quantum backends (qasm simulator, Origin OriginIR, Tianyan qcis), and can work with QIR simulator in the QCoder-compiler plugin for measurement statistics.

QLLVM architecture, installation, and multi-compiler configuration for QCoder-compiler plugin are described in the help directory in the GitHub repository (example: https://github.com/QCFlow; please replace with the actual organization repository address when publishing).

RAG Knowledge Augmentation

You can toggle the Online Services option related to RAG in chat settings. The following two points explain how it works (excluding backend implementation details):

1. Domain Consistency: When enabled, the assistant will combine materials related to the current question from the quantum computing-related knowledge base before answering, and then submit them together with the user's question to the large model to generate a response, making the output closer to textbook, paper, and engineering expressions, reducing general descriptions.
2. Switching between Pure Model Reasoning: When this option is disabled, it only relies on the model's own knowledge and reasoning, and dialogue and code generation can still be used normally; you can switch between "deep retrieval augmentation" and "lightweight pure reasoning" according to task type without changing the project code structure.

Built-in Large Models and Free Usage

The extension includes three built-in SCNet official models, which can be directly selected in the model selector:

The above three models use the extension's embedded SCNet access credentials, no need to fill in qcoder.scnetApiKey in settings, and no need to apply for separate keys for these three models, allowing free use of the built-in channel for quantum programming dialogue and code generation under compliant usage conditions.

If you add other custom SCNet models in settings, you need to configure qcoder.scnetApiKey (command: Set QCoder-chat SCNet API Key). When using Alibaba Cloud Qwen or DeepSeek, you still need to configure their respective qcoder.qwenApiKey / qcoder.deepseekApiKey in the extension.

Quick Start

1. Installation: Execute Extensions: Install from VSIX... in the command palette, select qcoder-chat-*.vsix, or install from the extension marketplace.
2. Install Companion Plugin: Install the QCoder-compiler plugin to support the complete compilation and running process.
3. Configure QLLVM: Install and configure the QLLVM compiler according to the instructions in the help directory on GitHub, ensuring it can be recognized by the QCoder-compiler plugin.
4. Select Model: Priority select one of the three built-in SCNet models to start with zero keys; if using other cloud service provider models, configure the corresponding API Key as needed.
5. Open Chat: Click QCODER-chat in the activity bar (sidebar); or use the command Chat with Quantum Programming Assistant to open a panel next to the editor (interaction details see "Interface and Interaction Points" above).
6. Generate and Compile: Generate circuit files in QCoder-chat, save them, then use the QCoder-compiler plugin to compile and run simulations.
7. Agent Automatic Process: Enable Agent Mode to automatically complete the full process from code generation, QLLVM compilation to running simulation, without manual tool switching, improving development efficiency.

Common Commands and Settings

Common Commands

Main Settings (qcoder-chat.*)

How to Read This Document

If you open this README in the VS Code explorer, you can use Ctrl+Shift+V (macOS: Cmd+Shift+V) to preview Markdown; side preview is available with Ctrl+K V. The Mermaid flowcharts in the text can usually be directly rendered on GitHub web pages; for consistent local effects, you can use a preview extension that supports Mermaid. After the extension is listed, a short summary can be placed on the marketplace details page, with complete instructions based on the GitHub repository homepage and help directory (https://github.com/QCFlow).

Project Structure (Overview)

Development and Building

npm install
npm run compile
npm run watch
npm run package
npm run lint
npm run test

Use Run and Debug to start the Extension Development Host to debug this extension.

License

MIT. Full license text: https://github.com/QCFlow.