Files
marqdo/doc/roadmap/three-problems-plan.md
T
cflmyandCursor 5fffb800f9 P4(b) 收口:mimo-v2.6-pro 两跑均端点 infra 不可评估,判据以 deepseek-flash 为准
- perf-validation-report §3 记录重跑终局(12/12→11/12 infra),(b) 判据判定不改
- three-problems-plan Phase 4 落地记录同步

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:10:28 +08:00

16 KiB
Raw Permalink Blame History

三大问题落地计划(core 收口 · 渐进式契约 · MLSP)

状态 本期开发依据 · 执行中
日期 2026-09-22
设计 three-problems.md(解决方向与验证设计;判据矩阵 §5.1)
范围 工程任务 = Phase 1–3;验证实验(three-problems.md §5.2)协议见 perf-validation.md(2026-09-23 用户授权自行设计并执行)
约定 每任务带机器可验证验收;任务完成 = 验收全绿 + 全量回归绿;只改宣言不改行为 = 未完成

0. 本期范围与依赖

阶段 定位 本期
Phase 1 核心收口 + 诊断地基 一切的地基 ✅ 启动
Phase 2 渐进式契约层 校验层(schema 源头 = 表格/段落) ✅ 本期主目标
Phase 3 MLSP(AI 语言服务) 下一步的超级核心(AI 不必学语法 + 可靠反馈闭环) ⏭ 下期启动,本期只留接口
Phase 4 验证实验 性能验证(非开发任务) ❌ 不认领

依赖链(跳步会倒逼「另造一套错误 / 另写一套 schema」的遮盖式捷径):

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 §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 §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)

  • 2026-09-23 用户授权自行设计性能验证设计并执行验证;doc/next/002.md 与性能验证无关(此前「待导入」表述已纠正)。
  • five 实验 (a)–(e) 的材料由 Phase 1–3 的验收金样直接供给;协议 / 指标 / 判据见 perf-validation.md §1–§5; 实验产物 = 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 §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(cflmy)、 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)

  • (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 §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 基线)零失败。