Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/01-getting-started/02-installation/01-windows.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ CUA Driver 仅用于当前 Windows 电脑的 GUI 自动化,默认启用。它
这些归档和可执行程序会增加安装包与首次启动后的磁盘占用。安全软件也可能在首次解包或运行时再次扫描它们;请等待扫描完成,不要通过关闭系统防护来强行绕过告警。
:::

你可以在 **资源管理器** → **算力** → **运行环境** 查看实际版本与路径。许可和来源说明见 [第三方软件与许可](../../05-more/09-third-party-software.md)。
你可以在 **资源管理器** → **算力** → **运行环境** 查看实际版本与路径。许可和来源说明见 [第三方软件与许可](../../05-more/10-third-party-software.md)。

## 处理 Windows SmartScreen 提示

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ keywords: [Web, Android, iOS, 鸿蒙, HarmonyOS, 移动端]
- **鸿蒙版** — 支持 HarmonyOS 设备
:::

我们会在版本发布时通过 [更新日志](../../05-more/10-changelog/index.md) 和官方网站公布最新进展。
我们会在版本发布时通过 [更新日志](../../05-more/11-changelog/index.md) 和官方网站公布最新进展。

目前请使用桌面客户端获得完整体验:

Expand Down
2 changes: 1 addition & 1 deletion docs/02-user-guide/09-capabilities/05-computer-use.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ GUI 自动化依赖目标平台提供的可访问性、窗口和输入能力,
- 对业务关键流程先在测试账号或副本数据上验证。

:::warning 第三方组件
Windows 当前使用的 CUA Driver 是由其权利人提供、按其自身许可证分发的独立第三方程序,并非 DesireCore 自有组件或 HostAgent。它是 Windows HostAgent 完成前的过渡载体;其版本、兼容性和上游支持可能变化,具体以随软件提供的第三方声明及 [第三方软件与许可](../../05-more/09-third-party-software.md) 为准。
Windows 当前使用的 CUA Driver 是由其权利人提供、按其自身许可证分发的独立第三方程序,并非 DesireCore 自有组件或 HostAgent。它是 Windows HostAgent 完成前的过渡载体;其版本、兼容性和上游支持可能变化,具体以随软件提供的第三方声明及 [第三方软件与许可](../../05-more/10-third-party-software.md) 为准。
:::

## 下一步
Expand Down
2 changes: 1 addition & 1 deletion docs/05-more/08-system-requirements-detail.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ macOS 当前通过 HostAgent 承载本机 GUI 操作,需要辅助功能、屏

Git 使用 GPLv2;Python 和 Node.js 的二进制发行物还包含主体许可证之外的依赖许可。DesireCore 会按发布版本记录来源与许可材料,但不同平台、版本和归档的条款可能变化。请以安装包、组件归档及对应发布页面提供的完整文本为准。普通使用通常不要求你采取额外行动;若你提取、修改或再分发这些组件,应自行核对相应的署名、许可文本、对应源码和其他义务。

详见 [第三方软件与许可](./09-third-party-software.md)和[用户协议](../terms.md)。
详见 [第三方软件与许可](./10-third-party-software.md)和[用户协议](../terms.md)。

## 网络要求

Expand Down
2 changes: 1 addition & 1 deletion docs/05-more/09-open-source-repos.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ DesireCore 项目在 GitHub 上维护了多个官方仓库,欢迎关注和参
| `desirecore-hostagent` | 原生 HostAgent 平台代码,用于 GUI 操作、设备能力、发现、配对与常驻执行 | macOS 实现当前已作为 GUI 操作载体;Windows、Linux、其他桌面与移动端实现仍在开发。初步计划稳定后开源,根据公司融资情况和经营战略决定,不作为最终承诺 |

:::info 不同平台的当前载体
macOS 当前仍由 HostAgent 承载 GUI 操作。Windows 为了让用户在原生 HostAgent 完成前先使用本机 GUI 自动化,暂时采用 DesireCore 随附的独立第三方 CUA Driver;这不表示 HostAgent 已被弃用或替代。第三方组件不属于 DesireCore 官方仓库,详见 [第三方软件与许可](./09-third-party-software.md)。
macOS 当前仍由 HostAgent 承载 GUI 操作。Windows 为了让用户在原生 HostAgent 完成前先使用本机 GUI 自动化,暂时采用 DesireCore 随附的独立第三方 CUA Driver;这不表示 HostAgent 已被弃用或替代。第三方组件不属于 DesireCore 官方仓库,详见 [第三方软件与许可](./10-third-party-software.md)。
:::

## 文档与分发
Expand Down
File renamed without changes.
3 changes: 2 additions & 1 deletion docs/05-more/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,5 @@ sidebar_position: 0
| [数据存储位置](./07-data-locations.md) | 各平台的数据存储路径 |
| [详细系统要求](./08-system-requirements-detail.md) | 完整的硬件和软件要求 |
| [开源仓库](./09-open-source-repos.md) | 官方 GitHub 仓库一览 |
| [更新日志](./10-changelog/index.md) | 版本更新历史记录 |
| [第三方软件与许可](./10-third-party-software.md) | 内置第三方组件及开源许可 |
| [更新日志](./11-changelog/index.md) | 版本更新历史记录 |
2 changes: 1 addition & 1 deletion docs/06-faq/01-installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ DesireCore 的安装包托管在多个下载源上(CDN、构建服务器、Git

DesireCore 的智能体需要在本地执行版本管理、脚本和 Windows GUI 操作,因此安装包中包含独立的 Git、Python/Node.js 归档和 CUA Driver。首次安装、解包或执行时,安全软件可能分别扫描这些文件,这不等同于检测到恶意行为。

请始终使用官方安装包并保留系统防护。如果安全软件明确报告威胁,不要盲目加入白名单;先记录文件路径、DesireCore 版本、检测名称和文件哈希,通过官方渠道反馈。第三方组件来源与许可见 [第三方软件与许可](../05-more/09-third-party-software.md)。
请始终使用官方安装包并保留系统防护。如果安全软件明确报告威胁,不要盲目加入白名单;先记录文件路径、DesireCore 版本、检测名称和文件哈希,通过官方渠道反馈。第三方组件来源与许可见 [第三方软件与许可](../05-more/10-third-party-software.md)。

## 启动后显示白屏?

Expand Down
65 changes: 62 additions & 3 deletions docs/06-faq/06-performance.md
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 服务),总资源占用是所有子进程之和。
74 changes: 74 additions & 0 deletions docs/06-faq/07-delegation.md
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)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Point team setup to a real agent-creation entrypoint

This step introduces ManageAgent, but the documented built-in tools list names Delegate, SendMessage, and ManageTeam while omitting any ManageAgent entry, and a repo-wide rg ManageAgent only 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 👍 / 👎.

2. 使用 ManageTeam 创建团队,指定组长和成员
3. 组长通过 Delegate 向成员分派任务
4. 成员完成后向组长汇报结果

:::warning
ManageTeam 不会自动创建缺失的成员。组队前必须先确认所有智能体已存在。
:::
83 changes: 83 additions & 0 deletions docs/06-faq/08-automation.md
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 在运行中才能触发;应用关闭期间到期的调度会在下次启动后补触发

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Honor missed-fire policy instead of promising a catch-up

This guarantee is false when a schedule uses the documented skip missed-fire policy: docs/02-user-guide/08-automation/03-scheduled-tasks.md:268-280 says only missed interval runs are detected for compensation and that missed_fire_policy determines whether they run at all. A user relying on this FAQ may close the app expecting a reminder or job to execute on restart even though it is skipped. Describe the policy-dependent behavior here and in the English mirror.

Useful? React with 👍 / 👎.

4. **检查执行权限** --- 调度的执行受审批模式约束,需确认模式下允许对应操作

## 如何查看调度执行历史?

调度每次触发会创建一个新的会话(Run)。查看方式:

1. 在智能体的对话历史中找到对应时间的会话记录
2. 调度触发时的 prompt 会作为该会话的第一条消息
3. 如果调度执行失败,可以在会话记录中看到错误信息
Comment on lines +34 to +36

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Direct users to the automation panel for schedule history

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 (docs/02-user-guide/08-automation/03-scheduled-tasks.md:282-306). Direct users to Automation → task details → execution history rather than presenting conversation history as the way to inspect runs, and update the English mirror as well.

Useful? React with 👍 / 👎.


## 心跳通知太频繁怎么调整?

如果智能体的心跳检查产生过多通知:

1. **调整心跳间隔** --- 修改 heartbeat 配置中的检查频率
2. **使用 notify=false** --- 无变化时静默记录,不发送通知
3. **优化检查逻辑** --- 只在确实有变化或需要关注时才设置 notify=true
Comment on lines +43 to +44

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Replace the unsupported heartbeat notify flag

The documented heartbeat contract does not expose a notify configuration flag: HeartbeatRespond submits an outcome and optional notificationText, and no_change is the outcome that records silently (docs/02-user-guide/08-automation/01-heartbeat.md:66-86). Consequently, setting notify=false or notify=true as suggested here will not adjust notification behavior. Direct users to return no_change or the appropriate structured outcome, and update the English mirror as well.

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 中直接写明。
:::
4 changes: 3 additions & 1 deletion docs/06-faq/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,4 +46,6 @@ DesireCore 支持多家模型供应商,包括 OpenAI、Anthropic (Claude)、Go
| [对话问题](./03-conversations.md) | 消息失败、回复太慢、历史丢失 |
| [智能体问题](./04-agents.md) | 安装失败、重置智能体、记忆问题 |
| [数据与隐私](./05-data-privacy.md) | 数据存储位置、备份方法、完全删除 |
| [性能问题](./06-performance.md) | 内存占用、响应速度、优化方法 |
| [性能问题](./06-performance.md) | 内存占用、磁盘空间、GPU、优化方法 |
| [委派与协作](./07-delegation.md) | 委派进展、团队协作、回执查看 |
| [自动化问题](./08-automation.md) | 调度 vs 心跳、定时任务、周期任务 |
2 changes: 1 addition & 1 deletion docs/terms.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ DesireCore v10 及更高版本采用分层许可模式。DesireCore 自有代码
- Node.js:MIT License,且其发行包包含使用其他许可证的第三方依赖;应保留完整许可证清单
- cua-driver:MIT License;应保留版权和许可声明

DesireCore 将这些独立组件聚合到安装包,不表示相关项目或权利人对 DesireCore 的背书、认证或担保。第三方组件按其许可证以“现状”提供,版本、可用性和打包方式可能因平台、上游条款或合规审查而调整。完整且具有约束力的条款以安装包内的 Third-Party Notices、许可证原文和对应源码说明为准;面向用户的版本与风险概要见[第三方软件与许可](./05-more/09-third-party-software.md)。
DesireCore 将这些独立组件聚合到安装包,不表示相关项目或权利人对 DesireCore 的背书、认证或担保。第三方组件按其许可证以“现状”提供,版本、可用性和打包方式可能因平台、上游条款或合规审查而调整。完整且具有约束力的条款以安装包内的 Third-Party Notices、许可证原文和对应源码说明为准;面向用户的版本与风险概要见[第三方软件与许可](./05-more/10-third-party-software.md)。

如用户再分发安装包、提取或单独分发这些组件,应自行确认并履行适用许可证义务。DesireCore 对第三方组件的聚合不授予超出原许可证范围的权利。

Expand Down
Loading
Loading