Документ технического дизайна фазы 1: Рефакторинг инфраструктуры

/**
 * Перечисление режимов выполнения.
 * - interactive: React/Ink UI режим (терминальное взаимодействие)
 * - non_interactive: неинтерактивный CLI режим (текстовый/JSON вывод)
 * - acp: ACP/Zed режим интеграции
 */
export type ExecutionMode = 'interactive' | 'non_interactive' | 'acp';

/**
 * Перечисление источников команд, используется для группировки в Help, значков автодополнения,
 * доступных команд ACP.
 *
 * Отличие от CommandKind:
 * - CommandKind — это внутренняя классификация загрузчиков (4 типа), влияющая на логику загрузки
 * - CommandSource — это ориентированная на пользователя классификация источника (9 типов),
 *   влияющая на отображение и ментальную модель
 *
 * Между ними возможно пересечение, но обязанности разные, не объединять.
 */
export type CommandSource =
  | 'builtin-command' // Встроенная команда (BuiltinCommandLoader)
  | 'bundled-skill' // Навык, распространяемый с пакетом (BundledSkillLoader)
  | 'skill-dir-command' // Команда из пользовательской/проектной директории .qwen/commands/ (FileCommandLoader, не плагин)
  | 'plugin-command' // Команда, предоставленная плагином (FileCommandLoader, extensionName не пуст)
  | 'mcp-prompt'; // Prompt, предоставленный MCP сервером (McpPromptLoader)
// Следующие источники зарезервированы, в фазе 1 не реализуются соответствующие Loader, но схема определена заранее:
// | 'workflow-command'
// | 'plugin-skill'
// | 'dynamic-skill'
// | 'builtin-plugin-skill'
// | 'mcp-skill'

/**
 * Тип выполнения команды, описывает "как выполняется" команда.
 *
 * - prompt: генерирует submit_prompt, отправляет содержимое модели. Подходит для навыков, файловых команд, MCP prompt.
 *   По умолчанию supportedModes — все режимы, modelInvocable по умолчанию true.
 *
 * - local: выполняет логику локально, не зависит от React/Ink UI. Может возвращать message, stream_messages,
 *   submit_prompt, tool и другие типы. Подходит для встроенных команд запроса, конфигурации, состояния.
 *   По умолчанию supportedModes — ['interactive'], необходимо явно объявить supportedModes,
 *   чтобы открыть для других режимов.
 *   Это согласуется с семантикой supportsNonInteractive: true в Claude Code —
 *   поддержка неинтерактивного режима требует явного объявления, а не автоматического вывода.
 *
 * - local-jsx: команды, зависящие от React/Ink UI (открытие диалогов, рендеринг JSX компонентов и т.д.).
 *   По умолчанию supportedModes только ['interactive'].
 */
export type CommandType = 'prompt' | 'local' | 'local-jsx';

export interface SlashCommand {
  // ── Существующие поля (остаются без изменений) ──────────────────────────────
  name: string;
  altNames?: string[];
  description: string;
  hidden?: boolean;
  completionPriority?: number;
  kind: CommandKind;
  extensionName?: string;
  action?: (...) => ...;
  completion?: (...) => ...;
  subCommands?: SlashCommand[];
 
  // ── Новое в фазе 1: источник и тип выполнения ─────────────────────────────
  /**
   * Источник команды, используется для группировки в Help, значков автодополнения,
   * отображения доступных команд ACP.
   * Заполняется каждым Loader, не объявляется самой командой.
   * В будущем, при отказе от CommandKind, source станет единственным идентификатором источника.
   */
  source?: CommandSource;
 
  /**
   * Метка источника для отображения, ориентированная на пользователя.
   * - builtin-command → "Built-in"
   * - bundled-skill → "Skill"
   * - skill-dir-command → "Custom"
   * - plugin-command → "Plugin: <extensionName>"
   * - mcp-prompt → "MCP: <serverName>"
   * Заполняется каждым Loader, может быть переопределено самой командой.
   */
  sourceLabel?: string;
 
  /**
   * Тип выполнения команды.
   * - Заполняется каждым Loader значением по умолчанию (prompt/local-jsx)
   * - Встроенные команды объявляются в каждом файле команды (local или local-jsx)
   * Стратегия по умолчанию при отсутствии объявления описана в getEffectiveCommandType().
   */
  commandType?: CommandType;
 
  // ── Новое в фазе 1: поддержка режимов ──────────────────────────────────────
  /**
   * В каких режимах выполнения доступна эта команда.
   * При отсутствии объявления выводится по commandType (см. getEffectiveSupportedModes()).
   * Явное объявление имеет приоритет над выводом.
   */
  supportedModes?: ExecutionMode[];
 
  // ── Новое в фазе 1: видимость ──────────────────────────────────────────────
  /**
   * Может ли пользователь вызвать эту команду через slash command.
   * По умолчанию true (почти все команды userInvocable).
   */
  userInvocable?: boolean;
 
  /**
   * Может ли модель вызвать эту команду через tool call.
   * По умолчанию false. Команды типа prompt (навыки, файловые команды, MCP prompt) должны быть true.
   * Встроенные команды не разрешают вызов модели (всегда false).
   */
  modelInvocable?: boolean;
 
  // ── Зарезервировано для фазы 3: метаданные опыта (в фазе 1 только определение, не используется) ───
  /**
   * Подсказка по аргументам, отображается после имени команды в меню автодополнения.
   * Пример: "<model-id>" / "show|list|set <id>" / "[--fast] [<model-id>]"
   */
  argumentHint?: string;
 
  /**
   * Пояснение для модели, когда вызывать эту команду.
   * Будет внедрено в description команд с modelInvocable.
   */
  whenToUse?: string;
 
  /**
   * Примеры использования, для отображения в Help и автодополнении.
   */
  examples?: string[];
}

// Не заполняет source/sourceLabel/commandType — объявляются в самих файлах команд
// Потому что commandType встроенных команд — local или local-jsx, требуется маркировка каждой
 
// Внедрение source и sourceLabel:
for (const cmd of rawCommands) {
  enrichedCommands.push({
    ...cmd,
    source: 'builtin-command',
    sourceLabel: 'Built-in',
    userInvocable: cmd.userInvocable ?? true,
    modelInvocable: false, // встроенные команды не разрешают вызов модели
  });
}

return skills.map((skill) => ({
  name: skill.name,
  description: skill.description,
  kind: CommandKind.SKILL,
  source: 'bundled-skill' as CommandSource,
  sourceLabel: 'Skill',
  commandType: 'prompt' as CommandType,
  userInvocable: true,
  modelInvocable: true,
  action: async (...) => { ... },
}));

// В createSlashCommandFromDefinition:
return {
  name: baseCommandName,
  description,
  kind: CommandKind.FILE,
  extensionName,
  // source определяется по extensionName:
  source: extensionName ? 'plugin-command' : 'skill-dir-command',
  sourceLabel: extensionName ? `Plugin: ${extensionName}` : 'Custom',
  commandType: 'prompt',
  userInvocable: true,
  modelInvocable: !extensionName, // команды плагинов пока не разрешают вызов модели, пользовательские/проектные — разрешают
  action: async (...) => { ... },
};

const newPromptCommand: SlashCommand = {
  name: commandName,
  description: prompt.description || `Invoke prompt ${prompt.name}`,
  kind: CommandKind.MCP_PROMPT,
  source: 'mcp-prompt',
  sourceLabel: `MCP: ${serverName}`,
  commandType: 'prompt',
  userInvocable: true,
  modelInvocable: true,
  // ... остальные существующие поля
};

/**
 * Возвращает фактический список поддерживаемых режимов для команды.
 *
 * Приоритет вывода (от высокого к низкому):
 * 1. Явно объявленное supportedModes (наивысший приоритет)
 * 2. Вывод на основе commandType
 * 3. Запасной вариант на основе CommandKind (обратная совместимость)
 */
export function getEffectiveSupportedModes(cmd: SlashCommand): ExecutionMode[] {
  // Приоритет 1: явное объявление
  if (cmd.supportedModes !== undefined) {
    return cmd.supportedModes;
  }
 
  // Приоритет 2: вывод на основе commandType
  if (cmd.commandType !== undefined) {
    switch (cmd.commandType) {
      case 'prompt':
        // Тип prompt не имеет зависимости от UI, доступен во всех режимах по умолчанию
        return ['interactive', 'non_interactive', 'acp'];
      case 'local':
        // Тип local по умолчанию консервативно: только interactive.
        // Команды, требующие неинтерактивной поддержки, должны явно объявить supportedModes
        // (соответствует supportsNonInteractive: true в Claude Code).
        // В фазе 2 каждая команда будет проверена и разблокирована,
        // чтобы предотвратить случайное раскрытие неадаптированных команд headless-вызывающим.
        return ['interactive'];
      case 'local-jsx':
        return ['interactive'];
    }
  }
 
  // Приоритет 3: запасной вариант (на основе CommandKind, для обратной совместимости со старым кодом)
  switch (cmd.kind) {
    case CommandKind.BUILT_IN:
      // Встроенная команда без объявленного commandType консервативно только interactive.
      // После завершения фазы 1 эта ветка не должна достигаться (все встроенные команды будут иметь commandType)
      return ['interactive'];
    case CommandKind.FILE:
    case CommandKind.SKILL:
    case CommandKind.MCP_PROMPT:
      // У этих трёх типов команд action по своей природе не зависит от UI,
      // исторически они были доступны во всех режимах
      return ['interactive', 'non_interactive', 'acp'];
    default:
      return ['interactive'];
  }
}

/**
 * Фильтрует команды по supportedModes для текущего режима.
 * Заменяет исходную функцию filterCommandsForNonInteractive.
 */
export function filterCommandsForMode(
  commands: readonly SlashCommand[],
  mode: ExecutionMode,
): SlashCommand[] {
  return commands.filter((cmd) =>
    getEffectiveSupportedModes(cmd).includes(mode),
  );
}

export class CommandService {
  // ── Существующие методы (остаются без изменений) ────────────────────────────────
  getCommands(): readonly SlashCommand[] {
    return this.commands;
  }
 
  // ── Новые методы фазы 1 ────────────────────────────────────────────────────────
 
  /**
   * Возвращает список команд, доступных в указанном режиме выполнения.
   * Заменяет комбинацию старого белого списка + filterCommandsForNonInteractive.
   *
   * @param mode Целевой режим выполнения
   * @returns Список команд, подходящих для этого режима (без скрытых команд)
   */
  getCommandsForMode(mode: ExecutionMode): readonly SlashCommand[] {
    return this.commands.filter((cmd) => {
      if (cmd.hidden) return false;
      return getEffectiveSupportedModes(cmd).includes(mode);
    });
  }
 
  /**
   * Возвращает все команды, у которых modelInvocable равен true.
   * В фазе 2 SkillTool будет использовать этот метод; в фазе 1 только предоставляется интерфейс.
   *
   * @returns Список команд, которые может вызывать модель
   */
  getModelInvocableCommands(): readonly SlashCommand[] {
    return this.commands.filter(
      (cmd) => !cmd.hidden && cmd.modelInvocable === true,
    );
  }
}

// ❌ Удалить
export const ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE = [
  'init', 'summary', 'compress', 'btw', 'bug', 'context',
] as const;
 
// ❌ Удалить
function filterCommandsForNonInteractive(
  commands: readonly SlashCommand[],
  allowedBuiltinCommandNames: Set<string>,
): SlashCommand[] { ... }

// ✅ Добавить (или импортировать из commandUtils)
import { filterCommandsForMode } from '../services/commandUtils.js';

// ❌ Старая сигнатура
export const handleSlashCommand = async (
  rawQuery: string,
  abortController: AbortController,
  config: Config,
  settings: LoadedSettings,
  allowedBuiltinCommandNames: string[] = [...ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE],
): Promise<NonInteractiveSlashCommandResult>
 
// ✅ Новая сигнатура (удалён параметр allowedBuiltinCommandNames)
export const handleSlashCommand = async (
  rawQuery: string,
  abortController: AbortController,
  config: Config,
  settings: LoadedSettings,
): Promise<NonInteractiveSlashCommandResult>

// Старый код:
const filteredCommands = filterCommandsForNonInteractive(
  allCommands,
  allowedBuiltinSet,
);
 
// Новый код:
const executionMode = isAcpMode ? 'acp' : 'non_interactive';
const filteredCommands = filterCommandsForMode(allCommands, executionMode);

// ❌ Старая сигнатура
export const getAvailableCommands = async (
  config: Config,
  abortSignal: AbortSignal,
  allowedBuiltinCommandNames: string[] = [...ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE],
): Promise<SlashCommand[]>
 
// ✅ Новая сигнатура
export const getAvailableCommands = async (
  config: Config,
  abortSignal: AbortSignal,
  mode: ExecutionMode = 'acp',
): Promise<SlashCommand[]>

// ❌ Старый вызов
const slashCommandResult = await handleSlashCommand(
  inputText,
  abortController,
  this.config,
  this.settings,
  // не передаётся, используется белый список по умолчанию
);
 
// ✅ Новый вызов (без изменений, удалён несуществующий теперь параметр по умолчанию)
const slashCommandResult = await handleSlashCommand(
  inputText,
  abortController,
  this.config,
  this.settings,
);
 
// ─────────────────────────────────────────
 
// ❌ Старый вызов
const slashCommands = await getAvailableCommands(
  this.config,
  abortController.signal,
);
 
// ✅ Новый вызов (явно указан mode)
const slashCommands = await getAvailableCommands(
  this.config,
  abortController.signal,
  'acp',
);

// ① Версия для интерактивного режима: local-jsx, только interactive
export const modelCommandInteractive: SlashCommand = {
  name: 'model',
  kind: CommandKind.BUILT_IN,
  commandType: 'local-jsx',
  supportedModes: ['interactive'], // явное ограничение
  // action: открывает диалог выбора модели
};
 
// ② Версия для неинтерактивного/acp: local, явно открыт для headless-вызовов
export const modelCommandHeadless: SlashCommand = {
  name: 'model',
  kind: CommandKind.BUILT_IN,
  commandType: 'local',
  supportedModes: ['non_interactive', 'acp'], // явное ограничение
  // action: читает/устанавливает модель, возвращает сообщение (простой текст)
};

describe('getEffectiveSupportedModes', () => {
  it('явное supportedModes имеет приоритет над выводом из commandType', () => {
    const cmd: SlashCommand = {
      name: 'test', description: '', kind: CommandKind.BUILT_IN,
      commandType: 'local',
      supportedModes: ['interactive'], // явное ограничение
    };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType: local выводится как все режимы', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN, commandType: 'local' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
 
  it('commandType: local-jsx выводится только как interactive', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN, commandType: 'local-jsx' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType: prompt выводится как все режимы', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.SKILL, commandType: 'prompt' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
 
  it('не указан commandType и CommandKind.BUILT_IN, fallback interactive', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('не указан commandType и CommandKind.FILE, fallback все режимы', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.FILE };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
 
  it('не указан commandType и CommandKind.MCP_PROMPT, fallback все режимы (исправление старого ограничения)', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.MCP_PROMPT };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
});
 
describe('filterCommandsForMode', () => {
  it('правильно фильтрует команды в режиме non_interactive', () => { ... });
  it('правильно фильтрует команды в режиме acp', () => { ... });
  it('не фильтрует скрытые команды (filterCommandsForMode не обрабатывает hidden, этим занимается CommandService)', () => { ... });
});