# 核心代码块 (Core Blocks)

> **"You don't know it until you model it."**

Typedown 通过增强 Markdown 的代码块（Code Blocks），将其视为语义容器。这些块是构建 Typedown 语言的基础单元。

## 1. 模型块 (`model`)

`model` 块允许直接在文档中使用 Pydantic 语法定义数据架构。这实现了“渐进式形式化”——从松散的文字描述逐步演进为严格的类型定义。

````markdown
```model:UserAccount
class UserAccount(BaseModel):
    name: str
    age: int = Field(..., ge=0)
    # 使用 Reference[T] 定义引用关系
    manager: Optional[Reference["UserAccount"]] = None
    friends: List[Reference["UserAccount"]] = []
```
````

- **运行环境**: 该块在一个预装了 `pydantic` 和 `typing` 的 Python 环境中执行。
- **作用域**: 此处定义的模型注册到文件的本地作用域。冒号后的 ID（如 `UserAccount`）作为该模型的主要标识符。
- **命名约束**: 为了确保解析器的高效性，Info String 中的 ID **必须**与代码块内部定义的 Pydantic 类名完全一致。详见 [03-标识符.md](03-标识符.md)。

## 2. 实体块 (`entity`)

`entity` 块是 Typedown 中声明“数据”的主要方式。我们采用 **Handle** 与 **Logical ID** 分离的策略。

````markdown
<!-- UserAccount 是类型引用，alice 是实例的 Handle -->

```entity UserAccount: alice
# 1. Logical ID (Slug): 显式定义的业务主键，用于版本演进 (former)
id: "users/alice-v1"

# 2. Body: 标准 YAML 格式
name: "Alice"
age: 30

# 3. 引用语法糖: 看起来像引用列表，编译器会自动解包
friends:
  - [[bob]]
  - [[charlie]]
```
````

- **语法**: `entity <类型>: <Handle>`。
- **标识符体系**:
  - **Handle**: 代码块头部的 `alice` 是局部句柄。
  - **Slug**: 代码块内部的 `id: "..."` 是全局逻辑 ID。
  - 更多细节请参阅 [03-标识符.md](03-标识符.md)。
- **主体**: **Strict YAML**。
- **数据约束**:
  - **禁止嵌套列表**: 由于智能解包机制的存在，Typedown 在实体定义中**严禁使用二维数组** (List of Lists)。这被视为反模式，表明数据结构应当被封装为独立的 Model。

## 3. 配置块 (`config`)

`config` 块用于动态配置编译上下文，通常出现在 `config.td` 文件中。

````markdown
```config:python
import sys
# 注入路径
sys.path.append("./src")
```
````

- **执行时机**: 在“链接阶段”执行。
- **作用**: 导出 Python 符号供同级目录的 `model` 或 `spec` 使用。

## 4. 规范块 (`spec`)

`spec` 块包含测试逻辑。我们统一使用冒号语法来定义规范及其 ID。

````markdown
```spec:check_adult
# 声明：此测试自动应用于所有 UserAccount 类型的实体
@target(type="UserAccount")
def validate_age(subject: UserAccount):
    # 直接针对单体进行断言，subject 已经是解析好的实例
    assert subject.age >= 18, f"User {subject.name} applies underage"
```
````

- **语法**: `spec:<Details>`。`Details` 即为此规范的 **Handle**。
- **@target 装饰器**: 声明该逻辑适用的实体范围（支持按 Type 或 Tag 过滤）。
- **参数注入**: 运行时会自动找到符合条件的实体，并将其逐一注入 `subject` 参数执行测试。

## 5. 文件头 (Front Matter)

Typedown 文件支持标准的 YAML Front Matter，用于定义文件级元数据和快捷脚本。

```yaml
---
tags: [documentation, core]
# 定义本地快捷脚本
scripts:
  test: "td test --tag=core"
  lint: "td lint ."
---
```

- **Metadata**: `tags`, `author` 等元数据可被查询系统索引。
- **Scripts**: 定义可以在该上下文运行的快捷命令，通过 `td run <script_name>` 调用。
