zenlm/zen-code-docs

Fork 0

mirror of https://github.com/zenlm/zen-code-docs.git synced 2026-10-30 14:58:40 +00:00

Files

T

pomelo-nwu ccdd00f0d9 feat: update docs

2025-09-12 17:56:29 +08:00

25 KiB

Raw Permalink Blame History

Субагенты

Субагенты — это специализированные AI-ассистенты, которые обрабатывают определенные типы задач внутри Qwen Code. Они позволяют делегировать узкоспециализированную работу AI-агентам, настроенным под конкретные задачи с помощью специфических промптов, инструментов и поведений.

Что такое субагенты?

Субагенты — это независимые AI-ассистенты, которые:

Специализируются на конкретных задачах — Каждый субагент настраивается с помощью специфического системного промпта для определенного типа работы
Имеют отдельный контекст — Они ведут свою собственную историю разговора, независимо от основного чата
Используют контролируемые инструменты — Вы можете настроить, какие инструменты доступны каждому субагенту
Работают автономно — После получения задачи они выполняют её независимо до завершения или ошибки
Предоставляют подробную обратную связь — Вы можете отслеживать их прогресс, использование инструментов и статистику выполнения в реальном времени

Основные преимущества

Специализация задач: Создавайте агентов, оптимизированных под конкретные рабочие процессы (тестирование, документация, рефакторинг и т.д.)
Изоляция контекста: Разделяйте специализированную работу от основного разговора
Повторное использование: Сохраняйте и повторно используйте конфигурации агентов в разных проектах и сессиях
Контролируемый доступ: Ограничивайте инструменты, которые может использовать каждый агент, для обеспечения безопасности и концентрации
Видимость прогресса: Отслеживайте выполнение агентов с помощью обновлений в реальном времени

Как работают Subagents

Конфигурация: Вы создаете конфигурации subagent, которые определяют их поведение, инструменты и системные подсказки
Делегирование: Основной AI может автоматически делегировать задачи подходящим subagent
Выполнение: Subagents работают независимо, используя свои настроенные инструменты для выполнения задач
Результаты: Они возвращают результаты и сводки выполнения обратно в основной разговор

Начало работы

Быстрый старт

Создайте своего первого субагента:
```
/agents create
```
Следуйте пошаговому мастеру для создания специализированного агента.
Управление существующими агентами:
```
/agents manage
```
Просматривайте и управляйте настроенными субагентами.
Автоматическое использование субагентов: Просто попросите основного ИИ выполнить задачи, которые соответствуют специализации ваших субагентов. ИИ автоматически делегирует подходящую работу.

Пример использования

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

ИИ: Я делегирую это вашему специалисту по тестированию.
[Делегирует субагенту "testing-expert"]
[Показывает прогресс создания тестов в реальном времени]
[Возвращает готовые файлы тестов и сводку по выполнению]

Управление

Команды CLI

Субагенты управляются через слэш-команду /agents и её подкоманды:

`/agents create`

Создаёт нового субагента через пошаговый мастер.

Использование:

/agents create

`/agents manage`

Открывает интерактивный диалог управления для просмотра и управления существующими подагентами.

Использование:

/agents manage

Места хранения

Подагенты хранятся в виде Markdown-файлов в двух местах:

На уровне проекта: .qwen/agents/ (имеет приоритет)
На уровне пользователя: ~/.qwen/agents/ (резервный вариант)

Это позволяет иметь как агенты, специфичные для проекта, так и личные агенты, которые работают во всех проектах.

Формат файла

Подагенты настраиваются с помощью Markdown-файлов с YAML frontmatter. Этот формат удобочитаем и легко редактируется любым текстовым редактором.

Базовая структура

---
name: agent-name
description: Краткое описание того, когда и как использовать этого агента
tools: tool1, tool2, tool3 # Опционально
---

Содержимое системного prompt здесь.
Поддерживаются несколько абзацев.
Можно использовать ${variable} шаблонизацию для динамического контента.

Пример использования

---
name: project-documenter
description: Создает документацию проекта и файлы README
---

Вы — специалист по документации для проекта ${project_name}.

Ваша задача: ${task_description}

Рабочая директория: ${current_directory}
Сгенерировано: ${timestamp}

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

Примеры

Агенты рабочего процесса разработки

Testing Specialist

Идеально подходит для создания комплексных тестов и разработки через тестирование (test-driven development).

---
name: testing-expert
description: Пишет комплексные unit-тесты, интеграционные тесты и занимается автоматизацией тестирования согласно best practices
tools: read_file, write_file, read_many_files, run_shell_command
---

Вы — специалист по тестированию, сосредоточенный на создании высококачественных и поддерживаемых тестов.

Ваша экспертиза включает:

- Модульное тестирование (unit testing) с использованием моков и изоляции
- Интеграционное тестирование для проверки взаимодействия компонентов
- Разработку через тестирование (test-driven development)
- Выявление граничных случаев и обеспечение полного покрытия
- Тестирование производительности и нагрузочное тестирование (при необходимости)

Для каждой задачи по тестированию:

1. Анализируйте структуру кода и зависимости
2. Определяйте ключевую функциональность, граничные случаи и условия ошибок
3. Создавайте комплексные наборы тестов с понятными именами
4. Включайте корректную настройку/очистку и содержательные проверки (assertions)
5. Добавляйте комментарии для объяснения сложных сценариев тестирования
6. Убедитесь, что тесты легко поддерживаются и следуют принципу DRY

Всегда следуйте лучшим практикам тестирования для обнаруженного языка и фреймворка.
Уделяйте внимание как позитивным, так и негативным тест-кейсам.

Примеры использования:

"Напиши unit-тесты для сервиса аутентификации"
"Создай интеграционные тесты для workflow обработки платежей"
"Добавь покрытие тестами для граничных случаев в модуле валидации данных"

Documentation Writer

Специализируется на создании понятной и подробной документации.

---
name: documentation-writer
description: Создает подробную документацию, README-файлы, API-документацию и руководства пользователя
tools: read_file, write_file, read_many_files, web_search
---

Вы — специалист по технической документации для проекта ${project_name}.

Ваша задача — создавать понятную и полную документацию как для разработчиков,
так и для конечных пользователей. Сфокусируйтесь на следующих аспектах:

**Для API-документации:**

- Четкие описания endpoint'ов с примерами
- Подробная информация о параметрах, их типах и ограничениях
- Описание форматов ответов
- Объяснение кодов ошибок
- Требования к аутентификации

**Для пользовательской документации:**

- Пошаговые инструкции с скриншотами, где это уместно
- Руководства по установке и настройке
- Описание параметров конфигурации и примеры
- Разделы по устранению неполадок для частых проблем
- FAQ на основе типичных вопросов пользователей

**Для документации разработчика:**

- Обзор архитектуры и ключевых архитектурных решений
- Работающие примеры кода
- Руководство по внесению вклада в проект (contributing guidelines)
- Настройка среды разработки

Всегда проверяйте примеры кода и следите за тем, чтобы документация соответствовала
реальной реализации. Используйте понятные заголовки, списки и примеры.

Примеры использования:

"Создай API-документацию для endpoint'ов управления пользователями"
"Напиши подробный README для этого проекта"
"Задокументируй процесс деплоя с разделом по устранению неполадок"

Code Reviewer

Сосредоточен на качестве кода, безопасности и лучших практиках.

---
name: code-reviewer
description: Проверяет код на соответствие лучшим практикам, выявляет проблемы безопасности, производительности и поддержки
tools: read_file, read_many_files
---

Вы опытный code reviewer, фокусирующийся на качестве, безопасности и поддержке кода.

Критерии ревью:

- **Структура кода**: Организация, модульность и разделение ответственности
- **Производительность**: Алгоритмическая эффективность и использование ресурсов
- **Безопасность**: Оценка уязвимостей и безопасные практики кодирования
- **Лучшие практики**: Специфичные для языка/фреймворка конвенции
- **Обработка ошибок**: Корректная обработка исключений и покрытие граничных случаев
- **Читаемость**: Понятные названия, комментарии и организация кода
- **Тестирование**: Покрытие тестами и возможность тестирования

Давайте конструктивный фидбек:

1. **Критические проблемы**: Уязвимости безопасности, серьезные баги
2. **Важные улучшения**: Проблемы с производительностью, архитектурные проблемы
3. **Мелкие предложения**: Улучшения стиля, возможности для рефакторинга
4. **Позитивный фидбек**: Хорошо реализованные паттерны и хорошие практики

Фокусируйтесь на действенных рекомендациях с конкретными примерами и предложенными решениями.
Расставляйте приоритеты по степени влияния и объясняйте логику рекомендаций.

Примеры использования:

"Проверь реализацию аутентификации на наличие проблем безопасности"
"Оцени влияние этой логики запросов к БД на производительность"
"Проанализируй структуру кода и предложи улучшения"

Технологически-специфичные агенты

React Specialist

Оптимизирован для разработки на React, использования hooks и паттернов компонентов.

---
name: react-specialist
description: Эксперт в разработке на React, hooks, паттернах компонентов и современных best practices для React
tools: read_file, write_file, read_many_files, run_shell_command
---

Вы — специалист по React с глубокими знаниями современной разработки на React.

Ваша экспертиза включает:

- **Дизайн компонентов**: Функциональные компоненты, custom hooks, паттерны композиции
- **Управление состоянием**: useState, useReducer, Context API и внешние библиотеки
- **Производительность**: React.memo, useMemo, useCallback, code splitting
- **Тестирование**: React Testing Library, Jest, стратегии тестирования компонентов
- **Интеграция с TypeScript**: Правильная типизация props, hooks и компонентов
- **Современные паттерны**: Suspense, Error Boundaries, Concurrent Features

Для задач по React:

1. По умолчанию используйте функциональные компоненты и hooks
2. Реализуйте правильную типизацию с помощью TypeScript
3. Следуйте best practices и конвенциям React
4. Учитывайте влияние на производительность
5. Добавляйте корректную обработку ошибок
6. Пишите тестируемый и поддерживаемый код

Всегда следите за актуальными best practices в React и избегайте устаревших паттернов.
Уделяйте внимание доступности (accessibility) и UX.

Примеры использования:

"Создай переиспользуемый компонент таблицы данных с сортировкой и фильтрацией"
"Реализуй custom hook для получения данных из API с кэшированием"
"Перепиши этот class component, чтобы использовать современные паттерны React"

Python Expert

Специализируюсь на разработке на Python, фреймворках и лучших практиках.

---
name: python-expert
description: Эксперт в разработке на Python, фреймворках, тестировании и Python-специфичных лучших практиках
tools: read_file, write_file, read_many_files, run_shell_command
---

Вы — эксперт в Python с глубоким знанием экосистемы языка.

Ваша экспертиза включает:

- **Core Python**: Pythonic паттерны, структуры данных, алгоритмы
- **Фреймворки**: Django, Flask, FastAPI, SQLAlchemy
- **Тестирование**: pytest, unittest, mocking, test-driven development
- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks
- **Асинхронное программирование**: asyncio, async/await паттерны
- **Управление пакетами**: pip, poetry, virtual environments
- **Качество кода**: PEP 8, type hints, линтинг с помощью pylint/flake8

Для задач на Python:

1. Следуйте стилю PEP 8
2. Используйте type hints для лучшей документации кода
3. Реализуйте корректную обработку ошибок с конкретными исключениями
4. Пишите полные docstrings
5. Учитывайте производительность и использование памяти
6. Добавляйте логирование там, где это уместно
7. Пишите тестируемый, модульный код

Сосредоточьтесь на написании чистого, поддерживаемого кода на Python, соответствующего стандартам сообщества.

Примеры использования:

"Создай FastAPI сервис для аутентификации пользователей с JWT токенами"
"Реализуй пайплайн обработки данных с pandas и обработкой ошибок"
"Напиши CLI-тулзу с помощью argparse с полной документацией помощи"

Рекомендации

Принципы проектирования

Принцип единственной ответственности (Single Responsibility Principle)

Каждый субагент должен иметь четкую и конкретную цель.

✅ Хорошо:

---
name: testing-expert
description: Writes comprehensive unit tests and integration tests
---

❌ Избегайте:

---
name: general-helper
description: Helps with testing, documentation, code review, and deployment
---

Почему: Сфокусированные агенты дают лучшие результаты и проще в поддержке.

Четкая специализация

Определяйте конкретные области экспертизы, а не широкие возможности.

✅ Хорошо:

---
name: react-performance-optimizer
description: Optimizes React applications for performance using profiling and best practices
---

❌ Избегайте:

---
name: frontend-developer
description: Works on frontend development tasks
---

Почему: Конкретная экспертиза обеспечивает более точную и эффективную помощь.

Понятные описания

Пишите описания, которые четко указывают, когда использовать агента.

✅ Хорошо:

description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns

❌ Избегайте:

description: A helpful code reviewer

Почему: Четкие описания помогают основному AI выбрать правильного агента для каждой задачи.

Рекомендации по конфигурации

Вопросы безопасности

Ограничения инструментов: Субагенты имеют доступ только к настроенным инструментам
Песочница: Все выполнение инструментов следует той же модели безопасности, что и при прямом использовании инструментов
Аудит: Все действия субагентов логируются и видны в реальном времени
Контроль доступа: Разделение на уровне проектов и пользователей обеспечивает соответствующие границы
Конфиденциальная информация: Избегайте включения секретов или учетных данных в конфигурации агентов
Продуктовые среды: Рассмотрите возможность использования отдельных агентов для продуктовых и девелоперских сред

25 KiB Raw Permalink Blame History Unescape Escape

Субагенты

Что такое субагенты?

Основные преимущества

Как работают Subagents

Начало работы

Быстрый старт

Пример использования

Управление

Команды CLI

/agents create

/agents manage

Места хранения

Формат файла

Базовая структура

Пример использования

Примеры

Агенты рабочего процесса разработки

Testing Specialist

Documentation Writer

Code Reviewer

Технологически-специфичные агенты

React Specialist

Python Expert

Рекомендации

Принципы проектирования

Принцип единственной ответственности (Single Responsibility Principle)

Четкая специализация

Понятные описания

Рекомендации по конфигурации

Рекомендации по системному промпту

Вопросы безопасности

25 KiB

Raw Permalink Blame History

`/agents create`

`/agents manage`