Define mid-stdlib admission rules and a phased roadmap so general primitives land in lib/ instead of ABI plugins. Co-authored-by: Cursor <cursoragent@cursor.com>
10 KiB
10 KiB
下一阶段:从玩具到可用语言
| 状态 | 进行中(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 |
| 标准库 | 核心 L1 已完成(stdlib-modules.md);下一主线 = 中层 Mid(stdlib-mid.md · stdlib-mid 路线) | P2 完成;Mid M1–M6 规划中 |
| 模块 | 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
树遍历与字节码同文案、同位置粒度(至少语句级);金样例断言位置而不只子串。
工作项
- 统一出口
- 解析侧尽量只产
Diagnostic(减少裸bail!("7:1: …"))。 - 字节码编译/VM:错误携带
Span(或指令 → 源行映射)。
- 解析侧尽量只产
- 位置粒度
- 短期:保持「语句起点」亦可;中期:为
Expr/CallExpr补span,让「未定义名」落在标识符上。
- 短期:保持「语句起点」亦可;中期:为
- 金样例
tests/errors/*:断言完整path:line:col前缀(或相对路径规范化后的形式)。- 补:类型错误、除零、循环条件、capture 下
input等。
- 文档
- 更新 pipeline-debug.md:错误码/严重级别可列为 P0.5(可选
E0001一类,不阻塞)。
- 更新 pipeline-debug.md:错误码/严重级别可列为 P0.5(可选
完成定义
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。
推荐路径(由易到难):
- 脚本化注入(无 UI)
marqdo run --stdin-file answers.txt或 frontmatter/---旁测数据。- view:执行前提供「预置输入行」文本框,一次性灌入队列。
- 实时交互(live view)
- 执行到
input→ 暂停 → HTTP/WS 返回 prompt → 用户提交一行 → 继续。 - 依赖 P3 的「可暂停执行」钩子;可与断点共用会话模型。
- 执行到
- 静态
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 解释器 C5)。 - 字节码调试可晚于树遍历一个迭代。
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. 验收总表(「真正可用」最低线)
- I/O:CLI 上
print/input双后端一致;view 至少支持预置或交互输入之一。 - 错误:失败必有稳定位置;常见错误有金样例;用户站不靠「瞎猜 stderr」。
- 库:至少
len/str/int可用并有文档。 - 调试:live view 可断点 + 单步 + 看当前绑定(树遍历即可宣称 v1)。
- 不破坏:现有
tests/金样例与public/用户站回归绿。
8. 文档与工程动作(开工时)
- 本文件定为「下一阶段宪法」;开工后把各 P 拆到
doc/design/子设计(input-interactive.md、stdlib.md、view-debug.md)。 - 每个里程碑:金样例 → 实现 →
public/更新 →(若行为用户可见)再发版 / 刷gh-pages。 - 版本建议:P1a+P0 可打
v0.0.4;P2-S0 打v0.0.5;P3-D3 打v0.1.0(「可用调试」语义升级)。
9. 一句话路线
先把错误说准、把输入在 CLI 做完,再长出最小标准库;最后把现有 view 升级成可暂停的调试宿主——而不是先做 IDE 插件或大而全标准库。