dsh-mnemon 0.1.2 → 0.1.3

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`。
 
@@ -173,7 +172,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.en.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.3 为基线；升级前先备份，并在隔离目录重复本页验证。
 
 ## 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 备份并建立升级前检查流程。

package/docs/zh-CN/interfaces.md

@@ -2,34 +2,20 @@
 
 **简体中文** | [English](../en/interfaces.md) | [文档中心](./README.md)
 
-## Web 工作台
+本页是集成参考。日常使用请先看 [Sidebar 与对话交互指南](./ui-guide.md)。
 
-`displayMode=sidebar`（默认）通过左侧栏打开独立工作台，`displayMode=buildin` 通过原有 DSH `conversation.view` 内嵌标签页打开同一功能界面。两种形态由设置页实时切换且不会同时挂载。主要 Web 界面跟随 DSH 全局语言和明暗主题。顶部导航分为三组，组间以分隔线呈现：「状态」独立成第一组；「运行时、记忆体、档案」对应三层存储；「沉淀、检索、实体、内容」为读写工具。默认进入「状态」页。
+## 用户界面入口
 
-| 页面 | 用途 | 调用边界 |
-|---|---|---|
-| 状态 | CLI、运行时热记忆、存储域、记忆体、Documents、生命周期和 worker 诊断 | 聚合读取 |
-| 运行时 | 查看和维护 USER / MEMORY 热记忆及容量 | 普通 mutation 确定性；容量维护可启动 worker |
-| 记忆体 | 记忆体目录、激活开关与元信息编辑、多空间实时图谱、节点检查 | 确定性 RPC 读取；开关与元信息编辑为写 RPC |
-| 档案 | 搜索、阅读、创建、更新、归档 Documents | 搜索/编辑走控制层；归档启动 worker |
-| 沉淀 | 让记忆 worker 选择范围、查重并写入；支持高级约束 | `spawn` 语义写入 |
-| 检索 | smart / keyword / basic 直连召回；可选证据限定 Agent 答案 | 直接服务读取；Agent 答案使用无工具 worker |
-| 实体 | 高频实体和实体相关上下文 | 直接服务读取 |
-| 内容 | 无 recall 副作用地浏览已激活记忆体、复制、克隆或软删除 | 图谱读取；删除走 worker |
-
-图谱每 15 秒同步一次，也可以手动刷新。自然布局、均匀重置、拖拽和键盘微调只影响客户端展示，不修改 Mnemon 数据。
-
-### 对话内交互
-
-记忆系统在对话流内以三个 DSH 原生槽位呈现，全部为纯增量注册，不替换任何官方渲染：
-
-| 槽位 | 呈现 | 数据与交互 |
-|---|---|---|
-| `tool.call.toolview`（按工具名 keyed） | 每个 `mnemon_*` 工具调用渲染为记忆风格卡片行：状态点、Mnemon 标、召回/沉淀标题与工具专属摘要；悬停出现「在记忆视图中打开」与「查看轨迹」 | 摘要从调用参数与已定稿结果 JSON 提取（recall/document-search 显示命中数、status 显示引擎健康、bodies 显示目录统计等）；展开显示参数与结果原文；跳转经 `mnemon:anchor` 事件通道落到记忆视图对应页（带查询 seed） |
-| `conversation.chat.turnTail`（chain） | 回合尾动作行上方一行「本回合记忆 · 召回 N · 沉淀 M · 档案检索 K」；展开列出具体工具名，并可跳到状态页 | 通过只读 RPC `turn-activity` 从宿主持久会话日志按 turn 统计 `mnemon_*` 调用；chain `select` 拒绝未完成回合，无记忆活动的回合不渲染任何内容 |
-| `conversation.chat.assistant-actions`（list，id `mnemon-save`） | 已定稿助手回复动作区（反馈按钮旁）的「存入记忆」按钮；点击展开候选面板 | 面板经只读 RPC `assistant-message` 按 messageId 提取消息文本为可编辑候选；提交走既有写 RPC `supervise`（受监督写回：记忆子 Agent 判断、查重、选择记忆体），显示子 Agent 回执；只读部署提前禁用并提示 |
+| 入口 | 默认 | 说明 |
+|---|---:|---|
+| Sidebar | 是 | 左侧栏独立“记忆系统”工作台；状态、运行时、记忆体、档案四个一级标签 |
+| Buildin | 否 | 原有 `conversation.view` 内嵌标签页，保留既有视觉 |
+| 本回合记忆 | 是 | 已完成回合的记忆工具摘要；展开后按工具名跳到对应页面 |
+| 存入记忆 | 是 | 已定稿助手回复旁的操作；确认后调用监督写入 |
+| `/mnemon` | — | 对话命令入口 |
+| 模型工具 | — | Root Agent 的结构化读写入口 |
 
-`turn-activity`、`assistant-message` 为新增只读端点，与既有端点共用同一 Host 通道与错误语义。对话内交互的渲染扩展面契约与后续「正文内联记忆高亮」方案见 Mnemon 档案「dsh-mnemon 对话内记忆交互侦察」。
+Sidebar 与 Buildin 实时互斥挂载，共享功能、数据和 Host 服务。对话内两个入口可在 `mnemon-ui` 设置中分别关闭。
 
 ## 模型工具
 
@@ -37,37 +23,37 @@
 
 | 工具 | 用途 | Root Agent 路径 |
 |---|---|---|
-| `mnemon_memory_bodies` | 读取 Memory Space 目录和统计 | 直接服务 |
-| `mnemon_recall` | 从一个或多个 active spaces 召回 | `spawn` recall worker |
-| `mnemon_related` | 从已知 ID 遍历关系 | `spawn` related worker；root 路径固定请求两跳 |
-| `mnemon_status` | CLI、配置和 active spaces 聚合状态 | 直接服务 |
-| `mnemon_document_search` | 确定性搜索受管 Documents | 直接 Documents 控制层 |
+| `mnemon_status` | CLI、配置、存储与目录聚合状态 | 直接服务 |
+| `mnemon_memory_bodies` | 读取记忆体目录与统计 | 直接服务 |
+| `mnemon_recall` | 从一个或多个 active 记忆体召回 | `spawn` recall worker |
+| `mnemon_related` | 从已知 ID 遍历关系 | `spawn` related worker；Root 默认两跳 |
+| `mnemon_document_search` | 确定性搜索受管档案 | Documents 控制层 |
 
-这里的“只读”表示不修改受管正文或长期语义内容。`mnemon_document_search` 命中后仍会更新 `lastAccessedAt` 并重写 Document index，用于 LRU 排序。
+“只读”表示不修改受管正文或长期语义内容。`mnemon_document_search` 命中后仍会更新 `lastAccessedAt`，用于 LRU 排序，因此功能只读不等于磁盘只读。
 
 ### `writeEnabled=true` 时的工具
 
 | 工具 | 用途 | Root Agent 路径 |
 |---|---|---|
-| `mnemon_runtime_memory` | `add` / `replace` / `remove` 热记忆 | 确定性控制层；add 溢出时 worker |
-| `mnemon_document_manage` | 创建、更新或归档 Document | 创建/更新确定性；归档 worker |
-| `mnemon_remember` | 长期沉淀一条洞察 | `spawn` write worker |
+| `mnemon_runtime_memory` | `add` / `replace` / `remove` 热记忆 | 确定性控制；add 溢出时可能启动 worker |
+| `mnemon_document_manage` | 创建、更新或归档档案 | 创建/更新确定性；归档使用 worker |
+| `mnemon_remember` | 沉淀一条长期洞察 | `spawn` write worker |
 | `mnemon_link` | 建立 typed relationship | `spawn` write worker |
 | `mnemon_forget` | 按精确 ID 软删除 | `spawn` write worker |
-| `mnemon_memory_body_create` | 创建独立 Memory Space | `spawn` write worker |
-| `mnemon_memory_body_update` | 更新名称、description、active | `spawn` write worker |
+| `mnemon_memory_body_create` | 创建独立记忆体 | `spawn` write worker |
+| `mnemon_memory_body_update` | 更新名称、说明或 active | `spawn` write worker |
 | `mnemon_memory_body_merge` | 非破坏性导入合并 | `spawn` write worker |
 
-worker 内调用同名工具时直接到服务层，不再委派。
+worker 内调用同名工具时直接进入服务层，不再递归委派。
 
 ## 工具准入建议
 
-- 热记忆：用户明确偏好、稳定项目约定、环境事实和高频经验。
-- Document：形成完整结构和理由的设计、调查、流程或交接。
-- 长期 Memory Space：明确要求跨任务保留，或适合图关系和深召回的稳定洞察。
-- 跳过：问题、猜测、临时进度、完成日志、原始输出、秘密、可轻易重新发现的仓库事实。
+- **运行时**：明确偏好、稳定项目约定、环境事实和高频经验。
+- **档案**：具有完整结构和理由的设计、调查、流程、复盘或交接。
+- **记忆体**：需要跨任务保留，或适合图关系与深召回的稳定事实、决策和洞察。
+- **跳过**：问题、猜测、临时进度、完成日志、原始输出、秘密和可轻易从仓库重新发现的普通事实。
 
-`mnemon_forget` 是破坏性语义操作，只有用户明确要求或内容已被验证错误/过时时才应执行。
+`mnemon_forget` 是破坏性语义操作；只有用户明确要求，或内容已确认错误 / 过时时才应执行。
 
 ## `/mnemon` 命令
 
@@ -81,17 +67,32 @@ worker 内调用同名工具时直接到服务层，不再委派。
 ```
 
 - 空 `/mnemon` 等价于 `status`。
-- `status` 确定性读取，不启动模型。
-- `recall`、`related`、`remember` 和 `forget` 使用命令所在 live Agent 作为 worker parent。
+- `status` 是确定性读取，不启动模型。
+- `recall`、`related`、`remember`、`forget` 使用命令所在 live Agent 作为 worker parent。
 - 命令 recall 最多返回 10 条。
-- `forget` 参数必须是一个不含空格的精确 ID。
-- 当前命令帮助和结果主要为中文，尚未跟随 Web locale。
+- `forget` 必须接收一个不含空格的精确 ID。
 
-## RPC 通道
+## 对话内交互契约
+
+| DSH 槽位 | 注册 | 行为 |
+|---|---|---|
+| `conversation.chat.turnTail` | chain | 通过 `turn-activity` 汇总完成回合中的 `mnemon_*` 调用；无活动或未完成回合不渲染 |
+| `conversation.chat.assistant-actions` | list，`id=mnemon-save` | 通过 `assistant-message` 读取已定稿文本；只在用户确认后调用 `supervise` |
+
+两者都是增量注册，不替换 DSH 官方渲染。`assistant-message` 读取的候选可编辑，长回复会按界面上限截取；写入结果以记忆子 Agent 回执为准。
+
+## 工作区路由
+
+工作台请求携带 `sessionId` 和可选 `workspaceId`。Host 只接受 `workspaceRegistry` 已登记的 ID：
 
-RPC 是 DSH Host 与本插件 Web client 的内部桥，不是承诺稳定的外部 HTTP API。
+- 确定性读取与人工维护可以路由到 `workspaceId` 选择的查看根；
+- Agent、工具、命令和生命周期仍按 `sessionId` 对应 Agent cwd 路由；
+- `status.workspaceContext` 返回 selected / effective roots 与 `aligned`；
+- 需要 Agent 的操作在未对齐时拒绝。
 
-工作台数据请求会携带 `sessionId` 和可选的 `workspaceId`。Host 只接受 `workspaceRegistry` 中已登记的工作区 ID：确定性读取与人工维护路由到 `workspaceId` 指向的查看根，而 Agent、工具和生命周期继续按 `sessionId` 对应 Agent 的 cwd 路由。`status.workspaceContext` 返回两条根目录和 `aligned` 状态；需要 Agent 写入的操作在未对齐时被拒绝。
+## RPC 通道
+
+RPC 是 DSH Host 与插件客户端之间的内部桥，不是稳定外部 HTTP API。
 
 ### 读通道
 
@@ -102,18 +103,15 @@ authority: trusted-host
 
 | Endpoint | 行为 |
 |---|---|
-| `runtime-memory` | Runtime 快照 |
-| `status` | 服务、生命周期、Documents 和存储域聚合状态 |
-| `documents` | Document 目录快照 |
-| `document` | 读取一份 Document |
-| `document-search` | 确定性搜索，命中会更新 LRU 元数据 |
-| `graph` | 聚合 active Memory Spaces 图谱 |
-| `bodies` | Memory Space 目录 |
-| `list` | 内容列表 |
-| `entities` | 实体统计或实体相关上下文 |
-| `search` | 直接 Mnemon 检索 |
-| `agent-search` | 直接检索后做证据限定回答 |
-| `related` | 直接关系遍历 |
+| `status` | 服务、版本、生命周期、档案与存储上下文聚合状态 |
+| `versions` | 检查 Mnemon 与 dsh-mnemon 当前 / 最新版本和安装来源 |
+| `runtime-memory` | 运行时快照 |
+| `documents` / `document` / `document-search` | 档案目录、正文与确定性搜索 |
+| `graph` / `bodies` | active 多空间图谱与记忆体目录 |
+| `list` / `entities` | 内容列表与实体聚合 |
+| `search` / `agent-search` / `related` | 直接检索、证据回答与关系遍历 |
+| `turn-activities` / `turn-activity` | 会话或单回合的记忆工具活动 |
+| `assistant-message` | 按 messageId 读取已定稿助手文本 |
 
 ### 写通道
 
@@ -125,25 +123,40 @@ authority: loopback
 | Endpoint | 行为 |
 |---|---|
 | `runtime-memory` | 热记忆 mutation |
-| `supervise` | 工作台候选交给记忆 worker |
+| `supervise` | 把候选交给记忆 worker |
 | `document` | create / update / archive |
-| `remember` | 带可选高级约束的语义写入 |
-| `link` | 建立关系 |
-| `forget` | 软删除 |
-| `body-create` | 创建 Memory Space |
-| `body-update` | 更新元数据或 active |
+| `remember` / `link` / `forget` | 长期语义写入、关系与软删除 |
+| `body-create` / `body-update` / `body-delete` | 记忆体创建、编辑与确认后的物理删除 |
+| `version-update` | 更新明确组件；Host 固定命令与参数 |
+
+`writeEnabled=false` 时通道仍稳定注册，但所有 mutation 在 Host 边界拒绝。
+
+### 备份通道
+
+```text
+channel:   /dsh-mnemon-pack
+authority: loopback
+```
+
+| Endpoint | 行为 |
+|---|---|
+| `target` | 当前有效根与范围 |
+| `export` | 导出完整、带 manifest 与 SHA-256 校验的 ZIP |
+| `inspect` | 解析并校验待导入 ZIP，返回组件与占用预览 |
+| `import` | 把 ZIP 安全合并到当前有效根；只读模式拒绝 |
 
-`writeEnabled=false` 时写通道保持稳定注册，但所有 mutation 都会在 Host 边界拒绝。
+备份包含私有记忆，因此整个通道保持 loopback-only。
 
 ### 设置通道
 
 ```text
 channel:   /dsh-mnemon-settings
 authority: loopback
+namespaces: mnemon, mnemon-ui
 endpoints: get, mutate
 ```
 
-mutation 使用 settings revision 防止覆盖并发编辑。
+mutation 使用 settings revision 防止覆盖并发编辑。`mnemon` 管理 Host / 存储设置；`mnemon-ui` 管理 `turnBar` 与 `saveAction`。
 
 ## npm 导出
 
@@ -161,13 +174,8 @@ MnemonSubagentCoordinator
 MnemonLifecycle
 ```
 
-`dsh-mnemon/client` 用于 DSH client bundle 的 `apply` 与 `inject`。`MnemonClient` 和 RPC endpoint 当前属于内部实现，不应当作稳定公共 SDK。
+`dsh-mnemon/client` 导出 DSH client bundle 的 `apply` 与 `inject`。客户端实现类与 RPC endpoint 目前均属于内部实现，不应当作稳定公共 SDK。
 
 ## 国际化范围
 
-Web 词典保持中文/英文键一一对应，品牌名、工具名和配置键不翻译。尚未完整国际化的表面包括：
-
-- `/mnemon` 命令输出；
-- 模型工具展示卡标题；
-- 部分 Host 校验和诊断错误；
-- 兼容发现旧 Store 时写入的默认名称和说明。
+主要 Sidebar / Buildin 工作台、设置与对话内入口支持中文和英文，并跟随 DSH locale 实时切换。品牌名、工具名和配置键不翻译。`/mnemon` 命令、模型工具卡、部分 Host 错误与兼容元数据尚未完全国际化。