docs: clarify OpenAPI chat username identity

astrbot/dashboard/schemas.py

@@ -183,7 +183,15 @@ class OpenApiChatRequest(OpenModel):
     message: Any = None
     session_id: str | None = None
     conversation_id: str | None = None
-    username: str | None = None
+    username: str | None = Field(
+        default=None,
+        description=(
+            "Caller-declared WebChat sender/session owner. This value is used "
+            "as the message sender identity and may participate in "
+            "sender-ID-based permission checks; trusted integrations should "
+            "validate or map it before accepting end-user input."
+        ),
+    )
     config_id: str | None = None
     config_name: str | None = None
     platform_id: str | None = None

docs/en/dev/openapi.md

@@ -130,6 +130,8 @@ Notes:
 
 `POST /api/v1/chat` additionally requires `username`, with optional `session_id` (a UUID is auto-generated if omitted).
 
+`username` is a caller-declared WebChat identity. It is used as the message sender and session owner in the message pipeline, including sender-ID-based command permission checks. Treat API keys with the `chat` scope as trusted backend credentials. If you expose chat access to end users, proxy requests through your own service and map each external user to an allowed `username`; do not let clients submit administrator IDs or other reserved sender IDs directly.
+
 ```json
 {
   "username": "alice",

docs/public/openapi.json

@@ -5944,7 +5944,8 @@
         ],
         "properties": {
           "username": {
-            "type": "string"
+            "type": "string",
+            "description": "Caller-declared WebChat sender/session owner. This value is used as the message sender identity and may participate in sender-ID-based command permission checks. Treat chat-scoped API keys as trusted backend credentials and map or validate usernames before accepting end-user input."
           },
           "session_id": {
             "type": "string"

docs/zh/dev/openapi.md

@@ -131,6 +131,8 @@ X-API-Key: abk_xxx
 
 `POST /api/v1/chat` 额外需要 `username`，可选 `session_id`（不传会自动创建 UUID）。
 
+`username` 是调用方声明的 WebChat 用户标识，会作为本次消息的 sender 和会话 owner 进入消息管道，并参与基于 sender ID 的指令权限判断。因此，带有 `chat` scope 的 API Key 应仅发放给可信后端服务。如果需要面向终端用户开放，请在自己的服务端将外部用户映射到受控的 `username`，不要允许客户端直接传入管理员 ID 或其他保留 sender ID。
+
 ```json
 {
   "username": "alice",

openspec/openapi-v1.yaml

@@ -5266,6 +5266,7 @@ components:
       properties:
         username:
           type: string
+          description: Caller-declared WebChat sender/session owner. This value is used as the message sender identity and may participate in sender-ID-based command permission checks. Treat chat-scoped API keys as trusted backend credentials and map or validate usernames before accepting end-user input.
         session_id:
           type: string
         conversation_id: