---
title: "类型"
description: "查阅 Kasumi 公共 TypeScript 类型、返回值形状和方法接口。"
---


> 查阅 Kasumi 公共 TypeScript 类型、返回值形状和方法接口。

## 模块边界

公共类型从 `@kasumi/bridge` 导出。业务代码应导入这些类型，不要复制协议字符串联合或
自定义同形接口，否则命令契约变更后会出现静默漂移。

## 基础联合

```ts
type KSMPlatform = 'windows' | 'android';

type KSMErrorCode =
  | 'INVALID_ARGS'
  | 'UNKNOWN_COMMAND'
  | 'PERMISSION_DENIED'
  | 'NOT_SUPPORTED'
  | 'NOT_FOUND'
  | 'IO_ERROR'
  | 'CANCELLED'
  | 'TIMEOUT'
  | 'BUSY'
  | 'INTERNAL_ERROR';
```

## 结果类型

|类型 |结构 |用途 |
| --- | --- | --- |
| `KSMFileHandle` | `{ file: string }` |大文本临时句柄 |
| `KSMAppInfo` | `{ name, version, platform, language }` |应用信息 |
| `KSMCapabilities` | `{ platform, commands, permissions }` |宿主能力 |

## API 接口

|接口 |方法 |
| --- | --- |
| `KSMFsApi` | `readText`、`writeText`、`exists`、`remove` |
| `KSMAppApi` | `getInfo`、`exit` |
| `KSMDialogApi` | `message`、`confirm`、`openFile`、`saveFile` |
| `KSMClipboardApi` | `readText`、`writeText` |
| `KSMNotificationApi` | `show` |
| `KSMPermissionApi` | `request` |
| `KSMWindowApi` | `setTitle`、`minimize`、`maximize`、`close` |
| `KSMTransport` | `send`、`onMessage` |

## 协议消息

```ts
interface KSMRequest<TArgs> {
  type: 'request';
  id: string;
  cmd: string;
  args: TArgs;
  timeoutMs?: number;
  windowId?: string;
}

interface KSMOkResponse<TResult> {
  type: 'response';
  id: string;
  ok: true;
  data: TResult;
}

interface KSMErrorResponse {
  type: 'response';
  id: string;
  ok: false;
  error: KSMError;
}

type KSMResponse<TResult> = KSMOkResponse<TResult> | KSMErrorResponse;

interface KSMEvent<TPayload = unknown> {
  type: 'event';
  event: string;
  payload: TPayload;
}

interface KSMFileHandle {
  file: string;
}
```

这些类型用于实现自定义传输或宿主适配器，业务页面通常只使用领域 API。

## 自定义传输

```ts
import type {
  KSMEvent,
  KSMResponse,
  KSMTransport
} from '@kasumi/bridge';

class LocalTransport implements KSMTransport {
  send(message: Parameters<KSMTransport['send']>[0]): void {
    console.info(message.type);
  }

  onMessage(
    listener: (message: KSMResponse<unknown> | KSMEvent) => void
  ): () => void {
    void listener;
    return () => {};
  }
}
```

## 类型边界

- TypeScript 类型不替代运行时校验；宿主仍会验证参数。
- `invoke<TResult>()` 的 `TResult` 是调用方断言，不是宿主保证。
- 能力缓存类型不表示命令在当前时刻一定可执行，权限仍可能失败。
- `KSMError` 是协议响应结构；Promise 拒绝时得到的是 `Error`，错误码位于 `name`。

## 相关

- [errors](/docs/kasumi/api/errors)
- [core/invoke](/docs/kasumi/api/core/invoke)