@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_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 插件
- 弹出您插件构建的每个信封
protocolVersion: 3(SDKs队) 导出被绑定的PROTOCOL_VERSION——取而代之为文字. - 返回时
classificationSignals: [](或真实信号事实) 发现处理器。 TS SDK 类型和 Pythonserve()指针 形状; 有线拒绝字段的缺失. - 可选择声明
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——故障类+formatDiagnosticpython/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 侧); 没有网络 任何一点.