47 行
2.2 KiB
Markdown
47 行
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)
|