[Feature]: 恢复首个 AI 实践课程并完成真实学习闭环

[ruijayfeng]

提交前检查

• 我已搜索已有 Issue，确认没有相同建议。
• 这个建议符合“在真实项目中由 AI 陪伴学习和创作”的产品方向。

主要受益者

初次使用 AI 编程的学习者

要解决的问题

当前产品已经能够选择真实项目、配置模型、进入居民会话并让 AI 执行任务，但默认流程是自由创作。第一次使用 AI 编程的用户仍需要自己理解以下关键概念：

• 为什么要先选择项目目录；
• 怎样把想法描述成可执行的小目标；
• 工具审批意味着什么；
• 为什么不能只相信模型回复，而要查看实际作品；
• 结果不符合预期时怎样在原会话继续修正；
• 下次怎样找回原项目和原会话。

仓库中已经保留首课的学习记录、项目绑定、执行证据、作品预览、再次改进和恢复逻辑，但入口目前被隐藏，真实模型与完整新手体验也尚未验收。继续扩展岛屿或课程内容前，需要先确认并跑通这一条最小学习闭环。

建议方案

恢复一条主动选择、可以暂停、不影响自由创作的首个 AI 实践课程。它是一堂真实创作入门课，不只是按钮导览，也暂不扩建成通用课程平台。

建议用户流程：

1. 用户从“创作手册”主动选择“学习 AI 创作”；已有未完成记录显示“继续学习”。
2. 用户先描述一个小作品或最小需求。
3. 用户创建或绑定一个真实项目目录，并能看到实际位置。
4. 到真正发送任务时检查模型配置；项目准备阶段不强制先配置模型。
5. 用户在真实 DSH 会话中发送需求，并理解、处理真实工具审批。
6. AI 完成后，课程依据真实回合和工具记录检查作品文件；用户打开安全预览并亲自确认体验结果。
7. 用户在减少提示的情况下提出一次自己的修改，重新检查结果。
8. 用户离开当前项目，再从创作手册找回原项目和会话，完成课程。

自由创作仍是默认路径。普通进入小岛、普通居民交谈、任务失败或停留时间过长都不应自动开启课程。

拟议范围

本 Issue 包含

• 恢复首课的主动开始、继续、暂停和恢复入口；
• 复用现有 TutorialRun、居民会话、DSH 执行与审批，不创建第二套聊天或执行历史；
• 校准当前 Q、阿澜、苔伯的角色名称与职责，清理已不符合现状的教学文案和分支；
• 在发送 AI 任务、检查作品、再次修改和找回项目几个关键节点提供清晰说明；
• 保留刷新、目录选择取消、项目失效、执行失败、拒绝审批后的继续路径；
• 同步中英文界面与相关施工文档；
• 使用真实模型和真实小岛完成一次人工端到端验收，并准确记录尚未覆盖的限制。

本 Issue 不包含

• 通用多课程解释器、课程市场或内容编辑器；
• 新增第四座岛、重做岛屿美术或区域分包架构；
• 用 Godot 动画、连续点击或模型自述代替学习验收；
• 自动判断用户已经独立掌握 AI；
• 修改 deepseek-harness submodule；
• 手机触控完整适配。

只有一门首课时，课程步骤可以保持针对该课程的具体实现。等出现第二门真实课程、并确认两门课程确实共享稳定行为后，再建立课程定义接口，避免提前引入没有实际变化对象的通用抽象。

责任与数据约束

• DSH 继续拥有 Workspace、Session、工具执行、审批和执行历史。
• agent-isles Host 拥有课程进度、步骤结果和教学验收依据。
• React 提交学习意图并呈现课程、原生会话和作品预览。
• Godot 只负责空间交互与学习状态演出，不直接推进课程、不执行工具，也不持久化权威学习进度。
• 项目目录、提示词、令牌和权限详情不得通过世界桥暴露给 Godot。

完成标准

• 用户可以主动开始首课，自由创作入口和既有项目流程不受影响。
• 未完成课程可以暂停、刷新、重新进入页面和 Host 重启后继续，不自动重复发送任务。
• 项目绑定成功前不宣称项目已准备完成；取消目录选择不会丢失用户想法。
• AI 请求进入当前项目的真实 DSH 会话，真实审批仍由 DSH 处理。
• 课程检查绑定到本轮真实用户消息、完成回合、成功工具记录和项目内作品文件。
• 用户必须打开作品并明确确认，模型回复或世界动画不能单独使步骤通过。
• 第二轮修改产生不同的作品依据，不能借用第一次结果结课。
• 用户离开后能从创作手册恢复正确项目和原会话，且不会建立重复居民关联。
• 模型失败、拒绝审批、取消、断线或作品不满足条件时保留明确的修正/重试入口，不伪造成功。
• 中文和英文流程均可用；相关 Web 测试、构建和必要的 Godot 桥接测试通过。
• 使用一套专用测试项目和真实模型完成桌面端人工走查，并记录窄屏与其他未验收范围。

建议的实现拆分

1. 入口与展示：恢复创作手册中的开始/继续入口，恢复首课面板，并将教学编排从大型世界页面中提取到聚焦模块。
2. 真实执行闭环：核对模型配置时机、原生会话、审批、作品检查与安全预览。
3. 恢复与异常路径：覆盖刷新、暂停、目录取消、项目失效、失败、拒绝和断线。
4. 端到端验收：真实模型、真实世界、桌面与相关窄屏走查，更新施工状态和已知限制。

每一步可以独立提交，但建议在同一关联 Issue 下保持一个聚焦 PR；如果实现范围明显扩大，再按入口恢复、恢复可靠性或世界演出拆分 PR。

考虑过的替代方案

先开发通用课程引擎

目前只有一门真实课程，尚无第二个课程实现验证共同需求。提前抽象会扩大接口、迁移和测试范围，因此不建议作为当前前置条件。

直接新增教学岛并把课程写进 Godot

这会让世界同时持有表现和学习真相，刷新、断线、审批与会话恢复都更难保持一致。新教学岛可以作为后续视觉呈现，但课程进度仍应由 Host 管理。

只增加操作提示或首次使用弹窗

这只能帮助用户找到按钮，无法证明用户经历了真实 AI 执行、检查结果、修正和续接，不满足“在真实项目中学会使用 AI”的目标。

需要维护者确认

在开始实现前，希望确认以下产品选择：

1. 首课入口是否只放在“创作手册”，不在首次进入时自动弹出？（建议：是）
2. 是否允许用户先完成想法和项目目录步骤，到首次发送任务时再要求配置模型？（建议：是）
3. 首版是否继续使用当前单文件 HTML 小作品作为固定练习，不在本轮扩建通用课程格式？（建议：是）
4. 用户可见名称是否使用“AI 创作入门”，而非容易被理解为普通操作导览的“首次使用教程”？
5. 新教学岛、区域加载扩展和岛屿玩法是否在本 Issue 通过并跑通首课后分别开 Issue？（建议：是）

后续候选 Issue（不阻塞本提案）

• 将硬编码的三岛位置、镜头、回响范围和加载逻辑整理为可扩展的区域模块；
• 将当前统一的邻岛资源包改为按区域加载，控制新增岛屿的初始下载成本；
• 设计一座承载学习地标和完成状态演出的 AI 学习岛；
• 增加“描述需求—执行—检查—修正”相关岛屿玩法，但不让玩法状态替代真实教学证据。

相关实现与文档

• packages/agent-isles-web/src/tutorial.ts
• packages/agent-isles-web/src/client/Tutorial.tsx
• packages/agent-isles-web/src/client/AgentIslesWorld.tsx
• games/mosslight/scripts/island_residents.gd
• docs/tutorial-architecture.md
• docs/first-vibe-coding-tutorial-plan.md
• docs/construction-plan.md

[ruijayfeng]

看到 #19 已明确将首课教学交由 #13 跟踪。我准备按本 Issue 中建议的五项默认方案，从最新 master 开始实现首批「入口恢复与测试覆盖」；如果范围需要调整，请告知。

[Qiuner]

@ruijayfeng 首批可以先做现有首课的入口与恢复逻辑梳理、相关测试，并尽早发 Draft PR。不过这里补充一下最近讨论的产品方向，请不要将正文中的五项建议视为全部已经确定。

教学未来需要覆盖 Coding、图片生成和其他 AI 能力。我们希望把课程内容、学习进度、能力调用与界面呈现分开；这不要求本 PR 实现通用课程引擎、图片生成接入或编辑器，但也不要把新的公共教学接口绑定成只能处理 HTML/Coding。

本批边界建议如下：

• 教程由用户主动开启，自由创作仍为默认；首次进入不自动弹出课程。
• 到真正调用模型时再检查配置；不要把项目目录要求推广为所有未来课程的必经步骤。
• 苔伯保持项目与历史管理职责，不恢复他的教学职责。正文提到的“创作手册”入口位置和课程名称需要结合当前 UI 再确认；请先贴出入口方案或截图，再定最终呈现。
• 可以用现有 HTML 首课验证入口、继续、暂停及恢复，但它是具体课程案例，不是所有教学形式的固定模板。
• 保留 DSH 原生会话、执行和审批，不新增另一套执行历史；本批不改生产 runtime，也不扩大到新岛屿或世界玩法。

请先说明预计修改哪些模块、补哪些测试，以及入口打算放在哪里。多类型课程的具体契约尚待对齐，可以先推进不依赖该决策的测试与现状梳理；无需在这次 PR 中独自完成整个教学底层。

[ruijayfeng]

收到边界补充。按"先贴入口方案与截图"的要求，首批方案如下，确认后即开工并尽早发 Draft PR。

入口方案（附当前 UI 截图）

截图为当前 master 实际运行 UI：左上角书本图标打开的"创作手册"目前只有"自由创作"区。

1. 主入口：创作手册内新增"跟着学"区，与"自由创作"并列。无未完成记录显示"开始学习"；有未完成记录则逐条显示"继续学习 · {项目名}"。全部为用户主动点击，自由创作仍是默认，首次进入不自动弹出任何课程。
2. 恢复卡：存在未完成记录时，小岛上显示持久目标卡（.town-tutorial-goal 样式仍在仓库，零新样式），一键回到当前步骤。
3. 欢迎对话第三选项"带我做第一个作品"（继续则"继续第一个作品"）。

课程用户可见名建议 "AI 创作入门"（问题 4），"跟着学"为区标题；两个词都不绑定 HTML/Coding，未来其它能力课程可复用同一入口区而不复用步骤实现。

预计修改模块

文件	改动
packages/qcode-web/src/client/QCodeWorld.tsx	恢复 tutorialPanel（现为 const tutorialPanel = null）；手册"跟着学"区；目标卡；enterLearning 接线；恢复 c981da5 移除的 4 处门禁（idea/folder 步骤免项目选择、免会话绑定、workOpen 豁免、自由创作时自动暂停）
packages/qcode-web/src/client/Tutorial.tsx	补 leave 实现（清项目态并禁止自动回填，否则 return 步骤无法完成）
packages/qcode-web/src/client/locales.ts	入口与目标卡文案 zh+en 新键（旧入口文案在 i18n 迁移前删除，无存量键可恢复）
packages/qcode-web/src/tutorial.ts	仅一处文案："请从工作记录继续" → "请从创作手册继续"（面板已更名）
docs/first-vibe-coding-tutorial-plan.md、docs/construction-plan.md	校准"向导/芽芽"旧词为 苔伯手册/Q；总索引"暂时隐藏"改"实施中"

关键边界落实

• 模型配置时机：现 enterLearning 在点击入口时就要求 modelState.ready——与本批边界冲突，将移除该门禁；提交路径已有 prepareResidentModel（client/index.ts），idea/folder 阶段完全不碰模型配置，到真正发送任务时才检查。
• 不绑定 HTML/Coding：本批不建通用课程引擎、不新增公共教学接口；TutorialRun/steps 保持首课具体实现；入口区文案中性。
• 苔伯：只承载创作手册（项目与历史管理），教学仍是 Q（执行）与阿澜（folder 步骤引导）；无恢复其教学职责的文案。
• DSH 原生会话、执行、审批零复制（教程只读事件作证据）；不动生产 runtime、新岛屿与世界玩法。

补哪些测试

1. 新增 packages/qcode-web/tests/tutorial-entry.test.mjs（进入 CI *.test.mjs glob）：无记录时手册显示"开始学习"且自由创作区不受影响；有未完成记录显示"继续学习 · {项目名}"；入口点击不自动提交任务；idea/folder 步骤不要求模型配置（入口无 ready 门禁，检查发生在提交）。
2. 孤儿文件处置：tests/handbook-browser.mjs 无调用方且仓库无 Playwright 依赖，断言已过时——拟把可迁移断言并入新测试后删除该文件；如维护者希望保留浏览器级回归请说明，我改为接线方案。
3. locales.test.mjs 的 zh/en parity 守卫自动覆盖新键；tutorial.test.mjs（reducer 11 项）与 tutorial-presentation.test.mjs（面板 4 项）不需要改——本批不动 reducer 语义。

若入口位置、区标题与课程名无异议，我按上述开工；首批 PR 只做入口恢复与测试覆盖，暂停/恢复可靠性与端到端验收随后分批。

[Qiuner]

首批方案可以按你列出的范围开工并尽早提交 Draft PR，入口位置、“跟着学”区标题和“AI 创作入门”课程名本批无异议。

范围按以下边界执行：

• 教程只由用户主动开启，自由创作保持默认，首次进入不自动弹课。
• idea / folder 阶段不提前要求模型配置；真正提交模型任务时再沿用现有检查。
• 本批只恢复入口、继续/暂停/恢复接线及对应测试，不建设通用课程引擎，不把公共契约绑定到 HTML/Coding。
• 苔伯继续只承担项目、历史和创作手册入口职责；真实执行、会话和审批仍由 DSH 原生能力承载。
• 可以迁移 tests/handbook-browser.mjs 中仍有效的断言后删除孤儿脚本，但请在 PR 中列明迁移对应关系。
• 文档状态只记录本批实际完成范围；真实模型端到端课程未执行前不得标为“已验收”。

请在 Draft PR 中附入口桌面与窄屏截图，并分别列出自动化已覆盖、真实模型未覆盖和后续批次。