Node API 参考

本页以 MiniMax Code v3.1.6 为基准，描述宿主传给 Node 入口的公开接口。运行时无需安装 SDK；miniapp-api.ts 只是 Skill 提供的类型快照。完整示例见 Node 运行时，Agent 方法见 Agent API 参考。

start 与 dispose

interface MiniAppLifecycle {
  dispose(): void | Promise<void>;
}

interface MiniAppModule {
  start(context: MiniAppContext): Promise<void | MiniAppLifecycle>;
}

// 宿主接受同步返回值，也会等待 Promise。
declare function start(context: MiniAppContext):
  void | MiniAppLifecycle | Promise<void | MiniAppLifecycle>;

入口必须导出命名函数 start。类型快照推荐 async start(context): Promise<void | MiniAppLifecycle>；运行时也接受同步返回 undefined 或包含 dispose 函数的对象。返回其他值会使启动失败。

参数：context 由宿主创建，不能由插件构造或替换宿主客户端。
就绪：先在 context.listen 上用 node:http 监听并安装路由，再完成 start。宿主还会检查端口鉴权；仅完成 start 不代表整个服务已就绪。
返回：没有资源要清理时允许不返回值；有监听、子进程、定时器、订阅等资源时，应返回 { dispose }。不要在 start 里发起 Agent 或工具业务调用，把它们放在激活后的请求处理里。
停止：宿主先中止 context.signal，再等待 dispose()。同一次停止不会重复执行此清理函数；清理失败或进程不退出时，宿主仍会按回收流程处理。

启动和停止错误由生命周期操作报告，不是页面的 Error.message 错误码，见运行时错误及运行与更新。

MiniAppContext

以下字段由宿主提供，不要修改。

字段	类型	含义与可用条件
`pluginId`	`string`	已接纳的插件 ID
`pluginRoot`	`string`	本次运行副本的目录，不是工作区或安装目录
`dataDir`	`string`	按插件隔离的持久化目录；业务状态写在这里
`listen`	`{ host: '127.0.0.1', port: number }`	分配的监听地址；不要自己选端口
`signal`	`AbortSignal`	本次入口的取消信号；停止或启动失败时中止，不会自动关闭插件自己的资源
`logger`	`MiniAppLogger`	下文的四级日志接口
`hostConnector?`	`HostConnectorClient`	`hostConnectorAccess.providers` 至少声明一个 provider 时注入
`tool?`	`MiniAppToolClient`	声明 `toolAccess: ["call"]` 时注入
`agent?`	`MiniAppAgentClient`	`agentAccess` 包含 `session.run` 或 `session.read` 时注入
`capabilities?`	`{ has(name: string): boolean }`	当前宿主的接口能力探测；旧宿主可能没有该对象

hostConnector、tool、agent 的注入取决于 manifest。用户关闭相应权限后，对象仍存在，但新调用会被拒绝或受到下文所述限制；对象存在不表示调用已获准。声明方式见 miniapp.json 字段。context.signal 与单次调用的 options.signal 不是同一个参数：前者表示运行生命周期，后者由调用方传入，用于取消特定请求。需要时可将生命周期信号传给请求选项。

请求预算

每个 Node 进程最多有 16 个普通在途请求，Connector 的 list / call、工具的 list / call / request，以及 Agent 的 run / answer / models / agents / create / sessions / session 共用这些名额。达到预算时，新请求会在派发前被拒绝。Agent reply 另有 16 个名额，observe 另有 4 个名额，因此普通请求占满时仍可回答审批。这些进程通信预算与 agentConcurrency 的回合名额分别计算，详见 Agent 并发与取消限制。Node 发给宿主的每个请求，包括请求 ID、方法名和参数，序列化为 UTF-8 JSON 后不能超过 256 KiB。Connector 或工具调用超过此限制时，会在本地以 INVALID_ARGUMENTS 拒绝，disposition: 'not_dispatched'、retryable: false，且可能没有 diagnostic。缩小参数、分页或拆分后再重试。此请求大小限制与 8 MiB 的响应帧上限分别计算。

JSON 类型

Connector 和工具的参数、schema、结果使用以下 JSON 类型；不能传函数、undefined 或循环引用。

type JsonPrimitive = null | boolean | number | string;
type JsonObject = { readonly [key: string]: JsonValue };
type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];

declare const HOST_CONNECTOR_TOOL_REF: unique symbol;
type HostConnectorToolRef = string & {
  readonly [HOST_CONNECTOR_TOOL_REF]: 'HostConnectorToolRef';
};

interface HostConnectorCallOptions {
  readonly signal?: AbortSignal;
}

logger

interface MiniAppLogger {
  debug(message: string, fields?: JsonObject): void;
  info(message: string, fields?: JsonObject): void;
  warn(message: string, fields?: JsonObject): void;
  error(message: string, fields?: JsonObject): void;
}

四个方法的参数和返回值相同，区别仅在日志级别。message 应是稳定的事件名称或不含业务内容的诊断文字；fields 可省略。v3.1.6 会将 message 截到前 4096 个 UTF-16 码元，只向宿主传递 fields 的键名，不保留字段值。这些日志只作有限的诊断记录，不能保证完整保留，也不能作为完整的结构化业务日志存储。不要写入凭据、原始输入或用户数据。

hostConnector

此接口仅供 Node 使用，通过用户已授权的第三方账号访问服务。声明示例：

miniapp/miniapp.json

{
  "hostConnectorAccess": { "providers": ["notion"] }
}

list(options?)

interface HostConnectorClient {
  list(options?: HostConnectorCallOptions): Promise<HostConnectorListResult>;
  call(
    toolRef: HostConnectorToolRef,
    arguments_: JsonObject,
    options?: HostConnectorCallOptions,
  ): Promise<HostConnectorCallResult>;
}

interface HostConnectorListResult {
  readonly tools: readonly HostConnectorTool[];
  readonly partial: boolean;
}

interface HostConnectorTool {
  readonly toolRef: HostConnectorToolRef;
  readonly provider: string;
  readonly name: string;
  readonly description?: string;
  readonly inputSchema: JsonValue;
  readonly outputSchema?: JsonValue;
}

参数或返回项	说明
`options.signal`	可选；中止本次列举
`tools`	当前用户、插件声明及开关允许列出的工具；按 `provider`、`name` 和实际 schema 选择
`partial`	清单不完整；已列出的结果仍可使用，但不代表全部工具
`toolRef`	宿主签发的不透明引用，类型为带标记的字符串；只能从清单取得
`inputSchema` / `outputSchema?`	服务提供的 JSON schema，不代表统一业务数据结构

list() 在激活前后都可用，不执行业务工具。引用绑定当前运行和账号；重新列举会替换本进程的 Connector 清单。不要自行构造、持久化或把 toolRef 传给页面；启动后、引用失效或账号变化后重新列举。

call(toolRef, arguments_, options?)

interface HostConnectorCallResult {
  readonly invocationId: string;
  readonly value: JsonValue;
}

参数或返回项	说明
`toolRef`	从最近一次 `list()` 取得的引用
`arguments_`	符合该工具 `inputSchema` 的 JSON 对象
`options.signal`	可选；取消等待和请求；取消不能证明外部写操作没有执行
`invocationId`	宿主为此次调用分配的标识
`value`	原始 provider JSON 结果，可能是对象、数组、字符串或其他 JSON 值，宿主不归一化

只在服务激活后的请求处理里调用，不能在 start 中调用。成功时 Promise 正常返回；provider 报告错误时，以 CONNECTOR_PROVIDER_ERROR 拒绝请求。请求默认限时 30 秒。取消、超时或连接丢失后，应按错误中的 disposition 判断是否可能已执行。关闭某个 provider 权限后，它不出现在新清单中，调用其引用返回 CONNECTOR_NOT_PERMITTED。退出登录会撤销工具清单和引用；同一账号重新登录后重新 list()，换账号后旧引用不可继续使用。解析 value 前先验证真实返回结构，不要把任意 content、text、value 字段当成宿主包装。完整处理示例见接入数据，错误码见 Host Connector 错误。

tool

声明 toolAccess: ["call"] 后，Node 可以调用宿主已挂载的插件 MCP、用户 MCP、宿主内置 MCP 和用户连接的 Connector。Agent 内置的文件、Shell、浏览器工具不通过此接口提供。

type MiniAppToolPermission = 'allow' | 'ask' | 'deny';

interface MiniAppToolClient {
  list(options?: HostConnectorCallOptions): Promise<MiniAppToolListResult>;
  call(
    name: string,
    arguments_: JsonObject,
    options?: HostConnectorCallOptions,
  ): Promise<MiniAppToolCallResult>;
  request(
    names: readonly string[],
    options?: HostConnectorCallOptions,
  ): Promise<Record<string, MiniAppToolPermission>>;
}

list(options?)

type MiniAppTool = {
  readonly name: string;
  readonly tool: string;
  readonly description?: string;
  readonly inputSchema: JsonValue;
  readonly permission: MiniAppToolPermission;
} & (
  | { readonly kind: 'connector'; readonly provider: string }
  | { readonly kind: 'mcp'; readonly server: string }
);

interface MiniAppToolListResult {
  readonly tools: readonly MiniAppTool[];
  readonly partial: boolean;
}

options.signal 可取消此次列举；list() 在激活前也可用。
name 是运行时调用名；tool 是 provider 或 MCP 服务器里的工具名。用 kind、server / provider、tool 匹配，从清单读取 name，不要拼接它。
permission 是列举时的权限快照。每次 call 都会重新判定，不能凭先前的 allow 跳过权限检查。
partial: true 表示清单不完整，可能有来源不可用或工具因元数据问题被省略；已列出的工具仍按当前权限调用。所有来源均失败时，列举可能拒绝。
用户关闭 tool:call 时仍可列举，但每项 permission 都为 deny。

call(name, arguments_, options?)

type MiniAppToolCallResult =
  | {
      readonly invocationId: string;
      readonly kind: 'connector';
      readonly value: JsonValue;
    }
  | {
      readonly invocationId: string;
      readonly kind: 'mcp';
      readonly isError: boolean;
      readonly content: readonly JsonValue[];
      readonly structuredContent?: JsonObject;
    };

参数或返回项	说明
`name`	最近列举到的运行时名称；未知名称应重新列举后核对
`arguments_`	符合工具 schema 的 JSON 对象
`options.signal`	可选；取消本次调用，不保证已经发出的外部操作被撤销
`kind: 'connector'`	`value` 为 provider 的原始 JSON 结果
`kind: 'mcp'`	`content` 保留 MCP 内容块；`structuredContent` 是可选的结构化结果
`isError`	MCP 工具报告业务失败；即使为 `true`，本次 Promise 仍 resolve，需要调用方检查
`invocationId`	本次调用标识；供诊断关联使用

只在激活后的请求处理里调用。不要通过此接口绕回本 Mini App 自己的托管 MCP 端点，直接复用本地业务函数。每次调用按用户的全局工具规则和全局权限模式判定，不继承某个 Agent 或会话的规则。deny 拒绝，ask 由宿主显示允许一次／始终允许／拒绝的确认框；只有用户在宿主选择始终允许才写全局规则。宿主内置工具沿用宿主原有放行行为。Agent 的工具 Hook 不在这条调用链运行。无人可以确认时返回 TOOL_APPROVAL_REQUIRED；审批最多等待 5 分钟。审批结束后的 Connector 调用默认最多 30 秒，MCP 调用最多 120 秒，也可能先达到 MCP 服务器自身的时限。返回结果必须放进一个 8 MiB 帧；超过限制会以 TOOL_RESULT_TOO_LARGE 拒绝，即使工具已经执行。关闭工具权限后，新的 call 被拒绝；已发出的调用可以继续完成。宿主不自动重试已派发的业务操作；Connector 引用在派发前失效时，会重新列举并尝试一次。对于超时、取消和未知结果，先检查下文的 disposition，不要仅根据错误名决定是否重复写操作。

request(names, options?)

names 必须是 1–10 个不同的运行时名称，从 list() 取得；options.signal 可取消请求。此方法提前询问需要用户确认的工具，不调用工具本身。

宿主只询问仍为 ask 的工具，已经是 allow 或 deny 的工具不会再次询问。用户勾选后可将对应工具设为全局始终允许。
resolve 的对象包含每个请求名称当前的 allow、ask 或 deny；它只是用于界面显示的权限快照，后续调用仍重新判定。
无人可以确认时，Node 以 TOOL_APPROVAL_REQUIRED 拒绝请求，错误另带 permissions 属性，保存未变更的权限映射。
tool:call 关闭时不弹框，直接返回所有名称为 deny。请求名不合法时仍会失败。
页面也可请求授权，但没有列出和调用工具的方法，见页面工具授权。Node 不受页面用户手势要求限制；宿主仍需能联系到用户，才能显示确认框。

context.tool 与 context.hostConnector 共用本进程的 Connector 清单。通过 hostConnector 重新列举可能使统一工具入口的旧 Connector 引用失效，tool 会重新列举一次；直接保存的 hostConnector 引用不会自动刷新。

Node 工具错误对象

Host Connector 和统一工具入口以以下错误对象拒绝请求，不要跨进程依赖 instanceof：

interface HostConnectorError extends Error {
  readonly code: string;
  readonly disposition:
    | 'not_dispatched'
    | 'provider_reported'
    | 'unknown_after_dispatch';
  readonly retryable: boolean;
  readonly invocationId?: string;
  readonly diagnostic?: {
    readonly issues: readonly {
      readonly path: string;
      readonly constraint: string;
      readonly limit?: number;
    }[];
  };
}

这里用 string 展示 code 的读取方式；已知码值分别列在 Connector 错误和工具错误中。如果存在，diagnostic.issues 会描述 schema 校验问题，不包含被拒绝的参数值；本地输入或请求大小校验也可能返回 INVALID_ARGUMENTS，且不带这个字段。request() 的 TOOL_APPROVAL_REQUIRED 还可携带 permissions 映射。

字段	处理方式
`disposition: 'not_dispatched'`	没有发给工具；修复原因后，仅在 `retryable` 为真时按原请求重试
`disposition: 'provider_reported'`	provider 明确报告失败；按业务错误处理，不能推断写操作必定没有副作用
`disposition: 'unknown_after_dispatch'`	工具可能已执行；先读取业务状态，不能盲目重试写操作
`retryable`	宿主是否认为原请求可稍后重试；不能替代 `disposition`

agent

context.agent 的运行、审批、问卷、模型、会话读取和观察接口见 Agent API 参考。Node 用 options.signal 取消；页面的 cancel、open 不属于 Node 接口。

capabilities

interface MiniAppHostCapabilities {
  has(name: string): boolean;
}

has 是同步探测。宿主能力表按版本固定，Node 和页面共用；返回 true 不表示 manifest 已声明、用户已授权，或该接口在 Node 端存在。旧宿主可能没有该对象。合法名称、适用端和声明条件见能力表。

入门

了解 Mini App

开发

参考

start 与 dispose

MiniAppContext

请求预算

JSON 类型

logger

hostConnector

list(options?)

call(toolRef, arguments_, options?)

tool

list(options?)

call(name, arguments_, options?)

request(names, options?)

Node 工具错误对象

agent

capabilities

​start 与 dispose

​MiniAppContext

​请求预算

​JSON 类型

​logger

​hostConnector

​list(options?)

​call(toolRef, arguments_, options?)

​tool

​list(options?)

​call(name, arguments_, options?)

​request(names, options?)

​Node 工具错误对象

​agent

​capabilities

start 与 dispose

MiniAppContext

请求预算

JSON 类型

logger

hostConnector

list(options?)

call(toolRef, arguments_, options?)

tool

list(options?)

call(name, arguments_, options?)

request(names, options?)

Node 工具错误对象

agent

capabilities