Jutze MES for VS Code

0.2.0 起使用本地 Python 工作区 + MES 同步：从应用文件 API 缓存源码，供 Python/Pylance 正常分析。 文件保存到本机后，再通过带版本校验的 API 上传 MES 数据库。 不连接 Docker/SSH；打开工作区不会安装依赖或执行应用，安装 SDK 需用户确认，不自动重启应用。

0.6.2：已安装 SDK 但缺少代码提示

如果 .venv 已安装 jutze，编辑器仍提示找不到包，请执行 MES: 修复 Python 代码提示， 不要反复安装 SDK。命令会检查已有安装来源，切换当前应用的解释器， 同步 Python Environments 扩展的项目环境，再重启 Pylance 分析。 修复不下载或安装包、不执行 app.py，也不要求提前配置 config.local.yaml； 运行应用仍然必须使用测试配置。

原因之一是旧工作区的 python-envs.pythonProjects 绑定了 system 环境： 修改 python.defaultInterpreterPath 或只调用旧 Python API，不一定改变 Pylance 实际使用的项目环境。 插件现在使用 Python Environments 公开 API 同步当前项目，并读取两套 API 验证选择结果。 没有启用新环境扩展时仍兼容原 Python API；不会禁用扩展、修改全局环境，或用 extraPaths 掩盖环境不一致。 解释器链接到同一全局二进制不代表是同一个运行环境，因此检查保留 .venv 身份， 不对解释器文件直接 realpath 后比较。

安装任务也采用相同的环境配置流程。若 SDK 安装成功而编辑器配置失败，会明确区分并提供修复按钮， 不再把“安装完成”当成“代码提示已就绪”。安装或修复后 Pylance 可能需要几秒重新分析。 需要工作区受信任，且已启用 Python 和 Pylance 扩展。

0.6.1：默认 SDK 地址与升级提示

默认 wheel 已设为：

https://bin.jutze.cn/artifactory/releases/jdc/mes-package/jutze-0.2.0-py3-none-any.whl

新工作区可直接运行 MES: 安装 SDK / 初始化环境，配置命令也会预填该地址。 已有自定义 wheel 不会被覆盖；升级前已选择源码项目且未明确配置 wheel 时，继续使用源码模式。 打开工作区仍不会自动下载安装。

若出现“没有注册配置 jutzeMes.sdkWheelUrl，因此无法写入工作区设置”，说明当前窗口没有加载该配置声明， 不是 wheel 下载失败。常见于旧窗口中升级扩展后，插件代码与窗口配置注册状态未同步。 请先保存文件，再执行 Developer: Reload Window / 开发人员: 重新加载窗口。 如果仍报错，完全退出 VS Code 后重新打开，并确认当前配置文件中启用的是新版 Jutze MES。 无需删除 .venv、本地业务文件或工作区。插件会在 SDK 读写前检测注册状态， 给出重载操作，不绕过 VS Code 直接修改设置 JSON。

0.6.0：远程 wheel SDK（推荐）

普通使用者不再需要本地 SDK 源码或 pyproject.toml：

1. 从 MES 网页打开应用，安装 Python / Pylance / Python Debugger 扩展。
2. 执行 MES: 配置远程 SDK（wheel），输入与部署环境匹配的 jutze-<版本>-<标签>.whl HTTPS 固定地址。
3. 点击 安装并配置 并确认来源。插件优先使用 uv，未找到时使用原生 Python： 创建/复用应用 .venv，下载 wheel，安装 SDK 及依赖，校验后自动切换 Python 解释器。
4. 复制 config.yaml 为 config.local.yaml，改为测试环境，再运行或 F5 调试。

配置项为 jutzeMes.sdkWheelUrl，明确设置的非空值优先于旧 sdkPath；默认值不抢占已有源码项目。支持在 URL 后附 #sha256=<64 位校验值> 固定包内容；未提供时仍记录下载哈希并核对实际安装来源， 但这不等于验证发布者身份。地址和重定向必须使用 HTTPS，不允许账号、密码、查询参数， 不支持带 token 的签名 URL；下载上限 128 MiB、超时 120 秒。 只有包名为 jutze 的 wheel 可用。Python 版本、平台标签及依赖兼容性由安装工具验证， 插件不会自动安装 Python，也不会检测生产容器里的 SDK 版本。

安装任务可取消，并且不会更改全局 Python。安装失败保留业务源码；真正开始修改环境前会清除 wheel 成功记录，不能把失败或半安装状态当作可运行环境。下载失败不更改旧环境。 更新地址或校验值后，请执行 MES: 安装 SDK / 初始化环境；同 URL 内容更新也需手动重新安装。 安装日志在任务终端；若 Python 扩展缺失或无法自动切换，会提示手动选择 .venv。 安装清理会改变目标目录的 pip/uv 环境变量；暂不支持需要登录、私有鉴权包源或任意 pip 参数的流程。

源码开发仍支持 MES: 选择外部 SDK 项目（源码开发），选择后清空 wheel 设置并恢复 editable 安装。 升级保留用户修改过的 tasks.json，这些旧任务不会自动改写；可直接使用新增的安装命令， 无需依赖旧初始化任务。.venv 不上传；下载缓存 sdk-cache/ 和来源记录 sdk-install.json 放在扩展缓存的应用目录 app/ 之外。

0.5.1：网页展示本地应用目录

• 连接后同步已有本地文件，保存、新建、复制目录及外部修改会自动同步，网页文件树自动刷新。
• 默认仅排除 .venv、.vscode、config.local.yaml，嵌套目录同样生效。
• 说明文档、隐藏文件和日志等 UTF-8 文本也参与同步；其他敏感文件请自行加入 .mesignore。
• 保留自定义忽略规则；未修改的旧默认 .mesignore 会自动升级。自定义文件中的旧规则需自行移除。
• 不上传二进制、链接、插件原子写入的临时文件或空目录；仍不传播删除，不绕过版本冲突校验。

0.5.0：外部 SDK 与前端彻底分离

• 前端和 VSIX 不再包含 Python SDK 源码、协议生成代码或 SDK 快照；不再生成 Python 启动脚本。
• 执行 MES: 选择外部 SDK 项目，选择包含 pyproject.toml 和 jutze 的完整项目。 项目必须位于应用工作区和插件之外；例如独立的 jdc_mes_package 源仓库。
• jutzeMes.sdkPath 同时用于 Pylance 和本地可编辑安装。切换 SDK 后需重新初始化环境。
• 插件不探测容器中的 SDK 版本。请依据基础镜像或依赖清单选定匹配版本，不把插件版本当作 SDK 版本。
• 运行及调试前由插件 JavaScript 检查测试配置和 SDK 安装来源，直接启动业务 app.py。
• 不再生成 start.sh；请使用跨平台 VS Code 初始化、运行和调试任务。
• 升级只删除登记过且未修改的旧 SDK/启动文件。修改过或未保存的文件保留并提示，迁移后不再使用旧入口。
• python-libs 和旧启动文件仍受同步保护，避免遗留文件上传。.mesignore 继续支持 gitignore 规则。
• 构建前扫描前端源码，打包时检查 VSIX 文件清单，防止 Python 源码或 SDK 快照重新进入交付物。

0.4.2：Artifactory 更新索引

默认检查地址改为 https://bin.jutze.cn/artifactory/releases/jdc/mes-vscode/releases.json。 直接读取此 JSON，不追加斜杠或再次拼接 releases.json；安装包及 .sha256 从索引所在目录下载。 兼容 Artifactory 返回的纯 SHA-256，以及构建生成的带文件名校验文件。 如果用户曾手动设置旧地址，请在用户设置中修改 jutzeMes.releaseUrl，或重置该设置以使用新默认值。

版本更新与完整性校验（0.4.1 起）

命令面板新增：

• MES: 检查插件更新：从配置的 HTTPS JSON 索引或目录获取文件列表， 按数字版本号选择最新稳定版本（例如 0.10.0 高于 0.9.0），不会降级。
• MES: 校验插件完整性：核对构建时注入的包内 SHA-256 清单，结果及 root hash 记录在「MES 插件更新」输出。

默认启动后及每 24 小时静默检查一次；仅发现新版时提示，不自动下载或安装。 在用户设置中可关闭 jutzeMes.autoCheckUpdates，或修改应用级设置 jutzeMes.releaseUrl。 更新源必须是 HTTPS JSON 索引或目录，工作区不能覆盖此设置。网络失败不会影响文件编辑，手动检查会显示错误。 自动检查后用户主动下载失败也会提示，不会静默忽略 hash 错误。

点击「下载并校验」后，先获取版本对应的 .sha256 文件，再下载并校验 VSIX。 缺少 hash、文件名不匹配或内容损坏时拒绝保存/安装，不降级为不校验下载。 成功后可选择「显示安装包」或「安装更新」；安装和重载窗口均需要用户确认。 VS Code 标准安装包后缀是 .vsix，不是 .vslx。

构建与发布约定

在扩展目录运行 npm run package，构建会自动：

1. 检查前端及打包列表不含 Python 源码或 SDK 快照。
2. 生成包内 integrity.json，包含插件源代码、生产依赖的逐文件 SHA-256，以及插件元数据指纹。 在 package.json 的 jutzeIntegrity.rootHash 中注入清单的汇总 hash。
3. 生成 mes-vscode-<version>.vsix，打包完成后计算整个 VSIX 的 SHA-256。
4. 生成 mes-vscode-<version>.vsix.sha256 和 releases.json；更新旧前端兼容的 mes-vscode.vsix。

以当前版本为例，把以下文件一起上传至 release 目录（更新插件不需要上传源码）：

mes-vscode-0.6.2.vsix
mes-vscode-0.6.2.vsix.sha256
releases.json

支持常见 HTML 自动目录列表、JSON 文件列表（files 数组）和 Artifactory children 列表。 配置为目录时，目录返回 404 或未发现版本包会读取目录下的 releases.json；无需开启目录浏览。 配置为 JSON 索引时只请求该索引，404/空列表会报错，不猜测其他地址。 仅识别同目录、同源的 mes-vscode-x.y.z.vsix 稳定版本，不读取其他主机或上级目录的下载链接。 构建的 .sha256 使用标准格式：<64 位 SHA-256> <完整版本文件名>；下载同时兼容纯 64 位 SHA-256。 构建目录存在历史版本时，必须同时保留它们原有的 .sha256；校验不匹配会终止发布清单生成。 多个构建机器发布时，需要合并 releases.json 的历史条目，或开启服务器目录列表。 本仓库 GitLab CI 已通过串行发布和索引合并实现，见下节。

GitLab CI 自动发布

支持内网 Artifactory 和 VS Code Marketplace 双渠道发布，两者使用同一份已测试的 VSIX。 执行顺序为 package → release（Artifactory）→ marketplace → build → deploy。

保留原有 workflow：不创建 MR/tag 流水线，只允许 dev、默认分支和 test 开头的分支。 每条允许的流水线先执行 build-vscode：安装锁定依赖（包括构建所需 devDependencies）、 运行完整 Node 测试，再生成 VSIX 和完整性清单。测试镜像安装 Python、venv 和 OpenSSL， 用于真实 wheel 安装及本机 HTTPS 测试；没有 uv 时现有测试仅执行 pip 路径。 制品保留七天，并传给 build-image，所以前端镜像始终带上本次源码构建的插件， 不要求开发者在本机提前打包。插件测试、打包或发布失败会阻止后续镜像构建和部署。

GitLab CI/CD 变量：

• JFROG_USER、JFROG_API_TOKEN：复用镜像发布已有变量，需同时拥有插件 release 目录的读取、 创建文件、更新索引及兼容入口权限。token 应设置为 Masked；如设置 Protected， 默认分支也必须受保护。脚本不会打印凭证。
• VSCODE_RELEASE_URL：可选，默认 https://bin.jutze.cn/artifactory/releases/jdc/mes-vscode/。 必须是 HTTPS 目录；客户端需能读取该目录中的包、校验文件和索引。 如改为其他地址，还需同步客户端的更新源配置，CI 变量不会自动修改插件更新源。
• NPM_REGISTRY：复用现有 npm 镜像源。
• VSCE_PAT：Marketplace 发布凭证，必须属于有权向 jutze publisher 发布扩展的账号， 创建 Azure DevOps PAT 时选择 Marketplace 的 Manage 权限。 在 GitLab 中设置为 Masked、Protected，并确保默认分支受保护且变量对该 job 可用。 不要写入仓库、命令行或 .npmrc；缺少凭证时 Marketplace job 明确失败，不静默跳过。

发布版本：

1. 修改插件后，提交前手动升级插件版本（CI 不自动改版本、不向仓库推送提交）： 在前端仓库根目录运行 npm --prefix vscode-extension version patch --no-git-tag-version。 同时提交插件 package.json 和 package-lock.json；前端 version 文件与插件版本独立。
2. 合入默认分支后，CI 检测插件目录变化并自动发布。
3. 发布脚本先校验本地 VSIX 的 SHA-256，再合并远端历史索引，上传版本包并确保 .sha256 可用， 回读验证安装包和校验文件，最后更新 releases.json。兼容 Artifactory 自动提供的纯 hash 校验端点，已存在时不重复上传校验文件。版本包和校验文件就绪前不会暴露新版本。
4. 相同版本、相同包允许重试；相同版本但内容不同会失败，禁止覆盖已发布版本。 VSIX 重新打包后的字节可能变化，因此优先重试原 publish-vscode job（七天制品有效期内）， 而不是重跑打包任务。若重新打包触发冲突，应升级版本。
5. 发布使用同一 resource_group 串行执行，旧流水线晚完成也只补齐历史版本， 不会把最新版索引排序或 mes-vscode.vsix 兼容入口回退。

首次发布允许远端 releases.json 不存在（404）。权限错误、服务器故障或损坏的索引均使发布失败， 不会将其当成空索引覆盖。若该目录已有历史包但没有索引，先将历史条目迁入 schemaVersion: 1 的索引（每项包含 name/version/sha256/size），再启用 CI。 不要再从其他不受该 GitLab resource group 管理的流水线或本机同时写入此发布目录。

Marketplace 首次启用及失败处理：

• 先在 Marketplace 发布者管理页面创建或取得 jutze publisher 的发布权限； 当前目标扩展 ID 固定为 jutze.mes-vscode。CI 不自动创建发布者，也不更改扩展 ID。
• publish-vscode-marketplace 等待内网发布成功，安装 lockfile 锁定的 @vscode/vsce， 校验构建制品 SHA-256 后调用 publishVSIX，不重新打包、不改版本、不创建 Git tag。
• Marketplace 发布是公开分发；启用前确认插件源码、README、内网默认地址和许可证适合公开。
• 两个发布任务分别串行执行。Marketplace 上传失败会阻止后续镜像构建和部署， 但不会回滚已经成功的 Artifactory 发布。
• 凭证或网络问题修复后，可在七天制品有效期内只重试 publish-vscode-marketplace， 不必重跑内网发布和打包。不要在完整流水线中盲目重新打包相同版本。
• 同版本已在 Marketplace 存在时保留失败，不使用 skipDuplicate 掩盖版本冲突。 如果上传成功但 job 未能记录成功，先人工核对 Marketplace 状态；需要再次发布时升级版本。 CI 上传成功也不代表 Marketplace 的验证及上架处理已经完成。
• 本次 CI 改动不修改网页安装入口或插件已有的内网更新源。

正式安装的插件激活前会进行包内自检；文件缺失、损坏或插件元数据变化时，不启动 MES 同步。 开发/测试宿主跳过自动自检，以允许编辑源码；手动校验仍可执行。VS Code 自动写入的 __metadata 不参与指纹；外部 SDK 不属于插件安装文件，不纳入插件自检。

完整安装包 hash 不能写回包自身，否则每次写入都会改变该 hash。这里采用「包内文件清单 + 包外整个 VSIX 校验」两层校验；它检测传输/存储损坏，不是发布者数字签名， 不能防御同时篡改安装包及校验文件的攻击，发布源仍必须可信并使用 HTTPS。

0.4.0：新建文件与本地运行

• 支持新建 UTF-8 文本文件和嵌套目录；空文件创建及编辑保存都会同步，空目录本身不上传。
• 新建使用 revision: "new" 的仅创建语义，同名文件/目录返回 409，不能覆盖服务器已有内容。
• app.py、config.yaml、pre_run.sh 可编辑；误删或改名后恢复最后落盘的必需文件，断网也有效。 扩展关闭期间无法拦截文件系统操作，下次打开工作区时会从备份恢复。未保存缓冲区不属于落盘备份。
• 删除不传播至服务器；重命名按新增文件处理，原服务器文件仍保留。
• 0.5.0 起 SDK 由外部项目提供，工作区不再复制参考源码。
• SDK、.venv、.vscode、隐藏文件/目录、config.local.yaml/json、日志和缓存不上传。
• 前后端及插件须一起升级；重新安装下载包后，从网页重新打开应用，旧虚拟目录仍不支持新建。

本地运行步骤

1. 安装兼容的 Python 以及 Python / Pylance / Python Debugger 扩展，uv 为可选加速工具。
2. 执行 MES: 配置远程 SDK（wheel），或选择外部 SDK 项目，核对版本与部署环境一致。
3. 执行 MES: 安装 SDK / 初始化环境 并确认来源，插件准备 .venv、安装依赖并选择解释器。 默认解释器不符时，请自行准备匹配版本的虚拟环境；SDK 版本和 Python 版本不由插件写死。
4. 复制 config.yaml 为 config.local.yaml，改为测试环境地址和独立身份，避免接入生产产线。
5. 使用任务 MES: 本地运行 app.py，或 F5 MES: 本地调试 app.py。 插件检查测试配置及 SDK 安装来源；wheel 模式核对版本/哈希，源码模式核对 editable 路径。

打开应用不触发安装或执行。远程 wheel 安装需要网络；不执行容器专用 pre_run.sh。 环境安装与代码提示使用同一 SDK 来源，但不会更新容器；正式更新仍走镜像/依赖包部署流程。 其他 Python 扩展入口和终端手动运行不经过 MES 检查；请自行确认解释器和配置。 工作区 MES-LOCAL.md 包含详细说明。升级保留用户修改的配置，出现提示时需手动迁移旧运行入口。

0.3.1：网页强制断开 VS Code

• 应用列表和详情页在 VS Code 占用编辑权限时提供 强制断开 VS Code 按钮，确认后撤销当前会话并释放编辑占用。
• 接口 POST /mes/app/editor/apps/{uuid}/disconnect 只接受网页登录 JWT，检查应用查看及文件编辑权限。
• 撤销与获取编辑占用、文件保存共用应用行锁；先删除 Redis 会话，再释放租约。重连在行锁内再次检查会话，并发续期不能重建已删除的会话。
• 网页通过原有状态通道更新，通常约 2 秒内恢复编辑。VS Code 最迟在下一次身份校验时（约 10 秒）关闭通道，但旧连接的上传权限立即失效。
• 新版扩展遇到会话撤销或权限失效会停止自动重连。重新连接必须由用户从网页再次点击 VS Code 打开。
• 强制断开不会关闭本机 VS Code、删除本地文件或停止运行中的应用；未上传的本地修改继续保留，网页内容也仍受文件版本冲突检查保护。
• 同步更新后端、前端及扩展；本次无需新增数据库表。旧版扩展即使尝试重连，也无法使用已撤销的会话再次占用。

0.3.0：编辑长连接与网页只读

打开本地工作区时，扩展先通过 WebSocket 获得当前应用的独占编辑租约。 确认成功后网页应用列表显示 VS Code 正在修改，网页代码编辑器切为只读，禁止保存和恢复历史。 未保存的网页缓冲区不被替换；需要先复制备份，释放占用后仍须通过原有文件版本校验。

• 编辑状态按“工作区已连接”显示，不代表键盘此刻一定在输入。
• 同一应用只允许一个编辑连接上传，第二个 VS Code 窗口只能保留本地代码、等待占用释放。
• 关闭窗口、退出编辑器或执行 MES: 断开当前应用连接 会释放占用。
• 客户端每 10 秒发心跳，服务器 30 秒未收到心跳会断开；租约最长 45 秒失效， 进程异常退出也不会永久锁定。扩展断线后每 5 秒尝试重连，没有占用时禁止上传。
• 网页通过独立的只读观察长连接接收状态，服务端每 2 秒核对数据库，变化时推送。 网页状态通道断开时按未知状态处理，编辑器保持只读，而不是错误地显示空闲。
• 后端每 10 秒重新校验长连接身份、原登录和现有权限；原有会话自动续期机制保持。
• 租约写入 mes_app_editor_lease，服务启动自动建表。占用申请、续租和文件写入共用应用行锁； 新保存 API、旧网页保存 API、历史恢复均在数据库事务中检查占用，不只是前端禁用按钮。
• HTTP 上传必须同时携带应用会话和 X-MES-Editor-Lease。租约绑定连接随机值与会话摘要， 网页只接收布尔状态，不接收租约、会话凭证或用户登录信息。
• 先升级后端，再升级前端/代理和扩展。旧扩展不提供长连接租约，升级后端后将不能继续上传。 未升级后端时，新网页保持只读、新扩展暂停上传，避免无保护写入。

Nginx 已增加 /api/mes/app/editor/channel 的 WebSocket Upgrade 配置。 如果还有网关/Ingress，也必须转发该路径的 Upgrade/Connection 头，保持至少 60 秒读取超时。 认证通过首帧发送，不写入 URL；浏览器连接严格检查同源 Origin，桌面扩展不发送 Origin。

用户安装与使用

1. 安装桌面版 VS Code（最低 1.95）。
2. 在 MES 应用列表点击 VS Code 打开，从引导窗口下载 mes-vscode.vsix。
3. 打开 VS Code 扩展面板，在右上角 … 选择 从 VSIX 安装…，选择安装包。
4. 回到 MES 网页，点击 重新打开，允许浏览器打开 VS Code。
5. 检查扩展提示的 MES 服务地址，确认可信后选择 连接。
6. 新窗口会打开真实的本地项目文件夹，按工作区推荐安装 Python / Pylance。
7. 执行 Python: 选择解释器，选择与应用兼容的本地 Python 环境（当前 SDK 要求 Python 3.13+）。
8. 编辑后按 Ctrl+S / Cmd+S 保存，并查看底部 MES 同步状态。

新建的 MES 工作区关闭自动保存，避免在编辑途中频繁修改服务器文件。 编辑器不再显示脏标记只代表保存到了本机，不代表 MES 已更新。 底部状态区会分别显示上传中、待同步数量或「本地已保存，上传失败」。点击状态区或执行 MES: 同步本地修改 可重试上传。应用仍按原有部署机制运行，是否重启由用户明确决定。

支持已有及新建 UTF-8 文本文件的同步。删除不传播，重命名按新增处理，服务器旧文件保留。 本地环境与 SDK/配置不上传。不要把本地运行/调试当作生产容器运行环境。

从 0.1.0 升级

重新安装新的 mes-vscode.vsix 并重载 VS Code。先保存或备份旧 mes-app:// 工作区里的修改， 再回到网页点击 VS Code 打开。旧窗口不会自动转换，新打开的窗口才使用本地文件。 旧虚拟文件系统仍保留，避免升级时丢弃尚未关闭的编辑器缓冲区。

Python 与 SDK 代码提示

• 推荐设置 jutzeMes.sdkWheelUrl 并确认安装，Python/Pylance 使用应用 .venv 中的包，无需源码。
• 以下为可选源码模式：jutzeMes.sdkPath 必须是包含 pyproject.toml 和 jutze/__init__.py 的外部项目绝对路径。 不接受只有类型声明的目录，也不回退到插件内置 SDK。两种来源均未配置时可以编辑和同步，不能使用 MES 本地运行任务。
• 插件将该项目加入 python.analysis.extraPaths，保留用户已有的其他路径并清理旧快照路径。
• 标准库提示由选定的 Python/Pylance 提供；第三方库需安装到工作区 .venv。
• 未安装 Pylance 不会阻止应用文件同步；安装后自动更新分析路径。
• 若工作区不受信任，请核对来源后自行决定是否信任；插件不会绕过工作区信任。
• 外部 SDK 与容器的版本对应关系由部署配置确定；插件不声称已自动验证远端版本。

保存冲突

网页与 VS Code 保存都携带读取时的内容版本。服务器有新版本时返回冲突，不强制覆盖。 冲突后本地文件与同步基线保持不变，不能通过再次保存或重连绕过检查。

1. 运行命令 MES: 与服务器最新版本比较。
2. 确保本地编辑已落盘，即使上传发生冲突也可以继续。
3. 执行 MES: 备份本地文件并使用服务器版本，确认后扩展会先备份当前本地内容， 再拉取服务器版本。若仍有未保存的编辑，则拒绝替换。
4. 从备份中合并所需修改，再保存。期间如有其他人再次保存，将再次提示冲突。

VS Code 自带的「还原文件」只还原到本地磁盘，不会读取 MES；不要用它代替上述命令。

命令 MES: 刷新应用文件 只更新没有本地改动的文件，保留脏缓冲区、离线修改和本地删除。 重新打开工作区采用相同保护规则，不持续轮询远程变更。 命令 MES: 断开当前应用连接 清除本机凭证，并尝试撤销服务器会话。 本地源码、备份和同步基线不会删除，重新连接后仍可继续处理待上传文件。

缓存位置为 VS Code 为扩展分配的 globalStorage/jutze.mes-vscode/local/<连接ID>/： app/ 是本地源码，state.json 只存文件版本，backups/ 是冲突处理备份。 缓存中包含应用源码与配置，应按本地开发数据保护；凭证单独存入 SecretStorage。

认证与部署边界

• 扩展 ID：jutze.mes-vscode（支持离线 VSIX 和 Marketplace；离线安装仍不依赖 Marketplace）。
• 唤起格式：vscode://jutze.mes-vscode/open?server=<MES_API_BASE>&ticket=<ONE_TIME_TICKET>。
• 票据 90 秒有效、原子消费一次；票据被消费或过期后必须在网页重新打开。
• 0.2.1 起自动续期：访问有效期一小时，扩展每分钟检查，到期前五分钟续期。 保存/读取前和窗口重新获得焦点时也会检查，休眠/断网后七天内可恢复。 每次成功续期重新计算七天窗口；七天未续期需要从网页重新打开。
• 续期和每次请求都校验原 JWT 与现有 Casbin 权限，不续签原登录、不绕过权限。 原登录失效、应用删除或权限被撤销后停止续期。本地文件与待同步修改保留。
• 网络异常续期失败后间隔一分钟重试；并发请求合并为一次续期，不重放文件写请求。 会话标识仍在 SecretStorage 中，不进入 URL；Redis 原子更新仅限仍存在的会话， 断开删除后的连接不能被并发续期请求重新创建。
• 此升级需同时部署后端和安装新版扩展。旧后端不支持续期接口，不能只更新前端。 仍有效的旧会话可迁移；已经被旧版 Redis TTL 清理的连接需从网页重新打开一次。
• 浏览器 JWT 不发送给扩展；会话凭证保存于 VS Code SecretStorage，不写入工作区文件、 URL、日志或普通配置。服务端 Redis 使用带 MES Master UUID 命名空间的哈希键和 TTL。
• 会话仅能访问绑定的应用和专用编辑 API，不能作为普通 JWT 使用。
• 权限沿用平台当前的 Casbin 操作权限，不新增项目当前并不存在的应用所有者 ACL。
• 用户电脑必须能够访问浏览器同源的 /api，不是只允许服务器本机访问的内网地址。
• 推荐 HTTPS。HTTP 仅适用于可信内网，扩展连接前会明确警告；不禁用证书验证、 不携带凭证跟随重定向。
• 新接口请求 JSON 上限 8 MiB。旧客户端仍可调用旧保存 API，旧客户端自身不具备新版本保护； 发布时应同时升级前后端，并让用户刷新旧页面。

构建与交付

在本目录执行（Node.js 20+，按锁文件安装）：

npm ci --ignore-scripts
npm test
npm run package

产物写入前端 public/extensions/mes-vscode.vsix，随 Vite 构建进入 dist/extensions/， 再随现有前端镜像部署。离线用户不需要 Node.js 或 npm。 扩展有修改时必须重新生成 VSIX；可先打包扩展，再构建前端。 也可在前端根目录运行 npm run build:vscode 完成扩展依赖安装、单元测试和打包。

SDK 独立发布，前端打包不读取 SDK 仓库。构建前执行 npm run check:no-python，拒绝源码目录内的 Python 文件或 SDK 快照；打包时再次检查 VSIX 文件清单。旧的含 SDK 安装包不应继续放在前端交付目录中。

真实 VS Code 集成测试（需已安装桌面版和 code CLI）：

npm run test:vscode

若 code 不在 PATH，使用环境变量 VSCODE_CLI 指向其完整路径。 测试启动独立临时配置窗口和仅监听本机的模拟 MES HTTP 服务，验证真实文件系统、 文档保存、中文路径和冲突处理；不修改已有 VS Code 配置，不连接生产环境。 它不替代已部署 MES + Master 的完整端到端验收。 设置 MES_TEST_PYTHON_EXTENSIONS 为已安装 Python/Pylance 的扩展目录，测试会将对应扩展 复制到临时目录，并实际断言 jutze.、jutze.hooks.、标准库及函数参数提示。 可通过 MES_TEST_PYTHON 指定测试解释器；测试不执行 MES 应用代码。

前端需要同版本 MES 后端提供：

应用会话通过 X-MES-Editor-Session 请求头发送。路径必须是当前应用内的规范相对路径。 读取返回 content 和 revision；保存请求体为 { "content": "...", "revision": "..." }。 新建文件使用同一个 PUT 接口，显式传 "revision": "new"；不存在才创建，文件/目录冲突返回 409。 历史恢复请求体为 { "historyId": "...", "revision": "..." }。 冲突/编辑占用失效返回 HTTP 409，不修改文件、不产生多余历史版本。所有 HTTP 响应禁止缓存。

验收清单

• 未安装扩展：引导可下载真实 VSIX，仍可进入网页详情。
• 已安装扩展：打开正确应用，UUID 不因 JavaScript 数值精度而变化。
• 运行/停止的应用都可编辑；保存不触发启动、停止或重启。
• 在一端保存，另一端重新读取能看到内容；沿用最近 10 条文件历史。
• 网页/VS Code 并发保存、历史恢复遇到过期版本都不覆盖。
• 超时票据、重复票据、其他应用 UUID、无权限、异常路径、过期登录被拒绝。
• 本地保存与远程同步分别显示；网络失败后本地文件保留，重试不绕过冲突检查。
• 中文、空格、#、%、嵌套目录正常读写。
• VS Code 重启/休眠后自动续期；原登录失效或七天未续期才需要从网页重新连接。
• 新工作区使用本地 file://，SDK 方法、Hook 方法及标准库能通过 Pylance 提供提示。
• SDK 目录更改、扩展升级后保留用户的其他 Python 搜索路径。

实现使用 VS Code 本地工作区、文档保存事件、registerUriHandler 和 SecretStorage； FileSystemProvider 仅用于兼容旧虚拟工作区。