Files
marqdo/doc/roadmap/next-phase.md
T
cflmyandCursor 1f23e2ed93 Add module namespaces and harden L1/agent after the import redesign.
Bind imports to library names with bare path calls (and use), forward optional host args through mq wrappers, stabilize writeback replacement newlines, and document the M1/M2 decisions.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 13:28:32 +08:00

9.9 KiB
Raw Blame History

下一阶段:从玩具到可用语言

状态 进行中(P3-D1–D3 live view 断点 v1)
日期 2026-08-05
目标 交互 I/O、可信诊断、可生长标准库;view 渐进成为调试宿主
相关 interpreter.md · keywords.md · pipeline-debug.md · view.md · view-debug.md

0. 现状快照(决策依据)

能力 现状 结论
print 树遍历 + 字节码均可用 够用
input CLI 双后端 + --stdin-file;frontmatter stdin:/输入:;live view 表单覆盖;无预置时 capture 提示补线 P1a + P1b 完成
诊断 语句级 path:line:col: message;字节码指令带 spans;errors 金样例双后端断言位置 P0 完成
view 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 文档浏览器
debug 独立 marqdo debug:断点 / 单步 / locals(树遍历) P3-D3 v1
标准库 S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络(stdlib-modules.md);数学/外联暂缓 P2 完成;五库扩展设计中
模块 module-namespace.md:M1+M2 已落地(库名绑定、库.成员 / use;无扁平合并) —

用户点名的三件事都对,但不能并行硬开:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;input 在 CLI 与 view 是两条路径。


1. 轻重缓急(总序)

P0  诊断加固(短、撬动后续一切)
P1  输入补完(先 CLI,再 view)
P2  最小标准库(内置 + 可选 .mq.md 库)
P3  view 调试(断点 / 单步)—— 在 P0 之后分期,勿一上来做 DAP
优先级 主题 为何此刻 不做的代价
P0 诊断完备度 便宜;给金样例、字节码、调试打地基 断点停错行;双后端错误体验分裂
P1 input 「真语言」最低交互面;已有半截实现 只能写纯计算/打印 demo
P2 标准库 无库则用户无法写稍大程序 人人自造轮子、示例膨胀
P3 前端调试 差异化(文档即调试);成本最高 view 仍停留在「跑完看 stdout」

原则: 先让 CLI 树遍历成为完备参考实现;字节码跟进同语义;view 只接「已有事件/钩子」,不单独发明第二套语义。


2. P0 — 诊断与错误模型(约 3–7 天)

目标

所有用户可见失败统一为:

path:line:col: message

树遍历与字节码同文案、同位置粒度(至少语句级);金样例断言位置而不只子串。

工作项

  1. 统一出口
    • 解析侧尽量只产 Diagnostic(减少裸 bail!("7:1: …"))。
    • 字节码编译/VM:错误携带 Span(或指令 → 源行映射)。
  2. 位置粒度
    • 短期:保持「语句起点」亦可;中期:为 Expr/CallExpr 补 span,让「未定义名」落在标识符上。
  3. 金样例
    • tests/errors/*:断言完整 path:line:col 前缀(或相对路径规范化后的形式)。
    • 补:类型错误、除零、循环条件、capture 下 input 等。
  4. 文档
    • 更新 pipeline-debug.md:错误码/严重级别可列为 P0.5(可选 E0001 一类,不阻塞)。

完成定义

  • cargo test:errors 金样例含位置。
  • 同一 .mq.md 在 --backend tree|bytecode 下诊断一致(允许实现细节差异写进豁免表)。
  • view 执行失败区仍可读,路径无 \\?\。

刻意不做

  • IDE DAP、完整堆栈 UI、sourcemap 可视化编辑器。

3. P1 — 输入(约 1–2 周)

分两轨:CLI 必须先绿;view 交互后做。

P1a — CLI 完备(高优先级)

项 说明
树遍历 已实现 stdin;补 tests/keywords/input.mq.md(用管道喂入)
字节码 增加 Op::Input(或等价 host call);与树同语义;capture 下同样拒绝或改走注入 API
文档/用户站 public/keywords/input.mq.md;说明「view 默认无交互 stdin」

完成定义:echo Alice | marqdo run … 与字节码后端输出一致;金样例稳定。

P1b — view / 静态站中的输入(中优先级,接在 P1a 后)

当前 run_file_capture 不能接真实 stdin——这是设计,不是偶然 bug。

推荐路径(由易到难):

  1. 脚本化注入(无 UI)
    • marqdo run --stdin-file answers.txt 或 frontmatter/--- 旁测数据。
    • view:执行前提供「预置输入行」文本框,一次性灌入队列。
  2. 实时交互(live view)
    • 执行到 input → 暂停 → HTTP/WS 返回 prompt → 用户提交一行 → 继续。
    • 依赖 P3 的「可暂停执行」钩子;可与断点共用会话模型。
  3. 静态 view output
    • 无服务器则只支持预置输入或跳过并标明 input skipped。

完成定义:live marqdo view 下至少一个带 input 的示例可点按跑通;静态导出行为有文档。


4. P2 — 标准库(约 2–3 周,可与 P1b/P3 前半重叠)

分层

L0  内置函数(解释器内)     len / str / int / float? / type?
L1  标准库模块(.mq.md)     文本、表/集合小工具;官方路径如 lib/ 或 std/
L2  生态约定                 catalog 收录;用户站专章

建议落地顺序

迭代 内容 依据
S0 len(文本/表)、str、int keywords.md 已列候选;字节码已有闲置 Op::Len 可接线
S1 表工具:取列、行数;字符串 trim/split(先内置或纯 mq 实现二选一) 文档型语言高频
S2 官方 lib/ 或 std/ + 导入约定(仍可用 frontmatter;或日后 > std/text.mq.md) 可生长而不破现有导入
S3 错误类型约定(如非法 int 文本 → 诊断) 依赖 P0

完成定义(S0)

  • 金样例 + 双后端;public/ 有对应介绍页。
  • 不引入 if/while 英文关键字(控制流仍归 Markdown 标记)。

刻意不做(本阶段)

  • 完整面向对象、包管理器、异步 I/O、HTTP 客户端(可列远期)。

5. P3 — 前端成为调试机构(约 3–6 周,分里程碑)

不要从 DAP/VS Code 插件开干。 view 已有 Structure / Source / Execution,是天然宿主。

flowchart LR
  P0loc[P0 可信位置] --> Pause[语句边界暂停钩子]
  Pause --> Sess[调试会话 API]
  Sess --> UI[view 断点与单步 UI]
  UI --> DAP[可选 DAP 适配]
里程碑 交付 依赖
D0 语句级源映射(树优先;字节码指令→行) P0
D1 运行时钩子:进入语句前可 pause;--trace-eval 结构化事件(JSON 行) D0
D2 进程内调试会话:设/清断点、continue、step over(先树遍历) D1
D3 view debug 模式:源码行点击断点;高亮当前行;侧栏 locals/栈;与文档模式切换 D2 + 少量 JS 或服务端推进
D4 与 P1b 合流:input 暂停复用同一会话 P1b
D5(可选) DAP 薄适配,供外部 IDE D2 稳定后

完成定义(D3 即「可用调试」)

  • 用户能在 marqdo view 对某 .mq.md 设断点、单步、看变量。
  • 文档站默认模式不变(一次执行);debug 为显式开关。
  • 断点命中行与 P0 诊断行一致(允许文档说明「语句起点」语义)。

风险与边界

  • 静态 gh-pages 无法真断点(无常驻 VM);调试仅 live view(或未来 WASM 解释器)。
  • 字节码调试可晚于树遍历一个迭代。

6. 推荐排期(可执行流程)

按「每段都可合并、可演示」切周,避免大爆炸:

周序 主题 可合并交付
W1 P0 诊断统一 + errors 金样例加固 双后端错误位置一致
W2 P1a input 字节码 + 管道金样例 + 用户文档 CLI 交互闭环
W3 P2-S0 len/str/int + 样例 「有点像语言」的第一批库
W4 P1b 预置输入(view 文本框 / --stdin-file) view 可跑含 input 的 demo
W5–W6 P3-D0–D2 暂停与会话 无 UI 也能用 API/CLI 单步
W7–W8 P3-D3 view 断点 UI + D4 与 input 暂停 调试机构第一版
并行/随后 P2-S1/S2 扩库;P3-D5 DAP 按反馈加

若人力紧:砍掉顺序为 D5 → S2 花活 → 字节码调试;不可砍:P0、P1a、P2-S0、D3 之前的 D0–D2。


7. 验收总表(「真正可用」最低线)

  1. I/O:CLI 上 print/input 双后端一致;view 至少支持预置或交互输入之一。
  2. 错误:失败必有稳定位置;常见错误有金样例;用户站不靠「瞎猜 stderr」。
  3. 库:至少 len/str/int 可用并有文档。
  4. 调试:live view 可断点 + 单步 + 看当前绑定(树遍历即可宣称 v1)。
  5. 不破坏:现有 tests/ 金样例与 public/ 用户站回归绿。

8. 文档与工程动作(开工时)

  1. 本文件定为「下一阶段宪法」;开工后把各 P 拆到 doc/design/ 子设计(input-interactive.md、stdlib.md、view-debug.md)。
  2. 每个里程碑:金样例 → 实现 → public/ 更新 →(若行为用户可见)再发版 / 刷 gh-pages。
  3. 版本建议:P1a+P0 可打 v0.0.4;P2-S0 打 v0.0.5;P3-D3 打 v0.1.0(「可用调试」语义升级)。

9. 一句话路线

先把错误说准、把输入在 CLI 做完,再长出最小标准库;最后把现有 view 升级成可暂停的调试宿主——而不是先做 IDE 插件或大而全标准库。