应用的皮肤不能删除

2：修改键盘AI点击必须要登录装填

.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "Bash(git checkout:*)",
+      "Bash(xcodebuild:*)",
+      "Bash(plutil:*)",
+      "Bash(find:*)",
+      "Bash(ls:*)",
+      "Bash(wc:*)"
+    ]
+  }
+}

.home/Library/Logs/CoreSimulator/CoreSimulator.com.apple.dt.xcodebuild.log

@@ -0,0 +1,17 @@
+Dec 18 13:42:00 macbookpro com.apple.dt.xcodebuild[42901] <Error>: Unable to deliver request ({
+	    "developer_dir" = "/Applications/Xcode.app/Contents/Developer";
+	    request = "set_developer_dir";
+	}) because we are not connected to CoreSimulatorService.
+Dec 18 13:42:00 macbookpro com.apple.dt.xcodebuild[42901] <Warning>: Unable to discover any Simulator runtimes. Developer Directory is /Applications/Xcode.app/Contents/Developer.
+Dec 18 13:42:00 macbookpro com.apple.dt.xcodebuild[42901] <Error>: Could not kickstart simdiskimaged; SimDiskImageManager services will not be available: Error Domain=NSPOSIXErrorDomain Code=53 "Software caused connection abort" UserInfo={NSLocalizedDescription=Error returned in reply from CoreSimulatorService: Connection invalid}
+Dec 18 13:42:00 macbookpro com.apple.dt.xcodebuild[42901] <Error>: simdiskimaged returned error (invalid), marking disconnected.
+Dec 18 13:42:00 macbookpro com.apple.dt.xcodebuild[42901] <Error>: simdiskimaged returned error (invalid), marking disconnected.
+Dec 18 13:42:00 macbookpro com.apple.dt.xcodebuild[42901] <Error>: Could not get list of trusted mount directories: Error Domain=com.apple.CoreSimulator.SimError Code=410 "The service used to manage runtime disk images (simdiskimaged) crashed or is not responding" UserInfo={NSLocalizedDescription=The service used to manage runtime disk images (simdiskimaged) crashed or is not responding}
+Dec 18 13:42:00 macbookpro com.apple.dt.xcodebuild[42901] <Error>: Unable to deliver request ({
+	    request = "notification_subscription";
+	    "set_path" = "/Users/mac/Library/Developer/CoreSimulator/Devices";
+	}) because we are not connected to CoreSimulatorService.
+Dec 18 13:42:00 macbookpro com.apple.dt.xcodebuild[42901] <Error>: Unable to deliver request ({
+	    request = "notification_subscription";
+	    "set_path" = "/Users/mac/Library/Developer/CoreSimulator/Devices";
+	}) because we are not connected to CoreSimulatorService.

CustomKeyboard/CustomKeyboard.entitlements

@@ -2,10 +2,17 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-    <key>keychain-access-groups</key>
-    <array>
-        <string>$(AppIdentifierPrefix)com.loveKey.nyx.shared</string>
-    </array>
+	<key>com.apple.developer.associated-domains</key>
+	<array>
+		<string>applinks:app.tknb.net</string>
+	</array>
+	<key>com.apple.security.application-groups</key>
+	<array>
+		<string>group.com.loveKey.nyx</string>
+	</array>
+	<key>keychain-access-groups</key>
+	<array>
+		<string>$(AppIdentifierPrefix)com.loveKey.nyx.shared</string>
+	</array>
 </dict>
 </plist>
-

CustomKeyboard/Info.plist

@@ -2,6 +2,12 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
+	<key>LSApplicationQueriesSchemes</key>
+	<array>
+		<string>kbkeyboardAppExtension</string>
+	</array>
+	<key>NSMicrophoneUsageDescription</key>
+	<string>需要使用麦克风进行语音输入</string>
 	<key>NSExtension</key>
 	<dict>
 		<key>NSExtensionAttributes</key>

CustomKeyboard/KeyboardAssets.xcassets/App_icon.imageset/Contents.json

@@ -0,0 +1,23 @@
+{
+  "images" : [
+    {
+      "filename" : "App_icon.png",
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "App_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "App_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/Contents.json

@@ -0,0 +1,6 @@
+{
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/ai_key_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "切图 271@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "切图 271@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/ai_limit_close.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "ai_limit_close@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "ai_limit_close@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/ai_limit_goto.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "ai_limit_goto@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "ai_limit_goto@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/ai_limit_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "ai_limit_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "ai_limit_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/back_keybord_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "back_keybord_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "back_keybord_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/buy_sel_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "buy_sel_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "buy_sel_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/close_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "close_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "close_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/home_ai_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "home_ai_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "home_ai_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/home_chat_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "home_chat_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "home_chat_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/home_emotion_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "home_emotion_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "home_emotion_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/home_keyboard_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "home_keyboard_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "home_keyboard_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/kb_del_icon.imageset/Contents.json

@@ -0,0 +1,86 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "appearances" : [
+        {
+          "appearance" : "luminosity",
+          "value" : "light"
+        }
+      ],
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "appearances" : [
+        {
+          "appearance" : "luminosity",
+          "value" : "dark"
+        }
+      ],
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "kb_del_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "appearances" : [
+        {
+          "appearance" : "luminosity",
+          "value" : "light"
+        }
+      ],
+      "filename" : "kb_del_icon@2x 1.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "appearances" : [
+        {
+          "appearance" : "luminosity",
+          "value" : "dark"
+        }
+      ],
+      "filename" : "切图 256@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "kb_del_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    },
+    {
+      "appearances" : [
+        {
+          "appearance" : "luminosity",
+          "value" : "light"
+        }
+      ],
+      "filename" : "kb_del_icon@3x 1.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    },
+    {
+      "appearances" : [
+        {
+          "appearance" : "luminosity",
+          "value" : "dark"
+        }
+      ],
+      "filename" : "切图 256@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/kb_zt_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "kb_zt_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "kb_zt_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/key_revoke.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "key_revoke@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "key_revoke@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/keybord_bg_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "keybord_bg_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "keybord_bg_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardAssets.xcassets/upgrad_vip_icon.imageset/Contents.json

@@ -0,0 +1,22 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "upgrad_vip_icon@2x.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "filename" : "upgrad_vip_icon@3x.png",
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

CustomKeyboard/KeyboardViewController.m

@@ -5,216 +5,237 @@
 //  Created by Mac on 2025/10/27.
 //
 
-#import "KeyboardViewController.h"
-#import "KBKeyBoardMainView.h"
+#import "KeyboardViewController+Private.h"
 
-#import "KBKey.h"
-#import "KBFunctionView.h"
-#import "KBSettingView.h"
-#import "Masonry.h"
-#import "KBAuthManager.h"
+#import "KBBackspaceUndoManager.h"
+#import "KBChatLimitPopView.h"
+#import "KBChatPanelView.h"
 #import "KBFullAccessManager.h"
+#import "KBFunctionView.h"
+#import "KBInputBufferManager.h"
+#import "KBKeyBoardMainView.h"
+#import "KBKeyboardSubscriptionView.h"
+#import "KBLocalizationManager.h"
+#import "KBSkinManager.h"
+#import "KBSuggestionEngine.h"
+#import <SDWebImage/SDWebImage.h>
 
-static CGFloat KEYBOARDHEIGHT = 256 + 20;
+#if DEBUG
+#import <mach/mach.h>
+#endif
 
-@interface KeyboardViewController () <KBKeyBoardMainViewDelegate, KBFunctionViewDelegate>
-@property (nonatomic, strong) UIButton *nextKeyboardButton; // 系统“下一个键盘”按钮（可选）
-@property (nonatomic, strong) KBKeyBoardMainView *keyBoardMainView;   // 功能面板视图（点击工具栏第0个时显示）
-@property (nonatomic, strong) KBFunctionView *functionView;   // 功能面板视图（点击工具栏第0个时显示）
-@property (nonatomic, strong) KBSettingView *settingView;     // 设置页
-@end
+#if DEBUG
+static NSInteger sKBKeyboardVCAliveCount = 0;
+
+static uint64_t KBPhysFootprintBytes(void) {
+  task_vm_info_data_t vmInfo;
+  mach_msg_type_number_t count = TASK_VM_INFO_COUNT;
+  kern_return_t kr = task_info(mach_task_self(), TASK_VM_INFO,
+                               (task_info_t)&vmInfo, &count);
+  if (kr != KERN_SUCCESS) {
+    return 0;
+  }
+  return (uint64_t)vmInfo.phys_footprint;
+}
+
+static NSString *KBFormatMB(uint64_t bytes) {
+  double mb = (double)bytes / 1024.0 / 1024.0;
+  return [NSString stringWithFormat:@"%.1fMB", mb];
+}
+#endif
 
 @implementation KeyboardViewController
 
 {
-    BOOL _kb_didTriggerLoginDeepLinkOnce;
+  BOOL _kb_didTriggerLoginDeepLinkOnce;
+#if DEBUG
+  BOOL _kb_debugDidCountAlive;
+#endif
 }
 
 - (void)viewDidLoad {
-    [super viewDidLoad];
-    [self setupUI];
-    // 指定 HUD 的承载视图（扩展里无法取到 App 的 KeyWindow）
-    [KBHUD setContainerView:self.view];
-    // 绑定完全访问管理器，便于统一感知和联动网络开关
-    [[KBFullAccessManager shared] bindInputController:self];
-    __unused id token = [[NSNotificationCenter defaultCenter] addObserverForName:KBFullAccessChangedNotification object:nil queue:[NSOperationQueue mainQueue] usingBlock:^(__unused NSNotification * _Nonnull note) {
-        // 如需，可在此刷新与完全访问相关的 UI
-    }];
+  [super viewDidLoad];
+#if DEBUG
+  if (!_kb_debugDidCountAlive) {
+    _kb_debugDidCountAlive = YES;
+    sKBKeyboardVCAliveCount += 1;
+  }
+  NSLog(@"[Keyboard] KeyboardViewController viewDidLoad alive=%ld self=%p mem=%@",
+        (long)sKBKeyboardVCAliveCount, self, KBFormatMB(KBPhysFootprintBytes()));
+#endif
+  // 撤销删除是“上一段删除操作”的临时状态；键盘被系统回收/重建或跨页面回来时应当清空，避免误显示。
+  [[KBBackspaceUndoManager shared] registerNonClearAction];
+  [self setupUI];
+  self.suggestionEngine = [KBSuggestionEngine shared];
+  self.currentWord = @"";
+  // 指定 HUD 的承载视图（扩展里无法取到 App 的 KeyWindow）
+  [KBHUD setContainerView:self.view];
+  // 绑定完全访问管理器，便于统一感知和联动网络开关
+  [[KBFullAccessManager shared] bindInputController:self];
+  self.kb_fullAccessObserverToken = [[NSNotificationCenter defaultCenter]
+      addObserverForName:KBFullAccessChangedNotification
+                  object:nil
+                   queue:[NSOperationQueue mainQueue]
+              usingBlock:^(__unused NSNotification *_Nonnull note){
+                  // 如需，可在此刷新与完全访问相关的 UI
+              }];
+
+  // 皮肤变化时，立即应用
+  __weak typeof(self) weakSelf = self;
+  self.kb_skinObserverToken = [[NSNotificationCenter defaultCenter]
+      addObserverForName:KBSkinDidChangeNotification
+                  object:nil
+                   queue:[NSOperationQueue mainQueue]
+              usingBlock:^(__unused NSNotification *_Nonnull note) {
+                __strong typeof(weakSelf) self = weakSelf;
+                if (!self) {
+                  return;
+                }
+                [self kb_applyTheme];
+              }];
+  [self kb_applyTheme];
+  [self kb_registerDarwinSkinInstallObserver];
+  [self kb_consumePendingShopSkin];
+  [self kb_applyDefaultSkinIfNeeded];
 }
 
-
-- (void)setupUI {
-    // 固定键盘整体高度
-    [self.view.heightAnchor constraintEqualToConstant:KEYBOARDHEIGHT].active = YES;
-    // 预置功能面板（默认隐藏），与键盘区域共享相同布局
-    self.functionView.hidden = YES;
-    [self.view addSubview:self.functionView];
-    [self.functionView mas_makeConstraints:^(MASConstraintMaker *make) {
-        make.left.right.equalTo(self.view);
-        make.top.equalTo(self.view).offset(4);
-        make.bottom.equalTo(self.view.mas_bottom).offset(-4);
-    }];
-    
-    [self.view addSubview:self.keyBoardMainView];
-    [self.keyBoardMainView mas_makeConstraints:^(MASConstraintMaker *make) {
-        make.left.right.equalTo(self.view);
-        make.top.equalTo(self.view).offset(4);
-        make.bottom.equalTo(self.view.mas_bottom).offset(-4);
-    }];
+- (void)didReceiveMemoryWarning {
+  [super didReceiveMemoryWarning];
+  // 扩展进程内存上限较小：在系统发出内存警告时主动清理可重建的缓存，降低被系统杀死概率。
+  self.kb_cachedGradientImage = nil;
+  [self.kb_defaultGradientLayer removeFromSuperlayer];
+  self.kb_defaultGradientLayer = nil;
+  [[KBSkinManager shared] clearRuntimeImageCaches];
+  [[SDImageCache sharedImageCache] clearMemory];
 }
 
+- (void)viewWillAppear:(BOOL)animated {
+  [super viewWillAppear:animated];
+  // FIX: iOS 26 键盘闪烁问题 —— 恢复键盘正确高度
+  // setupUI 中高度初始为 0（防止系统预渲染快照闪烁），此处恢复为实际键盘高度。
+  // 此时系统已准备好键盘滑入动画，恢复高度后键盘将正常从底部滑入。
+  CGFloat portraitWidth = [self kb_portraitWidth];
+  CGFloat keyboardHeight = [self kb_keyboardHeightForWidth:portraitWidth];
+  if (self.kb_heightConstraint) {
+    self.kb_heightConstraint.constant = keyboardHeight;
+  }
+  // 进入/重新进入输入界面时，清理上一次会话残留的撤销状态与缓存，避免显示“撤销删除”但实际上已不可撤销。
+  [[KBBackspaceUndoManager shared] registerNonClearAction];
+  [[KBInputBufferManager shared] resetWithText:@""];
+  [[KBLocalizationManager shared] reloadFromSharedStorageIfNeeded];
+  // 键盘再次出现时，恢复 HUD 容器与主题（viewDidDisappear 里可能已清理图片/缓存）。
+  [KBHUD setContainerView:self.view];
+  [self kb_ensureKeyBoardMainViewIfNeeded];
+  [self kb_applyTheme];
+#if DEBUG
+  NSLog(@"[Keyboard] viewWillAppear self=%p mem=%@",
+        self, KBFormatMB(KBPhysFootprintBytes()));
+#endif
+  // 注意：微信/QQ 等宿主的 documentContext 可能是“截断窗口”，这里只更新
+  // liveText，不要把它当作全文 manualSnapshot。
+  [[KBInputBufferManager shared]
+      updateFromExternalContextBefore:self.textDocumentProxy
+                                          .documentContextBeforeInput
+                                after:self.textDocumentProxy
+                                          .documentContextAfterInput];
+}
 
+- (void)viewWillDisappear:(BOOL)animated {
+  [super viewWillDisappear:animated];
+  [[KBBackspaceUndoManager shared] registerNonClearAction];
+  [self kb_releaseMemoryWhenKeyboardHidden];
+#if DEBUG
+  NSLog(@"[Keyboard] viewWillDisappear self=%p mem=%@",
+        self, KBFormatMB(KBPhysFootprintBytes()));
+#endif
+}
 
-#pragma mark - Private
+- (void)viewDidDisappear:(BOOL)animated {
+  [super viewDidDisappear:animated];
+  // 再兜底一次，防止某些宿主只触发 willDisappear 而未触发 didDisappear。
+  [self kb_releaseMemoryWhenKeyboardHidden];
+}
 
-/// 切换显示功能面板/键盘主视图
-- (void)showFunctionPanel:(BOOL)show {
-    // 简单显隐切换，复用相同的布局区域
-    self.functionView.hidden = !show;
-    self.keyBoardMainView.hidden = show;
-    
-    // 可选：把当前显示的视图置顶，避免层级遮挡
-    if (show) {
-        [self.view bringSubviewToFront:self.functionView];
-    } else {
-        [self.view bringSubviewToFront:self.keyBoardMainView];
+- (void)traitCollectionDidChange:(UITraitCollection *)previousTraitCollection {
+  [super traitCollectionDidChange:previousTraitCollection];
+  if (@available(iOS 13.0, *)) {
+    if (previousTraitCollection.userInterfaceStyle !=
+        self.traitCollection.userInterfaceStyle) {
+      self.kb_cachedGradientImage = nil;
+      [self kb_applyDefaultSkinIfNeeded];
     }
+  }
 }
 
-/// 显示/隐藏设置页（高度与 keyBoardMainView 一致），右侧滑入/滑出
-- (void)showSettingView:(BOOL)show {
-    if (show) {
-        //        if (!self.settingView) {
-        self.settingView = [[KBSettingView alloc] init];
-        self.settingView.hidden = YES;
-        [self.view addSubview:self.settingView];
-        [self.settingView mas_makeConstraints:^(MASConstraintMaker *make) {
-            // 与键盘主视图完全等同的区域，保证高度、宽度一致
-            make.edges.equalTo(self.keyBoardMainView);
-        }];
-        [self.settingView.backButton addTarget:self action:@selector(onTapSettingsBack) forControlEvents:UIControlEventTouchUpInside];
-        //        }
-        [self.view bringSubviewToFront:self.settingView];
-        // 以 keyBoardMainView 的实际宽度为准，避免首次添加时 self.view 宽度尚未计算
-        [self.view layoutIfNeeded];
-        CGFloat w = CGRectGetWidth(self.keyBoardMainView.bounds);
-        if (w <= 0) { w = CGRectGetWidth(self.view.bounds); }
-        if (w <= 0) { w = [UIScreen mainScreen].bounds.size.width; }
-        self.settingView.transform = CGAffineTransformMakeTranslation(w, 0);
-        self.settingView.hidden = NO;
-        [UIView animateWithDuration:0.25 delay:0 options:UIViewAnimationOptionCurveEaseOut animations:^{
-            self.settingView.transform = CGAffineTransformIdentity;
-        } completion:nil];
-    } else {
-        if (!self.settingView || self.settingView.hidden) return;
-        CGFloat w = CGRectGetWidth(self.keyBoardMainView.bounds);
-        if (w <= 0) { w = CGRectGetWidth(self.view.bounds); }
-        if (w <= 0) { w = [UIScreen mainScreen].bounds.size.width; }
-        [UIView animateWithDuration:0.22 delay:0 options:UIViewAnimationOptionCurveEaseIn animations:^{
-            self.settingView.transform = CGAffineTransformMakeTranslation(w, 0);
-        } completion:^(BOOL finished) {
-            self.settingView.hidden = YES;
-        }];
-    }
+- (void)textDidChange:(id<UITextInput>)textInput {
+  [super textDidChange:textInput];
+  [[KBInputBufferManager shared]
+      updateFromExternalContextBefore:self.textDocumentProxy
+                                          .documentContextBeforeInput
+                                after:self.textDocumentProxy
+                                          .documentContextAfterInput];
 }
 
-
-
-// MARK: - KBKeyBoardMainViewDelegate
-- (void)keyBoardMainView:(KBKeyBoardMainView *)keyBoardMainView didTapKey:(KBKey *)key {
-    switch (key.type) {
-        case KBKeyTypeCharacter:
-            [self.textDocumentProxy insertText:key.output ?: key.title ?: @""]; break;
-        case KBKeyTypeBackspace:
-            [self.textDocumentProxy deleteBackward]; break;
-        case KBKeyTypeSpace:
-            [self.textDocumentProxy insertText:@" "]; break;
-        case KBKeyTypeReturn:
-            [self.textDocumentProxy insertText:@"\n"]; break;
-        case KBKeyTypeGlobe:
-            [self advanceToNextInputMode]; break;
-        case KBKeyTypeCustom:
-            // 点击自定义键（如“AI”）切换到功能面板
-            [self showFunctionPanel:YES];
-            break;
-        case KBKeyTypeModeChange:
-        case KBKeyTypeShift:
-            // 这些已在 KBKeyBoardMainView/KBKeyboardView 内部处理
-            break;
-    }
-}
-
-- (void)keyBoardMainView:(KBKeyBoardMainView *)keyBoardMainView didTapToolActionAtIndex:(NSInteger)index {
-    if (index == 0) {
-        [self showFunctionPanel:YES];
-    } else {
-        [self showFunctionPanel:NO];
-    }
-}
-
-- (void)keyBoardMainViewDidTapSettings:(KBKeyBoardMainView *)keyBoardMainView {
-    [self showSettingView:YES];
-}
-
-// MARK: - KBFunctionViewDelegate
-- (void)functionView:(KBFunctionView *)functionView didTapToolActionAtIndex:(NSInteger)index {
-    // 需求：当 index == 0 时，切回键盘主视图
-    if (index == 0) {
-        [self showFunctionPanel:NO];
-    }
-}
-
-#pragma mark - lazy
-- (KBKeyBoardMainView *)keyBoardMainView{
-    if (!_keyBoardMainView) {
-        _keyBoardMainView = [[KBKeyBoardMainView alloc] init];
-        _keyBoardMainView.delegate = self;
-    }
-    return _keyBoardMainView;
-}
-
-- (KBFunctionView *)functionView{
-    if (!_functionView) {
-        _functionView = [[KBFunctionView alloc] init];
-        _functionView.delegate = self; // 监听功能面板顶部Bar点击
-    }
-    return _functionView;
-}
-
-- (KBSettingView *)settingView {
-    if (!_settingView) {
-        _settingView = [[KBSettingView alloc] init];
-    }
-    return _settingView;
-}
-
-
-#pragma mark - Actions
-
-- (void)onTapSettingsBack {
-    [self showSettingView:NO];
-}
-
-
-// 当键盘第一次显示时，尝试唤起主 App 以提示登录（由主 App 决定是否真的弹登录）。
 - (void)viewDidAppear:(BOOL)animated {
-    [super viewDidAppear:animated];
-    if (!_kb_didTriggerLoginDeepLinkOnce) {
-        _kb_didTriggerLoginDeepLinkOnce = YES;
-        // 仅在未登录时尝试拉起主App登录
-        if (!KBAuthManager.shared.isLoggedIn) {
-            [self kb_tryOpenContainerForLoginIfNeeded];
-        }
-    }
+  [super viewDidAppear:animated];
+  //    if (!_kb_didTriggerLoginDeepLinkOnce) {
+  //        _kb_didTriggerLoginDeepLinkOnce = YES;
+  //        // 仅在未登录时尝试拉起主App登录
+  //        if (!KBAuthManager.shared.isLoggedIn) {
+  //            [self kb_tryOpenContainerForLoginIfNeeded];
+  //        }
+  //    }
 }
 
-- (void)kb_tryOpenContainerForLoginIfNeeded {
-    NSURL *url = [NSURL URLWithString:@"kbkeyboard://login?src=keyboard"];
-    if (!url) return;
-    __weak typeof(self) weakSelf = self;
-    [self.extensionContext openURL:url completionHandler:^(__unused BOOL success) {
-        // 即使失败也不重复尝试；避免打扰。
-        __unused typeof(weakSelf) selfStrong = weakSelf;
-    }];
+- (void)viewDidLayoutSubviews {
+  [super viewDidLayoutSubviews];
+  //  [self kb_updateKeyboardLayoutIfNeeded];
+
+  // 首次布局完成后显示，避免闪烁
+  if (self.contentView.hidden) {
+    self.contentView.hidden = NO;
+  }
+  if (self.kb_defaultGradientLayer) {
+    self.kb_defaultGradientLayer.frame = self.bgImageView.bounds;
+  }
 }
+
+- (void)viewWillTransitionToSize:(CGSize)size
+       withTransitionCoordinator:
+           (id<UIViewControllerTransitionCoordinator>)coordinator {
+  [super viewWillTransitionToSize:size withTransitionCoordinator:coordinator];
+  __weak typeof(self) weakSelf = self;
+  [coordinator
+      animateAlongsideTransition:^(
+          id<UIViewControllerTransitionCoordinatorContext> _Nonnull context) {
+        [weakSelf kb_updateKeyboardLayoutIfNeeded];
+      }
+      completion:^(
+          __unused id<
+              UIViewControllerTransitionCoordinatorContext> _Nonnull context) {
+        [weakSelf kb_updateKeyboardLayoutIfNeeded];
+      }];
+}
+
+- (void)dealloc {
+  if (self.kb_fullAccessObserverToken) {
+    [[NSNotificationCenter defaultCenter]
+        removeObserver:self.kb_fullAccessObserverToken];
+    self.kb_fullAccessObserverToken = nil;
+  }
+  if (self.kb_skinObserverToken) {
+    [[NSNotificationCenter defaultCenter]
+        removeObserver:self.kb_skinObserverToken];
+    self.kb_skinObserverToken = nil;
+  }
+  [self kb_unregisterDarwinSkinInstallObserver];
+#if DEBUG
+  if (_kb_debugDidCountAlive) {
+    sKBKeyboardVCAliveCount -= 1;
+  }
+  NSLog(@"[Keyboard] KeyboardViewController dealloc alive=%ld self=%p mem=%@",
+        (long)sKBKeyboardVCAliveCount, self, KBFormatMB(KBPhysFootprintBytes()));
+#endif
+}
+
 @end

CustomKeyboard/KeyboardViewControllerHelp/KeyboardViewController+Chat.m

@@ -0,0 +1,712 @@
+//
+//  KeyboardViewController+Chat.m
+//  CustomKeyboard
+//
+//  Created by Codex on 2026/02/22.
+//
+
+#import "KeyboardViewController+Private.h"
+
+#import "KBChatLimitPopView.h"
+#import "KBChatMessage.h"
+#import "KBChatPanelView.h"
+#import "KBFullAccessManager.h"
+#import "KBHostAppLauncher.h"
+#import "KBInputBufferManager.h"
+#import "KBNetworkManager.h"
+#import "KBVM.h"
+#import "Masonry.h"
+
+#import <AVFoundation/AVFoundation.h>
+
+static const NSUInteger kKBChatMessageLimit = 6;
+
+@implementation KeyboardViewController (Chat)
+
+#pragma mark - KBChatPanelViewDelegate
+
+- (void)chatPanelView:(KBChatPanelView *)view didSendText:(NSString *)text {
+  NSString *trim =
+      [text stringByTrimmingCharactersInSet:
+                [NSCharacterSet whitespaceAndNewlineCharacterSet]];
+  if (trim.length == 0) {
+    return;
+  }
+  [self kb_sendChatText:trim];
+}
+
+- (void)chatPanelView:(KBChatPanelView *)view
+       didTapMessage:(KBChatMessage *)message {
+  if (message.audioFilePath.length == 0) {
+    return;
+  }
+  [self kb_playChatAudioAtPath:message.audioFilePath];
+}
+
+- (void)chatPanelView:(KBChatPanelView *)view
+    didTapVoiceButtonForMessage:(KBChatMessage *)message {
+  if (!message)
+    return;
+
+  // 如果有 audioData，直接播放
+  if (message.audioData && message.audioData.length > 0) {
+    [self kb_playChatAudioData:message.audioData];
+    return;
+  }
+
+  // 如果有 audioFilePath，播放文件
+  if (message.audioFilePath.length > 0) {
+    [self kb_playChatAudioAtPath:message.audioFilePath];
+    return;
+  }
+
+  NSLog(@"[Keyboard] 没有音频数据可播放");
+}
+
+- (void)chatPanelViewDidTapClose:(KBChatPanelView *)view {
+  // 清空 chatPanelView 内部的消息
+  [view kb_reloadWithMessages:@[]];
+  if (self.chatAudioPlayer.isPlaying) {
+    [self.chatAudioPlayer stop];
+  }
+  self.chatAudioPlayer = nil;
+  [self kb_setPanelMode:KBKeyboardPanelModeMain animated:YES];
+}
+
+#pragma mark - Chat Helpers
+
+- (void)kb_handleChatSendAction {
+  if (!self.chatPanelVisible) {
+    return;
+  }
+  [[KBInputBufferManager shared]
+      refreshFromProxyIfPossible:self.textDocumentProxy];
+  NSString *fullText = [KBInputBufferManager shared].liveText ?: @"";
+
+  // 去掉打开聊天面板前宿主输入框里已有的基线文本，只取新增部分
+  NSString *baseline = self.chatPanelBaselineText ?: @"";
+  NSString *rawText = fullText;
+  if (baseline.length > 0 && [fullText hasPrefix:baseline]) {
+    rawText = [fullText substringFromIndex:baseline.length];
+  }
+
+  NSString *trim =
+      [rawText stringByTrimmingCharactersInSet:
+                  [NSCharacterSet whitespaceAndNewlineCharacterSet]];
+  NSString *textToClear = rawText;
+  if (trim.length == 0) {
+    // 兼容「先输入再打开聊天面板」场景：
+    // 此时新增文本为空，但当前输入框已有可发送内容，应该允许直接发送。
+    NSString *fullTrim =
+        [fullText stringByTrimmingCharactersInSet:
+                      [NSCharacterSet whitespaceAndNewlineCharacterSet]];
+    if (fullTrim.length > 0) {
+      trim = fullTrim;
+      textToClear = fullText;
+    }
+  }
+  if (trim.length == 0) {
+    [KBHUD showInfo:KBLocalized(@"请输入内容")];
+    return;
+  }
+  [self kb_sendChatText:trim];
+  // 默认只清新增文本；若命中兜底则清当前全文，避免“已发送但输入框残留”。
+  [self kb_clearHostInputForText:textToClear];
+}
+
+- (void)kb_sendChatText:(NSString *)text {
+  if (text.length == 0) {
+    return;
+  }
+  NSLog(@"[KB] 发送消息: %@", text);
+
+  KBChatMessage *outgoing = [KBChatMessage userMessageWithText:text];
+  outgoing.avatarURL = [self kb_sharedUserAvatarURL];
+  [self.chatPanelView kb_addUserMessage:text];
+  [self kb_prefetchAvatarForMessage:outgoing];
+
+  if (![[KBFullAccessManager shared] ensureFullAccessOrGuideInView:self.view]) {
+    [KBHUD showInfo:KBLocalized(@"请开启完全访问后使用")];
+    return;
+  }
+
+  // 添加 loading 消息
+  [self.chatPanelView kb_addLoadingAssistantMessage];
+
+  // 调用新的聊天接口
+  [self kb_requestChatMessageWithContent:text];
+}
+
+#pragma mark - Chat Limit Pop
+
+- (void)kb_showChatLimitPopWithMessage:(NSString *)message {
+  [self kb_dismissChatLimitPop];
+
+  UIControl *mask = [[UIControl alloc] init];
+  mask.backgroundColor = [[UIColor blackColor] colorWithAlphaComponent:0.4];
+  mask.alpha = 0.0;
+  [mask addTarget:self
+                action:@selector(kb_dismissChatLimitPop)
+      forControlEvents:UIControlEventTouchUpInside];
+  [self.contentView addSubview:mask];
+  [mask mas_makeConstraints:^(MASConstraintMaker *make) {
+    make.edges.equalTo(self.contentView);
+  }];
+
+  CGFloat width = 252.0;
+  CGFloat height = 252.0 + 18.0 + 53.0 + 18.0 + 28.0;
+  KBChatLimitPopView *content =
+      [[KBChatLimitPopView alloc] initWithFrame:CGRectMake(0, 0, width, height)];
+  content.message = message ?: @"";
+  content.delegate = self;
+  [mask addSubview:content];
+  [content mas_makeConstraints:^(MASConstraintMaker *make) {
+    make.center.equalTo(mask);
+    make.width.mas_equalTo(width);
+    make.height.mas_equalTo(height);
+  }];
+
+  self.chatLimitMaskView = mask;
+  [self.contentView bringSubviewToFront:mask];
+  [UIView animateWithDuration:0.18
+                   animations:^{
+                     mask.alpha = 1.0;
+                   }];
+}
+
+- (void)kb_dismissChatLimitPop {
+  if (!self.chatLimitMaskView) {
+    return;
+  }
+  UIControl *mask = self.chatLimitMaskView;
+  self.chatLimitMaskView = nil;
+  [UIView animateWithDuration:0.15
+                   animations:^{
+                     mask.alpha = 0.0;
+                   }
+                   completion:^(__unused BOOL finished) {
+                     [mask removeFromSuperview];
+                   }];
+}
+
+- (void)kb_clearHostInputForText:(NSString *)text {
+  if (text.length == 0) {
+    return;
+  }
+  NSUInteger count = [self kb_composedCharacterCountForString:text];
+  for (NSUInteger i = 0; i < count; i++) {
+    [self.textDocumentProxy deleteBackward];
+  }
+  [[KBInputBufferManager shared] clearAllLiveText];
+  [self kb_clearCurrentWord];
+}
+
+- (NSUInteger)kb_composedCharacterCountForString:(NSString *)text {
+  if (text.length == 0) {
+    return 0;
+  }
+  __block NSUInteger count = 0;
+  [text enumerateSubstringsInRange:NSMakeRange(0, text.length)
+                           options:NSStringEnumerationByComposedCharacterSequences
+                        usingBlock:^(__unused NSString *substring,
+                                     __unused NSRange substringRange,
+                                     __unused NSRange enclosingRange,
+                                     __unused BOOL *stop) {
+                          count += 1;
+                        }];
+  return count;
+}
+
+- (NSString *)kb_sharedUserAvatarURL {
+  NSUserDefaults *ud = [[NSUserDefaults alloc] initWithSuiteName:AppGroup];
+  NSString *url = [ud stringForKey:AppGroup_UserAvatarURL];
+  return url ?: @"";
+}
+
+- (void)kb_prefetchAvatarForMessage:(KBChatMessage *)message {
+  if (!message || message.avatarImage) {
+    return;
+  }
+  NSString *urlString = message.avatarURL ?: @"";
+  if (urlString.length == 0) {
+    return;
+  }
+  if (![[KBFullAccessManager shared] hasFullAccess]) {
+    return;
+  }
+  __weak typeof(self) weakSelf = self;
+  [[KBVM shared] downloadAvatarFromURL:urlString
+                             completion:^(UIImage *image, NSError *error) {
+                               __strong typeof(weakSelf) self = weakSelf;
+                               if (!self || !image)
+                                 return;
+
+                               message.avatarImage = image;
+                               [self kb_reloadChatRowForMessage:message];
+                             }];
+}
+
+- (void)kb_reloadChatRowForMessage:(KBChatMessage *)message {
+  // 头像预加载完成后不需要刷新表格
+  // 因为键盘扩展的聊天面板不显示头像，所以这里直接返回
+  // 如果将来需要显示头像，可以只刷新特定行而不是整个表格
+}
+
+- (void)kb_requestChatAudioForText:(NSString *)text {
+  NSString *mockPath = [self kb_mockChatAudioPath];
+  if (mockPath.length > 0) {
+    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(0.35 * NSEC_PER_SEC)),
+                   dispatch_get_main_queue(), ^{
+                     NSString *displayText = KBLocalized(@"语音回复");
+                     KBChatMessage *incoming =
+                         [KBChatMessage messageWithText:displayText
+                                                outgoing:NO
+                                           audioFilePath:mockPath];
+                     incoming.displayName = KBLocalized(@"AI助手");
+                     [self kb_appendChatMessage:incoming];
+                     [self kb_playChatAudioAtPath:mockPath];
+                   });
+    return;
+  }
+  NSDictionary *payload = @{@"message" : text ?: @""};
+  __weak typeof(self) weakSelf = self;
+  [[KBNetworkManager shared] POST:API_AI_TALK
+                         jsonBody:payload
+                          headers:nil
+                       completion:^(NSDictionary *json, NSURLResponse *response,
+                                    NSError *error) {
+                         dispatch_async(dispatch_get_main_queue(), ^{
+                           __strong typeof(weakSelf) self = weakSelf;
+                           if (!self) {
+                             return;
+                           }
+                           if (error) {
+                             NSString *tip = error.localizedDescription
+                                                 ?: KBLocalized(@"请求失败");
+                             [KBHUD showInfo:tip];
+                             return;
+                           }
+                           NSString *displayText =
+                               [self kb_chatTextFromJSON:json];
+                           NSString *audioURL =
+                               [self kb_chatAudioURLFromJSON:json];
+                           NSString *audioBase64 =
+                               [self kb_chatAudioBase64FromJSON:json];
+                           if (audioURL.length > 0) {
+                             [self kb_downloadChatAudioFromURL:audioURL
+                                                   displayText:displayText];
+                             return;
+                           }
+                           if (audioBase64.length > 0) {
+                             NSData *data = [[NSData alloc]
+                                 initWithBase64EncodedString:audioBase64
+                                                      options:0];
+                             if (data.length == 0) {
+                               [KBHUD showInfo:KBLocalized(@"音频数据解析失败")];
+                               return;
+                             }
+                             [self kb_handleChatAudioData:data
+                                              fileExtension:@"m4a"
+                                                 displayText:displayText];
+                             return;
+                           }
+                           [KBHUD showInfo:KBLocalized(@"未获取到音频文件")];
+                         });
+                       }];
+}
+
+#pragma mark - New Chat API (with typewriter effect and audio preload)
+
+/// 调用新的聊天接口（返回文本和 audioId）
+- (void)kb_requestChatMessageWithContent:(NSString *)content {
+  if (content.length == 0) {
+    [self.chatPanelView kb_removeLoadingAssistantMessage];
+    return;
+  }
+
+  NSInteger companionId = [[KBVM shared] selectedCompanionIdFromAppGroup];
+  NSLog(@"[KB] 请求聊天: companionId=%ld", (long)companionId);
+
+  __weak typeof(self) weakSelf = self;
+  [[KBVM shared] sendChatMessageWithContent:content
+                                companionId:companionId
+                                 completion:^(KBChatResponse *response) {
+                                   __strong typeof(weakSelf) self = weakSelf;
+                                   if (!self)
+                                     return;
+
+                                   if (response.code != 0) {
+                                     if (response.code == 50030) {
+                                       NSLog(@"[KB] ⚠️ 次数用尽: %@",
+                                             response.message);
+                                       [self.chatPanelView
+                                           kb_removeLoadingAssistantMessage];
+                                       [self kb_showChatLimitPopWithMessage:
+                                                 response.message];
+                                       return;
+                                     }
+                                     NSLog(@"[KB] ❌ 请求失败: %@",
+                                           response.message);
+                                     [self.chatPanelView
+                                         kb_removeLoadingAssistantMessage];
+                                     [KBHUD showInfo:response.message
+                                                        ?: KBLocalized(@"请求失败")];
+                                     return;
+                                   }
+
+                                   NSLog(@"[KB] ✅ 收到回复: %@",
+                                         response.data.aiResponse);
+
+                                   if (response.data.aiResponse.length == 0) {
+                                     [self.chatPanelView
+                                         kb_removeLoadingAssistantMessage];
+                                     [KBHUD showInfo:KBLocalized(@"未获取到回复内容")];
+                                     return;
+                                   }
+
+                                   // 添加 AI 消息（带打字机效果）
+                                   NSLog(@"[KB] 准备添加 AI 消息");
+                                   [self.chatPanelView
+                                       kb_addAssistantMessage:response.data.aiResponse
+                                                     audioId:response.data.audioId];
+                                   NSLog(@"[KB] AI 消息添加完成");
+
+                                   // 通知主 App 刷新对应 persona 的聊天记录
+                                   [self kb_notifyMainAppChatUpdatedWithCompanionId:companionId];
+
+                                   // 如果有 audioId，开始预加载音频
+                                   if (response.data.audioId.length > 0) {
+                                     [self kb_preloadAudioWithAudioId:
+                                               response.data.audioId];
+                                   }
+                                 }];
+}
+
+/// 从 AppGroup 获取选中的 persona companionId
+- (NSInteger)kb_selectedCompanionId {
+  return [[KBVM shared] selectedCompanionIdFromAppGroup];
+}
+
+#pragma mark - Audio Preload
+
+/// 预加载音频（轮询获取 audioURL）
+- (void)kb_preloadAudioWithAudioId:(NSString *)audioId {
+  if (audioId.length == 0)
+    return;
+
+  NSLog(@"[Keyboard] 开始预加载音频，audioId: %@", audioId);
+
+  __weak typeof(self) weakSelf = self;
+  [[KBVM shared] pollAudioURLWithAudioId:audioId
+                              maxRetries:10
+                                interval:1.0
+                              completion:^(KBAudioResponse *response) {
+                                __strong typeof(weakSelf) self = weakSelf;
+                                if (!self)
+                                  return;
+
+                                if (!response.success ||
+                                    response.audioURL.length == 0) {
+                                  NSLog(@"[Keyboard] ❌ 预加载音频 URL 获取失败: %@",
+                                        response.errorMessage);
+                                  return;
+                                }
+
+                                NSLog(@"[Keyboard] ✅ 预加载音频 URL 获取成功");
+
+                                // 下载音频
+                                [[KBVM shared]
+                                    downloadAudioFromURL:response.audioURL
+                                             completion:^(
+                                                 KBAudioResponse *audioResponse) {
+                                               if (!audioResponse.success) {
+                                                 NSLog(@"[Keyboard] ❌ 预加载音频下载失败: %@",
+                                                       audioResponse.errorMessage);
+                                                 return;
+                                               }
+
+                                               // 更新最后一条 AI 消息的音频数据
+                                               [self.chatPanelView
+                                                   kb_updateLastAssistantMessageWithAudioData:
+                                                       audioResponse.audioData
+                                                                                 duration:
+                                                                                     audioResponse.duration];
+                                               NSLog(@"[Keyboard] ✅ 预加载音频完成，音频时长: %.2f秒",
+                                                     audioResponse.duration);
+                                             }];
+                              }];
+}
+
+- (void)kb_downloadChatAudioFromURL:(NSString *)audioURL
+                        displayText:(NSString *)displayText {
+  __weak typeof(self) weakSelf = self;
+  [[KBVM shared] downloadAudioFromURL:audioURL
+                           completion:^(KBAudioResponse *response) {
+                             __strong typeof(weakSelf) self = weakSelf;
+                             if (!self)
+                               return;
+
+                             if (!response.success) {
+                               [KBHUD showInfo:response.errorMessage
+                                                   ?: KBLocalized(@"下载失败")];
+                               return;
+                             }
+
+                             if (!response.audioData ||
+                                 response.audioData.length == 0) {
+                               [KBHUD showInfo:KBLocalized(@"未获取到音频数据")];
+                               return;
+                             }
+
+                             NSString *ext = @"m4a";
+                             NSURL *url = [NSURL URLWithString:audioURL];
+                             if (url.pathExtension.length > 0) {
+                               ext = url.pathExtension;
+                             }
+                             [self kb_handleChatAudioData:response.audioData
+                                            fileExtension:ext
+                                               displayText:displayText];
+                           }];
+}
+
+- (void)kb_handleChatAudioData:(NSData *)data
+                 fileExtension:(NSString *)extension
+                    displayText:(NSString *)displayText {
+  if (data.length == 0) {
+    [KBHUD showInfo:KBLocalized(@"音频数据为空")];
+    return;
+  }
+  NSString *ext = extension.length > 0 ? extension : @"m4a";
+  NSString *fileName = [NSString
+      stringWithFormat:@"kb_chat_%@.%@",
+                       @((long long)([NSDate date].timeIntervalSince1970 *
+                                     1000)),
+                       ext];
+  NSString *filePath =
+      [NSTemporaryDirectory() stringByAppendingPathComponent:fileName];
+  if (![data writeToFile:filePath atomically:YES]) {
+    [KBHUD showInfo:KBLocalized(@"音频保存失败")];
+    return;
+  }
+  NSString *text =
+      displayText.length > 0 ? displayText : KBLocalized(@"语音消息");
+  KBChatMessage *incoming =
+      [KBChatMessage messageWithText:text outgoing:NO audioFilePath:filePath];
+  incoming.displayName = KBLocalized(@"AI助手");
+  [self kb_appendChatMessage:incoming];
+}
+
+- (void)kb_appendChatMessage:(KBChatMessage *)message {
+  if (!message) {
+    return;
+  }
+  [self.chatMessages addObject:message];
+  if (self.chatMessages.count > kKBChatMessageLimit) {
+    NSUInteger overflow = self.chatMessages.count - kKBChatMessageLimit;
+    NSArray<KBChatMessage *> *removed =
+        [self.chatMessages subarrayWithRange:NSMakeRange(0, overflow)];
+    [self.chatMessages removeObjectsInRange:NSMakeRange(0, overflow)];
+    for (KBChatMessage *msg in removed) {
+      if (msg.audioFilePath.length > 0) {
+        NSString *tmpRoot = NSTemporaryDirectory();
+        if (tmpRoot.length > 0 && [msg.audioFilePath hasPrefix:tmpRoot]) {
+          [[NSFileManager defaultManager] removeItemAtPath:msg.audioFilePath
+                                                     error:nil];
+        }
+      }
+    }
+  }
+  [self.chatPanelView kb_reloadWithMessages:self.chatMessages];
+}
+
+- (NSString *)kb_mockChatAudioPath {
+  NSString *path = [[NSBundle mainBundle] pathForResource:@"ai_test"
+                                                   ofType:@"m4a"];
+  return path ?: @"";
+}
+
+- (NSString *)kb_chatTextFromJSON:(NSDictionary *)json {
+  NSDictionary *data = [self kb_chatDataDictionaryFromJSON:json];
+  NSString *text =
+      [self kb_stringValueInDict:data keys:@[ @"text", @"message", @"content" ]];
+  if (text.length == 0) {
+    text = [self kb_stringValueInDict:json
+                                  keys:@[ @"text", @"message", @"content" ]];
+  }
+  return text ?: @"";
+}
+
+- (NSString *)kb_chatAudioURLFromJSON:(NSDictionary *)json {
+  NSDictionary *data = [self kb_chatDataDictionaryFromJSON:json];
+  NSArray<NSString *> *keys =
+      @[ @"audioUrl", @"audioURL", @"audio_url", @"url", @"fileUrl",
+         @"file_url", @"audioFileUrl", @"audio_file_url" ];
+  NSString *url = [self kb_stringValueInDict:data keys:keys];
+  if (url.length == 0) {
+    url = [self kb_stringValueInDict:json keys:keys];
+  }
+  return url ?: @"";
+}
+
+- (NSString *)kb_chatAudioBase64FromJSON:(NSDictionary *)json {
+  NSDictionary *data = [self kb_chatDataDictionaryFromJSON:json];
+  NSArray<NSString *> *keys =
+      @[ @"audioBase64", @"audio_base64", @"audioData", @"audio_data",
+         @"base64" ];
+  NSString *b64 = [self kb_stringValueInDict:data keys:keys];
+  if (b64.length == 0) {
+    b64 = [self kb_stringValueInDict:json keys:keys];
+  }
+  return b64 ?: @"";
+}
+
+- (NSDictionary *)kb_chatDataDictionaryFromJSON:(NSDictionary *)json {
+  if (![json isKindOfClass:[NSDictionary class]]) {
+    return @{};
+  }
+  id dataObj = json[@"data"] ?: json[@"result"] ?: json[@"response"];
+  if ([dataObj isKindOfClass:[NSDictionary class]]) {
+    return (NSDictionary *)dataObj;
+  }
+  return @{};
+}
+
+- (NSString *)kb_stringValueInDict:(NSDictionary *)dict
+                               keys:(NSArray<NSString *> *)keys {
+  if (![dict isKindOfClass:[NSDictionary class]]) {
+    return @"";
+  }
+  for (NSString *key in keys) {
+    id value = dict[key];
+    if ([value isKindOfClass:[NSString class]] &&
+        ((NSString *)value).length > 0) {
+      return (NSString *)value;
+    }
+  }
+  return @"";
+}
+
+- (void)kb_playChatAudioAtPath:(NSString *)path {
+  if (path.length == 0) {
+    return;
+  }
+  NSURL *url = [NSURL fileURLWithPath:path];
+  if (![NSFileManager.defaultManager fileExistsAtPath:path]) {
+    [KBHUD showInfo:KBLocalized(@"音频文件不存在")];
+    return;
+  }
+
+  if (self.chatAudioPlayer && self.chatAudioPlayer.isPlaying) {
+    NSURL *currentURL = self.chatAudioPlayer.url;
+    if ([currentURL isEqual:url]) {
+      [self.chatAudioPlayer stop];
+      self.chatAudioPlayer = nil;
+      return;
+    }
+    [self.chatAudioPlayer stop];
+    self.chatAudioPlayer = nil;
+  }
+
+  NSError *sessionError = nil;
+  AVAudioSession *session = [AVAudioSession sharedInstance];
+  if ([session respondsToSelector:@selector(setCategory:options:error:)]) {
+    [session setCategory:AVAudioSessionCategoryPlayback
+             withOptions:AVAudioSessionCategoryOptionDuckOthers
+                   error:&sessionError];
+  } else {
+    [session setCategory:AVAudioSessionCategoryPlayback error:&sessionError];
+  }
+  [session setActive:YES error:nil];
+
+  NSError *playerError = nil;
+  AVAudioPlayer *player =
+      [[AVAudioPlayer alloc] initWithContentsOfURL:url error:&playerError];
+  if (playerError || !player) {
+    [KBHUD showInfo:KBLocalized(@"音频播放失败")];
+    return;
+  }
+  self.chatAudioPlayer = player;
+  [player prepareToPlay];
+  [player play];
+}
+
+/// 播放音频数据
+- (void)kb_playChatAudioData:(NSData *)audioData {
+  if (!audioData || audioData.length == 0) {
+    NSLog(@"[Keyboard] 音频数据为空");
+    return;
+  }
+
+  // 如果正在播放，先停止
+  if (self.chatAudioPlayer && self.chatAudioPlayer.isPlaying) {
+    [self.chatAudioPlayer stop];
+    self.chatAudioPlayer = nil;
+  }
+
+  // 配置音频会话
+  NSError *sessionError = nil;
+  AVAudioSession *session = [AVAudioSession sharedInstance];
+  if ([session respondsToSelector:@selector(setCategory:options:error:)]) {
+    [session setCategory:AVAudioSessionCategoryPlayback
+             withOptions:AVAudioSessionCategoryOptionDuckOthers
+                   error:&sessionError];
+  } else {
+    [session setCategory:AVAudioSessionCategoryPlayback error:&sessionError];
+  }
+  [session setActive:YES error:nil];
+
+  // 创建播放器
+  NSError *playerError = nil;
+  AVAudioPlayer *player =
+      [[AVAudioPlayer alloc] initWithData:audioData error:&playerError];
+  if (playerError || !player) {
+    NSLog(@"[Keyboard] 音频播放器初始化失败: %@",
+          playerError.localizedDescription);
+    [KBHUD showInfo:KBLocalized(@"音频播放失败")];
+    return;
+  }
+
+  self.chatAudioPlayer = player;
+  player.volume = 1.0;
+  [player prepareToPlay];
+  [player play];
+
+  NSLog(@"[Keyboard] 开始播放音频，时长: %.2f秒", player.duration);
+}
+
+#pragma mark - Notify Main App
+
+/// 通知主 App 刷新对应 persona 的聊天记录
+- (void)kb_notifyMainAppChatUpdatedWithCompanionId:(NSInteger)companionId {
+    NSUserDefaults *ud = [[NSUserDefaults alloc] initWithSuiteName:AppGroup];
+    [ud setInteger:companionId forKey:AppGroup_ChatUpdatedCompanionId];
+    [ud synchronize];
+
+    CFNotificationCenterPostNotification(
+        CFNotificationCenterGetDarwinNotifyCenter(),
+        (__bridge CFStringRef)kKBDarwinChatUpdated,
+        NULL, NULL, true);
+
+    NSLog(@"[KB] 已通知主 App 刷新 companionId=%ld 的聊天记录", (long)companionId);
+}
+
+#pragma mark - KBChatLimitPopViewDelegate
+
+- (void)chatLimitPopViewDidTapCancel:(KBChatLimitPopView *)view {
+  [self kb_dismissChatLimitPop];
+}
+
+- (void)chatLimitPopViewDidTapRecharge:(KBChatLimitPopView *)view {
+  [self kb_dismissChatLimitPop];
+  NSString *urlString =
+      [NSString stringWithFormat:@"%@://recharge?src=keyboard&vipType=svip",
+                                 KB_APP_SCHEME];
+  NSURL *scheme = [NSURL URLWithString:urlString];
+  BOOL success = [KBHostAppLauncher openHostAppURL:scheme
+                                     fromResponder:self.view];
+  if (!success) {
+    [KBHUD showInfo:KBLocalized(@"Please open the App to finish purchase")];
+  }
+}
+
+@end

CustomKeyboard/KeyboardViewControllerHelp/KeyboardViewController+Layout.m

@@ -0,0 +1,96 @@
+//
+//  KeyboardViewController+Layout.m
+//  CustomKeyboard
+//
+//  Created by Codex on 2026/02/22.
+//
+
+#import "KeyboardViewController+Private.h"
+
+// 以 375 宽设计稿为基准的键盘总高度
+static const CGFloat kKBKeyboardBaseHeight = 250.0f;
+static const CGFloat kKBChatPanelHeight = 180;
+
+@implementation KeyboardViewController (Layout)
+
+- (CGFloat)kb_portraitWidth {
+  CGSize s = [UIScreen mainScreen].bounds.size;
+  return MIN(s.width, s.height);
+}
+
+- (CGFloat)kb_keyboardHeightForWidth:(CGFloat)width {
+  if (width <= 0) {
+    width = KB_DESIGN_WIDTH;
+  }
+  CGFloat scale = width / KB_DESIGN_WIDTH;
+  CGFloat baseHeight = kKBKeyboardBaseHeight * scale;
+  CGFloat chatHeight = kKBChatPanelHeight * scale;
+  if (self.chatPanelVisible) {
+    return baseHeight + chatHeight;
+  }
+  return baseHeight;
+}
+
+- (CGFloat)kb_keyboardBaseHeightForWidth:(CGFloat)width {
+  if (width <= 0) {
+    width = KB_DESIGN_WIDTH;
+  }
+  CGFloat scale = width / KB_DESIGN_WIDTH;
+  return kKBKeyboardBaseHeight * scale;
+}
+
+- (CGFloat)kb_chatPanelHeightForWidth:(CGFloat)width {
+  if (width <= 0) {
+    width = KB_DESIGN_WIDTH;
+  }
+  CGFloat scale = width / KB_DESIGN_WIDTH;
+  return kKBChatPanelHeight * scale;
+}
+
+- (void)kb_updateKeyboardLayoutIfNeeded {
+  CGFloat portraitWidth = [self kb_portraitWidth];
+  CGFloat keyboardHeight = [self kb_keyboardHeightForWidth:portraitWidth];
+  CGFloat keyboardBaseHeight =
+      [self kb_keyboardBaseHeightForWidth:portraitWidth];
+  CGFloat chatPanelHeight = [self kb_chatPanelHeightForWidth:portraitWidth];
+  CGFloat containerWidth = CGRectGetWidth(self.view.superview.bounds);
+  if (containerWidth <= 0) {
+    containerWidth = CGRectGetWidth(self.view.window.bounds);
+  }
+  if (containerWidth <= 0) {
+    containerWidth = CGRectGetWidth([UIScreen mainScreen].bounds);
+  }
+
+  BOOL widthChanged = (fabs(self.kb_lastPortraitWidth - portraitWidth) >= 0.5);
+  BOOL heightChanged =
+      (fabs(self.kb_lastKeyboardHeight - keyboardHeight) >= 0.5);
+  if (!widthChanged && !heightChanged && containerWidth > 0 &&
+      self.kb_widthConstraint.constant == containerWidth) {
+    return;
+  }
+  self.kb_lastPortraitWidth = portraitWidth;
+  self.kb_lastKeyboardHeight = keyboardHeight;
+
+  if (self.kb_heightConstraint) {
+    self.kb_heightConstraint.constant = keyboardHeight;
+  }
+  if (containerWidth > 0 && self.kb_widthConstraint) {
+    self.kb_widthConstraint.constant = containerWidth;
+  }
+  if (self.contentWidthConstraint) {
+    [self.contentWidthConstraint setOffset:portraitWidth];
+  }
+  if (self.contentHeightConstraint) {
+    [self.contentHeightConstraint setOffset:keyboardHeight];
+  }
+  if (self.keyBoardMainHeightConstraint) {
+    [self.keyBoardMainHeightConstraint setOffset:keyboardBaseHeight];
+  }
+  if (self.chatPanelHeightConstraint) {
+    [self.chatPanelHeightConstraint setOffset:chatPanelHeight];
+  }
+  [self.view layoutIfNeeded];
+}
+
+@end
+

CustomKeyboard/KeyboardViewControllerHelp/KeyboardViewController+Panels.m

@@ -0,0 +1,656 @@
+//
+//  KeyboardViewController+Panels.m
+//  CustomKeyboard
+//
+//  Created by Codex on 2026/02/22.
+//
+
+#import "KeyboardViewController+Private.h"
+
+#import "KBAuthManager.h"
+#import "KBBackspaceUndoManager.h"
+#import "KBChatMessage.h"
+#import "KBChatPanelView.h"
+#import "KBFunctionView.h"
+#import "KBFullAccessManager.h"
+#import "KBHostAppLauncher.h"
+#import "KBInputBufferManager.h"
+#import "KBKey.h"
+#import "KBKeyBoardMainView.h"
+#import "KBKeyboardSubscriptionView.h"
+#import "KBSettingView.h"
+#import "Masonry.h"
+#import <SDWebImage/SDWebImage.h>
+#import <AVFoundation/AVAudioPlayer.h>
+
+@implementation KeyboardViewController (Panels)
+
+#pragma mark - Panel Mode
+
+- (void)kb_setPanelMode:(KBKeyboardPanelMode)mode animated:(BOOL)animated {
+  if (mode == self.kb_panelMode) {
+    return;
+  }
+
+  KBKeyboardPanelMode fromMode = self.kb_panelMode;
+
+  // AI 入口先判完全访问：未开启时仅展示引导，不再继续登录态判断。
+  if (mode == KBKeyboardPanelModeFunction &&
+      ![[KBFullAccessManager shared] ensureFullAccessOrGuideInView:self.view]) {
+    return;
+  }
+
+  // 未登录时，不要提前写入面板状态，避免 mode 被错误卡在 Function 导致后续点击无响应。
+  BOOL islogin = YES;
+  if (mode == KBKeyboardPanelModeFunction) {
+    [[KBAuthManager shared] reloadFromKeychain];
+    islogin = KBAuthManager.shared.isLoggedIn;
+  }
+#if DEBUG
+  if (mode == KBKeyboardPanelModeFunction) {
+    NSString *token = [KBAuthManager shared].current.accessToken ?: @"";
+    NSLog(@"[AuthTrace][Ext] tapAI mode=%ld isLoggedIn=%d tokenLen=%lu",
+          (long)mode, islogin, (unsigned long)token.length);
+  }
+#endif
+  if (mode == KBKeyboardPanelModeFunction && !islogin) {
+    [KBHUD showInfo:KBLocalized(@"请先登录后使用AI功能")];
+    NSString *schemeStr =
+        [NSString stringWithFormat:@"%@://login?src=keyboard", KB_APP_SCHEME];
+    NSURL *scheme = [NSURL URLWithString:schemeStr];
+    BOOL ok = [KBHostAppLauncher openHostAppURL:scheme fromResponder:self.view];
+    if (!ok) {
+      [KBHUD showInfo:KBLocalized(@"请回到桌面手动打开App登录")];
+    }
+    return;
+  }
+
+  self.kb_panelMode = mode;
+
+  // 主键盘视图是基础承载：确保存在（键盘隐藏后会被释放）
+  [self kb_ensureKeyBoardMainViewIfNeeded];
+
+  // 1) 先收起所有面板（再展开目标面板），避免互相调用导致漏关/层级错乱
+  [self kb_setSubscriptionPanelVisible:NO animated:animated];
+  [self kb_setSettingViewVisible:NO animated:animated];
+  [self kb_setChatPanelVisible:NO animated:animated];
+  [self kb_setFunctionPanelVisible:NO];
+
+  // 2) 再展开目标面板
+  switch (mode) {
+  case KBKeyboardPanelModeFunction:
+    [self kb_setFunctionPanelVisible:YES];
+    break;
+  case KBKeyboardPanelModeChat:
+    [self kb_setChatPanelVisible:YES animated:animated];
+    break;
+  case KBKeyboardPanelModeSettings:
+    [self kb_setSettingViewVisible:YES animated:animated];
+    break;
+  case KBKeyboardPanelModeSubscription:
+    [self kb_setSubscriptionPanelVisible:YES animated:animated];
+    break;
+  case KBKeyboardPanelModeMain:
+  default:
+    break;
+  }
+
+  // 3) 事件埋点：保持原逻辑（仅功能面板/主面板会互相曝光）
+  if (mode == KBKeyboardPanelModeFunction) {
+    [[KBMaiPointReporter sharedReporter]
+        reportPageExposureWithEventName:@"enter_keyboard_function_panel"
+                                 pageId:@"keyboard_function_panel"
+                                  extra:nil
+                             completion:nil];
+  } else if (mode == KBKeyboardPanelModeMain &&
+             fromMode == KBKeyboardPanelModeFunction) {
+    [[KBMaiPointReporter sharedReporter]
+        reportPageExposureWithEventName:@"enter_keyboard_main_panel"
+                                 pageId:@"keyboard_main_panel"
+                                  extra:nil
+                             completion:nil];
+  } else if (mode == KBKeyboardPanelModeSettings) {
+    [[KBMaiPointReporter sharedReporter]
+        reportPageExposureWithEventName:@"enter_keyboard_settings"
+                                 pageId:@"keyboard_settings"
+                                  extra:nil
+                             completion:nil];
+  } else if (mode == KBKeyboardPanelModeSubscription) {
+    [[KBMaiPointReporter sharedReporter]
+        reportPageExposureWithEventName:@"enter_keyboard_subscription_panel"
+                               pageId:@"keyboard_subscription_panel"
+                                extra:nil
+                           completion:nil];
+  }
+
+  // 4) 层级：保证当前面板在最上层
+  if (mode == KBKeyboardPanelModeSubscription) {
+    [self.contentView bringSubviewToFront:self.subscriptionView];
+  } else if (mode == KBKeyboardPanelModeSettings) {
+    [self.contentView bringSubviewToFront:self.settingView];
+  } else if (mode == KBKeyboardPanelModeChat) {
+    [self.contentView bringSubviewToFront:self.chatPanelView];
+  } else if (mode == KBKeyboardPanelModeFunction) {
+    [self.contentView bringSubviewToFront:self.functionView];
+  } else {
+    [self.contentView bringSubviewToFront:self.keyBoardMainView];
+  }
+}
+
+/// 对外兼容：切换显示功能面板/键盘主视图
+- (void)showFunctionPanel:(BOOL)show {
+  if (show) {
+    [self kb_setPanelMode:KBKeyboardPanelModeFunction animated:NO];
+    return;
+  }
+  if (self.kb_panelMode == KBKeyboardPanelModeFunction) {
+    [self kb_setPanelMode:KBKeyboardPanelModeMain animated:NO];
+  }
+}
+
+/// 对外兼容：显示/隐藏设置页（高度与 keyBoardMainView 一致），右侧滑入/滑出
+- (void)showSettingView:(BOOL)show {
+  if (show) {
+    [self kb_setPanelMode:KBKeyboardPanelModeSettings animated:YES];
+    return;
+  }
+  if (self.kb_panelMode == KBKeyboardPanelModeSettings) {
+    [self kb_setPanelMode:KBKeyboardPanelModeMain animated:YES];
+  }
+}
+
+/// 对外兼容：显示/隐藏聊天面板（覆盖整个键盘区域）
+- (void)showChatPanel:(BOOL)show {
+  if (show) {
+    [self kb_setPanelMode:KBKeyboardPanelModeChat animated:YES];
+    return;
+  }
+  if (self.kb_panelMode == KBKeyboardPanelModeChat) {
+    [self kb_setPanelMode:KBKeyboardPanelModeMain animated:YES];
+  }
+}
+
+- (void)kb_setFunctionPanelVisible:(BOOL)visible {
+  if (visible) {
+    [self kb_ensureFunctionViewIfNeeded];
+  }
+  if (_functionView) {
+    _functionView.hidden = !visible;
+  } else if (visible) {
+    // ensure 后按理已存在；这里兜底一次，避免异常情况下状态不一致
+    self.functionView.hidden = NO;
+  }
+  self.keyBoardMainView.hidden = visible;
+}
+
+- (void)kb_setChatPanelVisible:(BOOL)visible animated:(BOOL)animated {
+  if (visible == self.chatPanelVisible) {
+    return;
+  }
+  self.chatPanelVisible = visible;
+
+  if (visible) {
+    // 记录打开聊天面板时宿主输入框已有的文本，发送时只取新增部分
+    [[KBInputBufferManager shared]
+        refreshFromProxyIfPossible:self.textDocumentProxy];
+    self.chatPanelBaselineText = [KBInputBufferManager shared].liveText ?: @"";
+    [self kb_ensureChatPanelViewIfNeeded];
+    self.chatPanelView.hidden = NO;
+    self.chatPanelView.alpha = 0.0;
+    if (animated) {
+      [UIView animateWithDuration:0.2
+                            delay:0
+                          options:UIViewAnimationOptionCurveEaseOut
+                       animations:^{
+                         self.chatPanelView.alpha = 1.0;
+                       }
+                       completion:nil];
+    } else {
+      self.chatPanelView.alpha = 1.0;
+    }
+  } else {
+    // 从未创建过聊天面板时，直接返回，避免 show/hide 触发额外内存分配
+    if (!_chatPanelView) {
+      [self kb_updateKeyboardLayoutIfNeeded];
+      return;
+    }
+    if (animated) {
+      [UIView animateWithDuration:0.18
+          delay:0
+          options:UIViewAnimationOptionCurveEaseIn
+          animations:^{
+            self.chatPanelView.alpha = 0.0;
+          }
+          completion:^(BOOL finished) {
+            self.chatPanelView.hidden = YES;
+          }];
+    } else {
+      self.chatPanelView.alpha = 0.0;
+      self.chatPanelView.hidden = YES;
+    }
+  }
+  [self kb_updateKeyboardLayoutIfNeeded];
+}
+
+- (void)kb_setSettingViewVisible:(BOOL)visible animated:(BOOL)animated {
+  if (visible) {
+    KBSettingView *settingView = self.settingView;
+    if (!settingView.superview) {
+      settingView.hidden = YES;
+      [self.contentView addSubview:settingView];
+      [settingView mas_makeConstraints:^(MASConstraintMaker *make) {
+        make.edges.equalTo(self.contentView);
+      }];
+      [settingView.backButton addTarget:self
+                                 action:@selector(onTapSettingsBack)
+                       forControlEvents:UIControlEventTouchUpInside];
+    }
+    [self.contentView bringSubviewToFront:settingView];
+    // 以 keyBoardMainView 的实际宽度为准，避免首次添加时 self.view 宽度尚未计算
+    [self.contentView layoutIfNeeded];
+    CGFloat w = CGRectGetWidth(self.keyBoardMainView.bounds);
+    if (w <= 0) {
+      w = CGRectGetWidth(self.contentView.bounds);
+    }
+    if (w <= 0) {
+      w = [self kb_portraitWidth];
+    }
+    settingView.transform = CGAffineTransformMakeTranslation(w, 0);
+    settingView.hidden = NO;
+    if (animated) {
+      [UIView animateWithDuration:0.25
+                            delay:0
+                          options:UIViewAnimationOptionCurveEaseOut
+                       animations:^{
+                         settingView.transform = CGAffineTransformIdentity;
+                       }
+                       completion:nil];
+    } else {
+      settingView.transform = CGAffineTransformIdentity;
+    }
+  } else {
+    KBSettingView *settingView = _settingView;
+    if (!settingView) {
+      return;
+    }
+    if (!settingView.superview || settingView.hidden) {
+      return;
+    }
+    CGFloat w = CGRectGetWidth(self.keyBoardMainView.bounds);
+    if (w <= 0) {
+      w = CGRectGetWidth(self.contentView.bounds);
+    }
+    if (w <= 0) {
+      w = [self kb_portraitWidth];
+    }
+    if (animated) {
+      [UIView animateWithDuration:0.22
+          delay:0
+          options:UIViewAnimationOptionCurveEaseIn
+          animations:^{
+            settingView.transform = CGAffineTransformMakeTranslation(w, 0);
+          }
+          completion:^(BOOL finished) {
+            settingView.hidden = YES;
+          }];
+    } else {
+      settingView.transform = CGAffineTransformMakeTranslation(w, 0);
+      settingView.hidden = YES;
+    }
+  }
+}
+
+- (void)kb_setSubscriptionPanelVisible:(BOOL)visible animated:(BOOL)animated {
+  if (visible) {
+    KBKeyboardSubscriptionView *panel = self.subscriptionView;
+    if (!panel.superview) {
+      panel.hidden = YES;
+      [self.contentView addSubview:panel];
+      [panel mas_makeConstraints:^(MASConstraintMaker *make) {
+        make.edges.equalTo(self.contentView);
+      }];
+    }
+    [self.contentView bringSubviewToFront:panel];
+    panel.hidden = NO;
+    panel.alpha = 0.0;
+    CGFloat height = CGRectGetHeight(self.contentView.bounds);
+    if (height <= 0) {
+      height = 260;
+    }
+    panel.transform = CGAffineTransformMakeTranslation(0, height);
+    [panel refreshProductsIfNeeded];
+    if (animated) {
+      [UIView animateWithDuration:0.25
+                            delay:0
+                          options:UIViewAnimationOptionCurveEaseOut
+                       animations:^{
+                         panel.alpha = 1.0;
+                         panel.transform = CGAffineTransformIdentity;
+                       }
+                       completion:nil];
+    } else {
+      panel.alpha = 1.0;
+      panel.transform = CGAffineTransformIdentity;
+    }
+    return;
+  }
+
+  KBKeyboardSubscriptionView *panel = _subscriptionView;
+  if (!panel) {
+    return;
+  }
+  if (!panel.superview || panel.hidden) {
+    return;
+  }
+  CGFloat height = CGRectGetHeight(panel.bounds);
+  if (height <= 0) {
+    height = CGRectGetHeight(self.contentView.bounds);
+  }
+  if (animated) {
+    [UIView animateWithDuration:0.22
+        delay:0
+        options:UIViewAnimationOptionCurveEaseIn
+        animations:^{
+          panel.alpha = 0.0;
+          panel.transform = CGAffineTransformMakeTranslation(0, height);
+        }
+        completion:^(BOOL finished) {
+          panel.hidden = YES;
+          panel.alpha = 1.0;
+          panel.transform = CGAffineTransformIdentity;
+        }];
+  } else {
+    panel.hidden = YES;
+    panel.alpha = 1.0;
+    panel.transform = CGAffineTransformIdentity;
+  }
+}
+
+// 延迟创建：仅在用户真正打开功能面板时才创建/布局，降低默认内存占用。
+- (void)kb_ensureFunctionViewIfNeeded {
+  if (_functionView && _functionView.superview) {
+    return;
+  }
+  KBFunctionView *v = self.functionView;
+  if (!v.superview) {
+    v.hidden = YES;
+    [self.contentView addSubview:v];
+    [v mas_makeConstraints:^(MASConstraintMaker *make) {
+      make.edges.equalTo(self.contentView);
+    }];
+  }
+}
+
+// 延迟创建：仅在用户打开聊天面板时才创建/布局。
+- (void)kb_ensureChatPanelViewIfNeeded {
+  if (_chatPanelView && _chatPanelView.superview) {
+    return;
+  }
+  CGFloat portraitWidth = [self kb_portraitWidth];
+  CGFloat chatPanelHeight = [self kb_chatPanelHeightForWidth:portraitWidth];
+  KBChatPanelView *v = self.chatPanelView;
+  if (!v.superview) {
+    [self.contentView addSubview:v];
+    [v mas_makeConstraints:^(MASConstraintMaker *make) {
+      make.left.right.equalTo(self.contentView);
+      make.bottom.equalTo(self.keyBoardMainView.mas_top);
+      self.chatPanelHeightConstraint =
+          make.height.mas_equalTo(chatPanelHeight);
+    }];
+    v.hidden = YES;
+  }
+}
+
+// 延迟创建：键盘主面板（按键区）在隐藏时会被释放；再次显示时需要重建。
+- (void)kb_ensureKeyBoardMainViewIfNeeded {
+  if (_keyBoardMainView && _keyBoardMainView.superview) {
+    return;
+  }
+  CGFloat portraitWidth = [self kb_portraitWidth];
+  CGFloat keyboardBaseHeight =
+      [self kb_keyboardBaseHeightForWidth:portraitWidth];
+  KBKeyBoardMainView *v = self.keyBoardMainView;
+  if (!v.superview) {
+    [self.contentView addSubview:v];
+    [v mas_makeConstraints:^(MASConstraintMaker *make) {
+      make.left.right.equalTo(self.contentView);
+      make.bottom.equalTo(self.contentView);
+      self.keyBoardMainHeightConstraint =
+          make.height.mas_equalTo(keyboardBaseHeight);
+    }];
+  }
+  [self.contentView bringSubviewToFront:v];
+}
+
+// 键盘隐藏时释放可重建资源（背景图/缓存/非必需面板），降低扩展内存峰值。
+- (void)kb_releaseMemoryWhenKeyboardHidden {
+  [KBHUD setContainerView:nil];
+  self.bgImageView.image = nil;
+  self.kb_cachedGradientImage = nil;
+  [self.kb_defaultGradientLayer removeFromSuperlayer];
+  self.kb_defaultGradientLayer = nil;
+  [[SDImageCache sharedImageCache] clearMemory];
+
+  // 聊天相关可能持有音频数据/临时文件，键盘隐藏时直接清空，避免累计占用。
+  if (self.chatAudioPlayer) {
+    [self.chatAudioPlayer stop];
+    self.chatAudioPlayer = nil;
+  }
+  if (_chatMessages.count > 0) {
+    NSString *tmpRoot = NSTemporaryDirectory();
+    for (KBChatMessage *msg in _chatMessages.copy) {
+      if (tmpRoot.length > 0 && msg.audioFilePath.length > 0 &&
+          [msg.audioFilePath hasPrefix:tmpRoot]) {
+        [[NSFileManager defaultManager] removeItemAtPath:msg.audioFilePath
+                                                   error:nil];
+      }
+    }
+    [_chatMessages removeAllObjects];
+  }
+
+  if (_keyBoardMainView) {
+    [_keyBoardMainView removeFromSuperview];
+    _keyBoardMainView = nil;
+  }
+  self.keyBoardMainHeightConstraint = nil;
+
+  if (_functionView) {
+    [_functionView removeFromSuperview];
+    _functionView = nil;
+  }
+  if (_chatPanelView) {
+    [_chatPanelView removeFromSuperview];
+    _chatPanelView = nil;
+  }
+  self.chatPanelVisible = NO;
+  self.kb_panelMode = KBKeyboardPanelModeMain;
+
+  if (_subscriptionView) {
+    [_subscriptionView removeFromSuperview];
+    _subscriptionView = nil;
+  }
+  if (_settingView) {
+    [_settingView removeFromSuperview];
+    _settingView = nil;
+  }
+}
+
+// MARK: - KBKeyBoardMainViewDelegate
+
+- (void)keyBoardMainView:(KBKeyBoardMainView *)keyBoardMainView
+               didTapKey:(KBKey *)key {
+  switch (key.type) {
+  case KBKeyTypeCharacter: {
+    [[KBBackspaceUndoManager shared] registerNonClearAction];
+    NSString *text = key.output ?: key.title ?: @"";
+    [self.textDocumentProxy insertText:text];
+    [self kb_updateCurrentWordWithInsertedText:text];
+    [[KBInputBufferManager shared] appendText:text];
+  } break;
+  case KBKeyTypeBackspace:
+    [[KBInputBufferManager shared]
+        refreshFromProxyIfPossible:self.textDocumentProxy];
+    [[KBInputBufferManager shared]
+        prepareSnapshotForDeleteWithContextBefore:
+            self.textDocumentProxy.documentContextBeforeInput
+                                            after:
+                                                self.textDocumentProxy
+                                                    .documentContextAfterInput];
+    [[KBBackspaceUndoManager shared]
+        captureAndDeleteBackwardFromProxy:self.textDocumentProxy
+                                    count:1];
+    [self kb_scheduleContextRefreshResetSuppression:NO];
+    [[KBInputBufferManager shared] applyHoldDeleteCount:1];
+    break;
+  case KBKeyTypeSpace:
+    [[KBBackspaceUndoManager shared] registerNonClearAction];
+    [self.textDocumentProxy insertText:@" "];
+    [self kb_clearCurrentWord];
+    [[KBInputBufferManager shared] appendText:@" "];
+    break;
+  case KBKeyTypeReturn:
+    if (self.chatPanelVisible) {
+      [self kb_handleChatSendAction];
+      break;
+    }
+    [[KBBackspaceUndoManager shared] registerNonClearAction];
+    [self.textDocumentProxy insertText:@"\n"];
+    [self kb_clearCurrentWord];
+    [[KBInputBufferManager shared] appendText:@"\n"];
+    break;
+  case KBKeyTypeGlobe:
+    [self advanceToNextInputMode];
+    break;
+  case KBKeyTypeCustom:
+    [[KBBackspaceUndoManager shared] registerNonClearAction];
+    // 点击自定义键切换到功能面板
+    [self kb_setPanelMode:KBKeyboardPanelModeFunction animated:NO];
+    [self kb_clearCurrentWord];
+    break;
+  case KBKeyTypeModeChange:
+  case KBKeyTypeShift:
+    // 这些已在 KBKeyBoardMainView/KBKeyboardView 内部处理
+    break;
+  }
+}
+
+- (void)keyBoardMainView:(KBKeyBoardMainView *)keyBoardMainView
+    didTapToolActionAtIndex:(NSInteger)index {
+  NSDictionary *extra = @{@"index" : @(index)};
+  [[KBMaiPointReporter sharedReporter]
+      reportClickWithEventName:@"click_keyboard_toolbar_action"
+                        pageId:@"keyboard_main_panel"
+                     elementId:@"toolbar_action"
+                         extra:extra
+                    completion:nil];
+  if (index == 0) {
+    [self kb_setPanelMode:KBKeyboardPanelModeFunction animated:YES];
+    [self kb_clearCurrentWord];
+    return;
+  }
+  if (index == 1) {
+    [self kb_setPanelMode:KBKeyboardPanelModeChat animated:YES];
+    return;
+  }
+  [self kb_setPanelMode:KBKeyboardPanelModeMain animated:YES];
+}
+
+- (void)keyBoardMainViewDidTapSettings:(KBKeyBoardMainView *)keyBoardMainView {
+  [[KBMaiPointReporter sharedReporter]
+      reportClickWithEventName:@"click_keyboard_settings_btn"
+                        pageId:@"keyboard_main_panel"
+                     elementId:@"settings_btn"
+                         extra:nil
+                    completion:nil];
+  [self kb_setPanelMode:KBKeyboardPanelModeSettings animated:YES];
+}
+
+- (void)keyBoardMainView:(KBKeyBoardMainView *)keyBoardMainView
+          didSelectEmoji:(NSString *)emoji {
+  if (emoji.length == 0) {
+    return;
+  }
+  [[KBBackspaceUndoManager shared] registerNonClearAction];
+  [self.textDocumentProxy insertText:emoji];
+  [self kb_clearCurrentWord];
+  [[KBInputBufferManager shared] appendText:emoji];
+}
+
+- (void)keyBoardMainViewDidTapUndo:(KBKeyBoardMainView *)keyBoardMainView {
+  [[KBMaiPointReporter sharedReporter]
+      reportClickWithEventName:@"click_keyboard_undo_btn"
+                        pageId:@"keyboard_main_panel"
+                     elementId:@"undo_btn"
+                         extra:nil
+                    completion:nil];
+  [[KBBackspaceUndoManager shared] performUndoFromResponder:self.view];
+  [self kb_scheduleContextRefreshResetSuppression:YES];
+}
+
+- (void)keyBoardMainViewDidTapEmojiSearch:
+    (KBKeyBoardMainView *)keyBoardMainView {
+  //  [[KBMaiPointReporter sharedReporter]
+  //      reportClickWithEventName:@"click_keyboard_emoji_search_btn"
+  //                        pageId:@"keyboard_main_panel"
+  //                     elementId:@"emoji_search_btn"
+  //                         extra:nil
+  //                    completion:nil];
+  [KBHUD showInfo:KBLocalized(@"Search coming soon")];
+}
+
+// MARK: - KBFunctionViewDelegate
+
+- (void)functionView:(KBFunctionView *)functionView
+    didTapToolActionAtIndex:(NSInteger)index {
+  // 需求：当 index == 0 时，切回键盘主视图
+  if (index == 0) {
+    [self kb_setPanelMode:KBKeyboardPanelModeMain animated:NO];
+  }
+}
+
+- (void)functionView:(KBFunctionView *_Nullable)functionView
+    didRightTapToolActionAtIndex:(NSInteger)index {
+  [[KBMaiPointReporter sharedReporter]
+      reportClickWithEventName:@"click_keyboard_function_right_action"
+                        pageId:@"keyboard_function_panel"
+                     elementId:@"right_action"
+                         extra:@{@"action" : @"login_or_recharge"}
+                    completion:nil];
+  if (!KBAuthManager.shared.isLoggedIn) {
+    NSString *schemeStr =
+        [NSString stringWithFormat:@"%@://login?src=keyboard", KB_APP_SCHEME];
+    NSURL *scheme = [NSURL URLWithString:schemeStr];
+    // 从当前视图作为起点，通过响应链找到 UIApplication 再调起主 App
+    BOOL ok = [KBHostAppLauncher openHostAppURL:scheme fromResponder:self.view];
+    return;
+  }
+  NSString *schemeStr =
+      [NSString stringWithFormat:@"%@://recharge?src=keyboard", KB_APP_SCHEME];
+  NSURL *scheme = [NSURL URLWithString:schemeStr];
+  // 从当前视图作为起点，通过响应链找到 UIApplication 再调起主 App
+  BOOL ok = [KBHostAppLauncher openHostAppURL:scheme fromResponder:self.view];
+
+  if (!ok) {
+    // 失败兜底：给个文案提示
+    // 比如：请回到桌面手动打开 XXX App 进行设置/充值
+    [KBHUD showInfo:@"请回到桌面手动打开App进行充值"];
+  }
+}
+
+- (void)functionViewDidRequestSubscription:(KBFunctionView *)functionView {
+  [self showSubscriptionPanel];
+}
+
+#pragma mark - Actions
+
+- (void)onTapSettingsBack {
+  [[KBMaiPointReporter sharedReporter]
+      reportClickWithEventName:@"click_keyboard_settings_back_btn"
+                        pageId:@"keyboard_settings"
+                     elementId:@"back_btn"
+                         extra:nil
+                    completion:nil];
+  [self kb_setPanelMode:KBKeyboardPanelModeMain animated:YES];
+}
+
+@end

CustomKeyboard/KeyboardViewControllerHelp/KeyboardViewController+Private.h

@@ -0,0 +1,154 @@
+//
+//  KeyboardViewController+Private.h
+//  CustomKeyboard
+//
+//  Created by Codex on 2026/02/22.
+//
+
+#import "KeyboardViewController.h"
+#import "Masonry.h"
+
+@class AVAudioPlayer;
+@class CAGradientLayer;
+@class KBChatMessage;
+@class KBChatPanelView;
+@class KBFunctionView;
+@class KBKeyBoardMainView;
+@class KBKeyboardSubscriptionView;
+@class KBSettingView;
+@class KBSuggestionEngine;
+
+@protocol KBChatLimitPopViewDelegate;
+@protocol KBChatPanelViewDelegate;
+@protocol KBFunctionViewDelegate;
+@protocol KBKeyBoardMainViewDelegate;
+@protocol KBKeyboardSubscriptionViewDelegate;
+
+typedef NS_ENUM(NSInteger, KBKeyboardPanelMode) {
+  KBKeyboardPanelModeMain = 0,
+  KBKeyboardPanelModeFunction,
+  KBKeyboardPanelModeChat,
+  KBKeyboardPanelModeSettings,
+  KBKeyboardPanelModeSubscription,
+};
+
+@interface KeyboardViewController () <KBKeyBoardMainViewDelegate,
+                                      KBFunctionViewDelegate,
+                                      KBKeyboardSubscriptionViewDelegate,
+                                      KBChatPanelViewDelegate,
+                                      KBChatLimitPopViewDelegate>
+{
+  UIButton *_nextKeyboardButton;
+  UIView *_contentView;
+  KBKeyBoardMainView *_keyBoardMainView;
+  KBFunctionView *_functionView;
+  KBSettingView *_settingView;
+  UIImageView *_bgImageView;
+  KBChatPanelView *_chatPanelView;
+  KBKeyboardSubscriptionView *_subscriptionView;
+  KBSuggestionEngine *_suggestionEngine;
+  NSString *_currentWord;
+  UIControl *_chatLimitMaskView;
+  MASConstraint *_contentWidthConstraint;
+  MASConstraint *_contentHeightConstraint;
+  MASConstraint *_keyBoardMainHeightConstraint;
+  MASConstraint *_chatPanelHeightConstraint;
+  NSLayoutConstraint *_kb_heightConstraint;
+  NSLayoutConstraint *_kb_widthConstraint;
+  CGFloat _kb_lastPortraitWidth;
+  CGFloat _kb_lastKeyboardHeight;
+  UIImage *_kb_cachedGradientImage;
+  CGSize _kb_cachedGradientSize;
+  CAGradientLayer *_kb_defaultGradientLayer;
+  NSString *_kb_lastAppliedThemeKey;
+  NSMutableArray<KBChatMessage *> *_chatMessages;
+  AVAudioPlayer *_chatAudioPlayer;
+  BOOL _suppressSuggestions;
+  BOOL _chatPanelVisible;
+  NSString *_chatPanelBaselineText;
+  id _kb_fullAccessObserverToken;
+  id _kb_skinObserverToken;
+  KBKeyboardPanelMode _kb_panelMode;
+}
+
+@property(nonatomic, strong)
+    UIButton *nextKeyboardButton; // 系统“下一个键盘”按钮（可选）
+@property(nonatomic, strong) UIView *contentView;
+@property(nonatomic, strong) KBKeyBoardMainView
+    *keyBoardMainView; // 功能面板视图（点击工具栏第0个时显示）
+@property(nonatomic, strong)
+    KBFunctionView *functionView; // 功能面板视图（点击工具栏第0个时显示）
+@property(nonatomic, strong) KBSettingView *settingView; // 设置页
+@property(nonatomic, strong) UIImageView *bgImageView;   // 背景图（在底层）
+@property(nonatomic, strong) KBChatPanelView *chatPanelView;
+@property(nonatomic, strong) KBKeyboardSubscriptionView *subscriptionView;
+@property(nonatomic, strong) KBSuggestionEngine *suggestionEngine;
+@property(nonatomic, copy) NSString *currentWord;
+@property(nonatomic, assign) BOOL suppressSuggestions;
+@property(nonatomic, strong) UIControl *chatLimitMaskView;
+@property(nonatomic, strong) MASConstraint *contentWidthConstraint;
+@property(nonatomic, strong) MASConstraint *contentHeightConstraint;
+@property(nonatomic, strong) MASConstraint *keyBoardMainHeightConstraint;
+@property(nonatomic, strong) MASConstraint *chatPanelHeightConstraint;
+@property(nonatomic, strong) NSLayoutConstraint *kb_heightConstraint;
+@property(nonatomic, strong) NSLayoutConstraint *kb_widthConstraint;
+@property(nonatomic, assign) CGFloat kb_lastPortraitWidth;
+@property(nonatomic, assign) CGFloat kb_lastKeyboardHeight;
+@property(nonatomic, strong) UIImage *kb_cachedGradientImage;
+@property(nonatomic, assign) CGSize kb_cachedGradientSize;
+@property(nonatomic, strong, nullable) CAGradientLayer *kb_defaultGradientLayer;
+@property(nonatomic, copy, nullable) NSString *kb_lastAppliedThemeKey;
+@property(nonatomic, strong) NSMutableArray<KBChatMessage *> *chatMessages;
+@property(nonatomic, strong) AVAudioPlayer *chatAudioPlayer;
+@property(nonatomic, assign) BOOL chatPanelVisible;
+@property(nonatomic, copy) NSString *chatPanelBaselineText; // 打开聊天面板时宿主输入框已有的文本
+@property(nonatomic, strong, nullable) id kb_fullAccessObserverToken;
+@property(nonatomic, strong, nullable) id kb_skinObserverToken;
+@property(nonatomic, assign) KBKeyboardPanelMode kb_panelMode;
+
+@end
+
+@interface KeyboardViewController (KBPrivate)
+
+// UI
+- (void)setupUI;
+- (nullable KBFunctionView *)kb_functionViewIfCreated;
+
+// Panels
+- (void)showFunctionPanel:(BOOL)show;
+- (void)showSettingView:(BOOL)show;
+- (void)showChatPanel:(BOOL)show;
+- (void)showSubscriptionPanel;
+- (void)hideSubscriptionPanel;
+- (void)kb_setPanelMode:(KBKeyboardPanelMode)mode animated:(BOOL)animated;
+- (void)kb_ensureFunctionViewIfNeeded;
+- (void)kb_ensureChatPanelViewIfNeeded;
+- (void)kb_ensureKeyBoardMainViewIfNeeded;
+- (void)kb_releaseMemoryWhenKeyboardHidden;
+
+// Suggestions
+- (void)kb_updateCurrentWordWithInsertedText:(NSString *)text;
+- (void)kb_clearCurrentWord;
+- (void)kb_scheduleContextRefreshResetSuppression:(BOOL)resetSuppression;
+- (void)kb_refreshCurrentWordFromDocumentContextResetSuppression:
+    (BOOL)resetSuppression;
+- (void)kb_updateSuggestionsForCurrentWord;
+
+// Chat
+- (void)kb_handleChatSendAction;
+
+// Theme
+- (void)kb_applyTheme;
+- (void)kb_applyDefaultSkinIfNeeded;
+- (void)kb_consumePendingShopSkin;
+- (void)kb_registerDarwinSkinInstallObserver;
+- (void)kb_unregisterDarwinSkinInstallObserver;
+
+// Layout
+- (CGFloat)kb_portraitWidth;
+- (CGFloat)kb_keyboardHeightForWidth:(CGFloat)width;
+- (CGFloat)kb_keyboardBaseHeightForWidth:(CGFloat)width;
+- (CGFloat)kb_chatPanelHeightForWidth:(CGFloat)width;
+- (void)kb_updateKeyboardLayoutIfNeeded;
+
+@end

CustomKeyboard/KeyboardViewControllerHelp/KeyboardViewController+Subscription.m

@@ -0,0 +1,117 @@
+//
+//  KeyboardViewController+Subscription.m
+//  CustomKeyboard
+//
+//  Created by Codex on 2026/02/22.
+//
+
+#import "KeyboardViewController+Private.h"
+
+#import "KBAuthManager.h"
+#import "KBFullAccessManager.h"
+#import "KBHostAppLauncher.h"
+#import "KBKeyboardSubscriptionProduct.h"
+#import "KBKeyboardSubscriptionView.h"
+
+@implementation KeyboardViewController (Subscription)
+
+- (void)showSubscriptionPanel {
+  // 1) 先判断权限：未开启“完全访问”则走引导逻辑
+  if (![[KBFullAccessManager shared] hasFullAccess]) {
+    // 未开启完全访问：保持原有引导路径
+    //        [KBHUD showInfo:KBLocalized(@"处理中…")];
+    [[KBFullAccessManager shared] ensureFullAccessOrGuideInView:self.view];
+    return;
+  }
+  // 点击充值要先判断是否登录
+  // 2) 权限没问题，再判断是否登录：未登录 -> 直接拉起主 App，由主 App 负责完成登录
+  if (!KBAuthManager.shared.isLoggedIn) {
+    NSString *schemeStr =
+        [NSString stringWithFormat:@"%@://login?src=keyboard", KB_APP_SCHEME];
+    NSURL *scheme = [NSURL URLWithString:schemeStr];
+    // 从当前视图作为起点，通过响应链找到 UIApplication 再调起主 App
+    BOOL ok = [KBHostAppLauncher openHostAppURL:scheme fromResponder:self.view];
+    return;
+  }
+  [self kb_setPanelMode:KBKeyboardPanelModeSubscription animated:YES];
+}
+
+- (void)hideSubscriptionPanel {
+  if (self.kb_panelMode != KBKeyboardPanelModeSubscription) {
+    return;
+  }
+  [self kb_setPanelMode:KBKeyboardPanelModeMain animated:YES];
+}
+
+#pragma mark - KBKeyboardSubscriptionViewDelegate
+
+- (void)subscriptionViewDidTapClose:(KBKeyboardSubscriptionView *)view {
+  [[KBMaiPointReporter sharedReporter]
+      reportClickWithEventName:@"click_keyboard_subscription_close_btn"
+                        pageId:@"keyboard_subscription_panel"
+                     elementId:@"close_btn"
+                         extra:nil
+                    completion:nil];
+  [self hideSubscriptionPanel];
+}
+
+- (void)subscriptionView:(KBKeyboardSubscriptionView *)view
+    didTapPurchaseForProduct:(KBKeyboardSubscriptionProduct *)product {
+  NSMutableDictionary *extra = [NSMutableDictionary dictionary];
+  if ([product.productId isKindOfClass:NSString.class] &&
+      product.productId.length > 0) {
+    extra[@"product_id"] = product.productId;
+  }
+  [[KBMaiPointReporter sharedReporter]
+      reportClickWithEventName:@"click_keyboard_subscription_product_btn"
+                        pageId:@"keyboard_subscription_panel"
+                     elementId:@"product_btn"
+                         extra:extra.copy
+                    completion:nil];
+  [self hideSubscriptionPanel];
+  [self kb_openRechargeForProduct:product];
+}
+
+#pragma mark - Actions
+
+- (void)kb_openRechargeForProduct:(KBKeyboardSubscriptionProduct *)product {
+  if (![product isKindOfClass:KBKeyboardSubscriptionProduct.class] ||
+      product.productId.length == 0) {
+    [KBHUD showInfo:KBLocalized(@"Product unavailable")];
+    return;
+  }
+  NSString *encodedId = [self.class kb_urlEncodedString:product.productId];
+  NSString *title = [product displayTitle];
+  NSString *encodedTitle = [self.class kb_urlEncodedString:title];
+  NSMutableArray<NSString *> *params =
+      [NSMutableArray arrayWithObjects:@"autoPay=1", @"prefill=1", nil];
+  if (encodedId.length) {
+    [params addObject:[NSString stringWithFormat:@"productId=%@", encodedId]];
+  }
+  if (encodedTitle.length) {
+    [params
+        addObject:[NSString stringWithFormat:@"productTitle=%@", encodedTitle]];
+  }
+  NSString *query = [params componentsJoinedByString:@"&"];
+  NSString *urlString = [NSString
+      stringWithFormat:@"%@://recharge?src=keyboard&%@", KB_APP_SCHEME, query];
+  NSURL *scheme = [NSURL URLWithString:urlString];
+  BOOL success = [KBHostAppLauncher openHostAppURL:scheme fromResponder:self.view];
+  if (!success) {
+    [KBHUD showInfo:KBLocalized(@"Please open the App to finish purchase")];
+  }
+}
+
++ (NSString *)kb_urlEncodedString:(NSString *)value {
+  if (value.length == 0) {
+    return @"";
+  }
+  NSString *reserved = @"!*'();:@&=+$,/?%#[]";
+  NSMutableCharacterSet *allowed =
+      [[NSCharacterSet URLQueryAllowedCharacterSet] mutableCopy];
+  [allowed removeCharactersInString:reserved];
+  return [value stringByAddingPercentEncodingWithAllowedCharacters:allowed]
+             ?: @"";
+}
+
+@end

CustomKeyboard/KeyboardViewControllerHelp/KeyboardViewController+Suggestions.m

@@ -0,0 +1,178 @@
+//
+//  KeyboardViewController+Suggestions.m
+//  CustomKeyboard
+//
+//  Created by Codex on 2026/02/22.
+//
+
+#import "KeyboardViewController+Private.h"
+
+#import "KBBackspaceUndoManager.h"
+#import "KBInputBufferManager.h"
+#import "KBKeyBoardMainView.h"
+#import "KBSuggestionEngine.h"
+
+@implementation KeyboardViewController (Suggestions)
+
+// MARK: - Suggestions
+
+- (void)kb_updateCurrentWordWithInsertedText:(NSString *)text {
+  if (text.length == 0) {
+    return;
+  }
+  if ([self kb_isAlphabeticString:text]) {
+    NSString *current = self.currentWord ?: @"";
+    self.currentWord = [current stringByAppendingString:text];
+    self.suppressSuggestions = NO;
+    [self kb_updateSuggestionsForCurrentWord];
+  } else {
+    [self kb_clearCurrentWord];
+  }
+}
+
+- (void)kb_clearCurrentWord {
+  self.currentWord = @"";
+  [self.keyBoardMainView kb_setSuggestions:@[]];
+  self.suppressSuggestions = NO;
+}
+
+- (void)kb_scheduleContextRefreshResetSuppression:(BOOL)resetSuppression {
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [self kb_refreshCurrentWordFromDocumentContextResetSuppression:
+              resetSuppression];
+  });
+}
+
+- (void)kb_refreshCurrentWordFromDocumentContextResetSuppression:
+    (BOOL)resetSuppression {
+  NSString *context = self.textDocumentProxy.documentContextBeforeInput ?: @"";
+  NSString *word = [self kb_extractTrailingWordFromContext:context];
+  self.currentWord = word ?: @"";
+  if (resetSuppression) {
+    self.suppressSuggestions = NO;
+  }
+  [self kb_updateSuggestionsForCurrentWord];
+}
+
+- (NSString *)kb_extractTrailingWordFromContext:(NSString *)context {
+  if (context.length == 0) {
+    return @"";
+  }
+  static NSCharacterSet *letters = nil;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    letters = [NSCharacterSet
+        characterSetWithCharactersInString:
+            @"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"];
+  });
+
+  NSInteger idx = (NSInteger)context.length - 1;
+  while (idx >= 0) {
+    unichar ch = [context characterAtIndex:(NSUInteger)idx];
+    if (![letters characterIsMember:ch]) {
+      break;
+    }
+    idx -= 1;
+  }
+  NSUInteger start = (NSUInteger)(idx + 1);
+  if (start >= context.length) {
+    return @"";
+  }
+  return [context substringFromIndex:start];
+}
+
+- (BOOL)kb_isAlphabeticString:(NSString *)text {
+  if (text.length == 0) {
+    return NO;
+  }
+  static NSCharacterSet *letters = nil;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    letters = [NSCharacterSet
+        characterSetWithCharactersInString:
+            @"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"];
+  });
+  for (NSUInteger i = 0; i < text.length; i++) {
+    if (![letters characterIsMember:[text characterAtIndex:i]]) {
+      return NO;
+    }
+  }
+  return YES;
+}
+
+- (void)kb_updateSuggestionsForCurrentWord {
+  NSString *prefix = self.currentWord ?: @"";
+  if (prefix.length == 0) {
+    [self.keyBoardMainView kb_setSuggestions:@[]];
+    return;
+  }
+  if (self.suppressSuggestions) {
+    [self.keyBoardMainView kb_setSuggestions:@[]];
+    return;
+  }
+  NSArray<NSString *> *items =
+      [self.suggestionEngine suggestionsForPrefix:prefix limit:5];
+  NSArray<NSString *> *cased = [self kb_applyCaseToSuggestions:items
+                                                        prefix:prefix];
+  [self.keyBoardMainView kb_setSuggestions:cased];
+}
+
+- (NSArray<NSString *> *)kb_applyCaseToSuggestions:(NSArray<NSString *> *)items
+                                            prefix:(NSString *)prefix {
+  if (items.count == 0 || prefix.length == 0) {
+    return items;
+  }
+  BOOL allUpper = [prefix isEqualToString:prefix.uppercaseString];
+  BOOL firstUpper = [[prefix substringToIndex:1]
+      isEqualToString:[[prefix substringToIndex:1] uppercaseString]];
+
+  if (!allUpper && !firstUpper) {
+    return items;
+  }
+
+  NSMutableArray<NSString *> *result =
+      [NSMutableArray arrayWithCapacity:items.count];
+  for (NSString *word in items) {
+    if (allUpper) {
+      [result addObject:word.uppercaseString];
+    } else {
+      NSString *first = [[word substringToIndex:1] uppercaseString];
+      NSString *rest = (word.length > 1) ? [word substringFromIndex:1] : @"";
+      [result addObject:[first stringByAppendingString:rest]];
+    }
+  }
+  return result.copy;
+}
+
+// MARK: - KBKeyBoardMainViewDelegate (Suggestion)
+
+- (void)keyBoardMainView:(KBKeyBoardMainView *)keyBoardMainView
+     didSelectSuggestion:(NSString *)suggestion {
+  if (suggestion.length == 0) {
+    return;
+  }
+  NSDictionary *extra = @{@"suggestion_len" : @(suggestion.length)};
+  //  [[KBMaiPointReporter sharedReporter]
+  //      reportClickWithEventName:@"click_keyboard_suggestion_item"
+  //                        pageId:@"keyboard_main_panel"
+  //                     elementId:@"suggestion_item"
+  //                         extra:extra
+  //                    completion:nil];
+  [[KBBackspaceUndoManager shared] registerNonClearAction];
+  NSString *current = self.currentWord ?: @"";
+  if (current.length > 0) {
+    for (NSUInteger i = 0; i < current.length; i++) {
+      [self.textDocumentProxy deleteBackward];
+    }
+  }
+  [self.textDocumentProxy insertText:suggestion];
+  self.currentWord = suggestion;
+  [self.suggestionEngine recordSelection:suggestion];
+  self.suppressSuggestions = YES;
+  [self.keyBoardMainView kb_setSuggestions:@[]];
+  [[KBInputBufferManager shared] replaceTailWithText:suggestion
+                                         deleteCount:current.length];
+}
+
+@end
+

CustomKeyboard/KeyboardViewControllerHelp/KeyboardViewController+Theme.m

@@ -0,0 +1,376 @@
+//
+//  KeyboardViewController+Theme.m
+//  CustomKeyboard
+//
+//  Created by Codex on 2026/02/22.
+//
+
+#import "KeyboardViewController+Private.h"
+
+#import "KBFunctionView.h"
+#import "KBKeyBoardMainView.h"
+#import "KBSkinInstallBridge.h"
+#import "KBSkinManager.h"
+#import "UIImage+KBColor.h"
+#import <QuartzCore/QuartzCore.h>
+
+static NSString *const kKBDefaultSkinIdLight = @"normal_them";
+static NSString *const kKBDefaultSkinZipNameLight = @"normal_them";
+static NSString *const kKBDefaultSkinIdDark = @"normal_hei_them";
+static NSString *const kKBDefaultSkinZipNameDark = @"normal_hei_them";
+
+// 提前声明一个类别，使编译器在 static 回调中识别 kb_consumePendingShopSkin 方法。
+@interface KeyboardViewController (KBSkinShopBridge)
+- (void)kb_consumePendingShopSkin;
+@end
+
+static void KBSkinInstallNotificationCallback(CFNotificationCenterRef center,
+                                              void *observer, CFStringRef name,
+                                              const void *object,
+                                              CFDictionaryRef userInfo) {
+  KeyboardViewController *strongSelf =
+      (__bridge KeyboardViewController *)observer;
+  if (!strongSelf) {
+    return;
+  }
+  dispatch_async(dispatch_get_main_queue(), ^{
+    if ([strongSelf respondsToSelector:@selector(kb_consumePendingShopSkin)]) {
+      [strongSelf kb_consumePendingShopSkin];
+    }
+  });
+}
+
+@implementation KeyboardViewController (Theme)
+
+- (void)kb_registerDarwinSkinInstallObserver {
+  CFNotificationCenterAddObserver(
+      CFNotificationCenterGetDarwinNotifyCenter(),
+      (__bridge const void *)(self), KBSkinInstallNotificationCallback,
+      (__bridge CFStringRef)KBDarwinSkinInstallRequestNotification, NULL,
+      CFNotificationSuspensionBehaviorDeliverImmediately);
+}
+
+- (void)kb_unregisterDarwinSkinInstallObserver {
+  CFNotificationCenterRemoveObserver(
+      CFNotificationCenterGetDarwinNotifyCenter(),
+      (__bridge const void *)(self),
+      (__bridge CFStringRef)KBDarwinSkinInstallRequestNotification, NULL);
+}
+
+- (void)kb_applyTheme {
+  @autoreleasepool {
+    KBSkinTheme *t = [KBSkinManager shared].current;
+    UIImage *img = nil;
+    BOOL isDefaultTheme = [self kb_isDefaultKeyboardTheme:t];
+    BOOL isDarkMode = [self kb_isDarkModeActive];
+
+    NSString *skinId = t.skinId ?: @"";
+    NSString *themeKey =
+        [NSString stringWithFormat:@"%@|default=%d|dark=%d", skinId,
+                                   isDefaultTheme, isDarkMode];
+    BOOL themeChanged =
+        (self.kb_lastAppliedThemeKey.length == 0 ||
+         ![self.kb_lastAppliedThemeKey isEqualToString:themeKey]);
+    if (themeChanged) {
+      self.kb_lastAppliedThemeKey = themeKey;
+    }
+
+    CGSize size = self.bgImageView.bounds.size;
+    if (isDefaultTheme) {
+      if (isDarkMode) {
+        // 暗黑模式：直接使用背景色，不使用图片渲染
+        // 这样可以避免图片渲染时的色彩空间转换导致颜色不一致
+        img = nil;
+        self.bgImageView.image = nil;
+        [self.kb_defaultGradientLayer removeFromSuperlayer];
+        self.kb_defaultGradientLayer = nil;
+        // 使用与系统键盘底部完全相同的颜色
+        if (@available(iOS 13.0, *)) {
+          // iOS 系统键盘使用的实际颜色 (RGB: 44, 44, 46 in sRGB, 或 #2C2C2E)
+          // 但为了完美匹配，我们使用动态颜色并直接设置为背景
+          UIColor *kbBgColor =
+              [UIColor colorWithDynamicProvider:^UIColor *_Nonnull(
+                           UITraitCollection *_Nonnull traitCollection) {
+                if (traitCollection.userInterfaceStyle ==
+                    UIUserInterfaceStyleDark) {
+                  // 暗黑模式下系统键盘实际背景色
+                  return [UIColor colorWithRed:43.0 / 255.0
+                                         green:43.0 / 255.0
+                                          blue:43.0 / 255.0
+                                         alpha:1.0];
+                } else {
+                  return [UIColor colorWithRed:209.0 / 255.0
+                                         green:211.0 / 255.0
+                                          blue:219.0 / 255.0
+                                         alpha:1.0];
+                }
+              }];
+          self.contentView.backgroundColor = kbBgColor;
+          self.bgImageView.backgroundColor = kbBgColor;
+        } else {
+          UIColor *darkColor = [UIColor colorWithRed:43.0 / 255.0
+                                               green:43.0 / 255.0
+                                                blue:43.0 / 255.0
+                                               alpha:1.0];
+          self.contentView.backgroundColor = darkColor;
+          self.bgImageView.backgroundColor = darkColor;
+        }
+      } else {
+        // 浅色模式：使用渐变层（避免生成大位图导致内存上涨）
+        if (size.width <= 0 || size.height <= 0) {
+          [self.view layoutIfNeeded];
+          size = self.bgImageView.bounds.size;
+        }
+        if (size.width <= 0 || size.height <= 0) {
+          size = self.view.bounds.size;
+        }
+        if (size.width <= 0 || size.height <= 0) {
+          size = [UIScreen mainScreen].bounds.size;
+        }
+        UIColor *topColor = [UIColor colorWithHex:0xDEDFE4];
+        UIColor *bottomColor = [UIColor colorWithHex:0xD1D3DB];
+        UIColor *resolvedTopColor = topColor;
+        UIColor *resolvedBottomColor = bottomColor;
+        if (@available(iOS 13.0, *)) {
+          resolvedTopColor =
+              [topColor resolvedColorWithTraitCollection:self.traitCollection];
+          resolvedBottomColor =
+              [bottomColor resolvedColorWithTraitCollection:self.traitCollection];
+        }
+        CAGradientLayer *layer = self.kb_defaultGradientLayer;
+        if (!layer) {
+          layer = [CAGradientLayer layer];
+          layer.startPoint = CGPointMake(0.5, 0.0);
+          layer.endPoint = CGPointMake(0.5, 1.0);
+          [self.bgImageView.layer insertSublayer:layer atIndex:0];
+          self.kb_defaultGradientLayer = layer;
+        }
+        layer.colors =
+            @[ (id)resolvedTopColor.CGColor, (id)resolvedBottomColor.CGColor ];
+        layer.frame = (CGRect){CGPointZero, size};
+        img = nil;
+        self.bgImageView.image = nil;
+        self.contentView.backgroundColor = [UIColor clearColor];
+        self.bgImageView.backgroundColor = [UIColor clearColor];
+      }
+      NSLog(@"===");
+    } else {
+      // 自定义皮肤：清除背景色，使用皮肤图片
+      self.contentView.backgroundColor = [UIColor clearColor];
+      self.bgImageView.backgroundColor = [UIColor clearColor];
+      [self.kb_defaultGradientLayer removeFromSuperlayer];
+      self.kb_defaultGradientLayer = nil;
+      img = [[KBSkinManager shared] currentBackgroundImage];
+    }
+    NSLog(@"⌨️[Keyboard] apply theme id=%@ hasBg=%d", t.skinId, (img != nil));
+    [self kb_logSkinDiagnosticsWithTheme:t backgroundImage:img];
+    self.bgImageView.image = img;
+
+	    // 触发键区按主题重绘
+	    if (themeChanged &&
+	        [self.keyBoardMainView respondsToSelector:@selector(kb_applyTheme)]) {
+	      // method declared in KBKeyBoardMainView.h
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Warc-performSelector-leaks"
+	      [self.keyBoardMainView performSelector:@selector(kb_applyTheme)];
+#pragma clang diagnostic pop
+	    }
+	    // 注意：这里不能直接访问 self.functionView，否则会导致功能面板提前创建，占用内存。
+	    KBFunctionView *functionView = [self kb_functionViewIfCreated];
+	    if (themeChanged && functionView &&
+	        [functionView respondsToSelector:@selector(kb_applyTheme)]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Warc-performSelector-leaks"
+	      [functionView performSelector:@selector(kb_applyTheme)];
+#pragma clang diagnostic pop
+	    }
+	  }
+	}
+
+- (BOOL)kb_isDefaultKeyboardTheme:(KBSkinTheme *)theme {
+  NSString *skinId = theme.skinId ?: @"";
+  if (skinId.length == 0 || [skinId isEqualToString:@"default"]) {
+    return YES;
+  }
+  if ([skinId isEqualToString:kKBDefaultSkinIdLight]) {
+    return YES;
+  }
+  return [skinId isEqualToString:kKBDefaultSkinIdDark];
+}
+
+- (BOOL)kb_isDarkModeActive {
+  if (@available(iOS 13.0, *)) {
+    return self.traitCollection.userInterfaceStyle == UIUserInterfaceStyleDark;
+  }
+  return NO;
+}
+
+- (NSString *)kb_defaultSkinIdForCurrentStyle {
+  return [self kb_isDarkModeActive] ? kKBDefaultSkinIdDark
+                                    : kKBDefaultSkinIdLight;
+}
+
+- (NSString *)kb_defaultSkinZipNameForCurrentStyle {
+  return [self kb_isDarkModeActive] ? kKBDefaultSkinZipNameDark
+                                    : kKBDefaultSkinZipNameLight;
+}
+
+- (UIImage *)kb_defaultGradientImageWithSize:(CGSize)size
+                                    topColor:(UIColor *)topColor
+                                 bottomColor:(UIColor *)bottomColor {
+  if (size.width <= 0 || size.height <= 0) {
+    return nil;
+  }
+
+  // 尺寸未变则复用缓存，避免反复创建图片撑爆键盘扩展内存
+  if (self.kb_cachedGradientImage &&
+      CGSizeEqualToSize(self.kb_cachedGradientSize, size)) {
+    return self.kb_cachedGradientImage;
+  }
+
+  UIColor *resolvedTopColor = topColor;
+  UIColor *resolvedBottomColor = bottomColor;
+  if (@available(iOS 13.0, *)) {
+    resolvedTopColor =
+        [topColor resolvedColorWithTraitCollection:self.traitCollection];
+    resolvedBottomColor =
+        [bottomColor resolvedColorWithTraitCollection:self.traitCollection];
+  }
+
+  CAGradientLayer *layer = [CAGradientLayer layer];
+  layer.frame = CGRectMake(0, 0, size.width, size.height);
+  layer.startPoint = CGPointMake(0.5, 0.0);
+  layer.endPoint = CGPointMake(0.5, 1.0);
+  layer.colors =
+      @[ (id)resolvedTopColor.CGColor, (id)resolvedBottomColor.CGColor ];
+
+  UIGraphicsBeginImageContextWithOptions(size, YES, 0);
+  [layer renderInContext:UIGraphicsGetCurrentContext()];
+  UIImage *image = UIGraphicsGetImageFromCurrentImageContext();
+  UIGraphicsEndImageContext();
+
+  self.kb_cachedGradientImage = image;
+  self.kb_cachedGradientSize = size;
+  return image;
+}
+
+- (void)kb_logSkinDiagnosticsWithTheme:(KBSkinTheme *)theme
+                       backgroundImage:(UIImage *)image {
+#if DEBUG
+  NSString *skinId = theme.skinId ?: @"";
+  NSString *name = theme.name ?: @"";
+  NSMutableArray<NSString *> *roots = [NSMutableArray array];
+  NSURL *containerURL = [[NSFileManager defaultManager]
+      containerURLForSecurityApplicationGroupIdentifier:AppGroup];
+  if (containerURL.path.length > 0) {
+    [roots addObject:containerURL.path];
+  }
+  NSString *cacheRoot = NSSearchPathForDirectoriesInDomains(
+                            NSCachesDirectory, NSUserDomainMask, YES)
+                            .firstObject;
+  if (cacheRoot.length > 0) {
+    [roots addObject:cacheRoot];
+  }
+
+  NSFileManager *fm = [NSFileManager defaultManager];
+  NSMutableArray<NSString *> *lines = [NSMutableArray array];
+  for (NSString *root in roots) {
+    NSString *iconsDir = [[root stringByAppendingPathComponent:@"Skins"]
+        stringByAppendingPathComponent:skinId];
+    iconsDir = [iconsDir stringByAppendingPathComponent:@"icons"];
+    BOOL isDir = NO;
+    BOOL exists = [fm fileExistsAtPath:iconsDir isDirectory:&isDir] && isDir;
+    NSArray *contents =
+        exists ? [fm contentsOfDirectoryAtPath:iconsDir error:nil] : nil;
+    NSUInteger count = contents.count;
+    BOOL hasQ =
+        exists &&
+        [fm fileExistsAtPath:[iconsDir
+                                 stringByAppendingPathComponent:@"key_q.png"]];
+    BOOL hasQUp =
+        exists && [fm fileExistsAtPath:[iconsDir stringByAppendingPathComponent:
+                                                     @"key_q_up.png"]];
+    BOOL hasDel =
+        exists && [fm fileExistsAtPath:[iconsDir stringByAppendingPathComponent:
+                                                     @"key_del.png"]];
+    BOOL hasShift =
+        exists &&
+        [fm fileExistsAtPath:[iconsDir
+                                 stringByAppendingPathComponent:@"key_up.png"]];
+    BOOL hasShiftUpper =
+        exists && [fm fileExistsAtPath:[iconsDir stringByAppendingPathComponent:
+                                                     @"key_up_upper.png"]];
+    NSString *line = [NSString
+        stringWithFormat:@"root=%@ icons=%@ exist=%d count=%tu key_q=%d "
+                         @"key_q_up=%d key_del=%d key_up=%d key_up_upper=%d",
+                         root, iconsDir, exists, count, hasQ, hasQUp, hasDel,
+                         hasShift, hasShiftUpper];
+    [lines addObject:line];
+  }
+
+  NSLog(@"[Keyboard] theme id=%@ name=%@ hasBg=%d\n%@", skinId, name,
+        (image != nil), [lines componentsJoinedByString:@"\n"]);
+#endif
+}
+
+- (void)kb_consumePendingShopSkin {
+  KBWeakSelf [KBSkinInstallBridge
+      consumePendingRequestFromBundle:NSBundle.mainBundle
+                           completion:^(BOOL success,
+                                        NSError *_Nullable error) {
+                             if (!success) {
+                               if (error) {
+                                 NSLog(@"[Keyboard] skin request failed: %@",
+                                       error);
+                                 [KBHUD
+                                     showInfo:
+                                         KBLocalized(
+                                             @"皮肤资源准备失败，请稍后再试")];
+                               }
+                               return;
+                             }
+                             [weakSelf kb_applyTheme];
+                             [KBHUD showInfo:KBLocalized(
+                                                 @"皮肤已更新，立即体验吧")];
+                           }];
+}
+
+- (void)kb_applyDefaultSkinIfNeeded {
+  NSDictionary *pending = [KBSkinInstallBridge pendingRequestPayload];
+  if (pending.count > 0) {
+    return;
+  }
+
+  NSString *currentId = [KBSkinManager shared].current.skinId ?: @"";
+  BOOL isDefault =
+      (currentId.length == 0 || [currentId isEqualToString:@"default"]);
+  BOOL isLightDefault = [currentId isEqualToString:kKBDefaultSkinIdLight];
+  BOOL isDarkDefault = [currentId isEqualToString:kKBDefaultSkinIdDark];
+  if (!isDefault && !isLightDefault && !isDarkDefault) {
+    // 用户已应用自定义皮肤：不随深色模式切换默认皮肤
+    return;
+  }
+  NSString *targetId = [self kb_defaultSkinIdForCurrentStyle];
+  NSString *targetZip = [self kb_defaultSkinZipNameForCurrentStyle];
+  if (currentId.length > 0 && [currentId isEqualToString:targetId]) {
+    return;
+  }
+
+  NSError *applyError = nil;
+  if ([KBSkinInstallBridge applyInstalledSkinWithId:targetId error:&applyError]) {
+    return;
+  }
+
+  [KBSkinInstallBridge publishBundleSkinRequestWithId:targetId
+                                                 name:targetId
+                                              zipName:targetZip
+                                       iconShortNames:nil];
+  [KBSkinInstallBridge
+      consumePendingRequestFromBundle:NSBundle.mainBundle
+                           completion:^(__unused BOOL success,
+                                        __unused NSError *_Nullable error) {
+                             // 已通过通知触发主题刷新，这里无需额外处理
+                           }];
+}
+
+@end

CustomKeyboard/KeyboardViewControllerHelp/KeyboardViewController+UI.m

@@ -0,0 +1,151 @@
+//
+//  KeyboardViewController+UI.m
+//  CustomKeyboard
+//
+//  Created by Codex on 2026/02/22.
+//
+
+#import "KeyboardViewController+Private.h"
+
+#import "KBChatMessage.h"
+#import "KBChatPanelView.h"
+#import "KBFunctionView.h"
+#import "KBKeyBoardMainView.h"
+#import "KBKeyboardSubscriptionView.h"
+#import "KBSettingView.h"
+#import "Masonry.h"
+
+@implementation KeyboardViewController (UI)
+
+- (void)setupUI {
+  self.view.translatesAutoresizingMaskIntoConstraints = NO;
+
+  // 按“短边”宽度等比缩放，横屏保持竖屏布局比例
+  CGFloat portraitWidth = [self kb_portraitWidth];
+  CGFloat keyboardHeight = [self kb_keyboardHeightForWidth:portraitWidth];
+  CGFloat keyboardBaseHeight = [self kb_keyboardBaseHeightForWidth:portraitWidth];
+  CGFloat screenWidth = CGRectGetWidth([UIScreen mainScreen].bounds);
+
+  // FIX: iOS 26 键盘闪烁问题
+  // iOS 26 在键盘滑入动画开始前，会对 self.view 做一次离屏预渲染快照（非实时 view），
+  // 该快照会短暂显示在屏幕中间。如果此时 view 已有完整高度和内容，用户就会看到
+  // 键盘 UI 在屏幕中间闪现一帧，然后键盘才从底部正常滑入。
+  // 解决方案：初始高度设为 0，让系统快照时无内容可渲染；
+  // 在 viewWillAppear: 中恢复正确高度，此时系统已准备好滑入动画。
+  // （iOS 18 及更早版本无此预渲染机制，不受影响）
+  NSLayoutConstraint *h = [self.view.heightAnchor constraintEqualToConstant:0];
+  NSLayoutConstraint *w =
+      [self.view.widthAnchor constraintEqualToConstant:screenWidth];
+  self.kb_heightConstraint = h;
+  self.kb_widthConstraint = w;
+
+  h.priority = UILayoutPriorityRequired;
+  w.priority = UILayoutPriorityRequired;
+  [NSLayoutConstraint activateConstraints:@[ h, w ]];
+  // 关闭 UIInputView 自适应（某些系统版本会尝试放大为全屏高度导致冲突）
+  if ([self.view isKindOfClass:[UIInputView class]]) {
+    UIInputView *iv = (UIInputView *)self.view;
+    if ([iv respondsToSelector:@selector(setAllowsSelfSizing:)]) {
+      iv.allowsSelfSizing = NO;
+    }
+  }
+  // 内容容器：横屏时保持竖屏宽度，居中显示
+  [self.view addSubview:self.contentView];
+  [self.contentView mas_makeConstraints:^(MASConstraintMaker *make) {
+    make.centerX.equalTo(self.view);
+    make.bottom.equalTo(self.view);
+    self.contentWidthConstraint = make.width.mas_equalTo(portraitWidth);
+    self.contentHeightConstraint = make.height.mas_equalTo(keyboardHeight);
+  }];
+
+  // 背景图铺底（仅在内容容器内）
+  [self.contentView addSubview:self.bgImageView];
+  [self.bgImageView mas_makeConstraints:^(MASConstraintMaker *make) {
+    make.edges.equalTo(self.contentView);
+  }];
+
+  [self.contentView addSubview:self.keyBoardMainView];
+  [self.keyBoardMainView mas_makeConstraints:^(MASConstraintMaker *make) {
+    make.left.right.equalTo(self.contentView);
+    make.bottom.equalTo(self.contentView);
+    self.keyBoardMainHeightConstraint =
+        make.height.mas_equalTo(keyboardBaseHeight);
+  }];
+
+  // 初始隐藏，避免布局完成前闪烁
+  self.contentView.hidden = YES;
+}
+
+#pragma mark - Lazy
+
+- (nullable KBFunctionView *)kb_functionViewIfCreated {
+  return _functionView;
+}
+
+- (UIView *)contentView {
+  if (!_contentView) {
+    _contentView = [[UIView alloc] init];
+    _contentView.backgroundColor = [UIColor clearColor];
+  }
+  return _contentView;
+}
+
+- (UIImageView *)bgImageView {
+  if (!_bgImageView) {
+    _bgImageView = [[UIImageView alloc] init];
+    _bgImageView.contentMode = UIViewContentModeScaleAspectFill;
+    _bgImageView.clipsToBounds = YES;
+  }
+  return _bgImageView;
+}
+
+- (KBKeyBoardMainView *)keyBoardMainView {
+  if (!_keyBoardMainView) {
+    _keyBoardMainView = [[KBKeyBoardMainView alloc] init];
+    _keyBoardMainView.delegate = self;
+  }
+  return _keyBoardMainView;
+}
+
+- (KBFunctionView *)functionView {
+  if (!_functionView) {
+    _functionView = [[KBFunctionView alloc] init];
+    _functionView.delegate = self; // 监听功能面板顶部Bar点击
+  }
+  return _functionView;
+}
+
+- (KBSettingView *)settingView {
+  if (!_settingView) {
+    _settingView = [[KBSettingView alloc] init];
+  }
+  return _settingView;
+}
+
+- (KBChatPanelView *)chatPanelView {
+  if (!_chatPanelView) {
+    NSLog(@"[Keyboard] ⚠️ chatPanelView 被创建！");
+    _chatPanelView = [[KBChatPanelView alloc] init];
+    _chatPanelView.delegate = self;
+  }
+  return _chatPanelView;
+}
+
+- (NSMutableArray<KBChatMessage *> *)chatMessages {
+  if (!_chatMessages) {
+    _chatMessages = [NSMutableArray array];
+  }
+  return _chatMessages;
+}
+
+- (KBKeyboardSubscriptionView *)subscriptionView {
+  if (!_subscriptionView) {
+    _subscriptionView = [[KBKeyboardSubscriptionView alloc] init];
+    _subscriptionView.delegate = self;
+    _subscriptionView.hidden = YES;
+    _subscriptionView.alpha = 0.0;
+  }
+  return _subscriptionView;
+}
+
+@end

CustomKeyboard/Manager/KBEmojiDataProvider.h

@@ -0,0 +1,46 @@
+//
+//  KBEmojiDataProvider.h
+//  CustomKeyboard
+//
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+FOUNDATION_EXPORT NSString * const KBEmojiRecentsDidChangeNotification;
+
+@class KBEmojiCategory, KBEmojiItem;
+
+@interface KBEmojiItem : NSObject <NSCopying>
+@property (nonatomic, copy, readonly) NSString *value;
+@property (nonatomic, copy, readonly) NSString *name;
+- (instancetype)initWithValue:(NSString *)value name:(NSString *)name;
+@end
+
+@interface KBEmojiCategory : NSObject
+@property (nonatomic, copy, readonly) NSString *identifier;
+@property (nonatomic, copy, readonly) NSString *displayTitle;
+@property (nonatomic, copy, readonly) NSString *iconSymbol;
+@property (nonatomic, assign, readonly, getter=isDynamic) BOOL dynamic;
+@property (nonatomic, copy, readonly) NSArray<KBEmojiItem *> *items;
+@end
+
+@interface KBEmojiDataProvider : NSObject
+
++ (instancetype)shared;
+
+/// 所有分类（按系统顺序），包含“常用”。
+@property (nonatomic, copy, readonly) NSArray<KBEmojiCategory *> *categories;
+
+/// 记录一次 emoji 选择，并刷新“常用”分类。
+- (void)recordEmojiSelection:(NSString *)emoji;
+
+/// 重新加载 JSON（若首次调用）。
+- (void)reloadIfNeeded;
+
+/// 更新当前语言对应的分类标题。
+- (void)refreshLocalizedTitles;
+
+@end
+
+NS_ASSUME_NONNULL_END

CustomKeyboard/Manager/KBEmojiDataProvider.m

@@ -0,0 +1,270 @@
+//
+//  KBEmojiDataProvider.m
+//  CustomKeyboard
+//
+
+#import "KBEmojiDataProvider.h"
+#import "KBLocalizationManager.h"
+#import "KBConfig.h"
+
+NSString * const KBEmojiRecentsDidChangeNotification = @"KBEmojiRecentsDidChangeNotification";
+
+static NSString * const kKBEmojiJSONFileName = @"emoji_categories";
+static NSString * const kKBEmojiRecentsStoreKey = @"KBEmojiRecentEmojis";
+static NSString * const kKBEmojiRecentsCategoryId = @"recents";
+static const NSUInteger kKBEmojiRecentsLimit = 32;
+
+#pragma mark - Model Implementations
+
+@interface KBEmojiItem ()
+@property (nonatomic, copy, readwrite) NSString *value;
+@property (nonatomic, copy, readwrite) NSString *name;
+@end
+
+@implementation KBEmojiItem
+
+- (instancetype)initWithValue:(NSString *)value name:(NSString *)name {
+    if (self = [super init]) {
+        _value = [value copy];
+        _name = [name copy];
+    }
+    return self;
+}
+
+- (id)copyWithZone:(NSZone *)zone {
+    KBEmojiItem *item = [[[self class] allocWithZone:zone] initWithValue:self.value name:self.name];
+    return item;
+}
+
+@end
+
+@interface KBEmojiCategory ()
+@property (nonatomic, copy, readwrite) NSString *identifier;
+@property (nonatomic, copy) NSDictionary<NSString *, NSString *> *titleMap;
+@property (nonatomic, copy, readwrite) NSString *displayTitle;
+@property (nonatomic, copy, readwrite) NSString *iconSymbol;
+@property (nonatomic, assign, readwrite, getter=isDynamic) BOOL dynamic;
+@property (nonatomic, copy, readwrite) NSArray<KBEmojiItem *> *items;
+@end
+
+@implementation KBEmojiCategory
+
+- (void)refreshDisplayTitleForLanguage:(NSString *)lang {
+    if (lang.length == 0) {
+        lang = KBLanguageCodeEnglish;
+    }
+    NSString *title = self.titleMap[lang];
+    if (title.length == 0) {
+        if ([lang.lowercaseString hasPrefix:@"zh"]) {
+            title = self.titleMap[@"zh-Hans"] ?: self.titleMap[@"zh-hans"];
+        }
+    }
+    if (title.length == 0) {
+        title = self.titleMap[@"en"];
+    }
+    if (title.length == 0) {
+        title = self.titleMap.allValues.firstObject;
+    }
+    self.displayTitle = title ?: @"";
+}
+
+@end
+
+#pragma mark - Data Provider
+
+@interface KBEmojiDataProvider ()
+@property (nonatomic, copy) NSArray<KBEmojiCategory *> *categoriesInternal;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, KBEmojiItem *> *itemLookup;
+@property (nonatomic, strong) NSMutableOrderedSet<NSString *> *recentValues;
+@end
+
+@implementation KBEmojiDataProvider
+
++ (instancetype)shared {
+    static KBEmojiDataProvider *m;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        m = [KBEmojiDataProvider new];
+        [[NSNotificationCenter defaultCenter] addObserver:m
+                                                 selector:@selector(onLocalizationChanged:)
+                                                     name:KBLocalizationDidChangeNotification
+                                                   object:nil];
+    });
+    return m;
+}
+
+- (void)dealloc {
+    [[NSNotificationCenter defaultCenter] removeObserver:self];
+}
+
+- (NSArray<KBEmojiCategory *> *)categories {
+    [self reloadIfNeeded];
+    return self.categoriesInternal ?: @[];
+}
+
+- (void)reloadIfNeeded {
+    if (self.categoriesInternal.count > 0) { return; }
+    [self loadEmojiJSON];
+    [self refreshLocalizedTitles];
+    [self loadRecentsFromStore];
+    [self rebuildRecentsCategory];
+}
+
+- (void)loadEmojiJSON {
+    NSString *path = [[NSBundle mainBundle] pathForResource:kKBEmojiJSONFileName ofType:@"json"];
+    if (path.length == 0) {
+        return;
+    }
+    NSData *data = [NSData dataWithContentsOfFile:path];
+    if (data.length == 0) { return; }
+
+    NSError *err = nil;
+    NSDictionary *root = [NSJSONSerialization JSONObjectWithData:data options:0 error:&err];
+    if (!root || err) {
+        NSLog(@"[Emoji] failed to parse json: %@", err);
+        return;
+    }
+    NSArray *catArray = root[@"categories"];
+    if (![catArray isKindOfClass:NSArray.class]) {
+        return;
+    }
+
+    NSMutableArray<KBEmojiCategory *> *tmpCats = [NSMutableArray arrayWithCapacity:catArray.count];
+    self.itemLookup = [NSMutableDictionary dictionary];
+
+    for (NSDictionary *catDict in catArray) {
+        if (![catDict isKindOfClass:NSDictionary.class]) continue;
+        KBEmojiCategory *category = [KBEmojiCategory new];
+        category.identifier = catDict[@"id"] ?: @"";
+        NSDictionary *titleMap = catDict[@"title"];
+        if ([titleMap isKindOfClass:NSDictionary.class]) {
+            category.titleMap = titleMap;
+        } else {
+            category.titleMap = @{};
+        }
+        NSString *iconKey = catDict[@"icon"];
+        category.iconSymbol = [self symbolForIconKey:iconKey];
+        NSString *type = catDict[@"type"];
+        category.dynamic = [type.lowercaseString isEqualToString:@"dynamic"];
+
+        NSArray *emojiArray = catDict[@"emojis"];
+        NSMutableArray<KBEmojiItem *> *items = [NSMutableArray arrayWithCapacity:[emojiArray count]];
+        if ([emojiArray isKindOfClass:NSArray.class]) {
+            for (NSDictionary *emojiDict in emojiArray) {
+                if (![emojiDict isKindOfClass:NSDictionary.class]) continue;
+                NSString *value = emojiDict[@"value"];
+                if (value.length == 0) continue;
+                NSString *name = emojiDict[@"name"] ?: @"";
+                KBEmojiItem *item = [[KBEmojiItem alloc] initWithValue:value name:name];
+                [items addObject:item];
+                if (value.length > 0) {
+                    self.itemLookup[value] = item;
+                }
+            }
+        }
+        category.items = items.copy;
+        [tmpCats addObject:category];
+    }
+    self.categoriesInternal = tmpCats.copy;
+}
+
+- (NSString *)symbolForIconKey:(NSString *)key {
+    static NSDictionary<NSString *, NSString *> *map;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        map = @{
+            @"emoji_tab_recent": @"🕘",
+            @"emoji_tab_people": @"😊",
+            @"emoji_tab_nature": @"🌿",
+            @"emoji_tab_food": @"🍔",
+            @"emoji_tab_activity": @"🏀",
+            @"emoji_tab_travel": @"✈️",
+            @"emoji_tab_objects": @"💡",
+            @"emoji_tab_symbols": @"♾",
+            @"emoji_tab_flags": @"🏳️"
+        };
+    });
+    NSString *symbol = map[key];
+    return symbol.length ? symbol : @"●";
+}
+
+- (void)refreshLocalizedTitles {
+    NSString *lang = [KBLocalizationManager shared].currentLanguageCode ?: KBLanguageCodeEnglish;
+    for (KBEmojiCategory *cat in self.categoriesInternal) {
+        [cat refreshDisplayTitleForLanguage:lang];
+    }
+}
+
+- (void)onLocalizationChanged:(__unused NSNotification *)note {
+    [self refreshLocalizedTitles];
+    [[NSNotificationCenter defaultCenter] postNotificationName:KBEmojiRecentsDidChangeNotification object:nil];
+}
+
+- (void)recordEmojiSelection:(NSString *)emoji {
+    if (emoji.length == 0) return;
+    [self reloadIfNeeded];
+    if (!self.recentValues) {
+        self.recentValues = [NSMutableOrderedSet orderedSet];
+    }
+    [self.recentValues removeObject:emoji];
+    [self.recentValues insertObject:emoji atIndex:0];
+    while (self.recentValues.count > kKBEmojiRecentsLimit) {
+        [self.recentValues removeObjectAtIndex:self.recentValues.count - 1];
+    }
+    [self saveRecentsToStore];
+    [self rebuildRecentsCategory];
+    [[NSNotificationCenter defaultCenter] postNotificationName:KBEmojiRecentsDidChangeNotification object:nil];
+}
+
+- (void)loadRecentsFromStore {
+    NSUserDefaults *defs = [[NSUserDefaults alloc] initWithSuiteName:AppGroup];
+    if (!defs) { defs = NSUserDefaults.standardUserDefaults; }
+    NSArray *stored = [defs objectForKey:kKBEmojiRecentsStoreKey];
+    NSMutableOrderedSet *set = [NSMutableOrderedSet orderedSet];
+    if ([stored isKindOfClass:NSArray.class]) {
+        for (id obj in stored) {
+            if (![obj isKindOfClass:NSString.class]) continue;
+            NSString *str = (NSString *)obj;
+            if (str.length == 0) continue;
+            [set addObject:str];
+            if (set.count >= kKBEmojiRecentsLimit) break;
+        }
+    }
+    self.recentValues = set;
+}
+
+- (void)saveRecentsToStore {
+    if (!self.recentValues) return;
+    NSArray *arr = self.recentValues.array;
+    NSUserDefaults *defs = [[NSUserDefaults alloc] initWithSuiteName:AppGroup];
+    if (!defs) { defs = NSUserDefaults.standardUserDefaults; }
+    [defs setObject:arr forKey:kKBEmojiRecentsStoreKey];
+    [defs synchronize];
+}
+
+- (void)rebuildRecentsCategory {
+    KBEmojiCategory *recent = [self categoryForIdentifier:kKBEmojiRecentsCategoryId];
+    if (!recent) return;
+    NSArray<NSString *> *values = self.recentValues.array ?: @[];
+    NSMutableArray<KBEmojiItem *> *items = [NSMutableArray arrayWithCapacity:values.count];
+    for (NSString *value in values) {
+        KBEmojiItem *item = self.itemLookup[value];
+        if (!item) {
+            item = [[KBEmojiItem alloc] initWithValue:value name:@""];
+        }
+        [items addObject:item];
+    }
+    recent.items = items.copy;
+}
+
+- (KBEmojiCategory *)categoryForIdentifier:(NSString *)identifier {
+    if (identifier.length == 0) return nil;
+    for (KBEmojiCategory *cat in self.categoriesInternal) {
+        if ([cat.identifier isEqualToString:identifier]) {
+            return cat;
+        }
+    }
+    return nil;
+}
+
+@end

CustomKeyboard/Manager/KBSuggestionEngine.h

@@ -0,0 +1,23 @@
+//
+//  KBSuggestionEngine.h
+//  CustomKeyboard
+//
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Simple local suggestion engine (prefix match + lightweight ranking).
+@interface KBSuggestionEngine : NSObject
+
++ (instancetype)shared;
+
+/// Returns suggestions for prefix (lowercase expected), limited by count.
+- (NSArray<NSString *> *)suggestionsForPrefix:(NSString *)prefix limit:(NSUInteger)limit;
+
+/// Record a selection to slightly boost ranking next time.
+- (void)recordSelection:(NSString *)word;
+
+@end
+
+NS_ASSUME_NONNULL_END

CustomKeyboard/Manager/KBSuggestionEngine.m

@@ -0,0 +1,167 @@
+//
+//  KBSuggestionEngine.m
+//  CustomKeyboard
+//
+
+#import "KBSuggestionEngine.h"
+#import "KBConfig.h"
+
+@interface KBSuggestionEngine ()
+@property (nonatomic, copy) NSArray<NSString *> *words;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, NSNumber *> *selectionCounts;
+@property (nonatomic, strong) NSSet<NSString *> *priorityWords;
+@end
+
+@implementation KBSuggestionEngine
+
++ (instancetype)shared {
+    static KBSuggestionEngine *engine;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        engine = [[KBSuggestionEngine alloc] init];
+    });
+    return engine;
+}
+
+- (instancetype)init {
+    if (self = [super init]) {
+        _selectionCounts = [NSMutableDictionary dictionary];
+        NSArray<NSString *> *defaults = [self.class kb_defaultWords];
+        _priorityWords = [NSSet setWithArray:defaults];
+        _words = [self kb_loadWords];
+    }
+    return self;
+}
+
+- (NSArray<NSString *> *)suggestionsForPrefix:(NSString *)prefix limit:(NSUInteger)limit {
+    if (prefix.length == 0 || limit == 0) { return @[]; }
+    NSString *lower = prefix.lowercaseString;
+    NSMutableArray<NSString *> *matches = [NSMutableArray array];
+
+    for (NSString *word in self.words) {
+        if ([word hasPrefix:lower]) {
+            [matches addObject:word];
+            if (matches.count >= limit * 3) {
+                // Avoid scanning too many matches for long lists.
+                break;
+            }
+        }
+    }
+
+    if (matches.count == 0) { return @[]; }
+
+    [matches sortUsingComparator:^NSComparisonResult(NSString *a, NSString *b) {
+        NSInteger ca = self.selectionCounts[a].integerValue;
+        NSInteger cb = self.selectionCounts[b].integerValue;
+        if (ca != cb) {
+            return (cb > ca) ? NSOrderedAscending : NSOrderedDescending;
+        }
+        BOOL pa = [self.priorityWords containsObject:a];
+        BOOL pb = [self.priorityWords containsObject:b];
+        if (pa != pb) {
+            return pa ? NSOrderedAscending : NSOrderedDescending;
+        }
+        return [a compare:b];
+    }];
+
+    if (matches.count > limit) {
+        return [matches subarrayWithRange:NSMakeRange(0, limit)];
+    }
+    return matches.copy;
+}
+
+- (void)recordSelection:(NSString *)word {
+    if (word.length == 0) { return; }
+    NSString *key = word.lowercaseString;
+    NSInteger count = self.selectionCounts[key].integerValue + 1;
+    self.selectionCounts[key] = @(count);
+}
+
+#pragma mark - Defaults
+
+- (NSArray<NSString *> *)kb_loadWords {
+    NSMutableOrderedSet<NSString *> *set = [[NSMutableOrderedSet alloc] init];
+    [set addObjectsFromArray:[self.class kb_defaultWords]];
+
+    NSArray<NSString *> *paths = [self kb_wordListPaths];
+    for (NSString *path in paths) {
+        if (path.length == 0) { continue; }
+        NSString *content = [NSString stringWithContentsOfFile:path encoding:NSUTF8StringEncoding error:nil];
+        if (content.length == 0) { continue; }
+        NSArray<NSString *> *lines = [content componentsSeparatedByCharactersInSet:[NSCharacterSet newlineCharacterSet]];
+        for (NSString *line in lines) {
+            NSString *word = [self kb_sanitizedWordFromLine:line];
+            if (word.length == 0) { continue; }
+            [set addObject:word];
+        }
+    }
+
+    NSArray<NSString *> *result = set.array ?: @[];
+    return result;
+}
+
+- (NSArray<NSString *> *)kb_wordListPaths {
+    NSMutableArray<NSString *> *paths = [NSMutableArray array];
+    // 1) App Group override (allows server-downloaded large list).
+    NSURL *containerURL = [[NSFileManager defaultManager] containerURLForSecurityApplicationGroupIdentifier:AppGroup];
+    if (containerURL.path.length > 0) {
+        NSString *groupPath = [[containerURL path] stringByAppendingPathComponent:@"kb_words.txt"];
+        [paths addObject:groupPath];
+    }
+    // 2) Bundle fallback.
+    NSString *bundlePath = [[NSBundle mainBundle] pathForResource:@"kb_words" ofType:@"txt"];
+    if (bundlePath.length > 0) {
+        [paths addObject:bundlePath];
+    }
+    return paths;
+}
+
+- (NSString *)kb_sanitizedWordFromLine:(NSString *)line {
+    NSString *trimmed = [[line stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]] lowercaseString];
+    if (trimmed.length == 0) { return @""; }
+    static NSCharacterSet *letters = nil;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        letters = [NSCharacterSet characterSetWithCharactersInString:@"abcdefghijklmnopqrstuvwxyz"];
+    });
+    for (NSUInteger i = 0; i < trimmed.length; i++) {
+        if (![letters characterIsMember:[trimmed characterAtIndex:i]]) {
+            return @"";
+        }
+    }
+    return trimmed;
+}
+
++ (NSArray<NSString *> *)kb_defaultWords {
+    return @[
+        @"a", @"an", @"and", @"are", @"as", @"at",
+        @"app", @"ap", @"apple", @"apply", @"april", @"application",
+        @"about", @"above", @"after", @"again", @"against", @"all",
+        @"am", @"among", @"amount", @"any", @"around",
+        @"be", @"because", @"been", @"before", @"being", @"below",
+        @"best", @"between", @"both", @"but", @"by",
+        @"can", @"could", @"come", @"common", @"case",
+        @"do", @"does", @"down", @"day",
+        @"each", @"early", @"end", @"even", @"every",
+        @"for", @"from", @"first", @"found", @"free",
+        @"get", @"good", @"great", @"go",
+        @"have", @"has", @"had", @"help", @"how",
+        @"in", @"is", @"it", @"if", @"into",
+        @"just", @"keep", @"kind", @"know",
+        @"like", @"look", @"long", @"last",
+        @"make", @"more", @"most", @"my",
+        @"new", @"no", @"not", @"now",
+        @"of", @"on", @"one", @"or", @"other", @"our", @"out",
+        @"people", @"place", @"please",
+        @"quick", @"quite",
+        @"right", @"read", @"real",
+        @"see", @"say", @"some", @"such", @"so",
+        @"the", @"to", @"this", @"that", @"them", @"then", @"there", @"they", @"these", @"time",
+        @"use", @"up", @"under",
+        @"very",
+        @"we", @"with", @"what", @"when", @"where", @"who", @"why", @"will", @"would",
+        @"you", @"your"
+    ];
+}
+
+@end

CustomKeyboard/Model/KBChatMessage.h

@@ -0,0 +1,49 @@
+//
+//  KBChatMessage.h
+//  CustomKeyboard
+//
+
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface KBChatMessage : NSObject
+
+@property (nonatomic, copy) NSString *text;
+@property (nonatomic, assign) BOOL outgoing;
+@property (nonatomic, copy, nullable) NSString *audioFilePath;
+@property (nonatomic, copy, nullable) NSString *avatarURL;
+@property (nonatomic, copy, nullable) NSString *displayName;
+@property (nonatomic, strong, nullable) UIImage *avatarImage;
+
+/// 是否处于加载状态
+@property (nonatomic, assign) BOOL isLoading;
+/// 是否完成（用于打字机效果）
+@property (nonatomic, assign) BOOL isComplete;
+/// 是否需要打字机效果
+@property (nonatomic, assign) BOOL needsTypewriterEffect;
+/// 音频 ID（用于异步加载音频）
+@property (nonatomic, copy, nullable) NSString *audioId;
+/// 音频数据（缓存）
+@property (nonatomic, strong, nullable) NSData *audioData;
+/// 音频时长（秒）
+@property (nonatomic, assign) NSTimeInterval audioDuration;
+
++ (instancetype)messageWithText:(NSString *)text
+                        outgoing:(BOOL)outgoing
+                   audioFilePath:(nullable NSString *)audioFilePath;
+
+/// 创建用户消息
++ (instancetype)userMessageWithText:(NSString *)text;
+
+/// 创建 AI 消息（带 audioId）
++ (instancetype)assistantMessageWithText:(NSString *)text
+                                 audioId:(nullable NSString *)audioId;
+
+/// 创建加载中的 AI 消息
++ (instancetype)loadingAssistantMessage;
+
+@end
+
+NS_ASSUME_NONNULL_END

CustomKeyboard/Model/KBChatMessage.m

@@ -0,0 +1,55 @@
+//
+//  KBChatMessage.m
+//  CustomKeyboard
+//
+
+#import "KBChatMessage.h"
+
+@implementation KBChatMessage
+
++ (instancetype)messageWithText:(NSString *)text
+                        outgoing:(BOOL)outgoing
+                   audioFilePath:(NSString *)audioFilePath {
+    KBChatMessage *msg = [[KBChatMessage alloc] init];
+    msg.text = text ?: @"";
+    msg.outgoing = outgoing;
+    msg.audioFilePath = audioFilePath;
+    msg.isComplete = YES;
+    msg.isLoading = NO;
+    msg.needsTypewriterEffect = NO;
+    return msg;
+}
+
++ (instancetype)userMessageWithText:(NSString *)text {
+    KBChatMessage *msg = [[KBChatMessage alloc] init];
+    msg.text = text ?: @"";
+    msg.outgoing = YES;
+    msg.isComplete = YES;
+    msg.isLoading = NO;
+    msg.needsTypewriterEffect = NO;
+    return msg;
+}
+
++ (instancetype)assistantMessageWithText:(NSString *)text
+                                 audioId:(NSString *)audioId {
+    KBChatMessage *msg = [[KBChatMessage alloc] init];
+    msg.text = text ?: @"";
+    msg.outgoing = NO;
+    msg.audioId = audioId;
+    msg.isComplete = NO;
+    msg.isLoading = NO;
+    msg.needsTypewriterEffect = YES;
+    return msg;
+}
+
++ (instancetype)loadingAssistantMessage {
+    KBChatMessage *msg = [[KBChatMessage alloc] init];
+    msg.text = @"";
+    msg.outgoing = NO;
+    msg.isComplete = NO;
+    msg.isLoading = YES;
+    msg.needsTypewriterEffect = NO;
+    return msg;
+}
+
+@end

CustomKeyboard/Model/KBKey.h

@@ -16,17 +16,35 @@ typedef NS_ENUM(NSInteger, KBKeyType) {
     KBKeyTypeSpace,           // 空格
     KBKeyTypeReturn,          // 回车/发送
     KBKeyTypeGlobe,           // 系统地球键
-    KBKeyTypeCustom,          // 自定义功能占位
+    KBKeyTypeCustom,          // 自定义功能占位（如 AI/Emoji）
     KBKeyTypeSymbolsToggle    // 数字面板内的“#+=/123”切换
 };
 
+FOUNDATION_EXPORT NSString * const KBKeyIdentifierEmojiPanel;
+
+/// 字母键的大小写变体标记（非字母键使用 KBKeyCaseVariantNone）
+typedef NS_ENUM(NSInteger, KBKeyCaseVariant) {
+    KBKeyCaseVariantNone  = 0,
+    KBKeyCaseVariantLower = 1,
+    KBKeyCaseVariantUpper = 2,
+};
+
 @interface KBKey : NSObject
 
 @property (nonatomic, assign) KBKeyType type;
 @property (nonatomic, copy) NSString *title;      // 显示标题
 @property (nonatomic, copy) NSString *output;     // 字符键插入的文本
+/// 逻辑按键标识，用于皮肤映射（如 @"letter_q" @"space" @"backspace"）
+@property (nonatomic, copy, nullable) NSString *identifier;
+/// 字母键的大小写变体（便于皮肤为大小写准备不同图）
+@property (nonatomic, assign) KBKeyCaseVariant caseVariant;
 
 + (instancetype)keyWithTitle:(NSString *)title output:(NSString *)output;
 + (instancetype)keyWithTitle:(NSString *)title type:(KBKeyType)type;
+/// 通用构造方法：用于指定 identifier，便于皮肤做精细控制
++ (instancetype)keyWithIdentifier:(nullable NSString *)identifier
+                            title:(NSString *)title
+                           output:(NSString *)output
+                             type:(KBKeyType)type;
 
 @end

CustomKeyboard/Model/KBKey.m

@@ -5,6 +5,8 @@
 
 #import "KBKey.h"
 
+NSString * const KBKeyIdentifierEmojiPanel = @"emoji_panel";
+
 @implementation KBKey
 
 + (instancetype)keyWithTitle:(NSString *)title output:(NSString *)output {
@@ -12,6 +14,7 @@
     k.type = KBKeyTypeCharacter;
     k.title = title ?: @"";
     k.output = output ?: title ?: @"";
+    k.caseVariant = KBKeyCaseVariantNone;
     return k;
 }
 
@@ -20,8 +23,21 @@
     k.type = type;
     k.title = title ?: @"";
     k.output = @"";
+    k.caseVariant = KBKeyCaseVariantNone;
+    return k;
+}
+
++ (instancetype)keyWithIdentifier:(NSString *)identifier
+                            title:(NSString *)title
+                           output:(NSString *)output
+                             type:(KBKeyType)type {
+    KBKey *k = [[KBKey alloc] init];
+    k.type = type;
+    k.identifier = identifier;
+    k.title = title ?: @"";
+    k.output = output ?: @"";
+    k.caseVariant = KBKeyCaseVariantNone;
     return k;
 }
 
 @end
-

CustomKeyboard/Model/KBKeyboardLayoutConfig.h

@@ -0,0 +1,96 @@
+//
+//  KBKeyboardLayoutConfig.h
+//  CustomKeyboard
+//
+//  键盘布局配置模型（由 JSON 驱动）
+//
+
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface KBKeyboardLayoutMetrics : NSObject
+@property (nonatomic, strong, nullable) NSNumber *rowSpacing;
+@property (nonatomic, strong, nullable) NSNumber *topInset;
+@property (nonatomic, strong, nullable) NSNumber *bottomInset;
+@property (nonatomic, strong, nullable) NSNumber *keyHeight;
+@property (nonatomic, strong, nullable) NSNumber *edgeInset;
+@property (nonatomic, strong, nullable) NSNumber *gap;
+@property (nonatomic, strong, nullable) NSNumber *letterWidth;
+@property (nonatomic, strong, nullable) NSNumber *controlWidth;
+@property (nonatomic, strong, nullable) NSNumber *sendWidth;
+@property (nonatomic, strong, nullable) NSNumber *symbolsWideWidth;
+@property (nonatomic, strong, nullable) NSNumber *symbolsSideWidth;
+@end
+
+@interface KBKeyboardLayoutFonts : NSObject
+@property (nonatomic, strong, nullable) NSNumber *letter;
+@property (nonatomic, strong, nullable) NSNumber *digit;
+@property (nonatomic, strong, nullable) NSNumber *symbol;
+@property (nonatomic, strong, nullable) NSNumber *mode;
+@property (nonatomic, strong, nullable) NSNumber *space;
+@property (nonatomic, strong, nullable) NSNumber *send;
+@end
+
+@interface KBKeyboardKeyDef : NSObject
+@property (nonatomic, copy, nullable) NSString *type;
+@property (nonatomic, copy, nullable) NSString *title;
+@property (nonatomic, copy, nullable) NSString *selectedTitle;
+@property (nonatomic, copy, nullable) NSString *symbolName;
+@property (nonatomic, copy, nullable) NSString *selectedSymbolName;
+@property (nonatomic, copy, nullable) NSString *font;
+@property (nonatomic, copy, nullable) NSString *width;
+@property (nonatomic, strong, nullable) NSNumber *widthValue;
+@property (nonatomic, copy, nullable) NSString *backgroundColor;
+@end
+
+@interface KBKeyboardRowItem : NSObject
+@property (nonatomic, copy, nullable) NSString *itemId;
+@property (nonatomic, copy, nullable) NSString *width;
+@property (nonatomic, strong, nullable) NSNumber *widthValue;
++ (NSArray<KBKeyboardRowItem *> *)itemsFromRawArray:(NSArray *)raw;
+@end
+
+@interface KBKeyboardRowSegments : NSObject
+@property (nonatomic, strong, nullable) NSArray *left;
+@property (nonatomic, strong, nullable) NSArray *center;
+@property (nonatomic, strong, nullable) NSArray *right;
+- (NSArray<KBKeyboardRowItem *> *)leftItems;
+- (NSArray<KBKeyboardRowItem *> *)centerItems;
+- (NSArray<KBKeyboardRowItem *> *)rightItems;
+@end
+
+@interface KBKeyboardRowConfig : NSObject
+@property (nonatomic, strong, nullable) NSNumber *height;
+@property (nonatomic, strong, nullable) NSNumber *insetLeft;
+@property (nonatomic, strong, nullable) NSNumber *insetRight;
+@property (nonatomic, strong, nullable) NSNumber *gap;
+@property (nonatomic, copy, nullable) NSString *align;
+@property (nonatomic, strong, nullable) NSArray *items;
+@property (nonatomic, strong, nullable) KBKeyboardRowSegments *segments;
+- (NSArray<KBKeyboardRowItem *> *)resolvedItems;
+@end
+
+@interface KBKeyboardLayout : NSObject
+@property (nonatomic, strong, nullable) NSArray<KBKeyboardRowConfig *> *rows;
+@end
+
+@interface KBKeyboardLayoutConfig : NSObject
+@property (nonatomic, assign) CGFloat designWidth;
+@property (nonatomic, strong, nullable) KBKeyboardLayoutMetrics *metrics;
+@property (nonatomic, strong, nullable) KBKeyboardLayoutFonts *fonts;
+@property (nonatomic, copy, nullable) NSString *defaultKeyBackground;
+@property (nonatomic, strong, nullable) NSDictionary<NSString *, KBKeyboardKeyDef *> *keyDefs;
+@property (nonatomic, strong, nullable) NSDictionary<NSString *, KBKeyboardLayout *> *layouts;
+
++ (nullable instancetype)sharedConfig;
++ (nullable instancetype)configFromJSONData:(NSData *)data;
+- (CGFloat)scaledValue:(CGFloat)designValue;
+- (CGFloat)keyboardAreaDesignHeight;
+- (CGFloat)keyboardAreaScaledHeight;
+- (nullable KBKeyboardLayout *)layoutForName:(NSString *)name;
+- (nullable KBKeyboardKeyDef *)keyDefForIdentifier:(NSString *)identifier;
+@end
+
+NS_ASSUME_NONNULL_END

CustomKeyboard/Model/KBKeyboardLayoutConfig.m

@@ -0,0 +1,187 @@
+//
+//  KBKeyboardLayoutConfig.m
+//  CustomKeyboard
+//
+
+#import "KBKeyboardLayoutConfig.h"
+#import <MJExtension/MJExtension.h>
+#import "KBConfig.h"
+
+static NSString * const kKBKeyboardLayoutConfigFileName = @"kb_keyboard_layout_config";
+
+@implementation KBKeyboardLayoutMetrics
+@end
+
+@implementation KBKeyboardLayoutFonts
+@end
+
+@implementation KBKeyboardKeyDef
+@end
+
+@implementation KBKeyboardRowItem
+
++ (NSDictionary *)mj_replacedKeyFromPropertyName {
+    return @{ @"itemId": @"id" };
+}
+
++ (NSArray<KBKeyboardRowItem *> *)itemsFromRawArray:(NSArray *)raw {
+    if (![raw isKindOfClass:[NSArray class]] || raw.count == 0) {
+        return @[];
+    }
+    NSMutableArray<KBKeyboardRowItem *> *items = [NSMutableArray arrayWithCapacity:raw.count];
+    for (id obj in raw) {
+        if ([obj isKindOfClass:[NSString class]]) {
+            KBKeyboardRowItem *item = [KBKeyboardRowItem new];
+            item.itemId = (NSString *)obj;
+            [items addObject:item];
+            continue;
+        }
+        if ([obj isKindOfClass:[NSDictionary class]]) {
+            KBKeyboardRowItem *item = [KBKeyboardRowItem mj_objectWithKeyValues:obj];
+            if (item.itemId.length == 0) {
+                NSString *fallback = ((NSDictionary *)obj)[@"id"];
+                if ([fallback isKindOfClass:[NSString class]]) {
+                    item.itemId = fallback;
+                }
+            }
+            if (item.itemId.length > 0) {
+                [items addObject:item];
+            }
+        }
+    }
+    return items.copy;
+}
+
+@end
+
+@implementation KBKeyboardRowSegments
+
+- (NSArray<KBKeyboardRowItem *> *)leftItems {
+    return [KBKeyboardRowItem itemsFromRawArray:self.left ?: @[]];
+}
+
+- (NSArray<KBKeyboardRowItem *> *)centerItems {
+    return [KBKeyboardRowItem itemsFromRawArray:self.center ?: @[]];
+}
+
+- (NSArray<KBKeyboardRowItem *> *)rightItems {
+    return [KBKeyboardRowItem itemsFromRawArray:self.right ?: @[]];
+}
+
+@end
+
+@implementation KBKeyboardRowConfig
+
+- (NSArray<KBKeyboardRowItem *> *)resolvedItems {
+    return [KBKeyboardRowItem itemsFromRawArray:self.items ?: @[]];
+}
+
+@end
+
+@implementation KBKeyboardLayout
+
++ (NSDictionary *)mj_objectClassInArray {
+    return @{ @"rows": [KBKeyboardRowConfig class] };
+}
+
+@end
+
+@implementation KBKeyboardLayoutConfig
+
++ (instancetype)sharedConfig {
+    static KBKeyboardLayoutConfig *config = nil;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        NSString *path = [[NSBundle mainBundle] pathForResource:kKBKeyboardLayoutConfigFileName ofType:@"json"];
+        NSData *data = path.length ? [NSData dataWithContentsOfFile:path] : nil;
+        config = data ? [KBKeyboardLayoutConfig configFromJSONData:data] : nil;
+    });
+    return config;
+}
+
++ (instancetype)configFromJSONData:(NSData *)data {
+    if (data.length == 0) { return nil; }
+    NSError *error = nil;
+    id json = [NSJSONSerialization JSONObjectWithData:data options:0 error:&error];
+    if (error || ![json isKindOfClass:[NSDictionary class]]) {
+        return nil;
+    }
+    NSDictionary *dict = (NSDictionary *)json;
+    KBKeyboardLayoutConfig *config = [KBKeyboardLayoutConfig mj_objectWithKeyValues:dict];
+
+    NSDictionary *keyDefsRaw = dict[@"keyDefs"];
+    if ([keyDefsRaw isKindOfClass:[NSDictionary class]]) {
+        NSMutableDictionary<NSString *, KBKeyboardKeyDef *> *defs = [NSMutableDictionary dictionaryWithCapacity:keyDefsRaw.count];
+        [keyDefsRaw enumerateKeysAndObjectsUsingBlock:^(id key, id obj, BOOL *stop) {
+            if (![key isKindOfClass:[NSString class]] || ![obj isKindOfClass:[NSDictionary class]]) {
+                return;
+            }
+            KBKeyboardKeyDef *def = [KBKeyboardKeyDef mj_objectWithKeyValues:obj];
+            if (def) {
+                defs[key] = def;
+            }
+        }];
+        config.keyDefs = defs.copy;
+    }
+
+    NSDictionary *layoutsRaw = dict[@"layouts"];
+    if ([layoutsRaw isKindOfClass:[NSDictionary class]]) {
+        NSMutableDictionary<NSString *, KBKeyboardLayout *> *layouts = [NSMutableDictionary dictionaryWithCapacity:layoutsRaw.count];
+        [layoutsRaw enumerateKeysAndObjectsUsingBlock:^(id key, id obj, BOOL *stop) {
+            if (![key isKindOfClass:[NSString class]] || ![obj isKindOfClass:[NSDictionary class]]) {
+                return;
+            }
+            KBKeyboardLayout *layout = [KBKeyboardLayout mj_objectWithKeyValues:obj];
+            if (layout) {
+                layouts[key] = layout;
+            }
+        }];
+        config.layouts = layouts.copy;
+    }
+
+    return config;
+}
+
+- (CGFloat)scaledValue:(CGFloat)designValue {
+    CGFloat baseWidth = (self.designWidth > 0.0) ? self.designWidth : KB_DESIGN_WIDTH;
+    CGFloat scale = KBScreenWidth() / baseWidth;
+    return designValue * scale;
+}
+
+- (CGFloat)keyboardAreaDesignHeight {
+    KBKeyboardLayout *layout = [self layoutForName:@"letters"] ?: self.layouts.allValues.firstObject;
+    NSUInteger rowCount = layout.rows.count;
+    if (rowCount == 0) { return 0.0; }
+
+    CGFloat rowSpacing = self.metrics.rowSpacing.doubleValue;
+    CGFloat topInset = self.metrics.topInset.doubleValue;
+    CGFloat bottomInset = self.metrics.bottomInset.doubleValue;
+
+    CGFloat total = topInset + bottomInset + rowSpacing * (rowCount - 1);
+    for (KBKeyboardRowConfig *row in layout.rows) {
+        CGFloat height = row.height.doubleValue;
+        if (height <= 0.0) {
+            height = self.metrics.keyHeight.doubleValue;
+        }
+        if (height <= 0.0) { height = 40.0; }
+        total += height;
+    }
+    return total;
+}
+
+- (CGFloat)keyboardAreaScaledHeight {
+    CGFloat designHeight = [self keyboardAreaDesignHeight];
+    return designHeight > 0.0 ? [self scaledValue:designHeight] : 0.0;
+}
+
+- (KBKeyboardLayout *)layoutForName:(NSString *)name {
+    if (name.length == 0) { return nil; }
+    return self.layouts[name];
+}
+
+- (KBKeyboardKeyDef *)keyDefForIdentifier:(NSString *)identifier {
+    if (identifier.length == 0) { return nil; }
+    return self.keyDefs[identifier];
+}
+
+@end

CustomKeyboard/Model/KBKeyboardSubscriptionProduct.h

@@ -0,0 +1,43 @@
+//
+//  KBKeyboardSubscriptionProduct.h
+//  CustomKeyboard
+//
+//  订阅商品模型（键盘扩展专用），用于展示与主 App 相同的订阅列表。
+//
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface KBKeyboardSubscriptionProduct : NSObject
+/// 主键 id
+@property (nonatomic, assign) NSInteger identifier;
+/// Apple 商品编号
+@property (nonatomic, copy, nullable) NSString *productId;
+/// 商品名称，如 Monthly
+@property (nonatomic, copy, nullable) NSString *name;
+/// 单位，如 Subscription
+@property (nonatomic, copy, nullable) NSString *unit;
+/// 商品描述
+@property (nonatomic, copy, nullable) NSString *productDescription;
+/// 货币符号
+@property (nonatomic, copy, nullable) NSString *currency;
+/// 现价
+@property (nonatomic, assign) double price;
+/// 原价（如接口未返回，则回退为 price 的 1.25 倍）
+@property (nonatomic, assign) double originPrice;
+/// 有效期数值
+@property (nonatomic, assign) NSInteger durationValue;
+/// 有效期单位
+@property (nonatomic, copy, nullable) NSString *durationUnit;
+
+/// 标题（描述 > name+unit > name > unit）
+- (NSString *)displayTitle;
+/// 当前价格文本
+- (NSString *)priceDisplayText;
+/// 划线价文本
+- (nullable NSString *)strikePriceDisplayText;
+
+@end
+
+NS_ASSUME_NONNULL_END

CustomKeyboard/Model/KBKeyboardSubscriptionProduct.m

@@ -0,0 +1,55 @@
+//
+//  KBKeyboardSubscriptionProduct.m
+//  CustomKeyboard
+//
+
+#import "KBKeyboardSubscriptionProduct.h"
+#import <MJExtension/MJExtension.h>
+#import "KBLocalizationManager.h"
+
+@implementation KBKeyboardSubscriptionProduct
+
++ (NSDictionary *)mj_replacedKeyFromPropertyName {
+    return @{
+        @"identifier": @"id",
+        @"productDescription": @"description",
+    };
+}
+
+- (NSString *)displayTitle {
+    if (self.productDescription.length > 0) {
+        return self.productDescription;
+    }
+    NSString *name = self.name ?: @"";
+    NSString *unit = self.unit ?: @"";
+    if (name.length && unit.length) {
+        return [NSString stringWithFormat:@"%@ %@", name, unit];
+    }
+    if (name.length) { return name; }
+    if (unit.length) { return unit; }
+    if (self.durationValue > 0 && self.durationUnit.length > 0) {
+        return [NSString stringWithFormat:@"%ld %@", (long)self.durationValue, self.durationUnit];
+    }
+    return KBLocalized(@"Subscription");
+}
+
+- (NSString *)priceDisplayText {
+    double priceValue = self.price;
+    if (priceValue <= 0) {
+        return @"$0.00";
+    }
+    NSString *currency = self.currency.length ? self.currency : @"$";
+    return [NSString stringWithFormat:@"%@%.2f", currency, priceValue];
+}
+
+- (nullable NSString *)strikePriceDisplayText {
+    double rawValue = self.originPrice;
+    if (rawValue <= 0 && self.price > 0) {
+        rawValue = self.price * 1.25;
+    }
+    if (rawValue <= 0) { return nil; }
+    NSString *currency = self.currency.length ? self.currency : @"$";
+    return [NSString stringWithFormat:@"%@%.2f", currency, rawValue];
+}
+
+@end

CustomKeyboard/Network/KBNetworkManager.h

@@ -19,8 +19,15 @@ typedef NS_ERROR_ENUM(KBNetworkErrorDomain, KBNetworkError) {
     KBNetworkErrorDecodeFailed = 4,
 };
 
-/// 简单的 JSON 回调：json 为 NSDictionary/NSArray 或者在非 JSON 情况下返回 NSData
-typedef void(^KBNetworkCompletion)(id _Nullable jsonOrData, NSURLResponse * _Nullable response, NSError * _Nullable error);
+/// JSON 回调（扩展侧目前很少使用 JSON，可按需扩展）
+typedef void(^KBNetworkCompletion)(NSDictionary *_Nullable json,
+                                   NSURLResponse * _Nullable response,
+                                   NSError * _Nullable error);
+
+/// 二进制回调：用于下载 zip、图片等原始数据
+typedef void(^KBNetworkDataCompletion)(NSData *_Nullable data,
+                                       NSURLResponse *_Nullable response,
+                                       NSError *_Nullable error);
 
 @interface KBNetworkManager : NSObject
 
@@ -45,13 +52,27 @@ typedef void(^KBNetworkCompletion)(id _Nullable jsonOrData, NSURLResponse * _Nul
                                 headers:(nullable NSDictionary<NSString *, NSString *> *)headers
                               completion:(KBNetworkCompletion)completion;
 
+/// GET 原始二进制数据（不做 JSON 解析）
+- (nullable NSURLSessionDataTask *)GETData:(NSString *)path
+                                 parameters:(nullable NSDictionary *)parameters
+                                    headers:(nullable NSDictionary<NSString *, NSString *> *)headers
+                                  completion:(KBNetworkDataCompletion)completion;
+
 /// POST JSON 请求，jsonBody 会以 application/json 发送
 - (nullable NSURLSessionDataTask *)POST:(NSString *)path
                                jsonBody:(nullable id)jsonBody
                                 headers:(nullable NSDictionary<NSString *, NSString *> *)headers
                               completion:(KBNetworkCompletion)completion;
 
+/// POST multipart 上传文件（常用于语音/图片等文件）
+- (nullable NSURLSessionDataTask *)uploadFile:(NSString *)path
+                                      fileURL:(NSURL *)fileURL
+                                         name:(NSString *)name
+                                     mimeType:(NSString *)mimeType
+                                   parameters:(nullable NSDictionary *)parameters
+                                      headers:(nullable NSDictionary<NSString *, NSString *> *)headers
+                                   completion:(KBNetworkCompletion)completion;
+
 @end
 
 NS_ASSUME_NONNULL_END
-

CustomKeyboard/Network/KBNetworkManager.m

@@ -6,7 +6,8 @@
 #import "KBNetworkManager.h"
 #import "AFNetworking.h"
 #import "KBAuthManager.h"
-
+//#import "KBUserSessionManager.h"
+#import "KBSignUtils.h"
 NSErrorDomain const KBNetworkErrorDomain = @"com.company.keyboard.network";
 
 @interface KBNetworkManager ()
@@ -26,37 +27,59 @@ NSErrorDomain const KBNetworkErrorDomain = @"com.company.keyboard.network";
     if (self = [super init]) {
         _enabled = NO; // 键盘扩展默认无网络能力，需外部显式开启
         _timeout = 10.0;
-        _defaultHeaders = @{ @"Accept": @"application/json" };
+        // 默认请求头：Accept 任意类型 + 使用项目多语言管理器设置 Accept-Language
+        NSString *lang = [KBLocalizationManager shared].currentLanguageCode ?: KBLanguageCodeEnglish;
+//        NSString *token = [KBUserSessionManager shared].accessToken ? [KBUserSessionManager shared].accessToken : @"";
+        _defaultHeaders = @{
+            @"Accept": @"*/*",
+            @"Accept-Language": lang
+        };
         // 设置基础域名，路径可相对该地址拼接
         _baseURL = [NSURL URLWithString:KB_BASE_URL];
     }
     return self;
 }
 
+- (void)getSignWithParare:(NSDictionary *)bodyParams{
+    NSDictionary<NSString *, NSString *> *signHeaders = [KBSignUtils signHeadersWithBodyParams:bodyParams];
+    NSMutableDictionary<NSString *, NSString *> *headers =
+    [self.defaultHeaders mutableCopy] ?: [NSMutableDictionary dictionary];
+    [headers addEntriesFromDictionary:signHeaders ?: @{}];
+    self.defaultHeaders = headers;
+}
+
 #pragma mark - Public
 
 - (NSURLSessionDataTask *)GET:(NSString *)path
                      parameters:(NSDictionary *)parameters
                         headers:(NSDictionary<NSString *,NSString *> *)headers
                       completion:(KBNetworkCompletion)completion {
+    [self getSignWithParare:parameters];
     if (![self ensureEnabled:completion]) return nil;
     NSString *urlString = [self buildURLStringWithPath:path];
     if (!urlString) { [self fail:KBNetworkErrorInvalidURL completion:completion]; return nil; }
     // 使用 AFHTTPRequestSerializer 生成带参数与头的请求
     AFHTTPRequestSerializer *serializer = [AFHTTPRequestSerializer serializer];
     serializer.timeoutInterval = self.timeout;
+    NSError *serror = nil;
     NSMutableURLRequest *req = [serializer requestWithMethod:@"GET"
                                                    URLString:urlString
                                                   parameters:parameters
-                                                       error:NULL];
+                                                       error:&serror];
+    if (serror || !req) {
+        if (completion) completion(nil, nil, serror ?: [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidURL userInfo:@{NSLocalizedDescriptionKey: KBLocalized(@"Invalid URL")}]);
+        return nil;
+    }
     [self applyHeaders:headers toMutableRequest:req contentType:nil];
-    return [self startAFTaskWithRequest:req completion:completion];
+    return [self startAFJSONTaskWithRequest:req completion:completion];
 }
 
 - (NSURLSessionDataTask *)POST:(NSString *)path
                        jsonBody:(id)jsonBody
                         headers:(NSDictionary<NSString *,NSString *> *)headers
                       completion:(KBNetworkCompletion)completion {
+    [self getSignWithParare:jsonBody];
+
     if (![self ensureEnabled:completion]) return nil;
     NSString *urlString = [self buildURLStringWithPath:path];
     if (!urlString) { [self fail:KBNetworkErrorInvalidURL completion:completion]; return nil; }
@@ -70,14 +93,127 @@ NSErrorDomain const KBNetworkErrorDomain = @"com.company.keyboard.network";
                                                        error:&error];
     if (error) { if (completion) completion(nil, nil, error); return nil; }
     [self applyHeaders:headers toMutableRequest:req contentType:nil];
-    return [self startAFTaskWithRequest:req completion:completion];
+    return [self startAFJSONTaskWithRequest:req completion:completion];
+}
+
+- (NSURLSessionDataTask *)uploadFile:(NSString *)path
+                             fileURL:(NSURL *)fileURL
+                                name:(NSString *)name
+                            mimeType:(NSString *)mimeType
+                          parameters:(NSDictionary *)parameters
+                             headers:(NSDictionary<NSString *, NSString *> *)headers
+                          completion:(KBNetworkCompletion)completion {
+    [self getSignWithParare:parameters];
+    if (![self ensureEnabled:completion]) return nil;
+    NSString *urlString = [self buildURLStringWithPath:path];
+    if (!urlString) { [self fail:KBNetworkErrorInvalidURL completion:completion]; return nil; }
+    if (!fileURL) {
+        if (completion) completion(nil, nil, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidResponse userInfo:@{NSLocalizedDescriptionKey: KBLocalized(@"Invalid file")}]);
+        return nil;
+    }
+    AFHTTPRequestSerializer *serializer = [AFHTTPRequestSerializer serializer];
+    serializer.timeoutInterval = self.timeout;
+    NSError *error = nil;
+    NSMutableURLRequest *req = [serializer multipartFormRequestWithMethod:@"POST"
+                                                                URLString:urlString
+                                                               parameters:parameters
+                                                constructingBodyWithBlock:^(id<AFMultipartFormData> formData) {
+        NSString *safeName = (name.length > 0) ? name : @"file";
+        NSString *fileName = fileURL.lastPathComponent ?: @"upload.bin";
+        NSString *type = (mimeType.length > 0) ? mimeType : @"application/octet-stream";
+        [formData appendPartWithFileURL:fileURL name:safeName fileName:fileName mimeType:type error:nil];
+    } error:&error];
+    if (error || !req) {
+        if (completion) completion(nil, nil, error ?: [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidURL userInfo:@{NSLocalizedDescriptionKey: KBLocalized(@"Invalid URL")}]);
+        return nil;
+    }
+    [self applyHeaders:headers toMutableRequest:req contentType:nil];
+    self.manager.responseSerializer = [AFHTTPResponseSerializer serializer];
+    NSURLSessionUploadTask *task = [self.manager uploadTaskWithStreamedRequest:req progress:nil completionHandler:^(NSURLResponse *response, id responseObject, NSError *error) {
+        if (error) {
+            if (completion) completion(nil, response, error);
+            return;
+        }
+        NSData *data = (NSData *)responseObject;
+        if (![data isKindOfClass:[NSData class]]) {
+            if (completion) completion(nil, response, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidResponse userInfo:@{NSLocalizedDescriptionKey:KBLocalized(@"No data")}]);
+            return;
+        }
+        NSString *ct = nil;
+        if ([response isKindOfClass:[NSHTTPURLResponse class]]) {
+            ct = ((NSHTTPURLResponse *)response).allHeaderFields[@"Content-Type"];
+        }
+        BOOL looksJSON = (ct && [[ct lowercaseString] containsString:@"json"]);
+        if (!looksJSON) {
+            const unsigned char *bytes = data.bytes;
+            NSUInteger len = data.length;
+            for (NSUInteger i = 0; !looksJSON && i < len; i++) {
+                unsigned char c = bytes[i];
+                if (c == ' ' || c == '\n' || c == '\r' || c == '\t') continue;
+                looksJSON = (c == '{' || c == '[');
+                break;
+            }
+        }
+        if (looksJSON) {
+            NSError *jsonErr = nil;
+            id json = [NSJSONSerialization JSONObjectWithData:data options:0 error:&jsonErr];
+            if (jsonErr) {
+                if (completion) completion(nil, response, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorDecodeFailed userInfo:@{NSLocalizedDescriptionKey:KBLocalized(@"Failed to parse JSON")}]);
+                return;
+            }
+            if (![json isKindOfClass:[NSDictionary class]]) {
+                if (completion) completion(nil, response, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidResponse userInfo:@{NSLocalizedDescriptionKey:KBLocalized(@"Invalid response")}]);
+                return;
+            }
+            if (completion) completion((NSDictionary *)json, response, nil);
+        } else {
+            if (completion) completion(nil, response, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidResponse userInfo:@{NSLocalizedDescriptionKey:KBLocalized(@"Invalid response")}]);
+        }
+    }];
+    [task resume];
+    return task;
+}
+
+- (NSURLSessionDataTask *)GETData:(NSString *)path
+                       parameters:(NSDictionary *)parameters
+                          headers:(NSDictionary<NSString *,NSString *> *)headers
+                        completion:(KBNetworkDataCompletion)completion {
+    [self getSignWithParare:parameters];
+    if (!self.isEnabled) {
+        NSError *e = [NSError errorWithDomain:KBNetworkErrorDomain
+                                         code:KBNetworkErrorDisabled
+                                     userInfo:@{NSLocalizedDescriptionKey: KBLocalized(@"Network disabled (Full Access may be off)")}];
+        if (completion) completion(nil, nil, e);
+        return nil;
+    }
+    NSString *urlString = [self buildURLStringWithPath:path];
+    if (!urlString) {
+        NSError *e = [NSError errorWithDomain:KBNetworkErrorDomain
+                                         code:KBNetworkErrorInvalidURL
+                                     userInfo:@{NSLocalizedDescriptionKey: KBLocalized(@"Invalid URL")}];
+        if (completion) completion(nil, nil, e);
+        return nil;
+    }
+    AFHTTPRequestSerializer *serializer = [AFHTTPRequestSerializer serializer];
+    serializer.timeoutInterval = self.timeout;
+    NSError *serror = nil;
+    NSMutableURLRequest *req = [serializer requestWithMethod:@"GET"
+                                                   URLString:urlString
+                                                  parameters:parameters
+                                                       error:&serror];
+    if (serror || !req) {
+        if (completion) completion(nil, nil, serror ?: [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidURL userInfo:@{NSLocalizedDescriptionKey: KBLocalized(@"Invalid URL")}]);
+        return nil;
+    }
+    [self applyHeaders:headers toMutableRequest:req contentType:nil];
+    return [self startAFDataTaskWithRequest:req completion:completion];
 }
 
 #pragma mark - Core
 
 - (BOOL)ensureEnabled:(KBNetworkCompletion)completion {
     if (!self.isEnabled) {
-        NSError *e = [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorDisabled userInfo:@{NSLocalizedDescriptionKey: @"网络未启用（可能未开启完全访问）"}];
+        NSError *e = [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorDisabled userInfo:@{NSLocalizedDescriptionKey: KBLocalized(@"Network disabled (Full Access may be off)")}];
         if (completion) completion(nil, nil, e);
         return NO;
     }
@@ -90,7 +226,12 @@ NSErrorDomain const KBNetworkErrorDomain = @"com.company.keyboard.network";
         return path;
     }
     if (self.baseURL) {
-        return [NSURL URLWithString:path relativeToURL:self.baseURL].absoluteURL.absoluteString;
+        // 统一为目录型 base（以 / 结尾），并剥掉 path 的前导 /，避免覆盖 base 路径
+        NSString *base = self.baseURL.absoluteString ?: @"";
+        if (![base hasSuffix:@"/"]) { base = [base stringByAppendingString:@"/"]; }
+        NSURL *dirBase = [NSURL URLWithString:base];
+        NSString *relative = ([path hasPrefix:@"/"]) ? [path substringFromIndex:1] : path;
+        return [NSURL URLWithString:relative relativeToURL:dirBase].absoluteURL.absoluteString;
     }
     return path; // 当无 baseURL 且 path 不是完整 URL 时，让 AFN 处理（可能失败）
 }
@@ -98,6 +239,12 @@ NSErrorDomain const KBNetworkErrorDomain = @"com.company.keyboard.network";
 - (void)applyHeaders:(NSDictionary<NSString *,NSString *> *)headers toMutableRequest:(NSMutableURLRequest *)req contentType:(NSString *)contentType {
     // 合并默认头与局部头，并注入授权头（若可用）。局部覆盖优先。
     NSMutableDictionary *all = [self.defaultHeaders mutableCopy] ?: [NSMutableDictionary new];
+    NSString *token = [KBAuthManager shared].current.accessToken;
+    if (token.length > 0) {
+        all[@"auth-token"] = token;
+    } else {
+        [all removeObjectForKey:@"auth-token"];
+    }
     NSDictionary *auth = [[KBAuthManager shared] authorizationHeader];
     [auth enumerateKeysAndObjectsUsingBlock:^(NSString *key, NSString *obj, BOOL *stop) { all[key] = obj; }];
     if (contentType) all[@"Content-Type"] = contentType;
@@ -105,42 +252,82 @@ NSErrorDomain const KBNetworkErrorDomain = @"com.company.keyboard.network";
     [all enumerateKeysAndObjectsUsingBlock:^(NSString *key, NSString *obj, BOOL *stop) { [req setValue:obj forHTTPHeaderField:key]; }];
 }
 
-- (NSURLSessionDataTask *)startAFTaskWithRequest:(NSURLRequest *)req completion:(KBNetworkCompletion)completion {
+- (NSURLSessionDataTask *)startAFJSONTaskWithRequest:(NSURLRequest *)req completion:(KBNetworkCompletion)completion {
     // 响应先用原始数据返回，再按 Content-Type 解析 JSON（与原实现一致）
     self.manager.responseSerializer = [AFHTTPResponseSerializer serializer];
     NSURLSessionDataTask *task = [self.manager dataTaskWithRequest:req uploadProgress:nil downloadProgress:nil completionHandler:^(NSURLResponse *response, id responseObject, NSError *error) {
-        if (error) { if (completion) completion(nil, response, error); return; }
+        // AFN 默认对非 2xx 的状态码返回 error；这里直接回调上层
+        if (error) {
+            if (completion) completion(nil, response, error);
+            return;
+        }
         NSData *data = (NSData *)responseObject;
         if (![data isKindOfClass:[NSData class]]) {
-            if (completion) completion(nil, response, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidResponse userInfo:@{NSLocalizedDescriptionKey:@"无数据"}]);
+            if (completion) completion(nil, response, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidResponse userInfo:@{NSLocalizedDescriptionKey:KBLocalized(@"No data")}]);
             return;
         }
         NSString *ct = nil;
         if ([response isKindOfClass:[NSHTTPURLResponse class]]) {
             ct = ((NSHTTPURLResponse *)response).allHeaderFields[@"Content-Type"];
         }
-        BOOL looksJSON = (ct && [ct.lowercaseString containsString:@"application/json"]);
+        // 更宽松的 JSON 判定：Content-Type 里包含 json；或首字符是 { / [
+        BOOL looksJSON = (ct && [[ct lowercaseString] containsString:@"json"]);
+        if (!looksJSON) {
+            // 内容嗅探（不依赖服务端声明）
+            const unsigned char *bytes = data.bytes;
+            NSUInteger len = data.length;
+            for (NSUInteger i = 0; !looksJSON && i < len; i++) {
+                unsigned char c = bytes[i];
+                if (c == ' ' || c == '\n' || c == '\r' || c == '\t') continue;
+                looksJSON = (c == '{' || c == '[');
+                break;
+            }
+        }
         if (looksJSON) {
             NSError *jsonErr = nil;
             id json = [NSJSONSerialization JSONObjectWithData:data options:0 error:&jsonErr];
-            if (jsonErr) { if (completion) completion(nil, response, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorDecodeFailed userInfo:@{NSLocalizedDescriptionKey:@"JSON解析失败"}]); return; }
-            if (completion) completion(json, response, nil);
+            if (jsonErr) {
+                if (completion) completion(nil, response, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorDecodeFailed userInfo:@{NSLocalizedDescriptionKey:KBLocalized(@"Failed to parse JSON")}]);
+                return;
+            }
+            if (![json isKindOfClass:[NSDictionary class]]) {
+                if (completion) completion(nil, response, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidResponse userInfo:@{NSLocalizedDescriptionKey:KBLocalized(@"Invalid response")}]);
+                return;
+            }
+            if (completion) completion((NSDictionary *)json, response, nil);
         } else {
-            if (completion) completion(data, response, nil);
+            if (completion) completion(nil, response, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidResponse userInfo:@{NSLocalizedDescriptionKey:KBLocalized(@"Invalid response")}]);
         }
     }];
     [task resume];
     return task;
 }
 
+- (NSURLSessionDataTask *)startAFDataTaskWithRequest:(NSURLRequest *)req completion:(KBNetworkDataCompletion)completion {
+    self.manager.responseSerializer = [AFHTTPResponseSerializer serializer];
+    NSURLSessionDataTask *task = [self.manager dataTaskWithRequest:req uploadProgress:nil downloadProgress:nil completionHandler:^(NSURLResponse *response, id responseObject, NSError *error) {
+        if (error) {
+            if (completion) completion(nil, response, error);
+            return;
+        }
+        NSData *data = (NSData *)responseObject;
+        if (![data isKindOfClass:[NSData class]]) {
+            if (completion) completion(nil, response, [NSError errorWithDomain:KBNetworkErrorDomain code:KBNetworkErrorInvalidResponse userInfo:@{NSLocalizedDescriptionKey:KBLocalized(@"No data")}]);
+            return;
+        }
+        if (completion) completion(data, response, nil);
+    }];
+    [task resume];
+    return task;
+}
+
 #pragma mark - AFHTTPSessionManager
 
 - (AFHTTPSessionManager *)manager {
     if (!_manager) {
         NSURLSessionConfiguration *cfg = [NSURLSessionConfiguration ephemeralSessionConfiguration];
         cfg.requestCachePolicy = NSURLRequestReloadIgnoringLocalCacheData;
-        cfg.timeoutIntervalForRequest = self.timeout;
-        cfg.timeoutIntervalForResource = MAX(self.timeout, 30.0);
+        // 不在会话级别设置超时，避免与 per-request 的 serializer.timeoutInterval 产生不一致
         if (@available(iOS 11.0, *)) { cfg.waitsForConnectivity = YES; }
         _manager = [[AFHTTPSessionManager alloc] initWithBaseURL:nil sessionConfiguration:cfg];
         // 默认不使用 JSON 解析器，保持原生数据，再按需解析
@@ -152,12 +339,12 @@ NSErrorDomain const KBNetworkErrorDomain = @"com.company.keyboard.network";
 #pragma mark - Private helpers
 
 - (void)fail:(KBNetworkError)code completion:(KBNetworkCompletion)completion {
-    NSString *msg = @"网络错误";
+    NSString *msg = KBLocalized(@"Network error");
     switch (code) {
-        case KBNetworkErrorDisabled: msg = @"网络未启用（可能未开启完全访问）"; break;
-        case KBNetworkErrorInvalidURL: msg = @"无效的URL"; break;
-        case KBNetworkErrorInvalidResponse: msg = @"无效的响应"; break;
-        case KBNetworkErrorDecodeFailed: msg = @"解析失败"; break;
+        case KBNetworkErrorDisabled: msg = KBLocalized(@"Network disabled (Full Access may be off)"); break;
+        case KBNetworkErrorInvalidURL: msg = KBLocalized(@"Invalid URL"); break;
+        case KBNetworkErrorInvalidResponse: msg = KBLocalized(@"Invalid response"); break;
+        case KBNetworkErrorDecodeFailed: msg = KBLocalized(@"Parse failed"); break;
         default: break;
     }
     NSError *e = [NSError errorWithDomain:KBNetworkErrorDomain

CustomKeyboard/Network/KBStreamFetcher.h

@@ -0,0 +1,60 @@
+//
+//  KBStreamFetcher.h
+//  CustomKeyboard
+//
+//  轻量网络流拉取器：支持纯文本分块与 SSE(text/event-stream) 两种形式的“边下边显”。
+//  - 增量解码：按 UTF-8 安全前缀逐步转成字符串，避免半个多字节字符导致阻塞/乱码
+//  - SSE 解析：按 \n\n 切事件，合并 data: 行，移除前缀，仅回传正文
+//  - 兼容后端“/t”作为分段标记：可自动替换为制表符“\t”
+//  - 首段去首个“\t”：若首次正文以一个制表符起始（允许前导空白），可只移除“一个”\t
+//
+// 暂未使用
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+typedef void (^KBStreamFetcherChunkHandler)(NSString *chunk);
+typedef void (^KBStreamFetcherFinishHandler)(NSError *_Nullable error);
+
+@interface KBStreamFetcher : NSObject <NSURLSessionDataDelegate>
+
+// 便利构造
++ (instancetype)fetcherWithURL:(NSURL *)url;
+
+// 必填：请求地址
+@property (nonatomic, strong) NSURL *url;
+
+/// HTTP Method，默认为 GET
+@property (nonatomic, copy, nullable) NSString *httpMethod;
+
+/// 自定义请求体（例如 POST 的 JSON body）
+@property (nonatomic, strong, nullable) NSData *httpBody;
+
+// 可选 Header
+@property (nonatomic, copy, nullable) NSDictionary<NSString *, NSString *> *extraHeaders;
+
+// 配置项（默认值见注释）
+@property (nonatomic, assign) BOOL acceptEventStream;   // 默认 NO；置 YES 时发送 Accept: text/event-stream
+@property (nonatomic, assign) BOOL disableCompression;  // 默认 YES；发送 Accept-Encoding: identity
+@property (nonatomic, assign) BOOL treatSlashTAsTab;    // 默认 YES；将“/t”替换为“\t”
+@property (nonatomic, assign) BOOL trimLeadingTabOnce;  // 默认 YES；首次正文起始的“\t”删一个（忽略前导空白）
+@property (nonatomic, assign) NSTimeInterval requestTimeout; // 默认 30s
+/// UI 刷新节奏：当一次回调内解析出多段（如多条 SSE 事件）时，按该间隔逐条回调（默认 0.10s）。
+@property (nonatomic, assign) NSTimeInterval flushInterval;
+/// 非 SSE 且一次性拿到大段文本时，是否按空格切词逐条回调（模拟“逐词流式”），默认 YES。
+@property (nonatomic, assign) BOOL splitLargeDeltasOnWhitespace;
+
+/// 调试日志：默认 YES。输出起止时刻、首包耗时、各分片内容（截断）等关键信息。
+@property (nonatomic, assign) BOOL loggingEnabled;
+
+// 回调（统一在主线程触发）
+@property (nonatomic, copy, nullable) KBStreamFetcherChunkHandler onChunk;
+@property (nonatomic, copy, nullable) KBStreamFetcherFinishHandler onFinish;
+
+// 控制
+- (void)start;
+- (void)cancel;
+
+@end
+
+NS_ASSUME_NONNULL_END

CustomKeyboard/Network/KBStreamFetcher.m

@@ -0,0 +1,519 @@
+//
+//  KBStreamFetcher.m
+//
+
+#import "KBStreamFetcher.h"
+#import "KBLocalizationManager.h"
+
+@interface KBStreamFetcher () <NSURLSessionDataDelegate>
+@property (nonatomic, strong) NSURLSession *session;
+@property (nonatomic, strong) NSURLSessionDataTask *task;
+@property (nonatomic, strong) NSMutableData *buffer;           // 网络原始字节累加
+@property (nonatomic, assign) NSStringEncoding textEncoding;   // 推断得到的文本编码（默认 UTF-8）
+@property (nonatomic, assign) BOOL isSSE;                      // 是否为 SSE 响应
+@property (nonatomic, strong) NSMutableString *sseTextBuffer;  // SSE 文本缓冲（已解码）
+@property (nonatomic, assign) NSInteger decodedPrefixBytes;    // 已解码并写入 sseTextBuffer 的字节数（SSE）
+@property (nonatomic, assign) NSInteger deliveredCharCount;    // 已回传的字符数（非 SSE，用于做增量）
+@property (nonatomic, assign) BOOL hasEmitted;                 // 是否已经输出过正文（用于“首段删 1 个 \t”）
+@property (nonatomic, assign) BOOL lastChunkEndedWithTab;      // 上一个已输出分片是否以 "\t" 结尾（用于跨分片去除“\t 后空格”）
+@property (nonatomic, strong) NSMutableArray<NSString *> *pendingQueue; // 待回调的分片（节流输出）
+@property (nonatomic, strong) NSTimer *flushTimer;             // 定时从队列取出一条回调
+@property (nonatomic, strong, nullable) NSError *finishError;  // 结束时的错误（需要等队列清空再回调）
+@property (nonatomic, copy, nullable) NSString *pendingSplitTokenPrefix; // `<SPLIT>` 跨分片残留
+
+// Metrics
+@property (nonatomic, assign) CFAbsoluteTime tStart;           // start() 被调用的时刻
+@property (nonatomic, assign) CFAbsoluteTime tFirstByte;       // 第一次拿到可解码内容
+@property (nonatomic, assign) CFAbsoluteTime tFinish;          // 完成/失败时刻
+@property (nonatomic, assign) NSInteger emittedChunkCount;     // 已输出分片数量
+@end
+
+// 计算数据中以 UTF-8 编码可完整解码的“前缀字节长度”，避免切断多字节字符
+static NSUInteger kb_validUTF8PrefixLen(NSData *data) {
+    const unsigned char *bytes = (const unsigned char *)data.bytes;
+    NSUInteger n = data.length;
+    if (n == 0) return 0;
+    NSInteger i = (NSInteger)n - 1;
+    while (i >= 0 && (bytes[i] & 0xC0) == 0x80) { i--; } // 10xxxxxx 续字节
+    if (i < 0) return 0; // 全是续字节，等下次
+    unsigned char b = bytes[i];
+    NSUInteger expected = 1;
+    if ((b & 0x80) == 0x00) expected = 1;        // 0xxxxxxx
+    else if ((b & 0xE0) == 0xC0) expected = 2;   // 110xxxxx
+    else if ((b & 0xF0) == 0xE0) expected = 3;   // 1110xxxx
+    else if ((b & 0xF8) == 0xF0) expected = 4;   // 11110xxx
+    else return (NSUInteger)i;                   // 非法起始，截到 i 之前
+    NSUInteger remain = n - (NSUInteger)i;
+    return (remain >= expected) ? n : (NSUInteger)i;
+}
+
+static NSString * const kKBStreamSplitToken = @"<SPLIT>";
+
+@implementation KBStreamFetcher
+
++ (instancetype)fetcherWithURL:(NSURL *)url {
+    KBStreamFetcher *f = [[self alloc] init];
+    f.url = url;
+    return f;
+}
+
+- (instancetype)init {
+    if (self = [super init]) {
+        _httpMethod = @"GET";
+        _acceptEventStream = NO;
+        _disableCompression = YES;
+        _treatSlashTAsTab = YES;
+        _trimLeadingTabOnce = YES;
+        _requestTimeout = 30.0;
+        _textEncoding = NSUTF8StringEncoding;
+        _buffer = [NSMutableData data];
+        _sseTextBuffer = [NSMutableString string];
+        _pendingQueue = [NSMutableArray array];
+        _flushInterval = 0.1;
+        _splitLargeDeltasOnWhitespace = YES;
+        _loggingEnabled = YES;
+        _pendingSplitTokenPrefix = nil;
+    }
+    return self;
+}
+
+- (void)start {
+    if (!self.url) return;
+    [self cancel];
+
+    NSURLSessionConfiguration *cfg = [NSURLSessionConfiguration defaultSessionConfiguration];
+    cfg.requestCachePolicy = NSURLRequestReloadIgnoringLocalCacheData;
+    cfg.timeoutIntervalForRequest = self.requestTimeout;
+    cfg.timeoutIntervalForResource = MAX(self.requestTimeout, 60.0);
+
+    self.session = [NSURLSession sessionWithConfiguration:cfg delegate:self delegateQueue:[NSOperationQueue mainQueue]];
+
+    NSMutableURLRequest *req = [NSMutableURLRequest requestWithURL:self.url];
+    NSString *method = self.httpMethod.length > 0 ? self.httpMethod : @"GET";
+    req.HTTPMethod = method;
+    if (self.httpBody.length > 0) {
+        req.HTTPBody = self.httpBody;
+    }
+    if (self.disableCompression) { [req setValue:@"identity" forHTTPHeaderField:@"Accept-Encoding"]; }
+    if (self.acceptEventStream) { [req setValue:@"text/event-stream" forHTTPHeaderField:@"Accept"]; }
+    [req setValue:@"no-cache" forHTTPHeaderField:@"Cache-Control"];
+    [req setValue:@"keep-alive" forHTTPHeaderField:@"Connection"];
+    [self.extraHeaders enumerateKeysAndObjectsUsingBlock:^(NSString *k, NSString *v, BOOL *stop){ [req setValue:v forHTTPHeaderField:k]; }];
+
+    // 状态复位
+    [self.buffer setLength:0];
+    [self.sseTextBuffer setString:@""];
+    self.isSSE = NO;
+    self.textEncoding = NSUTF8StringEncoding;
+    self.decodedPrefixBytes = 0;
+    self.deliveredCharCount = 0;
+    self.hasEmitted = NO;
+    self.lastChunkEndedWithTab = NO;
+    [self.pendingQueue removeAllObjects];
+    [self.flushTimer invalidate]; self.flushTimer = nil;
+    self.finishError = nil;
+    self.pendingSplitTokenPrefix = nil;
+
+    self.tStart = CFAbsoluteTimeGetCurrent();
+    self.tFirstByte = 0;
+    self.tFinish = 0;
+    self.emittedChunkCount = 0;
+    if (self.loggingEnabled) {
+        NSLog(@"[KBStream] start url=%@ acceptSSE=%@ disableCompression=%@ flush=%.0fms splitWords=%@",
+              self.url.absoluteString,
+              self.acceptEventStream?@"YES":@"NO",
+              self.disableCompression?@"YES":@"NO",
+              self.flushInterval*1000.0,
+              self.splitLargeDeltasOnWhitespace?@"YES":@"NO");
+    }
+    self.task = [self.session dataTaskWithRequest:req];
+    [self.task resume];
+}
+
+- (void)cancel {
+    [self.task cancel];
+    self.task = nil;
+    [self.session invalidateAndCancel];
+    self.session = nil;
+    [self.buffer setLength:0];
+    [self.sseTextBuffer setString:@""];
+    self.decodedPrefixBytes = 0;
+    self.deliveredCharCount = 0;
+    self.hasEmitted = NO;
+    self.lastChunkEndedWithTab = NO;
+    [self.pendingQueue removeAllObjects];
+    [self.flushTimer invalidate]; self.flushTimer = nil;
+    self.finishError = nil;
+    self.pendingSplitTokenPrefix = nil;
+}
+
+#pragma mark - NSURLSessionDataDelegate
+
+- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask didReceiveResponse:(NSURLResponse *)response completionHandler:(void (^)(NSURLSessionResponseDisposition))completionHandler {
+    self.isSSE = NO;
+    self.textEncoding = NSUTF8StringEncoding;
+    if ([response isKindOfClass:[NSHTTPURLResponse class]]) {
+        NSHTTPURLResponse *r = (NSHTTPURLResponse *)response;
+        NSString *ct = r.allHeaderFields[@"Content-Type"] ?: r.allHeaderFields[@"content-type"];
+        if ([ct isKindOfClass:[NSString class]]) {
+            NSString *lower = [ct lowercaseString];
+            if ([lower containsString:@"text/event-stream"]) self.isSSE = YES;
+            NSRange pos = [lower rangeOfString:@"charset="];
+            if (pos.location != NSNotFound) {
+                NSString *charset = [[lower substringFromIndex:pos.location + pos.length] componentsSeparatedByString:@";"][0];
+                if ([charset containsString:@"utf-8"] || [charset containsString:@"utf8"]) {
+                    self.textEncoding = NSUTF8StringEncoding;
+                } else if ([charset containsString:@"iso-8859-1"] || [charset containsString:@"latin1"]) {
+                    self.textEncoding = NSISOLatin1StringEncoding;
+                }
+            }
+        }
+    }
+    [self.sseTextBuffer setString:@""];
+    self.decodedPrefixBytes = 0;
+    if (completionHandler) completionHandler(NSURLSessionResponseAllow);
+}
+
+- (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask didReceiveData:(NSData *)data {
+    if (data.length == 0) return;
+    [self.buffer appendData:data];
+
+    NSUInteger validLen = (self.textEncoding == NSUTF8StringEncoding)
+        ? kb_validUTF8PrefixLen(self.buffer)
+        : self.buffer.length;
+    if (validLen > 0 && self.tFirstByte == 0) {
+        self.tFirstByte = CFAbsoluteTimeGetCurrent();
+        if (self.loggingEnabled) {
+            NSLog(@"[KBStream] first-bytes after %.0fms (encoding=%@, SSE=%@)",
+                  (self.tFirstByte - self.tStart)*1000.0,
+                  (self.textEncoding==NSUTF8StringEncoding?@"UTF-8":@"Other"),
+                  self.isSSE?@"YES":@"NO");
+        }
+    }
+    if (validLen == 0) return; // 末尾可能卡着半个字符
+
+    if (self.isSSE) {
+        if ((NSUInteger)self.decodedPrefixBytes < validLen) {
+            NSRange rng = NSMakeRange((NSUInteger)self.decodedPrefixBytes, validLen - (NSUInteger)self.decodedPrefixBytes);
+            NSString *piece = [[NSString alloc] initWithBytes:(const char *)self.buffer.bytes + rng.location
+                                                       length:rng.length
+                                                     encoding:self.textEncoding];
+            if (piece.length > 0) {
+                [self.sseTextBuffer appendString:piece];
+                self.decodedPrefixBytes = (NSInteger)validLen;
+            }
+        }
+        // 统一换行并按 SSE 事件 \n\n 切开
+        if (self.sseTextBuffer.length > 0) {
+            NSString *normalized = [self.sseTextBuffer stringByReplacingOccurrencesOfString:@"\r\n" withString:@"\n"];
+            [self.sseTextBuffer setString:normalized];
+            while (1) {
+                NSRange sep = [self.sseTextBuffer rangeOfString:@"\n\n"]; // 完整事件
+                if (sep.location == NSNotFound) break;
+                NSString *event = [self.sseTextBuffer substringToIndex:sep.location];
+                [self.sseTextBuffer deleteCharactersInRange:NSMakeRange(0, sep.location + sep.length)];
+
+                // 合并 data: 行为正文
+                NSArray<NSString *> *lines = [event componentsSeparatedByString:@"\n"];
+                NSMutableString *payload = [NSMutableString string];
+                for (NSString *ln in lines) {
+                    if ([ln hasPrefix:@"data:"]) {
+                        NSString *v = [ln substringFromIndex:5];
+                        if (v.length > 0 && [v hasPrefix:@" "]) v = [v substringFromIndex:1];
+                        [payload appendString:v ?: @""];
+                    }
+                }
+        if (payload.length > 0) {
+            if (self.loggingEnabled) {
+                NSLog(@"[KBStream] SSE raw payload: %@", payload);
+            }
+            NSString *llmText = nil;
+            if ([self processLLMChunkPayload:payload output:&llmText]) {
+                if (llmText.length > 0) { [self enqueueChunk:llmText]; }
+            } else {
+                [self enqueueChunk:payload];
+                    }
+                }
+            }
+        }
+        return;
+    }
+
+    // 非 SSE：直接对“可解码前缀”做增量输出
+    NSString *prefix = [[NSString alloc] initWithBytes:self.buffer.bytes length:validLen encoding:self.textEncoding];
+    if (!prefix) return;
+    if (self.deliveredCharCount < (NSInteger)prefix.length) {
+        NSString *delta = [prefix substringFromIndex:self.deliveredCharCount];
+        self.deliveredCharCount = prefix.length;
+        if (self.splitLargeDeltasOnWhitespace && delta.length > 16) {
+            // 按空格切词逐条回调（保留空格，使观感更自然）
+            NSArray<NSString *> *parts = [delta componentsSeparatedByString:@" "];
+            for (NSUInteger i = 0; i < parts.count; i++) {
+                NSString *w = parts[i];
+                if (w.length == 0) { [self enqueueChunk:@" "]; continue; }
+                if (i + 1 < parts.count) {
+                    [self enqueueChunk:[w stringByAppendingString:@" "]];
+                } else {
+                    [self enqueueChunk:w];
+                }
+            }
+        } else {
+            [self enqueueChunk:delta];
+        }
+    }
+}
+
+- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task didCompleteWithError:(NSError *)error {
+    if (!error && self.isSSE && self.sseTextBuffer.length > 0) {
+        // 处理最后一条未以 \n\n 结束的事件
+        NSString *normalized = [self.sseTextBuffer stringByReplacingOccurrencesOfString:@"\r\n" withString:@"\n"];
+        NSArray<NSString *> *lines = [normalized componentsSeparatedByString:@"\n"];
+        NSMutableString *payload = [NSMutableString string];
+        for (NSString *ln in lines) {
+            if ([ln hasPrefix:@"data:"]) {
+                NSString *v = [ln substringFromIndex:5];
+                if (v.length > 0 && [v hasPrefix:@" "]) v = [v substringFromIndex:1];
+                [payload appendString:v ?: @""];
+            }
+        }
+        if (payload.length > 0) {
+            if (self.loggingEnabled) {
+                NSLog(@"[KBStream] SSE raw payload: %@", payload);
+            }
+            NSString *delta = nil;
+            if ((NSInteger)payload.length >= self.deliveredCharCount) {
+                delta = [payload substringFromIndex:self.deliveredCharCount];
+            } else {
+                delta = payload;
+            }
+            self.deliveredCharCount = payload.length;
+            if (delta.length > 0) {
+                NSString *llmText = nil;
+                if ([self processLLMChunkPayload:delta output:&llmText]) {
+                    if (llmText.length > 0) { [self emitChunk:llmText]; }
+                } else {
+                    [self emitChunk:delta];
+                }
+            }
+        }
+    }
+    if (self.pendingSplitTokenPrefix.length > 0) {
+        NSString *carry = self.pendingSplitTokenPrefix;
+        self.pendingSplitTokenPrefix = nil;
+        if (carry.length > 0) { [self enqueueChunk:carry]; }
+    }
+
+    self.tFinish = CFAbsoluteTimeGetCurrent();
+    if (self.loggingEnabled) {
+        double t0 = (self.tFirstByte>0? (self.tFirstByte - self.tStart)*1000.0 : -1);
+        double t1 = (self.tFirstByte>0? (self.tFinish - self.tFirstByte)*1000.0 : -1);
+        double tt = (self.tFinish - self.tStart)*1000.0;
+        NSLog(@"[KBStream] finish chunks=%ld firstByte=%.0fms after start, tail=%.0fms, total=%.0fms error=%@",
+              (long)self.emittedChunkCount, t0, t1, tt, error);
+    }
+    // 若队列还有待输出内容，等队列清空再回调 finish
+    if (self.pendingQueue.count > 0) {
+        self.finishError = error;
+        [self startFlushTimerIfNeeded];
+    } else {
+        if (self.onFinish) dispatch_async(dispatch_get_main_queue(), ^{ self.onFinish(error); });
+        [self cancel];
+    }
+}
+
+#pragma mark - Helpers
+
+- (void)emitChunk:(NSString *)rawText {
+    if (rawText.length == 0) return;
+    // 调试：在任何处理之前打印后端“原始文本分片”，便于对照排查
+    if (self.loggingEnabled) {
+//        NSLog(@"[KBStream] RAW chunk#%ld len=%lu text=\"%@\"",
+//              (long)(self.emittedChunkCount + 1),
+//              (unsigned long)rawText.length,
+//              KBPrintableSnippet(rawText, 160));
+    }
+    NSString *text = rawText;
+    // 0) 规范化换行与段起始：去掉位于片段开头的 \r/\n；将 "\n\t"、"\r\n\t"、"\r\t" 归一为 "\t"
+    text = [text stringByReplacingOccurrencesOfString:@"\r\n\t" withString:@"\t"];
+    text = [text stringByReplacingOccurrencesOfString:@"\n\t" withString:@"\t"];
+    text = [text stringByReplacingOccurrencesOfString:@"\r\t" withString:@"\t"];
+    while (text.length > 0) {
+        unichar c0 = [text characterAtIndex:0];
+        if (c0 == '\n' || c0 == '\r') { text = [text substringFromIndex:1]; continue; }
+        break;
+    }
+    // 1) 统一处理 “/t” -> “\t”
+    if (self.treatSlashTAsTab) {
+        text = [text stringByReplacingOccurrencesOfString:@"/t" withString:@"\t"];
+    }
+    // 2) 仅在整体首段：去掉一个起始的 "\t"，以及其后紧邻的一个空格（若存在）
+    if (!self.hasEmitted && self.trimLeadingTabOnce) {
+        if (text.length > 0 && [text characterAtIndex:0] == '\t') {
+            NSUInteger start = 1;
+            if (start < text.length && [text characterAtIndex:start] == ' ') start++;
+            text = [text substringFromIndex:start];
+        }
+    }
+    // 3) 从第二段开始：去掉每个段首的一个空格（即 “\t ” -> “\t”），跨分片也处理
+    if (text.length > 0) {
+        // 跨分片：若上个分片以 \t 结尾，本分片起始的一个或多个空格去掉一个
+        if (self.lastChunkEndedWithTab) {
+            NSUInteger j = 0;
+            while (j < text.length && [text characterAtIndex:j] == ' ') { j++; }
+            if (j > 0) {
+                text = [text substringFromIndex:1]; // 仅去一个空格
+            }
+        }
+        // 同一分片内：将 “\t ” 规范化为 “\t”（仅去一个空格）
+        text = [text stringByReplacingOccurrencesOfString:@"\t " withString:@"\t"];
+    }
+    if (text.length == 0) { self.lastChunkEndedWithTab = NO; return; }
+    self.emittedChunkCount += 1;
+    if (self.loggingEnabled) {
+        NSLog(@"[KBStream] chunk#%ld len=%lu text=\"%@\"",
+              (long)self.emittedChunkCount, (unsigned long)text.length, KBPrintableSnippet(text, 160));
+    }
+    if (self.onChunk) dispatch_async(dispatch_get_main_queue(), ^{ self.onChunk(text); });
+    self.hasEmitted = YES;
+    // 记录末尾是否为分段分隔符 \t（用于跨分片处理）
+    unichar lastc = [text characterAtIndex:text.length - 1];
+    self.lastChunkEndedWithTab = (lastc == '\t');
+}
+
+- (BOOL)processLLMChunkPayload:(NSString *)payload output:(NSString * _Nullable __autoreleasing *)output {
+    if (output) { *output = nil; }
+    if (payload.length == 0) { return NO; }
+    NSData *jsonData = [payload dataUsingEncoding:NSUTF8StringEncoding];
+    if (!jsonData) { return NO; }
+    NSError *jsonError = nil;
+    id obj = [NSJSONSerialization JSONObjectWithData:jsonData options:0 error:&jsonError];
+    if (jsonError || ![obj isKindOfClass:[NSDictionary class]]) { return NO; }
+    NSString *type = ((NSDictionary *)obj)[@"type"];
+    if (![type isKindOfClass:[NSString class]]) { return NO; }
+    if ([type isEqualToString:@"llm_chunk"]) {
+        id dataValue = ((NSDictionary *)obj)[@"data"];
+        if (![dataValue isKindOfClass:[NSString class]]) {
+            if (output) { *output = @""; }
+            return YES;
+        }
+        NSString *normalized = [self normalizedLLMDataString:(NSString *)dataValue];
+        if (output) { *output = normalized; }
+        return YES;
+    }
+    if ([type isEqualToString:@"search_result"]) {
+        NSString *searchText = [self normalizedSearchResultString:((NSDictionary *)obj)[@"data"]];
+        if (output) { *output = searchText ?: @""; }
+        return YES;
+    }
+    if ([type isEqualToString:@"done"]) {
+        if (output) { *output = @""; }
+        return YES;
+    }
+    return NO;
+}
+
+- (NSString *)normalizedLLMDataString:(NSString *)dataString {
+    NSString *combined = dataString ?: @"";
+    if (self.pendingSplitTokenPrefix.length > 0) {
+        combined = [self.pendingSplitTokenPrefix stringByAppendingString:combined];
+        self.pendingSplitTokenPrefix = nil;
+    }
+    if (combined.length == 0) { return @""; }
+    NSString *result = [combined stringByReplacingOccurrencesOfString:kKBStreamSplitToken withString:@"\t"];
+    NSString *suffix = [self pendingSplitPrefixSuffixForString:result];
+    if (suffix.length > 0) {
+        self.pendingSplitTokenPrefix = suffix;
+        result = [result substringToIndex:result.length - suffix.length];
+    }
+    return result;
+}
+
+- (NSString *)normalizedSearchResultString:(id)dataValue {
+    if (![dataValue isKindOfClass:[NSArray class]]) { return @""; }
+    NSArray *list = (NSArray *)dataValue;
+    NSMutableArray<NSString *> *segments = [NSMutableArray array];
+    for (NSUInteger i = 0; i < list.count; i++) {
+        id item = list[i];
+        NSString *payload = nil;
+        if ([item isKindOfClass:[NSDictionary class]]) {
+            id val = ((NSDictionary *)item)[@"payload"];
+            if ([val isKindOfClass:[NSString class]]) {
+                payload = (NSString *)val;
+            }
+        } else if ([item isKindOfClass:[NSString class]]) {
+            payload = (NSString *)item;
+        }
+        payload = [payload stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]];
+        if (payload.length == 0) { continue; }
+        NSString *line = [NSString stringWithFormat:@"%lu. %@", (unsigned long)(segments.count + 1), payload];
+        [segments addObject:line];
+    }
+    if (segments.count == 0) { return @""; }
+    NSString *title = KBLocalized(@"Search result");
+    NSMutableString *text = [NSMutableString string];
+    [text appendString:@"\t"];
+    [text appendFormat:@"%@:", title.length > 0 ? title : @"Search result"];
+    for (NSString *line in segments) {
+        [text appendString:@"\t"];
+        [text appendString:line];
+    }
+    return text;
+}
+
+- (NSString *)pendingSplitPrefixSuffixForString:(NSString *)text {
+    if (text.length == 0) { return @""; }
+    NSUInteger tokenLen = kKBStreamSplitToken.length;
+    if (tokenLen <= 1) { return @""; }
+    NSUInteger maxLen = MIN(tokenLen - 1, text.length);
+    for (NSUInteger len = maxLen; len > 0; len--) {
+        NSString *suffix = [text substringFromIndex:text.length - len];
+        NSString *prefix = [kKBStreamSplitToken substringToIndex:len];
+        if ([suffix isEqualToString:prefix]) {
+            return suffix;
+        }
+    }
+    return @"";
+}
+
+#pragma mark - Queue/Flush
+
+- (void)enqueueChunk:(NSString *)s {
+    if (s.length == 0) return;
+    [self.pendingQueue addObject:s];
+    [self startFlushTimerIfNeeded];
+}
+
+- (void)startFlushTimerIfNeeded {
+    if (self.flushTimer) return;
+    __weak typeof(self) weakSelf = self;
+    self.flushTimer = [NSTimer scheduledTimerWithTimeInterval:MAX(0.01, self.flushInterval)
+                                                     repeats:YES
+                                                       block:^(NSTimer * _Nonnull t) {
+        __strong typeof(weakSelf) self = weakSelf; if (!self) { [t invalidate]; return; }
+        if (self.pendingQueue.count == 0) {
+            [t invalidate]; self.flushTimer = nil;
+            if (self.finishError || self.finishError == nil) {
+                NSError *err = self.finishError; self.finishError = nil;
+                if (self.onFinish) dispatch_async(dispatch_get_main_queue(), ^{ self.onFinish(err); });
+                [self cancel];
+            }
+            return;
+        }
+        NSString *first = self.pendingQueue.firstObject;
+        [self.pendingQueue removeObjectAtIndex:0];
+        [self emitChunk:first];
+    }];
+}
+
+#pragma mark - Logging helpers
+
+static NSString *KBPrintableSnippet(NSString *s, NSUInteger maxLen) {
+    if (!s) return @"";
+    NSString *x = [s stringByReplacingOccurrencesOfString:@"\n" withString:@"\\n"];
+    if (x.length > maxLen) {
+        x = [[x substringToIndex:maxLen] stringByAppendingString:@"…"];
+    }
+    return x;
+}
+
+@end

CustomKeyboard/Network/NetworkStreamHandler.h

@@ -0,0 +1,71 @@
+//
+//  NetworkStreamHandler.h
+//  CustomKeyboard
+//
+//  Created by Mac on 2025/11/12.
+//
+// 暂未使用
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+typedef NS_ENUM(NSUInteger, NetworkStreamState) {
+    NetworkStreamStateIdle,
+    NetworkStreamStateConnecting,
+    NetworkStreamStateReceiving,
+    NetworkStreamStateCompleted,
+    NetworkStreamStateError
+};
+
+@class NetworkStreamHandler;
+
+@protocol NetworkStreamDelegate <NSObject>
+
+@optional
+// 接收到数据块
+- (void)networkStream:(NetworkStreamHandler *)stream didReceiveData:(NSData *)data;
+// 接收到文本数据（如果是文本内容）
+- (void)networkStream:(NetworkStreamHandler *)stream didReceiveText:(NSString *)text;
+// 进度更新
+- (void)networkStream:(NetworkStreamHandler *)stream downloadProgress:(float)progress;
+// 状态改变
+- (void)networkStream:(NetworkStreamHandler *)stream stateChanged:(NetworkStreamState)state;
+// 请求完成
+- (void)networkStream:(NetworkStreamHandler *)stream didCompleteWithError:(NSError * _Nullable)error;
+
+@end
+
+typedef void (^NetworkStreamProgressBlock)(float progress);
+typedef void (^NetworkStreamDataBlock)(NSData *data);
+typedef void (^NetworkStreamTextBlock)(NSString *text);
+typedef void (^NetworkStreamCompletionBlock)(NSError * _Nullable error);
+
+@interface NetworkStreamHandler : NSObject <NSURLSessionDataDelegate>
+
+@property (nonatomic, weak) id<NetworkStreamDelegate> delegate;
+@property (nonatomic, assign, readonly) NetworkStreamState state;
+@property (nonatomic, strong, readonly) NSURLResponse *response;
+@property (nonatomic, assign, readonly) long long totalBytesReceived;
+
+// 初始化方法
+- (instancetype)initWithURL:(NSURL *)url;
+- (instancetype)initWithRequest:(NSURLRequest *)request;
+
+// 开始请求（使用代理回调）
+- (void)startRequest;
+
+// 开始请求（使用 Block 回调）
+- (void)startRequestWithProgress:(NetworkStreamProgressBlock _Nullable)progress
+                        onData:(NetworkStreamDataBlock _Nullable)dataBlock
+                        onText:(NetworkStreamTextBlock _Nullable)textBlock
+                     completion:(NetworkStreamCompletionBlock _Nullable)completion;
+
+// 取消请求
+- (void)cancelRequest;
+
+// 构建默认请求（包含常见的请求头）
++ (NSURLRequest *)createDefaultRequestWithURL:(NSURL *)url method:(NSString *)method;
+
+@end
+
+NS_ASSUME_NONNULL_END

CustomKeyboard/Network/NetworkStreamHandler.m

@@ -0,0 +1,253 @@
+//
+//  NetworkStreamHandler.m
+//  CustomKeyboard
+//
+//  Created by Mac on 2025/11/12.
+//
+
+#import "NetworkStreamHandler.h"
+
+@interface NetworkStreamHandler ()
+
+@property (nonatomic, strong) NSURLSession *session;
+@property (nonatomic, strong) NSURLSessionDataTask *dataTask;
+@property (nonatomic, strong) NSURLRequest *request;
+@property (nonatomic, strong) NSMutableData *receivedData;
+@property (nonatomic, assign) long long expectedContentLength;
+@property (nonatomic, assign) NetworkStreamState state;
+@property (nonatomic, strong) NSURLResponse *response;
+
+// Block 回调
+@property (nonatomic, copy) NetworkStreamProgressBlock progressBlock;
+@property (nonatomic, copy) NetworkStreamDataBlock dataBlock;
+@property (nonatomic, copy) NetworkStreamTextBlock textBlock;
+@property (nonatomic, copy) NetworkStreamCompletionBlock completionBlock;
+
+@end
+
+@implementation NetworkStreamHandler
+
+- (instancetype)initWithURL:(NSURL *)url {
+    NSURLRequest *request = [NetworkStreamHandler createDefaultRequestWithURL:url method:@"GET"];
+    return [self initWithRequest:request];
+}
+
+- (instancetype)initWithRequest:(NSURLRequest *)request {
+    self = [super init];
+    if (self) {
+        _request = request;
+        _receivedData = [NSMutableData data];
+        _state = NetworkStreamStateIdle;
+        _totalBytesReceived = 0;
+        
+        // 创建 URLSession 配置
+        NSURLSessionConfiguration *config = [NSURLSessionConfiguration defaultSessionConfiguration];
+        config.timeoutIntervalForRequest = 30.0;
+        config.timeoutIntervalForResource = 300.0;
+        config.requestCachePolicy = NSURLRequestReloadIgnoringLocalCacheData;
+        
+        // 创建 URLSession
+        _session = [NSURLSession sessionWithConfiguration:config
+                                                 delegate:self
+                                            delegateQueue:[NSOperationQueue mainQueue]];
+    }
+    return self;
+}
+
+- (void)dealloc {
+    [self cancelRequest];
+}
+
+#pragma mark - Public Methods
+
+- (void)startRequest {
+    if (self.state != NetworkStreamStateIdle) {
+        NSLog(@"Request already in progress");
+        return;
+    }
+    
+    [self updateState:NetworkStreamStateConnecting];
+    self.dataTask = [self.session dataTaskWithRequest:self.request];
+    [self.dataTask resume];
+}
+
+- (void)startRequestWithProgress:(NetworkStreamProgressBlock)progress
+                         onData:(NetworkStreamDataBlock)dataBlock
+                         onText:(NetworkStreamTextBlock)textBlock
+                      completion:(NetworkStreamCompletionBlock)completion {
+    
+    self.progressBlock = progress;
+    self.dataBlock = dataBlock;
+    self.textBlock = textBlock;
+    self.completionBlock = completion;
+    
+    [self startRequest];
+}
+
+- (void)cancelRequest {
+    if (self.dataTask) {
+        [self.dataTask cancel];
+        self.dataTask = nil;
+    }
+    [self updateState:NetworkStreamStateIdle];
+}
+
++ (NSURLRequest *)createDefaultRequestWithURL:(NSURL *)url method:(NSString *)method {
+    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
+    request.HTTPMethod = method;
+    request.timeoutInterval = 30.0;
+    
+    // 设置常见的请求头（根据您的截图）
+    [request setValue:@"text/html, application/xhtml+xml, application/xml; q=0.9, image/avif, image/webp, image/apng, */*; q=0.8, application/signed-exchange; v=b3; q=0.7" forHTTPHeaderField:@"Accept"];
+    [request setValue:@"gzip, deflate" forHTTPHeaderField:@"Accept-Encoding"];
+    [request setValue:@"zh-CN, zh; q=0.9, ko; q=0.8, ja; q=0.7" forHTTPHeaderField:@"Accept-Language"];
+    [request setValue:@"keep-alive" forHTTPHeaderField:@"Connection"];
+    [request setValue:@"1" forHTTPHeaderField:@"Upgrade-Insecure-Requests"];
+    
+    // 用户代理（可选）
+    NSString *userAgent = @"Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.0 Mobile/15E148 Safari/604.1";
+    [request setValue:userAgent forHTTPHeaderField:@"User-Agent"];
+    
+    return [request copy];
+}
+
+#pragma mark - Private Methods
+
+- (void)updateState:(NetworkStreamState)newState {
+    if (_state != newState) {
+        _state = newState;
+        
+        // 通知代理状态改变
+        if ([self.delegate respondsToSelector:@selector(networkStream:stateChanged:)]) {
+            [self.delegate networkStream:self stateChanged:newState];
+        }
+    }
+}
+
+- (void)notifyProgress:(float)progress {
+    if (self.progressBlock) {
+        self.progressBlock(progress);
+    }
+    
+    if ([self.delegate respondsToSelector:@selector(networkStream:downloadProgress:)]) {
+        [self.delegate networkStream:self downloadProgress:progress];
+    }
+}
+
+- (void)notifyReceivedData:(NSData *)data {
+    if (self.dataBlock) {
+        self.dataBlock(data);
+    }
+    
+    if ([self.delegate respondsToSelector:@selector(networkStream:didReceiveData:)]) {
+        [self.delegate networkStream:self didReceiveData:data];
+    }
+    
+    // 如果是文本数据，尝试转换为字符串
+    if (self.textBlock || [self.delegate respondsToSelector:@selector(networkStream:didReceiveText:)]) {
+        NSString *text = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
+        if (text) {
+            if (self.textBlock) {
+                self.textBlock(text);
+            }
+            if ([self.delegate respondsToSelector:@selector(networkStream:didReceiveText:)]) {
+                [self.delegate networkStream:self didReceiveText:text];
+            }
+        }
+    }
+}
+
+- (void)notifyCompletionWithError:(NSError * _Nullable)error {
+    if (self.completionBlock) {
+        self.completionBlock(error);
+    }
+    
+    if ([self.delegate respondsToSelector:@selector(networkStream:didCompleteWithError:)]) {
+        [self.delegate networkStream:self didCompleteWithError:error];
+    }
+}
+
+#pragma mark - NSURLSessionDataDelegate
+
+- (void)URLSession:(NSURLSession *)session
+          dataTask:(NSURLSessionDataTask *)dataTask
+didReceiveResponse:(NSURLResponse *)response
+ completionHandler:(void (^)(NSURLSessionResponseDisposition))completionHandler {
+    
+    self.response = response;
+    self.expectedContentLength = response.expectedContentLength;
+    _totalBytesReceived = 0;
+    [self.receivedData setLength:0];
+    
+    [self updateState:NetworkStreamStateReceiving];
+    
+    // 检查响应头，处理 CORS 等
+    if ([response isKindOfClass:[NSHTTPURLResponse class]]) {
+        NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *)response;
+        NSLog(@"Response headers: %@", httpResponse.allHeaderFields);
+        
+        // 可以在这里检查 CORS 头等信息
+        NSString *allowOrigin = httpResponse.allHeaderFields[@"Access-Control-Allow-Origin"];
+        if (allowOrigin) {
+            NSLog(@"CORS Allow Origin: %@", allowOrigin);
+        }
+    }
+    
+    completionHandler(NSURLSessionResponseAllow);
+}
+
+- (void)URLSession:(NSURLSession *)session
+          dataTask:(NSURLSessionDataTask *)dataTask
+    didReceiveData:(NSData *)data {
+    
+    _totalBytesReceived += data.length;
+    [self.receivedData appendData:data];
+    
+    // 通知接收到数据块
+    [self notifyReceivedData:data];
+    
+    // 计算并通知进度
+    if (self.expectedContentLength != NSURLResponseUnknownLength) {
+        float progress = (float)self.totalBytesReceived / (float)self.expectedContentLength;
+        [self notifyProgress:progress];
+    } else {
+        // 对于 chunked 传输，可能没有确切的内容长度
+        [self notifyProgress:-1]; // 使用 -1 表示未知进度
+    }
+}
+
+- (void)URLSession:(NSURLSession *)session
+              task:(NSURLSessionTask *)task
+didCompleteWithError:(NSError *)error {
+    
+    if (error) {
+        [self updateState:NetworkStreamStateError];
+        NSLog(@"Request failed with error: %@", error);
+    } else {
+        [self updateState:NetworkStreamStateCompleted];
+        NSLog(@"Request completed successfully. Total bytes: %lld", self.totalBytesReceived);
+    }
+    
+    [self notifyCompletionWithError:error];
+    
+    // 清理
+    [self.session finishTasksAndInvalidate];
+    self.dataTask = nil;
+}
+
+#pragma mark - URL Session Delegate (处理 SSL/认证)
+
+- (void)URLSession:(NSURLSession *)session
+didReceiveChallenge:(NSURLAuthenticationChallenge *)challenge
+ completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition, NSURLCredential * _Nullable))completionHandler {
+    
+    // 处理 SSL 认证挑战
+    if ([challenge.protectionSpace.authenticationMethod isEqualToString:NSURLAuthenticationMethodServerTrust]) {
+        NSURLCredential *credential = [NSURLCredential credentialForTrust:challenge.protectionSpace.serverTrust];
+        completionHandler(NSURLSessionAuthChallengeUseCredential, credential);
+    } else {
+        completionHandler(NSURLSessionAuthChallengePerformDefaultHandling, nil);
+    }
+}
+
+@end

CustomKeyboard/Network/WJXEventSource/WJXEventSource.h

@@ -0,0 +1,70 @@
+//
+//  WJXEventSource.h
+//  WJXEventSource
+//
+//  Created by JiuxingWang on 2025/2/9.
+//
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+#ifdef __cplusplus
+#define WJX_EXTERN        extern "C" __attribute__((visibility ("default")))
+#else
+#define WJX_EXTERN        extern __attribute__((visibility ("default")))
+#endif
+
+/// 消息事件
+typedef NSString *WJXEventName NS_TYPED_EXTENSIBLE_ENUM;
+
+/// 消息事件
+WJX_EXTERN WJXEventName const WJXEventNameMessage;
+
+/// readyState 变化事件
+WJX_EXTERN WJXEventName const WJXEventNameReadyState;
+
+/// open 事件
+WJX_EXTERN WJXEventName const WJXEventNameOpen;
+
+/// error 事件
+WJX_EXTERN WJXEventName const WJXEventNameError;
+
+typedef NS_ENUM(NSUInteger, WJXEventState) {
+    WJXEventStateConnecting = 0,
+    WJXEventStateOpen,
+    WJXEventStateClosed,
+};
+
+@interface WJXEvent : NSObject
+
+@property (nonatomic, strong, nullable) id eventId;
+
+@property (nonatomic, copy, nullable) NSString *event;
+@property (nonatomic, copy, nullable) NSString *data;
+
+@property (nonatomic, assign) WJXEventState readyState;
+@property (nonatomic, strong, nullable) NSError *error;
+
+- (instancetype)initWithReadyState:(WJXEventState)readyState;
+
+@end
+
+typedef void(^WJXEventSourceEventHandler)(WJXEvent *event);
+
+@interface WJXEventSource : NSObject
+
+@property (nonatomic, assign) BOOL ignoreRetryAction;
+
+- (instancetype)initWithRquest:(NSURLRequest *)request;
+
+- (void)addListener:(WJXEventSourceEventHandler)listener
+           forEvent:(WJXEventName)eventName
+              queue:(nullable NSOperationQueue *)queue;
+
+- (void)open;
+- (void)close;
+
+@end
+
+NS_ASSUME_NONNULL_END

CustomKeyboard/Network/WJXEventSource/WJXEventSource.m

@@ -0,0 +1,309 @@
+//
+//  WJXEventSource.m
+//  WJXEventSource
+//
+//  Created by JiuxingWang on 2025/2/9.
+//
+
+#import "WJXEventSource.h"
+
+/// 消息事件
+WJXEventName const WJXEventNameMessage = @"message";
+
+/// readyState 变化事件
+WJXEventName const WJXEventNameReadyState = @"readyState";
+
+/// open 事件
+WJXEventName const WJXEventNameOpen = @"open";
+
+/// error 事件
+WJXEventName const WJXEventNameError = @"error";
+
+#pragma mark -
+#pragma mark WJXEvent
+
+@implementation WJXEvent
+
+- (instancetype)initWithReadyState:(WJXEventState)readyState;
+{
+    if (self = [super init]) {
+        self.readyState = readyState;
+    }
+    return self;
+}
+
+- (NSString *)description
+{
+    NSString *state = nil;
+    switch (_readyState) {
+        case WJXEventStateConnecting: {
+            state = @"CONNECTING";
+        } break;
+            
+        case WJXEventStateOpen: {
+            state = @"OPEN";
+        } break;
+            
+        case WJXEventStateClosed: {
+            state = @"CLOSED";
+        } break;
+    }
+    
+    return [NSString stringWithFormat:@"<%@: readyState: %@, id: %@; event: %@; data: %@>", [self class], state, _eventId, _event, _data];
+}
+
+@end
+
+
+#pragma mark -
+#pragma mark WJXEventHandler
+
+@interface WJXEventHandler : NSObject
+
+@property (nonatomic, copy, nonnull) WJXEventSourceEventHandler handler;
+@property (nonatomic, strong, nullable) NSOperationQueue *queue;
+
+@end
+
+@implementation WJXEventHandler
+
+- (instancetype)initWithHandler:(WJXEventSourceEventHandler)handler queue:(NSOperationQueue *)queue
+{
+    if (self = [super init]) {
+        self.handler = handler;
+        self.queue = queue;
+    }
+    return self;
+}
+
+@end
+
+
+#pragma mark -
+#pragma mark WJXEventSource
+
+@interface WJXEventSource () <NSURLSessionDataDelegate>
+
+@property (nonatomic, strong) NSMutableURLRequest *request;
+@property (nonatomic, strong) NSMutableDictionary<WJXEventName, NSMutableArray<WJXEventHandler *> *> *listeners;
+
+@property (nonatomic, strong) NSURLSession *session;
+@property (nonatomic, strong) NSURLSessionDataTask *dataTask;
+@property (nonatomic, copy) NSString *lastEventId;
+@property (nonatomic, assign) NSTimeInterval retryInterval;
+
+@property (nonatomic, assign) BOOL closedByUser;
+@property (nonatomic, strong) NSMutableData *buffer;
+
+@end
+
+@implementation WJXEventSource
+
+- (instancetype)initWithRquest:(NSURLRequest *)request;
+{
+    if (self = [super init]) {
+        self.request = [request mutableCopy];
+        self.listeners = [NSMutableDictionary dictionary];
+        self.session = [NSURLSession sessionWithConfiguration:[NSURLSessionConfiguration ephemeralSessionConfiguration] delegate:self delegateQueue:NSOperationQueue.mainQueue];
+        self.buffer = [NSMutableData data];
+    }
+    return self;
+}
+
+- (void)dealloc
+{
+    [_session finishTasksAndInvalidate];
+}
+
+- (void)addListener:(WJXEventSourceEventHandler)listener
+           forEvent:(WJXEventName)eventName
+              queue:(nullable NSOperationQueue *)queue;
+{
+    if (nil == listener) {
+        return;
+    }
+    
+    NSMutableArray *listeners = self.listeners[eventName];
+    if (nil == listeners) {
+        self.listeners[eventName] = listeners = [NSMutableArray array];
+    }
+    [listeners addObject:[[WJXEventHandler alloc] initWithHandler:listener queue:queue]];
+}
+
+- (void)open;
+{
+    if (_lastEventId.length) {
+        [_request setValue:_lastEventId forHTTPHeaderField:@"Last-Event-ID"];
+    }
+    
+    self.dataTask = [_session dataTaskWithRequest:_request];
+    [_dataTask resume];
+    
+    WJXEvent *event = [[WJXEvent alloc] initWithReadyState:WJXEventStateConnecting];
+    [self _dispatchEvent:event forName:WJXEventNameReadyState];
+}
+
+- (void)close;
+{
+    self.closedByUser = YES;
+    [_dataTask cancel];
+    [_session finishTasksAndInvalidate];
+    _buffer = [NSMutableData data];
+}
+
+
+#pragma mark -
+#pragma mark NSURLSessionDataDelegate
+
+- (void)URLSession:(NSURLSession *)session
+          dataTask:(NSURLSessionDataTask *)dataTask
+didReceiveResponse:(NSURLResponse *)response
+ completionHandler:(void (^)(NSURLSessionResponseDisposition disposition))completionHandler;
+{
+    NSHTTPURLResponse *HTTPResponse = (NSHTTPURLResponse *)response;
+    if (200 == HTTPResponse.statusCode) {
+        WJXEvent *event = [[WJXEvent alloc] initWithReadyState:WJXEventStateOpen];
+        [self _dispatchEvent:event forName:WJXEventNameReadyState];
+        [self _dispatchEvent:event forName:WJXEventNameOpen];
+    }
+    
+    if (nil != completionHandler) {
+        completionHandler(NSURLSessionResponseAllow);
+    }
+}
+
+- (void)URLSession:(NSURLSession *)session
+          dataTask:(NSURLSessionDataTask *)dataTask
+    didReceiveData:(NSData *)data;
+{
+    [_buffer appendData:data];
+    [self _processBuffer];
+}
+
+- (void)URLSession:(NSURLSession *)session
+          task:(NSURLSessionTask *)task
+didCompleteWithError:(nullable NSError *)error;
+{
+    if (_closedByUser) {
+        _buffer = [NSMutableData data];
+        return;
+    }
+
+    [self _dispatchPlainBufferIfNeeded];
+    
+    WJXEvent *event = [[WJXEvent alloc] initWithReadyState:WJXEventStateClosed];
+    if (nil == (event.error = error)) {
+        event.error = [NSError errorWithDomain:@"WJXEventSource" code:event.readyState userInfo:@{
+            NSLocalizedDescriptionKey: @"Connection with the event source was closed without error",
+        }];
+    }
+    [self _dispatchEvent:event forName:WJXEventNameReadyState];
+    
+    if (nil != error) {
+        [self _dispatchEvent:event forName:WJXEventNameError];
+        if (!_ignoreRetryAction) {
+            [self performSelector:@selector(open) withObject:nil afterDelay:_retryInterval];
+        }
+    }
+}
+
+
+#pragma mark -
+#pragma mark Private
+
+- (void)_processBuffer
+{
+    NSData *separatorLFLFData = [NSData dataWithBytes:"\n\n" length:2];
+    
+    NSRange range = [_buffer rangeOfData:separatorLFLFData options:kNilOptions range:(NSRange) {
+        .length = _buffer.length
+    }];
+    
+    while (NSNotFound != range.location) {
+        // Extract event data
+        NSData *eventData = [_buffer subdataWithRange:(NSRange) {
+            .length = range.location
+        }];
+        [_buffer replaceBytesInRange:(NSRange) {
+            .length = range.location + 2
+        } withBytes:NULL length:0];
+        
+        [self _parseEventData:eventData];
+        
+        // Look for next event
+        range = [_buffer rangeOfData:separatorLFLFData options:kNilOptions range:(NSRange) {
+            .length = _buffer.length
+        }];
+    }
+}
+
+- (void)_parseEventData:(NSData *)data
+{
+    WJXEvent *event = [[WJXEvent alloc] initWithReadyState:WJXEventStateOpen];
+    
+    NSString *eventString = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
+    if (eventString.length == 0) { return; }
+    NSArray *lines = [eventString componentsSeparatedByCharactersInSet:NSCharacterSet.newlineCharacterSet];
+    BOOL hasDataLine = NO;
+    for (NSString *line in lines) {
+        if ([line hasPrefix:@"id:"]) {
+            event.eventId = [[line substringFromIndex:3] stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceCharacterSet];
+        } else if ([line hasPrefix:@"event:"]) {
+            event.event = [[line substringFromIndex:6] stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceCharacterSet];
+        } else if ([line hasPrefix:@"data:"]) {
+            hasDataLine = YES;
+            NSString *data = [[line substringFromIndex:5] stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceCharacterSet];
+            event.data = event.data ? [event.data stringByAppendingFormat:@"\n%@", data] : data;
+        } else if ([line hasPrefix:@"retry:"]) {
+            NSString *retryString = [[line substringFromIndex:6] stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceCharacterSet];
+            self.retryInterval = [retryString doubleValue] / 1000;
+        }
+    }
+
+    if (!hasDataLine) {
+        NSString *trimmed = [eventString stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]];
+        if (trimmed.length > 0) {
+            event.data = trimmed;
+        }
+    }
+    
+    if (event.eventId) {
+        self.lastEventId = event.eventId;
+    }
+    
+    [self _dispatchEvent:event forName:WJXEventNameMessage];
+}
+
+- (void)_dispatchEvent:(WJXEvent *)event forName:(WJXEventName)name
+{
+    NSMutableArray<WJXEventHandler *> *listeners = self.listeners[name];
+    [listeners enumerateObjectsUsingBlock:^(WJXEventHandler * _Nonnull handler, NSUInteger idx, BOOL * _Nonnull stop) {
+        NSOperationQueue *queue = handler.queue ?: NSOperationQueue.mainQueue;
+        [queue addOperationWithBlock:^{
+            handler.handler(event);
+        }];
+    }];
+}
+
+- (void)_dispatchPlainBufferIfNeeded
+{
+    if (_buffer.length == 0) { return; }
+    NSData *data = [_buffer copy];
+    [_buffer setLength:0];
+    if (data.length == 0) { return; }
+    [self _parseEventData:data];
+}
+
+
+#pragma mark -
+#pragma mark Setters
+
+- (void)setDataTask:(NSURLSessionDataTask *)dataTask
+{
+    self.closedByUser = YES; {
+        [_dataTask cancel];
+        _dataTask = dataTask;
+    } self.closedByUser = NO;
+}
+
+@end

CustomKeyboard/PrefixHeader.pch

@@ -17,15 +17,25 @@
 
 // 公共配置
 #import "KBConfig.h"
+#import "KBAPI.h"      // 接口路径宏（统一管理）
 #import "Masonry.h"
 #import "KBHUD.h"   // 复用 App 内的 HUD 封装
 #import "KBLocalizationManager.h" // 复用多语言封装（可在扩展内使用）
+#import "KBMaiPointReporter.h"
+//#import "KBLog.h"
+
 
 // 通用链接（Universal Links）统一配置
 // 配置好 AASA 与 Associated Domains 后，只需修改这里即可切换域名/path。
-#define KB_UL_BASE      @"https://your.domain/ul"   // 替换为你的真实域名与前缀路径
+#define KB_UL_BASE      @"https://app.tknb.net/ul"   // 与 Associated Domains 一致
 #define KB_UL_LOGIN     KB_UL_BASE @"/login"
 #define KB_UL_SETTINGS  KB_UL_BASE @"/settings"
 
+// 在扩展内，启用 URL Bridge（仅在显式的用户点击动作中使用）
+// 这样即便宿主 App（如备忘录）拒绝 extensionContext 的 openURL，仍可通过响应链兜底拉起容器 App。
+#ifndef KB_URL_BRIDGE_ENABLE
+#define KB_URL_BRIDGE_ENABLE 1
+#endif
+
 
 #endif /* PrefixHeader_pch */

CustomKeyboard/PrivacyInfo.xcprivacy

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>NSPrivacyTracking</key>
+	<false/>
+	<key>NSPrivacyTrackingDomains</key>
+	<array/>
+	<key>NSPrivacyCollectedDataTypes</key>
+	<array>
+		<dict>
+			<key>NSPrivacyCollectedDataType</key>
+			<string>NSPrivacyCollectedDataTypeOtherUserContent</string>
+			<key>NSPrivacyCollectedDataTypeLinked</key>
+			<true/>
+			<key>NSPrivacyCollectedDataTypeTracking</key>
+			<false/>
+			<key>NSPrivacyCollectedDataTypePurposes</key>
+			<array>
+				<string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+			</array>
+		</dict>
+	</array>
+	<key>NSPrivacyAccessedAPITypes</key>
+	<array>
+		<dict>
+			<key>NSPrivacyAccessedAPIType</key>
+			<string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+			<key>NSPrivacyAccessedAPITypeReasons</key>
+			<array>
+				<string>CA92.1</string>
+			</array>
+		</dict>
+		<dict>
+			<key>NSPrivacyAccessedAPIType</key>
+			<string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
+			<key>NSPrivacyAccessedAPITypeReasons</key>
+			<array>
+				<string>C617.1</string>
+			</array>
+		</dict>
+	</array>
+</dict>
+</plist>

CustomKeyboard/Resource/KBSkinIconMap.strings

@@ -0,0 +1,248 @@
+/* 字母 q（小写） */
+"letter_q_lower" = "key_q";
+/* 字母 Q（大写） */
+"letter_q_upper" = "key_q_up";
+
+/* 字母 w（小写） */
+"letter_w_lower" = "key_w";
+/* 字母 W（大写） */
+"letter_w_upper" = "key_w_up";
+
+/* 字母 e（小写） */
+"letter_e_lower" = "key_e";
+/* 字母 E（大写） */
+"letter_e_upper" = "key_e_up";
+
+/* 字母 r（小写） */
+"letter_r_lower" = "key_r";
+/* 字母 R（大写） */
+"letter_r_upper" = "key_r_up";
+
+/* 字母 t（小写） */
+"letter_t_lower" = "key_t";
+/* 字母 T（大写） */
+"letter_t_upper" = "key_t_up";
+
+/* 字母 y（小写） */
+"letter_y_lower" = "key_y";
+/* 字母 Y（大写） */
+"letter_y_upper" = "key_y_up";
+
+/* 字母 u（小写） */
+"letter_u_lower" = "key_u";
+/* 字母 U（大写） */
+"letter_u_upper" = "key_u_up";
+
+/* 字母 i（小写） */
+"letter_i_lower" = "key_i";
+/* 字母 I（大写） */
+"letter_i_upper" = "key_i_up";
+
+/* 字母 o（小写） */
+"letter_o_lower" = "key_o";
+/* 字母 O（大写） */
+"letter_o_upper" = "key_o_up";
+
+/* 字母 p（小写） */
+"letter_p_lower" = "key_p";
+/* 字母 P（大写） */
+"letter_p_upper" = "key_p_up";
+
+/* 字母 a（小写） */
+"letter_a_lower" = "key_a";
+/* 字母 A（大写） */
+"letter_a_upper" = "key_a_up";
+
+/* 字母 s（小写） */
+"letter_s_lower" = "key_s";
+/* 字母 S（大写） */
+"letter_s_upper" = "key_s_up";
+
+/* 字母 d（小写） */
+"letter_d_lower" = "key_d";
+/* 字母 D（大写） */
+"letter_d_upper" = "key_d_up";
+
+/* 字母 f（小写） */
+"letter_f_lower" = "key_f";
+/* 字母 F（大写） */
+"letter_f_upper" = "key_f_up";
+
+/* 字母 g（小写） */
+"letter_g_lower" = "key_g";
+/* 字母 G（大写） */
+"letter_g_upper" = "key_g_up";
+
+/* 字母 h（小写） */
+"letter_h_lower" = "key_h";
+/* 字母 H（大写） */
+"letter_h_upper" = "key_h_up";
+
+/* 字母 j（小写） */
+"letter_j_lower" = "key_j";
+/* 字母 J（大写） */
+"letter_j_upper" = "key_j_up";
+
+/* 字母 k（小写） */
+"letter_k_lower" = "key_k";
+/* 字母 K（大写） */
+"letter_k_upper" = "key_k_up";
+
+/* 字母 l（小写） */
+"letter_l_lower" = "key_l";
+/* 字母 L（大写） */
+"letter_l_upper" = "key_l_up";
+
+/* 字母 z（小写） */
+"letter_z_lower" = "key_z";
+/* 字母 Z（大写） */
+"letter_z_upper" = "key_z_up";
+
+/* 字母 x（小写） */
+"letter_x_lower" = "key_x";
+/* 字母 X（大写） */
+"letter_x_upper" = "key_x_up";
+
+/* 字母 c（小写） */
+"letter_c_lower" = "key_c";
+/* 字母 C（大写） */
+"letter_c_upper" = "key_c_up";
+
+/* 字母 v（小写） */
+"letter_v_lower" = "key_v";
+/* 字母 V（大写） */
+"letter_v_upper" = "key_v_up";
+
+/* 字母 b（小写） */
+"letter_b_lower" = "key_b";
+/* 字母 B（大写） */
+"letter_b_upper" = "key_b_up";
+
+/* 字母 n（小写） */
+"letter_n_lower" = "key_n";
+/* 字母 N（大写） */
+"letter_n_upper" = "key_n_up";
+
+/* 字母 m（小写） */
+"letter_m_lower" = "key_m";
+/* 字母 M（大写） */
+"letter_m_upper" = "key_m_up";
+
+/* 数字 1 */
+"digit_1" = "key_1";
+/* 数字 2 */
+"digit_2" = "key_2";
+/* 数字 3 */
+"digit_3" = "key_3";
+/* 数字 4 */
+"digit_4" = "key_4";
+/* 数字 5 */
+"digit_5" = "key_5";
+/* 数字 6 */
+"digit_6" = "key_6";
+/* 数字 7 */
+"digit_7" = "key_7";
+/* 数字 8 */
+"digit_8" = "key_8";
+/* 数字 9 */
+"digit_9" = "key_9";
+/* 数字 0 */
+"digit_0" = "key_0";
+
+/* '-' */
+"sym_minus" = "key_minus";
+/* '/' */
+"sym_slash" = "key_slash";
+/* ':' */
+"sym_colon" = "key_colon";
+/* ';' */
+"sym_semicolon" = "key_semicolon";
+/* '(' */
+"sym_paren_l" = "key_paren_l";
+/* ')' */
+"sym_paren_r" = "key_paren_r";
+/* '$' */
+"sym_dollar" = "key_dollar";
+/* '&' */
+"sym_amp" = "key_amp";
+/* '@' */
+"sym_at" = "key_at";
+/* 双引号 " */
+"sym_quote_double" = "key_quote_d";
+
+/* ',' */
+"sym_comma" = "key_comma";
+/* '.' */
+"sym_dot" = "key_dot";
+/* '?' */
+"sym_question" = "key_question";
+/* '!' */
+"sym_exclam" = "key_exclam";
+/* 单引号 ' */
+"sym_quote_single" = "key_quote";
+
+/* '[' */
+"sym_bracket_l" = "key_bracket_l";
+/* ']' */
+"sym_bracket_r" = "key_bracket_r";
+/* '{' */
+"sym_brace_l" = "key_brace_l";
+/* '}' */
+"sym_brace_r" = "key_brace_r";
+/* '#' */
+"sym_hash" = "key_hash";
+/* '%' */
+"sym_percent" = "key_percent";
+/* '^' */
+"sym_caret" = "key_caret";
+/* '*' */
+"sym_asterisk" = "key_asterisk";
+/* '+' */
+"sym_plus" = "key_plus";
+/* '=' */
+"sym_equal" = "key_equal";
+
+/* '_' */
+"sym_underscore" = "key_underscore";
+/* '\' */
+"sym_backslash" = "key_backslash";
+/* '|' */
+"sym_pipe" = "key_pipe";
+/* '~' */
+"sym_tilde" = "key_tilde";
+/* '<' */
+"sym_lt" = "key_lt";
+/* '>' */
+"sym_gt" = "key_gt";
+/* '¥' */
+"sym_money" = "key_money";
+/* '€' */
+"sym_euro" = "key_euro";
+/* '£' */
+"sym_pound" = "key_pound";
+/* '•' */
+"sym_bullet" = "key_bullet";
+
+/* 空格键 */
+"space" = "key_space";
+/* 删除键（⌫） */
+"backspace" = "key_del";
+/* Shift（⇧） */
+"shift" = "key_up";
+/* Shift（⇧）大写 */
+"shift_upper" = "key_up_upper";
+/* 字母面板左下角 "123" */
+"mode_123" = "key_123";
+/* 数字面板左下角 "abc" */
+"mode_abc" = "key_abc";
+/* 数字面板内 "123 -> #+=" */
+"symbols_toggle_more" = "key_symbols_more";
+/* 数字面板内 "#+= -> 123" */
+"symbols_toggle_123" = "key_symbols_123";
+/* 自定义 AI 功能键 */
+"ai" = "key_ai";
+/* Emoji功能键 */
+//"emoji" = "key_emoji";
+"emoji_panel" = "key_emoji";
+/* 发送/换行键 */
+"return" = "key_send";

CustomKeyboard/Resource/kb_keyboard_layout_config.json

@@ -0,0 +1,414 @@
+{
+  "__comment": "键盘布局配置：所有尺寸为设计稿值（会按 designWidth 等比缩放）",
+  "designWidth": 375,
+  "__comment_designWidth": "设计稿宽度（如 375），用于计算缩放比例",
+  "defaultKeyBackground": "#FFFFFF",
+  "__comment_defaultKeyBackground": "无皮肤时按键默认背景色",
+  "metrics": {
+    "__comment": "全局尺寸参数（单位：pt，按 designWidth 缩放）",
+    "rowSpacing": 8,
+    "__comment_rowSpacing": "行间距（垂直）",
+    "topInset": 8,
+    "__comment_topInset": "键盘顶部内边距",
+    "bottomInset": 6,
+    "__comment_bottomInset": "键盘底部内边距",
+    "keyHeight": 41,
+    "__comment_keyHeight": "默认按键高度",
+    "edgeInset": 4,
+    "__comment_edgeInset": "行左右内边距（默认）",
+    "gap": 5,
+    "__comment_gap": "按键之间水平间距",
+    "letterWidth": 32,
+    "__comment_letterWidth": "字母键默认宽度",
+    "controlWidth": 41,
+    "__comment_controlWidth": "控制键宽度（如 shift/backspace/123）",
+    "sendWidth": 88,
+    "__comment_sendWidth": "send 键宽度",
+    "symbolsWideWidth": 47,
+    "__comment_symbolsWideWidth": "符号第3行中间大键宽度",
+    "symbolsSideWidth": 41,
+    "__comment_symbolsSideWidth": "符号第3行左右控制键宽度"
+  },
+  "fonts": {
+    "__comment": "字体大小（pt）",
+    "letter": 20,
+    "__comment_letter": "字母键字体大小",
+    "digit": 20,
+    "__comment_digit": "数字键字体大小",
+    "symbol": 18,
+    "__comment_symbol": "符号键字体大小",
+    "mode": 14,
+    "__comment_mode": "模式切换键字体大小（ABC/#+=/123）",
+    "space": 18,
+    "__comment_space": "空格键字体大小",
+    "send": 18,
+    "__comment_send": "发送键字体大小"
+  },
+  "keyDefs": {
+    "__comment": "特殊功能键配置（id 对应布局中的 item）",
+    "shift": {
+      "__comment": "大小写切换键",
+      "type": "shift",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "⇧",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "symbolName": "shift",
+      "__comment_symbolName": "无皮肤时使用 SF Symbol 名称",
+      "selectedSymbolName": "shift.fill",
+      "__comment_selectedSymbolName": "选中态 SF Symbol 名称",
+      "font": "symbol",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "controlWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "backspace": {
+      "__comment": "删除键",
+      "type": "backspace",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "⌫",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "symbol",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "controlWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "mode_123": {
+      "__comment": "字母面板左下角 123",
+      "type": "mode",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "123",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "mode",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "controlWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "mode_abc": {
+      "__comment": "数字面板左下角 ABC",
+      "type": "mode",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "ABC",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "mode",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "controlWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "symbols_toggle_more": {
+      "__comment": "数字面板内 123 -> #+=",
+      "type": "symbolsToggle",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "#+=",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "mode",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "symbolsSideWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "symbols_toggle_123": {
+      "__comment": "数字面板内 #+= -> 123",
+      "type": "symbolsToggle",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "123",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "mode",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "symbolsSideWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "emoji": {
+      "__comment": "emoji 功能键",
+      "type": "custom",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "😁",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "symbol",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "controlWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "space": {
+      "__comment": "空格键",
+      "type": "space",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "space",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "space",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "flex",
+      "__comment_width": "flex 表示自动占满剩余空间"
+    },
+    "send": {
+      "__comment": "发送键",
+      "type": "return",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "send",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "send",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "sendWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    }
+  },
+  "layouts": {
+    "__comment": "布局集合：letters/numbers/symbolsMore",
+    "letters": {
+      "__comment": "字母布局（小写/大写共用）",
+      "rows": [
+        {
+          "__comment": "字母第一行 qwertyuiop",
+          "align": "left",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "items": [
+            "letter:q", "letter:w", "letter:e", "letter:r", "letter:t",
+            "letter:y", "letter:u", "letter:i", "letter:o", "letter:p"
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
+        },
+        {
+          "__comment": "字母第二行 asdfghjkl",
+          "align": "center",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 0,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 0,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "items": [
+            "letter:a", "letter:s", "letter:d", "letter:f", "letter:g",
+            "letter:h", "letter:j", "letter:k", "letter:l"
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
+        },
+        {
+          "__comment": "字母第三行：左 shift，中间字母，右 backspace",
+          "align": "left",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "segments": {
+            "__comment": "分段布局：left/center/right",
+            "left": [
+              { "id": "shift", "width": "controlWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.controlWidth" }
+            ],
+            "__comment_left": "左侧固定按钮",
+            "center": [
+              "letter:z", "letter:x", "letter:c", "letter:v", "letter:b", "letter:n", "letter:m"
+            ],
+            "__comment_center": "中间字母键集合，整体居中",
+            "right": [
+              { "id": "backspace", "width": "controlWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.controlWidth" }
+            ],
+            "__comment_right": "右侧固定按钮"
+          }
+        },
+        {
+          "__comment": "字母第四行：123/emoji/space/send",
+          "align": "left",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "items": [
+            "mode_123", "emoji", "space", "send"
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
+        }
+      ]
+    },
+    "numbers": {
+      "__comment": "数字面板布局（123 页）",
+      "rows": [
+        {
+          "__comment": "数字第一行 1234567890",
+          "align": "left",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "items": [
+            "digit:1", "digit:2", "digit:3", "digit:4", "digit:5",
+            "digit:6", "digit:7", "digit:8", "digit:9", "digit:0"
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
+        },
+        {
+          "__comment": "数字第二行 - / : ; ( ) ￥ & @ “",
+          "align": "left",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "items": [
+            "sym:-", "sym:/", "sym::", "sym:;", "sym:(",
+            "sym:)", "sym:￥", "sym:&", "sym:@", "sym:“"
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
+        },
+        {
+          "__comment": "数字第三行：#+= / 中间符号 / 删除",
+          "align": "center",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "segments": {
+            "__comment": "分段布局：left/center/right",
+            "left": [
+              { "id": "symbols_toggle_more", "width": "symbolsSideWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.symbolsSideWidth" }
+            ],
+            "__comment_left": "左侧切换按钮",
+            "center": [
+              { "id": "sym:.", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:,", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:?", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:!", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:‘", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" }
+            ],
+            "__comment_center": "中间符号键集合，整体居中",
+            "right": [
+              { "id": "backspace", "width": "symbolsSideWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.symbolsSideWidth" }
+            ],
+            "__comment_right": "右侧删除键"
+          }
+        },
+        {
+          "__comment": "数字第四行：ABC/emoji/space/send",
+          "align": "left",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "items": [
+            "mode_abc", "emoji", "space", "send"
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
+        }
+      ]
+    },
+    "symbolsMore": {
+      "__comment": "符号面板布局（#+= 页）",
+      "rows": [
+        {
+          "__comment": "符号第一行 [ ] { } # % ^ * + =",
+          "align": "left",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "items": [
+            "sym:[", "sym:]", "sym:{", "sym:}", "sym:#",
+            "sym:%", "sym:^", "sym:*", "sym:+", "sym:="
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
+        },
+        {
+          "__comment": "符号第二行 _ \\ | ~ < > € ￥ $ ·",
+          "align": "left",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "items": [
+            "sym:_", "sym:\\", "sym:|", "sym:~", "sym:<",
+            "sym:>", "sym:€", "sym:￥", "sym:$", "sym:·"
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
+        },
+        {
+          "__comment": "符号第三行：123 / 中间符号 / 删除",
+          "align": "center",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "segments": {
+            "__comment": "分段布局：left/center/right",
+            "left": [
+              { "id": "symbols_toggle_123", "width": "symbolsSideWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.symbolsSideWidth" }
+            ],
+            "__comment_left": "左侧切换按钮",
+            "center": [
+              { "id": "sym:.", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:,", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:?", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:!", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:‘", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" }
+            ],
+            "__comment_center": "中间符号键集合，整体居中",
+            "right": [
+              { "id": "backspace", "width": "symbolsSideWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.symbolsSideWidth" }
+            ],
+            "__comment_right": "右侧删除键"
+          }
+        },
+        {
+          "__comment": "符号第四行：ABC/emoji/space/send",
+          "align": "left",
+          "__comment_align": "对齐方式：left/center",
+          "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
+          "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
+          "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
+          "items": [
+            "mode_abc", "emoji", "space", "send"
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
+        }
+      ]
+    }
+  }
+}

CustomKeyboard/Utils/KBBackspaceLongPressHandler.h

@@ -0,0 +1,22 @@
+//
+//  KBBackspaceLongPressHandler.h
+//  CustomKeyboard
+//
+
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface KBBackspaceLongPressHandler : NSObject
+
+- (instancetype)initWithContainerView:(UIView *)containerView;
+
+/// 配置删除按钮（包含长按删除；可选是否显示“上滑清空”提示）
+- (void)bindDeleteButton:(nullable UIView *)button showClearLabel:(BOOL)showClearLabel;
+
+/// 触发“上滑清空”逻辑（可用于功能面板的清空按钮）
+- (void)performClearAction;
+
+@end
+
+NS_ASSUME_NONNULL_END