Files
marqdo/doc/roadmap/three-problems.md
T
cflmyandCursor 1a729eb9ec P4 验证执行:(a)锚点消融✅/(c)契约消融✅/(d)防漂移✅/(e)守卫演练✅;(b)盲测 deepseek-flash 完成未达标、mimo-v2.6-pro 重跑中
- perf-validation.md:五实验协议/判据/材料(2026-09-23 自设计)
- perf-validation-report-2026-09-23.md:汇总报告(判据逐项对照 + 诚实结论)
- tests/blind_experiment.rs + tests/blind/:盲测 harness(查询通道/修复回路/usage 计量)+ 冻结材料(6 任务书 + docs-bundle)
- tests/contract_ablation.rs:四边界×三情形消融(拦截 100%/误报 0%/零回归)
- tests/drift_drill.rs:9 漂移必报 + 2 负对照
- src/mlsp.rs:syntax 卡片自持化(semantics/rule/sample/doc_quote)
- three-problems.md §5.1 判据矩阵逐行判定(问题 1✅ 2✅ 3❌);three-problems-plan.md Phase 4 落地记录
- 全量干净回归零失败

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 05:06:30 +08:00

394 lines
26 KiB
Markdown
Raw 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.
# Marqdo 三大问题:解决方向与验证设计
——证明「被解决」,而不是「被遮盖」
| | |
|---|---|
| 状态 | **设计 · 已导出本期开发任务:[three-problems-plan.md](three-problems-plan.md);验证实验不属于开发任务** |
| 日期 | 2026-09-22 |
| 来源 | [001.md](../next/001.md) 评审讨论提炼的三大问题;用户决议:**问题二走「渐进式契约 / 标注类型」**(拒绝照搬静态类型,也拒绝放弃语义校验);**问题三(AI 可靠反馈 + AI 不必学语法)是下一步的超级核心** |
| 相关 | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md)(语法宪法)· [tables-maps-footnotes.md](tables-maps-footnotes.md)(表格几何)· [catalog-cli.md](../design/catalog-cli.md) · [ai-skill.md](../design/ai-skill.md) · [objects.md](../design/objects.md) · [interpreter.md](interpreter.md) |
> **本文定位:三大问题的解决方向与验证设计。** 给三大问题定义「什么算被解决」(机器可验证判据,见 §5.1)与验证实验(修复率 / 盲测 / 消融 / 防漂移演练,见 §5.2),把「真正解决」与「遮盖过去」区分开。文中的解决步骤(各节 S 表)是**设计方向**;本期开发任务、排期与验收以 [three-problems-plan.md](three-problems-plan.md) 为准。**验证实验(§5.2)协议见 [perf-validation.md](perf-validation.md)**(2026-09-23 用户授权自行设计并执行)。
>
> **一句话:语言核心收口是地基;渐进式契约是校验层,schema 直接长在表格与说明段落里;AI 语言服务消费这两者形成可靠闭环。** 三个问题必须一起解——契约是 AI 接口的数据源,核心收口是契约语法不膨胀的前提。
**贯穿戒律(防止「遮盖式解决」):每个阶段的验收必须是机器可验证的行为变化。只产出宣言文档、不改变工具行为的,一律视为未完成。**
---
## 0. 问题清单与依赖
| # | 问题 | 定位 | 一句话方案 |
|---|------|------|-----------|
| 1 | 语言核心正在被生态功能淹没,identity 不清 | **地基** | 三层归属表 + 准入戒律 + 核心表面守卫(CI 断言) |
| 2 | 「静态类型列为非目标」被误读为「不需要语义校验」;但照搬 Java/TS 静态类型会毁掉低摩擦 | **校验层** | **渐进式契约**:schema 写在表格 / 说明段落里;按需契约校验;诊断带文档锚点 |
| 3 | AI 反馈不可靠(只有给人看的文本);AI 还在背千行语法文档 | **超级核心** | **Marqdo Language Server for AI(MLSP)**:结构化诊断协议 + 可查询 schema + 修复回路 |
依赖链:
```text
问题 1(核心收口:契约语法不许越界进核心)
└─→ 问题 2(契约层:schema 源头 = 表格 / 说明段落)
└─→ 问题 3(schema 注册表 = 契约 + 核心表面 + catalog)
└─→ 实证(修复实验 + 消融基准 → README 愿景 6)
```
共享地基先行项:**统一诊断协议(Diagnostic)**——问题 2 的契约校验与问题 3 的 AI 反馈都以它为出口,因此它排在最前(见 §3.3 与 §4)。
---
## 1. 问题一:语言核心必须小
### 1.1 诊断
Marqdo 现在同时是:Markdown 语言 + literate programming + 知识库 + catalog + web + WASM + 浏览器 + LLM + agent + MCP + 量子 + 线代 + 插件 ABI。工程上这很酷;语言设计上的危险是:
> **核心语言的 identity 被生态功能淹没;新功能随手进核心 → 语法面暗中膨胀。**
真正缺的不是「收敛宣言」,而是**三样机制**:
1. 一份穷举的**核心表面清单**——现在「什么算核心」没有唯一明文;
2. 一张**三层归属表**——新提案无处登记,默认哪儿都塞;
3. 一条**越界即可见的守卫**——核心语法暗增长没有任何机器报警。
### 1.2 目标 / 非目标
**目标**:Language / Runtime / Document 三层分离;核心标记维持**约 15 个**的封闭集合,生态增长不再增加语言面。
**非目标**:删掉 web/quantum/agent 等功能(它们不是错,层次混放才是错);重写解释器;给核心加模块可见性等系统编程特性。
### 1.3 三层归属表(S1 产出物,此处先锁定语义)
| 层 | 内容 | 仓库位置 |
|----|------|----------|
| **Language** | 标记映射、词法/行分类、AST、语义、升参、**契约检查器**、诊断 | `src/`(解释器核心)· `doc/design/markdown-mapping-v0.3.md` |
| **Runtime** | stdlib、插件 ABI、WASM、debugger、view、catalog / schema CLI、MCP | `lib/` · `plugins/` · `crates/` · `src/bin` |
| **Document** | 知识单元、skills、示例、public 站、agent 工作流、官方扩展 | `*.mq.md` · `skills/` · `ext/` · `public/` · `examples/` |
核心表面清单(S1 的枚举基线,来自宪法 §5,逐项进 `core-surface.md`):
叙述(含 `` `名` `` 声明/引用)· `**…**` 代码 · `*…*` 返回 · 空返回形(`*None*` 等)· `>` 调用 · `#` / `##` 标题单元 · 体内 `1.` 分支 · `-` 循环 · GFM 表格 = 集合 · `[键](集合)` 取元 · `修饰… [函数名]` 方括号调用 · 脚注取元(过渡)· ` ```lang ` 外联 · `---` 叙述分隔 · `` + `名` `` 形参(兼容形)。
### 1.4 解决方向(设计 · 任务化见 plan)
| 步 | 动作 | 产出 | 验收(机器可验证) |
|----|------|------|--------------------|
| S1 | 写 `doc/design/core-surface.md`:穷举核心标记,每个标记一行「戒律」(语义、边界、**为什么不能是普通 Markdown**) | 核心表面唯一清单 | 清单项 ↔ `tests/markup-v03/` 金样逐项有例;缺项即测试红 |
| S2 | 写 `doc/design/layers.md`:§1.3 归属表 + **准入戒律**——任何新特性提案必须先填「进哪层」;进 Language 层必须答「为什么现有标记不够」,默认答案是「进 ext」 | 归属与准入制度 | 仓库 PR 模板加「层归属」必填项 |
| S3 | 核心表面守卫:Rust 测试断言「词法分类枚举 ↔ core-surface.md 表格」一致(脚本解析 markdown 表格比对枚举名) | `tests/core_surface.rs` | 故意加一个新标记不更新清单 → CI 红 |
| S4 | 核心变更强制走 ADR:新增核心标记必须有 `doc/adr/` 编号 + 反例说明;每个 release 的 CHANGELOG 单列「核心表面 Δ」 | ADR 戒律 | 发版 checklist 含「核心表面 Δ」栏 |
| S5 | 文档收口:README/doc 目录按三层重排;`doc/design/` 只收 Language 层决策,Runtime 进 `doc/roadmap/`,生态面进各自 ext 文档 | 重排后的文档树 | README 目录树与三层表一一对应 |
**观测指标**(不是 KPI,是体检):核心标记计数每个 release 只许持平或下降;连续 3 个版本增长即触发 Language 层复盘。
### 1.5 遮盖 vs 解决
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|--------------------|--------------|------|
| 写一篇「语言核心很重要」的宣言 | 清单 + 归属表 + **CI 守卫** | 新增标记不更新清单时 CI 必须红 |
| 「以后尽量不加语法」的口头约定 | ADR 强制 + CHANGELOG 核心表面 Δ | 没有 ADR 编号的核心变更不允许合并 |
| 把 ext 功能砍掉显得小 | 不砍功能,只**归层** | web/quantum/agent 全部保留且测试通过 |
---
## 2. 问题二:渐进式契约 / 标注类型
### 2.1 分歧点澄清(本方案的立场)
GPT 一侧强调「AI 可验证语言需要强语义校验」,容易被听成「上静态类型」。**这两件事不一样**:
> 「放弃全程序静态编译类型」**≠** 「放弃语义检查、字段解析、契约校验」。
照搬 Java/TS 式静态类型会破坏「自然叙述优先、低摩擦」的体验——Marqdo 会变得笨重,丢掉对业务人员 / agent 即兴脚本的友好性。**目标不是变成静态语言,而是一套附着在文档单元上的可查询契约系统,作为 AI 闭环里的校验层。**
渐进式契约的四条特征:
1. **动态默认**——不强制任何标注,保持动态,适合快速原型与 agent 即兴脚本;
2. **契约即文档**——schema 可选地写在**表格、文档段落**里,不引入第二套标注语言;
3. **按需校验**——不做全局类型推导;在调用边界 / 字段访问时校验「当前值 vs 契约」;
4. **诊断即文档链接**——错误不只报类型错,还定位到文档里对应的说明段落,给 AI 的诊断自带文档上下文。
**独有优势(TS/Python 做不到)**:契约的 schema 源头就是表格与函数说明段落本身——不是额外写一套 JSON Schema。知识、契约、数据、代码在同一份 `.mq.md` 里,**契约即知识**。这是 Knowledge-Code Coherence 的第一个可落地实证:契约说 `int` 实际来了 `text` 时,被机器抓住的不是「文档过期」,而是**知识不一致**。
### 2.2 设计原则
| # | 原则 | 含义 |
|---|------|------|
| P1 | 无契约 = 全动态 | 没写契约的单元行为**一字不变**(零回归是硬验收) |
| P2 | 不新增核心标记 | 契约语法全部骑在现有 Markdown 外形上(问题一戒律直接约束本节) |
| P3 | 契约是数据 | 契约表本身就是 Marqdo 集合,运行时可内省(`get_schema` 一类的 lib 函数免费获得) |
| P4 | 双向防漂移 | 不只「值 vs 契约」,还查「契约 vs 实现」(§2.7-S5) |
| P5 | 诊断带锚点 | 凡契约诊断必含:契约表所在文件 + 行段 + 原文引用 |
### 2.3 契约的三个附着面
**A. 函数契约** —— `##` 函数体内、首个可执行行之前的**未绑定文档表**:
```markdown
## 加一
加一函数:把输入加一。
| 参数 | 类型 | 说明 |
|------|------|------|
| `n` | number | 输入值 |
| 返回 | 类型 | 说明 |
|------|------|------|
| — | number | n+1 |
对于输入变量`n`,执行**n=n+1**接着返回*n*。
```
参数仍由 v0.3 升参推断(宪法 §8),契约**不改变**形参机制,只在存在时校验——零摩擦兼容存量代码。
**B. 集合 / 表格契约** —— 紧邻 `` `名` = `` 绑定之前的未绑定文档表:
```markdown
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | 否 |
| name | text | 否 |
`用户` =
| 行 | id | name |
|----|----|------|
| 1 | 1 | 甲 |
```
**C. 对象契约** —— `# 对象` 体内首个成员之前的 `| 字段 | 类型 |` 表;同时被 catalog 提取为条目 schema(见 §3.5 项目面)。
**先例**:schema 长在表格里今天已经发生——`web_db_migration` 的 `| 字段 | 类型 | 可空 |` 列就是以数据形式传递的 DDL schema。契约系统把这个模式升格为**通用约定**。
### 2.4 形态选型(为什么是「契约表」)
| 候选 | 形态 | 判决 |
|------|------|------|
| **P-A 契约表**(选定) | 列头关键字(`参数`/`返回`/`字段`/`类型`/`说明`)的未绑定文档表 | ✅ 与「GFM 表格即数据」哲学一致;catalog 可提取;人读无负担 |
| P-B 叙述内标注 | `` `n`: int `` 写在散文里 | ❌ **否决**:改动行内 `` `名` `` 词法 = 核心标记变更,违反问题一戒律与 P2 |
| P-C frontmatter | YAML 声明契约 | ⚠️ 仅作文件级汇总的可选补充(serde_yaml 已在解析元信息);函数粒度不够,不作主形态 |
**消歧规则(防「契约表」误吃数据表)**:
1. **被绑定的表永不视为契约表**——`名` = 后的表是数据(宪法 §5:未绑定才「求值后丢弃」,即文档表)。`web_db_migration` 的列头恰好叫 `字段|类型|可空` 但它是绑定数据,不受影响;
2. 契约表必须是**未绑定文档表** + 列头命中关键字集,且出现在允许位置(§2.3 A/B/C);
3. 同一位置出现多张契约表:参数表与返回表各认各的列头;其余重复 → 诊断(防两份契约打架)。
### 2.5 类型词汇(刻意做小)
`text` · `number` · `bool` · `list` · `map` · `any` · 对象名(与 `# 对象` / `_type` 对齐)。
- 词汇表**只有这一行**;扩展类型词汇 = Language 层变更,走 ADR(问题一 S4)。
- 类型名拼错(如 `nubmer`)→ **必须报诊断**(§2.7 验收),否则契约本身成为新的漂移源。
### 2.6 校验时机(按需四边界,不做全局推导)
| 边界 | 校验什么 | 时机 |
|------|----------|------|
| 调用实参 | 实参值 vs 参数契约(类型 + 可选 required) | 运行时调用瞬间;`check` 静态可查处一并查 |
| 字段访问 | `[键](集合)` / `obj.field` vs 字段契约(键存在性 + 类型) | 访问瞬间 |
| 表绑定 | `` `名` = `` 表的几何/单元格 vs 集合契约 | 绑定瞬间 |
| 返回 | `*…*` 值 vs 返回契约 | 返回瞬间 |
无契约 → 该边界直接跳过(P1)。校验器**不是**编译器:不做跨函数全局推导、不要求全程序一致。
### 2.7 解决方向(设计 · 任务化见 plan)
| 步 | 动作 | 产出 | 验收(机器可验证) |
|----|------|------|--------------------|
| S1 | 契约提取器:按 §2.3/§2.4 规则解析未绑定文档表 → `Contract` 对象,挂入 AST 单元(`Param` 已有 `span`,契约同级带 `span`) | AST + 提取器 | 金样:三附着面各一份提取断言(含「绑定表不吃」反例) |
| S2 | 运行时边界校验:§2.6 四边界接入 `Contract` | 运行时校验 | 有契约 + 错值 → **必**产出 §3.3 诊断;无契约金样**全绿零回归** |
| S3 | `marqdo check`:静态按需校验(只查有契约处),`--json` 输出诊断 | CLI | 契约样例工程 `check` 退出码非 0 且诊断 JSON 合协议 |
| S4 | 诊断锚点:契约错误必带 `doc_anchor` + `doc_quote`(契约表原文行) | 诊断增强 | 金样断言诊断 JSON 里锚点字段非空、行号可回读原文 |
| S5 | **契约 vs 实现互查**(P4):契约参数名 ≠ 升参推断名、契约类型名未知、契约返回 vs 语句结构明显不符 → 诊断 | 防漂移检查 | 故意写错契约的金样**必须**红(而不是静默信任契约) |
| S6 | 运行时内省:`lib` 提供 `get_schema 单元=…`(P3:契约是数据) | lib 函数 | demo:运行中取回自身函数契约表并打印 |
### 2.8 遮盖 vs 解决
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|--------------------|--------------|------|
| 把「静态类型」继续列为非目标就收工 | 明确「≠ 放弃语义校验」,落**边界校验器** | 运行时行为变化可测(§2.7-S2) |
| 照搬 Java/TS 全程序静态类型 | 渐进式:无标注零摩擦,按需四边界 | 无契约金样零回归 |
| 另写一套 JSON Schema 文件 | schema = 表格 / 说明段落本身 | 仓库里**不允许**出现手写的第二份 schema;契约只能从 `.mq.md` 提取 |
| 契约写了就永远正确 | 契约 vs 升参互查 + 未知类型名必报 | 故意写错契约的金样必红 |
| 错误只报 `type mismatch` 文本 | 诊断带文档锚点 + 原文引用 | 金样断言锚点字段 |
---
## 3. 问题三(超级核心):AI 可靠反馈 + AI 不必学语法细节
### 3.1 两个子问题
**A. 可靠反馈**:今天解释器诊断是给人看的文本(`path:line:col` + message,见 ai-skill「按诊断迭代」)。AI 拿到它要「猜」哪里错、对应文档哪句话、怎么改。GPT 设想的闭环——
```text
LLM → Marqdo → 语义校验 → 结构化 Error → LLM 修复 → 合格程序
```
——的第一块砖就是**结构化诊断**,而且诊断必须自带文档上下文(问题二 §2.1-4 的锚点在这里被 AI 消费)。
**B. 不必学语法**:今天 `skills/marqdo` 是「面向模型的压缩操作手册」= **背诵式**。正确形态是**查询式**:
```text
AI ── discover ─→ construct ─→ validate ─→ execute ─→ inspect
```
AI 不阅读一千行文档然后猜,而是按需调 `get_syntax("branch")`、`fn_schema("print")`、`validate(program)`。**这才是 Marqdo 与普通 DSL 拉开距离的地方。**
### 3.2 总形态:Marqdo Language Server for AI(MLSP)
一套机器可读的语言服务协议。工具面(首版最小集):
| 工具 | 入参 | 返回 | 数据源 |
|------|------|------|--------|
| `syntax_list` / `syntax_get` | — / 构造名 | 核心构造表 / 单构造戒律 | core-surface(问题一 S1,机械转 JSON) |
| `fn_schema` | 函数名 | 参数/返回契约 + 说明 + 锚点 | 契约(问题二)+ stdlib/ext 签名 |
| `type_schema` | 对象名 | 字段契约 + 方法表 | `# 对象` 契约 + catalog |
| `validate` | 程序文本/文件 | `Diagnostic[]` | 契约校验器 + 语义检查 |
| `repair` | 程序 + 诊断 | 建议 patch(限定行级) | 诊断规则库 |
| `run` | 入口 | 结果或结构化错误 | 运行时 |
交付通道(按序):**`marqdo mcp`**(MCP server,复用 agent ext 的 MCP 经验)→ CLI `--json`(任何宿主可用)→ `skills/marqdo` 改造成「教 AI 查询」(§3.6)。
### 3.3 先决:统一诊断协议(可靠反馈的地基)
所有层(解释器、check、契约、插件错误)统一产出:
```json
{
"code": "contract.arg_mismatch",
"severity": "error",
"message": "参数 `n` 期望 number,实际 text",
"span": { "file": "demo.mq.md", "line": 12, "col": 3, "heading": ["加一"] },
"doc_anchor": "demo.mq.md#L4-L7",
"doc_quote": "| `n` | number | 输入值 |",
"contract_ref": { "unit": "加一", "kind": "param", "name": "n", "declared": "number" },
"suggestion": "把实参改为数字;若契约有误,改契约表的类型列"
}
```
规则:
1. 凡可定位必带 `span`(AST 已有 span,宪法 §10.2);
2. 凡契约错误必带 `doc_anchor` + `doc_quote`——**错误直接定位到文档里对应的说明段落**;
3. 凡可修复建议必带 `suggestion`(给修复回路的原料);
4. 人类文本输出保持现状,`--json` 并行提供——人机同读同写,诊断也一样。
### 3.4 修复回路(repair loop)
```text
validate(p) → diagnose → patch(p, diag) → validate(p') → … (预算 N=3 轮)
```
- **限定行级 patch**,不允许整文件重写(防止 AI「修复」时破坏叙述);
- 尝试预算与重复诊断去重,防循环;
- 实验指标:**一轮修复率**(带锚点 vs 不带锚点两组对比)——这是「可靠反馈」的直接证据。
### 3.5 Schema 注册表(三来源,零手写第二份)
| 面 | 来源 | 说明 |
|----|------|------|
| 语言面 | `core-surface.md` 机械转 JSON | 构造戒律原文进 `description` |
| 函数 / 类型面 | **契约**(问题二产物)+ stdlib/ext 签名 | schema 源头 = 表格与说明段落(§2.1 独有优势) |
| 项目面 | `catalog.yaml`(catalog 自动生成) | 知识单元、链接关系(知识图的边) |
格式 `marqdo-schema.json`(示意):
```json
{
"language": "marqdo",
"version": "0.3",
"constructs": [{ "name": "branch", "syntax": "1. … 2. … N. *", "rule": "自 1. 递增;重出 1. 开新判断" }],
"functions": [{ "name": "加一", "params": [{ "name": "n", "type": "number", "desc": "输入值", "anchor": "#L4" }], "returns": { "type": "number" } }]
}
```
命令:`marqdo schema [PATH]`(catalog 的兄弟命令,同样**只生成不手改**)。
### 3.6 AI Skill:从「背诵」改「查询」
`skills/marqdo` 改造原则:
- `SKILL.md` 只留**十条不可违反的硬规则**(叙述默认安全、`**` 代码 `*` 返回、表格几何、命名/双语约定等)+ MLSP 工具用法;
- 语法细节、API 明细**一律走 `syntax_get` / `fn_schema`**,不再进上下文;
- 工作流改为:construct(凭硬规则写)→ `validate` → 按诊断修 → `run`。
### 3.7 解决方向(设计 · 任务化见 plan)
| 步 | 动作 | 验收(机器可验证) |
|----|------|--------------------|
| S1 | Diagnostic 结构落地(Rust)+ 解释器诊断改造 + `run --json` / `check --json` | 现有错误金样转 JSON 后 `code`/`span` 全非空 |
| S2 | 契约诊断接入(消费 §2.7-S4 的锚点) | §2.8 判据全部成立 |
| S3 | `marqdo schema` 生成器(三来源汇聚) | 生成物 diff 稳定(两次生成 byte-identical);stdlib 主函数覆盖率 ≥ 90% |
| S4 | `marqdo mcp`:暴露 §3.2 工具面 | 用 MCP 客户端冒烟:`fn_schema` → `validate` → `repair` 全链路 |
| S5 | `skills/marqdo` 改造为查询式(保留硬规则十条) | skill 体积减半以上;既有 `marqdo run` 金样仍全绿 |
| S6 | 修复回路 + 实验执行(实验设计见 §5.2) | 实验报告(进 MarqdoThesis,对接 README 愿景 6) |
**「解决而不是遮盖」的最终判据(问题三)**:盲测组(零语法文档 + 工具)的成绩**不劣于**全文档背诵组,且 token 显著更少、修复轮次不升——达不到就继续改协议,**不许**用「再写一篇更好的文档」充数。
### 3.8 遮盖 vs 解决
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|--------------------|--------------|------|
| 再写一份更全的 AI 语法文档 | 查询协议 + schema 注册表 | 盲测实验成立 |
| 让 AI「多读 reference.md」 | `syntax_get` / `fn_schema` 按需取 | skill 体积减半且成绩不降 |
| 报错文本润色一下 | 统一 Diagnostic JSON + 文档锚点 | 诊断金样断言锚点字段 |
| 主观感觉「AI 好用了」 | 一轮修复率 / 盲测 / token 三组数字 | 实验报告可复现(MarqdoThesis) |
---
## 4. 路线顺序(依赖序 · 排期见 [three-problems-plan.md](three-problems-plan.md))
> 本表是**依赖顺序**,不是排期表——任务化与本期范围见 [three-problems-plan.md](three-problems-plan.md)。
| 顺序 | 内容 | 产出 | 依赖 |
|------|------|------|------|
| **M0 核心收口** | 问题一 S1–S5 | core-surface.md · layers.md · CI 守卫 | — |
| **M1 诊断地基** | 问题三 S1(Diagnostic + `--json`) | 统一诊断协议 | M0 |
| **M2 契约层** | 问题二 S1–S6 | 提取器 · 四边界校验 · `check` · 锚点 · 防漂移 | M1 |
| **M3 AI 语言服务** | 问题三 S2–S5 | schema 生成 · `marqdo mcp` · 查询式 skill · 修复回路 | M2 |
| **M4 实证** | 问题三 S6 | 修复实验 + 盲测 + 消融(对接 README 愿景 6) | M3 |
顺序理由:Diagnostic 先于契约(契约诊断是它的第一个消费者);契约先于 MLSP(契约是 schema 注册表的主数据源)——**任何一个跳步都会倒逼「另写一套 schema / 另造一套错误」的遮盖式捷径**。
---
## 5. 验证矩阵与实验设计(本文核心)
### 5.1 判据矩阵:什么算「已解决」
| 问题 | 解决的定义(机器可验证) | 遮盖式收场(一句话就能写完的,禁止) | 验证手段 | 判定(2026-09-23) |
|------|--------------------------|--------------------------------------|----------|--------------------|
| 1 核心要小 | 新标记不更新 core-surface → **CI 红** | 「我们重视语言核心」 | CI 守卫演练:故意加标记不更新清单,必须红 | ✅ (e) 3/3 必红→还原必绿 |
| 2 语义校验 | 四边界校验器上线;契约写错**必**被机器抓;无契约路径零回归 | 「静态类型是非目标」/照搬 TS 类型/另写 JSON Schema | 契约金样 + 防漂移金样 + 全量回归 | ✅ (c) 拦截 100%/误报 0%/零回归;(d) 必报 9/9 |
| 3 AI 反馈 / 语法 | 盲测组错误率 ≤ 全文档组且 token 显著更少;一轮修复率可复现 | 「再写更好的文档」 | §5.2 实验 (a)(b)(d) | ❌ (a) 过(双模型 100%);**(b) 四判据未全立** ⇒ 按 §3.7 继续改协议 |
> 2026-09-23 实测数字与判据对照:[perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。
> 按本矩阵口径:**问题 1、2 实证成立;问题 3 未解决**(查询式盲测未跑赢全背诵——详见报告 §3 的四条要点,
> 其中「模型不查自己不知道的语法」是协议改进的主攻方向)。
### 5.2 实验设计(性能 / 可靠性验证)
| 实验 | 对照组 | 指标 | 材料 |
|------|--------|------|------|
| (a) 锚点修复 | 诊断带 `doc_anchor` vs 不带 | 一轮修复率、平均修复轮次 | 注入已知 bug 的金样集 |
| (b) 盲测(零语法文档) | 只给 MLSP 工具 vs 给全文档背诵(现 `skills/marqdo`) | 语法错误率、契约违规率、token 消耗 | 任务集(QuixBugs 类 + 业务逻辑类) |
| (c) 契约消融 | 契约开 / 关 | 契约拦截率、误报率、无契约路径零回归 | 同上 |
| (d) 防漂移演练 | 契约故意写错(类型 typo / 参数名与升参不符) | 必报率 = 100% | 契约金样 |
| (e) 核心守卫演练 | 故意加新标记不更新清单 | CI 红 = 必须 | — |
实验基建:复用 MarqdoThesis `formal/exp1–3` 的 runner / oracle / 容错重试;报告即 README 愿景 6 的「可靠性基准」材料。**判据矩阵全绿 + 实验数字可复现之前,三大问题一律视为未解决**——这是「不遮盖」的最终保险。
---
## 6. 未决问题(进 M0/M2 的 ADR 逐条锁定)
1. 契约表消歧的边界案例:紧邻绑定的未绑定表(注释表)紧贴数据表时的归属规则要不要「隔空行才算分离」?(M2-S1 金样定夺)
2. 参数表与返回表合并成单表(首列 `参数`/`返回` 混排)是否更可读?(M2-S1 对比样例后定)
3. 对象字段契约:与 [objects.md](../design/objects.md) 「不把表当对象定义语言」的非目标如何划界——契约是**可选校验元数据**,不定义对象布局(对象仍是运行时 map);需 ADR 明文,避免与 [tables-maps-footnotes.md](tables-maps-footnotes.md) 非目标条目互相打架。
4. 类型词汇是否收 `对象名` 之外的复合形(如 `list<number>`)?——默认**不收**,需要时走 ADR(P2 + 问题一 S4)。
5. `marqdo check` 独立子命令 vs `run --check` 并存?(M2-S3 定,倾向独立 + `run` 默认轻查)
6. `repair` 的 patch 边界:行级 patch 的具体格式(unified diff vs 语句级替换)?(M3-S4 定,倾向语句级——与 AST span 对齐)