状态：首课实现已落地，自动化检查通过；真实模型与新手端到端体验待验收。当前验证范围见第 8 节。
本文继承 教程架构 与 总架构。通用生命周期、持久化、接口与事件契约不在这里重写；居民交谈与输入焦点沿用 居民对话系统。
用户完成首课后，能够找到自己的项目，向 AI 提出一个小改动，亲自体验结果，并给出反馈。完成作品只是中间目标，最后必须有一次减少提示后的独立迭代与项目续接。
首课暂以“待办清单”为样例：第一版只要求添加事项、标记完成，第二轮由用户选择一个小改动。课程文案与目标数据独立维护，不把样例名称写死在通用教程逻辑中。20～30 分钟是待用户试用验证的设计目标，不是强制倒计时。
教学分为三条线：项目目录意识、与 AI 协作、结果验收。必要的编程概念随问题解释，首课不要求记住所有居民和工具。
用户主动在向导处选择“带我做第一个作品”才开启首课。初次进入世界、普通交谈、停留时间过长或任务失败均不自动开启课程。已有未完成教程显示继续入口，暂停后不自动恢复教学。
教学载体：
- 常驻轻量目标卡：显示当前目标与继续入口，可以收起完整面板。
- 现有居民面板：在同一对话上方展示步骤、提示和检查入口，不创建第二套教学聊天。
- 作品查看入口：打开实际产物或安全预览；桌面可并排、窄屏可切换，具体预览能力先验证。
- 世界演出：阿澜出现、返回与带路用于建立文件夹管理意识；动画完成不作为步骤通过依据。
向导负责课程入口与恢复；芽芽负责需求和制作；阿澜负责项目命名、位置与新建/继续的选择；苔伯按需解释。普通项目选择入口继续可用，不能为了课程强制所有用户跑地图。
| 步骤 | 用户行动 | 教学表现 | 推进依据 |
|---|---|---|---|
| 开始 | 主动领取首课 | 向导解释“你提出想法并体验，芽芽协助制作”，交接居民面板 | 用户确认开始；创建课程准备记录 |
| 表达需求 | 向芽芽描述作品和最小功能 | 第一轮给可编辑示例；提示确定第一版范围 | 用户确认需求，保留待发送文本 |
| 给作品找家 | 无项目时接受阿澜提醒 | 芽芽与阿澜进行短交接，提供跟随或直接选目录 | 用户选择进入项目准备，不触发模型执行 |
| 准备项目 | 命名作品，选择存放位置，决定新建或继续 | 阿澜解释项目目录；显示实际位置并确认 | Workspace 绑定及学习记录关联成功 |
| 开始制作 | 回到芽芽确认原需求 | 恢复原文本，说明真实执行与首次审批 | 用户明确发送；读取 DSH 的接受与执行事实 |
| 体验作品 | 添加事项、标记完成 | 展示具体体验动作，以及“可正常使用 / 遇到问题” | 按课程定义记录实际检查或用户体验确认 |
| 自己改一次 | 提出并验收一个改动 | 撤掉完整示例，只给“现在怎样、希望怎样”的提示 | 改动有执行依据，用户体验并反馈；记录协助程度 |
| 下次继续 | 离开当前项目，再从工作记录返回 | 减少提示，让用户自行找到项目和原会话 | 有明确离开与恢复行为，用户确认能继续工作 |
最后回顾“作品放在哪里、怎样确认可用、下次如何继续”。不能仅凭模型回复、动画结束或连续点击下一步完成整课。
若制作中遇到问题，帮助用户描述操作、实际现象与预期，再回到当前步骤修正；不为教学故意破坏作品。没有发生问题时不强制插入故障关卡。
首版在教程内，用户明确提交“开始制作”的需求且尚无有效项目时介入。它不是打开居民面板就触发，也不使用模型猜测一句闲聊是否属于制作。
| 情况 | 行为 |
|---|---|
| 已恢复且没有绑定项目 | 保留需求，首次播放阿澜介入 |
| 已有有效项目 | 确认本次作品是否放在该项目；不重复飞来 |
| 项目目录仍在恢复 | 等待恢复或展示恢复状态，不误判为无项目 |
| 原项目失效 | 解释原项目不可用，进入恢复或重新选择，不说用户忘了建目录 |
| 用户暂停课程或普通交谈 | 不触发教学演出；自由创作仍使用常规项目前置检查 |
| 已看过介入又取消目录选择 | 保留当前步骤，展示继续入口，不反复播放整段 |
- 芽芽：“可以！先给这个作品找个家。”
- 阿澜传送出现在附近，再短距离飞入交谈位置：“等一下，你的作品准备放在哪里？每个项目都需要自己的文件夹，代码和图片才不会混在一起。”
- 阿澜：“来找我，我们给它准备一个家。刚才的想法已经留好了。”
- 提供“跟阿澜去”“直接选择文件夹”“稍后再说”。
- 选择跟随后，阿澜飞回自己的位置，给出可辨识的目标与路线提示。用户到达并交谈后打开项目准备。直接选择则在当前面板完成相同步骤。
- 准备成功后提示“这是你的项目，以后继续做它就打开这个项目”，提供“回芽芽那里继续”；恢复原需求，用户确认发送。
这段对白属于系统引导，不能伪装成模型即时回复。提醒强调作品需要存放位置，不用责备式“不对不对”。飞行路径、时长、镜头和距离在动画实现前结合场景确定，不在本文假设已可实现。
- 支持跳过演出和减少动态效果；用户选择不看动画仍可完成同一教学目标。
- 地图未就绪、路径不可达或演出失败时，以文本和直接选择入口继续，不让项目准备依赖动画回执。
- 演出期间切换项目、暂停或重新加载，应取消当前表现并恢复居民位置；不得改变既有任务状态。
- 同一次教学遭遇只允许一个实例；重复操作、重连或迟到的世界回执不能生成第二个阿澜或重复推进。
- 剧情对话打开时沿用面板输入规则；开始自主跟随时释放世界操作，避免面板阻止移动或意外发送输入。
阿澜必须让用户亲自作出三个决定：作品叫什么、放在哪里、创建新项目还是继续已有项目。不要只替用户操作目录选择器。
默认推荐专用练习目录，展示最终位置。用户选择已有非空目录时明确这是继续或复用已有项目，不自动复制模板、清空或覆盖文件。目录创建能力若不可用，应提供明确的手工准备路径，不声称已经建立目录。
项目准备后的反馈用实际 Workspace 信息生成，不以输入框里的名称当作绑定成功。选错、取消、权限不足和保存失败均停留在项目准备阶段，保留原需求。
当前按项目保存的草稿不足以覆盖“先提出想法、后选择项目”的流程。施工需新增课程准备期的待发送需求，先按准备请求身份保存；绑定成功后关联到 TutorialRun 与目标居民。它是草稿，不是已提交的 Session 消息。
需求续接必须满足：
- 跟随、直接选择、取消、刷新和模型设置过程中不丢原文；准备阶段尚无 Workspace 时也可恢复。
- 从准备记录转到项目学习记录时，同一需求只保留一个可发送身份，避免重复提交。
- 绑定文件夹不会自动发送模型请求；回到芽芽后仍有明确发送动作。
- 仅确认发送成功且用户未改写文本时清除草稿；结果未知时先核对提交状态。
- 多个页面不能把另一份准备草稿误绑到当前项目。保存失败应提示当前无法保证恢复，不静默宣称“已经记住”。
课程准备期间尚未建立正式项目学习记录的恢复身份，沿用教程架构的领取准备概念。阿澜演出已看/跳过标记与学习完成条件分开保存；刷新不会重播整段，也不能因为看过演出而跳过项目确认。
下表保留施工拆分和退出条件；实际完成范围及未验收项见第 8 节。不扩建通用课程引擎。
| 阶段 | 具体交付 | 主要边界 | 退出条件 |
|---|---|---|---|
| P0：接入核验 | 验证领域存储、准备记录、项目绑定/创建、跨端调用、检查执行与作品查看能力 | Host、DSH 公开接口 | 得到最小往返与恢复证据；能力缺口及退路明确 |
| P1：文本教学闭环 | 课程定义、主动开启、目标卡、准备草稿、无项目分支、直接选择、返回芽芽 | 教程 Host、React 居民面板 | 不依赖动画即可从需求走到绑定、确认发送；取消与刷新不丢需求 |
| P2：阿澜世界介入 | 传送飞入、返回、路线目标、到达交谈、跳过和减少动态 | 世界桥、Godot 居民与 React 协调 | 演出可取消、可降级，重复消息不产生重复角色或推进 |
| P3：制作与迭代教学 | 执行观察、首次审批解释、实际作品体验、问题反馈、自主改动 | DSH 会话投影、验收器、作品入口 | 完成一个作品及一次用户选择的改动，有真实依据 |
| P4：续接与首课验收 | 离开/返回项目、恢复原会话、回顾、结课 | 学习记录、居民关联、工作记录 | 新手在减少提示后能找回项目并继续，完成异常与浏览器验收 |
初步定位入口（实施前定点复核最新代码）：
- React 教学入口及居民面板：插件的
QCodeWorld.tsx与 Client 入口；提取必要的教学模块，避免继续将所有业务堆入单组件。 - 需求提交和居民关联：复用现有 Client / DSH 接口，准备期草稿与教程数据放入对应领域模块。
- 世界通信：同步修改
world-bridge.ts、Web shell 与 Godot 接收/发送端的校验。 - 世界演出：检查
island.gd、island_residents.gd现有居民定位、交谈与输入控制后再确定最小修改位置。
世界演出消息应携带教学遭遇身份及目标居民，返回开始、结束或取消等表现回执；最终消息名和载荷在 P2 定义。教学步骤不依赖演出回执作为通过证据。世界投影不得携带完整需求、凭据或项目绝对路径。
| 类别 | 必测场景 | 通过标准 |
|---|---|---|
| 触发 | 初次进入、普通聊天、主动制作、恢复中、已有项目 | 只有约定分支触发；不把恢复中或失效项目当作忘选目录 |
| 草稿 | 无项目输入后跟随、取消、刷新、设置模型、重新绑定 | 文本与准备身份可恢复，绑定后不自动或重复发送 |
| 文件保护 | 新目录、已有非空目录、权限不足、创建后中断 | 实际位置可确认，已有作品不覆盖，准备可以恢复 |
| 演出 | 重复触发、跳过、减少动态、不可达、切换/暂停/重载 | 单实例、能恢复居民位置、始终有直接操作退路 |
| 执行 | 真实审批、拒绝、失败、取消、答复丢失 | 引导反映事实，保留继续或处理入口，不伪造成功 |
| 教学结果 | 体验清单、自选改动、协助完成、作品再修改 | 验收依据明确，不把用户确认或代做标成独立掌握 |
| 续接 | 离开并返回、浏览器重开、Host 重启 | 恢复正确项目、学习记录与原会话，不重发任务或重播首次演出 |
| 真实体验 | 桌面、窄屏、键盘与真实世界交谈 | 目标可找，输入焦点正常，跟随与面板不互相阻断 |
各阶段先运行直接相关的领域与桥接测试，再做必要构建/导出。最终必须使用真实 Godot 世界验收阿澜介入和跟随；替代 iframe 或模拟模型只能证明部分流程，不能替代世界体验与真实作品验证。
新手试用重点观察：是否能说出作品存放位置、是否能找到原项目、是否主动体验 AI 结果、能否在没有完整示例时提出一个改动。目录绑定成功或课程状态变为完成都不足以单独证明学会。
2026-09-12 原生输入接入（已实现待验收）：建立会话后，需求与补充由 DSH 输入框发送，不显示自定义教程发送框；“检查成果”在当前项目会话中定位最近真实 user/message 的 rpcId，再要求对应回合完成、工具成功及作品文件有效。原生发送不自动附加首课指令，首课仍仅核对根目录 index.html。准备阶段表单保留。5 项教程测试通过，覆盖无第二输入框、跨项目拒绝、未完成拒绝及原生提交关联。真实模型首课和附件作品流程未验收。
2026-09-12 输入区补充（已实现待验收）：首课需求与补充输入使用同排发送按钮，完整动作语义保留于悬停提示。3 项教程展示测试、类型检查、构建和隔离世界浏览器桌面/窄屏布局检查通过；未重新执行真实提交。
2026-09-12 布局补充（已实现待验收）：绑定居民会话后，首课正文默认收为“首课进度”，输入继续在固定底部显示；会话建立前的准备步骤不折叠。浏览器隔离世界验证桌面与窄屏展开/收起及输入可见。首课领域逻辑未变，本轮未重跑模型、目录准备与完整首课。下述记录为历史验收。
- P0：接通 Cordis 教程子插件、DSH JSON 领域存储、Workspace 注册、Session 事件与有界文件读取。隔离 DSH_HOME 的真实 Host 启动成功，教程查询返回 200。
- P1：主动领取、准备期草稿、目标卡、项目命名/新建/复用、明确确认发送、暂停与恢复已实现。Host 保存学习记录；浏览器立即备份尚未保存的输入，保存命令固定绑定原 runId。新目录使用名称加唯一编号，创建中断后可通过“继续已有文件夹”显式恢复，不默认为已有目录取得所有权。
- P2：真实阿澜单实例飞入/返回、目的地标记、减少动态和中断复位已实现；文本与直接选目录始终可用。当前是目的地标记与飞行方向提示，尚未实现避障路线导航。
- P3：沿用居民会话和真实审批；用 DSH user/message 的 rpcId 定位本次回合，要求完成事件、成功工具记录与项目内 HTML 文件。预览隔离网络和主机，用户亲自体验后确认；错误反馈返回制作步骤，变更后的作品可重新核对。断线重试沿用原请求身份，由 DSH 对收件箱与持久消息去重。
- P4：自主改动必须有不同文件摘要；离开后从工作记录恢复并确认结课。完成记录表示执行核对与用户体验确认，不表示自动判定已经掌握。
实际检查：
补充交互：制作中保留“回答芽芽 / 补充说明”，回答使用新的请求身份继续原会话与当前步骤，检查转向这次回答的执行回合；上一请求尚未结束时拒绝登记新回答。回复草稿按当前请求在浏览器备份。审批沿用真实允许/拒绝按钮，目标卡提示待决定，不根据普通回复文本猜测审批或自动放行。已通过追问无工具不通过、执行中不能回答、跨会话拒绝、回答后执行可验收的回归场景。
corepack yarn build:web（含 TypeScript 编译）通过。node --test packages/qcode-web/tests/tutorial.test.mjs packages/qcode-web/tests/world-bridge.test.mjs packages/qcode-web/tests/resident-recovery.test.mjs：14 项通过。覆盖真实 JSON 领域存储关闭/重开、无项目草稿、过期 revision、跨项目会话拒绝、错误回合不借用后续成功、失败重试、预览变化、修正循环、自主改动与返回门槛。- Godot headless
tutorial_keeper.gd：6 项通过；embedded_hud.gd：12 项通过；既有residents.gd通过。演出测试加载真实岛屿场景，不使用替代世界。 corepack yarn build:world：字体检查与 Web 导出通过。git diff --check：通过（仅仓库已有的换行提示）。
验收限制：隔离实例未配置真实模型，尚未完成真实审批、模型产物、窄屏及新手完整走查；Headless 动画检查不等同于视觉与跟随体验验收。首课目前使用固定步骤与单文件 HTML，未实现通用课程解释器、检查历史列表或跨页面实时订阅；其他页面的变更以 revision 冲突和重新读取恢复。首课的作品检查证明文件与执行依据存在，具体功能是否可用仍由用户体验确认。