原计划的"翻转默认 + 旧形硬报错"不可行:`[键](集合)` 与 `[描述](实现)` 外形相同, 翻转会让 506 处取元静默变义,硬报错又拿不到证据。改为**按文件声明**。 一、per-file markup - frontmatter `markup: occlusion`(或 `标记: 遮蔽`)决定该文件模式 - load.rs 先取模式,用 parse::expr::with_markup(线程局部压栈)包住解析 - 同一进程可同时加载两种模式的文件(imports);MARQDO_MARKUP 仍作进程默认 - 好处:迁移逐文件、可增量、可回滚,不存在半迁移的静默错义 二、`marqdo migrate labels [--write|--json]` 改写规则: [键](集合) → [键](access(集合, "键")) [`名`](集合) → [名](access(集合, `名`)) - [项](集合) → - [项](遍历 集合 为 项) 安全模型:改写 → 重解析 → 证明等价 → 才写 - 原文件按 classic 解析得 AST-A;改写后按 occlusion 解析得 AST-B - 反归一化 B(标签与键同名且 payload 为 access 的遮蔽还原成 Index) - Debug(A) == Debug(反归一化(B))(抹掉行号)才写入,否则原文件一字不动 只改代码行(LineKind::Code);表格行只改 **…** 单元格,散文 markdown 链接不碰; 链式索引由内向外改写,已迁移的有守卫不二次改。 三、access 提升为宿主函数 HostFn::Access(u16 id 212) 与旧取元逐字一致(Map 按键 / List 1-based / 缺键 missing map key); 进 HostFn 是为了两个后端共用同一实现,interp 里的特例已删除。 四、顺带修的两处真实语义缺陷 1. payload 继承外层"文本模式":`f text=[k](access(c,k))` 中 access 不被当调用 → `()` 内永远允许 callee(args) 2. 遮蔽形状判定过宽:`[问候] ([格式化] "Bo")` 误判为遮蔽 → 要求 `]` 后紧跟 `(`,否则落回方括号调用 五、全仓迁移结果 migrate labels: 256 index, 23 loop, 80 file written;0 文件被等价性拒绝; 迁移后 cargo test --release → 604 passed / 0 failed;再跑迁移幂等。 等价性检查先后抓出 4 类改写 bug(表格散文链接、payload 文本模式、链式索引、 遮蔽与方括号调用混淆),每类都是先拦下再修工具,未污染文件。 测试:6 个单测 + 3 个集成(干跑不写盘 / 写入后运行输出不变且幂等 / 等价失败文件不动);全量 604 passed / 0 failed(M3 后 595 + 9);双后端一致。 文档:doc/design/change-m7-migration.md
用户文档(可执行 · 可下载 · 中英双语)
本目录即面向访客的 Marqdo 介绍:每个 .mq.md 既是文稿也能 marqdo run,并随仓库 / 静态站一起下载。
双语约定: 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程。成对放在同一目录。标准库:拉丁路径用英文 API,中文路径用中文 API;JSON 仅 lib/json.mq.md。
| 路径 | 内容 |
|---|---|
00-welcome.mq.md / 00-欢迎.mq.md |
首页(英 / 中) |
structure/ |
基本结构 |
keywords/ |
关键字与 L0 内置 |
stdlib/ |
标准库(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件/自写回/子任务;v0.1.2+ 内置于 CLI) |
features/ |
特性迭代(含对象、官方 ext/) |
features/19-foreign-view-cells.mq.md / 19-外联视图单元.mq.md |
外联 v2 完整 Python 示例:probe / JSON call / 并行 / 持久内核 / 状态桥 / view 单元 |
features/20-okf-ekc.mq.md / 20-OKF与EKC.mq.md |
代码即文档、文档即知识:OKF 形态与 EKC 工程知识编译器 |
features/21-persistence.mq.md / 21-持久化.mq.md |
外联结果持久化:静态快照与 writeback |
官方扩展(非 stdlib):ext/llm、ext/agent、ext/web、ext/quantum、ext/linalg — 见 features/05-*.mq.md、06-*.mq.md、07-linalg.mq.md / 07-线性代数.mq.md 与 doc/design/ext-*.md。
中层标准库(Mid):08–12(re/encoding · path/fs · hash/secrets · csv/text · list/cli;及对应中文页)。
不放 errors/:失败样例只在 tests/errors/。
开发文档在 doc/。
浏览与生成 HTML
cargo run -- view public
cargo run -- view output public -o public
详见 user-site.md。