[hahhforest]

这个 PR 想解决什么

现在 OAC 的自托管执行器在 Windows amd64 上已经能跑 Codex 和 Claude Code，唯独 MiniMax Code 不行：在 Windows 上选 MiniMax Code，安装器会直接拒绝，Web 的安装面板里也写着“Windows 不支持 MiniMax”。

我仔细查了一遍，发现 MiniMax Code 本身是支持 Windows 的——官方有 install.ps1，它在 Windows 上会自己选 shell（先找 PowerShell 7，再找 Windows PowerShell 5.1，都没有才回退到 Git Bash 和 PATH 上的 bash），进程清理也有 Windows 的实现。OAC 这边，daemon 管进程树用的是共用的 clirunner，Windows 上走 Job Object，Codex 和 Claude Code 早就靠它在 Windows 上稳定运行，MiniMax Code 适配器用的也是同一个 clirunner。

所以 MiniMax Code 在 Windows 上跑不起来，并不是哪里有根本性的障碍，而是一路上有几处显式的平台拦截，再加上几个只在 Unix 上成立的小假设。这个 PR 做的事情，就是把这些拦截和假设逐个处理掉，让 Windows 自托管机器也能像 Linux 和 macOS 一样，通过原生安装器装上并运行 MiniMax Code。

具体改了哪些地方

daemon 适配器（apps/daemon/internal/agent/mcode）

• installation.go：Supported 原本只认 linux 和 darwin，现在加上 windows。
• workspace.go：ConfigureLocal 原本在 Windows 上直接返回错误，这个拦截去掉了。根目录检查原本写死判断 /，换成 filepath.Dir(path) == path，这样 C:\ 这种盘符根也能正确识别。
• version.go、executor.go、session.go：安装器装进来的 MiniMax Code 入口是 native/cli.js。Unix 上它靠 shebang 直接执行，Windows 没有 shebang 这回事，直接执行会失败。我加了一个很小的 nativeCommand：入口是 .js 时，就用固定版本的 Node.js 启动它（[node, cli.js, ...]），版本探测和 ACP 启动走同一条路径。Node 的位置读 OAC_RUNTIME_MCODE_NODE，安装器本来就会设置这个变量，没设置时回退到 PATH 上的 node。这样做在 Unix 上也是一样的效果：shebang 原本找到的就是 PATH 上第一个 node，也就是安装器放进去的那个固定版本。
• versionprobe.Config 增加了 Args 字段，放在 --version 前面，用来支持上面这种“解释器 + 脚本”的探测方式。
• Skill 目录链接：工作区模式下，适配器会把冻结安装里的 Skill 链接到 Session 的 skills 目录。原来用的是 os.Symlink，但 Windows 上创建目录符号链接需要开启开发者模式或者管理员权限，普通账户下的自托管机器做不到。所以我把它拆成了 link_other.go（非 Windows，照旧用 symlink）和 link_windows.go（Windows，用 FSCTL_SET_REPARSE_POINT 创建目录 junction）。junction 不需要任何特殊权限，os.Readlink 能读回它的目标，后续对 Skill 根目录的校验逻辑在两个平台上完全一样。
• discovery_workspace.go、subagents.go：读取 node 位置时统一走同一个 defaultNode()，不再各自读环境变量。

companion 包（packages/mcode-harness/check.mjs）

• 原来只允许 linux 和 darwin，并且用 which 检查 bash 和 rg。Windows 上没有 which，而且 MiniMax Code 在 Windows 上默认用 PowerShell，本来就不需要 bash。
• 现在改成按 PATH/PATHEXT 自己查找可执行文件。Unix 上照旧要求 bash 和 rg；Windows 上只要求 rg，shell 交给 MiniMax Code 按它原生的方式去选。
• 这一点我想特别说明一下我的考虑：Claude Code 在 Windows 上要求 Git Bash，是因为 Claude Code 自己就是这么要求的；MiniMax Code 原生优先使用 PowerShell，我觉得 OAC 应该尊重 Harness 的原生行为，而不是再额外强加一个 Git Bash 依赖。环境准备命令（setup）照旧由 daemon 的共用代码在 Git Bash 里执行，这部分没有动。如果维护者希望 Windows 上统一强制 Git Bash，我很乐意改。
• 原生 bash 工具在所有平台上的工具名都是 bash（上游 LocalBashToolDef.name），所以 OAC 的事件投影不需要做任何修改。

安装器与 CI

• scripts/build-native-installer.mjs：去掉两处“Windows + MiniMax 直接报错”的拦截；ripgrep 在 Windows 上打包为 bin/rg.exe，清单里的文件条目也跟着变化。
• scripts/build-mcode-harness.sh：这个脚本原来只放行 Linux x86_64 和 macOS arm64。现在也放行 Windows 上的 Git Bash（MINGW64_NT-*:x86_64）。有一个坑需要说明：Git Bash 只会在命令行参数里自动把 /c/... 这样的 POSIX 路径转成 Windows 路径，环境变量里的不会转。而脚本里有 MCODE_SOURCE=... node ... 这种把路径放在环境变量里传给原生程序的写法，所以在 Windows 上我把所有路径统一用 cygpath -m 转成 C:/... 的形式——这种写法 MSYS 工具和原生的 node、git 都认。另外，脚本里两处 python3 换成了 node：一处是读 source.json 的 revision，一处是生成 provenance.json。原因是 Windows runner 上不一定有 python3 这个命令，而 node 本来就是这个构建必需的。新的实现保持了原来 Python 版本的语义：递归时只进入真正的目录，不跟进目录符号链接；指向文件的符号链接按文件计入；断链跳过。我在本机用一个包含这几种情况的目录，把新旧两种实现的输出对比过，文件列表和哈希完全一致。
• .gitattributes：新增一行 *.sh text eol=lf。这是仓库里第一个要在 Windows 上执行的 .sh 脚本，而 Git for Windows 默认开启 core.autocrlf=true，checkout 出来的脚本会变成 CRLF，bash 读到 set -euo pipefail\r 会直接报错退出。GitHub 的 Windows runner 碰巧没有转换换行，但不能指望每台机器、每个开发者的配置都是这样，所以让 .sh 在任何 checkout 下都保持 LF。
• .github/workflows/native.yml：companion 构建步骤去掉了 if: runner.os != 'Windows'；Harness 测试步骤里加上了新增的 TestNativeCommand 和 TestSelfHostedSkillDirectoryLink，这样 junction 的创建、读穿、删除链接不影响目标这些行为，会真的在 Windows runner 上跑一遍。
• .github/workflows/cache-warm.yml：companion 的缓存预热矩阵加上 Windows，不然 PR 在 Windows 上每次都要从头构建。
• scripts/build-native-installer-ci.mjs 和 scripts/native-onboarding-smoke.mjs：原来在 Windows 上专门断言“安装 MiniMax 必须失败”，现在三个平台统一安装 codex、claude、minimax 三个 Harness。

文档和 Web 文案

• 自托管指南的平台表里，Windows amd64 的 MiniMax Code 一栏改为“支持”；关于 Bash 的说明补充了 Windows 上 MiniMax Code 用 PowerShell 执行 bash 工具。
• 维护者文档、services/core/deploy/mcode/README.md、packages/mcode-harness/README.md 里“只支持 Linux/macOS”的说法都同步更新了。
• 中文镜像同步修改，并更新了 source_hash；website/tests/translations.test.mjs 本地通过。
• Web 安装面板的中英文文案里删掉了“Windows 不支持 MiniMax”。
• Harness 能力表没有改。表里写的是“自托管验收在 Linux 机器上进行”，这句话依然成立，我也不想在没做真实模型验收的情况下，把 Windows 写成已验证。

Core 侧没有任何改动：原生安装器是按制品提供组件的，没有写死哪个平台有哪些 Harness，Windows 的 MiniMax 制品出现以后，Core 自然就能分发它。

我做了哪些验证，哪些没做

按 CONTRIBUTING 的要求，我把验证情况分开写清楚。

已经跑过的：

• 本机（macOS arm64）：go build ./apps/daemon/...；GOOS=windows GOARCH=amd64 go build ./apps/daemon/...；对 mcode、versionprobe、cli 三个包跑 GOOS=windows go vet；用 GOOS=windows go test -c 编译 mcode 和 cli 的测试；gofmt 无输出；codex 包和 cli 的 TestNative|TestRuntimeInit 测试通过；make check-mcode-harness 通过；website/tests/translations.test.mjs 通过，中文镜像的 source_hash 是对的；对两个改过的 workflow 跑 actionlint，通过。
• 在我的 fork 上手动触发了 native-check（因为 fork 上没有 Blacksmith runner，我把 fork 的 OAC_USE_GITHUB_RUNNERS 设成了 true，用的是 GitHub 托管的 ubuntu-22.04、macos-15 和 windows-2025）。linux-amd64、darwin-arm64、windows-amd64 和 Core installer（macOS Intel）四个 job 全部通过：https://github.com/hahhforest/OpenAgentCore/actions/runs/39770191385（对应提交 f7473fd0）
• 在 windows-amd64 这个 job 里，我逐项看了日志，确认下面这些是真的跑了，没有被跳过：
  • MiniMax companion 在缓存未命中的情况下，用 Git Bash 从固定版本的上游源码完整构建了一遍（Built MiniMax Code 0.4.12 from 6355 source files.），产物随后写进了 Windows 缓存。
  • 打出来的安装包里有 node、codex、claude、minimax 四个组件。安装器打包时的就绪检查，用打进包里的 Node.js 在 Windows 上实际执行了 native/cli.js --version 和 check.mjs。也就是说，MiniMax Code CLI 能由 node 拉起来，原生 sqlite 模块能加载，rg.exe 能从 PATH 找到。
  • --harness codex,claude,minimax 的安装、追加安装、复用，全都通过。
  • 引导冒烟（bootstrap.ps1 → 交互安装 → 连接 → 重试 → 重复安装 → 卸载 → 认证）选中了全部三个 Harness，全部通过。
  • go test -race 跑 mcode 包，包括新增的 TestNativeCommandRunsJavaScriptEntrypointWithNode 和 TestSelfHostedSkillDirectoryLink，在 Windows 上通过。所以 junction 在普通账户下能创建，os.Readlink 能读回目标，能从 junction 读到目标目录里的内容，删除 junction 也不会动到目标目录。
• 按 CONTRIBUTING 的要求，完整 diff 交给了一个独立的审查者，只给它需求、验收标准和边界，不给实现说明。它提出的问题里，有四条我确认成立并已经修改：.sh 的 CRLF 问题（就是上面加的 .gitattributes）；provenance 遍历会跟进目录符号链接；绝对路径检查在 Unix 上也会接受 c:/...；node 位置有两处读取。还有一条我决定不改：Windows 上创建 junction 要分两步，先 Mkdir，再写 reparse point，不是原子操作。可是只有进程恰好在这两步之间崩溃才会留下一个空目录，而后果是这个 Session 准备 Skill 时报错，属于失败即关闭，不会产生错误的行为。为这么小的窗口再引入一套临时目录加 rename 的逻辑，我觉得不值得。

没能做的：

• Windows 上的真实模型验收没有做。 我手头只有 macOS 机器，没有可以接真实模型的 Windows 自托管环境，所以文本 Turn、取消、续接、文件与产物、子 Agent 这些在 Windows 上走真实模型的路径，都还没有实际跑过。CI 里的协议冒烟不发模型请求，只能证明安装、就绪检查和协议握手是通的。正因为这样，我没有动 Harness 能力表，也没有把 Windows 上的 MiniMax Code 标成 Verified。如果维护者那边有 Windows 自托管机器，非常希望能帮忙跑一遍验收；或者告诉我验收需要的配置，我去找一台 Windows 机器补上。

• macOS 本机上，mcode 包有 3 条测试失败（TestExecutorCancellationRetiresOwnerAndLateCancelCannotRetarget、TestSubagentSettlementIncludesActiveRootTurn、TestWorkspaceRunsNativeToolsWithoutExtraServers，报错都是 “protected Subagent reader is unavailable”），scripts/build-native-installer.test.mjs 也有 1 条失败（npm/npx 拷贝后的探针）。这几条在没有任何改动的 main（62b2df6）上同样失败，是我本机环境的问题，和这个 PR 无关；CI 上它们都是正常的。

• CI 的协议冒烟（native-harness-smoke.mjs）本来就只覆盖 Codex 和 Claude，在任何平台上都没有 MiniMax。所以 daemon 通过 ACP 拉起 node cli.js acp 完成握手，以及读取子 Agent 快照这两条路径，在 Windows 上还没有实际跑过。工作区相关的几个 mcode 测试依赖 POSIX shell fixture，在 Windows 上照旧跳过。

需要维护者帮忙看的地方

1. Windows 上 MiniMax Code 用 PowerShell、不强制 Git Bash，这个取舍是否符合你们的预期。
2. Windows 上 Skill 目录用 junction 而不是符号链接，这个做法是否可以接受。
3. 真实模型的 Windows 验收由谁来做、怎么做比较合适。
4. 有一个现有的行为，在 Windows 上可能更容易碰到，想提醒一下：subagents.go 出于安全考虑，要求 node 和子 Agent 读取脚本的路径必须已经是规范路径，也就是 filepath.EvalSymlinks(path) == path。Windows 上的 EvalSymlinks 会展开 8.3 短文件名，还会把盘符和大小写改成磁盘上的实际写法。所以如果 OAC_RUNTIME_HOME 是用短文件名或者大小写不一致的路径写的，开启子 Agent 的 Turn 会在这一步被拒绝。在默认路径下这个问题不会出现。我没有改这个检查，它在 macOS 上也同样严格（/var 会被解析成 /private/var），属于有意为之的失败即关闭。

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}