기능 (도구)

기능 은 LLM 이 호출할 수 있는 하나의 자체 완결 능력입니다. 기능 프레임워크는 단일 메타데이터 구조체에서 LLM 도구 등록, HTTP API, UI 폼, 권한 게이트, 감사 로그를 자동 파생합니다 — 새 기능 추가는 한 파일을 작성하고 init() 에서 Register 를 호출하는 것을 의미합니다.

기능은 edge 에이전트에서 실행될 때 L2 (디바이스 직접), 매니저에서 실행될 때 L3 (인텔리전스). 둘 다 일급.

구조

모든 기능이 출하:

// 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 — 매니저가 호출을 터널 RPC (Caller.Call(ctx, edgeID, "execute_skill", body)) 로 래핑, edge 에이전트의 하나의 execute_skill 핸들러가 키로 디스패치. LLM 도구 래퍼가 스키마에 필수 edge_id 정수 속성을 주입.
ScopeManager — in-process 실행. edge_id 없음; 공개 인터넷 호출 (web_search), 외부 API, 서브프로세스 기능 팩에 유용.

권한 클래스

메타데이터에 내장되어 게이트가 모든 호출에서 실행 (보조 추가가 아님):

Class	예시	누가 호출 가능
`safe`	probe_*, read_file, tail_file, query_promql	LLM, 모든 role
`mutating`	restart_service, kill_process	인간 in-the-loop 승인 필요 (보류, 그러나 게이트 존재)
`dangerous`	rm, reboot, drop_table	RSA 서명 SOP + 이중 승인 필요 (보류)

기본 클래스는 safe — 그러나 작성자가 필드 설정을 잊으면 프레임워크가 등록 시 경고를 로깅하므로 조용히 미끄러지지 않습니다. types.go:205 참고.

aiops 도구 레지스트리의 skill_bridge.go 는 현재 ClassSafe 기능만 LLM 에 노출 — skill_bridge.go 참고. Mutating 과 dangerous 클래스는 PR-G4 승인 워크플로를 기다립니다.

세 기능 모집단

Go 빌트인 (edge)

internal/skill/builtin/ 에 손으로 작성:

Key	What
`probe_http`, `probe_dns`, `probe_tcp`	읽기 전용 네트워크 도달성
`tail_file`, `read_journal`	로그 표면
`host_netns_inspect`	네트워크 네임스페이스 인벤토리
`web_search`	매니저 측; SearXNG 기본, 구성 가능
`restart_service`	Mutating; 게이트됨

각각 skill.Register 를 호출하는 init() 가 있는 Go 파일. Edge 바이너리는 모든 빌트인을 베이크 인하여 출하 — 플러그인 설치 없음, 원격 코드 실행 표면 없음.

서브프로세스 기능 팩

Edge 에이전트 재빌드 없이 드롭하고 싶은 능력은 skill.json manifest 와 실행 파일이 있는 디렉터리를 출하. internal/skill/subprocess.go 의 로더가 manifest 를 읽고 기능 등록, stdin params 와 함께 바이너리로 Execute 디스패치.

사용처: 네트워크 연구 도구 (ovs-vsctl, nft, bpftool, ethtool, ip netns), Kubernetes 점검 헬퍼 — 바이너리가 이미 존재하고 셸 아웃이 Go 로 재작성하는 것을 이기는 모든 경우.

매니저 측 BaseTool

가장 큰 모집단. internal/manager/biz/aiops/tools/ 아래 *_basetool.go 파일로 거주. 각각 자체 손수 작성 JSON Schema 운반 (선언적 ParamSchema 가 표현할 수 없는 형태: 배열, 중첩 객체, oneOf 에 필요).

선별된 BaseTool:

Tool	동작
`bash`	대상 edge 의 셸 (게이트됨; 기록됨)
`query_promql`, `query_logql`, `query_traceql`	세 가관측성 백엔드
`query_incidents`, `get_incident_detail`, `query_alert_rules`	알림 표면
`query_edges`, `query_change_events`	인벤토리 + 감사
`correlate_incident`	Prom + 로그 + 트레이스로의 composite fan-out
`expand_topology`, `find_topology_node`, `get_topology`	그래프
`query_knowledge`	RAG
`find_outlier_edges`, `rank_edges`	다중 호스트 비교
`host_load`, `host_processes`, `host_files`	호스트 상태 배치 도구
`get_edge_summary`	일회성 edge 헬스 스냅샷
`restart_service`	edge restart 기능 주변 매니저 측 래퍼
`send_message`	Coordinator → specialist 에이전트 통신
`task_stop`, `agent_tool`	Worker 생명주기

총 약 30+. 전체 리스트는 cmd/ongrid/main.go 의 BuildBaseTools 에 등록된 것.

Inventory bridge

브릿지 전에 두 병렬 레지스트리가 존재:

기능 레지스트리 — ScopeHost Go 빌트인 + 서브프로세스 팩. 감사 + 클래스 게이트로 SPA 의 /skills 페이지에 표면화.
BaseTool 가방 — 손수 작성된 매니저 측 도구. LLM 에는 표면화되지만 /skills 에는 아님.

운영자는 소스를 읽지 않고는 에이전트가 실제로 어떤 클라우드 측 능력을 가졌는지 볼 수 없었습니다. inventory_bridge.go 가 BaseTool 가방을 워크하여 모든 도구를 Scope=ScopeManager 인 기능으로 등록. Opt-in RawSchemaProvider 인터페이스가 각 BaseTool 의 손수 작성 JSON Schema 를 그대로 보존하는 데 사용됩니다.

2026-05-08 메모에 따르면 18 BaseTool 이 이 경로로 브릿지 — /skills 페이지는 이제 edge vs manager 를 나타내는 scope chip 과 함께 모든 클라우드 측 능력을 나열.

리버스 브릿지도 배선: skill_bridge.go 가 모든 safe 기능을 받아 LLM 대면 Tool 로 등록하므로 LLM 은 기능을 ScopeHost 의 것에 자동 prepend 된 edge_id 파라미터가 있는 함수 호출 도구로 봅니다.

감사

모든 도구 호출은 chat_tool_calls 에 행을 씀:

session_id — 호출한 chatruntime 세션.
tool_name, args_json, result_json, error.
device_id — 도구가 특정 호스트를 대상으로 한 경우 (ExecuteResult 의 EdgeID 필드).
started_at, finished_at, duration_ms.
caller_user_id + caller_role — LLM 발원 호출의 경우 프레임워크가 UserID=0 / Role="system" 사용.

HLD-010 감사 로그는 같은 테이블을 piggyback; admin /admin/audit 페이지가 타임라인 + 도구별 필터와 함께 렌더링.

같이 보기

WebShell — 일회성 도구 호출이 아닌 대화형 터미널로 표현된 bash 기능.
지식 베이스 — query_knowledge 심층 분석.
토폴로지 — expand_topology / find_topology_node.
기능 매니페스트 — 서브프로세스 기능 팩의 와이어 포맷.

기능 (도구) ​

구조 ​

권한 클래스 ​

세 기능 모집단 ​

Go 빌트인 (edge) ​

서브프로세스 기능 팩 ​

매니저 측 BaseTool ​

Inventory bridge ​

감사 ​

같이 보기 ​