# @gate-forge/plugin-protocol 中文文档

规范地址：https://npmcn.com/package/%40gate-forge/plugin-protocol/

版本：0\.19\.2
npm 元数据更新时间：2026-11-10T03:55:21.068Z
中文译文更新时间：2026-11-15T23:52:07.060Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40gate-forge/plugin-protocol
原文对照：https://npmcn.com/package/%40gate-forge/plugin-protocol/?lang=original
项目主页：https://github.com/umiddey/gateforge#readme
源码仓库：https://github.com/umiddey/gateforge

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

- 包体积（解压后）：138 kB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-09-16T21:52:50.795Z
- 最新版本发布：2026-11-10T03:55:20.751Z
- 近 30 天下载量：3510（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 46 个）

## 中文简介

GPP/3子进程插件协议:TS主机库,TS插件SDK,zod有效载荷计划,Python参考客户端.

## 安装

```sh
npm install @gate-forge/plugin-protocol
```

也可以使用：`pnpm add @gate-forge/plugin-protocol`、`yarn add @gate-forge/plugin-protocol`、`bun add @gate-forge/plugin-protocol`

## README

# @gate-forge/plugin-protocol — GPP/3 (英语)

硬化的 Gateforge 插件协议( 第 3 版): 新线限制 JSON 在插件子进程的 stdin/ stdout 上架设,握起手来, 每封电文摘要、计划生成的有效载荷验证和故障关闭 每项违法行为的单一原因诊断(ADR0002, 第D3号决定).

直系: GPP/1 峰值(`spikes/plugin-protocol/spec.md`, (中文(简体) ), `host/host.py`, (中文(简体) ), `plugins/_lib.js`证明运输;GPP/2后加 `pluginVersion` 针入, 每个消息 `digest`,以及 Zod 生成的验证; GPP/3 (ADR 0003 D6) 添加强制性 `classificationSignals` 数组为每组 `result` 有效载荷 - 在文摘检查的信封里 没有 GPP/2 兼容路径: a GPP/2 同行在握手时失败关闭 `E_PROTOCOL_VERSION` 两个都命名 版本,任何发现运行之前.

## 信封 (pin # 5)

每个框架都是一行(`\n`\- 有限, UTF-8, 每行8个米B:

```json
{
  "protocolVersion": 3,
  "pluginId": "pack-sqlalchemy",
  "pluginVersion": "1.0.0",
  "type": "result",
  "seq": 2,
  "payload": { "…": "…" },
  "digest": "<64 lowercase hex chars>"
}
```

`digest = sha256(canonical({type, seq, payload}))` 超过GF-canonical-JSON (单位:千美元)`@gate-forge/core`是因为 `sha256Canonical`: UTF-8, 递归按键类型, 不 白色空间,整数平原。 握个手`hello`编号 :`ready`(指针) `protocolVersion`, (中文(简体) ), `pluginId`,以及 `pluginVersion`; 后面的每一个框架都是 与被钉住的身份核对. `seq` 是每个方向,1基, 严格顺序.

## 信件目录

| 类型 | 方向 | 有效载数 |
| --- | --- | --- |
| `hello` | 插件 + 主机 | `{capabilities: string[]}` (非空;主机需要) `"discover"`(中文(简体) ) |
| `ready` | 主机 — 插件 | `{}` |
| `discover` | 主机 — 插件 | `{requestId: string, paths: string[]}` (相对,否) `..`(中文(简体) ) |
| `result` | 插件 + 主机 | `{requestId, resources[], unresolved[], findings[], classificationSignals[]}` |
| `error` | 两者 | `{requestId?, code, message}` 与 `requestId`: 请求范围; 无: 会话- fatal |
| `shutdown` | 主机 — 插件 | `{}` |
| `bye` | 插件 + 主机 | `{}` ——然后插件退出 0 |

会话形状:一个产卵,一个握手,许多锁步发现(最多) 一个未决的请求, 一个关闭握手. `result.resources` 匹配 `@gate-forge/core`是因为 `ResourceSchema`· ; `result.unresolved` 匹配 `UnresolvedReasonSchema`· ; `findings` 为: `{code, detail, locations[]}` (例如:. `DUPLICATE_TABLE_NAME`(三); `result.classificationSignals` 匹配 `@gate-forge/core`是因为 `ClassificationSignalSchema` (ADR0003 D1) (韩语). 球场是 强制自版本起起撞 — 一个没有信号支持的检测器发送 `[]`,而其资源又回落到保守的分类默认. A 类 省略字段失败 `E_SCHEMA` (无未编辑的可选字段) 兼容性)。 有效载荷 Zod 计划 `src/schema.ts` 执行 接收时。 信号从不离开文摘检查的信封.

## 能力

`hello.capabilities` 是非空列表; 主机需要 `"discover"`。 。 。 . GPP/3 定义了一个插件May宣布的附加能力 :

-   `classification-signals` ——插件的发现处理器发出 分类-符号事实。 主机不需要; 能力 说明什么 `result` 有效载荷可能含有,但不可少.

## 失败代码

每一次违反都属于明显的错误类别(`src/codes.ts`),失败 闭会(扑克剂被杀死),使一种可操作的诊断—— 框架编号、消息类型、违法字段、预期 vs 获得——从未获得 堆栈堆放 :

```
[plugin-protocol] FAIL E_PROTOCOL_VERSION: frame 1: envelope protocolVersion=2 but the host speaks 3
[plugin-protocol] offending frame: {"protocolVersion":2,…}
```

| 代码 | 触发 |
| --- | --- |
| `E_PROTOCOL_VERSION` | 信封/手摇 `protocolVersion` QQ 3( GPP/2 端点在此失效, 在发现前) |
| `E_UNKNOWN_PLUGIN` | `pluginId`编号 :`pluginVersion` 与钉入式登记(GF-18)不同 |
| `E_FRAME_JSON` | 空行, 无效的 JSON, 非对象框, 或 8 MiB 盖上的行 |
| `E_UNKNOWN_TYPE` | 信封 `type` 不在目录中 |
| `E_SCHEMA` | 缺少/ 错误类型字段、 消化不匹配、 下行间隙、 相位错误、 相位错误 `requestId`缺少 `classificationSignals` |
| `E_EOF` | 插件流在预期框架( 已报出代码) 之前结束 |
| `E_TIMEOUT` | 监视预算内没有预期框架; 插件已杀( SIGKILLL) |
| `E_PLUGIN_ERROR` | 插件以一个 `error` 边框 |
| `E_EXIT_STATUS` | 插件在清理后退出了非零( 或挂起) `bye` |

## 正在移动 GPP/2 插件

1.  弹出您插件构建的每个信封 `protocolVersion: 3` (SDKs队) 导出被绑定的 `PROTOCOL_VERSION` ——取而代之为文字.
2.  返回时 `classificationSignals: []` (或真实信号事实) 发现处理器。 TS SDK 类型和 Python `serve()` 指针 形状; 有线拒绝字段的缺失.
3.  可选择声明 `classification-signals` 能力.

迁移前插件失败 `E_PROTOCOL_VERSION: envelope protocolVersion=2 but the host speaks 3` —— 说 确切的三角洲版本.

## 写入插件

### 类型脚本

```ts
import { servePlugin } from '@gate-forge/plugin-protocol';

await servePlugin(
  async (paths) => ({
    resources: scanForResources(paths),
    unresolved: [],
    findings: [],
    classificationSignals: emitSignals(paths), // [] when unsupported
  }),
  { pluginId: 'my-detector', pluginVersion: '1.0.0' },
);
```

`servePlugin` 进行握手,验证主机帧(digest, exts, 身份),答案 `discover` 通过您的处理器( 掷出会变成一个) 请求范围 `error` 并完成关闭握手。 我/欧是 可注射(`input`编号 :`output`用于测试.

### Python( 仅限Stdlib) Name

```python
from gateforge_plugin import serve

def discover(paths):
    return {"resources": scan(paths), "unresolved": [], "findings": [],
            "classificationSignals": signals(paths)}  # [] when unsupported

raise SystemExit(serve("my-detector", "1.0.0", discover))
```

`python/gateforge_plugin/__init__.py` 是客户端模块; 软件包 python 一方作为源(`python/`)——插件添加到 `sys.path` (见 `python/plugins/reference_detector.py`)或安装.

## 驱动插件( 引擎侧)

```ts
import { PluginSession } from '@gate-forge/plugin-protocol';

const session = new PluginSession({
  command: ['node', 'plugin.js', repoRoot],
  pluginId: 'my-detector',      // pinned at the handshake
  pluginVersion: '1.0.0',
  timeouts: { handshakeMs: 10_000, requestMs: 10_000, shutdownMs: 5_000 },
});
await session.start();
const outcome = await session.discover(['src/routes.py']); // repeatable, lock-step
await session.shutdown();                                   // bye + exit 0
```

监视器每读一次运行;任何失败都会杀死插件. `dispose()` 是一个 最好的杀不掉的。 对于测试, `maxLineBytes` 和所有三个 暂停是压倒一切的.

## 版式

-   `src/host.ts` ——引擎侧主机(`PluginSession`(中文(简体) )
-   `src/plugin.ts` — TypeScript 插件 SDK ()`servePlugin`(中文(简体) )
-   `src/schema.ts` - 信息目录+zod有效载荷计划
-   `src/framing.ts` ——行框,信封验证/建设(由双方分担)
-   `src/codes.ts` ——故障类+ `formatDiagnostic`
-   `python/gateforge_plugin/` —— Python 客户端(仅限Stdlib)
-   `python/plugins/reference_detector.py` - Python 参考探测器
-   `test/fixtures/` ——每插件一错一错装置为EQQ测试提供动力 (单位:千美元)`app/routes.gfx` 通用的微小固定格式; `plugin_gpp2_peer.mjs` 是用于证明失败闭合握手的剪接前对等点)
-   `test/host.test.ts` - GF-12 + GF-18 力学:每个 EQQ 代码 诊断性断言、绿色多发现会话、决定论
-   `test/cross-language.test.ts` —— TS 主机 x Python 插件接口 (字节相同的发现文件,包括信号)
-   `test/plugin-sdk.test.ts` - SDK信封/最正确

需要节点QQ( TS 侧), Python QQ 3. 12( Python 侧); 没有网络 任何一点.

## 常见问题

### @gate-forge/plugin-protocol 是什么？

GPP/3子进程插件协议:TS主机库,TS插件SDK,zod有效载荷计划,Python参考客户端\.

### 如何安装 @gate-forge/plugin-protocol？

在项目目录运行 npm install @gate-forge/plugin-protocol，或使用 pnpm add / yarn add / bun add。

### @gate-forge/plugin-protocol 支持 TypeScript 吗？

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

### @gate-forge/plugin-protocol 支持 ESM 还是 CommonJS？

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

### @gate-forge/plugin-protocol 需要什么版本的 Node\.js？

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

### @gate-forge/plugin-protocol 可以商用吗？

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

### @gate-forge/plugin-protocol 的下载量有多少？

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

### @gate-forge/plugin-protocol 还在维护吗？

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

