Files
marqdo/doc/design/pipeline-debug.md
T
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

76 lines
2.7 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 解释器流水线可视调试
| | |
|---|---|
| 状态 | 已定(开发期强制友好) |
| 日期 | 2026-08-04 |
| 参考 | [Crafting Interpreters — Scanning](https://www.craftinginterpreters.com/scanning.html)(先打 token)· [AstPrinter](https://craftinginterpreters.com/representing-code.html) · CLI `--dump-ast` 类实践 |
---
## 1. 目标
开发 `marqdo` 时,对任意 `.mq.md` 应能**分阶段看见**中间结果,避免黑盒;正式 `run` 默认安静,仅输出程序 `print` 的内容。
---
## 2. CLI 开关
```bash
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](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` 随阶段增长自动变完整 |