接入数据与服务

选择接入方式

方式	适合	状态
Host Connector	用户已在 MiniMax Code 授权的第三方应用，比如 Notion	已发布
CLI 子进程	本机已有的命令行工具，由插件拉起、插件负责清理	已发布
HTTP API / SDK / 本地文件	有自己鉴权方式的服务，或用户授权的本地文件	已发布
统一工具入口	用同一个写法调用宿主已挂载的 MCP 工具和 Connector	即将发布

Connector 只是选择之一，不是 Mini App 的前提，没有对应的 Connector 也不代表数据拿不到。用户明确指定了方式并且能验证时，就用用户的；否则按可用能力、鉴权、运行环境和需要的操作来选。

先验证，再开发

写包之前，对每个数据源用选定的方式做一次只读查询，确认授权、真实参数、返回字段和类型，拿到一条有代表性的数据，或一个真实的空结果。解析逻辑按观察到的结构来写。

Agent 终端里查询成功，不代表 Mini App 运行时里也能成功。CLI、API、文件访问还要在 Node 服务里实际跑通一次。

Host Connector

Node 服务通过 context.hostConnector 使用用户已授权的连接器。访问第三方服务时，用的是用户授权给 MiniMax Code 的账号，Mini App 自己不保存任何凭证。

miniapp/miniapp.json

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

只声明运行时真正需要、并且已经验证过的 provider。
list() 随时可用，返回允许的工具清单和输入 schema。call() 只在服务激活后、在请求处理里调用，不要在 start 里调。
不要自己构造或保存 toolRef，也不要发给页面。进程重启或遇到过期引用时，重新 list()。
用户退出登录时，工具清单和授权引用会被撤销；同一账号重新登录后再 list() 即可恢复，不用重新发布。换成别的账号，旧引用就永久失效了。

// 在请求处理里调用；工具名和参数以验证时观察到的清单和 schema 为准
async function readRecords(context, args) {
  const { tools } = await context.hostConnector.list();
  const tool = tools.find((t) => t.provider === 'notion' && t.name === VERIFIED_TOOL_NAME);
  if (!tool) throw new Error('connector_tool_unavailable');
  const result = await context.hostConnector.call(tool.toolRef, args);
  return parseRecords(decodeHostConnectorValue(result.value));
}

错误处理

按 code 判断，不要依赖跨进程的 instanceof。

code	含义
`TOOL_REF_STALE` / `SERVICE_RESTARTED`	引用过期或服务重启了，重新 `list()`
`INVALID_ARGUMENTS`	参数不符合 schema；`diagnostic.issues` 给出 `path`、`constraint`、`limit`，不含参数值
`CONNECTOR_UNAVAILABLE`	连接器当前不可用
`CONNECTOR_TIMEOUT` / `REQUEST_CANCELLED`	超时或已取消
`CONNECTOR_PROVIDER_ERROR`	第三方服务报错。原因不明时不要推断成授权问题
`CONNECTOR_OUTCOME_UNKNOWN`	请求已发出，结果未知

disposition 说明请求有没有发出去：not_dispatched、provider_reported、unknown_after_dispatch。遇到 unknown_after_dispatch，先读业务状态核对，再决定写操作要不要重试。

解析返回值

result.value 是第三方服务的原始结果，宿主不做归一化。Skill 提供的 host-connector-value.mjs 处理常见的”单个 text 块”包装，其他结构原样返回。解析出零条数据时，只有服务明确返回了空结果才算成功；有源数据却解析不出来，要按解析错误处理，不要显示成”暂无数据”。

状态与持久化

运行时数据写在 context.dataDir，不要写进工作区或载荷。
页面、MCP 调用和 Agent 操作的所有写入都走同一个 Node 业务服务。先把状态落盘，再推 SSE 或 WebSocket 事件，这样每个打开的页面都能刷新到最新数据。

入门

了解 Mini App

开发

参考

选择接入方式

先验证，再开发

Host Connector

错误处理

解析返回值

状态与持久化

​选择接入方式

​先验证，再开发

​Host Connector

​错误处理

​解析返回值

​状态与持久化

选择接入方式

先验证，再开发

Host Connector

错误处理

解析返回值

状态与持久化