README

@Doc — AI 原生語義文件表示法

每一代文件格式，都在解決那個時代最核心的問題：

格式	解決的問題
Word	文件編輯
HTML	文件顯示
Markdown	易於人類撰寫
JSON	資料交換
JSX	元件組合
@Doc	AI 與人類共同撰寫的語義文件表示

但沒有一種格式，是為 AI 生成內容而設計的。

@Doc 為三種讀者設計：

撰寫內容的人類
生成內容的 AI
渲染它的編譯器

@Doc 不是下一個 Markdown。它是 LLM 生成內容與渲染器之間缺失的那個 notation 層。

現有主流格式通常只能優化其中一到兩項，很少同時把三者作為一級設計目標：

特性	Markdown	HTML	MDX	@Doc
AI 生成穩定性	❌	⚠️	❌	✅
Token 效率	✅	❌	❌	✅
語義可查	❌	⚠️	⚠️	✅
多目標編譯	❌	❌	⚠️	✅

現有方案的根本問題

Markdown — 為人類書寫設計，不為機器生成設計

LLM 讀 Markdown 沒問題。問題是反過來：讓 LLM 生成 Markdown 並交給下游程式解析，輸出的結構幾乎無法被可靠保證——縮排歧義、巢狀清單漂移、表格損壞、parser 方言差異。

Markdown 沒有語義意圖。它無法表達「這個按鈕是 primary variant」或「這個表格需要斑馬紋」。

HTML — 結構與展示混為一談

HTML 可以表達任何東西，但代價是把展示邏輯寫死在結構裡。同一份內容要渲染到不同平台？重寫。要讓 AI 生成穩定的 HTML？面對幻覺標籤與未閉合元素的風險。HTML 是一個渲染目標，不是一套 notation。

MDX — 為人類開發者設計，代價由 AI 承擔

MDX 將文件與程式碼融合，為人類開發者提供極高的表達能力。但這種自由度對生成式模型而言意味著另一件事：更高的語法不穩定性與更脆弱的結構可預測性。

對比維度	MDX	@Doc
本質定位	把文件變成程式（Code-driven）	把文件變成語義資料（Data-driven）
AI 生成穩定性	允許任意 JS 邏輯，LLM 容易語法崩潰	確定性語法，LLM 輸出可預測
括號語義	`{}` `[]` `<>` 語義多重混淆	`[]` 全域唯一含義就是 Content（內容）
Token 成本	冗長標籤閉合與 JS 樣板代碼	語法極度壓縮（`w-300px` 而非 `w-[300px]`，規劃中，見下方核心語法一節的但書）
錯誤處理	渲染時崩潰，錯一個字元白畫面	解析時捕捉，AI 可秒級自我修正

@Doc 是什麼

同一份 @Doc 原始碼，不修改任何字元，可以乾淨編譯到 Tailwind JIT HTML、Inline Style HTML，或任何未來的渲染目標。

結構與展示徹底分離。語義由格式本身承載，不由渲染器決定。

核心語法

每個節點的長期目標是同一個四槽結構：

text

@node(modifier){styles}[content]<action>

槽位	角色	範例
`@node`	節點類型	`@heading`（別名 `@h`）、`@paragraph`（別名 `@p`）、`@card`
`(modifier)`	變體或屬性	`(primary)`、`(ja)`
`{styles}`	樣式或元數據	`{w-300px bg-fff}`
`[content]`	內容槽位 ── 全域唯一	`[Submit]`
`<action>`	尾綴動作	`<submit>`、`<install>`

[] 在 @Doc 中只有一個含義：內容。沒有例外，沒有逃逸地獄。

語法範例

text

@meta[
title = @Doc 2026 Spec
description = AI-native semantic document runtime
]

@heading(1)[@Doc 專案規範]

@paragraph[這是普通段落，其中包含行內語義節點。]

@card(featured)[
  @heading[AI 原生語言]
  @paragraph[具有確定性語法的結構化標記語言，專為雙向 AST 設計]
]

@table[
  @cols[id|name|price]
  @data[
    [1|早餐|60]
    [2|午餐|80]
    [3|晚餐|90]
  ]
]

雙線並行編譯

同一份 AST，兩種輸出，原始碼一字不改：

Route A — Tailwind JIT

html

<h1 class="text-lg w-[120px]">@Doc 專案規範</h1>

Route B — Universal Inline Style

html

<h1 class="text-lg" style="width: 120px;">@Doc 專案規範</h1>

動態值在 AST 中以結構化資料儲存（{ prop: "w", value: "120px" }），而非原始字串。由後端適配器決定如何渲染。

語法 v0.1.2 的新內容

變更	規範位置
`@img` 對齊：`float-left`／`float-right`（文字環繞圖片），以及裸關鍵字寫法 `@img(src,float-left)[...]`	Block Spec 第 5 節 Image
表格儲存格以 `\|` 分隔；容許頭尾多一根 `\|`；逗號寫法不變	Block Spec 第 5 節 Table
`@span(n)[...]`——一個表格儲存格橫跨 `n` 欄	Block Spec 第 5 節 Table
`@spoiler[...]`——行內、揭露前隱藏的文字	Inline Spec 第 15 節
`@hex[#3366ff]`——色塊加上它自己的色碼（與 `@color` 不同）	Inline Spec 第 15 節
新增 diagnostics：列寬度 ≠ 欄數、錯誤的 `@span`／`@hex`、未知的 `{styles}` token、未知的 `@img` align、非數字的 `@defn` id	Inline Spec 第 11 節 Diagnostics
`@tabs` 的 DOM id 在整份文件內唯一；預設選取第一個分頁	Block Spec 第 8 節 Tabs

這些變更背後大多遵循同一條原則：過去會乾淨解析、卻渲染出錯誤結果的錯誤（少一格的表格、@card{blue}、align=middle），現在都會變成看得見的 diagnostic，而不再是靜默失敗。無論如何，文件仍會照常解析與渲染。

套件版本與語法版本

atdoc-core 的套件版本（0.1.x）與語言的語法版本（此處為 v0.1.2）是分開編號的。套件版本追蹤本 repo 的發行；語法版本追蹤文法的變更。兩份規格文件各自帶有自己的修訂編號（目前為 v1.5）。

節點分類

Core Nodes — 結構原件

文件骨架，不可再分割的原子。

@heading（別名 @h） @paragraph（別名 @p） @quote @code @list @img @table（含其 @cols／@data／@span 部分）

Semantic Nodes — 語義容器

兩種行為模式：

Inline Semantic — 渲染為帶標籤的行內元素：@mark[重要]、@link(example.com)[連結]、@spoiler[隱藏]、@hex[#3366ff]
Block Metadata — 注入 Host 的設定，不渲染任何 HTML：@meta[key = value]

給 AI 開發人員

直接讓 LLM 生成 HTML 很脆弱。@Doc 為模型提供一套受約束的確定性語法——錯誤在解析時暴露，不是渲染時。

因為 [] 是唯一具備內容語義的括號，模型不需要推理括號衝突。

Token 成本也更低：w-300px 而非 Tailwind 的任意值語法 w-[300px]——括號由編譯器補回，不由模型生成（規劃中，目前 {styles} 僅支援顏色 token，見上方核心語法一節的但書）。

給網站開發人員

import { tokenize } from './Lexer';
import { DocParser } from './Parser';
import { DocTranspiler } from './Adapters';

const tokens = tokenize(source);
const ast = new DocParser(tokens).parse();
const html = ast.map(node => DocTranspiler.toTailwindHTML(node)).join('\n');

輸入 @Doc 原始碼，輸出結構化 AST，用符合你技術棧的適配器渲染。Parser 和 Adapters 直接加入你的 pipeline，沒有額外依賴。

設計邊界

@Doc 刻意不是程式語言。這不是限制，是武器。

無變數
無條件判斷
無迴圈
無巨集系統

邏輯由 Host 應用負責。@Doc 只負責結構，不負責行為。這條邊界讓 AI 生成的輸出永遠可預測。這條線是刻意的，不會移動。

現狀

核心 Parser、Lexer 與雙線適配器已可基礎運作。網頁原生版本的 Lexer 與 Parser 正處於密集開發階段。互動式 Playground 與 CLI 工具已列入近期開發時程表。

@Doc 的存在是為了探索 LLM 輸出與渲染目標之間的設計空間。核心功能已可運作，其餘部分正在公開場合持續構建中。

目標：2027 年 1 月 1 日，1.0 Production 等級正式發布。

這個 Repo 有什麼

text

src/            Lexer、Parser、Serializer、registry（節點的單一事實來源）、types、pipeline、markdownImport
src/index/      預設渲染 plugin：Adapters（HTML 渲染的兩條路線）＋ index.css
src/editor/     Monarch tokenizer，給 Monaco 類編輯器用
tests/          Lexer/Parser 的 Strict Mode 案例集（`tests/cases/*.atd`，預期結果在 `expected.json`）、serializer round-trip，以及 v0.1.2 節點的渲染驗證——以 `npm test` 全部執行
configs/        editor/tooling 用的節點設定
*-Specification.md   語言的權威文法定義（EBNF + 語意規則）

Block-Syntax-Specification.md 與 Inline-Syntax-Specification.md 是文法的權威來源。程式碼註解裡偶爾會引用 Structural-Blocks.md、Container-Blocks.md 這類逐節點的補充說明文件——它們不在 v0.1 這份釋出範圍內，對應內容都能在上面兩份規格書裡找到。

License

MIT — see LICENSE.

在 GitHub 上檢視原始檔