能力补全验证矩阵

定义协议、契约、包、双端原生、端到端与发布链路验证矩阵。

定义协议、生成契约、前端、包、双端原生、端到端与发布链路的验证范围和通过标准。

状态与范围

状态项	说明
`当前 26.11.5`	当前 26.11.5 基线为 63 个命令、3 个事件、18 个插件、18 个权限、11 个错误码；Windows 62 个命令、Android 55 个命令，两端各 3 个事件。托盘、全局快捷键、更新器和单实例存在占位行为；新增能力均尚未发布。
`目标规格（未发布）`	规格 / 待实现：把 P0–P5 的命令、事件、双端服务、npm 包、文档与产物纳入同一验证矩阵；平台差异、错误码和 Release 结论可追溯。
`实施阶段`	P0–P5；每个阶段退出前执行对应行，P5 执行完整矩阵。
`验收标准`	全部自动验证通过；需真机、签名资产或发布环境的条目明确标注并人工验收；无占位成功、无生成契约漂移、无覆盖 26.11.5。

模块边界

本页定义验证入口和通过标准，不替代各能力页的专项测试，也不把本地构建、CI 构建、Release 资产与 npm registry 状态混为一谈。验证失败时先定位到协议、前端、宿主、平台服务、包或发布链路，再修改对应事实源。

层级	真实入口	责任
协议	`protocol/commands.json`、`protocol/permissions.schema.json`、`protocol/plugins.json`、`protocol/errors.json`、`protocol/kasumi.config.schema.json`	命令、事件、权限、错误码、插件和平台矩阵一致性。
生成器	`tools/validate_protocol.py`、`tools/codegen.py`	参数校验器、三端契约、插件元数据与能力查询数据。
前端与契约	`frontend/src/bridge/ksm.ts`、`frontend/src/bridge/transport.ts`、`tests/contract/`	请求生命周期、重载恢复、订阅、取消、消息边界与模拟宿主。
CLI 与模板	`packages/kasumi-cli/src/config.mjs`、`cli/kasumi_config.py`、`packages/create-kasumi/templates/`、`pnpm ksm doctor`	配置、扩展清单、origin、命令白名单、干净目录初始化。
Windows	`windows/CMakeLists.txt`、`windows/tests/contract_runner.cpp`	构建与 CTest；平台服务、多窗口、线程与资源清理。
Android	`android/kasumi/build.gradle.kts`、`android/app/src/test/`、`android/app/src/androidTest/`	Gradle JVM 与 instrumentation；SAF、Media3、生命周期与后台运行。
发布	`version.json`、`pnpm ksm package --target sdk`、`.ksm/release/`、GitHub Release、npm registry	版本、资产、签名、校验和、Release 与 npm 一致性。

当前缺口与目标契约

验证层	当前 26.11.5 基线	目标规格 / 待实现
协议与生成	已有 `pnpm validate:protocol` 与 `pnpm codegen`，生成物覆盖 63 个内置命令和 3 个事件。	新增扩展清单、网络、媒体库、音频、媒体会话、多窗口、系统命令与事件后零漂移；`since` 从 `version.json` 生成。
前端契约	现有测试覆盖传输、超时、重载、路径、消息限制与内置 API。	覆盖扩展命令/事件、定向事件、64 KiB 边界、`{ file }`、能力查询、重复订阅与取消竞态。
包与模板	已有 `pnpm test:packages`、`pnpm test:tarballs`。	新增 `kasumi-plugin-audio`、`kasumi-plugin-media-session`；所有包依赖同一新版本 `kasumi-bridge`。
Windows	已有构建和 CTest 入口；占位系统能力不代表真实行为。	HTTP、文件 scope、媒体元数据、WASAPI、多窗口、托盘、热键、更新、深链和资源清理专项测试。
Android	已有 JVM 与 instrumentation 入口；缺少媒体会话和后台租约覆盖。	SAF 持久授权、Media3、MediaSession、前台服务、通知权限、后台 JS、低内存隔离和深链专项测试。
发布	26.11.5 已发布标签、Release 资产与 npm 包。	新版本从 `version.json` 生成，先 GitHub Release 再 npm；不覆盖、不移动、不重复发布 26.11.5。
文档	九页规格标注“规格 / 待实现”。	代码发布后同步相关 API 与 Plugins 页；状态表、命令数量、平台矩阵与生成结果一致。

验证命令	范围	通过条件
`pnpm validate:protocol`	协议一致性、权限、插件、错误码与平台矩阵。	无未知字段、无重复命令/事件、无缺失权限或平台声明。
`pnpm codegen`	TypeScript、C++、Kotlin 契约生成。	重新生成后 `git diff` 只包含预期契约；生成文件无手写改动。
`pnpm typecheck`	`frontend/tsconfig.json` 与 `tests/tsconfig.json`。	严格类型检查无错误，目标 API 类型从公共入口导出。
`pnpm test:contract`	`tests/contract/`。	超时、取消、重载、订阅、迟到响应、消息边界与能力查询全部通过。
`pnpm test:packages`	`kasumi-bridge`、插件、CLI、create-kasumi。	包导出、README、依赖版本与构建产物一致。
`pnpm test:tarballs`	干净目录中的 npm tarball 安装链路。	初始化、配置、doctor 与最小构建可用，不复制框架源码。
Windows 构建与 CTest	`windows/CMakeLists.txt`、`windows/tests/`。	平台服务、UI 线程回投、多窗口、设备与系统资源专项通过。
Android Gradle JVM / instrumentation	`android/kasumi/build.gradle.kts`、设备测试目录。	JVM 测试通过；instrumentation 构建或真机测试覆盖系统能力。
`git diff --check`	工作树文本差异。	无空白错误、无 CRLF、无 BOM；`.tmp/` 不进入提交。

接口与示例

真实入口是仓库 package.json 脚本、cli/ksm.mjs、pnpm ksm docs、windows/CMakeLists.txt 与 Android Gradle 工程。文档草稿只放在 .tmp/kasumi-docs/，线上修订通过 pnpm ksm docs 的 --dry-run 和带 --note 的提交流程，本轮不执行提交。

以下示例描述目标接口，尚未在 26.11.5 发布：

TypeScript

import { KSM, KSMWebMessageTransport } from 'kasumi-bridge';

KSM.initialize(new KSMWebMessageTransport());
KSM.configureExtensions({
  id: 'library',
  commands: [
    {
      name: 'app.library.scan.start',
      platforms: ['windows', 'android'],
      permissions: ['fs.read', 'media.probe'],
      args: {},
      result: {}
    }
  ],
  events: []
});

const capabilities = await KSM.capabilities();
const permission = await KSM.permission.request('fs.read');
if (!permission.granted || !capabilities.commands.includes('app.library.scan.start')) {
  throw new Error('The extension verification case is unavailable.');
}

const off = KSM.on<{ visible: boolean }>(
  'window.visibilityChanged',
  (payload) => console.info(payload.visible)
);
await KSM.subscribe('window.visibilityChanged');
await KSM.invoke('app.library.scan.start', {});
off();
await KSM.unsubscribe('window.visibilityChanged');

该用例验证扩展契约加载、能力查询、权限守卫、目标事件订阅与调用。测试不得把断言写进生产前端代码；模拟宿主使用 tests/contract/adapters/mock-host.ts，平台真实行为交给 Windows CTest 与 Android instrumentation。

双端实现

平台	验证入口	必须覆盖
Windows	`windows/CMakeLists.txt`、`windows/tests/contract_runner.cpp`、`windows/src/platform/` 的 CTest 目标	WinHTTP 与逐跳 origin、CookieJar、目录/多选、FFmpeg/TagLib 或等价元数据、WASAPI 共享/独占、设备占用、EQ、倍速、seek、tick/ended、多 WebView2、托盘菜单、热键、单实例互斥、深链、签名更新安装与回滚、UI 线程回投、销毁后迟到响应、资源清理。
Android	`android/kasumi/build.gradle.kts`、`android/app/src/test/`、`android/app/src/androidTest/`	SAF 持久目录与多文件、系统下载、Media3 播放、MediaSession/锁屏控制、MediaStyle 通知、通知权限、音频焦点、唤醒锁、后台 WebView 租约、后台 JS 可调度、旋转、Activity 销毁、`onTrimMemory` 隔离、深链冷/热启动、返回键事件、签名与安装边界。

JVM 测试不能替代需要系统服务、前台服务、锁屏控制或真机后台策略的 instrumentation 测试。CI 构建、本地构建、Release 资产与 registry 状态分别在报告中记录。

反例与限制

不把 dev server、模拟器启动、依赖下载或构建成功当作普通验证；不把构建产物视为已签名发布资产。
不运行全仓格式化器批量重排无关文件；不手改生成契约，不以本地旧 README 数量替代当前协议生成结果。
不向前端暴露真实路径，不在 Android 使用 addJavascriptInterface，不在单条 JSON 消息中传递超过 64 KiB 的载荷，不引入 Rust/Node 中间 runtime，不写前端平台分支。
不直接修改应用生成工程中的 vendor/ SDK；业务扩展命令通过清单与已发布 SDK 接入。
不覆盖、不移动、不重复发布 26.11.5 的标签、Release 资产或 npm 版本；发布失败时增加补丁版本。
不把未实现平台写成支持，不把占位成功写成通过，不把规格页写成已上线 API 文档。
不把 .tmp/ 草稿、.ksm/dev/ 缓存、构建垃圾或 .workbuddy/ 纳入提交；正式文档提交只通过 pnpm ksm docs。

错误与排查

错误码	验证场景	期望行为
`INVALID_ARGS`	参数、扩展 Schema、URL、虚拟路径或事件载荷非法。	前端守卫与宿主校验同时拒绝。
`UNKNOWN_COMMAND`	生成契约、插件注册、allowlist 或扩展清单不一致。	定位到协议、CLI 或路由器，不回退私有通道。
`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 配置阶段拒绝构建。

现象	优先检查
`pnpm codegen` 后仍有差异	是否手改生成文件、协议源文件是否保存、生成器输出路径、`git diff --check`。
前端扩展命令不可用	扩展契约加载顺序、能力缓存、命令 allowlist、插件注册与 `windowId`。
契约测试通过但真机失败	模拟宿主是否覆盖系统服务、instrumentation 是否执行、签名与权限是否齐全。
Windows CTest 超时	UI 线程回投、互斥量、独占音频设备、更新安装进程占用。
Android 后台测试不稳定	前台服务、唤醒锁、音频焦点、WebView 租约、系统电池策略与设备日志。
包测试版本不一致	`version.json`、npm manifests、`kasumi-bridge` peer/dependency 版本与 tarball 内容。
Release 资产与 npm 不一致	发布顺序、校验和、签名、Release 资产列表、registry `latest`。
文档 `dry-run` diff 异常	草稿路径是否在 `.tmp/kasumi-docs/`、frontmatter 是否手写、命令数量是否来自当前协议。

验收

P0 通过 pnpm validate:protocol、pnpm codegen、pnpm typecheck、pnpm test:contract；P1–P4 每阶段补跑对应 Windows CTest、Android JVM/instrumentation 与 pnpm test:packages。
P5 通过 pnpm test:tarballs、pnpm ksm package --target sdk、git diff --check、Windows 安装包与签名 Android APK 校验；pnpm ksm docs 的每篇 --dry-run diff 检查通过，正式提交带 --note 并记录 uuid。
所有目标命令、事件、错误码、权限与平台矩阵来自同一生成结果；相关 API/Plugins 页只在代码发布后同步。
九页规格与索引包含状态表、真实入口、示例、反例、错误表、排查表和验收条目；重新 pnpm ksm docs pull 验证线上正文一致。
从 version.json 生成高于 26.11.5 的新版本，先发 GitHub Release 再发 npm；Release 不写版本号、日期、作者，修复项写明现象与根因或方案；验证全部 npm 包版本和 latest。
不覆盖、不移动、不重复发布 26.11.5；不使用 dev server 或模拟器作为普通验证；不运行全仓格式化器；生成契约无漂移，占位成功清零，.tmp/ 与构建垃圾不进入提交。

状态与范围

模块边界

当前缺口与目标契约

接口与示例

双端实现

反例与限制

错误与排查

验收

评论

On this page

状态与范围

模块边界

当前缺口与目标契约

接口与示例

双端实现

反例与限制

错误与排查

验收