Skip to content

docs(getting-started): polish quickstart chapter with flow diagram and UX tips #39

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.

Sign up for GitHub

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

Merged
yi-ge merged 3 commits into from
Jul 28, 2026
Merged

docs(getting-started): polish quickstart chapter with flow diagram and UX tips #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d567b45
docs(getting-started): polish quickstart chapter with flow diagram an…
yi-ge Jul 25, 2026
b6a7a75
docs(getting-started): improve installation pages and API key guide
yi-ge Jul 25, 2026
2c27751
docs(getting-started/en): sync installation and API key improvements
yi-ge Jul 25, 2026
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
4 changes: 4 additions & 0 deletions docs/01-getting-started/01-system-requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ keywords: [系统要求, 硬件, 操作系统, 兼容性]

DesireCore 桌面客户端支持 macOS、Windows、Linux 三大平台。下面列出了各平台的环境要求。

:::tip 快速判断
如果你的电脑是近 3 年内购买的，基本都能流畅运行 DesireCore。最低只需要 8 GB 内存和 2 GB 磁盘空间。

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 25, 2026

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 Base the quick check on actual hardware and OS requirements

For recently purchased low-end laptops with less than 8 GB RAM, or devices running an unsupported OS such as ChromeOS, the purchase-date heuristic says DesireCore should run smoothly even though the requirements immediately below exclude them. This can send users into an installation they cannot complete; direct them to verify the listed OS, memory, processor, and disk requirements instead.

Useful? React with 👍 / 👎.

:::

## 桌面版

### macOS
Expand Down
10 changes: 10 additions & 0 deletions docs/01-getting-started/02-installation/01-windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ keywords: [Windows, 安装, NSIS, SmartScreen]

本指南介绍如何在 Windows 上安装 DesireCore。

:::tip 预计耗时
整个安装过程通常只需 **1-2 分钟**（取决于下载速度）。
:::

## 安装步骤

1. **下载安装包**
Expand Down Expand Up @@ -83,4 +87,10 @@ Windows 版会随包提供可移植 Git、推荐的 Python/Node.js 运行时归
卸载时会提示是否同时删除应用数据。如果你计划重新安装，建议保留数据；如果确定不再使用，可以选择一并删除。
:::

## 遇到问题？

- **安装程序无法打开**：确认文件下载完整（大小约 100-200 MB），尝试重新下载。
- **杀毒软件拦截**：将 DesireCore 安装目录加入白名单，或暂时关闭实时防护后重试。

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 25, 2026

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 Do not advise disabling real-time protection

When antivirus blocks the installer because it is actually malicious, corrupted, or unexpectedly signed, following this instruction removes the protection immediately before running it. This also directly contradicts lines 52 and 58–60 of the same Windows guide, which tell users not to disable protection and to verify the source and signature; troubleshooting should retain those checks rather than recommend an allowlist or temporary shutdown.

Useful? React with 👍 / 👎.

- **其他问题**：前往 [常见问题](../../06-faq/index.md) 或联系支持团队。

安装完成后，前往 [首次启动](../03-first-run.md) 了解启动后的引导流程。
11 changes: 11 additions & 0 deletions docs/01-getting-started/02-installation/02-macos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ keywords: [macOS, 安装, DMG, Gatekeeper, Apple Silicon, Intel]

本指南介绍如何在 macOS 上安装 DesireCore。

:::tip 预计耗时
整个安装过程通常只需 **1 分钟**——下载 DMG、拖入 Applications 即完成。
:::

## 安装步骤

1. **下载 DMG 文件**
Expand Down Expand Up @@ -72,4 +76,11 @@ DesireCore 的安装包已经过 Apple 公证（Notarization），是安全的
~/.desirecore/
```

## 遇到问题？

- **DMG 无法打开**：确认文件下载完整，尝试重新下载。
- **"已损坏，无法打开"提示**：这通常是 Gatekeeper 拦截，按上方"处理 Gatekeeper 提示"操作即可。

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 25, 2026

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 Treat a damaged-app warning as a verification failure

When macOS reports that the app is damaged, the download may be incomplete or its signature/notarization verification may have failed; it is not the unidentified-developer prompt handled by the control-click/Open Anyway steps above. Directing users to bypass that warning can both leave them stuck and encourage running a tampered copy, so this case should instead require re-downloading from the official source and rechecking the signature.

Useful? React with 👍 / 👎.

- **Apple Silicon 用户运行缓慢**：确认下载的是 arm64 版本而非 x64 版本（Rosetta 转译会有性能损耗）。
- **其他问题**：前往 [常见问题](../../06-faq/index.md) 或联系支持团队。

安装完成后，前往 [首次启动](../03-first-run.md) 了解启动后的引导流程。
9 changes: 9 additions & 0 deletions docs/01-getting-started/02-installation/03-linux.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,15 @@ keywords: [Linux, 安装, AppImage, Ubuntu, Fedora, ARM64, 统信UOS, 银河麒

本指南介绍如何在 Linux 上安装 DesireCore。DesireCore 以 AppImage 格式分发，支持 x64 和 ARM64 架构，兼容大多数主流 Linux 发行版，同时也支持统信 UOS、银河麒麟、深度 Deepin、openKylin 等国产操作系统。

:::tip 老手速览
```bash
# 下载后两步即可运行
chmod +x DesireCore_x86_64_*.AppImage
./DesireCore_x86_64_*.AppImage
```
如遇沙箱报错，请直接跳到 [常见问题排查](#常见问题排查)。
:::

:::tip 国产操作系统用户
DesireCore 已在统信 UOS、银河麒麟（Kylin）、深度 Deepin、openKylin 等国产操作系统上完成适配测试。如需了解国产系统专属的安装说明和兼容性信息，请访问 [DesireCore 中国官网](https://www.desirecore.cn)。
:::
Expand Down
4 changes: 4 additions & 0 deletions docs/01-getting-started/02-installation/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ keywords: [安装, 下载, macOS, Windows, Linux]

DesireCore 桌面客户端支持 macOS、Windows 和 Linux 三大平台。

:::info 安装前确认
请先确保你的设备满足 [系统要求](../01-system-requirements.md)（8 GB 内存、2 GB 磁盘空间、可访问互联网）。
:::

## 下载

前往 DesireCore 官网，点击下载按钮即可获取最新版本：
Expand Down
10 changes: 9 additions & 1 deletion docs/01-getting-started/03-first-run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,15 @@ keywords: [首次启动, 欢迎, 引导, 界面, 主窗口]

### 聊天区域（右侧）

这是你和 AI 同伴交流的主要区域。顶部显示当前对话的智能体信息，底部是消息输入框。
这是你和 AI 同伴交流的主要区域：

- **顶部**：显示当前对话的智能体名称和简介
- **中间**：对话消息流（首次启动时为空）
- **底部**：消息输入框——输入内容后按 **Enter** 发送，**Shift + Enter** 换行

:::tip 提示
将鼠标悬停在导航栏图标上可查看功能名称。界面各区域的详细介绍见 [界面导航](../02-user-guide/01-interface/01-layout-overview.md)。
:::

## 下一步

Expand Down
8 changes: 8 additions & 0 deletions docs/01-getting-started/04-configure-api-key.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@ DesireCore 是一个本地优先的应用——你的核心数据存储在本地
| 官方云端算力 | 不想先注册各家供应商的新用户 | 登录后自动绑定 `desirecore-cloud`，按订阅或 credit 使用 |
| 自备 API Key | 已有供应商账号、需要自控成本或企业合规 | API Key 存储在本机受权限保护的 `secrets.json` 中，供应商配置只保存引用 |

:::info 已经用云端算力了？
如果你已通过账号登录并绑定了官方云端算力，**可以跳过本页**，直接开始 [第一次对话](./05-first-conversation.md)。后续想添加更多供应商时随时回来配置。
:::

## 什么是 API Key？

API Key 就像是你访问 AI 服务的"钥匙"。每个 AI 供应商（如 OpenAI、Anthropic、DeepSeek 等）都提供 API 服务，你需要在它们的网站上注册并获取一个 API Key，然后在 DesireCore 中填入，DesireCore 就能调用对应的 AI 模型了。
Expand All @@ -33,6 +37,10 @@ API Key 就像是你访问 AI 服务的"钥匙"。每个 AI 供应商（如 Open

<!-- 截图占位: 配置 API Key (configure-api-key.png) -->

:::note 密钥安全
你的 API Key 仅保存在本机的 `~/.desirecore/secrets.json` 中（文件权限为 `600`，仅当前用户可读），不会上传到 DesireCore 服务器或任何第三方。

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 25, 2026

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 State that the configured provider receives the key

For every self-managed provider request, the claim that the key is never sent to “any third party” is false: the key must be sent to that provider as authentication, as documented in docs/02-user-guide/10-settings/04-compute-service.md lines 113–114. This materially misstates the privacy boundary; clarify that the key is not uploaded to DesireCore but is transmitted to the configured provider when the user invokes it.

Useful? React with 👍 / 👎.

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 25, 2026

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 Use the actual secrets path and platform-specific permissions

Users trying to inspect or protect this file are directed to the wrong location: the rest of the documentation consistently identifies it as ~/.desirecore/config/secrets.json, not ~/.desirecore/secrets.json. In addition, the unconditional 600 claim does not apply on Windows; docs/02-user-guide/10-settings/04-compute-service.md lines 111–112 explicitly limits that mode to POSIX platforms and describes Windows ACL protection separately.

Useful? React with 👍 / 👎.

:::

## 各供应商 API Key 获取指南

DesireCore 支持超过 20 个 AI 供应商。下面是最常用的几个供应商的获取方法。
Expand Down
8 changes: 7 additions & 1 deletion docs/01-getting-started/05-first-conversation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ DesireCore 是随应用自带的通用智能体，使用蓝色圆形头像。它

发送后，你会看到一个"DesireCore 思考中"的提示，几秒钟后，智能体的回复就会出现在对话中。

回复以左侧气泡的形式展示，你发送的消息在右侧。
回复以左侧气泡的形式展示，你发送的消息在右侧。首次对话的回复通常是纯文字；当你开始让智能体执行任务后，还会看到行动回执、委派通知等更丰富的卡片格式（见下方"理解回复格式"）。

## 理解回复格式

Expand Down Expand Up @@ -72,4 +72,10 @@ DesireCore 的智能体不仅会回复文字，还可能展示不同类型的内

就这么简单！DesireCore 的核心体验就是自然的对话——你说，它做。随着你使用得越多，它会越来越了解你的偏好和习惯。

:::tip 对话小技巧
- 你可以随时在同一对话中切换话题，智能体会记住上下文
- 如果回复不理想，直接告诉它哪里需要调整即可
- 想让智能体记住某个偏好？直接说"记住：我喜欢……"

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 25, 2026

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 Tell users to confirm the learned preference

When a newcomer follows this tip, saying the phrase alone does not make the preference persistent: docs/02-user-guide/03-teaching/05-learning-feedback.md lines 28–35 says the knowledge is formally written only after the user confirms the learning-feedback card, and the memory guide likewise requires accepting a candidate. Without mentioning that confirmation step, users can leave the card unconfirmed and later find that the promised preference was not remembered.

Useful? React with 👍 / 👎.

:::

准备好探索更多功能了吗？看看 [下一步去哪里](./06-whats-next.md)。
4 changes: 4 additions & 0 deletions docs/01-getting-started/06-whats-next.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ keywords: [下一步, 指南, 学习路径, 推荐]

恭喜你完成了快速上手！现在你已经能和 AI 同伴正常对话了。接下来，根据你想做的事情，选择一条适合你的探索路径。

:::tip 不知道从哪开始？
建议先试试"教会智能体做事"——告诉 DesireCore 你的名字、工作背景和偏好，它会立刻变得更懂你。这是最快感受到价值的方式。
:::

## 按需求选择路径

### 想熟悉界面操作
Expand Down
2 changes: 2 additions & 0 deletions docs/01-getting-started/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ DesireCore 是一个"委派式交互的 Agent 操作系统"——你可以像带

按照以下步骤，你很快就能和你的 AI 同伴开始第一次对话：

![快速上手流程：检查系统要求 → 安装 → 首次启动 → 配置 API Key → 第一次对话](/img/getting-started/quickstart-flow.svg)

| 步骤 | 内容 | 预计时间 |
|------|------|----------|
| **1** | [检查系统要求](./01-system-requirements.md) | 10 秒 |
Expand Down
10 changes: 10 additions & 0 deletions ...us-plugin-content-docs/current/01-getting-started/02-installation/01-windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ keywords: [Windows, installation, NSIS, SmartScreen]

This guide covers how to install DesireCore on Windows.

:::tip Estimated time
The entire installation typically takes just **1–2 minutes** (depending on download speed).
:::

## Installation Steps

1. **Download the installer**
Expand Down Expand Up @@ -81,4 +85,10 @@ To uninstall DesireCore:
During uninstallation, you'll be asked whether to also delete application data. If you plan to reinstall, it's recommended to keep the data; if you're sure you won't use it again, you can choose to delete everything.
:::

## Troubleshooting

- **Installer won't open**: Verify the download completed successfully (file size ~100–200 MB), then try downloading again.
- **Antivirus blocks installation**: Add the DesireCore install directory to your antivirus allowlist, or temporarily disable real-time protection and retry.
- **Other issues**: Visit the [FAQ](../../06-faq/index.md) or contact our support team.

After installation, head to [First Run](../03-first-run.md) to learn about the post-launch onboarding flow.
11 changes: 11 additions & 0 deletions ...urus-plugin-content-docs/current/01-getting-started/02-installation/02-macos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ keywords: [macOS, installation, DMG, Gatekeeper, Apple Silicon, Intel]

This guide covers how to install DesireCore on macOS.

:::tip Estimated time
The entire installation typically takes just **1 minute** — download the DMG, drag to Applications, done.
:::

## Installation Steps

1. **Download the DMG file**
Expand Down Expand Up @@ -76,4 +80,11 @@ To also remove application data, delete the following directories:
~/.desirecore/
```

## Troubleshooting

- **DMG won't open**: Verify the download completed successfully, then try downloading again.
- **"is damaged and can't be opened" message**: This is usually Gatekeeper blocking the app — follow the "Handling Gatekeeper Prompts" section above.
- **Slow performance on Apple Silicon**: Confirm you downloaded the arm64 version, not x64 (Rosetta translation incurs a performance penalty).
- **Other issues**: Visit the [FAQ](../../06-faq/index.md) or contact our support team.

After installation, head to [First Run](../03-first-run.md) to learn about the post-launch onboarding flow.
9 changes: 9 additions & 0 deletions ...urus-plugin-content-docs/current/01-getting-started/02-installation/03-linux.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,15 @@ keywords: [Linux, installation, AppImage, Ubuntu, Fedora, ARM64, UnionTech UOS,

This guide covers how to install DesireCore on Linux. DesireCore is distributed as an AppImage, supporting both x64 and ARM64 architectures, and is compatible with most mainstream Linux distributions, including Chinese domestic operating systems such as UnionTech UOS, Kylin OS, Deepin, and openKylin.

:::tip Experienced users — quick start
```bash
# Two commands after downloading:
chmod +x DesireCore_x86_64_*.AppImage
./DesireCore_x86_64_*.AppImage
```
If you hit a sandbox error, jump to [Troubleshooting](#troubleshooting-sandbox-errors).
:::

:::tip Chinese Domestic OS Users
DesireCore has been tested and verified on UnionTech UOS, Kylin OS, Deepin, openKylin, and other Chinese domestic operating systems. For platform-specific installation instructions and compatibility details, please visit the [DesireCore China website](https://www.desirecore.cn).
:::
Expand Down
8 changes: 8 additions & 0 deletions ...cusaurus-plugin-content-docs/current/01-getting-started/04-configure-api-key.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@ DesireCore is a local-first application: core data is stored locally by default.
| Official cloud compute | Users who do not want to register with each model provider first | Sign in to bind the `desirecore-cloud` provider and use a subscription or credits |
| Your own API key | Existing provider accounts, direct cost control, or enterprise compliance | The key is stored in the permission-protected local `secrets.json`; provider configuration stores only a reference |

:::info Already using cloud compute?
If you've signed in and bound official cloud compute, you can **skip this page** and go straight to [Your First Conversation](./05-first-conversation.md). Come back anytime to add more providers.
:::

## What is an API Key?

An API Key is like a "key" to access AI services. Each AI provider (such as OpenAI, Anthropic, DeepSeek, etc.) offers API services — you need to register on their website, obtain an API Key, and then enter it in DesireCore so it can call the corresponding AI models.
Expand All @@ -33,6 +37,10 @@ Calls made with your own API key are billed by the corresponding provider. Offic

<!-- Screenshot placeholder: Configure API Key (configure-api-key.png) -->

:::note Key Security
Your API Key is stored only in the local file `~/.desirecore/secrets.json` (file permission `600`, readable only by the current user). It is never uploaded to DesireCore servers or any third party.
:::

## Provider API Key Guides

DesireCore supports over 20 AI providers. Below are instructions for the most commonly used ones.
Expand Down
2 changes: 2 additions & 0 deletions i18n/en/docusaurus-plugin-content-docs/current/01-getting-started/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ DesireCore is a "delegation-based interactive Agent OS" — you can train your A

Follow these steps to start your first conversation with your AI companion:

![Quickstart flow: Check requirements → Install → First launch → Configure API Key → First conversation](/img/getting-started/quickstart-flow-en.svg)

| Step | Content | Estimated Time |
|------|---------|----------------|
| **1** | [Check system requirements](./01-system-requirements.md) | 10 seconds |
Expand Down
33 changes: 33 additions & 0 deletions static/img/getting-started/quickstart-flow-en.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
33 changes: 33 additions & 0 deletions static/img/getting-started/quickstart-flow.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading