diff --git a/CHANGELOG.md b/CHANGELOG.md index f0eecff..27f5466 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 或第二个交互模式。 diff --git a/examples/foreign-writeback/index.mq.md b/examples/foreign-writeback/index.mq.md new file mode 100644 index 0000000..e37441c --- /dev/null +++ b/examples/foreign-writeback/index.mq.md @@ -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"** + + +The keyed slot below is generated by the run: + +查看源码,确认 `total` 槽位就在这次 writeback 调用下方。 diff --git a/public/README.md b/public/README.md index 067b978..987fd7e 100644 --- a/public/README.md +++ b/public/README.md @@ -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`。 diff --git a/public/features/19-foreign-view-cells.mq.md b/public/features/19-foreign-view-cells.mq.md index a2e70db..5fcbfa4 100644 --- a/public/features/19-foreign-view-cells.mq.md +++ b/public/features/19-foreign-view-cells.mq.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 `` 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. diff --git a/public/features/19-外联视图单元.mq.md b/public/features/19-外联视图单元.mq.md index e685efe..d526a8b 100644 --- a/public/features/19-外联视图单元.mq.md +++ b/public/features/19-外联视图单元.mq.md @@ -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` 会在调用点附近写入显式的 `` 槽位;带 key 的槽位不会互相覆盖,可以随源码一起审阅和提交。这是显式动作,不是隐藏的内核序列化。 - -建议分工:面向用户的发布文档用静态导出;需要保留最新执行结果的探索/审计文档用自写回,把结果写进 `.mq.md` 便于跟踪。 - 语言上的重点: `初始值` 表把同一个 Marqdo `订单` 值传给两个内核。内核态归 `外联` 管理。view 只渲染句柄和单元。`run` 仍然把同一份文档当程序执行。 diff --git a/public/features/21-persistence.mq.md b/public/features/21-persistence.mq.md new file mode 100644 index 0000000..dd022e6 --- /dev/null +++ b/public/features/21-persistence.mq.md @@ -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. diff --git a/public/features/21-持久化.mq.md b/public/features/21-持久化.mq.md new file mode 100644 index 0000000..fb75bbf --- /dev/null +++ b/public/features/21-持久化.mq.md @@ -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` 本身里的活文档用自写回。两者可以共存于同一个仓库:静态页面给读者,自写回示例给作者和审计。