From 88f68c7ef0201e90657ca8a522ba8ffa9d743d25 Mon Sep 17 00:00:00 2001 From: yi-ge Date: Sat, 19 Sep 2026 21:37:36 +0800 Subject: [PATCH] docs: sync English interface and conversation enhancements --- .../01-interface/01-layout-overview.md | 2 + .../01-interface/07-feature-entry.md | 6 ++ .../02-conversations/07-markdown-rendering.md | 54 +++++++++++++ .../08-exporting-conversations.md | 25 ++++++ .../02-conversations/09-context-control.md | 22 +++++ .../02-conversations/10-rewind-checkpoints.md | 22 +++++ .../conversations/context-lifecycle-en.svg | 52 ++++++++++++ .../conversations/rewind-branch-en.svg | 44 ++++++++++ .../interface/three-column-layout-en.svg | 81 +++++++++++++++++++ 9 files changed, 308 insertions(+) create mode 100644 static/img/user-guide/conversations/context-lifecycle-en.svg create mode 100644 static/img/user-guide/conversations/rewind-branch-en.svg create mode 100644 static/img/user-guide/interface/three-column-layout-en.svg diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/01-interface/01-layout-overview.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/01-interface/01-layout-overview.md index 7130a699..8be29f72 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/01-interface/01-layout-overview.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/01-interface/01-layout-overview.md @@ -10,6 +10,8 @@ DesireCore uses a **single-window three-column layout**, where all functions are ## Layout Diagram +![DesireCore three-column layout](/img/user-guide/interface/three-column-layout-en.svg) + ``` +--------------------------------------------------------------+ | +------+--------------+----------------------------------+ | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/01-interface/07-feature-entry.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/01-interface/07-feature-entry.md index 9d6e6bfd..8a3a9b48 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/01-interface/07-feature-entry.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/01-interface/07-feature-entry.md @@ -1,3 +1,9 @@ +--- +title: Feature Entry Points and Operation Paths +description: Get to know DesireCore’s three main areas (Conversation Interface, Resource Manager, and Applications and Services) and common operation paths. +keywords: [feature entry points, operation paths, conversation interface, resource manager, applications and services, getting started] +--- + # Feature Entry Points and Operation Paths First time using DesireCore? Not sure where to start? diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/07-markdown-rendering.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/07-markdown-rendering.md index 08ff36b1..7fcbf78b 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/07-markdown-rendering.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/07-markdown-rendering.md @@ -33,6 +33,60 @@ DesireCore supports common LaTeX syntax: Long formulas scroll inside the message bubble instead of breaking the layout. +## Rendering Examples + +The following examples show common Markdown elements in Companion replies: + +**Code blocks** (with syntax highlighting and one-click copying): + +````markdown +```python +def hello(): + print("Hello, DesireCore!") +``` +```` + +**Tables** (automatically aligned, with horizontal scrolling on narrow screens): + +```markdown +| Feature | Status | +|---------|--------| +| Rendering | ✅ | +| Copying | ✅ | +``` + +**Mermaid diagrams** (automatically rendered as visual diagrams): + +````markdown +```mermaid +graph LR + A[User input] --> B[Companion processing] + B --> C[Return results] +``` +```` + +**Math formulas** (typeset with KaTeX): + +```markdown +Inline: $E = mc^2$ +Block: $$\int_0^1 x^2 dx = \frac{1}{3}$$ +``` + +## Troubleshooting Rendering + +| Issue | What Happens | What to Do | +|-------|--------------|------------| +| Invalid Mermaid syntax | The original code block is kept instead of a diagram | Ask the Companion to correct the syntax and output it again | +| Invalid LaTeX formatting | The raw LaTeX source is displayed | Check that the `$` delimiters are paired | +| Inconsistent table column counts | Some columns may be misaligned | Make sure each row has the same number of `\|` characters | +| Unclosed code block | Subsequent content is treated as code | Make sure opening and closing triple backticks (`` ``` ``) are paired | + +:::tip Practical Tips +- If a Companion's Mermaid diagram does not render, tell it: "The Mermaid syntax is invalid. Please fix it." +- To copy diagram source, use "Copy Markdown" instead of "Copy". +- Long formulas scroll horizontally inside the message bubble without breaking the layout. +::: + ## Copying | Action | Result | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/08-exporting-conversations.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/08-exporting-conversations.md index 1190ffa3..1deecaee 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/08-exporting-conversations.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/08-exporting-conversations.md @@ -30,3 +30,28 @@ Markdown is best when you want to keep editing. PDF is best for sharing with peo Desktop PDF export uses the unified document rendering pipeline and preserves common Markdown structures such as headings, tables, code blocks, images, and formulas. +## Step-by-Step Instructions + +### Export a Full Conversation + +1. Open the target Companion's chat. +2. Click the "More" button (three dots) on the right side of the chat header. +3. Choose "Export Conversation" from the menu. +4. In the export settings panel, select the full-history scope, a format (Markdown / PDF), and content options. +5. Confirm the export. The file is saved to your system's Downloads folder or the location you specify. + +### Export Selected Messages + +1. Choose "Multi-select" from the chat header's "More" menu to enter multi-select mode. +2. Check the messages you want to export using the checkboxes on their left. +3. Click "Export" in the bottom action bar. +4. Choose a format and content options, then confirm. + +:::tip Export Scope +Multi-select export groups selected messages by run (a complete request-response cycle) to preserve context. For example, selecting a Companion reply also includes its corresponding user question and tool calls in the export. +::: + +## Next Steps + +- Learn about searching and locating messages in [Chat History](./05-chat-history.md). +- Use [Context Control](./09-context-control.md) to manage long conversations. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/09-context-control.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/09-context-control.md index 77f0b9aa..779dda40 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/09-context-control.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/09-context-control.md @@ -8,6 +8,8 @@ keywords: [context, compaction, /new, /compact, CompactSession, long conversatio DesireCore keeps the visible conversation history, but each model call has a finite context window. Context control lets long conversations continue without deleting the visible history. +![Context lifecycle diagram](/img/user-guide/conversations/context-lifecycle-en.svg) + ## `/new` `/new` creates a new context boundary in the same conversation. @@ -32,3 +34,23 @@ When a conversation approaches the model's context limit, DesireCore can compact Some agents can call `CompactSession` themselves when they detect a long-running task. It keeps the UI history intact and only changes what future model calls read. +## Practical Recommendations + +| Scenario | Recommended Action | Reason | +|----------|--------------------|--------| +| Switching topics, such as from coding to the weather | `/new` | Prevent old task context from interfering with the new topic | +| Working on a long task, such as writing a 20-page document | `/compact` | Free up context space while retaining a task summary | +| The conversation is long but still about the same task | Wait for automatic compaction | The system compacts context at an appropriate time | +| The agent went in the wrong direction and you want to try again | Rewind | Return to a checkpoint before the mistake | +| You no longer need the conversation at all | Clear chat history | Irreversible; use with care | + +:::info Choosing Between `/new` and `/compact` +- **`/new`**: Breaks the context connection with earlier content. Use it when the next topic is unrelated to the previous discussion. +- **`/compact`**: Keeps a summary of earlier content. Use it when you are continuing the same task but the conversation has become too long. + +If you are unsure, prefer `/compact`: it preserves the task context in a summary. +::: + +:::tip Memory Is Unaffected by Compaction +A Companion's long-term memory (knowledge acquired through teaching or automatic learning) is stored in AgentFS and is unaffected by context compaction. Learned rules and preferences remain in effect after `/new` or `/compact`. +::: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/10-rewind-checkpoints.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/10-rewind-checkpoints.md index 1973a1da..2e29c80e 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/10-rewind-checkpoints.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/02-conversations/10-rewind-checkpoints.md @@ -29,3 +29,25 @@ Before applying, DesireCore shows an impact preview. The old branch remains in h Rewind restores DesireCore-managed local state. It usually cannot undo external side effects such as sent emails, pushed commits, external API calls, or third-party approvals. +## How Branching Works + +Rewind creates a new execution branch from a checkpoint while preserving the existing history: + +![Rewind branching diagram](/img/user-guide/conversations/rewind-branch-en.svg) + +- **The old branch is preserved**: All messages and operation records from before the rewind remain in history. +- **A new branch is created**: After confirmation, the system starts a new execution path from the target checkpoint. +- **Repeated rewinds**: Each rewind creates another branch, forming a structure similar to Git branches. + +```text +Timeline: + Message 1 → Message 2 → Message 3 → Message 4 (original path) + ↘ + Message 3' → Message 4' (after the first rewind) + ↘ + Message 3'' → ... (after the second rewind) +``` + +:::tip Safety Net +Preserving old branches makes it easier to try another path. If the new path is unsatisfactory, rewind again to an earlier checkpoint or refer to content in the old branch. The external side-effect limits described above still apply. +::: diff --git a/static/img/user-guide/conversations/context-lifecycle-en.svg b/static/img/user-guide/conversations/context-lifecycle-en.svg new file mode 100644 index 00000000..106f7526 --- /dev/null +++ b/static/img/user-guide/conversations/context-lifecycle-en.svg @@ -0,0 +1,52 @@ + + + + + + + + + Context Lifecycle + + + + + + Message 1 + + Message 2 + + Message 3 + + /compact + + Message 4 + + Message 5 + + /new + + + Compacted Summary + Key points from messages 1–3 + Original content remains available + + + Active Context + Summary + recent messages + What the model actually reads + + + New Boundary + Earlier content + no longer read + + + Command Comparison + + /compact — Summarize older messages to preserve continuity during a long task + + /new — Start fresh context when switching to an unrelated topic + + Auto-compaction — Triggered near the context limit; no manual action needed + diff --git a/static/img/user-guide/conversations/rewind-branch-en.svg b/static/img/user-guide/conversations/rewind-branch-en.svg new file mode 100644 index 00000000..a27b20dd --- /dev/null +++ b/static/img/user-guide/conversations/rewind-branch-en.svg @@ -0,0 +1,44 @@ + + + + + + + + + + Rewind Branching + + + + Message 1 + + Message 2 + + Message 3 + + Message 4 + + Message 5 + + + Rewind point + + + + + Message 3' + + Message 4' + New path + + + New branch after the first rewind + + + Key Features + • The old branch (green) remains in history + • The new branch (blue) develops from the rewind point + • Rewind repeatedly to create more branches + • Restore files, memory, skills, and other state + diff --git a/static/img/user-guide/interface/three-column-layout-en.svg b/static/img/user-guide/interface/three-column-layout-en.svg new file mode 100644 index 00000000..fb5b0a67 --- /dev/null +++ b/static/img/user-guide/interface/three-column-layout-en.svg @@ -0,0 +1,81 @@ + + + + + + + + + + + + + DesireCore Three-Column Layout + + + NavRail + 62px + + Logo + + Chat + + Relationships + + Resources + + Apps + + Marketplace + + 🔔 + + ⚙ + + + Conversation List + 290px + + Search agents... + + + DesireCore + Let me analyze this... + 11:05 + + + Legal Assistant + Contract reviewed... + Yest. + + + Data Analyst + Report ready... + Mon + + + Chat Area + flex-1 adaptive + + + + DesireCore + + Online + [Immersive] [Profile] [More] + + + Hello! How can I help? + + Please analyze this report. + + Let me read and analyze the file... + + Read file... + + + Type a message... + [+] [📷] [✂] + + ↑ +