> ## Documentation Index > Fetch the complete documentation index at: https://agent.minimaxi.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Node API 参考 > start(context)、生命周期、日志、Host Connector 和统一工具入口的签名、参数与返回类型。 本页以 MiniMax Code v3.1.6 为基准，描述宿主传给 Node 入口的公开接口。运行时无需安装 SDK；`miniapp-api.ts` 只是 Skill 提供的类型快照。完整示例见 [Node 运行时](https://agent.minimaxi.com/docs/miniapp/authors/node-runtime.md)，Agent 方法见 [Agent API 参考](https://agent.minimaxi.com/docs/miniapp/reference/agent-api.md)。 ## start 与 dispose ```typescript theme={null} interface MiniAppLifecycle { dispose(): void | Promise; } interface MiniAppModule { start(context: MiniAppContext): Promise; } // 宿主接受同步返回值，也会等待 Promise。 declare function start(context: MiniAppContext): void | MiniAppLifecycle | Promise; ``` 入口必须导出命名函数 `start`。类型快照推荐 `async start(context): Promise`；运行时也接受同步返回 `undefined` 或包含 `dispose` 函数的对象。返回其他值会使启动失败。 * **参数**：`context` 由宿主创建，不能由插件构造或替换宿主客户端。 * **就绪**：先在 `context.listen` 上用 `node:http` 监听并安装路由，再完成 `start`。宿主还会检查端口鉴权；仅完成 `start` 不代表整个服务已就绪。 * **返回**：没有资源要清理时允许不返回值；有监听、子进程、定时器、订阅等资源时，应返回 `{ dispose }`。不要在 `start` 里发起 Agent 或工具业务调用，把它们放在激活后的请求处理里。 * **停止**：宿主先中止 `context.signal`，再等待 `dispose()`。同一次停止不会重复执行此清理函数；清理失败或进程不退出时，宿主仍会按回收流程处理。 启动和停止错误由生命周期操作报告，不是页面的 `Error.message` 错误码，见[运行时错误](https://agent.minimaxi.com/docs/miniapp/reference/errors.md#runtime)及[运行与更新](https://agent.minimaxi.com/docs/miniapp/host/lifecycle.md)。 ## 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 字段](https://agent.minimaxi.com/docs/miniapp/reference/manifest.md#permissions)。 `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 并发与取消限制](https://agent.minimaxi.com/docs/miniapp/reference/agent-api.md#limits)。 Node 发给宿主的每个请求，包括请求 ID、方法名和参数，序列化为 UTF-8 JSON 后不能超过 256 KiB。Connector 或工具调用超过此限制时，会在本地以 `INVALID_ARGUMENTS` 拒绝，`disposition: 'not_dispatched'`、`retryable: false`，且可能没有 `diagnostic`。缩小参数、分页或拆分后再重试。此请求大小限制与 8 MiB 的响应帧上限分别计算。 ## JSON 类型 Connector 和工具的参数、schema、结果使用以下 JSON 类型；不能传函数、`undefined` 或循环引用。 ```typescript theme={null} 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 ```typescript theme={null} 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 使用，通过用户已授权的第三方账号访问服务。声明示例： ```json miniapp/miniapp.json theme={null} { "hostConnectorAccess": { "providers": ["notion"] } } ``` ### list(options?) ```typescript theme={null} interface HostConnectorClient { list(options?: HostConnectorCallOptions): Promise; call( toolRef: HostConnectorToolRef, arguments_: JsonObject, options?: HostConnectorCallOptions, ): Promise; } 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?) ```typescript theme={null} 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` 字段当成宿主包装。完整处理示例见[接入数据](https://agent.minimaxi.com/docs/miniapp/authors/data.md#host-connector)，错误码见 [Host Connector 错误](https://agent.minimaxi.com/docs/miniapp/reference/errors.md#connector)。 ## tool 声明 `toolAccess: ["call"]` 后，Node 可以调用宿主已挂载的插件 MCP、用户 MCP、宿主内置 MCP 和用户连接的 Connector。Agent 内置的文件、Shell、浏览器工具不通过此接口提供。 ```typescript theme={null} type MiniAppToolPermission = 'allow' | 'ask' | 'deny'; interface MiniAppToolClient { list(options?: HostConnectorCallOptions): Promise; call( name: string, arguments_: JsonObject, options?: HostConnectorCallOptions, ): Promise; request( names: readonly string[], options?: HostConnectorCallOptions, ): Promise>; } ``` ### list(options?) ```typescript theme={null} 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?) ```typescript theme={null} 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`。请求名不合法时仍会失败。 * 页面也可请求授权，但没有列出和调用工具的方法，见[页面工具授权](https://agent.minimaxi.com/docs/miniapp/reference/client-api.md#tool-request)。Node 不受页面用户手势要求限制；宿主仍需能联系到用户，才能显示确认框。 `context.tool` 与 `context.hostConnector` 共用本进程的 Connector 清单。通过 `hostConnector` 重新列举可能使统一工具入口的旧 Connector 引用失效，`tool` 会重新列举一次；直接保存的 `hostConnector` 引用不会自动刷新。 ## Node 工具错误对象 Host Connector 和统一工具入口以以下错误对象拒绝请求，不要跨进程依赖 `instanceof`： ```typescript theme={null} 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 错误](https://agent.minimaxi.com/docs/miniapp/reference/errors.md#connector)和[工具错误](https://agent.minimaxi.com/docs/miniapp/reference/errors.md#tools)中。如果存在，`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 参考](https://agent.minimaxi.com/docs/miniapp/reference/agent-api.md)。Node 用 `options.signal` 取消；页面的 `cancel`、`open` 不属于 Node 接口。 ## capabilities ```typescript theme={null} interface MiniAppHostCapabilities { has(name: string): boolean; } ``` `has` 是同步探测。宿主能力表按版本固定，Node 和页面共用；返回 `true` 不表示 manifest 已声明、用户已授权，或该接口在 Node 端存在。旧宿主可能没有该对象。合法名称、适用端和声明条件见[能力表](https://agent.minimaxi.com/docs/miniapp/reference/client-api.md#capabilities)。