dsh-mnemon 0.1.2 → 0.1.3

package/docs/zh-CN/operations.md

@@ -4,7 +4,7 @@
 
 ## 健康检查
 
-先检查二进制，再检查插件聚合状态：
+先检查二进制，再查看工作台“状态”：
 
 ```sh
 command -v mnemon
@@ -15,142 +15,152 @@ mnemon --version
 /mnemon status
 ```
 
-`mnemon status` 会打开有效 Store，上游 CLI 可能初始化默认数据或执行迁移；它不是完全无副作用的只读探测。插件状态页还会检查 active Memory Spaces、Documents、生命周期和 subagent 计数。
+[![状态页：组件版本、三层数据与实际存储目录](../assets/screenshots/status-overview.png)](../assets/screenshots/status-overview.png)
 
-## 安全边界
+状态页显示 Mnemon / dsh-mnemon 版本、Runtime、Memory Spaces、Documents 和当前实际目录。`mnemon status` 会打开有效 Store，上游 CLI 可能初始化数据或执行迁移，因此不是完全无副作用的只读探测。
 
-### 进程
+## 版本检查与更新
 
-- `spawn(command, args, { shell: false })`，不拼接 shell 命令。
-- stdout + stderr 默认合计限制 2 MiB。
-- 每次 CLI 调用受 `timeoutMs` 和 AbortSignal 控制。
-- 超时或取消先发送 `SIGTERM`，1.5 秒后仍未退出则发送 `SIGKILL`。
-- 一个 `MnemonRunner` 内的 CLI 调用串行，避免同一进程内并发迁移导致 SQLite 锁冲突。
+状态页的“检查版本”打开“检查与更新版本”面板：
 
-串行队列不替代跨 DSH 进程协调；多个 Host 同时访问同一 Mnemon Store 时仍依赖 Mnemon/SQLite 自身的并发语义。
+[![检查与更新 Mnemon CLI 和 dsh-mnemon](../assets/screenshots/version-check.png)](../assets/screenshots/version-check.png)
 
-### 文件
+- **Mnemon CLI**：本地版本来自 `mnemon --version`，最新版本来自 Mnemon GitHub Releases。
+- **dsh-mnemon**：运行版本来自当前插件包，最新版本来自 npm registry。
 
-- Runtime 和 Documents 都有进程内队列及跨实例 lock file。
-- 等待锁默认最多 5 秒；锁超过 30 秒才被视为 stale。
-- 写入使用临时文件和 rename。
-- Runtime 用 revision 阻止过期压缩覆盖并发修改。
-- Document 归档用数字 revision 阻止移动已被更新的 active 原文。
-- `sourcePaths` 不能逃出发起会话工作区，也不能指向受管 Documents 目录。
+检查只读，不会自动安装。只有发现更高版本并安全识别安装来源时才显示“更新”：Mnemon 支持 Homebrew Cask / Formula 与 `go install`；dsh-mnemon 支持当前 DSH Profile 中由 pnpm 管理的 npm 安装。`link:` / `file:` 开发版本与无法识别的手工安装只显示说明，避免覆盖源码。
 
-### Web
+更新命令由 Host 固定选择：浏览器不能传入命令或参数，执行禁用 shell，并限制时间与输出。更新完成后界面自动重新检查两个组件并刷新状态。Mnemon CLI 从下一次调用起生效；dsh-mnemon 仍需重启 `dsh web` 才能加载新插件代码。
 
-- 读 RPC：`trusted-host`。
-- 记忆写 RPC：`loopback`。
-- 设置 RPC：`loopback`。
-- WebUI 不直接读取 SQLite 或启动进程。
+## 备份与恢复
 
-### 模型
+### 推荐：设置页 ZIP
 
-- worker 使用 persona、工具白名单、结构化输出和 `maxDepth: 1`。
-- 用户查询、候选内容、Document 正文和历史记忆均按不可信数据处理。
-- 证据回答 worker 无 Mnemon 工具，只能使用 Host 提供的命中内容。
+“设置 → 记忆系统 → 备份与迁移”针对**当前有效根**工作：
 
-这些边界不等于秘密扫描器。当前还没有确定性的凭据/秘密检测；不要向热记忆、Documents 或 Memory Spaces 提交密钥、token、私钥和原始敏感日志。
+- **导出 ZIP**：包含 Runtime、Documents 和全部 Memory Spaces；
+- **导入 ZIP**：先预检，再合并到当前有效根；
+- 包内包含 `manifest.json`、SHA-256 清单和三类数据摘要；
+- 导出与导入持有组件锁，Memory Space 仍有未 checkpoint 的 WAL 时会拒绝；
+- 导入检查路径、数量、压缩 / 展开大小、JSON schema、Document 哈希、registry 与 SQLite 头；
+- 合并先写 staging，再替换目标组件；提交失败会恢复导入前目录。
 
-### 安全问题报告
+当前 UI 只提供安全合并，不做“覆盖一切”：
+
+- Runtime 按目标与内容去重；
+- 相同 Document ID + 相同内容跳过，ID 冲突且内容不同则生成新 ID；
+- 相同 Memory Space ID + 相同数据库跳过，内容不同则生成新 ID。
+
+导入受 `writeEnabled` 控制，只读部署会拒绝。ZIP 包含私有记忆，应像源代码与凭据备份一样加密、限制访问并验证恢复。
 
-发现安全漏洞请按 [SECURITY.md](../../SECURITY.md) 的渠道私下报告（GitHub Security Advisories 或维护者邮箱），不要开公开 issue。范围内的典型问题包括：数据丢失、路径穿越、锁与 revision 检查绕过、子 Agent 隔离破坏、WebUI 对记忆内容的注入。
+### 恢复演练
 
-## 备份
+1. 先选择一个隔离的 `custom` 目录并保存。
+2. 确认设置页显示的“当前目录 ZIP”正是隔离根。
+3. 选择备份，阅读预检摘要后执行导入。
+4. 在状态页检查 Runtime、Documents、Memory Spaces 与目录。
+5. 用一个聚焦查询验证直接检索，再阅读一份档案。
+6. 验证无误后再决定是否切换正式范围。
 
-三层数据共用 `storageRoot`，一致备份应覆盖整个根，而不是只复制 `mnemon.db`：
+不要在没有备份时把恢复直接指向唯一生产根。
+
+### 文件系统级快照
+
+需要保留预留 `state` 或做离线完整快照时，可以停止所有使用该根的 DSH / Mnemon 进程后复制：
 
 ```text
 <storageRoot>/runtime
 <storageRoot>/documents
 <storageRoot>/data
-<storageRoot>/state    # when present
+<storageRoot>/state    # 若存在；不在内置 ZIP 的三类数据组件中
 ```
 
-推荐过程：
+复制完成后生成文件清单或校验和，并在隔离路径演练恢复。不要在多个进程仍写入时把普通目录复制当作一致快照。
 
-1. 停止 DSH Host 和其他写入同一根的进程。
-2. 记录当前插件、DSH 和 `mnemon --version`。
-3. 复制整个根到新的、带时间戳的目录。
-4. 对备份执行文件清单或校验和。
-5. 在隔离路径中完成恢复演练后再依赖它。
+## 切换存储范围
 
-项目当前没有内置一致快照、导出或恢复命令；运行中直接复制可能捕获跨文件不一致状态。
+保存 `global` / `workspace` / `custom` 后，Host 先初始化新运行图，再原子切换；页面自动重新读取，但**不会迁移数据**：
 
-## 恢复
+```text
+旧范围 -- 保存设置 --> 新的空目录或既有目录
 
-1. 停止所有使用目标根的 DSH/Mnemon 进程。
-2. 保留现有根的第二份副本，不要直接覆盖唯一数据。
-3. 把完整备份恢复到一个新目录。
-4. 先用 `storageScope=custom` 指向新目录。
-5. 启动并检查 Runtime 投影、Document index、Memory Space 目录和 recall。
-6. 验证后再决定是否替换原根。
+不自动复制
+不自动合并
+不自动删除
+```
 
-`USER.md` / `MEMORY.md` 损坏时，控制层可从有效的 `memories.json` 修复；损坏的 JSON、Document index 或 SQLite 不存在自动通用修复流程。
+推荐迁移流程：在旧范围导出 ZIP → 切换到新范围并确认显示目录 → 导入 ZIP → 验证。工作区模式下先确认查看工作区与会话执行工作区是否是预期目标。
 
-## 切换存储范围
+## 安全边界
 
-插件不会自动迁移数据：
+### 进程
 
-```text
-old scope -- change setting + save --> new empty or existing scope
+- CLI 使用 `spawn(command, args, { shell: false })`，不拼接 shell。
+- stdout + stderr 默认合计限制 2 MiB。
+- 每次调用受 `timeoutMs` 与 AbortSignal 控制；取消先 `SIGTERM`，1.5 秒后 `SIGKILL`。
+- 单个 Runner 内调用串行；跨 DSH 进程仍依赖 Mnemon / SQLite 并发语义。
 
-no implicit copy
-no implicit merge
-no implicit delete
-```
+### 文件
+
+- Runtime、Documents 和 Pack 操作使用进程内队列或组件锁。
+- lock 默认等待 5 秒，超过 30 秒才视为 stale。
+- 写入使用临时文件、staging 与 rename。
+- Runtime revision 阻止过期压缩覆盖；Document revision 阻止移动已更新原文。
+- `sourcePaths` 不能逃出发起会话工作区，也不能指向受管 Documents 目录。
+
+### Web 与模型
+
+- 读 RPC 为 `trusted-host`；写、设置与备份 RPC 为 `loopback`。
+- WebUI 不直接读取 SQLite、启动进程或指定任意更新命令。
+- worker 使用 persona、工具白名单、结构化输出与 `maxDepth: 1`。
+- 查询、候选、档案正文与历史记忆全部按不可信数据处理。
 
-需要迁移时，停止写入后复制完整根。合并两套根不能靠目录覆盖，因为 JSON index、registry 和多个数据库都可能冲突；应在备份上设计显式合并方案。
+这些边界不是秘密扫描器。当前没有确定性的凭据检测；不要提交密钥、token、私钥和原始敏感日志。
+
+### 安全问题报告
+
+按 [SECURITY.md](../../SECURITY.md) 私下报告漏洞，不要创建公开 issue。数据丢失、路径穿越、锁 / revision 绕过、子 Agent 隔离破坏和 WebUI 记忆内容注入都在范围内。
 
 ## 故障排查
 
 | 现象 | 检查与处理 |
 |---|---|
 | Mnemon 不可用 | 运行 `command -v mnemon`、`mnemon --version`；设置 `MNEMON_CLI_PATH` 或 `cliPath` 后重启 |
-| 状态正常但召回为空 | 检查是否有 active Memory Space、当前 `storageScope`、工作台查看目录、会话实际生效目录和查询是否足够聚焦 |
-| 工作台提示目录未对齐 | 这是安全提示：工作台正在查看另一工作区，而 Agent 仍跟随当前会话；点击“对齐当前会话”或有意保留跨工作区查看 |
-| `memoryBodyId is required...` | active 数量不是恰好 1；让 worker 或调用方显式选择目标 |
-| `memory body is not active for reading` | 在记忆体页激活目标；写入 inactive 可以，但读取不行 |
-| subagent provider 错误 | 普通任务需要完整隔离能力；后台审查另需 `fork + inheritsParentContext` |
-| 设置保存后无变化 | 检查界面错误提示；所有选项应在保存成功后实时生效 |
-| custom 目录被拒绝 | 使用绝对路径、`~` 或 `~/...` |
-| Document 无 workspace | 会话必须对应 live root Agent，并在 session header 中带 cwd |
-| source path 被拒绝 | 路径必须留在会话工作区内，且不能引用托管 Documents 目录 |
-| Runtime replace 超容量 | 缩短 replacement 或先显式整理；当前自动维护只处理 add 溢出 |
-| CLI timeout | 增大 `timeoutMs`；大 Store 的状态和图谱导出可能超过 10 秒 |
-| lock timeout | 检查是否有另一个实例正在写；不要删除仍属于活跃进程的 lock |
-| invalid JSON / unexpected viz | CLI 输出协议可能不兼容；在隔离根中验证版本，不要继续写生产数据 |
-| 远程页面可以读但不能写 | 写 RPC 强制 loopback，这是权限设计 |
-| 左侧栏不显示“记忆系统” | 检查 `tabEnabled=true` 且 `displayMode=sidebar`；`buildin` 会显示在对话区标签页；本地 link 修改后先运行 `pnpm run build` 并重启 DSH profile |
-| 本地 link 不反映源码 | 先运行 `pnpm run build`，再重启 DSH profile |
+| 左侧栏没有“记忆系统” | 检查 `tabEnabled=true`、`displayMode=sidebar`；Buildin 位于对话区；本地 link 先 `pnpm run build` 再重启 profile |
+| 状态正常但召回为空 | 检查 active 记忆体、存储范围、查看目录、会话实际目录和查询是否足够聚焦 |
+| 顶部提示目录未对齐 | 工作台正在查看另一个工作区；点击一键对齐，或有意保留只读查看；Agent-backed 操作在未对齐时拒绝 |
+| 设置保存后无变化 | 查看保存错误；成功保存应实时切换并自动重新读取，不需要刷新 |
+| 自定义目录被拒绝 | 使用绝对路径、`~` 或 `~/...` |
+| `memoryBodyId is required...` | active 数量不是恰好 1；显式选择目标 |
+| `memory body is not active for reading` | 在概览激活目标；写入 inactive 可以，读取不行 |
+| Provider 错误 | 普通语义任务需要完整隔离能力；后台审查另需 `fork + inheritsParentContext` |
+| Runtime replace 超容量 | 缩短 replacement 或先显式整理；自动维护只处理 add 溢出 |
+| Document source path 被拒绝 | 路径必须在会话工作区内，且不能引用受管 Documents 目录 |
+| CLI timeout | 增大 `timeoutMs`；大 Store 的状态与图谱可能超过 10 秒 |
+| lock timeout | 检查其他写进程，不要删除仍属于活跃进程的 lock |
+| ZIP 导出提示 WAL busy | 等待 Memory Space 写入完成并重试；不要绕过未 checkpoint WAL 检查 |
+| ZIP 导入 checksum / schema 失败 | 备份损坏或格式不兼容；保留当前根，不要手工解压覆盖 |
+| 更新按钮不出现 | 当前已是最新、远程检查失败，或安装来源是 link / 手工模式；按面板提示沿原方式更新 |
+| 远程页面能读不能写 | 写、设置与备份 RPC 强制 loopback，这是权限设计 |
 
 ## 已知限制
 
 ### 功能只读不等于磁盘只读
 
-`writeEnabled=false` 禁用语义 mutation，但启动时仍可能创建/修复 Runtime 文件，Document 搜索会更新 `lastAccessedAt`，Mnemon 读取也可能触发上游 migration。不要在真正只读文件系统上假设它能无写运行。
+`writeEnabled=false` 禁用语义 mutation 与 Pack 导入，但启动可能初始化 / 修复 Runtime 投影，Document 搜索更新 `lastAccessedAt`，Mnemon 读命令也可能迁移数据库。
 
 ### Documents 的共享范围
 
-`global` 和 `custom` 可能让多个工作区共享同一 Document index；记录没有独立 workspace ownership 字段。`sourcePaths` 仅在写入时相对发起会话 cwd 校验。
-
-### 冷引用路径
-
-当前 archive worker 的提示使用 `.mnemon/documents/archived/<filename>` 作为计划引用；在 global/custom scope 中实际文件位于 `<storageRoot>/documents/archived/<filename>`。定位原文时应以 `documents/index.json` 或 UI 展示的 `relativePath` 为准。这是待修复的路径表达差异。
+`global` 与 `custom` 可能让多个工作区共享同一 Document index；记录没有独立 workspace ownership 字段。`sourcePaths` 只在写入时相对发起会话 cwd 校验。
 
 ### 跨系统事务
 
-“先索引、后移动”保护 active 原文，但不是跨 Mnemon SQLite 与文件系统的可回滚分布式事务。索引成功后若 revision 冲突，索引可能保留为重复引用；插件选择保留数据而不是回滚已完成的长期写入。
+“先冷索引、后移动”保护 active 原文，但不是跨 Mnemon SQLite 与文件系统的可回滚分布式事务。索引后发生 revision 冲突时可能保留重复引用；系统选择保留数据。
 
 ### 后台水位
 
-评分、最近 checkpoint 和重试状态没有持久化。Host 重启会清空尚未处理的活动；失败退避、熔断和人工重试入口也尚未实现。
-
-### 版本矩阵
-
-项目尚未声明正式的 DSH/Mnemon 支持矩阵和 schema migration 策略。升级必须先备份并在隔离根中验证。
+活动评分、最近 checkpoint 与重试状态未持久化；Host 重启会清空未处理活动。失败退避、熔断和人工重试入口尚未实现。
 
-### 国际化
+### 版本与国际化
 
-主要 Web 工作台为中英文双语，但命令、工具卡、兼容默认元数据和部分错误信息尚未完整国际化。
+尚无正式固定的 DSH / Mnemon 支持矩阵。主要 Web 界面为中英文双语，但命令、工具卡、兼容元数据和部分错误仍未完全国际化。

package/docs/zh-CN/project-overview.md

@@ -2,248 +2,132 @@
 
 **简体中文** | [English](../en/project-overview.md) | [文档中心](./README.md)
 
-> **`dsh-mnemon` 是 [Mnemon](https://github.com/mnemon-dev/mnemon) 与 DSH 的深度集成插件，为 DSH 提供完备的记忆体能力。**
+`dsh-mnemon` 将 [Mnemon](https://github.com/mnemon-dev/mnemon) 的长期记忆体接入 DeepSeek Harness，并补充运行时热记忆、项目档案、生命周期路由、受限子 Agent、确定性控制层与 DSH 原生界面。
 
-它把“每轮必须知道的内容”“需要完整阅读的项目知识”和“跨会话按需召回的长期历史”分别放在三个职责清晰的层级中，再由 DSH 提供路由、生命周期、受限子 Agent 和用户界面。
+它要解决的不是“保存更多文字”，而是让 Agent 在长期连续性、当前事实优先、上下文成本和可恢复写入之间取得平衡。
 
-项目的核心目标是：让 Agent 获得长期连续性，同时保持当前任务优先、上下文紧凑、写入可审计、失败时不丢原始数据。
+[![记忆体概览：目录、激活边界与多空间关系图](../assets/screenshots/overview-memory-graph.png)](../assets/screenshots/overview-memory-graph.png)
 
-[![Mnemon 记忆体页：记忆体目录、激活状态与多空间实时关系图](./assets/screenshots/overview-memory-graph.png)](./assets/screenshots/overview-memory-graph.png)
+## 为什么需要三个层级
 
-*记忆体页把记忆体目录、激活状态、统计信息和多空间关系图放在同一工作面中；点击图片可查看原始分辨率。*
+单一记忆层很难同时满足高频注入、完整阅读和跨会话召回：
 
-## 为什么需要它
-
-仅依赖当前对话上下文时，Agent 很难稳定延续用户偏好、项目约定和历史决策；把全部历史直接塞入 prompt，又会造成上下文膨胀、过期信息干扰和成本增加。单一记忆层级同样无法兼顾以下需求：
-
-| 需求 | 单一记忆层级的局限 | dsh-mnemon 的处理方式 |
+| 需求 | 如果只有一个记忆层 | dsh-mnemon 的选择 |
 |---|---|---|
-| 下一轮立即知道稳定偏好和约定 | 每次检索会增加延迟，且可能漏召回 | Runtime Memory 每轮注入紧凑投影 |
-| 快速阅读完整设计、调查或流程 | 拆成碎片后会失去叙事结构 | Documents 保留可检索的 Markdown 原文 |
-| 跨会话查找事实、决策和关系 | 全量加载会污染当前上下文 | Memory Spaces 按需召回图增强证据 |
-| 长文不常用但仍需追溯 | 永久保留在热层会持续占用容量 | 先建立长期冷引用，再迁移原文 |
-| 让模型判断价值又不把安全交给模型 | LLM 输出无法承担路径、并发和事务保证 | LLM 负责语义判断，Host 负责硬边界 |
-
-无论命中哪一层，当前用户指令、实时工具结果和仓库事实始终高于历史记忆。插件提供的是可复核证据与连续性，不允许旧内容覆盖当前事实。
-
-为同时满足即时可见、完整阅读与长期召回三类需求，插件在 DSH 与本地存储之间建立了一套分层、受监督的记忆架构。
-
-## 总体架构
-
-DSH 提供主 Agent 与扩展入口，`dsh-mnemon` 负责三层控制、路由和安全边界，[Mnemon](https://github.com/mnemon-dev/mnemon) 则为长期 Memory Spaces 提供记忆体能力。Runtime 投影与 Documents 原文由插件管理；长期记忆体和归档冷引用通过 Mnemon 保存和检索。
-
-[![dsh-mnemon 运行时架构：DSH Web、主 Agent、监督控制层与三层本地存储](./assets/project-architecture.svg)](./assets/project-architecture.svg)
-
-架构可以理解为四个边界：
-
-1. **交互边界**：用户通过 DSH 对话、`/mnemon` 命令、模型工具和 Web 工作台使用记忆能力。
-2. **监督边界**：生命周期只提供短提示；长期召回、语义写入和维护任务在受限子 Agent 中执行。
-3. **确定性控制边界**：Host 校验输入、路径、权限、revision、UTF-8 容量、锁、超时和进程参数。
-4. **本地数据边界**：Runtime、Documents 和 Memory Spaces 统一位于选定的 `storageRoot`；记忆持久化不依赖远程记忆服务。
-
-更细的模块分工、root/worker 双路径和 RPC 信任边界见[架构设计](./architecture.md)。
-
-架构边界决定谁可以执行操作，内置 Prompt 决定 LLM 何时主动使用能力，三层模型则决定信息以什么粒度保存、何时进入上下文。
+| 下一轮必须知道用户偏好和稳定约定 | 每次检索有延迟，也可能漏召回 | 运行时记忆每轮注入紧凑投影 |
+| 阅读完整设计、调查或流程 | 切成碎片会失去叙事和来源 | 档案保留受管 Markdown 全文 |
+| 跨会话查找事实、决策和关系 | 全量加载会污染上下文 | 记忆体按需返回有界图增强证据 |
+| 保留不常用长文的可追溯性 | 永久留在热层持续占容量 | 先建立冷引用，再迁移原文 |
+| 让模型判断价值但不掌握系统安全 | LLM 无法保证路径、锁和事务 | worker 负责语义，Host 负责硬边界 |
 
-## 内置 Prompt 与主动记忆
-
-插件通过系统 Prompt、动态注入的最新 `USER.md` / `MEMORY.md`、生命周期提示与工具说明，把 Runtime Memory、Documents、Memory Spaces、关系和目录维护等全部读写能力呈现给 LLM，启发它在当前任务可能受益时主动调用相应能力，而不是等待用户逐个指定工具。
-
-“主动”不等于每轮无条件读写：当前任务始终优先；无需记忆时继续工作；任何写入都必须以有效工具回执为完成依据。当用户明确表达意图时，LLM 会按信息的粒度和目标选择不同路径：
-
-| 用户意图或任务信号 | 优先调用的能力 |
-|---|---|
-| 回顾过去、寻找历史依据、补齐精确旧细节 | 先检索 active Documents，再按需 `mnemon_recall` / `mnemon_related` |
-| 记住偏好、稳定约定或纠正旧信息 | `mnemon_runtime_memory` 的 `add` / `replace` / `remove` |
-| 保存完整设计、调查、流程或交接材料 | `mnemon_document_search` 后创建或更新受管 Document，必要时执行归档 |
-| 长期沉淀事实或决策、建立关系、忘记内容、调整记忆体 | 由受限 worker 查重和路由后调用 Memory Space 写入与维护能力 |
-
-即使用户没有逐字要求“记住”，明确且可复用的新事实也可以触发主动热记忆写入；当已完成工作达到活动评分门槛且主 Agent 保持空闲时，`fork` 后台审查还会保守检查热记忆与项目档案。完整提示策略、生命周期门槛和工具权限见[生命周期与核心流程](./workflows.md)与[接口参考](./interfaces.md)。
+无论命中哪一层，优先级始终是：**当前用户指令 → 实时工具与仓库事实 → 历史记忆**。
 
 ## 三层记忆模型
 
-### 1. Runtime Memory：每轮可见的热记忆
-
-Runtime Memory 保存高频且紧凑的稳定信息：
+### 1. 运行时记忆
 
-- `target=user`：身份、角色、长期偏好、习惯、沟通风格和明确协作要求；
-- `target=memory`：项目约定、环境事实、决策、工具特性和可复用经验。
+运行时层保存高频、紧凑、每轮都可能使用的信息：
 
-`runtime/memories.json` 是唯一事实源，`USER.md` 和 `MEMORY.md` 是每轮注入 prompt 的确定性投影。USER 上限为 4 KiB，MEMORY 上限为 10 KiB，单条内容最大 8 KiB，均按 UTF-8 字节计算。
+- `USER.md`：身份、角色、偏好、习惯和明确协作要求；
+- `MEMORY.md`：项目约定、环境事实、决策、工具特性与可复用经验。
 
-普通 `add`、`replace` 和 `remove` 由确定性控制层完成。只有 `add` 造成容量溢出时才触发维护：USER 在本地由无工具 worker 保守合并；MEMORY 先由受限 worker 归档长期语义，再压缩热层候选。导致溢出的 `replace` 会直接拒绝，不会自动整理。
+`runtime/memories.json` 是唯一事实源，两个 Markdown 文件是确定性投影。USER 上限 4 KiB，MEMORY 上限 10 KiB，均按 UTF-8 字节计算。普通增删改由控制层执行；只有容量维护才可能启动 worker。
 
-[![运行时记忆页面：USER 与 MEMORY 热记忆、容量和编辑操作](./assets/screenshots/runtime-memory.png)](./assets/screenshots/runtime-memory.png)
+### 2. 项目档案
 
-*运行时页面并列展示 USER 与 MEMORY 两个投影的容量、重要度、分类和逐条编辑入口。*
+档案保存需要完整结构的设计、调查、流程、复盘和交接。标题、检索说明与正文参与确定性搜索，正文保持 Markdown。
 
-### 2. Project Documents：保留完整叙事的项目档案
+单份正文最大 2 MiB，active 总量最大 10 MiB。人工归档或容量整理时，插件先让受限 worker 在 Mnemon 写入带摘要与 SHA-256 的冷引用，再在 revision 未变化时移动原文。失败或冲突时优先保留 active 原文。
 
-Documents 保存比单条记忆更完整、又需要快速阅读的知识，例如架构理由、调查结论、操作流程、故障复盘和实现交接。正文保持 Markdown 结构，并通过标题、description 和正文做确定性检索。
+### 3. 记忆体
 
-单份正文最大 2 MiB，active Documents 渲染后总量最大 10 MiB。容量不足或人工归档时，插件先让受限 worker 在 Mnemon 中建立带摘要和 SHA-256 的冷引用，再在 Document revision 未变化时把原文移入 `archived/`。这一顺序优先保护 active 原文，但不是跨 SQLite 与文件系统的可回滚分布式事务。
-
-Documents 的共享范围跟随 `storageScope`。在 `global` 或 `custom` 下，多个工作区可能共享同一个 Document index；当前会话工作区只约束新写入的 `sourcePaths`，不构成独立 ownership。
-
-[![项目档案页面：Document 列表、元数据与 Markdown 原文渲染](./assets/screenshots/documents-markdown.png)](./assets/screenshots/documents-markdown.png)
-
-*档案页面保留 Document 元数据与 Markdown 结构，列表选择、检索和正文阅读在同一页面完成。*
-
-### 3. Memory Spaces：长期、隔离、按需召回
-
-每个 Memory Space（记忆体）对应一个 Mnemon 原生命名 Store 和独立的 `mnemon.db`。插件为它补充稳定 ID、名称、路由 description 和 active 状态。
+每个记忆体对应一个独立 Mnemon Store 与 `mnemon.db`，并拥有稳定 ID、名称、路由说明和激活状态。
 
 - 读取只覆盖已激活记忆体；
-- 写入可以指定任意已登记记忆体；
-- 向 inactive 目标写入成功后会自动激活；
-- 新建记忆体时，模型提供语义名称和边界，Host 生成稳定 ID；
-- 合并通过非破坏性 import 完成，默认停用来源但不删除来源数据库。
-
-Mnemon 长期层保留 `temporal`、`semantic`、`causal` 和 `entity` 四类关系。召回结果携带 Memory Space 来源和记忆 ID，主 Agent 可以继续沿关系图获取上下文。
+- 写入可以选择任何已登记目标，成功后自动激活；
+- 长期层保留时间、语义、因果和实体四类关系；
+- 召回返回记忆体来源与记忆 ID，后续可以继续查看关联。
 
-完整目录、容量和权威源说明见[存储与三层记忆模型](./storage-model.md)。
+三层的权威文件、容量与目录结构见[存储与三层记忆模型](./storage-model.md)。
 
-三层并非彼此孤立的仓库，而是组成了一条由近到远、按需扩展的查询路径；信息也可以在明确写入或受控维护时，以适合其频率和粒度的形式沉淀下来。
-
-## 从当前请求到长期沉淀
-
-### 读取：由近到远，按需升级
-
-插件遵循由近到远的查询梯度：
-
-1. 当前请求、实时工具结果和仓库事实优先；
-2. 主 Agent 已能看到每轮注入的 Runtime Memory；
-3. 需要完整项目知识时，先确定性搜索 active Documents；
-4. 需要历史决策、跨会话事实或关系时，再调用监督召回；
-5. 命中冷引用且确需全文时，最后读取 archived Document 原文。
-
-主 Agent 调用 `mnemon_recall` 后，coordinator 启动一个隔离 worker。worker 只能查看记忆体目录、执行 recall 和遍历 related；它根据名称与 description 选择 active Memory Spaces，返回有上限的结构化证据。原始路由推理和完整目录不会被灌入主对话。
-
-Web 的直接检索走确定性服务；“Agent 查询”则先完成相同检索，再启动一个无 Mnemon 工具的 evidence-only worker，只根据命中内容组织答案并返回有效 citation。
-
-[![检索页面：Agent 查询答案、来源记忆 ID 与原始召回结果](./assets/screenshots/recall-agent-answer.png)](./assets/screenshots/recall-agent-answer.png)
-
-*“Agent 查询”把证据限定在本次命中范围内，同时保留来源记忆 ID 和原始召回条目，方便核验答案。*
-
-真实会话中，主 Agent 可以先检查记忆体目录和项目档案，再从已激活空间召回；若当前任务确需访问 inactive 空间，也可以在受控流程中临时激活，并在读取后恢复原状态。工具轨迹让检索次序、空间选择和来源都可观察。
-
-[![DSH 会话中的记忆召回：档案检索、多记忆体召回与状态恢复](./assets/screenshots/conversation-recall.png)](./assets/screenshots/conversation-recall.png)
-
-### 写入：语义判断与系统保证分离
-
-读取路径解决何时使用记忆；写入路径还需要约束谁来判断、谁来落盘，以及失败时如何保护原始数据。
+## 总体架构
 
-插件把语义判断与系统保证分开：
+[![dsh-mnemon 运行时架构：DSH Web、Root Agent、监督控制层与三层本地存储](../assets/diagrams/zh-CN/project-architecture.svg)](../assets/diagrams/zh-CN/project-architecture.svg)
 
-| LLM / worker 负责 | Host 硬保证 |
-|---|---|
-| 判断内容是否值得长期保存 | 输入 schema 和操作权限 |
-| 选择最窄的 Memory Space | 路径不能逃逸工作区边界 |
-| 识别重复、冲突和语义簇 | CLI 参数数组启动且禁用 shell |
-| 摘要、路由和关系理由 | 超时、取消、输出上限和进程串行 |
-| 判断复杂工作是否形成项目档案 | 文件锁、临时文件、rename 和 revision fence |
-| 在 persona 范围内保守维护 | UTF-8 容量计算和失败时保留原数据 |
+架构由四个边界组成：
 
-长期召回、语义写入与容量维护使用隔离的 `spawn` worker；后台审查只在已完成 turn 达到活动评分门槛、主 Agent 持续空闲后使用继承 checkpoint 的 `fork` worker。新 turn 会取消等待或运行中的审查。worker 的上下文、工具和输出均受限，Host 继续负责确定性校验；完整 provider 要求和审查边界见工作流文档。
+1. **交互边界**：用户通过对话、Sidebar / Buildin 工作台、`/mnemon` 命令与模型工具使用记忆。
+2. **监督边界**：长期召回、语义写入和归档在受限 worker 中执行；生命周期只提供短提示和调度信号。
+3. **确定性控制边界**：Host 校验 schema、路径、权限、容量、锁、revision、CLI 参数、超时与取消。
+4. **本地数据边界**：Runtime、Documents 与 Memory Spaces 统一位于当前 `storageRoot`，不依赖远程记忆服务。
 
-召回、写入、容量维护、归档和评分公式详见[生命周期与核心流程](./workflows.md)。
+### 记忆系统流转
 
-当用户明确要求记住稳定内容时，主 Agent 会根据内容类型使用结构化工具逐条写入，Host 继续负责目标、容量和 revision 校验。最终回复说明真正写入的内容，而不是把内部推理当作持久化结果。
+下面的架构图是稳定执行边界，不是实时状态面板。实线是 Host 确定性路径，虚线是需要 LLM 判断的受监督 worker 路径。
 
-[![DSH 会话中的记忆写回：结构化 Runtime Memory 工具调用与写入回执](./assets/screenshots/conversation-writeback.png)](./assets/screenshots/conversation-writeback.png)
+[![记忆系统流转：每轮上下文、按需语义操作、空闲维护与归档](../assets/diagrams/zh-CN/memory-system-flow.png)](../assets/diagrams/zh-CN/memory-system-flow.png)
 
-### 三层协同示例：保存一项架构决策
+三条主链路分别是：
 
-假设一次复杂任务确认了“所有外部 CLI 必须使用参数数组启动并禁止 shell”，同时产出完整的威胁分析和迁移说明：
+- **每轮上下文**：Runtime 投影进入 prompt；Root Agent 按需确定性搜索 active Documents。
+- **按需语义操作**：Root Agent 调度 `spawn` worker，通过 Host Bridge 访问已激活记忆体并只返回有界证据或写入回执。
+- **维护与归档**：普通变更由 Host 原子执行；空闲审查使用继承已完成 checkpoint 的 `fork`；档案归档先验证冷索引，再跨 revision fence 移动原文。
 
-1. 这条高频执行约定可以作为简短事实进入 `MEMORY.md`，从下一轮开始直接可见。
-2. 完整分析和迁移步骤适合进入 active Document，保留标题、章节、代码片段和来源文件。
-3. 若该决策需要跨项目长期召回，受限 worker 会选择合适的 Memory Space，先查重，再写入自包含决策，并可与相关安全原则建立关系。
-4. 未来询问“为什么不能拼接 shell 命令”时，Agent 先看到热层规则；需要理由时搜索 Document；需要跨会话关联时再召回 Mnemon 证据。
-5. 当 Document 长期不再频繁访问且 active 容量不足时，插件先写入带摘要和哈希的冷引用，再迁移原文。未来仍可沿引用追溯完整分析。
+触发门槛、取消行为和失败语义见[生命周期与核心流程](./workflows.md)。
 
-同一知识因此可以按使用频率和叙事粒度在不同层保留互补表达，而不是把整份文档复制到每轮 prompt，或把一个短规则强行扩展成长记录。
+## 读取路径：由近到远
 
-这些流程既能由 Agent 工具主动完成，也可以在 DSH 的记忆系统工作台中查看、核验和维护。
+一次依赖历史的问题按以下顺序扩展：
 
-## 用户与集成入口
+1. 当前请求、实时工具结果和仓库文件；
+2. 已在 prompt 中的 Runtime Memory；
+3. active Documents 的确定性检索与按需全文；
+4. 已激活 Memory Spaces 的监督召回；
+5. 命中冷引用后才读取 archived 原文。
 
-### Web 工作台
+`mnemon_recall` 会启动隔离 worker。worker 根据记忆体名称和说明选择最窄范围，只能使用允许的召回与关联工具；完整路由过程与整个目录不会灌入主对话。
 
-默认 `sidebar` 形态由左侧栏“记忆系统”入口打开独立主内容区工作台；可在设置中切换为 `buildin`，恢复原有对话区内嵌标签页。两种形态复用同一功能界面并实时互斥挂载。工作台提供八个页面，分为三组：「状态」独立成第一组；「运行时、记忆体、档案」对应三层存储；「沉淀、检索、实体、内容」为读写工具：
+Web 的“直接检索”返回原始证据；“Agent 查询”先取得相同证据，再让一个无 Mnemon 工具的 evidence-only worker 组织答案。
 
-`workspace` 存储范围下，顶部选择器是独立的“查看上下文”：可以留在当前对话不变的情况下查看和维护另一个已登记 DSH 工作区。Agent、工具和生命周期使用的是“执行上下文”，始终跟随当前会话 cwd。查看与执行目录不一致时，整个工作台都会显示路径差异和一键对齐入口；需要启动 Agent 的操作在未对齐时不会执行。
+## 写入路径：语义与系统保证分离
 
-| 页面 | 主要用途 |
+| 记忆 worker 负责 | Host 硬保证 |
 |---|---|
-| 状态 | CLI、运行时热记忆、存储域、生命周期和 subagent 诊断 |
-| 运行时 | USER / MEMORY 热记忆、容量和确定性维护 |
-| 记忆体 | Memory Space 目录、激活开关、元信息编辑和多空间实时图谱 |
-| 档案 | Documents 检索、阅读、编辑和归档 |
-| 沉淀 | 把候选交给受限 worker 查重、路由和写入 |
-| 检索 | direct recall、related 和 evidence-only Agent 查询 |
-| 实体 | 高频实体及其跨图上下文 |
-| 内容 | 浏览、复制、克隆或软删除长期记忆 |
-
-主要 Web 界面与设置卡支持中文和英文，并跟随 DSH 全局明暗主题。命令输出、工具卡和部分后端诊断仍未完全国际化。
-
-[![实体页面：高频实体、命中数量与实体相关上下文](./assets/screenshots/entities-context.png)](./assets/screenshots/entities-context.png)
-
-*实体页面按命中数量聚合名称，并在右侧保留相关记忆、类别、重要度、分数和记忆体来源。*
-
-[![内容页面：长期记忆筛选、标签、关系与维护操作](./assets/screenshots/memory-content.png)](./assets/screenshots/memory-content.png)
-
-*内容页面用于筛选和检查长期记忆，并提供查看关系、基于当前条目新建、复制 ID 与软删除操作。*
-
-### 模型工具与命令
-
-插件注册只读和写入两组 `mnemon_*` 模型工具，并提供：
-
-```text
-/mnemon status
-/mnemon recall <查询>
-/mnemon related <完整记忆 ID>
-/mnemon remember <稳定、自包含的长期洞察>
-/mnemon forget <完整记忆 ID>
-```
-
-Web RPC 是 DSH Host 与插件客户端之间的内部桥：读通道要求 `trusted-host`，记忆写通道和设置通道要求 `loopback`。它们不是稳定的外部 HTTP SDK。完整工具和 RPC 表见[WebUI、工具、命令与 RPC](./interfaces.md)。
-
-## 本地优先与可靠性设计
+| 判断候选是否值得保存 | 输入 schema 与操作权限 |
+| 选择最窄记忆体并查重 | 工作区与路径不能逃逸 |
+| 提炼自包含内容与关系理由 | CLI 禁用 shell，限制输出、超时与取消 |
+| 判断长内容是否应成为档案 | 文件锁、临时文件、rename 与 revision fence |
+| 在 persona 范围内保守维护 | UTF-8 容量与失败时保留原数据 |
 
-在可见性之外，插件还通过确定性边界约束路径、容量、并发与失败恢复。
+长期召回与写入优先使用隔离的 `spawn`；评分后台审查只在已完成回合达到门槛且持续空闲后使用 `fork`。新回合会取消等待或运行中的审查。
 
-- **本地数据**：SQLite、registry、Runtime JSON 和 Documents 都位于用户选定的根目录。
-- **无 shell 执行**：Mnemon CLI 使用 `spawn(command, args, { shell: false })`。
-- **有界进程**：单次调用有超时、取消和 2 MiB stdout + stderr 上限。
-- **并发控制**：Runtime 和 Documents 使用进程内队列与跨实例 lock file；CLI 调用在一个 Runner 内串行。
-- **原文优先保护**：revision 冲突、worker 失败或回执无效时，不用过期结果覆盖当前热记忆或移动 active Document。
-- **可恢复投影**：有效 `memories.json` 可以重建 `USER.md` 和 `MEMORY.md`。
-- **最小权限 worker**：每类 worker 都有固定 persona、工具白名单、结构化输出和 `maxDepth: 1`。
+## 用户能看到什么
 
-这些边界不等于秘密扫描器或完整备份系统。当前没有确定性凭据检测、跨系统回滚、内置一致快照或通用损坏修复工具。生产数据应建立独立备份与恢复演练，详见[运维、安全与故障排查](./operations.md)。
+默认 Sidebar 只有四个一级页面：状态、运行时、记忆体、档案。记忆体再分概览、检索、内容、实体；添加、编辑和沉淀使用统一弹窗，长列表采用筛选与渐进加载。
 
-“本地优先”描述的是持久化位置和 CLI 执行方式，并不保证被选中的内容永远不离开设备。若 DSH 的主模型或 subagent provider 运行在远端，相关 prompt、候选内容或召回证据仍可能发送给该 provider；数据处理边界取决于实际 DSH 模型配置。
+对话内还有两个增量入口：
 
-## 适用范围与版本状态
+- **本回合记忆**：汇总本轮记忆工具活动，并支持跳到对应页面；
+- **存入记忆**：把已定稿回复载入可编辑确认弹窗，只有确认后才启动监督写入。
 
-`dsh-mnemon` 适合：
+逐页截图与工作区查看 / 执行语义见 [Sidebar 与对话交互指南](./ui-guide.md)。工具、命令和 RPC 契约见[接口参考](./interfaces.md)。
 
-- 长期协作中需要稳定延续用户偏好和工作约定；
-- 大型项目需要保存设计理由、调查记录和交接知识；
-- 多个知识域需要隔离存储、选择性激活和跨空间召回；
-- 希望数据留在本地，同时让 LLM 负责语义判断；
-- 需要可查看、可编辑、可诊断的 DSH 原生记忆体验。
+## 本地优先与可靠性
 
-它不适合把秘密、原始日志、短期进度或可从仓库直接重建的普通事实批量写入长期存储，也不应被当作事实源、权限系统、备份系统或主动通知守护进程。
+- CLI 通过参数数组启动，`shell=false`；输出、超时与取消有界。
+- Runtime 与 Documents 使用进程内队列、跨实例锁、临时文件与 rename。
+- Runtime revision 阻止过期压缩覆盖；Document revision 阻止移动已更新原文。
+- 子 Agent 使用 persona、工具白名单、结构化输出和深度限制。
+- WebUI 不直接读取 SQLite，不从浏览器传入任意更新命令。
+- 插件不存储模型凭据，但当前也没有确定性的秘密扫描器。
 
-当前版本处于早期 Beta 阶段，仍在持续优化和迭代中；部分后续能力与演进计划见 [Roadmap](./roadmap.md)。
+这些保证不是跨 Mnemon SQLite 与文件系统的可回滚分布式事务；项目选择在不确定时保留原数据。完整边界与已知限制见[运维指南](./operations.md)。
 
 ## 继续阅读
 
-- 想立即运行：阅读[快速开始](./getting-started.md)。
-- 想理解代码边界：阅读[架构设计](./architecture.md)。
-- 想选择数据范围：阅读[存储与三层记忆模型](./storage-model.md)和[配置参考](./configuration.md)。
-- 想理解事务和 review：阅读[生命周期与核心流程](./workflows.md)。
-- 想部署或升级：阅读[运维、安全与故障排查](./operations.md)。
-- 想参与开发：阅读[开发与验证](./development.md)。
+- [快速开始](./getting-started.md)：安装与第一次验证。
+- [Sidebar 与对话交互指南](./ui-guide.md)：完整 UI 使用路径。
+- [架构设计](./architecture.md)：模块、worker 与信任边界。
+- [存储模型](./storage-model.md)：目录、容量与权威源。
+- [生命周期与核心流程](./workflows.md)：注入、召回、写入、审查与归档。
+- [配置参考](./configuration.md)：展示形态、存储范围与高级开关。