# 标识符体系 (Identifiers)

Typedown 的核心哲学是**渐进式形式化**，这一哲学深刻地体现在其标识符体系中。我们在不同的阶段、不同的场景下，使用不同精度的标识符来指代事物。

## 标识符光谱 (The Identifier Spectrum)

我们定义了四种核心标识符，它们的精度依次递增，而易用性依次递减：

| 类型   | 名称               | 所在位置             | 特性               | 典型场景                       |
| :----- | :----------------- | :------------------- | :----------------- | :----------------------------- |
| **L1** | **Handle (句柄)**  | Code Block Header    | 局部、易变、简短   | 开发阶段、代码块声明、局部引用 |
| **L2** | **Slug (逻辑 ID)** | Entity Body (`id`)   | 全局、稳定、可读   | 跨文件引用、长期维护、版本演进 |
| **L3** | **UUID**           | Entity Body (`uuid`) | 全局、唯一、无语义 | 数据库主键、无需人工干预的场景 |
| **L0** | **Hash (指纹)**    | 不可变 (Calculated)  | 绝对、确定、不可变 | 发布制品、依赖锁定、内容寻址   |

### 1. Handle (句柄)

**Handle** 是开发者与代码块交互的第一界面。通过冒号语法定义。

- **语法**: `BlockType: Handle`
- **作用域**: 默认为文件级私有（Local Scope），除非被显式导出。
- **用途**: 提供一个好记的名字，供当前上下文快速引用。

````markdown
<!-- "User" 和 "alice" 都是 Handle -->

```model:User
...
```

```entity User: alice
...
```
````

### 2. Slug (逻辑 ID)

**Slug** 是实体在时空中的稳定锚点。当一个实体成熟后，它应该拥有一个显式的逻辑 ID。

- **语法**: 在 Entity Body 中定义 `id: "path/to/identity"`。
- **约束**: 全局唯一。通常采用类 URL 的路径结构。
- **演进**: 使用 `former: ["old-slug"]` 来追踪 ID 的重命名，保证历史引用的连续性。

````markdown
```entity User: alice
# 这是一个 Slug，它是该实体的官方身份证
id: "users/alice-v1"
name: "Alice"
```
````

### 3. Hash (内容指纹)

**Hash** 是内容的数学摘要。它是客观真理，不以人的意志为转移。

- **生成**: `SHA-256(Canonical_Body)`。
- **用途**: 确保引用指向的是**特定时刻的特定状态**。

当你在引用中使用 Hash 时 (`[[sha256:abc...]]`)，你不再是引用"那个叫 Alice 的人"（她可能会变），而是引用"在该时刻、该状态下的 Alice 数据快照"。

### 4. UUID

**UUID** 是最终的兜底标识。

- **用途**: 当你懒得命名 (Handle)，也不想维护逻辑路径 (Slug)，且内容经常变化 (Hash 不稳定) 时，使用 UUID。
- **自动化**: 通常由工具自动生成，人类尽量避免手动处理。

## 标识符的解析优先级

当发生引用 `[[target]]` 时，解析器遵循以下优先级：

1. **Hash Check**: 如果是 `sha256:...`，直接进行内容寻址 (L0)。
2. **Handle Lookup**: 在当前文件及 Context 查找是否有匹配的 Handle (L1)。
3. **Slug/UUID Lookup**: 在全局索引中查找是否有匹配的 ID (L2/L3)。
