# 3. namespace

namespace 是资源归属、组织与检索的单位。对代码资源，系统使用 namespace key 查找索引，取得对应代码段，并形成可见代码视图。

函数、class 和 agent 定义，以及需要独立保存和引用的基础内容，都纳入这一组织体系。资源类别与变量引用见[资源、类型与类](07-types-and-classes.md)；非代码资源的登记和成员定位形式仍待定义，不由代码视图的语法推导。

workspace 确定资源的整体归属与授权边界，namespace 组织其内部资源。用户、角色及 r／w／x 分工的主定义见[用户身份与 workspace 权限](02-user-identity.md)。

## 3.1 key 格式

```text
workspace handle:第一级namespace.后续namespace
```

key 由一个 workspace handle、一个冒号和至少一个 namespace 路径段组成。路径段之间用点号连接：

| key | 结构 |
| --- | --- |
| `atelier:shop` | workspace handle 与一级 namespace |
| `atelier:shop.pricing` | workspace handle 与两级 namespace |
| `atelier:shop.backend.orders` | workspace handle 与三级 namespace |

key 中的 handle 规则见[Workspace handle 与显示名](02-user-identity.md#21-workspace-handle-与显示名)。namespace 路径段在本文词法草案中使用标识符，详见[词法结构](06-lexical-structure.md)。

## 3.2 最小归属

独立登记的资源必须同时具有归属 workspace 和非空 namespace 路径。下列形式缺少必要信息：

| 形式                     | 缺少的内容                              |
| ---------------------- | ---------------------------------- |
| `atelier` 或 `atelier:` | namespace 路径                       |
| `:shop`                | workspace handle                   |
| `atelier.shop.ui`      | workspace handle 与 namespace 的分隔冒号 |

workspace 显示名不能替代 handle。只有 workspace handle 不是完整 namespace key；workspace 本身的管理入口另行定义。

## 3.3 层级语义

workspace 承担类似 repository 的整体资源与授权边界。其下第一级 namespace 与所有后续层级具有相同语义，`shop` 不构成额外权限边界或特殊 module 类型。

namespace 路径表示组织关系。路径段名 `ui`、`backend`、`data` 或 `agents` 不自动决定执行位置、数据存储、通信方式或语言阶段。

父子 namespace 的可见性与成员范围需要独立规则；仅凭路径前缀不能认定读取父级一定包含全部子级代码。

## 3.4 可见代码视图

代码以独立代码段存储，索引关联完整 key 与代码段。可见代码视图是根据这些成员关系获得的逻辑代码集合：

```text
atelier:shop.pricing
    → namespace 索引
    → 对应的独立代码段
    → 可见代码视图
```

视图可以用于阅读和程序处理，不依赖源码文件的物理路径。S3 承担代码段的存储职责；对象键与语言中的 namespace key 是不同概念，详细约定见[代码存储与视图](../appendices/code-storage-and-views.md)。

## 3.5 归属与引用

归属 key 定位当前代码，use key 定位它引用的代码。两者使用同一 key 格式，但承担不同职责：

```text
当前代码：market:shop.checkout
引用目标：atelier:shop.pricing
```

当前代码的 key 由外部上下文提供；引用目标写入正文的 `use` 声明。引用不改变归属，也不自动授予访问权限。下一章说明声明与导入的组织方式。

## 3.6 Workspace 与资源成员

`atelier:pricing` 与 `atelier:shop.pricing` 都属于 atelier workspace。pricing 与 shop.pricing 是不同的内部路径，增加一层 namespace 不要求额外创建 workspace。

| 定位部分 | 职责 |
| --- | --- |
| workspace handle | 找到整体归属与授权边界 |
| namespace 路径 | 找到内部资源组织与检索范围 |
| 声明名或资源成员标识 | 在该范围内选择具体资源，成员定位形式仍待定义 |

成员加入、退出或管理员更换不改变 workspace 中资源的 key；handle 改名与资源迁移是独立操作。历史用户名 key 的迁移与默认 workspace 命名见[规范状态](../appendices/specification-status.md#workspace-名称与生命周期)。

## 3.7 整体权限与内部可视域

workspace 统一授予资源的 r、w、x 操作权限，不为每个 namespace 或其下级重复配置访问名单。namespace 层级组织内容，读取某层时的视图成员规则仍独立适用；权限覆盖整个 workspace 不表示父级视图自动包含所有下级内容。

类型和声明可视域决定程序能否引用一个成员，不代替平台授权。跨 workspace 调用要同时满足目标的语言可见性和执行授权；有权查看源码不自动允许外部程序引用内部成员。

`w` 用于编辑代码和资源内容，`x` 用于执行定义好的入口及其业务效果。调用产生业务数据不因此要求调用者取得整个 workspace 的编辑权限。图片等基础内容具有自己的类型用法，workspace 的 `x` 不将它们变成可调用函数。

具体角色、执行授权及其与管理能力的关系见[Workspace 角色与授权](02-user-identity.md#27-workspace-角色与授权)。use 的名称引入、声明组合与可视域见下一章。

[上一章：用户身份与 workspace 权限](02-user-identity.md) · [下一章：程序结构与导入](04-program-structure.md) · [目录](../README.md)