102 lines
6.2 KiB
Markdown
102 lines
6.2 KiB
Markdown
## Context
|
|
TrueGrowth desktop already has a local API boundary, task center, Model Center, ComfyUI integration, FunClip-related readiness, social publishing bridge, and local persistence split between Electron `userData` and `.truegrowth-runtime`. Commercial delivery needs a first-run experience that treats these as one runtime estate instead of feature-by-feature setup fragments.
|
|
|
|
## Goals
|
|
- Provide one product-level runtime readiness summary in Model Center.
|
|
- Make first-run setup safe for Windows and macOS customers.
|
|
- Download Hugging Face model assets with realtime progress and resumable status.
|
|
- Prefer bundled or per-user managed dependencies over asking users to install developer tools manually.
|
|
- Keep heavy runtimes stopped until the user starts or initializes the feature, avoiding machine-wide freezes.
|
|
- Give manual guidance when automation cannot legally or safely complete the step.
|
|
|
|
## Non-Goals
|
|
- Silent administrator-level system modification.
|
|
- Guaranteed GPU support on every machine.
|
|
- Bundling every model in the desktop installer.
|
|
- Replacing ComfyUI, FunClip, social-auto-upload, or Agent-Reach internals.
|
|
- Exposing raw install logs, stack traces, command lines, or foreign-brand setup pages to customers.
|
|
|
|
## Runtime Directory Strategy
|
|
- The packaged application directory is treated as read-only.
|
|
- Customer runtime state defaults to a per-user TrueGrowth directory:
|
|
- macOS: Electron `app.getPath('userData')` or `~/Library/Application Support/TrueGrowth`
|
|
- Windows: `%APPDATA%/TrueGrowth`
|
|
- Runtime installs live under this directory, for example:
|
|
- `runtimes/ComfyUI`
|
|
- `runtimes/python`
|
|
- `runtimes/ffmpeg`
|
|
- `models/comfyui`
|
|
- `cache/huggingface`
|
|
- `logs/runtime`
|
|
- Development builds may keep using project-local paths, but the setup summary must explicitly report whether it is using development paths or customer runtime paths.
|
|
|
|
## Dependency Resolution Strategy
|
|
Each dependency is represented as a readiness resource with:
|
|
- `id`, `label`, `category`, `platforms`
|
|
- `status`: `ready`, `missing`, `needs_action`, `installing`, `downloading`, `failed`, `external`, `unsupported`
|
|
- `source`: `bundled`, `managed`, `system`, `configured`, `download`, `manual`, `development`
|
|
- `canAutoInstall`, `requiresAdmin`, `requiresRestart`, `requiresNetwork`, `licenseRequired`
|
|
- `version`, `path`, `sizeBytes`, `requiredBytes`, `availableBytes`
|
|
- `progress` with bytes, percent, speed, ETA, stage, and task id when applicable
|
|
- `actions` such as `install`, `download`, `openGuide`, `chooseMirror`, `configurePath`, `retry`, `clearPartial`
|
|
|
|
Safe automation:
|
|
- Install or update dependencies only inside the managed runtime directory.
|
|
- Install Python packages into a managed venv or embedded Python when present.
|
|
- Clone or update ComfyUI only inside the managed ComfyUI directory.
|
|
- Download model files into ComfyUI model directories or managed model cache.
|
|
- Use bundled ffmpeg when present; otherwise guide the user or install managed ffmpeg only if the package is available in the app bundle or approved download source.
|
|
|
|
Manual guidance:
|
|
- If Git or Python is absent and no bundled/managed installer is available, show OS-specific install steps.
|
|
- If Windows requires Visual C++ runtime, long path support, or GPU driver/CUDA setup, report it as a guided prerequisite.
|
|
- If macOS blocks unsigned binaries or quarantine attributes, show customer-safe recovery steps and only remove quarantine for app-managed runtime files when allowed.
|
|
|
|
## Mirror and Network Strategy
|
|
- Provide a runtime source selector with options such as:
|
|
- Hugging Face official
|
|
- configured mirror endpoint
|
|
- custom endpoint
|
|
- Store the selected endpoint in local runtime settings.
|
|
- Apply the endpoint to Hugging Face CLI/API downloads through `HF_ENDPOINT`.
|
|
- Disable Xet by default when it improves compatibility for large downloads, while keeping the setting visible in diagnostics.
|
|
- Preflight network access to GitHub, Hugging Face endpoint, and selected mirror with customer-facing status.
|
|
|
|
## Hugging Face Download Progress
|
|
- Single-file downloads should stream response bytes and patch the runtime task with:
|
|
- downloaded bytes
|
|
- total bytes when known
|
|
- percent
|
|
- speed
|
|
- ETA
|
|
- target path
|
|
- Snapshot downloads should prefer a controllable download helper over opaque child-process output when possible. The helper should emit structured progress events for files and total bytes.
|
|
- If the Hugging Face CLI is used as a fallback, parse progress output when possible; otherwise report stage progress and cache status.
|
|
- Incomplete downloads must be resumable when the underlying cache supports it, and the UI must show whether cache cleanup or retry is recommended.
|
|
|
|
## Model Center UX
|
|
- Add a first-run environment panel in Model Center before model cards.
|
|
- Group readiness by:
|
|
- System prerequisites
|
|
- Local image / ComfyUI
|
|
- AI clipping / FunClip / ASR
|
|
- Digital human / voice
|
|
- Publishing / browser automation
|
|
- Network and mirrors
|
|
- Every group shows readiness, progress, next action, and whether other features can still be used.
|
|
- Primary actions use TrueGrowth orange and feed into task center.
|
|
- The lower-left global task status remains the global progress entry; no fixed topbar is introduced.
|
|
|
|
## Safety and Resource Controls
|
|
- Do not auto-start heavy services at app boot.
|
|
- Before starting ComfyUI/FunClip/ASR, check memory/disk/GPU basics and show expected resource use.
|
|
- Allow one runtime initialization task per dependency group at a time.
|
|
- Cancellation should stop downloads where possible and leave resumable cache state.
|
|
- Logs stay available in diagnostics but are summarized before being shown to users.
|
|
|
|
## Risks
|
|
- Cross-platform dependency installation is fragile. Mitigation: prefer managed/bundled dependencies and degrade to exact guidance.
|
|
- Hugging Face snapshot progress is harder than single-file progress. Mitigation: implement a structured helper for official downloads, with CLI parsing as fallback.
|
|
- Large local models can exhaust customer disks. Mitigation: preflight every model, show target path and required space, and keep partial-cache cleanup explicit.
|
|
- Heavy AI runtimes can freeze weak machines. Mitigation: no automatic heavy service start on boot, readiness/resource checks before launch, and clear unsupported states.
|