# 需求分析报告 - 日期 / 轮次:2026-09-19 / 第 1 轮 - 输入:`00-request.md`;必读上游方案 `01-学习者画像与基线评测方案.md` 至 `06-实施路线图与资源准备清单.md`;现有产品实走与代码契约核对 - 应用的历史教训:无 - 结论:分析完成,交产品设计;V1 可按已审阅方案推进,但“6 卡闭环与卡 2/4 后置”“`card_skip` 事件未定义”“阅读事件避免重复写入”三处契约冲突/缺口必须由下游按本文推荐假设收敛,并在实现前交主 agent 裁决 ## 用户原话摘录 > “分析如何利用现有英语资源:自然拼读、剑桥英语、牛津树、小猪佩奇/布鲁伊动画片 等资源规划孩子每一天学习” > “结合现有工具和孩子学习特点+hermes 设计一套:学习计划、hermes提醒执行、agent(TTS ASR 发音评分、口语练习)收集孩子学习效果。” > “hermes agent 打通微信每天提醒孩子学习(听说读、写字母&高频单词)和反馈,并发送局域网网页地址进行游戏测验、定期复习。” > “孩子每天学习用哪个设备、微信提醒发到哪 → 家里 iPad 登录了微信,孩子自己看提醒、点链接在 iPad 上学。” > “剑桥 Starters 定位 → 不急着考试,把 Starters 词表/题型当能力标尺,每月用真题抽测校准。” > “已审阅按默认推荐设计。” ## 用户画像 - **直接使用者:约 6 岁女孩。** 能独立操作 iPad、只看懂少量中文,单次专注约 15–20 分钟;因此孩子端不能依赖长文字或复杂选择,正文中文每句不超过 12 字、按钮热区至少 44px、关键操作需要图标与语音提示(上游 P1、P10、C1、C4)。 - **学习基础:不是零基础,而是“学过但迁移不稳”。** 认识 26 个字母,OPW L1–L5 约掌握 60%,牛津树 3–4 级每本仍有 3–5 个生词;b/d/p/q、长短元音和功能词混淆是优先弱点。计划应做螺旋巩固和跨场景迁移,不能从字母启蒙重新线性教学(P2–P6、C9)。 - **操作边界:不适合软键盘和抽象自评。** 拼写应使用字母块,掌握判定不能依赖“会/不会”,应依赖跨天测验与后续复测(P7、P8、C2、C5、C10)。 - **行为特点:允许多次尝试,也可能因简单或重复而故意点错。** 错误不应造成惩罚或中断;系统需区分仓促作答与真实混淆,保护兴趣同时保证数据可信(P7、P9、C3、C6)。 - **使用场景:孩子在家中 iPad 微信收到提醒,点局域网链接进入网页学习。** 微信只是唤起与反馈通道,不承载学习流程;除后续口语页外,V1 应能从微信内或现有网页顺畅开始(P11、P12、C7、C8)。 - **辅助使用者:双职工家长。** 日常只适合少量介入,主要在周报、请假、跳过卡片和月度 Starters 抽测时参与;V1 必须让家长能快速判断“做了什么、哪里薄弱、下周练什么”,不能要求每日手工排课(P10、P13、P14)。 ## 场景与痛点 1. **资源很多但没有每日编排。** 自然拼读、牛津树、动画、Starters 与现有游戏各自可用,却没有统一的周规则、每日任务、完成标准和顺延机制,孩子与家长仍需临时决定学什么(用户原话;02;03)。 2. **现有学习入口是“资源书架”,不是“今天任务”。** 2026-09-19 实走 `http://127.0.0.1/estudy/` 可见书架、拼读、闯关及“今天读/练”三条启发式提示,但访问 `/estudy/today` 为空白;现有 `App.tsx` 也没有 `/today`、`/parent/report` 路由。因此微信链接尚无可执行的每日闭环落点。 3. **学习结果分散且判定过宽。** 当前单词状态按书保存在 localStorage,掌握规则为连对两次,既不能跨书合并,也不符合家长认可的 3 天—7 天—30 天复测标准;换设备、清缓存和多入口学习也会造成进度割裂(04 §3、§11;05 §1)。 4. **现有页面无法证明计划完成。** Learn、Quiz、SpellingGame、ChildBookReader 尚未通过 `planItemId` 关联计划,也没有统一事件流、离线重放和服务端卡片状态,Hermes 无法准确静默提醒或生成可信反馈(05 §3.3–§5.3)。 5. **V1 与最终六卡方案存在阶段差。** 最终模板包含拼、听、读、说、写、闯六卡,但本流水线明确不做正式 Listen 切片和口语评分;若不先定义占位/隐藏及星星分母,“完成 6 卡”的阶段退出标准无法被一致验收(03 §2;06 §1–§2)。 6. **家长反馈尚未形成闭环。** 当前家长端以文本校对和已有学习情况为主,没有按统一事件聚合的日/周报告、薄弱项和跳过卡片能力,无法低成本监督执行(03 §6–§7;05 §4.5、§5.6)。 7. **Hermes 尚缺可安装、可验证的确定性接口。** 提醒时间、静默条件、允许账号、脚本职责已有方案,但仓库需交付 skill、脚本、cron 与安装说明;实际主机安装和扫码由用户完成,不应被误算为代码验收失败(05 §8;06 §2、§5)。 ## 核心诉求(按优先级) 上游追溯编号:`U0`=用户原话/澄清;`U01`–`U06`=六份已审阅方案文档;`EX`=现有产品核对。 | # | 诉求 | 明说/隐含 | 验收口径 | | --- | --- | --- | --- | | R1 | 服务端按日期、课程游标、到期项和昨日顺延确定性生成当天计划,成为所有端的唯一真源(U0、U03 §2、U04 §6–§8、U05 §1/§4.1、U06 §2)。 | 明说 | 无当日文件时 `GET /api/plan/today` 在 300ms 内生成;同日重复调用返回同一计划;`force` 仅在当日无事件时可重生;全部时间按 Asia/Shanghai。 | | R2 | V1 形成不超过 20 分钟、单卡不超过 6 分钟的可执行日流程,并按“先输入后输出、动静交替”呈现(U01 C4、U03 §2、U04 §6)。 | 明说 | 标准工作日计划的新项≤6、复习项≤12、预估总时长≤20分钟;每张可执行卡有名称、内容、完成标准、深链/动作、状态和星星。 | | R3 | 用 W1–W4 最小课程数据把拼读、高频词、牛津树与字母书写纳入计划,后续可无缝接入动画与口语(U0、U02 §3/§4/§5/§7、U06 §2)。 | 明说 | 只读取约定的 `docs/data/curriculum/{phonics-units,hf-words,ort-sequence,letters}.json`;W1–W4、A/B 组可生成计划;文件缺失时明确报阻塞,不另造平行数据源。 | | R4 | 新增孩子可独立操作的 `/today` 落点,并从书架提供“今天”入口;完成卡片后回到今天页看到即时状态(U0、U01 C1/C7、U05 §5.1–§5.3、U06 验收 2/7)。 | 明说 | 微信链接与书架入口均能到 `/today`;卡片热区≥44px、中文≤12字/句;Learn 三连关完成后事件落盘、卡1变为完成并返回/刷新今天页;周日或请假日仅显示自由入口。 | | R5 | 让现有 Learn、Quiz、SpellingGame、ChildBookReader 接受 `?plan=` 并按既定事件 schema 上报,页面无 `plan` 时保留原有自由学习行为(U05 §3.4/§5.3、U06 §2)。 | 明说 | 四个页面从计划深链进入时事件携带正确 `planItemId="{date}:{cardId}"`;无 `plan` 仍可使用且事件不关联卡;事件 payload 字段和 type 不改名、不变形。 | | R6 | 建立单孩子、跨书合并的 SRS 状态机,落实 3天—7天—30天—90天复测和按题型判定(U0、U01 P13/C10、U04 §2–§4/§9–§10、U05 §3.2)。 | 明说 | `new→learning→weekly→monthly→mastered` 及回落按 U04 执行;同日多次正确只计一个 `correctDay`;选择题首次正确且响应≥1500ms 才推进;掌握项90天抽检。 | | R7 | 识别仓促/随意作答,既不把它计为真实错误,也不让孩子因惩罚受挫(U01 P7/P9/C3/C6、U04 §5、U06 验收3)。 | 明说 | 单题 `<1500ms` 且错记 `hasty`、不增加 `wrongCount`、本轮末重出;连续2次显示“慢一点,先听一遍 👂”并重播且2秒不可点;同轮≥3次进入两段式,不扣星。 | | R8 | 把现有 localStorage 学习状态一次性、幂等迁移到服务端,迁移后服务端判定、前端只缓存与排队(U04 §11、U05 §1/§4.3/§5.3、U06 验收4)。 | 明说 | `/api/srs/sync` 可接收全部 `BookStudyState`;重复调用不重复项目或历史事件;同词跨书合并;原 `mastered` 降为 `weekly`;成功后本地标记但不清除原数据;书架三条提示与当日计划一致。 | | R9 | 事件写入驱动 SRS、卡片状态、星星与报告,并支持断网缓存、批量重放和幂等去重(U03 §8、U05 §1/§3.4/§4.2/§5.2)。 | 明说 | 单条或≤200条批量事件可写入并返回 `ids/srsUpdates/card`;离线时卡片本地先完成、恢复后重放;同一事件 ID 重放不重复累计;常规事件写入目标<50ms。 | | R10 | 阅读记录接口继续兼容旧调用,同时统一进入 reading 事件和计划闭环(U05 §4.7、U06 §2)。 | 隐含 | 旧 `POST /api/records` 请求仍成功;含可选 `plan_item_id/mode` 时更新对应卡;每次阅读完成只产生一条业务 reading 事件,不能因页面同时调用新旧接口重复计数。 | | R11 | 家长可查看本周执行与学习效果,并可跳过当天不可执行的卡(U0、U03 §6–§8、U04 §12、U05 §4.5/§5.6、U06 验收6)。 | 明说 | `/parent/report` 至少显示周完成天数/完成率、星星、拼读与高频词薄弱项、阅读书目、下周重点;可跳过指定卡并记录原因;孩子今天页同步反映跳过且不扣星。口语、月报、Starters 录分不进入本 V1。 | | R12 | Hermes 通过固定脚本拉取后端文案,在约定时段向孩子/家长提醒并在已完成、请假或无事件时静默(U0、U03 §1/§6、U05 §8、U06 §2/§5)。 | 明说 | 仓库交付 `easy-study-coach` 的 SKILL.md、6个约定脚本、README 与 cron 文档;工作日19:30可取今日消息,20:15全部完成/day_off返回空体200,20:45无事件不唤醒,周六10:00孩子提醒、20:00家长周报;数字、英文词、链接不被模型改写。 | | R13 | 系统在后端、Hermes或网络局部故障时仍可学习并给家长可诊断信号(U03 §8、U05 §12、U06 R4/R9)。 | 隐含 | 后端不可达时今天页显示缓存计划/友好降级,事件入本地队列;Hermes curl失败非零退出并只告警家长;Hermes不可用不影响从书架进入学习。 | | R14 | 学习运行数据按单孩子隔离、原子写入、排除版本库并可夜间备份,Hermes写接口受 token 保护(U05 §3/§4/§11、U06 §2)。 | 明说 | 数据只写 `docs/data/learning/default/` 约定结构,JSON使用锁+tmp+`os.replace`、事件JSONL加锁追加;目录被gitignore;备份脚本可生成归档;Hermes写请求在配置 token 时无/错 token 被拒绝。 | | R15 | 保持现有产品自由阅读/拼读/闯关入口与底栏,不把本轮扩成全面改版(EX、U05 §5.1、U06 §2)。 | 隐含 | 原 `/`、`/learn/:id`、`/quiz/:id`、`/spell/:id`、`/book/:id/read` 和三项底栏可继续使用;本轮不新增第四个底栏项、不改变既有 basename 与 `/estudy/api` 代理契约。 | | R16 | 按孩子体验约束完成专项实测后再验收(U01 C1–C7、U06 验收7、仓库约定)。 | 隐含 | Today、计划深链、卡片返回路径完成 `child-ux-tester`;最终报告无P0/P1;P0/P1修复后方可宣称V1完成。 | ## 非目标 - 本轮不实现正式口语评分、Speak 页、ASR/TTS 评分闭环、弱音素联动或微信图片识别;这些属于 `speaking-coach-agent`。 - 本轮不做动画/台词音频切片、正式 Listen 页、Starters 词表覆盖/录分、基线评测模式、月测/月报或 stage-05 结构化;这些属于 `listening-clips-and-starters`。 - 本轮不做视频播放、HTTPS/mkcert、火山凭证开通、Hermes 主机安装/扫码登录,也不以实际外部微信投递作为纯代码交付的必要条件;需提供可照做的安装与验证文档。 - 不新增数据库、多孩子管理、云端账号体系或公网部署;V1 固定 `child_id=default`,但文件路径保留 `{child_id}` 结构。 - 不重做书架、阅读器、拼读、闯关的核心玩法,不新增底栏第四项,不修改 `251228-words/` 旧模块和 OCR/音频流水线。 - 不让 LLM 决定计划、掌握状态、分数、星星或报告数字;模型只允许在后续/约定的反馈环节润色措辞。 - 不把自由重读、自选动画或周日自由玩算作计划强制任务;不因跳过、顺延、错误或周日扣星。 ## 关键假设与开放问题 1. **[需裁决:六卡与 V1 后置冲突]** `U06 §1` 要求阶段 2 跑通“完成 6 卡”,但 `U06 §2` 又明确口语卡不做、听力卡可占位或不生成,无法同时严格成立。推荐假设:V1 生成 **5 张可执行卡**——卡2用“当前绘本整本音频段”占位,卡4不生成;总卡数、完成率与星星按实际生成卡动态计算,不展示不可获得的“8颗星”。若主 agent 坚持“6卡”,则必须补充一个无需口语评分且可真实完成的卡4替代任务,不能把“即将开放”算完成。 2. **[需裁决:跳过事件缺枚举]** `U06` 验收要求事件有 `card_skip`,但 `U05 §3.4` 的事件枚举没有该 type,只有 skip API。推荐假设:保留既定 type 不擅自新增;skip API 更新计划卡为 `skipped`,并由服务端产生现有可追踪事件前需主 agent 指定合法 type/payload。产品与开发不得各自另起名字。 3. **[需细化:阅读重复写入]** `U05` 同时要求页面上报 `reading` 事件及 `/api/records` 内部转发 reading,存在双写风险。推荐假设:ChildBookReader 继续以 `/api/records` 为单一提交入口,并新增 `plan_item_id/mode/event_id`;服务端只转成一次 reading 事件,按 `event_id` 幂等。 4. **[需细化:事件幂等]** 离线队列必然重放,但上游只定义事件 ID,未明确重复 ID 的响应语义。推荐假设:服务端以 `(childId,event.id)` 去重;重复提交返回原 ID/当前卡状态,不再次更新 SRS、星星或报告。 5. **[需细化:卡完成聚合]** phonics 每词每关多事件、quiz 每题加汇总,但“何时自动将卡置 done”的服务端规则未逐卡写成契约。推荐假设:严格用 `U03 §2` 的完成标准聚合;客户端不得仅凭发出任意一条事件宣告完成。 6. **[需细化:顺延合并]** `U04 §6` 写“昨日 deferred 卡在今日同位卡加 carriedOver”,但未定义同位已有新内容时替换、合并还是排队。推荐假设:顺延内容优先,占用当日同类型卡容量且仍受20分钟、新项/复习上限;只顺延一次,再未完成转 skipped。 7. **[需细化:课程文件并行产出]** `00-request.md` 表示另一后台工作流产出课程文件,`U06` 又把 W1–W4 最小集列入本流水线数据范围。推荐假设:本流水线只消费约定文件;进入开发阶段仍不存在则报告“外部依赖阻塞”,不复制脚本或手写第二套数据。 8. **[需细化:Hermes 验收边界]** D13 仅假设 Linux 主机可直连本机 API,实际主机与 chat_id 尚未确认。推荐假设:代码验收以脚本可在 Linux shell 通过环境变量运行、dry/manual curl验证为准;实际安装、扫码和真实投递列为用户环境验收。 9. **[需细化:书架三条提示]** 现有三条分别是“今天读这本 / 这些词还要再练 / 今天练这些词”,而 `/api/plan/today` 可能在周日、请假或降档时没有对应内容。推荐假设:只展示计划中存在的映射项,不用旧启发式补齐;无任务时显示统一休息态。 10. **[已采用假设]** D1–D15 均按用户审阅后的默认值执行;本轮直接相关的是既定时段、周日静默、无实物奖励、mastered 90天抽检、迁移降级、learning数据gitignore+备份、反馈先edge-tts。D13 按 `EASYSTUDY_API` 环境变量解耦主机位置。 11. **[现有产品缺口]** `/today` 实走为空白且路由未注册;这不是文案或样式问题,而是本轮必须补齐的入口与数据闭环。现有书架的三个提示只能视为迁移来源,不能视为计划引擎已经存在。 ## 给下游的硬约束 - 用户已审阅的 `U01`–`U06` 是契约;API 路径、schema 字段、事件 type 和 `planItemId` 形式不可擅自改名改形。 - 产品设计首先收敛“V1 实际几张可执行卡、可获星星总数”,不得同时展示不可完成的卡和“全部完成”目标。 - 6岁孩子端必须满足:中文≤12字/句、按钮≥44px、少文字、图标+语音、无软键盘、错后可重试且不惩罚。 - 标准日总时长≤20分钟、单卡≤6分钟;顺延、自适应和占位内容也不得突破上限。 - Today 是微信深链落点,但书架和三项底栏继续保留;不新增第四个底栏项。 - 服务端是进度唯一真源;客户端只能做缓存、乐观显示和离线队列,不能继续独立判定 mastered。 - 所有计划内学习结果必须经既定事件结构关联 `planItemId`;离线重放必须幂等。 - `/api/records` 必须向后兼容,阅读结果只能形成一次业务事件,禁止新旧接口双计。 - 仓促错误不计 `wrongCount`;真实混淆才进入加权与后续复习。 - 周日和 day_off 不生成任务卡、不发提醒、不中断 streak;跳过和顺延不扣星。 - 家长报告 V1 只覆盖周报与跳卡,不夹带 Starters、口语评分、月报和课程设置大改。 - Hermes 只转发后端确定性结果;数字、英文词和链接原样保留,孩子账号不能触发管理操作。 - 课程最小数据必须消费约定文件;缺文件要显式阻塞,不能在前后端内硬编码另一套课程。 - 运行数据必须原子写、按孩子隔离、排除 git 并可备份;版权资源不得纳入仓库或公网分发。 - 实现结束必须实走微信链接落点、四个现有深链、断网重放、周日/请假、跳卡与迁移,并通过 `child-ux-tester` 的 P0/P1 门禁。 ## 上游双向核对 - `U01` 的 P1–P14 已落在用户画像、R2/R4/R6/R7/R16;C1–C10 已落在 R2/R4/R6/R7、非目标与硬约束。 - `U02` 的 W1–W4、A/B 高频词、牛津树游标和四类课程文件已落在 R3;其 M4–M6、动画切片、Starters 与完整评测明确列为非目标。 - `U03` 的六卡来源、深链、完成标准、事件、星星落在 R2/R4/R5/R9;顺延、周测、激励、微信模板与例外处理落在 R1/R7/R11–R13 及开放问题1/5/6。 - `U04` 的状态机、正确定义、随意作答、计划算法、阅读游标、升降档、抽样、迁移、指标和 profile 约束落在 R1/R2/R6–R9/R11;未落地的月测与口语特殊规则按 `U06` 列为后续流水线。 - `U05` 的数据布局、`srs/plans/events` schema、V1 API、Today/深链、后端模块、Hermes与安全契约落在 R1、R4–R15;发现的 skip 事件、阅读双写和事件幂等缺口列入开放问题2–4。 - `U06 §2` 的 V1 必做项全部可追溯到 R1–R16,V1 不做项全部进入非目标,7条验收口径分别落在 R1、R4/R5、R7、R8、R12、R11、R16;其中“6卡”矛盾已单列开放问题1。 - 本轮输出的每项核心诉求均至少追溯到 `U0/U01–U06/EX` 之一,没有新增不可追溯的“用户要求”;所有补充均明确标为隐含诉求或推荐假设。