From db711648e0885ba82ebb3a0160eed02f1e761a7c Mon Sep 17 00:00:00 2001
From: kurihada <kurihada@qq.com>
Date: Fri, 12 Dec 2025 18:38:43 +0800
Subject: [PATCH] =?UTF-8?q?feat(ui):=20=E6=B7=BB=E5=8A=A0=E6=96=9C?=
 =?UTF-8?q?=E6=9D=A0=E5=91=BD=E4=BB=A4=E8=BE=93=E5=85=A5=E6=94=AF=E6=8C=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 useCommands hook 用于加载和搜索命令
- 新增 CommandMenu 组件，支持键盘导航和选择
- ChatInput 支持 / 触发命令菜单
- 导出命令相关 API 和类型
---
 packages/ui/src/components/ChatInput.tsx   | 105 ++++++++-
 packages/ui/src/components/CommandMenu.tsx | 245 +++++++++++++++++++++
 packages/ui/src/hooks/useCommands.ts       | 143 ++++++++++++
 packages/ui/src/index.ts                   |  13 ++
 4 files changed, 500 insertions(+), 6 deletions(-)
 create mode 100644 packages/ui/src/components/CommandMenu.tsx
 create mode 100644 packages/ui/src/hooks/useCommands.ts

diff --git a/packages/ui/src/components/ChatInput.tsx b/packages/ui/src/components/ChatInput.tsx
index 7cd128e..ade207c 100644
--- a/packages/ui/src/components/ChatInput.tsx
+++ b/packages/ui/src/components/ChatInput.tsx
@@ -2,11 +2,14 @@
  * Chat Input Component
  *
  * 支持响应式：responsive=true 时适配移动端键盘和触摸操作
+ * 支持斜杠命令：输入 / 时显示命令菜单
  */
 
-import { useState, useRef, useEffect } from 'react';
+import { useState, useRef, useEffect, useCallback } from 'react';
 import { Send, Square } from 'lucide-react';
 import clsx from 'clsx';
+import { CommandMenu, type CommandMenuItem } from './CommandMenu.js';
+import { useCommands } from '../hooks/useCommands.js';
 
 interface ChatInputProps {
   onSend: (content: string) => void;
@@ -15,6 +18,8 @@ interface ChatInputProps {
   disabled?: boolean;
   /** 是否启用响应式布局（移动端适配） */
   responsive?: boolean;
+  /** 是否启用斜杠命令 */
+  enableCommands?: boolean;
 }
 
 export function ChatInput({
@@ -23,10 +28,20 @@ export function ChatInput({
   isLoading,
   disabled,
   responsive = false,
+  enableCommands = true,
 }: ChatInputProps) {
   const [input, setInput] = useState('');
+  const [showCommandMenu, setShowCommandMenu] = useState(false);
+  const [selectedCommandIndex, setSelectedCommandIndex] = useState(0);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
 
+  // 命令系统
+  const {
+    filteredCommands,
+    isLoading: commandsLoading,
+    filterCommands,
+  } = useCommands({ autoLoad: enableCommands });
+
   // 自动调整高度
   useEffect(() => {
     const textarea = textareaRef.current;
@@ -38,10 +53,59 @@ export function ChatInput({
     }
   }, [input, responsive]);
 
+  // 检测斜杠命令输入
+  const checkCommandTrigger = useCallback(
+    (value: string) => {
+      if (!enableCommands) return;
+
+      // 检测是否在输入斜杠命令
+      // 条件：以 / 开头，且 / 后面没有空格（还在输入命令名）
+      const slashMatch = value.match(/^\/(\S*)$/);
+
+      if (slashMatch) {
+        const query = slashMatch[1]; // / 后面的内容
+        setShowCommandMenu(true);
+        setSelectedCommandIndex(0);
+        filterCommands(query);
+      } else {
+        setShowCommandMenu(false);
+      }
+    },
+    [enableCommands, filterCommands]
+  );
+
+  // 处理输入变化
+  const handleInputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    const value = e.target.value;
+    setInput(value);
+    checkCommandTrigger(value);
+  };
+
+  // 选择命令
+  const handleCommandSelect = useCallback(
+    (command: CommandMenuItem) => {
+      // 替换输入内容为 /command + 空格，准备输入参数
+      setInput(`/${command.name} `);
+      setShowCommandMenu(false);
+
+      // 聚焦输入框
+      textareaRef.current?.focus();
+    },
+    []
+  );
+
+  // 关闭命令菜单
+  const handleCommandMenuClose = useCallback(() => {
+    setShowCommandMenu(false);
+  }, []);
+
   const handleSubmit = () => {
     const trimmed = input.trim();
     if (!trimmed || isLoading || disabled) return;
 
+    // 关闭命令菜单
+    setShowCommandMenu(false);
+
     onSend(trimmed);
     setInput('');
 
@@ -52,6 +116,22 @@ export function ChatInput({
   };
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
+    // 如果命令菜单打开，让菜单处理键盘事件
+    if (showCommandMenu && filteredCommands.length > 0) {
+      if (['ArrowUp', 'ArrowDown', 'Tab', 'Escape'].includes(e.key)) {
+        // 这些键由 CommandMenu 处理，阻止默认行为
+        return;
+      }
+      if (e.key === 'Enter' && !e.shiftKey) {
+        // Enter 选择命令
+        e.preventDefault();
+        if (filteredCommands[selectedCommandIndex]) {
+          handleCommandSelect(filteredCommands[selectedCommandIndex]);
+        }
+        return;
+      }
+    }
+
     // Enter 发送，Shift+Enter 换行
     if (e.key === 'Enter' && !e.shiftKey) {
       e.preventDefault();
@@ -62,21 +142,34 @@ export function ChatInput({
   return (
     <div
       className={clsx(
-        'border-t border-gray-700 bg-gray-900',
+        'border-t border-gray-700 bg-gray-900 relative',
         responsive ? 'p-3 md:p-4 safe-area-pb' : 'p-4'
       )}
     >
+      {/* Command Menu */}
+      {enableCommands && (
+        <CommandMenu
+          commands={filteredCommands}
+          isOpen={showCommandMenu}
+          selectedIndex={selectedCommandIndex}
+          onSelect={handleCommandSelect}
+          onClose={handleCommandMenuClose}
+          onSelectedIndexChange={setSelectedCommandIndex}
+          isLoading={commandsLoading}
+        />
+      )}
+
       <div className="max-w-4xl mx-auto flex gap-2">
         <div className="flex-1 relative">
           <textarea
             ref={textareaRef}
             value={input}
-            onChange={(e) => setInput(e.target.value)}
+            onChange={handleInputChange}
             onKeyDown={handleKeyDown}
             placeholder={
               responsive
-                ? 'Type a message...'
-                : 'Type a message... (Shift+Enter for new line)'
+                ? 'Type a message or /command...'
+                : 'Type a message or /command... (Shift+Enter for new line)'
             }
             disabled={disabled}
             rows={1}
@@ -110,7 +203,7 @@ export function ChatInput({
       {/* 响应式模式下桌面端显示提示文字 */}
       {responsive && (
         <p className="hidden md:block text-xs text-gray-500 text-center mt-2">
-          Press Enter to send, Shift+Enter for new line
+          Press Enter to send, Shift+Enter for new line, / for commands
         </p>
       )}
     </div>
diff --git a/packages/ui/src/components/CommandMenu.tsx b/packages/ui/src/components/CommandMenu.tsx
new file mode 100644
index 0000000..46cc7ef
--- /dev/null
+++ b/packages/ui/src/components/CommandMenu.tsx
@@ -0,0 +1,245 @@
+/**
+ * Command Menu Component
+ *
+ * 斜杠命令选择菜单，支持键盘导航
+ */
+
+import { useEffect, useRef } from 'react';
+import { motion, AnimatePresence } from 'framer-motion';
+import { Terminal, Sparkles, FolderGit2 } from 'lucide-react';
+import clsx from 'clsx';
+
+export interface CommandMenuItem {
+  name: string;
+  description?: string;
+  source: string;
+}
+
+interface CommandMenuProps {
+  /** 命令列表 */
+  commands: CommandMenuItem[];
+  /** 是否显示 */
+  isOpen: boolean;
+  /** 当前选中索引 */
+  selectedIndex: number;
+  /** 选择命令回调 */
+  onSelect: (command: CommandMenuItem) => void;
+  /** 关闭菜单回调 */
+  onClose: () => void;
+  /** 选中索引变化回调 */
+  onSelectedIndexChange: (index: number) => void;
+  /** 是否正在加载 */
+  isLoading?: boolean;
+  /** 定位参考点（用于计算菜单位置） */
+  anchorRect?: DOMRect | null;
+}
+
+// 根据 source 获取图标
+function getSourceIcon(source: string) {
+  switch (source) {
+    case 'builtin':
+      return <Terminal size={14} className="text-blue-400" />;
+    case 'user':
+      return <Sparkles size={14} className="text-purple-400" />;
+    case 'project':
+      return <FolderGit2 size={14} className="text-green-400" />;
+    default:
+      return <Terminal size={14} className="text-gray-400" />;
+  }
+}
+
+// 根据 source 获取标签颜色
+function getSourceBadge(source: string) {
+  const colors: Record<string, string> = {
+    builtin: 'bg-blue-500/20 text-blue-400',
+    user: 'bg-purple-500/20 text-purple-400',
+    project: 'bg-green-500/20 text-green-400',
+  };
+  return colors[source] || 'bg-gray-500/20 text-gray-400';
+}
+
+export function CommandMenu({
+  commands,
+  isOpen,
+  selectedIndex,
+  onSelect,
+  onClose,
+  onSelectedIndexChange,
+  isLoading = false,
+}: CommandMenuProps) {
+  const menuRef = useRef<HTMLDivElement>(null);
+  const selectedRef = useRef<HTMLButtonElement>(null);
+
+  // 滚动选中项到可见区域
+  useEffect(() => {
+    if (isOpen && selectedRef.current) {
+      selectedRef.current.scrollIntoView({
+        block: 'nearest',
+        behavior: 'smooth',
+      });
+    }
+  }, [selectedIndex, isOpen]);
+
+  // 键盘导航
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault();
+          onSelectedIndexChange(
+            selectedIndex < commands.length - 1 ? selectedIndex + 1 : 0
+          );
+          break;
+        case 'ArrowUp':
+          e.preventDefault();
+          onSelectedIndexChange(
+            selectedIndex > 0 ? selectedIndex - 1 : commands.length - 1
+          );
+          break;
+        case 'Enter':
+          e.preventDefault();
+          if (commands[selectedIndex]) {
+            onSelect(commands[selectedIndex]);
+          }
+          break;
+        case 'Escape':
+          e.preventDefault();
+          onClose();
+          break;
+        case 'Tab':
+          e.preventDefault();
+          if (commands[selectedIndex]) {
+            onSelect(commands[selectedIndex]);
+          }
+          break;
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isOpen, commands, selectedIndex, onSelect, onClose, onSelectedIndexChange]);
+
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <motion.div
+          ref={menuRef}
+          initial={{ opacity: 0, y: 8, scale: 0.96 }}
+          animate={{ opacity: 1, y: 0, scale: 1 }}
+          exit={{ opacity: 0, y: 8, scale: 0.96 }}
+          transition={{ duration: 0.15 }}
+          className="absolute bottom-full left-0 right-0 mb-2 mx-4 md:mx-0 z-50"
+        >
+          <div className="bg-gray-800 border border-gray-700 rounded-lg shadow-xl overflow-hidden max-h-64 overflow-y-auto">
+            {/* Header */}
+            <div className="px-3 py-2 border-b border-gray-700 bg-gray-800/80 sticky top-0">
+              <div className="flex items-center gap-2 text-xs text-gray-400">
+                <Terminal size={12} />
+                <span>Commands</span>
+                {commands.length > 0 && (
+                  <span className="text-gray-500">({commands.length})</span>
+                )}
+              </div>
+            </div>
+
+            {/* Loading */}
+            {isLoading && commands.length === 0 && (
+              <div className="px-3 py-4 text-center text-gray-400 text-sm">
+                Loading commands...
+              </div>
+            )}
+
+            {/* Empty state */}
+            {!isLoading && commands.length === 0 && (
+              <div className="px-3 py-4 text-center text-gray-400 text-sm">
+                No commands found
+              </div>
+            )}
+
+            {/* Command list */}
+            {commands.length > 0 && (
+              <div className="py-1">
+                {commands.map((command, index) => (
+                  <button
+                    key={command.name}
+                    ref={index === selectedIndex ? selectedRef : null}
+                    onClick={() => onSelect(command)}
+                    onMouseEnter={() => onSelectedIndexChange(index)}
+                    className={clsx(
+                      'w-full px-3 py-2 flex items-start gap-3 text-left transition-colors',
+                      index === selectedIndex
+                        ? 'bg-primary-600/20'
+                        : 'hover:bg-gray-700/50'
+                    )}
+                  >
+                    {/* Icon */}
+                    <div className="mt-0.5">{getSourceIcon(command.source)}</div>
+
+                    {/* Content */}
+                    <div className="flex-1 min-w-0">
+                      <div className="flex items-center gap-2">
+                        <span
+                          className={clsx(
+                            'font-mono text-sm',
+                            index === selectedIndex
+                              ? 'text-primary-300'
+                              : 'text-gray-200'
+                          )}
+                        >
+                          /{command.name}
+                        </span>
+                        <span
+                          className={clsx(
+                            'text-[10px] px-1.5 py-0.5 rounded-full',
+                            getSourceBadge(command.source)
+                          )}
+                        >
+                          {command.source}
+                        </span>
+                      </div>
+                      {command.description && (
+                        <p className="text-xs text-gray-400 mt-0.5 truncate">
+                          {command.description}
+                        </p>
+                      )}
+                    </div>
+
+                    {/* Keyboard hint */}
+                    {index === selectedIndex && (
+                      <div className="flex items-center gap-1 text-[10px] text-gray-500">
+                        <kbd className="px-1 py-0.5 bg-gray-700 rounded">
+                          Enter
+                        </kbd>
+                      </div>
+                    )}
+                  </button>
+                ))}
+              </div>
+            )}
+
+            {/* Footer hint */}
+            <div className="px-3 py-1.5 border-t border-gray-700 bg-gray-800/80 sticky bottom-0">
+              <div className="flex items-center gap-3 text-[10px] text-gray-500">
+                <span>
+                  <kbd className="px-1 py-0.5 bg-gray-700 rounded mr-1">↑</kbd>
+                  <kbd className="px-1 py-0.5 bg-gray-700 rounded">↓</kbd>
+                  {' '}navigate
+                </span>
+                <span>
+                  <kbd className="px-1 py-0.5 bg-gray-700 rounded">Tab</kbd>
+                  {' '}select
+                </span>
+                <span>
+                  <kbd className="px-1 py-0.5 bg-gray-700 rounded">Esc</kbd>
+                  {' '}close
+                </span>
+              </div>
+            </div>
+          </div>
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}
diff --git a/packages/ui/src/hooks/useCommands.ts b/packages/ui/src/hooks/useCommands.ts
new file mode 100644
index 0000000..05d47b5
--- /dev/null
+++ b/packages/ui/src/hooks/useCommands.ts
@@ -0,0 +1,143 @@
+/**
+ * Commands Hook
+ *
+ * 管理斜杠命令的加载、搜索和缓存
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { listCommands, searchCommands } from '../api/client.js';
+import type { CommandListResponse } from '../api/types.js';
+
+type CommandItem = CommandListResponse['commands'][number];
+
+interface UseCommandsOptions {
+  /** 是否在挂载时自动加载命令列表 */
+  autoLoad?: boolean;
+}
+
+interface UseCommandsState {
+  /** 所有命令列表 */
+  commands: CommandItem[];
+  /** 过滤后的命令列表 */
+  filteredCommands: CommandItem[];
+  /** 是否正在加载 */
+  isLoading: boolean;
+  /** 错误信息 */
+  error: string | null;
+}
+
+export function useCommands(options: UseCommandsOptions = {}) {
+  const { autoLoad = true } = options;
+
+  const [state, setState] = useState<UseCommandsState>({
+    commands: [],
+    filteredCommands: [],
+    isLoading: false,
+    error: null,
+  });
+
+  const loadedRef = useRef(false);
+
+  // 加载命令列表
+  const loadCommands = useCallback(async () => {
+    if (state.isLoading) return;
+
+    setState((prev) => ({ ...prev, isLoading: true, error: null }));
+
+    try {
+      const result = await listCommands();
+      if (result.success) {
+        setState({
+          commands: result.data.commands,
+          filteredCommands: result.data.commands,
+          isLoading: false,
+          error: null,
+        });
+      } else {
+        setState((prev) => ({
+          ...prev,
+          isLoading: false,
+          error: 'Failed to load commands',
+        }));
+      }
+    } catch (error) {
+      setState((prev) => ({
+        ...prev,
+        isLoading: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      }));
+    }
+  }, [state.isLoading]);
+
+  // 搜索/过滤命令
+  const filterCommands = useCallback(
+    async (query: string) => {
+      // 空查询显示所有命令
+      if (!query.trim()) {
+        setState((prev) => ({
+          ...prev,
+          filteredCommands: prev.commands,
+        }));
+        return;
+      }
+
+      // 本地过滤（快速响应）
+      const queryLower = query.toLowerCase();
+      const localFiltered = state.commands.filter(
+        (cmd) =>
+          cmd.name.toLowerCase().includes(queryLower) ||
+          cmd.description?.toLowerCase().includes(queryLower)
+      );
+
+      // 如果本地过滤有结果，直接使用
+      if (localFiltered.length > 0) {
+        setState((prev) => ({
+          ...prev,
+          filteredCommands: localFiltered,
+        }));
+        return;
+      }
+
+      // 否则尝试服务端搜索（可能有模糊匹配）
+      try {
+        const result = await searchCommands(query, 10);
+        if (result.success && result.data.length > 0) {
+          setState((prev) => ({
+            ...prev,
+            filteredCommands: result.data.map((r) => ({
+              name: r.name,
+              description: r.description,
+              source: r.source,
+            })),
+          }));
+        } else {
+          setState((prev) => ({
+            ...prev,
+            filteredCommands: [],
+          }));
+        }
+      } catch {
+        // 搜索失败，保持本地过滤结果
+        setState((prev) => ({
+          ...prev,
+          filteredCommands: localFiltered,
+        }));
+      }
+    },
+    [state.commands]
+  );
+
+  // 自动加载
+  useEffect(() => {
+    if (autoLoad && !loadedRef.current) {
+      loadedRef.current = true;
+      loadCommands();
+    }
+  }, [autoLoad, loadCommands]);
+
+  return {
+    ...state,
+    loadCommands,
+    filterCommands,
+  };
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 8b86a13..1d0b1ed 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -21,6 +21,12 @@ export {
   getFileTree,
   getConfig,
   updateConfig,
+  // Commands API
+  listCommands,
+  getCommand,
+  executeCommand,
+  searchCommands,
+  reloadCommands,
 } from './api/client.js';
 
 // Types
@@ -34,6 +40,11 @@ export type {
   FileTreeNode,
   FileTreeResponse,
   ServerConfig,
+  // Command types
+  CommandInfo,
+  CommandSearchResult,
+  CommandExecuteResult,
+  CommandListResponse,
 } from './api/client.js';
 
 // Primitives (shadcn/ui style)
@@ -46,6 +57,7 @@ export * from './utils/animations.js';
 // Components
 export { ChatMessage, StreamingMessage, TypingIndicator } from './components/ChatMessage.js';
 export { ChatInput } from './components/ChatInput.js';
+export { CommandMenu, type CommandMenuItem } from './components/CommandMenu.js';
 export { Sidebar } from './components/Sidebar.js';
 export { FileBrowser } from './components/FileBrowser.js';
 export { ConfigPanel } from './components/ConfigPanel.js';
@@ -59,3 +71,4 @@ export { toast } from 'sonner';
 
 // Hooks
 export { useChat } from './hooks/useChat.js';
+export { useCommands } from './hooks/useCommands.js';