Metadata-Version: 2.4
Name: qtvscode
Version: 0.1.0
Summary: 将 VS Code Web 工作台嵌入 PySide6/PyQt6 的通用代码编辑器控件
Author: qtvscode
License: MIT
Keywords: vscode,pyqt,pyside,qt,editor,code-editor,embed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: pyside6
Requires-Dist: PySide6>=6.6; extra == "pyside6"
Provides-Extra: pyqt6
Requires-Dist: PyQt6>=6.6; extra == "pyqt6"
Requires-Dist: PyQt6-WebEngine>=6.6; extra == "pyqt6"

# 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 安装（已发布时）

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

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

### 从源码安装（开发）

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

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

```powershell
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`：

```bat
:: 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
```

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

```bash
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：按需下载（分发给其它机器）

```python
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/*`

## 快速开始

```python
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 页面**）：

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

## 安装扩展

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

```bash
:: 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 脚本（同样能力）
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`。

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

先把语言包装进产物：

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

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

## Pi Agent Studio

```json
{
  "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`。
