docs(design): 函数能否解释为 GFM 表 — 11 组实验 + 史料考古(未改代码)
回应「代码函数(## 名 + 参数 + 体)从某种角度能否解释成 GFM 表,
这样的解释运行时有没有巨大风险、有没有实际收益、历史上出现过吗为什么放弃」。
核心答案:命题在 Marqdo 里**已经实现**,但实现的是「关于函数的表」(契约表),
不是「函数本身」。界:表能描述外延(输入→结果)与签名(元数据),
不能描述内涵(怎么算);而调用恰恰是内涵操作。
[k](集合) 是投影已有数据,f(x) 是计算新数据,只有 f 已是预先枚举的表函数才重合。
一、固定表格几何(实测)
- 1 列 N 行 → List;≥2 列 1 行 → Map 记录(实测 {"x":1,"y":2})
- ≥2 列 N 行 → **列向聚合** Map(实测 {"档位":[1,2],"税率":[...]})
- 行向记录必须显式标记(行/@/row),文档原话「不得与默认列向字典静默混用」
→ 「行 = 参数」在 Marqdo 里不是自然形态
二、命题已存在:契约表(tests/contracts/ok_contract.mq.md)
src/contract.rs:表头含 参数/返回/字段 + 必须有「类型」列 → 契约块。
契约表的首列标头正是 §3.5 那种「显式形态标记」的同类做法。
三、11 组实验(1.5.2 实跑)划定边界
- E1b 表列 n 但体不读 → > f 无参调用成功 → 表**不能声明**形参
- E3 叙述声明 n + 表 + 传"七" → 参数 n 期望 number,实际 text(契约校验)
- E4 无表 → 七1,不校验
- E5 + `n` 旧式形参行 + 表 → 契约生效(用户草图形态可用)
- E6 表写 2 行、体只读 1 个 → too many positional(**表 ≠ arity**)
- E7 单列参数表 → 七1,**契约静默失效**(1 列 = List,且 check 报"无契约问题")
- E8 重复行 → 取首行无诊断;E9 幽灵行 → 静默忽略
- E10 同一张表加 `tc` = 绑定 → 契约消失
→ 隐含规则:**未绑定的表 = 声明/元数据;绑定的表 = 数据**
四、若表成为定义(把静默漂移从"少个校验"升级为"少个参数")
漏类型列/表体漂移/重复行/调换行序都会变成绑定语义;
最致命的是行序携带语义——「把 b 行移到 a 上面」这个无害编辑会改变位置参数绑定。
而 [键](集合) 之所以安全是因为**键是显式的**,取元不依赖顺序。
五、链接式调用第三次论证(带史料)
collection-access-link.md §1「方括号 = 取出的名字,圆括号 = 从哪取」;
§4 非目标排除点号/在/箭头/(键)[集合];call-arguments.md 锁定 `]` 紧邻 `(` = 取元。
→ [f](args) 不是未决定,而是**已被明确分配给取元**。
六、史料:这条路是被反向走过的
- v0.2 要求手写 `+ 名` 形参表 → v0.3 列为**代价**(仪式感强、与正文脱节),
P4 改为体推断,`+ 名` 标注「过渡兼容,新代码不推荐」
- objects.md §6 非目标:**用表格声明字段 schema**(表格仍表示数据集合)
- tables-maps-footnotes §3.3 行向记录「不默认」,§3.5 显式标记才开启
- collection-access-link §3 记录了取元语法的迁移与定稿
七、收益(诚实)
tool schema 最实:tools 已能写成记录行(tool_names 接受含 name/工具 的 Object),
但 agent_format_tools 只渲染 `- name`,说明与参数被丢弃——能力已在那儿,只差接上签名。
八、建议:表做声明不做定义,补三件事
① 消灭静默:契约表缺类型列/幽灵行/重复行/与 arity 不符 → check 应 warn(当前全静默)
② 反向生成:marqdo view 从签名生成契约表草案(单一真相仍是体,表是投影)
③ 签名可供机器消费:knowledge 能力条目带参数 schema → tool schema 自动生成
零语法改动。§9 给了「双写 + 一致性校验」的可试写法(E5 已验证可跑)。
未修改任何代码。
This commit is contained in:
1 parent
3260494e5c
commit
eae4815fc7
2 files changed
+336
-1
No files matched your search
@@ -0,0 +1,335 @@
|
||||
# 语义探析:代码函数能否解释为一张 GFM 表
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未修改任何代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 提出 | 「`## 函数名` + `+ 参数` + 函数体,从某种角度能否解释成 GFM 表」 |
|
||||
| 方法 | 11 组运行时实验(1.5.2)+ 5 份设计/路线图文档考古 |
|
||||
| 相邻 | [functions-as-values-evaluation.md](functions-as-values-evaluation.md) · [link-style-call-evaluation.md](link-style-call-evaluation.md) |
|
||||
| 关键前置 | [collection-access-link.md](collection-access-link.md) · [call-arguments.md](call-arguments.md) · [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [objects.md](objects.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话答案
|
||||
|
||||
**你的命题在 Marqdo 里已经实现了——但它实现的是「关于函数的表」,不是「函数本身」。**
|
||||
|
||||
```
|
||||
## 加一
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| n | number | 输入值 |
|
||||
|
||||
*n+1*
|
||||
```
|
||||
|
||||
这张表**今天就能跑**,是既有特性(契约表,`tests/contracts/ok_contract.mq.md`)。
|
||||
它证明了:函数参数**确实可以**是一张 GFM 表。
|
||||
|
||||
但它只能**描述**参数,不能**声明**参数;它不含函数体,不决定 arity,也不能被调用。
|
||||
一句话划界:
|
||||
|
||||
> **表能描述外延(输入→结果)与签名(元数据),不能描述内涵(怎么算)。**
|
||||
> 而「调用」恰恰是内涵操作。
|
||||
> `[k](集合)` 是**投影已有数据**,`f(x)` 是**计算新数据**——
|
||||
> 只有 f 本身已经是「预先枚举好的表函数」时,两者才重合。
|
||||
|
||||
---
|
||||
|
||||
## 1. 先固定事实:Marqdo 的表格几何(实测)
|
||||
|
||||
讨论前必须先把「表」的语义钉死,否则会建在错觉上。
|
||||
|
||||
| 形状 | 绑定结果 | 实验 |
|
||||
|------|---------|------|
|
||||
| 1 列 N 行 | `List`(列值) | 文档锁定 + 实测 |
|
||||
| ≥2 列 **1 行** | `Map`(表头→标量,即「记录」) | `{"档位":[1,2]}` 反例 → 单行才是记录 |
|
||||
| ≥2 列 **N 行** | `Map`(表头→**列列表**,列向聚合) | 实测 `{"档位":[1,2],"税率":[0.03,0.1]}` |
|
||||
| 首列标头为 `行` / `@` / `row` | `List[Map]`(**行向记录**,显式开启) | [tables-maps-footnotes](../roadmap/tables-maps-footnotes.md) §3.5 |
|
||||
|
||||
**关键点**:Marqdo 的默认是**列向**。多行多列表不是「一组记录」,
|
||||
而是「一列一个列表」。行向记录是**显式标记**才能开的形态,
|
||||
文档原话:「**不得**与默认列向字典静默混用」。
|
||||
|
||||
这一条直接决定了「行 = 参数」在 Marqdo 里**不是自然形态**:
|
||||
按默认几何,`| 参数 | 类型 |` 两行参数会变成
|
||||
`{"参数":["a","b"], "类型":["number","number"]}` —— 列向。
|
||||
|
||||
---
|
||||
|
||||
## 2. 你的命题已经存在:契约表
|
||||
|
||||
`src/contract.rs:308` 的注释写得很清楚:
|
||||
|
||||
```
|
||||
/// 未绑定文档表(`Expr::Map`)→ 契约块。
|
||||
/// - `None`:非契约形状(普通数据/说明表,原样保留)。
|
||||
/// - `Some(Err)`:契约形状但畸形 —— 必产诊断。
|
||||
/// - `Some(Ok)`:合法契约(`参数`/`返回`/`字段` 三形状之一,须含 `类型` 列)。
|
||||
```
|
||||
|
||||
三条规则(`src/contract.rs:260-334`):
|
||||
|
||||
| 规则 | 实现 |
|
||||
|------|------|
|
||||
| 表头含 `参数`/`形参`/`param`/`arg` → 形参契约 | `PARAM_HEADERS` |
|
||||
| 表头含 `返回`/`return`/`result` → 返回契约 | `RETURN_HEADERS` |
|
||||
| **必须含 `类型` 列**,否则视为普通说明表 | `TYPE_HEADERS` 缺失 → `return None` |
|
||||
|
||||
也就是说:**「函数参数表」不仅可能,而且已经是正式语法**。
|
||||
第一列标头(`参数` / `返回` / `字段`)扮演的正是
|
||||
[tables-maps-footnotes](../roadmap/tables-maps-footnotes.md) §3.5 里
|
||||
`行`/`@`/`row` 那种**形态标记**的角色:显式声明「这张表是干什么用的」。
|
||||
|
||||
---
|
||||
|
||||
## 3. 但它是「关于参数的表」,不是「参数本身」
|
||||
|
||||
11 组实验里最关键的 6 组(全部实跑):
|
||||
|
||||
| # | 写法 | 实测结果 | 说明 |
|
||||
|---|------|---------|------|
|
||||
| E1 | 参数表列 `n`,函数体不读 `n` | `> f` 无参调用**成功**,`n` 不是形参 | 表不能声明形参 |
|
||||
| E3 | 叙述声明 `n` + 参数表 + 传 `"七"` | `参数 n 期望 number,实际 text(契约校验)` | **表能校验** |
|
||||
| E4 | 叙述声明 `n`,**无表** + 传 `"七"` | `七1` | 无表则不校验 |
|
||||
| E5 | `+ \`n\`` 旧式形参行 + 参数表 + 传 `"七"` | 同 E3,报契约错 | **你的草图形态可用** |
|
||||
| E6 | 表写 2 行(`a`,`b`),体只读 `a` | `too many positional arguments` | **表 ≠ arity** |
|
||||
| E7 | 单列参数表 `\| 参数 \|` + `\| n \|` | `七1`,**契约静默失效** | 1 列 = List,不成契约 |
|
||||
| E8 | 表里重复两行 `n` | 取**首行**类型,无诊断 | 表内重复静默 |
|
||||
| E9 | 表里有 `ghost`(体里没有) | 静默忽略 | 幽灵行静默 |
|
||||
| E10 | 同一张表加 `` `tc` = `` 绑定 | `七1`,契约**消失** | 绑定 → 变数据 |
|
||||
|
||||
**E10 揭示了一条隐含且优雅的规则**:
|
||||
|
||||
> **未绑定的表 = 声明/元数据(契约);绑定的表 = 数据。**
|
||||
|
||||
这正是语言对「表可以是声明吗」给出的既有答案:可以,**但前提是它不是一个值**。
|
||||
一旦你给它起名字(`` `tc` = ``),它就从「关于函数的声明」降级为「一个普通数据值」。
|
||||
|
||||
E6 + E7 + E8 + E9 合起来说明:**表与真实签名之间今天就可能漂移,而且是静默的**
|
||||
(`marqdo check e7.mq.md` 输出「无契约问题」)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 若让表成为「定义」,运行时会发生什么
|
||||
|
||||
把上面的静默漂移从「少个校验」升级成「少个参数」,风险等级完全不同。
|
||||
|
||||
| 风险 | 今天(表=注解) | 若表=定义 |
|
||||
|------|----------------|-----------|
|
||||
| 漏写 `类型` 列 | 契约静默失效(E7) | **参数静默消失**,调用直接错 arity |
|
||||
| 表行数 ≠ 体读取数 | 表多余行被忽略(E6/E9) | **接口由表决定**,体重构后表未改 → 运行期崩 |
|
||||
| 重复行 | 取首行(E8) | **参数重复定义**,行为取决于解析器取舍 |
|
||||
| 表行重排 | 无影响(顺序由声明序决定) | **改变位置参数绑定顺序** → `> f 1 2` 含义变了 |
|
||||
| 加名字绑定 | 变数据(E10) | 语义分叉:什么时候是函数、什么时候是数据? |
|
||||
|
||||
最后一条最致命。**表是「可自由编辑的文档」**:调整行序、增删说明列、
|
||||
甚至把两张表合并,都是正常的写作行为。一旦表的行序决定位置参数绑定,
|
||||
「把 `b` 那行移到 `a` 上面」这个无害的编辑动作就**改变了程序行为**。
|
||||
|
||||
而 Marqdo 的核心承诺是「**文档即程序,且文档可被人阅读与维护**」。
|
||||
让排版顺序携带语义,等于给每张表埋一颗静默的雷。
|
||||
|
||||
对比一下:`[键](集合)` 之所以安全,是因为**键是显式的**,
|
||||
取元不依赖顺序。而位置参数天然依赖顺序——所以**签名不该用表承载顺序**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 为什么链接式调用 `[f](args)` 走不通(第三次论证,这次有史料)
|
||||
|
||||
前两轮已从「与取元同形」论证过。这次找到了设计层的原始决议。
|
||||
|
||||
[collection-access-link.md](collection-access-link.md) §1:
|
||||
|
||||
> 心智:**方括号 = 取出的名字,圆括号 = 从哪取。**
|
||||
|
||||
```markdown
|
||||
**价 = [拿铁](菜单)** # 取出的名字 = 拿铁;从哪取 = 菜单
|
||||
```
|
||||
|
||||
§4「非目标」明确排除:点号 map 访问、`在`、箭头取元、`(键)[集合]`。
|
||||
[call-arguments.md](call-arguments.md) §2 同样锁定:
|
||||
|
||||
> `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记。
|
||||
|
||||
所以 `[f](x)` **不是「还没决定的语法」,而是已被明确分配给取元**。
|
||||
让它兼作调用,就是把「从哪取」这个心智反转成「调用谁」——两套直觉会打架。
|
||||
|
||||
而且这与 §4 的表问题**同源**:都是「同一个外形要承载两种语义」,
|
||||
只不过一个在值层面(表 vs 函数),一个在语法层面(取元 vs 调用)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 历史:这条路走过,而且是被**反向**走过的
|
||||
|
||||
这是本轮考古最有价值的发现。四条史料:
|
||||
|
||||
### 6.1 v0.2 要求手写形参表 → v0.3 明确废除
|
||||
|
||||
[markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §1 把 v0.2 的做法列为**代价**:
|
||||
|
||||
| v0.2 | 代价 |
|
||||
|------|------|
|
||||
| 形参必须 `` + `名` `` | **仪式感强;函数头像「另一套签名语言」,与正文脱节** |
|
||||
|
||||
§2 P4 直接给出新方针:
|
||||
|
||||
> **P4 — 形参由体推断(Body-inferred params)**
|
||||
> **不再要求**作者手写 `` + `名` `` 形参表(v0.3 默认关闭;过渡期可兼容)
|
||||
|
||||
§5 对照表把 `+ 名` 标为「**过渡兼容**:显式形参;**新代码不推荐**」。
|
||||
|
||||
**结论**:Marqdo 的发展方向是**离「声明式签名」越来越远**,转向「叙述即签名」。
|
||||
把参数改写成表,是在这条已经走反了的路上再走一遍。
|
||||
|
||||
### 6.2 「用表声明 schema」是明文非目标
|
||||
|
||||
[objects.md](objects.md) §6 非目标:
|
||||
|
||||
> - 用表格声明字段 schema(**表格仍表示数据集合**;见 tables-maps-footnotes.md)
|
||||
|
||||
路线图里同样列为非目标:
|
||||
|
||||
> 用表声明对象字段 schema(仍见 objects 非目标;**与数据集合分开**)
|
||||
|
||||
**结论**:语言已明确决定「表管数据,不管声明」。契约表是这一原则的**受控例外**——
|
||||
它只提供注解与校验,不提供绑定。
|
||||
|
||||
### 6.3 行向记录必须显式标记,且「不得静默混用」
|
||||
|
||||
[tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) §3.3:
|
||||
|
||||
> **备选语义(不默认):行向记录列表** …… 若未来需要,用显式标记区分,
|
||||
> **不得**与默认列向字典静默混用。
|
||||
|
||||
§3.5 落地了 `行`/`@`/`row` 标记。
|
||||
|
||||
**结论**:凡是「形态会改变语义」的地方,Marqdo 一律要求**显式标记**。
|
||||
「函数签名表」如果真要参与绑定,属于同类形态变化,必须同样显式——
|
||||
而契约表的 `参数`/`返回` 头,正是这个显式标记的现成形态。
|
||||
|
||||
### 6.4 取元曾被反复挑选,最后选定链接形
|
||||
|
||||
[collection-access-link.md](collection-access-link.md) §3 记录了迁移史:
|
||||
脚注形 `` 集合[^键] ``(左键右基)→ 链接形 `[键](集合)`(左键右基,更好读)。
|
||||
|
||||
**结论**:`[…](…)` 这块语法是被**反复权衡后定下来的**,不是随手占用。
|
||||
|
||||
---
|
||||
|
||||
## 7. 诚实的收益清单
|
||||
|
||||
不能只讲风险。这条路确实有真收益:
|
||||
|
||||
| 收益 | 现状 | 潜力 |
|
||||
|------|------|------|
|
||||
| **人读** | 契约表已能带类型+说明,比 `+ 名` 可读得多 | 正是 v0.3 批评 `+` 行「仪式感」的解药 |
|
||||
| **调用边界校验** | 已实现(E3) | 可扩展到更多类型(枚举、范围) |
|
||||
| **机器读:tool schema** | ⚠️ 半成品:`tools` 已能写成记录行(`tool_names` 接受含 `name`/`工具` 字段的对象),但 `agent_format_tools` **只渲染名字**(`- name`),说明与参数被丢弃 | 若函数暴露签名,工具可带 schema 与说明,实参可校验 |
|
||||
| **机器读:CLI/表单** | ❌ 无 | 签名即表 → 直接生成命令行参数解析、Web 表单 |
|
||||
| **文档一致性** | ❌ 表与体可静默漂移(E6/E9) | 可做成「漂移即报错」 |
|
||||
|
||||
最后三行是**最有价值的**。最典型的是 tool schema:`tools` 的数据形态**已经允许**每行带说明,
|
||||
但渲染器只取名字——也就是说**能力已经在那儿,只差把签名接上去**。
|
||||
这不需要把表变成定义,只需要让签名**可被投影成表**。
|
||||
|
||||
---
|
||||
|
||||
## 8. 建议:表做声明,不做定义(并补三件事)
|
||||
|
||||
### 8.1 结论
|
||||
|
||||
| 主张 | 裁决 |
|
||||
|------|------|
|
||||
| 函数参数可以用 GFM 表**描述** | ✅ **已经是特性**,继续用 |
|
||||
| 函数参数可以由 GFM 表**声明**(表即真相) | ❌ 不建议:顺序携带语义、静默漂移、与 v0.3 方向相反 |
|
||||
| 函数**本身**(含函数体)= 表 | ❌ 不可行:体是代码不是数据(见 functions-as-values §4.2) |
|
||||
| `[f](args)` 链接式调用 | ❌ 已被明确分配给取元 |
|
||||
|
||||
**保持现有分工**:
|
||||
|
||||
> 未绑定的表 = 声明(契约);绑定的表 = 数据;**函数体与 arity 是唯一真相**。
|
||||
|
||||
### 8.2 该补的三件事(都低成本,且都是「消灭静默」)
|
||||
|
||||
**① 让漂移显式化(最高价值)**
|
||||
|
||||
现状:表写 2 行、体只读 1 个 → 静默忽略(E6/E9);1 列 → 静默失效(E7)。
|
||||
建议 `marqdo check` 增加诊断:
|
||||
|
||||
| 情形 | 现在 | 应改为 |
|
||||
|------|------|--------|
|
||||
| 契约表缺 `类型` 列 | 静默视为普通表 | 若表头含 `参数`/`返回` 则 **warn**:缺 `类型` 列,已按说明表忽略 |
|
||||
| 契约表列数不齐 | 有诊断(`Some(Err)`) | 保持 |
|
||||
| 表里的参数名不在真实 arity 内 | 静默忽略 | **warn**:`ghost` 不是本函数的形参 |
|
||||
| 表头重复参数名 | 取首行 | **warn**:重复声明 |
|
||||
|
||||
这与本轮 D9「未闭合引号静默吞行」是同一类问题——**静默类缺陷**优先修。
|
||||
|
||||
**② 反向生成:签名 → 表(满足「语法很美」)**
|
||||
|
||||
既然表是好的**呈现**,就让工具来生成它,而不是让人手写:
|
||||
|
||||
```
|
||||
marqdo view --signature 文件.mq.md # 从体推断的签名生成契约表草案
|
||||
```
|
||||
|
||||
单一真相仍是函数体,表是**投影**。这样既拿到「签名即表」的可读性,
|
||||
又不引入第二真相。人也可以手写表,`check` 负责校验它与体一致(即 ①)。
|
||||
|
||||
**③ 让签名可供机器消费**
|
||||
|
||||
把 `Function` 的签名(名、参数、类型契约)暴露成结构化数据(如
|
||||
`marqdo knowledge` 的能力条目里带上参数 schema),
|
||||
`ext/ai` 的工具即可从「只渲染名字」升级为「带 schema 与说明的工具」。
|
||||
这是 §7 里最实的收益,且**零语法改动**。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一个可以试的新写法(示例,供你评判)
|
||||
|
||||
如果你想保留「表 + 函数体」的书写快感,最安全的形态是**双写 + 一致性校验**:
|
||||
|
||||
```markdown
|
||||
## 税率
|
||||
+ `档位`
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| 档位 | number | 1/2/3 档 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | number | 适用税率 |
|
||||
|
||||
- [行](`税率表`)
|
||||
**hit = [档位](`行`)**
|
||||
1. `hit`
|
||||
...
|
||||
*[税率](`行`)*
|
||||
```
|
||||
|
||||
| 优点 | 缺点 |
|
||||
|------|------|
|
||||
| 人读极好(表 + 正文) | 与真实签名可能漂移(需 ① 的校验兜住) |
|
||||
| 已经是**今天可跑**的语法(E5 验证) | `+ 行` 是 v0.3 标注「新代码不推荐」的旧形态 |
|
||||
| 类型校验已生效(E3) | 表不能替代体推断,参数仍要声明 |
|
||||
|
||||
**要点**:这张表**不是**函数的定义,而是它的**仪表盘**。
|
||||
真正的接口由 `+ 档位`(或叙述声明)决定,表负责类型与说明。
|
||||
只要两者不一致就报错,这套写法就既美又安全。
|
||||
|
||||
---
|
||||
|
||||
## 10. 待你决策
|
||||
|
||||
1. **裁决**:是否接受「表做声明、不做定义」(§8.1)?
|
||||
2. **优先级**:§8.2 的三件事(① 漂移诊断 / ② 反向生成 / ③ 签名可供机器消费)
|
||||
先做哪个?我建议 ①(消灭静默)→ ③(tool schema 是刚需)→ ②。
|
||||
3. **是否要我把 `+ 行` 加契约表的组合**写成教程样例(§9),
|
||||
并明确标注「`+` 是兼容形态、新代码优先叙述声明」?
|
||||
4. 若你仍想推进「表即签名」,我可以做一次**限定实验**:
|
||||
要求显式标记(如 `| 签名 | 参数 | 类型 |`)+ 与体推断不一致即报错,
|
||||
在小范围金样里验证是否可控。要我做吗?
|
||||
Reference in new issue
Block a user