AstrBot-Desktop/crates/desktop-protocol/src/astrbot.rs
YokiiroBW 7dae4898cb
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
feat(pet): separate remote identity and add paper pet window
2026-07-20 16:28:42 +08:00

518 行
18 KiB
Rust

//! Real AstrBot OpenAPI/Dashboard wire types and SSE frame mapping.
//!
//! The provisional Desktop Gateway contract remains the internal normalized
//! model. This module translates observed AstrBot `/api/v1` chat SSE frames
//! into that model without claiming full product compatibility.
use serde::{Deserialize, Serialize};
use serde_json::Value;
use thiserror::Error;
use crate::{
EventMetadata, FinishReason, GatewayErrorPayload, GatewayEvent, GatewayEventBody,
HeartbeatPayload, MessageCompletedPayload, MessageDeltaPayload,
};
/// Wire transport used by a connection profile.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "kebab-case")]
pub enum TransportKind {
/// Provisional Mock / future Desktop Gateway (`/desktop/v1`).
#[default]
DesktopV1,
/// Real AstrBot OpenAPI surface (`/api/v1`).
AstrBotOpenApi,
}
impl TransportKind {
pub fn as_str(self) -> &'static str {
match self {
Self::DesktopV1 => "desktop-v1",
Self::AstrBotOpenApi => "astrbot-openapi",
}
}
pub fn parse(value: &str) -> Option<Self> {
match value {
"desktop-v1" => Some(Self::DesktopV1),
"astrbot-openapi" => Some(Self::AstrBotOpenApi),
_ => None,
}
}
}
/// JSON envelope used by most AstrBot dashboard/OpenAPI JSON responses.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct AstrBotApiEnvelope<T> {
pub status: String,
#[serde(default)]
pub message: Option<String>,
#[serde(default)]
pub data: Option<T>,
}
impl<T> AstrBotApiEnvelope<T> {
pub fn is_ok(&self) -> bool {
self.status.eq_ignore_ascii_case("ok")
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct AstrBotChatRequest {
pub message: Value,
#[serde(skip_serializing_if = "Option::is_none")]
pub session_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub conversation_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub username: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub nickname: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub config_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub attachments: Option<Vec<AstrBotAttachment>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub platform_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub enable_streaming: Option<bool>,
}
/// A model/provider configuration exposed by AstrBot.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct AstrBotModelOption {
pub id: String,
#[serde(default)]
pub name: Option<String>,
#[serde(default)]
pub is_default: Option<bool>,
}
/// Normalized attachment returned by the Rust upload boundary.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct AstrBotAttachment {
pub attachment_id: String,
pub file_name: String,
pub mime_type: String,
pub size_bytes: u64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub url: Option<String>,
}
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct AstrBotCapabilitySnapshot {
pub transport: String,
pub text_chat: bool,
pub streaming: bool,
pub model_selection: bool,
pub file_upload: bool,
pub image_input: bool,
pub models: Vec<AstrBotModelOption>,
}
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct AstrBotSessionListData {
#[serde(default)]
pub sessions: Vec<AstrBotSessionSummary>,
#[serde(default)]
pub page: Option<u64>,
#[serde(default)]
pub page_size: Option<u64>,
#[serde(default)]
pub total: Option<u64>,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct AstrBotSessionSummary {
pub session_id: String,
#[serde(default)]
pub platform_id: Option<String>,
#[serde(default)]
pub creator: Option<String>,
#[serde(default)]
pub display_name: Option<String>,
#[serde(default)]
pub is_group: Option<i64>,
#[serde(default)]
pub created_at: Option<String>,
#[serde(default)]
pub updated_at: Option<String>,
}
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct AstrBotConfigListData {
#[serde(default)]
pub configs: Vec<AstrBotConfigSummary>,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct AstrBotConfigSummary {
pub id: String,
#[serde(default)]
pub name: Option<String>,
#[serde(default)]
pub path: Option<String>,
#[serde(default)]
pub is_default: Option<bool>,
}
/// One decoded SSE unit from an AstrBot chat stream.
#[derive(Clone, Debug, PartialEq)]
pub enum AstrBotSseUnit {
HeartbeatComment,
Json(AstrBotStreamFrame),
Ignored,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct AstrBotStreamFrame {
#[serde(rename = "type")]
pub frame_type: String,
#[serde(default)]
pub data: Value,
#[serde(default)]
pub session_id: Option<String>,
#[serde(default)]
pub streaming: Option<bool>,
#[serde(default)]
pub chain_type: Option<Value>,
#[serde(default)]
pub message_id: Option<String>,
}
#[derive(Debug, Error)]
pub enum AstrBotMapError {
#[error("invalid astrbot sse json: {0}")]
Json(#[from] serde_json::Error),
}
/// Parses a single SSE line (not including the blank separator).
pub fn parse_astrbot_sse_line(line: &str) -> Result<AstrBotSseUnit, AstrBotMapError> {
let trimmed = line.trim_end_matches('\r');
if trimmed.is_empty() {
return Ok(AstrBotSseUnit::Ignored);
}
if trimmed.starts_with(':') {
// AstrBot heartbeats are comment frames: ": heartbeat"
return Ok(AstrBotSseUnit::HeartbeatComment);
}
if let Some(data) = trimmed.strip_prefix("data:") {
let payload = data.trim_start();
if payload.is_empty() {
return Ok(AstrBotSseUnit::Ignored);
}
let frame: AstrBotStreamFrame = serde_json::from_str(payload)?;
return Ok(AstrBotSseUnit::Json(frame));
}
// event:/id: fields are currently unused by AstrBot chat streams.
Ok(AstrBotSseUnit::Ignored)
}
/// Stateful mapper that turns AstrBot chat SSE frames into Desktop Gateway events.
#[derive(Debug, Default)]
pub struct AstrBotStreamMapper {
server_instance_id: String,
session_id: Option<String>,
active_message_id: Option<String>,
accumulated: String,
delta_index: u32,
sequence: u64,
saw_assistant_delta: bool,
}
impl AstrBotStreamMapper {
pub fn new(server_instance_id: impl Into<String>) -> Self {
Self {
server_instance_id: server_instance_id.into(),
..Self::default()
}
}
pub fn session_id(&self) -> Option<&str> {
self.session_id.as_deref()
}
pub fn push_line(&mut self, line: &str) -> Result<Vec<GatewayEvent>, AstrBotMapError> {
match parse_astrbot_sse_line(line)? {
AstrBotSseUnit::Ignored => Ok(Vec::new()),
AstrBotSseUnit::HeartbeatComment => Ok(vec![self.heartbeat_event()]),
AstrBotSseUnit::Json(frame) => Ok(self.map_frame(frame)),
}
}
/// Call when the HTTP stream ends without a terminal server frame.
pub fn finish_stream(&mut self) -> Vec<GatewayEvent> {
self.complete_if_needed(FinishReason::Stop)
}
fn map_frame(&mut self, frame: AstrBotStreamFrame) -> Vec<GatewayEvent> {
match frame.frame_type.as_str() {
"session_id" => {
if let Some(session_id) = frame
.session_id
.clone()
.filter(|value| !value.trim().is_empty())
{
self.session_id = Some(session_id);
} else if let Some(session_id) = string_from_value(&frame.data) {
self.session_id = Some(session_id);
}
Vec::new()
}
"user_message_saved" => Vec::new(),
"plain" => self.map_plain(frame),
"agent_stats" => {
let detail = frame.data.to_string();
vec![self.event(
frame.message_id.clone(),
GatewayEventBody::AgentStatus(crate::AgentStatusPayload {
state: "running".into(),
detail: Some(detail),
}),
)]
}
"run_snapshot" => {
vec![self.event(
frame.message_id.clone(),
GatewayEventBody::AgentStatus(crate::AgentStatusPayload {
state: "snapshot".into(),
detail: Some(frame.data.to_string()),
}),
)]
}
"message_saved" | "end" => self.complete_if_needed(FinishReason::Stop),
"error" => {
let mut events = self.complete_if_needed(FinishReason::Error);
let message = string_from_value(&frame.data)
.unwrap_or_else(|| "AstrBot stream error".to_owned());
events.push(self.event(
frame.message_id,
GatewayEventBody::Error(GatewayErrorPayload {
code: "astrbotStreamError".into(),
message,
retryable: true,
}),
));
events
}
"attachment_saved" => Vec::new(),
_ => Vec::new(),
}
}
fn map_plain(&mut self, frame: AstrBotStreamFrame) -> Vec<GatewayEvent> {
let chunk = string_from_value(&frame.data).unwrap_or_default();
if chunk.is_empty() && frame.streaming.unwrap_or(false) {
// Keep empty streaming markers out of the UI unless they carry text.
return Vec::new();
}
if let Some(message_id) = frame.message_id.clone() {
if self
.active_message_id
.as_ref()
.is_some_and(|current| current != &message_id)
{
// New assistant message id: complete the previous accumulation first.
let mut events = self.complete_if_needed(FinishReason::Stop);
self.active_message_id = Some(message_id);
self.accumulated.clear();
self.delta_index = 0;
self.saw_assistant_delta = false;
events.extend(self.emit_delta(chunk));
return events;
}
self.active_message_id = Some(message_id);
}
self.emit_delta(chunk)
}
fn emit_delta(&mut self, chunk: String) -> Vec<GatewayEvent> {
if chunk.is_empty() {
return Vec::new();
}
self.accumulated.push_str(&chunk);
self.saw_assistant_delta = true;
let index = self.delta_index;
self.delta_index = self.delta_index.saturating_add(1);
vec![self.event(
self.active_message_id.clone(),
GatewayEventBody::MessageDelta(MessageDeltaPayload {
delta: chunk,
index,
}),
)]
}
fn complete_if_needed(&mut self, reason: FinishReason) -> Vec<GatewayEvent> {
if !self.saw_assistant_delta && self.accumulated.is_empty() {
return Vec::new();
}
let content = std::mem::take(&mut self.accumulated);
self.saw_assistant_delta = false;
self.delta_index = 0;
let message_id = self.active_message_id.clone();
vec![self.event(
message_id,
GatewayEventBody::MessageCompleted(MessageCompletedPayload {
finish_reason: reason,
content: Some(content),
}),
)]
}
fn heartbeat_event(&mut self) -> GatewayEvent {
self.event(
None,
GatewayEventBody::Heartbeat(HeartbeatPayload { interval_ms: 1_000 }),
)
}
fn event(&mut self, message_id: Option<String>, body: GatewayEventBody) -> GatewayEvent {
self.sequence = self.sequence.saturating_add(1);
let event_id = format!("astrbot-{}-{}", self.server_instance_id, self.sequence);
let mut metadata = EventMetadata::new(
event_id,
self.server_instance_id.clone(),
current_timestamp(),
self.sequence,
);
metadata.session_id = self.session_id.clone();
metadata.conversation_id = self.session_id.clone();
metadata.message_id = message_id.or_else(|| self.active_message_id.clone());
GatewayEvent { metadata, body }
}
}
fn string_from_value(value: &Value) -> Option<String> {
match value {
Value::Null => None,
Value::String(text) => Some(text.clone()),
Value::Number(number) => Some(number.to_string()),
Value::Bool(flag) => Some(flag.to_string()),
other => Some(other.to_string()),
}
}
fn current_timestamp() -> String {
// Protocol timestamps are opaque strings for consumers; keep a stable UTC-like form
// without adding a time dependency to the protocol crate.
"1970-01-01T00:00:00Z".into()
}
/// Derives a stable local server identity substitute when AstrBot has no server-info API.
pub fn derive_astrbot_server_instance_id(base_url: &str) -> String {
use std::hash::{Hash, Hasher};
let normalized = base_url.trim().trim_end_matches('/').to_ascii_lowercase();
let mut hasher = std::collections::hash_map::DefaultHasher::new();
normalized.hash(&mut hasher);
format!("astrbot-{:016x}", hasher.finish())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn maps_live_probe_style_plain_stream() {
let mut mapper = AstrBotStreamMapper::new("astrbot-test");
let lines = [
r#"data: {"type": "session_id", "data": null, "session_id": "desktop-companion-s1"}"#,
r#"data: {"type": "user_message_saved", "data": {"id": 1}}"#,
": heartbeat",
r#"data: {"type": "plain", "data": "Hello", "streaming": true, "message_id": "m1"}"#,
r#"data: {"type": "plain", "data": "!", "streaming": true, "message_id": "m1"}"#,
];
let mut events = Vec::new();
for line in lines {
events.extend(mapper.push_line(line).expect("parse"));
}
events.extend(mapper.finish_stream());
assert_eq!(mapper.session_id(), Some("desktop-companion-s1"));
assert!(
events
.iter()
.any(|event| event.body.event_type() == "system.heartbeat")
);
let deltas: Vec<_> = events
.iter()
.filter_map(|event| match &event.body {
GatewayEventBody::MessageDelta(payload) => Some(payload.delta.as_str()),
_ => None,
})
.collect();
assert_eq!(deltas, ["Hello", "!"]);
let completed = events
.iter()
.find_map(|event| match &event.body {
GatewayEventBody::MessageCompleted(payload) => payload.content.clone(),
_ => None,
})
.expect("completed");
assert_eq!(completed, "Hello!");
assert_eq!(
events.last().map(|e| e.body.event_type()),
Some("message.completed")
);
}
#[test]
fn maps_error_frames() {
let mut mapper = AstrBotStreamMapper::new("astrbot-test");
let events = mapper
.push_line(r#"data: {"type":"error","data":"provider missing"}"#)
.expect("parse");
assert_eq!(events.len(), 1);
match &events[0].body {
GatewayEventBody::Error(error) => {
assert_eq!(error.code, "astrbotStreamError");
assert!(error.message.contains("provider missing"));
}
other => panic!("unexpected {other:?}"),
}
}
#[test]
fn derives_stable_instance_ids() {
let a = derive_astrbot_server_instance_id("http://192.168.31.210:26285/");
let b = derive_astrbot_server_instance_id("http://192.168.31.210:26285");
let c = derive_astrbot_server_instance_id("http://192.168.31.210:26286");
assert_eq!(a, b);
assert_ne!(a, c);
assert!(a.starts_with("astrbot-"));
}
#[test]
fn chat_request_serializes_model_and_attachment_options() {
let request = AstrBotChatRequest {
message: Value::String("hello".into()),
session_id: Some("session-a".into()),
conversation_id: None,
username: Some("desktop".into()),
nickname: None,
config_id: Some("model-a".into()),
attachments: Some(vec![AstrBotAttachment {
attachment_id: "file-a".into(),
file_name: "image.png".into(),
mime_type: "image/png".into(),
size_bytes: 12,
url: None,
}]),
platform_id: None,
enable_streaming: Some(true),
};
let value = serde_json::to_value(request).expect("request serializes");
assert_eq!(value["config_id"], "model-a");
assert_eq!(value["attachments"][0]["attachmentId"], "file-a");
}
#[test]
fn protocol_version_constant_is_unchanged_for_internal_model() {
assert_eq!(crate::PROTOCOL_VERSION, "desktop-v1alpha1");
}
}