@gate-forge/plugin-protocol

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

GPP/3 subprocess plugin protocol: TS host library, TS plugin SDK, zod payload schemas, Python reference client.

原始使用文档
文档目录10 节
  1. Envelope (pin #5)
  2. Message catalog
  3. Capabilities
  4. Failure codes
  5. Migrating a GPP/2 plugin
  6. Writing a plugin
  7. TypeScript
  8. Python (stdlib only)
  9. Driving plugins (engine side)
  10. Layout

@gate-forge/plugin-protocol — GPP/3

The hardened Gateforge Plugin Protocol (version 3): newline-delimited JSON framing over a plugin subprocess's stdin/stdout, with a pinned handshake, per-message digests, schema-generated payload validation, and fail-closed single-cause diagnostics on every violation (ADR 0002, decision D3).

Lineage: GPP/1 spike (spikes/plugin-protocol/spec.md, host/host.py, plugins/_lib.js) proved the transport; GPP/2 added pluginVersion pinning, the per-message digest, and zod-generated validation; GPP/3 (ADR 0003 D6) adds the mandatory classificationSignals array to every result payload — inside the digest-checked envelope. There is no GPP/2 compatibility path: a GPP/2 peer fails closed at the handshake with E_PROTOCOL_VERSION naming both versions, before any discovery runs.

Envelope (pin #5)

Every frame is one line (\n-delimited, UTF-8, 8 MiB cap per line):

{
  "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})) over GF-canonical-JSON (@gate-forge/core's sha256Canonical): UTF-8, recursively key-sorted, no whitespace, integers plain. The handshake (hello/ready) pins protocolVersion, pluginId, and pluginVersion; every later frame is checked against the pinned identity. seq is per-direction, 1-based, strictly sequential.

Message catalog

typedirectionpayload
helloplugin → host{capabilities: string[]} (non-empty; host requires "discover")
readyhost → plugin{}
discoverhost → plugin{requestId: string, paths: string[]} (repo-relative, no ..)
resultplugin → host{requestId, resources[], unresolved[], findings[], classificationSignals[]}
errorboth{requestId?, code, message} — with requestId: request-scoped; without: session-fatal
shutdownhost → plugin{}
byeplugin → host{} — then the plugin exits 0

Session shape: one spawn, one handshake, many lock-step discovers (at most one outstanding request), one shutdown handshake. result.resources matches @gate-forge/core's ResourceSchema; result.unresolved matches UnresolvedReasonSchema; findings are {code, detail, locations[]} (e.g. DUPLICATE_TABLE_NAME); result.classificationSignals matches @gate-forge/core's ClassificationSignalSchema (ADR 0003 D1). The field is mandatory since the version bump — a detector without signal support sends [], and its resources fall back to conservative classification defaults. A result omitting the field fails E_SCHEMA (no unversioned optional-field compatibility). Payload zod schemas live in src/schema.ts and are enforced on receive. Signals never travel outside the digest-checked envelope.

Capabilities

hello.capabilities is a non-empty list; the host requires "discover". GPP/3 defines one additional capability a plugin MAY declare:

  • classification-signals — the plugin's discovery handler emits classification-signal facts. The host does NOT require it; the capability states what the result payload may contain, never less.

Failure codes

Every violation is a distinct error class (src/codes.ts), fails the session closed (plugin killed), and renders one actionable diagnostic — frame number, message type, offending field, expected vs got — never a stack dump:

[plugin-protocol] FAIL E_PROTOCOL_VERSION: frame 1: envelope protocolVersion=2 but the host speaks 3
[plugin-protocol] offending frame: {"protocolVersion":2,…}
codetrigger
E_PROTOCOL_VERSIONenvelope/handshake protocolVersion ≠ 3 (a GPP/2 peer fails here, before discovery)
E_UNKNOWN_PLUGINpluginId/pluginVersion differs from the pinned registration (GF-18)
E_FRAME_JSONempty line, invalid JSON, non-object frame, or line over the 8 MiB cap
E_UNKNOWN_TYPEenvelope type not in the catalog
E_SCHEMAmissing/mistyped field, digest mismatch, seq gap, wrong phase, wrong requestId, missing classificationSignals
E_EOFplugin stream ended before the expected frame (exit code reported)
E_TIMEOUTno expected frame within the watchdog budget; plugin killed (SIGKILL)
E_PLUGIN_ERRORplugin answered a request (or the session) with an error frame
E_EXIT_STATUSplugin exited nonzero (or hung) after a clean bye

Migrating a GPP/2 plugin

  1. Bump every envelope your plugin builds to protocolVersion: 3 (the SDKs export the pinned PROTOCOL_VERSION — use it instead of literals).
  2. Return classificationSignals: [] (or real signal facts) from your discover handler. The TS SDK type and the Python serve() docstring pin the shape; the wire rejects the field's absence.
  3. Optionally declare the classification-signals capability.

A pre-migration plugin fails with E_PROTOCOL_VERSION: envelope protocolVersion=2 but the host speaks 3 — the expected-versus-received diagnostic names the exact version delta.

Writing a plugin

TypeScript

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 performs the handshake, validates host frames (digest, seq, identity), answers discover through your handler (a throw becomes a request-scoped error frame), and completes the shutdown handshake. I/O is injectable (input/output) for tests.

Python (stdlib only)

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 is the client module; the package ships the Python side as source (python/) — plugins add it to sys.path (see python/plugins/reference_detector.py) or install it.

Driving plugins (engine side)

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

Watchdogs run per read; any failure kills the plugin. dispose() is a best-effort kill that never throws. For tests, maxLineBytes and all three timeouts are overridable.

Layout

  • src/host.ts — engine-side host (PluginSession)
  • src/plugin.ts — TypeScript plugin SDK (servePlugin)
  • src/schema.ts — message catalog + zod payload schemas
  • src/framing.ts — line framing, envelope verify/build (shared by both sides)
  • src/codes.ts — failure classes + formatDiagnostic
  • python/gateforge_plugin/ — Python client (stdlib only)
  • python/plugins/reference_detector.py — Python reference detector
  • test/fixtures/ — one-fault-per-plugin fixtures powering the E_* tests (app/routes.gfx is the shared trivial fixture format; plugin_gpp2_peer.mjs is the pre-cutover peer used to prove the fail-closed handshake)
  • test/host.test.ts — GF-12 + GF-18 mechanics: every E_* code with diagnostic assertions, green multi-discover session, determinism
  • test/cross-language.test.ts — TS host x Python plugin interop (byte-identical discovery documents incl. signals)
  • test/plugin-sdk.test.ts — SDK envelope/digest correctness

Requires Node >= 20 (TS side), Python >= 3.12 (Python side); no network at any point.

版本与发布记录

@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 subprocess plugin protocol: TS host library, TS plugin SDK, zod payload schemas, Python reference client.

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