@ 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 路径,等等 —— 仅对制作它的提供者有意义 .
相关软件包
@godspeedai/cognate-execution-sshSSH 主机提供者( SFTP + 远程执行结束)ssh2) (中文(简体) ).@godspeedai/cognate-execution-wsl——WSL发行商.@godspeedai/cognate-runtime-bun- 接收通过createRuntime。 。 。 .@godspeedai/cognateSDK伞.
许可证
阿帕奇 - 2.0