# 练习页交互与功能设计(Agent 专用) > **读者**:实现/自动化 Agent > **目标**:按本文即可 1:1 复刻探趣岛学习链路交互,并用 CDP **无需 LLM 翻译**完成答题抓取 > **依据**:`tanqudao-capture/deep-20261011/` 实测 + 复刻报告 + ARCHITECTURE v0.2 > **对照课**:`c-mn15edqe-qirc12`《新手英语生活场景入门》/ Lesson1 `l-mn15jfdn-ikcigx` > **材料根**:`task/tanqu分析/`(后续迁至 `tasks/tanqu分析/`) > **更新**:2026-10-11(合并打字答题实录 + lesson-sheet 字段证据) 相关文档(同目录或同任务包): - [`学习页1对1复刻报告.md`](./学习页1对1复刻报告.md) - [`ARCHITECTURE.md`](./ARCHITECTURE.md) --- ## 0. Agent 速查(先读这段) ### 0.1 页面路由 | 路由 | 作用 | |------|------| | `/app/courses` | 课程广场 | | `/app/courses/:courseId` | 课程详情 | | `/app/game` | **练习主界面**(所有答题模式都在这里) | 进入练习:详情页点 **继续学习**(已验证)或课节卡片。 ### 0.2 答题标准作业程序(SOP)— 禁止猜英文 ``` 1. 聚焦练习页(body / 输入框) 2. Space(或 ↓)→ 显示答案(底栏芯片变为「空格 隐藏答案」) 3. 从页面已揭晓的英文中复制答案(整句或当前空) - 优先读 .answer-item-top / .answer-curtain / .answer-sheet 内英文 - 打字模式亦可从 .typing-hero-sentence 拼出字符 4. 填入对应输入: - 拆句:input.word-input(第 N 个单词) - 整句/中译英/听写:textarea 或主输入 - 打字:input.typing-practice-input(可配合 .typing-key.is-blank) 5. Enter 提交 6. 观察反馈:correct-fx-canvas、van-icon-success.mode-check、sfx、进度 练习(i/n) 7. Shift+→ 或点「下一题 >」继续;Ctrl+; 重练当前题 ``` **不要**调用 LLM 翻译题目;答案以 Space 揭晓内容为准。 ### 0.3 关键快捷键 | 键 | 行为 | |----|------| | `Space` | 显示/隐藏答案(部分模式亦「跳格」) | | `↓` / `↑` | 答案 | | `Enter` | 提交作答 | | `Ctrl+A` | 朗读(播当前 voiceUrl) | | `Ctrl+;` | 再来一次(清空重练) | | `Ctrl+Q` | 不熟悉(拆句等) | | `Shift+←` / `Shift+→` | 上一题 / 下一题 | | 点击 `< 上一题` / `下一题 >` | 同切题(class `hk-key hk-nav`) | 底栏芯片 class:`hk-key hk-chip` / `hk-key hk-nav`。 --- ## 1. 范围 **在范围内**:广场浏览、课程详情、`/app/game` 多模式练习、快捷键、答后反馈、句表数据字段、音效、视觉 token。 **不在范围内**:开通会员/支付、发帖、合伙人、教辅广场完整交互。管理端(P2)延后。 --- ## 2. 信息架构与全局壳 ``` 侧栏 aside ~176px 首页 / 我的收藏 / 课程广场 / 教辅广场 / 复习本 / 发帖有奖 / 合伙人计划 / 开通会员 / 奖励明细 / 设置 / 深色模式 顶栏 header 56px(广场/详情) 咨询客服 / 建议反馈 / 用户胶囊(昵称·等级·今日时长) 练习页 /app/game 通常弱化或隐藏主导航,全屏深色练习台;aside=null ``` --- ## 3. 页面一:课程广场 `/app/courses` ### 3.1 布局 | 区域 | 说明 | |------|------| | 左栏 | 宽 ~176px;导航圆角 12px;当前项蓝光晕 `rgba(79,139,255,.3)` | | 顶栏 | 高 56px;半透明 `rgba(7,10,15,.72)` | | 分类 Tab | 全部 / 零基础 / 入门 / 初级 / 中级 / 进阶 / 高级 | | 卡片网格 | 封面 + 标题 + editorName + `N小节` | ### 3.2 功能 | 功能 | 交互 | 数据 | |------|------|------| | 分类过滤 | 点 Tab | 再请求 `GET /api/courses` | | 打开课程 | 点卡片 | 进 `/app/courses/:id` | 证据:`deep-20261011/01-plaza/`、`interactions.jsonl`。 --- ## 4. 页面二:课程详情 `/app/courses/:id` ### 4.1 布局 - 标题区:课程名、返回、小节数、累计练习时长 - 主操作:**继续学习**、**收藏** - 进度文案:如「学习进度 0%」 - 课节网格:每课一大按钮(英中标题、时长、完成次数、状态、#序号) ### 4.2 功能 | 控件 | 行为 | API | |------|------|-----| | 返回 | 回广场 | — | | 继续学习 | 进 `/app/game`,恢复进度 | `POST /api/practice/enter` → `{ok:true,data:{ok:true}}` | | 收藏 | 切换收藏 | `POST /api/favorites/courses/:id` | | 课节按钮 | 进该课练习 | 带 `lessonId` | 证据:`02-course-detail/`。勿把侧栏「开通会员」误判为付费墙。 --- ## 5. 页面三:练习 `/app/game`(核心) ### 5.1 区域划分 ``` ┌──────────────────────────────────────────────────────────┐ │ 返回(紫粉) 练习(i/n) 设置 切换模式 学习内容 重置… 全屏 │ │ 计时 mm:ss │ │ [拆句练习] [整句练习] [显示图片] ← variant-pill │ │ │ │ 主内容区(中文提示 / 空格 / 揭晓区 / 图) │ │ │ │ <上一题 CtrlA朗读 空格显隐答案 Shift切题 Ctrl;再来 下一题> │ └──────────────────────────────────────────────────────────┘ ``` ### 5.2 顶栏 pills | 文案 | class | 功能 | |------|-------|------| | 返回 | `back` | 离开 game;字色 `rgba(183,126,255,.98)`;圆角 12px;字号 12px | | 设置 | `pill pill-settings` | 设置面板(字段 **未确认**) | | 切换模式 | `pill pill-mode` | 打开模式面板 | | 学习内容 | `pill pill-content` | 句表面板 | | 重置进度 | `pill pill-reset` | 确认框 `reset-btn reset-confirm/cancel` | | 个性化 | `pill pill-personal` | **未确认**全字段 | | 报错 | `pill pill-report` | 音频有问题/拼写不对/翻译不准/排版错乱 → `report-submit` | | 沉浸模式 | `pill pill-immersive` | **未确认** | | 全屏 | `pill pill-fullscreen` | 全屏 | ### 5.3 变体 pills | 文案 | class | 功能 | |------|-------|------| | 拆句练习 | `variant-pill` | 多空填词;sheet `practice=split` | | 整句练习 | `variant-pill is-active` | 整句;激活蓝 inset 光晕 | | 显示图片 | — | 开关 `imageUrl` | ### 5.4 模式面板 | 模式 | class | UI 输入 | Agent 填答 | |------|-------|---------|------------| | 整句练习 | `variant-btn active` | textarea | Space 后整句填入 | | 拆句练习 | `variant-btn` | 多 `input.word-input` | Space 后按空填 | | 拼图模式 | `mode-card` | 词块(拖拽 **未确认**) | 优先 Space 对照 | | 听写模式 | `mode-card` | 音频+输入 | Ctrl+A 再听;Space 后填 | | 中译英模式 | `mode-card` | 中文+输入 | Space 后填 | | 打字练习 | `mode-card` | `typing-practice-input` + `.typing-key` | Space → type → Enter | 关闭:`mode-close`;确认:`restart-confirm-btn primary`。 进度 `mode` 例:`listening`;`full-source` → `{mode:"split"}`。 --- ## 6. 打字练习:输入单词答题(实测) ### 6.1 DOM - 主输入:`input.typing-practice-input` - 空白键:`.typing-key.is-blank.is-wide`;当前空 `is-active` - 题目:`.typing-hero-sentence` / `.typing-word` - 揭晓:`.answer-curtain` → `.answer-sheet` → `.answer-item-*` - `.answer-item-top` = 带标点目标(如 `Hi!`)← **填答优先** - `.answer-item-ipa-measure` = 词;`.answer-item-ipa-text` = IPA - `.answer-item-bot` = 句法;`.answer-single-zh` = 中文 - 反馈:`correct-fx-canvas`、`.van-icon-success.mode-check` ### 6.2 实测(`typing-answer/`,约 1/19→12/19) 流程:切打字 → Space 揭晓 → type 进 `typing-practice-input` → Enter → Shift+→ | 题 | before | answer | after | |----|--------|--------|-------| | q1 | 1/19 | Hello! | 3/19 | | q2 | 3/19 | Hello, | 4/19 | | q3 | 4/19 | I am | 5/19 | | q4 | 5/19 | Hello, | 6/19 | | q5 | 6/19 | Tom! | 7/19 | | q6 | 7/19 | Hello! | 8/19 | | q7 | 8/19 | Lucy. | 9/19 | | q8 | 9/19 | Hello, | 10/19 | | q9 | 10/19 | Lucy! | 11/19 | | q10 | 11/19 | to meet | 12/19 | 每题均见 `correct-fx-canvas` + `mode-check`;q10 `hasCorrectWord:true`。 完整:`typing-log.json`;分镜 `qN-before/revealed/typed/after-enter.png`。 提交后 input value 常清空,正常。 ### 6.3 其它跑通 - `practice-run/`:1/19→19/19(`practice-log.json`) - `practice-unstick/`:按钮 class 权威清单 --- ## 7. 拆句 / 整句 / 答后效应 ### 7.1 拆句 中文提示 + 多 `input.word-input`(「第 N 个单词」);字色 `rgb(65,98,255)`;揭晓后词+IPA+句法+cardCut。 ### 7.2 整句 主输入 `TEXTAREA`;`variant-pill is-active` 在整句上。 ### 7.3 答后效应 | 效应 | 证据 | |------|------| | 正确特效 | `correct-fx-canvas`、`van-icon-success.mode-check` | | 音效 | typing/nav/correct/wrong/complete → `/api/sfx/...` | | 进度 | `练习(i/n)`(打字可跳号 1→3) | | 上报 | `POST progress`、`add-time`;错句 `wrong-sentences` | 错答红闪 class:**未确认**。 --- ## 8. 数据契约 统一:`{ ok, message, data }`。 ### 8.1 `GET /api/courses` items≈89;categories:`all/零基础/入门/初级/中级/进阶/高级`。 item 样例:`id,title,category,lessonsCount,learnersCount,visitorsCount,hidden,cover,landscapeCover,editorName,editorColor,heatLevel` (`editorColor:"#f209d0"`, `heatLevel:5`, Luna) ### 8.2 `GET /api/courses/:id` + `lessons[{id,title,durationSec,hidden}]`;title 常 `English\n中文`。L1 共 10 课。详情响应无 heatLevel。 ### 8.3 `GET /api/lesson-sheet?courseId=&lessonId=&practice=split` ``` found: true columns: content|translation|cardCut|annotations|voiceUrl|imageUrl(带中文 title) rows: 62 alwaysText: [] stats: { totalRows:62, wholeSentenceRows:17 } ``` row 字段:`id,content,translation,wordTranslation,ipa,pos,syntax,cardCut,annotations,voiceUrl,imageUrl,rowType` 词行例:`content:"Wake up!"`, `ipa:"/weɪk/+/ʌp/"`, `pos:"动词+副词"`, `syntax:"谓语(短语动词)"`, `wordTranslation:"醒来+起"`, voiceUrl 有、cardCut/image 空。 整句行例(17 条):`content:"Wake up! It's morning."`, `cardCut:"/Wake up!/+/It's morning./"`, 有 imageUrl+voiceUrl, `wordTranslation:"醒来+起+是早晨+早晨"`。 练习 `i/n`(如 19)≠ 必等于 totalRows(62)。 ### 8.4 会话 API 实测 | API | data | |-----|------| | `GET .../practice/progress` | `{found,current,total,mode:"listening",updatedAt}` | | `GET .../practice/full-source` | `{mode:"split"}` | | `GET .../practice/course-status` | `{recentLessonId,completedLessonIds,completedCounts,totalPracticeSec,lessonPracticeSec}` | | `POST .../practice/enter` | `{ok:true}` | | `POST .../practice/progress` | `{ok:true}`(请求体 schema **未确认**) | | `POST .../practice/add-time` | `{ok, freePractice:{enabled,dailyMinutes:15,limitSec:900,spentSec,remainingSec,...}}` | | `POST .../review/wrong-sentences` | 存在(body **未确认**) | | `GET /api/sound-effects` | 五类 URL | --- ## 9. Design Tokens | Token | 值 | |-------|-----| | 底色 | `rgb(7,10,15)` | | main 底 | `rgb(0,0,0)` | | 字体 | Hind + 系统栈 + Microsoft YaHei | | 字号 | 16px;芯片/练习顶栏 12px | | 侧栏/顶栏 | ~176px / 56px | | 圆角 | pill 12px;variant/hk 10px | | 返回 | `rgba(183,126,255,.98)` | | 填空字 | `rgb(65,98,255)` | | 芯片底 | `rgb(27,28,33)` | | pill 底 | 白 4% | | 激活光晕 | `rgba(79,139,255,.3)` | | CSS 变量 | 根上几乎无 `--*` | --- ## 10. 实现清单(前端 Agent) **P0 页**:`/courses`、`/courses/:id`、`/game` 壳(pills、变体、hk、进度、计时) **P0 模式**:拆句 / 整句 / 打字;听写·中译英复用;拼图后续 **P0 反馈**:correct-fx、sfx、i/n、progress/add-time **数据**:`sheet_rows` 保留 cardCut/ipa/pos/syntax/voice/image --- ## 11. CDP Agent Playbook ```js // CDP 9222 → 已登录 /app/game await page.bringToFront(); await page.click('button.pill-mode'); await page.click('text=打字练习'); async function answerOne() { await page.keyboard.press('Space'); // 揭晓 const answer = await page.$eval('.answer-item-top', el => el.textContent.trim()).catch(() => null) || await page.$eval('.answer-item-ipa-measure', el => el.textContent.trim()); const input = await page.$('input.typing-practice-input') || await page.$('input.word-input') || await page.$('textarea'); await input.click(); await input.type(answer, { delay: 20 }); await page.keyboard.press('Enter'); await page.keyboard.down('Shift'); await page.keyboard.press('ArrowRight'); await page.keyboard.up('Shift'); } ``` 要点:先聚焦输入;以底栏芯片文案区分显隐/提交;答案只从 DOM 抄写。 脚本:`work/typing-answer.js`、`practice-shortcuts.js`、`deep-capture.js`。 --- ## 12. 证据索引 | 路径 | 内容 | |------|------| | `deep-20261011/01-plaza/` | 广场 | | `…/02-course-detail/` | 详情 | | `…/03-practice-*` | 进课 | | `…/04-game/` | game + keyboard-probe | | `…/practice-unstick/` | 揭晓填答 + 按钮 class | | `…/practice-run/` | 跑到 19/19 | | `…/typing-answer/` | 输入单词答题 | | `…/03-api-data/` | lesson-sheet 等 | | `tanqudao-capture/03-api-data/` | courses 列表/详情 | | `…/design-tokens.json` | tokens | | `…/interactions.jsonl` / `SUMMARY.json` | 日志汇总 | | `task/tanqu分析/docs/` | 本文档任务包 | --- ## 13. 未确认 / 已知坑 1. 拼图拖拽与完成判定 — **未确认** 2. 设置/个性化/沉浸全字段 — **未确认** 3. `POST progress` / `wrong-sentences` 完整请求体 — **未确认** 4. 错答红色高亮 class — **未确认** 5. 侧栏「开通会员」易误判付费墙 6. 无焦点时快捷键可能 no-op 7. Enter vs Space 在不同模式语义不同 — 看底栏芯片 8. 打字进度可跳号(1→3) 9. 详情 API 无 heatLevel,列表有 --- ## 14. 变更记录 | 日期 | 内容 | |------|------| | 2026-10-11 | 初版:复刻报告 + 打字答题实录 | | 2026-10-11 | 补强 API 样例/answer-* DOM;终稿落盘 `task/tanqu分析/docs/` |