@geminilight/mindos 0.5.56 → 0.5.57

package/app/components/ask/AskContent.tsx

@@ -13,6 +13,33 @@ import SessionHistory from '@/components/ask/SessionHistory';
 import FileChip from '@/components/ask/FileChip';
 import { consumeUIMessageStream } from '@/lib/agent/stream-consumer';
 import { cn } from '@/lib/utils';
+import { useComposerVerticalResize } from '@/hooks/useComposerVerticalResize';
+
+const PANEL_COMPOSER_STORAGE = 'mindos-agent-panel-composer-height';
+const PANEL_COMPOSER_DEFAULT = 104;
+const PANEL_COMPOSER_MIN = 84;
+const PANEL_COMPOSER_MAX_ABS = 440;
+const PANEL_COMPOSER_MAX_VIEW = 0.48;
+const PANEL_COMPOSER_KEY_STEP = 24;
+
+function panelComposerMaxForViewport(): number {
+  if (typeof window === 'undefined') return PANEL_COMPOSER_MAX_ABS;
+  return Math.min(PANEL_COMPOSER_MAX_ABS, Math.floor(window.innerHeight * PANEL_COMPOSER_MAX_VIEW));
+}
+
+function readStoredPanelComposerHeight(): number {
+  if (typeof window === 'undefined') return PANEL_COMPOSER_DEFAULT;
+  try {
+    const s = localStorage.getItem(PANEL_COMPOSER_STORAGE);
+    if (s) {
+      const n = parseInt(s, 10);
+      if (Number.isFinite(n) && n >= PANEL_COMPOSER_MIN && n <= PANEL_COMPOSER_MAX_ABS) return n;
+    }
+  } catch {
+    /* ignore */
+  }
+  return PANEL_COMPOSER_DEFAULT;
+}
 
 interface AskContentProps {
   /** Controls visibility — 'open' for modal, 'active' for panel */
@@ -33,11 +60,79 @@ interface AskContentProps {
 }
 
 export default function AskContent({ visible, currentFile, initialMessage, onFirstMessage, variant, onClose, maximized, onMaximize, askMode, onModeSwitch }: AskContentProps) {
-  const inputRef = useRef<HTMLInputElement>(null);
+  const isPanel = variant === 'panel';
+
+  const inputRef = useRef<HTMLInputElement | HTMLTextAreaElement>(null);
   const abortRef = useRef<AbortController | null>(null);
   const firstMessageFired = useRef(false);
   const { t } = useLocale();
 
+  const [panelComposerHeight, setPanelComposerHeight] = useState(readStoredPanelComposerHeight);
+  const panelComposerHRef = useRef(panelComposerHeight);
+  panelComposerHRef.current = panelComposerHeight;
+
+  const getPanelComposerHeight = useCallback(() => panelComposerHRef.current, []);
+  const persistPanelComposerHeight = useCallback((h: number) => {
+    try {
+      localStorage.setItem(PANEL_COMPOSER_STORAGE, String(h));
+    } catch {
+      /* ignore */
+    }
+  }, []);
+
+  const onPanelComposerResizePointerDown = useComposerVerticalResize({
+    minHeight: PANEL_COMPOSER_MIN,
+    maxHeightAbs: PANEL_COMPOSER_MAX_ABS,
+    maxHeightViewportRatio: PANEL_COMPOSER_MAX_VIEW,
+    getHeight: getPanelComposerHeight,
+    setHeight: setPanelComposerHeight,
+    persist: persistPanelComposerHeight,
+  });
+
+  const [panelComposerViewportMax, setPanelComposerViewportMax] = useState(panelComposerMaxForViewport);
+
+  const applyPanelComposerClampAndPersist = useCallback(() => {
+    const maxH = panelComposerMaxForViewport();
+    setPanelComposerViewportMax(maxH);
+    const h = panelComposerHRef.current;
+    if (h > maxH) {
+      setPanelComposerHeight(maxH);
+      panelComposerHRef.current = maxH;
+      persistPanelComposerHeight(maxH);
+    }
+  }, [persistPanelComposerHeight]);
+
+  const handlePanelComposerSeparatorKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLElement>) => {
+      if (!['ArrowUp', 'ArrowDown', 'Home', 'End'].includes(e.key)) return;
+      e.preventDefault();
+      const maxH = panelComposerMaxForViewport();
+      setPanelComposerViewportMax(maxH);
+      const h = panelComposerHRef.current;
+      let next = h;
+      if (e.key === 'ArrowUp') next = h + PANEL_COMPOSER_KEY_STEP;
+      else if (e.key === 'ArrowDown') next = h - PANEL_COMPOSER_KEY_STEP;
+      else if (e.key === 'Home') next = PANEL_COMPOSER_MIN;
+      else if (e.key === 'End') next = maxH;
+      const clamped = Math.round(Math.max(PANEL_COMPOSER_MIN, Math.min(maxH, next)));
+      setPanelComposerHeight(clamped);
+      panelComposerHRef.current = clamped;
+      persistPanelComposerHeight(clamped);
+    },
+    [persistPanelComposerHeight],
+  );
+
+  const resetPanelComposerHeight = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      setPanelComposerHeight(PANEL_COMPOSER_DEFAULT);
+      panelComposerHRef.current = PANEL_COMPOSER_DEFAULT;
+      persistPanelComposerHeight(PANEL_COMPOSER_DEFAULT);
+    },
+    [persistPanelComposerHeight],
+  );
+
   const [input, setInput] = useState('');
   const [isLoading, setIsLoading] = useState(false);
   const [loadingPhase, setLoadingPhase] = useState<'connecting' | 'thinking' | 'streaming'>('connecting');
@@ -93,6 +188,13 @@ export default function AskContent({ visible, currentFile, initialMessage, onFir
     return () => window.removeEventListener('keydown', handler);
   }, [variant, visible, onClose, mention]);
 
+  useEffect(() => {
+    if (!isPanel) return;
+    applyPanelComposerClampAndPersist();
+    window.addEventListener('resize', applyPanelComposerClampAndPersist);
+    return () => window.removeEventListener('resize', applyPanelComposerClampAndPersist);
+  }, [isPanel, applyPanelComposerClampAndPersist]);
+
   const handleInputChange = useCallback((val: string) => {
     setInput(val);
     mention.updateMentionFromInput(val);
@@ -108,21 +210,32 @@ export default function AskContent({ visible, currentFile, initialMessage, onFir
     setTimeout(() => inputRef.current?.focus(), 0);
   }, [input, attachedFiles, mention]);
 
-  const handleInputKeyDown = useCallback((e: React.KeyboardEvent<HTMLInputElement>) => {
-    if (mention.mentionQuery === null) return;
-    if (e.key === 'ArrowDown') {
-      e.preventDefault();
-      mention.navigateMention('down');
-    } else if (e.key === 'ArrowUp') {
-      e.preventDefault();
-      mention.navigateMention('up');
-    } else if (e.key === 'Enter' || e.key === 'Tab') {
-      if (mention.mentionResults.length > 0) {
+  const handleInputKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => {
+      if (mention.mentionQuery !== null) {
+        if (e.key === 'ArrowDown') {
+          e.preventDefault();
+          mention.navigateMention('down');
+        } else if (e.key === 'ArrowUp') {
+          e.preventDefault();
+          mention.navigateMention('up');
+        } else if (e.key === 'Enter' || e.key === 'Tab') {
+          if (e.key === 'Enter' && e.shiftKey) return;
+          if (mention.mentionResults.length > 0) {
+            e.preventDefault();
+            selectMention(mention.mentionResults[mention.mentionIndex]);
+          }
+        }
+        return;
+      }
+      // Panel: multiline input — Enter sends, Shift+Enter inserts newline (textarea default).
+      if (variant === 'panel' && e.key === 'Enter' && !e.shiftKey && !isLoading && input.trim()) {
         e.preventDefault();
-        selectMention(mention.mentionResults[mention.mentionIndex]);
+        (e.currentTarget as HTMLTextAreaElement).form?.requestSubmit();
       }
-    }
-  }, [mention, selectMention]);
+    },
+    [mention, selectMention, variant, isLoading, input],
+  );
 
   const handleStop = useCallback(() => { abortRef.current?.abort(); }, []);
 
@@ -250,7 +363,6 @@ export default function AskContent({ visible, currentFile, initialMessage, onFir
     setTimeout(() => inputRef.current?.focus(), 0);
   }, [session, currentFile, upload, mention]);
 
-  const isPanel = variant === 'panel';
   const iconSize = isPanel ? 13 : 14;
   const inputIconSize = isPanel ? 14 : 15;
 
@@ -319,47 +431,79 @@ export default function AskContent({ visible, currentFile, initialMessage, onFir
         labels={{ connecting: t.ask.connecting, thinking: t.ask.thinking, generating: t.ask.generating }}
       />
 
-      {/* Input area */}
-      <div className="border-t border-border shrink-0">
-        {attachedFiles.length > 0 && (
-          <div className={isPanel ? 'px-3 pt-2 pb-1' : 'px-4 pt-2.5 pb-1'}>
-            <div className={`text-muted-foreground/70 mb-1 ${isPanel ? 'text-[10px]' : 'text-xs'}`}>
-              {isPanel ? 'Context' : 'Knowledge Base Context'}
-            </div>
-            <div className={`flex flex-wrap ${isPanel ? 'gap-1' : 'gap-1.5'}`}>
-              {attachedFiles.map(f => (
-                <FileChip key={f} path={f} onRemove={() => setAttachedFiles(prev => prev.filter(x => x !== f))} />
-              ))}
-            </div>
+      {/* Input area — panel: fixed-height shell + top drag handle (persisted); modal: simple block */}
+      <div
+        className={cn('shrink-0 border-t border-border', isPanel && 'flex flex-col overflow-hidden bg-card')}
+        style={isPanel ? { height: panelComposerHeight } : undefined}
+      >
+        {isPanel ? (
+          <div
+            role="separator"
+            tabIndex={0}
+            aria-orientation="horizontal"
+            aria-label={`${t.ask.panelComposerResize}. ${t.ask.panelComposerResetHint}. ${t.ask.panelComposerKeyboard}`}
+            aria-valuemin={PANEL_COMPOSER_MIN}
+            aria-valuemax={panelComposerViewportMax}
+            aria-valuenow={panelComposerHeight}
+            title={`${t.ask.panelComposerResize} · ${t.ask.panelComposerResetHint} · ${t.ask.panelComposerKeyboard}`}
+            onPointerDown={onPanelComposerResizePointerDown}
+            onKeyDown={handlePanelComposerSeparatorKeyDown}
+            onDoubleClick={resetPanelComposerHeight}
+            className="group flex h-3 shrink-0 cursor-ns-resize items-center justify-center border-b border-border/50 bg-muted/[0.06] transition-colors hover:bg-muted/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
+          >
+            <span
+              className="pointer-events-none h-1 w-10 rounded-full bg-border transition-colors group-hover:bg-[var(--amber)]/45 group-active:bg-[var(--amber)]/60"
+              aria-hidden
+            />
           </div>
-        )}
-
-        {upload.localAttachments.length > 0 && (
-          <div className={isPanel ? 'px-3 pb-1' : 'px-4 pb-1'}>
-            <div className={`text-muted-foreground/70 mb-1 ${isPanel ? 'text-[10px]' : 'text-xs'}`}>
-              {isPanel ? 'Uploaded' : 'Uploaded Files'}
+        ) : null}
+
+        <div className={cn(isPanel && 'flex min-h-0 flex-1 flex-col overflow-hidden')}>
+          {attachedFiles.length > 0 && (
+            <div className={cn('shrink-0', isPanel ? 'px-3 pt-2 pb-1' : 'px-4 pt-2.5 pb-1')}>
+              <div className={`text-muted-foreground/70 mb-1 ${isPanel ? 'text-[10px]' : 'text-xs'}`}>
+                {isPanel ? 'Context' : 'Knowledge Base Context'}
+              </div>
+              <div className={`flex flex-wrap ${isPanel ? 'gap-1' : 'gap-1.5'}`}>
+                {attachedFiles.map(f => (
+                  <FileChip key={f} path={f} onRemove={() => setAttachedFiles(prev => prev.filter(x => x !== f))} />
+                ))}
+              </div>
             </div>
-            <div className={`flex flex-wrap ${isPanel ? 'gap-1' : 'gap-1.5'}`}>
-              {upload.localAttachments.map((f, idx) => (
-                <FileChip key={`${f.name}-${idx}`} path={f.name} variant="upload" onRemove={() => upload.removeAttachment(idx)} />
-              ))}
+          )}
+
+          {upload.localAttachments.length > 0 && (
+            <div className={cn('shrink-0', isPanel ? 'px-3 pb-1' : 'px-4 pb-1')}>
+              <div className={`text-muted-foreground/70 mb-1 ${isPanel ? 'text-[10px]' : 'text-xs'}`}>
+                {isPanel ? 'Uploaded' : 'Uploaded Files'}
+              </div>
+              <div className={`flex flex-wrap ${isPanel ? 'gap-1' : 'gap-1.5'}`}>
+                {upload.localAttachments.map((f, idx) => (
+                  <FileChip key={`${f.name}-${idx}`} path={f.name} variant="upload" onRemove={() => upload.removeAttachment(idx)} />
+                ))}
+              </div>
             </div>
-          </div>
-        )}
+          )}
 
-        {upload.uploadError && (
-          <div className={`${isPanel ? 'px-3' : 'px-4'} pb-1 text-xs text-error`}>{upload.uploadError}</div>
-        )}
+          {upload.uploadError && (
+            <div className={cn('shrink-0 pb-1 text-xs text-error', isPanel ? 'px-3' : 'px-4')}>{upload.uploadError}</div>
+          )}
 
-        {mention.mentionQuery !== null && mention.mentionResults.length > 0 && (
-          <MentionPopover
-            results={mention.mentionResults}
-            selectedIndex={mention.mentionIndex}
-            onSelect={selectMention}
-          />
-        )}
+          {mention.mentionQuery !== null && mention.mentionResults.length > 0 && (
+            <MentionPopover
+              results={mention.mentionResults}
+              selectedIndex={mention.mentionIndex}
+              onSelect={selectMention}
+            />
+          )}
 
-        <form onSubmit={handleSubmit} className={`flex items-center ${isPanel ? 'gap-1.5 px-2 py-2.5' : 'gap-2 px-3 py-3'}`}>
+          <form
+            onSubmit={handleSubmit}
+            className={cn(
+              'flex',
+              isPanel ? 'min-h-0 flex-1 items-end gap-1.5 px-2 py-2' : 'items-center gap-2 px-3 py-3',
+            )}
+          >
           <button type="button" onClick={() => upload.uploadInputRef.current?.click()} className="p-1.5 rounded-md text-muted-foreground hover:text-foreground hover:bg-muted transition-colors shrink-0" title="Attach local file">
             <Paperclip size={inputIconSize} />
           </button>
@@ -385,7 +529,10 @@ export default function AskContent({ visible, currentFile, initialMessage, onFir
               const pos = el.selectionStart ?? input.length;
               const newVal = input.slice(0, pos) + '@' + input.slice(pos);
               handleInputChange(newVal);
-              setTimeout(() => { el.focus(); el.setSelectionRange(pos + 1, pos + 1); }, 0);
+              setTimeout(() => {
+                el.focus();
+                el.setSelectionRange(pos + 1, pos + 1);
+              }, 0);
             }}
             className="p-1.5 rounded-md text-muted-foreground hover:text-foreground hover:bg-muted transition-colors shrink-0"
             title="@ mention file"
@@ -393,15 +540,32 @@ export default function AskContent({ visible, currentFile, initialMessage, onFir
             <AtSign size={inputIconSize} />
           </button>
 
-          <input
-            ref={inputRef}
-            value={input}
-            onChange={e => handleInputChange(e.target.value)}
-            onKeyDown={handleInputKeyDown}
-            placeholder={t.ask.placeholder}
-            disabled={isLoading}
-            className="flex-1 bg-transparent text-sm text-foreground placeholder:text-muted-foreground outline-none disabled:opacity-50 min-w-0"
-          />
+          {isPanel ? (
+            <textarea
+              ref={(el) => {
+                inputRef.current = el;
+              }}
+              value={input}
+              onChange={e => handleInputChange(e.target.value)}
+              onKeyDown={handleInputKeyDown}
+              placeholder={t.ask.placeholder}
+              disabled={isLoading}
+              rows={1}
+              className="min-h-0 min-w-0 flex-1 resize-none overflow-y-auto bg-transparent py-2 text-sm leading-snug text-foreground placeholder:text-muted-foreground outline-none transition-[height] duration-75 disabled:opacity-50"
+            />
+          ) : (
+            <input
+              ref={(el) => {
+                inputRef.current = el;
+              }}
+              value={input}
+              onChange={e => handleInputChange(e.target.value)}
+              onKeyDown={handleInputKeyDown}
+              placeholder={t.ask.placeholder}
+              disabled={isLoading}
+              className="flex-1 bg-transparent text-sm text-foreground placeholder:text-muted-foreground outline-none disabled:opacity-50 min-w-0"
+            />
+          )}
 
           {isLoading ? (
             <button type="button" onClick={handleStop} className="p-1.5 rounded-md transition-colors shrink-0 text-muted-foreground hover:text-foreground hover:bg-muted" title={t.ask.stopTitle}>
@@ -412,7 +576,8 @@ export default function AskContent({ visible, currentFile, initialMessage, onFir
               <Send size={isPanel ? 13 : 14} />
             </button>
           )}
-        </form>
+          </form>
+        </div>
       </div>
 
       {/* Footer hints — use full class strings so Tailwind JIT includes utilities */}
@@ -420,13 +585,36 @@ export default function AskContent({ visible, currentFile, initialMessage, onFir
         className={cn(
           'flex shrink-0 items-center',
           isPanel
-            ? 'gap-2 px-3 pb-1.5 text-[10px] text-muted-foreground/40'
+            ? 'flex-wrap gap-x-2 gap-y-1 px-3 pb-1.5 text-[10px] text-muted-foreground/40'
             : 'hidden gap-3 px-4 pb-2 text-xs text-muted-foreground/50 md:flex',
         )}
       >
-        <span><kbd className="font-mono">↵</kbd> {t.ask.send}</span>
-        <span><kbd className="font-mono">@</kbd> {t.ask.attachFile}</span>
-        {!isPanel && <span><kbd className="font-mono">ESC</kbd> {t.search.close}</span>}
+        <span suppressHydrationWarning>
+          <kbd className="font-mono">↵</kbd> {t.ask.send}
+        </span>
+        {isPanel ? (
+          <span suppressHydrationWarning>
+            <kbd className="font-mono">⇧</kbd>
+            <kbd className="font-mono ml-0.5">↵</kbd> {t.ask.newlineHint}
+          </span>
+        ) : null}
+        {isPanel ? (
+          <span
+            className="hidden sm:inline"
+            suppressHydrationWarning
+            title={`${t.ask.panelComposerResize} · ${t.ask.panelComposerResetHint} · ${t.ask.panelComposerKeyboard}`}
+          >
+            <kbd className="font-mono">↕</kbd> {t.ask.panelComposerFooter}
+          </span>
+        ) : null}
+        <span suppressHydrationWarning>
+          <kbd className="font-mono">@</kbd> {t.ask.attachFile}
+        </span>
+        {!isPanel && (
+          <span suppressHydrationWarning>
+            <kbd className="font-mono">ESC</kbd> {t.search.close}
+          </span>
+        )}
       </div>
     </>
   );

package/app/hooks/useComposerVerticalResize.ts

@@ -0,0 +1,74 @@
+'use client';
+
+import { useCallback, type PointerEvent as ReactPointerEvent } from 'react';
+
+export interface UseComposerVerticalResizeOptions {
+  minHeight: number;
+  maxHeightAbs: number;
+  maxHeightViewportRatio: number;
+  getHeight: () => number;
+  setHeight: (h: number) => void;
+  persist: (h: number) => void;
+}
+
+/**
+ * Drag the top edge of a composer upward to grow height (panel input UX).
+ * Uses pointer capture so drag ends reliably (window exit, touch, pointercancel).
+ */
+export function useComposerVerticalResize({
+  minHeight,
+  maxHeightAbs,
+  maxHeightViewportRatio,
+  getHeight,
+  setHeight,
+  persist,
+}: UseComposerVerticalResizeOptions) {
+  const onPointerDown = useCallback(
+    (e: ReactPointerEvent<HTMLElement>) => {
+      if (e.pointerType === 'mouse' && e.button !== 0) return;
+      e.preventDefault();
+      const el = e.currentTarget;
+      el.setPointerCapture(e.pointerId);
+
+      const pointerId = e.pointerId;
+      const startY = e.clientY;
+      const startH = getHeight();
+      let currentH = startH;
+
+      const maxH = () => Math.min(maxHeightAbs, Math.floor(window.innerHeight * maxHeightViewportRatio));
+
+      document.body.classList.add('select-none');
+      document.body.style.cursor = 'ns-resize';
+
+      const onMove = (ev: PointerEvent) => {
+        if (ev.pointerId !== pointerId) return;
+        const dy = startY - ev.clientY;
+        const next = Math.round(Math.max(minHeight, Math.min(maxH(), startH + dy)));
+        currentH = next;
+        setHeight(next);
+      };
+
+      const onUpOrCancel = (ev: PointerEvent) => {
+        if (ev.pointerId !== pointerId) return;
+        document.body.classList.remove('select-none');
+        document.body.style.cursor = '';
+        el.removeEventListener('pointermove', onMove);
+        el.removeEventListener('pointerup', onUpOrCancel);
+        el.removeEventListener('pointercancel', onUpOrCancel);
+        try {
+          el.releasePointerCapture(pointerId);
+        } catch {
+          /* already released */
+        }
+        persist(currentH);
+      };
+
+      el.addEventListener('pointermove', onMove);
+      el.addEventListener('pointerup', onUpOrCancel);
+      el.addEventListener('pointercancel', onUpOrCancel);
+    },
+    [minHeight, maxHeightAbs, maxHeightViewportRatio, getHeight, setHeight, persist],
+  );
+
+  return onPointerDown;
+}

package/app/lib/i18n-en.ts

@@ -97,6 +97,11 @@ export const en = {
     placeholder: 'Ask a question... or type @ to attach a file',
     emptyPrompt: 'Ask anything about your knowledge base',
     send: 'send',
+    newlineHint: 'new line',
+    panelComposerResize: 'Drag up to enlarge the input area',
+    panelComposerFooter: 'Resize height',
+    panelComposerResetHint: 'Double-click to reset height',
+    panelComposerKeyboard: 'Arrow keys adjust height; Home/End min/max',
     attachFile: 'attach file',
     attachCurrent: 'attach current file',
     stopTitle: 'Stop',

package/app/lib/i18n-zh.ts

@@ -122,6 +122,11 @@ export const zh = {
     placeholder: '输入问题，或输入 @ 添加附件文件',
     emptyPrompt: '可以问任何关于知识库的问题',
     send: '发送',
+    newlineHint: '换行',
+    panelComposerResize: '向上拖拽以拉高输入区',
+    panelComposerFooter: '拉高输入区',
+    panelComposerResetHint: '双击恢复默认高度',
+    panelComposerKeyboard: '方向键调节高度；Home/End 最小或最大',
     attachFile: '附加文件',
     attachCurrent: '附加当前文件',
     stopTitle: '停止',

package/app/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
+import "./.next/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/app/next.config.ts

@@ -4,6 +4,7 @@ import path from "path";
 const nextConfig: NextConfig = {
   transpilePackages: ['github-slugger'],
   serverExternalPackages: ['chokidar', 'openai', '@mariozechner/pi-ai', '@mariozechner/pi-agent-core'],
+  output: 'standalone',
   outputFileTracingRoot: path.join(__dirname),
   turbopack: {
     root: path.join(__dirname),

package/bin/cli.js

@@ -394,7 +394,11 @@ const commands = {
       startSyncDaemon(mindRoot).catch(() => {});
     }
     await printStartupInfo(webPort, mcpPort);
-    run(`${NEXT_BIN} start -p ${webPort} ${extra}`, resolve(ROOT, 'app'));
+    run(
+      `${NEXT_BIN} start -p ${webPort} ${extra}`,
+      resolve(ROOT, 'app'),
+      process.env.HOSTNAME ? undefined : { HOSTNAME: '127.0.0.1' }
+    );
   },
 
   // ── build ──────────────────────────────────────────────────────────────────

package/bin/lib/utils.js

@@ -3,9 +3,13 @@ import { resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { ROOT } from './constants.js';
 
-export function run(command, cwd = ROOT) {
+/**
+ * @param {Record<string, string | undefined>} [envPatch] merged into process.env (for child only)
+ */
+export function run(command, cwd = ROOT, envPatch) {
   try {
-    execSync(command, { cwd, stdio: 'inherit', env: process.env });
+    const env = envPatch ? { ...process.env, ...envPatch } : process.env;
+    execSync(command, { cwd, stdio: 'inherit', env });
   } catch (err) {
     process.exit(err.status || 1);
   }

package/mcp/package.json

@@ -8,11 +8,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.0",
+    "tsx": "^4.19.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^22",
-    "tsx": "^4.19.0",
     "typescript": "^5"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminilight/mindos",
-  "version": "0.5.56",
+  "version": "0.5.57",
   "description": "MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.",
   "keywords": [
     "mindos",
@@ -64,6 +64,7 @@
     "start": "mindos start",
     "mcp": "mindos mcp",
     "test": "cd app && npx vitest run",
+    "verify:standalone": "node scripts/verify-standalone.mjs",
     "release": "bash scripts/release.sh"
   },
   "engines": {

package/scripts/release.sh

@@ -28,6 +28,13 @@ else
   exit 1
 fi
 cd ..
+echo "🩺 Verifying standalone server (/api/health)..."
+if node scripts/verify-standalone.mjs; then
+  echo "   ✅ Standalone smoke OK"
+else
+  echo "❌ Standalone verify failed (trace / serverExternalPackages?)"
+  exit 1
+fi
 # Restore any files modified by next build (e.g. next-env.d.ts)
 git checkout -- . 2>/dev/null || true
 echo ""

package/scripts/verify-standalone.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * Smoke-test Next standalone server: merge static/public, spawn server.js, GET /api/health.
+ * Catches missing serverExternalPackages / file-trace gaps (MODULE_NOT_FOUND at startup).
+ *
+ * Run from repo root after: cd app && ./node_modules/.bin/next build
+ *   node scripts/verify-standalone.mjs
+ *
+ * @see wiki/specs/spec-desktop-standalone-runtime.md
+ */
+import { spawn } from 'child_process';
+import http from 'http';
+import { existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { materializeStandaloneAssets } from '../desktop/scripts/prepare-mindos-bundle.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..');
+const appDir = path.join(root, 'app');
+const serverJs = path.join(appDir, '.next', 'standalone', 'server.js');
+
+if (!existsSync(serverJs)) {
+  console.error(
+    `[verify-standalone] Missing ${serverJs}\nBuild first: cd app && ./node_modules/.bin/next build`
+  );
+  process.exit(1);
+}
+
+try {
+  materializeStandaloneAssets(appDir);
+} catch (e) {
+  console.error(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+}
+
+const port = 31000 + Math.floor(Math.random() * 5000);
+const nodeBin = process.execPath;
+
+function waitHealth(timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    const tick = () => {
+      if (Date.now() > deadline) {
+        reject(new Error(`Timeout waiting for http://127.0.0.1:${port}/api/health`));
+        return;
+      }
+      const req = http.get(
+        `http://127.0.0.1:${port}/api/health`,
+        { timeout: 2000 },
+        (res) => {
+          let body = '';
+          res.on('data', (c) => {
+            body += c;
+          });
+          res.on('end', () => {
+            if (res.statusCode === 200) {
+              try {
+                const j = JSON.parse(body);
+                if (j.ok === true && j.service === 'mindos') {
+                  resolve();
+                  return;
+                }
+              } catch {
+                /* fall through */
+              }
+            }
+            setTimeout(tick, 300);
+          });
+        }
+      );
+      req.on('error', () => {
+        setTimeout(tick, 300);
+      });
+      req.on('timeout', () => {
+        req.destroy();
+        setTimeout(tick, 300);
+      });
+    };
+    tick();
+  });
+}
+
+let stderr = '';
+const child = spawn(nodeBin, [serverJs], {
+  cwd: appDir,
+  env: {
+    ...process.env,
+    NODE_ENV: 'production',
+    PORT: String(port),
+    /** Next binds to machine hostname by default; Desktop health checks use 127.0.0.1 */
+    HOSTNAME: '127.0.0.1',
+  },
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+
+child.stderr?.on('data', (c) => {
+  stderr += c.toString();
+});
+
+function killChild() {
+  try {
+    child.kill('SIGTERM');
+  } catch {
+    /* ignore */
+  }
+}
+
+async function main() {
+  try {
+    await waitHealth(90_000);
+    console.log(`[verify-standalone] OK (port ${port})`);
+    return 0;
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    if (stderr.trim()) console.error('--- server stderr (tail) ---\n', stderr.slice(-4000));
+    return 1;
+  } finally {
+    killChild();
+    await new Promise((r) => setTimeout(r, 500));
+  }
+}
+
+child.on('error', (err) => {
+  console.error('[verify-standalone] spawn failed:', err.message);
+  process.exit(1);
+});
+
+main().then((code) => process.exit(code));

package/skills/mindos/SKILL.md

@@ -2,6 +2,8 @@
 name: mindos
 description: >
   MindOS knowledge base operation guide, only for agent tasks on files inside the MindOS knowledge base.
+  Explains core concepts: Space (partitions by how you think), Instruction (agent-wide rules, often in INSTRUCTION.md),
+  Skill (how agents read/write/organize the KB via SKILL.md packages). Notes can embody Instructions and Skills.
   Trigger only when the target files are inside the MindOS knowledge base directory.
   Typical requests: "update notes", "search knowledge base", "organize files", "execute SOP",
   "review with our standards", "handoff to another agent", "sync decisions", "append CSV",
@@ -20,9 +22,19 @@ context automatically when present. User rules override default rules on conflic
 
 ---
 
-<!-- version: 1.1.0 -->
+<!-- version: 1.2.0 -->
 # MindOS Operating Rules
 
+## MindOS concepts
+
+Shared vocabulary for the knowledge base and connected agents:
+
+- **Space** — Knowledge partitions organized the way you think. You decide the structure, and AI agents follow it to read, write, and manage automatically.
+- **Instruction** — A rules file that all AI agents obey. You write the boundaries once, and every agent connected to your knowledge base follows them.
+- **Skill** — Teaches agents how to operate your knowledge base — reading, writing, organizing. Agents don't guess; they follow the skills you've installed.
+
+**Notes as Instruction and Skill** — Instructions and Skills are usually expressed as Markdown in your tree (e.g. root or directory `INSTRUCTION.md`, `SKILL.md` under a skill folder). A note is not only free-form text: it can be the governance layer agents must follow (Instruction) or a procedure package agents load to execute (Skill).
+
 ## Core Principles
 
 - Treat repository state as source of truth.

package/skills/mindos-zh/SKILL.md

@@ -2,6 +2,8 @@
 name: mindos-zh
 description: >
   MindOS 知识库中文操作指南，仅用于 MindOS 知识库内的 Agent 任务。
+  说明核心概念：空间（按思维方式划分的知识分区）、指令（全 Agent 遵守的规则，常见为 INSTRUCTION.md）、
+  技能（通过 SKILL.md 等教 Agent 如何读写整理知识库）。笔记可以承载指令与技能。
   仅当操作目标是 MindOS 知识库目录下的文件时触发，典型请求包括"更新笔记""搜索知识库"
   "整理文件""执行 SOP""按团队标准 review""把任务交接给另一个 Agent""同步决策"
   "追加 CSV""复盘这段对话""提炼关键经验""把复盘结果自适应更新到对应文档"
@@ -18,9 +20,19 @@ description: >
 
 ---
 
-<!-- version: 1.1.0 -->
+<!-- version: 1.2.0 -->
 # MindOS 操作规则
 
+## MindOS 核心概念
+
+与知识库和接入 Agent 共用的术语说明：
+
+- **空间（Space）** — 按你的思维方式组织的知识分区。你怎么想，就怎么分，AI Agent 遵循同样的结构来自动读写和管理。
+- **指令（Instruction）** — 一份所有 AI Agent 都遵守的规则文件。你写一次边界，每个连接到知识库的 Agent 都会照做。
+- **技能（Skill）** — 教 Agent 如何操作你的知识库——读取、写入、整理。Agent 不是瞎猜，而是按你安装的 Skill 来执行。
+
+**笔记即指令 / 技能** — 指令与技能在知识库里通常体现为 Markdown 文件（例如根或目录下的 `INSTRUCTION.md`、技能目录中的 `SKILL.md`）。笔记不只是随笔：可以是 Agent 必须遵守的治理层（指令），也可以是 Agent 加载后按步骤执行的程序包（技能）。
+
 ## 核心原则
 
 - 以仓库当前状态为唯一依据。