plugins
Shell
查看 MarkdownKasumi 外部链接插件的方法、origin 白名单与平台差异。
理解 Shell 插件的外部链接白名单、URL 校验、平台调用和信任边界。
Shell 插件只把已授权的绝对 HTTP(S) URL 交给系统浏览器。它不下载内容、不返回浏览器页面、
不处理浏览器后续重定向，也不允许 javascript:、file:、data:、intent: 或
content:// 交给系统。
| 层级 | 入口 | 责任 |
|---|---|---|
| 前端 API | frontend/src/api/shell.ts | URL 形状守卫 |
| 协议清单 | protocol/plugins.json | shell 插件和命令归属 |
| Windows 服务 | ksm_windows_host_services.cpp | 精确 origin 白名单和 ShellExecuteW |
| Android 服务 | KSMAndroidHostServices.kt | 精确 origin 白名单和 ACTION_VIEW |
| 命令 | Windows | Android | 权限 | 返回 |
|---|---|---|---|---|
shell.openExternal | 支持 | 支持 | shell.open | { opened } |
宿主初始化时配置精确 origin 白名单，默认空白名单并拒绝所有调用。比较包含 scheme、host 和显式端口；默认端口会规范化。以下输入会被拒绝：
只校验调用时传入的 URL。系统浏览器后续重定向不经过 Kasumi，因此应用必须选择可信目标 origin。
try {
const result = await KSM.shell.openExternal({
url: 'https://example.com/docs'
});
if (!result.opened) {
console.warn('系统没有可用浏览器处理器');
}
} catch (error) {
if (error instanceof Error && error.name === 'PERMISSION_DENIED') {
console.warn('origin 未加入宿主白名单');
}
}Windows 使用 ShellExecuteW；Android 使用 ACTION_VIEW。两端服务层都会再次校验精确
origin。Android 不会把 intent:// 或任意 content:// 交给系统。
| 错误码 | 场景 |
|---|---|
INVALID_ARGS | scheme、相对 URL、凭据、空主机或长度非法 |
PERMISSION_DENIED | 未授予权限或 origin 不在白名单 |
IO_ERROR | 系统调用失败 |
NOT_SUPPORTED | 宿主没有 Shell 服务 |
TIMEOUT / CANCELLED | 请求超时或窗口销毁 |
没有可用处理器时可能返回 { opened: false }，业务应提供可读提示，而不是循环重试。
shell.open。opened: false 时检查系统默认浏览器或 URL 处理器。
评论