Add module intros and per-function purpose lines across EN/ZH libs, with callable examples on the smaller modules; keep + params and host bodies intact. Co-authored-by: Cursor <cursoragent@cursor.com>
Marqdo
代码即文档。文档即代码。文档即知识库。
Marqdo 把 Markdown 标记当作编程语法:同一个 .mq.md 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
欢迎访问 marqdo 官方网站 阅读更多特性与可执行文档。
语法宪法:doc/design/markdown-mapping.md · 对象:objects.md · 调用实参:call-arguments.md · 用户站:user-site.md · 浏览:view.md · 调试:view-debug.md · OKF 清单:catalog-cli.md · VS Code 扩展:vscode-extension.md(分支 vscode-extension;提交约定 vscode-extension-commit.md) · AI Skill:skills/marqdo/(说明 ai-skill.md) · 官方扩展:ext-llm.md(ext/llm)· ext-agent.md(智能体开发框架)· ext-cli.md(marqdo ext list/add/remove) · 原生插件 ABI:ext-abi.md(lib/plugin) · 金样例:tests/ · 用户文档:public/ · 变更:CHANGELOG.md
为什么重要
| 痛点 | Marqdo 的答案 |
|---|---|
| 文档过期、示例跑不通 | 一份源文件:叙述、结构与执行结果同源 |
| 知识散落在 Wiki / 注释 / 脚本里 | .mq.md 即知识单元,可浏览、可运行、可检索 |
| 人写给人看,AI / 工具另起一套 | 人机同读同写同构:标记语言对人类友好,对解释器确定 |
| 大仓里「文档站」与「代码仓」脱节 | view 文档站 + debug 调试面 + catalog 清单,同一棵树长大 |
这不是「再做一个 Markdown 渲染器」,而是:把文档升格为可解释的程序与可生长的知识库,让协作在大型项目里依然站得住。
语法速览(v0.2)
| 标记 | 含义 |
|---|---|
| 无标记行 | 注释(空行分段) |
*…* |
程序语句 |
**…** |
返回值(架构) |
**** / ** + 空白 + ** |
空返回(None),并结束本函数体 |
> print … 等 |
输出等副作用 = 普通函数,非架构标记 |
# |
对象 / 类型(构造体;# main = 入口) |
## … |
函数 / 方法(按标题深度嵌套) |
> `obj`.method … |
方法调用(obj 为带 _type 的 map) |
+ / 1. … |
函数头下 + `名` = 形参;体内 1. 2. … = 分支(N. * = else) |
- |
循环(- `条件` 或 - [项](集合) / - [`项`](`集合`)) |
| 表格 | 集合 |
单独一行 --- / *** |
叙述分隔(跳过;不是函数收束) |
空返回 *None* / 整行 ** / **** |
结束本函数体并返回 None |
文件开头成对 --- … --- |
Frontmatter(元信息 / 导入) |
# main
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello `谁`!
*None*
## 加一
+ `n`
**`n` + 1**
完整约定:markdown-mapping-v0.3.md。
理念
- 叙述默认安全(无标记 = 注释)。
- 返回是架构;打印只是函数。
- 代码即文档即知识库:文稿可执行,执行可回看结构,结构可导航与调试。
- 对齐 OKF(Open Knowledge Format)方向:清单由工具从
.mq.md自动生成,不是手填配置——见下节与 catalog-cli.md。 - 正经解释器(Rust):词法/行分类 → 语法 → 语义 → 树遍历(及字节码);不用 Flex/Bison。见 路线图。
OKF 风格清单(自动生成)
从源码派生 YAML / Markdown 知识包(勿手改生成物):
marqdo catalog [PATH] -o OUT_DIR
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
| 参数 | 默认 | 说明 |
|---|---|---|
PATH |
. |
工程根或含 .mq.md 的目录 |
-o / --out |
.marqdo |
输出目录 |
产物示例:catalog.yaml、index.md、modules/*.md(type: Marqdo Module 等)。设计见 generated-yaml-manifest.md · 调研 okf-and-marqdo.md。
智能体框架横向调研(LangGraph / CrewAI / 厂商 SDK 等 vs Marqdo 文档驱动优势):agent-frameworks-and-marqdo.md · 优化路线 ext-agent-optimize.md。
cargo run -- catalog public -o .marqdo
# 或已安装二进制时:
marqdo catalog public -o .marqdo
现状(v0.4.0)
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在
tests/ - 对象:
#= 类型/构造,##+ = 函数/方法;见 objects.md marqdo view:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)marqdo debug:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)marqdo catalog/sync:OKF 风格 YAML + 模块概念页marqdo version --check:与 GitHub 最新 release 对比- 标准库:内置于二进制(v0.1.2+);磁盘
lib/或MARQDO_LIB可覆盖。模块含文本、表、浏览器效应、文件、系统、时间、JSON、网络、数学、外联、插件、自写回、子任务;中层 Mid M1–M6 + Mid2 M7–M10(datetime/url/toml/html/fs++/stats/log.fields 等,见 stdlib-mid.md · stdlib-mid2.md) - 官方扩展库
ext/(非 stdlib,本版收口):web:W0–W7 + P3 + W8;定制 C0–C4;宿主 H1–H2(proxy/invoke,见 ext-hosting.md);原生层默认 Golibweb(ADR 0004,scripts/build-web-plugin.sh);示例 marqdo-blog · anlian-mq;生产路径见 web-asgi-servers-and-marqdo.mdquantum:Q0–Q7 + Q8a/b 主题 SVG;示例 quantum-entanglementlinalg:L0–L6 + 公式文档面(中缀 /declare/ 展示化简);示例 linalg-transpose · linalg-svd · linalg-least-squaresagent:A1–A4 + MCP Server stdio(mcp_server);宿主缺口见 ext-hosting.md · agent-framework-gaps-after-a4.mdllm:OpenAI 兼容对话- 安装:
marqdo ext list/add …/remove(ext-cli.md;默认~/.marqdo/ext)。原生插件先cargo build -p marqdo_plugin_*再ext add
- 原生插件 ABI:
include/marqdo_abi.h· ext-abi.md;plugins/{demo,agent,web,quantum,linalg}(web为 Go;其余为 Rust) - 用户静态站:
public/→view output→ CI 发布 gh-pages - VS Code 扩展:分支
vscode-extension(main不跟踪源码;见 vscode-extension-commit.md);Release 附带.vsix - 浏览器 Marqdo(WASM):
marqdo wasm build+ 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);lib/browser+ GFM;web.client_embed;示例 browser-hello · browser-app · browser-media · web-client-site(ADR 0002 · D · E · F) - 选型:ADR 0001 — Rust · ADR 0002 — 浏览器 WASM(C0–C5 完结,见 roadmap/browser-wasm.md)· ADR 0003 — 异步效应
如何使用最新 Marqdo(v0.4.0)
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v0.4.0 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
marqdo version --check
# 2) 跑解释器 / 文档站 / catalog
marqdo run tests/structure/hello.mq.md
marqdo run tests/structure/hello.mq.md --backend bytecode
marqdo view public --no-open
marqdo debug public --no-open
marqdo catalog public -o .marqdo
# 3) 安装官方扩展(Release 用户:无需本机 Rust/Go)
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(Go libweb)
marqdo ext add agent # 或:智能体
marqdo ext add quantum # 或:量子
marqdo ext add linalg # 或:线性代数
marqdo ext add llm # 或:大模型(纯 .mq.md)
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg}
# bash ./scripts/build-web-plugin.sh # 需 Go + cgo → libweb
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1
# 4) 动态站示例(扩展装好后)
marqdo run examples/marqdo-blog/index.mq.md
marqdo run examples/anlian-mq/index.mq.md # W-G14 验收站
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
# 5) 浏览器 WASM(可选)
marqdo wasm build
# → dist/wasm/ … 见 examples/browser-hello/
# 6) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
# https://github.com/cflmy/marqdo/releases/tag/v0.4.0
开发期也可用 cargo run -- … 代替已安装的 marqdo:
cargo run -- run tests/structure/hello.mq.md
cargo run -- view public --no-open
cargo run -- view output public -o public
powershell -File ./scripts/build-public.ps1
发布包(GitHub Releases):单独二进制 已内置官方 lib/(import …:lib/… 可直接导入)。仍提供带 lib/ 的 zip 便于覆盖或离线分发。扩展库用 marqdo ext add … 安装(见 CHANGELOG 与 ext-cli.md);原生 .so/.dll 需本地编译或从带 native/ 的安装目录解析。
文档:用户站 public/ · 设计 doc/ · OKF / catalog catalog-cli.md · 调试 view-debug.md · 变更 CHANGELOG.md
命名
Marqdo = Marq(Markdown)+ do(执行)