diff --git a/diagnostics.go b/diagnostics.go index 8ee9966..0f98a34 100644 --- a/diagnostics.go +++ b/diagnostics.go @@ -36,45 +36,3 @@ func (s *DiagnosticsService) QueryDiagnose(ctx context.Context, req *DiagnoseReq } return out, resp, nil } - -// List monitored targets. -// -// List the targets observed under the current tenant by the monit-agent route projection. Supports `target_locator` prefix search and cursor pagination. Use this to drive `target_locator` selection for `/monit/tools/catalog` and `/monit/tools/invoke`. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id. -// -// API: POST /monit/targets (monit-read-targets-list). -func (s *DiagnosticsService) TargetsList(ctx context.Context, req *TargetsListRequest) (*TargetsListResponse, *Response, error) { - out := new(TargetsListResponse) - resp, err := s.client.do(ctx, "/monit/targets", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} - -// List target tool catalog. -// -// Look up the tools that the per-target monit-agent currently exposes for a given `target_locator` (host). Returns each tool's name, description, and JSON-Schema `input_schema`. Pair with `/monit/tools/invoke` to drive AI-SRE tool calls. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id. -// -// API: POST /monit/tools/catalog (monit-read-tools-catalog). -func (s *DiagnosticsService) ToolsCatalog(ctx context.Context, req *ToolCatalogRequest) (*ToolCatalogResponse, *Response, error) { - out := new(ToolCatalogResponse) - resp, err := s.client.do(ctx, "/monit/tools/catalog", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} - -// Invoke target tools. -// -// Invoke up to 8 monit-agent tools concurrently on a single target. Results come back in the order of the input `tools` array. Long-running — individual tools have per-tool timeouts on the agent and the whole request may take tens of seconds. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id. -// -// API: POST /monit/tools/invoke (monit-read-tools-invoke). -func (s *DiagnosticsService) ToolsInvoke(ctx context.Context, req *ToolInvokeRequest) (*ToolInvokeResponse, *Response, error) { - out := new(ToolInvokeResponse) - resp, err := s.client.do(ctx, "/monit/tools/invoke", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} diff --git a/e2e/sweep_test.go b/e2e/sweep_test.go index eb965ae..299b628 100644 --- a/e2e/sweep_test.go +++ b/e2e/sweep_test.go @@ -140,10 +140,6 @@ func TestServiceReadSweep(t *testing.T) { }) return rid(r), tot(r), err }}, - {"Diagnostics", func() (string, int, error) { - _, r, err := c.Diagnostics.TargetsList(ctx, &flashduty.TargetsListRequest{}) - return rid(r), tot(r), err - }}, } for _, rd := range reads { diff --git a/internal/cmd/gen/naming.go b/internal/cmd/gen/naming.go index 532da3a..062c4e6 100644 --- a/internal/cmd/gen/naming.go +++ b/internal/cmd/gen/naming.go @@ -121,6 +121,8 @@ func commonPrefixLen(opTokens [][]string) int { } var methodPrefixByTag = map[string][]string{ + // Removing Agent endpoints must not rename the supported query methods. + "Monitors/Diagnostics": {"monit", "read"}, "On-call/Incidents": {"incident"}, "On-call/Integrations": {"webhook", "history"}, } diff --git a/internal/cmd/gen/naming_test.go b/internal/cmd/gen/naming_test.go new file mode 100644 index 0000000..320106c --- /dev/null +++ b/internal/cmd/gen/naming_test.go @@ -0,0 +1,10 @@ +package main + +import "testing" + +func TestDiagnosticsNamesSurviveAgentRetirement(t *testing.T) { + names := methodNames("Monitors/Diagnostics", []string{"monit-read-query-data", "monit-read-query-diagnose"}) + if names["monit-read-query-data"] != "QueryData" || names["monit-read-query-diagnose"] != "QueryDiagnose" { + t.Fatalf("supported method names changed: %v", names) + } +} diff --git a/models_gen.go b/models_gen.go index fd7d579..b4a0d6b 100644 --- a/models_gen.go +++ b/models_gen.go @@ -9710,28 +9710,6 @@ type StringMapPatch struct { Set map[string]string `json:"set,omitempty" toon:"set,omitempty"` } -// TargetsListRequest is generated from the Flashduty OpenAPI schema. -type TargetsListRequest struct { - // Optional consistency check. Must equal the authenticated account when supplied. - AccountID int64 `json:"account_id,omitempty" toon:"account_id,omitempty"` - // Opaque pagination cursor from the previous response's `next_cursor`. Omit / pass empty string for the first page. Reset whenever `keyword`, `limit`, or tenant changes. - Cursor string `json:"cursor,omitempty" toon:"cursor,omitempty"` - // Prefix match against `target_locator`. ASCII only, no whitespace, no `|`, max 256 bytes. Substring search is not supported. - Keyword string `json:"keyword,omitempty" toon:"keyword,omitempty"` - // Page size. Default 50, max 200. - Limit int64 `json:"limit,omitempty" toon:"limit,omitempty"` -} - -// TargetsListResponse is generated from the Flashduty OpenAPI schema. -type TargetsListResponse struct { - // The current page of invocable targets, sorted ascending by `target_locator`. - Items []TargetsListResponseItemsItem `json:"items" toon:"items"` - // Opaque cursor for the next page. Absent / empty means this is the last page. - NextCursor *string `json:"next_cursor,omitempty" toon:"next_cursor,omitempty"` - // Total matches for the current `(account_id, keyword)` pair, independent of `cursor`. - Total int64 `json:"total" toon:"total"` -} - // TeamBriefItem is generated from the Flashduty OpenAPI schema. type TeamBriefItem struct { // Array of person IDs belonging to the team; empty array (never null) when the team has no members. @@ -10055,48 +10033,6 @@ type TimeFilter struct { Start string `json:"start,omitempty" toon:"start,omitempty"` } -// ToolCatalogRequest is generated from the Flashduty OpenAPI schema. -type ToolCatalogRequest struct { - // Optional consistency check. Must equal the authenticated account when supplied. - AccountID int64 `json:"account_id,omitempty" toon:"account_id,omitempty"` - // Optional target kind; only host is supported. Inferred when omitted. - TargetKind string `json:"target_kind,omitempty" toon:"target_kind,omitempty"` - // Host name. Max 256 bytes; no whitespace, control characters or |. - TargetLocator string `json:"target_locator" toon:"target_locator"` -} - -// ToolCatalogResponse is generated from the Flashduty OpenAPI schema. -type ToolCatalogResponse struct { - // Request-level business error. Omitted on success. Returned with HTTP 200 — do not rely on the status code alone. - Error *ToolCatalogResponseError `json:"error,omitempty" toon:"error,omitempty"` - // Resolved target. Omitted when `target_kind` was not supplied and the locator could not be uniquely inferred. - Target *ToolCatalogResponseTarget `json:"target,omitempty" toon:"target,omitempty"` - // Tool metadata advertised by the target's agent. Always present; an empty array when `error` is set. - Tools []ToolCatalogResponseToolsItem `json:"tools" toon:"tools"` -} - -// ToolInvokeRequest is generated from the Flashduty OpenAPI schema. -type ToolInvokeRequest struct { - // Optional consistency check. Must equal the authenticated account when supplied. - AccountID int64 `json:"account_id,omitempty" toon:"account_id,omitempty"` - // Optional target kind; only host is supported. Inferred when omitted. - TargetKind string `json:"target_kind,omitempty" toon:"target_kind,omitempty"` - // Host name. Max 256 bytes; no whitespace, control characters or |. - TargetLocator string `json:"target_locator" toon:"target_locator"` - // Up to 8 tool calls; webapi executes them concurrently and returns results in input order. - Tools []ToolInvokeRequestToolsItem `json:"tools" toon:"tools"` -} - -// ToolInvokeResponse is generated from the Flashduty OpenAPI schema. -type ToolInvokeResponse struct { - // Request-level business error. Omitted on success. Returned with HTTP 200 — do not rely on the status code alone. - Error *ToolInvokeResponseError `json:"error,omitempty" toon:"error,omitempty"` - // Per-tool results, aligned with the request `tools[]` order. Empty when a request-level `error` is present. - Results []ToolInvokeResponseResultsItem `json:"results" toon:"results"` - // Resolved target. Omitted when `target_kind` was not supplied and the locator could not be uniquely inferred. - Target *ToolInvokeResponseTarget `json:"target,omitempty" toon:"target,omitempty"` -} - // TryLinkPersonRequest is generated from the Flashduty OpenAPI schema. type TryLinkPersonRequest struct { // IM integration ID; obtain it from `POST /datasource/im/war-room-enabled/list`. @@ -11251,96 +11187,6 @@ type RUMIssueItemSuspectedCause struct { Value string `json:"value" toon:"value"` } -// TargetsListResponseItemsItem is generated from the Flashduty OpenAPI schema. -type TargetsListResponseItemsItem struct { - // Most recently observed Agent version. - AgentVersion string `json:"agent_version" toon:"agent_version"` - // Edge cluster name. - ClusterName string `json:"cluster_name" toon:"cluster_name"` - // Edge instance address (`ip:port`), surfaced for diagnostics. - EdgeIpport string `json:"edge_ipport" toon:"edge_ipport"` - // Host target kind. Filtering by kind is not supported in v1. - TargetKind string `json:"target_kind" toon:"target_kind"` - // Target identifier; the list is sorted by this field ascending. - TargetLocator string `json:"target_locator" toon:"target_locator"` - // Last route-projection upsert time, Unix seconds. Treat as 'most recently observed', not a live-online indicator. - UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` -} - -// ToolCatalogResponseError is generated from the Flashduty OpenAPI schema. -type ToolCatalogResponseError struct { - // Request-level error code: `target_unavailable` target unreachable, `timeout` resolution timed out, `forward_failed` cross-instance forwarding failed, `invalid_tool_result` agent returned an invalid result, `ambiguous_target_kind` target kind not uniquely inferable. - Code string `json:"code" toon:"code"` - // Human-readable error detail. - Message string `json:"message" toon:"message"` - // Returned for `ambiguous_target_kind`; lists the candidate kinds. - TargetKinds *[]string `json:"target_kinds,omitempty" toon:"target_kinds,omitempty"` -} - -// ToolCatalogResponseTarget is generated from the Flashduty OpenAPI schema. -type ToolCatalogResponseTarget struct { - // Resolved host target kind. - Kind string `json:"kind" toon:"kind"` - // Echo of the target locator from the request. - Locator string `json:"locator" toon:"locator"` -} - -// ToolCatalogResponseToolsItem is generated from the Flashduty OpenAPI schema. -type ToolCatalogResponseToolsItem struct { - // Tool capability description for UI / AI-SRE consumption. - Description string `json:"description" toon:"description"` - // JSON Schema for `tools[].params`. - InputSchema map[string]any `json:"input_schema" toon:"input_schema"` - // Tool name; pass into `/monit/tools/invoke` as `tools[].tool`. - Name string `json:"name" toon:"name"` - // Target kind this tool applies to. - TargetKind string `json:"target_kind" toon:"target_kind"` -} - -// ToolInvokeRequestToolsItem is generated from the Flashduty OpenAPI schema. -type ToolInvokeRequestToolsItem struct { - // Tool parameters matching the catalog `input_schema`. For no-arg tools pass `{}` explicitly. - Params map[string]any `json:"params,omitempty" toon:"params,omitempty"` - // Tool name, typically from `/monit/tools/catalog`. - Tool string `json:"tool" toon:"tool"` -} - -// ToolInvokeResponseError is generated from the Flashduty OpenAPI schema. -type ToolInvokeResponseError struct { - // Request-level error code: `target_unavailable` target unreachable, `forward_failed` cross-instance forwarding failed, `ambiguous_target_kind` target kind not uniquely inferable. - Code string `json:"code" toon:"code"` - // Human-readable error detail. - Message string `json:"message" toon:"message"` - // Returned only when `code` is `ambiguous_target_kind`, listing the candidate target kinds matched by the locator; omitted otherwise. - TargetKinds *[]string `json:"target_kinds,omitempty" toon:"target_kinds,omitempty"` -} - -// ToolInvokeResponseResultsItem is generated from the Flashduty OpenAPI schema. -type ToolInvokeResponseResultsItem struct { - // Tool business payload. Present only on success. Webapi already unwraps the monit-agent result envelope, so there is no nested `data.data`. - Data *map[string]any `json:"data,omitempty" toon:"data,omitempty"` - // Per-tool failure. Present only on failure, and mutually exclusive with `data` / `summary` / `truncated`. - Error *ToolInvokeResponseResultsItemError `json:"error,omitempty" toon:"error,omitempty"` - // Request params echoed back by webapi. Normalized to `{}` when the request omitted them or sent null. - Params map[string]any `json:"params" toon:"params"` - // Human/LLM-readable one-line distillation of the result. Present only when non-empty. - Summary *string `json:"summary,omitempty" toon:"summary,omitempty"` - // Tool name, aligned one-to-one with the request `tools[]` order. - Tool string `json:"tool" toon:"tool"` - // Agent-executed tool version. Omitted when the failure occurred before the agent picked a version. - ToolVersion *string `json:"tool_version,omitempty" toon:"tool_version,omitempty"` - // Present only when the result was actually truncated — the field's presence is the signal, so there is no redundant `truncated: true`. - Truncated *ToolInvokeResponseResultsItemTruncated `json:"truncated,omitempty" toon:"truncated,omitempty"` -} - -// ToolInvokeResponseTarget is generated from the Flashduty OpenAPI schema. -type ToolInvokeResponseTarget struct { - // Resolved host target kind. - Kind string `json:"kind" toon:"kind"` - // Echo of the target locator from the request. - Locator string `json:"locator" toon:"locator"` -} - // UpsertStatusPageComponentRequestComponentsItem is generated from the Flashduty OpenAPI schema. type UpsertStatusPageComponentRequestComponentsItem struct { // Time the component became (or becomes) available, in Unix seconds. On create, defaults to the current time; on update, replaces the stored value. @@ -11457,20 +11303,6 @@ type RuleConfigsCheckThresholdRecovery struct { ValueFields []string `json:"value_fields,omitempty" toon:"value_fields,omitempty"` } -// ToolInvokeResponseResultsItemError is generated from the Flashduty OpenAPI schema. -type ToolInvokeResponseResultsItemError struct { - // Common WebAPI codes: `timeout`, `target_unavailable`, `invalid_tool_result`, `internal`, `invalid_args`, `unsupported_syntax`, `path_not_found`, and `catalog_changed`. Agent-specific tool errors may also be returned unchanged. - Code string `json:"code" toon:"code"` - // Human-readable detail for this tool's failure; agent-side messages may be forwarded verbatim. - Message string `json:"message" toon:"message"` -} - -// ToolInvokeResponseResultsItemTruncated is generated from the Flashduty OpenAPI schema. -type ToolInvokeResponseResultsItemTruncated struct { - // Why the result was truncated. - Reason string `json:"reason" toon:"reason"` -} - // CreateChannelRequestEscalateRuleTargetBy is generated from the Flashduty OpenAPI schema. type CreateChannelRequestEscalateRuleTargetBy struct { // Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:`, `dingtalk_app:`, `wecom_app:`, `slack_app:`, `teams_app:`. diff --git a/openapi/openapi.en.json b/openapi/openapi.en.json index d19d92b..1fa032d 100644 --- a/openapi/openapi.en.json +++ b/openapi/openapi.en.json @@ -20281,326 +20281,6 @@ "deprecated": true } }, - "/monit/tools/catalog": { - "post": { - "operationId": "monit-read-tools-catalog", - "summary": "List target tool catalog", - "description": "Look up the tools that the per-target monit-agent currently exposes for a given `target_locator` (host). Returns each tool's name, description, and JSON-Schema `input_schema`. Pair with `/monit/tools/invoke` to drive AI-SRE tool calls. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id.", - "tags": [ - "Monitors/Diagnostics" - ], - "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- Use `target_locator` to identify the target; `target_kind` is optional and is inferred from current target routing when omitted.\n- If multiple kinds match the same locator, the response is HTTP 200 with `data.error.code = \"ambiguous_target_kind\"` and a `target_kinds` list — retry with an explicit `target_kind`.\n- The catalog is a candidate capability view, not an execution guarantee. The target Agent may go offline between catalog and invoke, or local Agent policy may block individual tools at invoke time.\n- Each tool entry exposes only `name`, `target_kind`, `description`, and `input_schema`. It does not expose tool versions, output contracts, catalog revisions, or execution limits.\n- Business errors (`target_unavailable`, `timeout`, `forward_failed`, `invalid_tool_result`, `ambiguous_target_kind`) return HTTP 200 with `data.error` present and `data.tools = []`. Only protocol, authentication, and internal errors use the standard error envelope.\n- The response uses **sparse fields**: on success `error` is omitted rather than sent as `null`, and `target` is omitted when the locator could not be uniquely resolved. `tools` is always present.", - "href": "/en/api-reference/monitors/diagnostics/monit-read-tools-catalog", - "metadata": { - "sidebarTitle": "List target tool catalog" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ToolCatalogRequest" - }, - "example": { - "account_id": 10001, - "target_locator": "web-01" - } - } - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/ToolCatalogResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "target": { - "kind": "host", - "locator": "web-01" - }, - "tools": [ - { - "name": "os.overview", - "target_kind": "host", - "description": "Returns a bounded overview of host health: CPU usage and load, memory and swap utilisation, disk and network counters, and top processes.", - "input_schema": { - "type": "object", - "additionalProperties": false, - "properties": {} - } - }, - { - "name": "net.tcp_ping", - "target_kind": "host", - "description": "Checks TCP reachability of a host:port from the target, reporting connect latency.", - "input_schema": { - "type": "object", - "additionalProperties": false, - "required": [ - "host", - "port" - ], - "properties": { - "host": { - "type": "string" - }, - "port": { - "type": "integer" - } - } - } - } - ] - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - } - } - }, - "/monit/tools/invoke": { - "post": { - "operationId": "monit-read-tools-invoke", - "summary": "Invoke target tools", - "description": "Invoke up to 8 monit-agent tools concurrently on a single target. Results come back in the order of the input `tools` array. Long-running — individual tools have per-tool timeouts on the agent and the whole request may take tens of seconds. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id.", - "tags": [ - "Monitors/Diagnostics" - ], - "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- Up to **8** tools per call (`MaxToolsPerInvoke`); larger batches must be split client-side. The 8-tool cap aligns with the per-target agent concurrency.\n- Tools execute in parallel on the agent; webapi returns `results[]` aligned with the request `tools[]` order.\n- Long-running: set client timeouts to **at least 35 s**. The endpoint is intended for AI-SRE / human-RCA flows, not interactive UI.\n- Request-level errors (`target_unavailable`, `ambiguous_target_kind`, `forward_failed`) appear as HTTP 200 with `data.error` set and `data.results = []`.\n- Per-tool failures appear as HTTP 200 with `data.error` absent and `results[i].error` populated — always check **all three** layers (outer envelope `error`, `data.error`, then each `results[i].error`).\n- The response uses **sparse fields**: absent means empty. On success `error` is omitted entirely rather than sent as `null`; on failure `data`, `summary` and `truncated` are omitted. Do not key logic off placeholder `null` fields, and do not expect `target` when the locator could not be uniquely resolved.\n- `results[i].data` is the tool payload with the monit-agent result envelope **already unwrapped** — there is no nested `data.data`. The one-line distillation is `results[i].summary`, and `results[i].truncated` (carrying a `reason`) appears only when the result was genuinely truncated.\n- `results[i].params` echoes the params webapi received for that tool, so batched calls stay correlatable even when an individual tool fails.\n- Construct `tools[].params` against the `input_schema` returned by `/monit/tools/catalog`. For no-arg tools always pass `params: {}` explicitly.", - "href": "/en/api-reference/monitors/diagnostics/monit-read-tools-invoke", - "metadata": { - "sidebarTitle": "Invoke target tools" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ToolInvokeRequest" - }, - "example": { - "account_id": 10001, - "target_locator": "web-01", - "tools": [ - { - "tool": "os.overview", - "params": {} - }, - { - "tool": "net.tcp_ping", - "params": { - "host": "10.0.0.10", - "port": 3306 - } - } - ] - } - } - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/ToolInvokeResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "target": { - "kind": "host", - "locator": "web-01" - }, - "results": [ - { - "tool": "os.overview", - "params": {}, - "tool_version": "0.6.0", - "data": { - "sample_interval_sec": 0.5, - "cpu": { - "cores": 4, - "usage_pct": 32.66, - "user_pct": 28.14, - "system_pct": 3.52, - "iowait_pct": 1.01, - "idle_pct": 67.34 - }, - "load": { - "load1": 1.79, - "load5": 1.83, - "load15": 1.67, - "runnable_procs": 7, - "total_procs": 1036 - } - }, - "summary": "os.overview cpu=32.66% mem=74.46% swap=not_configured oom_kill_since_boot=2 load1=1.79" - }, - { - "tool": "net.tcp_ping", - "params": { - "host": "10.255.255.1", - "port": 3306 - }, - "tool_version": "0.1.0", - "error": { - "code": "timeout", - "message": "tool \"net.tcp_ping\" exceeded 8000ms" - } - } - ] - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - } - } - }, - "/monit/targets": { - "post": { - "operationId": "monit-read-targets-list", - "summary": "List monitored targets", - "description": "List the targets observed under the current tenant by the monit-agent route projection. Supports `target_locator` prefix search and cursor pagination. Use this to drive `target_locator` selection for `/monit/tools/catalog` and `/monit/tools/invoke`. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id.", - "tags": [ - "Monitors/Diagnostics" - ], - "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- This is a **UI projection view**, not the live source-of-truth used by `/monit/tools/invoke`. A row in the list is no guarantee the target is currently invokable.\n- `keyword` is a **prefix** match against `target_locator` (ASCII-only, no whitespace, no `|`, max 256 bytes). Substring search is not supported in v1.\n- `limit` defaults to 50, max 200. Pagination is cursor-based: pass the previous response's `next_cursor` to fetch the next page; an empty / missing `next_cursor` means the last page.\n- Resetting `keyword`, `limit`, or the tenant context requires resetting `cursor`; never mix a cursor across different filter sets.\n- `total` is the unfiltered-by-cursor match count for the current `(account_id, keyword)` pair and stays stable across pages.\n- Fields surface `cluster_name` / `edge_ipport` for diagnostics; treat `updated_at` as \"most recently observed\" rather than a live online indicator.", - "href": "/en/api-reference/monitors/diagnostics/monit-read-targets-list", - "metadata": { - "sidebarTitle": "List monitored targets" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TargetsListRequest" - }, - "example": { - "keyword": "db-prod", - "limit": 50 - } - } - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/TargetsListResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "items": [ - { - "target_kind": "host", - "target_locator": "db-prod-01", - "agent_version": "2.0.0", - "cluster_name": "edge-a", - "edge_ipport": "10.0.0.1:19090", - "updated_at": 1710000000 - } - ], - "total": 120, - "next_cursor": "eyJ0YXJnZXRfbG9jYXRvciI6ImRiLXByb2QtMDEiLCJpZCI6MTIzNDV9" - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - } - } - }, "/change/list": { "post": { "operationId": "change-read-list", @@ -49634,332 +49314,6 @@ } } }, - "ToolCatalogRequest": { - "type": "object", - "required": [ - "target_locator" - ], - "properties": { - "account_id": { - "type": "integer", - "format": "int64", - "description": "Optional consistency check. Must equal the authenticated account when supplied." - }, - "target_locator": { - "type": "string", - "description": "Host name. Max 256 bytes; no whitespace, control characters or |." - }, - "target_kind": { - "type": "string", - "description": "Optional target kind; only host is supported. Inferred when omitted.", - "enum": [ - "host" - ] - } - } - }, - "ToolCatalogResponse": { - "type": "object", - "properties": { - "target": { - "type": "object", - "description": "Resolved target. Omitted when `target_kind` was not supplied and the locator could not be uniquely inferred.", - "properties": { - "kind": { - "type": "string", - "description": "Resolved host target kind." - }, - "locator": { - "type": "string", - "description": "Echo of the target locator from the request." - } - }, - "x-flashduty-preserve-absence": true - }, - "tools": { - "type": "array", - "description": "Tool metadata advertised by the target's agent. Always present; an empty array when `error` is set.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Tool name; pass into `/monit/tools/invoke` as `tools[].tool`." - }, - "target_kind": { - "type": "string", - "description": "Target kind this tool applies to." - }, - "description": { - "type": "string", - "description": "Tool capability description for UI / AI-SRE consumption." - }, - "input_schema": { - "type": "object", - "description": "JSON Schema for `tools[].params`." - } - } - } - }, - "error": { - "type": "object", - "description": "Request-level business error. Omitted on success. Returned with HTTP 200 — do not rely on the status code alone.", - "properties": { - "code": { - "type": "string", - "enum": [ - "target_unavailable", - "timeout", - "forward_failed", - "invalid_tool_result", - "ambiguous_target_kind" - ], - "description": "Request-level error code: `target_unavailable` target unreachable, `timeout` resolution timed out, `forward_failed` cross-instance forwarding failed, `invalid_tool_result` agent returned an invalid result, `ambiguous_target_kind` target kind not uniquely inferable." - }, - "message": { - "type": "string", - "description": "Human-readable error detail." - }, - "target_kinds": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Returned for `ambiguous_target_kind`; lists the candidate kinds.", - "x-flashduty-preserve-absence": true - } - }, - "x-flashduty-preserve-absence": true - } - } - }, - "ToolInvokeRequest": { - "type": "object", - "required": [ - "target_locator", - "tools" - ], - "properties": { - "account_id": { - "type": "integer", - "format": "int64", - "description": "Optional consistency check. Must equal the authenticated account when supplied." - }, - "target_locator": { - "type": "string", - "description": "Host name. Max 256 bytes; no whitespace, control characters or |." - }, - "target_kind": { - "type": "string", - "description": "Optional target kind; only host is supported. Inferred when omitted.", - "enum": [ - "host" - ] - }, - "tools": { - "type": "array", - "minItems": 1, - "maxItems": 8, - "description": "Up to 8 tool calls; webapi executes them concurrently and returns results in input order.", - "items": { - "type": "object", - "required": [ - "tool" - ], - "properties": { - "tool": { - "type": "string", - "description": "Tool name, typically from `/monit/tools/catalog`." - }, - "params": { - "type": "object", - "description": "Tool parameters matching the catalog `input_schema`. For no-arg tools pass `{}` explicitly.", - "additionalProperties": true - } - } - } - } - } - }, - "ToolInvokeResponse": { - "type": "object", - "properties": { - "target": { - "type": "object", - "description": "Resolved target. Omitted when `target_kind` was not supplied and the locator could not be uniquely inferred.", - "properties": { - "kind": { - "type": "string", - "description": "Resolved host target kind." - }, - "locator": { - "type": "string", - "description": "Echo of the target locator from the request." - } - }, - "x-flashduty-preserve-absence": true - }, - "results": { - "type": "array", - "description": "Per-tool results, aligned with the request `tools[]` order. Empty when a request-level `error` is present.", - "items": { - "type": "object", - "properties": { - "tool": { - "type": "string", - "description": "Tool name, aligned one-to-one with the request `tools[]` order." - }, - "params": { - "type": "object", - "description": "Request params echoed back by webapi. Normalized to `{}` when the request omitted them or sent null." - }, - "tool_version": { - "type": "string", - "description": "Agent-executed tool version. Omitted when the failure occurred before the agent picked a version.", - "x-flashduty-preserve-absence": true - }, - "data": { - "type": "object", - "description": "Tool business payload. Present only on success. Webapi already unwraps the monit-agent result envelope, so there is no nested `data.data`.", - "x-flashduty-preserve-absence": true - }, - "summary": { - "type": "string", - "description": "Human/LLM-readable one-line distillation of the result. Present only when non-empty.", - "x-flashduty-preserve-absence": true - }, - "truncated": { - "type": "object", - "description": "Present only when the result was actually truncated — the field's presence is the signal, so there is no redundant `truncated: true`.", - "properties": { - "reason": { - "type": "string", - "description": "Why the result was truncated." - } - }, - "x-flashduty-preserve-absence": true - }, - "error": { - "type": "object", - "description": "Per-tool failure. Present only on failure, and mutually exclusive with `data` / `summary` / `truncated`.", - "properties": { - "code": { - "type": "string", - "description": "Common WebAPI codes: `timeout`, `target_unavailable`, `invalid_tool_result`, `internal`, `invalid_args`, `unsupported_syntax`, `path_not_found`, and `catalog_changed`. Agent-specific tool errors may also be returned unchanged." - }, - "message": { - "type": "string", - "description": "Human-readable detail for this tool's failure; agent-side messages may be forwarded verbatim." - } - }, - "x-flashduty-preserve-absence": true - } - } - } - }, - "error": { - "type": "object", - "description": "Request-level business error. Omitted on success. Returned with HTTP 200 — do not rely on the status code alone.", - "properties": { - "code": { - "type": "string", - "enum": [ - "target_unavailable", - "forward_failed", - "ambiguous_target_kind" - ], - "description": "Request-level error code: `target_unavailable` target unreachable, `forward_failed` cross-instance forwarding failed, `ambiguous_target_kind` target kind not uniquely inferable." - }, - "message": { - "type": "string", - "description": "Human-readable error detail." - }, - "target_kinds": { - "type": "array", - "items": { - "type": "string" - }, - "x-flashduty-preserve-absence": true, - "description": "Returned only when `code` is `ambiguous_target_kind`, listing the candidate target kinds matched by the locator; omitted otherwise." - } - }, - "x-flashduty-preserve-absence": true - } - } - }, - "TargetsListRequest": { - "type": "object", - "properties": { - "account_id": { - "type": "integer", - "format": "int64", - "description": "Optional consistency check. Must equal the authenticated account when supplied." - }, - "keyword": { - "type": "string", - "description": "Prefix match against `target_locator`. ASCII only, no whitespace, no `|`, max 256 bytes. Substring search is not supported." - }, - "limit": { - "type": "integer", - "description": "Page size. Default 50, max 200.", - "default": 50, - "maximum": 200 - }, - "cursor": { - "type": "string", - "description": "Opaque pagination cursor from the previous response's `next_cursor`. Omit / pass empty string for the first page. Reset whenever `keyword`, `limit`, or tenant changes." - } - } - }, - "TargetsListResponse": { - "type": "object", - "properties": { - "items": { - "type": "array", - "items": { - "type": "object", - "properties": { - "target_kind": { - "type": "string", - "description": "Host target kind. Filtering by kind is not supported in v1." - }, - "target_locator": { - "type": "string", - "description": "Target identifier; the list is sorted by this field ascending." - }, - "agent_version": { - "type": "string", - "description": "Most recently observed Agent version." - }, - "cluster_name": { - "type": "string", - "description": "Edge cluster name." - }, - "edge_ipport": { - "type": "string", - "description": "Edge instance address (`ip:port`), surfaced for diagnostics." - }, - "updated_at": { - "type": "integer", - "format": "int64", - "description": "Last route-projection upsert time, Unix seconds. Treat as 'most recently observed', not a live-online indicator." - } - } - }, - "description": "The current page of invocable targets, sorted ascending by `target_locator`." - }, - "total": { - "type": "integer", - "format": "int64", - "description": "Total matches for the current `(account_id, keyword)` pair, independent of `cursor`." - }, - "next_cursor": { - "type": "string", - "description": "Opaque cursor for the next page. Absent / empty means this is the last page.", - "x-flashduty-preserve-absence": true - } - } - }, "ListChangeResponse": { "type": "object", "properties": { diff --git a/openapi/openapi.zh.json b/openapi/openapi.zh.json index edc6fff..fec2e1f 100644 --- a/openapi/openapi.zh.json +++ b/openapi/openapi.zh.json @@ -20281,326 +20281,6 @@ "deprecated": true } }, - "/monit/tools/catalog": { - "post": { - "operationId": "monit-read-tools-catalog", - "summary": "查询监控对象工具能力清单", - "description": "根据 `target_locator`(host)查询该监控对象上 monit-agent 当前暴露的工具能力。返回每个工具的名称、描述以及 JSON-Schema `input_schema`。配合 `/monit/tools/invoke` 驱动 AI-SRE 的工具调用。 Agent 目标仅支持 host。远端数据源取证使用 /monit/datasource/tools/invoke 和 datasource_id。", - "tags": [ - "Monitors/诊断分析" - ], - "x-mint": { - "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**；**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`（只读；不受特定权限分类约束） |\n\n## 使用说明\n\n- 使用 `target_locator` 标识监控对象；`target_kind` 可选，省略时按当前监控对象路由自动推断。\n- 若同一 locator 匹配多个 kind，响应为 HTTP 200，`data.error.code = \"ambiguous_target_kind\"`，并附带 `target_kinds` 列表——请带上显式的 `target_kind` 重试。\n- 工具能力清单是候选能力视图，并非执行保证。目标 Agent 可能在拿到清单与发起调用之间下线，本地 Agent 策略也可能在调用时拦截某些工具。\n- 每个工具条目只返回 `name`、`target_kind`、`description` 和 `input_schema`，不会暴露工具版本、输出契约、目录版本或执行限制。\n- 业务错误（`target_unavailable`、`timeout`、`forward_failed`、`invalid_tool_result`、`ambiguous_target_kind`）以 HTTP 200 返回，`data.error` 存在且 `data.tools = []`。只有协议、鉴权和内部错误才使用标准错误信封。\n- 响应采用**稀疏字段**：成功时 `error` 直接省略而非返回 `null`；当 locator 无法唯一解析时，`target` 不输出。`tools` 字段恒存在。", - "href": "/zh/api-reference/monitors/diagnostics/monit-read-tools-catalog", - "metadata": { - "sidebarTitle": "查询监控对象工具能力清单" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ToolCatalogRequest" - }, - "example": { - "account_id": 10001, - "target_locator": "web-01" - } - } - } - }, - "responses": { - "200": { - "description": "成功", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/ToolCatalogResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "target": { - "kind": "host", - "locator": "web-01" - }, - "tools": [ - { - "name": "os.overview", - "target_kind": "host", - "description": "Returns a bounded overview of host health: CPU usage and load, memory and swap utilisation, disk and network counters, and top processes.", - "input_schema": { - "type": "object", - "additionalProperties": false, - "properties": {} - } - }, - { - "name": "net.tcp_ping", - "target_kind": "host", - "description": "Checks TCP reachability of a host:port from the target, reporting connect latency.", - "input_schema": { - "type": "object", - "additionalProperties": false, - "required": [ - "host", - "port" - ], - "properties": { - "host": { - "type": "string" - }, - "port": { - "type": "integer" - } - } - } - } - ] - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - } - } - }, - "/monit/tools/invoke": { - "post": { - "operationId": "monit-read-tools-invoke", - "summary": "调用监控对象工具", - "description": "在单个监控对象上并发调用至多 8 个 monit-agent 工具。结果按入参 `tools` 数组顺序返回。长耗时——单个工具在 Agent 上有自己的超时,整体请求可能耗时数十秒。 Agent 目标仅支持 host。远端数据源取证使用 /monit/datasource/tools/invoke 和 datasource_id。", - "tags": [ - "Monitors/诊断分析" - ], - "x-mint": { - "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**；**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`（只读；不受特定权限分类约束） |\n\n## 使用说明\n\n- 单次调用至多 **8** 个工具（`MaxToolsPerInvoke`）；超出需在客户端拆分。8 个工具的上限与单监控对象 Agent 的并发能力对齐。\n- 工具在 Agent 上并行执行；webapi 返回的 `results[]` 与请求中的 `tools[]` 顺序对齐。\n- 长耗时：客户端超时至少设置 **35 秒**。该接口面向 AI-SRE / 人工排障流程，不适用于交互式 UI。\n- 请求级错误（`target_unavailable`、`ambiguous_target_kind`、`forward_failed`）以 HTTP 200 返回，`data.error` 不为空，`data.results = []`。\n- 单工具失败以 HTTP 200 返回，`data.error` 不输出，`results[i].error` 被填充——务必同时检查**三层**（外层信封 `error`、`data.error`、再到每个 `results[i].error`）。\n- 响应采用**稀疏字段**：字段不存在即表示为空。成功时 `error` 直接省略而非返回 `null`；失败时 `data`、`summary`、`truncated` 均不输出。不要依赖占位的 `null` 字段做判断；当 locator 无法唯一解析时，`target` 同样不会出现。\n- `results[i].data` 是 Tool 的业务数据，monit-agent 的 result envelope **已被解开**——不会出现嵌套的 `data.data`。一行摘要位于 `results[i].summary`；`results[i].truncated`（内含 `reason`）仅在结果确实被截断时出现。\n- `results[i].params` 回显 webapi 收到的该 Tool 调用参数，便于在批量调用中关联结果——即使其中某个 Tool 失败也能对上号。\n- 按 `/monit/tools/catalog` 返回的 `input_schema` 构造 `tools[].params`。对于无参工具，务必显式传 `params: {}`。", - "href": "/zh/api-reference/monitors/diagnostics/monit-read-tools-invoke", - "metadata": { - "sidebarTitle": "调用监控对象工具" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ToolInvokeRequest" - }, - "example": { - "account_id": 10001, - "target_locator": "web-01", - "tools": [ - { - "tool": "os.overview", - "params": {} - }, - { - "tool": "net.tcp_ping", - "params": { - "host": "10.0.0.10", - "port": 3306 - } - } - ] - } - } - } - }, - "responses": { - "200": { - "description": "成功", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/ToolInvokeResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "target": { - "kind": "host", - "locator": "web-01" - }, - "results": [ - { - "tool": "os.overview", - "params": {}, - "tool_version": "0.6.0", - "data": { - "sample_interval_sec": 0.5, - "cpu": { - "cores": 4, - "usage_pct": 32.66, - "user_pct": 28.14, - "system_pct": 3.52, - "iowait_pct": 1.01, - "idle_pct": 67.34 - }, - "load": { - "load1": 1.79, - "load5": 1.83, - "load15": 1.67, - "runnable_procs": 7, - "total_procs": 1036 - } - }, - "summary": "os.overview cpu=32.66% mem=74.46% swap=not_configured oom_kill_since_boot=2 load1=1.79" - }, - { - "tool": "net.tcp_ping", - "params": { - "host": "10.255.255.1", - "port": 3306 - }, - "tool_version": "0.1.0", - "error": { - "code": "timeout", - "message": "tool \"net.tcp_ping\" exceeded 8000ms" - } - } - ] - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - } - } - }, - "/monit/targets": { - "post": { - "operationId": "monit-read-targets-list", - "summary": "监控对象列表", - "description": "列出当前租户下被 monit-agent 路由投影所观测到的监控对象。支持 `target_locator` 前缀搜索与游标分页。用于为 `/monit/tools/catalog` 与 `/monit/tools/invoke` 选择 `target_locator`。 Agent 目标仅支持 host。远端数据源取证使用 /monit/datasource/tools/invoke 和 datasource_id。", - "tags": [ - "Monitors/诊断分析" - ], - "x-mint": { - "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 这是一个 **UI 投影视图**,不是 `/monit/tools/invoke` 所依赖的实时数据源。列表中存在不代表对应监控对象当前可被调用。\n- `keyword` 是对 `target_locator` 的**前缀匹配**(仅 ASCII,不含空白,不含 `|`,最长 256 字节)。v1 不支持子串搜索。\n- `limit` 默认 50,最大 200。分页基于游标:将上次响应中的 `next_cursor` 传入即可拉取下一页;`next_cursor` 为空或缺失表示已到末页。\n- 重置 `keyword`、`limit` 或租户上下文时必须重置 `cursor`;切勿在不同筛选条件之间复用游标。\n- `total` 是当前 `(account_id, keyword)` 组合下未受游标影响的匹配总数,跨页保持稳定。\n- 字段中暴露 `cluster_name` / `edge_ipport` 供排障使用;`updated_at` 表示\"最近一次被观测到\",而非实时在线指标。", - "href": "/zh/api-reference/monitors/diagnostics/monit-read-targets-list", - "metadata": { - "sidebarTitle": "监控对象列表" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TargetsListRequest" - }, - "example": { - "keyword": "db-prod", - "limit": 50 - } - } - } - }, - "responses": { - "200": { - "description": "成功", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SuccessEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/TargetsListResponse" - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", - "data": { - "items": [ - { - "target_kind": "host", - "target_locator": "db-prod-01", - "agent_version": "2.0.0", - "cluster_name": "edge-a", - "edge_ipport": "10.0.0.1:19090", - "updated_at": 1710000000 - } - ], - "total": 120, - "next_cursor": "eyJ0YXJnZXRfbG9jYXRvciI6ImRiLXByb2QtMDEiLCJpZCI6MTIzNDV9" - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - } - } - }, "/change/list": { "post": { "operationId": "change-read-list", @@ -49634,332 +49314,6 @@ } } }, - "ToolCatalogRequest": { - "type": "object", - "required": [ - "target_locator" - ], - "properties": { - "account_id": { - "type": "integer", - "format": "int64", - "description": "可选的一致性校验。若提供,必须等于已认证账户。" - }, - "target_locator": { - "type": "string", - "description": "主机名，最多 256 字节，不允许空白、控制字符或 |。" - }, - "target_kind": { - "type": "string", - "description": "可选目标类型，仅支持 host，省略时推断。", - "enum": [ - "host" - ] - } - } - }, - "ToolCatalogResponse": { - "type": "object", - "properties": { - "target": { - "type": "object", - "description": "解析出的目标。未传 `target_kind` 且无法根据 locator 唯一推断时，不输出该字段。", - "properties": { - "kind": { - "type": "string", - "description": "解析后的 host 目标类型。" - }, - "locator": { - "type": "string", - "description": "回显请求中的目标标识符（locator）。" - } - }, - "x-flashduty-preserve-absence": true - }, - "tools": { - "type": "array", - "description": "目标 Agent 当前声明的 Tool 元数据。该字段恒存在；出错时为空数组。", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "工具名;作为 `/monit/tools/invoke` 的 `tools[].tool` 传入。" - }, - "target_kind": { - "type": "string", - "description": "该工具适用的 target kind。" - }, - "description": { - "type": "string", - "description": "工具能力描述,供 UI / AI-SRE 使用。" - }, - "input_schema": { - "type": "object", - "description": "用于 `tools[].params` 的 JSON Schema。" - } - } - } - }, - "error": { - "type": "object", - "description": "请求级业务错误，成功时不输出。该错误以 HTTP 200 返回——不要只看状态码。", - "properties": { - "code": { - "type": "string", - "enum": [ - "target_unavailable", - "timeout", - "forward_failed", - "invalid_tool_result", - "ambiguous_target_kind" - ], - "description": "请求级错误码：`target_unavailable` 目标不可达，`timeout` 解析超时，`forward_failed` 跨实例转发失败，`invalid_tool_result` Agent 返回结果非法，`ambiguous_target_kind` 无法唯一推断目标类型。" - }, - "message": { - "type": "string", - "description": "人类可读的错误详情。" - }, - "target_kinds": { - "type": "array", - "items": { - "type": "string" - }, - "description": "在 `ambiguous_target_kind` 时返回;列出候选的 kind。", - "x-flashduty-preserve-absence": true - } - }, - "x-flashduty-preserve-absence": true - } - } - }, - "ToolInvokeRequest": { - "type": "object", - "required": [ - "target_locator", - "tools" - ], - "properties": { - "account_id": { - "type": "integer", - "format": "int64", - "description": "可选的一致性校验。若提供,必须等于已认证账户。" - }, - "target_locator": { - "type": "string", - "description": "主机名，最多 256 字节，不允许空白、控制字符或 |。" - }, - "target_kind": { - "type": "string", - "description": "可选目标类型，仅支持 host，省略时推断。", - "enum": [ - "host" - ] - }, - "tools": { - "type": "array", - "minItems": 1, - "maxItems": 8, - "description": "至多 8 个工具调用;webapi 会并发执行,并按入参顺序返回结果。", - "items": { - "type": "object", - "required": [ - "tool" - ], - "properties": { - "tool": { - "type": "string", - "description": "工具名,通常来自 `/monit/tools/catalog`。" - }, - "params": { - "type": "object", - "description": "符合工具能力清单中 `input_schema` 的参数。无参工具请显式传 `{}`。", - "additionalProperties": true - } - } - } - } - } - }, - "ToolInvokeResponse": { - "type": "object", - "properties": { - "target": { - "type": "object", - "description": "解析出的目标。未传 `target_kind` 且无法根据 locator 唯一推断时，不输出该字段。", - "properties": { - "kind": { - "type": "string", - "description": "解析后的 host 目标类型。" - }, - "locator": { - "type": "string", - "description": "回显请求中的目标标识符（locator）。" - } - }, - "x-flashduty-preserve-absence": true - }, - "results": { - "type": "array", - "description": "各 Tool 的执行结果，与请求中 `tools[]` 的顺序对齐。存在请求级 `error` 时为空数组。", - "items": { - "type": "object", - "properties": { - "tool": { - "type": "string", - "description": "Tool 名称，与请求中 `tools[]` 的顺序一一对应。" - }, - "params": { - "type": "object", - "description": "WebAPI 从原始请求回填的调用参数。请求中缺省或为 null 时规范化为 `{}`。" - }, - "tool_version": { - "type": "string", - "description": "Agent 实际执行的 Tool 版本。若失败发生在 Agent 选定版本之前，则不输出该字段。", - "x-flashduty-preserve-absence": true - }, - "data": { - "type": "object", - "description": "Tool 的业务数据，仅成功时输出。WebAPI 已解开 monit-agent 的 result envelope，因此不会出现嵌套的 `data.data`。", - "x-flashduty-preserve-absence": true - }, - "summary": { - "type": "string", - "description": "人类 / LLM 可读的一行结果摘要，仅在非空时输出。", - "x-flashduty-preserve-absence": true - }, - "truncated": { - "type": "object", - "description": "仅在结果确实被截断时输出——字段存在本身即表示已截断，因此不再输出冗余的 `truncated: true`。", - "properties": { - "reason": { - "type": "string", - "description": "结果被截断的原因。" - } - }, - "x-flashduty-preserve-absence": true - }, - "error": { - "type": "object", - "description": "单 Tool 失败信息。仅失败时输出，与 `data` / `summary` / `truncated` 互斥。", - "properties": { - "code": { - "type": "string", - "description": "常见 WebAPI 错误码：`timeout`、`target_unavailable`、`invalid_tool_result`、`internal`、`invalid_args`、`unsupported_syntax`、`path_not_found` 和 `catalog_changed`。Agent 特有的工具错误也可能原样返回。" - }, - "message": { - "type": "string", - "description": "该 Tool 失败的人类可读错误详情；Agent 侧错误信息可能原样透传。" - } - }, - "x-flashduty-preserve-absence": true - } - } - } - }, - "error": { - "type": "object", - "description": "请求级业务错误，成功时不输出。该错误以 HTTP 200 返回——不要只看状态码。", - "properties": { - "code": { - "type": "string", - "enum": [ - "target_unavailable", - "forward_failed", - "ambiguous_target_kind" - ], - "description": "请求级错误码：`target_unavailable` 目标不可达，`forward_failed` 跨实例转发失败，`ambiguous_target_kind` 无法唯一推断目标类型。" - }, - "message": { - "type": "string", - "description": "人类可读的错误详情。" - }, - "target_kinds": { - "type": "array", - "items": { - "type": "string" - }, - "x-flashduty-preserve-absence": true, - "description": "仅当 `code` 为 `ambiguous_target_kind` 时返回，列出该 locator 命中的候选 target kind；其他情况省略。" - } - }, - "x-flashduty-preserve-absence": true - } - } - }, - "TargetsListRequest": { - "type": "object", - "properties": { - "account_id": { - "type": "integer", - "format": "int64", - "description": "可选的一致性校验。若提供,必须等于已认证账户。" - }, - "keyword": { - "type": "string", - "description": "对 `target_locator` 的前缀匹配。仅 ASCII,不含空白,不含 `|`,最长 256 字节。不支持子串搜索。" - }, - "limit": { - "type": "integer", - "description": "分页大小。默认 50,最大 200。", - "default": 50, - "maximum": 200 - }, - "cursor": { - "type": "string", - "description": "来自上次响应的 `next_cursor` 的不透明游标。首页请省略或传空串。变更 `keyword`、`limit` 或租户时必须重置。" - } - } - }, - "TargetsListResponse": { - "type": "object", - "properties": { - "items": { - "type": "array", - "items": { - "type": "object", - "properties": { - "target_kind": { - "type": "string", - "description": "主机目标类型 host。v1 不支持按 kind 过滤。" - }, - "target_locator": { - "type": "string", - "description": "监控对象标识;列表按此字段升序排序。" - }, - "agent_version": { - "type": "string", - "description": "最近一次观测到的 Agent 版本。" - }, - "cluster_name": { - "type": "string", - "description": "边缘集群名。" - }, - "edge_ipport": { - "type": "string", - "description": "边缘实例地址(`ip:port`),供排障使用。" - }, - "updated_at": { - "type": "integer", - "format": "int64", - "description": "最近一次路由投影写入时间,Unix 秒。视为\"最近一次被观测到\",而非实时在线指标。" - } - } - }, - "description": "当前页的可调用目标（target）列表，按 `target_locator` 升序排列。" - }, - "total": { - "type": "integer", - "format": "int64", - "description": "当前 `(account_id, keyword)` 组合下的匹配总数,与 `cursor` 无关。" - }, - "next_cursor": { - "type": "string", - "description": "下一页的不透明游标。缺失 / 为空表示已到末页。", - "x-flashduty-preserve-absence": true - } - } - }, "ListChangeResponse": { "type": "object", "properties": { diff --git a/roundtrip_gen_test.go b/roundtrip_gen_test.go index 979b710..e8ed7b3 100644 --- a/roundtrip_gen_test.go +++ b/roundtrip_gen_test.go @@ -130,9 +130,6 @@ var exampleDataDecoders = map[string]func(json.RawMessage) error{ "POST /monit/store/ruleset/info": func(d json.RawMessage) error { var v StoreRulesetItem; return json.Unmarshal(d, &v) }, "POST /monit/store/ruleset/list": func(d json.RawMessage) error { var v StoreRulesetListResponse; return json.Unmarshal(d, &v) }, "POST /monit/store/ruleset/update": func(d json.RawMessage) error { var v StoreRulesetItem; return json.Unmarshal(d, &v) }, - "POST /monit/targets": func(d json.RawMessage) error { var v TargetsListResponse; return json.Unmarshal(d, &v) }, - "POST /monit/tools/catalog": func(d json.RawMessage) error { var v ToolCatalogResponse; return json.Unmarshal(d, &v) }, - "POST /monit/tools/invoke": func(d json.RawMessage) error { var v ToolInvokeResponse; return json.Unmarshal(d, &v) }, "POST /oncall/license/list": func(d json.RawMessage) error { var v LicenseListResponse; return json.Unmarshal(d, &v) }, "POST /person/infos": func(d json.RawMessage) error { var v PersonInfosResponse; return json.Unmarshal(d, &v) }, "POST /role/info": func(d json.RawMessage) error { var v RoleItem; return json.Unmarshal(d, &v) },