- 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>
394 lines
26 KiB
Markdown
394 lines
26 KiB
Markdown
# 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 对齐)
|