- 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。
2.7 KiB
Executable File
2.7 KiB
Executable File
解释器流水线可视调试
| 状态 | 已定(开发期强制友好) |
| 日期 | 2026-08-04 |
| 参考 | Crafting Interpreters — Scanning(先打 token)· AstPrinter · CLI --dump-ast 类实践 |
1. 目标
开发 marqdo 时,对任意 .mq.md 应能分阶段看见中间结果,避免黑盒;正式 run 默认安静,仅输出程序 print 的内容。
2. CLI 开关
marqdo run FILE [dumps...]
marqdo dump FILE --stage lines|tokens|ast|sema|all
| 标志 | 阶段 | 输出内容 |
|---|---|---|
--dump-lines |
行分类 | 每行:kind=Comment|Code|Blank + 原文;v0.3 行内位 [decl n] / [bold …] / [italic …] |
--dump-tokens |
词法 | Token 流:type lexeme line:col |
--dump-ast |
语法 | 模块/函数/语句;形参带 inferred;叙述死绑定 dead=[…] |
--dump-sema |
语义 | 作用域、导入图、提升后的符号表 |
--trace-eval |
求值 | JSON 行(stderr):语句级事件,含 path / span(line:col) |
--dump-bytecode |
字节码 | 反汇编 Program(指令旁带 @line:col;见 bytecode.md) |
--backend tree|bytecode |
执行后端 | 默认 tree;bytecode 走栈式 VM |
--dump-all |
以上全部 | 按管道顺序打印,段之间用横幅分隔 |
格式约定:
- dump 人类可读优先;段首统一:
=== marqdo: <stage> === --trace-eval:每条事件一行 JSON,例如
{"event":"stmt","path":"…","span":"5:1","kind":"call","callee":"print"}
树遍历:enter_fn/stmt/leave_fn;字节码:op(print/input/call/return)。- 有 dump 时:若求值未实现,仍打印已实现阶段再以非 0 退出(便于 M1 只测 lines)
3. 横幅示例
=== marqdo: lines (tests/structure/hello.mq.md) ===
1 Blank
2 Comment | # Hello World
3 Blank
4 Comment | 本程序调用...
5 Blank
6 Code | > print text=Hello World!
=== marqdo: end lines ===
4. 实现要点
- dump 逻辑放在
src/debug/(或各阶段fmt),不与安静求值路径搅在一起。 - 每个阶段纯函数:
input → (artifacts, diagnostics),CLI 负责打印。 - 单测可断言 dump 字符串包含关键行(稳定子集),避免绑死全文格式。
5. 与里程碑
| 里程碑 | 必须可用的 dump |
|---|---|
| M1 | --dump-lines(及可选 tokens 雏形) |
| M2 | --dump-ast |
| M3–M4 | --dump-sema、--trace-eval |
| 全程 | --dump-all 随阶段增长自动变完整 |