fix(camera): clarify toolbar semantics and delay first frame

Tonnodoubt · Tonnodoubt · commit 1e3db9c6debe · 2026-04-03T11:02:29.000+08:00
diff --git a/app/(tabs)/main.tsx b/app/(tabs)/main.tsx
@@ -888,7 +888,7 @@ const MainUIScreen: React.FC<MainUIScreenProps> = () => {
     return false;
   }, [audio.isConnected, audio.isRecording, audio.sendMessage]);
 
-  const handleToggleScreen = useCallback(async (next: boolean) => {
+  const handleToggleCamera = useCallback(async (next: boolean) => {
     if (!next) {
       // 停止摄像头
       cameraStream.stopStreaming();
@@ -1352,7 +1352,7 @@ const MainUIScreen: React.FC<MainUIScreenProps> = () => {
         - 详见：docs/strategy/cross-platform-components.md
         
         功能包括：
-        - 麦克风/屏幕共享切换
+        - 麦克风/摄像头切换
         - Agent 设置面板
         - Settings 面板
         - 设置菜单（Live2D设置、API密钥、角色管理等）
@@ -1364,7 +1364,7 @@ const MainUIScreen: React.FC<MainUIScreenProps> = () => {
           right={isMobile ? 12 : 24}
           top={isMobile ? screenHeight * 0.05 : 24}
           micEnabled={toolbarMicEnabled}
-          screenEnabled={cameraStream.isStreaming}
+          cameraEnabled={cameraStream.isStreaming}
           goodbyeMode={toolbarGoodbyeMode}
           openPanel={toolbarOpenPanel}
           onOpenPanelChange={setToolbarOpenPanel}
@@ -1373,7 +1373,7 @@ const MainUIScreen: React.FC<MainUIScreenProps> = () => {
           agent={agent}
           onAgentChange={handleToolbarAgentChange}
           onToggleMic={handleToggleMic}
-          onToggleScreen={handleToggleScreen}
+          onToggleCamera={handleToggleCamera}
           onGoodbye={handleGoodbye}
           onReturn={handleReturn}
           onSettingsMenuClick={handleSettingsMenuClick}
diff --git a/assets/icons/README.md b/assets/icons/README.md
@@ -7,7 +7,7 @@
 请从主项目的 `static/icons/` 目录复制以下图标文件到此目录：
 
 - `mic_icon_off.png` - 麦克风图标
-- `screen_icon_off.png` - 屏幕分享图标
+- `screen_icon_off.png` - 摄像头按钮当前复用的历史图标资源
 - `Agent_off.png` - Agent 工具图标
 - `set_off.png` - 设置图标
 - `rest_off.png` - 离开/返回图标
diff --git a/docs/features/realtime-vision-guide.md b/docs/features/realtime-vision-guide.md
@@ -172,7 +172,7 @@ export interface CameraStreamConfig {
 **关键实现**：
 
 - `setCameraRef(ref)` — 绑定 CameraView ref
-- `start()` — 启动 `setInterval` 帧捕获循环，立即捕获第一帧
+- `start()` — 启动帧捕获循环，首帧延迟约 500ms 以提升 CameraView 启动稳定性
 - `stop()` — 清除 interval，状态回到 `idle`
 - `pause()` / `resume()` — 后台暂停/恢复
 - `captureAndSend()` — 内部方法：
@@ -256,7 +256,7 @@ const cameraStream = useCameraStream({
 **(c) 替换 toolbarScreenEnabled 状态 (line 220)**
 
 - 删除 `const [toolbarScreenEnabled, setToolbarScreenEnabled] = useState(false);`
-- 把 toolbar 的 `screenEnabled` prop 改为 `screenEnabled={cameraStream.isStreaming}`
+- 把 toolbar 的 `cameraEnabled` prop 接到 `cameraStream.isStreaming`
 
 **(d) 重写 handleToggleScreen (line 772-775)**
 
@@ -303,7 +303,7 @@ iOS `NSCameraUsageDescription` 也做同样更新。
 | `services/imageCompression.ts` | 直接复用 `compress()` 方法，无需改动 |
 | `services/AudioService.ts` | 通过 hook 层的 `sendMessage` 消费 |
 | `hooks/useCamera.ts` | 单张拍照 hook，保持独立 |
-| `packages/project-neko-components/` | toolbar 已有 `screenEnabled` / `onToggleScreen` props |
+| `packages/project-neko-components/` | toolbar 已统一为 `cameraEnabled` / `onToggleCamera` props |
 | 后端所有文件 | 协议和限流完全兼容 |
 
 #### 4.2.5 实现顺序
@@ -385,7 +385,7 @@ React 渲染 CameraStreamOverlay + CameraView
         ↓
 onCameraReady 回调触发 → setCameraRef + start()
         ↓
-setInterval 启动 (每 1.5s) + 立即捕获第一帧
+定时启动 (每 1.5s) + 首帧延迟约 500ms
         ↓
 takePictureAsync() → ImageCompressionService.compress()
         ↓
diff --git a/packages/project-neko-components/src/Live2DRightToolbar/Live2DRightToolbar.native.tsx b/packages/project-neko-components/src/Live2DRightToolbar/Live2DRightToolbar.native.tsx
@@ -44,7 +44,7 @@ export function Live2DRightToolbar({
   top = 24,
   isMobile,
   micEnabled,
-  screenEnabled,
+  cameraEnabled,
   goodbyeMode,
   openPanel,
   onOpenPanelChange,
@@ -53,7 +53,7 @@ export function Live2DRightToolbar({
   agent,
   onAgentChange,
   onToggleMic,
-  onToggleScreen,
+  onToggleCamera,
   onGoodbye,
   onReturn,
   onSettingsMenuClick,
@@ -68,19 +68,19 @@ export function Live2DRightToolbar({
   // 使用共享的按钮配置（RN 使用本地 require() 资源）
   const buttons = useToolbarButtons<number>({
     micEnabled,
-    screenEnabled,
+    cameraEnabled,
     openPanel,
     goodbyeMode,
     isMobile,
     onToggleMic,
-    onToggleScreen,
+    onToggleCamera,
     onGoodbye,
     togglePanel,
     t,
     // RN: 使用本地打包的图标资源（确保这些文件存在于 assets/icons/）
     icons: {
       mic: require('../../../../assets/icons/mic_icon_off.png'),
-      screen: require('../../../../assets/icons/screen_icon_off.png'),
+      camera: require('../../../../assets/icons/screen_icon_off.png'),
       agent: require('../../../../assets/icons/Agent_off.png'),
       settings: require('../../../../assets/icons/set_off.png'),
       goodbye: require('../../../../assets/icons/rest_off.png'),
diff --git a/packages/project-neko-components/src/Live2DRightToolbar/Live2DRightToolbar.tsx b/packages/project-neko-components/src/Live2DRightToolbar/Live2DRightToolbar.tsx
@@ -25,7 +25,7 @@ export function Live2DRightToolbar({
   top,
   isMobile,
   micEnabled,
-  screenEnabled,
+  cameraEnabled,
   goodbyeMode,
   openPanel,
   onOpenPanelChange,
@@ -34,7 +34,7 @@ export function Live2DRightToolbar({
   agent,
   onAgentChange,
   onToggleMic,
-  onToggleScreen,
+  onToggleCamera,
   onGoodbye,
   onReturn,
   onSettingsMenuClick,
@@ -51,12 +51,12 @@ export function Live2DRightToolbar({
   // 使用共享的按钮配置
   const buttons = useToolbarButtons<string>({
     micEnabled,
-    screenEnabled,
+    cameraEnabled,
     openPanel,
     goodbyeMode,
     isMobile,
     onToggleMic,
-    onToggleScreen,
+    onToggleCamera,
     onGoodbye,
     togglePanel,
     t,
diff --git a/packages/project-neko-components/src/Live2DRightToolbar/hooks.ts b/packages/project-neko-components/src/Live2DRightToolbar/hooks.ts
@@ -87,32 +87,32 @@ export function usePanelToggle(
  */
 export function useToolbarButtons<TIcon = ToolbarIcon>({
   micEnabled,
-  screenEnabled,
+  cameraEnabled,
   openPanel,
   goodbyeMode,
   isMobile,
   onToggleMic,
-  onToggleScreen,
+  onToggleCamera,
   onGoodbye,
   togglePanel,
   t,
   iconBasePath = '/static/icons', // Web 使用
   icons, // RN 使用 require() 资源
 }: {
   micEnabled: boolean;
-  screenEnabled: boolean;
+  cameraEnabled: boolean;
   openPanel: Live2DRightToolbarPanel;
   goodbyeMode: boolean;
   isMobile?: boolean;
   onToggleMic: (next: boolean) => void;
-  onToggleScreen: (next: boolean) => void;
+  onToggleCamera: (next: boolean) => void;
   onGoodbye: () => void;
   togglePanel: (panel: Exclude<Live2DRightToolbarPanel, null>) => void;
   t?: TFunction;
   iconBasePath?: string;
   icons?: {
     mic: TIcon;
-    screen: TIcon;
+    camera: TIcon;
     agent: TIcon;
     settings: TIcon;
     goodbye: TIcon;
@@ -130,12 +130,12 @@ export function useToolbarButtons<TIcon = ToolbarIcon>({
           icon: (icons?.mic ?? `${iconBasePath}/mic_icon_off.png`) as TIcon,
         },
         {
-          id: 'screen' as const,
+          id: 'camera' as const,
           title: tOrDefault(t, 'buttons.cameraShare', '摄像头'),
           hidden: false,
-          active: screenEnabled,
-          onClick: () => onToggleScreen(!screenEnabled),
-          icon: (icons?.screen ?? `${iconBasePath}/screen_icon_off.png`) as TIcon,
+          active: cameraEnabled,
+          onClick: () => onToggleCamera(!cameraEnabled),
+          icon: (icons?.camera ?? `${iconBasePath}/screen_icon_off.png`) as TIcon,
         },
         {
           id: 'agent' as const,
@@ -165,7 +165,7 @@ export function useToolbarButtons<TIcon = ToolbarIcon>({
           hasPanel: false,
         },
       ].filter((b) => !b.hidden),
-    [goodbyeMode, isMobile, micEnabled, onGoodbye, onToggleMic, onToggleScreen, openPanel, screenEnabled, t, togglePanel, iconBasePath, icons]
+    [cameraEnabled, goodbyeMode, isMobile, micEnabled, onGoodbye, onToggleCamera, onToggleMic, openPanel, t, togglePanel, iconBasePath, icons]
   );
 }
 
diff --git a/packages/project-neko-components/src/Live2DRightToolbar/types.ts b/packages/project-neko-components/src/Live2DRightToolbar/types.ts
@@ -4,7 +4,7 @@
  * 此文件包含 Web 和 RN 版本共享的所有类型定义
  */
 
-export type Live2DRightToolbarButtonId = "mic" | "screen" | "agent" | "settings" | "goodbye" | "return";
+export type Live2DRightToolbarButtonId = "mic" | "camera" | "agent" | "settings" | "goodbye" | "return";
 
 export type Live2DRightToolbarPanel = "agent" | "settings" | null;
 
@@ -47,7 +47,7 @@ export interface Live2DRightToolbarProps {
   isMobile?: boolean;
 
   micEnabled: boolean;
-  screenEnabled: boolean;
+  cameraEnabled: boolean;
   goodbyeMode: boolean;
 
   openPanel: Live2DRightToolbarPanel;
@@ -60,7 +60,7 @@ export interface Live2DRightToolbarProps {
   onAgentChange: (id: Live2DAgentToggleId, next: boolean) => void;
 
   onToggleMic: (next: boolean) => void;
-  onToggleScreen: (next: boolean) => void;
+  onToggleCamera: (next: boolean) => void;
   onGoodbye: () => void;
   onReturn: () => void;
 
diff --git a/services/CameraStreamService.ts b/services/CameraStreamService.ts
@@ -17,6 +17,11 @@ export interface CameraStreamConfig {
 const yieldToMain = (ms: number = 0): Promise<void> =>
   new Promise(resolve => setTimeout(resolve, ms));
 
+/**
+ * CameraView 刚 ready 时给原生预览一点稳定时间，避免首帧拍照过早失败。
+ */
+const INITIAL_CAPTURE_DELAY_MS = 500;
+
 /**
  * 摄像头流式服务
  * 使用 aggressive yielding 策略避免阻塞 JS 线程
@@ -64,7 +69,7 @@ export class CameraStreamService {
 
     console.log('📹 启动摄像头流');
     this.setStatus('streaming');
-    this.scheduleNextCapture(0);
+    this.scheduleNextCapture(INITIAL_CAPTURE_DELAY_MS);
   }
 
   private scheduleNextCapture(delayMs: number = this.frameInterval) {
@@ -103,7 +108,7 @@ export class CameraStreamService {
     if (this.status !== 'paused') return;
     console.log('📹 恢复摄像头流');
     this.setStatus('streaming');
-    this.scheduleNextCapture(0);
+    this.scheduleNextCapture(INITIAL_CAPTURE_DELAY_MS);
   }
 
   /**
