Files
marqdo/doc/design/pipeline-debug.md
T
cflmyandCursor fd36b92224 Emit structured JSON --trace-eval events with source spans.
Tree walk logs enter_fn/stmt/leave_fn; bytecode logs op events for print/input/call/return, paving the way for view debug pause hooks.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-04 17:37:45 +08:00

2.6 KiB
Raw Blame History

解释器流水线可视调试

状态 已定(开发期强制友好)
日期 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 行分类 每行:LINE kind=Comment|Code|Blank + 原文预览
--dump-tokens 词法 Token 流:type lexeme line:col
--dump-ast 语法 S 表达式或缩进树(模块/函数/语句)
--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 随阶段增长自动变完整