qtype

English | 中文

Markdown 驱动的打字练习工具。 用 Markdown 写卡片,qtype 让你把它打一遍来内化。6 种卡片形态(word / sentence / article / snippet / qa / code)覆盖从背单词到练代码到抄诗的所有场景。

快速开始

mkdir my-deck
npx @qnroa/qtype init my-deck --lang zh
cd my-deck
# `qtype init` 会在 material/ 下放 6 张类型模板 —— 直接改任意一张,
# 或复制一份重命名当新卡组:
#   material/word.md  sentence.md  article.md  snippet.md  qa.md  code.md
npx @qnroa/qtype publish build
npx @qnroa/qtype publish serve    # http://localhost:4000

需要 Node ≥ 20。

卡片格式

一个文件 = 一副卡组,type(在 frontmatter)决定形态。最简单的例子 —— 一张 sentence 卡:

---
title: 热身
type: sentence
tags: [热身]
---

# The quick brown fox jumps over the lazy dog.
### 英文全字母句。

用 # H1 分卡。sentence 卡用 H2 放音标、H3 放翻译。其他类型:

| type | 打字目标 | 附加项 | |---|---|---| | word | H1 单词 | H2 音标 · H3 释义 · H4 图片 | | sentence | H1 句子 | H2 音标 · H3 翻译 · H4 图片 | | article | H1 之下正文 | 内嵌图片自动抽出 | | snippet | H1 之下正文 | 居中排版(诗句/格言) | | qa | ## A 块 | ## Q 题干(完整 markdown) | | code | ## A 里的 fenced 块 | 可选 Shiki 语法高亮 |

完整规范:templates/zh/QTYPE.md(会拷进每个新仓库)。深度参考:docs/zh/material-types.md。

富渲染(展示侧,不参与打字):Mermaid 流程图(构建时预渲染)、KaTeX 数学公式($…$ / $$…$$,懒加载)、Shiki 代码高亮。详见 material-types.md。

CLI

| 命令 | 作用 | |---|---| | qtype init [dir] | 初始化资料仓库(QTYPE.md + 6 种类型起手模板 + .qtype/) | | qtype check [dir] | 校验卡片(只读,错则退出码 1) | | qtype content search <q> | 全文搜索,支持 --tag / --type / --json | | qtype publish build | 拼装静态站到 dist/(mermaid 预渲染、可选 AES-GCM 加密) | | qtype publish serve | 本地 :4000 预览 | | qtype publish init | 写 .gitignore(加 --ci github 写 Pages workflow) | | qtype publish password set | 密码保护(argon2id → AES-256) | | qtype pack | 打包资料为 .tar.gz | | qtype config get/set/list | 双层配置(~/.config/qtype/ + <repo>/.qtype/) | | qtype repo new / sync | 新建仓库 / 补齐约定 |

每个命令 qtype <cmd> --help 看完整选项。完整列表:docs/zh/cli-reference.md。

密码保护

qtype publish password set                        # 交互输入
QTYPE_PUBLISH_PASSWORD=hunter2 qtype publish build

内容用 AES-256-GCM 客户端加密,argon2id 派生的密钥缓存在浏览器 sessionStorage(同 tab 刷新不再问密码)。威胁模型:防止拿到 URL 的路人随便看,不防拿到 dist 后离线暴力破解 KDF 的高动机攻击者。

命名

qtype = Q + type(问题的打字)—— 把 MD 转成可打字复现的卡片

文档

• Getting Started —— 5 分钟教程
• 撰写指南 —— material/*.md 的快速入门
• Material 类型详解 —— 6 种类型的深度参考
• CLI 简介 —— 所有命令 + 配置键
• Settings 参考 —— 所有用户可见的设置项
• 部署指南 —— GitHub Pages / Cloudflare / nginx
• 快捷键 —— 按键绑定 + 重绑
• 打字规则 —— ignoreCase / retryOnFail / 等
• CHANGELOG.zh.md —— 版本历史

开发

npm install
npm run dev:view         # http://localhost:5173(view 端热开发)
npm test                 # vitest
npm run build            # CLI(tsc)
npm run build:view       # SPA bundle(vite)
npm run build:all        # 一起
npm run lint             # tsc --noEmit(cli + view 两份 tsconfig)

让 dev server 指向别的 material 目录:

QTYPE_DEV_MATERIAL=templates/zh/material npm run dev:view

目录结构

qtype/
├── src/
│   ├── core/       # 纯逻辑,无 IO(parser / typing engine / keystroke / encrypt)
│   ├── view/       # React SPA(TanStack Router + Vite)
│   ├── store/      # 持久化(KvStore + JsonStorage / MemoryStorage / BrowserStorage)
│   └── cli/        # commander + registry/mount 模式
├── templates/{zh,en}/    # init 时拷进用户仓库
├── examples/{zh,en}/     # smoke test + dev 用的真实形状仓库
├── docs/                 # 这份文档
└── vite.config.ts        # 输出到 dist/view

发布结构:

• dist/cli/ — CLI 可执行(bin: qtype)
• dist/core/ — 类型复用(exports "./core")
• dist/view/ — 预编译 SPA;publish build 时拷到用户 dist/

License

Apache-2.0 —— 详见 LICENSE。