---
title: "Path 插件"
description: "虚拟路径构造、规范化和安全检查。"
---


> 理解 Path 插件的虚拟路径规则、方法返回值和跨平台边界。

## 模块边界

Path 插件只构造和检查 `app://` 虚拟路径，不读取文件、不创建目录，也不把虚拟路径解析成
宿主真实路径。需要实际 I/O 时继续使用 `KSM.fs` 或 `KSM.sql`。

| 层级 | 入口 | 责任 |
| --- | --- | --- |
| 前端 API | `frontend/src/api/path.ts` | 参数守卫和命令封装 |
| 协议清单 | `protocol/plugins.json` | 七个命令归属 `path` |
| Windows 插件 | `windows/src/plugins/ksm_path_plugin.cpp` | 路径构造和校验 |
| Android 插件 | `KSMPathPlugin.kt` | 与 Windows 对齐的路径规则 |

## 方法

| 方法 | 参数 | 返回 |
| --- | --- | --- |
| `path.dirs` | `{}` | `{ data, cache, temp, resource, asset }` |
| `path.join` | `{ base, segments }` | `{ path }` |
| `path.normalize` | `{ path }` | `{ path }` |
| `path.dirname` | `{ path }` | `{ path }` |
| `path.basename` | `{ path, suffix? }` | `{ name }` |
| `path.extname` | `{ path }` | `{ extension }` |
| `path.isAbsolute` | `{ path }` | `{ absolute }` |

`path.isAbsolute` 判断的是合法 Kasumi 虚拟路径，不是宿主的真实绝对路径。`app://data`、
`app://cache`、`app://tmp`、`app://picked`、`app://res` 和 `app://assets` 是固定根。

## 路径规则

- 路径必须以受支持的 `app://` 根开头。
- 拒绝空字节、反斜杠、父目录穿越、当前目录段、`~` 和盘符样式片段。
- 拒绝额外斜杠、空路径段和不在固定根内的路径。
- `app://picked` 只表示用户选择文件句柄，不参与普通目录拼接。
- `path.join` 的每个片段必须是相对片段，不能以 `/` 开头。

## 示例

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

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

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 });
```

## 平台差异

| 项 | Windows | Android |
| --- | --- | --- |
| 七个命令 | 支持 | 支持 |
| 虚拟根集合 | 一致 | 一致 |
| 真实路径解析 | 不提供 | 不提供 |
| 执行位置 | 插件运行时 | 插件运行时 |

## 错误行为

| 错误码 | 场景 |
| --- | --- |
| `INVALID_ARGS` | 路径、片段或后缀不是字符串，路径越界或格式非法 |
| `NOT_SUPPORTED` | 当前宿主没有注册 `path` 插件 |
| `TIMEOUT` / `CANCELLED` | 请求被超时或取消链路终止 |

## 排查路径

1. 确认路径从 `KSM.path.dirs()` 返回的根开始。
2. 确认没有 `..`、反斜杠、`~`、空字节或盘符片段。
3. 确认 `path.join` 的片段是相对片段。
4. 需要文件存在性时调用 `KSM.fs.exists`，不要用 Path 插件推断。
5. 确认应用 allowlist 包含目标命令。