Compare commits

..
15 Commits
Author SHA1 Message Date
cflmy 33a14d272c release: v1.5.2 — foreign v3 P0/P1 (stdin, plan API, snapshot, capture, persist) 2026-10-18 14:57:15 +08:00
cflmy 6ed70fd8b8 docs(design): defer G7 and G8 from the v3 target
Keep the cross-document scope and non-Python/Node adapter designs in the document for future work, but remove them from the current implementation target and priorities.
2026-10-18 14:51:12 +08:00
cflmy 115d1f6c0b feat(view): explicit persist and nested-plan boundary
Add per-cell Persist backed by lib/writeback and /api/session/cell/persist. Reject nested foreign.session plans with a top-level diagnostic and tests.
2026-10-18 14:47:54 +08:00
cflmy 7dc5e56850 feat(foreign): reject nested view plans
Enforce the v3 plan boundary: foreign.session must be a top-level binding. Nested plans are diagnosed instead of silently becoming stateless. Tests cover the AST helper and DocumentSession open.
2026-10-18 14:46:57 +08:00
cflmy 514caa55ae docs(design): mark G9 snapshot capture implemented
view capture and view output --snapshot are implemented with source-hash validation; remaining gaps are G3/G7/G8/G10.
2026-10-18 14:46:20 +08:00
cflmy 74908ebf04 feat(view): capture live snapshots for static export
Add view capture to record per-cell outputs and session summary with source hashes. view output --snapshot consumes the capture without re-executing and rejects source drift. Includes snapshot parsing tests.
2026-10-18 14:45:26 +08:00
cflmy 0f852593bc docs(design): record foreign v3 P0/P1 implementation status
Mark stdin/per-cell inputs/interrupt and plan/snapshot APIs as implemented; keep G3/G7/G8/G9/G10 as pending design items.
2026-10-18 14:44:29 +08:00
cflmy 34e2fb4f74 feat(foreign): snapshot export, import and replay
Export JSON-safe kernel values, cells and journal; restore values into a matching plan; replay cells with recorded stdin. Add /api/session/snapshot/{export,import,replay}.
2026-10-18 14:43:53 +08:00
cflmy 0e407b2bd3 feat(foreign): runtime plan updates and generation
Add explicit add/remove cell and set-value operations with a plan generation counter. Expose /api/session/plan/{assign,add,remove,value}.
2026-10-18 14:43:26 +08:00
cflmy e5e532d83f fix(foreign): keep session_list arity empty
ForeignSessionList accepts no id; only ForeignSessionInterrupt takes id.
2026-10-18 14:38:27 +08:00
cflmy 064522a338 feat(foreign): raw stdin, per-cell inputs and interrupt
Persistent Python/Node kernels receive raw program stdin per eval; foreign.session accepts an inputs table and view exposes per-cell stdin. Add session interrupt host API and view control.
2026-10-18 14:37:45 +08:00
cflmy c85f1a2829 feat(foreign): support raw stdin and per-cell inputs
Session eval now carries raw stdin, and the Python/Node workers temporarily replace program stdin during evaluation. foreign.session accepts an inputs table; view exposes per-cell stdin and Run All sends a per-cell input map. Stateless and persistent cells share the same input semantics.
2026-10-18 14:36:47 +08:00
cflmy a7266185b2 docs(design): propose foreign v3 capability plan
Document the remaining foreign runtime gaps: persistent raw stdin, per-cell input, dynamic plan boundaries, runtime plan updates, interrupt, state export/replay, cross-document scope, non-Python/Node adapters, live-to-static snapshots and explicit writeback policy.
2026-10-18 14:31:44 +08:00
cflmy 4d7c0bea1b fix: sync Cargo.lock with v1.5.1 version bump 2026-10-18 14:23:20 +08:00
cflmy 53758ebd1c debian: changelog entry for 1.5.1-1ppa1 2026-10-18 14:20:24 +08:00
20 changed files with 1816 additions and 37 deletions

No files matched your search

+3 -1
View File
@@ -126,9 +126,11 @@ jobs:
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **v1.5.2**:外联 v3 P0/P1——raw stdin + 每 cell 输入 · plan API · snapshot · `view capture` · Persist
- **v1.5.2**: Foreign v3 P0/P1 — raw stdin + per-cell inputs, plan API, snapshot export/import/replay, `view capture`, Persist
- **v1.5.2 ext**:扩展包同步 1.5.2 / Ext pack 1.5.2
- **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
+29
View File
@@ -8,6 +8,35 @@
### Changed
## v1.5.2 — 2026-10-18
### Highlights
**外联 v3 P0/P1**:session eval 支持 raw stdin(Python/Node 持久内核);每 cell 独立 stdin 与 Interrupt;plan generation/add/remove/value API;snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获实时快照;显式 Persist 按钮。CLI · wasm · ext **1.5.2**。
```bash
git checkout v1.5.2 && cargo build --release
marqdo ext add web # CDN → 1.5.2
```
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v3 扩展 `lib/foreign` 库 API;不改 MQ 关键词 / 表几何。
### Added
- **raw stdin + 每 cell 输入**:session eval 支持 raw stdin;`foreign.session inputs=` 每 cell 独立 stdin;view 增加每卡 stdin 字段与 Interrupt 按钮。
- **plan API**:plan generation/add/remove/value;运行时 plan 更新与 generation。
- **snapshot**:snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获 live 快照用于静态导出。
- **显式 Persist**:Persist 按钮 + `/api/session/cell/persist`。
- **嵌套 plan 边界**:显式 persist 与嵌套 plan 边界;foreign 拒绝嵌套 view plans。
### Fixed
- **`session_list` arity**:保持空 arity。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.5.2**。
## v1.5.1 — 2026-10-18
### Highlights
Generated
+2 -2
View File
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "1.5.0"
version = "1.5.2"
dependencies = [
"anyhow",
"assert_cmd",
@@ -603,7 +603,7 @@ dependencies = [
[[package]]
name = "marqdo-wasm"
version = "1.5.0"
version = "1.5.2"
dependencies = [
"marqdo",
"serde_json",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "1.5.1"
version = "1.5.2"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
+6 -6
View File
@@ -149,10 +149,10 @@ marqdo catalog public -o .marqdo
---
## 现状(v1.5.1)
## 现状(v1.5.2)
- **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**
- **外联 v3 P0/P1(v1.5.2)**:raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · `view capture` · Persist 按钮 · 扩展包同步 **1.5.2**
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin;扩展包同步 **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)
@@ -186,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.1)
### 如何使用最新 Marqdo(v1.5.2)
**安装解释器(任选其一)**
@@ -201,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.1 # 或留在 main
git checkout v1.5.2 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -240,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.1
# https://github.com/cflmy/marqdo/releases/tag/v1.5.2
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "1.5.1"
version = "1.5.2"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
+18
View File
@@ -1,3 +1,21 @@
marqdo (1.5.2-1ppa1) noble; urgency=medium
* Marqdo 1.5.2: Foreign v3 P0/P1 — raw stdin with per-cell inputs and
interrupt, plan generation/add/remove/value API, snapshot
export/import/replay, view capture for static export, explicit Persist
button, nested plan boundary.
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 15:00:00 +0800
marqdo (1.5.1-1ppa1) noble; urgency=medium
* Marqdo 1.5.1: View static/live execution path unified; foreign value
passing into multi-kernel sessions; cell stdin for live/static/persistent
kernels; build-time execution with stdout injection in static exports;
runnable foreign writeback example; writeback block grouping.
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 22:00:00 +0800
marqdo (1.5.0-1ppa1) noble; urgency=medium
* Marqdo 1.5.0: Foreign kernels v2 (structured invoke, JSON calls,
+654
View File
@@ -0,0 +1,654 @@
# 外联运行时 v3 — 能力缺口与深化设计(Proposed)
| | |
|---|---|
| 状态 | **Proposed;尚未实现** |
| 日期 | 2026-10-18 |
| 层 | Runtime(foreign)· Document(`foreign.session`)· View(投影) |
| 相关 | [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [foreign-v2.md](../roadmap/foreign-v2.md) · [stdlib-writeback.md](stdlib-writeback.md) · [view-static-interactive.md](view-static-interactive.md) |
| 核心表面 Δ | **无增删**:不新增 Markdown 标记、不新增 notebook CLI |
> 本文只定义设计,不承诺已实现。当前基线是 v1.5.0 之后的本地工作:`foreign.session` 句柄、多内核、values 初始化、view 控制、静态执行与显式 writeback 已可用;本文处理仍然缺失的能力。
---
## 1. 设计约束
v3 必须继续满足以下约束,否则不进入实现:
1. **外联库拥有内核与状态**:`foreign` 管理内核、会话、cell 计划、输入、输出、journal 和生命周期。`view` 只消费句柄,不拥有第二套运行时。
2. **表与围栏是值**:`内核表`、`单元表`、`输入表`、`值表` 都是普通 Marqdo 值;没有保留表名,没有新增标记。
3. **单一执行语义**:`run` 是规范执行;`view` 是同一文档的交互投影;静态导出是同一会话的快照,不另写解释器。
4. **没有 Notebook 模式**:没有 `marqdo notebook`,没有 `In/Out`,没有“普通 view / notebook view”两套布局。
5. **显式 I/O**:Marqdo 值通过 `values` / `session_set` 传递;程序 stdin 是单独概念,不能伪装成 `marqdo_input`。
6. **显式持久化**:默认不改源码;writeback 必须由文档显式调用,或由用户显式选择策略。
7. **安全默认值**:执行受 capability 控制;输入/输出有界;不反序列化任意对象;跨文档共享必须显式开启。
---
## 2. 基线:现在已经有什么
| 能力 | 状态 |
|---|---|
| `foreign.run` / `run_lang` / `invoke` / `probe` | 已实现 |
| `foreign.call` / `call_many` / JSON 进出 / 并行 | 已实现 |
| `session_open` / `eval` / `set` / `get` / `names` / `close` / `list` | 已实现 |
| `foreign.session kernels= cells= values=` | 已实现 |
| 多内核 view 会话、cell 顺序、内核归属 | 已实现 |
| Marqdo 表通过 `values` 传入多个内核 | 已实现 |
| 无 `会话` 时无状态 cells | 已实现 |
| view 每 cell 内核选择 / Clean / Run | 已实现 |
| 静态导出执行 cells 并嵌入真实输出 | 已实现 |
| 静态页 session summary、内核归属、多内核展示 | 已实现 |
| 显式 `writeback.record` | 已实现(库能力) |
| 静态页按钮的“不可执行”提示 | 已实现 |
---
## 2.1 实施状态(2026-10-18)
| ID | 状态 | 备注 |
|---|---|---|
| G1/G2 | ✅ 已实现 | session eval raw stdin;`foreign.session inputs=`;per-cell UI;Python/Node 测试 |
| G5 | ✅ 基本实现 | `session_interrupt` + view Interrupt;Python SIGINT 保留会话;Node 进程可能被终止 |
| G4 | ✅ 已实现(API) | add/remove/set-value + generation;view 尚未提供 add/remove UI |
| G6 | ✅ 已实现(API) | export/import/replay JSON snapshot;view/CLI 尚未做文件封装 |
| G9 | ✅ 已实现(CLI/API 基础) | `view capture` + `view output --snapshot`;source hash 校验 |
| G3 | ✅ 边界已实现 | 顶层 plan;嵌套 plan 诊断 |
| G10 | ✅ 显式 persist | `/api/session/cell/persist` + view Persist;不自动写源码 |
| G7/G8 | 📌 已移出当前目标 | 设计保留,后续版本再开发 |
## 3. 缺口清单
| ID | 缺口 | 优先级 | 当前行为 | 目标 |
|---|---|---|---|---|
| G1 | 持久内核 raw stdin | P0 | 持久内核只有 `marqdo_input` | 程序 stdin 与控制协议分离 |
| G2 | 每 cell 独立 stdin | P0 | 页面级 Cell stdin,Run All 共用一个输入 | cell 级输入表 + UI |
| G3 | 动态 plan | P2 | 只读顶层 `会话` | 明确边界,或受控动态 |
| G4 | 运行时更新 plan | P1 | values 只在打开时初始化 | 显式 session 变更 API |
| G5 | kernel interrupt | P0 | 只能等超时/杀进程组 | 可中断当前 eval |
| G6 | 状态持久化 / replay | P1 | journal/dirty 只在内存 | 导出/恢复/replay |
| G7 | 跨文档内核 | P2 | 每文档独立 | 显式 scope/空间 |
| G8 | 非 Python/Node 持久内核 | P3 | Go 等一次性执行 | LangSpec 会话适配器 |
| G9 | live → static 输入捕获 | P0 | 静态构建不捕获临时 stdin | 显式 snapshot 捕获 |
| G10 | 自动 writeback | P2 | 必须显式调用 | 显式策略下的“运行后写回” |
---
## 4. 统一模型
### 4.1 会话句柄
`foreign.session` 返回的句柄是一个普通 Marqdo 值,建议稳定形状:
```text
{
kind: "foreign-session",
id: "<session-id>",
document: "<entry-source-hash>",
status: "created | ready | running | interrupted | dirty | closed",
kernels: [...],
cells: [...],
inputs: [...],
values: [...],
generation: 1
}
```
`view` 只读这些字段;任何执行操作都通过 `foreign` 的 host API。句柄不是第二套运行时。
### 4.2 三种输入
必须严格区分:
| 输入 | 目标 | 形态 | 当前 |
|---|---|---|---|
| `values` | 内核变量 | Marqdo 值 → JSON copy | 已实现 |
| `input` | `marqdo_input` | JSON 值 | 已实现(低层) |
| `stdin` | 程序 stdin | 原始文本/字节 | 仅无状态 cell 有 |
v3 不允许把 raw stdin 偷偷塞进 `marqdo_input`;两者语义不同。
### 4.3 每 cell 输入表
不新增标记,仍然使用普通表:
```mq.md
`单元输入` =
| 单元 | stdin | input |
|------|-------|-------|
| 计算 | hello | {rate: 0.08} |
| 复核 | | {check: true} |
```
`foreign.session` 增加可选参数:
```text
foreign.session kernels=... cells=... values=... inputs=`单元输入`
```
规则:
- `stdin` 只给该 cell 的程序 stdin;
- `input` 只给该 cell 的 `marqdo_input`;
- 空值表示不提供;
- 输入大小有上限,超限显式报错;
- 静态导出使用同一张表,因此 view 与静态快照可以一致。
### 4.4 执行流水线
```text
evaluate 会话 handle
→ open kernels
→ apply values
→ apply cell inputs
→ run cell
→ record {stdout, stderr, input_echo, result}
→ next cell
```
失败不终止整个 Run All;错误写入 cell record,journal 保留。
---
## 5. G1/G2:持久内核 stdin 与每 cell 输入
### 5.1 问题
当前持久内核的 worker 用 stdin 传输 JSON 控制协议,因此程序自己的 stdin 不可用;`marqdo_input` 只是 JSON 变量,不是 stdin。
### 5.2 方案 A(推荐):控制通道与程序 stdin 分离
- Unix:父进程创建 **socketpair**(或两个 pipe),worker 通过 fd 3/4 读写控制帧;程序 stdin 使用单独的 pipe。
- Windows:named pipe 或可继承的匿名 pipe 作为控制通道;程序 stdin 单独 pipe。
- worker 协议升级为 `protocol: 2`:
- 控制帧:`eval` / `set` / `get` / `interrupt` / `close`
- eval 帧可带 `stdin`(UTF-8)或 `stdin_b64`(二进制,后续)
- Python worker:每次 eval 前把 `sys.stdin` 替换为 `io.TextIOWrapper`/`StringIO`,eval 后恢复控制通道;用户代码读到的是真正的 stdin。
- Node worker:控制 readline 移到控制 pipe;每次 eval 把 `process.stdin` 替换为 `PassThrough`/`Readable`,eval 后恢复。
- 超时/中断关闭该次 stdin,不污染下一次 eval。
### 5.3 方案 B(降级):只支持 `input`
如果控制通道暂不实现,持久内核只支持 `input`,并显式拒绝 raw stdin:
```text
persistent kernel stdin is unavailable; use input= or stateless cells
```
不能静默把 stdin 变成 `marqdo_input`。
### 5.4 方案 C:stdin cell 降级为一次性
持久会话中遇到 raw stdin 时,用一次性进程执行该 cell;明确标记 `state: none`,不假装内核态连续。
### 5.5 UI 与静态
- `view`:每个代码卡提供 **Cell stdin** 小输入框,或者页面级输入表;推荐每 cell,因为它们经常不同。
- 静态:读取 `inputs` 表;没有输入时显示“requires stdin”说明,而不是 traceback。
- Run All 使用每 cell 的输入;不再把一个页面级 stdin 复制给所有 cell。
### 5.6 验收
- Python 与 Node 持久内核都能读取真实 stdin;
- 同一个 cell 连续 eval 不串输入;
- 超时/中断后下一次 eval 仍可读 stdin;
- 无状态 cell 行为不变;
- 静态快照使用相同输入表,结果与 live 一致(在相同输入下)。
---
## 6. G3:动态 plan 的边界
### 6.1 问题
`foreign.session` 目前只识别 entry 顶层的 `会话` 绑定。分支、函数、运行时循环中定义的 plan 不会被 view 发现。
### 6.2 设计决定(建议)
**v3 不支持任意控制流中的 plan。** 这是有意的语义边界:
- plan 是文档的声明,不是程序运行时的副作用;
- view 不应为了找 plan 而执行 `# main`;
- 避免 view 再次长出一套“运行程序再猜计划”的隐式逻辑。
允许的动态形式:
- 顶层赋值右侧的纯表达式,包括引入的纯函数;
- `foreign.session` 的 tables/values 可以由顶层表函数计算;
- 运行时变化通过 G4 的显式 session API 完成。
**不支持**:
- `##` 函数内部的 plan;
- `if`/`while` 分支里的 plan;
- 依赖 `# main` 副作用才能得到的 plan。
### 6.3 诊断
如果源码中出现非顶层 `foreign.session`,给出:
```text
foreign.session: plan must be a top-level binding (会话 = > foreign.session ...)
```
而不是静默降级为无状态。
---
## 7. G4:运行时更新 plan
### 7.1 目标
已打开的 view session 允许用户显式修改 cell 归属、增加/移除 cell、更新内核变量;所有修改都要可追踪。
### 7.2 API
```text
foreign.session_assign session=<handle> cell="计算" kernel="复核"
foreign.session_add_cell session=<handle> cell="新单元" kernel="分析"
foreign.session_remove_cell session=<handle> cell="旧单元"
foreign.session_set_value session=<handle> kernel="分析" name="rate" value=0.08
```
所有操作:
- 校验 cell/kernel 语言;
- 递增 `generation`;
- 写入 journal(kind=plan_change / value_change);
- 标记受影响 cell 为 `dirty`;
- 失败不改变 handle。
### 7.3 View
- 内核下拉复用 `session_assign`;
- 增加/删除 cell 放在显式菜单,不做隐式拖拽写入源码;
- UI 显示 generation / dirty 状态。
### 7.4 静态
静态快照不执行变更;它记录变更后的 plan,或在构建时执行一次并固化。
---
## 8. G5:kernel interrupt
### 8.1 API
```text
foreign.session_interrupt id=<session-id>
```
### 8.2 行为
- 控制通道发送 `interrupt`;
- worker 取消当前 eval,返回 `{ok:false, interrupted:true}`;
- 保留已完成的值和 journal;
- 状态从 `running` → `interrupted`;
- 下一次 eval 可以继续使用内核(除非进程已损坏);
- 超时继续作为最后一道防线。
### 8.3 View
- 工具栏增加 Interrupt;执行中的 cell 显示 interrupted;
- 不自动重跑;
- 静态导出没有 interrupt(快照不执行)。
### 8.4 跨平台
Unix:进程组信号 + 控制帧;Windows:控制帧 + `taskkill /T` fallback。两者都必须有测试。
---
## 9. G6:状态持久化与 replay
### 9.1 不做的事
- 不做 Python pickle / Node 堆快照;
- 不做任意对象反序列化;
- 不把内核内存默认写进 `.mq.md`。
### 9.2 显式快照
```text
foreign.session_export session=<handle> path=".marqdo/sessions/doc-1.json"
foreign.session_import path=".marqdo/sessions/doc-1.json"
```
快照只包含:
```text
{
version: 1,
document_hash: "...",
plan_hash: "...",
kernels: [{name, lang, cmd, values: {...}}],
cells: [{name, kernel, status, last_ok, last_error}],
journal: [...],
inputs: [...]
}
```
值只允许 JSON 可表达的 Marqdo 值;不可序列化的值显式失败。
### 9.3 replay
```text
foreign.session_replay path="..." verify=True
```
按 journal 顺序重放 cell + inputs,比较 stdout/status;差异写入 report。replay 不覆盖原 journal,除非显式 `append`。
### 9.4 存储
- 默认目录 `.marqdo/sessions/`(gitignore 可选);
- 用户可通过 path 放到受控目录;
- 不默认提交,不默认写源码。
---
## 10. G7:跨文档内核(Deferred / future)
> **状态:已移出 v3 当前实现目标。** 本节设计保留,作为后续版本(v4 或独立 session-scope 工作)的输入;当前不承诺 API 或兼容性。
### 10.1 原则
- 默认每文档独立;
- 跨文档必须显式 `scope=` / `space=`;
- 不自动按变量名或路径共享。
### 10.2 API
```text
foreign.session_open lang="python" scope="shared:analytics"
foreign.session_list scope="shared:analytics"
foreign.session_close id=... scope=...
```
- scope 注册表由 foreign runtime 管理;
- 同名冲突报错,不覆盖;
- view 只能打开当前文档声明允许的 scope;
- 生命周期由 owner/refcount 管理,最后一个引用关闭时清理。
### 10.3 安全
- 跨文档共享可能违反文档隔离,必须 capability + 显式配置;
- journal 标记 scope;
- 静态导出默认不打开跨文档 scope。
---
## 11. G8:非 Python/Node 持久内核(Deferred / future)
> **状态:已移出 v3 当前实现目标。** 本节设计保留,等待目标语言与 worker 适配器确定后再实现;当前不承诺 API。
### 11.1 模型
不是所有语言都需要持久内核。`LangSpec` 增加能力标志:
```text
session: none | protocol_v2
```
- `none`:只能 `run` / `invoke` 一次性;
- `protocol_v2`:实现控制通道与 eval 协议,可以 `session_open`。
### 11.2 适配器
Go 等语言通过一个薄 worker 实现:
```text
control frame: eval {code, stdin, input}
result frame: {ok, stdout, stderr, result, error}
```
不允许“看起来像持久内核、实际每次重启”的假实现。
### 11.3 失败语义
- `session_open` 对 `session: none` 的语言明确报错;
- `foreign.session` 的 plan 只能使用支持 session 的语言;
- 静态/无状态仍可使用一次性执行。
---
## 12. G9:live → static 输入捕获
### 12.1 问题
静态构建在构建环境执行,无法知道用户在 live view 中临时输入的 stdin;同一文档的结果可能不同。
### 12.2 设计
增加显式的“捕获快照”:
```text
view → Capture snapshot → .marqdo/snapshots/<doc>.view.json
```
快照内容:
- document source hash;
- session plan(kernels/cells/values);
- 每 cell 的 stdin/input;
- 每 cell 的 stdout/stderr/status;
- journal 摘要、语言/解释器版本;
- 捕获时间。
静态导出:
```text
marqdo view output --snapshot .marqdo/snapshots/doc.view.json
```
优先使用快照中的记录,校验 source hash,不重新执行;若 hash 不匹配,显式失败或 `--execute` 重跑。
### 12.3 安全/隐私
- 快照可能包含 secrets;默认不提交、不发布;
- 提供 `redact` 字段/正则;
- 静态页面只发布脱敏后的快照。
### 12.4 验收
- live 中成功的结果可以在静态页面原样显示;
- 不捕获内核内存,只捕获输入/输出/状态;
- 没有快照时回退到构建时执行,行为明确。
---
## 13. G10:自动 writeback
### 13.1 原则
**“自动”必须是用户显式选择的策略,不是默认副作用。**
### 13.2 API
```text
foreign.session persist=`写回策略`
```
策略表:
```mq.md
`写回策略` =
| 单元 | key |
|------|-----|
| 计算 | total |
| 复核 | check |
```
或 view 的 **Persist results** 按钮:将当前 cell 结果写到 `writeback.record key=...`。
### 13.3 语义
- 默认不写源码;
- 显式策略只在 **用户点击 Persist** 或 `marqdo run --writeback` 时执行;
- 静态构建默认不写回;`--writeback` 必须显式;
- writeback 只支持 JSON 可表达值;
- 写入位置/格式仍由 `writeback` 库决定。
### 13.4 与静态快照的关系
- 静态快照是只读发布;
- writeback 是源码内的活结果;
- 两者可以共存,但不能互相隐式触发。
---
## 14. API / 端点汇总
### 14.1 新增 foreign 函数
```text
foreign.session inputs=
foreign.session_assign
foreign.session_add_cell
foreign.session_remove_cell
foreign.session_set_value
foreign.session_interrupt
foreign.session_export
foreign.session_import
foreign.session_replay
foreign.session_open scope=
foreign.session_list scope=
```
### 14.2 View API
```text
POST /api/session/cell/run { cell, stdin }
POST /api/session/run_all { restart, inputs? }
POST /api/session/cell/clear
POST /api/session/plan/assign
POST /api/session/plan/add
POST /api/session/plan/remove
POST /api/session/plan/value
POST /api/session/interrupt
POST /api/session/snapshot/capture
```
所有端点只操作 foreign 句柄;view 不直接读写内核。
### 14.3 CLI
```text
marqdo view output --snapshot FILE
marqdo view output --execute
marqdo view output --no-exec
marqdo run --writeback
```
不新增 `marqdo notebook`。
---
## 15. 语义矩阵
| 能力 | run | view | static |
|---|---|---|---|
| `foreign.session` plan | 作为普通值执行 | 消费句柄 | 可执行或快照 |
| raw stdin | 支持(一次性/session) | 每 cell | inputs 表/快照 |
| interrupt | 无 UI | 可调用 | 不可用 |
| state export | 可调用 | 可显式导出 | 不导出或快照 |
| cross-doc(deferred) | 设计保留 | 设计保留 | 设计保留 |
| writeback | `--writeback` | 显式按钮 | 默认不写 |
---
## 16. 实施顺序
### P0(先做,直接影响真实使用)
1. **G1/G2 stdin**:控制通道 + 每 cell 输入表 + UI。
2. **G5 interrupt**:避免只能等超时。
3. **G9 snapshot capture**:解决 live/static 不一致。
### P1
4. **G4 runtime plan updates**。
5. **G6 export/replay**。
### P2
6. **G3 dynamic plan 边界**:按第 6 节,只做顶层纯表达式;任意控制流不承诺。
7. **G10 explicit writeback policy**。
### Deferred(不在当前目标)
- **G7 cross-document scope**:设计保留,后续版本再开发。
- **G8 non-Python/Node persistent adapters**:设计保留,等待目标语言与 worker。
---
## 17. 测试设计
### 单元
- `stdin` 协议:空输入、大输入、超时、中断、连续 eval;
- 每 cell 输入隔离;
- 返回值锚定在调用点(已修复的 CallFrame.call_line);
- 表格不产生 call chip(已修复);
- plan top-level 诊断;
- session generation / dirty;
- export/import/replay 校验。
### 集成
- Python 持久内核读 `sys.stdin`;
- Node 持久内核读 `process.stdin`;
- view Run All 使用每 cell 输入;
- interrupt 后下一次 eval 正常;
- static snapshot 与 live 结果一致;
- snapshot hash 不匹配显式失败;
- cross-doc scope 冲突/清理;
- Go 一次性 vs 持久能力诊断;
- writeback 只显式写入。
### 静态
- 输出无 traceback;
- 没有输入时显示说明而非伪造;
- 多内核 controls 显示;
- writeback slot 单块、暗色主题;
- 静态按钮提示。
---
## 18. 兼容与迁移
- 现有 `foreign.session kernels= cells= values=` 保持兼容;
- 新 `inputs=` 可选;
- `session_open` 旧协议继续可用;v2 控制通道通过 handshake 协商;
- 旧页面没有 `inputs` 时仍按空 stdin 执行/显示说明;
- 不修改已发布的 v1.5.0 tag;v3 以新版本发布。
---
## 19. 需要拍板的决策
1. **G1**:是否接受控制通道与程序 stdin 分离的协议改造?否则只能保留 `input`,不能宣称 raw stdin。
2. **G3**:是否接受“plan 必须是顶层声明”的边界?若不接受,需要定义 view 可安全调用的 plan 入口,风险更高。
3. **G6**:状态快照只允许 JSON 值,是否可接受?不做任意对象序列化。
4. **G9**:快照文件是否默认放在 `.marqdo/snapshots/` 且不提交?涉及 secrets。
5. **G10**:自动 writeback 是否只允许显式按钮/flag,而不是每次运行自动写源码?
---
## 20. 当前目标范围
v3 当前实现目标为:**G1、G2、G3、G4、G5、G6、G9、G10**。
**G7、G8 已移出当前目标**,但设计文档保留在本文件第 10、11 节,供后续开发;它们不计入 v3 完成条件,也不影响现有 API 的兼容性承诺。
## 21. 非目标
- 不新增 Markdown 标记;
- 不新增 notebook CLI/模式;
- 不把任意内核内存序列化;
- 不默认修改 `.mq.md`;
- 不自动镜像变量;
- 不把 view 变成第二套解释器;
- 不把“未实现”伪装成支持。
+1 -1
View File
@@ -1 +1 @@
1.5.1
1.5.2
+14 -2
View File
@@ -153,6 +153,7 @@ in input order. Raises with the failing index after all workers finish.
+ `kernels`=None
+ `cells`=None
+ `values`=None
+ `inputs`=None
Declare a document view session. `kernels` and `cells` are ordinary tables:
kernels are `|名称|语言|命令|` (ZH or EN), cells are `|单元|内核|`.
@@ -164,6 +165,7 @@ view has no persistent kernel state.
**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 = > table.put in=`p` at="inputs" value=`inputs`**
*p*
## session_open
@@ -183,12 +185,14 @@ default per-eval timeout.
+ `code`=None
+ `source`=None
+ `input`=None
+ `stdin`=None
+ `timeout`=None
Evaluate code (a code value) or source text in session id; returns a record
with id/alive. `input` is JSON-encoded for the kernel.
with id/alive. `input` is JSON-encoded for the kernel; `stdin` is raw program
stdin for this evaluation.
*> host_foreign_session_eval id=`id` code=`code` source=`source` input=`input` timeout=`timeout`*
*> host_foreign_session_eval id=`id` code=`code` source=`source` input=`input` stdin=`stdin` timeout=`timeout`*
## session_set
+ `id`
@@ -221,6 +225,14 @@ Kill and remove a session; returns whether it existed.
*> host_foreign_session_close id=`id`*
## session_interrupt
+ `id`
Interrupt the current evaluation of a persistent kernel. The session remains
usable for the next evaluation when the worker supports interruption.
*> host_foreign_session_interrupt id=`id`*
## session_list
List live sessions with id/lang/cmd/evals/alive/started_ms.
+11 -1
View File
@@ -151,6 +151,7 @@ JSON 进 / JSON 出:把 `输入` 编码到 stdin,解析 stdout JSON 返回
+ `内核表`=None
+ `单元表`=None
+ `值表`=None
+ `输入表`=None
声明文档视图会话。内核表和单元表都是普通表格;返回一个 foreign 会话句柄,
供 view 消费。没有这个句柄时,view 的 cells 是无状态的。
@@ -160,6 +161,7 @@ JSON 进 / JSON 出:把 `输入` 编码到 stdin,解析 stdout JSON 返回
**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 = > table.put in=`p` at="inputs" value=`输入表`**
*p*
## 会话开启
@@ -178,12 +180,13 @@ JSON 进 / JSON 出:把 `输入` 编码到 stdin,解析 stdout JSON 返回
+ `代码`=None
+ `源码`=None
+ `输入`=None
+ `标准输入`=None
+ `超时`=None
在会话中求值代码(code 值)或源码文本;返回带 id/alive 的记录。
`输入` 会编码为 JSON 交给内核。
*> host_foreign_session_eval id=`标识` code=`代码` source=`源码` input=`输入` timeout=`超时`*
*> host_foreign_session_eval id=`标识` code=`代码` source=`源码` input=`输入` stdin=`标准输入` timeout=`超时`*
## 会话设值
+ `标识`
@@ -202,6 +205,13 @@ JSON 进 / JSON 出:把 `输入` 编码到 stdin,解析 stdout JSON 返回
*> host_foreign_session_get id=`标识` name=`名称`*
## 会话中断
+ `标识`
中断持久内核当前求值;worker 支持时,会话仍可用于下一次求值。
*> host_foreign_session_interrupt id=`标识`*
## 会话变量
+ `标识`
+19 -2
View File
@@ -217,6 +217,7 @@ pub enum HostFn {
ForeignSessionNames = 208,
ForeignSessionClose = 209,
ForeignSessionList = 210,
ForeignSessionInterrupt = 211,
}
@@ -424,6 +425,7 @@ impl HostFn {
208 => Self::ForeignSessionNames,
209 => Self::ForeignSessionClose,
210 => Self::ForeignSessionList,
211 => Self::ForeignSessionInterrupt,
_ => return None,
})
}
@@ -515,6 +517,7 @@ impl HostFn {
"host_foreign_session_names" | "foreign_session_names" => Self::ForeignSessionNames,
"host_foreign_session_close" | "foreign_session_close" => Self::ForeignSessionClose,
"host_foreign_session_list" | "foreign_session_list" => Self::ForeignSessionList,
"host_foreign_session_interrupt" | "foreign_session_interrupt" => Self::ForeignSessionInterrupt,
"host_foreign_langs" => Self::ForeignLangs,
"host_dotenv_load" | "load_dotenv" => Self::DotenvLoad,
"host_http_request" | "http_request" => Self::HttpRequest,
@@ -726,6 +729,7 @@ impl HostFn {
Self::ForeignSessionNames => "host_foreign_session_names",
Self::ForeignSessionClose => "host_foreign_session_close",
Self::ForeignSessionList => "host_foreign_session_list",
Self::ForeignSessionInterrupt => "host_foreign_session_interrupt",
Self::ForeignLangs => "host_foreign_langs",
Self::DotenvLoad => "host_dotenv_load",
Self::HttpRequest => "host_http_request",
@@ -904,6 +908,7 @@ impl HostFn {
Self::ForeignSessionNames => &["id"],
Self::ForeignSessionClose => &["id"],
Self::ForeignSessionList => &[],
Self::ForeignSessionInterrupt => &["id"],
Self::ForeignLangs => &[],
Self::PluginLoad => &["path"],
Self::PluginUnload | Self::PluginList => &[],
@@ -1053,7 +1058,7 @@ impl HostFn {
"concurrency",
],
Self::ForeignSessionOpen => &["cmd", "env", "cwd", "timeout"],
Self::ForeignSessionEval => &["code", "source", "input", "timeout"],
Self::ForeignSessionEval => &["code", "source", "input", "stdin", "timeout"],
Self::ForeignSessionSet
| Self::ForeignSessionGet
| Self::ForeignSessionNames
@@ -1512,12 +1517,13 @@ pub fn call_host(
HostFn::ForeignSessionEval => {
#[cfg(feature = "exec-host")]
{
crate::host::foreign_session::eval(
crate::host::foreign_session::eval_with_stdin(
ctx,
require(bound, "id")?,
bound.get("code"),
bound.get("source"),
bound.get("input"),
bound.get("stdin").and_then(|v| v.reveal_text()),
bound.get("timeout"),
)
}
@@ -1580,6 +1586,17 @@ pub fn call_host(
Err("foreign unavailable in browser wasm".into())
}
}
HostFn::ForeignSessionInterrupt => {
#[cfg(feature = "exec-host")]
{
crate::host::foreign_session::interrupt(ctx, require(bound, "id")?)
}
#[cfg(not(feature = "exec-host"))]
{
let _ = (ctx, bound);
Err("foreign unavailable in browser wasm".into())
}
}
HostFn::ForeignSessionList => {
#[cfg(feature = "exec-host")]
{
+619 -7
View File
@@ -48,12 +48,16 @@ pub struct Cell {
pub line_end: u32,
pub source_hash: String,
pub kernel: String,
/// Per-cell raw stdin from foreign.session inputs=.
pub stdin: String,
pub listed: bool,
pub status: CellStatus,
pub runs: u64,
pub last_ms: u64,
pub last_ok: bool,
pub last_error: String,
/// Value returned by the last successful evaluation, used by explicit persist.
pub last_result: Value,
}
#[derive(Debug, Clone)]
@@ -87,6 +91,7 @@ pub struct DocumentSession {
pub journal: Vec<JournalRecord>,
pub value_store: HashMap<String, Value>,
pub cursor: usize,
pub generation: u64,
pub opened_ms: i64,
host: HostContext,
kernel_sessions: HashMap<String, String>,
@@ -170,16 +175,17 @@ fn plan_tables(
Option<Vec<HashMap<String, Value>>>,
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));
return Ok((None, None, None, None));
};
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));
return Ok((None, None, None, None));
};
let field = |name: &str| {
fields
@@ -203,7 +209,11 @@ fn plan_tables(
Some(Value::None) | None => None,
Some(v) => Some(table_rows(&v)?),
};
Ok((kernels, cells, values))
let inputs = match field("inputs") {
Some(Value::None) | None => None,
Some(v) => Some(table_rows(&v)?),
};
Ok((kernels, cells, values, inputs))
}
fn col_value<'a>(row: &'a HashMap<String, Value>, names: &[&str]) -> Option<&'a Value> {
@@ -272,12 +282,14 @@ fn collect_cells(stmts: &[crate::ast::Stmt], out: &mut Vec<Cell>, seen: &mut Has
line_end: *end_line,
source_hash: hash_source(&c.source),
kernel: String::new(),
stdin: String::new(),
listed: false,
status: CellStatus::Never,
runs: 0,
last_ms: 0,
last_ok: false,
last_error: String::new(),
last_result: Value::None,
});
}
crate::ast::Stmt::Branch { arms, .. } => {
@@ -294,6 +306,22 @@ fn collect_cells(stmts: &[crate::ast::Stmt], out: &mut Vec<Cell>, seen: &mut Has
Ok(())
}
fn fun_has_plan(fun: &crate::ast::Function) -> bool {
fun.body.iter().any(|stmt| match stmt {
crate::ast::Stmt::Assign { name, .. } => name == "会话",
_ => false,
}) || fun.children.iter().any(fun_has_plan)
}
fn has_nested_plan(module: &crate::ast::Module, entry_name: &str) -> bool {
module
.functions
.iter()
.find(|f| f.name == entry_name)
.map(|entry| entry.children.iter().any(fun_has_plan))
.unwrap_or(false)
}
impl DocumentSession {
pub fn open(path: &Path, root: &Path) -> Result<Self, String> {
let source = std::fs::read_to_string(path)
@@ -321,8 +349,14 @@ impl DocumentSession {
let mut seen = HashSet::new();
collect_cells(&entry.body, &mut cells, &mut seen)?;
let declarations = capture_bindings(path, root, &module, &source)?;
if !declarations.contains_key("会话") && has_nested_plan(&module, &entry.name) {
return Err(
"foreign.session: plan must be a top-level binding (`会话` = > foreign.session ...)"
.into(),
);
}
let (plan_kernels, plan_cells, plan_values) = plan_tables(&declarations)?;
let (plan_kernels, plan_cells, plan_values, plan_inputs) = plan_tables(&declarations)?;
let persistent = matches!(
declarations.get("会话"),
Some(Value::Map(fields))
@@ -432,6 +466,7 @@ impl DocumentSession {
journal: Vec::new(),
value_store: HashMap::new(),
cursor: 0,
generation: 1,
opened_ms: now_ms(),
host,
kernel_sessions: HashMap::new(),
@@ -455,6 +490,18 @@ impl DocumentSession {
)?;
}
}
if let Some(rows) = plan_inputs {
for row in rows {
let cell = col_text(&row, &["单元", "Cell", "cell", "单元名"])
.ok_or_else(|| "foreign.session inputs: missing 单元/Cell".to_string())?;
let raw = col_value(&row, &["stdin", "标准输入", "输入"])
.map(value_text)
.unwrap_or_default();
if let Some(i) = session.cell_index(&cell) {
session.cells[i].stdin = raw;
}
}
}
Ok(session)
}
@@ -581,6 +628,13 @@ impl DocumentSession {
c.last_ms = ms;
c.last_ok = ok;
c.last_error = error.clone();
c.last_result = field("result")
.filter(|v| !matches!(v, Value::None))
.unwrap_or_else(|| {
field("stdout")
.and_then(|v| v.reveal_text().map(|s| Value::Text(s.to_string())))
.unwrap_or(Value::None)
});
c.status = if ok { CellStatus::Clean } else { CellStatus::Error };
}
self.seq += 1;
@@ -614,6 +668,11 @@ impl DocumentSession {
if !self.cells[ci].listed && kernel_override.is_none() {
return Err(format!("cell `{cell_name}` is not listed in the foreign session"));
}
let stdin_owned = stdin.map(str::to_string).or_else(|| {
let s = self.cells[ci].stdin.clone();
if s.is_empty() { None } else { Some(s) }
});
let stdin = stdin_owned.as_deref();
if !self.persistent {
self.cells[ci].kernel = "one-shot".into();
self.cells[ci].status = CellStatus::Running;
@@ -666,12 +725,13 @@ impl DocumentSession {
let result = (|| -> Result<Value, String> {
let id = self.ensure_kernel_session(&kernel)?;
let source = Value::Text(self.cells[ci].source.clone());
let record = foreign_session::eval(
let record = foreign_session::eval_with_stdin(
&mut self.host,
&Value::Text(id),
None,
Some(&source),
stdin.map(|s| Value::Text(s.to_string())).as_ref(),
None,
stdin,
None,
)?;
self.record_result(cell_name, &kernel, &record)?;
@@ -692,6 +752,7 @@ impl DocumentSession {
return Ok(Value::Map(vec![
("done".into(), Value::Bool(true)),
("cursor".into(), Value::Int(self.cursor as i64)),
("generation".into(), Value::Int(self.generation as i64)),
]));
}
let name = self.order[self.cursor].clone();
@@ -717,6 +778,15 @@ impl DocumentSession {
&mut self,
restart: bool,
stdin: Option<&str>,
) -> Result<Value, String> {
self.run_all_with_inputs(restart, stdin, None)
}
pub fn run_all_with_inputs(
&mut self,
restart: bool,
stdin: Option<&str>,
inputs: Option<&HashMap<String, String>>,
) -> Result<Value, String> {
if restart {
self.restart_all()?;
@@ -725,7 +795,11 @@ impl DocumentSession {
let mut records = Vec::new();
let mut failed = 0i64;
for name in self.order.clone() {
let record = match self.run_cell_with_stdin(&name, None, stdin) {
let cell_stdin = inputs
.and_then(|m| m.get(&name))
.map(String::as_str)
.or(stdin);
let record = match self.run_cell_with_stdin(&name, None, cell_stdin) {
Ok(record) => record,
Err(error) => {
if let Some(i) = self.cell_index(&name) {
@@ -768,6 +842,20 @@ impl DocumentSession {
]))
}
pub fn interrupt(&mut self) -> Result<Value, String> {
let ids: Vec<String> = self.kernel_sessions.keys().cloned().collect();
let mut out = Vec::new();
for name in ids {
if let Some(id) = self.kernel_sessions.get(&name) {
match foreign_session::interrupt(&mut self.host, &Value::Text(id.clone())) {
Ok(_) => out.push(Value::Text(name)),
Err(e) => out.push(Value::Text(format!("{name}: {e}"))),
}
}
}
Ok(Value::List(out))
}
pub fn restart_kernel(&mut self, name: &str) -> Result<Value, String> {
if let Some(id) = self.kernel_sessions.remove(name) {
let _ = foreign_session::close(&mut self.host, &Value::Text(id));
@@ -810,9 +898,70 @@ impl DocumentSession {
self.cells[ci].kernel = kernel.to_string();
self.cells[ci].listed = true;
self.cells[ci].status = CellStatus::Dirty;
self.generation += 1;
Ok(Value::None)
}
pub fn add_cell(
&mut self,
cell: &str,
lang: &str,
source: &str,
kernel: &str,
) -> Result<Value, String> {
if self.cell_index(cell).is_some() {
return Err(format!("cell `{cell}` already exists"));
}
let lang = registry::canonical(lang);
let decl = self
.kernel(kernel)
.ok_or_else(|| format!("unknown kernel `{kernel}`"))?
.clone();
if registry::canonical(&decl.lang) != lang {
return Err(format!(
"cell `{cell}` ({lang}) cannot use kernel `{kernel}` ({})",
decl.lang
));
}
self.cells.push(Cell {
name: cell.to_string(),
lang,
source: source.to_string(),
line_start: 0,
line_end: 0,
source_hash: hash_source(source),
kernel: kernel.to_string(),
stdin: String::new(),
listed: true,
status: CellStatus::Never,
runs: 0,
last_ms: 0,
last_ok: false,
last_error: String::new(),
last_result: Value::None,
});
self.order.push(cell.to_string());
self.generation += 1;
Ok(Value::Bool(true))
}
pub fn remove_cell(&mut self, cell: &str) -> Result<Value, String> {
let Some(i) = self.cell_index(cell) else {
return Err(format!("unknown cell `{cell}`"));
};
self.cells.remove(i);
self.order.retain(|name| name != cell);
self.journal.retain(|j| j.cell != cell);
self.generation += 1;
Ok(Value::Bool(true))
}
pub fn set_value(&mut self, kernel: &str, name: &str, value: Value) -> Result<Value, String> {
let out = self.push_value(kernel, name, value)?;
self.generation += 1;
Ok(out)
}
pub fn state_list(&mut self) -> Result<Value, String> {
let marqdo = self
.value_store
@@ -885,6 +1034,7 @@ impl DocumentSession {
("last_ms".into(), Value::Int(c.last_ms as i64)),
("last_ok".into(), Value::Bool(c.last_ok)),
("last_error".into(), Value::Text(c.last_error.clone())),
("stdin".into(), Value::Text(c.stdin.clone())),
])
})
.collect();
@@ -913,6 +1063,7 @@ impl DocumentSession {
self.order.iter().cloned().map(Value::Text).collect(),
)),
("cursor".into(), Value::Int(self.cursor as i64)),
("generation".into(), Value::Int(self.generation as i64)),
("journal".into(), Value::List(
self.journal
.iter()
@@ -952,6 +1103,212 @@ impl DocumentSession {
}
/// Clear displayed outputs and per-cell records; kernels and live state survive.
/// Export plan, explicit values, kernel values and journal as JSON-safe data.
pub fn export_snapshot(&mut self) -> Result<Value, String> {
let mut kernels = Vec::new();
for decl in self.kernels.clone() {
let mut values = Vec::new();
if let Some(id) = self.kernel_sessions.get(&decl.name).cloned() {
if let Ok(Value::List(names)) =
foreign_session::names(&mut self.host, &Value::Text(id.clone()))
{
for name in names {
if let Value::Text(n) = &name {
if let Ok(v) = foreign_session::get(
&mut self.host,
&Value::Text(id.clone()),
&Value::Text(n.clone()),
) {
values.push(Value::Map(vec![
("name".into(), Value::Text(n.clone())),
("value".into(), v),
]));
}
}
}
}
}
kernels.push(Value::Map(vec![
("name".into(), Value::Text(decl.name.clone())),
("lang".into(), Value::Text(decl.lang.clone())),
("cmd".into(), Value::Text(decl.cmd.clone().unwrap_or_default())),
("values".into(), Value::List(values)),
]));
}
let cells = self
.cells
.iter()
.map(|c| {
Value::Map(vec![
("name".into(), Value::Text(c.name.clone())),
("lang".into(), Value::Text(c.lang.clone())),
("kernel".into(), Value::Text(c.kernel.clone())),
("source".into(), Value::Text(c.source.clone())),
("stdin".into(), Value::Text(c.stdin.clone())),
("status".into(), Value::Text(c.status.as_str().into())),
("runs".into(), Value::Int(c.runs as i64)),
("last_ok".into(), Value::Bool(c.last_ok)),
])
})
.collect();
let journal = self.journal_json();
Ok(Value::Map(vec![
("version".into(), Value::Int(1)),
("path".into(), Value::Text(self.path.display().to_string())),
("persistent".into(), Value::Bool(self.persistent)),
("generation".into(), Value::Int(self.generation as i64)),
("kernels".into(), Value::List(kernels)),
("cells".into(), Value::List(cells)),
("order".into(), Value::List(
self.order.iter().cloned().map(Value::Text).collect(),
)),
("journal".into(), journal),
]))
}
/// Import JSON-safe values from an exported snapshot. Source identity and
/// cell names must already match; no arbitrary objects are deserialized.
pub fn import_snapshot(&mut self, snapshot: &Value) -> Result<Value, String> {
let Value::Map(fields) = snapshot else {
return Err("snapshot must be a map".into());
};
let field = |name: &str| {
fields
.iter()
.find(|(k, _)| k == name)
.map(|(_, v)| v.clone())
};
let Some(Value::List(kernels)) = field("kernels") else {
return Err("snapshot: missing kernels".into());
};
let mut restored = 0i64;
for kernel in kernels {
let Value::Map(kfields) = kernel else { continue };
let get = |name: &str| {
kfields
.iter()
.find(|(k, _)| k == name)
.map(|(_, v)| v.clone())
};
let Some(Value::Text(name)) = get("name") else { continue };
if self.kernel(&name).is_none() {
return Err(format!("snapshot: unknown kernel `{name}`"));
}
let Some(Value::List(values)) = get("values") else { continue };
let id = self.ensure_kernel_session(&name)?;
for item in values {
let Value::Map(vfields) = item else { continue };
let getv = |name: &str| {
vfields
.iter()
.find(|(k, _)| k == name)
.map(|(_, v)| v.clone())
};
let Some(Value::Text(vname)) = getv("name") else { continue };
let Some(value) = getv("value") else { continue };
foreign_session::set(
&mut self.host,
&Value::Text(id.clone()),
&Value::Text(vname),
&value,
)?;
restored += 1;
}
}
if let Some(Value::List(cells)) = field("cells") {
for item in cells {
let Value::Map(cfields) = item else { continue };
let getc = |name: &str| {
cfields
.iter()
.find(|(k, _)| k == name)
.map(|(_, v)| v.clone())
};
let Some(Value::Text(name)) = getc("name") else { continue };
let Some(i) = self.cell_index(&name) else { continue };
if let Some(Value::Text(status)) = getc("status") {
self.cells[i].status = match status.as_str() {
"clean" => CellStatus::Clean,
"error" => CellStatus::Error,
"dirty" => CellStatus::Dirty,
"stale" => CellStatus::Stale,
"unlisted" => CellStatus::Unlisted,
_ => CellStatus::Never,
};
}
}
}
self.generation += 1;
Ok(Value::Int(restored))
}
/// Replay recorded cells in order, using the snapshot's per-cell stdin.
pub fn replay_snapshot(&mut self, snapshot: &Value) -> Result<Value, String> {
let Value::Map(fields) = snapshot else {
return Err("snapshot must be a map".into());
};
let cells = fields
.iter()
.find(|(k, _)| k == "cells")
.and_then(|(_, v)| match v {
Value::List(xs) => Some(xs.clone()),
_ => None,
})
.ok_or_else(|| "snapshot: missing cells".to_string())?;
let mut records = Vec::new();
for item in cells {
let Value::Map(cfields) = item else { continue };
let getc = |name: &str| {
cfields
.iter()
.find(|(k, _)| k == name)
.map(|(_, v)| v.clone())
};
let Some(Value::Text(name)) = getc("name") else { continue };
if self.cell_index(&name).is_none() {
continue;
}
let stdin = getc("stdin").and_then(|v| match v {
Value::Text(s) if !s.is_empty() => Some(s),
_ => None,
});
let record = self.run_cell_with_stdin(&name, None, stdin.as_deref())?;
let mut m = match record {
Value::Map(m) => m,
other => vec![("result".into(), other)],
};
m.push(("cell".into(), Value::Text(name)));
records.push(Value::Map(m));
}
Ok(Value::Map(vec![
("ok".into(), Value::Bool(true)),
("replayed".into(), Value::Int(records.len() as i64)),
("records".into(), Value::List(records)),
]))
}
/// Explicitly persist the last cell result through lib/writeback.
pub fn persist_cell(&mut self, cell: &str, key: &str) -> Result<Value, String> {
let i = self
.cell_index(cell)
.ok_or_else(|| format!("unknown cell `{cell}`"))?;
let value = self.cells[i].last_result.clone();
if matches!(value, Value::None) {
return Err(format!("cell `{cell}` has no result to persist"));
}
let key = if key.is_empty() { cell } else { key };
let line = self.cells[i].line_end.max(self.cells[i].line_start);
crate::host::writeback::record(
&mut self.host,
&value,
None,
Some(&Value::Text(key.to_string())),
Some(&Value::Int(line as i64)),
)?;
self.generation += 1;
Ok(Value::Bool(true))
}
pub fn clear_outputs(&mut self) -> Value {
for cell in &mut self.cells {
cell.runs = 0;
@@ -1339,6 +1696,261 @@ console.log(globalThis.kept);
let _ = std::fs::remove_file(&path);
}
#[test]
fn snapshot_export_import_restores_values() {
if !node_available() {
return;
}
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let path = root.join("tests/notebook/shared.mq.md");
let mut a = DocumentSession::open(&path, &root).unwrap();
a.set_value("分析", "rate", Value::Int(42)).unwrap();
let snap = a.export_snapshot().unwrap();
a.close();
let mut b = DocumentSession::open(&path, &root).unwrap();
let restored = b.import_snapshot(&snap).unwrap();
assert!(matches!(restored, Value::Int(n) if n > 0));
let rate = b.pull_value("分析", "rate").unwrap();
assert_eq!(rate, Value::Int(42));
b.close();
}
#[test]
fn nested_plan_is_rejected_at_open() {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let path = root.join(format!(
"target/view-nested-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 = "# main\n\n## view\n\n`会话` = > foreign.session\n";
std::fs::write(&path, source).unwrap();
let err = match DocumentSession::open(&path, &root) {
Ok(_) => panic!("nested plan should be rejected"),
Err(e) => e,
};
assert!(err.contains("top-level"), "{err}");
let _ = std::fs::remove_file(&path);
}
#[test]
fn nested_plan_helper_detects_child_binding() {
let src = "# main\n\n## view\n\n`会话` = > foreign.session\n";
let module = crate::parse::parse_source(src).unwrap();
assert!(has_nested_plan(&module, "main"));
}
#[test]
fn runtime_plan_add_remove_and_generation() {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let path = root.join("tests/notebook/shared.mq.md");
let mut s = DocumentSession::open(&path, &root).unwrap();
let before = s.generation;
s.add_cell("extra", "node", "console.log('extra');", "分析")
.unwrap();
assert!(s.generation > before);
assert!(s.cells.iter().any(|c| c.name == "extra"));
s.assign_kernel("extra", "分析").unwrap();
s.remove_cell("extra").unwrap();
assert!(!s.cells.iter().any(|c| c.name == "extra"));
assert!(s.generation > before + 1);
s.close();
}
#[test]
fn persist_cell_writes_a_keyed_slot() {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let path = root.join(format!(
"target/view-persist-{}-{}.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` =
```python
print(950)
```
"#;
std::fs::write(&path, source).unwrap();
let mut s = DocumentSession::open(&path, &root).unwrap();
s.run_cell("a", None).unwrap();
s.persist_cell("a", "total").unwrap();
let text = std::fs::read_to_string(&path).unwrap();
assert!(text.contains("marqdo-out total"), "{text}");
s.close();
let _ = std::fs::remove_file(&path);
}
#[test]
fn plan_inputs_feed_each_cell() {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let path = root.join(format!(
"target/view-plan-input-{}-{}.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: plan inputs test
import foreign:lib/foreign.mq.md
---
# main
`内核` =
| 名称 | 语言 |
|------|------|
| py | python |
`单元` =
| 单元 | 内核 |
|------|------|
| a | py |
`输入` =
| 单元 | stdin |
|------|-------|
| a | hello plan |
`会话` = > foreign.session kernels=`内核` cells=`单元` inputs=`输入`
`a` =
```python
import sys
print(sys.stdin.read().strip())
```
"#;
std::fs::write(&path, source).unwrap();
let mut s = DocumentSession::open(&path, &root).unwrap();
let summary = s.run_all_with_stdin(false, None).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!(
field(&records[0], "stdout").and_then(|v| v.reveal_text().map(|s| s.to_string())),
Some("hello plan\n".to_string())
);
s.close();
let _ = std::fs::remove_file(&path);
}
#[test]
fn persistent_node_cell_accepts_raw_stdin() {
if !node_available() {
return;
}
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let path = root.join(format!(
"target/view-node-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#"---
title: persistent node stdin test
import foreign:lib/foreign.mq.md
---
# main
`内核` =
| 名称 | 语言 |
|------|------|
| js | node |
`单元` =
| 单元 | 内核 |
|------|------|
| a | js |
`会话` = > foreign.session kernels=`内核` cells=`单元`
`a` =
```node
(async () => {
await new Promise((resolve) => {
let input = "";
process.stdin.on("data", (chunk) => { input += chunk; });
process.stdin.on("end", () => { console.log(input.trim()); resolve(); });
});
})();
```
"#;
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 node"))
.unwrap();
assert_eq!(
field(&record, "stdout").and_then(|v| v.reveal_text().map(|s| s.to_string())),
Some("hello node\n".to_string())
);
s.close();
let _ = std::fs::remove_file(&path);
}
#[test]
fn persistent_python_cell_accepts_raw_stdin() {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let path = root.join(format!(
"target/view-persistent-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#"---
title: persistent stdin test
import foreign:lib/foreign.mq.md
---
# main
`内核` =
| 名称 | 语言 |
|------|------|
| py | python |
`单元` =
| 单元 | 内核 |
|------|------|
| a | py |
`会话` = > foreign.session kernels=`内核` cells=`单元`
`a` =
```python
import sys
print(sys.stdin.read().strip())
```
"#;
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 persistent"))
.unwrap();
assert_eq!(
field(&record, "stdout").and_then(|v| v.reveal_text().map(|s| s.to_string())),
Some("hello persistent\n".to_string())
);
s.close();
let _ = std::fs::remove_file(&path);
}
#[test]
fn stateless_cell_accepts_stdin() {
if !node_available() {
+54
View File
@@ -53,6 +53,9 @@ for _line in sys.stdin:
continue
_code = req.get("code", "")
_g["marqdo_input"] = req.get("input")
_old_stdin = sys.stdin
if req.get("stdin") is not None:
sys.stdin = io.StringIO(str(req.get("stdin")))
_out_buf = io.StringIO()
_err_buf = io.StringIO()
try:
@@ -69,6 +72,8 @@ for _line in sys.stdin:
_send({"id": rid, "ok": True, "stdout": _out_buf.getvalue(), "stderr": _err_buf.getvalue(), "result": _result, "error": ""})
except BaseException:
_send({"id": rid, "ok": False, "stdout": _out_buf.getvalue(), "stderr": _err_buf.getvalue(), "result": None, "error": traceback.format_exc(limit=8)})
finally:
sys.stdin = _old_stdin
"#;
const JS_BOOTSTRAP: &str = r#"const readline = require("readline");
@@ -113,7 +118,21 @@ rl.on("line", async (line) => {
return;
}
globalThis.marqdo_input = req.input === undefined ? null : req.input;
const oldStdin = process.stdin;
let stdinPatched = false;
if (req.stdin !== undefined && req.stdin !== null) {
try {
const { PassThrough } = require("stream");
const ps = new PassThrough();
ps.end(String(req.stdin));
Object.defineProperty(process, "stdin", { value: ps, configurable: true, writable: true });
stdinPatched = true;
} catch (e) {}
}
const cap = await capture(async () => vm.runInThisContext(req.code || "", { filename: "<marqdo>" }));
if (stdinPatched) {
try { Object.defineProperty(process, "stdin", { value: oldStdin, configurable: true, writable: true }); } catch (e) {}
}
send({ id: rid, ok: !cap.error, stdout: cap.logs, stderr: cap.errs, result: toJSON(cap.result), error: cap.error });
});
"#;
@@ -425,6 +444,18 @@ pub fn eval(
source: Option<&Value>,
input: Option<&Value>,
timeout: Option<&Value>,
) -> Result<Value, String> {
eval_with_stdin(ctx, id, code, source, input, None, timeout)
}
pub fn eval_with_stdin(
ctx: &mut HostContext,
id: &Value,
code: Option<&Value>,
source: Option<&Value>,
input: Option<&Value>,
stdin: Option<&str>,
timeout: Option<&Value>,
) -> Result<Value, String> {
ensure_config(ctx);
let id = as_text(id, "id")?.to_string();
@@ -462,6 +493,7 @@ pub fn eval(
"op": "eval",
"code": code,
"input": input_json,
"stdin": stdin,
});
let start = Instant::now();
let (lang, cmd) = {
@@ -620,6 +652,28 @@ fn kill_session(ctx: &mut HostContext, id: &str) {
}
}
/// Interrupt the current evaluation without destroying the kernel. Python
/// reports KeyboardInterrupt through the normal result frame.
pub fn interrupt(ctx: &mut HostContext, id: &Value) -> Result<Value, String> {
let id = as_text(id, "id")?.to_string();
let session = ctx
.foreign_sessions
.get_mut(&id)
.ok_or_else(|| format!("foreign session `{id}` not found"))?;
#[cfg(unix)]
unsafe {
libc::kill(-(session.child.id() as i32), libc::SIGINT);
}
#[cfg(windows)]
{
let _ = Command::new("taskkill")
.args(["/PID", &session.child.id().to_string(), "/T", "/F"])
.output();
session.alive = false;
}
Ok(Value::Bool(true))
}
pub fn set(
ctx: &mut HostContext,
id: &Value,
+23 -1
View File
@@ -16,7 +16,7 @@ use marqdo::knowledge::{
resolve, reuse_json, stale_json, verify, verify_json, write_knowledge, KnowledgeOptions,
LearnInput, ReuseBudget,
};
use marqdo::view::{serve, serve_debug, write_static, DebugOptions, OutputOptions, ViewOptions};
use marqdo::view::{serve, serve_debug, write_capture, write_static, CaptureOptions, DebugOptions, OutputOptions, ViewOptions};
use marqdo::{Backend, RunOptions};
#[derive(Parser, Debug)]
@@ -374,6 +374,17 @@ enum ViewAction {
#[arg(long)]
no_exec: bool,
#[arg(long, value_name = "FILE")]
snapshot: Option<PathBuf>,
},
/// Capture live cell results for `view output --snapshot`
Capture {
#[arg(value_name = "PATH")]
path: Option<PathBuf>,
#[arg(short = 'o', long = "out", required = true)]
out: PathBuf,
},
}
@@ -509,6 +520,7 @@ fn try_main(cli: Cli) -> Result<i32> {
path: out_path,
out,
no_exec,
snapshot,
}) => {
write_static(OutputOptions {
path: out_path
@@ -516,6 +528,16 @@ fn try_main(cli: Cli) -> Result<i32> {
.unwrap_or_else(|| PathBuf::from(".")),
out_dir: out,
no_exec,
snapshot,
})?;
Ok(0)
}
Some(ViewAction::Capture { path: out_path, out }) => {
write_capture(CaptureOptions {
path: out_path
.or(path)
.unwrap_or_else(|| PathBuf::from(".")),
out,
})?;
Ok(0)
}
+86 -8
View File
@@ -3290,8 +3290,32 @@ body.notebook-page .code-head .nb-kernel {
font: 0.66rem/1.2 var(--sans);
cursor: pointer;
}
body.notebook-page .code-head .nb-clean {
body.notebook-page .code-head .nb-cell-stdin {
order: 4;
width: 8rem;
padding: 0.16rem 0.3rem;
border: 1px solid var(--nb-border);
border-radius: 3px;
background: var(--nb-bg);
color: var(--nb-text);
font: 0.62rem/1.2 var(--mono);
}
body.notebook-page .code-head .nb-persist {
order: 6;
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-persist:hover {
border-color: var(--nb-accent);
color: var(--nb-strong);
}
body.notebook-page .code-head .nb-clean {
order: 5;
padding: 0.14rem 0.4rem;
border: 1px solid var(--nb-border);
border-radius: 3px;
@@ -3305,7 +3329,7 @@ body.notebook-page .code-head .nb-clean:hover {
color: var(--nb-strong);
}
body.notebook-page .code-head .nb-badge {
order: 5;
order: 7;
padding: 0.14rem 0.34rem;
border: 1px solid var(--nb-border);
border-radius: 3px;
@@ -3317,7 +3341,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: 6;
order: 8;
display: flex;
align-items: center;
gap: 0.3rem;
@@ -3542,6 +3566,7 @@ body.notebook-page .wb-source-text { color: var(--nb-text); }
<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-interrupt">Interrupt</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>
@@ -3637,6 +3662,22 @@ body.notebook-page .wb-source-text { color: var(--nb-text); }
}
return sel;
}
function ensureCellStdin(el, c) {
var inp = el.querySelector(".nb-cell-stdin");
if (!inp) {
inp = document.createElement("input");
inp.className = "nb-cell-stdin";
inp.placeholder = "stdin";
inp.autocomplete = "off";
var head = el.querySelector(".code-head");
if (head) head.appendChild(inp);
}
if (c && inp.dataset.loaded !== "1") {
inp.value = c.stdin || "";
inp.dataset.loaded = "1";
}
return inp;
}
function clearCard(el) {
var out = el.querySelector(".code-out");
if (out) {
@@ -3667,6 +3708,23 @@ body.notebook-page .wb-source-text { color: var(--nb-text); }
}).catch(function (e2) { status(String(e2)); });
});
}
function bindPersist(el) {
var btn = el.querySelector(".nb-persist");
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 (!name) return;
if (!live) {
status("static export: persist is unavailable");
return;
}
post("api/session/cell/persist", { cell: name, key: name }).then(function (r) {
status(r.ok ? "persisted " + name : (r.error || "persist failed"));
}).catch(function (e2) { status(String(e2)); });
});
}
function renderRecord(name, rec) {
var el = card(name);
if (!el || !rec) return;
@@ -3729,6 +3787,7 @@ body.notebook-page .wb-source-text { color: var(--nb-text); }
var el = card(c.name);
if (!el) return;
badge(el, c.status, c.status === "clean");
ensureCellStdin(el, c);
if (!state.persistent) {
ensureKernel(el, false);
return;
@@ -3758,7 +3817,9 @@ body.notebook-page .wb-source-text { color: var(--nb-text); }
});
}
function runOne(name) {
return post("api/session/cell/run", { cell: name, stdin: cellStdin() }).then(function (r) {
var inputEl = document.querySelector('.code-card[data-code-name="' + name + '"] .nb-cell-stdin');
var stdinValue = inputEl && inputEl.value ? inputEl.value : cellStdin();
return post("api/session/cell/run", { cell: name, stdin: stdinValue }).then(function (r) {
if (r.ok) { renderRecord(name, r.record); if (r.session) renderSummary(r.session); }
else status(r.error || "run failed");
});
@@ -3782,7 +3843,13 @@ body.notebook-page .wb-source-text { color: var(--nb-text); }
}).catch(function (e) { status(String(e)); });
return;
}
post("api/session/run_all", { restart: !!restart, stdin: cellStdin() }).then(function (r) {
var perCell = {};
document.querySelectorAll(".code-card").forEach(function (el) {
var inp = el.querySelector(".nb-cell-stdin");
var name = el.getAttribute("data-code-name");
if (inp && name && inp.value) perCell[name] = inp.value;
});
post("api/session/run_all", { restart: !!restart, stdin: cellStdin(), inputs: perCell }).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) || [];
@@ -3849,7 +3916,7 @@ body.notebook-page .wb-source-text { color: var(--nb-text); }
function staticNotice() {
status("静态页面无法真实执行 / static export: no live execution");
}
["nb-run-all", "nb-restart", "nb-step", "nb-state", "nb-journal",
["nb-run-all", "nb-restart", "nb-step", "nb-interrupt", "nb-state", "nb-journal",
"nb-clear", "nb-reload", "nb-debug", "exec-clear"].forEach(function (id) {
bind(id, staticNotice);
});
@@ -3866,13 +3933,24 @@ body.notebook-page .wb-source-text { color: var(--nb-text); }
ensureKernel(el, false);
});
}
document.querySelectorAll(".code-card").forEach(bindClean);
document.querySelectorAll(".code-card").forEach(function (el) {
bindClean(el);
bindPersist(el);
});
status("static export · preview only");
return;
}
document.querySelectorAll(".code-card").forEach(bindClean);
document.querySelectorAll(".code-card").forEach(function (el) {
bindClean(el);
bindPersist(el);
});
bind("nb-run-all", function () { runAll(false); });
bind("nb-restart", function () { runAll(true); });
bind("nb-interrupt", function () {
post("api/session/interrupt", {}).then(function (r) {
status(r.ok ? "interrupt sent" : (r.error || "interrupt failed"));
});
});
bind("nb-step", function () {
if (!state.persistent && Object.keys(state.cells).length === 0) {
status("no cells; Run All runs the document");
+46 -1
View File
@@ -10,7 +10,7 @@ mod notebook_api;
mod output;
mod render;
pub use output::{write_static, OutputOptions};
pub use output::{write_capture, write_static, CaptureOptions, OutputOptions};
use std::fs;
use std::io::{self, Read};
@@ -194,6 +194,51 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
notebook_api::api_run_document(&root.root, body)
})
}
"/api/session/snapshot/export" => {
return api_debug_post(request, |body| {
notebook_api::api_export_snapshot(&root.root, body)
})
}
"/api/session/snapshot/import" => {
return api_debug_post(request, |body| {
notebook_api::api_import_snapshot(&root.root, body)
})
}
"/api/session/snapshot/replay" => {
return api_debug_post(request, |body| {
notebook_api::api_replay_snapshot(&root.root, body)
})
}
"/api/session/plan/assign" => {
return api_debug_post(request, |body| {
notebook_api::api_plan_assign(&root.root, body)
})
}
"/api/session/plan/add" => {
return api_debug_post(request, |body| {
notebook_api::api_plan_add(&root.root, body)
})
}
"/api/session/plan/remove" => {
return api_debug_post(request, |body| {
notebook_api::api_plan_remove(&root.root, body)
})
}
"/api/session/plan/value" => {
return api_debug_post(request, |body| {
notebook_api::api_plan_value(&root.root, body)
})
}
"/api/session/cell/persist" => {
return api_debug_post(request, |body| {
notebook_api::api_persist_cell(&root.root, body)
})
}
"/api/session/interrupt" => {
return api_debug_post(request, |body| {
notebook_api::api_interrupt(&root.root, body)
})
}
"/api/session/cell/clear" => {
return api_debug_post(request, |body| {
notebook_api::api_clear_cell(&root.root, body)
+92 -1
View File
@@ -170,6 +170,44 @@ where
}
}
pub fn api_persist_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("");
let key = v.get("key").and_then(|x| x.as_str()).unwrap_or("");
if cell.is_empty() {
return err("missing cell".into());
}
with_session(root, body, "persisted", |s| s.persist_cell(cell, key))
}
pub fn api_interrupt(root: &Path, body: &str) -> serde_json::Value {
with_session(root, body, "interrupted", |s| s.interrupt())
}
pub fn api_export_snapshot(root: &Path, body: &str) -> serde_json::Value {
with_session(root, body, "snapshot", |s| s.export_snapshot())
}
pub fn api_import_snapshot(root: &Path, body: &str) -> serde_json::Value {
let v = body_value(body);
let snapshot = v.get("snapshot").cloned().unwrap_or(serde_json::Value::Null);
let snapshot = match json_to_value(&snapshot) {
Ok(v) => v,
Err(e) => return err(e),
};
with_session(root, body, "restored", |s| s.import_snapshot(&snapshot))
}
pub fn api_replay_snapshot(root: &Path, body: &str) -> serde_json::Value {
let v = body_value(body);
let snapshot = v.get("snapshot").cloned().unwrap_or(serde_json::Value::Null);
let snapshot = match json_to_value(&snapshot) {
Ok(v) => v,
Err(e) => return err(e),
};
with_session(root, body, "replay", |s| s.replay_snapshot(&snapshot))
}
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("");
@@ -204,7 +242,12 @@ 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);
let stdin = v.get("stdin").and_then(|x| x.as_str());
with_session(root, body, "summary", |s| s.run_all_with_stdin(restart, stdin))
let inputs: Option<HashMap<String, String>> = v.get("inputs").and_then(|x| x.as_object()).map(|m| {
m.iter()
.filter_map(|(k, val)| val.as_str().map(|s| (k.clone(), s.to_string())))
.collect()
});
with_session(root, body, "summary", |s| s.run_all_with_inputs(restart, stdin, inputs.as_ref()))
}
pub fn api_kernel_restart(root: &Path, body: &str) -> serde_json::Value {
@@ -216,6 +259,54 @@ pub fn api_kernel_restart(root: &Path, body: &str) -> serde_json::Value {
with_session(root, body, "value", |s| s.restart_kernel(kernel))
}
pub fn api_plan_assign(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()).unwrap_or("");
if cell.is_empty() || kernel.is_empty() {
return err("missing cell/kernel".into());
}
with_session(root, body, "value", |s| s.assign_kernel(cell, kernel))
}
pub fn api_plan_add(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 lang = v.get("lang").and_then(|x| x.as_str()).unwrap_or("");
let kernel = v.get("kernel").and_then(|x| x.as_str()).unwrap_or("");
let source = v.get("source").and_then(|x| x.as_str()).unwrap_or("");
if cell.is_empty() || lang.is_empty() || kernel.is_empty() {
return err("missing cell/lang/kernel".into());
}
with_session(root, body, "value", |s| s.add_cell(cell, lang, source, kernel))
}
pub fn api_plan_remove(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, "value", |s| s.remove_cell(cell))
}
pub fn api_plan_value(root: &Path, body: &str) -> serde_json::Value {
let v = body_value(body);
let kernel = v.get("kernel").and_then(|x| x.as_str()).unwrap_or("");
let name = v.get("name").and_then(|x| x.as_str()).unwrap_or("");
if kernel.is_empty() || name.is_empty() {
return err("missing kernel/name".into());
}
let value = match v.get("value") {
Some(v) => match json_to_value(v) {
Ok(v) => v,
Err(e) => return err(e),
},
None => Value::None,
};
with_session(root, body, "value", |s| s.set_value(kernel, name, value))
}
pub fn api_assign(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("");
+135 -2
View File
@@ -5,8 +5,10 @@ use std::fs;
use std::path::PathBuf;
use anyhow::{Context, Result};
use sha2::{Digest, Sha256};
use crate::host::foreign_doc::DocumentSession;
use crate::host::json::json_to_value;
use crate::value::Value;
use crate::view::html::{escape, page_file, page_index, LinkMode};
use crate::view::{build_file_view, build_root, ViewRoot};
@@ -15,6 +17,12 @@ pub struct OutputOptions {
pub path: PathBuf,
pub out_dir: PathBuf,
pub no_exec: bool,
pub snapshot: Option<PathBuf>,
}
pub struct CaptureOptions {
pub path: PathBuf,
pub out: PathBuf,
}
#[derive(Debug, Clone)]
@@ -23,6 +31,12 @@ struct StaticCellOutput {
text: String,
}
fn source_hash(source: &str) -> String {
let mut h = Sha256::new();
h.update(source.as_bytes());
format!("{:x}", h.finalize())
}
fn value_text(v: &Value) -> Option<String> {
match v {
Value::Text(s) => Some(s.clone()),
@@ -59,7 +73,8 @@ fn static_page_data(
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 {
let page_stdin = if stdin.trim().is_empty() { None } else { Some(stdin) };
let Ok(summary) = session.run_all_with_stdin(false, page_stdin) else {
session.close();
return (out, None);
};
@@ -170,7 +185,91 @@ fn inject_static_session(html: &str, summary: Option<&Value>) -> String {
html.replace("window.MARQDO_VIEW_LIVE = false;", &line)
}
/// Capture live-cell results into a snapshot consumed by `view output --snapshot`.
pub fn write_capture(opts: CaptureOptions) -> Result<()> {
let root = build_root(&opts.path)?;
let mut pages = serde_json::Map::new();
for rel_pb in &root.files {
let rel = rel_pb.to_string_lossy().replace('\\', "/");
let abs = resolve_abs(&root, &rel)?;
let vm = build_file_view(&root, &abs, &rel, &[], false)?;
let (outputs, summary) = static_page_data(&root, &abs, &vm.preset_stdin);
let mut out_map = serde_json::Map::new();
for (name, output) in outputs {
out_map.insert(
name,
serde_json::json!({ "ok": output.ok, "text": output.text }),
);
}
let summary_json = summary
.as_ref()
.and_then(|v| crate::host::json::value_to_json(v).ok())
.unwrap_or(serde_json::Value::Null);
pages.insert(
rel.clone(),
serde_json::json!({
"source_hash": source_hash(&vm.source),
"summary": summary_json,
"outputs": out_map,
}),
);
}
let doc = serde_json::json!({ "version": 1, "pages": pages });
if let Some(parent) = opts.out.parent() {
fs::create_dir_all(parent)?;
}
fs::write(&opts.out, serde_json::to_string_pretty(&doc)?)
.with_context(|| format!("write {}", opts.out.display()))?;
eprintln!("marqdo view capture: {} page(s) → {}", root.files.len(), opts.out.display());
Ok(())
}
fn snapshot_page(
snapshot: &serde_json::Value,
rel: &str,
source: &str,
) -> Result<(HashMap<String, StaticCellOutput>, Option<Value>)> {
let page = snapshot
.get("pages")
.and_then(|p| p.get(rel))
.ok_or_else(|| anyhow::anyhow!("snapshot has no page `{rel}`"))?;
let expected = page
.get("source_hash")
.and_then(|v| v.as_str())
.unwrap_or("");
if expected != source_hash(source) {
anyhow::bail!("snapshot source hash mismatch for `{rel}`");
}
let mut outputs = HashMap::new();
if let Some(map) = page.get("outputs").and_then(|v| v.as_object()) {
for (name, value) in map {
outputs.insert(
name.clone(),
StaticCellOutput {
ok: value.get("ok").and_then(|v| v.as_bool()).unwrap_or(false),
text: value
.get("text")
.and_then(|v| v.as_str())
.unwrap_or("")
.to_string(),
},
);
}
}
let summary = page
.get("summary")
.filter(|v| !v.is_null())
.and_then(|v| json_to_value(v).ok());
Ok((outputs, summary))
}
pub fn write_static(opts: OutputOptions) -> Result<()> {
let snapshot = match &opts.snapshot {
Some(path) => Some(serde_json::from_str::<serde_json::Value>(
&fs::read_to_string(path).with_context(|| format!("read {}", path.display()))?,
)?),
None => None,
};
let root = build_root(&opts.path)?;
fs::create_dir_all(&opts.out_dir)
.with_context(|| format!("create {}", opts.out_dir.display()))?;
@@ -204,7 +303,9 @@ pub fn write_static(opts: OutputOptions) -> Result<()> {
let links = LinkMode::Static {
from: Some(rel.clone()),
};
let (cell_outputs, static_summary) = if opts.no_exec {
let (cell_outputs, static_summary) = if let Some(snapshot) = &snapshot {
snapshot_page(snapshot, &rel, &vm.source)?
} else if opts.no_exec {
(HashMap::new(), None)
} else {
static_page_data(&root, &abs, &vm.preset_stdin)
@@ -263,6 +364,38 @@ fn resolve_abs(root: &ViewRoot, rel: &str) -> Result<PathBuf> {
mod tests {
use super::*;
#[test]
fn snapshot_page_rejects_source_hash_mismatch() {
let snap = serde_json::json!({
"pages": {
"a.mq.md": {
"source_hash": "bad",
"summary": null,
"outputs": {}
}
}
});
assert!(snapshot_page(&snap, "a.mq.md", "# main\n").is_err());
}
#[test]
fn snapshot_page_reads_outputs_and_summary() {
let source = "# main\n";
let hash = source_hash(source);
let snap = serde_json::json!({
"pages": {
"a.mq.md": {
"source_hash": hash,
"summary": {"persistent": false, "cells": [], "kernels": []},
"outputs": {"a": {"ok": true, "text": "42"}}
}
}
});
let (outputs, summary) = snapshot_page(&snap, "a.mq.md", source).unwrap();
assert_eq!(outputs["a"].text, "42");
assert!(summary.is_some());
}
#[test]
fn injects_visible_static_cell_outputs() {
let html = r#"<div class="card" data-code-name="a"></div><pre class="code-out" hidden></pre>"#;
+2
View File
@@ -1260,6 +1260,7 @@ fn render_stmt(
<code class="expr">`{name}` =</code>
<span class="code-lang">{lang}</span>
<button type="button" class="nb-clean" title="Clear this output">Clean</button>
<button type="button" class="nb-persist" title="Persist this result with writeback">Persist</button>
</div>
<pre class="code-body"><code class="language-{lang}">{src}</code></pre>
<div class="code-foot">
@@ -1539,6 +1540,7 @@ pub(crate) fn render_code_assign_card(name: &str, lang: &str, source: &str) -> S
<span class="code-name">{name}</span>
<span class="code-lang">{lang}</span>
<button type="button" class="nb-clean" title="Clear this output">Clean</button>
<button type="button" class="nb-persist" title="Persist this result with writeback">Persist</button>
</div>
<pre class="code-body"><code class="language-{lang}">{src}</code></pre>
<div class="code-foot">