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

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

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

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

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

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

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

## 中文简介

作为执行世界的SSH主机:SFTP文件系统和远程执行在ssh2之上,有强制主机-键验证,ProxyJump和清洁处理等功能. 与其他供应商的合同相同.

## 安装

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

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

## README

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

作为Cognate执行世界的 SSH 主机: 文件覆盖 SFTP, 命令覆盖远程 `exec` - 在同一个后面 `filesystem.*` 编号 : `process.exec` 和所有其他供应商一样,所以在供应商之上没有任何人知道它是SSH。 建造于 [`ssh2`](https://www.npmjs.com/package/ssh2) 软件包.

**何时使用此软件包 :** 一个代理应该读取、写入和运行在远程机器上的命令,您可以通过 SSH 访问( 选择通过 跳转到主机) , 在发送任何消息之前验证主机身份 。 用于当地机器 [`@godspeedai/cognate-execution`](https://www.npmjs.com/package/@godspeedai/cognate-execution)是因为 `localExecutionWorld`;用于 WSL 分布式使用 [`@godspeedai/cognate-execution-wsl`](https://www.npmjs.com/package/@godspeedai/cognate-execution-wsl)。 。 。 .

## 安装

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

要求数 [阿宝](https://bun.sh/) 1.4.0. 取决于 `ssh2` 财务报告和审定财务报表 [`@godspeedai/cognate-execution`](https://www.npmjs.com/package/@godspeedai/cognate-execution) (合同 这个提供者的工具).

## 快开始

```ts
import { sshExecutionWorld } from "@godspeedai/cognate-execution-ssh";

const world = sshExecutionWorld({
  worldId: "build-box",
  host: "build.example.com",
  username: "dev",
  auth: { kind: "key", privateKeyPath: "~/.ssh/id_ed25519" }, // or { kind: "agent" } / { kind: "password", password }
  hostKeys: { fingerprints: ["SHA256:..."] }, // REQUIRED — or { knownHostsPath: "/home/me/.ssh/known_hosts" }
  jump: [ // ProxyJump, optional; each hop is verified like the target
    { host: "bastion.example.com", username: "dev", auth: { kind: "agent" }, hostKeys: { knownHostsPath: "/home/me/.ssh/known_hosts" } },
  ],
});

const path = world.fileSystem.resolve("/srv/workspace", "README.md");
const readme = await world.fileSystem.readText(path);
const result = await world.process.exec({ argv: ["cargo", "test"], cwd: "/srv/workspace", timeoutMs: 300_000 });

console.log(world.metadata); // { host, port, username, auth: "key", hostKey: "SHA256:..." } — safe for logs

await world.dispose();
```

建筑彻底拒绝空置主机钥匙政策. 与新主机的第一个连接应该通过 `probeHostKey`,它读取服务器的密钥和 _拒绝_ ——没有经过认证或发送——人类可以决定将所打印的指纹贴上:

```ts
import { probeHostKey } from "@godspeedai/cognate-execution-ssh";

const probe = await probeHostKey({ host: "build.example.com" });
console.log(probe.fingerprint, probe.keyType, probe.known); // "SHA256:..." "ssh-ed25519" "unknown"
// Show it to a person; pin it in hostKeys.fingerprints or known_hosts before connecting for real.
```

## 它的保证

-   **服务器是你钉住的.** 主机密钥核查是强制性的——没有信任先用,没有接受-任何方式. 出现不匹配现象 `HostKeyMismatchError` 在试图进行认证之前, 从未进行过再测试 。 平平无奇 `known_hosts` 条目, `[host]:port` 表格、通配符、否定和 `@revoked` 标记受到尊重; `@cert-authority` 条目被忽略(不支持).
-   **关闭失败.** 无法到达的主机, 已更改的密钥, 或已处理的世界会升起 `WorldUnavailableError`没有什么会回到当地处决.
-   **禁闭.** `resolve` 拒绝 lexical 逃逸, 任何读取/ 写入/ stat/ 列表( 通过 SFTP) 之前, 拒绝 root 内部的同义链接 `realpath`) (中文(简体) ).
-   **一个已取消的命令真的结束 .** 在一个主管之下运行的指令, 并有自己的流程组, 结束于 `TERM` 或当stdin到达EOF时——因此整个进程树甚至针对忽略信号请求或放弃连接的服务器而死.
-   **复相通达.** 在下一个操作上重拨了已丢弃的连接; 偶数文件操作重试一次, 命令和写作从不这样做 .
-   **清净处置.** `dispose()` 关闭直播频道,SFTP,以及每一次跳;它具有一能性,而后操作失败关闭.
-   **没有秘密泄露.** `metadata` 携带主机、端口、用户、认证 _类型_,以及经过验证的主机钥匙指纹——从没有密码,密码,或密钥. 错误也从不重复证书 .

## 测试您的整合

这个 `./fixture` 子路径导出 `startSshFixture` ——一个真正的进程内SSH服务器(sh2) `Server`)带有密码/公用钥匙认证,工作 `exec`,一个 SFTP 子集,以及用于 ProxyJump 的直接 tcpip 转发——这样,你自己的测试就可以运行共享兼容套件,从 [`@godspeedai/cognate-execution/conformance`](https://www.npmjs.com/package/@godspeedai/cognate-execution) 对一个没有外部机器的真正的SSH客户端/服务器对.

## 已知限制

-   远程登录 shell 必须接受 `exec sh -c '<posix script>'`。 。 。 .
-   `version` 实值 `mtime(seconds):size` (SFTP属性只携带了整秒),所以两个写在同一秒内,大小相等的外观不变. 当地和指挥世界 `mtime(ns):size:inode`。 。 。 .
-   并联封存检查是检查时使用:检查与操作之间的并发互换没有被阻止.
-   没有键盘交互/2FA认证和没有 `@cert-authority` 支助.

## 相关软件包

-   [`@godspeedai/cognate-execution`](https://www.npmjs.com/package/@godspeedai/cognate-execution) 合同和合规套件.
-   [`@godspeedai/cognate-execution-wsl`](https://www.npmjs.com/package/@godspeedai/cognate-execution-wsl) ——WSL发行商.
-   [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) SDK伞.

## 许可证

阿帕奇 - 2.0

## 常见问题

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

作为执行世界的SSH主机:SFTP文件系统和远程执行在ssh2之上,有强制主机-键验证,ProxyJump和清洁处理等功能\. 与其他供应商的合同相同\.

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

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

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

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

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

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

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

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

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

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

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

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

