示例体系

Norm 有五类示例。每一类有明确的源码归属，分别回答不同的问题。

类别	读者要完成的事	源码归属
网站展示	判断为什么使用 Norm	主仓库中的可执行展示文件
norm hello	在本地探索五个完整程序	主仓库中的单一 CLI 模板源
语言	查看语言特性的准确行为与组合	主仓库中的专业示例
教学	一次学会一个特性	主仓库中的独立教学示例
库	调用真实 API，完成常见场景	各库仓库的 samples/

英文和中文页面共用代码。页面展示维护中的源码文件，不复制第二份示例。语言说明和参考页面可以引用专业语言示例；教学页面使用自己的短示例，不直接引用专业示例源码。语言和教学示例可以为说明当前特性而使用库，并链接到该库 samples/ 中的完整用法。

网站展示

展示区有三个入口：

1. Simple： 短小、可立即运行的程序，附命令和输出。
2. Agent first： 从 @Document 读取声明意图，查询语义和相关声明，按需查看源码与测试，预览重命名，由 Agent 应用编辑，再展示结构化检查和测试结果。
3. Application development： 可切换的聚焦示例，涵盖数据模型、表达式结果、清晰调用、字段响应式、类型化行为和完整类型信息。

每个示例展示可观察的输出、变化或诊断。@Document.description 记录意图和使用约束，签名和类型由编译器提供。types、functions、fields 使用受检查的声明引用。@Document 是二进制保留的元数据，不作为运行时注解的演示。norm docs 从同一语义模型生成结构化 API 文档，--strict 检查文档覆盖。关联测试来自测试侧的 @Test 声明，不是 @Document 字段。网站把命令标为已发行能力之前，必须核对公开发行资产；未经测量不宣称 Agent 效率收益。具体机制见 Agent 工具设计、API 文档与注解规范。

norm hello

命令在当前目录写入五个可独立运行、每个只有一个手写源文件的程序：

文件	程序
hell.norm	Hello World
sort.norm	冒泡排序与集合值语义
maze.norm	广度优先搜索迷宫最短路径，并在终端画出路线
todo.norm	GUI Todo，支持添加、完成、删除、筛选及本地持久化
board.norm	Web 留言板，使用服务端页面和表单完成查看、提交、删除及持久化

体验从终端开始，逐步进入 GUI 和 Web。依赖由正常工具链管理，运行数据与源码分开。默认体验不要求账号、密钥或外部服务。生成过程不得静默覆盖同名文件。模板只维护一份，生成的文件由用户自由修改。命令附英文和中文说明。GUI 与 Web 的单文件依赖加载、启动、交互和持久化，必须用实际生成的文件验收。

专业语言示例

这类示例面向有经验的开发者及语言参考页面。典型示例约 40～60 行，可以组合相关特性，解释其语义和实际用途。精选预期失败示例要明确说明诊断，并单独验收。示例可以调用标准库或生态库，完整 API 场景仍归各库维护。主题包含值与身份、表达式结果和匹配、命名调用、泛型与运行时类型、字段观察、类型化注解、声明引用、结果构建器，以及 @Document 与语义查询和测试关联。

教学示例

教学按特性分节，按阶段导航。每节只引入一个新特性，使用可独立运行的 10～30 行示例，附预期结果、细致解释和一个小练习。行数是可读性目标。只有涉及文件边界的概念才使用多文件示例。后面的课程可以使用已经解释过的语法，不能悄悄依赖尚未介绍的知识。教学代码独立于专业语言示例，即使两者讨论同一特性也是如此。

递进顺序为：

1. 程序入口、变量、推断、插值、运算、条件执行。
2. 函数、命名和默认参数、实参简写、if 结果、末尾表达式返回。
3. List、遍历、条件循环、break、continue、Array、Map、Set、集合值语义，以及集合字面量中的 for、if 和展开元素。
4. value、相等性、class、身份、复制、构造器、计算属性、链式方法。
5. 可空性、类型收窄、安全访问、空值回退、枚举、数据枚举、switch 结果、穷尽与嵌套模式。
6. 接口、默认实现、继承、覆盖、泛型类型与函数、推断、运行时泛型匹配、重载。
7. 函数值、Lambda、捕获、方法引用、扩展、尾随和命名回调、块调用链。
8. 导入、模块、包、可见性、依赖、测试、异常与清理。
9. 声明引用、注解与保留策略、运行时注解、拦截器，再单独学习 @Document。
10. 词法 ref 及其生命周期、字段句柄、变化订阅、集合变化、资源归属和关闭、结果构建器。

上述以逗号分隔的特性在构成独立学习步骤时各设一节。库的教学微课安排在前置知识之后：数据建模后学习序列化，错误处理后学习文件或请求失败，回调和状态后学习 GUI 交互，模块与依赖后学习 Web 和存储。它们使用短教学程序，不复制库的综合场景。前八阶段构成主路径，后两阶段属于进阶内容。

值位置的 for 结果仍属于计划中的循环设计，只在编译器支持后加入教学路径。

库的 samples/

每个库仓库都有 samples/ 索引。samples/README.md 是英文入口，samples/README.zh-CN.md 是中文入口，两者指向同一份代码。至少一个有意义的入门示例展示真实调用和结果，通常为 15～30 行。核心库增加典型场景，通常为 40～80 行；确实需要多个文件时放入独立目录。每项说明用途、准备条件、运行命令、可观察结果和 API 参考。内部或聚合仓库通过索引指向实际面向用户的库，不制造无意义程序。

GUI 库示例讲控件和绑定，Web 库示例讲路由和表单。完整 Todo 与留言板归 norm hello 模板维护。公开示例解析已发行依赖，候选发行验收通过正常依赖机制对同一源码进行测试。需要外部凭据的示例说明前提；没有执行就报告未执行。网站按用途索引库示例，不复制源码。

目录与验收

沿用当前可执行文档链路：教学页面引用 norm/tests/docs/tour/ 和 norm/tests/docs/projects/ 中的源码，现有输出和项目测试将实际输出与 .out 或 expected.out 比对。将教学结构细化为每节一个文件。专业示例放入独立的 norm/tests/docs/language/ 测试集；网站展示与 norm hello 模板按职责分别维护。扩展已有测试设施与 VitePress 文件引用，不增加第二套示例运行器或目录清单；页面导航即为目录。

每个示例都验收其承诺的结果：输出、预期诊断、数据变化、HTTP 响应、GUI 交互或持久化状态。尤其要从生成结果验收 norm hello 的五个文件，而不只验收模板。示例承诺行为时，编译成功或进程正常退出不足以证明行为正确。

替代示例具备可执行入口后，清理旧的对外示例及重复引用。保留有独立目的的编译器和库回归测试。远端仓库删除属于另一个仓库级决策；清理旧示例不自动推导为删除仓库。