diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..45685cf --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,178 @@ +# Contributing + +Welcome to MBrain! You can contribute by reporting bugs, suggesting features, improving documentation and translations, refining the interface, or developing Android and MCP features. Small fixes can go straight to a pull request. For new capabilities, permission boundaries, or major architectural changes, consider opening an issue first to discuss the use case and approach. + +This guide covers getting the source, running the app locally, validating changes, and submitting contributions. For detailed device testing, see the [development guide](docs/development.md). For interface changes, refer to the [design guidelines](DESIGN.md). + +## Reporting bugs and suggesting features + +Search existing issues before opening a new one, then use the repository's issue templates. + +- Bug reports: include the app version, Android version, device model, reproduction steps, and expected and actual behavior. For Root, Shizuku, or external MCP issues, include the relevant environment and connection method. +- Feature requests: describe the problem, the real-world use case, and why existing features do not meet your needs. +- Screenshots and logs: share only what is needed to investigate the issue. Redact tokens, passwords, private file contents, and sensitive device information. + +## Getting the source and creating a branch + +`dev` is the default development branch. Start all feature, fix, documentation, and workflow changes on a dedicated branch based on the latest `dev`, then submit a pull request targeting `dev`. Do not commit or push directly to `dev` or `main`. + +If you do not have write access, fork `powercess/mbrain` on GitHub, then run the following commands, replacing `YOUR_USERNAME` with your username: + +```bash +git clone https://github.com/YOUR_USERNAME/mbrain.git +cd mbrain +git remote add upstream https://github.com/powercess/mbrain.git +git fetch upstream dev +git switch -c docs/contributing-guide upstream/dev +``` + +Choose a branch name that fits your task, such as `fix/issue-description`, `feat/feature-description`, or `docs/topic`. Branches created by automated agents must use the `agent/` prefix. + +If you have write access, clone the main repository and run `git fetch origin dev` followed by `git switch -c origin/dev`. Before starting a new task, handle any existing local changes so unrelated edits do not enter the branch. + +## Setting up your environment + +Documentation-only changes do not require an Android build environment. For app development, open the repository root in Android Studio and prepare the following tools. The repository's build configuration and CI are the source of truth for versions. + +| Tool | Current requirement | +| --- | --- | +| JDK | 17; point `JAVA_HOME` to its installation directory and select JDK 17 as Android Studio's Gradle JDK | +| Android SDK | Platform 35, Build Tools 35.0.0, and Platform Tools; command-line installation also requires Command-line Tools | +| Android NDK | 28.2.13676358, used to build the bundled frpc | +| Go | 1.26.3, matching CI | +| Python | 3.9 or later, used for frpc builds and repository checks | +| Gradle | Use the included Wrapper (8.13); no separate installation is needed | +| Test device | A physical device or emulator running Android 9.0 (API 28) or later | + +The project uses Kotlin 2.1.20, Android Gradle Plugin 8.13.2, and Jetpack Compose. See the [version catalog](gradle/libs.versions.toml) for dependency versions and [app/build.gradle.kts](app/build.gradle.kts) for app build configuration. + +Install the SDK and NDK through Android Studio's SDK Manager, or run the following after adding `sdkmanager` to your PATH: + +```bash +sdkmanager "platform-tools" "platforms;android-35" "build-tools;35.0.0" "ndk;28.2.13676358" +sdkmanager --licenses +``` + +Set the local SDK path through `ANDROID_HOME` or the root `local.properties` file. Android Studio usually generates this file. If you create it manually, set `sdk.dir`; Windows paths can use forward slashes. Do not commit machine-specific paths or `local.properties`. + +Check that `java -version`, `go version`, and your Python command work. The default Python command is `python` on Windows and `python3` on macOS / Linux. Set `MBRAIN_PYTHON` to use a different Python executable. On macOS / Linux, replace `python` with `python3` in the checks below as needed. + +The first build downloads Gradle, Maven dependencies, a pinned version of the frp source, and Go modules. Gradle automatically invokes `scripts/build_frpc.py` to verify the source and compile frpc for four ABIs. Even if you are only debugging the interface, the first app build requires Go, Python, and the NDK. You do not need to download or commit generated binaries manually. + +## Building, installing, and running + +Run these commands from the repository root. + +**Windows PowerShell:** + +```powershell +.\gradlew.bat :app:assembleDebug +adb devices +.\gradlew.bat :app:installDebug +``` + +**macOS / Linux:** + +```bash +./gradlew :app:assembleDebug +adb devices +./gradlew :app:installDebug +``` + +Enable USB debugging on a physical device and authorize your computer, or start an emulator first. You can also select `app` and the target device in Android Studio and run it there. + +The debug APK is generated at `app/build/outputs/apk/debug/app-debug.apk`. Its fixed package name is `com.powercess.mbrain.dev`, and its launcher label is `MBrain 开发版`, so it can coexist with the release app. Keep this identity across versions; do not override it with version numbers or temporary task names. Local development does not require release signing materials. Reuse your local debug keystore so updates retain the same signing identity. If installation fails because of a signature mismatch, first check the source of the installed test package. Uninstalling it will erase its app data. + +After opening the app, start the gateway from the home screen and open the connection address and credentials section to get the actual address and token. Basic device information does not require Root. Prepare Root or Shizuku and grant MBrain access separately only when testing capabilities that require elevated permissions. + +You can forward the port with ADB and run an MCP smoke test from your computer. This example assumes the app uses the default port, 8765: + +```powershell +adb forward tcp:8765 tcp:8765 +powershell -ExecutionPolicy Bypass -File scripts/smoke-mcp.ps1 +``` + +The script prompts for a token and checks authentication, initialization, tool listing, and a read-only battery query. Adjust the forwarding command if the port differs, and use the script's `-Endpoint` parameter to specify the computer-side address when needed. With multiple devices, use `adb -s `. The script requires PowerShell; with cross-platform PowerShell, run `pwsh -File scripts/smoke-mcp.ps1`. + +See the [development guide](docs/development.md) for further HTTP / stdio, Root, and Shizuku validation, and the [remote access guide](docs/remote-access.md) for tunnel and frpc testing. + +## Finding your way around + +| Directory or file | Purpose | +| --- | --- | +| `app/src/main/` | App source and resources: `ui` handles the interface, `gateway` manages the gateway lifecycle, `mcp` integrates external services, `shell` handles commands and file operations, and `data` manages configuration | +| `app/src/test/` | App JVM unit tests | +| `app/src/androidTest/` | Device tests that require an Android environment | +| `vendor/droid-mcp/` | The pinned upstream foundation and its module tests | +| `scripts/` | Build, source scanning, APK inspection, and integration testing scripts | +| `.github/workflows/` | CI and release workflows | +| `docs/` | Development, feature, and release documentation | + +Keep each contribution focused on a clear problem and follow the organization of nearby code. For behavior fixes, add tests that reproduce the issue. For interface changes, check light and dark themes, enlarged fonts, and editing states, and include relevant screenshots in the pull request. When changing the upstream foundation, retain its licenses and record local changes in [UPSTREAM.md](vendor/droid-mcp/UPSTREAM.md). + +## Validating your changes + +Local checks should cover the behavior you changed. A full Android build is not required for every change. + +| Change scope | Suggested validation | +| --- | --- | +| Documentation and contribution instructions | Check wording, relative links, example commands, and the diff; no Android build is needed | +| Repository scripts and workflows | Run relevant Python tests; validate workflow changes with actionlint and test any changed CI logic | +| App code, dependencies, and build configuration | Run relevant module tests, builds, and lint; verify device behavior on a physical device or emulator | +| MCP, permissions, tunnels, and other integrations | In addition to relevant tests, follow the integration guides to verify connections, failure handling, and resource cleanup after stopping | + +Common Android checks on Windows (replace `.\gradlew.bat` with `./gradlew` on macOS / Linux): + +```powershell +.\gradlew.bat :app:assembleDebug testDebugUnitTest :app:lintDebug +``` + +`testDebugUnitTest` runs JVM tests for configured modules. To validate a single module, specify a task such as `:app:testDebugUnitTest` or `:droid-mcp-core:testDebugUnitTest`. JVM tests do not replace device testing; state the actual devices and scope tested in your pull request. + +Run repository script tests with: + +```bash +python -m unittest discover -s scripts -p 'test_*.py' +``` + +Before committing, stage only files related to your contribution and inspect the staged changes: + +```bash +git add CONTRIBUTING.md +python scripts/check-source.py +git diff --cached --check +git diff --cached --stat +git diff --cached +``` + +Replace the example filename with the files you changed. `check-source.py` scans Git's staging area; unstaged changes are not checked. Do not commit tokens, signing materials, personal paths, private device addresses, APKs, build caches, or debug logs. Local debugging artifacts can go in the ignored `.local-tools/` directory. + +CI continues to report the `build` and `branch-policy` checks. Documentation-only pull requests skip Android setup and builds while still running lightweight checks such as source scanning. Pushes to `dev` / `main`, manual runs, and releases retain full validation. + +## Submitting your contribution + +Commit and pull request titles must use `type: description` or `type(scope): description`, with a space after the colon. Descriptions may be in English or Chinese. For example: + +```text +docs: improve local development instructions +fix(ui): keep the save button visible +feat(mcp): add connection status feedback +``` + +When ready, commit and push your dedicated branch, then open a pull request targeting `powercess/mbrain:dev` on GitHub. If you use a fork, push to your own `origin`. Include: + +- The problem being solved, related issues, and the resulting behavior. +- The checks you actually ran and their results, plus any unverified areas and why they were not tested. +- Screenshots for interface changes, or reproduction and integration testing steps for protocol and device capabilities. + +Continue updating the same branch in response to review feedback. Merge only after required checks pass and branch update requirements are met. Merge and squash commit titles must follow the same format. Do not bypass branch protections. + +Regular contributions do not target `main` or create release tags. Only this repository's `dev` branch may open a release integration pull request targeting `main`. Create version tags only on `main` commits and only when a release is explicitly authorized. See [AGENTS.md](AGENTS.md) and the [development guide](docs/development.md) for detailed rules. + +## Troubleshooting + +- **Gradle uses the wrong Java version:** check both the terminal's `JAVA_HOME` and Android Studio's Gradle JDK, and keep both on JDK 17. +- **SDK, NDK, or Python cannot be found:** verify the SDK path, exact NDK version, and `MBRAIN_PYTHON`. The first bundled frpc build requires the complete toolchain. +- **Initial dependency downloads fail:** check access to the configured dependency repositories, GitHub, and Go module sources. Do not remove source verification to work around download problems. +- **Temporary directory renaming fails on Windows:** wait for file locks to be released, then retry with `--max-workers=1 --no-parallel --no-watch-fs` appended to the Gradle command. +- **A restricted environment cannot write to the default Gradle cache:** set `GRADLE_USER_HOME` to the ignored `.gradle-user-home` directory under the repository. diff --git a/README.fr.md b/README.fr.md new file mode 100644 index 0000000..d4b7479 --- /dev/null +++ b/README.fr.md @@ -0,0 +1,186 @@ +
+ +Logo MBrain + +# MBrain + +**Une passerelle MCP Android pour les agents IA.** + +Informations sur l’appareil · Gestion des applications · Fichiers · Root / Shizuku · Agrégation MCP + +

+ Android 9.0 ou version ultérieure + MCP HTTP + Dernière version +

+ +[简体中文](README.zh_CN.md) | [繁體中文](README.zh_TW.md) | [English](README.md) | **Français** | [日本語](README.ja.md) + +[Démarrage rapide](#démarrage-rapide) · [Connexion d’un agent](#connecter-un-agent-ia) · [Services MCP](#ajouter-des-services-mcp) · [FAQ](#faq) · [Signaler un problème](https://github.com/powercess/mbrain/issues) + +
+ +--- + +MBrain est une passerelle Android pour le Model Context Protocol (MCP). Elle permet aux agents IA de consulter l’état du téléphone, de gérer les applications, de manipuler les fichiers et d’exécuter des commandes. Elle regroupe aussi des services MCP supplémentaires derrière un point d’accès unique. Choisissez les capacités à activer sur votre téléphone et arrêtez la passerelle à tout moment. + +## Aperçu + + + + + + + + +
AccueilCapacitésParamètres
Accueil : outils, services et commande de la passerelleGestion des capacités Root, Shizuku et applicationsParamètres de connexion, apparence et historique
+ +Captures de l’application. Les outils disponibles dépendent des capacités activées et des services connectés. Thèmes clair, sombre et système disponibles. + +## Fonctionnalités + +| Capacité | Utilisation | +| --- | --- | +| **Informations sur l’appareil** | Consulter les caractéristiques, la batterie, le stockage et le réseau | +| **Gestion des applications** | Lister, examiner et lancer les applications ; les accès privilégiés permettent aussi leur installation, désinstallation et arrêt | +| **Commandes et fichiers** | Exécuter des commandes via Root ou Shizuku ; parcourir, lire, écrire, copier et déplacer des fichiers | +| **Agrégation MCP** | Connecter des services HTTP MCP locaux ou gérer des processus stdio MCP | +| **Point d’accès unique** | Rechercher les outils, consulter leur description, copier les paramètres de connexion et voir l’historique récent | +| **Accès distant** | Utiliser le client frpc intégré pour exposer MBrain ou d’autres services du téléphone via des tunnels TCP | + +- **Activation à la demande :** Root et Shizuku disposent de commutateurs et de vérifications d’autorisation séparés. +- **Contrôle immédiat :** démarrez ou arrêtez la passerelle depuis l’accueil ou arrêtez-la depuis la notification persistante. +- **Services personnalisés :** renseignez vos propres noms et configurations, sans dépendre d’une application tierce particulière. + +## Démarrage rapide + +### 1. Installer MBrain + +Nécessite **Android 9.0 ou une version ultérieure**. + +Téléchargez `mbrain-v-universal.apk` depuis [GitHub Releases](https://github.com/powercess/mbrain/releases/latest) et installez-le sur votre appareil Android. L’APK universel prend en charge ARM64, ARM32, x86_64 et x86. + +Chaque publication comprend des notes de version et un fichier de sommes de contrôle `SHA256SUMS.txt`. Pour compiler l’application et utiliser les variantes de développement, consultez le [guide de développement](docs/development.md) (chinois simplifié). + +### 2. Choisir les capacités + +Ouvrez l’onglet **Capacités** : + +- Les informations sur l’appareil ne nécessitent pas Root. +- Activez la gestion des applications selon vos besoins. +- Pour les opérations privilégiées, activez **Root** ou **Shizuku** et accordez les autorisations demandées. + +Root nécessite un appareil rooté et une autorisation accordée à **MBrain lui-même**. Pour Shizuku, installez et démarrez [Shizuku](https://shizuku.rikka.app/). Les deux accès peuvent être activés séparément. + +### 3. Démarrer la passerelle + +Depuis **Accueil**, appuyez sur le bouton de démarrage en bas à droite. Une fois la passerelle en cours d’exécution, ouvrez les **coordonnées et identifiants de connexion** pour copier l’URL MCP et le jeton Bearer. + +## Connecter un agent IA + +Ajoutez un service dans un client prenant en charge **MCP sur HTTP et l’authentification Bearer** : + +| Paramètre | Valeur | +| --- | --- | +| Nom | `MBrain`, ou un nom personnalisé | +| URL MCP | `http://127.0.0.1:8765/mcp` | +| Authentification | Jeton Bearer | +| Jeton | À copier depuis la page des identifiants dans MBrain | + +Pour une configuration par en-tête HTTP : + +```http +Authorization: Bearer +``` + +Les **clients sur le même téléphone** utilisent directement cette adresse. Les **clients sur ordinateur** nécessitent une connexion ADB et une redirection de port : + +```bash +adb forward tcp:8765 tcp:8765 +``` + +Si le port par défaut est occupé, MBrain en choisit un disponible. Utilisez l’adresse et la commande ADB affichées dans l’application. Le jeton est chiffré sur l’appareil, conservé après redémarrage et réinitialisable depuis la page des identifiants. + +Commencez par une requête en lecture seule : + +> Vérifie le niveau de batterie et l’espace de stockage disponible sur ce téléphone. + +## Ajouter des services MCP + +Ouvrez **MCP → Ajouter un service**, puis choisissez : + +| Type | Usage | Configuration | +| --- | --- | --- | +| **Service HTTP** | Une autre application ou un processus exécute déjà le service sur le téléphone | Nom, URL locale, jeton facultatif | +| **Processus géré** | MBrain démarre et gère un service stdio MCP | Nom, exécutable, arguments séparés, identité d’exécution | + +Enregistrez, puis sélectionnez **Connecter le service** dans ses détails. Ses outils rejoignent le catalogue et deviennent accessibles via la même URL MCP. + +Les services HTTP doivent actuellement utiliser une adresse de bouclage. Préparez les exécutables et les environnements nécessaires sur l’appareil avant d’ajouter un processus géré : MBrain n’inclut ni Node.js ni Python. + +## Accès distant + +Le client **frpc** intégré peut rediriger MBrain ou d’autres services du téléphone via un serveur **frps** que vous hébergez. Dans **Paramètres → Accès distant → Configurer le serveur**, saisissez l’adresse, le port et le jeton, puis ajoutez des tunnels TCP. + +Tous les tunnels partagent une configuration de serveur. Chacun dispose de commandes indépendantes de démarrage, d’arrêt et de nouvelle tentative. Les tunnels MCP suivent le cycle de vie de la passerelle ; les tunnels personnalisés fonctionnent indépendamment. Seule la redirection TCP de base est prise en charge. Consultez le [guide d’accès distant](docs/remote-access.md) (chinois simplifié). + +## Autorisations et sécurité + +- La passerelle écoute uniquement sur l’interface de bouclage du téléphone. Utilisez ADB depuis un ordinateur et les tunnels configurés pour l’accès distant. +- Tout client disposant du jeton peut appeler **tous les outils activés**. Les autorisations par client ne sont pas encore prises en charge. +- Les outils Root et Shizuku peuvent modifier réellement l’appareil. Connectez uniquement des clients de confiance et gardez le jeton privé. +- Choisissez les capacités sur le téléphone et arrêtez la passerelle lorsque l’accès n’est plus nécessaire. + +## FAQ + +
+Puis-je utiliser MBrain sans Root ? + +Oui. Les informations sur l’appareil, la consultation et le lancement ordinaires d’applications ainsi que les services HTTP MCP locaux ne nécessitent pas Root. Shizuku offre un autre accès privilégié, dont les possibilités dépendent de son mode de démarrage. + +
+ +
+Pourquoi mon client ne se connecte-t-il pas ? + +Vérifiez que la passerelle fonctionne et que le jeton correspond à celui affiché dans l’application. Sur ordinateur, vérifiez la redirection ADB du port réel. La passerelle écoute uniquement sur l’interface de bouclage ; l’accès distant nécessite un tunnel TCP configuré. + +
+ +
+Pourquoi un outil est-il absent ? + +La liste dépend des capacités activées, des autorisations et des services connectés. Vérifiez les onglets Capacités et MCP, puis actualisez les outils dans votre client. + +
+ +
+Que se passe-t-il lorsque j’arrête la passerelle ? + +MBrain n’accepte plus de requêtes, déconnecte les services MCP externes et termine les processus enfants directement gérés. La passerelle ne démarre pas automatiquement au démarrage du téléphone. L’historique reste uniquement en mémoire. + +
+ +## Contribuer + +Les signalements, suggestions, améliorations de documentation et contributions de code sont les bienvenus. Utilisez les [modèles de tickets](https://github.com/powercess/mbrain/issues/new/choose) en précisant la version et les étapes de reproduction. Masquez les jetons et les informations privées dans les captures et journaux. + +Le [guide de contribution](CONTRIBUTING.md) (anglais) décrit l’installation, la compilation, les vérifications et les pull requests. Créez une branche dédiée à partir du dernier `dev` et ciblez `dev` pour votre pull request. Le [guide de développement](docs/development.md) (chinois simplifié) détaille les tests sur appareil. + +## Remerciements + +- [droid-mcp](https://github.com/stixez/droid-mcp) : base Android MCP utilisée par MBrain, avec conservation de sa [licence Apache-2.0](vendor/droid-mcp/LICENSE) et de son [historique de provenance](vendor/droid-mcp/UPSTREAM.md). +- [Shizuku](https://github.com/RikkaApps/Shizuku) et [libsu](https://github.com/topjohnwu/libsu) : accès privilégiés Android. +- [RikkaHub](https://github.com/rikkahub/rikkahub) : référence pour les listes de paramètres et les interactions. + +## Star History + +Si MBrain vous est utile, vous pouvez soutenir le projet avec une étoile. + + + + + Évolution des étoiles GitHub de MBrain + + +Graphique fourni par Star History. diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 0000000..dacf7d6 --- /dev/null +++ b/README.ja.md @@ -0,0 +1,186 @@ +
+ +MBrain ロゴ + +# MBrain + +**AI エージェントから Android の機能を利用できる MCP ゲートウェイ。** + +端末情報 · アプリ管理 · ファイル操作 · Root / Shizuku · MCP サービスの集約 + +

+ Android 9.0 以降 + HTTP MCP + 最新リリース +

+ +[简体中文](README.zh_CN.md) | [繁體中文](README.zh_TW.md) | [English](README.md) | [Français](README.fr.md) | **日本語** + +[クイックスタート](#クイックスタート) · [エージェントの接続](#ai-エージェントを接続する) · [MCP サービスの追加](#mcp-サービスを追加する) · [よくある質問](#よくある質問) · [問題を報告](https://github.com/powercess/mbrain/issues) + +
+ +--- + +MBrain は、Android 上で動作する Model Context Protocol(MCP)ゲートウェイです。AI エージェントは、単一のエンドポイントを通じて端末情報の取得、アプリ管理、ファイル操作、コマンド実行、外部 MCP サービスの利用を行えます。公開する機能は端末側で選択でき、ゲートウェイはいつでも停止できます。 + +## スクリーンショット + + + + + + + + +
ホーム機能管理設定
ホーム:ツール、サービス、ゲートウェイの起動と停止Root、Shizuku、アプリ管理の機能設定接続情報、外観、実行履歴の設定
+ +実際のアプリ画面です。利用可能なツールは、有効な機能と接続済みサービスによって変わります。ライト、ダーク、システムに合わせるテーマに対応しています。 + +## 主な機能 + +| 機能 | 内容 | +| --- | --- | +| **端末情報** | 端末の詳細、バッテリー、ストレージ、ネットワークの状態を取得 | +| **アプリ管理** | アプリの一覧・詳細の取得と起動。特権アクセスではインストール、アンインストール、停止も可能 | +| **コマンドとファイル** | Root または Shizuku でコマンドを実行し、ファイルの参照、読み書き、コピー、移動を実施 | +| **MCP サービスの集約** | 端末内の HTTP MCP サービスを接続、または stdio MCP プロセスを起動・管理 | +| **単一の接続先** | ツールの検索、説明の確認、接続情報のコピー、最近の実行履歴の確認 | +| **リモートアクセス** | 内蔵 frpc で TCP トンネルを作成し、MBrain や端末内の別サービスへ接続 | + +- **必要な機能だけ有効化:** Root と Shizuku は個別のスイッチと権限確認を備えています。 +- **すぐに停止:** ホームから起動・停止でき、常駐通知からも停止できます。 +- **任意のサービスを追加:** サービス名と設定を指定でき、特定のサードパーティーアプリに依存しません。 + +## クイックスタート + +### 1. MBrain をインストールする + +**Android 9.0 以降**が必要です。 + +[GitHub Releases](https://github.com/powercess/mbrain/releases/latest) から最新の `mbrain-v-universal.apk` をダウンロードし、Android 端末にインストールしてください。ユニバーサル APK は ARM64、ARM32、x86_64、x86 に対応しています。 + +リリースには変更内容とチェックサムファイル `SHA256SUMS.txt` が含まれます。ソースからのビルドや開発版については、[開発ガイド](docs/development.md)(簡体字中国語)をご覧ください。 + +### 2. 公開する機能を選ぶ + +下部の**機能**タブを開きます。 + +- 端末情報の取得には Root は不要です。 +- 必要に応じてアプリ管理を有効にします。 +- 特権操作には **Root** または **Shizuku** を有効にし、権限を許可します。 + +Root を使うには、端末が root 化されており、**MBrain 自体**に権限が付与されている必要があります。Shizuku を使う場合は、先に [Shizuku](https://shizuku.rikka.app/) をインストールして起動してください。両方を同時に有効にする必要はありません。 + +### 3. ゲートウェイを起動する + +**ホーム**の右下にある起動ボタンを押します。起動後、**接続先と認証情報**を開き、MCP URL と Bearer トークンをコピーします。 + +## AI エージェントを接続する + +**HTTP MCP と Bearer 認証**に対応したクライアントでサービスを追加します。 + +| 項目 | 値 | +| --- | --- | +| 名前 | `MBrain`、または任意の名前 | +| MCP URL | `http://127.0.0.1:8765/mcp` | +| 認証方式 | Bearer トークン | +| トークン | MBrain の認証情報画面からコピー | + +HTTP ヘッダーで認証を設定する場合: + +```http +Authorization: Bearer +``` + +**同じ端末上のクライアント**は、この URL をそのまま使えます。**パソコン上のクライアント**は、ADB で端末に接続してポートを転送します。 + +```bash +adb forward tcp:8765 tcp:8765 +``` + +既定のポートが使用中の場合は、空いているポートが選択されます。アプリ内に表示される実際の URL と ADB コマンドを使用してください。トークンは端末上で暗号化して保存され、再起動後も維持されます。認証情報画面からリセットできます。 + +まずは読み取り専用の簡単なリクエストを試してください。 + +> この端末のバッテリー残量とストレージの空き容量を確認してください。 + +## MCP サービスを追加する + +**MCP → サービスを追加**で接続方式を選びます。 + +| 方式 | 用途 | 設定項目 | +| --- | --- | --- | +| **HTTP サービス** | 端末上の別アプリやプロセスですでにサービスが動作している場合 | 名前、ローカル URL、任意のトークン | +| **管理対象プロセス** | MBrain が stdio MCP サービスを起動・管理する場合 | 名前、実行ファイル、個別の引数、実行ユーザー | + +保存後、詳細画面で**サービスに接続**を選択します。接続が成功すると、そのサービスのツールがゲートウェイの一覧に追加され、同じ MCP エンドポイントから利用できます。 + +HTTP サービスは現在、ループバックアドレスのみ対応しています。管理対象プロセスに必要な実行ファイルやランタイムは、事前に端末に用意してください。MBrain に Node.js や Python は含まれていません。 + +## リモートアクセス + +内蔵 **frpc** クライアントを使い、自分で運用する **frps** サーバー経由で MBrain や端末内の別サービスに接続できます。**設定 → リモートアクセス → サーバー設定**でアドレス、ポート、トークンを入力し、TCP トンネルを追加します。 + +すべてのトンネルは同じサーバー設定を共有します。トンネルごとに起動、停止、再試行が可能です。MCP トンネルはゲートウェイの起動・停止に連動し、カスタムサービスのトンネルは独立して動作します。現在は基本的な TCP 転送のみ対応しています。[リモートアクセスガイド](docs/remote-access.md)(簡体字中国語)で設定例と動作を確認できます。 + +## 権限とセキュリティ + +- ゲートウェイは端末のループバックインターフェースだけで待ち受けます。パソコンからは ADB 転送、遠隔地からは設定済みトンネルを利用します。 +- Bearer トークンを持つクライアントは、**有効なすべてのツール**を呼び出せます。クライアントごとの権限設定には未対応です。 +- Root や Shizuku のツールは端末を実際に変更できます。信頼できるクライアントだけを接続し、トークンを共有しないでください。 +- 公開する機能は端末で選び、不要になったらゲートウェイを停止してください。 + +## よくある質問 + +
+Root なしでも使えますか? + +はい。端末情報の取得、通常のアプリ情報の取得・起動、ローカル HTTP MCP サービスの接続には Root は不要です。特権操作には Shizuku も使えますが、操作できる範囲は起動方法によって異なります。 + +
+ +
+クライアントが接続できません。 + +ゲートウェイが起動していることと、認証情報画面のトークンを使っていることを確認してください。パソコンからの場合は、実際のポートへの ADB 転送も確認します。待ち受けはループバックのみのため、リモート接続には設定済みの TCP トンネルが必要です。 + +
+ +
+必要なツールが見つかりません。 + +ツール一覧は、機能スイッチ、権限、外部サービスの接続状態で変わります。機能タブと MCP タブを確認し、クライアント側で一覧を更新してください。 + +
+ +
+ゲートウェイを停止するとどうなりますか? + +リクエストの受付と外部 MCP サービスへの接続を停止し、直接管理している子プロセスを終了します。端末の起動時にゲートウェイが自動起動することはありません。実行履歴は現在、メモリ内だけに保持されます。 + +
+ +## コントリビューション + +不具合報告、機能提案、ドキュメント改善、コードの貢献を歓迎します。[Issue テンプレート](https://github.com/powercess/mbrain/issues/new/choose)を使い、バージョンと再現手順を記載してください。スクリーンショットやログからトークンと個人情報を取り除いてください。 + +環境構築、ビルド、検証、プルリクエストの流れは[貢献ガイド](CONTRIBUTING.md)(英語)を参照してください。最新の `dev` から専用ブランチを作り、プルリクエストの対象は `dev` にしてください。端末でのテストは[開発ガイド](docs/development.md)(簡体字中国語)に記載しています。 + +## 謝辞 + +- [droid-mcp](https://github.com/stixez/droid-mcp):MBrain が使用する Android MCP の基盤。[Apache-2.0 ライセンス](vendor/droid-mcp/LICENSE)と[由来の記録](vendor/droid-mcp/UPSTREAM.md)を保持しています。 +- [Shizuku](https://github.com/RikkaApps/Shizuku) と [libsu](https://github.com/topjohnwu/libsu):Android の特権アクセス。 +- [RikkaHub](https://github.com/rikkahub/rikkahub):設定リストと操作設計の参考。 + +## Star History + +MBrain が役に立ったら、ぜひスターで応援してください。 + + + + + MBrain の GitHub スター数の推移 + + +グラフ提供:Star History。 diff --git a/README.md b/README.md index 01385af..81be4c2 100644 --- a/README.md +++ b/README.md @@ -4,180 +4,187 @@ # MBrain -**让 AI Agent 调用你的 Android 手机能力。** +**An Android MCP gateway for AI agent device control.** -设备信息 · 应用管理 · 文件操作 · Root / Shizuku · MCP 服务聚合 +Device information · App management · File operations · Root / Shizuku · MCP service aggregation

- Android 9.0 及以上 + Android 9.0 or later HTTP MCP - 最新版本 + Latest release

-[快速上手](#快速上手) · [连接 Agent](#连接-agent) · [接入 MCP 服务](#接入-mcp-服务) · [常见问题](#常见问题) · [反馈问题](https://github.com/powercess/mbrain/issues) +[简体中文](README.zh_CN.md) | [繁體中文](README.zh_TW.md) | **English** | [Français](README.fr.md) | [日本語](README.ja.md) + +[Quick start](#quick-start) · [Connect an agent](#connect-an-ai-agent) · [Add MCP services](#add-mcp-services) · [FAQ](#faq) · [Report an issue](https://github.com/powercess/mbrain/issues) --- -MBrain 是运行在 Android 上的 MCP 网关。它把手机自身的能力和你接入的 MCP 服务汇集到一个入口,让支持 MCP 的 AI 客户端读取设备状态、管理应用、操作文件或执行命令。你可以在手机上选择开放哪些能力,并随时停止服务。 +MBrain is an Android gateway for the Model Context Protocol (MCP) that lets AI agents access device information, manage apps, operate files, execute commands, and connect to additional MCP services through one unified endpoint. Enable only the capabilities you need and stop the gateway at any time. -## 界面预览 +## Screenshots - - - + + + - - - + + +
首页能力管理设置HomeCapabilitiesSettings
首页:工具与服务概览,右下角悬浮启停按钮能力管理:按需启用 Root、Shizuku 和应用管理设置:连接凭据、外观和运行记录Home screen with tools, services, and gateway controlCapability management for Root, Shizuku, and appsSettings for credentials, appearance, and runtime logs
-应用实际运行截图。可用工具数量取决于已启用能力和接入服务;支持浅色、深色及跟随系统。 +Screenshots from the running app. Available tools depend on enabled capabilities and connected services. Light, dark, and system themes are supported. -## 可以做什么 +## Features -| 能力 | 用途 | +| Capability | What it provides | | --- | --- | -| **读取设备状态** | 查看设备信息、电量、存储空间和网络状态 | -| **管理应用** | 查看应用列表与详情、启动应用;高权限通道还可安装、卸载和停止应用 | -| **执行命令与操作文件** | 通过 Root 或 Shizuku 执行命令,浏览、读取、写入、复制和移动文件 | -| **接入其他 MCP 服务** | 添加手机本机的 HTTP MCP 服务,或由 MBrain 启动和管理 stdio MCP 进程 | -| **统一管理与连接** | 一个 MCP 地址提供工具目录,支持搜索工具、查看说明、复制连接信息和查看近期运行记录 | -| **内网穿透** | 内置 frpc,统一配置一台服务器,多条基础 TCP 隧道转发 MBrain 或手机其他服务 | +| **Device information** | Read device details, battery, storage, and network status | +| **App management** | List, inspect, and launch apps; privileged channels can also install, uninstall, and stop apps | +| **Commands and files** | Run commands through Root or Shizuku and browse, read, write, copy, or move files | +| **MCP service aggregation** | Add local HTTP MCP services or let MBrain manage stdio MCP processes | +| **One endpoint** | Expose one searchable tool catalog with connection details and recent run history | +| **Remote access** | Use the built-in frpc client to forward MBrain or other phone services through TCP tunnels | -- **按需启用**:Root 和 Shizuku 各用一个开关,打开时自动检查并申请权限。 -- **随时停止**:首页右下角一键启停,也可从前台通知停止网关。 -- **服务自由添加**:填写自己的服务名称与配置,不绑定特定第三方应用。 +- **Opt-in capabilities:** Root and Shizuku have separate switches and permission checks. +- **One-tap control:** Start or stop the gateway from Home or the foreground notification. +- **Bring your own services:** Add service names and configurations without being tied to a specific third-party app. -## 快速上手 +## Quick start -### 1. 安装 MBrain +### 1. Install MBrain -需要 **Android 9.0 或更高版本**。 +Requires **Android 9.0 or later**. -从 [GitHub Releases](https://github.com/powercess/mbrain/releases/latest) 下载最新版本的 `mbrain-v版本号-universal.apk`,在 Android 设备上打开并安装。通用安装包覆盖 ARM64、ARM32、x86_64 和 x86,无需挑选架构。 +Download the latest `mbrain-v-universal.apk` from [GitHub Releases](https://github.com/powercess/mbrain/releases/latest) and install it on your Android device. The universal APK supports ARM64, ARM32, x86_64, and x86. -发行页面提供更新说明和 `SHA256SUMS.txt` 校验文件。自行构建及开发测试版说明见[开发指南](docs/development.md)。 +Releases include notes and a `SHA256SUMS.txt` checksum file. See the [development guide](docs/development.md) for local builds and development variants. -### 2. 选择需要开放的能力 +### 2. Choose capabilities -打开底部的 **能力** 页面: +Open the **Capabilities** tab: -- 设备信息不需要 Root。 -- 按需启用应用管理。 -- 需要高权限操作时,进入 **Root** 或 **Shizuku**,打开启用开关,并完成授权。 +- Device information does not require Root. +- Enable app management when needed. +- For privileged operations, enable **Root** or **Shizuku** and complete authorization. -使用 Root 需要设备具备 Root 能力,并允许 **MBrain 本身**获取权限。使用 Shizuku 则需先安装并启动 [Shizuku](https://shizuku.rikka.app/)。两种通道可以分别启用,不需要同时开启。 +Root requires a rooted device and permission granted to **MBrain itself**. Shizuku requires [Shizuku](https://shizuku.rikka.app/) to be installed and running. The two channels can be enabled independently. -### 3. 启动网关 +### 3. Start the gateway -回到 **首页**,点击右下角的启动按钮。显示“运行中”后,打开 **连接地址与凭据**,获取 MCP 地址和 Bearer Token。 +Return to **Home**, tap the start button, then open **Connection details and credentials** to copy the MCP URL and Bearer token. -## 连接 Agent +## Connect an AI agent -在支持 **HTTP MCP 和 Bearer 认证**的客户端中添加服务: +Add MBrain to a client that supports **HTTP MCP and Bearer authentication**: -| 配置项 | 填写内容 | +| Setting | Value | | --- | --- | -| 名称 | `MBrain`,也可自行命名 | -| MCP 地址 | `http://127.0.0.1:8765/mcp` | -| 认证方式 | Bearer Token | -| Token | 从 MBrain 的“连接地址与凭据”页面复制 | +| Name | `MBrain`, or a name of your choice | +| MCP URL | `http://127.0.0.1:8765/mcp` | +| Authentication | Bearer token | +| Token | Copy from the app's connection credentials page | -如果客户端通过请求头配置认证,填写: +For clients configured through request headers: ```http -Authorization: Bearer <从 MBrain 复制的 Token> +Authorization: Bearer ``` -**同一台手机上的客户端**可以直接使用上述地址。 - -**电脑上的客户端**需要先通过 ADB 连接手机,再转发端口: +**Clients on the same phone** can use the URL directly. **Desktop clients** need an ADB connection and port forwarding: ```bash adb forward tcp:8765 tcp:8765 ``` -默认端口被占用时,网关会自动使用空闲端口。请以“连接地址与凭据”中的实际地址及“使用说明”中的 ADB 命令为准。Token 加密保存在设备上,重启后保持不变;可在凭据页重置。 +If the default port is occupied, MBrain chooses an available port. Use the actual URL and ADB command shown in the app. The token is encrypted on the device, persists across restarts, and can be reset from the credentials page. + +Try a simple read-only request: -**远程客户端**可在“设置 → 内网穿透”配置一台自建 frps,再添加 TCP 隧道。每条隧道独立启停与重试;MCP 隧道跟随网关,自定义服务隧道独立运行。具体见[内网穿透指南](docs/remote-access.md)。 +> Check this phone's battery level and available storage. -连接后可以先让 Agent 执行一个简单的只读请求: +## Add MCP services -> 查看这台手机的电量和剩余存储空间。 +Open **MCP → Add service** and choose a connection type: -> **权限说明**:当前持有 Token 的客户端可以调用全部已启用工具,尚不支持为不同客户端单独分配权限。Root / Shizuku 工具能够执行实际修改,请只连接可信客户端,不要分享 Token。 +| Type | Use case | Configuration | +| --- | --- | --- | +| **HTTP service** | Another app or process already runs the service on the phone | Name, local URL, optional token | +| **Managed process** | MBrain starts and manages a stdio MCP process | Name, executable, individual arguments, execution identity | -## 接入 MCP 服务 +Save the configuration and select **Connect service** in its details. Connected tools join the gateway's catalog and are available through the same MCP endpoint. -需要从公网连接时,可进入 **设置 → 内网穿透 → 配置服务器** 填写 frps 地址、端口和 Token。当前仅支持基础 TCP 转发,所有隧道共用一台服务器。配置示例与运行规则见[内网穿透指南](docs/remote-access.md)。 +HTTP services currently require loopback addresses. Prepare executables and runtimes on the device before adding managed processes; MBrain does not bundle Node.js or Python. -进入 **MCP → 添加服务**,选择连接方式: +## Remote access -| 方式 | 适用情况 | 需要填写 | -| --- | --- | --- | -| **HTTP 服务** | 服务已经由手机上的其他应用或进程启动 | 名称、本机服务地址、可选 Token | -| **托管进程** | 希望由 MBrain 启动并管理 stdio MCP 服务 | 名称、程序、逐项启动参数、执行身份 | +The built-in **frpc** client can forward MBrain or other phone services through a self-hosted **frps** server. Open **Settings → Remote access → Configure server**, enter the server address, port, and token, then add TCP tunnels. + +All tunnels share one server configuration. Each tunnel has independent start, stop, and retry controls. MCP tunnels follow the gateway lifecycle; custom service tunnels run independently. Only basic TCP forwarding is supported. See the [remote access guide](docs/remote-access.md) (Simplified Chinese) for configuration and operating rules. -保存配置后,在服务详情中点击 **连接服务**。成功连接后,该服务的工具会加入 MBrain 的工具目录,Agent 可以通过同一个入口调用。 +## Permissions and security -HTTP 服务目前只支持回环地址。托管进程所需的程序和运行环境需要事先在设备上准备好,MBrain 不内置 Node.js 或 Python。 +- The gateway listens only on the phone's loopback interface. Desktop access uses ADB forwarding; remote access uses configured tunnels. +- Any client with the Bearer token can call **all enabled tools**. Per-client permissions are not currently supported. +- Root and Shizuku tools can make real changes to the device. Connect trusted clients and keep the token private. +- Choose capabilities on the phone and stop the gateway whenever access is no longer needed. -## 常见问题 +## FAQ
-没有 Root,能使用吗? +Can I use MBrain without Root? -可以。设备信息、普通应用查询与启动、本机 HTTP MCP 接入不依赖 Root。需要更高权限时,可以使用 Shizuku;实际操作范围取决于它的启动方式。 +Yes. Device information, ordinary app queries and launching, and local HTTP MCP services do not require Root. Shizuku provides another channel for privileged operations; its capabilities depend on how it was started.
-为什么客户端连接不上? +Why can't my client connect? -先确认首页显示“运行中”,并使用凭据页中的 Token。电脑连接时还需确认实际端口的 ADB 转发成功。网关仅监听手机回环地址;远程访问通过已配置的 TCP 隧道连接。 +Check that the gateway is running and the token matches the credentials page. For desktop access, verify ADB forwarding for the actual port. The gateway listens only on loopback; remote connections require a configured TCP tunnel.
-为什么找不到某个工具? +Why is a tool missing? -工具数量随能力开关、权限状态和外部服务连接情况变化。先在能力页检查开关,再到 MCP 页检查服务状态,最后在客户端重新获取工具列表。 +Available tools depend on capability switches, permissions, and external service connections. Check Capabilities and MCP service status, then refresh the tool list in your client.
-停止服务后会发生什么? +What happens when I stop the gateway? -网关停止接收请求,断开外部 MCP 连接,并清理直接托管的子进程。应用不会在开机后自动启动网关;运行记录目前仅保留在内存中。 +MBrain stops accepting requests, disconnects external MCP services, and cleans up directly managed child processes. It does not automatically start the gateway at boot. Run history is currently kept only in memory.
-## 反馈与参与 +## Contributing -遇到问题或有功能建议,欢迎通过 [Issue 模板](https://github.com/powercess/mbrain/issues/new/choose)反馈。描述问题时请附上版本和复现步骤;截图或日志中请隐去 Token 与私人信息。 +Bug reports, feature suggestions, documentation improvements, and code contributions are welcome. Use the [issue templates](https://github.com/powercess/mbrain/issues/new/choose) and include the app version and reproduction steps. Remove tokens and private information from screenshots and logs. -欢迎通过 Pull Request 改进项目。请从默认分支 `dev` 创建功能分支,再提交 PR 到 `dev`;`dev` 和 `main` 均不接受直接推送。发布时由 `dev` 提交 PR 到 `main`,版本 tag 触发正式发布。构建与测试说明见[开发指南](docs/development.md)。 +Read the [contributing guide](CONTRIBUTING.md) for setup, building, validation, and the pull request workflow. Start from the latest `dev` on a dedicated branch and target `dev` in your pull request. The [development guide](docs/development.md) (Simplified Chinese) covers device testing. -## 致谢 +## Acknowledgements -- [droid-mcp](https://github.com/stixez/droid-mcp):MBrain 使用的 Android MCP 基座,保留其 [Apache-2.0 许可证](vendor/droid-mcp/LICENSE)和[来源记录](vendor/droid-mcp/UPSTREAM.md)。 -- [Shizuku](https://github.com/RikkaApps/Shizuku) 与 [libsu](https://github.com/topjohnwu/libsu):Android 高权限能力接入。 -- [RikkaHub](https://github.com/rikkahub/rikkahub):设置列表与交互设计参考。 +- [droid-mcp](https://github.com/stixez/droid-mcp): the Android MCP foundation used by MBrain, with its [Apache-2.0 license](vendor/droid-mcp/LICENSE) and [upstream record](vendor/droid-mcp/UPSTREAM.md) retained. +- [Shizuku](https://github.com/RikkaApps/Shizuku) and [libsu](https://github.com/topjohnwu/libsu): Android privileged access. +- [RikkaHub](https://github.com/rikkahub/rikkahub): settings list and interaction design reference. ## Star History -如果 MBrain 对你有帮助,欢迎点一个 Star。 +If MBrain is useful to you, consider giving it a star. - MBrain 的 GitHub Star 增长趋势 + MBrain GitHub star history -Star 趋势由 Star History 提供。 +Chart provided by Star History. diff --git a/README.zh_CN.md b/README.zh_CN.md new file mode 100644 index 0000000..8d3e730 --- /dev/null +++ b/README.zh_CN.md @@ -0,0 +1,193 @@ +
+ +MBrain Logo + +# MBrain + +**让 AI Agent 调用你的 Android 手机能力。** + +设备信息 · 应用管理 · 文件操作 · Root / Shizuku · MCP 服务聚合 + +

+ Android 9.0 及以上 + HTTP MCP + 最新版本 +

+ +**简体中文** | [繁體中文](README.zh_TW.md) | [English](README.md) | [Français](README.fr.md) | [日本語](README.ja.md) + +[快速上手](#快速上手) · [连接 Agent](#连接-agent) · [接入 MCP 服务](#接入-mcp-服务) · [常见问题](#常见问题) · [反馈问题](https://github.com/powercess/mbrain/issues) + +
+ +--- + +MBrain 是运行在 Android 上的 Model Context Protocol(MCP)网关。它把手机自身的能力和你接入的 MCP 服务汇集到一个入口,让支持 MCP 的 AI 客户端读取设备状态、管理应用、操作文件或执行命令。你可以在手机上选择开放哪些能力,并随时停止服务。 + +## 界面预览 + + + + + + + + + + + + +
首页能力管理设置
首页:工具与服务概览,右下角悬浮启停按钮能力管理:按需启用 Root、Shizuku 和应用管理设置:连接凭据、外观和运行记录
+ +应用实际运行截图。可用工具数量取决于已启用能力和接入服务;支持浅色、深色及跟随系统。 + +## 可以做什么 + +| 能力 | 用途 | +| --- | --- | +| **读取设备状态** | 查看设备信息、电量、存储空间和网络状态 | +| **管理应用** | 查看应用列表与详情、启动应用;高权限通道还可安装、卸载和停止应用 | +| **执行命令与操作文件** | 通过 Root 或 Shizuku 执行命令,浏览、读取、写入、复制和移动文件 | +| **接入其他 MCP 服务** | 添加手机本机的 HTTP MCP 服务,或由 MBrain 启动和管理 stdio MCP 进程 | +| **统一管理与连接** | 一个 MCP 地址提供工具目录,支持搜索工具、查看说明、复制连接信息和查看近期运行记录 | +| **内网穿透** | 内置 frpc,统一配置一台服务器,多条基础 TCP 隧道转发 MBrain 或手机其他服务 | + +- **按需启用**:Root 和 Shizuku 各用一个开关,打开时自动检查并申请权限。 +- **随时停止**:首页右下角一键启停,也可从前台通知停止网关。 +- **服务自由添加**:填写自己的服务名称与配置,不绑定特定第三方应用。 + +## 快速上手 + +### 1. 安装 MBrain + +需要 **Android 9.0 或更高版本**。 + +从 [GitHub Releases](https://github.com/powercess/mbrain/releases/latest) 下载最新版本的 `mbrain-v版本号-universal.apk`,在 Android 设备上打开并安装。通用安装包覆盖 ARM64、ARM32、x86_64 和 x86,无需挑选架构。 + +发行页面提供更新说明和 `SHA256SUMS.txt` 校验文件。自行构建及开发测试版说明见[开发指南](docs/development.md)。 + +### 2. 选择需要开放的能力 + +打开底部的 **能力** 页面: + +- 设备信息不需要 Root。 +- 按需启用应用管理。 +- 需要高权限操作时,进入 **Root** 或 **Shizuku**,打开启用开关,并完成授权。 + +使用 Root 需要设备具备 Root 能力,并允许 **MBrain 本身**获取权限。使用 Shizuku 则需先安装并启动 [Shizuku](https://shizuku.rikka.app/)。两种通道可以分别启用,不需要同时开启。 + +### 3. 启动网关 + +回到 **首页**,点击右下角的启动按钮。显示“运行中”后,打开 **连接地址与凭据**,获取 MCP 地址和 Bearer Token。 + +## 连接 Agent + +在支持 **HTTP MCP 和 Bearer 认证**的客户端中添加服务: + +| 配置项 | 填写内容 | +| --- | --- | +| 名称 | `MBrain`,也可自行命名 | +| MCP 地址 | `http://127.0.0.1:8765/mcp` | +| 认证方式 | Bearer Token | +| Token | 从 MBrain 的“连接地址与凭据”页面复制 | + +如果客户端通过请求头配置认证,填写: + +```http +Authorization: Bearer <从 MBrain 复制的 Token> +``` + +**同一台手机上的客户端**可以直接使用上述地址。 + +**电脑上的客户端**需要先通过 ADB 连接手机,再转发端口: + +```bash +adb forward tcp:8765 tcp:8765 +``` + +默认端口被占用时,网关会自动使用空闲端口。请以“连接地址与凭据”中的实际地址及“使用说明”中的 ADB 命令为准。Token 加密保存在设备上,重启后保持不变;可在凭据页重置。 + +连接后可以先让 Agent 执行一个简单的只读请求: + +> 查看这台手机的电量和剩余存储空间。 + +## 接入 MCP 服务 + +进入 **MCP → 添加服务**,选择连接方式: + +| 方式 | 适用情况 | 需要填写 | +| --- | --- | --- | +| **HTTP 服务** | 服务已经由手机上的其他应用或进程启动 | 名称、本机服务地址、可选 Token | +| **托管进程** | 希望由 MBrain 启动并管理 stdio MCP 服务 | 名称、程序、逐项启动参数、执行身份 | + +保存配置后,在服务详情中点击 **连接服务**。成功连接后,该服务的工具会加入 MBrain 的工具目录,Agent 可以通过同一个入口调用。 + +HTTP 服务目前只支持回环地址。托管进程所需的程序和运行环境需要事先在设备上准备好,MBrain 不内置 Node.js 或 Python。 + +## 远程访问 + +内置 **frpc** 客户端,可通过自建 **frps** 服务器转发 MBrain 或手机上的其他服务。进入 **设置 → 内网穿透 → 配置服务器**,填写服务器地址、端口和 Token,再添加 TCP 隧道。 + +当前仅支持基础 TCP 转发,所有隧道共用一台服务器。每条隧道独立启停与重试;MCP 隧道跟随网关,自定义服务隧道独立运行。配置示例与运行规则见[内网穿透指南](docs/remote-access.md)。 + +## 权限与安全 + +- 网关仅监听手机回环地址。电脑通过 ADB 转发连接,远程访问通过已配置的隧道连接。 +- 持有 Bearer Token 的客户端可以调用**全部已启用工具**,尚不支持为不同客户端单独分配权限。 +- Root / Shizuku 工具能够执行实际修改,请只连接可信客户端,不要分享 Token。 +- 在手机上选择开放的能力,不再需要时随时停止网关。 + +## 常见问题 + +
+没有 Root,能使用吗? + +可以。设备信息、普通应用查询与启动、本机 HTTP MCP 接入不依赖 Root。需要更高权限时,可以使用 Shizuku;实际操作范围取决于它的启动方式。 + +
+ +
+为什么客户端连接不上? + +先确认首页显示“运行中”,并使用凭据页中的 Token。电脑连接时还需确认实际端口的 ADB 转发成功。网关仅监听手机回环地址;远程访问通过已配置的 TCP 隧道连接。 + +
+ +
+为什么找不到某个工具? + +工具数量随能力开关、权限状态和外部服务连接情况变化。先在能力页检查开关,再到 MCP 页检查服务状态,最后在客户端重新获取工具列表。 + +
+ +
+停止服务后会发生什么? + +网关停止接收请求,断开外部 MCP 连接,并清理直接托管的子进程。应用不会在开机后自动启动网关;运行记录目前仅保留在内存中。 + +
+ +## 反馈与参与 + +遇到问题或有功能建议,欢迎通过 [Issue 模板](https://github.com/powercess/mbrain/issues/new/choose)反馈。描述问题时请附上版本和复现步骤;截图或日志中请隐去 Token 与私人信息。 + +欢迎提交问题报告、改进文档或贡献代码。请阅读[贡献指南](CONTRIBUTING.md)(英文),了解本地环境、构建运行、验证及拉取请求流程。基于最新 `dev` 创建独立分支,并将拉取请求提交到 `dev`。详细设备测试步骤见[开发指南](docs/development.md)。 + +## 致谢 + +- [droid-mcp](https://github.com/stixez/droid-mcp):MBrain 使用的 Android MCP 基座,保留其 [Apache-2.0 许可证](vendor/droid-mcp/LICENSE)和[来源记录](vendor/droid-mcp/UPSTREAM.md)。 +- [Shizuku](https://github.com/RikkaApps/Shizuku) 与 [libsu](https://github.com/topjohnwu/libsu):Android 高权限能力接入。 +- [RikkaHub](https://github.com/rikkahub/rikkahub):设置列表与交互设计参考。 + +## Star History + +如果 MBrain 对你有帮助,欢迎点一个 Star。 + + + + + MBrain 的 GitHub Star 增长趋势 + + +Star 趋势由 Star History 提供。 + diff --git a/README.zh_TW.md b/README.zh_TW.md new file mode 100644 index 0000000..e782211 --- /dev/null +++ b/README.zh_TW.md @@ -0,0 +1,194 @@ +
+ +MBrain Logo + +# MBrain + +**讓 AI Agent 調用你的 Android 手機能力。** + +設備資訊 · 應用管理 · 檔案操作 · Root / Shizuku · MCP 服務聚合 + +

+ Android 9.0 及以上 + HTTP MCP + 最新版本 +

+ +[简体中文](README.zh_CN.md) | **繁體中文** | [English](README.md) | [Français](README.fr.md) | [日本語](README.ja.md) + +[快速上手](#快速上手) · [連接 Agent](#連接-agent) · [接入 MCP 服務](#接入-mcp-服務) · [常見問題](#常見問題) · [反饋問題](https://github.com/powercess/mbrain/issues) + +
+ +--- + +MBrain 是執行在 Android 上的 Model Context Protocol(MCP)閘道。它把手機自身的能力和你接入的 MCP 服務匯集到一個入口,讓支持 MCP 的 AI 用戶端讀取設備狀態、管理應用、操作檔案或執行命令。你可以在手機上選擇開放哪些能力,并隨時停止服務。 + +## 界面預覽 + + + + + + + + + + + + +
首頁能力管理設定
首頁:工具與服務概覽,右下角懸浮啟停按鈕能力管理:按需啟用 Root、Shizuku 和應用管理設定:連接憑據、外觀和執行記錄
+ +應用實際執行截圖。可用工具數量取決于已啟用能力和接入服務;支持淺色、深色及跟隨系統。 + +## 可以做什么 + +| 能力 | 用途 | +| --- | --- | +| **讀取設備狀態** | 查看設備資訊、電量、儲存空間和網絡狀態 | +| **管理應用** | 查看應用列表與詳情、啟動應用;高權限通道還可安裝、卸載和停止應用 | +| **執行命令與操作檔案** | 通過 Root 或 Shizuku 執行命令,瀏覽、讀取、寫入、復制和移動檔案 | +| **接入其他 MCP 服務** | 添加手機本機的 HTTP MCP 服務,或由 MBrain 啟動和管理 stdio MCP 程序 | +| **統一管理與連接** | 一個 MCP 地址提供工具目錄,支持搜索工具、查看說明、復制連接資訊和查看近期執行記錄 | +| **內網穿透** | 內置 frpc,統一設定一臺伺服器,多條基礎 TCP 隧道轉發 MBrain 或手機其他服務 | + +- **按需啟用**:Root 和 Shizuku 各用一個開關,打開時自動檢查并申請權限。 +- **隨時停止**:首頁右下角一鍵啟停,也可從前臺通知停止閘道。 +- **服務自由添加**:填寫自己的服務名稱與設定,不綁定特定第三方應用。 + +## 快速上手 + +### 1. 安裝 MBrain + +需要 **Android 9.0 或更高版本**。 + +從 [GitHub Releases](https://github.com/powercess/mbrain/releases/latest) 下載最新版本的 `mbrain-v版本號-universal.apk`,在 Android 設備上打開并安裝。通用安裝包覆蓋 ARM64、ARM32、x86_64 和 x86,無需挑選架構。 + +發行頁面提供更新說明和 `SHA256SUMS.txt` 校驗檔案。自行構建及開發測試版說明見[開發指南](docs/development.md)。 + +### 2. 選擇需要開放的能力 + +打開底部的 **能力** 頁面: + +- 設備資訊不需要 Root。 +- 按需啟用應用管理。 +- 需要高權限操作時,進入 **Root** 或 **Shizuku**,打開啟用開關,并完成授權。 + +使用 Root 需要設備具備 Root 能力,并允許 **MBrain 本身**獲取權限。使用 Shizuku 則需先安裝并啟動 [Shizuku](https://shizuku.rikka.app/)。兩種通道可以分別啟用,不需要同時開啟。 + +### 3. 啟動閘道 + +回到 **首頁**,點擊右下角的啟動按鈕。顯示“執行中”后,打開 **連接地址與憑據**,獲取 MCP 地址和 Bearer Token。 + +## 連接 Agent + +在支持 **HTTP MCP 和 Bearer 認證**的用戶端中添加服務: + +| 設定項 | 填寫內容 | +| --- | --- | +| 名稱 | `MBrain`,也可自行命名 | +| MCP 地址 | `http://127.0.0.1:8765/mcp` | +| 認證方式 | Bearer Token | +| Token | 從 MBrain 的“連接地址與憑據”頁面復制 | + +如果用戶端通過請求頭設定認證,填寫: + +```http +Authorization: Bearer <從 MBrain 復制的 Token> +``` + +**同一臺手機上的用戶端**可以直接使用上述地址。 + +**電腦上的用戶端**需要先通過 ADB 連接手機,再轉發連接埠: + +```bash +adb forward tcp:8765 tcp:8765 +``` + +默認連接埠被占用時,閘道會自動使用空閑連接埠。請以“連接地址與憑據”中的實際地址及“使用說明”中的 ADB 命令為準。Token 加密保存在設備上,重啟后保持不變;可在憑據頁重置。 + +連接后可以先讓 Agent 執行一個簡單的只讀請求: + +> 查看這臺手機的電量和剩余儲存空間。 + +## 接入 MCP 服務 + +進入 **MCP → 添加服務**,選擇連接方式: + +| 方式 | 適用情況 | 需要填寫 | +| --- | --- | --- | +| **HTTP 服務** | 服務已經由手機上的其他應用或程序啟動 | 名稱、本機服務地址、可選 Token | +| **托管程序** | 希望由 MBrain 啟動并管理 stdio MCP 服務 | 名稱、程序、逐項啟動參數、執行身份 | + +保存設定后,在服務詳情中點擊 **連接服務**。成功連接后,該服務的工具會加入 MBrain 的工具目錄,Agent 可以通過同一個入口調用。 + +HTTP 服務目前只支持回環地址。托管程序所需的程序和執行環境需要事先在設備上準備好,MBrain 不內置 Node.js 或 Python。 + +## 遠程訪問 + +內置 **frpc** 用戶端,可通過自建 **frps** 伺服器轉發 MBrain 或手機上的其他服務。進入 **設定 → 內網穿透 → 設定伺服器**,填寫伺服器地址、連接埠和 Token,再添加 TCP 隧道。 + +當前僅支持基礎 TCP 轉發,所有隧道共用一臺伺服器。每條隧道獨立啟停與重試;MCP 隧道跟隨閘道,自定義服務隧道獨立執行。設定示例與執行規則見[內網穿透指南](docs/remote-access.md)。 + +## 權限與安全 + +- 閘道僅監聽手機回環地址。電腦通過 ADB 轉發連接,遠程訪問通過已設定的隧道連接。 +- 持有 Bearer Token 的用戶端可以調用**全部已啟用工具**,尚不支持為不同用戶端單獨分配權限。 +- Root / Shizuku 工具能夠執行實際修改,請只連接可信用戶端,不要分享 Token。 +- 在手機上選擇開放的能力,不再需要時隨時停止閘道。 + +## 常見問題 + +
+沒有 Root,能使用嗎? + +可以。設備資訊、普通應用查詢與啟動、本機 HTTP MCP 接入不依賴 Root。需要更高權限時,可以使用 Shizuku;實際操作范圍取決于它的啟動方式。 + +
+ +
+為什么用戶端連接不上? + +先確認首頁顯示“執行中”,并使用憑據頁中的 Token。電腦連接時還需確認實際連接埠的 ADB 轉發成功。閘道僅監聽手機回環地址;遠程訪問通過已設定的 TCP 隧道連接。 + +
+ +
+為什么找不到某個工具? + +工具數量隨能力開關、權限狀態和外部服務連接情況變化。先在能力頁檢查開關,再到 MCP 頁檢查服務狀態,最后在用戶端重新獲取工具列表。 + +
+ +
+停止服務后會發生什么? + +閘道停止接收請求,斷開外部 MCP 連接,并清理直接托管的子程序。應用不會在開機后自動啟動閘道;執行記錄目前僅保留在記憶體中。 + +
+ +## 反饋與參與 + +遇到問題或有功能建議,歡迎通過 [Issue 模板](https://github.com/powercess/mbrain/issues/new/choose)反饋。描述問題時請附上版本和復現步驟;截圖或日志中請隱去 Token 與私人資訊。 + +歡迎提交問題報告、改進文檔或貢獻代碼。請閱讀[貢獻指南](CONTRIBUTING.md)(英文),了解本地環境、構建執行、驗證及拉取請求流程。基于最新 `dev` 創建獨立分支,并將拉取請求提交到 `dev`。詳細設備測試步驟見[開發指南](docs/development.md)。 + +## 致謝 + +- [droid-mcp](https://github.com/stixez/droid-mcp):MBrain 使用的 Android MCP 基座,保留其 [Apache-2.0 許可證](vendor/droid-mcp/LICENSE)和[來源記錄](vendor/droid-mcp/UPSTREAM.md)。 +- [Shizuku](https://github.com/RikkaApps/Shizuku) 與 [libsu](https://github.com/topjohnwu/libsu):Android 高權限能力接入。 +- [RikkaHub](https://github.com/rikkahub/rikkahub):設定列表與交互設計參考。 + +## Star History + +如果 MBrain 對你有幫助,歡迎點一個 Star。 + + + + + MBrain 的 GitHub Star 增長趨勢 + + +Star 趨勢由 Star History 提供。 + + diff --git a/app/build.gradle.kts b/app/build.gradle.kts index c8bd12e..27c2427 100644 --- a/app/build.gradle.kts +++ b/app/build.gradle.kts @@ -10,17 +10,20 @@ android { compileSdk = libs.versions.compileSdk.get().toInt() defaultConfig { applicationId = "com.powercess.mbrain" + manifestPlaceholders["appLabel"] = "MBrain" minSdk = libs.versions.minSdk.get().toInt() targetSdk = libs.versions.targetSdk.get().toInt() - versionCode = 4 - versionName = "0.2.0" + versionCode = 5 + versionName = "0.3.0" testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" } buildFeatures { compose = true; buildConfig = true } buildTypes { getByName("debug") { - applicationIdSuffix = ".debug" - versionNameSuffix = "-debug" + // Stable development identity across versions; never use per-release suffixes. + applicationIdSuffix = ".dev" + versionNameSuffix = "-dev" + manifestPlaceholders["appLabel"] = "MBrain 开发版" } } compileOptions { diff --git a/app/src/androidTest/java/com/powercess/mbrain/control/ClipboardDeviceSmoke.java b/app/src/androidTest/java/com/powercess/mbrain/control/ClipboardDeviceSmoke.java new file mode 100644 index 0000000..354feb1 --- /dev/null +++ b/app/src/androidTest/java/com/powercess/mbrain/control/ClipboardDeviceSmoke.java @@ -0,0 +1,48 @@ +package com.powercess.mbrain.control; + +import android.content.ClipData; +import android.os.IBinder; +import java.lang.reflect.Method; +import org.json.JSONObject; + +/** Keeps the original ClipData exclusively in device RAM. Never serializes or prints it. */ +public final class ClipboardDeviceSmoke { + public static void run() throws Exception { + if (android.os.Looper.getMainLooper() == null) android.os.Looper.prepareMainLooper(); + IBinder binder = (IBinder) Class.forName("android.os.ServiceManager").getMethod("getService", String.class).invoke(null, "clipboard"); + Object service = Class.forName("android.content.IClipboard$Stub").getMethod("asInterface", IBinder.class).invoke(null, binder); + int user = (Integer) Class.forName("android.app.ActivityManager").getMethod("getCurrentUser").invoke(null); + Method getter = method("getPrimaryClip"), setter = method("setPrimaryClip"), clear = method("clearPrimaryClip"); + ClipData original = (ClipData) getter.invoke(service, arguments(getter, user, null)); + // Invoke production code locally: only pass/fail ever crosses ADB. + Method operation = PhoneControlMain.class.getDeclaredMethod("clipboard", String.class, JSONObject.class); + operation.setAccessible(true); + PhoneControlMain helper = new PhoneControlMain(); + String expected = "MBrain 中文😀 clipboard QA"; + try { + operation.invoke(helper, "clipboard_set", new JSONObject().put("value", expected)); + JSONObject reply = (JSONObject) operation.invoke(helper, "clipboard_get", new JSONObject()); + if (!expected.equals(reply.optString("text"))) throw new IllegalStateException("Clipboard roundtrip mismatch"); + System.out.println("PASS clipboard Unicode roundtrip (device-local)"); + } finally { + if (original != null) setter.invoke(service, arguments(setter, user, original)); + else clear.invoke(service, arguments(clear, user, null)); + } + } + private static Method method(String name) throws Exception { + for (Method method : Class.forName("android.content.IClipboard").getMethods()) if (method.getName().equals(name)) return method; + throw new NoSuchMethodException(name); + } + private static Object[] arguments(Method method, int user, ClipData clip) { + Object[] result = new Object[method.getParameterCount()]; + int strings = 0, ints = 0; + for (int i = 0; i < result.length; i++) { + Class type = method.getParameterTypes()[i]; + if (type == String.class) result[i] = strings++ == 0 ? "com.android.shell" : null; + else if (type == int.class) result[i] = ints++ == 0 ? user : 0; + else if (type == ClipData.class) result[i] = clip; + else throw new IllegalStateException("Unknown clipboard signature"); + } + return result; + } +} diff --git a/app/src/androidTest/kotlin/com/powercess/mbrain/control/CapabilityGatewayTest.kt b/app/src/androidTest/kotlin/com/powercess/mbrain/control/CapabilityGatewayTest.kt new file mode 100644 index 0000000..8618f5f --- /dev/null +++ b/app/src/androidTest/kotlin/com/powercess/mbrain/control/CapabilityGatewayTest.kt @@ -0,0 +1,89 @@ +package com.powercess.mbrain.control + +import android.content.Intent +import androidx.test.ext.junit.runners.AndroidJUnit4 +import androidx.test.platform.app.InstrumentationRegistry +import com.powercess.mbrain.MainActivity +import com.powercess.mbrain.gateway.GatewayRuntime +import com.powercess.mbrain.gateway.MBrainService +import kotlinx.serialization.json.* +import org.junit.Assert.* +import org.junit.Assume.assumeTrue +import org.junit.Test +import org.junit.runner.RunWith +import java.net.HttpURLConnection +import java.net.URL + +/** Opt-in real Shizuku + authenticated MCP test. Credentials never leave the device. */ +@RunWith(AndroidJUnit4::class) +class CapabilityGatewayTest { + @Test fun shizukuToolsAreCallableThroughAuthenticatedGateway() { + assumeTrue("Enable with -e capabilityGateway true after granting test app Shizuku", + InstrumentationRegistry.getArguments().getString("capabilityGateway") == "true") + val instrumentation = InstrumentationRegistry.getInstrumentation() + val context = instrumentation.targetContext + require(context.packageName == "com.powercess.mbrain.dev") + val activity = instrumentation.startActivitySync(Intent(context, MainActivity::class.java).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)) + try { + await { GatewayRuntime.status.value.shizukuReady } + assertTrue("Enable Shizuku in the test app first", GatewayRuntime.config.value.shizukuEnabled) + instrumentation.runOnMainSync { context.startForegroundService(Intent(context, MBrainService::class.java)) } + await { GatewayRuntime.status.value.running && GatewayRuntime.status.value.tools.any { it.name == "shizuku_ui_dump" } } + val status = GatewayRuntime.status.value + var session: String? = null + var id = 0 + fun rpc(method: String, params: JsonObject): JsonObject { + val connection = URL(status.endpoint).openConnection() as HttpURLConnection + try { + connection.requestMethod = "POST" + connection.doOutput = true + connection.connectTimeout = 5000 + connection.readTimeout = 30000 + connection.setRequestProperty("Authorization", "Bearer ${status.token}") + connection.setRequestProperty("Content-Type", "application/json") + connection.setRequestProperty("Accept", "application/json, text/event-stream") + session?.let { connection.setRequestProperty("Mcp-Session-Id", it) } + val body = buildJsonObject { put("jsonrpc", "2.0"); put("id", ++id); put("method", method); put("params", params) } + connection.outputStream.use { it.write(body.toString().toByteArray()) } + assertEquals("HTTP status for $method", 200, connection.responseCode) + connection.getHeaderField("Mcp-Session-Id")?.let { session = it } + val response = Json.parseToJsonElement(connection.inputStream.bufferedReader().use { it.readText() }).jsonObject + assertFalse("RPC error for $method", response.containsKey("error")) + return response.getValue("result").jsonObject + } finally { connection.disconnect() } + } + rpc("initialize", buildJsonObject { + put("protocolVersion", "2024-11-05"); put("capabilities", buildJsonObject {}) + put("clientInfo", buildJsonObject { put("name", "capability-device-test"); put("version", "1") }) + }) + val names = rpc("tools/list", buildJsonObject {}).getValue("tools").jsonArray.map { it.jsonObject.getValue("name").jsonPrimitive.content } + val required = listOf("ui_dump", "ui_click", "ui_long_click", "ui_set_text", "ui_swipe", "ui_navigate", "ui_wait", "clipboard_get", "clipboard_set", + "logs_query", "appops_get", "appops_set", "proc_list", "app_resource_usage", "net_status", "net_diagnose") + required.forEach { assertTrue("Missing tool $it", "shizuku_$it" in names) } + fun call(name: String, params: JsonObject = buildJsonObject {}) { + val result = rpc("tools/call", buildJsonObject { put("name", "shizuku_$name"); put("arguments", params) }) + assertNotEquals("Tool failed: $name", true, result["isError"]?.jsonPrimitive?.booleanOrNull) + assertTrue("Missing tool content: $name", result.getValue("content").jsonArray.isNotEmpty()) + } + call("ui_dump", buildJsonObject { put("limit", 5) }) + call("ui_wait", buildJsonObject { put("text", "MBrain"); put("package", context.packageName); put("timeout_ms", 2000) }) + call("logs_query", buildJsonObject { put("tag", "MBrainSmoke"); put("lines", 5) }) + call("appops_get", buildJsonObject { put("package", context.packageName); put("op", "VIBRATE") }) + call("proc_list", buildJsonObject { put("package", context.packageName) }) + call("app_resource_usage", buildJsonObject { put("package", context.packageName) }) + call("net_status") + call("net_diagnose", buildJsonObject { put("host", "localhost"); put("port", status.port!!) }) + call("ui_click", buildJsonObject { put("text", "能力"); put("package", context.packageName) }) + call("ui_wait", buildJsonObject { put("text", "手机能力"); put("timeout_ms", 2000) }) + } finally { + instrumentation.runOnMainSync { context.stopService(Intent(context, MBrainService::class.java)); activity.finish() } + } + } + private fun await(condition: () -> Boolean) { + val deadline = android.os.SystemClock.uptimeMillis() + 10000 + while (!condition()) { + check(android.os.SystemClock.uptimeMillis() < deadline) { "Gateway/Shizuku did not become ready" } + Thread.sleep(100) + } + } +} diff --git a/app/src/androidTest/kotlin/com/powercess/mbrain/control/CapabilitySmokeMain.kt b/app/src/androidTest/kotlin/com/powercess/mbrain/control/CapabilitySmokeMain.kt new file mode 100644 index 0000000..911c449 --- /dev/null +++ b/app/src/androidTest/kotlin/com/powercess/mbrain/control/CapabilitySmokeMain.kt @@ -0,0 +1,57 @@ +package com.powercess.mbrain.control + +import com.powercess.mbrain.shell.DiagnosticTools +import io.droidmcp.shell.ShellBackend +import io.droidmcp.shell.ShellResult +import kotlinx.coroutines.runBlocking + +/** Device-only smoke entry point. Run via app_process with app + test APKs on CLASSPATH. */ +object CapabilitySmokeMain { + @JvmStatic fun main(args: Array) = runBlocking { + try { + require(args.size == 2) { "Usage: APK_PATH TEST_PACKAGE" } + val shell = object : ShellBackend { + override val name = "device-shell" + override fun isAvailable() = true + override suspend fun exec(command: String, args: List): ShellResult { + val process = ProcessBuilder(listOf(command) + args).start() + var stderr = "" + val reader = Thread { stderr = process.errorStream.bufferedReader().use { it.readText() } }.apply { start() } + val stdout = process.inputStream.use { it.readBytes() } + val exit = process.waitFor() + reader.join() + return ShellResult(exit, stdout, stderr) + } + } + val diagnostic = DiagnosticTools.all(shell).associateBy { it.name } + suspend fun checkCall(name: String, params: Map = emptyMap()) { + val result = diagnostic.getValue(name).execute(params) + check(result.isSuccess) { "$name: ${result.errorMessage}" } + println("PASS $name") + } + checkCall("logs_query", mapOf("lines" to 5, "tag" to "MBrainSmoke")) + checkCall("appops_get", mapOf("package" to args[1], "op" to "VIBRATE")) + // Dedicated test package only; preserve the original mode on-device. + val before = shell.exec("cmd", listOf("appops", "get", args[1], "VIBRATE")).stdout + val mode = Regex("VIBRATE: (allow|ignore|deny|default|foreground)").find(before)?.groupValues?.get(1) ?: "default" + try { checkCall("appops_set", mapOf("package" to args[1], "op" to "VIBRATE", "mode" to "ignore")) } + finally { shell.exec("cmd", listOf("appops", "set", args[1], "VIBRATE", mode)) } + checkCall("proc_list", mapOf("package" to args[1])) + checkCall("app_resource_usage", mapOf("package" to args[1])) + checkCall("net_status") + val network = PhoneTools.all(shell, args[0]).first { it.name == "net_diagnose" } + val result = network.execute(mapOf("host" to "localhost", "port" to 1)) + check(result.isSuccess) + check((result.data!!["dns"] as Map<*, *>)["ok"] == true) + check((result.data!!["tcp"] as Map<*, *>)["ok"] == false) + println("PASS net_diagnose DNS success and TCP failure") + ClipboardDeviceSmoke.run() + println("CAPABILITY_SMOKE_OK") + System.exit(0) + } catch (failure: Throwable) { + // Do not print tool payloads: logs and clipboard can contain private data. + System.err.println("CAPABILITY_SMOKE_FAILED: ${failure.javaClass.simpleName}: ${failure.message}") + System.exit(1) + } + } +} diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 3b74617..e2ee40e 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -1,6 +1,6 @@ - connectionType = Class.forName("android.app.IUiAutomationConnection"); + Object connection = Class.forName("android.app.UiAutomationConnection").getConstructor().newInstance(); + automation = UiAutomation.class.getConstructor(Looper.class, connectionType) + .newInstance(callbacks.getLooper(), connection); + UiAutomation.class.getMethod("connect", int.class).invoke(automation, + UiAutomation.FLAG_DONT_SUPPRESS_ACCESSIBILITY_SERVICES); + AccessibilityServiceInfo info = automation.getServiceInfo(); + info.flags |= AccessibilityServiceInfo.FLAG_REPORT_VIEW_IDS + | AccessibilityServiceInfo.FLAG_INCLUDE_NOT_IMPORTANT_VIEWS; + automation.setServiceInfo(info); + } + + private JSONObject control(String operation, JSONObject params) throws Exception { + connect(); + switch (operation) { + case "ui_dump": return dump(params); + case "ui_wait": return waitFor(params); + case "ui_click": case "ui_long_click": case "ui_set_text": return nodeAction(operation, params); + case "ui_swipe": return swipe(params); + case "ui_navigate": { + String action = params.getString("action"); + int code; + switch (action) { + case "back": code = AccessibilityService.GLOBAL_ACTION_BACK; break; + case "home": code = AccessibilityService.GLOBAL_ACTION_HOME; break; + case "recents": code = AccessibilityService.GLOBAL_ACTION_RECENTS; break; + case "notifications": code = AccessibilityService.GLOBAL_ACTION_NOTIFICATIONS; break; + case "quick_settings": code = AccessibilityService.GLOBAL_ACTION_QUICK_SETTINGS; break; + default: throw new IllegalArgumentException("Unknown navigation action"); + } + if (!automation.performGlobalAction(code)) throw new IllegalStateException("Navigation rejected"); + return new JSONObject().put("performed", true).put("action", action); + } + default: throw new IllegalArgumentException("Unknown operation: " + operation); + } + } + + private static final class Node { + final AccessibilityNodeInfo info; + final int parent; + Node(AccessibilityNodeInfo info, int parent) { this.info = info; this.parent = parent; } + } + + private static final class UiUnavailable extends IllegalStateException { + UiUnavailable() { super("ui_unavailable: No active window; unlock the device and retry"); } + } + + private List snapshot() { + AccessibilityNodeInfo root = automation.getRootInActiveWindow(); + // Connection registration can finish before the active window is published. + long deadline = SystemClock.uptimeMillis() + 1000; + while (root == null && SystemClock.uptimeMillis() < deadline) { + SystemClock.sleep(100); + root = automation.getRootInActiveWindow(); + } + if (root == null) throw new UiUnavailable(); + List nodes = new ArrayList<>(); + nodes.add(new Node(root, -1)); + for (int i = 0; i < nodes.size() && nodes.size() < MAX_NODES; i++) { + AccessibilityNodeInfo node = nodes.get(i).info; + for (int child = 0; child < node.getChildCount() && nodes.size() < MAX_NODES; child++) { + AccessibilityNodeInfo next = node.getChild(child); + if (next != null) nodes.add(new Node(next, i)); + } + } + return nodes; + } + + private static void recycle(List nodes) { + for (Node node : nodes) node.info.recycle(); + } + + private JSONObject describe(Node item, int index) throws Exception { + AccessibilityNodeInfo node = item.info; + Rect bounds = new Rect(); node.getBoundsInScreen(bounds); + return new JSONObject().put("index", index).put("parent", item.parent) + .put("text", node.isPassword() ? "" : bounded(node.getText())) + .put("description", bounded(node.getContentDescription())) + .put("resource_id", value(node.getViewIdResourceName())) + .put("class", value(node.getClassName())).put("package", value(node.getPackageName())) + .put("bounds", new JSONArray(new int[]{bounds.left, bounds.top, bounds.right, bounds.bottom})) + .put("clickable", node.isClickable()).put("long_clickable", node.isLongClickable()) + .put("editable", node.isEditable()).put("scrollable", node.isScrollable()) + .put("enabled", node.isEnabled()).put("visible", node.isVisibleToUser()) + .put("focused", node.isFocused()).put("password", node.isPassword()); + } + + private JSONObject dump(JSONObject params) throws Exception { + List nodes = snapshot(); + try { + int limit = integer(params, "limit", 50, 1, 60); + int offset = integer(params, "offset", 0, 0, MAX_NODES - 1); + JSONArray result = new JSONArray(); + int end = Math.min(nodes.size(), offset + limit); + for (int i = offset; i < end; i++) result.put(describe(nodes.get(i), i)); + return new JSONObject().put("nodes", result).put("count", nodes.size()) + .put("next_offset", end < nodes.size() ? end : JSONObject.NULL) + .put("truncated", nodes.size() == MAX_NODES) + .put("note", "Indices describe this snapshot only. Select actions by text/resource_id/description."); + } finally { recycle(nodes); } + } + + private List matches(List nodes, JSONObject params) throws Exception { + if (!params.has("text") && !params.has("resource_id") && !params.has("description")) + throw new IllegalArgumentException("Supply text, resource_id or description selector"); + List result = new ArrayList<>(); + for (int i = 0; i < nodes.size(); i++) { + AccessibilityNodeInfo node = nodes.get(i).info; + if (!node.isVisibleToUser()) continue; + if (params.has("text") && (node.isPassword() || !match(value(node.getText()), params.getString("text"), params.optBoolean("contains", false)))) continue; + if (params.has("resource_id") && !value(node.getViewIdResourceName()).equals(params.getString("resource_id"))) continue; + if (params.has("description") && !match(value(node.getContentDescription()), params.getString("description"), params.optBoolean("contains", false))) continue; + if (params.has("package") && !value(node.getPackageName()).equals(params.getString("package"))) continue; + result.add(i); + } + return result; + } + + private static boolean match(String actual, String expected, boolean contains) { + return contains ? actual.contains(expected) : actual.equals(expected); + } + + private JSONObject nodeAction(String operation, JSONObject params) throws Exception { + if (params.has("x") || params.has("y")) { + if (operation.equals("ui_set_text")) throw new IllegalArgumentException("Text input requires a node selector"); + for (String key : new String[]{"text", "resource_id", "description", "package", "index", "contains"}) { + if (params.has(key)) throw new IllegalArgumentException("Use coordinates OR a selector"); + } + int x = integer(params, "x", -1, 0, 20000), y = integer(params, "y", -1, 0, 20000); + gesture(x, y, x, y, operation.equals("ui_long_click") ? 800 : 70); + return new JSONObject().put("performed", true); + } + List nodes = snapshot(); + try { + List found = matches(nodes, params); + if (found.isEmpty()) throw new IllegalStateException("node_not_found"); + if (found.size() > 1 && !params.has("index")) throw new IllegalArgumentException("ambiguous_selector: " + found.size() + " matches; supply zero-based index"); + int index = integer(params, "index", 0, 0, found.size() - 1); + int position = found.get(index); + AccessibilityNodeInfo target = nodes.get(position).info; + int action = operation.equals("ui_set_text") ? AccessibilityNodeInfo.ACTION_SET_TEXT + : operation.equals("ui_long_click") ? AccessibilityNodeInfo.ACTION_LONG_CLICK : AccessibilityNodeInfo.ACTION_CLICK; + while (position >= 0 && !(operation.equals("ui_set_text") ? target.isEditable() + : operation.equals("ui_long_click") ? target.isLongClickable() : target.isClickable())) { + position = nodes.get(position).parent; + if (position >= 0) target = nodes.get(position).info; + } + if (position < 0) throw new IllegalStateException("No actionable ancestor for " + operation); + if (!target.isEnabled()) throw new IllegalStateException("Target is disabled"); + Bundle args = new Bundle(); + if (operation.equals("ui_set_text")) { + String content = params.getString("value"); + if (content.length() > 16000) throw new IllegalArgumentException("Text exceeds 16000 characters"); + args.putCharSequence(AccessibilityNodeInfo.ACTION_ARGUMENT_SET_TEXT_CHARSEQUENCE, content); + } + if (!target.performAction(action, args)) throw new IllegalStateException("action_rejected: Refresh ui_dump and retry with another selector"); + return new JSONObject().put("performed", true).put("matched_count", found.size()); + } finally { recycle(nodes); } + } + + private JSONObject waitFor(JSONObject params) throws Exception { + int timeout = integer(params, "timeout_ms", 5000, 0, 15000); + String state = params.optString("state", "present"); + if (!state.equals("present") && !state.equals("absent")) throw new IllegalArgumentException("state must be present or absent"); + long start = SystemClock.uptimeMillis(); + do { + List nodes = null; + try { + nodes = snapshot(); + List found = matches(nodes, params); + if (state.equals("absent") == found.isEmpty()) { + JSONObject result = new JSONObject().put("matched", true).put("state", state) + .put("elapsed_ms", SystemClock.uptimeMillis() - start); + if (!found.isEmpty()) result.put("node", describe(nodes.get(found.get(0)), found.get(0))); + return result; + } + } catch (UiUnavailable unavailable) { + // During activity transitions there may briefly be no root. This is not + // evidence of an absent selector; continue until a real tree or timeout. + } finally { if (nodes != null) recycle(nodes); } + if (SystemClock.uptimeMillis() - start >= timeout) break; + SystemClock.sleep(Math.min(250, timeout - (SystemClock.uptimeMillis() - start))); + } while (true); + throw new IllegalStateException("wait_timeout: condition not met after " + timeout + "ms"); + } + + private JSONObject swipe(JSONObject params) throws Exception { + gesture(integer(params, "x1", -1, 0, 20000), integer(params, "y1", -1, 0, 20000), + integer(params, "x2", -1, 0, 20000), integer(params, "y2", -1, 0, 20000), + integer(params, "duration_ms", 350, 50, 3000)); + return new JSONObject().put("performed", true); + } + + private void gesture(int x1, int y1, int x2, int y2, int duration) throws Exception { + // Default display only; use current real display dimensions (including system bars). + Object manager = Class.forName("android.hardware.display.DisplayManagerGlobal").getMethod("getInstance").invoke(null); + android.view.Display display = (android.view.Display) manager.getClass().getMethod("getRealDisplay", int.class).invoke(manager, 0); + android.graphics.Point size = new android.graphics.Point(); display.getRealSize(size); + if (x1 >= size.x || x2 >= size.x || y1 >= size.y || y2 >= size.y) throw new IllegalArgumentException("Coordinates outside " + size.x + "x" + size.y); + long down = SystemClock.uptimeMillis(); + inject(down, MotionEvent.ACTION_DOWN, x1, y1); + boolean completed = false; + try { + int steps = Math.max(1, duration / 16); + for (int step = 1; step <= steps; step++) { + long delay = down + (long) duration * step / steps - SystemClock.uptimeMillis(); + if (delay > 0) SystemClock.sleep(delay); + float fraction = (float) step / steps; + if (x1 != x2 || y1 != y2) inject(down, MotionEvent.ACTION_MOVE, x1 + (x2 - x1) * fraction, y1 + (y2 - y1) * fraction); + } + inject(down, MotionEvent.ACTION_UP, x2, y2); + completed = true; + } finally { + if (!completed) inject(down, MotionEvent.ACTION_CANCEL, x2, y2); + } + } + + private void inject(long down, int action, float x, float y) { + MotionEvent event = MotionEvent.obtain(down, SystemClock.uptimeMillis(), action, x, y, 0); + event.setSource(InputDevice.SOURCE_TOUCHSCREEN); + try { if (!automation.injectInputEvent(event, true)) throw new IllegalStateException("Input injection rejected"); } + finally { event.recycle(); } + } + + private JSONObject clipboard(String operation, JSONObject params) throws Exception { + if (!operation.equals("clipboard_get") && !operation.equals("clipboard_set")) throw new IllegalArgumentException("Unknown clipboard operation"); + IBinder binder = (IBinder) Class.forName("android.os.ServiceManager").getMethod("getService", String.class).invoke(null, "clipboard"); + Object service = Class.forName("android.content.IClipboard$Stub").getMethod("asInterface", IBinder.class).invoke(null, binder); + String methodName = operation.equals("clipboard_get") ? "getPrimaryClip" : "setPrimaryClip"; + Method selected = null; + for (Method method : Class.forName("android.content.IClipboard").getMethods()) { + if (method.getName().equals(methodName)) { selected = method; break; } + } + if (selected == null) throw new UnsupportedOperationException("Clipboard interface unavailable"); + int user = (Integer) Class.forName("android.app.ActivityManager").getMethod("getCurrentUser").invoke(null); + Object[] args = new Object[selected.getParameterCount()]; + int strings = 0, ints = 0; + for (int i = 0; i < args.length; i++) { + Class type = selected.getParameterTypes()[i]; + if (type == String.class) args[i] = strings++ == 0 ? "com.android.shell" : null; + else if (type == int.class) args[i] = ints++ == 0 ? user : 0; + else if (type == ClipData.class) { + String text = params.getString("value"); + if (text.length() > 16000) throw new IllegalArgumentException("Clipboard exceeds 16000 characters"); + args[i] = ClipData.newPlainText("MBrain", text); + } else throw new UnsupportedOperationException("Unsupported clipboard signature"); + } + Object result = selected.invoke(service, args); + if (operation.equals("clipboard_set")) return new JSONObject().put("written", true); + ClipData clip = (ClipData) result; + if (clip == null) return new JSONObject().put("available", false).put("text", JSONObject.NULL) + .put("note", "Clipboard is empty or access was denied by the system"); + CharSequence text = clip.getItemCount() > 0 ? clip.getItemAt(0).getText() : null; + if (text == null) return new JSONObject().put("available", true).put("text", JSONObject.NULL).put("item_count", clip.getItemCount()); + String content = text.toString(); + return new JSONObject().put("available", true).put("text", content.substring(0, Math.min(16000, content.length()))) + .put("truncated", content.length() > 16000).put("item_count", clip.getItemCount()); + } + + private static String value(CharSequence value) { return value == null ? "" : value.toString(); } + private JSONObject network(JSONObject params) throws Exception { + String host = params.getString("host"); + if (host.length() > 253 || !host.matches("[A-Za-z0-9:.%-]+") || host.startsWith("-")) + throw new IllegalArgumentException("Invalid host; supply a hostname or IP without scheme/path"); + int port = integer(params, "port", 443, 1, 65535); + java.util.concurrent.ExecutorService worker = java.util.concurrent.Executors.newSingleThreadExecutor(); + JSONObject result = new JSONObject().put("host", host).put("port", port); + long start = SystemClock.uptimeMillis(); + try { + java.util.concurrent.Future lookup = worker.submit(() -> java.net.InetAddress.getAllByName(host)); + java.net.InetAddress[] addresses; + try { addresses = lookup.get(4, java.util.concurrent.TimeUnit.SECONDS); } + catch (Exception error) { + lookup.cancel(true); + return result.put("dns", new JSONObject().put("ok", false).put("error", error.toString())) + .put("tcp", new JSONObject().put("attempted", false)); + } + JSONArray resolved = new JSONArray(); + for (java.net.InetAddress address : addresses) resolved.put(address.getHostAddress()); + result.put("dns", new JSONObject().put("ok", true).put("addresses", resolved) + .put("elapsed_ms", SystemClock.uptimeMillis() - start)); + JSONArray attempts = new JSONArray(); + boolean connected = false; + for (int i = 0; i < Math.min(3, addresses.length); i++) { + long tcpStart = SystemClock.uptimeMillis(); + JSONObject attempt = new JSONObject().put("address", addresses[i].getHostAddress()); + try (java.net.Socket socket = new java.net.Socket()) { + socket.connect(new java.net.InetSocketAddress(addresses[i], port), 2000); + attempt.put("ok", true); connected = true; + } catch (Exception error) { attempt.put("ok", false).put("error", error.toString()); } + attempt.put("elapsed_ms", SystemClock.uptimeMillis() - tcpStart); + attempts.put(attempt); + if (connected) break; + } + return result.put("tcp", new JSONObject().put("attempted", true).put("ok", connected).put("attempts", attempts)); + } finally { worker.shutdownNow(); } + } + + private static String bounded(CharSequence value) { String text = value(value); return text.substring(0, Math.min(200, text.length())); } + private static int integer(JSONObject params, String key, int fallback, int min, int max) throws Exception { + Object raw = params.has(key) ? params.get(key) : fallback; + if (!(raw instanceof Number)) throw new IllegalArgumentException(key + " must be an integer"); + double number = ((Number) raw).doubleValue(); + if (!Double.isFinite(number) || number != Math.rint(number) || number < min || number > max) + throw new IllegalArgumentException(key + " must be between " + min + " and " + max); + return (int) number; + } +} diff --git a/app/src/main/kotlin/com/powercess/mbrain/control/PhoneTools.kt b/app/src/main/kotlin/com/powercess/mbrain/control/PhoneTools.kt new file mode 100644 index 0000000..fc271f8 --- /dev/null +++ b/app/src/main/kotlin/com/powercess/mbrain/control/PhoneTools.kt @@ -0,0 +1,97 @@ +package com.powercess.mbrain.control + +import io.droidmcp.core.* +import io.droidmcp.shell.ShellBackend +import kotlinx.coroutines.CancellationException +import kotlinx.coroutines.sync.Mutex +import kotlinx.coroutines.sync.withLock +import kotlinx.serialization.json.* + +/** One UI automation connection at a time, shared by both privileged backends. */ +object PhoneTools { + private val session = Mutex() + fun all(shell: ShellBackend, apkPath: String): List = operations.map { (name, spec) -> + object : McpTool { + override val name = name + override val description = spec.description + override val parameters = spec.parameters + override val annotations = ToolAnnotations(readOnlyHint = spec.readOnly, destructiveHint = !spec.readOnly, openWorldHint = name == "net_diagnose") + override suspend fun execute(params: Map): ToolResult = try { + val unknown = params.keys - parameters.map { it.name }.toSet() + require(unknown.isEmpty()) { "Unknown arguments: ${unknown.joinToString()}" } + parameters.forEach { parameter -> + val value = params[parameter.name] + require(value != null || !parameter.required) { "${parameter.name} is required" } + if (value != null) require(when (parameter.type) { + ParameterType.STRING -> value is String + ParameterType.BOOLEAN -> value is Boolean + ParameterType.INTEGER -> value is Number && value.toDouble().isFinite() && value.toDouble() == value.toLong().toDouble() + else -> false + }) { "Invalid ${parameter.name}" } + } + params.values.filterIsInstance().forEach { require(it.length <= 16000 && '\u0000' !in it) { "Text too long or contains NUL" } } + session.withLock { + val response = shell.exec("/system/bin/env", listOf("CLASSPATH=$apkPath", "/system/bin/app_process", + "/system/bin", "com.powercess.mbrain.control.PhoneControlMain", name, buildJsonObject { + params.forEach { (key, value) -> put(key, when (value) { + is Boolean -> JsonPrimitive(value) + is Number -> JsonPrimitive(value) + else -> JsonPrimitive(value.toString()) + }) } + }.toString())) + if (!response.isSuccess) ToolResult.error("phone_control_failed", response.stderr.take(2000)) + else decodePhoneReply(response.stdout) + } + } catch (cancel: CancellationException) { throw cancel } + catch (error: Exception) { ToolResult.error("phone_control_failed", error.message) } + } + } + + private data class Spec(val description: String, val parameters: List, val readOnly: Boolean = false) + private fun string(name: String, description: String, required: Boolean = false) = ToolParameter(name, description, ParameterType.STRING, required) + private fun number(name: String, description: String, required: Boolean = false) = ToolParameter(name, description, ParameterType.INTEGER, required) + private val selector = listOf( + string("text", "Exact node text; at least one of text/resource_id/description required"), + string("resource_id", "Full Android view resource ID"), + string("description", "Accessibility content description"), + string("package", "Restrict selector to this package"), + ToolParameter("contains", "Substring match for text/description; default false", ParameterType.BOOLEAN), + ) + private val actionSelector = selector + number("index", "Zero-based occurrence among matches; required when ambiguous (NOT dump node index)") + private val coordinates = listOf(number("x", "Default-display pixel X; use coordinates OR selector"), number("y", "Default-display pixel Y")) + private val operations = linkedMapOf( + "ui_dump" to Spec("Read the active window's node tree, text, bounds and actions. Paginated live snapshot; default display. Requires Root/Shizuku, no accessibility service setup.", + listOf(number("offset", "Node offset, default 0"), number("limit", "Page size 1..60, default 50")), true), + "ui_click" to Spec("Click a visible node (or nearest clickable ancestor), or pixel coordinates. Ambiguous selectors fail unless index supplied.", actionSelector + coordinates), + "ui_long_click" to Spec("Long-click a visible node (or actionable ancestor), or hold coordinates for 800ms.", actionSelector + coordinates), + "ui_set_text" to Spec("Replace an editable node's text with Unicode, including Chinese and emoji. Empty value clears it; does not submit. Use ui_wait/dump to verify.", + actionSelector + string("value", "Replacement text, up to 16000 characters", true)), + "ui_swipe" to Spec("Swipe between default-display pixel coordinates. Coordinates follow current screen rotation.", + listOf(number("x1", "Start X", true), number("y1", "Start Y", true), number("x2", "End X", true), number("y2", "End Y", true), number("duration_ms", "50..3000; default 350"))), + "ui_navigate" to Spec("Perform Android navigation: back, home, recents, notifications or quick_settings.", + listOf(string("action", "back | home | recents | notifications | quick_settings", true))), + "ui_wait" to Spec("Wait for a visible node to appear or disappear; polls a fresh tree every 250ms. Timeout is an error, not success.", + selector + listOf(string("state", "present (default) or absent"), number("timeout_ms", "0..15000, default 5000")), true), + "clipboard_get" to Spec("Read first clipboard text item for the current Android user. Returns available=false when empty or system-denied; non-text content is not dereferenced.", emptyList(), true), + "clipboard_set" to Spec("Replace clipboard text for the current Android user, including Chinese and emoji.", listOf(string("value", "Text, up to 16000 characters", true))), + "net_diagnose" to Spec("Diagnose DNS resolution and TCP connectivity from the selected Root/Shizuku backend. Returns per-stage status; DNS/TCP failure is a diagnostic result. No HTTP request is sent.", + listOf(string("host", "Hostname or IP without scheme/path", true), number("port", "TCP port 1..65535; default 443")), true), + ) +} + +internal fun decodePhoneReply(output: String): ToolResult { + val envelope = output.lineSequence().lastOrNull { it.startsWith("MBRAIN_RESULT:") } + ?: return ToolResult.error("phone_control_protocol", "Helper returned no result") + return try { + val reply = Json.parseToJsonElement(envelope.removePrefix("MBRAIN_RESULT:")).jsonObject + if (reply["ok"]?.jsonPrimitive?.booleanOrNull != true) ToolResult.error("phone_control_failed", reply["error"]?.jsonPrimitive?.content) + else ToolResult.success(reply.getValue("data").jsonObject.mapValues { jsonValue(it.value) }) + } catch (_: Exception) { ToolResult.error("phone_control_protocol", "Invalid helper result") } +} + +private fun jsonValue(value: JsonElement): Any? = when (value) { + JsonNull -> null + is JsonObject -> value.mapValues { jsonValue(it.value) } + is JsonArray -> value.map(::jsonValue) + is JsonPrimitive -> if (value.isString) value.content else value.booleanOrNull ?: value.longOrNull ?: value.doubleOrNull ?: value.content +} diff --git a/app/src/main/kotlin/com/powercess/mbrain/gateway/GatewayRuntime.kt b/app/src/main/kotlin/com/powercess/mbrain/gateway/GatewayRuntime.kt index 7a6a48f..e57efda 100644 --- a/app/src/main/kotlin/com/powercess/mbrain/gateway/GatewayRuntime.kt +++ b/app/src/main/kotlin/com/powercess/mbrain/gateway/GatewayRuntime.kt @@ -4,6 +4,7 @@ import android.content.Context import com.powercess.mbrain.data.* import com.powercess.mbrain.mcp.* import com.powercess.mbrain.shell.* +import com.powercess.mbrain.control.PhoneTools import com.powercess.mbrain.remote.SecretStore import io.droidmcp.apps.AppsTools import io.droidmcp.core.* @@ -217,6 +218,8 @@ object GatewayRuntime { add(ShellCommandTool(backend, prefix)) addAll(ShellTools.all(context, backend).filterNot { it.name == "run_shell" }.map { NamedTool(it, prefix) }) addAll(FileOperationTool.all(backend, prefix)) + addAll(PhoneTools.all(backend, context.applicationInfo.sourceDir).map { NamedTool(it, prefix) }) + addAll(DiagnosticTools.all(backend).map { NamedTool(it, prefix) }) } } } diff --git a/app/src/main/kotlin/com/powercess/mbrain/shell/DiagnosticTools.kt b/app/src/main/kotlin/com/powercess/mbrain/shell/DiagnosticTools.kt new file mode 100644 index 0000000..616c7e2 --- /dev/null +++ b/app/src/main/kotlin/com/powercess/mbrain/shell/DiagnosticTools.kt @@ -0,0 +1,125 @@ +package com.powercess.mbrain.shell + +import io.droidmcp.core.* +import io.droidmcp.shell.ShellBackend +import kotlinx.coroutines.CancellationException + +/** Bounded diagnostic commands; caller values are argv, never shell fragments. */ +object DiagnosticTools { + fun all(shell: ShellBackend): List = listOf( + command("logs_query", "Read a bounded logcat snapshot (not a stream). Filters combine; time is MM-DD HH:MM:SS.mmm. Buffer/UID support varies by Android version.", listOf( + integer("lines", "Maximum lines 1..300; default 100"), integer("pid", "Process ID"), integer("uid", "Android UID"), + string("tag", "Exact log tag; default all"), string("level", "V/D/I/W/E/F; default I"), + string("since", "MM-DD HH:MM:SS.mmm; optional"), string("buffer", "main/system/crash/events/all; default main"), + )) { p -> + val args = mutableListOf("-d", "-v", "threadtime", + "-b", p.choice("buffer", "main", setOf("main", "system", "crash", "events", "all"))) + if (p.containsKey("pid")) args += "--pid=${p.int("pid", 0, 1, Int.MAX_VALUE)}" + if (p.containsKey("uid")) args += "--uid=${p.int("uid", 0, 0, Int.MAX_VALUE)}" + if (p.containsKey("since")) { + val since = p.text("since") + require(Regex("\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}\\.\\d{3}").matches(since)) { "Invalid since format" } + args += listOf("-T", since, "-m", p.int("lines", 100, 1, 300).toString()) + } else args += listOf("-t", p.int("lines", 100, 1, 300).toString()) + val tag = if (p.containsKey("tag")) p.text("tag").also { require(Regex("[A-Za-z0-9_.-]{1,120}").matches(it)) { "Invalid tag" } } else "*" + args += "$tag:${p.choice("level", "I", setOf("V", "D", "I", "W", "E", "F"))}" + if (tag != "*") args += "*:S" + run(shell, "logcat", args, p.int("lines", 100, 1, 300)) + }, + command("appops_get", "Read AppOps modes for an application and optional operation.", packageParams + string("op", "Optional operation name")) { p -> + run(shell, "cmd", listOf("appops", "get", "--user", p.user(), p.pkg()) + p.optionalOp()) + }, + command("appops_set", "Set one AppOp mode, then return the observed mode. default resets this operation to platform policy.", packageParams + listOf( + string("op", "Operation, e.g. CAMERA or android:camera", true), string("mode", "allow/ignore/deny/default/foreground", true)), false) { p -> + val op = p.op() + val result = run(shell, "cmd", listOf("appops", "set", "--user", p.user(), p.pkg(), op, + p.choice("mode", null, setOf("allow", "ignore", "deny", "default", "foreground")))) + if (!result.isSuccess) result else { + val observed = run(shell, "cmd", listOf("appops", "get", "--user", p.user(), p.pkg(), op)) + if (observed.isSuccess) ToolResult.success(mapOf("applied" to true, "observed" to observed.data)) + else ToolResult.error("appops_verification_failed", "Set completed; readback failed: ${observed.errorMessage}") + } + }, + command("proc_list", "List processes with PID, UID, RSS and command. RSS is KiB. Optional package matches main and colon-suffixed processes.", + listOf(string("package", "Optional exact package"), integer("limit", "1..300, default 100"))) { p -> + val response = shell.exec("ps", listOf("-A", "-o", "PID,UID,RSS,NAME")) + if (!response.isSuccess) failure(response.exitCode, response.stderr) else { + val packageName = if (p.containsKey("package")) p.pkg() else null + val lines = response.stdout.lineSequence().drop(1).filter { it.isNotBlank() }.toList() + val processes = lines.mapNotNull { line -> + val parts = line.trim().split(Regex("\\s+"), limit = 4) + if (parts.size != 4 || parts[0].toLongOrNull() == null) null else mapOf( + "pid" to parts[0].toLong(), "uid" to parts[1], "rss_kib" to parts[2].toLongOrNull(), "name" to parts[3]) + }.filter { row -> packageName == null || row["name"] == packageName || row["name"].toString().startsWith("$packageName:") } + val limit = p.int("limit", 100, 1, 300) + ToolResult.success(mapOf("processes" to processes.take(limit), "total" to processes.size, "truncated" to (processes.size > limit))) + } + }, + command("app_resource_usage", "Read application memory and system CPU snapshot. CPU uses dumpsys' reported sampling interval, not an instantaneous percent.", + listOf(string("package", "Application package", true))) { p -> + val pkg = p.pkg() + val memory = run(shell, "dumpsys", listOf("meminfo", pkg)) + if (!memory.isSuccess) memory else { + val cpu = shell.exec("dumpsys", listOf("cpuinfo")) + if (!cpu.isSuccess) failure(cpu.exitCode, cpu.stderr) else { + val cpuLines = cpu.stdout.lineSequence().filter { it.contains(pkg) || it.startsWith("CPU usage") || it.contains("TOTAL:") }.toList() + ToolResult.success(mapOf("package" to pkg, "memory" to memory.data, "cpu" to cpuLines)) + } + } + }, + command("net_status", "Read IP addresses, IPv4/IPv6 routes, Wi-Fi status and global HTTP proxy. Each section reports its own exit code.", emptyList()) { + val sections = linkedMapOf() + listOf(Triple("addresses", "ip", listOf("addr", "show")), + Triple("routes_ipv4", "ip", listOf("route", "show")), Triple("routes_ipv6", "ip", listOf("-6", "route", "show")), + Triple("wifi", "cmd", listOf("wifi", "status")), Triple("http_proxy", "settings", listOf("get", "global", "http_proxy"))) + .forEach { (name, executable, args) -> + val result = shell.exec(executable, args) + sections[name] = mapOf("exit_code" to result.exitCode, "output" to result.stdout.take(12000), "stderr" to result.stderr.take(2000)) + } + ToolResult.success(sections) + }, + ) + + private val packageParams = listOf(string("package", "Application package", true), integer("user", "Android user ID; defaults to current user")) + private fun string(name: String, description: String, required: Boolean = false) = ToolParameter(name, description, ParameterType.STRING, required) + private fun integer(name: String, description: String) = ToolParameter(name, description, ParameterType.INTEGER) + private fun command(name: String, description: String, parameters: List, readOnly: Boolean = true, + openWorld: Boolean = false, execute: suspend (Map) -> ToolResult): McpTool = object : McpTool { + override val name = name + override val description = description + override val parameters = parameters + override val annotations = ToolAnnotations(readOnlyHint = readOnly, destructiveHint = !readOnly, openWorldHint = openWorld) + override suspend fun execute(params: Map): ToolResult = try { + require((params.keys - parameters.map { it.name }.toSet()).isEmpty()) { "Unknown argument" } + execute.invoke(params) + } catch (cancel: CancellationException) { throw cancel } + catch (error: Exception) { ToolResult.error("diagnostic_failed", error.message) } + } + private suspend fun run(shell: ShellBackend, executable: String, args: List, maxLines: Int = 400): ToolResult { + val result = shell.exec(executable, args) + if (!result.isSuccess) return failure(result.exitCode, result.stderr.ifBlank { result.stdout }) + // Some Android cmd handlers report errors on stderr while exiting zero. + if (result.stderr.lineSequence().any { it.startsWith("Error:") || it.startsWith("Exception") }) return ToolResult.error(result.stderr.take(2000)) + val lines = result.stdout.lines() + val text = lines.takeLast(maxLines).joinToString("\n") + return ToolResult.success(mapOf("output" to text.take(48000), "truncated" to (lines.size > maxLines || text.length > 48000), + "exit_code" to result.exitCode, "stderr" to result.stderr.take(2000))) + } + private fun failure(code: Int, error: String) = ToolResult.error("command_failed", "exit=$code: ${error.take(2000)}") + private fun Map.text(key: String): String = (this[key] as? String)?.also { + require(it.isNotBlank() && '\u0000' !in it) { "$key must not be blank or contain NUL" } + } ?: error("$key is required") + private fun Map.pkg() = text("package").also { require(Regex("[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)+").matches(it)) { "Invalid package" } } + private fun Map.op() = text("op").also { require(Regex("[A-Za-z][A-Za-z0-9_:]{0,100}").matches(it)) { "Invalid operation" } } + private fun Map.optionalOp() = if (containsKey("op")) listOf(op()) else emptyList() + private fun Map.user() = if (containsKey("user")) int("user", 0, 0, 100000).toString() else "current" + private fun Map.choice(key: String, default: String?, choices: Set): String = + (if (containsKey(key)) text(key) else default ?: error("$key is required")).also { require(it in choices) { "Invalid $key" } } + private fun Map.int(key: String, default: Int, min: Int, max: Int): Int { + if (!containsKey(key)) return default + val value = this[key] as? Number ?: error("$key must be an integer") + val number = value.toDouble() + require(number.isFinite() && number == value.toLong().toDouble() && number >= min && number <= max) { "$key must be $min..$max" } + return value.toInt() + } +} diff --git a/app/src/main/kotlin/com/powercess/mbrain/ui/DetailScreens.kt b/app/src/main/kotlin/com/powercess/mbrain/ui/DetailScreens.kt index a2fe863..4b6af0d 100644 --- a/app/src/main/kotlin/com/powercess/mbrain/ui/DetailScreens.kt +++ b/app/src/main/kotlin/com/powercess/mbrain/ui/DetailScreens.kt @@ -19,6 +19,12 @@ private val toolLabels = mapOf( "list_installed_apps" to "应用列表", "get_app_info" to "应用详情", "launch_app" to "启动应用", "exec" to "执行命令", "file_list" to "浏览目录", "file_read" to "读取文件", "file_write" to "写入文件", "file_mkdir" to "创建目录", "file_copy" to "复制文件", "file_move" to "移动文件", "file_delete" to "删除文件", + "ui_dump" to "读取控件树", "ui_click" to "点击控件", "ui_long_click" to "长按控件", + "ui_set_text" to "输入文本", "ui_swipe" to "滑动屏幕", "ui_navigate" to "系统导航", "ui_wait" to "等待控件", + "clipboard_get" to "读取剪贴板", "clipboard_set" to "写入剪贴板", + "logs_query" to "查询日志", "appops_get" to "查询 AppOps", "appops_set" to "修改 AppOps", + "proc_list" to "进程列表", "app_resource_usage" to "应用资源占用", + "net_status" to "网络状态", "net_diagnose" to "网络诊断", ) internal fun toolTitle(name: String): String = toolLabels[name.removePrefix("root_").removePrefix("shizuku_")] ?: name diff --git a/app/src/test/kotlin/com/powercess/mbrain/control/PhoneToolsTest.kt b/app/src/test/kotlin/com/powercess/mbrain/control/PhoneToolsTest.kt new file mode 100644 index 0000000..e19df84 --- /dev/null +++ b/app/src/test/kotlin/com/powercess/mbrain/control/PhoneToolsTest.kt @@ -0,0 +1,56 @@ +package com.powercess.mbrain.control + +import io.droidmcp.shell.ShellBackend +import io.droidmcp.shell.ShellResult +import kotlinx.coroutines.test.runTest +import kotlinx.serialization.json.* +import org.junit.Assert.* +import org.junit.Test + +class PhoneToolsTest { + private class Shell : ShellBackend { + override val name = "fake" + override fun isAvailable() = true + val calls = mutableListOf>>() + override suspend fun exec(command: String, args: List): ShellResult { + calls += command to args + return ShellResult.ofText(0, "MBRAIN_RESULT:{\"ok\":true,\"data\":{\"performed\":true}}", "") + } + } + @Test fun `unicode and shell syntax are delivered as literal JSON argv`() = runTest { + val shell = Shell() + val tool = PhoneTools.all(shell, "/data/app/a b/base.apk").first { it.name == "ui_set_text" } + val text = "中文😀\n'\"; $(touch /sdcard/injected)" + assertTrue(tool.execute(mapOf("resource_id" to "app:id/input", "value" to text)).isSuccess) + val (command, args) = shell.calls.single() + assertEquals("/system/bin/env", command) + assertEquals("CLASSPATH=/data/app/a b/base.apk", args.first()) + assertEquals(text, Json.parseToJsonElement(args.last()).jsonObject["value"]!!.jsonPrimitive.content) + assertFalse(args.contains("-c")) + } + @Test fun `bad required types fractional numbers and unknown args never reach backend`() = runTest { + val shell = Shell() + val tools = PhoneTools.all(shell, "/base.apk").associateBy { it.name } + assertFalse(tools.getValue("ui_set_text").execute(mapOf("text" to "field")).isSuccess) + assertFalse(tools.getValue("clipboard_set").execute(mapOf("value" to 12)).isSuccess) + assertFalse(tools.getValue("ui_click").execute(mapOf("x" to 1.5, "y" to 2)).isSuccess) + assertFalse(tools.getValue("ui_navigate").execute(mapOf("action" to "back", "acton" to "home")).isSuccess) + assertFalse(tools.getValue("clipboard_set").execute(mapOf("value" to "x\u0000y")).isSuccess) + assertTrue(shell.calls.isEmpty()) + } + @Test fun `helper failures and malformed output never become successful calls`() { + assertFalse(decodePhoneReply("VM startup failed").isSuccess) + assertFalse(decodePhoneReply("MBRAIN_RESULT:garbage").isSuccess) + val result = decodePhoneReply("log line\nMBRAIN_RESULT:{\"ok\":false,\"error\":\"wait_timeout\"}") + assertFalse(result.isSuccess) + assertTrue(result.errorMessage!!.contains("wait_timeout")) + } + @Test fun `nested node results and explicit null survive decoding`() { + val result = decodePhoneReply("MBRAIN_RESULT:{\"ok\":true,\"data\":{\"nodes\":[{\"text\":\"中文\",\"bounds\":[1,2,3,4]}],\"next_offset\":null,\"truncated\":false}}") + assertTrue(result.isSuccess) + val data = result.data!! + assertNull(data["next_offset"]) + assertEquals(false, data["truncated"]) + assertEquals("中文", ((data["nodes"] as List<*>).single() as Map<*, *>)["text"]) + } +} diff --git a/app/src/test/kotlin/com/powercess/mbrain/shell/DiagnosticToolsTest.kt b/app/src/test/kotlin/com/powercess/mbrain/shell/DiagnosticToolsTest.kt new file mode 100644 index 0000000..70b978d --- /dev/null +++ b/app/src/test/kotlin/com/powercess/mbrain/shell/DiagnosticToolsTest.kt @@ -0,0 +1,67 @@ +package com.powercess.mbrain.shell + +import io.droidmcp.shell.ShellBackend +import io.droidmcp.shell.ShellResult +import kotlinx.coroutines.test.runTest +import org.junit.Assert.* +import org.junit.Test + +class DiagnosticToolsTest { + private class Shell : ShellBackend { + override val name = "fake" + override fun isAvailable() = true + val calls = mutableListOf>>() + var reply = ShellResult.ofText(0, "ok", "") + override suspend fun exec(command: String, args: List): ShellResult { + calls += command to args + return reply + } + fun tool(name: String) = DiagnosticTools.all(this).first { it.name == name } + } + @Test fun `log queries are finite and combine validated filters`() = runTest { + val shell = Shell() + val result = shell.tool("logs_query").execute(mapOf("pid" to 42L, "uid" to 10000L, "tag" to "App", "lines" to 12, "level" to "E")) + assertTrue(result.isSuccess) + val args = shell.calls.single().second + assertTrue(args.containsAll(listOf("-d", "-t", "12", "--pid=42", "--uid=10000", "App:E", "*:S"))) + } + @Test fun `invalid command arguments cannot reach shell`() = runTest { + val shell = Shell() + assertFalse(shell.tool("logs_query").execute(mapOf("tag" to "x; id")).isSuccess) + assertFalse(shell.tool("logs_query").execute(mapOf("lines" to 0)).isSuccess) + assertFalse(shell.tool("logs_query").execute(mapOf("pid" to 1.5)).isSuccess) + assertFalse(shell.tool("appops_set").execute(mapOf("package" to "a.b;id", "op" to "CAMERA", "mode" to "allow")).isSuccess) + assertFalse(shell.tool("appops_set").execute(mapOf("package" to "a.b", "op" to "CAMERA", "mode" to "typo")).isSuccess) + assertTrue(shell.calls.isEmpty()) + } + @Test fun `timestamp queries retain a maximum record count`() = runTest { + val shell = Shell() + assertTrue(shell.tool("logs_query").execute(mapOf("since" to "09-24 12:30:00.000", "lines" to 7)).isSuccess) + val args = shell.calls.single().second + assertTrue(args.containsAll(listOf("-d", "-T", "09-24 12:30:00.000", "-m", "7"))) + assertFalse(args.contains("-t")) + } + @Test fun `AppOps writes specify user and read back same operation`() = runTest { + val shell = Shell() + assertTrue(shell.tool("appops_set").execute(mapOf("package" to "a.b", "op" to "CAMERA", "mode" to "default", "user" to 10)).isSuccess) + assertEquals(listOf("appops", "set", "--user", "10", "a.b", "CAMERA", "default"), shell.calls[0].second) + assertEquals(listOf("appops", "get", "--user", "10", "a.b", "CAMERA"), shell.calls[1].second) + } + @Test fun `shell failures are surfaced and AppOps write does not continue`() = runTest { + val shell = Shell() + shell.reply = ShellResult.ofText(1, "", "denied") + assertFalse(shell.tool("appops_set").execute(mapOf("package" to "a.b", "op" to "CAMERA", "mode" to "allow")).isSuccess) + assertEquals(1, shell.calls.size) + shell.reply = ShellResult.ofText(0, "", "Error: unknown operation") + assertFalse(shell.tool("appops_get").execute(mapOf("package" to "a.b")).isSuccess) + } + @Test fun `process filtering excludes similar package names and reports truncation`() = runTest { + val shell = Shell() + shell.reply = ShellResult.ofText(0, "PID UID RSS NAME\n1 10000 42 a.b\n2 10000 21 a.b:remote\n3 10001 11 a.bc\n", "") + val result = shell.tool("proc_list").execute(mapOf("package" to "a.b", "limit" to 1)) + val data = result.data!! + assertEquals(2, data["total"]) + assertEquals(true, data["truncated"]) + assertEquals(42L, ((data["processes"] as List<*>).single() as Map<*, *>)["rss_kib"]) + } +} diff --git a/docs/capability-packs.md b/docs/capability-packs.md new file mode 100644 index 0000000..ce6cb4b --- /dev/null +++ b/docs/capability-packs.md @@ -0,0 +1,82 @@ +# 手机操作与应用诊断 + +启用 Root 或 Shizuku 后,在工具目录中选择对应来源。下表省略 `root_` / `shizuku_` 前缀,例如完整名称为 `shizuku_ui_dump`。工具不需要单独启用无障碍服务,也不依赖 AutoX.js。 + +## 手机操作 + +| 工具 | 参数与用途 | +| --- | --- | +| `ui_dump` | `offset`、`limit`;读取当前窗口,默认每页 50 个节点,最多 60 个;总遍历上限 600 个 | +| `ui_click` | 按选择器点击节点或可点击的父节点;也可传 `x`、`y` | +| `ui_long_click` | 按选择器长按;坐标长按保持 800ms | +| `ui_set_text` | 选择输入框或它的标签,`value` 为替换内容;支持中文、emoji、换行,空字符串清空 | +| `ui_swipe` | `x1`、`y1`、`x2`、`y2`,`duration_ms` 为 50–3000,默认 350 | +| `ui_navigate` | `action`:`back`、`home`、`recents`、`notifications`、`quick_settings` | +| `ui_wait` | 选择器 + `state=present/absent`,默认等待出现,`timeout_ms` 默认 5000、最多 15000 | +| `clipboard_get` | 读取第一项文本;返回可用性、文本、项数与截断状态,不读取 URI 指向的文件 | +| `clipboard_set` | `value`:写入最多 16000 字符的文本 | + +选择器至少提供 `text`、`resource_id`、`description` 之一,多个字段同时提供表示同时满足。可用 `package` 限定目标应用。`text` 和 `description` 默认精确匹配,`contains=true` 改为包含匹配。动作遇到多个匹配时返回错误,使用 `index` 指定匹配结果中的第几个(从 0 开始);它不是 `ui_dump` 的节点索引。坐标与选择器不能混用。 + +`ui_dump` 的索引和父索引用于描述当次快照,翻页期间页面应保持稳定;不缓存节点供后续动作复用。单个文字/描述最多返回 200 字符,密码文字不返回。文本写入最多 16000 字符。动作返回 `performed=true` 表示系统接受了动作,业务是否完成应继续用 `ui_wait`、`ui_dump` 或截图验证。 + +例如: + +```json +{"name":"shizuku_ui_set_text","arguments":{"text":"服务名称","package":"com.powercess.mbrain","value":"中文输入 😀"}} +``` + +```json +{"name":"shizuku_ui_wait","arguments":{"text":"保存成功","timeout_ms":5000}} +``` + +## 应用诊断 + +| 工具 | 参数与用途 | +| --- | --- | +| `logs_query` | `lines`(1–300,默认 100)、`pid`、`uid`、`tag`、`level`(默认 I)、`buffer`(默认 main)、`since` | +| `appops_get` | `package`、可选 `op` 和 `user` | +| `appops_set` | `package`、`op`、`mode`(allow/ignore/deny/default/foreground)、可选 `user`;设置后读回 | +| `proc_list` | 可选 `package` 和 `limit`;返回 PID、UID、RSS KiB、进程名,包括包名的冒号子进程 | +| `app_resource_usage` | `package`;返回内存报告,以及系统 CPU 报告中的采样区间、目标应用和总量 | +| `net_status` | 返回 IP、IPv4/IPv6 路由、Wi-Fi 与全局 HTTP 代理,各项带退出码 | +| `net_diagnose` | `host`、`port`(默认 443);DNS 最多等待 4 秒,最多尝试 3 个地址、每次 TCP 最多 2 秒 | + +日志未传 `since` 时取最近若干条;传入 `MM-DD HH:MM:SS.mmm` 后,从该时间开始最多取 `lines` 条。日志是快照,不持续监听。输出超出执行器预算会明确报错,应缩小查询范围。普通诊断文本返回截断标记。 + +AppOps 默认针对当前 Android 用户;`default` 恢复该项的平台默认策略。网络诊断只进行域名解析与 TCP 握手,不发送 HTTP 请求;DNS/TCP 失败作为诊断结果返回,不能仅凭 MCP 调用成功判断网络畅通。连通性反映所选执行身份,并不等同于目标应用的网络权限或 VPN 路由。 + +## 执行方式 + +固定 Java 辅助入口打包在 APK 中,经现有高权限执行器启动 `app_process`,只接受上述固定操作和 JSON 参数,不接受任意代码。UI 操作在两个后端之间串行执行;连接时保留已有无障碍服务,完成后断开。沿用现有命令超时、输出上限与能力关闭行为。 + +## 验证 + +应用单元测试覆盖参数边界、字面量 Unicode 参数传递、辅助进程错误、结果解码、日志过滤、AppOps 读回及进程匹配。 + +构建 Debug APK 和 AndroidTest APK,安装独立测试包后运行: + +```powershell +./gradlew.bat :app:assembleDebug :app:assembleDebugAndroidTest :app:testDebugUnitTest :app:lintDebug +./scripts/smoke-capabilities.ps1 -Package com.powercess.mbrain.dev +``` + +脚本仅允许测试包名,会重新启动该测试应用,操作未保存的服务表单,不清除数据。诊断测试只返回通过/失败;剪贴板原始对象在设备内存中保存、恢复,不传回主机。测试前让设备保持解锁。使用固定开发包名和同一本地签名覆盖安装,不卸载已有应用。 + +真实 Shizuku → MCP 链路另由 `CapabilityGatewayTest` 验证。在测试应用中启用并授权 Shizuku,安装对应 AndroidTest APK,然后执行: + +```powershell +adb shell am instrument -w -e class com.powercess.mbrain.control.CapabilityGatewayTest -e capabilityGateway true com.powercess.mbrain.dev.test/androidx.test.runner.AndroidJUnitRunner +``` + +常规开发测试统一使用固定的开发包名。测试在设备内获取自己的网关凭据、初始化 MCP、检查全部 16 项工具并执行读操作及测试应用内的点击;Token 不离开设备。结束后停止测试网关。 + +### 2026-09-24 验证记录 + +- Debug 与 AndroidTest APK 构建通过;应用模块 41 项 JVM 测试通过,lint 为 0 错误、33 警告。已有 HTTP 本机测试曾出现一次 socket 超时,复跑通过。构建复用了未修改的四 ABI frpc 产物。 +- Android 15 / API 35 已连接设备:`smoke-capabilities.ps1` 通过,覆盖控件树、选择器点击、中文与 emoji 输入、长按、滑动、返回/桌面/最近任务、出现/消失等待与超时、设备内剪贴板保存/恢复,以及全部诊断工具。 +- `CapabilityGatewayTest` 通过:真实 Shizuku → 托管执行器 → 辅助进程 / 系统命令 → MCP 返回链路可用,16 项新增工具均出现在网关目录。 +- 中文工具名和搜索界面验证通过。测试使用独立 `controlqa` 包,保留原有应用数据;结束时测试网关已停止。 +- 尚未覆盖其他 Android 版本、其他 ROM、直接 Root 后端与多显示器;当前 UI 操作仅支持默认显示器。 + +固定开发包名后的提交前复验:`com.powercess.mbrain.dev` / “MBrain 开发版”安装成功,手机操作与诊断脚本、设备内 Shizuku/MCP 测试再次通过。Debug、AndroidTest、Release 构建、各模块 JVM 测试、Debug/Release lint 及四 ABI 打包检查通过;常规开发不再使用临时包名覆盖脚本。 diff --git a/docs/development.md b/docs/development.md index 75424a4..3f8607e 100644 --- a/docs/development.md +++ b/docs/development.md @@ -51,7 +51,9 @@ GitHub Actions 在 push、PR 和手动触发时使用 Ubuntu 24.04、JDK 17、An 通用 APK 覆盖 `arm64-v8a`、`armeabi-v7a`、`x86_64` 和 `x86`,最低 Android 9.0。CI 检查 APK 中每个原生库是否同时包含四种 ABI;当前原生库来自 AndroidX 依赖。无需按 CPU 下载不同文件。该检查验证打包完整性,不代表四种架构都已进行运行测试。设备上的外部 MCP 程序需要另行匹配设备架构。 -自动构建使用临时 Debug 签名和 `com.powercess.mbrain.debug` 包名,仅用于测试,可与正式版并存。不同运行的 Debug 签名可能不同,不能保证覆盖安装同名测试包。正式版固定使用 `com.powercess.mbrain` 和正式签名。早期临时版本曾使用正式包名与 Debug 签名,无法直接覆盖为正式版;卸载会清除配置,操作前需保存需要保留的连接设置。 +本地开发与普通 Debug 构建固定使用 `com.powercess.mbrain.dev`,桌面显示“MBrain 开发版”,版本号显示为 `版本号-dev`。包名不随版本号或开发任务改变,不再通过临时 init 脚本改成 `controlqa` 等名称。后续本地构建使用同一份 Debug keystore,并以 `adb install -r` 覆盖更新,保留配置。 + +CI 使用临时 Debug 签名,签名可能与本地不同,不能保证覆盖安装同名开发包。正式版固定使用 `com.powercess.mbrain` 和正式签名。已有旧测试包不会自动迁移或卸载;签名冲突时应先确认安装来源,不通过不断更换包名解决。卸载会清除配置。 验证首次克隆时,在新目录克隆后设置标准 `JAVA_HOME`、`ANDROID_HOME` 和全新的 `GRADLE_USER_HOME`,运行 `./gradlew :app:assembleDebug testDebugUnitTest :app:lintDebug --no-build-cache --max-workers=1 --no-parallel --no-watch-fs`。Windows 使用 `gradlew.bat`。不复制旧目录的 `local.properties`、`.local-tools`、`.gradle` 或 `build`。 @@ -70,6 +72,8 @@ KernelSU 等管理器可能对未授权应用隐藏 `su`,需在管理器中单 ## 当前工具 +0.3.0 新增手机操作包与应用诊断包,完整参数和设备测试见[能力包说明](capability-packs.md)。两组工具随 Root / Shizuku 来源启用,不需要额外安装自动化引擎。 + | 来源 | 工具 | |---|---| | 设备(始终启用) | `get_device_info`、`get_battery_info`、`get_connectivity`、`get_storage_info` | diff --git a/docs/releases/0.3.0.md b/docs/releases/0.3.0.md new file mode 100644 index 0000000..fa198c8 --- /dev/null +++ b/docs/releases/0.3.0.md @@ -0,0 +1,27 @@ +# MBrain 0.3.0 + +本版本增加手机操作包和应用诊断包。启用 Root 或 Shizuku 后,工具会随对应来源出现在工具目录中;无需配置外部自动化应用。 + +## 手机操作包 + +- 控件树:读取当前窗口的文字、描述、资源 ID、坐标、父子关系和可操作状态,支持分页。 +- 点击与长按:按文字、资源 ID、描述定位,也支持坐标操作;多个匹配需明确选择。 +- 中文输入:替换输入框内容,支持中文、emoji 和多行文本,可通过输入框标签定位。 +- 滑动与导航:滑动、返回、桌面、最近任务、通知栏和快捷设置。 +- 等待:等待控件出现或消失,超时明确返回错误。 +- 剪贴板:读取和写入文本。 + +## 应用诊断包 + +- 日志:按进程、UID、标签、级别、缓冲区和起始时间查询。 +- AppOps:读取、修改单项操作模式,并返回修改后的查询结果。 +- 进程与资源:进程列表、RSS、应用内存报告和 CPU 采样报告。 +- 网络:IP、路由、Wi-Fi、代理状态,以及 DNS 解析和 TCP 连通性诊断。 + +## 使用范围 + +新增 16 个工具,每个已启用的高权限来源分别注册 `root_` 或 `shizuku_` 前缀。工具目录提供对应中文名称。现有工具和配置保持兼容。 + +开发版固定使用 `com.powercess.mbrain.dev`,桌面名称为“MBrain 开发版”;包名不随版本变化,后续使用相同本地签名覆盖更新。正式版仍使用 `com.powercess.mbrain`。 + +手机操作针对当前活动窗口和默认显示器,设备需要处于可交互状态。自绘控件、受保护页面可能不提供完整控件树。剪贴板、系统命令及隐藏接口受 Android 版本和厂商系统影响,不可用时返回明确错误,不自动切换执行身份。 diff --git a/scripts/smoke-capabilities.ps1 b/scripts/smoke-capabilities.ps1 new file mode 100644 index 0000000..e156b83 --- /dev/null +++ b/scripts/smoke-capabilities.ps1 @@ -0,0 +1,73 @@ +param( + [string]$Package = 'com.powercess.mbrain.dev', + [string]$Serial = '', + [string]$TestApk = "$PSScriptRoot/../app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk" +) +$ErrorActionPreference = 'Stop' +if ($Package -ne 'com.powercess.mbrain.dev') { + throw 'Only the fixed development package com.powercess.mbrain.dev may be tested.' +} +$deviceArgs = if ($Serial) { @('-s', $Serial) } else { @() } +function Invoke-Adb([string[]]$Arguments) { + $output = & adb @deviceArgs @Arguments + if ($LASTEXITCODE -ne 0) { throw "ADB failed ($LASTEXITCODE): $($Arguments[0])" } + return $output +} +function Quote-Shell([string]$Value) { "'" + $Value.Replace("'", "'" + [char]34 + "'" + [char]34 + "'") + "'" } +$apkPath = ([string](Invoke-Adb @('shell', 'pm', 'path', $Package))).Replace('package:', '').Trim() +if (!$apkPath.StartsWith('/data/app/')) { throw 'Install the test app first.' } +$helper = "CLASSPATH=$(Quote-Shell $apkPath) timeout 30 app_process /system/bin com.powercess.mbrain.control.PhoneControlMain" +function Invoke-Phone([string]$Operation, [hashtable]$Arguments = @{}) { + # Restrict selectors to the test app; global navigation and coordinates are explicit below. + if ($Arguments.ContainsKey('text')) { $Arguments['package'] = $Package } + $json = ConvertTo-Json -InputObject $Arguments -Compress -EscapeHandling EscapeNonAscii + $output = Invoke-Adb @('shell', "$helper $Operation $(Quote-Shell $json)") + $line = $output | Where-Object { $_.StartsWith('MBRAIN_RESULT:') } | Select-Object -Last 1 + if (!$line) { throw 'No helper response' } + $reply = $line.Substring(14) | ConvertFrom-Json + if (!$reply.ok) { throw "$Operation failed: $($reply.error)" } + return $reply.data +} +Invoke-Adb @('push', (Resolve-Path $TestApk).Path, '/data/local/tmp/mbrain-control-tests.apk') | Out-Null +try { + Invoke-Adb @('shell', 'am', 'force-stop', $Package) | Out-Null + Invoke-Adb @('shell', 'am', 'start', '-W', '-n', "$Package/com.powercess.mbrain.MainActivity") | Out-Null + $classpath = Quote-Shell "${apkPath}:/data/local/tmp/mbrain-control-tests.apk" + $result = Invoke-Adb @('shell', "CLASSPATH=$classpath timeout 60 app_process /system/bin com.powercess.mbrain.control.CapabilitySmokeMain $(Quote-Shell $apkPath) $Package") + if ($result -notcontains 'CAPABILITY_SMOKE_OK') { throw 'Device diagnostics failed' } + $result + $tree = Invoke-Phone ui_dump + if ($tree.count -le 0) { throw 'Empty UI tree' } + 'PASS ui_dump' + Invoke-Phone ui_click @{text='MCP'} | Out-Null + Invoke-Phone ui_wait @{text='添加服务'; timeout_ms=5000} | Out-Null + Invoke-Phone ui_click @{text='添加服务'} | Out-Null + Invoke-Phone ui_wait @{text='HTTP 服务'; timeout_ms=5000} | Out-Null + Invoke-Phone ui_click @{text='HTTP 服务'} | Out-Null + Invoke-Phone ui_set_text @{text='服务名称';value='MBrain 中文😀输入验证'} | Out-Null + Invoke-Phone ui_wait @{text='MBrain 中文😀输入验证'; timeout_ms=5000} | Out-Null + 'PASS Chinese + emoji input and present wait' + Invoke-Phone ui_long_click @{text='MBrain 中文😀输入验证'} | Out-Null + 'PASS node long click' + Invoke-Phone ui_navigate @{action='back'} | Out-Null + # Derive swipe coordinates from the current root, so the script works at different resolutions. + $bounds = (Invoke-Phone ui_dump).nodes[0].bounds + $x = [int](($bounds[0] + $bounds[2]) / 2) + $y1 = [int]($bounds[1] + ($bounds[3] - $bounds[1]) * 0.65) + $y2 = [int]($bounds[1] + ($bounds[3] - $bounds[1]) * 0.4) + Invoke-Phone ui_swipe @{x1=$x;y1=$y1;x2=$x;y2=$y2;duration_ms=250} | Out-Null + 'PASS swipe' + Invoke-Phone ui_wait @{text='MBrain nonexistent control';state='absent';timeout_ms=0} | Out-Null + try { Invoke-Phone ui_wait @{text='MBrain nonexistent control';timeout_ms=100} | Out-Null; throw 'Expected timeout' } + catch { if (!$_.ToString().Contains('wait_timeout')) { throw } } + 'PASS absent wait and timeout error' + Invoke-Phone ui_navigate @{action='home'} | Out-Null + Invoke-Phone ui_navigate @{action='recents'} | Out-Null + Invoke-Phone ui_navigate @{action='back'} | Out-Null + 'PASS home, recents and back' +} finally { + Invoke-Adb @('shell', 'rm', '-f', '/data/local/tmp/mbrain-control-tests.apk') | Out-Null + # Discard the unsaved test form, leaving installed app data intact. + Invoke-Adb @('shell', 'am', 'force-stop', $Package) | Out-Null + Invoke-Adb @('shell', 'am', 'start', '-W', '-n', "$Package/com.powercess.mbrain.MainActivity") | Out-Null +} diff --git a/scripts/smoke-frpc.py b/scripts/smoke-frpc.py index cd1fd91..654df27 100644 --- a/scripts/smoke-frpc.py +++ b/scripts/smoke-frpc.py @@ -22,7 +22,7 @@ def free_port(): def run(args): root = Path(__file__).resolve().parents[1] - if args.package in {"com.powercess.mbrain", "com.powercess.mbrain.debug"}: + if args.package in {"com.powercess.mbrain", "com.powercess.mbrain.debug", "com.powercess.mbrain.dev"}: raise ValueError("Use an isolated QA package to protect existing application data") adb = [args.adb, "-s", args.serial] source = root / "build/frpc-source/frp-0.71.0"