Add v0 markup-as-syntax constitution, examples, and tech stack choice.

Lock Markdown marker mappings, ship runnable-shaped examples, and select TypeScript + remark + Vitest for the reference implementation.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-08-04 10:42:36 +08:00
1 parent 117a03ca8e
commit 2cb05fd838
12 files changed
+507 -128

No files matched your search

+44 -118
View File
@@ -2,149 +2,75 @@
**代码即文档。文档即代码。**
Marqdo 是一门正在设计中的编程语言:源文件既是可执行程序,也是可被 Markdown 渲染的文档。写法本身就是叙述;运行与阅读共用同一份文本,而不是两套彼此漂移的产物。
Marqdo 是一门编程语言:源文件是可执行的程序,也是可被 Markdown 渲染的文档。语法由 Markdown **标记**本身承担(Markup-as-Syntax),而不是在文档里嵌入另一套关键字。
第一版语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 示例:[examples/](examples/)
---
## 为什么需要一门新语言
传统工作流里,代码与文档是两套工件:
传统工作流里,代码与文档是两套工件,文档写完即开始过时。Literate Programming、注释生成文档、Markdown 围栏演示都无法做到「同一份文本既是程序又是说明」。
| | 代码 | 文档 |
|---|---|---|
| 写给谁 | 机器 / 编译器 | 人 |
| 保真度 | 精确、可执行 | 易读、可解释 |
| 典型命运 | 持续演进 | 逐渐过时 |
Marqdo 的路径:**标记即语法**——标题是函数,粗体是输出,斜体是返回值,列表是控制流,表格是集合。
我们用注释、README、Wiki、生成器去弥合裂缝,但裂缝从未真正消失——文档写完的那一刻,就开始落后于代码。
---
**Literate Programming** 把叙事与代码交织,仍是「文档里嵌代码」。
**Markdown + 代码块** 适合演示,不适合构建真实系统。
**注释生成文档** 能提取签名与说明,却无法保证叙事与实现同构。
## 语法速览(v0)
Marqdo 想走第三条路:**语言的语法与语义从一开始就按「可渲染、可阅读、可执行」一起设计**,而不是事后把代码「翻译」成文档。
| 标记 | 含义 |
|------|------|
| `#` / `##` | 函数与作用域 |
| `-` 纯名(函数头下) | 形参 |
| `-`(体内) | 循环 |
| `+` 或 `1.` | 分支(`*` 独行 = else) |
| `**…**` | 输出 |
| `*…*` | 返回值 |
| `` `name` `` | 变量;`=` 绑定,`==` 比较 |
| `>` | 调用;frontmatter 里 `> file.mq.md` 为跨文件导入 |
| 表格 | 集合 |
```markdown
---
title: Hello World
---
# main
> 输出函数 输出内容=Hello World!
## 输出函数
- 输出内容
**`输出内容`**
```
更多:[examples/index.mq.md](examples/index.mq.md)、[examples/branch.mq.md](examples/branch.mq.md)、[examples/loop.mq.md](examples/loop.mq.md)。
---
## 核心理念
### 1. 同一份源,两种阅读
一份 `.mq.md` 源文件:
- **对机器**:是完整的程序——可解析、可类型检查、可执行。
- **对人 / 渲染器**:就是 Markdown——GitHub、编辑器预览、静态站点无需转换即可阅读。
后缀选用 `.mq.md`,刻意让「可被 Markdown 工具链直接渲染」成为默认能力,而不是可选插件。
**手写的只有源。** 依赖与模块元数据由工具链分析 `.mq.md` 后,生成 **OKF 风格的 YAML/Markdown 清单**(类比其它语言由工具维护的依赖描述),并可自动汇总成本项目的目录文档——不是给人填的配置文件。详见 [设计草案](doc/design/generated-yaml-manifest.md)。
不是「从代码生成文档」,也不是「从文档提取代码」。**源文本本身就是程序与说明**;生成清单只是全项目的结构化投影。
### 2. 语法即排版
若代码要自动成为好文档,语法就不能只对解析器友好。
Marqdo 的设计约束包括:
- **结构即层级** — 模块、类型、函数的嵌套应对应文档的标题层级,而不是依赖额外的 `@section` 注解。
- **命名即语义** — 标识符、契约、类型应能在渲染后直接读懂,少依赖旁白式注释。
- **声明即说明** — 接口、不变量、副作用边界写在语言里,而不是散落在散文里。
- **噪声极低** — 括号、分号、样板代码若无法帮助理解,就不应存在。
一门「看起来像 Markdown」却无法严肃编程的语言会沦为玩具;一门「能编程」却渲染成乱码的语言则失去初衷。Marqdo 必须同时成立。
### 3. 可读性是一等公民
多数语言把可读性交给风格指南与格式化工具。Marqdo 把可读性抬升为语言语义的一部分:
- 良好的程序应当**读起来像一篇写清楚的说明**。
- 糟糕的抽象、含糊的命名、隐式的副作用,不仅是工程问题,也是**文档失败**。
- 工具链(格式化、诊断、预览)的目标是:打开源文件时,你已经在读文档;运行它时,你已经在跑程序。
### 4. 设计优先于实现
「代码即文档」听起来简单,落地极难。它要求我们在以下张力之间找到平衡:
```
表达力 ↔ 简洁性
精确性 ↔ 可读性
可组合性 ↔ 叙事流畅
机器友好 ↔ 人类友好
```
没有深思熟虑的语法、类型与模块设计,这门语言很容易退化成「带一点 Markdown 装饰的脚本」。因此 Marqdo 会**先把语言设计做对**,再推进解释器、编译器与生态——宁可慢,不可歪。
---
## 愿景一瞥
理想中的 Marqdo 程序,打开时像文档,运行时像程序:
```markdown
# 购物车
维护一组商品行,并给出应付总额。
## 行项目
一行包含名称、单价与数量。
type Line =
name: Text
price: Number
qty: Number
## 总额
总额是所有行的 `price × qty` 之和。
fn total(cart: [Line]) -> Number =
cart |> map(l => l.price * l.qty) |> sum
```
> 以上仅为思想示意,**不是**最终语法。真实语法将在设计文档中逐步敲定。
关键点不在于「看起来像 Markdown」,而在于:
1. 叙事结构与程序结构同源;
2. 类型与函数是文档中的一等段落,而非被围栏隔离的异类;
3. 读者与执行者看到的是同一份真相。
---
## 我们关心的设计问题
后续设计将围绕这些问题展开(非完整列表):
- **边界**:哪些 Markdown 结构是程序结构?哪些只是散文?
- **求值与排版**:同一文本如何无损地同时服务解析器与渲染器?
- **类型与证明**:类型信息如何既服务检查,又服务阅读?
- **模块与长文**:大型程序如何仍像一本可导航的书,而不是一堵墙?
- **交互文档**:渲染结果能否嵌入可运行示例、求值结果、实时预览?
- **互操作**:如何与现有语言、工具链、包生态共存?
1. **同一份源,两种阅读** — `.mq.md` 对人是 Markdown,对机器是程序。
2. **手写源,生成清单** — 依赖/模块目录以 OKF 风格由工具生成,不是手填配置([说明](doc/design/generated-yaml-manifest.md))。
3. **行首判别** — 有标记则执行,无标记则注释(注释内标记无语义)。
4. **设计优先于实现** — 先定映射宪法,再选型实现。
---
## 现状
Marqdo 处于**思想与语言设计**阶段。各阶段开发文档集中在 [`doc/`](doc/):
- 语法映射 v0:**已定论** — [markdown-mapping.md](doc/design/markdown-mapping.md)
- 调研:[OKF](doc/research/okf-and-marqdo.md)
- 下一步:实现技术选型、解析器与测试
- 设计原则与决策记录(ADR)
- 调研笔记(含对 [OKF](doc/research/okf-and-marqdo.md) 等相邻标准的借鉴)
- 语法草案与示例
- 参考实现(解析 · 渲染 · 求值)
- 工具与编辑器支持
欢迎讨论理念与设计;实现会随后跟上。
文档目录:[doc/](doc/)
---
## 命名
**Marqdo** = **Marq**(mark / Markdown)+ **do**(行动、执行)。
标记是为了被人读懂;`do` 是为了被机器执行。两者不应再分家。
**Marqdo** = **Marq**(mark / Markdown)+ **do**(执行)。
---
+14 -10
View File
@@ -1,25 +1,29 @@
# Marqdo 开发文档
本目录存放 Marqdo 各阶段的设计与调研文档,与实现代码分离,便于在语言定型前持续迭代思想。
本目录存放各阶段设计与调研文档。
## 目录约定
| 路径 | 用途 |
|------|------|
| [`research/`](research/) | 外部标准、论文、相邻系统的调研与借鉴分析 |
| [`design/`](design/) | 语言设计草案、语法、语义、模块模型 |
| `adr/` | 架构决策记录(Architecture Decision Records,待建) |
| `roadmap/` | 阶段目标与里程碑(待建) |
| [`research/`](research/) | 外部标准与调研 |
| [`design/`](design/) | 语言设计(语法映射、清单模型等) |
| `adr/` | 架构决策记录(待建) |
| `roadmap/` | 里程碑(待建) |
## 当前文档
| 文档 | 摘要 |
|------|------|
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | Google OKF 调研,以及对 Marqdo 的可借鉴点 |
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 机器生成的 OKF 风格 YAML 清单(依赖 / 项目文档,非配置文件) |
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0 语法宪法**:Markup-as-Syntax 全映射 |
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 机器生成的 OKF 风格依赖/文档清单 |
| [design/tech-stack.md](design/tech-stack.md) | 参考实现技术选型(TypeScript + remark + Vitest) |
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | Google OKF 调研与借鉴 |
示例程序见仓库 [`examples/`](../examples/)。
## 写作原则
1. **先思想,后实现** — 文档应说清「为什么」与「约束」,避免过早绑定未验证的语法细节。
2. **可演进** — 草案用日期或版本标注;被否决的路径保留在 ADR,不默默删除。
3. **与源文件同构** — 文档本身尽量用清晰 Markdown;示例源文件统一使用 `.mq.md` 后缀。
1. 先思想,后实现。
2. 草案可演进;否决项进 ADR。
3. 示例统一 `.mq.md`。
+2
View File
@@ -28,6 +28,8 @@ Marqdo 项目中的 **YAML(及由其组成的 OKF 风格知识包)是工具
**唯一手写真相**仍是 `.mq.md` 源文件正文。YAML 清单是派生工件;过时则重新生成,禁止当成第二套权威配置去手改(除非工具链明确支持的「生成后微调」流程,且须可复现)。
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `> other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
---
## 纠正:它不是什么
+266
View File
@@ -0,0 +1,266 @@
# Marqdo 语法映射 v0(Markup-as-Syntax)
| | |
|---|---|
| 状态 | 已定论(第一版宪法) |
| 日期 | 2026-08-04 |
| 相关 | [生成式 YAML/OKF 清单](generated-yaml-manifest.md) · [OKF 调研](../research/okf-and-marqdo.md) |
本文规定:Markdown **标记即 Marqdo 语法**。不在文中嵌入 `print` / `fn` / `import` 等外来关键字作为主路径。
---
## 1. 哲学
1. 源文件后缀 `.mq.md`:打开即渲染,运行即程序。
2. **行首符号**区分代码与注释;注释内一切标记无语义(无副作用强调写在注释行)。
3. **作用域唯一来源** = 标题 `#` 的个数;缩进不建立作用域。
4. 工程入口:`index.mq.md`(对齐 OKF 的 index 角色)。
---
## 2. 行首判别
对每一行:跳过前导空白,看第一个非空白字符。
| 情况 | 分类 |
|------|------|
| 无非空白,或首字符为普通文字(含 CJK) | **注释** — 忽略行内一切 Markdown 标记 |
| 首字符开启 Markdown/Marqdo 标记 | **代码** — 按标记解释 |
v0 标记字符至少包括:`#` `*` `>` `+` `-` `` ` `` `|`(表格)以及有序列表数字。
空行分隔结构,不执行。
---
## 3. 缩进政策
- **要识别**:CommonMark 列表嵌套缩进;行首先剥空白再认标记。
- **不要**:把缩进做成 Python 式作用域(作用域只认 `#` 层级)。
- **避免**:用 ≥4 空格缩进普通注释段(会变成 GFM 缩进代码块,破坏「打开即文档」)。v0 对此应警告或报错。
---
## 4. 映射总表
| 标记 | 语义 |
|------|------|
| `#` … `######` | 函数 / 代码块;层数 = 嵌套与作用域 |
| 函数头下 `-` 纯名 | 形参(每行一个) |
| 体内 `-` | **循环**(while / foreach) |
| 体内 `+` | **分支**(推荐) |
| 体内 `1.` `2.` … | **分支**(同样合法) |
| 分支臂整行恰为 `*` | else |
| `> 函数 形参=实参` | 调用 |
| frontmatter 中 `> path.mq.md` | **跨文件导入** |
| `**…**` | **输出**(stdout) |
| `*…*` | **返回值** |
| `` `name` `` | 变量;行首 `` `名` = … `` 为绑定 |
| `` `a` == `b` `` | 相等比较(比较不用单独 `=`) |
| GFM 表格 | 集合字面量 |
| 无标记行 | 注释 |
| ` ```lang ` 围栏 | 外联异种代码(FFI 细节后置) |
---
## 5. Frontmatter 元信息与跨文件
```markdown
---
title: 主程序
description: 示例入口
> utils.mq.md
> lib/math.mq.md
---
```
- 可含普通 YAML 键值(`title`、`description` 等)与 **`>` 导入行**(Marqdo 扩展;实现按行扫描,勿假定整块为纯 YAML)。
- `> path.mq.md`:导入目标文件顶层公有定义(顶层 `#`);`##` 及更内层默认不导出。
- 路径相对当前文件。生成 OKF 依赖清单时可从这些行收集边。
- 正文 `> 名字 …` 为调用;frontmatter `> ….mq.md` 为文件导入(以路径/后缀区分)。
源 frontmatter = 文稿/代码元信息 + 人手声明的导入;工程级 OKF 目录仍由工具生成(见 [generated-yaml-manifest.md](generated-yaml-manifest.md))。
---
## 6. 函数、作用域、提升
```markdown
# 输出函数
- 输出内容
*`输出内容`*
```
- `#` 个数决定嵌套;内层可见外层;内层同名遮蔽外层。
- **定义顺序不影响可调用性**:Pass1 收集标题树,Pass2 再执行(提升)。
- **推荐**:非公有助手写成调用方下的 `##`,缩小作用域、减少泄露。
- **公有**:与入口同级的顶层 `#`,可供其它文件在导入后 `>` 调用。
推荐写法(调用可出现在内嵌定义之前,靠提升;调用写在 `# main` 下、`##` 之前,以免落入子节):
```markdown
# main
> 输出函数 输出内容=Hello World!
## 输出函数
- 输出内容
**`输出内容`**
```
(上例「输出函数」体用 `**…**` 做输出;若交回值则用 `*…*`。)
形参 `- 输出内容` 在体内以 `` `输出内容` `` 引用。
---
## 7. 输出与返回
| 构造 | 作用 |
|------|------|
| `**…**` | 输出到 stdout;可嵌 `` `变量` `` |
| `*…*` | 函数返回值;可嵌变量与表达式 |
| 注释行内的 `*` / `**` | 无语义 |
else 消歧:分支臂**第一行整行恰好一个** `*` → else。
`*中间有内容*` → 返回,不是 else。
```markdown
# 加一
- n
*`n` + 1*
```
绑定调用返回值(细写可后续收紧):
```markdown
`y` = > 加一 n=3
```
---
## 8. 绑定与比较
| 写法 | 含义 |
|------|------|
| `` `x` = 1 `` | 绑定 |
| `` `x` == 1 `` | 相等比较 |
| `` `x` = `y` `` | 绑定(右值为引用) |
比较还支持 v0 最小集:`>` `<` `>=` `<=`(出现在臂头/while 头/表达式中时)。
---
## 9. 分支(`+` 或有序)
自上而下找第一个条件为真的臂执行;else 必须在最后。
```markdown
`x` = 0
+ `x` > 0
**正数**
+ `x` < 0
**负数**
+ *
**零**
```
有序形式同等合法。v0 **不用** `*` 作为无序列表项目符(避免与 else、斜体冲突)。
---
## 10. 循环(仅 `-`)
| 项头形状 | 种类 |
|----------|------|
| `[元素](集合)` | foreach:链接文字=循环变量,目标=集合名 |
| 布尔条件 | while |
| 其它 | 编译错误 |
多项顶层 `-` = 依次执行多个循环。
```markdown
- [果](篮子)
**今天吃`果`**
- `n` > 0
**`n`**
`n` = `n` - 1
```
---
## 11. 集合:GFM 表格
以 GFM 为准(纯 CommonMark 无表格)。须有表头行 + 分隔行。
```markdown
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
```
| 形状 | 含义 |
|------|------|
| 单列多行 | 序列 |
| 单行多列 | 元组 / 向量 |
| 多列多行 | 记录序列;表头=字段名,行进入 foreach 后字段名进作用域 |
| 仅表头无数据 | 空集合 |
`` `名` = `` 后紧跟表格块 → 表格为右值。单列/单行均合法。
---
## 12. 三种 `-` / 列表消歧
1. **形参**:紧跟函数标题,项为纯标识符名。
2. **循环**:函数体内,项目符为 `-`,项头为链接或条件。
3. **分支**:项目符为 `+`,或有序列表。
---
## 13. 求值入口
1. 加载 `index.mq.md` 与 frontmatter(含 `>` 导入)。
2. Pass1:加载导入文件;收集所有函数定义树。
3. Pass2:优先执行顶层 `# main`;若无,按文档序执行顶层可执行节点。
4. 遇 `-` 列表 → 循环;遇 `+` / 有序 → 分支;遇 `>` / `**` / `*` / 绑定 / 表 → 相应动作。
---
## 14. v0 非目标
- `break` / `continue`、完整错误模型、标准输入
- 静态类型系统、完整 FFI 约定
- 用 `*` 作无序列表符
---
## 15. 已知后续 ADR
- `>` 调用作右值的空白与多实参细写
- 记录字段名遮蔽规则
- frontmatter 字段正式 schema
- 表达式与运算符全文法
---
## 16. 示例索引
| 文件 | 说明 |
|------|------|
| [examples/hello.mq.md](../../examples/hello.mq.md) | 最小输出 |
| [examples/index.mq.md](../../examples/index.mq.md) | 推荐入口:main + 内嵌 + 调用 |
| [examples/branch.mq.md](../../examples/branch.mq.md) | `+` 分支 |
| [examples/loop.mq.md](../../examples/loop.mq.md) | while / foreach |
| [examples/collection.mq.md](../../examples/collection.mq.md) | 表格集合 |
| [examples/utils.mq.md](../../examples/utils.mq.md) | 供导入的公有函数 |
| [examples/with-import.mq.md](../../examples/with-import.mq.md) | frontmatter `>` 跨文件 |
+74
View File
@@ -0,0 +1,74 @@
# 技术选型 v0(参考实现)
| | |
|---|---|
| 状态 | 草案(选型结论) |
| 日期 | 2026-08-04 |
| 目标 | 能跑通 `examples/*.mq.md` 的解析 + 求值,并用测试锁定行为 |
---
## 结论
**第一版参考实现采用 TypeScript(Node.js ≥ 20)+ 统一语系 Markdown 工具链 + Vitest。**
| 层 | 选择 | 理由 |
|----|------|------|
| 语言 | TypeScript | 与 GFM/MD 生态最贴;类型利于 AST;后续可编译到 WASM/CLI |
| Markdown 解析 | `remark-parse` + `remark-gfm` + `mdast` | 得到标题/列表/强调/表格/引用的标准 AST,避免手写 GFM |
| 运行 | Node.js ESM | CLI 简单;`fs` 读 `.mq.md` |
| 测试 | Vitest | 快;用 fixtures 对照 `examples/` 期望 stdout |
| 包管理 | pnpm | 锁文件清晰(亦可用 npm) |
**暂不采用:** Python 快速原型(后期两套实现成本高)、Rust 首版(MD 生态与迭代速度不如 TS 适合验证语法宪法)。语法稳定后再考虑 Rust 重写热路径或正式编译器。
---
## 架构草图
```
.mq.md
→ remark/GFM → mdast
→ marqdo lower:行首判别、标题树、列表符语义(- / + / 1.)
→ AST(函数、调用、输出、返回、分支、循环、表、绑定)
→ Pass1 收集定义 + frontmatter `>` 导入
→ Pass2 求值 → stdout / 返回值
```
包建议(仓库内):
```
packages/marqdo/ # 或暂用根目录 src/
src/parse.ts
src/lower.ts
src/eval.ts
src/cli.ts
tests/fixtures/
```
首版 CLI:`marqdo run examples/hello.mq.md` → 打印 `Hello World!`
---
## 测试策略
1. **金样例**:每个 `examples/*.mq.md` 对应一份期望输出(`.stdout` 或测试内快照)。
2. **单元**:行首判别、`-`/`+` 消歧、`*` else vs `*ret*`、表格绑定。
3. **排查顺序**:先 hello → index → branch → loop → collection → with-import。
---
## 里程碑
1. 脚手架 + `run` hello
2. 函数 / 调用 / 输出 / 返回
3. 分支 `+` 与循环 `-`
4. 表格集合 + foreach
5. frontmatter `>` 导入
---
## 非目标(本选型文档)
- LSP、格式化、编译到原生
- 完整表达式文法一次性做完(按测试增量加)
+16
View File
@@ -0,0 +1,16 @@
---
title: 分支示例
---
# main
根据 `x` 的符号输出中文说明。使用 `+` 作为分支列表符;最后一臂 `*` 为 else。
`x` = 0
+ `x` > 0
**正数**
+ `x` < 0
**负数**
+ *
**零**
+18
View File
@@ -0,0 +1,18 @@
---
title: 集合(表格)示例
---
# main
用 GFM 单列表格定义序列,再 foreach 打印。
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
- [果](篮子)
**`果`**
+5
View File
@@ -0,0 +1,5 @@
# Hello World
本程序向标准输出打印一句问候。注释里的 **强调** 不会输出。
**Hello World!**
+15
View File
@@ -0,0 +1,15 @@
---
title: Hello World
description: 推荐风格入口——内嵌助手函数与调用(调用可写在定义之前,靠提升解析)
---
# main
向标准输出打印一句问候。助手函数定义在 main 内部,避免名字泄露。
> 输出函数 输出内容=Hello World!
## 输出函数
- 输出内容
**`输出内容`**
+25
View File
@@ -0,0 +1,25 @@
---
title: 循环示例
---
# main
## while:倒数
`n` = 3
- `n` > 0
**`n`**
`n` = `n` - 1
## foreach:遍历篮子
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
- [果](篮子)
**今天吃`果`**
+14
View File
@@ -0,0 +1,14 @@
---
title: 工具函数
description: 供其它文件通过 frontmatter > 导入的公有模块
---
# 加一
- n
*`n` + 1*
# 问候
- 谁
**你好,`谁`!**
+14
View File
@@ -0,0 +1,14 @@
---
title: 跨文件导入示例
> utils.mq.md
---
# main
frontmatter 中的 `> utils.mq.md` 导入同目录公有函数,再调用并打印返回值。
`y` = > 加一 n=41
**`y`**
> 问候 谁=Marqdo