Files
marqdo/doc/design/stdlib-writeback.md
T
cflmyandCursor f47a1e143a feat(writeback): image form ![marqdo-out](…) with view parity
Auto-persist image paths/URLs as Markdown images (validated extension);
keep HTML comment for text. View and static export share styled source
markers and output-card <img> rendering.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 15:45:52 +08:00

3.0 KiB
Raw Permalink Blame History

自写回标准库(writeback)

状态 v1 已落地
日期 2026-08-07
库 lib/writeback.mq.md · lib/自写回.mq.md

定位

Jupyter 输出单元的 Marqdo 等价物:执行得到结果 → record / 写回 写入入口 .mq.md → marqdo view(及静态 view output)在对应语句下显示 output-card,并在源码面用 writeback 样式标出块本身。

存储格式(两种,可并存)

1. HTML 注释(文本 / 结构化输出)

*`n` = > len value=`xs` *
<!-- marqdo-out
42
-->

命名槽(智能体成功/失败互不覆盖):

<!-- marqdo-out ok
status=ok result=…
-->
<!-- marqdo-out error
pending
-->

2. Markdown 图片(生成图 / 审计友好)

当 value 看起来像图片引用(扩展名 .png / .jpg / .jpeg / .gif / .webp / .svg / …,或 data:image/…)时,record 自动写成:

![marqdo-out](plots/out.svg)
![marqdo-out ok](plots/ok.png)
  • 普通 Markdown 预览即可看见图;view / 静态站额外加 writeback 标记与 output-card 中的 <img>。
  • 非图片路径仍走注释块;把非图片硬写成 ![marqdo-out](…) 时扫描会忽略(校验失败)。
  • list / scan_path 结果带 kind: comment | image。

共用规则

  • 标记字为 marqdo-out,可选后跟槽名(ok / error 等),不存行号
  • 默认在调用行下方插入或替换紧邻无键块
  • at_end=true:替换文件末尾的无键块
  • key= / 键=:在当前调用锚点下方创建或替换该命名槽;ensure 在缺失时写入占位且不覆盖已有正文
  • line= / 行=:显式锚点行号;主机侧有全局互斥锁

替换跨度与空行

替换 <!-- marqdo-out … --> 时,被替换跨度包含注释块结束 --> 后的单个换行符(不把该换行留在文件里)。这样多次 record 不会在块下方累积多余空行。

命名槽仍锚在调用行(如 step / 写回)下方;整簇结束后保留一条有意空行即可,且应稳定。

API

EN ZH 说明
record 写回 value=;可选 at_end、key、line
get 取 可选 at_end、key、line
clear 清除 可选 at_end、key、line
ensure 确保 key= + 可选 placeholder=、line=;槽已存在则不动
list 列出 全文所有输出块(命名槽含 key 字段)

可选参数语法:+ `参数名`=默认值(与现有参数列表兼容)。

Host:host_writeback_*(src/host/writeback.rs);智能体侧经 lib/subtask 异步调用写回,避免阻塞推理主路径。

与 ext/ai/agent: ## step / ## 单步 在 D2 起 默认自动 record 到 ok/error 槽(参数 writeback= / 写回= 可关)。多步工作簿依赖此默认,见 ext-agent-plan.md · ext-agent.md。