Windows + Android 原生能力补全总览
定义 Kasumi Windows 与 Android 通用原生能力补全目标、边界、阶段和完成标准。
同时检索文章与文档，或切换类型缩小范围
定义 Kasumi Windows 与 Android 通用原生能力补全目标、边界、阶段和完成标准。
定义 Kasumi 在 Windows 与 Android 上需要补齐的通用原生能力、分层边界、阶段与完成标准。
| 状态项 | 说明 |
|---|---|
当前 26.11.5 | 当前 26.11.5 基线为 63 个命令、3 个事件、18 个插件、18 个权限、11 个错误码；Windows 62 个命令、Android 55 个命令，两端各 3 个事件。网络仅有 http.download，事件仅有 webview.navigated、webview.reloaded、window.resized；托盘、全局快捷键、更新器和单实例存在占位行为。 |
目标规格（未发布） | 规格 / 待实现：补齐协议扩展、网络、媒体库、音频、媒体会话、多窗口和系统能力，双端提供真实实现或明确的 NOT_SUPPORTED；公共 API、插件包、生成契约和测试使用同一平台矩阵。 |
实施阶段 | P0–P5；本页是总览，各子页标注其阶段。 |
验收标准 | 目标能力清单全部实现或明确声明不支持；无占位成功；协议、生成物、文档、npm 包和 Release 一致；Windows 与 Android 验收矩阵通过。 |
| 平台 | 范围 | 说明 |
|---|---|---|
| Windows | 范围内 | C++20、Win32、WebView2、WASAPI、系统托盘、全局快捷键、安装包更新。 |
| Android | 范围内 | Kotlin、系统 WebView、SAF、Media3、MediaSession、前台服务、系统通知。 |
| macOS | 范围外 | 不声明能力，不纳入协议矩阵和验收。 |
| Linux | 范围外 | 不声明能力，不纳入协议矩阵和验收。 |
| iOS | 范围外 | 不声明能力，不纳入协议矩阵和验收。 |
框架提供原生原子能力、应用扩展清单、固定媒体依赖和统一消息边界。应用使用扩展命令与现有 FS、SQL、Store、HTTP 能力组合业务编排，不把业务表、缓存策略或播放器状态写入框架协议。
| 层级 | 事实源或入口 | 责任 |
|---|---|---|
| 协议 | protocol/commands.json、protocol/permissions.schema.json、protocol/plugins.json、protocol/errors.json | 内置命令、事件、权限、错误码、插件归属和平台矩阵。 |
| 生成器与配置 | tools/codegen.py、tools/validate_protocol.py、protocol/kasumi.config.schema.json | 三端契约、参数校验、能力清单与扩展清单校验。 |
| 前端 | frontend/src/index.ts、frontend/src/bridge/ksm.ts、frontend/src/bridge/transport.ts | KSM 根入口、请求生命周期、事件订阅、参数守卫和 64 KiB 消息边界。 |
| CLI | packages/kasumi-cli/src/config.mjs、cli/kasumi_config.py | 配置解析、命令白名单、origin 白名单、doctor 和模板接线。 |
| Windows | windows/src/bridge/ksm_router.cpp、windows/src/plugins/、windows/src/platform/ | 原生命令、Host Services、窗口隔离、URL 与虚拟路径策略。 |
| Android | android/kasumi/src/main/java/dev/kasumi/app/bridge/KSMRouter.kt、KSMWebViewHost.kt、KSMPlugin.kt | 原生命令、Host Services、WebView 生命周期与窗口隔离。 |
| 包 | packages/kasumi-bridge/、packages/kasumi-plugin-*/ | 公共 API、类型、插件包装和同版本依赖。 |
当前 26.11.5 基线不表示实现后的最终数量。下表全部为规格 / 待实现；命令、事件和权限的正式结构与 since 由后续协议文件和 tools/codegen.py 生成。
| 子系统 | 目标命令 | 目标事件 | 当前缺口 |
|---|---|---|---|
| 扩展与协议 | KSM.configureExtensions(contract)；顶层 extensions 配置；扩展命令 app.<domain>.<action>；扩展事件 app.<domain>.<event> | 重载后的扩展事件订阅恢复 | 生成事件白名单固定，CLI 与前端不接受应用扩展清单。 |
| 错误码 | MEDIA_UNSUPPORTED、AUDIO_DEVICE_BUSY、UPDATE_VERIFICATION_FAILED、DEEP_LINK_INVALID、EXTENSION_CONFLICT | 无 | 共享错误码只覆盖现有 11 类错误。 |
| 网络 | http.request、http.transfer.start、http.transfer.cancel、http.cookies.get、http.cookies.set、http.cookies.clear | http.transfer.progress、http.transfer.completed、http.transfer.failed | 只有 http.download；无通用请求、CookieJar、进度和取消事件。 |
| 文件与媒体库 | dialog.openFolder、dialog.openFiles、fs.walk、fs.scope.release、media.probe、media.ffmpeg.detect、media.ffmpeg.validate、media.ffmpeg.setPath、media.ffmpeg.pickExecutable | 无 | 无目录选择、多文件选择、递归枚举、持久目录 scope 和媒体元数据。 |
| 音频 | audio.devices.list、audio.devices.set、audio.output.getMode、audio.output.setExclusive、audio.eq.set、audio.speed.set、audio.probe、audio.load、audio.play、audio.pause、audio.stop、audio.seek、audio.volume.set、audio.state.get | audio.tick、audio.ended、audio.stateChanged、audio.error | 双端均无音频引擎和设备控制。 |
| 媒体会话 | mediaSession.update、mediaSession.clear | mediaSession.command | 无前台服务、媒体通知、传输控制或后台 WebView 租约。 |
| 多窗口 | window.create、window.show、window.hide、window.setPosition、window.setAlwaysOnTop、window.setTransparent、window.getState、event.emit、app.deepLink.getPending、app.openDevtools | window.visibilityChanged、window.stateChanged、app.deepLink.received、app.secondInstance.received；Android 返回键事件纳入目标清单 | 当前窗口插件只控制当前窗口；生成事件固定；深链和跨窗口事件缺失。 |
| 系统 | tray.configure、updater.install；真实单实例、全局快捷键和通知权限 | tray.action、tray.click、globalShortcut.triggered、updater.progress、updater.status | 托盘无真实图标和菜单，快捷键默认不注册，更新器无签名安装与回滚，单实例默认放行。 |
| 依赖 | 目标位置 | 约束 |
|---|---|---|
| Windows FFmpeg、TagLib 或等价元数据库、WASAPI | windows/vcpkg.json、windows/CMakeLists.txt、Windows Host Services | 版本固定在版本清单；编解码和系统调用留在服务层。 |
Android Media3、MediaSession 与 documentfile | Gradle version catalog 和 android/kasumi/build.gradle.kts | 版本固定在版本清单；权限写入 android/kasumi/src/main/AndroidManifest.xml。 |
| 阶段 | 交付 | 退出条件 |
|---|---|---|
| P0 | 协议、权限、错误码、插件元数据、扩展清单、codegen、CLI、模板与 doctor。 | 生成契约零漂移；非法扩展清单被拒绝；Node CLI 与 Python CLI 结论一致。 |
| P1 | 网络、文件 scope、目录/多选取器、递归枚举、媒体元数据与转码工具检测。 | 双端请求、授权、枚举、探测与大结果 { file } 通过；无真实路径进入前端。 |
| P2 | 双端音频引擎、设备控制、播放状态与进度事件。 | 设备、解码、EQ、倍速、seek、tick/ended 与设备占用语义通过。 |
| P3 | Android 媒体会话、前台服务、后台 WebView 租约、Windows 托盘与全局快捷键。 | 传输控制、后台调度、资源释放与多窗口隔离通过。 |
| P4 | 多窗口、跨窗口事件、深链、单实例、devtools、签名更新安装与回滚。 | windowId 隔离、冷/热启动、互斥、更新回滚与占位成功清零通过。 |
| P5 | npm 包、端到端示例、签名产物、文档同步、GitHub Release 与 npm 发布。 | 全量验证矩阵、Release 资产、npm 版本与 latest 一致；高于 26.11.5 的新版本完成发布。 |
| 分层 | 框架职责 | 应用职责 |
|---|---|---|
| 原生原子能力 | 协议、命令、事件、权限、双端服务、固定媒体依赖和测试。 | 从 KSM 根入口调用，不复制框架源码。 |
| 扩展清单 | 校验 ID、命名、命令、事件、权限和平台；生成前端契约。 | 声明扩展命令与事件，注册宿主插件，实现业务编排。 |
| 业务编排 | 提供通用 FS、SQL、Store、HTTP、媒体和窗口能力。 | 组合扫描、缓存、数据模型、播放列表与偏好状态。 |
完成定义：
NOT_SUPPORTED。vendor/ SDK，不复制框架 C++、Kotlin 或生成契约。真实入口是 frontend/src/index.ts 导出的 KSM 类以及 kasumi-bridge 包。KSM.initialize() 创建传输，KSM.capabilities() 查询当前宿主能力，KSM.invoke() 进入统一请求通道，KSM.on() 与 KSM.subscribe() 管理事件。以下命令和模块均为规格 / 待实现。
以下示例描述目标接口，尚未在 26.11.5 发布：
import { KSM, KSMWebMessageTransport } from 'kasumi-bridge';
KSM.initialize(new KSMWebMessageTransport());
const capabilities = await KSM.capabilities();
const permission = await KSM.permission.request('http.request');
if (!permission.granted || !capabilities.commands.includes('http.request')) {
throw new Error('http.request is unavailable.');
}
const response = await KSM.invoke<{ body: string | { file: string } }, {
url: string;
method: 'GET';
}>('http.request', {
url: 'https://api.example.test/health',
method: 'GET'
});
if (typeof response.body !== 'string') {
const handle = await KSM.fs.readText({ path: response.body.file });
console.info(handle);
}扩展清单、HTTP 响应、媒体探测结果和枚举结果超过 64 KiB 时返回 { file } 虚拟句柄，由前端按需读取。命令参数与返回值必须先进入 protocol/commands.json，再经 tools/codegen.py 生成三端校验器。
| 平台 | 实现边界 | 验收重点 |
|---|---|---|
| Windows | WinHTTP 与 CookieJar、Win32 对话框和文件 scope、FFmpeg/TagLib 或等价库、WASAPI、多 WebView2 窗口、Shell_NotifyIconW、全局热键、签名安装包安装与回滚，全部放入 windows/src/platform/ 服务层。 | UI 线程回投、窗口销毁后迟到响应抑制、独占设备释放、更新回滚和多窗口状态隔离。 |
| Android | OkHttp 或平台网络栈与隔离 CookieJar、SAF 持久授权、Media3 播放与 MediaSession、前台服务和媒体通知、唤醒锁、后台 WebView 租约、系统下载、通知运行时权限，全部放入 Android Host Services 与 bridge/。 | 持久授权失效、旋转和 Activity 销毁、音频焦点、后台 JS 可调度、低内存不取消其他窗口任务。 |
两端都从生成契约读取命令名、权限和平台矩阵。capabilities.query 必须反映真实注册的插件；未实现平台返回 NOT_SUPPORTED，不得返回占位成功。
protocol/commands.json；应用扩展命令使用 app.<domain>.<action>，不抢占 core.*、ksm.* 或生成命令名。frontend/src/generated/contract.ts、windows/src/generated/contract.h 或 Android 生成契约；不按平台字符串在前端写分支。content:// URI、私有凭据或未脱敏的 Cookie；目录授权只转换为 app://scope/<id>/...。addJavascriptInterface，不直接调用 window.chrome.webview 或 WebView 私有注入对象，不自行拼接协议响应。{ file }。vendor/ SDK，不把构建通过视为能力测试通过。shown: true、快捷键 registered: true、更新器 downloaded: true 或单实例 primary: true 当作占位成功的返回值。| 错误码 | 触发条件 | 期望行为 |
|---|---|---|
INVALID_ARGS | 参数不符合扩展清单或生成契约。 | 前端守卫与宿主校验同时拒绝。 |
UNKNOWN_COMMAND | 命令未注册或扩展清单未启用。 | 路由器拒绝，不回退私有通道。 |
PERMISSION_DENIED | 权限、origin、目录 scope 或系统运行时授权未通过。 | 原生层在命令执行前拒绝。 |
NOT_SUPPORTED | 平台未实现且能力矩阵明确排除。 | 能力查询不列出该命令。 |
CANCELLED / TIMEOUT | 传输取消、窗口销毁或超时。 | 释放资源，抑制迟到响应。 |
MEDIA_UNSUPPORTED | 文件或音频流无法解码。 | 返回结构化原因，不回退任意可执行文件。 |
AUDIO_DEVICE_BUSY | 音频设备被占用或独占模式冲突。 | 保持当前状态，允许显式释放后重试。 |
UPDATE_VERIFICATION_FAILED | 更新包签名或校验和失败。 | 保留旧版本并删除临时包。 |
DEEP_LINK_INVALID | 深链 scheme、host 或参数非法。 | 拒绝导航，不投递事件。 |
EXTENSION_CONFLICT | 扩展 ID、命令或事件与保留名冲突。 | CLI 配置阶段拒绝构建。 |
| 现象 | 优先检查 |
|---|---|
| 能力查询缺少目标命令 | protocol/commands.json、生成契约、插件注册、命令白名单和平台矩阵。 |
前端出现 UNKNOWN_COMMAND | KSM 初始化、扩展契约加载顺序、宿主路由器与生成事件表。 |
| 重载后事件丢失 | webview.reloaded 恢复流程、KSM.capabilities() 缓存和按 windowId 的订阅表。 |
| 文件 scope 失效 | app://scope 句柄、SAF 持久授权、Windows 选择器授权和 fs.scope.release。 |
| 后台播放停止 | Android 前台服务、唤醒锁、音频焦点、WebView 运行时租约和窗口关闭所有权。 |
| 系统能力返回成功但无效果 | 托盘、热键、更新器、单实例是否仍为占位实现。 |
| Release 与 npm 不一致 | version.json、平台版本头、npm manifests、Release 资产和 registry latest。 |
NOT_SUPPORTED；capabilities.query、协议矩阵和线上文档结论一致。addJavascriptInterface，无前端平台分支，无超过 64 KiB 的 JSON 载荷，无 Rust/Node 中间 runtime。26.11.5 不被覆盖或重复发布。capability-tests 页的逐项结果为准。
评论