# Capabilities & Skills — 词刻 Cike

> What 词刻 Cike can do, organized by capability domain.

## 1. Vocabulary Learning

### 1.1 Multi-level word banks
- 小学 (Primary school): grade-aligned vocabulary
- 初中 (Middle school): primary + compulsory curriculum + 中考 words
- 高中 (High school): middle additions + high school / 高考 words (no primary duplicates)
- 四级 (CET-4): 3,807 deduplicated headwords (ECDICT cet4 tag)
- 六级 (CET-6): 5,349 deduplicated headwords (ECDICT cet6 tag)
- Total: 7,129 words in production database

### 1.2 Active recall system
- Default: type Chinese core meaning (主动回忆)
- Fallback: 4-option multiple choice (only when active recall fails or explicitly requested)
- 3,832 verified Chinese-English example sentence pairs for context encoding

### 1.3 FSRS spaced repetition
- Algorithm: FSRS (Free Spaced Repetition Scheduler) via ts-fsrs
- 6 independent skill dimensions per word:
  1. Pronunciation recognition (听音辨音)
  2. Reading aloud / production (朗读输出)
  3. Active meaning extraction (主动词义提取)
  4. Written discrimination (卷面辨义)
  5. Example sentence context (例句语境)
  6. Speed / fluency (速度流畅度)
- Earliest-due required skill determines overall review time
- Difficulty categories: 熟练·又快又准 / 一般·准确但慢 / 易错·很快却答错 / 未掌握·超时未答对
- Speed only rewards correct answers; fast wrong answers increase review priority

## 2. AI Pronunciation & Speech

### 2.1 Text-to-Speech (TTS)
- Engine: Deepgram Aura-2
- 10 curated American English voices:
  - Female: Harmonia (default), Thalia, Vesta, Callista, Luna
  - Male: Arcas (male default), Orpheus, Orion, Neptune, Aries
- Speeds: standard + 0.8× slow mode
- Example sentence reading (verified sentences only)
- Caching: R2 with custom CDN domain `audio.cike.ifq.ai`; SHA-256 content identity; global single-generation via Durable Object
- Fallback chain: R2 CDN → same-origin API → device `en-US` TTS (1.2s timeout) → Free Dictionary API human recordings

### 2.2 Speech-to-Text (STT) / pronunciation check
- Engine: Deepgram Nova-3 (en-US)
- Real-time transcription of learner's speech
- Only checks whether the target English word was pronounced clearly
- Chinese meaning verified locally with deterministic matching (not sent to AI)
- Deepgram confidence = transcription reliability, not phoneme-level accent score
- Results conservatively mapped to independent pronunciation skill's FSRS schedule

### 2.3 AI speaking practice (口语速记)
- Up to 5 words per session, selected by deterministic priority:
  - 到期加固 (due for reinforcement)
  - 薄弱补强 (weakness reinforcement)
  - 今日新词 (today's new words)
  - 拓展新词 (extension words)
- Course frozen at session start (no mid-session word swapping)
- Semantic judgment: GPT-5.4 mini (Deepgram Standard tier), difficulty adjusted by level (小学/初中/高中/四级/六级)
- ~3 minute target (not mechanical disconnect): system predicts whether next word can complete; near target, only current answer and feedback are finished
- 75s inactivity → natural exit; 5min → hard safety limit
- Disconnection does not create wrong-answer evidence

### 2.4 Voice Agent
- Real-time WebSocket relay for AI conversation practice
- 45-second signed tickets (HMAC, domain-separated), single-use admission
- Max one active session per learning profile
- Rate limited by account and IP

## 3. Adaptive Learning Engine

### 3.1 Initial assessment
- 20-word stratified placement test covering current word bank's difficulty range
- First-answer accuracy estimates known word count
- Adjusts first-round new word volume

### 3.2 New word scheduling
- Daily: due words first, then at most one new-word batch in 10/15/25-minute timebox
- New word cap: baseline from 7-day accuracy, then adjusted by word bank target and learning pace
- Challenge pace only increases volume after 90% accuracy, and never crowds out due reviews

### 3.3 Review queue
- Considers: due degree, predicted retrievability, error count, reaction speed, word difficulty
- Wrong words reappear within ~10 minutes
- Every 25 high-frequency-priority words = one sorting window; within window, 5 difficulty levels interleaved into 5-word groups

### 3.4 Learning profiles
- Each profile stores: current word bank target, background, learning pace
- Paces: 鼓励陪伴 (encouraging) / 稳定进阶 (steady) / 挑战冲刺 (challenge) — only adjust task intensity and feedback style, no personality labels
- Per-profile: TTS voice selection, ambient soundscape volume, theme color

## 4. Privacy & Security

### 4.1 Data minimization
- Audio: short recordings only forwarded to Deepgram during active checks with `mip_opt_out=true`; never stored in D1/R2/logs/profile
- Learning profile: only model, match level, confidence interval, duration (compact evidence)
- Chinese answers: always local deterministic judgment, never sent to any AI
- RUM: 1% anonymous, only numeric latency to Cloudflare Analytics Engine — no account/word/learning data

### 4.2 Authentication
- Supabase / MemFire cloud account (shared with 解释TV)
- 8-hour session: `httpOnly + Secure + SameSite=Lax + __Host-` prefix
- HMAC session verification at Cloudflare edge (no per-request Supabase call)
- AI cost quota bound to verified cloud user ID

### 4.3 Content Security
- Strict CSP: default-src 'self'; GA origins explicitly allowlisted
- X-Frame-Options: DENY
- X-Content-Type-Options: nosniff
- Referrer-Policy: strict-origin-when-cross-origin
- Permissions-Policy: camera=(), geolocation=(), microphone=(self), browsing-topics=()
- AI routes: logged-in + same-origin + in-bank target + supported audio, 160 KiB limit, account/IP dual rate limit, 8s upstream timeout, no-store

## 5. Infrastructure & Performance

### 5.1 Edge architecture
- Next.js 16 App Router + React 19, output: standalone
- Cloudflare Workers via OpenNext
- Vocabulary: Workers Static Assets binding (served after HMAC verification, no Next.js/D1)
- D1: vocabulary fallback, AI whitelist, health checks only
- R2: pronunciation audio (custom CDN domain)
- Static assets: hash-immutable cache (1 year)

### 5.2 Performance optimizations
- First vocabulary shard verifies then immediately learnable; remaining 3 shards concurrent fill
- Audio prefetch adaptive: 4G=2 words, 3G/unknown=1 word, 2G/data-saver=0 words
- No example sentence auto-generation
- Remote audio 1.2s timeout → device TTS fallback
- Turbopack for dev builds
- Tailwind CSS 4 (zero-config, JIT)

### 5.3 Offline resilience
- Browser persists complete successful vocabulary copies
- Active study rounds tolerate short disconnections
- Old Service Worker and static homepage cache auto-cleaned on client
- After logout, cannot re-enter study page via offline shell

## 6. Accessibility & UX

### 6.1 Accessibility
- Skip-to-content link
- Semantic HTML structure
- Keyboard navigation support
- `prefers-color-scheme` aware (light theme primary)
- `prefers-reduced-motion` respected
- ARIA labels on interactive elements
- Focus visible styles

### 6.2 UX features
- Ambient soundscapes: soft white noise, rain night, night insect chirps (seamless local loops)
- Auto-duck during reading, auto-near-silence before recording
- Per-account volume memory, fade in/out, background pause
- Theme colors per profile (chrome color swaps dynamically)
- Points only reward real progress: accurate recall, speed improvement, due review completion
- No random lottery, no punitive streak system

## 7. Self-test & Diagnostics

`/selftest` (user-initiated, not indexed) verifies:
1. Secure origin
2. Microphone access
3. Audio context
4. Device English TTS voice
5. Aura-2 pronunciation generation
6. Aura-2 → Nova-3 loopback
7. AI Agent 45-second signed ticket
8. Same-origin WebSocket relay
9. Workers Assets vocabulary
10. D1 health status

Degraded capabilities only show as "limited" — device issues are never misreported as learning failures.

## 8. For Developers

- **Repo**: https://github.com/peixl/cike_word
- **Framework**: Next.js 16 + React 19 + TypeScript 5.9 + Tailwind CSS 4
- **Runtime**: Node.js >=22.13.0, Cloudflare Workers (OpenNext)
- **Database**: SQLite (local) / Cloudflare D1 (production)
- **AI SDKs**: @deepgram/agents, @supabase/ssr, @supabase/supabase-js
- **Testing**: Node.js built-in test runner (`node --test`)
- **Linting**: ESLint 9 + eslint-config-next
- **Type checking**: `tsc --noEmit`
- **Build**: `npm run build` (CLOUDFLARE_BUILD=1)
- **Local dev**: `npm run dev` (requires `.dev.vars` with Supabase config + signing secret)
- **Deploy**: GitHub main → Cloudflare Workers Builds → `npx wrangler deploy`

*Last updated: 2026-08-25*