typingnorm 0.1.0__py3-none-any.whl

typingnorm/__init__.py

@@ -0,0 +1,19 @@
+"""typingnorm — 人類打字的常模，以及據此判斷輸入是否為真人的判準。
+
+`profile.json` 是常模本身：擬合自 KeyRecs（CC BY 4.0，可商業使用）的擊鍵時序分佈。
+`detect.check()` 拿觀測到的擊鍵去比對常模。`simulate` 反過來從常模抽樣產生擊鍵，
+主要用途是給偵測端當測試對手。
+
+每條判準的誤判率都在另一份獨立資料集（Aalto 136M Keystrokes，2,245 位受試者）上
+量過，方法與數字見 METHOD.md。
+"""
+
+from .detect import RULES, Report, check
+from .metrics import (DEFAULT_METRIC, METRICS, Session, all_scores,
+                      load_session, score)
+
+__version__ = "0.1.0"
+__all__ = [
+    "check", "Report", "RULES",
+    "score", "all_scores", "Session", "load_session", "METRICS", "DEFAULT_METRIC",
+]

typingnorm/detect.py

@@ -0,0 +1,192 @@
+"""判斷一段擊鍵輸入是否具有合成的跡象。
+
+設計原則有三條，都是被資料逼出來的，不是選來好看的。
+
+**只用速度不變的判準。** 打字快與慢的人，rollover、間隔、dwell 全都差很多。任何
+「離人類平均多遠」的判準都會系統性誤判速度極端的人，那恰好是最不該被誤判的族群。
+
+**優先用物理上不可能，而不是統計上罕見。** 同一個實體鍵不可能在放開前再次按下；
+每個鍵按住的時間不可能完全一樣。這類判準跟打字快慢無關。
+
+**回報訊號，不回報布林值。** 一個回傳 is_human 的函式會誘導呼叫端拿它當閘門，而
+這種方法只擋得住不用心的自動化。刻意模仿的程式可以通過全部判準。
+
+每條判準的誤判率都在 Aalto 136M Keystrokes 的 2,245 位受試者上量過，見 METHOD.md
+第 7.2 節。誤判率寫在 RULES 裡，呼叫端據此決定要不要採信。
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Iterable, Literal, Sequence
+
+# 選字、確認、切換輸入法的鍵不是產生文字的擊鍵，一律排除
+NAV_PREFIXES = ("Arrow", "Meta", "Shift", "Control", "Alt", "Tab", "Escape",
+                "Enter", "Page", "Home", "End", "CapsLock", "Fn", "OS")
+# 修飾鍵左右手同碼名的問題：左右 Shift 若被正規化成同一個名字，會產生假的同鍵重疊
+MODIFIERS = ("Shift", "Control", "Alt", "Meta", "OS", "CapsLock", "Fn")
+
+MIN_KEYSTROKES = 150      # 低於此樣本數不下任何結論
+ROLLOVER_MIN_WPM = 35.0   # 慢速真人本來就接近零重疊，這條判準不適用
+MIN_HUMAN_DWELL_MS = 5.0  # 真人 dwell 中位數約 91ms，低於這個值是物理上不可能
+
+Verdict = Literal["human-consistent", "synthetic-signals", "insufficient-data"]
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    what: str
+    false_positive: float | None   # 在 2,245 位真人上的誤判率，None 表示未量測
+
+
+RULES = {
+    "same_key_overlap": Rule(
+        "same_key_overlap",
+        "同一個實體鍵在放開前又被按下。手指做不到，作業系統的行為也未定義。",
+        0.0000,
+    ),
+    "constant_dwell": Rule(
+        "constant_dwell",
+        "按住時間不像真的：每個鍵按住的時間幾乎完全一樣，或短到物理上不可能。"
+        "真人的 dwell 變異係數沒有低於 0.05 的，中位數也沒有低於 20ms 的。",
+        0.0000,
+    ),
+    "zero_rollover": Rule(
+        "zero_rollover",
+        "完全沒有按鍵重疊。只在 35 WPM 以上套用，因為慢速真人本來就接近零。",
+        0.0031,
+    ),
+}
+
+
+@dataclass
+class Report:
+    verdict: Verdict
+    flags: list[str] = field(default_factory=list)
+    measures: dict[str, float | None] = field(default_factory=dict)
+    n_keystrokes: int = 0
+    note: str = ""
+
+    @property
+    def false_positive_budget(self) -> float:
+        """觸發的判準當中最高的誤判率。呼叫端用它決定要不要採信這次判定。"""
+        rates = [RULES[f].false_positive for f in self.flags
+                 if RULES[f].false_positive is not None]
+        return max(rates) if rates else 0.0
+
+    def as_dict(self) -> dict:
+        return {
+            "verdict": self.verdict,
+            "flags": [{"rule": f, "what": RULES[f].what,
+                       "false_positive": RULES[f].false_positive} for f in self.flags],
+            "measures": self.measures,
+            "n_keystrokes": self.n_keystrokes,
+            "note": self.note,
+        }
+
+
+def _is_nav(code: str) -> bool:
+    return code.startswith(NAV_PREFIXES)
+
+
+def _is_modifier(code: str) -> bool:
+    return code.startswith(MODIFIERS)
+
+
+def _pair(events: Sequence[tuple]) -> tuple[list[tuple[float, float, str]], int]:
+    """把事件配成 (按下, 放開, 鍵碼)。回傳配對結果與同鍵重疊的次數。
+
+    事件一律先按時間戳排序：瀏覽器的派送順序與時間戳不一致，實測看過時間戳較早的
+    keyup 在較晚的事件之後才送達。
+    """
+    ordered = sorted(events, key=lambda e: e[0])
+    down: dict[str, float] = {}
+    presses: list[tuple[float, float, str]] = []
+    overlaps = 0
+
+    for t, kind, code, *_ in ordered:
+        if kind not in ("D", "U"):
+            raise ValueError(f"事件類型必須是 'D' 或 'U'，收到 {kind!r}")
+        if kind == "D":
+            if code in down and not _is_modifier(code):
+                # 修飾鍵排除在外，因為左右 Shift 常被正規化成同一個名字，
+                # 那會製造假的重疊。實測 2,245 人裡有 15 人因此被誤判。
+                overlaps += 1
+            down[code] = t
+        else:
+            start = down.pop(code, None)
+            if start is not None:
+                presses.append((start, t, code))
+
+    presses.sort()
+    return presses, overlaps
+
+
+def _cv(xs: Sequence[float]) -> float | None:
+    if len(xs) < 2:
+        return None
+    m = sum(xs) / len(xs)
+    if m <= 0:
+        return None
+    return math.sqrt(sum((x - m) ** 2 for x in xs) / len(xs)) / m
+
+
+def check(events: Iterable[tuple], min_keystrokes: int = MIN_KEYSTROKES) -> Report:
+    """檢查一段擊鍵事件。
+
+    events 是 (時間毫秒, 'D' 或 'U', 實體鍵碼, 可省略的 key) 的序列。**鍵碼必須是
+    實體鍵**（瀏覽器的 event.code），不是字元，否則同鍵重疊那條判準會失準。
+
+    回傳的是訊號不是判決。verdict 為 human-consistent 只代表沒有觸發任何判準，
+    不代表對方一定是人：刻意模仿真人時序的程式可以全部通過。
+    """
+    presses, overlaps = _pair(events)
+    text = [p for p in presses if not _is_nav(p[2])]
+
+    if len(text) < min_keystrokes:
+        return Report(
+            verdict="insufficient-data",
+            n_keystrokes=len(text),
+            note=f"只有 {len(text)} 次擊鍵，低於 {min_keystrokes} 的門檻。"
+                 f"樣本不足時所有統計都不可靠，不應據此下任何結論。",
+        )
+
+    dwell = [(u - d) for d, u, _ in text]
+    iki = [text[i + 1][0] - text[i][0] for i in range(len(text) - 1)]
+    rollover = sum(1 for i in range(len(text) - 1) if text[i + 1][0] < text[i][1])
+    mean_iki = sum(iki) / len(iki) if iki else 0.0
+    wpm = 12000.0 / mean_iki if mean_iki > 0 else 0.0
+    roll_pct = rollover / len(iki) * 100 if iki else 0.0
+    dwell_cv = _cv(dwell)
+
+    flags: list[str] = []
+    if overlaps > 0:
+        flags.append("same_key_overlap")
+    dwell_median = sorted(dwell)[len(dwell) // 2] if dwell else 0.0
+    # 變異係數在 dwell 全為零時無定義，而全為零正是最退化的合成輸入，
+    # 所以要另外擋。只看變異係數會讓這種輸入整條溜過去。
+    if dwell_median < MIN_HUMAN_DWELL_MS or (dwell_cv is not None and dwell_cv < 0.05):
+        flags.append("constant_dwell")
+    if rollover == 0 and wpm >= ROLLOVER_MIN_WPM:
+        flags.append("zero_rollover")
+
+    note = ("觸發的判準只證明這串輸入不像手打的。沒有觸發也不證明是人，"
+            "刻意模仿真人時序的程式可以通過全部判準。")
+    if not flags and wpm < ROLLOVER_MIN_WPM:
+        note += f" 另外此次速度 {wpm:.0f} WPM 低於 {ROLLOVER_MIN_WPM:.0f}，零重疊判準未套用。"
+
+    return Report(
+        verdict="synthetic-signals" if flags else "human-consistent",
+        flags=flags,
+        measures={
+            "wpm": round(wpm, 1),
+            "iki_median_ms": round(sorted(iki)[len(iki) // 2], 1) if iki else None,
+            "dwell_median_ms": round(dwell_median, 1) if dwell else None,
+            "dwell_cv": round(dwell_cv, 4) if dwell_cv is not None else None,
+            "rollover_pct": round(roll_pct, 2),
+            "same_key_overlaps": overlaps,
+        },
+        n_keystrokes=len(text),
+        note=note,
+    )

typingnorm/metrics.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""打字速度指標。以下常數與規則的來源見 METHOD.md。
+
+每個語言有慣用的算法，使用者也可以切換成別的。
+
+設計前提：**永遠不存分數，只存原始事件**。分數是顯示時才從事件流算出來的。
+任何一個地方存了分數，之後換算法就得重收資料。
+
+每個指標都是純函式 (Session) -> float。要加新語言就加一個函式，不動其他東西。
+
+單位的來源分兩種，`authoritative` 欄位標示得很清楚：
+  True  出自國家級認證機構，數字對當地人有意義（80 字/分是 TQC 專業級）
+  False 業界慣例或本站自訂，介面上不得出現「合格」「專業級」這類字眼
+"""
+import json
+import sys
+from dataclasses import dataclass, field
+
+# 注音符號與聲調，用來判斷哪些擊鍵屬於組字過程
+BOPOMOFO = set(range(0x3105, 0x3130)) | {0x02C7, 0x02CA, 0x02CB, 0x02D9}
+# 韓文字母，타수 是按字母鍵計數（한 = ㅎ+ㅏ+ㄴ = 3 타）
+HANGUL_JAMO = set(range(0x3131, 0x3164))
+
+
+@dataclass
+class Session:
+    """一次練習的原始紀錄。這是唯一被儲存的東西。"""
+    language: str                    # zh-TW / en / ja / ko / hi / th ...
+    script: str                      # han-trad / latin / kana / hangul / thai ...
+    input_method: str                # zhuyin / pinyin / direct / inscript / telex ...
+    layout: str                      # qwerty / dachen / kedmanee / dubeolsik ...
+    prompt: str                      # 題目原文
+    typed: str                       # 實際打出的內容
+    seconds: float                   # 從第一次按鍵到最後一次按鍵
+    keystrokes: int                  # 按下的總次數，含修正與組字
+    events: list = field(default_factory=list)   # [(t, 'D'|'U', code, key)]
+
+    def correct_chars(self):
+        """逐位置比對，回傳正確字元數。"""
+        return sum(1 for a, b in zip(self.prompt, self.typed) if a == b)
+
+    def errors(self):
+        """錯打、多打、漏打合計。顛倒字需要更細的比對，見 TQC 規則。"""
+        wrong = sum(1 for a, b in zip(self.prompt, self.typed) if a != b)
+        return wrong + abs(len(self.prompt) - len(self.typed))
+
+    def minutes(self):
+        return max(self.seconds, 1e-9) / 60.0
+
+
+# ---------------------------------------------------------------------------
+# 指標實作
+# ---------------------------------------------------------------------------
+
+def kpm(s):
+    """每分鐘擊鍵數。唯一在所有書寫系統都成立的指標，因為每種文字都用鍵盤打。
+    字數與詞數都是各語言自己的抽象，擊鍵數才是共同分母，跨語言比較要用這個。"""
+    return s.keystrokes / s.minutes()
+
+
+def wpm_net_5(s):
+    """英文慣例：五個字元算一個詞，淨速度扣掉錯誤。印地文與阿拉伯文沿用。"""
+    return (s.correct_chars() / 5 - s.errors() / 5) / s.minutes()
+
+
+def kdph_ssc(s):
+    """印度公職考試的正式單位：每小時按鍵次數。
+    SSC CHSL 英文門檻 10,500 KDPH（= 35 WPM），印地文 9,000（= 30 WPM）。
+    換算關係 KDPH = WPM × 300。"""
+    return s.keystrokes * 3600.0 / max(s.seconds, 1e-9)
+
+
+def cpm_tqc(s):
+    """台灣 TQC 中文輸入：每分鐘淨字數，每錯一次扣 0.5 字。
+    錯誤率 ≥ 10% 該次成績不予計算，此處回傳 0 表示不計。
+    級別：實用 15、進階 30、專業 80。"""
+    total = max(len(s.prompt), 1)
+    if s.errors() / total >= 0.10:
+        return 0.0
+    return max(0.0, s.correct_chars() - 0.5 * s.errors()) / s.minutes()
+
+
+def cpm_jp(s):
+    """日文：純字数／分。全商速度部門 1 級為 10 分鐘 700 字，即 70 字/分。"""
+    return max(0.0, s.correct_chars() - s.errors()) / s.minutes()
+
+
+def tasu(s):
+    """韓文 타수：按字母鍵計數，不是按字計數。
+    「한」是 ㅎ+ㅏ+ㄴ 三打。所以這個指標只能從擊鍵流算，從輸出文字算不出來。
+    워드프로세서 1 급門檻 300 타，一般成人 200 到 300。"""
+    jamo = sum(1 for e in s.events
+               if e[1] == 'D' and e[3] and ord(e[3][0]) in HANGUL_JAMO)
+    return (jamo or s.keystrokes) / s.minutes()
+
+
+def wpm_4(s):
+    """泰文慣例：四個字元算一個詞。來源只有社群與練習網站，非官方標準。"""
+    return (s.correct_chars() / 4 - s.errors() / 4) / s.minutes()
+
+
+def cpm_raw(s):
+    """每分鐘正確字元數。沒有當地標準時的中性預設。"""
+    return s.correct_chars() / s.minutes()
+
+
+METRICS = {
+    'kpm':        (kpm,        '打鍵/分',  False, '跨語言比較用的共同分母'),
+    'wpm_net_5':  (wpm_net_5,  'WPM',      False, '英文慣例，五字元一詞'),
+    'kdph_ssc':   (kdph_ssc,   'KDPH',     True,  'SSC 公職考試，10500 = 35 WPM'),
+    'cpm_tqc':    (cpm_tqc,    '字/分',    True,  'TQC，專業級 80'),
+    'cpm_jp':     (cpm_jp,     '字/分',    True,  '全商速度部門，1 級 70'),
+    'tasu':       (tasu,       '타수',     True,  '워드프로세서 1급 300'),
+    'wpm_4':      (wpm_4,      'คำ/นาที',  False, '泰文社群慣例，四字元一詞'),
+    'cpm_raw':    (cpm_raw,    '字元/分',  False, '中性預設'),
+}
+
+# 語言的預設指標。使用者可以切換成 METRICS 裡的任何一個。
+DEFAULT_METRIC = {
+    'zh-TW': 'cpm_tqc', 'zh-HK': 'cpm_tqc', 'zh-CN': 'cpm_raw',
+    'ja': 'cpm_jp', 'ko': 'tasu', 'hi': 'kdph_ssc',
+    'en': 'wpm_net_5', 'ar': 'wpm_net_5', 'th': 'wpm_4', 'vi': 'kpm',
+}
+
+
+def score(session, metric=None):
+    """算分。不指定就用該語言的慣用指標。"""
+    key = metric or DEFAULT_METRIC.get(session.language, 'cpm_raw')
+    fn, unit, authoritative, note = METRICS[key]
+    return {
+        'metric': key, 'value': round(fn(session), 1), 'unit': unit,
+        'authoritative': authoritative, 'note': note,
+    }
+
+
+def all_scores(session):
+    """全部算一遍，給切換用。介面只是換一個已經算好的值，不用重打。"""
+    return [score(session, k) for k in METRICS]
+
+
+# ---------------------------------------------------------------------------
+
+def _demo():
+    """對照公開的門檻值驗算，公式錯了這裡就會失敗。"""
+    # 印度 SSC：35 WPM 英文應該剛好是 10,500 KDPH
+    en = Session('en', 'latin', 'direct', 'qwerty',
+                 prompt='x' * 175, typed='x' * 175, seconds=60,
+                 keystrokes=175)
+    assert abs(score(en, 'wpm_net_5')['value'] - 35.0) < 0.01
+    assert abs(score(en, 'kdph_ssc')['value'] - 10500.0) < 1
+
+    # 印地文 30 WPM 應該是 9,000 KDPH
+    hi = Session('hi', 'devanagari', 'inscript', 'inscript',
+                 prompt='x' * 150, typed='x' * 150, seconds=60, keystrokes=150)
+    assert abs(score(hi)['value'] - 9000.0) < 1
+    assert score(hi)['authoritative'] is True
+
+    # TQC：80 字全對，一分鐘，應為專業級 80
+    tw = Session('zh-TW', 'han-trad', 'zhuyin', 'dachen',
+                 prompt='字' * 80, typed='字' * 80, seconds=60, keystrokes=320)
+    assert abs(score(tw)['value'] - 80.0) < 0.01
+    # 錯四個字：正確 76、錯誤 4，扣 2 字，應為 74
+    tw_err = Session('zh-TW', 'han-trad', 'zhuyin', 'dachen',
+                     prompt='字' * 80, typed='字' * 76 + '錯' * 4,
+                     seconds=60, keystrokes=320)
+    assert abs(score(tw_err)['value'] - 74.0) < 0.01
+    # 錯誤率達 10% 不予計算
+    tw_bad = Session('zh-TW', 'han-trad', 'zhuyin', 'dachen',
+                     prompt='字' * 80, typed='字' * 72 + '錯' * 8,
+                     seconds=60, keystrokes=320)
+    assert score(tw_bad)['value'] == 0.0
+
+    # 韓文：타수 從擊鍵流算。「한」三個字母鍵，打二十次即 60 타/分
+    ev = [(i * 100.0, 'D', 'KeyR', c) for i, c in enumerate('ㅎㅏㄴ' * 20)]
+    ko = Session('ko', 'hangul', 'direct', 'dubeolsik',
+                 prompt='한' * 20, typed='한' * 20, seconds=60,
+                 keystrokes=60, events=ev)
+    assert abs(score(ko)['value'] - 60.0) < 0.01
+
+    # 同一場練習換指標，值要跟著換，原始資料完全沒動
+    assert len({s['metric'] for s in all_scores(tw)}) == len(METRICS)
+
+    print('metrics 自檢通過：SSC / TQC / 全商 / 워드프로세서 的門檻換算都對得上')
+    print()
+    print('同一場練習（TQC 專業級 80 字/分）換成各種指標：')
+    for s in all_scores(tw):
+        flag = '官方' if s['authoritative'] else '慣例'
+        print(f"  {s['metric']:11s} {s['value']:9.1f} {s['unit']:9s} [{flag}] {s['note']}")
+
+
+
+
+def load_session(path):
+    """從 session JSON 載入。欄位缺漏在這裡就會炸，不會拖到分析階段才發現。"""
+    with open(path, encoding='utf-8') as f:
+        d = json.load(f)
+    for k in ('schema', 'session_id', 'locale', 'prompt', 'typed', 'events'):
+        if k not in d:
+            raise ValueError(f'{path} 缺少必填欄位 {k}')
+    ev = sorted(d['events'], key=lambda e: e[0])   # 派送順序不可信，一律重排
+    downs = [e for e in ev if e[1] == 'D']
+    return Session(
+        language=d['locale']['language'], script=d['locale']['script'],
+        input_method=d['locale']['input_method'], layout=d['locale']['layout'],
+        prompt=d['prompt'], typed=d['typed'],
+        seconds=(ev[-1][0] - ev[0][0]) / 1000.0 if ev else 0.0,
+        keystrokes=len(downs), events=[(e[0], e[1], e[2], e[3]) for e in ev],
+    )
+
+
+if __name__ == '__main__':
+    if len(sys.argv) > 1 and sys.argv[1] == '--json':
+        print(json.dumps({k: {'unit': v[1], 'authoritative': v[2], 'note': v[3]}
+                          for k, v in METRICS.items()}, ensure_ascii=False, indent=2))
+    else:
+        _demo()

typingnorm/profile.json

@@ -0,0 +1,108 @@
+{
+  "schema": 1,
+  "source": {
+    "name": "KeyRecs: A keystroke dynamics and typing pattern recognition dataset",
+    "authors": "Dias, Vitorino, Maia, Sousa, Praça",
+    "venue": "Data in Brief, 2023",
+    "doi": "10.1016/j.dib.2023.109509",
+    "url": "https://zenodo.org/records/7886743",
+    "license": "CC BY 4.0",
+    "commercial_use": true
+  },
+  "sample": {
+    "participants": 99,
+    "digraphs": 562372,
+    "wpm_median": 48.5
+  },
+  "speed_definition": "級距以受試者的吞吐量指派：WPM = 12 / mean(IKI)。模型取該級距的 iki_median 當對數常態的中位數（mu = ln(iki_median)），長尾由停頓層補上，因為真實 IKI 分佈比對數常態更尖峰厚尾。",
+  "bands": {
+    "30": {
+      "sigma": 0.7117,
+      "iki_median": 0.246,
+      "dwell_letter": 0.083,
+      "cv": 0.839,
+      "rollover_pct": 2.0,
+      "n": 68400
+    },
+    "40": {
+      "sigma": 0.7052,
+      "iki_median": 0.204,
+      "dwell_letter": 0.09,
+      "cv": 0.877,
+      "rollover_pct": 10.7,
+      "n": 133730
+    },
+    "50": {
+      "sigma": 0.6343,
+      "iki_median": 0.178,
+      "dwell_letter": 0.095,
+      "cv": 0.85,
+      "rollover_pct": 13.1,
+      "n": 130292
+    },
+    "60": {
+      "sigma": 0.612,
+      "iki_median": 0.155,
+      "dwell_letter": 0.096,
+      "cv": 0.816,
+      "rollover_pct": 22.5,
+      "n": 112555
+    },
+    "70": {
+      "sigma": 0.5773,
+      "iki_median": 0.14,
+      "dwell_letter": 0.087,
+      "cv": 0.798,
+      "rollover_pct": 22.2,
+      "n": 49268
+    },
+    "80": {
+      "sigma": 0.6267,
+      "iki_median": 0.122,
+      "dwell_letter": 0.092,
+      "cv": 0.817,
+      "rollover_pct": 31.0,
+      "n": 43255
+    }
+  },
+  "dwell": {
+    "letter_sigma": 0.3429,
+    "space": [
+      0.091,
+      0.3263
+    ],
+    "shift": [
+      0.254,
+      0.4404
+    ],
+    "backspace": [
+      0.079,
+      0.3394
+    ]
+  },
+  "error": {
+    "backspaces_per_char": [
+      0.0676,
+      0.0472,
+      0.0906
+    ],
+    "note": "中位數 / p25 / p75。模型的 error_rate 應校準到重現中位數"
+  },
+  "transition": {
+    "same_hand": 1.1287,
+    "alternate_hand": 0.8904,
+    "same_finger": 1.0723
+  },
+  "lexical": {
+    "rare_word": 1.0474,
+    "common_word": 0.9141,
+    "word_edge": 0.9366,
+    "word_middle": 1.0778
+  },
+  "counts": {
+    "transition": 298920,
+    "lexical": 167252,
+    "position": 167252,
+    "dwell_letter": 413757
+  }
+}

typingnorm/session_schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "humantype practice session",
+  "description": "一次打字練習的原始紀錄。只存量測到的東西，不存任何分數：分數是顯示時才依所選指標從事件流算出來的，這樣換算法或加新指標都不必重收資料。也不存使用者自己寫的文字，因為題目是出好的。",
+  "type": "object",
+  "required": ["schema", "session_id", "started_at", "locale", "prompt_id",
+               "prompt", "typed", "events"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": 1 },
+    "session_id": {
+      "type": "string",
+      "description": "匿名亂數 ID，不連結到任何身分"
+    },
+    "started_at": { "type": "string", "format": "date-time" },
+    "consent": {
+      "type": "object",
+      "description": "同意公開釋出的版本與時間。缺這一項的工作階段不得進入公開資料集。",
+      "required": ["version", "granted_at", "redistribution"],
+      "properties": {
+        "version": { "type": "string" },
+        "granted_at": { "type": "string", "format": "date-time" },
+        "redistribution": { "type": "boolean" }
+      }
+    },
+    "locale": {
+      "type": "object",
+      "required": ["language", "script", "input_method", "layout"],
+      "properties": {
+        "language": { "type": "string", "examples": ["zh-TW", "en", "ja", "ko", "hi", "th", "vi", "ar"] },
+        "script": { "type": "string", "examples": ["han-trad", "han-simp", "latin", "kana", "hangul", "devanagari", "thai", "arabic"] },
+        "input_method": { "type": "string", "examples": ["zhuyin", "pinyin", "cangjie", "direct", "inscript", "remington", "telex", "vni", "romaja"] },
+        "layout": { "type": "string", "examples": ["qwerty", "azerty", "dvorak", "dachen", "eten", "dubeolsik", "kedmanee", "pattachote"] }
+      }
+    },
+    "prompt_id": { "type": "string" },
+    "prompt": { "type": "string", "description": "題目原文" },
+    "typed": { "type": "string", "description": "實際打出的內容，用來比對正確率" },
+    "commits": {
+      "type": "array",
+      "description": "組字型輸入法專用：每個字上屏的時刻與用掉的擊鍵數。直打型語言留空。",
+      "items": {
+        "type": "object",
+        "required": ["i", "char", "t", "keys"],
+        "properties": {
+          "i": { "type": "integer" },
+          "char": { "type": "string" },
+          "t": { "type": "number", "description": "毫秒，相對於第一次按鍵" },
+          "keys": { "type": "integer" },
+          "code": { "type": "string", "description": "打出這個字用的輸入碼，例如 ㄐㄧㄣ" }
+        }
+      }
+    },
+    "events": {
+      "type": "array",
+      "description": "原始按鍵事件，依 timeStamp 排序。瀏覽器的派送順序與時間戳不一致，寫入前必須排序。",
+      "items": {
+        "type": "array",
+        "prefixItems": [
+          { "type": "number", "description": "毫秒，相對於第一次按鍵" },
+          { "enum": ["D", "U"], "description": "按下或放開" },
+          { "type": "string", "description": "實體鍵，event.code" },
+          { "type": "string", "description": "event.key，組字時會是注音符號等" }
+        ],
+        "minItems": 4, "maxItems": 4
+      }
+    },
+    "client": {
+      "type": "object",
+      "properties": {
+        "ua": { "type": "string" },
+        "timer_resolution_ms": { "type": "number" }
+      }
+    }
+  }
+}