# 方案评估:函数名含空格的调用(D8) | | | |---|---| | 状态 | **Proposed · 待审阅**(未实施任何代码改动) | | 日期 | 2026-10-22 | | 来源 | [qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) D8 | | 前置 | [parser-diagnostics-d8-d9.md](parser-diagnostics-d8-d9.md)(该文方案 A「禁止空格」**已被否决**,见 §0) | | 影响面 | 核心解析:`src/parse/expr.rs` 调用切词 / `src/lex` 行分类 / 名称解析 | --- ## 0. 为什么原方案被否决 原方案 A 主张「定义期拒绝含空格的函数名」。这是**错的**,理由是我此前忽略的一句话: > Marqdo 的立身之本就是**完全兼容 Markdown**。 `## 用户 登录` 是一个**完全合法的 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` 的「含空白即拒绝」改为「允许空白, 但需与既有歧义守卫共存」;并确认调用链后续不再按空格切词。 **用法**: ```markdown ## 用户 登录流程 + `账号` *"已登录 " + `账号`* # 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` 后,尝试用「已知函数名」做最长前缀匹配。 **否决理由** 1. **上下文不可达**:调用发生在表达式解析阶段,此时只有本模块符号表; 跨模块 `lib.函数 名` 需要 import 解析结果,不可在词法期判定。 2. **歧义爆炸**:`> print text=hello world` 中,若存在名为 `print text` 的函数, 本来正确的调用会突然变成别的函数。所有多词行语义都可能改变。 3. 属于**核心语义变更**,收益(省掉方括号)远小于风险。 --- ### 方案 3 — 主张「标题即函数名,调用用完整标题」(不改代码,只改文档) **做法**:明确官方立场——带空格的名字**不自称可调用**,需要调用就请写 一个无空格的 `## 别名` 转发,或直接把标题写成无空格形式。 ```markdown ## 用户 登录流程 ← 给人读的标题,不被调用 ## 用户登录流程 ← 真正被调用的函数 + `账号` ... ``` **优点**:零代码改动;鼓励「标题给人、标识符给机器」的清晰分层。 **缺点**:与「完全兼容 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. **选哪个方案?** 我倾向 **方案 1**(放开方括号空格):不新增语法、 完全兼容 Markdown、改动可控、可验证性强。 2. **若选方案 1,调用书写是否需要中文别名?** 例如同时接受 `【加一 号】`(全角方括号), 与全角冒号问题(D2)一致。 3. **是否要保留方案 3 的文档立场作为补充说明?** 即「标题可自由书写; 需要调用时用 `[完整名]` 引用」——这句话本身就很适合写进教程。 在你确认前,我不会改动 D8 相关代码。