@qnroa/qtype 0.0.2 → 0.0.3

package/docs/zh/authoring.md

@@ -1,112 +1,116 @@
 # 撰写 material 文件
 
-English: [authoring.md](../en/authoring.md)
+English: [authoring.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/authoring.md)
 
-`material/*.md` 的快速入门。权威规范见
-[`templates/zh/QTYPE.md`](../../templates/zh/QTYPE.md)
-（`qtype init --lang zh` 时拷到新 repo）。有疑问先查那份。
+`material/*.md` 的快速入门。深度参考见
+[material-types.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/material-types.md);LLM 协作用的完整规范见
+[`templates/zh/QTYPE.md`](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=templates/zh/QTYPE.md)(`qtype init
+--lang zh` 时会拷到新 repo)。有疑问先查那两份。
 
 ## 文件位置
 
 ```
 my-deck/
-├── QTYPE.md              # 规范（init 时自动拷贝；留着）
-├── index.md              # 面向人的目录（可选）
+├── QTYPE.md              # 规范(init 时自动拷贝;留着,给 LLM 用)
+├── index.md              # 面向人的目录(可选)
 ├── material/
-│   ├── example.md
-│   ├── javascript-basics.md
-│   └── english-vocab.md
+│   ├── word.md           # 6 种类型的入门模板
+│   ├── sentence.md       # 由 qtype init 自动拷入
+│   ├── article.md
+│   ├── snippet.md
+│   ├── qa.md
+│   └── code.md
 └── .qtype/
     └── config.json       # 单 repo 配置
 ```
 
-一个 `.md` 文件 = 一副卡组。
+**一个 `.md` 文件 = 一副卡组,整个文件一个 `type`**。想加新卡组,
+复制一个类型模板重命名即可。
 
-## 卡片形状
+## 六种类型
 
-每张卡有一个问题和一个答案，用 `## Q:` / `## A:` 标题分隔。同一文件里
-的多张卡用 `\n\n---\n\n`（独占一行的 `---`，前后各留空行）分隔。
+qtype 支持 6 种 material 类型,每种有自己的 Markdown 结构:
 
-```markdown
----
-tags: [js, basics]
-type: normal
----
-
-## Q:
+| type | 打字目标 | 结构 |
+|---|---|---|
+| `word` | H1 单词本身 | H1 + 可选 H2 音标 / H3 释义 / H4 图片 |
+| `sentence` | H1 整句 | 结构同 word |
+| `article` | H1 之下正文 | H1 是章节标题(不打),下方段落是目标 |
+| `snippet` | H1 之下正文 | 结构同 article,渲染时**居中排版**;适合诗句 / 格言 |
+| `qa` | `## A` 块 | H1 卡名, `## Q` 题干, `## A` 打字目标 |
+| `code` | `## A` 里的 fenced code block | 同 qa,但 A 里是代码块 |
 
-React 三大核心概念是什么？
+## 卡片切分
 
-## A:
+同一文件里的多张卡用 **`# H1`** 分隔 —— 每一个 H1 起一张新卡。**不用
+`---` 分割**。
 
-组件、props 和 state。
+## 举例
 
+**word:**
+```markdown
+---
+type: word
+tags: [example]
 ---
 
-## Q:
-
-`useState` 返回什么？
-
-## A:
+# apple
+## /ˈæp.əl/
+### 苹果
 
-一个 `[值, setter]` 的元组。
+# ephemeral
+## /əˈfem(ə)rəl/
+### 短暂的
 ```
 
-parser 先按 `---` 分割，再逐卡提取 Q、A、metadata。缺 Q 或 A 的卡片被
-静默丢弃（方便写占位）。
-
-## Frontmatter 字段
-
-文件顶部的 YAML frontmatter 对文件内每张卡都生效。如需单卡覆盖，把
-YAML fence 放到该卡上方（见规范）。
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `tags` | `string[]` | 自由形式；用于列表过滤 |
-| `type` | `normal \| word \| sentence` | 默认 `normal` |
-| `hint` | `none \| ghost` | 下方是否显示褪色目标 |
-| `difficulty` | `1..5` | 可选，信息用 |
-| `phonetic` | `string` | `type: word` 用 —— IPA / 拼音 |
-| `gloss` | `string` | `type: word` 用 —— 释义 |
-| `translation` | `string` | `type: sentence` 用 —— 目标语等价句 |
+**sentence:**
+```markdown
+---
+type: sentence
+tags: [example]
+---
 
-示例 —— 一张 `word` 卡：
+# The quick brown fox jumps over the lazy dog.
+### 英文全字母句。
+```
 
+**qa:**
 ```markdown
 ---
-type: word
-phonetic: /ˈklō-zhər/
-gloss: 捕获词法作用域的函数
+type: qa
+tags: [js]
 ---
 
-## Q:
+# 什么是闭包
 
-closure
+## Q
+用一句话解释闭包。
 
-## A:
-
-closure
+## A
+闭包是函数与它诞生时的词法作用域组合在一起。
 ```
 
-## 被打字的是什么？
+其余三种见 [material-types.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/material-types.md)。
+
+## 被打字的是什么?
 
-**答案**是用户要打的内容。Q 只做提示（不打）。代码块、行内代码、多行
-答案都支持 —— 打字引擎按归一化后的答案逐 codepoint 迭代。
+**答案侧**(见每种类型的「打字目标」列)是用户要打的内容。题干 / 音标 /
+释义只做展示,不打。所有字符必须 OS 键盘(含中文 IME)能敲得出来。
 
-引擎处理不了的字符（比如某些代理对 emoji）会出现在 `qtype check`
-输出里。发布前修掉或删掉。
+打字引擎处理不了的字符(某些代理对 emoji / 零宽字符 / 控制字符)会
+出现在 `qtype check` 输出里 —— 发布前修掉或删掉。
 
 ## 跑 `qtype check`
 
-发布前始终跑：
+发布前始终跑:
 
 ```bash
 qtype check
 ```
 
-它报告：
-- `material/` 目录不存在（致命）
-- 含无法打字字符的卡片（致命，附逐卡列表）
+它报告:
+- `material/` 目录不存在(致命)
+- 含无法打字字符的卡片(致命,附逐卡列表)
 
 退出码 0 = 可以安全发布。
 
@@ -117,15 +121,16 @@ qtype publish build
 qtype publish serve            # http://localhost:4000
 ```
 
-密码保护的卡组：
+密码保护的卡组:
 
 ```bash
 qtype publish password set     # 写入 repo 配置
 qtype publish build            # 出栈时加密 material
 ```
 
-## 完整规范在哪
+## 完整参考
 
-以上是 80% 的用法。少见场景（单卡 frontmatter 覆盖、准确的空白处理、
-分隔规则边界情形、跨文件引用）见
-[`templates/zh/QTYPE.md`](../../templates/zh/QTYPE.md)。
+- [material-types.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/material-types.md) —— 6 种类型的**深度**参考,
+  含解析器行为 / UI 布局 / 交互细节
+- [`templates/zh/QTYPE.md`](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=templates/zh/QTYPE.md) —— **LLM 协作
+  规范**,init 时自动拷入 repo,让 AI agent 直接按规矩生成 material

package/docs/zh/cli-reference.md

@@ -1,6 +1,6 @@
 # qtype CLI 简介
 
-English: [cli-reference.md](../en/cli-reference.md)
+English: [cli-reference.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/cli-reference.md)
 
 每个顶层命令的简单介绍。跑 `qtype <cmd> --help` 看完整选项。
 
@@ -12,69 +12,107 @@ English: [cli-reference.md](../en/cli-reference.md)
 | `-v, --version` | 显示版本 |
 | `--lang <zh\|en>` | 本次调用的 UI 语言 |
 
-语言优先级：`--lang` > `$QTYPE_LANG` > `~/.config/qtype/config.json` 里的
+语言优先级:`--lang` > `$QTYPE_LANG` > `~/.config/qtype/config.json` 里的
 `cli.lang` > 系统 locale。
 
 ---
 
-## `qtype init [dir]`
+## `qtype init [path]`
 
-在已有目录里搭起 material 仓库脚手架。`qtype repo sync` 的别名，形态一致。
+在已有目录里搭起 material 仓库脚手架。`qtype repo sync` 的顶层别名。
 
 ```bash
-qtype init                    # 当前目录
-qtype init my-deck --lang en  # 在 ./my-deck 下用英文模板
+mkdir my-deck && qtype init my-deck --lang zh
+qtype init                     # 当前目录
+qtype init my-deck --force     # 覆盖 qtype 管理的规范文件
+qtype init my-deck --dry-run   # 只打印计划,不写盘
 ```
 
-创建：`QTYPE.md`（撰写规范）、`AGENTS.md` / `CLAUDE.md` / `GEMINI.md`
-（指向 `QTYPE.md` 的软链）、`README.md`、`TODO.md`、`index.md`、
-`log.md`、含 example 的 `material/`、`.qtype/` 骨架。
+创建:`QTYPE.md`(撰写规范)、`AGENTS.md` / `CLAUDE.md` / `GEMINI.md`
+(指向 `QTYPE.md` 的软链)、`README.md`、`TODO.md`、`index.md`、
+`log.md`、`material/{word,sentence,article,snippet,qa,code}.md` 6 张起手模板
++ 对应的 SVG 图片(`material/assets/<type>/*.svg`)、`.qtype/` 骨架。
 
-幂等 —— 跳过已有的用户内容，只有 `--force` 会覆盖 qtype 管理的规范文件。
+幂等 —— 跳过已有的用户内容,只有 `--force` 才会覆盖 qtype 管理的规范文件。
 
 ---
 
 ## `qtype repo new <name>`
 
-新建一个 material 仓库目录。
+在**父目录**下新建一个 material 仓库子目录。
 
 ```bash
 qtype repo new my-deck --lang zh
-cd my-deck
+qtype repo new my-deck --description "GRE 词汇" --git
 ```
 
-## `qtype repo sync [dir]`
+| 选项 | 说明 |
+|---|---|
+| `--lang <zh\|en>` | 语言,决定模板 |
+| `--description <text>` | README 里的一句简介 |
+| `--dir <path>` | 父目录(默认当前) |
+| `--git` | 顺手 `git init` |
+
+## `qtype repo sync [path]`
 
 在已有 repo 里补齐约定。与 `qtype init` 相同。
 
 ---
 
-## `qtype check [dir]`
+## `qtype check [path]`
+
+`qtype content lint` 的顶层别名,校验 `material/*.md`:报告含打字引擎无法处理
+字符的卡片。返回非零码用于 CI。
+
+```bash
+qtype check                    # 当前目录
+qtype check --json             # JSON 输出,便于工具处理
+```
+
+---
+
+## `qtype content lint | validate | search`
+
+- `lint` —— 卡片文本级校验(打字目标里有无法打字的字符 → 报错)
+- `validate` —— schema 级校验(frontmatter 字段类型 / 必填等)
+- `search <query>` —— 卡片全量子串搜索
 
-校验 `material/*.md` 里的每张卡。报告含打字引擎无法处理字符的卡片
-（返回非零码）。只读；建议在 CI 里放在 `publish build` 前面。
+`search` 支持过滤 + 结构化输出:
 
 ```bash
-qtype check
+qtype content search "闭包"
+qtype content search "apple" --tag GRE --type word --limit 5
+qtype content search "*" --tag 数学 --json    # 脚本友好
 ```
 
+| `search` 选项 | 说明 |
+|---|---|
+| `--limit <n>` | 最多返回结果数(默认 20) |
+| `--tag <tag...>` | 按 tag 过滤(可多次;AND 语义,需全部匹配) |
+| `--type <type...>` | 按 material 类型过滤(可多次) |
+| `--json` | 以 JSON 输出结果 |
+
 ---
 
-## `qtype publish build [dir]`
+## `qtype publish build [path]`
 
-拼装静态站到 `dist/`。执行：
+拼装静态站到 `<repo>/dist/`。执行:
 
 1. 解析每个 `material/*.md`
-2. 预渲染 Mermaid 图（除非 `publish.mermaid=off`）
-3. 加密 material（如果 `publish.password.enabled=true`）
-4. 输出每份 material 的 HTML + `_data/material.json`
-5. 把预构建的 view bundle 拷到 `dist/_app/`
+2. 预渲染 Mermaid 图(除非 `publish.mermaid=off`),生成
+   `dist/material/mermaid.json` + `mermaid.css`(dark + light 两版 SVG)
+3. 加密 material(如果 `publish.password.enabled=true`)—— 用 argon2id
+   派生 AES-256 密钥,AES-GCM 加密每份 material,输出 `<file>.enc.json`
+4. 生成 `dist/material/index.json` manifest(供浏览器懒加载)
+5. 把预构建的 view bundle 拷到 `dist/` 根,可以直接静态部署
 
 ```bash
 qtype publish build
+QTYPE_PUBLISH_PASSWORD=demo qtype publish build   # 非交互输密码
+qtype publish build --out ./build                 # 自定义输出目录
 ```
 
-## `qtype publish serve [dir]`
+## `qtype publish serve [path]`
 
 本地 HTTP 预览 `dist/`。默认端口 4000。
 
@@ -85,18 +123,31 @@ qtype publish serve --port 8080
 
 ## `qtype publish init`
 
-写 `.gitignore` + GitHub Pages workflow，push 到 `main` 就触发构建 + 部署。
+写入部署辅助文件。**默认只写 `.gitignore`**;`--ci github` 追加
+`.github/workflows/pages.yml`,push 到 `main` 就触发构建 + 部署。
+
+```bash
+qtype publish init                # 只写 .gitignore
+qtype publish init --ci github    # 带 GitHub Pages 部署
+```
 
 ## `qtype publish password set / clear / status`
 
-密码保护生命周期。`set` 会提示输入密码，用 Argon2id 派生 AES 密钥，
-把结果 salt + hash 写到 `.qtype/config.json`。`clear` 关闭保护。
+密码保护生命周期。`set` 会提示输入密码,用 Argon2id(64 MiB / t=3 / p=1)
+派生一个短暂 AES 密钥,把 hash + salt 写到 `.qtype/config.json`。密码本身
+**不存**,只存 hash;每次 `publish build` 需要重新提供密码派生 AES 密钥
+加密内容。
 
 ```bash
-qtype publish password set
+qtype publish password set        # 交互输入
+echo "hunter2" | qtype publish password set   # stdin 输入,便于脚本
 qtype publish password status
+qtype publish password clear
 ```
 
+浏览器端:用户在 `PasswordGate` 输密码 → argon2id 派生同一 AES 密钥 →
+解密 material。派生结果缓存到 `sessionStorage`(同一 tab 内刷新不再问)。
+
 ---
 
 ## `qtype pack [-o file]`
@@ -110,25 +161,13 @@ qtype pack -o my-deck.tar.gz
 
 ---
 
-## `qtype content lint | validate | search`
-
-- `lint` —— material 文件的样式级 pass
-- `validate` —— schema 级 pass；`qtype check` 的补充
-- `search <query>` —— 卡片全量子串搜索
-
-```bash
-qtype content search "closure"
-```
-
----
-
 ## `qtype config get / set / unset / list`
 
-git 风格的双层配置（user 层在 `~/.config/qtype/config.json`，repo 层
-在 `<repo>/.qtype/config.json`）。
+git 风格的双层配置(user 层在 `~/.config/qtype/config.json`,repo 层
+在 `<repo>/.qtype/config.json`)。
 
-读优先级：repo > user > schema default。写入默认：repo-scope 键写到
-repo，user-only 键写到 user，双层键优先写 repo。
+读优先级:**CLI flag > repo > user > schema default**。写入默认:
+repo-only 键写到 repo,user-only 键写到 user,双 scope 键优先写 repo。
 
 ```bash
 qtype config set cli.lang zh --global
@@ -138,25 +177,20 @@ qtype config list
 qtype config unset typing.targetWpm
 ```
 
-已知的键包括：
-
-- `cli.lang`、`cli.color`（user-only）
-- `repo.name`、`publish.password.*`（repo-only）
-- `repo.lang`、`typing.theme`、`typing.targetWpm`、`typing.tabBehavior`、
-  `typing.hint`、`typing.showKeyboard`、`typing.showHands`、
-  `publish.mermaid`（双 scope）
-
-严格模式：未知键会被拒绝。
-
----
+**已知配置键**:
 
-## `qtype plugin`
+- **User-only**: `cli.lang`、`cli.color`
+- **Repo-only**: `repo.name`、`publish.password.enabled`、`publish.password.hash`、
+  `publish.password.aesSalt`、`publish.password.scope`、`publish.password.selected`
+- **双 scope**: `repo.lang`、`typing.theme`、`typing.targetWpm`、`typing.tabBehavior`、
+  `typing.hint`、`typing.showKeyboard`、`typing.showHands`、`publish.mermaid`
 
-命令骨架。运行时执行尚未实现 —— 见 [TODO.zh.md](../../TODO.zh.md)。
+严格模式:未知键会被拒绝。View-side 的界面设置(自动朗读 / 数学渲染 /
+AFK 阈值等)存在**浏览器 kv 层**,不在这个 config 里。
 
 ---
 
 ## 退出码
 
 - `0` —— 成功
-- `1` —— 校验 / lint / 构建失败，或任何抛出的错误
+- `1` —— 校验 / lint / 构建失败,或任何抛出的错误

package/docs/zh/deployment.md

@@ -0,0 +1,179 @@
+# 部署指南
+
+English: [deployment.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/deployment.md)
+
+`qtype publish build` 出的 `dist/` 是一个纯静态目录:HTML + JS + CSS +
+`material/*.md`(或加密的 `.enc.json`)+ assets。**没有 server 端**,
+可以扔到任何 CDN / 静态托管上。
+
+## 部署前的 checklist
+
+```bash
+qtype check                # 校验干净?
+qtype publish build        # 生成 dist/
+ls dist/                   # 应看到 index.html + assets/ + material/
+```
+
+**关键点**:构建产物是 `dist/`,不是 `dist/view/`。前者是**用户仓库
+里**的输出目录,后者是**开发时**的 view bundle 缓存(publish build 会
+把 dist/view/* 拷进你的 dist/)。
+
+## GitHub Pages
+
+qtype 自带一键 workflow:
+
+```bash
+qtype publish init --ci github
+```
+
+它会写 `.github/workflows/pages.yml`。push 到 `main` 分支就会:
+1. `npm install -g @qnroa/qtype`
+2. `qtype publish build`
+3. 把 `dist/` 上传到 GitHub Pages
+
+**需要在 GitHub 仓库设置里**手动开启 Pages:
+- Settings → Pages → Source 选 **GitHub Actions**
+
+**如果启用了密码保护**:workflow 里得用 secret 注入密码:
+
+```yaml
+- run: qtype publish build
+  env:
+    QTYPE_PUBLISH_PASSWORD: ${{ secrets.QTYPE_PASSWORD }}
+```
+
+在 Settings → Secrets and variables → Actions 里加一个叫
+`QTYPE_PASSWORD` 的 secret。
+
+## Cloudflare Pages
+
+1. Cloudflare Dashboard → Pages → Create → Connect Git
+2. 构建配置:
+   - **Framework preset**: `None`
+   - **Build command**: `npx @qnroa/qtype publish build`
+   - **Build output directory**: `dist`
+   - **Node version**: `20` (环境变量 `NODE_VERSION=20`)
+3. 密码保护:在 Settings → Environment variables 加
+   `QTYPE_PUBLISH_PASSWORD`(选「Production」+ 勾「Encrypt」)
+
+## Vercel
+
+`vercel.json`(仓库根):
+
+```json
+{
+  "buildCommand": "npx @qnroa/qtype publish build",
+  "outputDirectory": "dist",
+  "framework": null
+}
+```
+
+密码用 `vercel env add QTYPE_PUBLISH_PASSWORD` 加。
+
+## Netlify
+
+`netlify.toml`(仓库根):
+
+```toml
+[build]
+  command = "npx @qnroa/qtype publish build"
+  publish = "dist"
+
+[build.environment]
+  NODE_VERSION = "20"
+```
+
+密码在 Site settings → Environment variables 里加。
+
+## 自建 nginx
+
+`qtype publish build` 完之后:
+
+```bash
+scp -r dist/* user@yourhost:/var/www/your-site/
+```
+
+nginx 配置:
+
+```nginx
+server {
+    listen 80;
+    server_name your-site.example;
+    root /var/www/your-site;
+    index index.html;
+
+    # SPA 回退:任何未命中的路由都返回 index.html,
+    # 让客户端路由接管(/typing/xxx.md 等)
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # 静态资源长缓存 —— hash 化过的文件名,可以放心 immutable
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # material/* 短缓存 —— 用户可能重发,不要缓存太久
+    location /material/ {
+        expires 5m;
+    }
+}
+```
+
+启用 gzip(整个 config 或 site-level):
+
+```nginx
+gzip on;
+gzip_types text/plain text/css application/javascript application/json image/svg+xml;
+gzip_min_length 1024;
+```
+
+## Docker
+
+一个最小 Dockerfile,serve 静态站:
+
+```dockerfile
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY . .
+RUN npm install -g @qnroa/qtype && qtype publish build
+
+FROM nginx:alpine
+COPY --from=build /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+```
+
+nginx.conf 用上一节的 SPA fallback 配置。
+
+## 密码保护的部署注意
+
+密码保护是**客户端解密** —— server 只 serve 加密的 `.enc.json`,
+浏览器输密码后本地解密。所以:
+
+- ✅ **server 不需要认证** —— 加密内容本身就是保护
+- ✅ 可以放到公开的 GitHub Pages / Cloudflare Pages
+- ⚠️ **攻击者能下载整个 dist**,离线暴力破解 KDF —— argon2id 参数
+  (64 MiB / t=3 / p=1)让每次尝试 ≈ 700ms,但不是无限强度。**别用
+  弱密码**(< 12 字符的 dictionary 词组)
+- ⚠️ 密码错了后端不知道,只有客户端能识别 —— 所以没有服务端限速。
+  view 端有本地限速(3 次错误后冷却 2/5/15 秒)是防止手动敲错的,
+  不是安全屏障
+
+## 子路径部署(sub-path)
+
+如果你的站在 `https://example.com/mydeck/` 而不是根,现在**不支持**
+—— 客户端 fetch `/material/*` 是硬编码的绝对路径。要求根部署,或者
+用反代把 `/mydeck/*` rewrite 成 `/*`。
+
+## 验证部署
+
+部署完打开:
+- `/` → 应看到 material 列表(如果加密,先看到密码框)
+- `/material/index.json` → JSON manifest
+- 打开浏览器 devtools → Network,应看到:
+  - 一次 `/material/index.json`
+  - 点某张卡后一次 `/material/<file>.md`(或 `.enc.json`)
+  - 图片时 `/material/assets/**/*.svg`
+
+**任一 404** = server 没配 SPA fallback 或路径搞错了。