Skip to content

avatar

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

avatar

README.md

@nimiplatform/avatar

Nimi Avatar（阿凡达）是桌面悬浮 embodiment carrier。Authority-defined backend union is live2d | vrm; no renderer backend is the semantic home of Runtime or Avatar product truth.

This README is a non-authoritative operator guide. Normative authority lives in ../../.nimi/spec/avatar/embodiment-surface.authority.yaml, with admitted machine inputs under config/avatar-*.yaml.

Quick Links

Launch Model

The normal path is Desktop bridge/handoff to a local Avatar asset:

  • Launch context requires a current-session canonical agent_handle；the common Host handoff accepts an optional conversation_anchor_id and resolves or revalidates the canonical fence before native launch。avatar_instance_id and non-authoritative launch_source are optional.
  • The handle and anchor are selectors, not authorization proof. Runtime/SDK validates their active session binding.
  • Missing or invalid launch context fails closed; Avatar does not choose a default agent.
  • Local Live2D and VRM assets enter only through their validated package/profile boundary.
  • Runtime bootstrap uses the Desktop/Runtime bridge. Avatar does not read shared auth, create a Realm client, or own login/session truth.
  • Handoff payloads do not carry raw tokens, subject_user_id, or Realm base URLs.
  • When Runtime binding is unavailable, Avatar stops interaction, voice, and activity consumption, unmounts the normal carrier, and renders only the degraded surface.

Runtime and Fixtures

  • Normal boot uses the Desktop-selected launch context, local Avatar asset, Runtime bridge, and public SDK projections.
  • VITE_AVATAR_DRIVER=mock enables an explicit development/test fixture.
  • Fixture output never establishes real Runtime binding or carrier readiness.
  • Runtime failure does not silently downgrade to fixture mode.

Architecture

  • Shell: Desktop-supervised Electron BrowserWindow; Avatar has no independent native shell or native bundle.
  • Renderer: React 19, Vite 7, Tailwind 4.
  • Backends: live2d | vrm.
  • Shared contracts and UI: @nimiplatform/kit.
  • Runtime/Realm projections: public @nimiplatform/sdk entrypoints.
  • Renderer-local state: Zustand.

The teaching model is:

agent semantics -> embodiment projection -> backend-specific execution

Runtime/SDK retain semantic truth. Avatar owns embodiment projection, validated package/profile binding, and concrete carrier execution. Kit owns reusable primitives and typed projection surfaces.

Commands

pnpm --filter @nimiplatform/avatar dev:renderer
pnpm dev:avatar
pnpm dev:avatar --cdp-port 19472
pnpm dev:avatar --agent-handle agent_ref_<current-session-handle>
VITE_AVATAR_DRIVER=mock pnpm --filter @nimiplatform/avatar dev:renderer
pnpm --filter @nimiplatform/avatar typecheck
pnpm --filter @nimiplatform/avatar lint
pnpm --filter @nimiplatform/avatar test

The root dev:avatar command defaults to the Desktop-owned Electron carrier. It enables deterministic loopback CDP port 9336 by default; --cdp-port <port> overrides the port and --no-cdp disables it. The avatar-only Electron carrier and ordinary pnpm dev:desktop are mutually exclusive Desktop instances.

Main Paths

apps/avatar/
├── src/shell/renderer/
│   ├── app-shell/   # renderer-local state and composition
│   ├── semantic-projection/ # built-in activity and event projection wiring
│   ├── live2d/      # Live2D backend
│   ├── vrm/         # VRM backend
│   ├── mock/        # explicit fixture driver
│   └── sdk/         # real Runtime/SDK adapter
└── src-electron/    # preload sources consumed by the Desktop-supervised BrowserWindow

Upstream Contracts

The carrier consumes Runtime-owned conversation, activity, audio, timing, playback, and interruption projections. Avatar owns local rendering, playback, backend lipsync, visible geometry, hit regions, and bounded window behavior.