From ce93a1441840351d8231e85f4009ad766641a186 Mon Sep 17 00:00:00 2001 From: ysyneu Date: Tue, 11 Aug 2026 07:52:37 -0700 Subject: [PATCH] chore: sync OpenAPI spec from flashduty-docs + regenerate Picks up the 9 new AI SRE knowledge endpoints (/safari/knowledge/*: pack get/list/ensure/update/delete, file get/list/put/delete), adding the generated KnowledgeService and its request/response models. --- knowledge.go | 134 ++++ models_gen.go | 179 ++++++ openapi/openapi.en.json | 1315 +++++++++++++++++++++++++++++++++++++++ openapi/openapi.zh.json | 1315 +++++++++++++++++++++++++++++++++++++++ roundtrip_gen_test.go | 9 + services_gen.go | 2 + 6 files changed, 2954 insertions(+) create mode 100644 knowledge.go diff --git a/knowledge.go b/knowledge.go new file mode 100644 index 0000000..79e069a --- /dev/null +++ b/knowledge.go @@ -0,0 +1,134 @@ +// Code generated by internal/cmd/gen; DO NOT EDIT. + +package flashduty + +import "context" + +// KnowledgeService handles the "AI SRE/Knowledge" API resource. +type KnowledgeService service + +// Get knowledge file. +// +// Return a knowledge file's metadata and its base64-encoded content. +// +// API: POST /safari/knowledge/file/get (knowledge-file-read-get). +func (s *KnowledgeService) FileReadGet(ctx context.Context, req *KnowledgeFileGetRequest) (*KnowledgeFileGetResponse, *Response, error) { + out := new(KnowledgeFileGetResponse) + resp, err := s.client.do(ctx, "/safari/knowledge/file/get", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + +// List knowledge files. +// +// List the files in a knowledge pack with metadata such as size and checksum. +// +// API: POST /safari/knowledge/file/list (knowledge-file-read-list). +func (s *KnowledgeService) FileReadList(ctx context.Context, req *KnowledgeFileListRequest) (*KnowledgeFileListResponse, *Response, error) { + out := new(KnowledgeFileListResponse) + resp, err := s.client.do(ctx, "/safari/knowledge/file/list", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + +// Delete knowledge file. +// +// Delete a file from a knowledge pack by its relative path. +// +// API: POST /safari/knowledge/file/delete (knowledge-file-write-delete). +func (s *KnowledgeService) FileWriteDelete(ctx context.Context, req *KnowledgeFileDeleteRequest) (*KnowledgeFileDeleteResponse, *Response, error) { + out := new(KnowledgeFileDeleteResponse) + resp, err := s.client.do(ctx, "/safari/knowledge/file/delete", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + +// Upload knowledge file. +// +// Create or overwrite a file in a knowledge pack with base64-encoded content. +// +// API: POST /safari/knowledge/file/put (knowledge-file-write-put). +func (s *KnowledgeService) FileWritePut(ctx context.Context, req *KnowledgeFilePutRequest) (*KnowledgeFilePutResponse, *Response, error) { + out := new(KnowledgeFilePutResponse) + resp, err := s.client.do(ctx, "/safari/knowledge/file/put", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + +// Get account knowledge pack. +// +// Return the account-scope knowledge pack metadata and its file list. +// +// API: POST /safari/knowledge/get (knowledge-pack-read-get). +func (s *KnowledgeService) PackReadGet(ctx context.Context) (*KnowledgeGetResponse, *Response, error) { + out := new(KnowledgeGetResponse) + resp, err := s.client.do(ctx, "/safari/knowledge/get", nil, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + +// List knowledge packs. +// +// List knowledge packs visible to the caller across account and team scopes. +// +// API: POST /safari/knowledge/pack/list (knowledge-pack-read-list). +func (s *KnowledgeService) PackReadList(ctx context.Context, req *KnowledgePackListRequest) (*KnowledgePackListResponse, *Response, error) { + out := new(KnowledgePackListResponse) + resp, err := s.client.do(ctx, "/safari/knowledge/pack/list", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + +// Delete knowledge pack. +// +// Delete a knowledge pack and all of its files. +// +// API: POST /safari/knowledge/pack/delete (knowledge-pack-write-delete). +func (s *KnowledgeService) PackWriteDelete(ctx context.Context, req *KnowledgePackDeleteRequest) (*KnowledgePackDeleteResponse, *Response, error) { + out := new(KnowledgePackDeleteResponse) + resp, err := s.client.do(ctx, "/safari/knowledge/pack/delete", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + +// Ensure knowledge pack. +// +// Idempotently create the knowledge pack at the given scope, or return the existing one. +// +// API: POST /safari/knowledge/pack/ensure (knowledge-pack-write-ensure). +func (s *KnowledgeService) PackWriteEnsure(ctx context.Context, req *KnowledgePackEnsureRequest) (*KnowledgePackItem, *Response, error) { + out := new(KnowledgePackItem) + resp, err := s.client.do(ctx, "/safari/knowledge/pack/ensure", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} + +// Update knowledge pack. +// +// Move a knowledge pack to a different account or team scope. +// +// API: POST /safari/knowledge/pack/update (knowledge-pack-write-update). +func (s *KnowledgeService) PackWriteUpdate(ctx context.Context, req *KnowledgePackUpdateRequest) (*KnowledgePackItem, *Response, error) { + out := new(KnowledgePackItem) + resp, err := s.client.do(ctx, "/safari/knowledge/pack/update", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} diff --git a/models_gen.go b/models_gen.go index a863d8d..29203dc 100644 --- a/models_gen.go +++ b/models_gen.go @@ -4000,6 +4000,185 @@ type InviteMemberItem struct { TimeZone string `json:"time_zone,omitempty" toon:"time_zone,omitempty"` } +// KnowledgeFileDeleteRequest is generated from the Flashduty OpenAPI schema. +type KnowledgeFileDeleteRequest struct { + // Delete even when other pack files reference this file; the referrers are then returned as warnings instead of blocking the delete. + Force bool `json:"force,omitempty" toon:"force,omitempty"` + // Knowledge pack ID; defaults to the caller's account-scope pack. + PackID string `json:"pack_id,omitempty" toon:"pack_id,omitempty"` + // Path of the file relative to the pack root. + RelPath string `json:"rel_path" toon:"rel_path"` +} + +// KnowledgeFileDeleteResponse is generated from the Flashduty OpenAPI schema. +type KnowledgeFileDeleteResponse struct { + Warnings []KnowledgeWarning `json:"warnings" toon:"warnings"` +} + +// KnowledgeFileGetRequest is generated from the Flashduty OpenAPI schema. +type KnowledgeFileGetRequest struct { + // Knowledge pack ID; defaults to the caller's account-scope pack. + PackID string `json:"pack_id,omitempty" toon:"pack_id,omitempty"` + // Path of the file relative to the pack root. + RelPath string `json:"rel_path" toon:"rel_path"` +} + +// KnowledgeFileGetResponse is generated from the Flashduty OpenAPI schema. +type KnowledgeFileGetResponse struct { + // Base64-encoded file content; decodes to UTF-8 text. + ContentB64 string `json:"content_b64" toon:"content_b64"` + File KnowledgeFileItem `json:"file" toon:"file"` +} + +// KnowledgeFileItem is generated from the Flashduty OpenAPI schema. +type KnowledgeFileItem struct { + // SHA-256 hex digest of the file content. + Checksum string `json:"checksum" toon:"checksum"` + // MIME type; inferred from the file extension when not set on upload. + ContentType string `json:"content_type" toon:"content_type"` + // File ID (`kfl_` prefix). + FileID string `json:"file_id" toon:"file_id"` + // ID of the knowledge pack that contains the file. + PackID string `json:"pack_id" toon:"pack_id"` + // Path relative to the pack root, e.g. `runbooks/restart.md`. + RelPath string `json:"rel_path" toon:"rel_path"` + // File size in bytes. + SizeBytes int64 `json:"size_bytes" toon:"size_bytes"` + // Unix timestamp in milliseconds when the file was last modified. + UpdatedAtMs TimestampMilli `json:"updated_at_ms" toon:"updated_at_ms"` + // Person ID of the member who last modified the file. + UpdatedBy int64 `json:"updated_by" toon:"updated_by"` +} + +// KnowledgeFileListRequest is generated from the Flashduty OpenAPI schema. +type KnowledgeFileListRequest struct { + ListOptions + // Knowledge pack ID; defaults to the caller's account-scope pack. + PackID string `json:"pack_id,omitempty" toon:"pack_id,omitempty"` +} + +// KnowledgeFileListResponse is generated from the Flashduty OpenAPI schema. +type KnowledgeFileListResponse struct { + Files []KnowledgeFileItem `json:"files" toon:"files"` + // Total number of files in the pack. + Total int64 `json:"total" toon:"total"` +} + +// KnowledgeFilePutRequest is generated from the Flashduty OpenAPI schema. +type KnowledgeFilePutRequest struct { + // Base64-encoded file content; must decode to valid UTF-8 text. + ContentB64 string `json:"content_b64,omitempty" toon:"content_b64,omitempty"` + // MIME type; inferred from the file extension when omitted. + ContentType string `json:"content_type,omitempty" toon:"content_type,omitempty"` + // Knowledge pack ID; defaults to the caller's account-scope pack. + PackID string `json:"pack_id,omitempty" toon:"pack_id,omitempty"` + // Destination path relative to the pack root; existing files are overwritten. + RelPath string `json:"rel_path" toon:"rel_path"` +} + +// KnowledgeFilePutResponse is generated from the Flashduty OpenAPI schema. +type KnowledgeFilePutResponse struct { + File KnowledgeFileItem `json:"file" toon:"file"` + Warnings []KnowledgeWarning `json:"warnings" toon:"warnings"` +} + +// KnowledgeGetRequest is generated from the Flashduty OpenAPI schema. +type KnowledgeGetRequest struct{} + +// KnowledgeGetResponse is generated from the Flashduty OpenAPI schema. +type KnowledgeGetResponse struct { + Files []KnowledgeFileItem `json:"files" toon:"files"` + Pack KnowledgePackItem `json:"pack" toon:"pack"` +} + +// KnowledgePackDeleteRequest is generated from the Flashduty OpenAPI schema. +type KnowledgePackDeleteRequest struct { + // Knowledge pack ID to delete. + PackID string `json:"pack_id" toon:"pack_id"` +} + +// KnowledgePackDeleteResponse is generated from the Flashduty OpenAPI schema. +type KnowledgePackDeleteResponse struct { + // True when the pack was deleted. + OK bool `json:"ok" toon:"ok"` +} + +// KnowledgePackEnsureRequest is generated from the Flashduty OpenAPI schema. +type KnowledgePackEnsureRequest struct { + // Scope of the pack to ensure. + Scope string `json:"scope" toon:"scope"` + // Team ID; required for `team` scope, ignored for `account` scope. + ScopeID int64 `json:"scope_id,omitempty" toon:"scope_id,omitempty"` +} + +// KnowledgePackItem is generated from the Flashduty OpenAPI schema. +type KnowledgePackItem struct { + // Account that owns the pack. + AccountID int64 `json:"account_id" toon:"account_id"` + // Whether the caller can edit this pack. + CanEdit bool `json:"can_edit" toon:"can_edit"` + // Unix timestamp in milliseconds when the pack was created. + CreatedAtMs TimestampMilli `json:"created_at_ms" toon:"created_at_ms"` + // Person ID of the member who created the pack. + CreatedBy int64 `json:"created_by" toon:"created_by"` + // Number of files in the pack. + FileCount int64 `json:"file_count" toon:"file_count"` + // Knowledge pack ID (`kpk_` prefix). + PackID string `json:"pack_id" toon:"pack_id"` + // Pack scope. `channel` is a legacy scope; new packs are `account` or `team`. + Scope string `json:"scope" toon:"scope"` + // Scope owner: the account ID for `account` scope, the team ID for `team` scope. + ScopeID int64 `json:"scope_id" toon:"scope_id"` + // Display name of the owning team (team scope only); empty for account scope. + TeamName string `json:"team_name" toon:"team_name"` + // Total size of all files in bytes. + TotalBytes int64 `json:"total_bytes" toon:"total_bytes"` + // Unix timestamp in milliseconds when the pack was last modified. + UpdatedAtMs TimestampMilli `json:"updated_at_ms" toon:"updated_at_ms"` + // Pack version, incremented on every file change. + Version int64 `json:"version" toon:"version"` +} + +// KnowledgePackListRequest is generated from the Flashduty OpenAPI schema. +type KnowledgePackListRequest struct { + ListOptions + // Include the account-scope pack; defaults to true. + IncludeAccount *bool `json:"include_account,omitempty" toon:"include_account,omitempty"` + // Case-insensitive substring filter over pack ID, scope, and team name. + Query string `json:"query,omitempty" toon:"query,omitempty"` + // Restrict to one scope; `all` (default) overrides `include_account`. + Scope string `json:"scope,omitempty" toon:"scope,omitempty"` + // Restrict to these team IDs; for non-admins the list is intersected with their own teams. + TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` +} + +// KnowledgePackListResponse is generated from the Flashduty OpenAPI schema. +type KnowledgePackListResponse struct { + Packs []KnowledgePackItem `json:"packs" toon:"packs"` + // Total number of packs after filtering, before pagination. + Total int64 `json:"total" toon:"total"` +} + +// KnowledgePackUpdateRequest is generated from the Flashduty OpenAPI schema. +type KnowledgePackUpdateRequest struct { + // Knowledge pack ID to update. + PackID string `json:"pack_id" toon:"pack_id"` + // Destination scope; omit for a no-op that returns the current pack. + Scope *string `json:"scope,omitempty" toon:"scope,omitempty"` + // Destination team ID; required when `scope` is `team`, set automatically for `account`. + ScopeID *int64 `json:"scope_id,omitempty" toon:"scope_id,omitempty"` +} + +// KnowledgeWarning is generated from the Flashduty OpenAPI schema. +type KnowledgeWarning struct { + // Warning code. + Code string `json:"code" toon:"code"` + // Single reference related to the warning. + Ref string `json:"ref" toon:"ref"` + // Multiple references related to the warning. + Refs []string `json:"refs" toon:"refs"` +} + // LicenseListResponse is generated from the Flashduty OpenAPI schema. type LicenseListResponse struct { // People holding an active license. diff --git a/openapi/openapi.en.json b/openapi/openapi.en.json index 31d94de..5a2ec03 100644 --- a/openapi/openapi.en.json +++ b/openapi/openapi.en.json @@ -167,6 +167,9 @@ { "name": "RUM/Resources", "description": "Query the RUM resource record and current usage for the account." + }, + { + "name": "AI SRE/Knowledge" } ], "paths": { @@ -29911,6 +29914,843 @@ } } } + }, + "/safari/knowledge/get": { + "post": { + "operationId": "knowledge-pack-read-get", + "summary": "Get account knowledge pack", + "description": "Return the account-scope knowledge pack metadata and its file list.", + "tags": [ + "AI SRE/Knowledge" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Always targets the caller's account-scope pack — there is no `pack_id` parameter; use `POST /safari/knowledge/pack/list` to discover team packs.\n- The account pack is created lazily on first access, so a valid account never gets not-found here.\n", + "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-get", + "metadata": { + "sidebarTitle": "Get account knowledge pack" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgeGetResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "pack": { + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "account_id": 2451002751131, + "scope": "account", + "scope_id": 2451002751131, + "file_count": 17, + "total_bytes": 41010, + "version": 134, + "created_by": 2476444212131, + "created_at_ms": 1778768680053, + "updated_at_ms": 1786456567177, + "can_edit": true + }, + "files": [ + { + "file_id": "kfl_QvT4g3c8zAHxTthuT6hGne", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "aliyun.md", + "content_type": "text/markdown", + "size_bytes": 1436, + "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f", + "updated_by": 3790925372131, + "updated_at_ms": 1783311304757 + }, + { + "file_id": "kfl_BMsQZCZSqhW4TFskYNb4H5", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "DUTY.md", + "content_type": "text/markdown", + "size_bytes": 1301, + "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b", + "updated_by": 2476444212131, + "updated_at_ms": 1784800003394 + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeGetRequest" + }, + "example": {} + } + } + } + } + }, + "/safari/knowledge/pack/list": { + "post": { + "operationId": "knowledge-pack-read-list", + "summary": "List knowledge packs", + "description": "List knowledge packs visible to the caller across account and team scopes.", + "tags": [ + "AI SRE/Knowledge" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Visibility matches the console: admins see the account pack plus every team pack; non-admins see the account pack plus their own teams, and requested `team_ids` are silently intersected with their teams.\n- `scope` selects `all` (default), `account`-only, or `team`-only, overriding `include_account`.\n- `query` applies a case-insensitive substring filter over pack ID, scope, and team name; `p`/`limit` paginate the filtered result.\n", + "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-list", + "metadata": { + "sidebarTitle": "List knowledge packs" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgePackListResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "packs": [ + { + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "account_id": 2451002751131, + "scope": "account", + "scope_id": 2451002751131, + "file_count": 17, + "total_bytes": 41010, + "version": 134, + "created_by": 2476444212131, + "created_at_ms": 1778768680053, + "updated_at_ms": 1786456567177, + "can_edit": true + }, + { + "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy", + "account_id": 2451002751131, + "scope": "team", + "scope_id": 2477033058131, + "team_name": "研发团队", + "file_count": 4, + "total_bytes": 11159, + "version": 15, + "created_by": 2476444212131, + "created_at_ms": 1782201586089, + "updated_at_ms": 1785462092702, + "can_edit": true + } + ], + "total": 3 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgePackListRequest" + }, + "example": { + "p": 1, + "limit": 20, + "scope": "all", + "include_account": true + } + } + } + } + } + }, + "/safari/knowledge/pack/ensure": { + "post": { + "operationId": "knowledge-pack-write-ensure", + "summary": "Ensure knowledge pack", + "description": "Idempotently create the knowledge pack at the given scope, or return the existing one.", + "tags": [ + "AI SRE/Knowledge" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Idempotent: if a pack already exists at (`scope`, `scope_id`), it is returned unchanged.\n- For `account` scope, `scope_id` is ignored (the account ID is used) and a default `DUTY.md` is seeded on first creation.\n- Creating the account-scope pack requires account owner/admin; creating into a team requires membership of that team.\n- Every call is recorded in the account audit log.\n", + "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure", + "metadata": { + "sidebarTitle": "Ensure knowledge pack" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgePackItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "account_id": 2451002751131, + "scope": "account", + "scope_id": 2451002751131, + "file_count": 17, + "total_bytes": 41010, + "version": 138, + "created_by": 2476444212131, + "created_at_ms": 1778768680053, + "updated_at_ms": 1786458765182, + "can_edit": true + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgePackEnsureRequest" + }, + "example": { + "scope": "team", + "scope_id": 2477033058131 + } + } + } + } + } + }, + "/safari/knowledge/pack/update": { + "post": { + "operationId": "knowledge-pack-write-update", + "summary": "Update knowledge pack", + "description": "Move a knowledge pack to a different account or team scope.", + "tags": [ + "AI SRE/Knowledge" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- `scope` is the only mutable field; omitting it is a no-op that returns the current pack.\n- For `team` scope, `scope_id` is required; for `account` scope it is set to the account ID automatically.\n- The move fails with `ReferenceExist` when the destination scope already has a pack — packs are never merged.\n- Every call is recorded in the account audit log.\n", + "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-update", + "metadata": { + "sidebarTitle": "Update knowledge pack" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgePackItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy", + "account_id": 2451002751131, + "scope": "team", + "scope_id": 2477033058131, + "team_name": "研发团队", + "file_count": 4, + "total_bytes": 11159, + "version": 15, + "created_by": 2476444212131, + "created_at_ms": 1782201586089, + "updated_at_ms": 1785462092702, + "can_edit": true + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgePackUpdateRequest" + }, + "example": { + "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy", + "scope": "team", + "scope_id": 2477033058131 + } + } + } + } + } + }, + "/safari/knowledge/pack/delete": { + "post": { + "operationId": "knowledge-pack-write-delete", + "summary": "Delete knowledge pack", + "description": "Delete a knowledge pack and all of its files.", + "tags": [ + "AI SRE/Knowledge" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting a pack removes every file it contains; the operation cannot be undone.\n- Deleting the account-scope pack is allowed; it is re-created empty on next access.\n- Every call is recorded in the account audit log.\n", + "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-delete", + "metadata": { + "sidebarTitle": "Delete knowledge pack" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgePackDeleteResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "ok": true + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgePackDeleteRequest" + }, + "example": { + "pack_id": "kpk_YqHXPTEUHQFGepUfRS7vsh" + } + } + } + } + } + }, + "/safari/knowledge/file/list": { + "post": { + "operationId": "knowledge-file-read-list", + "summary": "List knowledge files", + "description": "List the files in a knowledge pack with metadata such as size and checksum.", + "tags": [ + "AI SRE/Knowledge" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Omitting `pack_id` targets the caller's account-scope pack (created lazily if absent).\n- Reading a team-scope pack requires membership of that team.\n- `p`/`limit` are accepted but the current implementation always returns the full file list.\n", + "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-list", + "metadata": { + "sidebarTitle": "List knowledge files" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgeFileListResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "files": [ + { + "file_id": "kfl_QvT4g3c8zAHxTthuT6hGne", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "aliyun.md", + "content_type": "text/markdown", + "size_bytes": 1436, + "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f", + "updated_by": 3790925372131, + "updated_at_ms": 1783311304757 + }, + { + "file_id": "kfl_BMsQZCZSqhW4TFskYNb4H5", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "DUTY.md", + "content_type": "text/markdown", + "size_bytes": 1301, + "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b", + "updated_by": 2476444212131, + "updated_at_ms": 1784800003394 + } + ], + "total": 17 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeFileListRequest" + }, + "example": { + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc" + } + } + } + } + } + }, + "/safari/knowledge/file/get": { + "post": { + "operationId": "knowledge-file-read-get", + "summary": "Get knowledge file", + "description": "Return a knowledge file's metadata and its base64-encoded content.", + "tags": [ + "AI SRE/Knowledge" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Content is returned in `content_b64` (base64); pack files are guaranteed UTF-8 text.\n- Omitting `pack_id` targets the account-scope pack; reading a team-scope pack requires team membership.\n- A missing file returns `ResourceNotFound` (HTTP 400).\n", + "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-get", + "metadata": { + "sidebarTitle": "Get knowledge file" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgeFileGetResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "file": { + "file_id": "kfl_gctXKRG45aFQGgxSFr59WY", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "tmp/openapi-example.md", + "content_type": "text/markdown", + "size_bytes": 50, + "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d", + "updated_by": 2476444212131, + "updated_at_ms": 1786458764961 + }, + "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeFileGetRequest" + }, + "example": { + "rel_path": "tmp/openapi-example.md" + } + } + } + } + } + }, + "/safari/knowledge/file/put": { + "post": { + "operationId": "knowledge-file-write-put", + "summary": "Upload knowledge file", + "description": "Create or overwrite a file in a knowledge pack with base64-encoded content.", + "tags": [ + "AI SRE/Knowledge" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- The file body is sent as base64 text in the JSON field `content_b64` — this is not a multipart upload.\n- Writing an existing `rel_path` overwrites it; `content_type` is inferred from the extension when omitted (`.md` → `text/markdown`).\n- Content must decode to valid UTF-8 text; binary payloads are rejected with `InvalidParameter`.\n- Editing the account-scope pack requires account owner/admin; editing a team pack requires team membership.\n- Every call is recorded in the account audit log.\n", + "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-put", + "metadata": { + "sidebarTitle": "Upload knowledge file" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgeFilePutResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "file": { + "file_id": "kfl_gctXKRG45aFQGgxSFr59WY", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "tmp/openapi-example.md", + "content_type": "text/markdown", + "size_bytes": 50, + "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d", + "updated_by": 2476444212131, + "updated_at_ms": 1786458764961 + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeFilePutRequest" + }, + "example": { + "rel_path": "tmp/openapi-example.md", + "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=", + "content_type": "text/markdown" + } + } + } + } + } + }, + "/safari/knowledge/file/delete": { + "post": { + "operationId": "knowledge-file-write-delete", + "summary": "Delete knowledge file", + "description": "Delete a file from a knowledge pack by its relative path.", + "tags": [ + "AI SRE/Knowledge" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting is idempotent — removing a file that does not exist succeeds.\n- When other pack files still reference the target, the delete fails with `ReferenceExist` listing the referrers; set `force` to proceed (the referrers are returned as warnings).\n- Omitting `pack_id` targets the account-scope pack; editing the account pack requires account owner/admin, editing a team pack requires team membership.\n- Every call is recorded in the account audit log.\n", + "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-delete", + "metadata": { + "sidebarTitle": "Delete knowledge file" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgeFileDeleteResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeFileDeleteRequest" + }, + "example": { + "rel_path": "tmp/openapi-delete-example.md" + } + } + } + } + } } }, "components": { @@ -56966,6 +57806,481 @@ "description": "Unix timestamp in seconds when the on-premises license expires. Only present on on-premises deployments; omitted entirely for SaaS accounts." } } + }, + "KnowledgePackItem": { + "type": "object", + "description": "A knowledge pack — a versioned file tree staged into every AI SRE sandbox at session start. One pack exists per (account, scope, scope_id).", + "properties": { + "pack_id": { + "type": "string", + "description": "Knowledge pack ID (`kpk_` prefix)." + }, + "account_id": { + "type": "integer", + "description": "Account that owns the pack.", + "format": "int64" + }, + "scope": { + "type": "string", + "description": "Pack scope. `channel` is a legacy scope; new packs are `account` or `team`.", + "enum": [ + "account", + "team", + "channel" + ] + }, + "scope_id": { + "type": "integer", + "description": "Scope owner: the account ID for `account` scope, the team ID for `team` scope.", + "format": "int64" + }, + "team_name": { + "type": "string", + "description": "Display name of the owning team (team scope only); empty for account scope." + }, + "file_count": { + "type": "integer", + "description": "Number of files in the pack." + }, + "total_bytes": { + "type": "integer", + "description": "Total size of all files in bytes.", + "format": "int64" + }, + "version": { + "type": "integer", + "description": "Pack version, incremented on every file change." + }, + "created_by": { + "type": "integer", + "description": "Person ID of the member who created the pack.", + "format": "int64" + }, + "created_at_ms": { + "type": "integer", + "description": "Unix timestamp in milliseconds when the pack was created.", + "format": "int64" + }, + "updated_at_ms": { + "type": "integer", + "description": "Unix timestamp in milliseconds when the pack was last modified.", + "format": "int64" + }, + "can_edit": { + "type": "boolean", + "description": "Whether the caller can edit this pack." + } + }, + "required": [ + "pack_id", + "account_id", + "scope", + "scope_id", + "file_count", + "total_bytes", + "version", + "created_by", + "created_at_ms", + "updated_at_ms", + "can_edit" + ] + }, + "KnowledgeFileItem": { + "type": "object", + "description": "Metadata of one file inside a knowledge pack. Content is fetched separately via file/get.", + "properties": { + "file_id": { + "type": "string", + "description": "File ID (`kfl_` prefix)." + }, + "pack_id": { + "type": "string", + "description": "ID of the knowledge pack that contains the file." + }, + "rel_path": { + "type": "string", + "description": "Path relative to the pack root, e.g. `runbooks/restart.md`." + }, + "content_type": { + "type": "string", + "description": "MIME type; inferred from the file extension when not set on upload." + }, + "size_bytes": { + "type": "integer", + "description": "File size in bytes.", + "format": "int64" + }, + "checksum": { + "type": "string", + "description": "SHA-256 hex digest of the file content." + }, + "updated_by": { + "type": "integer", + "description": "Person ID of the member who last modified the file.", + "format": "int64" + }, + "updated_at_ms": { + "type": "integer", + "description": "Unix timestamp in milliseconds when the file was last modified.", + "format": "int64" + } + }, + "required": [ + "file_id", + "pack_id", + "rel_path", + "content_type", + "size_bytes", + "checksum", + "updated_by", + "updated_at_ms" + ] + }, + "KnowledgeWarning": { + "type": "object", + "description": "Non-blocking annotation returned by file uploads and deletions, e.g. references that point at a removed file.", + "properties": { + "code": { + "type": "string", + "description": "Warning code.", + "enum": [ + "unresolved_reference", + "still_referenced_by" + ] + }, + "ref": { + "type": "string", + "description": "Single reference related to the warning." + }, + "refs": { + "type": "array", + "description": "Multiple references related to the warning.", + "items": { + "type": "string" + } + } + }, + "required": [ + "code" + ] + }, + "KnowledgeGetRequest": { + "type": "object", + "description": "No request fields — the account-scope pack is always targeted.", + "properties": {} + }, + "KnowledgePackListRequest": { + "type": "object", + "description": "Filter and pagination for the pack list.", + "properties": { + "p": { + "type": "integer", + "description": "Page number, 1-based; returns all results when both `p` and `limit` are unset." + }, + "limit": { + "type": "integer", + "description": "Page size." + }, + "scope": { + "type": "string", + "description": "Restrict to one scope; `all` (default) overrides `include_account`.", + "enum": [ + "all", + "account", + "team" + ] + }, + "query": { + "type": "string", + "description": "Case-insensitive substring filter over pack ID, scope, and team name.", + "maxLength": 128 + }, + "team_ids": { + "type": "array", + "description": "Restrict to these team IDs; for non-admins the list is intersected with their own teams.", + "items": { + "type": "integer", + "format": "int64" + } + }, + "include_account": { + "type": [ + "boolean", + "null" + ], + "description": "Include the account-scope pack; defaults to true." + } + } + }, + "KnowledgePackEnsureRequest": { + "type": "object", + "description": "Scope at which to ensure a knowledge pack exists.", + "properties": { + "scope": { + "type": "string", + "description": "Scope of the pack to ensure.", + "enum": [ + "account", + "team" + ] + }, + "scope_id": { + "type": "integer", + "description": "Team ID; required for `team` scope, ignored for `account` scope.", + "format": "int64" + } + }, + "required": [ + "scope" + ] + }, + "KnowledgePackUpdateRequest": { + "type": "object", + "description": "Move a knowledge pack to a different scope.", + "properties": { + "pack_id": { + "type": "string", + "description": "Knowledge pack ID to update." + }, + "scope": { + "type": [ + "string", + "null" + ], + "description": "Destination scope; omit for a no-op that returns the current pack.", + "enum": [ + "account", + "team", + null + ] + }, + "scope_id": { + "type": [ + "integer", + "null" + ], + "description": "Destination team ID; required when `scope` is `team`, set automatically for `account`.", + "format": "int64" + } + }, + "required": [ + "pack_id" + ] + }, + "KnowledgePackDeleteRequest": { + "type": "object", + "description": "Pack to delete.", + "properties": { + "pack_id": { + "type": "string", + "description": "Knowledge pack ID to delete." + } + }, + "required": [ + "pack_id" + ] + }, + "KnowledgePackDeleteResponse": { + "type": "object", + "description": "Deletion result.", + "properties": { + "ok": { + "type": "boolean", + "description": "True when the pack was deleted." + } + }, + "required": [ + "ok" + ] + }, + "KnowledgeFileListRequest": { + "type": "object", + "description": "Which pack's files to list.", + "properties": { + "pack_id": { + "type": "string", + "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + }, + "p": { + "type": "integer", + "description": "Page number, 1-based." + }, + "limit": { + "type": "integer", + "description": "Page size." + } + } + }, + "KnowledgeFileGetRequest": { + "type": "object", + "description": "Which file to fetch.", + "properties": { + "pack_id": { + "type": "string", + "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + }, + "rel_path": { + "type": "string", + "description": "Path of the file relative to the pack root." + } + }, + "required": [ + "rel_path" + ] + }, + "KnowledgeFilePutRequest": { + "type": "object", + "description": "File to create or overwrite. The body is base64 text in `content_b64`, not a multipart upload.", + "properties": { + "pack_id": { + "type": "string", + "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + }, + "rel_path": { + "type": "string", + "description": "Destination path relative to the pack root; existing files are overwritten." + }, + "content_b64": { + "type": "string", + "description": "Base64-encoded file content; must decode to valid UTF-8 text." + }, + "content_type": { + "type": "string", + "description": "MIME type; inferred from the file extension when omitted." + } + }, + "required": [ + "rel_path" + ] + }, + "KnowledgeGetResponse": { + "type": "object", + "description": "Account-scope pack metadata plus its file list.", + "properties": { + "pack": { + "$ref": "#/components/schemas/KnowledgePackItem" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KnowledgeFileItem" + } + } + }, + "required": [ + "pack", + "files" + ] + }, + "KnowledgePackListResponse": { + "type": "object", + "description": "Visible packs and the total after filtering.", + "properties": { + "packs": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KnowledgePackItem" + } + }, + "total": { + "type": "integer", + "description": "Total number of packs after filtering, before pagination.", + "format": "int64" + } + }, + "required": [ + "packs", + "total" + ] + }, + "KnowledgeFileListResponse": { + "type": "object", + "description": "Files in the pack.", + "properties": { + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KnowledgeFileItem" + } + }, + "total": { + "type": "integer", + "description": "Total number of files in the pack.", + "format": "int64" + } + }, + "required": [ + "files", + "total" + ] + }, + "KnowledgeFileGetResponse": { + "type": "object", + "description": "File metadata plus its base64-encoded content.", + "properties": { + "file": { + "$ref": "#/components/schemas/KnowledgeFileItem" + }, + "content_b64": { + "type": "string", + "description": "Base64-encoded file content; decodes to UTF-8 text." + } + }, + "required": [ + "file", + "content_b64" + ] + }, + "KnowledgeFilePutResponse": { + "type": "object", + "description": "The written file plus any non-blocking warnings.", + "properties": { + "file": { + "$ref": "#/components/schemas/KnowledgeFileItem" + }, + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KnowledgeWarning" + } + } + }, + "required": [ + "file" + ] + }, + "KnowledgeFileDeleteRequest": { + "type": "object", + "description": "File to remove from a knowledge pack.", + "properties": { + "pack_id": { + "type": "string", + "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + }, + "rel_path": { + "type": "string", + "description": "Path of the file relative to the pack root." + }, + "force": { + "type": "boolean", + "description": "Delete even when other pack files reference this file; the referrers are then returned as warnings instead of blocking the delete." + } + }, + "required": [ + "rel_path" + ] + }, + "KnowledgeFileDeleteResponse": { + "type": "object", + "description": "Deletion result; empty unless warnings were raised.", + "properties": { + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KnowledgeWarning" + } + } + } } } } diff --git a/openapi/openapi.zh.json b/openapi/openapi.zh.json index d6ce50b..e608fe2 100644 --- a/openapi/openapi.zh.json +++ b/openapi/openapi.zh.json @@ -167,6 +167,9 @@ { "name": "RUM/资源", "description": "查询账户的 RUM 资源记录及当前用量。" + }, + { + "name": "AI SRE/知识" } ], "paths": { @@ -29903,6 +29906,843 @@ } } } + }, + "/safari/knowledge/get": { + "post": { + "operationId": "knowledge-pack-read-get", + "summary": "查看账户知识包", + "description": "返回账户范围知识包的元数据及其文件列表。", + "tags": [ + "AI SRE/知识" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 固定返回调用者的账户范围知识包——没有 `pack_id` 参数；如需团队知识包请使用 `POST /safari/knowledge/pack/list`。\n- 账户知识包在首次访问时惰性创建，因此有效账户调用不会返回 not-found。\n", + "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-get", + "metadata": { + "sidebarTitle": "查看账户知识包" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgeGetResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "pack": { + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "account_id": 2451002751131, + "scope": "account", + "scope_id": 2451002751131, + "file_count": 17, + "total_bytes": 41010, + "version": 134, + "created_by": 2476444212131, + "created_at_ms": 1778768680053, + "updated_at_ms": 1786456567177, + "can_edit": true + }, + "files": [ + { + "file_id": "kfl_QvT4g3c8zAHxTthuT6hGne", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "aliyun.md", + "content_type": "text/markdown", + "size_bytes": 1436, + "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f", + "updated_by": 3790925372131, + "updated_at_ms": 1783311304757 + }, + { + "file_id": "kfl_BMsQZCZSqhW4TFskYNb4H5", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "DUTY.md", + "content_type": "text/markdown", + "size_bytes": 1301, + "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b", + "updated_by": 2476444212131, + "updated_at_ms": 1784800003394 + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeGetRequest" + }, + "example": {} + } + } + } + } + }, + "/safari/knowledge/pack/list": { + "post": { + "operationId": "knowledge-pack-read-list", + "summary": "查询知识包列表", + "description": "查询调用者可见的账户与团队范围知识包列表。", + "tags": [ + "AI SRE/知识" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 可见性与控制台一致：管理员可见账户包及全部团队包；非管理员可见账户包及所属团队包，传入的 `team_ids` 会被静默过滤为其所属团队。\n- `scope` 用于选择 `all`（默认）、仅 `account` 或仅 `team`，会覆盖 `include_account`。\n- `query` 对知识包 ID、范围和团队名称做大小写不敏感的子串过滤；`p`/`limit` 对过滤结果分页。\n", + "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-list", + "metadata": { + "sidebarTitle": "查询知识包列表" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgePackListResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "packs": [ + { + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "account_id": 2451002751131, + "scope": "account", + "scope_id": 2451002751131, + "file_count": 17, + "total_bytes": 41010, + "version": 134, + "created_by": 2476444212131, + "created_at_ms": 1778768680053, + "updated_at_ms": 1786456567177, + "can_edit": true + }, + { + "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy", + "account_id": 2451002751131, + "scope": "team", + "scope_id": 2477033058131, + "team_name": "研发团队", + "file_count": 4, + "total_bytes": 11159, + "version": 15, + "created_by": 2476444212131, + "created_at_ms": 1782201586089, + "updated_at_ms": 1785462092702, + "can_edit": true + } + ], + "total": 3 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgePackListRequest" + }, + "example": { + "p": 1, + "limit": 20, + "scope": "all", + "include_account": true + } + } + } + } + } + }, + "/safari/knowledge/pack/ensure": { + "post": { + "operationId": "knowledge-pack-write-ensure", + "summary": "确保知识包存在", + "description": "在指定范围幂等创建知识包，已存在时直接返回现有知识包。", + "tags": [ + "AI SRE/知识" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 幂等：若（`scope`, `scope_id`）已存在知识包，则原样返回。\n- 账户范围忽略 `scope_id`（使用账户 ID），首次创建时会自动写入默认 `DUTY.md`。\n- 创建账户范围知识包需要账户 Owner/Admin 权限；在团队下创建需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", + "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure", + "metadata": { + "sidebarTitle": "确保知识包存在" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgePackItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "account_id": 2451002751131, + "scope": "account", + "scope_id": 2451002751131, + "file_count": 17, + "total_bytes": 41010, + "version": 138, + "created_by": 2476444212131, + "created_at_ms": 1778768680053, + "updated_at_ms": 1786458765182, + "can_edit": true + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgePackEnsureRequest" + }, + "example": { + "scope": "team", + "scope_id": 2477033058131 + } + } + } + } + } + }, + "/safari/knowledge/pack/update": { + "post": { + "operationId": "knowledge-pack-write-update", + "summary": "更新知识包", + "description": "将知识包移动到其他账户或团队范围。", + "tags": [ + "AI SRE/知识" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- `scope` 是唯一可修改的字段；不传则为空操作，返回当前知识包。\n- 团队范围必须传 `scope_id`；账户范围自动使用账户 ID。\n- 目标范围已存在知识包时返回 `ReferenceExist`——知识包不会被合并。\n- 每次调用都会记录到账户审计日志。\n", + "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-update", + "metadata": { + "sidebarTitle": "更新知识包" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgePackItem" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy", + "account_id": 2451002751131, + "scope": "team", + "scope_id": 2477033058131, + "team_name": "研发团队", + "file_count": 4, + "total_bytes": 11159, + "version": 15, + "created_by": 2476444212131, + "created_at_ms": 1782201586089, + "updated_at_ms": 1785462092702, + "can_edit": true + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgePackUpdateRequest" + }, + "example": { + "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy", + "scope": "team", + "scope_id": 2477033058131 + } + } + } + } + } + }, + "/safari/knowledge/pack/delete": { + "post": { + "operationId": "knowledge-pack-write-delete", + "summary": "删除知识包", + "description": "删除知识包及其全部文件。", + "tags": [ + "AI SRE/知识" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除知识包会同时删除其中所有文件，且不可恢复。\n- 允许删除账户范围知识包；下次访问时会重新创建为空包。\n- 每次调用都会记录到账户审计日志。\n", + "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-delete", + "metadata": { + "sidebarTitle": "删除知识包" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgePackDeleteResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "ok": true + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgePackDeleteRequest" + }, + "example": { + "pack_id": "kpk_YqHXPTEUHQFGepUfRS7vsh" + } + } + } + } + } + }, + "/safari/knowledge/file/list": { + "post": { + "operationId": "knowledge-file-read-list", + "summary": "查询知识文件列表", + "description": "查询知识包内的文件列表，包含大小、校验和等元数据。", + "tags": [ + "AI SRE/知识" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不传 `pack_id` 时默认查询调用者的账户范围知识包（不存在时惰性创建）。\n- 读取团队范围知识包需要是该团队成员。\n- `p`/`limit` 参数会被接受，但当前实现始终返回完整文件列表。\n", + "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-list", + "metadata": { + "sidebarTitle": "查询知识文件列表" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgeFileListResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "files": [ + { + "file_id": "kfl_QvT4g3c8zAHxTthuT6hGne", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "aliyun.md", + "content_type": "text/markdown", + "size_bytes": 1436, + "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f", + "updated_by": 3790925372131, + "updated_at_ms": 1783311304757 + }, + { + "file_id": "kfl_BMsQZCZSqhW4TFskYNb4H5", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "DUTY.md", + "content_type": "text/markdown", + "size_bytes": 1301, + "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b", + "updated_by": 2476444212131, + "updated_at_ms": 1784800003394 + } + ], + "total": 17 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeFileListRequest" + }, + "example": { + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc" + } + } + } + } + } + }, + "/safari/knowledge/file/get": { + "post": { + "operationId": "knowledge-file-read-get", + "summary": "获取知识文件", + "description": "返回知识文件的元数据及 Base64 编码的文件内容。", + "tags": [ + "AI SRE/知识" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 文件内容通过 `content_b64`（Base64）返回；知识包文件保证为 UTF-8 文本。\n- 不传 `pack_id` 时默认账户范围知识包；读取团队范围知识包需要是该团队成员。\n- 文件不存在时返回 `ResourceNotFound`（HTTP 400）。\n", + "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-get", + "metadata": { + "sidebarTitle": "获取知识文件" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgeFileGetResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "file": { + "file_id": "kfl_gctXKRG45aFQGgxSFr59WY", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "tmp/openapi-example.md", + "content_type": "text/markdown", + "size_bytes": 50, + "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d", + "updated_by": 2476444212131, + "updated_at_ms": 1786458764961 + }, + "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeFileGetRequest" + }, + "example": { + "rel_path": "tmp/openapi-example.md" + } + } + } + } + } + }, + "/safari/knowledge/file/put": { + "post": { + "operationId": "knowledge-file-write-put", + "summary": "上传知识文件", + "description": "以 Base64 编码的内容在知识包中创建或覆盖文件。", + "tags": [ + "AI SRE/知识" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 文件内容以 JSON 字段 `content_b64` 中的 Base64 文本上传——不是 multipart 上传。\n- 写入已存在的 `rel_path` 会覆盖原文件；`content_type` 留空时按扩展名推断（`.md` → `text/markdown`）。\n- 内容解码后必须是合法的 UTF-8 文本，二进制内容会被拒绝并返回 `InvalidParameter`。\n- 编辑账户范围知识包需要账户 Owner/Admin 权限；编辑团队知识包需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", + "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-put", + "metadata": { + "sidebarTitle": "上传知识文件" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgeFilePutResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "file": { + "file_id": "kfl_gctXKRG45aFQGgxSFr59WY", + "pack_id": "kpk_kE49k3FhecfJBwutbshEEc", + "rel_path": "tmp/openapi-example.md", + "content_type": "text/markdown", + "size_bytes": 50, + "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d", + "updated_by": 2476444212131, + "updated_at_ms": 1786458764961 + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeFilePutRequest" + }, + "example": { + "rel_path": "tmp/openapi-example.md", + "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=", + "content_type": "text/markdown" + } + } + } + } + } + }, + "/safari/knowledge/file/delete": { + "post": { + "operationId": "knowledge-file-write-delete", + "summary": "删除知识文件", + "description": "按相对路径删除知识包中的文件。", + "tags": [ + "AI SRE/知识" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除是幂等的——删除不存在的文件也会成功。\n- 当其他包内文件仍引用目标文件时，删除失败并返回 `ReferenceExist`（附带引用方列表）；设置 `force` 可强制删除（引用方以警告形式返回）。\n- 不传 `pack_id` 时默认账户范围知识包；编辑账户包需要账户 Owner/Admin 权限，编辑团队包需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n", + "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-delete", + "metadata": { + "sidebarTitle": "删除知识文件" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/KnowledgeFileDeleteResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": {} + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeFileDeleteRequest" + }, + "example": { + "rel_path": "tmp/openapi-delete-example.md" + } + } + } + } + } } }, "components": { @@ -56957,6 +57797,481 @@ "description": "私有化部署 License 到期时间，Unix 秒级时间戳。仅私有化部署会返回该字段，SaaS 账户不会出现该字段。" } } + }, + "KnowledgePackItem": { + "type": "object", + "description": "知识包——一棵带版本号的文件树，AI SRE 会话启动时会注入到每个沙箱中。每个（账户, scope, scope_id）仅有一个知识包。", + "properties": { + "pack_id": { + "type": "string", + "description": "知识包 ID（`kpk_` 前缀）。" + }, + "account_id": { + "type": "integer", + "description": "知识包所属账户 ID。", + "format": "int64" + }, + "scope": { + "type": "string", + "description": "知识包范围；`channel` 为历史遗留范围，新建知识包为 `account` 或 `team`。", + "enum": [ + "account", + "team", + "channel" + ] + }, + "scope_id": { + "type": "integer", + "description": "范围归属 ID：账户范围为账户 ID，团队范围为团队 ID。", + "format": "int64" + }, + "team_name": { + "type": "string", + "description": "所属团队的显示名称（仅团队范围）；账户范围为空。" + }, + "file_count": { + "type": "integer", + "description": "包内文件数量。" + }, + "total_bytes": { + "type": "integer", + "description": "包内所有文件的总字节数。", + "format": "int64" + }, + "version": { + "type": "integer", + "description": "知识包版本号，文件每次变更时递增。" + }, + "created_by": { + "type": "integer", + "description": "创建者成员 ID。", + "format": "int64" + }, + "created_at_ms": { + "type": "integer", + "description": "创建时间的 Unix 毫秒时间戳。", + "format": "int64" + }, + "updated_at_ms": { + "type": "integer", + "description": "最近修改时间的 Unix 毫秒时间戳。", + "format": "int64" + }, + "can_edit": { + "type": "boolean", + "description": "调用者是否有权限编辑该知识包。" + } + }, + "required": [ + "pack_id", + "account_id", + "scope", + "scope_id", + "file_count", + "total_bytes", + "version", + "created_by", + "created_at_ms", + "updated_at_ms", + "can_edit" + ] + }, + "KnowledgeFileItem": { + "type": "object", + "description": "知识包内单个文件的元数据；文件内容需通过 file/get 单独获取。", + "properties": { + "file_id": { + "type": "string", + "description": "文件 ID（`kfl_` 前缀）。" + }, + "pack_id": { + "type": "string", + "description": "文件所属的知识包 ID。" + }, + "rel_path": { + "type": "string", + "description": "相对于知识包根目录的路径，如 `runbooks/restart.md`。" + }, + "content_type": { + "type": "string", + "description": "MIME 类型；上传时未指定则按扩展名推断。" + }, + "size_bytes": { + "type": "integer", + "description": "文件大小（字节）。", + "format": "int64" + }, + "checksum": { + "type": "string", + "description": "文件内容的 SHA-256 十六进制摘要。" + }, + "updated_by": { + "type": "integer", + "description": "最近修改者成员 ID。", + "format": "int64" + }, + "updated_at_ms": { + "type": "integer", + "description": "最近修改时间的 Unix 毫秒时间戳。", + "format": "int64" + } + }, + "required": [ + "file_id", + "pack_id", + "rel_path", + "content_type", + "size_bytes", + "checksum", + "updated_by", + "updated_at_ms" + ] + }, + "KnowledgeWarning": { + "type": "object", + "description": "文件上传/删除返回的非阻塞提示，例如指向已删除文件的引用。", + "properties": { + "code": { + "type": "string", + "description": "提示码。", + "enum": [ + "unresolved_reference", + "still_referenced_by" + ] + }, + "ref": { + "type": "string", + "description": "与提示相关的单个引用。" + }, + "refs": { + "type": "array", + "description": "与提示相关的多个引用。", + "items": { + "type": "string" + } + } + }, + "required": [ + "code" + ] + }, + "KnowledgeGetRequest": { + "type": "object", + "description": "无请求字段——固定查询账户范围知识包。", + "properties": {} + }, + "KnowledgePackListRequest": { + "type": "object", + "description": "知识包列表的过滤与分页参数。", + "properties": { + "p": { + "type": "integer", + "description": "页码，从 1 开始；`p` 与 `limit` 均未设置时返回全部结果。" + }, + "limit": { + "type": "integer", + "description": "每页条数。" + }, + "scope": { + "type": "string", + "description": "限定范围；`all`（默认）会覆盖 `include_account`。", + "enum": [ + "all", + "account", + "team" + ] + }, + "query": { + "type": "string", + "description": "对知识包 ID、范围和团队名称做大小写不敏感的子串过滤。", + "maxLength": 128 + }, + "team_ids": { + "type": "array", + "description": "限定团队 ID；非管理员会与其所属团队取交集。", + "items": { + "type": "integer", + "format": "int64" + } + }, + "include_account": { + "type": [ + "boolean", + "null" + ], + "description": "是否包含账户范围的知识包；默认为 true。" + } + } + }, + "KnowledgePackEnsureRequest": { + "type": "object", + "description": "要确保存在知识包的范围。", + "properties": { + "scope": { + "type": "string", + "description": "知识包范围。", + "enum": [ + "account", + "team" + ] + }, + "scope_id": { + "type": "integer", + "description": "团队 ID；团队范围必填，账户范围忽略。", + "format": "int64" + } + }, + "required": [ + "scope" + ] + }, + "KnowledgePackUpdateRequest": { + "type": "object", + "description": "将知识包移动到其他范围。", + "properties": { + "pack_id": { + "type": "string", + "description": "要更新的知识包 ID。" + }, + "scope": { + "type": [ + "string", + "null" + ], + "description": "目标范围；不传则为空操作，返回当前知识包。", + "enum": [ + "account", + "team", + null + ] + }, + "scope_id": { + "type": [ + "integer", + "null" + ], + "description": "目标团队 ID；`scope` 为 `team` 时必填，为 `account` 时自动设置。", + "format": "int64" + } + }, + "required": [ + "pack_id" + ] + }, + "KnowledgePackDeleteRequest": { + "type": "object", + "description": "要删除的知识包。", + "properties": { + "pack_id": { + "type": "string", + "description": "要删除的知识包 ID。" + } + }, + "required": [ + "pack_id" + ] + }, + "KnowledgePackDeleteResponse": { + "type": "object", + "description": "删除结果。", + "properties": { + "ok": { + "type": "boolean", + "description": "知识包删除成功时为 true。" + } + }, + "required": [ + "ok" + ] + }, + "KnowledgeFileListRequest": { + "type": "object", + "description": "要列出文件的知识包。", + "properties": { + "pack_id": { + "type": "string", + "description": "知识包 ID；默认为调用者的账户范围知识包。" + }, + "p": { + "type": "integer", + "description": "页码，从 1 开始。" + }, + "limit": { + "type": "integer", + "description": "每页条数。" + } + } + }, + "KnowledgeFileGetRequest": { + "type": "object", + "description": "要获取的文件。", + "properties": { + "pack_id": { + "type": "string", + "description": "知识包 ID；默认为调用者的账户范围知识包。" + }, + "rel_path": { + "type": "string", + "description": "文件相对于知识包根目录的路径。" + } + }, + "required": [ + "rel_path" + ] + }, + "KnowledgeFilePutRequest": { + "type": "object", + "description": "要创建或覆盖的文件。文件体通过 `content_b64` 以 Base64 文本上传，不是 multipart 上传。", + "properties": { + "pack_id": { + "type": "string", + "description": "知识包 ID；默认为调用者的账户范围知识包。" + }, + "rel_path": { + "type": "string", + "description": "相对于知识包根目录的目标路径；已存在的文件会被覆盖。" + }, + "content_b64": { + "type": "string", + "description": "Base64 编码的文件内容；解码后必须是合法的 UTF-8 文本。" + }, + "content_type": { + "type": "string", + "description": "MIME 类型；留空时按扩展名推断。" + } + }, + "required": [ + "rel_path" + ] + }, + "KnowledgeGetResponse": { + "type": "object", + "description": "账户范围知识包元数据及其文件列表。", + "properties": { + "pack": { + "$ref": "#/components/schemas/KnowledgePackItem" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KnowledgeFileItem" + } + } + }, + "required": [ + "pack", + "files" + ] + }, + "KnowledgePackListResponse": { + "type": "object", + "description": "可见的知识包及过滤后的总数。", + "properties": { + "packs": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KnowledgePackItem" + } + }, + "total": { + "type": "integer", + "description": "过滤后、分页前的知识包总数。", + "format": "int64" + } + }, + "required": [ + "packs", + "total" + ] + }, + "KnowledgeFileListResponse": { + "type": "object", + "description": "知识包内的文件。", + "properties": { + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KnowledgeFileItem" + } + }, + "total": { + "type": "integer", + "description": "知识包内文件总数。", + "format": "int64" + } + }, + "required": [ + "files", + "total" + ] + }, + "KnowledgeFileGetResponse": { + "type": "object", + "description": "文件元数据及其 Base64 编码的内容。", + "properties": { + "file": { + "$ref": "#/components/schemas/KnowledgeFileItem" + }, + "content_b64": { + "type": "string", + "description": "Base64 编码的文件内容；解码后为 UTF-8 文本。" + } + }, + "required": [ + "file", + "content_b64" + ] + }, + "KnowledgeFilePutResponse": { + "type": "object", + "description": "写入的文件及非阻塞提示。", + "properties": { + "file": { + "$ref": "#/components/schemas/KnowledgeFileItem" + }, + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KnowledgeWarning" + } + } + }, + "required": [ + "file" + ] + }, + "KnowledgeFileDeleteRequest": { + "type": "object", + "description": "要从知识包中删除的文件。", + "properties": { + "pack_id": { + "type": "string", + "description": "知识包 ID；默认为调用者的账户范围知识包。" + }, + "rel_path": { + "type": "string", + "description": "文件相对于知识包根目录的路径。" + }, + "force": { + "type": "boolean", + "description": "即使其他包内文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。" + } + }, + "required": [ + "rel_path" + ] + }, + "KnowledgeFileDeleteResponse": { + "type": "object", + "description": "删除结果；无警告时为空对象。", + "properties": { + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KnowledgeWarning" + } + } + } } } } diff --git a/roundtrip_gen_test.go b/roundtrip_gen_test.go index 6e205c5..8dfb897 100644 --- a/roundtrip_gen_test.go +++ b/roundtrip_gen_test.go @@ -186,6 +186,15 @@ var exampleDataDecoders = map[string]func(json.RawMessage) error{ "POST /safari/automation/rule/update": func(d json.RawMessage) error { var v AutomationRuleItem; return json.Unmarshal(d, &v) }, "POST /safari/automation/run/list": func(d json.RawMessage) error { var v AutomationRunListResponse; return json.Unmarshal(d, &v) }, "POST /safari/automation/template/list": func(d json.RawMessage) error { var v AutomationTemplateListResponse; return json.Unmarshal(d, &v) }, + "POST /safari/knowledge/file/delete": func(d json.RawMessage) error { var v KnowledgeFileDeleteResponse; return json.Unmarshal(d, &v) }, + "POST /safari/knowledge/file/get": func(d json.RawMessage) error { var v KnowledgeFileGetResponse; return json.Unmarshal(d, &v) }, + "POST /safari/knowledge/file/list": func(d json.RawMessage) error { var v KnowledgeFileListResponse; return json.Unmarshal(d, &v) }, + "POST /safari/knowledge/file/put": func(d json.RawMessage) error { var v KnowledgeFilePutResponse; return json.Unmarshal(d, &v) }, + "POST /safari/knowledge/get": func(d json.RawMessage) error { var v KnowledgeGetResponse; return json.Unmarshal(d, &v) }, + "POST /safari/knowledge/pack/delete": func(d json.RawMessage) error { var v KnowledgePackDeleteResponse; return json.Unmarshal(d, &v) }, + "POST /safari/knowledge/pack/ensure": func(d json.RawMessage) error { var v KnowledgePackItem; return json.Unmarshal(d, &v) }, + "POST /safari/knowledge/pack/list": func(d json.RawMessage) error { var v KnowledgePackListResponse; return json.Unmarshal(d, &v) }, + "POST /safari/knowledge/pack/update": func(d json.RawMessage) error { var v KnowledgePackItem; return json.Unmarshal(d, &v) }, "POST /safari/mcp/server/create": func(d json.RawMessage) error { var v McpServerItem; return json.Unmarshal(d, &v) }, "POST /safari/mcp/server/delete": func(d json.RawMessage) error { var v any; return json.Unmarshal(d, &v) }, "POST /safari/mcp/server/disable": func(d json.RawMessage) error { var v any; return json.Unmarshal(d, &v) }, diff --git a/services_gen.go b/services_gen.go index c8c468f..55b85f4 100644 --- a/services_gen.go +++ b/services_gen.go @@ -10,6 +10,7 @@ type service struct{ client *Client } type genServices struct { A2aAgents *A2aAgentsService Automations *AutomationsService + Knowledge *KnowledgeService McpServers *McpServersService Sessions *SessionsService Skills *SkillsService @@ -53,6 +54,7 @@ func (c *Client) initServices() { c.common.client = c c.A2aAgents = (*A2aAgentsService)(&c.common) c.Automations = (*AutomationsService)(&c.common) + c.Knowledge = (*KnowledgeService)(&c.common) c.McpServers = (*McpServersService)(&c.common) c.Sessions = (*SessionsService)(&c.common) c.Skills = (*SkillsService)(&c.common)