- 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。
8.1 KiB
Executable File
设计:解析器诊断缺陷修复(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:调用侧贪婪匹配已知函数名(否决)
按「已知函数名的最长前缀」匹配。
否决理由:
- 需要把「所有已定义函数名」带进表达式解析上下文,跨越模块边界后不可判定
> print text=hello world里hello world会被尝试拼成函数名,语义歧义- 改变所有多词行的解析路径,属于核心语义变更,收益远小于风险
方案 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. 实施顺序
- D9(分类层,影响面已量化)→ 测试 → 文档
- D8(定义期校验)→ 测试 → 文档
- 两条都做完后跑全仓库回归(
cargo test+ 抽样marqdo run)
每一步独立提交,便于回滚。