zustand

This skill documents LobeHub's Zustand state-management conventions for the lobe-chat codebase, giving contributors and AI agents a consistent pattern for writing and editing store slices. It defines a three-tier action hierarchy: public actions (verb-named interfaces called by UI components, responsible for validation and orchestration), internal actions (`internal_` prefixed core business logic handling optimistic updates, service calls, and error handling, never called directly by UI), and dispatch methods (`internal_dispatch*` handlers that call reducers and update the store). The problem it solves is keeping a large, evolving store organized and predictable as the codebase grows.

The guide covers when to use the reducer pattern versus a simple `set` (reducers for object lists/maps, optimistic updates, and complex transitions; simple set for booleans and single values), the standard optimistic-update flow of updating the frontend immediately, calling the backend, then refreshing for consistency — with the explicit note that destructive delete operations should not use optimistic updates. It documents naming conventions for actions and state (ID arrays, maps, active-item fields, init flags), and an ongoing migration from plain StateCreator objects to class-based actions that receive `(set, get, api)` in a constructor, use private fields, and are composed via a `flattenActions` helper. Companion reference files detail action patterns (including SWR integration, cache invalidation via mutate, loading-state management, and the reducer pattern with immer's produce) and slice organization (top-level store aggregation, single-slice directory structure, map structures, and best practices).

The target users are front-end engineers and coding agents editing `src/store` in lobe-chat. It is a benign code-convention and architecture reference with illustrative TypeScript snippets and no risky operations.