diff --git a/.claude/skills/translate-zh-to-en/glossary.md b/.claude/skills/translate-zh-to-en/glossary.md index f7cae3ec6..7a5202114 100644 --- a/.claude/skills/translate-zh-to-en/glossary.md +++ b/.claude/skills/translate-zh-to-en/glossary.md @@ -199,7 +199,7 @@ Translatable companions (do NOT belong in DNT — translate to Chinese): | English | Chinese | |---------|---------| | Artifact / Artifacts | 产物 | -| Knowledge | 知识库 — the DUTY.md-rooted file tree an account or team maintains for AI SRE. Formerly "Knowledge Pack"; do not use that name in copy. Running text uses lowercase "knowledge" (e.g., "team knowledge"); API identifiers such as `pack_id` and `knowledge-pack-*` CLI commands stay unchanged | +| Knowledge | 知识 — the DUTY.md-rooted file tree an account or team maintains for AI SRE. Formerly "Knowledge Pack"; do not use that name in copy. Running text uses lowercase "knowledge" (e.g., "team knowledge"); API identifiers such as `pack_id` and `knowledge-pack-*` CLI commands stay unchanged | | Memory | 记忆 | | Context | 上下文 — the Customize group holding Knowledge and Memory | | Customize | 自定义 — the AI SRE sidebar entry that opens Context, Plugins, and Environments | diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 5c2bdd216..7513b534f 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -5017,10 +5017,10 @@ "type": "object" }, "ContextResolvedItem": { - "description": "Snapshot of the three-tier knowledge-pack resolution for this session.", + "description": "Snapshot of the three-tier knowledge resolution for this session.", "properties": { "account_pack_id": { - "description": "Resolved account-scoped pack id.", + "description": "Resolved account-scope knowledge ID.", "type": "string" }, "incident_id": { @@ -5028,19 +5028,19 @@ "type": "string" }, "resolved_at_ms": { - "description": "Unix timestamp in milliseconds when the packs were resolved.", + "description": "Unix timestamp in milliseconds when the knowledge was resolved.", "format": "int64", "type": "integer" }, "team_pack_id": { - "description": "Resolved team-scoped pack id.", + "description": "Resolved team-scope knowledge ID.", "type": "string" }, "versions": { "additionalProperties": { "type": "integer" }, - "description": "Per-pack resolved version map.", + "description": "Resolved version map, one entry per knowledge.", "type": "object" } }, @@ -12829,18 +12829,18 @@ "type": "object" }, "KnowledgeFileDeleteRequest": { - "description": "File to remove from a knowledge pack.", + "description": "Knowledge file to remove.", "properties": { "force": { - "description": "Delete even when other pack files reference this file; the referrers are then returned as warnings instead of blocking the delete.", + "description": "Delete even when other knowledge files reference this file; the referrers are then returned as warnings instead of blocking the delete.", "type": "boolean" }, "pack_id": { - "description": "Knowledge pack ID; defaults to the caller's account-scope pack.", + "description": "Knowledge ID; defaults to the caller's account-scope knowledge.", "type": "string" }, "rel_path": { - "description": "Path of the file relative to the pack root.", + "description": "Path of the file relative to the knowledge root.", "type": "string" } }, @@ -12853,7 +12853,7 @@ "description": "Deletion result; empty unless warnings were raised.", "properties": { "warnings": { - "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the pack (`refs` lists the referrers). Absent when there are no warnings (omitempty).", + "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the knowledge (`refs` lists the referrers). Absent when there are no warnings (omitempty).", "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, @@ -12866,11 +12866,11 @@ "description": "Which file to fetch.", "properties": { "pack_id": { - "description": "Knowledge pack ID; defaults to the caller's account-scope pack.", + "description": "Knowledge ID; defaults to the caller's account-scope knowledge.", "type": "string" }, "rel_path": { - "description": "Path of the file relative to the pack root.", + "description": "Path of the file relative to the knowledge root.", "type": "string" } }, @@ -12897,7 +12897,7 @@ "type": "object" }, "KnowledgeFileItem": { - "description": "Metadata of one file inside a knowledge pack. Content is fetched separately via file/get.", + "description": "Metadata of one knowledge file. Content is fetched separately via file/get.", "properties": { "checksum": { "description": "SHA-256 hex digest of the file content.", @@ -12912,11 +12912,11 @@ "type": "string" }, "pack_id": { - "description": "ID of the knowledge pack that contains the file.", + "description": "ID of the knowledge that contains the file.", "type": "string" }, "rel_path": { - "description": "Path relative to the pack root, e.g. `runbooks/restart.md`.", + "description": "Path relative to the knowledge root, e.g. `runbooks/restart.md`.", "type": "string" }, "size_bytes": { @@ -12948,7 +12948,7 @@ "type": "object" }, "KnowledgeFileListRequest": { - "description": "Which pack's files to list.", + "description": "Which knowledge's files to list.", "properties": { "limit": { "description": "Page size. Accepted but currently ignored — the response always contains the full file list.", @@ -12959,24 +12959,24 @@ "type": "integer" }, "pack_id": { - "description": "Knowledge pack ID; defaults to the caller's account-scope pack.", + "description": "Knowledge ID; defaults to the caller's account-scope knowledge.", "type": "string" } }, "type": "object" }, "KnowledgeFileListResponse": { - "description": "Files in the pack.", + "description": "Files in the knowledge.", "properties": { "files": { - "description": "Array of files in the specified knowledge pack; empty array when the pack has no files.", + "description": "Array of files in the specified knowledge; empty array when it has no files.", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, "type": "array" }, "total": { - "description": "Total number of files in the pack.", + "description": "Total number of files in the knowledge.", "format": "int64", "type": "integer" } @@ -12999,11 +12999,11 @@ "type": "string" }, "pack_id": { - "description": "Knowledge pack ID; defaults to the caller's account-scope pack.", + "description": "Knowledge ID; defaults to the caller's account-scope knowledge.", "type": "string" }, "rel_path": { - "description": "Destination path relative to the pack root; existing files are overwritten.", + "description": "Destination path relative to the knowledge root; existing files are overwritten.", "type": "string" } }, @@ -13019,7 +13019,7 @@ "$ref": "#/components/schemas/KnowledgeFileItem" }, "warnings": { - "description": "Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the pack. Absent when there are no warnings (omitempty).", + "description": "Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the knowledge. Absent when there are no warnings (omitempty).", "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, @@ -13032,15 +13032,15 @@ "type": "object" }, "KnowledgeGetRequest": { - "description": "No request fields — the account-scope pack is always targeted.", + "description": "No request fields — the account-scope knowledge is always targeted.", "properties": {}, "type": "object" }, "KnowledgeGetResponse": { - "description": "Account-scope pack metadata plus its file list.", + "description": "Account-scope knowledge metadata plus its file list.", "properties": { "files": { - "description": "Array of files in this knowledge pack; empty array when the pack has no files.", + "description": "Array of files in this knowledge; empty array when it has no files.", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, @@ -13057,10 +13057,10 @@ "type": "object" }, "KnowledgePackDeleteRequest": { - "description": "Pack to delete.", + "description": "Knowledge to delete.", "properties": { "pack_id": { - "description": "Knowledge pack ID to delete.", + "description": "Knowledge ID to delete.", "type": "string" } }, @@ -13073,7 +13073,7 @@ "description": "Deletion result.", "properties": { "ok": { - "description": "True when the pack was deleted.", + "description": "True when the knowledge was deleted.", "type": "boolean" } }, @@ -13083,10 +13083,10 @@ "type": "object" }, "KnowledgePackEnsureRequest": { - "description": "Scope at which to ensure a knowledge pack exists.", + "description": "Scope at which to ensure knowledge exists.", "properties": { "scope": { - "description": "Scope of the pack to ensure. One of: `account` (account-level pack; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level pack; the `scope_id` team ID is required and the caller must belong to that team).", + "description": "Scope of the knowledge to ensure. One of: `account` (account-level knowledge; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level knowledge; the `scope_id` team ID is required and the caller must belong to that team).", "enum": [ "account", "team" @@ -13105,41 +13105,41 @@ "type": "object" }, "KnowledgePackItem": { - "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).", + "description": "Knowledge — a versioned file tree staged into every AI SRE sandbox at session start. One knowledge exists per (account, scope, scope_id).", "properties": { "account_id": { - "description": "Account that owns the pack.", + "description": "Account that owns the knowledge.", "format": "int64", "type": "integer" }, "can_edit": { - "description": "Whether the caller can edit this pack.", + "description": "Whether the caller can edit this knowledge.", "type": "boolean" }, "created_at_ms": { - "description": "Unix timestamp in milliseconds when the pack was created.", + "description": "Unix timestamp in milliseconds when the knowledge was created.", "format": "int64", "type": "integer" }, "created_by": { - "description": "Person ID of the member who created the pack.", + "description": "Person ID of the member who created the knowledge.", "format": "int64", "type": "integer" }, "duty_version": { - "description": "Pack version at which DUTY.md was last authored or re-affirmed. When `version` is greater, DUTY.md no longer reflects every file in the pack.", + "description": "Knowledge version at which DUTY.md was last authored or re-affirmed. When `version` is greater, DUTY.md no longer reflects every file in the knowledge.", "type": "integer" }, "file_count": { - "description": "Number of files in the pack.", + "description": "Number of files in the knowledge.", "type": "integer" }, "pack_id": { - "description": "Knowledge pack ID (`kpk_` prefix).", + "description": "Knowledge ID (`kpk_` prefix).", "type": "string" }, "scope": { - "description": "Pack scope. `channel` is a legacy scope; new packs are `account` or `team`.", + "description": "Knowledge scope. `channel` is a legacy scope; new knowledge is `account` or `team` scope.", "enum": [ "account", "team", @@ -13162,12 +13162,12 @@ "type": "integer" }, "updated_at_ms": { - "description": "Unix timestamp in milliseconds when the pack was last modified.", + "description": "Unix timestamp in milliseconds when the knowledge was last modified.", "format": "int64", "type": "integer" }, "version": { - "description": "Pack version, incremented on every file change.", + "description": "Knowledge version, incremented on every file change.", "type": "integer" } }, @@ -13188,10 +13188,10 @@ "type": "object" }, "KnowledgePackListRequest": { - "description": "Filter and pagination for the pack list.", + "description": "Filter and pagination for the knowledge list.", "properties": { "include_account": { - "description": "Include the account-scope pack; defaults to true.", + "description": "Include the account-scope knowledge; defaults to true.", "type": [ "boolean", "null" @@ -13206,12 +13206,12 @@ "type": "integer" }, "query": { - "description": "Case-insensitive substring filter over pack ID, scope, scope ID/account ID, and team name.", + "description": "Case-insensitive substring filter over knowledge ID, scope, scope ID/account ID, and team name.", "maxLength": 128, "type": "string" }, "scope": { - "description": "Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level packs only), `team` (team-level packs only, can be combined with `team_ids`).", + "description": "Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level knowledge only), `team` (team-level knowledge only, can be combined with `team_ids`).", "enum": [ "all", "account", @@ -13231,17 +13231,17 @@ "type": "object" }, "KnowledgePackListResponse": { - "description": "Visible packs and the total after filtering.", + "description": "Visible knowledge and the total after filtering.", "properties": { "packs": { - "description": "Array of visible knowledge packs after filtering (current page), used with `total` for pagination.", + "description": "Array of visible knowledge after filtering (current page), used with `total` for pagination.", "items": { "$ref": "#/components/schemas/KnowledgePackItem" }, "type": "array" }, "total": { - "description": "Total number of packs after filtering, before pagination.", + "description": "Total number of knowledge entries after filtering, before pagination.", "format": "int64", "type": "integer" } @@ -13253,14 +13253,14 @@ "type": "object" }, "KnowledgePackUpdateRequest": { - "description": "Move a knowledge pack to a different scope.", + "description": "Move knowledge to a different scope.", "properties": { "pack_id": { - "description": "Knowledge pack ID to update.", + "description": "Knowledge ID to update.", "type": "string" }, "scope": { - "description": "Destination scope; omit for a no-op that returns the current pack.", + "description": "Destination scope; omit for a no-op that returns the current knowledge.", "enum": [ "account", "team" @@ -13288,7 +13288,7 @@ "description": "Non-blocking annotation returned by file uploads and deletions, e.g. references that point at a removed file.", "properties": { "code": { - "description": "Warning code. One of: `unresolved_reference` (an @ref in the written file's content points to a file that does not exist in the pack; `ref` carries it), `still_referenced_by` (the deleted file is still @ref-referenced by other files in the pack; `refs` lists the referrers).", + "description": "Warning code. One of: `unresolved_reference` (an @ref in the written file's content points to a file that does not exist in the knowledge; `ref` carries it), `still_referenced_by` (the deleted file is still @ref-referenced by other files in the knowledge; `refs` lists the referrers).", "enum": [ "unresolved_reference", "still_referenced_by" @@ -23757,7 +23757,7 @@ "$ref": "#/components/schemas/SessionItem" }, "suggest_init": { - "description": "Account-wide onboarding flag: true when the account has zero knowledge packs in any scope; not specific to this session.", + "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not specific to this session.", "type": "boolean" }, "pending_messages": { @@ -24111,7 +24111,7 @@ "type": "array" }, "suggest_init": { - "description": "Account-wide onboarding flag: true when the account has zero knowledge packs in any scope; not dependent on this call's filters.", + "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not dependent on this call's filters.", "type": "boolean" }, "total": { @@ -52619,7 +52619,7 @@ }, "/safari/knowledge/file/delete": { "post": { - "description": "Delete a file from a knowledge pack by its relative path.", + "description": "Delete a knowledge file by its relative path.", "operationId": "knowledge-file-write-delete", "requestBody": { "content": { @@ -52687,7 +52687,7 @@ "AI SRE/Knowledge" ], "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", + "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 knowledge 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 knowledge; editing the account knowledge requires account owner/admin, editing team knowledge 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" @@ -52774,7 +52774,7 @@ "AI SRE/Knowledge" ], "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", + "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); knowledge files are guaranteed UTF-8 text.\n- Omitting `pack_id` targets the account-scope knowledge; reading team-scope knowledge 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" @@ -52784,7 +52784,7 @@ }, "/safari/knowledge/file/list": { "post": { - "description": "List the files in a knowledge pack with metadata such as size and checksum.", + "description": "List knowledge files with metadata such as size and checksum.", "operationId": "knowledge-file-read-list", "requestBody": { "content": { @@ -52873,7 +52873,7 @@ "AI SRE/Knowledge" ], "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", + "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 knowledge (created lazily if absent).\n- Reading team-scope knowledge 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" @@ -52883,7 +52883,7 @@ }, "/safari/knowledge/file/put": { "post": { - "description": "Create or overwrite a file in a knowledge pack with base64-encoded content.", + "description": "Create or overwrite a knowledge file with base64-encoded content.", "operationId": "knowledge-file-write-put", "requestBody": { "content": { @@ -52964,7 +52964,7 @@ "AI SRE/Knowledge" ], "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", + "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 knowledge requires account owner/admin; editing team knowledge 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" @@ -52974,7 +52974,7 @@ }, "/safari/knowledge/get": { "post": { - "description": "Return the account-scope knowledge pack metadata and its file list.", + "description": "Return the metadata and file list of the account-scope knowledge.", "operationId": "knowledge-pack-read-get", "requestBody": { "content": { @@ -53069,22 +53069,22 @@ "AppKeyAuth": [] } ], - "summary": "Get account knowledge pack", + "summary": "Get account knowledge", "tags": [ "AI SRE/Knowledge" ], "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", + "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 knowledge — there is no `pack_id` parameter; use `POST /safari/knowledge/pack/list` to discover team knowledge.\n- The account knowledge 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" + "sidebarTitle": "Get account knowledge" } } } }, "/safari/knowledge/pack/delete": { "post": { - "description": "Delete a knowledge pack and all of its files.", + "description": "Delete knowledge and all of its files.", "operationId": "knowledge-pack-write-delete", "requestBody": { "content": { @@ -53149,22 +53149,22 @@ "AppKeyAuth": [] } ], - "summary": "Delete knowledge pack", + "summary": "Delete knowledge", "tags": [ "AI SRE/Knowledge" ], "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", + "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 knowledge removes every file it contains; the operation cannot be undone.\n- Deleting the account-scope knowledge 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" + "sidebarTitle": "Delete knowledge" } } } }, "/safari/knowledge/pack/ensure": { "post": { - "description": "Idempotently create the knowledge pack at the given scope, or return the existing one.", + "description": "Idempotently create the knowledge at the given scope, or return the existing one.", "operationId": "knowledge-pack-write-ensure", "requestBody": { "content": { @@ -53241,22 +53241,22 @@ "AppKeyAuth": [] } ], - "summary": "Ensure knowledge pack", + "summary": "Ensure knowledge", "tags": [ "AI SRE/Knowledge" ], "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", + "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 knowledge 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 knowledge 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" + "sidebarTitle": "Ensure knowledge" } } } }, "/safari/knowledge/pack/list": { "post": { - "description": "List knowledge packs visible to the caller across account and team scopes.", + "description": "List the knowledge visible to the caller across account and team scopes.", "operationId": "knowledge-pack-read-list", "requestBody": { "content": { @@ -53352,22 +53352,22 @@ "AppKeyAuth": [] } ], - "summary": "List knowledge packs", + "summary": "List knowledge", "tags": [ "AI SRE/Knowledge" ], "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", + "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 knowledge plus every team's knowledge; non-admins see the account knowledge plus their own teams' knowledge, 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 knowledge 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" + "sidebarTitle": "List knowledge" } } } }, "/safari/knowledge/pack/update": { "post": { - "description": "Move a knowledge pack to a different account or team scope.", + "description": "Move knowledge to a different account or team scope.", "operationId": "knowledge-pack-write-update", "requestBody": { "content": { @@ -53446,15 +53446,15 @@ "AppKeyAuth": [] } ], - "summary": "Update knowledge pack", + "summary": "Update knowledge", "tags": [ "AI SRE/Knowledge" ], "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", + "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 knowledge.\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 knowledge — knowledge is 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" + "sidebarTitle": "Update knowledge" } } } @@ -54491,7 +54491,7 @@ "AI SRE/Sessions" ], "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- Pagination uses `p`/`limit` (max 100); `scope` defaults to `all`.\n- `all` returns your personal sessions plus team sessions you can access; account admins see all team sessions, but not other users' personal sessions.\n- `team_ids` narrows the visible set and never expands access.\n- `is_running` reflects the live run-set; `has_unread` is computed per calling user; the `current_turn_*` fields are always zero here — only `session/get` computes them while a session is running.\n- `suggest_init` is an account-wide onboarding flag (true only when the account has zero knowledge packs anywhere) — it doesn't depend on the list filters.\n", + "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- Pagination uses `p`/`limit` (max 100); `scope` defaults to `all`.\n- `all` returns your personal sessions plus team sessions you can access; account admins see all team sessions, but not other users' personal sessions.\n- `team_ids` narrows the visible set and never expands access.\n- `is_running` reflects the live run-set; `has_unread` is computed per calling user; the `current_turn_*` fields are always zero here — only `session/get` computes them while a session is running.\n- `suggest_init` is an account-wide onboarding flag (true only when the account has no knowledge in any scope) — it doesn't depend on the list filters.\n", "href": "/en/api-reference/ai-sre/sessions/session-read-list", "metadata": { "sidebarTitle": "List sessions" diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index afedef7f7..fff8dc46f 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -5017,10 +5017,10 @@ "type": "object" }, "ContextResolvedItem": { - "description": "该会话三层知识包解析结果的快照。", + "description": "该会话三层知识解析结果的快照。", "properties": { "account_pack_id": { - "description": "解析出的账户级知识包 ID。", + "description": "解析出的账户级知识 ID。", "type": "string" }, "incident_id": { @@ -5028,19 +5028,19 @@ "type": "string" }, "resolved_at_ms": { - "description": "知识包解析时间，Unix 毫秒时间戳。", + "description": "知识解析时间，Unix 毫秒时间戳。", "format": "int64", "type": "integer" }, "team_pack_id": { - "description": "解析出的团队级知识包 ID。", + "description": "解析出的团队级知识 ID。", "type": "string" }, "versions": { "additionalProperties": { "type": "integer" }, - "description": "各知识包解析版本映射。", + "description": "各份知识的解析版本映射。", "type": "object" } }, @@ -12829,18 +12829,18 @@ "type": "object" }, "KnowledgeFileDeleteRequest": { - "description": "要从知识包中删除的文件。", + "description": "要删除的知识文件。", "properties": { "force": { - "description": "即使其他包内文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。", + "description": "即使其他知识文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。", "type": "boolean" }, "pack_id": { - "description": "知识包 ID；默认为调用者的账户范围知识包。", + "description": "知识 ID；默认为调用者的账户范围知识。", "type": "string" }, "rel_path": { - "description": "文件相对于知识包根目录的路径。", + "description": "文件相对于知识根目录的路径。", "type": "string" } }, @@ -12853,7 +12853,7 @@ "description": "删除结果；无警告时为空对象。", "properties": { "warnings": { - "description": "删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被包内其他文件 @ref 引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。", + "description": "删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被知识内其他文件 @ref 引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。", "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, @@ -12866,11 +12866,11 @@ "description": "要获取的文件。", "properties": { "pack_id": { - "description": "知识包 ID；默认为调用者的账户范围知识包。", + "description": "知识 ID；默认为调用者的账户范围知识。", "type": "string" }, "rel_path": { - "description": "文件相对于知识包根目录的路径。", + "description": "文件相对于知识根目录的路径。", "type": "string" } }, @@ -12897,7 +12897,7 @@ "type": "object" }, "KnowledgeFileItem": { - "description": "知识包内单个文件的元数据；文件内容需通过 file/get 单独获取。", + "description": "单个知识文件的元数据；文件内容需通过 file/get 单独获取。", "properties": { "checksum": { "description": "文件内容的 SHA-256 十六进制摘要。", @@ -12912,11 +12912,11 @@ "type": "string" }, "pack_id": { - "description": "文件所属的知识包 ID。", + "description": "文件所属的知识 ID。", "type": "string" }, "rel_path": { - "description": "相对于知识包根目录的路径，如 `runbooks/restart.md`。", + "description": "相对于知识根目录的路径，如 `runbooks/restart.md`。", "type": "string" }, "size_bytes": { @@ -12948,7 +12948,7 @@ "type": "object" }, "KnowledgeFileListRequest": { - "description": "要列出文件的知识包。", + "description": "要列出文件的知识。", "properties": { "limit": { "description": "每页条数。目前接受但忽略——响应始终返回完整文件列表。", @@ -12959,24 +12959,24 @@ "type": "integer" }, "pack_id": { - "description": "知识包 ID；默认为调用者的账户范围知识包。", + "description": "知识 ID；默认为调用者的账户范围知识。", "type": "string" } }, "type": "object" }, "KnowledgeFileListResponse": { - "description": "知识包内的文件。", + "description": "知识内的文件。", "properties": { "files": { - "description": "指定知识包内的文件数组；无文件时为空数组。", + "description": "指定知识内的文件数组；无文件时为空数组。", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, "type": "array" }, "total": { - "description": "知识包内文件总数。", + "description": "知识内文件总数。", "format": "int64", "type": "integer" } @@ -12999,11 +12999,11 @@ "type": "string" }, "pack_id": { - "description": "知识包 ID；默认为调用者的账户范围知识包。", + "description": "知识 ID；默认为调用者的账户范围知识。", "type": "string" }, "rel_path": { - "description": "相对于知识包根目录的目标路径；已存在的文件会被覆盖。", + "description": "相对于知识根目录的目标路径；已存在的文件会被覆盖。", "type": "string" } }, @@ -13019,7 +13019,7 @@ "$ref": "#/components/schemas/KnowledgeFileItem" }, "warnings": { - "description": "写入成功后的非阻塞警告数组；`code=unresolved_reference` 表示文件内容中的 @ref 引用了包内不存在的文件。无警告时该字段缺省（omitempty）。", + "description": "写入成功后的非阻塞警告数组；`code=unresolved_reference` 表示文件内容中的 @ref 引用了知识内不存在的文件。无警告时该字段缺省（omitempty）。", "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, @@ -13032,15 +13032,15 @@ "type": "object" }, "KnowledgeGetRequest": { - "description": "无请求字段——固定查询账户范围知识包。", + "description": "无请求字段——固定查询账户范围知识。", "properties": {}, "type": "object" }, "KnowledgeGetResponse": { - "description": "账户范围知识包元数据及其文件列表。", + "description": "账户范围知识元数据及其文件列表。", "properties": { "files": { - "description": "该知识包内的文件数组；无文件时为空数组。", + "description": "该知识内的文件数组；无文件时为空数组。", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, @@ -13057,10 +13057,10 @@ "type": "object" }, "KnowledgePackDeleteRequest": { - "description": "要删除的知识包。", + "description": "要删除的知识。", "properties": { "pack_id": { - "description": "要删除的知识包 ID。", + "description": "要删除的知识 ID。", "type": "string" } }, @@ -13073,7 +13073,7 @@ "description": "删除结果。", "properties": { "ok": { - "description": "知识包删除成功时为 true。", + "description": "知识删除成功时为 true。", "type": "boolean" } }, @@ -13083,10 +13083,10 @@ "type": "object" }, "KnowledgePackEnsureRequest": { - "description": "要确保存在知识包的范围。", + "description": "要确保存在知识的范围。", "properties": { "scope": { - "description": "知识包范围。可选值：`account`（账户级知识包，scope_id 固定为调用方账户 ID，仅账户管理员可创建；首次创建会播种默认 DUTY.md）、`team`（团队级知识包，必须提供 `scope_id` 团队 ID，调用者需属于该团队）。", + "description": "知识范围。可选值：`account`（账户级知识，scope_id 固定为调用方账户 ID，仅账户管理员可创建；首次创建会播种默认 DUTY.md）、`team`（团队级知识，必须提供 `scope_id` 团队 ID，调用者需属于该团队）。", "enum": [ "account", "team" @@ -13105,15 +13105,15 @@ "type": "object" }, "KnowledgePackItem": { - "description": "知识包——一棵带版本号的文件树，AI SRE 会话启动时会注入到每个沙箱中。每个（账户, scope, scope_id）仅有一个知识包。", + "description": "知识——一棵带版本号的文件树，AI SRE 会话启动时会注入到每个沙箱中。每个（账户, scope, scope_id）仅有一份知识。", "properties": { "account_id": { - "description": "知识包所属账户 ID。", + "description": "知识所属账户 ID。", "format": "int64", "type": "integer" }, "can_edit": { - "description": "调用者是否有权限编辑该知识包。", + "description": "调用者是否有权限编辑该知识。", "type": "boolean" }, "created_at_ms": { @@ -13127,19 +13127,19 @@ "type": "integer" }, "duty_version": { - "description": "最后一次撰写或确认 DUTY.md 时的知识库版本。当 `version` 大于该值时，说明 DUTY.md 已不能反映知识库的全部文件。", + "description": "最后一次撰写或确认 DUTY.md 时的知识版本。当 `version` 大于该值时，说明 DUTY.md 已不能反映知识的全部文件。", "type": "integer" }, "file_count": { - "description": "包内文件数量。", + "description": "知识内文件数量。", "type": "integer" }, "pack_id": { - "description": "知识包 ID（`kpk_` 前缀）。", + "description": "知识 ID（`kpk_` 前缀）。", "type": "string" }, "scope": { - "description": "知识包范围；`channel` 为历史遗留范围，新建知识包为 `account` 或 `team`。", + "description": "知识范围；`channel` 为历史遗留范围，新建知识为 `account` 或 `team`。", "enum": [ "account", "team", @@ -13157,7 +13157,7 @@ "type": "string" }, "total_bytes": { - "description": "包内所有文件的总字节数。", + "description": "知识内所有文件的总字节数。", "format": "int64", "type": "integer" }, @@ -13167,7 +13167,7 @@ "type": "integer" }, "version": { - "description": "知识包版本号，文件每次变更时递增。", + "description": "知识版本号，文件每次变更时递增。", "type": "integer" } }, @@ -13188,10 +13188,10 @@ "type": "object" }, "KnowledgePackListRequest": { - "description": "知识包列表的过滤与分页参数。", + "description": "知识列表的过滤与分页参数。", "properties": { "include_account": { - "description": "是否包含账户范围的知识包；默认为 true。", + "description": "是否包含账户范围的知识；默认为 true。", "type": [ "boolean", "null" @@ -13206,12 +13206,12 @@ "type": "integer" }, "query": { - "description": "对知识包 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。", + "description": "对知识 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。", "maxLength": 128, "type": "string" }, "scope": { - "description": "限定范围；`all`（默认）会覆盖 `include_account`。可选值：`all`（账户范围 + 可见团队范围）、`account`（仅账户级知识包）、`team`（仅团队级知识包，可配合 `team_ids` 过滤）。", + "description": "限定范围；`all`（默认）会覆盖 `include_account`。可选值：`all`（账户范围 + 可见团队范围）、`account`（仅账户级知识）、`team`（仅团队级知识，可配合 `team_ids` 过滤）。", "enum": [ "all", "account", @@ -13231,17 +13231,17 @@ "type": "object" }, "KnowledgePackListResponse": { - "description": "可见的知识包及过滤后的总数。", + "description": "可见的知识及过滤后的总数。", "properties": { "packs": { - "description": "过滤后当前可见的知识包数组（当前页），与 `total` 配合分页。", + "description": "过滤后当前可见的知识数组（当前页），与 `total` 配合分页。", "items": { "$ref": "#/components/schemas/KnowledgePackItem" }, "type": "array" }, "total": { - "description": "过滤后、分页前的知识包总数。", + "description": "过滤后、分页前的知识总数。", "format": "int64", "type": "integer" } @@ -13253,14 +13253,14 @@ "type": "object" }, "KnowledgePackUpdateRequest": { - "description": "将知识包移动到其他范围。", + "description": "将知识移动到其他范围。", "properties": { "pack_id": { - "description": "要更新的知识包 ID。", + "description": "要更新的知识 ID。", "type": "string" }, "scope": { - "description": "目标范围；不传则为空操作，返回当前知识包。", + "description": "目标范围；不传则为空操作，返回当前知识。", "enum": [ "account", "team" @@ -13288,7 +13288,7 @@ "description": "文件上传/删除返回的非阻塞提示，例如指向已删除文件的引用。", "properties": { "code": { - "description": "提示码。可选值：`unresolved_reference`（写入的文件内容中 @ref 引用了包内不存在的文件，`ref` 给出该引用）、`still_referenced_by`（被删除的文件仍被包内其他文件 @ref 引用，`refs` 列出引用方）。", + "description": "提示码。可选值：`unresolved_reference`（写入的文件内容中 @ref 引用了知识内不存在的文件，`ref` 给出该引用）、`still_referenced_by`（被删除的文件仍被知识内其他文件 @ref 引用，`refs` 列出引用方）。", "enum": [ "unresolved_reference", "still_referenced_by" @@ -23757,7 +23757,7 @@ "$ref": "#/components/schemas/SessionItem" }, "suggest_init": { - "description": "账户级引导标志：当账户在任何范围内都没有知识包时为 true；并非该会话独有的属性。", + "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；并非该会话独有的属性。", "type": "boolean" }, "pending_messages": { @@ -24111,7 +24111,7 @@ "type": "array" }, "suggest_init": { - "description": "账户级引导标志：当账户在任何范围内都没有知识包时为 true；与本次调用的过滤条件无关。", + "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；与本次调用的过滤条件无关。", "type": "boolean" }, "total": { @@ -52619,7 +52619,7 @@ }, "/safari/knowledge/file/delete": { "post": { - "description": "按相对路径删除知识包中的文件。", + "description": "按相对路径删除知识文件。", "operationId": "knowledge-file-write-delete", "requestBody": { "content": { @@ -52687,7 +52687,7 @@ "AI SRE/知识" ], "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", + "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": "删除知识文件" @@ -52774,7 +52774,7 @@ "AI SRE/知识" ], "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", + "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": "获取知识文件" @@ -52784,7 +52784,7 @@ }, "/safari/knowledge/file/list": { "post": { - "description": "查询知识包内的文件列表，包含大小、校验和等元数据。", + "description": "查询知识文件列表，包含大小、校验和等元数据。", "operationId": "knowledge-file-read-list", "requestBody": { "content": { @@ -52873,7 +52873,7 @@ "AI SRE/知识" ], "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", + "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": "查询知识文件列表" @@ -52883,7 +52883,7 @@ }, "/safari/knowledge/file/put": { "post": { - "description": "以 Base64 编码的内容在知识包中创建或覆盖文件。", + "description": "以 Base64 编码的内容创建或覆盖知识文件。", "operationId": "knowledge-file-write-put", "requestBody": { "content": { @@ -52964,7 +52964,7 @@ "AI SRE/知识" ], "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", + "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": "上传知识文件" @@ -52974,7 +52974,7 @@ }, "/safari/knowledge/get": { "post": { - "description": "返回账户范围知识包的元数据及其文件列表。", + "description": "返回账户范围知识的元数据及其文件列表。", "operationId": "knowledge-pack-read-get", "requestBody": { "content": { @@ -53069,22 +53069,22 @@ "AppKeyAuth": [] } ], - "summary": "查看账户知识包", + "summary": "查看账户知识", "tags": [ "AI SRE/知识" ], "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", + "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": "查看账户知识包" + "sidebarTitle": "查看账户知识" } } } }, "/safari/knowledge/pack/delete": { "post": { - "description": "删除知识包及其全部文件。", + "description": "删除知识及其全部文件。", "operationId": "knowledge-pack-write-delete", "requestBody": { "content": { @@ -53149,22 +53149,22 @@ "AppKeyAuth": [] } ], - "summary": "删除知识包", + "summary": "删除知识", "tags": [ "AI SRE/知识" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除知识包会同时删除其中所有文件，且不可恢复。\n- 允许删除账户范围知识包；下次访问时会重新创建为空包。\n- 每次调用都会记录到账户审计日志。\n", + "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": "删除知识包" + "sidebarTitle": "删除知识" } } } }, "/safari/knowledge/pack/ensure": { "post": { - "description": "在指定范围幂等创建知识包，已存在时直接返回现有知识包。", + "description": "在指定范围幂等创建知识，已存在时直接返回现有知识。", "operationId": "knowledge-pack-write-ensure", "requestBody": { "content": { @@ -53241,22 +53241,22 @@ "AppKeyAuth": [] } ], - "summary": "确保知识包存在", + "summary": "确保知识存在", "tags": [ "AI SRE/知识" ], "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", + "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": "确保知识包存在" + "sidebarTitle": "确保知识存在" } } } }, "/safari/knowledge/pack/list": { "post": { - "description": "查询调用者可见的账户与团队范围知识包列表。", + "description": "查询调用者可见的账户与团队范围知识列表。", "operationId": "knowledge-pack-read-list", "requestBody": { "content": { @@ -53352,22 +53352,22 @@ "AppKeyAuth": [] } ], - "summary": "查询知识包列表", + "summary": "查询知识列表", "tags": [ "AI SRE/知识" ], "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", + "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": "查询知识包列表" + "sidebarTitle": "查询知识列表" } } } }, "/safari/knowledge/pack/update": { "post": { - "description": "将知识包移动到其他账户或团队范围。", + "description": "将知识移动到其他账户或团队范围。", "operationId": "knowledge-pack-write-update", "requestBody": { "content": { @@ -53446,15 +53446,15 @@ "AppKeyAuth": [] } ], - "summary": "更新知识包", + "summary": "更新知识", "tags": [ "AI SRE/知识" ], "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", + "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": "更新知识包" + "sidebarTitle": "更新知识" } } } @@ -54491,7 +54491,7 @@ "AI SRE/会话" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`。\n- `all` 返回调用者自己的个人会话，以及调用者可访问团队的团队会话；账户管理员可见所有团队会话，但不可见他人的个人会话。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n- `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算；`current_turn_*` 字段在此接口恒为 0 —— 仅 `session/get` 会在会话运行时计算它们。\n- `suggest_init` 是账户级的引导提示（仅当账户在任何范围内都没有知识包时为 true），与列表过滤条件无关。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`。\n- `all` 返回调用者自己的个人会话，以及调用者可访问团队的团队会话；账户管理员可见所有团队会话，但不可见他人的个人会话。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n- `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算；`current_turn_*` 字段在此接口恒为 0 —— 仅 `session/get` 会在会话运行时计算它们。\n- `suggest_init` 是账户级的引导提示（仅当账户在任何范围内都没有知识时为 true），与列表过滤条件无关。\n", "href": "/zh/api-reference/ai-sre/sessions/session-read-list", "metadata": { "sidebarTitle": "查询会话列表" diff --git a/api-reference/safari.openapi.en.json b/api-reference/safari.openapi.en.json index 3ede44fa1..396530ce8 100644 --- a/api-reference/safari.openapi.en.json +++ b/api-reference/safari.openapi.en.json @@ -2429,7 +2429,7 @@ } ], "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- Pagination uses `p`/`limit` (max 100); `scope` defaults to `all`.\n- `all` returns your personal sessions plus team sessions you can access; account admins see all team sessions, but not other users' personal sessions.\n- `team_ids` narrows the visible set and never expands access.\n- `is_running` reflects the live run-set; `has_unread` is computed per calling user; the `current_turn_*` fields are always zero here — only `session/get` computes them while a session is running.\n- `suggest_init` is an account-wide onboarding flag (true only when the account has zero knowledge packs anywhere) — it doesn't depend on the list filters.\n", + "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- Pagination uses `p`/`limit` (max 100); `scope` defaults to `all`.\n- `all` returns your personal sessions plus team sessions you can access; account admins see all team sessions, but not other users' personal sessions.\n- `team_ids` narrows the visible set and never expands access.\n- `is_running` reflects the live run-set; `has_unread` is computed per calling user; the `current_turn_*` fields are always zero here — only `session/get` computes them while a session is running.\n- `suggest_init` is an account-wide onboarding flag (true only when the account has no knowledge in any scope) — it doesn't depend on the list filters.\n", "href": "/en/api-reference/ai-sre/sessions/session-read-list", "metadata": { "sidebarTitle": "List sessions" @@ -3189,8 +3189,8 @@ "/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.", + "summary": "Get account knowledge", + "description": "Return the metadata and file list of the account-scope knowledge.", "tags": [ "AI SRE/Knowledge" ], @@ -3200,10 +3200,10 @@ } ], "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", + "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 knowledge — there is no `pack_id` parameter; use `POST /safari/knowledge/pack/list` to discover team knowledge.\n- The account knowledge 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" + "sidebarTitle": "Get account knowledge" } }, "responses": { @@ -3299,8 +3299,8 @@ "/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.", + "summary": "List knowledge", + "description": "List the knowledge visible to the caller across account and team scopes.", "tags": [ "AI SRE/Knowledge" ], @@ -3310,10 +3310,10 @@ } ], "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", + "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 knowledge plus every team's knowledge; non-admins see the account knowledge plus their own teams' knowledge, 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 knowledge 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" + "sidebarTitle": "List knowledge" } }, "responses": { @@ -3410,8 +3410,8 @@ "/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.", + "summary": "Ensure knowledge", + "description": "Idempotently create the knowledge at the given scope, or return the existing one.", "tags": [ "AI SRE/Knowledge" ], @@ -3421,10 +3421,10 @@ } ], "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", + "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 knowledge 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 knowledge 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" + "sidebarTitle": "Ensure knowledge" } }, "responses": { @@ -3502,8 +3502,8 @@ "/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.", + "summary": "Update knowledge", + "description": "Move knowledge to a different account or team scope.", "tags": [ "AI SRE/Knowledge" ], @@ -3513,10 +3513,10 @@ } ], "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", + "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 knowledge.\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 knowledge — knowledge is 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" + "sidebarTitle": "Update knowledge" } }, "responses": { @@ -3596,8 +3596,8 @@ "/safari/knowledge/pack/delete": { "post": { "operationId": "knowledge-pack-write-delete", - "summary": "Delete knowledge pack", - "description": "Delete a knowledge pack and all of its files.", + "summary": "Delete knowledge", + "description": "Delete knowledge and all of its files.", "tags": [ "AI SRE/Knowledge" ], @@ -3607,10 +3607,10 @@ } ], "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", + "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 knowledge removes every file it contains; the operation cannot be undone.\n- Deleting the account-scope knowledge 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" + "sidebarTitle": "Delete knowledge" } }, "responses": { @@ -3677,7 +3677,7 @@ "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.", + "description": "List knowledge files with metadata such as size and checksum.", "tags": [ "AI SRE/Knowledge" ], @@ -3687,7 +3687,7 @@ } ], "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", + "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 knowledge (created lazily if absent).\n- Reading team-scope knowledge 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" @@ -3786,7 +3786,7 @@ } ], "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", + "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); knowledge files are guaranteed UTF-8 text.\n- Omitting `pack_id` targets the account-scope knowledge; reading team-scope knowledge 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" @@ -3863,7 +3863,7 @@ "post": { "operationId": "knowledge-file-write-put", "summary": "Upload knowledge file", - "description": "Create or overwrite a file in a knowledge pack with base64-encoded content.", + "description": "Create or overwrite a knowledge file with base64-encoded content.", "tags": [ "AI SRE/Knowledge" ], @@ -3873,7 +3873,7 @@ } ], "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", + "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 knowledge requires account owner/admin; editing team knowledge 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" @@ -3954,7 +3954,7 @@ "post": { "operationId": "knowledge-file-write-delete", "summary": "Delete knowledge file", - "description": "Delete a file from a knowledge pack by its relative path.", + "description": "Delete a knowledge file by its relative path.", "tags": [ "AI SRE/Knowledge" ], @@ -3964,7 +3964,7 @@ } ], "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", + "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 knowledge 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 knowledge; editing the account knowledge requires account owner/admin, editing team knowledge 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" @@ -6294,15 +6294,15 @@ }, "ContextResolvedItem": { "type": "object", - "description": "Snapshot of the three-tier knowledge-pack resolution for this session.", + "description": "Snapshot of the three-tier knowledge resolution for this session.", "properties": { "account_pack_id": { "type": "string", - "description": "Resolved account-scoped pack id." + "description": "Resolved account-scope knowledge ID." }, "team_pack_id": { "type": "string", - "description": "Resolved team-scoped pack id." + "description": "Resolved team-scope knowledge ID." }, "incident_id": { "type": "string", @@ -6311,14 +6311,14 @@ "resolved_at_ms": { "type": "integer", "format": "int64", - "description": "Unix timestamp in milliseconds when the packs were resolved." + "description": "Unix timestamp in milliseconds when the knowledge was resolved." }, "versions": { "type": "object", "additionalProperties": { "type": "integer" }, - "description": "Per-pack resolved version map." + "description": "Resolved version map, one entry per knowledge." } }, "required": [ @@ -7255,7 +7255,7 @@ }, "suggest_init": { "type": "boolean", - "description": "Account-wide onboarding flag: true when the account has zero knowledge packs in any scope; not specific to this session." + "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not specific to this session." }, "pending_messages": { "type": "array", @@ -7614,7 +7614,7 @@ }, "suggest_init": { "type": "boolean", - "description": "Account-wide onboarding flag: true when the account has zero knowledge packs in any scope; not dependent on this call's filters." + "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not dependent on this call's filters." } }, "required": [ @@ -7962,20 +7962,20 @@ }, "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).", + "description": "Knowledge — a versioned file tree staged into every AI SRE sandbox at session start. One knowledge exists per (account, scope, scope_id).", "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID (`kpk_` prefix)." + "description": "Knowledge ID (`kpk_` prefix)." }, "account_id": { "type": "integer", - "description": "Account that owns the pack.", + "description": "Account that owns the knowledge.", "format": "int64" }, "scope": { "type": "string", - "description": "Pack scope. `channel` is a legacy scope; new packs are `account` or `team`.", + "description": "Knowledge scope. `channel` is a legacy scope; new knowledge is `account` or `team` scope.", "enum": [ "account", "team", @@ -7993,7 +7993,7 @@ }, "file_count": { "type": "integer", - "description": "Number of files in the pack." + "description": "Number of files in the knowledge." }, "total_bytes": { "type": "integer", @@ -8002,30 +8002,30 @@ }, "version": { "type": "integer", - "description": "Pack version, incremented on every file change." + "description": "Knowledge version, incremented on every file change." }, "duty_version": { "type": "integer", - "description": "Pack version at which DUTY.md was last authored or re-affirmed. When `version` is greater, DUTY.md no longer reflects every file in the pack." + "description": "Knowledge version at which DUTY.md was last authored or re-affirmed. When `version` is greater, DUTY.md no longer reflects every file in the knowledge." }, "created_by": { "type": "integer", - "description": "Person ID of the member who created the pack.", + "description": "Person ID of the member who created the knowledge.", "format": "int64" }, "created_at_ms": { "type": "integer", - "description": "Unix timestamp in milliseconds when the pack was created.", + "description": "Unix timestamp in milliseconds when the knowledge was created.", "format": "int64" }, "updated_at_ms": { "type": "integer", - "description": "Unix timestamp in milliseconds when the pack was last modified.", + "description": "Unix timestamp in milliseconds when the knowledge was last modified.", "format": "int64" }, "can_edit": { "type": "boolean", - "description": "Whether the caller can edit this pack." + "description": "Whether the caller can edit this knowledge." } }, "required": [ @@ -8045,7 +8045,7 @@ }, "KnowledgeFileItem": { "type": "object", - "description": "Metadata of one file inside a knowledge pack. Content is fetched separately via file/get.", + "description": "Metadata of one knowledge file. Content is fetched separately via file/get.", "properties": { "file_id": { "type": "string", @@ -8053,11 +8053,11 @@ }, "pack_id": { "type": "string", - "description": "ID of the knowledge pack that contains the file." + "description": "ID of the knowledge that contains the file." }, "rel_path": { "type": "string", - "description": "Path relative to the pack root, e.g. `runbooks/restart.md`." + "description": "Path relative to the knowledge root, e.g. `runbooks/restart.md`." }, "content_type": { "type": "string", @@ -8100,7 +8100,7 @@ "properties": { "code": { "type": "string", - "description": "Warning code. One of: `unresolved_reference` (an @ref in the written file's content points to a file that does not exist in the pack; `ref` carries it), `still_referenced_by` (the deleted file is still @ref-referenced by other files in the pack; `refs` lists the referrers).", + "description": "Warning code. One of: `unresolved_reference` (an @ref in the written file's content points to a file that does not exist in the knowledge; `ref` carries it), `still_referenced_by` (the deleted file is still @ref-referenced by other files in the knowledge; `refs` lists the referrers).", "enum": [ "unresolved_reference", "still_referenced_by" @@ -8124,12 +8124,12 @@ }, "KnowledgeGetRequest": { "type": "object", - "description": "No request fields — the account-scope pack is always targeted.", + "description": "No request fields — the account-scope knowledge is always targeted.", "properties": {} }, "KnowledgePackListRequest": { "type": "object", - "description": "Filter and pagination for the pack list.", + "description": "Filter and pagination for the knowledge list.", "properties": { "p": { "type": "integer", @@ -8141,7 +8141,7 @@ }, "scope": { "type": "string", - "description": "Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level packs only), `team` (team-level packs only, can be combined with `team_ids`).", + "description": "Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level knowledge only), `team` (team-level knowledge only, can be combined with `team_ids`).", "enum": [ "all", "account", @@ -8150,7 +8150,7 @@ }, "query": { "type": "string", - "description": "Case-insensitive substring filter over pack ID, scope, scope ID/account ID, and team name.", + "description": "Case-insensitive substring filter over knowledge ID, scope, scope ID/account ID, and team name.", "maxLength": 128 }, "team_ids": { @@ -8166,17 +8166,17 @@ "boolean", "null" ], - "description": "Include the account-scope pack; defaults to true." + "description": "Include the account-scope knowledge; defaults to true." } } }, "KnowledgePackEnsureRequest": { "type": "object", - "description": "Scope at which to ensure a knowledge pack exists.", + "description": "Scope at which to ensure knowledge exists.", "properties": { "scope": { "type": "string", - "description": "Scope of the pack to ensure. One of: `account` (account-level pack; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level pack; the `scope_id` team ID is required and the caller must belong to that team).", + "description": "Scope of the knowledge to ensure. One of: `account` (account-level knowledge; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level knowledge; the `scope_id` team ID is required and the caller must belong to that team).", "enum": [ "account", "team" @@ -8194,18 +8194,18 @@ }, "KnowledgePackUpdateRequest": { "type": "object", - "description": "Move a knowledge pack to a different scope.", + "description": "Move knowledge to a different scope.", "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID to update." + "description": "Knowledge ID to update." }, "scope": { "type": [ "string", "null" ], - "description": "Destination scope; omit for a no-op that returns the current pack.", + "description": "Destination scope; omit for a no-op that returns the current knowledge.", "enum": [ "account", "team" @@ -8226,11 +8226,11 @@ }, "KnowledgePackDeleteRequest": { "type": "object", - "description": "Pack to delete.", + "description": "Knowledge to delete.", "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID to delete." + "description": "Knowledge ID to delete." } }, "required": [ @@ -8243,7 +8243,7 @@ "properties": { "ok": { "type": "boolean", - "description": "True when the pack was deleted." + "description": "True when the knowledge was deleted." } }, "required": [ @@ -8252,11 +8252,11 @@ }, "KnowledgeFileListRequest": { "type": "object", - "description": "Which pack's files to list.", + "description": "Which knowledge's files to list.", "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + "description": "Knowledge ID; defaults to the caller's account-scope knowledge." }, "p": { "type": "integer", @@ -8274,11 +8274,11 @@ "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + "description": "Knowledge ID; defaults to the caller's account-scope knowledge." }, "rel_path": { "type": "string", - "description": "Path of the file relative to the pack root." + "description": "Path of the file relative to the knowledge root." } }, "required": [ @@ -8291,11 +8291,11 @@ "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + "description": "Knowledge ID; defaults to the caller's account-scope knowledge." }, "rel_path": { "type": "string", - "description": "Destination path relative to the pack root; existing files are overwritten." + "description": "Destination path relative to the knowledge root; existing files are overwritten." }, "content_b64": { "type": "string", @@ -8312,7 +8312,7 @@ }, "KnowledgeGetResponse": { "type": "object", - "description": "Account-scope pack metadata plus its file list.", + "description": "Account-scope knowledge metadata plus its file list.", "properties": { "pack": { "$ref": "#/components/schemas/KnowledgePackItem" @@ -8322,7 +8322,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, - "description": "Array of files in this knowledge pack; empty array when the pack has no files." + "description": "Array of files in this knowledge; empty array when it has no files." } }, "required": [ @@ -8332,18 +8332,18 @@ }, "KnowledgePackListResponse": { "type": "object", - "description": "Visible packs and the total after filtering.", + "description": "Visible knowledge and the total after filtering.", "properties": { "packs": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgePackItem" }, - "description": "Array of visible knowledge packs after filtering (current page), used with `total` for pagination." + "description": "Array of visible knowledge after filtering (current page), used with `total` for pagination." }, "total": { "type": "integer", - "description": "Total number of packs after filtering, before pagination.", + "description": "Total number of knowledge entries after filtering, before pagination.", "format": "int64" } }, @@ -8354,18 +8354,18 @@ }, "KnowledgeFileListResponse": { "type": "object", - "description": "Files in the pack.", + "description": "Files in the knowledge.", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, - "description": "Array of files in the specified knowledge pack; empty array when the pack has no files." + "description": "Array of files in the specified knowledge; empty array when it has no files." }, "total": { "type": "integer", - "description": "Total number of files in the pack.", + "description": "Total number of files in the knowledge.", "format": "int64" } }, @@ -8403,7 +8403,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, - "description": "Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the pack. Absent when there are no warnings (omitempty)." + "description": "Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the knowledge. Absent when there are no warnings (omitempty)." } }, "required": [ @@ -8412,19 +8412,19 @@ }, "KnowledgeFileDeleteRequest": { "type": "object", - "description": "File to remove from a knowledge pack.", + "description": "Knowledge file to remove.", "properties": { "pack_id": { "type": "string", - "description": "Knowledge pack ID; defaults to the caller's account-scope pack." + "description": "Knowledge ID; defaults to the caller's account-scope knowledge." }, "rel_path": { "type": "string", - "description": "Path of the file relative to the pack root." + "description": "Path of the file relative to the knowledge 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." + "description": "Delete even when other knowledge files reference this file; the referrers are then returned as warnings instead of blocking the delete." } }, "required": [ @@ -8440,7 +8440,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, - "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the pack (`refs` lists the referrers). Absent when there are no warnings (omitempty)." + "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the knowledge (`refs` lists the referrers). Absent when there are no warnings (omitempty)." } } }, diff --git a/api-reference/safari.openapi.zh.json b/api-reference/safari.openapi.zh.json index 3b78f4295..56a04ca72 100644 --- a/api-reference/safari.openapi.zh.json +++ b/api-reference/safari.openapi.zh.json @@ -2429,7 +2429,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`。\n- `all` 返回调用者自己的个人会话，以及调用者可访问团队的团队会话；账户管理员可见所有团队会话，但不可见他人的个人会话。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n- `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算；`current_turn_*` 字段在此接口恒为 0 —— 仅 `session/get` 会在会话运行时计算它们。\n- `suggest_init` 是账户级的引导提示（仅当账户在任何范围内都没有知识包时为 true），与列表过滤条件无关。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`。\n- `all` 返回调用者自己的个人会话，以及调用者可访问团队的团队会话；账户管理员可见所有团队会话，但不可见他人的个人会话。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n- `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算；`current_turn_*` 字段在此接口恒为 0 —— 仅 `session/get` 会在会话运行时计算它们。\n- `suggest_init` 是账户级的引导提示（仅当账户在任何范围内都没有知识时为 true），与列表过滤条件无关。\n", "href": "/zh/api-reference/ai-sre/sessions/session-read-list", "metadata": { "sidebarTitle": "查询会话列表" @@ -3189,8 +3189,8 @@ "/safari/knowledge/get": { "post": { "operationId": "knowledge-pack-read-get", - "summary": "查看账户知识包", - "description": "返回账户范围知识包的元数据及其文件列表。", + "summary": "查看账户知识", + "description": "返回账户范围知识的元数据及其文件列表。", "tags": [ "AI SRE/知识" ], @@ -3200,10 +3200,10 @@ } ], "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", + "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": "查看账户知识包" + "sidebarTitle": "查看账户知识" } }, "responses": { @@ -3299,8 +3299,8 @@ "/safari/knowledge/pack/list": { "post": { "operationId": "knowledge-pack-read-list", - "summary": "查询知识包列表", - "description": "查询调用者可见的账户与团队范围知识包列表。", + "summary": "查询知识列表", + "description": "查询调用者可见的账户与团队范围知识列表。", "tags": [ "AI SRE/知识" ], @@ -3310,10 +3310,10 @@ } ], "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", + "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": "查询知识包列表" + "sidebarTitle": "查询知识列表" } }, "responses": { @@ -3410,8 +3410,8 @@ "/safari/knowledge/pack/ensure": { "post": { "operationId": "knowledge-pack-write-ensure", - "summary": "确保知识包存在", - "description": "在指定范围幂等创建知识包，已存在时直接返回现有知识包。", + "summary": "确保知识存在", + "description": "在指定范围幂等创建知识，已存在时直接返回现有知识。", "tags": [ "AI SRE/知识" ], @@ -3421,10 +3421,10 @@ } ], "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", + "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": "确保知识包存在" + "sidebarTitle": "确保知识存在" } }, "responses": { @@ -3502,8 +3502,8 @@ "/safari/knowledge/pack/update": { "post": { "operationId": "knowledge-pack-write-update", - "summary": "更新知识包", - "description": "将知识包移动到其他账户或团队范围。", + "summary": "更新知识", + "description": "将知识移动到其他账户或团队范围。", "tags": [ "AI SRE/知识" ], @@ -3513,10 +3513,10 @@ } ], "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", + "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": "更新知识包" + "sidebarTitle": "更新知识" } }, "responses": { @@ -3596,8 +3596,8 @@ "/safari/knowledge/pack/delete": { "post": { "operationId": "knowledge-pack-write-delete", - "summary": "删除知识包", - "description": "删除知识包及其全部文件。", + "summary": "删除知识", + "description": "删除知识及其全部文件。", "tags": [ "AI SRE/知识" ], @@ -3607,10 +3607,10 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识库管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除知识包会同时删除其中所有文件，且不可恢复。\n- 允许删除账户范围知识包；下次访问时会重新创建为空包。\n- 每次调用都会记录到账户审计日志。\n", + "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": "删除知识包" + "sidebarTitle": "删除知识" } }, "responses": { @@ -3677,7 +3677,7 @@ "post": { "operationId": "knowledge-file-read-list", "summary": "查询知识文件列表", - "description": "查询知识包内的文件列表，包含大小、校验和等元数据。", + "description": "查询知识文件列表，包含大小、校验和等元数据。", "tags": [ "AI SRE/知识" ], @@ -3687,7 +3687,7 @@ } ], "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", + "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": "查询知识文件列表" @@ -3786,7 +3786,7 @@ } ], "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", + "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": "获取知识文件" @@ -3863,7 +3863,7 @@ "post": { "operationId": "knowledge-file-write-put", "summary": "上传知识文件", - "description": "以 Base64 编码的内容在知识包中创建或覆盖文件。", + "description": "以 Base64 编码的内容创建或覆盖知识文件。", "tags": [ "AI SRE/知识" ], @@ -3873,7 +3873,7 @@ } ], "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", + "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": "上传知识文件" @@ -3954,7 +3954,7 @@ "post": { "operationId": "knowledge-file-write-delete", "summary": "删除知识文件", - "description": "按相对路径删除知识包中的文件。", + "description": "按相对路径删除知识文件。", "tags": [ "AI SRE/知识" ], @@ -3964,7 +3964,7 @@ } ], "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", + "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": "删除知识文件" @@ -6294,15 +6294,15 @@ }, "ContextResolvedItem": { "type": "object", - "description": "该会话三层知识包解析结果的快照。", + "description": "该会话三层知识解析结果的快照。", "properties": { "account_pack_id": { "type": "string", - "description": "解析出的账户级知识包 ID。" + "description": "解析出的账户级知识 ID。" }, "team_pack_id": { "type": "string", - "description": "解析出的团队级知识包 ID。" + "description": "解析出的团队级知识 ID。" }, "incident_id": { "type": "string", @@ -6311,14 +6311,14 @@ "resolved_at_ms": { "type": "integer", "format": "int64", - "description": "知识包解析时间，Unix 毫秒时间戳。" + "description": "知识解析时间，Unix 毫秒时间戳。" }, "versions": { "type": "object", "additionalProperties": { "type": "integer" }, - "description": "各知识包解析版本映射。" + "description": "各份知识的解析版本映射。" } }, "required": [ @@ -7255,7 +7255,7 @@ }, "suggest_init": { "type": "boolean", - "description": "账户级引导标志：当账户在任何范围内都没有知识包时为 true；并非该会话独有的属性。" + "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；并非该会话独有的属性。" }, "pending_messages": { "type": "array", @@ -7614,7 +7614,7 @@ }, "suggest_init": { "type": "boolean", - "description": "账户级引导标志：当账户在任何范围内都没有知识包时为 true；与本次调用的过滤条件无关。" + "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；与本次调用的过滤条件无关。" } }, "required": [ @@ -7962,20 +7962,20 @@ }, "KnowledgePackItem": { "type": "object", - "description": "知识包——一棵带版本号的文件树，AI SRE 会话启动时会注入到每个沙箱中。每个（账户, scope, scope_id）仅有一个知识包。", + "description": "知识——一棵带版本号的文件树，AI SRE 会话启动时会注入到每个沙箱中。每个（账户, scope, scope_id）仅有一份知识。", "properties": { "pack_id": { "type": "string", - "description": "知识包 ID（`kpk_` 前缀）。" + "description": "知识 ID（`kpk_` 前缀）。" }, "account_id": { "type": "integer", - "description": "知识包所属账户 ID。", + "description": "知识所属账户 ID。", "format": "int64" }, "scope": { "type": "string", - "description": "知识包范围；`channel` 为历史遗留范围，新建知识包为 `account` 或 `team`。", + "description": "知识范围；`channel` 为历史遗留范围，新建知识为 `account` 或 `team`。", "enum": [ "account", "team", @@ -7993,20 +7993,20 @@ }, "file_count": { "type": "integer", - "description": "包内文件数量。" + "description": "知识内文件数量。" }, "total_bytes": { "type": "integer", - "description": "包内所有文件的总字节数。", + "description": "知识内所有文件的总字节数。", "format": "int64" }, "version": { "type": "integer", - "description": "知识包版本号，文件每次变更时递增。" + "description": "知识版本号，文件每次变更时递增。" }, "duty_version": { "type": "integer", - "description": "最后一次撰写或确认 DUTY.md 时的知识库版本。当 `version` 大于该值时，说明 DUTY.md 已不能反映知识库的全部文件。" + "description": "最后一次撰写或确认 DUTY.md 时的知识版本。当 `version` 大于该值时，说明 DUTY.md 已不能反映知识的全部文件。" }, "created_by": { "type": "integer", @@ -8025,7 +8025,7 @@ }, "can_edit": { "type": "boolean", - "description": "调用者是否有权限编辑该知识包。" + "description": "调用者是否有权限编辑该知识。" } }, "required": [ @@ -8045,7 +8045,7 @@ }, "KnowledgeFileItem": { "type": "object", - "description": "知识包内单个文件的元数据；文件内容需通过 file/get 单独获取。", + "description": "单个知识文件的元数据；文件内容需通过 file/get 单独获取。", "properties": { "file_id": { "type": "string", @@ -8053,11 +8053,11 @@ }, "pack_id": { "type": "string", - "description": "文件所属的知识包 ID。" + "description": "文件所属的知识 ID。" }, "rel_path": { "type": "string", - "description": "相对于知识包根目录的路径，如 `runbooks/restart.md`。" + "description": "相对于知识根目录的路径，如 `runbooks/restart.md`。" }, "content_type": { "type": "string", @@ -8100,7 +8100,7 @@ "properties": { "code": { "type": "string", - "description": "提示码。可选值：`unresolved_reference`（写入的文件内容中 @ref 引用了包内不存在的文件，`ref` 给出该引用）、`still_referenced_by`（被删除的文件仍被包内其他文件 @ref 引用，`refs` 列出引用方）。", + "description": "提示码。可选值：`unresolved_reference`（写入的文件内容中 @ref 引用了知识内不存在的文件，`ref` 给出该引用）、`still_referenced_by`（被删除的文件仍被知识内其他文件 @ref 引用，`refs` 列出引用方）。", "enum": [ "unresolved_reference", "still_referenced_by" @@ -8124,12 +8124,12 @@ }, "KnowledgeGetRequest": { "type": "object", - "description": "无请求字段——固定查询账户范围知识包。", + "description": "无请求字段——固定查询账户范围知识。", "properties": {} }, "KnowledgePackListRequest": { "type": "object", - "description": "知识包列表的过滤与分页参数。", + "description": "知识列表的过滤与分页参数。", "properties": { "p": { "type": "integer", @@ -8141,7 +8141,7 @@ }, "scope": { "type": "string", - "description": "限定范围；`all`（默认）会覆盖 `include_account`。可选值：`all`（账户范围 + 可见团队范围）、`account`（仅账户级知识包）、`team`（仅团队级知识包，可配合 `team_ids` 过滤）。", + "description": "限定范围；`all`（默认）会覆盖 `include_account`。可选值：`all`（账户范围 + 可见团队范围）、`account`（仅账户级知识）、`team`（仅团队级知识，可配合 `team_ids` 过滤）。", "enum": [ "all", "account", @@ -8150,7 +8150,7 @@ }, "query": { "type": "string", - "description": "对知识包 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。", + "description": "对知识 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。", "maxLength": 128 }, "team_ids": { @@ -8166,17 +8166,17 @@ "boolean", "null" ], - "description": "是否包含账户范围的知识包；默认为 true。" + "description": "是否包含账户范围的知识；默认为 true。" } } }, "KnowledgePackEnsureRequest": { "type": "object", - "description": "要确保存在知识包的范围。", + "description": "要确保存在知识的范围。", "properties": { "scope": { "type": "string", - "description": "知识包范围。可选值：`account`（账户级知识包，scope_id 固定为调用方账户 ID，仅账户管理员可创建；首次创建会播种默认 DUTY.md）、`team`（团队级知识包，必须提供 `scope_id` 团队 ID，调用者需属于该团队）。", + "description": "知识范围。可选值：`account`（账户级知识，scope_id 固定为调用方账户 ID，仅账户管理员可创建；首次创建会播种默认 DUTY.md）、`team`（团队级知识，必须提供 `scope_id` 团队 ID，调用者需属于该团队）。", "enum": [ "account", "team" @@ -8194,18 +8194,18 @@ }, "KnowledgePackUpdateRequest": { "type": "object", - "description": "将知识包移动到其他范围。", + "description": "将知识移动到其他范围。", "properties": { "pack_id": { "type": "string", - "description": "要更新的知识包 ID。" + "description": "要更新的知识 ID。" }, "scope": { "type": [ "string", "null" ], - "description": "目标范围；不传则为空操作，返回当前知识包。", + "description": "目标范围；不传则为空操作，返回当前知识。", "enum": [ "account", "team" @@ -8226,11 +8226,11 @@ }, "KnowledgePackDeleteRequest": { "type": "object", - "description": "要删除的知识包。", + "description": "要删除的知识。", "properties": { "pack_id": { "type": "string", - "description": "要删除的知识包 ID。" + "description": "要删除的知识 ID。" } }, "required": [ @@ -8243,7 +8243,7 @@ "properties": { "ok": { "type": "boolean", - "description": "知识包删除成功时为 true。" + "description": "知识删除成功时为 true。" } }, "required": [ @@ -8252,11 +8252,11 @@ }, "KnowledgeFileListRequest": { "type": "object", - "description": "要列出文件的知识包。", + "description": "要列出文件的知识。", "properties": { "pack_id": { "type": "string", - "description": "知识包 ID；默认为调用者的账户范围知识包。" + "description": "知识 ID；默认为调用者的账户范围知识。" }, "p": { "type": "integer", @@ -8274,11 +8274,11 @@ "properties": { "pack_id": { "type": "string", - "description": "知识包 ID；默认为调用者的账户范围知识包。" + "description": "知识 ID；默认为调用者的账户范围知识。" }, "rel_path": { "type": "string", - "description": "文件相对于知识包根目录的路径。" + "description": "文件相对于知识根目录的路径。" } }, "required": [ @@ -8291,11 +8291,11 @@ "properties": { "pack_id": { "type": "string", - "description": "知识包 ID；默认为调用者的账户范围知识包。" + "description": "知识 ID；默认为调用者的账户范围知识。" }, "rel_path": { "type": "string", - "description": "相对于知识包根目录的目标路径；已存在的文件会被覆盖。" + "description": "相对于知识根目录的目标路径；已存在的文件会被覆盖。" }, "content_b64": { "type": "string", @@ -8312,7 +8312,7 @@ }, "KnowledgeGetResponse": { "type": "object", - "description": "账户范围知识包元数据及其文件列表。", + "description": "账户范围知识元数据及其文件列表。", "properties": { "pack": { "$ref": "#/components/schemas/KnowledgePackItem" @@ -8322,7 +8322,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, - "description": "该知识包内的文件数组；无文件时为空数组。" + "description": "该知识内的文件数组；无文件时为空数组。" } }, "required": [ @@ -8332,18 +8332,18 @@ }, "KnowledgePackListResponse": { "type": "object", - "description": "可见的知识包及过滤后的总数。", + "description": "可见的知识及过滤后的总数。", "properties": { "packs": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgePackItem" }, - "description": "过滤后当前可见的知识包数组（当前页），与 `total` 配合分页。" + "description": "过滤后当前可见的知识数组（当前页），与 `total` 配合分页。" }, "total": { "type": "integer", - "description": "过滤后、分页前的知识包总数。", + "description": "过滤后、分页前的知识总数。", "format": "int64" } }, @@ -8354,18 +8354,18 @@ }, "KnowledgeFileListResponse": { "type": "object", - "description": "知识包内的文件。", + "description": "知识内的文件。", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeFileItem" }, - "description": "指定知识包内的文件数组；无文件时为空数组。" + "description": "指定知识内的文件数组；无文件时为空数组。" }, "total": { "type": "integer", - "description": "知识包内文件总数。", + "description": "知识内文件总数。", "format": "int64" } }, @@ -8403,7 +8403,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, - "description": "写入成功后的非阻塞警告数组；`code=unresolved_reference` 表示文件内容中的 @ref 引用了包内不存在的文件。无警告时该字段缺省（omitempty）。" + "description": "写入成功后的非阻塞警告数组；`code=unresolved_reference` 表示文件内容中的 @ref 引用了知识内不存在的文件。无警告时该字段缺省（omitempty）。" } }, "required": [ @@ -8412,19 +8412,19 @@ }, "KnowledgeFileDeleteRequest": { "type": "object", - "description": "要从知识包中删除的文件。", + "description": "要删除的知识文件。", "properties": { "pack_id": { "type": "string", - "description": "知识包 ID；默认为调用者的账户范围知识包。" + "description": "知识 ID；默认为调用者的账户范围知识。" }, "rel_path": { "type": "string", - "description": "文件相对于知识包根目录的路径。" + "description": "文件相对于知识根目录的路径。" }, "force": { "type": "boolean", - "description": "即使其他包内文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。" + "description": "即使其他知识文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。" } }, "required": [ @@ -8440,7 +8440,7 @@ "items": { "$ref": "#/components/schemas/KnowledgeWarning" }, - "description": "删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被包内其他文件 @ref 引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。" + "description": "删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被知识内其他文件 @ref 引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。" } } }, diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx index 54265f2f6..971ce3139 100644 --- a/en/openapi/api-catalog.mdx +++ b/en/openapi/api-catalog.mdx @@ -491,11 +491,11 @@ Only plain human messages are projected: rows produced by internal producers (au | Method | Endpoint | Description | | :--- | :--- | :--- | -| POST | [`/safari/knowledge/pack/list`](/en/api-reference/ai-sre/knowledge/knowledge-pack-read-list) | List knowledge packs | -| POST | [`/safari/knowledge/get`](/en/api-reference/ai-sre/knowledge/knowledge-pack-read-get) | Get account knowledge pack | -| POST | [`/safari/knowledge/pack/ensure`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure) | Ensure knowledge pack | -| POST | [`/safari/knowledge/pack/update`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-update) | Update knowledge pack | -| POST | [`/safari/knowledge/pack/delete`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-delete) | Delete knowledge pack | +| POST | [`/safari/knowledge/pack/list`](/en/api-reference/ai-sre/knowledge/knowledge-pack-read-list) | List knowledge | +| POST | [`/safari/knowledge/get`](/en/api-reference/ai-sre/knowledge/knowledge-pack-read-get) | Get account knowledge | +| POST | [`/safari/knowledge/pack/ensure`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure) | Ensure knowledge | +| POST | [`/safari/knowledge/pack/update`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-update) | Update knowledge | +| POST | [`/safari/knowledge/pack/delete`](/en/api-reference/ai-sre/knowledge/knowledge-pack-write-delete) | Delete knowledge | | POST | [`/safari/knowledge/file/list`](/en/api-reference/ai-sre/knowledge/knowledge-file-read-list) | List knowledge files | | POST | [`/safari/knowledge/file/get`](/en/api-reference/ai-sre/knowledge/knowledge-file-read-get) | Get knowledge file | | POST | [`/safari/knowledge/file/put`](/en/api-reference/ai-sre/knowledge/knowledge-file-write-put) | Upload knowledge file | diff --git a/zh/ai-sre.mdx b/zh/ai-sre.mdx index 0cef25ee0..43e90cf72 100644 --- a/zh/ai-sre.mdx +++ b/zh/ai-sre.mdx @@ -25,7 +25,7 @@ Flashduty AI SRE 是一个对话式的自治 SRE Agent 平台。你用自然语 从故障或作战室一键拉起会话，Agent 携带上下文进入排查，沉淀的知识反哺下一次响应 - 以 DUTY.md 为入口的知识库承载服务清单、runbook、值班路径等长期上下文 + 以 DUTY.md 为入口的知识承载服务清单、runbook、值班路径等长期上下文 通过 Skill、MCP、A2A Agent 扩展能力；自托管 Runner 让排障进入你的内网 diff --git a/zh/ai-sre/agents.mdx b/zh/ai-sre/agents.mdx index 7b833fb56..f1272b4c2 100644 --- a/zh/ai-sre/agents.mdx +++ b/zh/ai-sre/agents.mdx @@ -303,7 +303,7 @@ A2A Agent 的完整生命周期可在 **自定义 → 插件 → Agents** 页面 --- -A2A Agent 与其他资源（Skill、知识库、MCP、运行环境）共用同一套**两级作用域**模型，分为账户级与团队级。控制台界面中，账户级这一档显示为「**共享**」/「**共享范围**」，与账户级同义（整个账户内可见）： +A2A Agent 与其他资源（Skill、知识、MCP、运行环境）共用同一套**两级作用域**模型，分为账户级与团队级。控制台界面中，账户级这一档显示为「**共享**」/「**共享范围**」，与账户级同义（整个账户内可见）： | 作用域 | 可见性 | | --- | --- | @@ -328,7 +328,7 @@ A2A Agent 与其他资源（Skill、知识库、MCP、运行环境）共用同 为 Agent 接入外部工具，扩展其在任务中的能力边界。 - 用 DUTY.md 与知识库为 Agent 提供团队上下文与排障经验。 + 用 DUTY.md 与知识为 Agent 提供团队上下文与排障经验。 在 IM 群里 @ AI SRE，并了解故障作战室的自动诊断。 diff --git a/zh/ai-sre/automations.mdx b/zh/ai-sre/automations.mdx index b2b5937ac..1488d0935 100644 --- a/zh/ai-sre/automations.mdx +++ b/zh/ai-sre/automations.mdx @@ -235,7 +235,7 @@ API 返回的运行记录还包含 `trigger_kind`，可能取值为 `schedule` ### 作用域与权限 -自动化规则与 AI SRE 下的其它资源（Skill、知识库、MCP、Agent、运行环境）共用同一套两级作用域： +自动化规则与 AI SRE 下的其它资源（Skill、知识、MCP、Agent、运行环境）共用同一套两级作用域： | 维度 | 规则 | |---|---| diff --git a/zh/ai-sre/context.mdx b/zh/ai-sre/context.mdx index 7447d16ef..e8d0fffb4 100644 --- a/zh/ai-sre/context.mdx +++ b/zh/ai-sre/context.mdx @@ -1,7 +1,7 @@ --- title: 了解上下文 -description: 上下文是 AI SRE 排障时带着的两类长期资料。知识库由人维护，记忆由系统整理。控制台在 自定义 → 上下文 分组下为它们各设一页。 -keywords: ["AI SRE", "上下文", "知识库", "记忆", "DUTY.md"] +description: 上下文是 AI SRE 排障时带着的两类长期资料。知识由人维护，记忆由系统整理。控制台在 自定义 → 上下文 分组下为它们各设一页。 +keywords: ["AI SRE", "上下文", "知识", "记忆", "DUTY.md"] sidebarTitle: 了解上下文 --- @@ -15,7 +15,7 @@ sidebarTitle: 了解上下文 上下文是 AI SRE 在一次排障里能反复用到的长期资料。它分成两种，在控制台 **AI SRE → 自定义** 侧栏的 **上下文** 分组下各有一页。 -- **[知识库](/zh/ai-sre/knowledge)**是人维护的。它写的是这个环境怎么运转：一份使用说明 `DUTY.md`，加上运行手册、服务清单等文件。会话开始时会读使用说明，其它文件在需要时再打开。入口：**AI SRE → 自定义 → 上下文 → 知识库**。 +- **[知识](/zh/ai-sre/knowledge)**是人维护的。它写的是这个环境怎么运转：一份使用说明 `DUTY.md`，加上运行手册、服务清单等文件。会话开始时会读使用说明，其它文件在需要时再打开。入口：**AI SRE → 自定义 → 上下文 → 知识**。 - **[记忆](/zh/ai-sre/memory)**是系统整理的。会话结束后，系统从对话里留下以后还会用到的偏好、做法、事实和教训。你也可以在对话里直接说记住或忘掉一件事。入口：**AI SRE → 自定义 → 上下文 → 记忆**。 两页底部都有一个输入框：写下要改什么，控制台会打开新对话，由 AI 先说明改动、经你同意后保存。 @@ -26,20 +26,20 @@ sidebarTitle: 了解上下文 两类资料都按范围组织，但支持的范围不同。 -| 范围 | 记忆 | 知识库 | +| 范围 | 记忆 | 知识 | | --- | --- | --- | | 个人 | 你自己的 | 没有 | | 团队 | 这个团队的 | 这个团队的那一份（每个团队最多 1 个） | | 共享 | 没有 | 整个账户的那一份 | -个人范围没有知识库。共享范围没有记忆。 +个人范围没有知识。共享范围没有记忆。 ## 接着看 --- - + 使用说明、运行手册和文件怎么组织，以及助手在会话里怎么读它们。 diff --git a/zh/ai-sre/im.mdx b/zh/ai-sre/im.mdx index 752362533..36d357eb7 100644 --- a/zh/ai-sre/im.mdx +++ b/zh/ai-sre/im.mdx @@ -143,7 +143,7 @@ IM 会话没有控制台那样的选择器 UI，但支持两条斜杠命令在** ### /env — 切换运行环境 -在群聊或私聊里向机器人发送 `/env <目标>`，可将当前 IM 会话重新绑定到另一个运行环境，对话历史与上下文完整保留。切换后，旧环境的工作目录不再可用：本次对话中在旧环境里创建或修改的文件已丢失，技能与知识库文件会在新环境中按需重新挂载。 +在群聊或私聊里向机器人发送 `/env <目标>`，可将当前 IM 会话重新绑定到另一个运行环境，对话历史与上下文完整保留。切换后，旧环境的工作目录不再可用：本次对话中在旧环境里创建或修改的文件已丢失，技能与知识文件会在新环境中按需重新挂载。 `<目标>` 有三种写法： @@ -170,11 +170,11 @@ IM 会话没有控制台那样的选择器 UI，但支持两条斜杠命令在** 切换后，AI SRE 会： 1. 将记忆快照刷新为新团队作用域下的记忆（旧团队的记忆不再适用于本次会话）。 -2. 把新团队的知识库排入挂载队列，在下一条消息处理时自动注入上下文。 +2. 把新团队的知识排入挂载队列，在下一条消息处理时自动注入上下文。 3. 检查本次会话钉定的运行环境是否仍然可用：如果钉定的是**另一个团队独有**的 BYOC Runner 或云端沙箱模板，会把运行环境改回「自动选择」，并回复「「x」不属于当前团队，运行环境已改回自动选择。」共享环境与账户级环境不受影响；无法确认归属时（例如模板列表拉取失败）保持原有钉定不变。 -已挂载到本次会话的知识库不会被移除——挂载是对话级别的，切回之前挂载过的团队不会重复注入提醒。 +已挂载到本次会话的知识不会被移除——挂载是对话级别的，切回之前挂载过的团队不会重复注入提醒。 ## /feedback — 评价 AI SRE 的回复 diff --git a/zh/ai-sre/init.mdx b/zh/ai-sre/init.mdx index bda25aaaa..7e8d8daf1 100644 --- a/zh/ai-sre/init.mdx +++ b/zh/ai-sre/init.mdx @@ -1,7 +1,7 @@ --- title: 初始化（/init） -description: 在 AI SRE 会话中输入 /init，由 Agent 以访谈的方式带你从零搭建运维知识库（DUTY.md + runbook + 服务清单等）并按需接入 MCP——每一项写入都需你逐条确认。 -keywords: ["AI SRE", "init", "运营作战图", "知识库", "onboarding", "DUTY.md", "runbook", "MCP"] +description: 在 AI SRE 会话中输入 /init，由 Agent 以访谈的方式带你从零搭建运维知识（DUTY.md + runbook + 服务清单等）并按需接入 MCP——每一项写入都需你逐条确认。 +keywords: ["AI SRE", "init", "运营作战图", "知识", "onboarding", "DUTY.md", "runbook", "MCP"] sidebarTitle: 初始化 --- @@ -13,9 +13,9 @@ sidebarTitle: 初始化 --- -在任意 AI SRE 会话的输入框中输入 `/init`，Agent 会切换成一名**运维 onboarding 访谈者**，带你从零搭建一份运维知识库——也就是这个团队的「运营作战图」。它会扫描你的 Flashduty 故障与通知渠道、向你提问、把你口述的服务拓扑、排查手册、集群访问方式等沉淀成知识文件，并在需要时帮你接入外部工具（MCP）。 +在任意 AI SRE 会话的输入框中输入 `/init`，Agent 会切换成一名**运维 onboarding 访谈者**，带你从零搭建一份运维知识——也就是这个团队的「运营作战图」。它会扫描你的 Flashduty 故障与通知渠道、向你提问、把你口述的服务拓扑、排查手册、集群访问方式等沉淀成知识文件，并在需要时帮你接入外部工具（MCP）。 -`/init` 是知识库的**起点**。AI SRE 的诊断质量直接取决于它能读到多少关于你系统的真实知识：[知识库](/zh/ai-sre/knowledge)维护得越完整、越准确，Agent 定位根因就越快、越靠谱。`/init` 就是把这份知识从零建立起来的引导流程，建完之后每一次会话都会自动加载它。 +`/init` 是搭建知识的**起点**。AI SRE 的诊断质量直接取决于它能读到多少关于你系统的真实知识：[知识](/zh/ai-sre/knowledge)维护得越完整、越准确，Agent 定位根因就越快、越靠谱。`/init` 就是把这份知识从零建立起来的引导流程，建完之后每一次会话都会自动加载它。 `/init` **不会**在未经你同意的情况下写入或安装任何东西。每个阶段在写入文件前都会列出「将要创建/更新哪些文件」的清单，由你逐条确认后才执行。凭证（token、密码、AK/SK）永远不会在对话里明文回显，只记为 `<已记录（长度=N）>`。详见 [安全与同意](#安全与同意)。 @@ -29,12 +29,12 @@ sidebarTitle: 初始化 | 场景 | 用法 | |---|---| -| 第一次给某个账户 / 团队搭知识库 | **`/init`**——它会成体系地走完服务、可观测性、runbook、常见故障、集群访问等主题 | -| 系统性地补全或重整一个已有知识库 | **`/init`**——可随时重跑，它会基于现有内容继续，而非推倒重来 | +| 第一次给某个账户 / 团队搭建知识 | **`/init`**——它会成体系地走完服务、可观测性、runbook、常见故障、集群访问等主题 | +| 系统性地补全或重整一份已有知识 | **`/init`**——可随时重跑，它会基于现有内容继续，而非推倒重来 | | 「补一篇 runbook」「更新 services.md」「记一下这个故障模式」 | **直接用自然语言说**，无需 `/init`——Agent 会就当前会话作用域读取、编辑、保存 | -`/init` 与零散的自然语言编辑是互补的：用 `/init` 把底子打全，之后在日常排障里随手让 Agent「把这条经验记进知识库」做增量维护。两者写入的是同一个知识库。 +`/init` 与零散的自然语言编辑是互补的：用 `/init` 把底子打全，之后在日常排障里随手让 Agent「把这条经验记进知识」做增量维护。两者写入的是同一份知识。 ## 如何运行 @@ -52,7 +52,7 @@ sidebarTitle: 初始化 Agent 按主题逐阶段提问（服务与拓扑、可观测性、runbook、常见故障、集群访问……），把你的回答整理成知识文件草稿。每个阶段结束都会问你「继续下一项，还是先停在这里」。 - 每个阶段写入文件前，Agent 会给出一份「将创建/更新哪些文件」的清单，每个文件配 3–5 行摘要。你确认后它才写入知识库，并把新文件链接进 `DUTY.md` 目录。 + 每个阶段写入文件前，Agent 会给出一份「将创建/更新哪些文件」的清单，每个文件配 3–5 行摘要。你确认后它才写入知识，并把新文件链接进 `DUTY.md` 目录。 你可以随时说「跳过这项」「回到第 N 步」「先到这里」。`/init` 不是一次性的——之后任何时候重新输入 `/init` 都能基于已有知识继续补全。 @@ -73,7 +73,7 @@ sidebarTitle: 初始化 通过 Flashduty MCP 拉取你的渠道、近 30 天故障、团队与成员，归纳出你在用的集成类型与高频故障标签。若扫描结果为空（全新账户），切换到「冷启动」模式，改为完全靠访谈采集。 - 可选步骤，需你主动同意，绝不自动触发。如果你已经在 Claude Code / Codex / Cursor / Windsurf / Copilot / Gemini CLI 等本地工具里积累了知识与记忆，可一次性导入，避免后续被反复追问。当 Runner 能直接访问到这些文件时（装在你本机的自托管 Runner），Agent 直接读取 `~/.claude/CLAUDE.md`、各仓库的 `CLAUDE.md` / `AGENTS.md`、`.cursor/rules`、记忆库等；否则（云端沙箱或装在另一台机器上）Agent 给你两段通用提示词，你在本地工具里运行后把结果粘贴 / 上传回来。导入内容按其性质分流：运维 / 服务知识写入知识库文件，个人偏好 / 可复用习惯写入 Agent 记忆，重复或无用的则丢弃。所有导入内容在预览或写入前都会先做**密钥脱敏**，密钥永远不会落盘。 + 可选步骤，需你主动同意，绝不自动触发。如果你已经在 Claude Code / Codex / Cursor / Windsurf / Copilot / Gemini CLI 等本地工具里积累了知识与记忆，可一次性导入，避免后续被反复追问。当 Runner 能直接访问到这些文件时（装在你本机的自托管 Runner），Agent 直接读取 `~/.claude/CLAUDE.md`、各仓库的 `CLAUDE.md` / `AGENTS.md`、`.cursor/rules`、记忆库等；否则（云端沙箱或装在另一台机器上）Agent 给你两段通用提示词，你在本地工具里运行后把结果粘贴 / 上传回来。导入内容按其性质分流：运维 / 服务知识写入知识文件，个人偏好 / 可复用习惯写入 Agent 记忆，重复或无用的则丢弃。所有导入内容在预览或写入前都会先做**密钥脱敏**，密钥永远不会落盘。 Agent 用一段话回述它看到的画面：「我看到 N 个渠道、近 30 天 M 个故障、你似乎在用 [列表]、高频标签包括 [列表]。对吗？还缺什么？」等你确认或纠正，**此时还不写入任何文件**。 @@ -94,7 +94,7 @@ sidebarTitle: 初始化 - 当你表示完成时，Agent 给出一段小结：本次创建/更新了哪些文件、登记了哪些 MCP，并提示「任何时候重跑 `/init` 都能继续」。知识库本身就是这次会话的持久成果。 + 当你表示完成时，Agent 给出一段小结：本次创建/更新了哪些文件、登记了哪些 MCP，并提示「任何时候重跑 `/init` 都能继续」。知识本身就是这次会话的持久成果。 @@ -115,7 +115,7 @@ sidebarTitle: 初始化 每当需要你提供或生成凭证（kubeconfig、云 AK/SK、数据库账号、API token），Agent 都会要求你按**只读 / 最小权限**来配置；在边界可机器校验时，它会先做一次只读边界检查再记录。 - 不是所有信息都值得写进知识库。Agent 只写「缺了它，AI 在故障里会做出更糟决定」的内容——可有可无的细节不会被塞进去，避免知识库变臃肿。 + 不是所有信息都值得写进知识。Agent 只写「缺了它，AI 在故障里会做出更糟决定」的内容——可有可无的细节不会被塞进去，避免知识变臃肿。 @@ -123,9 +123,9 @@ sidebarTitle: 初始化 --- -`/init` 的成果是一份可被后续每次会话自动加载的[知识库](/zh/ai-sre/knowledge)： +`/init` 的成果是一份可被后续每次会话自动加载的[知识](/zh/ai-sre/knowledge)： -- **`DUTY.md`**——知识库的目录入口，只放一句话导引和一份 `@文件名` 链接清单，指向各主题文件； +- **`DUTY.md`**——知识的目录入口，只放一句话导引和一份 `@文件名` 链接清单，指向各主题文件； - **主题文件**——`services.md`、`topology.md`、`observability.md`、`runbooks/<主题>.md`、`common-failures.md`、`clusters.md` 等，实质内容都在这里； - **MCP 登记**（可选）——若访谈中接入了外部工具，会在 `tools.md` 记录并完成 MCP 服务器注册。 @@ -141,15 +141,15 @@ sidebarTitle: 初始化 - 从零把知识库搭起来：服务、拓扑、runbook、集群访问一次成体系地沉淀，让 Agent 一上来就懂你的系统。 + 从零把知识搭起来：服务、拓扑、runbook、集群访问一次成体系地沉淀，让 Agent 一上来就懂你的系统。 - 回看近 30 天会话，找出反复粘贴的上下文、缺失的 runbook、用错的数据源，告诉你**下一步该往知识库里补什么**。 + 回看近 30 天会话，找出反复粘贴的上下文、缺失的 runbook、用错的数据源，告诉你**下一步该往知识里补什么**。 -推荐的节奏：先用 `/init` 打好底子，跑几次真实排障后再用 `/insight` 复盘，把它指出的摩擦补回知识库——必要时重跑 `/init` 做系统性整理。知识库越完善，AI SRE 越精准好用。 +推荐的节奏：先用 `/init` 打好底子，跑几次真实排障后再用 `/insight` 复盘，把它指出的摩擦补回知识——必要时重跑 `/init` 做系统性整理。知识越完善，AI SRE 越精准好用。 ## 相关页面 @@ -161,7 +161,7 @@ sidebarTitle: 初始化 `/init` 的产出落在这里——了解 DUTY.md 结构、文件约束，以及如何手动编辑与维护。 - 用 `/insight` 复盘会话、发现运维摩擦，指导你持续补全知识库。 + 用 `/insight` 复盘会话、发现运维摩擦，指导你持续补全知识。 `/init` 可在访谈中帮你接入的外部工具，了解 MCP 的连接与管理。 diff --git a/zh/ai-sre/insight.mdx b/zh/ai-sre/insight.mdx index 9b31b3c30..533820b00 100644 --- a/zh/ai-sre/insight.mdx +++ b/zh/ai-sre/insight.mdx @@ -1,7 +1,7 @@ --- title: 使用洞察（/insight） description: 在 AI SRE 会话中输入 /insight，自动分析您近 30 天的会话，产出一份只读的教练式月度复盘——先讲做得好的地方，再讲值得消除的摩擦，最后给出更高杠杆的下一步建议。 -keywords: ["AI SRE", "insight", "运营洞察", "摩擦报告", "知识库", "复盘"] +keywords: ["AI SRE", "insight", "运营洞察", "摩擦报告", "知识", "复盘"] sidebarTitle: 使用洞察 --- @@ -18,7 +18,7 @@ sidebarTitle: 使用洞察 这是一份**教练视角的月度复盘**，而不是一张问题清单：它先讲**做得好的地方**——这一个月 AI SRE 在哪些地方真正帮上了忙；再讲**值得现在就消除的摩擦**——那些一再消耗您时间的模式，比如同一个数据库连接串您在多个会话里反复粘贴、Agent 缺少某个本该已知的排查手册、或它反复查错了数据源；最后给出 **2–3 条更高杠杆的下一步建议**——在「怎么用 AI SRE」这件事上可以尝试的方向。 -`/insight` 是**只读**的。它只做分析和呈现，**不会**自动改动任何知识库、Skill 或 MCP 配置。每一条建议都是可复制的文本，是否采纳由您决定。详见 [如何处理建议](#如何处理建议)。 +`/insight` 是**只读**的。它只做分析和呈现，**不会**自动改动任何知识、Skill 或 MCP 配置。每一条建议都是可复制的文本，是否采纳由您决定。详见 [如何处理建议](#如何处理建议)。 `/insight` 是 AI SRE 内置的一项 Skill：它会自动导出你的历史会话、统计量化指标、逐段分析会话内容，最后汇总渲染成一份报告。整个过程对您透明，您只需要输入 `/insight`。 @@ -134,10 +134,10 @@ sidebarTitle: 使用洞察 | `missing_runbook`（缺少运行手册） | Agent 不得不临时拼凑一套多步排查，而您显然期望它本就该会 | 新增运行手册：`knowledge/<范围>/runbooks/<主题>.md` | | `wrong_data_source`（数据源用错） | Agent 查了错误的数据源 / 集群 / 命名空间，被您纠正 | 在 `observability.md` / `clusters.md` 里固定正确的数据源 | | `hallucinated_entity`（臆测实体） | Agent 引用了一个并不存在的服务 / 主机 / 指标 / 变更，被您否定 | 把真实的实体清单补进 `services.md` | -| `stale_knowledge`（知识过期） | 来自知识库 / DUTY.md 的某个事实已经过时或错误，被您当场纠正 | 更新那个过期的文件 | +| `stale_knowledge`（知识过期） | 来自知识 / DUTY.md 的某个事实已经过时或错误，被您当场纠正 | 更新那个过期的文件 | -`repeated_context` 之所以排在首位，是因为它**最持久**——同一个事实跨多个会话被反复提供，意味着把它沉淀进知识库一次，未来每个会话都能直接受益。当它的证据数与其他摩擦持平时，也优先排在前面。 +`repeated_context` 之所以排在首位，是因为它**最持久**——同一个事实跨多个会话被反复提供，意味着把它沉淀进知识一次，未来每个会话都能直接受益。当它的证据数与其他摩擦持平时，也优先排在前面。 ## 如何处理建议 @@ -154,12 +154,12 @@ sidebarTitle: 使用洞察 每张卡片的「可复制的建议」里是一段可直接粘贴的文本，其第一行（`Add this to knowledge/<范围>/…`）就是落点，告诉您它该写到哪个文件——复制时会把目标路径一并带上。 - 根据摩擦类型，到相应的资源里粘贴并保存：重复上下文与臆测实体写进知识库的 `services.md` 或 DUTY.md；缺少运行手册则在知识库里新增一份 runbook；数据源用错就固定到 `observability.md` / `clusters.md`；知识过期则直接更新那个文件。这些都属于 [知识库](/zh/ai-sre/knowledge) 的常规编辑。 + 根据摩擦类型，到相应的资源里粘贴并保存：重复上下文与臆测实体写进知识的 `services.md` 或 DUTY.md；缺少运行手册则在知识里新增一份 runbook；数据源用错就固定到 `observability.md` / `clusters.md`；知识过期则直接更新那个文件。这些都属于 [知识](/zh/ai-sre/knowledge) 的常规编辑。 -`/insight` 永远不会替您执行写入——它不调用任何同步/安装动作，也不改动知识库、Skill 或 MCP。如果您后续想让 AI SRE「把这条 runbook 加进去」，那是一次**独立**的自然语言指令，不属于 `/insight` 的范围。 +`/insight` 永远不会替您执行写入——它不调用任何同步/安装动作，也不改动知识、Skill 或 MCP。如果您后续想让 AI SRE「把这条 runbook 加进去」，那是一次**独立**的自然语言指令，不属于 `/insight` 的范围。 @@ -175,7 +175,7 @@ sidebarTitle: 使用洞察 了解会话的创建、团队绑定与作战室——这些决定了 `/insight` 的分析范围。 - 报告里的建议大多落在知识库的 DUTY.md / `services.md` / runbooks，这里讲如何编辑。 + 报告里的建议大多落在知识的 DUTY.md / `services.md` / runbooks，这里讲如何编辑。 从整体了解 AI SRE 的能力与运行机制。 diff --git a/zh/ai-sre/knowledge.mdx b/zh/ai-sre/knowledge.mdx index 44fa3de9e..cce853cea 100644 --- a/zh/ai-sre/knowledge.mdx +++ b/zh/ai-sre/knowledge.mdx @@ -1,8 +1,8 @@ --- -title: 了解知识库 -description: 知识库由人维护，写这个环境怎么运转。一份 DUTY.md 加上运行手册、服务清单等文件，会话开始时先读使用说明，其余按需打开。 -keywords: ["AI SRE", "知识库", "DUTY.md", "运行手册", "上下文"] -sidebarTitle: 了解知识库 +title: 了解知识 +description: 知识由人维护，写这个环境怎么运转。一份 DUTY.md 加上运行手册、服务清单等文件，会话开始时先读使用说明，其余按需打开。 +keywords: ["AI SRE", "知识", "DUTY.md", "运行手册", "上下文"] +sidebarTitle: 了解知识 --- @@ -13,30 +13,30 @@ sidebarTitle: 了解知识库 --- -知识库是您交给 AI SRE 的运维知识：一份 `DUTY.md` 加上一组运行手册（runbook）、FAQ、服务清单、集群配置等文件。会话开始时，Agent 先读取 `DUTY.md`，再按需打开其它文件，从而把您团队的处置经验、命名约定与系统拓扑带进每一次诊断。 +知识是您交给 AI SRE 的运维资料：一份 `DUTY.md` 加上一组运行手册（runbook）、FAQ、服务清单、集群配置等文件。会话开始时，Agent 先读取 `DUTY.md`，再按需打开其它文件，从而把您团队的处置经验、命名约定与系统拓扑带进每一次诊断。 -控制台入口：**AI SRE → 自定义 → 上下文 → 知识库**。同一分组下的 [记忆](/zh/ai-sre/memory) 是另一页，两者分开管理。 +控制台入口：**AI SRE → 自定义 → 上下文 → 知识**。同一分组下的 [记忆](/zh/ai-sre/memory) 是另一页，两者分开管理。 -整个账户只能有 1 个共享知识库，每个团队最多有 1 个团队知识库： +整个账户只能有 1 份共享知识，每个团队最多有 1 份团队知识： - **共享（即账户级）**知识对账户内所有 Agent 可见。 - **团队级**知识仅在该团队的会话中加载。 -知识库是 AI SRE 资源的一种，遵循统一的两级作用域模型。其他资源（Skill、MCP、Agent、运行环境）的作用域规则与本页一致。 +知识是 AI SRE 资源的一种，遵循统一的两级作用域模型。其他资源（Skill、MCP、Agent、运行环境）的作用域规则与本页一致。 - 知识库内容用于**精炼**Agent 的领域上下文（人设、方法论、系统知识），但不会覆盖系统的安全与行为底线。如果某份知识要求 Agent 跳过安全规则，会被当作越权内容忽略，而非更高优先级的指令。 + 知识内容用于**精炼**Agent 的领域上下文（人设、方法论、系统知识），但不会覆盖系统的安全与行为底线。如果某份知识要求 Agent 跳过安全规则，会被当作越权内容忽略，而非更高优先级的指令。 ## DUTY.md 结构 --- -`DUTY.md` 是整个知识库的**目录入口**，每次会话自动加载。Agent 会全文读取 `DUTY.md`，再通过 `@文件名` 引用按需拉取其它文件。系统不会在 `DUTY.md` 之外另附文件列表：知识文件放在会话工作区的 `knowledge/` 目录下，Agent 像浏览代码仓库一样用 ls / glob / grep 查找，`DUTY.md` 没有引用到的文件也能被找到。 +`DUTY.md` 是整份知识的**目录入口**，每次会话自动加载。Agent 会全文读取 `DUTY.md`，再通过 `@文件名` 引用按需拉取其它文件。系统不会在 `DUTY.md` 之外另附文件列表：知识文件放在会话工作区的 `knowledge/` 目录下，Agent 像浏览代码仓库一样用 ls / glob / grep 查找，`DUTY.md` 没有引用到的文件也能被找到。 如果某个作用域还没有 `DUTY.md`，该作用域不会被静默跳过：系统会告诉 Agent 这个范围没有使用说明、文件在哪个目录下，并要求它在开展实质工作前先列出目录、阅读相关文件。 -引用采用 `@<路径>` 风格，路径指向同一个知识库内的另一份文件，支持子目录（如 `@runbooks/api-5xx.md`）： +引用采用 `@<路径>` 风格，路径指向同一份知识内的另一份文件，支持子目录（如 `@runbooks/api-5xx.md`）： ```markdown # 值班知识总览 (DUTY.md) @@ -64,7 +64,7 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 | --- | --- | --- | | 文件内容 | 纯文本（UTF-8） | 按**内容**校验而非扩展名：文件不含 NUL 字节且能按 UTF-8 解码即可保存。因此 `.md` `.yaml` `.json` `.txt` `.sh` 之外的 `.py` `.sql`，乃至没有扩展名的 `Dockerfile` 都可以上传；反之，扩展名是 `.txt` 但内容为二进制的文件会被拒绝 | | 单文件上限 | 1 MiB | 超出无法保存 | -| 单个知识库上限 | 5 MiB | 控制台用量条按此额度显示 | +| 单份知识上限 | 5 MiB | 控制台用量条按此额度显示 | | 文件数量上限 | 100 | 达到上限后无法新增文件 | | 子目录 | 允许 | 路径可含 `/`，如 `runbooks/api-5xx.md`；不允许以 `.` 开头的路径段 | | 点文件 | 不允许 | 文件名不能以 `.` 开头 | @@ -73,33 +73,33 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 --- -进入 **AI SRE → 自定义 → 上下文 → 知识库**。列表每行是一个知识库，按范围（「共享」或团队名）标识，列出文件数、`DUTY.md` 状态和最近修改时间。`DUTY.md` 状态有三种：**未创建**、**已同步**，以及 **需梳理 · 之后改了 N 次**（`DUTY.md` 写好之后，库里其它文件又改过）。点击 **创建** 可以为共享范围或您所属的团队新建知识库；账户和所有可用团队都已有知识库时，按钮置灰。 +进入 **AI SRE → 自定义 → 上下文 → 知识**。列表每行是一份知识，按范围（「共享」或团队名）标识，列出文件数、`DUTY.md` 状态和最近修改时间。`DUTY.md` 状态有三种：**未创建**、**已同步**，以及 **需梳理 · 之后改了 N 次**（`DUTY.md` 写好之后，这份知识里其它文件又改过）。点击 **创建** 可以为共享范围或您所属的团队新建知识；账户和所有可用团队都已有知识时，按钮置灰。 -还没有任何知识库时，页面改为引导：**初始化 AI-SRE** 会打开新对话并运行 [`/init`](/zh/ai-sre/init)，**上传已有文档** 会打开新对话并弹出附件选择。 +还没有任何知识时，页面改为引导：**初始化 AI-SRE** 会打开新对话并运行 [`/init`](/zh/ai-sre/init)，**上传已有文档** 会打开新对话并弹出附件选择。 -点击某一行进入这个知识库： +点击某一行进入这份知识： - **左侧是文件树。** `DUTY.md` 固定在最上方，带 **自动加载** 标记；其余文件列在「其他文件 · 按需读取」下。还没有 `DUTY.md` 时，这里显示「未创建」和 **让 AI 生成** 按钮。文件树上方显示用量（已用 / 5 MB 和文件数），以及 **新建文件**、**上传** 两个入口。 - **右侧是文件正文。** 点 **编辑** 可以直接改当前文件，在 **预览** 与 **源码** 之间切换，点 **保存** 写入。 - **上传**：任意 UTF-8 文本文件直接入库，支持选择整个文件夹上传，同名文件会先询问是否覆盖。PDF、Word、HTML 等文档不能直接入库，可以点 **转到对话分析**，由 AI 读取后提炼成 Markdown 文件，经您确认再保存。 -文件仍要满足上面的限制：纯文本、单文件不超过 1 MiB、一个知识库不超过 5 MiB 和 100 个文件。`@引用` 指向库里没有的文件时，仍然可以保存。 +文件仍要满足上面的限制：纯文本、单文件不超过 1 MiB、一份知识不超过 5 MiB 和 100 个文件。`@引用` 指向这份知识里没有的文件时，仍然可以保存。 ### 让 AI 修改 -正文下方有一个输入框（提示语为「想让 AI 怎么改这个知识库？例如：补一份 OOM 排查手册」）。写下要改什么并发送，控制台会打开一个新对话，输入框里已带上这个知识库的引用和您的要求；团队知识库会把对话切到对应团队。发出后，AI 先用文字说明要改哪些文件、怎么改，您同意后才保存。页面本身不提供改动预览或逐条审阅。 +正文下方有一个输入框（提示语为「想让 AI 怎么改这份知识？例如：补一份 OOM 排查手册」）。写下要改什么并发送，控制台会打开一个新对话，输入框里已带上这份知识的引用和您的要求；团队知识会把对话切到对应团队。发出后，AI 先用文字说明要改哪些文件、怎么改，您同意后才保存。页面本身不提供改动预览或逐条审阅。 **让 AI 生成** 与下面的 **让 AI 梳理** 也是同样的流程：转到新对话，请求已经写好。 ### DUTY.md 需要梳理时 -`DUTY.md` 写好之后，如果库里其它文件又被改过，文件树上方会出现提示：「DUTY.md 写好之后，知识库又改了 N 次，可能需要重新梳理」。有编辑权限时，提示下方有两个操作： +`DUTY.md` 写好之后，如果这份知识里其它文件又被改过，文件树上方会出现提示：「DUTY.md 写好之后，知识又改了 N 次，可能需要重新梳理」。有编辑权限时，提示下方有两个操作： - **让 AI 梳理**：转到新对话，让 AI 对照现有文件更新 `DUTY.md` 的索引，改动先经您确认。 - **已核对，不用改**：确认 `DUTY.md` 仍然准确。提示随即消失，直到下一次文件改动。 - 助手也能在对话里维护当前会话所属范围的知识库，例如「补一篇 runbook」「更新 services.md」。它读取、修改，再经您确认后保存。 + 助手也能在对话里维护当前会话所属范围的知识，例如「补一篇 runbook」「更新 services.md」。它读取、修改，再经您确认后保存。 ## Agent 如何使用知识 @@ -125,14 +125,14 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 - 若知识库未能成功加载进当前会话，消息列表上方会出现一条警告横幅：「知识库加载失败 — 本次会话中 AI-SRE 可能无法访问 DUTY.md 与 runbook。」，并附带 **重试** 按钮，点击后会重新尝试加载。重试成功前，Agent 在该会话中可能无法读取 DUTY.md 与运行手册。 + 若知识未能成功加载进当前会话，消息列表上方会出现一条警告横幅：「知识加载失败 — 本次会话中 AI-SRE 可能无法访问 DUTY.md 与 runbook。」，并附带 **重试** 按钮，点击后会重新尝试加载。重试成功前，Agent 在该会话中可能无法读取 DUTY.md 与运行手册。 ## 作用域与可见性 --- -每个知识库都有一个作用域：共享范围（即账户级，账户内全局可见）或团队范围。 +每份知识都有一个作用域：共享范围（即账户级，账户内全局可见）或团队范围。 | 维度 | 共享 | 团队 | | --- | --- | --- | @@ -141,9 +141,9 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 | 会话中加载 | 所有会话 | 仅绑定该团队的会话 | | 运行时可读 | 所有会话 | 绑定该团队的会话；以及创建者属于该团队的个人会话（读取即挂载） | -**编辑权限**：团队知识库仅该团队的成员可以操作，组织管理员也需要先加入该团队；共享知识库仅账户 Owner 或管理员可以操作；不存在「创建者额外保留权限」的规则。控制台会把你无权编辑的行置灰，并禁用其开关与操作按钮。 +**编辑权限**：团队知识仅该团队的成员可以操作，组织管理员也需要先加入该团队；共享知识仅账户 Owner 或管理员可以操作；不存在「创建者额外保留权限」的规则。控制台会把你无权编辑的行置灰，并禁用其开关与操作按钮。 -**创建与改归属**：创建新的团队知识库时，您必须是目标团队成员；共享范围创建仅限账户 Owner 或管理员。编辑已有知识库时，账户 Owner 或管理员可以把它移动到任意团队，用于恢复空团队或离职成员留下的资源；普通成员只能移动到自己所属的团队。把已有知识库提升为共享范围（**设为共享**）与共享范围创建同门槛：仅限账户 Owner 或管理员操作，普通成员即使属于该知识库所在团队也不能自助提升。 +**创建与改归属**：创建新的团队知识时，您必须是目标团队成员；共享范围创建仅限账户 Owner 或管理员。编辑已有知识时，账户 Owner 或管理员可以把它移动到任意团队，用于恢复空团队或离职成员留下的资源；普通成员只能移动到自己所属的团队。把已有知识提升为共享范围（**设为共享**）与共享范围创建同门槛：仅限账户 Owner 或管理员操作，普通成员即使属于这份知识所在团队也不能自助提升。 **运行时可见性**：会话开始时，只加载**共享范围**资源加上**当前会话绑定团队**的资源。绑定来源是显式指定的团队，或作战室（war room）故障对应的团队。会话进行中能否再挂载其它团队的知识，看会话类型： @@ -171,10 +171,10 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 新增或重命名文件后，同步更新 `DUTY.md` 与相关文件里的 `@引用`。保存时的「引用未解析」警告与删除时的「仍被引用」提示，能帮您及时发现断链。 - 共享知识库放跨团队通用的约定（命名规范、通用排障方法、平台访问方式）；团队知识库放该团队专属的服务清单、值班手册与上下游。绑定团队的会话会同时拿到两者。 + 共享知识放跨团队通用的约定（命名规范、通用排障方法、平台访问方式）；团队知识放该团队专属的服务清单、值班手册与上下游。绑定团队的会话会同时拿到两者。 - 排障过程中沉淀出的新处置经验，可以直接让 Agent「补一篇 runbook」或「记录这个故障模式」，它会对当前作用域读取→编辑→保存，把经验回写进知识库，形成持续积累的闭环。 + 排障过程中沉淀出的新处置经验，可以直接让 Agent「补一篇 runbook」或「记录这个故障模式」，它会对当前作用域读取→编辑→保存，把经验回写进知识，形成持续积累的闭环。 @@ -184,13 +184,13 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 - 把可复用的诊断流程封装为 Skill，与知识库共享同一套作用域。 + 把可复用的诊断流程封装为 Skill，与知识共享同一套作用域。 通过 MCP 接入外部系统，让 Agent 调用您的工具与数据。 - AI 在对话里记下的偏好、做法、事实和教训，与知识库分开管理。 + AI 在对话里记下的偏好、做法、事实和教训，与知识分开管理。 了解会话如何绑定团队，以及知识在会话中如何被读取与挂载。 diff --git a/zh/ai-sre/mcp.mdx b/zh/ai-sre/mcp.mdx index 92c0a4b28..0979b00bd 100644 --- a/zh/ai-sre/mcp.mdx +++ b/zh/ai-sre/mcp.mdx @@ -208,7 +208,7 @@ Agent 读取 Flashduty 故障、告警等数据的能力是**内置**的：**Fla --- -MCP 与其他资源（Skill、知识库、Agent、运行环境）共用同一套**两级作用域**模型，分为共享范围与团队范围： +MCP 与其他资源（Skill、知识、Agent、运行环境）共用同一套**两级作用域**模型，分为共享范围与团队范围： | 作用域 | 可见性 | | --- | --- | diff --git a/zh/ai-sre/memory.mdx b/zh/ai-sre/memory.mdx index d65430e6b..ca65324a1 100644 --- a/zh/ai-sre/memory.mdx +++ b/zh/ai-sre/memory.mdx @@ -15,7 +15,7 @@ sidebarTitle: 了解记忆 AI SRE 每次新会话都从当前范围里已有的记忆文件读起。如果每次都要重新说明您的习惯、某类故障先看哪里、上次为什么放弃了某个做法，排障就得从头介绍背景。记忆把这些从对话里留下来，写成一份份 Markdown 文件，后面的会话继续用。 -记忆和[知识库](/zh/ai-sre/knowledge)是两回事。知识库由人维护，写的是环境怎么运转。记忆由系统整理，写的是从对话里留下来的偏好、做法、事实和教训。两者同属控制台的 [上下文](/zh/ai-sre/context) 分组，但各有一页：**AI SRE → 自定义 → 上下文 → 记忆**。 +记忆和[知识](/zh/ai-sre/knowledge)是两回事。知识由人维护，写的是环境怎么运转。记忆由系统整理，写的是从对话里留下来的偏好、做法、事实和教训。两者同属控制台的 [上下文](/zh/ai-sre/context) 分组，但各有一页：**AI SRE → 自定义 → 上下文 → 记忆**。 ## 记忆类型 @@ -89,9 +89,9 @@ AI SRE 每次新会话都从当前范围里已有的记忆文件读起。如果 - 记忆和知识库怎么分，以及个人、团队、共享范围各自有什么。 + 记忆和知识怎么分，以及个人、团队、共享范围各自有什么。 - + 使用说明和运行手册由人维护，和系统整理的记忆不是同一类资料。 diff --git a/zh/ai-sre/overview.mdx b/zh/ai-sre/overview.mdx index aae8dce69..960c56ada 100644 --- a/zh/ai-sre/overview.mdx +++ b/zh/ai-sre/overview.mdx @@ -1,7 +1,7 @@ --- title: AI SRE 产品概述 description: Flashduty 推出的自治 SRE Agent 平台，通过对话让 AI 自主排障、调查故障、沉淀与复用运维知识，并与 Flashduty 故障响应体系及 IM 协作深度联动 -keywords: ["AI SRE", "Agent", "故障排查", "对话式排障", "IM 协作", "作战室", "MCP", "知识库"] +keywords: ["AI SRE", "Agent", "故障排查", "对话式排障", "IM 协作", "作战室", "MCP", "知识"] sidebarTitle: 概述 --- @@ -124,7 +124,7 @@ AI SRE 围绕"对话排障 + 知识沉淀 + 自主执行"构建了一套完整 可被 Agent 调用的 Skill 包，封装可复用的排障流程。范围可设为共享（即账户级）或团队，启用后在会话中按需加载。 - 以 DUTY.md 为入口、按 @-引用索引的知识库，承载服务清单、runbook、值班路径等长期上下文，按账户/团队分层加载。 + 以 DUTY.md 为入口、按 @-引用索引的知识，承载服务清单、runbook、值班路径等长期上下文，按账户/团队分层加载。 通过 Model Context Protocol 接入外部工具与数据源。MCP 服务器不预连接，Agent 在调用时按需建连、执行、断连。 @@ -163,7 +163,7 @@ AI SRE 围绕"对话排障 + 知识沉淀 + 自主执行"构建了一套完整 | 分组 | 页面 | 作用 | |------|------|------| -| 上下文 | 知识库、记忆 | [知识库](/zh/ai-sre/knowledge)：整个账户 1 个共享知识库，每个团队最多 1 个团队知识库。[记忆](/zh/ai-sre/memory)：AI 在对话里记下的偏好、做法、事实和教训，分个人和团队。 | +| 上下文 | 知识、记忆 | [知识](/zh/ai-sre/knowledge)：整个账户 1 份共享知识，每个团队最多 1 份团队知识。[记忆](/zh/ai-sre/memory)：AI 在对话里记下的偏好、做法、事实和教训，分个人和团队。 | | 插件 | 概览、Apps、Skill、MCP、Agents | **概览** 是插件目录（MCP 模板、Skill 模板、内置 App）；[Apps](/zh/ai-sre/apps)（已授权的外部应用，如 GitHub）、[Skill](/zh/ai-sre/skills)、[MCP](/zh/ai-sre/mcp)（外部工具）、[Agents](/zh/ai-sre/agents)（A2A 远端 Agent）。 | | 环境 | 自托管、云端 | [自托管](/zh/ai-sre/environments)：部署在您机器上的常驻 Runner；**云端**：Flashduty 托管的云端沙箱模板。无可用自托管环境时，会话回退到云端沙箱。 | diff --git a/zh/ai-sre/quickstart.mdx b/zh/ai-sre/quickstart.mdx index 93a0fa2e4..aafa25fb5 100644 --- a/zh/ai-sre/quickstart.mdx +++ b/zh/ai-sre/quickstart.mdx @@ -1,7 +1,7 @@ --- title: 15 分钟完成第一次 AI SRE 排障 description: 从一个真实故障开始，完成第一次有上下文、有证据、可继续追问的 AI SRE 调查；随后按需让新故障自动获得第一轮分析、建立团队知识、部署 BYOC Runner 接入真实数据源。 -keywords: ["AI SRE", "快速开始", "Quickstart", "故障调查", "故障自动分析", "/init", "知识库", "MCP", "BYOC Runner"] +keywords: ["AI SRE", "快速开始", "Quickstart", "故障调查", "故障自动分析", "/init", "知识", "MCP", "BYOC Runner"] sidebarTitle: 快速开始 --- @@ -19,7 +19,7 @@ sidebarTitle: 快速开始 |---|---| | 会话 | 你和 Agent 的一次协作，控制台或 IM 里都能开 → [控制台](/zh/ai-sre/sessions) | | @ 引用 | 把故障现场带进对话的方式，输入 `@` 搜索并插入故障 → [控制台](/zh/ai-sre/sessions) | -| 知识库 | 你维护的、关于你系统的长期资料（DUTY.md、运行手册、服务清单），越完整定位越准 → [了解知识库](/zh/ai-sre/knowledge) | +| 知识 | 你维护的、关于你系统的长期资料（DUTY.md、运行手册、服务清单），越完整定位越准 → [了解知识](/zh/ai-sre/knowledge) | | 运行环境 | Agent 动手的地方——云端 Sandbox 或你内网的 BYOC Runner → [运行环境](/zh/ai-sre/environments) | ## 三个入口（从哪儿开始） @@ -90,9 +90,9 @@ AI SRE 没有唯一入口，从你现在所在的场景开始就好： 它与作战室自动诊断是两条独立链路：这条对每一条匹配的新故障生效，结果写回故障评论；作战室自动诊断在你为故障开启 IM 作战室时运行，结果回贴到作战室群里（见 [IM 平台](/zh/ai-sre/im)）。 -### 建一份团队知识库 +### 建一份团队知识 -Agent 每次排障都从零猜「这是什么服务」「谁负责」「以前是怎么处理的」，效率就上不去。在会话里输入 `/init`，Agent 会用访谈的方式带你梳理服务清单、runbook、值班路径等知识，逐条确认后写入知识库，后续会话自动加载。完整访谈流程见[初始化（/init）](/zh/ai-sre/init)，知识库结构与最佳实践见[管理知识](/zh/ai-sre/knowledge)。 +Agent 每次排障都从零猜「这是什么服务」「谁负责」「以前是怎么处理的」，效率就上不去。在会话里输入 `/init`，Agent 会用访谈的方式带你梳理服务清单、runbook、值班路径等知识，逐条确认后写入知识，后续会话自动加载。完整访谈流程见[初始化（/init）](/zh/ai-sre/init)，知识结构与最佳实践见[管理知识](/zh/ai-sre/knowledge)。 ### 接入真实数据源 diff --git a/zh/ai-sre/sessions.mdx b/zh/ai-sre/sessions.mdx index e651e57de..16866c116 100644 --- a/zh/ai-sre/sessions.mdx +++ b/zh/ai-sre/sessions.mdx @@ -143,8 +143,8 @@ Subagent / A2A 子会话本身也不能单独开启分享——分享只能在** **交接只带一个引用时会预填提问**：当本次交接合并后恰好只剩一个引用、且该引用里带了入口维护的默认提问时，输入框会预填这句提问，`[[ref]]` 占位处则落成引用胶囊。例如在故障列表里对多条故障批量点击 **AI 分析**，输入框预填的就是「请批量分析这些故障 〈引用胶囊〉：先判断它们之间的关联性（同一根因、连锁反应或彼此独立）并分组；再按组给出可能根因与影响面；最后给出整体处置建议与优先级。需要单个故障的细节时用工具按需拉取，不必逐个展开全部故障。请区分已确认事实、合理推断和待确认项；证据不足时明确说明，不要声称执行了未执行的操作。」，胶囊标题为「故障清单（N）」；带多个引用的交接则不预填提问，输入框保持原样。一条消息可携带多个引用。除了从相关页面自动携带引用外，也可以在任意会话的输入框里直接输入 `@` 触发故障搜索下拉（支持关键词模糊匹配与近期故障列表），选中后插入与自动携带相同的引用胶囊——这是一个随时可用的独立引用入口。输入邮箱地址不会误触发该下拉：当 `@` 紧跟在邮箱地址字符（字母、数字或 `._%+-`）之后时，选择器不会弹出；而空格之后、或与中文相邻的 `@` 仍正常触发。 - - 会话启动时会按绑定团队自动加载对应的知识库与 Skill；详见下文 知识库 与 Skill。 + + 会话启动时会按绑定团队自动加载对应的知识与 Skill；详见下文 知识 与 Skill。 @@ -187,7 +187,7 @@ Subagent / A2A 子会话本身也不能单独开启分享——分享只能在** -当上一个沙箱因空闲被回收时，卡片会给出警示：**原沙箱因闲置 N 分钟被回收 — 已保存的文件被重置**。这意味着此前写入沙箱文件系统的内容已不复存在。请将需要长期留存的产出**保存为 Artifact 或沉淀到知识库**，而不要依赖沙箱内的临时文件。 +当上一个沙箱因空闲被回收时，卡片会给出警示：**原沙箱因闲置 N 分钟被回收 — 已保存的文件被重置**。这意味着此前写入沙箱文件系统的内容已不复存在。请将需要长期留存的产出**保存为 Artifact 或沉淀到知识**，而不要依赖沙箱内的临时文件。 @@ -469,14 +469,14 @@ Fork 会话会清理只属于运行中的临时状态，例如当前回合缓存 --- -新建会话时可以为会话 **绑定团队**。绑定后，会话在启动时会自动加载该团队的知识库、Skill 与 MCP，让 Agent 一开始就具备这个团队的领域上下文与能力。未绑定团队时，会话以账户范围运行。 +新建会话时可以为会话 **绑定团队**。绑定后，会话在启动时会自动加载该团队的知识、Skill 与 MCP，让 Agent 一开始就具备这个团队的领域上下文与能力。未绑定团队时，会话以账户范围运行。 在新建会话的输入区通过团队选择器挑选要绑定的团队；您上次的选择会被记住，省去每次重复选择。 - 会话启动即加载「账户范围 + 绑定团队」的知识库 / Skill / MCP 元数据，Agent 随即可用。 + 会话启动即加载「账户范围 + 绑定团队」的知识 / Skill / MCP 元数据，Agent 随即可用。 未绑定团队的个人会话里，Agent 可以按需读取会话创建者所属团队的知识，将该团队的知识与能力作为持久上下文挂载进当前会话——一次挂载在本会话内持续有效。绑定了团队的会话只用共享范围和这个团队的知识，不能挂载其它团队的。 diff --git a/zh/ai-sre/skills.mdx b/zh/ai-sre/skills.mdx index 09995d01b..db5943e25 100644 --- a/zh/ai-sre/skills.mdx +++ b/zh/ai-sre/skills.mdx @@ -215,7 +215,7 @@ Skill 包**过大无法预览**时，检视面板会提示体积并建议改用 --- -Skill 与其他资源（知识库、MCP、Agent、运行环境）共用同一套**两级作用域**模型，分为账户级与团队级： +Skill 与其他资源（知识、MCP、Agent、运行环境）共用同一套**两级作用域**模型，分为账户级与团队级： | 作用域 | 可见性 | | --- | --- | @@ -238,7 +238,7 @@ Skill 与其他资源（知识库、MCP、Agent、运行环境）共用同一套 - 用 DUTY.md 与知识库为 Agent 提供团队上下文与排障经验。 + 用 DUTY.md 与知识为 Agent 提供团队上下文与排障经验。 接入外部工具，让 Skill 在 SKILL.md 中以 `mcp:服务名/工具名` 调用它们。 diff --git a/zh/developer/cli.mdx b/zh/developer/cli.mdx index a6c2c1059..f73b84a44 100644 --- a/zh/developer/cli.mdx +++ b/zh/developer/cli.mdx @@ -702,17 +702,17 @@ flashduty alert --help # 查看告警相关的生成命令 生成命令的时间窗口参数（`--start-time` / `--end-time`）与精选命令一样支持人性化的时间格式：相对时长（`7d`、`24h`，表示从当前往前推）、`+7d`（从当前往后推，即未来时间）、`now`、日期或日期时间（如 `2026-05-01`、`2026-05-01 10:00:00`）、Unix 秒级时间戳。此外，`--since` 和 `--until` 分别是 `--start-time` 和 `--end-time` 的别名，可互换使用；若两种写法同时传入且取值不同，CLI 会报冲突错误。 -#### knowledge — AI SRE 知识库 +#### knowledge — AI SRE 知识 -`safari knowledge-*` 命令族管理 AI SRE 的**知识库**——账户或团队作用域下的版本化文件树（`DUTY.md` 加运行手册、FAQ、服务清单等），会话开始时会被加载进每个 AI SRE 沙箱。知识库的完整功能模型（`DUTY.md` 结构、`@引用`、账户/团队作用域、文件约束）参见 [管理知识](/zh/ai-sre/knowledge)。 +`safari knowledge-*` 命令族管理 AI SRE 的**知识**——账户或团队作用域下的版本化文件树（`DUTY.md` 加运行手册、FAQ、服务清单等），会话开始时会被加载进每个 AI SRE 沙箱。知识的完整功能模型（`DUTY.md` 结构、`@引用`、账户/团队作用域、文件约束）参见 [管理知识](/zh/ai-sre/knowledge)。 ```bash -flashduty safari knowledge-get # 获取当前账户知识库（含文件列表） -flashduty safari knowledge-pack-list [flags] # 列出知识库 -flashduty safari knowledge-pack-ensure --scope [--scope-id ] # 确保知识库存在（不存在则创建） -flashduty safari knowledge-pack-update [--scope ...] # 变更知识库作用域 -flashduty safari knowledge-pack-delete # 删除知识库（不可逆） -flashduty safari knowledge-file-list [--pack-id ] # 列出知识库内的文件 +flashduty safari knowledge-get # 获取当前账户知识（含文件列表） +flashduty safari knowledge-pack-list [flags] # 列出知识 +flashduty safari knowledge-pack-ensure --scope [--scope-id ] # 确保知识存在（不存在则创建） +flashduty safari knowledge-pack-update [--scope ...] # 变更知识作用域 +flashduty safari knowledge-pack-delete # 删除知识（不可逆） +flashduty safari knowledge-file-list [--pack-id ] # 列出知识内的文件 flashduty safari knowledge-file-get --rel-path # 读取单个知识文件（内容为 Base64 编码） flashduty safari knowledge-file-put --rel-path --content-b64 # 上传或覆盖知识文件 flashduty safari knowledge-file-delete --rel-path [--force] # 删除知识文件 @@ -722,9 +722,9 @@ flashduty safari knowledge-file-delete --rel-path [--force] # 删除知 | 参数 | 说明 | |------|------| -| `--pack-id` | 知识库 ID；省略时默认使用调用者账户作用域的知识库 | -| `--rel-path` | 文件相对知识库根目录的路径（必填，支持子目录，如 `runbooks/api-5xx.md`） | -| `--scope` | 知识库作用域：`account` 或 `team`（`knowledge-pack-ensure` 必填） | +| `--pack-id` | 知识 ID；省略时默认使用调用者账户作用域的知识 | +| `--rel-path` | 文件相对知识根目录的路径（必填，支持子目录，如 `runbooks/api-5xx.md`） | +| `--scope` | 知识作用域：`account` 或 `team`（`knowledge-pack-ensure` 必填） | | `--scope-id` | 团队 ID；`team` 作用域必填，`account` 作用域忽略 | | `--force` | 删除文件时跳过「仍被其他文件引用」检查，引用方改为以警告形式返回 | diff --git a/zh/developer/go-sdk.mdx b/zh/developer/go-sdk.mdx index 6b8d4def1..2b45a0400 100644 --- a/zh/developer/go-sdk.mdx +++ b/zh/developer/go-sdk.mdx @@ -164,7 +164,7 @@ client, err := flashduty.NewClient("YOUR_APP_KEY", | `client.A2aAgents` | A2A Agents | | `client.Artifacts` | AI SRE 产物 | | `client.Automations` | AI SRE 自动化 | -| `client.Knowledge` | AI SRE 知识库（知识库本身与其中的知识文件） | +| `client.Knowledge` | AI SRE 知识（每份知识本身与其中的知识文件） | | `client.McpServers` | MCP Servers | | `client.Sessions` | AI SRE 会话 | | `client.Skills` | Skills | @@ -180,7 +180,7 @@ client, err := flashduty.NewClient("YOUR_APP_KEY", `client.StatusPages.DraftCreate`（`POST /status-page/draft/create`）把一次状态页事件草稿存下来，供人工在控制台审阅后发布，不会直接对外可见：`draft` 为任意 JSON，按原文存储、序列化后不超过 64 KB，其中 `page_id`、`type`（`incident` 或 `maintenance`）、`name`、`message` 会被校验；`change_id`（> 0 时表示追加到已有事件的一次更新）、`status`、`affected_components` 可选，新建 maintenance 时可用 `start_time` / `end_time`（Unix 秒）指定窗口。请求上的 `source` 是草稿来源标记（≤ 64 字符，如 `ai_sre:sess_xxx`）；响应返回 `draft_id`（匹配 `draft_[A-Za-z0-9]{22}`），控制台的审阅链接即携带它。 -`client.Knowledge` 对应 `/safari/knowledge/*` 的 9 个 API 操作：知识库侧为 `PackReadGet`（获取账户知识库）、`PackReadList`（列出知识库）、`PackWriteEnsure`（确保知识库存在）、`PackWriteUpdate`（变更知识库作用域）、`PackWriteDelete`（删除知识库）；知识文件侧为 `FileReadGet`、`FileReadList`、`FileWritePut`（上传/覆盖）、`FileWriteDelete`。相关导出类型包括 `KnowledgePackItem`、`KnowledgeFileItem`、`KnowledgeWarning` 以及各 `Knowledge*Request` / `Knowledge*Response`。 +`client.Knowledge` 对应 `/safari/knowledge/*` 的 9 个 API 操作：知识侧为 `PackReadGet`（获取账户知识）、`PackReadList`（列出知识）、`PackWriteEnsure`（确保知识存在）、`PackWriteUpdate`（变更知识作用域）、`PackWriteDelete`（删除知识）；知识文件侧为 `FileReadGet`、`FileReadList`、`FileWritePut`（上传/覆盖）、`FileWriteDelete`。相关导出类型包括 `KnowledgePackItem`、`KnowledgeFileItem`、`KnowledgeWarning` 以及各 `Knowledge*Request` / `Knowledge*Response`。 `client.Artifacts`（AI SRE 产物）对应 `/safari/artifact/*` 的 11 个 API 操作：画廊读取侧 `ReadGet`（按 ID 获取单个已发布产物）、`ReadList`（分页列出调用方可见的产物，支持标题子串搜索、`scope`（`all` / `personal` / `team`）与 `team_ids` 过滤）、`ReadGetFileState`（批量探测会话展示文件（`pf_` 前缀）是否已有上线产物，单次至多 50 个 ID）；文件侧 `ReadSign`（为展示文件签发短期有效的下载/预览 URL，有效期 5 分钟，`expires_in` 固定 300 秒）与 `ReadStream`（凭签名 token 下载或预览文件，成功响应体是文件而非 JSON 信封，原始字节放在 `Response.Raw`）；写入侧 `WritePublish`（把会话产生的文件发布为画廊产物）、`WriteUpdate`（重命名或转移个人/团队作用域）、`WriteDelete`（从画廊移除，源文件仍保留在会话中）；公开分享 `WriteShareEnable`（开启匿名公开分享并返回公开链接，任何人凭链接即可查看、无需登录）、`WriteShareRevoke`（关闭分享，链接立即失效）、`WriteShareSync`（把公开快照刷新为最新内容——当 `share_enabled` 为 true 且 `share_file_id` 与 `file_id` 不一致时表示快照已过期，调用它刷新）。相关导出类型包括 `PublishedArtifactItem`、`ArtifactShareState`、`SignedUrLs` 以及各 `Artifact*Request` / `Artifact*Response`。 diff --git a/zh/home.mdx b/zh/home.mdx index bef254aa6..a01c20084 100644 --- a/zh/home.mdx +++ b/zh/home.mdx @@ -45,7 +45,7 @@ Flashduty 是面向 DevOps、SRE 和运维团队的一站式可观测性平台 - **对话即排障**：Agent 自主规划、调用工具、流式输出调查过程与结论 - **与故障响应联动**：从故障或作战室一键拉起会话，携带上下文进入排查 - - **知识沉淀与复用**：以 DUTY.md 为入口的知识库承载长期运维上下文 + - **知识沉淀与复用**：以 DUTY.md 为入口的知识承载长期运维上下文 - **可扩展工具生态**：Skill、MCP、A2A Agent 与自托管 Runner diff --git a/zh/on-call/comparison/vs-pagerduty.mdx b/zh/on-call/comparison/vs-pagerduty.mdx index b70c35712..d67e15507 100644 --- a/zh/on-call/comparison/vs-pagerduty.mdx +++ b/zh/on-call/comparison/vs-pagerduty.mdx @@ -160,7 +160,7 @@ Response 解决「找到人之后怎么快速闭环」：一条时间线、一 | **代码仓库与 K8s** | [GitHub/GitLab App](/zh/ai-sre/apps) 沙箱内访问代码仓库、提交 PR/MR/Issue；Kubernetes App 按 namespace 接入集群 | 公开资料未见 | | **AI 自动化任务** | [自动化](/zh/ai-sre/automations)按 cron、HTTP API 或故障事件触发，内置告警噪音分析、事故复盘、值班洞察等模板 | 依赖 Event Orchestration 与 Runbook Automation 独立产品线 | | **可扩展性** | [Skills 市场](/zh/ai-sre/skills)、[MCP 外部工具](/zh/ai-sre/mcp)、[Subagent 与 A2A 委派](/zh/ai-sre/agents)，**扩展面不设上限** | SRE Agent 限于启停官方预置连接器（Datadog、Splunk、CloudWatch 等约 23 个）与追加提示词式 Skill；不支持为自家 Agent 挂载任意 MCP 工具，无子 Agent 派生，跨厂商 Agent 协作尚在 early access | -| **知识与记忆** | [知识库](/zh/ai-sre/knowledge)（DUTY.md + 文件引用）、[自动记忆提炼](/zh/ai-sre/memory)，`/init` 可导入 Claude Code、Cursor 等工具的已有知识 | 公开资料未见 | +| **知识与记忆** | [知识](/zh/ai-sre/knowledge)（DUTY.md + 文件引用）、[自动记忆提炼](/zh/ai-sre/memory)，`/init` 可导入 Claude Code、Cursor 等工具的已有知识 | 公开资料未见 | | **AI 复盘** | 故障复盘一键生成 + 自动化定时复盘 | 复盘（原 Jeli，正并入主产品）随 Professional 及以上提供，Professional/Business 档限每年 300 次 | | **使用洞察** | [/insight](/zh/ai-sre/insight) 复盘近 30 天 AI 使用情况，量化摩擦并给出改进建议 | 公开资料未见 | | **计费方式** | 按 credits 用量计费（1 credit = ¥1），开通免费，详见[官网价格页](https://www.flashduty.com/zh/pricing) | AIOps 单独加购（\$699+/月起，按事件量计费）；各套餐含一次性 AI Actions 额度（Professional 1,000 / Business 5,000 / Enterprise 20,000 次），SRE Agent 查询、Scribe 会议按次扣点，超额需加购 | diff --git a/zh/openapi/api-catalog.mdx b/zh/openapi/api-catalog.mdx index 2b8550a7c..1042b8f57 100644 --- a/zh/openapi/api-catalog.mdx +++ b/zh/openapi/api-catalog.mdx @@ -491,11 +491,11 @@ Flashduty Open API 提供 **338** 个接口，覆盖 On-call、Monitors、RUM、 | 方法 | 接口 | 描述 | | :--- | :--- | :--- | -| POST | [`/safari/knowledge/pack/list`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-list) | 查询知识包列表 | -| POST | [`/safari/knowledge/get`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-get) | 查看账户知识包 | -| POST | [`/safari/knowledge/pack/ensure`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure) | 确保知识包存在 | -| POST | [`/safari/knowledge/pack/update`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-update) | 更新知识包 | -| POST | [`/safari/knowledge/pack/delete`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-delete) | 删除知识包 | +| POST | [`/safari/knowledge/pack/list`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-list) | 查询知识列表 | +| POST | [`/safari/knowledge/get`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-get) | 查看账户知识 | +| POST | [`/safari/knowledge/pack/ensure`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure) | 确保知识存在 | +| POST | [`/safari/knowledge/pack/update`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-update) | 更新知识 | +| POST | [`/safari/knowledge/pack/delete`](/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-delete) | 删除知识 | | POST | [`/safari/knowledge/file/list`](/zh/api-reference/ai-sre/knowledge/knowledge-file-read-list) | 查询知识文件列表 | | POST | [`/safari/knowledge/file/get`](/zh/api-reference/ai-sre/knowledge/knowledge-file-read-get) | 获取知识文件 | | POST | [`/safari/knowledge/file/put`](/zh/api-reference/ai-sre/knowledge/knowledge-file-write-put) | 上传知识文件 |