1. 课件生成里最容易被忽略的一环：PPT 文案额外描述
如果你在用 Codex 做教学中心的课件生成，大概率遇到过这种场景：教案分镜已经排好了，但每一页 PPT 的讲解侧重点、风格要求、课堂补充说明，每次都要手动敲一遍。今天想让学生"多举生活例子"，明天想"突出公式推导过程"，后天又要"加一道随堂练习"——这些要求散落在各个分镜行里，改一次要翻半天。
TeachingCenter 里的LessonPlanAdditional就是来解决这个问题的。它本质上是一个"额外要求库"：教师把常用的风格、结构、讲解侧重点沉淀成可复用的模板，PPT 教案分镜在生成时通过GetAdditionalList拉取这些模板，选中后自动回填到分镜行的additionalTitle和additional字段。适合谁？适合正在用 Codex 开发教学模块、或者想优化自己课件生成流程的教师和开发者。
这篇文章不讲空泛的架构，直接给你可复制的config.toml骨架、TaoToken 统一 Key 的接入步骤，以及验证额外描述是否真正生效的检查动作。字段、接口、页面结构都基于真实源码，Codex 拿到就能干活。
2. 前置准备：TaoToken 统一 Key 接入
在让 Codex 生成课件之前，先把模型调用通道打通。TaoToken 提供统一的 API Key，一个 Key 可以走模型对话、Coding Plan 和接入文档里列出的多种能力，省得你在多个平台之间来回切换配置。
2.1 获取 API Key
打开控制台创建 Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。创建后复制那串sk-开头的字符串，后面config.toml里要用。
注意：Key 只显示一次，建议创建后立刻存到本地密码管理器，别直接提交到 Git 仓库。
2.2 确认接入端点
TaoToken 的 API 基础地址是 https://taotoken.net/api ，注意这个地址不带任何查询参数。模型对话、Coding Plan 相关的调用都走这个 base URL，具体路径在接入文档里有说明： https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
如果你用的是 Claude Code 这类编码工具，Anthropic 兼容层的配置方式可以参考： https://taotoken.net/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
2.3 环境变量方式（推荐）
比起把 Key 硬编码进配置文件，更稳妥的做法是走环境变量。Linux/macOS 下：
export TAOTOKEN_API_KEY="sk-你的Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"Windows PowerShell：
$env:TAOTOKEN_API_KEY="sk-你的Key" $env:TAOTOKEN_BASE_URL="https://taotoken.net/api"这样config.toml里只引用变量名，Key 不会跟着代码走。
3. 可复制的 config.toml 骨架
Codex 在生成课件时，需要知道用哪个模型、走哪个端点、额外描述从哪读。下面这份config.toml骨架可以直接抄，改掉注释里标出的部分即可。
# Codex 课件生成配置骨架 # 配合 TeachingCenter 的 LessonPlanAdditional 使用 [model] # 模型名称按你实际开通的填写 name = "claude-sonnet" # 从环境变量读取，避免硬编码 api_key = "${TAOTOKEN_API_KEY}" base_url = "${TAOTOKEN_BASE_URL}" # 课件生成建议温度低一些，保证结构稳定 temperature = 0.3 max_tokens = 4096 [teaching_center] # 额外描述库的接口前缀，与后端 ViewSet 对齐 additional_endpoint = "/api/TeachingCenter/LessonPlanAdditional/" # 分镜行回填字段，对应 storyboardAction 里的映射 additional_title_field = "additionalTitle" additional_content_field = "additional" # 拉取模板的方法名，前端 api.ts 里保持一致 fetch_method = "GetAdditionalList" [ppt_generation] # 生成时是否自动带上额外描述 inject_additional = true # 额外描述在提示词里的拼接位置 inject_position = "system_prompt_tail" # 单次生成最多注入几条模板，防止提示词过长 max_additional_items = 3 [logging] level = "info" # 记录每次注入的模板 id，方便排查是否生效 log_injected_ids = true几个关键点解释一下。additional_endpoint必须和后端LessonPlanAdditionalViewSet的路由前缀完全一致，否则GetAdditionalList会 404。inject_position控制额外描述拼到提示词的哪个位置，放在system_prompt_tail是为了让模型优先遵守这些补充要求，而不是被前面的通用指令冲淡。log_injected_ids打开后，每次生成都会在日志里打印实际注入的模板 id，这是后面验证是否生效的主要依据。
提示：
max_additional_items别设太大。我试过塞 8 条模板进去，结果模型开始忽略前面的分镜结构，只盯着最后几条要求写，反而把课件写散了。
4. 后端与前端的关键配置对齐
光有config.toml还不够，Codex 生成代码时得知道后端字段和前端映射长什么样。这部分直接决定额外描述能不能正确回填。
4.1 后端字段范围
LessonPlanAdditional模型本身字段很少，业务字段只有title和additional，其余creator_name、create_datetime、update_datetime来自CoreModel通用字段。Codex 生成表单时，创建者和时间字段不能让用户手动编辑，列表搜索可以保留creator_name。
后端LessonPlanAdditionalViewSet的http_method_names = ['get', 'post', 'put']，筛选字段包括creator_name、title、additional。注意源码里没有单独的 LLM 生成、OCR、导入导出或审批动作，LessonPlanAdditionalViewSetUtilsMixin只是保留扩展混入点，别让 Codex 凭空造出复杂服务。
4.2 前端映射关系
前端crud.tsx里renderAdditionalPopover负责长文本悬浮查看，列表列包含创建者、标题和额外描述，表单要求title和additional必填，额外描述用 textarea 多行输入。
真正的联动发生在LessonPlan/api.ts和storyboardAction/index.vue。GetAdditionalList请求/api/TeachingCenter/LessonPlanAdditional/，组件把返回值映射成{ id, title, content }，选择某个额外描述后写入分镜行的additionalTitle和additional。这个映射关系在config.toml里已经用additional_title_field和additional_content_field声明了，两边必须一致。
| 配置项 | config.toml 值 | 源码对应位置 |
|---|---|---|
| 接口前缀 | /api/TeachingCenter/LessonPlanAdditional/ | LessonPlanAdditional.py 路由 |
| 拉取方法 | GetAdditionalList | LessonPlan/api.ts |
| 标题回填字段 | additionalTitle | storyboardAction/index.vue |
| 内容回填字段 | additional | storyboardAction/index.vue |
| 长文展示 | popover | crud.tsx renderAdditionalPopover |
4.3 给 Codex 的配置约束 Prompt
把上面这些约束整理成一段 Prompt，Codex 生成时就不会跑偏：
请基于教育管理系统真实源码，为 PPT 文案额外描述模块生成配置与联动代码。 后端源码：server_backend/modules/TeachingCenter/models.py、views_app/LessonPlanAdditional.py、utils.py 前端源码：server_vue3/src/views/modules/TeachingCenter/LessonPlanAdditional/index.vue、api.ts、crud.tsx 模型对象：LessonPlanAdditional 字段范围：title、additional、creator_name、create_datetime、update_datetime 接口范围：/api/TeachingCenter/LessonPlanAdditional/ 扩展能力边界：数据联动 请生成 config.toml 骨架、api.ts 封装、storyboardAction 回填逻辑。 只允许使用源码中存在的字段、接口和页面状态，不要新增不存在的业务入口。5. 验证额外描述是否生效
配置写完不代表就生效了。下面这套检查动作，是我踩过坑之后总结出来的，按顺序走一遍基本能定位问题。
5.1 接口层验证
先用 curl 直接打后端接口，确认GetAdditionalList能返回数据：
curl -X GET "https://taotoken.net/api/TeachingCenter/LessonPlanAdditional/" \ -H "Authorization: Bearer ${TAOTOKEN_API_KEY}" \ -H "Content-Type: application/json"正常返回应该是一个包含title和additional的列表。如果返回 404，检查路由前缀；返回 401，检查 Key 是否过期；返回空数组，说明库里还没数据，先去页面新增一条。
5.2 前端回填验证
打开 LessonPlan 页面的分镜行，点击额外描述选择器，看下拉列表里有没有你刚新增的模板。选中后，检查分镜行的additionalTitle和additional是否被正确写入。这一步可以在浏览器控制台里直接看组件状态：
// 在 storyboardAction 组件里打印当前分镜行数据 console.log('additionalTitle:', this.additionalTitle) console.log('additional:', this.additional)如果additionalTitle有值但additional为空，多半是GetAdditionalList返回结构里字段名对不上，检查映射逻辑是不是把content写成了别的名字。
5.3 生成注入验证
这是最关键的一步。打开config.toml里的log_injected_ids = true，然后触发一次课件生成。在日志里搜索injected_ids，应该能看到本次实际注入的模板 id 列表。
# 查看最近一次生成的注入记录 grep "injected_ids" ./logs/codex-ppt.log | tail -n 1如果日志里injected_ids是空数组，说明inject_additional没生效或者模板没被选中。如果 id 有值但生成的 PPT 文案里看不到对应要求，那就是inject_position设错了，试试改成system_prompt_head再跑一次。
注意：验证时先用一条模板测试，别一上来就塞满
max_additional_items。单条能生效，再逐步加量，这样出问题容易定位。
6. 本篇常见错排查
6.1 GetAdditionalList 返回 404
最常见的原因是config.toml里的additional_endpoint和后端路由对不上。后端LessonPlanAdditionalViewSet注册在/api/TeachingCenter/LessonPlanAdditional/，注意结尾的斜杠不能少。另外确认urls.py里确实注册了这个 ViewSet，有时候 Codex 生成了视图但忘了加路由。
6.2 选中模板后分镜行没变化
先看storyboardAction/index.vue里的handleAdditionalSelect有没有被触发。可以在函数入口加一行console.log。如果没触发，是选择器的事件绑定问题；如果触发了但字段没变，检查additionalTitle和additional的赋值语句，别把title和content搞反了。
6.3 生成结果里看不到额外描述
按 5.3 的步骤查日志。如果injected_ids有值但文案没体现，可能是提示词拼接位置太靠前，被后面的分镜指令覆盖了。把inject_position改成system_prompt_tail，让额外描述紧贴生成指令。还有一种可能是max_tokens太小，额外描述把预算吃完了，分镜内容反而被截断，适当调大。
6.4 长文本在列表里显示不全
这是crud.tsx里renderAdditionalPopover的职责。如果悬浮查看没反应，检查 popover 组件有没有正确引入，以及additional字段有没有传进去。别直接把长文本塞进表格单元格，会撑破布局。
6.5 保存后回显丢失
检查保存载荷里有没有带上additionalTitle和additional。这两个字段是随 LessonPlan 分镜数据一起提交的，不是单独存到LessonPlanAdditional表里。如果保存接口只传了分镜 id 没传这两个字段，回显自然就丢了。
7. 继续把课件生成链路跑通
配置和验证都过了之后，如果你还想让 Codex 在课件生成上做更多事，比如批量生成分镜、自动补全讲解词，可以走 Coding Plan 把长期编码任务接起来： https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
需要新建或轮换 Key 的时候，控制台入口在这里： https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
想先手动试试模型对额外描述的理解效果，可以直接在模型对话里贴一段模板加一段分镜，看它怎么融合： https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
接入过程中如果遇到字段对不上、路由 404 这类问题，接入文档里有各模块的接口说明，对着查比盲猜快： https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
