欢迎使用 Magician 助手pro

基于 PySide6 深度构建的现代化 AI 桌面客户端。支持多模型接入、自定义联网搜索、本地安全沙箱与 WebDAV 云同步。

1. 简介与安装

软件提供两种运行方式：直接下载打包好的 Windows 可执行文件，或者通过源码运行。

方式一：直接下载 (推荐)

• 点击上方的 ⬇ 下载最新版 (Windows) 即可下载 v1.0.2 压缩包。
• 下载完成后，解压压缩包，双击 MagicianAI.exe 即可直接运行，无需配置 Python 环境。
• 注意：由于使用了 PyInstaller 打包，部分杀毒软件（如 360）可能会误报，请添加信任。

方式二：源码运行

如果您熟悉 Python 环境，可以克隆仓库并自行运行。需要 Python 3.10+ 版本。

git clone https://gitee.com/magicianswand/Magicianpro.git
cd Magicianpro
pip install PySide6 cryptography
python run.py

2. 配置 API Key

软件首次启动时处于无模型状态，需要配置您的大模型 API Key 才能开始对话。

1. 点击软件左下角的 ⚙ 设置 按钮。
2. 在“API 配置”中选择您的服务商（如 DeepSeek、OpenAI、通义千问等）。
3. 填入您申请的 API Key。（如果您使用 Ollama 本地模型，API Key 可以随意填写，只要地址正确即可）。
4. 点击 测试连接，提示成功后点击保存。
5. 回到主界面，输入内容发送即可。

如果你还没有 API Key，可以去 DeepSeek 官网申请（platform.deepseek.com）。

3. 自定义联网搜索

由于免费搜索接口（如 DuckDuckGo）极易被反爬虫拦截，v1.0.2 版本重构了网络搜索模块，完全交由用户自定义。

• 在设置页面找到 联网搜索配置。
• 搜索服务商选择 Tavily，填入您注册获取的 API Key。
• Tavily 专为 AI 设计，每月提供 1000 次免费搜索额度。您可以前往 tavily.com 注册。
• 在聊天输入框下方，勾选 🌐 联网 开关。
• 此时向 AI 询问实时信息（如“今天有什么科技新闻”），AI 会自动调用 Function Calling 获取最新资讯。

4. AI 沙箱与安全

MagicianAI 允许 AI 执行有限的本地操作。为了您的数据安全，我们设计了严格的三级权限：

• 安全类（自动执行）：列出沙箱目录、读取文本文件、获取系统信息等。
• 敏感类（弹窗确认）：写入文件、删除文件（移入回收站）、读取/写入剪贴板。
• 危险类（需手动开启）：执行任意 Shell 命令。默认关闭，需在设置中输入 I UNDERSTAND 才能开启。

所有的文件操作均被强制限制在 ai_sandbox/ 目录中，无法越权访问系统文件，且所有操作均有日志记录（ai_sandbox/logs/operations.log）。

5. 插件开发指南

如果你懂一点 Python，可以通过编写插件来扩展自定义命令。

在软件根目录的 ai_plugins/ 文件夹下新建一个 .py 文件（比如 my_plugin.py），编写如下代码：

# ai_plugins/hello.py
def register(main_window):
    def hello():
        from PySide6.QtWidgets import QMessageBox
        QMessageBox.information(main_window, "插件", "Hello!")
    main_window.register_plugin_command("/hello", "示例命令", hello)

保存并重启软件。在输入框输入 /hello 并回车，即可看到你的自定义命令生效。

6. 报错排查

在使用过程中，你可能会遇到一些常见报错。以下是排查指南：

❌ 提示“ModuleNotFoundError: No module named 'PySide6'”

原因： 你没有安装依赖，或者选错了 Python 环境（比如用到了系统默认环境而不是虚拟环境）。

解决： 确保在项目目录下，终端提示符带有 (.venv) 时，运行：
pip install PySide6 cryptography

❌ 软件打开后白屏 / 文字不显示

原因： 显卡驱动渲染冲突，或者旧版本的缓存卡死。

解决： 尝试更新显卡驱动。如果是开发者，请检查 widgets.py 中是否不小心启用了冲突的动画特效。

❌ 提示“HTTP 401 Unauthorized” 或 “无效的 API Key”

原因： 设置里的 API Key 填错了，或者该 Key 已经欠费失效。

解决： 打开设置，点击“测试连接”。如果失败，请去对应的服务商平台（如 DeepSeek）检查余额和 Key 是否正确。

❌ 联网搜索失败，提示“请勿频繁调用”

原因： 使用免费接口（如 DuckDuckGo）时触发了对方的反爬虫限制。

解决： 请在设置中配置 Tavily API Key，Tavily 专为 AI 设计，不会有这种限制。

7. 常见问题汇总

Q: 我的聊天记录和 API Key 会泄露吗？

A: 绝对不会。MagicianAI 是一个纯本地客户端，所有的数据（包括聊天记录、配置、API Key）都以 JSON 文件形式保存在你的电脑上。唯一的网络请求是直接发送给你的大模型服务商（如 DeepSeek）。

Q: 为什么我的软件里没有“文件搜索”或“操作电脑”的功能？

A: 请点击左下角设置，找到“AI 沙箱控制”，勾选“启用 AI 沙箱控制”。开启后，AI 才能获得读写本地文件、执行安全命令的权限。

Q: 如何修改打字机音效？

A: 在设置 -> 系统集成中，勾选或取消“打字机音效（Windows）”。该音效是通过调用 Windows 系统底层的蜂鸣器实现的。

Q: 支持本地离线运行吗？

A: 支持。如果你使用 Ollama 并下载了本地模型（如 Qwen、Llama3），在设置中选择“Ollama 本地”，API 地址填 http://localhost:11434/v1，即可完全断网离线聊天。

Q: 为什么我打开官网或下载很慢？

A: 官网托管在 Cloudflare 上，部分地区由于运营商 DNS 限制可能访问缓慢。如果下载失败，请直接前往 Gitee Releases 页面下载。

Q: 如何联系官方或反馈问题？

A: 您可以通过发送邮件至 official@magicianswand.cn 联系开发者，或者直接在 Gitee 仓库提交 Issue。