- 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。
16 KiB
Executable File
语义探析:代码函数能否解释为一张 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) 走不通(第三次论证,这次有史料)
前两轮已从「与取元同形」论证过。这次找到了设计层的原始决议。
心智:方括号 = 取出的名字,圆括号 = 从哪取。
**价 = [拿铁](菜单)** # 取出的名字 = 拿铁;从哪取 = 菜单
§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. 待你决策
- 裁决:是否接受「表做声明、不做定义」(§8.1)?
- 优先级:§8.2 的三件事(① 漂移诊断 / ② 反向生成 / ③ 签名可供机器消费) 先做哪个?我建议 ①(消灭静默)→ ③(tool schema 是刚需)→ ②。
- 是否要我把
+ 行加契约表的组合写成教程样例(§9), 并明确标注「+是兼容形态、新代码优先叙述声明」? - 若你仍想推进「表即签名」,我可以做一次限定实验:
要求显式标记(如
| 签名 | 参数 | 类型 |)+ 与体推断不一致即报错, 在小范围金样里验证是否可控。要我做吗?