feat: implement shared runtime management for Windows, including installation, repair, and status commands

Author: bruc3van

CHANGELOG.md

@@ -6,6 +6,8 @@
 
 - 默认启用 `.docugenius.json` 项目配置文件创建，确保项目启用/禁用状态可持久化
 - 同步调整设置文案与运行时默认值，避免配置声明与代码兜底不一致
+- Windows 改为使用扩展级共享 runtime：首次确认后统一安装到全局存储目录，不再向每个工作区单独安装依赖
+- 新增共享 runtime 的安装、修复、状态命令，并将依赖准备流程迁移到 VS Code 原生通知、进度和日志通道中
 
 ## [2.5.0] - 2025-04-14
 

README.md

@@ -90,7 +90,25 @@ DocuGenius 是一个 VSCode 插件，将 Word、Excel、PowerPoint、PDF 转换
   ```bash
   sudo /usr/sbin/softwareupdate --install-rosetta --agree-to-license
   ```
-- **Windows**：需预先安装 Python 3.6+（依赖库会自动安装）
+- **Windows**：需预先安装 Python 3.6+
+  - 首次转换时，DocuGenius 会先提示你安装一套**共享本地运行时**
+  - 这套运行时只会安装在扩展自己的存储目录中，并在所有工作区之间复用
+  - 不会向每个项目目录单独创建 `.venv`，也不会把依赖安装到当前工作区
+
+## Windows 运行时说明
+
+在 Windows 上，DocuGenius 会使用系统里的 Python **只做一次引导**：
+
+1. 检测本机是否存在可用的 Python
+2. 在扩展的全局存储目录里创建一套共享运行时
+3. 将 `python-docx`、`openpyxl`、`python-pptx`、`pdfplumber` 安装到这套共享运行时
+4. 后续所有工作区都复用这套运行时进行转换
+
+如果你需要手动处理运行时，可以从命令面板使用：
+
+- `DocuGenius: Install Shared Runtime`
+- `DocuGenius: Repair Shared Runtime`
+- `DocuGenius: Show Runtime Status`
 
 ## 常见问题
 
@@ -106,6 +124,10 @@ A: 文档转换过程完全在本地执行，不会上传到任何服务器。
 
 A: 不支持。DocuGenius 专注文档转换，如需在 IDE 中预览原始文件，建议搭配 Office Viewer 类插件使用。
 
+**Q: Windows 会不会给每个项目都安装一份依赖？**
+
+A: 不会。DocuGenius 现在会把 Windows 运行时安装到扩展自己的共享目录中，所有工作区共用一份，不会污染每个项目目录。
+
 ## 作者
 
 - X: [@bruc3van](https://x.com/bruc3van)

bin/converter.py

@@ -2572,7 +2572,8 @@ def main():
 
     # 调用对应转换函数
     try:
-        deps_ok, err = check_dependencies(file_ext)
+        auto_install_deps = os.environ.get('DOCUGENIUS_AUTO_INSTALL_DEPS', '1').lower() not in ('0', 'false', 'no')
+        deps_ok, err = check_dependencies(file_ext, auto_install=auto_install_deps)
         if not deps_ok:
             print(f"Error: {err}", file=sys.stderr)
             sys.exit(1)

package.json

@@ -155,6 +155,21 @@
         "command": "documentConverter.showProjectStatus",
         "title": "%command.showProjectStatus.title%",
         "category": "DocuGenius"
+      },
+      {
+        "command": "documentConverter.installRuntime",
+        "title": "%command.installRuntime.title%",
+        "category": "DocuGenius"
+      },
+      {
+        "command": "documentConverter.repairRuntime",
+        "title": "%command.repairRuntime.title%",
+        "category": "DocuGenius"
+      },
+      {
+        "command": "documentConverter.showRuntimeStatus",
+        "title": "%command.showRuntimeStatus.title%",
+        "category": "DocuGenius"
       }
     ],
     "menus": {

package.nls.json

@@ -28,6 +28,9 @@
   "command.enableProject.title": "[DocuGenius]Enable for Current Project",
   "command.disableProject.title": "[DocuGenius]Disable for Current Project",
   "command.showProjectStatus.title": "[DocuGenius]Show Project Status",
+  "command.installRuntime.title": "[DocuGenius]Install Shared Runtime",
+  "command.repairRuntime.title": "[DocuGenius]Repair Shared Runtime",
+  "command.showRuntimeStatus.title": "[DocuGenius]Show Runtime Status",
 
   "message.ready": "DocuGenius is ready!",
   "message.projectEnabled": "Project enabled",
@@ -51,6 +54,7 @@
   "status.batchPartial": "{0}/{1} converted",
   "status.configUpdated": "Config updated",
   "status.skipped": "Skipped {0}",
+  "status.runtimePreparing": "Preparing runtime...",
   "tooltip.ready": "DocuGenius: {0}",
   "tooltip.converting": "Converting {0} to Markdown",
   "tooltip.converted": "Successfully converted {0}",
@@ -74,5 +78,40 @@
   "log.watcherEnabled": "File watcher enabled for extensions: {0}",
   "log.watcherDisabled": "File watcher disabled",
   "log.fileSkipped": "Skipped {0}: {1}",
-  "log.batchProgress": "Converting ({0}): {1}"
+  "log.batchProgress": "Converting ({0}): {1}",
+  "log.runtime.bootstrap": "Preparing shared runtime with bootstrap Python: {0}",
+  "log.runtime.installPackages": "Installing shared runtime packages: {0}",
+  "log.runtime.ready": "Shared runtime is ready: {0}",
+  "log.runtime.failed": "Shared runtime setup failed: {0}",
+  "runtime.action.install": "Install Runtime",
+  "runtime.action.repair": "Repair Runtime",
+  "runtime.action.viewDetails": "View Details",
+  "runtime.action.notNow": "Not Now",
+  "runtime.action.openLogs": "Open Logs",
+  "runtime.action.openPythonDownload": "Install Python",
+  "runtime.prompt.manualTitle": "DocuGenius needs a shared local runtime before it can convert documents on Windows.",
+  "runtime.prompt.backgroundTitle": "DocuGenius found documents to convert, but the shared runtime is not ready yet.",
+  "runtime.progress.installTitle": "Installing DocuGenius shared runtime...",
+  "runtime.progress.repairTitle": "Repairing DocuGenius shared runtime...",
+  "runtime.progress.creatingEnvironment": "Creating an isolated shared Python environment...",
+  "runtime.progress.installingDependencies": "Installing required conversion packages into the shared runtime...",
+  "runtime.progress.verifying": "Verifying the shared runtime...",
+  "runtime.success.ready": "DocuGenius shared runtime is ready.",
+  "runtime.error.installFailed": "DocuGenius could not prepare the shared runtime. Open the logs to see the full setup output.",
+  "runtime.error.pythonMissing": "DocuGenius could not find Python 3.6+ on this machine. Install Python once to bootstrap the shared runtime.",
+  "runtime.error.setupDeferred": "DocuGenius skipped conversion because the shared runtime is not ready yet.",
+  "runtime.error.verifyFailed": "The shared runtime was created, but dependency verification failed.",
+  "runtime.error.invalidRuntimePath": "Refusing to modify a runtime path outside the extension storage directory.",
+  "runtime.error.timeout": "Command timed out after {0} seconds while preparing the shared runtime.",
+  "runtime.detail.ready": "The shared runtime is installed and verified.",
+  "runtime.detail.installRequired": "The shared runtime has not been installed yet. DocuGenius will create one copy for this extension and reuse it across workspaces.",
+  "runtime.detail.repairRequired": "The shared runtime exists, but it is missing files or dependencies and needs repair.",
+  "runtime.detail.missingPython": "Python is required once to bootstrap the shared runtime. DocuGenius will not install dependencies into each workspace.",
+  "runtime.status.readyTitle": "DocuGenius shared runtime is ready.",
+  "runtime.status.issueTitle": "DocuGenius shared runtime needs attention.",
+  "runtime.status.notManagedPlatform": "This platform uses the built-in bundled converter and does not need a managed Python runtime.",
+  "runtime.status.locationLabel": "Location",
+  "runtime.status.versionLabel": "Runtime version",
+  "runtime.status.bootstrapLabel": "Bootstrap Python",
+  "runtime.status.detailLabel": "Details"
 }

package.nls.zh-cn.json

@@ -28,6 +28,9 @@
   "command.enableProject.title": "[DocuGenius]为当前项目启用",
   "command.disableProject.title": "[DocuGenius]为当前项目禁用",
   "command.showProjectStatus.title": "[DocuGenius]显示项目状态",
+  "command.installRuntime.title": "[DocuGenius]安装共享运行时",
+  "command.repairRuntime.title": "[DocuGenius]修复共享运行时",
+  "command.showRuntimeStatus.title": "[DocuGenius]显示运行时状态",
 
   "message.ready": "DocuGenius 已就绪！",
   "message.projectEnabled": "项目已启用",
@@ -51,6 +54,7 @@
   "status.batchPartial": "{0}/{1} 已转换",
   "status.configUpdated": "配置已更新",
   "status.skipped": "已跳过 {0}",
+  "status.runtimePreparing": "正在准备运行时...",
   "tooltip.ready": "DocuGenius: {0}",
   "tooltip.converting": "正在转换 {0} ",
   "tooltip.converted": "成功转换 {0}",
@@ -74,5 +78,40 @@
   "log.watcherEnabled": "文件监控已启用，支持扩展名: {0}",
   "log.watcherDisabled": "文件监控已禁用",
   "log.fileSkipped": "已跳过 {0}: {1}",
-  "log.batchProgress": "转换中 ({0}): {1}"
+  "log.batchProgress": "转换中 ({0}): {1}",
+  "log.runtime.bootstrap": "正在使用引导 Python 准备共享运行时: {0}",
+  "log.runtime.installPackages": "正在向共享运行时安装依赖: {0}",
+  "log.runtime.ready": "共享运行时已就绪: {0}",
+  "log.runtime.failed": "共享运行时准备失败: {0}",
+  "runtime.action.install": "安装运行时",
+  "runtime.action.repair": "修复运行时",
+  "runtime.action.viewDetails": "查看详情",
+  "runtime.action.notNow": "稍后再说",
+  "runtime.action.openLogs": "打开日志",
+  "runtime.action.openPythonDownload": "安装 Python",
+  "runtime.prompt.manualTitle": "DocuGenius 在 Windows 上转换文档前，需要先准备一套共享本地运行时。",
+  "runtime.prompt.backgroundTitle": "DocuGenius 检测到待转换文档，但共享运行时尚未准备好。",
+  "runtime.progress.installTitle": "正在安装 DocuGenius 共享运行时...",
+  "runtime.progress.repairTitle": "正在修复 DocuGenius 共享运行时...",
+  "runtime.progress.creatingEnvironment": "正在创建隔离的共享 Python 环境...",
+  "runtime.progress.installingDependencies": "正在向共享运行时安装文档转换依赖...",
+  "runtime.progress.verifying": "正在验证共享运行时...",
+  "runtime.success.ready": "DocuGenius 共享运行时已就绪。",
+  "runtime.error.installFailed": "DocuGenius 无法准备共享运行时。请打开日志查看完整安装输出。",
+  "runtime.error.pythonMissing": "DocuGenius 未在当前机器上找到 Python 3.6+。需要先安装一次 Python，才能引导共享运行时。",
+  "runtime.error.setupDeferred": "由于共享运行时尚未准备好，DocuGenius 已跳过本次转换。",
+  "runtime.error.verifyFailed": "共享运行时已创建，但依赖校验失败。",
+  "runtime.error.invalidRuntimePath": "拒绝修改扩展存储目录之外的运行时路径。",
+  "runtime.error.timeout": "准备共享运行时时命令执行超时，已超过 {0} 秒。",
+  "runtime.detail.ready": "共享运行时已安装并完成校验。",
+  "runtime.detail.installRequired": "共享运行时尚未安装。DocuGenius 会为当前扩展创建一份共享运行时，并在所有工作区之间复用。",
+  "runtime.detail.repairRequired": "共享运行时已存在，但缺少文件或依赖，需要修复。",
+  "runtime.detail.missingPython": "共享运行时只需要用 Python 引导一次。DocuGenius 不会再向每个工作区单独安装依赖。",
+  "runtime.status.readyTitle": "DocuGenius 共享运行时已就绪。",
+  "runtime.status.issueTitle": "DocuGenius 共享运行时需要处理。",
+  "runtime.status.notManagedPlatform": "当前平台使用内置打包转换器，不需要托管 Python 运行时。",
+  "runtime.status.locationLabel": "位置",
+  "runtime.status.versionLabel": "运行时版本",
+  "runtime.status.bootstrapLabel": "引导 Python",
+  "runtime.status.detailLabel": "说明"
 }