# Xiaoxitu AIGC Desktop Shell Contract

Updated: 2026-07-02

This package is a frozen desktop shell, not the business application.

## Stable Responsibilities

- Own one independent WebView2 window.
- Load the configured Web/static entry from `assistant-url.txt`.
- Append `qda_desktop_mode=install_root` and `qda_desktop_root=<install-root>`.
- Keep the WebView2 profile under `<install-root>/webview-profile`.
- Keep user assets under `<install-root>/users/<sanitized-user>/`.
- In desktop install-root mode, mirror node outputs to physical files under `<install-root>/users/<sanitized-user>/节点资产/<node-name>/`. The installer only creates the stable base buckets (`节点资产`, `服务器资产`, `画布记录`, etc.); the producing node creates its own Chinese-name directory at write time. Filenames use the frontend-provided node initials plus timestamp, with child/shot/segment suffixes when supplied. Legacy `{images|videos|texts}/node_outputs/<node-name>/` paths remain readable for compatibility but are not the new write target.
- In desktop install-root mode, accept frontend `workflow` JSON bridge writes and mirror workflow files under `<install-root>/users/<sanitized-user>/workflows/`: latest autosave in `autosave/canvas_autosave_latest.json`, latest workflow-library manifest in `library/workflow_library_manifest_latest.json`, and manual save snapshots in `snapshots/`. Workflow rows are indexed in `<install-root>/users/<sanitized-user>/indexes/desktop_workflows.jsonl`.
- Start the bundled local video helper on `127.0.0.1:17660-17670`.
- Expose the small WebView2 message bridge used by the Web frontend:
  - `qda-desktop-auth-user`
  - `qda-desktop-asset-write`

## Long-Term Extension Boundary

The desktop client is a one-time lightweight install. Future plugins, helper packages, model runtimes, and large model files must be pulled from the backend plugin library on first use or first run, then cached under the install root. The default installer should not keep growing with product plugins or model files.

Static Web page first:

- plugin marketplace/status UI
- model availability UI
- install/update prompts
- manifest comparison
- frontend cache busting
- node/plugin orchestration

Backend plugin library first:

- plugin catalog and signed manifests
- model-file manifests and download URLs
- account entitlement checks
- package hashes, versions, rollout, disable/revoke flags

Native desktop shell only:

- WebView2 and OS window behavior
- install-root and per-user local storage boundary
- minimal verified file-write bridge
- approved local helper/runtime bootstrap

Detailed planning is tracked in `docs/DESKTOP_LIGHT_CLIENT_EXTENSION_PLAN_20260702.md`.

## Do Not Rebuild For

- Frontend node UI changes.
- Browser-only workflow persistence fixes that do not change the native bridge schema.
- Asset manager UI changes.
- Model routing UI changes.
- Backend API/business logic changes.
- Static page cache-busting changes.
- Plugin catalog, plugin manifest, or model manifest changes.
- Normal plugin/model package rollout from the backend plugin library.

Those changes belong in `frontend/`, `backend/`, and deployment config. The installed desktop app should just refresh or reload the configured page.

## Rebuild Only For

- WebView2 window behavior.
- Tray/menu/icon behavior.
- Native asset bridge message schema changes.
- Bundled helper/runtime changes.
- Installer/shortcut behavior.
- Default shell config files such as `assistant-url.txt`, `window-size.txt`, or `window-zoom.txt`.

## Development Mode

For source development, keep `assistant-url.txt` as:

```text
http://127.0.0.1:8080/index.html
```

Run the repo frontend static server, then refresh the desktop app. Do not reinstall the desktop app for ordinary frontend/backend repairs.

## Production Mode

For server deployment, set `assistant-url.txt` in the installed root to:

```text
https://www.xixiaotu.com/
```

Then deploy updated frontend/backend code to the server. The desktop shell remains unchanged.
