[xiaoyumuxi]

关联 Issue / Linked issue

• Refs [Feature] macOS 存量重构计划：清理废弃实现，将 Maven/Java 领域逻辑完整迁入插件后端 #1495

PR 类型 / Type

• feat：新功能或用户可见的改进
• fix：缺陷修复
• docs：文档、Agent Note、Skill 等规则文件
• release：稳定版发布准备

改动说明 / What changes

背景 / Why

#1791 合入后，在 preview 构建上安装 Maven 插件并打开 Maven 项目，构建后端启动前就失败，run.log 记录
run.preparation.failed error="The resolved tool environment is invalid or too large."，Maven 插件的 host.log
记录 host.planFailed operation=lithe/build/model。所有依赖工具定义（toolDefinitions）选出运行时的构建插件都受影响。

原因是 MacBuildToolResolver 把工具链选择结果的 environment（调用方整份进程环境叠加导出变量之后的结果）
当成"这个工具链贡献的变量"，于是 providerEnvironment 变成了整份进程环境。Core 的 provider_hints 对 provider
环境限制 64 个变量、变量名只允许 [A-Z_][A-Z0-9_]*，整份环境必然被拒。#1791 之前这里是按 JAVA_HOME 名字特判的，
拆分时换成了通用的 contributed 集合，但集合的来源取错了。

改动 / Changes

• macos/Sources/Lithe/Core/Ports/DefinedToolchains.swift：ResolvedDefinedToolchain 新增带默认值的 exports: [String: String]，
  只装这次选择新加到调用方环境里的变量（定义的 environment 导出项，以及有 pathPrepend 时的 PATH）；environment
  仍是调用方环境叠加这些导出后的完整结果，供直接启动进程的消费者使用。
• macos/Sources/Lithe/Platform/MacOS/Runtime/MacToolchainDiscovery+Resolution.swift：从 Core toolchains.resolve 的
  selection.environment 和 pathPrepend 填充 exports。
• macos/Sources/Lithe/Platform/MacOS/Build/MacBuildToolResolver.swift：工具链候选的 choice environment 改为 selected.exports。
  合并回调用方环境后得到的执行环境不变，但 contributed 只记录工具链真正导出的变量，provider 收到的是
  PATH + 导出项 + 与宿主进程不同的变量。
• macos/Tests/LitheTests/MacBuildToolResolverTests.swift：新增回归测试，工具链候选解析后 providerEnvironment 的键只有
  PATH 和导出项，宿主进程原有的其他变量不出现；执行环境仍包含它们。

不在本 PR 范围内 / Out of scope

• Maven / Gradle 插件清单里被契约拒绝的 languageImport 字段：fix(manifest): 移除宿主已删除的 buildSystems.languageImport 字段 Lithe-IDEA/lithe-plugin-maven#13、清单 languageImport 字段已被宿主契约拒绝，需删除并改走 pluginFunctions 中继 Lithe-IDEA/lithe-plugin-gradle#7。
• Maven / Gradle 通过 pluginFunctions 导出 languageImport.settings：通过 pluginFunctions 导出 languageImport.settings，替代已删除的 languageImport 清单字段 Lithe-IDEA/lithe-plugin-maven#14、清单 languageImport 字段已被宿主契约拒绝，需删除并改走 pluginFunctions 中继 Lithe-IDEA/lithe-plugin-gradle#7。
• Windows 仍使用过渡 crate lithe-legacy-tooling，不走这条宿主路径。

---

类型专属：fix

复现与根因

• 复现步骤：preview 构建（0b7a2b5f1）安装 Java Support 1.1.0 与 Maven 插件，打开 Maven 项目，触发构建模型加载。实际结果：
  run.preparation.failed，错误文案 "The resolved tool environment is invalid or too large."，构建窗口无模型。期望结果：Maven 后端
  以选中 JDK 的 JAVA_HOME、PATH 启动。
• 根因：fix(epic,core,macos): 把 Java 专属逻辑全部移出 Core 与 macOS 宿主，改走通用插件 API #1791（185222d8b）把 MacBuildToolResolver 的 JAVA_HOME 特判换成通用 contributed 集合时，工具链 choice 的
  environment 取了完整环境而不是导出项，contributed 因而包含进程里所有变量。
• 影响平台：macOS。

检查项

• 已先写回归测试，确认它在修复前失败、修复后通过；测试路径与修复前的失败输出：MacBuildToolResolverTests/toolchainSelectionContributesOnlyItsExportsToTheProvider，修复前 providerEnvironment.keys 为 ["PATH","FIXTURE_HOME","FIXTURE_SECRET","SHELL"]
• 无法自动化时，已写明手动复现与验证步骤：见上方复现步骤；修复后在同一构建上重新打开 Maven 项目，后端正常启动
• 已搜索被修改函数、类型、契约字段的全部调用方（含另一平台、插件、SDK、脚本和按字符串分发的调用）：ResolvedDefinedToolchain 的三个构造点（发现、打包运行时、测试）和消费 environment 的 MacPluginBackendLaunchPreparer、MacDefinedToolchainResolver 行为不变
• [N/A] 已检查另一平台是否有同类缺陷：Windows 未接入 toolDefinitions 解析，仍用过渡 crate
• 只改了修复所需的代码，没有夹带重构；修复过程中发现的其他问题已提交 Issue：通过 pluginFunctions 导出 languageImport.settings，替代已删除的 languageImport 清单字段 Lithe-IDEA/lithe-plugin-maven#14、清单 languageImport 字段已被宿主契约拒绝，需删除并改走 pluginFunctions 中继 Lithe-IDEA/lithe-plugin-gradle#7
• [N/A] 修复改变了行为约束或容易复发，已在 .agents/notes/implemented/bug-fix/ 记录：约束已写在 ResolvedDefinedToolchain.exports 的类型注释和回归测试里，没有新的架构取舍

---

范围检查 / Scope checks

功能矩阵 / Feature matrix

N/A：恢复 #1791 之前的既有行为，没有新增能力或改变跨平台行为。

统一日志系统 / Structured logging

N/A：没有新增或改动日志事件。

界面文案 / i18n

N/A：没有新增用户可见文字。

逻辑归属 / Logic placement

• 可共享的逻辑在 Rust Core：环境限制的校验仍在 Core provider_hints；本 PR 只修正 Swift 层把哪些变量交给 Core 的 I/O 接线
• [N/A] 修改平台层已有的可共享逻辑时已迁入 Core：改动只是把 Core 已返回的导出项原样带到消费者
• 工具或运行时专属的知识放在插件或成熟上游，宿主和 Core 没有按工具名加分支

性能与内存 / Performance and memory

N/A：没有新增后台功能、子进程、缓存或依赖。

设置 / Settings

N/A：不涉及设置项。

插件与共享契约 / Plugin and shared contracts

N/A：没有改动 shared/contracts/、capabilities 或宿主方法。

发行包与资源 / Bundle and resources

N/A：没有新增运行时资源。

无用代码与重构 / Dead code and refactoring

• 本次改动导致变成无用的代码已在本 PR 删除
• [N/A] 本次之前就存在的无用代码或可重构之处：本次没有发现

---

验证 / Verification

命令或操作	平台	结果
swift test --triple arm64-apple-macosx --filter MacBuildToolResolverTests	macOS	新增回归测试通过，套件其余测试通过
scripts/macos/test/test-macos.sh --filter 'MacBuildToolResolverTests|BuildToolProviderResolutionTests|PluginBackendLaunchTests|RunLaunchEnvironmentTests|BuildSystemServiceTests'	macOS	运行中，结果补在评论里
preview 构建安装 Maven 插件后打开三模块 reactor 项目，构建后端启动	macOS	待重建 app 后验证，结果补在评论里

未能执行的检查和原因： Windows 构建与测试未在本机执行；Windows 不走本路径。

提交前确认 / Final checks

• 分支从最新的 preview 创建；目标分支：preview
• 以 Draft 提交，本地验证通过后才标记 ready
• 没有无关改动，没有提交 .build/、target/、dist/、.artifacts/ 等产物，没有凭据、个人路径和未脱敏的日志或截图
• 本次构建、测试或预览启动的 Lithe 应用和子进程已全部关闭，没有进程残留

[xiaoyumuxi]

本地验证结果：

命令	结果
scripts/macos/test/test-macos.sh --triple arm64-apple-macosx --filter 'MacBuildToolResolverTests|BuildToolProviderResolutionTests|PluginBackendLaunchTests|RunLaunchEnvironmentTests|BuildSystemServiceTests'	150 项通过，含新增回归测试 toolchainSelectionContributesOnlyItsExportsToTheProvider

修复前同一测试得到 providerEnvironment.keys == ["PATH","FIXTURE_HOME","FIXTURE_SECRET","SHELL"]（宿主整份环境）；修复后只有 ["PATH","FIXTURE_HOME"]。

端到端验证（preview 构建安装 Maven 插件、打开三模块 reactor 项目）在重建 app 后进行，结果会补在这里。