From 2b40d08c7855e09eba231dd17ede0b2eb34e8531 Mon Sep 17 00:00:00 2001
From: qzl <qzl@example.com>
Date: Sat, 28 Feb 2026 12:19:02 +0800
Subject: [PATCH] docs: add Friends API documentation to runtime-route.md

---
 docs/runtime/runtime-route.md | 179 ++++++++++++++++++++++++++++++++++
 1 file changed, 179 insertions(+)

diff --git a/docs/runtime/runtime-route.md b/docs/runtime/runtime-route.md
index 89b67c2..e60b79a 100644
--- a/docs/runtime/runtime-route.md
+++ b/docs/runtime/runtime-route.md
@@ -444,6 +444,185 @@
 
 ---
 
+## Friends
+
+### POST /friends/requests
+
+发送好友请求（需要认证）。
+
+**Request:**
+```json
+{
+  "target_user_id": "string (uuid)",
+  "content": "string? (max 500 chars)"
+}
+```
+
+**Response:** 201 Created
+```json
+{
+  "id": "uuid",
+  "from_user_id": "uuid",
+  "to_user_id": "uuid",
+  "content": "string?",
+  "status": "pending",
+  "created_at": "string (ISO 8601)",
+  "updated_at": "string (ISO 8601)"
+}
+```
+
+**Errors:**
+- 400: 不能添加自己为好友
+- 401: 未认证
+- 404: 目标用户不存在
+- 409: 已是好友或请求已存在
+- 422: 请求参数无效
+
+---
+
+### GET /friends/requests/inbox
+
+获取收到的好友请求（需要认证）。
+
+**Response:** 200 OK
+```json
+[
+  {
+    "id": "uuid",
+    "from_user_id": "uuid",
+    "to_user_id": "uuid",
+    "content": "string?",
+    "status": "pending",
+    "created_at": "string (ISO 8601)",
+    "updated_at": "string (ISO 8601)"
+  }
+]
+```
+
+**Errors:**
+- 401: 未认证
+
+---
+
+### GET /friends/requests/outgoing
+
+获取发出的好友请求（需要认证）。
+
+**Response:** 200 OK
+```json
+[
+  {
+    "id": "uuid",
+    "from_user_id": "uuid",
+    "to_user_id": "uuid",
+    "content": "string?",
+    "status": "pending",
+    "created_at": "string (ISO 8601)",
+    "updated_at": "string (ISO 8601)"
+  }
+]
+```
+
+**Errors:**
+- 401: 未认证
+
+---
+
+### POST /friends/requests/{id}/accept
+
+接受好友请求（需要认证）。
+
+**Response:** 200 OK
+```json
+{
+  "id": "uuid",
+  "from_user_id": "uuid",
+  "to_user_id": "uuid",
+  "content": "string?",
+  "status": "accepted",
+  "created_at": "string (ISO 8601)",
+  "updated_at": "string (ISO 8601)"
+}
+```
+
+**Errors:**
+- 401: 未认证
+- 404: 请求不存在
+- 409: 请求已被处理
+
+---
+
+### POST /friends/requests/{id}/decline
+
+拒绝好友请求（需要认证）。
+
+**Response:** 200 OK
+```json
+{
+  "id": "uuid",
+  "from_user_id": "uuid",
+  "to_user_id": "uuid",
+  "content": "string?",
+  "status": "declined",
+  "created_at": "string (ISO 8601)",
+  "updated_at": "string (ISO 8601)"
+}
+```
+
+**Errors:**
+- 401: 未认证
+- 404: 请求不存在
+- 409: 请求已被处理
+
+---
+
+### DELETE /friends/requests/{id}
+
+取消发出的好友请求（需要认证）。
+
+**Response:** 204 No Content
+
+**Errors:**
+- 401: 未认证
+- 404: 请求不存在
+
+---
+
+### GET /friends
+
+获取好友列表（需要认证）。
+
+**Response:** 200 OK
+```json
+[
+  {
+    "id": "uuid",
+    "friend_id": "uuid",
+    "username": "string",
+    "avatar_url": "string?",
+    "bio": "string?",
+    "created_at": "string (ISO 8601)"
+  }
+]
+```
+
+**Errors:**
+- 401: 未认证
+
+---
+
+### DELETE /friends/{id}
+
+删除好友（需要认证）。
+
+**Response:** 204 No Content
+
+**Errors:**
+- 401: 未认证
+- 404: 好友关系不存在
+
+---
+
 ## Agent Chat
 
 ### POST /agent-chats