# @godspeedai/cognate-execution-wsl 中文文档

规范地址：https://npmcn.com/package/%40godspeedai/cognate-execution-wsl/

版本：0\.10\.0
npm 元数据更新时间：2026-11-16T03:43:25.188Z
中文译文更新时间：2026-11-16T19:05:21.501Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40godspeedai/cognate-execution-wsl
原文对照：https://npmcn.com/package/%40godspeedai/cognate-execution-wsl/?lang=original
项目主页：https://github.com/GodSpeedAI/Cognate#readme
源码仓库：https://github.com/GodSpeedAI/Cognate

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：34.8 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2026-10-09T02:28:44.521Z
- 最新版本发布：2026-11-16T03:43:24.858Z
- 近 30 天下载量：2966（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

WSL 作为执行世界的分布: 文件系统和处理端口 `wsl.exe -e sh -s`与所有其他供应商的合同相同.

## 安装

```sh
npm install @godspeedai/cognate-execution-wsl
```

也可以使用：`pnpm add @godspeedai/cognate-execution-wsl`、`yarn add @godspeedai/cognate-execution-wsl`、`bun add @godspeedai/cognate-execution-wsl`

## README

# @godspideai/cognate-execution-wsl (英语)

作为Cognate执行世界的 WSL 分布: 文件系统和进程端口已执行 `wsl.exe`,在与其他所有供应商相同的合同背后——所以一个代理工具在Linux内部运行,而主机则停留在任何地方. 根是 POSIX 路径 _分布式内_; 从来没有Windows路径进入合同.

**工作地点:** 此提供者在 WSL 内部运行的 Linux 主机上被执行( Windows interop) `wsl.exe` 编辑 `PATH`) (中文(简体) ). 一个运行 Bun 的本地Windows主机未经测试,没有WSL安装和发行对象,提供商就毫无意义. 如果你只需要一个"Linux盒子", [`@godspeedai/cognate-execution-ssh`](https://www.npmjs.com/package/@godspeedai/cognate-execution-ssh) 是更便携式的远程提供者.

## 安装

```sh
bun add @godspeedai/cognate-execution-wsl
```

要求数 [阿宝](https://bun.sh/) 1.4.0, WSL 安装可透过 `wsl.exe` (以 `wslBin`),以及 [`@godspeedai/cognate-execution`](https://www.npmjs.com/package/@godspeedai/cognate-execution),其合同 这个提供者执行.

## 快开始

```ts
import { wslExecutionWorld } from "@godspeedai/cognate-execution-wsl";

const world = wslExecutionWorld({ worldId: "ubuntu", distro: "Ubuntu-24.04" });

const path = world.fileSystem.resolve("/home/me/project", "README.md");
const readme = await world.fileSystem.readText(path);
const result = await world.process.exec({ argv: ["cargo", "test"], cwd: "/home/me/project", timeoutMs: 300_000 });
console.log(result.exitCode, result.stdout, result.timedOut);

await world.dispose();
```

## 设计:发射 `wsl.exe` 尽可能少

`wsl.exe` 是堆栈的脆弱部分——在冷冷的分发上发射需要几秒钟,在装入Windows WSL服务时断断续续或失败发射(平面) `wsl.exe -e true` 已用9至20秒测量。 因此,提供者保留了一小批持久性的 `sh -s` 分布和运行 _所有的东西_ 通过它们作为框架请求(出站、出站和在唯一标记之间的退出状态返回):

-   在稳定状态下,一个代理运行 发射没有 `wsl.exe` ;只有会话启动才有。 一场未能上台的会话,在世界未能结束之前就被取代了.
-   一个命令在自己的进程组中运行( O)`setsid`) (中文(简体) ). 超时或中止时,该组从第二会场中被杀死,作为最后手段,繁忙会场被关闭——结束 `wsl.exe` 结束一切它开始, 所以整个过程树死亡.
-   命令在不同的会话中平行运行;闲会返回池(最多为4个),一旦没有世界使用,则在短暂的宽限期后关闭. 一个会话的寿命被束缚在它的斯丁管上,所以如果主机进程死亡,它就会自行结束. 举行会话也使发行不被WSL闲置关闭.
-   文件操作基于 `commandFileSystem` 从 [`@godspeedai/cognate-execution`](https://www.npmjs.com/package/@godspeedai/cognate-execution),所以相同的形状适合容器.
-   失败从来不是沉默,也不会是本地的:一个缺失 `wsl.exe`,无法到达的分布,或被支配的世界上升 `WorldUnavailableError`。 。 。 .

## 选项

| 选项 | 含义 |
| --- | --- |
| `worldId`, (中文(简体) ), `distro` | 注册名称和 WSL 分布到目标 |
| `user?` | Linux 用户在发行区内部(`wsl.exe -u`; 默认省略 |
| `wslBin?` | 路径 `wsl.exe` 二进制( 默认 ): `wsl.exe` 编辑 `PATH`(中文(简体) ) |
| `defaultTimeoutMs?` | 默认命令超时( 30 s) |
| `fileOpTimeoutMs?` | 固定会话中一个文件操作的停顿预算( 重新开始并重试一次) |
| `sessionStartTimeoutMs?` | 开新会需要多长时间 |
| `maxOutputBytes?` | 每个命令输出上限( 10 MiB) |
| `shellCommand?` | 测试接合器替换整个发射命令(必须从 stdin 读取脚本类似 `sh -s`(中文(简体) ) |

## 限制

-   从WSL内部(使用Windows interop的Linux主机);运行 Bun的本地Windows主机尚未测试.
-   WSL 自己的服务仍然可以失败会话启动; 错误报告 `wsl.exe`而不是回到本地执行.
-   封装用途 `realpath`\- 基于检查(检查-当时使用);不阻止同时互换的同义链接.

## 相关软件包

-   [`@godspeedai/cognate-execution`](https://www.npmjs.com/package/@godspeedai/cognate-execution) 合同和合规套件.
-   [`@godspeedai/cognate-execution-ssh`](https://www.npmjs.com/package/@godspeedai/cognate-execution-ssh) ——SSH主机提供商,可移植替代品.
-   [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) SDK伞.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @godspeedai/cognate-execution-wsl 是什么？

WSL 作为执行世界的分布: 文件系统和处理端口 wsl\.exe -e sh -s与所有其他供应商的合同相同\.

### 如何安装 @godspeedai/cognate-execution-wsl？

在项目目录运行 npm install @godspeedai/cognate-execution-wsl，或使用 pnpm add / yarn add / bun add。

### @godspeedai/cognate-execution-wsl 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/godspeedai\_\_cognate-execution-wsl 是否存在。

### @godspeedai/cognate-execution-wsl 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @godspeedai/cognate-execution-wsl 可以商用吗？

@godspeedai/cognate-execution-wsl 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @godspeedai/cognate-execution-wsl 的下载量有多少？

根据 npm 官方下载统计，@godspeedai/cognate-execution-wsl 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,966 次，日均约 99 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @godspeedai/cognate-execution-wsl 还在维护吗？

最新版本 0\.10\.0 发布于 2026/11/16（今天）；至今共发布 20 个版本，其中过去 12 个月发布了 20 个；首次发布于 2026/10/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

