# M1 开发与验收约定

> 版本：1.0｜2026-09-12｜个人自用，Flutter 手机优先，支持 iPhone、Android、Mac。
> 本文件统一 M1 范围、数据契约、降级行为和验收。学习算法以《学习引擎规格》为准，A0 清单与评估以《A0 阶段标准》为准。其他文档不得另设升级门槛；调整时须同步更新并记录版本。

## 1. 冻结的范围

M1 是完整的 **A0 学习闭环**，不是全部 A0–B2 产品：

- 10 节种子课程及必要的分段教学；每个有新内容的教学段先做课前词汇预热，再进入听、说、读、写和简短语法解释。
- 固定能力地图驱动的每日推荐、AI 变式和补救微课；课程总量不限。
- 课程内及独立入口的 A0 受控任务对话；文字输入、轮流录音、转写确认、TTS。
- 本地学习证据、掌握状态、到期复习、基础写作纠错与进度。
- A0 四技能出口评估、未通过补练、重新评估、通过状态。
- 课程、阅读与受控对话中的随时查词；短语优先、单词其次，提供释义、音频、例句和加入复习。
- AI 服务配置与连接测试、离线基础练习、中断恢复和安全的数据删除。

不包含：账号、社交、付费、留存运营、通知、自建业务后台、自动同步、导出/导入、自由主题聊天、实时全双工语音、精细发音诊断。导出/导入和 A1 课程在 M2；A2 及以上逐阶段扩展，不因文档列出目标而视为已经交付。

M1 通过 A0 后记录 `A0 已通过，A1 内容待提供`，可继续 A0 巩固；不在运行时生成 A1 主线。A1 内容须按《学习引擎规格》第 5 节离线生成单元内容包并经确认冻结；只有 A0 通过且至少有一个已冻结的 A1 单元时才允许进入。A1 内容冻结前，入门定位只在 A0 内推荐起点；之后的定级规则见学习引擎 3.6。

## 2. 内容与生成契约

### 2.1 稳定身份与内容来源

阶段、能力、词句、课程、练习、素材均有稳定 ID 和版本。生成的变式有自己的 ID，并引用原能力及词句 ID，不能因措辞改变而产生新的核心掌握项。

内置种子内容需完成教学审校、答案校验及音频抽听后才标记 `approved`。外部网站和教材默认只作参考/外链；素材记录来源、许可或原创说明，不直接搬运。AI 生成内容标记来源为 AI，不能冒充人工审校。

### 2.2 最小课程结构（实现时转为有版本的 JSON Schema）

| 对象 | 必填内容 | 约束 |
|---|---|---|
| 课程 | schemaVersion、lessonId、revision、stageVersion、source、status、abilityIds、prerequisiteIds、targetItemIds、receptiveChunks、newItemIds、previewItemIds、estimatedMinutes、tasks | status 为 draft / validated / approved / rejected；只有 validated 或 approved 可学习 |
| 练习 | taskId、skill、type、prompt、stimulus、targetItemIds、answerSpec、rubricId、supportPolicy、variantFamilyId | skill 为 listening / speaking / reading / writing；题型限定在客户端支持的模板中 |
| 答案 | 判定方式、参考答案、可接受变体、必需信息槽、排除条件、简短解释 | 选择题有唯一答案；开放题不以字符串完全相等作为正确条件 |
| 素材 | assetId、文本、语言、音频来源/生成状态、来源许可、校验摘要 | 听力题答案与实际播放文本一致；无音频时不伪装为听力题 |
| 对话 | scenarioId、角色、允许词句、目标信息槽、最少任务要求、最多用户轮数、收尾条件 | M1 通常 3–5 个用户回答轮；简单种子任务可更短，不能为凑轮次重复提问 |

每个可展示的英文词块要能关联 `LexiconEntry`：entryId、词形/短语、音标（可选）、词性（可选）、适合当前阶段的中文释义、TTS/课程音频、一个已学例句、关联能力/词句 ID、版本与来源。点击时优先匹配最长已定义短语，如 `Nice to meet you`，再匹配单词；专名、数字和标点不强制提供词典条目。释义应服务当前句义，避免塞入完整词典义项或未学复杂例句。

一个教学分段最多新增 8 个词汇项、2 个需要主动产出的句型；数字、字母、星期较多时拆段，每段约 10–15 分钟，完成种子主题不等于只用一天。复习段可以没有新词。固定短语按词块教学，所含功能词不再逐词重复计算，但必须提供整句释义和音频；新增理解用词块每段最多 2 个，超过则先增加准备段。

10–15 分钟为整段合计，已包含预热、应用练习、受控对话和独立尝试；后续词句步骤用于句中应用而非重复词卡。每日 10/20/30 分钟的分配、积压阈值、复核降级均以《学习引擎规格》2.1、2.2a、3.2 为唯一执行规则。

每段必须标注 independentTaskIds 和各技能的完成状态；独立任务可复用对话最后一轮或写作题，时长约 30–90 秒。撤掉帮助后换内容值，恢复帮助则标记辅助，不当场无限循环；跳过保持待做。完整句写作从第 5 课逐步练，第 6–10 课落实自由输出，不用填槽证据代替出口能力。种子主题四技能机会映射见课程包。

有新增内容的教学段在正式任务前必须定义 `previewItemIds`：只包含该段会遇到的新增词汇和理解词块，通常 3–6 项，最多不超过本段的新词/词块预算。每项有词条、音频、当前句义与一项轻量匹配/听辨；可逐项重放、查词、跳过或回看。预热完成只记为 `exposed`，不产生掌握成功、失败或复习到期日；没有新增内容的复习段不显示预热。

对话额外新词指本段与已学内容之外的词：每轮最多 1 个、整段对话最多 2 个，先教学再使用；出口评估为 0。额外新词仅作扩展复习，不自动加入阶段核心分母。

### 2.3 每日生成流程

1. 本地规则先选到期复习、未完成任务或已满足前置条件的能力，给 AI 明确的目标 ID；没有薄弱项时正常复习或选下一个能力，不硬造错误。
2. 请求包含阶段版本、能力及词句白名单、理解用词块、个人薄弱项、提示策略、题型和新词预算。不发送真实电话号码；姓名、地点可使用虚拟资料。
3. 输出完整课程/练习对象，不能只返回一段聊天文字。对话单轮返回 reply、已提取信息槽、证据引用、完成建议和可选的一条反馈。
4. 本地检查结构、ID 引用、前置关系、必填答案、词句预算、轮次；专名与词形变化使用明示的允许表，不用简单英文词数误判超纲。
5. 用独立审核请求检查自然度、答案与材料一致性、难度及无提示可解性；可以同一模型，但输入不包含生成时的推理。审核失败或不确定不发布。AI 审核并非正确性保证，提供“内容有问题”入口，标记后隔离相关题目与评分证据并重新计算受影响状态。
6. 校验通过后保存版本，再展示。每个生成任务最多自动修复 1 次；仍失败则用同能力已审核的内置/缓存模板，不无限重试。若无可用变式，提供已审核原题复习并说明不是新迁移证据。

生成、审核、转写失败均不得改变掌握度。AI 只能提出判定，客户端根据证据和规则更新状态；不采信模型单独返回的“已掌握/可以升级”。

### 2.4 判题边界

封闭题优先本地判定。开放题返回 correct / incorrect / uncertain、原始作答证据片段、缺失信息和可选改进，不得补写用户未表达的信息。用户说出有效同义表达应接受；轻微大小写或标点不阻断表达成功。检测到无法确认的答案或用户质疑时记 uncertain，安排不同题重测，不直接降级或升级。

课程完成只表示完成教学任务，可以带提示或文字完成；词句掌握和阶段通过另按有效证据计算。离线自由写作可以保存为 pending，不假装已获得 AI 纠错。

### 2.5 查词与学习证据

教学模式中，课程正文、AI 消息、阅读材料、听力文字稿和纠错示例均支持点词/点短语；查词卡显示中文意思、原句、播放/慢放、一个简短例句，以及“加入复习”。如果当前内容来自动态生成，优先使用本地已审核词条；缺失时可请求文字 AI 生成**临时释义**，标记“待审核”，不自动加入核心清单或掌握计算。断网时只显示本地词条或“暂时无法查询”，不编造解释。

教学中点词、看释义或翻译不会失败，也不阻止完成课程；相应 attempt 记录 `lookupEntryIds`、`lookupCount` 与是否查看整句翻译。用户主动“加入复习”创建低优先级认识/回忆练习，不能直接标记已掌握；同一词条一天最多自动加入一次，避免误触堆积队列。

独立练习与出口评估默认隐藏查词、整句翻译、词库和句框。用户仍可选择“先查词再练习”，系统将当前题切换为教学态，清楚提示“本题不计独立听/读/说/写证据”，然后提供另一等价题补测；不把查词行为记为语言错误。查看词条本身不等于看答案，正式评估中不提供入口以避免该边界含混。

## 3. 本地数据最小约定

| 实体 | 必须保存的信息 |
|---|---|
| StageDefinition / AbilityNode | 阶段版本、核心项 ID、能力 ID、前置条件、出口规则版本、内容是否就绪 |
| Lesson / Task / Asset | 上述内容契约、生成/审核来源、版本、可用状态、缓存引用 |
| AttemptEvidence | 唯一 attemptId、taskId/版本、目标词句、技能、原始作答、输入方式、转写原文/修改后文本、确认/修改标记、提示/翻译/字幕/重放/查词词条次数、结果、判定来源、时间、variantFamilyId |
| PreviewExposure | lesson/段版本、词条 ID、首次/最后查看时间、播放次数、是否跳过；只用于恢复和推荐回看，不计掌握 |
| LexiconEntry / SavedWord | 稳定词块 ID、当前释义/音频/例句版本、来源与审核状态；用户收藏时间、复习状态、是否核心项 |
| MasteryItem | 稳定词句 ID、状态、首次正式教学时间、分技能证据、有效成功/失败引用、检查点、到期时间、需复核标记与复核阶段；必须能从证据重算 |
| StudySession / ConversationSession | 当前步骤、已提交轮次、信息槽、请求 ID、暂停/待反馈/完成状态；原始录音仅引用本机路径 |
| StageAssessment | 评估版本、题目版本、四技能结果与证据、提示情况、pending / passed / needsPractice / invalidated、补练目标 |
| ProviderConfiguration | 地址、模型、能力测试结果和时间；密钥仅存安全存储，不写入数据库日志 |

相同 attemptId 的重复提交只入账一次；证据、掌握状态和复习更新使用一次本地事务。网络重试不得产生多份学习成功。题目升级保留旧作答对应的旧版本；无效内容导致的结果失效需显示原因，而非显示“你退步了”。

一题多个目标时记录每个目标的证据片段、技能和结果，只对实际证明的目标更新，不把整句正确广播给所有词。每天同词句最多推进一次间隔。首次正式教学时间在释义/示范加首次应用尝试后登记；预热、查词、收藏及整课结束均不能重置它。复核中的词句暂不计入首次阶段升级门槛，既有阶段通过记录保留。

## 4. 语音边界和异常恢复

设备原生 STT/TTS 是否离线可用取决于设备、系统、语言包及权限，启动时探测，不作跨平台保证。原生识别也可能联网，首次使用说明数据去向；云端转写仅在用户启用后发送录音。M1 默认代理只接收文字。

| 情况 | 行为 | 学习证据 |
|---|---|---|
| 无网络/AI 未配置 | 内置课程、缓存/本机可用音频、本地答案题和模板复习；动态生成暂停 | 本地可判定题正常记账，开放题 pending |
| STT 无权限/不可用 | 保留录音回听（若录音权限可用），提供文字练习或稍后重试 | 文字不能替代口语达标，缺口为待评估而非失败 |
| TTS/音频不可用 | 可继续阅读/写作；听力题留待补做 | 不把看文本答题计为听力 |
| 转写无置信度、与回答目标不符或用户质疑 | 显示“我没有完全听清”，确认/修改/重说；无可靠置信度时统一先确认 | 修改后仅记文字表达；有争议的原语音不判错 |
| 超时/断网/429 | 保留已提交内容和当前轮；提示手动重试，429 按服务等待时间限制重试 | pending，不扣掌握度 |
| 401/403/模型不存在 | 引导修正配置，停止自动重试 | 不修改学习结果 |
| 非法 JSON/超纲回答 | 不展示为正式题目或计分结果；最多修复一次，转缓存模板 | 无合格结果则 pending |
| 退出/来电/重复点击 | 停止录音并保存步骤，返回时“继续上次练习”；请求结果按 ID 去重 | 不重复计分 |

默认单次 AI 请求 30 秒超时；用户可取消。切换服务由用户明确操作，不自动切换到另一付费服务。连接测试依次检查地址/鉴权、选定模型短文本、结构化返回；流式可选，失败时可使用非流式。测试会发送极短测试文本且可能计费，界面事先说明；兼容地址不意味着语音能力也兼容。

手机的 localhost 不是 Mac；设置页提供局域网连通性说明。远程连接使用 HTTPS，不通过不可信明文地址发送 Token，不关闭证书验证。测试和错误日志隐藏 Token 与敏感内容。

发音只提供示范、慢放、回听及可选通用提示。重复 ASR 错误不能诊断音素；转写准确也不等于已证明真人都能听懂。M1 的口语证据为受控场景下的有限代理指标，个性化音素诊断和更高阶段真人可理解度复核后续另行验证。

## 5. 开发顺序和验收样例

先完成一条纵向闭环，再扩展全部种子内容与平台；以下是待开发验收要求，不代表已经测试通过。

1. 本地一课：听力 → 跟读 → 阅读 → 写作 → 本地记录，中断后可继续。
2. 接入文字受控对话、结构校验、开放答案反馈和失败降级。
3. 接入录音、TTS、STT、转写确认和分技能证据。
4. 接入每日推荐、间隔复习、生成变式与 A0 四技能出口评估。
5. 完成全部种子段和评估题组的教学/音频审校；iPhone、Android 真机后完成 Mac 同流程验收。

| 编号 | 场景 | 必须结果 |
|---|---|---|
| AC01 | 完成 10 节但掌握不足 | 不解锁 A1，推荐当前阶段补练 |
| AC02 | 新生成 100 个扩展词 | A0 核心分母仍为 60，不覆盖旧核心 ID |
| AC03 | 看翻译答对听力、修改转写后答对 | 可完成练习，不记独立听力/口语成功 |
| AC04 | AI 声称通过但缺少必需信息 | 客户端不通过；显示待补信息或待确认 |
| AC05 | 缺一次复习/一周未打开 | 逾期项保留，不补造成功、不集中要求补做四次 |
| AC06 | 网络或识别连续失败 | 不因技术失败降级；可以本地练习且保留待评估 |
| AC07 | 相同题立即重做、重复提交请求 | 不增加独立间隔/迁移证据，不重复记账 |
| AC08 | 生成非法格式、错答案、超纲题 | 拒绝该结果，修复最多一次后使用合格模板 |
| AC09 | A0 门槛及两次四技能评估都满足 | 记录 A0 通过；M1 显示 A1 待提供，不编造 A1 课程 |
| AC10 | 口语待评估但文字全部通过 | 不标记完整阶段通过，给出补测入口 |
| AC11 | 清空数据 | 二次确认具体范围；仅删除所选本机记录，密钥单独管理 |
| AC12 | 手机和 Mac 分别练习 | 各自进度独立，界面不暗示已同步 |
| AC13 | 教学中点 `from` 或 `Nice to meet you` | 优先显示短语或词块的中文释义、音频、例句和加入复习；不退出当前学习步骤 |
| AC14 | 评估时尝试查词 | 提示先转为练习；当前题不产生独立证据，并提供等价题补测 |
| AC15 | 开始含新词的教学段 | 先显示仅覆盖本段的课前词汇预热；预热后进入课程，跳过不阻止学习 |
| AC16 | 只看完词汇预热 | 保存观看位置，可回看；不增加掌握度、不创建到期复习、不让课程自动完成 |
| AC17 | 10 分钟内未完成课程 | 保存下一步骤，预热和对话不重复计时；未做技能不自动完成 |
| AC18 | 结尾独立尝试时查词 | 允许继续，记辅助；下一次换题，不增加本次独立证据 |
| AC19 | 一题正确说 I like tea | 分别检查 tea 与 I like 的表达证据，不推断其他词或听力成功 |
| AC20 | 复习积压超过阈值 | 暂停推荐新段，交替照顾最早到期和近期错误，总预算不增加 |
| AC21 | 主题分三天完成 | 各词句从自己的首次正式教学日排期，不等主题结课 |
| AC22 | 已掌握项一次答错后复核成功 | 保留历史与状态，先 7 天抽查，再回 30 天；不重走四次 |
| AC23 | 第 10 课已说姓名地点喜好但未反问 | 留出反问机会；五项齐全才成功，上限缺项记待补练 |

## 6. 文档索引

本轮学习流程修订：统一教学总预算，增加撤提示的独立尝试，落实写作递进；复习改为按时间选任务并逐词句取证，按词句首次正式教学日起算；单次遗忘先复核；第 10 课统一五项完成条件。本轮修改仅涉及 Markdown 规格与文字线框，HTML 原型和应用实现尚未同步这些变更。

- [产品范围](PRODUCT-PRD.md)
- [学习引擎](LEARNING-ENGINE-SPEC.md)
- [A0 阶段标准](A0-STAGE-STANDARD.md)
- [种子课程](A0-COURSE-PACK.md)
- [AI 对话](AI-CONVERSATION-PRD.md)
- [技术架构](TECHNICAL-ARCHITECTURE.md)
- [页面交互](M1-WIREFRAMES.md)与[原型说明](PROTOTYPE-DESIGN-SPEC.md)