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: 标准版 (推荐)

# 双击运行
bootstrap.bat

方法 B: Q8 量化版 (显存 ≥ 12GB，占用约 10.2GB)

# 双击运行
bootstrap_q8.bat

启动服务

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

# 停止服务
.\start_8080_toolhub_stack.cmd stop

访问界面

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

---

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

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

# ==========================================
# 🚀 核心运行模式
# ==========================================
# 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 文件或联系老王团队。