Files
marqdo/doc/roadmap/next-phase.md
cflmyandCursor 784d5ec346 feat(stdlib): Mid2 M10 stats and log fields
Add thin mean/median/stdev and optional structured fields on log
lines; close Mid2 M7–M10 (zip skipped).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 09:42:13 +08:00

221 lines
10 KiB
Markdown
Raw Permalink 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.
# 下一阶段:从玩具到可用语言
| | |
|---|---|
| 状态 | **进行中**(P3-D1–D3 live view 断点 v1) |
| 日期 | 2026-08-05 |
| 目标 | 交互 I/O、可信诊断、可生长标准库;view 渐进成为调试宿主 |
| 相关 | [interpreter.md](interpreter.md) · [keywords.md](../design/keywords.md) · [pipeline-debug.md](../design/pipeline-debug.md) · [view.md](../design/view.md) · [view-debug.md](../design/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 + Mid M1–M6 + Mid2 M7–M10 已完成([stdlib-modules.md](../design/stdlib-modules.md) · [stdlib-mid2.md](../design/stdlib-mid2.md)) | **P2 + Mid1 + Mid2 完成** |
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
---
## 1. 轻重缓急(总序)
```text
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 天)
### 目标
所有用户可见失败统一为:
```text
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](../design/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 前半重叠)
### 分层
```text
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,是天然宿主。
```mermaid
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 解释器](browser-wasm.md) 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. 验收总表(「真正可用」最低线)
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 插件或大而全标准库。**