- 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。
221 lines
10 KiB
Markdown
Executable File
221 lines
10 KiB
Markdown
Executable File
# 下一阶段:从玩具到可用语言
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **进行中**(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 插件或大而全标准库。**
|