# 用户需求 - 日期:2026-09-19(需求首次提出 2026-09-17,方案文档 2026-09-17 完成,用户 2026-09-19 审阅通过) - 入口 URL(体验/测试用):`http://127.0.0.1/estudy/`(Nginx 80 → Vite 5120 + FastAPI 8120;**不要**直开 `:5120` 调 `/api`) - 技术栈:easy-study 默认(FastAPI + React19/TS/antd-mobile/zustand,JSON 文件存储,无数据库) - 本流水线是「儿童英语学习 & 辅导闭环方案」三条流水线中的**第一条**:`daily-plan-engine`。后两条 `speaking-coach-agent`、`listening-clips-and-starters` 另开目录,不在本轮范围。 - 原型确认停点:**不阻塞**(用户已整体审阅方案并选择默认设计;阶段 4 通过后把原型路径通知用户即继续)。 ## 用户原话 > 根据项目现有功能及用户沟通历史问题 ,分析如何利用现有英语资源:自然拼读、剑桥英语、牛津树、小猪佩奇/布鲁伊动画片 等资源规划孩子每一天学习,并结合现有工具和孩子学习特点+hermes 设计一套:学习计划、hermes提醒执行、agent(TTS ASR 发音评分、口语练习)收集孩子学习效果。制定一套完整详细的儿童英语学习&辅导计划。目前可用的点是:借助火山平台开发agent收集孩子口语发音情况,hermes agent 打通微信每天提醒孩子学习(听说读、写字母&高频单词)和反馈,并发送局域网网页地址进行游戏测验、定期复习。先告诉我你计划怎么做 > (2026-09-17 澄清问答)孩子每天学习用哪个设备、微信提醒发到哪 → 用户选:家里 iPad 登录了微信,孩子自己看提醒、点链接在 iPad 上学。剑桥 Starters 定位 → 用户选:不急着考试,把 Starters 词表/题型当能力标尺,每月用真题抽测校准。 > (2026-09-19,审阅阶段 1 六份文档后)已审阅按默认推荐设计 ## 背景补充(主 agent 掌握的上下文) ### 必读的上游方案文档(本流水线的需求与契约来源) 目录 `tasks/0913-EnglishStudyAnalysis/`(绝对路径 `D:\codes\MyProjects\easy-study\tasks\0913-EnglishStudyAnalysis\`): | 文档 | 本流水线用到的部分 | | --- | --- | | `01-学习者画像与基线评测方案.md` | §2 画像 P1-P14 与设计约束 C1-C10(孩子端所有文案/交互必须遵守) | | `02-学习目标与课程地图.md` | §3.3 前 12 周规则表、§4 高频词六组、§5 牛津树阅读序列、§7 课程数据文件 | | `03-每日每周学习模板.md` | §2 六张卡(内容来源、深链、完成标准、事件、星星)、§2.3 顺延、§3 周测、§5 激励、§6 微信文案模板、§8 例外处理 | | `04-掌握度判定与复习调度规则.md` | 全部:状态机、正确定义、随意作答检测、每日计划生成算法、阅读游标、升降档、周测/月测抽样、localStorage 迁移映射、指标定义、`profile.json` | | `05-系统总体设计.md` | §3 数据模型(`srs.json` / `plans` / `events.jsonl` schema)、§4 API 契约、§5 前端设计(今天页、深链协议、家长页)、§6 后端模块布局、§8 Hermes 设计、§11 安全 | | `06-实施路线图与资源准备清单.md` | **§2 流水线 1 的 V1 范围、V1 不做、验收口径**;§5 Hermes 安装清单;§8 用户决策 D1-D15(全部采用默认值) | 各角色**先读用户原话独立理解,再读上述文档**;文档里的接口路径、数据 schema、事件类型属于已确认契约,角色可细化、不可改名改形;若发现契约有缺口,按铁律 5 报给主 agent 裁决。 ### 用户决策(D1-D15 全部按 06 §8 默认值) - 基线评测放阶段 2 上线后第一周(口语部分家长判);周一至周五 19:30 / 20:15 / 20:45,周六 10:00 / 20:00;周日完全不提醒;不配置实物奖励;通过线词 70 / 句 65;`mastered` 90 天抽检;迁移时「已掌握」降为 `weekly`;HTTPS 用 mkcert(阶段 3 前置,本轮不做);`docs/data/learning/` gitignore + 夜间备份;反馈语音先 edge-tts。 - D13(Hermes 主机位置)用户未指定:**假设** Hermes 网关跑在局域网内某台 Linux 主机,能直连 `http://192.168.11.157:8120`;所有脚本通过环境变量 `EASYSTUDY_API` 取地址,改成经 NAS `https://…/estudy/api` 只需改变量。 ### 现有产品(改动前状态,`bookshelf/`) - 孩子端路由:`/` 书架 `Home.tsx`(「今天读这本 / 这些词还要再练 / 今天练这些词」三块引导 + 书格,级别 tab)、`/learn/:id` 拼读 `Learn.tsx`(听音选字 → 六宫格 → 按序拼词 → 拆分块)、`/quiz/:id` 闯关 `Quiz.tsx`(5 题:听音选字 / 字母块选拼法)、`/book/:id/read` 沉浸阅读 `ChildBookReader.tsx`(翻页、整本音频、点词词典、读完 → 读后 6 词自检 → 去拼读/玩拼字)、`/spell/:id` 拼字 `SpellingGame.tsx`(重点词乱序字母块 + 干扰项)。底栏只有 看书 / 拼读 / 闯关;阅读与拼字页沉浸无底栏。 - 家长端:长按书架小熊 🐻 → 校对 → 「学习情况」`/parent` `Dashboard.tsx`;`/parent/review/:id` 文本校对 + 重点词句页签;`/book/:id` 校对阅读器。 - 学习状态:**全部在 localStorage**(`src/pages/child/bookStudy.ts`,键 `easy-study:phonics:book:`,结构 `BookStudyState{words{word,status,source,correctCount,wrongCount,addedAt,updatedAt}, quizAttempts[], spellingAttempts[]}`;掌握规则连对 2 次;`peekTodayWords/peekReviewTask` 的 4h/12h/24h 启发式)。服务端只有阅读记录 `POST/GET /api/records`(`docs/data/reading-records/default.json`,线程锁 + tmp + os.replace 原子写,是新增小数据持久化的模板)与重点词句 `GET/PUT /api/books/{stage}/{folder}/key-words`。 - 后端:`app/main.py` 挂载 books/key_words/words/records;`app/config.py` 集中路径(`DATA_DIR` = `docs/data` 经 workhome 软链,`RECORDS_DIR`、`KEY_WORDS_DIR`…,环境变量可覆盖)。`app/routers/words.py` 提供 `/api/words/lookup/{word}`(音素、字母-音素拆分、释义、音频候选)与 TTS。 - 数据:`docs/data/book-index.json`(14 级 364 本)、`book-structured/stage-03|04/*.json`(80 本,`all_words`、句子含 `phonics`)、`251228-words/phonics-data.json`(1836 词 `letterPhonemes`)、`phoneme.json`(48 音素音频)。 - 前端 API 客户端 `src/api/client.ts`(`booksApi/keyWordsApi/recordsApi/wordsApi`),路径基址 `withBase('/api')` → `/estudy/api`。 - 部署:Vite `base=/estudy/`,路由 `basename`;Nginx `/estudy/api/` → 8120;`deploy/nginx/nginx-win.conf`(开发)与 `nginx-win-prod.conf`(生产)。 ### 并行工作流(角色需知) - 课程数据由另一条后台工作流同时产出:`bookshelf/backend/tools/build_*.py` 与 `docs/data/curriculum/{phonics-units,hf-words,ort-sequence,letters}.json`(W1-W4 最小集优先,schema 见 02 §7 / 05 §3.1)。**后端角色消费这些文件,不要自己另造一份**;到阶段 5 若文件还不存在,结论写「阻塞」交主 agent 处理,不计轮次。 - **课程数据已就位(2026-09-19 07:26)**:`docs/data/curriculum/{phonics-units,hf-words,ort-sequence,letters,qa-bank,starters-words}.json` 由 `bookshelf/backend/tools/build_curriculum.py` 一键生成(种子在 `tools/seeds/`)。**实际 schema**:每个文件顶层是对象 `{version, generatedAt, generator, inputs{…sha1}, summary, <数组>}`,数组键分别为 `units` / `groups` / `books` / `letters` / `questions` / `words`(不是 02 §7 示意的裸数组);例词带 `phonemes / letterPhonemes / occurrences[{bookId,page,sentence}]`;`phonics-units.json.summary.removedWords` 列出因不在 `phonics-data.json` 而被剔除的种子词(正在经 `phonics-missing.json → patch_phonics.py merge` 补录后重跑,重跑不改 schema)。`letters.json` 的字母卡引用 PDF 页 + `cardBox`,无逐字母 PNG。`qa-bank` 含 `{childName}` 等占位符需按 profile 替换。 - Hermes 侧的 skill 与 cron 定义文件(`deploy/hermes/`)属于本流水线后端范围(05 §8、06 §5);实际在 Hermes 主机安装、扫码登录由用户完成,不在验收范围,但文件与 README 要能照着做。 ### 既有约定 - 孩子端改动完成后(阶段 7 通过后、阶段 8 前)必须跑 `child-ux-tester`,报告只读 `bookshelf/tasks/child-ux-report.md`,修完 P0/P1 才验收(AGENTS.md)。 - 面向孩子的文案禁止 M3/Quiz/Learn/SRS/事件 等黑话;按钮 ≥ 44px;中文 ≤ 12 字/句(01 §2.3 C1)。 - 后端起服务不要 `--reload`;改后端后重启 `python -m uvicorn app.main:app --port 8120`(当前用系统 Python,venv 缺 uvicorn)。 ## 主 agent 的初步假设(角色们可质疑) 1. V1 范围与「不做」以 `06 §2` 为准:后端 plan/events/srs/reports(日/周)/days/curriculum(week) + `/api/records` 兼容转发 + scheduler;前端 `/today`、书架「今天」入口、四个现有页面接 `?plan=` 并上报事件、`bookStudy.ts` 改缓存 + 事件 + 一次性 `srs/sync`、`/parent/report` V1、离线事件队列;`deploy/hermes/` skill 与 cron 文档;`docs/data/learning/` gitignore + 备份脚本。**不做**:口语评分与 Speak 页(卡 4 在计划中生成但显示「即将开放」或由 profile 开关隐藏,由产品设计定)、听一听切片与 Listen 页(卡 2 同上处理)、Starters 录分、评测模式、HTTPS。 2. 今天页是微信链接的落点(`/today`),书架保留为底栏「看书」首页并在顶部加「今天」入口卡;是否把「今天」做成默认首页由产品/UX 决定,但底栏不加第四项。 3. 计划生成、判定、到期全部在服务端;前端不再做掌握度判断;`peekTodayWords/peekReviewTask` 退役,书架三条引导改读 `/api/plan/today`。 4. 事件是唯一写入口:现有页面结束时 `POST /api/events`(带 `planItemId`),`/api/records` 保持兼容并在服务端转成 `reading` 事件。 5. 微信文案由后端 `wechat-text` / `reports?format=wechat` 渲染(03 §6 模板),Hermes 脚本原样转发;`nudge` 在全部完成或 day_off 时返回空体。 6. 随意作答检测(04 §5)在闯关与拼一拼里生效:`responseMs < 1500` 且错 → `hasty`,不计错;连续 2 次弹「慢一点,先听一遍 👂」并重播音频。 7. 单孩子 `child_id=default`;多孩子档案不在范围,但数据路径按 `learning/{child_id}/` 组织。 ## 主 agent 裁决记录(铁律 5;下游角色必须遵守,不得另起方案) 针对 `10-analysis.md` 第 1 轮「关键假设与开放问题」: 1. **六卡与 V1 后置(开放问题 1)→ 裁决:V1 生成 5 张可执行卡。** 卡 1 拼一拼、卡 2 听一听(占位:当前计划绘本的整本音频前约 60 秒,计划 JSON 标 `placeholder: true`,文案由产品/UX 定但不能出现「即将开放」之类让孩子失望的字样)、卡 3 读一读、卡 5 写一写、卡 6 闯关;**卡 4 说一说不生成**(`profile.features.speaking=false`,后续流水线打开)。卡片编号保留 c1-c6 语义但 `cards[]` 只含实际生成的卡;星星分母按实际卡数动态计算(5 卡 + 全完成奖励 2 = 7),今天页不展示拿不到的星。06 §1 的「完成 6 卡」退出标准按此改为「完成当日全部生成卡」。 2. **`card_skip` 事件(开放问题 2)→ 裁决:新增事件 type `card_skip`**,payload `{cardId, reason, source: "parent" | "hermes"}`,由 skip API 在服务端写入;05 §3.4 已同步增补。不再新增其他 type。 3. **阅读双写(开放问题 3)→ 裁决:`POST /api/records` 是阅读结果的唯一提交入口**,新增可选字段 `plan_item_id`、`mode`、`event_id`;服务端只转成一条 `reading` 事件并按 `event_id` 幂等;页面不得再单独 `POST /api/events` 上报 reading。05 §4.7 已同步修订。 4. **事件幂等(开放问题 4)→ 裁决:服务端按 `(childId, event.id)` 去重**;重复提交返回原 `ids` 与当前卡状态,不再次更新 SRS/星星/报告。前端生成事件 id 用 `evt_` + ULID/UUID。05 §4.2 已同步。 5. **卡完成聚合(开放问题 5)→ 裁决:卡片 `done` 只由服务端按 03 §2 完成标准聚合**(卡 1:4 词三关事件齐;卡 2:`listening.playCount ≥ 1` 且 `durationSec ≥ 45`;卡 3:reading 事件 `completed=true` 且 mode 匹配,D3 需 `selfCheck`;卡 5:`writing_checkin` 或 `/complete`;卡 6:题数达标的 `quiz` 事件 + `quiz_summary`)。客户端只做乐观显示。 6. **顺延合并(开放问题 6)→ 裁决:顺延内容优先占用当日同类型卡容量**,仍受 20 分钟与新项/复习上限;只顺延一次,再未完成记 `skipped(reason=carry_over_expired)`。 7. **课程文件(开放问题 7)→ 维持**:只消费约定文件,缺失即「阻塞」。 8. **Hermes 验收边界(开放问题 8)→ 维持**:代码验收 = 脚本在 Linux shell(可用 WSL/Git Bash 模拟)按环境变量运行并 curl 到本机后端得到预期文本/空体;真实安装与投递为用户环境验收。 9. **书架三条提示(开放问题 9)→ 维持**:只展示计划中存在的映射项,无任务时统一休息态。 10. **写一写的完成确认(40-review 第 2 轮 P0)→ 裁决:孩子页不得直接写入完成。** 卡 5 的完成只有两条路:① 微信照片/「写好了」经 Hermes 写 `writing_checkin`;② 家长在成人门禁之后确认——复用现有「长按小熊解锁」模式(`easy-study:adult-unlocked`),在今天页写一写卡内长按 2 秒出现「家长确认」小面板再点确认,或在家长页确认。孩子页写一写卡只显示任务内容与「写好了就给爸爸妈妈看」,无可直接点的完成按钮。这是交互门禁,不改数据契约(仍是 `/complete` 接口与 `writing_checkin` 事件)。 11. **周六闯关题数(55-frontend 第 1 轮报告:实际 14 题 vs 契约 15 题)→ 裁决:后端缺陷,按 04 §9 补齐。** `weekly` 到期池不足 15 时依次用 `learning` 到期项、本周新项补足并标 `filler: true`;只有全部可用学习项总数 < 15 时才允许少于 15,且 `summary` 里要写 `questionShortfallReason`。归后端第 2 轮修复;前端不做特殊处理。 12. **「这个词我要练」/读后「不会」的事件落点(55-frontend 第 1 轮)→ 裁决:不新增事件 type。** ① 阅读页内点词「我要练」与读后「不会」继续累积进 `/api/records` 的 `unknown_words`(阅读结果唯一入口,裁决 #3),服务端把这些词写入 SRS 为 `new`(source `reader`)。② 拼一拼/Learn 页的「这个词我要练」发 `phonics` 事件,`payload.stage = "want_practice"`(在既有 listen_pick/scramble/spell 之外新增一个 stage 值,不是新 type),服务端只确保该词在 SRS 中存在且状态不低于 `new`、source 记 `learn`,不改 correct/wrong 计数,也不参与卡完成聚合。后端第 2 轮实现 ②,前端按此发事件。 ## 范围猜测 - **后端**:新增 `routers/{plan,events,srs,reports,days,curriculum}.py`、`services/{store,curriculum,srs_engine,plan_engine,reports,wechat_templates,scheduler}.py`、`config.py` 路径与 `EASYSTUDY_TOKEN`、`main.py` 挂载、`requirements.txt`(APScheduler)、`.env.example`、`.gitignore`(`docs/data/learning/`)、`deploy/backup/backup_learning.py`。 - **前端(孩子端)**:`pages/child/Today.tsx(+css)`、`Home.tsx` 今天入口、`Learn/Quiz/SpellingGame/ChildBookReader` 接 `?plan=` 与事件上报、`bookStudy.ts` 重构、`api/client.ts` 新增 `planApi/eventsApi/srsApi/reportsApi`、离线事件队列、`App.tsx` 路由。 - **前端(家长端)**:`pages/parent/Report.tsx`(周报字段 + 跳过卡)、入口接线。 - **部署/文档**:`deploy/hermes/README.md`、`deploy/hermes/cron.md`、`deploy/hermes/skills/easy-study-coach/{SKILL.md,scripts/*.sh}`。 - **不涉及**:`251228-words/` 旧模块、OCR/音频流水线工具、StudyDeck、Nginx TLS。