---
title: 核心理念
---

# 核心理念 (Core Concepts)

Typedown 不仅仅是为 Markdown 添加数据支持，更是一套关于**模型演进**的方法论。在设计过程中，我们做出了几个关键的权衡（Trade-offs），本篇文档将解释这些设计背后的“为什么”。

## 0. 定义 (Definition)

Typedown 是一门 **共识建模语言 (Consensus Modeling Language - CML)**。

它旨在对组织中的**真理 (Truth)** 进行建模。

- **非目标 (Non-Goals)**: 它**不是**笔记语言，也**不是**通用的数据序列化格式。请勿将其用于非结构化的随笔记录或存储大数据量的矩阵。

## 1. 为什么“引用即查询”？ (Why Reference as Query)

在传统的编程语言或配置中，引用通常是一个**地址 (Address)**，例如文件路径 `../db/config.json` 或内存指针。

Typedown 选择将 `[[...]]` 视为一个**查询意图 (Query Intent)**。

- **解耦 (Decoupling)**: 当你写下 `[[db]]` 时，你表达的是“我需要那个叫做 db 的东西”，而不是“去加载路径 X 的文件”。
- **迟绑定 (Late Binding)**: 具体的解析逻辑被推迟到了运行时。这意味着同一个 `app.td` 文件，放在 `prod/` 目录下时 `[[db]]` 指向生产库，放在 `dev/` 目录下时指向测试库。
- **环境多态 (Environmental Polymorphism)**: 这是实现“一份代码，多处运行”的基石。

## 2. 为什么禁止多层列表？ (Why No Nested Lists)

Typedown 在设计上**严禁**在 Entity Body 中使用二维数组（List of Lists）。

**原因：关注点分离与数据边界。**

任何需要超过一维数组的数据（如矩阵、张量），都不应该出现在 Typedown 中。这不仅是为了支持 `manager: [[alice]]` 的“智能解包 (Smart Unboxing)”语法糖，更是为了逼迫开发者使用正确的数据载体。

**如果需要矩阵数据，请使用 CSV 或 JSON，反正别用 Typedown 写。**

## 3. 为什么拥抱“脆弱性”与工具依赖？ (Why Embrace Fragility & Tooling)

许多系统追求“稳健性”，即文件移动后依然能自动工作。Typedown 反其道而行之，我们**拥抱脆弱性 (Embrace Fragility)**，并将**工具依赖**视为核心特性。

### 3.1 模拟自然语言 (Simulating Natural Language)

我们模拟了自然语言的模糊性。隐式上下文让源码读起来像自然语言一样流畅，但也带来了多义性。这种模糊性总而言之不会比自然语言更糟，且必须配合强大的工具链（Git, LSP, Compiler）来解析。

- **草稿 (Source)**: 源码是给人类看的，允许模糊。
- **真理 (Artifact)**: 理论上发布推送的文档，必须是**物化 (Materialized)** 甚至引用 Hash 的。编译器负责将模糊的意图坍缩为绝对的、不可变的真理。

### 3.2 环境即场域 (Context as Field)

其他语言使用显式 import 来硬编码依赖，Typedown 使用**隐式上下文**。这创造了一个强力的“场域”：

- **位置决定命运**: 文件的物理位置决定了它所处的“语义场”（Schema 约束、可用配置、Handle 映射）。
- **移动即重构**: 当你将文件从目录 A 移动到目录 B，你实际上是在改变它所处的场。

### 3.3 错误作为反馈 (Error as Feedback)

我们**不**希望系统默默地自动适配新环境。相反，我们要它**立刻崩溃**：

- **爆裂式反馈**: 如果移动后的文件不再符合新环境的约束（例如引用了新环境下不存在的 Handle），CI 和编译器应立即报出几十个错误。
- **强制对齐**: 这种剧烈的摩擦迫使开发者停下来，显式地运行 `get block query` 或通过 **LSP Doc Lens** 来重新审视当前的上下文场域。
- **精心重写**: 文档的每一次移动，都是一次对认知的重新校准。为了通过 CI，你必须精心重写代码以适配新的场。

这种设计拒绝了“沉默的误解”，选择了“喧闹的修正”。在 Typedown 工程中，本地测试 (`td test`) 的通过意味着你真正理解了你所在的场域。
