@max-null/dsh-memory 0.22.0 → 0.22.2

package/README.md

@@ -144,10 +144,24 @@ DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后
 - 只读文件、只复制——**绝不复用引擎的写入路径**。写路径会先 `reload()` 再合并，磁盘缺失时它会把内存覆盖掉，正是这次事故的成因；备份不能走同一条路。
 - 日记按**逐字节内容**判断是否已备份过，不按 mtime：复制与编辑都会动 mtime，内容才是事实。
 
-## 云同步（2026-11-11）
+## 云同步（2026-11-11）· **默认关闭**
 
 把本机记忆镜像到一个 git 仓库，多个环境之间共享同一份记忆。
 
+> **默认不启用，而且是显式开关。** `memory.sync.enabled` 为 `true` 时才注册
+> `memory_sync` 与 `memory_conflicts`——关着时**根本不注册**（模型看不到，也就不会去调），
+> 自述里的工具数停在 14。
+>
+> 判据**不是「配了 remote」**（2026-11-12 改）：填了目标地址不等于打开了功能，那会让一次
+> 配置试验变成意外开机。开关与目标解耦后，还多出一档「只开本地镜像、暂不推送」
+> ——此时 `remote` 留空即可，push 会明确回「未配置远端地址 —— 已完成本地提交」。
+>
+> 开关在插件页「记忆」详情里点（与日记开关同一张卡片）。值写进 **profile 的
+> `cordis.patch.yml`**（`memory.config.sync.enabled`，不是独立的设置文件）：该 profile 开了
+> `patchReload: live` 时即时生效，否则**重启实例后生效**——2026-11-12 在 dev 实例里实测，
+> 关掉热重载时点了开关、工具不会立刻出现。`remote` / `mirrorDir` 那几项决定连接目标，
+> 无论哪种情况都要重启。
+
 **为什么是「一条记忆一个文件」。** 整份 `memory.json` 放进 git 会撞：2026-11-06 实测，两端各新增一条记忆后 merge，`git` 报 `CONFLICT (content)`——两条记录挤在同一个插入点，按「取一边」解决会**静默丢掉另一端那条**，而 git 仍报「合并成功」。改成一条一个文件后同一场景是 `Merge made by the 'ort' strategy`，0 冲突。
 
 **项目身份用项目名，不用路径。** 本机 `H:\MaxNull\WorkStation` 与另一台机器 `D:\WorkStation` 是同一个项目——目录名（统一小写）决定它在 `records/project/` 下落到哪。用绝对路径哈希的话，换个盘符就成了另一个项目，记忆会静默分裂成两份互不相认的。
@@ -155,8 +169,9 @@ DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后
 ```yaml
 memory:
   sync:
+    enabled: true                    # 总开关；关着两个工具根本不注册
     mirrorDir: ''                    # 缺省 <DSH_HOME>/memory-sync
-    remote: ''                       # https 远端；缺省只做本地提交
+    remote: ''                       # https 远端；留空只做本地提交
     branch: main
     envName: ''                      # 本环境短名，冲突留证时用作后缀
 ```

package/client.js

@@ -104,51 +104,17 @@ function brainIcon() {
     strokeLinejoin: "round"
   }, BRAIN_PATHS.map((d, index) => (0, import_react.createElement)("path", { key: index, d })));
 }
-var SETTINGS_NAV_MARKER = "data-dsh-memory-settings-nav";
-var BRAIN_MASK_SVG = `%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M9.5 2A2.5 2.5 0 0 1 12 4.5v15a2.5 2.5 0 0 1-4.96.44 2.5 2.5 0 0 1-2.96-3.08 3 3 0 0 1-.34-5.58 2.5 2.5 0 0 1 1.32-4.24 2.5 2.5 0 0 1 1.98-3A2.5 2.5 0 0 1 9.5 2Z'/%3E%3Cpath d='M14.5 2A2.5 2.5 0 0 0 12 4.5v15a2.5 2.5 0 0 0 4.96.44 2.5 2.5 0 0 0 2.96-3.08 3 3 0 0 0 .34-5.58 2.5 2.5 0 0 0-1.32-4.24 2.5 2.5 0 0 0-1.98-3A2.5 2.5 0 0 0 14.5 2Z'/%3E%3C/svg%3E`;
-var NAV_ICON_CSS = `
-[data-dsh-memory-settings-nav] > svg:first-child { display: none; }
-[data-dsh-memory-settings-nav]::before {
-  content: '';
-  flex: none;
-  width: 16px;
-  height: 16px;
-  background: currentColor;
-  -webkit-mask: url("data:image/svg+xml,${BRAIN_MASK_SVG}") center / contain no-repeat;
-  mask: url("data:image/svg+xml,${BRAIN_MASK_SVG}") center / contain no-repeat;
-}
-`;
-var navCssInjected = false;
-function injectNavCss() {
-  if (navCssInjected || typeof document === "undefined") return;
-  navCssInjected = true;
-  const style = document.createElement("style");
-  style.setAttribute("data-plugin", "@max-null/dsh-memory");
-  style.textContent = NAV_ICON_CSS;
-  document.head.append(style);
-}
-function registerSettingsNavIcon(label) {
-  let disposed = false;
-  const sync = () => {
-    if (disposed) return;
-    const currentLabel = label().trim();
-    const buttons = document.querySelectorAll('[role="dialog"] nav button');
-    for (const button of buttons) {
-      const matches = currentLabel.length > 0 && button.textContent?.trim() === currentLabel;
-      if (matches) button.setAttribute(SETTINGS_NAV_MARKER, "");
-      else button.removeAttribute(SETTINGS_NAV_MARKER);
-    }
-  };
-  sync();
-  const observer = new MutationObserver(sync);
-  observer.observe(document.body, { childList: true, subtree: true, characterData: true });
-  return () => {
-    disposed = true;
-    observer.disconnect();
-    document.querySelectorAll(`[${SETTINGS_NAV_MARKER}]`).forEach((element) => {
-      element.removeAttribute(SETTINGS_NAV_MARKER);
-    });
-  };
+function navIcon(size) {
+  return (0, import_react.createElement)("svg", {
+    width: size,
+    height: size,
+    viewBox: "0 0 24 24",
+    fill: "none",
+    stroke: "currentColor",
+    strokeWidth: 2,
+    strokeLinecap: "round",
+    strokeLinejoin: "round"
+  }, BRAIN_PATHS.map((d, index) => (0, import_react.createElement)("path", { key: index, d })));
 }
 var STRINGS = {
   zh: {
@@ -1031,19 +997,8 @@ function SettingsMemoryView(props) {
     cwd: currentSessionCwd(props.ctx)
   });
 }
-function DiarySettingsCard(props) {
-  const { form } = props;
-  const [enabled, setEnabled] = (0, import_react.useState)(true);
-  (0, import_react.useEffect)(() => {
-    const read = () => {
-      setEnabled(form.getSnapshot()?.value?.diary?.enabled ?? true);
-    };
-    read();
-    const off = form.subscribe(read);
-    return () => {
-      if (typeof off === "function") off();
-    };
-  }, [form]);
+function SwitchRow(props) {
+  const { label, hint, enabled, ariaLabel, onToggle, divided } = props;
   return (0, import_react.createElement)(
     "div",
     {
@@ -1053,18 +1008,14 @@ function DiarySettingsCard(props) {
         justifyContent: "space-between",
         gap: 12,
         padding: "12px 0",
-        borderTop: "1px solid var(--dsw-alias-border-l2, #1e2836)"
+        ...divided ? { borderTop: "1px solid var(--dsw-alias-border-l2, #1e2836)" } : {}
       }
     },
     (0, import_react.createElement)(
       "div",
       { style: { minWidth: 0 } },
-      (0, import_react.createElement)("div", { style: { fontSize: 13, fontWeight: 600, color: "var(--dsw-alias-label-primary, #d8e0ea)" } }, "\u65E5\u8BB0"),
-      (0, import_react.createElement)(
-        "div",
-        { style: { fontSize: 11.5, color: "var(--dsw-alias-label-secondary, #67748a)", marginTop: 3, lineHeight: 1.5 } },
-        "\u672C\u673A\u5199\u65E5\u8BB0\u3002\u5173\u6389\u540E\u65E5\u8BB0\u5DE5\u5177\u62D2\u7EDD\u6267\u884C\u3001\u4E0D\u518D\u6CE8\u5165\u6307\u9488\uFF1B\u5DF2\u6709\u65E5\u8BB0\u6587\u4EF6\u539F\u6837\u4FDD\u7559\uFF0C\u4E0D\u4F1A\u88AB\u5220\u3002"
-      )
+      (0, import_react.createElement)("div", { style: { fontSize: 13, fontWeight: 600, color: "var(--dsw-alias-label-primary, #d8e0ea)" } }, label),
+      (0, import_react.createElement)("div", { style: { fontSize: 11.5, color: "var(--dsw-alias-label-secondary, #67748a)", marginTop: 3, lineHeight: 1.5 } }, hint)
     ),
     (0, import_react.createElement)(
       "button",
@@ -1072,17 +1023,8 @@ function DiarySettingsCard(props) {
         type: "button",
         role: "switch",
         "aria-checked": enabled,
-        "aria-label": "\u65E5\u8BB0\u5F00\u5173",
-        onClick: () => {
-          try {
-            const pending = form.mutate([{ op: "set", path: ["diary", "enabled"], value: !enabled }]);
-            void Promise.resolve(pending).catch((error) => {
-              console.warn("dsh-memory: \u65E5\u8BB0\u5F00\u5173\u5199\u5165\u5931\u8D25", error);
-            });
-          } catch (error) {
-            console.warn("dsh-memory: \u65E5\u8BB0\u5F00\u5173\u5199\u5165\u629B\u9519", error);
-          }
-        },
+        "aria-label": ariaLabel,
+        onClick: onToggle,
         style: {
           flex: "none",
           width: 40,
@@ -1110,6 +1052,52 @@ function DiarySettingsCard(props) {
     )
   );
 }
+function MemorySettingsCard(props) {
+  const { form } = props;
+  const [diary, setDiary] = (0, import_react.useState)(true);
+  const [sync, setSync] = (0, import_react.useState)(false);
+  (0, import_react.useEffect)(() => {
+    const read = () => {
+      setDiary(form.getSnapshot()?.value?.diary?.enabled ?? true);
+      setSync(form.getSnapshot()?.value?.sync?.enabled ?? false);
+    };
+    read();
+    const off = form.subscribe(read);
+    return () => {
+      if (typeof off === "function") off();
+    };
+  }, [form]);
+  const write = (path, value, what) => {
+    try {
+      const pending = form.mutate([{ op: "set", path, value }]);
+      void Promise.resolve(pending).catch((error) => {
+        console.warn(`dsh-memory: ${what}\u5F00\u5173\u5199\u5165\u5931\u8D25`, error);
+      });
+    } catch (error) {
+      console.warn(`dsh-memory: ${what}\u5F00\u5173\u5199\u5165\u629B\u9519`, error);
+    }
+  };
+  return (0, import_react.createElement)(
+    "div",
+    null,
+    (0, import_react.createElement)(SwitchRow, {
+      label: "\u65E5\u8BB0",
+      hint: "\u672C\u673A\u5199\u65E5\u8BB0\u3002\u5173\u6389\u540E\u65E5\u8BB0\u5DE5\u5177\u62D2\u7EDD\u6267\u884C\u3001\u4E0D\u518D\u6CE8\u5165\u6307\u9488\uFF1B\u5DF2\u6709\u65E5\u8BB0\u6587\u4EF6\u539F\u6837\u4FDD\u7559\uFF0C\u4E0D\u4F1A\u88AB\u5220\u3002",
+      enabled: diary,
+      ariaLabel: "\u65E5\u8BB0\u5F00\u5173",
+      onToggle: () => write(["diary", "enabled"], !diary, "\u65E5\u8BB0"),
+      divided: false
+    }),
+    (0, import_react.createElement)(SwitchRow, {
+      label: "\u4E91\u540C\u6B65",
+      hint: "\u628A\u672C\u673A\u8BB0\u5FC6\u955C\u50CF\u5230\u4E00\u4E2A git \u4ED3\u5E93\uFF0C\u591A\u4E2A\u73AF\u5883\u5171\u7528\u4E00\u4EFD\u8BB0\u5FC6\u3002\u5173\u7740\u65F6 memory_sync \u4E0E memory_conflicts \u6839\u672C\u4E0D\u6CE8\u518C\u3002\u6253\u5F00\u540E\u8FD8\u9700\u8981\u5728\u63D2\u4EF6\u914D\u7F6E\u91CC\u586B sync.remote\uFF08\u7559\u7A7A = \u53EA\u505A\u672C\u5730\u955C\u50CF\u4E0E\u63D0\u4EA4\uFF09\u3002\u5F00\u5173\u5199\u5165 profile \u7684 cordis.patch.yml\uFF1Aprofile \u5F00 patchReload: live \u65F6\u5373\u65F6\u751F\u6548\uFF0C\u5426\u5219\u91CD\u542F\u5B9E\u4F8B\u540E\u751F\u6548\u3002",
+      enabled: sync,
+      ariaLabel: "\u4E91\u540C\u6B65\u5F00\u5173",
+      onToggle: () => write(["sync", "enabled"], !sync, "\u4E91\u540C\u6B65"),
+      divided: true
+    })
+  );
+}
 function apply(ctx) {
   const face = ctx;
   const locale = face.get?.("locale");
@@ -1120,7 +1108,6 @@ function apply(ctx) {
   });
   const slots = ctx.slots;
   if (slots?.inject !== void 0) {
-    injectNavCss();
     slots.inject("settings.section", () => slots.register({
       name: "settings.section",
       id: "dsh-memory",
@@ -1130,7 +1117,12 @@ function apply(ctx) {
     }, () => (0, import_react.createElement)(SettingsMemoryView, {
       ctx
     })));
-    face.effect?.(() => registerSettingsNavIcon(() => STRINGS[localeId].tabMemory), "dsh-memory: settings navigation icon");
+    slots.inject("settings.section.icon", () => slots.register({
+      name: "settings.section.icon",
+      id: "dsh-memory",
+      order: 60,
+      label: () => STRINGS[localeId].tabMemory
+    }, (props) => navIcon(props?.size ?? 16)));
   }
   try {
     const configForms = face.get?.("configForms");
@@ -1140,10 +1132,10 @@ function apply(ctx) {
         name: "plugins.bundle.config",
         key: "@max-null/dsh-memory",
         inject: () => ({})
-      }, () => (0, import_react.createElement)(DiarySettingsCard, { form: settingsForm })));
+      }, () => (0, import_react.createElement)(MemorySettingsCard, { form: settingsForm })));
     }
   } catch (error) {
-    console.warn("dsh-memory: \u65E5\u8BB0\u914D\u7F6E\u5361\u7247\u672A\u6CE8\u518C\uFF08\u4E0D\u5F71\u54CD\u8BB0\u5FC6\u4E0E\u65E5\u8BB0\u5DE5\u5177\uFF09", error);
+    console.warn("dsh-memory: \u8BBE\u7F6E\u5361\u7247\u672A\u6CE8\u518C\uFF08\u4E0D\u5F71\u54CD\u8BB0\u5FC6\u4E0E\u65E5\u8BB0\u5DE5\u5177\uFF09", error);
   }
   const root = ctx;
   if (root.inject === void 0) return;

package/dist/engine.d.ts

@@ -370,14 +370,16 @@ export interface MemoryConfig {
      */
     backup?: MemoryBackupConfig;
     /**
-     * 云同步配置（2026-11-11）：`{ mirrorDir, remote?, branch?, envName? }`。
+     * 云同步配置（2026-11-11；2026-11-12 改成显式开关）：
+     * `{ enabled, mirrorDir, remote?, branch?, envName? }`。
      *
-     * 缺省不配 = 不同步。设计见 `docs/设计/2026-11-06-记忆云同步-设计方案.md`。
+     * **开关是 `enabled`，不是「配了 remote 就算开」**——与日记同一个模式。缺省不配 = 不同步。
+     * 设计见 `docs/设计/2026-11-06-记忆云同步-设计方案.md`。
      */
     sync?: unknown;
     /**
-     * 日记开关的**部署默认值**（2026-10-24）。运行中的选择在面板里改，写入
-     * `$DSH_HOME/memory-settings.json`；两边都开才开——否则部署时关掉会被
+     * 日记开关的**部署默认值**（2026-10-24）。运行中的选择在面板里改，值写进
+     * profile 的 `cordis.patch.yml`（**不另设存储文件**，见设计文档 §四）；两边都开才开——否则部署时关掉会被
      * 使用者那一侧缺省的 `true` 翻回来。
      *
      * 关掉时日记工具会拒绝写入、不注入指针、也不提醒；已有的 md 文件原样保留

package/dist/index.d.ts

@@ -34,11 +34,31 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     embeddings: z<any, any, "plain">;
     backup: z<any, any, "plain">;
     /**
-     * 云同步配置（2026-11-11）：`{ mirrorDir, remote?, branch?, envName? }`。
+     * 云同步配置（2026-11-11；2026-11-12 改成显式开关）。
      *
-     * 缺省不配 = 不同步。设计见 `docs/设计/2026-11-06-记忆云同步-设计方案.md`。
+     * **用 `enabled` 开关，而不是「配了 remote 就算开」**：与日记同一个模式。语义清楚得多
+     * ——「我打开了这个功能」和「我碰巧填了一个字段」是两件事；而且开启后可以只配一部分
+     * （比如只做本地镜像、暂不推送）。
+     *
+     * `volatile()` 让 `enabled` 能在运行时改：设置面板把值写进 profile 的
+     * `cordis.patch.yml`，是否即时生效取决于该 profile 的 `patchReload`（`live` 才热重载）。
+     * 其余字段（remote / branch 等）改了要重启——它们决定的是连接目标，不是临时状态。
+     *
+     * 默认 **关闭**：实验性功能不该影响别人的安装。
      */
-    sync: z<any, any, "plain">;
+    sync: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        mirrorDir: z<string, string, "defined">;
+        remote: z<string, string, "defined">;
+        branch: z<string, string, "defined">;
+        envName: z<string, string, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        mirrorDir: z<string, string, "defined">;
+        remote: z<string, string, "defined">;
+        branch: z<string, string, "defined">;
+        envName: z<string, string, "defined">;
+    }>>>, "volatile-defined">;
     /**
      * 日记开关。默认开——这是**功能默认，不是采集默认**。
      *
@@ -61,11 +81,31 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     embeddings: z<any, any, "plain">;
     backup: z<any, any, "plain">;
     /**
-     * 云同步配置（2026-11-11）：`{ mirrorDir, remote?, branch?, envName? }`。
+     * 云同步配置（2026-11-11；2026-11-12 改成显式开关）。
      *
-     * 缺省不配 = 不同步。设计见 `docs/设计/2026-11-06-记忆云同步-设计方案.md`。
+     * **用 `enabled` 开关，而不是「配了 remote 就算开」**：与日记同一个模式。语义清楚得多
+     * ——「我打开了这个功能」和「我碰巧填了一个字段」是两件事；而且开启后可以只配一部分
+     * （比如只做本地镜像、暂不推送）。
+     *
+     * `volatile()` 让 `enabled` 能在运行时改：设置面板把值写进 profile 的
+     * `cordis.patch.yml`，是否即时生效取决于该 profile 的 `patchReload`（`live` 才热重载）。
+     * 其余字段（remote / branch 等）改了要重启——它们决定的是连接目标，不是临时状态。
+     *
+     * 默认 **关闭**：实验性功能不该影响别人的安装。
      */
-    sync: z<any, any, "plain">;
+    sync: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        mirrorDir: z<string, string, "defined">;
+        remote: z<string, string, "defined">;
+        branch: z<string, string, "defined">;
+        envName: z<string, string, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+        mirrorDir: z<string, string, "defined">;
+        remote: z<string, string, "defined">;
+        branch: z<string, string, "defined">;
+        envName: z<string, string, "defined">;
+    }>>>, "volatile-defined">;
     /**
      * 日记开关。默认开——这是**功能默认，不是采集默认**。
      *

package/dist/index.js

@@ -13,7 +13,7 @@ import { MemoryGateway } from "./remote.js";
 import { runMemoryBackup } from "./backup.js";
 import { ANCHOR_KINDS } from "./anchors.js";
 import { mountMemoryApi } from "./routes.js";
-import { SELF_DESCRIPTION } from "./self.js";
+import { buildSelfDescription } from "./self.js";
 import { appendEntry, diaryDir, lastWriteAt, pointerLine, readDay, recentDates } from "./diary.js";
 import z from '@deepseek-ai/schemastery';
 import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, candidateNotice, indexNotice, neighborNotice, neutralizeBraces, omittedNotice, renderInjection, staleNotice } from "./injection.js";
@@ -45,11 +45,25 @@ export const Config = z.object({
     embeddings: z.any(),
     backup: z.any(),
     /**
-     * 云同步配置（2026-11-11）：`{ mirrorDir, remote?, branch?, envName? }`。
+     * 云同步配置（2026-11-11；2026-11-12 改成显式开关）。
      *
-     * 缺省不配 = 不同步。设计见 `docs/设计/2026-11-06-记忆云同步-设计方案.md`。
+     * **用 `enabled` 开关，而不是「配了 remote 就算开」**：与日记同一个模式。语义清楚得多
+     * ——「我打开了这个功能」和「我碰巧填了一个字段」是两件事；而且开启后可以只配一部分
+     * （比如只做本地镜像、暂不推送）。
+     *
+     * `volatile()` 让 `enabled` 能在运行时改：设置面板把值写进 profile 的
+     * `cordis.patch.yml`，是否即时生效取决于该 profile 的 `patchReload`（`live` 才热重载）。
+     * 其余字段（remote / branch 等）改了要重启——它们决定的是连接目标，不是临时状态。
+     *
+     * 默认 **关闭**：实验性功能不该影响别人的安装。
      */
-    sync: z.any(),
+    sync: z.object({
+        enabled: z.boolean().default(false),
+        mirrorDir: z.string().default(''),
+        remote: z.string().default(''),
+        branch: z.string().default('main'),
+        envName: z.string().default(''),
+    }).default({ enabled: false }).volatile(),
     /**
      * 日记开关。默认开——这是**功能默认，不是采集默认**。
      *
@@ -93,6 +107,35 @@ function diaryOn(config) {
         : raw;
     return unwrapped?.enabled !== false;
 }
+/**
+ * 解包 `config.sync`。
+ *
+ * `config.sync` 经 loader 解析后是 `Volatile<{...}>`（`settings` 侧的解包就是
+ * `isVolatile(v) → v.get()`）——**schema 声明了 `.volatile()`，所以挂载时一定会被包装**，
+ * 直接读字段拿到的是空的。裸对象只在直接调用 `apply` 的场合出现，一并兜住。
+ * 开关与字段读的是同一份解包结果，所以只在这里做一次。
+ * @param config - 插件配置。
+ * @returns 解包后的对象；没配就是空对象（字段全按「缺省」处理）。
+ */
+function syncSettings(config) {
+    const raw = config?.sync;
+    if (raw === undefined || raw === null)
+        return {};
+    const unwrapped = typeof raw.get === 'function'
+        ? raw.get()
+        : raw;
+    return (unwrapped ?? {});
+}
+/**
+ * 读云同步开关。
+ *
+ * 判据是显式 `enabled`，不是「配了 remote」——与日记同一个模式（2026-11-12）。
+ * 与日记相反：**解不出来就是关**（`=== true` 才开）。默认值必须与 schema 的
+ * `default(false)` 一致——实验性功能不能因为读不到开关就自己跑起来。
+ */
+function syncOn(config) {
+    return syncSettings(config).enabled === true;
+}
 /** 日记提醒的冷却窗口（毫秒）。6 小时是拍出来的第一个值，实测后再调。 */
 const DIARY_REMIND_MS = 6 * 60 * 60 * 1000;
 /**
@@ -508,12 +551,18 @@ export async function apply(ctx, config) {
         order: 115,
         text: GUIDANCE,
     });
+    // 云同步**默认关闭**（2026-11-11）：实验性功能不该影响别人的安装。判据是显式开关
+    // `enabled`（2026-11-12，与日记一致）——「我打开了这个功能」与「我碰巧填了一个
+    // remote」是两件事，后者会让一次配置试验变成意外开机。关闭时那两个工具**根本不
+    // 注册**，而不是注册了再报错：模型看不到就不会去调。
+    const syncEnabled = syncOn(config);
     // 0.3.2：记忆机制自述——常驻注入（不落用户存储），随发版更新。
     // order 49 < recall(50)：机制说明在具体记忆内容之前。
     ctx.systemPrompt.context({
         name: 'memory:self',
         order: 49,
-        text: SELF_DESCRIPTION,
+        // 自述里的工具清单必须与实际注册的一致：漏一个，模型就按一份不存在的工具面行事。
+        text: buildSelfDescription(syncEnabled),
     });
     const injectionBudget = config?.injectionBudget ?? DEFAULT_INJECTION_BUDGET;
     const summaryChars = config?.summaryChars ?? DEFAULT_SUMMARY_CHARS;
@@ -1018,10 +1067,12 @@ export async function apply(ctx, config) {
     // 决定。把 `git pull --rebase && git add && git commit && git push` 那一串交给模型，
     // 出错难排查，也容易越权。
     //
-    // 缺省不启用：没配 `memory.sync` 时这两个工具直接报「未配置」，而不是默默什么都不做——
-    // 静默不动作比报错更坏。
+    // 缺省不启用：没打开 `memory.sync.enabled` 时这两个工具根本不注册（见上面的
+    // `syncEnabled`）；打开之后配置才可能不全——`remote` 为空就只做本地提交。
     const syncConfig = () => {
-        const raw = (config?.sync ?? {});
+        // 走 {@link syncSettings} 解包：`.volatile()` 包装后直接读字段是空的，
+        // 「开关打开了、配置读不出来」正是半成品状态会踩的坑。
+        const raw = syncSettings(config);
         const mirrorDir = typeof raw.mirrorDir === 'string' && raw.mirrorDir !== ''
             ? raw.mirrorDir
             : join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'memory-sync');
@@ -1032,56 +1083,58 @@ export async function apply(ctx, config) {
             ...typeof raw.envName === 'string' && raw.envName !== '' ? { envName: raw.envName } : {},
         };
     };
-    ctx.tools.register(defineTool({
-        name: registered('memory_sync'),
-        description: 'Push this machine\'s memories to the sync repo, pull other machines\' memories back, or inspect sync state. Conflicts are never auto-resolved — both versions are kept under conflicts/ for a human to settle. 把本机记忆推到同步仓库 / 拉回其他机器的记忆 / 查看同步状态。冲突不会自动裁决：两边版本都留在 conflicts/ 里等人处理。',
-        parameters: {
-            action: {
-                type: 'string',
-                required: true,
-                enum: ['status', 'pull', 'push'],
-                description: 'status = 只看状态（不读不写）；pull = 拉取并导入；push = 镜像、提交并推送。',
+    if (syncEnabled) {
+        ctx.tools.register(defineTool({
+            name: registered('memory_sync'),
+            description: 'Push this machine\'s memories to the sync repo, pull other machines\' memories back, or inspect sync state. Conflicts are never auto-resolved — both versions are kept under conflicts/ for a human to settle. 把本机记忆推到同步仓库 / 拉回其他机器的记忆 / 查看同步状态。冲突不会自动裁决：两边版本都留在 conflicts/ 里等人处理。',
+            parameters: {
+                action: {
+                    type: 'string',
+                    required: true,
+                    enum: ['status', 'pull', 'push'],
+                    description: 'status = 只看状态（不读不写）；pull = 拉取并导入；push = 镜像、提交并推送。',
+                },
             },
-        },
-        output: {
-            schema: { type: 'object', additionalProperties: true, properties: {} },
-            render: (_args, value) => renderJson(value),
-        },
-        async execute(args) {
-            const cfg = syncConfig();
-            const run = args.action === 'push'
-                ? await syncPush(memory, cfg)
-                : args.action === 'pull'
-                    ? await syncPull(memory, cfg)
-                    : await syncStatus(cfg);
-            // 工具返回值要求 `Record<string, JsonValue>`；这几个结果都是普通可序列化对象，
-            // 结构化类型对不上而已。走一遍 JSON 往返顺便保证它确实可序列化。
-            return JSON.parse(JSON.stringify(run));
-        },
-        presentCall: args => present('Sync memory', 'other'),
-    }));
-    ctx.tools.register(defineTool({
-        name: registered('memory_conflicts'),
-        description: 'List memory conflicts left by sync. Sync never auto-resolves them: if two machines changed the same memory, both versions were kept. 列出同步留下的记忆冲突。同步不会自动裁决——两端改过同一条时，两个版本都留着。',
-        parameters: {
-            action: {
-                type: 'string',
-                required: true,
-                enum: ['list'],
-                description: 'list = 列出 conflicts/ 下的冲突文件。',
+            output: {
+                schema: { type: 'object', additionalProperties: true, properties: {} },
+                render: (_args, value) => renderJson(value),
             },
-        },
-        output: {
-            schema: { type: 'object', additionalProperties: true, properties: {} },
-            render: (_args, value) => renderJson(value),
-        },
-        async execute() {
-            const cfg = syncConfig();
-            const files = conflictFiles(cfg);
-            return { count: files.length, files };
-        },
-        presentCall: () => present('List memory conflicts', 'other'),
-    }));
+            async execute(args) {
+                const cfg = syncConfig();
+                const run = args.action === 'push'
+                    ? await syncPush(memory, cfg)
+                    : args.action === 'pull'
+                        ? await syncPull(memory, cfg)
+                        : await syncStatus(cfg);
+                // 工具返回值要求 `Record<string, JsonValue>`；这几个结果都是普通可序列化对象，
+                // 结构化类型对不上而已。走一遍 JSON 往返顺便保证它确实可序列化。
+                return JSON.parse(JSON.stringify(run));
+            },
+            presentCall: args => present('Sync memory', 'other'),
+        }));
+        ctx.tools.register(defineTool({
+            name: registered('memory_conflicts'),
+            description: 'List memory conflicts left by sync. Sync never auto-resolves them: if two machines changed the same memory, both versions were kept. 列出同步留下的记忆冲突。同步不会自动裁决——两端改过同一条时，两个版本都留着。',
+            parameters: {
+                action: {
+                    type: 'string',
+                    required: true,
+                    enum: ['list'],
+                    description: 'list = 列出 conflicts/ 下的冲突文件。',
+                },
+            },
+            output: {
+                schema: { type: 'object', additionalProperties: true, properties: {} },
+                render: (_args, value) => renderJson(value),
+            },
+            async execute() {
+                const cfg = syncConfig();
+                const files = conflictFiles(cfg);
+                return { count: files.length, files };
+            },
+            presentCall: () => present('List memory conflicts', 'other'),
+        }));
+    }
     // 定时备份（2026-10-18 事故后新增）：只读复制，绝不走引擎的写入路径。
     // 首次延迟 1 分钟避开启动高峰；此后按 `backup.intervalMinutes` 重复；`unref` 不挡进程退出。
     const backup = config?.backup;

package/dist/self.d.ts

@@ -1,2 +1,5 @@
 export declare const SELF_VERSION: string;
+/** 能力全貌（面板 / 远端视图用；同步未启用时也展示它的存在）。 */
 export declare const SELF_DESCRIPTION: string;
+/** 按当前是否启用同步生成自述——系统提示那一路用这个。 */
+export declare function buildSelfDescription(syncEnabled: boolean): string;

package/dist/self.js

@@ -24,23 +24,33 @@ export const SELF_VERSION = (() => {
         return 'unknown';
     }
 })();
-export const SELF_DESCRIPTION = `[记忆系统自述] 本环境内置跨会话记忆服务（dsh-memory v${SELF_VERSION}）。`
-    + '你有 16 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget / memory_move / memory_sweep（`memory_confirm` 仅在用户明确要求放行隔离记录时用；`memory_move` 把放错了层的记忆移到 global、当前工作区或相对祖先；`memory_sweep` 是只读体检——失效清单、久未命中、候选与预算占用，不修改任何状态）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）；'
-    + '**同步工具** memory_sync / memory_conflicts：跨环境同步；`memory_sync` 的 `status` 只看状态、`pull` 拉取并导入、`push` 镜像并推送，`memory_conflicts` 列出**未被自动裁决**的冲突，同步**不会**自动决定哪一边对——两边都改过同一条时两个版本都留着等人处理，记忆被静默覆盖就没了；'
-    + '**日记工具** diary_read / diary_write：日记是 md 文件，落在 `<DSH_HOME>/diary`，与记忆**分开存、不进检索、不占注入预算**。记的是经历——发生了什么（有细节）、我怎么想（可以有情绪、可以没结论）、关于他（他说了什么、我注意到了什么）；不是任务清单（那是 git log），也不是结论（那是 memory_save）。读它不吃预算，需要时整篇读。'
-    + '记忆分两层：`global` 跨项目（偏好 / 习惯 / 环境知识），`project` 跟随工作区（落在 `<cwd>/.dsh/storages/`，随 git 提交分享）。'
-    + '**何时写入**（不必刻意找机会，遇到下面这些就动手）：'
-    + '① 用户表达长期偏好或约定（「以后都…」「记住…」「我们的规矩是…」）；'
-    + '② 用户纠正了你的做法或理解——把正确结论记下来；'
-    + '③ 得出跨会话仍然有用的结论、路径或坑，而非本次任务的临时细节。'
-    + '**不要记**：临时状态、未经验证的推测、能从代码或文档直接读到的事实（那类记「去哪查」即可）。'
-    + '**怎么写**：一条一件事，并给多角度关键词（同义词、缩写、中英），否则将来检索不到它。'
-    + '**锚点（可选）**：若这条记忆描述的是「随某个环境值变化的事实」（某工具版本下的行为、某环境变量决定的配置），用 anchor 参数把它绑到那个值上——值变了它会自动失效并标 stale，不会再被当成仍然正确；绑错了用 memory_update 改（当场重新判定，成立即复活），不要了就传 `anchor: null` 清除。当前锚点随记录一起返回。'
-    + '写入即生效（`approved`），人工只在例外时介入；命中密钥/凭据规则的写入会被隔离（不进注入与检索）。'
-    + '**常驻注入**：每轮注入「global + 当前会话工作区」里 approved 且开着常驻开关的记忆单行摘要（形如 `- [memory:id:namespace] 摘要`）；全文要靠 memory_search 取。'
-    + '常驻开关由人（或模型显式传 `injected`）决定：**自动改变注入状态的规则已全部停用**——命中次数不再自动升常驻（它只喂体检报告的候选提示），30 天未命中的自动撤下也已改为**只计量不生效**（撤下来就基本不会自己回去，那种动作不该由一个没有分布依据的阈值决定）。**给 memory_save / memory_update 传 `injected` 即显式接管**。'
-    + '**钉的判据是「失效可察觉性」**：这条记忆若没被想起来，你会不会根本意识不到自己漏了它？会 → 钉常驻（规则 / 委托 / 判据）；不会 → 留检索（事实 / 参考 / 案例）。'
-    + '**注入有预算**（默认 1500 字符，约装 11 条），装不下的整条丢弃、按**最近更新**优先取舍（不是最近被检索——检索是「需要时才用」的行为，拿它决定「谁每轮在场」会让查得多的挤掉钉得牢的）——所以「钉了常驻」只等于「有资格排队」。'
-    + '装不下时注入末尾会出现一行 `（另有 N 条常驻因预算未注入：…短摘要…）`——**那是「有常驻记忆并不在场」的唯一信号**，看到它就该逐条评估撤下。'
-    + '发现某条记忆与实际不符时用 memory_update 修正（保持生效）；确认没用的用 memory_forget。'
-    + '（English: dsh-memory provides cross-session memory. Writes take effect immediately; save durable preferences, corrections and reusable conclusions — not transient state, guesses, or facts readable from the repo (record where to look instead). Always add multi-angle keywords. Pass `injected: true` to keep one resident every turn — reserve that for rules and standing agreements; facts stay search-only. Resident injection runs on a budget, so a pinned memory is only queued, never guaranteed to be in context.)';
+function buildDescription(syncEnabled) {
+    return (`[记忆系统自述] 本环境内置跨会话记忆服务（dsh-memory v${SELF_VERSION}）。`
+        + '你有 ' + (syncEnabled ? 16 : 14) + ' 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget / memory_move / memory_sweep（`memory_confirm` 仅在用户明确要求放行隔离记录时用；`memory_move` 把放错了层的记忆移到 global、当前工作区或相对祖先；`memory_sweep` 是只读体检——失效清单、久未命中、候选与预算占用，不修改任何状态）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）；'
+        + (syncEnabled
+            ? '**同步工具** memory_sync / memory_conflicts：跨环境同步；`memory_sync` 的 `status` 只看状态、`pull` 拉取并导入、`push` 镜像并推送，`memory_conflicts` 列出**未被自动裁决**的冲突，同步**不会**自动决定哪一边对——两边都改过同一条时两个版本都留着等人处理，记忆被静默覆盖就没了；'
+            : '')
+        + '**日记工具** diary_read / diary_write：日记是 md 文件，落在 `<DSH_HOME>/diary`，与记忆**分开存、不进检索、不占注入预算**。记的是经历——发生了什么（有细节）、我怎么想（可以有情绪、可以没结论）、关于他（他说了什么、我注意到了什么）；不是任务清单（那是 git log），也不是结论（那是 memory_save）。读它不吃预算，需要时整篇读。'
+        + '记忆分两层：`global` 跨项目（偏好 / 习惯 / 环境知识），`project` 跟随工作区（落在 `<cwd>/.dsh/storages/`，随 git 提交分享）。'
+        + '**何时写入**（不必刻意找机会，遇到下面这些就动手）：'
+        + '① 用户表达长期偏好或约定（「以后都…」「记住…」「我们的规矩是…」）；'
+        + '② 用户纠正了你的做法或理解——把正确结论记下来；'
+        + '③ 得出跨会话仍然有用的结论、路径或坑，而非本次任务的临时细节。'
+        + '**不要记**：临时状态、未经验证的推测、能从代码或文档直接读到的事实（那类记「去哪查」即可）。'
+        + '**怎么写**：一条一件事，并给多角度关键词（同义词、缩写、中英），否则将来检索不到它。'
+        + '**锚点（可选）**：若这条记忆描述的是「随某个环境值变化的事实」（某工具版本下的行为、某环境变量决定的配置），用 anchor 参数把它绑到那个值上——值变了它会自动失效并标 stale，不会再被当成仍然正确；绑错了用 memory_update 改（当场重新判定，成立即复活），不要了就传 `anchor: null` 清除。当前锚点随记录一起返回。'
+        + '写入即生效（`approved`），人工只在例外时介入；命中密钥/凭据规则的写入会被隔离（不进注入与检索）。'
+        + '**常驻注入**：每轮注入「global + 当前会话工作区」里 approved 且开着常驻开关的记忆单行摘要（形如 `- [memory:id:namespace] 摘要`）；全文要靠 memory_search 取。'
+        + '常驻开关由人（或模型显式传 `injected`）决定：**自动改变注入状态的规则已全部停用**——命中次数不再自动升常驻（它只喂体检报告的候选提示），30 天未命中的自动撤下也已改为**只计量不生效**（撤下来就基本不会自己回去，那种动作不该由一个没有分布依据的阈值决定）。**给 memory_save / memory_update 传 `injected` 即显式接管**。'
+        + '**钉的判据是「失效可察觉性」**：这条记忆若没被想起来，你会不会根本意识不到自己漏了它？会 → 钉常驻（规则 / 委托 / 判据）；不会 → 留检索（事实 / 参考 / 案例）。'
+        + '**注入有预算**（默认 1500 字符，约装 11 条），装不下的整条丢弃、按**最近更新**优先取舍（不是最近被检索——检索是「需要时才用」的行为，拿它决定「谁每轮在场」会让查得多的挤掉钉得牢的）——所以「钉了常驻」只等于「有资格排队」。'
+        + '装不下时注入末尾会出现一行 `（另有 N 条常驻因预算未注入：…短摘要…）`——**那是「有常驻记忆并不在场」的唯一信号**，看到它就该逐条评估撤下。'
+        + '发现某条记忆与实际不符时用 memory_update 修正（保持生效）；确认没用的用 memory_forget。'
+        + '（English: dsh-memory provides cross-session memory. Writes take effect immediately; save durable preferences, corrections and reusable conclusions — not transient state, guesses, or facts readable from the repo (record where to look instead). Always add multi-angle keywords. Pass `injected: true` to keep one resident every turn — reserve that for rules and standing agreements; facts stay search-only. Resident injection runs on a budget, so a pinned memory is only queued, never guaranteed to be in context.)');
+}
+/** 能力全貌（面板 / 远端视图用；同步未启用时也展示它的存在）。 */
+export const SELF_DESCRIPTION = buildDescription(true);
+/** 按当前是否启用同步生成自述——系统提示那一路用这个。 */
+export function buildSelfDescription(syncEnabled) {
+    return buildDescription(syncEnabled);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.22.0",
+  "version": "0.22.2",
   "description": "Cross-session plaintext memory plugin for the DeepSeek Harness — deterministic BM25 recall, writes take effect immediately, signal-driven injection, no embeddings",
   "license": "MIT",
   "publishConfig": {