Kasumi
Kasumi Framework Development Skill
查看 MarkdownKasumi 框架内部开发规范、仓库导航、变更流程、验证矩阵和文档同步要求。
同时检索文章与文档，或切换类型缩小范围
Kasumi 框架内部开发规范、仓库导航、变更流程、验证矩阵和文档同步要求。
修改 Kasumi 框架内部协议、桥接、插件、CLI、Windows、Android、测试、打包或文档时使用本指南。
适用于：
frontend 桥接层、kasumi-bridge 和 kasumi-plugin-* 包。kasumi-cli、create-kasumi、模板、构建、打包和发布流程。不适用于使用 Kasumi 开发应用业务页面、应用数据模型或普通前端交互。应用开发使用 kasumi-app skill 和 skill/kasumi/app 页面。
如果应用缺少框架本身没有的原生能力，在框架仓库实现并发布，不要要求应用修改 vendor/ 中的 SDK。
任何代码或文档改动前，依次读取：
AGENTS.md。.agents/skills/yuinijika/SKILL.md。.agents/skills/yuinijika/coding-style.md。.agents/skills/yuinijika/docs-style.md。线上文档是公共 API 和用户行为的事实来源。不要依据旧聊天、旧草稿、发布说明或本地缓存猜测参数、返回值、权限或平台支持。
Kasumi 文档统一通过仓库工具读写：
pnpm ksm docs list --paths
pnpm ksm docs show kasumi/development
pnpm ksm docs pull kasumi/development
pnpm ksm docs push .tmp/kasumi-docs/kasumi/development.md --path kasumi/development --note "同步开发状态" --dry-run
pnpm ksm docs status工具规则：
tools/update_docs.py。kasumi 与 skill/kasumi 文档分区。.tmp/kasumi-docs/；Agent skill 规范源文件可直接使用 docs/skill/kasumi/。--note，提交前必须检查 --dry-run diff。pnpm ksm docs create <file> --path <path> --title <title> --description <description> --note <note> --dry-run。MIOMOE_AGENT_BASE_URL、MIOMOE_AGENT_KEY 或 --env 读取。.workbuddy 文档脚本，禁止创建 .workbuddy/。提交的是修订队列中的完整正文，不是增量 diff。审核通过后重新拉取页面，确认线上内容已经生效。
| 路径 | 职责 |
|---|---|
version.json | 仓库、SDK、npm 包和平台工程的版本元数据 |
protocol/commands.json | 命令、参数、返回值、平台、权限和版本字段 |
protocol/permissions.schema.json | 权限命名和授权边界 |
protocol/plugins.json | 插件身份、模块归属和命令归属 |
protocol/errors.json | 共享错误码 |
protocol/kasumi.config.schema.json | 用户配置文件结构 |
protocol/README.md | 协议维护约束和平台矩阵 |
命令契约只修改上述源文件。TypeScript、C++ 和 Kotlin 契约必须由 tools/codegen.py 生成，禁止手写平行清单。
生成位置：
| 路径 | 来源 |
|---|---|
frontend/src/generated/contract.ts | tools/codegen.py |
windows/src/generated/contract.h | tools/codegen.py |
windows/src/generated/errors.h | tools/codegen.py |
android/kasumi/src/main/java/dev/kasumi/app/generated/KSMGeneratedContract.kt | tools/codegen.py |
android/kasumi/src/main/java/dev/kasumi/app/generated/KSMErrorCode.kt | tools/codegen.py |
| 路径 | 职责 |
|---|---|
frontend/src/bridge/ | WebView 消息传输、请求生命周期、事件总线和共享类型 |
frontend/src/api/ | 面向用户的前端 API 包装和参数守卫 |
frontend/src/index.ts | KSM 根入口和模块挂载 |
packages/kasumi-bridge/ | 发布给应用的前端桥接包 |
packages/kasumi-plugin-* | 内置插件的 npm 包和类型入口 |
packages/kasumi-cli/ | ksm 命令、配置解析、开发、构建、打包和发布 |
packages/create-kasumi/ | 在线初始化器、模板选择和 SDK 安装 |
packages/create-kasumi/templates/ | basic、React、Vue、Next.js 和 Nuxt 应用模板 |
windows/src/bridge/ | Windows 路由、请求注册和命令分发 |
windows/src/plugins/ | Windows 内置插件实现 |
windows/src/platform/ | Win32、WebView2、Host Services、路径和 URL 安全策略 |
windows/examples/ | Win32 示例宿主 |
android/kasumi/src/main/java/dev/kasumi/app/bridge/ | Android 路由、插件、WebView 和多窗口生命周期 |
android/kasumi/src/main/java/dev/kasumi/app/ | Android Host Services 和公开宿主入口 |
tools/validate_protocol.py | 协议一致性和平台矩阵校验 |
tools/codegen.py | 三端 TypeScript、C++、Kotlin 契约生成 |
tests/contract/ | 前端与模拟宿主契约、生命周期和超时测试 |
website/ | Vue 3 + Vite 独立官网工程 |
protocol/commands.json 是命令契约的唯一事实来源。permissions.schema.json、plugins.json、errors.json 及对应 schema 保持一致。version.json 是版本元数据的唯一来源。不要在 CLI、原生工程、README 或发布脚本中新增硬编码版本号。.ksm/dist/，开发缓存进入 .ksm/dev/，框架发布附件进入 .ksm/release/。.tmp/，禁止创建或恢复 .workbuddy/。protocol/commands.json，补齐参数、返回值、平台、权限、since 和行为说明。permissions.schema.json、plugins.json、errors.json 和 schema。protocol/README.md 的平台矩阵和命令归属。pnpm validate:protocol。pnpm codegen，禁止直接编辑生成文件。不要在协议尚未确定时先改 C++ 或 Kotlin，否则命令元数据、权限和前端类型会分叉。
frontend/src/api/ 增加或修改模块 API，使用共享 guard 校验参数。frontend/src/index.ts 挂载到 KSM 根入口，并导出公开类型。packages/kasumi-bridge 的公共入口和类型，不复制生成契约。packages/kasumi-plugin-* 的包装、README 和平台能力过滤。pnpm typecheck 和 pnpm test:contract。pnpm test:packages。请求 ID、超时、取消、重载和迟到响应属于桥接层职责。不要在业务插件里各自实现一套。
windows/src/plugins/ 注册插件和命令，从生成契约读取命令名。windows/src/platform/ 服务层。ksm_plugin_registry 和 ksm_router 中保持命令发现与分发一致。WebView2 默认使用系统 Evergreen Runtime。只有用户明确要求时才生成或打包 WebView2Loader.dll。
android/kasumi/src/main/java/dev/kasumi/app/bridge/ 增加插件、命令和 Host Services 方法。windowId 路由请求、事件、下载和取消，不使用覆盖式全局单例。https://app.local 和显式启用的开发 origin。close() 只注销当前窗口；Activity 或 Application 管理 Host Services 生命周期。onTrimMemory 只影响当前窗口，不要取消其他窗口的下载或暂停全局 WebView 计时器。shell.openExternal 和精确 origin 白名单打开。protocol/kasumi.config.schema.json 和 packages/kasumi-cli/src/config.mjs。.ksm/dist/，开发状态进入 .ksm/dev/，框架维护者发布附件进入 .ksm/release/。pnpm test:tarballs，不要只检查模板静态文件。version.json 读取。公共行为变化后，先读取当前线上 MDX，再更新本地实现或文档。
用户要求同步文档时：
pnpm ksm docs pull <path> 拉取目标页和相邻索引到 .tmp/kasumi-docs/。pnpm ksm docs push <file> --path <path> --note <note> --dry-run。--yes 提交修订，并记录返回的 uuid 与状态。pnpm ksm docs status <uuid> 跟踪审核；通过后再次 pull 确认线上内容。不得提前把未发布的 SDK、npm 包或 Release 描述为已上线。必须区分本地构建、CI 构建、Release 资产和 npm registry 已验证状态。
| 改动 | 最低验证 |
|---|---|
| 协议、权限、错误码、生成契约 | pnpm validate:protocol、pnpm typecheck、pnpm test:contract |
| 前端桥接或共享类型 | pnpm typecheck、pnpm test:contract |
| npm 包或内置插件包 | pnpm test:packages |
| 初始化器、模板或 tarball 安装链路 | pnpm test:tarballs |
| 在线文档工具 | python -m unittest tests.test_update_docs |
| Windows 原生实现 | 仓库定义的 Windows 构建和 CTest 目标 |
| Android 原生实现 | 对应 Gradle JVM 测试和 instrumentation 构建 |
| 官网 | 在 website/ 执行 pnpm type-check 和 pnpm build |
| 任意改动收尾 | git diff --check |
用户未要求时，不要启动 dev、开发服务器、模拟器或完整发布构建。涉及发布、打包或真实环境门槛时，明确区分已执行验证和仍需人工验证的项目。
version.json 更新版本。.ksm/release/kasumi/、.ksm/release/app/。doctor。发布失败时增加补丁版本，不覆盖已公开的 npm 版本或移动已发布标签，除非用户明确要求并理解缓存和下游影响。
.workbuddy/ 没有进入工作树。
评论