文言文全流程教辅与口播生成系统

本项目旨在构建高准确率、高流畅度的文言文智能精讲、互动及口播教辅平台。针对目前系统在 TTS 多音字朗读错误、大模型输出不稳定与 Token 消耗偏高、Web 长任务易超时 以及 学习闭环深度不够 等痛点，特制定本实施计划表。

• TTS 读音准确率：多音字（如“还”、“度”、“舍”等）口播正确率提升至 100%。
• LLM JSON 成功率：引入 JSON Schema 后，结构化解析成功率达到 100%，彻底淘汰正则兜底。
• Prompt 成本与延迟：通过 RAG 预匹配削减 Context Window，Token 消耗降低 60% 以上。
• 架构稳定性：Web 端长任务彻底解耦，API 响应时间降至 <100ms（静态化缓存击中率 >95%）。

---

---

核心目标：解决多音字读错痛点，将拼音结构化并转换为火山引擎 SSML 指令。

• [ ] Task 1.1: 数据库与数据结构扩展
• 影响文件：database/migrations/、fa_wenyan_chunk 数据表
• 实施内容：
• 在 fa_wenyan_chunk 表中新增 pinyin 字段（VARCHAR(64) NULL DEFAULT ''），用于存储结构化的字词拼音（带声调，如 huán 或 duó）。
• 编写补丁脚本，自动扫描历史 note 字段中的 音xx 并提取填入 pinyin 字段。
• 负责人：后端开发
• [ ] Task 1.2: Prompt 升级与拼音字段提取
• 影响文件：inc/getchunk_llm.php
• 实施内容：
• 修改 Prompt 指令，要求 LLM 在生成切块 JSON 时，针对存在多音或特定读音的字词，必须输出独立的 pinyin 属性。
• 示例格式：

```json

{

"text": "先自度其足",

"chunks": [

{"text": "先", "note": null, "pinyin": null},

{"text": "自", "note": null, "pinyin": null},

{"text": "度", "note": "度：衡量、测量", "pinyin": "duó", "mark": "wavy"}

]

}

```

• 负责人：AI / 后端开发
• [ ] Task 1.3: 火山 TTS 请求适配与 SSML 转换
• 影响文件：v2_db.php、js/knowledgetopic_clock_tts.js
• 实施内容：
• 修改 v2_db.php 中的请求体参数，将 text_type: 'plain' 修改为 text_type: 'ssml'。
• 编写 SSML 构建工具函数 buildSsmlText(text, pinyin)：
• 当检测到 pinyin 存在时，使用 <speak> 与 <phoneme> 标签包装。
• 生成格式：<speak>先自<phoneme alphabet="py" ph="duo2">度</phoneme>其足</speak>。
• 负责人：前端 / 后端开发
• [ ] Task 1.4: TTS 缓存 Key 改造
• 影响文件：v2_db.php
• 实施内容：
• 将音频缓存文件的 MD5 生成逻辑从 md5(plain_text) 升级为 md5(ssml_text + voice_type)。
• 确保更新多音字拼音后，缓存能自动失效并重新请求合成。
• 负责人：后端开发

---

核心目标：提高 JSON 输出稳定性，大幅降低 Token 成本，建立错误自愈与测试监控机制。

• [ ] Task 2.1: Native JSON Schema (Structured Outputs) 接入
• 影响文件：inc/getchunk_llm.php、inc/getjz_llm.php
• 实施内容：
• 引入 OpenAI / Gemini 的 response_format: { type: "json_schema", ... } 机制。
• 定义严谨的 JSON Schema，强制输出包含 chunks / sentences 数组。
• 移除 inc/getchunk_llm.php 中繁重的 salvage 正则截取与 Markdown 围栏剥离代码。
• 负责人：AI 开发
• [ ] Task 2.2: 基于 AC 自动机的 Prompt 上下文瘦身 (RAG)
• 影响文件：getchunk.php、inc/getchunk_llm.php
• 实施内容：
• 在调用 LLM 前，使用 PHP 字符串匹配算法（或 AC 自动机扩展）将全量 fa_wenyan_lexicon 知识点与当前篇目原文进行预扫描。
• 仅将当前篇目中确实出现的词典条目注入 Prompt，避免全量词库污染上下文。
• 负责人：后端开发
• [ ] Task 2.3: 字符串拼接断言与 LLM Self-Correction (自愈闭环)
• 影响文件：getchunk.php
• 实施内容：
• 增强校验：implode('', array_column($chunks, 'text')) === $original_text。
• 若校验失败，自动触发 Turn 2 自愈请求，将具体的 Diff 信息（如：“第 12 个字 ‘履’ 漏掉”）喂回给 LLM 重新生成，替代过去的硬降级逻辑。
• 负责人：AI / 后端开发
• [ ] Task 2.4: 黄金测试集与 Eval 监控搭建
• 影响文件：tests/BenchmarkTest.php
• 实施内容：
• 挑选 10 篇典型文言文（长篇、多音字密集篇、专有名词密集篇）建立黄金测试集。
• 记录每次 Prompt 调整后的 Token 消耗、切块对齐率、延迟数据。
• 负责人：测试 / AI 开发

---

核心目标：摆脱 Web 长任务超时截断，实现 TTS 静态化 CDN 预热，增强数据入库断言。

• [ ] Task 3.1: 异步队列改造 (Redis + CLI 守护进程)
• 影响文件：getchunk.php、getjz.php、application/command/ProcessWywTask.php
• 实施内容：
• 将 Web 端同步执行的 getchunk / getjz 任务抽离为 ThinkPHP/FastAdmin Command 后台命令行任务。
• 前端提交切块/分句请求时，写入 Redis 队列并返回 task_id，页面通过 Ajax 轮询进度。
• 彻底删除 set_time_limit(0) 和 HTML padding 机制。
• 负责人：后端开发
• [ ] Task 3.2: 数据入库断言与事务防脏校验
• 影响文件：getchunk_save_chunks 及相关 Model
• 实施内容：
• 增加数据库事务保护。
• 在写入 fa_wenyan_chunk 前增加严格的行数与主外键校验，防少题、防错表前缀污染。
• 负责人：后端开发
• [ ] Task 3.3: TTS 批量静态化与 CDN 回写
• 影响文件：v2_db.php、application/admin/controller/Wenyan.php
• 实施内容：
• 在篇目发布审核通过时，触发后台 TTS 预热脚本。
• 批量生成切块与句子的音频，上传至 CDN/本地静态存储，并回写地址到 fa_wenyan_chunk.audio_url。
• 前端点读优先读取 audio_url，失效时才降级请求 v2_db.php。
• 负责人：运维 / 后端开发

---

核心目标：提升学生端视听跟读体验，构建生词本艾宾浩斯复习闭环。

• [ ] Task 4.1: 前端口播播放器体验优化
• 影响文件：wyw8.html、js/wyw_player.js
• 实施内容：
• 控制栏新增 语速调节 按钮（0.75x, 1.0x, 1.25x），联动火山 TTS speed_ratio 参数。
• 增加 Focus Mode（聚焦模式）：当开启句子精讲或浮窗释义时，非焦点文字微弱暗化，强化学生注意力。
• 负责人：前端开发
• [ ] Task 4.2: 生词本与刷题系统复习闭环
• 影响文件：wyw8.html、fa_wenyan_vocab、fa_shuati_question
• 实施内容：
• 在前端增加“生词闪卡（Flashcards）”复习模块。
• 将 fa_wenyan_vocab（生词本）与 fa_shuati_question（刷题库）打通，根据生词关联的词条自动组卷，实现“收集-复习-测试”闭环。
• 负责人：前端 / 后端开发

---

---

• 多音字测试用例：
• 包含《郑人买履》“先自度其足”、“置之其坐”、“反归取之”。
• 预期结果：正确发音分别为 duó (度)、zuò (坐)、huán (还)。
• 长任务测试用例：
• 提交 5000 字长篇文言文切块任务。
• 预期结果：Web 页面平滑显示进度条，后台队列正常完成，无 504 Gateway Timeout。
• 数据完整性测试用例：
• 模拟 LLM 返回断头 JSON。
• 预期结果：触发 Self-Correction 自动修复，二次修复成功后入库，原文无断字漏字。