From 6b93afb2439b0a5b43d13723bf3da9a848c86202 Mon Sep 17 00:00:00 2001 From: yi-ge Date: Sun, 26 Jul 2026 00:00:39 +0800 Subject: [PATCH 1/3] docs: enhance interface & conversations chapters - Add YAML frontmatter to 07-feature-entry.md - Add SVG diagrams: three-column layout, context lifecycle, rewind branch - Enhance 07-markdown-rendering with rendering examples and troubleshooting - Enhance 08-exporting-conversations with detailed operation steps - Enhance 09-context-control with practical guidance and /new vs /compact comparison - Enhance 10-rewind-checkpoints with branch mechanism explanation - Insert image references in layout-overview, context-control, rewind-checkpoints --- .../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 | 26 ++++++ .../02-conversations/09-context-control.md | 23 ++++++ .../02-conversations/10-rewind-checkpoints.md | 23 ++++++ .../conversations/context-lifecycle.svg | 52 ++++++++++++ .../conversations/rewind-branch.svg | 44 ++++++++++ .../interface/three-column-layout.svg | 81 +++++++++++++++++++ 9 files changed, 311 insertions(+) create mode 100644 static/img/user-guide/conversations/context-lifecycle.svg create mode 100644 static/img/user-guide/conversations/rewind-branch.svg create mode 100644 static/img/user-guide/interface/three-column-layout.svg 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/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 文件... + + + 输入消息... + [+] [📷] [✂] + + ↑ + From 657920f7a2ad16f2d77b6cd08f5f6e3bebfeec5a Mon Sep 17 00:00:00 2001 From: yi-ge Date: Tue, 28 Jul 2026 10:30:10 +0800 Subject: [PATCH 2/3] docs(conversations): final P0 optimizations --- REVIEW-interface-conversations.md | 73 +++++++++++++++++++ .../02-conversations/01-sending-messages.md | 2 +- .../02-conversations/02-message-types.md | 4 +- .../02-conversations/05-chat-history.md | 4 +- .../06-managing-conversations.md | 4 +- 5 files changed, 80 insertions(+), 7 deletions(-) create mode 100644 REVIEW-interface-conversations.md diff --git a/REVIEW-interface-conversations.md b/REVIEW-interface-conversations.md new file mode 100644 index 0000000..720102b --- /dev/null +++ b/REVIEW-interface-conversations.md @@ -0,0 +1,73 @@ +# 复盘总结：Interface & Conversations 章节完善（v2） + +## 执行概况 + +- **执行时间**：2026-07-25 ~ 2026-07-26 +- **分支**：`docs/interface-conversations-enhancement` +- **提交哈希**：6b93afb +- **PR**：#36（OPEN，CI 全部通过，MERGEABLE） +- **变更文件数**：9 个（6 个 md 文件修改 + 3 个新增 SVG） +- **新增行数**：311 行 +- **流程**：分支 → 提交 → 推送 → PR（未直接 push main ✅） + +## v1 → v2 变更说明 + +v1（commit 3193ca1）因直接 push main 被远程 force-reset 清除。v2 改用分支 + PR 流程，并做以下调整： +- 将 AI 生成的 PNG 概念图替换为手写 SVG 示意图（与仓库其他章节风格一致、可版本控制） +- 精简图片数量（12→3），仅保留内容增益最大的图 +- 内容增强保持不变（经审阅无捏造信息） + +## 完成事项 + +### ✅ 修复结构问题 +- 为 `07-feature-entry.md` 添加了 YAML frontmatter（title/description/keywords） + +### ✅ 补充薄弱内容 +| 文件 | 补充内容 | +|------|----------| +| 07-markdown-rendering.md | 渲染效果示例（代码块、表格、Mermaid、公式）+ 渲染异常处理表格 + 实用提示 | +| 08-exporting-conversations.md | 详细操作步骤（完整导出 + 多选导出） | +| 09-context-control.md | 实践建议表格 + /new vs /compact 选择指南 + 记忆不受压缩影响说明 | +| 10-rewind-checkpoints.md | 分支机制详细说明（旧分支保留、新分支创建、多次 Rewind 结构） | + +### ✅ 新增 SVG 示意图 +| 文件名 | 对应文档 | 内容 | +|--------|----------|------| +| three-column-layout.svg | 01-layout-overview.md | 三栏布局结构图（暗色主题） | +| context-lifecycle.svg | 09-context-control.md | 上下文生命周期流程图 | +| rewind-branch.svg | 10-rewind-checkpoints.md | Rewind 分支时间线图 | + +### ✅ 插入图片引用 +- 3 个 md 文件中正确插入了对应 SVG 引用（Docusaurus 静态资源路径 `/img/user-guide/...`） + +### ✅ PR 创建与 CI +- PR #36 已创建，描述完整 +- CLA Check ✅ / Vercel Preview ✅ / Vercel Preview Comments ✅ +- 状态：MERGEABLE，等待 review + +## Drawio 检查 + +- 本章节（interface / conversations）中**无 .drawio 文件** ✅ +- 仓库中仅有的 .drawio 位于 `03-use-cases/01-general/assets/`，属于「应用场景」章节，不在本人负责范围 + +## 未完成 / 后续改进 + +| 项目 | 说明 | 优先级 | +|------|------|--------| +| 统一链接格式 | 部分文件用 `./context-control`（无 .md），部分用 `./03-cards.md`，未统一 | 低 | +| 真实界面截图 | 当前为 SVG 示意图，后续可替换为真实产品截图 | 中 | +| 更多章节配图 | 02~06（interface）、01~05（conversations）可按需追加 SVG | 低 | + +## 质量评估 + +- **准确性**：所有内容基于产品实际行为描述，无捏造 ✅ +- **完整性**：主要缺口（薄弱内容 + 关键配图）已补齐 ✅ +- **一致性**：SVG 暗色主题风格统一、frontmatter 格式统一 ✅ +- **可维护性**：SVG 可版本控制、可直接编辑，集中在 static/img/ 下 ✅ +- **流程合规**：分支 + PR，未直接 push main ✅ + +## 经验教训 + +1. **严禁直接 push main** — v1 的提交被 force-reset 清除，工作白费 +2. **SVG 优于 AI 生成 PNG** — 可版本控制、风格统一、文件小、无版权疑虑 +3. **先分析再动手** — v2 精简为 3 张高价值图，比 v1 的 12 张效率更高 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) From c6b082f39f84773fa877d927557ed0ae9fd9e14b Mon Sep 17 00:00:00 2001 From: yi-ge Date: Tue, 28 Jul 2026 11:02:49 +0800 Subject: [PATCH 3/3] chore: remove internal review file from PR --- REVIEW-interface-conversations.md | 73 ------------------------------- 1 file changed, 73 deletions(-) delete mode 100644 REVIEW-interface-conversations.md diff --git a/REVIEW-interface-conversations.md b/REVIEW-interface-conversations.md deleted file mode 100644 index 720102b..0000000 --- a/REVIEW-interface-conversations.md +++ /dev/null @@ -1,73 +0,0 @@ -# 复盘总结：Interface & Conversations 章节完善（v2） - -## 执行概况 - -- **执行时间**：2026-07-25 ~ 2026-07-26 -- **分支**：`docs/interface-conversations-enhancement` -- **提交哈希**：6b93afb -- **PR**：#36（OPEN，CI 全部通过，MERGEABLE） -- **变更文件数**：9 个（6 个 md 文件修改 + 3 个新增 SVG） -- **新增行数**：311 行 -- **流程**：分支 → 提交 → 推送 → PR（未直接 push main ✅） - -## v1 → v2 变更说明 - -v1（commit 3193ca1）因直接 push main 被远程 force-reset 清除。v2 改用分支 + PR 流程，并做以下调整： -- 将 AI 生成的 PNG 概念图替换为手写 SVG 示意图（与仓库其他章节风格一致、可版本控制） -- 精简图片数量（12→3），仅保留内容增益最大的图 -- 内容增强保持不变（经审阅无捏造信息） - -## 完成事项 - -### ✅ 修复结构问题 -- 为 `07-feature-entry.md` 添加了 YAML frontmatter（title/description/keywords） - -### ✅ 补充薄弱内容 -| 文件 | 补充内容 | -|------|----------| -| 07-markdown-rendering.md | 渲染效果示例（代码块、表格、Mermaid、公式）+ 渲染异常处理表格 + 实用提示 | -| 08-exporting-conversations.md | 详细操作步骤（完整导出 + 多选导出） | -| 09-context-control.md | 实践建议表格 + /new vs /compact 选择指南 + 记忆不受压缩影响说明 | -| 10-rewind-checkpoints.md | 分支机制详细说明（旧分支保留、新分支创建、多次 Rewind 结构） | - -### ✅ 新增 SVG 示意图 -| 文件名 | 对应文档 | 内容 | -|--------|----------|------| -| three-column-layout.svg | 01-layout-overview.md | 三栏布局结构图（暗色主题） | -| context-lifecycle.svg | 09-context-control.md | 上下文生命周期流程图 | -| rewind-branch.svg | 10-rewind-checkpoints.md | Rewind 分支时间线图 | - -### ✅ 插入图片引用 -- 3 个 md 文件中正确插入了对应 SVG 引用（Docusaurus 静态资源路径 `/img/user-guide/...`） - -### ✅ PR 创建与 CI -- PR #36 已创建，描述完整 -- CLA Check ✅ / Vercel Preview ✅ / Vercel Preview Comments ✅ -- 状态：MERGEABLE，等待 review - -## Drawio 检查 - -- 本章节（interface / conversations）中**无 .drawio 文件** ✅ -- 仓库中仅有的 .drawio 位于 `03-use-cases/01-general/assets/`，属于「应用场景」章节，不在本人负责范围 - -## 未完成 / 后续改进 - -| 项目 | 说明 | 优先级 | -|------|------|--------| -| 统一链接格式 | 部分文件用 `./context-control`（无 .md），部分用 `./03-cards.md`，未统一 | 低 | -| 真实界面截图 | 当前为 SVG 示意图，后续可替换为真实产品截图 | 中 | -| 更多章节配图 | 02~06（interface）、01~05（conversations）可按需追加 SVG | 低 | - -## 质量评估 - -- **准确性**：所有内容基于产品实际行为描述，无捏造 ✅ -- **完整性**：主要缺口（薄弱内容 + 关键配图）已补齐 ✅ -- **一致性**：SVG 暗色主题风格统一、frontmatter 格式统一 ✅ -- **可维护性**：SVG 可版本控制、可直接编辑，集中在 static/img/ 下 ✅ -- **流程合规**：分支 + PR，未直接 push main ✅ - -## 经验教训 - -1. **严禁直接 push main** — v1 的提交被 force-reset 清除，工作白费 -2. **SVG 优于 AI 生成 PNG** — 可版本控制、风格统一、文件小、无版权疑虑 -3. **先分析再动手** — v2 精简为 3 张高价值图，比 v1 的 12 张效率更高