diff --git a/docs/02-user-guide/01-interface/01-layout-overview.md b/docs/02-user-guide/01-interface/01-layout-overview.md index 079dc9b..fe51d2d 100644 --- a/docs/02-user-guide/01-interface/01-layout-overview.md +++ b/docs/02-user-guide/01-interface/01-layout-overview.md @@ -10,6 +10,8 @@ DesireCore 采用**单窗口三栏布局**，所有功能都在一个窗口内 ## 布局示意 +![DesireCore 三栏布局示意图](/img/user-guide/interface/three-column-layout.svg) + ``` +--------------------------------------------------------------+ | +------+--------------+----------------------------------+ | diff --git a/docs/02-user-guide/01-interface/07-feature-entry.md b/docs/02-user-guide/01-interface/07-feature-entry.md index a278a79..93acb5b 100644 --- a/docs/02-user-guide/01-interface/07-feature-entry.md +++ b/docs/02-user-guide/01-interface/07-feature-entry.md @@ -1,3 +1,9 @@ +--- +title: 功能入口与操作路径 +description: 快速了解 DesireCore 的三大功能区域（对话界面、资源管理器、应用与服务）及常用操作路径。 +keywords: [功能入口, 操作路径, 对话界面, 资源管理器, 应用与服务, 新手引导] +--- + # 功能入口与操作路径 第一次用 DesireCore？不知道从哪里开始？ diff --git a/docs/02-user-guide/02-conversations/01-sending-messages.md b/docs/02-user-guide/02-conversations/01-sending-messages.md index 84373a0..6b7a9b0 100644 --- a/docs/02-user-guide/02-conversations/01-sending-messages.md +++ b/docs/02-user-guide/02-conversations/01-sending-messages.md @@ -155,4 +155,4 @@ DesireCore 的输入区域支持多种消息发送方式，包括文本、图片 - 了解[消息类型识别](./02-message-types.md)，区分不同角色的消息 - 查看[交互卡片详解](./03-cards.md)，了解 Companion 回复中的各种卡片 -- 了解[上下文控制](./context-control)和 [Rewind / Checkpoint](./rewind-checkpoints) +- 了解[上下文控制](./09-context-control.md)和 [Rewind / Checkpoint](./10-rewind-checkpoints.md) diff --git a/docs/02-user-guide/02-conversations/02-message-types.md b/docs/02-user-guide/02-conversations/02-message-types.md index 465c81c..9ffc942 100644 --- a/docs/02-user-guide/02-conversations/02-message-types.md +++ b/docs/02-user-guide/02-conversations/02-message-types.md @@ -45,7 +45,7 @@ Companion 的消息可以包含多种结构化内容： | `.md` 路径 | 可信助手回复中的本地 Markdown 路径可点击打开 | | 图片 | 图片附件可预览，也会参与对话导出 | -消息操作栏中「复制」会复制纯文本，「复制 Markdown」会保留 Markdown 结构。详见 [Markdown 与图表渲染](./markdown-rendering)。 +消息操作栏中「复制」会复制纯文本，「复制 Markdown」会保留 Markdown 结构。详见 [Markdown 与图表渲染](./07-markdown-rendering.md)。 ### 思考过程 @@ -119,4 +119,4 @@ Companion 的心跳（Heartbeat）系统会定期检查状态并汇报。需要 - 深入了解[交互卡片详解](./03-cards.md)，掌握各种功能卡片的用途 - 学习如何[选择 AI 模型](./04-model-selection.md) -- 阅读 [Markdown 与图表渲染](./markdown-rendering) +- 阅读 [Markdown 与图表渲染](./07-markdown-rendering.md) diff --git a/docs/02-user-guide/02-conversations/05-chat-history.md b/docs/02-user-guide/02-conversations/05-chat-history.md index da56ef5..4eb7adf 100644 --- a/docs/02-user-guide/02-conversations/05-chat-history.md +++ b/docs/02-user-guide/02-conversations/05-chat-history.md @@ -81,9 +81,9 @@ DesireCore 会保存你与每个 Companion 的所有对话记录。你可以随 - 图片附件可以随导出嵌入 - 工具调用可选择隐藏、摘要或完整展开 -详见 [导出对话](./exporting-conversations)。 +详见 [导出对话](./08-exporting-conversations.md)。 ## 下一步 - 了解如何[管理对话](./06-managing-conversations.md)，包括新建、删除和清除上下文 -- 学习[上下文控制](./context-control)，区分历史、压缩和新上下文 +- 学习[上下文控制](./09-context-control.md)，区分历史、压缩和新上下文 diff --git a/docs/02-user-guide/02-conversations/06-managing-conversations.md b/docs/02-user-guide/02-conversations/06-managing-conversations.md index ef71027..115c9b6 100644 --- a/docs/02-user-guide/02-conversations/06-managing-conversations.md +++ b/docs/02-user-guide/02-conversations/06-managing-conversations.md @@ -70,7 +70,7 @@ DesireCore 的对话以 Companion 为单位组织 --- 每个 Companion 对应一 | Rewind | 回到某条用户消息前的检查点 | 保留旧分支 | | 清除聊天记录 | 删除当前 Companion 的历史消息 | 否 | -详见 [上下文控制](./context-control) 和 [Rewind 与 Checkpoint](./rewind-checkpoints)。 +详见 [上下文控制](./09-context-control.md) 和 [Rewind 与 Checkpoint](./10-rewind-checkpoints.md)。 ## 删除对话 @@ -109,5 +109,5 @@ DesireCore 的对话支持跨会话的上下文延续： - 返回查看[发送消息](./01-sending-messages.md)的详细操作 - 了解[交互卡片](./03-cards.md)的含义 -- 学习[导出对话](./exporting-conversations) +- 学习[导出对话](./08-exporting-conversations.md) - 遇到问题？查看[常见问题](../../06-faq/index.md) diff --git a/docs/02-user-guide/02-conversations/07-markdown-rendering.md b/docs/02-user-guide/02-conversations/07-markdown-rendering.md index b7709b1..187e0fa 100644 --- a/docs/02-user-guide/02-conversations/07-markdown-rendering.md +++ b/docs/02-user-guide/02-conversations/07-markdown-rendering.md @@ -48,6 +48,60 @@ DesireCore 支持常见 LaTeX 写法： 路径点击只对可信助手回复中的本地 Markdown 路径启用。普通文本、用户消息和不明确的路径不会自动执行任何操作。 ::: +## 渲染效果示例 + +以下是 Companion 回复中常见的 Markdown 元素渲染效果： + +**代码块**（带语法高亮和一键复制）： + +````markdown +```python +def hello(): + print("Hello, DesireCore!") +``` +```` + +**表格**（自动对齐，窄屏横向滚动）： + +```markdown +| 功能 | 状态 | +|------|------| +| 渲染 | ✅ | +| 复制 | ✅ | +``` + +**Mermaid 图表**（自动渲染为可视化图形）： + +````markdown +```mermaid +graph LR + A[用户输入] --> B[Companion 处理] + B --> C[返回结果] +``` +```` + +**数学公式**（KaTeX 排版）： + +```markdown +行内：$E = mc^2$ +块级：$$\int_0^1 x^2 dx = \frac{1}{3}$$ +``` + +## 渲染异常处理 + +| 异常情况 | 表现 | 处理方式 | +|----------|------|----------| +| Mermaid 语法错误 | 保留原始代码块，不渲染图表 | 让 Companion 修正语法后重新输出 | +| LaTeX 公式格式错误 | 显示原始 LaTeX 源码 | 检查 `$` 定界符是否配对 | +| 表格列数不一致 | 部分列可能错位 | 确认每行 `|` 数量一致 | +| 代码块未闭合 | 后续内容被当作代码 | 确认 ``` 成对出现 | + +:::tip 实用建议 +- 如果 Companion 输出的 Mermaid 图表未渲染，可以直接告诉它"Mermaid 语法有误，请修正" +- 需要复制图表源码时，使用「复制 Markdown」而非「复制」 +- 长公式在气泡内可横向滚动，不会撑破布局 +::: + ## 复制内容 消息操作栏提供两种复制方式： diff --git a/docs/02-user-guide/02-conversations/08-exporting-conversations.md b/docs/02-user-guide/02-conversations/08-exporting-conversations.md index 6479114..af30ca8 100644 --- a/docs/02-user-guide/02-conversations/08-exporting-conversations.md +++ b/docs/02-user-guide/02-conversations/08-exporting-conversations.md @@ -51,3 +51,29 @@ PDF 导出适合正式归档和分享。桌面端会使用统一的文档渲染 | 调试智能体行为 | 导出完整工具调用 | | 做会议纪要或报告 | 隐藏工具调用，仅保留摘要 | +## 操作步骤 + +### 导出完整对话 + +1. 打开目标 Companion 的聊天界面 +2. 点击聊天头部右侧的「更多」按钮（三个圆点） +3. 在弹出菜单中选择「导出对话」 +4. 在导出设置面板中选择格式（Markdown / PDF）和内容选项 +5. 确认导出，文件保存到系统下载目录或你指定的位置 + +### 多选导出（部分消息） + +1. 在聊天头部「更多」菜单中选择「多选」，进入多选模式 +2. 勾选需要导出的消息（消息左侧出现复选框） +3. 点击底部操作栏的「导出」按钮 +4. 选择格式和内容选项后确认 + +:::tip 导出范围说明 +多选导出会按选中消息所属的 run（一次完整的请求-响应周期）聚合，确保上下文完整。例如你选中了一条 Companion 回复，该回复对应的用户提问和工具调用过程也会一并导出。 +::: + +## 下一步 + +- 了解[对话历史](./05-chat-history.md)中的搜索和定位功能 +- 学习[上下文控制](./09-context-control.md)管理长对话 + diff --git a/docs/02-user-guide/02-conversations/09-context-control.md b/docs/02-user-guide/02-conversations/09-context-control.md index a5331ae..f4e2106 100644 --- a/docs/02-user-guide/02-conversations/09-context-control.md +++ b/docs/02-user-guide/02-conversations/09-context-control.md @@ -8,6 +8,8 @@ keywords: [上下文, 压缩, /new, /compact, CompactSession, 长对话] DesireCore 会保存完整对话历史，但模型每次只能读取有限长度的上下文。上下文控制用于在不丢失可见历史的前提下，让长对话继续稳定运行。 +![上下文生命周期示意图](/img/user-guide/conversations/context-lifecycle.svg) + ## `/new`：开启新上下文 输入 `/new` 会在当前对话中创建新的上下文边界。 @@ -53,3 +55,24 @@ DesireCore 会保存完整对话历史，但模型每次只能读取有限长度 | 自动压缩 | 保留 | 后台压缩旧上下文 | 可查看原始历史 | | 清除聊天记录 | 删除 | 删除对应历史 | 通常不可恢复 | +## 实践建议 + +| 场景 | 推荐操作 | 理由 | +|------|----------|------| +| 换话题（如从写代码转到问天气） | `/new` | 避免旧任务上下文干扰新话题 | +| 长任务进行中（如连续写 20 页文档） | `/compact` | 释放上下文空间，保留任务摘要 | +| 对话已经很长但还在同一任务 | 等待自动压缩 | 系统会自动在合适时机压缩 | +| 智能体走错方向，想重来 | Rewind | 回到错误前的检查点 | +| 彻底不需要这段对话 | 清除聊天记录 | 不可逆，慎用 | + +:::info `/new` vs `/compact` 如何选择 +- **`/new`**：完全切断与之前内容的上下文关联。适合"前面聊的事跟接下来完全无关"的场景。 +- **`/compact`**：保留之前内容的摘要。适合"还在做同一件事，只是对话太长了"的场景。 + +如果你不确定用哪个，优先用 `/compact`——它更温和，不会丢失任务上下文。 +::: + +:::tip 记忆不受压缩影响 +Companion 的长期记忆（通过教学或自动学习获得的知识）存储在 AgentFS 中，不受上下文压缩影响。即使执行了 `/new` 或 `/compact`，Companion 学到的规则和偏好仍然有效。 +::: + diff --git a/docs/02-user-guide/02-conversations/10-rewind-checkpoints.md b/docs/02-user-guide/02-conversations/10-rewind-checkpoints.md index 3c23990..58df243 100644 --- a/docs/02-user-guide/02-conversations/10-rewind-checkpoints.md +++ b/docs/02-user-guide/02-conversations/10-rewind-checkpoints.md @@ -55,3 +55,26 @@ Rewind 主要恢复 DesireCore 管理的本地状态。以下外部副作用通 - 第三方服务内部已经完成的交易或审批 如果回撤涉及外部副作用，建议查看审计记录后再决定下一步处理方式。 + +## 分支机制 + +Rewind 不是"删除"历史，而是从检查点创建新的运行分支： + +![Rewind 分支机制示意图](/img/user-guide/conversations/rewind-branch.svg) + +- **旧分支保留**：回撤前的所有消息和操作记录仍然存在于历史中，不会被删除 +- **新分支创建**：确认后，系统从目标检查点开始一条新的运行路径 +- **多次 Rewind**：你可以多次执行 Rewind，每次都会产生新的分支，形成类似 Git 的分支结构 + +``` +时间线： + 消息1 → 消息2 → 消息3 → 消息4（原始路径） + ↘ + 消息3' → 消息4'（第一次 Rewind 后的新路径） + ↘ + 消息3'' → ...（第二次 Rewind） +``` + +:::tip 安全网 +因为旧分支始终保留，Rewind 是一个低风险操作。即使回撤后新路径也不理想，你可以再次 Rewind 回到更早的检查点，或者查看旧分支中的内容作为参考。 +::: diff --git a/static/img/user-guide/conversations/context-lifecycle.svg b/static/img/user-guide/conversations/context-lifecycle.svg new file mode 100644 index 0000000..27b782a --- /dev/null +++ b/static/img/user-guide/conversations/context-lifecycle.svg @@ -0,0 +1,52 @@ + + + + + + + + + 上下文生命周期 + + + + + + 消息1 + + 消息2 + + 消息3 + + /compact + + 消息4 + + 消息5 + + /new + + + 压缩为摘要 + 消息1-3 的要点被提炼 + 原始内容仍可查看 + + + 活跃上下文 + 摘要 + 最近消息 + 模型实际读取的内容 + + + 新边界 + 之前的内容 + 不再自动读取 + + + 命令对比 + + /compact — 压缩旧消息为摘要，保留任务连续性，适合同一长任务 + + /new — 完全切断上下文关联，适合切换到全新话题 + + 自动压缩 — 接近上下文上限时系统自动触发，无需手动操作 + diff --git a/static/img/user-guide/conversations/rewind-branch.svg b/static/img/user-guide/conversations/rewind-branch.svg new file mode 100644 index 0000000..56b9f5b --- /dev/null +++ b/static/img/user-guide/conversations/rewind-branch.svg @@ -0,0 +1,44 @@ + + + + + + + + + + Rewind 分支机制 + + + + 消息1 + + 消息2 + + 消息3 + + 消息4 + + 消息5 + + + ⏪ Rewind 点 + + + + + 消息3' + + 消息4' + 新路径 + + + 第一次 Rewind 后的新分支 + + + 关键特性 + • 旧分支（绿色）始终保留，不会被删除 + • 新分支（蓝色）从 Rewind 点开始，可以独立发展 + • 可多次 Rewind，产生多个分支 + • 支持恢复文件、记忆、技能等工作状态 + diff --git a/static/img/user-guide/interface/three-column-layout.svg b/static/img/user-guide/interface/three-column-layout.svg new file mode 100644 index 0000000..4755015 --- /dev/null +++ b/static/img/user-guide/interface/three-column-layout.svg @@ -0,0 +1,81 @@ + + + + + + + + + + + + + DesireCore 三栏布局 + + + NavRail + 62px + + Logo + + 对话 + + 关系 + + 资源 + + 应用 + + 市场 + + 🔔 + + ⚙ + + + 对话列表 + 290px + + 🔍 搜索智能体... + + + DesireCore + 好的，让我帮你分析... + 11:05 + + + 法律助手 + 合同审查已完成... + 昨天 + + + 数据分析师 + 报表已生成... + 周一 + + + 聊天区域 + flex-1 自适应 + + + + DesireCore + + 在线 + [沉浸] [档案] [更多] + + + 你好！有什么可以帮你的？ + + 帮我分析一下这份报告 + + 好的，让我读取文件并分析... + + 🔧 Read 文件... + + + 输入消息... + [+] [📷] [✂] + + ↑ +