---
title: "Kasumi Framework Development Skill"
description: "Kasumi 框架内部开发规范、仓库导航、变更流程、验证矩阵和文档同步要求。"
---


> 修改 Kasumi 框架内部协议、桥接、插件、CLI、Windows、Android、测试、打包或文档时使用本指南。

## 1. 适用边界

适用于：

- 新增或修改协议命令、权限、错误码、插件元数据和生成契约。
- 修改 `frontend` 桥接层、`kasumi-bridge` 和 `kasumi-plugin-*` 包。
- 修改 Windows Win32/WebView2 宿主、Android WebView 宿主和双端插件实现。
- 修改 `kasumi-cli`、`create-kasumi`、模板、构建、打包和发布流程。
- 修改框架测试、示例、官网和在线开发文档。

不适用于使用 Kasumi 开发应用业务页面、应用数据模型或普通前端交互。应用开发使用 `kasumi-app` skill 和 `skill/kasumi/app` 页面。

如果应用缺少框架本身没有的原生能力，在框架仓库实现并发布，不要要求应用修改 `vendor/` 中的 SDK。

## 2. 强制上下文

任何代码或文档改动前，依次读取：

1. 仓库根目录 `AGENTS.md`。
2. `.agents/skills/yuinijika/SKILL.md`。
3. 写码时读取 `.agents/skills/yuinijika/coding-style.md`。
4. 写技术文档时读取 `.agents/skills/yuinijika/docs-style.md`。
5. 本文档和本次改动涉及的线上 API、Plugins 页面。

线上文档是公共 API 和用户行为的事实来源。不要依据旧聊天、旧草稿、发布说明或本地缓存猜测参数、返回值、权限或平台支持。

## 3. 线上文档读写

Kasumi 文档统一通过仓库工具读写：

```bash
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/`。
- 单篇上限 4 MiB。
- 正式提交必须提供 `--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。审核通过后重新拉取页面，确认线上内容已经生效。

## 4. 事实来源

| 路径 | 职责 |
|---|---|
| `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` |

## 5. 核心目录

| 路径 | 职责 |
|---|---|
| `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 独立官网工程 |

## 6. 不可破坏的约束

- `protocol/commands.json` 是命令契约的唯一事实来源。
- 权限、插件和错误码必须分别与 `permissions.schema.json`、`plugins.json`、`errors.json` 及对应 schema 保持一致。
- 生成文件只通过生成器更新，禁止手工补命令、错误码或类型。
- `version.json` 是版本元数据的唯一来源。不要在 CLI、原生工程、README 或发布脚本中新增硬编码版本号。
- 平台的命令支持必须显式声明。协议矩阵、能力查询、双端实现和文档必须使用同一结论。
- URL、虚拟路径、外部 origin、下载大小、超时和取消语义属于安全边界，校验必须留在宿主服务层。
- 多 WebView 状态必须按窗口隔离。不要用进程级单例覆盖路由、事件、下载取消或生命周期状态。
- 注入的 Host Services 由创建它的 Activity、Application 或宿主所有者关闭。单个 WebView 销毁不能关闭共享服务。
- 生成的用户项目只能消费发布 SDK 和平台适配层，不能复制框架 C++、Kotlin 或实现源码。
- 用户应用构建和打包产物进入 `.ksm/dist/`，开发缓存进入 `.ksm/dev/`，框架发布附件进入 `.ksm/release/`。
- 临时内容只放 `.tmp/`，禁止创建或恢复 `.workbuddy/`。
- 工作树可能有用户未提交改动。不要回退、覆盖或重排与当前任务无关的修改，也不要运行全仓格式化器。

## 7. 协议与契约变更

1. 更新 `protocol/commands.json`，补齐参数、返回值、平台、权限、`since` 和行为说明。
2. 按需更新 `permissions.schema.json`、`plugins.json`、`errors.json` 和 schema。
3. 更新 `protocol/README.md` 的平台矩阵和命令归属。
4. 运行 `pnpm validate:protocol`。
5. 运行 `pnpm codegen`，禁止直接编辑生成文件。
6. 检查生成差异只包含预期契约。

不要在协议尚未确定时先改 C++ 或 Kotlin，否则命令元数据、权限和前端类型会分叉。

## 8. 前端桥接与插件包

1. 在 `frontend/src/api/` 增加或修改模块 API，使用共享 guard 校验参数。
2. 在 `frontend/src/index.ts` 挂载到 `KSM` 根入口，并导出公开类型。
3. 更新 `packages/kasumi-bridge` 的公共入口和类型，不复制生成契约。
4. 更新对应 `packages/kasumi-plugin-*` 的包装、README 和平台能力过滤。
5. 运行 `pnpm typecheck` 和 `pnpm test:contract`。
6. 仅当包内容或导出变化时运行 `pnpm test:packages`。

请求 ID、超时、取消、重载和迟到响应属于桥接层职责。不要在业务插件里各自实现一套。

## 9. Windows

1. 在 `windows/src/plugins/` 注册插件和命令，从生成契约读取命令名。
2. 把网络、文件、URL、DPI、窗口和系统调用放到 `windows/src/platform/` 服务层。
3. 在 `ksm_plugin_registry` 和 `ksm_router` 中保持命令发现与分发一致。
4. 所有 UI 操作回投到拥有窗口的线程，所有请求支持超时、取消和销毁后迟到响应抑制。
5. 多窗口实例共享服务时确认所有权；单窗口关闭不能销毁共享 Host Services。
6. 增加策略、边界、并发和资源清理测试，再运行仓库定义的 Windows 构建与 CTest。

WebView2 默认使用系统 Evergreen Runtime。只有用户明确要求时才生成或打包 `WebView2Loader.dll`。

## 10. Android

1. 在 `android/kasumi/src/main/java/dev/kasumi/app/bridge/` 增加插件、命令和 Host Services 方法。
2. 通过 `windowId` 路由请求、事件、下载和取消，不使用覆盖式全局单例。
3. 导航只接受生产 `https://app.local` 和显式启用的开发 origin。
4. `close()` 只注销当前窗口；Activity 或 Application 管理 Host Services 生命周期。
5. `onTrimMemory` 只影响当前窗口，不要取消其他窗口的下载或暂停全局 WebView 计时器。
6. 覆盖旋转、Activity 销毁、超时取消竞态和迟到响应。
7. 外部链接只能通过 `shell.openExternal` 和精确 origin 白名单打开。
8. 运行对应 Gradle JVM 测试，并按任务要求执行 instrumentation 构建或设备测试。

## 11. CLI、模板与产物

1. 配置字段先进入 `protocol/kasumi.config.schema.json` 和 `packages/kasumi-cli/src/config.mjs`。
2. 用户应用构建和打包进入 `.ksm/dist/`，开发状态进入 `.ksm/dev/`，框架维护者发布附件进入 `.ksm/release/`。
3. 平台参数、默认值、帮助文本和 README 必须使用同一语义。
4. 模板从发布 SDK 消费框架，不复制框架原生源码。
5. 模板只保留应用代码、配置和最小平台适配文件。
6. 修改初始化器或模板后运行 `pnpm test:tarballs`，不要只检查模板静态文件。
7. 版本号从 `version.json` 读取。

## 12. 文档同步

公共行为变化后，先读取当前线上 MDX，再更新本地实现或文档。

用户要求同步文档时：

1. 用 `pnpm ksm docs pull <path>` 拉取目标页和相邻索引到 `.tmp/kasumi-docs/`。
2. 基于当前版本编辑，不覆盖其他代理的并发修订。
3. 检查 frontmatter、链接、命令数量、平台矩阵和示例。
4. 运行 `pnpm ksm docs push <file> --path <path> --note <note> --dry-run`。
5. diff 通过后加 `--yes` 提交修订，并记录返回的 uuid 与状态。
6. 用 `pnpm ksm docs status <uuid>` 跟踪审核；通过后再次 `pull` 确认线上内容。

不得提前把未发布的 SDK、npm 包或 Release 描述为已上线。必须区分本地构建、CI 构建、Release 资产和 npm registry 已验证状态。

## 13. 验证矩阵

| 改动 | 最低验证 |
|---|---|
| 协议、权限、错误码、生成契约 | `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`、开发服务器、模拟器或完整发布构建。涉及发布、打包或真实环境门槛时，明确区分已执行验证和仍需人工验证的项目。

## 14. 发布

1. 只修改 `version.json` 更新版本。
2. 重新生成平台版本头、Gradle 元数据、npm manifest 和发布清单。
3. 构建框架 SDK、应用包和示例包，确认目录分别位于 `.ksm/release/kasumi/`、`.ksm/release/app/`。
4. 验证 Windows ZIP、Android APK、签名和校验和。
5. 先发布 GitHub Release，再发布依赖它的 npm 包。
6. 在干净目录执行在线初始化、构建和 `doctor`。
7. 所有公开资产可访问后再更新线上发布状态。

发布失败时增加补丁版本，不覆盖已公开的 npm 版本或移动已发布标签，除非用户明确要求并理解缓存和下游影响。

## 15. 完成标准

- 线上文档和仓库协议没有互相矛盾。
- 命令元数据、权限、错误码和前端类型来自同一来源。
- 所有声明的适用平台都有实现，平台不支持项有明确错误和文档。
- 生成契约无未提交漂移，测试覆盖新增边界。
- 没有把框架源码复制进生成应用，也没有新增硬编码版本号。
- 临时文件、构建垃圾和 `.workbuddy/` 没有进入工作树。