# 设计:解析器诊断缺陷修复(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`) 每一步独立提交,便于回滚。