Files
marqdo/lib/自写回.mq.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

5.7 KiB
Executable File
Raw Permalink Blame History

markup, title, description
markup title description
occlusion lib/自写回 将运行结果写回 .mq.md(Jupyter 式自写回)

将运行结果写回 .mq.md(Jupyter 式自写回)

读取并维护持久化执行输出槽位。

能力与边界:记录与读取默认锚定入口的当前调用点;命名槽互相隔离。结构化章节修改使用文档库,而不是把自写回当作任意文档编辑器。

本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。

相对文件路径以 --fs-root 为准,省略时以被调用文件所在目录为准。写入需要显式 fs.write 授权,子进程需要 process.exec;纯计算无需 IO 权限。

实现入口:src/host/writeback.rs

开发时保持中英文语义一致,先组合公开库;仅在 OS 或算法边界添加宿主原语并声明效应。修改后运行 marqdo check --narrative-ratio 本文件,并执行 tests/stdlib_tasks.rs 的真实任务。

写回

参数 类型 默认 说明
值 any 必填 待转换或保存的值;不会就地修改输入
末尾 any False 是否追加到目标区块末尾
键 any None 要读取、比较或更新的字段名或存储键
行 any None 加入受管理写回区块的文本行
返回 类型 说明
result any 在入口文件中写入自写回块:若 值 像图片路径/URL(.png / .svg / … 或 data:image/…)则写成 ![marqdo-out](…),否则写成 <!-- marqdo-out … -->

这里使用值、末尾=False、键=None、行=None。

调用效应:fs.write。

在入口文件中写入自写回块:若 值 像图片路径/URL(.png / .svg / … 或 data:image/…)则写成 ![marqdo-out](…),否则写成 <!-- marqdo-out … -->。默认在调用行下方插入或替换;末尾=true 时替换无键末尾块。带 键=(如 ok / error / 成功 / 失败)时只更新该命名槽,互不覆盖。可选 行= 锚定到指定源码行(子任务写回时需要)。

完成后返回*[在入口文件中写入自写回块:若 值 像图片路径/URL(.png / .svg / … 或 data:image/…)则写成 !marqdo-out(…),否则写成 ](> host_writeback_record value=值 at_end=末尾 key=键 line=行)*。

取

参数 类型 默认 说明
末尾 any False 是否追加到目标区块末尾
键 any None 要读取、比较或更新的字段名或存储键
行 any None 加入受管理写回区块的文本行
返回 类型 说明
result any 读取当前调用处紧邻无键块、无键末尾块,或命名槽

这里使用末尾=False、键=None、行=None。

调用效应:fs.read。

读取当前调用处紧邻无键块、无键末尾块,或命名槽。

完成后返回*[读取当前调用处紧邻无键块、无键末尾块,或命名槽](> host_writeback_get at_end=末尾 key=键 line=行)*。

清除

参数 类型 默认 说明
末尾 any False 是否追加到目标区块末尾
键 any None 要读取、比较或更新的字段名或存储键
行 any None 加入受管理写回区块的文本行
返回 类型 说明
result any 删除紧邻块、末尾块或命名槽

这里使用末尾=False、键=None、行=None。

调用效应:fs.write。

删除紧邻块、末尾块或命名槽。

完成后返回*[删除紧邻块、末尾块或命名槽](> host_writeback_clear at_end=末尾 key=键 line=行)*。

确保

参数 类型 默认 说明
键 any 必填 要读取、比较或更新的字段名或存储键
占位 any "pending" 创建受管理区块时使用的占位文本
行 any None 加入受管理写回区块的文本行
返回 类型 说明
result any 若命名槽不存在则创建并写入占位;已存在则不改动

这里使用键、占位="pending"、行=None。

调用效应:fs.write。

若命名槽不存在则创建并写入占位;已存在则不改动。

完成后返回*[若命名槽不存在则创建并写入占位;已存在则不改动](> host_writeback_ensure key=键 placeholder=占位 line=行)*。

列出

返回 类型 说明
result list 列出当前入口源码中的受管理输出槽位;不写入,也不读取其他文件

调用效应:fs.read。

列出当前入口源码中的受管理输出槽位;不写入,也不读取其他文件。

完成后返回*列出当前入口源码中的受管理输出槽位;不写入,也不读取其他文件*。

扫描路径

参数 类型 默认 说明
路径 any 必填 授权文件根目录内的路径
返回 类型 说明
result list 扫描任意文件中的自写回槽(注释块与 ![marqdo-out](…) 图片;工作簿观察)

这里使用路径。

调用效应:fs.read。

直接调用此函数:

marqdo call lib/自写回.mq.md 扫描路径 '路径="lib/writeback.mq.md"' --effects fs.read --fs-root . --json

扫描任意文件中的自写回槽(注释块与 ![marqdo-out](…) 图片;工作簿观察)。

完成后返回*[扫描任意文件中的自写回槽(注释块与 !marqdo-out(…) 图片;工作簿观察)](> host_writeback_scan_path path=路径)*。