缺陷:`**s = "abc`(引号未闭合)被静默当成叙述丢弃,退出码 0,
没有输出也没有报错,该行凭空消失。对「文档即程序」来说这是最危险的一类
错误——文档看起来完整、能跑、check 通过,实际少了一节。
根因在**分类层**而不是解析层:
parse_quoted_string 里 `unterminated " string` 的报错一直都在,
但 matching_bold_close 扫描时遇到未闭合的 '"' 后一直处于 in_str 状态,
再也找不到收尾 '**',于是 is_marqdo_star_line 返回 false,
该行被判为 LineKind::Comment 成为叙述,解析器根本看不到它。
解析层精心准备的报错不可达。
修复(两层,缺一不可):
1. src/lex/mod.rs
- 新增 pub fn has_unterminated_string:统计未被 \ 转义的 '"',奇数即「开了没收」
- is_marqdo_star_line:粗体起始且找不到收尾时,若引号未闭合则仍判 Code
(判 Comment 会静默丢行;判 Code 才能让解析器说话)
2. src/parse/mod.rs
- parse_simple_stmt 紧跟既有粗体分支之后,对「粗体起始 + 引号未闭合」
给出精确报错,而不是笼统的 unrecognized statement
影响面(改前量化,避免凭直觉改核心解析):
- 全仓库 845 个 .mq.md、620 个含代码行文件
- 引号计数为奇数的代码行:**0**
- 结论:不改变任何现有文件的解析结果,只作用于畸形输入
测试(TDD,先写测试确认失败再修):
- 新增 4 个单测:未闭合→Code、闭合→Code、叙述含引号→Comment、
叙述含孤立引号→Comment
- 修复前 unterminated_quote_inside_bold_is_code_not_comment 如期失败
- 修复后 lex 14/14;cargo test --lib 237 passed 0 failed(基线 233 + 新增 4)
- cargo test --test gold 276 passed 8 failed;git stash 验证基线同样 8 failed,
失败全部是 ext_web_*(依赖 Go 插件 libweb,本机环境不具备),与本次无关
文档:
- doc/design/parser-diagnostics-d8-d9.md 设计依据、根因链路、候选方案评判、影响面
- doc/design/change-d9-unterminated-string.md 变更记录(现象/根因/改法/测试/边界)
- doc/design/spaced-function-names-d8.md D8 方案评估(待审阅,未改代码)
已知边界:单引号 '...' 未闭合仍是旧行为,留作后续评估
(单引号兼作英文撇号,误判风险高于双引号)。
209 lines
8.1 KiB
Markdown
209 lines
8.1 KiB
Markdown
# 设计:解析器诊断缺陷修复(D8 / D9)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **Accepted** |
|
||
| 日期 | 2026-10-22 |
|
||
| 来源 | [qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) D8 / D9 |
|
||
| 影响面 | **核心解析**(`src/lex/mod.rs` 行分类 + `src/parse/expr.rs` 函数调用) |
|
||
| 关联 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-vs-comment.md](code-vs-comment.md) |
|
||
|
||
---
|
||
|
||
## 0. 为什么这两条要先做调研
|
||
|
||
D8 与 D9 都落在**行分类**这一层:它决定一行是「叙述」还是「代码」。
|
||
改错的代价是**整类文档解析结果变化**,而不是某个函数行为变化。
|
||
所以本文先量化影响面、列出候选方案并逐条否决,再动手。
|
||
|
||
一句话结论:
|
||
|
||
- **D9** 的根因是分类层把「引号未闭合的粗体行」降级为叙述,
|
||
导致解析层精心准备的 `unterminated " string` 报错**永远走不到**。
|
||
修法是在分类层补一条「粗体起始但闭合搜索失败」的判定,让它进入解析层报错。
|
||
语料实测 620 个文件 0 处受影响,风险可控。
|
||
- **D8** 的根因是函数名解析按空格切词,与定义侧不对称。
|
||
修法是在**定义期**拒绝含空格的函数名(fail fast),
|
||
而不是在调用期做贪婪匹配(那会改变所有多词行的语义)。
|
||
|
||
---
|
||
|
||
## 1. D9 — 未闭合引号静默吞行
|
||
|
||
### 1.1 现状链路
|
||
|
||
```
|
||
源码行 "**s = \"abc"
|
||
↓ classify_source → classify_line
|
||
↓ 首字符 '*' → is_marqdo_star_line?
|
||
trimmed.starts_with("**") → matching_bold_close(trimmed)
|
||
→ matching_bold_close_opts(require_eol=true)
|
||
扫描时遇 '"' → in_str = true
|
||
之后没有任何 '"' 关闭它 → 后续 '*' 全部被当作字符串内容跳过
|
||
返回 None(找不到收尾 **)
|
||
→ is_marqdo_star_line = false
|
||
↓ classify_line 落到 `Some('*') if !is_marqdo_star_line` → LineKind::Comment
|
||
↓ 该行成为**叙述**,parser 根本看不到它
|
||
↓ parse_quoted_string 里 `bail!("unterminated {quote} string")` 不可达
|
||
```
|
||
|
||
**结论**:这不是解析器的 bug,是**分类器的静默降级**。
|
||
解析层已经把错误信息写好了,却没有人把这一行送到它面前。
|
||
|
||
### 1.2 影响(为什么算高严重度)
|
||
|
||
| 场景 | 后果 |
|
||
|------|------|
|
||
| 手写漏一个引号 | 该行消失;变量未定义 → 在别处报 `undefined variable`,方向被引偏 |
|
||
| LLM 生成文档 | 少一段内容,但 `exit 0`、`marqdo check` 通过,**文档看起来完整却缺节** |
|
||
| CI/门禁 | 门禁试跑通过 → 错误文档被沉淀入库 |
|
||
|
||
对「文档即程序」而言,这属于最危险的一类:**静默产出错误结果**。
|
||
|
||
### 1.3 候选方案与评判
|
||
|
||
#### 方案 A:分类层补判定(采纳)
|
||
|
||
在 `is_marqdo_star_line` 中,当 `trimmed.starts_with("**")` 且
|
||
`matching_bold_close` 返回 `None` 时,再判断「这一行是否**像**粗体代码」:
|
||
|
||
- 行内含有 `=`(赋值)或 `>` 前导(调用)等强代码信号
|
||
- 且引号计数为奇数
|
||
|
||
满足则**仍判为 Code**,让解析层去报 `unterminated " string`。
|
||
|
||
**优点**
|
||
- 改动局限在分类层,不动解析语义
|
||
- 复用解析层已有的、措辞准确的报错
|
||
- 对「正常叙述中含 `**` 强调」零影响(那些行引号是配对的)
|
||
|
||
**风险**:叙述里恰好出现 `**…"…` 这种畸形组合会被判成代码 → 报错。
|
||
但实测语料 0 例,且这种组合本身就是写法错误,报错是**期望行为**。
|
||
|
||
#### 方案 B:解析层预扫描(否决)
|
||
|
||
在 `parse_classified` 前加一遍全文引号配对检查。
|
||
|
||
**否决理由**:引号可以合法地出现在叙述、围栏代码块、行内代码里。
|
||
全文扫描无法区分上下文,会制造大量假阳性(例如叙述里写「他说 "你好」)。
|
||
逐行判断需要的是**分类**信息,而这正是方案 A 在做的事。
|
||
|
||
#### 方案 C:放宽 `matching_bold_close`,引号未闭合时也认 `**` 收尾(否决)
|
||
|
||
**否决理由**:会改变「粗体闭合」的语义。`**s = "a ** b"` 这类行
|
||
会提前在中间 `**` 处闭合,把字符串拆断,产生更难理解的错误。
|
||
这是把静默错误换成**更混乱的错误**,不是改进。
|
||
|
||
### 1.4 影响面实测
|
||
|
||
对仓库内全部 `.mq.md`(`target/` 除外)做静态扫描:
|
||
|
||
| 指标 | 数值 |
|
||
|------|------|
|
||
| `.mq.md` 文件总数 | 845 |
|
||
| 含 `**` 起始代码行的文件 | 620 |
|
||
| **引号计数为奇数的代码行** | **0** |
|
||
|
||
扫描时正确跳过了 `\` 转义(`\"` 不算引号开合)。
|
||
结论:修复不会改变任何现有文件的解析结果。
|
||
|
||
### 1.5 验收
|
||
|
||
| 用例 | 期望 |
|
||
|------|------|
|
||
| `**s = "abc`(未闭合) | 报 `unterminated " string`,退出码非 0 |
|
||
| `**s = "abc"`(闭合) | 正常运行 |
|
||
| 跨行 `**s = "a` + `b"**` | 报错(不跨行拼接,符合现状) |
|
||
| 叙述 `他说 "你好"` | 仍是叙述,不受影响 |
|
||
| 全量 `cargo test` | 233 全绿 |
|
||
| 全仓库重跑 `marqdo check` | 无新增错误 |
|
||
|
||
---
|
||
|
||
## 2. D8 — 函数名含空格:定义成功、调用必崩
|
||
|
||
> **⚠️ 本节方案已作废。** 原主张「定义期拒绝空格」违背了「完全兼容 Markdown」:
|
||
> `## 用户 登录流程` 是合法标题,不该为了可调用而改写。
|
||
> 现行评估见 [spaced-function-names-d8.md](spaced-function-names-d8.md)(Proposed · 待审阅)。
|
||
> 本文其余部分(D9)仍然有效。
|
||
|
||
### 2.1 现状链路
|
||
|
||
```
|
||
定义侧:## 加一 号 → 标题整体作为函数名 "加一 号"(允许空格)
|
||
|
||
调用侧:> 加一 号 n=1
|
||
↓ 按空白切词
|
||
token[0] = "加一" → 当作函数名
|
||
token[1..] = ["号", "n=1"]
|
||
↓ "号" 无 `=` → 按位置参数/变量插值处理
|
||
↓ 变量 "号" 不存在 → undefined variable `号`
|
||
```
|
||
|
||
两侧不对称:定义时把整串当名字,调用时只取第一个词。
|
||
|
||
### 2.2 候选方案与评判
|
||
|
||
#### 方案 A:定义期拒绝空格(**已否决**)
|
||
|
||
解析 `## 函数名` 时,若函数名含空白则报错:
|
||
|
||
```
|
||
error: 文件:行: function name may not contain spaces: `加一 号`
|
||
(write `加一_号`, or quote the call as `> "加一 号"`)
|
||
```
|
||
|
||
**优点**
|
||
- fail fast:错误在定义处暴露,与调用处报 `undefined variable` 相比指向明确
|
||
- 不改变任何合法程序的语义
|
||
- 与「标识符不含空格」的通行约定一致
|
||
|
||
**风险**:可能已有文件用了空格函数名且**只定义不调用**(今天能跑)。
|
||
需先扫描语料确认。
|
||
|
||
#### 方案 B:调用侧贪婪匹配已知函数名(否决)
|
||
|
||
按「已知函数名的最长前缀」匹配。
|
||
|
||
**否决理由**:
|
||
1. 需要把「所有已定义函数名」带进表达式解析上下文,跨越模块边界后不可判定
|
||
2. `> print text=hello world` 里 `hello world` 会被尝试拼成函数名,语义歧义
|
||
3. 改变所有多词行的解析路径,属于核心语义变更,收益远小于风险
|
||
|
||
#### 方案 C:只警告不报错(否决)
|
||
|
||
**否决理由**:D8 的危害正是「check 通过、运行崩」。继续给警告等于维持现状。
|
||
|
||
### 2.3 影响面实测
|
||
|
||
统计仓库内**定义侧含空格**的 `##`/`###` 标题(仅可调用的层级):
|
||
|
||
| 指标 | 数值 |
|
||
|------|------|
|
||
| 含空格的二级及以下标题 | 4 |
|
||
| 其中位于源码(非运行时目录)的 | **0** |
|
||
| 分布 | 全部在 `.marqdo/agent/contexts/*.mq.md` 运行时生成物,且是叙述性标题("Existing Capabilities"),从未被调用 |
|
||
|
||
结论:源码中不存在含空格的函数名,加定义期校验不会破坏任何现有模块。
|
||
运行时生成的 context 文件不受影响——它们不被 import。
|
||
|
||
### 2.4 验收
|
||
|
||
| 用例 | 期望 |
|
||
|------|------|
|
||
| `## 加一 号` | 报 `function name may not contain spaces` |
|
||
| `## 加一_号` + 调用 | 正常 |
|
||
| `## 断言干净`(中文连写) | 正常 |
|
||
| 方法 `### 名字 带空格` | 同样拒绝 |
|
||
| 全量测试 | 233 全绿 |
|
||
|
||
---
|
||
|
||
## 3. 实施顺序
|
||
|
||
1. D9(分类层,影响面已量化)→ 测试 → 文档
|
||
2. D8(定义期校验)→ 测试 → 文档
|
||
3. 两条都做完后跑全仓库回归(`cargo test` + 抽样 `marqdo run`)
|
||
|
||
每一步独立提交,便于回滚。
|