[xiaoyumuxi]

关联 Issue / Linked issue

• Refs [Feature] Viva 桌面客户端（desktop/）在 Windows 上构建、链接 Rust Core，并跑通欢迎页、工作台和日志窗口 #1798（Viva 桌面端在 Windows 上构建并链接 Rust Core；本 PR 只修复其中的打包和 make core 入口，不完成该 Issue）

PR 类型 / Type

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

改动说明 / What changes

背景 / Why

在 Windows 上运行 mingw32-make package 打 Viva 桌面端安装包时，命令直接报错退出：

$ mingw32-make package
../scripts/desktop/package-desktop.sh --arch amd64
cgo cannot link the MSVC .lib archive for x86_64-pc-windows-msvc; use x86_64-pc-windows-gnu for Windows.
mingw32-make: *** [makefile:74: package] Error 2

打包脚本为了把 lithe-mcp 辅助程序嵌进客户端，直接调用 build-desktop-core.sh --release，绕过了 desktop-go.sh。build-desktop-core.sh 在 LITHE_CORE_TARGET 为空时会使用 rustc 的主机目标，而 rustup 在 Windows 上默认装的是 x86_64-pc-windows-msvc，脚本检测到 MSVC 后拒绝构建。desktop-go.sh 本来负责把 GOOS/GOARCH 映射到 Core 目标（Windows 为 x86_64-pc-windows-gnu），客户端本体的构建走它，所以目标是对的，出问题的只有辅助程序这一步。

同一原因还有两个表现：

• 在 arm64 Mac 上 make package ARCH=amd64 能打出包，但嵌入的 lithe-mcp 是 arm64 版本，Intel Mac 上 IDE 连接用的辅助程序无法运行。
• make core 也直接调用 build-desktop-core.sh --debug，在 Windows 上报同样的错误。

.github/workflows/desktop-release.yml 里的 Windows 发版任务（windows-2022）和 darwin amd64 发版任务（macos-26，arm64 runner）都没有设置 LITHE_CORE_TARGET，所以第一次推 desktop-v* 标签时会遇到同样的问题：Windows 包打不出来，amd64 macOS 包嵌入了 arm64 的辅助程序。这个工作流还不在 main 上，没有运行过，所以问题还没暴露。

改动 / Changes

• scripts/desktop/desktop-go.sh

  • 新增 --print-core-stage 模式：沿用已有的 GOOS/GOARCH → Core 目标映射、LITHE_DESKTOP_CORE_PROFILE 和 MACOSX_DEPLOYMENT_TARGET 设置，暂存 Core 后只把暂存目录输出到 stdout 然后退出，不运行 Go。
  • 这个模式的参数检查放在 Core 构建之前，参数写错时立即退出（exit 2），不会先白编一次 Core。
  • 文件头 Usage 和说明补上这个模式，并说明调用方不应直接调用 build-desktop-core.sh（它默认取 rustc 主机目标）。

• scripts/desktop/package-desktop.sh：暂存 lithe-mcp 的那一步从 build-desktop-core.sh --release 改为 GOARCH="$ARCH" LITHE_DESKTOP_CORE_PROFILE=release desktop-go.sh --print-core-stage，辅助程序和安装包使用同一个目标与 profile；同步更新注释。

• desktop/Makefile：make core 改为 desktop-go.sh --print-core-stage（profile 仍是 debug），并加注释说明原因。

• 新增 scripts/desktop/package-desktop.test.mjs：在临时目录中运行真实的 package-desktop.sh、desktop-go.sh 和 desktop/Makefile。go、rustc 和 build-desktop-core.sh 用假程序代替，其中假的 build-desktop-core.sh 保留真实脚本的目标规则（优先 LITHE_CORE_TARGET，否则取 rustc 主机目标，遇到 MSVC 拒绝）。共三个用例：

  1. 模拟 Windows amd64，rustc 默认 MSVC：只暂存 x86_64-pc-windows-gnu --release，嵌入的辅助程序属于 GNU 目标。
  2. 模拟 arm64 Mac 打 --arch amd64 包：只暂存 x86_64-apple-darwin --release，嵌入的是 x86_64 辅助程序。
  3. 模拟 Windows 运行 make core：只暂存 x86_64-pc-windows-gnu --debug，stdout 只有暂存目录。

  每个子进程都通过 write-stable-tests 的 runProcess 启动，超时 60 秒，并断言没有超时、进程树已结束；临时目录在 finally 中删除。

• .github/workflows/desktop-ci.yml：在 Linux 任务的 “Run script tests” 中加入这个测试。Draft PR 也会运行它。

• shared/platform-feature-matrix/features/ide-mcp-connection.json：两端 evidence 补上 package-desktop.sh 和新测试；notes 写明辅助程序按 desktop-go.sh 的目标映射构建；verification 写入新测试的验证内容。两端的实现状态和验证状态不变（partial / pending）。

不在本 PR 范围内 / Out of scope

• [Feature] Viva 桌面客户端（desktop/）在 Windows 上构建、链接 Rust Core，并跑通欢迎页、工作台和日志窗口 #1798 的其余内容（快捷键按平台映射、Windows 上的工作流验证、终端接线等）。
• 没有在真实的 Windows x64 机器上运行 mingw32-make package，见下方“未能执行的检查”。
• docs/development/desktop-getting-started.md 中关于这个 MSVC 报错的排查说明没有改。修复后，直接运行 build-desktop-core.sh 时这个报错依然会出现，原有说明仍然准确。

---

类型专属：fix

复现与根因

• 复现步骤、实际结果、期望结果：
  • 环境：Windows x64，Git Bash，rustup 默认主机为 x86_64-pc-windows-msvc，已 rustup target add x86_64-pc-windows-gnu，MinGW-w64 已在 PATH 中。
  • 步骤：cd desktop && mingw32-make package。
  • 实际：打印 cgo cannot link the MSVC .lib archive for x86_64-pc-windows-msvc; use x86_64-pc-windows-gnu for Windows.，Error 2 退出，没有生成安装包。
  • 期望：在 dist/desktop/windows-amd64/ 生成 lithe-<version>-windows-amd64-setup.exe 和 zip，嵌入的 lithe-mcp 为 GNU 目标。
  • 同类：arm64 Mac 上运行 make package ARCH=amd64，安装包能生成，但嵌入的 lithe-mcp 是 arm64 版本；Windows 上运行 make core 报同样的 MSVC 错误。
• 根因（引入该行为的提交或 PR）：Epic(0.7.0): 基于 Viva 框架的跨平台方案的迁移（#1794） #1799（0faecba49）。这次提交加入了 package-desktop.sh 的 build-desktop-core.sh --release 和 Makefile core 目标的 build-desktop-core.sh --debug（用 git log -S 确认）。这两处绕过了 desktop-go.sh 的目标映射，回到 rustc 主机默认目标。
• 影响平台：Windows（打包和 make core 失败）；macOS 上跨架构打包（arm64 主机打 amd64 包时嵌入了错误架构的辅助程序）；Desktop Release 工作流的 Windows 和 darwin amd64 任务。Linux 本机架构打包不受影响，因为主机目标和映射目标一致。

检查项

• 已先写回归测试，确认它在修复前失败、修复后通过；测试路径与修复前的失败输出：scripts/desktop/package-desktop.test.mjs。修复前 3 项全部失败：Windows 打包用例和 make core 用例输出上面的 MSVC 报错并 exit 2；arm64 主机打 amd64 包的用例中，暂存记录里多出 aarch64-apple-darwin --release，嵌入的辅助程序不是 x86_64。修复后 3 项全部通过（约 2.6 秒）。
• [N/A] 无法自动化时，已写明手动复现与验证步骤：已自动化；真实 Windows 打包没有运行，原因见“未能执行的检查”。
• 已搜索被修改函数、类型、契约字段的全部调用方（含另一平台、插件、SDK、脚本和按字符串分发的调用）：仓库里直接调用 build-desktop-core.sh 的只有 desktop-go.sh（本来就会先设置目标）、package-desktop.sh 和 desktop/Makefile。CI 中其余引用只用于 bash -n、ShellCheck 和 cache key 的 hashFiles。desktop_go_test.go 和 desktop-core-cache.test.mjs 用自己的假脚本，已重新运行并通过。scripts/ci/desktop-release/package-release.sh 通过 package-desktop.sh 间接受益，不需要改。
• 已检查另一平台是否有同类缺陷（有则本 PR 一并修复，或已提交 Issue）：macOS 跨架构打包有同类缺陷，本 PR 一并修复并加了回归用例；Linux 使用同一代码路径，也一起修好。
• 只改了修复所需的代码，没有夹带重构；修复过程中没有发现需要另外提交 Issue 的问题。
• [N/A] 修复改变了行为约束或容易复发，已在 .agents/notes/implemented/bug-fix/ 记录：约束（需要暂存 Core 时走 desktop-go.sh --print-core-stage，不要直接调用 build-desktop-core.sh）已写进 desktop-go.sh 文件头和两个调用点的注释，并由 CI 中的回归测试守住，没有另写 Note。

---

范围检查 / Scope checks

功能矩阵 / Feature matrix

• 已更新 shared/platform-feature-matrix/features/ide-mcp-connection.json：两端的 evidence、notes、verification 已补充；实现状态和验证状态保持 partial / pending（没有在两端实机验证）
• 已运行 ./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh（validated 217 platform capabilities）和 ./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/preview HEAD（matrix change gate passed）
• 没有提交 .artifacts/ 下生成的矩阵视图
• [N/A] 没有更新矩阵的，理由：已更新矩阵

统一日志系统 / Structured logging

N/A：只改了构建、打包脚本和 Makefile，没有改动运行时的生命周期、用户操作或失败路径。

界面文案 / i18n

N/A：没有新增或修改用户可见文案。新增的 Usage: … --print-core-stage 是开发者命令行的 stderr 输出，不属于界面文案。两项 i18n 检查仍已运行并通过。

逻辑归属 / Logic placement

N/A：没有业务逻辑，只是构建脚本改为复用已有的目标映射。

性能与内存 / Performance and memory

N/A：没有改动运行时功能、启动路径或依赖。打包时 Core 仍然只为一个目标构建一次。

设置 / Settings

N/A：没有涉及设置。

插件契约 / Plugin contract

N/A：没有改动插件契约、能力版本或宿主方法，PINNED_CORE_REVISION 不变。

发行包与资源 / Bundle and resources

• 运行时不向已安装的 app bundle 或 Windows 安装目录写入：嵌入的 desktop/internal/idehelp/lithe-mcp.bin 仍然只在打包时生成，结束后由 trap 删除，运行时的安装位置不变。已运行 ./scripts/desktop/verify/verify-runtime-bundle-immutability.sh（模板里写的 scripts/macos/verify/… 已不存在，桌面端对应的脚本是这个），结果通过
• [N/A] 新增或修改下载、解压、生成或缓存资源的，已同步 scripts/resources/worktree-resources.json 等：没有新增资源路径、缓存变量或下载入口。Core 的暂存位置和缓存规则不变，只是辅助程序这一步现在使用正确的目标

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

• 本次改动没有让任何代码变成无用代码（build-desktop-core.sh 仍由 desktop-go.sh 调用）
• [N/A] 本次之前就存在的无用代码或可重构之处：没有发现

---

验证 / Verification

命令或操作	平台	结果
node --test scripts/desktop/package-desktop.test.mjs（修复前）	macOS arm64	3 项全部失败（见上）
node --test scripts/desktop/package-desktop.test.mjs（修复后）	macOS arm64	3 项全部通过，约 2.6 秒
node --test scripts/desktop/desktop-core-cache.test.mjs	macOS arm64	通过
bash scripts/desktop/desktop-go.sh test ./internal/core/ -run 'TestDesktopGoFindsWindowsCargoImportLibraries|TestBuildDesktopCoreChecksOutFreshPinnedRevision' -count=1	macOS arm64	ok
真实 make -s core（固定 Core 修订 47c9859d2f43）	macOS arm64	exit 0，约 65 秒；stdout 只有暂存目录，identity 为 target=aarch64-apple-darwin、profile=debug
bash -n 与 shellcheck -S warning（desktop-go.sh、package-desktop.sh）	macOS arm64	通过
actionlint .github/workflows/desktop-ci.yml	macOS arm64	通过
./.agents/skills/write-stable-tests/scripts/verify-test-stability.sh --base origin/preview	macOS arm64	Test stability check passed
./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh	macOS arm64	validated 217 platform capabilities
./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/preview HEAD	macOS arm64	matrix change gate passed
node scripts/i18n/verify-app-language-localization.mjs、node scripts/i18n/generate-i18n.mjs --check	macOS arm64	通过
./scripts/desktop/verify/verify-runtime-bundle-immutability.sh	macOS arm64	通过（desktop macOS and Windows sources）

未能执行的检查和原因：

• 没有在真实 Windows x64 上运行 mingw32-make package。本机的 Parallels 虚拟机是 ARM64，当前状态为 invalid，而 Windows 打包只支持 amd64。Windows 行为目前只由回归测试中的模拟覆盖。需要在 x64 Windows 上运行 cd desktop && mingw32-make package NO_SIGN=1，确认生成 setup.exe/zip，并确认安装后 IDE 连接能启动 lithe-mcp。
• 没有在本机运行完整的 make package（含签名、dmg），也没有在 Intel Mac 上验证 amd64 包里的 lithe-mcp 能运行。
• Draft PR 只运行 Linux 检查。macOS 和 Windows CI 要等标记 ready 后才运行。

提交前确认 / Final checks

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