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.
This commit is contained in:
cflmy committed 2026-10-18 13:23:03 +08:00
1 parent e4387259ba
commit 05d48f68a4
3 files changed
+148 -273

No files matched your search

+77 -140
View File
@@ -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.
+69 -132
View File
@@ -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,也没有隐藏的语言切换。
+2 -1
View File
@@ -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")