checkpoint before checking out main

2026-08-25 13:42:00 +08:00
parent 57844ce615
commit dccafe6f9e
105 changed files with 4302 additions and 1323 deletions
@@ -0,0 +1,188 @@
+// FrequentTermStore.swift
+// OSGKeyboard · Shared
+//
+// Small App Group sidecar for committed typing terms. Reading librime's
+// LevelDB userdb while the keyboard owns it can race the engine, so the
+// extension records eligible Chinese and English terms here and the host app
+// ranks them for personal-dictionary suggestions.
+
+import Foundation
+
+public struct FrequentTerm: Codable, Equatable, Identifiable, Sendable {
+    public var id: String { term.lowercased() }
+
+    public let term: String
+    public let commitCount: Int
+    public let firstSeenAt: Date
+    public let lastSeenAt: Date
+
+    public init(
+        term: String,
+        commitCount: Int,
+        firstSeenAt: Date,
+        lastSeenAt: Date
+    ) {
+        self.term = term
+        self.commitCount = commitCount
+        self.firstSeenAt = firstSeenAt
+        self.lastSeenAt = lastSeenAt
+    }
+}
+
+/// Captures repeated eligible commits without writing to the curated
+/// PersonalDictionary until the user explicitly confirms a suggestion.
+public final class FrequentTermStore: @unchecked Sendable {
+    public static let defaultsKey = "typing.frequentTerms.v2"
+    public static let legacyRimeDefaultsKey = "rimeTyping.frequentTerms.v1"
+    public static let minimumSuggestionCount = 2
+    public static let maximumTrackedTerms = 256
+
+    private let defaults: UserDefaults
+    private let lock = NSLock()
+
+    public init(defaults: UserDefaults = AppGroupStore().defaults) {
+        self.defaults = defaults
+    }
+
+    public func recordCommittedText(_ text: String, at date: Date = Date()) {
+        guard let term = Self.normalizedCandidate(from: text) else { return }
+
+        lock.lock()
+        defer { lock.unlock() }
+
+        var terms = loadLocked()
+        let key = term.lowercased()
+        if let index = terms.firstIndex(where: { $0.term.lowercased() == key }) {
+            let existing = terms[index]
+            terms[index] = FrequentTerm(
+                term: term,
+                commitCount: min(10_000, existing.commitCount + 1),
+                firstSeenAt: existing.firstSeenAt,
+                lastSeenAt: date
+            )
+        } else {
+            terms.append(
+                FrequentTerm(
+                    term: term,
+                    commitCount: 1,
+                    firstSeenAt: date,
+                    lastSeenAt: date
+                )
+            )
+        }
+
+        terms.sort { lhs, rhs in
+            if lhs.lastSeenAt != rhs.lastSeenAt {
+                return lhs.lastSeenAt > rhs.lastSeenAt
+            }
+            return lhs.commitCount > rhs.commitCount
+        }
+        saveLocked(Array(terms.prefix(Self.maximumTrackedTerms)))
+    }
+
+    /// Repeated, recent commits that are not already curated.
+    public func suggestions(
+        excludingPersonalTerms personalTerms: Set<String>,
+        limit: Int = 5
+    ) -> [FrequentTerm] {
+        guard limit > 0 else { return [] }
+        let excluded = Set(personalTerms.map { $0.lowercased() })
+
+        lock.lock()
+        let terms = loadLocked()
+        lock.unlock()
+
+        return terms
+            .filter {
+                $0.commitCount >= Self.minimumSuggestionCount
+                    && !excluded.contains($0.term.lowercased())
+            }
+            .sorted { lhs, rhs in
+                if lhs.commitCount != rhs.commitCount {
+                    return lhs.commitCount > rhs.commitCount
+                }
+                if lhs.lastSeenAt != rhs.lastSeenAt {
+                    return lhs.lastSeenAt > rhs.lastSeenAt
+                }
+                return lhs.term.localizedStandardCompare(rhs.term) == .orderedAscending
+            }
+            .prefix(limit)
+            .map { $0 }
+    }
+
+    public func clear() {
+        lock.lock()
+        defaults.removeObject(forKey: Self.defaultsKey)
+        defaults.removeObject(forKey: Self.legacyRimeDefaultsKey)
+        lock.unlock()
+    }
+
+    static func normalizedCandidate(from text: String) -> String? {
+        let term = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard (2...32).contains(term.count),
+              !commonTerms.contains(term.lowercased()),
+              !term.unicodeScalars.contains(where: {
+                  CharacterSet.whitespacesAndNewlines.contains($0)
+              }) else {
+            return nil
+        }
+
+        var semanticCharacterCount = 0
+        for scalar in term.unicodeScalars {
+            if HanScript.isIdeograph(scalar)
+                || (scalar.isASCII && CharacterSet.alphanumerics.contains(scalar)) {
+                semanticCharacterCount += 1
+                continue
+            }
+            // Product names, proper nouns, and English contractions commonly
+            // contain these separators.
+            guard allowedSeparators.contains(Character(String(scalar))) else {
+                return nil
+            }
+        }
+        return semanticCharacterCount >= 2 ? term : nil
+    }
+
+    private func loadLocked() -> [FrequentTerm] {
+        if let data = defaults.data(forKey: Self.defaultsKey),
+           let terms = try? JSONDecoder().decode([FrequentTerm].self, from: data) {
+            return terms
+        }
+
+        guard let legacyData = defaults.data(forKey: Self.legacyRimeDefaultsKey),
+              let legacyTerms = try? JSONDecoder().decode([FrequentTerm].self, from: legacyData) else {
+            return []
+        }
+
+        // The legacy value has the same Codable shape, so migration only
+        // changes its key and keeps every user's existing Chinese history.
+        saveLocked(legacyTerms)
+        defaults.removeObject(forKey: Self.legacyRimeDefaultsKey)
+        return legacyTerms
+    }
+
+    private func saveLocked(_ terms: [FrequentTerm]) {
+        guard let data = try? JSONEncoder().encode(terms) else { return }
+        defaults.set(data, forKey: Self.defaultsKey)
+    }
+
+    /// Avoid recommending ubiquitous conversational glue as a personal term.
+    private static let commonTerms: Set<String> = [
+        "a", "about", "after", "all", "also", "am", "an", "and", "any", "are",
+        "as", "at", "be", "because", "been", "but", "by", "can", "could", "did",
+        "do", "does", "for", "from", "get", "got", "had", "has", "have", "he",
+        "her", "here", "him", "his", "how", "i", "if", "in", "is", "it", "its",
+        "just", "me", "more", "my", "no", "not", "now", "of", "on", "one", "or",
+        "our", "out", "she", "so", "some", "than", "that", "the", "their", "them",
+        "then", "there", "they", "this", "to", "too", "up", "us", "was", "we",
+        "were", "what", "when", "where", "which", "who", "why", "will", "with",
+        "would", "you", "your",
+        "一个", "一下", "不会", "不是", "什么", "他们", "但是", "你们", "你好",
+        "可能", "可以", "因为", "好的", "如果", "已经", "应该", "怎么", "我们",
+        "所以", "时候", "明天", "昨天", "有点", "没有", "然后", "现在", "知道",
+        "自己", "觉得", "谢谢", "这个", "这里", "这样", "还是", "还有", "那个",
+        "那里", "那样", "需要", "今天", "就是"
+    ]
+
+    private static let allowedSeparators: Set<Character> = ["-", "'", ".", "+", "#", "·"]
+}