From 05d48f68a416896df45e7b5319bcbac3f4aa61a7 Mon Sep 17 00:00:00 2001 From: cflmy Date: Sun, 18 Oct 2026 13:23:03 +0800 Subject: [PATCH] docs(view): show kernel state and Marqdo value passing Rewrite the static foreign walkthrough without stdin-driven examples. It now demonstrates session_set from an ordinary Marqdo table, persistent kernel state across evaluations, and a foreign.session view plan sharing state across cells. Static export executes those cells and embeds the real outputs. --- public/features/19-foreign-view-cells.mq.md | 217 +++++++------------- public/features/19-外联视图单元.mq.md | 201 +++++++----------- src/view/output.rs | 3 +- 3 files changed, 148 insertions(+), 273 deletions(-) diff --git a/public/features/19-foreign-view-cells.mq.md b/public/features/19-foreign-view-cells.mq.md index 9073bcb..e865759 100644 --- a/public/features/19-foreign-view-cells.mq.md +++ b/public/features/19-foreign-view-cells.mq.md @@ -1,23 +1,32 @@ --- title: Foreign kernels v2 — Python analysis in view -description: A complete Python data walkthrough with probe, JSON calls, parallel fan-out, persistent state and view cells +description: Kernel state, Marqdo-to-kernel values and view cells — without a stdin-only demo import foreign:lib/foreign.mq.md --- # main -This page is both a readable document and a runnable program. It uses the same file to show the foreign-kernel features added in v2: language probing, structured records, JSON in/out, parallel fan-out, a persistent Python kernel, and an explicit state bridge. The same source can also be opened in view as interactive cells. - -The data is intentionally small and deterministic, so every number below can be reproduced by running the page. +This page shows the foreign runtime as a language feature: a persistent kernel, explicit state from Marqdo values, and view cells that share kernel state. It never asks the reader to type JSON into stdin. --- -The input. +Probe the interpreter first. The result is ordinary Marqdo data. -`orders` = +**python = > foreign.probe lang="python"** -| @ | region | amount | -|---|--------|--------| +> print text=[ok](`python`) +> print text=[version](`python`) + +--- + +Marqdo values into a kernel. + +The `订单` table is a normal Marqdo value. `foreign.session_set` copies it into the Python kernel as JSON; no shell and no stdin. + +`订单` = + +| @ | 区域 | 金额 | +|---|------|------| | 1 | 华东 | 120 | | 2 | 华东 | 300 | | 3 | 华南 | 90 | @@ -25,39 +34,73 @@ The input. | 5 | 华北 | 220 | | 6 | 西部 | 80 | ---- +**内核会话 = > foreign.session_open lang="python"** -Probe Python before using it. +**> foreign.session_set id=`内核会话` name="orders" value=`订单`** -**python = > foreign.probe lang="python"** +**total = > foreign.session_eval id=`内核会话` source="round(sum(float(row['金额']) for row in orders), 2)"** -> print text=[ok](`python`) -> print text=[version](`python`) +> print text=[result](`total`) -The probe record also carries `cmd`, `path` and `error`, so a site can explain a missing interpreter instead of producing a blank cell. +The low-level kernel session is managed entirely by `foreign`; the table crossed the boundary as an explicit JSON copy. --- -A JSON call. Python reads the table as JSON, groups it, and writes one JSON result. +Kernel state persists. -`analyze` = +Two evaluations share the same kernel. The second sees the first variable. + +**> foreign.session_eval id=`内核会话` source="values = [3, 4, 5]"** + +**square_sum = > foreign.session_eval id=`内核会话` source="sum(value * value for value in values)"** + +> print text=[result](`square_sum`) + +**> foreign.session_close id=`内核会话`** + +This is kernel state, not a one-shot process. It is created, queried and closed through `foreign`. + +--- + +View cells share state. + +`foreign.session` declares a view session from ordinary tables. The table names are free; this document uses `分析内核` and `分析单元`. + +`分析内核` = + +| @ | 名称 | 语言 | +|---|------|------| +| 1 | 分析 | python | + +`分析单元` = + +| @ | 单元 | 内核 | +|---|------|------| +| 1 | 准备 | 分析 | +| 2 | 计算 | 分析 | + +`会话` = > foreign.session kernels=`分析内核` cells=`分析单元` + +`准备` = +```python +orders = [ + {"区域": "华东", "金额": 120}, + {"区域": "华东", "金额": 300}, + {"区域": "华南", "金额": 90}, + {"区域": "华南", "金额": 140}, + {"区域": "华北", "金额": 220}, + {"区域": "西部", "金额": 80}, +] +``` + +`计算` = ```python import json import statistics -import sys -raw = sys.stdin.read() -rows = json.loads(raw) if raw.strip() else [ - {"region": "华东", "amount": 120}, - {"region": "华东", "amount": 300}, - {"region": "华南", "amount": 90}, - {"region": "华南", "amount": 140}, - {"region": "华北", "amount": 220}, - {"region": "西部", "amount": 80}, -] by_region = {} -for row in rows: - by_region.setdefault(row["region"], []).append(float(row["amount"])) +for row in orders: + by_region.setdefault(row["区域"], []).append(float(row["金额"])) summary = [] for region, values in sorted(by_region.items()): @@ -73,121 +116,15 @@ for region, values in sorted(by_region.items()): print(json.dumps({ "regions": summary, - "total": round(sum(float(row["amount"]) for row in rows), 2), - "count": len(rows), + "total": round(sum(float(row["金额"]) for row in orders), 2), + "count": len(orders), }, ensure_ascii=False)) ``` -**result = > foreign.call code=`analyze` input=`orders`** +`查看` consumes the `会话` handle. Run All runs `准备` then `计算` in the same Python kernel; the static export runs the same cells at build time and embeds their real outputs. -> print text=[count](`result`) -> print text=[total](`result`) -> print text=[region]([1]([regions](`result`))) -> print text=[mean]([1]([regions](`result`))) +The important language point: -A call is JSON-in / JSON-out: the table is encoded on stdin, and the final stdout value is parsed into Marqdo values. +Tables are values passed to `foreign.session`. Kernel state lives in `foreign`. View only renders the handle and its cells. `run` still executes the same document as a program. ---- - -The same work as a structured record. `invoke` keeps stdout, stderr, exit code and timing even when the program fails. - -**record = > foreign.invoke code=`analyze` input=`orders` output="json"** - -> print text=[ok](`record`) -> print text=[code](`record`) -> print text=[ms](`record`) - -Here `result` is already a parsed value, while `stdout` remains available for logging. - ---- - -Persistent Python state. The first evaluation imports a module and creates a list; the second evaluation sees both. - -**session = > foreign.session_open lang="python"** - -**first = > foreign.session_eval id=`session` source="import math\nvalues = [3, 4, 5]"** - -**second = > foreign.session_eval id=`session` source="round(math.sqrt(sum(value * value for value in values)), 3)"** - -> print text=[result](`second`) - -The kernel is strict and serial: evaluations do not interleave, and a timeout kills the process group. - ---- - -The explicit state bridge. Values cross as JSON copies, never as shared object references. - -**> foreign.session_set id=`session` name="threshold" value=2.5** - -**threshold = > foreign.session_get id=`session` name="threshold"** - -> print text=`threshold` - -**> foreign.session_close id=`session`** - -No implicit mirroring: if a variable is not pushed or pulled, the other side does not see it. - ---- - -Parallel fan-out. Every input gets its own process; failures are isolated and order is preserved. - -`increment` = -```python -import json -import sys - -raw = sys.stdin.read() -value = json.loads(raw) if raw.strip() else 1 -print(json.dumps(value + 1)) -``` - -`numbers` = - -| value | -|-------| -| 1 | -| 2 | -| 3 | -| 4 | - -**bumped = > foreign.call_many code=`increment` inputs=`numbers` concurrency=4** - -> print text=`bumped` - ---- - -Cells in view. Named kernels and a cell order are ordinary bound tables, not fence metadata or YAML config. - -```text -`分析内核` = - -| 名称 | 语言 | 命令 | 说明 | -|------|------|------|------| -| 分析 | python | | shared analysis | -| 复核 | python | | isolated review | - -`分析单元` = - -| 单元 | 内核 | 说明 | -|------|------|------| -| 准备数据 | 分析 | generate orders | -| 计算指标 | 分析 | regions and totals | -| 独立复核 | 复核 | read the JSON report | -``` - - -`marqdo view` consumes the foreign-owned `会话` handle and renders Run All, Step, per-cell kernel switching, a journal, dirty reload and a state panel. Without that handle, cells are stateless one-shot runs. There is no separate interactive command; `marqdo run` still executes the same file as one program. - ---- - -Why this stays readable. - -| Layer | What the reader sees | -|---|---| -| Markdown | headings, prose, tables and fenced code | -| Program | assignments, calls and return values | -| Knowledge | frontmatter, links, task pages and generated catalog entries | - -The foreign layer does not add syntax to the language. A fence is still a fence; a table is still a table. - -For the lower-level API and safety defaults, read [`../../lib/foreign.mq.md`](../../lib/foreign.mq.md) and [`../../doc/design/foreign-kernel.md`](../../doc/design/foreign-kernel.md). +There is no separate notebook CLI, no stdin requirement in this example, and no hidden language switch. diff --git a/public/features/19-外联视图单元.mq.md b/public/features/19-外联视图单元.mq.md index bb73cd5..ab24d51 100644 --- a/public/features/19-外联视图单元.mq.md +++ b/public/features/19-外联视图单元.mq.md @@ -1,18 +1,27 @@ --- title: 外联内核 v2 — Python 分析(view 单元) -description: 从 probe、JSON 调用、并行扇出、持久状态到显式桥与 view 交互单元的完整 Python 示例 +description: 内核态、Marqdo 值传入与 view 单元 —— 不依赖 stdin 的完整示例 导入 外联:lib/外联.mq.md --- # main -这一页既是可读文档,也是可运行程序。它用同一份文件展示 v2 的外联内核能力:语言探测、结构化记录、JSON 进出、并行扇出、持久 Python 内核,以及显式状态桥。同一份源也可以在 view 中作为交互单元打开。 - -数据故意保持小而确定,因此下面每个数字都可以通过运行本页复现。 +这一页把外联运行时当作语言能力来展示:持久内核、从 Marqdo 值显式传入状态,以及共享内核状态的 view 单元。读者不需要向 stdin 输入 JSON。 --- -输入数据。 +先探测解释器。结果仍然是普通 Marqdo 数据。 + +**python = > 外联.探测 语言="python"** + +> 打印 内容=[ok](`python`) +> 打印 内容=[version](`python`) + +--- + +Marqdo 值进入内核。 + +`订单` 表是普通 Marqdo 值。`外联.会话设值` 把它作为 JSON 复制进 Python 内核;没有 shell,也没有 stdin。 `订单` = @@ -25,29 +34,56 @@ description: 从 probe、JSON 调用、并行扇出、持久状态到显式桥 | 5 | 华北 | 220 | | 6 | 西部 | 80 | ---- +**内核会话 = > 外联.会话开启 语言="python"** -先探测 Python。 +**> 外联.会话设值 标识=`内核会话` 名称="orders" 值=`订单`** -**python = > 外联.探测 语言="python"** +**合计 = > 外联.会话求值 标识=`内核会话` 源码="round(sum(float(row['金额']) for row in orders), 2)"** -> 打印 内容=[ok](`python`) -> 打印 内容=[version](`python`) +> 打印 内容=[result](`合计`) -探测记录还带 `cmd`、`path` 与 `error`,所以站点可以解释“解释器缺失”,而不是显示一个空白单元。 +低层内核会话完全由 `外联` 管理;表格以显式 JSON 拷贝跨过边界。 --- -JSON 调用。Python 把表读成 JSON,按区域聚合,再写出一个 JSON 结果。 +内核态是持续的。 -`分析` = +两次求值共享同一个内核。第二次能看到第一次创建的变量。 + +**> 外联.会话求值 标识=`内核会话` 源码="values = [3, 4, 5]"** + +**平方和 = > 外联.会话求值 标识=`内核会话` 源码="sum(value * value for value in values)"** + +> 打印 内容=[result](`平方和`) + +**> 外联.会话关闭 标识=`内核会话`** + +这是内核态,不是一次性进程。它由 `外联` 创建、查询和关闭。 + +--- + +view 单元共享状态。 + +`外联.会话` 从普通表格声明一个 view 会话。表名完全自由;本页用 `分析内核` 和 `分析单元`。 + +`分析内核` = + +| @ | 名称 | 语言 | +|---|------|------| +| 1 | 分析 | python | + +`分析单元` = + +| @ | 单元 | 内核 | +|---|------|------| +| 1 | 准备 | 分析 | +| 2 | 计算 | 分析 | + +`会话` = > 外联.会话 内核表=`分析内核` 单元表=`分析单元` + +`准备` = ```python -import json -import statistics -import sys - -raw = sys.stdin.read() -rows = json.loads(raw) if raw.strip() else [ +orders = [ {"区域": "华东", "金额": 120}, {"区域": "华东", "金额": 300}, {"区域": "华南", "金额": 90}, @@ -55,8 +91,15 @@ rows = json.loads(raw) if raw.strip() else [ {"区域": "华北", "金额": 220}, {"区域": "西部", "金额": 80}, ] +``` + +`计算` = +```python +import json +import statistics + by_region = {} -for row in rows: +for row in orders: by_region.setdefault(row["区域"], []).append(float(row["金额"])) summary = [] @@ -73,121 +116,15 @@ for region, values in sorted(by_region.items()): print(json.dumps({ "regions": summary, - "total": round(sum(float(row["金额"]) for row in rows), 2), - "count": len(rows), + "total": round(sum(float(row["金额"]) for row in orders), 2), + "count": len(orders), }, ensure_ascii=False)) ``` -**结果 = > 外联.调用 代码=`分析` 输入=`订单`** +`查看` 消费 `会话` 句柄。Run All 会在同一个 Python 内核里先跑 `准备` 再跑 `计算`;静态导出在构建时走同一批单元,并把真实输出嵌入页面。 -> 打印 内容=[count](`结果`) -> 打印 内容=[total](`结果`) -> 打印 内容=[region]([1]([regions](`结果`))) -> 打印 内容=[mean]([1]([regions](`结果`))) +语言上的重点: -调用是 JSON 进 / JSON 出:表编码到 stdin,stdout 的最后一个值再解析成 Marqdo 值。 +表是值,传给 `外联.会话`。内核态归 `外联` 管理。view 只渲染句柄和单元。`run` 仍然把同一份文档当程序执行。 ---- - -同样的工作也可以保留成结构化记录。`执行` 即使进程失败也保留 stdout、stderr、退出码与耗时。 - -**记录 = > 外联.执行 代码=`分析` 输入=`订单` 输出="json"** - -> 打印 内容=[ok](`记录`) -> 打印 内容=[code](`记录`) -> 打印 内容=[ms](`记录`) - -这里 `result` 已经是解析后的值,同时 `stdout` 仍可用于日志。 - ---- - -持久 Python 状态。第一次求值导入模块并创建列表;第二次求值仍能看到两者。 - -**会话 = > 外联.会话开启 语言="python"** - -**第一次 = > 外联.会话求值 标识=`会话` 源码="import math\nvalues = [3, 4, 5]"** - -**第二次 = > 外联.会话求值 标识=`会话` 源码="round(math.sqrt(sum(value * value for value in values)), 3)"** - -> 打印 内容=[result](`第二次`) - -内核严格串行:求值不会交错,超时会杀掉进程组。 - ---- - -显式状态桥。值以 JSON 拷贝跨越边界,永远不是共享对象引用。 - -**> 外联.会话设值 标识=`会话` 名称="threshold" 值=2.5** - -**阈值 = > 外联.会话取值 标识=`会话` 名称="threshold"** - -> 打印 内容=`阈值` - -**> 外联.会话关闭 标识=`会话`** - -没有隐式镜像:没有 push / pull 的变量,另一边看不到。 - ---- - -并行扇出。每个输入都有独立进程;失败互相隔离,顺序保持不变。 - -`加一` = -```python -import json -import sys - -raw = sys.stdin.read() -value = json.loads(raw) if raw.strip() else 1 -print(json.dumps(value + 1)) -``` - -`数值` = - -| value | -|-------| -| 1 | -| 2 | -| 3 | -| 4 | - -**加一后 = > 外联.批量调用 代码=`加一` 输入表=`数值` 并发=4** - -> 打印 内容=`加一后` - ---- - -view 中的单元。命名内核和单元顺序都是普通绑定表,不是 fence 元数据或 YAML 配置。 - -```text -`分析内核` = - -| 名称 | 语言 | 命令 | 说明 | -|------|------|------|------| -| 分析 | python | | 共享分析 | -| 复核 | python | | 独立复核 | - -`分析单元` = - -| 单元 | 内核 | 说明 | -|------|------|------| -| 准备数据 | 分析 | 生成订单 | -| 计算指标 | 分析 | 区域与总额 | -| 独立复核 | 复核 | 读取 JSON 报告 | -``` - - -`marqdo view` 消费 foreign 拥有的 `会话` 句柄,渲染 Run All、Step、切换内核、journal、dirty reload 和状态面板。没有该句柄时,单元是无状态的一次性运行。没有单独的交互命令;`marqdo run` 仍把同一份文件当单个程序执行。 - ---- - -为什么它仍然可读。 - -| 层 | 读者看到什么 | -|---|---| -| Markdown | 标题、叙述、表格与围栏代码 | -| 程序 | 赋值、调用与返回值 | -| 知识 | frontmatter、链接、任务页与生成的 catalog 条目 | - -外联层没有给语言新增语法。围栏还是围栏,表还是表。 - -底层 API 与安全默认值见 [`../../lib/外联.mq.md`](../../lib/外联.mq.md) 与 [`../../doc/design/foreign-kernel.md`](../../doc/design/foreign-kernel.md)。 +没有单独的 notebook CLI,这个示例不依赖 stdin,也没有隐藏的语言切换。 diff --git a/src/view/output.rs b/src/view/output.rs index f5da4c3..998f52e 100644 --- a/src/view/output.rs +++ b/src/view/output.rs @@ -94,6 +94,7 @@ fn static_cell_outputs( parts.push(error); } } + let has_body = !parts.is_empty(); let mut meta = Vec::new(); if let Some(code) = record_field(&rec, "code").and_then(|v| match v { Value::Int(n) => Some(n), @@ -114,7 +115,7 @@ fn static_cell_outputs( if !meta.is_empty() { parts.push(format!("— {}", meta.join(" · "))); } - let text = if parts.is_empty() { + let text = if !has_body { "(no output)".to_string() } else { parts.join("\n\n")