- 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。
9.0 KiB
Executable File
方案评估:函数名含空格的调用(D8)
| 状态 | Proposed · 待审阅(未实施任何代码改动) |
| 日期 | 2026-10-22 |
| 来源 | qdagent-refactor-defects-2026-10.md D8 |
| 前置 | parser-diagnostics-d8-d9.md(该文方案 A「禁止空格」已被否决,见 §0) |
| 影响面 | 核心解析:src/parse/expr.rs 调用切词 / src/lex 行分类 / 名称解析 |
0. 为什么原方案被否决
原方案 A 主张「定义期拒绝含空格的函数名」。这是错的,理由是我此前忽略的一句话:
Marqdo 的立身之本就是完全兼容 Markdown。
## 用户 登录 是一个完全合法的 Markdown 二级标题。真实文档里这类标题极多:
## 用户 登录流程
## 第三阶段 数据校验
## Appendix A Results
如果禁止这些标题当函数名,等于强迫作者为了「能调用」而改写标题措辞—— 这恰恰把「代码即文档」降级成「代码迁就文档」。作者写的标题首先应当是他自己想写的标题。
结论:空格必须被支持,问题只在于「怎么把带空格的名字准确传给调用」。
1. 事实基础(全部实测,1.5.2)
先固定真实行为,避免方案讨论建立在猜测上。
1.1 定义侧
| 输入 | 结果 |
|---|---|
## 加一 号 |
✅ 定义成功,函数名原样为 加一 号(parse_object_decl 走 Ok((raw.to_string(), None))) |
## 用户 登录流程 |
✅ 同上 |
定义侧完全支持空格,不需要任何改动。
1.2 调用侧
| 输入 | 结果 | 原因 |
|---|---|---|
> 加一 号 n=1 |
❌ undefined variable 号 |
parse_call_tail 用 split_whitespace().next() 只取首词 |
> [加一_号] n=1 |
✅ 正常(返回 2) | 方括号标记调用已存在且工作 |
> [加一 号] n=1 |
❌ unknown function [加一 |
is_bracket_callee_inner 第 1248 行显式拒绝含空白 |
`加一 号` 作为表达式 |
❌ undefined variable 加一 号 |
反引号名走变量解析,找不到函数 |
1.3 关键发现
方括号标记调用(
[callee])已经存在且实现完整, 挡住带空格名字的是is_bracket_callee_inner里的两处校验, 而不是一处(首轮评估低估了)。
这是本次评估最重要的发现:不需要发明新语法,只需要让既有机制接受空格。
1.4 可行性实测(已做,未保留改动)
为回答「放开后运行时到底能不能查到含空格的函数名」,做了受控实验:
临时放开两处校验 → 编译 → 跑用例 → 立即回退(src/parse/expr.rs 已恢复原样)。
| 关卡 | 位置 | 原逻辑 | 放开后 |
|---|---|---|---|
| 1 | is_bracket_callee_inner |
t.chars().any(is_whitespace) → 拒绝 |
删除该检查 |
| 2 | 同函数末尾 bare-name 白名单 | is_alphanumeric() | '_' | '.' | !is_ascii() |
追加 | c == ' ' |
实验结果
| 用例 | 结果 |
|---|---|
## 加一 号 + > [加一 号] n=1 |
✅ 返回 2(运行时函数表正确命中含空格名) |
## 加一_号 + > [加一_号] n=1(对照) |
✅ 仍返回 2,既有行为不变 |
全量 cargo test --lib |
✅ 237 passed, 0 failed |
结论:方案 1 技术上完全成立,且不破坏既有测试。 (237 = 基线 233 + 本轮 D9 新增的 4 个分类测试。)
注意:实验只证明「可行」,未固化。正式实施需要补 §4 的全部 V1–V9 用例, 特别是 V3–V7 的歧义排除,再决定是否合入。
2. 候选方案
方案 1 — 放开方括号内的空格(推荐)
做法:把 is_bracket_callee_inner 的「含空白即拒绝」改为「允许空白,
但需与既有歧义守卫共存」;并确认调用链后续不再按空格切词。
用法:
## 用户 登录流程
+ `账号`
*"已登录 " + `账号`*
# main
> [用户 登录流程] 账号=alice
*""
优点
- 不新增语法:
[…]标记调用是既有的正式特性,只是被一行校验挡住 - 向后兼容:所有现有调用(含
[加一_号])行为不变 - 与 Markdown 完全兼容:标题怎么写都行,调用时用方括号「引用这个名字」
- 语义清晰:方括号本身就是「这里是一个整体名字」的视觉标记
- 可推广:方法调用
[obj.方法 名]、库函数[lib.函数 名]一并受益
风险与缓解
| 风险 | 缓解 |
|---|---|
[…] 也被用于链接索引 [key](map) |
已有守卫:] 后紧跟 ( 则不是 callee(第 981 行),保持 |
JSON 数组 [1, 2] 被误认为 callee |
既有守卫:含 , : { } [ ] 一律拒绝,保持 |
print text=(礼貌 [问候] x) 类内嵌方括号 |
既有守卫:前缀含 = ( " ' : 则不当 callee,保持 |
运行时按下标查函数表,加一 号 能否命中 |
需实测验证(见 §4 验证计划 V1) |
工作量:改 2 处校验 + 补 6–9 个测试 + 更新教程与陷阱手册。最小可验证改动。
方案 2 — 调用侧最长前缀匹配(否决)
做法:拿到 加一 号 n=1 后,尝试用「已知函数名」做最长前缀匹配。
否决理由
- 上下文不可达:调用发生在表达式解析阶段,此时只有本模块符号表;
跨模块
lib.函数 名需要 import 解析结果,不可在词法期判定。 - 歧义爆炸:
> print text=hello world中,若存在名为print text的函数, 本来正确的调用会突然变成别的函数。所有多词行语义都可能改变。 - 属于核心语义变更,收益(省掉方括号)远小于风险。
方案 3 — 主张「标题即函数名,调用用完整标题」(不改代码,只改文档)
做法:明确官方立场——带空格的名字不自称可调用,需要调用就请写
一个无空格的 ## 别名 转发,或直接把标题写成无空格形式。
## 用户 登录流程 ← 给人读的标题,不被调用
## 用户登录流程 ← 真正被调用的函数
+ `账号`
...
优点:零代码改动;鼓励「标题给人、标识符给机器」的清晰分层。
缺点:与「完全兼容 Markdown」仍有张力——作者得写两遍。
适用:如果审计认为方括号放开会牵连过多,可作为保守退路。
方案 4 — 反引号名解析到函数(否决)
允许 `加一 号` 在调用位解析成函数引用(> 加一 号 n=1)。
否决理由:反引号在 Marqdo 中统一表示变量引用。让它有时指变量、有时指函数, 会让「反引号=变量」这条最基础的约定失效,错误更难排查。
3. 方案对比
| 维度 | 方案 1 放开方括号 | 方案 2 前缀匹配 | 方案 3 文档立场 | 方案 4 反引号 |
|---|---|---|---|---|
| 兼容 Markdown | ✅ 完全 | ✅ | ⚠️ 需写两遍 | ✅ |
| 新增语法 | 无(复用既有) | 无 | 无 | 有歧义 |
| 改动范围 | 1 处校验 + 测试 | 核心语义 | 0 代码 | 核心语义 |
| 回归风险 | 低 | 高 | 无 | 高 |
| 可验证性 | 高(可枚举用例) | 低 | — | 低 |
| 推荐 | 首选 | 否决 | 备选 | 否决 |
4. 若采纳方案 1:验证计划
必须全部通过才可合入。
| 编号 | 用例 | 期望 |
|---|---|---|
| V1 ✅ | ## 加一 号 + > [加一 号] n=1 |
返回 2(已实测通过,见 §1.4) |
| V2 | ## 加一_号 + > [加一_号] n=1 |
返回 2(既有行为不变) |
| V3 | 链接索引 [k](m) |
仍解析为索引,不被当 callee |
| V4 | > print text=(礼貌 [问候] x) |
内嵌方括号不被当 callee |
| V5 | 方括号内 JSON [1, 2] / ["a"] |
仍被拒绝为 callee |
| V6 | 跨模块 [lib.函数 名] |
正确解析到库函数 |
| V7 | 方法 [obj.方法 名] |
正确解析 receiver |
| V8 | 全量 cargo test |
233 全绿(+ 新增用例) |
| V9 | 全仓库 .mq.md 回归 |
无新增解析错误 |
V1 是决定性的:如果运行时函数表以 加一 号 为键能正常查到,
方案 1 就成立;如果查不到(比如符号表内部也做了归一化),需要再评估。
5. 待你决策的问题
- 选哪个方案? 我倾向 方案 1(放开方括号空格):不新增语法、 完全兼容 Markdown、改动可控、可验证性强。
- 若选方案 1,调用书写是否需要中文别名? 例如同时接受
【加一 号】(全角方括号), 与全角冒号问题(D2)一致。 - 是否要保留方案 3 的文档立场作为补充说明? 即「标题可自由书写;
需要调用时用
[完整名]引用」——这句话本身就很适合写进教程。
在你确认前,我不会改动 D8 相关代码。