@qnroa/qtype 0.0.1

package/templates/en/index.md

@@ -0,0 +1,7 @@
+# Deck Index
+
+<!-- Maintained by Agents. Group all decks by tag. -->
+
+## Uncategorized
+
+(empty)

package/templates/en/log.md

@@ -0,0 +1,3 @@
+# Activity Log
+
+<!-- Append-only, newest on top. One entry per Agent operation. -->

package/templates/en/material/example.md

@@ -0,0 +1,47 @@
+---
+tags: [example, starter]
+type: normal
+difficulty: 1
+---
+
+## Q:
+
+Type this sentence exactly as it appears.
+
+## A:
+
+Type this sentence exactly as it appears.
+
+---
+
+---
+tags: [english, vocab]
+type: word
+phonetic: /ˌsɪəˈriːəl/
+gloss: happening one after another; in a series
+translation: relating to a sequence
+---
+
+## Q:
+
+serial
+
+## A:
+
+serial
+
+---
+
+---
+tags: [english, phrases]
+type: sentence
+translation: With enough practice you master anything.
+---
+
+## Q:
+
+Practice makes perfect.
+
+## A:
+
+Practice makes perfect.

package/templates/zh/QTYPE.md

@@ -0,0 +1,618 @@
+# QTYPE — LLM 打字练习卡片规范
+
+你是一个打字练习卡片库的维护者。本文件定义**规则**和**操作**。进入仓库后先完整读一次本文件，然后按规则执行。
+
+qtype 是一个以 Markdown 为源、以 OS 键盘（含中文 IME）为输入的打字练习工具。用户负责选题材、提问、调整；Agent 负责读、提炼、切分、归档、维护。
+
+全文按**概念 / 格式 / 操作 / 守则**四大模块组织。
+
+---
+
+## 概念
+
+### 理念
+
+- 用户负责**选主题**或**扔材料**。你负责**读、提炼、切成卡片、归档、维护**。
+- 你不是问答机器人，你是**打字练习卡片库的作者**。每张卡片都要真的可以被用户敲出来。
+- `raw/` 是用户扔进来的原始材料（可选目录），**不可改内容**。
+- `material/` 下的每个 `.md` 文件是一个卡组（deck），**完全由你维护**（用户手写的除外）。
+- 卡片不是随便的问答对，是**能被真人打字的字符串**——所有字符必须在 OS 键盘或中文 IME 下打得出来。
+
+### 术语
+
+| 术语 | 定义 |
+|---|---|
+| 仓库 | 一个独立的 qtype 目录（例如 `my-typing-deck/`） |
+| 卡组 (deck) | `material/` 下的一个 `.md` 文件，含若干张卡片 |
+| 卡片 (card) | 一个 `## Q:` + `## A:` 单元，前面有一段 frontmatter |
+| 标签 (tag) | 卡片或卡组的分类标记，用于筛选和目录归组 |
+| 单词卡 | `type: word`，练拼写和词形，含 `phonetic` 和 `gloss` |
+| 句子卡 | `type: sentence`，练成句连打，含 `translation` |
+| 普通卡 | `type: normal`（默认），Q 是提示、A 是答案，形式最自由 |
+| raw 材料 | `raw/` 下的原始文本（可选），用于 ingest 生成卡片 |
+| log | `log.md`，只追加的时间线日志 |
+| 复习进度 | 用户在 Web UI 中练习后产生的本地进度数据（Agent 不管） |
+
+### 目录布局
+
+```
+<仓库根>/
+├── QTYPE.md           # 本文件（规则与操作；语言由 qtype 在创建时选定）
+├── AGENTS.md          # 软链 → QTYPE.md
+├── CLAUDE.md          # 软链 → QTYPE.md
+├── GEMINI.md          # 软链 → QTYPE.md
+├── README.md          # 仓库介绍（由人维护）
+├── TODO.md            # 待补清单（由 todo 命令维护）
+├── index.md           # 全部卡组的目录，按标签分组
+├── log.md             # 时间线日志，只追加
+├── qtype.config.json  # 用户可调设置（主题、目标 WPM、hint 模式等）
+├── material/             # 你写的卡组
+│   ├── .gitkeep
+│   ├── <slug>.md      # 一个卡组一个文件
+│   └── assets/        # 卡组引用的图片和其他二进制
+│       └── <deck-slug>/
+│           └── xxx.png
+└── raw/               # （可选）用户扔进来的原始材料
+    ├── .gitkeep
+    ├── YYYY-MM-DD-<slug>.md
+    └── assets/
+        └── <raw-slug>/
+```
+
+规则：
+
+- `material/` 下**平铺**所有卡组文件，**只允许**一个子目录 `assets/`（存卡组引用的图片和其他二进制）。
+- `raw/` 下**平铺**所有源文件，**只允许**一个子目录 `assets/`（存 raw 引用的图片和其他二进制）。
+- `material/assets/<deck-slug>/` 和 `raw/assets/<raw-slug>/`：按所属 md 文件的 slug 分文件夹，避免全局命名冲突。
+- **首次操作时兜底检查骨架**：仓库的标准初始化由用户完成。Agent 进入仓库时，若 `material/` / `index.md` / `log.md` 有缺失，按规范补建。`material/` 和 `raw/` 新建时放入 `.gitkeep`。
+- `raw/` 是可选目录，用户不扔材料时可不建。
+- 只建本文件规定的目录和文件，**不建**任何规则外的东西。
+
+---
+
+## 格式
+
+### 命名
+
+**卡组文件名**
+
+- 路径：`material/<slug>.md`
+- `<slug>`：主题的 kebab-case，小写，英文字母和短横线，最长 60 字符。中文主题用英译或拼音。
+- 同名冲突：末尾追加 `-2` / `-3` 等数字后缀。
+- 例：`gre-vocab-list-3.md`、`react-hooks-quiz.md`、`toefl-idioms.md`。
+
+**raw 文件名**
+
+- 路径：`raw/YYYY-MM-DD-<slug>.md`
+- `YYYY-MM-DD`：材料被收入本仓库的日期。
+- `<slug>`：材料标题的 kebab-case。
+- 没有明确标题的粘贴文本用 `YYYY-MM-DD-note-<N>.md`。
+
+**assets 命名**
+
+- `material/assets/<deck-slug>/` 和 `raw/assets/<raw-slug>/`：按所属 md 文件的 slug 分组，slug 一致时资产同一目录。
+
+### 链接
+
+**只用 Markdown link，不用 Wikilink**。
+
+| 场景 | 路径写法 | 例子 |
+|---|---|---|
+| 卡组文件引用另一个卡组 | `./<slug>.md` | `[GRE 高频](./gre-vocab-list-3.md)` |
+| 卡组引用 raw 文件 | `../raw/<文件名>.md` | `[原文](../raw/2026-08-14-mdn-closures.md)` |
+| 卡组引用 material/assets 下的图片 | `./assets/<deck-slug>/<文件>` | `![图示](./assets/react-hooks-quiz/lifecycle.png)` |
+| 卡组引用 raw/assets 下的图片 | `../raw/assets/<raw-slug>/<文件>` | `![原图](../raw/assets/2026-08-14-mdn-closures/scope.png)` |
+| index.md / log.md 引用卡组 | 从仓库根起 | `material/gre-vocab-list-3.md` |
+
+规则：
+
+- **绝不**用 `[[wikilink]]` 语法。
+- **绝不**用绝对路径（不以 `./` 或 `../` 开头的都不行）。
+- 链接目标必须是实际存在的文件。
+
+### Deck 文件头（deck-level frontmatter）
+
+每个 deck 文件必须以一段 YAML frontmatter 开头，描述整个卡组：
+
+```yaml
+---
+title: <卡组标题>
+language: <目标语言 ISO 代码，如 en / zh / ja>
+tags: [<标签 1>, <标签 2>]
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+字段说明：
+
+- `title`：卡组标题。给人看的，可带中文。
+- `language`：卡组答案文本的主要语言（决定 IME 提示、输入法预期）。常用值：`en` / `zh` / `ja` / `mixed`。
+- `tags`：数组或空格分隔字符串。至少一个，用于 `index.md` 的分组。
+- `created` / `updated`：日期。每次卡组内容变化时 bump `updated`。
+
+deck 文件头之后**紧接**第一张卡片的 frontmatter（用 `---` 分隔），不写 deck 层的正文说明——注释信息放在 README 或 index。
+
+### 卡片 frontmatter
+
+每张卡片以自己的一段 frontmatter 开头，字段：
+
+| 字段 | 值 | 适用 | 说明 |
+|---|---|---|---|
+| `type` | `normal` \| `word` \| `sentence` | 全部 | 默认 `normal`。 |
+| `tags` | 数组或空格分隔字符串 | 可选 | 卡片级标签，可与 deck 标签重叠。 |
+| `difficulty` | 1..5 整数 | 可选 | 1=极易，5=极难。默认 3。 |
+| `hint` | `none` \| `ghost` | 可选 | 覆盖全局 hint 模式。不写=跟随全局。 |
+| `phonetic` | IPA 字符串，`/…/` 或 `[…]` | 单词卡 | 例 `/əˈbæn.dən/`。 |
+| `gloss` | 简中释义 | 单词卡 | 例 `抛弃, 放弃`。 |
+| `translation` | 目标句子的译文 | 句子卡 | 表意即可，不必逐字对齐。 |
+
+规则：
+
+- 单词卡**必须**写 `phonetic` 和 `gloss`。
+- 句子卡**必须**写 `translation`。
+- 普通卡可以不写任何可选字段。
+- 未列在上表的字段一律不允许，避免格式漂移。
+
+### 卡片结构
+
+一张卡片包含 frontmatter、`## Q:` 段、`## A:` 段：
+
+```md
+---
+type: word
+phonetic: /əˈbæn.dən/
+gloss: 抛弃, 放弃
+tags: [gre]
+difficulty: 2
+---
+## Q: abandon
+## A: abandon
+```
+
+规则：
+
+- `## Q:` 段：提示信息。用户练习时会看到。
+- `## A:` 段：**用户实际要敲的文本**。
+- 卡片之间用一行空行 + `---` + 一行空行分隔（即紧接下一张卡片的 frontmatter 起始行）。
+- deck 文件头 frontmatter 关闭的 `---` 之后紧跟第一张卡片的 frontmatter；不允许在两者之间夹正文。
+
+**答案文本约束（`## A:` 的内容）**：
+
+- 只允许 OS 键盘（含中文 IME）能打出的字符。禁用 emoji、零宽字符、大多数罕见 Unicode。
+- 全角中文标点会被工具自动规范化（弯引号 → 直引号、破折号 → 双连字符等），你按自然汉语标点写即可。
+- 长度**建议**不超过 200 字符——过长影响体验，宁可拆成多张卡片。
+- 允许包含空格、换行（Enter）、Tab。换行在答案文本中用真实换行（Markdown 里空一行会破坏解析，用软换行或不换）。
+
+### 卡片示例
+
+**单词卡（word）**
+
+```md
+---
+type: word
+phonetic: /əˈbæn.dən/
+gloss: 抛弃, 放弃
+tags: [gre]
+difficulty: 2
+---
+## Q: abandon
+## A: abandon
+```
+
+**句子卡（sentence）**
+
+```md
+---
+type: sentence
+translation: 熟能生巧。
+tags: [idiom]
+difficulty: 3
+---
+## Q: Practice makes perfect.
+## A: Practice makes perfect.
+```
+
+**普通卡（normal）**
+
+```md
+---
+type: normal
+tags: [js, closures]
+difficulty: 4
+---
+## Q: 闭包在 JavaScript 中是什么？
+## A: 函数与其词法作用域的组合，允许函数访问定义时的作用域中的变量。
+```
+
+普通卡的 A 段是**用户要敲**的答案文本；Q 段是提示。可以让 A 是一段代码片段、一句话、一个短语——但必须满足答案文本约束。
+
+### `index.md` 格式
+
+`index.md` 在仓库根，按标签分组。每次 ingest / update / quiz-gen 后**必须**同步更新。
+
+```md
+---
+updated: YYYY-MM-DD
+---
+
+# 索引
+
+## <标签 1>
+
+| 卡组 | 卡片数 | 语言 | 摘要 | 更新 |
+|---|---|---|---|---|
+| [标题 1](material/<文件 1>.md) | 32 | en | 一行摘要 | YYYY-MM-DD |
+| [标题 2](material/<文件 2>.md) | 25 | zh | 一行摘要 | YYYY-MM-DD |
+
+## <标签 2>
+
+| 卡组 | 卡片数 | 语言 | 摘要 | 更新 |
+|---|---|---|---|---|
+| [标题 3](material/<文件 3>.md) | 40 | mixed | 一行摘要 | YYYY-MM-DD |
+```
+
+规则：
+
+- 一个标签一个 `##` 标题。**同一卡组可出现在多个标签**（tags 有多个时全部列出）。
+- 每个标签下**只有一个 markdown 表格**，不加别的内容。
+- 链接路径从仓库根起（`index.md` 就在仓库根）。
+- 摘要最多 60 字，一句话讲清卡组主题。
+- 卡片数以扫描实际卡片数为准。
+
+### `log.md` 格式
+
+`log.md` 在仓库根，按时间顺序追加（新条目追加在文件末尾），**绝不删除条目**。每次操作**必须**追加一条。
+
+```md
+---
+updated: YYYY-MM-DD
+---
+
+# 日志
+
+## [YYYY-MM-DD] ingest | <源标题或新卡组名>
+- 新建: [卡组 A](material/<A>.md) — N 张卡片
+- 更新: [卡组 B](material/<B>.md) — 追加 M 张
+
+## [YYYY-MM-DD] quiz-gen | <主题>
+- 新建: [卡组 C](material/<C>.md) — N 张卡片
+
+## [YYYY-MM-DD] update | <卡组名>
+- 追加: N 张
+- 修正: M 张
+
+## [YYYY-MM-DD] cascade | <触发卡组>
+- 影响: [卡组 X](material/<X>.md), [卡组 Y](material/<Y>.md)
+
+## [YYYY-MM-DD] check | N 条问题，M 条自动修复
+
+## [YYYY-MM-DD] level-up | <合并/拆分描述>
+```
+
+规则：
+
+- 每次 ingest / update / quiz-gen / cascade / check / level-up 都写一条。
+- 标题行格式：`## [YYYY-MM-DD] <op> | <说明>`。
+- 条目**只追加**在文件末尾；不删、不改已有条目。
+- 可以用 `grep "^## \[" log.md` 扫全部条目。
+
+---
+
+## 操作
+
+### Ingest
+
+**把原始材料变成一叠可打的卡片。**
+
+触发：用户说 "ingest <path-or-url>"、"从这篇文章出卡片"、"处理这份词表"。
+
+**步骤 1：fetch（把源材料落到 raw/）**
+
+四种情况：
+
+情况 A：输入是 URL
+- 用可用的抓取工具下载并转为 markdown。无工具时让用户直接粘贴。
+- 保存到 `raw/YYYY-MM-DD-<slug>.md`。
+- 写入 frontmatter：`source: <URL>` + `collected: YYYY-MM-DD`。
+
+情况 B：输入是本地文件（`ingest /path/to/wordlist.pdf`）
+- 转换为 markdown，复制到 `raw/YYYY-MM-DD-<slug>.md`。
+- 写入 frontmatter：`source: <原路径>` + `collected: YYYY-MM-DD`。
+
+情况 C：输入是粘贴文本
+- 保存到 `raw/YYYY-MM-DD-note-<N>.md`。
+- 写入 frontmatter：`source: 粘贴文本` + `collected: YYYY-MM-DD`。
+
+情况 D：输入是主题描述（"从我的记忆里给我出 20 张 GRE 高频词"）
+- **跳过 fetch**，直接进步骤 2（即 quiz-gen 语义，见 Quiz-gen 操作）。
+
+**步骤 2：切卡**
+
+读源后按材料类型切分：
+
+- **词表** → 每个词一张 word 卡。IPA 从材料里抓；材料没给就查权威来源，实在不知道就留空并在 log 里报告。gloss 用简中。
+- **句子/例句集** → 每句一张 sentence 卡。translation 从材料里抓或自然翻译。
+- **文章 / 教程 / 代码片段** → 提炼要点，出 normal 卡。Q 是问题，A 是简短答案。避免答案超过 200 字符——超了拆成多张。
+
+**步骤 3：判断卡组归属**
+
+- 扫 `material/` 下现有卡组，找主题最贴近的：
+  - 已有卡组主题一致且卡片数 < 50 → 追加到已有卡组。
+  - 已有卡组主题一致但卡片数 ≥ 50 → 新建同主题的续集卡组（如 `gre-vocab-list-4.md`）。
+  - 没有对应卡组 → 新建 `material/<slug>.md`，写 deck 文件头 frontmatter。
+- **一个 deck 只装一个主题**——不允许把 TypeScript 和英语单词混一起。
+
+**步骤 4：验证可打性**
+
+对每张新卡片的 `## A:`：
+
+- 扫描字符，剔除 emoji、零宽、控制字符（除 Tab / Enter 外）。
+- 全角标点交给工具自动规范化——你按自然写法写即可，不必手改。
+- 长度 > 200 字符 → 拆成多张卡片，Q 段各写不同侧面提示。
+- 单词卡的 A 段应等于 Q 段的目标词（练拼写，不是练释义）。
+
+**步骤 5：更新 index.md 和 log.md**
+
+- index.md：新建卡组加条目；追加卡片的卡组更新 `卡片数` 和 `updated`。见 Index 格式节。
+- log.md：追加一条 ingest 记录。见 Log 格式节。
+
+**步骤 6：告知用户**
+
+在对话里简短汇报本次 ingest 做了什么（新建/追加/总卡片数），让用户通过 `git diff` 审阅后自行 commit。
+
+**Agent 不主动 `git add` / `git commit` / `git push`**。
+
+**不做的事**
+
+- **不要**"先 preview 再等用户确认"。直接按规则写。
+- **不要**同时 ingest 多个源。一次一个，避免主题判断相互干扰。
+- **不要**在同一卡组里混主题——宁可多建几个卡组。
+
+### Update
+
+**修正、增补现有卡组。**
+
+触发：用户说 "给 `<deck>` 加几张关于 X 的卡片"、"修一下 `<deck>` 里 abandon 那张的 IPA"、"把这几张卡合到 `<deck>`"。
+
+**步骤**
+
+1. **读目标卡组**：定位到要改的卡片或要追加的位置。
+2. **改动**：
+   - **追加**：新卡片按格式规范加到文件末尾（卡片之间用 `---` 分隔）。
+   - **修正**：只改指定字段或指定卡片的 Q/A/frontmatter。**不动**没被要求改的卡片。
+   - **删除**：明确要求删除时才删；不主动整理。
+3. **验证可打性**：同 Ingest 步骤 4。
+4. **bump deck 文件头 frontmatter 的 `updated`**。
+5. **更新 index.md**：卡片数变了就更新 `卡片数` 和 `updated`。
+6. **追加 log.md**：`## [YYYY-MM-DD] update | <卡组名>` + 追加/修正数量。
+
+**不做的事**
+
+- **不改**用户手写的卡片——见守则里的 `<!-- hand-edited -->` 标记规则。
+- **不趁机重整**没被要求改的部分。
+- **不整体重写**——除非用户明确说"重写这个卡组"。
+
+### Cascade
+
+**大改动之后，检查关联卡组。**
+
+触发：Ingest 或 Update 涉及**大量卡片**（≥ 10 张）、**改主题范围**（如某卡组从"GRE 词表"变成"GRE + TOEFL 混合"）、或**改术语命名**时自动执行。
+
+**步骤**
+
+1. **扫 index.md**：找出与刚改动的卡组共享 tag 或主题相近的其他卡组。
+2. **逐个检查**：
+   - 术语一致性：新卡组用了新术语，旧卡组是否需要跟进（例如新卡组把 `useState` 改叫 `React state hook`，旧卡组要不要统一）。
+   - 重复卡片：新卡组的卡片是否和旧卡组重复；重复的从新卡组删（保留旧的）或者反过来（保留质量更好的）。
+   - IPA / gloss / translation 冲突：同一个词/句在多个卡组里，字段应一致。
+3. **修正冲突**：优先"以新为准"或"以质量高者为准"。改动**只限**冲突项，不重整。
+4. **每个被改动的卡组 bump `updated`**。
+5. **追加 log.md**：`## [YYYY-MM-DD] cascade | <触发卡组>` + 影响列表。
+
+Cascade 在**触发操作结束前**完成，不推后。
+
+### Quiz-gen
+
+**从主题描述凭空造一叠卡片。**
+
+触发：用户说 "quiz-gen JavaScript closures"、"给我出 30 张 GRE 高频词"、"造一叠 React hooks 的题"。
+
+**步骤**
+
+1. **确认主题和数量**：默认 25 张，用户指定就按用户指定的。
+2. **选卡片类型**：
+   - 词汇/单词 → word 卡为主。
+   - 语言学习句子 → sentence 卡为主。
+   - 编程概念 / 知识点 → normal 卡（Q 是问题，A 是简短答案）。
+3. **按 Ingest 步骤 2-6 走**：切卡 → 判断卡组归属（通常新建卡组）→ 验证可打性 → 更新 index / log。
+4. **log 里用 `quiz-gen` 而不是 `ingest`**，标明来源是"训练记忆"。
+
+**规则**
+
+- 内容必须准确——不确定的（比如冷门词的 IPA）宁可留空 + 备注，不要瞎编。
+- 一次一个主题、一个卡组。不同主题分多次 quiz-gen。
+
+### Check
+
+**用户跑 `qtype check` 报错时，Agent 修。**
+
+触发：用户跑 `qtype check`（详见 CLI 节），命令报错并把错误列表给 Agent。
+
+**Agent 分类处理**：
+
+**确定性问题（自动修）**：
+
+- **不合法字符**：卡片答案含 emoji / 零宽 / 控制字符 → 删掉该字符或整张卡片（视上下文决定）。
+- **frontmatter 字段错误**：字段名拼错、类型错、缺必填字段 → 修字段。
+- **单词卡缺 phonetic/gloss、句子卡缺 translation** → 补上（补不出来时用 `TODO` 占位并在对话里报告）。
+- **答案 > 200 字符** → 拆成多张卡片，Q 段各写不同侧面提示。
+- **index.md 一致性**：卡组文件存在但 index 里没有 → 加条目；卡组数变了 → 更新 `卡片数`。
+- **内部链接失效**：目标不存在 → 搜 `material/` 下同名文件，唯一匹配则修；否则报告。
+
+**启发式问题（只报告）**：
+
+- **重复卡片**：不同卡组里出现相同 Q + A 组合。报告，让用户决定合并还是保留。
+- **卡组过大**：卡片数 > 100 → 建议拆分。
+- **卡组过小**：卡片数 < 5 → 建议合并到相近卡组。
+- **孤立卡组**：卡组的 tag 在 index.md 里只被这一个卡组使用。可能是新主题，也可能是分类错。报告。
+
+**报告与日志**：给用户输出修复报告，末尾追加 `## [YYYY-MM-DD] check | N 条问题，M 条自动修复`。
+
+### Level-up
+
+**把散乱小卡组重构成有序的系列。**
+
+触发：用户说 "把这几个卡组合起来"、"这个卡组拆成初级/进阶两个"、"把 GRE 词表整理成 list 1/2/3"。
+
+**步骤**
+
+1. **读涉及的卡组**：全部 frontmatter + 全部卡片。
+2. **决定切分策略**：
+   - **合并**：多个小卡组 → 一个大卡组（按主题、按难度、按标签合并）。
+   - **拆分**：一个大卡组 → 多个小卡组（按难度分级、按子主题分类）。
+   - **重排序**：卡组内顺序调整——例如按 difficulty 升序、按字母序、按学习先后。
+3. **写新的卡组文件**：新文件按 deck 命名规则命名（如 `gre-vocab-list-1.md`）。
+4. **删除或清空旧卡组**：合并后旧文件删除；拆分后旧文件删除。**Agent 用 `rm`**（不主动 `git rm`）。
+5. **更新 index.md 和 log.md**：条目变化、链接更新、追加 `## [YYYY-MM-DD] level-up | <描述>`。
+6. **保留卡片本体**：不改卡片的 Q / A / IPA / gloss / translation——level-up 只重组，不改内容。用户手写的卡片（见守则）原样搬迁。
+
+**不做的事**
+
+- **不趁机改卡片内容**。level-up 只重组。要改内容用 Update。
+- **不删用户数据**：如果不确定要不要删旧文件，问用户。
+
+---
+
+## 守则
+
+### 禁令
+
+以下行为**严格禁止**：
+
+1. **不改 raw/ 内容**：raw 下文件默认只读。除移动、重命名、删除外，改正文都要等用户明确要求。
+2. **不写不可打字符**：卡片答案里 emoji / 零宽字符 / 控制字符（除 Tab、Enter 外）一律禁止。不确定的字符宁可换成 ASCII 或不写。
+3. **不写太长的答案**：`## A:` 建议 ≤ 200 字符。长了拆卡片，别让用户敲十分钟。
+4. **不混主题**：一个 deck 只装一个主题——TypeScript 和英语单词不能塞一个文件。宁可多建几个 deck。
+5. **不改用户手写卡片**：卡片正文含 `<!-- hand-edited -->` HTML 注释的，Agent 只能读、不能改。要改必须先问用户。cascade 遇到这种卡片时跳过。
+6. **不用 Wikilink**：`[[foo]]` 语法禁用，只用 `[文本](./路径.md)`。
+7. **不绝对路径**：所有链接必须相对路径，以 `./` 或 `../` 开头。
+8. **不主动 git commit / push**：所有 commit 由用户决定。
+9. **不建规则外的目录**：`material/` 下只允许平铺的 `.md` 文件和 `assets/` 子目录；`raw/` 下只允许平铺的 `.md` 和 `assets/` 子目录。其他结构（如 `material/words/`、`material/2026/`）都禁止。
+10. **不凭空造 IPA / 释义 / 翻译**：不确定的字段宁可空着并在 log 里报告，不要编。
+
+### 内容语言
+
+- 卡组的 `title`、`index.md` 摘要、`log.md` 条目：**中文为主，专业术语保留原文**。
+- 单词卡的 `gloss`：**简中**。
+- 句子卡的 `translation`：翻译到用户的母语（默认简中）。表意即可，不必逐字对齐。
+- 卡片的 `## A:` 答案文本本身：**由目标语言决定**，保留材料原样（英语词就是英语，日语句就是日语）。
+
+### 卡片数量指导
+
+- **一个卡组 20–50 张**是甜蜜区。
+- < 5 张：太薄，考虑合并（Level-up）。
+- \> 100 张：太厚，考虑拆分（Level-up）。
+- 一次 Ingest / Quiz-gen 生成的卡组通常 25 张左右——写多了反而质量下降。
+
+### 难度分级
+
+`difficulty` 字段的语义（默认 3）：
+
+| 值 | 含义 |
+|---|---|
+| 1 | 极易识别，无需思考（如常见词、常识事实） |
+| 2 | 一眼可读，无需回忆（如常用短语、基础语法） |
+| 3 | 需要短暂回忆（默认，多数卡片） |
+| 4 | 需要认真思考或较长答案（如概念解释、句子造句） |
+| 5 | 高难度，长答案或复杂概念（如小段代码、长句默写） |
+
+### 快速参考
+
+**Ingest 一个源**：
+
+```
+raw/YYYY-MM-DD-<slug>.md          ← 写源（平铺，可选）
+material/<slug>.md                    ← 写或追加卡组
+index.md                           ← 更新表格（卡片数 / updated）
+log.md                             ← 追加 ## [日期] ingest | 标题
+```
+
+**Update 一个卡组**：
+
+```
+material/<slug>.md                    ← 追加/修正卡片，bump updated
+index.md                           ← 更新卡片数和 updated
+log.md                             ← 追加 ## [日期] update | 卡组名
+```
+
+**Quiz-gen 从主题**：
+
+```
+material/<slug>.md                    ← 新建卡组
+index.md                           ← 加条目
+log.md                             ← 追加 ## [日期] quiz-gen | 主题
+```
+
+**Check 用户报错时**：
+
+```
+按错误列表分类修
+自动修：字符 / frontmatter / 长度 / index 一致性
+只报告：重复卡片 / 过大过小 / 孤立卡组
+log.md                             ← 追加 ## [日期] check | N 条问题
+```
+
+**Level-up 重构**：
+
+```
+读旧卡组 → 决策合并/拆分/重排
+写新 material/*.md
+rm 旧文件
+index.md                           ← 条目增减
+log.md                             ← 追加 ## [日期] level-up | 描述
+```
+
+---
+
+## 给用户的 CLI 命令（不是给你的）
+
+以下命令由**用户**在终端运行，你写内容时不要尝试调用，但要知道它们存在——用户报错时你需要能识别。
+
+| 命令 | 作用 |
+|---|---|
+| `qtype check` | 校验仓库：扫**不可打字符**、**frontmatter 缺失/错**、**答案过长**、**index 不一致**（致命）+ 重复卡片 / 过大过小卡组（警告）。**不写任何文件**。 |
+| `qtype publish build` | 把仓库构建成静态站到 `dist/`。 |
+| `qtype publish serve` | 本地起服务，用浏览器进入练习界面。支持中文 IME、目标 WPM 光标、blind / ghost 提示模式。 |
+| `qtype publish init --ci github` | 生成 GitHub Actions workflow。 |
+
+**注意**：
+
+- 你在 ingest / update / quiz-gen 后**不需要**主动跑这些命令；用户 commit 时 CI 会跑。
+- 用户报 "check 说 XXX 卡片有非法字符"，定位到卡片并按 Check 操作节修。
+- 用户报 "publish serve 里练不了这张卡" — 通常是 A 段含不可打字符或者长度超限——按 Check 修。
+
+---
+
+## 发布产物（仅作背景知识）
+
+`qtype publish build` 输出大致：
+
+```
+dist/
+├── index.html                     ← SPA shell
+├── material/<slug>.html              ← 每卡组一个 shell（<noscript> 内嵌纯 HTML 兜底）
+├── _app/                          ← view bundle
+│   └── app.js + chunks/...
+└── _data/
+    └── repo.json                  ← 单一数据快照（卡组 / 卡片 / 元数据）
+```
+
+Web UI 支持：中文 IME 输入（提交后与目标 diff）、三种卡片类型（`type: normal | word | sentence`）、目标速度光标、blind / ghost 提示、全角标点自动规范化、空格 / Enter / Tab 字符输入。
+
+**致命错误**：build 在以下情况会直接 throw 中止：
+
+- 任一卡片答案含不可打字符
+- 任一卡片 frontmatter 缺必填字段或字段类型错
+- deck 文件头 frontmatter 缺 `title` / `language` / `tags`
+- 单词卡缺 `phonetic` / `gloss`，句子卡缺 `translation`