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

2.2 KiB

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:

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:

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.