“In 2004 when Markdown was born, nobody needed a document that could be atomically rewritten by programs.”
For the past two decades, text formats have developed along a clear dichotomy:
Under this division of labor, human engineers and computer programs operated in their respective domains without conflict.
However, with the rapid rise of Large Language Models (LLMs) and autonomous AI Agents embedded directly into software workflows and knowledge management, an irreversible shift has occurred: Documents are no longer authored solely by humans for human readers. They are co-authored, incrementally modified, and continuously maintained by humans and AI Agents together.
The AI Agent has become the document’s second reader—and its frequent co-author.
When humans and machines sit down at the same writing desk, our traditional document infrastructure begins to fracture.
Markdown was created in 2004 by John Gruber with a singular goal: allowing writers to format plain text intuitively and convert it easily to HTML. It was never architected to support atomic, programmatic in-place mutations.
Because Markdown lacks deterministic block boundaries and machine-identifiable primary keys, an Agent attempting to modify a single parameter or clause is typically forced into one of two fragile paths:
In an Agent’s iterative execution loop, full-text rewrites introduce severe penalties:
If Markdown is too loose, why not store everything in JSON or XML?
The answer is obvious: Syntactical wrapping is too heavy, and human cognitive load is too high.
Deeply nested braces, quotes, closing tags, and escape sequences deter human reading and direct editing, while consuming an unnecessarily high percentage of token budget.
In current Agent architectures, knowledge is scattered across disjointed stores: some in vector databases, some in short-term runtime memory, some in ad-hoc prompt templates, and some in copied-and-pasted Markdown snippets.
Software engineering holds an undeniable truth: Copies begin drifting the moment they are born.
When redundant copies lack a single source of truth to anchor them, Agents inevitably operate on conflicting versions and fragmented data.
In 2000, Roy Fielding introduced the REST architectural style in his doctoral dissertation. REST did not invent new networking hardware; its breakthrough was conceptual: giving every scattered resource on the web a unique name (URI) and a uniform set of operational verbs (GET / POST / PUT / DELETE). This simple convention laid the groundwork for modern web collaboration.
Today, facing countless paragraphs, rule definitions, system parameters, and conclusions scattered across documents, we encounter the exact same problem.
The solution to human-agent co-authoring is not another complex rich-text editor. It is bringing the philosophy of REST into plain text:
Doc-as-a-Base (Base of Truth):
Assign every logical block inside a document a unique name (#id), accompanied by standard operational verbs (get/set/add/delete).
To turn Doc-as-a-Base from a design philosophy into deterministic engineering, GEML (geml-spec) establishes four foundational laws:
Every structural block must have a stable machine key, readable and replaceable in isolation.
GEML organizes plain text into Typed Blocks, each with an explicit #id.
get(id) reads only that specific block; set(id) updates only that specific block. When an Agent modifies a section, the rest of the document is not only untouched—it is not even loaded into the prompt context.
“What isn’t loaded cannot be broken — isolation, not discipline.”
Physical context isolation eliminates the token waste and hallucinations caused by full-text rewrites.
Inclusion must be dynamic evaluation at the view layer, not static duplication.
GEML natively supports modular embedding across blocks and documents. Defined once at the source, resolved dynamically upon consumption. This eliminates the maintenance burden of keeping duplicate copies in sync.
Cross-block references must be verified at build time; bad writes are rejected before hitting disk.
Write-time defense. If an Agent produces broken syntax or a dangling reference, the GEML parser rejects the write before it lands on disk, without waiting for manual human review.
When errors occur, roll back only the faulty block.
With its companion .gemlhistory sidecar, GEML tracks block-level modification history. If an Agent introduces a bad edit, that specific block can be rolled back atomically without reverting the entire document.
“It’s not that Git is bad; it’s just not operating at this layer.”
Git governs file- and commit-level version control; GEML governs fine-grained, intra-document block rollbacks.
The credibility of any rigorous specification rests on clearly stating what it does not claim:
=== type {#id ...} syntax carries lightweight structural cost. GEML practices Syntax Austerity—spending zero tokens on unnecessary styling or wrappers, reserving maximum context for actual content.Addressing, projection, validation, and reversibility—each of these four capabilities is mature in its own domain: databases have primary keys, XML has XInclude, schemas provide validation, and Git tracks history.
What is unusual is not any single one of these capabilities, but packing all four into human-readable plain text.
Doc-as-a-Base is not about introducing a heavy runtime system. It is about establishing simple conventions that bring order to human-agent collaboration.
Give every paragraph a name. Give every modification a boundary.
“Markdown 诞生的 2004 年，还没有人需要一份能被程序原子化改写的文档。”
在过去的二十多年里，文本格式的演进遵循着一条清晰的分水岭：
在这两套体系下，人类工程师与计算机各司其职，相安无事。
然而，随着大语言模型（LLM）与自动化 AI Agent 深入软件研发与知识协作的一线，一个不可逆的历史性转折发生了：文档不再仅由人类编写、供人类阅读，而是由人类与 AI Agent 共同创作、实时修改与持续维护。
AI Agent 成了文档的第二个读者，同时也是高频介入的共同写作者。
当人机坐到同一张写字台前时，我们今天习以为常的文档基础设施开始全面瓦解。
Markdown 诞生于 2004 年，John Gruber 当初设计它的初衷极其纯粹——让写作者能够用直观的纯文本快速排版并转换成 HTML。它从来没有被设计用来承载“程序的原子级局部改写”。
因为缺乏确定性的区块边界与机器可识别的唯一标识，当 Agent 需要修改 Markdown 文档中的某一个参数或某一段逻辑时，常见的做法只有两种：
在 Agent 的多轮执行循环里，全文重写带来了可怕的恶果：
如果说 Markdown 太过松散，那为什么不直接用 JSON 或 XML 存储一切？
答案同样显而易见：包裹语法太沉重，且人类心智无法直接承受。
大段嵌套的括号、引号、闭合标签与转义符，不仅让程序员失去直接阅读与沉浸编辑的欲望，更在长上下文中占据了相当比例的无效 Token。
在现有的 Agent 架构中，知识往往被拆碎：一部分在向量数据库里，一部分在短期记忆里，一部分在临时 Prompt 模板里，还有一部分散落在各种复制粘贴的 Markdown 副本中。
软件工程有一条朴素的真理：副本自诞生起就在漂移。
当多处副本无法通过单一源头自动同步时，Agent 面对的就是充斥着版本分歧与事实冲突的混沌状态。
2000 年，Roy Fielding 在其博士论文中提出了 REST 架构风格。REST 并没有发明任何新的网络硬件，它的核心创见在于：为互联网上散落的所有资源赋予唯一的名字（URI），并为它们定义了一组标准的操作动词（GET / POST / PUT / DELETE）。 这一极简约定奠定了现代互联网协作的基石。
今天，面对文档内部散落的无数逻辑块、规则定义、系统参数与任务结论，我们遇到了完全相同的问题。
解决人机共写冲突的答案，不是发明一个更加复杂的富文本编辑器，而是将 REST 的思想引入纯文本：
Doc-as-a-Base（文档即真相之源）：
为文档内的每一个逻辑块赋予唯一的名字（#id），并赋予标准的操作动词（get/set/add/delete）。
为了让 Doc-as-a-Base 从哲学变成确定性的工程实践，GEML (geml-spec) 确立了四项不可分割的运行定律：
每个结构块必须有稳定的机器主键，脱离上下文即可被单独读取与替换。
GEML 将纯文本划分为类型化区块（Typed Blocks），每个块拥有明确的 #id。
get(id) 只读取那一块，set(id) 只写入那一块。在 Agent 操作局部内容时，其余部分不仅不修改，在 Prompt 中甚至根本不加载。
“没被加载的东西不可能被改坏——要隔离，不要自律。”
依靠物理级的上下文隔离，彻底消灭全量重写带来的幻觉与 Token 浪费。
引用必须是视图端的动态取值，而非静态复制。
GEML 原生支持跨文档与跨区块的嵌入引用。源头单一定义，渲染与消费时动态求值。彻底终结跨文档复制粘贴导致的“副本碎片化”噩梦。
块间引用必须在构建期受核验，坏写入挡在落盘之前。
写入即防御。当 Agent 产生破坏性的语法结构或产生悬空断引用时，GEML 解析器在落盘前直接拦截报错，不等人工 Review 介入。
出错时必须能只回滚出错的那一块。
GEML 借助伴生的 .gemlhistory 文件，记录每次 Block 的变更历史。Agent 哪怕改错了一处参数，也支持单块原子回退，不影响整篇文档的其他内容。
“不是 Git 不好，是它不在这一层。”
Git 负责文件与 Commit 级别的版本管理，GEML 负责文本内部细粒度的块级撤销。
任何成熟的工程规范，其信誉都建立在“主动讲清自己不主张什么”之上：
=== type {#id ...} 语法本身具备轻量结构开销，GEML 主张的是语法克制（Syntax Austerity）——不为排版浪费一个多余的 Token，把宝贵的上下文留给内容。寻址、投射、校验、可逆——这四种能力在各自领域都有极其成熟的对应物：数据库有主键，XML 有 XInclude，Schema 能校验，Git 管历史。
不寻常的不是其中任何一项，而是将这四样能力，同时装进了一种人类肉眼可读的纯文本之中。
Doc-as-a-Base 不是要创造一个沉重的系统，而是用极简的约定，给混沌的人机协作带来秩序。
让每段文字拥有名字，让每次修改拥有边界。