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

46 行
2.2 KiB
Markdown

# 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)