docs: OpenWiki-Dokumentation und Auto-Update-Workflow hinzufügen

Fügt generierte OpenWiki-Docs (Architektur, Domain, Betrieb, Tests, Workflows) sowie den GitHub-Actions-Workflow zur automatischen Aktualisierung hinzu. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-23 14:53:30 +02:00
parent c69dddd8f5
commit 66ecf55ea9
18 changed files with 780 additions and 0 deletions
@@ -0,0 +1,3 @@
+# Files
+
+- [Operations-Runbook](runbook.md) - Konfiguration, Autostart, Build/Packaging, CI/CD und Versionsverwaltung für whisper-local. Praktische Anleitungen für Betrieb und Release.
@@ -0,0 +1,110 @@
+---
+type: Runbook
+title: Operations-Runbook
+description: Konfiguration, Autostart, Build/Packaging, CI/CD und Versionsverwaltung für whisper-local. Praktische Anleitungen für Betrieb und Release.
+tags: [operations, runbook, config, autostart, build, packaging, ci, versioning]
+---
+
+# Operations-Runbook
+
+## Konfiguration
+
+Die Konfiguration liegt als TOML-Datei:
+
+- **Linux**: `~/.config/whisper-local/config.toml`
+- **Windows**: `%APPDATA%\whisper-local\config.toml`
+
+Die Datei wird beim ersten Start automatisch mit Defaults angelegt. Vorlage: [`config.example.toml`](../../config.example.toml).
+
+### Sektionen
+
+| Sektion | Schlüssel | Default | Beschreibung |
+|---|---|---|---|
+| `[hotkey]` | `key` | `KEY_F12` | Hotkey im evdev-Format — auch unter Windows |
+| `[whisper]` | `model` | `small` | faster-whisper Modellname |
+| `[whisper]` | `language` | `de` | Sprache für Transkription |
+| `[whisper]` | `compute_type` | `int8` | Compute-Typ (CPU-optimiert) |
+| `[audio]` | `sample_rate` | `16000` | Abtastrate in Hz |
+| `[audio]` | `channels` | `1` | Anzahl Kanäle (Mono) |
+| `[audio]` | `min_duration` | `0.5` | Mindestdauer in Sekunden — kürzere Aufnahmen werden verworfen |
+| `[audio]` | `device` | `""` | Mikrofon-Gerätename (leer = Standardgerät) |
+| `[media]` | `pause_during_recording` | `true` | Medien während Aufnahme pausieren |
+
+### Config-Quellcode
+
+[`config.py`](../../whisper_local/config.py) enthält `Config`-Dataclass, `load_config()` und `save_config()`. TOML-Strings werden via `_toml_str()` escaped (Backslash und Quotes), um ungültiges TOML bei Sonderzeichen zu verhindern.
+
+### Einstellungs-Dialog
+
+Rechtsklick auf das Tray-Icon → „Einstellungen". Der Dialog ([`_settings.py`](../../whisper_local/tray/_settings.py)) bietet:
+
+- **Hotkey-Aufzeichnung**: Taste drücken → evdev-Name wird erfasst. Unter Windows zusätzlich Konflikt-Erkennung via Win32 `RegisterHotKey`.
+- **Mikrofon-Auswahl**: Dropdown aller Eingabegeräte via `sounddevice.query_devices()`.
+- **Medien-Pause**: Checkbox für `pause_during_recording`.
+
+Änderungen greifen sofort via `_on_config_reload()` — kein Neustart erforderlich. Siehe [Aufnahme-Zyklus → Config-Reload](../workflows/recording-cycle.md#config-reload-zur-laufzeit).
+
+## Autostart
+
+### Linux (systemd user unit)
+
+```bash
+mkdir -p ~/.config/systemd/user
+cp systemd/whisper-local.service ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now whisper-local.service
+```
+
+Das `whisper-local`-Executable muss in `~/.local/bin` verfügbar sein (`uv tool install .` oder Pfad in der Unit anpassen). Die Unit startet nach `graphical-session.target` und restartet bei Fehlern.
+
+### Windows
+
+Kein integrierter Autostart-Mechanismus. Möglichkeit: Verknüpfung zur `whisper-local.exe` im Autostart-Ordner (`%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup`).
+
+## Build und Packaging (Windows)
+
+### PyInstaller-Build
+
+```powershell
+.\build.ps1              # Build + ZIP
+.\build.ps1 -Clean       # dist/ und build/ löschen, dann Build
+.\build.ps1 -SkipBuild   # Nur ZIP aus bestehendem dist/ erstellen
+```
+
+`build.ps1` liest die Version aus `pyproject.toml`, führt `uv sync --group build` aus, startet PyInstaller mit `whisper_local.spec` und erstellt ein versioniertes ZIP (`whisper-local-v{version}-win64.zip`).
+
+Die PyInstaller-Spec ([`whisper_local.spec`](../../whisper_local.spec)) bündelt:
+
+- **ctranslate2**-DLLs (Haupt-DLL, cuDNN, Intel OpenMP)
+- **pywin32**-System-DLLs (`pythoncom313.dll`, `pywintypes313.dll`)
+- **PortAudio**-Binaries für `sounddevice`
+- **onnxruntime** (für Silero VAD in faster-whisper)
+- **av/FFmpeg**-DLLs (per Glob gesammelt)
+- **sv_ttk** Theme-Daten, **Silero VAD** ONNX-Modell
+
+Im gebündelten Modus (`sys.frozen`) cacht `Transcriber._model_cache_dir()` das Whisper-Modell neben der EXE im `models/`-Verzeichnis (portabel).
+
+## CI/CD
+
+### OpenWiki-Aktualisierung
+
+`.github/workflows/openwiki-update.yml` führt täglich um 08:00 Uhr (`cron: "0 8 * * *"`) oder manuell (`workflow_dispatch`) ein OpenWiki-Doku-Update durch. Der Workflow:
+
+1. Installiert OpenWiki via `npm install --global openwiki`.
+2. Führt `openwiki code --update --print` aus (mit OpenRouter als Provider).
+3. Erstellt einen Pull-Request via `peter-evans/create-pull-request@v7` auf Branch `openwiki/update`.
+
+Erforderliche Secrets: `OPENROUTER_API_KEY`, `LANGSMITH_API_KEY`.
+
+## Versionsverwaltung
+
+Version steht in `pyproject.toml` (`version = "1.3.0"`). Der [bump-version-Skill](../../.claude/skills/bump-version/SKILL.md) automatisiert SemVer-Bumps:
+
+```bash
+uv version --bump patch    # 1.3.0 → 1.3.1
+uv version --bump minor    # 1.3.0 → 1.4.0
+uv version --bump major    # 1.3.0 → 2.0.0
+uv version 2.0.0           # explizite Version
+```
+
+Nach dem Bump wird ein Git-Commit und Tag erstellt. Der Skill ist für Claude-Code-Sessions konzipiert und fragt bei Commit-Anfragen, ob die Version mit aktualisiert werden soll.