Files
marqdo/doc/design/function-as-table-semantics.md
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

338 lines
16 KiB
Markdown
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 语义探析:代码函数能否解释为一张 GFM 表
> **2026-10-23 审阅裁决**:下文 v1.5.2 实验不替代当前回归。保留现有数据表几何与契约表角色,不重复声明参数;“现有实现不支持函数表”不等于表格不能表达计算。有限决策表和生成式签名视图按真实用例评估,见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **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. 若你仍想推进「表即签名」,我可以做一次**限定实验**:
要求显式标记(如 `| 签名 | 参数 | 类型 |`)+ 与体推断不一致即报错,
在小范围金样里验证是否可控。要我做吗?