Auto backup \2026-\04-\20

nanobot-patches/README.md

@@ -0,0 +1,128 @@
+# nanobot 图片识别修复补丁
+
+> 适用对象：`nanobot`（uv 工具安装，位于 `~/.local/share/uv/tools/nanobot-ai/`）
+> 修复日期：2026-08-21
+> 备份目录：本目录 `/home/ubuntu/nanocode/nanobot-patches/`
+
+---
+
+## 一、问题现象
+
+使用支持视觉的模型（如 `deepseek-v4-flash-vision-exp`）时，通过 `read_file` 读取图片后，模型**看不到图片**，只收到类似 `(Image file: xxx.png)` 的占位符文本，导致无法识别图片内容。
+
+## 二、根因
+
+`nanobot/providers/openai_compat_provider.py` 的 `_sanitize_messages()` 中有一行逻辑：
+
+```python
+force_string_content = bool(self._spec and self._spec.name == "deepseek")
+```
+
+只要 provider 名字是 `deepseek`，它就把**所有**消息的 `content` 强制转为纯字符串。而 `content` 一旦是字符串，里面 `image_url` / `input_image` / `image` / `file` 等视觉块就会被剥离，图片信息丢失。
+
+> 该逻辑本意是兼容 DeepSeek 纯文本模型的"只收字符串 content"，但**一刀切**地也作用到了视觉模型上，导致视觉内容被丢弃。
+
+## 三、修复方法
+
+在 `openai_compat_provider.py` 中：
+
+1. 新增一个静态方法，判断 `content` 是否包含视觉块：
+
+```python
+@staticmethod
+def _content_has_vision_blocks(content: Any) -> bool:
+    """Return True when content is a block list containing image/file blocks.
+
+    Used to keep vision content intact for multimodal models (e.g.
+    ``deepseek-v4-flash-vision-exp``) instead of coercing it to plain text.
+    """
+    if not isinstance(content, list):
+        return False
+    for item in content:
+        mapping = OpenAICompatProvider._maybe_mapping(item)
+        if not mapping:
+            continue
+        if mapping.get("type") in ("image_url", "input_image", "image", "file"):
+            return True
+    return False
+```
+
+2. 在 `_sanitize_messages()` 的强制转字符串条件里，增加"含视觉块则跳过"的判断：
+
+```python
+if (
+    force_string_content
+    and not (clean.get("role") == "assistant" and clean.get("tool_calls"))
+    and not OpenAICompatProvider._content_has_vision_blocks(clean.get("content"))
+):
+    clean["content"] = self._coerce_content_to_string(clean.get("content"))
+```
+
+> 关键点：`_content_has_vision_blocks()` 判断在 `_coerce_content_to_string()` **之前**生效，视觉块因此被保留。纯文本消息仍会走原字符串转换逻辑，不受影响。
+
+## 四、涉及文件与路径
+
+- 被修改文件：
+  `/home/ubuntu/.local/share/uv/tools/nanobot-ai/lib/python3.11/site-packages/nanobot/providers/openai_compat_provider.py`
+
+- 本目录备份：
+  - `openai_compat_provider.py.before_patch` —— 修复**前**（旧）文件
+  - `openai_compat_provider.py.after_patch` —— 修复**后**（当前）文件
+
+## 五、⚠️ 重要：uv 升级会覆盖补丁
+
+`nanobot-ai` 是通过 `uv tool` 安装的。一旦执行升级（例如 `uv tool upgrade nanobot-ai` 或重新安装），`site-packages` 下的文件会被**覆盖**，补丁随之丢失。
+
+**重新打补丁的方法**（升级后执行）：
+
+```bash
+# 1. 确认当前文件与 before_patch 是否一致（若一致说明补丁已丢失）
+diff /home/ubuntu/nanocode/nanobot-patches/openai_compat_provider.py.before_patch \
+     /home/ubuntu/.local/share/uv/tools/nanobot-ai/lib/python3.11/site-packages/nanobot/providers/openai_compat_provider.py
+
+# 2. 若补丁丢失，用 after_patch 覆盖回去
+cp /home/ubuntu/nanocode/nanobot-patches/openai_compat_provider.py.after_patch \
+   /home/ubuntu/.local/share/uv/tools/nanobot-ai/lib/python3.11/site-packages/nanobot/providers/openai_compat_provider.py
+
+# 3. 重启 nanobot 服务使补丁生效
+sudo systemctl restart nanobot
+```
+
+## 六、验证方法
+
+用 nanobot 自身的 venv Python 跑一次完整链路（构造图片块 → `_sanitize_messages` → `chat`），确认 `content` 仍为 `list` 且保留 `image_url` 块，并能返回图片描述：
+
+```bash
+PY=/home/ubuntu/.local/share/uv/tools/nanobot-ai/bin/python
+$PY -c "
+import asyncio, base64
+from nanobot.providers.registry import PROVIDERS
+from nanobot.providers.openai_compat_provider import OpenAICompatProvider
+
+spec = next(s for s in PROVIDERS if s.name=='deepseek')
+key = 'sk-xxxx'  # 替换为 DeepSeek API Key
+model = 'deepseek-v4-flash-vision-exp'
+b64 = base64.b64encode(open('/path/to/img.png','rb').read()).decode()
+messages = [{'role':'user','content':[
+    {'type':'image_url','image_url':{'url':'data:image/png;base64,'+b64}},
+    {'type':'text','text':'请描述这张图片'}
+]}]
+prov = OpenAICompatProvider(api_key=key, spec=spec, default_model=model)
+async def main():
+    s = prov._sanitize_messages(messages)
+    print('blocks:', [b.get('type') for b in s[0]['content']])  # 期望 ['image_url','text']
+    resp = await prov.chat(messages, model=model)
+    print(resp.text)
+asyncio.run(main())
+"
+```
+
+## 七、关于"识别能力"的说明
+
+- **图片识别能力本身**是模型自带的（如 `deepseek-v4-flash-vision-exp`、Kimi 等视觉模型都支持），**不需要**记忆到 nanobot 的长期记忆里。
+- **需要防丢失的**是"代码补丁"这一工程事实：它属于 `site-packages` 的源码改动，会随 `uv` 升级被覆盖。因此用**文档 + 前后备份**来保护，而不是当作模型能力去记忆。
+
+## 八、关联历史
+
+- 修改前备份文件：`/home/ubuntu/backup_openai_compat_provider.py.1787316174`
+- 历史记忆（memory）中的补丁位置与"uv 升级会覆盖、需重新打"的记录与此文档一致。