# 3. namespace

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

## 3.1 key 格式

```text
用户名:第一级namespace.后续namespace
```

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

| key | 结构 |
| --- | --- |
| `alice:shop` | 用户名与一级 namespace |
| `alice:shop.pricing` | 用户名与两级 namespace |
| `alice:shop.backend.orders` | 用户名与三级 namespace |

key 中的用户名规则见[用户身份](02-user-identity.md)。namespace 路径段在本文词法草案中使用标识符，详见[词法结构](06-lexical-structure.md)。

## 3.2 最小归属

代码必须同时具有用户和非空 namespace 路径。下列形式缺少必要信息：

| 形式 | 缺少的内容 |
| --- | --- |
| `alice` 或 `alice:` | namespace 路径 |
| `:shop` | 用户名 |
| `alice.shop.ui` | 用户名与 namespace 的分隔冒号 |

显示名不能替代用户名。代码也不能直接归属于没有 namespace 的用户根层级。

## 3.3 层级语义

用户之下的第一级 namespace 与所有后续层级具有相同语义。`shop` 在位置上类似 repository 那一层，但不构成独立的 repository 或特殊 module 类型。

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

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

## 3.4 可见代码视图

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

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

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

## 3.5 归属与引用

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

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

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

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