fix: restore OpenAPI file uploads

Expose /api/v1/file in OpenAPI, enable file-scoped API keys, and regenerate docs/client artifacts.

docs/en/dev/openapi.md

@@ -40,6 +40,7 @@ When creating an API Key, you can configure `scopes`. Each scope controls the ra
 | `im` | Send proactive IM messages and query bot/platform list | `POST /api/v1/im/message`, `GET /api/v1/im/bots` |
 | `config` | Manage config profiles, system config, and shared configuration. This scope also includes `bot` and `provider` access. | `GET /api/v1/configs`, `GET/PUT /api/v1/system-config`, `GET/POST /api/v1/config-profiles` |
 | `chat` | Access chat capabilities and query sessions | `POST /api/v1/chat`, `GET /api/v1/chat/sessions` |
+| `file` | Upload and download chat attachments | `POST /api/v1/file`, `GET /api/v1/file`, `POST /api/v1/files` |
 | `plugin` | Manage plugins, plugin config, plugin sources, and marketplace entries | `GET /api/v1/plugins`, `GET/PUT /api/v1/plugins/config`, `POST /api/v1/plugins/install/url` |
 | `mcp` | Manage MCP server configurations and provider sync | `GET/POST /api/v1/mcp/servers`, `PATCH /api/v1/mcp/servers/{server_name}/enabled`, `POST /api/v1/mcp/providers/modelscope/sync` |
 | `skill` | Manage skills, skill archives, skill files, and Shipyard Neo skill workflows | `GET/POST /api/v1/skills`, `PUT /api/v1/skills/{skill_name}/files/{file_path}`, `POST /api/v1/skills/neo/sync` |
@@ -48,7 +49,7 @@ If the API Key does not include the required scope for the target endpoint, the
 
 `config` is a broad management scope. When an API key is created with `config`, AstrBot grants the key `config`, `bot`, and `provider` access together. The WebUI mirrors this dependency: selecting `config` selects `bot` and `provider`; deselecting `bot` or `provider` removes `config`.
 
-Developer API keys currently support only the 9 scopes listed above. `file`, `tool`, `skills`, `kb`, `data`, and `system` are not valid developer API key scopes. Use the singular `skill` scope for `/api/v1/skills/*` endpoints. The public OpenAPI reference only includes endpoints covered by supported developer API key scopes.
+Developer API keys currently support only the 10 scopes listed above. `tool`, `skills`, `kb`, `data`, and `system` are not valid developer API key scopes. Use the singular `skill` scope for `/api/v1/skills/*` endpoints. The public OpenAPI reference only includes endpoints covered by supported developer API key scopes.
 
 ## Common Endpoints
 
@@ -59,6 +60,7 @@ Interact with AstrBot's built-in Agent. Supports plugin calls, tool calls, and o
 - `POST /api/v1/chat`: send chat message (SSE stream, server generates UUID when `session_id` is omitted)
 - `GET /api/v1/chat/sessions`: list sessions for a specific `username` with pagination
 - `GET /api/v1/configs`: list available config files
+- `POST /api/v1/file`: upload an attachment for later use in message segments
 
 **Bots and Providers**
 
@@ -120,7 +122,7 @@ Supported `type` values:
 
 Notes:
 
-- `attachment_id` comes from an existing attachment record. Developer API keys cannot currently upload attachments via `POST /api/v1/file`.
+- `attachment_id` comes from an existing attachment record, or from `POST /api/v1/file` after uploading an attachment with the `file` scope.
 - `reply` cannot be the only segment; at least one content segment (e.g. `plain/image/file/...`) is required.
 - A request with only `reply` or empty content will return an error.
 

docs/public/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "AstrBot OpenAPI v1",
     "version": "0.1.0",
-    "description": "Target REST contract for migrating AstrBot HTTP APIs to /api/v1. Dynamic AstrBot configuration payloads are intentionally modeled as open JSON objects because their schemas are provided at runtime by template endpoints. Developer API keys currently support these scopes only: bot, provider, persona, im, config, chat, plugin, mcp, skill. The config scope also grants bot and provider access.\n"
+    "description": "Target REST contract for migrating AstrBot HTTP APIs to /api/v1. Dynamic AstrBot configuration payloads are intentionally modeled as open JSON objects because their schemas are provided at runtime by template endpoints. Developer API keys currently support these scopes only: bot, provider, persona, im, config, chat, file, plugin, mcp, skill. The config scope also grants bot and provider access.\n"
   },
   "servers": [
     {
@@ -17,6 +17,9 @@
     }
   ],
   "tags": [
+    {
+      "name": "Open API"
+    },
     {
       "name": "System Config"
     },
@@ -41,6 +44,9 @@
     {
       "name": "IM"
     },
+    {
+      "name": "Files"
+    },
     {
       "name": "Plugins"
     },
@@ -2224,6 +2230,214 @@
         }
       }
     },
+    "/api/v1/files": {
+      "post": {
+        "tags": [
+          "Files"
+        ],
+        "summary": "Upload a file",
+        "operationId": "uploadFile",
+        "x-astrbot-scope": "file",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/FileUploadRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/Ok"
+          }
+        }
+      }
+    },
+    "/api/v1/file": {
+      "post": {
+        "tags": [
+          "Open API"
+        ],
+        "summary": "Upload a file",
+        "operationId": "uploadOpenApiFile",
+        "x-astrbot-scope": "file",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/FileUploadRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/Ok"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Open API"
+        ],
+        "summary": "Download an uploaded file by attachment ID",
+        "operationId": "downloadOpenApiFile",
+        "x-astrbot-scope": "file",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AttachmentIdQuery"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "File content or an error envelope",
+            "content": {
+              "application/octet-stream": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/files/content": {
+      "get": {
+        "tags": [
+          "Files"
+        ],
+        "summary": "Get an uploaded file by stored filename",
+        "operationId": "getFileByName",
+        "x-astrbot-scope": "file",
+        "parameters": [
+          {
+            "name": "filename",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "File bytes or an error envelope",
+            "content": {
+              "application/octet-stream": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/files/tokens/{file_token}": {
+      "get": {
+        "tags": [
+          "Files"
+        ],
+        "summary": "Get a tokenized public file",
+        "operationId": "getTokenFile",
+        "x-astrbot-scope": "file",
+        "parameters": [
+          {
+            "name": "file_token",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Tokenized file bytes or an error envelope",
+            "content": {
+              "application/octet-stream": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/files/{attachment_id}": {
+      "get": {
+        "tags": [
+          "Files"
+        ],
+        "summary": "Get attachment metadata",
+        "operationId": "getAttachment",
+        "x-astrbot-scope": "file",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AttachmentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/Ok"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Files"
+        ],
+        "summary": "Delete an attachment",
+        "operationId": "deleteAttachment",
+        "x-astrbot-scope": "file",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AttachmentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/Ok"
+          }
+        }
+      }
+    },
+    "/api/v1/files/{attachment_id}/content": {
+      "get": {
+        "tags": [
+          "Files"
+        ],
+        "summary": "Download attachment content",
+        "operationId": "downloadAttachment",
+        "x-astrbot-scope": "file",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AttachmentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "File content",
+            "content": {
+              "application/octet-stream": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/plugins": {
       "get": {
         "tags": [
@@ -5376,6 +5590,22 @@
       }
     },
     "parameters": {
+      "AttachmentId": {
+        "name": "attachment_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        }
+      },
+      "AttachmentIdQuery": {
+        "name": "attachment_id",
+        "in": "query",
+        "required": true,
+        "schema": {
+          "type": "string"
+        }
+      },
       "BotId": {
         "name": "bot_id",
         "in": "path",
@@ -5961,6 +6191,18 @@
         },
         "additionalProperties": false
       },
+      "FileUploadRequest": {
+        "type": "object",
+        "required": [
+          "file"
+        ],
+        "properties": {
+          "file": {
+            "type": "string",
+            "format": "binary"
+          }
+        }
+      },
       "PluginUpdateRequest": {
         "type": "object",
         "properties": {

docs/scripts/update_openapi_json.py

@@ -12,6 +12,7 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
 DEFAULT_SPEC = REPO_ROOT / "openspec" / "openapi-v1.yaml"
 DEFAULT_OUTPUT = REPO_ROOT / "docs" / "public" / "openapi.json"
 PUBLIC_OPEN_API_TAGS = {
+    "Open API",
     "System Config",
     "Config Profiles",
     "Bot Config Routes",
@@ -20,6 +21,7 @@ PUBLIC_OPEN_API_TAGS = {
     "Providers",
     "Chat",
     "IM",
+    "Files",
     "Plugins",
     "Plugin Sources",
     "Plugin Pages",

docs/zh/dev/openapi.md

@@ -40,6 +40,7 @@ X-API-Key: abk_xxx
 | `im` | 主动发 IM 消息、查询 bot/platform 列表 | `POST /api/v1/im/message`、`GET /api/v1/im/bots` |
 | `config` | 管理配置文件、系统配置和通用配置。该 scope 同时包含 `bot` 和 `provider` 访问权限。 | `GET /api/v1/configs`、`GET/PUT /api/v1/system-config`、`GET/POST /api/v1/config-profiles` |
 | `chat` | 调用对话能力、查询对话会话 | `POST /api/v1/chat`、`GET /api/v1/chat/sessions` |
+| `file` | 上传和下载对话附件 | `POST /api/v1/file`、`GET /api/v1/file`、`POST /api/v1/files` |
 | `plugin` | 管理插件、插件配置、插件源和插件市场 | `GET /api/v1/plugins`、`GET/PUT /api/v1/plugins/config`、`POST /api/v1/plugins/install/url` |
 | `mcp` | 管理 MCP 服务器配置和服务端同步 | `GET/POST /api/v1/mcp/servers`、`PATCH /api/v1/mcp/servers/{server_name}/enabled`、`POST /api/v1/mcp/providers/modelscope/sync` |
 | `skill` | 管理 Skills、Skill 压缩包、Skill 文件和 Shipyard Neo Skill 流程 | `GET/POST /api/v1/skills`、`PUT /api/v1/skills/{skill_name}/files/{file_path}`、`POST /api/v1/skills/neo/sync` |
@@ -48,7 +49,7 @@ X-API-Key: abk_xxx
 
 `config` 是较大的管理 scope。创建 API Key 时如果包含 `config`，AstrBot 会同时授予该 Key `config`、`bot` 和 `provider` 访问权限。WebUI 的勾选逻辑也会体现这个依赖关系：选中 `config` 会同时选中 `bot` 和 `provider`；取消选中 `bot` 或 `provider` 时，会同步取消 `config`。
 
-当前开发者 API Key 仅开放以上 9 个 scope。`file`、`tool`、`skills`、`kb`、`data`、`system` 暂不支持作为开发者 API Key scope。`/api/v1/skills/*` 接口使用单数 `skill` scope，不使用复数 `skills`。公开 OpenAPI 文档只包含这些开发者 API Key scope 覆盖的接口。
+当前开发者 API Key 仅开放以上 10 个 scope。`tool`、`skills`、`kb`、`data`、`system` 暂不支持作为开发者 API Key scope。`/api/v1/skills/*` 接口使用单数 `skill` scope，不使用复数 `skills`。公开 OpenAPI 文档只包含这些开发者 API Key scope 覆盖的接口。
 
 ## 常用接口
 
@@ -59,6 +60,7 @@ X-API-Key: abk_xxx
 - `POST /api/v1/chat`：发送对话消息（SSE 流式返回，不传 `session_id` 会自动创建 UUID）
 - `GET /api/v1/chat/sessions`：分页获取指定 `username` 的会话
 - `GET /api/v1/configs`：获取可用配置文件列表
+- `POST /api/v1/file`：上传附件，之后可在消息段中引用
 
 **机器人和模型提供商**
 
@@ -121,7 +123,7 @@ X-API-Key: abk_xxx
 
 说明：
 
-- `attachment_id` 来自已存在的附件记录。开发者 API Key 当前不能使用 `POST /api/v1/file` 上传附件。
+- `attachment_id` 来自已存在的附件记录，或使用 `file` scope 调用 `POST /api/v1/file` 上传附件后的返回值。
 - `reply` 不能单独作为唯一内容，至少需要一个有实际内容的段（如 `plain/image/file/...`）。
 - 仅 `reply` 或空内容会返回错误。