Skip to content

feat(plugins): macOS 设置页接入工具链提供方查询 (#1581) #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FxRayHughes merged 1 commit into from
Nov 1, 2026
Merged

feat(plugins): macOS 设置页接入工具链提供方查询 (#1581) #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions .agents/notes/proposed/architecture/2026-10-31-plugin-injected-toolchains.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

## 先说结论

从 Dock 启动时找不到版本管理器安装的运行时、项目要求的版本未生效，不能靠宿主逐个补目录和版本文件解析器解决。本方案把工具定义、安装事实提供方和使用方分开：插件说明工具是什么，版本管理器回答当前事实，宿主只提供统一选择、查询和环境展示框架；Java、Maven 等定义全部由插件贡献，不保留宿主内置定义表或兼容别名。当前已实现 Core 基础切片及 macOS 只读设置页；macOS 设置页已按声明式路线真实扫描本机安装、运行定义的版本探测并交 Core 选择，尚未接入两端的查询进程、文件监听、保存和运行时消费者。完整方案仍在本提案中跟踪，不能把页面出现解释成产品已能使用 mise 或已经完成工具迁移。
从 Dock 启动时找不到版本管理器安装的运行时、项目要求的版本未生效，不能靠宿主逐个补目录和版本文件解析器解决。本方案把工具定义、安装事实提供方和使用方分开：插件说明工具是什么，版本管理器回答当前事实，宿主只提供统一选择、查询和环境展示框架；Java、Maven 等定义全部由插件贡献，不保留宿主内置定义表或兼容别名。当前已实现 Core 基础切片及 macOS 只读设置页；macOS 设置页已按声明式路线真实扫描本机安装、运行定义的版本探测并交 Core 选择，并通过插件后端查询提供方、监听其输入后整份重查；Windows 查询、保存和运行时消费者尚未接入。完整方案仍在本提案中跟踪，不能把页面出现解释成产品已能使用 mise 或已经完成工具迁移。

## 问题

Expand Down Expand Up @@ -106,9 +106,9 @@ Core 基础切片先独立验证固定值，因此低层提供方超时不能撤

插件停用或卸载后，撤销其工具行、使用方、导出变量和设置页，取消它拥有的查询及监听；写下的固定值保留，重新启用再校验并恢复。存在固定值不代表定义仍然有效，不能靠残留固定继续导出环境或启动程序。所有用户文案实现时进入 `shared/i18n/`，不把原型里的字符串直接写进视图或服务。

当前 macOS 页面先交付通用只读框架：构建分组新增“运行环境”和“环境来源”，保留旧项目页，直到真实使用方迁移后再删除旧链路。加载器只读取已注册且已启用插件的声明与本机 `local.json`；固定继承仍调用 Core，不在 Swift 维护第二份规则。页面只显示读到的事实：存在的版本文件只说明“版本未查询”，固定值显示“已保存，未验证”；全局默认列出登录 Shell 里定义声明的 home 变量及其探测出的版本，再列 `PATH` 上按声明顺序找到的第一个命令并标“版本未验证”（不运行它）；自动检测列出声明式扫描找到并通过 Core 校验的安装，版本最高的打勾，同版本不同 home 标冲突，未通过校验的只计数并在悬停里给原因。提供方的全局默认与安装在查询客户端接入前不显示；使用方与变量没有事实就不显示。添加、切换、保存和查询还没有真实实现，所以界面上直接不放这些控件，也不放禁用的占位按钮。目录树只列项目根目录、自己有版本文件或固定值的目录及其上级，扫描与行数有上限，超出时用诊断说明覆盖了多少目录。隔离预览（`--toolchain-settings-demo`，仅 Debug）只用样例插件清单代替已安装插件：工作区是真实文件（临时生成或 `--toolchain-demo-workspace` 指定），固定、版本文件、自动检测和登录 Shell 都走生产加载器、Core 和启动时的同一读取流程；它不进入生产插件表或运行流程，退出时删除临时目录。远程工作区在读本机文件前拒绝。
当前 macOS 页面先交付通用只读框架：构建分组新增“运行环境”和“环境来源”，保留旧项目页，直到真实使用方迁移后再删除旧链路。加载器只读取已注册且已启用插件的声明与本机 `local.json`；固定继承仍调用 Core，不在 Swift 维护第二份规则。页面只显示读到的事实：存在的版本文件在提供方回答前说明“版本未查询”，回答后显示提供方原文的要求和对应安装版本，固定值显示“已保存，未验证”；全局默认列出登录 Shell 里定义声明的 home 变量及其探测出的版本，再列 `PATH` 上按声明顺序找到的第一个命令并标“版本未验证”（不运行它）；自动检测列出声明式扫描找到并通过 Core 校验的安装，版本最高的打勾，同版本不同 home 标冲突，未通过校验的只计数并在悬停里给原因。提供方报告的全局要求列在全局步骤，安装并入自动检测并保留提供方归属；使用方与变量没有事实就不显示。添加、切换、保存和查询还没有真实实现，所以界面上直接不放这些控件，也不放禁用的占位按钮。目录树只列项目根目录、自己有版本文件或固定值的目录及其上级，扫描与行数有上限，超出时用诊断说明覆盖了多少目录。隔离预览（`--toolchain-settings-demo`，仅 Debug）只用样例插件清单代替已安装插件：工作区是真实文件（临时生成或 `--toolchain-demo-workspace` 指定），固定、版本文件、自动检测和登录 Shell 都走生产加载器、Core 和启动时的同一读取流程；它不进入生产插件表或运行流程，退出时删除临时目录。远程工作区在读本机文件前拒绝。

来源页只展示两类已有事实。第一类是登录 Shell 读取：使用的 Shell、读取状态、变量数量、耗时与时间，以及 `PATH` 各目录来自登录 Shell 还是 Lithe 的启动环境。其他变量可能含有密钥，只计数不显示值。“重新读取”只刷新子进程缺少的变量和下次启动用的 `PATH` 缓存，不改本进程的 `PATH`（线程启动后 `setenv` 不安全）；发现 `PATH` 变了就提示重启。第二类是插件声明的版本管理器：它监视的文件、本项目里实际找到的文件，以及来自哪个插件。提供方的运行状态、查询命令、耗时和全局默认，在原生查询客户端接入前一律不显示，不保留占位徽标。
来源页只展示两类已有事实。第一类是登录 Shell 读取：使用的 Shell、读取状态、变量数量、耗时与时间，以及 `PATH` 各目录来自登录 Shell 还是 Lithe 的启动环境。其他变量可能含有密钥，只计数不显示值。“重新读取”只刷新子进程缺少的变量和下次启动用的 `PATH` 缓存，不改本进程的 `PATH`（线程启动后 `setenv` 不安全）；发现 `PATH` 变了就提示重启。第二类是插件声明的版本管理器：它监视的文件、本项目里实际找到的文件，以及来自哪个插件。每个版本管理器显示最近一次查询的结果：耗时，或提供方原样给出的失败原因（如未受信任的配置），不替用户执行 trust 或安装。

macOS 的声明式路线由 `MacToolchainDiscovery` 执行，宿主不认识任何工具名，只照 `discoveryPlan` 做三件事：

Expand Down Expand Up @@ -147,7 +147,7 @@ macOS 的声明式路线由 `MacToolchainDiscovery` 执行，宿主不认识任
| 阶段 | 交付内容 | 必须证明 |
| --- | --- | --- |
| 1：提案 | 本笔记、隔离的清单贡献、查询和解析、`pins` 契约草案及 fixture | Java 风格定义、mise 提供方、未定义工具反例可读且一致；未实施的草案字段不能被误当成已支持能力 |
| 2：Core 与查询客户端，部分完成 | Core 已支持定义/答案校验、目录固定、四层解析、同时列出扫描规则与提供方的发现计划、设置页候选（`toolchains.candidates`）、只报告安装的提供方和版本校验；macOS 设置页已接入声明式扫描与版本探测；macOS 查询客户端和监听未接入 | 已有纯数据测试保护固定失效、来源与最低版本、冲突、路径和数量边界，以及只扫描、只由定义插件自供、两条路线报告同一 home 时只算一份；macOS 用真实临时目录和注入的探测证明扫描、工作区排除、只探测 Core 返回的文件和冲突；取消、真实超时、文件新建/删除、全量查询及进程回收仍须平台实现证明；不新增宿主工具表 |
| 2：Core 与查询客户端，部分完成 | Core 已支持定义/答案校验、目录固定、四层解析、同时列出扫描规则与提供方的发现计划、设置页候选（`toolchains.candidates`）、只报告安装的提供方和版本校验；macOS 设置页已接入声明式扫描、版本探测、提供方查询客户端和输入监听；Windows 未接入 | 已有纯数据测试保护固定失效、来源与最低版本、冲突、路径和数量边界，以及只扫描、只由定义插件自供、两条路线报告同一 home 时只算一份；macOS 用真实临时目录和注入的探测证明扫描、工作区排除、只探测 Core 返回的文件和冲突；macOS 已用脚本后端与注入查询证明协商、原样回复、独立代次、整份重查与合并；真实超时、进程回收与 Windows 仍须平台实现证明；不新增宿主工具表 |
| 3：统一选择与设置界面，部分完成 | macOS 环境/来源页和只读加载器已接入；实际启动与展示共用快照、Java/Maven 定义迁移尚未完成 | 现有目录、插件撤销、错误及过期快照测试；手动添加、确认保存、冲突回读和消费者切换仍须后续验证；同项删除被替换的专属路径 |
| 4：两个真实提供方 | mise 后端调用上游输出，SDKMAN 作为不同机制的验收插件，设置各自注入插件页 | 第二个提供方只改插件；SDKMAN 路径从 `MacRuntimeDiscovery` 迁出；原生工作流、离线/未信任/未安装/取消、进程清理与安装包哈希不变 |

Expand Down Expand Up @@ -190,3 +190,11 @@ macOS 的声明式路线由 `MacToolchainDiscovery` 执行，宿主不认识任
- `windows/tauri/src/platform/`
- `Plugins/mac/`
- `Plugins/win/`

## macOS 查询客户端的取舍

- 复用 `MacPluginBackendSessions` 的单插件单进程，不另起进程：查询与页面调用共用同一后端和设置重启规则。协商结果在 Core 会话状态里，未协商的提供方由 Core 拒绝，不写到进程。
- Core 只搬运原始回复（`{id,response}`），所有成功与错误规则留给 `toolchains.decodeReply`；否则引擎和解码器会各维护一份错误码表。
- 每个提供方先发一次全局查询（`workspace:null`），再对根目录和有自己版本文件的目录逐个查询（上限 32）。这样项目配置不可用时仍能列出安装；未打开窗口的工作区没有 context，只做全局查询并说明原因。
- 宿主只读取回复与定义点名的路径（home、可执行布局、`${home}` 前缀、来源文件）作为事实。别名链接（如 mise 的 `latest`）只有链接路径的事实，Core 由链接事实推出规范目标再校验，避免宿主为规范路径再读一遍。
- 失效用整份重载：工作区内按 `watchFiles` 尾部匹配，工作区外按回复的 `watch` 用一个 FSEvents 流监听其最近存在的父目录；短时间事件合并为一次重载，关闭页面即释放监听。
Loading
Loading