docs/API.md

# API 文档

本文档详细描述了饭否 MCP 服务器提供的所有工具函数。

## 认证方式

### 环境变量方式（PyPI 包）
使用环境变量传递认证信息：
- `FANFOU_API_KEY` - 饭否应用的 API Key
- `FANFOU_API_SECRET` - 饭否应用的 API Secret  
- `FANFOU_OAUTH_TOKEN` - OAuth Token（推荐）
- `FANFOU_OAUTH_TOKEN_SECRET` - OAuth Token Secret（推荐）
- `FANFOU_USERNAME` - 饭否用户名（首次使用）
- `FANFOU_PASSWORD` - 饭否密码（首次使用）

### HTTP 头方式（SSE 服务）
使用 HTTP 头传递认证信息，支持多用户隔离：
- `X-Fanfou-Api-Key` - 饭否应用的 API Key
- `X-Fanfou-Api-Secret` - 饭否应用的 API Secret
- `X-Fanfou-OAuth-Token` - OAuth Token（推荐）
- `X-Fanfou-OAuth-Token-Secret` - OAuth Token Secret（推荐）
- `X-Fanfou-Username` - 饭否用户名（首次使用）
- `X-Fanfou-Password` - 饭否密码（首次使用）

## 认证相关

### generate_oauth_token

生成 OAuth Token

**功能:**
- 使用用户名密码生成 OAuth Token
- 用于后续免密登录，避免重复输入用户名密码

**前提条件:**
- 环境变量方式：需要设置 `FANFOU_USERNAME` 和 `FANFOU_PASSWORD` 环境变量
- HTTP 头方式：需要传递 `X-Fanfou-Username` 和 `X-Fanfou-Password` 头部

**返回:**
- 包含 OAuth Token 信息的字典
- 控制台会显示详细的 Token 信息和使用说明

## 时间线相关

### get_home_timeline

获取当前用户首页关注用户及自己的饭否时间线

**功能:**
- 调用饭否 API 的 /statuses/home_timeline.json 接口获取当前用户的首页时间线
- 包含用户关注的所有人的最新消息
- 注：通常用户询问「我的饭否」时，指的是该时间线，除非用户明确指出「某个用户的饭否」

**参数:**
- `count` (int, 可选): 获取数量，默认 5 条
- `max_id` (str, 可选): 返回列表中内容最新 ID，用于分页获取更早的内容

**返回:**
- 首页时间线列表，包含以下字段：
  - `饭否内容`: 饭否消息内容（HTML 格式）
    - 转发：以「转@」开头，后跟用户链接，如 `转@<a href="https://fanfou.com/~FgPOFSnmkW8" class="former">kingcos</a>`，其中 href 中的是用户 ID，inner Text 是被转发用户的显示名称，一条饭否可能有多个转发
    - 话题：以「#」包围，如 `#<a href="/q/%E6%AD%A3%E5%9C%A8%E6%92%AD%E6%94%BE">正在播放</a>#`，其中 q/ 后面的是话题名，一条饭否可能有多个话题
    - 审核状态：如果内容末尾显示「【审核中】」，表示该内容正在审核中
  - `发布 ID`: 消息的唯一标识符
  - `发布时间`: 消息发布时间
  - `发布者`: 发布者的用户名
  - `发布者 ID`: 发布者的用户 ID
  - `图片链接`: 如果包含图片，则提供图片链接

### get_user_timeline

根据用户 ID 获取某个用户发表内容的时间线

**功能:**
- 调用饭否 API 的 /statuses/user_timeline.json 接口获取指定用户的时间线
- 当提供搜索关键词时，会调用 /search/user_timeline.json 接口进行搜索

**参数:**
- `user_id` (str, 可选): 用户 ID，如果为空则获取当前用户时间线
- `max_id` (str, 可选): 返回列表中内容最新 ID，用于分页获取更早的内容
- `count` (int, 可选): 获取数量，默认 5 条
- `q` (str, 可选): 搜索关键词，如果为空则获取普通用户时间线；如果不为空则搜索该用户包含该关键词的消息

**返回:**
- 用户时间线列表，包含以下字段：
  - `饭否内容`: 饭否消息内容（HTML 格式）
    - 转发：以「转@」开头，后跟用户链接，如 `转@<a href="https://fanfou.com/~FgPOFSnmkW8" class="former">kingcos</a>`，其中 href 中的是用户 ID，inner Text 是被转发用户的显示名称，一条饭否可能有多个转发
    - 话题：以「#」包围，如 `#<a href="/q/%E6%AD%A3%E5%9C%A8%E6%92%AD%E6%94%BE">正在播放</a>#`，其中 q/ 后面的是话题名，一条饭否可能有多个话题
    - 审核状态：如果内容末尾显示「【审核中】」，表示该内容正在审核中
  - `发布 ID`: 消息的唯一标识符
  - `发布时间`: 消息发布时间
  - `发布者`: 发布者的用户名
  - `发布者 ID`: 发布者的用户 ID
  - `图片链接`: 如果包含图片，则提供图片链接

### get_public_timeline

获取公开时间线

**功能:**
- 调用饭否 API 的 /statuses/public_timeline.json 接口获取饭否全站最新的公开消息
- 这些是所有用户可见的公开饭否内容
- 当提供搜索关键词时，会调用 /search/public_timeline.json 接口进行搜索

**参数:**
- `count` (int, 可选): 获取数量，默认 5 条
- `max_id` (str, 可选): 返回列表中内容最新 ID，用于分页获取更早的内容
- `q` (str, 可选): 搜索关键词，如果为空则获取普通公开时间线；如果不为空则搜索包含该关键词的公开消息

**返回:**
- 公开时间线列表，包含以下字段：
  - `饭否内容`: 饭否消息内容（HTML 格式）
    - 转发：以「转@」开头，后跟用户链接，如 `转@<a href="https://fanfou.com/~FgPOFSnmkW8" class="former">kingcos</a>`，其中 href 中的是用户 ID，inner Text 是被转发用户的显示名称，一条饭否可能有多个转发
    - 话题：以「#」包围，如 `#<a href="/q/%E6%AD%A3%E5%9C%A8%E6%92%AD%E6%94%BE">正在播放</a>#`，其中 q/ 后面的是话题名，一条饭否可能有多个话题
    - 审核状态：如果内容末尾显示「【审核中】」，表示该内容正在审核中
  - `发布 ID`: 消息的唯一标识符
  - `发布时间`: 消息发布时间
  - `发布者`: 发布者的用户名
  - `发布者 ID`: 发布者的用户 ID
  - `图片链接`: 如果包含图片，则提供图片链接

## 用户和内容相关

### get_user_info

获取用户信息

**功能:**
- 调用饭否 API 的 /users/show.json 接口获取指定用户的详细信息
- 如果 user_id 为空，则获取当前登录用户的信息

**参数:**
- `user_id` (str, 可选): 用户 ID，如果为空则获取当前用户信息

**返回:**
- 用户信息字典，包含以下字段：
  - `用户 ID`: 用户的唯一标识符
  - `用户名`: 用户名
  - `位置`: 用户所在位置
  - `性别`: 用户性别
  - `生日`: 用户生日
  - `描述`: 用户个人描述
  - `头像`: 用户头像链接
  - `链接`: 用户个人网站链接
  - `是否加锁`: 账号是否受保护
  - `粉丝数`: 被关注数量
  - `朋友数`: 互相关注数量
  - `收藏数`: 收藏的消息数量
  - `发布数`: 发布的消息数量
  - `照片数`: 发布的照片数量
  - `是否关注`: 当前用户是否关注该用户
  - `注册时间`: 账号注册时间
  - `最新状态`: 用户最新发布的消息信息（包含发布时间、发布 ID、发布内容）

### get_status_info

获取某条饭否内容的具体信息

**功能:**
- 调用饭否 API 的 /statuses/show/id.json 接口获取指定饭否内容的详细信息

**参数:**
- `status_id` (str, 必需): 饭否内容的 ID

**返回:**
- 饭否内容的详细信息字典，包含以下字段：
  - `饭否内容`: 消息文本内容（HTML 格式）
    - 转发：以「转@」开头，后跟用户链接，如 `转@<a href="https://fanfou.com/~FgPOFSnmkW8" class="former">kingcos</a>`，其中 href 中的是用户 ID，inner Text 是被转发用户的显示名称，一条饭否可能有多个转发
    - 话题：以「#」包围，如 `#<a href="/q/%E6%AD%A3%E5%9C%A8%E6%92%AD%E6%94%BE">正在播放</a>#`，其中 q/ 后面的是话题名，一条饭否可能有多个话题
    - 审核状态：如果内容末尾显示「【审核中】」，表示该内容正在审核中
  - `发布 ID`: 消息的唯一标识符
  - `发布时间`: 消息发布时间
  - `发布者`: 发布者的显示名称
  - `发布者 ID`: 发布者的用户 ID
  - `是否收藏`: 当前用户是否收藏了该消息
  - `是否是自己`: 是否是当前用户发布的消息
  - `发布位置`: 消息发布的地理位置
  - `回复信息`: 如果是回复消息，包含被回复的状态 ID、用户 ID 和用户名
  - `图片链接`: 如果包含图片，则提供图片链接

## 互动相关

### manage_favorite

管理饭否内容的收藏状态

**功能:**
- 调用饭否 API 的 /favorites/create/id.json 或 /favorites/destroy/id.json 接口
- 可以收藏或取消收藏指定的饭否内容
- 内置二次确认机制，防止误操作
- **重要：AI助手不能自动确认操作，必须等待用户明确指示**

**参数:**
- `status_id` (str, 必需): 饭否内容的 ID
- `action` (str, 必需): 操作类型，"create" 表示收藏，"destroy" 表示取消收藏
- `confirm` (bool, 可选): 是否确认操作，默认为 False

**返回:**
**首次调用时（confirm=False）:**
- 确认信息字典，包含以下字段：
  - `需要确认`: 是否需要用户确认
  - `内容预览`: 要操作的内容预览（最多50字）
  - `发布时间`: 内容的发布时间
  - `发布 ID`: 内容的 ID
  - `发布者`: 内容的发布者
  - `当前收藏状态`: 当前的收藏状态
  - `操作类型`: 要执行的操作（收藏/取消收藏）
  - `⚠️ 重要提示`: 操作的提醒信息
  - `确认提示`: 如何进行确认的说明
  - `🚫 绝对禁止`: AI助手不能自动确认的提醒

**确认操作时（confirm=True）:**
- 操作结果字典，包含以下字段：
  - `是否收藏`: 操作后的收藏状态
  - `操作结果`: 操作是否成功的描述信息
  - `操作类型`: 执行的具体操作（收藏/取消收藏）

**使用流程:**
1. 首次调用：`manage_favorite("status_id", "action")` - 显示内容预览和确认提示
2. **用户必须明确表示要操作**：用户看到预览后，必须明确说"确认收藏"或"确认取消收藏"
3. 确认操作：只有在用户明确确认后，AI才会调用 `manage_favorite("status_id", "action", confirm=True)`

**安全机制:**
- 🛡️ **双重保护**：首次调用只显示预览，不执行操作
- 🚫 **AI限制**：AI助手被明确禁止自动确认操作
- 👤 **用户控制**：只有用户明确表示要操作时，AI才会执行
- ⚠️ **状态检查**：自动检查当前收藏状态，避免重复操作

### manage_friendship

管理用户关注状态

**功能:**
- 调用饭否 API 的 /friendships/create.json 或 /friendships/destroy.json 接口
- 可以关注或取消关注指定用户
- 在执行关注操作前，会先调用 get_user_info 查询目标用户信息
- 智能处理受保护账号的关注申请
- 内置二次确认机制，防止误操作
- **重要：AI助手不能自动确认操作，必须等待用户明确指示**

**参数:**
- `user_id` (str, 必需): 目标用户的 ID
- `action` (str, 必需): 操作类型，"create" 表示关注，"destroy" 表示取消关注
- `confirm` (bool, 可选): 是否确认操作，默认为 False

**返回:**
**首次调用时（confirm=False）:**
- 确认信息字典，包含以下字段：
  - `需要确认`: 是否需要用户确认
  - `用户预览`: 要操作的用户预览信息（用户名、用户ID、是否受保护、粉丝数、发布数、个人描述）
  - `当前关注状态`: 当前的关注状态
  - `操作类型`: 要执行的操作（关注/取消关注）
  - `⚠️ 重要提示`: 操作的提醒信息
  - `特殊情况`: 如果是受保护账号，会包含相关提示
  - `确认提示`: 如何进行确认的说明
  - `🚫 绝对禁止`: AI助手不能自动确认的提醒

**确认操作时（confirm=True）:**
- 操作结果字典，包含以下字段：
  - `是否关注`: 操作后的关注状态
  - `操作结果`: 操作是否成功的描述信息
  - `操作类型`: 执行的具体操作（关注/取消关注/关注申请）
  - `用户信息`: 目标用户的基本信息（用户名、用户ID、是否受保护）
  - `特殊情况`: 如果是受保护账号的关注申请，会包含相关提示

**使用流程:**
1. 首次调用：`manage_friendship("user_id", "action")` - 显示用户预览和确认提示
2. **用户必须明确表示要操作**：用户看到预览后，必须明确说"确认关注"或"确认取消关注"
3. 确认操作：只有在用户明确确认后，AI才会调用 `manage_friendship("user_id", "action", confirm=True)`

**安全机制:**
- 🛡️ **双重保护**：首次调用只显示预览，不执行操作
- 🚫 **AI限制**：AI助手被明确禁止自动确认操作
- 👤 **用户控制**：只有用户明确表示要操作时，AI才会执行
- ⚠️ **状态检查**：自动检查当前关注状态，避免重复操作

**特殊情况:**
- 当目标用户账号受保护（protected）时，关注操作将变为申请关注
- 系统会自动检测并处理这种情况，返回相应的提示信息
- 申请关注需要对方确认后才能生效

## 发布相关

### publish_status

发布饭否内容（仅文字）

**功能:**
- 调用饭否 API 的 /statuses/update.json 接口发布纯文字内容
- 支持最多140字的文字内容发布
- 内置二次确认机制，防止误发布
- **重要：AI助手不能自动确认发布，必须等待用户明确指示**

**参数:**
- `status` (str, 必需): 要发布的文字内容（最多140字）
- `confirm` (bool, 可选): 是否确认发布，默认为 False

**返回:**
**首次调用时（confirm=False）:**
- 确认信息字典，包含以下字段：
  - `需要确认`: 是否需要用户确认
  - `内容预览`: 要发布的内容预览
  - `字数统计`: 当前字数和限制（如：50/140）
  - `操作类型`: 发布饭否
  - `⚠️ 重要提示`: 发布的提醒信息
  - `确认提示`: 如何进行确认的说明
  - `🚫 绝对禁止`: AI助手不能自动确认的提醒

**确认发布时（confirm=True）:**
- 发布结果字典，包含以下字段：
  - `发布 ID`: 新发布消息的唯一标识符
  - `发布时间`: 消息发布时间
  - `发布结果`: 发布是否成功的描述信息
  - `重要提示`: 关于审核的提醒信息

**使用流程:**
1. 首次调用：`publish_status("内容")` - 显示内容预览和确认提示
2. **用户必须明确表示要发布**：用户看到预览后，必须明确说"确认发布"或类似的话
3. 确认发布：只有在用户明确确认后，AI才会调用 `publish_status("内容", confirm=True)`

**安全机制:**
- 🛡️ **双重保护**：首次调用只显示预览，不执行发布
- 🚫 **AI限制**：AI助手被明确禁止自动确认发布
- 👤 **用户控制**：只有用户明确表示要发布时，AI才会执行
- ⚠️ **内容验证**：自动进行字数统计和内容验证

**注意事项:**
- 发布成功后需要等待审核才能在时间线中显示
- 内容不能为空且不能超过140字
- 系统会自动进行内容验证
- **AI助手绝对不会自动执行发布操作**

### publish_photo

发布饭否内容（文字+图片）

**功能:**
- 调用饭否 API 的 /photos/upload.json 接口发布带图片的内容
- 支持文字+单张图片的组合发布（最多一张图片）
- 支持从网络 URL 自动下载图片
- 内置二次确认机制，防止误发布
- **重要：AI助手不能自动确认发布，必须等待用户明确指示**

**参数:**
- `status` (str, 必需): 要发布的文字内容（最多140字）
- `photo_url` (str, 必需): 图片的网络 URL 地址
- `confirm` (bool, 可选): 是否确认发布，默认为 False

**返回:**
**首次调用时（confirm=False）:**
- 确认信息字典，包含以下字段：
  - `需要确认`: 是否需要用户确认
  - `内容预览`: 要发布的内容预览
  - `字数统计`: 当前字数和限制（如：50/140）
  - `图片链接`: 图片的 URL 地址
  - `操作类型`: 发布带图片的饭否
  - `⚠️ 重要提示`: 发布的提醒信息
  - `URL 提示`: 图片 URL 格式检查结果
  - `确认提示`: 如何进行确认的说明
  - `🚫 绝对禁止`: AI助手不能自动确认的提醒

**确认发布时（confirm=True）:**
- 发布结果字典，包含以下字段：
  - `发布 ID`: 新发布消息的唯一标识符
  - `发布时间`: 消息发布时间
  - `发布结果`: 发布是否成功的描述信息
  - `重要提示`: 关于审核的提醒信息

**使用流程:**
1. 首次调用：`publish_photo("内容", "图片URL")` - 显示内容和图片预览以及确认提示
2. **用户必须明确表示要发布**：用户看到预览后，必须明确说"确认发布"或类似的话
3. 确认发布：只有在用户明确确认后，AI才会调用 `publish_photo("内容", "图片URL", confirm=True)`

**安全机制:**
- 🛡️ **双重保护**：首次调用只显示预览，不执行发布
- 🚫 **AI限制**：AI助手被明确禁止自动确认发布
- 👤 **用户控制**：只有用户明确表示要发布时，AI才会执行
- ⚠️ **内容验证**：自动进行字数统计、内容验证和图片URL检查

**支持的图片格式:**
- JPEG: `https://example.com/image.jpg`
- PNG: `https://example.com/image.png`
- GIF: `https://example.com/image.gif`
- BMP: `https://example.com/image.bmp`
- WebP: `https://example.com/image.webp`

**注意事项:**
- 发布成功后需要等待审核才能在时间线中显示
- 文字内容不能为空且不能超过140字
- 图片下载后大小不能超过5MB
- 系统会自动从 URL 下载图片并上传到饭否
- 支持 HTTP 和 HTTPS 协议
- 下载超时时间为30秒
- 系统会自动检测图片的 MIME 类型
- **AI助手绝对不会自动执行发布操作**

### delete_status

删除饭否内容

**功能:**
- 调用饭否 API 的 /statuses/destroy.json 接口删除指定的饭否内容
- 只能删除自己发布的内容
- 内置二次确认机制，防止误删
- **重要：AI助手不能自动确认删除，必须等待用户明确指示**

**参数:**
- `status_id` (str, 必需): 要删除的饭否内容的 ID
- `confirm` (bool, 可选): 是否确认删除，默认为 False

**返回:**
**首次调用时（confirm=False）:**
- 确认信息字典，包含以下字段：
  - `需要确认`: 是否需要用户确认
  - `内容预览`: 要删除的内容预览（最多50字）
  - `发布时间`: 内容的发布时间
  - `发布 ID`: 内容的 ID
  - `⚠️ 重要警告`: 删除操作的警告信息
  - `确认提示`: 如何进行确认的说明
  - `🚫 绝对禁止`: AI助手不能自动确认的提醒

**确认删除时（confirm=True）:**
- 删除结果字典，包含以下字段：
  - `删除 ID`: 被删除消息的 ID
  - `删除结果`: 删除是否成功的描述信息
  - `重要提示`: 关于删除操作的提醒信息

**使用流程:**
1. 首次调用：`delete_status("status_id")` - 显示内容预览和确认提示
2. **用户必须明确表示要删除**：用户看到预览后，必须明确说"确认删除"或类似的话
3. 确认删除：只有在用户明确确认后，AI才会调用 `delete_status("status_id", confirm=True)`

**安全机制:**
- 🛡️ **双重保护**：首次调用只显示预览，不执行删除
- 🚫 **AI限制**：AI助手被明确禁止自动确认删除操作
- 👤 **用户控制**：只有用户明确表示要删除时，AI才会执行删除
- ⚠️ **警告提示**：每次都会显示删除不可逆的警告

**注意事项:**
- 只能删除自己发布的饭否内容
- 删除操作不可逆，请谨慎操作
- 删除成功后，内容将立即从时间线中消失
- 需要提供准确的饭否内容 ID
- 系统会自动检查内容所有权，非本人内容无法删除
- 内容预览会自动移除HTML标签，便于阅读
- **AI助手绝对不会自动执行删除操作**