Kasumi
Kasumi Application Development Skill
查看 Markdown使用 Kasumi SDK 创建、配置、调试、构建和发布应用的规范与工作流。
同时检索文章与文档，或切换类型缩小范围
使用 Kasumi SDK 创建、配置、调试、构建和发布应用的规范与工作流。
使用 Kasumi 创建、配置、调试、构建和发布应用时使用本指南。
适用于：
create-kasumi 创建 basic、React、Vue、Next.js 或 Nuxt 应用。kasumi-bridge 暴露的 KSM API 和内置插件。不适用于修改 Kasumi 协议、桥接实现、CLI、原生插件或框架 SDK。此类任务使用 kasumi-framework skill 和 skill/kasumi/framework 页面。
应用缺少框架本身没有的原生能力时，先在框架仓库实现插件，再升级应用依赖。不要复制或修改 vendor/ 中的 SDK 源码。
开始改动前依次读取：
AGENTS.md。kasumi.config.json、package.json 和现有平台宿主入口。yuinijika skill，写码前读取 coding-style.md，写文档前读取 docs-style.md。web-design-guidelines、web-artifacts-builder 和 apple-design。不要根据旧模板、历史聊天或本页面猜测参数、返回值、权限和平台支持。
常用入口：
https://blog.miomoe.cn/docs/kasumihttps://blog.miomoe.cn/docs/kasumi/indexhttps://blog.miomoe.cn/docs/kasumi/developmenthttps://blog.miomoe.cn/docs/kasumi/apihttps://blog.miomoe.cn/docs/kasumi/api/typeshttps://blog.miomoe.cn/docs/kasumi/plugins常用插件页：
https://blog.miomoe.cn/docs/kasumi/plugins/fshttps://blog.miomoe.cn/docs/kasumi/plugins/dialoghttps://blog.miomoe.cn/docs/kasumi/plugins/clipboardhttps://blog.miomoe.cn/docs/kasumi/plugins/notificationhttps://blog.miomoe.cn/docs/kasumi/plugins/windowhttps://blog.miomoe.cn/docs/kasumi/plugins/httphttps://blog.miomoe.cn/docs/kasumi/plugins/shellhttps://blog.miomoe.cn/docs/kasumi/plugins/devicehttps://blog.miomoe.cn/docs/kasumi/plugins/sqlhttps://blog.miomoe.cn/docs/kasumi/plugins/pathhttps://blog.miomoe.cn/docs/kasumi/plugins/storehttps://blog.miomoe.cn/docs/kasumi/plugins/oshttps://blog.miomoe.cn/docs/kasumi/plugins/log在 Kasumi 框架仓库内，用统一工具读取原始 MDX：
pnpm ksm docs pull kasumi/index
pnpm ksm docs pull kasumi/api
pnpm ksm docs pull kasumi/plugins/sql生成应用不包含 tools/update_docs.py，也不允许应用开发者直接提交线上文档修订。
读取顺序：
kasumi/index
└─ kasumi/api
├─ kasumi/api/types
└─ affected API page
└─ kasumi/plugins
└─ affected plugin page
└─ kasumi/development文档没有声明的平台能力视为未确认，不要用当前设备测试结果代替平台矩阵。development 页说明当前已实现和待验证能力，不等同于稳定 API 承诺。
create-kasumi 生成的项目保持前后端与平台宿主分离：
my-app/
├─ frontend/
│ ├─ index.html
│ ├─ framework files
│ └─ src/
│ ├─ main.ts
│ └─ application code
├─ windows/
│ ├─ CMakeLists.txt
│ ├─ main.cpp
│ ├─ cmake/
│ └─ vcpkg.json
├─ android/
│ ├─ settings.gradle.kts
│ ├─ build.gradle.kts
│ ├─ gradle/
│ └─ app/
│ ├─ build.gradle.kts
│ └─ src/main/
│ ├─ AndroidManifest.xml
│ └─ java/<package>/MainActivity.kt
├─ vendor/
│ ├─ windows/kasumi/
│ └─ android/repo/
├─ kasumi.config.json
├─ package.json
├─ pnpm-workspace.yaml
└─ README.mdReact、Vue、Next.js 和 Nuxt 只改变前端目录内容，不改变 Windows、Android、配置和构建入口的职责。
| 路径 | 应用侧职责 | 不应包含 |
|---|---|---|
frontend/ | 页面、组件、状态、业务请求和 KSM 调用 | 框架原生源码、私有消息协议 |
windows/ | Win32 窗口、WebView2 启动、资源和 Host Services 接线 | 从 SDK 复制的命令实现 |
android/ | Activity、WebView 启动、资源和 Host Services 接线 | 从 SDK 复制的插件实现 |
vendor/windows/kasumi/ | 已发布 Windows SDK | SDK 源码修改 |
vendor/android/repo/ | 已发布 Android Maven 仓库 | 手工修改的框架 AAR |
kasumi.config.json | 两端包名、版本、命令和 Windows 标题栏 | 临时开发地址或密钥 |
package.json | 统一命令入口和前端依赖 | 平台专属命令的平行实现 |
{
"windows": {
"packageName": "com.example.app",
"version": "1.0.0",
"commands": ["ping", "capabilities.query"],
"decorations": true
},
"android": {
"packageName": "com.example.app",
"version": "1.0.0",
"commands": ["ping", "capabilities.query"]
}
}| 字段 | 作用 |
|---|---|
windows.packageName | Windows 应用标识、数据目录和产物命名 |
windows.version | Windows 应用版本 |
windows.commands | all 或显式命令白名单 |
windows.decorations | true 使用系统标题栏，false 使用应用自绘窗口控制 |
android.packageName | Android application ID |
android.version | Android 应用版本 |
android.commands | all 或显式命令白名单 |
配置修改后运行 pnpm ksm doctor。不要绕过诊断直接改生成平台文件，否则下一次构建会重新生成配置并覆盖手工修改。
"commands": "all" 会开放完整命令矩阵。生产应用优先使用显式白名单，并保留应用实际使用的 ping、capabilities.query 及插件命令。
| 命令 | 用途 |
|---|---|
pnpm dev | 启动默认开发平台 |
pnpm dev:windows | 启动 Windows 开发宿主 |
pnpm dev:android | 启动 Android 开发宿主 |
pnpm build | 执行默认构建 |
pnpm build:windows | 构建 Windows 应用 |
pnpm build:android | 构建 Android APK |
pnpm build:all | 构建 Windows 和 Android |
pnpm package | 生成发布包 |
pnpm typecheck | 前端 TypeScript 类型检查 |
pnpm ksm doctor | 检查 SDK、配置、工具链和项目结构 |
不要假设 build 会隐式打包或签名。发布动作使用 ksm package，签名要求以线上文档为准。
import { KSM } from "kasumi-bridge";
KSM.init();KSM 方法。KSM.get() 或应用启动流程确认平台与已启用命令。业务状态留在应用前端。原生层只负责系统能力，不承载页面状态。
不要直接调用 WebView2 postMessage、Android JavaScript interface 或自行发明消息格式。所有能力从 kasumi-bridge 的 KSM 根入口进入。
插件命令仍通过 KSM 访问。使用前读取对应 Plugins 页，并确认：
应用没有启用命令时，前端守卫不能代替宿主权限检查。不要通过直接调用系统 API 绕过插件边界。
文件路径使用 Kasumi 虚拟路径。不要把真实磁盘路径、content:// 或任意 URL 传给文件 API。
外部链接只通过 shell.openExternal 打开，并受宿主精确 origin 白名单约束。WebView 导航不能绕过该白名单。
生产页面来源是 https://app.local。开发 origin 只在显式 debug/dev 模式启用，不能固化进生产安全策略。
只有应用级策略需要时修改平台入口：
不要在这里重写命令路由、文件系统、网络、SQL 或通知实现。此类改动属于框架 SDK。
https://app.local。windows.decorations: false 和前端窗口控制共同完成。app-region: drag，按钮和输入控件使用 app-region: no-drag。vendor/windows/kasumi/ 只消费，不修改。https://app.local。ACTION_VIEW，必须经过 shell.openExternal 策略。vendor/android/repo/ 只消费，不修改。推荐顺序：
pnpm ksm doctor 检查配置、SDK 和工具链。pnpm typecheck 检查前端类型和 API 调用。kasumi.config.json 是否启用目标命令。capabilities.query 或 KSM.get() 的实际平台能力。https://app.local 或受控开发 origin。| 现象 | 优先检查 |
|---|---|
| 前端方法不存在 | kasumi-bridge 版本、线上文档、导入入口 |
调用返回 PERMISSION_DENIED | 命令白名单、宿主权限、origin |
| 文件路径被拒绝 | 是否使用 app://data、app://cache、app://tmp |
| 外链打不开 | shell.openExternal 和宿主精确 origin 白名单 |
页面 ERR_NAME_NOT_RESOLVED | 开发服务器是否启动、开发 origin 是否启用 |
| Windows 构建找不到依赖 | SDK、CMake、vcpkg、系统 WebView2 Runtime |
| Android 构建找不到 SDK | vendor/android/repo/、JDK、Android SDK |
开发只在用户要求时启动：
pnpm dev:windows
pnpm dev:android构建：
pnpm build:windows
pnpm build:android
pnpm build:all发布包：
pnpm ksm package --windows
pnpm ksm package --android
pnpm ksm package --all构建与缓存目录：
| 路径 | 内容 |
|---|---|
.ksm/dev/ | 开发状态、开发宿主和依赖缓存 |
.ksm/dist/windows/ | Windows 开发或构建产物 |
.ksm/dist/android/ | Android APK 构建产物 |
.ksm/dist/packages/ | ksm package 生成的发布包 |
.tmp/ | 一次性诊断和测试输出 |
发布前读取线上文档确认签名环境变量、WebView2 打包选项、产物内容和校验要求。普通开发构建不等于已签名发布包。
出现以下情况时停止修改应用 vendor/：
切换到 kasumi-framework skill，在框架仓库完成协议、双端实现、测试和发布，再升级应用。
评论