Qwen3.5-9B-ToolHub-Enhanced-Version/README.md

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 | 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模型）

# 方法一：标准启动脚本（双击运行）
bootstrap.bat

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

启动服务

.\start_8080_toolhub_stack.cmd start
# 浏览器访问 http://127.0.0.1:8080

停止：.\start_8080_toolhub_stack.cmd stop

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

---

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

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

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

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

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

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

---

其他部署路线

• 🧊 WSL 模式 — 已有WSL环境的用户

  ./install.sh + ./start_8080_toolhub_stack.sh start
  

  底层复用Windows主链路，适合双系统开发场景。

---

📖 文档导航

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

---

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

当前时间：🕒 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 — 通义千问多模态大模型
• llama.cpp — 高性能GGUF推理引擎

---

祝你调试愉快！🚀