@Doc

README

@Doc — AI 原生语义文档表示法


每一代文档格式,都在解决那个时代最核心的问题:

格式解决的问题
Word文档编辑
HTML文档显示
Markdown易于人类撰写
JSON数据交换
JSX组件组合
@DocAI 与人类共同撰写的语义文档表示

但没有一种格式,是为 AI 生成内容而设计的。


@Doc 为三种读者设计:

  • 撰写内容的人类
  • 生成内容的 AI
  • 渲染它的编译器

@Doc 不是下一个 Markdown。 它是 LLM 生成内容与渲染器之间缺失的那个 notation 层。

现有主流格式通常只能优化其中一到两项,很少同时把三者作为一级设计目标:

特性MarkdownHTMLMDX@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 idInline 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,见上方核心语法一节的但书)。


给网站开发人员

ts
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.