Справочник на способности
Способностите са атомарните действия, които Gratis AI Agent може да изпълнява в вашата инсталация на WordPress. Всяка способност е регистриран PHP клас, който излага JSON схема — агентът четенето тази схема по време на работа за да разбере какви параметри са необходими и какво връща способността.
Тази страница документира всички способности, включени в Gratis AI Agent v1.9.0.
Custom Post Types (Потребителски типове съдържание)
Тези способности управляват потребителските типове съдържание (CPT), регистрирани чрез агента. Регистрациите се запазват в таблицата за опции на WordPress, така че остават дори след деактивиране и реактивиране на плагината.
register_post_type
Регистрира нов потребителски тип съдържание.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
slug | string | Да | Ключът за тип пост (максимум 20 символа, без заглавни букви и интервали) |
singular_label | string | Да | Чешно име на един елемент, например Portfolio Item |
plural_label | string | Да | Чешно име на множество елементи, например Portfolio Items |
public | boolean | Не | Дали тип постът е публично достъпен. Дефолт true |
supports | array | Не | Функциите, които поддържа: title, editor, thumbnail, excerpt, comments, revisions, custom-fields. Дефолт ["title","editor"] |
has_archive | boolean | Не | Дали е включена страница за архив на типа пост. Дефолт false |
menu_icon | string | Не | Клас на Dashicons или URL за иконата в административния меню. Дефолт "dashicons-admin-post" |
rewrite_slug | string | Не | URL slug за типа пост. Дефолт е slug |
Пример
{
"slug": "portfolio",
"singular_label": "Portfolio Item",
"plural_label": "Portfolio Items",
"public": true,
"supports": ["title", "editor", "thumbnail"],
"has_archive": true,
"menu_icon": "dashicons-portfolio"
}
Връщане { "success": true, "slug": "portfolio" }
list_post_types
Връща всички нестандартни типове пост, регистрирани от агента.
Параметри — няма
Връщане
{
"post_types": [
{
"slug": "portfolio",
"singular_label": "Portfolio Item",
"plural_label": "Portfolio Items",
"public": true
}
]
}
delete_post_type
Премахва кастомния тип пост, който е бил регистриран от агента. Съществуващите постове от този тип остават в база данни, но вече не са достъпни чрез неговия тип пост.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
slug | string | Да | Ключът на типа пост, който трябва да бъде премахнат |
Връщане { "success": true, "slug": "portfolio" }
Кастомни таксономии (Custom Taxonomies)
Тези функции управляват кастомните таксономии. Подобно на CPT-тата, регистрирането на таксономии се запазва в базата данни.
register_taxonomy
Регистрира нова кастомна таксономия.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
slug | string | Да | Ключът на таксономията (максимум 32 знака) |
singular_label | string | Да | Четово име за един елемент, например Категория на проект |
plural_label | string | Да | Множествено име за елементи, например Категории на проекти |
post_types | array | Да | Слаговете на типове пост към които трябва да бъде прикрепена тази так сономия |
hierarchical | boolean | Не | true за стил на категории (категорийни), false за стил на тагове. Дефолтът е true |
public | boolean | Не | Дали термите са публично достъпни. Дефолтът е true |
rewrite_slug | string | Не | URL слаг за таксономията. По подразбиране е slug |
Пример
{
"slug": "project-category",
"singular_label": "Project Category",
"plural_label": "Project Categories",
"post_types": ["portfolio"],
"hierarchical": true
}
Връщане { "success": true, "slug": "project-category" }
list_taxonomies
Връща всички кастомни таксономии, регистрирани от агента.
Параметри — лични
Връщане
{
"taxonomies": [
{
"slug": "project-category",
"singular_label": "Категория на проект",
"post_types": ["portfolio"],
"hierarchical": true
}
]
}
delete_taxonomy
Деактивира (премахва регистрацията) кастомна таксономия, която е била регистрирана от агента.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
slug | string | Да | Ключът на таксономията за премахване |
Връщане { "success": true, "slug": "project-category" }
Design System
Способностите за Design System променят визуалното представяне на сайта – от кастомния CSS до блокови шаблони и логото на сайта.
inject_custom_css
Добавя CSS към <head> на сайта чрез функцията wp_add_inline_style. CSS се съхранява в опцията gratis_ai_agent_custom_css и се изтрива чисто, когато способността бъде рестартирана.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
css | string | Да | Валиден CSS за инжектиране |
label | string | Не | Четимо за човека име за този блок на CSS, се използва в лог файловете за отстраняване на грешки. Дефолтът е "agent-injected" |
replace | boolean | Не | Ако е true, замества всички предварително инжектирани CSS. Дефолтът е false (добавя) |
Пример
{
"css": ":root { --primary: #1a1a2e; --accent: #e94560; } body { font-family: 'Inter', sans-serif; }",
"label": "brand-colours",
"replace": false
}
Връщане { "success": true, "bytes": 96 }
add_block_pattern
Регистрира повторно използваем блок шаблон в библиотеката на шаблони на WordPress.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
slug | string | Да | Идентификатор на шаблона, например gratis/hero-dark |
title | string | Да | Четово име на шаблона, което се показва в редактора |
content | string | Да | Сериализиран маркер на блока (HTML) за шаблона |
categories | array | Не | Слагове на категориите на шаблони, например ["featured", "hero"] |
description | string | Не | Кратко описание, което се показва в избора на шаблони |
keywords | array | Не | Думи за търсене |
Връщане { "success": true, "slug": "gratis/hero-dark" }
list_block_patterns
Извежда всички блок шаблони, регистрирани от агента.
Параметри — лични
Връщане
{
"patterns": [
{
"slug": "gratis/hero-dark",
"title": "Dark Hero",
"categories": ["hero"]
}
]
}
set_site_logo
Поставя логото на сайта на WordPress, използвайки даден ID на прикрепено изображение или отдалечен URL към изображение. Когато се предостави URL, изображението се сваля и импортира в Библиотеката на медии (Media Library).
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
attachment_id | integer | Не | ID на съществуващо прикрепено изображение в Библиотеката на медии |
url | string | Не | Отдалечен URL към изображение, което трябва да бъде импортирано и зададено като лого |
Трябва да се предостави един от attachment_id или url.
Връщане { "success": true, "attachment_id": 42 }
apply_theme_json_preset
Прилага преглед (preset) с име към настройките за цвят/типографика в theme.json (или global-styles) на активната тема. Прегледите са пакети, поддържани от екипа на Gratis AI Agent.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
preset | string | Да | Име на прегледа, например minimal-dark, warm-editorial, corporate-blue |
merge | boolean | Не | Ако е true, слива с е с вече съществуващите стойности вместо замяна. Дефолтът е false |
Достъпни прегледи
| Преглед | Описание |
|---|---|
minimal-dark | Практически черен фон, бяв текст, един акцентен цвят |
warm-editorial | Топъл бял фон, шрифтове с засечки (serif), земни акцентни цветове |
corporate-blue | Синя и бяла палитра с професионална типография |
vibrant-startup | Ярки градиенти, заглавници с заглавени ъгли, съвременен шрифт без засечки (sans-serif) |
classic-blog | Нейтрални сиви тонове, удобна линия на текста, традиционно разполагане на интервалите |
Връщане { "success": true, "preset": "minimal-dark" }
Global Styles (Глобални стилове)
Способностите за Глобални стилове четят и записват стойности в theme.json чрез WordPress Global Styles API, което влияе на всички блокове и шаблони по цял сайт.
get_global_styles
Връща текущата конфигурация на глобалните стилове.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
path | string | Не | JSON указател към конкретна стойност, например /color/palette или /typography/fontSizes. Връща целия обект, ако не е посочен. |
Връща пълния общ стилове обект или стойността по path.
set_global_styles
Актуализира една или повече стойности в конфигурацията на общите стилове.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
path | string | Да | JSON указател към стойността, която искате да зададете, например /color/palette |
value | any | Да | Новата стойност |
Пример — добавяне на цвят в палитрата
{
"path": "/color/palette",
"value": [
{ "slug": "primary", "color": "#1a1a2e", "name": "Primary" },
{ "slug": "accent", "color": "#e94560", "name": "Accent" }
]
}
Връща { "success": true, "path": "/color/palette" }
reset_global_styles
Среща всички промени в общите стилове, приложени от агента, като възстановява стандартните настройки на тема.
Параметри — няма
Връща { "success": true }
Навигационни менюта (Navigation Menus)
Способностите за Навигационни Меню създават и управляват менютата за навигация в WordPress и техните елементи.
create_menu
Създава ново меню за навигация в WordPress.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
name | string | Да | Име на менюто, например Primary Navigation |
location | string | Не | Местоположение в темата, към което се приспада това меню, например primary |
Връща { "success": true, "menu_id": 7 }
update_menu
Преименува менюто или го преназначава на локация в тема.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
menu_id | integer | Да | ID на менюто, което трябва да се актуализира |
name | string | Не | Новото име на менюто |
location | string | Не | Локацията в тема, към която се назначава или преназначава |
Връщане { "success": true, "menu_id": 7 }
add_menu_item
Добавя елемент в съществува меню за навигация.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
menu_id | integer | Да | ID на целта менюто |
type | string | Да | Тип на елемента: custom, post_type или taxonomy |
title | string | Не | Етикет за елемента в менюто (задължителен за типа custom) |
url | string | Не | URL за елементи от типа custom |
object_id | integer | Не | ID на поста или термин за елементи от типа post_type/taxonomy |
parent_id | integer | Не | ID на елемента в менюто, под който се групира този елемент |
position | integer | Не | Позиция (от 0) в менюто |
Връщане { "success": true, "item_id": 12 }
remove_menu_item
Премахва елемент от меню за навигация.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
item_id | integer | Да | ID на елемента в менюто, който трябва да се премахне |
Връщане { "success": true, "item_id": 12 }
list_menus
Извежда всички навигационни менюта в WordPress, включително им назначените локации в тема.
Параметри — лични (няма)
Връщане
Управление опциите (Options Management)
Способността за четене и запис на WordPress опциите се извършва чрез функциите get_option / update_option. Вграденият механизъм за безопасност предотвратява случайно промяната на критични настройки.
get_option
Чете една WordPress опция.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
option_name | string | Да | Ключът н а опцията, например blogname |
Връщане { "option_name": "blogname", "value": "My Site" }
Връща грешка, ако option_name е в списъка с безопасни блокове.
set_option
Записва WordPress опция.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
option_name | string | Да | Ключът на опцията |
value | any | Да | Новата стойност (автоматично се сериализира за масиви/обекти) |
autoload | string | Не | "yes" или "no". По подразбиране запазва текущата настройка на автозареждане |
Връща грешка, ако option_name е в списъка с безопасни блокове.
Връщане { "success": true, "option_name": "blogname" }
delete_option
Изтрива WordPress опция.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
option_name | string | Да | Ключът на опцията, която трябва да се изтрие |
Връща грешка, ако option_name е в списъка с безопасни блокове.
Връщане { "success": true, "option_name": "my_custom_option" }
list_options
Списва опции от WordPress, които съвпадат с определен шаблон.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
pattern | string | Не | SQL LIKE шаблон за филтриране на имена на опциите, например gratis_%. Връща всички опции, ако не е указан (използвайте с предоставете внимание при големи бази данни). |
limit | integer | Не | Максимално броят резултати. С डिफалтно стойност 50, максимум 500. |
Връщане
{
"options": [
{ "option_name": "gratis_ai_agent_version", "autoload": "yes" }
],
"total": 1
}
Управление на съдържанието (Content Management)
Способностите за управление на съдържанието създават и редактират публикации и страници в WordPress. Се извлича ID-тата на публикациите, за да могат следващите стъпки в плановете с множество способности да се отнасят до създадения контент.
create_post
Създава нова публикация, страница или запис за произволен тип пост (custom post type).
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
title | string | Да | Заглавие на поста |
content | string | Не | Текст на поста – приема обикновен текст, HTML или сериализиран блок ма ркер |
status | string | Не | draft, publish, pending, private. Дефолтът е draft |
post_type | string | Не | Slug на типа пост, например post, page или всяка регистрирана CPT. Дефолтът е post |
excerpt | string | Не | Кратко резюме, което се показва в архивите и резултатите от търсенето |
categories | array | Не | Масив от имена или ID на категории за присвояване |
tags | array | Не | Масив от имена или ID на тагове за присвояване |
author | integer | Не | WordPress потребителски ID, който се задава като автор на поста. Дефолтът е текущият потребител |
date | string | Не | Дата на публикуване в ISO 8601 формат, например 2026-05-01T09:00:00 |
page_template | string | Не | Файл за шаблон, който се присвоява на този пост или страница, например page-full-width.php. Значимо само когато post_type е page или CPT, който поддържа шаблони за страници. |
Пример
{
"title": "Добре дошли в нашия нов сайт",
"content": "<!-- wp:paragraph --><p>Здравейте!</p><!-- /wp:paragraph -->",
"status": "publish",
"post_type": "page",
"page_template": "page-full-width.php"
}
Връщане { "success": true, "post_id": 42, "permalink": "https://example.com/welcome/" }
update_post
Актуализира съществуващ WordPress пост или страница.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
post_id | integer | Да | ID на поста, който трябва да се актуализира |
title | string | Не | Но заглавие на поста |
content | string | Не | Новото съдържание на поста |
status | string | Не | Новото състояние: draft, publish, pending, private |
excerpt | string | Не | Новото изречение (извад ка) за поста |
categories | array | Не | Заместете целия списък с категории с този масив от имена или ID-та |
tags | array | Не | Заместете целия списък с тагове с този масив от имена или ID-та |
page_template | string | Не | Новият шаблон за назначаване на този пост или страница, например page-full-width.php. Предайте празна нива, за да премахнете назначаването на шаблона и да се върнете към стандартния шаблон на тема. |
Пример — промяна на шаблона след създаване
{
"post_id": 42,
"page_template": "page-full-width.php"
}
Връщане { "success": true, "post_id": 42 }
batch_create_posts
Създава множество постове в един извикване на способността, което намалява броя на заявките при изграждане на сайта или масово импортиране на съдържание. Постовете се създават последователно; ако един от тях не успее, другите продължават и неуспеха се докладва в масива с резултати.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
posts | array | Да | Масив от обекти на постове, всеки от които приема същите параметри като create_post |
stop_on_error | boolean | Не | Ако е true, спира обработката след първия провал. По подразбиране е false |
Пример
{
"posts": [
{
"title": "За нас",
"post_type": "page",
"status": "publish",
"page_template": "page-full-width.php"
},
{
"title": "Услуги",
"post_type": "page",
"status": "publish"
},
{
"title": "Контакти",
"post_type": "page",
"status": "publish"
}
]
}
**Връщане**
```json
{
"created": 3,
"failed": 0,
"results": [
{ "success": true, "post_id": 42, "title": "За нас" },
{ "success": true, "post_id": 43, "title": "Услуги" },
{ "success": true, "post_id": 44, "title": "Контакти" }
]
}
set_featured_image
Поставя снимка за преглед (миниатюра на поста или страниците) на съществуващ пост или страница. Приема ID на съществуващо прикрепено изображение от Media Library или URL на отдалечено изображение; когато се предостави URL, изображението се сваля и импортира автоматично.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
post_id | integer | Да | ID на поста или страницата, която да бъде актуализирана |
attachment_id | integer | Не | ID на съществуващо прикрепено изображение от Media Library |
url | string | Не | URL на отдалечено изображение за импорт и настройка като снимка за преглед |
alt_text | string | Не | Текст за алтернативен текст, който се прилага към прикрепеното изображение, ако е импортирано от URL |
Трябва да бъде предоставен един от attachment_id или url.
Връщане { "success": true, "post_id": 42, "attachment_id": 17 }
create_contact_form
Создает форму обратной связи, используя активный плагин (Contact Form 7, WPForms, Fluent Forms или Gravity Forms, в зависимости от того, какой установлен). Возвращает шорткод, который можно вставить в любой пост или страницу.
Параметры
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
title | string | Да | Имя формы, отображаемое в админке плагина формы |
fields | array | Да | Упорядоченный список полей формы (см. объект Field ниже) |
recipient | string | Нет | Адрес электронной почты для получения сообщений. По умолчанию — почта администратора WordPress |
subject | string | Нет | Тема письма. Поддерживает плейсхолдеры [ваше-имя] и [ваша-тема] при использовании Contact Form 7 |
confirmation_message | string | Нет | Сообщение, отображаемое после успешной отправки. По умолчанию: "Спасибо за ваше сообщение. Мы скоро с вами свяжемся." |
Объект поля (Field object)
| Ключ | Тип | Обязат ельно | Описание |
|---|---|---|---|
name | string | Да | Внутреннее имя поля / машинный ключ |
label | string | Да | Человекочитаемое название, отображаемое на форме |
type | string | Да | text, email, tel, textarea, select, checkbox, radio, file, date |
required | boolean | Нет | Требуется ли заполнение поля перед отправкой. По умолчанию false |
options | array | Нет | Опции для полей select, checkbox и radio |
placeholder | string | Нет | Текст-заполнитель для текстовых полей ввода |
Пример
{
"title": "Запит за резервация в ресторан",
"fields": [
{ "name": "your-name", "label": "Име", "type": "text", "required": true },
{ "name": "your-email", "label": "Емейл", "type": "email", "required": true },
{ "name": "party-size", "label": "Размер на групата", "type": "select", "options": ["1–2", "3–5", "6–10", "10+"] },
{ "name": "your-message", "label": "Особени заявки", "type": "textarea", "required": false }
],
"recipient": "[email protected]",
"subject": "Нов запит за резервация от [your-name]"
}
Връщане
{
"success": true,
"form_id": 3,
"shortcode": "[contact-form-7 id=\"3\" title=\"Запит за резерв ация в ресторан\"]"
}
Визуален преглед
Способностите за визуален преглед позволяват на агента да снима скриншоти от живи страници и да ги анализира, което улеснява автономния дизайн преглед, сравнения преди/след и проверки за визуална регресия без нужда от разширения за браузъра.
capture_screenshot
Снима скриншот на страница в WordPress по зададена URL чрез сървърно-страничен (headless) браузър. Изображението се запазва във Media Library, а се връща URL с CDN.
Параметри
| Параметър | Тип | Изисква се | Описание |
|---|---|---|---|
url | string | Да | Пълна URL на страницата, която ще бъде скратшотена, например https://example.com/about/ |
width | integer | Не | Ширина на прозореца в пиксели. Дефолт 1280 |
height | integer | Не | Височина на прозореца в пиксели. Дефолт 800 |
full_page | boolean | Не | Заснема цялата пролистваема страница вместо само прозореца. Дефолт false |
delay_ms | integer | Не | Милисекунди за чакане след зареждането на страницата преди снимката, полезно за анимиран съдържание. Дефолт 500 |
label | string | Не | Четимо за човека езиково име, запазено с приложаването в Media Library |
Връщане
{
"success": true,
"attachment_id": 88,
"url": "https://example.com/wp-content/uploads/2026/04/screenshot-about.png",
"width": 1280,
"height": 800
}
compare_screenshots
Приема две снимки и връща визуален р езултат от сравнение (diff score) плюс изображение с разлика (diff image), което подчертава променените региони. Полезно за потвърждаване, че промяната в дизайна е довела до очаквания резултат или за откриване на нежелани регресии.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
before_url | string | Да | URL на страницата, която да бъде заснета като "предишна" състояние. |
after_url | string | Да | URL на страницата, която да бъде заснета като "следващо" състояние. Може да е същият URL при сравняване във времето. |
width | integer | Не | Ширина на прозореца за двете снимки. Дефолтът е 1280. |
threshold | float | Не | Проницален праг в пиксели (от 0.0 до 1.0). Пикселите в рамките на тази толерантност се считат за не променени. Дефолтът е 0.1. |
Връщане
{
"success": true,
"diff_score": 0.04,
"changed_pixels": 2340,
"total_pixels": 1024000,
"diff_attachment_id": 91,
"diff_url": "https://example.com/wp-content/uploads/2026/04/diff-about.png"
}
diff_score от 0.0 означава, че няма видими промени; 1.0 означава, че всеки пиксел е променен.
review_page_design
Заснема скриншот на страница и го изпраща към модела за езикова обработка за визуален анализ. Връща структурирана оценка, която обхваща структурата (layout), типографиката, използването на цветове и проблеми с достъпността (accessibility).
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
url | string | Да | Пълният URL на страницата за преглед. |
focus | string | Не | Заредена списък от области за преглед, които трябва да бъдат подчертани с запетая: layout, typography, colour, accessibility, mobile. Дефолт: всички области. |
width | integer | Не | Ширина на прозореца. Дефолтът е 1280. |
Връщане
Установяеми способности
Регистърът за установяеми способности (Installable Abilities Registry) ви позволява да разширите агента с допълнителни пакети от способности, които са разпределени като WordPress плагини. Всеки пакет регистрира една или повече способности чрез стандартния API за способности.
list_available_abilities
Връща каталога на пакетите от способности, достъпни за инсталиране от регистратора.
Параметри
| Параметър | Тип | Изисква се | Описание |
|---|---|---|---|
category | string | Не е задължително | Филете по категория: ecommerce, seo, media, social, developer |
Връщане
install_ability
Зарежда и активира пакет с възможности (ability pack) от регистъра.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
slug | string | Да | Slug на плагината с пакета с възможности |
Връщане { "success": true, "slug": "gratis-ai-agent-woocommerce", "abilities_added": 3 }
recommend_plugin
Задава заявка към регистъра на възможностите, за да намери най-добрия плагин за описания случай на употреба и, опционално, го инсталира.
Параметри
| Параметър | Тип | Изисква ли | Описание |
|---|---|---|---|
description | string | Да | Естествено езиково описание на желаната функцион алност |
install | boolean | Не | Ако е true, препоръчаният плагин се инсталира веднага. Дефолтът е false |
Пример
{
"description": "Мне трябва контактна форма с поддръжка за качване на файлове и защита от спам",
"install": false
}
Връщане
{
"recommendation": {
"slug": "contact-form-7",
"name": "Contact Form 7",
"reason": "Широко използвани, поддържа качване на файлове и се интегрира с Akismet за филтриране на спам.",
"alternatives": ["wpforms-lite", "fluent-forms"]
}
}