Skills (инструменты)

Skill — это одна самодостаточная возможность, которую LLM может вызвать. Skill-фреймворк автовыводит регистрацию LLM-инструмента, HTTP API, форму UI, гейт прав и audit-log из одной метадаты-структуры — добавление нового скилла означает написание одного файла и вызов Register в init().

Скиллы — L2 (device-direct), когда они запускаются на edge-агенте, L3 (intelligence), когда они запускаются на manager. Оба — first-class.

Анатомия

Каждый скилл поставляет:

// internal/skill/types.go:99
type Metadata struct {
    Key          string   // lower_snake — id in dedupe keys, audit logs, LLM tool names
    Name         string   // human label
    Description  string   // shown to humans AND to the LLM
    Class        Class    // safe | mutating | dangerous
    Scope        Scope    // host (default) | manager
    Category     string   // free-form group label
    Params       ParamSchema
    ResultPreview string
}

Плюс Executor:

type Executor interface {
    Metadata() Metadata
    Execute(ctx context.Context, params json.RawMessage) (json.RawMessage, error)
}

Фреймворк диспетчирует на основе Scope:

• ScopeHost — manager оборачивает вызов в tunnel RPC (Caller.Call(ctx, edgeID, "execute_skill", body)), один handler execute_skill edge-агента диспетчирует по ключу. LLM-обёртка инструмента инъецирует обязательное целочисленное свойство edge_id в схему.
• ScopeManager — запускается in-process. Без edge_id; полезно для вызовов public-internet (web_search), внешних API, subprocess skill packs.

Классы прав

Встроены в метадату, так что гейт запускается на каждый вызов, а не как довесок:

Класс	Примеры	Кто может вызывать
safe	probe_*, read_file, tail_file, query_promql	LLM, любая роль
mutating	restart_service, kill_process	Требует одобрения human-in-the-loop (припарковано, но гейт существует)
dangerous	rm, reboot, drop_table	Требует RSA-подписанного SOP + двойного одобрения (припарковано)

Класс по умолчанию — safe — но фреймворк логирует предупреждение во время регистрации, когда автор забывает поставить поле, так что это не может проскользнуть молча. См. types.go:205.

skill_bridge.go в aiops tools registry в настоящее время только выставляет ClassSafe скиллы LLM — см. skill_bridge.go. Mutating и dangerous классы ждут approval-workflow PR-G4.

Три популяции скиллов

Go-builtin'ы (edge)

Написаны вручную в internal/skill/builtin/:

Key	Что
probe_http, probe_dns, probe_tcp	Read-only network reachability
tail_file, read_journal	Лог-поверхность
host_netns_inspect	Инвентарь network namespace
web_search	Manager-side; SearXNG по умолчанию, настраиваемо
restart_service	Mutating; гейтится

Каждый — это Go-файл с init(), вызывающий skill.Register. Edge-бинарь поставляет каждый builtin запечённым — без установки плагинов, без поверхности удалённого выполнения кода.

Subprocess skill packs

Для возможностей, которые вы хотите подкинуть без пересборки edge-агента, поставьте директорию с манифестом skill.json и исполняемым файлом. Загрузчик в internal/skill/subprocess.go читает манифест, регистрирует скилл, диспетчирует Execute на бинарь с параметрами в stdin.

Используется для: network research tools (ovs-vsctl, nft, bpftool, ethtool, ip netns), Kubernetes inspect helpers — всё, где бинарь уже существует и shell out лучше, чем переписывать на Go.

Manager-side BaseTool

Самая большая популяция. Живёт под internal/manager/biz/aiops/tools/ как файлы *_basetool.go. Каждый несёт собственную написанную вручную JSON Schema (нужна для форм, которые декларативный ParamSchema не может выразить: массивы, вложенные объекты, oneOf).

Избранные BaseTool:

Tool	Что делает
bash	Shell на целевом edge (гейтится; записывается)
query_promql, query_logql, query_traceql	Три observability-бэкенда
query_incidents, get_incident_detail, query_alert_rules	Поверхность алертинга
query_edges, query_change_events	Инвентарь + аудит
correlate_incident	Композитный fan-out в prom + log + trace
expand_topology, find_topology_node, get_topology	Граф
query_knowledge	RAG
find_outlier_edges, rank_edges	Multi-host сравнение
host_load, host_processes, host_files	Host-state batch-инструменты
get_edge_summary	One-shot edge health snapshot
restart_service	Manager-side обёртка вокруг edge-restart-скилла
send_message	Coordinator → specialist agent comms
task_stop, agent_tool	Worker lifecycle

Около 30+ в сумме. Полный список — что зарегистрировано в BuildBaseTools в cmd/ongrid/main.go.

Inventory bridge

Два параллельных реестра существовали до bridge:

• Skill registry — ScopeHost Go-builtin'ы + subprocess pack'и. Выставляются на странице SPA /skills с audit + class-гейтом.
• BaseTool bag — написанные вручную manager-side инструменты. Выставляются LLM, но НЕ в /skills.

Операторы не могли видеть, какие cloud-side возможности у агента реально были, не читая исходники. inventory_bridge.go обходит BaseTool bag и регистрирует каждый инструмент как скилл с Scope=ScopeManager. Opt-in интерфейс RawSchemaProvider используется для сохранения написанной вручную JSON Schema каждого BaseTool дословно.

По memo 2026-05-08, 18 BaseTool bridged через этот путь — страница /skills теперь перечисляет каждую cloud-side возможность с scope-чипом, указывающим edge vs manager.

Обратный bridge также подключён: skill_bridge.go берёт каждый safe-скилл и регистрирует его как LLM-обращённый Tool, так что LLM видит скиллы как function-calling инструменты с параметром edge_id, автоматически предпосылаемым для ScopeHost.

Аудит

Каждый вызов инструмента пишет строку в chat_tool_calls:

• session_id — chatruntime-сессия, которая вызвала.
• tool_name, args_json, result_json, error.
• device_id — когда инструмент целился в конкретный хост (поле EdgeID в ExecuteResult).
• started_at, finished_at, duration_ms.
• caller_user_id + caller_role — для LLM-originated вызовов фреймворк использует UserID=0 / Role="system".

Audit log HLD-010 садится на ту же таблицу; админ-страница /admin/audit рендерит его с таймлайном + per-tool фильтрами.

См. также

• WebShell — bash скилл, выраженный как интерактивный терминал, а не one-shot tool-вызов.
• Знания — query_knowledge глубокий дайв.
• Топология — expand_topology / find_topology_node.
• Манифест скилла — wire-формат для subprocess skill packs.