快速开始

创建 Agent 密钥

登录红薯盒子 → 设置页 → API 密钥 → 选择「Agent」类型 → 创建

设置环境变量

export XHSBOX_KEY="xhsbox_agent_xxxx_xxxx"
export XHSBOX_BASE="https://xhsbox.leolan.top"

开始调用

curl -s -H "Authorization: Bearer $XHSBOX_KEY" \
  "$XHSBOX_BASE/api/agent/notes?search=美食&limit=5"

认证

所有请求需要在 Header 中携带 Agent 密钥：

Authorization: Bearer xhsbox_agent_xxxx_xxxx

⚠️ 需要会员权限才能使用 Agent API。

API 端点

GET/api/agent/notes

搜索和列出笔记

search搜索关键词（匹配标题、摘要、标签、作者）

contentType内容类型筛选：my_note、favorite_note、my_album、favorite_collection、all

limit返回数量，默认 20，最大 100

cursor分页游标（从上次响应的 nextCursor 获取）

GET/api/agent/notes/{id}

获取单篇笔记的完整详情

GET/api/agent/stats

获取收藏库统计信息（总数、各类型数量）

POST/api/agent/ai/analyze

AI 分析单篇笔记，返回核心要点、质量评分、关键词

{ "noteId": "xxx" }

POST/api/agent/ai/analyze-album

AI 分析整个专辑或分类中的所有笔记

albumId专辑 ID（和 classificationId 二选一）

classificationId分类 ID（和 albumId 二选一）

question你想了解的问题

modelId可选，指定 AI 模型

{ "albumId": "xxx", "question": "总结核心主题" }

POST/api/agent/ai/classify

AI 自动分类笔记

{ "noteIds": ["id1", "id2"] }  // 空数组或不传 = 全部

GET/api/agent/classifications

获取 AI 分类结果列表

GET/api/agent/models

获取可用的 AI 模型列表（非会员仅显示免费模型）

响应格式

成功

{
  "ok": true,
  "data": { ... },
  "meta": { "count": 10, "nextCursor": "..." }
}

失败

{
  "ok": false,
  "error": "VIP membership required",
  "code": "MEMBERSHIP_REQUIRED"
}

MCP Server (Claude Desktop)

在 Claude Desktop 的 MCP 配置中添加：

{
  "mcpServers": {
    "xhsbox": {
      "url": "https://xhsbox.leolan.top/api/mcp",
      "headers": {
        "Authorization": "Bearer 你的Agent密钥"
      }
    }
  }
}

可用工具：list_notes、get_note、get_stats、analyze_album、list_classifications、list_models

Claude Code Skill

在 Claude Code 中一键安装：

/install-skill https://xhsbox.leolan.top/skills/xhsbox-agent.md

安装后 Claude Code 将自动了解如何调用红薯盒子 API。