@godspeedai/cognate-execution

中文文档
0.10.0发布于 2026/11/16Apache-2.0ES Module构建来源已验证近 30 天下载 3189

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

中文使用文档
文档目录8 节
  1. 安装
  2. 快开始
  3. 合同和供应商
  4. program.run
  5. 写入提供者
  6. 限制
  7. 相关软件包
  8. 许可证

@ godspideai/ cognate- 执行

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

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

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

安装

bun add @godspeedai/cognate-execution

要求数 阿宝 1.4.0. 取决于 @godspeedai/cognate-kernel-api 联 合 国 Component 形状 – 没有传送或库类型跨越此软件包的边界.

快开始

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 在运行时间或内核上挂载能力组件:

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,并用共享套房证明:

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 路径,等等 —— 仅对制作它的提供者有意义 .

许可证

阿帕奇 - 2.0

版本与发布记录

@godspeedai/cognate-execution 共发布 20 个版本,首次发布于 2026/10/09;过去 12 个月发布了 20 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.10.0latest2026/11/16今天
0.9.22026/11/152 天前
0.9.12026/11/143 天前
0.9.02026/11/0610 天前
0.8.02026/10/2720 天前
0.7.12026/10/2523 天前

关于 @godspeedai/cognate-execution 的常见问题

@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 和提交记录判断。