План рефакторинга модуля Qwen Code Command

1. Определение целей

Данный план основан на единственном принципе:

• Архитектура кода может не копировать Claude Code
• Но основные функции, пользовательский опыт и взаимодействие с системой команд должны быть на 95% выровнены с Claude Code

Под “выравниванием” здесь понимаются возможность, непосредственно воспринимаемая пользователем, включая:

1. Охват источников команд
2. Справка и обнаруживаемость команд
3. Автодополнение команд и опыт использования slash-команд в середине ввода
4. Доступность в ACP / non-interactive режимах
5. Возможность вызова prompt command / skill моделью

Данный рефакторинг — это не добавление нескольких полей и не мелкий ремонт существующего SlashCommand, а повышение модуля команд с “вспомогательной возможности интерактивного UI” до “унифицированной платформы команд, работающей поверх interactive / ACP / non-interactive / model”.

2. Выводы после переосмысления

Проблемы текущей системы команд Qwen заключаются не в полном отсутствии возможностей, а в следующем:

1. Относительная полнота только на основном пути interactive
2. Модель типов слишком “тонкая”, чтобы выдержать уровень продукта Claude
3. ACP / non-interactive зависят от белого списка, что крайне плохо для расширяемости
4. Источники команд хоть и существуют, но не формируют единого, видимого пользователю ментального представления
5. Prompt command и система раскрытия skill модели разрознены

Поэтому новый план должен одновременно решить четыре задачи:

1. Дополнить возможности Claude Code
2. Сохранить инженерные преимущества унифицированной outcome-модели Qwen
3. Создать унифицированную архитектуру registry / resolver / executor / adapter
4. Заставить справку, автодополнение, ACP available commands и документацию использовать один и тот же набор метаданных

3. Принципы рефакторинга

3.1 Приоритет функционального выравнивания над реализационным

Допускаются различия в:

• Внутренних именах классов
• Способах разделения модулей
• Реализации исполнителя
• Структуре effect / outcome

Не допускаются различия, при которых:

• Заметно ухудшается охват источников команд
• Заметно ухудшается справка и автодополнение команд
• Заметно ухудшается доступность в ACP / non-interactive
• Заметно ухудшается интеграция prompt command с возможностями модели

При возникновении компромиссов приоритет должен быть следующим:

1. Выравнивание пользовательского опыта
2. Выравнивание охвата возможностей команд
3. Выравнивание согласованности режимов
4. Простота внутренней реализации

3.2 Сохранение унифицированной outcome-модели Qwen

Механическое копирование реализации выполнения Claude не рекомендуется.

Текущая унифицированная модель результатов Qwen все еще заслуживает сохранения, поскольку она естественно подходит для:

• Перехвата управления UI
• Утверждения/подтверждения
• Диспетчеризации tool
• Отправки prompt
• Адаптации между режимами

Но она должна быть модернизирована, чтобы нести возможности уровня команд Claude, а не продолжать существовать как упрощенный фреймворк команд для UI.

3.3 Типы, источники, режимы и видимость должны быть полностью развязаны

Новая модель команд как минимум должна разделить следующие измерения:

1. Тип: как выполняется команда
2. Источник: откуда берется команда
3. Возможности режима: в каких средах выполнения доступна
4. Видимость: видна пользователю или видна модели

4. Возможности Claude Code, которые необходимо выровнять

4.1 Типы команд

Qwen должна явно поддерживать три типа команд:

1. prompt
2. local
3. local-jsx

4.2 Источники команд

Схема команды Qwen должна охватывать следующие источники, начиная с первой фазы:

1. built-in commands
2. bundled skills
3. skill dir commands
4. workflow commands
5. plugin commands
6. plugin skills
7. dynamic skills
8. mcp prompts
9. mcp skills

Здесь больше нельзя отступать к “сначала поддерживать только те типы, которые уже есть”.

4.3 Метаданные команд

Как минимум дополнить следующими полями:

1. argumentHint
2. whenToUse
3. examples
4. sourceLabel
5. userFacingName
6. alias
7. immediate
8. isSensitive
9. userInvocable
10. modelInvocable
11. supportedModes
12. requiresUi

4.4 Возможности взаимодействия

Как минимум дополнить следующими возможностями:

1. Автодополнение по псевдониму (alias)
2. Значок источника (source badge)
3. Подсказки по аргументам
4. Сортировка по недавно использованным
5. Обнаружение и автодополнение slash-команд в середине ввода
6. Справка в виде каталога команд
7. Полное представление ACP available commands

5. Новая модель команд

5.1 Основная структура

Рекомендуется ввести единый CommandDescriptor в качестве формата регистрации для всех команд.

Он должен содержать как минимум четыре части:

1. identity
2. metadata
3. capabilities
4. handler

identity

• id
• name
• altNames
• canonicalPath

metadata

• description
• argumentHint
• whenToUse
• examples
• group
• source
• sourceLabel
• userFacingName
• hidden

capabilities

• type: prompt | local | local-jsx
• supportedModes: interactive | acp | non_interactive
• requiresUi
• supportsDialog
• supportsStreaming
• supportsToolInvocation
• supportsConfirmation
• remoteSafe
• readOnly
• immediate
• isSensitive
• userInvocable
• modelInvocable

handler

• resolveArgs()
• execute()
• completion()
• fallback()

5.2 Обязанности трех типов команд

prompt

Используется для:

• skills
• file commands
• workflow prompt commands
• plugin skills
• mcp prompt / skill

Характеристики:

• Создает ресурсы prompt / skill
• По умолчанию поддерживает interactive / ACP / non-interactive
• Может вызываться пользователем или моделью

local

Используется для:

• Команд запросов
• Команд конфигурации
• Команд состояния, выполнимых в headless режиме
• Основной точки входа выполнения для большинства built-in commands

Характеристики:

• Не зависит от UI
• Должен стать основным承载ющим типом для ACP / non-interactive

local-jsx

Используется для:

• picker
• панелей
• wizard
• интерактивных UI оболочек (shell)

Характеристики:

• Обрабатывает только interactive UI
• Больше не может быть единственной точкой входа
• Должен предоставлять fallback или соответствующую local подкоманду

6. Модель источников команд

6.1 Модель внешних источников

Это модель источников, видимая пользователю, и она должна максимально соответствовать ментальной модели Claude Code:

• builtin-command
• bundled-skill
• skill-dir-command
• workflow-command
• plugin-command
• plugin-skill
• dynamic-skill
• builtin-plugin-skill
• mcp-prompt
• mcp-skill

Этот набор полей будет напрямую использоваться для:

• Группировки в справке
• Значка источника в автодополнении
• ACP available commands
• Экспорта документации

6.2 Модель внутренней нормализации

Чтобы не быть жестко привязанными к внешним именам, добавляем внутренний слой полей реализации:

• providerType
• artifactType
• activationMode
• builtinProvided
• originPath
• namespace

Это позволит достичь:

• Внешний опыт выровнен по Claude
• Внутренняя реализация сохраняет поддерживаемость Qwen

6.3 Стратегия разрешения конфликтов

Унифицированное управление по стабильному id, разделение отображаемого имени и имени для ввода:

1. id: стабильный уникальный идентификатор
2. name: основное имя для ввода
3. userFacingName: отображаемое имя в справке/автодополнении

Рекомендуемый приоритет при конфликтах:

1. built-in
2. bundled / skill-dir / workflow
3. plugin / builtin-plugin
4. dynamic
5. mcp, отдельное пространство имен

7. Унифицированная архитектура выполнения

7.1 CommandRegistry

Обязанности:

1. Агрегировать все загрузчики/провайдеры
2. Строить многомерные индексы
3. Предоставлять представления для справки, автодополнения, ACP и документации
4. Предоставлять отдельные представления для команд, видимых пользователю, и команд, видимых модели

Обязательно поддерживаемые провайдеры:

1. BuiltinCommandLoader
2. BundledSkillLoader
3. FileCommandLoader
4. McpPromptLoader
5. WorkflowCommandLoader
6. PluginCommandLoader
7. PluginSkillLoader
8. DynamicSkillProvider
9. BuiltinPluginSkillLoader

Даже если некоторые провайдеры не будут полностью реализованы в первом выпуске, схема и API должны их поддерживать заранее.

7.2 CommandResolver

Обязанности:

1. Разрешать slash command
2. Разрешать alias
3. Разрешать путь подкоманды
4. Распознавать slash-токен в середине ввода
5. Выдавать каноническую разрешенную команду

7.3 CommandExecutor

Обязанности:

1. Выполнять проверку возможностей (capability check)
2. Выполнять prompt | local | local-jsx
3. Унифицированно создавать outcome
4. Обрабатывать fallback / unsupported

7.4 ModeAdapter

Необходимо выделить три типа адаптеров:

1. InteractiveModeAdapter
2. AcpModeAdapter
3. NonInteractiveModeAdapter

Только так три режима смогут использовать один и тот же registry и executor команд, а не каждый свою жестко закодированную логику.

8. Принципы рефакторинга UI-команд: разделение основных команд и интерактивной оболочки

Это ключ к реальной работоспособности ACP и non-interactive.

Все команды, которые по своей сути являются “открыть диалог”, должны быть преобразованы в:

1. Интерактивную оболочку (interactive shell)
2. Набор local подкоманд

Первая партия команд, подлежащих разделению

1. /model
2. /permissions
3. /mcp
4. /resume
5. /hooks
6. /extensions
7. /agents
8. /approval-mode

Пример целевой формы

/model

• /model
• /model show
• /model list
• /model set <id>

/permissions

• /permissions
• /permissions show
• /permissions set <mode>
• /permissions allow <tool>
• /permissions deny <tool>

/mcp

• /mcp
• /mcp list
• /mcp show <server>
• /mcp enable <server>
• /mcp disable <server>

9. Унифицированный дизайн Prompt Command / Skill

Это P0 (приоритет высшего уровня) в рефакторинге, а не отложенная возможность.

9.1 Цель

Создать унифицированный Model-Invocable Prompt Command Registry, который объединяет следующие ресурсы в единое представление, вызываемое моделью:

1. bundled skills
2. file commands
3. workflow prompt commands
4. plugin skills
5. mcp prompts / mcp skills

9.2 Ключевые поля

Необходимо добавить:

1. userInvocable
2. modelInvocable
3. allowedTools
4. whenToUse
5. argSchema или минимальное описание аргументов
6. contextMode: inline | fork
7. agent
8. effort

9.3 Отношение к SkillTool

После рефакторинга SkillTool больше не должен потреблять только узкие skills.

Вместо этого следует:

1. CommandRegistry.getModelInvocablePromptCommands() создает унифицированное представление
2. SkillTool или будущий унифицированный command tool потребляет это представление
3. Пользовательские slash-команды и вызовы skill моделью используют один и тот же пул ресурсов prompt-command

Только так Qwen сможет приблизиться по опыту к тому, как Claude обрабатывает такие возможности как /review, /commit, /openspec-apply.

10. Переработка Help / Completion / Discoverability

10.1 Completion

Элемент автодополнения как минимум должен отображать:

1. label
2. description
3. argumentHint
4. sourceBadge
5. modeBadges
6. aliasHit
7. recentlyUsedScore

Сортировка как минимум должна учитывать:

1. Точное совпадение
2. Совпадение по alias
3. Недавнее использование
4. Совпадение по префиксу
5. Нечеткое совпадение (fuzzy)

10.2 Mid-input slash command

Необходимо дополнить:

1. Обнаружение slash-токена рядом с курсором
2. Подсказка ghost text
3. Завершение по Tab
4. Подсветка валидных токенов команд

На первом этапе достаточно выровнять опыт ввода; можно ли внедрить более сильную “семантику встроенного выполнения команд” — решать на последующих итерациях.

10.3 Help

Справка больше не является плоским списком, а представляет собой полный каталог команд.

Как минимум группировать по:

1. Built-in Commands
2. Bundled Skills
3. Skill Dir Commands
4. Workflow Commands
5. Plugin Commands
6. Plugin Skills
7. Dynamic Skills
8. Builtin Plugin Skills
9. MCP Commands / MCP Skills

Каждая команда как минимум отображает:

1. Имя
2. Подсказку по аргументам
3. Описание
4. Источник
5. Поддерживаемые режимы
6. Возможность вызова моделью
7. Краткое описание подкоманд

11. Рефакторинг ACP / Non-Interactive

11.1 Полный отказ от подхода “белого списка”

Старый план:

• built-in allowlist
• Особые случаи для FILE / SKILL
• Остальные типы результатов — unsupported

Новый план:

• Каждая команда сама объявляет свои возможности (capability)
• Registry отвечает за фильтрацию
• Adapter отвечает за выполнение и fallback

11.2 Целевая поддержка outcome

interactive

• submit_prompt
• message
• stream_messages
• tool
• dialog
• load_history
• confirm_action
• confirm_shell_commands

acp

• submit_prompt
• message
• stream_messages
• tool
• confirm_action
• confirm_shell_commands
• dialog fallback

non_interactive

• submit_prompt
• message
• stream_messages
• tool
• confirm_action
• confirm_shell_commands
• dialog fallback / structured failure

11.3 Вывод ACP available commands

Как минимум должен содержать:

1. name
2. description
3. argumentHint
4. source
5. examples
6. supportedModes
7. interactiveOnly
8. subcommands
9. modelInvocable

12. Документация, справка и автодополнение используют один и тот же набор метаданных

После рефакторинга следующее должно экспортироваться из одного и того же представления registry:

1. Справка
2. Автодополнение
3. ACP available commands
4. Экспорт документации

Это необходимо для решения текущей проблемы несоответствия между “реализацией, справкой и документацией” для набора команд.

13. Этапы внедрения

Phase 1: Перестройка фундамента

Результат:

1. Новый CommandDescriptor
2. Полная схема источников
3. Модель возможностей (capability)
4. userInvocable / modelInvocable
5. CommandRegistry
6. CommandResolver
7. CommandExecutor
8. Три типа ModeAdapter
9. getModelInvocablePromptCommands()

Phase 2: Миграция основных команд

Результат:

1. /model
2. /permissions
3. /mcp
4. /resume
5. /hooks
6. /extensions
7. /agents
8. /approval-mode

Все эти команды должны пройти рефакторинг “interactive shell + local подкоманды”.

Phase 3: Интеграция возможностей модели

Результат:

1. SkillTool подключается к унифицированному представлению registry
2. file command / bundled skill / mcp prompt / plugin skill попадают в единый набор model-invocable
3. prompt command и ресурсы skill полностью унифицированы

Phase 4: Выравнивание пользовательского опыта с Claude

Результат:

1. Сортировка по недавно использованным
2. Значок источника (source badge)
3. Подсказка по аргументам
4. Значок режима (mode badge)
5. Полный каталог справки
6. Опыт использования slash-команд в середине ввода
7. Автоматический экспорт или проверка документации

14. Критерии приемки

После завершения должно быть выполнено как минимум:

1. Справка, автодополнение, ACP и документация могут отражать полную модель источников
2. За исключением чистых UI-оболочек, большинство built-in command доступны в ACP / non-interactive
3. Prompt command и вызовы skill моделью используют один и тот же пул ресурсов
4. Пользовательский опыт работы с командами (справка, автодополнение, отображение источника, подсказки по аргументам, опыт mid-input) достигает 95% уровня Claude Code
5. Больше нет зависимости от built-in allowlist для поддержки команд в ACP / non-interactive

15. Итоговое заключение

Суть данного рефакторинга — не “добавить несколько полей в существующий SlashCommand”, а:

• Используя внутренний архитектурный стиль Qwen, предоставить платформу команд, которая на 95% выровнена по внешнему опыту с Claude Code

Если необходимо выбирать из двух вариантов:

• Внутренняя реализация больше похожа на Claude
• Внешний опыт больше похож на Claude

Данный план однозначно выбирает последнее.