⚠️ MCP 鉴权策略（按需检测 → 连接器配置 → OAuth → 设备码流兜底）

Step 0：连接器存在性检测（按需检查，不主动写配置）

重要原则：不要主动写入 ~/.workbuddy/mcp.json！ 这是 WorkBuddy 的配置文件，agent 无权操作；即使写入也需要重启 WorkBuddy 才生效。 正确做法是 按需检测 + 用户引导。

检测方式

隐式检测（首选）：

• 调用任意 MCP 工具（如 check_auth_status），如果返回结果说明连接器已配置
• 如果返回「找不到工具」「连接失败」「MCP 服务器不可达」等错误 → 连接器可能未配置

显式检测（兜底）：

• 让用户去 WorkBuddy「专家」->「技能」->「连接器」查看是否能看到 xsd-mcp
• 如果看不到 → 连接器未配置，需要引导用户添加

如果连接器不存在 → 引导用户添加（不要 agent 写入）

告诉用户按以下步骤添加（不要 agent 自动写文件）：

1. 打开 WorkBuddy「专家」->「技能」->「连接器」
2. 点击「自定义连接器」（或「添加」按钮）
3. 填入以下配置：
   • 名称：xsd-mcp
   • URL：https://ai.shudingkj.com/mcp
   • 传输协议：streamable-http
   • 超时：1800（秒）
4. 保存（WorkBuddy 通常会自动加载新配置，可能需要重启）

完整 JSON 格式（供参考）：

{
  "mcpServers": {
    "xsd-mcp": {
      "url": "https://ai.shudingkj.com/mcp",
      "transport": "streamable-http",
      "timeout": 1800
    }
  }
}

添加完成后让用户重新发起请求，agent 再继续后续鉴权流程。

如果连接器已配置但未信任 → 进入 Step 1 OAuth 流程

Step 1：OAuth 优先（WorkBuddy 自动完成）

如果连接器存在但首次连接：

1. 打开 「专家」->「技能」->「连接器」；
2. 点击 「自定义连接器」；
3. 找到 xsd-mcp 这一项；
4. 点击 「信任」（首次连接）或 「重链」（圆形循环符号，已连接但失效时）重新建立连接。

WorkBuddy 会自动完成 OAuth 30 天持久化（refresh_token），首次验证后 30 天内免认证。

认证方式对比（用户体验一致）

两种方式用户体验完全一致：都是首次验证后 30 天内免认证。区别在于触发方式。 优先尝试 OAuth，仅在 OAuth 真的无法完成时回退到设备码流。

🔑 OAuth 实在无法完成？设备码流 fallback（最后兜底，体验等价 OAuth）

何时用：调用 check_auth_status 一直返回 authenticated: false，且 auth_method 是 none/bearer_token（token 失效） 而 WorkBuddy 客户端始终无法把有效 token 传给 MCP 调用。

⚠️ Agent 行为约束（必读）

禁止行为（会浪费时间且无效）：

• ❌ 反复调用 check_auth_status 看结果
• ❌ 直接读取/调用 oauth_client.py、OAuth HTTP API
• ❌ 读 mcp.json、反复"读取 MCP 配置"
• ❌ 用 curl/http_get 直接探测 OAuth 端点
• ❌ 告诉用户"请在 WorkBuddy 信任 xsd-mcp"（用户已经做了，无效）
• ❌ 反复让用户"重新点击信任连接器"

正确行为：

• ✅ 看到 authenticated: false 且 auth_method: "none" → 立即调 start_login
• ✅ 把 verification_url 以链接形式直接发给用户，让用户点开
• ✅ 用户验证后调 check_auth_status(device_code="...") 拿到 30 天 JWT
• ✅ 必须把 device_token 告知 WorkBuddy 缓存（下次调用带 Authorization: Bearer 即可免认证）

设备码流完整流程

Step 1：调用 mcp__xsd-mcp__start_login（公开免鉴权）

• 返回 verification_url（如 https://ai.shudingkj.com/device/verify?code=XXXX）
• 返回 device_code（如 E88CjUhoZwwV7T68zhB4Xyb9BjscfkHx）
• 返回 expires_in（600 秒，设备码本身 10 分钟过期）

Step 2：把 verification_url 以 Markdown 链接形式发给用户（直接发）：

🔑 **一键启用 xsd-mcp**：[点击这里完成验证](verification_url)
（点开后输入手机号 + 短信验证码，10 秒搞定。绑定后 30 天内免再验证，进程重启也不丢失。）

Step 3：等待用户在浏览器完成验证（不需要轮询，让用户告诉「验证好了」即可）

Step 4：用户告知后立即调用：

mcp__xsd-mcp__check_auth_status(device_code="<上一步返回的 device_code>")

返回结构：

• authenticated: true 且 auth_method: device_long_lived_token
• device_token ← 关键：30 天有效的 JWT，客户端必须缓存
• device_token_expires_in: 2592000（30 天 × 86400 秒）
• device_token_usage_hint: 提示用法

Step 5：告诉 WorkBuddy 缓存 device_token，后续 MCP 调用带上：

Authorization: Bearer 

• WorkBuddy 重启不影响（自己缓存即可）
• MCP server 重启不影响（JWT 自带签名校验）
• 30 天内免认证（与 OAuth refresh_token 等价）

Step 6：继续发起错题本/视频搜索等请求

device_token 持久化机制

• JWT RS256 签名：服务端用 RSA 私钥签名，客户端无需联网即可验证
• payload：{sub: user_id, exp: now+30days, scope: "cuoti", type: "device_long_lived"}
• 客户端缓存策略：WorkBuddy 应在本地存储 device_token，每次 MCP 调用时作为 Authorization: Bearer header 带上
• 过期前续签：用户可在 token 即将过期时（28 天后）重新走一次设备码流刷新

为什么设备码流体验等价 OAuth：

设备码流额外优势：

• 不依赖客户端 OAuth 实现（WorkBuddy 不需要支持 OAuth 发现/回调）
• 不需要 OAuth 动态注册/refresh_token 等复杂握手
• 触发方式更可控（agent 主动调 start_login）

核心架构：路径 A 与路径 B 真正并行，路径 C 依赖 A3

优化重点（v3.1）：路径 A 和路径 B 是真正并行启动，不是"边讲边启动 B"。 agent 应在阶段 0 题号确认后，同时启动路径 A（A1 多模态识别）和路径 B（B1 鉴权 + B2 配额）。 路径 B1-B4 完全不依赖路径 A 的输出（讲解内容），可与 A1-A4 并行穿插执行。 路径 C 必须等 A3 完成（需要从讲解中提取核心知识点），因此在 A3 后启动。

时间线示意

阶段 0: 题号确认（必须先完成，B 需要题号）
  │
  ├─ 并行启动 ──────────────────────────────────────────────────┐
  │                                                              │
  ├─ 路径 A（主线）                                               │
  │   ├─ A1 多模态识别题目 ─┐                                     │
  │   ├─ A2 题号确认 ──────┤ (与 B3 上传图片 并行)                │
  │   ├─ A3 深度讲解 ──────┐                                     │
  │   └─ A4 生成可视化 ────┤ (与 B4 发起 PDF、B5 轮询 并行)       │
  │                                                              │
  ├─ 路径 B（副线·并行）                                          │
  │   ├─ B1 鉴权检查 ──── 与 A1 并行                            │
  │   ├─ B2 配额检查 ──── 与 A1 并行                            │
  │   ├─ B3 上传图片 ────── 与 A2 并行                          │
  │   ├─ B4 发起 PDF（async）─ 与 A3 并行，秒返 task_id          │
  │   └─ B5 轮询 ─────────── 与 A4 并行，穿插等待                │
  │                                                              │
  └─ 路径 C（依赖 A3）────────────────────────────────────────────┘
      ├─ C1 提取核心知识点（A3 完成后启动）
      └─ C2 调用 search_knowledge_videos（C1 后立即启动）

关键原则：

• 路径 A 是主线，agent 应先开始 A1 多模态识别（不依赖任何前置）
• 路径 B 的 B1-B4 完全不依赖 A 的输出，阶段 0 后立即与 A1 并行启动
• B4 发起 PDF 是异步任务（秒返 task_id），不阻塞后续步骤
• B5 轮询穿插在 A4 生成可视化期间（不需要等 A 完成）
• 路径 C 必须等 A3 完成（需要从讲解中提取知识点），其他步骤在 A3 后启动
• 最终呈现三个产物：可视化 HTML + 错题本 PDF + 视频推荐

agent 实际行为

# 阶段 0: 题号确认（必须串行）
problem_number = confirm_question_number(user_message, identified_problems)

# 阶段 1: 并行启动 A 和 B
# agent 应该**同时**发起这两个调用（不是先 A 后 B）
in_parallel(
    # 路径 A 主线
    task_A1_A2_A3_A4(),  # 多模态识别 → 题号确认 → 深度讲解 → 生成可视化

    # 路径 B 副线
    task_B1_auth(),       # 鉴权
    task_B2_quota(),      # 配额
    task_B3_upload(),     # 上传图片（需要题号）
    task_B4_submit(),     # 发起 PDF 生成（异步，返回 task_id）
)

# 路径 B5：穿插在 A4 期间轮询
poll_pdf_task(task_id)  # 不阻塞 A4

# 路径 C：A3 完成后启动
task_C1_extract_keywords(),  # 从 A3 讲解中提取知识点
task_C2_search_videos(),     # 搜索视频

MCP 工具参考

以下全部工具属于 xsd-mcp 服务器。路径 A（讲题+可视化）由 WorkBuddy 自身能力完成，路径 B（错题本 PDF）和路径 C（B站视频搜索）使用 MCP 工具。

MCP 客户端认证配置

两种方式用户体验一致（都是 30 天免认证）：

对 agent 的要求：

• 优先 OAuth：让 WorkBuddy 走标准 OAuth 流程（"信任连接器"按钮），30 天免认证
• 设备码流兜底：仅在 OAuth 实在无法完成时使用。详见上方「🔑 OAuth 实在无法完成？设备码流 fallback」章节

完整工作流

阶段 0：接收用户请求

当用户发送题目图片并请求讲解/整理错题时，进入以下流程。

快速判断：

• 用户只说了"整理错题"/"生成错题本" -> 可以只走路径 B
• 用户说了"讲题"/"讲解"/"这道题怎么做" -> 必须走路径 A + B + C（三线）
• 用户没有明确指定 -> 默认三线并行（讲题 + 错题本 + 视频推荐）
• 用户给了图片但没说题号 -> 先走 A1 识别，再走 A2 澄清

阶段 0 的关键作用： 阶段 0 完成后，必须明确知道：

1. 题号（如"第3题"）——路径 B3（上传）和 B4（发起 PDF）需要
2. 科目（数学/物理）——路径 B4 需要
3. 题型（是否需要可视化）——路径 A4 需要

⚠️ 题号必须先确定，否则路径 B 无法发起 PDF 生成。题号确认后立即并行启动 A 和 B。 如果用户没指定题号，先弹出选择框（用 ask_followup_question）让用户选择，不要阻塞太久。 一旦题号确认，同时启动 A1 和 B1-B2（不要等 A 完成再启动 B）。

路径 A（主线）：智能讲题 + 可视化 HTML

路径 A 不依赖 MCP 工具，完全由 WorkBuddy 自身多模态 + 代码生成能力完成。

A1. 多模态识别题目

使用 WorkBuddy 自身的多模态视觉能力直接观察用户上传的图片：

1. 识别图片中共有几道题，每道题的题号、科目（数学/物理）、题型
2. 列出题目清单：[题号] 科目 - 简要描述
3. 如果图片中题目有手写批改痕迹（红笔✓/✗），一并识别

⚠️ 不要用 MCP 工具做题目识别。MCP 的 extract_questions 用于生成 PDF 时的文字提取， 不适用于实时讲题场景。实时讲题直接用 WorkBuddy 视觉能力。

A2. 确认用户需求

根据用户消息判断：

• 用户已指定题号（如"讲一下第3题"）-> 直接进入 A3
• 用户未指定题号 -> 弹出选择框让用户选择要讲解的题目。使用 ask_followup_question 工具，格式如下：

  {
    "questions": "[{"id":"q_select","question":"我看到图片中有以下题目，你想让我讲解哪道？","options":["第1题 - 数学 - [简要描述]","第2题 - 物理 - [简要描述]","第3题 - 数学 - [简要描述]","全部讲解"],"multiSelect":false}]"
  }
  

  • options 中每一项格式为 第X题 - 科目 - 简要描述
  • 最后一个选项固定为 全部讲解
  • multiSelect 设为 false（单选）
  • 用户选择后根据结果进入 A3（选"全部讲解"则逐题讲解）
• 图片中只有一道题 -> 无需询问，直接进入 A3

A3. 深度讲解

对目标题目进行完整讲解，覆盖：

1. 知识点定位：该题考察的核心知识点
2. 审题分析：已知条件、隐含条件、求解目标
3. 解题思路：逻辑推导链条，为什么这样解
4. 分步解答：每一步的计算/推理过程
5. 答案与验证：最终答案，验证方法
6. 易错点提示：常见错误和避坑指南

讲解风格：教师口语化，逻辑清晰，适当使用 Markdown 排版公式（LaTeX 风格，如 $F=ma$、$angle ABC$）。

🔗 A3 完成后立即启动路径 C：从讲解中提取核心知识点（如"二次函数与一次函数交点个数"）， 调用 search_knowledge_videos 搜索B站相关讲解视频。

A4. 生成可视化动态讲解 HTML

讲解完成后，根据题目类型生成交互式 HTML 可视化页面。

判断科目类型：

• 几何、函数、方程、不等式、坐标几何 -> 数学可视化（-> references/math-visualization.md）
• 力学、电学、磁学、光学、波动、热学 -> 物理可视化（-> references/physics-visualization.md）
• 其他（如纯代数计算）-> 可跳过可视化，仅文字讲解

可视化生成的核心要求：

• 单文件 HTML，CSS/SVG/JavaScript 全部内联，零外部依赖
• 内联 SVG + const steps = [...] 状态机驱动（标题/讲解/公式/SVG 显隐/高亮）
• 数学 36 步，物理 37 步，每步一个核心观察点
• 所有 SVG 元素预绘制在 中，JS 只负责切换显隐
• 禁止 Canvas、MathJax/KaTeX、外部库、eval、动态创建 SVG
• SVG 使用固定 viewBox，标签间距 ≥ 40px 防重叠，各区域垂直排列不混叠
• 文字区/公式区用独立
  + 背景色 + 内边距，与 SVG 区域分离

📘 详细规范见 reference 文件：

• 数学：references/math-visualization.md（步骤设计、SVG 模式、色彩规范、模板、自检清单）
• 物理：references/physics-visualization.md（同上 + 临界点识别、复杂场景简化策略）

输出方式：

• 将 HTML 写入 /mnt/user-data/outputs/ 目录（文件名如 math_visual_题号.html）
• 不要在聊天中输出原始 HTML 代码（会污染上下文）
• 写入文件后告诉用户"可视化讲题页面已生成，可打开查看"

路径 B（副线 · 与 A 真正并行）：错题本 PDF 生成

路径 B 使用 MCP 工具。关键：路径 B 与路径 A 真正并行——

• B1（鉴权）和 B2（配额）只依赖 user_id，阶段 0 后立即与 A1（多模态识别）并行启动
• B3（上传图片）依赖题号，与 A2（题号确认）并行
• B4（发起 PDF）是异步任务，秒返 task_id，与 A3（讲解）并行
• B5（轮询）穿插在 A4（生成可视化）期间，不阻塞 A

绝对不要等 A 完成后才启动 B，那样会浪费 B1-B4 几分钟的执行时间。

B1. 鉴权检查（第一步）：分两步（连接器检测 + 鉴权状态）

Step 1：连接器存在性检测（按需检查，不要主动写 mcp.json）

调用 mcp__xsd-mcp__check_auth_status：

• 工具调用成功（即使返回 authenticated: false）→ 连接器已配置，进入 Step 2
• 工具调用失败（找不到工具 / 连接失败 / 找不到 xsd-mcp 服务器）→ 连接器未配置：
  • 不要 agent 写入 mcp.json（agent 无权操作 WorkBuddy 配置文件）
  • 引导用户手动添加：

    请在 WorkBuddy 中添加 xsd-mcp 连接器（一次配置，长期使用）：
    - 名称：xsd-mcp
    - URL：https://ai.shudingkj.com/mcp
    - 传输协议：streamable-http
    - 超时：1800 秒
    

  • 用户添加后让用户重新发起请求，再继续后续流程
  • 路径 A 继续执行（不受连接器配置影响）

Step 2：检查鉴权状态（连接器已配置时）

连接器存在后，调用 mcp__xsd-mcp__check_auth_status。

• authenticated: true -> 继续 B2

• authenticated: false ->

  • 检查 auth_method 字段判断走哪个 fallback：
    • auth_method: "none" 且 WorkBuddy 信任连接器已确认打开 → 走设备码流 （详见 SKILL 开头「🔑 OAuth 实在无法完成？设备码流 fallback」章节）
    • auth_method: "bearer_token" 但用户仍报"未登录" → token 已过期，让 WorkBuddy 重新走 OAuth
    • 若 WorkBuddy 完全无法完成 OAuth 流程 → 设备码流
  • 设备码流 5 步（关键：必须拿到 30 天 JWT 并让 WorkBuddy 缓存）：
    1. 调 mcp__xsd-mcp__start_login 获取 verification_url
    2. 把链接发给用户，让用户点开完成手机号验证
    3. 用户告知后调 mcp__xsd-mcp__check_auth_status(device_code="...")
    4. 从响应中提取 device_token（30 天 JWT）
    5. 告诉 WorkBuddy 缓存 device_token，后续调用带 Authorization: Bearer 即可在 30 天内免认证（与 OAuth refresh_token 等价）

  绝对不要：

  • 反复探测 OAuth HTTP API / 读 mcp.json / 调 oauth_client.py
  • 让用户在 WorkBuddy 中"重新信任连接器"（用户可能已做过，无效）
  • 忽略 device_token 不缓存（否则每次都要重新走设备码流）

  路径 A 继续执行（不受鉴权影响）。

常见错误区分：

• 「找不到 xsd-mcp 服务器」→ 连接器未配置 → Step 1 处理
• 「未登录 / 401」→ 鉴权问题 → Step 2 处理
• 「MCP 服务器不可达」→ 网络问题 → 告知用户稍后重试，路径 A 继续

B2. 配额检查

调用 mcp__xsd-mcp__get_usage_summary。

• 剩余 0 -> 告知用户"本月配额已用完，错题本 PDF 无法生成"，路径 A 继续
• 剩余 < 3 -> 提示用户确认后继续
• 充足 -> 继续 B3

B3. 上传图片

• 用户提供了 OSS/公网图片链接 -> 调用 mcp__xsd-mcp__upload_image(image_url=...)
• 用户上传了本地文件（最常见） ->
  1. 调用 mcp__xsd-mcp__get_upload_ticket(ext="jpg") 获取 put_url + oss_url
  2. 用 curl -X PUT -T <本地文件路径> "" 直传到 OSS
  3. 上传成功后，用返回的 oss_url 作为图片链接

⚠️ put_url 预签名凭证 1 小时有效。PUT 时不要手动添加 Content-Type 请求头。

B4. 发起异步 PDF 生成

调用 mcp__xsd-mcp__batch_extract_and_pdf：

batch_extract_and_pdf(
    requests=[{
        "image_urls": [<题图 OSS 链接>],
        "question": "<题号，如 '第3题'>",
        "subject": "<科目：数学 / 物理>",
    }],
    title="<科目>错题本",
    subject="<科目>",
)

• 返回 task_id（异步任务，不会同步等结果）

B5. 轮询任务状态（与 A4 穿插执行）

循环调用 mcp__xsd-mcp__get_task_status(task_id=task_id)，间隔 3~5 秒， 直到 status 变为 done 或 failed：

• done -> 获取 download_url / pdf_url
• failed -> 反馈 error 给用户

⚠️ 轮询穿插在 A4 期间（不要阻塞路径 A）：

• 路径 A4 生成可视化期间，每次回答用户问题/讲解步骤之间插入一次轮询
• 不要等 A 全部完成才轮询（浪费并行机会）
• 路径 A 完成后如果 PDF 还未好，继续轮询直至完成
• 最终呈现时把 PDF 链接和视频列表一起给用户

路径 C（副线 · 异步并行）：B站视频推荐

路径 C 使用 MCP 工具搜索B站讲解视频。在路径 A 的 A3（深度讲解）完成后立即启动路径 C。

C1. 提取核心知识点

从 A3 的讲解内容中提取该题目的核心知识点关键词。

知识点提取要点：

• 提取 1-3 个核心知识点，组成搜索关键词
• 关键词应具体、有教学价值，如"二次函数与一次函数交点个数"、"相似三角形判定"、"受力分析正交分解"
• 避免过于宽泛（如只写"数学"）或过于具体（如照抄整道题）

示例：

• 题目考查二次函数 y=ax²+bx+c 与直线 y=kx+m 的交点个数 -> 知识点：二次函数与一次函数交点个数
• 题目考查相似三角形证明 -> 知识点：相似三角形判定与证明
• 题目考查斜面上物体受力分析 -> 知识点：斜面受力分析正交分解法

C2. 调用视频搜索工具

调用 mcp__xsd-mcp__search_knowledge_videos：

search_knowledge_videos(
    keyword="<核心知识点，如 '二次函数与一次函数交点个数'>",
    subject="<科目：数学 / 物理>",
    count=3,
)

返回结构：

{
  "success": true,
  "keyword": "二次函数与一次函数交点个数",
  "total_candidates": 15,
  "filter_note": "已按粉丝≥50万的大UP筛选后综合排序",
  "videos": [
    {
      "rank": 1,
      "title": "初中数学【二次函数】从零基础到中考压轴难度合集",
      "author": "一数",
      "fans": 24940000,
      "fans_display": "2494.0万",
      "play": 1234567,
      "play_display": "1,234,567",
      "duration": 3600,
      "duration_display": "1:00:00",
      "url": "https://www.bilibili.com/video/BV1t54y1173m",
      "relevance_score": 3,
      "chapters": ["第3讲 二次函数、方程与不等式"],
      "chapter_hint": "重点看：第3讲 二次函数、方程与不等式"
    }
  ],
  "learning_order": [
    "1. 先看《一数》... -> 体系打基础",
    "2. 先看《马哥初中几何》... -> 专攻本题型",
    "3. 先看《马哥初中几何》... -> 补变式/拔高"
  ]
}

• 搜索耗时约 5-15 秒（多策略检索 + 粉丝校验 + 排序）
• 如果返回 success: false，告知用户视频搜索暂不可用，不影响其他路径

⚠️ 路径 C 不消耗配额（cost=0），但不绕过鉴权。 如果鉴权失败（路径 B 的 B1 已检测），路径 C 同样不可用，路径 A 继续执行。

最终呈现（路径 A + B + C 汇合）

并行执行的好处：三线并行启动后，总耗时 = max(A, B) + C 启动延迟，而不是 A + B + C。 用户实际等待时间 = 路径 A 完成时间（A4 生成可视化通常最慢，约 30-60 秒）。 路径 B 的 PDF 生成和路径 C 的视频搜索都是后端异步任务，不阻塞用户。

三条线全部完成后，合并呈现结果：

📚 题目讲解已完成！

📖 **文字讲解**：[已完成]


🎬 **可视化动态讲解**：[已生成，可打开 HTML 文件查看]
   - 包含 X 步交互式动画，逐步展示推理/物理过程
   - 使用上一步/下一步按钮切换


📄 **错题本 PDF**：⬇️ 点击下载（24h 有效）
   [📄 错题本PDF下载](download_url)


📺 **B站推荐讲解视频**：

1. 一数《初中数学【二次函数】从零基础到中考压轴难度合集》
   链接：https://www.bilibili.com/video/BV1t54y1173m
   重点看第 3 讲「二次函数、方程与不等式」（交点个数就靠联立+判别式 Δ），第 7 讲顺带讲 x 轴交点。

2. 马哥初中几何《二次函数与直线交点分布大合辑》
   链接：https://www.bilibili.com/video/BV1GUAwefEKC
   最直接对口：标题就是「二次函数与直线（=一次函数图像）交点」，系统讲 0/1/2 个交点的判定与分类讨论。

3. 马哥初中几何《二函与直线交点问题与任意直线》
   链接：https://www.bilibili.com/video/BV1bWDzYtEJs
   补充带参数（k、m）的变式，应对中考压轴。

学习顺序建议：先看成体系的一数第 3 讲打基础 -> 再用马哥第 2 个专攻「交点个数」题型 -> 有余力看第 3 个补含参变式。

如果路径 B 或 C 失败（鉴权/配额/网络问题），只呈现可用的产物， 并说明不可用部分的原因。不要让 B/C 的失败阻塞 A。 视频推荐结果应基于 search_knowledge_videos 返回的数据格式化呈现， 包含：序号、标题、链接、重点章节提示、学习顺序建议。

特殊场景处理

仅整理错题（不讲解）

用户明确说"整理错题"/"生成错题本"而不需要讲解 -> 只走路径 B。

图片中有多道题，用户指定一道讲解

• 路径 A 只讲解指定题目
• 路径 B 生成全部题目的错题本 PDF
• 路径 C 只搜索指定题目的知识点视频
• 告知用户："已针对第X题进行讲解，同时错题本包含了图片中所有题目"

图片中有多道题，用户要求全部讲解

• 路径 A 逐题讲解并生成可视化（每题独立 HTML）
• 路径 B 生成全部题目的错题本 PDF
• 路径 C 为每道题分别搜索知识点视频（或合并核心知识点一次搜索）
• 每题讲解完成后展示可视化链接

路径 B/C 工具不可用

如果 MCP 工具调用持续失败（连接不上/工具未找到）：

先区分是连接器配置问题还是鉴权问题：

• 工具找不到 / 找不到 xsd-mcp 服务器 → 连接器未配置（按 SKILL 开头「Step 0 连接器存在性检测」处理，引导用户手动添加）
• 工具返回 401 / 未登录 → 鉴权问题（按 SKILL 开头「Step 1 OAuth」或「设备码流」处理）
• MCP 服务器不可达（HTTP 错误） → 网络问题，告知用户稍后重试

路径 A 始终继续执行不受影响。

告知用户：

当前无法连接 MCP 服务（原因：xxx），已为你完成题目讲解。 如需错题本 PDF 或视频推荐，请按以下步骤处理：[具体步骤]

配额消耗

免费用户每月 10 点。路径 A（讲题+可视化）和路径 C（视频搜索）不消耗 MCP 配额。 完整流程最多消耗 1 点（仅 PDF 生成）。

限制

• 支持数学、物理等科目的题目讲解与错题整理
• 题号格式：第12题、第13,14题
• 每次最多 2 页图片
• 返回 quota_exceeded 时提示配额已用完（不影响讲题和视频搜索）
• B站视频搜索依赖B站 API 可用性，偶发限流时会返回失败