From 184556140560e2ae59c67f8adc35744fbe5a4e7e Mon Sep 17 00:00:00 2001 From: Your Name Date: Mon, 1 Jun 2026 18:20:10 +0800 Subject: [PATCH] docs: add quick deploy txt and one-click dependency bootstrap --- bootstrap_deps.bat | 36 +++++ bootstrap_deps.py | 239 +++++++++++++++++++++++++++++++++ docs/README.md | 1 + docs/deployment_quickstart.txt | 111 +++++++++++++++ 4 files changed, 387 insertions(+) create mode 100644 bootstrap_deps.bat create mode 100644 bootstrap_deps.py create mode 100644 docs/deployment_quickstart.txt diff --git a/bootstrap_deps.bat b/bootstrap_deps.bat new file mode 100644 index 0000000..bd25ac8 --- /dev/null +++ b/bootstrap_deps.bat @@ -0,0 +1,36 @@ +@echo off +setlocal + +pushd "%~dp0" >nul 2>&1 +if errorlevel 1 ( + echo [ERROR] Failed to change to script directory. + exit /b 1 +) + +set "BOOTSTRAP_SCRIPT=bootstrap_deps.py" +if not exist "%BOOTSTRAP_SCRIPT%" ( + echo [ERROR] Missing %BOOTSTRAP_SCRIPT% in project root. + popd >nul 2>&1 + exit /b 1 +) + +where py >nul 2>&1 +if not errorlevel 1 ( + py -3 "%BOOTSTRAP_SCRIPT%" %* + set "EXIT_CODE=%ERRORLEVEL%" + goto :done +) + +where python >nul 2>&1 +if errorlevel 1 ( + echo [ERROR] Python launcher not found. Install Python 3.10+ and add it to PATH. + popd >nul 2>&1 + exit /b 1 +) + +python "%BOOTSTRAP_SCRIPT%" %* +set "EXIT_CODE=%ERRORLEVEL%" + +:done +popd >nul 2>&1 +exit /b %EXIT_CODE% diff --git a/bootstrap_deps.py b/bootstrap_deps.py new file mode 100644 index 0000000..b3ca550 --- /dev/null +++ b/bootstrap_deps.py @@ -0,0 +1,239 @@ +#!/usr/bin/env python3 +""" +One-click dependency bootstrap for this repository. + +Default behavior: +1. Create/update a virtual environment at .venv +2. Upgrade pip/setuptools/wheel in that environment +3. Install dependencies from requirements.txt + +Examples: + python bootstrap_deps.py + python bootstrap_deps.py --minimal + python bootstrap_deps.py --no-venv + python bootstrap_deps.py --index-url https://pypi.tuna.tsinghua.edu.cn/simple +""" + +from __future__ import annotations + +import argparse +import shlex +import subprocess +import sys +from pathlib import Path +from typing import Iterable, Sequence + + +def _echo(message: str) -> None: + print(message, flush=True) + + +def _format_cmd(cmd: Sequence[str]) -> str: + return " ".join(shlex.quote(part) for part in cmd) + + +def _run(cmd: Sequence[str], *, cwd: Path, dry_run: bool = False) -> None: + _echo(f"$ {_format_cmd(cmd)}") + if dry_run: + return + subprocess.run(cmd, cwd=str(cwd), check=True) + + +def _resolve_requirements(repo_root: Path, args: argparse.Namespace) -> Path: + if args.requirements: + req = Path(args.requirements).expanduser() + if not req.is_absolute(): + req = repo_root / req + else: + req_name = "requirements-minimal.txt" if args.minimal else "requirements.txt" + req = repo_root / req_name + return req.resolve() + + +def _resolve_venv_python(venv_dir: Path) -> Path: + candidates = ( + venv_dir / "Scripts" / "python.exe", + venv_dir / "Scripts" / "python", + venv_dir / "bin" / "python", + ) + for candidate in candidates: + if candidate.exists(): + return candidate.resolve() + raise FileNotFoundError( + f"Could not find a Python executable in virtual environment: {venv_dir}" + ) + + +def _build_pip_index_args(args: argparse.Namespace) -> list[str]: + pip_args: list[str] = [] + if args.index_url: + pip_args += ["--index-url", args.index_url] + for item in args.extra_index_url: + pip_args += ["--extra-index-url", item] + for item in args.trusted_host: + pip_args += ["--trusted-host", item] + if args.no_cache_dir: + pip_args.append("--no-cache-dir") + if args.prefer_binary: + pip_args.append("--prefer-binary") + return pip_args + + +def _validate_python_version() -> None: + if sys.version_info < (3, 10): + raise RuntimeError( + f"Python 3.10+ is required. Current interpreter: {sys.version.split()[0]}" + ) + + +def _parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description="Bootstrap project dependencies in a migration-friendly way." + ) + parser.add_argument( + "--venv-dir", + default=".venv", + help="Virtual environment directory (default: .venv).", + ) + parser.add_argument( + "--no-venv", + action="store_true", + help="Install into the current Python environment instead of creating/using a venv.", + ) + parser.add_argument( + "--python", + default="", + help="Python executable used to create the virtual environment.", + ) + parser.add_argument( + "--minimal", + action="store_true", + help="Install requirements-minimal.txt instead of requirements.txt.", + ) + parser.add_argument( + "--requirements", + default="", + help="Custom requirements file path (overrides --minimal).", + ) + parser.add_argument( + "--skip-pip-upgrade", + action="store_true", + help="Skip upgrading pip/setuptools/wheel.", + ) + parser.add_argument( + "--index-url", + default="", + help="Base package index URL for pip install.", + ) + parser.add_argument( + "--extra-index-url", + action="append", + default=[], + help="Extra package index URL for pip install (repeatable).", + ) + parser.add_argument( + "--trusted-host", + action="append", + default=[], + help="Trusted host passed to pip install (repeatable).", + ) + parser.add_argument( + "--no-cache-dir", + action="store_true", + help="Pass --no-cache-dir to pip.", + ) + parser.add_argument( + "--prefer-binary", + action="store_true", + help="Prefer binary wheels when possible.", + ) + parser.add_argument( + "--dry-run", + action="store_true", + help="Print commands without executing them.", + ) + return parser.parse_args() + + +def main() -> int: + _validate_python_version() + args = _parse_args() + repo_root = Path(__file__).resolve().parent + requirements_path = _resolve_requirements(repo_root, args) + + if not requirements_path.exists(): + raise FileNotFoundError(f"Requirements file not found: {requirements_path}") + + if args.no_venv: + install_python = Path(sys.executable).resolve() + _echo(f"Using current interpreter: {install_python}") + else: + venv_dir = Path(args.venv_dir).expanduser() + if not venv_dir.is_absolute(): + venv_dir = repo_root / venv_dir + creator_python = (args.python or sys.executable).strip() + + if not _resolve_venv_python_if_exists(venv_dir): + _echo(f"Creating virtual environment: {venv_dir}") + _run([creator_python, "-m", "venv", str(venv_dir)], cwd=repo_root, dry_run=args.dry_run) + else: + _echo(f"Virtual environment already exists: {venv_dir}") + + install_python = _resolve_venv_python(venv_dir) + _echo(f"Using virtual environment interpreter: {install_python}") + + pip_base = [str(install_python), "-m", "pip"] + pip_index_args = _build_pip_index_args(args) + + if not args.skip_pip_upgrade: + _echo("Upgrading pip, setuptools, and wheel...") + _run( + [*pip_base, "install", "--upgrade", "pip", "setuptools", "wheel", *pip_index_args], + cwd=repo_root, + dry_run=args.dry_run, + ) + + _echo(f"Installing dependencies from: {requirements_path}") + _run( + [*pip_base, "install", "-r", str(requirements_path), *pip_index_args], + cwd=repo_root, + dry_run=args.dry_run, + ) + + if not args.no_venv: + _echo("") + _echo("Done.") + if sys.platform.startswith("win"): + _echo(r"Activate with: .venv\Scripts\Activate.ps1") + else: + _echo("Activate with: source .venv/bin/activate") + else: + _echo("") + _echo("Done (installed into current interpreter).") + + return 0 + + +def _resolve_venv_python_if_exists(venv_dir: Path) -> Path | None: + candidates: Iterable[Path] = ( + venv_dir / "Scripts" / "python.exe", + venv_dir / "Scripts" / "python", + venv_dir / "bin" / "python", + ) + for candidate in candidates: + if candidate.exists(): + return candidate.resolve() + return None + + +if __name__ == "__main__": + try: + raise SystemExit(main()) + except subprocess.CalledProcessError as exc: + _echo("") + _echo(f"Command failed with exit code {exc.returncode}.") + raise SystemExit(exc.returncode) + except Exception as exc: # pragma: no cover - defensive entrypoint guard + _echo("") + _echo(f"Bootstrap failed: {exc}") + raise SystemExit(1) diff --git a/docs/README.md b/docs/README.md index bd0c969..67863c2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,7 @@ ### 入门与依赖 - **DEPENDENCY_GUIDE.md** - 依赖安装与版本说明 - **迁移部署指南.md** - 新电脑部署与手机端操作清单 +- **deployment_quickstart.txt** - 极简迁移说明(优先一键部署 + 手机导航栏教程) - **WiFi_ADB_使用指南.md** - WiFi ADB 连接指南 - **scrcpy_手动安装指南.md** - scrcpy 手动安装 - **核显GPU加速说明.md** - 核显 GPU 加速 diff --git a/docs/deployment_quickstart.txt b/docs/deployment_quickstart.txt new file mode 100644 index 0000000..7a85ff0 --- /dev/null +++ b/docs/deployment_quickstart.txt @@ -0,0 +1,111 @@ +Douyin Guaji - Quick Deployment (TXT) +===================================== + +Purpose +------- +This is the simplified migration guide. +Computer-side setup is kept minimal because one-click deploy scripts are already provided. + + +1) Computer (minimal) +--------------------- +Prerequisites: +- Windows 10/11 +- Python 3.10+ +- ADB (platform-tools) available in PATH + +In project root, run: + + bootstrap_deps.bat + +Optional: + + bootstrap_deps.bat --minimal + + +2) Phone required setup +----------------------- +2.1 Enable Developer options +- Open: Settings -> About phone +- Tap "Build number" 7 times +- Enter lock screen password if asked + +2.2 Enable USB debugging +- Open: Settings -> Developer options +- Turn on: + - USB debugging + - (if available) USB debugging (Security settings) / USB installation + +2.3 First USB authorization +- Connect phone to PC with USB cable +- Set USB mode to File Transfer (MTP) +- On phone popup "Allow USB debugging", tap Allow +- Verify on PC: + + adb devices + +Expected: + + device + +If status is "unauthorized", replug cable and approve popup again. + + +3) How to show the bottom navigation bar on phone (detailed) +------------------------------------------------------------- +This section is for the Android system navigation bar (Back / Home / Recents). + +Method A (standard Android path) +-------------------------------- +1. Open Settings +2. Search "Navigation mode" (or "System navigation") +3. Open the result and switch to: + - 3-button navigation (shows bottom buttons), or + - Gesture navigation (shows gesture bar/hint on some devices) + +Common path examples: +- Pixel / near-stock Android: + Settings -> System -> Navigation mode +- Some other ROMs: + Settings -> System -> Gestures -> Navigation mode + +Method B (common brand paths) +----------------------------- +- Samsung: + Settings -> Display -> Navigation bar -> Buttons +- Xiaomi / Redmi / POCO (MIUI / HyperOS): + Settings -> Home screen -> System navigation -> Buttons +- OPPO / OnePlus (ColorOS / OxygenOS): + Settings -> System settings -> System navigation -> Virtual buttons +- vivo / iQOO: + Settings -> System navigation -> Navigation keys +- Huawei / Honor: + Settings -> System & updates -> System navigation -> Three-key navigation + +If the bar still does not appear: +--------------------------------- +1. Disable any "Full screen gestures" option +2. Disable app-level full screen mode for the current app +3. Reboot phone once after switching navigation mode +4. Use Settings search with keywords: + - navigation + - system navigation + - gesture + +Temporary reveal tip: +--------------------- +If an app is full-screen and hides controls, swipe up from the very bottom edge once. +On many devices this temporarily shows system navigation controls. + + +4) Quick run check +------------------ +After dependencies are ready and ADB is authorized: + + python bin/gui_app.py + +Check: +- Device is visible in device selector +- Screenshot action works +- Start button can launch run loop +