# 🎓 Python 小白完全指南
> 这份指南专门为 Python 初学者编写，会详细解释每一步操作。
## 📋 目录
1. [检查 Python 环境](#1-检查-python-环境)
2. [安装项目依赖](#2-安装项目依赖)
3. [配置豆包 API Key](#3-配置豆包-api-key)
4. [测试项目功能](#4-测试项目功能)
5. [在 Cursor 中配置和使用](#5-在-cursor-中配置和使用)
6. [常见问题解决](#6-常见问题解决)
---
## 1. 检查 Python 环境
### 步骤 1.1：检查是否安装了 Python
**Windows 用户：**
1. 按 `Win + R`，输入 `cmd`，按回车打开命令提示符
2. 输入以下命令，按回车：
```bash
python --version
```
**如果看到类似这样的输出，说明已安装：**
```
Python 3.10.11
```
**如果提示"不是内部或外部命令"：**
- 需要安装 Python
- 访问：https://www.python.org/downloads/
- 下载并安装（⚠️ 安装时勾选 "Add Python to PATH"）
### 步骤 1.2：确认 pip 可用
在命令提示符中输入：
```bash
pip --version
```
应该看到类似输出：
```
pip 23.2.1 from ...
```
---
## 2. 安装项目依赖
### 方法 A：使用安装脚本（推荐，最简单）
**Windows 用户：**
1. 打开项目文件夹：`D:\work\my-project\douyin_to_notion`
2. 双击运行 `install.bat`
3. 等待安装完成（会自动创建虚拟环境并安装依赖）
**安装完成后会自动打开 `.env` 文件让你配置 API Key**
### 方法 B：手动安装（如果脚本失败）
1. **打开命令提示符**
- 按 `Win + R`
- 输入 `cmd`，回车
2. **进入项目目录**
```bash
cd D:\work\my-project\douyin_to_notion
```
3. **创建虚拟环境**
```bash
python -m venv venv
```
> 💡 **解释**：虚拟环境是 Python 项目的独立空间，避免不同项目的依赖冲突
4. **激活虚拟环境**
```bash
venv\Scripts\activate
```
**成功后，你会看到命令提示符前面多了 `(venv)`**
```
(venv) D:\work\my-project\douyin_to_notion>
```
5. **安装依赖包**
```bash
pip install -e .
```
> 💡 **解释**：这会安装 `pyproject.toml` 中列出的所有依赖包
**等待安装完成，应该看到：**
```
Successfully installed mcp-1.0.0 httpx-0.27.0 python-dotenv-1.0.0 ...
```
---
## 3. 配置豆包 API Key
### 步骤 3.1：获取豆包 API Key
1. 访问：https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey
2. 登录你的火山引擎账号
3. 点击"创建 API Key"
4. 复制生成的 API Key（类似：`xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）
### 步骤 3.2：创建配置文件
1. **复制示例文件**
- 在项目文件夹中找到 `env.example` 文件
- 复制它，重命名为 `.env`（注意前面有个点）
2. **编辑 `.env` 文件**
用记事本或任何文本编辑器打开 `.env` 文件，你会看到：
```env
DOUBAO_API_KEY=your_api_key_here
DOUBAO_API_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3/chat/completions
DOUBAO_MODEL=doubao-1.5-vision-pro-32k
```
3. **替换 API Key**
把 `your_api_key_here` 替换成你刚才复制的实际 API Key：
```env
DOUBAO_API_KEY=你的真实API密钥
DOUBAO_API_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3/chat/completions
DOUBAO_MODEL=doubao-1.5-vision-pro-32k
```
4. **保存文件**
> ⚠️ **重要**：`.env` 文件包含敏感信息，不要分享给别人！
---
## 4. 测试项目功能
### 步骤 4.1：运行测试脚本
1. **确保虚拟环境已激活**
命令提示符应该显示 `(venv)`：
```
(venv) D:\work\my-project\douyin_to_notion>
```
如果没有，运行：
```bash
venv\Scripts\activate
```
2. **运行测试**
```bash
python test_example.py
```
3. **查看测试结果**
你会看到类似输出：
```
============================================================
抖音视频解析测试
============================================================
============================================================
测试 1: 链接提取功能
============================================================
✓ 口令文本提取成功：https://v.douyin.com/DGHl69ciWp4/
✓ 纯链接提取成功：https://v.douyin.com/DGHl69ciWp4/
⚠️ 注意: 测试 2 需要实际的抖音链接和网络连接
是否继续测试视频 URL 提取功能? (y/n):
```
4. **输入 `y` 继续测试**
如果一切正常，会显示：
```
✓ 视频 URL 获取成功
视频地址: https://v3-web.douyinvod.com/...
✓ 视频信息获取成功
时长: 10.2 秒
尺寸: 1080x1920
作者: Real机智张
```
**恭喜！🎉 如果看到这些，说明项目运行正常！**
---
## 5. 在 Cursor 中配置和使用
### 步骤 5.1：打开 Cursor 设置
1. 打开 Cursor
2. 点击左下角的设置图标（齿轮）⚙️
3. 或者按快捷键：`Ctrl + ,`
### 步骤 5.2：找到 MCP 配置
1. 在设置搜索框中输入 `MCP`
2. 找到 "MCP Servers" 或类似选项
3. 点击 "Edit in settings.json"
### 步骤 5.3：添加配置
在打开的 JSON 文件中添加以下内容：
```json
{
"mcpServers": {
"douyin-analyzer": {
"command": "python",
"args": ["-m", "src"],
"env": {
"DOUBAO_API_KEY": "你的豆包API密钥"
},
"cwd": "D:\\work\\my-project\\douyin_to_notion"
}
}
}
```
> ⚠️ **重要修改**：
> 1. 把 `你的豆包API密钥` 替换成实际的 API Key
> 2. 确认 `cwd` 路径正确（使用双反斜杠 `\\`）
### 步骤 5.4：保存并重启 Cursor
1. 保存配置文件（`Ctrl + S`）
2. 完全关闭 Cursor
3. 重新打开 Cursor
### 步骤 5.5：测试使用
在 Cursor 的聊天框中输入：
```
分析这个抖音视频：https://v.douyin.com/DGHl69ciWp4/
```
或者：
```
帮我看看这个抖音视频内容：0.05 09/23 https://v.douyin.com/DGHl69ciWp4/ 复制此链接
```
**如果配置成功，AI 会调用你的服务并返回视频分析结果！** 🎊
---
## 6. 常见问题解决
### ❌ 问题 1：`python` 不是内部或外部命令
**原因**：Python 未安装或未添加到系统 PATH
**解决**：
1. 重新安装 Python
2. 安装时勾选 "Add Python to PATH"
3. 或手动添加到环境变量
### ❌ 问题 2：`pip install` 很慢或失败
**原因**：网络连接慢或被墙
**解决**：使用国内镜像源
```bash
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple
```
### ❌ 问题 3：虚拟环境激活失败
**错误信息**：`无法加载文件 venv\Scripts\Activate.ps1，因为在此系统上禁止运行脚本`
**原因**：PowerShell 执行策略限制
**解决方法 1**：使用命令提示符（cmd）而不是 PowerShell
**解决方法 2**：临时允许执行脚本
```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```
### ❌ 问题 4：找不到 `.env` 文件
**原因**：文件名错误或隐藏
**解决**：
1. 确保文件名是 `.env`（前面有个点）
2. 在文件资源管理器中显示文件扩展名
3. 检查是否命名为 `.env.txt`（应该去掉 `.txt`）
### ❌ 问题 5：API Key 错误
**错误信息**：`未设置豆包 API Key`
**解决**：
1. 确认 `.env` 文件在项目根目录
2. 确认文件内容格式正确
3. 确认 API Key 没有多余的空格或引号
### ❌ 问题 6：Cursor 中无法调用
**可能原因**：
1. MCP 配置路径错误
2. API Key 未设置
3. Cursor 未重启
**检查清单**：
- [ ] `cwd` 路径是否正确？
- [ ] 路径中的反斜杠是否使用双反斜杠 `\\`？
- [ ] `DOUBAO_API_KEY` 是否填写？
- [ ] 是否重启了 Cursor？
### ❌ 问题 7：抖音 API 调用失败
**错误信息**：`无法从 API 响应中提取视频 URL`
**可能原因**：
1. 抖音链接已过期
2. 抖音 API 服务不可用
3. 网络连接问题
**解决**：
1. 尝试使用新的抖音链接
2. 检查网络连接
3. 稍后重试
---
## 🎯 快速命令参考
### 激活虚拟环境
```bash
# Windows
venv\Scripts\activate
# 停用虚拟环境
deactivate
```
### 运行测试
```bash
python test_example.py
```
### 直接运行 MCP 服务器
```bash
python -m src
```
### 重新安装依赖
```bash
pip install -e . --force-reinstall
```
---
## 📞 获取帮助
如果遇到问题：
1. **查看错误信息**：仔细阅读红色的错误提示
2. **检查配置**：确认 `.env` 文件和 MCP 配置正确
3. **查看文档**：参考 `README.md` 中的常见问题
4. **提交 Issue**：如果还是无法解决，可以提交问题
---
## ✅ 成功标志
你应该能够：
- ✅ 运行 `python test_example.py` 并看到测试通过
- ✅ 在 Cursor 中使用自然语言调用服务
- ✅ 成功获取视频分析结果
**恭喜你完成设置！🎉**
---
## 💡 调试技巧
### 查看详细错误信息
如果遇到错误，可以这样查看详细信息：
```bash
python test_example.py 2>&1 | more
```
### 检查包是否安装成功
```bash
pip list
```
应该看到：
- mcp
- httpx
- python-dotenv
### 验证环境变量
在 Python 中测试：
```bash
python
```
然后输入：
```python
from dotenv import load_dotenv
import os
load_dotenv()
print(os.getenv('DOUBAO_API_KEY'))
```
应该打印出你的 API Key（如果不为 None 说明配置成功）
输入 `exit()` 退出 Python
---
**祝你使用愉快！如有问题随时询问。** 😊
