qtvscode

把 VS Code Web 工作台 作为控件嵌入 PySide6 / PyQt6 桌面应用， 提供一个功能完整的代码编辑器页面，并与 Python 双向通信。 与具体业务无关，任何 Qt 应用（编辑器、IDE、工具软件等）均可使用。

架构

你的 Qt 主程序 (PySide6 / PyQt6)
 ├─ 你自己的面板（图表 / 日志 / 业务 UI…）
 └─ QtVscodeWidget ──► QWebEngineView ──► qtvscode-server (Node, 127.0.0.1)
                                              └─ qtvscode-bridge 扩展
                          QtvscodeBridge ◄── WebSocket JSON-RPC ──┘

安装

从 PyPI 安装（已发布时）

pip install qtvscode
# 或指定 Qt 绑定
pip install "qtvscode[pyside6]"   # 推荐（QtWebEngine 随包提供）
pip install "qtvscode[pyqt6]"

PyPI 上的 qtvscode 是轻量包（仅 Python 胶水层，不含 server）。 安装后仍需按下文获取 server（本机构建或按需下载）。

从源码安装（开发）

cd qtvscode
pip install -e .
# 或按绑定安装
pip install -e ".[pyside6]"     # 推荐
pip install -e ".[pyqt6]"

自带 server 的“胖包”（离线分发）

powershell qtvscode/scripts/package.ps1 -BundleServer

生成的 wheel 已包含 qtvscode/server/，pip install 后即可直接运行（无需再获取 server）。 注意：server 约 700MB，超过 PyPI 单文件上限，适合内网/离线分发，不适合上传 PyPI。

获取 qtvscode-server

pip install 只安装 Python 胶水层，不会构建 server。server 需要单独获取。

server 是 VS Code 源码（本仓库的 vscode/ 目录） 构建出来的 reh-web 产物， 本机构建即可使用，不需要上传到 GitHub；GitHub Release 仅用于「让别的机器自动下载」。

注意：vscode/ 源码目录里没有 vscode-reh-web-win32-x64/，它是构建产物， 默认生成在 vscode/ 的同级目录（即仓库根 C:\...\vscode-main\vscode-reh-web-win32-x64）。

方式 A：本机构建（推荐，离线可用）

只需两步（不是三步）——build_server.ps1 内部已包含 npm install 与 npx gulp：

:: 1) 安装 Python 胶水层（源码用 `pip install -e .`；PyPI 用 `pip install qtvscode`）
cd qtvscode
pip install -e .

:: 2) 构建 server 并复制进包（内部执行 npm install + gulp + 复制 + conpty 修复）
powershell qtvscode\scripts\build_server.ps1 -Copy

如果你想自己手动执行每一步，等价于：

cd vscode
npm install
npm run gulp vscode-reh-web-win32-x64       # 发布用：vscode-reh-web-win32-x64-min
# 然后可选：把产物复制进包
#   qtvscode/qtvscode/server/  <- vscode-reh-web-win32-x64/*</p>

构建环境怎么来的？ npm install 安装 Node 依赖；gulp vscode-reh-web-* 会下载 内置的 Node 运行时、编译原生模块（node-pty 等）并打包。这些都在构建时完成， pip install 不参与。Windows 首次编译原生模块可能需要补充构建环境（详见 QTVSCODE_PLAN.md 附录 A 的 Spectre / signtool 说明，脚本已自动处理）。

方式 B：按需下载（分发给其它机器）

from qtvscode import ensure_server
server_dir = ensure_server()          # 读取环境变量 QTVSCODE_SERVER_URL
# 或 ensure_server("https://github.com/<owner>/<repo>/releases/download/v0.1.0/vscode-reh-web-win32-x64.zip")

发布包生成：powershell qtvscode/scripts/package_server.ps1 → qtvscode-server-<target>.zip。

server 自动发现顺序

find_server_dir() 依次查找：

1. 显式传入 server_dir=...
2. 环境变量 QTVSCODE_SERVER_DIR
3. Python 包内 qtvscode/server/
4. 仓库构建产物 vscode-reh-web-*
5. 运行时下载目录 ~/.qtvscode-server/runtime/*

快速开始

import sys
from qtvscode import (
    ensure_qtwebengine_attributes, QApplication,
    QtvscodeBridge, QtVscodeWidget,
)

ensure_qtwebengine_attributes()      # 必须在 QApplication 之前
app = QApplication(sys.argv)

bridge = QtvscodeBridge()
bridge.register("run", lambda p: print("运行:", p.get("path")))
bridge.register("stop", lambda p: {"ok": True})

editor = QtVscodeWidget("/path/to/workspace", bridge=bridge)
editor.resize(1200, 800)
editor.show()
sys.exit(app.exec())

或直接运行示例（整个窗口就是一个 VS Code 页面）：

set PYTHONPATH=qtvscode
python -m qtvscode.examples.editor_app            :: 启动
python -m qtvscode.examples.editor_app --selftest :: 自检后退出

安装扩展

extension marketplace 已配置为 Open VSX，可在界面「扩展」视图中搜索安装； 若界面安装受限，可用命令行（等价能力，最稳）：

:: Python 入口（跨平台，推荐）
set PYTHONPATH=qtvscode
python -m qtvscode.install detachhead.basedpyright johnny-zhao.pi-agent-studio
python -m qtvscode.install ms-ceintl.vscode-language-pack-zh-hans

# PowerShell 脚本（同样能力）
powershell -ExecutionPolicy Bypass -File qtvscode/scripts/install_python_extensions.ps1 `
  -ExtensionIds detachhead.basedpyright,johnny-zhao.pi-agent-studio

扩展安装到持久化目录 ~/.qtvscode-server/extensions/（重新构建产物时不会丢失），重启编辑器后生效。

预置默认行为

首次运行会写入用户设置（~/.qtvscode-server/data/User/settings.json，不覆盖已有设置）：

• workbench.colorTheme = qtvscode Dark
• chat.disableAIFeatures = true（只用 Pi Agent Studio，隐藏内置 Copilot Chat）
• extensions.verifySignature = false（Open VSX 场景允许安装扩展）
• locale = zh-cn（配合中文语言包）

Chat / Agent

内置 Chat 面板属于 VS Code 核心功能，默认参与者来自内置的 extensions/copilot（GitHub Copilot）， 未登录时会提示 “You need to set up GitHub Copilot...”。本产品默认隐藏它，改用 Pi Agent Studio（johnny-zhao.pi-agent-studio）：命令面板 → Pi Agent Studio: Open / Open in Sidebar。

API

QtVscodeServer

管理 server 子进程：随机端口、连接 token、--default-folder、注入 RPC 环境变量。 信号：ready(QUrl) / output(str) / exited(int) / failed(str)。

QtvscodeBridge

基于 QtWebSockets 的 JSON-RPC 服务端。register(method, handler) 注册方法， invoke(method, params) 本地调用，notify(method, params) 广播给扩展。 信号：connected / disconnected / activeEditorChanged(str) / logReceived(str, str)。

QtVscodeWidget

QWidget，内含 QWebEngineView（可选工具栏）。show_toolbar=False 时只显示编辑器页面。 trigger(method, params) 触发 qtvscode 操作，open_in_browser() 在系统浏览器打开，stop() 回收进程。

注意事项

• 必须在创建 QApplication 之前 调用 ensure_qtwebengine_attributes()。
• 无独显 / 远程桌面可设置软件渲染： QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu 或 QT_OPENGL=software。
• server 仅监听 127.0.0.1，并使用随机连接 token。

界面语言（中文）

Web(reh-web) 版工作台的显示语言不读 locale 设置，而是：

1. server 依据 cookie vscode.nls.locale 决定是否加载 WORKBENCH_NLS_URL；
2. 该 URL 由 product.json 的 nlsCoreBaseUrl 拼出。

本包已内置处理：安装语言包后，QtVscodeWidget(locale="zh-cn") 会在加载前写入 cookie 与 localStorage，并用 qtvscode.nls 从语言包合成 out/nls/<commit>/<version>/<locale>/nls.messages.js。

editor = QtVscodeWidget(workspace, locale="zh-cn")

先把语言包装进产物：

set PYTHONPATH=qtvscode
python -m qtvscode.install ms-ceintl.vscode-language-pack-zh-hans

示例读取环境变量 QTVSCODE_LOCALE，默认 zh-cn。

Pi Agent Studio

{
  "pi-agent-studio.path": "C:\Users\<you>\AppData\Roaming\npm\pi.cmd",
  "pi-agent-studio.ui": "webview",
  "pi-agent-studio.language": "zh-cn"
}

命令面板 → Pi Agent Studio: Open / Open in Sidebar。