# @bjorntech/key-ferry 中文文档

规范地址：https://npmcn.com/package/%40bjorntech/key-ferry/

版本：0\.1\.17
npm 元数据更新时间：2026-11-07T06:35:06.506Z
中文译文更新时间：2026-11-08T05:27:49.343Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：614 kB，92 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：effect 4\.0\.1，solid-js \>=1\.9\.0，@opencode/plugin 2\.0\.30
- 首次发布：2026-10-16T15:54:21.107Z
- 最新版本发布：2026-11-07T06:35:06.187Z
- 近 30 天下载量：2200（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

OpenCode V2 的工程范围密钥渡轮集成

## 安装

```sh
npm install @bjorntech/key-ferry
```

也可以使用：`pnpm add @bjorntech/key-ferry`、`yarn add @bjorntech/key-ferry`、`bun add @bjorntech/key-ferry`

## README

# @bjorntech/ key-ferry (英语)

Global and project-scoped Key Ferry 证书代理集成 OpenCode V2.

## 保护什么

原生效果 4 插件拥有一个工程范围 Varlock 代理进程和 保护明确选择的 MCP 服务器 :

-   本地MCP服务器接收占位符支持的环境映射.
-   远程 API- key MCP 服务器使用经认证,范围化回放中继器. 中继器通过 Varlock 的 HTTP 转发流式 HTTP 和 遗留 SSE 配置的 HTTPS 端点的 CONNECT 代理 .
-   启动、刷新、丢失位置持有人、中继和侧车故障失败 关闭。 没有直接运输倒退.
-   未选择的远程服务器,包括本地的OAuth服务器,保持不变.

插件从不包装 OpenCode, 变异全局 `process.env`,或存储真实 openCode 配置中的秘密值。 公共地位、RPC和TUI产出 永不曝光中继符、环境值、 CA 内容或原始守护进程 输出.

这是范围化的证书 - 代用路线, 不是一个完整的沙盒。 同一用户 进程仍然可以访问正常文件、存储和守护进程。 远程中继器 控制其配置的出入境路径,而不是依赖 MCP 客户端 荣誉代理环境变量,但没有保证响应有效载荷 将每个秘密清洗. 不包括直接提供者/API运输保护.

## 所需资源

-   OpenCode V2 有原生代码 `@opencode/plugin/effect`
-   `@opencode/plugin` 2.0.30 兼容运行时间
-   4.0.1 兼容运行时间
-   22号节点或更新
-   Varlock CLI 1.23.0 单独安装为 `varlock`
-   安装的 Varlock CLI 和配置的 Varlock 环境/schema 与 机密和代理规则 您的 MCP 服务器需要
-   一个私有的,可写作的所有权记录运行时间目录. 默认情况下 实值 `tmpdir()/key-ferry-<uid>`· ; `adapter.ownershipDirectory` 可用于 输入另一个私有、可写目录。 如果无法保证, 启动 未关闭 `ownership_unavailable` 诊断(另见 `key-ferry.doctor`) (中文(简体) ).
-   配置机密源和认证 [Varlock 文档](https://varlock.dev/)

已同第24号节点和第1.4.2号舱一道进行了核查 原生OpenCode V2包类型和效果 4.0.1.

## 安装

OpenCode 自动安装配置的 npm 插件 。 将软件包添加到 全局 OpenCode 插件配置( 通常情况下) `~/.config/opencode/opencode.json`(中文(简体) ) 并保存任何已存在的无关条目 :

```jsonc
{
  "plugins": [
    {
      "package": "@bjorntech/key-ferry",
      "options": {
        "enabled": true,
        "requireStrictEgress": true,
        "projectDirectory": ".",
        "servers": {
          "example-local-mcp": { "env": ["FAKE_API_KEY"] },
          "example-remote-mcp": {
            "remote": {
              "headers": {
                "Authorization": { "env": "REMOTE_API_KEY", "prefix": "Bearer " }
              }
            }
          }
        }
      }
    }
  ]
}
```

软件包在全球配置,而 `projectDirectory` 选择 服务器映射决定保护哪个项目上下文。 未放大的 MCP 服务器仍在本地 OpenCode 行为下。 选定的远程 API- key 服务器 必须明确设置 `oauth: false`; 原生 OAuth 保持不变 未选中服务器 .

分别安装 Varlock CLI 。 优先使用共享的 CLI 安装 在每个工程中安装 :

```sh
brew install dmno-dev/tap/varlock
varlock --version
```

该插件不安装 Varlock 或解锁一个秘密商店 。 配置其 环境与认证,分别遵循 [Varlock 文档](https://varlock.dev/)。 。 。 .

包裹的兄弟们 `./tui` 导出在 服务器插件已装入 。 不添加重复内容 `cli.json` 条目 普通服务器插件安装 。 全球 `cli.json` 条目仅有用 用于仅连接到远程 OpenCode 服务器的 CLI 或 CLI 部署 已装入服务器插件 .

设定 `projectDirectory` 至 Varlock 工程根中包含该图案。 这个 插件启动并拥有其 Varlock 侧车本身; 不包写 OpenCode 或 手动运行 `varlock proxy`。 。 。 .

## 全球配置和项目选入

本地插件条目可以在 OpenCode 全局配置中安装一次. 设定 `projectConfig.enabled` 改为 `true` 使项目文件符合条件; 是 `false` 默认的反向兼容性。 全球配置拥有 一个瓦洛克集团及其绘图 当前 OpenCode 项目中的一个项目 root 可以在 `.opencode/key-ferry.jsonc`数字 :

```jsonc
{
  "enabled": true,
  "servers": {
    "project-mcp": { "env": ["PROJECT_API_KEY"] }
  }
}
```

使用 [全球实例](https://npmcn.com/package/%40bjorntech/key-ferry/examples/global/opencode.json),则 [本地项目示例](https://npmcn.com/package/%40bjorntech/key-ferry/examples/project/opencode.json),则 [项目绘图实例](https://npmcn.com/package/%40bjorntech/key-ferry/examples/project/.opencode/key-ferry.jsonc) 可复制 形状。 项目文件只映射已存在的 MCP 服务器 工程的本地 OpenCode 配置; 它不定义或安装 MCP 服务器,它不需要第二个 Key Ferry 插件条目。 配对 [本地项目实例](https://npmcn.com/package/%40bjorntech/key-ferry/examples/project/opencode.json) 显示单独 定义。 这个 合成 `GLOBAL_API_KEY` 财务报告和审定财务报表 `PROJECT_API_KEY` 名字是计划参考文献, 非证书; 分别配置每个 Varlock 根及其密源 使用 [Varlock 文档](https://varlock.dev/)。工程文件为 相对于 cononic 工程根而不是服务读取 工作目录及其可选 `projectDirectory` 必须留在里面 树根。 它只包含项目绘图:全球绘图、环境键和 Varlock计划从未进口或联合。 重新使用的项目映射a 全局服务器名必须在 `overrides`; 否则碰撞 被拒绝。 其他全球约束服务器不受影响.

全球 `projectConfig.activation` 政策是一层楼. `"auto"` 激活一个 自动获得资格的项目; `"manual"` 需要明确 `key-ferry.activateProject` 命令。 项目可能限制自动全球 使用自己的激活 `"activation": "manual"`,但不能升级手动 全球政策。 手动激活是当前位置的内存,并且是 不是一个存储的入学名单。 状态纯洁,报告所有配置范围, 包括不活动的项目范围。 默认刷新和医生保留 全局行为; 范围化的项目操作只针对选定的活动 项目组,永远不要激活它。 使用 `activateProject` 首先当 项目正在等待启动.

这种选入是执行政策,而不是认证或安全边界. Varlock 供应商和 `@exec` 可执行代码,而一个不信任的寄存器是 而非由此特性所装入的沙盒 。 在启用全局前审查项目文件 自动激活.

## 配置

本地映射保存 MCP 命令, cwd, 和无关的环境 :

```jsonc
"example-local-mcp": {
  "env": { "UPSTREAM_API_KEY": "FAKE_API_KEY" }
}
```

远程映射地图目标为HTTP头来精确瓦洛克环境名称. 字符串形式是一个环境参考, 绝不是一个原始标题值 :

```jsonc
"example-remote-mcp": {
  "remote": {
    "headers": {
      "Authorization": { "env": "REMOTE_API_KEY", "prefix": "Bearer " },
      "X-Tenant": { "env": "REMOTE_TENANT", "suffix": "-synthetic" }
    }
  }
}
```

信头名称被验证用于控制、跳跃、协议、复制和 证明性障碍 目标 URL 来自本地的 MCP 远程 配置,不是来自中继绘图. HTTPS 证书和碎片 拒绝。 除非 明确 `allowPrivateNetwork: true` 政策已经设定。 普通企业DNS 姓名并非仅仅因为可以在国内解决而被拒绝.

使用 `examples/single-project/.env.schema` 仅用于遗产单根的例子。 给 全球/ 项目设置, 复制 `examples/global/.env.schema` 输入已配置 全球瓦洛克根和 `examples/project/.env.schema` 输入项目 分开的瓦洛克根。 不要重用一个综合计划 或围绕这个工作 与 Varlock 导入分离: Varlock 在 Key Ferry 之前装入全部计划 请求的过滤键 。 标记每个远程上游主机 `@proxy(domain="...")` 保留 `@proxyConfig={egress="strict"}`通过Varlock配置任何秘密来源; Key Ferry 不安装 Varlock 、 创建其计划或配置提供者 认证。 永远不要做一个真正的秘密.

经纪人流程仍然可用 `idleTimeoutMs` 毫秒后 最后一次租赁解除( 默认 : `600000`或十分钟). 这个可以重用 在返回项目时认证 Varlock 代理 。 设定 `idleTimeoutMs: 0` 立即拆卸; 闲置经纪人总是被停止 主机关闭或当其计划/配置身份发生变化时。 这是一个 安全/业绩权衡:已解密仍在代理程序中 保存到项目离开后闲置超时的内存。 启动时键渡 还收获了先前程序留下的孤儿身份核查代理记录. 如果在关闭时停止代理失败, Key Ferry 将保留其所有权记录和 将清理推迟到下一个启动,其收割者重试同一会话UUID. 在 SIGINT 或 SIGTERM 上,它执行有界限的清理(最多 三秒钟),删除 它的信号听器,当它是唯一的听器的时候,它能重新发出信号 保存主机正常终止语义; 主机拥有的信号 听众继续控制.

## TUI 命令

| 调色板命令 | 斜线命令 | 难民保护委员会 |
| --- | --- | --- |
| `key-ferry.status` | `/key-ferry-status` | `status` |
| `key-ferry.refresh` | `/key-ferry-refresh` | `refresh` |
| `key-ferry.doctor` | `/key-ferry-doctor` | `doctor` |
| `key-ferry.project.activate` | `/key-ferry-project-activate` | `activateProject` |
| `key-ferry.project.refresh` | `/key-ferry-project-refresh` | `refresh({ scope: "project" })` |
| `key-ferry.project.doctor` | `/key-ferry-project-doctor` | `doctor({ scope: "project" })` |

重命名是故意突破0.1.0发布:否 `varlock-*` 命令别名保留.

刷新和医生报告安全生命周期和远程配置诊断. 项目命令选择活动的项目组;它们不激活 非活动项目 . `activateProject` 开始一次合格的手工项目 当前位置。 它们不提供证明提示或收集 证书。 医生可以 调和或重建选中的不健康 `oauth:false` 远程中继器 Varlock 准备成功, 因此认证仍然取决于配置 瓦洛克语境.

本地插件激活并不意味着经纪人准备 。 启动期间, 映射的服务器在编组准备就绪之前一直关闭;一个健康组 如果另一组失败,则继续。 残疾融合不注册 状态RPC,所以预计为404.

## 运输和生命周期限制

中继支持可流式 HTTP POST/GET/DELETE,流式SSE,范围化 回回认证、 限定请求处理和会话 URL 重写 用于遗留的SSE端点。 现代可流化的HTTP和遗留的SSE反应是: 通过边框流; 压缩或过大流量未关闭 内。 在最多256个注册会话时保持中继功能 路线; 重复登记不消耗容量, 新路线为 盖后被拒绝。 Varlock 刷新时重新设置本地 MCP 会话状态 更改管理器生成或替换中继器时。 现有远程 课程必须重新连接.

Varlock的公用CA在IO边界被读取并被接力所信任. 这个 CA不是一个秘密,而原始的秘密值仍然留在OpenCode之外. 这是 不是一个完整的响应内容洗涤器,也不替换原生 OAuth . 公共CA使用 瓦洛克的要求 `0644` 信任-物质权限. 清理范围仅限于此项目实例,从未执行全局 瓦洛克关闭.

已打包的根, TUI, 和中继导入路径一起验证 。 无包装 需要进程.

## 核查

```sh
bun typecheck
bun test
bun run build
```

涵盖范围、事由和每个功能的《加拿大区域行动方案》门的细节记录如下: [质量检查](https://npmcn.com/package/%40bjorntech/key-ferry/docs/quality.md)。 。 。 .

两次现场的Varlock测试被锁定并跳过,除非 `VARLOCK_LIVE_BINARY` 指向绝对的 CLI 路径。 它使用合成 固定装置和孤立的配置。 没有每个测试主机证书或提供者 需要认证。 明确使用:

```sh
VARLOCK_LIVE_BINARY=/absolute/path/to/varlock bun test tests/varlock-live.test.ts
VARLOCK_LIVE_BINARY=/absolute/path/to/varlock bun test tests/remote-varlock-live.test.ts
```

普通的套房和有门的活装置是独立的核查层. 运行 ; 不将普通套件当作 认证每个外部MCP供应商、生产部署或现场 OpenCode TUI 会话.

见 [建筑](https://npmcn.com/package/%40bjorntech/key-ferry/docs/architecture.md), (中文(简体) ), [解决问题](https://npmcn.com/package/%40bjorntech/key-ferry/docs/troubleshooting.md),以及 [质量检查](https://npmcn.com/package/%40bjorntech/key-ferry/docs/quality.md), (中文(简体) ), [单项目实例](https://npmcn.com/package/%40bjorntech/key-ferry/examples/single-project/opencode.json), (中文(简体) ), [全球配置实例](https://npmcn.com/package/%40bjorntech/key-ferry/examples/global/opencode.json),以及 [项目文件示例](https://npmcn.com/package/%40bjorntech/key-ferry/examples/project/.opencode/key-ferry.jsonc)。 。 。 .

## 常见问题

### @bjorntech/key-ferry 是什么？

OpenCode V2 的工程范围密钥渡轮集成

### 如何安装 @bjorntech/key-ferry？

在项目目录运行 npm install @bjorntech/key-ferry，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（4\.0\.1）、solid-js（\>=1\.9\.0）、@opencode/plugin（2\.0\.30）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bjorntech/key-ferry 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bjorntech/key-ferry 支持 ESM 还是 CommonJS？

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

### @bjorntech/key-ferry 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bjorntech/key-ferry 可以商用吗？

@bjorntech/key-ferry 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bjorntech/key-ferry 的下载量有多少？

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

### @bjorntech/key-ferry 还在维护吗？

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