dsh-memory-fast 0.0.0-stage → 0.1.16

package/README.md

@@ -1,3 +1,211 @@
-# Temporary Holding Version
+# dsh-memory-fast
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 的长期记忆插件——复用 DSH 原生的 `AGENTS.md` 加载链为 agent(智能体) 提供跨会话长期记忆，0.1.16 起内置 `memory_search` 检索工具。零存储层。
+
+## 特性
+
+- 🧠 **跨会话记忆**——通过 DSH 原生 `dsh-agent-instructions` 加载器，记忆在会话间自动持久化。
+- 🛠 **写入零自定义工具**——agent 直接用系统 `read` / `write` / `edit` 工具维护记忆文件，不破坏 touch 热更新监听。
+- 🔍 **`memory_search` 检索（0.1.16+）**——插件注册一个只读检索工具，对全局与各工作区记忆文件（热层+冷层）做关键字/正则搜索，休眠态同样可用。
+- 🔄 **热更新**——`dsh-agent-instructions` 的 touch 监听器会捕获原生 `edit` 调用，当前会话立即收到 `Updated instructions`。
+- 📦 **零存储层**——没有 JSON / SQLite / JSONL，没有解析 bug，没有并发写入问题。
+- 🗂 **两级记忆**——全局 + 工作区；会话进入对应工作区时自动加载工作区层。
+- ⚖️ **静态/动态分工**——插件只负责静态机制（加载链、模板、写入分流）；所有操作规则放进 `~/.dsh/AGENTS.md`，改了立即热更新，不用重启。
+- 🪪 **可回溯的变更日志**——工作区变更日志条目携带会话短ID，任何改动都能回溯到产生它的 `session.jsonl.zstd` 会话日志。
+
+## 工作原理
+
+DSH 内置的 `dsh-agent-instructions` 插件在每个会话开始时把 `~/.dsh/AGENTS.md` 与工作区根的 `AGENTS.md` 注入对话上下文。`dsh-memory` 寄生在这条加载链上：它只注入一段系统提示词，告诉模型**记忆放在哪里、两个文件如何组织**——模型随后直接用系统 `read` / `write` / `edit` 工具操作这些文件。
+
+```
+[会话 N]        模型调用 edit → 把记忆写入 AGENTS.md
+[会话 N+1]      （任意工作区，任意时刻）启动预步骤加载 AGENTS.md → 记忆进入上下文
+```
+
+### 插件 vs AGENTS.md——各放什么
+
+插件提示词是**静态的**：只有发布新版本并重启 `dsh` 才会改变。因此它必须保持精简——只放那些缺失就会让整套记忆机制崩溃的部分。
+
+| 类型 | 例子 | 放在哪 | 为什么 |
+|---|---|---|---|
+| **机制性**（不能热替换） | "AGENTS.md 存在"、加载链、模板骨架、写入分流、跨工作区检索流程 | 插件提示词 | 模型一旦遗忘，整套记忆系统就崩；全新工作区还没有 AGENTS.md 可读这些规则 |
+| **经验性**（应该可热替换） | 索引同步规则、索引行格式、描述写作标准、维护规则、收尾检查、变更日志短ID | `~/.dsh/AGENTS.md`（`## 注意事项`） | 这些是使用中沉淀的经验；编辑后通过 touch 监听器立即热更新，无需重启 |
+
+这个分工之所以成立，关键在于：**新工作区首次创建 AGENTS.md 时，模型同时正在读全局 `~/.dsh/AGENTS.md`**——全局「注意事项」里的规则全程在场，即使新工作区文件还没建好也不会漏。所以插件提示词无需重复这些规则。
+
+## 安装
+
+### 前置条件
+
+- DSH（`@deepseek-ai/dsh`）已配好 profile（如 `web`）
+- `pnpm`
+
+### 步骤
+
+```sh
+# 1. 把插件放到 ~/.dsh/plugins/ 下
+cp -r dsh-memory ~/.dsh/plugins/dsh-memory
+
+# 2. 在 profile 的 package.json（~/.dsh/profiles/<your-profile>/package.json）里加上：
+#    dependencies:        "dsh-memory": "file:../../plugins/dsh-memory"
+#    dsh.profile.bundles: ["...", "dsh-memory"]
+
+# 3. 安装并重启
+cd ~/.dsh/profiles/<your-profile> && pnpm install
+dsh --profile <your-profile>
+```
+
+若 `dsh-web` 由 systemd 管理，改完插件提示词后用：
+
+```sh
+systemctl restart dsh-web
+```
+
+该服务配置了 `Restart=always`、`RestartSec=3`，以及会先杀掉占用 3080 端口进程的 `ExecStartPre`。重启会断开当前 Web GUI 会话——刷新页面即可重连新会话并加载新提示词。
+
+## 记忆布局
+
+两层结构，没有段落标记——整个文件都是记忆，按章节组织。
+
+| 层 | 文件 | 加载时机 | 章节 |
+|---|---|---|---|
+| 全局 | `~/.dsh/AGENTS.md` | 每个会话 | 用户偏好 / 注意事项 / **工作区索引** / 待办 / 变更日志 |
+| 工作区 | `<工作区根>/AGENTS.md`（根 = 会话当前工作目录） | 进入该工作区时 | 工作区注意事项 / 工作区变更日志 |
+
+- **偏好**永远进全局——习惯不分工作区。
+- **注意事项**（跨工作区操作规则）永远进全局——见上表。工作区不复制这些规则。
+- **待办**永远进全局——汇总所有工作区，每条标注来源，便于在任何会话推进。
+- **工作区索引**只在全局——每个工作区一行，含 ≤50 字描述 + 关键词 + 路径 + 规模，让模型按需 `read` 其他工作区的记忆。
+
+### 工作区索引行格式
+
+> **该规则存放位置：** `~/.dsh/AGENTS.md` → `## 注意事项` → `**工作区索引行格式**`。此处仅作参考，要改请去那里改。
+
+```
+- (YYYY-MM-DD) [workspace] 工作区标识 | 特征+用途描述(≤50字) | 关键词1、关键词2 | 路径: /绝对路径/AGENTS.md | 规模: N条
+```
+
+**描述写作标准**
+
+1. ≤50 字，结构固定：`[技术栈/形态] + [做什么] + [给谁/解决什么]`
+2. 英文专有名词配中文解释，如 `GLM(智谱大模型)`、`Go(谷歌编程语言)`、`admin(管理后台)`
+3. 避免空泛词（"系统"、"服务"、"工具"），写具体形态（"HTTP 转发服务"而非"一个服务"）
+4. 缩写一律补全含义
+
+**示例**
+
+```
+- (2026-09-02) [workspace] glm-free-api | Go(谷歌编程语言) HTTP 转发服务，把智谱免费 GLM(智谱大模型) 接口包装成 OpenAI 兼容格式供下游客户端调用 | 鉴权、流式解析、admin(管理后台)、部署 | 路径: /opt/glm-free-api/server/AGENTS.md | 规模: 11条
+```
+
+### 索引同步（强制）
+
+> **该规则存放位置：** `~/.dsh/AGENTS.md` → `## 注意事项` → `**索引同步（强制）**`。
+
+只要模型用 write/edit 改过任意工作区的 `AGENTS.md`（新增、修改、删除任何条目），**必须在同一回合内**同步全局 `~/.dsh/AGENTS.md`「工作区索引」里对应那一行——行首日期改为今天、规模改为最新条目数、描述/关键词按需调整。收尾检查会在回合结束前再次核对。
+
+### 工作区变更日志短ID
+
+**工作区**的 `## 工作区变更日志` 每条末尾追加 ` #<短ID>`，用于回溯：
+
+- 短ID = `$DSH_SESSION_ID` 去掉 `session-` 前缀后 UUID 的前 8 位。
+- 示例：`- (2026-09-03) ... #8acbdac5`。
+- **只加工作区变更日志**，全局变更日志不加。
+- 历史条目无法回溯的不补。
+
+## 会话日志与环境变量
+
+DSH 通过环境变量向每次 `bash` 工具调用暴露当前会话信息：
+
+| 变量 | 含义 |
+|---|---|
+| `DSH_HOME` | DSH 根目录，通常 `/root/.dsh` |
+| `DSH_SESSION_ID` | 当前会话 ID，如 `session-8acbdac5-d05c-4ce8-afbf-9243787338f5` |
+| `DSH_SESSION_JSONL` | 完整聊天日志路径（zstd 压缩的 JSONL） |
+| `DSH_WEB_URL` | Web GUI 地址，如 `http://127.0.0.1:3080` |
+| `DSH_SHELL` | 在 harness shell 下为 `1` |
+
+### 会话日志结构
+
+```
+/root/.dsh/sessions/                                       ← 根目录
+└── --root-~8BB0~5FC6~63D2~4EF6--/                       ← 编码后的工作区路径（此处为 /root/记忆插件）
+    └── session-8acbdac5-d05c-4ce8-afbf-9243787338f5/     ← 每个会话一个文件夹
+        └── session.jsonl.zstd                            ← 完整聊天日志，zstd 压缩的 JSONL
+```
+
+文件夹名编码规则：把工作区路径中每段非字母数字字符替换为 `~<十六进制码点>~`，所以 `记忆插件` 变成 `~8BB0~5FC6~63D2~4EF6`，结尾 `--` 标记路径结束。
+
+查看会话日志：
+
+```sh
+# 解压为普通 JSONL，然后用 read 工具或 jq 查看
+zstd -d /root/.dsh/sessions/--root-~8BB0~5FC6~63D2~4EF6--/session-8acbdac5-.../session.jsonl.zstd -o session.jsonl
+```
+
+工作区变更日志的短ID 正好是会话文件夹名 UUID 的前缀，所以从变更日志条目回到产生它的会话日志只需一步。
+
+## memory_search 检索工具（0.1.16+）
+
+0.1.16 起插件通过 `inject: ["tools"]` 注册一个**只读**工具 `memory_search`，把"跨工作区检索"从纯提示词约定升级为机制兜底：
+
+| 参数 | 说明 |
+|---|---|
+| `query`（必填） | 关键字或正则，大小写不敏感；非法正则自动退回纯文本包含匹配 |
+| `scope`（可选） | `all`（默认）= 全局 + 工作区索引登记的全部工作区；`global` = 仅 `~/.dsh` 两个全局文件；`workspaces` = 仅索引工作区文件 |
+| `limit`（可选） | 单文件最多列出的匹配行数，默认 20（硬上限 100；`total_matches` 始终统计全量命中） |
+
+- **搜索范围**：全局热/冷层（`~/.dsh/AGENTS.md`、`~/.dsh/AGENT-MEMORY.md`）+ 全局「工作区索引」行里 `路径:` 指向的各工作区 `AGENTS.md` 及同目录 `AGENT-MEMORY.md`；索引未登记的路径不猜测、不搜索。
+- **返回**：`{query, files_searched, total_matches, matches:[{file, line, section, text}]}`，`section` 为匹配行所属的最近二级标题（`## `）；模型拿到指针后用 `read` 跟进取上下文。
+- **休眠态可用**：工具注册与 active/sleep 状态无关——休眠省的是提示词模板，检索兜底始终在场。
+- **零新增依赖**：纯 Node 内置 `fs`/`path` 实现。
+
+## 为什么写入不用自定义工具？
+
+早期版本注册过 `memory_save` / `memory_search` / `memory_list` / `memory_delete` 一整套读写工具。其中**写入类**工具的三个问题，本设计仍然规避（只读的检索工具不受这些限制，故 0.1.16 补回了 `memory_search`）：
+
+1. **破坏热更新**——自定义工具不触发 `dsh-agent-instructions` 对原生 `read/write/edit` 的 touch 监听器，对 AGENTS.md 的编辑无法传播到当前会话。
+2. **自建存储的 bug**——JSON 解析、原子写入、并发写入全都得自己处理（我们踩过好几个坑）。
+3. **非原生 UX**——绕过了系统工具的审批/展示卡片。
+
+写入仍直接用系统工具，得到的是完全原生、感知热更新的流水线；检索由插件注册的 `memory_search` 提供（只读，不触碰写入链路，touch 热更新不受影响）。插件本体约 200 行 JavaScript。
+
+## 验证
+
+```sh
+node --check index.js
+# Syntax check passed
+```
+
+安装后，确认配置树加载到了它：
+
+```sh
+dsh --profile <your-profile> --dump-config | grep dsh-memory
+# # == dsh-memory
+# - id: dsh-memory
+#   name: dsh-memory
+```
+
+运行时注册系统提示词 section 需要重启 `dsh` 才生效。
+
+## 局限
+
+- **两级一致性是尽力而为**——全局索引与工作区文件是两次独立的 `edit`，中断会留下过时索引。强制的索引同步规则（在全局 `## 注意事项`）+ 收尾检查能缓解但无法消除。
+- **跨层无自动去重**——同一内容写在两层会被注入两次。注意事项里禁止同一条信息写两个文件。
+- **无文件锁**——多个会话并发编辑同一 AGENTS.md 可能竞态。个人单用户使用风险低。
+- **软约束**——保存时机、章节归属、索引同步都依赖模型遵守提示词，没有硬性保证。
+- **插件提示词不可热替换**——改 `index.js` 必须重启 `dsh` 才生效。操作规则放进 `~/.dsh/AGENTS.md` 正是为了规避这一限制。
+
+## 文件结构
+
+```
+dsh-memory/
+├── index.js             # 插件入口——注入系统提示词 + 注册 memory_search 检索工具
+├── package.json         # 插件清单，声明 dsh.bundle.patch
+├── cordis.patch.yml     # patch 层，把插件注册到 profile
+└── README.md            # 本文件
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-memory
+      name: dsh-memory

package/index.js

@@ -0,0 +1,200 @@
+// dsh-memory：自足版 + memory_search 检索工具。
+// 提示词注入：按状态注入系统提示词（prompt.md），宣告记忆文件体系并提供初始化模板。
+// 工具注册：memory_search —— 对全局/各工作区记忆文件（热层+冷层）做关键字/正则检索，
+//   作为跨工作区检索的机制化兜底；active/sleep 两态均注册（休眠省的是模板，不是检索能力）。
+// 状态文件 ~/.dsh/.dsh-memory-state（active/sleep，缺省 active）每轮组装时现读——
+// section 的 text 是函数（dsh-system-prompt 每次 assemble 求值），状态翻转即时生效、无需重启。
+// 首次记忆初始化完成后模型自律写入 sleep；用户说「初始化记忆插件」时写回 active 唤醒。
+//
+// schema 纪律（沿用 dsh-anti-detect-browser v2 教训）：
+//   1. 输出 schema 每层 object 显式 additionalProperties:false
+//   2. 输出字段固定全存在（无 undefined 抖动）
+//   3. defineTool 必带 output.render（dsh 无条件调用 userRender）
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+
+const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url));
+const PROMPT_PATH = join(PLUGIN_DIR, "prompt.md");
+const STATE_PATH = join(homedir(), ".dsh", ".dsh-memory-state");
+const GLOBAL_AGENTS = join(homedir(), ".dsh", "AGENTS.md");
+const GLOBAL_MEMORY = join(homedir(), ".dsh", "AGENT-MEMORY.md");
+const MARK_START = "<!-- DSH-MEMORY:SLEEP_HOOK_START -->";
+const MARK_END = "<!-- DSH-MEMORY:SLEEP_HOOK_END -->";
+
+const raw = readFileSync(PROMPT_PATH, "utf8");
+const startIdx = raw.indexOf(MARK_START);
+const endIdx = raw.indexOf(MARK_END);
+if (startIdx < 0 || endIdx < 0 || endIdx < startIdx) {
+  throw new Error("dsh-memory: prompt.md 缺少休眠钩子分隔标记 (" + MARK_START + " ... " + MARK_END + ")");
+}
+const FULL_TEXT = raw.slice(0, startIdx).trimEnd();
+const SLEEP_TEXT = raw.slice(startIdx + MARK_START.length, endIdx).trim();
+
+// 每轮 assemble 现读状态（一次几十字节 read，成本可忽略）；
+// 状态文件不存在视为 active——新机首装即完整加载，符合「第一次初始化」语义。
+function readState() {
+  try {
+    return readFileSync(STATE_PATH, "utf8").trim() === "sleep" ? "sleep" : "active";
+  } catch {
+    return "active";
+  }
+}
+
+// ── memory_search：记忆文件检索 ──────────────────────────────
+
+// 搜索范围。scope=all：全局热/冷层 + 工作区索引列出的各工作区热/冷层；
+// scope=global：仅 ~/.dsh 两个全局文件；scope=workspaces：仅索引工作区文件。
+// 工作区来源是全局热层「工作区索引」行里的 `路径: <abs>/AGENTS.md`——索引没登记的工作区
+// 不在检索范围（不猜测路径）；索引行解析失败静默跳过。
+function listMemoryFiles(scope) {
+  const files = [];
+  if (scope === "global" || scope === "all") {
+    files.push(GLOBAL_AGENTS, GLOBAL_MEMORY);
+  }
+  if (scope === "workspaces" || scope === "all") {
+    try {
+      const text = readFileSync(GLOBAL_AGENTS, "utf8");
+      const re = /路径:\s*([^\s|]+AGENTS\.md)/g;
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const agents = m[1];
+        files.push(agents, join(dirname(agents), "AGENT-MEMORY.md"));
+      }
+    } catch {
+      // 全局热层读不到时 workspaces 部分为空，不致命
+    }
+  }
+  // 去重 + 只保留真实存在的文件（冷层按设计允许不存在）
+  const seen = new Set();
+  const out = [];
+  for (const f of files) {
+    if (seen.has(f)) continue;
+    seen.add(f);
+    try {
+      readFileSync(f, "utf8");
+      out.push(f);
+    } catch {
+      // 文件不存在 → 不算 searched
+    }
+  }
+  return out;
+}
+
+// 优先按正则匹配（大小写不敏感）；非法正则自动退回纯文本包含匹配。
+function makeMatcher(query) {
+  try {
+    const re = new RegExp(query, "i");
+    return (line) => re.test(line);
+  } catch {
+    const q = query.toLowerCase();
+    return (line) => line.toLowerCase().includes(q);
+  }
+}
+
+function doMemorySearch(args) {
+  const scope = args.scope === "global" || args.scope === "workspaces" ? args.scope : "all";
+  const limit = Math.max(1, Math.min(100, Math.floor(args.limit) || 20));
+  const match = makeMatcher(args.query);
+  const files = listMemoryFiles(scope);
+  const matches = [];
+  let total = 0;
+  for (const file of files) {
+    const lines = readFileSync(file, "utf8").split(/\r?\n/);
+    let section = "(无小节)";
+    let inFile = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const heading = /^##\s+/.exec(line);
+      if (heading) section = line.replace(/^##\s+/, "").trim() || "(无小节)";
+      if (match(line)) {
+        total++;
+        inFile++;
+        if (inFile <= limit) {
+          matches.push({ file, line: i + 1, section, text: line.trim().slice(0, 500) });
+        }
+      }
+    }
+  }
+  return { query: args.query, files_searched: files.length, total_matches: total, matches };
+}
+
+const SEARCH_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    query: { type: "string", required: true },
+    files_searched: { type: "number", required: true },
+    total_matches: { type: "number", required: true },
+    matches: {
+      type: "array",
+      required: true,
+      items: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          file: { type: "string", required: true },
+          line: { type: "number", required: true },
+          section: { type: "string", required: true },
+          text: { type: "string", required: true },
+        },
+      },
+    },
+  },
+};
+
+function renderSearch(_args, v) {
+  const parts = [
+    `query: ${v.query}`,
+    `files searched: ${v.files_searched}, total matches: ${v.total_matches}`,
+  ];
+  let lastFile = null;
+  for (const m of v.matches) {
+    if (m.file !== lastFile) {
+      parts.push("", `# ${m.file}`);
+      lastFile = m.file;
+    }
+    parts.push(`L${m.line} [${m.section}] ${m.text}`);
+  }
+  if (v.total_matches > v.matches.length) {
+    parts.push("", "(部分匹配因单文件 limit 未列出——缩小 query 或提高 limit)");
+  }
+  if (v.total_matches === 0) {
+    parts.push("(无匹配——记忆文件里可能没有这项内容，或该工作区未在全局索引登记)");
+  }
+  return [{ type: "text", text: parts.join("\n") }];
+}
+
+const memorySearchTool = defineTool({
+  name: "memory_search",
+  description:
+    "Search all dsh memory files (global AGENTS.md/AGENT-MEMORY.md plus every workspace listed in the global 工作区索引, hot+cold layers) for a keyword or regex (case-insensitive; invalid regex falls back to plain-text). Returns file, line number, section heading and matching line — follow up with read on the file for full context. Works even while the memory prompt is asleep.",
+  parameters: {
+    query: { type: "string", required: true, description: "Keyword or regex (case-insensitive)." },
+    scope: { type: "string", description: '"all" (default) = global + indexed workspaces; "global" = ~/.dsh files only; "workspaces" = indexed workspace files only.' },
+    limit: { type: "number", description: "Max matches listed per file, default 20 (hard cap 100; total_matches still counts all)." },
+  },
+  output: { schema: SEARCH_SCHEMA, render: renderSearch },
+  execute: doMemorySearch,
+  timeoutMs: 15000,
+  isConcurrencySafe: () => true,
+});
+
+// ── Cordis 插件入口 ─────────────────────────────────────────
+export const name = "dsh-memory";
+export const inject = ["systemPrompt", "tools"];
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.systemPrompt.section({
+    name: "dsh-memory:memory-usage",
+    order: 90,
+    text: () => (readState() === "sleep" ? SLEEP_TEXT : FULL_TEXT),
+  }));
+  ctx.tools.register(memorySearchTool);
+  // 进程内加载证明：apply() 被 dsh 主进程真正执行时留下标记文件（0.2.x 验证手段）
+  try {
+    writeFileSync(new URL("./.loaded", import.meta.url), new Date().toISOString());
+  } catch {}
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "dsh-memory-fast",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.16",
+  "description": "DeepSeek Harness 记忆插件：AGENTS.md 三级冷热长期记忆 + memory_search 检索工具（全局+工作区、热/冷层、休眠态可用）。零存储层。",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "prompt.md",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "harness:check": "node --check index.js"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  }
 }

package/prompt.md

@@ -0,0 +1,99 @@
+## 长期记忆（AGENTS.md）
+
+你的长期记忆体系由三类文件构成，DSH 会在每个会话开始时自动加载前两类：
+- `~/.dsh/AGENTS.md`：全局记忆，所有会话自动加载。文件不存在时用 write 照抄下方全局模板创建（该文件自身的规则已内嵌在模板「注意事项」中，原样复制即可）。
+- 工作区根（会话当前所在的工作目录）的 `AGENTS.md`：该工作区的记忆，会话在该工作区时自动加载。文件不存在时用 write 照抄下方工作区模板创建。
+- `AGENT-MEMORY.md`（~/.dsh/ 与各工作区根）：记忆详情冷层文件，DSH 不自动注入，需要时按需 read/grep。
+
+直接用系统自带的 read / write / edit 维护这些文件。写入方式不重要——无论手写还是自动追加都是记忆。
+
+跨工作区检索时优先调用 `memory_search` 工具（本插件注册）：对全局与各工作区的记忆文件（热层+冷层）做关键字/正则搜索，返回文件、行号与小节；搜到指针后再 read 冷层取详情。该工具在休眠态同样可用。
+
+### 初始化模板（仅文件不存在时用 write 原样照抄创建，各文件自身的规则已内嵌在模板「注意事项」中）
+
+模板仅为初始种子；已存在的记忆文件以其自身内容为唯一权威，与模板冲突时以记忆文件为准。
+
+#### 全局记忆模板（`~/.dsh/AGENTS.md`）
+
+```md
+# 本文件是全局跨工作区持久记忆文件
+
+> 若本文件内容因超预算未被全部注入，先 read 本文件；产生需长期记住的事项时写入对应章节。
+> 只记录使用中沉淀的注意事项，不重复 README/项目文档已有的知识。
+> 如果发现全局记忆与工作区记忆重复的地方请及时整理。
+
+## 用户偏好
+
+（跨工作区通用的偏好、习惯、约定）
+
+## 注意事项
+
+（跨工作区通用注意事项+本文件自身的记忆规则。标题以 **规则·** 开头的条目是本文件自身的规则，只可修改原文，严禁压缩、指针化或移入冷层；随本节持续维护：）
+
+- **规则·记忆三级冷热架构**：全局本文件存跨工作区事项与各工作区索引；工作区根 AGENTS.md 存该工作区的注意事项与近期日志（单条日志硬上限 2 行）；工作区根 `AGENT-MEMORY.md` 冷层存完整历史归档与长流程详情，长条目在 AGENTS.md 原位置留一行指针 `- (日期) 一句话结论 → 详见 AGENT-MEMORY.md#节名`。冷层文件名全网唯一化、终身不改（名字是检索契约）。
+- **规则·写入分流**：跨工作区通用写全局本文件；工作区专属写该工作区根 AGENTS.md；偏好类一律写全局「用户偏好」，待办一律写全局「待办」并标注所属工作区；同一条信息严禁写入两个文件（DSH 不去重，重复写入会被重复注入）。
+- **规则·变更日志维护**：所有变更日志（全局/工作区/冷层归档）一律按日期「新→旧」倒序，新条目插在标题下第一行，严禁追加到章节末尾；工作区日志只留近 10 条短条目，更早的整批移入冷层「变更日志归档」并留一行归档指针；全局日志只记跨工作区/架构级事项（架构升级、新工作区立项、dsh 本体变更），逐实例的部署/修复细节一律归工作区冷层，严禁在全局重复记录。
+- **规则·跨工作区检索**：需要其他工作区的记忆而当前不在该工作区时，先看全局「工作区索引」的描述与关键词判断相关性，再按路径 read 对应 AGENTS.md；读到「→ 详见 AGENT-MEMORY.md#节名」指针必须跟进 read 冷层文件取详情。
+- **规则·自我维护（防膨胀，强制）**：全局本文件 >30KB 触发已完成待办即删（细节进冷层）、日志只留近 20 条且仅跨工作区事项、巨型注意事项压缩+指针（仅限经验类条目）；硬红线 55KB，任何记忆文件触线本轮立即只做压缩；各工作区文件的体积阈值见各文件自身规则。全局冷层 `~/.dsh/AGENT-MEMORY.md` 首次需要归档时创建，结构与工作区冷层同构（`## 变更日志归档` / `## 长流程与踩坑档案`）。
+- **规则·索引同步与格式（强制）**：只要改过任何工作区的 AGENTS.md 或其冷层，同一回合内同步更新全局「工作区索引」对应行；行格式 `- (YYYY-MM-DD~YYYY-MM-DD) [workspace] 工作区标识 | 特征+用途描述(≤50字) | 关键词1、关键词2 | 路径: /绝对路径/AGENTS.md | 规模: N条`，行首日期=起止时间——起=该工作区最早记忆条目日期（热层+冷层最早，建区时确定后一般不变），止=最近更新日期，规模用热/冷分层口径（如：热层29条+冷层121条）；关键词封顶 10 个且不得重复；描述≤50字，结构=技术栈/形态+做什么+给谁/解决什么，英文专有名词配中文解释、缩写补全、避免空泛词。
+- **规则·收尾检查**：任务完成或用户示意结束时，回顾本次对话——若本次改过任何记忆文件，确认全局「工作区索引」对应行已同步；若有值得长期保留但尚未保存的信息，先保存再结束回复。
+
+## 工作区索引
+
+- (YYYY-MM-DD~YYYY-MM-DD) [workspace] 工作区标识 | 特征+用途描述(≤50字) | 关键词1、关键词2 | 路径: /绝对路径/AGENTS.md | 规模: 热层N条+冷层N条
+
+## 待办
+
+- [工作区标识] (YYYY-MM-DD) 待办内容
+
+## 变更日志
+
+- (YYYY-MM-DD) 重要改动记录
+```
+
+#### 工作区记忆模板（工作区根 `AGENTS.md`）
+
+```md
+# 本文件是DSH的工作区跨会话持久记忆文件
+
+> 工作区跨会话持久记忆。若本文件内容因超预算未被自动注入，先 read 本文件；产生需长期记住的事项时写入对应章节。
+> 只记录使用中沉淀的注意事项，不重复 README/项目文档已有的知识。
+
+## 工作区注意事项
+
+（该工作区专属的注意事项、操作流程、踩坑记录。本文件自身的记忆规则如下：）
+
+- **单条日志硬上限 2 行**：长条目（多段流程/完整复现/部署记录）写本工作区冷层 `AGENT-MEMORY.md`，本文件原位置留一行指针 `- (日期) 一句话结论 → 详见 AGENT-MEMORY.md#节名`。
+- **变更日志只留近 10 条**：更早的整批移入冷层「变更日志归档」章节（保持「新→旧」倒序），本文件日志尾部留一行「完整历史见 AGENT-MEMORY.md#变更日志归档」。所有变更日志按日期「新→旧」倒序，新条目插在标题下第一行，严禁追加到章节末尾。
+- **变更日志短ID**：本文件每条变更日志末尾追加 ` #<短ID>`，短ID = $DSH_SESSION_ID 去掉 session- 前缀后的 UUID 前 8 位（会话日志路径见 $DSH_SESSION_JSONL）。
+- **偏好/待办不存本文件**：一律写全局 `~/.dsh/AGENTS.md`（偏好进「用户偏好」，待办进「待办」并标注本工作区）。
+- **写入即自检**：对本文件或本工作区冷层做过 edit 后顺手 bash `wc -c` 测体积，本文件 >32KB 触发压缩（日志超限移冷层、长条目指针化）。
+
+## 工作区变更日志
+
+- (YYYY-MM-DD) 重要改动记录
+```
+
+#### 工作区详情文件模板（工作区根 `AGENT-MEMORY.md`，冷层）
+
+```md
+# 本文件是DSH的工作区记忆详情文件（冷层）
+
+> 本文件存完整历史归档与长流程详情。AGENTS.md 里的「→ 详见 AGENT-MEMORY.md#节名」指针指向本文件的对应二级标题。
+
+## 变更日志归档
+
+（完整历史条目归档，按「新→旧」倒序，新条目插顶；AGENTS.md 只保留近期短条目）
+
+## 长流程与踩坑档案
+
+（多段操作流程、完整复现过程、部署记录等长条目，一节一事，标题即锚点）
+```
+
+### 插件状态自管（首次休眠）
+
+本提示词由 dsh-memory 插件注入。当全局 `~/.dsh/AGENTS.md` 与当前工作区记忆文件均已初始化完毕后，在首次会话收尾时用 write 把 `~/.dsh/.dsh-memory-state` 写为 `sleep`——此后新会话只注入休眠钩子，省下本段提示词的上下文开销；用户说「初始化记忆插件」时把该文件写回 `active` 即恢复完整注入（下一轮对话生效，无需重启）。
+
+<!-- DSH-MEMORY:SLEEP_HOOK_START -->
+当用户说「初始化记忆插件」（或明确要求重启记忆插件）时：用 write 把 `~/.dsh/.dsh-memory-state` 写为 `active`——下一轮对话起自动恢复本插件的完整注入，无需重启。
+<!-- DSH-MEMORY:SLEEP_HOOK_END -->