AstrBot-Desktop/docs/protocol/v1/README.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

54 行
2.2 KiB
Markdown

# AstrBot Desktop Gateway Protocol v1
Status: provisional P00 contract for desktop development and the local Mock Gateway.
Compatibility with a real AstrBot Gateway must not be claimed until the server-side contract is reviewed.
## Source of truth
Rust types in `crates/desktop-protocol` are authoritative. JSON Schema files in `schemas/` are generated and checked with:
```text
cargo run -p desktop-protocol --example export_schemas -- --write
cargo run -p desktop-protocol --example export_schemas
```
Generated Schema files must not be edited manually.
## Trust boundary
An inbound `profileId` is an untrusted server hint. The Rust connection object binds each accepted event to its local `profile_id` and `companion` or `operations` slot. `serverInstanceId` must match the identity obtained from `server-info`.
The React application never connects directly to this protocol and never receives access or refresh tokens.
## Versioning
- REST prefix: `/desktop/v1`
- Envelope version: `1.0`
- Breaking wire changes require a new major REST prefix and protocol version.
- Unknown event types are reported as unsupported and safely skipped; they are not routed to the UI.
- Security-sensitive payloads reject unknown outer fields.
## Mock instances
Run each instance in a separate process when manually testing independent failure:
```text
cargo run -p mock-gateway -- --instance companion --port 43101
cargo run -p mock-gateway -- --instance operations --port 43102
```
The Mock Gateway refuses non-loopback bind addresses. It uses only runtime-generated mock credentials, has no shell/file/NAS capability, and is not a Tauri release dependency.
Available fixed scenarios:
- `steady`
- `disconnect-once`
- `duplicate-events`
- `auth-reject`
The 30-minute dual-SSE soak is an explicit local Spike acceptance run and must be recorded separately; its result is not implied by unit tests.
## Real AstrBot transport note
As of the 2026-07-20 live probe, real AstrBot servers do **not** implement /desktop/v1.
Desktop keeps this protocol as the internal normalized model and maps AstrBot OpenAPI chat SSE through the Rust adapter (TransportKind::astrbot-openapi).
See docs/reports/astrbot-real-protocol-review.md and docs/decisions/ADR-0005-astrbot-openapi-adapter.md.