@landmark-plugin/runtime-node

Landmark 独立插件后端的官方 Node.js 进程与容器运行时。包内包含完整启动入口，不依赖或复制宿主源码；process 与 container 模式执行同一份 src/process-child.mjs。

普通插件业务代码不需要导入本包。宿主根据 plugin.json 自动启动它；自定义运行时、部署工具和诊断工具可以使用根入口公开的握手、环境和限制 API。

运行时职责

• 使用 IPC（本机 process）或 NDJSON 标准输入输出（container）连接宿主。
• 校验 API、RPC 协议、插件 ID 和服务端入口定义。
• 动态加载 defineServerPlugin() 入口并创建 PluginServerContext。
• 在 setup 完成前等待路由、服务、Hook、队列、任务、Socket、支付、认证和模型注册落地。
• 编码和解码 undefined、特殊数字、BigInt、Date、Buffer、Error、回调、Socket 和 AsyncIterable。
• 提供 RPC 请求超时、消息大小、嵌套深度、回调数量、流数量和回调并发限制。
• 传播请求上下文，等待请求内异步宿主回调完成。
• 支持插件回调、宿主回调、双向异步流和 Socket 命令。
• 支持迁移调用、优雅停止、AbortSignal、scope 清理、心跳和 fatal 事件。
• 将插件 console 输出重定向到 stderr，保证 stdout 只承载容器 RPC 协议。
• 过滤 __proto__、prototype 和 constructor，拒绝循环引用与过深载荷。

公开诊断 API

import {
    getRuntimeInfo,
    resolveRuntimeLimits,
    validateRuntimeHandshake,
} from "@landmark-plugin/runtime-node";

console.log(getRuntimeInfo());
const limits = resolveRuntimeLimits({ maxMessageBytes: 2 * 1024 * 1024 });
validateRuntimeHandshake({ pluginId: "example", apiVersion: 1, protocolVersion: 2 });

• assertRuntimeEnvironment()：要求 Node.js 20 或更高版本；正式宿主工具链统一使用 >=20.19.0。
• getRuntimeInfo()：返回运行时版本、Node、平台、架构、API、SDK 和协议元数据。
• resolveRuntimeLimits()：规范化消息、超时、回调、流和并发限制。
• validateRuntimeHandshake()：校验并冻结握手数据。
• PLUGIN_RUNTIME_PROTOCOL：当前协议标识 landmark-plugin-rpc/2。
• PLUGIN_RUNTIME_VERSION：当前运行时实现版本；宿主会在 bootstrap 与 start 两次握手中精确校验该值。

@landmark-plugin/runtime-node/process-child 是宿主使用的副作用启动入口，不应在插件业务代码中导入。

宿主把本包声明为运行时依赖，并通过该公开子路径解析进程入口。开发包和生产包只使用包内公开入口，不复制 monorepo 源码启动文件。

容器镜像

从仓库根目录构建：

pnpm plugin:runtime:build
pnpm plugin:runtime:smoke

plugin:runtime:smoke 会让真实宿主通过该镜像启动临时插件，验证版本握手、宿主路由与服务能力调用、HTTP 响应桥接以及容器卸载清理。执行前必须启动 Docker Engine。

镜像以非 root 的 node 用户运行，只包含 contracts、SDK 和 runtime-node。插件目录由宿主只读挂载到 /plugin；宿主源码和宿主 node_modules 不会挂载进容器。

容器入口：

@landmark-plugin/runtime-node/process-child

环境限制

• LMK_PLUGIN_RPC_MAX_BYTES
• LMK_PLUGIN_RPC_TIMEOUT_MS
• LMK_PLUGIN_CALLBACK_LIMIT
• LMK_PLUGIN_STREAM_LIMIT
• LMK_PLUGIN_CALLBACK_CONCURRENCY

所有值都会被限制在安全区间，不能通过环境变量关闭边界保护。