# @cat-factory/gatekeeper-bindings 中文文档

规范地址：https://npmcn.com/package/%40cat-factory/gatekeeper-bindings/

版本：0\.46\.0
npm 元数据更新时间：2026-11-04T00:26:49.891Z
中文译文更新时间：2026-11-09T09:56:29.440Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cat-factory/gatekeeper-bindings
原文对照：https://npmcn.com/package/%40cat-factory/gatekeeper-bindings/?lang=original
源码仓库：https://github.com/kibertoad/cat-factory

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

- 包体积（解压后）：262 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-08-08T12:32:23.936Z
- 最新版本发布：2026-11-04T00:26:49.482Z
- 近 30 天下载量：2959（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

Cat-factory 公共 API (/api/v1) 的政策性附加操作表: per- operation speces, 突变和传输元数据, 并使用 thunks 超越 @ cat-factory/sdk, 生成自 SDKs 相同的 OpenAPI spec. 为证书持有所建

## 安装

```sh
npm install @cat-factory/gatekeeper-bindings
```

也可以使用：`pnpm add @cat-factory/gatekeeper-bindings`、`yarn add @cat-factory/gatekeeper-bindings`、`bun add @cat-factory/gatekeeper-bindings`

## README

# @ cat- factory/ 守门员- 绑定

## 这是什么

每个数据要素的政策说明表 **公开 API** (单位:千美元)`/api/v1`操作,加上 瞄准梯帮助对象 策略层 排序按键并用它进行调用。 喜欢 [`sdk/mcp`](https://github.com/kibertoad/cat-factory/tree/main/sdk/mcp)这是 **非第五个 客户端**: 与四个SDK所暴露的操作相同, 投射为表格, 产生自 相同的 OpenAPI 规格 (`pnpm gen:sdk`),因此它不能从地表上漂出. un 调用 [`@cat-factory/sdk`](https://www.npmjs.com/package/@cat-factory/sdk) 和重新执行 它的行为.

这是猫因子数据的一半 **守门员** 一家人,三块取出两块不同的 方式:

| 块 | 这是什么 | 你怎么样 |
| --- | --- | --- |
| `@cat-factory/gatekeeper-bindings` (本套装) | 生成的操作表和范围助手 | 安装,以构建自己的政策层 |
| [`@cat-factory/gatekeeper-worker`](https://www.npmjs.com/package/@cat-factory/gatekeeper-worker) | 完整的守门员机械:Cap'n Web能力表面,关键经纪人,Webhook接收器,批准 | 安装, 只写一个策略 |
| [`deploy/gatekeeper`](https://github.com/kibertoad/cat-factory/tree/main/deploy/gatekeeper) | 部署模板: 策略文件、 硬盘绑定、 三行接线 | 复制和编辑 `src/policy.config.ts` |

## 宗旨和目标

用于建筑 **证书持有前端**: 持有猫因子 API 键的服务 自己和计数 他们自己的呼叫者可以做什么。 刺激消费者是 [Cloudflare 操作系统](https://github.com/cloudflare/cloudflare-os) 守门工人(设计记录: [设计记录](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/adr/0052-cloudflare-os-gatekeeper.md), (中文(简体) ), 但这里没有Cloudflare的特异性: 任何代理、机器人或治理层 猫因子键可以使用.

目标是这样一个层层对实际部署的行动执行政策 在它实际执行的仪表层里 绝对不会违反手动操作的清单. 地板来自Spec's `x-min-scope`,服务器从同一合同生成的 字段控制器执行,所以所宣布的范围和所执行的范围是一个值.

## 每一个束缚带

一个 `GatekeeperBinding` 百分比 `/api/v1` 操作 :

-   `name` (单位:千美元)`tasks_create`:政策拼写法,与MCP外形工具名完全相同.
-   `minScope`: 部署对路线执行的按键镜层(`read` 编号 : `write` 编号 : `decide` 编号 : `admin`),读取 spec's `x-min-scope`。这是STATIC层:一个运行启动 仍然可以拒绝操作 `pipeline_requires_decide_scope` 应请求指定时间 管道可以停在人身上.
-   `readOnly`, (中文(简体) ), `consequence`:前端需要决定哪个电话被挥动, 被记录, 需要人类. `consequence` 只在有利害关系的地方存在 真实的金钱或一个合并的拉取请求, 和MCP工具表一样, 所以读一遍 `resolveConsequence(binding)` 而不是直接:未经说明的突变是谨慎的 破坏性,和 `binding.consequence?.destructive` 会回答 `false` 对于它.
-   `result`问:如何 `invoke`答案会回来的`value`, SSE 数据 `stream`,或 `binary` 字节),所以 JSON-中继前端可以将非价值操作进行路由或扣留,说明是哪个.
-   `pathParams` 编号 : `queryParams` 编号 : `hasBody` 财务报告和审定财务报表 `invoke(client, args)`: 足以揭露 整个地表 动态地没有手写 包装器每个操作。 论点 常规是 MCP 外观( 最高层的路径参数和查询键, 下方的正体) `body`; 未知密钥被丢弃, 从未转发).

## 帮手们

手写在桌子旁`src/index.ts`),因为每个消费者都需要它们并产生 独立是怎样让他们倒行逆施的:

-   `scopeSatisfies(have, need)`:是否为范围的关键 `have` 清除地板 `need`编辑 阶梯是包容性的:每个跑步都能够做到它下面的一切.
-   `bindingsWithinScope(scope)`:每个操作都能够调用这个范围的关键.
-   `bindingByName(name)`政策拼写操作; `undefined` 用于命名表面 因此,一个拼错或退休的名字是呼叫者报告的条件,而不是一个 给人惊喜了.
-   `resolveConsequence(binding)`: 用谨慎的默认表示的后果(a) 未附加说明的突变算作有破坏性和无理想性.
-   `PUBLIC_API_SCOPE_LADDER`: 范围排名本身, 由 spec's 排放 `x-public-api-scopes`。 。 。 .
-   `renderSessionTypes(request)`页:1 `.d.ts` 一个对象能力会话作为其类型脚本 类型,由生成的 `SESSION_METHOD_SIGNATURES` 准确的操作a 政策授权。 因为一个命名整个地表的文件 承诺对象没有的方法。 它在它没有签名的名下发声: 滴入的方法读取一个特工 完全像一个操作 部署没有服务 两个需要相反的修复.

梯子帮手 **抛出他们不携带的瞄准镜** 而不是把它排到下面 `read`数字 : 在此软件包之前的一次发布必须读作版本 skew, 绝不是没有的密钥 权限.

## 怎样用

```ts
import { CatFactoryClient } from '@cat-factory/sdk'
import {
  bindingByName,
  bindingsWithinScope,
  resolveConsequence,
  scopeSatisfies,
} from '@cat-factory/gatekeeper-bindings'

const client = new CatFactoryClient({ baseUrl: process.env.BASE_URL!, apiKey: process.env.KEY! })

// Expose to this caller only what a `write` key can do, minus anything destructive. Read the
// consequence through the helper: most mutations carry no annotation, and the unannotated ones
// are the cautious case, not the safe one.
const exposed = bindingsWithinScope('write').filter((b) => !resolveConsequence(b).destructive)

// Forward a metered call.
const binding = bindingByName('tasks_create')!
if (!scopeSatisfies('write', binding.minScope)) throw new Error('caller tier too low')
const result = await binding.invoke(client, {
  serviceId: 'svc_123',
  body: { title: 'Fix the flaky login test', description: '...' },
})
```

由于两条路线没有诚实的操作形状,所以故意没有出现在桌子上: `GET /api/v1/openapi.json` (样本发现)和 `ALL /api/v1/mcp` (主机MCP端点). 两者 大门在 `read` 在服务器上.

## 产生的东西

两个文件,都由 `pnpm gen:sdk` 并严防漂泊 `pnpm check:sdk`数字 :

| 文件 | 它携带着什么 |
| --- | --- |
| `src/bindings.generated.ts` | 操作表:镜片平面,突变和传输元数据,后果提示,引用thunks. |
| `src/session-types.generated.ts` | 每个操作都有一个类型脚本方法签名,用于编组一个给定会话 `.d.ts`。 。 。 . |

签名带有完全打入的ArGUMENTS(路径参数,带有要求的查询密钥,a (a) 操作需要的机体)和 `unknown` 结果。 这是蓄意的,而不是一个差距: a 会话中继部署自己解码的 JSON, 这些形状的权威是 OpenAPI 文档在 `GET /api/v1/openapi.json`,每个部署服务。 内置模型 树会把第二个拷贝 放在每个消费者的包里 自由地不同意第一个.

## 配置和定制

此软件包中没有任何内容是配置或定制的:它是生成的数据加纯帮助器,以及 其上的政策属于消费者(参见: `@cat-factory/gatekeeper-worker` (单位:千美元) 现成一出. `src/bindings.generated.ts` 改为:`pnpm gen:sdk`; 更改路线 合同,从来没有文件.

## 参考资料

-   [`backend/docs/public-api.md`](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/public-api.md)数字 : 完整的 API 引用( 键、 瞄准镜、 端点语义).
-   [`sdk/README.md`](https://github.com/kibertoad/cat-factory/blob/main/sdk/README.md): 客户端 家族和世代的连锁 这桌骑.
-   [`@cat-factory/gatekeeper-worker`](https://www.npmjs.com/package/@cat-factory/gatekeeper-worker)数字 : 对照本表汇编部署政策的工人机制.
-   [ADR 0052 (英语)](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/adr/0052-cloudflare-os-gatekeeper.md)数字 : 设计记录,它被决定的替代品, 和陷阱的构造浮出水面.

## 常见问题

### @cat-factory/gatekeeper-bindings 是什么？

Cat-factory 公共 API \(/api/v1\) 的政策性附加操作表: per- operation speces, 突变和传输元数据, 并使用 thunks 超越 @ cat-factory/sdk, 生成自 SDKs 相同的 OpenAPI spec\. 为证书持有所建

### 如何安装 @cat-factory/gatekeeper-bindings？

在项目目录运行 npm install @cat-factory/gatekeeper-bindings，或使用 pnpm add / yarn add / bun add。

### @cat-factory/gatekeeper-bindings 支持 TypeScript 吗？

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

### @cat-factory/gatekeeper-bindings 支持 ESM 还是 CommonJS？

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

### @cat-factory/gatekeeper-bindings 需要什么版本的 Node\.js？

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

### @cat-factory/gatekeeper-bindings 可以商用吗？

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

### @cat-factory/gatekeeper-bindings 的下载量有多少？

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

### @cat-factory/gatekeeper-bindings 还在维护吗？

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