botrun-horse 2.29.2 → 2.30.0

package/botrun-c/mobile-android/WSL-ANDROID-SETUP.md

@@ -0,0 +1,252 @@
+# 🤖 WSL + Windows Android Studio 設定指南
+
+## 📋 前置需求
+
+### Windows 環境
+- ✅ Windows 10/11
+- ✅ WSL2 已安裝
+- ✅ Android Studio（需在 Windows 上安裝）
+- ✅ JDK 17+（Android Studio 內建或獨立安裝）
+
+---
+
+## 🚀 步驟 1：在 WSL 中建立 Android 專案
+
+### 1.1 進入 mobile-android 目錄
+```bash
+cd /home/bigcookie/github/botrun-c/mobile-android
+```
+
+### 1.2 安裝依賴
+```bash
+npm install
+```
+
+### 1.3 建置 Web 專案（產生靜態檔案）
+```bash
+cd ../web
+npm run build
+cd ../mobile-android
+```
+
+### 1.4 使用 Capacitor CLI 建立 Android 專案
+```bash
+npx cap add android
+```
+
+這個指令會：
+- ✅ 自動建立 `android/` 目錄
+- ✅ 產生完整的 Android 專案結構
+- ✅ 配置 `AndroidManifest.xml`
+- ✅ 設定 Gradle 建置腳本
+
+### 1.5 同步 Web 內容到 Android
+```bash
+npx cap sync android
+```
+
+---
+
+## 🛠️ 步驟 2：設定 Android 錄音權限
+
+### 2.1 編輯 AndroidManifest.xml
+```bash
+nano android/app/src/main/AndroidManifest.xml
+```
+
+### 2.2 在 `<manifest>` 標籤內加入權限
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- 錄音權限 -->
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+
+    <!-- 網路權限（已存在） -->
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <!-- 其他需要的權限（檔案上傳功能） -->
+    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
+    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+
+    <application>
+        ...
+    </application>
+</manifest>
+```
+
+儲存後離開（Ctrl+X, Y, Enter）
+
+---
+
+## 🪟 步驟 3：在 Windows 上開啟 Android Studio
+
+### 3.1 取得 WSL 專案路徑
+在 WSL 中執行：
+```bash
+pwd
+# 輸出: /home/bigcookie/github/botrun-c/mobile-android
+```
+
+### 3.2 轉換為 Windows 路徑
+WSL 路徑轉換規則：
+```
+WSL:     /home/bigcookie/github/botrun-c/mobile-android
+Windows: \\wsl.localhost\Ubuntu\home\bigcookie\github\botrun-c\mobile-android
+```
+
+或使用 `wsl$`（舊版 Windows）：
+```
+\\wsl$\Ubuntu\home\bigcookie\github\botrun-c\mobile-android
+```
+
+### 3.3 在 Windows 上開啟 Android Studio
+
+**方式 1：透過檔案總管**
+1. 按 `Win + R`，輸入：
+   ```
+   \\wsl.localhost\Ubuntu\home\bigcookie\github\botrun-c\mobile-android\android
+   ```
+2. 右鍵點擊 `android` 資料夾 → 選擇「以 Android Studio 開啟」
+
+**方式 2：透過 Android Studio**
+1. 開啟 Android Studio
+2. File → Open
+3. 在路徑列貼上：
+   ```
+   \\wsl.localhost\Ubuntu\home\bigcookie\github\botrun-c\mobile-android\android
+   ```
+4. 點擊「OK」
+
+---
+
+## 📱 步驟 4：在 Android Studio 中設定
+
+### 4.1 Gradle Sync
+首次開啟時會自動執行 Gradle Sync，需要等待 2-5 分鐘：
+- ✅ 下載依賴
+- ✅ 建立索引
+- ✅ 設定專案結構
+
+### 4.2 設定 Firebase（如果需要）
+1. 從 Firebase Console 下載 `google-services.json`
+2. 放到 WSL 路徑：
+   ```bash
+   # 在 WSL 中執行
+   cp ~/Downloads/google-services.json /home/bigcookie/github/botrun-c/mobile-android/android/app/
+   ```
+
+### 4.3 連接 Android 實體裝置
+
+#### USB 偵錯設定
+1. 手機開啟「開發者選項」
+2. 啟用「USB 偵錯」
+3. 用 USB 連接手機到 Windows 電腦
+4. 手機會彈出「允許 USB 偵錯」→ 點「允許」
+
+#### 驗證裝置連接
+在 Android Studio 上方工具列：
+- ✅ 看到你的手機型號（如「Pixel 6」）
+- ✅ 顯示為「Connected」
+
+### 4.4 執行 App
+1. 確認選擇了你的實體裝置
+2. 點擊綠色的 ▶️ **Run** 按鈕
+3. 等待建置完成（首次需要 3-5 分鐘）
+4. App 會自動安裝到手機並啟動
+
+---
+
+## 🧪 步驟 5：測試錄音功能
+
+### 5.1 授予麥克風權限
+首次開啟 App 點擊錄音按鈕時：
+- 系統會彈出「允許 Botrun Agent 錄製音訊嗎？」
+- 點擊「允許」
+
+### 5.2 測試項目
+- [ ] 點擊麥克風按鈕開始錄音
+- [ ] 顯示「🎤 錄音中...」狀態
+- [ ] 說話 10 秒以上
+- [ ] 點擊停止按鈕
+- [ ] 確認自動開始轉錄
+- [ ] 驗證轉錄結果正確顯示
+
+### 5.3 長時間錄音測試
+- [ ] 錄音超過 10 分鐘
+- [ ] 切換到其他 App（背景錄音）
+- [ ] 回到 App，停止錄音
+- [ ] 驗證錄音完整性
+
+---
+
+## 🐛 常見問題
+
+### ❌ 問題 1：Gradle Sync 失敗
+**錯誤訊息**：`Could not resolve all dependencies`
+
+**解決方式**：
+```bash
+# 在 WSL 中清除 Gradle cache
+cd /home/bigcookie/github/botrun-c/mobile-android/android
+./gradlew clean
+./gradlew --refresh-dependencies
+```
+
+### ❌ 問題 2：找不到 Android SDK
+**錯誤訊息**：`Android SDK not found`
+
+**解決方式**：
+1. 在 Android Studio 中：File → Settings → Appearance & Behavior → System Settings → Android SDK
+2. 確認 SDK Location 路徑正確（通常是 `C:\Users\你的使用者名稱\AppData\Local\Android\Sdk`）
+3. 確保已安裝 Android 13 (API 33) 或更新版本
+
+### ❌ 問題 3：ADB 無法連接裝置
+**錯誤訊息**：`device not found` 或 `unauthorized`
+
+**解決方式**：
+```bash
+# 在 Windows PowerShell 中執行
+adb kill-server
+adb start-server
+adb devices
+```
+
+手機上重新點擊「允許 USB 偵錯」
+
+### ❌ 問題 4：WSL 路徑無法存取
+**錯誤訊息**：`Network path not found`
+
+**解決方式**：
+1. 確認 WSL 正在運行（開啟 WSL terminal）
+2. 使用正確的路徑格式：
+   - Windows 11: `\\wsl.localhost\Ubuntu\...`
+   - Windows 10: `\\wsl$\Ubuntu\...`
+3. 如果還是不行，直接在 WSL 中執行：
+   ```bash
+   explorer.exe .
+   ```
+   這會在 Windows 檔案總管中開啟當前目錄
+
+---
+
+## 📚 後續步驟
+
+完成測試後：
+1. ✅ 更新 `TODO-CAPACITOR-INTEGRATION.md`（標記 TODO #8, #9 完成）
+2. ✅ 截圖測試結果
+3. ✅ 記錄任何問題到開發筆記
+4. ✅ 如果需要，繼續完成 TODO #10-#22
+
+---
+
+## 🔗 參考資料
+
+- [Capacitor Android 官方文件](https://capacitorjs.com/docs/android)
+- [WSL 與 Android Studio 整合](https://developer.android.com/studio/run/emulator-acceleration#vm-windows-wsl2)
+- [Android 權限文件](https://developer.android.com/guide/topics/permissions/overview)
+- [Capawesome Audio Recorder](https://capawesome.io/plugins/audio-recorder/)
+
+---
+
+**建立時間**：2025-11-06
+**測試環境**：WSL2 Ubuntu + Windows 11 + Android Studio

package/botrun-c/mobile-android/android/app/build.gradle

@@ -0,0 +1,75 @@
+apply plugin: 'com.android.application'
+
+// Load keystore properties from keystore.properties file
+def keystorePropertiesFile = rootProject.file("keystore.properties")
+def keystoreProperties = new Properties()
+if (keystorePropertiesFile.exists()) {
+    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
+}
+
+android {
+    namespace "ai.botrun.botrunapp"
+    compileSdk rootProject.ext.compileSdkVersion
+    defaultConfig {
+        applicationId "ai.botrun.botrunapp"
+        minSdkVersion rootProject.ext.minSdkVersion
+        targetSdkVersion rootProject.ext.targetSdkVersion
+        versionCode 38
+        versionName "1.6.3"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        aaptOptions {
+             // Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps.
+             // Default: https://android.googlesource.com/platform/frameworks/base/+/282e181b58cf72b6ca770dc7ca5f91f135444502/tools/aapt/AaptAssets.cpp#61
+            ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
+        }
+    }
+
+    // Signing configuration for release builds
+    signingConfigs {
+        release {
+            if (keystorePropertiesFile.exists()) {
+                keyAlias keystoreProperties['keyAlias']
+                keyPassword keystoreProperties['keyPassword']
+                storeFile rootProject.file(keystoreProperties['storeFile'])
+                storePassword keystoreProperties['storePassword']
+            }
+        }
+    }
+
+    buildTypes {
+        release {
+            signingConfig signingConfigs.release
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+}
+
+repositories {
+    flatDir{
+        dirs '../capacitor-cordova-android-plugins/src/main/libs', 'libs'
+    }
+}
+
+dependencies {
+    implementation fileTree(include: ['*.jar'], dir: 'libs')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "androidx.coordinatorlayout:coordinatorlayout:$androidxCoordinatorLayoutVersion"
+    implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion"
+    implementation project(':capacitor-android')
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+    implementation project(':capacitor-cordova-android-plugins')
+}
+
+apply from: 'capacitor.build.gradle'
+
+try {
+    def servicesJSON = file('google-services.json')
+    if (servicesJSON.text) {
+        apply plugin: 'com.google.gms.google-services'
+    }
+} catch(Exception e) {
+    logger.info("google-services.json not found, google-services plugin not applied. Push Notifications won't work")
+}

package/botrun-c/mobile-android/android/app/capacitor.build.gradle

@@ -0,0 +1,31 @@
+// DO NOT EDIT THIS FILE! IT IS GENERATED EACH TIME "capacitor update" IS RUN
+
+android {
+  compileOptions {
+      sourceCompatibility JavaVersion.VERSION_21
+      targetCompatibility JavaVersion.VERSION_21
+  }
+}
+
+apply from: "../capacitor-cordova-android-plugins/cordova.variables.gradle"
+dependencies {
+    implementation project(':capacitor-firebase-authentication')
+    implementation project(':capacitor-app')
+    implementation project(':capacitor-camera')
+    implementation project(':capacitor-filesystem')
+    implementation project(':capacitor-haptics')
+    implementation project(':capacitor-keyboard')
+    implementation project(':capacitor-share')
+    implementation project(':capacitor-status-bar')
+    implementation project(':capawesome-team-capacitor-android-foreground-service')
+    implementation project(':capawesome-team-capacitor-audio-recorder')
+    implementation project(':capawesome-capacitor-app-update')
+    implementation project(':capawesome-capacitor-live-update')
+    implementation project(':capgo-capacitor-navigation-bar')
+
+}
+
+
+if (hasProperty('postBuildExtras')) {
+  postBuildExtras()
+}

package/botrun-c/mobile-android/android/app/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile

package/botrun-c/mobile-android/android/build.gradle

@@ -0,0 +1,29 @@
+// Top-level build file where you can add configuration options common to all sub-projects/modules.
+
+buildscript {
+    
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.2'
+        classpath 'com.google.gms:google-services:4.4.2'
+
+        // NOTE: Do not place your application dependencies here; they belong
+        // in the individual module build.gradle files
+    }
+}
+
+apply from: "variables.gradle"
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+task clean(type: Delete) {
+    delete rootProject.buildDir
+}

package/botrun-c/mobile-android/android/capacitor.settings.gradle

@@ -0,0 +1,42 @@
+// DO NOT EDIT THIS FILE! IT IS GENERATED EACH TIME "capacitor update" IS RUN
+include ':capacitor-android'
+project(':capacitor-android').projectDir = new File('../node_modules/@capacitor/android/capacitor')
+
+include ':capacitor-firebase-authentication'
+project(':capacitor-firebase-authentication').projectDir = new File('../node_modules/@capacitor-firebase/authentication/android')
+
+include ':capacitor-app'
+project(':capacitor-app').projectDir = new File('../node_modules/@capacitor/app/android')
+
+include ':capacitor-camera'
+project(':capacitor-camera').projectDir = new File('../node_modules/@capacitor/camera/android')
+
+include ':capacitor-filesystem'
+project(':capacitor-filesystem').projectDir = new File('../node_modules/@capacitor/filesystem/android')
+
+include ':capacitor-haptics'
+project(':capacitor-haptics').projectDir = new File('../node_modules/@capacitor/haptics/android')
+
+include ':capacitor-keyboard'
+project(':capacitor-keyboard').projectDir = new File('../node_modules/@capacitor/keyboard/android')
+
+include ':capacitor-share'
+project(':capacitor-share').projectDir = new File('../node_modules/@capacitor/share/android')
+
+include ':capacitor-status-bar'
+project(':capacitor-status-bar').projectDir = new File('../node_modules/@capacitor/status-bar/android')
+
+include ':capawesome-team-capacitor-android-foreground-service'
+project(':capawesome-team-capacitor-android-foreground-service').projectDir = new File('../node_modules/@capawesome-team/capacitor-android-foreground-service/android')
+
+include ':capawesome-team-capacitor-audio-recorder'
+project(':capawesome-team-capacitor-audio-recorder').projectDir = new File('../node_modules/@capawesome-team/capacitor-audio-recorder/android')
+
+include ':capawesome-capacitor-app-update'
+project(':capawesome-capacitor-app-update').projectDir = new File('../node_modules/@capawesome/capacitor-app-update/android')
+
+include ':capawesome-capacitor-live-update'
+project(':capawesome-capacitor-live-update').projectDir = new File('../node_modules/@capawesome/capacitor-live-update/android')
+
+include ':capgo-capacitor-navigation-bar'
+project(':capgo-capacitor-navigation-bar').projectDir = new File('../node_modules/@capgo/capacitor-navigation-bar/android')

package/botrun-c/mobile-android/android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-all.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

package/botrun-c/mobile-android/android/gradle.properties

@@ -0,0 +1,22 @@
+# Project-wide Gradle settings.
+
+# IDE (e.g. Android Studio) users:
+# Gradle settings configured through the IDE *will override*
+# any settings specified in this file.
+
+# For more details on how to configure your build environment visit
+# http://www.gradle.org/docs/current/userguide/build_environment.html
+
+# Specifies the JVM arguments used for the daemon process.
+# The setting is particularly useful for tweaking memory settings.
+org.gradle.jvmargs=-Xmx1536m
+
+# When configured, Gradle will run in incubating parallel mode.
+# This option should only be used with decoupled projects. More details, visit
+# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
+# org.gradle.parallel=true
+
+# AndroidX package structure to make it clearer which packages are bundled with the
+# Android operating system, and which are packaged with your app's APK
+# https://developer.android.com/topic/libraries/support-library/androidx-rn
+android.useAndroidX=true