dsh-mnemon 0.1.0

package/docs/zh-CN/operations.md

@@ -0,0 +1,151 @@
+# 运维、安全与故障排查
+
+**简体中文** | [English](../en/operations.md) | [文档中心](./README.md)
+
+## 健康检查
+
+先检查二进制，再检查插件聚合状态：
+
+```sh
+command -v mnemon
+mnemon --version
+```
+
+```text
+/mnemon status
+```
+
+`mnemon status` 会打开有效 Store，上游 CLI 可能初始化默认数据或执行迁移；它不是完全无副作用的只读探测。插件状态页还会检查 active Memory Spaces、Documents、生命周期和 subagent 计数。
+
+## 安全边界
+
+### 进程
+
+- `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 自身的并发语义。
+
+### 文件
+
+- Runtime 和 Documents 都有进程内队列及跨实例 lock file。
+- 等待锁默认最多 5 秒；锁超过 30 秒才被视为 stale。
+- 写入使用临时文件和 rename。
+- Runtime 用 revision 阻止过期压缩覆盖并发修改。
+- Document 归档用数字 revision 阻止移动已被更新的 active 原文。
+- `sourcePaths` 不能逃出发起会话工作区，也不能指向受管 Documents 目录。
+
+### Web
+
+- 读 RPC：`trusted-host`。
+- 记忆写 RPC：`loopback`。
+- 设置 RPC：`loopback`。
+- WebUI 不直接读取 SQLite 或启动进程。
+
+### 模型
+
+- worker 使用 persona、工具白名单、结构化输出和 `maxDepth: 1`。
+- 用户查询、候选内容、Document 正文和历史记忆均按不可信数据处理。
+- 证据回答 worker 无 Mnemon 工具，只能使用 Host 提供的命中内容。
+
+这些边界不等于秘密扫描器。当前还没有确定性的凭据/秘密检测；不要向热记忆、Documents 或 Memory Spaces 提交密钥、token、私钥和原始敏感日志。
+
+## 备份
+
+三层数据共用 `storageRoot`，一致备份应覆盖整个根，而不是只复制 `mnemon.db`：
+
+```text
+<storageRoot>/runtime
+<storageRoot>/documents
+<storageRoot>/data
+<storageRoot>/state    # when present
+```
+
+推荐过程：
+
+1. 停止 DSH Host 和其他写入同一根的进程。
+2. 记录当前插件、DSH 和 `mnemon --version`。
+3. 复制整个根到新的、带时间戳的目录。
+4. 对备份执行文件清单或校验和。
+5. 在隔离路径中完成恢复演练后再依赖它。
+
+项目当前没有内置一致快照、导出或恢复命令；运行中直接复制可能捕获跨文件不一致状态。
+
+## 恢复
+
+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 不存在自动通用修复流程。
+
+## 切换存储范围
+
+插件不会自动迁移数据：
+
+```text
+old scope -- change setting + restart --> new empty or existing scope
+
+no implicit copy
+no implicit merge
+no implicit delete
+```
+
+需要迁移时，停止写入后复制完整根。合并两套根不能靠目录覆盖，因为 JSON index、registry 和多个数据库都可能冲突；应在备份上设计显式合并方案。
+
+## 故障排查
+
+| 现象 | 检查与处理 |
+|---|---|
+| Mnemon 不可用 | 运行 `command -v mnemon`、`mnemon --version`；设置 `MNEMON_CLI_PATH` 或 `cliPath` 后重启 |
+| 状态正常但召回为空 | 检查是否有 active Memory Space、当前 `storageScope`、DSH 启动 cwd 和查询是否足够聚焦 |
+| `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=false` 仍显示 Tab | 当前开关只停 Host 数据 RPC，不会移除客户端 slot |
+| 本地 link 不反映源码 | 先运行 `pnpm run build`，再重启 DSH profile |
+
+## 已知限制
+
+### 功能只读不等于磁盘只读
+
+`writeEnabled=false` 禁用语义 mutation，但启动时仍可能创建/修复 Runtime 文件，Document 搜索会更新 `lastAccessedAt`，Mnemon 读取也可能触发上游 migration。不要在真正只读文件系统上假设它能无写运行。
+
+### 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` 为准。这是待修复的路径表达差异。
+
+### 跨系统事务
+
+“先索引、后移动”保护 active 原文，但不是跨 Mnemon SQLite 与文件系统的可回滚分布式事务。索引成功后若 revision 冲突，索引可能保留为重复引用；插件选择保留数据而不是回滚已完成的长期写入。
+
+### 后台水位
+
+评分、最近 checkpoint 和重试状态没有持久化。Host 重启会清空尚未处理的活动；失败退避、熔断和人工重试入口也尚未实现。
+
+### 版本矩阵
+
+项目尚未声明正式的 DSH/Mnemon 支持矩阵和 schema migration 策略。升级必须先备份并在隔离根中验证。
+
+### 国际化
+
+主要 Web 工作台为中英文双语，但命令、工具卡、兼容默认元数据和部分错误信息尚未完整国际化。

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

@@ -0,0 +1,247 @@
+# 项目介绍：面向 DSH 的本地三层记忆系统
+
+**简体中文** | [English](../en/project-overview.md) | [文档中心](./README.md)
+
+> **`dsh-mnemon` 是 [Mnemon](https://github.com/mnemon-dev/mnemon) 与 DSH 的深度集成插件，为 DSH 提供完备的记忆体能力。**
+
+它把“每轮必须知道的内容”“需要完整阅读的项目知识”和“跨会话按需召回的长期历史”分别放在三个职责清晰的层级中，再由 DSH 提供路由、生命周期、受限子 Agent 和用户界面。
+
+项目的核心目标是：让 Agent 获得长期连续性，同时保持当前任务优先、上下文紧凑、写入可审计、失败时不丢原始数据。
+
+[![Mnemon 记忆体页：记忆体目录、激活状态与多空间实时关系图](./assets/screenshots/overview-memory-graph.png)](./assets/screenshots/overview-memory-graph.png)
+
+*记忆体页把记忆体目录、激活状态、统计信息和多空间关系图放在同一工作面中；点击图片可查看原始分辨率。*
+
+## 为什么需要它
+
+仅依赖当前对话上下文时，Agent 很难稳定延续用户偏好、项目约定和历史决策；把全部历史直接塞入 prompt，又会造成上下文膨胀、过期信息干扰和成本增加。单一记忆层级同样无法兼顾以下需求：
+
+| 需求 | 单一记忆层级的局限 | 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 何时主动使用能力，三层模型则决定信息以什么粒度保存、何时进入上下文。
+
+## 内置 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)
+
+*运行时页面并列展示 USER 与 MEMORY 两个投影的容量、重要度、分类和逐条编辑入口。*
+
+### 2. Project Documents：保留完整叙事的项目档案
+
+Documents 保存比单条记忆更完整、又需要快速阅读的知识，例如架构理由、调查结论、操作流程、故障复盘和实现交接。正文保持 Markdown 结构，并通过标题、description 和正文做确定性检索。
+
+单份正文最大 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 状态。
+
+- 读取只覆盖已激活记忆体；
+- 写入可以指定任意已登记记忆体；
+- 向 inactive 目标写入成功后会自动激活；
+- 新建记忆体时，模型提供语义名称和边界，Host 生成稳定 ID；
+- 合并通过非破坏性 import 完成，默认停用来源但不删除来源数据库。
+
+Mnemon 长期层保留 `temporal`、`semantic`、`causal` 和 `entity` 四类关系。召回结果携带 Memory Space 来源和记忆 ID，主 Agent 可以继续沿关系图获取上下文。
+
+完整目录、容量和权威源说明见[存储与三层记忆模型](./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)
+
+### 写入：语义判断与系统保证分离
+
+读取路径解决何时使用记忆；写入路径还需要约束谁来判断、谁来落盘，以及失败时如何保护原始数据。
+
+插件把语义判断与系统保证分开：
+
+| 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 要求和审查边界见工作流文档。
+
+召回、写入、容量维护、归档和评分公式详见[生命周期与核心流程](./workflows.md)。
+
+当用户明确要求记住稳定内容时，主 Agent 会根据内容类型使用结构化工具逐条写入，Host 继续负责目标、容量和 revision 校验。最终回复说明真正写入的内容，而不是把内部推理当作持久化结果。
+
+[![DSH 会话中的记忆写回：结构化 Runtime Memory 工具调用与写入回执](./assets/screenshots/conversation-writeback.png)](./assets/screenshots/conversation-writeback.png)
+
+### 三层协同示例：保存一项架构决策
+
+假设一次复杂任务确认了“所有外部 CLI 必须使用参数数组启动并禁止 shell”，同时产出完整的威胁分析和迁移说明：
+
+1. 这条高频执行约定可以作为简短事实进入 `MEMORY.md`，从下一轮开始直接可见。
+2. 完整分析和迁移步骤适合进入 active Document，保留标题、章节、代码片段和来源文件。
+3. 若该决策需要跨项目长期召回，受限 worker 会选择合适的 Memory Space，先查重，再写入自包含决策，并可与相关安全原则建立关系。
+4. 未来询问“为什么不能拼接 shell 命令”时，Agent 先看到热层规则；需要理由时搜索 Document；需要跨会话关联时再召回 Mnemon 证据。
+5. 当 Document 长期不再频繁访问且 active 容量不足时，插件先写入带摘要和哈希的冷引用，再迁移原文。未来仍可沿引用追溯完整分析。
+
+同一知识因此可以按使用频率和叙事粒度在不同层保留互补表达，而不是把整份文档复制到每轮 prompt，或把一个短规则强行扩展成长记录。
+
+这些流程既能由 Agent 工具主动完成，也可以在 DSH 的记忆系统工作台中查看、核验和维护。
+
+## 用户与集成入口
+
+### Web 工作台
+
+会话“记忆系统”Tab 提供八个页面，分为三组：「状态」独立成第一组；「运行时、记忆体、档案」对应三层存储；「沉淀、检索、实体、内容」为读写工具：
+
+| 页面 | 主要用途 |
+|---|---|
+| 状态 | 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)。
+
+## 本地优先与可靠性设计
+
+在可见性之外，插件还通过确定性边界约束路径、容量、并发与失败恢复。
+
+- **本地数据**：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)。
+
+“本地优先”描述的是持久化位置和 CLI 执行方式，并不保证被选中的内容永远不离开设备。若 DSH 的主模型或 subagent provider 运行在远端，相关 prompt、候选内容或召回证据仍可能发送给该 provider；数据处理边界取决于实际 DSH 模型配置。
+
+## 适用范围与版本状态
+
+`dsh-mnemon` 适合：
+
+- 长期协作中需要稳定延续用户偏好和工作约定；
+- 大型项目需要保存设计理由、调查记录和交接知识；
+- 多个知识域需要隔离存储、选择性激活和跨空间召回；
+- 希望数据留在本地，同时让 LLM 负责语义判断；
+- 需要可查看、可编辑、可诊断的 DSH 原生记忆体验。
+
+它不适合把秘密、原始日志、短期进度或可从仓库直接重建的普通事实批量写入长期存储，也不应被当作事实源、权限系统、备份系统或主动通知守护进程。
+
+当前版本处于早期 Beta 阶段，仍在持续优化和迭代中；部分后续能力与演进计划见 [Roadmap](./roadmap.md)。
+
+## 继续阅读
+
+- 想立即运行：阅读[快速开始](./getting-started.md)。
+- 想理解代码边界：阅读[架构设计](./architecture.md)。
+- 想选择数据范围：阅读[存储与三层记忆模型](./storage-model.md)和[配置参考](./configuration.md)。
+- 想理解事务和 review：阅读[生命周期与核心流程](./workflows.md)。
+- 想部署或升级：阅读[运维、安全与故障排查](./operations.md)。
+- 想参与开发：阅读[开发与验证](./development.md)。

package/docs/zh-CN/roadmap.md

@@ -0,0 +1,41 @@
+# Roadmap
+
+**简体中文** | [English](../en/roadmap.md) | [文档中心](./README.md)
+
+Roadmap 记录当前实现之外的工作，不是已交付能力承诺。优先级以数据安全、可恢复性和可验证性为先。
+
+## P0：可靠性与可恢复调度
+
+- [ ] **持久化后台审查水位**：按 root session 保存活动信号、最近处理 checkpoint、评分版本和运行状态；重启或 resume 后恢复未处理活动。
+- [ ] **幂等 checkpoint**：为一次审查输入建立稳定标识，避免超时、重试或重复 hook 产生重复 Document。
+- [ ] **退避、熔断和人工重试**：连续失败后有上限地退避，状态页展示原因并允许显式恢复。
+- [ ] **确定性敏感信息防线**：在 LLM 准入之外增加秘密/凭据模式检测、大小限制和审计回执。
+- [ ] **自动化真实 WebUI E2E**：隔离 DSH_HOME、storageRoot、workspace 和端口，覆盖轻任务、评分审查、取消和失败无半写入。
+- [ ] **修正 `tabEnabled` 语义**：Host 和 client 使用同一开关，真正注册或移除完整 Tab 能力。
+- [ ] **修正冷引用路径**：所有 storage scope 都写入与实际托管路径一致的可解析引用。
+
+## P1：长期维护与数据运维
+
+- [ ] **跨 session 长期整理**：基于时间和新增 session 数触发独立整理，而不是复用逐 turn 审查。
+- [ ] **Mnemon GC / forget 审阅**：生成衰减、冲突、过时内容和孤立关系候选，展示证据后再执行删除。
+- [ ] **一致性备份与恢复**：为 registry、多个数据库、Runtime 和 Documents 提供统一快照、校验和恢复演练。
+- [ ] **修复与重建工具**：检测损坏 JSON、缺失投影、孤儿 Document、缺失 DB 和 registry/磁盘不一致。
+- [ ] **schema migration**：为 Runtime、Documents index 和 Memory Space registry 增加显式升级与回滚策略。
+- [ ] **兼容矩阵**：记录并自动测试支持的 DSH、Mnemon CLI、Node 和数据格式组合。
+- [ ] **明确 Documents workspace ownership**：在共享 storage scope 中记录来源工作区或提供可配置隔离策略。
+
+## P2：可观测性、体验与发布工程
+
+- [ ] **后台审查历史**：展示最近评分、checkpoint、等待/运行/失败、worker 回执和产生的变更。
+- [ ] **完整国际化**：覆盖命令、工具卡、Host 错误、兼容默认元数据和确认文案。
+- [ ] **多记忆体 E2E**：覆盖自动建空间、跨空间召回、一次迁移分流、多种边、合并和受控 forget。
+- [ ] **容量与故障注入**：真实触发 USER/MEMORY 边界、Document LRU、revision 冲突、CLI 超时和 Host 中途重启。
+- [ ] **文档一致性检查**：相对链接、外链、双语文件镜像、配置键和代码块一致性进入 CI。
+- [ ] **发布收口**：稳定版本号、变更日志、升级/卸载/数据保留指南、artifact 校验和最小支持策略。
+
+## 当前明确不在范围内
+
+- Runtime `daily` target；当前只维护 `user` 和 `memory`。
+- 没有明确触达语义的主动通知守护进程；Mnemon 仍是按需拉取系统。
+- 把内部 RPC 或 `MnemonClient` 宣布为稳定公共 SDK。
+- 自动删除来源 Memory Space 数据库；当前 merge 保留来源文件。

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

@@ -0,0 +1,179 @@
+# 存储与三层记忆模型
+
+**简体中文** | [English](../en/storage-model.md) | [文档中心](./README.md)
+
+## 为什么是三层
+
+一种存储形态无法同时满足“每轮都可见”“保留完整叙事”和“长期图增强召回”：
+
+| 问题 | 对应层 | 原因 |
+|---|---|---|
+| 下一轮必须直接知道什么？ | Runtime Memory | 极小、直接进入 prompt |
+| 哪份设计或流程需要快速完整阅读？ | active Documents | 保留 Markdown 结构，不必做深召回 |
+| 哪些历史事实和关系应跨会话存在？ | Memory Spaces | 独立数据库、图关系、按需召回 |
+| 长文已不常用但仍需追溯怎么办？ | archived Documents | Mnemon 留索引，冷层保留原文 |
+
+推荐查询梯度：
+
+```text
+current request and repository facts
+             |
+             v
+Runtime Memory already in prompt
+             |
+             v
+search active Documents
+             |
+             v
+recall active Memory Spaces
+             |
+             v
+follow an exact cold reference when full text is required
+```
+
+## 统一根目录
+
+```text
+<storageRoot>/
++-- runtime/
+|   +-- memories.json
+|   +-- USER.md
+|   +-- MEMORY.md
++-- documents/
+|   +-- index.json
+|   +-- active/
+|   +-- archived/
++-- data/
+|   +-- .dsh-memory-bodies.json
+|   +-- <memory-space-id>/
+|       +-- mnemon.db
++-- state/                         # reserved; no persistent reviewer yet
+```
+
+`storageScope` 决定整个根，而不只是 Mnemon 数据库。`state/` 当前只会被状态盘点器识别；评分水位仍保存在运行中 Host 的内存中。
+
+## Runtime Memory
+
+### 语义
+
+- `target=user`：身份、角色、长期偏好、习惯、沟通风格和明确协作要求。
+- `target=memory`：项目、环境、决策、约定、工具特性和可复用经验。
+- `importance=critical|normal|low`：用于整理时的保留优先级。
+
+当前不实现 `daily` target。
+
+### 事实源和投影
+
+`runtime/memories.json` 是唯一事实源。每条记录包含：
+
+```text
+content
+created_at
+updated_at
+target
+importance
+```
+
+`USER.md` 和 `MEMORY.md` 是确定性派生文件。每个条目被归一成单行，条目之间使用单独一行的 `§` 分隔；`§` 是保留字符。启动和 prompt 组装时，控制层会从 JSON 修复缺失或被手工修改的投影。
+
+### 操作
+
+- `add` 写入独立新事实，完全相同的内容不会重复添加。
+- `replace` 用 `old_text` 的唯一子串定位并替换整个条目。
+- `remove` 用唯一子串移除整个条目。
+- 零命中或多命中都拒绝，不执行模糊修改。
+
+### 容量
+
+| 目标 | 上限 | 维护方式 |
+|---|---:|---|
+| `USER.md` | 4 KiB | 本地、无工具 worker 保守合并，不进入 Memory Space |
+| `MEMORY.md` | 10 KiB | worker 先归档已提交内容，再返回压缩候选 |
+
+容量按投影正文的实际 UTF-8 字节计算。单条内容最大 8 KiB。自动容量维护只由溢出的 `add` 触发；导致溢出的 `replace` 会直接报错，调用方应先显式整理。
+
+## Project Documents
+
+### 用途
+
+Documents 保存比单条记忆更完整、又希望快速阅读的项目知识，例如：
+
+- 架构设计和理由；
+- 有证据的调查结论；
+- 操作流程、发布清单和故障复盘；
+- 实现交接与长期维护说明。
+
+用户画像、普通聊天、临时进度、原始大日志和秘密不应进入 Documents。
+
+### 控制面
+
+`documents/index.json` 是元数据事实源，管理 ID、标题、description、状态、文件名、来源路径、session、时间、revision、SHA-256、大小和 Memory Space 引用。Markdown 托管副本带有生成的 frontmatter。
+
+`sourcePaths`：
+
+- 只能指向当前会话工作区内部；
+- 只作为来源引用，不会被插件修改；
+- 当前实现不要求路径实际存在；
+- 不允许指向受管 `documents/` 目录自身。
+
+### 范围
+
+Documents 的物理共享范围由 `storageScope` 决定：
+
+- `workspace`：通常随项目隔离；
+- `global` / `custom`：多个工作区可能共享同一个 `documents/index.json`。
+
+因此“项目档案”表示内容类型，不保证天然按工作区物理隔离。当前会话工作区只约束新写入的 `sourcePaths`。
+
+### 容量与冷热分层
+
+| 项目 | 限制 |
+|---|---:|
+| 单份正文 | 最大 2 MiB |
+| active 总量 | 最大 10 MiB，包含生成后的 frontmatter |
+| archived 总量 | 不计 active 上限 |
+
+创建或更新前会计算真实投影大小。空间不足时按 `lastAccessedAt`、再按 `updatedAt` 选择最久未访问的 active 文档；先写入/验证 Mnemon 冷引用，再在 revision 未变化时迁移原文。
+
+默认搜索只覆盖 active。搜索会更新命中文档的 `lastAccessedAt`，因此它对正文只读，但会写索引元数据。
+
+## Memory Spaces
+
+每个记忆体是一个 Mnemon 原生命名 Store，并在 `.dsh-memory-bodies.json` 中增加可维护元数据：
+
+```text
+id            Host 生成的稳定 UUID 或已发现的兼容 Store 名
+name          人类可读名称
+description   路由边界：什么属于这里、何时召回
+active        是否参与读取
+mnemon.db     独立数据面
+```
+
+### 读写边界
+
+- 召回、图谱、内容和实体读取只使用已激活记忆体。
+- 指定未激活记忆体进行读取会被拒绝。
+- 写入可以选择已登记的任意记忆体。
+- 对未激活目标写入成功后，插件自动激活它。
+- 没有显式目标且激活数量不是 1 时，确定性服务要求调用方先选择目标。
+
+### 创建、发现和合并
+
+- 创建时模型提供 name 和 description，Host 生成 ID。
+- 既有 `<storageRoot>/data/<store>/mnemon.db` 会被发现并登记，不移动数据库。
+- 合并通过 Mnemon import 把来源内容导入目标；来源数据库保留，默认只将来源设为未激活。
+- `forget` 是按精确 ID 的软删除，不等于删除数据库文件。
+
+## 四类关系
+
+Mnemon 长期层保留 `temporal`、`semantic`、`causal` 和 `entity` 关系。插件不会要求每条记忆都手工创建关系；关系应在确实能改善未来召回时建立。记忆体页可以聚合多个已激活记忆体的记忆、实体、关系和空间归属。
+
+## 数据权威表
+
+| 数据 | 权威源 | 派生/缓存 |
+|---|---|---|
+| 热记忆 | `runtime/memories.json` | `USER.md`、`MEMORY.md` |
+| Documents | `documents/index.json` + 托管 Markdown | excerpt、搜索排序、状态聚合 |
+| Memory Space 目录 | `data/.dsh-memory-bodies.json` + 磁盘 Store | Web 状态聚合 |
+| 长期记忆 | 各 Store 的 `mnemon.db` | HTML/DOT 图谱解析结果 |
+| 审查水位 | Host 进程内存 | 状态页快照；尚未持久化 |