From 693881062566538780055c7e71cfd048ee703308 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 1 Nov 2025 17:56:01 +0000
Subject: [PATCH 1/6] Initial plan


From 73dfddbdc6f6c13e8dc266ece5e4885447edf5dc Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 1 Nov 2025 18:13:12 +0000
Subject: [PATCH 2/6] Fix knowledge base DocumentStorage connection attribute
 error

- Add defensive @property to DocumentStorage that raises helpful error when old code tries to access .connection
- Update v4.5.1 changelog with fix for issue #3191
- The .connection attribute was removed in 4.5.0 refactor; this provides clear error message for users with cached bytecode or outdated plugins

Co-authored-by: LIghtJUNction <106986785+LIghtJUNction@users.noreply.github.com>
---
 .../db/vec_db/faiss_impl/document_storage.py     | 16 ++++++++++++++++
 changelogs/v4.5.1.md                             |  1 +
 2 files changed, 17 insertions(+)

diff --git a/astrbot/core/db/vec_db/faiss_impl/document_storage.py b/astrbot/core/db/vec_db/faiss_impl/document_storage.py
index e27eb6fe8..bc8a321f1 100644
--- a/astrbot/core/db/vec_db/faiss_impl/document_storage.py
+++ b/astrbot/core/db/vec_db/faiss_impl/document_storage.py
@@ -43,6 +43,22 @@ def __init__(self, db_path: str):
             "sqlite_init.sql",
         )
 
+    @property
+    def connection(self):
+        """Compatibility property for old code trying to access .connection attribute.
+
+        This was removed in AstrBot 4.5.0 when the database was migrated to async operations.
+        External plugins or cached bytecode may still reference this attribute.
+        """
+        raise AttributeError(
+            "DocumentStorage.connection attribute was removed in AstrBot 4.5.0. "
+            "The database now uses async operations with self.engine. "
+            "If you're seeing this error, please: "
+            "1. Clear Python cache files: find data/plugins -name '*.pyc' -delete "
+            "2. Update any custom plugins that use DocumentStorage "
+            "3. Restart AstrBot"
+        )
+
     async def initialize(self):
         """Initialize the SQLite database and create the documents table if it doesn't exist."""
         await self.connect()
diff --git a/changelogs/v4.5.1.md b/changelogs/v4.5.1.md
index 94462b803..397c33421 100644
--- a/changelogs/v4.5.1.md
+++ b/changelogs/v4.5.1.md
@@ -5,3 +5,4 @@
 3. 新增: xAI Grok Live Search
 4. 优化: 插件卡片左下角恢复 文档 按钮并新增 插件配置 按钮。
 5. 优化: 更好地适配 Class 方式注册 LLM Tool。
+6. 修复：知识库日志中出现的 `'DocumentStorage' object has no attribute 'connection'` 错误 ([#3191](https://github.com/AstrBotDevs/AstrBot/issues/3191))

From 458ab1243c34ee8c8a4c457b75d0a1c8b63225ac Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 1 Nov 2025 18:16:04 +0000
Subject: [PATCH 3/6] Improve error message with better guidance and portable
 commands

- Add specific instructions for plugin developers (use self.engine and get_session())
- Improve shell command with proper command chaining and error handling
- Make error message more actionable with concrete examples

Co-authored-by: LIghtJUNction <106986785+LIghtJUNction@users.noreply.github.com>
---
 .../core/db/vec_db/faiss_impl/document_storage.py   | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/astrbot/core/db/vec_db/faiss_impl/document_storage.py b/astrbot/core/db/vec_db/faiss_impl/document_storage.py
index bc8a321f1..8a90dec3e 100644
--- a/astrbot/core/db/vec_db/faiss_impl/document_storage.py
+++ b/astrbot/core/db/vec_db/faiss_impl/document_storage.py
@@ -52,11 +52,14 @@ def connection(self):
         """
         raise AttributeError(
             "DocumentStorage.connection attribute was removed in AstrBot 4.5.0. "
-            "The database now uses async operations with self.engine. "
-            "If you're seeing this error, please: "
-            "1. Clear Python cache files: find data/plugins -name '*.pyc' -delete "
-            "2. Update any custom plugins that use DocumentStorage "
-            "3. Restart AstrBot"
+            "The database now uses async operations with self.engine and async context managers. "
+            "\n\nIf you're seeing this error, please: "
+            "\n1. Clear Python cache files: find data/plugins -name '*.pyc' -delete && find data/plugins -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true "
+            "\n2. Update any custom plugins that use DocumentStorage: "
+            "\n   - Replace 'self.connection' with 'self.engine' "
+            "\n   - Use 'async with self.get_session() as session' for database operations "
+            "\n   - See DocumentStorage source code for examples "
+            "\n3. Restart AstrBot"
         )
 
     async def initialize(self):

From 78f18cf06ba721fa24b225e3baa818f057fd15f0 Mon Sep 17 00:00:00 2001
From: LIghtJUNction <lightjunction.me@gmail.com>
Date: Sun, 2 Nov 2025 02:25:17 +0800
Subject: [PATCH 4/6] Update
 astrbot/core/db/vec_db/faiss_impl/document_storage.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 .../core/db/vec_db/faiss_impl/document_storage.py  | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/astrbot/core/db/vec_db/faiss_impl/document_storage.py b/astrbot/core/db/vec_db/faiss_impl/document_storage.py
index 8a90dec3e..489ae58de 100644
--- a/astrbot/core/db/vec_db/faiss_impl/document_storage.py
+++ b/astrbot/core/db/vec_db/faiss_impl/document_storage.py
@@ -54,11 +54,15 @@ def connection(self):
             "DocumentStorage.connection attribute was removed in AstrBot 4.5.0. "
             "The database now uses async operations with self.engine and async context managers. "
             "\n\nIf you're seeing this error, please: "
-            "\n1. Clear Python cache files: find data/plugins -name '*.pyc' -delete && find data/plugins -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true "
-            "\n2. Update any custom plugins that use DocumentStorage: "
-            "\n   - Replace 'self.connection' with 'self.engine' "
-            "\n   - Use 'async with self.get_session() as session' for database operations "
-            "\n   - See DocumentStorage source code for examples "
+            "\n1. Clear Python cache files:"
+            "\n   - On Unix/macOS: find data/plugins -name '*.pyc' -delete && find data/plugins -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true"
+            "\n   - On Windows: Delete all .pyc files and __pycache__ folders in data\\plugins manually, or run:"
+            "\n       del /s data\\plugins\\*.pyc"
+            "\n       rmdir /s /q data\\plugins\\__pycache__"
+            "\n2. Update any custom plugins that use DocumentStorage:"
+            "\n   - Replace 'self.connection' with 'self.engine'"
+            "\n   - Use 'async with self.get_session() as session' for database operations"
+            "\n   - See DocumentStorage source code for examples"
             "\n3. Restart AstrBot"
         )
 

From fcacc6a53ed262cc36346b552dfe34ba05ff4c68 Mon Sep 17 00:00:00 2001
From: LIghtJUNction <lightjunction.me@gmail.com>
Date: Sun, 2 Nov 2025 02:25:31 +0800
Subject: [PATCH 5/6] Update changelogs/v4.5.1.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 changelogs/v4.5.1.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/changelogs/v4.5.1.md b/changelogs/v4.5.1.md
index 397c33421..2cbf86f18 100644
--- a/changelogs/v4.5.1.md
+++ b/changelogs/v4.5.1.md
@@ -5,4 +5,4 @@
 3. 新增: xAI Grok Live Search
 4. 优化: 插件卡片左下角恢复 文档 按钮并新增 插件配置 按钮。
 5. 优化: 更好地适配 Class 方式注册 LLM Tool。
-6. 修复：知识库日志中出现的 `'DocumentStorage' object has no attribute 'connection'` 错误 ([#3191](https://github.com/AstrBotDevs/AstrBot/issues/3191))
+6. 修复: 知识库日志中出现的 `'DocumentStorage' object has no attribute 'connection'` 错误 ([#3191](https://github.com/AstrBotDevs/AstrBot/issues/3191))

From 8202e536205eadbf3922efb289d5d27520987968 Mon Sep 17 00:00:00 2001
From: LIghtJUNction <lightjunction.me@gmail.com>
Date: Sun, 2 Nov 2025 02:30:36 +0800
Subject: [PATCH 6/6] Update
 astrbot/core/db/vec_db/faiss_impl/document_storage.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 astrbot/core/db/vec_db/faiss_impl/document_storage.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/astrbot/core/db/vec_db/faiss_impl/document_storage.py b/astrbot/core/db/vec_db/faiss_impl/document_storage.py
index 489ae58de..e25357aa0 100644
--- a/astrbot/core/db/vec_db/faiss_impl/document_storage.py
+++ b/astrbot/core/db/vec_db/faiss_impl/document_storage.py
@@ -55,7 +55,7 @@ def connection(self):
             "The database now uses async operations with self.engine and async context managers. "
             "\n\nIf you're seeing this error, please: "
             "\n1. Clear Python cache files:"
-            "\n   - On Unix/macOS: find data/plugins -name '*.pyc' -delete && find data/plugins -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true"
+            "\n   - On Unix/macOS: find data/plugins -name '*.pyc' -delete && find data/plugins -type d -name '__pycache__' -prune -exec rm -rf {} \\; 2>/dev/null || true"
             "\n   - On Windows: Delete all .pyc files and __pycache__ folders in data\\plugins manually, or run:"
             "\n       del /s data\\plugins\\*.pyc"
             "\n       rmdir /s /q data\\plugins\\__pycache__"