dsh-mnemon 0.1.2 → 0.1.4

package/docs/zh-CN/README.md

@@ -1,40 +1,48 @@
 # dsh-mnemon 文档中心
 
-**简体中文** | [English](../en/README.md) | [返回项目首页](../../README.md)
+**简体中文** | [English](../en/README.md) | [项目首页](../../README.zh-CN.md)
 
-这组文档以当前代码实现为事实源。根 README 用于快速理解；这里展开设计理由、边界、事务流程、配置和运维方式。
+这里按“你现在要完成什么”组织文档。第一次使用从快速开始进入；需要理解页面时看 UI 指南；只有在部署、集成或开发时才需要进入参考文档。
 
-## 建议阅读路径
+## 新用户路径
 
-1. [项目介绍](./project-overview.md)：项目定位、Mnemon 与 DSH 的集成边界、三层模型、总体架构与适用场景。
-2. [快速开始](./getting-started.md)：安装、首次配置与基本验证。
-3. [架构设计](./architecture.md)：DSH Host、Web Client、控制层、子 Agent 与 Mnemon CLI 的边界。
-4. [存储与三层记忆模型](./storage-model.md)：Runtime、Documents、Memory Spaces 的语义和目录结构。
-5. [生命周期与核心流程](./workflows.md)：召回、写入、后台审查、容量整理和归档。
-6. [配置参考](./configuration.md)：全部配置、默认值、优先级和 provider 要求。
-7. [WebUI、工具、命令与 RPC](./interfaces.md)：所有用户与模型入口。
-8. [运维、安全与故障排查](./operations.md)：锁、权限、备份、恢复和已知限制。
-9. [开发与验证](./development.md)：模块结构、测试、构建和发布检查。
-10. [Roadmap](./roadmap.md)：尚未完成的可靠性、运维和国际化工作。
-11. [安全策略](../../SECURITY.md)：支持版本、漏洞私密报告渠道与范围。
+1. [快速开始](./getting-started.md)：安装 Mnemon 与插件，选择存储范围，完成第一次验证。
+2. [Sidebar 与对话交互指南](./ui-guide.md)：认识状态、运行时、记忆体、档案和对话内入口。
+3. [项目介绍](./project-overview.md)：理解三层模型、跨 Agent 共享边界、读写边界与完整流转。
 
-## 术语
+## 按任务查找
 
-| 中文 | English | 含义 |
-|---|---|---|
-| 记忆体 | Memory Space | 一个 Mnemon 原生命名 Store 及其独立 `mnemon.db` |
-| 运行时热记忆 | Runtime Memory / hot memory | 每轮直接注入的紧凑用户画像和工作记忆 |
-| 项目档案 | Project Documents | 由插件托管的完整 Markdown 项目知识 |
-| 活跃档案 | Active Document | 参与默认近场检索的档案 |
-| 归档 | Archive | 已建立长期索引、不计 active 容量的原文 |
-| 沉淀 | Distill / supervised writeback | 经 LLM 判断、查重和路由后的持久写入 |
-| 召回 | Recall | 从已激活记忆体读取历史证据 |
+| 我想要…… | 文档 |
+|---|---|
+| 决定一条信息应放在哪一层 | [存储与三层记忆模型](./storage-model.md) |
+| 让 DSH 与其他 Mnemon-enabled Agent 共享长期记忆 | [项目介绍：跨 Agent 共享边界](./project-overview.md#跨-agent-共享边界) · [配置参考：共享范围](./configuration.md#选择跨-agent-共享范围) |
+| 了解每轮注入、召回、沉淀和归档何时发生 | [生命周期与核心流程](./workflows.md) |
+| 切换 Sidebar / Buildin、全局 / 工作区 / 自定义目录 | [配置参考](./configuration.md) |
+| 理解工作区“查看目录”与 Agent“实际生效目录” | [UI 指南：工作区模式](./ui-guide.md#工作区模式查看与执行分离) |
+| 检查或更新 Mnemon 与 dsh-mnemon | [运维指南：版本检查与更新](./operations.md#版本检查与更新) |
+| 备份、恢复或迁移完整记忆目录 | [运维指南：备份与恢复](./operations.md#备份与恢复) |
+| 排查召回为空、目录未对齐、CLI 或 Provider 问题 | [运维、安全与故障排查](./operations.md#故障排查) |
+| 使用模型工具、`/mnemon` 命令或内部 RPC | [接口参考](./interfaces.md) |
+| 理解 Host、worker、控制面与数据面 | [架构设计](./architecture.md) |
+| 修改代码、截图、测试或发布 | [开发与验证](./development.md) |
+| 查看下一阶段计划 | [Roadmap](./roadmap.md) |
+
+## 核心术语
 
-品牌名、命令、工具名、配置键、RPC endpoint 和代码符号保持原样，不翻译。
+| 中文 | 英文 / 代码名 | 含义 |
+|---|---|---|
+| 记忆系统 | Memory System | dsh-mnemon 在 DSH 中的完整入口 |
+| 运行时记忆 | Runtime Memory | 每轮注入的 USER / MEMORY 热记忆 |
+| 档案 | Project Documents | 受管、可检索、保留完整 Markdown 叙事的项目知识 |
+| 记忆体 | Memory Space | 独立、可激活、按需召回的长期 Mnemon Store |
+| 跨 Agent 共享 | Cross-agent memory sharing | 多个 Mnemon-enabled Agent 使用同一根和 Store，共享长期记忆而非完整 DSH 上下文 |
+| 沉淀 | Remember / Distill | 把候选交给受监督子 Agent 判断、查重与写入 |
+| 召回 | Recall | 从已激活记忆体按需取回有界证据 |
+| 归档 | Archive | 先建立冷引用，再把不常用档案迁出 active 层 |
 
 ## 文档边界
 
-- 当前用户指令和仓库事实高于历史记忆。
-- `state/` 目前是预留目录；后台审查水位仍只存在于 Host 进程内。
-- 主要 Web 工作台已提供中文和英文；命令输出、工具卡和部分后端诊断尚未全部国际化。
-- `docs/sedimentation-research.md` 是历史研究记录，不是规范或用户手册。
+- 用户文档以 v0.1.4 的 Sidebar 默认体验为主，同时说明 Buildin 兼容形态。
+- 架构图表达稳定执行边界，不是实时监控面板；实时数量与版本以“状态”页为准。
+- RPC 是 Host 与插件客户端之间的内部协议，不承诺稳定外部 API。
+- 当前没有正式固定的 DSH / Mnemon 版本矩阵；升级前应备份并在隔离目录验证。

package/docs/zh-CN/architecture.md

@@ -8,14 +8,16 @@
 
 - DSH 提供主 Agent、生命周期事件、subagent provider、工具、命令、设置和 Web 扩展点；
 - 插件提供三层知识控制面、路由策略、事务屏障和 UI；
-- 本地 `mnemon` CLI 提供命名 Store、SQLite 持久化、四类图、召回、关系和软删除。
+- 本地 `mnemon` CLI 提供命名 Store、SQLite 持久化、四类图、召回、关系和软删除，并形成与其他 Mnemon-enabled Agent 共享长期记忆的数据边界。
 
 ## 组件图
 
-[![dsh-mnemon 运行时架构](./assets/project-architecture.svg)](./assets/project-architecture.svg)
+[![dsh-mnemon 运行时架构](../assets/diagrams/zh-CN/project-architecture.svg)](../assets/diagrams/zh-CN/project-architecture.svg)
 
 图中实线表示确定性数据或控制路径，紫色虚线表示 LLM 监督路径。Runtime Memory 和 Documents 直接使用受管文件；只有 Memory Spaces 通过 `MnemonRunner` 调用本地 Mnemon CLI。点击图片可以查看原始 SVG。
 
+因此跨 Agent 互操作只发生在图中的 Memory Spaces：共享的是 Mnemon Store 内的长期记忆与关系，不是 DSH 的会话上下文、Runtime 投影或 Documents 控制面。插件不会把数据主动推送到其他 Agent；参与方通过对齐本地 Mnemon 根和 Store 来共享。
+
 ## Host 组合根
 
 `src/index.ts::apply()` 按以下顺序组装插件：
@@ -51,6 +53,8 @@ root Agent calls mnemon_recall
 
 长期语义写入、关系、软删除以及记忆体创建/更新/合并采用相同模式。运行时记忆和 Documents 的普通变更先经过 coordinator，但通常由确定性控制层直接提交；只有容量维护或归档需要额外 worker。
 
+记忆体目录的物理删除是单独的确定性危险操作：WebUI 必须先展示二次确认，随后经 loopback 写 RPC 调用 Mnemon 原生 `store remove`；只有 CLI 删除成功后才移除目录登记。
+
 ## 两类子 Agent
 
 ### `spawn`

package/docs/zh-CN/configuration.md

@@ -12,7 +12,7 @@ $DSH_HOME/settings.yaml
 
 默认通常是 `~/.dsh/settings.yaml`。当前全部配置标记为 `live` 生效；保存后会先初始化候选运行图，再原子切换 Host 服务。
 
-Web 设置卡编辑 `displayMode`、`storageScope` 和 `dataDir`。其他高级项需要直接修改 YAML。
+Web 设置页编辑 `displayMode`、`storageScope`、`dataDir`，以及 `mnemon-ui` 下的回合记忆条和存入记忆按钮；同页还提供当前有效目录的 ZIP 导入 / 导出。其他高级项需要直接修改 YAML。
 
 ## 完整示例
 
@@ -52,9 +52,8 @@ mnemon:
 | `idleReviewMs` | `30000` | 5000–600000 ms | 达标后需要连续空闲的时间 |
 | `tabEnabled` | `true` | boolean | 是否挂载 `displayMode` 指定的 Web 入口；关闭后 Host RPC、命令和 Agent 工具保持注册 |
 | `writeEnabled` | `true` | boolean | 是否暴露语义写工具、写 RPC 和写命令 |
-| `mnemon-ui.toolviews` | `false` | boolean | 对话内记忆工具卡（`mnemon_*` 调用的记忆风格卡片）；默认关闭（opt-in），**保存后实时生效** |
-| `mnemon-ui.turnBar` | `false` | boolean | 回合尾记忆活动条；默认关闭（opt-in），**保存后实时生效** |
-| `mnemon-ui.saveAction` | `false` | boolean | 已定稿助手回复旁的「存入记忆」按钮；默认关闭（opt-in），**保存后实时生效** |
+| `mnemon-ui.turnBar` | `true` | boolean | 回合尾记忆活动条；默认开启，**保存后实时生效** |
+| `mnemon-ui.saveAction` | `true` | boolean | 已定稿助手回复旁的「存入记忆」图标与确认弹窗；默认开启，**保存后实时生效** |
 
 `mnemon` Host/存储命名空间和 `mnemon-ui` 浏览器呈现命名空间都实时生效。存储根只会在新运行图初始化成功后原子切换；旧版 `mnemon.conversationInteraction` 仍会作为迁移默认值读取，但新保存只写入 `mnemon-ui`。
 
@@ -67,7 +66,7 @@ MNEMON_DATA_DIR when non-empty
   otherwise ~/.mnemon
 ```
 
-适合希望多个工作区共享 Runtime、Documents 和 Memory Spaces 的用户。
+适合希望多个工作区共享 Runtime、Documents 和 Memory Spaces 的用户；其他 Mnemon-enabled Agent 使用相同根时，也可以共享其中的 Mnemon Memory Spaces。
 
 ### `workspace`
 
@@ -88,6 +87,16 @@ mnemon:
 
 也允许 `~` 和 `~/...`。相对路径会被拒绝。
 
+### 选择跨 Agent 共享范围
+
+| 目标 | 推荐范围 | 说明 |
+|---|---|---|
+| 本机多个 Agent 共享长期记忆 | `global` | 各方统一使用 `~/.mnemon` 或同一个 `MNEMON_DATA_DIR` |
+| 多个 Agent 共享指定数据根 | `custom` | 各方显式配置同一个绝对目录，便于隔离和备份 |
+| 只在一个项目内共享 | `workspace` | 各方都需要把 Mnemon 根对齐到该项目的 `<workspace>/.mnemon` |
+
+只有 `data/<store>/mnemon.db` 中的 Mnemon 长期层具备原生跨 Agent 互操作性。Runtime、Documents、DSH 的激活状态和 UI 元数据仍属于 dsh-mnemon 管理范围。
+
 ## CLI 发现优先级
 
 ```text
@@ -173,7 +182,7 @@ routingGuidance=false
 
 ## 展示形态与 `tabEnabled` 界面开关
 
-`displayMode=sidebar`（默认）会挂载“记忆系统”侧边栏入口和独立主内容区工作台；`displayMode=buildin` 会改为注册原有的 DSH `conversation.view` 内嵌标签页。设置页保存后会先卸载当前入口再挂载目标入口，因此两种形态不会同时出现。
+`displayMode=sidebar`（默认）会挂载“记忆系统”侧边栏入口和独立主内容区工作台，并使用无 Mnemon Logo 的 DSH 官方风格极简皮肤；`displayMode=buildin` 会改为注册原有的 DSH `conversation.view` 内嵌标签页并保持既有视觉。两者共享功能工作台，但外观定义隔离。设置页保存后会先卸载当前入口再挂载目标入口，因此两种形态不会同时出现。
 
 `tabEnabled=false` 会实时移除当前形态的 Web 入口。为避免运行中的 Agent 或命令因界面设置变化而失效，Host RPC、命令和工具不会随展示形态或总开关卸载。
 

package/docs/zh-CN/development.md

@@ -106,10 +106,29 @@ local link installation
 7. Documents：创建、检索、更新、人工归档和原项目文件不变。
 8. 评分审查：轻任务不触发；达标后等待 idle；新 turn 能取消并保留水位。
 9. 只读：写工具、写命令和写 RPC 被拒绝，读取仍可用。
-10. 状态和浏览器控制台：无未处理错误或警告。
+10. Sidebar：四个一级标签、记忆体四个二级标签、固定页头、筛选与加载更多均正常。
+11. 对话内交互：本回合记忆只在已完成且有活动的回合出现；跳转目标正确；存入记忆取消不写入。
+12. 设置：Sidebar / Buildin、存储范围与两个对话开关保存后实时生效，不需要刷新。
+13. ZIP：导出后可预检，并能在隔离 custom 根完成合并恢复；损坏 checksum 必须拒绝。
+14. 版本：检查不会安装；link / 手工来源不显示不安全更新；更新完成后自动重新检查状态。
+15. 状态和浏览器控制台：无未处理错误或警告。
 
 容量极限、CLI 超时、revision 冲突和 Host 重启应在专用故障注入环境验证。
 
+## 维护文档视觉素材
+
+公开 UI 截图统一位于 `docs/assets/screenshots/`，中英文文档复用同一组实机画面；语言相关架构图分别保存在 `docs/assets/diagrams/zh-CN/` 与 `docs/assets/diagrams/en/`。界面结构、主要文案或默认行为变化时：
+
+1. 使用真实 DSH Web profile，但先检查画面中没有 token、凭据或不应公开的个人数据；
+2. 只做查看、筛选、展开与打开弹窗等可逆交互；需要展示写入前流程时停在最终确认之前；
+3. 覆盖同职责截图，避免按版本不断累积文件名；只有新增用户任务时才增加素材；
+4. 同步 README 海报、GIF / MP4 演示和 `ui-guide.md`；
+5. 检查 PNG / JPEG 扩展名与真实编码一致，并在原始分辨率下确认文字可读；
+6. 删除已无引用、展示旧 Buildin 布局或术语过时的截图；
+7. 运行链接与图片检查，再人工打开中英文 README 和 UI 指南。
+
+README 演示资源位于 `docs/assets/media/dsh-mnemon-memory-system-demo.*`。演示应覆盖状态、运行时、记忆体、档案和对话内确认，但不要用自动化真正提交记忆、更新组件或更改设置。
+
 ## 修改 subagent schema
 
 DSH structured output 只支持一个紧凑 JSON Schema 子集：
@@ -142,7 +161,8 @@ Runtime、Documents 和 Memory Space registry 都带版本字段或固定结构
 - 保持命令、配置键、路径和代码符号完全一致；
 - 使用相对路径互链对应语言页面；
 - 架构总览优先使用可访问、无脚本和无外部资源的 SVG；目录树、命令、公式与短协议仍使用可复制的 `text` / ASCII；
-- 根 README 只保留摘要，把细节放到单一权威 docs 页面。
+- 根 README 只保留摘要，把细节放到单一权威 docs 页面；
+- 所有用户可感知界面变化同步检查 `ui-guide.md`、`getting-started.md`、`configuration.md` 与 `operations.md`。
 
 Web locale 变更时，中文键集合仍是类型事实源；英文词典必须满足 `Record<MnemonKey, string>`，并保持占位符一致。
 
@@ -151,7 +171,7 @@ Web locale 变更时，中文键集合仍是类型事实源；英文词典必须
 ```text
 [ ] pnpm run verify
 [ ] review source and generated lib diffs
-[ ] validate package file list includes README.en.md and docs
+[ ] validate package file list includes README.md, README.zh-CN.md, docs/assets and bilingual docs
 [ ] install the built/local bundle into an isolated Web profile
 [ ] run real Mnemon CLI and WebUI smoke tests
 [ ] verify Chinese and English workspaces
@@ -160,7 +180,7 @@ Web locale 变更时，中文键集合仍是类型事实源；英文词典必须
 [ ] back up any data root used for upgrade testing
 ```
 
-`package.json.files` 当前发布 `lib`、patch、两份根 README、双语公开 docs 和 License；历史研究台账不进入安装包。
+`package.json.files` 当前发布 `lib`、patch、两份根 README、统一管理的文档视觉素材、双语公开 docs 和 License。
 
 ## 发布到 npm
 

package/docs/zh-CN/getting-started.md

@@ -2,33 +2,19 @@
 
 **简体中文** | [English](../en/getting-started.md) | [文档中心](./README.md)
 
+本页从空白环境走到第一次可验证召回。默认采用 Sidebar 和全局存储；如果你已经安装完成，可直接跳到[首次验证](#6-完成第一次验证)。
+
 ## 1. 前置条件
 
 你需要：
 
 - 一个可以启动的 DSH Web profile；
 - 本地可执行的 `mnemon` CLI；
-- 可用于受限子任务的 DSH subagent provider。
-
-provider 的准确要求如下：
+- 一个可用于隔离记忆任务的 DSH subagent Provider。
 
-```text
-regular semantic operations
-  -> prefer provider named "spawn"
-  -> may fall back to another compatible provider
-
-scored background review
-  -> requires provider named "fork"
-  -> inheritsParentContext = true
-
-both paths require
-  -> outputSchema
-  -> toolFilter
-  -> persona
-  -> depthLimit
-```
+普通语义任务优先使用名为 `spawn` 的 Provider，并要求 `outputSchema`、`toolFilter`、`persona` 与 `depthLimit`。可选的评分后台审查还要求名为 `fork`、且 `inheritsParentContext=true` 的 Provider。缺少 `fork` 不影响确定性页面读取和普通手动操作。
 
-插件没有在代码中声明固定的 DSH/Mnemon 最低版本矩阵。**已验证基线**：`dsh-mnemon` 0.1.0 在 `@deepseek-ai/dsh` 0.1.0-rc.6（2026-08-13 快照）的 live web profile 上实测通过，最后验证日期 2026-08-14。升级前应先在隔离数据目录中运行本页的验证步骤。
+项目当前不声明固定的 DSH / Mnemon 最低版本矩阵。本文与截图以 dsh-mnemon v0.1.4 为基线；升级前先备份，并在隔离目录重复本页验证。
 
 ## 2. 安装 Mnemon
 
@@ -38,7 +24,7 @@ macOS 推荐 Homebrew Cask：
 brew install --cask mnemon-dev/tap/mnemon
 ```
 
-macOS 或 Linux 也可以通过 Go 安装：
+macOS 或 Linux 也可通过 Go 安装：
 
 ```sh
 go install github.com/mnemon-dev/mnemon@latest
@@ -50,11 +36,9 @@ go install github.com/mnemon-dev/mnemon@latest
 mnemon --version
 ```
 
-如果还要直接检查上游 Store，可以运行 `mnemon status`。该命令会打开有效 Store，可能初始化默认数据或执行迁移；不要把它当作完全无副作用的安装探测。
+如果 DSH 无法从 `PATH` 找到它，可设置 `MNEMON_CLI_PATH`，或把绝对路径写入 `mnemon.cliPath`。`mnemon status` 会打开有效 Store，可能初始化数据或执行上游迁移，不要把它当作完全无副作用的安装探测。
 
-如果 DSH 无法从 `PATH` 找到它，可以设置 `MNEMON_CLI_PATH`，或在 `mnemon.cliPath` 中配置绝对路径。
-
-## 3. 安装插件
+## 3. 安装 dsh-mnemon
 
 安装到 Web profile：
 
@@ -62,104 +46,110 @@ mnemon --version
 dsh plugin --profile web add dsh-mnemon
 ```
 
-未发布到 npm 的预发布版本可从 git 安装：
+开发检出使用绝对路径：
 
 ```sh
-dsh plugin --profile web add "github:omdsh-dev/dsh-mnemon"
+dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
 ```
 
-本地开发检出：
+然后启动或重启 profile：
 
 ```sh
-dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
+dsh --profile web
 ```
 
-插件包中的 `cordis.patch.yml` 会挂载 Host 插件；Web client bundle 会注册会话工作台和插件设置卡。
-
-### 升级与卸载
-
-`dsh plugin` 是 pnpm 转发器，在 profile 目录下执行：
+升级与卸载：
 
 ```sh
-# 升级
 dsh plugin --profile web update dsh-mnemon
-
-# 卸载（同时从 profile 移除其 bundle 注册）
 dsh plugin --profile web remove dsh-mnemon
 ```
 
-卸载不会删除记忆数据：`global` 范围数据留在 `~/.mnemon`，`workspace` / `custom` 范围数据留在对应目录，重新安装后继续可用。
+卸载只移除插件注册，不删除全局、工作区或自定义目录中的记忆数据。
 
-临时停用自动读写而不卸载：在插件配置里关闭 `writebackMode` / `recallMode` / `lifecycleEnabled`（见[配置参考](./configuration.md)的“开关交互”）。只想隐藏 Web 工作台时设置 `tabEnabled=false`；Host RPC、命令和 Agent 工具保持可用。
+## 4. 选择入口与存储位置
 
-## 4. 选择存储范围
+打开“设置 → 记忆系统”：
 
-启动 DSH Web profile：
+[![记忆系统设置：展示形态、存储位置、对话界面与备份](../assets/screenshots/settings-memory-system.png)](../assets/screenshots/settings-memory-system.png)
 
-```sh
-dsh --profile web
-```
+### 展示形态
 
-在“设置 -> 记忆系统”独立配置页先选择展示形态：默认 `sidebar` 使用左侧栏独立工作台，`buildin` 使用原有对话区内嵌标签页；保存后实时切换。再选择存储范围：
+- **Sidebar**（默认）：从 DSH 左侧栏进入独立工作台；适合绝大多数用户。
+- **Buildin**：使用原有对话区标签页，并保留既有视觉。
+
+### 存储位置
 
 | 范围 | 根目录 | 适合场景 |
 |---|---|---|
-| `global` | `MNEMON_DATA_DIR` 或 `~/.mnemon` | 多个工作区共享同一套记忆 |
-| `workspace` | 每个 DSH 工作区根目录下的 `.mnemon` | 项目隔离与跨工作区查看 |
-| `custom` | `dataDir` | 显式磁盘、挂载卷或专用数据目录 |
+| **全局**（默认） | `MNEMON_DATA_DIR` 或 `~/.mnemon` | 多个工作区共享同一套记忆 |
+| **工作区** | `<workspace>/.mnemon` | 项目隔离，并允许在工作台切换查看其他工作区 |
+| **自定义** | `dataDir` | 专用磁盘、挂载卷或明确的数据目录 |
 
-设置写入 `$DSH_HOME/settings.yaml`，保存后实时应用。切换范围不会搬运旧数据；需要保留时先停止写入并通过整体 ZIP 备份迁移。
+点击保存后会先初始化新运行图，再原子切换 Host；页面自动清理旧状态并重新读取，无需刷新浏览器。切换范围不会自动迁移、合并或删除旧数据。
 
-选择 `workspace` 后，工作台顶部可以切换要查看的工作区。这个选择只决定工作台正在查看和维护哪一套数据；Agent 实际使用的目录始终跟随当前会话。两者不同时会出现全局提示，可一键对齐。
+在工作区模式下，工作台选择器只决定“正在查看哪套数据”；Agent、工具与生命周期实际使用的目录始终跟随当前会话。两者不一致时顶部会提示并提供一键对齐。
 
-## 5. 创建第一个记忆体
+## 5. 打开 Sidebar 工作台
 
-使用默认 `sidebar` 时点击 DSH 左侧栏的“记忆系统”入口；使用 `buildin` 时打开对话区的“记忆系统”标签页：
+点击左侧栏“记忆系统”，先查看“状态”：
 
-1. 打开“记忆体”页。
-2. 创建一个主题明确的记忆体，例如“项目决策”。
-3. description 应说明“哪些内容属于这里，以及什么任务应召回它”。
-4. 开启读取开关，或在第一次写入后让插件自动激活它。
+[![状态页：CLI、版本、运行时、记忆体、档案与存储根](../assets/screenshots/status-overview.png)](../assets/screenshots/status-overview.png)
 
-空白记忆体默认可以保持未激活。激活只控制读取范围；写入可以选择任意已登记记忆体，写入成功后会自动激活目标。
+确认：
 
-## 6. 验证完整链路
+- 右上角显示“已连接”；
+- Mnemon 与 dsh-mnemon 能显示当前版本；
+- 存储根与刚才选择的范围一致；
+- Runtime、Memory Spaces 和 Documents 没有错误提示。
 
-先检查确定性状态：
+如果 Mnemon 不可用，先运行 `command -v mnemon` 与 `mnemon --version`。更多症状见[故障排查](./operations.md#故障排查)。
 
-```text
-/mnemon status
-```
+## 6. 完成第一次验证
 
-再在“沉淀”页提交一条稳定、自包含、未来仍有用的内容。worker 会选择记忆体、查重并返回结构化回执。随后验证：
+### 创建记忆体
 
-```text
-/mnemon recall <一个能命中新内容的聚焦查询>
-```
+1. 打开“记忆体 → 概览”。
+2. 点击“创建记忆体”。
+3. 使用主题明确的名称，例如“项目决策”。
+4. 在说明中写清“哪些内容属于这里，以及什么任务应召回它”。
+5. 开启读取激活开关。
+
+### 沉淀一条测试信息
 
-最后检查：
+点击右上角“沉淀记忆”，填写一条稳定、自包含、未来仍有用且不含秘密的信息。默认不要展开高级选项，让记忆子 Agent 自己选择目标、查重与提炼。
 
-- “记忆体”页能看到已激活记忆体和图谱；
-- “内容”能看到写入项及所属记忆体；
-- “状态”中 CLI、运行时、记忆体目录和 subagent 均正常；
-- 召回结果包含完整 `memoryBodyId` 和记忆 ID。
+只有点击“调度子 Agent 判断并沉淀”才会启动写入；取消弹窗不会改变状态。
 
-## 7. 推荐的第一次真实对话
+### 验证召回
 
-选择一个确实依赖历史决策的问题，而不是要求模型无条件调用记忆工具。预期流程是：
+1. 打开“记忆体 → 检索”。
+2. 输入一个能命中刚才内容的具体问题。
+3. 先用“直接检索”检查原始证据。
+4. 确认结果包含记忆体来源、分类、重要性、分数和 ID。
+
+也可以在对话中运行：
 
 ```text
-user asks a history-dependent question
-  -> pre-step adds a short optional cue
-  -> main Agent decides whether history matters
-  -> recall worker selects active Memory Spaces
-  -> only useful evidence returns to the main Agent
+/mnemon status
+/mnemon recall <聚焦查询>
 ```
 
+## 7. 验证对话内记忆
+
+在一个确实依赖历史信息的问题中，让 Agent 自主判断是否需要召回。完成后：
+
+- 若本轮调用了记忆工具，回复下方会出现“本回合记忆”；
+- 展开后可以看到具体工具名，并点击跳到对应页面；
+- “存入记忆”会先打开可编辑确认弹窗，取消不会写入。
+
+[![本回合记忆与工具跳转](../assets/screenshots/conversation-turn-memory.png)](../assets/screenshots/conversation-turn-memory.png)
+
 普通聊天不应强制召回。当前请求、现有源文件和实时工具结果应优先于历史内容。
 
 ## 8. 下一步
 
-- 阅读[存储模型](./storage-model.md)，再决定 `storageScope`。
-- 阅读[配置参考](./configuration.md)，配置只读模式或关闭生命周期提示。
-- 阅读[运维指南](./operations.md)，建立备份和升级前验证流程。
+- 用 [Sidebar 与对话交互指南](./ui-guide.md) 认识全部页面。
+- 用[存储模型](./storage-model.md)决定信息应进入运行时、档案还是记忆体。
+- 用[配置参考](./configuration.md)设置工作区范围、只读模式或生命周期开关。
+- 用[运维指南](./operations.md)导出第一份 ZIP 备份并建立升级前检查流程。