# 评定:`[描述](语句)` —— 方括号读作「人话」,圆括号读作「机器话」 > **2026-10-23 审阅裁决**:本文的 Classic 冲突统计和兼容取舍属于迁移历史;v2.1 默认采用描述包裹 payload,不能据旧冲突恢复默认 `[键](集合)`。保留标签的阅读/检索/步骤价值,不强制所有子表达式命名,也不把标签当作目标或权限依据。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。 | | | |---|---| | 状态 | **已决策:走「路线二 纯度」**(落地见 [label-freshness-and-repair.md](label-freshness-and-repair.md)) | | 日期 | 2026-10-22 | | 提案 | 「`[]()` 不是两个部分两个含义,而是 `[描述性显示文字](实际执行的简短语句)`」 | | 方法 | 语料实测(索引 506 / 循环 44 / 方括号调用 0)+ 渲染器源码核对 + 设计史对照 | | 相邻 | [label-freshness-and-repair.md](label-freshness-and-repair.md)(后续:纯度落地 + 标签过期检测)· [function-as-naming-philosophy.md](function-as-naming-philosophy.md) · [collection-access-link.md](collection-access-link.md) · [call-syntax-from-marks.md](call-syntax-from-marks.md) | > **决策**:用户选择**路线二(纯度)**——`()` 只装机器语句,取元搬进 `()`; > 标签可省略书写但**编译器必须报错**;循环写法不追求统一,`()` 内自洽即可。 > 落地细节、普通取元形态,以及**标签过期检测(L1 引用一致性 / L2 指纹台账 / L3 LLM 复核)** > 见 [label-freshness-and-repair.md](label-freshness-and-repair.md)。 --- ## 0. 先把提案精确化 你的话可以解析出三种读法,差别很大,必须先分清: | 读法 | `[]` 是什么 | `()` 是什么 | 语义是否变 | |------|------------|------------|-----------| | **A 标签化(你的原意,本文主评)** | 这个值的**人话名字**(纯描述) | 算出它的**机器语句** | **变** | | B 命名规范化 | 更好的键名(描述取出的东西) | 仍是集合 | 不变 | | C 内联命名 | 同时引入可引用的名字 | 算出它的语句 | 新增绑定 | 你说「`[]()` 函数也有了落脚地」「括号里面可以写长一些」,指向的是 **A**: **`[]` 只负责说人话,`()` 负责说准话;两者合起来才是一条完整语句。** --- ## 1. 为什么我们会下意识觉得这个写法"美" 你的直觉不是审美偏好,它对应三个**真实存在**的设计同构: ### 1.1 超链接:可见文本 ↔ 目标 `` / `[可见文字](目标地址)` 的全部意义就是**给机器一个目标,给人类一个说法**。 这是人类最早、最成功的"双面文本"。 ### 1.2 文学编程的 chunk 名(Knuth) Knuth 的 `<>` 就是"可执行片段的人话名字"。 而**文学编程的整个出发点,正是你前面说的"代码要像文章"**——这个类比不是巧合。 ### 1.3 Marqdo 自己已经有这个形态 ```markdown ![marqdo-out](图片路径) ``` - `[]` 里是**指令/说明**(`marqdo-out`、可带 key) - `()` 里是**负载**(图片 URL / data URI) **语言里已经有一个"方括号说意图、圆括号放负载"的地方。** 你的提案是把这个模式提升为通则。 ### 1.4 一个经验证据:`[]` 在实践里本来就偏"给人看" | 用法 | 数量 | 谁读 | |------|------|------| | `[键](集合)` 取元 | 506 | 机器 | | `- [项](集合)` 循环 | 44 | 机器 | | `[函数] 参数` 调用 | **0(可执行)** | — | | `[函数.名] 参数` 用法说明(`lib/*` 的 `Caller:` 行) | **189** | **人** | **可执行的方括号调用从未被使用**;`[]` 在文档里出现最多的地方,恰恰是"给人看的用法示例"。 这支持你的判断:`[]` 的天性更接近"描述",而不是"标识符"。 --- ## 2. 提案的三个真实收益(这部分我完全同意,而且比你说的更强) ### 2.1 收益一:两条规则变一条 —— 这是最大的价值 现在 `[x](y)` 是**两个部分、两个含义**(键 + 集合)。这导致前几轮那个死结: > `[f](args)` 想当调用,但它和 `[k](c)` **同形**;按名字消歧会打断 2 个真实文件。 你的重读**直接解散了这个死结**:如果 `[x](y)` 一律是"标签 + 语句", 那么**根本不存在"取元独占外形"这件事**——取元只是"`()` 恰好是个取值语句"的特例。 > 这是本提案最硬的结构收益:**它把一条只能容纳一种语义的外形,改造成能容纳任意语句的外形。** > 前几轮我们反复撞墙,是因为一直默认 `()` 只能是集合。你换了默认。 ### 2.2 收益二:嵌套取元终于可读 现在是: ```markdown **第一 = [1]([苹果](货架))** ``` 两层嵌套,人类读者要在"货架→苹果→第1项"之间跳三次。 改成标签后: ```markdown **第一 = [货架里苹果的第一项](…机器语句…)** ``` **人读标签,机器读嵌套。** 你点出的"嵌套难以描述"问题被真正解决了。 ### 2.3 收益三:循环的"来源"可见 —— 但要说清它成立的范围 你的原话:`- [果](篮子)` 在 Markdown 渲染里看不出"果是从篮子拿的"。 **这一点需要精确化,因为它决定这块值不值得改**: | 阅读场合 | `- [果](篮子)` 的表现 | |---------|---------------------| | 通用 Markdown(GitHub / VSCode 预览 / 编辑器) | 渲染成**名为「果」的链接指向「篮子」**——看不出是遍历,你的批评成立 | | **Marqdo 自己的 `view`** | 已渲染成带 `foreach` 徽章的 `loop-card`(`src/view/render.rs:1354`)——已经看得出 | 而取元在 `view` 里仍渲染成字面 `[键](集合)`(`render.rs:1502`),和 Markdown 链接同形。 **结论**:循环的"来源不可见"在**通用 Markdown 阅读器**里成立,而这恰好是大多数人的阅读场合 (`marqdo view` 需要额外一步)。所以这条收益真实,但它其实在说另一件事: > **Marqdo 的语义正确性,不应该依赖读者是否用了 `marqdo view`。** > 文档的第一载体是 `.mq.md` 本身,它在任何 Markdown 渲染器里都该读得通。 这比你原本的表述更有力——它把"渲染不好看"升级成"语义不可自解释"。 ### 2.4 附带收益:标签是天然的锚点 你提到"点击之后跳转到对应位置"。这件事可行性很高,而且价值不小: - `view` 已经保留每个语句的 span(`stmt_start`),标签可以让锚点从"行号"升级为"人话定位" - 报错信息可以说「在 **货架里苹果的第一项** 处出错」,而不是 `foo.mq.md:118` - 对 agent 尤其有用:模型用自然语言描述定位,比用行列号稳得多 --- ## 3. 结构性弱点:`()` 要变成"语句",就必须再发明一套取元 这是本提案**代价最大、也最容易被忽略**的一点,必须摊开。 若 `[]` 只是标签,那 `(菜单)` 就只表示"整个菜单",**不再表示取成员**。要取成员,`()` 内需要新语法: | 方案 | 形态 | 问题 | |------|------|------| | 点号 | `(菜单.拿铁)` | 与库路径 `txt.str_trim`、对象方法 `obj.m` 三者同形,容易混淆 | | 函数式 | `(取 菜单 拿铁)` | 需要新内建;与自然语言"取"字冲突多 | | 保留方括号 | `([拿铁](菜单))` | **嵌套方括号**,正是标签想消除的东西 | | 英文式 | `(get(菜单, 拿铁))` | 破坏中文叙述风格 | **这就是核心张力**: > 你想用 `()` 装"任意机器语句",来换取 `[]` 的纯粹描述性; > 但"取值"本身就需要一个语法,而这个语法要么是新的(增规则), > 要么就是旧的 `[k](c)`(则 `[]` 仍然兼任键,两义仍在)。 换句话说:**收益一(一条规则)能不能兑现,取决于你愿不愿意新增一条取元规则。** 这不是否决理由,但必须算进成本——因为 Marqdo 的宪法是「标记即语法,少而精」, **用一条新规则换掉一条旧规则,不必然是净简化**。 --- ## 4. 描述漂移:我认为不能轻描淡写 你说「从语言设计上这好像又不是特别重要」。我不同意,理由三条: ### 4.1 它是"注释"的回归 Marqdo 用「叙述 + 标记」取代了注释:叙述在外面说意图,标记在里面说事实。 而标签是**贴在执行体上的、可说谎的、必须短的文本**——这正是注释的老问题。 Marqdo 花了很大力气让"文档即程序",标签会把"文档可能是假的"重新引进来。 ### 4.2 一旦标签成为锚点,漂移就有操作后果 你在 §2.4 里期望标签用于跳转与定位。那么: - 报错说「在 **安全读取** 处失败」,而实际代码是写入 → **错误信息也撒谎** - agent 用标签定位 bug → 被标签误导 - 点击跳转跳到一段与描述不符的代码 → 读者信任崩塌 **标签的可信度必须与它的用途匹配。** 纯装饰可以漂移;一旦用于定位,就必须可校验。 ### 4.3 安全面:标签是 agent 可读的攻击面 Marqdo 是 agent 框架。标签是**作者可控的自然语言**,而模型天然倾向相信自然语言。 「标签写:只读校验;`()` 里:删除文件」这类不一致,从"文档瑕疵"升级为**误导 agent 的通道**。 **所以我建议把漂移当成一条可检查的不变量,而不是接受它的存在**: | 缓释手段 | 说明 | 成本 | |---------|------|------| | ① 标签永不参与绑定 | 纯显示,不进符号表、不进作用域 | 零 | | ② 词重叠校验 | `check` 检查"标签里提到的名字"是否至少有一个出现在 `()` 里;全不重叠 → warn | 低 | | ③ trace 双输出 | 错误/trace 同时给标签与 `()` 原文 | 低 | | ④ 策略不看标签 | 沙箱/权限判定只读 `()` 的语义,绝不读标签 | 设计约束 | 其中 ② 最划算:它能抓住**最恶劣的一类漂移**(标签说 A,代码做 B), 而对"标签写得更细"这种正常情况不误报。 --- ## 5. 采用风险:可能重演 v0.3 废除的"仪式感" v0.3 废除 `+ \`名\`` 形参表的原话理由是:**「仪式感强;函数头像另一套签名语言,与正文脱节」**。 强制每个访问都配一段人话标签,是**同一类仪式**。两种可预测的退化: 1. **凑数**:作者写 `[x](…)`、`[价格](…)`——标签退化成变量名,等于没有 2. **噪音**:标签越写越长,正文被切碎,扫描性下降 这不是反对,而是提醒:**标签的价值只在"写得比键更有信息"时成立**。 所以设计上应当考虑"**可以省略**",但一旦可省略,`[]` 就又变成可选键 → 歧义回归。 **这个矛盾必须在设计里正面解决,不能靠自觉。** --- ## 6. 迁移面(实测) | 受影响的写法 | 数量 | 文件 | |------------|------|------| | `[键](集合)` 取元 | **506 处** | 136 个文件 | | `- [项](集合)` 循环 | **44 处** | 24 个文件 | | `[函数] 参数` 可执行调用 | **0** | (189 处是 `lib/*` 的 `Caller:` 说明行,不执行) | **危险点**:如果 `[]` 改为"纯标签",那 506 处取元的**含义会变**(`(菜单)` 变成整个菜单), 而且是**同形换义**——同一段文本含义变了、还不报错。这是最坏的一类变更(参见 D9)。 所以若走这条路,**必须硬报错 + 版本门**:旧写法在新版本下直接报 「`[键](集合)` 已改为 `[描述](语句)`,请写成 X」。 另有一个好消息:**可执行方括号调用量为 0**,所以"把 `[f] args` 收编进新形式"是零迁移成本。 --- ## 7. 两条落地路线 ### 路线一:双层(推荐,兼容) > **规则一句话:`[]` 永远是「这个值的人话名字」;`()` 永远是「怎么算出它」。** - **长形(新增)**:`[描述](语句)` —— 承载调用、复杂取元、循环 - **短形(现状保留)**:`[键](集合)`、`- [项](集合)` 定义为长形的**缩写** - 文档里显式承认:短形是历史妥协,`[]` 在短形中兼任键 | 优 | 劣 | |----|----| | 零迁移(506 处不动) | 短形的"两义"仍在(但被定义为可解释的缩写) | | 调用终于有落脚地(且 0 成本收编) | 规则仍是"一条 + 一个特例",不是纯一条 | | 嵌套可读、循环可写清来源 | | | 标签可以逐步引入,不强迫 | | ### 路线二:纯度(一条规则到底) > `()` 只装机器语句,取元必须搬进 `()`。 必须同时决定:**`()` 内取元用什么形式**(§3 表),然后迁移 506 处 + 版本门。 | 优 | 劣 | |----|----| | 语义最纯,教学最简 | 需新增取元规则(可能不是净简化) | | `[]` 完全自由,可写很长的描述 | 506 处迁移,同形换义风险 | | 与 Markdown 链接语义完全一致 | 新取元语法与库路径/方法调用需要消歧设计 | --- ## 8. 我的评定 **这是本系列里结构上最强的一个提案**,因为它第一次正面回答了"为什么 `[]()` 一直不肯就范": 不是我们选错了语义,而是我们把一个"双面文本"当成了"两段语义"。 | 维度 | 评分 | 说明 | |------|------|------| | 哲学自洽性 | ★★★★★ | 与超链接、文学编程、`![alt](src)` 三处同构;且"文档自解释"优于"依赖 view 渲染" | | 解决问题 | ★★★★☆ | 解散 link-call 死结、治嵌套可读性、治循环来源——三个真问题 | | 规则净简化 | ★★★☆☆ | 收益是"两规则→一规则",但代价可能是"新增一条取元规则" | | 迁移风险 | ★★☆☆☆ | 506 处同形换义,必须硬报错;但可执行方括号调用为 0 是利好 | | 漂移风险 | ★★★☆☆ | 比你估计的重(注释回归 + 锚点说谎 + agent 攻击面),但可用 ② 词重叠校验兜住 | | 采用风险 | ★★★☆☆ | 有重演 v0.3"仪式感"的可能,需正面解决"可省略 vs 歧义" | **我的建议**:走 **路线一(双层)**,但把"长形"作为**推荐写法**、把文档里的示例全部改成长形, 让短形成为"读得懂但不必写"的兼容层。这样: - 你今天就能拿到全部三个收益(描述性、嵌套可读、循环来源) - 506 处零迁移 - 调用终于有家,且成本为零 - 未来若要纯度,可以在长形已被广泛使用后,再决定是否废弃短形 **一条具体建议**:先把 §4 的 ②(词重叠 warn)做出来。 它让"标签"从"可能说谎的装饰"变成"**可被机器轻度核验的描述**"—— 这一步做完,标签才配得上你要给它加的"AI 定位锚点"和"点击跳转"这两个职责。 --- ## 9. 待你决策 1. **路线一(双层)还是路线二(纯度)?** 2. 若路线二:`()` 内的取元用哪种形式(点号 / 函数式 / 其他)?——这决定要不要新增规则。 3. **标签可否省略?** 若可,省略时算"以 `()` 的文字为标签",还是要额外标记? 4. **是否采纳 §4.2 的"词重叠校验"**?我认为它是这套设计能否安全的支点。 5. 循环的新写法你倾向哪一种: - `- [从篮子取出的每个果子](遍历 篮子 为 果)` - `- [篮子里的果子](篮子 → 果)` - 保留 `- [果](篮子)` 作短形