@qnroa/qtype 0.0.1 → 0.0.3

package/templates/zh/QTYPE.md

@@ -15,604 +15,322 @@ qtype 是一个以 Markdown 为源、以 OS 键盘（含中文 IME）为输入
 - 用户负责**选主题**或**扔材料**。你负责**读、提炼、切成卡片、归档、维护**。
 - 你不是问答机器人，你是**打字练习卡片库的作者**。每张卡片都要真的可以被用户敲出来。
 - `raw/` 是用户扔进来的原始材料（可选目录），**不可改内容**。
-- `material/` 下的每个 `.md` 文件是一个卡组（deck），**完全由你维护**（用户手写的除外）。
+- `material/` 下的每个 `.md` 文件是一个素材（material），**完全由你维护**（用户手写的除外）。
 - 卡片不是随便的问答对，是**能被真人打字的字符串**——所有字符必须在 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 目录 |
+| 素材 (material) | `material/` 下的一个 `.md` 文件，含若干张卡片 |
+| 卡片 (card) | 一个 `#` H1 及其下方内容 |
+| 标签 (tag) | 素材的分类标记，只在 material-level 声明 |
+| type | 素材的形态类型，决定卡片内部结构：`word` / `sentence` / `article` / `snippet` / `qa` / `code` |
 
 ### 目录布局
 
 ```
 <仓库根>/
-├── QTYPE.md           # 本文件（规则与操作；语言由 qtype 在创建时选定）
+├── QTYPE.md           # 本文件（规则与操作）
 ├── AGENTS.md          # 软链 → QTYPE.md
 ├── CLAUDE.md          # 软链 → QTYPE.md
 ├── GEMINI.md          # 软链 → QTYPE.md
 ├── README.md          # 仓库介绍（由人维护）
-├── TODO.md            # 待补清单（由 todo 命令维护）
-├── index.md           # 全部卡组的目录，按标签分组
+├── TODO.md            # 待补清单
+├── index.md           # 全部素材的目录，按标签分组
 ├── log.md             # 时间线日志，只追加
-├── qtype.config.json  # 用户可调设置（主题、目标 WPM、hint 模式等）
-├── material/             # 你写的卡组
+├── qtype.config.json  # 用户可调设置
+├── material/          # 你写的素材
 │   ├── .gitkeep
-│   ├── <slug>.md      # 一个卡组一个文件
-│   └── assets/        # 卡组引用的图片和其他二进制
-│       └── <deck-slug>/
-│           └── xxx.png
+│   ├── <slug>.md      # 一个素材一个文件
+│   └── assets/        # 素材引用的图片
+│       └── <material-slug>/
 └── 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 一致时资产同一目录。
+### Material 顶部 frontmatter
 
-### 链接
-
-**只用 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 开头，描述整个卡组：
+每个 material 文件必须以一段 YAML frontmatter 开头，**决定整个素材所有卡片的形态**：
 
 ```yaml
 ---
-title: <卡组标题>
-language: <目标语言 ISO 代码，如 en / zh / ja>
-tags: [<标签 1>, <标签 2>]
+title: <素材标题>
+type: word | sentence | article | snippet | qa | code
+tags: [<t1>, <t2>]
 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。
+- `title`：素材标题，人看的
+- `type`：**必填**，决定所有卡片的解析规则和渲染样式
+- `tags`：数组或空格分隔，至少一个
+- `created` / `updated`：日期。内容变化时 bump `updated`
+- **一个 material 只有一个 type**，一个文件的所有卡片形态一致
 
-### 卡片 frontmatter
+**没有 card-level frontmatter**。所有卡片信息都由 markdown 结构表达。
 
-每张卡片以自己的一段 frontmatter 开头，字段：
+### Card 结构
 
-| 字段 | 值 | 适用 | 说明 |
-|---|---|---|---|
-| `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` | 目标句子的译文 | 句子卡 | 表意即可，不必逐字对齐。 |
+**H1（`#`）分卡**：每一个 H1 起一张新卡片。下一个 H1 = 下一张卡。**不用 `---` 分隔**。
 
-规则：
+**按 type 分六种结构**：
 
-- 单词卡**必须**写 `phonetic` 和 `gloss`。
-- 句子卡**必须**写 `translation`。
-- 普通卡可以不写任何可选字段。
-- 未列在上表的字段一律不允许，避免格式漂移。
+#### type: word
 
-### 卡片结构
-
-一张卡片包含 frontmatter、`## Q:` 段、`## A:` 段：
+单词卡。H1 = 打字目标；H2/H3/H4 是可选注解，位置固定。
 
 ```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 里空一行会破坏解析，用软换行或不换）。
-
-### 卡片示例
+# abandon
+## /əˈbæn.dən/
+### 抛弃, 放弃
+#### ![](./assets/vocab/abandon.jpg)
 
-**单词卡（word）**
+# ephemeral
+## /əˈfem(ə)rəl/
+### 短暂的
 
-```md
----
-type: word
-phonetic: /əˈbæn.dən/
-gloss: 抛弃, 放弃
-tags: [gre]
-difficulty: 2
----
-## Q: abandon
-## A: abandon
+# barebones
 ```
 
-**句子卡（sentence）**
+| 层级 | 内容 | 可选 |
+|---|---|---|
+| **H1** | 打字目标（要敲的词） | 必填 |
+| **H2** | 音标 / 拼音 | 可选 |
+| **H3** | 释义 / 简译 | 可选 |
+| **H4** | 图片，用 `![](url)` markdown 语法 | 可选 |
 
-```md
----
-type: sentence
-translation: 熟能生巧。
-tags: [idiom]
-difficulty: 3
----
-## Q: Practice makes perfect.
-## A: Practice makes perfect.
-```
+#### type: sentence
 
-**普通卡（normal）**
+句子卡。**同 word 结构**，H1 = 打字目标（完整句子）。
 
 ```md
----
-type: normal
-tags: [js, closures]
-difficulty: 4
----
-## Q: 闭包在 JavaScript 中是什么？
-## A: 函数与其词法作用域的组合，允许函数访问定义时的作用域中的变量。
+# Practice makes perfect.
+### 熟能生巧。
+
+# 举头望明月，低头思故乡。
+### 抬头看月亮，低头想故乡。
 ```
 
-普通卡的 A 段是**用户要敲**的答案文本；Q 段是提示。可以让 A 是一段代码片段、一句话、一个短语——但必须满足答案文本约束。
+| 层级 | 内容 | 可选 |
+|---|---|---|
+| **H1** | 打字目标（要敲的句子） | 必填 |
+| **H2** | 音标 / 拼音 | 可选（句子级少用） |
+| **H3** | 翻译 | 可选 |
+| **H4** | 图片 | 可选 |
 
-### `index.md` 格式
+#### type: article
 
-`index.md` 在仓库根，按标签分组。每次 ingest / update / quiz-gen 后**必须**同步更新。
+文章卡。**H1 = 卡片标题（不打），H1 之下的正文是打字目标**。
 
 ```md
----
-updated: YYYY-MM-DD
----
-
-# 索引
-
-## <标签 1>
+# 早起习惯
 
-| 卡组 | 卡片数 | 语言 | 摘要 | 更新 |
-|---|---|---|---|---|
-| [标题 1](material/<文件 1>.md) | 32 | en | 一行摘要 | YYYY-MM-DD |
-| [标题 2](material/<文件 2>.md) | 25 | zh | 一行摘要 | YYYY-MM-DD |
+Wake up early. Drink a glass of water. Start typing for ten minutes.
+Consistency beats intensity — that's how habits compound over time.
 
-## <标签 2>
+# 200 字自我介绍
 
-| 卡组 | 卡片数 | 语言 | 摘要 | 更新 |
-|---|---|---|---|---|
-| [标题 3](material/<文件 3>.md) | 40 | mixed | 一行摘要 | YYYY-MM-DD |
+Hello, my name is Alice. I'm a software engineer based in Shanghai.
 ```
 
-规则：
+| 层级 | 内容 |
+|---|---|
+| **H1** | 卡片标题 / 章节名（不打） |
+| **H1 之下** | 所有普通段落 = 打字目标 |
 
-- 一个标签一个 `##` 标题。**同一卡组可出现在多个标签**（tags 有多个时全部列出）。
-- 每个标签下**只有一个 markdown 表格**，不加别的内容。
-- 链接路径从仓库根起（`index.md` 就在仓库根）。
-- 摘要最多 60 字，一句话讲清卡组主题。
-- 卡片数以扫描实际卡片数为准。
+正文中可以有 `![](url)` 图片，图片会正常渲染但**不参与打字**（parser 提取时跳过）。
 
-### `log.md` 格式
+#### type: snippet
 
-`log.md` 在仓库根，按时间顺序追加（新条目追加在文件末尾），**绝不删除条目**。每次操作**必须**追加一条。
+短章卡。**结构和 article 完全一样**（H1 = 标题不打，H1 之下 = 打字目标），区别只在渲染：snippet 渲染时**居中显示、居中排版**，适合诗句、格言、口号、slogan、短小的独立段落。视觉上比 article 更像"海报"。
 
 ```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 张
+# Simplicity is the ultimate sophistication.
 
-## [YYYY-MM-DD] cascade | <触发卡组>
-- 影响: [卡组 X](material/<X>.md), [卡组 Y](material/<Y>.md)
-
-## [YYYY-MM-DD] check | N 条问题，M 条自动修复
-
-## [YYYY-MM-DD] level-up | <合并/拆分描述>
+Attributed to Leonardo da Vinci.
 ```
 
-规则：
-
-- 每次 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：切卡**
-
-读源后按材料类型切分：
+选 article 还是 snippet：段落自然阅读、有上下文流 → article；短小、独立、要视觉呼吸感 → snippet。
 
-- **词表** → 每个词一张 word 卡。IPA 从材料里抓；材料没给就查权威来源，实在不知道就留空并在 log 里报告。gloss 用简中。
-- **句子/例句集** → 每句一张 sentence 卡。translation 从材料里抓或自然翻译。
-- **文章 / 教程 / 代码片段** → 提炼要点，出 normal 卡。Q 是问题，A 是简短答案。避免答案超过 200 字符——超了拆成多张。
+#### type: qa
 
-**步骤 3：判断卡组归属**
+问答卡。**H1 = 卡片名，`## Q` = 题干，`## A` = 打字目标**。
 
-- 扫 `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。
+```md
+# 闭包
 
-### Check
+## Q
+什么是 JavaScript 中的闭包？请举一个实际例子。
 
-**用户跑 `qtype check` 报错时，Agent 修。**
+## A
+闭包是函数与其词法作用域的组合。当内部函数被外部引用时，词法作用域中的变量被保留在内存中。常见例子是计数器函数。
+```
 
-触发：用户跑 `qtype check`（详见 CLI 节），命令报错并把错误列表给 Agent。
+| 层级 | 内容 |
+|---|---|
+| **H1** | 卡片名（不打） |
+| **`## Q`** | 题干（markdown，可含图片，不打） |
+| **`## A`** | 打字目标（markdown） |
 
-**Agent 分类处理**：
+#### type: code
 
-**确定性问题（自动修）**：
+代码题。**同 qa 结构**，A 段里预期有 fenced code block，代码块内容 = 打字目标。
 
-- **不合法字符**：卡片答案含 emoji / 零宽 / 控制字符 → 删掉该字符或整张卡片（视上下文决定）。
-- **frontmatter 字段错误**：字段名拼错、类型错、缺必填字段 → 修字段。
-- **单词卡缺 phonetic/gloss、句子卡缺 translation** → 补上（补不出来时用 `TODO` 占位并在对话里报告）。
-- **答案 > 200 字符** → 拆成多张卡片，Q 段各写不同侧面提示。
-- **index.md 一致性**：卡组文件存在但 index 里没有 → 加条目；卡组数变了 → 更新 `卡片数`。
-- **内部链接失效**：目标不存在 → 搜 `material/` 下同名文件，唯一匹配则修；否则报告。
+````md
+# Two Sum
 
-**启发式问题（只报告）**：
+## Q
+给你一个整数数组 nums 和一个目标值 target，找出和为目标值的那两个整数的下标。
 
-- **重复卡片**：不同卡组里出现相同 Q + A 组合。报告，让用户决定合并还是保留。
-- **卡组过大**：卡片数 > 100 → 建议拆分。
-- **卡组过小**：卡片数 < 5 → 建议合并到相近卡组。
-- **孤立卡组**：卡组的 tag 在 index.md 里只被这一个卡组使用。可能是新主题，也可能是分类错。报告。
+## A
+```py
+class Solution:
+    def twoSum(self, nums, target):
+        seen = {}
+        for i, x in enumerate(nums):
+            if target - x in seen:
+                return [seen[target - x], i]
+            seen[x] = i
+```
+````
 
-**报告与日志**：给用户输出修复报告，末尾追加 `## [YYYY-MM-DD] check | N 条问题，M 条自动修复`。
+| 层级 | 内容 |
+|---|---|
+| **H1** | 题目名（不打） |
+| **`## Q`** | 题干（markdown，不打） |
+| **`## A`** | 包含一个 fenced code block；**代码内容 = 打字目标** |
 
-### Level-up
+代码块的语言 tag 用于 Shiki 高亮（`ts` / `py` / `go` 等）。
 
-**把散乱小卡组重构成有序的系列。**
+### 通用规则
 
-触发：用户说 "把这几个卡组合起来"、"这个卡组拆成初级/进阶两个"、"把 GRE 词表整理成 list 1/2/3"。
+- **卡片作者不用记"音标必须 inline code"这种约定**：结构一目了然
+- 打字目标里可以出现空格、换行（Enter）、Tab
+- 长度**建议**不超过 200 字符（每卡）——过长影响体验，拆卡
+- 只允许 OS 键盘（含中文 IME）能打出的字符
+- 全角中文标点会被工具自动规范化
 
-**步骤**
+### 富渲染（题干 / 正文可用，不参与打字）
 
-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 只重组，不改内容。用户手写的卡片（见守则）原样搬迁。
+打字目标之外的展示位置（`## Q` 题干、article / snippet 正文、gloss）支持 3 种富内容：
 
-**不做的事**
+- **Mermaid 流程图**：` ```mermaid ` 代码块，`publish build` 预渲染 SVG
+- **数学公式**：行内 `$…$`，块级 `$$…$$`，KaTeX 懒加载渲染（~280KB）
+- **代码块 / 图片 / 粗斜体**：标准 markdown
 
-- **不趁机改卡片内容**。level-up 只重组。要改内容用 Update。
-- **不删用户数据**：如果不确定要不要删旧文件，问用户。
+举例（`## Q` 里放公式，`## A` 打 ASCII）：
 
+```md
+---
+type: qa
+tags: [数学]
 ---
 
-## 守则
-
-### 禁令
-
-以下行为**严格禁止**：
+# 高斯积分
 
-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 里报告，不要编。
+## Q
+求以下积分：
 
-### 内容语言
+$$\int_{-\infty}^{\infty} e^{-x^2}\,dx = ?$$
 
-- 卡组的 `title`、`index.md` 摘要、`log.md` 条目：**中文为主，专业术语保留原文**。
-- 单词卡的 `gloss`：**简中**。
-- 句子卡的 `translation`：翻译到用户的母语（默认简中）。表意即可，不必逐字对齐。
-- 卡片的 `## A:` 答案文本本身：**由目标语言决定**，保留材料原样（英语词就是英语，日语句就是日语）。
+## A
+sqrt(pi)
+```
 
-### 卡片数量指导
+**渲染只在展示侧发生，打字目标（`## A` / word 的 H1 / 等等）依然只能是键盘能敲的字符**。
 
-- **一个卡组 20–50 张**是甜蜜区。
-- < 5 张：太薄，考虑合并（Level-up）。
-- \> 100 张：太厚，考虑拆分（Level-up）。
-- 一次 Ingest / Quiz-gen 生成的卡组通常 25 张左右——写多了反而质量下降。
+### 命名
 
-### 难度分级
+**素材文件名**：`material/<slug>.md`
 
-`difficulty` 字段的语义（默认 3）：
+- `<slug>`：主题的 kebab-case，小写，英文字母和短横线，最长 60 字符
+- 中文主题用英译或拼音
+- 同名冲突：末尾追加 `-2` / `-3`
 
-| 值 | 含义 |
-|---|---|
-| 1 | 极易识别，无需思考（如常见词、常识事实） |
-| 2 | 一眼可读，无需回忆（如常用短语、基础语法） |
-| 3 | 需要短暂回忆（默认，多数卡片） |
-| 4 | 需要认真思考或较长答案（如概念解释、句子造句） |
-| 5 | 高难度，长答案或复杂概念（如小段代码、长句默写） |
+### 链接
 
-### 快速参考
+- **只用 Markdown link**，不用 Wikilink
+- **绝不**用绝对路径（不以 `./` 或 `../` 开头的都不行）
+- 链接目标必须实际存在
 
-**Ingest 一个源**：
+### index.md 格式
 
-```
-raw/YYYY-MM-DD-<slug>.md          ← 写源（平铺，可选）
-material/<slug>.md                    ← 写或追加卡组
-index.md                           ← 更新表格（卡片数 / updated）
-log.md                             ← 追加 ## [日期] ingest | 标题
-```
+按标签分组，每次改动同步更新：
 
-**Update 一个卡组**：
+```md
+---
+updated: YYYY-MM-DD
+---
 
-```
-material/<slug>.md                    ← 追加/修正卡片，bump updated
-index.md                           ← 更新卡片数和 updated
-log.md                             ← 追加 ## [日期] update | 卡组名
-```
+# 索引
 
-**Quiz-gen 从主题**：
+## <标签 1>
 
-```
-material/<slug>.md                    ← 新建卡组
-index.md                           ← 加条目
-log.md                             ← 追加 ## [日期] quiz-gen | 主题
+| 素材 | 类型 | 卡片数 | 摘要 | 更新 |
+|---|---|---|---|---|
+| [标题 1](material/<文件 1>.md) | word | 32 | 摘要 | YYYY-MM-DD |
 ```
 
-**Check 用户报错时**：
+### log.md 格式
 
-```
-按错误列表分类修
-自动修：字符 / frontmatter / 长度 / index 一致性
-只报告：重复卡片 / 过大过小 / 孤立卡组
-log.md                             ← 追加 ## [日期] check | N 条问题
-```
+只追加：
 
-**Level-up 重构**：
-
-```
-读旧卡组 → 决策合并/拆分/重排
-写新 material/*.md
-rm 旧文件
-index.md                           ← 条目增减
-log.md                             ← 追加 ## [日期] level-up | 描述
+```md
+## [YYYY-MM-DD] ingest | <来源>
+- 新建: [素材 A](material/<A>.md) — N 张卡片
 ```
 
 ---
 
-## 给用户的 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 / Cascade / Check / Level-up
 
-**注意**：
+（保留原有语义 — 见操作节完整说明。核心变化：每次生成 material 时**先决定 type**，然后按对应结构写卡。）
 
-- 你在 ingest / update / quiz-gen 后**不需要**主动跑这些命令；用户 commit 时 CI 会跑。
-- 用户报 "check 说 XXX 卡片有非法字符"，定位到卡片并按 Check 操作节修。
-- 用户报 "publish serve 里练不了这张卡" — 通常是 A 段含不可打字符或者长度超限——按 Check 修。
+### 决定 type
 
----
+- 单词、词组、短语 → **word**
+- 单句、名言、格言 → **sentence**
+- 段落、文章、诗词 → **article**
+- 问答、面试题、概念解释 → **qa**
+- 代码题、算法题、片段 → **code**
 
-## 发布产物（仅作背景知识）
+**一个 material 只有一个 type**。混合内容拆成多个 material。
 
-`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`
+1. **不改 raw/ 内容**：默认只读
+2. **不写不可打字符**：emoji / 零宽字符 / 控制字符（除 Tab、Enter 外）禁止
+3. **不写太长的答案**：`## A:` 或 article 正文建议 ≤ 200 字符
+4. **不混主题**：一个 material 只装一个主题
+5. **不改用户手写卡片**：卡片正文含 `<!-- hand-edited -->` HTML 注释的 Agent 只能读、不能改
+6. **不用 Wikilink**
+7. **不绝对路径**
+8. **不主动 git commit / push**
+9. **不建规则外的目录**
+10. **不凭空造 IPA / 释义 / 翻译**：不确定的宁可空着
+11. **一个 material 只有一个 type**：不能混
+12. **没有 card-level frontmatter**：所有 per-card 信息都用 markdown 结构表达