memory-bank-skill 7.2.1 → 7.3.0

package/README.md

@@ -180,5 +180,5 @@ service=memory-bank Plugin initialized (unified) {"projectRoot":"..."}
 
 ## 版本
 
-- **版本**: 7.1.0
-- **主要更新**: v7.1 Index-First + Direct-First 架构（意图驱动路由 + Gating 收紧 + 两层读取协议 + 模板升级路径）
+- **版本**: 7.3.0
+- **主要更新**: Doc-First Gate 默认启用（warn），无 Memory Bank 项目自动提醒初始化

package/dist/cli.js

@@ -27,7 +27,7 @@ import { fileURLToPath } from "url";
 // package.json
 var package_default = {
   name: "memory-bank-skill",
-  version: "7.2.1",
+  version: "7.3.0",
   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",

package/dist/plugin.js

@@ -24,6 +24,7 @@ import path from "path";
 var DEBUG = process.env.MEMORY_BANK_DEBUG === "1";
 var DEFAULT_MAX_CHARS = 12000;
 var GATING_MODE = process.env.MEMORY_BANK_GUARD_MODE || "warn";
+var DOC_FIRST_MODE = process.env.MEMORY_BANK_DOC_FIRST_MODE || "warn";
 var TRUNCATION_NOTICE = `
 
 ---
@@ -292,7 +293,7 @@ async function checkMemoryBankExists(root, log) {
 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 };
+    meta = { rootsTouched: new Set, lastActiveRoot: fallbackRoot, notifiedMessageIds: new Set, planOutputted: false, promptInProgress: false, userMessageReceived: false, sessionNotified: false, userMessageSeq: 0, pendingDocFirstSatisfied: false };
     sessionMetas.set(sessionId, meta);
   }
   return meta;
@@ -351,13 +352,32 @@ var EXCLUDED_DIRS = [
   /^\.claude\//
 ];
 var MEMORY_BANK_PATTERN = /^memory-bank\//;
+var DOC_FIRST_FILE_PATTERNS = [
+  /\.py$/,
+  /\.ts$/,
+  /\.tsx$/,
+  /\.js$/,
+  /\.jsx$/,
+  /\.go$/,
+  /\.rs$/,
+  /\.vue$/,
+  /\.svelte$/
+];
 function isDisabled() {
   return process.env.MEMORY_BANK_DISABLED === "1" || process.env.MEMORY_BANK_DISABLED === "true";
 }
-function getMessageGatingState(gatingKey) {
+function getMessageGatingState(gatingKey, sessionId, projectRoot) {
   let state = messageGatingStates.get(gatingKey);
   if (!state) {
-    state = { readFiles: new Set, contextSatisfied: false, warnedThisMessage: false };
+    let inheritDocFirst = false;
+    if (sessionId && projectRoot) {
+      const meta = sessionMetas.get(sessionId);
+      if (meta?.pendingDocFirstSatisfied) {
+        inheritDocFirst = true;
+        meta.pendingDocFirstSatisfied = false;
+      }
+    }
+    state = { readFiles: new Set, contextSatisfied: false, warnedThisMessage: false, docFirstSatisfied: inheritDocFirst, docFirstWarned: false };
     messageGatingStates.set(gatingKey, state);
     if (messageGatingStates.size > 100) {
       const first = messageGatingStates.keys().next().value;
@@ -928,7 +948,7 @@ ${triggers.join(`
           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 });
+          sessionMetas.set(sessionId, { rootsTouched: new Set, lastActiveRoot: projectRoot, notifiedMessageIds: new Set, planOutputted: false, promptInProgress: false, userMessageReceived: false, sessionNotified: false, userMessageSeq: 0, pendingDocFirstSatisfied: false });
           const parentID = info?.parentID;
           sessionsById.set(sessionId, { parentID });
           log.info("Session created", { sessionId, parentID });
@@ -1152,7 +1172,7 @@ Or call: proxy_task({ subagent_type: "memory-reader", ... })`);
         const meta = getSessionMeta(sessionID, projectRoot);
         const messageKey = meta.lastUserMessageKey || "default";
         const gatingKey = `${sessionID}::${messageKey}`;
-        const gatingState = getMessageGatingState(gatingKey);
+        const gatingState = getMessageGatingState(gatingKey, sessionID, projectRoot);
         const toolLower2 = tool.toLowerCase();
         const readTools = ["read"];
         if (readTools.includes(toolLower2)) {
@@ -1272,6 +1292,111 @@ Or call: proxy_task({ subagent_type: "memory-reader", ... })`);
           }
         }
       }
+      if (DOC_FIRST_MODE !== "off") {
+        const dfMeta = getSessionMeta(sessionID, projectRoot);
+        const dfMessageKey = dfMeta.lastUserMessageKey || "default";
+        const dfGatingKey = `${sessionID}::${dfMessageKey}`;
+        const dfState = getMessageGatingState(dfGatingKey, sessionID, projectRoot);
+        const dfToolLower = tool.toLowerCase();
+        const dfWriteTools = ["write", "edit", "multiedit", "apply_patch", "patch"];
+        if (dfWriteTools.includes(dfToolLower) && !dfState.docFirstSatisfied && !dfState.docFirstWarned) {
+          const dfTargetPaths = extractWritePaths(dfToolLower, output.args || {});
+          const mbCheckResults = await Promise.all(dfTargetPaths.map((p) => isMemoryBankPath(p)));
+          const hasCodeFile = dfTargetPaths.some((p, i) => {
+            if (mbCheckResults[i])
+              return false;
+            return DOC_FIRST_FILE_PATTERNS.some((pat) => pat.test(p.toLowerCase()));
+          });
+          if (hasCodeFile && !dfState.warnedThisMessage) {
+            const hasMemoryBank = await checkMemoryBankExists(projectRoot, log);
+            if (!hasMemoryBank) {
+              const state = getRootState(sessionID, projectRoot);
+              if (!state.initReminderFired) {
+                state.initReminderFired = true;
+                log.info("Doc-First Gate: no memory-bank, sending init suggestion", { sessionID });
+                client.session.prompt({
+                  path: { id: sessionID },
+                  body: {
+                    noReply: true,
+                    variant: PLUGIN_PROMPT_VARIANT,
+                    parts: [{
+                      type: "text",
+                      text: `## [Memory Bank] \u9879\u76EE\u5C1A\u672A\u542F\u7528
+
+` + `\u68C0\u6D4B\u5230\u4EE3\u7801\u5199\u5165\uFF0C\u4F46\u9879\u76EE\u5C1A\u672A\u542F\u7528 Memory Bank\u3002
+
+` + `\u5EFA\u8BAE\u8FD0\u884C \`/memory-bank-refresh\` \u521D\u59CB\u5316\uFF0C\u5F00\u542F\u6587\u6863\u5148\u884C\u5DE5\u4F5C\u6D41\u3002`
+                    }]
+                  }
+                }).catch((err) => log.error("Failed to send init suggestion:", String(err)));
+              }
+            } else if (DOC_FIRST_MODE === "block") {
+              log.warn("Doc-First Gate: code write blocked (no MB doc written)", {
+                sessionID,
+                gatingKey: dfGatingKey,
+                tool,
+                targetPaths: dfTargetPaths
+              });
+              throw new Error(`[Doc-First Gate] \u8BF7\u5148\u6C89\u6DC0\u5DE5\u4F5C\u6587\u6863\u518D\u5199\u4EE3\u7801\u3002
+
+` + `\u8BF7\u7528 MemoryWriter \u5148\u8BB0\u5F55\u4F60\u8981\u505A\u4EC0\u4E48\uFF1A
+` + `\u2022 \u4FEE Bug / \u8E29\u5751 \u2192 learnings/YYYY-MM-DD-xxx.md
+` + `\u2022 \u65B0\u529F\u80FD / \u9700\u6C42 \u2192 requirements/REQ-xxx.md
+` + `\u2022 \u91CD\u6784 / \u4F18\u5316 \u2192 design/design-xxx.md
+` + `\u2022 \u7B80\u5355\u53D8\u66F4 \u2192 \u8FFD\u52A0\u5230 progress.md
+
+` + `\u8C03\u7528\u65B9\u5F0F: proxy_task({ subagent_type: "memory-bank-writer", ... })
+` + `\u5199\u5B8C\u6587\u6863\u540E\u518D\u6267\u884C\u4EE3\u7801\u4FEE\u6539\u3002`);
+            } else {
+              dfState.docFirstWarned = true;
+              log.info("Doc-First Gate: warning issued", {
+                sessionID,
+                gatingKey: dfGatingKey,
+                tool,
+                targetPaths: dfTargetPaths
+              });
+              client.session.prompt({
+                path: { id: sessionID },
+                body: {
+                  noReply: true,
+                  variant: PLUGIN_PROMPT_VARIANT,
+                  parts: [{
+                    type: "text",
+                    text: `## \u26A0\uFE0F [Doc-First] \u5EFA\u8BAE\u5148\u6C89\u6DC0\u5DE5\u4F5C\u6587\u6863\u518D\u5199\u4EE3\u7801
+
+` + `\u8BF7\u7528 MemoryWriter \u5148\u8BB0\u5F55\u4F60\u8981\u505A\u4EC0\u4E48\uFF0C\u5E76\u4F5C\u4E3A\u7B2C\u4E00\u4F18\u5148\u7EA7 todo\uFF1A
+` + `\u2022 \u4FEE Bug / \u8E29\u5751 \u2192 learnings/YYYY-MM-DD-xxx.md
+` + `\u2022 \u65B0\u529F\u80FD / \u9700\u6C42 \u2192 requirements/REQ-xxx.md
+` + `\u2022 \u91CD\u6784 / \u4F18\u5316 \u2192 design/design-xxx.md
+` + `\u2022 \u7B80\u5355\u53D8\u66F4 \u2192 \u8FFD\u52A0\u5230 progress.md
+
+` + `\u8C03\u7528\u65B9\u5F0F: \`proxy_task({ subagent_type: "memory-bank-writer", ... })\``
+                  }]
+                }
+              }).catch((err) => log.error("Failed to send doc-first warning:", String(err)));
+            }
+          }
+        }
+      }
+      const markParentDocFirstSatisfied = (writerSessionID) => {
+        const parentID = sessionsById.get(writerSessionID)?.parentID;
+        if (!parentID)
+          return;
+        const parentMeta = getSessionMeta(parentID, projectRoot);
+        const parentMsgKey = parentMeta.lastUserMessageKey;
+        if (parentMsgKey) {
+          const parentGatingKey = `${parentID}::${parentMsgKey}`;
+          const parentGating = getMessageGatingState(parentGatingKey, parentID, projectRoot);
+          parentGating.docFirstSatisfied = true;
+          log.debug("Doc-First: parent satisfied via writer write", { writerSessionID, parentID, parentGatingKey });
+        }
+        const defaultGatingKey = `${parentID}::default`;
+        const defaultState = messageGatingStates.get(defaultGatingKey);
+        if (defaultState) {
+          defaultState.docFirstSatisfied = true;
+        }
+        parentMeta.pendingDocFirstSatisfied = true;
+      };
       const isWriterAllowed = (sid) => {
         if (writerSessionIDs.has(sid))
           return true;
@@ -1338,6 +1463,7 @@ Or call: proxy_task({ subagent_type: "memory-reader", ... })`);
           }
           if (isWriterAllowed(sessionID)) {
             log.debug("Writer agent write allowed", { sessionID, tool, targetPath });
+            markParentDocFirstSatisfied(sessionID);
             return;
           }
           blockWrite("not writer agent", {
@@ -1488,6 +1614,7 @@ Or call: proxy_task({ subagent_type: "memory-reader", ... })`);
             if (await isMemoryBankPath(resolvedTarget)) {
               if (isWriterAllowed(sessionID)) {
                 log.debug("Writer agent bash redirect allowed", { sessionID, command: command.slice(0, 100) });
+                markParentDocFirstSatisfied(sessionID);
                 return;
               }
               blockWrite("bash redirect to memory-bank", { command: command.slice(0, 200), segment: segment.slice(0, 100) });
@@ -1503,6 +1630,7 @@ Or call: proxy_task({ subagent_type: "memory-reader", ... })`);
                 if (await isMemoryBankPath(resolved)) {
                   if (isWriterAllowed(sessionID)) {
                     log.debug("Writer agent find with dangerous flags allowed", { sessionID });
+                    markParentDocFirstSatisfied(sessionID);
                     return;
                   }
                   blockWrite("find with dangerous flags on memory-bank", { command: command.slice(0, 200), segment: segment.slice(0, 100) });
@@ -1519,6 +1647,7 @@ Or call: proxy_task({ subagent_type: "memory-reader", ... })`);
             if (await isMemoryBankPath(resolved)) {
               if (isWriterAllowed(sessionID)) {
                 log.debug("Writer agent bash write allowed", { sessionID, command: command.slice(0, 100) });
+                markParentDocFirstSatisfied(sessionID);
                 return;
               }
               blockWrite("bash write to memory-bank", { command: command.slice(0, 200), pathArg, resolved });

package/package.json

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