AstrBot-Desktop/docs/protocol/v1/http.md

54 行
1.6 KiB
Markdown

# Desktop Gateway v1 HTTP and SSE surface
## Public discovery
```text
GET /desktop/v1/health
GET /desktop/v1/server-info
GET /desktop/v1/capabilities
```
`server-info.serverInstanceId` becomes the expected server identity for the active connection. A later mismatch freezes that connection rather than silently rebinding it.
## Authentication
```text
POST /desktop/v1/auth/login
POST /desktop/v1/auth/refresh
```
Credentials and returned tokens remain in the Rust layer. Request and response bodies containing credential material must not derive or use unrestricted debug logging.
## Messaging and events
```text
POST /desktop/v1/messages
GET /desktop/v1/events/stream
POST /desktop/v1/events/{event_id}/ack
```
SSE frames carry both the SSE `id` and the complete JSON event envelope in `data`. Reconnect uses the `Last-Event-ID` request header. Replay and de-duplication are scoped to the local connection profile, so the same event ID on two server instances remains two distinct events.
Initial event types:
```text
system.heartbeat
message.delta
message.completed
message.proactive
agent.status
tool.proposal
capabilities.changed
error
```
## Local action reporting
```text
POST /desktop/v1/local-actions/{action_id}/accepted
POST /desktop/v1/local-actions/{action_id}/rejected
POST /desktop/v1/local-actions/{action_id}/progress
POST /desktop/v1/local-actions/{action_id}/result
```
A `tool.proposal` is only an untrusted proposal. Schema validation, tool registry validation, slot/profile checks, server identity verification, expiry checks, local policy, and user authorization happen before any local execution.