15 KiB
评定:[描述](语句) —— 方括号读作「人话」,圆括号读作「机器话」
2026-10-23 审阅裁决:本文的 Classic 冲突统计和兼容取舍属于迁移历史;v2.1 默认采用描述包裹 payload,不能据旧冲突恢复默认
[键](集合)。保留标签的阅读/检索/步骤价值,不强制所有子表达式命名,也不把标签当作目标或权限依据。参见文档原生指导 §2。
| 状态 | 已决策:走「路线二 纯度」(落地见 label-freshness-and-repair.md) |
| 日期 | 2026-10-22 |
| 提案 | 「[]() 不是两个部分两个含义,而是 [描述性显示文字](实际执行的简短语句)」 |
| 方法 | 语料实测(索引 506 / 循环 44 / 方括号调用 0)+ 渲染器源码核对 + 设计史对照 |
| 相邻 | label-freshness-and-repair.md(后续:纯度落地 + 标签过期检测)· function-as-naming-philosophy.md · collection-access-link.md · call-syntax-from-marks.md |
决策:用户选择路线二(纯度)——
()只装机器语句,取元搬进(); 标签可省略书写但编译器必须报错;循环写法不追求统一,()内自洽即可。 落地细节、普通取元形态,以及标签过期检测(L1 引用一致性 / L2 指纹台账 / L3 LLM 复核) 见 label-freshness-and-repair.md。
0. 先把提案精确化
你的话可以解析出三种读法,差别很大,必须先分清:
| 读法 | [] 是什么 |
() 是什么 |
语义是否变 |
|---|---|---|---|
| A 标签化(你的原意,本文主评) | 这个值的人话名字(纯描述) | 算出它的机器语句 | 变 |
| B 命名规范化 | 更好的键名(描述取出的东西) | 仍是集合 | 不变 |
| C 内联命名 | 同时引入可引用的名字 | 算出它的语句 | 新增绑定 |
你说「[]() 函数也有了落脚地」「括号里面可以写长一些」,指向的是 A:
[] 只负责说人话,() 负责说准话;两者合起来才是一条完整语句。
1. 为什么我们会下意识觉得这个写法"美"
你的直觉不是审美偏好,它对应三个真实存在的设计同构:
1.1 超链接:可见文本 ↔ 目标
<a> / [可见文字](目标地址) 的全部意义就是给机器一个目标,给人类一个说法。
这是人类最早、最成功的"双面文本"。
1.2 文学编程的 chunk 名(Knuth)
Knuth 的 <<chunk name>> 就是"可执行片段的人话名字"。
而文学编程的整个出发点,正是你前面说的"代码要像文章"——这个类比不是巧合。
1.3 Marqdo 自己已经有这个形态

[]里是指令/说明(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 收益二:嵌套取元终于可读
现在是:
**第一 = [1]([苹果](货架))**
两层嵌套,人类读者要在"货架→苹果→第1项"之间跳三次。
改成标签后:
**第一 = [货架里苹果的第一项](…机器语句…)**
人读标签,机器读嵌套。 你点出的"嵌套难以描述"问题被真正解决了。
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 废除 + \名`` 形参表的原话理由是:「仪式感强;函数头像另一套签名语言,与正文脱节」。
强制每个访问都配一段人话标签,是同一类仪式。两种可预测的退化:
- 凑数:作者写
[x](…)、[价格](…)——标签退化成变量名,等于没有 - 噪音:标签越写越长,正文被切碎,扫描性下降
这不是反对,而是提醒:标签的价值只在"写得比键更有信息"时成立。
所以设计上应当考虑"可以省略",但一旦可省略,[] 就又变成可选键 → 歧义回归。
这个矛盾必须在设计里正面解决,不能靠自觉。
6. 迁移面(实测)
| 受影响的写法 | 数量 | 文件 |
|---|---|---|
[键](集合) 取元 |
506 处 | 136 个文件 |
- [项](集合) 循环 |
44 处 | 24 个文件 |
[函数] 参数 可执行调用 |
0 | (189 处是 lib/* 的 Caller: 说明行,不执行) |
危险点:如果 [] 改为"纯标签",那 506 处取元的含义会变((菜单) 变成整个菜单),
而且是同形换义——同一段文本含义变了、还不报错。这是最坏的一类变更(参见 D9)。
所以若走这条路,必须硬报错 + 版本门:旧写法在新版本下直接报
「[键](集合) 已改为 [描述](语句),请写成 X」。
另有一个好消息:可执行方括号调用量为 0,所以"把 [f] args 收编进新形式"是零迁移成本。
7. 两条落地路线
路线一:双层(推荐,兼容)
规则一句话:
[]永远是「这个值的人话名字」;()永远是「怎么算出它」。
- 长形(新增):
[描述](语句)—— 承载调用、复杂取元、循环 - 短形(现状保留):
[键](集合)、- [项](集合)定义为长形的缩写 - 文档里显式承认:短形是历史妥协,
[]在短形中兼任键
| 优 | 劣 |
|---|---|
| 零迁移(506 处不动) | 短形的"两义"仍在(但被定义为可解释的缩写) |
| 调用终于有落脚地(且 0 成本收编) | 规则仍是"一条 + 一个特例",不是纯一条 |
| 嵌套可读、循环可写清来源 | |
| 标签可以逐步引入,不强迫 |
路线二:纯度(一条规则到底)
()只装机器语句,取元必须搬进()。
必须同时决定:() 内取元用什么形式(§3 表),然后迁移 506 处 + 版本门。
| 优 | 劣 |
|---|---|
| 语义最纯,教学最简 | 需新增取元规则(可能不是净简化) |
[] 完全自由,可写很长的描述 |
506 处迁移,同形换义风险 |
| 与 Markdown 链接语义完全一致 | 新取元语法与库路径/方法调用需要消歧设计 |
8. 我的评定
这是本系列里结构上最强的一个提案,因为它第一次正面回答了"为什么 []() 一直不肯就范":
不是我们选错了语义,而是我们把一个"双面文本"当成了"两段语义"。
| 维度 | 评分 | 说明 |
|---|---|---|
| 哲学自洽性 | ★★★★★ | 与超链接、文学编程、 三处同构;且"文档自解释"优于"依赖 view 渲染" |
| 解决问题 | ★★★★☆ | 解散 link-call 死结、治嵌套可读性、治循环来源——三个真问题 |
| 规则净简化 | ★★★☆☆ | 收益是"两规则→一规则",但代价可能是"新增一条取元规则" |
| 迁移风险 | ★★☆☆☆ | 506 处同形换义,必须硬报错;但可执行方括号调用为 0 是利好 |
| 漂移风险 | ★★★☆☆ | 比你估计的重(注释回归 + 锚点说谎 + agent 攻击面),但可用 ② 词重叠校验兜住 |
| 采用风险 | ★★★☆☆ | 有重演 v0.3"仪式感"的可能,需正面解决"可省略 vs 歧义" |
我的建议:走 路线一(双层),但把"长形"作为推荐写法、把文档里的示例全部改成长形, 让短形成为"读得懂但不必写"的兼容层。这样:
- 你今天就能拿到全部三个收益(描述性、嵌套可读、循环来源)
- 506 处零迁移
- 调用终于有家,且成本为零
- 未来若要纯度,可以在长形已被广泛使用后,再决定是否废弃短形
一条具体建议:先把 §4 的 ②(词重叠 warn)做出来。 它让"标签"从"可能说谎的装饰"变成"可被机器轻度核验的描述"—— 这一步做完,标签才配得上你要给它加的"AI 定位锚点"和"点击跳转"这两个职责。
9. 待你决策
- 路线一(双层)还是路线二(纯度)?
- 若路线二:
()内的取元用哪种形式(点号 / 函数式 / 其他)?——这决定要不要新增规则。 - 标签可否省略? 若可,省略时算"以
()的文字为标签",还是要额外标记? - 是否采纳 §4.2 的"词重叠校验"?我认为它是这套设计能否安全的支点。
- 循环的新写法你倾向哪一种:
- [从篮子取出的每个果子](遍历 篮子 为 果)- [篮子里的果子](篮子 → 果)- 保留
- [果](篮子)作短形