dsh-mnemon 0.1.2 → 0.1.4

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 错误与兼容元数据尚未完全国际化。

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 界面为中英文双语，但命令、工具卡、兼容元数据和部分错误仍未完全国际化。