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>
77 lines
3.0 KiB
Markdown
77 lines
3.0 KiB
Markdown
# 自写回标准库(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 注释(文本 / 结构化输出)
|
||
|
||
```markdown
|
||
*`n` = > len value=`xs` *
|
||
<!-- marqdo-out
|
||
42
|
||
-->
|
||
```
|
||
|
||
命名槽(智能体成功/失败互不覆盖):
|
||
|
||
```markdown
|
||
<!-- marqdo-out ok
|
||
status=ok result=…
|
||
-->
|
||
<!-- marqdo-out error
|
||
pending
|
||
-->
|
||
```
|
||
|
||
### 2. Markdown 图片(生成图 / 审计友好)
|
||
|
||
当 `value` **看起来像图片引用**(扩展名 `.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` / `.svg` / …,或 `data:image/…`)时,`record` **自动**写成:
|
||
|
||
```markdown
|
||

|
||

|
||
```
|
||
|
||
- 普通 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-plan.md) · [ext-agent.md](ext-agent.md)。
|