# AI 识别课件时设置 PDF 页码(找目录 + 偏移量) ## 问题背景 daily-lesson 课程设置页的 AI 按钮 ai-001「自动识别课程附件」调本机 Claude Code,通过每日课 MCP 给视频课挂课件。最近三次运行(`daily-lesson/backend/data/ai-runs/`)都没有设页码: - MCP `add_course_wares` 的 items 只有 title、uri、hostOverride,不能带 pageNo;页码只能事后逐个 `save_course_ware`。 - agent 用 Claude Code 的 Read 打开 PDF 时报错 `pdftoppm is not installed`,看不到 PDF 页面,于是按「确定了才设」全部留空。 - 样例书 `Phonics/res/1.books_notebooks_audio-video/3/Oxford_Phonics_World_3_SB.pdf` 是扫描版:105 页,没有文字层、书签和页码标签。目录在第 2、4 页(第 3 页是书名页),Unit 1 印刷页 4 对应 PDF 第 6 页(已有课件 197 的 pageNo=6),偏移 +2。 ## 用户对话整理 看看课程添加附件的 mcp 是不是不支持页码?新加的 AI 识别课件功能调用 claude code 好像都没传页码。 页码需要分割 pdf 找到目录,并根据目录和对应页内容增加偏移量(pdf 前几页通常带封面、扉页、目录等,所以要偏移 + 页码指向 pdf 文件的真实页码)。 为了节省资源,pdf 转图片时可以尝试 480p、720p、1080p(并裁剪上半截)以找到目录,再分别看看能否找到目录,找到后再完整解析目录内容。 ## 后续任务步骤 1. `add_course_wares`(以及 HTTP `POST /courses/node/{id}/wares`)的 items 支持 pageNo;uri 重复且原来页码是 0 时补上页码。 2. 新增 MCP 工具:`get_pdf_info`(页数、书签、页码标签、有无文字层)、`get_pdf_text`(文字层)、`render_pdf_pages`(按 480/720/1080 高度和 top/bottom/full 裁剪转 JPEG 图片返回)。 3. MCP 结果支持图片 content。 4. backend 依赖加 PyMuPDF,装进 `.venv`。 5. 改 `prompt/ai-001.md`:每本 PDF 先找目录、算偏移、核对,再按「印刷页码 + 偏移」设 pageNo;不要用 Read 打开 PDF。 6. 补测试,更新 mcp-api.md、http-api.md、README。 ## 规划 - 渲染、读字、找目录的「看」交给 agent,后端只提供切页转图和读字的工具,不在后端判断哪页是目录。 - height 指整页图片高度(480p = 整页高 480 像素),crop=top 时图片只留上半页,高度减半。 - 每次调用限制页数和总像素,避免 MCP 结果超出 Claude Code 的输出上限。 - 已有课件只补缺:页码为 0 的可以补,不改已有页码。 ## 说明 - 结论:`add_course_wares` 原来确实不收页码(MCP schema 不允许多余字段,后端模型也会忽略 pageNo),页码只能事后逐个 `save_course_ware`;同时 agent 看不到 PDF 页面(Read 要 pdftoppm),所以三次运行都没设页码。 - 已做:`add_course_wares` / HTTP 加课件支持 pageNo,返回多了 `paged`;新增 `get_pdf_info`、`get_pdf_text`、`render_pdf_pages`(`app/agent/mcp_pdf.py`、`app/service/pdf.py`);提示词 ai-001 写了找目录、算偏移、核对的步骤;requirements 加 `PyMuPDF>=1.24,<3`,已装进 `.venv`(装上的是 2.1)。 - 验证:后端 42 个测试通过;对运行中的 8160 直接调工具,12 页 480p 上半页一次约 290KB、0.15 秒;本机 `claude -p` 调 `render_pdf_pages` 能看到图片,读出第 3 页目录 Unit 1 → 4、Unit 2 → 12,第 5 页是 Unit 1 开头页。 - 样例书实测:SB 第 2 页是书名页,目录在第 3、4 页;Unit 1 印刷页 4 在 PDF 第 5 页,偏移 +1(第 6 页页脚印的是 5)。课件 197(U1 第 01 课)现有 SB pageNo=6,对应印刷页 5,不是单元开头页,需要用户确认。WB 没核对。 - 上次加的 96 个课件(nodeId 213–260)页码都是 0,再在这个文件夹上跑一次 AI 按钮会按同 uri 补页码。 - `app/agent/__init__.py` 被仓库 `.gitignore` 的 `__init__.py` 规则忽略,docstring 改动只留在本地。 - 风险:Claude Code 对 MCP 图片也算 `MAX_MCP_OUTPUT_TOKENS`(默认 25000),所以每次限 12 页、400 万像素。