6.3 KiB
4. 程序结构与导入
一个 namespace 的代码视图由导入和声明组成。声明描述类型、逻辑、agent 或界面；导入使代码能够引用其他 namespace 中允许使用的声明。基础内容也可作为资源归属到 namespace，但其登记方式不由代码视图文法定义。
4.1 正文结构
本文采用的程序结构为：
零个或多个 use 声明
一个或多个 class、function 或 agent 声明
声明之间不使用逗号或分号。正文不含自身 namespace 声明，其归属来自外部 key 与索引。
“一个或多个”表示同一代码视图可以包含任意数量的这三类顶层声明，至少包含一个；不要求每类各出现一次，也不要求一个 namespace 只保存一个定义。
| 声明组合 | 表达的内容 |
|---|---|
| 一个或多个 function | 一组可组合的逻辑入口或辅助计算 |
| 一个或多个 class | 一组共享数据结构及其成员定义 |
| 一个或多个 agent | 一组模型驱动的行为定义 |
| 三类声明混合 | 类型、普通逻辑和 agent 共同组成程序 |
顶层声明与内部成员是不同位置。class 内的成员函数仍是 function，但属于类的成员作用域；agent 内的变量、函数或类型也保留其共有语义，并与 agent 实例或运行职责关联。内部成员不会仅因使用相同关键字自动成为 namespace 的顶层成员。
这里描述代码视图中的声明结构，不表示查看视图就实例化全部 class、启动全部 agent 或执行全部函数。函数体里的 let 和 return 仍遵守函数体规则，图片、文本等非代码资源的登记也不靠增加占位 class 或 function 表达。
agent 是语言声明，内部复用共有成员结构并增加 agent 作用域及运行关联。声明骨架仍为提案；工具、记忆和控制关联的具体写法见Agent。
这是一份逻辑代码视图的语法结构，不规定独立代码段的存储粒度或物理排列。代码段边界及视图组装规则见代码存储与视图。
4.2 use 声明
代码归属：market:shop.checkout。导入声明：
use atelier:shop.pricing
use 后跟一个完整 namespace key。workspace handle 与路径用冒号分隔，路径层级用点号分隔。每个 use 引用一个 namespace，不附加类名、函数名或选择性名称列表。
引用整个 namespace 表示指定依赖来源，不表示获得访问权限或自动执行其中的函数。
4.3 声明组合
代码归属：atelier:shop.data。
class Product {
name: String
price: Number
}
function listedPrice(product: Product): Number {
return product.price
}
同一视图可以同时包含类、函数和 agent。界面逻辑通过普通函数及其结果表达，与业务逻辑共用声明和表达式规则。
类与函数的内部结构分别在类型与类和函数与调用中定义。查看资源和呈现界面结果见资源访问与呈现。
以下是同一视图中的声明关系示意，不是完整源码。沿用 Product 与 listedPrice，agent 的工具关联形式尚未定义：
namespace 代码视图
Product：class 定义
listedPrice：function 定义，使用 Product
定价 agent：agent 定义
内部变量与辅助函数
引用 listedPrice，或在内部实现其他工具逻辑
这三项可以共同存在，但拥有各自的声明身份。agent 引用 listedPrice 不改变函数归属，也不把该函数自动变为 agent 的内部成员。类、函数或 agent 的声明先进入 Preflight 准备，其调用或实例使用属于 inflight。
声明之间的依赖不要求按执行顺序将所有代码写在一个文件里；视图顺序、前向引用与名称冲突仍按各自的规则确定。独立代码段是否与一条顶层声明对应，也不由此示意规定。
4.4 名称引用
导入后的声明必须依据可见性和名称查找规则使用。跨 namespace 示例采用“导入的名称可直接查找且没有冲突”的简化条件，用于展示调用含义；这不是对全部声明自动进入作用域的承诺。
名称限定、别名、同名冲突与可见性规则列于规范状态。官方 UI 组件的来源单独说明，不属于示例用户库。
名称解析、代码可视域和平台权限分别承担三个判断：找到哪个声明、当前代码位置能否引用它、操作身份能否对它进行本次操作。use 完成依赖表达，不替代后两个判断。
按已确定的操作分工，阅读源码使用 r，编辑定义使用 w，调用程序入口使用 x。业务调用可以按入口契约产生数据写入，不需要因为这一效果给调用用户整个归属范围的编辑权。只具有 x 时所需签名与接口信息如何提供，仍待定义，不能据此承诺全部源码可见。
平台权限统一放在 workspace 层，内部声明仍可以具有自己的语言可视域。一个用户即使拥有整个 workspace 的 r，外部函数也不能绕过成员可见性；允许外部引用的声明也不会自动向无授权用户开放。主定义见平台权限与代码可视域。
本文的 atelier 与 market 都是 workspace handle。编写、修改或调用代码的用户可以不同；成员变化不改变 use 中引用的 workspace。
4.5 程序与局部片段
本书区分三类示例：
- 声明示例：展示可以出现在代码视图中的类、函数或 agent；未定关联形式采用结构示意。
- 函数体片段：展示 let、return 或局部表达式。
- 结构与访问示意：展示界面组成或资源访问行为，不表示源码。
局部片段用于查询语法，不自动成为程序顶层入口。入口选择、空视图与定位形式仍列于规范状态。