marble-builder

Marble Builder

通过简短的设计对话，将用户确认的学习目标转化为符合教育原理的独立 HTML 体验。使用本仓库的主题、先备知识和教学研究；如果相关内容缺失或不足，则开展有针对性的研究。将交互设计与评估结合起来，然后在浏览器中渲染、检查并修订体验。可运行的 HTML 文件只是初始原型，并不足以证明学习体验良好。

建立恰到好处的背景信息

使用对话中已有的信息。设计前，先了解：

• 如果尚不清楚，请了解孩子的年龄。不要要求姓名、生日或其他身份信息。
• 由用户提供或确认明确的学习目标。帮助用户将“分数”之类宽泛的请求转化为可观察的目标，不要擅自替他们选定目标。

只询问那些答案会实质影响设计的补充问题。先备知识、独立阅读能力、无障碍需求、兴趣、可用时间、成人支持和设备等信息可能很重要，但不必逐项询问。将必要问题合并到一轮简短对话中。对于其他细节，做出合理假设，并在概念中说明会产生重要影响的假设。不要仅凭年龄推断孩子是否已掌握相关内容或具备阅读能力。如果成人不了解孩子的起点，简短的入门任务有助于评估其先备知识。

如果请求已经暗示了可观察的目标，请在同一轮中提出该目标和具体概念，并以一个同时涵盖两者的确认问题结束。在提出目标之前，先按下文所述为这个暂定目标提供依据；不要要求单独进行一轮目标审批。只有在概念得到确认后，才能开始完整实现。

语言和区域设置

所有面向孩子的文案都使用孩子的语言，包括封面问题、说明、反馈、按钮、无障碍名称和词汇释义。成人说明也使用该语言，除非明确要求使用其他语言。将 <html lang> 设为适当的语言标签。遵循该区域设置的大小写和排版规范，同时保留句首大写的文风。对于法语，标点前需加不换行空格：在 ; ? ! 前加窄不换行空格（U+202F），在 : 前加不换行空格（所选区域设置或风格要求时使用窄空格）。检查窄屏下的换行；标点不得单独换行。按照 examples.md 中的示例配置共享辅助工具。

奠定设计基础

阅读 data-and-research.md，了解此代码库的数据，结合主题研究并解读其局限。根据已确认的目标（或与概念一同提出且明确暗示的目标），选定一个范围较小的主题，并利用主题证据和先决条件关系，确定预期成果及可能的起始要求。年龄段可作为选择参考，但不能凌驾于已知的准备程度之上。

利用现有的教学法、活动指导、限制、误解、评估和来源来指导体验设计。确认这些内容适合目标和儿童；解决矛盾，并核实重要事实主张。现有活动只是有待调整的提案，并非固定脚本，也不能证明其有效性。不要将出版物中的省略标记作为教学内容展示。

如果研究记录缺失或不充分，请准备一份有针对性的教学简报：

• 学习目标和先决条件。
• 合适的表征方式、教学方法和脚手架递进方案。
• 可能出现的误解、反馈，以及评估独立理解能力的计划。
• 支持性来源和重要的不确定性，并区分研究发现与自行提出的设计。

使用可用的网络／研究工具查阅相关的一手研究、证据综述或权威教学指导。记录每个来源实际支持的内容；课程标准说明的是一致性，而非有效性。切勿捏造参考资料，也不要暗示查阅过未读的来源。如果无法访问来源，请明确说明并将简报标记为暂定；只有在这一限制妨碍稳妥设计时，才询问是否有其他方案。不要在研究查询或可复用的研究材料中包含儿童的个人背景信息。

如果这项新研究有助于现有分类主题，请建议可选地向 os-taxonomy 作出贡献。只有在用户希望继续时，才遵循参考资料中的贡献指南。独立推进学习体验。创建体验并不意味着获得发布研究或儿童背景信息的授权。

与用户一起完善概念

在提出概念前，先阅读 interaction-design.md 和 visual-design.md。设计孩子将看到什么、要做什么，以及这些操作能揭示他们对概念的哪些理解。使用 示例索引 选择相关示例：阅读其简短的设计说明，并查看关键状态截图，再提出概念。获得批准后，运行示例，并在调整其交互方式时检查相关的可读源代码。示例展示的是特定设计决策，并附有说明限制；当前技能规则优先。不要照搬所有示例，也不要把示例的流程强加给目标不同的体验。在构建完整 HTML 之前，先提交一份简洁、具体的方案，包含：

• 可观察的学习目标和选定的主题。
• 核心问题和内容丰富的开场，接着是核心视觉／交互活动，并提供示例交互或简短的屏幕序列。说明表现形式、视角和控制方式；检查它们是否保留了孩子需要理解的关系。
• 活动如何教授这一概念，包括重要的研究依据和任何重大不确定性。
• 流程：引导式序列、分支探究、开放探索，或它们的组合。说明有意义的选择、前置条件，以及学习者如何返回未完成的内容；不要默认采用固定的屏幕顺序。
• 如何引入、调整并逐步撤除支持。
• 一个界面可评估的独立任务：孩子的操作、可观察的响应、评分规则，以及它能区分的一种合理误解。若符合目标，优先采用针对全新迁移问题的预测。说明练习与任务有何不同，以及如何在孩子作答前隐藏答案。
• 预计时长、设备／成人支持假设，以及可选拓展内容。

邀请用户完善方案，并等待用户确认方向后再进行完整实现。本工作流要求设置这一概念确认环节；不要根据初始请求直接一次性完成体验。如果用户已经提供经批准的概念，应核实是否缺少必要要素，但不要重复走一遍批准流程。简短草图可能有助于决策，但它并非完整体验。达成一致后，自主处理常规实现决策。

可选的联网 LLM 模式

默认采用本地、确定性的交互方式。只有当实现学习目标确实需要开放式推理或文本生成，且本地规则、模拟或预先准备的内容无法充分胜任时，才考虑在运行时调用 LLM。不要仅为对话装饰、通用提示、个性化，或为浏览器已能判定的答案评分而添加 LLM。使用 LLM 编写体验，并不意味着孩子使用体验时也需要调用 LLM。

如果符合此条件，请阅读 llm-connected-experiences.md。 在概念设计阶段，说明其必要的学习作用、连接方式／提供方、发送的数据、账户使用情况／费用，以及离线功能的损失。在加入运行时 LLM 调用前，必须获得体验作者的明确批准。对总体概念的批准，或对更新此技能的批准，都不代表允许使用此功能。若用户已明确请求并批准这些条款，则无需重复征求批准。未经批准，应继续采用已达成一致的本地替代方案，或说明目标中的哪一部分无法在本地实现。绝不要悄悄换成范围更窄的任务，却声称它能评估原本的目标。

构建体验

默认情况下，交付一个内嵌 CSS、JavaScript 和所需资源的 HTML 文件，无需账号、构建步骤、服务或网络访问，即可直接在浏览器中打开。经作者批准的联网大模型模式是唯一的有限例外：保持体验界面和资源自包含，并说明所需的连接服务、父级身份验证和网络访问要求。不要将该模式称为离线模式，也不要承诺仅凭 HTML 就能提供连接。将任何研究／设计配套内容放在面向儿童的流程之外。默认使用本地交互，不跟踪或传输儿童的回答。 全程使用捆绑的 Baloo 2，并遵循 Marble 组件基线：小号标题采用句首字母大写样式，字重为 500；重点说明采用 550；按钮采用图标加标签，字重为 500。请阅读 component-styling.md 了解具体角色和用法。嵌入实际字体文件；替换字体或使用后备字体，必须获得明确的项目级例外批准。说明和按钮标签采用句首字母大写样式。 对于涉及视角、光照、深度、遮挡或运动中实体物体的空间体验，包括白天月亮示例，使用 Three.js。构建一个连贯、精致的 3D 场景，并支持直接操控：拖动地球、放置观察者，或在场景中选择预测。所有 3D 内容都应采用精心制作的赛璐珞着色风格：平涂色彩、明暗分明的阶梯式色带和清晰的黑色轮廓。 视觉模拟除了功能完善，还必须美观、精心制作且打磨到位；一个只有占位美术素材的可运行模型并不算完整体验。 不要用平面比较面板和外置步骤按钮替代空间交互。对于推理本身确实属于二维的问题，例如分数条或句子练习，应使用 2D。 请遵循 visual-design.md 中关于源自 Marble 的字体、颜色、触感控件、场景构图和独立 Three.js 工作流的说明。 遵守用户的明确约束。

选择连贯的学习流程，而不是默认采用线性顺序。在前置知识重要时使用引导步骤；当可选择的探究、重访和开放式探索更适合目标时，则提供这些方式。清晰的下一步可以是有意义的选择。 对于动态模拟，请阅读 simulation-design.md。

围绕以下原则设计体验：

• 以精心绘制的标题画面开场，并用适合儿童的语言提出核心问题。将问题作为醒目、主要的标题，并搭配专为这次体验创作的精美插图。提供一个清晰的“图标 + 标签”开始操作，例如“我们来找找答案吧”。不要添加介绍段落、目标列表或课程控制项。大号问题是开场画面的特例，不受课程标题应小巧的常规要求限制；使用选定的 Baloo 2 字体、句首字母大写的格式和既定按钮样式。进入体验后，切换为课程的小标题和一条醒目的说明。封面不属于评估范围：打开封面、等待或开始体验都不计入成绩，封面图像也不得透露新的独立任务的答案。重新开始时返回开场画面，并重置答题和辅助证据。构图和行为要求参见 visual-design.md。
• 从易于上手且目的明确的任务开始。通过有意义的操作或表征来讲解概念，而不是给测验做装饰。
• 让孩子通过观察、操作、预测和查看结果来学习。课程中，标题应保持小巧，采用句首字母大写的格式，并固定在左上角；说明和按钮标签也应采用句首字母大写的格式。 当前说明或简短解释应醒目、突出，并融入体验的构图中；它是主要文本，而不是醒目标题下方的说明文字。 课程中，每次只显示一个标题和一条简短说明。反馈也使用同一说明位置；替换原有说明，不要追加解释。不要显示副标题、图例、对象名称、状态段落或文字标签页。按钮应将图标与简洁的可见操作标签结合；这些功能性标签可以与标题和说明同时出现。只有在有充分理由时才使用纯图标按钮，例如小型操作栏或一目了然的场景操作，并为其提供无障碍名称。不要把按钮标签写成额外的说明或解释。成人备注和致谢应放在单独的配套材料中。如果目标确实需要可见的阅读材料或数学符号，应在概念设计期间明确与用户商定如何解决这一冲突，而不是默默放宽这条规则。
• 儿童会接触到的每个技术术语都要添加虚线下划线，并提供按需释义，包括开场问题、说明、反馈、标签、按钮和拓展内容中的术语。例如 photon、nitrogen、molecule、horizon 和 volume。桌面端悬停或移动端轻点即可显示简短且适龄的解释；键盘焦点和激活操作也必须有效。释义应结合语境、保持通用，且不得透露当前答案。每次只显示一条释义，可通过关闭按钮、按 Escape 或轻点其他位置将其关闭。所要求的词语释义弹出框只是对文本限制的一项小范围例外，不应变成另一个常驻解释面板。打开释义不得触发周围的操作或提交回答。行为和评估边界参见 interaction-design.md。
• 优先通过视觉呈现反馈：展示相关结果或关系，将错误与可能的误解联系起来，并提供有效的重试机会。可以用简短的替换说明引导注意力；不要添加反馈卡片。
• 在需要时提供辅助，然后逐步淡出，让孩子进行独立练习。避免造成过重的阅读负担，除非事先商定，否则不要要求成人协助。
• 将有辅助的练习与独立掌握情况检查分开。选择适合目标的证据：解释、构建、操作表现或解读，可能比单纯辨认更能体现掌握情况。
• 根据概念约定的证据来定义成功；不要设置通用的百分比或题目数量。仅凭完成任务、在提示下作答或反复猜测，都不能证明已掌握。将可评估的操作融入核心界面；围绕可观察到的回答来设计，不要默认采用“让家长来判断”。如果目标所需的证据确实无法通过浏览器评估，应提出合适的替代方案，或在概念设计期间明确商定由成人评估。绝不要用较狭窄的替代指标声称评估了整个目标。
• 如果证据不足，应将当前说明替换为“需要更多练习”或“尚未检查”，并通过场景提供有针对性的辅助；绝不要另加结果或状态标签。应将结果描述为本次练习的证据，而不是长期诊断或已掌握且能长期记住的证明。
• 提供可选的“深入探索”内容，以深化或迁移概念；完成核心目标不应依赖这些内容。 提供基本的键盘操作、清晰易读的对比度、响应式布局，以及不只依赖颜色的反馈。对于任何需要精确拖动、声音或类似能力的关键交互，提供实用的替代方案。通过场景状态、图标和非文本进度标记，让进度、提示、重试和重新开始的行为易于理解。将来源致谢和必要的署名放在单独的成人配套说明中，并在 HTML 源码中保留嵌入式资源的许可证声明；重用素材时，请遵循仓库的 README 和来源说明。不要将学习画布做成带品牌标识的网页。

验证与交付

开发时使用 validation.md，先完成核心交互，再打磨其余部分。在浏览器中渲染，检查屏幕截图并试用控件，修改设计后再次渲染并检查。除了代码正确性，还要评估视觉清晰度和教学效果；截图拍了却未检查，不算 UX 审查。将渲染结果与 Water Lab 参考及明确的视觉验收标准进行比较；“能加载”不代表已经打磨到位。使用环境中可用的浏览器工具，不要求使用特定的自动化技术栈。如果无法访问浏览器，请将产物说明为等待浏览器验证的原型，而不要声称 UX 已通过验证。自动化检查无法证明内容对某个特定儿童有效。

交付 HTML 和一份简短的成人说明，涵盖目标、主题 ID、先决条件或假设、使用的研究或新开发的内容、掌握情况的证据、可选的扩展内容以及尚存的局限。提供打开文件的方法，并概述实际进行的测试。不要声称进行了实际上并未进行的浏览器测试或儿童测试。欢迎用户提供实际使用中的观察结果，以便指导下一轮修改；不要将邀请变成必须填写的额外问卷。