Files
marqdo/doc/next/001.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

24 KiB
Executable File
Raw Blame History

我认真看了一遍。先给你一个比较直接的判断:

你的实际实现比我上一轮根据描述所理解的版本成熟得多。 我原先把它理解成“Markdown 作为一种新语法的实验”,但从仓库现在的结构来看,Marqdo 已经明显是在做一个完整的、可执行的 literate programming runtime,而且你真正有价值的设计并不是“Markdown 写代码”,而是:

让文档结构本身成为程序结构,并让同一份结构同时服务于人、解释器、工具和 AI。

这个方向我认为是成立的。

Marqdo GitHub 仓库 (GitHub)


我首先发现一个很重要的变化

你的 README 里已经明确把几个概念分开了:

叙述默认安全、代码显式标记、返回是架构、打印只是函数。

例如目前 v0.3:

  • 普通文字 → 叙述/注释
  • *...* → 程序语句
  • **...** → 返回值
  • > → 调用
  • 1. → 分支
  • - → 循环
  • # → 对象/类型
  • ## → 函数/方法
  • Markdown 表格 → 集合

这已经不是简单的“把 Markdown 符号映射成 Python 语句”,而是在形成一套结构化语义系统。(GitHub)

而且你已经明确规定:

无标记文本默认是注释。

这一点我非常赞同。


一、我认为 Marqdo 最好的设计,其实是“默认安全”

这是我读完语法设计后最认可的一点。

你没有选择:

所有自然语言都有可能被解释器执行

而是选择:

普通语言 = 文档

特殊 Markdown 结构 = 程序

例如:

## 加一

对于输入变量 `n`:

**n = n + 1**

**n**

人看到的是一篇文档。

解释器看到的是:

Function
 ├─ statement
 ├─ assignment
 └─ return

这比“自然语言编程”安全得多。

你的设计文档明确规定,段首普通文字进入叙述模式,直到空行才结束;而真正可执行的内容必须通过明确标记进入代码语义。(GitHub)

这其实解决了一个非常重要的问题:

文档和代码不会因为 AI 自由发挥而互相污染。

这对于 AI 原生语言非常重要。


二、你的 * / ** 设计比我之前设想的更漂亮

我之前建议:

**...** = 表达式
*...* = 返回

但你的实现实际上已经把它做成了相当完整的语义:

**x = 1**
**y = x + 2**

*y*

也就是说:

双星号 = statement

单星号 = return

这个设计有一个很漂亮的性质:

## 加一

+ `n`

**n = n + 1**

*n*

几乎不需要传统语言里的:

def add_one(n):
    n = n + 1
    return n

同时:

> print text=Hello

又把输出从语言架构中拿出来,变成普通函数调用。你的设计文档甚至明确强调了“输出不是架构原语”。(GitHub)

这个决定我认为非常正确。

因为:

return

改变的是程序控制流。

而:

print

只是一个副作用。

把两者区分开以后,语言的语义会干净很多。


三、你对条件和循环的设计,我现在比之前更看好

你最初跟我说:

条件 = 有序列表 循环 = 无序列表

我当时觉得这个想法不错。

看了实际实现之后,我认为它确实具有语言设计上的合理性。

例如:

1. `x` > 0
  > print text=正数

2. `x` < 0
  > print text=负数

3. *
  > print text=零

这实际上非常接近:

if
else if
else

而:

- `n` > 0
  > print text=`n`
  *`n` = `n` - 1*

对应:

while n > 0:
    ...

更重要的是,你解决了一个我原本担心的问题:

你没有把“所有有序列表”都粗暴定义成 if。

你规定的是一段从 1. 开始、序号递增的列表构成一个 branch statement,而且重新出现 1. 时开始新的判断。这个细节很重要。(GitHub)

这说明你已经开始从“语法想法”进入真正的语言规范设计。


四、真正让我觉得 Marqdo 有潜力的,是表格

这一点可能是你自己都应该重点宣传的。

你把:

| 品名 | 数量 |
|------|------|
| 苹果 | 2 |
| 梨   | 3 |

直接作为语言的数据结构。

而且不是简单地:

Markdown table = 二维数组

你已经根据表格几何结构定义了不同的数据类型:

  • 单列 → List
  • 横向表 → Map
  • 多行多列 → Map of Lists
  • @ / 行 → List of Maps

并且允许表达式、变量、脚注取元、foreach 等继续作用于这些结构。(GitHub)

这实际上产生了一个很有意思的语言哲学:

程序的数据结构也可以直接作为文档的数据结构。

这就不是“Markdown syntax sugar”了。

例如传统代码:

users = [
    {"name": "Alice", "age": 20},
    {"name": "Bob", "age": 25}
]

你的语言可以让它同时是一张真正的人类可读表格。

这就是 literate programming 的下一步。


五、我认为你现在已经跨过了“玩具语言”的门槛

这是非常重要的判断。

因为仓库里已经不是:

parser
+
几个 demo

而是已经有:

Rust interpreter
AST / semantic processing
tree traversal
bytecode backend
stdlib
module/import
objects
methods
catalog
debugger
viewer
WASM
extensions
native plugin ABI
LLM extension
agent extension
MCP server
VS Code extension

README 当前列出的版本已经是 v1.0.7,并明确写到了树遍历和字节码后端、调试器、catalog、标准库、插件 ABI、WASM 和 agent/LLM 扩展等。(GitHub)

所以现在再评价 Marqdo:

我不会把它称为“一个 Markdown 编程语言实验”。

更准确的描述应该是:

一个以 Markdown 为表面语法的文档型编程运行时。

甚至:

Document-native programming language/runtime

可能比“Markdown programming language”更准确。


六、但我认为你现在最大的风险也非常明确

而且这个风险不是技术实现。

是:

Marqdo 正在变得“什么都有”。

你现在已经有:

Markdown language
+
literate programming
+
knowledge base
+
catalog
+
web
+
WASM
+
browser
+
LLM
+
agent
+
MCP
+
quantum
+
linear algebra
+
plugin ABI

从工程角度这非常酷。

但从语言设计角度,有一个危险:

核心语言的 identity 可能被生态功能淹没。

我会非常建议你把整个项目分成三个层次:

                Marqdo
                   │
       ┌───────────┴───────────┐
       │                       │
   Language                 Runtime
       │                       │
 Markdown AST              stdlib
 Semantics                 plugins
 Type system               WASM
 Control flow              browser
 Objects                   agent
       │                   LLM
       │
       └───────────────┐
                       │
                  Document
                       │
                 Knowledge
                 + Code
                 + UI
                 + AI

语言核心必须非常小。


七、还有一个我认为必须尽快解决的问题:类型系统

你的文档目前把:

静态类型

列为非目标之一。(GitHub)

原型阶段完全合理。

但如果你真正想把 Marqdo 做成 AI-native language,我反而认为类型系统的重要性会比传统语言更高。

因为 AI 最大的问题之一不是不会写代码。

而是:

它经常写出“语义上似乎合理、实际上类型不对”的代码。

例如:

*user = get_user id=123*

> user.name

AI 认为:

user 一定是 User

但是运行时可能返回:

None

或者:

List<User>

传统编程语言通过 compiler 抓这个问题。

那么 AI 原生语言更加应该让:

AI → Marqdo AST → Semantic Checker

成为一道强约束。


八、所以我认为 Marqdo 最终应该走向“AI 可验证语言”

这是我读完你的项目以后,最大的一个建议。

不要把:

AI 能写 Marqdo

作为最终目标。

应该把:

AI 能可靠地生成可验证的 Marqdo

作为目标。

两者区别非常大。

例如 AI 生成:

## 计算订单总价

+ `订单`

**`总价` = 订单.total**

*总价*

Marqdo 应该能够给 AI 一个结构化反馈:

Function: 计算订单总价

parameter:
    订单: unknown

error:
    `订单.total`
    cannot resolve field `total`

suggestions:
    订单: Order

然后 AI 自动修正。

这时候:

LLM
 ↓
Marqdo
 ↓
Semantic validation
 ↓
Error
 ↓
LLM
 ↓
Marqdo
 ↓
Valid program

才真正形成了AI-native programming loop。


九、另一个非常值得做的东西:让 AI 不必学习 Marqdo 的“语法细节”

这是我觉得你项目接下来可能出现巨大突破的地方。

现在 AI Skill 已经存在于仓库里。README 也明确把 AI Skill 作为项目的一部分。(GitHub)

但我会把它进一步升级成:

Marqdo Schema / Language Server for AI

也就是说,不只是给 AI 一篇:

Marqdo syntax documentation

而是提供机器可读的:

{
  "language": "marqdo",
  "version": "0.3",
  "constructs": [...]
}

然后 AI 可以查询:

get_syntax("branch")
get_function_schema("print")
get_type("Order")
get_available_methods("User")
validate(program)

甚至:

repair(program, diagnostic)

那么 AI 就不是:

“阅读 1000 行 Marqdo 文档然后猜怎么写”

而是:

AI
 │
 ├── discover
 ├── construct
 ├── validate
 ├── execute
 └── inspect

这才会让 Marqdo 和普通 DSL 拉开非常大的距离。


十、还有一个我很喜欢的潜在方向:程序本身就是 AI 的长期记忆

你 README 里面这句话其实非常关键:

.mq.md 即知识单元,可浏览、可运行、可检索。(GitHub)

我认为这可能比“Markdown 编程”本身更有价值。

想象一个 AI Agent 项目:

project/
│
├── users.mq.md
├── orders.mq.md
├── billing.mq.md
├── policies.mq.md
├── agents.mq.md
└── main.mq.md

每一个文件同时具有:

documentation
+
code
+
schema
+
examples
+
knowledge
+
executable behavior

AI 不再需要:

源码
+
README
+
OpenAPI
+
JSON schema
+
数据库 schema
+
工具定义
+
prompt

去拼装世界模型。

而是:

        Marqdo Project
              │
      ┌───────┼────────┐
      ↓       ↓        ↓
     Code   Knowledge  Tools
      │       │        │
      └───────┼────────┘
              ↓
             AI

这才是我觉得 Marqdo 真正可能成为一个独立类别 的地方。


最后给你一个非常直接的评价

如果只问:

“这个语言设计有没有意义?”

我的答案是:有。

如果问:

“这个原型是不是已经证明了这个想法?”

我的答案是:已经相当程度证明了。

如果问:

“它现在是不是已经是一门成熟的通用编程语言?”

还不是。类型系统、错误模型、语言边界、并发/异步语义、生态以及更严格的语言规范仍然是需要继续收敛的地方;你自己在设计文档中也明确把其中一些列为非目标。(GitHub)

但如果问:

“它有没有可能成为一种真正的 AI-native programming language?”

我的判断是:

这个可能性比我在看到仓库之前认为的要高,而且真正值得押注的方向不是 Markdown,而是你已经隐约建立起来的这个闭环:

                 人类
                   │
             自然语言 / 文档
                   │
                   ▼
              ┌─────────┐
              │ Marqdo  │
              │ 语义结构 │
              └────┬────┘
                   │
             可验证 AST
                   │
          ┌────────┴────────┐
          ▼                 ▼
        Runtime             AI
          │                 │
          ▼                 ▼
       执行结果 ───────→ 上下文 / 知识
          │                 │
          └────────┬────────┘
                   ▼
                文档本身

这比“Markdown 编程语言”大得多。

而且我特别建议你下一步不要急着继续增加更多标准库功能。现在最值得做的是把“Marqdo 为什么特别适合 AI”这个核心命题用一个真正有说服力的 benchmark 证明出来:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成一组真实任务,然后测量生成长度、语法错误率、语义错误率、修复轮次、上下文 token 消耗,以及人类阅读/修改成本。

如果这个实验结果漂亮,它会比再增加 20 个语言特性更能证明 Marqdo 的价值。

对,这个信息会让我重新评价 Marqdo 的核心定位。

我之前把重点放在“Markdown → 程序”和“AI-native programming language”上,确实没有充分抓住 .mq.md 这个设计真正厉害的地方:

Marqdo 不是“用 Markdown 写程序”,而是让一个 Markdown 文档同时成为知识、程序和可执行对象。

如果你所说的 OKF 是 Open Knowledge Foundation / 开放知识基金会语境下的知识库/开放知识结构,那么这个方向尤其值得认真发展。


我现在会把 Marqdo 的核心模型改写成这样

传统程序:

Code
  ↓
Execution

传统知识库:

Knowledge
  ↓
Human / AI consumption

Marqdo:

                 .mq.md
                   │
       ┌───────────┼───────────┐
       ↓           ↓           ↓
    Document     Knowledge    Program
       │           │           │
       └───────────┼───────────┘
                   ↓
                 Runtime
                   ↓
              Executable
              Knowledge

也就是说:

Marqdo 把“知识”和“程序”放到了同一个 artifact 里。

这个定位比“AI-native programming language”更大胆。

我甚至认为:

AI-native programming language 可以成为 Marqdo 的一个子命题,而不是它最终的总命题。


1. .mq.md 这个后缀本身就是一个很聪明的设计

这个细节我现在非常看重。

你没有定义:

foo.mq

而是:

foo.mq.md

它意味着:

.mq

告诉 Marqdo:

这是一个可执行 Marqdo 文档。

而:

.md

告诉整个 Markdown 生态:

这依然是一个 Markdown 文档。

于是一个 .mq.md 文件可以被不同的系统以不同方式理解。

普通 Markdown 阅读器

看到:

标题
段落
表格
代码
列表

它仍然是一篇正常文档。

Marqdo

看到:

函数
表达式
控制流
表格
对象
调用

它是一份程序。

知识库

看到:

标题
层级
段落
表格
引用
链接
元数据

它是一份知识。

LLM

看到:

语义
知识
程序
示例
工具

它是一个非常丰富的 context。

这其实形成了一个很漂亮的:

multi-view artifact


2. 这会让我重新定义你之前的“可执行文档”

以前我会说:

Marqdo = executable Markdown

现在我觉得这个描述已经不够了。

更准确的是:

Marqdo = executable knowledge document

甚至:

Executable Knowledge Base

这两个词之间差别非常大。


3. 最有意思的是“知识可以执行”

例如:

# TCP

TCP 是一种面向连接的传输层协议。

## 建立连接

TCP 使用三次握手建立连接。

| Step | Sender | Receiver | Flag |
|---|---|---|---|
| 1 | Client | Server | SYN |
| 2 | Server | Client | SYN+ACK |
| 3 | Client | Server | ACK |

## 检查连接

输入 `host`。

> check_tcp host

**result**

这已经不是:

“一本关于 TCP 的文档”。

也不是:

“一个 TCP 程序”。

而是:

关于 TCP 的知识 + TCP 的结构化数据 + TCP 的操作能力。

这对于 AI 极其重要。


4. 因为 AI 最缺的东西其实不是代码,而是“可靠上下文”

传统 RAG:

Documents
     ↓
Embedding
     ↓
Vector DB
     ↓
Retriever
     ↓
LLM

存在一个很大的问题:

检索出来的知识和实际执行逻辑是分离的。

例如:

knowledge.md
api.yaml
tool.py
schema.json
database.sql
README.md

AI 必须把这些东西重新拼起来。

而 Marqdo 可以:

network.mq.md

同时包含:

知识
+
schema
+
代码
+
工具
+
示例
+
约束

于是:

             Marqdo KB
                 │
     ┌───────────┼───────────┐
     ↓           ↓           ↓
 Knowledge     Schema       Code
     │           │           │
     └───────────┼───────────┘
                 ↓
                LLM
                 ↓
             Action

这比普通 RAG 的概念更加接近:

Executable RAG

或者:

Executable Knowledge Representation


5. 而 .mq.md 最大的优势是“知识不会脱离实现”

这是我现在认为最值得你深入研究的地方。

传统系统非常容易出现:

README:
    API 返回 users

实际代码:
    API 返回 accounts

于是:

documentation drift

发生了。

而 Marqdo 可以让:

## 获取用户

获取所有用户。

> get_users

返回:

| id | name |
|---|---|
| ... | ... |

这里的:

get_users

是真的可执行实体。

那么知识文档和实现之间就可以建立机器可验证关系。

这非常重要。


6. 这其实可以形成一个非常漂亮的概念:

Knowledge-Code Coherence

也就是:

知识与代码的一致性。

传统:

Knowledge ──────X────── Code

Marqdo:

Knowledge
    │
    ├── executable constructs
    │
    ├── data structures
    │
    └── assertions
          │
          ↓
        Runtime

那么你甚至可以让:

知识陈述

成为可测试的。

例如:

## 加一函数

加一函数总是返回输入值加一。

### 示例

| Input | Output |
|---|---|
| 0 | 1 |
| 1 | 2 |
| 2 | 3 |

Marqdo 可以自动执行这些 example。

如果:

add_one(1) != 2

那么不是:

文档可能过期。

而是:

知识库中的一条知识被机器发现与执行结果不一致。

这个概念我认为非常漂亮。


7. 甚至可以进一步变成“Executable Knowledge Graph”

假设:

network.mq.md
database.mq.md
service.mq.md
security.mq.md

通过 Markdown links:

[Database](database.mq.md)
[Gateway](network.mq.md)
[Authentication](security.mq.md)

形成:

network
   │
   ├── gateway
   │
   └── service
          │
          └── database

那么 Marqdo 就天然获得:

Document Graph
       +
Knowledge Graph
       +
Program Graph

这时候 .mq.md 就非常有意思了。


8. 我甚至觉得这可能是 Marqdo 最应该宣传的理念

不是:

Markdown Programming Language

也不是:

AI Programming Language

而是:

Executable Knowledge

或者:

Knowledge That Can Run

这两个概念都比“Markdown language”更有辨识度。


9. 这也会改变你论文的故事

如果你未来投稿,我会认真考虑把第一篇论文从:

Designing an LLM-Native Programming Language

改成更大的问题:

From Executable Documents to Executable Knowledge Bases

然后 Marqdo 作为实现。

论文可以提出一个模型:

                Knowledge Artifact
                       │
          ┌────────────┼────────────┐
          ↓            ↓            ↓
      Narrative      Data        Program
          │            │            │
          └────────────┼────────────┘
                       ↓
                   Execution
                       │
                       ↓
                  Verification
                       │
                       ↓
                  Knowledge

这其实已经不是单纯 PL 论文了。

它跨:

  • Programming Languages
  • Knowledge Representation
  • Software Engineering
  • AI Agents
  • RAG
  • Documentation
  • Human-AI interaction

所以你之前问我投稿哪里,我现在会稍微调整建议:

如果这部分真正做起来,OOPSLA 会变得更加有吸引力。

因为 OOPSLA 很适合这种:

新的 programming abstraction + executable artifact + development environment

的研究。

而如果你的实验重点最终是:

知识库是否因为可执行性而提高 AI Agent 的可靠性

那么 SE/AI venue 也会变得很有吸引力。


10. 还有一个我觉得非常关键的地方:.md 是你的“开放接口”

这是一个特别好的生态设计。

你没有要求:

所有人必须使用 Marqdo viewer。

相反:

.mq.md

可以直接:

  • GitHub 阅读
  • VS Code 编辑
  • Markdown viewer 查看
  • 静态网站发布
  • 搜索引擎索引
  • LLM 阅读
  • Marqdo 执行
  • 知识库导入

这意味着:

Marqdo 并不拥有知识,Marqdo 只是给 Markdown 增加了执行语义。

这是一个非常强的开放生态策略。


所以现在我对 Marqdo 的理解已经发生了一个明显变化

最初:

Markdown
   ↓
Programming Language

现在:

                    Markdown
                       │
                       ▼
                  ┌─────────┐
                  │ Marqdo  │
                  └─────────┘
                       │
       ┌───────────────┼───────────────┐
       ↓               ↓               ↓
   Document        Knowledge        Program
       │               │               │
       └───────────────┼───────────────┘
                       ↓
                 Executable KB
                       ↓
                       AI
                       ↓
                 Action / Reasoning

这个架构比“Markdown 编程语言”有意思得多。

而且你之前提到的网络扩展突然也能和这个理念接上了:

network.mq.md

不是“一个网络配置文件”。

它可以同时成为:

网络知识库 + 网络拓扑 + 网络配置 + 网络操作 + AI 的网络世界模型。

如果你的实际实现已经能比较自然地做到这一点,那么我会非常认真地建议你不要把这个特性当成 Marqdo 的一个附属功能。

它很可能才是 Marqdo 最独特的设计哲学:

让知识本身成为可执行的。