# typer
**Repository Path**: feiku/typer
## Basic Information
- **Project Name**: typer
- **Description**: 一款免费在线打字练习工具软件，无需注册，电脑、iPad 打开网页就能练，也可以安装到桌面或主屏幕。支持实体键盘与触屏输入、自定义练习文本、PWA 离线使用，还可以通过插件创造自己的课程与玩法。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-07-29
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# KeyPilot Typer
### 一个父亲为女儿做的免费在线打字练习工具
无需注册，电脑、iPad 打开网页就能练，也可以安装到桌面或主屏幕。
支持实体键盘与触屏输入、自定义练习文本、PWA 离线使用，还可以通过插件创造自己的课程与玩法。
### [🚀 在线体验：https://typer.h5ds.com](https://typer.h5ds.com/)
[在线体验](https://typer.h5ds.com/) · [项目初衷](#为什么做-keypilot-typer) · [核心能力](#核心能力) · [PWA 安装](#安装为应用pwa) · [快速开始](#快速开始) · [插件开发](#插件生态) · [参与贡献](#参与贡献)
> **KeyPilot Typer 不是一场打字测速，而是一套可以持续练习、持续反馈、持续扩展的输入技能训练系统。**
## 为什么做 KeyPilot Typer
这个项目的起点，不是一个商业计划，也不是为了验证某项技术，而是一个很具体的愿望：**我想给自己的小女儿找一款免费、好用，而且随时随地都能练习的打字软件。**
我们以前也用过很多人熟悉的金山打字通。它承载了不少人的打字启蒙，但需要安装在电脑上，到了 Apple iPad 这类设备上就不方便使用。我希望孩子不必被某一台电脑绑定，拿起身边的设备、打开网页，就能继续昨天的练习。
后来我发现了 `typer.fun`。它的体验确实很好，也证明了“在网页里认真练习打字”这件事完全可行；但它需要付费，不符合我想为孩子准备一个可以长期、自由使用的免费工具的初衷。
于是，我借助 AI，以 **Vibe Coding** 的方式，用几天时间从零开始，自己“手搓”出了 KeyPilot Typer。
它从第一天起就围绕几件朴素的事情设计：
- **打开网页就能用**：无需强制安装客户端；需要时也能以 PWA 添加到桌面或主屏幕。
- **电脑和 iPad 都能练**：适配不同尺寸与终端，既支持实体键盘，也可以直接点击或触摸屏幕上的虚拟键盘。
- **网络不好也能继续**：首次在线访问完成缓存后，可以离线进入课程、自由练习和游戏。
- **永久免费**：每个孩子、家长和学习者都可以无门槛使用。
- **练什么可以自己决定**：在文本库中直接录入自己的内容，也可以通过内容插件制作完整课程。
- **玩法不由作者决定上限**：键盘、指法、课程、声音、主题、特效和游戏都尽量抽离为插件，任何人都可以开发自己的插件并集成进来。
KeyPilot Typer 最初是我为女儿做的小工具，现在我把它以 MIT 协议开放出来，希望它也能帮助更多正在学习打字的孩子和成年人，并在社区的创造力下生长出更多课程与玩法。
## 它解决了什么问题
| 常见痛点 | KeyPilot Typer 的做法 | 带来的改变 |
|---|---|---|
| 传统打字软件需要安装，只能在特定电脑上使用 | 采用响应式 Web 应用，适配电脑与 iPad | 有浏览器就能练，不再被设备绑定 |
| 浏览器书签不够直观，断网时网页又无法打开 | 支持安装为 PWA，并缓存完整应用资源 | 像普通应用一样从主屏幕启动，缓存后可离线练习 |
| iPad 等设备不一定随时连接实体键盘 | 虚拟键盘支持点击和触摸输入，也能与实体键盘同时使用 | 没有外接键盘时也可以熟悉键位和完成练习 |
| 体验好的在线工具往往需要持续付费 | 核心功能永久免费，并采用 MIT 协议开源 | 个人、家庭和学校都可以无门槛使用 |
| 固定练习内容不一定适合自己的学习目标 | 内置自定义文本库，并支持 `content-pack` 内容插件 | 临时练一段文字或制作整套课程都可以 |
| 一上来就追求 WPM，错误动作被反复强化 | 课程设置准确率与速度建议，先定位、再扩键、后提速 | 让速度建立在稳定动作之上 |
| 只显示对错，不告诉用户该怎么按 | 同步高亮目标键、主按手指、修饰键与长按状态 | 每一次输入都有可执行的动作提示 |
| 练习内容零散，没有清晰成长路线 | 16 个渐进阶段，从 F/J 定位走向真实输入场景 | 知道现在练什么，也知道下一步练什么 |
| 重复抄写容易失去兴趣 | 六种内置训练游戏，包含难度、连击、成绩与成就 | 把准确率和节奏转化为即时挑战 |
| 功能写死，课程和玩法难以复用 | 课程、键盘、指法、游戏等能力全部插件化 | 可以围绕学校、语言、职业或设备建立新内容 |
## 核心能力
### 打开网页，随时随地练习
KeyPilot Typer 是一个本地优先的响应式 Web 应用。无需下载安装包或创建账号，在电脑、iPad 等终端访问在线地址即可开始练习：
### [立即免费体验 → https://typer.h5ds.com](https://typer.h5ds.com/)
在有实体键盘时可以正常盲打；没有外接键盘时，也可以直接点击或触摸页面上的虚拟键盘。两种输入方式可以同时使用，并可在“练习设置 → 点击 / 触摸输入”中随时开启或关闭。
练习进度、设置、自定义文本和游戏成绩默认保存在浏览器本地。你也可以通过 Docker 或静态托管部署一份完全属于自己的版本。
### 可安装、可离线的 PWA
KeyPilot Typer 同时是一款渐进式 Web 应用（Progressive Web App）：
- 可以安装到 iPad 主屏幕、Android 主屏幕以及 Windows/macOS 桌面。
- 安装后以独立窗口全屏运行，不必每次从浏览器标签页进入。
- 首次在线打开会缓存应用外壳和当前构建资源，之后断网仍可进入课程、自由练习和游戏。
- 课程进度、自定义文本、设置与游戏成绩继续保存在设备本地。
- 页面重新回到前台时会检查更新，运行期间也会定时检查；新版本就绪后自动接管并刷新。
- Manifest 提供“自由练习”“键位课程”和“游戏实验室”三个快捷入口。
安装 PWA 是可选的，不安装也可以继续通过网页使用。具体步骤与部署要求见[安装为应用（PWA）](#安装为应用pwa)。
### 一条真正循序渐进的训练路径
内置课程覆盖 **16 个训练阶段、近百节练习**，从最基础的 F/J 定位点开始，逐步扩展到：
- 基准排、上排、下排与三排全字母协同
- 数字行、Shift、大小写与常用符号
- 英文单词、短句与连续文本
- 拼音和中文输入节奏
- 速度、准确率、耐力与真实格式综合挑战
每个阶段都包含学习目标、建议准确率、建议 WPM、预计时长和动态技巧提示。课程内容由 `content-pack` 插件提供，可以替换或扩展为其他语言、专业词汇、考试训练与无障碍课程。
### 练什么，由你决定：自定义文本库
除了内置课程和随机自由练习，练习页面还提供了可直接使用的自定义文本库：
1. 进入“键位练习”，打开顶部的“文本库”。
2. 点击“新增文本”，填写标题并粘贴或输入练习内容。
3. 点击“保存并开始”，立即使用这段内容进行练习。
4. 后续可以从文本库快速切换、预览、编辑或删除已保存内容。
自定义文本会保存在当前浏览器中。你可以用它练习孩子正在学习的单词和课文、准备考试内容、代码片段，或任何自己真正需要输入的文字。
如果希望把内容做成可分享、可复用的完整课程，还可以使用 `content-pack` 内容插件，完整定义课程阶段、练习目标、提示文案和训练文本，例如：
- 为孩子录入正在学习的英语单词和课文
- 制作拼音、数字、符号或考试专项训练
- 加入编程关键字、代码片段和专业术语
- 为不同年龄、语言或无障碍需求设计独立课程
内容扩展不需要侵入核心页面；把它做成插件，就可以独立维护、分享和复用。
### 随时预览完整练习文本
练习界面默认聚焦当前行和下一行，减少长文本带来的视觉干扰；当你想先了解全文或回顾整体结果时，可以打开完整文本预览：
- 练习过程中，点击当前行或待输入行即可查看本次练习的全部文本。
- 预览窗口同步显示已完成字符数和整体进度。
- 已正确输入、输入错误、当前位置和待输入内容使用不同状态标记。
- 完成练习后，点击“本次练习完整结果”可以再次查看全文与错误位置。
- 再次点击预览、点击窗口外部或按 `Esc` 即可关闭，并返回当前练习。
预览打开期间会暂停接收练习输入，避免查看全文时误触键盘影响成绩。
### 看得见的指法反馈
练习时，系统会把“应该按什么”转化为直观动作：
- 高亮当前目标键与实际按键
- 标记负责主键和修饰键的手指
- 展示 Shift 等修饰键的持续按住状态
- 处理 Caps Lock、Num Lock 和双值字符
- 支持点击或触摸虚拟键盘输入，实体键盘仍可同时使用
- 通过虚拟手、声音与动效提供即时反馈
- 支持关闭动画、隐藏键盘和调整提示强度
### 面向长期训练的数据闭环
KeyPilot Typer 不只保留一次测试结果，还会持续记录：
- 实时 WPM、准确率与用时
- 每节课程的完成状态和历史最佳成绩
- 每日训练时长与自定义目标
- 按键级正确/错误统计与薄弱键提示
- 游戏最高分、最高连击、难度进度与成就
设置、课程进度和游戏成绩默认持久化在浏览器本地，无需账号或后端服务即可开始训练。
### 六种游戏化训练
| 游戏 | 训练重点 |
|---|---|
| 键帽地鼠 | 目标扫描与单键反应 |
| 极速竞键 | 稳定输入、速度与连续命中 |
| 字母降落 | 视觉搜索与输入优先级 |
| 单词拼图 | 字母顺序与英文单词输入 |
| 轨道防线 | 威胁判断与快速切换目标 |
| 星舰截击 | 字母识别、连续输入与节奏 |
游戏与第三方扩展使用同一套插件协议，并共享难度、成绩、成就、音效和动态反馈能力。
### 多键盘与个性化体验
- 104、98、87、WinBook、MacBook 与 Apple 妙控键盘等物理模型
- QWERTY、Dvorak、Colemak 键位映射
- 虚拟键盘与实物图片键盘皮肤
- 浅色/深色主题、声音包、打字特效与虚拟手
- 左右手修饰键习惯、手部透明度、尺寸与键盘亮度设置
- 键盘可访问性与 `prefers-reduced-motion` 支持
## 快速开始
### 本地运行
环境要求：
- Node.js 18+
- npm 9+，或 Yarn 1.x
```bash
# 克隆或下载仓库后进入项目目录
cd typer
npm install
npm run dev
```
打开 [http://localhost:5173](http://localhost:5173)。
如果使用 Yarn：
```bash
yarn
yarn dev
```
### 常用命令
```bash
npm run dev # 启动开发服务器
npm run lint # ESLint 静态检查
npm run test:run # 运行单元与组件测试
npm run test:coverage # 生成测试覆盖率
npm run build # 类型检查并构建生产版本
npm run verify:pwa # 校验 PWA manifest、图标、版本和离线缓存产物
npm run test:e2e # 运行 Playwright 端到端测试
npm run preview # 本地预览生产构建
```
### 安装为应用（PWA）
生产构建包含 Web App Manifest、安装图标、Service Worker、离线缓存和自动更新能力。部署到 HTTPS 站点后，可以点击页面顶部的“安装应用”，或使用浏览器菜单安装到设备主屏幕或桌面：
| 平台 | 安装方式 |
|---|---|
| iPad / iPhone | 使用 Safari 打开站点，点击“分享” → “添加到主屏幕” |
| Android | 使用 Chrome 打开站点，选择“安装应用”或“添加到主屏幕” |
| Windows / macOS | 使用 Edge 或 Chrome，点击地址栏中的安装按钮 |
> iPad/iPhone 建议通过 Safari 添加到主屏幕。PWA 首次加载与首次缓存需要联网；离线能力从缓存成功后开始生效。
安装后可以使用 `standalone` 模式独立运行。Service Worker 会预缓存当前构建的应用外壳和静态资源，并为同源导航提供离线回退；断网时仍可进入课程、自由练习和游戏。
应用每 30 分钟以及每次重新回到前台时检查更新。新版本 Service Worker 激活后会清理旧版本缓存、接管页面并自动刷新，避免设备长期停留在旧资源上。
每次执行 `npm run build` 或 `yarn build`，`package.json` 的补丁版本号会自动递增，
同时同步 `package-lock.json` 与 `public/app-version.json`。例如：
```text
0.0.0 -> 0.0.1 -> 0.0.2
```
构建结束后还会自动校验 manifest、Service Worker、版本文件和 192/512 像素安装图标。
自托管 PWA 时请确保：
- 生产站点使用 HTTPS（`localhost` 开发环境除外）。
- SPA 路由能够回退到 `index.html`。
- `sw.js`、`manifest.webmanifest` 和 `app-version.json` 不使用长期强缓存。
- 带内容哈希的 JS、CSS 和图片等静态资源可以使用长期不可变缓存。
仓库内的 [`nginx.conf`](./nginx.conf) 已包含上述 SPA 回退、PWA 入口重验证和静态资源缓存规则。
如果 HTTPS 由外层 Nginx 反向代理，请勿添加只有 `expires`、却没有 `proxy_pass`
的图片正则 `location`。该配置会抢先匹配 PNG 请求并在外层服务器本地查找文件，
导致 PWA 图标和练习图片返回 404。建议让全部请求统一转发给容器：
```nginx
location / {
proxy_pass http://localhost:8820;
}
```
若必须保留图片正则块，也需要在块内配置相同的 `proxy_pass`。
### Docker 部署
```bash
docker build -t keypilot-typer:latest .
docker run -d --name keypilot-typer -p 8080:80 keypilot-typer:latest
```
打开 [http://localhost:8080](http://localhost:8080)。
也可以直接使用 Docker Compose：
```bash
docker compose up -d --build
```
默认访问地址为 [http://localhost:8820](http://localhost:8820)。
## 从专业角度看：训练设计
KeyPilot Typer 的课程遵循三个原则：
1. **准确优先**：没有稳定的动作模式，单纯提速只会放大错误。
2. **渐进负荷**：每次只增加有限的新键位或新组合，降低认知负担。
3. **及时反馈**：把结果反馈前移到每一次触键，让用户立即修正动作。
课程并非简单按字母顺序排列，而是围绕“定位 → 同排协作 → 跨排伸展 → 修饰键控制 → 语言应用 → 综合输入”组织。阶段检查与应用练习穿插在键位学习之间，使练习从孤立动作逐步迁移到真实输入。
| 训练区间 | 核心目标 | 建议门槛 |
|---|---|---|
| 阶段 01–04 | F/J 定位与完整基准排 | 90%–92% 准确率 |
| 阶段 05–10 | 上下排扩展与全字母协同 | 93%–94% 准确率 |
| 阶段 11–14 | 数字、词句、大小写与符号 | 94%–95% 准确率 |
| 阶段 15–16 | 中文输入节奏与综合挑战 | 95%–96% 准确率 |
## 从技术角度看：可扩展的训练平台
KeyPilot Typer 将稳定的输入判定、状态持久化和插件运行时放在核心层，把容易变化的产品能力拆成插件。这样既能保持训练逻辑一致，也能让社区独立贡献内容和体验。
```mermaid
flowchart LR
P["插件目录
src/plugins/*/plugin.ts(x)"] --> D["Vite 自动发现"]
D --> V["协议校验与依赖排序"]
V --> R["PluginRegistry"]
R --> H["核心运行时宿主"]
H --> UI["课程 / 练习 / 设置 / 游戏大厅"]
UI --> PWA["Web App Manifest / Service Worker"]
PWA --> DEVICE["浏览器 / 桌面 / 主屏幕 / 离线运行"]
SDK["plugin-sdk 公共 API"] --> P
S["隔离的设置、课程进度与游戏成绩"] --> H
```
### 技术栈
- **前端**：React 18、TypeScript 5、Vite 5
- **路由与状态**：React Router、Zustand
- **样式**：Tailwind CSS、项目级 CSS
- **质量保障**：ESLint、Vitest、Testing Library、Playwright
- **PWA**：Web App Manifest、Service Worker、版本化预缓存与自动更新
- **部署**：Docker、Nginx、静态托管
### 核心设计
- **输入规则独立**：字符、物理按键、锁定键和修饰键逻辑集中处理。
- **插件注册表**：统一完成 manifest 校验、依赖排序、ID 冲突和路由冲突检查。
- **稳定 SDK 边界**：第三方插件只依赖 `plugin-sdk`，不直接耦合页面或 Zustand Store。
- **错误隔离**：单个插件渲染失败不会直接拖垮整个应用。
- **版本化设置**：插件可以声明设置字段与迁移逻辑。
- **本地优先**：当前版本无需后端，适合静态托管、私有部署与离线场景。
- **PWA 构建门禁**：构建后校验 Manifest、Service Worker、版本文件和安装图标，缓存版本与应用版本保持一致。
## 插件生态
当前 Plugin API v1 提供十类可组合能力：
| Capability | 可以扩展什么 |
|---|---|
| `keyboard-model` | 物理键盘区域、行列、键宽、指示灯和平台 |
| `keymap` | 字符到物理主键、修饰键的解析规则 |
| `finger-strategy` | 主键与修饰键对应的手和手指 |
| `keyboard-skin` | 虚拟键盘或实物图片键盘外观 |
| `hand-visualizer` | 虚拟手、手指标记与动作反馈 |
| `sound-pack` | 正确、错误和其他输入事件音效 |
| `typing-effect` | 键帽、手指、练习区与全屏特效 |
| `content-pack` | 课程阶段、练习、目标和自由文本 |
| `theme` | 主题类名与 CSS 变量 |
| `game` | 游戏卡片、路由、难度、成绩与成就 |
当前采用“可信源码插件”模式：
1. 将包含 `plugin.ts` 或 `plugin.tsx` 的目录放入 `src/plugins/`。
2. 重启开发服务器，或重新执行生产构建。
3. Vite 自动发现插件，注册表完成协议校验、依赖排序与贡献项注册。
一个可复制的最小插件模板位于 [`examples/plugin-template`](./examples/plugin-template/README.md)。
### 插件开发文档
| 文档 | 内容 |
|---|---|
| [插件文档导航](./docs/plugins/README.md) | 推荐阅读顺序和能力索引 |
| [五分钟创建插件](./docs/plugins/getting-started.md) | 目录、清单、安装、依赖和最小示例 |
| [架构与生命周期](./docs/plugins/architecture.md) | 发现、校验、注册、选择、渲染和错误隔离 |
| [能力开发手册](./docs/plugins/capabilities.md) | 十类贡献项的接口、约束和示例 |
| [课程内容插件](./docs/plugins/content-packs.md) | 课程阶段、练习、目标、文案与内容设计 |
| [游戏插件](./docs/plugins/game-plugins.md) | 路由、难度、进度、成就、设置和完整样例 |
| [设置、存储与迁移](./docs/plugins/settings-and-migrations.md) | 声明式设置、版本与数据迁移 |
| [测试、发布与插件商城](./docs/plugins/testing-and-marketplace.md) | 契约测试、质量门禁、安全与商城演进 |
> 当前插件适用于可信开源仓库和自托管构建。远程下载、数字签名、权限隔离、自动更新与恶意代码扫描仍属于未来的安装器/商城阶段，请勿直接执行来源不明的远程 JavaScript。
## 项目结构
```text
src/
├─ app/ # 应用组合根与插件目录发现
├─ core/
│ ├─ audio/ # 声音播放宿主
│ ├─ games/ # 游戏进度公共能力
│ ├─ input/ # 字符、物理键与修饰键规则
│ └─ plugins/ # 协议、校验、注册表与运行时宿主
├─ plugin-sdk/ # 第三方插件唯一公共依赖入口
├─ plugins/ # 内置插件与本地安装插件
├─ pwa.ts # Service Worker 注册、更新检查与版本接管
├─ components/ # 通用 UI 组件
├─ hooks/ # 应用用例 Hook
├─ pages/ # 页面与路由
└─ stores/ # 设置、课程、输入和游戏状态
public/
├─ manifest.webmanifest # PWA 名称、显示模式、图标与快捷入口
├─ app-version.json # 当前构建版本与构建时间
└─ icons/ # PWA 与 Apple Touch 安装图标
scripts/
├─ bump-version.mjs # 构建前递增补丁版本
└─ verify-pwa-build.mjs # 构建产物完整性校验
docs/plugins/ # 插件开发文档
examples/plugin-template/ # 最小插件模板
tests/ # 单元、组件与端到端测试
```
## 路线图
- [x] 渐进式课程、自由练习与本地进度
- [x] 多键盘模型、键位映射和实时指法提示
- [x] 可安装 PWA、离线缓存与自动更新
- [x] 六种插件化训练游戏
- [x] Plugin API v1、公共 SDK、契约测试与开发文档
- [ ] 更多语言、专业场景和无障碍课程包
- [ ] 标准化插件包与 CLI/桌面安装器
- [ ] 插件签名、哈希校验、权限声明与版本回滚
- [ ] 社区插件目录与自动兼容性检查
## 参与贡献
欢迎提交 Issue、功能建议、课程内容、键盘模型、主题、声音、游戏或代码改进。
贡献前请注意：
- 核心改动应聚焦协议、运行时宿主、安全与跨插件基础设施。
- 新键盘、新内容、新音效、新特效和新游戏优先以插件实现。
- 新贡献项 ID 必须以插件 ID 作为命名空间。
- 提交前请运行 lint、测试、构建和端到端冒烟测试。
- 修改 PWA、部署或构建流程后，请额外运行 `npm run verify:pwa`。
- 动画必须支持 `prefers-reduced-motion`，交互控件必须可通过键盘操作。
- 请确保图片、音频、字体和课程内容具有兼容的开源授权。
建议的贡献流程：
1. Fork 仓库并创建功能分支。
2. 完成实现、文档与必要测试。
3. 运行质量检查并确认没有破坏已有训练流程。
4. 提交 Pull Request，说明动机、行为变化和验证方式。
## License
本项目采用 [MIT License](https://opensource.org/license/mit/) 开源。你可以自由使用、复制、修改和分发本项目，但请保留原始版权与许可声明。
---
如果 KeyPilot Typer 对你有帮助，欢迎 Star、分享，或一起为它增加新的课程与玩法。
**让每一次敲击，都成为更好的肌肉记忆。**