acecode-desktop-usage

name	acecode-desktop-usage
description	说明 ACECode Desktop 原生桌面应用的用法，包括工作区、任务、会话、输入框、权限、可选 Git worktree、搜索、文件与差异面板、设置、技能、MCP、循环任务、通知、更新和故障排查。当用户询问 Windows、macOS 或 Linux 图形界面的操作方法时使用。不要用终端 TUI 的命令代替 Desktop 界面操作。

ACECode Desktop 使用指南

说明 ACECode 原生桌面应用的操作方法。以当前 Desktop 界面中实际可见的控件和行为为准， 不要照搬终端 TUI 的命令或快捷键，因为两个界面的功能范围并不完全相同。

按当前界面回答

• 将 acecode-desktop.exe、acecode-desktop 和 ACECode.app 视为由原生外壳、 React 界面和托管 daemon 组成的 ACECode Desktop。
• 先给出最短的界面操作步骤，再补充相关选项。
• 明确区分工作区、任务/会话、Git worktree 和循环任务。
• 不要声称新建任务会自动创建目录或 Git worktree。
• 不要在 Desktop 中推荐仅 TUI 支持的 /model、/mode、/resume、 /memory 或 /theme。应改用模型选择器、权限选择器、侧边栏、搜索或设置页。
• 如果可以读取当前仓库，并且问题涉及容易变化的细节，应检查：
  • web/src/：界面控件和快捷键
  • web/src/lib/settingsNavigation.js：设置页分类
  • web/src/lib/permissionMode.js：权限选项
  • src/desktop/：原生窗口、托盘、更新和 daemon 行为

认识主要对象

• 工作区：已经添加到 ACECode 的本地代码目录。
• 任务：一次对话或会话，可以关联工作区，也可以不使用工作区。
• Worktree：为单个任务选择性创建的隔离 Git 检出目录，不等同于工作区。
• 循环任务：保存后按一次性或周期计划执行的提示词，可以选择工作区和 worktree。

ACECode Desktop 由一个托管 daemon 服务应用内的多个工作区，而不是为每个工作区分别启动 daemon。会话仍会保留自己的工作区上下文。

新建任务

在首页执行：

1. 点击 新建任务。
2. 选择现有工作区，或选择 不使用工作区。
3. 在输入框底部选择模型和权限。
4. 输入要求并按 Enter 发送。

需要添加已有代码目录时，使用 打开现有目录。只有确实需要创建空项目目录时才使用 新建项目。选择 不使用工作区 新建任务不会创建任何目录。

首次使用时，可跟随引导查看侧边栏、工作区选择、输入框、模型与权限控件以及设置页。

选择性使用 Git Worktree

Worktree 默认不启用，必须显式勾选：

1. 选择一个 Git 工作区。
2. 在新任务输入区勾选 worktree。
3. 如果界面提供分支选项，选择或输入所需分支。
4. 发送第一条普通消息。

ACECode 在任务真正开始时创建 worktree，而不是在勾选复选框时立即创建。未勾选时， 任务直接在所选工作区中运行。

不要描述成 Desktop 会自动或优先创建 worktree。创建失败时，先确认所选工作区是有效的 Git 仓库，再查看任务中显示的错误。

输入和发送消息

• Enter：发送消息。
• Shift+Enter：插入换行。
• 输入框为空且尚未编辑时，使用 Up 和 Down 浏览历史输入。
• 输入 / 打开受支持的命令菜单。选中命令只会插入内容，不会自动发送。
• 输入 @ 引用当前工作区中的文件或目录。
• @src/ 之类的目录引用只是路径提示，不会递归上传目录内的全部文件。
• 在原生 Desktop 中使用添加按钮附加图片、文件或目录。
• 将文件拖入输入框也可以添加附件。
• 当前任务需要网页信息时，可加入已连接浏览器的上下文。

如果用户实际使用的是浏览器中的 Web UI，而不是原生 Desktop，应说明浏览器版支持的附件 类型可能少于原生应用。

控制正在执行的任务

Desktop 支持以下三条特殊消息命令：

• /turn <引导内容>：在下一个模型边界调整当前主任务的方向。
• /btw <问题>：发起一次与主任务分离的旁问。
• /side <问题>：/btw 的别名。

需要改变当前工作方向时使用 /turn。只是临时问一个不应影响、取消或替换主任务的问题时， 使用 /btw 或 /side。

任务执行期间发送普通消息时，该消息可能进入队列。不要把普通排队消息描述成与 /turn 完全等价。

选择权限

Desktop 输入框提供三种权限：

• 默认权限：敏感写入或命令执行前请求确认。
• 自动接收编辑：自动允许文件编辑，但命令执行仍需确认。
• 完全访问权限：自动允许常规工具操作。

需要进入计划模式时使用 /plan。不要声称 Desktop 权限选择器中存在第四个“计划模式”选项。

推荐 完全访问权限 前先说明风险。即使使用完全访问权限，也不能忽略任务指定的工作区， 更不能泄露密钥或其他敏感信息。

使用 Desktop 支持的命令

Desktop 内置命令菜单只提供一组聚焦的命令：

• /init：创建或刷新项目说明。
• /compact：压缩对话上下文。
• /goal：管理长期目标。
• /plan：进入计划模式。
• /lsp：查看语言服务器集成。
• /rc 或 /remote-control：管理远程控制。
• /turn、/btw 和 /side：控制当前任务或发起旁问。

已安装的技能和兼容命令文件可以向菜单增加条目。Desktop 不支持全部 TUI 斜杠命令， 遇到以下需求时应使用界面：

• 使用输入框的模型选择器或设置页切换模型。
• 使用输入框的权限选择器切换权限。
• 从侧边栏或全局搜索恢复、切换会话。
• 在设置页管理技能和 MCP 服务器。
• 使用 Ctrl/Cmd+F 在当前对话中查找文字。

管理任务和工作区

使用左侧边栏：

• 切换工作区和会话；
• 新建任务；
• 置顶或取消置顶会话；
• 重命名会话；
• 归档会话；
• 重新打开历史任务。

已归档会话位于 设置 > 已归档会话。

会话右键菜单包含置顶/取消置顶、重命名、复制标题、复制 ID 和归档。消息右键菜单可以复制 内容，或使用 从这里分叉 创建新任务。

搜索和查找

• Ctrl/Cmd+K：打开跨任务、项目和会话的全局搜索。
• Ctrl/Cmd+F：在当前对话中查找文字。
• F3：跳到下一个匹配项。
• Shift+F3：跳到上一个匹配项。

需要查找其他任务或工作区时使用全局搜索。只需要定位当前对话中的文字时使用对话查找。

查看文件、改动和工具输出

使用右侧面板查看：

• 工作区文件树；
• 文件预览；
• 已修改文件和差异；
• 当前打开的标签页及任务产物。

文件和目录右键菜单可以复制路径或将其加入对话上下文。工具结果右键菜单可以复制当前可见 输出或完整输出。折叠内容中缺少所需诊断信息时，优先复制完整输出。

通过对话流中现有的状态信息和工具卡片跟踪进度。不要另行虚构一个重复的固定进度面板。

打开设置

从快捷菜单打开 设置。当前分类包括：

• 常规：应用行为和通知。
• 外观：主题和显示偏好。
• 配置、个性化：ACECode 行为和个性化说明。
• 使用情况：使用量信息。
• 技能：管理全局和工作区技能。
• MCP 服务器：管理 MCP 配置和状态。
• 连接器：管理已连接服务。
• 模型：配置提供商和模型。
• 工具：配置工具。
• 钩子：配置钩子。
• 已归档会话：查看已归档任务。
• 问题反馈、关于：反馈、版本和更新信息。

设置页可能随版本变化。如果安装版本中的标签与这里不同，应以实际界面为准。

管理技能

打开 设置 > 技能，查看全局和工作区技能、刷新技能发现，或打开技能目录。每个技能使用 独立目录，并包含一个 SKILL.md。

• 通用技能放入全局技能目录。
• 只适用于当前仓库的技能放入工作区技能目录。
• 新增或修改文件后刷新技能发现。
• 为技能编写准确的描述，使 ACECode 能在正确的请求中选中它。

内置 seed 技能只会在 ACECode 首次创建 ~/.acecode 用户目录时安装。应用升级不会覆盖 现有技能，也不会自动把后来新增的 seed 技能补装到已有用户目录。现有用户需要显式复制 或安装新技能。

管理 MCP 服务器和连接器

使用 设置 > MCP 服务器 添加、编辑、启用、停用或查看 MCP 服务器。使用 设置 > 连接器 管理支持的账号型集成。

修改集成后：

1. 保存配置。
2. 使用界面提供的刷新或重新连接操作。
3. 如果该集成不支持动态重载，重启应用或托管 daemon。

不要因为某个连接器或 MCP 服务器出现在文档中，就假设它已经安装或连接成功。

创建和管理循环任务

打开循环任务页面，或从快捷菜单选择 循环任务。

按需配置：

• 模板或自定义提示词；
• 可选工作区；
• 默认不勾选的可选 worktree；
• 模型；
• 循环任务支持的权限；
• 单次、间隔或定时触发方式；
• 界面提供的有效时间范围。

Desktop 循环任务的权限选择少于普通任务，通常只提供默认审批或完全访问。保存后可以启用、 停用循环，并查看运行记录。除非调度设置明确要求立即运行，否则不要声称保存循环后会马上执行。

使用通知、托盘和更新

Desktop 可以在任务完成、请求权限或提出问题时发送系统通知。为避免重复提醒，当前获得焦点且 可见的任务可以不发送通知；在 设置 > 常规 中调整相关选项。

启用“关闭到托盘”后，关闭窗口可能只是把 ACECode 隐藏到系统托盘。需要彻底退出时，使用 托盘菜单、快捷菜单中的 退出，或操作系统提供的明确退出操作。

使用 检查更新 或 关于 检查新版本。更新流程可以下载、应用并重启应用。应用更新前， 先保存或提交工作区中的重要改动。

使用诊断快捷键

• Ctrl + 反引号键：打开或收起控制台。
• F11：在当前 Desktop 构建中打开原生开发者工具。

这些功能只用于排查问题。让用户复制相关错误即可，不要要求其导出令牌、配置密钥或无关的 会话内容。

遵守当前 Desktop 边界

• Desktop daemon 会话目前没有与 TUI 完全一致的持久记忆支持，不要承诺 /memory 可以在 Desktop 中使用。
• Desktop 和 TUI 的命令注册表本来就不同。
• 不使用工作区的任务是有效的，但无法访问工作区文件。
• @目录/ 只提供目录路径上下文，不代表递归上传。
• 一个托管 daemon 服务应用中的多个工作区，不要按“每个工作区一个 daemon”排查。
• Worktree 和循环任务都是显式选择，在出现复选框的地方默认关闭。

排查常见问题

• 找不到工作区时，使用 打开现有目录 并选择实际仓库根目录。
• 任务看不到文件时，确认任务关联了正确工作区，并检查其 worktree 是否仍然存在。
• 找不到模型时，检查 设置 > 模型 和提供商状态。
• 工具长时间等待时，查看对话中是否有待处理的权限卡片或问题卡片。
• 技能或 MCP 服务器缺失时，先在对应设置页刷新，必要时重启应用。
• 关闭窗口后应用仍在运行时，检查系统托盘。
• 如果实际界面与本技能不同，以安装版本显示的界面为准，并根据当前源码更新本技能。