# 快速参考指南
## 一分钟快速启动
```bash
# 1. 进入项目目录
cd xiaohongshu-python
# 2. 运行设置脚本
bash setup.sh
# 3. 启动服务
source venv/bin/activate
python main.py
```
访问 `http://localhost:18060/docs` 查看 API 文档。
## 常用命令
### 开发命令
```bash
# 使用 Makefile
make setup # 设置环境
make install # 安装依赖
make run # 运行服务
make dev # 开发模式（非无头）
make test # 运行测试
make clean # 清理文件
make format # 格式化代码
make lint # 代码检查
```
### Docker 命令
```bash
make docker-build # 构建镜像
make docker-up # 启动容器
make docker-down # 停止容器
make docker-logs # 查看日志
```
## API 端点速查
### 登录相关
```bash
# 检查登录状态
GET /api/v1/login/status
# 获取登录二维码
GET /api/v1/login/qrcode
# 删除 cookies
DELETE /api/v1/login/cookies
```
### Feed 相关
```bash
# 获取 Feed 列表
GET /api/v1/feeds/list
# 搜索内容
POST /api/v1/feeds/search
{
"keyword": "搜索关键词",
"filters": {}
}
# 获取 Feed 详情
POST /api/v1/feeds/detail
{
"feed_id": "xxx",
"xsec_token": "xxx",
"load_all_comments": false
}
```
### 评论相关
```bash
# 发表评论
POST /api/v1/feeds/comment
{
"feed_id": "xxx",
"xsec_token": "xxx",
"content": "评论内容"
}
# 回复评论
POST /api/v1/feeds/comment/reply
{
"feed_id": "xxx",
"xsec_token": "xxx",
"comment_id": "xxx",
"content": "回复内容"
}
```
### 用户相关
```bash
# 获取用户主页
POST /api/v1/user/profile
{
"user_id": "xxx",
"xsec_token": "xxx"
}
```
### 发布相关
```bash
# 发布图文
POST /api/v1/publish
{
"title": "标题",
"content": "内容",
"images": ["path1", "path2"],
"tags": ["标签1", "标签2"]
}
# 发布视频
POST /api/v1/publish_video
{
"title": "标题",
"content": "内容",
"video_path": "path",
"cover_path": "path",
"tags": ["标签1"]
}
```
## MCP 工具速查
| 工具名 | 功能 | 参数 |
|--------|------|------|
| `check_login_status` | 检查登录状态 | 无 |
| `get_login_qrcode` | 获取登录二维码 | 无 |
| `delete_cookies` | 删除 cookies | 无 |
| `list_feeds` | 获取 Feed 列表 | 无 |
| `search_feeds` | 搜索内容 | keyword, filters |
| `get_feed_detail` | 获取 Feed 详情 | feed_id, xsec_token, load_all_comments |
| `post_comment_to_feed` | 发表评论 | feed_id, xsec_token, content |
| `reply_comment_in_feed` | 回复评论 | feed_id, xsec_token, comment_id, content |
| `like_feed` | 点赞/取消点赞 | feed_id, xsec_token, action |
| `favorite_feed` | 收藏/取消收藏 | feed_id, xsec_token, action |
| `user_profile` | 获取用户主页 | user_id, xsec_token |
| `publish_content` | 发布图文 | title, content, images, tags |
| `publish_with_video` | 发布视频 | title, content, video_path, cover_path, tags |
## 环境变量速查
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `HOST` | 服务器地址 | `0.0.0.0` |
| `PORT` | 服务器端口 | `18060` |
| `HEADLESS` | 无头模式 | `true` |
| `BROWSER_BIN_PATH` | 浏览器路径 | 自动 |
| `COOKIES_PATH` | Cookie 路径 | `./data/cookies.json` |
| `LOG_LEVEL` | 日志级别 | `INFO` |
## 目录结构速查
```
xiaohongshu-python/
├── xiaohongshu/ # 业务逻辑
├── browser/ # 浏览器管理
├── cookies/ # Cookie 管理
├── configs/ # 配置管理
├── errors/ # 错误处理
├── tests/ # 测试文件
├── data/ # 数据目录（运行时创建）
├── images/ # 图片目录（运行时创建）
├── logs/ # 日志目录（运行时创建）
├── main.py # 主程序
├── service.py # 服务层
├── mcp_server.py # MCP 服务器
├── routes.py # HTTP 路由
└── app_server.py # 应用服务器
```
## 调试技巧速查
### 1. 非无头模式
```bash
HEADLESS=false python main.py
```
### 2. 调试日志
```bash
LOG_LEVEL=DEBUG python main.py
```
### 3. Playwright Inspector
```bash
PWDEBUG=1 python main.py
```
### 4. 查看页面截图
```python
await page.screenshot(path="debug.png")
```
### 5. 打印页面 HTML
```python
html = await page.content()
print(html)
```
## 常见问题速查
### Q: 如何修改端口？
```bash
# 方法 1：修改 .env
PORT=18061
# 方法 2：环境变量
PORT=18061 python main.py
```
### Q: 如何查看日志？
```bash
# 实时日志
tail -f logs/xiaohongshu_*.log
# Docker 日志
docker-compose logs -f
```
### Q: 如何重置 Cookie？
```bash
# 删除 Cookie 文件
rm data/cookies.json
# 或调用 API
curl -X DELETE http://localhost:18060/api/v1/login/cookies
```
### Q: 如何更新依赖？
```bash
pip install --upgrade -r requirements.txt
playwright install chromium
```
## 文档速查
| 文档 | 说明 |
|------|------|
| `README.md` | 项目概述和使用指南 |
| `IMPLEMENTATION_GUIDE.md` | 详细实现指南 |
| `PROJECT_SUMMARY.md` | 项目总结 |
| `CHECKLIST.md` | 验证清单 |
| `QUICK_REFERENCE.md` | 本文档 |
## 相关链接
- **Playwright 文档**: https://playwright.dev/python/
- **FastAPI 文档**: https://fastapi.tiangolo.com/
- **Pydantic 文档**: https://docs.pydantic.dev/
- **MCP 文档**: https://modelcontextprotocol.io/
## 获取帮助
```bash
# 查看 Makefile 帮助
make help
# 查看 Python 帮助
python main.py --help
# 查看 API 文档
# 访问 http://localhost:18060/docs
```
---
**提示**：将此文档保存为书签，方便快速查阅！
