303 lines
15 KiB
Markdown
303 lines
15 KiB
Markdown
# 评定:`[描述](语句)` —— 方括号读作「人话」,圆括号读作「机器话」
|
||
|
||
> **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 超链接:可见文本 ↔ 目标
|
||
|
||
`<a>` / `[可见文字](目标地址)` 的全部意义就是**给机器一个目标,给人类一个说法**。
|
||
这是人类最早、最成功的"双面文本"。
|
||
|
||
### 1.2 文学编程的 chunk 名(Knuth)
|
||
|
||
Knuth 的 `<<chunk name>>` 就是"可执行片段的人话名字"。
|
||
而**文学编程的整个出发点,正是你前面说的"代码要像文章"**——这个类比不是巧合。
|
||
|
||
### 1.3 Marqdo 自己已经有这个形态
|
||
|
||
```markdown
|
||

|
||
```
|
||
|
||
- `[]` 里是**指令/说明**(`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. 我的评定
|
||
|
||
**这是本系列里结构上最强的一个提案**,因为它第一次正面回答了"为什么 `[]()` 一直不肯就范":
|
||
不是我们选错了语义,而是我们把一个"双面文本"当成了"两段语义"。
|
||
|
||
| 维度 | 评分 | 说明 |
|
||
|------|------|------|
|
||
| 哲学自洽性 | ★★★★★ | 与超链接、文学编程、`` 三处同构;且"文档自解释"优于"依赖 view 渲染" |
|
||
| 解决问题 | ★★★★☆ | 解散 link-call 死结、治嵌套可读性、治循环来源——三个真问题 |
|
||
| 规则净简化 | ★★★☆☆ | 收益是"两规则→一规则",但代价可能是"新增一条取元规则" |
|
||
| 迁移风险 | ★★☆☆☆ | 506 处同形换义,必须硬报错;但可执行方括号调用为 0 是利好 |
|
||
| 漂移风险 | ★★★☆☆ | 比你估计的重(注释回归 + 锚点说谎 + agent 攻击面),但可用 ② 词重叠校验兜住 |
|
||
| 采用风险 | ★★★☆☆ | 有重演 v0.3"仪式感"的可能,需正面解决"可省略 vs 歧义" |
|
||
|
||
**我的建议**:走 **路线一(双层)**,但把"长形"作为**推荐写法**、把文档里的示例全部改成长形,
|
||
让短形成为"读得懂但不必写"的兼容层。这样:
|
||
|
||
- 你今天就能拿到全部三个收益(描述性、嵌套可读、循环来源)
|
||
- 506 处零迁移
|
||
- 调用终于有家,且成本为零
|
||
- 未来若要纯度,可以在长形已被广泛使用后,再决定是否废弃短形
|
||
|
||
**一条具体建议**:先把 §4 的 ②(词重叠 warn)做出来。
|
||
它让"标签"从"可能说谎的装饰"变成"**可被机器轻度核验的描述**"——
|
||
这一步做完,标签才配得上你要给它加的"AI 定位锚点"和"点击跳转"这两个职责。
|
||
|
||
---
|
||
|
||
## 9. 待你决策
|
||
|
||
1. **路线一(双层)还是路线二(纯度)?**
|
||
2. 若路线二:`()` 内的取元用哪种形式(点号 / 函数式 / 其他)?——这决定要不要新增规则。
|
||
3. **标签可否省略?** 若可,省略时算"以 `()` 的文字为标签",还是要额外标记?
|
||
4. **是否采纳 §4.2 的"词重叠校验"**?我认为它是这套设计能否安全的支点。
|
||
5. 循环的新写法你倾向哪一种:
|
||
- `- [从篮子取出的每个果子](遍历 篮子 为 果)`
|
||
- `- [篮子里的果子](篮子 → 果)`
|
||
- 保留 `- [果](篮子)` 作短形
|