工作区记忆 Rogers-F/dsh-zcode-memory

DSH ZCode Memory

把 ZCode 3.16.1 源码快照中的工作区记忆迁移为 DSH 0.2.1-rc.2 插件。不是只改提示词，也不是向量检索演示：包含文件协议、冻结索引、自动提取、受限工具循环、三种 agent scope、只读管理页，以及上游默认未启用的 recall/Dream 引擎。

这是行为移植，不保证两个宿主的二进制或模型输出完全相同。 已知差异见下方。安装和升级请通过 DSH 插件页操作。Apache-2.0，独立项目，非 Z.ai/DeepSeek 官方插件。

0.1.4 设置页布局对齐 ZCode

「设置 → 工作区记忆」的视觉结构逐部位对齐 ZCode 3.16.1 的 Settings → Memory：设置卡片行（标题+描述+无文字拨动开关）、胶囊形工作区菜单（图标+下拉单选）、竖分隔线旁的「N 条记忆」计数、36px 内嵌图标搜索框、「文件」标题行+刷新图标按钮、圆角低饱和文件列表（图标方块+文件名+相对时间「刚刚/N 分钟前/今天/昨天/周X/日期」）、虚线空态与原文案。相对时间阈值与文案移植自上游 memoryUpdatedAt.ts。

保留三个有意的 DSH 差异：开关带视觉隐藏的状态文字（宿主设置可能加载中/失败/只读，绝不伪装成已关闭）；设置/目录错误就地展示并可重试；文件正文在页内只读预览卡片查看（DSH 没有可打开的外部编辑器），上游此处是「在编辑器打开」按钮组。颜色全部消费 DSH 主题令牌，随宿主明暗主题切换。本版本只改客户端，无 Host 变更，刷新页面即生效。

0.1.3 自有客户端传输修复

修复「此 DSH 传输未提供已授权的 Fetch 通道」：文件目录和正文读取现在优先使用 DSH 公开的 connection.rpc.call，不再假设桌面/隔离客户端一定暴露 Fetch。Web 与自有载体共用原来的 owner 保护路由；RPC 拒绝不会降级到 HTTP 或其他主机，路径校验和文件大小限制不变。

本版本同时更新客户端和 Host 路由，必须完整重启 DSH 让 Host 注册新的 RPC 请求处理，单独刷新页面不够。开关继续使用原生 ConfigForms，无需配置地址、Token 或 API Key。

0.1.2 原生设置页与明确开关

新增 设置 → 工作区记忆，按工作区浏览索引与事实文件；插件详情页也保留同一个界面。开关通过 DSH 原生 ConfigForms 读写同一 Host 字段，遵循只读权限、revision 和写入失败恢复，不另存浏览器状态。

真实关闭时显示蓝色「开启工作区记忆」操作；加载中显示「读取设置…」，失败时就地显示原因和「重新读取设置」，不再把未知状态伪装成「已关闭」。默认值仍为关闭，由用户明确开启以避免额外费用。

0.1.1 启用修复

修复 0.1.0 的 TypeError: Invalid effect：Cordis 插件入口不能返回普通 controller 对象，现改为无返回值，控制器通过已有 getter 获取，清理由已注册 effect 负责。全部集成测试改为直接加载插件模块，并增加默认关闭、开启、带 Connection 及卸载的真实启用回归，避免旧包装测试吞掉返回值。

本补丁不改变记忆格式、存储目录、权限或开关设置。若正在运行的 DSH 已缓存旧模块，需完全退出并重开 DSH，不只是刷新浏览器页面。

安装与启用

1. DSH 侧栏「插件」→「添加插件」→ 选择本插件交付的 .tgz 本地绝对路径。
2. 安装后启用组合包，打开 设置 → 工作区记忆（插件详情页也可进入）。
3. 点击 开启工作区记忆，然后新建会话，或完全退出 DSH 后冷恢复会话；已有会话保持创建时的开关和索引。
4. 在新会话让 Agent 实际保存一条长期偏好，再到该设置页点击刷新，选择工作区和文件查看。尚未生成记忆文件时列表为空，不代表插件失效。
5. 如新插件配置页未出现，刷新当前 GUI；必要时完全退出并重开 DSH。不要另外启动一个 Web 服务来替代现有 GUI。

包安装只需要普通 JS 依赖，无原生模型、Embedding 下载、额外 API key 或依赖构建脚本。若使用原始源码目录安装，先完成 build；交付 .tgz 已带客户端 bundle。

使用

在对话中说「记住：本项目发布时必须先走 staging」或「忘掉刚才的发布约定」。主 agent 使用原有 read/write/edit 工具管理记忆；不是另加一套要求用户记忆的命令。

成功回合结束后，后台提取会检查最近增量内容，必要时调用同一回合的模型和受限工具写入文件。无值得保存的信息则无操作。记忆不是聊天记录全集，只有四类稳定信息：

| 类型 | 内容 |
| user | 用户角色、知识背景和稳定偏好 |
| feedback | 工作方式的纠正或确认，含 Why / How to apply |
| project | 无法从当前代码/git 推导的目标、原因或约束 |
| reference | 外部资料和查找入口 |

已有代码、Git 历史、指令文件和临时任务进度不重复存储。上下文压缩不等于长期记忆；记忆内容也不能覆盖更高优先级指令。

保留的上游细节

- 后台提取以空白切分至少 3 词判定用户 prose；纯中文无空格短句可能不触发自动提取。这是源行为，不是中文分词器。显式「记住」仍可由前台写入。
- 窗口中出现过直接 Write/Edit 到记忆目录的尝试就跳过后台提取，即使那次工具失败；这是源行为。
- 每会话最多一个 running 和一个 latest pending，不堆积 FIFO；成功/no-op/skip 推进游标，失败和取消不推进。
- 默认提取最多 5 次模型请求，末次返回的工具仍执行；辅助请求最多 5000 输出 token，并选择提供方支持的最低 reasoning 档位。
- 主对话不会等待提取。会话关闭/插件卸载取消背景工作；迟到结果不能继续写入。常规关闭等待上限 60 秒。
- 设置关闭只影响新建/冷恢复实例，不热改正在运行的会话。关闭组合包或销毁会话才取消当前实例。

存储与查看

默认路径（从 DSH 自己的 home 解析，不读取 ZCode 用户数据）：

$DSH_HOME/zcode-memory/memories/projects/<slug>-<sha256前16位>/memory/ MEMORY.md release-branch-policy.md user-preference.md

一个事实一个 Markdown 文件，索引一行一个链接。四类元数据、originSessionId 补齐、去重/遗忘规则、完整源 prompt 均已迁移。索引会话初始化只读取一次，限制 200 行或 25000 个 JS 字符，超限有明确 warning。Windows 路径大小写和短路径别名经过规范化处理。
插件页提供工作区列表、文件名搜索、只读 Markdown 预览和显式刷新；只列记忆目录顶层文件。单文件预览最多 5MiB。远端查看被拒绝；网页预览不执行 HTML，也不自动请求图片和链接。

默认项目记忆写入应用私有目录，不改变工作区项目文件。配置下面的 custom project/local scope 时，会在工作区的隐藏目录创建对应记忆，这是显式配置的例外。

自定义 agent 记忆

使用 profile 补丁为 DSH agent preset 名称指定 scope；也支持确切 agent id。普通子代理不会自动获得主 agent 的项目记忆。fork 继承活父实例冻结的开关；真正冷恢复读取新设置。

- id: zcode-memory
config:
enabled: true
use: true
extractionEnabled: true
customAgents:
reviewer: project
architect: user
private-helper: local

| scope | 路径 |
| user | $DSH_HOME/zcode-memory/agent-memory/<agent-key>/ |
| project | <workspace>/.dsh/agent-memory/<agent-key>/ |
| local | <workspace>/.dsh/agent-memory-local/<agent-key>/ |

自定义 agent 获得完整 Persistent Agent Memory 提示词和自己的索引；不与主项目库混用。DSH 的显式工具禁用/权限守卫仍优先，不为了记忆偷偷恢复被禁用的工具。headless 任务若只想读既有记忆而不自动提取，可将 extractionEnabled 设为 false；本插件没有仿造 ZCode CLI 的 --memory-bench 开关。

默认关闭的能力不是遗失功能

- Semantic Recall：完整 manifest/selector/异步 prefetch/consume/预算/失效逻辑保留，生产常量仍关闭（与源当前默认分支一致）。DSH 0.2.1 的公开 LLM 接口没有已验证的原生 structured-output 合同，所以 DSH Adapter 明确报告不支持，不能把独立引擎测试误称为 DSH 语义召回端到端通过。
- Dream：完整 24h/10min/5 其他 session gate、PID 锁、50 轮工具循环、合并整理 prompt 和一次性 memory_update 保留并测试；没有新增自动触发。源本身也未接产品触发点。DSH transcript 归属/mtime Adapter 未作为产品入口接线，未宣称它能从当前 DSH 历史自动整理。

安全、费用与有意差异

1. 本地保存不等于本地推理。 记忆与提取所需上下文会发给该回合所选模型服务商；消耗 token，依赖对应账户额度。未启用额外第三方记忆云服务。
2. 开启记忆授权插件在明确的私有存储目录维护 Markdown。前台/后台都走 DSH 的 tool policy 与 monotonic guards；read-only 模式拒绝写入。workspace-write 只为这个狭窄应用存储增加例外，不改变普通 workspace 路径策略。
3. 后台 Windows 命令使用有限的虚拟只读/窄删除解释器，不启动任意 PowerShell。只接受单条 literal-path Get-Content/Get-ChildItem/Get-Item/Test-Path 和 root 内 Remove-Item；拒绝管道、脚本、重定向、工作目录重定向和后台脱离任务。POSIX Bash 保留移植的上游只读分类器；批准的只读 Bash 可由 DSH 原工具执行，未做 macOS/Linux 实机验收。
4. 所有记忆 IO 额外应用 5MiB 限制、符号链接/路径别名校验、稳定句柄与原子提交。这比源部分读取路径更严格。
5. 截断的 semantic recall 被标记 partial，不能凭不完整内容覆盖整个文件；源代码存在较宽松行为，本插件没有复制这个数据丢失风险。
6. 源中将索引包装成可覆盖默认行为的文案未照搬，索引按 DSH 背景上下文接入；完整上游文本仍保存在来源素材中供对照。
7. 工具名称按 DSH 的 read/write/edit/pwsh 适配；模型请求协议、custom scope 的 .dsh 目录与原宿主不同。0.1.4 起设置页布局与 ZCode 对齐，仅保留开关状态文字、就地错误重试、页内只读预览三处宿主差异（见上）。没有承诺模型每次作出同一记忆判断。
8. 后台请求、usage、工具调用与结果作为可忽略 plugin 审计事件写入原 DSH 会话日志，避免不可重建的隐藏模型输入；这会增加本地会话日志体积。

开发和验收

pnpm install --ignore-scripts
pnpm build
pnpm check
pnpm test
pnpm test:integration

默认测试入口会递归包含 storage/prompts 子目录，不只运行顶层文件。integration 使用已安装 Electron 的 Node 模式加载真实 DSH 包，临时 HOME/DSH_HOME 与本地 scripted provider 隔离，不读真实凭据、不请求真实模型、不打开替代 GUI 服务器。非默认安装位置可设置 DSH_INTEGRATION_ELECTRON 和 DSH_INTEGRATION_ROOT。

覆盖范围包括原 prompt golden、文件 hash、字节/行截断、真实存储读写、取消与迟到结果、游标/合并、recall/Dream 独立引擎、React 实际交互、真实 DSH Context+agent-loop+fs/tools、跨会话召回、cold resume、权限拒绝、cwd 冻结和鉴权路由。具体最终计数以交付验收记录为准。

卸载

在 DSH 插件页关闭/卸载本组合包；不会自动删除记忆数据。确认不再需要后，用户可自行备份并清理上述独立目录。没有迁移、删除或覆写 ZCode 已有记忆。

来源与许可：NOTICE、Apache-2.0、上游NOTICE、逐文件来源hash、Engine来源hash。