企业官网建设流程全解析

• 后端
• 前端
• 协同办公
• 即时通讯
• 企业应用

DooTask 在安装 ai 插件后，会在页面侧边常驻一个 AI 助手悬浮按钮（浮球），提供一键唤起对话浮窗的快捷入口。本文以 AI 助手悬浮按钮设置指南 为核心，完整介绍该开关的入口路径、操作步骤、影响范围，并结合仓库前端源码（设置页、浮球组件、IndexedDB 偏好存储）讲解其底层实现，帮助你按需关闭浮球、恢复显示，并理解"关闭浮球不等于禁用 AI"的边界。

功能概述：一个按设备生效的浮球开关

AI 助手悬浮按钮是 DooTask AI 助手（ai 插件）在桌面端与移动端页面上渲染的圆形浮动入口，点击即可唤起全局 AI 对话浮窗。它并非独立功能模块，而是 AI 助手主组件（AIAssistant）挂载到页面上的一个子组件。

自 DooTask v1.9.18 起，系统新增了悬浮按钮显示开关，用户可"按当前设备隐藏浮球，同时保留快捷键和其他 AI 入口"（见 CHANGELOG.md 中 v1.9.18 Features 说明）。这意味着：

• 该开关只控制浮球是否显示，不卸载 ai 插件，也不禁用 AI 助手本身；
• 开关状态按账号 + 当前设备保存，不同设备互不影响；
• 关闭后，右上角「+ → AI 助手」、Cmd/Ctrl + I快捷键、项目/任务/汇报等页面内的 AI 功能仍然可用。

设置入口：在哪里找到「AI 助手设置」

两个前提条件：

1. 系统已安装 ai 插件。从源码看，「AI 助手设置」菜单项是条件渲染的：在 设置页菜单构建逻辑 中，只有aiVisible为真时才menu.push({path: 'assistant', name: 'AI 助手设置'})；而aiVisible由 store/getters.js 中的 getter 计算，其核心条件是state.microAppsIds?.includes('ai')（即微应用列表中包含 ai 插件）。
2. 已登录账号。设置页仅对登录用户开放，未登录用户没有「个人设置」入口（参见 个人设置入口文档）。

作为防御性处理，设置页还有一道兜底：当路由已是manage-setting-assistant而aiVisible变为假时，会自动跳回「个人设置」子页（设置页路由守卫逻辑）。

操作步骤：打开 / 关闭 / 提交 / 重置

「AI 助手设置」页面只包含一个开关项，操作非常轻量：

1. 进入「AI 助手设置」；
2. 打开或关闭「显示悬浮按钮」开关；
3. 点击「提交」保存并应用；点击「重置」可恢复进入页面时的值；
4. 关闭后如需恢复，返回同一页面重新打开开关并提交即可。

对应实现位于 resources/assets/js/pages/manage/setting/assistant.vue：

• 页面挂载时通过loadFloatButtonVisible(this.userId)读入当前账号的偏好，并保存一份快照formData_bak；
• 「提交」调用saveFloatButtonVisible(this.userId, visible)持久化，随后通过事件总线广播aiAssistantFloatButtonVisibilityChanged，让浮球组件立即响应（无需刷新页面）；
• 「重置」仅将表单还原为进入页面时的快照值，不会写回存储，需再点「提交」才生效。

从 设置子页路由 可知，该子页对应路由为/manage/setting/assistant，是个人设置/manage/setting/personal的一个子页。

影响范围：按账号 + 按设备，仅影响浮球

原文档明确列出三点边界，理解它们可以避免误判：

1. 按当前账号保存在当前设备：偏好通过浏览器本地 IndexedDB（localforage 封装）存储，key 为aiAssistant.floatButtonVisible.${userId}（见 float-button-preference.js），因此同一账号换一台设备登录，开关状态互不共享。
2. 只隐藏页面侧边的浮球：不影响其他 AI 入口，包括：
   • 右上角「+」下拉菜单中的「AI 助手」——由 manage.vue 的菜单分发逻辑 触发openAIAssistantGlobal事件唤起；
   • 桌面快捷键Cmd/Ctrl + I；
   • 项目、任务、汇报等页面内的 AI 小按钮（如「项目名 AI 生成」「描述 AI 生成」「AI 任务分析」等，它们由aiVisible门控，与浮球开关无关）。
3. 清除客户端缓存后恢复默认开启：偏好以IDBBoolean读取且默认值为true（float-button-preference.js）。在设置页点击「清除缓存」会触发$A.IDBClear()类清理（见 设置页清除缓存逻辑），清除 IndexedDB 后，开关自然回落为默认开启状态。

源码级原理：浮球如何渲染、如何响应开关

1. 挂载与卸载

浮球不是静态写死在页面模板里，而是由 AI 助手主组件动态挂载：AIAssistant组件mounted时调用mountFloatButton()，通过Vue.extend(FloatButton)创建实例并$mount()后appendChild到document.body；组件销毁时调用unmountFloatButton()移除（见 resources/assets/js/components/AIAssistant/index.vue#L475-L495）。

2. 可见性判定链

浮球是否渲染，由 float-button.vue 中的 visible 计算属性 综合决定，多个条件同时满足才显示：

• aiVisible（全局 AI 可见性，依赖 ai 插件已安装）；
• userId > 0（已登录）；
• positionLoaded与visibilityLoaded（本地偏好异步加载完成）；
• floatButtonVisible（即「显示悬浮按钮」开关的当前值）；
• 不在登录页路由，且父级未弹出模态框。

其中floatButtonVisible在组件mounted后通过watch userId触发loadVisibility异步读取（float-button.vue#L177-L194），并监听aiAssistantFloatButtonVisibilityChanged事件实时更新（onVisibilityChanged）。这就是"点提交后浮球立刻消失/出现"的机制来源。

3. 偏好存储细节

float-button-preference.js是开关的唯一读写入口：

• 读：loadFloatButtonVisible(userId)→$A.IDBBoolean(cacheKey(userId), true)，默认开启；
• 写：saveFloatButtonVisible(userId, visible)→$A.IDBSet(cacheKey(userId), visible)；
• 未登录（userId <= 0）时读写直接短路返回，不做任何存储。

$A.IDBBoolean/$A.IDBSet是 resources/assets/js/functions/common.js#L1739-L1742 中基于 localforage 的封装：读取时校验值类型为布尔，否则返回默认值；写入时调用localforage.setItem。

4. 浮球本身的交互行为（非开关但值得了解）

即使不关闭开关，浮球也具备自动收边、可拖动等细节（float-button.vue）：

• 默认位置：桌面端默认距右 24px、距下 100px，移动端竖屏默认贴边并居中偏下；
• 位置持久化：拖拽后的坐标以aiAssistant.floatButtonPosition存入 IndexedDB，窗口 resize 时会做边界校验（最小边距 12px）；
• 自动收起：靠近屏幕边缘时，桌面端约 1 秒、移动端约 5 秒后自动收成 12px 宽的竖条，鼠标悬停或触摸可重新展开；
• 点击判定：鼠标按下到松开移动距离小于 5px 且时长小于 200ms 视为点击，点击即唤起 AI 助手浮窗。

常见问题排查

相关资源

• AI 助手的全部入口（浮球、右上角菜单、字段级 AI 按钮、快捷键）：menu-navigation/ai-assistant.md
• 个人设置入口与子页清单：user-settings/entry.md
• 开关设置页实现：resources/assets/js/pages/manage/setting/assistant.vue
• 偏好读写封装：resources/assets/js/components/AIAssistant/float-button-preference.js
• 浮球组件实现（可见性、拖拽、自动收起）：resources/assets/js/components/AIAssistant/float-button.vue
• 功能上线记录：v1.9.18 CHANGELOG.md

• 后端
• 前端
• 协同办公
• 即时通讯
• 企业应用