fauxnix

在 Windows 上运行 Linux 风格命令 — 原生、确定性、无虚拟机、无 WSL。

fauxnix 是一个面向 AI 代理构建的 bash→PowerShell 翻译层。您的代理可以继续编写它已经熟悉的 bash 命令（ls -la | grep foo、find . -name '*.ts' | wc -l、kill -9 1234），而 fauxnix 会确定性地将每条命令翻译成 PowerShell，原生执行，并返回看起来像 GNU/Linux 的输出：ls -l 列、bash 风格错误消息、coreutils 退出码、自动处理 UTF-8/GBK。

npm install -g fauxnix-cli    # then point any MCP harness at `fauxnix mcp`

$ fauxnix "ls -la src | head -2"
-rw-r--r-- 1 me me 1204 Aug 16 09:12 ast.ts
-rw-r--r-- 1 me me 8192 Aug 16 09:12 cli.ts

$ fauxnix "cat nope.txt"
cat: nope.txt: No such file or directory        # not a PowerShell stack trace

实测：您的模型在 PowerShell 上的表现可能比您想象的要差

同一模型（DeepSeek-V4-Pro）、相同的 5 个任务、在一台 Windows 机器上的三种执行模式 — 完整数据见 docs/benchmark-deepseek-v4-pro.md 和 `docs/benchmark-ark-models.md：

在 Volcano Ark 编码计划的 7 个模型上，PowerShell 与 fauxnix 的差距在每一个被测模型上都存在 — 最差情况（kimi-k2-thinking）：编写 PowerShell 比通过 fauxnix 慢 3.1 倍并出现 24 个错误事件，而 fauxnix 为 0 错误。在不安装 bash 工具链的情况下，fauxnix 的表现可达真实 bash 上限的 ~15% 以内。

Related MCP server: wmux

为什么

LLM 代理在 bash 方面的能力明显优于 PowerShell — bash 在训练数据中占主导地位，因此 Windows 上的模型经常会生成“看起来对、跑不起来”的命令（错误的引号、不是 curl 的 curl、代码页不匹配导致的乱码、难以理解的 CategoryInfo 错误转储）。现有解决方案要么是完整的虚拟机（WSL — 重量级、文件系统不同、环境隔离），要么是简单的 shell 包装器（底层仍然是 PowerShell）。

fauxnix 走第三条路：翻译，而非模拟。Linux 命令行中一个庞大且高价值的子集 — 文件操作、文本处理、进程管理、压缩归档、基础网络 — 可以干净地映射到 PowerShell + .NET。fauxnix 忠实地实现该子集，并且对于无法翻译的内容会响亮而有益地失败，因此代理永远不会得到静默的错误结果。

安装

npm install -g fauxnix-cli

或者从源码安装：

git clone https://github.com/20000419/fauxnix && cd fauxnix && npm install -g .

npm 包名是 fauxnix-cli（npm 上的 fauxnix 名称属于一个无关的 2015 年 websocket 库）；安装后的命令仍然是 fauxnix。

要求：Windows 自带 PowerShell 5.1+（内置）和 Node.js ≥ 18。

快速开始

# one-off commands
fauxnix "ls -la"
fauxnix "grep -rn TODO src | wc -l"
fauxnix "cat log.txt | grep -i error | sort | uniq -c"

# see what a command becomes (great for debugging / learning PS)
fauxnix translate "find . -name '*.log' -mtime +7 -delete"

# check your environment
fauxnix check

# run the MCP stdio server (what agent harnesses connect to)
fauxnix mcp

未知命令（git、node、npm、python、cargo、gh、docker 等）会以 argv 风格引号原生透传 — 无需重新解析字符串，也没有引号 bug。

与您的代理框架一起使用

fauxnix 附带一个 MCP stdio 服务器，暴露 bash 工具（以及 fauxnix_translate 和 fauxnix_session）。将任何支持 MCP 的框架指向它：

Claude Code

claude mcp add fauxnix -- fauxnix mcp

Codex（~/.codex/config.toml 或 codex mcp add fauxnix -- fauxnix mcp）

[mcp_servers.fauxnix]
command = "fauxnix"
args = ["mcp"]

注意：在非交互式 codex exec 模式下，MCP 工具调用会被审批层自动拒绝；请传入 --dangerously-bypass-approvals-and-sandbox（或交互式运行并批准一次）。

OpenCode（opencode.json）

{
  "mcp": {
    "fauxnix": { "type": "local", "command": ["fauxnix", "mcp"] }
  }
}

Kimi Code — 与其他框架不同，MCP 服务器位于 JSON 文件中，而不是 TOML 配置：~/.kimi-code/mcp.json

{
  "mcpServers": {
    "fauxnix": { "command": "fauxnix", "args": ["mcp"] }
  }
}

任何 MCP 客户端 — stdio 服务器：fauxnix mcp。工具名称是 bash（可通过 FAUXNIX_TOOL_NAME 覆盖）。工具描述已经教会模型所支持的子集，因此无需更改系统提示词。

MCP 会话会在工具调用之间持久化 cwd、环境变量、export/unset 和 cd -/OLDPWD — 它的行为类似于一个已登录的 shell，而不是无状态的 exec。

支持翻译的命令

~105 个命令，开发期间所有输出均与 Windows（Git Bash）上的真实 GNU coreutils 对齐：

• 文件：ls cp mv rm mkdir rmdir touch mktemp ln readlink realpath basename dirname stat file du df find chmod chown diff

• 文本过滤器：grep egrep sed awk sort uniq cut tr — sed/awk 脚本在翻译时解析（不支持的构造会抛出命名错误，绝不会静默出错）

• 文本 I/O：echo printf cat head tail wc tee nl tac md5sum sha1sum sha256sum base64 seq yes xargs

• shell/系统：cd pwd export unset env printenv ps kill pkill pgrep sleep which type whoami id groups date uname hostname uptime free nproc clear true false test [ [[ : pushd popd dirs sudo timeout man history less more source . eval exit alias set

• 网络：curl wget ping netstat ss ip ifconfig nslookup dig host

• 归档：tar gzip gunzip zcat zip unzip

此外还有 shell 语法：管道、&& / || / ;、重定向（> >> 2> 2>&1 < &>、/dev/null）、引号、$VAR、$(...) 命令替换、VAR=x cmd 前缀、~ 展开，以及 POSIX 风格路径规范化（/tmp、/d/foo → D:\foo）。

退出码遵循 bash 约定：0 成功，1 失败，2 用法错误/严重错误，127 命令未找到，124 超时。

工作原理

bash command ──parser──▶ AST ──translator──▶ PowerShell script ──executor──▶ powershell.exe
                                                                              │
agent ◀── GNU-style output, bash-style errors ◀── decoder (UTF-8 → GBK fallback) ◀┘

• 确定性翻译，运行时零 LLM 调用。

• 每个命令映射到一个生成器，该生成器生成符合“Fauxnix 合约”的自包含 PowerShell 块：每行字符串的 stdout、用于 bash 风格 stderr 的 [Console]::Error.WriteLine、用于退出码的 $script:fx_exit、用于 stdin 的 $input。

• 执行器为每个脚本强制使用 UTF-8 编码（[Console]::OutputEncoding、$OutputEncoding、chcp 65001），以严格 UTF-8 解码输出，并为旧版原生工具提供 GBK(936) 回退，从 stderr 中剥离 CLIXML 序列化和 PowerShell 噪音，并将常见的 PowerShell 错误（包括 zh-CN 区域设置消息）改写为 bash 措辞。

• 脚本通过 -EncodedCommand（UTF-16LE）运行，并在可能超过 32 KB 命令行限制时透明地回退到临时 .ps1 文件。

已知偏差（诚实清单）

fauxnix 针对代理实际运行的命令进行了优化。已知偏差如下：

• X=1 独立赋值遵循 export 语义（环境是会话级的；bash 中 shell 变量与导出变量的区分在这里不存在），并且同一段前缀在命令自身的词内对 $VAR 可见（此处 Z=in [[ $Z == in ]] 为真，而在 bash 中为假，因为词展开先于临时环境）。

• yes 最多输出 65,536 行 — PS 5.1 管道无法向上游生产者发送停止信号，因此无界的 yes | head 会挂起。

• tail -f、source、eval、alias、heredoc、反引号、shell 控制流（if/for/while）和后台 & 会被拒绝，并给出可操作的错误消息，而不是行为异常。

• chmod 仅映射只读位；执行位在 Windows 上是空操作。chown 是静默空操作（与 Git Bash 相同）。

• ps aux 列是近似值（没有按进程的 CPU% 统计，USER 显示 ?）。

• gzip -c/管道 stdin 是文本保真，而非字节保真；文件模式 gzip f 是字节精确的。

• 恰好产生一行的管道再输入 wc -l 会计数这一行（如果生产者省略了末尾换行，bash 会计数 0）。printf 'x' | md5sum 保持字节精确。

• sed/awk 支持常见子集；保持空间（hold-space）、标签、数组、循环会在翻译时抛出命名“not supported”错误。

• curl/wget 默认拒绝回环/私有/保留地址（localhost、127.x、::1、10.x、172.16–31.x、192.168.x、169.254.x），作为代理驱动 HTTP 的安全默认值。

• 原生命令管道与编码：PS 5.1 只有一个控制台编码旋钮，因此将本地化管理工具（ipconfig、tasklist — zh-CN 下为 GBK）与 UTF-8 原生开发工具（node、curl）通过管道连接时，无法在管道中间同时干净地解码。默认优先使用 UTF-8 开发工具；当您的代理需要 grep 原生 Windows 管理工具的中文输出时，请设置 FAUXNIX_NATIVE_ENCODING=ansi。文件读取总是按文件嗅探（严格 UTF-8 → GBK 回退），因此对 GBK 文件 使用 grep/sed/awk 在任一模式下都能工作 — 这与 Git Bash 不同，后者只会匹配其区域设置所假定的编码。

开发

npm install
npm test          # unit + real-PowerShell integration suite (Windows only, auto-skipped elsewhere)
npm run build
npx tsx scratch/run.mjs "any bash command"   # quick live check

架构图：src/parser.ts（bash 子集 → AST）· src/translator.ts（AST → PowerShell + 执行器包装）· src/executor.ts（spawn、重定向、会话持久化）· src/commands/*.ts（每个命令的生成器）· src/mcp.ts（MCP 服务器）· src/cli.ts。

许可证

MIT © 20000419