Tổng quan cách hoạt động

Cốt lõi của DevLingo là hệ thống “tra cứu phân tầng” thông minh: bắt đầu từ tra cứu nhanh cục bộ, nâng cấp dần lên suy luận AI. Nhờ đó, hầu hết tra cứu hoàn thành trong vài mili giây, tra cứu phức tạp cũng không quá 2 giây.

Quy trình hoàn chỉnh

Người dùng chọn văn bản trong bất kỳ ứng dụng nào
    ↓
[Kích hoạt] Nhấn phím tắt ⌘⇧D
    ↓
[Trích xuất] TextExtractor lấy:
    • Văn bản đã chọn
    • 50 ký tự ngữ cảnh trước và sau (để AI hiểu bối cảnh)
    • bundleIdentifier của ứng dụng hiện tại (Xcode / Slack / GitHub, v.v.)
    ↓
[Phân loại] InputTypeDetector xác định loại đầu vào:
    • Ngôn ngữ mẹ đẻ → chế độ Express
    • Một từ → chế độ Word
    • 2-4 từ và không có cấu trúc câu → chế độ Phrase
    • Câu hoàn chỉnh ≤20 từ → chế độ Sentence
    • Nhiều câu hoặc >20 từ → chế độ Paragraph
    ↓
[Tra cứu] LookupCoordinator tra cứu phân tầng (chi tiết bên dưới)
    ↓
[Hiển thị] FloatingPanelController:
    • Hiện cửa sổ nổi NSPanel bên dưới con trỏ chuột
    • Hiển thị skeleton screen (hoạt ảnh tải)
    • Chọn lớp View tương ứng theo chế độ (WordView / PhraseView / SentenceView, v.v.)
    • Khi dữ liệu đến, mờ dần hiển thị kết quả
    ↓
[Tương tác] Người dùng có thể:
    • Nhấn nút phát để nghe phát âm
    • Nhấn vào từ để tra cứu đệ quy
    • Lưu vào "sổ từ" (SwiftData)
    • Đóng cửa sổ nổi để tiếp tục làm việc

Hệ thống tra cứu phân tầng

Đây là chìa khóa hiệu suất của DevLingo. Tra cứu theo thứ tự ưu tiên, tìm thấy kết quả là trả về:

Tầng 1: Kho thuật ngữ kỹ thuật cục bộ (<50ms)

Với đầu vào tiếng Anh, đầu tiên tra cứu trong cơ sở dữ liệu SQLite cục bộ. Đã tích hợp sẵn 85+ thuật ngữ phát triển phổ biến:

idempotent, deployment, microservice, containerization,
latency, throughput, cache invalidation, API gateway,
circuit breaker, distributed tracing, ...

Tỷ lệ trúng khoảng 30% tra cứu từ vựng phát triển. Phản hồi cực nhanh.

Tầng 2: Kho cụm từ phát triển cục bộ (<100ms)

Với cụm từ 2-4 từ, tra cứu cơ sở dữ liệu cụm từ cục bộ (50+ cụm từ tích hợp sẵn):

yak shaving, bikeshedding, rubber ducking, code smell,
low-hanging fruit, technical debt, nerd sniping, ...

Tỷ lệ trúng khoảng 20% tra cứu cụm từ.

Tầng 3: Bộ nhớ đệm SwiftData (<10ms)

Từ vựng, cụm từ, câu mà người dùng đã tra cứu trước đó đều được lưu trong bộ nhớ đệm SwiftData cục bộ. Nếu tìm thấy, trả về ngay lập tức.

Đã tra cứu "idempotent" → lần sau tra cứu <10ms

Tỷ lệ trúng khoảng 50% (tùy thuộc lịch sử sử dụng).

Tầng 4: Claude API (0.5-2s)

Nếu ba tầng đầu đều không trúng, gọi Claude API để nhận phản hồi có cấu trúc.

Yêu cầu: {
  "text": "gracefully degrade",
  "mode": "phrase",
  "context": "when upstream dependencies are unavailable",
  "sourceApp": "Xcode",
  "userLanguage": "vi-VN"
}

Phản hồi: {
  "type": "phrase", // compound verb
  "definition_en": "...",
  "definition_vi": "...",
  "examples": [...],
  "pronunciation": {...},
  "register": "technical",
  "l1_tips": "..."
}

:::note Tại sao thiết kế phân tầng

95% từ vựng phổ biến trúng ba tầng đầu, <100ms trả về
5% từ vựng hiếm hoặc mới mới cần Claude API, nhưng cũng chỉ 1-2 giây
Không có mạng vẫn tra cứu được kho cục bộ và bộ nhớ đệm
Tiết kiệm hạn mức — Claude API tính phí theo lượt sử dụng, phân tầng giảm 95% cuộc gọi API :::

Kiến trúc backend

Backend của DevLingo được triển khai trên các node biên Cloudflare Workers, xử lý yêu cầu API.

Ứng dụng Mac
  ↓ HTTPS (Bearer token)
Cloudflare Workers (Edge)
  ├─ API Gateway (định tuyến Hono)
  ├─ Auth Middleware (xác thực JWT)
  ├─ Lookup Endpoint (/api/lookup)
  │   └─ Claude API Client (proxy yêu cầu AI)
  ├─ TTS Endpoint (/api/tts)
  │   └─ Google Cloud TTS (proxy tổng hợp phát âm)
  └─ Data Sync Endpoints
      └─ Cloudflare D1 (cơ sở dữ liệu người dùng)

Thành phần chính

Hono framework: Framework HTTP nhẹ, tối ưu cho Cloudflare Workers
Cơ sở dữ liệu D1: SQLite trên Cloudflare, lưu trữ sổ từ và dữ liệu đồng bộ
KV Storage: Token phiên, bộ nhớ đệm giới hạn tốc độ, bộ nhớ đệm phản hồi API
Proxy Claude API: Ứng dụng Mac proxy yêu cầu Claude qua Workers, tránh lộ API key cục bộ

Trích xuất văn bản và ngữ cảnh

TextExtractor sử dụng AXUIElement (macOS Accessibility API) để lấy:

Người dùng chọn trong Slack: "idempotent"

Kết quả trích xuất:
{
  "selectedText": "idempotent",
  "beforeContext": "We need to make sure this endpoint is ",
  "afterContext": " for retry requests.",
  "sourceApp": "com.tinyspeck.slackmacgap",  // Slack
  "fullSentence": "We need to make sure this endpoint is idempotent for retry requests."
}

Ngữ cảnh này được gửi đến Claude, giúp AI hiểu: “idempotent ở đây là trong bối cảnh thiết kế API”, chứ không phải gì khác.

Thuật toán phát hiện loại đầu vào

if văn bản chứa ngôn ngữ mẹ đẻ:
  → chế độ Express
elif số từ == 1:
  → chế độ Word
elif số từ in [2, 3, 4]:
  if chứa cấu trúc câu hoàn chỉnh:
    → chế độ Sentence
  else:
    → chế độ Phrase
elif số câu > 1 or số từ > 20:
  → chế độ Paragraph
else:
  → chế độ Sentence

:::tip Phát hiện thông minh Phát hiện đầu vào hoàn thành tức thì trên máy cục bộ, không cần gọi API. Đảm bảo người dùng không bao giờ cảm nhận được độ trễ của bước “xác định loại đầu vào”. :::

Hiển thị cửa sổ nổi

FloatingPanelController tạo một NSPanel (cửa sổ nổi):

Đặc tính:
• Hiển thị trên tất cả ứng dụng (Level: screenSaver)
• Vị trí: ngay dưới con trỏ chuột (y offset +20px, tránh che khuất)
• Trạng thái ban đầu: skeleton screen (khung xương tải)
• Dữ liệu đến: mờ dần vào, hủy skeleton
• Tương tác: truyền qua chuột hoàn toàn (không chặn ứng dụng nền)
• Cách đóng: nhấn bên ngoài, nhấn ESC, 5 phút không thao tác tự đóng

Mục tiêu hiệu suất

Tra cứu kho cục bộ: <50ms (phân vị thứ 99)
Trúng bộ nhớ đệm: <10ms
Đầu cuối hoàn chỉnh (bao gồm API): <2s (phân vị thứ 99)
Thời gian xuất hiện cửa sổ nổi: <300ms (nhanh theo cảm nhận người dùng)
Tạo âm thanh TTS: Lần đầu <2s, lần sau từ bộ nhớ đệm <100ms

:::note Chiến lược bộ nhớ đệm Âm thanh TTS cũng được lưu trong bộ nhớ đệm cục bộ và KV, phát âm của cùng một từ chỉ được tổng hợp một lần. :::

Quyền riêng tư dữ liệu

Văn bản người dùng
  ↓
Ứng dụng Mac (mã hóa HTTPS)
  ↓
Cloudflare Edge (xử lý tức thì)
  ├─ Yêu cầu Claude API (tạm thời, không dùng để huấn luyện)
  └─ Kết quả lưu vào KV (tự động hết hạn)
  ↓
Kết quả trả về Mac
  ↓
Lưu trữ SwiftData cục bộ (trong thiết bị, tùy chọn đồng bộ đám mây đến D1)

Nội dung văn bản không được lưu trữ, trừ khi người dùng chủ động lưu vào sổ từ. Xem chi tiết tại Quyền riêng tư và bảo mật dữ liệu.

Triết lý thiết kế kiến trúc của DevLingo là: “Nhanh là chính, AI là phụ, quyền riêng tư là trên hết”.