- src/mlsp.rs: 行分隔 JSON 协议 + 五 handler;语法唯一事实来源 = CORE_CONSTRUCTS(只加检索别名) - repair_targets 带有界护栏策略(anchored-local / 越界必拒 abstain / max_attempts=2) - schema 契约导出(T2.6):形参/返回/字段契约 + 升参清单 + 锚点 - marqdo mlsp 子命令:stdio 行分隔 JSON 服务 - tests/mlsp.rs 7 例全绿;全量回归零失败(含 262 gold) Co-authored-by: Cursor <cursoragent@cursor.com>
181 lines
12 KiB
Markdown
181 lines
12 KiB
Markdown
# 三大问题落地计划(core 收口 · 渐进式契约 · MLSP)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **本期开发依据 · 执行中** |
|
||
| 日期 | 2026-09-22 |
|
||
| 设计 | [three-problems.md](three-problems.md)(解决方向与验证设计;判据矩阵 §5.1) |
|
||
| 范围 | **工程任务 = Phase 1–3**;验证实验(three-problems.md §5.2)**不属于开发任务**,待「性能验证设计」(`doc/next/`,用户维护)导入后对接 |
|
||
| 约定 | 每任务带机器可验证验收;**任务完成 = 验收全绿 + 全量回归绿**;只改宣言不改行为 = 未完成 |
|
||
|
||
## 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 · 验证实验(**非开发任务**)
|
||
|
||
- 对接「性能验证设计」(`doc/next/`,用户维护,待导入);three-problems.md §5.2 实验 (a)–(e) 的**材料由 Phase 1–3 的验收金样直接供给**;开发侧仅保留「实验基建适配」支持义务(复用 MarqdoThesis `formal/exp1–3` runner/oracle)。
|
||
|
||
---
|
||
|
||
## 完成定义
|
||
|
||
| 阶段 | 完成定义 |
|
||
|------|----------|
|
||
| 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.2 + T2.6;T3.3/T3.4 待做)
|
||
|
||
- **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.3(修复循环护栏 · golden 20 例 ≥80%)**:护栏策略字段已就位(anchored-local / abstain /
|
||
max_attempts=2);golden 实验需要模型调用,属验证实验性质,待做。
|
||
- **T3.4(AI Skill 换骨:背语法 → 查 MLSP)**:待做——`.cursor/skills/marqdo*` 三件套改为
|
||
「写代码前先 `mlsp syntax/locate`、提交前 `mlsp validate`」的查询式工作流。
|