Files
marqdo/doc/design/parser-diagnostics-d8-d9.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

8.1 KiB
Executable File
Raw Permalink Blame History

设计:解析器诊断缺陷修复(D8 / D9)

状态 Accepted
日期 2026-10-22
来源 qdagent-refactor-defects-2026-10.md D8 / D9
影响面 核心解析(src/lex/mod.rs 行分类 + src/parse/expr.rs 函数调用)
关联 markdown-mapping-v0.3.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(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)

每一步独立提交,便于回滚。