同一个代码仓库在三种系统上的代理工作笔记

把同一个仓库交给编程代理，换一台电脑，结果未必相同。差异通常不在模型是否理解代码，而在它调用的终端、找到的依赖，以及执行命令时拥有的权限。比较 Windows、macOS 与 Linux，适合从这些可观察的条件开始，而不是先给系统排出名次。

§ 终端：先确认命令在哪里执行

• Windows：PowerShell、命令提示符与 WSL 是不同环境。代理生成的 Bash 命令不能直接当作 PowerShell 脚本使用。选择原生运行还是 WSL，应先检查所用客户端当前版本的支持说明。
• macOS：交互式终端常用 zsh，但项目脚本可能要求 Bash。代理从终端或桌面程序启动时，继承的环境变量也可能不同。
• Linux：适合直接运行常见的类 Unix 工具链，但精简容器或服务器镜像可能缺少 Git、编译器和基础命令，不能把“系统可用”等同于“工具齐全”。

让代理修改代码前，先要求它报告当前目录、终端类型、运行时版本和测试入口。这份简短记录，比一句“本机运行正常”更容易复用。

§ 文件：路径相似，语义未必相同

• Windows：盘符、反斜杠、带空格的目录名都需要正确处理。若采用 WSL，涉及大量小文件的项目通常更适合放在其 Linux 文件系统内；跨文件系统访问应实测性能。
• macOS：常见默认文件系统配置不区分文件名大小写，仅修改大小写的重命名可能掩盖问题。提交前应检查 Git 实际记录的文件名。
• Linux：常见文件系统区分大小写。导入路径与真实文件名不一致，可能直到这里才报错；脚本的可执行位也需要随版本管理保存。

三端都应约定换行符、编码和路径处理方式。让代理使用项目现有的路径库，不要把本机绝对路径写进配置，也不要为了消除换行差异而重写整个仓库。

§ 依赖：同一份锁文件仍需要分别验证

• Windows：原生扩展可能依赖额外构建工具。原生环境与 WSL 应分别安装依赖，不要共享包含平台二进制文件的依赖目录。
• macOS：需要区分 Apple 芯片与 Intel 环境。包管理器路径、预编译包和容器镜像架构，都可能影响代理给出的安装步骤。
• Linux：发行版、系统库版本和处理器架构同样重要。开发机与部署机都叫 Linux，并不表示原生依赖可以直接复制。

比较三端表现时，应固定提交、运行时、锁文件和测试命令。若项目使用容器，它能缩小环境差异，但不能消除文件挂载、权限和宿主网络带来的影响。

§ 权限：能执行，不代表应该自动执行

Windows 的访问控制、macOS 的隐私授权，以及 Linux 的用户与文件权限，都会影响代理读写目录或启动进程。遇到拒绝访问时，应先定位具体资源，不要直接改为管理员运行或扩大整个目录的权限。

三种系统都适合采用相同边界：限定工作目录，运行前审阅破坏性命令，修改后检查差异，并把测试与部署权限分开。不要默认代理会避开密钥文件；应结合客户端的排除机制和系统权限限制访问。

§ 接口：统一连接，不掩盖本地差异

使用 Claude Code、Codex 或 Gemini CLI 时，可以把本地执行环境与远端模型连接分开配置。Vana API 在 https://api.vanaapi.com 提供 OpenAI 兼容接口，同时支持 Anthropic Messages 与 Gemini 原生协议，可用于这些客户端及 OpenAI SDK；具体配置应按客户端版本选择对应协议和设置项，而不是混用参数。

统一入口有助于减少跨平台维护的连接配置，但不会替你统一终端语法、文件权限或依赖。密钥应通过客户端支持的安全方式注入，不提交到仓库，也不直接写进会进入终端历史的命令。Vana API 按实际使用的令牌计费，无月费；需要验证连接时，可以创建一个账户，先用小任务检查请求、响应与用量记录。

§ 选择：让现有工作流决定落点

依赖 Windows 专用工具，就优先验证原生工作流；日常使用 macOS，就保留本地编辑体验，并在目标环境补测；部署面向 Linux，就尽早让代理在对应容器或持续集成环境中执行测试。更稳妥的比较标准不是哪套系统让代理“更聪明”，而是哪套环境能让命令可解释、变更可审查、结果可重复。