- 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。
5.7 KiB
Executable File
markup, title, description
| markup | title | description |
|---|---|---|
| occlusion | lib/自写回 | 将运行结果写回 .mq.md(Jupyter 式自写回) |
将运行结果写回 .mq.md(Jupyter 式自写回)
读取并维护持久化执行输出槽位。
能力与边界:记录与读取默认锚定入口的当前调用点;命名槽互相隔离。结构化章节修改使用文档库,而不是把自写回当作任意文档编辑器。
本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。
相对文件路径以 --fs-root 为准,省略时以被调用文件所在目录为准。写入需要显式 fs.write 授权,子进程需要 process.exec;纯计算无需 IO 权限。
开发时保持中英文语义一致,先组合公开库;仅在 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 … --> |
这里使用值、末尾=False、键=None、行=None。
调用效应:fs.write。
在入口文件中写入自写回块:若 值 像图片路径/URL(.png / .svg / … 或 data:image/…)则写成 ,否则写成 <!-- 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 | 扫描任意文件中的自写回槽(注释块与  图片;工作簿观察) |
这里使用路径。
调用效应:fs.read。
直接调用此函数:
marqdo call lib/自写回.mq.md 扫描路径 '路径="lib/writeback.mq.md"' --effects fs.read --fs-root . --json
扫描任意文件中的自写回槽(注释块与  图片;工作簿观察)。
完成后返回*[扫描任意文件中的自写回槽(注释块与 !marqdo-out(…) 图片;工作簿观察)](> host_writeback_scan_path path=路径)*。