Web、Headless、工具、命令与 RPC

本页是集成参考。日常使用请先看 Sidebar 与对话交互指南。

#记忆空间命名与兼容性

产品统一使用记忆空间（memory space）。Source 导出 MemorySpace、MemorySpaceView、MemorySpaceCatalog 及对应的请求和元数据类型；已发布的 MemoryBody* 类型作为弃用别名保留，数据形状不变。

既有 v0.5.x 标识，如 mnemon_memory_bodies、mnemon_memory_body_create、body-directory 和 memoryBodyId / memoryBodyIds，仍表示记忆空间。为兼容已安装的工具、Source 页面、Provider 适配器和持久化的 Document/Pack 来源信息，这些标识保持稳定；.dsh-memory-bodies.json 文件名与其中的 bodies 字段也继续保留。术语调整不会重命名用户创建的空间、修改 ID、移动数据库或改变访问授权。

#用户界面入口

displayMode 选择 sidebar（默认）或 builtin（会话标签页）；tabEnabled 控制所选入口是否显示。会话标签页不展示 Sidebar 的范围控件。对话内两个快捷入口在界面中分别开关，通过 mnemon-ui 设置范围保存。

#Profile 能力面

Headless 会获得完整模型工具面。它把命令行任务作为普通用户消息提交，不提供交互式斜杠命令分发；Agent 进入 idle 前已经完成的显式和模型引导写入会持久化。

模型工具、生命周期 hook 与系统调度都使用 automatic trigger；Web/RPC 中由用户直接发起的数据面操作使用 manual trigger。因此把某层设为 manual 会保留人工管理能力，同时拒绝模型工具和自动投影。memory-system 与 status 属于控制面观察，即使某层关闭也仍可读取。

#模型工具

#只读工具

“只读”表示不修改受管正文或长期语义内容。mnemon_document_search 命中后仍会更新 lastAccessedAt，用于 LRU 排序，因此功能只读不等于磁盘只读。

#writeEnabled=true 时的工具

worker 内调用同名工具时直接进入服务层，不再递归委派。

自主 write worker（蒸馏与 supervised writeback 运行）自行决定写入内容，因此宿主在其硬性工具白名单中排除了 mnemon_forget：遇到重复或冲突时只能跳过或写入修正后的条目，不能删除已有记忆。请求目标由用户或用户侧流程显式给出的操作（/mnemon forget、mnemon_link 与记忆空间管理）保留完整 write 工具面。

后台审查可以搜索档案并调用 mnemon_document_create，不能调用 mnemon_document_manage 或 mnemon_view_action。已有档案覆盖候选时跳过；有新增知识时，新建一份独立档案并引用相关已有档案 ID。Source 的 create Action 接收 title、content，以及可选的 description、sourcePaths、sessionIds；拒绝 action、id 等额外字段。容量不足时拒绝创建，不归档已有档案。已有的用户档案和 Agent 创建档案都受此保护；显式编辑继续使用原有管理路径。

mnemon_runtime_memory 的 target=memory 写入支持可选 branches 数组（git 分支名）。带分支范围的条目只在会话 workspace 处于所列分支上时投影进每回合 Runtime 快照；无分支标签的条目始终投影。replace 时提供 branches 修改范围，传空数组清除范围，省略则保持当前范围；该参数对 target=user 会被拒绝。

#工具准入建议

• 运行时：明确偏好、稳定项目约定、环境事实和高频经验。
• 档案：具有完整结构和理由的设计、调查、流程、复盘或交接。
• 记忆空间：需要跨任务保留，或适合图关系与深召回的稳定事实、决策和洞察。
• 跳过：问题、猜测、临时进度、完成日志、原始输出、秘密和可轻易从仓库重新发现的普通事实。

mnemon_forget 是破坏性语义操作；只有用户明确要求，或内容已确认错误 / 过时时才应执行。宿主通过把该工具排除出自主 worker 的白名单来强制这一点；用户明确要求时主代理仍可调用。

#/mnemon 命令

/mnemon
/mnemon status
/mnemon recall <查询>
/mnemon related <完整记忆 ID>
/mnemon remember <内容>
/mnemon forget <精确 ID>

• 空 /mnemon 等价于 status。
• status 是确定性读取，不启动模型。
• recall、related 通过命令所在 live Agent 的限定 Source 路由直接读取，不启动 worker；remember、forget 使用该 Agent 作为写入 worker 的 parent。
• 命令 recall 最多返回 10 条。
• forget 必须接收一个不含空格的精确 ID。
• forget 仅在收到 forgotten 回执时报告删除成功；跳过、失败或未确认的结果返回错误并附 worker 摘要。

#界面注册

Mnemon 在 DSH 中展示的一切都注册到 DSH 自己的界面区域。对话内的注册都是增量的，不替换 DSH 官方渲染。

Mnemon 自己声明两个 keyed 区域，都以组件包名为键：mnemon.component.settings 渲染在该组件的页面上，mnemon.component.status 是它在状态页上的卡片。官方组件与第三方组件都通过这两个区域注册，见插件开发。

assistant-message 读取的候选可编辑，长回复会按界面上限截取；确认后会启动独立任务 Agent，写入结果以它的落定回执为准。

#工作区路由

Web 工作台请求携带 sessionId 和可选 workspaceId。Host 只接受 workspaceRegistry 已登记的 ID：

• 确定性读取与人工维护可以路由到 workspaceId 选择的查看根；
• Agent、工具、命令和生命周期仍按 sessionId 对应 Agent cwd 路由；
• status.workspaceContext 返回 selected / effective roots 与 aligned；
• 工作台发起的独立任务 Agent 使用查看工作区，不要求当前主会话与其对齐；对话工具仍使用所属会话的 cwd 和本轮 View，不借用工作台的查看范围。

Headless 等没有 Web 工作区目录的 profile 不提供任意查看目标；Agent 执行仍直接根据 session cwd 路由 workspace 范围。

#RPC 通道

RPC 是 DSH Host 与插件客户端之间的内部桥，不是稳定外部 HTTP API。页面与组件插件应使用 dsh-mnemon/client 提供的限定范围客户端，见插件开发。

回环页面直接调用这些通道，由 DSH 浏览器会话认证。远程页面经 DSH API Gateway 到达同一组处理器：通道 /api，endpoint 为 dshMnemon/read、dshMnemon/activation、dshMnemon/write、dshMnemon/pack、dshMnemon/settings、dshMnemon/view 与 dshMnemon/viewWrite。Gateway 负责 Host/Origin 校验、浏览器配对与响应封装；Mnemon 只额外施加上表中的 remoteAccess 授权，并在启动时确定。见远程管理。

#读通道

#激活通道

/dsh-mnemon-activation 的请求 schema 比写通道更窄。body endpoint 只接受 memoryBodyId、布尔值 active 和常规 session / workspace 路由字段；source-assistance 以经确认的 activation 操作接受同样两个字段，仅作用于 Memory Spaces 实例。两者只控制记忆空间是否参与 DSH 读取与路由，不接受元信息、Provider 连接、凭据、删除或持久记忆 mutation。只读模式会在 Host 边界拒绝。

#写通道

provider-services 通过读通道返回脱敏目录。设置编辑器只知道哪些凭据字段已经配置；保存新的值或显式清除字段，不回读已保存的凭据值。

writeEnabled=false 时激活通道与写通道仍保持注册，但所有 mutation 都在 Host 边界拒绝。浏览器也会根据 Host settings snapshot 在传输前禁用 mutation 控件。

#备份通道

备份包含私有记忆；调用方必须把已认证 DSH 浏览器会话视为完整 Host 权限，并单独保护导出的归档。

#设置通道

/dsh-mnemon-settings 为两个命名空间提供 get 与 mutate：mnemon 管理 Host 与存储设置，mnemon-ui 管理 turnBar 与 saveAction，保存为 conversationInteraction。mutation 携带 settings revision，防止覆盖并发编辑。插件页中的 dsh-mnemon 页面（plugins.bundle.config）在回环页面和远程页面上都通过该通道读写。回环页面还会跟随 DSH ctx.configForms 中 mnemon 条目的 revision，在其他页面或 profile 重新加载改动它时重新读取该通道。

#记忆组合通道

apply 把主策略与各组件选项保存在 mnemon-view 设置范围（保存为 memoryView）；组件开关由 DSH 插件管理器写入 profile patch。见配置参考。

#npm 导出与扩展服务

Core 发布 ctx.mnemonMemory: MnemonMemoryService，实际服务只提供 installContributions。Source/Strategy 作者通过 inject = ['mnemonMemory'] 与 installMemory 注册，不获得引擎、控制器或注册表。各包的公开子入口以其 package.json#exports 为准；Source 可提供自己的 ./contracts 和可选 ./client。

通用模型工具 mnemon_view_route、mnemon_view_action 只执行当前 View 内的 route/offer；原有具名工具保留默认工作流。浏览器管理使用 source-management-catalog、source-management-read、source-management-mutate 与可选 source-assistance，Host/Source 检查实例、确认、修订与当前权限。内部 RPC 名称不是插件 SDK，页面应使用限定实例的管理客户端。见插件开发。

#国际化范围

主要 Sidebar 工作台、插件页中的配置与对话内入口支持中文和英文，并跟随 DSH locale 实时切换。品牌名、工具名和配置键不翻译。/mnemon 命令、模型工具卡、部分 Host 错误与兼容元数据尚未完全国际化。