docs: 重写用户使用 README

Author: cimorn

.gitattributes

@@ -0,0 +1,2 @@
+* text=auto
+

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: windows-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        shell: pwsh
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Run tests
+        shell: pwsh
+        run: |
+          python -m pytest tests -q

.github/workflows/release.yml

@@ -0,0 +1,121 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag. Leave empty to update latest."
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  build-windows:
+    runs-on: windows-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+
+      - name: Enable pnpm
+        shell: pwsh
+        run: |
+          corepack enable
+          corepack prepare pnpm@10 --activate
+
+      - name: Install dependencies
+        shell: pwsh
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+          pnpm install --frozen-lockfile
+
+      - name: Run tests
+        shell: pwsh
+        run: |
+          python -m pytest tests -q
+
+      - name: Build Electron package
+        shell: pwsh
+        run: |
+          pnpm run electron:pack
+
+      - name: Upload release artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: weekflow-windows-release
+          path: |
+            dist/WeekFlow-V*.zip
+
+  publish-release:
+    runs-on: ubuntu-latest
+    needs:
+      - build-windows
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Resolve release tag
+        id: release
+        shell: bash
+        run: |
+          PACKAGE_VERSION="$(python -c 'import json; print(json.load(open("package.json", encoding="utf-8"))["version"])')"
+          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" && -n "${{ inputs.tag }}" ]]; then
+            TAG_NAME="${{ inputs.tag }}"
+          elif [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            TAG_NAME="${GITHUB_REF_NAME}"
+          else
+            TAG_NAME="latest"
+          fi
+          TITLE="WeekFlow-V$PACKAGE_VERSION"
+          echo "tag_name=$TAG_NAME" >> "$GITHUB_OUTPUT"
+          echo "title=$TITLE" >> "$GITHUB_OUTPUT"
+
+      - name: Download built artifacts
+        uses: actions/download-artifact@v6
+        with:
+          path: release-assets
+          merge-multiple: true
+
+      - name: Publish GitHub release assets
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG_NAME: ${{ steps.release.outputs.tag_name }}
+          TITLE: ${{ steps.release.outputs.title }}
+        run: |
+          ls -la release-assets
+          if gh release view "$TAG_NAME" --repo "$GH_REPO" >/dev/null 2>&1; then
+            gh release edit "$TAG_NAME" --repo "$GH_REPO" --title "$TITLE"
+            if [[ "$TAG_NAME" == "latest" ]]; then
+              gh api --method PATCH "repos/$GH_REPO/git/refs/tags/$TAG_NAME" -f sha="$GITHUB_SHA" -F force=true
+            fi
+            gh release view "$TAG_NAME" --repo "$GH_REPO" --json assets --jq '.assets[].name' |
+              while read -r asset_name; do
+                if [[ "$asset_name" == WeekFlow-* ]]; then
+                  gh release delete-asset "$TAG_NAME" "$asset_name" --repo "$GH_REPO" --yes
+                fi
+              done
+            gh release upload "$TAG_NAME" release-assets/* --repo "$GH_REPO" --clobber
+          else
+            gh release create "$TAG_NAME" release-assets/* --repo "$GH_REPO" --title "$TITLE" --generate-notes --latest
+          fi

.gitignore

@@ -0,0 +1,26 @@
+# Local Python environments and caches
+.venv/
+.worktrees/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+# Build outputs
+build/
+dist/
+dist-electron/
+releases/
+WeekFlow.spec
+
+# JavaScript/Electron dependencies
+node_modules/
+# Local environment files
+.env
+
+# OS-generated files
+.DS_Store
+Thumbs.db
+
+# Generated app icons
+src/weekflow_logo.icns

.scripts/build_electron_bridge.ps1

@@ -0,0 +1,53 @@
+$ErrorActionPreference = "Stop"
+
+$root = Split-Path -Parent $PSScriptRoot
+Set-Location $root
+
+$python = ".\.venv\Scripts\python.exe"
+if (-not (Test-Path $python)) {
+    $python = "python"
+}
+
+$src = Join-Path $root "src\WeekFlow\electron_bridge.py"
+$distPath = Join-Path $root "dist\bridge"
+$workPath = Join-Path $root "build\electron-bridge"
+$iconPath = Join-Path $root "src\weekflow_logo.ico"
+
+if (-not (Test-Path $src)) {
+    throw "Electron bridge entry not found at $src"
+}
+
+if (Test-Path $distPath) {
+    Remove-Item -LiteralPath $distPath -Recurse -Force
+}
+
+$args = @(
+    "-m", "PyInstaller",
+    "--noconfirm",
+    "--clean",
+    "--onefile",
+    "--name", "WeekFlowBridge",
+    "--distpath", $distPath,
+    "--workpath", $workPath,
+    "--specpath", $workPath,
+    "--paths", (Join-Path $root "src")
+)
+
+if (Test-Path $iconPath) {
+    $args += @("--icon", $iconPath)
+}
+
+$args += $src
+
+& $python @args
+
+$bridgeExe = Join-Path $distPath "WeekFlowBridge.exe"
+if (-not (Test-Path $bridgeExe)) {
+    throw "Electron bridge build did not create $bridgeExe"
+}
+
+if (Test-Path $workPath) {
+    Remove-Item -LiteralPath $workPath -Recurse -Force
+}
+
+Write-Output $bridgeExe

.scripts/build_exe.ps1

@@ -0,0 +1,27 @@
+$ErrorActionPreference = "Stop"
+
+$root = Split-Path -Parent $PSScriptRoot
+Set-Location $root
+
+$python = ".\.venv\Scripts\python.exe"
+if (-not (Test-Path $python)) {
+    $python = "python"
+}
+
+$icoIcon = Join-Path $root "src\weekflow_logo.ico"
+
+if (-not (Test-Path $icoIcon)) {
+    throw "App icon not found at $icoIcon"
+}
+
+& $python -m PyInstaller `
+    --noconfirm `
+    --clean `
+    --windowed `
+    --name WeekFlow `
+    --icon $icoIcon `
+    --add-data "src\weekflow_logo.ico;src" `
+    run_app.py
+
+$appDataDir = Join-Path $root "dist\WeekFlow\data"
+New-Item -ItemType Directory -Force -Path $appDataDir | Out-Null

.scripts/build_macos_app.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+PYTHON_BIN="$ROOT/.venv/bin/python"
+ICO_ICON="$ROOT/src/weekflow_logo.ico"
+ICNS_ICON="$ROOT/src/weekflow_logo.icns"
+
+if [[ ! -x "$PYTHON_BIN" ]]; then
+  echo "Project virtual environment not found. Create .venv and install dependencies first." >&2
+  exit 1
+fi
+
+if [[ ! -f "$ICO_ICON" ]]; then
+  echo "App icon not found at $ICO_ICON" >&2
+  exit 1
+fi
+
+"$PYTHON_BIN" "$ROOT/.scripts/export_app_icon.py" "$ICO_ICON" "$ICNS_ICON"
+
+"$PYTHON_BIN" -m PyInstaller \
+  --noconfirm \
+  --clean \
+  --windowed \
+  --name WeekFlow \
+  --icon "$ICNS_ICON" \
+  --add-data "src/weekflow_logo.ico:src" \
+  --osx-bundle-identifier "com.cimorn.weekflow" \
+  run_app.py

.scripts/export_app_icon.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from PySide6.QtCore import QRectF, Qt
+from PySide6.QtGui import QColor, QGuiApplication, QImage, QPainter
+from PySide6.QtSvg import QSvgRenderer
+
+
+FORMAT_BY_SUFFIX = {
+    ".ico": "ICO",
+    ".icns": "ICNS",
+}
+
+
+def export_icon(source: Path, destination: Path, size: int = 256) -> None:
+    image_format = FORMAT_BY_SUFFIX.get(destination.suffix.lower())
+    if image_format is None:
+        supported = ", ".join(sorted(FORMAT_BY_SUFFIX))
+        raise RuntimeError(f"Unsupported icon format for {destination}. Expected one of: {supported}")
+
+    if source.suffix.lower() == ".svg":
+        renderer = QSvgRenderer(str(source))
+        if not renderer.isValid():
+            raise RuntimeError(f"Invalid SVG icon: {source}")
+
+        image = QImage(size, size, QImage.Format_ARGB32)
+        image.fill(Qt.GlobalColor.transparent)
+
+        painter = QPainter(image)
+        try:
+            painter.setRenderHint(QPainter.RenderHint.Antialiasing, True)
+            painter.setRenderHint(QPainter.RenderHint.SmoothPixmapTransform, True)
+            painter.fillRect(image.rect(), QColor(0, 0, 0, 0))
+            renderer.render(painter, QRectF(0, 0, size, size))
+        finally:
+            painter.end()
+    else:
+        image = QImage(str(source))
+        if image.isNull():
+            raise RuntimeError(f"Invalid icon source: {source}")
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    if not image.save(str(destination), image_format):
+        raise RuntimeError(f"Failed to write icon file: {destination}")
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        raise SystemExit("Usage: export_app_icon.py <source-image> <destination-icon>")
+
+    app = QGuiApplication([])
+    source = Path(sys.argv[1]).resolve()
+    destination = Path(sys.argv[2]).resolve()
+    export_icon(source, destination)
+    app.quit()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())