memory-bank-skill 5.6.0 → 5.6.2

package/dist/cli.js

@@ -7,7 +7,57 @@ import { homedir } from "os";
 import { join, dirname } from "path";
 import { createHash } from "crypto";
 import { fileURLToPath } from "url";
-var VERSION = "5.6.0";
+// package.json
+var package_default = {
+  name: "memory-bank-skill",
+  version: "5.6.2",
+  description: "Memory Bank - \u9879\u76EE\u8BB0\u5FC6\u7CFB\u7EDF\uFF0C\u8BA9 AI \u52A9\u624B\u5728\u6BCF\u6B21\u5BF9\u8BDD\u4E2D\u90FD\u80FD\u5FEB\u901F\u7406\u89E3\u9879\u76EE\u4E0A\u4E0B\u6587",
+  type: "module",
+  main: "dist/plugin.js",
+  bin: {
+    "memory-bank-skill": "dist/cli.js"
+  },
+  files: [
+    "dist/",
+    "skill/",
+    "templates/"
+  ],
+  scripts: {
+    build: "bun build src/cli.ts plugin/memory-bank.ts --outdir dist --target bun && mv dist/src/cli.js dist/cli.js && mv dist/plugin/memory-bank.js dist/plugin.js && rm -rf dist/plugin dist/src",
+    prepublishOnly: "bun run build",
+    "test:install": "bun run build && bun ./dist/cli.js install",
+    "test:doctor": "bun run build && bun ./dist/cli.js doctor"
+  },
+  keywords: [
+    "opencode",
+    "plugin",
+    "memory-bank",
+    "ai",
+    "context",
+    "claude"
+  ],
+  author: "",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/user/memory-bank-skill.git"
+  },
+  engines: {
+    node: ">=18.0.0"
+  },
+  peerDependencies: {
+    "@opencode-ai/plugin": "^1.1.14"
+  },
+  publishConfig: {
+    registry: "https://registry.npmjs.org/"
+  },
+  devDependencies: {
+    "memory-bank-skill": "5.5.1"
+  }
+};
+
+// src/cli.ts
+var VERSION = package_default.version;
 var colors = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",

package/dist/memory-bank.js

@@ -0,0 +1,845 @@
+// plugin/memory-bank.ts
+import { stat, readFile } from "node:fs/promises";
+import { execSync } from "node:child_process";
+import path from "node:path";
+var DEBUG = process.env.MEMORY_BANK_DEBUG === "1";
+var DEFAULT_MAX_CHARS = 12000;
+var TRUNCATION_NOTICE = `
+
+---
+
+[TRUNCATED] Memory Bank context exceeded size limit. Read files directly for complete content.`;
+var MEMORY_BANK_FILES = [
+  "memory-bank/brief.md",
+  "memory-bank/active.md",
+  "memory-bank/_index.md"
+];
+var SENTINEL_OPEN = "<memory-bank-bootstrap>";
+var SENTINEL_CLOSE = "</memory-bank-bootstrap>";
+var SERVICE_NAME = "memory-bank";
+var PLUGIN_PROMPT_VARIANT = "memory-bank-plugin";
+var rootStates = new Map;
+var sessionMetas = new Map;
+var memoryBankExistsCache = new Map;
+var fileCache = new Map;
+var WRITER_AGENT_NAME = "memory-bank-writer";
+var sessionsById = new Map;
+var writerSessionIDs = new Set;
+var agentBySessionID = new Map;
+function makeStateKey(sessionId, root) {
+  return `${sessionId}::${root}`;
+}
+function maxChars() {
+  const raw = process.env.MEMORY_BANK_MAX_CHARS;
+  const n = raw ? Number(raw) : NaN;
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_MAX_CHARS;
+}
+function isPluginGeneratedPrompt(message, content) {
+  if (message?.variant === PLUGIN_PROMPT_VARIANT)
+    return true;
+  return content.includes("## [Memory Bank]") || content.includes("## [SYSTEM REMINDER - Memory Bank");
+}
+function getMessageKey(message, rawContent) {
+  const id = message?.id || message?.messageID;
+  if (id)
+    return String(id);
+  const created = message?.time?.created;
+  if (typeof created === "number")
+    return `ts:${created}`;
+  const trimmed = rawContent.trim();
+  if (trimmed)
+    return `content:${trimmed.slice(0, 200)}`;
+  return null;
+}
+function getOrCreateMessageKey(meta, message, rawContent) {
+  const directKey = getMessageKey(message, rawContent);
+  if (directKey && !directKey.startsWith("content:"))
+    return directKey;
+  const trimmed = rawContent.trim();
+  if (!trimmed)
+    return directKey ?? null;
+  const now = Date.now();
+  const digest = trimmed.slice(0, 200);
+  const sameAsLast = meta.lastUserMessageDigest === digest;
+  const withinWindow = typeof meta.lastUserMessageAt === "number" && now - meta.lastUserMessageAt < 2000;
+  if (sameAsLast && withinWindow && meta.lastUserMessageKey) {
+    return meta.lastUserMessageKey;
+  }
+  meta.userMessageSeq += 1;
+  const key = `seq:${meta.userMessageSeq}`;
+  meta.lastUserMessageDigest = digest;
+  meta.lastUserMessageAt = now;
+  meta.lastUserMessageKey = key;
+  return key;
+}
+function createLogger(client) {
+  let pending = Promise.resolve();
+  const formatArgs = (args) => {
+    return args.map((a) => {
+      if (typeof a === "string")
+        return a;
+      try {
+        const str = JSON.stringify(a);
+        return str.length > 2000 ? str.slice(0, 2000) + "..." : str;
+      } catch {
+        return String(a);
+      }
+    }).join(" ");
+  };
+  const enqueue = (level, message) => {
+    pending = pending.then(() => client.app.log({
+      body: { service: SERVICE_NAME, level, message }
+    })).catch(() => {});
+  };
+  return {
+    debug: (...args) => {
+      if (DEBUG)
+        enqueue("debug", formatArgs(args));
+    },
+    info: (...args) => enqueue("info", formatArgs(args)),
+    warn: (...args) => enqueue("warn", formatArgs(args)),
+    error: (...args) => enqueue("error", formatArgs(args)),
+    flush: () => pending
+  };
+}
+async function readTextCached(absPath) {
+  try {
+    const st = await stat(absPath);
+    const cached = fileCache.get(absPath);
+    if (cached && cached.mtimeMs === st.mtimeMs)
+      return cached.text;
+    const text = await readFile(absPath, "utf8");
+    fileCache.set(absPath, { mtimeMs: st.mtimeMs, text });
+    return text;
+  } catch {
+    return null;
+  }
+}
+function truncateToBudget(text, budget) {
+  if (text.length <= budget)
+    return text;
+  const reserve = TRUNCATION_NOTICE.length;
+  if (budget <= reserve)
+    return TRUNCATION_NOTICE.slice(0, budget);
+  return text.slice(0, budget - reserve) + TRUNCATION_NOTICE;
+}
+async function buildMemoryBankContextWithMeta(projectRoot) {
+  const fnStart = Date.now();
+  if (DEBUG)
+    console.error(`[MB-DEBUG] buildMemoryBankContextWithMeta START projectRoot=${projectRoot}`);
+  const parts = [];
+  const files = [];
+  for (const rel of MEMORY_BANK_FILES) {
+    const fileStart = Date.now();
+    const abs = path.join(projectRoot, rel);
+    if (DEBUG)
+      console.error(`[MB-DEBUG] reading ${rel}...`);
+    const content = await readTextCached(abs);
+    if (DEBUG)
+      console.error(`[MB-DEBUG] read ${rel} done, hasContent=${!!content}, elapsed=${Date.now() - fileStart}ms`);
+    if (!content)
+      continue;
+    const trimmed = content.trim();
+    if (!trimmed)
+      continue;
+    parts.push(`## ${rel}
+
+${trimmed}`);
+    files.push({ relPath: rel, chars: trimmed.length });
+  }
+  if (DEBUG)
+    console.error(`[MB-DEBUG] all files read, parts=${parts.length}, totalElapsed=${Date.now() - fnStart}ms`);
+  if (parts.length === 0)
+    return null;
+  const fileList = files.map((f) => f.relPath.replace("memory-bank/", "")).join(", ");
+  const totalChars = files.reduce((sum, f) => sum + f.chars, 0);
+  const header = `# Memory Bank Bootstrap (Auto-injected by OpenCode plugin)
+
+` + `Use \`memory-bank/_index.md\` to locate additional context files.
+` + `Read more files from \`memory-bank/\` as needed based on the task.
+
+` + `**AI 行为指令**：
+` + `- 每次回复末尾加一行确认：\`| \uD83D\uDCDA Memory Bank | ${fileList} (${totalChars.toLocaleString()} chars) |\`
+` + `- **Memory-first（核心原则）**：
+` + `  - 任何问题先查 _index.md 并打开相关文档（active.md/brief.md/tech.md/docs/requirements/learnings/patterns.md）
+` + `  - 找到答案 → 引用文件路径直接回答；_index.md 与对应目录检索无果或确认已过时 → 才读代码
+` + `  - 文档与代码不一致时以代码为准，但必须提议更新文档
+` + `  - 若因文档缺失而读了代码 → 这本身就是写入触发点，需点名要补的文件路径
+` + `- **文档驱动开发**：
+` + `  - 方案讨论完成后，**先写设计文档到 memory-bank/docs/，再写代码**
+` + `  - 设计文档是契约，代码实现要符合文档
+` + `  - 实现完成后回顾：如有偏差，决定是改文档还是改实现
+` + `- **写入触发场景**（语义判断，非关键词匹配）：
+` + `  - 方案讨论确定 / 设计变更（"重新设计"、"改一下设计"、"那就这样吧"）→ 检查 docs/design-*.md 是否已存在，存在则更新，否则创建
+` + `  - 用户描述新功能/需求（"我需要..."、"能不能加..."、"帮我做..."、"要实现..."）→ requirements/
+` + `  - 用户做出技术选型（"我们用 X 吧"、"决定采用..."、"选择..."）→ patterns.md
+` + `  - 修复了 bug 或踩坑经验（"原来问题是..."、"这个坑是..."、"发现..."）→ learnings/
+` + `  - AI 修改了代码/配置文件 → active.md（如涉及 bug 修复则同时 learnings/）
+` + `  - 当前任务完成，焦点切换 → active.md
+` + `- **Todo 创建规则（必须）**：
+` + `  - 方案讨论完成后开始落地：第一项必须是"写入设计文档到 memory-bank/docs/"
+` + `  - 最后一项必须是"更新 Memory Bank"（检查触发场景并更新相应文件）
+
+` + `---
+
+`;
+  const wrapped = `${SENTINEL_OPEN}
+` + header + parts.join(`
+
+---
+
+`) + `
+${SENTINEL_CLOSE}`;
+  const budget = maxChars();
+  const truncated = wrapped.length > budget;
+  const text = truncateToBudget(wrapped, budget);
+  return { text, files, totalChars, truncated };
+}
+async function buildMemoryBankContext(projectRoot) {
+  const result = await buildMemoryBankContextWithMeta(projectRoot);
+  return result?.text ?? null;
+}
+async function checkMemoryBankExists(root, log) {
+  if (memoryBankExistsCache.has(root)) {
+    const cached = memoryBankExistsCache.get(root);
+    if (cached) {
+      log.debug("memoryBankExists cache hit (true):", root);
+      return true;
+    }
+  }
+  try {
+    const mbPath = path.join(root, "memory-bank");
+    await stat(mbPath);
+    memoryBankExistsCache.set(root, true);
+    log.debug("memoryBankExists check: true for", root);
+    return true;
+  } catch {
+    memoryBankExistsCache.set(root, false);
+    log.debug("memoryBankExists check: false for", root);
+    return false;
+  }
+}
+function getSessionMeta(sessionId, fallbackRoot) {
+  let meta = sessionMetas.get(sessionId);
+  if (!meta) {
+    meta = { rootsTouched: new Set, lastActiveRoot: fallbackRoot, notifiedMessageIds: new Set, planOutputted: false, promptInProgress: false, userMessageReceived: false, sessionNotified: false, userMessageSeq: 0 };
+    sessionMetas.set(sessionId, meta);
+  }
+  return meta;
+}
+function getRootState(sessionId, root) {
+  const key = makeStateKey(sessionId, root);
+  let state = rootStates.get(key);
+  if (!state) {
+    state = {
+      filesModified: [],
+      hasNewRequirement: false,
+      hasTechDecision: false,
+      hasBugFix: false,
+      memoryBankReviewed: false,
+      skipInit: false,
+      initReminderFired: false,
+      lastUpdateReminderSignature: undefined,
+      lastSyncedTriggerSignature: undefined
+    };
+    rootStates.set(key, state);
+  }
+  return state;
+}
+var TRACKABLE_FILE_PATTERNS = [
+  /\.py$/,
+  /\.ts$/,
+  /\.tsx$/,
+  /\.js$/,
+  /\.jsx$/,
+  /\.go$/,
+  /\.rs$/,
+  /\.md$/,
+  /\.json$/,
+  /\.yaml$/,
+  /\.yml$/,
+  /\.toml$/,
+  /\.css$/,
+  /\.scss$/,
+  /\.html$/,
+  /\.vue$/,
+  /\.svelte$/
+];
+var EXCLUDED_DIRS = [
+  /^node_modules\//,
+  /^\.venv\//,
+  /^venv\//,
+  /^dist\//,
+  /^build\//,
+  /^\.next\//,
+  /^\.nuxt\//,
+  /^coverage\//,
+  /^\.pytest_cache\//,
+  /^__pycache__\//,
+  /^\.git\//,
+  /^\.opencode\//,
+  /^\.claude\//
+];
+var MEMORY_BANK_PATTERN = /^memory-bank\//;
+function isDisabled() {
+  return process.env.MEMORY_BANK_DISABLED === "1" || process.env.MEMORY_BANK_DISABLED === "true";
+}
+function computeTriggerSignature(state) {
+  return JSON.stringify({
+    files: [...state.filesModified].sort(),
+    flags: {
+      hasNewRequirement: state.hasNewRequirement,
+      hasTechDecision: state.hasTechDecision,
+      hasBugFix: state.hasBugFix
+    }
+  });
+}
+function detectGitChanges(root, log) {
+  try {
+    const stdout = execSync("git status --porcelain", {
+      cwd: root,
+      timeout: 5000,
+      encoding: "utf8"
+    });
+    if (!stdout.trim()) {
+      log.debug("No git changes detected in", root);
+      return { modifiedFiles: [], memoryBankUpdated: false };
+    }
+    const lines = stdout.replace(/[\r\n]+$/, "").split(/\r?\n/);
+    const modifiedFiles = [];
+    let memoryBankUpdated = false;
+    for (const line of lines) {
+      if (line.length < 4)
+        continue;
+      const x = line[0];
+      const y = line[1];
+      let payload = line.slice(3);
+      if (!payload)
+        continue;
+      if (payload.startsWith('"') && payload.endsWith('"')) {
+        payload = payload.slice(1, -1);
+      }
+      if ((x === "R" || x === "C") && payload.includes(" -> ")) {
+        payload = payload.split(" -> ")[1];
+      }
+      const relativePath = payload.replace(/\\/g, "/");
+      if (MEMORY_BANK_PATTERN.test(relativePath)) {
+        memoryBankUpdated = true;
+        log.debug("Git detected memory-bank update:", relativePath);
+        continue;
+      }
+      if (TRACKABLE_FILE_PATTERNS.some((p) => p.test(relativePath))) {
+        if (!EXCLUDED_DIRS.some((p) => p.test(relativePath))) {
+          const absPath = path.join(root, relativePath);
+          modifiedFiles.push(absPath);
+          log.debug("Git detected modified file:", relativePath);
+        }
+      }
+    }
+    log.info("Git changes detected", {
+      root,
+      modifiedCount: modifiedFiles.length,
+      memoryBankUpdated
+    });
+    return { modifiedFiles, memoryBankUpdated };
+  } catch (err) {
+    log.debug("Git detection failed (not a git repo?):", String(err));
+    return null;
+  }
+}
+var plugin = async ({ client, directory, worktree }) => {
+  const projectRoot = worktree || directory;
+  const log = createLogger(client);
+  log.info("Plugin initialized (unified)", { projectRoot });
+  async function sendContextNotification(sessionId, messageKey, messageId) {
+    if (isDisabled())
+      return;
+    const meta = getSessionMeta(sessionId, projectRoot);
+    if (meta.promptInProgress) {
+      log.debug("Context notification skipped (prompt in progress)", { sessionId, messageId });
+      return;
+    }
+    if (meta.notifiedMessageIds.has(messageKey)) {
+      log.debug("Context notification skipped (already notified for this message)", { sessionId, messageKey, messageId });
+      return;
+    }
+    const result = await buildMemoryBankContextWithMeta(projectRoot);
+    if (!result) {
+      log.debug("Context notification skipped (no memory-bank)", { sessionId });
+      return;
+    }
+    const fileList = result.files.map((f) => f.relPath.replace("memory-bank/", "")).join(", ");
+    const truncatedNote = result.truncated ? " (truncated)" : "";
+    const text = `## [Memory Bank]
+
+**已读取 Memory Bank 文件**: ${fileList} (${result.totalChars.toLocaleString()} chars)${truncatedNote}
+
+**写入提醒**：如果本轮涉及以下事件，工作完成后输出更新计划：
+- 新需求 → requirements/
+- 技术决策 → patterns.md
+- Bug修复/踩坑 → learnings/
+- 焦点变更 → active.md
+
+操作：请加载 memory-bank skill，按规范输出更新计划或更新内容（无需 slash command）。`;
+    try {
+      meta.promptInProgress = true;
+      await client.session.prompt({
+        path: { id: sessionId },
+        body: {
+          noReply: false,
+          variant: PLUGIN_PROMPT_VARIANT,
+          parts: [{ type: "text", text }]
+        }
+      });
+      meta.notifiedMessageIds.add(messageKey);
+      meta.sessionNotified = true;
+      if (meta.notifiedMessageIds.size > 100) {
+        const first = meta.notifiedMessageIds.values().next().value;
+        if (first)
+          meta.notifiedMessageIds.delete(first);
+      }
+      log.info("Context notification sent", { sessionId, messageKey, messageId, files: result.files.length, totalChars: result.totalChars });
+    } catch (err) {
+      log.error("Failed to send context notification:", String(err));
+    } finally {
+      meta.promptInProgress = false;
+    }
+  }
+  async function evaluateAndFireReminder(sessionId) {
+    if (isDisabled()) {
+      log.info("[SESSION_IDLE DECISION]", { sessionId, decision: "SKIP", reason: "MEMORY_BANK_DISABLED is set" });
+      return;
+    }
+    const meta = getSessionMeta(sessionId, projectRoot);
+    if (meta.promptInProgress) {
+      log.info("[SESSION_IDLE DECISION]", { sessionId, decision: "SKIP", reason: "prompt already in progress" });
+      return;
+    }
+    const gitChanges = detectGitChanges(projectRoot, log);
+    const isGitRepo = gitChanges !== null;
+    const state = getRootState(sessionId, projectRoot);
+    if (gitChanges) {
+      const { modifiedFiles, memoryBankUpdated: gitMemoryBankUpdated } = gitChanges;
+      state.filesModified = modifiedFiles;
+      if (gitMemoryBankUpdated) {
+        state.lastSyncedTriggerSignature = computeTriggerSignature(state);
+      }
+    }
+    memoryBankExistsCache.delete(projectRoot);
+    const hasMemoryBank = await checkMemoryBankExists(projectRoot, log);
+    const triggerSignature = computeTriggerSignature(state);
+    const decisionContext = {
+      sessionId,
+      root: projectRoot,
+      projectName: path.basename(projectRoot),
+      isGitRepo,
+      filesModified: state.filesModified.length,
+      hasMemoryBank,
+      initReminderFired: state.initReminderFired,
+      lastUpdateReminderSignature: state.lastUpdateReminderSignature,
+      lastSyncedTriggerSignature: state.lastSyncedTriggerSignature,
+      triggerSignature,
+      memoryBankReviewed: state.memoryBankReviewed,
+      skipInit: state.skipInit,
+      hasNewRequirement: state.hasNewRequirement,
+      hasTechDecision: state.hasTechDecision,
+      hasBugFix: state.hasBugFix
+    };
+    if (state.memoryBankReviewed) {
+      log.info("[SESSION_IDLE DECISION]", { ...decisionContext, decision: "SKIP", reason: "memoryBankReviewed escape valve active" });
+      return;
+    }
+    if (!hasMemoryBank) {
+      if (state.skipInit) {
+        log.info("[SESSION_IDLE DECISION]", { ...decisionContext, decision: "SKIP", reason: "skipInit escape valve active" });
+        return;
+      }
+      if (state.initReminderFired) {
+        log.info("[SESSION_IDLE DECISION]", { ...decisionContext, decision: "SKIP", reason: "initReminderFired already true" });
+        return;
+      }
+      state.initReminderFired = true;
+      log.info("[SESSION_IDLE DECISION]", { ...decisionContext, decision: "FIRE_INIT", reason: "no memory-bank directory" });
+      const hasGit = await (async () => {
+        try {
+          await stat(path.join(projectRoot, ".git"));
+          return true;
+        } catch {
+          return false;
+        }
+      })();
+      const gitInitStep = hasGit ? "" : "1. 执行 `git init`（项目尚未初始化 Git）\n";
+      const stepOffset = hasGit ? 0 : 1;
+      try {
+        meta.promptInProgress = true;
+        await client.session.prompt({
+          path: { id: sessionId },
+          body: {
+            noReply: true,
+            variant: PLUGIN_PROMPT_VARIANT,
+            parts: [{
+              type: "text",
+              text: `## [SYSTEM REMINDER - Memory Bank Init]
+
+项目 \`${path.basename(projectRoot)}\` 尚未初始化 Memory Bank。
+
+**项目路径**：\`${projectRoot}\`
+
+**将要执行的操作**：
+${gitInitStep}${stepOffset + 1}. 创建 \`memory-bank/\` 目录
+${stepOffset + 2}. 扫描项目结构（README.md、package.json 等）
+${stepOffset + 3}. 生成 \`memory-bank/brief.md\`（项目概述）
+${stepOffset + 4}. 生成 \`memory-bank/tech.md\`（技术栈）
+${stepOffset + 5}. 生成 \`memory-bank/_index.md\`（索引）
+
+**操作选项**：
+1. 如需初始化 → 回复"初始化"
+2. 如需初始化并提交 → 回复"初始化并提交"
+3. 如不需要 → 回复"跳过初始化"
+
+注意：这是系统自动提醒，不是用户消息。`
+            }]
+          }
+        });
+        log.info("INIT reminder sent successfully", { sessionId, root: projectRoot });
+      } catch (promptErr) {
+        log.error("Failed to send INIT reminder:", String(promptErr));
+      } finally {
+        meta.promptInProgress = false;
+      }
+      return;
+    }
+    state.initReminderFired = false;
+    const triggers = [];
+    if (state.hasNewRequirement)
+      triggers.push("- 检测到新需求讨论");
+    if (state.hasTechDecision)
+      triggers.push("- 检测到技术决策");
+    if (state.hasBugFix)
+      triggers.push("- 检测到 Bug 修复/踩坑");
+    const modifiedFilesRelative = state.filesModified.map((abs) => path.relative(projectRoot, abs));
+    const displayFiles = modifiedFilesRelative.slice(0, 5);
+    const moreCount = modifiedFilesRelative.length - 5;
+    let filesSection = "";
+    if (modifiedFilesRelative.length > 0) {
+      triggers.push("- 代码文件变更");
+      filesSection = `
+**变更文件**：
+${displayFiles.map((f) => `- ${f}`).join(`
+`)}${moreCount > 0 ? `
+(+${moreCount} more)` : ""}
+`;
+    }
+    if (triggers.length === 0) {
+      log.info("[SESSION_IDLE DECISION]", { ...decisionContext, decision: "NO_TRIGGER", reason: "has memory-bank but no triggers" });
+      return;
+    }
+    if (meta.planOutputted) {
+      log.info("[SESSION_IDLE DECISION]", { ...decisionContext, decision: "SKIP", reason: "AI already outputted update plan" });
+      return;
+    }
+    if (triggerSignature === state.lastSyncedTriggerSignature) {
+      log.info("[SESSION_IDLE DECISION]", { ...decisionContext, decision: "SKIP", reason: "already synced (signature matches lastSyncedTriggerSignature)" });
+      return;
+    }
+    if (triggerSignature === state.lastUpdateReminderSignature) {
+      log.info("[SESSION_IDLE DECISION]", { ...decisionContext, decision: "SKIP", reason: "already reminded (signature matches lastUpdateReminderSignature)" });
+      return;
+    }
+    state.lastUpdateReminderSignature = triggerSignature;
+    log.info("[SESSION_IDLE DECISION]", { ...decisionContext, decision: "FIRE_UPDATE", reason: `${triggers.length} triggers detected`, triggers });
+    try {
+      meta.promptInProgress = true;
+      await client.session.prompt({
+        path: { id: sessionId },
+        body: {
+          noReply: true,
+          variant: PLUGIN_PROMPT_VARIANT,
+          parts: [{
+            type: "text",
+            text: `## [SYSTEM REMINDER - Memory Bank Update]
+
+本轮检测到以下变更：${filesSection}
+**触发事件**：
+${triggers.join(`
+`)}
+
+**操作选项**：
+1. 如需更新 → 回复"更新"，输出更新计划
+2. 如需更新并提交 → 回复"更新并提交"
+3. 如不需要 → 回复"跳过"`
+          }]
+        }
+      });
+      log.info("UPDATE reminder sent successfully", { sessionId, root: projectRoot });
+    } catch (promptErr) {
+      log.error("Failed to send UPDATE reminder:", String(promptErr));
+    } finally {
+      meta.promptInProgress = false;
+    }
+  }
+  return {
+    "experimental.chat.system.transform": async (_input, output) => {
+      const hookStart = Date.now();
+      log.info("[HOOK] system.transform START");
+      try {
+        if (output.system.some((s) => s.includes(SENTINEL_OPEN))) {
+          log.info("[HOOK] system.transform SKIP (sentinel exists)", { elapsed: Date.now() - hookStart });
+          return;
+        }
+        log.info("[HOOK] system.transform building context...");
+        const ctx = await buildMemoryBankContext(projectRoot);
+        log.info("[HOOK] system.transform context built", { hasCtx: !!ctx, elapsed: Date.now() - hookStart });
+        if (ctx) {
+          output.system.push(ctx);
+          log.info("[HOOK] system.transform DONE (ctx pushed)", { elapsed: Date.now() - hookStart });
+          return;
+        }
+        const initInstruction = `${SENTINEL_OPEN}
+` + `# Memory Bank 未初始化
+
+` + `项目 \`${path.basename(projectRoot)}\` 尚未初始化 Memory Bank。
+
+` + `**AI 行为指令**：
+` + `- **Todo 创建规则（必须）**：创建 todo 时，第一项必须是"初始化 Memory Bank"（扫描项目结构，创建 brief.md + tech.md + _index.md），最后一项必须是"更新 Memory Bank"（更新 active.md）
+` + `${SENTINEL_CLOSE}`;
+        output.system.push(initInstruction);
+        log.info("[HOOK] system.transform DONE (init pushed)", { elapsed: Date.now() - hookStart });
+      } catch (err) {
+        log.error("[HOOK] system.transform ERROR", String(err), { elapsed: Date.now() - hookStart });
+      }
+    },
+    "experimental.session.compacting": async (_input, output) => {
+      const hookStart = Date.now();
+      log.info("[HOOK] session.compacting START");
+      try {
+        if (output.context.some((s) => s.includes(SENTINEL_OPEN))) {
+          log.info("[HOOK] session.compacting SKIP (sentinel exists)", { elapsed: Date.now() - hookStart });
+          return;
+        }
+        log.info("[HOOK] session.compacting building context...");
+        const ctx = await buildMemoryBankContext(projectRoot);
+        log.info("[HOOK] session.compacting context built", { hasCtx: !!ctx, elapsed: Date.now() - hookStart });
+        if (ctx) {
+          output.context.push(ctx);
+          log.info("[HOOK] session.compacting DONE (ctx pushed)", { elapsed: Date.now() - hookStart });
+          return;
+        }
+        const initInstruction = `${SENTINEL_OPEN}
+` + `# Memory Bank 未初始化
+
+` + `项目 \`${path.basename(projectRoot)}\` 尚未初始化 Memory Bank。
+
+` + `**AI 行为指令**：
+` + `- **Todo 创建规则（必须）**：创建 todo 时，第一项必须是"初始化 Memory Bank"（扫描项目结构，创建 brief.md + tech.md + _index.md），最后一项必须是"更新 Memory Bank"（更新 active.md）
+` + `${SENTINEL_CLOSE}`;
+        output.context.push(initInstruction);
+        log.info("[HOOK] session.compacting DONE (init pushed)", { elapsed: Date.now() - hookStart });
+      } catch (err) {
+        log.error("[HOOK] session.compacting ERROR", String(err), { elapsed: Date.now() - hookStart });
+      }
+    },
+    event: async ({ event }) => {
+      try {
+        let sessionId;
+        const props = event.properties;
+        const info = props?.info;
+        if (event.type === "session.created" || event.type === "session.deleted") {
+          sessionId = info?.id;
+        } else if (event.type === "message.updated") {
+          sessionId = info?.sessionID;
+        } else {
+          sessionId = info?.sessionID || info?.id || props?.sessionID || props?.session_id;
+        }
+        if (!sessionId) {
+          log.debug("event handler: no sessionId in event", event.type, JSON.stringify(props || {}).slice(0, 200));
+          return;
+        }
+        if (event.type === "session.created") {
+          sessionMetas.set(sessionId, { rootsTouched: new Set, lastActiveRoot: projectRoot, notifiedMessageIds: new Set, planOutputted: false, promptInProgress: false, userMessageReceived: false, sessionNotified: false, userMessageSeq: 0 });
+          const parentID = info?.parentID;
+          sessionsById.set(sessionId, { parentID });
+          log.info("Session created", { sessionId, parentID });
+        }
+        if (event.type === "session.deleted") {
+          const meta = sessionMetas.get(sessionId);
+          if (meta) {
+            for (const root of meta.rootsTouched) {
+              rootStates.delete(makeStateKey(sessionId, root));
+            }
+          }
+          sessionMetas.delete(sessionId);
+          sessionsById.delete(sessionId);
+          writerSessionIDs.delete(sessionId);
+          agentBySessionID.delete(sessionId);
+          log.info("Session deleted", { sessionId });
+        }
+        if (event.type === "message.updated") {
+          const message = info;
+          const meta = getSessionMeta(sessionId, projectRoot);
+          const rawContent = JSON.stringify(message?.content || "");
+          if (DEBUG) {
+            log.debug("message.updated received", {
+              sessionId,
+              role: message?.role,
+              agent: message?.agent,
+              variant: message?.variant,
+              messageId: message?.id || message?.messageID
+            });
+          }
+          if (isPluginGeneratedPrompt(message, rawContent)) {
+            log.debug("message.updated skipped (plugin prompt)", { sessionId });
+            return;
+          }
+          if (message?.role === "user") {
+            if (meta.promptInProgress) {
+              log.debug("message.updated skipped (prompt in progress)", { sessionId });
+              return;
+            }
+            const content = rawContent.toLowerCase();
+            const targetRoot = meta.lastActiveRoot || projectRoot;
+            const state = getRootState(sessionId, targetRoot);
+            if (/新需求|new req|feature request|需要实现|要做一个/.test(content)) {
+              state.hasNewRequirement = true;
+              log.debug("Keyword detected: newRequirement", { sessionId, root: targetRoot });
+            }
+            if (/决定用|选择了|我们用|技术选型|architecture|决策/.test(content)) {
+              state.hasTechDecision = true;
+              log.debug("Keyword detected: techDecision", { sessionId, root: targetRoot });
+            }
+            if (/bug|修复|fix|问题|error|踩坑|教训/.test(content)) {
+              state.hasBugFix = true;
+              log.debug("Keyword detected: bugFix", { sessionId, root: targetRoot });
+            }
+            if (/跳过初始化|skip.?init/.test(content)) {
+              state.skipInit = true;
+              log.info("Escape valve triggered: skipInit", { sessionId, root: targetRoot });
+            } else if (/memory.?bank.?reviewed|无需更新|不需要更新|已检查|^跳过$/.test(content)) {
+              state.memoryBankReviewed = true;
+              log.info("Escape valve triggered: memoryBankReviewed", { sessionId, root: targetRoot });
+            }
+            const messageId = message.id || message.messageID;
+            const messageKey = getOrCreateMessageKey(meta, message, rawContent);
+            if (!messageKey) {
+              log.debug("Context notification skipped (no message key)", { sessionId, messageId });
+              return;
+            }
+            log.debug("Context notification disabled (using system prompt instruction instead)", { sessionId, messageKey, messageId });
+            meta.userMessageReceived = true;
+            meta.planOutputted = false;
+          }
+          if (message?.role === "assistant") {
+            const content = JSON.stringify(message.content || "");
+            const meta2 = getSessionMeta(sessionId, projectRoot);
+            if (/Memory Bank 更新计划|\[Memory Bank 更新计划\]/.test(content)) {
+              meta2.planOutputted = true;
+              log.info("Plan outputted detected", { sessionId });
+            }
+            const agentName = message?.agent;
+            if (agentName) {
+              agentBySessionID.set(sessionId, agentName);
+              const sessionInfo = sessionsById.get(sessionId);
+              if (agentName === WRITER_AGENT_NAME && sessionInfo?.parentID) {
+                writerSessionIDs.add(sessionId);
+                log.info("Writer agent session registered", { sessionId, agentName, parentID: sessionInfo.parentID });
+              }
+            }
+          }
+        }
+      } catch (err) {
+        log.error("event handler error:", String(err));
+      }
+    },
+    "tool.execute.before": async (input, output) => {
+      const { tool, sessionID } = input;
+      const isMemoryBankPath = (targetPath) => {
+        const absPath = path.isAbsolute(targetPath) ? targetPath : path.resolve(projectRoot, targetPath);
+        const relativePath = path.relative(projectRoot, absPath);
+        if (relativePath === ".." || relativePath.startsWith(".." + path.sep))
+          return false;
+        return relativePath === "memory-bank" || relativePath.startsWith("memory-bank" + path.sep) || relativePath.startsWith("memory-bank/");
+      };
+      const isWriterAllowed = (sid) => {
+        if (writerSessionIDs.has(sid))
+          return true;
+        const sessionInfo = sessionsById.get(sid);
+        const agentName = agentBySessionID.get(sid);
+        if (agentName === WRITER_AGENT_NAME && sessionInfo?.parentID) {
+          writerSessionIDs.add(sid);
+          log.info("Writer agent late-registered", { sessionID: sid, agentName });
+          return true;
+        }
+        return false;
+      };
+      const blockWrite = (reason, context) => {
+        log.warn("Memory Bank write blocked", { sessionID, tool, reason, ...context });
+        throw new Error(`[Memory Bank Guard] 写入 memory-bank/ 受限。
+` + `请使用 delegate_task 调用 memory-bank-writer agent 来更新 Memory Bank。
+` + `示例: delegate_task(subagent_type="memory-bank-writer", load_skills=["memory-bank-writer"], prompt="更新...")`);
+      };
+      if (tool === "Write" || tool === "Edit") {
+        const targetPath = output.args?.filePath ?? output.args?.path ?? output.args?.filename;
+        if (!targetPath)
+          return;
+        if (!isMemoryBankPath(targetPath))
+          return;
+        if (!targetPath.endsWith(".md")) {
+          blockWrite("only .md files allowed", { targetPath });
+        }
+        if (isWriterAllowed(sessionID)) {
+          log.debug("Writer agent write allowed", { sessionID, tool, targetPath });
+          return;
+        }
+        blockWrite("not writer agent", {
+          targetPath,
+          isSubAgent: !!sessionsById.get(sessionID)?.parentID,
+          agentName: agentBySessionID.get(sessionID)
+        });
+      }
+      if (tool.toLowerCase() === "bash") {
+        const command = output.args?.command;
+        if (!command || typeof command !== "string")
+          return;
+        if (!/(?:^|[^A-Za-z0-9_-])memory-bank(?:$|[^A-Za-z0-9_-])/.test(command) && !command.startsWith("memory-bank"))
+          return;
+        const hasShellOperators = /[;&|]|\$\(|`/.test(command);
+        if (!hasShellOperators) {
+          const readOnlyPatterns = [
+            /^\s*(ls|cat|head|tail|less|more|grep|rg|ag|find|tree|wc|file|stat)\b/,
+            /^\s*git\s+(status|log|diff|show|blame)\b/
+          ];
+          if (readOnlyPatterns.some((p) => p.test(command)))
+            return;
+        }
+        const writePatterns = [
+          /(?:^|[^2])>/,
+          />>/,
+          /<</,
+          /\|/,
+          /\btee\b/,
+          /\bsed\s+-i/,
+          /\bperl\s+-[ip]/,
+          /\bcp\b/,
+          /\bmv\b/,
+          /\brm\b/,
+          /\bmkdir\b/,
+          /\btouch\b/,
+          /\bgit\s+(add|rm|mv|apply|checkout|restore|reset|clean|stash|commit)\b/,
+          /\bpython\b.*\bopen\b/
+        ];
+        const isWriteOperation = writePatterns.some((p) => p.test(command));
+        if (!isWriteOperation)
+          return;
+        if (isWriterAllowed(sessionID)) {
+          log.debug("Writer agent bash write allowed", { sessionID, command: command.slice(0, 100) });
+          return;
+        }
+        blockWrite("bash write operation", { command: command.slice(0, 200) });
+      }
+    }
+  };
+};
+var memory_bank_default = plugin;
+export {
+  memory_bank_default as default
+};

package/dist/plugin.js

@@ -23,6 +23,10 @@ var rootStates = new Map;
 var sessionMetas = new Map;
 var memoryBankExistsCache = new Map;
 var fileCache = new Map;
+var WRITER_AGENT_NAME = "memory-bank-writer";
+var sessionsById = new Map;
+var writerSessionIDs = new Set;
+var agentBySessionID = new Map;
 function makeStateKey(sessionId, root) {
   return `${sessionId}::${root}`;
 }
@@ -654,7 +658,9 @@ ${triggers.join(`
         }
         if (event.type === "session.created") {
           sessionMetas.set(sessionId, { rootsTouched: new Set, lastActiveRoot: projectRoot, notifiedMessageIds: new Set, planOutputted: false, promptInProgress: false, userMessageReceived: false, sessionNotified: false, userMessageSeq: 0 });
-          log.info("Session created", { sessionId });
+          const parentID = info?.parentID;
+          sessionsById.set(sessionId, { parentID });
+          log.info("Session created", { sessionId, parentID });
         }
         if (event.type === "session.deleted") {
           const meta = sessionMetas.get(sessionId);
@@ -664,6 +670,9 @@ ${triggers.join(`
             }
           }
           sessionMetas.delete(sessionId);
+          sessionsById.delete(sessionId);
+          writerSessionIDs.delete(sessionId);
+          agentBySessionID.delete(sessionId);
           log.info("Session deleted", { sessionId });
         }
         if (event.type === "message.updated") {
@@ -727,11 +736,107 @@ ${triggers.join(`
               meta2.planOutputted = true;
               log.info("Plan outputted detected", { sessionId });
             }
+            const agentName = message?.agent;
+            if (agentName) {
+              agentBySessionID.set(sessionId, agentName);
+              const sessionInfo = sessionsById.get(sessionId);
+              if (agentName === WRITER_AGENT_NAME && sessionInfo?.parentID) {
+                writerSessionIDs.add(sessionId);
+                log.info("Writer agent session registered", { sessionId, agentName, parentID: sessionInfo.parentID });
+              }
+            }
           }
         }
       } catch (err) {
         log.error("event handler error:", String(err));
       }
+    },
+    "tool.execute.before": async (input, output) => {
+      const { tool, sessionID } = input;
+      const isMemoryBankPath = (targetPath) => {
+        const absPath = path.isAbsolute(targetPath) ? targetPath : path.resolve(projectRoot, targetPath);
+        const relativePath = path.relative(projectRoot, absPath);
+        if (relativePath === ".." || relativePath.startsWith(".." + path.sep))
+          return false;
+        return relativePath === "memory-bank" || relativePath.startsWith("memory-bank" + path.sep) || relativePath.startsWith("memory-bank/");
+      };
+      const isWriterAllowed = (sid) => {
+        if (writerSessionIDs.has(sid))
+          return true;
+        const sessionInfo = sessionsById.get(sid);
+        const agentName = agentBySessionID.get(sid);
+        if (agentName === WRITER_AGENT_NAME && sessionInfo?.parentID) {
+          writerSessionIDs.add(sid);
+          log.info("Writer agent late-registered", { sessionID: sid, agentName });
+          return true;
+        }
+        return false;
+      };
+      const blockWrite = (reason, context) => {
+        log.warn("Memory Bank write blocked", { sessionID, tool, reason, ...context });
+        throw new Error(`[Memory Bank Guard] \u5199\u5165 memory-bank/ \u53D7\u9650\u3002
+` + `\u8BF7\u4F7F\u7528 delegate_task \u8C03\u7528 memory-bank-writer agent \u6765\u66F4\u65B0 Memory Bank\u3002
+` + `\u793A\u4F8B: delegate_task(subagent_type="memory-bank-writer", load_skills=["memory-bank-writer"], prompt="\u66F4\u65B0...")`);
+      };
+      if (tool === "Write" || tool === "Edit") {
+        const targetPath = output.args?.filePath ?? output.args?.path ?? output.args?.filename;
+        if (!targetPath)
+          return;
+        if (!isMemoryBankPath(targetPath))
+          return;
+        if (!targetPath.endsWith(".md")) {
+          blockWrite("only .md files allowed", { targetPath });
+        }
+        if (isWriterAllowed(sessionID)) {
+          log.debug("Writer agent write allowed", { sessionID, tool, targetPath });
+          return;
+        }
+        blockWrite("not writer agent", {
+          targetPath,
+          isSubAgent: !!sessionsById.get(sessionID)?.parentID,
+          agentName: agentBySessionID.get(sessionID)
+        });
+      }
+      if (tool.toLowerCase() === "bash") {
+        const command = output.args?.command;
+        if (!command || typeof command !== "string")
+          return;
+        if (!/(?:^|[^A-Za-z0-9_-])memory-bank(?:$|[^A-Za-z0-9_-])/.test(command) && !command.startsWith("memory-bank"))
+          return;
+        const hasShellOperators = /[;&|]|\$\(|`/.test(command);
+        if (!hasShellOperators) {
+          const readOnlyPatterns = [
+            /^\s*(ls|cat|head|tail|less|more|grep|rg|ag|find|tree|wc|file|stat)\b/,
+            /^\s*git\s+(status|log|diff|show|blame)\b/
+          ];
+          if (readOnlyPatterns.some((p) => p.test(command)))
+            return;
+        }
+        const writePatterns = [
+          /(?:^|[^2])>/,
+          />>/,
+          /<</,
+          /\|/,
+          /\btee\b/,
+          /\bsed\s+-i/,
+          /\bperl\s+-[ip]/,
+          /\bcp\b/,
+          /\bmv\b/,
+          /\brm\b/,
+          /\bmkdir\b/,
+          /\btouch\b/,
+          /\bgit\s+(add|rm|mv|apply|checkout|restore|reset|clean|stash|commit)\b/,
+          /\bpython\b.*\bopen\b/
+        ];
+        const isWriteOperation = writePatterns.some((p) => p.test(command));
+        if (!isWriteOperation)
+          return;
+        if (isWriterAllowed(sessionID)) {
+          log.debug("Writer agent bash write allowed", { sessionID, command: command.slice(0, 100) });
+          return;
+        }
+        blockWrite("bash write operation", { command: command.slice(0, 200) });
+      }
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-bank-skill",
-  "version": "5.6.0",
+  "version": "5.6.2",
   "description": "Memory Bank - 项目记忆系统，让 AI 助手在每次对话中都能快速理解项目上下文",
   "type": "module",
   "main": "dist/plugin.js",

package/skill/memory-bank-writer/README.md

@@ -0,0 +1,27 @@
+# Memory Bank Writer Skill
+
+Memory Bank 专用写入 Agent 的技能定义。
+
+## 用途
+
+主 Agent 无法直接写入 `memory-bank/` 目录，必须通过 delegate 调用此 Agent。
+
+## 调用方式
+
+```
+delegate_task(
+    subagent_type="memory-bank-writer",
+    load_skills=["memory-bank-writer"],
+    prompt="更新设计文档：[内容]"
+)
+```
+
+## 内置规则
+
+- 写入前 Glob 检查已有文件
+- 优先更新而非创建
+- 自动更新 `_index.md`
+
+## 文件
+
+- `SKILL.md` - 技能定义和规则

package/skill/memory-bank-writer/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: memory-bank-writer
+description: Memory Bank 专用写入 Agent - 负责所有 memory-bank/ 目录的写入操作
+---
+
+# Memory Bank Writer
+
+你是 Memory Bank 的专用写入 Agent。只有你能写入 `memory-bank/` 目录。
+
+## 核心职责
+
+1. 接收主 Agent 的写入请求
+2. 执行写入前检查（Glob 查找已有文件）
+3. 决定更新现有文件还是创建新文件
+4. 执行写入并更新索引
+
+## 写入规则（强制）
+
+### 设计文档 (`docs/design-*.md`)
+
+```
+1. Glob("memory-bank/docs/design-*.md") 获取所有设计文档
+2. 读取 _index.md 中的设计文档列表
+3. 检查是否有相关文档：
+   - 文件名包含相同关键词 → 更新该文件
+   - 标题描述相同主题 → 更新该文件
+   - 无匹配 → 创建新文件
+4. 输出决策理由
+```
+
+### 需求文档 (`requirements/REQ-*.md`)
+
+```
+1. 读取 requirements/ 目录现有文件
+2. 检查是否有相同需求（按标题/ID）
+3. 有 → 更新；无 → 创建新 REQ-xxx.md
+```
+
+### 经验文档 (`learnings/**/*.md`)
+
+```
+1. 确定类型：bugs / performance / integrations
+2. 检查是否有相同问题的记录
+3. 有 → 追加或更新；无 → 创建新文件
+4. 文件名格式：YYYY-MM-DD-{slug}.md
+```
+
+### 其他文件
+
+| 文件 | 规则 |
+|------|------|
+| `active.md` | 始终更新（不创建新的） |
+| `brief.md` | 始终更新（不创建新的） |
+| `tech.md` | 始终更新（不创建新的） |
+| `patterns.md` | 追加内容（不覆盖） |
+| `_index.md` | 每次写入后自动更新 |
+
+## 输出格式
+
+每次写入前，输出计划：
+
+```
+[Memory Bank Writer 写入计划]
+
+检查结果：
+- Glob docs/design-*.md → 找到 3 个文件
+- 相关文件：design-auth.md（标题含 "认证"）
+
+决策：更新 memory-bank/docs/design-auth.md（而非新建）
+
+将要写入：
+- 更新: memory-bank/docs/design-auth.md
+- 更新: memory-bank/_index.md
+
+执行写入...
+```
+
+## 索引更新
+
+每次写入后，检查并更新 `_index.md`：
+
+1. 新建文件 → 添加索引条目
+2. 更新文件 → 更新 `updated` 和 `size` 字段
+3. 删除文件 → 移除索引条目
+
+## 禁止行为
+
+- 不要跳过 Glob 检查
+- 不要在不确定时创建新文件（宁可询问）
+- 不要修改 `memory-bank/` 以外的文件
+- 不要删除文件（除非明确要求）
+
+## 错误处理
+
+如果写入失败：
+1. 报告具体错误
+2. 不要重试（让主 Agent 决定）
+3. 保持已写入的文件（不回滚）
+
+## 守卫机制
+
+Plugin 层面强制执行：
+- 只有 `memory-bank-writer` agent 能写入 `memory-bank/`
+- 只允许写入 `.md` 文件
+- 主 agent 直接写入会被阻止
+
+## 已知限制
+
+> 写入守卫是**策略守卫**，防止意外违规，不是安全边界。
+
+| 限制 | 说明 |
+|------|------|
+| Bash 启发式 | 变量间接、eval、脚本无法检测 |
+| Symlinks | 通过 symlink 可绕过路径检查 |
+| 首次写入 | 可能因 race condition 被阻止一次（重试即可） |