> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 删除知识文件

> 按相对路径删除知识包中的文件。

## 限制说明

| 项目   | 说明                                   |
| ---- | ------------------------------------ |
| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |
| 权限要求 | **知识库管理**（`ai-sre`）                  |

## 使用说明

* 删除是幂等的——删除不存在的文件也会成功。
* 当其他包内文件仍引用目标文件时，删除失败并返回 `ReferenceExist`（附带引用方列表）；设置 `force` 可强制删除（引用方以警告形式返回）。
* 不传 `pack_id` 时默认账户范围知识包；编辑账户包需要账户 Owner/Admin 权限，编辑团队包需要是该团队成员。
* 每次调用都会记录到账户审计日志。


## OpenAPI

````yaml /api-reference/safari.openapi.zh.json post /safari/knowledge/file/delete
openapi: 3.1.0
info:
  title: Flashduty 开放 API
  description: >-
    Flashduty AI SRE 平台的公开 HTTP API —— 技能、MCP 服务器（连接器）、A2A 智能体与会话。所有接口均使用
    Flashduty 控制台签发的 `app_key` 查询参数进行认证。
  version: 1.0.0
servers:
  - url: https://api.flashcat.cloud
    description: Flashduty Open API
security:
  - AppKeyAuth: []
tags:
  - name: AI SRE/技能
    description: AI SRE 智能体技能管理。
  - name: AI SRE/MCP 服务器
    description: MCP（Model Context Protocol）服务器管理。
  - name: AI SRE/A2A 智能体
    description: A2A（智能体到智能体）远程智能体管理。
  - name: AI SRE/会话
    description: AI SRE 智能体会话历史 —— 查询、查看与导出会话记录。
  - name: AI SRE/自动化
  - name: AI SRE/知识
paths:
  /safari/knowledge/file/delete:
    post:
      tags:
        - AI SRE/知识
      summary: 删除知识文件
      description: 按相对路径删除知识包中的文件。
      operationId: knowledge-file-write-delete
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeFileDeleteRequest'
            example:
              rel_path: tmp/openapi-delete-example.md
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ResponseEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/KnowledgeFileDeleteResponse'
              example:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                data: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - AppKeyAuth: []
components:
  schemas:
    KnowledgeFileDeleteRequest:
      type: object
      description: 要从知识包中删除的文件。
      properties:
        pack_id:
          type: string
          description: 知识包 ID；默认为调用者的账户范围知识包。
        rel_path:
          type: string
          description: 文件相对于知识包根目录的路径。
        force:
          type: boolean
          description: 即使其他包内文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。
      required:
        - rel_path
    ResponseEnvelope:
      type: object
      description: >-
        Standard response envelope used by every Flashduty public API. On
        success `data` contains the endpoint-specific payload and `error` is
        absent. On failure `error` is present and `data` is absent. `request_id`
        is always present and is also mirrored in the `Flashcat-Request-Id`
        response header.
      properties:
        request_id:
          type: string
          description: >-
            Unique ID for this request. Mirrored in the Flashcat-Request-Id
            header. Include it when reporting issues.
          example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
        error:
          $ref: '#/components/schemas/DutyError'
        data:
          description: Endpoint-specific payload. See each operation's 200 response schema.
      required:
        - request_id
    KnowledgeFileDeleteResponse:
      type: object
      description: 删除结果；无警告时为空对象。
      properties:
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeWarning'
          description: >-
            删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被包内其他文件 @ref
            引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。
    DutyError:
      type: object
      description: >-
        Error payload inside the response envelope. Present only on non-2xx
        responses.
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: >-
            Human-readable error message, localized by the caller's
            Accept-Language. May contain field names, IDs, or other context from
            the failing request.
      required:
        - code
        - message
    KnowledgeWarning:
      type: object
      description: 文件上传/删除返回的非阻塞提示，例如指向已删除文件的引用。
      properties:
        code:
          type: string
          description: >-
            提示码。可选值：`unresolved_reference`（写入的文件内容中 @ref 引用了包内不存在的文件，`ref`
            给出该引用）、`still_referenced_by`（被删除的文件仍被包内其他文件 @ref 引用，`refs` 列出引用方）。
          enum:
            - unresolved_reference
            - still_referenced_by
        ref:
          type: string
          description: 与提示相关的单个引用。
        refs:
          type: array
          description: 与提示相关的多个引用。
          items:
            type: string
      required:
        - code
    ErrorResponse:
      type: object
      description: Response envelope for errors. `error` is required; `data` is absent.
      properties:
        request_id:
          type: string
          example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          description: 本次请求的唯一追踪 ID（trace ID），反馈问题时请提供该值以便检索日志。
        error:
          $ref: '#/components/schemas/DutyError'
      required:
        - request_id
        - error
    ErrorCode:
      type: string
      description: >-
        Flashduty error code enum. Every failed API response sets `error.code`
        to one of these values. The value is a stable wire string — not a
        localized message and not a numeric status. HTTP status is
        informational.
      enum:
        - OK
        - InvalidParameter
        - BadRequest
        - InvalidContentType
        - ResourceNotFound
        - NoLicense
        - ReferenceExist
        - Unauthorized
        - BalanceNotEnough
        - AccessDenied
        - RouteNotFound
        - MethodNotAllowed
        - UndonedOrderExist
        - RequestLocked
        - EntityTooLarge
        - RequestTooFrequently
        - RequestVerifyRequired
        - DangerousOperation
        - InternalError
        - ServiceUnavailable
  responses:
    BadRequest:
      description: Invalid request — usually a missing or malformed parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingParameter:
              summary: Missing required parameter
              value:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                error:
                  code: InvalidParameter
                  message: The specified parameter skill_id is not valid.
    Unauthorized:
      description: Missing or invalid app_key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingAppKey:
              value:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                error:
                  code: Unauthorized
                  message: You are unauthorized.
    Forbidden:
      description: The app_key is valid but lacks permission for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            accessDenied:
              value:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                error:
                  code: AccessDenied
                  message: Access Denied.
    TooManyRequests:
      description: Rate limit hit. Either the global API limit or a per-account limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimited:
              value:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                error:
                  code: RequestTooFrequently
                  message: Request too frequently.
    ServerError:
      description: Unexpected server-side error. Include the request_id when reporting.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal:
              value:
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
                error:
                  code: InternalError
                  message: >-
                    We encountered an internal error, and it has been reported.
                    Please try again later.
  securitySchemes:
    AppKeyAuth:
      type: apiKey
      in: query
      name: app_key
      description: >-
        App key issued from the Flashduty console. Required on every public API
        call. Keep it secret — it grants the same access as the owning account.

````