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>
3.0 KiB
3.0 KiB
自写回标准库(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 自动写成:


- 普通 Markdown 预览即可看见图;view / 静态站额外加 writeback 标记与 output-card 中的
<img>。 - 非图片路径仍走注释块;把非图片硬写成
时扫描会忽略(校验失败)。 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。