---
title: "Path API"
description: "TypeScript 虚拟路径 API。"
---


> 在 TypeScript 中构造和检查 Kasumi 虚拟路径。

## 模块边界

`KSM.path` 封装 Path 插件，只处理 `app://` 虚拟路径，不访问真实文件系统。文件读写仍由
`KSM.fs` 负责，数据库路径仍由 `KSM.sql` 负责。

实现入口是 `frontend/src/api/path.ts` 和 `frontend/src/api/guards.ts`。前端拒绝明显非法
参数，宿主插件继续执行最终路径校验。

## 平台支持

| 能力 | Windows | Android |
| --- | --- | --- |
| 七个 Path 命令 | 支持 | 支持 |
| 真实路径解析 | 不提供 | 不提供 |

## 方法

### `dirs()`

```ts
const roots = await KSM.path.dirs();
```

返回 `data`、`cache`、`temp`、`resource` 和 `asset` 五个虚拟根。

### `join({ base, segments })`

```ts
const path = await KSM.path.join({
  base: 'app://data',
  segments: ['notes', 'entry.json']
});
```

片段必须是相对片段，不能以 `/` 开头，也不能包含反斜杠、盘符、`~`、空字节或 `..`。

### `normalize({ path })`

```ts
const result = await KSM.path.normalize({ path: 'app://data/notes/' });
```

返回规范化后的虚拟路径，并移除末尾分隔符。

### 其他方法

```ts
const parent = await KSM.path.dirname({ path: file.path });
const name = await KSM.path.basename({
  path: file.path,
  suffix: '.json'
});
const extension = await KSM.path.extname({ path: file.path });
const absolute = await KSM.path.isAbsolute({ path: file.path });
```

`isAbsolute()` 表示路径是否是合法虚拟路径，不表示操作系统真实绝对路径。

## 参数守卫

- 所有路径参数必须是非空字符串且不超过 8192 字节。
- `segments` 必须是非空字符串数组。
- `suffix` 不超过 256 字节。
- 前端拒绝非法形状；宿主对越界路径返回 `INVALID_ARGS`。

## 错误行为

| 错误码 | 场景 |
| --- | --- |
| `INVALID_ARGS` | 路径、片段或后缀非法 |
| `NOT_SUPPORTED` | 宿主未注册 `path` 插件 |
| `TIMEOUT` / `CANCELLED` | 请求被超时或取消 |

## 相关

- [Path 插件规则](/docs/kasumi/plugins/path)
- [文件系统 API](/docs/kasumi/api/fs)
- [共享类型](/docs/kasumi/api/types)

## 排查路径

1. 确认路径从 `KSM.path.dirs()` 返回的根开始。
2. 确认没有父目录穿越和真实文件路径片段。
3. 需要文件存在性时调用 `KSM.fs.exists()`。
4. 确认 `capabilities.query` 返回目标 Path 命令。