# @godspeedai/cognate-execution 中文文档

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

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

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

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

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

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

## 中文简介

框架所属的执行-世界合同:文件系统和处理端口,可替换的提供者,以及文件系统._/进程._ 能力部分。 没有运输或图书馆类型.

## 安装

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

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

## README

# @ godspideai/ cognate- 执行

Cognate 的执行-世界合同:高级工具的框架拥有的文件系统和处理端口(`read`, (中文(简体) ), `edit`, (中文(简体) ), `bash`,以及任何其它触及文件或运行命令的)消耗,加上互换的提供者注册 _地点_ 这些操作发生——本地机器,SSH主机,WSL发行,或者你自己的——不改变工具.

**何时使用此软件包 :** 您想要在可替换的提供者后面获得文件/进程访问,或者您正在写入一个必须满足相同合同的提供者(SSH,一个容器运行时间,一个测试双人)。 现成供应商: [`@godspeedai/cognate-execution-ssh`](https://www.npmjs.com/package/@godspeedai/cognate-execution-ssh) 财务报告和审定财务报表 [`@godspeedai/cognate-execution-wsl`](https://www.npmjs.com/package/@godspeedai/cognate-execution-wsl)。 。 。 .

一行的想法: 一个工作空间说 _什麽_ 一个用户在工作; 一个执行世界说 _地点_ 其文件被读取并运行命令; 在一个下替换提供者 `filesystem.*` 编号 : `process.exec` 合同将执行移至另一台机器,对工具、代理或批准作零更改.

## 安装

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

要求数 [阿宝](https://bun.sh/) 1.4.0. 取决于 [`@godspeedai/cognate-kernel-api`](https://www.npmjs.com/package/@godspeedai/cognate-kernel-api) 联 合 国 `Component` 形状 – 没有传送或库类型跨越此软件包的边界.

## 快开始

```ts
import { createExecutionWorldRegistry, localExecutionWorld } from "@godspeedai/cognate-execution";

const registry = createExecutionWorldRegistry([
  localExecutionWorld({ worldId: "local", metadata: { host: "dev-box" } }),
]);

const world = registry.get("local");
const path = world.fileSystem.resolve("/home/me/workspace", "src/app.ts"); // canonical path; escapes throw PathEscapeError
const exists = await world.fileSystem.exists(path);
const result = await world.process.exec({ argv: ["bun", "test"], cwd: "/home/me/workspace", timeoutMs: 60_000 });
console.log(result.exitCode, result.stdout, result.timedOut);

await registry.dispose();
```

`registry.get` 掷出 `WorldUnavailableError` 对于一个未知或注定要的世界来说,它永远不会回到另一个世界。 缺少的文件报告为 `undefined` 从 `stat`编号 :`version`,而不是作为一个错误。 供应商 `metadata` 对持久状态和日志安全:主机名称和认证 _类型_,从不证明.

将世界暴露为能力(因此代理人和工具援引 `filesystem.readText` 财务报告和审定财务报表 `process.exec` 在运行时间或内核上挂载能力组件:

```ts
import { executionWorldsComponent } from "@godspeedai/cognate-execution";
import { createRuntime } from "@godspeedai/cognate-runtime-bun";

const runtime = await createRuntime({
  store: "./app.sqlite",
  agents: [/* ... */],
  policy, // authorize the filesystem.*/process.exec capabilities
  actions,
  components: [executionWorldsComponent(registry)],
});
```

## 合同和供应商

| 导出 | 仁爱 | 含义 |
| --- | --- | --- |
| `FileSystemPort` | 端口 | `resolve`, (中文(简体) ), `stat`, (中文(简体) ), `exists`, (中文(简体) ), `readText`, (中文(简体) ), `list`, (中文(简体) ), `writeText`, (中文(简体) ), `version` |
| `ProcessPort` | 端口 | `exec(spec, { signal })` → `{ stdout, stderr, exitCode, timedOut }` |
| `ExecutionWorldProvider` | 提供者 | 一个 `worldId`, (中文(简体) ), `kind`保险 `metadata`,两个端口,同位素 `dispose()` |
| `createExecutionWorldRegistry()` | 工厂 | 登记/未登记/获取提供者; `list()` 返回无秘密描述符 |
| `executionWorldsComponent(registry)` | 组件 | 发布以下功能, 由呼叫者路由 `worldId` |
| `localExecutionWorld()` | 提供者 | 当地机器(`node:fs` + 键 `Bun.spawn`(中文(简体) ) |
| `memoryExecutionWorld()` | 提供者 | 具有虚拟文件系统和脚本命令的处理中决定世界(`memory echo/fail/slow`用于测试 |
| `PathEscapeError`, (中文(简体) ), `WorldUnavailableError` | 错误 | 路径逃脱了它的根;世界未知,无法到达,或被处理 |

已公布的能力标识 : `filesystem.resolve`, (中文(简体) ), `filesystem.stat`, (中文(简体) ), `filesystem.readText`, (中文(简体) ), `filesystem.writeText`, (中文(简体) ), `filesystem.list`, (中文(简体) ), `filesystem.version`, (中文(简体) ), `process.exec`消除一个提供者使其能力无法解决——一个干净的失败,决不是无声的当地倒退.

### `program.run`

`programExecutorComponent(registry)` 发表 `program.run`,在已宣布的工作空间内应用以散列为支撑的统一diff的单独能力,然后运行一个已宣布的命令。 它像任何能力一样通过内核被引用,所以你的政策和治理决定它是否运行(它刻意不在) `EXECUTION_CAPABILITY_IDS`) (中文(简体) ).

-   输入 : `{ worldId, workspace, patch, patchSha256, argv, cwd?, timeoutMs? }`。 。 。 . `patchSha256` 是补丁 UTF-8 字节的sha256;拒绝匹配(`ProgramRefusedError`,原因 `patch_hash_mismatch`在一切运行之前.
-   补丁在内存中先被应用,只有在每个hunk精确应用时才被写入;否则工作空间没有被触及. v1 只编辑已存在的文本文件(没有创建,删除,重命名或二进制).
-   `argv` 是一个交给世界进程端口的阵列,绝不是外壳;补丁目标并 `cwd` 必须在 `workspace`。在一个文件系统提供可选选项的世界中 `realPath` (当地世界确实如此),每个目标的真正路径和 `cwd` 必须等于真实的工作空间根加上相同的相对路径: 路径的任意一个符号链接被拒绝 `path_escape`不论它指向外面还是留在里面 检查在每次写作之前和命令之前立即重复. 最后一个检查和写入之间的一个并行进程互换的链接不排除在外.
-   如果写出失败, 每一个被触碰的文件( 包括失败的文件, 可能是部分被写入的) 都会被写回; 如果还原也失败了, 则留下的错误名 。 无世界 `realPath` (记忆,和POSIX-script的世界, 守卫自己的同音符) `resolve`/IO)跳过真实路径检查.
-   结果 : `{ patchSha256, filesPatched, command, exitCode, timedOut, outputDigest, stdout, stderr }`非零退出抛出 `ProgramCommandFailedError`,因此失败的引用记录保留了退出代码,补丁散列,命令和文摘.

也导出 : `commandFileSystem(runScript)` a 包括: `FileSystemPort` 由单个“ 运行此 POSIX 脚本” 原始( 由 WSL 提供者使用; 方便容器使用); POSIX 帮助器 `shellQuote`, (中文(简体) ), `execScript`, (中文(简体) ), `supervisedExecScript`, (中文(简体) ), `resolvePosix`, (中文(简体) ), `createRootGuard`; 和 `./conformance` 子路径.

## 写入提供者

导出返回一个函数 `ExecutionWorldProvider`,并用共享套房证明:

```ts
import { executionWorldConformance } from "@godspeedai/cognate-execution/conformance";

executionWorldConformance("my-world", async () => ({
  provider: myExecutionWorld({ /* ... */ }),
  root: "/workspace", // a location this provider owns
  commands: {
    echo: (marker) => ({ argv: ["printf", "%s", marker], cwd: "/workspace" }),
    fail: (marker, code) => ({ argv: ["sh", "-c", `printf %s ${JSON.stringify(marker)} 1>&2; exit ${code}`], cwd: "/workspace" }),
    slow: () => ({ argv: ["sleep", "30"], cwd: "/workspace" }),
  },
}));
```

该套房声称,对于任何提供者: 封禁拒绝逃脱,一个缺失的文件是 `undefined` 而不是掷出、读出、写出, `version` 内容更改, `exec` 报告 stdout/stderr/exit 代码、超时和中止确实结束了这一过程,以及 `dispose()` 是无能的。 运出的地方,内存,SSH,和WSL的提供者都不加修改地通过.

## 限制

-   合同只定义文件和进程——没有套接字,没有表,没有花样.
-   `resolve` 封存对本地世界来说是名词化的(符号链接作为-is解决);SSH 提供者增加了一个符号链接检查,以及 `commandFileSystem`\- 基于世界的检查通过 `realpath`。在同时互换的同位素链接上进行检查时的比赛在任何地方都没有被阻止.
-   `cwd` 在一个 `ExecSpec` 是由提供者拥有的 : 本地的 OS 路径, WSL 发行内部的 POSIX 路径,等等 —— 仅对制作它的提供者有意义 .

## 相关软件包

-   [`@godspeedai/cognate-execution-ssh`](https://www.npmjs.com/package/@godspeedai/cognate-execution-ssh) SSH 主机提供者( SFTP + 远程执行结束) `ssh2`) (中文(简体) ).
-   [`@godspeedai/cognate-execution-wsl`](https://www.npmjs.com/package/@godspeedai/cognate-execution-wsl) ——WSL发行商.
-   [`@godspeedai/cognate-runtime-bun`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-bun) - 接收通过 `createRuntime`。 。 。 .
-   [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) SDK伞.

## 许可证

阿帕奇 - 2.0

## 常见问题

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

框架所属的执行-世界合同:文件系统和处理端口,可替换的提供者,以及文件系统\./进程\. 能力部分。 没有运输或图书馆类型\.

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

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

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

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

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

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

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

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

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

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

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

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

