# Qwen3.5-9B ToolHub 增强版 (Enhanced Edition)
> **版本标识**：原版基础功能 + 本地写作/记忆 + 混合云智能路由  
> **作者**: 老王 (Lao Wang) & AI 协作伙伴  
> **最后更新**: 2026-03-12

## 🚀 项目简介
本项目是基于 **Qwen3.5-9B** 多模态模型的本地一体化部署方案。它不仅具备原版的联网搜索、看图读图能力，更通过深度二次开发实现了从“只能看”到"**能写、能记、能感知**"的质变，并引入了混合云架构以应对复杂任务。

- ✅ **原生能力**：本地 GPU 推理、OpenAI 兼容 API、多模态输入。
- ⭐ **核心增强**：原子化文件写入、持久化记忆注入、实时环境感知。
- ⭐ **智能扩展**：混合云路由（本地+DeepSeek/GPT）、粘性会话切换。

---

## 🆚 版本差异对比 (原版 vs 增强版)

| 功能模块 | 原版 (Original) | 增强版 (Enhanced v2.0+) |
| :--- | :--- | :--- |
| **模型推理** | 仅本地 Qwen3.5-9B | **本地 + 云端(DeepSeek/GPT) 混合路由** |
| **文件操作** | 🔒 只读浏览 | ✏️ **原子化写入 (白名单沙盒)** |
| **记忆系统** | ❌ 无长期记忆 | 🧠 **JSON 持久化偏好库 (热加载)** |
| **网络抓取** | 普通请求 | 🛡️ **反爬优化 (User-Agent + 重试机制)** |
| **环境感知** | 静态上下文 | ⏰ **动态注入时间/日期/星期** |
| **适用场景** | 简单问答、分析 | **代码编写、长程规划、隐私数据分析** |

---

## 🛠️ 快速开始 (Quick Start)

### 1. 环境要求
- **操作系统**: Windows 10 / 11
- **硬件**: NVIDIA 显卡 (显存 ≥ 8GB, 推荐 ≥ 12GB)
- **软件**: Python 3.10+, Git, Docker (可选)

### 2. 安装与启动
#### 首次安装 (下载约 6GB 模型)
*方法 A: 标准版 (推荐)*
```bat
# 双击运行
bootstrap.bat
```

*方法 B: Q8 量化版 (显存 ≥ 12GB，占用约 10.2GB)*
```bat
# 双击运行
bootstrap_q8.bat
```

#### 启动服务
```bat
# 启动服务 (端口 8080)
.\start_8080_toolhub_stack.cmd start

# 停止服务
.\start_8080_toolhub_stack.cmd stop
```

#### 访问界面
打开浏览器访问：**http://127.0.0.1:8080**  
*(注：首次启动需等待 30~60 秒加载模型)*

---

## ⚙️ 增强配置详解 (.env)

在启动前，请编辑项目根目录下的 `.env` 文件，根据需求开启增强功能。**注意路径不要带末尾斜杠**。

```ini
# ==========================================
# 🚀 核心运行模式
# ==========================================
# local = 仅使用本地 Qwen3.5-9B
# cloud = 仅使用云端模型 (需配置下方密钥)
MODEL_MODE=local 

# ==========================================
# ☁️ 云端大脑配置 (DeepSeek / OpenAI 兼容)
# ==========================================
# 默认云端模型 ID (例如: deepseek-chat, gpt-4o-mini)
CLOUD_MODEL_ID=deepseek-chat
# 云端 API Base URL
CLOUD_BASE_URL=https://api.deepseek.com/v1
# 云端 API Key (请勿泄露)
CLOUD_API_KEY=sk-your-key-here

# ==========================================
# 🛠️ 文件系统增强 (写入功能)
# ==========================================
# [True/False] 是否允许 AI 物理写入本地文件
ENABLE_FILE_WRITE=True

# 📂 安全沙盒：只允许在此目录下写入 (支持多个路径用分号隔开)
# 示例: E:\AI_Workspace;D:\Projects\Temp
WRITEABLE_FS_ROOTS=E:\AI_Workspace

# ==========================================
# 🧠 持久记忆系统
# ==========================================
# 记忆文件绝对或相对路径 (必须确保目录存在)
MEMORY_FILE_PATH=./.tmp/super_agent_data/memory.json
```

---

## 🧠 核心高级功能说明

### 1. 混合云智能路由 (Hybrid Cloud Routing)
系统不再是非黑即白的单模型选择，而是基于**语义意图**和**手动指令**的智能切换：

- **自动分流**: 
    - **高频/隐私任务** -> 自动路由至本地 `Qwen3.5-9B` (零成本，高速度)。
    - **复杂逻辑/大规模编程** -> 自动路由至云端 `DeepSeek/GPT` (强逻辑，长文本)。
- **手动干预 (粘性切换)**:
    - 输入 `/cloud ...`: 强制当前及后续对话切换到云端，直到再次切换。
    - 输入 `/local ...`: 强制切回本地模型。
    - *特性*: 系统会记住您最近的切换指令，保持上下文一致性。

### 2. 原子化物理写入 (Atomic Write Engine)
赋予模型真正的“动手能力”，但处于严格保护中：
- **安全机制**: 只有 `WRITEABLE_FS_ROOTS` 指定的目录内的文件可被修改/创建。
- **应用场景**: 自动生成代码文件、整理日志、构建文档。
- **警告**: 严禁将 `SYSTEM` 或 `Program Files` 等系统目录加入白名单。

### 3. 持久化记忆热注入 (Persistent Memory)
- **原理**: 每次对话开始时，系统会自动读取 `memory.json` 中的内容，并将其作为 System Prompt 的一部分注入给 AI。
- **用途**: 记住您的昵称（如“老王”）、工作习惯（如“代码必须加注释”、“Markdown 格式”）、偏好设置。
- **数据格式**: 支持纯列表 `["item1"]` 或对象包装 `{"items": [...]}`，系统自动容错。

### 4. 反侦察网页抓取
针对 GitHub、Google Scholar 等高防御网站进行了优化：
- 内置主流浏览器 User-Agent 伪装。
- 集成指数退避重试策略，自动处理 HTTP 429 (Too Many Requests) 错误。

---

## 🐞 故障排查 (Troubleshooting)

| 现象 | 可能原因 | 解决方案 |
| :--- | :--- | :--- |
| **Network Error** | 网关未注册 Write 工具 | 检查 `toolhub_gateway_agent.py` 是否包含 `import agent_runtime.write_tools` |
| **AI "失忆"** | `memory.json` 格式错误 | 检查 JSON 是否有**末尾逗号**；运行诊断脚本 `python diagnose_memory.py` |
| **无法写入文件** | 路径不在白名单 | 确认写入路径是否在 `WRITEABLE_FS_ROOTS` 列表中，且目录已存在 |
| **云端切换无效** | 指令格式错误 | 确保 `/cloud` 后紧跟一个空格再写内容，如 `/cloud 帮我写个算法` |
| **HTTP 429 报错** | 频繁刷新网页 | 等待几秒重试，新版已自动处理此类重试逻辑 |

---

## 📁 常用操作指令速查

| 指令类型 | 用法示例 | 作用 |
| :--- | :--- | :--- |
| **正常对话** | `(直接输入)` | 遵循 `.env` 默认路由模式 |
| **强制云端** | `/cloud 分析一下这个复杂的架构` | 立即切换至云端大模型 |
| **强制本地** | `/local 看看我的本地日志 file.log` | 立即切换回本地小模型，节省 Token |
| **查看状态** | `(询问系统信息)` | AI 会汇报当前时间、模型负载及路由状态 |

---

## 📝 开发者笔记
- **记忆文件格式**: 建议由用户手动维护或使用官方导出工具生成，避免手滑产生非法 JSON 字符。
- **日志查看**: Windows 下直接运行批处理脚本时，命令行窗口即为实时日志终端。
- **数据安全**: 所有的模型权重、记忆文件和日志均存储在本地 (`E:\Qwen3.5...`)，不上传任何私有数据至公有云（除非明确使用 `/cloud` 处理非敏感数据）。

---
*祝你调试愉快！如有问题，请查阅 logs 文件或联系老王团队。*