[xiaoyumuxi]

概要

Issue #827 第三阶段（P3）的第一部分：macOS 宿主接入插件 VCS Provider。装上 Subversion 社区插件后，Lithe 能识别工作区里的 SVN 工作副本，在左侧“Subversion”工具窗口里查看变更、勾选提交、更新、回滚、标记冲突已解决、清理，查看文件和工作副本的历史，与基线比较；项目树按 SVN 状态着色，项目树里的重命名、移动交给 Provider（svn move）记录。

SVN 插件不再放在主仓库，改为像 Cargo 插件一样的独立社区插件：Lithe-IDEA/lithe-plugin-svn，插件 ID io.github.lithe-idea.svn-support，vendor.signatureRequirement 为 none（不需要 Lithe 签名）。原来放插件的 #1432 已关闭，其中与具体 VCS 无关的部分并入本 PR。

本 PR 的 base 改为 feat/827-vcs-provider-core，合入顺序为 #1430 → 本 PR（#1430 合并后 base 改成 preview）。宿主里没有任何 VCS 或插件名字的分支，界面看 Provider 协商的能力决定显示什么。

相对上一版（114dcc1be）的变化

评审过上一版的话，先看这一节。

1. SVN 插件搬到独立仓库

• 不再包含 Plugins/mac/Official/SvnSupport/、rust/lithe-core/tests/plugin_sdk/svn.rs，以及 verify-rust-core-crates.sh 里运行 SVN 插件测试的步骤。主仓库 CI 不需要装 svn。
• 也不再包含 feat(svn): Subversion 官方插件 Provider（#827 P2） #1432 为“官方 SVN 插件”做的配套改动：OfficialPluginCatalog.Entry 改成可选 language、LSPControlCenterView 跟着改、ModuleRuntimeTests 的断言、Rust plugin_sdk 测试辅助函数的搬动。这些只在 SVN 是官方插件时需要，现在和 feat/827-vcs-provider-core 保持一致。
• 插件仓库内容：Provider 源码、录制的 svn --xml 样例与错误输出、解析测试、sdk.lock.json 按上游提交和逐文件 SHA-256 固定 Node SDK、按同一宿主提交构建 Core 跑的端到端场景测试（状态、提交、过期提交、更新与冲突、resolve、回滚、移动、删除、历史分页、Annotate、二进制文件、changelist），以及 CI 和 Release 工作流。暂未打 tag、未发 Release，也没有向 Lithe Store 提交索引。
• 插件仓库这次额外修了两处：
  • 在 changelist 里的文件原来不会出现在状态里（svn status --xml 把它们放在 <changelist> 下，与 <target> 同级），现在会照常列出。
  • 移动未版本化文件时改为不覆盖已有的目标文件或目录，目标已存在时报 svn.move.destinationExists。

2. 从 #1432 并入的通用部分

• ModuleID.vcsProvidersExtension(_:) 与 LanguageExtensionModuleManifests.vcsProviders(...)：每个声明 vcsProviders 的插件生成一个 <插件 ID>.vcs-providers 模块，默认不启用，启用状态随插件。
• DeclarativePluginDescriptor 读取清单的 vcsProviders（只读 id 和 displayName），为每个 Provider 生成工具窗口和命令贡献。
• 契约 shared/contracts/vcs-provider-v1.md：示例里的插件 ID 改为 io.github.lithe-idea.svn-support；lsp.vcsRequest 示例的键名改为实际使用的 sessionId、operationId；“Subversion provider notes”改为指向社区插件仓库，详细映射看插件 README。
• sdk/node/examples/sample-vcs/provider/main.mjs 注释里的“官方 Subversion 插件”改为“Subversion 社区插件”。
• Plugins/mac/README.md 新增 “Subversion community plugin” 一节，说明插件独立维护发布、需要宿主声明 vcsProviders、SVN 的样例和 Core 兼容测试在插件仓库，主仓库只保留通用契约测试和 SDK 样例 Provider。

3. 测试不再依赖 SVN 插件

• VcsProviderHostTests 用契约自带的 fixture 清单（shared/contracts/plugins/v1/fixtures/svn-provider.plugin.json）测真实 Rust Core 的根识别、归属、回复校验和安装审核。
• PluginManagerTests.vcsProviderPluginGetsOneDisabledModuleForItsProviders 用 SDK 样例 Provider（sdk/node/examples/sample-vcs/plugin.json）验证 Core 接受 vcsProviders 插件，并且只生成一个默认停用的模块。
• 上一版描述里写的 VcsProviderProjectMoveTests 实际名为 VcsProviderAppModelTests（同一文件），这次补了关闭窗口的用例。

4. 自审和评审修正（f76025c18）

• 包住工作区的工作副本也会刷新：打开的目录位于某个 SVN 工作副本内部时（根是 .. 这类上层目录），工作区的文件监听看不到上层 .svn，在终端里提交或更新后工具窗口不刷新。现在 VcsProvidersFeatureModel 为这类根单独监听 Provider 声明的元数据目录（只监听 .svn，不监听整个上层工作副本）；监听丢事件或目录消失时按标记变化处理，重新识别根。工厂由 MacServiceContainer 注入 MacDirectoryWatcherFactory。
• 移动两端都要归同一个根：项目树移动交给 Provider 前，先按 Core 的归属规则（vcs.ownerOf）确认源和目标都属于这个根。目标落在嵌套的 Git 仓库里，或者落在还没选 VCS 的歧义目录里时，不再当成 svn move，退回普通的磁盘移动。
• 关闭窗口后 Provider 不会被重新拉起：shutdownProjectSession 调用新的 VcsProvidersFeatureModel.shutdown()，停掉这个窗口的所有 Provider 和待执行的刷新。修了一个竞态：窗口关闭时还在进行的工作区扫描结束后会调用 loadVcsProviders，以前会把 Provider 重新启动；现在 shutdown() 之后的加载请求一律只清空。关闭的会话模型不会被复用，所以不需要恢复入口。
• 工具窗口图标：Provider 的工具窗口和命令面板项沿用宿主的版本控制图标（PluginUIIcon(host: "git")），以前侧栏按钮显示的是通用插件图标。
• 首次读取状态时显示“正在读取更改…”：第一次读取还要启动 Provider 进程，可能要几秒，以前这段时间是空白。
• 辅助功能：变更行合并成一个辅助功能元素后，VoiceOver 只能勾选。现在补了选中状态，以及“选择”（默认操作）、“显示差异/打开文件”、“纳入提交”三个操作；“显示差异”还是“打开文件”和双击的规则一致（新提取的 opensDiff）。
• 新增测试：watchesTheMetadataOfAWorkingCopyThatEnclosesTheWorkspace、providerWindowsShowTheVersionControlIcon、closingTheProjectWindowStopsTheWorkspaceProviders；movesTrackedItemsThroughTheProviderAndLeavesTheRestToTheDisk 补了目标落在嵌套 Git 仓库时退回磁盘移动的用例。
• Agent Note、能力版本 Note 和功能矩阵同步更新：记录社区插件的决定和不采用“官方插件留在主仓库”的原因，以及上面几条宿主行为。

完整改动

宿主能力与安装审核

• PluginManifest.hostCapabilities 声明 vcsProviders: [1]，Core 从此接受声明了 vcsProviders 的插件。
• PluginProgram 新增 packagedVcsProvider、systemVcsProvider、runtimeVcsProvider 三种程序类型，以及 vcs、vcsClientCommands、entry、runtimeArguments、mayUseNetwork 读取方法。
• 安装确认页显示 Provider 的启动命令、客户端命令（如 Client: svn）和“可能连接仓库服务器”，用户批准前就知道插件会运行哪个程序。

Provider 进程与 Core 调用

• VcsProviderContracts.swift：宿主侧的 VCS 操作（状态、提交、更新、回滚、标记已解决、清理、历史、基线内容、文件操作）、回复模型、Provider 错误、工具窗口贡献 ID 与可见性键。
• RustVcsOperations：封装 vcs.detectRoots、vcs.ownerOf、vcs.decodeReply，根识别、文件归属和回复校验都由 Rust Core 决定。
• RustCoreBridge.lspVcsRequest / LanguageServerRuntimeCore.requestVcsProvider / LanguageServerSession.vcsRequest：经 lsp.vcsRequest 发送一个 VCS 操作并等待 requestCompleted。
• RustDeclarativePluginOperations.vcsProviderLaunchPlan 与 MacPluginLanguageServerLaunchResolver.resolveVcsProvider：展开 Provider 的启动计划，校验插件包内路径，在插件状态目录（Application Support）下为每个 Provider 建 ${stateDir} / ${workspaceStateDir}，不写 app bundle 和插件包。
• MacVcsProviderSessions：每个“插件 × VCS × 工作区”一个进程，第一次请求时启动，切换工作区、停用或替换插件时停止；插件设置变化后下一次请求重启。VCS 客户端（如 svn）单独解析并在每个请求里传给 Provider。

功能模型

• VcsProvidersFeatureModel（按窗口创建；启动时有插件声明 vcsProviders 才创建）：
  • 打开工作区时识别根，记录歧义目录；用户选择的 VCS 由 MacVcsRootMappingStore 按工作区存进应用偏好（Vcs.RootMappings.<摘要>），不再歧义时自动删除。
  • 读取每个根的状态，嵌套 Git 仓库和工作区外的变更不进项目树。
  • 文件变化合并约 0.8 秒后刷新受影响的根；元数据目录里只有 Provider 声明的 metadataPaths（SVN 是 .svn/wc.db）会触发刷新，宿主自己的操作期间和结束后 2 秒内忽略元数据变化；出现或消失标记目录时重新识别；包住工作区的工作副本单独监听其元数据目录。
  • 提交、回滚、更新、标记已解决、清理、移动同一时间只运行一个，结束后刷新状态；Provider 错误码按契约给出中文提示（认证失败、工作副本过期、冲突、锁定、格式不支持、客户端不可用）。
  • 提交信息草稿按根保存，关闭工具窗口不丢失。
  • 窗口关闭时 shutdown()，之后不再加载任何工作区。
• AppModel+VcsProviders：打开工作区时识别根，工作区文件变化转发给功能模型；插件启用状态变化时重新识别，关闭工作区时停止进程。

工具窗口（Views/Vcs/）

• 每个 Provider 贡献一个左侧工具窗口，VcsProviderToolWindowRegistration 只按贡献上的 vcsProviderPluginID、vcsProviderID 键注册，没有 VCS 名字。启动后才安装的插件，窗口提示重启 Lithe。
• “变更”页：冲突、变更、未版本控制文件三组；默认只勾选“变更”组，冲突文件和被忽略的文件不能勾选；移动的文件提交时带上原路径。工具栏有刷新、更新项目、回滚（二次确认）、显示差异、标记为已解决、清理工作副本。多个根时可切换，显示当前修订和分支，并展示识别问题、歧义目录选择、截断提示和操作结果。右键菜单：显示差异、打开、显示历史、标记已解决、回滚、复制路径、在 Finder 中显示。
• “历史”页：工作副本历史和单个文件的历史，分页加载，展开查看每个修订改动的文件。
• 差异：窗口级弹出面板（RootView 显示 presentedDiff），项目树右键菜单也能打开；复用本地历史的比较算法和 Git 的 DiffPaneView，超过 2 万行时退成左右两栏纯文本；二进制和超过 2 MB 的文件不比较。

项目树与文件操作

• 项目树通过只观察 VCS 功能模型的包装视图拿到插件根的状态，项目树本身仍是 .equatable()；同一文件 Git 和插件都有状态时显示 Git 的。文件行显示 Provider 状态字母，右键菜单新增“显示 差异”（Provider 支持基线内容、文件有基线时）。
• LitheWorkspaceModule.WorkspaceFeatureModel 新增注入的 moveTrackedItem 回调：重命名和拖动移动先交给拥有该文件的 Provider，Provider 不跟踪、拒绝或两端不归同一个根时退回原来的磁盘移动。工作区模块不认识任何 VCS。

文档、矩阵与本地化

• 提议 Note 2026-10-22-unified-vcs-provider-model.md：第 7 节改为“SVN 作为社区插件”，记录 P2、P3 第一部分完成的内容和原因，新增“SVN 作为官方插件留在主仓库”的不采用理由；状态读取热路径改为“先整根查询、实测太慢再按能力版本加增量参数”。
• 能力版本 Note：vcsProviders: [1] 等 macOS 接入会话后才加入的说明。
• 功能矩阵 vcs-subversion-and-plugin-providers：macOS 改为部分实现；验证项写明 SVN 回归在插件仓库 CI、主仓库只保留通用契约回归，以及宿主自动化覆盖的场景。
• 新增所有界面文案的简体中文翻译（含“正在读取更改…”）；本地化测试检查这些键存在且占位符一致。原来比较界面用的 “Base” 键已有“目标”的含义，改用新键 “Base revision”（基线版本）。

暂不包含

• 编辑器 gutter 与 Annotate、交互式认证（lithe/vcs/authenticate 仍按未知请求回绝，认证失败时提示先用命令行登录一次）、把 lithe/vcs/execution 执行报告接到项目控制台。
• 对照 IDEA Subversion 工具窗口还缺的部分，下一个 PR 处理：
  • “仓库”页的主从布局（左边修订列表、右边该修订的文件树）、按日期分组、按作者/日期筛选和搜索；这些只需要宿主改。
  • 查看历史修订里某个文件的差异：契约 v1 只能取 BASE 内容，要加可选能力（例如 revisionContent）。
  • “传入”页（服务器上还没更新到本地的修订）：要加可选能力（例如 incoming）。
  • “工作副本信息”：契约已有 head.location，宿主可以先显示 URL 和修订；仓库根、depth 等要扩展回复。
  • 本地更改按 changelist 分组：要在状态回复里加可选字段。
  • Git 和插件 VCS 共用一个版本控制窗口：等 Git 迁到同一模型时再做，目前同时有 Git 和 SVN 的项目会出现两个窗口。
• SVN 插件的 Release 和 Lithe Store 上架：要等带 vcsProviders 能力的宿主版本发布后再做。
• Windows 宿主（P4）。

测试

• VcsProviderHostTests（15 个）与 VcsProviderAppModelTests（2 个，经真实 AppModel）：
  • 用假 Core 和假 Provider 测功能模型：根识别与嵌套 Git 的归属、刷新规则（未声明的元数据不刷新、宿主操作期间忽略元数据、标记目录触发重新识别）、包住工作区的工作副本元数据监听、同一时间只运行一个操作、移动跟踪与拒绝、歧义目录选择的保存与清理、错误提示、外层工作副本的路径换算。
  • 工具窗口规则：分组和默认勾选、移动的两个路径、修订摘要与日期显示、工具窗口和命令使用版本控制图标。
  • 真实 Rust Core：用契约 fixture 清单识别 .svn 根与嵌套 .git、文件归属、回复校验（未知状态被拒绝）；真实安装审核显示 Provider 命令、客户端和联网。
  • VcsProviderAppModelTests：经项目树移动时被跟踪的文件交给 Provider、未版本控制的文件走磁盘移动；关闭项目窗口停止 Provider，之后迟到的工作区加载不再启动。
• PluginManagerTests：SDK 样例 Provider 经 Core 校验，生成一个默认停用的模块。
• AppLocalizationTests：新文案的简体中文翻译与占位符。

本地验证：

• 完整 macOS 测试（test-stability-macos.sh）2735 个，只有 PluginUIIconTests 的两个渲染取色测试失败（15 个问题都来自这两个测试）。它们不涉及本 PR 的代码，单独运行也失败，上一版在 CI 的 Swift tests 中通过，是本机 macOS 27.2 的渲染差异。
• VcsProvider 相关 18 个测试单独运行全部通过。
• verify-shared-contracts.sh、verify-platform-feature-matrix.sh、verify-module-boundaries.sh、verify-agent-notes.sh、verify-runtime-bundle-immutability.sh 通过。
• 插件仓库：LITHE_SVN_INTEGRATION=1 node scripts/test.mjs 24 个测试全部通过（含按固定 Core 跑的 svn 场景测试），测试结束后没有残留的 Core 或 Provider 进程。

后续修正（078d0bd、b8c81d9）

• 隐藏 .svn：项目树、搜索、索引和工作区监听像 .git 一样隐藏 .svn（Swift 与 Rust Core 的内置列表同步），避免 .svn/pristine 的基线副本进入索引。
• 按根监听元数据：每个插件根单独监听自己的标记目录（含包住工作区的 ../.svn）；工作区里新出现的条目会在后台检查标记，新检出的工作副本能被识别。
• 客户端缺失：找不到 svn 时按契约报 vcs.tool.unavailable，工具窗口先显示安装提示。
• 基线比较判断统一：VcsRootState.comparesWithBase 供工具窗口双击、辅助功能动作和项目树右键共用。
• 移动归属等待期：等 Core 判断归属时开始了别的操作，就直接退回磁盘移动。
• ..repo 判断：根 ID 只有全部由 .. 段组成时才算外层工作副本，与 Core 一致；工作区内名为 ..repo 的根不再丢失文件状态，补充回归用例。
• 适配基线：基线已按 refactor(plugins): 契约发布到 lithe-plugin-docs，fixture 按能力改名，SDK 移出主仓库 #1442 把 SDK 移到 lithe-plugin-docs，PluginManagerTests 改用契约 fixture vcs-provider.plugin.json；VCS 工具窗口提交栏改用 preview 的 ActionButton.spacing（Commit.buttonBorderInset 已删除）。
• 测试修正：watchesTheMetadataDirectoryOfEveryRoot 在第二次投递元数据事件前推进时钟（读状态会开始全局静默期）。

本地验证：VCS/插件管理/市场/文件可见性/项目树相关 75 个 Swift 测试通过；cargo test -p lithe-core、cargo fmt --check、契约、Agent Notes、功能矩阵（含变更门禁）、模块边界、服务边界、测试稳定性、Rust Core 注释、bundle 不可变性检查均通过。完整 macOS 测试在本机有大批异步等待超时，同一组套件在不含本 PR 的基线工作树上同样失败，判断为本机环境问题，以 CI 为准。

[lithe-code-review]

Lithe Review

结论： ⛔ 有阻塞
范围： feat/827-svn-support ← feat/827-svn-host · head: 114dcc1

Findings

1. [P1] 将 VCS Provider 清理接入原生项目窗口关闭路径
   macos/Sources/Lithe/Platform/MacOS/MacServiceContainer.swift:794

   • 实际影响：新增的 Provider 会话未随项目窗口关闭而停止，后台进程和轮询任务会残留；重复打开、关闭项目会累积资源。
   • 触发条件：已启用 SVN 插件，工作区状态读取已启动 Provider，然后关闭该项目的独立窗口，同时保持 Lithe 其他窗口运行。
   • 复现步骤：打开 SVN 项目并等待状态显示，关闭窗口，再重复操作。静态调用链为 RootView.closeWindowAfterProjectCleanup → resetDedicatedWindowSession → AppModel.shutdownProjectSession()；后者没有调用 VCS reset。新增 reset 只位于工作区切换、显式关闭路径（AppModel.swift:947、1014）。VCS 对应的 DeclarativeWorkbenchModule.shutdown() 为空，不能代为清理；LanguageServerSession.swift:943–946 的轮询任务还会强引用会话，释放窗口引用也不能结束它。
   • 来源：本次引入。新增服务持有独立进程，但未接入既有项目会话销毁入口。

2. [P2] 文件移动应使用 Core 判定的实际归属
   macos/Sources/Lithe/Application/Features/VcsProvidersFeatureModel.swift:563–568

   • 实际影响：嵌套 Git 根或未映射的歧义目录中的文件，仍可能被交给外层 SVN Provider 移动，产生不符合 Core 归属结果的 SVN 删除、添加记录。
   • 触发条件：外层 SVN 工作副本中的已跟踪目录，同时包含一个嵌套 Git 根；用户从项目树重命名其中的文件。
   • 复现步骤：让 SVN 跟踪 module/a.txt，在 module 建立 Git 仓库后打开外层工作区，再重命名该文件。rootPath(of:)（第 663 行）只遍历插件 roots，忽略 allRootIDs 中的 Git 根和 ambiguous；而 isUnversioned 将无树状态视为可跟踪，因此最终发送外层 SVN .move。官方 Provider 随后执行 svn move（svn-provider.mjs:378–379）。树状态投影已使用 planner.owners 排除这些路径，移动操作却未遵循相同规则。
   • 来源：本次引入。新增项目树移动回调使用了与 vcs.ownerOf 契约不同的归属判断。

3. [P2] 为工作区外的 Provider 元数据注册监听
   macos/Sources/Lithe/Models/AppModel/AppModel+VcsProviders.swift:19–20

   • 实际影响：打开 SVN 工作副本的子目录时，外部命令造成的纯元数据变更不会自动刷新，工具窗口和项目树会持续显示旧状态，直到手动刷新。
   • 触发条件：工作副本位于 /wc，Lithe 只打开 /wc/subdir；外部操作仅改变 /wc/.svn/wc.db。
   • 复现步骤：先创建 /wc/subdir/a.txt 并等待界面显示未版本控制，待刷新静默期结束后，在外部执行 svn add /wc/subdir/a.txt。新增接线只接收现有工作区文件通知；DirectoryWatchConfiguration.physicalRoots 只有工作区和 Git 上下文，MacDirectoryWatcher.swift:168–171 也只发布工作区内的普通路径，所以外层 .svn/wc.db 无法到达 workspaceFilesChanged。本 PR 已明确支持外层工作副本的路径换算，但未扩展相应监听范围。
   • 来源：本次引入。新增自动刷新功能依赖了无法覆盖所支持根范围的事件源。

Scope Check

• 关联 Issue：[Feature] 希望能够支持svn #827 要求跨平台 SVN 支持；本 PR 仅实现 macOS P3 第一部分，不能视为整个 Issue 完成。
• 已完成范围：宿主能力与安装审核、Provider 启动和请求、状态与主要操作、历史和差异、项目树展示及移动接线。
• 未完成范围：gutter、Annotate、交互式认证、执行报告接入项目控制台、官方插件索引发布，以及 Windows P4；正文、Note 和功能矩阵已说明阶段边界。
• 能力复用：复用 Rust Core 根识别与回复校验、现有语言服务进程通道、SVN CLI 和既有差异组件，未发现需要另行报告的并行领域实现问题。
• 三项 Finding 均由本次宿主接入引入，属于其生命周期、文件归属和刷新职责范围。

Suggestions

1. 提交前必须修复 Finding 1： 在 shutdownProjectSession() 首次挂起前停止 VCS 功能，取消待处理任务并停止启动中、运行中的会话；补充原生窗口关闭路径的确定性回归测试，验证 Provider 停止及进程登记释放。
2. 非阻塞，针对 Finding 2： 对移动的源、目标使用 planner.owners(roots:ambiguous:paths:)，仅当两者实际归属于同一插件根时调用 Provider；覆盖嵌套 Git 和未映射歧义目录。
3. 非阻塞，针对 Finding 3： 将检测到的 Provider 元数据路径注册为独立监听输入，使工作区外的元数据事件也能触发 VCS 刷新；补充从 watcher 到功能模型的测试。
4. 补充安装审核、VCS 工具窗口、历史、差异和项目树的截图；已有界面修改提供前后对比。当前提供的上下文没有截图，视觉效果尚未验证。

Summary

整体接入复用了已有 Core、进程通信和 UI 组件，阶段范围清楚。当前需要先修复项目窗口关闭后的进程清理遗漏；另两项建议涉及已支持场景中的归属一致性和自动刷新。现有测试覆盖了较多模型规则，但未覆盖上述实际窗口销毁与元数据监听调用链。

Verification

• 实际检查：固定 base...head 的完整 40 文件清单及相关调用链，重点包括功能模型、Provider 会话、启动解析、Swift/Core 契约、项目树移动、窗口销毁、文件监听、UI、测试和矩阵。仅执行静态只读检查。
• 作者报告：4 组共 46 个测试通过；完整 macOS 2731 个测试中有两个渲染测试失败，作者称在基线同样复现；矩阵、模块边界、Agent Notes 和 bundle 不可变性检查通过。以上均未由本次审查独立验证。
• 已提供 CI：多个 gate、矩阵及 Agent Notes 检查成功，但 Swift、Rust、Windows 和插件实际测试作业多项为 skipped；不能据此认定运行时和跨平台测试已通过。
• 本次未运行任何仓库代码、测试、构建、验证脚本或应用，也未访问网络。
• 验证缺口：真实 Provider 的窗口关闭清理、嵌套根移动路由、外层 SVN 元数据监听，以及 UI 截图。上述复现路径来自静态调用链分析，未动态执行。