第 1 章 · 产品介绍

什么是 DeskWand？

DeskWand 是一款开源的 AI 桌面 Agent。不同于普通的聊天机器人，它不仅会回答问题，还会自主规划、调用工具、持续推进，直到完成你设定的目标。它运行在你的本地机器上，你可以自由选择使用的 AI 模型，数据留在本地，一切由你掌控。

核心能力

• 多模型支持 — 支持 OpenAI、Anthropic、Gemini、Ollama、DeepSeek、OpenRouter 以及任何 OpenAI/Anthropic/Gemini 兼容端点。使用你自己的 API Key。
• 工具调用 — Agent 自主读写文件、执行 Shell 命令、搜索网页、抓取内容。
• 技能系统 — 安装和启用技能，注入专业知识和工具指令（PDF 处理、视频编辑、飞书操作等）。
• MCP 连接器 — 通过 Model Context Protocol 连接外部工具和数据源（浏览器、数据库、第三方 API）。
• 定时自动化 — 设置单次或周期性任务，到点自动执行。
• 长期记忆 — Agent 会记住你的偏好和项目上下文，跨会话延续。

典型应用场景

• 代码开发 — 阅读代码库、编写和编辑文件、运行测试、修复 Bug
• 数据分析 — 处理表格数据、生成图表和报告
• 文档撰写 — 起草、编辑和格式化文档
• 网页调研 — 搜索互联网、提取页面内容、汇总调研结果
• 日常自动化 — 设置周期性任务，如日报生成、邮件摘要、数据同步

与普通聊天的区别

普通聊天机器人回答完问题就等你下一条消息。DeskWand 主动推进：它将你的目标拆解成步骤，为每个步骤选择合适的工具（读文件、跑命令、搜网页），执行后评估结果，然后继续。这个循环会一直运转，直到目标达成或你手动暂停。

第 2 章 · 安装与快速开始

系统要求

下载与安装

访问 deskwand.com/zh/#download 下载对应平台的最新版本：

• macOS — 打开 .dmg 文件，将 DeskWand 拖入 Applications 文件夹。
• Windows — 运行 .exe 安装程序，按向导完成安装。
• Linux — 使用 .AppImage、.deb 或 .rpm 包。

首次启动

1. 打开 DeskWand。首次运行时自动显示 API 配置 界面。
2. 选择你的 AI 服务商（如 OpenAI、Anthropic、Gemini），输入 API Key。
3. 从列表中选择模型，或手动输入模型 ID。
4. 点击 保存设置。
5. 准备就绪 — 输入消息，按回车发送。

界面概览

主窗口分为四个关键区域：

第 3 章 · API 配置

支持的服务商

DeskWand 兼容任何遵循 OpenAI、Anthropic 或 Gemini 协议的 API。具体支持以下服务商：

你也可以连接任何暴露 OpenAI 或 Anthropic 兼容 API 的自定义端点。

配置流程

1. 打开 设置 → API。
2. 从列表中选择服务商，或选择「其他供应商」配置自定义端点。
3. 输入你的 API Key。
4. （可选）自定义 Base URL，用于连接代理或自托管端点。
5. 选择或手动输入 模型 ID。
6. 点击 测试连接 验证配置是否正确。
7. 点击 保存设置。

配置方案管理

你可以创建多套配置方案 — 例如工作用 OpenAI，个人项目用本地 Ollama 模型。在 API 设置页面顶部的下拉菜单中快速切换。每个方案独立存储服务商、密钥、Base URL 和模型列表。

视觉模型

如果你的主模型不支持图片理解（多模态），可以单独配置一个视觉模型。当你粘贴或附加图片时，Agent 会先用视觉模型识别图片内容，再将描述传递给主模型进行推理。

在 设置 → API → 视觉模型 中配置。

搜索配置

在 设置 → API → 搜索 中，你可以为网页搜索和内容抓取配置专用模型。这与主模型分离，允许你为搜索类操作使用更快或更便宜的模型，而保留更强大的模型用于推理。

OAuth 订阅接入

无需手动输入 API Key，可直接连接你已有的订阅：

• ChatGPT Plus — 用 OpenAI 账号登录
• Claude Max — 用 Anthropic 账号登录（需 Max 订阅 + 额外用量额度，Pro 不支持）
• GitHub Copilot — 用 GitHub 账号登录
• OpenRouter — 用 OpenRouter 账号登录

前往 设置 → API，滚动到「订阅账号接入」区域，点击对应服务商的 连接 按钮。

连接诊断

如果遇到连接问题，使用内置诊断工具：设置 → API → 诊断连接。它会逐步检查：

1. DNS 解析 — 能否解析 API 域名？
2. TCP 连接 — 能否到达服务器？
3. TLS 握手 — 连接是否安全？
4. API 认证 — Key 是否有效？
5. 模型验证 — 模型能否正常响应？

每个步骤会报告通过/失败，并提供可操作的修复建议。

第 4 章 · 项目与会话

项目

项目是一个绑定到磁盘目录的命名工作区。会话（对话）归属于某个项目，所有文件操作和工具执行都限定在该目录范围内。这让你可以清晰地区分不同工作流 — 例如一个「官网开发」项目和一个「数据分析」项目。

在侧边栏创建新项目：点击项目区域的 + 按钮，输入名称，DeskWand 会自动创建对应目录。

会话管理

• 新建会话 — 点击侧边栏的 新建 按钮开始全新对话。
• 切换会话 — 点击侧边栏中任意会话即可切换上下文。
• 搜索会话 — 使用侧边栏顶部的搜索栏按标题或项目名查找会话。

侧边栏组织

会话按项目分组，按时间排序：运行中、今天、昨天、最近 7 天、更早。项目可折叠/展开。活跃会话会显示运行状态标识。

归档与恢复

归档不再需要的会话以保持侧边栏整洁。右键（或长按）会话，选择 归档。在 设置 → 已归档 中查看和恢复已归档的会话。

上下文压缩

长时间对话可能超出模型的上下文窗口。此时 DeskWand 会自动压缩对话 — 将较早的消息总结压缩，释放空间。你也可以手动触发：输入 /compact 或从快捷菜单选择。

Goal 模式

Goal 模式让 Agent 围绕一个高层目标自主循环工作：

1. 设定目标 — 例如「调研并总结本周最热门的 5 篇 AI 论文」
2. Agent 规划 → 执行 → 评估 → 重复，直到目标达成。
3. 你可以随时暂停、继续或清除目标。
4. 状态栏显示进度：当前轮次、已用 Token、已用时间。

通过快捷菜单（/goal）或操作栏访问 Goal 模式。

第 5 章 · 聊天交互

发送消息

在底部输入框中输入指令，按 回车 发送。你还可以：

• 粘贴剪贴板中的图片 — Agent 会识别图片内容（需主模型或视觉模型支持图片）。
• 附加文件 — 拖拽文件或使用输入框中的附件按钮。
• 展开输入框 — 点击展开按钮或按 Shift+Enter 实现多行输入。

Slash 快捷命令

在输入框中按 / 唤出快捷命令菜单。菜单按类别列出可用命令和技能。使用方向键导航，回车 选择。分类包括：

• 命令 — 内置操作（compact、goal 等）
• 技能 — 已安装的技能，用于特定领域任务

流式输出与思考过程

Agent 工作时，回复会实时流式展示。Agent 还可能展示其思考过程 — 在采取行动前的推理步骤。思考过程以可折叠块的形式显示在每条回复上方，你可以展开查看或折叠隐藏。

工具调用卡片

Agent 使用工具时（读文件、跑命令、搜网页），聊天中会出现对应的卡片，显示：

• 工具名称和输入内容
• 输出或结果
• 执行耗时和 Token 用量

卡片按类型配色，紧凑展示 — 点击可展开查看完整细节。

产物面板

右侧面板（通过产物按钮切换）展示当前会话中创建或修改的所有文件。每项显示：

• 文件路径
• 变更摘要（± 新增/删除行数）
• 快捷操作：预览、在文件夹中定位、复制路径

消息操作

鼠标悬停在任意消息上，会显示操作按钮：复制 消息文本，或在文件管理器中定位消息引用的文件。

权限审批

某些工具执行前需要你的授权 — 特别是写入文件和执行 Shell 命令。当工具需要权限时：

• 弹出对话框，显示工具名称、输入内容和警告。
• 你可以选择允许（本次）、始终允许（本次会话内）或拒绝。
• 需要管理员权限的命令会提示输入系统密码（不会存储）。

第 6 章 · 工具系统

工具工作方式

Agent 会自动为每一步选择并使用最合适的工具 — 你不需要手动指定。只需描述你想做什么，Agent 会自行决定是读文件、跑命令、搜网页，还是组合使用多种工具。

文件工具

Shell 命令（Bash）

Agent 可以在你的工作目录中执行 Shell 命令。用于安装依赖、运行脚本、构建项目等操作。需要管理员权限的命令会提示输入密码。

网络工具

网络访问配置

在 设置 → 网络访问 中选择搜索供应商。可用选项：OpenAI、Brave、Exa、Tavily、Perplexity、Gemini、自动选择。每个供应商可使用独立的 API Key，也可以继承主 API 配置的密钥。

产物面板

产物面板（右侧栏）自动追踪会话中创建或修改的每个文件。这是查找 Agent 刚刚处理的文件的最快方式。每张产物卡片显示文件路径、变更摘要和快捷操作按钮。

第 7 章 · 技能系统

什么是技能？

技能（Skill） 是一个可复用的扩展包，为 Agent 注入特定领域的专业知识、指令和工具配置。技能使 Agent 在处理 PDF、视频编辑、财务分析、天气查询、飞书/Slack 等任务时更加专业高效。

内置技能

DeskWand 预装了一套内置技能，覆盖常用任务场景。你可以在 设置 → 技能 中单独启用或停用每个技能。内置技能无需安装，开箱即用。

技能市场

在技能云中浏览、安装和更新社区贡献的技能：

1. 从侧边栏或设置 → 技能中打开 技能云。
2. 按分类浏览或搜索特定技能。
3. 点击技能卡片查看详情（描述、版本、下载量）。
4. 点击 安装 将其添加到你的技能库。

已安装的技能出现在 我的技能 列表中，可启用/停用或删除。市场会在有新版本时显示更新标识。

技能云（需登录）

登录 DeskWand 账号可解锁云端功能：

• 同步 — 在多台设备间同步技能
• 分享 — 与团队分享技能
• 发布 — 将自己的技能发布到市场

自定义技能

你可以从本地文件夹导入技能：前往 设置 → 技能，点击 从文件夹安装。适用于测试自己编写的技能或使用同事直接分享的技能。

第 8 章 · MCP 连接器

什么是 MCP？

Model Context Protocol（MCP） 是一个开放标准，用于将 AI 模型连接到外部工具和数据源。MCP 连接器让你的 Agent 能够与浏览器、数据库、API 等服务交互 — 就像使用内置工具一样。

快速添加预设

DeskWand 内置了常用 MCP 服务器的预设配置（如 Chrome DevTools）。前往 设置 → MCP 连接器，点击预设即可一键添加。预设已预先配置好，只需启用即可。

自定义连接器

在 设置 → MCP 连接器 中点击 添加连接器 来配置自定义连接器。支持三种传输类型：

每个连接器可配置环境变量用于认证令牌（如 NOTION_TOKEN、DATABASE_URL）。

管理连接器

连接器添加并启用后，其工具即可在对话中被 Agent 调用。连接器卡片显示：

• 连接状态（已连接 / 连接中 / 失败）
• 可用工具数量
• 编辑和删除选项

第 9 章 · 定时任务

概述

定时任务让你可以设定指令在指定时间自动执行 — 就像一个为你 AI Agent 设置的闹钟。适用于日报生成、周期性数据检查、定期调研等场景。

日历视图

通过 设置 → 定时任务 访问定时任务管理。日历视图以日/周/月三种方式展示所有任务。点击空白区域创建新任务，点击已有任务进行编辑。

任务模式

配置任务

1. 选择模式（单次、每天、每周、间隔）。
2. 设置执行时间 — 点击添加时间点（格式：HH:MM）。
3. 输入指令 — 触发时 Agent 要执行的内容。
4. 可选指定工作目录（默认为当前项目目录）。
5. 切换 启用 开关激活任务。

监控与控制

• 查看每个任务的下次执行时间和最近执行状态。
• 点击 立即执行 触发任务以便测试。
• 暂停/恢复单个任务，无需删除。
• 运行中的任务会在侧边栏创建会话 — 你可以手动停止或查看进度。

第 10 章 · 记忆系统

记忆如何工作

DeskWand 会建立你的偏好、历史工作和项目上下文的长期记忆，让后续会话更加高效。记忆分为两种：

启用 / 停用

前往 设置 → 记忆 来开启或关闭记忆系统。关闭后，Agent 不会将历史记忆注入新会话，也不会从当前会话中学习新内容。已有的记忆数据会保留，重新启用后恢复生效。

搜索记忆

在 设置 → 记忆 中使用搜索栏按关键词查找历史记忆。可按范围筛选：当前工作区、全部记忆或仅核心记忆。点击任意结果查看完整摘要和原始出处摘录。

维护操作

在 设置 → 记忆 → 维护操作 中，你可以：

• 重建当前工作区 — 重新扫描历史会话以重建工作区记忆。
• 清空当前工作区 — 删除当前项目的所有记忆。
• 清空 Core Memory — 删除所有全局偏好和模式记忆。

第 11 章 · 设置与偏好

外观

在 设置 → 通用 中配置：

• 主题 — 浅色、深色或跟随系统。
• 调色板 — 从预设中选择：Graphite 石墨、Paper 纸页、Void 虚空、Ocean 深海、Forest 森林、Ember 余烬、Aurora 极光。
• 语言 — English 或 中文。

自动技能学习

开启后（默认），Agent 可以在对话中自动发现并学习新技能，并定期整理已有技能。如果你偏好手动管理技能，可以关闭此功能。注意：项目模式下不支持自动学习。

匿名使用统计

DeskWand 收集匿名使用统计数据以帮助改进产品。仅包含随机设备标识和应用版本信息 — 不包含任何个人数据。可在 设置 → 通用 → 匿名使用统计 中关闭。

版本更新

前往 设置 → 关于 查看当前版本并检查更新。DeskWand 支持自动更新检查和一键安装。有新版本时，状态栏会出现通知。

第 12 章 · 常见问题与排障

API 连接失败 — 我该检查什么？

1. API Key 是否正确且未过期？
2. Base URL 是否正确？（尤其在使用代理或自托管端点时。）
3. 运行 设置 → API → 诊断连接 进行逐步排查。
4. 检查网络 — 防火墙或 VPN 可能阻止 API 连接。

我的模型不在列表中 — 如何使用？

切换到 手动输入 模式，直接输入模型 ID。确保选择的协议（OpenAI / Anthropic / Gemini）与模型 API 匹配。

Agent 执行命令时反复报错

• 确认工作目录存在且可访问。
• 对于系统级命令（安装、构建），检查是否需要管理员权限。
• 查看聊天中的工具调用卡片，找到具体错误信息。

如何导出日志用于求助？

前往 设置 → 日志，点击 导出诊断包。这会生成一个 ZIP 文件，包含应用日志、脱敏后的运行环境信息，以及最近会话和错误的元数据摘要。将此文件发送给 DeskWand 团队可加快排障速度。

可以离线使用 DeskWand 吗？

可以 — 通过 Ollama 使用本地模型。安装 Ollama，拉取模型（ollama pull llama3），然后在 DeskWand 中配置 Ollama 端点。本地模型不需要互联网连接。

我的数据存储在哪里？

所有数据均为本地优先。你的 API Key、对话记录、设置和记忆都存储在本地机器上。除非你明确使用云端功能（技能云同步、OAuth 订阅）或启用遥测（匿名且最小化），否则不会发送到 DeskWand 服务器。

如何获取帮助或报告 Bug？

• GitHub — github.com/deskwand/agent — 提交 Issue 或发起 Discussion
• 官网 — deskwand.com
• X（Twitter） — @deskwanda