---
title: "invoke"
description: "使用协议命令名直接调用宿主，并执行已注册命令的本地参数校验。"
---


> 使用协议命令名直接调用宿主，并执行已注册命令的本地参数校验。

## 签名

```ts
KSM.invoke<TResult, TArgs>(
cmd: string,
args: TArgs
): Promise<TResult>
```

## 平台与权限

| Windows | Android |权限 |
| --- | --- | --- |
|支持 |支持 |由目标命令决定 |

## 参数

|参数 |类型 |必填 |说明 |
| --- | --- | --- | --- |
| `cmd` | `string` |是 | `protocol/commands.json` 中的协议命令名 |
| `args` | `TArgs` |是 |目标命令参数对象 |

命令名不带 `KSM` 前缀，例如 `fs.readText`，不是 `KSM.fs.readText`。

## 返回值

`Promise<TResult>`。`TResult` 由调用方指定，运行时不额外校验宿主返回结构。

## 行为

- 如果 `cmd` 是已注册命令，发送前会运行生成的参数校验器。
- 参数不符合契约时，本地抛出一个 `Error`，其 `name` 为 `INVALID_ARGS`。
- 未知命令名会继续发送给宿主，由宿主返回 `UNKNOWN_COMMAND`。
- 业务代码不应依赖内部生成的命令名称表来绕过领域封装。

## 示例

```ts
type Pong = { pong: true };

const result = await KSM.invoke<Pong, Record<string, never>>(
  'ping',
  {}
);
console.assert(result.pong === true);
```

优先使用类型更明确的领域 API：

```ts
await KSM.fs.readText({ path: 'app://data/config.json' });
```

## 错误

|错误 |场景 |
| --- | --- |
| `INVALID_ARGS` |已注册命令的参数不符合契约 |
| `UNKNOWN_COMMAND` |宿主未注册该命令 |
| `TIMEOUT` |请求超过默认 10 秒 |
|普通 `Error` |桥接未初始化、传输失败或桥接已销毁 |

## 相关

- [fs](/docs/kasumi/api/fs)
- [types](/docs/kasumi/api/types)
- [errors](/docs/kasumi/api/errors)