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.
This commit is contained in:
1 parent
8dcd69412f
commit
5acf026e0c
7 files changed
+112
-46
No files matched your search
@@ -5,6 +5,7 @@
|
||||
### Added
|
||||
|
||||
- **code 卡控制**:恢复每个代码卡的内核切换下拉与 Clean 按钮;Clean 清除单个 cell 输出/记录,不重启内核,动态走 `/api/session/cell/clear`,静态只清本地显示。
|
||||
- **持久化示例**:新增可运行 `examples/foreign-writeback/index.mq.md`,用 `foreign.run` + `writeback.record` 将结果写入 `.mq.md` 的 keyed 槽位;用户站新增独立的静态快照 vs 自写回说明页。
|
||||
- **view Cell stdin**:view 增加 `Cell stdin / input` 输入框,Run/Step/Run All 都会传给外联 cells;无状态 cell 使用 raw stdin,持久内核使用 `marqdo_input`;静态导出使用 frontmatter `stdin` 作为构建时输入。
|
||||
- **foreign 拥有视图会话**:新增 `foreign.session kernels= cells=`,返回 foreign 会话句柄;`view` 只消费 `会话` 绑定,不再识别 `内核表` / `会话表` 保留名。没有 `会话` 时,view cells 使用无状态一次性执行,不创建内核。清除输出已接通 `/api/session/clear`,普通 view 与 foreign cells 共用,并由 Execution 面板的 Clear 按钮清除页面输出;无 `会话` 的 view 在 Run All 时执行整个文档并回写 Execution(不再空转);静态导出与动态 view 共用同一套 View 外壳和按钮布局;静态页面执行按钮点击显示“静态页面无法真实执行”,不伪造成功;静态导出与 view 的 Run All 共用同一 foreign_doc `run_all` 路径;构建时实际执行代码单元并把 stdout/stderr 注入代码卡;静态示例通过代码 fallback 或 frontmatter `stdin` 提供输入,不再依赖空 stdin;`会话` 作为低层 session id 时不会被误判为 view plan;移除 `In []` / `Out []` 与 Notebook 品牌;没有新增 CLI 或第二个交互模式。
|
||||
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Foreign result writeback
|
||||
description: Execute a foreign code fence and persist the result into this .mq.md
|
||||
import foreign:lib/foreign.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
This is a runnable example, not a screenshot. Run it with:
|
||||
|
||||
```text
|
||||
marqdo run examples/foreign-writeback/index.mq.md
|
||||
```
|
||||
|
||||
The foreign fence below is a normal Marqdo code value. `foreign.run` executes it;
|
||||
`writeback.record` writes the result into a keyed output slot immediately below
|
||||
the call. Re-running replaces only the `total` slot.
|
||||
|
||||
`合计代码` =
|
||||
```python
|
||||
print(950)
|
||||
```
|
||||
|
||||
**结果 = > foreign.run code=`合计代码`**
|
||||
|
||||
**> writeback.record value=`结果` key="total"**
|
||||
<!-- marqdo-out total
|
||||
950
|
||||
-->
|
||||
|
||||
The keyed slot below is generated by the run:
|
||||
|
||||
查看源码,确认 `total` 槽位就在这次 writeback 调用下方。
|
||||
@@ -13,6 +13,7 @@
|
||||
| [`features/`](features/) | 特性迭代(含对象、官方 `ext/`) |
|
||||
| [`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`。
|
||||
|
||||
|
||||
@@ -145,29 +145,6 @@ print(json.dumps({
|
||||
|
||||
`查看` 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.
|
||||
|
||||
---
|
||||
|
||||
Persisting results: two complementary options.
|
||||
|
||||
The static export is the publishing snapshot. `marqdo view output` runs the cells and embeds their outputs in HTML; it does not mutate the source. Use it for user docs, reviews and links.
|
||||
|
||||
Writeback is for living reports. Pair `foreign` with `lib/writeback` when the source should retain the latest result:
|
||||
|
||||
```text
|
||||
import writeback:lib/writeback.mq.md
|
||||
`写回代码` =
|
||||
```python
|
||||
print(950)
|
||||
```
|
||||
|
||||
**结果 = > foreign.run code=`写回代码`**
|
||||
**> writeback.record value=`结果` key="total"**
|
||||
```
|
||||
|
||||
`writeback.record` writes an explicit `<!-- marqdo-out total ... -->` slot adjacent to the call. Keyed slots do not overwrite each other, and the slot can be reviewed and committed with the source. This is opt-in; it is not hidden kernel serialization.
|
||||
|
||||
Recommended split: static export for published user documentation; writeback for exploratory or audit documents that must keep the latest run result in the `.mq.md` itself.
|
||||
|
||||
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.
|
||||
|
||||
@@ -145,29 +145,6 @@ print(json.dumps({
|
||||
|
||||
`查看` 消费 `会话` 句柄。Run All 在 `分析` 内核执行 `计算`,在 `复核` 内核执行 `复核`;静态导出走同一批单元,并把真实输出嵌入页面。
|
||||
|
||||
---
|
||||
|
||||
执行结果持久化:两种互补方式。
|
||||
|
||||
静态导出是发布快照。`marqdo view output` 执行单元并把输出嵌入 HTML,不修改源码;适合用户文档、评审和链接分享。
|
||||
|
||||
自写回用于“活文档”。需要把最新结果留在源码里时,把 `外联` 和 `lib/writeback` 搭配使用:
|
||||
|
||||
```text
|
||||
import writeback:lib/writeback.mq.md
|
||||
`写回代码` =
|
||||
```python
|
||||
print(950)
|
||||
```
|
||||
|
||||
**结果 = > 外联.运行 代码=`写回代码`**
|
||||
**> writeback.record value=`结果` key="total"**
|
||||
```
|
||||
|
||||
`writeback.record` 会在调用点附近写入显式的 `<!-- marqdo-out total ... -->` 槽位;带 key 的槽位不会互相覆盖,可以随源码一起审阅和提交。这是显式动作,不是隐藏的内核序列化。
|
||||
|
||||
建议分工:面向用户的发布文档用静态导出;需要保留最新执行结果的探索/审计文档用自写回,把结果写进 `.mq.md` 便于跟踪。
|
||||
|
||||
语言上的重点:
|
||||
|
||||
`初始值` 表把同一个 Marqdo `订单` 值传给两个内核。内核态归 `外联` 管理。view 只渲染句柄和单元。`run` 仍然把同一份文档当程序执行。
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Persisting foreign execution results
|
||||
description: Static snapshots and writeback — how foreign results survive after the process exits
|
||||
---
|
||||
|
||||
# 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 |
|
||||
|
||||
The checked-in runnable example is [examples/foreign-writeback/index.mq.md](https://github.com/cflmy/marqdo/blob/main/examples/foreign-writeback/index.mq.md). Run it with `marqdo run examples/foreign-writeback/index.mq.md`; it writes a `total` slot containing `950` directly below the `writeback.record` call. Re-running replaces only that keyed slot.
|
||||
|
||||
Writeback is explicit. It is not hidden kernel serialization, does not persist arbitrary kernel memory, and does not touch a file unless the document calls it.
|
||||
|
||||
---
|
||||
|
||||
## Choosing
|
||||
|
||||
For published user docs, use the static snapshot. For a living report that must keep the latest run result in the `.mq.md` itself, use writeback. Both can coexist in one repository: static pages for readers, writeback examples for authors and audits.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: 外联执行结果的持久化
|
||||
description: 静态快照与自写回 —— 外联结果在进程退出后如何保留
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
外联代码有两种有用的形态:发布快照,以及把最新结果保留在源码里的活文档。两者回答不同的问题,不应混为一谈。
|
||||
|
||||
---
|
||||
|
||||
## 静态快照:发布结果
|
||||
|
||||
`marqdo view output` 执行文档单元,并把真实输出嵌入生成的 HTML。`.mq.md` 源码不会被修改。这是用户文档、评审和稳定链接的默认选择:读者不需要运行任何东西就能看到结果,源码保持干净。
|
||||
|
||||
静态快照是某个时间点的产物。外部服务变化后重新构建即可,不要把它当成实时看板。
|
||||
|
||||
---
|
||||
|
||||
## 自写回:把结果留在源码里
|
||||
|
||||
对于探索性或审计型文档,把 `外联` 和 `lib/writeback` 搭配使用。`writeback.record` 会在调用点附近写入带 key 的输出槽位。槽位在 Markdown 源码中可见,可以在 diff 中审阅,也可以随文档提交。
|
||||
|
||||
| 步骤 | 作用 |
|
||||
|------|------|
|
||||
| 外联.运行 / 外联.会话 | 执行外联代码并返回 Marqdo 值 |
|
||||
| writeback.record | 把该值持久化到命名槽位 |
|
||||
| git diff | 像审阅普通文档改动一样审阅结果 |
|
||||
|
||||
可运行示例已经放在仓库里:[examples/foreign-writeback/index.mq.md](https://github.com/cflmy/marqdo/blob/main/examples/foreign-writeback/index.mq.md)。运行 `marqdo run examples/foreign-writeback/index.mq.md`,它会在 `writeback.record` 调用下方写入包含 `950` 的 `total` 槽位。再次运行只替换这个 keyed 槽位。
|
||||
|
||||
自写回是显式动作。它不是隐藏的内核序列化,不持久化任意内核内存,也不会在文档没有调用时修改文件。
|
||||
|
||||
---
|
||||
|
||||
## 如何选择
|
||||
|
||||
面向用户的发布文档用静态快照;需要把最新执行结果留在 `.mq.md` 本身里的活文档用自写回。两者可以共存于同一个仓库:静态页面给读者,自写回示例给作者和审计。
|
||||
Reference in new issue
Block a user