外联执行结果的持久化ok

---
markup: occlusion
title: 外联执行结果的持久化
description: 静态快照与自写回 —— 外联结果在进程退出后如何保留
导入:
  外联: lib/外联.mq.md
  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` 本身里的活文档用自写回。两者可以共存于同一个仓库：静态页面给读者，自写回示例给作者和审计。