xiaomin1397 · Oct 29, 2026 · Oct 28, 2026
diff --git a/debug/shell/android/app-impl/src/main/java/org/hapjs/debugger/fragment/AppFragment.java b/debug/shell/android/app-impl/src/main/java/org/hapjs/debugger/fragment/AppFragment.java
@@ -165,9 +165,9 @@ public void onInstallResult(String pkg, boolean result, int code) {
 
 
             @Override
-            public void onError(int code) {
+            public void onError(int code, Bundle extras) {
                 resetButtonTextView();
-                super.onError(code);
+                super.onError(code, extras);
             }
 
             @Override

diff --git a/debug/shell/android/app-impl/src/main/java/org/hapjs/debugger/fragment/CardFragment.java b/debug/shell/android/app-impl/src/main/java/org/hapjs/debugger/fragment/CardFragment.java
@@ -10,6 +10,7 @@
 import android.content.pm.PackageInfo;
 import android.content.pm.PackageManager;
 import android.os.Build;
+import android.os.Bundle;
 import android.os.Handler;
 import android.os.Message;
 import android.os.SystemClock;
@@ -179,9 +180,9 @@ public void run() {
             }
 
             @Override
-            public void onError(int code) {
+            public void onError(int code, Bundle extras) {
                 resetButtonTextView();
-                super.onError(code);
+                super.onError(code, extras);
             }
         });
         CardDebugManager.getInstance(getContext()).setDebugListener(new CardDebugManager.CardDebugListener() {

diff --git a/debug/shell/android/app-impl/src/main/java/org/hapjs/debugger/fragment/DebugFragment.java b/debug/shell/android/app-impl/src/main/java/org/hapjs/debugger/fragment/DebugFragment.java
@@ -8,6 +8,7 @@
 import android.Manifest;
 import android.app.Activity;
 import android.app.Dialog;
+import android.content.ActivityNotFoundException;
 import android.content.DialogInterface;
 import android.content.Intent;
 import android.content.pm.PackageManager;
@@ -17,6 +18,7 @@
 import android.os.Build;
 import android.os.Bundle;
 import android.os.Handler;
+import android.provider.Settings;
 import android.text.TextUtils;
 import android.util.DisplayMetrics;
 import android.util.Log;
@@ -87,6 +89,8 @@ public abstract class DebugFragment extends Fragment implements AdapterView.OnIt
     protected boolean mIsToolkitDebug;
     String mScanTarget;
     private AlertDialog mGetRpkErrorDialog;
+    private AlertDialog mAdbDisabledDialog;
+    private boolean mDevOptionsEnabled;
     private Uri mPendingPackageUri;
     private Server mServer;
 
@@ -228,6 +232,9 @@ public void onDestroy() {
         if (mGetRpkErrorDialog != null) {
             mGetRpkErrorDialog.dismiss();
         }
+        if (mAdbDisabledDialog != null) {
+            mAdbDisabledDialog.dismiss();
+        }
         mServer.stop();
     }
 
@@ -359,6 +366,48 @@ protected void showGetRpkErrorDialog() {
         mGetRpkErrorDialog.show();
     }
 
+    protected void showAdbDisabledDialog(boolean devOptionsEnabled) {
+        Activity activity = getActivity();
+        if (activity == null || activity.isDestroyed()
+                || activity.isFinishing()
+                || (mAdbDisabledDialog != null && mAdbDisabledDialog.isShowing())) {
+            Log.w(TAG, "showAdbDisabledDialog skipped: devOptionsEnabled=" + devOptionsEnabled
+                    + ", activityNull=" + (activity == null)
+                    + ", dialogShowing="
+                    + (mAdbDisabledDialog != null && mAdbDisabledDialog.isShowing()));
+            return;
+        }
+        Log.i(TAG, "showAdbDisabledDialog: devOptionsEnabled=" + devOptionsEnabled
+                + ", mDevOptionsEnabled(prev)=" + mDevOptionsEnabled);
+        mDevOptionsEnabled = devOptionsEnabled;
+        if (mAdbDisabledDialog == null) {
+            mAdbDisabledDialog = new AlertDialog.Builder(activity)
+                    .setPositiveButton(R.string.dlg_env_not_ready_positive,
+                            (d, w) -> {
+                                try {
+                                    Log.i(TAG, "AdbDisabledDialog positive clicked:"
+                                            + " mDevOptionsEnabled=" + mDevOptionsEnabled);
+                                    Intent intent;
+                                    if (mDevOptionsEnabled) {
+                                        intent = new Intent(
+                                                Settings.ACTION_APPLICATION_DEVELOPMENT_SETTINGS);
+                                    } else {
+                                        intent = new Intent(
+                                                android.provider.Settings.ACTION_DEVICE_INFO_SETTINGS);
+                                    }
+                                    startActivity(intent);
+                                } catch (ActivityNotFoundException e) {
+                                    Log.w(TAG, "No settings activity", e);
+                                }
+                            })
+                    .setNegativeButton(android.R.string.cancel, null)
+                    .create();
+        }
+        mAdbDisabledDialog.setTitle(R.string.dlg_env_not_ready_title);
+        mAdbDisabledDialog.setMessage(getActivity().getString(R.string.dlg_env_not_ready_desc));
+        mAdbDisabledDialog.show();
+    }
+
     protected void setupServer() {
         mServer = new Server();
         mServer.setListener(new Server.ServerListener() {
@@ -654,7 +703,7 @@ public void onUninstallResult(boolean result) {
         }
 
         @Override
-        public void onError(final int code) {
+        public void onError(final int code, final Bundle extras) {
             final Activity activity = getActivity();
             if (activity == null) {
                 return;
@@ -670,6 +719,13 @@ public void run() {
                         case AppDebugManager.ERROR_CODE_GET_RPK_FILE_FAILED:
                             showGetRpkErrorDialog();
                             break;
+                        case AppDebugManager.SERVICE_CODE_ADB_NOT_ENABLED:
+                        case AppDebugManager.SERVICE_CODE_DEV_OPTIONS_DISABLED:
+                            boolean devOptionsEnabled = extras != null
+                                    && extras.getBoolean(
+                                            AppDebugManager.EXTRA_DEV_OPTIONS_ENABLED, false);
+                            showAdbDisabledDialog(devOptionsEnabled);
+                            break;
                         case AppDebugManager.ERROR_CODE_FAIL_TO_SAVE_LOCAL_FILE:  // fallthrough
                         case AppDebugManager.ERROR_CODE_FAIL_TO_CREATE_TEMP_FILE: // fallthrough
                         case AppDebugManager.ERROR_CODE_GET_PACKAGE_INFO_FAIL: // fallthrough

diff --git a/debug/shell/android/app-impl/src/main/res/values-zh-rCN/strings.xml b/debug/shell/android/app-impl/src/main/res/values-zh-rCN/strings.xml
@@ -68,6 +68,9 @@
         \n\n2. 是否已经执行\"npm run server\"命令
         \n\n3. hap-toolkit版本是否支持USB调试
         \n\n4. 开发者选项中的USB调试是否打开</string>
+    <string name="dlg_env_not_ready_title">快应用调试环境未就绪</string>
+    <string name="dlg_env_not_ready_desc">快应用调试需开启USB调试。请按以下步骤操作：\n\n第一步：进入\"设置\"＞\"关于手机\"；\n\n第二步：连续点击\"软件版本号\"7次；\n\n第三步：看到提示\"已显示开发者选项入口\"后，返回\"设置\"；\n\n第四步：在\"设置\"中搜索\"开发者选项\"；\n\n第五步：开启\"开发者选项\"总开关，并开启\"USB调试\"。</string>
+    <string name="dlg_env_not_ready_positive">去设置</string>
     <string name="dlg_hint_downloading">正在下载...</string>
     <string name="dlg_universal_scan_confirm_title">是否启动快应用？</string>
 

diff --git a/debug/shell/android/app-impl/src/main/res/values/strings.xml b/debug/shell/android/app-impl/src/main/res/values/strings.xml
@@ -69,6 +69,9 @@
         \n\n2. whether \"npm run server\" command has been executed
         \n\n3. whether the hap-toolkit supports USB debugging
         \n\n4. whether the USB debugging in developer options is checked</string>
+    <string name="dlg_env_not_ready_title">Quick app debug environment not ready</string>
+    <string name="dlg_env_not_ready_desc">Quick app debugging requires USB debugging. Please follow these steps:\n\nStep 1: Open \"Settings\" ＞ \"About phone\";\n\nStep 2: Tap \"Software version\" 7 times continuously;\n\nStep 3: After seeing \"Developer options entry shown\", return to \"Settings\";\n\nStep 4: Search \"Developer options\" in \"Settings\";\n\nStep 5: Enable the \"Developer options\" master switch, then enable \"USB debugging\".</string>
+    <string name="dlg_env_not_ready_positive">Go to Settings</string>
     <string name="dlg_hint_downloading">Downloading...</string>
     <string name="dlg_universal_scan_confirm_title">Do you want to enable Instant Apps?</string>