@qnroa/qtype 0.0.1 → 0.0.3

package/templates/zh/README.md

@@ -30,7 +30,7 @@
 ├── TODO.md           # 待补清单（由 Agent 维护）
 ├── index.md          # 全库目录
 ├── log.md            # 活动日志（追加）
-├── material/            # 资料文件（每个 .md 一个 deck）
+├── material/            # 资料文件（每个 .md 一个 material）
 │   └── assets/<slug>/
 ├── raw/              # (可选) 原始材料，等 Agent 处理
 │   └── assets/<slug>/
@@ -41,12 +41,12 @@
 
 | 操作 | 触发 | 作用 |
 |---|---|---|
-| ingest    | `ingest <path-or-topic>` | 读材料/生成 → 建/更新 deck → 追加 log |
-| quiz-gen  | `按<主题>生成 <N> 张卡片` | 从主题生成新 deck |
-| update    | `修 <deck-slug> 里的 <字段>` | 修改现有 deck |
-| cascade   | `级联检查` | 修完一个 deck 后同步相关的 |
+| ingest    | `ingest <path-or-topic>` | 读材料/生成 → 建/更新 material → 追加 log |
+| quiz-gen  | `按<主题>生成 <N> 张卡片` | 从主题生成新 material |
+| update    | `修 <material-slug> 里的 <字段>` | 修改现有 material |
+| cascade   | `级联检查` | 修完一个 material 后同步相关的 |
 | check     | `check`（或直接跑 CLI） | 校验卡片格式 |
-| level-up  | `合并/拆分 <slug>` | 把太小/太大的 deck 重组 |
+| level-up  | `合并/拆分 <slug>` | 把太小/太大的 material 重组 |
 
 完整规则见 [QTYPE.md](./QTYPE.md)。
 

package/templates/zh/index.md

@@ -1,6 +1,6 @@
 # 全库目录
 
-<!-- 由 Agent 维护。按标签分组列出所有 deck。 -->
+<!-- 由 Agent 维护。按标签分组列出所有 material。 -->
 
 ## 未分类
 

package/templates/zh/material/article.md

@@ -0,0 +1,18 @@
+---
+title: 文章示例
+type: article
+tags: [示例, 文章]
+created: 2026-01-01
+updated: 2026-08-22
+---
+
+# 早起的习惯
+
+![清晨](./assets/article/sunrise.svg)
+
+早上起来做的第一件事,往往决定了一整天的状态。喝一杯水,做几分钟拉伸,然后坐下来打字十分钟。规律比强度更重要——习惯是这样一点一点复利出来的。
+
+# Morning ritual
+
+Wake up early. Drink a glass of water. Start typing for ten minutes.
+Consistency beats intensity — that is how habits compound over time.

package/templates/zh/material/assets/article/sunrise.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" aria-label="sunrise">
+  <line x1="15" y1="140" x2="185" y2="140" />
+  <path d="M55 140 A 45 45 0 0 1 145 140" />
+  <line x1="100" y1="60" x2="100" y2="45" />
+  <line x1="55" y1="80" x2="45" y2="70" />
+  <line x1="145" y1="80" x2="155" y2="70" />
+  <line x1="30" y1="115" x2="15" y2="115" />
+  <line x1="170" y1="115" x2="185" y2="115" />
+  <line x1="15" y1="165" x2="60" y2="165" />
+  <line x1="75" y1="165" x2="125" y2="165" />
+  <line x1="140" y1="165" x2="185" y2="165" />
+</svg>

package/templates/zh/material/assets/code/tree.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 260 200" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-label="binary tree">
+  <line x1="130" y1="35"  x2="70"  y2="90"  />
+  <line x1="130" y1="35"  x2="190" y2="90"  />
+  <line x1="70"  y1="90"  x2="35"  y2="150" />
+  <line x1="70"  y1="90"  x2="105" y2="150" />
+  <line x1="190" y1="90"  x2="225" y2="150" />
+  <circle cx="130" cy="35"  r="18" fill="var(--qt-base, #fff)" />
+  <circle cx="70"  cy="90"  r="18" fill="var(--qt-base, #fff)" />
+  <circle cx="190" cy="90"  r="18" fill="var(--qt-base, #fff)" />
+  <circle cx="35"  cy="150" r="18" fill="var(--qt-base, #fff)" />
+  <circle cx="105" cy="150" r="18" fill="var(--qt-base, #fff)" />
+  <circle cx="225" cy="150" r="18" fill="var(--qt-base, #fff)" />
+  <text x="130" y="40"  text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="14" fill="currentColor" stroke="none">1</text>
+  <text x="70"  y="95"  text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="14" fill="currentColor" stroke="none">2</text>
+  <text x="190" y="95"  text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="14" fill="currentColor" stroke="none">3</text>
+  <text x="35"  y="155" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="14" fill="currentColor" stroke="none">4</text>
+  <text x="105" y="155" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="14" fill="currentColor" stroke="none">5</text>
+  <text x="225" y="155" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="14" fill="currentColor" stroke="none">6</text>
+</svg>

package/templates/zh/material/assets/qa/login-flow.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 120" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-label="login flow">
+  <rect x="10"  y="35" width="70" height="50" rx="6" />
+  <rect x="125" y="35" width="70" height="50" rx="6" />
+  <rect x="240" y="35" width="70" height="50" rx="6" />
+  <text x="45"  y="65" text-anchor="middle" font-family="ui-sans-serif, system-ui" font-size="12" fill="currentColor" stroke="none">User</text>
+  <text x="160" y="65" text-anchor="middle" font-family="ui-sans-serif, system-ui" font-size="12" fill="currentColor" stroke="none">Client</text>
+  <text x="275" y="65" text-anchor="middle" font-family="ui-sans-serif, system-ui" font-size="12" fill="currentColor" stroke="none">Server</text>
+  <line x1="80"  y1="60" x2="120" y2="60" />
+  <polyline points="115,55 125,60 115,65" />
+  <line x1="195" y1="60" x2="235" y2="60" />
+  <polyline points="230,55 240,60 230,65" />
+  <text x="103" y="30" text-anchor="middle" font-family="ui-sans-serif, system-ui" font-size="10" fill="currentColor" stroke="none">creds</text>
+  <text x="217" y="30" text-anchor="middle" font-family="ui-sans-serif, system-ui" font-size="10" fill="currentColor" stroke="none">POST /login</text>
+  <line x1="240" y1="95" x2="80" y2="95" />
+  <polyline points="85,90 75,95 85,100" />
+  <text x="160" y="112" text-anchor="middle" font-family="ui-sans-serif, system-ui" font-size="10" fill="currentColor" stroke="none">token</text>
+</svg>

package/templates/zh/material/assets/sentence/pangram.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" aria-label="a-to-z">
+  <text x="100" y="90" text-anchor="middle" font-family="ui-serif, Georgia, serif" font-size="52" font-style="italic" fill="currentColor" stroke="none">A</text>
+  <text x="100" y="150" text-anchor="middle" font-family="ui-serif, Georgia, serif" font-size="52" font-style="italic" fill="currentColor" stroke="none">Z</text>
+  <line x1="80" y1="105" x2="120" y2="105" />
+  <path d="M60 170 Q 100 180 140 170" />
+</svg>

package/templates/zh/material/assets/snippet/moon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" aria-label="crescent moon">
+  <path d="M130 40 A 70 70 0 1 0 130 160 A 55 55 0 1 1 130 40 Z" />
+  <circle cx="55" cy="55" r="2" fill="currentColor" />
+  <circle cx="45" cy="90" r="1.6" fill="currentColor" />
+  <circle cx="75" cy="35" r="1.6" fill="currentColor" />
+  <circle cx="35" cy="135" r="2" fill="currentColor" />
+  <circle cx="60" cy="155" r="1.4" fill="currentColor" />
+</svg>

package/templates/zh/material/assets/word/apple.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" aria-label="apple">
+  <path d="M100 60 C 80 40, 55 50, 55 90 C 55 130, 80 165, 100 165 C 120 165, 145 130, 145 90 C 145 50, 120 40, 100 60 Z" />
+  <path d="M100 60 C 100 45, 105 30, 118 22" />
+  <path d="M100 60 C 92 52, 88 42, 90 30 C 100 30, 108 42, 108 52" fill="currentColor" fill-opacity="0.15" />
+</svg>

package/templates/zh/material/code.md

@@ -0,0 +1,55 @@
+---
+title: 代码示例
+type: code
+tags: [示例, 代码]
+created: 2026-01-01
+updated: 2026-08-22
+---
+
+# 二叉树中序遍历
+
+## Q
+参考下图,写出中序遍历的迭代实现:
+
+![二叉树](./assets/code/tree.svg)
+
+## A
+```py
+def inorder(root):
+    stack, result = [], []
+    while root or stack:
+        while root:
+            stack.append(root)
+            root = root.left
+        root = stack.pop()
+        result.append(root.val)
+        root = root.right
+    return result
+```
+
+# Two Sum
+
+## Q
+给你一个整数数组 nums 和一个目标值 target,找出和为目标值的两个整数的下标。
+
+## A
+```py
+def two_sum(nums, target):
+    seen = {}
+    for i, x in enumerate(nums):
+        if target - x in seen:
+            return [seen[target - x], i]
+        seen[x] = i
+```
+
+# Reverse a string
+
+## Q
+在 TypeScript 里写一个把字符串反转的函数。
+
+## A
+```ts
+function reverse(s: string): string {
+  return s.split('').reverse().join('')
+}
+```

package/templates/zh/material/qa.md

@@ -0,0 +1,33 @@
+---
+title: 问答示例
+type: qa
+tags: [示例, 问答]
+created: 2026-01-01
+updated: 2026-08-22
+---
+
+# 描述登录流程
+
+## Q
+根据下图描述用户登录流程:
+
+![登录流程](./assets/qa/login-flow.svg)
+
+## A
+用户输入账号密码,前端 POST /login,后端校验后返回 token。
+
+# 什么是闭包
+
+## Q
+用一句话解释 JavaScript 里的闭包。
+
+## A
+闭包是函数与它诞生时的词法作用域组合在一起——外层函数返回后,内部函数依然能访问外层的变量。
+
+# 事件循环
+
+## Q
+浏览器的事件循环大致是怎么运作的?
+
+## A
+主线程执行完当前任务后,从任务队列取出下一个任务运行;期间产生的微任务在任务之间清空。

package/templates/zh/material/sentence.md

@@ -0,0 +1,19 @@
+---
+title: 句子示例
+type: sentence
+tags: [示例, 句子]
+created: 2026-01-01
+updated: 2026-08-22
+---
+
+# The quick brown fox jumps over the lazy dog.
+## /ðə kwɪk braʊn fɑks/
+### 敏捷的棕色狐狸跳过懒狗——英文全字母句。
+#### ![A-Z](./assets/sentence/pangram.svg)
+
+# 熟能生巧。
+## /shú néng shēng qiǎo/
+### Practice makes perfect.
+
+# Simplicity is the ultimate sophistication.
+### 简约是复杂的终极形态。

package/templates/zh/material/snippet.md

@@ -0,0 +1,20 @@
+---
+title: 短章示例
+type: snippet
+tags: [示例, 短章]
+created: 2026-01-01
+updated: 2026-08-22
+---
+
+# 静夜思
+
+![月夜](./assets/snippet/moon.svg)
+
+床前明月光,
+疑是地上霜。
+举头望明月,
+低头思故乡。
+
+# Simplicity is the ultimate sophistication.
+
+— Attributed to Leonardo da Vinci

package/templates/zh/material/word.md

@@ -0,0 +1,20 @@
+---
+title: 单词示例
+type: word
+tags: [示例, 单词]
+created: 2026-01-01
+updated: 2026-08-22
+---
+
+# apple
+## /ˈæp.əl/
+### 苹果
+#### ![苹果](./assets/word/apple.svg)
+
+# ephemeral
+## /əˈfem(ə)rəl/
+### 短暂的,转瞬即逝的
+
+# 电脑
+## diàn nǎo
+### computer

package/dist/cli/commands/check/action.js

@@ -1,56 +0,0 @@
-/**
- * `qtype check` action — validate material files without writing anything.
- *
- * Reports:
- *   - Missing `material/` directory (fatal)
- *   - Cards with non-typable characters (fatal, non-zero exit)
- *
- * Exit code: 0 if clean, 1 if any issue was found. Designed to be dropped
- * into CI before `qtype publish build` so a bad card fails fast rather than
- * producing a broken site.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { info, success, fatal } from '../../utils/output.js';
-import { ensureQtypeRepo } from '../../utils/repoGuard.js';
-import { t } from '../../i18n/index.js';
-import { parseMaterial } from '../../../core/parser/parseMaterial.js';
-export async function checkAction(opts = {}) {
-    const root = ensureQtypeRepo(opts.repo ?? process.cwd());
-    info(t('check.msg.scanning', { path: root }));
-    const materialDir = path.join(root, 'material');
-    if (!fs.existsSync(materialDir)) {
-        fatal(t('err.dir.notExists', { path: materialDir }));
-    }
-    const files = fs
-        .readdirSync(materialDir)
-        .filter((f) => f.endsWith('.md'))
-        .map((f) => path.join(materialDir, f));
-    let cardTotal = 0;
-    const bad = [];
-    for (const file of files) {
-        const source = fs.readFileSync(file, 'utf-8');
-        const material = parseMaterial(source, path.relative(root, file));
-        cardTotal += material.cards.length;
-        material.cards.forEach((c, i) => {
-            if (c.unknownChars.length > 0) {
-                bad.push({
-                    file: path.relative(root, file),
-                    card: i + 1,
-                    chars: [...new Set(c.unknownChars)],
-                });
-            }
-        });
-    }
-    console.log('  ' + t('check.msg.summary', { materials: files.length, cards: cardTotal }));
-    if (bad.length > 0) {
-        console.log('\n  ' + t('check.msg.unknownChars', { count: bad.length }));
-        for (const b of bad.slice(0, 30)) {
-            console.log(`  • ${b.file} #${b.card}  →  ${b.chars.join(' ')}`);
-        }
-        if (bad.length > 30)
-            console.log(`  …and ${bad.length - 30} more`);
-        fatal(t('check.msg.failed', { count: bad.length }));
-    }
-    success(t('check.msg.ok'));
-}

package/dist/cli/commands/check/i18n.js

@@ -1,26 +0,0 @@
-export const messages = {
-    'zh-CN': {
-        'check.summary': '校验资料',
-        'check.description': '扫描目录下的 material/*.md，检查卡片格式是否合法',
-        'check.opt.repo': '仓库路径（默认当前目录）',
-        'check.example.basic': '校验当前仓库',
-        'check.example.repo': '校验指定路径',
-        'check.msg.scanning': '校验 {path}',
-        'check.msg.summary': '资料 {materials} · 卡片 {cards}',
-        'check.msg.unknownChars': '含无法练习的字符（{count} 张卡）：',
-        'check.msg.ok': '所有卡片通过校验。',
-        'check.msg.failed': '发现 {count} 个问题，请修复。',
-    },
-    'en-US': {
-        'check.summary': 'Validate materials',
-        'check.description': 'Scan material/*.md in the given directory and report card format issues',
-        'check.opt.repo': 'Repo path (default: current directory)',
-        'check.example.basic': 'Check the current repo',
-        'check.example.repo': 'Check an explicit path',
-        'check.msg.scanning': 'Checking {path}',
-        'check.msg.summary': 'materials {materials} · cards {cards}',
-        'check.msg.unknownChars': 'Non-typable chars ({count} card(s)):',
-        'check.msg.ok': 'All cards passed validation.',
-        'check.msg.failed': 'Found {count} issue(s); please fix.',
-    },
-};

package/dist/cli/commands/plugin/i18n.js

@@ -1,28 +0,0 @@
-export const messages = {
-    'zh-CN': {
-        'plugin.summary': '插件管理',
-        'plugin.description': '管理 qtype 插件：列表 / 启用 / 禁用（骨架，暂未接入插件系统）',
-        'plugin.list.summary': '列出插件',
-        'plugin.list.description': '列出所有已注册的插件及其状态',
-        'plugin.enable.summary': '启用插件',
-        'plugin.enable.description': '启用一个已注册的插件',
-        'plugin.disable.summary': '禁用插件',
-        'plugin.disable.description': '禁用一个已启用的插件',
-        'plugin.msg.noPlugins': '没有已注册的插件',
-        'plugin.msg.notImplemented': '插件系统尚未实现（qtype {phase}）',
-        'plugin.msg.notFound': '插件不存在：{id}',
-    },
-    'en-US': {
-        'plugin.summary': 'Plugin management',
-        'plugin.description': 'Manage qtype plugins: list / enable / disable (skeleton, plugin system not yet wired)',
-        'plugin.list.summary': 'List plugins',
-        'plugin.list.description': 'List all registered plugins and their status',
-        'plugin.enable.summary': 'Enable plugin',
-        'plugin.enable.description': 'Enable a registered plugin',
-        'plugin.disable.summary': 'Disable plugin',
-        'plugin.disable.description': 'Disable an enabled plugin',
-        'plugin.msg.noPlugins': 'No plugins registered',
-        'plugin.msg.notImplemented': 'Plugin system not yet implemented (qtype {phase})',
-        'plugin.msg.notFound': 'Plugin not found: {id}',
-    },
-};

package/dist/cli/commands/plugin/index.js

@@ -1,41 +0,0 @@
-import { t } from '../../i18n/index.js';
-import { info } from '../../utils/output.js';
-import { messages } from './i18n.js';
-const listCmd = {
-    name: 'list',
-    aliases: ['ls'],
-    summary: () => t('plugin.list.summary'),
-    describe: () => t('plugin.list.description'),
-    action: async () => {
-        info(t('plugin.msg.noPlugins'));
-    },
-};
-const enableCmd = {
-    name: 'enable',
-    summary: () => t('plugin.enable.summary'),
-    describe: () => t('plugin.enable.description'),
-    args: [{ flag: '<id>', describe: () => 'plugin id' }],
-    action: async (id) => {
-        info(t('plugin.msg.notImplemented', { phase: 'v0' }));
-        info(t('plugin.msg.notFound', { id }));
-        process.exitCode = 1;
-    },
-};
-const disableCmd = {
-    name: 'disable',
-    summary: () => t('plugin.disable.summary'),
-    describe: () => t('plugin.disable.description'),
-    args: [{ flag: '<id>', describe: () => 'plugin id' }],
-    action: async (id) => {
-        info(t('plugin.msg.notImplemented', { phase: 'v0' }));
-        info(t('plugin.msg.notFound', { id }));
-        process.exitCode = 1;
-    },
-};
-export const pluginCmd = {
-    name: 'plugin',
-    messages,
-    summary: () => t('plugin.summary'),
-    describe: () => t('plugin.description'),
-    subcommands: [listCmd, enableCmd, disableCmd],
-};

package/dist/core/typing/engine.js

@@ -1,112 +0,0 @@
-export function createState(target) {
-    return {
-        target,
-        typed: '',
-        cursor: 0,
-        correctCount: 0,
-        wrongCount: 0,
-        startedAt: null,
-        finishedAt: null,
-        composing: false,
-    };
-}
-export function beginComposition(s, now = Date.now()) {
-    return {
-        ...s,
-        startedAt: s.startedAt ?? now,
-        composing: true,
-    };
-}
-export function endComposition(s, committed, now = Date.now()) {
-    const next = commitChars(s, committed, now);
-    return { ...next, composing: false };
-}
-export function typeChar(s, ch, now = Date.now()) {
-    if (s.composing)
-        return s;
-    return commitChars(s, ch, now);
-}
-export function backspace(s) {
-    if (s.composing || s.cursor === 0)
-        return s;
-    const removed = s.typed[s.cursor - 1];
-    const expected = s.target[s.cursor - 1];
-    const wasCorrect = removed === expected;
-    return {
-        ...s,
-        typed: s.typed.slice(0, -1),
-        cursor: s.cursor - 1,
-        correctCount: wasCorrect ? s.correctCount - 1 : s.correctCount,
-        wrongCount: wasCorrect ? s.wrongCount : s.wrongCount - 1,
-        finishedAt: null,
-    };
-}
-function commitChars(s, chunk, now) {
-    if (!chunk)
-        return s;
-    let { cursor, correctCount, wrongCount, typed } = s;
-    const startedAt = s.startedAt ?? now;
-    const chars = Array.from(chunk);
-    for (const ch of chars) {
-        const expected = s.target[cursor];
-        if (expected === undefined)
-            break;
-        if (ch === expected)
-            correctCount++;
-        else
-            wrongCount++;
-        typed += ch;
-        cursor++;
-    }
-    const finishedAt = cursor >= s.target.length ? now : null;
-    return {
-        ...s,
-        typed,
-        cursor,
-        correctCount,
-        wrongCount,
-        startedAt,
-        finishedAt,
-    };
-}
-export function charStatus(s, index) {
-    if (index < s.cursor) {
-        return s.typed[index] === s.target[index] ? 'correct' : 'wrong';
-    }
-    if (index === s.cursor)
-        return 'current';
-    return 'pending';
-}
-// Sync the state to a full "typed so far" string (read from the contenteditable
-// editor on every input event, dazidazi-style). Recomputes correct/wrong counts
-// from scratch based on positional character comparison, so the caller doesn't
-// need to track incremental changes.
-export function syncTyped(s, typed, now = Date.now()) {
-    const chars = Array.from(typed);
-    let correctCount = 0;
-    let wrongCount = 0;
-    for (let i = 0; i < chars.length; i++) {
-        const expected = s.target[i];
-        if (expected === undefined) {
-            // Overflow — extra characters past target length count as wrong.
-            wrongCount++;
-            continue;
-        }
-        if (chars[i] === expected)
-            correctCount++;
-        else
-            wrongCount++;
-    }
-    const cursor = chars.length;
-    const startedAt = s.startedAt ?? (typed.length > 0 ? now : null);
-    const finished = cursor >= s.target.length && correctCount === s.target.length;
-    return {
-        ...s,
-        typed,
-        cursor,
-        correctCount,
-        wrongCount,
-        startedAt,
-        finishedAt: finished ? (s.finishedAt ?? now) : null,
-    };
-}