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

16 KiB
Executable File
Raw Permalink Blame History

语义探析:代码函数能否解释为一张 GFM 表

2026-10-23 审阅裁决:下文 v1.5.2 实验不替代当前回归。保留现有数据表几何与契约表角色,不重复声明参数;“现有实现不支持函数表”不等于表格不能表达计算。有限决策表和生成式签名视图按真实用例评估,见文档原生指导 §2。

状态 Proposed · 待决策(未修改任何代码)
日期 2026-10-22
提出 「## 函数名 + + 参数 + 函数体,从某种角度能否解释成 GFM 表」
方法 11 组运行时实验(1.5.2)+ 5 份设计/路线图文档考古
相邻 functions-as-values-evaluation.md · link-style-call-evaluation.md
关键前置 collection-access-link.md · call-arguments.md · tables-maps-footnotes.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 §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 §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 §1:

心智:方括号 = 取出的名字,圆括号 = 从哪取。

**价 = [拿铁](菜单)**      # 取出的名字 = 拿铁;从哪取 = 菜单

§4「非目标」明确排除:点号 map 访问、在、箭头取元、(键)[集合]。 call-arguments.md §2 同样锁定:

] 后紧邻 ( → 取元 [key](collection),不是 callee 标记。

所以 [f](x) 不是「还没决定的语法」,而是已被明确分配给取元。 让它兼作调用,就是把「从哪取」这个心智反转成「调用谁」——两套直觉会打架。

而且这与 §4 的表问题同源:都是「同一个外形要承载两种语义」, 只不过一个在值层面(表 vs 函数),一个在语法层面(取元 vs 调用)。


6. 历史:这条路走过,而且是被反向走过的

这是本轮考古最有价值的发现。四条史料:

6.1 v0.2 要求手写形参表 → v0.3 明确废除

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 §6 非目标:

  • 用表格声明字段 schema(表格仍表示数据集合;见 tables-maps-footnotes.md)

路线图里同样列为非目标:

用表声明对象字段 schema(仍见 objects 非目标;与数据集合分开)

结论:语言已明确决定「表管数据,不管声明」。契约表是这一原则的受控例外—— 它只提供注解与校验,不提供绑定。

6.3 行向记录必须显式标记,且「不得静默混用」

tables-maps-footnotes.md §3.3:

备选语义(不默认):行向记录列表 …… 若未来需要,用显式标记区分, 不得与默认列向字典静默混用。

§3.5 落地了 行/@/row 标记。

结论:凡是「形态会改变语义」的地方,Marqdo 一律要求显式标记。 「函数签名表」如果真要参与绑定,属于同类形态变化,必须同样显式—— 而契约表的 参数/返回 头,正是这个显式标记的现成形态。

6.4 取元曾被反复挑选,最后选定链接形

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. 一个可以试的新写法(示例,供你评判)

如果你想保留「表 + 函数体」的书写快感,最安全的形态是双写 + 一致性校验:

## 税率
    + `档位`

| 参数 | 类型 | 说明 |
|------|------|------|
| 档位 | number | 1/2/3 档 |

| 返回 | 类型 | 说明 |
|------|------|------|
|  | number | 适用税率 |

- [行](`税率表`)
  **hit = [档位](`行`)**
  1. `hit`
    ...
    *[税率](`行`)*
优点 缺点
人读极好(表 + 正文) 与真实签名可能漂移(需 ① 的校验兜住)
已经是今天可跑的语法(E5 验证) + 行 是 v0.3 标注「新代码不推荐」的旧形态
类型校验已生效(E3) 表不能替代体推断,参数仍要声明

要点:这张表不是函数的定义,而是它的仪表盘。 真正的接口由 + 档位(或叙述声明)决定,表负责类型与说明。 只要两者不一致就报错,这套写法就既美又安全。


10. 待你决策

  1. 裁决:是否接受「表做声明、不做定义」(§8.1)?
  2. 优先级:§8.2 的三件事(① 漂移诊断 / ② 反向生成 / ③ 签名可供机器消费) 先做哪个?我建议 ①(消灭静默)→ ③(tool schema 是刚需)→ ②。
  3. 是否要我把 + 行 加契约表的组合写成教程样例(§9), 并明确标注「+ 是兼容形态、新代码优先叙述声明」?
  4. 若你仍想推进「表即签名」,我可以做一次限定实验: 要求显式标记(如 | 签名 | 参数 | 类型 |)+ 与体推断不一致即报错, 在小范围金样里验证是否可控。要我做吗?