diff --git a/docs/API.md b/docs/API.md index 384ad67..b2f36b8 100644 --- a/docs/API.md +++ b/docs/API.md @@ -4,7 +4,7 @@ 该项目提供了小红书 MCP (Model Context Protocol) 服务的 HTTP API 接口，同时支持 MCP 协议和标准的 HTTP REST API。本文档描述了 HTTP API 的使用方法。 -**Base URL**: `http://localhost:8080` +**Base URL**: `http://localhost:18060` **注意**: 以下响应示例仅展示主要字段结构，完整的字段信息请通过实际API调用查看。 @@ -30,6 +30,26 @@ } ``` +## API 端点一览 + +| 方法 | 端点 | 描述 | +|------|------|------| +| GET | `/health` | 健康检查 | +| GET | `/api/v1/login/status` | 检查登录状态 | +| GET | `/api/v1/login/qrcode` | 获取登录二维码 | +| DELETE | `/api/v1/login/cookies` | 删除 Cookies（重置登录） | +| POST | `/api/v1/publish` | 发布图文内容 | +| POST | `/api/v1/publish_video` | 发布视频内容 | +| GET | `/api/v1/feeds/list` | 获取 Feeds 列表 | +| GET/POST | `/api/v1/feeds/search` | 搜索 Feeds | +| POST | `/api/v1/feeds/detail` | 获取 Feed 详情 | +| POST | `/api/v1/user/profile` | 获取用户主页信息 | +| GET | `/api/v1/user/me` | 获取当前登录用户信息 | +| POST | `/api/v1/feeds/comment` | 发表评论 | +| POST | `/api/v1/feeds/comment/reply` | 回复评论 | + +--- + ## API 端点 ### 1. 健康检查 @@ -107,6 +127,27 @@ GET /api/v1/login/qrcode - `is_logged_in`: 当前是否已登录 - `img`: Base64 编码的二维码图片 +#### 2.3 删除 Cookies（重置登录状态） + +删除本地存储的 cookies 文件，重置登录状态。 + +**请求** +``` +DELETE /api/v1/login/cookies +``` + +**响应** +```json +{ + "success": true, + "data": { + "cookie_path": "/path/to/cookies.json", + "message": "Cookies 已成功删除，登录状态已重置。下次操作时需要重新登录。" + }, + "message": "删除 cookies 成功" +} +``` + --- ### 3. 内容发布 @@ -230,14 +271,35 @@ GET /api/v1/feeds/list "user": { "userId": "user_id_1", "nickname": "用户昵称", + "nickName": "用户昵称", "avatar": "https://example.com/avatar.jpg" }, "interactInfo": { + "liked": false, "likedCount": "100", - "commentCount": "50" + "collected": false, + "collectedCount": "50", + "commentCount": "30", + "sharedCount": "10" }, "cover": { - "url": "https://example.com/cover.jpg" + "width": 1080, + "height": 1440, + "url": "https://example.com/cover.jpg", + "urlDefault": "https://example.com/cover_default.jpg", + "urlPre": "https://example.com/cover_pre.jpg", + "fileId": "file_id", + "infoList": [ + { + "imageScene": "WB_DFT", + "url": "https://example.com/image.jpg" + } + ] + }, + "video": { + "capa": { + "duration": 60 + } } }, "index": 0 @@ -249,11 +311,27 @@ GET /api/v1/feeds/list } ``` +**响应字段说明:** +- `xsecToken`: 安全令牌，调用详情等接口时需要 +- `id`: Feed ID +- `modelType`: 模型类型，通常为 "note" +- `noteCard.type`: 笔记类型 +- `noteCard.video`: 视频信息（仅视频笔记有此字段） + - `capa.duration`: 视频时长（秒） +- `noteCard.interactInfo`: 互动信息 + - `liked`: 当前用户是否已点赞 + - `collected`: 当前用户是否已收藏 + - `likedCount`: 点赞数 + - `collectedCount`: 收藏数 + - `commentCount`: 评论数 + - `sharedCount`: 分享数 +``` + #### 4.2 搜索 Feeds -根据关键词搜索 Feeds。 +根据关键词搜索 Feeds，支持 GET 和 POST 两种请求方式。 -**请求** +**请求方式一：GET** ``` GET /api/v1/feeds/search?keyword=搜索关键词 ``` @@ -261,6 +339,33 @@ GET /api/v1/feeds/search?keyword=搜索关键词 **查询参数:** - `keyword` (string, required): 搜索关键词 +**请求方式二：POST（支持高级筛选）** +``` +POST /api/v1/feeds/search +Content-Type: application/json +``` + +**请求体** +```json +{ + "keyword": "搜索关键词", + "filters": { + "sort_by": "综合", + "note_type": "不限", + "publish_time": "不限", + "search_scope": "不限", + "location": "不限" + } +} +``` + +**筛选参数说明:** +- `sort_by` (string, optional): 排序依据，可选值：`综合`(默认) | `最新` | `最多点赞` | `最多评论` | `最多收藏` +- `note_type` (string, optional): 笔记类型，可选值：`不限`(默认) | `视频` | `图文` +- `publish_time` (string, optional): 发布时间，可选值：`不限`(默认) | `一天内` | `一周内` | `半年内` +- `search_scope` (string, optional): 搜索范围，可选值：`不限`(默认) | `已看过` | `未看过` | `已关注` +- `location` (string, optional): 位置距离，可选值：`不限`(默认) | `同城` | `附近` + **响应** ```json { @@ -272,15 +377,28 @@ GET /api/v1/feeds/search?keyword=搜索关键词 "id": "feed_id_1", "modelType": "note", "noteCard": { + "type": "normal", "displayTitle": "相关笔记标题", "user": { "userId": "user_id_1", - "nickname": "用户昵称" + "nickname": "用户昵称", + "avatar": "https://example.com/avatar.jpg" }, "interactInfo": { + "liked": false, "likedCount": "80", - "commentCount": "35" - } + "collected": false, + "collectedCount": "40", + "commentCount": "35", + "sharedCount": "15" + }, + "cover": { + "width": 1080, + "height": 1440, + "url": "https://example.com/cover.jpg", + "urlDefault": "https://example.com/cover_default.jpg" + }, + "video": null }, "index": 0 } @@ -291,9 +409,14 @@ GET /api/v1/feeds/search?keyword=搜索关键词 } ``` +**响应字段说明:** +- 响应结构与"获取 Feeds 列表"接口相同 +- `video`: 视频笔记时有此字段，图文笔记为 null +``` + #### 4.3 获取 Feed 详情 -获取指定 Feed 的详细信息。 +获取指定 Feed 的详细信息，支持加载全部评论和自定义评论加载配置。 **请求** ``` @@ -305,13 +428,26 @@ Content-Type: application/json ```json { "feed_id": "64f1a2b3c4d5e6f7a8b9c0d1", - "xsec_token": "security_token_here" + "xsec_token": "security_token_here", + "load_all_comments": false, + "comment_config": { + "click_more_replies": true, + "max_replies_threshold": 50, + "max_comment_items": 100, + "scroll_speed": "normal" + } } ``` **请求参数说明:** - `feed_id` (string, required): Feed ID - `xsec_token` (string, required): 安全令牌 +- `load_all_comments` (boolean, optional): 是否加载全部评论，默认 false +- `comment_config` (object, optional): 评论加载配置 + - `click_more_replies` (boolean): 是否点击"更多回复"按钮 + - `max_replies_threshold` (int): 回复数量阈值，超过这个数量的"更多"按钮将被跳过（0表示不跳过任何） + - `max_comment_items` (int): 最大加载评论数（.parent-comment 数量），0表示加载所有 + - `scroll_speed` (string): 滚动速度等级，可选值：`slow`(慢速) | `normal`(正常) | `fast`(快速) **响应** ```json @@ -322,19 +458,33 @@ Content-Type: application/json "data": { "note": { "noteId": "64f1a2b3c4d5e6f7a8b9c0d1", + "xsecToken": "security_token_value", "title": "笔记标题", "desc": "笔记详细内容描述", + "type": "normal", + "time": 1702195200000, + "ipLocation": "浙江", "user": { "userId": "user_id_123", - "nickname": "作者昵称" + "nickname": "作者昵称", + "nickName": "作者昵称", + "avatar": "https://example.com/avatar.jpg" }, "interactInfo": { + "liked": false, "likedCount": "100", - "commentCount": "50" + "collected": false, + "collectedCount": "80", + "commentCount": "50", + "sharedCount": "20" }, "imageList": [ { - "urlDefault": "https://example.com/image1_default.jpg" + "width": 1080, + "height": 1440, + "urlDefault": "https://example.com/image1_default.jpg", + "urlPre": "https://example.com/image1_pre.jpg", + "livePhoto": false } ] }, @@ -342,12 +492,32 @@ Content-Type: application/json "list": [ { "id": "comment_id_1", + "noteId": "64f1a2b3c4d5e6f7a8b9c0d1", "content": "评论内容", + "likeCount": "10", + "createTime": 1702195200000, + "ipLocation": "北京", + "liked": false, "userInfo": { - "nickname": "评论者昵称" - } + "userId": "commenter_id", + "nickname": "评论者昵称", + "avatar": "https://example.com/commenter_avatar.jpg" + }, + "subCommentCount": "5", + "subComments": [ + { + "id": "sub_comment_id_1", + "content": "子评论内容", + "createTime": 1702195300000, + "userInfo": { + "nickname": "回复者昵称" + } + } + ], + "showTags": ["热评"] } ], + "cursor": "next_cursor_value", "hasMore": true } } @@ -356,11 +526,32 @@ Content-Type: application/json } ``` +**响应字段说明:** +- `note.time`: 笔记发布时间戳（毫秒） +- `note.ipLocation`: 发布者 IP 归属地 +- `note.type`: 笔记类型 +- `note.interactInfo`: 互动信息 + - `liked`: 当前用户是否已点赞 + - `collected`: 当前用户是否已收藏 +- `note.imageList[].livePhoto`: 是否为 Live Photo +- `comments.list[].createTime`: 评论发布时间戳（毫秒） +- `comments.list[].ipLocation`: 评论者 IP 归属地 +- `comments.list[].likeCount`: 评论点赞数 +- `comments.list[].liked`: 当前用户是否已点赞该评论 +- `comments.list[].subCommentCount`: 子评论数量 +- `comments.list[].subComments`: 子评论列表 +- `comments.list[].showTags`: 显示标签（如 "热评"） +- `comments.cursor`: 分页游标 +- `comments.hasMore`: 是否有更多评论 +``` + --- ### 5. 用户信息 -获取用户主页信息。 +#### 5.1 获取用户主页信息 + +获取指定用户的主页信息，包括基本信息、互动数据和发布的笔记列表。 **请求** ``` @@ -389,7 +580,11 @@ Content-Type: application/json "userBasicInfo": { "nickname": "用户昵称", "desc": "用户个人描述", - "redId": "xiaohongshu_id" + "redId": "xiaohongshu_id", + "gender": 1, + "ipLocation": "浙江", + "images": "https://example.com/avatar.jpg", + "imageb": "https://example.com/background.jpg" }, "interactions": [ { @@ -401,14 +596,26 @@ Content-Type: application/json "type": "fans", "name": "粉丝", "count": "5000" + }, + { + "type": "interaction", + "name": "获赞与收藏", + "count": "10000" } ], "feeds": [ { + "xsecToken": "security_token_value", "id": "feed_id_1", + "modelType": "note", "noteCard": { - "displayTitle": "用户的笔记标题" - } + "displayTitle": "用户的笔记标题", + "interactInfo": { + "likedCount": "100", + "collectedCount": "50" + } + }, + "index": 0 } ] } @@ -417,6 +624,86 @@ Content-Type: application/json } ``` +**响应字段说明:** +- `userBasicInfo.gender`: 性别（1: 男, 2: 女, 0: 未知） +- `userBasicInfo.ipLocation`: IP 归属地 +- `userBasicInfo.images`: 头像图片 URL +- `userBasicInfo.imageb`: 背景图片 URL +- `userBasicInfo.redId`: 小红书号 +- `interactions`: 互动数据数组 + - `type`: 类型（follows: 关注, fans: 粉丝, interaction: 获赞与收藏） + - `name`: 显示名称 + - `count`: 数量 +- `feeds`: 用户发布的笔记列表（结构同 Feed 列表） +``` + +#### 5.2 获取当前登录用户信息 + +获取当前登录用户的个人信息（无需传入 user_id），通过侧边栏导航到个人主页获取。 + +**请求** +``` +GET /api/v1/user/me +``` + +**响应** +```json +{ + "success": true, + "data": { + "data": { + "userBasicInfo": { + "nickname": "当前用户昵称", + "desc": "个人描述", + "redId": "xiaohongshu_id", + "gender": 1, + "ipLocation": "浙江", + "images": "https://example.com/my_avatar.jpg", + "imageb": "https://example.com/my_background.jpg" + }, + "interactions": [ + { + "type": "follows", + "name": "关注", + "count": "100" + }, + { + "type": "fans", + "name": "粉丝", + "count": "500" + }, + { + "type": "interaction", + "name": "获赞与收藏", + "count": "2000" + } + ], + "feeds": [ + { + "xsecToken": "security_token_value", + "id": "feed_id_1", + "modelType": "note", + "noteCard": { + "displayTitle": "我的笔记标题", + "interactInfo": { + "likedCount": "50", + "collectedCount": "30" + } + }, + "index": 0 + } + ] + } + }, + "message": "获取我的主页成功" +} +``` + +**响应字段说明:** +- 响应结构与"获取用户主页信息"接口相同 +- 此接口无需 `user_id` 和 `xsec_token` 参数，自动获取当前登录用户信息 +``` + --- ### 6. 评论管理 @@ -458,6 +745,72 @@ Content-Type: application/json } ``` +#### 6.2 回复评论 + +回复指定评论。 + +**请求** +``` +POST /api/v1/feeds/comment/reply +Content-Type: application/json +``` + +**请求体** +```json +{ + "feed_id": "64f1a2b3c4d5e6f7a8b9c0d1", + "xsec_token": "security_token_here", + "comment_id": "comment_id_to_reply", + "user_id": "target_user_id", + "content": "回复内容" +} +``` + +**请求参数说明:** +- `feed_id` (string, required): Feed ID +- `xsec_token` (string, required): 安全令牌 +- `comment_id` (string, required*): 要回复的评论 ID（与 user_id 二选一必填） +- `user_id` (string, required*): 要回复的用户 ID（与 comment_id 二选一必填） +- `content` (string, required): 回复内容 + +**响应** +```json +{ + "success": true, + "data": { + "feed_id": "64f1a2b3c4d5e6f7a8b9c0d1", + "target_comment_id": "comment_id_to_reply", + "target_user_id": "target_user_id", + "success": true, + "message": "回复评论成功" + }, + "message": "回复评论成功" +} +``` + +--- + +## 错误代码 + +所有 API 在发生错误时会返回统一格式的错误响应。以下是可能出现的错误代码： + +| 错误代码 | HTTP 状态码 | 描述 | +|----------|-------------|------| +| `INVALID_REQUEST` | 400 | 请求参数错误或格式不正确 | +| `MISSING_KEYWORD` | 400 | 搜索时缺少关键词参数 | +| `STATUS_CHECK_FAILED` | 500 | 检查登录状态失败 | +| `DELETE_COOKIES_FAILED` | 500 | 删除 Cookies 失败 | +| `PUBLISH_FAILED` | 500 | 发布图文内容失败 | +| `PUBLISH_VIDEO_FAILED` | 500 | 发布视频内容失败 | +| `LIST_FEEDS_FAILED` | 500 | 获取 Feeds 列表失败 | +| `SEARCH_FEEDS_FAILED` | 500 | 搜索 Feeds 失败 | +| `GET_FEED_DETAIL_FAILED` | 500 | 获取 Feed 详情失败 | +| `GET_USER_PROFILE_FAILED` | 500 | 获取用户主页信息失败 | +| `GET_MY_PROFILE_FAILED` | 500 | 获取当前用户信息失败 | +| `POST_COMMENT_FAILED` | 500 | 发表评论失败 | +| `REPLY_COMMENT_FAILED` | 500 | 回复评论失败 | +| `INTERNAL_ERROR` | 500 | 服务器内部错误 | + --- ## 注意事项