api
按错误码定位 Kasumi 参数、权限、平台支持、生命周期和 IO 问题。
按错误码定位 Kasumi 参数、权限、平台支持、生命周期和 IO 问题。
错误码全集来自 protocol/errors.json。宿主通过标准错误响应返回错误码；前端总线把
响应转换成普通 Error，并把错误码写入 error.name。
interface KSMError {
code: KSMErrorCode;
message: string;
detail?: unknown;
}Promise 拒绝时不会返回上述对象，而是普通 Error：
try {
await KSM.fs.readText({ path: 'app://data/config.json' });
} catch (error) {
if (error instanceof Error) {
console.info(error.name, error.message);
}
}如果响应带 detail，前端会把它附加到 Error 对象上。
error.name | 含义 | 优先检查 |
|---|---|---|
INVALID_ARGS | 参数不符合命令契约 | 参数名、类型、未知字段、权限名、事件名 |
UNKNOWN_COMMAND | 命令未注册 | 协议版本和 capabilities.commands |
PERMISSION_DENIED | 权限或路径边界拒绝 | 权限请求、只读根、picked 句柄 |
NOT_SUPPORTED | 当前平台或宿主不支持 | 能力列表、平台服务配置 |
NOT_FOUND | 资源不存在 | 路径、文件是否已删除 |
IO_ERROR | IO 或大小限制失败 | 16 MiB 限制、文件权限、临时文件写入 |
CANCELLED | 宿主主动取消请求 | 路由中断或宿主取消响应 |
TIMEOUT | 请求超时 | 10 秒默认超时、宿主线程或协程阻塞 |
BUSY | 并发或资源忙 | 并发上限、重复打开对话框 |
INTERNAL_ERROR | 宿主未预期异常 | 宿主日志和命令实现 |
以下路径只抛普通错误或返回空结果，不应按 Kasumi 错误码处理：
| 场景 | 表现 |
|---|---|
| 前端路径守卫拒绝 | TypeError |
| 标题、正文或文本类型错误 | 文案不固定的 TypeError |
| 桥接未初始化 | Error，文案为 KSM must be initialized before use. |
| 桥接销毁时有未完成请求 | 普通 Error |
| 剪贴板读取失败 | { text: '' } |
文件不存在时调用 exists | { exists: false } |
| 文件删除失败或不存在 | { removed: false } |
| 对话框取消 | { confirmed: false }或 { file: null } |
async function readConfig(): Promise<string | null> {
try {
return await KSM.fs.readText({
path: 'app://data/config.json'
}) as string;
} catch (error) {
if (!(error instanceof Error)) {
throw error;
}
if (error.name === 'NOT_FOUND') {
return null;
}
throw error;
}
}只对已确认幂等的读取操作考虑重试。写入、删除、退出等非幂等操作不得自动重试。
Android 对话框和运行时权限的宿主内部等待上限是 60 秒，但前端请求默认 10 秒超时。
因此长于 10 秒的用户操作通常先得到 TIMEOUT，不会等到底层返回 false。
TypeError、普通 Error 和带错误码的桥接错误。capabilities.commands 与 capabilities.permissions。..、~、反斜杠和只读根。TIMEOUT 检查宿主执行线程是否被系统对话框或阻塞 IO 占住。BUSY 检查并发命令数和是否有未完成的文件选择器。
评论