AstrBot-Desktop/docs/reports/astrbot-real-protocol-review.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

18 KiB

AstrBot Real Protocol Review (vs Desktop provisional contract)

  • Date: 2026-07-20
  • Status: research complete; live container probe pending user-provided instance
  • Conclusion: do not claim compatibility with /desktop/v1. Real AstrBot exposes Dashboard JWT + developer OpenAPI on /api and /api/v1. A desktop adapter layer is required.

Sources

Source Path / URL Role
Local upstream clone C:\Users\Administrator\Documents\Codex\refs\AstrBot Code authority (no GitHub Apps used)
Package version pyproject.toml → 4.26.7 Observed clone version
Official OpenAPI docs docs/zh/dev/openapi.md, docs/en/dev/openapi.md Public developer API contract
Dashboard API code astrbot/dashboard/api/*, services/chat_service.py, services/auth_service.py Auth, SSE, WS, scopes
Compose defaults compose.yml Port 6185 WebUI/API
Desktop provisional contract docs/protocol/v1/*, docs/01_Architecture_Design.md, PD-0009 Current client assumption

Upstream repo identity: AstrBotDevs/AstrBot. Docker image commonly soulter/astrbot:latest.

What real AstrBot exposes

Transport and base URLs

  • Default container/WebUI port: 6185 (compose.yml maps 6185:6185, Dockerfile EXPOSE 6185).
  • API surface is FastAPI / ASGI, not a custom Desktop Gateway.
  • Two parallel API styles coexist:
    1. v1 OpenAPI-style routes: prefix /api/v1 (API_V1_PREFIX).
    2. Legacy Dashboard routes: prefixes like /api/auth, /api/chat, /api/session, etc.
  • Interactive docs (when running): http://<host>:6185/api/v1/docs
  • OpenAPI schema: http://<host>:6185/api/v1/openapi.json

Authentication (two valid modes)

Mode How presented Intended use Notes
Dashboard JWT Authorization: Bearer <jwt> or cookie astrbot_dashboard_jwt WebUI / dashboard-user flows Login via POST /api/v1/auth/login or legacy POST /api/auth/login with username/password (+ optional TOTP). JWT payload: { username, exp } HS256, default 7 days. No refresh-token endpoint found in current code.
Developer API Key Official docs show Authorization: Bearer abk_xxx or X-API-Key: abk_xxx; code also accepts ApiKey <key>, query api_key/key Machine integration Scope-gated. Prefer header auth; avoid putting keys in query strings in Desktop.

Response envelope for most JSON APIs:

{ "status": "ok|error", "message": "...", "data": {} }

Login success data includes at least:

{
  "token": "<jwt>",
  "username": "...",
  "change_pwd_hint": false,
  "md5_pwd_hint": false,
  "password_upgrade_required": false
}

Fresh installs may print a random strong dashboard password in startup logs (default password policy changed).

Chat / streaming (the critical path for Desktop text chat)

Capability Real AstrBot Desktop provisional (/desktop/v1)
Send message POST /api/v1/chat (OpenAPI, SSE) or legacy POST /api/chat/send POST /desktop/v1/messages
Session list GET /api/v1/chat/sessions (API key path requires username) Not modeled the same way
New session Dashboard: GET /api/v1/chat/sessions/new / legacy GET /api/chat/new_session Implicit/local
Streaming transport Request-scoped SSE from chat send; also run attach GET /api/v1/chat/runs/{run_id}/stream Long-lived GET /desktop/v1/events/stream with Last-Event-ID
Optional duplex WS /api/v1/chat/ws (OpenAPI) and live-chat WS endpoints Deferred WS for voice/game only
Event ACK Not present as Desktop-style POST /events/{id}/ack Required in provisional contract
Health / server-info / capabilities No `/desktop/v1/health server-info
Auth refresh No refresh token pair found POST /desktop/v1/auth/refresh
Tool proposal from server to desktop Not present as tool.proposal Core operations model
Local-action result callbacks Not present as /local-actions/* Required for ops tools

OpenAPI chat request shape (OpenApiChatRequest)

{
  "message": "Hello" ,
  "session_id": "uuid-or-omit",
  "conversation_id": "alias-of-session_id",
  "username": "required-for-api-key-mode",
  "config_id": "optional",
  "config_name": "optional",
  "platform_id": "optional",
  "enable_streaming": true,
  "flags": {}
}

message may be:

  1. plain string
  2. message-segment array, e.g. { "type": "plain", "text": "..." } plus attachment segments (image/record/file/video with attachment_id)

Observed SSE frame style (from chat_service.py)

  • Media type: text/event-stream
  • Frames are mostly data: {json}\n\n
  • Heartbeat is comment-style: : heartbeat\n\n (not Desktop system.heartbeat event objects)
  • Payload types observed in stream path include:
    • session_id
    • user_message_saved
    • run_snapshot
    • agent_stats
    • attachment_saved
    • message_saved
    • error
    • plus intermediate chunk payloads whose type can be message-chain types such as plain / attachment types and end markers from the internal queue

This is not the Desktop provisional event set:

system.heartbeat
message.delta
message.completed
message.proactive
agent.status
tool.proposal
capabilities.changed
error

Developer API Key scopes

Supported scopes in code/docs: bot, provider, persona, im, config, chat, file, plugin, mcp, skill.

Important:

  • config implies bot + provider.
  • Docs state developer keys do not currently expose some management scopes as first-class developer scopes (tool, kb, data, system called out as unsupported developer scopes in docs).
  • Desktop “operations tool proposal” is not an AstrBot OpenAPI scope; it is a Desktop-local safety model.

Dual-instance implications

AstrBot itself is one server process/instance with multi-session WebChat identities (username + session_id / platform session keys).

Desktop dual slots (companion / operations) remain a client-side concept:

  • Two Desktop Profiles can point at the same AstrBot base URL with different roles/policies.
  • Or two Profiles can point at two containers.
  • Real server does not natively understand Desktop slot roles.
  • Isolation keys on Desktop must still include local profile_id + observed server_instance_id substitute + conversation/session id.

There is no first-class serverInstanceId discovery endpoint equivalent to Desktop server-info. A safe substitute must be designed (e.g., hash of base URL + dashboard instance markers + TLS cert fingerprint + optional user-confirmed label). This is still an open protocol decision.

Gap table (Desktop provisional vs real AstrBot)

Area Desktop design Real AstrBot today Risk if ignored Can implement now?
Base path /desktop/v1/* /api/v1/* + legacy /api/* 100% connection failure Adapter required
Auth model access + refresh tokens JWT (7d) and/or API Key; no refresh pair found Refresh logic dead code / false security assumptions Adapter: store JWT or API Key in Credential Manager
Credentials in React forbidden N/A policy violation if mirrored Keep Rust-only secret store
Health discovery /health not equivalent mock-only health checks Map to lightweight authenticated probe or WebUI reachability
Server identity /server-info.serverInstanceId missing silent cross-instance mixups Need substitute identity + user confirmation
Capabilities /capabilities partial via configs/plugins/bots lists; not Desktop schema capability UI wrong Map subset later
Chat send REST message post POST /api/v1/chat SSE wrong client shape Implement adapter
Event stream long-lived SSE + Last-Event-ID per-request SSE (+ optional run stream / WS) reconnect/dedupe model invalid Redesign stream manager
Event names Desktop enum different types parser rejects everything Map/normalize in adapter
ACK required absent useless calls / noise Make ACK optional/no-op for AstrBot backend
Proactive messages message.proactive over long SSE IM proactive API exists (POST /api/v1/im/message) but not Desktop push bus wrong product assumption Separate design
Ops tool.proposal server pushes proposals not present operations panel cannot be driven by AstrBot core alone Keep Desktop-local proposal engine / future plugin contract
Local-action callbacks /local-actions/* absent cannot close tool loop to AstrBot Local audit only, or future plugin
TLS / pinning required by Desktop security model container often HTTP on LAN may force HTTP exception path Prefer HTTPS reverse proxy; never disable TLS validation globally
Dual SSE slots two long-lived streams two chat runs / two API keys / two containers architecture mismatch Keep dual client slots; adapt transport

Architecture impact (important: not a total rewrite)

Keep (still valid)

  • Tauri + React + Rust boundary
  • Dual Profile / dual slot isolation
  • Credential Manager storage
  • Mock Gateway for deterministic tests
  • Local diagnostics / NAS transfer security pipeline (client-side)
  • Provisional Desktop protocol as internal normalized model

Must add

  1. AstrBotAdapter (Rust) that translates:
    • Desktop normalized commands → AstrBot REST/SSE/WS
    • AstrBot stream frames → Desktop GatewayEvent (best-effort mapping)
  2. Auth strategies:
    • Strategy A: Dashboard username/password → JWT (short-lived session model, re-login on expiry)
    • Strategy B: API Key with scopes chat (+ file if attachments; carefully limited admin scopes)
  3. Stream manager redesign:
    • Not one eternal server push bus
    • Per send-stream + optional run re-attach + future WS for duplex
  4. Server identity substitute decision (open item)
  5. Operations path:
    • Do not expect stock AstrBot to emit Desktop tool.proposal
    • Either local-only ops tools, or a future explicit AstrBot plugin/contract

Do not do

  • Rewrite Desktop core to call random AstrBot internal Python APIs
  • Claim /desktop/v1 is real AstrBot
  • Put API keys/JWT into React, SQLite plain fields, logs, or URL query strings
  • Disable TLS validation to “make container work”
  • Implement arbitrary shell execution because ops tools are missing server-side

Live container probe plan (when you provide the instance)

Please provide (redact secrets in chat if needed; better paste into a local file path I can read, or supply a temporary throwaway password/API key):

  1. Base URL, e.g. http://192.168.x.x:6185
  2. Auth mode: dashboard password or API Key (abk_...)
  3. Whether LLM provider is already configured (chat may stream errors without a model)
  4. Network reachability from this Windows desktop host

Minimum probe sequence (no secrets logged in full):

  1. GET / or WebUI reachability
  2. GET /api/v1/openapi.json (schema presence/version markers)
  3. Auth:
    • login POST /api/v1/auth/login or
    • API key header against GET /api/v1/chat/sessions?username=...
  4. Create/send chat:
    • POST /api/v1/chat with small plain message and capture first SSE frames
  5. Confirm session list returns the session
  6. Optional: WS /api/v1/chat/ws smoke
  7. Record actual event type sequence into this report appendix

Success criteria for “connection is implementable”:

  • Auth succeeds without Dashboard browser cookies as the only path
  • One chat message produces parseable SSE frames
  • Session id is stable enough to store under a Desktop Profile
  • Dual Profiles can open two independent sessions without cross-talk

Failure that would force design pause:

  • Only cookie-auth works and API key/JWT blocked
  • Chat stream format unstable / undocumented and unusable
  • No way to distinguish two server instances safely for dual-slot ops
  • Requirement to modify AstrBot core for basic text chat

Decision recommendation

Decision Recommendation
Is Desktop mock protocol wrong? It is a valid internal contract, not a real server contract.
Should we throw away Desktop work? No. Keep Mock + normalized events; add adapter.
First live integration target Text chat via POST /api/v1/chat SSE + session APIs
Preferred auth for automation tests API Key with minimal scopes (chat, maybe file)
Preferred auth for user login UX Dashboard login → JWT in Credential Manager, re-login on 401/expiry
Operations tools MVP Remain Desktop-local; do not depend on AstrBot emitting proposals yet
Protocol docs Update PD-0009 / add ADR after first successful container probe

Can implement now / needs container / blocked

Item Status
Protocol research + gap table Done (this document)
Adapter design sketch Ready
Live endpoint/version confirmation against your container Needs container
Real chat SSE fixture capture Needs container + model provider
Dual-instance identity substitute finalization Needs probe + product decision
Claiming production compatibility Blocked until probe passes
Rewriting whole Desktop architecture Not required based on current evidence

Next action

Provide the test AstrBot container endpoint and auth material. I will run a non-destructive probe, capture redacted SSE samples, and only then propose the minimal adapter implementation plan (likely ADR + protocol mapping tables, without expanding product scope).

Live container probe (2026-07-20)

  • Target: http://192.168.31.210:26285
  • Auth: developer API Key (abk_…, redacted)
  • Mode: non-destructive chat/session/config probes only
  • Artifacts:
    • docs/reports/astrbot-live-probe-summary.json
    • docs/reports/astrbot-live-probe-sse.raw.txt (secrets redacted)
    • docs/reports/run-live-probe.ps1 (requires env key; no embedded secret)

Connectivity results

Check Result
TCP 192.168.31.210:26285 Reachable
GET / WebUI HTML 200
GET /api/auth/setup-status (no auth) 200; setup_required=false
API Key on GET /api/v1/chat/sessions?username=... 200
Auth styles accepted Authorization: Bearer abk_…, X-API-Key, Authorization: ApiKey …, query api_key (prefer headers only in Desktop)
GET /api/v1/configs 200; one config default
GET /api/v1/im/bots 200; bot_ids=["napcat3"]
GET /api/v1/openapi.json / /docs / several management routes Often SPA-style HTML 404 page even when authenticated; do not rely on OpenAPI UI path on this deployment
Dashboard JWT login Not exercised in this probe (API key path is sufficient for automation)

Chat SSE (authoritative live sample)

POST /api/v1/chat with:

{
  "message": "desktop-probe ...",
  "username": "desktop-companion|desktop-operations",
  "session_id": "desktop-*-s1",
  "enable_streaming": true
}

Observed response:

  • HTTP 200
  • Content-Type: text/event-stream
  • Initial frames:
    1. {"type":"session_id","data":null,"session_id":"..."}
    2. {"type":"user_message_saved","data":{"id":N,"created_at":"...","llm_checkpoint_id":"..."}}
    3. Comment heartbeats: : heartbeat
    4. Streamed assistant tokens: {"type":"plain","data":"Hello","streaming":true,"chain_type":null,"message_id":"..."}
  • message_id is stable across one assistant generation
  • Client may close after idle heartbeats; server can keep heartbeating after partial generation
  • Terminal message_saved / end frames were not always observed before client idle-close in this probe; adapter must tolerate incomplete terminal markers and reconstruct final text from accumulated plain frames + later session history fetch if needed

Dual-slot isolation evidence

Desktop-like identity username session_id Session list total
Companion desktop-companion desktop-companion-s1 1
Operations desktop-operations desktop-operations-s1 1

Session list responses were fully isolated by username. Same API key can drive both slots if Desktop binds different local usernames/session ids per Profile. Prefer separate API keys later for least privilege, but not required for MVP connectivity.

Mapping recommendation (internal Desktop events)

AstrBot live frame Desktop normalized event
comment : heartbeat local connection liveness only (optional system.heartbeat)
session_id bind conversation/session identity
user_message_saved local user message ack / persistence metadata
plain + streaming=true message.delta (append data)
accumulated plain until idle/end message.completed (client synthesized if server omits terminal frame)
error error
no tool.proposal observed keep operations tools Desktop-local for now

Implementability verdict

Goal Verdict
Text chat against real AstrBot Implementable now via adapter
Dual companion/operations chat panels on one server Implementable with per-slot username + session_id
Direct use of provisional /desktop/v1 against this server Not possible
Long-lived server push bus + ACK Not available; redesign stream manager
Server-driven local tool proposals Not available on stock API
Need to rewrite whole Desktop app No

Remaining probe gaps (non-blocking for chat MVP)

  • Dashboard password login / JWT expiry behavior not live-tested
  • File upload (POST /api/v1/file) not tested
  • WebSocket /api/v1/chat/ws not tested
  • Re-attach GET /api/v1/chat/runs/{run_id}/stream not tested
  • No durable serverInstanceId discovery endpoint; still needs identity substitute design
  • This deployment returns SPA 404 HTML for some documented OpenAPI paths; adapter should feature-detect actual routes rather than assume full OpenAPI UI availability

Security notes from probe

  • API key worked and must stay in Windows Credential Manager only
  • Never log full key; sample captures store abk_[REDACTED]
  • Prefer header auth, not query-string key
  • Target is plain HTTP on LAN; TLS pinning decision remains open for production Profiles