# Claude Code 项目指南
## 项目概述
这是一个**小红书 MCP 服务器的 Python 实现**，从 Go 版本完整重构而来。项目提供了完整的小红书自动化功能，包括登录、浏览、互动和发布等。
**核心技术栈**：
- FastAPI（Web 框架）
- Playwright（浏览器自动化）
- MCP Python SDK（Model Context Protocol）
- Pydantic（数据验证）
- Loguru（日志）
## 项目结构
```
xiaohongshu-python/
├── xiaohongshu/ # 核心业务逻辑包
│ ├── types.py # Pydantic 数据模型定义
│ ├── navigate.py # 页面导航（探索页、个人主页）
│ ├── login.py # 登录功能（二维码登录、状态检查）
│ ├── feeds.py # Feed 列表获取
│ ├── search.py # 搜索功能
│ ├── feed_detail.py # Feed 详情获取
│ ├── comment_feed.py # 评论和回复功能
│ ├── like_favorite.py # 点赞和收藏功能
│ ├── user_profile.py # 用户主页信息
│ ├── publish.py # 图文发布（已完成）
│ └── publish_video.py # 视频发布（骨架）
│
├── browser/ # 浏览器管理
│ └── browser.py # Playwright 浏览器封装
│
├── cookies/ # Cookie 管理
│ └── cookies.py # Cookie 加载、保存、删除
│
├── configs/ # 配置管理
│ └── settings.py # 环境变量和配置
│
├── errors/ # 错误处理
│ └── errors.py # 自定义异常类
│
├── service.py # 业务服务层（整合所有 Action）
├── mcp_server.py # MCP 服务器（13 个工具）
├── routes.py # HTTP REST API 路由
├── app_server.py # FastAPI 应用服务器
├── main.py # 主程序入口
│
├── tests/ # 测试文件
│ └── testread.md # 测试内容示例
│
├── test_images/ # 测试图片
│
├── cookies.json # Cookie 存储（运行时生成）
├── storage_state.json # Playwright 存储状态（运行时生成）
├── server.log # 服务器日志（运行时生成）
├── server.pid # 服务器进程 ID（运行时生成）
│
├── requirements.txt # Python 依赖
├── .env # 环境变量配置
├── .env.example # 环境变量示例
├── Dockerfile # Docker 镜像配置
├── docker-compose.yml # Docker Compose 配置
└── README.md # 项目文档
```
## 关键文件说明
### 核心业务模块
#### `xiaohongshu/types.py`
定义所有数据模型（Pydantic BaseModel）：
- `FeedItem`：Feed 列表项
- `FeedDetail`：Feed 详情
- `Comment`：评论结构
- `UserProfile`：用户信息
- 等等
#### `xiaohongshu/publish.py` ⭐ 重点
**图文发布功能**，已完整实现并测试通过。
关键方法：
- `publish(title, content, images, tags)` - 主发布流程
- `_click_publish_tab(tabname)` - 点击发布 TAB（3 种回退方法）
- `_remove_all_overlays()` - 移除页面遮挡元素
- `_upload_images(image_paths)` - 上传图片
- `_submit_publish(title, content, tags)` - 提交发布
**重要实现细节**：
1. 发布页面默认是"上传视频" TAB，需要点击"上传图文" TAB
2. 页面可能有遮挡元素（`.d-popover`, `.modal`, `.dialog` 等），需要先移除
3. 使用 3 种回退方法点击 TAB：
- 方法 1：Playwright `has-text` 选择器
- 方法 2：JavaScript 强制点击（通常成功）
- 方法 3：遍历所有 TAB + 强制点击
4. 标签输入需要点击联想选项（`#creator-editor-topic-container .item`）
5. 需要检查标题和正文长度限制
#### `browser/browser.py`
浏览器管理器，封装 Playwright：
- `start()` - 启动浏览器
- `new_page()` - 创建新页面
- `save_cookies()` - 保存 Cookie
- `close()` - 关闭浏览器
**重要配置**：
- 支持 `storage_state.json` 持久化登录状态
- 支持自定义浏览器路径（`BROWSER_BIN_PATH`）
- 支持 headless/非 headless 模式
#### `service.py`
业务服务层，整合所有功能：
- 管理浏览器生命周期
- 提供统一的业务接口
- 处理页面创建和销毁
### API 层
#### `mcp_server.py`
MCP 服务器，注册 13 个工具：
1. `check_login_status` - 检查登录状态
2. `get_login_qrcode` - 获取登录二维码
3. `delete_cookies` - 删除 cookies
4. `list_feeds` - 获取 Feed 列表
5. `search_feeds` - 搜索内容
6. `get_feed_detail` - 获取 Feed 详情
7. `post_comment_to_feed` - 发表评论
8. `reply_comment_in_feed` - 回复评论
9. `like_feed` - 点赞/取消点赞
10. `favorite_feed` - 收藏/取消收藏
11. `user_profile` - 获取用户主页
12. `publish_content` - 发布图文内容 ⭐
13. `publish_with_video` - 发布视频内容
#### `routes.py`
HTTP REST API 路由，对应 MCP 工具。
访问 `http://localhost:18060/docs` 查看 Swagger UI 文档。
## 环境配置
### `.env` 文件
```bash
# 服务器配置
HOST=0.0.0.0
PORT=18060
# 浏览器配置
HEADLESS=false # 是否无头模式
BROWSER_BIN_PATH=/path/to/chrome # 自定义浏览器路径（可选）
# Cookie 配置
COOKIES_PATH=./cookies.json # Cookie 文件路径
# 日志配置
LOG_LEVEL=INFO # 日志级别
```
### Cookie 文件路径优先级
1. `/tmp/cookies.json`（向后兼容）
2. 环境变量 `COOKIES_PATH`
3. 当前目录 `cookies.json`
## 运行服务
### 本地运行
```bash
# 1. 激活虚拟环境
source venv/bin/activate
# 2. 启动服务
python main.py
# 服务将在 http://localhost:18060 启动
```
### 后台运行
```bash
# 启动
nohup python main.py > server.log 2>&1 &
echo $! > server.pid
# 停止
kill $(cat server.pid)
```
### Docker 运行
```bash
docker-compose up -d
docker-compose logs -f
docker-compose down
```
## 测试功能
### 测试发布功能
```bash
# 使用 curl 测试发布 API
curl -X POST http://localhost:18060/api/v1/publish \
-H "Content-Type: application/json" \
-d '{
"title": "测试标题",
"content": "测试内容",
"images": ["/path/to/image.jpg"],
"tags": ["标签1", "标签2"]
}'
```
### 测试脚本
项目包含多个测试脚本：
- `test_publish_dog.py` - 测试发布狗狗文章
- `test_features.py` - 测试各种功能
- `test_login.py` - 测试登录功能
- `quick_feed_test.py` - 快速测试 Feed 列表
## 常见问题
### 1. 登录问题
**问题**：服务重启后需要重新登录
**解决**：
- 确保 `storage_state.json` 文件存在
- 检查 Cookie 是否过期
- 使用 `one_time_login.py` 手动登录一次
### 2. 发布 TAB 点击失败
**问题**：`没有找到发布 TAB - 上传图文`
**解决**：
- 已在 `publish.py` 中实现 3 种回退方法
- 使用 `_remove_all_overlays()` 移除遮挡元素
- 如果仍然失败，检查页面结构是否变化
### 3. 图片上传失败
**问题**：图片路径不存在或格式不支持
**解决**：
- 确保图片路径是绝对路径
- 检查图片文件是否存在
- 支持的格式：JPG, PNG, WEBP
### 4. 浏览器启动失败
**问题**：`playwright._impl._api_types.Error: Executable doesn't exist`
**解决**：
```bash
playwright install chromium
playwright install-deps chromium
```
## 开发指南
### 添加新功能
1. 在 `xiaohongshu/` 创建新模块（如 `new_feature.py`）
2. 在 `service.py` 添加对应方法
3. 在 `mcp_server.py` 注册 MCP 工具
4. 在 `routes.py` 添加 HTTP 端点
### 调试技巧
1. **使用非 headless 模式**：
```bash
HEADLESS=false python main.py
```
2. **使用 Playwright Inspector**：
```python
await page.pause() # 在代码中添加断点
```
3. **查看日志**：
```bash
tail -f server.log
```
4. **截图调试**：
```python
await page.screenshot(path="debug.png")
```
### 页面选择器更新
如果小红书页面结构变化，需要更新 CSS 选择器：
1. 使用浏览器开发者工具检查元素
2. 更新对应模块中的选择器
3. 测试功能是否正常
## 项目状态
### ✅ 已完成
- 登录管理（二维码登录、状态检查）
- Feed 列表获取
- 图文发布功能（完整实现并测试通过）⭐
- MCP 服务器（13 个工具）
- HTTP API（12 个端点）
- Docker 部署
### 🔨 待完善
- 搜索功能（需要实现过滤器）
- Feed 详情（需要实现评论加载）
- 评论功能（需要测试）
- 点赞收藏（需要测试）
- 视频发布（需要实现上传逻辑）
## 重要提示
### 给 Claude Code 的建议
1. **修改代码前先阅读**：
- 使用 `Read` 工具查看文件内容
- 理解现有实现逻辑
- 避免破坏已有功能
2. **测试修改**：
- 修改后运行相关测试脚本
- 检查服务是否正常启动
- 验证功能是否正常工作
3. **保持一致性**：
- 遵循现有代码风格
- 使用 Pydantic 进行数据验证
- 使用 Loguru 记录日志
- 使用 async/await 异步编程
4. **处理错误**：
- 使用 try-except 捕获异常
- 记录详细的错误日志
- 返回有意义的错误信息
5. **页面自动化注意事项**：
- 等待页面加载完成（`wait_for_load_state`）
- 等待元素出现（`wait_for_selector`）
- 处理可能的遮挡元素
- 使用多种回退方法
## 联系方式
如有问题，请查看：
- `README.md` - 项目文档
- `PROJECT_SUMMARY.md` - 项目总结
- `IMPLEMENTATION_GUIDE.md` - 实现指南
- `server.log` - 运行日志
---
**最后更新**：2026-01-17
**项目状态**：✅ 核心功能完成，持续优化中
