Files
marqdo/doc/design/bracket-as-label-evaluation.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

15 KiB
Executable File
Raw Blame History

评定:[描述](语句) —— 方括号读作「人话」,圆括号读作「机器话」

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](图片路径)
  • [] 里是指令/说明(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 废除 + \名`` 形参表的原话理由是:「仪式感强;函数头像另一套签名语言,与正文脱节」。

强制每个访问都配一段人话标签,是同一类仪式。两种可预测的退化:

  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. 循环的新写法你倾向哪一种:
    • - [从篮子取出的每个果子](遍历 篮子 为 果)
    • - [篮子里的果子](篮子 → 果)
    • 保留 - [果](篮子) 作短形