# Qwen3.5-9B ToolHub Enhanced Version

> **版本标识**：**原版基础功能 + 二开增强模块** | **Qwen3.5 多模态工具链本地一体化部署方案**

基于 Qwen3.5-9B 多模态模型 + 可调用工具的本地一体化部署方案。本项目是在原版基础上深度二次开发，实现了 AI 从"只能看"到"**能写、能记、能感知**"的质变。

---

## 📌 项目定位与声明

### 基础定位
- ✅联网搜索、看图、读文件（原版能力）
- **模型推理在本机 GPU 完成，可通过 API 接口使用**
- 需要 Windows 10/11、NVIDIA 显卡（≥8GB 显存）、Python 3.10+

### 声明
本版本由 **老王 (Lao Wang)** 及 AI 协作伙伴共同完成，旨在探索本地小规模参数模型在实际办公场景中的生产力极限。  
开源致谢：[Qwen3.5](https://github.com/QwenLM/Qwen3) | [llama.cpp](https://github.com/ggml-org/llama.cpp)

---

## 🚀 核心增强功能（二开版独有）

### 1. ⚡ 原子化物理写入引擎 (Atomic Write Engine)
- **功能突破**：新增 `write_tools.py` 模块，赋予模型真正的"物理写权限"
- **静默落盘**：通过 `.env`环境变量配置 `WRITEABLE_FS_ROOTS`白名单，实现安全、极速的自动化文件保存
- **沙盒保护**：严格限制写入目录，确保系统核心文件的安全

### 2. 🧠 "睁眼即知"的持久化记忆热注入 (Persistent Memory Injection)
- **长期记忆库**：独立开发 `memory_tools.py`，支持基于 JSON 的偏好、身份和习惯存储
- **热加载技术**：重构 `toolhub_gateway_agent.py`，在每一轮对话初始化时，将 `memory.json`内容动态注入 System Prompt
- **零开销感知**：AI 无需主动翻阅本子，即可毫秒级感知用户昵称（如"老王"）、特定排版偏好（如 Markdown）等重要信息

### 3. 🛡️ 反侦察网页抓取增强 (Robust Web Fetcher)
- **HTTP 429 修复**：解决了原版抓取 GitHub 等站点时频发的 HTTP 429 错误
- **技术细节**：集成主流浏览器 User-Agent伪装，引入指数补偿重试逻辑

### 4. ⏰ 实时环境感知系统
- **时效性补全**：动态注入系统实时时间、星期及运行环境上下文，显著提升处理时间敏感型指令的准确度

---

## ✅ 完整功能清单（合并版）

| 能力类别 | 基础功能 (原版) | 增强功能 (二开) |
|---------|-----------------|---------------|
| **联网搜索** | ✅网页抓取、摘要提炼、附来源链接 | ✅反爬优化，429错误自动重试 |
| **图片处理** | ✅看图提问、局部放大、以图搜图 | - |
| **文件操作** | ✅只读浏览本机文件/日志 | ⭐原子化写入（白名单沙盒） |
| **记忆管理** | 无长期记忆 | ⭐JSON持久化偏好库 |
| **环境感知** | 基础上下文 | ⭐实时时间/星期动态注入 |
| **API接口** | ✅OpenAI兼容 API (v1) | - |

---

## 🛠️ 安装与配置（完整流程）

### 主线部署：Windows 默认方式（推荐新手）

#### 首次安装（约6GB模型）
```bash
# 方法一：标准启动脚本（双击运行）
bootstrap.bat

# 方法二：Q8量化版（显存≥12GB，占用约10.2GB）
bootstrap_q8.bat
```

#### 启动服务
```bash
.\start_8080_toolhub_stack.cmd start
# 浏览器访问 http://127.0.0.1:8080

停止：.\start_8080_toolhub_stack.cmd stop
```

> ⚠️ **每次启动需要30–60秒加载模型**

---

### 🔧 增强配置（二开版专属）

在 `.env`文件中添加以下配置以启用增强功能：

```env
# =========================================
# 【二开版】增强功能开关与路径配置
# =========================================

# ✅ 开启文件写入功能
ENABLE_FILE_WRITE=True

# 📂 写入权限白名单（沙盒保护）
WRITEABLE_FS_ROOTS=E:\AI_Workspace

# 💾 记忆文件存储路径
MEMORY_FILE_PATH=./.tmp/super_agent_data/memory.json
```

---

### 其他部署路线

- **🧊 WSL 模式** — 已有WSL环境的用户  
  ```bash
  ./install.sh + ./start_8080_toolhub_stack.sh start
  ```
  底层复用Windows主链路，适合双系统开发场景。

---

## 📖 文档导航

| 章节 | 说明 | 路径 |
|------|------|------|
| [详细介绍](docs/QUICKSTART.md) | 安装、启动、配置、服务管理 | docs/QUICKSTART.md |
| [常见问题](docs/TROUBLESHOOTING.md) | 排障指引，含HTTP 429处理 | docs/TROUBLESHOOTING.md |
| [Docker Compose](docs/DOCKER_COMPOSE.md) | 容器化部署指南 | docs/DOCKER_COMPOSE.md |

---

## 📊 系统实时状态（环境上下文）

```text
当前时间：🕒 2026-03-11 星期三 16:29:03 CST
运行模式：本地 GPU 推理 + OpenAI API兼容层
API端点：http://127.0.0.1:8080/v1
```

---

## ⚙️ 启动命令速查表

| 操作 | Windows命令 |  
|------|------------|
| **首次安装** | `bootstrap.bat` |  
| **Q8量化版** | `bootstrap_q8.bat` (≥12GB显存) |  
| **启动服务** | `.\start_8080_toolhub_stack.cmd start` |  
| **停止服务** | `.\start_8080_toolhub_stack.cmd stop` |  

---

## 🤝 开源致谢

- **[Qwen3.5](https://github.com/QwenLM/Qwen3)** — 通义千问多模态大模型
- **[llama.cpp](https://github.com/ggml-org/llama.cpp)** — 高性能GGUF推理引擎

---

祝你调试愉快！🚀