fix(assistant): normalize avatar storage and identity (#558)

## Summary
- Store user assistant avatars as managed filenames instead of local
absolute paths, and repair legacy local path rows at startup.
- Resolve conversation/team/cron assistant identity from current
assistant definitions instead of mutable snapshot avatar/name fields.
- Serve assistant avatar routes from managed definition values with
cache-busting response URLs and no directory scan fallback.

## Related PRs
- Frontend rendering changes: iOfficeAI/AionUi#3493

## Test Plan
- cargo fmt --all
- cargo test -p aionui-app --test assistants_e2e avatar
- cargo test -p aionui-conversation
create_routes_asset_avatar_in_assistant_identity_through_backend
- cargo test -p aionui-team
tc_create_team_prefers_assistant_avatar_over_backend_logo
- just push -u origin fix/assistant-avatar-source

Co-authored-by: zk <>

Author: kaizhou-lab

crates/aionui-api-types/src/assistant.rs

@@ -215,6 +215,62 @@ pub struct AssistantDetailResponse {
     pub preferences: AssistantPreferencesResponse,
 }
 
+pub fn assistant_avatar_response_value(
+    avatar_type: &str,
+    avatar_value: Option<&str>,
+    assistant_id: &str,
+) -> Option<String> {
+    if matches!(avatar_type, "builtin_asset" | "user_asset") {
+        return Some(format!("/api/assistants/{assistant_id}/avatar"));
+    }
+
+    let value = avatar_value.map(str::trim).filter(|value| !value.is_empty())?;
+
+    match avatar_type {
+        _ if is_unsupported_direct_avatar_value(value) => None,
+        _ if is_local_avatar_value(value) => None,
+        _ => Some(value.to_owned()),
+    }
+}
+
+pub fn assistant_avatar_response_value_with_version(
+    avatar_type: &str,
+    avatar_value: Option<&str>,
+    assistant_id: &str,
+    version: i64,
+) -> Option<String> {
+    if matches!(avatar_type, "builtin_asset" | "user_asset") {
+        return Some(format!("/api/assistants/{assistant_id}/avatar?v={version}"));
+    }
+
+    assistant_avatar_response_value(avatar_type, avatar_value, assistant_id)
+}
+
+pub fn is_local_avatar_value(value: &str) -> bool {
+    let value = value.trim();
+    if value.is_empty() {
+        return false;
+    }
+    if value.starts_with("file://") {
+        return true;
+    }
+    if value.starts_with("/api/") || value.starts_with("/assets/") {
+        return false;
+    }
+    if value.starts_with("//") || value.contains("://") || value.starts_with("data:") {
+        return false;
+    }
+    if value.as_bytes().get(1) == Some(&b':') && matches!(value.as_bytes().first(), Some(b'A'..=b'Z' | b'a'..=b'z')) {
+        return true;
+    }
+    std::path::Path::new(value).is_absolute()
+}
+
+fn is_unsupported_direct_avatar_value(value: &str) -> bool {
+    let value = value.trim().to_ascii_lowercase();
+    value.starts_with("http://") || value.starts_with("https://") || value.starts_with("data:")
+}
+
 // ---------------------------------------------------------------------------
 // Request types
 // ---------------------------------------------------------------------------
@@ -345,6 +401,61 @@ mod tests {
         assert!(parsed.is_err());
     }
 
+    #[test]
+    fn assistant_avatar_response_value_routes_asset_values_through_backend() {
+        assert_eq!(
+            assistant_avatar_response_value("user_asset", Some("data:image/svg+xml;base64,abc"), "custom-1").as_deref(),
+            Some("/api/assistants/custom-1/avatar")
+        );
+        assert_eq!(
+            assistant_avatar_response_value("user_asset", None, "custom-1").as_deref(),
+            Some("/api/assistants/custom-1/avatar")
+        );
+        assert_eq!(
+            assistant_avatar_response_value("user_asset", Some("https://example.invalid/avatar.png"), "custom-1")
+                .as_deref(),
+            Some("/api/assistants/custom-1/avatar")
+        );
+    }
+
+    #[test]
+    fn assistant_avatar_response_value_with_version_routes_asset_values_through_backend() {
+        assert_eq!(
+            assistant_avatar_response_value_with_version("user_asset", Some("custom-1.png"), "custom-1", 1782714544060)
+                .as_deref(),
+            Some("/api/assistants/custom-1/avatar?v=1782714544060")
+        );
+        assert_eq!(
+            assistant_avatar_response_value_with_version("emoji", Some("🧠"), "custom-1", 1782714544060).as_deref(),
+            Some("🧠")
+        );
+    }
+
+    #[test]
+    fn assistant_avatar_response_value_never_exposes_local_paths() {
+        assert_eq!(
+            assistant_avatar_response_value(
+                "user_asset",
+                Some("/Users/veryliu/.aionui/assistant-avatars/custom-1.jpg"),
+                "custom-1",
+            )
+            .as_deref(),
+            Some("/api/assistants/custom-1/avatar")
+        );
+        assert_eq!(
+            assistant_avatar_response_value(
+                "emoji",
+                Some("file:///Users/veryliu/.aionui/assistant-avatars/custom-1.jpg"),
+                "custom-1",
+            ),
+            None
+        );
+        assert_eq!(
+            assistant_avatar_response_value("emoji", Some("https://example.invalid/avatar.png"), "custom-1"),
+            None
+        );
+    }
+
     #[test]
     fn assistant_response_round_trip_snake_case() {
         let resp = AssistantResponse {

crates/aionui-api-types/src/lib.rs

@@ -56,7 +56,8 @@ pub use assistant::{
     AssistantDetailResponse, AssistantEngineResponse, AssistantPreferencesResponse, AssistantProfileResponse,
     AssistantPromptsResponse, AssistantResponse, AssistantRulesResponse, AssistantSource, AssistantStateResponse,
     CreateAssistantRequest, ImportAssistantsRequest, ImportAssistantsResult, ImportError, SetAssistantStateRequest,
-    UpdateAssistantRequest,
+    UpdateAssistantRequest, assistant_avatar_response_value, assistant_avatar_response_value_with_version,
+    is_local_avatar_value,
 };
 pub use auth::{
     AuthStatusResponse, ChangePasswordRequest, LoginRequest, LoginResponse, PublicUser, QrLoginRequest,

crates/aionui-app/tests/assistants_e2e.rs

@@ -117,6 +117,24 @@ fn test_agent_row(id: &str, backend: Option<&str>, agent_type: AgentType, name:
     }
 }
 
+fn assert_versioned_avatar_route(body: &Value, expected_path: &str) {
+    assert_versioned_avatar_value(body["data"]["avatar"].as_str(), expected_path);
+}
+
+fn assert_versioned_avatar_value(value: Option<&str>, expected_path: &str) {
+    let avatar = value.expect("avatar must be a string");
+    let (path, version) = avatar
+        .split_once("?v=")
+        .expect("assistant avatar route must include cache-busting version");
+
+    assert_eq!(path, expected_path);
+    assert!(!version.is_empty(), "avatar route version must not be empty");
+    assert!(
+        version.chars().all(|ch| ch.is_ascii_digit()),
+        "avatar route version must be numeric: {version}"
+    );
+}
+
 async fn insert_generated_bare_assistant(
     fx: &Fixture,
     assistant_id: &str,
@@ -449,9 +467,9 @@ async fn list_builtin_file_avatar_is_served_via_assistant_avatar_route() {
         .find(|assistant| assistant["id"] == "builtin-office")
         .expect("builtin-office missing from assistant list");
 
-    assert_eq!(
+    assert_versioned_avatar_value(
         builtin_office["avatar"].as_str(),
-        Some("/api/assistants/builtin-office/avatar")
+        "/api/assistants/builtin-office/avatar",
     );
 }
 
@@ -736,7 +754,7 @@ async fn create_user_avatar_from_local_file_is_served_via_assistant_avatar_route
     let resp = fx.app.clone().oneshot(req).await.unwrap();
     assert_eq!(resp.status(), StatusCode::CREATED);
     let body = body_json(resp).await;
-    assert_eq!(body["data"]["avatar"], "/api/assistants/u-avatar/avatar");
+    assert_versioned_avatar_route(&body, "/api/assistants/u-avatar/avatar");
 
     let persisted_avatar = fx.user_data_dir.join("assistant-avatars/u-avatar.png");
     assert!(
@@ -783,7 +801,7 @@ async fn create_user_avatar_from_builtin_avatar_route_copies_builtin_asset() {
     let resp = fx.app.clone().oneshot(req).await.unwrap();
     assert_eq!(resp.status(), StatusCode::CREATED);
     let body = body_json(resp).await;
-    assert_eq!(body["data"]["avatar"], "/api/assistants/u-avatar-from-builtin/avatar");
+    assert_versioned_avatar_route(&body, "/api/assistants/u-avatar-from-builtin/avatar");
 
     let persisted_avatar = fx.user_data_dir.join("assistant-avatars/u-avatar-from-builtin.png");
     assert!(
@@ -833,10 +851,7 @@ async fn create_user_avatar_from_absolute_builtin_avatar_route_copies_builtin_as
     let resp = fx.app.clone().oneshot(req).await.unwrap();
     assert_eq!(resp.status(), StatusCode::CREATED);
     let body = body_json(resp).await;
-    assert_eq!(
-        body["data"]["avatar"],
-        "/api/assistants/u-avatar-from-builtin-absolute/avatar"
-    );
+    assert_versioned_avatar_route(&body, "/api/assistants/u-avatar-from-builtin-absolute/avatar");
 
     let persisted_avatar = fx
         .user_data_dir
@@ -1270,7 +1285,7 @@ async fn avatar_builtin_returns_bytes_with_content_type() {
 }
 
 #[tokio::test]
-async fn avatar_user_returns_bytes_after_file_planted() {
+async fn avatar_user_ignores_planted_file_without_managed_value() {
     let fx = fixture().await;
     create_user(&fx, "u1", "A").await;
     let avatars_dir = fx.user_data_dir.join("assistant-avatars");
@@ -1283,11 +1298,7 @@ async fn avatar_user_returns_bytes_after_file_planted() {
         .oneshot(get_with_token("/api/assistants/u1/avatar", &fx.token))
         .await
         .unwrap();
-    assert_eq!(resp.status(), StatusCode::OK);
-    assert_eq!(
-        resp.headers().get("content-type").and_then(|v| v.to_str().ok()),
-        Some("image/svg+xml")
-    );
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
 }
 
 #[tokio::test]

crates/aionui-assistant/src/routes.rs

@@ -124,6 +124,7 @@ async fn get_avatar(State(state): State<AssistantRouterState>, Path(id): Path<St
     Response::builder()
         .status(StatusCode::OK)
         .header(header::CONTENT_TYPE, content_type)
+        .header(header::CACHE_CONTROL, "no-store")
         .body(Body::from(asset.bytes))
         .map_err(|e| ApiError::Internal(e.to_string()))
 }