- perf-validation-report §3 记录重跑终局(12/12→11/12 infra),(b) 判据判定不改 - three-problems-plan Phase 4 落地记录同步 Co-authored-by: Cursor <cursoragent@cursor.com>
226 lines
16 KiB
Markdown
226 lines
16 KiB
Markdown
# 三大问题落地计划(core 收口 · 渐进式契约 · MLSP)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **本期开发依据 · 执行中** |
|
||
| 日期 | 2026-09-22 |
|
||
| 设计 | [three-problems.md](three-problems.md)(解决方向与验证设计;判据矩阵 §5.1) |
|
||
| 范围 | **工程任务 = Phase 1–3**;验证实验(three-problems.md §5.2)协议见 [perf-validation.md](perf-validation.md)(2026-09-23 用户授权自行设计并执行) |
|
||
| 约定 | 每任务带机器可验证验收;**任务完成 = 验收全绿 + 全量回归绿**;只改宣言不改行为 = 未完成 |
|
||
|
||
## 0. 本期范围与依赖
|
||
|
||
| 阶段 | 定位 | 本期 |
|
||
|------|------|------|
|
||
| **Phase 1** 核心收口 + 诊断地基 | 一切的地基 | ✅ 启动 |
|
||
| **Phase 2** 渐进式契约层 | 校验层(schema 源头 = 表格/段落) | ✅ 本期主目标 |
|
||
| **Phase 3** MLSP(AI 语言服务) | **下一步的超级核心**(AI 不必学语法 + 可靠反馈闭环) | ⏭ 下期启动,本期只留接口 |
|
||
| **Phase 4** 验证实验 | 性能验证(非开发任务) | ❌ 不认领 |
|
||
|
||
依赖链(**跳步会倒逼「另造一套错误 / 另写一套 schema」的遮盖式捷径**):
|
||
|
||
```text
|
||
T1.4 Diagnostic ──是──> T2.x 契约诊断的唯一出口
|
||
T2.x 契约 ───────是──> T3.1 schema 注册表的主数据源
|
||
T1.1 core-surface ─是─> T3.1 语言面 + T1.3 守卫
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 1 · 核心收口 + 诊断地基(本期启动)
|
||
|
||
### T1.1 核心表面清单
|
||
|
||
- **产出**:`doc/design/core-surface.md`
|
||
- **实现要点**:
|
||
- 两张表:**行构造**(heading-unit `#`/`##`、call-line `>`、branch-list `1.`、loop-list `-`、param `+ 名`、table、fence、hr、writeback、narrative、blank)与**内联标记**(ident `` `名` ``、bold-code `**…**`、italic-return `*…*`、empty-return、link-index `[键](集合)`、bracket-call `[函数]`、footnote-index `[^键]` 过渡);
|
||
- 每行含:**id**(英文 kebab,守卫用)、Markdown 外形、语义、**戒律**(边界 + 为什么不能是普通 Markdown)、**金样**(`tests/markup-v03/…` 路径);
|
||
- 与 [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) §5 / §10 对齐;词法大类(`src/lex/mod.rs` `LineKind`)另列一节说明与构造表的关系。
|
||
- **验收**:每行金样文件真实存在(T1.3 断言);id 全集 = T1.3 `CORE_CONSTRUCTS` 全集。
|
||
|
||
### T1.2 三层归属与准入戒律
|
||
|
||
- **产出**:`doc/design/layers.md` + `.github/PULL_REQUEST_TEMPLATE.md`(无则新建)
|
||
- **实现要点**:
|
||
- 归属表(含仓库路径):Language = `src/lex` `src/parse` `src/ast` `src/interp` `src/diagnostics` + 契约检查器;Runtime = `lib/` `plugins/` `crates/` `src/catalog.rs` `src/view` `src/debug` + 未来的 check/schema/mcp;Document = `*.mq.md` `skills/` `ext/` `public/` `examples/`;
|
||
- 准入戒律:新特性先填层归属;进 Language 必答「为什么现有标记不够」;默认进 ext;核心标记计数每 release 只许持平或下降;
|
||
- 发布 checklist:CHANGELOG 增「核心表面 Δ」栏(写入 `skills/marqdo-release/SKILL.md` 一步)。
|
||
- **验收**:PR 模板含「层归属」必填项;layers.md 与 core-surface.md 互相引用闭合。
|
||
|
||
### T1.3 核心表面守卫(CI)
|
||
|
||
- **产出**:`tests/core_surface.rs` + `src/parse/mod.rs` 增 `pub const CORE_CONSTRUCTS: &[(&str, &str)]`(id、外形;**紧邻分类代码维护**)
|
||
- **实现要点**:`include_str!` 解析 core-surface.md 表格 id 列 ↔ `CORE_CONSTRUCTS` **双向集合相等**;每行「金样」路径 `Path::exists()` 断言。
|
||
- **验收(反遮盖核心)**:
|
||
- 新增 `CORE_CONSTRUCTS` 条目不改文档 → **红**;
|
||
- 文档加行不改代码 → **红**;
|
||
- 删除/改名金样文件 → **红**。
|
||
|
||
### T1.4 诊断对象扩展(Phase 2/3 的唯一出口)
|
||
|
||
- **产出**:`src/diagnostics.rs` 扩展 + `src/main.rs` `run --json`
|
||
- **实现要点**:
|
||
- `Diagnostic` 增 `code`(如 `parse.*` / `contract.*` / `runtime.*`)、`severity`、`suggestion`、`doc_anchor`、`doc_quote`、`contract_ref`(Phase 2 起填值);`::new/at` 签名不变(全仓调用零改动),新增 builder 方法;
|
||
- `serde::Serialize` + `to_json()`;**Display 保持 `path:line:col: message`**(人类输出零回归);
|
||
- `run --json`:顶层错误路径把 Diagnostic 序列化输出(stderr JSON 行)。
|
||
- **验收**:现有错误金样文本输出**零变化**;新金样断言 JSON `code`/`span` 非空;`cargo test` 全绿。
|
||
|
||
---
|
||
|
||
## Phase 2 · 渐进式契约层(本期主目标)
|
||
|
||
### T2.1 契约 AST + 提取器
|
||
|
||
- **产出**:`src/contract.rs`(`Contract` / `ParamContract` / `FieldContract` + 类型词汇 `text/number/bool/list/map/any/对象名`);`src/parse/`(提取);`src/ast.rs`(挂载,带 span)
|
||
- **实现要点**:按 [three-problems.md](three-problems.md) §2.3/§2.4——**未绑定文档表** + 列头关键字(`参数/返回/字段/类型/说明`)+ 允许位置(函数体首个可执行行前 / 绑定前 / 对象体首成员前);**被绑定的表永不视为契约表**。
|
||
- **验收**:三附着面金样 + 「绑定表不吃」反例金样(web_db_migration 式 `字段|类型|可空` 绑定数据表必须原样是数据);未知类型名(`nubmer`)必产诊断。
|
||
|
||
### T2.2 四边界运行时校验
|
||
|
||
- **产出**:`src/interp.rs` 接入四边界——调用实参 / 字段访问(`[键](集合)`、`.field`)/ 表绑定 / `*…*` 返回
|
||
- **实现要点**:只在**该边界有契约**时校验(无契约 = 全动态,P1);诊断一律走 T1.4 出口(`code=contract.*`)。
|
||
- **验收**:有契约 + 错值 → 必产诊断;**无契约路径全量回归零变化**;three-problems.md §5.2(c) 消融材料可产。
|
||
|
||
### T2.3 `marqdo check` + `--json`
|
||
|
||
- **产出**:`src/check.rs` + `src/main.rs` `Commands::Check`
|
||
- **实现要点**:静态**按需**校验(只查有契约处);不做全局推导。
|
||
- **验收**:契约样例工程 `check` 退出码非 0 且 JSON 合协议;干净工程 0 退出零输出。
|
||
|
||
### T2.4 锚点诊断
|
||
|
||
- **产出**:契约诊断填 `doc_anchor`(契约表行段 `file#Lx-Ly`)+ `doc_quote`(表行原文)
|
||
- **验收**:金样断言锚点非空且行号回读命中契约表;three-problems.md §5.2(a) 材料就绪。
|
||
|
||
### T2.5 契约 vs 实现互查(防漂移)
|
||
|
||
- **产出**:check + 运行时提示——契约参数名 ≠ 升参名 / 未知类型 / 返回契约明显不符 → 诊断
|
||
- **验收**:故意写错契约的金样**必红**(three-problems.md §5.2(d) 材料就绪)。
|
||
|
||
### T2.6 运行时内省 `get_schema`(可延后,P3)
|
||
|
||
- **产出**:`src/builtin.rs` 内省 builtin(契约是数据,P3)
|
||
- **验收**:demo 运行中取回自身函数契约并打印。
|
||
|
||
---
|
||
|
||
## Phase 3 · MLSP(下一步的超级核心;本期只留接口)
|
||
|
||
### T3.1 `marqdo schema`(schema 注册表,三来源零手写)
|
||
|
||
- **产出**:`src/schema.rs` + `Commands::Schema`——语言面(core-surface 机械转 JSON)+ 函数/类型面(**契约** + stdlib/ext 签名)+ 项目面(`catalog.yaml`)
|
||
- **验收**:两次生成 byte-identical;stdlib 主函数覆盖率 ≥ 90%。
|
||
|
||
### T3.2 `marqdo mcp`(AI 工具面)
|
||
|
||
- **产出**:MCP server(参考 `plugins/agent/src/mcp_server.rs`)——`syntax_list` / `syntax_get` / `fn_schema` / `type_schema` / `validate` / `repair` / `run`
|
||
- **验收**:MCP 客户端冒烟:`fn_schema` → `validate` → `repair` 全链路。
|
||
|
||
### T3.3 查询式 AI Skill
|
||
|
||
- **产出**:`skills/marqdo/` 改写——十条硬规则 + 查询工作流(construct → validate → 修 → run);细节一律走 `syntax_get` / `fn_schema`
|
||
- **验收**:skill 体积减半以上;金样全绿。
|
||
|
||
### T3.4 修复回路
|
||
|
||
- **产出**:repair 规则库 + 语句级 patch(AST span 对齐;预算 N=3;防循环)
|
||
- **验收**:注入 bug 金样一轮修复率可测(three-problems.md §5.2(a) 执行就绪)。
|
||
|
||
---
|
||
|
||
## Phase 4 · 验证实验(**协议 = [perf-validation.md](perf-validation.md)**)
|
||
|
||
- 2026-09-23 用户授权**自行设计**性能验证设计并执行验证;`doc/next/002.md` 与性能验证无关(此前「待导入」表述已纠正)。
|
||
- five 实验 (a)–(e) 的**材料由 Phase 1–3 的验收金样直接供给**;协议 / 指标 / 判据见 [perf-validation.md](perf-validation.md) §1–§5;
|
||
实验产物 = [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。
|
||
|
||
---
|
||
|
||
## 完成定义
|
||
|
||
| 阶段 | 完成定义 |
|
||
|------|----------|
|
||
| Phase 1 | T1.1–T1.4 验收全绿 |
|
||
| Phase 2 | T2.1–T2.5 验收全绿(T2.6 可延后) |
|
||
| Phase 3 | T3.1–T3.4 验收全绿 |
|
||
| 三大问题「已解决」 | [three-problems.md](three-problems.md) §5.1 判据矩阵全绿 + 实验数字可复现(Phase 4) |
|
||
|
||
## 落地记录
|
||
|
||
### Phase 2 · 渐进式契约层(2026-09-22 完成 T2.1–T2.5;T2.6 按计划延后至 Phase 3)
|
||
|
||
- **T2.1** `src/contract.rs`(类型词汇/三形状契约表解析/合并/四边界校验诊断)+
|
||
`src/parse/mod.rs::extract_function_contract`(位置 + 形状双重判定,**在升参推断之前**执行——
|
||
契约表的单元不会被误升参;契约表从 body 移除,元数据永不执行)。
|
||
反例守住:**绑定**的 `字段|类型` 数据表(web_db_migration 风格)绝不视为契约。
|
||
- **T2.2** 四边界全接:调用实参(普通/库路径/方法三条调用路径)、返回、表绑定、字段访问
|
||
(键存在性**先于**取值,契约诊断优先于 `missing map key`)。列语义按「几何即类型」:标量或全匹配列向量。
|
||
- **T2.3/T2.5** `marqdo check [FILE] [--json]`:契约行 vs 升参推断形参双向互查
|
||
(错行 ⇒ Error;新升参未覆盖 ⇒ Warning)、未知类型名(附最近建议)、错位契约;Error ⇒ 非零退出。
|
||
- **T2.4** 全部契约诊断带 `doc_anchor`(`file.mq.md#L7-L13`)+ `doc_quote`(契约表原文)+
|
||
`contract_ref`(`declared` = 契约声明摘要);`run --json` / `check --json` 同源输出。
|
||
- **附带修复(错误出口唯一)**:`src/load.rs` 原来把 parse 错误 `anyhow!("{label}: {e}")` 拍平成字符串,
|
||
结构化诊断在 import 装载链路丢失;改为 `label_error` 保留 Diagnostic(补文件标签),任何装载层都不许拍平错误。
|
||
- 验收:`tests/contracts.rs` 12 例(提取 4 + 四边界 4 + check 3 + 正向对照 1)全绿;
|
||
全量回归零失败(含 262 gold)。
|
||
- **T2.6(契约导出 `get_schema`)**:按计划延后至 Phase 3 与 MLSP `schema` 一并实现。
|
||
|
||
### Phase 3 · MLSP(2026-09-22 完成 T3.1–T3.4 全部工程项 + T2.6)
|
||
|
||
- **T3.1** `marqdo mlsp` 子命令:行分隔 JSON over stdio,请求 `{"id","method","params"}` →
|
||
响应 `{"id","ok","result"|"error"}`(永不 panic,错误也是结构化 JSON)。
|
||
- **T3.2** 五个 handler 全部实现(`src/mlsp.rs`):
|
||
`locate`(构造卡片 / 符号定位 + 契约)、`syntax`(关键字/别名 → 卡片;语法唯一事实来源 =
|
||
`parse::CORE_CONSTRUCTS`,MLSP 只加检索别名不定义语法)、`validate`(parse + 契约 check → 结构化诊断数组)、
|
||
`repair_targets`(有界修复靶点:`strategy=anchored-local`、`on_violation=abstain`——越界必拒护栏先行)、
|
||
`schema`(**T2.6 完成**:单元名 → 形参/返回/字段契约 + 升参清单 + 锚点)。
|
||
- 验收:`tests/mlsp.rs` 7 例全绿(语法问答/未知查询/符号定位/漂移校验/schema 导出/有界修复/结构化错误);
|
||
stdio 冒烟通过;全量回归零失败。
|
||
- **T3.4(修复回路)**(2026-09-22 完成工程项)——`src/repair.rs` **机械护栏**(有界行编辑
|
||
replace/delete/insert:触碰行必须落在靶点范围内,越界 ⇒ 整体拒绝 + 越界清单 + abstain,源零字节不改;
|
||
表尾追加允许 end+1)+ `mlsp repair_apply` 出口(护栏的 MLSP 面)+ **golden 20 例**
|
||
(10 骨架 × 2 变体:arg/ret/field/key/typo/drift/dup;金修复经完整修复循环复现——诊断 → 靶点 →
|
||
行编辑自动推导 → 范围自检(「易锚定」的机器验证)→ 应用 → 复验)+ 护栏负例(越界必拒/部分越界全拒)。
|
||
**模型实验完成(2026-09-22 · `tests/repair_experiment.rs` · 双模型三轮 @ llm.cflmy.cn)**:
|
||
§5.2(a) 锚点消融——`anchor` 臂(诊断带 `doc_anchor`/`doc_quote`/`suggestion`)**一轮修复率最高 20/20 = 100%**(目标 ≥80% ✅);
|
||
`plain` 臂(去锚)85%–100%。三轮汇总:
|
||
|
||
| 轮 | 模型 | anchor 一轮 | anchor 最终 | plain 一轮 | plain 最终 | 护栏越界 |
|
||
|---|---|---|---|---|---|---|
|
||
| 1 | `cflmy`(Qwen3.8-Flash-Next) | **20/20(100%)** | 100% | 17/20(85%) | 17/20 | 0 |
|
||
| 2 | `mimo-v2.6-flash`(容错加固中) | 18/20(90%) | 19/20(95%) | 19/20(95%) | 19/20 | 0 |
|
||
| 3 | `mimo-v2.6-flash`(容错补齐后) | **20/20(100%)** | 100% | 18/20(90%) | 19/20(95%) | 0 |
|
||
|
||
**"≥80% 一轮修复率"三轮双臂全部达标(最低 85%)**;护栏 0 越界(越界必拒/abstain 由确定性测试
|
||
`tests/repair_loop.rs` 硬断言覆盖)。实验同时是 `validate`→`repair_targets`→`repair_apply` 功能面的真实消费者。
|
||
**"不稳定"定性为三类测量端问题,均已加固**(与 Marqdo 语义无关):① 网关空体抖动 → curl `--retry` + 5s 退避;
|
||
② 推理模型 token 预算被 `reasoning_content` 吃光 → `max_tokens` 2000→8000;③ 模型输出格式畸形 → 解析容错
|
||
(数组/单对象/NDJSON 多对象流/字符串化元素/字符串型行号/围栏/数字后多余引号的确定性修补)。
|
||
锚点增量观察:易锚定样本两臂都高(天花板效应),cflmy 上 anchor +20pp 明显、mimo 上持平——
|
||
**锚点价值的区分性验证留 Phase 4**(难样本/信息受限消融)。
|
||
报告:[repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md)(cflmy)、
|
||
[repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)(mimo 终测)。
|
||
- **T3.3(AI Skill 换骨:背语法 → 查 MLSP)**(2026-09-22 完成)——`marqdo` / `marqdo-dev` 两件套改为
|
||
查询式工作流:写码前 `mlsp syntax/locate`、提交前 `mlsp validate` + `marqdo check`;
|
||
渐进式契约三种表格形状入语法面;错误修复照 `doc_anchor` 局部改(越界必弃权)。
|
||
|
||
## Phase 4 · 验证执行记录(2026-09-23,协议 [perf-validation.md](perf-validation.md))
|
||
|
||
- **(a) 锚点修复消融** ✅ PASS——判据「anchor 一轮 ≥80% + 护栏 0 越界」:cflmy anchor 20/20=100%(plain 85%)、
|
||
mimo-v2.6-flash anchor 20/20=100%(plain 90%),越界拒/越界应用 0/0。易锚定样本近天花板,
|
||
增量区分性留难样本扩展(协议 §1 诚实注记)。
|
||
- **(b) 盲测(查询式 vs 全文档背诵)** ❌ 四判据未全立 ⇒ 按 three-problems.md §3.7 **继续改协议**——
|
||
deepseek-flash:docs 4/6 vs query 0/3(端点 infra 剔除 3/6);首轮语法错 2/3 vs 2/6;token 69,771 vs 57,276。
|
||
mimo-v2.6-pro 两跑均端点 infra(12/12、11/12,**不可评估**;结果回填 [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md) §3)。
|
||
**真发现**:查询机制本身无缺陷(多词查询亦正确命中卡片),败例是**跨语言习惯泄漏**(元组表达式/Python 调用形)
|
||
——模型"不知道自己不知道"而不去查。协议改进主攻方向:**自查触发机制**(validate 前置自检、
|
||
陌生构造强制查询),而非继续改进卡片。
|
||
- **(c) 契约消融** ✅ PASS——拦截率 4/4=100%、误报率 0/4=0%、无契约零回归 4/4(四边界:调用实参/返回/表绑定/键访问)。
|
||
- **(d) 防漂移演练** ✅ PASS——必报率 9/9=100%(9 类故意写错全数诊断)、负对照误报 0/2。
|
||
- **(e) 核心守卫演练** ✅ PASS——3/3 变异注入必红(清单私增/文档私增/金样删除)、还原必绿。
|
||
- **判据矩阵回填**:three-problems.md §5.1 逐行标注——问题 1 ✅、问题 2 ✅、**问题 3 ❌(未解决)**。
|
||
- **测量端记录**:LLM 网关随机空体为最大干扰(重试 5→12 次、退避 5→15 秒、截断自适应 max_tokens);
|
||
harness 修复两处协议性 bug(查询额度用满误判、提取失败不进修复回路)后采样;
|
||
模型口径按用户指示由 `cflmy`/`mimo-v2.6-flash` 改 `mimo-v2.6-pro`/`deepseek-flash`(实验 (a) 数据为原组合,不重跑)。
|
||
- **全量干净回归**(无 API key 基线)零失败。
|