dsh-mnemon 0.1.2 → 0.1.4

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

@@ -1,249 +1,145 @@
-# 项目介绍：面向 DSH 的本地三层记忆系统
+# 项目介绍：面向 DSH 的本地三层与跨 Agent 共享记忆系统
 
 **简体中文** | [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 原生界面。因为长期层使用 Mnemon 原生 Store，DSH 也获得了与其他 Mnemon-enabled Agent 复用同一套本地长期记忆的能力。
 
-它把“每轮必须知道的内容”“需要完整阅读的项目知识”和“跨会话按需召回的长期历史”分别放在三个职责清晰的层级中，再由 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)。
+| 下一轮必须知道用户偏好和稳定约定 | 每次检索有延迟，也可能漏召回 | 运行时记忆每轮注入紧凑投影 |
+| 阅读完整设计、调查或流程 | 切成碎片会失去叙事和来源 | 档案保留受管 Markdown 全文 |
+| 跨会话查找事实、决策和关系 | 全量加载会污染上下文 | 记忆体按需返回有界图增强证据 |
+| 保留不常用长文的可追溯性 | 永久留在热层持续占容量 | 先建立冷引用，再迁移原文 |
+| 让模型判断价值但不掌握系统安全 | LLM 无法保证路径、锁和事务 | worker 负责语义，Host 负责硬边界 |
 
-架构边界决定谁可以执行操作，内置 Prompt 决定 LLM 何时主动使用能力，三层模型则决定信息以什么粒度保存、何时进入上下文。
-
-## 内置 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 保存高频且紧凑的稳定信息：
-
-- `target=user`：身份、角色、长期偏好、习惯、沟通风格和明确协作要求；
-- `target=memory`：项目约定、环境事实、决策、工具特性和可复用经验。
-
-`runtime/memories.json` 是唯一事实源，`USER.md` 和 `MEMORY.md` 是每轮注入 prompt 的确定性投影。USER 上限为 4 KiB，MEMORY 上限为 10 KiB，单条内容最大 8 KiB，均按 UTF-8 字节计算。
-
-普通 `add`、`replace` 和 `remove` 由确定性控制层完成。只有 `add` 造成容量溢出时才触发维护：USER 在本地由无工具 worker 保守合并；MEMORY 先由受限 worker 归档长期语义，再压缩热层候选。导致溢出的 `replace` 会直接拒绝，不会自动整理。
-
-[![运行时记忆页面：USER 与 MEMORY 热记忆、容量和编辑操作](./assets/screenshots/runtime-memory.png)](./assets/screenshots/runtime-memory.png)
+### 1. 运行时记忆
 
-*运行时页面并列展示 USER 与 MEMORY 两个投影的容量、重要度、分类和逐条编辑入口。*
+运行时层保存高频、紧凑、每轮都可能使用的信息：
 
-### 2. Project Documents：保留完整叙事的项目档案
+- `USER.md`：身份、角色、偏好、习惯和明确协作要求；
+- `MEMORY.md`：项目约定、环境事实、决策、工具特性与可复用经验。
 
-Documents 保存比单条记忆更完整、又需要快速阅读的知识，例如架构理由、调查结论、操作流程、故障复盘和实现交接。正文保持 Markdown 结构，并通过标题、description 和正文做确定性检索。
+`runtime/memories.json` 是唯一事实源，两个 Markdown 文件是确定性投影。USER 上限 4 KiB，MEMORY 上限 10 KiB，均按 UTF-8 字节计算。普通增删改由控制层执行；只有容量维护才可能启动 worker。
 
-单份正文最大 2 MiB，active Documents 渲染后总量最大 10 MiB。容量不足或人工归档时，插件先让受限 worker 在 Mnemon 中建立带摘要和 SHA-256 的冷引用，再在 Document revision 未变化时把原文移入 `archived/`。这一顺序优先保护 active 原文，但不是跨 SQLite 与文件系统的可回滚分布式事务。
+### 2. 项目档案
 
-Documents 的共享范围跟随 `storageScope`。在 `global` 或 `custom` 下，多个工作区可能共享同一个 Document index；当前会话工作区只约束新写入的 `sourcePaths`，不构成独立 ownership。
+档案保存需要完整结构的设计、调查、流程、复盘和交接。标题、检索说明与正文参与确定性搜索，正文保持 Markdown。
 
-[![项目档案页面：Document 列表、元数据与 Markdown 原文渲染](./assets/screenshots/documents-markdown.png)](./assets/screenshots/documents-markdown.png)
+单份正文最大 2 MiB，active 总量最大 10 MiB。人工归档或容量整理时，插件先让受限 worker 在 Mnemon 写入带摘要与 SHA-256 的冷引用，再在 revision 未变化时移动原文。失败或冲突时优先保留 active 原文。
 
-*档案页面保留 Document 元数据与 Markdown 结构，列表选择、检索和正文阅读在同一页面完成。*
+### 3. 记忆体
 
-### 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 可以继续沿关系图获取上下文。
-
-完整目录、容量和权威源说明见[存储与三层记忆模型](./storage-model.md)。
-
-三层并非彼此孤立的仓库，而是组成了一条由近到远、按需扩展的查询路径；信息也可以在明确写入或受控维护时，以适合其频率和粒度的形式沉淀下来。
-
-## 从当前请求到长期沉淀
-
-### 读取：由近到远，按需升级
+- 写入可以选择任何已登记目标，成功后自动激活；
+- 长期层保留时间、语义、因果和实体四类关系；
+- 召回返回记忆体来源与记忆 ID，后续可以继续查看关联。
 
-插件遵循由近到远的查询梯度：
+三层的权威文件、容量与目录结构见[存储与三层记忆模型](./storage-model.md)。
 
-1. 当前请求、实时工具结果和仓库事实优先；
-2. 主 Agent 已能看到每轮注入的 Runtime Memory；
-3. 需要完整项目知识时，先确定性搜索 active Documents；
-4. 需要历史决策、跨会话事实或关系时，再调用监督召回；
-5. 命中冷引用且确需全文时，最后读取 archived Document 原文。
+## 跨 Agent 共享边界
 
-主 Agent 调用 `mnemon_recall` 后，coordinator 启动一个隔离 worker。worker 只能查看记忆体目录、执行 recall 和遍历 related；它根据名称与 description 选择 active Memory Spaces，返回有上限的结构化证据。原始路由推理和完整目录不会被灌入主对话。
+这里的“共享”不是 dsh-mnemon 把对话或文件主动广播给任意 Agent，而是多个已接入 Mnemon 的 Agent 使用同一套本地 Mnemon 数据：
 
-Web 的直接检索走确定性服务；“Agent 查询”则先完成相同检索，再启动一个无 Mnemon 工具的 evidence-only worker，只根据命中内容组织答案并返回有效 citation。
+1. 每个参与方都安装并接入 Mnemon；
+2. 每个参与方都能访问同一个 `storageRoot`；
+3. 需要共享的长期记忆位于各方共同识别的 Mnemon Store 中。
 
-[![检索页面：Agent 查询答案、来源记忆 ID 与原始召回结果](./assets/screenshots/recall-agent-answer.png)](./assets/screenshots/recall-agent-answer.png)
+满足这些条件后，在 DSH 中写入的长期事实、实体与关系可以由其他 Mnemon-enabled Agent 召回，反向写入也能被 DSH 发现。共享范围只覆盖 Mnemon Memory Spaces；`runtime/` 和 `documents/` 是 dsh-mnemon 管理的 DSH 层，不会仅因共用目录就自动成为其他 Agent 的上下文。
 
-*“Agent 查询”把证据限定在本次命中范围内，同时保留来源记忆 ID 和原始召回条目，方便核验答案。*
+`global` 默认根 `~/.mnemon` 最适合本机多个 Agent 共享；`custom` 适合显式约定的公共根；`workspace` 则把共享限制在对应项目目录。多个进程同时访问时依赖 Mnemon / SQLite 的并发语义，离线复制、迁移或直接修改数据库前应先停止所有使用者。
 
-真实会话中，主 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)：展示形态、存储范围与高级开关。

package/docs/zh-CN/storage-model.md

@@ -164,6 +164,12 @@ mnemon.db     独立数据面
 - 合并通过 Mnemon import 把来源内容导入目标；来源数据库保留，默认只将来源设为未激活。
 - `forget` 是按精确 ID 的软删除，不等于删除数据库文件。
 
+### 跨 Agent 可见性
+
+`mnemon.db` 是 Mnemon 原生数据面，不是 dsh-mnemon 私有格式。其他 Mnemon-enabled Agent 在使用同一个 `storageRoot` 和 Store 时，可以访问同一份长期记忆。dsh-mnemon 也会发现磁盘上兼容的 Store；其 DSH 专有名称、说明和激活状态仍由 `.dsh-memory-bodies.json` 管理。
+
+共享不延伸到 `runtime/` 或 `documents/`。即使它们位于同一个根，其他 Agent 也必须自行实现相应协议才能理解这些 DSH 管理层；不能把“共享 Mnemon 长期记忆”表述为自动共享完整 DSH 上下文。
+
 ## 四类关系
 
 Mnemon 长期层保留 `temporal`、`semantic`、`causal` 和 `entity` 关系。插件不会要求每条记忆都手工创建关系；关系应在确实能改善未来召回时建立。记忆体页可以聚合多个已激活记忆体的记忆、实体、关系和空间归属。

package/docs/zh-CN/ui-guide.md

@@ -0,0 +1,160 @@
+# Sidebar 与对话交互指南
+
+**简体中文** | [English](../en/ui-guide.md) | [文档中心](./README.md)
+
+本指南以默认的 `sidebar` 形态为主，按真实使用路径介绍记忆系统。截图来自 v0.1.4 实机界面；数量、名称和内容会随你的数据变化。
+
+## 先认识两种展示形态
+
+在 DSH 的“设置 → 记忆系统”中选择入口与存储位置：
+
+[![记忆系统设置：Sidebar、Buildin、存储位置、对话界面与备份迁移](../assets/screenshots/settings-memory-system.png)](../assets/screenshots/settings-memory-system.png)
+
+| 形态 | 适合场景 |
+|---|---|
+| **Sidebar**（默认） | 从 DSH 左侧栏进入独立工作台；外观与任务看板、SSH 等官方面板一致，适合日常管理 |
+| **Buildin** | 在对话区内打开原有标签页；保留之前的布局和视觉，适合依赖旧工作流的用户 |
+
+两种形态共享功能、数据和 Host 服务，只拆分入口与外观。保存后实时切换，不需要刷新浏览器，也不会同时挂载两个入口。
+
+## 工作台结构
+
+Sidebar 顶部始终回答三个问题：
+
+1. 现在打开的是“记忆系统”；
+2. 存储位置使用全局、工作区还是自定义模式；
+3. Host 是否已连接。
+
+主体只有四个一级标签：**状态、运行时、记忆体、档案**。记忆体内部再分为**概览、检索、内容、实体**；“沉淀记忆”固定为这一层的主要动作。
+
+## 1. 状态：先确认系统是否可用
+
+[![状态页：版本、运行时、记忆体、档案与存储根摘要](../assets/screenshots/status-overview.png)](../assets/screenshots/status-overview.png)
+
+状态页聚合以下信息：
+
+- Mnemon CLI 与 dsh-mnemon 当前版本；
+- USER / MEMORY 运行时条目数；
+- 已激活记忆体与长期记忆数量；
+- active / archived 档案数量；
+- 当前存储根，以及 Runtime、Documents、Memory Spaces 三个实际目录。
+
+如果这里显示异常，先不要沉淀或归档；从[故障排查](./operations.md#故障排查)开始检查。
+
+### 检查与更新版本
+
+点击版本区域会打开只读检查面板：
+
+[![检查与更新 Mnemon 和 dsh-mnemon 版本](../assets/screenshots/version-check.png)](../assets/screenshots/version-check.png)
+
+检查不会自动安装。只有识别到受支持的安装来源并发现新版本时，才会出现“更新”。更新完成后界面会自动重新检查并刷新系统状态；dsh-mnemon 更新后仍需重启 `dsh web` 才能加载新代码。
+
+## 2. 运行时：管理每轮都会使用的热记忆
+
+[![运行时记忆：容量摘要、范围筛选、内容筛选与统一列表](../assets/screenshots/runtime-memory.png)](../assets/screenshots/runtime-memory.png)
+
+页面上方分别显示用户画像（`USER.md`）和工作记忆（`MEMORY.md`）的条目与容量；下方是统一列表。
+
+- 用“全部 / 用户画像 / 工作记忆”筛选范围；
+- 用右侧输入框按内容筛选；
+- 标签显示来源和重要性；
+- “编辑”打开弹窗，“移除”进入危险操作流程；
+- 长列表通过“再显示 N 条”逐步展开。
+
+### 添加运行时记忆
+
+[![添加热记忆弹窗：内容、分类与重要性](../assets/screenshots/runtime-memory-add.png)](../assets/screenshots/runtime-memory-add.png)
+
+一条运行时记忆应当简洁、独立、未来仍然常用。用户身份、偏好与明确协作要求放入“用户画像”；项目、环境、决策和工具经验放入“工作记忆”。临时进度、原始日志和一次性事实不适合这里。
+
+## 3. 记忆体：管理长期记忆与关系
+
+### 概览
+
+[![记忆体概览：目录卡片、激活开关与多空间关系图](../assets/screenshots/overview-memory-graph.png)](../assets/screenshots/overview-memory-graph.png)
+
+目录卡片先展示名称和路由说明，右上角是读取激活开关，底部是统计与编辑 / 删除操作。激活只控制读取范围；写入可以选择已登记但未激活的目标，成功后会自动激活。
+
+下方关系图聚合全部已激活记忆体。布局、拖拽和重置只影响当前浏览器展示，不会修改 Mnemon 数据。
+
+### 沉淀记忆
+
+[![沉淀记忆弹窗：候选内容与可选高级约束](../assets/screenshots/remember-dialog.png)](../assets/screenshots/remember-dialog.png)
+
+默认只需填写候选内容。确认后，隔离的记忆子 Agent 会判断是否值得保存、选择最窄记忆体、查重、提炼并写入。“人工高级选项”只用于确实需要约束目标记忆体、分类或重要性时。
+
+### 检索
+
+[![记忆检索：查询、分类、策略、原始召回与加载更多](../assets/screenshots/recall-agent-answer.png)](../assets/screenshots/recall-agent-answer.png)
+
+- **直接检索**返回原始证据，不启动回答 Agent；
+- **Agent 查询**先取得相同证据，再让无 Mnemon 工具的 evidence-only worker 组织答案；
+- 分类与策略可以缩小范围；
+- 结果保留记忆体来源、分类、重要性、分数与 ID；
+- “查看关联”继续沿图遍历，“忘记”属于破坏性语义操作。
+
+使用具体问题比宽泛关键词更可靠。例如“这个项目为什么禁止 shell 拼接？”通常优于“项目架构”。
+
+### 内容与实体
+
+| 内容 | 实体 |
+|---|---|
+| [![记忆内容列表与筛选](../assets/screenshots/memory-content.png)](../assets/screenshots/memory-content.png) | [![实体查询与相关记忆](../assets/screenshots/entities-context.png)](../assets/screenshots/entities-context.png) |
+
+- **内容**用于无召回副作用地浏览长期记忆，并按文本或分类筛选；可以查看关联、基于当前内容新建、复制 ID 或忘记。
+- **实体**先显示高频实体，选择或输入名称后聚合跨事实、决策与上下文的相关记忆。
+
+两页都采用可见数量 / 总数和加载更多，避免大量数据一次撑满页面。
+
+## 4. 档案：保留完整项目叙事
+
+[![项目档案：容量摘要、渐进目录与独立 Markdown 阅读器](../assets/screenshots/documents-markdown.png)](../assets/screenshots/documents-markdown.png)
+
+档案适合设计、调查、流程、复盘和交接。左侧目录分批加载，右侧保留标题、检索说明、来源、revision、哈希、文件大小与完整 Markdown；切换文档时阅读区会回到顶部。
+
+达到 active 容量上限前，最久未使用的档案会先在 Mnemon 中建立冷引用，再迁入 archived；失败或 revision 冲突时保留 active 原文。
+
+### 新建档案
+
+[![创建托管档案弹窗](../assets/screenshots/document-create-dialog.png)](../assets/screenshots/document-create-dialog.png)
+
+标题与检索说明决定未来是否容易找到，来源路径用于追溯；正文保留 Markdown 结构。原项目文件始终只读，工作台创建的是受管副本。
+
+## 5. 对话内交互
+
+### 本回合记忆
+
+[![展开本回合记忆：召回、档案检索与精确工具跳转](../assets/screenshots/conversation-turn-memory.png)](../assets/screenshots/conversation-turn-memory.png)
+
+只有已完成且发生记忆活动的回合才显示这一行。展开后列出具体工具；点击工具名会打开对应页面，并保留当前会话上下文。
+
+[![从本回合记忆跳转到记忆体检索页](../assets/screenshots/conversation-memory-jump.png)](../assets/screenshots/conversation-memory-jump.png)
+
+### 存入记忆
+
+[![确认存入记忆：编辑候选后再交给记忆子 Agent](../assets/screenshots/conversation-save-dialog.png)](../assets/screenshots/conversation-save-dialog.png)
+
+“存入记忆”位于已定稿助手回复的原生操作区。点击只会打开确认弹窗并读取这条回复；可以修改候选或取消。只有点击“确认并交给记忆子 Agent”才会执行写入流程。
+
+## 工作区模式：查看与执行分离
+
+`storageScope=workspace` 下需要区分两个概念：
+
+| 概念 | 由什么决定 | 影响什么 |
+|---|---|---|
+| **查看工作区** | 工作台顶部的工作区选择器 | 当前页面展示和人工维护哪套 `<workspace>/.mnemon` |
+| **执行工作区** | 当前对话 / Agent 的 cwd | 工具、命令、生命周期与子 Agent 实际使用哪套目录 |
+
+因此，你可以留在项目 A 的对话中查看项目 B 的记忆，但 Agent 仍然使用项目 A。两者不一致时，顶部会显示提示与一键对齐；需要 Agent 子任务的操作会被 Host 拒绝，防止写错项目。切换查看工作区会先卸载旧页面状态，再加载新目录。
+
+`global` 与 `custom` 只有一个明确存储根，不需要这层对齐。
+
+## 常见交互规则
+
+- 蓝色实心按钮表示当前主要动作；蓝色描边通常用于编辑；红色用于移除、删除、归档或忘记；中性按钮用于查看、复制与取消。
+- 删除记忆体等物理危险操作需要独立确认；“忘记”是长期语义软删除，也只应在明确需要时使用。
+- 保存配置后页面自动清理旧状态并重新读取，无需浏览器刷新。
+- Sidebar 的一级页头保持稳定；记忆体内部二级内容标题随内容自然滚动。
+- Buildin 保留既有布局和视觉，功能说明仍可参考本指南，但控件位置可能不同。
+
+下一步：[快速开始](./getting-started.md) · [存储模型](./storage-model.md) · [配置参考](./configuration.md) · [运维指南](./operations.md)