五个可运行示例,覆盖 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 首行正文去掉了内嵌 `#` 标题写法
2.6 KiB
2.6 KiB
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 约定——传什么、读什么,都写在代码里。
汇总代码 =
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=订单
排序代码 =
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上追加一条华北订单,
再重新排序;不需要重新传一遍整张表。
追加代码 =
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=会话