Compare commits

...
26 Commits
Author SHA1 Message Date
cflmy dff0b700ae release: v1.5.1 — view static/live unified + foreign value passing 2026-10-18 14:05:19 +08:00
cflmy 4da07c1b26 fix(view): do not turn documentation tables into call chips
Keep descriptive table labels non-callable and suppress call annotations on table blocks. This removes the collapsed call {步骤...} chip while preserving the table and the return 950 chips at the actual foreign/writeback calls.
2026-10-18 13:59:24 +08:00
cflmy 78922102e4 fix(view): anchor imported-function returns at their call site
Track the caller line on CallFrame and use it for return annotations instead of the callee library line. Return 950 stays visible on the actual foreign/writeback calls; the Markdown table remains intact and no longer receives stray return chips.
2026-10-18 13:56:50 +08:00
cflmy 064bae2c65 docs(view): keep writeback table labels as inline code
Wrap foreign.run/session and writeback.record table labels in code spans so the prose table is not traced as executable calls; this removes the stray return 950 chips.
2026-10-18 13:52:51 +08:00
cflmy 92b91ffc81 fix(view): group and theme writeback blocks
Render contiguous writeback comment lines as one block, and map output-card/writeback tokens to the View dark theme. Static and live pages no longer show three dashed fragments or light output cards on dark.
2026-10-18 13:51:11 +08:00
cflmy ab6648ae0e docs(view): make the writeback page itself the runnable example
Move the foreign + writeback demo into the user persistence page. The page runs a Python code fence, records a keyed total slot, and the slot is visible in both source and static rendering. Remove the separate example document.
2026-10-18 13:48:05 +08:00
cflmy 5acf026e0c docs(view): add a runnable foreign writeback example
Move persistence guidance out of the walkthrough into separate static pages. Add examples/foreign-writeback/index.mq.md, which executes a foreign code fence and writes a keyed total slot into its own source.
2026-10-18 13:45:27 +08:00
cflmy 8dcd69412f docs(view): recommend static snapshots and writeback persistence
Add a persistence recommendation to the user-facing foreign walkthrough: static export for published snapshots, and lib/writeback for opt-in result slots in the .mq.md source. Show a readable code-fence based writeback example.
2026-10-18 13:40:44 +08:00
cflmy 2a13e52981 docs(view): show low-level session evaluation as code fences
Replace inline source strings with readable Python code fences bound as Marqdo code values. The low-level session evaluates those values; no long escaped source argument remains.
2026-10-18 13:35:51 +08:00
cflmy 9b269f6447 feat(foreign): pass Marqdo values into multi-kernel view sessions
foreign.session accepts a values table and initializes each kernel from ordinary Marqdo values. The static walkthrough now uses two kernels and a shared 订单 value instead of redefining orders inside Python. Static pages embed the session summary so kernel controls and Clean stay visible.
2026-10-18 13:32:51 +08:00
cflmy 15362cb048 fix(view): restore per-cell kernel switch and Clean
Code cards again show a kernel selector and a Clean button. Clean calls /api/session/cell/clear for live sessions and clears local output in static snapshots, without restarting kernels.
2026-10-18 13:27:15 +08:00
cflmy 05d48f68a4 docs(view): show kernel state and Marqdo value passing
Rewrite the static foreign walkthrough without stdin-driven examples. It now demonstrates session_set from an ordinary Marqdo table, persistent kernel state across evaluations, and a foreign.session view plan sharing state across cells. Static export executes those cells and embeds the real outputs.
2026-10-18 13:23:03 +08:00
cflmy e4387259ba fix(view): make static examples self-contained
Foreign cell examples read stdin with a deterministic fallback, so static exports show real output without tracebacks. Low-level session bindings named 会话 are no longer mistaken for a view plan; static export runs all cells again.
2026-10-18 13:19:41 +08:00
cflmy 518f8e386b fix(view): avoid stdin tracebacks in static snapshots
Static export skips cells that read stdin when the document has no preset stdin, and shows a short explanation instead of a traceback. Preset stdin still executes normally.
2026-10-18 13:14:17 +08:00
cflmy 9da12c9093 feat(view): add cell stdin for live and static runs
View gets a Cell stdin/input field wired to cell Run, Step and Run All. Stateless cells receive raw stdin; persistent kernels receive marqdo_input. Static export uses the document preset stdin and the same run_all path.
2026-10-18 13:10:08 +08:00
cflmy e0d34669e0 fix(view): use the same run path for static and live cells
Run All now records per-cell failures and continues; static export uses the same foreign_doc run_all and injects those records. A cell that succeeds in view therefore succeeds in the static snapshot, and failures match.
2026-10-18 13:03:46 +08:00
cflmy 0ba4d3d2d7 feat(view): render real cell outputs in static exports
Static export opens the foreign document session, runs cells once, and injects stdout/stderr/error into the code cards. Failures are shown as real errors; --no-exec still skips execution.
2026-10-18 13:00:41 +08:00
cflmy ad3ebf243a fix(view): keep static buttons with a no-live notice
Static pages now render the same toolbar and Execution Clear button as live view. Clicking any execution control shows a static-export notice instead of hiding controls or pretending to run.
2026-10-18 12:55:07 +08:00
cflmy 142d30ce08 fix(view): share the same shell between static and live output
Static exports now include the View shell and dark theme; interactive toolbar and Execution Clear stay hidden, while dynamic pages show them.
2026-10-18 12:52:48 +08:00
cflmy 4757b82edd fix(view): run stateless documents and clear Execution output
No-session view Run All now runs the document and renders stdout into Execution; Clear outputs clears Execution output, plots and plan cards as well as cell outputs.
2026-10-18 12:51:13 +08:00
cflmy bff2f53e52 fix(view): clear Execution output from the view surface
Add an Execution Clear button and clear the Execution out/plots/plan card in addition to code-cell outputs. The same clearOutputs path calls /api/session/clear, so ordinary stateless pages and foreign sessions are both wired.
2026-10-18 12:47:56 +08:00
cflmy fb28eee62f feat(foreign): own view sessions and clear outputs
foreign.session returns a handle from ordinary kernel/cell tables; view consumes only the 会话 binding. Sessions live in host foreign_doc. Without 会话, view cells run stateless one-shot. Add /api/session/clear and a Clear outputs button for every view page; clearing keeps persistent kernel state.
2026-10-18 12:42:15 +08:00
cflmy 01468ad976 test(view): add foreign and non-foreign preview fixtures
Add a pure Marqdo control page and make the Python view-cells example explicitly import lib/foreign.
2026-10-18 12:22:36 +08:00
cflmy f3791d11b4 refactor(view): evaluate cell plans through the interpreter
Delete the source-line table scanner. 内核表/会话表 are now evaluated as ordinary Marqdo bindings (with simple assignment dependencies) via Interpreter::capture_declarations. Every view page uses the same cell toolbar; run/watch semantics are unchanged; no new CLI or Markdown marker.
2026-10-18 12:17:42 +08:00
cflmy 7fef690167 refactor(view): unify cells into the view surface
Cell controls now appear only when a document declares 内核表/会话表. Remove Notebook branding and Jupyter In/Out prompts; ordinary view pages stay classic. There is no new CLI command or second interactive mode; run remains canonical execution and view is the only interactive surface.
2026-10-18 12:03:17 +08:00
cflmy 024cdee82a debian: add 1.5.0 PPA changelog 2026-10-18 03:36:53 +08:00
43 changed files with 1941 additions and 640 deletions

No files matched your search

+1 -1
View File
@@ -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
+3
View File
@@ -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
View File
@@ -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
View File
@@ -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"
+6 -5
View File
@@ -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 -1
View File
@@ -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)"
+11
View File
@@ -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.
+23 -22
View File
@@ -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 |
+10 -10
View File
@@ -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` 遍历 |
+3 -3
View File
@@ -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
View File
@@ -1 +1 @@
1.5.0
1.5.1
+18
View File
@@ -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
+16
View File
@@ -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
+7 -5
View File
@@ -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
View File
@@ -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
View File
@@ -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`。
-183
View File
@@ -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).
+152
View File
@@ -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.
-183
View File
@@ -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)。
+152
View File
@@ -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,也没有隐藏的语言切换。
+4 -4
View File
@@ -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)
+4 -4
View File
@@ -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)
+56
View File
@@ -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.
+56
View File
@@ -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` 本身里的活文档用自写回。两者可以共存于同一个仓库:静态页面给读者,自写回示例给作者和审计。
+1 -1
View File
@@ -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.
+1 -1
View File
@@ -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 包。
+8 -5
View File
@@ -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).
---
+8 -5
View File
@@ -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)。
---
+3
View File
@@ -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,
}
+577 -121
View File
@@ -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() {
+2
View File
@@ -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
View File
@@ -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)
}
-2
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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 &amp; 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");
}
}
+15
View File
@@ -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)
+44 -4
View File
@@ -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
View File
@@ -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}");
}
}
+2
View File
@@ -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">
+31
View File
@@ -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.
+4 -1
View File
@@ -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
+3
View File
@@ -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;