AstrBot-Desktop/docs/decisions/ADR-0007-jwt-background-pet-and-remote-identity.md

26 行
2.2 KiB
Markdown

# ADR-0007: JWT authentication, remote identity, and background pet windows
## Context
AstrBot Desktop must support both API-key automation and Dashboard user login. The pet must continue running after the main chat window is closed, without creating a separate Windows taskbar button. Users also need a stable remote chat identity and animated behavior.
## Decision
1. JWT login is a required capability, alongside API Key and device token. JWTs, API keys, passwords, and other credentials are accessed only by Rust and stored in Windows Credential Manager. React never receives plaintext credentials.
2. Remote identity consists of a nickname and an ID configured by the user. The nickname is for display and addressing the user; the ID is used as AstrBot `username` and for local isolation. IDs allow 3-32 ASCII letters and digits and must be unique within a local account.
3. Floating pet mode uses a borderless, skip-taskbar background window. Closing the main chat window leaves the application resident in the system tray. Floating mode is not topmost by default and is controlled by settings.
4. The first pet renderer uses PNG/WebP spritesheets and bounded animation clips. Animation state and movement control are separate. Initial clips include idle, working with a book, speaking, notification, resting walk, and error. Live2D, Spine, 3D, and user script plugins are deferred.
## Rationale
- JWT supports normal user login while API Key remains useful for automation and testing.
- Separating nickname and ID provides natural addressing without sacrificing stable session isolation.
- A skip-taskbar background window provides a clean desktop pet experience without changing local permission boundaries.
- Spritesheets provide animated and interactive behavior at lower implementation and security cost, while leaving room for a richer renderer later.
## Consequences
- Add JWT login, expiration, 401 re-login, and secure credential migration tests.
- Connect the existing pet display-range setting to the Rust window controller instead of leaving it as a frontend placeholder.
- Extend the pet-pack manifest with animation clips, state transitions, and bounded interaction actions.
- Defer game mode to Q7; do not implement game detection or game-window behavior in this decision.