Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
dff0b700ae | ||
|
|
4da07c1b26 | ||
|
|
78922102e4 | ||
|
|
064bae2c65 | ||
|
|
92b91ffc81 | ||
|
|
ab6648ae0e | ||
|
|
5acf026e0c | ||
|
|
8dcd69412f | ||
|
|
2a13e52981 | ||
|
|
9b269f6447 | ||
|
|
15362cb048 | ||
|
|
05d48f68a4 | ||
|
|
e4387259ba | ||
|
|
518f8e386b | ||
|
|
9da12c9093 | ||
|
|
e0d34669e0 | ||
|
|
0ba4d3d2d7 | ||
|
|
ad3ebf243a | ||
|
|
142d30ce08 | ||
|
|
4757b82edd | ||
|
|
bff2f53e52 | ||
|
|
fb28eee62f | ||
|
|
01468ad976 | ||
|
|
f3791d11b4 | ||
|
|
7fef690167 | ||
|
|
024cdee82a |
No files matched your search
@@ -210,7 +210,7 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
|
||||
- `invoke` returns a record (`ok`, `code`, `stdout`, `stderr`, `ms`, `timed_out`, `truncated`, `result`); pass `input` for JSON stdin and `output="json"` for a parsed result.
|
||||
- `call` is JSON-in / JSON-out; `call_many` fans out one program over a list with ordered results.
|
||||
- `session_open` starts a persistent Python/Node kernel; `session_eval` evaluates source; `session_set` / `session_get` bridge values explicitly as JSON. Close it with `session_close`.
|
||||
- A notebook is still a document: bind `内核表` and `会话表` as ordinary tables inside `# main`. A `view` session adds cell stepping, Run All, kernel switching, journal and reload. No new Markdown marker exists.
|
||||
- A view document opts into kernel state with `会话 = > foreign.session kernels=... cells=...`; the table names are free. `view` consumes only the `会话` handle and never scans source lines or reserved table names. Without `会话`, cells are stateless one-shot runs; no kernel is created. Clearing outputs calls `/api/session/clear` and keeps persistent kernel state. There is no separate notebook CLI mode or command, and no new Markdown marker exists.
|
||||
- The same source remains the authority; state crossing kernels is explicit, never implicitly mirrored.
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
@@ -126,6 +126,9 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v1.5.1**:view 静态/动态统一 + 外联值传递——共用执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin
|
||||
- **v1.5.1**: View static/live unified + foreign value passing — shared execution path, build-time run with stdout injection, `foreign.session` value passing, cell stdin
|
||||
- **v1.5.1 ext**:扩展包同步 1.5.1 / Ext pack 1.5.1
|
||||
- **v1.5.0**:外联 v2 + 文档原生 Notebook——invoke/JSON call/并行/持久 Python·Node/状态桥 · cell 单步 · 高对比 view
|
||||
- **v1.5.0**: Foreign v2 + document-native notebooks — invoke, JSON calls, fan-out, persistent Python/Node, state bridge, cell stepping, high-contrast view
|
||||
- **v1.5.0 ext**:扩展包同步 1.5.0 / Ext pack 1.5.0
|
||||
|
||||
+38
-1
@@ -8,6 +8,43 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## v1.5.1 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**view 静态/动态统一 + 外联值传递**:静态导出与 live view 共用同一套 `foreign_doc` 执行路径;构建时实际运行代码单元并注入 stdout;`foreign.session` 可把 Marqdo 值传入多内核会话;cell stdin 支持 live/static/持久内核三种模式。CLI · wasm · ext **1.5.1**。
|
||||
|
||||
```bash
|
||||
git checkout v1.5.1 && cargo build --release
|
||||
marqdo ext add web # CDN → 1.5.1
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——view 执行路径统一 + 外联值传递;不改 MQ 关键词 / 表几何。
|
||||
|
||||
### Added
|
||||
|
||||
- **外联值传递**:`foreign.session kernels= cells=` 可把 Marqdo 值传入多内核 view 会话;`view` 只消费 `会话` 绑定,不再识别 `内核表` / `会话表` 保留名。
|
||||
- **Cell stdin**:view 增加 `Cell stdin / input` 输入框;Run/Step/Run All 都会传给外联 cells;无状态 cell 使用 raw stdin,持久内核使用 `marqdo_input`;静态导出使用 frontmatter `stdin` 作为构建时输入。
|
||||
- **静态导出真实执行**:构建时实际执行代码单元并把 stdout/stderr 注入代码卡;静态示例通过代码 fallback 或 frontmatter `stdin` 提供输入。
|
||||
- **可运行外联写回示例**:新增 `examples/foreign-writeback/index.mq.md`,用 `foreign.run` + `writeback.record` 将结果写入 `.mq.md` 的 keyed 槽位。
|
||||
- **写回块分组与主题**:view 对写回块按目标分组并统一主题样式。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **code 卡控制恢复**:恢复每个代码卡的内核切换下拉与 Clean 按钮;Clean 清除单个 cell 输出/记录,不重启内核。
|
||||
- **导入函数返回锚定**:导入函数的返回值锚定在调用位置。
|
||||
- **静态导出自包含**:静态示例不再依赖空 stdin 或外部内核状态。
|
||||
- **Execution 输出清除**:view 清除 Execution 输出从 view 表面。
|
||||
- **文档表不再变 call chips**:view 不再把文档表转为 call chips。
|
||||
- **写回表标签**:写回表标签保持为行内代码。
|
||||
|
||||
### Changed
|
||||
|
||||
- **静态/动态统一执行路径**:static 与 live cells 使用同一 `foreign_doc` `run_all` 路径;移除 `In []` / `Out []` 与 Notebook 品牌。
|
||||
- **静态按钮行为**:静态页面执行按钮点击显示"静态页面无法真实执行",不伪造成功。
|
||||
- **低层会话评估可见**:文档展示低层 session evaluation 为代码围栏。
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.5.1**。
|
||||
|
||||
## v1.5.0 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
@@ -22,7 +59,7 @@ git checkout v1.5.0 && cargo build --release
|
||||
|
||||
### Added
|
||||
|
||||
- **用户静态站(外联 / OKF / EKC)**:新增中英双语 `features/19-foreign-notebook` 与 `features/20-okf-ekc`,重写 `stdlib/foreign`,首页加入「一份文件三个面」、外联 Python 运行、Notebook 表、OKF/EKC 与 preflight 说明。
|
||||
- **用户静态站(外联 / OKF / EKC)**:新增中英双语 `features/19-foreign-view-cells` 与 `features/20-okf-ekc`,重写 `stdlib/foreign`,首页加入「一份文件三个面」、外联 Python 运行、Notebook 表、OKF/EKC 与 preflight 说明。
|
||||
- **`lib/foreign` F0/F1**:`invoke` 结构化记录(`ok`/`code`/`stdout`/`stderr`/`ms`/`timed_out`/`truncated`/`result`);`run`/`run_lang` 新增 `env`/`cwd`/`timeout`/`args`/`max_output`;15 个语言预设;`probe`/`register`/`unset`/`load_config`;`.marqdo/foreign.toml`。
|
||||
- **`lib/foreign` F2**:JSON 进 / JSON 出 `call`;并行 `run_many` / `call_many`(有序、单项隔离、并发上限);`invoke` 的 `input` / `output` / `result` / `result_error`。
|
||||
- **`lib/foreign` F3/F3.5**:Python / Node 持久会话 `session_open` / `session_eval` / `session_close` / `session_list`;状态桥 `session_set` / `session_get` / `session_names`;会话超时即杀、崩溃隔离、drop 清理。
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "1.5.0"
|
||||
version = "1.5.1"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
|
||||
@@ -149,9 +149,10 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v1.5.0)
|
||||
## 现状(v1.5.1)
|
||||
|
||||
- **外联 v2 / 文档原生 Notebook(v1.5.0)**:结构化 invoke · JSON call/call_many · 并行扇出 · Python/Node 持久内核 · 显式状态桥 · cell 单步/Run All/内核切换 · 高对比浅深主题;扩展包同步 **1.5.0**
|
||||
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin · 扩展包同步 **1.5.1**
|
||||
- **外联 v2 / view 交互单元(v1.5.0)**:结构化 invoke · JSON call/call_many · 并行扇出 · Python/Node 持久内核 · 显式状态桥 · cell 单步/Run All/内核切换 · `foreign.session` 句柄 · 无 `会话` 时无状态 cells · 清除输出 API · 高对比浅深主题;扩展包同步 **1.5.0**
|
||||
- **裸自增升参(v1.4.6)**:首次粗体赋值左值即声明;`**n = n + 1**` 无反引号也升为必选形参。扩展包仍为 **1.4.5**
|
||||
- **Streamable HTTP MCP + web invoke 鉴权(v1.4.5)**:`agent_mcp_serve transport=http` · Bearer/`X-Api-Key` 注入 · `unauthorized`→401 · openai/agent `json.get` 硬化
|
||||
- **LLM 传输软失败 + `ext/ai` 表优先(v1.4.4)**:上游不可达 → `status=error`(不 abort);`agent`/`llm` 去 `json.set` 胶水 · [agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)
|
||||
@@ -185,7 +186,7 @@ marqdo catalog public -o .marqdo
|
||||
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
|
||||
|
||||
### 如何使用最新 Marqdo(v1.5.0)
|
||||
### 如何使用最新 Marqdo(v1.5.1)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -200,7 +201,7 @@ marqdo catalog public -o .marqdo
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v1.5.0 # 或留在 main
|
||||
git checkout v1.5.1 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -239,7 +240,7 @@ marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.5.0
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.5.1
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.5.0"
|
||||
version = "1.5.1"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
Vendored
+11
@@ -1,3 +1,14 @@
|
||||
marqdo (1.5.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.5.0: Foreign kernels v2 (structured invoke, JSON calls,
|
||||
parallel fan-out, persistent Python/Node kernels, explicit state
|
||||
bridge) and document-native notebooks in view; high-contrast
|
||||
light/dark view themes, resizable code/output panes, OKF/EKC and
|
||||
Python examples on the user site. Fixes branch-local variables
|
||||
leaking into required constructor parameters.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 03:30:00 +0800
|
||||
|
||||
marqdo (1.4.6-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.6: Promote a bare self-increment to a required parameter.
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
# 文档会话(Document Session)
|
||||
# 文档会话(View Cells)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **D1–D3 首版已实现;D4/D5 待做** |
|
||||
| 日期 | 2026-10-17 |
|
||||
| 层 | Runtime + Document(view 服务端 / notebook 交互) |
|
||||
| 层 | Runtime + Document(view 服务端 / 交互单元) |
|
||||
| 相关 | [notebook-syntax.md](notebook-syntax.md) · [foreign-kernel.md](foreign-kernel.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [view.md](view.md) · [view-debug.md](view-debug.md) · [stdlib-subtask.md](stdlib-subtask.md) |
|
||||
| 核心表面 Δ | 无(读取既有 AST 与表格) |
|
||||
|
||||
> 文档会话是 view 背后的“notebook 运行时”:它记住哪些 cell、在哪个内核、按什么顺序执行、状态是什么、结果是否过期。
|
||||
> 文档会话是 view 背后的交互单元运行时:它记住哪些 cell、在哪个内核、按什么顺序执行、状态是什么、结果是否过期。它不是第二个 CLI 模式——`marqdo view` 是唯一的交互面,`marqdo run` 是规范执行。
|
||||
|
||||
---
|
||||
|
||||
@@ -23,11 +23,12 @@
|
||||
|
||||
---
|
||||
|
||||
## 1.1 实施状态(2026-10-17)
|
||||
## 1.1 实施状态(2026-10-18)
|
||||
|
||||
| 能力 | 状态 | 位置 |
|
||||
|---|---|---|
|
||||
| `内核表` / `会话表` 解析(中英列名) | ✅ | `src/notebook/mod.rs` |
|
||||
| `foreign.session` 句柄(kernels/cells 表参数) | ✅ | `lib/foreign.mq.md` · `src/host/foreign_doc.rs` |
|
||||
| cell plan 求值 | ✅ 解释器求值 `会话` 绑定;不扫描源码行、不认保留表名 | `src/interp.rs` · `src/host/foreign_doc.rs` |
|
||||
| cell index(绑定名 / 行号 / source hash) | ✅ | 同上 |
|
||||
| 命名内核 + 默认内核 + 语言校验 | ✅ | 同上 |
|
||||
| 同内核共享 / 跨内核隔离 | ✅ | Node 金样例 + 单测 |
|
||||
@@ -39,8 +40,8 @@
|
||||
| view 工具栏 / 状态徽标 / 内核下拉 / 状态表单 | ✅ | `src/view/html.rs` |
|
||||
| `POST /api/session/*` | ✅(含 `reload`) | `src/view/notebook_api.rs` |
|
||||
| cell step | ✅ | 同上 |
|
||||
| Marqdo statement step | ✅(notebook 工具栏 Debug → 同一 view 服务的 `/debug`;`/api/debug/*`) | `src/debug` · `src/view/debug_api.rs` |
|
||||
| dirty/stale 自动检测 | 部分(reload → dirty;assign → dirty;stale 传播待做) | `src/notebook/mod.rs` |
|
||||
| Marqdo statement step | ✅(view 工具栏 Debug → 同一 view 服务的 `/debug`;`/api/debug/*`) | `src/debug` · `src/view/debug_api.rs` |
|
||||
| dirty/stale 自动检测 | 部分(reload → dirty;assign → dirty;stale 传播待做) | `src/host/foreign_doc.rs` |
|
||||
| writeback 集成 | 待做 | `writeback` |
|
||||
| replay / 持久化 | 待做 | — |
|
||||
| Python 会话 | ✅(本机无 python,CI/用户机条件测试) | `src/host/foreign_session.rs` |
|
||||
@@ -50,18 +51,18 @@
|
||||
|
||||
---
|
||||
|
||||
## 2. 两种执行模式
|
||||
## 2. 两个执行面(不是两个 CLI 模式)
|
||||
|
||||
### 2.1 Program mode(规范)
|
||||
### 2.1 Program execution(规范)
|
||||
|
||||
- 入口:`marqdo run doc.mq.md` / CI / `view` 的 `Run document`。
|
||||
- 执行:`# main` 程序语义;外联通过显式 `foreign.session_open/eval/call` 编排。
|
||||
- 状态:一次运行内有效;运行结束进程退出(除非显式持久内核)。
|
||||
- 结果:可复现;是文档的“真理”。
|
||||
|
||||
### 2.2 Notebook mode(交互)
|
||||
### 2.2 View cells(交互)
|
||||
|
||||
- 入口:`marqdo view doc.mq.md` → Session 面板。
|
||||
- 入口:`marqdo view doc.mq.md` → 文档单元(cell)控制。
|
||||
- 执行:按 `会话表`(或自动顺序)逐 cell 执行。
|
||||
- 状态:内核持久;可切换、重启、单步。
|
||||
- 结果:默认临时显示;可显式 writeback。
|
||||
@@ -72,7 +73,7 @@
|
||||
```text
|
||||
.mq.md
|
||||
/ \
|
||||
Program mode Notebook mode
|
||||
Program run View cells
|
||||
(canonical) (interactive)
|
||||
\ /
|
||||
Document Session
|
||||
@@ -83,8 +84,8 @@
|
||||
```
|
||||
|
||||
- 共享 cell index 与 kernel registry。
|
||||
- Program mode 可以不使用 notebook 表;Notebook mode 可以使用。
|
||||
- 冲突时以 Program mode 为准;Notebook mode 不改变文档语义。
|
||||
- `run` 不消费视图会话;`view` 只在文档绑定 `会话 = > foreign.session ...` 时提供持久 cell 控制;无 `会话` 时 cells 无状态一次性执行。
|
||||
- 冲突时以 `run` 的程序语义为准;view cells 不改变文档语义。
|
||||
|
||||
---
|
||||
|
||||
@@ -107,7 +108,7 @@ DocumentSession
|
||||
├── value_store: HashMap<String, Value> // Marqdo 侧会话值
|
||||
├── journal: Vec<ExecutionRecord>
|
||||
├── created_ms / last_active_ms
|
||||
└── mode: program | notebook
|
||||
└── surface: program | view
|
||||
```
|
||||
|
||||
### 3.1 Cell
|
||||
@@ -130,7 +131,7 @@ DocumentSession
|
||||
1. 读取/解析文档(现有 `parse_source` / `load_module`)。
|
||||
2. 遍历 AST,找 `Stmt::Assign { name, value: Expr::Code(c) }`。
|
||||
3. 记录 name、lang、source、span、source hash。
|
||||
4. 读取 `内核表` / `会话表` 绑定(见 [notebook-syntax.md](notebook-syntax.md))。
|
||||
4. 通过解释器求值 `会话` 绑定(`foreign.session` 返回的句柄,含简单依赖);不扫描源码行、不认保留表名(见 [notebook-syntax.md](notebook-syntax.md))。
|
||||
5. 解析 kernel 声明与 cell 归属;校验;生成诊断。
|
||||
6. 生成执行顺序:
|
||||
- 有会话表 → 行顺序;
|
||||
@@ -233,7 +234,7 @@ resolve cell -> resolve kernel
|
||||
| **Marqdo statement step** | 执行下一条 Marqdo 语句;遇到 `foreign.session_eval` 时整个外联调用原子完成 |
|
||||
| **Foreign line step** | 不做;未来 DAP |
|
||||
|
||||
- Cell step 是 Notebook mode 的主单步。
|
||||
- Cell step 是 view cells 的主单步。
|
||||
- Statement step 复用 `DebugController`;需要把 debug session 与 DocumentSession 关联。
|
||||
- 两者可以互相切换:cell step 到某个 Marqdo cell 后可 statement step;语句执行完回到 cell 边界。
|
||||
|
||||
@@ -333,7 +334,7 @@ resolve cell -> resolve kernel
|
||||
|
||||
### 7.1 默认
|
||||
|
||||
- Notebook mode 输出只在 view 中显示;不写 `.mq.md`。
|
||||
- View cells 输出只在 view 中显示;不写 `.mq.md`。
|
||||
- 关闭/刷新后可通过 journal 恢复最近结果(若 session 持久化)。
|
||||
- 不写 execution_count 到文档。
|
||||
|
||||
@@ -463,7 +464,7 @@ Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
|
||||
### 12.1 服务端
|
||||
|
||||
- cell index:绑定名/行号/lang/source hash;未绑定围栏排除。
|
||||
- 表解析:内核表/会话表/自动模式/重复/未知/语言不匹配。
|
||||
- 会话解析:foreign.session 句柄/自动模式/重复/未知/语言不匹配。
|
||||
- 会话:open/close/reload;kernel 启动/重启/中断。
|
||||
- cell run:状态机 never→running→clean/error;dirty/stale。
|
||||
- step:cell step 顺序;statement step 与 debug 联动。
|
||||
@@ -474,7 +475,7 @@ Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
|
||||
|
||||
### 12.2 金样例
|
||||
|
||||
- `tests/notebook/kernels.mq.md`:内核表/会话表。
|
||||
- `tests/notebook/kernels.mq.md`:foreign.session 句柄。
|
||||
- `tests/notebook/shared-state.mq.md`:两个 Python cell 共享 `x`。
|
||||
- `tests/notebook/step.mq.md`:cell step 顺序。
|
||||
- `tests/notebook/state-bridge.mq.md`:Marqdo ↔ Python 推拉。
|
||||
@@ -495,7 +496,7 @@ Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
|
||||
| 源 | `.ipynb` | `.mq.md` |
|
||||
| 执行顺序 | 隐藏的 `In[n]` | 会话表 / 文档顺序 / journal |
|
||||
| 状态 | 隐藏 kernel | kernel + value store + 状态面板 |
|
||||
| 多语言 | 一 notebook 一 kernel | 命名内核 + 每 cell 归属 |
|
||||
| 多语言 | 一文档一 kernel | 命名内核 + 每 cell 归属 |
|
||||
| 单步 | cell | cell + statement |
|
||||
| 复现 | 手动 | Restart & Run All + journal + replay |
|
||||
| Git | 输出/计数噪声 | 源码干净;输出显式 |
|
||||
@@ -509,7 +510,7 @@ Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
|
||||
| 阶段 | 内容 |
|
||||
|---|---|
|
||||
| D0 | 设计/语法/决策文档(本文件) |
|
||||
| D1 | `src/notebook/`:cell index、表解析、session 结构、诊断 |
|
||||
| D1 | `src/host/foreign_doc.rs`:cell index、foreign.session 句柄、session 结构、诊断 |
|
||||
| D2 | 服务端 API:open/close/cell run/step/run_all/restart/interrupt |
|
||||
| D3 | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal |
|
||||
| D4 | statement step 接入;dirty/stale;writeback |
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# 文档原生 Notebook 语法
|
||||
# 文档原生 view cells 语法
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -110,7 +110,7 @@ Marqdo 的选择:
|
||||
````markdown
|
||||
# main
|
||||
|
||||
这份文档演示一个最小 notebook:两个 Python 单元共享 `分析` 内核,
|
||||
这份文档演示一个最小 view cells 文档:两个 Python 单元共享 `分析` 内核,
|
||||
一个绘图单元在隔离的 `绘图` 内核里运行。
|
||||
|
||||
`内核表` =
|
||||
@@ -211,7 +211,7 @@ print(x + 1)
|
||||
|
||||
## 5. 可读性规则(语法评审标准)
|
||||
|
||||
新增/修改任何 notebook 语法,必须满足:
|
||||
新增/修改任何 cell 表约定,必须满足:
|
||||
|
||||
1. **先读人话**:去掉执行语义后,表格仍像目录/清单。
|
||||
2. **不使用属性串**:不写 `kernel=…`、`class=…`、JSON/YAML 元数据。
|
||||
@@ -231,7 +231,7 @@ print(x + 1)
|
||||
| 情况 | 诊断(中文示例) | 修复建议 |
|
||||
|---|---|---|
|
||||
| 内核名重复 | `内核表: 内核名「分析」重复(第 12、20 行)` | 改名或合并 |
|
||||
| 会话引用未知内核 | `会话表: 单元「汇总」引用了未声明的内核「分析」` | 在 `内核表` 声明,或改用语言 id |
|
||||
| 会话引用未知内核 | `foreign.session: cell「汇总」引用了未声明的内核「分析」` | 在 kernels 表声明,或改用语言 id |
|
||||
| 会话引用未知单元 | `会话表: 找不到名为「清洗」的代码单元` | 检查 `` `清洗` = `` 绑定 |
|
||||
| 单元重复 | `会话表: 单元「汇总」重复出现` | 每个单元只列一次 |
|
||||
| 语言不匹配 | `会话表: 单元「前端」(node) 不能使用 python 内核「分析」` | 换内核或换语言 |
|
||||
@@ -243,15 +243,15 @@ print(x + 1)
|
||||
|
||||
---
|
||||
|
||||
## 7. 与 Program mode 的关系
|
||||
## 7. 与 program execution 的关系
|
||||
|
||||
- `内核表` / `会话表` 是**声明**,不是执行指令。
|
||||
- `内核表` / `会话表` 只是传递给 `foreign.session` 的普通表变量,不是保留名。
|
||||
- `marqdo run` 仍然执行 `# main` 的程序语义;这两个表会被求值为普通数据。
|
||||
- Program mode 的外联编排用显式 API(`foreign.session_open` / `session_eval` / `call`);表只服务 view 的 notebook 会话与一键 Run All。
|
||||
- 两种模式可以并存:
|
||||
- `run` 的外联编排用显式 API(`foreign.session_open` / `session_eval` / `call`);`foreign.session` 句柄服务 `view` 的 cells 与一键 Run All。
|
||||
- 两者可以并存:
|
||||
- 文档用表描述“交互时怎么跑”;
|
||||
- `# main` 用显式调用描述“CI 时怎么跑”。
|
||||
- 如果两者冲突,以 Program mode 的程序语义为准;Notebook mode 的表只影响 view。
|
||||
- 如果两者冲突,以 `run` 的程序语义为准;cell 表只影响 `view`。
|
||||
|
||||
这样避免把“执行计划”变成第二套程序语义。
|
||||
|
||||
@@ -295,7 +295,7 @@ v2 **不**为状态交换新增表格/注释。原因:
|
||||
|
||||
| 逻辑 | 位置 |
|
||||
|---|---|
|
||||
| 识别 `内核表` / `会话表` 绑定 | `src/notebook/syntax.rs`(新) |
|
||||
| 识别 `会话` 的 foreign.session 句柄 | `src/host/foreign_doc.rs` |
|
||||
| 读取绑定值 | AST `Stmt::Assign` + `Expr::Table` / `Expr::List`;或最近一次 run 的 bindings |
|
||||
| 校验名称/语言/重复/未入会话 | 同上;错误进入现有 Diagnostic |
|
||||
| cell index(绑定名/行号/语言/source hash) | 解析后的 `Module` 遍历 |
|
||||
|
||||
@@ -54,8 +54,8 @@
|
||||
### 结论 C:Hybrid 执行模型
|
||||
|
||||
- **Program mode(规范模式)**:`marqdo run` / CI / 可复现执行。文档是程序;外联通过显式 `foreign.session_*` / `call` 编排;结果可重复。
|
||||
- **Notebook mode(交互模式)**:`view` 中按 cell 执行、单步、切换内核、查看状态。适合探索,不默认写入文档。
|
||||
- 两者共享同一个内核运行时与同一套 cell 索引;Notebook mode 是 Program mode 的**交互镜头**,不是替代品。
|
||||
- **View cells(交互面)**:`view` 中按 cell 执行、单步、切换内核、查看状态。适合探索,不默认写入文档;不是第二个 CLI 模式。
|
||||
- 两者共享同一个内核运行时与同一套 cell 索引;view cells 是 program execution 的**交互镜头**,不是替代品。
|
||||
|
||||
理由:如果让 cell 执行取代文档程序语义,Marqdo 就退化成 Jupyter;如果只有 Program mode,就失去 Jupyter 的即时反馈。Hybrid 同时保留两者。
|
||||
|
||||
@@ -99,7 +99,7 @@
|
||||
|
||||
### 结论 H:输出默认临时,writeback 显式;状态不写进 `.mq.md`
|
||||
|
||||
- Notebook mode 的输出默认只在 view 中显示,不修改文档。
|
||||
- View cells 的输出默认只在 view 中显示,不修改文档。
|
||||
- 需要持久化时显式 writeback(沿用 `<!-- marqdo-out … -->`),可 Git 跟踪、可忽略。
|
||||
- 执行日志放 `.marqdo/sessions/…`(默认 git 忽略)。
|
||||
- 不把 execution_count / kernel 状态 / base64 输出写进 `.mq.md`。
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
1.5.0
|
||||
1.5.1
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: lib/foreign
|
||||
description: Run bound code fences and inline sources via local interpreters
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
Run bound code fences and inline sources via local interpreters.
|
||||
@@ -148,6 +149,23 @@ in input order. Raises with the failing index after all workers finish.
|
||||
|
||||
*> host_foreign_call_many inputs=`inputs` code=`code` lang=`lang` source=`source` cmd=`cmd` env=`env` cwd=`cwd` timeout=`timeout` args=`args` max_output=`max_output` concurrency=`concurrency`*
|
||||
|
||||
## session
|
||||
+ `kernels`=None
|
||||
+ `cells`=None
|
||||
+ `values`=None
|
||||
|
||||
Declare a document view session. `kernels` and `cells` are ordinary tables:
|
||||
kernels are `|名称|语言|命令|` (ZH or EN), cells are `|单元|内核|`.
|
||||
Returns a foreign session handle consumed by `view`; without this handle the
|
||||
view has no persistent kernel state.
|
||||
|
||||
**p = > table.empty_map**
|
||||
**p = > table.put in=`p` at="kind" value="foreign-session"**
|
||||
**p = > table.put in=`p` at="kernels" value=`kernels`**
|
||||
**p = > table.put in=`p` at="cells" value=`cells`**
|
||||
**p = > table.put in=`p` at="values" value=`values`**
|
||||
*p*
|
||||
|
||||
## session_open
|
||||
+ `lang`
|
||||
+ `cmd`=None
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: lib/外联
|
||||
description: 通过本机解释器运行绑定的代码围栏与内联源码
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
通过本机解释器运行绑定的代码围栏与内联源码。
|
||||
@@ -146,6 +147,21 @@ JSON 进 / JSON 出:把 `输入` 编码到 stdin,解析 stdout JSON 返回
|
||||
|
||||
*> host_foreign_call_many inputs=`输入表` code=`代码` lang=`语言` source=`源码` cmd=`命令` env=`环境` cwd=`工作目录` timeout=`超时` args=`参数` max_output=`最大输出` concurrency=`并发`*
|
||||
|
||||
## 会话
|
||||
+ `内核表`=None
|
||||
+ `单元表`=None
|
||||
+ `值表`=None
|
||||
|
||||
声明文档视图会话。内核表和单元表都是普通表格;返回一个 foreign 会话句柄,
|
||||
供 view 消费。没有这个句柄时,view 的 cells 是无状态的。
|
||||
|
||||
**p = > table.empty_map**
|
||||
**p = > table.put in=`p` at="kind" value="foreign-session"**
|
||||
**p = > table.put in=`p` at="kernels" value=`内核表`**
|
||||
**p = > table.put in=`p` at="cells" value=`单元表`**
|
||||
**p = > table.put in=`p` at="values" value=`值表`**
|
||||
*p*
|
||||
|
||||
## 会话开启
|
||||
+ `语言`
|
||||
+ `命令`=None
|
||||
|
||||
@@ -57,28 +57,30 @@ Foreign v2 is a good example. Probe Python, then run the bound fence:
|
||||
2. *
|
||||
> print text="(python3 not found — install Python to run this cell)"
|
||||
|
||||
The same module also supports JSON calls, parallel fan-out, persistent kernels and an explicit state bridge. See [stdlib/foreign.mq.md](stdlib/foreign.mq.md) and the full Python walkthrough in [features/19-foreign-notebook.mq.md](features/19-foreign-notebook.mq.md).
|
||||
The same module also supports JSON calls, parallel fan-out, persistent kernels and an explicit state bridge. See [stdlib/foreign.mq.md](stdlib/foreign.mq.md) and the full Python walkthrough in [features/19-foreign-view-cells.mq.md](features/19-foreign-view-cells.mq.md).
|
||||
|
||||
A notebook is still a document. Named kernels and a cell order are ordinary bound tables:
|
||||
A view document is still a document. Named kernels and a cell order are ordinary bound tables:
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 说明 |
|
||||
|------|------|------|
|
||||
| 分析 | python | shared state |
|
||||
| 复核 | python | isolated state |
|
||||
|
||||
`会话表` =
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | write |
|
||||
| 计算指标 | 分析 | read |
|
||||
| 独立复核 | 复核 | validate |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
```
|
||||
|
||||
Live view turns that into Run All, Step, per-cell kernels, a journal and a state panel. Program mode still runs the file as one program.
|
||||
`marqdo view` consumes the foreign-owned `会话` handle and turns it into Run All, Step, per-cell kernels, a journal and a state panel. Without `会话`, cells are stateless one-shot runs. There is no separate interactive mode or command; `marqdo run` still executes the file as one program.
|
||||
|
||||
Documentation becomes knowledge when it can be discovered, verified and reused. OKF supplies the portable Markdown + YAML shape; EKC projects the repository into catalog layers L0–L4, a graph and an engineering preflight. The source `.mq.md` remains the only authority; generated artifacts are marked and rebuildable.
|
||||
|
||||
|
||||
+7
-5
@@ -57,28 +57,30 @@ print("hello-from-python")
|
||||
2. *
|
||||
> 打印 内容="(未找到 python3 — 安装 Python 后可运行此单元)"
|
||||
|
||||
同一个模块还支持 JSON 调用、并行扇出、持久内核与显式状态桥。见 [stdlib/外联.mq.md](stdlib/外联.mq.md) 与完整 Python 示例 [features/19-外联Notebook.mq.md](features/19-外联Notebook.mq.md)。
|
||||
同一个模块还支持 JSON 调用、并行扇出、持久内核与显式状态桥。见 [stdlib/外联.mq.md](stdlib/外联.mq.md) 与完整 Python 示例 [features/19-外联视图单元.mq.md](features/19-外联视图单元.mq.md)。
|
||||
|
||||
Notebook 仍然是一篇文档。命名内核与单元顺序就是普通绑定表:
|
||||
view 仍然是一篇文档。命名内核与单元顺序就是普通绑定表:
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 说明 |
|
||||
|------|------|------|
|
||||
| 分析 | python | 共享状态 |
|
||||
| 复核 | python | 隔离状态 |
|
||||
|
||||
`会话表` =
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | 写入 |
|
||||
| 计算指标 | 分析 | 读取 |
|
||||
| 独立复核 | 复核 | 校验 |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
```
|
||||
|
||||
live view 会把它变成 Run All、Step、每单元内核、journal 与状态面板;Program 模式仍然把文件当单个程序运行。
|
||||
`marqdo view` 消费 foreign 拥有的 `会话` 句柄,变成 Run All、Step、每单元内核、journal 与状态面板。没有 `会话` 时,单元是无状态的一次性运行。没有单独的交互模式或命令;`marqdo run` 仍然把文件当单个程序运行。
|
||||
|
||||
文档能被发现、验证和复用时,才成为知识。OKF 提供可移植的 Markdown + YAML 形态;EKC 把仓库投影成 catalog L0–L4、图与工程 preflight。源 `.mq.md` 始终是唯一权威,生成物有标记、可重建。
|
||||
|
||||
|
||||
+2
-1
@@ -11,8 +11,9 @@
|
||||
| [`keywords/`](keywords/) | 关键字与 L0 内置 |
|
||||
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件/**自写回**/**子任务**;v0.1.2+ 内置于 CLI) |
|
||||
| [`features/`](features/) | 特性迭代(含对象、官方 `ext/`) |
|
||||
| [`features/19-foreign-notebook.mq.md`](features/19-foreign-notebook.mq.md) / [`19-外联Notebook.mq.md`](features/19-外联Notebook.mq.md) | 外联 v2 完整 Python 示例:probe / JSON call / 并行 / 持久内核 / 状态桥 / notebook |
|
||||
| [`features/19-foreign-view-cells.mq.md`](features/19-foreign-view-cells.mq.md) / [`19-外联视图单元.mq.md`](features/19-外联视图单元.mq.md) | 外联 v2 完整 Python 示例:probe / JSON call / 并行 / 持久内核 / 状态桥 / view 单元 |
|
||||
| [`features/20-okf-ekc.mq.md`](features/20-okf-ekc.mq.md) / [`20-OKF与EKC.mq.md`](features/20-OKF与EKC.mq.md) | 代码即文档、文档即知识:OKF 形态与 EKC 工程知识编译器 |
|
||||
| [`features/21-persistence.mq.md`](features/21-persistence.mq.md) / [`21-持久化.mq.md`](features/21-持久化.mq.md) | 外联结果持久化:静态快照与 writeback |
|
||||
|
||||
官方扩展(非 stdlib):`ext/llm`、`ext/agent`、`ext/web`、`ext/quantum`、`ext/linalg` — 见 `features/05-*.mq.md`、`06-*.mq.md`、`07-linalg.mq.md` / `07-线性代数.mq.md` 与 `doc/design/ext-*.md`。
|
||||
|
||||
|
||||
@@ -1,183 +0,0 @@
|
||||
---
|
||||
title: Foreign kernels v2 — a Python analysis notebook
|
||||
description: A complete Python data walkthrough with probe, JSON calls, parallel fan-out, persistent state, an explicit bridge and document-native notebook cells
|
||||
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 data is intentionally small and deterministic, so every number below can be reproduced by running the page.
|
||||
|
||||
---
|
||||
|
||||
The input.
|
||||
|
||||
`orders` =
|
||||
|
||||
| @ | region | amount |
|
||||
|---|--------|--------|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
---
|
||||
|
||||
Probe Python before using it.
|
||||
|
||||
**python = > foreign.probe lang="python"**
|
||||
|
||||
> print text=[ok](`python`)
|
||||
> print text=[version](`python`)
|
||||
|
||||
The probe record also carries `cmd`, `path` and `error`, so a site can explain a missing interpreter instead of producing a blank cell.
|
||||
|
||||
---
|
||||
|
||||
A JSON call. Python reads the table as JSON, groups it, and writes one JSON result.
|
||||
|
||||
`analyze` =
|
||||
```python
|
||||
import json
|
||||
import statistics
|
||||
import sys
|
||||
|
||||
rows = json.load(sys.stdin)
|
||||
by_region = {}
|
||||
for row in rows:
|
||||
by_region.setdefault(row["region"], []).append(float(row["amount"]))
|
||||
|
||||
summary = []
|
||||
for region, values in sorted(by_region.items()):
|
||||
mean = statistics.mean(values)
|
||||
sd = statistics.pstdev(values) or 1.0
|
||||
summary.append({
|
||||
"region": region,
|
||||
"orders": len(values),
|
||||
"total": round(sum(values), 2),
|
||||
"mean": round(mean, 2),
|
||||
"z_span": round((max(values) - mean) / sd, 3),
|
||||
})
|
||||
|
||||
print(json.dumps({
|
||||
"regions": summary,
|
||||
"total": round(sum(float(row["amount"]) for row in rows), 2),
|
||||
"count": len(rows),
|
||||
}, ensure_ascii=False))
|
||||
```
|
||||
|
||||
**result = > foreign.call code=`analyze` input=`orders`**
|
||||
|
||||
> print text=[count](`result`)
|
||||
> print text=[total](`result`)
|
||||
> print text=[region]([1]([regions](`result`)))
|
||||
> print text=[mean]([1]([regions](`result`)))
|
||||
|
||||
A call is JSON-in / JSON-out: the table is encoded on stdin, and the final stdout value is parsed into Marqdo values.
|
||||
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
value = json.load(sys.stdin)
|
||||
print(json.dumps(value + 1))
|
||||
```
|
||||
|
||||
`numbers` =
|
||||
|
||||
| value |
|
||||
|-------|
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
|
||||
**bumped = > foreign.call_many code=`increment` inputs=`numbers` concurrency=4**
|
||||
|
||||
> print text=`bumped`
|
||||
|
||||
---
|
||||
|
||||
A document-native notebook. Named kernels and a session table are ordinary bound data tables, not fence metadata or YAML config.
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | shared analysis |
|
||||
| 复核 | python | | isolated review |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | generate orders |
|
||||
| 计算指标 | 分析 | regions and totals |
|
||||
| 独立复核 | 复核 | read the JSON report |
|
||||
```
|
||||
|
||||
Live `view` renders these as cells with Run All, Step, per-cell kernel switching, a journal, dirty reload and a state panel. The same file still runs as a single 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).
|
||||
@@ -0,0 +1,152 @@
|
||||
---
|
||||
title: Foreign kernels v2 — Python analysis in view
|
||||
description: Kernel state, Marqdo-to-kernel values and view cells — without a stdin-only demo
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
Probe the interpreter first. The result is ordinary Marqdo data.
|
||||
|
||||
**python = > foreign.probe lang="python"**
|
||||
|
||||
> 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 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
**内核会话 = > foreign.session_open lang="python"**
|
||||
|
||||
**> foreign.session_set id=`内核会话` name="orders" value=`订单`**
|
||||
|
||||
`total_code` =
|
||||
```python
|
||||
round(sum(float(row["金额"]) for row in orders), 2)
|
||||
```
|
||||
|
||||
**total = > foreign.session_eval id=`内核会话` code=`total_code`**
|
||||
|
||||
> print text=[result](`total`)
|
||||
|
||||
The low-level kernel session is managed entirely by `foreign`; the table crossed the boundary as an explicit JSON copy.
|
||||
|
||||
---
|
||||
|
||||
Kernel state persists.
|
||||
|
||||
Two evaluations share the same kernel. The second sees the first variable.
|
||||
|
||||
`set_values_code` =
|
||||
```python
|
||||
values = [3, 4, 5]
|
||||
```
|
||||
|
||||
**> foreign.session_eval id=`内核会话` code=`set_values_code`**
|
||||
|
||||
`square_sum_code` =
|
||||
```python
|
||||
sum(value * value for value in values)
|
||||
```
|
||||
|
||||
**square_sum = > foreign.session_eval id=`内核会话` code=`square_sum_code`**
|
||||
|
||||
> 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 |
|
||||
| 2 | 复核 | python |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| @ | 单元 | 内核 |
|
||||
|---|------|------|
|
||||
| 1 | 计算 | 分析 |
|
||||
| 2 | 复核 | 复核 |
|
||||
|
||||
`初始值` =
|
||||
|
||||
| 内核 | 名称 | 值 |
|
||||
|------|------|----|
|
||||
| 分析 | orders | `订单` |
|
||||
| 复核 | orders | `订单` |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元` values=`初始值`
|
||||
|
||||
`计算` =
|
||||
```python
|
||||
import json
|
||||
import statistics
|
||||
|
||||
by_region = {}
|
||||
for row in orders:
|
||||
by_region.setdefault(row["区域"], []).append(float(row["金额"]))
|
||||
|
||||
summary = []
|
||||
for region, values in sorted(by_region.items()):
|
||||
mean = statistics.mean(values)
|
||||
sd = statistics.pstdev(values) or 1.0
|
||||
summary.append({
|
||||
"region": region,
|
||||
"orders": len(values),
|
||||
"total": round(sum(values), 2),
|
||||
"mean": round(mean, 2),
|
||||
"z_span": round((max(values) - mean) / sd, 3),
|
||||
})
|
||||
|
||||
print(json.dumps({
|
||||
"regions": summary,
|
||||
"total": round(sum(float(row["金额"]) for row in orders), 2),
|
||||
"count": len(orders),
|
||||
}, ensure_ascii=False))
|
||||
```
|
||||
|
||||
`复核` =
|
||||
```python
|
||||
import json
|
||||
|
||||
print(json.dumps({
|
||||
"kernel": "复核",
|
||||
"count": len(orders),
|
||||
"total": round(sum(float(row["金额"]) for row in orders), 2),
|
||||
}, ensure_ascii=False))
|
||||
```
|
||||
|
||||
`查看` consumes the `会话` handle. Run All runs `计算` in the `分析` kernel and `复核` in the `复核` kernel; the static export runs the same cells and embeds their real outputs.
|
||||
|
||||
The important language point:
|
||||
|
||||
The `初始值` table passes the same Marqdo `订单` value into both kernels. Kernel state lives in `foreign`. View only renders the handle and its cells. `run` still executes the same document as a program.
|
||||
|
||||
There is no separate notebook CLI, no stdin requirement in this example, and no hidden language switch.
|
||||
@@ -1,183 +0,0 @@
|
||||
---
|
||||
title: 外联内核 v2 — Python 分析 Notebook
|
||||
description: 从 probe、JSON 调用、并行扇出、持久状态到显式桥与文档原生 notebook 单元的完整 Python 示例
|
||||
导入 外联:lib/外联.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这一页既是可读文档,也是可运行程序。它用同一份文件展示 v2 的外联内核能力:语言探测、结构化记录、JSON 进出、并行扇出、持久 Python 内核,以及显式状态桥。
|
||||
|
||||
数据故意保持小而确定,因此下面每个数字都可以通过运行本页复现。
|
||||
|
||||
---
|
||||
|
||||
输入数据。
|
||||
|
||||
`订单` =
|
||||
|
||||
| @ | 区域 | 金额 |
|
||||
|---|------|------|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
---
|
||||
|
||||
先探测 Python。
|
||||
|
||||
**python = > 外联.探测 语言="python"**
|
||||
|
||||
> 打印 内容=[ok](`python`)
|
||||
> 打印 内容=[version](`python`)
|
||||
|
||||
探测记录还带 `cmd`、`path` 与 `error`,所以站点可以解释“解释器缺失”,而不是显示一个空白单元。
|
||||
|
||||
---
|
||||
|
||||
JSON 调用。Python 把表读成 JSON,按区域聚合,再写出一个 JSON 结果。
|
||||
|
||||
`分析` =
|
||||
```python
|
||||
import json
|
||||
import statistics
|
||||
import sys
|
||||
|
||||
rows = json.load(sys.stdin)
|
||||
by_region = {}
|
||||
for row in rows:
|
||||
by_region.setdefault(row["区域"], []).append(float(row["金额"]))
|
||||
|
||||
summary = []
|
||||
for region, values in sorted(by_region.items()):
|
||||
mean = statistics.mean(values)
|
||||
sd = statistics.pstdev(values) or 1.0
|
||||
summary.append({
|
||||
"region": region,
|
||||
"orders": len(values),
|
||||
"total": round(sum(values), 2),
|
||||
"mean": round(mean, 2),
|
||||
"z_span": round((max(values) - mean) / sd, 3),
|
||||
})
|
||||
|
||||
print(json.dumps({
|
||||
"regions": summary,
|
||||
"total": round(sum(float(row["金额"]) for row in rows), 2),
|
||||
"count": len(rows),
|
||||
}, ensure_ascii=False))
|
||||
```
|
||||
|
||||
**结果 = > 外联.调用 代码=`分析` 输入=`订单`**
|
||||
|
||||
> 打印 内容=[count](`结果`)
|
||||
> 打印 内容=[total](`结果`)
|
||||
> 打印 内容=[region]([1]([regions](`结果`)))
|
||||
> 打印 内容=[mean]([1]([regions](`结果`)))
|
||||
|
||||
调用是 JSON 进 / JSON 出:表编码到 stdin,stdout 的最后一个值再解析成 Marqdo 值。
|
||||
|
||||
---
|
||||
|
||||
同样的工作也可以保留成结构化记录。`执行` 即使进程失败也保留 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
|
||||
|
||||
value = json.load(sys.stdin)
|
||||
print(json.dumps(value + 1))
|
||||
```
|
||||
|
||||
`数值` =
|
||||
|
||||
| value |
|
||||
|-------|
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
|
||||
**加一后 = > 外联.批量调用 代码=`加一` 输入表=`数值` 并发=4**
|
||||
|
||||
> 打印 内容=`加一后`
|
||||
|
||||
---
|
||||
|
||||
文档原生 Notebook。命名内核和会话表都是普通绑定数据表,不是 fence 元数据或 YAML 配置。
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | 共享分析 |
|
||||
| 复核 | python | | 独立复核 |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | 生成订单 |
|
||||
| 计算指标 | 分析 | 区域与总额 |
|
||||
| 独立复核 | 复核 | 读取 JSON 报告 |
|
||||
```
|
||||
|
||||
live `view` 会把这些渲染成带 Run All、Step、切换内核、journal、dirty reload 和状态面板的单元。同一份文件仍可作为单个程序运行。
|
||||
|
||||
---
|
||||
|
||||
为什么它仍然可读。
|
||||
|
||||
| 层 | 读者看到什么 |
|
||||
|---|---|
|
||||
| Markdown | 标题、叙述、表格与围栏代码 |
|
||||
| 程序 | 赋值、调用与返回值 |
|
||||
| 知识 | frontmatter、链接、任务页与生成的 catalog 条目 |
|
||||
|
||||
外联层没有给语言新增语法。围栏还是围栏,表还是表。
|
||||
|
||||
底层 API 与安全默认值见 [`../../lib/外联.mq.md`](../../lib/外联.mq.md) 与 [`../../doc/design/foreign-kernel.md`](../../doc/design/foreign-kernel.md)。
|
||||
@@ -0,0 +1,152 @@
|
||||
---
|
||||
title: 外联内核 v2 — Python 分析(view 单元)
|
||||
description: 内核态、Marqdo 值传入与 view 单元 —— 不依赖 stdin 的完整示例
|
||||
导入 外联:lib/外联.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这一页把外联运行时当作语言能力来展示:持久内核、从 Marqdo 值显式传入状态,以及共享内核状态的 view 单元。读者不需要向 stdin 输入 JSON。
|
||||
|
||||
---
|
||||
|
||||
先探测解释器。结果仍然是普通 Marqdo 数据。
|
||||
|
||||
**python = > 外联.探测 语言="python"**
|
||||
|
||||
> 打印 内容=[ok](`python`)
|
||||
> 打印 内容=[version](`python`)
|
||||
|
||||
---
|
||||
|
||||
Marqdo 值进入内核。
|
||||
|
||||
`订单` 表是普通 Marqdo 值。`外联.会话设值` 把它作为 JSON 复制进 Python 内核;没有 shell,也没有 stdin。
|
||||
|
||||
`订单` =
|
||||
|
||||
| @ | 区域 | 金额 |
|
||||
|---|------|------|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
**内核会话 = > 外联.会话开启 语言="python"**
|
||||
|
||||
**> 外联.会话设值 标识=`内核会话` 名称="orders" 值=`订单`**
|
||||
|
||||
`合计代码` =
|
||||
```python
|
||||
round(sum(float(row["金额"]) for row in orders), 2)
|
||||
```
|
||||
|
||||
**合计 = > 外联.会话求值 标识=`内核会话` 代码=`合计代码`**
|
||||
|
||||
> 打印 内容=[result](`合计`)
|
||||
|
||||
低层内核会话完全由 `外联` 管理;表格以显式 JSON 拷贝跨过边界。
|
||||
|
||||
---
|
||||
|
||||
内核态是持续的。
|
||||
|
||||
两次求值共享同一个内核。第二次能看到第一次创建的变量。
|
||||
|
||||
`设值代码` =
|
||||
```python
|
||||
values = [3, 4, 5]
|
||||
```
|
||||
|
||||
**> 外联.会话求值 标识=`内核会话` 代码=`设值代码`**
|
||||
|
||||
`平方和代码` =
|
||||
```python
|
||||
sum(value * value for value in values)
|
||||
```
|
||||
|
||||
**平方和 = > 外联.会话求值 标识=`内核会话` 代码=`平方和代码`**
|
||||
|
||||
> 打印 内容=[result](`平方和`)
|
||||
|
||||
**> 外联.会话关闭 标识=`内核会话`**
|
||||
|
||||
这是内核态,不是一次性进程。它由 `外联` 创建、查询和关闭。
|
||||
|
||||
---
|
||||
|
||||
view 单元共享状态。
|
||||
|
||||
`外联.会话` 从普通表格声明一个 view 会话。表名完全自由;本页用 `分析内核` 和 `分析单元`。
|
||||
|
||||
`分析内核` =
|
||||
|
||||
| @ | 名称 | 语言 |
|
||||
|---|------|------|
|
||||
| 1 | 分析 | python |
|
||||
| 2 | 复核 | python |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| @ | 单元 | 内核 |
|
||||
|---|------|------|
|
||||
| 1 | 计算 | 分析 |
|
||||
| 2 | 复核 | 复核 |
|
||||
|
||||
`初始值` =
|
||||
|
||||
| 内核 | 名称 | 值 |
|
||||
|------|------|----|
|
||||
| 分析 | orders | `订单` |
|
||||
| 复核 | orders | `订单` |
|
||||
|
||||
`会话` = > 外联.会话 内核表=`分析内核` 单元表=`分析单元` 值表=`初始值`
|
||||
|
||||
`计算` =
|
||||
```python
|
||||
import json
|
||||
import statistics
|
||||
|
||||
by_region = {}
|
||||
for row in orders:
|
||||
by_region.setdefault(row["区域"], []).append(float(row["金额"]))
|
||||
|
||||
summary = []
|
||||
for region, values in sorted(by_region.items()):
|
||||
mean = statistics.mean(values)
|
||||
sd = statistics.pstdev(values) or 1.0
|
||||
summary.append({
|
||||
"region": region,
|
||||
"orders": len(values),
|
||||
"total": round(sum(values), 2),
|
||||
"mean": round(mean, 2),
|
||||
"z_span": round((max(values) - mean) / sd, 3),
|
||||
})
|
||||
|
||||
print(json.dumps({
|
||||
"regions": summary,
|
||||
"total": round(sum(float(row["金额"]) for row in orders), 2),
|
||||
"count": len(orders),
|
||||
}, ensure_ascii=False))
|
||||
```
|
||||
|
||||
`复核` =
|
||||
```python
|
||||
import json
|
||||
|
||||
print(json.dumps({
|
||||
"kernel": "复核",
|
||||
"count": len(orders),
|
||||
"total": round(sum(float(row["金额"]) for row in orders), 2),
|
||||
}, ensure_ascii=False))
|
||||
```
|
||||
|
||||
`查看` 消费 `会话` 句柄。Run All 在 `分析` 内核执行 `计算`,在 `复核` 内核执行 `复核`;静态导出走同一批单元,并把真实输出嵌入页面。
|
||||
|
||||
语言上的重点:
|
||||
|
||||
`初始值` 表把同一个 Marqdo `订单` 值传给两个内核。内核态归 `外联` 管理。view 只渲染句柄和单元。`run` 仍然把同一份文档当程序执行。
|
||||
|
||||
没有单独的 notebook CLI,这个示例不依赖 stdin,也没有隐藏的语言切换。
|
||||
@@ -21,13 +21,13 @@ OKF(Open Knowledge Format)用 Markdown + YAML frontmatter 表示知识:一
|
||||
type: Capability
|
||||
title: 持久外联内核
|
||||
description: 在命名内核中运行 Python 或 Node 并保留状态
|
||||
resource: public/features/19-外联Notebook.mq.md
|
||||
resource: public/features/19-外联视图单元.mq.md
|
||||
status: stable
|
||||
verified:
|
||||
by: marqdo-knowledge/verify
|
||||
tags:
|
||||
- foreign
|
||||
- notebook
|
||||
- view-cells
|
||||
```
|
||||
|
||||
同一页可以在编辑器里读、从 catalog 链接、被 Agent 查询,也可以直接运行。未知字段保留;未知类型降级为可读正文。概念页不是源文件的复制品。
|
||||
@@ -104,7 +104,7 @@ marqdo find "外联 会话"
|
||||
marqdo reuse "实现 JSON 并行扇出"
|
||||
|
||||
# 看一次修改会影响什么
|
||||
marqdo impact public/features/19-外联Notebook.mq.md
|
||||
marqdo impact public/features/19-外联视图单元.mq.md
|
||||
|
||||
# 校验知识投影
|
||||
marqdo knowledge verify
|
||||
@@ -132,4 +132,4 @@ Catalog CLI:[Catalog CLI](../../doc/design/catalog-cli.md)
|
||||
|
||||
OKF 与 Marqdo 调研:[OKF 与 Marqdo 调研](../../doc/research/okf-and-marqdo.md)
|
||||
|
||||
外联 Notebook 示例:[外联 Notebook 示例](19-外联Notebook.mq.md)
|
||||
外联 view 单元示例:[外联 view 单元示例](19-外联视图单元.mq.md)
|
||||
@@ -21,13 +21,13 @@ A concept page can therefore point at the exact file that proves it:
|
||||
type: Capability
|
||||
title: Persistent foreign kernels
|
||||
description: Run Python or Node in a named, stateful kernel
|
||||
resource: public/features/19-foreign-notebook.mq.md
|
||||
resource: public/features/19-foreign-view-cells.mq.md
|
||||
status: stable
|
||||
verified:
|
||||
by: marqdo-knowledge/verify
|
||||
tags:
|
||||
- foreign
|
||||
- notebook
|
||||
- view-cells
|
||||
```
|
||||
|
||||
The same page can be opened in an editor, linked from a catalog, queried by an agent, and executed. Unknown fields are preserved; unknown types degrade to readable prose. The page is a concept, not a copy of one.
|
||||
@@ -104,7 +104,7 @@ marqdo find "foreign session"
|
||||
marqdo reuse "implement JSON fan-out"
|
||||
|
||||
# See what a change would touch
|
||||
marqdo impact public/features/19-foreign-notebook.mq.md
|
||||
marqdo impact public/features/19-foreign-view-cells.mq.md
|
||||
|
||||
# Validate the knowledge projection
|
||||
marqdo knowledge verify
|
||||
@@ -132,4 +132,4 @@ Catalog CLI: [Catalog CLI](../../doc/design/catalog-cli.md)
|
||||
|
||||
OKF and Marqdo research: [OKF and Marqdo research](../../doc/research/okf-and-marqdo.md)
|
||||
|
||||
Foreign notebook example: [Foreign notebook example](19-foreign-notebook.mq.md)
|
||||
Foreign view-cells example: [Foreign view-cells example](19-foreign-view-cells.mq.md)
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Persisting foreign execution results
|
||||
description: Static snapshots and writeback — how foreign results survive after the process exits
|
||||
import foreign:lib/foreign.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Foreign code has two useful lives: as a published snapshot, and as a living document whose latest result is kept in source. They answer different questions and should not be confused.
|
||||
|
||||
---
|
||||
|
||||
Static snapshot: publish the result.
|
||||
|
||||
`marqdo view output` executes the document's cells and embeds their real output in the generated HTML. The `.mq.md` source is not modified. This is the default choice for user documentation, reviews and stable links: a reader sees the result without running anything, and the source stays clean.
|
||||
|
||||
The static snapshot is a point-in-time artifact. If an external service changes, rebuild it; do not treat it as a live dashboard.
|
||||
|
||||
---
|
||||
|
||||
Writeback: keep the result in the source.
|
||||
|
||||
For an exploratory or audit document, pair `foreign` with `lib/writeback`. `writeback.record` writes a keyed output slot next to the call. The slot is visible in the Markdown source, can be reviewed in a diff and can be committed with the document.
|
||||
|
||||
| Step | What it does |
|
||||
|------|--------------|
|
||||
| Foreign run / Foreign session | Execute the foreign code and return a Marqdo value |
|
||||
| Writeback record | Persist that value in a named slot |
|
||||
| git diff | Review the changed result like any other document change |
|
||||
|
||||
A real writeback in this page.
|
||||
|
||||
This page is itself the runnable example. The code fence below is ordinary Marqdo data; `foreign.run` executes it, then `writeback.record` writes the `total` slot into this source file.
|
||||
|
||||
`写回代码` =
|
||||
```python
|
||||
print(950)
|
||||
```
|
||||
|
||||
**结果 = > foreign.run code=`写回代码`**
|
||||
|
||||
**> writeback.record value=`结果` key="total"**
|
||||
<!-- marqdo-out total
|
||||
950
|
||||
-->
|
||||
|
||||
The generated slot is directly below that call. Re-running the page replaces only the `total` slot; it does not duplicate it.
|
||||
|
||||
Writeback is explicit. It is not hidden kernel serialization, does not persist arbitrary kernel memory, and does not touch a file unless the document calls it.
|
||||
|
||||
---
|
||||
|
||||
Choosing.
|
||||
|
||||
For published user docs, use the static snapshot. For a living report that must keep the latest run result in the `.mq.md` itself, use writeback. Both can coexist in one repository: static pages for readers, writeback examples for authors and audits.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: 外联执行结果的持久化
|
||||
description: 静态快照与自写回 —— 外联结果在进程退出后如何保留
|
||||
导入 外联:lib/外联.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
外联代码有两种有用的形态:发布快照,以及把最新结果保留在源码里的活文档。两者回答不同的问题,不应混为一谈。
|
||||
|
||||
---
|
||||
|
||||
静态快照:发布结果。
|
||||
|
||||
`marqdo view output` 执行文档单元,并把真实输出嵌入生成的 HTML。`.mq.md` 源码不会被修改。这是用户文档、评审和稳定链接的默认选择:读者不需要运行任何东西就能看到结果,源码保持干净。
|
||||
|
||||
静态快照是某个时间点的产物。外部服务变化后重新构建即可,不要把它当成实时看板。
|
||||
|
||||
---
|
||||
|
||||
自写回:把结果留在源码里。
|
||||
|
||||
对于探索性或审计型文档,把 `外联` 和 `lib/writeback` 搭配使用。`writeback.record` 会在调用点附近写入带 key 的输出槽位。槽位在 Markdown 源码中可见,可以在 diff 中审阅,也可以随文档提交。
|
||||
|
||||
| 步骤 | 作用 |
|
||||
|------|------|
|
||||
| 外联执行 / 外联会话 | 执行外联代码并返回 Marqdo 值 |
|
||||
| 写回记录 | 把该值持久化到命名槽位 |
|
||||
| git diff | 像审阅普通文档改动一样审阅结果 |
|
||||
|
||||
这一页本身就是完整示例。
|
||||
|
||||
这一页就是可运行的示例。下面的代码围栏是普通 Marqdo 值;`外联.运行` 执行它,然后 `writeback.record` 把 `total` 槽位写进本页源码。
|
||||
|
||||
`写回代码` =
|
||||
```python
|
||||
print(950)
|
||||
```
|
||||
|
||||
**结果 = > 外联.运行 代码=`写回代码`**
|
||||
|
||||
**> writeback.record value=`结果` key="total"**
|
||||
<!-- marqdo-out total
|
||||
950
|
||||
-->
|
||||
|
||||
生成的槽位就在这次调用下方。再次运行只替换 `total` 槽位,不会重复添加。
|
||||
|
||||
自写回是显式动作。它不是隐藏的内核序列化,不持久化任意内核内存,也不会在文档没有调用时修改文件。
|
||||
|
||||
---
|
||||
|
||||
如何选择。
|
||||
|
||||
面向用户的发布文档用静态快照;需要把最新执行结果留在 `.mq.md` 本身里的活文档用自写回。两者可以共存于同一个仓库:静态页面给读者,自写回示例给作者和审计。
|
||||
@@ -11,7 +11,7 @@ English-named files export English APIs; Chinese-named files export Chinese APIs
|
||||
|
||||
No extra allow flags: importing a module means you intend to use it. Under marqdo view or static export, exit soft-fails and long sleeps are clamped so the console stays up.
|
||||
|
||||
Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络), math (math / 数学), foreign (foreign / 外联), plugin (plugin / 插件), writeback (writeback / 自写回), subtask (subtask / 子任务). Foreign v2 adds structured invoke records, JSON calls, parallel fan-out, persistent Python/Node kernels, an explicit state bridge and document-native notebook sessions — see stdlib/foreign.mq.md and features/19-foreign-notebook.mq.md.
|
||||
Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络), math (math / 数学), foreign (foreign / 外联), plugin (plugin / 插件), writeback (writeback / 自写回), subtask (subtask / 子任务). Foreign v2 adds structured invoke records, JSON calls, parallel fan-out, persistent Python/Node kernels, an explicit state bridge and document-native view cells — see stdlib/foreign.mq.md and features/19-foreign-view-cells.mq.md.
|
||||
|
||||
From v0.1.2, official `lib/*.mq.md` is embedded in the `marqdo` binary (disk `lib/` or `MARQDO_LIB` still overrides). Standalone `.exe` works without a separate stdlib zip.
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ description: 如何导入官方 lib 模块
|
||||
|
||||
导入即表示要用对应能力,无需再加允许旗标。marqdo view 或静态导出里,退出会软失败、长睡眠会被钳制,以免拖垮控制台。
|
||||
|
||||
模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)、数学(math / 数学)、外联(foreign / 外联)、插件(plugin / 插件)、自写回(writeback / 自写回)、子任务(subtask / 子任务)。外联 v2 新增结构化执行记录、JSON 调用、并行扇出、Python/Node 持久内核、显式状态桥与文档原生 notebook 会话 — 见 stdlib/外联.mq.md 与 features/19-外联Notebook.mq.md。
|
||||
模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)、数学(math / 数学)、外联(foreign / 外联)、插件(plugin / 插件)、自写回(writeback / 自写回)、子任务(subtask / 子任务)。外联 v2 新增结构化执行记录、JSON 调用、并行扇出、Python/Node 持久内核、显式状态桥与文档原生 view 单元 — 见 stdlib/外联.mq.md 与 features/19-外联视图单元.mq.md。
|
||||
|
||||
自 v0.1.2 起,官方 `lib/*.mq.md` 内置于 `marqdo` 二进制(磁盘 `lib/` 或 `MARQDO_LIB` 仍可覆盖)。单独下载 `.exe` 即可导入标准库,无需再解压 stdlib 包。
|
||||
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
title: lib/foreign — foreign kernels v2
|
||||
description: Structured execution, JSON calls, parallel fan-out, persistent kernels and an explicit state bridge
|
||||
import foreign:lib/foreign.mq.md
|
||||
stdin: 21
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -106,28 +107,30 @@ This is a JSON copy, not shared memory. The kernel receives a value; Marqdo rece
|
||||
|
||||
---
|
||||
|
||||
Notebook sessions.
|
||||
Cells in view.
|
||||
|
||||
A document can declare named kernels and a cell order without new Markdown markers:
|
||||
`foreign.session` owns the document's kernel state. The kernel and cell order are ordinary tables passed as arguments; the names are free:
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | shared analysis |
|
||||
| 复核 | python | | isolated review |
|
||||
|
||||
`会话表` =
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | write state |
|
||||
| 计算指标 | 分析 | read state |
|
||||
| 独立复核 | 复核 | isolated kernel |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
```
|
||||
|
||||
Live `view` then adds Run All, Step, kernel switching, a journal and per-cell state. See the complete Python walkthrough in [`features/19-foreign-notebook.mq.md`](../features/19-foreign-notebook.mq.md).
|
||||
`view` consumes the `会话` handle and adds Run All, Step, kernel switching, a journal and per-cell state. Without `会话`, view cells are stateless one-shot runs: same shell, no persistent kernel. There is no second CLI mode. See the complete Python walkthrough in [`features/19-foreign-view-cells.mq.md`](../features/19-foreign-view-cells.mq.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
title: lib/外联 — 外联内核 v2
|
||||
description: 结构化执行、JSON 调用、并行扇出、持久内核与显式状态桥
|
||||
导入 外联:lib/外联.mq.md
|
||||
stdin: 21
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -106,28 +107,30 @@ process.stdin.on("end", () => {
|
||||
|
||||
---
|
||||
|
||||
Notebook 会话。
|
||||
view 中的单元。
|
||||
|
||||
文档可以直接声明命名内核和单元顺序,不需要新增 Markdown 标记:
|
||||
`foreign.session` 拥有文档的内核状态。内核和单元顺序都是作为参数传入的普通表格,名字可以自由选择:
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | 共享分析 |
|
||||
| 复核 | python | | 独立复核 |
|
||||
|
||||
`会话表` =
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | 写入状态 |
|
||||
| 计算指标 | 分析 | 读取状态 |
|
||||
| 独立复核 | 复核 | 隔离内核 |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
```
|
||||
|
||||
live `view` 会提供 Run All、Step、切换内核、journal 和单元状态。完整 Python 示例见 [`features/19-外联Notebook.mq.md`](../features/19-外联Notebook.mq.md)。
|
||||
`view` 消费 `会话` 句柄,提供 Run All、Step、切换内核、journal 和单元状态。没有 `会话` 时,view 的 cells 是无状态的一次性运行:同一套外壳,但没有持久内核。没有第二个 CLI 模式。完整 Python 示例见 [`features/19-外联视图单元.mq.md`](../features/19-外联视图单元.mq.md)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -89,7 +89,10 @@ impl StmtEventKind {
|
||||
pub struct CallFrame {
|
||||
pub call_id: u32,
|
||||
pub fn_name: String,
|
||||
/// Definition line of the callee.
|
||||
pub fn_line: u32,
|
||||
/// Call site line in the executing document (0 for the entry call).
|
||||
pub call_line: u32,
|
||||
pub ordinal: u32,
|
||||
pub args_brief: String,
|
||||
}
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
//! Document session: cells, kernels, execution journal, state store.
|
||||
//!
|
||||
//! The notebook layer reads the conventional `内核表`/`会话表` bindings and the
|
||||
//! bound code fences. It does not change the Markdown parser.
|
||||
//! Stateful cells live here, owned by the foreign runtime. The view reads a
|
||||
//! `会话 = > foreign.session ...` handle; no table names are reserved, and a
|
||||
//! document without that handle gets stateless one-shot cells.
|
||||
|
||||
use std::collections::{HashMap, HashSet};
|
||||
use std::path::{Path, PathBuf};
|
||||
@@ -11,7 +12,6 @@ use sha2::{Digest, Sha256};
|
||||
use crate::foreign::registry;
|
||||
use crate::host::foreign_session;
|
||||
use crate::host::HostContext;
|
||||
use crate::parse::parse_source;
|
||||
use crate::value::Value;
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
@@ -79,6 +79,8 @@ pub struct JournalRecord {
|
||||
|
||||
pub struct DocumentSession {
|
||||
pub path: PathBuf,
|
||||
root: PathBuf,
|
||||
pub persistent: bool,
|
||||
pub cells: Vec<Cell>,
|
||||
pub kernels: Vec<KernelDecl>,
|
||||
pub order: Vec<String>,
|
||||
@@ -104,90 +106,110 @@ fn now_ms() -> i64 {
|
||||
.unwrap_or(0)
|
||||
}
|
||||
|
||||
/// Split a GFM row into trimmed cells.
|
||||
fn split_row(line: &str) -> Vec<String> {
|
||||
let t = line.trim();
|
||||
let t = t.strip_prefix('|').unwrap_or(t);
|
||||
let t = t.strip_suffix('|').unwrap_or(t);
|
||||
t.split('|')
|
||||
.map(|c| c.trim().trim_matches('`').trim().to_string())
|
||||
.collect()
|
||||
/// Convert a table value into row maps. Handles both row tables (`| @ | ... |`)
|
||||
/// and ordinary column tables; no source text is scanned.
|
||||
fn table_rows(v: &Value) -> Result<Vec<HashMap<String, Value>>, String> {
|
||||
match v {
|
||||
Value::None => Ok(Vec::new()),
|
||||
Value::List(rows) => {
|
||||
let mut out = Vec::with_capacity(rows.len());
|
||||
for (i, row) in rows.iter().enumerate() {
|
||||
let Value::Map(pairs) = row else {
|
||||
return Err(format!("view table row {} is not a map", i + 1));
|
||||
};
|
||||
out.push(
|
||||
pairs
|
||||
.iter()
|
||||
.filter(|(k, _)| k != "@")
|
||||
.map(|(k, v)| (k.clone(), v.clone()))
|
||||
.collect(),
|
||||
);
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
Value::Map(cols) => {
|
||||
// A single-row table may evaluate to a map of scalar fields rather
|
||||
// than a column map. Treat that map as one record.
|
||||
if !cols.iter().all(|(_, v)| matches!(v, Value::List(_))) {
|
||||
let row = cols
|
||||
.iter()
|
||||
.filter(|(k, _)| k != "@")
|
||||
.map(|(k, v)| (k.clone(), v.clone()))
|
||||
.collect();
|
||||
return Ok(vec![row]);
|
||||
}
|
||||
let mut width = 0usize;
|
||||
for (_, value) in cols {
|
||||
let Value::List(xs) = value else {
|
||||
unreachable!();
|
||||
};
|
||||
width = width.max(xs.len());
|
||||
}
|
||||
let mut out = Vec::with_capacity(width);
|
||||
for i in 0..width {
|
||||
let mut row = HashMap::new();
|
||||
for (name, value) in cols {
|
||||
if let Value::List(xs) = value {
|
||||
if let Some(v) = xs.get(i) {
|
||||
row.insert(name.clone(), v.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
out.push(row);
|
||||
}
|
||||
Ok(out)
|
||||
}
|
||||
_ => Err("view plan binding is not a table".into()),
|
||||
}
|
||||
}
|
||||
|
||||
/// Find `` `name` = `` and the first contiguous table after it.
|
||||
fn table_after(source: &str, name: &str) -> Result<Option<Vec<HashMap<String, String>>>, String> {
|
||||
let lines: Vec<&str> = source.lines().collect();
|
||||
let needle_a = format!("`{name}`");
|
||||
let needle_b = format!("{name} =");
|
||||
let mut start = None;
|
||||
for (i, line) in lines.iter().enumerate() {
|
||||
let t = line.trim();
|
||||
if t.starts_with(&needle_a) && t.contains('=') || t.starts_with(&needle_b) {
|
||||
start = Some(i + 1);
|
||||
break;
|
||||
}
|
||||
}
|
||||
let Some(mut i) = start else {
|
||||
return Ok(None);
|
||||
fn plan_tables(
|
||||
bindings: &HashMap<String, Value>,
|
||||
) -> Result<
|
||||
(
|
||||
Option<Vec<HashMap<String, Value>>>,
|
||||
Option<Vec<HashMap<String, Value>>>,
|
||||
Option<Vec<HashMap<String, Value>>>,
|
||||
),
|
||||
String,
|
||||
> {
|
||||
let Some(plan) = bindings.get("会话") else {
|
||||
return Ok((None, None, None));
|
||||
};
|
||||
while i < lines.len() && !lines[i].trim().starts_with('|') {
|
||||
if !lines[i].trim().is_empty() && !lines[i].trim().starts_with('|') {
|
||||
// Prose between the binding and the table is allowed.
|
||||
}
|
||||
i += 1;
|
||||
let Value::Map(fields) = plan else {
|
||||
// `会话` is also a common low-level session id binding (e.g. from
|
||||
// foreign.session_open). It is not a view plan; leave cells stateless.
|
||||
return Ok((None, None, None));
|
||||
};
|
||||
let field = |name: &str| {
|
||||
fields
|
||||
.iter()
|
||||
.find(|(k, _)| k == name)
|
||||
.map(|(_, v)| v.clone())
|
||||
};
|
||||
let kind = field("kind").map(|v| value_text(&v)).unwrap_or_default();
|
||||
if kind != "foreign-session" {
|
||||
return Err("`会话` must be a foreign.session handle".into());
|
||||
}
|
||||
if i >= lines.len() {
|
||||
return Ok(None);
|
||||
}
|
||||
let mut rows = Vec::new();
|
||||
let mut header: Option<Vec<String>> = None;
|
||||
while i < lines.len() {
|
||||
let t = lines[i].trim();
|
||||
if !t.starts_with('|') {
|
||||
break;
|
||||
}
|
||||
i += 1;
|
||||
if t.chars().all(|c| c == '|' || c == '-' || c == ':' || c.is_whitespace()) {
|
||||
continue;
|
||||
}
|
||||
let cells = split_row(t);
|
||||
if header.is_none() {
|
||||
header = Some(cells);
|
||||
continue;
|
||||
}
|
||||
let h = header.as_ref().unwrap();
|
||||
if cells.len() != h.len() {
|
||||
return Err(format!(
|
||||
"table `{name}`: row has {} cells, header has {}",
|
||||
cells.len(),
|
||||
h.len()
|
||||
));
|
||||
}
|
||||
let mut row = HashMap::new();
|
||||
for (k, v) in h.iter().zip(cells) {
|
||||
row.insert(k.clone(), v);
|
||||
}
|
||||
rows.push(row);
|
||||
}
|
||||
Ok(Some(rows))
|
||||
let kernels = match field("kernels") {
|
||||
Some(Value::None) | None => None,
|
||||
Some(v) => Some(table_rows(&v)?),
|
||||
};
|
||||
let cells = match field("cells") {
|
||||
Some(Value::None) | None => None,
|
||||
Some(v) => Some(table_rows(&v)?),
|
||||
};
|
||||
let values = match field("values") {
|
||||
Some(Value::None) | None => None,
|
||||
Some(v) => Some(table_rows(&v)?),
|
||||
};
|
||||
Ok((kernels, cells, values))
|
||||
}
|
||||
|
||||
fn table_any(
|
||||
source: &str,
|
||||
names: &[&str],
|
||||
) -> Result<Option<Vec<HashMap<String, String>>>, String> {
|
||||
for name in names {
|
||||
if let Some(rows) = table_after(source, name)? {
|
||||
return Ok(Some(rows));
|
||||
}
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
|
||||
fn col<'a>(row: &'a HashMap<String, String>, names: &[&str]) -> Option<&'a String> {
|
||||
fn col_value<'a>(row: &'a HashMap<String, Value>, names: &[&str]) -> Option<&'a Value> {
|
||||
for n in names {
|
||||
if let Some(v) = row.get(*n) {
|
||||
if !v.is_empty() {
|
||||
if !matches!(v, Value::None) {
|
||||
return Some(v);
|
||||
}
|
||||
}
|
||||
@@ -195,6 +217,38 @@ fn col<'a>(row: &'a HashMap<String, String>, names: &[&str]) -> Option<&'a Strin
|
||||
None
|
||||
}
|
||||
|
||||
fn value_text(v: &Value) -> String {
|
||||
match v {
|
||||
Value::Text(s) => s.clone(),
|
||||
Value::None => String::new(),
|
||||
other => other.as_display(),
|
||||
}
|
||||
}
|
||||
|
||||
fn col_text(row: &HashMap<String, Value>, names: &[&str]) -> Option<String> {
|
||||
col_value(row, names).map(value_text).filter(|s| !s.trim().is_empty())
|
||||
}
|
||||
|
||||
/// Evaluate the entry object's declarations with the real interpreter. Tables
|
||||
/// are ordinary Marqdo values; the view does not re-parse source text.
|
||||
fn capture_bindings(
|
||||
path: &Path,
|
||||
root: &Path,
|
||||
module: &crate::ast::Module,
|
||||
source: &str,
|
||||
) -> Result<HashMap<String, Value>, String> {
|
||||
let mut host = HostContext::for_capture(Some(path), crate::host::HostCaps::default());
|
||||
host.cwd = path.parent().unwrap_or_else(|| Path::new(".")).to_path_buf();
|
||||
host.fs_root = Some(root.to_path_buf());
|
||||
host.entry_path = Some(path.to_path_buf());
|
||||
host.entry_source = Some(source.to_string());
|
||||
host.entry_metadata = module.metadata.clone();
|
||||
let mut interp = crate::interp::Interpreter::with_capture(Some(path), false).with_host(host);
|
||||
interp
|
||||
.capture_declarations(module, &["会话"])
|
||||
.map_err(|e| format!("view plan evaluation: {e}"))
|
||||
}
|
||||
|
||||
fn collect_cells(stmts: &[crate::ast::Stmt], out: &mut Vec<Cell>, seen: &mut HashSet<String>) -> Result<(), String> {
|
||||
for stmt in stmts {
|
||||
match stmt {
|
||||
@@ -244,7 +298,12 @@ impl DocumentSession {
|
||||
pub fn open(path: &Path, root: &Path) -> Result<Self, String> {
|
||||
let source = std::fs::read_to_string(path)
|
||||
.map_err(|e| format!("read {}: {e}", path.display()))?;
|
||||
let module = parse_source(&source).map_err(|e| format!("parse {}: {e}", path.display()))?;
|
||||
let bind_ctx = crate::binding::BindingContext::from_binds(
|
||||
&[],
|
||||
crate::binding::cwd_for_path(Some(path)),
|
||||
);
|
||||
let module = crate::load::load_module_with_ctx(path, &bind_ctx)
|
||||
.map_err(|e| format!("load {}: {e}", path.display()))?;
|
||||
let entry = module
|
||||
.functions
|
||||
.iter()
|
||||
@@ -261,27 +320,31 @@ impl DocumentSession {
|
||||
let mut cells = Vec::new();
|
||||
let mut seen = HashSet::new();
|
||||
collect_cells(&entry.body, &mut cells, &mut seen)?;
|
||||
if cells.is_empty() {
|
||||
return Err("notebook: no bound code fences (`name` = + ```lang)".into());
|
||||
}
|
||||
let declarations = capture_bindings(path, root, &module, &source)?;
|
||||
|
||||
let (plan_kernels, plan_cells, plan_values) = plan_tables(&declarations)?;
|
||||
let persistent = matches!(
|
||||
declarations.get("会话"),
|
||||
Some(Value::Map(fields))
|
||||
if fields
|
||||
.iter()
|
||||
.any(|(k, v)| k == "kind" && value_text(v) == "foreign-session")
|
||||
);
|
||||
let mut kernels: Vec<KernelDecl> = Vec::new();
|
||||
let mut kernel_map: HashMap<String, KernelDecl> = HashMap::new();
|
||||
if let Some(rows) = table_any(&source, &["内核表", "kernels", "Kernels"])? {
|
||||
if let Some(rows) = plan_kernels {
|
||||
if rows.is_empty() {
|
||||
return Err("内核表: at least one kernel row is required".into());
|
||||
return Err("foreign.session: at least one kernel row is required".into());
|
||||
}
|
||||
for row in rows {
|
||||
let name = col(&row, &["名称", "Name", "name"])
|
||||
.ok_or_else(|| "内核表: missing 名称/Name".to_string())?
|
||||
.clone();
|
||||
let lang = col(&row, &["语言", "Language", "language", "lang"])
|
||||
.ok_or_else(|| format!("内核表[{name}]: missing 语言/Language"))?
|
||||
.clone();
|
||||
let name = col_text(&row, &["名称", "Name", "name"])
|
||||
.ok_or_else(|| "foreign.session kernels: missing 名称/Name".to_string())?;
|
||||
let lang = col_text(&row, &["语言", "Language", "language", "lang"])
|
||||
.ok_or_else(|| format!("foreign.session[{name}]: missing 语言/Language"))?;
|
||||
let lang = registry::canonical(&lang);
|
||||
let cmd = col(&row, &["命令", "Command", "command", "cmd"]).cloned();
|
||||
let cmd = col_text(&row, &["命令", "Command", "command", "cmd"]);
|
||||
if kernel_map.contains_key(&name) {
|
||||
return Err(format!("内核表: kernel `{name}` is declared twice"));
|
||||
return Err(format!("foreign.session: kernel `{name}` is declared twice"));
|
||||
}
|
||||
let decl = KernelDecl {
|
||||
name: name.clone(),
|
||||
@@ -295,10 +358,10 @@ impl DocumentSession {
|
||||
}
|
||||
|
||||
let mut order: Vec<String> = Vec::new();
|
||||
let session_rows = table_any(&source, &["会话表", "session", "Session"])?;
|
||||
let session_rows = plan_cells;
|
||||
if let Some(rows) = session_rows {
|
||||
if rows.is_empty() {
|
||||
return Err("会话表: at least one cell row is required".into());
|
||||
return Err("foreign.session cells: at least one cell row is required".into());
|
||||
}
|
||||
let by_name: HashMap<String, usize> = cells
|
||||
.iter()
|
||||
@@ -307,22 +370,20 @@ impl DocumentSession {
|
||||
.collect();
|
||||
let mut listed = HashSet::new();
|
||||
for row in rows {
|
||||
let cell_name = col(&row, &["单元", "Cell", "cell", "单元名"])
|
||||
.ok_or_else(|| "会话表: missing 单元/Cell".to_string())?
|
||||
.clone();
|
||||
let kernel_name = col(&row, &["内核", "Kernel", "kernel"])
|
||||
.ok_or_else(|| format!("会话表[{cell_name}]: missing 内核/Kernel"))?
|
||||
.clone();
|
||||
let cell_name = col_text(&row, &["单元", "Cell", "cell", "单元名"])
|
||||
.ok_or_else(|| "foreign.session cells: missing 单元/Cell".to_string())?;
|
||||
let kernel_name = col_text(&row, &["内核", "Kernel", "kernel"])
|
||||
.ok_or_else(|| format!("foreign.session[{cell_name}]: missing 内核/Kernel"))?;
|
||||
let Some(&ci) = by_name.get(&cell_name) else {
|
||||
return Err(format!("会话表: unknown cell `{cell_name}`"));
|
||||
return Err(format!("foreign.session: unknown cell `{cell_name}`"));
|
||||
};
|
||||
if !listed.insert(cell_name.clone()) {
|
||||
return Err(format!("会话表: cell `{cell_name}` is listed twice"));
|
||||
return Err(format!("foreign.session: cell `{cell_name}` is listed twice"));
|
||||
}
|
||||
let kernel = resolve_kernel(&mut kernels, &mut kernel_map, &kernel_name)?;
|
||||
if registry::canonical(&cells[ci].lang) != registry::canonical(&kernel.lang) {
|
||||
return Err(format!(
|
||||
"会话表: cell `{cell_name}` ({}) cannot use kernel `{}` ({})",
|
||||
"foreign.session: cell `{cell_name}` ({}) cannot use kernel `{}` ({})",
|
||||
cells[ci].lang, kernel.name, kernel.lang
|
||||
));
|
||||
}
|
||||
@@ -335,7 +396,7 @@ impl DocumentSession {
|
||||
cell.status = CellStatus::Unlisted;
|
||||
}
|
||||
}
|
||||
} else {
|
||||
} else if persistent {
|
||||
for cell in &mut cells {
|
||||
let kernel = ensure_default_kernel(
|
||||
&mut kernels,
|
||||
@@ -346,6 +407,12 @@ impl DocumentSession {
|
||||
cell.listed = true;
|
||||
order.push(cell.name.clone());
|
||||
}
|
||||
} else {
|
||||
for cell in &mut cells {
|
||||
cell.kernel = "one-shot".into();
|
||||
cell.listed = true;
|
||||
order.push(cell.name.clone());
|
||||
}
|
||||
}
|
||||
|
||||
let mut host = HostContext::default();
|
||||
@@ -355,8 +422,10 @@ impl DocumentSession {
|
||||
host.entry_path = Some(path.to_path_buf());
|
||||
host.entry_source = Some(source);
|
||||
|
||||
Ok(Self {
|
||||
let mut session = Self {
|
||||
path: path.to_path_buf(),
|
||||
root: root.to_path_buf(),
|
||||
persistent,
|
||||
cells,
|
||||
kernels,
|
||||
order,
|
||||
@@ -367,7 +436,26 @@ impl DocumentSession {
|
||||
host,
|
||||
kernel_sessions: HashMap::new(),
|
||||
seq: 0,
|
||||
})
|
||||
};
|
||||
if let Some(rows) = plan_values {
|
||||
for row in rows {
|
||||
let kernel = col_text(&row, &["内核", "Kernel", "kernel"])
|
||||
.ok_or_else(|| "foreign.session values: missing 内核/Kernel".to_string())?;
|
||||
let name = col_text(&row, &["名称", "Name", "name"])
|
||||
.ok_or_else(|| "foreign.session values: missing 名称/Name".to_string())?;
|
||||
let value = col_value(&row, &["值", "Value", "value", "数据"])
|
||||
.ok_or_else(|| format!("foreign.session values[{name}]: missing 值/Value"))?
|
||||
.clone();
|
||||
let id = session.ensure_kernel_session(&kernel)?;
|
||||
foreign_session::set(
|
||||
&mut session.host,
|
||||
&Value::Text(id),
|
||||
&Value::Text(name),
|
||||
&value,
|
||||
)?;
|
||||
}
|
||||
}
|
||||
Ok(session)
|
||||
}
|
||||
|
||||
/// Re-read the document, preserving kernels/state/journal. Changed cells become dirty.
|
||||
@@ -511,11 +599,47 @@ impl DocumentSession {
|
||||
}
|
||||
|
||||
pub fn run_cell(&mut self, cell_name: &str, kernel_override: Option<&str>) -> Result<Value, String> {
|
||||
self.run_cell_with_stdin(cell_name, kernel_override, None)
|
||||
}
|
||||
|
||||
pub fn run_cell_with_stdin(
|
||||
&mut self,
|
||||
cell_name: &str,
|
||||
kernel_override: Option<&str>,
|
||||
stdin: Option<&str>,
|
||||
) -> Result<Value, String> {
|
||||
let ci = self
|
||||
.cell_index(cell_name)
|
||||
.ok_or_else(|| format!("unknown cell `{cell_name}`"))?;
|
||||
if !self.cells[ci].listed && kernel_override.is_none() {
|
||||
return Err(format!("cell `{cell_name}` is not in 会话表"));
|
||||
return Err(format!("cell `{cell_name}` is not listed in the foreign session"));
|
||||
}
|
||||
if !self.persistent {
|
||||
self.cells[ci].kernel = "one-shot".into();
|
||||
self.cells[ci].status = CellStatus::Running;
|
||||
let lang = self.cells[ci].lang.clone();
|
||||
let source = self.cells[ci].source.clone();
|
||||
let result = crate::host::foreign::invoke_for_view(
|
||||
&self.root,
|
||||
&lang,
|
||||
&source,
|
||||
None,
|
||||
stdin,
|
||||
None,
|
||||
);
|
||||
return match result {
|
||||
Ok(record) => {
|
||||
self.record_result(cell_name, "one-shot", &record)?;
|
||||
Ok(record)
|
||||
}
|
||||
Err(e) => {
|
||||
if let Some(i) = self.cell_index(cell_name) {
|
||||
self.cells[i].status = CellStatus::Error;
|
||||
self.cells[i].last_error = e.clone();
|
||||
}
|
||||
Err(e)
|
||||
}
|
||||
};
|
||||
}
|
||||
let kernel = match kernel_override {
|
||||
Some(k) => {
|
||||
@@ -547,7 +671,7 @@ impl DocumentSession {
|
||||
&Value::Text(id),
|
||||
None,
|
||||
Some(&source),
|
||||
None,
|
||||
stdin.map(|s| Value::Text(s.to_string())).as_ref(),
|
||||
None,
|
||||
)?;
|
||||
self.record_result(cell_name, &kernel, &record)?;
|
||||
@@ -560,6 +684,10 @@ impl DocumentSession {
|
||||
}
|
||||
|
||||
pub fn step(&mut self) -> Result<Value, String> {
|
||||
self.step_with_stdin(None)
|
||||
}
|
||||
|
||||
pub fn step_with_stdin(&mut self, stdin: Option<&str>) -> Result<Value, String> {
|
||||
if self.cursor >= self.order.len() {
|
||||
return Ok(Value::Map(vec![
|
||||
("done".into(), Value::Bool(true)),
|
||||
@@ -567,7 +695,7 @@ impl DocumentSession {
|
||||
]));
|
||||
}
|
||||
let name = self.order[self.cursor].clone();
|
||||
let record = self.run_cell(&name, None)?;
|
||||
let record = self.run_cell_with_stdin(&name, None, stdin)?;
|
||||
let ci = self.cell_index(&name).unwrap_or(0);
|
||||
let kernel = self.cells[ci].kernel.clone();
|
||||
self.cursor += 1;
|
||||
@@ -582,6 +710,14 @@ impl DocumentSession {
|
||||
}
|
||||
|
||||
pub fn run_all(&mut self, restart: bool) -> Result<Value, String> {
|
||||
self.run_all_with_stdin(restart, None)
|
||||
}
|
||||
|
||||
pub fn run_all_with_stdin(
|
||||
&mut self,
|
||||
restart: bool,
|
||||
stdin: Option<&str>,
|
||||
) -> Result<Value, String> {
|
||||
if restart {
|
||||
self.restart_all()?;
|
||||
}
|
||||
@@ -589,7 +725,23 @@ impl DocumentSession {
|
||||
let mut records = Vec::new();
|
||||
let mut failed = 0i64;
|
||||
for name in self.order.clone() {
|
||||
let record = self.run_cell(&name, None)?;
|
||||
let record = match self.run_cell_with_stdin(&name, None, stdin) {
|
||||
Ok(record) => record,
|
||||
Err(error) => {
|
||||
if let Some(i) = self.cell_index(&name) {
|
||||
self.cells[i].status = CellStatus::Error;
|
||||
self.cells[i].last_error = error.clone();
|
||||
}
|
||||
Value::Map(vec![
|
||||
("ok".into(), Value::Bool(false)),
|
||||
("stdout".into(), Value::Text(String::new())),
|
||||
("stderr".into(), Value::Text(String::new())),
|
||||
("error".into(), Value::Text(error)),
|
||||
("code".into(), Value::Int(-1)),
|
||||
("ms".into(), Value::Int(0)),
|
||||
])
|
||||
}
|
||||
};
|
||||
let ok = match &record {
|
||||
Value::Map(m) => matches!(
|
||||
m.iter().find(|(k, _)| k == "ok").map(|(_, v)| v),
|
||||
@@ -754,6 +906,7 @@ impl DocumentSession {
|
||||
Value::Map(vec![
|
||||
("title".into(), Value::Text(self.title())),
|
||||
("path".into(), Value::Text(self.path.display().to_string())),
|
||||
("persistent".into(), Value::Bool(self.persistent)),
|
||||
("cells".into(), Value::List(cells)),
|
||||
("kernels".into(), Value::List(kernels)),
|
||||
("order".into(), Value::List(
|
||||
@@ -782,6 +935,38 @@ impl DocumentSession {
|
||||
])
|
||||
}
|
||||
|
||||
/// Clear one cell's displayed output/record; kernels and live state survive.
|
||||
pub fn clear_cell(&mut self, cell: &str) -> Result<Value, String> {
|
||||
let i = self
|
||||
.cell_index(cell)
|
||||
.ok_or_else(|| format!("unknown cell `{cell}`"))?;
|
||||
self.cells[i].runs = 0;
|
||||
self.cells[i].last_ms = 0;
|
||||
self.cells[i].last_ok = false;
|
||||
self.cells[i].last_error.clear();
|
||||
if self.cells[i].listed {
|
||||
self.cells[i].status = CellStatus::Never;
|
||||
}
|
||||
self.journal.retain(|j| j.cell != cell);
|
||||
Ok(self.summary())
|
||||
}
|
||||
|
||||
/// Clear displayed outputs and per-cell records; kernels and live state survive.
|
||||
pub fn clear_outputs(&mut self) -> Value {
|
||||
for cell in &mut self.cells {
|
||||
cell.runs = 0;
|
||||
cell.last_ms = 0;
|
||||
cell.last_ok = false;
|
||||
cell.last_error.clear();
|
||||
if cell.listed {
|
||||
cell.status = CellStatus::Never;
|
||||
}
|
||||
}
|
||||
self.journal.clear();
|
||||
self.cursor = 0;
|
||||
self.summary()
|
||||
}
|
||||
|
||||
pub fn journal_json(&self) -> Value {
|
||||
Value::List(
|
||||
self.journal
|
||||
@@ -833,7 +1018,7 @@ fn resolve_kernel(
|
||||
return Ok(decl);
|
||||
}
|
||||
Err(format!(
|
||||
"会话表: kernel `{name}` is not declared in 内核表"
|
||||
"foreign.session: kernel `{name}` is not declared in kernels"
|
||||
))
|
||||
}
|
||||
|
||||
@@ -862,17 +1047,87 @@ mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn rows_parse() {
|
||||
assert_eq!(split_row("| a | b |"), vec!["a", "b"]);
|
||||
assert_eq!(split_row("| `a` | b |"), vec!["a", "b"]);
|
||||
fn table_rows_reads_row_records_and_columns() {
|
||||
let row_table = Value::List(vec![Value::Map(vec![
|
||||
("@".into(), Value::Text("1".into())),
|
||||
("名称".into(), Value::Text("分析".into())),
|
||||
("语言".into(), Value::Text("python".into())),
|
||||
])]);
|
||||
let rows = table_rows(&row_table).unwrap();
|
||||
assert_eq!(rows.len(), 1);
|
||||
assert_eq!(col_text(&rows[0], &["名称"]).as_deref(), Some("分析"));
|
||||
|
||||
let column_table = Value::Map(vec![
|
||||
("名称".into(), Value::List(vec![Value::Text("分析".into())])),
|
||||
("语言".into(), Value::List(vec![Value::Text("python".into())])),
|
||||
]);
|
||||
let rows = table_rows(&column_table).unwrap();
|
||||
assert_eq!(rows.len(), 1);
|
||||
assert_eq!(col_text(&rows[0], &["语言"]).as_deref(), Some("python"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn table_after_finds_rows() {
|
||||
let src = "# main\n\n`内核表` =\n\n| 名称 | 语言 |\n|---|---|\n| 分析 | python |\n";
|
||||
let rows = table_after(src, "内核表").unwrap().unwrap();
|
||||
assert_eq!(rows.len(), 1);
|
||||
assert_eq!(rows[0].get("名称").map(|s| s.as_str()), Some("分析"));
|
||||
fn plan_uses_evaluated_bindings() {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join(format!(
|
||||
"target/view-plan-{}-{}.mq.md",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.map(|d| d.as_nanos())
|
||||
.unwrap_or(0)
|
||||
));
|
||||
let source = r#"---
|
||||
title: evaluated plan test
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`lang` = python
|
||||
|
||||
`分析内核` =
|
||||
|
||||
| @ | 名称 | 语言 |
|
||||
|---|------|------|
|
||||
| 1 | 分析 | `lang` |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| @ | 单元 | 内核 |
|
||||
|---|------|------|
|
||||
| 1 | 单元 | 分析 |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
|
||||
`单元` =
|
||||
```python
|
||||
print(1)
|
||||
```
|
||||
"#;
|
||||
std::fs::write(&path, source).unwrap();
|
||||
let s = DocumentSession::open(&path, &root).unwrap();
|
||||
assert_eq!(s.cells.len(), 1);
|
||||
assert_eq!(s.cells[0].kernel, "分析");
|
||||
assert_eq!(s.kernels[0].lang, "python");
|
||||
let _ = std::fs::remove_file(&path);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn view_open_accepts_a_document_without_cells() {
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join(format!(
|
||||
"target/view-empty-{}-{}.mq.md",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.map(|d| d.as_nanos())
|
||||
.unwrap_or(0)
|
||||
));
|
||||
std::fs::write(&path, "# main\n\n> print text=hello\n").unwrap();
|
||||
let s = DocumentSession::open(&path, &root).unwrap();
|
||||
assert!(s.cells.is_empty());
|
||||
let _ = std::fs::remove_file(&path);
|
||||
}
|
||||
|
||||
fn node_available() -> bool {
|
||||
@@ -907,7 +1162,12 @@ mod tests {
|
||||
.map(|d| d.as_nanos())
|
||||
.unwrap_or(0)
|
||||
));
|
||||
let source = r#"# main
|
||||
let source = r#"---
|
||||
title: shared state test
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`内核表` =
|
||||
|
||||
@@ -924,6 +1184,8 @@ mod tests {
|
||||
| 读取 | 分析 | read |
|
||||
| 隔离 | 绘图 | isolated |
|
||||
|
||||
`会话` = > foreign.session kernels=`内核表` cells=`会话表`
|
||||
|
||||
`设置` =
|
||||
```node
|
||||
let shared = 41;
|
||||
@@ -964,6 +1226,200 @@ console.log(typeof shared === "undefined" ? "isolated" : "leaked");
|
||||
let _ = std::fs::remove_file(&path);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn magic_table_names_without_session_are_ignored() {
|
||||
if !node_available() {
|
||||
return;
|
||||
}
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join(format!(
|
||||
"target/view-stateless-{}-{}.mq.md",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.map(|d| d.as_nanos())
|
||||
.unwrap_or(0)
|
||||
));
|
||||
let source = r#"# main
|
||||
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 |
|
||||
|------|------|
|
||||
| 分析 | node |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 |
|
||||
|------|------|
|
||||
| a | 分析 |
|
||||
|
||||
`a` =
|
||||
```node
|
||||
console.log("stateless");
|
||||
```
|
||||
"#;
|
||||
std::fs::write(&path, source).unwrap();
|
||||
let mut s = DocumentSession::open(&path, &root).unwrap();
|
||||
assert!(!s.persistent);
|
||||
assert!(s.kernels.is_empty(), "magic tables must not create kernels");
|
||||
assert_eq!(s.order, vec!["a".to_string()]);
|
||||
assert_eq!(s.cells[0].kernel, "one-shot");
|
||||
let r = s.run_cell("a", None).unwrap();
|
||||
assert_eq!(
|
||||
field(&r, "stdout").and_then(|v| v.reveal_text().map(|s| s.to_string())),
|
||||
Some("stateless\n".to_string())
|
||||
);
|
||||
assert_eq!(s.cells[0].status, CellStatus::Clean);
|
||||
s.clear_outputs();
|
||||
assert_eq!(s.cells[0].status, CellStatus::Never);
|
||||
assert!(s.journal.is_empty());
|
||||
s.close();
|
||||
let _ = std::fs::remove_file(&path);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn clear_outputs_keeps_persistent_kernel_state() {
|
||||
if !node_available() {
|
||||
return;
|
||||
}
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join(format!(
|
||||
"target/view-clear-{}-{}.mq.md",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.map(|d| d.as_nanos())
|
||||
.unwrap_or(0)
|
||||
));
|
||||
let source = r#"---
|
||||
title: clear outputs
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`内核` =
|
||||
|
||||
| 名称 | 语言 |
|
||||
|------|------|
|
||||
| 分析 | node |
|
||||
|
||||
`单元` =
|
||||
|
||||
| 单元 | 内核 |
|
||||
|------|------|
|
||||
| a | 分析 |
|
||||
|
||||
`会话` = > foreign.session kernels=`内核` cells=`单元`
|
||||
|
||||
`a` =
|
||||
```node
|
||||
globalThis.kept = (globalThis.kept || 0) + 1;
|
||||
console.log(globalThis.kept);
|
||||
```
|
||||
"#;
|
||||
std::fs::write(&path, source).unwrap();
|
||||
let mut s = DocumentSession::open(&path, &root).unwrap();
|
||||
let r = s.run_cell("a", None).unwrap();
|
||||
assert_eq!(
|
||||
field(&r, "stdout").and_then(|v| v.reveal_text().map(|s| s.to_string())),
|
||||
Some("1\n".to_string())
|
||||
);
|
||||
s.clear_outputs();
|
||||
assert_eq!(s.cells[0].status, CellStatus::Never);
|
||||
assert!(s.journal.is_empty());
|
||||
let r = s.run_cell("a", None).unwrap();
|
||||
assert_eq!(
|
||||
field(&r, "stdout").and_then(|v| v.reveal_text().map(|s| s.to_string())),
|
||||
Some("2\n".to_string()),
|
||||
"clear outputs must not restart the kernel"
|
||||
);
|
||||
s.close();
|
||||
let _ = std::fs::remove_file(&path);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn stateless_cell_accepts_stdin() {
|
||||
if !node_available() {
|
||||
return;
|
||||
}
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join(format!(
|
||||
"target/view-stdin-{}-{}.mq.md",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.map(|d| d.as_nanos())
|
||||
.unwrap_or(0)
|
||||
));
|
||||
let source = r#"# main
|
||||
|
||||
`a` =
|
||||
```node
|
||||
const fs = require("fs");
|
||||
const input = fs.readFileSync(0, "utf8").trim();
|
||||
console.log("got:" + input);
|
||||
```
|
||||
"#;
|
||||
std::fs::write(&path, source).unwrap();
|
||||
let mut s = DocumentSession::open(&path, &root).unwrap();
|
||||
let record = s
|
||||
.run_cell_with_stdin("a", None, Some("hello stdin"))
|
||||
.unwrap();
|
||||
assert_eq!(
|
||||
field(&record, "stdout").and_then(|v| v.reveal_text().map(|s| s.to_string())),
|
||||
Some("got:hello stdin\n".to_string())
|
||||
);
|
||||
s.close();
|
||||
let _ = std::fs::remove_file(&path);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn run_all_continues_after_a_cell_error() {
|
||||
if !node_available() {
|
||||
return;
|
||||
}
|
||||
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
let path = root.join(format!(
|
||||
"target/view-run-all-error-{}-{}.mq.md",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.map(|d| d.as_nanos())
|
||||
.unwrap_or(0)
|
||||
));
|
||||
let source = r#"# main
|
||||
|
||||
`a` =
|
||||
```node
|
||||
throw new Error("boom");
|
||||
```
|
||||
|
||||
`b` =
|
||||
```node
|
||||
console.log("after error");
|
||||
```
|
||||
"#;
|
||||
std::fs::write(&path, source).unwrap();
|
||||
let mut s = DocumentSession::open(&path, &root).unwrap();
|
||||
let summary = s.run_all(false).unwrap();
|
||||
let records = match &summary {
|
||||
Value::Map(entries) => entries.iter().find(|(k, _)| k == "records").map(|(_, v)| v.clone()),
|
||||
_ => None,
|
||||
};
|
||||
let Some(Value::List(records)) = records else { panic!("no records") };
|
||||
assert_eq!(records.len(), 2);
|
||||
assert_eq!(field(&records[0], "ok"), Some(Value::Bool(false)));
|
||||
assert_eq!(field(&records[1], "ok"), Some(Value::Bool(true)));
|
||||
assert!(field(&records[1], "stdout")
|
||||
.and_then(|v| v.reveal_text().map(|s| s.to_string()))
|
||||
.unwrap_or_default()
|
||||
.contains("after error"));
|
||||
s.close();
|
||||
let _ = std::fs::remove_file(&path);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn reload_marks_changed_cell_dirty() {
|
||||
if !node_available() {
|
||||
@@ -15,6 +15,8 @@ pub mod event_bus;
|
||||
#[cfg(feature = "exec-host")]
|
||||
pub mod foreign;
|
||||
#[cfg(feature = "exec-host")]
|
||||
pub mod foreign_doc;
|
||||
#[cfg(feature = "exec-host")]
|
||||
pub mod foreign_session;
|
||||
mod fs;
|
||||
mod hash;
|
||||
|
||||
+148
@@ -208,6 +208,7 @@ impl Interpreter {
|
||||
call_id,
|
||||
fn_name: fun.name.clone(),
|
||||
fn_line: fun.span.line,
|
||||
call_line: self.current_span.line,
|
||||
ordinal,
|
||||
args_brief,
|
||||
});
|
||||
@@ -372,6 +373,98 @@ impl Interpreter {
|
||||
result
|
||||
}
|
||||
|
||||
/// Evaluate only the entry object's top-level assignments, without running
|
||||
/// calls/returns/control flow. This is the view plan's language-native
|
||||
/// projection: cell tables are ordinary Marqdo values, not source scans.
|
||||
/// Evaluate selected entry bindings plus their assignment dependencies.
|
||||
/// This is the view plan's language-native projection: cell tables are
|
||||
/// ordinary Marqdo values, not source scans.
|
||||
pub fn capture_declarations(
|
||||
&mut self,
|
||||
module: &Module,
|
||||
names: &[&str],
|
||||
) -> Result<std::collections::HashMap<String, Value>> {
|
||||
let prev = self.site_module;
|
||||
self.site_module = Some(module as *const Module);
|
||||
let result = (|| {
|
||||
let entry = find_top(module, "main").or_else(|| {
|
||||
let entries: Vec<&Function> = module
|
||||
.functions
|
||||
.iter()
|
||||
.filter(|f| f.is_object() && f.params.is_empty())
|
||||
.collect();
|
||||
if entries.len() == 1 {
|
||||
Some(entries[0])
|
||||
} else {
|
||||
None
|
||||
}
|
||||
});
|
||||
let entry = entry.ok_or_else(|| self.err("no `# main` object to inspect"))?;
|
||||
let assignments: std::collections::HashMap<&str, &Expr> = entry
|
||||
.body
|
||||
.iter()
|
||||
.filter_map(|stmt| match stmt {
|
||||
Stmt::Assign { name, value, .. } => Some((name.as_str(), value)),
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
let mut env = Env::with_metadata(module);
|
||||
let mut done = std::collections::HashSet::new();
|
||||
let mut visiting = std::collections::HashSet::new();
|
||||
|
||||
fn resolve(
|
||||
this: &mut Interpreter,
|
||||
module: &Module,
|
||||
fun: &Function,
|
||||
assignments: &std::collections::HashMap<&str, &Expr>,
|
||||
name: &str,
|
||||
env: &mut Env,
|
||||
done: &mut std::collections::HashSet<String>,
|
||||
visiting: &mut std::collections::HashSet<String>,
|
||||
) -> Result<()> {
|
||||
if done.contains(name) {
|
||||
return Ok(());
|
||||
}
|
||||
if !visiting.insert(name.to_string()) {
|
||||
return Err(this.err(format!("cyclic view-plan binding `{name}`")));
|
||||
}
|
||||
let Some(expr) = assignments.get(name) else {
|
||||
visiting.remove(name);
|
||||
return Ok(());
|
||||
};
|
||||
let mut deps = std::collections::HashSet::new();
|
||||
collect_decl_reads(expr, &mut deps);
|
||||
for dep in deps {
|
||||
if assignments.contains_key(dep.as_str()) && env.get(&dep).is_none() {
|
||||
resolve(this, module, fun, assignments, &dep, env, done, visiting)?;
|
||||
}
|
||||
}
|
||||
let value = this.eval_expr(module, fun, env, expr)?;
|
||||
env.set(name.to_string(), value);
|
||||
done.insert(name.to_string());
|
||||
visiting.remove(name);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
for name in names {
|
||||
resolve(
|
||||
self,
|
||||
module,
|
||||
entry,
|
||||
&assignments,
|
||||
name,
|
||||
&mut env,
|
||||
&mut done,
|
||||
&mut visiting,
|
||||
)?;
|
||||
}
|
||||
self.entry_bindings = env.vars_clone();
|
||||
Ok(self.entry_bindings.clone())
|
||||
})();
|
||||
self.site_module = prev;
|
||||
result
|
||||
}
|
||||
|
||||
pub fn run_module(&mut self, module: &Module) -> Result<Value> {
|
||||
let prev = self.site_module;
|
||||
self.site_module = Some(module as *const Module);
|
||||
@@ -1557,6 +1650,61 @@ fn bind_args(
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
fn collect_decl_reads(expr: &Expr, out: &mut std::collections::HashSet<String>) {
|
||||
match expr {
|
||||
Expr::Var(name) => {
|
||||
out.insert(name.clone());
|
||||
}
|
||||
Expr::Interp(parts) => {
|
||||
for part in parts {
|
||||
match part {
|
||||
InterpPart::Var(name) => {
|
||||
out.insert(name.clone());
|
||||
}
|
||||
InterpPart::Index { base, .. } => {
|
||||
out.insert(base.clone());
|
||||
}
|
||||
InterpPart::Lit(_) => {}
|
||||
}
|
||||
}
|
||||
}
|
||||
Expr::Index { base, label } => {
|
||||
collect_decl_reads(base, out);
|
||||
if let IndexKey::Var(name) = label {
|
||||
out.insert(name.clone());
|
||||
}
|
||||
}
|
||||
Expr::Binary { left, right, .. } => {
|
||||
collect_decl_reads(left, out);
|
||||
collect_decl_reads(right, out);
|
||||
}
|
||||
Expr::Unary { expr, .. } => collect_decl_reads(expr, out),
|
||||
Expr::List(xs) => {
|
||||
for x in xs {
|
||||
collect_decl_reads(x, out);
|
||||
}
|
||||
}
|
||||
Expr::Map(entries) => {
|
||||
for (_, v) in entries {
|
||||
collect_decl_reads(v, out);
|
||||
}
|
||||
}
|
||||
Expr::Call(call) => {
|
||||
if let Some(receiver) = &call.receiver {
|
||||
out.insert(receiver.clone());
|
||||
}
|
||||
for arg in &call.args {
|
||||
match arg {
|
||||
Arg::Positional(e) | Arg::Named { value: e, .. } => {
|
||||
collect_decl_reads(e, out);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Expr::Literal(_) | Expr::Formula(_) | Expr::Code(_) => {}
|
||||
}
|
||||
}
|
||||
|
||||
fn find_top<'a>(module: &'a Module, name: &str) -> Option<&'a Function> {
|
||||
module.functions.iter().find(|f| f.name == name)
|
||||
}
|
||||
|
||||
@@ -34,8 +34,6 @@ pub mod lex;
|
||||
pub mod linalg_ops;
|
||||
pub mod load;
|
||||
pub mod mlsp;
|
||||
#[cfg(feature = "exec-host")]
|
||||
pub mod notebook;
|
||||
pub mod parse;
|
||||
pub mod repair;
|
||||
pub mod value;
|
||||
|
||||
+15
-2
@@ -205,9 +205,22 @@ pub fn build_view_annots(module: &Module, source: &str, cap: &RunCapture) -> Vec
|
||||
last_ret.insert((ev.line, ev.call_id, ev.loop_id, ev.iter), ev);
|
||||
}
|
||||
}
|
||||
let call_sites: HashMap<u32, u32> = cap
|
||||
.view_trace
|
||||
.calls
|
||||
.iter()
|
||||
.map(|fr| (fr.call_id, fr.call_line))
|
||||
.collect();
|
||||
for ((line, _, _, _), ev) in last_ret {
|
||||
// Return events from an imported library carry the callee's line
|
||||
// number. Anchor the chip at the caller's line instead.
|
||||
let anchor_line = call_sites
|
||||
.get(&ev.call_id)
|
||||
.copied()
|
||||
.filter(|l| *l > 0)
|
||||
.unwrap_or(line);
|
||||
let text = lines
|
||||
.get(line.saturating_sub(1) as usize)
|
||||
.get(anchor_line.saturating_sub(1) as usize)
|
||||
.copied()
|
||||
.unwrap_or("");
|
||||
let mut start = None;
|
||||
@@ -222,7 +235,7 @@ pub fn build_view_annots(module: &Module, source: &str, cap: &RunCapture) -> Vec
|
||||
out.push(ViewAnnot {
|
||||
id: next_id("r"),
|
||||
kind: AnnotKind::Return,
|
||||
anchor_line: line,
|
||||
anchor_line,
|
||||
anchor_byte_start: start,
|
||||
anchor_byte_end: end,
|
||||
label: "return".into(),
|
||||
|
||||
+18
-5
@@ -101,11 +101,18 @@ pub fn render_module_document(module: &Module, source: &str, annots: &[ViewAnnot
|
||||
}
|
||||
LineKind::Writeback => {
|
||||
flush_para(&mut para, &mut out);
|
||||
let start_line = l.line_no;
|
||||
let mut block = String::new();
|
||||
while i < lines.len() && matches!(lines[i].kind, LineKind::Writeback) {
|
||||
if !block.is_empty() {
|
||||
block.push('\n');
|
||||
}
|
||||
block.push_str(lines[i].text.trim_end_matches(['\r', '\n']));
|
||||
i += 1;
|
||||
}
|
||||
out.push_str(&crate::view::render::render_writeback_source_line(
|
||||
l.line_no,
|
||||
l.text.trim_end_matches(['\r', '\n']),
|
||||
start_line, &block,
|
||||
));
|
||||
i += 1;
|
||||
}
|
||||
LineKind::Comment => {
|
||||
let text = l.text.trim_end_matches(['\r', '\n']);
|
||||
@@ -335,8 +342,14 @@ fn render_table_block(
|
||||
html.push_str("</table>");
|
||||
// Annots on first table line (bind of collection).
|
||||
if let Some(list) = by_line.get(&first_line) {
|
||||
if !list.is_empty() {
|
||||
let owned: Vec<ViewAnnot> = list.iter().map(|a| (*a).clone()).collect();
|
||||
// A table is already its own readable value; a call chip would collapse
|
||||
// the whole collection into an ellipsis. Keep only non-call chips.
|
||||
let owned: Vec<ViewAnnot> = list
|
||||
.iter()
|
||||
.filter(|a| a.kind != crate::view::annot::AnnotKind::Call)
|
||||
.map(|a| (*a).clone())
|
||||
.collect();
|
||||
if !owned.is_empty() {
|
||||
html.push_str(&render_annot_band(&owned, MAX_VISIBLE_ANNOTS));
|
||||
}
|
||||
}
|
||||
|
||||
+294
-56
@@ -625,6 +625,24 @@ ul.doc-loop, ol.doc-branch {
|
||||
border-radius: 10px;
|
||||
border: 1px solid transparent;
|
||||
}
|
||||
.exec-clear {
|
||||
float: right;
|
||||
font: inherit;
|
||||
font-size: 0.72rem;
|
||||
padding: 0.2rem 0.6rem;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 999px;
|
||||
background: var(--surface);
|
||||
color: var(--muted);
|
||||
cursor: pointer;
|
||||
}
|
||||
.exec-clear:hover { color: var(--ink); border-color: var(--muted); }
|
||||
body.notebook-page .exec-clear {
|
||||
border-color: var(--nb-border);
|
||||
background: var(--nb-surface-2);
|
||||
color: var(--nb-text);
|
||||
}
|
||||
body.notebook-page .exec-clear:hover { border-color: var(--nb-accent); color: var(--nb-strong); }
|
||||
.out, .source {
|
||||
font-family: var(--mono);
|
||||
font-size: 0.82rem;
|
||||
@@ -1021,20 +1039,18 @@ ul.doc-loop, ol.doc-branch {
|
||||
}
|
||||
.doc-writeback {
|
||||
margin: 0.35rem 0;
|
||||
padding: 0.4rem 0.55rem;
|
||||
padding: 0.45rem 0.6rem;
|
||||
border-radius: 8px;
|
||||
border: 1px dashed #94a3b8;
|
||||
background: #f1f5f9;
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 0.4rem 0.65rem;
|
||||
align-items: baseline;
|
||||
}
|
||||
.doc-writeback[data-wb-kind="image"] {
|
||||
border-color: #0d9488;
|
||||
background: #f0fdfa;
|
||||
}
|
||||
.wb-source-badge {
|
||||
display: inline-block;
|
||||
margin-bottom: 0.28rem;
|
||||
font: 0.68rem/1.2 var(--sans);
|
||||
letter-spacing: 0.04em;
|
||||
text-transform: uppercase;
|
||||
@@ -1048,10 +1064,11 @@ ul.doc-loop, ol.doc-branch {
|
||||
color: #115e59;
|
||||
}
|
||||
.wb-source-text {
|
||||
display: block;
|
||||
font: 0.82rem/1.4 var(--mono);
|
||||
color: #0f172a;
|
||||
white-space: pre-wrap;
|
||||
word-break: break-all;
|
||||
word-break: break-word;
|
||||
}
|
||||
.wb-outline {
|
||||
margin-top: 0.75rem;
|
||||
@@ -1645,15 +1662,7 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
|
||||
var body = card.querySelector(".code-body code");
|
||||
// Narrative ```text``` cards have no Run chrome — leave as-is.
|
||||
if (!btn) return;
|
||||
if (!live) {{
|
||||
// Static: hide fake Run (view-static-interactive D5 / view-prose-annot-gaps P4).
|
||||
if (foot) foot.hidden = true;
|
||||
else {{
|
||||
btn.hidden = true;
|
||||
if (cmd) cmd.hidden = true;
|
||||
}}
|
||||
return;
|
||||
}}
|
||||
if (!live) return; // static actions are bound to the view-shell notice
|
||||
if (!out || !body) return;
|
||||
btn.addEventListener("click", function () {{
|
||||
btn.disabled = true;
|
||||
@@ -3050,6 +3059,33 @@ body.notebook-page #notebook-bar strong {
|
||||
color: var(--nb-strong);
|
||||
font: 600 0.76rem/1.6 var(--sans);
|
||||
}
|
||||
body.notebook-page .nb-stdin-bar {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.55rem;
|
||||
margin: 0 0 0.75rem;
|
||||
padding: 0.4rem 0.55rem;
|
||||
border: 1px solid var(--nb-border);
|
||||
border-radius: var(--nb-radius);
|
||||
background: var(--nb-surface);
|
||||
}
|
||||
body.notebook-page .nb-stdin-bar label {
|
||||
color: var(--nb-muted);
|
||||
font: 0.7rem/1.2 var(--mono);
|
||||
white-space: nowrap;
|
||||
}
|
||||
body.notebook-page .nb-stdin-bar textarea {
|
||||
flex: 1;
|
||||
min-height: 2.1rem;
|
||||
max-height: 7rem;
|
||||
resize: vertical;
|
||||
border: 1px solid var(--nb-border);
|
||||
border-radius: 6px;
|
||||
padding: 0.3rem 0.5rem;
|
||||
background: var(--nb-bg);
|
||||
color: var(--nb-text);
|
||||
font: 0.72rem/1.35 var(--mono);
|
||||
}
|
||||
body.notebook-page #notebook-bar button {
|
||||
appearance: none;
|
||||
padding: 0.34rem 0.58rem;
|
||||
@@ -3233,16 +3269,6 @@ body.notebook-page .code-head {
|
||||
background: var(--nb-surface-2);
|
||||
}
|
||||
body.notebook-page .code-head .badge { display: none; }
|
||||
body.notebook-page .nb-prompt {
|
||||
order: 0;
|
||||
min-width: 3.2rem;
|
||||
padding-right: 0.5rem;
|
||||
border-right: 1px solid var(--nb-border);
|
||||
color: var(--nb-muted);
|
||||
font: 0.66rem/1.3 var(--mono);
|
||||
text-align: right;
|
||||
white-space: nowrap;
|
||||
}
|
||||
body.notebook-page .code-name {
|
||||
order: 1;
|
||||
color: var(--nb-strong);
|
||||
@@ -3264,8 +3290,22 @@ body.notebook-page .code-head .nb-kernel {
|
||||
font: 0.66rem/1.2 var(--sans);
|
||||
cursor: pointer;
|
||||
}
|
||||
body.notebook-page .code-head .nb-badge {
|
||||
body.notebook-page .code-head .nb-clean {
|
||||
order: 4;
|
||||
padding: 0.14rem 0.4rem;
|
||||
border: 1px solid var(--nb-border);
|
||||
border-radius: 3px;
|
||||
background: var(--nb-bg);
|
||||
color: var(--nb-muted);
|
||||
font: 0.62rem/1.2 var(--sans);
|
||||
cursor: pointer;
|
||||
}
|
||||
body.notebook-page .code-head .nb-clean:hover {
|
||||
border-color: var(--nb-accent);
|
||||
color: var(--nb-strong);
|
||||
}
|
||||
body.notebook-page .code-head .nb-badge {
|
||||
order: 5;
|
||||
padding: 0.14rem 0.34rem;
|
||||
border: 1px solid var(--nb-border);
|
||||
border-radius: 3px;
|
||||
@@ -3277,7 +3317,7 @@ body.notebook-page .code-head .nb-badge {
|
||||
body.notebook-page .nb-badge.ok { color: var(--nb-success); }
|
||||
body.notebook-page .nb-badge.bad { color: var(--nb-error); }
|
||||
body.notebook-page .code-head .code-actions {
|
||||
order: 5;
|
||||
order: 6;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.3rem;
|
||||
@@ -3350,7 +3390,7 @@ body.notebook-page .code-out {
|
||||
word-break: break-word;
|
||||
}
|
||||
body.notebook-page .code-out::before {
|
||||
content: "Out [ ]";
|
||||
content: "Output";
|
||||
display: block;
|
||||
margin-bottom: 0.38rem;
|
||||
color: var(--nb-muted);
|
||||
@@ -3457,6 +3497,34 @@ body.notebook-page .stdin-form button {
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
body.notebook-page .output-card {
|
||||
background: var(--nb-surface-2);
|
||||
border-left-color: var(--nb-accent);
|
||||
}
|
||||
body.notebook-page .output-card.output-card-image { border-left-color: var(--nb-success); }
|
||||
body.notebook-page .output-card .wb-badges { color: var(--nb-muted); }
|
||||
body.notebook-page .output-card .output-body {
|
||||
color: var(--nb-text);
|
||||
background: var(--nb-bg);
|
||||
}
|
||||
body.notebook-page .wb-badge {
|
||||
background: var(--nb-surface-3);
|
||||
color: var(--nb-text);
|
||||
border-color: var(--nb-border);
|
||||
}
|
||||
body.notebook-page .wb-badge.wb-ok { background: #143d2b; color: #86efac; }
|
||||
body.notebook-page .wb-badge.wb-error { background: #4a1d1d; color: #fca5a5; }
|
||||
body.notebook-page .wb-badge.wb-trace { background: #2e2a5a; color: #c7d2fe; }
|
||||
body.notebook-page .doc-writeback {
|
||||
background: var(--nb-surface-2);
|
||||
border-color: var(--nb-border);
|
||||
}
|
||||
body.notebook-page .wb-source-badge {
|
||||
background: var(--nb-surface-3);
|
||||
color: var(--nb-muted);
|
||||
}
|
||||
body.notebook-page .wb-source-text { color: var(--nb-text); }
|
||||
|
||||
/* ── Narrow preview panes ──────────────────────────────────────────── */
|
||||
@media (max-width: 760px) {
|
||||
body.notebook-page main.panel { padding: 1rem 0.75rem 3.5rem; }
|
||||
@@ -3470,17 +3538,22 @@ body.notebook-page .stdin-form button {
|
||||
}
|
||||
</style>
|
||||
<div class="notebook-bar" id="notebook-bar" hidden>
|
||||
<strong>Notebook</strong>
|
||||
<strong>View</strong>
|
||||
<button type="button" id="nb-run-all">Run All</button>
|
||||
<button type="button" id="nb-restart">Restart & Run All</button>
|
||||
<button type="button" id="nb-step">Step</button>
|
||||
<button type="button" id="nb-state">State</button>
|
||||
<button type="button" id="nb-journal">Journal</button>
|
||||
<button type="button" id="nb-clear">Clear outputs</button>
|
||||
<button type="button" id="nb-reload">Reload</button>
|
||||
<button type="button" id="nb-debug">Debug</button>
|
||||
<button type="button" id="nb-theme" title="切换浅色/深色主题">浅色</button>
|
||||
<span id="nb-status">opening…</span>
|
||||
</div>
|
||||
<div class="nb-stdin-bar" id="nb-stdin-bar">
|
||||
<label for="nb-stdin">Cell stdin / input</label>
|
||||
<textarea id="nb-stdin" rows="1" placeholder="raw stdin for stateless cells; JSON/string for persistent kernels" spellcheck="false"></textarea>
|
||||
</div>
|
||||
<div class="notebook-bar" id="nb-state-actions" hidden>
|
||||
<span>Bridge</span>
|
||||
<input id="nb-kernel-input" placeholder="kernel" autocomplete="off"/>
|
||||
@@ -3508,10 +3581,10 @@ body.notebook-page .stdin-form button {
|
||||
var savedTheme = "dark";
|
||||
try { savedTheme = localStorage.getItem(THEME_KEY) || "dark"; } catch (e) {}
|
||||
applyTheme(savedTheme);
|
||||
if (!window.MARQDO_VIEW_LIVE) return;
|
||||
var live = !!window.MARQDO_VIEW_LIVE;
|
||||
var path = window.MARQDO_FILE_PATH || "";
|
||||
if (!path) return;
|
||||
var state = { open: false, kernels: [], cells: {} };
|
||||
var state = { open: false, persistent: false, kernels: [], cells: {} };
|
||||
function post(url, body) {
|
||||
return fetch(url, {
|
||||
method: "POST",
|
||||
@@ -3520,6 +3593,10 @@ body.notebook-page .stdin-form button {
|
||||
}).then(function (r) { return r.json(); });
|
||||
}
|
||||
function status(t) { var e = document.getElementById("nb-status"); if (e) e.textContent = t; }
|
||||
function cellStdin() {
|
||||
var el = document.getElementById("nb-stdin");
|
||||
return el ? el.value : "";
|
||||
}
|
||||
function card(name) {
|
||||
var els = document.querySelectorAll(".code-card");
|
||||
for (var i = 0; i < els.length; i++) {
|
||||
@@ -3539,6 +3616,57 @@ body.notebook-page .stdin-form button {
|
||||
b.textContent = text;
|
||||
b.className = "nb-badge " + (ok ? "ok" : (text === "clean" || text === "never" ? "" : "bad"));
|
||||
}
|
||||
function ensureKernel(el, persistent) {
|
||||
var sel = el.querySelector(".nb-kernel");
|
||||
if (!sel) {
|
||||
sel = document.createElement("select");
|
||||
sel.className = "nb-kernel";
|
||||
var head = el.querySelector(".code-head");
|
||||
if (head) head.appendChild(sel);
|
||||
}
|
||||
if (!persistent) {
|
||||
sel.disabled = true;
|
||||
sel.title = "No live kernel; this cell is stateless";
|
||||
sel.innerHTML = "";
|
||||
var opt = document.createElement("option");
|
||||
opt.textContent = "one-shot";
|
||||
sel.appendChild(opt);
|
||||
} else {
|
||||
sel.disabled = false;
|
||||
sel.title = "Switch kernel";
|
||||
}
|
||||
return sel;
|
||||
}
|
||||
function clearCard(el) {
|
||||
var out = el.querySelector(".code-out");
|
||||
if (out) {
|
||||
out.hidden = true;
|
||||
out.textContent = "";
|
||||
out.classList.remove("err");
|
||||
}
|
||||
var b = el.querySelector(".nb-badge");
|
||||
if (b) { b.textContent = "never"; b.className = "nb-badge"; }
|
||||
}
|
||||
function bindClean(el) {
|
||||
var btn = el.querySelector(".nb-clean");
|
||||
if (!btn || btn.dataset.bound) return;
|
||||
btn.dataset.bound = "1";
|
||||
btn.addEventListener("click", function (e) {
|
||||
e.preventDefault();
|
||||
var name = el.getAttribute("data-code-name") || "";
|
||||
if (!live) {
|
||||
clearCard(el);
|
||||
status("static export: local output cleared");
|
||||
return;
|
||||
}
|
||||
if (!name) return;
|
||||
post("api/session/cell/clear", { cell: name }).then(function (r) {
|
||||
clearCard(el);
|
||||
if (r.ok && r.session) renderSummary(r.session);
|
||||
status(r.ok ? "clean" : (r.error || "clean failed"));
|
||||
}).catch(function (e2) { status(String(e2)); });
|
||||
});
|
||||
}
|
||||
function renderRecord(name, rec) {
|
||||
var el = card(name);
|
||||
if (!el || !rec) return;
|
||||
@@ -3562,27 +3690,18 @@ body.notebook-page .stdin-form button {
|
||||
}
|
||||
function renderSummary(s) {
|
||||
if (!s) return;
|
||||
state.persistent = !!s.persistent;
|
||||
state.kernels = s.kernels || [];
|
||||
state.cells = {};
|
||||
(s.cells || []).forEach(function (c) { state.cells[c.name] = c; });
|
||||
(s.cells || []).forEach(function (c) {
|
||||
var el = card(c.name);
|
||||
if (!el) return;
|
||||
var head0 = el.querySelector(".code-head");
|
||||
var prompt = el.querySelector(".nb-prompt");
|
||||
if (!prompt && head0) {
|
||||
prompt = document.createElement("span");
|
||||
prompt.className = "nb-prompt";
|
||||
head0.insertBefore(prompt, head0.firstChild);
|
||||
}
|
||||
if (prompt) prompt.textContent = "In [" + (c.runs ? c.runs : " ") + "]";
|
||||
badge(el, c.status, c.status === "clean");
|
||||
var sel = el.querySelector(".nb-kernel");
|
||||
if (!sel) {
|
||||
sel = document.createElement("select");
|
||||
sel.className = "nb-kernel";
|
||||
var head = el.querySelector(".code-head");
|
||||
if (head) head.appendChild(sel);
|
||||
var sel = ensureKernel(el, state.persistent);
|
||||
if (!state.persistent) return;
|
||||
if (!sel.dataset.bound) {
|
||||
sel.dataset.bound = "1";
|
||||
sel.addEventListener("change", function () {
|
||||
post("api/session/kernel/assign", { cell: c.name, kernel: sel.value }).then(function (r) {
|
||||
status(r.ok ? "kernel: " + sel.value : (r.error || "assign failed"));
|
||||
@@ -3600,6 +3719,34 @@ body.notebook-page .stdin-form button {
|
||||
});
|
||||
});
|
||||
}
|
||||
function renderStaticSummary(s) {
|
||||
if (!s) return;
|
||||
state.persistent = !!s.persistent;
|
||||
state.kernels = s.kernels || [];
|
||||
state.cells = {};
|
||||
(s.cells || []).forEach(function (c) { state.cells[c.name] = c; });
|
||||
(s.cells || []).forEach(function (c) {
|
||||
var el = card(c.name);
|
||||
if (!el) return;
|
||||
badge(el, c.status, c.status === "clean");
|
||||
if (!state.persistent) {
|
||||
ensureKernel(el, false);
|
||||
return;
|
||||
}
|
||||
var sel = ensureKernel(el, true);
|
||||
var opts = state.kernels.filter(function (k) { return k.lang === c.lang; }).map(function (k) { return k.name; });
|
||||
if (!opts.length) opts = [c.kernel];
|
||||
sel.innerHTML = "";
|
||||
opts.forEach(function (n) {
|
||||
var o = document.createElement("option");
|
||||
o.value = n; o.textContent = n;
|
||||
if (n === c.kernel) o.selected = true;
|
||||
sel.appendChild(o);
|
||||
});
|
||||
sel.disabled = true;
|
||||
sel.title = "Static export: kernel fixed to " + c.kernel;
|
||||
});
|
||||
}
|
||||
function openSession() {
|
||||
var bar = document.getElementById("notebook-bar");
|
||||
if (bar) bar.hidden = false;
|
||||
@@ -3611,14 +3758,31 @@ body.notebook-page .stdin-form button {
|
||||
});
|
||||
}
|
||||
function runOne(name) {
|
||||
return post("api/session/cell/run", { cell: name }).then(function (r) {
|
||||
return post("api/session/cell/run", { cell: name, stdin: cellStdin() }).then(function (r) {
|
||||
if (r.ok) { renderRecord(name, r.record); if (r.session) renderSummary(r.session); }
|
||||
else status(r.error || "run failed");
|
||||
});
|
||||
}
|
||||
function renderDocumentResult(data) {
|
||||
var out = document.getElementById("exec-main");
|
||||
if (out) {
|
||||
out.hidden = false;
|
||||
out.classList.toggle("err", !data.ok);
|
||||
out.textContent = data.ok ? (data.stdout || "(no output)") : (data.error || "run failed");
|
||||
}
|
||||
var block = document.getElementById("exec-block");
|
||||
if (block) block.hidden = false;
|
||||
}
|
||||
function runAll(restart) {
|
||||
status(restart ? "restarting…" : "running all…");
|
||||
post("api/session/run_all", { restart: !!restart }).then(function (r) {
|
||||
if (!state.persistent && Object.keys(state.cells).length === 0) {
|
||||
post("api/session/run_document", {}).then(function (r) {
|
||||
renderDocumentResult(r);
|
||||
status(r.ok ? "document run done" : (r.error || "document run failed"));
|
||||
}).catch(function (e) { status(String(e)); });
|
||||
return;
|
||||
}
|
||||
post("api/session/run_all", { restart: !!restart, stdin: cellStdin() }).then(function (r) {
|
||||
if (!r.ok) { status(r.error || "run all failed"); return; }
|
||||
if (r.session) renderSummary(r.session);
|
||||
var recs = (r.summary && r.summary.records) || [];
|
||||
@@ -3626,6 +3790,37 @@ body.notebook-page .stdin-form button {
|
||||
status("run all done");
|
||||
});
|
||||
}
|
||||
function clearDom() {
|
||||
document.querySelectorAll(".code-out").forEach(function (el) {
|
||||
el.hidden = true;
|
||||
el.textContent = "";
|
||||
el.classList.remove("err");
|
||||
});
|
||||
document.querySelectorAll(".nb-badge").forEach(function (el) {
|
||||
el.textContent = "never";
|
||||
el.className = "nb-badge";
|
||||
});
|
||||
var exec = document.getElementById("exec-main");
|
||||
if (exec) { exec.hidden = true; exec.textContent = ""; }
|
||||
var execBlock = document.getElementById("exec-block");
|
||||
if (execBlock) {
|
||||
execBlock.querySelectorAll(".plots, .plan-card").forEach(function (el) {
|
||||
el.hidden = true;
|
||||
el.innerHTML = "";
|
||||
});
|
||||
}
|
||||
var stateOut = document.getElementById("nb-state-out");
|
||||
if (stateOut) { stateOut.hidden = true; stateOut.textContent = ""; }
|
||||
var pullOut = document.getElementById("nb-pull-out");
|
||||
if (pullOut) pullOut.textContent = "";
|
||||
}
|
||||
function clearOutputs() {
|
||||
clearDom();
|
||||
post("api/session/clear", {}).then(function (r) {
|
||||
if (r.ok && r.session) renderSummary(r.session);
|
||||
status(r.ok ? "outputs cleared" : (r.error || "clear failed"));
|
||||
}).catch(function (e) { status(String(e)); });
|
||||
}
|
||||
function bind(id, fn) { var b = document.getElementById(id); if (b) b.addEventListener("click", fn); }
|
||||
function init() {
|
||||
var themeBtn = document.getElementById("nb-theme");
|
||||
@@ -3646,10 +3841,44 @@ body.notebook-page .stdin-form button {
|
||||
foot.remove();
|
||||
}
|
||||
});
|
||||
if (!live) {
|
||||
var staticBar = document.getElementById("notebook-bar");
|
||||
if (staticBar) staticBar.hidden = false;
|
||||
var staticStdin = document.getElementById("nb-stdin-bar");
|
||||
if (staticStdin) staticStdin.hidden = false;
|
||||
function staticNotice() {
|
||||
status("静态页面无法真实执行 / static export: no live execution");
|
||||
}
|
||||
["nb-run-all", "nb-restart", "nb-step", "nb-state", "nb-journal",
|
||||
"nb-clear", "nb-reload", "nb-debug", "exec-clear"].forEach(function (id) {
|
||||
bind(id, staticNotice);
|
||||
});
|
||||
document.querySelectorAll(".code-run").forEach(function (btn) {
|
||||
btn.addEventListener("click", function (e) {
|
||||
e.preventDefault();
|
||||
staticNotice();
|
||||
});
|
||||
});
|
||||
if (window.MARQDO_STATIC_SESSION) {
|
||||
renderStaticSummary(window.MARQDO_STATIC_SESSION);
|
||||
} else {
|
||||
document.querySelectorAll(".code-card").forEach(function (el) {
|
||||
ensureKernel(el, false);
|
||||
});
|
||||
}
|
||||
document.querySelectorAll(".code-card").forEach(bindClean);
|
||||
status("static export · preview only");
|
||||
return;
|
||||
}
|
||||
document.querySelectorAll(".code-card").forEach(bindClean);
|
||||
bind("nb-run-all", function () { runAll(false); });
|
||||
bind("nb-restart", function () { runAll(true); });
|
||||
bind("nb-step", function () {
|
||||
post("api/session/cell/step", {}).then(function (r) {
|
||||
if (!state.persistent && Object.keys(state.cells).length === 0) {
|
||||
status("no cells; Run All runs the document");
|
||||
return;
|
||||
}
|
||||
post("api/session/cell/step", { stdin: cellStdin() }).then(function (r) {
|
||||
if (!r.ok) { status(r.error || "step failed"); return; }
|
||||
if (r.record) {
|
||||
if (r.record.cell) renderRecord(r.record.cell, r.record);
|
||||
@@ -3669,6 +3898,7 @@ body.notebook-page .stdin-form button {
|
||||
pre.textContent = JSON.stringify(r.state || r, null, 2);
|
||||
if (actions) actions.hidden = false;
|
||||
if (ki && !ki.value && state.kernels.length) ki.value = state.kernels[0].name;
|
||||
if (!state.persistent) status("stateless: no kernel state");
|
||||
});
|
||||
});
|
||||
bind("nb-push", function () {
|
||||
@@ -3700,11 +3930,14 @@ body.notebook-page .stdin-form button {
|
||||
if (!pre) return;
|
||||
pre.hidden = false;
|
||||
pre.textContent = JSON.stringify(r.journal || r, null, 2);
|
||||
if (!state.persistent) status("stateless: journal is per one-shot run");
|
||||
});
|
||||
});
|
||||
bind("nb-debug", function () {
|
||||
window.open("debug?path=" + encodeURIComponent(path), "_blank");
|
||||
});
|
||||
bind("nb-clear", clearOutputs);
|
||||
bind("exec-clear", clearOutputs);
|
||||
bind("nb-reload", function () {
|
||||
post("api/session/reload", {}).then(function (r) {
|
||||
if (!r.ok) { status(r.error || "reload failed"); return; }
|
||||
@@ -3832,6 +4065,7 @@ pub fn page_file(files: &[PathBuf], rel: &str, vm: &FileViewModel, links: &LinkM
|
||||
LinkMode::Live => "true",
|
||||
LinkMode::Static { .. } => "false",
|
||||
};
|
||||
let exec_clear = r#"<button type="button" class="exec-clear" id="exec-clear">Clear</button>"#;
|
||||
let outline_block = if vm.outline_html.is_empty() {
|
||||
String::new()
|
||||
} else {
|
||||
@@ -3872,11 +4106,9 @@ pub fn page_file(files: &[PathBuf], rel: &str, vm: &FileViewModel, links: &LinkM
|
||||
let trace_safe = vm
|
||||
.trace_json
|
||||
.replace("</", "<\\/");
|
||||
let notebook = if matches!(links, LinkMode::Live) {
|
||||
notebook_ui().to_string()
|
||||
} else {
|
||||
String::new()
|
||||
};
|
||||
// Static exports share the same view shell. The script sees
|
||||
// MARQDO_VIEW_LIVE=false and leaves the interactive controls hidden.
|
||||
let notebook = notebook_ui().to_string();
|
||||
let main = format!(
|
||||
r#"
|
||||
<script>
|
||||
@@ -3892,12 +4124,12 @@ window.MARQDO_AUTO_STREAM = {auto_stream};
|
||||
<h2>Structure</h2>
|
||||
{structure_block}
|
||||
</section>
|
||||
<section class="block exec-block">
|
||||
<h2>Execution</h2>
|
||||
<section class="block exec-block" id="exec-block">
|
||||
<h2>Execution {exec_clear}</h2>
|
||||
{stdin_panel}
|
||||
{stream_panel}
|
||||
{plan_card}
|
||||
<div class="out {status}">{out}</div>
|
||||
<div class="out {status}" id="exec-main">{out}</div>
|
||||
{plots}
|
||||
</section>
|
||||
<section class="block source-block">
|
||||
@@ -3918,6 +4150,7 @@ window.MARQDO_AUTO_STREAM = {auto_stream};
|
||||
status_label = status_label,
|
||||
rel = escape(rel),
|
||||
notebook = notebook,
|
||||
exec_clear = exec_clear,
|
||||
structure_block = structure_block,
|
||||
stdin_panel = stdin_panel,
|
||||
stream_panel = stream_panel,
|
||||
@@ -4140,5 +4373,10 @@ mod tests {
|
||||
"notebook API URLs must stay relative for path-prefix proxy"
|
||||
);
|
||||
assert!(ui.contains("post(\"api/session/open\""));
|
||||
assert!(!ui.contains("In ["), "view cells must not mimic Jupyter In[] prompts");
|
||||
assert!(!ui.contains("Out ["), "view cells must not mimic Jupyter Out[] prompts");
|
||||
assert!(ui.contains("id=\"nb-clear\""), "view must expose Clear outputs");
|
||||
assert!(ui.contains("api/session/clear"), "Clear outputs must call the session API");
|
||||
}
|
||||
|
||||
}
|
||||
@@ -189,6 +189,21 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
|
||||
notebook_api::api_close(&root.root, body)
|
||||
})
|
||||
}
|
||||
"/api/session/run_document" => {
|
||||
return api_debug_post(request, |body| {
|
||||
notebook_api::api_run_document(&root.root, body)
|
||||
})
|
||||
}
|
||||
"/api/session/cell/clear" => {
|
||||
return api_debug_post(request, |body| {
|
||||
notebook_api::api_clear_cell(&root.root, body)
|
||||
})
|
||||
}
|
||||
"/api/session/clear" => {
|
||||
return api_debug_post(request, |body| {
|
||||
notebook_api::api_clear(&root.root, body)
|
||||
})
|
||||
}
|
||||
"/api/session/cell/run" => {
|
||||
return api_debug_post(request, |body| {
|
||||
notebook_api::api_cell_run(&root.root, body)
|
||||
|
||||
@@ -5,7 +5,7 @@ use std::path::{Path, PathBuf};
|
||||
use std::sync::{Arc, Mutex, OnceLock};
|
||||
|
||||
use crate::host::json::{json_to_value, value_to_json};
|
||||
use crate::notebook::DocumentSession;
|
||||
use crate::host::foreign_doc::DocumentSession;
|
||||
use crate::value::Value;
|
||||
|
||||
fn sessions() -> &'static Mutex<HashMap<String, Arc<Mutex<DocumentSession>>>> {
|
||||
@@ -67,6 +67,25 @@ fn err(error: String) -> serde_json::Value {
|
||||
serde_json::json!({ "ok": false, "error": error })
|
||||
}
|
||||
|
||||
pub fn api_run_document(root: &Path, body: &str) -> serde_json::Value {
|
||||
let v = body_value(body);
|
||||
let (_rel, abs) = match path_of(root, &v) {
|
||||
Ok(p) => p,
|
||||
Err(e) => return err(e),
|
||||
};
|
||||
let mut opts = crate::RunOptions::default();
|
||||
opts.fs_root = Some(root.to_path_buf());
|
||||
opts.sleep_limit_ms = Some(30_000);
|
||||
match crate::run_file_capture(&abs, &opts) {
|
||||
Ok(cap) => serde_json::json!({
|
||||
"ok": true,
|
||||
"stdout": cap.stdout,
|
||||
"value": json_value(&cap.value),
|
||||
}),
|
||||
Err(e) => serde_json::json!({ "ok": false, "error": format!("{e:#}") }),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn api_open(root: &Path, body: &str) -> serde_json::Value {
|
||||
let v = body_value(body);
|
||||
let (_rel, abs) = match path_of(root, &v) {
|
||||
@@ -151,24 +170,41 @@ where
|
||||
}
|
||||
}
|
||||
|
||||
pub fn api_clear_cell(root: &Path, body: &str) -> serde_json::Value {
|
||||
let v = body_value(body);
|
||||
let cell = v.get("cell").and_then(|x| x.as_str()).unwrap_or("");
|
||||
if cell.is_empty() {
|
||||
return err("missing cell".into());
|
||||
}
|
||||
with_session(root, body, "cleared", |s| s.clear_cell(cell))
|
||||
}
|
||||
|
||||
pub fn api_clear(root: &Path, body: &str) -> serde_json::Value {
|
||||
with_session(root, body, "cleared", |s| Ok(s.clear_outputs()))
|
||||
}
|
||||
|
||||
pub fn api_cell_run(root: &Path, body: &str) -> serde_json::Value {
|
||||
let v = body_value(body);
|
||||
let cell = v.get("cell").and_then(|x| x.as_str()).unwrap_or("");
|
||||
let kernel = v.get("kernel").and_then(|x| x.as_str()).filter(|s| !s.is_empty());
|
||||
let stdin = v.get("stdin").and_then(|x| x.as_str());
|
||||
if cell.is_empty() {
|
||||
return err("missing cell".into());
|
||||
}
|
||||
with_session(root, body, "record", |s| s.run_cell(cell, kernel))
|
||||
with_session(root, body, "record", |s| s.run_cell_with_stdin(cell, kernel, stdin))
|
||||
}
|
||||
|
||||
pub fn api_cell_step(root: &Path, body: &str) -> serde_json::Value {
|
||||
with_session(root, body, "record", |s| s.step())
|
||||
let v = body_value(body);
|
||||
let stdin = v.get("stdin").and_then(|x| x.as_str());
|
||||
with_session(root, body, "record", |s| s.step_with_stdin(stdin))
|
||||
}
|
||||
|
||||
pub fn api_run_all(root: &Path, body: &str) -> serde_json::Value {
|
||||
let v = body_value(body);
|
||||
let restart = v.get("restart").and_then(|x| x.as_bool()).unwrap_or(false);
|
||||
with_session(root, body, "summary", |s| s.run_all(restart))
|
||||
let stdin = v.get("stdin").and_then(|x| x.as_str());
|
||||
with_session(root, body, "summary", |s| s.run_all_with_stdin(restart, stdin))
|
||||
}
|
||||
|
||||
pub fn api_kernel_restart(root: &Path, body: &str) -> serde_json::Value {
|
||||
@@ -281,6 +317,10 @@ mod tests {
|
||||
Some(false),
|
||||
"{failed:?}"
|
||||
);
|
||||
let clear = api_clear(&root, r#"{"path":"shared.mq.md"}"#);
|
||||
assert_eq!(clear.get("ok").and_then(|v| v.as_bool()), Some(true), "{clear:?}");
|
||||
let cleared = clear.get("session").and_then(|s| s.get("cells")).and_then(|c| c.as_array()).cloned().unwrap_or_default();
|
||||
assert!(cleared.iter().all(|c| c.get("runs").and_then(|v| v.as_u64()) == Some(0)));
|
||||
let push = api_state_push(
|
||||
&root,
|
||||
r#"{"path":"shared.mq.md","kernel":"分析","name":"z","value":9}"#,
|
||||
|
||||
+195
-7
@@ -1,11 +1,14 @@
|
||||
//! Static HTML export: `marqdo view output`.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::fs;
|
||||
use std::path::PathBuf;
|
||||
|
||||
use anyhow::{Context, Result};
|
||||
|
||||
use crate::view::html::{page_file, page_index, LinkMode};
|
||||
use crate::host::foreign_doc::DocumentSession;
|
||||
use crate::value::Value;
|
||||
use crate::view::html::{escape, page_file, page_index, LinkMode};
|
||||
use crate::view::{build_file_view, build_root, ViewRoot};
|
||||
|
||||
pub struct OutputOptions {
|
||||
@@ -14,6 +17,159 @@ pub struct OutputOptions {
|
||||
pub no_exec: bool,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
struct StaticCellOutput {
|
||||
ok: bool,
|
||||
text: String,
|
||||
}
|
||||
|
||||
fn value_text(v: &Value) -> Option<String> {
|
||||
match v {
|
||||
Value::Text(s) => Some(s.clone()),
|
||||
Value::None => None,
|
||||
_ => v.reveal_text().map(|s| s.to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
fn value_bool(v: &Value) -> Option<bool> {
|
||||
match v {
|
||||
Value::Bool(b) => Some(*b),
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
|
||||
fn record_field(record: &Value, key: &str) -> Option<Value> {
|
||||
match record {
|
||||
Value::Map(entries) => entries
|
||||
.iter()
|
||||
.find(|(k, _)| k == key)
|
||||
.map(|(_, v)| v.clone()),
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
|
||||
/// Run the document's cells at export time and keep their real outputs. This
|
||||
/// is what makes a static page show foreign results instead of just source.
|
||||
fn static_page_data(
|
||||
root: &ViewRoot,
|
||||
abs: &std::path::Path,
|
||||
stdin: &str,
|
||||
) -> (HashMap<String, StaticCellOutput>, Option<Value>) {
|
||||
let mut out = HashMap::new();
|
||||
let Ok(mut session) = DocumentSession::open(abs, &root.root) else {
|
||||
return (out, None);
|
||||
};
|
||||
let Ok(summary) = session.run_all_with_stdin(false, Some(stdin)) else {
|
||||
session.close();
|
||||
return (out, None);
|
||||
};
|
||||
let records = match &summary {
|
||||
Value::Map(entries) => entries
|
||||
.iter()
|
||||
.find(|(k, _)| k == "records")
|
||||
.map(|(_, v)| v.clone()),
|
||||
_ => None,
|
||||
};
|
||||
if let Some(Value::List(records)) = records {
|
||||
for rec in records {
|
||||
let Some(cell) = record_field(&rec, "cell").and_then(|v| value_text(&v)) else {
|
||||
continue;
|
||||
};
|
||||
let ok = record_field(&rec, "ok")
|
||||
.and_then(|v| value_bool(&v))
|
||||
.unwrap_or(false);
|
||||
let mut parts = Vec::new();
|
||||
if let Some(stdout) = record_field(&rec, "stdout").and_then(|v| value_text(&v)) {
|
||||
if !stdout.is_empty() {
|
||||
parts.push(stdout);
|
||||
}
|
||||
}
|
||||
if let Some(stderr) = record_field(&rec, "stderr").and_then(|v| value_text(&v)) {
|
||||
if !stderr.is_empty() {
|
||||
parts.push(format!("[stderr]\n{stderr}"));
|
||||
}
|
||||
}
|
||||
if let Some(error) = record_field(&rec, "error").and_then(|v| value_text(&v)) {
|
||||
if !error.is_empty() {
|
||||
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),
|
||||
_ => None,
|
||||
}) {
|
||||
if code != 0 {
|
||||
meta.push(format!("exit {code}"));
|
||||
}
|
||||
}
|
||||
if let Some(ms) = record_field(&rec, "ms").and_then(|v| match v {
|
||||
Value::Int(n) => Some(n),
|
||||
_ => None,
|
||||
}) {
|
||||
if ms > 0 {
|
||||
meta.push(format!("{ms}ms"));
|
||||
}
|
||||
}
|
||||
if !meta.is_empty() {
|
||||
parts.push(format!("— {}", meta.join(" · ")));
|
||||
}
|
||||
let text = if !has_body {
|
||||
"(no output)".to_string()
|
||||
} else {
|
||||
parts.join("\n\n")
|
||||
};
|
||||
out.insert(cell, StaticCellOutput { ok, text });
|
||||
}
|
||||
}
|
||||
let view_summary = session.summary();
|
||||
session.close();
|
||||
(out, Some(view_summary))
|
||||
}
|
||||
|
||||
/// Inject static cell outputs into code cards without running client JS.
|
||||
fn inject_cell_outputs(html: &str, outputs: &HashMap<String, StaticCellOutput>) -> String {
|
||||
let mut html = html.to_string();
|
||||
for (name, out) in outputs {
|
||||
let marker = format!(r#"data-code-name="{name}""#);
|
||||
let Some(pos) = html.find(&marker) else {
|
||||
continue;
|
||||
};
|
||||
let tail = &html[pos..];
|
||||
let Some(out_pos) = tail.find(r#"<pre class="code-out" hidden></pre>"#) else {
|
||||
continue;
|
||||
};
|
||||
let abs_pos = pos + out_pos;
|
||||
let replacement = if out.ok {
|
||||
format!(r#"<pre class="code-out">{}</pre>"#, escape(&out.text))
|
||||
} else {
|
||||
format!(r#"<pre class="code-out err">{}</pre>"#, escape(&out.text))
|
||||
};
|
||||
html.replace_range(
|
||||
abs_pos..abs_pos + r#"<pre class="code-out" hidden></pre>"#.len(),
|
||||
&replacement,
|
||||
);
|
||||
}
|
||||
html
|
||||
}
|
||||
|
||||
fn inject_static_session(html: &str, summary: Option<&Value>) -> String {
|
||||
let Some(summary) = summary else {
|
||||
return html.to_string();
|
||||
};
|
||||
let Ok(json) = crate::host::json::value_to_json(summary) else {
|
||||
return html.to_string();
|
||||
};
|
||||
let Ok(json) = serde_json::to_string(&json) else {
|
||||
return html.to_string();
|
||||
};
|
||||
let line = format!(
|
||||
"window.MARQDO_VIEW_LIVE = false;\nwindow.MARQDO_STATIC_SESSION = {json};"
|
||||
);
|
||||
html.replace("window.MARQDO_VIEW_LIVE = false;", &line)
|
||||
}
|
||||
|
||||
pub fn write_static(opts: OutputOptions) -> Result<()> {
|
||||
let root = build_root(&opts.path)?;
|
||||
fs::create_dir_all(&opts.out_dir)
|
||||
@@ -48,7 +204,18 @@ pub fn write_static(opts: OutputOptions) -> Result<()> {
|
||||
let links = LinkMode::Static {
|
||||
from: Some(rel.clone()),
|
||||
};
|
||||
let html = page_file(&root.files, &rel, &vm, &links);
|
||||
let (cell_outputs, static_summary) = if opts.no_exec {
|
||||
(HashMap::new(), None)
|
||||
} else {
|
||||
static_page_data(&root, &abs, &vm.preset_stdin)
|
||||
};
|
||||
let html = inject_static_session(
|
||||
&inject_cell_outputs(
|
||||
&page_file(&root.files, &rel, &vm, &links),
|
||||
&cell_outputs,
|
||||
),
|
||||
static_summary.as_ref(),
|
||||
);
|
||||
let out_file = pages_root.join(format!("{rel}.html"));
|
||||
if let Some(parent) = out_file.parent() {
|
||||
fs::create_dir_all(parent)?;
|
||||
@@ -57,11 +224,17 @@ pub fn write_static(opts: OutputOptions) -> Result<()> {
|
||||
|
||||
if first_page_html.is_none() {
|
||||
// index.html = first file (same content, links rooted at OUT_DIR)
|
||||
first_page_html = Some(page_file(
|
||||
&root.files,
|
||||
&rel,
|
||||
&vm,
|
||||
&LinkMode::Static { from: None },
|
||||
first_page_html = Some(inject_static_session(
|
||||
&inject_cell_outputs(
|
||||
&page_file(
|
||||
&root.files,
|
||||
&rel,
|
||||
&vm,
|
||||
&LinkMode::Static { from: None },
|
||||
),
|
||||
&cell_outputs,
|
||||
),
|
||||
static_summary.as_ref(),
|
||||
));
|
||||
}
|
||||
}
|
||||
@@ -85,3 +258,18 @@ fn resolve_abs(root: &ViewRoot, rel: &str) -> Result<PathBuf> {
|
||||
let abs = root.root.join(rel);
|
||||
Ok(abs.canonicalize().unwrap_or(abs))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn injects_visible_static_cell_outputs() {
|
||||
let html = r#"<div class="card" data-code-name="a"></div><pre class="code-out" hidden></pre>"#;
|
||||
let mut outputs = HashMap::new();
|
||||
outputs.insert("a".to_string(), StaticCellOutput { ok: true, text: "42".into() });
|
||||
let html = inject_cell_outputs(html, &outputs);
|
||||
assert!(html.contains(r#"<pre class="code-out">42</pre>"#), "{html}");
|
||||
assert!(!html.contains("hidden"), "{html}");
|
||||
}
|
||||
}
|
||||
@@ -1259,6 +1259,7 @@ fn render_stmt(
|
||||
<span class="badge">code</span>
|
||||
<code class="expr">`{name}` =</code>
|
||||
<span class="code-lang">{lang}</span>
|
||||
<button type="button" class="nb-clean" title="Clear this output">Clean</button>
|
||||
</div>
|
||||
<pre class="code-body"><code class="language-{lang}">{src}</code></pre>
|
||||
<div class="code-foot">
|
||||
@@ -1537,6 +1538,7 @@ pub(crate) fn render_code_assign_card(name: &str, lang: &str, source: &str) -> S
|
||||
<span class="badge">code</span>
|
||||
<span class="code-name">{name}</span>
|
||||
<span class="code-lang">{lang}</span>
|
||||
<button type="button" class="nb-clean" title="Clear this output">Clean</button>
|
||||
</div>
|
||||
<pre class="code-body"><code class="language-{lang}">{src}</code></pre>
|
||||
<div class="code-foot">
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: View without foreign
|
||||
description: A pure Marqdo document — formula, table, plot and prose, no external kernel
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
This page has no foreign import and no ` ```lang ` code cell. It is still opened by the same `view` surface, with the same toolbar and layout. The cell list is simply empty.
|
||||
|
||||
The formula is ordinary Marqdo data:
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
**_plot = math.plot formula=`f` var="x" min=-4 max=4**
|
||||
|
||||
| region | orders | revenue |
|
||||
|--------|--------|---------|
|
||||
| 华东 | 45 | 56253 |
|
||||
| 华南 | 45 | 67187 |
|
||||
| 华北 | 45 | 65272 |
|
||||
| 西部 | 45 | 66884 |
|
||||
|
||||
**total = 56253 + 67187 + 65272 + 66884**
|
||||
|
||||
> print text=`total`
|
||||
|
||||
This is the control page: no foreign, no cells, no separate mode. The same view shell is used.
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: Python 经营洞察 Notebook
|
||||
title: Python 经营洞察 · View Cells
|
||||
description: 多 cell 共享 Python 内核,做订单生成、区域/产品指标、异常检测、报告输出与独立复核。
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -22,6 +23,8 @@ description: 多 cell 共享 Python 内核,做订单生成、区域/产品指
|
||||
| 生成报告 | 分析 | ASCII 图 + JSON 报告 |
|
||||
| 独立复核 | 复核 | 另一个内核读取报告做校验 |
|
||||
|
||||
`会话` = > foreign.session kernels=`内核表` cells=`会话表`
|
||||
|
||||
`准备数据` =
|
||||
```python
|
||||
import math
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: notebook shared state
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -19,6 +20,8 @@ title: notebook shared state
|
||||
| 读取 | 分析 | 读取共享变量 |
|
||||
| 隔离 | 绘图 | 看不到 shared |
|
||||
|
||||
`会话` = > foreign.session kernels=`内核表` cells=`会话表`
|
||||
|
||||
`设置` =
|
||||
```node
|
||||
let shared = 41;
|
||||
|
||||
Reference in new issue
Block a user