Hotfix/2.6.0 (#2233)

This pull request introduces a new normalized table for message-citation
relations, updates citation repository logic to support both legacy and
new models, and improves error handling and logging. It also updates the
project version to `2.6.0-fix` and ensures all relevant containers use
the new image tag.

**Message-Citation Relation Normalization:**

* Added `MessageCitationRelation` and `MessageCitationRelationBase`
models to represent the association between messages and citations,
including a unique constraint on `(message_id, citation_id)`
(`[[1]](diffhunk://#diff-186aa205991c0eac4a1387fdf8e234009fae675f94ed330d04a3310bc1f8d18cR34-R67)`,
`[[2]](diffhunk://#diff-8cdbc5b6b1f410bf0bca612f26079028955deb6a664953ce88957d1f9aaea4b6L1-R13)`,
`[[3]](diffhunk://#diff-1d8ee5758e663e5b5e7659c59a1be5d82d1e1a8b5a3c6730ce3a42ae33a5f32dL1-R13)`).
* Created new repository methods in `MessageCitationRepositoryImpl` for
ensuring citations and relations exist (with race condition handling),
and for querying citations through both the new relation table and
legacy model
(`[[1]](diffhunk://#diff-0b2053b79f9ba1ce49a7e592bad4024baaf7ad5c43b081dd4f1dd1110858931eL18-R178)`,
`[[2]](diffhunk://#diff-0b2053b79f9ba1ce49a7e592bad4024baaf7ad5c43b081dd4f1dd1110858931eL69-R322)`).

**Repository and Query Logic Updates:**

* Updated all relevant repository methods to support both the new
normalized relation table and the legacy citation ownership, including
deduplication and ordering helpers
(`[[1]](diffhunk://#diff-0b2053b79f9ba1ce49a7e592bad4024baaf7ad5c43b081dd4f1dd1110858931eL18-R178)`,
`[[2]](diffhunk://#diff-0b2053b79f9ba1ce49a7e592bad4024baaf7ad5c43b081dd4f1dd1110858931eL69-R322)`).
* Added batch creation and retrieval methods for citations and
relations, with both async and sync variants
(`[[1]](diffhunk://#diff-0b2053b79f9ba1ce49a7e592bad4024baaf7ad5c43b081dd4f1dd1110858931eL18-R178)`,
`[[2]](diffhunk://#diff-0b2053b79f9ba1ce49a7e592bad4024baaf7ad5c43b081dd4f1dd1110858931eL69-R322)`).

**Error Handling and Logging Improvements:**

* Updated logging to use `logger.opt(exception=True).warning(...)`
instead of passing `exc_info=`, which is not supported by loguru and can
cause runtime errors
(`[[1]](diffhunk://#diff-28b48f7c52734619b80a958f872695c431f29f8e180ee63ac3ff152ccedbb302L310-R310)`,
`[[2]](diffhunk://#diff-5fd402ae0d329b78a7cb9bce444327d8045c72c13b7223b5832e2ec3830ddcd8R31)`).

**Version and Deployment Updates:**

* Bumped the backend and frontend version to `2.6.0-fix` in
`__init__.py` and `docker-compose.yml` to ensure all services use the
updated code and images
(`[[1]](diffhunk://#diff-6593331a7fecd32e889ab36d3ef3c414587b13d753f28bf59b5f311c5c8f9daeL7-R7)`,
`[[2]](diffhunk://#diff-423deb13b7c401b1a7f41ee91c77f722e11d2f317d6a66b546524e8a04cc8b03L84-R84)`,
`[[3]](diffhunk://#diff-423deb13b7c401b1a7f41ee91c77f722e11d2f317d6a66b546524e8a04cc8b03L126-R126)`,
`[[4]](diffhunk://#diff-423deb13b7c401b1a7f41ee91c77f722e11d2f317d6a66b546524e8a04cc8b03L159-R159)`).

**Dependency and Import Adjustments:**

* Updated imports to include new models and handle additional
dependencies required by the new logic
(`[[1]](diffhunk://#diff-186aa205991c0eac4a1387fdf8e234009fae675f94ed330d04a3310bc1f8d18cL4-R4)`,
`[[2]](diffhunk://#diff-0b2053b79f9ba1ce49a7e592bad4024baaf7ad5c43b081dd4f1dd1110858931eL2-R7)`).

These changes collectively migrate citation management to a more
normalized structure, improve reliability under concurrent access, and
address logging pitfalls.

Author: zgqgit

docker/docker-compose.yml

@@ -81,7 +81,7 @@ services:
 
   backend:
     container_name: bisheng-backend
-    image: dataelement/bisheng-backend:v2.6.0
+    image: dataelement/bisheng-backend:v2.6.0-fix
     ports:
       - "7860:7860"
     environment:
@@ -123,7 +123,7 @@ services:
 
   backend_worker:
     container_name: bisheng-backend-worker
-    image: dataelement/bisheng-backend:v2.6.0
+    image: dataelement/bisheng-backend:v2.6.0-fix
     environment:
       TZ: Asia/Shanghai
       BS_SSO_SYNC__GATEWAY_HMAC_SECRET: "bisheng-local-hmac-20260422"
@@ -156,7 +156,7 @@ services:
 
   frontend:
     container_name: bisheng-frontend
-    image: dataelement/bisheng-frontend:v2.6.0
+    image: dataelement/bisheng-frontend:v2.6.0-fix
     ports:
       - "3001:3001"
     environment:

src/backend/AGENTS.md

@@ -28,6 +28,7 @@ Error codes (MMMEE) & module numbers → constitution **C5**. Pagination: `PageD
 - **Never use printf `%s` / `%r` / `%d` with loguru.** It does not interpolate them — the placeholder is printed literally and the args are silently dropped (this is a real bug, not a style nit: it has burned dry-run scripts).
 - f-strings (`logger.info(f"...")`) are also safe and still common in the tree; acceptable, but prefer `{}` for new logs.
 - Never downgrade `logger.exception(...)` (auto-attaches the traceback) to `logger.error`.
+- **Never pass `exc_info=` to loguru** — it has no such parameter, and *any* kwarg makes loguru run `str.format()` on the message. A message embedding a provider error (`Error code: 429 - {'error': {...}}`) then raises `KeyError` from inside `Logger._log`, before any handler. Want a traceback? `logger.exception(msg)` for ERROR, `logger.opt(exception=True).warning(msg)` for other levels. Guarded by `test/common/test_loguru_exc_info_guard.py`. Files using stdlib `logging.getLogger` are exempt — there `exc_info=` is correct and `core/logger.py`'s `InterceptHandler` forwards it properly.
 
 ---
 

src/backend/bisheng/__init__.py

@@ -4,7 +4,7 @@
 
 try:
     # SetujuciGo to automatic modification
-    __version__ = '2.6.0'
+    __version__ = '2.6.0-fix'
 except metadata.PackageNotFoundError:
     # Case where package metadata is not available.
     __version__ = ''

src/backend/bisheng/api/services/knowledge_imp.py

@@ -307,7 +307,7 @@ def addEmbedding(
                         f"similar_scan_sync file_id={db_file.id} skipped: no simhash in memory"
                     )
             except Exception:
-                logger.warning("similar scan (sync) failed", exc_info=True)
+                logger.opt(exception=True).warning("similar scan (sync) failed")
 
             if enable_auto_tags:
                 KnowledgeSpaceAutoTagService.apply_after_upload_parse(

src/backend/bisheng/citation/domain/__init__.py

@@ -1,3 +1,13 @@
-from bisheng.citation.domain.models import MessageCitation, MessageCitationBase
+from bisheng.citation.domain.models import (
+    MessageCitation,
+    MessageCitationBase,
+    MessageCitationRelation,
+    MessageCitationRelationBase,
+)
 
-__all__ = ['MessageCitation', 'MessageCitationBase']
+__all__ = [
+    "MessageCitation",
+    "MessageCitationBase",
+    "MessageCitationRelation",
+    "MessageCitationRelationBase",
+]

src/backend/bisheng/citation/domain/models/__init__.py

@@ -1,3 +1,13 @@
-from bisheng.citation.domain.models.message_citation import MessageCitation, MessageCitationBase
+from bisheng.citation.domain.models.message_citation import (
+    MessageCitation,
+    MessageCitationBase,
+    MessageCitationRelation,
+    MessageCitationRelationBase,
+)
 
-__all__ = ['MessageCitation', 'MessageCitationBase']
+__all__ = [
+    "MessageCitation",
+    "MessageCitationBase",
+    "MessageCitationRelation",
+    "MessageCitationRelationBase",
+]

src/backend/bisheng/citation/domain/models/message_citation.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 from typing import Any
 
-from sqlalchemy import Column, DateTime, String, text
+from sqlalchemy import Column, DateTime, Integer, String, UniqueConstraint, text
 from sqlmodel import Field
 
 from bisheng.common.models.base import SQLModelSerializable
@@ -31,3 +31,37 @@ class MessageCitation(MessageCitationBase, table=True):
     __tablename__ = "message_citation"
 
     id: int | None = Field(default=None, primary_key=True)
+
+
+class MessageCitationRelationBase(SQLModelSerializable):
+    tenant_id: int | None = Field(
+        default=None,
+        sa_column=Column(
+            Integer,
+            nullable=False,
+            server_default=text("1"),
+            index=True,
+            comment="Tenant ID",
+        ),
+    )
+    message_id: int = Field(index=True)
+    citation_id: str = Field(index=True, max_length=128)
+    created_time: datetime | None = Field(
+        default=None,
+        sa_column=Column(DateTime, nullable=False, server_default=text("CURRENT_TIMESTAMP")),
+    )
+
+
+class MessageCitationRelation(MessageCitationRelationBase, table=True):
+    """Associate one globally stored citation with one persisted chat message."""
+
+    __tablename__ = "message_citation_relation"
+    __table_args__ = (
+        UniqueConstraint(
+            "message_id",
+            "citation_id",
+            name="uq_msg_citation_rel_message_citation",
+        ),
+    )
+
+    id: int | None = Field(default=None, primary_key=True)