@geminilight/mindos 0.6.38 → 0.6.39

package/app/components/settings/UpdateTab.tsx

@@ -12,7 +12,19 @@ interface MindosDesktopBridge {
   onUpdateProgress?: (cb: (progress: { percent: number }) => void) => () => void;
   onUpdateReady?: (cb: () => void) => () => void;
   onUpdateError?: (cb: (info: { message?: string }) => void) => () => void;
-  getAppInfo?: () => Promise<{ version?: string }>;
+  getAppInfo?: () => Promise<{ version?: string; mode?: string }>;
+  // Core Hot Update
+  checkCoreUpdate?: () => Promise<{
+    available: boolean; currentVersion: string; latestVersion: string;
+    urls: string[]; size: number; sha256: string;
+    minDesktopVersion: string; desktopTooOld: boolean;
+  }>;
+  downloadCoreUpdate?: (urls: string[], version: string, size: number, sha256: string) => Promise<void>;
+  cancelCoreDownload?: () => Promise<void>;
+  applyCoreUpdate?: () => Promise<{ ok: boolean; version?: string }>;
+  getCoreUpdatePending?: () => Promise<{ version: string | null }>;
+  onCoreUpdateProgress?: (cb: (progress: { percent: number; transferred: number; total: number }) => void) => () => void;
+  onCoreUpdateAvailable?: (cb: (info: { current: string; latest: string; ready?: boolean }) => void) => () => void;
 }
 
 function getDesktopBridge(): MindosDesktopBridge | null {
@@ -67,8 +79,262 @@ function StageIcon({ status }: { status: string }) {
   }
 }
 
-/** Desktop (Electron) update: uses electron-updater via preload IPC bridge */
-function DesktopUpdateTab() {
+/** Format bytes to human-readable */
+function formatSize(bytes: number): string {
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** Desktop Core update card — downloads runtime packages, restarts services only */
+function DesktopCoreCard() {
+  const { t } = useLocale();
+  const u = t.settings.update;
+  const bridge = getDesktopBridge()!;
+
+  type CoreState = 'idle' | 'checking' | 'available' | 'downloading' | 'cancelling' | 'ready' | 'applying' | 'error' | 'desktopTooOld';
+  const [state, setState] = useState<CoreState>('idle');
+  const [currentVersion, setCurrentVersion] = useState('');
+  const [latestVersion, setLatestVersion] = useState('');
+  const [updateInfo, setUpdateInfo] = useState<{
+    urls: string[]; size: number; sha256: string;
+  } | null>(null);
+  const [progress, setProgress] = useState(0);
+  const [errorMsg, setErrorMsg] = useState('');
+  const [minDesktopVersion, setMinDesktopVersion] = useState('');
+
+  useEffect(() => {
+    // Always fetch current version first
+    const init = async () => {
+      // Get current Core version via a check call (also probes for updates)
+      try {
+        const info = await bridge.checkCoreUpdate?.();
+        if (info) setCurrentVersion(info.currentVersion);
+      } catch { /* ignore */ }
+
+      // Check for pending download (from previous session)
+      try {
+        const r = await bridge.getCoreUpdatePending?.();
+        if (r?.version) {
+          setLatestVersion(r.version);
+          setState('ready');
+          return;
+        }
+      } catch { /* ignore */ }
+
+      // Otherwise do a full remote check
+      handleCheck();
+    };
+    init();
+
+    const cleanups: Array<() => void> = [];
+    if (bridge.onCoreUpdateProgress) {
+      cleanups.push(bridge.onCoreUpdateProgress((p) => setProgress(Math.round(p.percent))));
+    }
+    if (bridge.onCoreUpdateAvailable) {
+      cleanups.push(bridge.onCoreUpdateAvailable((info) => {
+        setCurrentVersion(info.current);
+        setLatestVersion(info.latest);
+        setState(info.ready ? 'ready' : 'available');
+      }));
+    }
+    return () => cleanups.forEach((fn) => fn());
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const handleCheck = async () => {
+    if (!bridge.checkCoreUpdate) return;
+    setState('checking');
+    setErrorMsg('');
+    try {
+      const info = await bridge.checkCoreUpdate();
+      setCurrentVersion(info.currentVersion);
+      if (info.desktopTooOld) {
+        setLatestVersion(info.latestVersion);
+        setMinDesktopVersion(info.minDesktopVersion);
+        setState('desktopTooOld');
+      } else if (info.available) {
+        setLatestVersion(info.latestVersion);
+        setUpdateInfo({ urls: info.urls, size: info.size, sha256: info.sha256 });
+        setState('available');
+      } else {
+        setState('idle');
+      }
+    } catch {
+      setState('idle'); // Silent — can't reach CDN, not an error
+    }
+  };
+
+  const handleDownload = async () => {
+    if (!bridge.downloadCoreUpdate || !updateInfo) return;
+    setState('downloading');
+    setProgress(0);
+    try {
+      await bridge.downloadCoreUpdate(updateInfo.urls, latestVersion, updateInfo.size, updateInfo.sha256);
+      setState('ready');
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('aborted')) {
+        // User cancelled — go back to available
+        setState('available');
+      } else {
+        setState('error');
+        setErrorMsg(msg || 'Download failed');
+      }
+    }
+  };
+
+  const handleCancel = () => {
+    bridge.cancelCoreDownload?.();
+    // Don't immediately go to 'available' — the download IPC will reject with 'aborted',
+    // and the catch in handleDownload will set state to 'error'. We set 'cancelling' to
+    // block re-entry, and handleDownload's catch will detect the abort and go to 'available'.
+    setState('cancelling');
+  };
+
+  const handleApply = async () => {
+    if (!bridge.applyCoreUpdate) return;
+    setState('applying');
+    try {
+      const result = await bridge.applyCoreUpdate();
+      if (result?.version) setCurrentVersion(result.version);
+      setState('idle');
+      // Page will be reloaded by main process
+    } catch (err) {
+      setState('error');
+      setErrorMsg(err instanceof Error ? err.message : 'Apply failed');
+    }
+  };
+
+  // Don't show if no Core update bridge available
+  if (!bridge.checkCoreUpdate) return null;
+
+  return (
+    <div className="rounded-xl border border-border bg-card p-4 space-y-3">
+      <div className="flex items-center justify-between">
+        <span className="text-sm font-medium text-foreground">{u?.coreTitle ?? 'MindOS Core'}</span>
+        {currentVersion && <span className="text-xs font-mono text-muted-foreground">v{currentVersion}</span>}
+      </div>
+
+      {state === 'checking' && (
+        <div className="flex items-center gap-2 text-xs text-muted-foreground">
+          <Loader2 size={13} className="animate-spin" />
+          {u?.checking ?? 'Checking for updates...'}
+        </div>
+      )}
+
+      {state === 'idle' && (
+        <div className="flex items-center gap-2 text-xs text-success">
+          <CheckCircle2 size={13} />
+          {u?.coreUpToDate ?? 'Core is up to date'}
+        </div>
+      )}
+
+      {state === 'available' && (
+        <div className="flex items-center gap-2 text-xs text-[var(--amber-text)]">
+          <Download size={13} />
+          v{latestVersion} {u?.coreAvailable ? u.coreAvailable(formatSize(updateInfo?.size ?? 0)) : `available (${formatSize(updateInfo?.size ?? 0)})`}
+        </div>
+      )}
+
+      {(state === 'downloading' || state === 'cancelling') && (
+        <div className="space-y-2">
+          <div className="flex items-center justify-between text-xs">
+            <div className="flex items-center gap-2 text-foreground">
+              <Loader2 size={13} className="animate-spin text-[var(--amber)]" />
+              {state === 'cancelling'
+                ? (u?.coreCancel ?? 'Cancelling...')
+                : <>{ u?.coreDownloading ?? 'Downloading...'} v{latestVersion}</>}
+            </div>
+            {state === 'downloading' && (
+              <button onClick={handleCancel} className="text-muted-foreground hover:text-foreground transition-colors">
+                {u?.coreCancel ?? 'Cancel'}
+              </button>
+            )}
+          </div>
+          <div className="h-1 rounded-full bg-muted overflow-hidden">
+            <div className="h-full rounded-full bg-[var(--amber)] transition-all duration-300"
+              style={{ width: `${Math.max(progress, 3)}%` }} />
+          </div>
+        </div>
+      )}
+
+      {state === 'ready' && (
+        <div className="flex items-center gap-2 text-xs text-success">
+          <CheckCircle2 size={13} />
+          v{latestVersion} {u?.coreReady ?? 'ready — restart services to apply'}
+        </div>
+      )}
+
+      {state === 'applying' && (
+        <div className="flex items-center gap-2 text-xs text-muted-foreground">
+          <Loader2 size={13} className="animate-spin text-[var(--amber)]" />
+          {u?.coreApplying ?? 'Applying update...'}
+        </div>
+      )}
+
+      {state === 'desktopTooOld' && (
+        <div className="space-y-1">
+          <div className="flex items-center gap-2 text-xs text-[var(--amber-text)]">
+            <AlertCircle size={13} />
+            {u?.coreDesktopTooOld ? u.coreDesktopTooOld(latestVersion) : `v${latestVersion} requires a newer Desktop.`}
+          </div>
+          <p className="text-2xs text-muted-foreground">
+            {u?.coreDesktopTooOldHint ?? 'Please update MindOS Desktop first.'} (Desktop ≥ v{minDesktopVersion})
+          </p>
+        </div>
+      )}
+
+      {state === 'error' && (
+        <div className="flex items-center gap-2 text-xs text-destructive">
+          <AlertCircle size={13} />
+          {errorMsg || (u?.coreError ?? 'Core update failed.')}
+        </div>
+      )}
+
+      {/* Actions */}
+      <div className="flex items-center gap-2 pt-1">
+        {(state === 'idle' || state === 'error') && (
+          <button onClick={handleCheck} disabled={state !== 'idle' && state !== 'error'}
+            className="flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg border border-border text-muted-foreground hover:text-foreground hover:bg-muted disabled:opacity-40 disabled:cursor-not-allowed transition-colors">
+            <RefreshCw size={14} />
+            {u?.checkButton ?? 'Check for Updates'}
+          </button>
+        )}
+
+        {state === 'available' && (
+          <button onClick={handleDownload}
+            className="flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg font-medium text-[var(--amber-foreground)] bg-[var(--amber)] transition-colors">
+            <Download size={14} />
+            {u?.updateButton ? u.updateButton(latestVersion) : `Update to v${latestVersion}`}
+          </button>
+        )}
+
+        {state === 'ready' && (
+          <button onClick={handleApply}
+            className="flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg font-medium text-[var(--amber-foreground)] bg-[var(--amber)] transition-colors">
+            <RefreshCw size={14} />
+            {u?.coreRestartServices ?? 'Restart Services'}
+          </button>
+        )}
+
+        {state === 'error' && (
+          <button onClick={updateInfo ? handleDownload : handleCheck}
+            className="flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg border border-border text-muted-foreground hover:text-foreground hover:bg-muted transition-colors">
+            <RefreshCw size={14} />
+            {u?.coreRetry ?? 'Retry'}
+          </button>
+        )}
+      </div>
+
+      <p className="text-2xs text-muted-foreground/60">
+        {u?.coreHint ?? 'Core updates only restart services — no app restart needed.'}
+      </p>
+    </div>
+  );
+}
+
+/** Desktop shell update card — uses electron-updater (requires app restart) */
+function DesktopShellCard() {
   const { t } = useLocale();
   const u = t.settings.update;
   const bridge = getDesktopBridge()!;
@@ -135,119 +401,101 @@ function DesktopUpdateTab() {
   };
 
   return (
-    <div className="space-y-6">
-      <div className="rounded-xl border border-border bg-card p-4 space-y-3">
-        <div className="flex items-center justify-between">
-          <div className="flex items-center gap-2">
-            <Monitor size={14} className="text-muted-foreground" />
-            <span className="text-sm font-medium text-foreground">MindOS Desktop</span>
-          </div>
-          {appVersion && <span className="text-xs font-mono text-muted-foreground">v{appVersion}</span>}
+    <div className="rounded-xl border border-border bg-card p-4 space-y-3">
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <Monitor size={14} className="text-muted-foreground" />
+          <span className="text-sm font-medium text-foreground">{u?.shellTitle ?? 'MindOS Desktop'}</span>
         </div>
+        {appVersion && <span className="text-xs font-mono text-muted-foreground">v{appVersion}</span>}
+      </div>
 
-        {state === 'checking' && (
-          <div className="flex items-center gap-2 text-xs text-muted-foreground">
-            <Loader2 size={13} className="animate-spin" />
-            {u?.checking ?? 'Checking for updates...'}
-          </div>
-        )}
-
-        {state === 'idle' && !available && (
-          <div className="flex items-center gap-2 text-xs text-success">
-            <CheckCircle2 size={13} />
-            {u?.upToDate ?? "You're up to date"}
-          </div>
-        )}
+      {state === 'checking' && (
+        <div className="flex items-center gap-2 text-xs text-muted-foreground">
+          <Loader2 size={13} className="animate-spin" />
+          {u?.checking ?? 'Checking for updates...'}
+        </div>
+      )}
 
-        {state === 'idle' && available && (
-          <div className="flex items-center gap-2 text-xs text-[var(--amber-text)]">
-            <Download size={13} />
-            {version ? `Update available: v${version}` : 'Update available'}
-          </div>
-        )}
+      {state === 'idle' && !available && (
+        <div className="flex items-center gap-2 text-xs text-success">
+          <CheckCircle2 size={13} />
+          {u?.upToDate ?? "You're up to date"}
+        </div>
+      )}
 
-        {state === 'downloading' && (
-          <div className="space-y-2">
-            <div className="flex items-center gap-2 text-xs text-foreground">
-              <Loader2 size={13} className="animate-spin text-[var(--amber)]" />
-              {u?.desktopDownloading ?? 'Downloading update...'}
-            </div>
-            <div className="h-1 rounded-full bg-muted overflow-hidden">
-              <div
-                className="h-full rounded-full bg-[var(--amber)] transition-all duration-300"
-                style={{ width: `${Math.max(progress, 3)}%` }}
-              />
-            </div>
-          </div>
-        )}
+      {state === 'idle' && available && (
+        <div className="flex items-center gap-2 text-xs text-[var(--amber-text)]">
+          <Download size={13} />
+          {version ? `Update available: v${version}` : 'Update available'}
+        </div>
+      )}
 
-        {state === 'ready' && (
-          <div className="flex items-center gap-2 text-xs text-success">
-            <CheckCircle2 size={13} />
-            {u?.desktopReady ?? 'Update downloaded. Restart to apply.'}
+      {state === 'downloading' && (
+        <div className="space-y-2">
+          <div className="flex items-center gap-2 text-xs text-foreground">
+            <Loader2 size={13} className="animate-spin text-[var(--amber)]" />
+            {u?.desktopDownloading ?? 'Downloading update...'}
           </div>
-        )}
-
-        {state === 'error' && (
-          <div className="flex items-center gap-2 text-xs text-destructive">
-            <AlertCircle size={13} />
-            {errorMsg}
+          <div className="h-1 rounded-full bg-muted overflow-hidden">
+            <div className="h-full rounded-full bg-[var(--amber)] transition-all duration-300"
+              style={{ width: `${Math.max(progress, 3)}%` }} />
           </div>
-        )}
-        {/* Actions */}
-        <div className="flex items-center gap-2 pt-1">
-          <button
-            onClick={handleCheck}
-            disabled={state === 'checking' || state === 'downloading'}
-            className="flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg border border-border text-muted-foreground hover:text-foreground hover:bg-muted disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
-          >
-            <RefreshCw size={14} className={state === 'checking' ? 'animate-spin' : ''} />
-            {u?.checkButton ?? 'Check for Updates'}
-          </button>
-
-          {state === 'idle' && available && (
-            <button
-              onClick={handleInstall}
-              className="flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg font-medium text-[var(--amber-foreground)] bg-[var(--amber)] transition-colors"
-            >
-              <Download size={14} />
-              {version ? `Update to v${version}` : 'Update'}
-            </button>
-          )}
+        </div>
+      )}
 
-          {state === 'ready' && (
-            <button
-              onClick={async () => {
-                try {
-                  await bridge.installUpdate();
-                } catch {
-                  setState('error');
-                  setErrorMsg(u?.error ?? 'Failed to install update. Please try again.');
-                }
-              }}
-              className="flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg font-medium text-[var(--amber-foreground)] bg-[var(--amber)] transition-colors"
-            >
-              <RefreshCw size={14} />
-              {u?.desktopRestart ?? 'Restart Now'}
-            </button>
-          )}
+      {state === 'ready' && (
+        <div className="flex items-center gap-2 text-xs text-success">
+          <CheckCircle2 size={13} />
+          {u?.desktopReady ?? 'Update downloaded. Restart to apply.'}
         </div>
+      )}
 
-        {/* Info */}
-        <div className="border-t border-border/50 pt-3 space-y-2">
-          <a
-            href={CHANGELOG_URL}
-            target="_blank"
-            rel="noopener noreferrer"
-            className="flex items-center gap-1.5 text-sm text-muted-foreground hover:text-foreground transition-colors"
-          >
-            <ExternalLink size={12} />
-            {u?.releaseNotes ?? 'View release notes'}
-          </a>
-          <p className="text-2xs text-muted-foreground/60">
-            {u?.desktopHint ?? 'Updates are delivered through the Desktop app auto-updater.'}
-          </p>
+      {state === 'error' && (
+        <div className="flex items-center gap-2 text-xs text-destructive">
+          <AlertCircle size={13} />
+          {errorMsg}
         </div>
+      )}
+
+      {/* Actions */}
+      <div className="flex items-center gap-2 pt-1">
+        <button onClick={handleCheck} disabled={state === 'checking' || state === 'downloading'}
+          className="flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg border border-border text-muted-foreground hover:text-foreground hover:bg-muted disabled:opacity-40 disabled:cursor-not-allowed transition-colors">
+          <RefreshCw size={14} className={state === 'checking' ? 'animate-spin' : ''} />
+          {u?.checkButton ?? 'Check for Updates'}
+        </button>
+
+        {state === 'idle' && available && (
+          <button onClick={handleInstall}
+            className="flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg font-medium text-[var(--amber-foreground)] bg-[var(--amber)] transition-colors">
+            <Download size={14} />
+            {version ? `Update to v${version}` : 'Update'}
+          </button>
+        )}
+
+        {state === 'ready' && (
+          <button onClick={async () => {
+              try { await bridge.installUpdate(); }
+              catch { setState('error'); setErrorMsg(u?.error ?? 'Failed to install update.'); }
+            }}
+            className="flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-lg font-medium text-[var(--amber-foreground)] bg-[var(--amber)] transition-colors">
+            <RefreshCw size={14} />
+            {u?.desktopRestart ?? 'Restart Now'}
+          </button>
+        )}
+      </div>
+
+      {/* Info */}
+      <div className="border-t border-border/50 pt-3 space-y-2">
+        <a href={CHANGELOG_URL} target="_blank" rel="noopener noreferrer"
+          className="flex items-center gap-1.5 text-sm text-muted-foreground hover:text-foreground transition-colors">
+          <ExternalLink size={12} />
+          {u?.releaseNotes ?? 'View release notes'}
+        </a>
+        <p className="text-2xs text-muted-foreground/60">
+          {u?.desktopHint ?? 'Updates are delivered through the Desktop app auto-updater.'}
+        </p>
       </div>
     </div>
   );
@@ -256,8 +504,24 @@ function DesktopUpdateTab() {
 /** Router: Desktop uses electron-updater IPC; browser/CLI uses npm API */
 export function UpdateTab() {
   const [isDesktop, setIsDesktop] = useState(false);
-  useEffect(() => { setIsDesktop(!!getDesktopBridge()); }, []);
-  if (isDesktop) return <DesktopUpdateTab />;
+  const [isLocal, setIsLocal] = useState(true);
+  useEffect(() => {
+    const bridge = getDesktopBridge();
+    setIsDesktop(!!bridge);
+    if (bridge?.getAppInfo) {
+      bridge.getAppInfo().then((info) => {
+        if (info && 'mode' in info) setIsLocal((info as { mode?: string }).mode !== 'remote');
+      }).catch(() => {});
+    }
+  }, []);
+  if (isDesktop) {
+    return (
+      <div className="space-y-6">
+        {isLocal && <DesktopCoreCard />}
+        <DesktopShellCard />
+      </div>
+    );
+  }
   return <BrowserUpdateTab />;
 }
 

package/app/data/skills/mindos/SKILL.md

@@ -7,11 +7,15 @@ description: >
   Use when the task targets files inside the user's MindOS KB (mindRoot).
   NOT for editing app source, project docs, or paths outside the KB.
   Core concepts: Space, Instruction (INSTRUCTION.md), Skill (SKILL.md); notes can embody both.
+  Trigger when user asks to: save or record a note, search their knowledge base, update or edit
+  a file, organize notes, run a workflow or SOP, capture decisions from a session, append rows
+  to a table or CSV, hand off context to another agent — or says "帮我记下来" / "搜一下我的笔记" /
+  "更新知识库" / "整理文件" / "执行工作流".
 ---
 
 # MindOS Skill
 
-<!-- version: 1.3.1 -->
+<!-- version: 1.3.2 -->
 
 **Before every task, internalize these 5 rules:**
 
@@ -83,8 +87,7 @@ User request
       └─ ASK for clarification. Propose 2-3 specific options based on KB state. Do NOT start editing.
 ```
 
-**For any write/SOP/structural path above → read [references/write-supplement.md](./references/write-supplement.md) first.**
-It covers: startup protocol, write tool selection, and step-by-step execution details for each path.
+**For any write/SOP/structural path above → the write supplement is already loaded in context (see `## Write & Workflow Supplement` section below or in the next context block).**
 
 ---
 
@@ -97,7 +100,7 @@ It covers: startup protocol, write tool selection, and step-by-step execution de
 | Find files | `mindos_search_notes` (2-4 parallel keyword variants) | Single-keyword search |
 | Read content | `mindos_read_file` or `mindos_read_lines` (for large files) | Reading entire large file when you need 10 lines |
 
-Write, structural, and history tools → [references/write-supplement.md](./references/write-supplement.md).
+Write, structural, and history tools → see Write & Workflow Supplement (loaded below or in next context block).
 
 ### Fallbacks
 
@@ -112,15 +115,27 @@ Write, structural, and history tools → [references/write-supplement.md](./refe
 |---------|------|-----------|
 | **Read-only Q&A** | Lookup / summarize / quote | Tree reasoning → search → read → answer with citations → state gaps |
 
-For write, SOP, structural, and handoff patterns → [references/write-supplement.md](./references/write-supplement.md).
+For write, SOP, structural, and handoff patterns → see Write & Workflow Supplement (loaded below or in next context block).
 
 ---
 
-## Interaction rules
+## Judgment heuristics
 
-- **Ambiguous request?** Ask first. Propose 2-3 options based on KB state (recent changes, directory structure). Never start reorganizing without understanding scope.
-- **Cite sources.** Every fact from the KB gets a file path so the user can verify.
-- **Brevity first.** Show the most likely match, not an exhaustive list.
+**Save intent — read vs. write boundary**
+- "帮我记下来" / "记录一下" / "保存这个" = write
+- "搜一下有没有关于 X 的笔记" / "总结上周的工作" = read-only
+- Ambiguous boundary ("整理一下这些内容") → ask first: display only, or write back to KB?
+
+**File location uncertainty**
+- 扫目录树 5 秒内定不下来 → don't invent a new directory; use the nearest semantically-fit existing one and inform the user
+- User says "just put it somewhere" → place in inbox or top-level general directory, propose classification after (triggers Structure classification hook)
+
+**Scope creep signals**
+- Single input routes to >5 files → pause, confirm scope; users rarely intend bulk rewrites
+- "Update all of these" + content spans multiple topics → split into batches, confirm each, don't execute all at once
+
+**Citation discipline**
+- KB-cited facts must include the file path so the user can verify
 
 ---
 

package/app/data/skills/mindos-zh/SKILL.md

@@ -6,11 +6,15 @@ description: >
   update notes, search knowledge base, organize, SOP, retrospective, CSV, handoff, route notes, distill experience.
   仅 mindRoot 知识库内任务。不用于：改代码仓库/项目文档/KB 外路径。
   核心概念：空间、指令(INSTRUCTION.md)、技能(SKILL.md)；笔记可承载指令与技能。
+  当用户说"帮我记下来"、"搜一下我的笔记"、"更新知识库"、"整理文件"、"执行工作流"、
+  "记录这次会议的决策"、"追加到表格"、"交接给下一个 Agent" 时触发。
+  也适用于：save/record a note, search KB, update/edit files, run SOP, capture decisions,
+  append CSV rows, cross-agent handoff — 所有 mindRoot 知识库内的读写操作。
 ---
 
 # MindOS Skill
 
-<!-- version: 1.3.1 -->
+<!-- version: 1.3.2 -->
 
 **每次任务前，内化这 5 条规则：**
 
@@ -82,8 +86,7 @@ description: >
       └─ 先问清楚。基于 KB 状态提出 2-3 个具体选项。不要开始编辑。
 ```
 
-**以上任何写入 / SOP / 结构路径 → 先读 [references/write-supplement.md](./references/write-supplement.md)。**
-包含：启动协议、写工具选型、各路径详细执行步骤。
+**以上任何写入 / SOP / 结构路径 → 写入补充已加载到上下文（见下方或下一个上下文块中的 `## 写入与工作流补充` 章节）。**
 
 ---
 
@@ -96,7 +99,7 @@ description: >
 | 找文件 | `mindos_search_notes`（2-4 条并行关键词变体）| 单关键词搜索 |
 | 读内容 | `mindos_read_file` 或 `mindos_read_lines`（大文件） | 只需 10 行却读整文件 |
 
-写入、结构变更、历史工具 → [references/write-supplement.md](./references/write-supplement.md)。
+写入、结构变更、历史工具 → 见写入与工作流补充（已加载到下方或下一个上下文块）。
 
 ### 回退
 
@@ -111,15 +114,27 @@ description: >
 |------|----------|----------|
 | **只读问答** | 查找 / 总结 / 引用 | 目录树推断 → 搜索 → 读取 → 标注来源 → 明确说信息缺口 |
 
-写入模式详细执行步骤 → [references/write-supplement.md](./references/write-supplement.md)。
+写入模式详细执行步骤 → 见写入与工作流补充（已加载到下方或下一个上下文块）。
 
 ---
 
-## 交互规则
+## 判断启发式规则
 
-- **模糊请求？** 先问。基于 KB 现状提出 2-3 个选项。不要在没理解范围前开始编辑。
-- **标注来源。** KB 中的事实附带文件路径，便于验证。
-- **简洁优先。** 展示最可能的匹配，不列全部。
+**保存意图 — 读写边界识别**
+- "帮我记下来" / "记录一下" / "保存这个" = 写入
+- "搜一下有没有关于 X 的笔记" / "总结上周的工作" = 只读
+- 模糊边界（"整理一下这些内容"）→ 先问：是读取展示，还是写回 KB？
+
+**文件位置不确定时**
+- 扫目录树 5 秒内定不下来 → 不要自创新目录；放语义最近的已有目录，告知用户
+- 用户说"随便放个地方" → 放 inbox 或最顶层通用目录，任务后提议归类（触发 Structure classification hook）
+
+**范围蔓延信号**
+- 单条输入导致路由表 > 5 个文件 → 暂停，先确认范围；用户鲜少意图批量重写
+- "把这些都更新一下" + 内容跨越多个主题 → 拆成批次确认，不一次性执行
+
+**引用纪律**
+- KB 中引用的事实必须附带文件路径，便于用户核查
 
 ---