marqdo
阅读到这里的朋友你好！我是 Marqdo 的开发者。Marqdo 是一门「代码即文档，文档即代码」的语言：Markdown 标记就是程序结构，你读到的就是能跑的程序。
AI 偏爱 Markdown 结构的输出。我当时的念头很简单——何必再把文档和代码拆成两套？于是有了 marqdo。为了让文件既能当文档渲染又能执行，后缀定为 .mq.md。更远的目标还有 OKF 式知识库的 YAML、甚至自动生成 PPT；眼下它至少已经是个不错的博客工具——对，这个站点就是 Marqdo 生成的。AI 写 .mq.md 时往往更省 token，钱包也会轻松一点。
English docs: 00-welcome.mq.md（English prose and English builtins）.
从这一版起，不必为了试用一个函数再包一层入口。marqdo call 直接运行文件里的某个函数，参数写在命令上。同一页仍然是给人读的文档。作用和价值写在 features/22-函数调用.mq.md。
除了这些基本面，标准库里还有表、时间、文本、文件、系统、数学、外联等。我特别想提数学和外联。
比方说，直接写一块公式，并用 TeX 注释标上变量名：
外联则允许嵌一段别的语言。把hi绑成下面这样即可：
print("hello-from-python")hello-from-python — 20ms
这些在 Markdown 里读起来仍然像文章——这就是 marqdo 想坚持的：代码即文档，文档即代码。
一份文件，三个面。
| 面 | 是什么 |
|---|---|
| 文档 | 普通 Markdown：叙述、表格、链接、围栏代码 |
| 程序 | 同一批标记可执行：赋值、调用、返回 |
| 知识 | frontmatter、链接与生成的 catalog 条目，Agent 可查询 |
你正在读的静态站就是由这些文件生成的，所以示例不是截图。运行同一份源，会得到同一页。
外联 v2 是个好例子。先探测 Python，再运行绑定围栏：
同一个模块还支持 JSON 调用、并行扇出、持久内核与显式状态桥。见 stdlib/外联.mq.md 与完整 Python 示例 features/19-外联视图单元.mq.md。
view 仍然是一篇文档。命名内核与单元顺序就是普通绑定表：
`分析内核` =
| 名称 | 语言 | 说明 |
|------|------|------|
| 分析 | python | 共享状态 |
| 复核 | python | 隔离状态 |
`分析单元` =
| 单元 | 内核 | 说明 |
|------|------|------|
| 准备数据 | 分析 | 写入 |
| 计算指标 | 分析 | 读取 |
| 独立复核 | 复核 | 校验 |
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`marqdo view 消费 foreign 拥有的 会话 句柄，变成 Run All、Step、每单元内核、journal 与状态面板。没有 会话 时，单元是无状态的一次性运行。没有单独的交互模式或命令；marqdo run 仍然把文件当单个程序运行。
文档能被发现、验证和复用时，才成为知识。OKF 提供可移植的 Markdown + YAML 形态；EKC 把仓库投影成 catalog L0–L4、图与工程 preflight。源 .mq.md 始终是唯一权威，生成物有标记、可重建。
| 循环 | 问题 |
|---|---|
| OKF | 人和 Agent 如何共享一页可读知识？ |
| EKC | 创建之前，应该复用哪些已有能力、决策、约束与失败？ |
| Preflight | REUSE → ADAPT → CREATE |
概念与命令见 features/20-OKF与EKC.mq.md。
最后，再次欢迎你，尽情体验 marqdo 吧！
解释器（CLI）任选其一：
| 方式 | 说明 |
|---|---|
| Ubuntu PPA | `sudo add-apt-repository ppa:cflmy/marqdo` 后 `sudo apt install marqdo` |
| GitHub Releases | [releases](https://github.com/cflmy/marqdo/releases) 下载 Windows / Linux 预编译包 |
| 源码 | `cargo build --release`（需本机 Rust） |
官方扩展与 CLI 可分开更新。安装扩展：
marqdo ext add web
marqdo ext add quantumext add 下载顺序：CDN https://ext.marqdo.com → GitHub → proxy 镜像。详见本站 features/05-扩展.mq.md。
| lang | python |
| cmd | python3 --version |
| path | /usr/bin/python3 |
| ok | True |
| version | Python 3.12.3 |
| error |
| key | value |
|---|---|
| lang | python |
| cmd | python3 --version |
| path | /usr/bin/python3 |
| ok | True |
| version | Python 3.12.3 |
| error |
结构步骤（非实际执行时序）
navigation `features/05-扩展.mq.md`call 打印call 问候 → mq://public/00-%E6%AC%A2%E8%BF%8E/function/main/%E9%97%AE%E5%80%99navigation stdlib/外联.mq.mdnavigation features/19-外联视图单元.mq.mdnavigation features/20-OKF与EKC.mq.mdcall 问候 → mq://public/00-%E6%AC%A2%E8%BF%8E/function/main/%E9%97%AE%E5%80%99observe okcall 打印call 打印navigation `stdlib/`navigation GitHubnavigation `00-welcome.mq.md`navigation features/22-函数调用.mq.mdmq://public/00-%E6%AC%A2%E8%BF%8E/function/main/%E5%AE%89%E8%A3%85() → anysha256:5f1e0e42172b0… （未检查锁定状态）nonemq://public/00-%E6%AC%A2%E8%BF%8E/function/main/%E9%97%AE%E5%80%99(谁: any) → anysha256:d51dd5f2bb056… （未检查锁定状态）none---
markup: occlusion
title: 欢迎使用 Marqdo
description: 用户文档首页 — 代码即文档（中文版）
导入:
数学: lib/数学.mq.md
外联: lib/外联.mq.md
---
# main
阅读到这里的朋友你好！我是 Marqdo 的开发者。Marqdo 是一门「代码即文档，文档即代码」的语言：Markdown 标记就是程序结构，你读到的就是能跑的程序。
AI 偏爱 Markdown 结构的输出。我当时的念头很简单——何必再把文档和代码拆成两套？于是有了 marqdo。为了让文件既能当文档渲染又能执行，后缀定为 `.mq.md`。更远的目标还有 OKF 式知识库的 YAML、甚至自动生成 PPT；眼下它至少已经是个不错的博客工具——对，这个站点就是 Marqdo 生成的。AI 写 `.mq.md` 时往往更省 token，钱包也会轻松一点。
语言仍在起步：结构标记、中英内核双名（`打印` / `print` …）、可导入的标准库（见本站 [`stdlib/`](stdlib/)）、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
English docs: [`00-welcome.mq.md`](00-welcome.mq.md)（English prose and English builtins）.
想先打个招呼？`marqdo run` 会运行入口 `# main`。比如：**问候 谁="marqdo"**。名字里可以带空格：**问候 谁="marqdo user"**。
从这一版起，不必为了试用一个函数再包一层入口。`marqdo call` 直接运行文件里的某个函数，参数写在命令上。同一页仍然是给人读的文档。作用和价值写在 [features/22-函数调用.mq.md](features/22-函数调用.mq.md)。
除了这些基本面，标准库里还有表、时间、文本、文件、系统、数学、外联等。我特别想提数学和外联。
比方说，直接写一块公式，并用 TeX 注释标上变量名：
$$
% marqdo: var=f
x^2 - 2
$$
接着画出来：**_svg = 数学.绘图 formula=`f` var="x" min=-3 max=3**
外联则允许嵌一段别的语言。把`hi`绑成下面这样即可：
`hi` =
```python
print("hello-from-python")
```
这些在 Markdown 里读起来仍然像文章——这就是 marqdo 想坚持的：代码即文档，文档即代码。
一份文件，三个面。
| 面 | 是什么 |
|---|---|
| 文档 | 普通 Markdown：叙述、表格、链接、围栏代码 |
| 程序 | 同一批标记可执行：赋值、调用、返回 |
| 知识 | frontmatter、链接与生成的 catalog 条目，Agent 可查询 |
你正在读的静态站就是由这些文件生成的，所以示例不是截图。运行同一份源，会得到同一页。
外联 v2 是个好例子。先探测 Python，再运行绑定围栏：
**python = > 外联.探测 语言="python"**
1. [ok](access(`python`, "ok"))
**问候 = > 外联.运行 代码=`hi`**
> 打印 内容=`问候`
2. *
> 打印 内容="（未找到 python3 — 安装 Python 后可运行此单元）"
同一个模块还支持 JSON 调用、并行扇出、持久内核与显式状态桥。见 [stdlib/外联.mq.md](stdlib/外联.mq.md) 与完整 Python 示例 [features/19-外联视图单元.mq.md](features/19-外联视图单元.mq.md)。
view 仍然是一篇文档。命名内核与单元顺序就是普通绑定表：
```text
`分析内核` =
| 名称 | 语言 | 说明 |
|------|------|------|
| 分析 | python | 共享状态 |
| 复核 | python | 隔离状态 |
`分析单元` =
| 单元 | 内核 | 说明 |
|------|------|------|
| 准备数据 | 分析 | 写入 |
| 计算指标 | 分析 | 读取 |
| 独立复核 | 复核 | 校验 |
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
```
`marqdo view` 消费 foreign 拥有的 `会话` 句柄，变成 Run All、Step、每单元内核、journal 与状态面板。没有 `会话` 时，单元是无状态的一次性运行。没有单独的交互模式或命令；`marqdo run` 仍然把文件当单个程序运行。
文档能被发现、验证和复用时，才成为知识。OKF 提供可移植的 Markdown + YAML 形态；EKC 把仓库投影成 catalog L0–L4、图与工程 preflight。源 `.mq.md` 始终是唯一权威，生成物有标记、可重建。
| 循环 | 问题 |
|---|---|
| OKF | 人和 Agent 如何共享一页可读知识？ |
| EKC | 创建之前，应该复用哪些已有能力、决策、约束与失败？ |
| Preflight | REUSE → ADAPT → CREATE |
概念与命令见 [features/20-OKF与EKC.mq.md](features/20-OKF与EKC.mq.md)。
最后，再次欢迎你，尽情体验 marqdo 吧！
## 问候
见到访客`谁`时，我们 **打印 内容="欢迎，`谁`！"**，然后收束为*None*。
## 安装
解释器（CLI）任选其一：
| 方式 | 说明 |
|------|------|
| Ubuntu PPA | `sudo add-apt-repository ppa:cflmy/marqdo` 后 `sudo apt install marqdo` |
| GitHub Releases | [releases](https://github.com/cflmy/marqdo/releases) 下载 Windows / Linux 预编译包 |
| 源码 | `cargo build --release`（需本机 Rust） |
官方扩展与 CLI 可分开更新。安装扩展：
```text
marqdo ext add web
marqdo ext add quantum
```
`ext add` 下载顺序：CDN https://ext.marqdo.com → GitHub → proxy 镜像。详见本站 [`features/05-扩展.mq.md`](features/05-扩展.mq.md)。