-
Notifications
You must be signed in to change notification settings - Fork 6
docs: 扩充 FAQ 性能/委派/自动化章节,修复 More 索引 #38
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
26e2d36
6b0ae73
36f0b29
c6a9655
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,22 +1,81 @@ | ||
| --- | ||
| title: 性能问题 | ||
| description: 解决 DesireCore 运行时的内存占用、响应速度和性能优化问题 | ||
| keywords: [性能, 内存占用, 响应速度, 优化, GPU, 卡顿] | ||
| keywords: [性能, 内存占用, 响应速度, 优化, GPU, 卡顿, 磁盘, 风扇] | ||
| --- | ||
|
|
||
| # 性能问题 | ||
|
|
||
| ## 应用占用过多内存? | ||
|
|
||
| DesireCore 桌面客户端会占用一定的基础内存。如果内存占用异常偏高: | ||
| DesireCore 桌面客户端基于 Electron 构建,会占用一定的基础内存(通常 200–400 MB)。如果内存占用异常偏高: | ||
|
|
||
| 1. **检查版本** --- 确保你使用的是最新版本,开发团队会持续优化性能 | ||
| 2. **检查智能体数量** --- 同时运行超过 300 个智能体会显著增加内存开销 | ||
| 3. **重启应用** --- 长时间运行后内存可能逐渐增长,定期重启可以释放累积的内存 | ||
| 3. **关闭不用的对话** --- 每个活跃对话都会占用渲染内存,关闭不需要的对话标签页 | ||
| 4. **重启应用** --- 长时间运行后内存可能逐渐增长,定期重启可以释放累积的内存 | ||
|
|
||
| ## AI 回复的响应速度慢? | ||
|
|
||
| 响应速度主要取决于 AI 模型 API 的性能,与 DesireCore 客户端本身关系较小。优化建议: | ||
|
|
||
| 1. **更换 API 端点** --- 更换为更快的 AI 模型提供商 | ||
| 2. **检查网络质量** --- 使用稳定的网络连接,减少丢包和延迟 | ||
| 3. **检查模型负载** --- 高峰时段供应商 API 可能排队,稍后重试 | ||
|
|
||
| ## 磁盘占用过大? | ||
|
|
||
| DesireCore 的数据目录(`~/.desirecore/`)会随使用时间增长。主要占用来源: | ||
|
|
||
| | 来源 | 典型大小 | 清理方式 | | ||
| |------|---------|---------| | ||
| | 应用缓存 | 数百 MB | 删除系统应用缓存目录(见下方路径) | | ||
| | 市场仓库缓存 | 50–200 MB | 可安全删除,下次启动自动重建 | | ||
| | 会话记录 | 视使用量 | 在设置中清理历史会话 | | ||
| | 智能体数据 | 视智能体数 | 删除不需要的智能体 | | ||
|
|
||
| 缓存目录路径: | ||
| - macOS: `~/Library/Application Support/desirecore/Cache` | ||
| - Windows: `%APPDATA%/desirecore/Cache` | ||
| - Linux: `~/.config/desirecore/Cache` | ||
|
|
||
| :::tip | ||
| 删除缓存前请先关闭 DesireCore。缓存会在下次启动时自动重建,不影响你的数据。 | ||
| ::: | ||
|
|
||
| ## GPU 占用高或风扇狂转? | ||
|
|
||
| DesireCore 使用 GPU 加速渲染界面(玻璃材质、动画等)。如果 GPU 占用异常: | ||
|
|
||
| 1. **检查显卡驱动** --- 过旧的驱动可能导致 GPU 效率低下,更新到最新版本 | ||
| 2. **关闭其他 GPU 密集型应用** --- 游戏、视频编辑等会争抢 GPU 资源 | ||
| 3. **降低动画效果** --- 在系统设置中启用「减弱动态效果」可减少 GPU 负载 | ||
| 4. **禁用硬件加速** --- 以 `--disable-gpu` 参数启动 DesireCore 可完全关闭 GPU 加速(界面流畅度会下降) | ||
|
|
||
| ## 长时间运行后变慢? | ||
|
|
||
| Electron 应用在长时间运行后可能出现性能下降。建议: | ||
|
|
||
| 1. **定期重启** --- 每周或感觉明显变慢时重启应用 | ||
| 2. **清理对话历史** --- 过多的历史消息会增加渲染负担 | ||
| 3. **检查后台任务** --- 大量定时调度或心跳任务同时运行会占用 Agent 服务资源 | ||
|
|
||
| ## 大量智能体同时在线有什么影响? | ||
|
|
||
| 每个在线智能体都会占用 Agent 服务的内存和调度资源: | ||
|
|
||
| - **1–50 个智能体**:正常使用,无明显影响 | ||
| - **50–200 个智能体**:内存占用增加,建议关闭不常用的智能体 | ||
| - **200+ 个智能体**:可能影响响应速度,建议精简智能体列表 | ||
|
|
||
| :::tip | ||
| 删除不再需要的智能体可以释放资源。智能体的记忆和配置会一并清除,请确认不需要后再操作。 | ||
| ::: | ||
|
|
||
| ## 如何查看资源占用? | ||
|
|
||
| - **macOS**:打开「活动监视器」(Activity Monitor),搜索 `DesireCore` 查看 CPU、内存、GPU 占用 | ||
| - **Windows**:打开「任务管理器」(Ctrl+Shift+Esc),在「进程」标签页找到 DesireCore | ||
| - **Linux**:使用 `htop` 或系统监视器,搜索 `desirecore` 进程 | ||
|
|
||
| DesireCore 包含多个子进程(主进程、渲染进程、Agent 服务),总资源占用是所有子进程之和。 |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| --- | ||
| title: 委派与协作问题 | ||
| description: 解决 DesireCore 智能体委派、团队协作和任务分派中的常见问题 | ||
| keywords: [委派, 协作, 团队, 任务, 回执, delegate, 智能体通信] | ||
| --- | ||
|
|
||
| # 委派与协作问题 | ||
|
|
||
| ## 委派和直接对话有什么区别? | ||
|
|
||
| | 对比项 | 直接对话 | 委派 | | ||
| |--------|---------|------| | ||
| | 交互方式 | 你与智能体实时对话 | 一个智能体将任务交给另一个 | | ||
| | 上下文 | 你手动提供背景 | 委派方自动传递任务描述和上下文 | | ||
| | 适用场景 | 简单问答、即时反馈 | 复杂任务、需要专业能力、多步工作 | | ||
| | 结果获取 | 实时流式输出 | 完成后返回结果(同步)或异步汇报 | | ||
|
|
||
| 简单来说:直接对话是"你和智能体聊天",委派是"让一个智能体去找另一个智能体帮忙"。 | ||
|
|
||
| ## 委派后如何查看进展? | ||
|
|
||
| 1. **同步委派**:委派方会等待结果返回,你可以在对话中看到"正在委派给 XXX..."的提示,完成后结果会直接出现在对话中 | ||
| 2. **异步委派**:任务在后台执行,完成后会收到通知。你可以通过回执(Receipt)查看完整执行过程 | ||
| 3. **InspectRuns**:委派方可以使用 InspectRuns 工具查看子任务的执行历史和摘要 | ||
|
|
||
| ## 如何取消正在执行的委派任务? | ||
|
|
||
| - **同步委派**:点击对话中的「停止」按钮,会同时中断当前智能体和其委派的子任务 | ||
| - **异步委派**:委派方可以使用 Delegate 工具的 `terminate` 动作,通过 run_id 或 correlation_id 中止后台子任务 | ||
| - **注意**:已经完成的步骤不会被撤销,取消只影响后续执行 | ||
|
|
||
| ## 团队成员之间如何通信? | ||
|
|
||
| DesireCore 团队中的智能体可以通过以下方式通信: | ||
|
|
||
| | 方式 | 工具 | 适用场景 | | ||
| |------|------|---------| | ||
| | 委派任务 | Delegate | 需要对方执行完整工作流 | | ||
| | 发送消息 | SendMessage | 轻量通知、提问、汇报 | | ||
| | 共享文件 | 工作目录 | 通过共享目录交换文件产物 | | ||
|
|
||
| 组长(supervisor)负责协调团队成员的任务分配和进度跟踪。 | ||
|
|
||
| ## 回执(Receipt)在哪里查看? | ||
|
|
||
| 回执记录了智能体每次执行的完整证据链。查看方式: | ||
|
|
||
| 1. 在对话中,智能体完成操作后会自动生成回执 | ||
| 2. 回执包含:执行的操作列表、工具调用记录、最终结果 | ||
| 3. 异步委派完成后,汇报消息中会附带 runId,可用于追溯完整执行过程 | ||
|
|
||
| ## 委派失败或超时怎么办? | ||
|
|
||
| 常见原因和解决方法: | ||
|
|
||
| 1. **目标智能体不在线** --- 检查目标智能体是否处于 idle 状态 | ||
| 2. **任务描述不清晰** --- 提供更具体的任务描述和必要上下文 | ||
| 3. **超时** --- 复杂任务可能需要较长时间,异步委派不受对话超时限制 | ||
| 4. **权限不足** --- 目标智能体可能缺少执行任务所需的工具或技能 | ||
|
|
||
| :::tip | ||
| 如果委派频繁失败,尝试将复杂任务拆分为多个小任务分别委派,成功率更高。 | ||
| ::: | ||
|
|
||
| ## 如何创建团队进行多智能体协作? | ||
|
|
||
| 1. 确保所有需要的智能体已经创建(使用 ManageAgent) | ||
| 2. 使用 ManageTeam 创建团队,指定组长和成员 | ||
| 3. 组长通过 Delegate 向成员分派任务 | ||
| 4. 成员完成后向组长汇报结果 | ||
|
|
||
| :::warning | ||
| ManageTeam 不会自动创建缺失的成员。组队前必须先确认所有智能体已存在。 | ||
| ::: | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| --- | ||
| title: 自动化问题 | ||
| description: 解决 DesireCore 定时调度、心跳监控和自动化任务中的常见问题 | ||
| keywords: [调度, 心跳, 定时任务, 自动化, schedule, heartbeat, cron] | ||
| --- | ||
|
|
||
| # 自动化问题 | ||
|
|
||
| ## 调度(Schedule)和心跳(Heartbeat)有什么区别? | ||
|
|
||
| | 对比项 | 调度(Schedule) | 心跳(Heartbeat) | | ||
| |--------|-----------------|-------------------| | ||
| | 触发方式 | 按时间触发(定时/延迟/周期/cron) | 系统按固定间隔唤醒智能体 | | ||
| | 用途 | 在未来特定时刻执行指定任务 | 让智能体主动检查状态、监控变化 | | ||
| | 上下文 | 每次触发创建全新会话,不继承对话上下文 | 在当前智能体上下文中执行 | | ||
| | 典型场景 | "3 分钟后提醒我开会"、"每天 9 点生成日报" | "监控构建状态"、"定期检查邮件" | | ||
| | 管理方式 | ManageSchedule 工具 | heartbeat/ 目录下的配置 | | ||
|
|
||
| 简单记忆:**调度 = 闹钟**(到时间做特定事),**心跳 = 巡逻**(定期看看有没有事)。 | ||
|
|
||
| ## 定时任务没有触发怎么办? | ||
|
|
||
| 排查步骤: | ||
|
|
||
| 1. **确认调度存在** --- 使用 ManageSchedule(action=list)查看调度列表,确认任务未被删除或取消 | ||
| 2. **检查触发时间** --- 确认 trigger_value 的时区正确(使用带时区的 ISO 格式,如 `2026-07-26T09:00:00+08:00`) | ||
| 3. **检查应用是否运行** --- 调度需要 DesireCore 在运行中才能触发;应用关闭期间到期的调度会在下次启动后补触发 | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
This guarantee is false when a schedule uses the documented Useful? React with 👍 / 👎. |
||
| 4. **检查执行权限** --- 调度的执行受审批模式约束,需确认模式下允许对应操作 | ||
|
|
||
| ## 如何查看调度执行历史? | ||
|
|
||
| 调度每次触发会创建一个新的会话(Run)。查看方式: | ||
|
|
||
| 1. 在智能体的对话历史中找到对应时间的会话记录 | ||
| 2. 调度触发时的 prompt 会作为该会话的第一条消息 | ||
| 3. 如果调度执行失败,可以在会话记录中看到错误信息 | ||
|
Comment on lines
+34
to
+36
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
For triggers whose result is stored only as an execution record, there may be no corresponding conversation to find: the scheduled-task guide says results can enter a conversation, notification, or execution record, while every trigger—including failed and skipped runs—is recorded in the task detail's execution history ( Useful? React with 👍 / 👎. |
||
|
|
||
| ## 心跳通知太频繁怎么调整? | ||
|
|
||
| 如果智能体的心跳检查产生过多通知: | ||
|
|
||
| 1. **调整心跳间隔** --- 修改 heartbeat 配置中的检查频率 | ||
| 2. **使用 notify=false** --- 无变化时静默记录,不发送通知 | ||
| 3. **优化检查逻辑** --- 只在确实有变化或需要关注时才设置 notify=true | ||
|
Comment on lines
+43
to
+44
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
The documented heartbeat contract does not expose a Useful? React with 👍 / 👎. |
||
|
|
||
| :::tip | ||
| 好的心跳实践:大多数时候返回 `no_change`(静默),只在发现异常或重要变化时才通知用户。 | ||
| ::: | ||
|
|
||
| ## Sleep 和 Schedule 该用哪个? | ||
|
|
||
| | 场景 | 选择 | 原因 | | ||
| |------|------|------| | ||
| | 等 5 秒后检查构建状态 | Sleep | 需要拿到结果后继续当前任务 | | ||
| | 3 分钟后提醒开会 | Schedule | 独立任务,不需要当前上下文 | | ||
| | 轮询等待下载完成 | Sleep | 在同一任务链中循环检查 | | ||
| | 每天早上 9 点生成报告 | Schedule(cron) | 周期性独立任务 | | ||
|
|
||
| 核心区别:Sleep 在当前会话中阻塞等待(保留上下文),Schedule 到期时创建全新会话(无上下文)。 | ||
|
|
||
| ## 如何创建周期性定时任务? | ||
|
|
||
| 使用 ManageSchedule 工具,支持四种触发类型: | ||
|
|
||
| | 类型 | 说明 | 示例 | | ||
| |------|------|------| | ||
| | `delay` | 延迟执行一次 | ISO Duration:`PT30M`(30 分钟后) | | ||
| | `at` | 指定时刻执行一次 | `2026-07-26T09:00:00+08:00` | | ||
| | `interval` | 固定间隔重复 | `PT1H`(每小时) | | ||
| | `cron` | Cron 表达式 | `0 9 * * 1-5`(工作日 9 点) | | ||
|
|
||
| 示例 prompt:"每周一早上 9 点提醒我查看周报"→ trigger_type=cron, trigger_value="0 9 * * 1" | ||
|
|
||
| ## 调度任务执行失败如何排查? | ||
|
|
||
| 1. **查看会话记录** --- 找到调度触发时创建的会话,查看错误信息 | ||
| 2. **检查 prompt 是否清晰** --- 调度的 prompt 应包含足够的上下文,因为新会话不继承之前的对话 | ||
| 3. **检查依赖服务** --- 如果任务需要网络、特定文件或 API,确认它们在触发时可用 | ||
| 4. **检查审批模式** --- 需确认的审批模式下,无人值守的调度可能因等待审批而超时 | ||
|
|
||
| :::warning | ||
| 调度的 prompt 中不要引用"上次对话的内容"或"之前的上下文"——每次触发都是全新会话,没有历史记忆。需要引用信息时,在 prompt 中直接写明。 | ||
| ::: | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This step introduces
ManageAgent, but the documented built-in tools list namesDelegate,SendMessage, andManageTeamwhile omitting anyManageAgententry, and a repo-widerg ManageAgentonly finds these newly added FAQ lines. A user following this recipe can get stuck before creating the team because the referenced tool name is not exposed elsewhere in the docs; point them to the actual agent-management UI/tool name and update the English mirror too.Useful? React with 👍 / 👎.