Files
marqdo/doc/design/stdlib-writeback.md
T
cflmyandCursor fbece725e1 Enable default writeback on agent step and lock the plan design.
Document multi-step workbooks in ext-agent-plan, and make step/单步 persist ok/error slots unless writeback is turned off.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 13:47:34 +08:00

2.5 KiB
Raw Blame History

自写回标准库(writeback)

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

定位

Jupyter 输出单元的 Marqdo 等价物:执行得到结果 → record / 写回 写入入口 .mq.md 的 <!-- marqdo-out … --> → marqdo view 在对应语句下显示 output-card。普通 Markdown 预览不显示该区域。

存储格式

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

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

<!-- marqdo-out ok
status=ok result=…
-->
<!-- marqdo-out error
pending
-->
  • 注释内为 marqdo-out,可选后跟槽名(ok / error 等),不存行号
  • 默认在调用行下方插入或替换紧邻无键块
  • at_end=true:替换文件末尾的无键块
  • key= / 键=:在当前调用锚点下方创建或替换该命名槽(智能体单步用父调用行,即 step 语句下方);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。