AstrBot-Desktop/docs/decisions/ADR-0005-astrbot-openapi-adapter.md
YokiiroBW 3d1d962461
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
feat(chat): add AstrBot dual-slot chat foundation
2026-07-20 11:31:41 +08:00

2.2 KiB

ADR-0005: Real AstrBot OpenAPI adapter over internal Desktop protocol

Status

Accepted for foundation work on 2026-07-20.

Context

P00/P01 defined a provisional Desktop Gateway contract (/desktop/v1) and dual Mock Gateway. Live probe of AstrBot 4.26.x on http://192.168.31.210:26285 showed the real server exposes Dashboard/OpenAPI routes under /api and /api/v1, with request-scoped chat SSE from POST /api/v1/chat, API Key or Dashboard JWT auth, and no Desktop-native long-lived event bus, ACK, tool.proposal, or server-info endpoints.

Rewriting the whole Desktop application around raw AstrBot internal APIs would discard working dual-slot isolation, Mock tests, and security boundaries.

Decision

  1. Keep the provisional Desktop Gateway event model as the internal normalized contract.
  2. Add a Rust-owned AstrBot OpenAPI adapter that translates:
    • Desktop chat send intent → POST /api/v1/chat
    • AstrBot SSE frames → Desktop GatewayEvent (message.delta, message.completed, heartbeat, error)
  3. Add TransportKind on ConnectionProfile:
    • desktop-v1 for Mock/provisional gateway
    • astrbot-openapi for real AstrBot
  4. Store secrets only in Windows Credential Manager; React may submit one-shot enrollment IPC but never receives stored secrets.
  5. Use derived server_instance_id substitute (astrbot-<hash(base_url)>) until a stronger identity enrollment flow is approved.
  6. Keep operations tool proposals Desktop-local; do not invent a fake server proposal channel.

Consequences

Positive

  • Real chat connectivity can proceed without discarding Mock-based dual-slot tests.
  • Security boundaries remain Rust-owned.
  • UI and local storage continue to reason about normalized events and slots.

Negative / costs

  • Adapter must tolerate missing terminal SSE frames and synthesize completion.
  • Capability/discovery surfaces differ by transport.
  • Certificate pinning and JWT login remain open follow-ups.

Follow-ups

  • Live dual-slot chat UI rendering and history persistence
  • Dashboard JWT login path
  • Attachment upload (/api/v1/file)
  • Optional WS chat path
  • Stronger server identity enrollment (PD-0011) and TLS fingerprint binding (PD-0012)