@gate-forge/plugin-protocol

中文文档
0.19.2发布于 2026/11/10Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 3510

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

中文使用文档
文档目录10 节
  1. 信封 (pin # 5)
  2. 信件目录
  3. 能力
  4. 失败代码
  5. 正在移动 GPP/2 插件
  6. 写入插件
  7. 类型脚本
  8. Python( 仅限Stdlib) Name
  9. 驱动插件( 引擎侧)
  10. 版式

@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:

{
  "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_PLUGINpluginId编号 :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 —— 说 确切的三角洲版本.

写入插件

类型脚本

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

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)或安装.

驱动插件( 引擎侧)

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 共发布 46 个版本,首次发布于 2026/09/17;过去 12 个月发布了 46 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.19.2latest2026/11/105 天前
0.19.12026/11/106 天前
0.19.02026/10/2917 天前
0.18.32026/10/2522 天前
0.18.22026/10/2125 天前
0.18.12026/10/2125 天前

关于 @gate-forge/plugin-protocol 的常见问题

@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 和提交记录判断。