feat(desktop): Octop 桌面客户端

.github/workflows/octop-desktop.yml

@@ -0,0 +1,301 @@
+name: Octop Desktop Package
+
+on:
+  push:
+    tags:
+      - "*"
+    branches:
+      - "*"
+  workflow_dispatch:
+    inputs:
+      platforms:
+        description: "Comma-separated plats, or 'all'"
+        required: true
+        default: "all"
+        type: string
+      attach_release:
+        description: "If running on a v* tag, also upload zips to that GitHub Release"
+        required: false
+        default: true
+        type: boolean
+      release_tag:
+        description: "GitHub Release tag to attach to (e.g. v0.9.27). Defaults to the current v* tag ref."
+        required: false
+        default: ""
+        type: string
+      attach_from_run:
+        description: "Existing workflow run ID — attach its Octop-* artifacts and skip the 6-platform rebuild"
+        required: false
+        default: ""
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: green-portable-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Prefer GitHub upstream on Actions runners (npmmirror is for CN local builds).
+  PBS_BASE_URL: https://github.com/astral-sh/python-build-standalone/releases/download/20251209
+  PBS_TAG: "20251209"
+  PBS_PY: "3.12.12"
+
+jobs:
+  frontend:
+    name: Build dashboard
+    if: github.event_name != 'workflow_dispatch' || github.event.inputs.attach_from_run == ''
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: dashboard/package-lock.json
+
+      - name: Build frontend → src/octop/dashboard
+        run: make build-frontend
+
+      - uses: actions/upload-artifact@v5
+        with:
+          name: dashboard-dist
+          path: src/octop/dashboard/
+          if-no-files-found: error
+          retention-days: 7
+
+  package:
+    name: "${{ matrix.plat }}"
+    needs: frontend
+    runs-on: ${{ matrix.os }}
+    # Matrix runners are native for each plat; pin host detection so x64 Git Bash
+    # on windows-11-arm does not mis-classify the job as windows-amd64 cross-build.
+    env:
+      GREEN_HOST_PLAT: ${{ matrix.plat }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - plat: linux-amd64
+            arch: amd64
+            os: ubuntu-latest
+          - plat: linux-arm64
+            arch: arm64
+            os: ubuntu-24.04-arm
+          - plat: darwin-arm64
+            arch: arm64
+            os: macos-14
+          - plat: darwin-amd64
+            arch: amd64
+            os: macos-15-intel
+          - plat: windows-amd64
+            arch: amd64
+            os: windows-latest
+          - plat: windows-arm64
+            arch: arm64
+            os: windows-11-arm
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Decide whether to build this platform
+        id: want
+        run: |
+          set -euo pipefail
+          sel="${{ github.event.inputs.platforms || 'all' }}"
+          sel="$(echo "$sel" | tr '[:upper:]' '[:lower:]' | tr -d ' ')"
+          plat="${{ matrix.plat }}"
+          if [[ "$sel" == "all" || ",$sel," == *",$plat,"* ]]; then
+            echo "build=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "build=false" >> "$GITHUB_OUTPUT"
+            echo "Skipping ${plat} (selection=${sel})"
+          fi
+
+      - uses: actions/download-artifact@v5
+        if: steps.want.outputs.build == 'true'
+        with:
+          name: dashboard-dist
+          path: src/octop/dashboard
+
+      - uses: astral-sh/setup-uv@v6
+        if: steps.want.outputs.build == 'true'
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      # GitHub Cache outages must not fail the build — PBS download is cheap enough.
+      - name: Cache python-build-standalone downloads
+        if: steps.want.outputs.build == 'true'
+        continue-on-error: true
+        uses: actions/cache@v5
+        with:
+          path: green/.cache
+          key: pbs-${{ env.PBS_TAG }}-${{ env.PBS_PY }}-${{ matrix.plat }}
+
+      - name: Bootstrap portable CPython
+        if: steps.want.outputs.build == 'true'
+        env:
+          GREEN_HOST_PLAT: ${{ matrix.plat }}
+        run: bash desktop/portable/bootstrap-runtime.sh "${{ matrix.plat }}"
+
+      - name: Assemble green zip
+        if: steps.want.outputs.build == 'true'
+        env:
+          GREEN_HOST_PLAT: ${{ matrix.plat }}
+        run: |
+          set -euo pipefail
+          echo "GREEN_HOST_PLAT=${GREEN_HOST_PLAT} RUNNER_ARCH=${RUNNER_ARCH:-} uname=$(uname -ms)"
+          bash desktop/portable/package.sh "${{ matrix.plat }}"
+
+      - name: Smoke import (native host only)
+        if: steps.want.outputs.build == 'true'
+        run: |
+          set -euo pipefail
+          staging="desktop/portable/release/Octop-${{ matrix.plat }}"
+          if [[ -x "${staging}/runtime/bin/python3" ]]; then
+            py="${staging}/runtime/bin/python3"
+          elif [[ -f "${staging}/runtime/python.exe" ]]; then
+            py="${staging}/runtime/python.exe"
+          else
+            echo "python missing under ${staging}/runtime" >&2
+            exit 1
+          fi
+          req_file="desktop/portable/requirements-${{ matrix.plat }}.txt"
+          if [[ ! -f "$req_file" ]]; then
+            echo "frozen requirements missing: ${req_file}" >&2
+            exit 1
+          fi
+          verify_args=(
+            --packages "${staging}/packages"
+            --requirements "$req_file"
+          )
+          override_file="desktop/portable/overrides-${{ matrix.plat }}.txt"
+          if [[ -f "$override_file" ]]; then
+            verify_args+=(--overrides "$override_file")
+          fi
+          PYTHONNOUSERSITE=1 \
+            "$py" desktop/portable/verify_imports.py \
+              "${verify_args[@]}"
+          # macOS: fail if any native extension linked Homebrew/MacPorts paths.
+          if [[ "${{ matrix.plat }}" == darwin-* ]]; then
+            REPO_ROOT="$PWD" # shellcheck source=desktop/portable/_common.sh
+            source desktop/portable/_common.sh
+            verify_no_homebrew_dylibs "${staging}/packages" "${{ matrix.plat }}"
+          fi
+
+      - uses: actions/setup-go@v6
+        if: steps.want.outputs.build == 'true'
+        with:
+          go-version: "1.25.x"
+          cache-dependency-path: desktop/src/go.sum
+
+      - name: Install Linux desktop build dependencies
+        if: steps.want.outputs.build == 'true' && runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libgtk-4-dev libwebkitgtk-6.0-dev
+
+      - name: Install Wails v3 CLI
+        if: steps.want.outputs.build == 'true'
+        run: go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-beta.13
+
+      - name: Package desktop app with bundled portable runtime
+        if: steps.want.outputs.build == 'true'
+        working-directory: desktop/src
+        run: >-
+          wails3 task package
+          ARCH=${{ matrix.arch }}
+          PORTABLE_ZIP=../portable/release/Octop-${{ matrix.plat }}.zip
+
+      # archive: false — upload the prebuilt zip as-is. Default archive=true would
+      # wrap it again, so Actions UI / "Download artifact" becomes zip-in-zip
+      # (Octop-<plat>.zip containing another Octop-<plat>.zip). Affects every plat.
+      # With archive:false, artifact name is the filename (name: is ignored).
+      - uses: actions/upload-artifact@v7
+        if: steps.want.outputs.build == 'true'
+        with:
+          path: desktop/portable/release/Octop-${{ matrix.plat }}.zip
+          archive: false
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Upload bundled desktop package
+        if: steps.want.outputs.build == 'true'
+        uses: actions/upload-artifact@v7
+        with:
+          path: desktop/src/bin/Octop-Desktop-${{ matrix.plat }}.*
+          archive: false
+          if-no-files-found: error
+          retention-days: 14
+
+  release:
+    name: Attach zips to GitHub Release
+    needs: package
+    # always(): still run when package was skipped (attach_from_run rebuild skip).
+    if: >-
+      always() &&
+      !cancelled() &&
+      (needs.package.result == 'success' || needs.package.result == 'skipped') &&
+      (
+        (github.event_name == 'workflow_dispatch' &&
+         github.event.inputs.attach_from_run != '') ||
+        (startsWith(github.ref, 'refs/tags/v') &&
+         (github.event_name == 'push' ||
+          (github.event_name == 'workflow_dispatch' &&
+           github.event.inputs.attach_release == 'true')))
+      )
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      actions: read
+    steps:
+      - name: Resolve release tag
+        id: rel
+        run: |
+          set -euo pipefail
+          tag="${{ github.event.inputs.release_tag }}"
+          if [[ -z "$tag" && "${GITHUB_REF}" == refs/tags/v* ]]; then
+            tag="${GITHUB_REF_NAME}"
+          fi
+          if [[ "$tag" != v* ]]; then
+            echo "Need a v* tag (run on a version tag, or pass release_tag)." >&2
+            exit 1
+          fi
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+
+      # v8 required for archive:false artifacts. skip-decompress keeps the
+      # uploaded .zip / .tar / .dmg / .exe intact — default unzip turns portable
+      # zips into directories, so files: release-assets/* would skip them.
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: Octop-*
+          path: release-assets
+          merge-multiple: true
+          skip-decompress: true
+          repository: ${{ github.repository }}
+          run-id: ${{ github.event.inputs.attach_from_run || github.run_id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: List release assets
+        run: |
+          set -euo pipefail
+          ls -lh release-assets/
+          if find release-assets -mindepth 1 -maxdepth 1 -type d | grep -q .; then
+            echo "Download extracted archives into directories; refuse incomplete attach." >&2
+            find release-assets -mindepth 1 -maxdepth 1 -print
+            exit 1
+          fi
+
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.rel.outputs.tag }}
+          files: release-assets/*
+          fail_on_unmatched_files: true
+          # Upsert: works whether Release workflow already created the release.
+          generate_release_notes: false

.gitignore

@@ -20,6 +20,8 @@ __pycache__/
 *.so
 .Python
 build/
+!desktop/src/build/
+!desktop/src/build/**
 dist/
 *.egg-info/
 *.egg

dashboard/src/App.tsx

@@ -19,6 +19,7 @@ import { LayoutModeProvider } from "./context/LayoutModeContext";
 import { VoiceOutputProvider } from "./context/VoiceOutputContext";
 import { useIsMobile } from "./hooks/useIsMobile";
 import { useUnauthorizedRedirect } from "./hooks/useUnauthorizedRedirect";
+import { installDesktopExternalLinks } from "./utils/desktopExternalLinks";
 import { brandTokensFor } from "./styles/themePalettes";
 import "./styles/theme-vars.css";
 import "./styles/layout.css";
@@ -44,6 +45,8 @@ function ThemedApp() {
 
   useUnauthorizedRedirect();
 
+  useEffect(() => installDesktopExternalLinks(), []);
+
   // Set document title based on current language
   useEffect(() => {
     document.title = t("app.pageTitle");