Files
marqdo/doc/roadmap/next-phase.md
T
cflmyandCursor ecc92f473a Unify frontmatter imports as import bind:target and drop > imports.
`import json:lib/json.mq.md` binds file libraries; `import fmt:time.format`
binds member short names (replaces `> use`). Legacy `> path.mq.md` / `> use`
now hard-error with a hint. Migrates repo docs, skills, ext, lib, public, examples,
man-test and tests; adds a negative gold and updates view/catalog rendering.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-13 10:03:21 +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;或日后 import text: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 插件或大而全标准库。