feat: 添加系统命令支持 (:clear)

- 新增系统命令模块 (core/system-commands) - 支持 :clear/:cls/:c 清空对话历史 - 命令注册表支持别名 - 可扩展的命令执行器 - Server 端支持 - 新增 /api/system-commands API - WebSocket 处理系统命令消息 - 会话清空 API 端点 - UI 端支持 - 新增 SystemCommandMenu 组件 - 输入 : 时显示命令建议菜单 - 键盘导航和选择 - 底部提示添加 : 快捷键
2025-12-17 19:25:42 +08:00
parent 4fc6b61134
commit e0444a966f
21 changed files with 1109 additions and 9 deletions
@@ -53,6 +53,9 @@ import type {
  // LSP types
  LSPServer,
  DiagnosticsResponse,
+  // System Commands types
+  SystemCommandListResponse,
+  SystemCommandInfo,
 } from './types.js';

 // Re-export types
@@ -145,6 +148,9 @@ export type {
  SingleFileDiagnosticsResponse,
  AllFilesDiagnosticsResponse,
  DiagnosticsResponse,
+  // System Commands types
+  SystemCommandInfo,
+  SystemCommandListResponse,
 } from './types.js';

 // API Configuration
@@ -368,6 +374,29 @@ export async function deleteCommand(
  return request('DELETE', `/commands/${encodeURIComponent(name)}`);
 }

+// ============ System Commands API (: 前缀) ============
+
+/**
+ * 获取所有系统命令列表
+ */
+export async function listSystemCommands(): Promise<{
+  success: boolean;
+  data: SystemCommandListResponse;
+}> {
+  return request('GET', '/system-commands');
+}
+
+/**
+ * 获取单个系统命令
+ */
+export async function getSystemCommand(name: string): Promise<{
+  success: boolean;
+  data?: SystemCommandInfo;
+  error?: string;
+}> {
+  return request('GET', `/system-commands/${encodeURIComponent(name)}`);
+}
+
 // ============ MCP API ============

 /**
@@ -291,6 +291,23 @@ export interface CommandContent {
  sourcePath?: string;
 }

+// ============ System Commands (: 前缀) 相关 ============
+
+/** 系统命令信息 */
+export interface SystemCommandInfo {
+  /** 命令名称（不含 : 前缀） */
+  name: string;
+  /** 命令描述 */
+  description: string;
+  /** 命令别名 */
+  aliases: string[];
+}
+
+/** 系统命令列表响应 */
+export interface SystemCommandListResponse {
+  commands: SystemCommandInfo[];
+}
+
 // ============ MCP 相关 ============

 /** MCP 服务器状态类型 */
@@ -3,6 +3,7 @@
 *
 * 支持响应式：responsive=true 时适配移动端键盘和触摸操作
 * 支持斜杠命令：输入 / 时显示命令菜单
+ * 支持系统命令：输入 : 时显示系统命令菜单
 * 支持文件提及：输入 @ 时显示文件搜索菜单
 */

@@ -11,10 +12,12 @@ import { Square, Sparkles } from 'lucide-react';
 import { motion } from 'framer-motion';
 import clsx from 'clsx';
 import { CommandMenu, type CommandMenuItem } from './CommandMenu.js';
+import { SystemCommandMenu, type SystemCommandMenuItem } from './SystemCommandMenu.js';
 import { FileMenu, type FileMenuItem } from './FileMenu.js';
 import { FileMentionTag } from './FileMentionTag.js';
 import { AgentModeSelector, type AgentModeType } from './AgentModeSelector.js';
 import { useCommands } from '../hooks/useCommands.js';
+import { useSystemCommands } from '../hooks/useSystemCommands.js';
 import { useFileMention } from '../hooks/useFileMention.js';

 interface ChatInputProps {
@@ -54,6 +57,8 @@ export function ChatInput({
  const [input, setInput] = useState('');
  const [showCommandMenu, setShowCommandMenu] = useState(false);
  const [selectedCommandIndex, setSelectedCommandIndex] = useState(0);
+  const [showSystemCommandMenu, setShowSystemCommandMenu] = useState(false);
+  const [selectedSystemCommandIndex, setSelectedSystemCommandIndex] = useState(0);
  const textareaRef = useRef<HTMLTextAreaElement>(null);

  // 命令系统
@@ -63,6 +68,13 @@ export function ChatInput({
    filterCommands,
  } = useCommands({ autoLoad: enableCommands });

+  // 系统命令系统
+  const {
+    filteredCommands: filteredSystemCommands,
+    isLoading: systemCommandsLoading,
+    filterCommands: filterSystemCommands,
+  } = useSystemCommands({ autoLoad: enableCommands });
+
  // 文件提及系统
  const {
    isOpen: showFileMenu,
@@ -130,17 +142,41 @@ export function ChatInput({
    [enableCommands, filterCommands]
  );

+  // 检测系统命令输入
+  const checkSystemCommandTrigger = useCallback(
+    (value: string) => {
+      if (!enableCommands) return;
+
+      // 检测是否在输入系统命令
+      // 条件：以 : 开头，且 : 后面没有空格（还在输入命令名）
+      const colonMatch = value.match(/^:(\S*)$/);
+
+      if (colonMatch) {
+        const query = colonMatch[1]; // : 后面的内容
+        setShowSystemCommandMenu(true);
+        setSelectedSystemCommandIndex(0);
+        filterSystemCommands(query);
+      } else {
+        setShowSystemCommandMenu(false);
+      }
+    },
+    [enableCommands, filterSystemCommands]
+  );
+
  // 处理输入变化
  const handleInputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
    const value = e.target.value;
    const cursorPos = e.target.selectionStart;
    setInput(value);

-    // 检查命令触发
+    // 检查斜杠命令触发
    checkCommandTrigger(value);

+    // 检查系统命令触发
+    checkSystemCommandTrigger(value);
+
    // 检查文件提及触发（只在非命令输入模式下）
-    if (enableFileMention && !value.startsWith('/')) {
+    if (enableFileMention && !value.startsWith('/') && !value.startsWith(':')) {
      checkFileTrigger(value, cursorPos);
    } else {
      closeFileMenu();
@@ -189,12 +225,28 @@ export function ChatInput({
    setShowCommandMenu(false);
  }, []);

+  // 选择系统命令
+  const handleSystemCommandSelect = useCallback((command: SystemCommandMenuItem) => {
+    // 直接发送系统命令
+    setInput(`:${command.name}`);
+    setShowSystemCommandMenu(false);
+
+    // 聚焦输入框
+    textareaRef.current?.focus();
+  }, []);
+
+  // 关闭系统命令菜单
+  const handleSystemCommandMenuClose = useCallback(() => {
+    setShowSystemCommandMenu(false);
+  }, []);
+
  const handleSubmit = () => {
    const trimmed = input.trim();
    if (!trimmed || isLoading || disabled) return;

-    // 关闭菜单
+    // 关闭所有菜单
    setShowCommandMenu(false);
+    setShowSystemCommandMenu(false);
    closeFileMenu();

    onSend(trimmed);
@@ -222,7 +274,7 @@ export function ChatInput({
      }
    }

-    // 命令菜单处理
+    // 斜杠命令菜单处理
    if (showCommandMenu && filteredCommands.length > 0) {
      if (['ArrowUp', 'ArrowDown', 'Tab', 'Escape'].includes(e.key)) {
        // 这些键由 CommandMenu 处理，阻止默认行为
@@ -238,6 +290,22 @@ export function ChatInput({
      }
    }

+    // 系统命令菜单处理
+    if (showSystemCommandMenu && filteredSystemCommands.length > 0) {
+      if (['ArrowUp', 'ArrowDown', 'Tab', 'Escape'].includes(e.key)) {
+        // 这些键由 SystemCommandMenu 处理，阻止默认行为
+        return;
+      }
+      if (e.key === 'Enter' && !e.shiftKey) {
+        // Enter 选择系统命令
+        e.preventDefault();
+        if (filteredSystemCommands[selectedSystemCommandIndex]) {
+          handleSystemCommandSelect(filteredSystemCommands[selectedSystemCommandIndex]);
+        }
+        return;
+      }
+    }
+
    // Enter 发送，Shift+Enter 换行
    if (e.key === 'Enter' && !e.shiftKey) {
      e.preventDefault();
@@ -252,7 +320,7 @@ export function ChatInput({
        responsive ? 'p-3 md:p-4 safe-area-pb' : 'p-4'
      )}
    >
-      {/* Command Menu */}
+      {/* Command Menu (斜杠命令) */}
      {enableCommands && (
        <CommandMenu
          commands={filteredCommands}
@@ -265,6 +333,19 @@ export function ChatInput({
        />
      )}

+      {/* System Command Menu (系统命令) */}
+      {enableCommands && (
+        <SystemCommandMenu
+          commands={filteredSystemCommands}
+          isOpen={showSystemCommandMenu}
+          selectedIndex={selectedSystemCommandIndex}
+          onSelect={handleSystemCommandSelect}
+          onClose={handleSystemCommandMenuClose}
+          onSelectedIndexChange={setSelectedSystemCommandIndex}
+          isLoading={systemCommandsLoading}
+        />
+      )}
+
      {/* File Menu */}
      {enableFileMention && (
        <FileMenu
@@ -382,6 +463,10 @@ export function ChatInput({
              <kbd className="px-1.5 py-0.5 rounded bg-surface-subtle text-fg-muted font-mono text-[10px]">/</kbd>
              <span>commands</span>
            </span>
+            <span className="flex items-center gap-1">
+              <kbd className="px-1.5 py-0.5 rounded bg-surface-subtle text-fg-muted font-mono text-[10px]">:</kbd>
+              <span>system</span>
+            </span>
            <span className="flex items-center gap-1">
              <kbd className="px-1.5 py-0.5 rounded bg-surface-subtle text-fg-muted font-mono text-[10px]">@</kbd>
              <span>files</span>
@@ -0,0 +1,228 @@
+/**
+ * System Command Menu Component
+ *
+ * 系统命令（: 前缀）选择菜单，支持键盘导航
+ */
+
+import { useEffect, useRef } from 'react';
+import { motion, AnimatePresence } from 'framer-motion';
+import { Settings, Trash2, RefreshCw } from 'lucide-react';
+import clsx from 'clsx';
+
+export interface SystemCommandMenuItem {
+  name: string;
+  description: string;
+  aliases?: string[];
+}
+
+interface SystemCommandMenuProps {
+  /** 命令列表 */
+  commands: SystemCommandMenuItem[];
+  /** 是否显示 */
+  isOpen: boolean;
+  /** 当前选中索引 */
+  selectedIndex: number;
+  /** 选择命令回调 */
+  onSelect: (command: SystemCommandMenuItem) => void;
+  /** 关闭菜单回调 */
+  onClose: () => void;
+  /** 选中索引变化回调 */
+  onSelectedIndexChange: (index: number) => void;
+  /** 是否正在加载 */
+  isLoading?: boolean;
+}
+
+// 根据命令名称获取图标
+function getCommandIcon(name: string) {
+  switch (name) {
+    case 'clear':
+      return <Trash2 size={14} className="text-red-400" />;
+    case 'reload':
+      return <RefreshCw size={14} className="text-blue-400" />;
+    default:
+      return <Settings size={14} className="text-purple-400" />;
+  }
+}
+
+export function SystemCommandMenu({
+  commands,
+  isOpen,
+  selectedIndex,
+  onSelect,
+  onClose,
+  onSelectedIndexChange,
+  isLoading = false,
+}: SystemCommandMenuProps) {
+  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-surface-subtle border border-line rounded-lg shadow-xl overflow-hidden max-h-64 overflow-y-auto">
+            {/* Header */}
+            <div className="px-3 py-2 border-b border-line bg-surface-subtle/80 sticky top-0">
+              <div className="flex items-center gap-2 text-xs text-fg-muted">
+                <Settings size={12} />
+                <span>System Commands</span>
+                {commands.length > 0 && (
+                  <span className="text-fg-subtle">({commands.length})</span>
+                )}
+              </div>
+            </div>
+
+            {/* Loading */}
+            {isLoading && commands.length === 0 && (
+              <div className="px-3 py-4 text-center text-fg-muted text-sm">
+                Loading system commands...
+              </div>
+            )}
+
+            {/* Empty state */}
+            {!isLoading && commands.length === 0 && (
+              <div className="px-3 py-4 text-center text-fg-muted text-sm">
+                No system 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-surface-muted/50'
+                    )}
+                  >
+                    {/* Icon */}
+                    <div className="mt-0.5">{getCommandIcon(command.name)}</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-fg-secondary'
+                          )}
+                        >
+                          :{command.name}
+                        </span>
+                        {command.aliases && command.aliases.length > 0 && (
+                          <span className="text-[10px] text-fg-subtle">
+                            ({command.aliases.map((a) => `:${a}`).join(', ')})
+                          </span>
+                        )}
+                      </div>
+                      {command.description && (
+                        <p className="text-xs text-fg-muted mt-0.5 truncate">
+                          {command.description}
+                        </p>
+                      )}
+                    </div>
+
+                    {/* Keyboard hint */}
+                    {index === selectedIndex && (
+                      <div className="flex items-center gap-1 text-[10px] text-fg-subtle">
+                        <kbd className="px-1 py-0.5 bg-surface-muted rounded">
+                          Enter
+                        </kbd>
+                      </div>
+                    )}
+                  </button>
+                ))}
+              </div>
+            )}
+
+            {/* Footer hint */}
+            <div className="px-3 py-1.5 border-t border-line bg-surface-subtle/80 sticky bottom-0">
+              <div className="flex items-center gap-3 text-[10px] text-fg-subtle">
+                <span>
+                  <kbd className="px-1 py-0.5 bg-surface-muted rounded mr-1">↑</kbd>
+                  <kbd className="px-1 py-0.5 bg-surface-muted rounded">↓</kbd>
+                  {' '}navigate
+                </span>
+                <span>
+                  <kbd className="px-1 py-0.5 bg-surface-muted rounded">Tab</kbd>
+                  {' '}select
+                </span>
+                <span>
+                  <kbd className="px-1 py-0.5 bg-surface-muted rounded">Esc</kbd>
+                  {' '}close
+                </span>
+              </div>
+            </div>
+          </div>
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}
@@ -564,6 +564,33 @@ export function useChat({ sessionId, onError, onSessionNotFound, onSessionUpdate
            }, 1000);
            break;
          }
+
+          // ============ 系统命令结果 ============
+
+          case 'system_command_result': {
+            const payload = message.payload as {
+              success: boolean;
+              message?: string;
+              error?: string;
+              action?: { type: string };
+            };
+
+            // 处理清空消息操作
+            if (payload.success && payload.action?.type === 'clear_messages') {
+              setState((prev) => ({
+                ...prev,
+                messages: [],
+                streamingMessage: null,
+                isLoading: false,
+              }));
+            }
+
+            // 如果有错误，通过 onError 回调通知
+            if (!payload.success && payload.error) {
+              onErrorRef.current?.(new Error(payload.error));
+            }
+            break;
+          }
        }
      } catch {
        // 忽略解析错误
@@ -693,6 +720,23 @@ export function useChat({ sessionId, onError, onSessionNotFound, onSessionUpdate
    [sessionId]
  );

+  // 清空会话消息（系统命令 :clear）
+  const clearMessages = useCallback(() => {
+    if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) {
+      onErrorRef.current?.(new Error('WebSocket not connected'));
+      return;
+    }
+
+    // 发送 :clear 系统命令
+    wsRef.current.send(
+      JSON.stringify({
+        type: 'message',
+        sessionId,
+        payload: { content: ':clear' },
+      })
+    );
+  }, [sessionId]);
+
  // 回答问题（ask_user_question 工具）
  const answerQuestion = useCallback(
    (questionPartId: string, answers: string[]) => {
@@ -813,5 +857,6 @@ export function useChat({ sessionId, onError, onSessionNotFound, onSessionUpdate
    setAgentMode,
    setAutoApprove,
    answerQuestion,
+    clearMessages,
  };
 }
@@ -0,0 +1,112 @@
+/**
+ * System Commands Hook
+ *
+ * 管理系统命令（: 前缀）的加载和过滤
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { listSystemCommands } from '../api/client.js';
+import type { SystemCommandInfo } from '../api/types.js';
+
+interface UseSystemCommandsOptions {
+  /** 是否在挂载时自动加载命令列表 */
+  autoLoad?: boolean;
+}
+
+interface UseSystemCommandsState {
+  /** 所有系统命令列表 */
+  commands: SystemCommandInfo[];
+  /** 过滤后的命令列表 */
+  filteredCommands: SystemCommandInfo[];
+  /** 是否正在加载 */
+  isLoading: boolean;
+  /** 错误信息 */
+  error: string | null;
+}
+
+export function useSystemCommands(options: UseSystemCommandsOptions = {}) {
+  const { autoLoad = true } = options;
+
+  const [state, setState] = useState<UseSystemCommandsState>({
+    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 listSystemCommands();
+      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 system commands',
+        }));
+      }
+    } catch (error) {
+      setState((prev) => ({
+        ...prev,
+        isLoading: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      }));
+    }
+  }, [state.isLoading]);
+
+  // 搜索/过滤系统命令
+  const filterCommands = useCallback(
+    (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) ||
+          cmd.aliases?.some((alias) => alias.toLowerCase().includes(queryLower))
+      );
+
+      setState((prev) => ({
+        ...prev,
+        filteredCommands: localFiltered,
+      }));
+    },
+    [state.commands]
+  );
+
+  // 自动加载
+  useEffect(() => {
+    if (autoLoad && !loadedRef.current) {
+      loadedRef.current = true;
+      loadCommands();
+    }
+  }, [autoLoad, loadCommands]);
+
+  return {
+    ...state,
+    loadCommands,
+    filterCommands,
+  };
+}