> ## 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.

# 接入数据与服务

> 业务数据的读写放在 Mini App 的 Node 服务里，页面只调用 Node 提供的业务接口。

## 选择接入方式

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

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

## 先验证，再开发

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

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

## Host Connector

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

```json miniapp/miniapp.json theme={null}
{
  "hostConnectorAccess": { "providers": ["notion"] }
}
```

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

```javascript theme={null}
// 在请求处理里调用；工具名和参数以验证时观察到的清单和 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 事件，这样每个打开的页面都能刷新到最新数据。