From ecd7d5e43339a5911d012d28f5929d16cc2f72b8 Mon Sep 17 00:00:00 2001 From: cflmy Date: Thu, 22 Oct 2026 10:41:41 +0800 Subject: [PATCH] =?UTF-8?q?examples:=20=E6=96=B0=E5=A2=9E=20oa2026-showcas?= =?UTF-8?q?e=EF=BC=882026=20=E5=BC=80=E6=BA=90=E9=A1=B9=E7=9B=AE=E5=A4=A7?= =?UTF-8?q?=E8=B5=9B=E4=BD=9C=E5=93=81=E4=BB=8B=E7=BB=8D=E7=A4=BA=E4=BE=8B?= =?UTF-8?q?=E9=9B=86=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 五个可运行示例,覆盖 Marqdo 的核心能力面: | 文件 | 展示 | |------|------| | add.mq.md | 叙述统一、粗体即代码、斜体即返回 | | invoice.mq.md | 表格即数据、循环、分支、断言 | | calculus.mq.md | 公式即变量、求导、求根、绘图 | | bell.mq.md | 量子电路、概率、断言、SVG 派生物 | | foreign-node.mq.md | 外联一次性执行、持久会话、显式传值 | 全部实测跑通(1.5.2),输出与 README「预期输出」一节一致: - add → 42 - invoice → 960 / 912 / 966 / within-cap - calculus → 3*x^2 - 3 / 9 / [-1.73, 0, 1.73] / plot-ok - bell → {00: 0.5, 11: 0.5} / bell-00-ok / bell-11-ok / bell-draw-ok - foreign-node → 区域汇总表 + 持久会话复读 仓库侧改动: - examples/oa2026-showcase/*.svg 随示例入库(README 有说明,属固定产物) - .gitignore 忽略根目录 bell-*.svg / calculus-*.svg —— 从仓库根运行示例时 draw/plot 会把 SVG 写到 cwd,那是运行产物不是源文件 - examples/marqdo-blog/db/posts.mq.md 首行正文去掉了内嵌 `#` 标题写法 --- .gitignore | 5 ++ examples/marqdo-blog/db/posts.mq.md | 2 +- examples/oa2026-showcase/README.md | 51 +++++++++++++ examples/oa2026-showcase/add.mq.md | 10 +++ examples/oa2026-showcase/bell-circuit.svg | 24 ++++++ examples/oa2026-showcase/bell-probs.svg | 14 ++++ examples/oa2026-showcase/bell.mq.md | 58 ++++++++++++++ examples/oa2026-showcase/calculus-plot.svg | 17 +++++ examples/oa2026-showcase/calculus.mq.md | 32 ++++++++ examples/oa2026-showcase/foreign-node.mq.md | 84 +++++++++++++++++++++ examples/oa2026-showcase/invoice.mq.md | 44 +++++++++++ 11 files changed, 340 insertions(+), 1 deletion(-) create mode 100644 examples/oa2026-showcase/README.md create mode 100644 examples/oa2026-showcase/add.mq.md create mode 100644 examples/oa2026-showcase/bell-circuit.svg create mode 100644 examples/oa2026-showcase/bell-probs.svg create mode 100644 examples/oa2026-showcase/bell.mq.md create mode 100644 examples/oa2026-showcase/calculus-plot.svg create mode 100644 examples/oa2026-showcase/calculus.mq.md create mode 100644 examples/oa2026-showcase/foreign-node.mq.md create mode 100644 examples/oa2026-showcase/invoice.mq.md diff --git a/.gitignore b/.gitignore index 78b2a9c..eae8dd0 100644 --- a/.gitignore +++ b/.gitignore @@ -71,6 +71,11 @@ plugins/*/tmp/ /examples/linalg-*/**/*.svg /examples/linalg-*/*.svg /examples/linalg-*.svg +# oa2026 showcase: SVGs beside the examples ARE tracked; root-level ones are +# run artifacts (draw/plot write to cwd when the example is run from root) +/bell-*.svg +/calculus-*.svg + # Plot SVGs emitted beside tests / notebooks when demos run /tests/**/*-plot-*.svg diff --git a/examples/marqdo-blog/db/posts.mq.md b/examples/marqdo-blog/db/posts.mq.md index e70520e..563a421 100644 --- a/examples/marqdo-blog/db/posts.mq.md +++ b/examples/marqdo-blog/db/posts.mq.md @@ -24,7 +24,7 @@ import data:ext/data/db.mq.md | title | slug | summary | content | tag | created_at | |-------|------|---------|---------|-----|------------| -| Hello Marqdo | hello | Welcome | # Hello\n\nExecutable documents. | intro | 2026-09-01 | +| Hello Marqdo | hello | Welcome | Hello — executable documents. | intro | 2026-09-01 | | Artifact Web | artifact-web | Document first | Pages are mq.md files. | design | 2026-09-28 | *rows* diff --git a/examples/oa2026-showcase/README.md b/examples/oa2026-showcase/README.md new file mode 100644 index 0000000..0c43278 --- /dev/null +++ b/examples/oa2026-showcase/README.md @@ -0,0 +1,51 @@ +# oa2026-showcase + +用于 2026 开源项目大赛作品介绍文档的可运行示例。 + +| 文件 | 展示的能力 | 运行 | +|------|------------|------| +| `add.mq.md` | 叙述统一、粗体即代码、斜体即返回 | `marqdo run examples/oa2026-showcase/add.mq.md` | +| `invoice.mq.md` | 表格即数据、循环、分支、断言 | `marqdo run examples/oa2026-showcase/invoice.mq.md` | +| `calculus.mq.md` | 公式即变量、求导、求根、绘图 | `marqdo run examples/oa2026-showcase/calculus.mq.md` | +| `bell.mq.md` | 量子电路、概率、断言、SVG 派生物 | `marqdo run examples/oa2026-showcase/bell.mq.md` | +| `foreign-node.mq.md` | 外联一次性执行、持久会话、显式传值 | `marqdo run examples/oa2026-showcase/foreign-node.mq.md` | + +## 预期输出 + +```text +$ marqdo run examples/oa2026-showcase/add.mq.md +42 + +$ marqdo run examples/oa2026-showcase/invoice.mq.md +960 +912 +966 +within-cap + +$ marqdo run examples/oa2026-showcase/calculus.mq.md +3*x^2 - 3 +9 +[-1.7320508076, 0, 1.7320508076] +plot-ok + +$ marqdo run examples/oa2026-showcase/foreign-node.mq.md +{华东: 420, 华北: 220, 华南: 230} +华东: 420 +华南: 230 +华北: 220 + +华东: 420 +华北: 300 +华南: 230 + +$ marqdo run examples/oa2026-showcase/bell.mq.md +{00: 0.5, 11: 0.5} +0.5 +0.5 +bell-00-ok +bell-11-ok +bell-draw-ok +``` + +`bell.mq.md` 运行后会生成 `bell-circuit.svg` 与 `bell-probs.svg`; +`calculus.mq.md` 运行后会生成 `calculus-plot.svg`。 diff --git a/examples/oa2026-showcase/add.mq.md b/examples/oa2026-showcase/add.mq.md new file mode 100644 index 0000000..7519d39 --- /dev/null +++ b/examples/oa2026-showcase/add.mq.md @@ -0,0 +1,10 @@ +## 加一 + +对于输入变量`n`,我们执行 **`n` = `n` + 1**,然后把更新后的值作为结果返回 *`n`*。 + +# main + +从 41 出发调用「加一」,把结果存进`r`并打印。 + +**`r` = > 加一 n=41** +> print text=`r` diff --git a/examples/oa2026-showcase/bell-circuit.svg b/examples/oa2026-showcase/bell-circuit.svg new file mode 100644 index 0000000..8f37118 --- /dev/null +++ b/examples/oa2026-showcase/bell-circuit.svg @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + +q0 + +q1 +H + + + + \ No newline at end of file diff --git a/examples/oa2026-showcase/bell-probs.svg b/examples/oa2026-showcase/bell-probs.svg new file mode 100644 index 0000000..c56c528 --- /dev/null +++ b/examples/oa2026-showcase/bell-probs.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + +10000.50110.50 \ No newline at end of file diff --git a/examples/oa2026-showcase/bell.mq.md b/examples/oa2026-showcase/bell.mq.md new file mode 100644 index 0000000..0955362 --- /dev/null +++ b/examples/oa2026-showcase/bell.mq.md @@ -0,0 +1,58 @@ +--- +title: 贝尔态:两个量子比特如何一起回答 +description: 从一条假设开始,搭电路、看概率、画图,并用断言验收。 +import quantum:ext/quantum/quantum.mq.md +--- + +# main + +贝尔态:一次可读的量子实验。 + +我们先做一个假设:如果对第一个量子比特施加 Hadamard 门,再用它控制第二个量子比特翻转, +那么测量结果不会出现「一个 0、一个 1」,只会出现「00」或「11」。 + +下面的表不是配置,而是实验步骤本身。读者先读实验设计,再读执行结果。 + +`步骤` = + +| 步骤 | gate | qubits | +|------|------|--------| +| 1 | H | 0 | +| 2 | CX | 0,1 | + +**`电路` = > quantum.circuit qubits=2 steps=`步骤`** +**`概率` = > `电路`.probabilities** + +> print text=`概率` + +--- + +我们期待什么?如果假设成立,`概率`应该只在「00」与「11」上有值,而且各占一半。 +先把两个关键概率取出来,读者不必在长映射里找: + +**`p00` = [00](概率)** +**`p11` = [11](概率)** + +> print text=`p00` +> print text=`p11` + +下面的断言不是装饰:如果电路写错,或者门接错,运行会直接失败。 + +1. `p00` > 0.49 + > print text=bell-00-ok +2. * + > print text=bell-00-fail + +1. `p11` > 0.49 + > print text=bell-11-ok +2. * + > print text=bell-11-fail + +--- + +图不是截图,而是这份文档运行后生成的派生物。电路图和概率图都来自同一个`电路`。 + +**`_` = > `电路`.draw path="bell-circuit.svg" theme="light"** +**`_` = > `电路`.draw kind="probs" path="bell-probs.svg" theme="light"** + +> print text=bell-draw-ok diff --git a/examples/oa2026-showcase/calculus-plot.svg b/examples/oa2026-showcase/calculus-plot.svg new file mode 100644 index 0000000..d1f8999 --- /dev/null +++ b/examples/oa2026-showcase/calculus-plot.svg @@ -0,0 +1,17 @@ + + + + + + + +xy-3-2-1123-15-10-5510150 + \ No newline at end of file diff --git a/examples/oa2026-showcase/calculus.mq.md b/examples/oa2026-showcase/calculus.mq.md new file mode 100644 index 0000000..1e458ee --- /dev/null +++ b/examples/oa2026-showcase/calculus.mq.md @@ -0,0 +1,32 @@ +--- +title: 一份可执行的求导讲义 +description: 公式、求导、求根、求值与绘图,在同一条叙述里完成。 +import math:lib/math.mq.md +--- + +# main + +我们从一条曲线开始。下面这个公式既是排版出来的数学对象, +也是运行时可以直接求导、求根与绘图的`f`。 + +`f` = +$$ +x^3 - 3*x +$$ + +对它求导,得到`df`;再让`df`在 x = 2 处取值,得到切线斜率。 + +**`df` = [math.diff] formula=`f` var="x"** +**`slope` = [math.eval] formula=`df` var="x" value=2** +> print text=`df` +> print text=`slope` + +曲线与 x 轴的交点同样可以被机器找出来。这里不需要另写一段脚本。 + +**`roots` = [math.solve] formula=`f` var="x" min=-3 max=3** +> print text=`roots` + +最后把公式画成图。图不是截图,而是本文档运行产生的派生物。 + +**`_svg` = [math.plot] formula=`f` var="x" min=-3 max=3 path="calculus-plot.svg"** +> print text=plot-ok diff --git a/examples/oa2026-showcase/foreign-node.mq.md b/examples/oa2026-showcase/foreign-node.mq.md new file mode 100644 index 0000000..3c91d58 --- /dev/null +++ b/examples/oa2026-showcase/foreign-node.mq.md @@ -0,0 +1,84 @@ +--- +title: 外联:把 Node 当作文档里的计算车间 +description: 一次性执行、持久会话、显式传值,以及可读的结果。 +import foreign:lib/foreign.mq.md +--- + +# main + +这份文档要回答一个很具体的问题:同一批订单,按区域汇总之后,总金额分别是多少? +数据已经写在文档里,计算交给 Node,结果回到文档里继续被阅读与断言。 + +`订单` = + +| @ | 区域 | 金额 | +|---|------|------| +| 1 | 华东 | 120 | +| 2 | 华东 | 300 | +| 3 | 华南 | 90 | +| 4 | 华南 | 140 | +| 5 | 华北 | 220 | + +先做一次性执行。`foreign.call` 把`订单`编码成 JSON 放到 stdin, +Node 读完、汇总、打印 JSON;外联再把 stdout 解析成 Marqdo 的值。 +没有 shell,也没有隐式的 stdin 约定——传什么、读什么,都写在代码里。 + +`汇总代码` = +```javascript +const incoming = JSON.parse(require('fs').readFileSync(0, 'utf8')); + +const byRegion = {}; +for (const row of incoming) { + byRegion[row["区域"]] = (byRegion[row["区域"]] || 0) + Number(row["金额"]); +} + +console.log(JSON.stringify(byRegion)); +``` + +**`汇总` = > foreign.call code=`汇总代码` input=`订单`** +> print text=`汇总` + +--- + +一次性执行适合「算完就走」。如果想让同一个 Node 内核保留变量, +就显式开启会话、显式设值、显式求值、显式关闭——状态不会藏在某个看不见的 cell 里。 + +**`会话` = > foreign.session_open lang="node"** +**> foreign.session_set id=`会话` name="orders" value=`订单`** + +`排序代码` = +```javascript +const ranked = Object.entries( + orders.reduce((acc, row) => { + acc[row["区域"]] = (acc[row["区域"]] || 0) + Number(row["金额"]); + return acc; + }, {}) +).sort((a, b) => b[1] - a[1]); + +console.log(ranked.map(([region, total]) => `${region}: ${total}`).join("\n")); +``` + +**`第一次` = > foreign.session_eval id=`会话` code=`排序代码`** +> print text=[stdout](`第一次`) + +内核状态是持续的。下面这段代码在同一个`orders`上追加一条华北订单, +再重新排序;不需要重新传一遍整张表。 + +`追加代码` = +```javascript +orders.push({ 区域: "华北", 金额: 80 }); + +const rankedAgain = Object.entries( + orders.reduce((acc, row) => { + acc[row["区域"]] = (acc[row["区域"]] || 0) + Number(row["金额"]); + return acc; + }, {}) +).sort((a, b) => b[1] - a[1]); + +console.log(rankedAgain.map(([region, total]) => `${region}: ${total}`).join("\n")); +``` + +**`第二次` = > foreign.session_eval id=`会话` code=`追加代码`** +> print text=[stdout](`第二次`) + +**> foreign.session_close id=`会话`** diff --git a/examples/oa2026-showcase/invoice.mq.md b/examples/oa2026-showcase/invoice.mq.md new file mode 100644 index 0000000..582d1dd --- /dev/null +++ b/examples/oa2026-showcase/invoice.mq.md @@ -0,0 +1,44 @@ +--- +title: 一张订单,一份可执行的业务说明 +description: 叙述、数据、计算与断言共享同一个 .mq.md 源文件。 +--- + +# main + +这份文档不是代码旁边的说明,也不是说明里贴的代码。下表既是给人读的订单, +也是运行时直接使用的记录集合;下面的句子既解释业务规则,也参与计算。 + +`订单` = + +| @ | 客户 | 单价 | 数量 | 提前天数 | +|---|------|------|------|----------| +| 1 | 青山实验室 | 120 | 3 | 10 | +| 2 | 远望中心 | 80 | 5 | 4 | +| 3 | 星尘工坊 | 200 | 1 | 14 | + +逐行把「单价 × 数量」累加进`小计`。读者看到的是清单,机器执行的是同一张表。 + +**`小计` = 0** +- [行](订单) + **`小计` = `小计` + [单价](行) * [数量](行)** + +业务约定写在叙述里:提前不少于七天,整单按九五折;否则原价。 +本单最早提前 14 天。 + +**`最早提前` = 14** +1. `最早提前` >= 7 + **`折后` = `小计` * 95 / 100** +2. * + **`折后` = `小计`** + +把结果、依据和判断一起写进文档。下面的断言如果跑不通,文档本身就是错的。 + +**`含税` = `折后` * 106 / 100** +> print text=`小计` +> print text=`折后` +> print text=`含税` + +1. `含税` < 10000 + > print text=within-cap +2. * + > print text=over-cap