cyberseo

name	Поиск и импорт тем CyberSEO
description	Ищет темы для блога CyberSEO по cyberseo.project.yml, строит главные темы и подтемы, проверяет очередь и опубликованные статьи через state.cyberseo, убирает дубли, сохраняет темы в state.topics и по подтверждению импортирует темы через /api/v1/queue/batch.

Поиск и импорт тем CyberSEO

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

Что читать

1. cyberseo.project.yml.
2. Контракт импорта тем.
3. Правила поиска тем.

Отдельный .cyberseo.state.yml не создавать и не использовать.

Как обновлять cyberseo.project.yml

Комментарии в файле нужно сохранять. При записи state.topics, state.import.topics_imported и других полей нельзя пересохранять весь YAML через обычный парсер, потому что он удаляет комментарии.

Правило:

• менять только нужные места в существующем файле;
• использовать apply_patch или точечную замену блока;
• перед заменой большого блока сделать копию файла;
• после правки проверить, что комментарии # остались;
• если комментарии уже исчезли, восстановить шаблонный cyberseo.project.yml из cyberseo-full/assets/cyberseo.project.yml и перенести значения.

Что нужно для работы

Обязательное:

• API CyberSEO и админ-токен в cyberseo.project.yml -> state.cyberseo;
• topics.main_topic;
• topics.country;
• topics.count.

Желательное:

• topics.city;
• topics.language;
• site.blog_description;
• site.about_blog;
• keys.firecrawl_api_key;
• keys.perplexity_api_key.

Если Firecrawl или Perplexity не настроены, не падать. Продолжать тем способом, который доступен.

topics.country означает страну, где ищем спрос. topics.language означает язык ключей и статей. Если topics.language пустой, выбрать язык по стране. Если заполнен, использовать его. Пример: country: Германия, city: Берлин, language: ru — искать темы для русскоязычных людей в Германии.

Порядок работы

1. Прочитать cyberseo.project.yml.
2. Получить текущую очередь:
   • GET /api/v1/queue
3. Получить опубликованные статьи:
   • GET /api/v1/published
4. Использовать реальные данные CyberSEO для ключей и спроса, если API доступен.
5. Если есть Firecrawl, аккуратно посмотреть конкурентов.
6. Собрать главные темы и подтемы.
7. Создать стабильные ID.
8. Убрать дубли.
9. Сохранить результат в cyberseo.project.yml -> state.topics.
10. Показать список пользователю.
11. Импортировать только после подтверждения:

• POST /api/v1/queue/batch

12. После импорта обновить state.import.topics_imported в cyberseo.project.yml.

Не создавать cyberseo.topics.yml, import-rows.json, import-report.md и другие отдельные файлы.

Структура тем

Главная тема:

• topic_role = pillar;
• topic_id равен своему стабильному ID;
• cluster_id равен topic_id;
• parent_topic_id пустой.

Подтема:

• topic_role = support;
• topic_id свой;
• cluster_id равен topic_id главной темы;
• parent_topic_id равен topic_id главной темы.

Правила дублей

Не импортировать тему, если:

• совпал topic_id;
• совпал id;
• такая тема уже есть среди опубликованных;
• совпали main_keyword + country + city и тема явно та же.

Похожие темы не удалять молча. Положить их в отчёт как “возможный дубль”.

Perplexity

Perplexity использовать, если ключ заполнен и пользователь хочет работать через свой баланс Perplexity.

Не представлять Perplexity как обязательный ключ. Если его нет, продолжать через доступные источники CyberSEO.

Выход

В конце дать:

• сколько тем найдено;
• сколько пропущено как дубли;
• сколько не подошло;
• что сохранено в state.topics;
• был ли импорт в очередь.