Compare commits

...
16 Commits
Author SHA1 Message Date
cflmyandCursor 5272acaea0 release: v1.1.0 —— 核心表面守卫 + 渐进式契约 + MLSP for AI
- Cargo.toml / marqdo-wasm / ext/VERSION → 1.1.0(CLI 与扩展同步)
- CHANGELOG v1.1.0(含核心表面 Δ = 无增删;诚实标注 P4(b) 盲测未达标)
- README 现状/安装/示例更新(新命令 check / --json / mlsp)
- debian/changelog 1.1.0-1ppa1;release.yml Highlights stub 更新
- 核心表面 Δ:无增删(19 构造不变;本版为 Runtime/Document 层变更)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:31:27 +08:00
cflmyandCursor cba51238b6 doc/next/002: 智能体框架「认知编译」构想(Learning → Compilation)
用户维护文档归档:每次执行沉淀 mq.md;>3 次调用自动总结优化出记忆文档;
完全学会后降能耗运行(少 LLM 思考 / Jev 决策模型 / 纯分支控制)。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:19:56 +08:00
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
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
cflmyandCursor 00c763300e test(repair): mimo-v2.6-flash cross-check + measurement-side hardening
mimo-v2.6-flash 终测:anchor 臂一轮 20/20=100%、plain 90%(最终 95%);
三轮双臂一轮修复率全部 >=85%(目标 >=80%),护栏 0 越界。

'测试不稳定'定性为三类测量端问题并全部加固(与 Marqdo 语义无关):
- 网关空体抖动 -> curl --retry + 5s 退避(加固后 0 次失败)
- 推理模型 reasoning_content 吃光 token 预算 -> max_tokens 2000->8000
- 模型输出格式畸形 -> parse_edits 容错(数组/单对象/NDJSON 多对象流/
  字符串化元素/字符串型行号/围栏/数字后多余引号的确定性修补 unquote_line_nums)

报告按模型分文件(repair-experiment-<date>-<model>.md),cflmy/mimo 双报告并存;
计划记录更新为三轮对照表。干净环境 cargo test 444/444 全绿(零回归);
ext_llm_*/ext_agent_*_live 为环境开关型实况测试,与本期无关。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 01:27:01 +08:00
cflmyandCursor 224b3d4a66 test(repair): §5.2(a) 模型在环修复实验 —— 锚点消融:anchor 100%(20/20) vs plain 85%,≥80% 目标达成
- tests/repair_experiment.rs:真实消费 validate → repair_targets → 模型行编辑 → repair_apply(越界必拒)
  → 复验 的完整闭环(≤2 轮;容错重试;cflmy @ llm.cflmy.cn,.env 读取,#[ignore] 不进常规回归)
- 双臂消融:anchor(诊断带 doc_anchor/doc_quote/suggestion)vs plain(剥掉)——
  anchor 一轮修复 20/20=100%;plain 17/20=85%(3 例失败均为网络空体抖动)
- tests/common/mod.rs:golden 20 例与诊断/应用共享件抽出(repair_loop + experiment 同源)
- parse_edits 容错(数组/单对象/字符串化元素/围栏);越界必拒/abstain 由 repair_loop 硬断言覆盖
- 报告:doc/roadmap/repair-experiment-2026-09-22.md;.gitignore 补 .env(密钥不入库)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 21:10:03 +08:00
cflmyandCursor 81d26a265a docs(roadmap): 落地记录 —— T3.4 修复回路工程项完成(护栏 + golden 20 例);T3.3 编号归位
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 20:14:32 +08:00
cflmyandCursor 5b599125d1 feat(repair): T3.3 修复护栏 + golden 20 例 —— 机械护栏(有界行编辑·越界必拒·abstain)+ mlsp repair_apply
- src/repair.rs:行编辑有界应用(replace/delete/insert;触碰行必须落在靶点范围内,
  越界 ⇒ 整体拒绝 + 越界清单,源零字节不改 = abstain;表尾追加允许 end+1)
- mlsp repair_apply:护栏的 MLSP 出口(ranges + edits → 新源;越界报 mlsp.repair_out_of_scope)
- tests/repair_loop.rs:golden 20 例(10 骨架 × 2)走完整修复循环
  (诊断 → 靶点 → 金修复行编辑自动推导 → 范围自检 = 「易锚定」机器验证 → 应用 → 复验)
  + 护栏负例(越界必拒 + 源零字节不改 + 部分越界全拒)
- 待做:模型修复实验(把金修复换成模型编辑,测 ≥80% 修复率)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 20:13:41 +08:00
cflmyandCursor 18d89d6cf2 docs(roadmap): 落地记录更新 —— T3.4 完成;T3.3 golden 实验待做
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:47:19 +08:00
cflmyandCursor 199b5c532f docs(skill): T3.4 AI Skill 换骨 —— 背语法 → 查 MLSP;渐进式契约入语法面
- marqdo/SKILL.md: 置顶「查 MLSP」查询式工作流(五方法 + 行分隔 JSON 协议 + 修复护栏);
  渐进式契约三种表格形状/位置/四边界;工作流与 checklist 增加 validate/check 环节
- marqdo-dev/SKILL.md: 契约/MLSP/三层准入/错误出口唯一的开发戒律

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:46:25 +08:00
cflmyandCursor db5f0e830b feat(mlsp): Phase 3 MLSP for AI —— locate/syntax/validate/repair_targets/schema(T3.1/T3.2 + T2.6)
- 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>
2026-09-22 19:44:35 +08:00
cflmyandCursor 7a449c40b1 feat(contract): Phase 2 渐进式契约层 —— 契约表提取 + 四边界校验 + marqdo check 防漂移(T2.1–T2.5)
- src/contract.rs: 类型词汇(渐进标注)、参数/返回/字段三形状契约表解析、合并、四边界校验诊断
- src/parse/mod.rs: extract_function_contract —— 位置+形状双重判定,在升参推断之前提取;
  绑定表/普通文档表绝不吃(P1 零回归),契约表从 body 移除(元数据永不执行)
- src/interp.rs: 四边界校验 —— 调用实参(3 条调用路径)/返回/表绑定/字段访问
- src/check.rs + marqdo check [--json]: 漂移双向互查、未知类型名(附建议)、错位契约
- src/load.rs: label_error 保留结构化诊断(错误出口唯一,不拍平成字符串)
- T2.4: 全部契约诊断带 doc_anchor/doc_quote/contract_ref
- tests/contracts.rs 12 例全绿;全量回归零失败(含 262 gold)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:40:08 +08:00
cflmyandCursor 97fda7aa10 feat(core): Phase 1 —— 核心收口 + 诊断地基(core-surface 守卫 · 三层准入 · Diagnostic JSON)
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:03:03 +08:00
cflmyandCursor a49592a3ba docs: 三大问题设计移出 doc/next/ → roadmap/three-problems.md;新增落地计划 three-problems-plan.md
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 17:46:09 +08:00
cflmyandCursor ed9ac03c0c docs: README 前置核心优势与愿景(Executable Knowledge 定位);doc/next 交流笔记入库
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 17:07:33 +08:00
cflmyandCursor cb46ad7abe fix(ppa): trim bundled Rust to build essentials; clean extract on failure
Launchpad builds only need rustc + cargo + rust-std (debian/rules PATH),
but install.sh was still shipping rust-docs-json-preview / rustfmt /
rls (~1G). Also drop the 1.5G extract dir via EXIT trap when install
fails — the leftover is what filled /tmp last run.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 16:40:39 +08:00
60 changed files with 8558 additions and 28 deletions

No files matched your search

+15
View File
@@ -150,3 +150,18 @@ When editing a file full of `json.set`:
- Tables: `doc/design/stdlib-table.md` · `doc/design/table-cell-expressions.md`
- Browser effects: `doc/roadmap/browser-wasm-e.md` · `doc/roadmap/browser-wasm-f.md`
- Release: [marqdo-release](../marqdo-release/SKILL.md)
## 渐进式契约 + MLSP(Phase 2/3 落地后的开发戒律)
- **契约实现**:`src/contract.rs`(类型词汇 / 三形状契约表解析 / 合并 / 四边界校验诊断);
`src/parse/mod.rs::extract_function_contract`(位置 + 形状双重判定,**在升参推断之前**执行;
绑定表与普通文档表绝不吃 ⇒ 无契约文件零回归)。契约表从 body 移除——元数据永不执行。
- **静态互查**:`src/check.rs`(`marqdo check [--json]`)——契约行 vs 升参推断形参双向漂移、
未知类型名、错位契约;Error ⇒ 非零退出。
- **AI 工具面**:`src/mlsp.rs`(`marqdo mlsp`,行分隔 JSON)——`locate` / `syntax` / `validate` /
`repair_targets` / `schema`。语法唯一事实来源 = `parse::CORE_CONSTRUCTS`(CI 守卫与
`doc/design/core-surface.md` 同步);MLSP 只加检索别名,**不定义语法**。
- **准入戒律**:新特性先过 `doc/design/layers.md` 三层归属(Language 层改动须 ADR + core-surface);
新契约形状/类型词汇 = 文档层扩展,进 `src/contract.rs`,不进词法/语法。
- **错误出口唯一**:`src/load.rs::label_error` 已示范——装载层/任何新代码都**不许**把
`Diagnostic` 拍平成字符串;错误链里必须能 `Diagnostic::find` 找回结构化诊断(AI/MLSP 面)。
+1 -1
View File
@@ -85,7 +85,7 @@ Checks: clean tree; `main` ff-only; smoke tests; CHANGELOG Unreleased; no secret
|------|------|-----|-----|
| `Cargo.toml` + `crates/marqdo-wasm/Cargo.toml` | bump | bump | — |
| `ext/VERSION` | bump | — | bump |
| `CHANGELOG.md` | `## vVER` | `## vVER` | `## Ext pack vVER` |
| `CHANGELOG.md` | `## vVER`(含**核心表面 Δ**,见 `doc/design/layers.md`) | same | `## Ext pack vVER` |
| `README.md` / `public/**` install + download table | update | update | update ext notes |
| `.cursor/skills/marqdo/SKILL.md` | if surface changed | same | rare |
| `.github/workflows/release.yml` Highlights stub | yes | yes | — |
+66 -5
View File
@@ -36,6 +36,62 @@ Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
12. **Bracket-marked calls:** Function name may be marked with `[函数名]`; bare words before `[` are boolean modifiers (`礼貌 [问候] x` → `礼貌=True`). `]` immediately followed by `(` is **index** `[key](coll)`, not a call. Prefer `[k](c)` over footnote index in new code. See [bracket-call-modifiers.md](../../doc/design/bracket-call-modifiers.md).
## 记不住语法细节?查 MLSP(AI 必读)
**不必背 Marqdo 语法细节**——语法可查、程序可验、修复有界。写码前后走**查询式**工作流:
```bash
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
printf '%s\n' '{"id":2,"method":"locate","params":{"path":"a.mq.md","symbol":"加一"}}' | marqdo mlsp
printf '%s\n' '{"id":3,"method":"validate","params":{"path":"a.mq.md"}}' | marqdo mlsp
printf '%s\n' '{"id":4,"method":"schema","params":{"path":"a.mq.md","unit":"加一"}}' | marqdo mlsp
printf '%s\n' '{"id":5,"method":"repair_targets","params":{"code":"contract.arg_mismatch","doc_anchor":"a.mq.md#L9-L15"}}' | marqdo mlsp
```
| method | 何时用 |
|--------|--------|
| `syntax` | 不确定某个语法怎么写(关键字/别名 → 构造卡片:「返回」「表」「调用」「循环」…) |
| `locate` | 找符号定义位置 + 契约;或反查构造卡片 |
| `validate` | 提交前校验(结构化诊断数组;`ok:false` 就修) |
| `schema` | 查单元契约(形参/返回/字段) |
| `repair_targets` | 拿错误的**有界**修复靶点:只改锚点范围内行,越界必弃权(abstain) |
行分隔 JSON:每行请求 `{"id","method","params"}` → 每行响应 `{"id","ok","result"|"error"}`。
语法唯一事实来源 = `doc/design/core-surface.md`(CI 守卫同步);卡片带 `manual` 指回文档行。
所有错误诊断都是结构化 JSON:`code` / `severity` / `span` / `suggestion` / `doc_anchor` / `doc_quote` / `contract_ref`。
### 渐进式契约(可选标注;schema 就长在文档表里)
契约是**未绑定文档表**(绑定表是数据,永远不是契约)。三种形状、严格位置:
| 形状(须含 `类型` 列) | 允许位置 | 附着 |
|--------------------------|----------|------|
| `参数`/`类型`/`说明` 表 + `返回`/`类型`/`说明` 表 | 函数体首个可执行行之前 | 函数 |
| `字段`/`类型`/`可空`/`说明` 表 | 紧邻 `` `名` = `` 绑定之前 | 集合(变量) |
| `字段`/`类型`/`可空`/`说明` 表 | 对象(`#`)体首成员之前 | 对象类型 |
````text
## 加一
对于输入变量`n`,期望是数字。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
| 返回 | 类型 | 说明 |
|------|------|------|
| | number | 加一结果 |
*n+1*
````
- 类型词汇:`text` / `number` / `bool` / `list` / `map` / `any` / `#` 对象名(拼错 ⇒ `contract.unknown_type` + 最近建议)。
- 契约表**永不执行**、不污染升参推断;无契约文件行为逐字节不变(动态默认,零摩擦)。
- 运行时只在四个边界校验:调用实参 / 字段访问 `[键](集合)` / 表绑定 / 返回。
- `marqdo check [FILE] [--json]` 静态互查:契约行 vs 升参推断形参**双向**漂移(错行=Error;新升参未覆盖=Warning)、未知类型、错位契约;有 Error 非零退出。
- 契约诊断带 `doc_anchor` + `doc_quote`(表原文)——修复只照锚点局部改。
## Markup → meaning (v0.3)
| Marker | Meaning |
@@ -244,11 +300,14 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
## AI authoring workflow
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
2. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
3. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
4. On `path:line:col: message`, fix that span; re-run until exit 0.
5. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
1. **查再写**:不确定语法就 `marqdo mlsp`(`syntax` / `locate`)——不必背语法细节。
2. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
3. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
4. 可选:给函数/集合写**渐进式契约**(上节三种表格形状;写全或不写,别写一半)。
5. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
6. On errors:结构化诊断(含 `doc_anchor` / `suggestion`)→ `repair_targets` 取有界靶点,**只改锚点范围内**的行。
7. 提交前:`marqdo check path/to/file.mq.md`(或 `mlsp validate`)清到零 Error。
8. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
## Anti-patterns (common model mistakes)
@@ -287,3 +346,5 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
- [ ] Browser client: `lib/browser` + tables when returning effects
- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view
- [ ] `marqdo run` succeeds (or errors addressed)
- [ ] 语法拿不准的地方已查 MLSP(`syntax`/`locate`),而不是凭记忆发明
- [ ] 契约(如有)与升参一致:`marqdo check` 零 Error
+15
View File
@@ -0,0 +1,15 @@
## 层归属(必填,见 doc/design/layers.md)
- [ ] Language(`src/lex` `src/parse` `src/ast` `src/interp` `src/diagnostics` / 契约)
- [ ] Runtime(`lib/` `plugins/` `crates/` catalog / view / debug / builtin)
- [ ] Document(`*.mq.md` `skills/` `ext/` `public/` `examples/`)
## 核心表面(见 doc/design/core-surface.md)
- [ ] 不涉及核心标记
- [ ] 涉及核心标记:ADR 编号 ______;core-surface.md 与 `CORE_CONSTRUCTS` 已同步(CI 守卫)
## 验收
- [ ] 相关验收(机器可验证)全绿
- [ ] 全量回归绿(`cargo test` / `go test ./...` 视触及面)
+2 -1
View File
@@ -124,8 +124,9 @@ jobs:
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **v1.1.0**:AI 原生闭环三件套——核心表面守卫(问题一)· 渐进式契约 + `marqdo check`(问题二)· **MLSP for AI**(`marqdo mlsp`:locate/syntax/validate/repair_targets/repair_apply/schema,AI 按需查语法而非背诵)(问题三)· `run --json` 结构化诊断
- **v1.1.0**: AI-native loop — core-surface guard, progressive contracts + `marqdo check`, **MLSP for AI** (`marqdo mlsp`: query syntax on demand instead of memorizing), `run --json` structured diagnostics
- **v1.0.7**:WS/网络边界加固(同源握手、require_auth/需要登录、消息上限、HTTP 8 MiB 截断);`url_encode` `%20`
- **v1.0.7**: WS/net boundary hardening (same-origin, require_auth, message caps, 8 MiB HTTP cap); `url_encode` `%20`
- **v1.0.3**:Ubuntu PPA + 扩展 CDN(ext.marqdo.com);CLI/扩展可分发;noble 捆绑 Rust 工具链
- **v1.0.3**: Ubuntu PPA + extension CDN; independent CLI/ext packs; bundled Rust for noble
- **v1.0.1**:修复 Go `libweb` 动态路由 `{param}` 查询代入、详情 Markdown、CSS 数字误报
+3
View File
@@ -84,3 +84,6 @@ plugins/*/tmp/
# ephemeral sqlite / test artifacts
tests/ext/:memory:
# local secrets
.env
+44
View File
@@ -1,5 +1,49 @@
# Changelog
## v1.1.0 — 2026-09-23
### Highlights
**AI 原生闭环三件套落地**:核心表面守卫(问题一)· 渐进式契约(问题二)· MLSP for AI(问题三)。
`marqdo check` 静态契约防漂移、`marqdo mlsp` 让 AI **按需查询**语法而非背诵、`run --json` 统一结构化诊断(错误即数据,供 AI 直接消费)。
本版 CLI 与扩展包 **同步为 1.1.0**。
- **核心要小(问题一)**:`doc/design/core-surface.md` 列出 19 个核心构造 + `CORE_CONSTRUCTS` 守卫测试——任一侧(清单/文档/金样)单边改动 CI 必红;三层架构(Core / Runtime / Document)入 `doc/design/layers.md`。
- **语义校验(问题二)**:渐进式契约表(`参数`/`返回`/`字段`/集合)嵌入文档叙述;四边界校验(调用实参 / 返回值 / 表绑定 / 键访问);`marqdo check` 静态防漂移(类型 typo / 参数名漂移 / 重复契约必报)。
- **AI 可靠反馈 + 不必学语法(问题三)**:`marqdo mlsp`(MLSP,行分隔 JSON over stdio)提供 `locate` / `syntax` / `validate` / `repair_targets` / `repair_apply` / `schema`;`syntax` 卡片机械携带戒律原文 / 样例 / 文档锚点,AI 无需预学语法。修复护栏:有界行编辑、越界必拒(abstain)。
- **验证(P4)**:锚点消融 anchor 一轮修复率 **100%**(双模型,plain 85%/90%);契约消融拦截 100% / 误报 0%;防漂移必报 9/9;核心守卫演练 3/3 必红。详见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)。
```bash
# Ubuntu PPA / 源码
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.1.0 && cargo build --release
marqdo ext add web
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造(`heading` / `bold-code` / `italic-return` / `param-list` / `call-quote` / `branch-list` / `loop-list` / `table-bind` / `footnote-index` / `link-index` / …)与 v1.0.7 完全一致,未新增标记。本版为 **Runtime 层(契约校验 / MLSP / 诊断 JSON)** 与 **Document 层(core-surface / layers)** 变更,不触碰语言核心。
### Added
- **MLSP(`marqdo mlsp`)**:面向 AI 的语言服务协议(行分隔 JSON over stdio)——`locate` / `syntax` / `validate` / `repair_targets` / `repair_apply` / `schema`;`syntax` 卡片含 `semantics` / `rule` / `sample` / `doc_quote`(自持,机器可读戒律原文)。
- **`marqdo check`**:静态契约漂移检查(未知类型词 / 参数名漂移 / 返回越约 / 重复契约表 / 错位契约表)。
- **渐进式契约(Progressive contracts)**:文档叙述内嵌契约表(`参数`/`返回`/`字段` + 集合 `字段`),四边界校验(调用实参 / 返回值 / 表绑定 / 键访问);被绑定的 `字段|类型` 表是**数据**、永不误判为契约。
- **`marqdo run --json`**:统一结构化诊断(`code` / `severity` / `suggestion` / `doc_anchor` / `doc_quote` / `contract_ref`),错误即数据。
- **修复护栏**:`mlsp repair_apply` 有界行编辑——只允许落在 `doc_anchor` 指定范围内的编辑,越界整体拒绝(all-or-nothing / abstain)。
- **守卫与文档**:`doc/design/core-surface.md`(19 构造)、`doc/design/layers.md`(三层架构)、`tests/core_surface.rs`(守卫生效验证)。
### Fixed
- **错误链不再扁平化**:`src/load.rs` 以 `label_error` 保留结构化 `Diagnostic`("Error Exit Only" 原则),修复契约类错误被降级为字符串的回归。
- **契约 parse 边界**:`interp.rs` 键访问优先给出 `index_diag`(索引/键诊断先于取值),空字段 vs 缺字段语义消歧。
### Changed
- **`.cursor/skills/marqdo`**:由「背诵式压缩操作手册」改为**查询式工作流**——写码前 `mlsp syntax` / `locate`,提交前 `mlsp validate` + `marqdo check`,修复照 `doc_anchor` 局部改。
- **契约表一经出现即为完整声明**(新推断的升参未覆盖 ⇒ `contract.param_drift` 警告,不静默)。
- 取元**主推** `[键](集合)`(`link-index`);`` `集合`[^键] ``(`footnote-index`)保留兼容。
### 已知未决(诚实标注)
- **P4 实验 (b) 盲测未达标**:「查询式 vs 全文档背诵」四判据未全立(`deepseek-flash`:docs 4/6 vs query 0/3;端点 infra 削样本)。查询机制本身已验证无缺陷,瓶颈在**模型自查纪律**(不知道自己不知道 ⇒ 不查询)——协议改进(写码前强制自检 / 陌生构造强制查询)列入下一阶段。见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md) §3。
## Unreleased
## v1.0.7 — 2026-09-22
### Highlights
Generated
+2 -2
View File
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "1.0.7"
version = "1.1.0"
dependencies = [
"anyhow",
"assert_cmd",
@@ -603,7 +603,7 @@ dependencies = [
[[package]]
name = "marqdo-wasm"
version = "1.0.7"
version = "1.1.0"
dependencies = [
"marqdo",
"serde_json",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "1.0.7"
version = "1.1.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
+58 -8
View File
@@ -1,8 +1,8 @@
# Marqdo
**代码即文档。文档即代码。文档即知识库。**
**代码即文档。文档即知识库。知识即可执行。**
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
@@ -10,6 +10,47 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
---
## 核心优势:可执行知识(Executable Knowledge)
> **Knowledge That Can Run —— 知识即可执行。**
> Marqdo 不是「用 Markdown 写程序」这么简单:它让一个 `.mq.md` 文档**同时**是文稿、知识与程序——同一份结构,同时服务于人、解释器、工具与 AI。
```text
.mq.md(同一份文件)
┌─────────┼─────────┐
文稿 知识 程序
└─────────┼─────────┘
▼
Marqdo 运行时
▼
可执行知识(Executable Knowledge)
```
| 真正的核心优势 | 说明 |
|------|------|
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
| **默认安全,AI 友好** | 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥**不会污染**文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。 |
| **multi-view artifact**<br>`.mq.md` 双后缀即开放接口 | `.mq` 告诉解释器「可执行」,`.md` 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。**Marqdo 不占有知识,只是给 Markdown 增加执行语义。** |
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元 `[键](集合)` 也是 Markdown 链接形。这是 literate programming 的下一步。 |
| **语义干净** | **返回是架构,打印只是函数**:`*…*` 改变控制流,`print` 只是副作用函数;分支与循环长在 Markdown 结构上(`1.` `2.` 递增 = 分支,`-` = 循环),不是所有列表都被粗暴当成 if。 |
| **AI 的可靠上下文与长期记忆** | 一个 `.mq.md` 同时是 documentation + schema + code + examples + knowledge + executable behavior;AI 不必再拼装 README + OpenAPI + JSON Schema + prompt。整个工程天然就是 AI 的**世界模型**——比 RAG 更接近 Executable RAG。 |
| **完整工程,不是玩具** | Rust 正经解释器(词法 / 语法 / 语义 / 树遍历 + 字节码后端)、stdlib、模块与对象、debugger、viewer、catalog、WASM、原生插件 ABI、VS Code 扩展、agent / LLM / MCP。 |
---
## 愿景与期许
不把「AI 能写 Marqdo」当终点,而是 **「AI 能可靠地生成可验证的 Marqdo」**:
1. **AI 可验证语言**:`LLM → Marqdo AST → 语义检查 → 结构化诊断 → LLM 修复 → 合格程序`。让类型与语义检查成为 AI 编程闭环里的强约束,堵住「语义看似合理、类型实则不对」的生成。
2. **Marqdo Schema / Language Server for AI**:机器可读的语言 Schema(`get_syntax` / `validate` / `repair` …),AI 不必读千行文档猜语法,而是 discover → construct → validate → execute → inspect。
3. **程序即 AI 长期记忆**:`.mq.md` 工程 = 可执行知识库 = AI 的世界模型(Executable Knowledge Representation)。
4. **可执行知识图**:`.mq.md` 之间的 Markdown 链接天然长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
5. **知识可测试**:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
---
## 为什么重要
| 痛点 | Marqdo 的答案 |
@@ -38,7 +79,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
| 表格 | 集合;取元优先 `[键](集合)` |
| 表格 | 集合(几何即类型,见下);取元优先 `[键](集合)` |
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
```markdown
@@ -58,6 +99,8 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
对于输入变量`n`,执行**n=n+1**接着返回*n*。
```
**表格几何即类型**:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。详见 [tables-maps-footnotes.md](doc/roadmap/tables-maps-footnotes.md)。
完整约定:[markdown-mapping-v0.3.md](doc/design/markdown-mapping-v0.3.md)。
---
@@ -68,7 +111,8 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
2. **返回是架构;打印只是函数。**
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
6. **语言核心保持小**:Language(标记映射 / AST / 语义 / 类型)、Runtime(stdlib / 插件 ABI / WASM / agent)、Document(知识 + 代码 + UI + AI)三层分明——生态功能不淹没语言身份。
---
@@ -98,8 +142,9 @@ marqdo catalog public -o .marqdo
---
## 现状(v1.0.7)
## 现状(v1.1.0)
- **AI 原生闭环(v1.1.0 新增)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
@@ -120,7 +165,7 @@ marqdo catalog public -o .marqdo
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
### 如何使用最新 Marqdo(v1.0.7)
### 如何使用最新 Marqdo(v1.1.0)
**安装解释器(任选其一)**
@@ -135,7 +180,7 @@ marqdo catalog public -o .marqdo
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v1.0.7 # 或留在 main
git checkout v1.1.0 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -148,6 +193,11 @@ marqdo view public --no-open
marqdo debug public --no-open
marqdo catalog public -o .marqdo
# 2b) AI 原生闭环(v1.1.0):契约检查 / 结构化诊断 / MLSP 查询
marqdo check tests/contracts/ok_contract.mq.md # 静态契约防漂移
marqdo run tests/structure/hello.mq.md --json # 结构化诊断(错误即数据)
printf '{"id":1,"method":"syntax","params":{"query":"返回"}}\n' | marqdo mlsp
# 3) 安装官方扩展(Release / CDN 用户:无需本机 Rust/Go)
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(Go libweb)
marqdo ext add agent # 或:智能体
@@ -169,7 +219,7 @@ marqdo wasm build
# → dist/wasm/ … 见 examples/browser-hello/
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
# https://github.com/cflmy/marqdo/releases/tag/v1.0.7
# https://github.com/cflmy/marqdo/releases/tag/v1.1.0
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "1.0.7"
version = "1.1.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
+11
View File
@@ -1,3 +1,14 @@
marqdo (1.1.0-1ppa1) noble; urgency=medium
* Marqdo 1.1.0: core surface guard + progressive contracts + MLSP for AI.
New `marqdo check` (static contract drift) and `marqdo mlsp` (language
server for AI: locate/syntax/validate/repair_targets/schema/repair_apply);
`run --json` unified structured diagnostics; contract tables
(参数/返回/字段/集合) with four validation boundaries; anchored repair
guardrails (bounded line edits, out-of-scope refused).
-- cflmy <pingan@cflmy.cn> Wed, 23 Sep 2026 13:30:00 +0800
marqdo (1.0.7-1ppa1) noble; urgency=medium
* Marqdo 1.0.7: WS/net boundary hardening (same-origin handshake,
+47
View File
@@ -0,0 +1,47 @@
# 核心表面清单(core-surface)
| | |
|---|---|
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
| 日期 | 2026-09-22 |
| 守卫 | `tests/core_surface.rs` ⇄ `src/parse/mod.rs` `CORE_CONSTRUCTS`(改动任一侧不同步 → CI 红) |
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)(语义宪法)· [layers.md](layers.md)(准入戒律)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.1/T1.3 |
> **戒律总纲**:核心标记是**封闭集合**(约 19 个构造)。新增任何一行必须走 ADR(见 [layers.md](layers.md) 准入戒律)并回答「为什么现有标记不够」;生态需求的默认答案是**进 ext**。本表 id 列与守卫测试强一致:改表不同步 `CORE_CONSTRUCTS`(或反之)、样例文件缺失,一律 CI 红。
## 1. 行构造
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `narrative` | 无标记文字 | 叙述(注释) | 段落内延续到空行;**默认安全**——永远不存在「叙述被执行」的路径 | `tests/markup-v03/soft-emphasis.mq.md` |
| `blank` | 空行 | 段落边界 | 叙述分段的唯一手段;不得被赋予其它语义 | `tests/markup-v03/inc-prose.mq.md` |
| `heading-unit` | `#` / `##` | 对象 / 函数单元 | 标题即单元边界,按深度嵌套;正文禁止用 `##` 做版式(会变成函数) | `tests/markup-v03/decl-ident-only.mq.md` |
| `call-line` | `>` | 调用行 | 输出等副作用 = **普通函数**,不是架构标记 | `tests/markup-v03/dual-call.mq.md` |
| `branch-list` | 体内 `1.` 递增 | 分支 | 自 `1.` 起序号递增构成一个判断;重出 `1.` 开新判断;`N. *` = else;**不是所有有序列表都是 if** | `tests/markup-v03/greet-default.mq.md` |
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [项](集合)` | `tests/structure/loop.mq.md` |
| `param` | `` + `名` `` | 形参(兼容形) | 首选叙述 `` `名` `` 升参(宪法 §8);`+` 形仅兼容保留 | `tests/markup-v03/greet-default.mq.md` |
| `table` | GFM 表 | 集合 | 几何即类型([tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md));**绑定 = 数据,未绑定 = 文档表** | `tests/structure/collection.mq.md` |
| `fence` | ` ```lang ` | 外联 | 语言块原样外联,不进 Marqdo 语义 | `tests/lib/foreign-python.mq.md` |
| `hr` | 单行 `---` 或 `***` | 叙述分隔 | **不收束函数**(返回才收束) | `tests/markup-v03/module-hr.mq.md` |
| `writeback` | `<!-- marqdo-out … -->` | 持久化输出 | 只读回放,不执行 | `tests/lib/writeback-get.mq.md` |
## 2. 内联标记
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.mq.md` |
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 只有粗体进入执行;判别序:赋值 → 调用 → 表达式 | `tests/markup-v03/multi-bold.mq.md` |
| `italic-return` | `*…*` | 返回 | 改变控制流(**返回是架构**);返回即结束函数体 | `tests/markup-v03/inc-prose.mq.md` |
| `empty-return` | `*None*` / `****` | 空返回 | 返回 `None` 并结束函数体 | `tests/markup-v03/empty-return-none.mq.md` |
| `link-index` | `[键](集合)` | 取元 / foreach | **主取元语法**;与 bracket-call 靠 `]` 后是否紧邻 `(` 消歧 | `tests/lib/table-collections.mq.md` |
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;与 link-index 消歧同上 | `tests/structure/bracket-call.mq.md` |
| `footnote-index` | `集合[^键]` | 过渡取元 | **仅兼容**;新代码一律写 link-index | `tests/structure/footnote-index.mq.md` |
| `soft-emphasis` | `*仅*` / `**说明**` | 忽略 | 非代码形强调**不执行**——默认安全的关键消歧规则 | `tests/markup-v03/soft-emphasis.mq.md` |
## 3. 词法大类(LineKind,`src/lex/mod.rs`)
行级入口只有四个大类:`Blank` / `Comment`(叙述段落,含软强调与行内 `` `名` ``)/ `Writeback` / `Code`(`# * > + - | ~ $` 或数字开头)。本清单第 1 节的行构造是在 `Code`(及 `Comment`/`Writeback`)内部的**语义细分**;第 2 节内联标记由 `src/parse/prose.rs` 行内扫描产出。两层合起来 = 核心表面全集。
## 4. 范围外(进 Language 层,但不在本守卫)
frontmatter YAML(元信息)与 `import` 行(模块装载)属于 Language 层的其它语言面,随 [layers.md](layers.md) 准入流程登记,暂不进本清单守卫;如需一并守卫,走 ADR 扩表。
+29
View File
@@ -0,0 +1,29 @@
# 三层归属与准入戒律(layers)
| | |
|---|---|
| 状态 | **Accepted · 准入制度(问题一落地)** |
| 日期 | 2026-09-22 |
| 相关 | [core-surface.md](core-surface.md)(核心表面守卫)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.2 |
> **目的**:语言核心保持小——**Language / Runtime / Document 三层分明,生态功能不淹没语言身份**。本制度是机制不是宣言:违反即 CI 红 / PR 不评审。
## 1. 三层归属表
| 层 | 内容 | 仓库位置 |
|----|------|----------|
| **Language** | 标记映射、词法/行分类、AST、语义、升参、契约检查器、诊断 | `src/lex/` `src/parse/` `src/ast.rs` `src/interp.rs` `src/diagnostics.rs`(及 `contract`/`check`)· 宪法 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [core-surface.md](core-surface.md) |
| **Runtime** | stdlib、插件 ABI、WASM、debugger、view、catalog / schema / mcp CLI、字节码后端 | `lib/` `plugins/` `crates/` `src/catalog.rs` `src/view/` `src/debug/` `src/builtin.rs` `src/bytecode/` |
| **Document** | 知识单元、AI skills、示例、官方扩展、用户站 | `*.mq.md` `skills/` `ext/` `public/` `examples/` `doc/` |
## 2. 准入戒律
1. **先填层归属**:任何新特性提案(issue / PR / 设计文档)必须先声明进哪层;未填 = 不评审。
2. **Language 层变更 = ADR**:新增核心标记必须有 `doc/adr/` 编号 + 「为什么现有标记不够」+ [core-surface.md](core-surface.md) 增行 + 样例 + `CORE_CONSTRUCTS` 同步(缺任一 → CI 守卫红)。
3. **核心计数只许持平或下降**:每个 release 的核心标记计数不得增长;确需增长即触发 Language 层复盘(ADR 里写明不可替代理由)。
4. **默认进 ext**:能用扩展、stdlib、插件解决的,一律不进核心。
5. **CHANGELOG 单列「核心表面 Δ」**:每个 release 写明增删(无 Δ 写「无」);发版 checklist(`.cursor/skills/marqdo-release/SKILL.md`)含此步。
## 3. PR 模板
`.github/PULL_REQUEST_TEMPLATE.md` 含「层归属」必填项与「核心表面」勾选——与本制度一一对应。
+1373
View File
File diff suppressed because it is too large. Load diff
+933
View File
@@ -0,0 +1,933 @@
这是marqdo的智能体框架,我一直都不满意,我认为marqdo的智能体框架应该更好才对,因为marqdo本身就是一门极好的AI原生语言,针对这个智能体框架,我的构想是,每次执行,智能体都会沉淀mq.md文档,超过三次的调用就会自动总结优化出一份类似与记忆的mq.md文档,把每一步都拆解的非常好,类似与人类的某些学习过程,当完全学习到了一些内容,实际上后续就可以不再每次都聚精会神,而是用一种较低能耗运行,就像是我们沉淀下来的mq.md代码,其中可以使用非常少的大模型思考,或者使用类似Jev的决策模型,或者干脆只使用分支控制,之后调用即可,你觉得呢?
对,而且我现在觉得你这个构想**很可能比目前的 Agent 框架本身更接近 Marqdo 真正应该成为的东西**。
我仔细看了你上传的 `ext/ai/agent`。其实你已经无意中铺好了不少基础:现在的 `plan` 已经有 `reuse`、`near_match`、`soft_match`、`promote`、`improve_every=3` 和 `kb_dir=.marqdo/agent-kb`;命中已有 skill 后甚至可以走 `llm_free` 路径。 而且现有逻辑已经会把成功的 workbook promote 到 agent KB。
**所以我觉得你现在缺的不是“memory”,而是一个更深的概念:Learning → Compilation。**
---
# 1. 我会把你想做的东西定义成:Agent 的“认知编译”
你描述的人类学习过程非常准确:
```text
第一次:
仔细思考
↓
尝试
↓
犯错
↓
修正
第二次:
仍然需要思考
↓
但已经有经验
第三次:
开始形成套路
多次之后:
“我知道怎么做了”
↓
不再重新思考
↓
直接执行
```
传统 Agent:
```text
User
↓
LLM
↓
Tool
↓
LLM
↓
Tool
↓
LLM
```
每次任务都重新付出推理成本。
你想让 Marqdo 变成:
```text
新任务
│
▼
是否已经学会?
/ \
是 否
│ │
▼ ▼
已编译 mq.md LLM 推理
│ │
▼ ▼
低成本执行 执行 + 观察
│
▼
沉淀 mq.md
│
▼
验证 / 优化
│
▼
编译成 Skill
```
我认为这个想法**非常漂亮**。
---
# 2. 而且这和 Marqdo 的语言设计天然吻合
这可能是你整个项目最重要的一次“闭环”。
你前面定义:
> `.mq.md` = Markdown + 可执行程序 + 知识。
现在 Agent 又产生:
> `.mq.md` = Agent 学会的经验。
于是:
```text
Agent
│
│ 学习
▼
.mq.md
│
┌───────┼────────┐
↓ ↓ ↓
知识 策略 程序
│ │ │
└───────┼────────┘
▼
Agent Skill
│
▼
低成本执行
```
这就非常有意思了。
**Agent 的 memory 不再是一段向量 embedding,也不只是聊天历史。**
它是:
> **可阅读、可修改、可验证、可执行的知识程序。**
这才是真正的 **Marqdo-native Agent**。
---
# 3. 你现在的 Agent 已经有这个雏形,但还没有真正“学习”
从你现在的代码看,已经存在:
```text
reuse
near_match
soft_match
promote
improve_every = 3
llm_free
```
这些机制实际上已经在做:
> **经验复用。**
例如当前逻辑会查找已有 KB,如果命中 `llm_free` skill,就可以直接运行 resource,而不是再让父 Agent 做一轮 LLM 推理。
这是很好的基础。
但我认为:
> **Reuse ≠ Learning。**
现在更像:
```text
成功任务
↓
保存
↓
以后查找
↓
复用
```
而你现在构想的是:
```text
成功任务
↓
观察多次执行
↓
抽象共同结构
↓
去掉偶然信息
↓
形成一般策略
↓
验证
↓
编译
↓
以后低成本执行
```
这两者差距非常大。
---
# 4. 我甚至建议你不要叫它 Memory
我会给它一个更有 Marqdo 味道的名字:
## **Skill Compilation**
或者:
## **Experience Compilation**
甚至:
## **Cognitive Compilation**
整个过程:
```text
Experience
↓
Episodic Trace
↓
Pattern Extraction
↓
Generalization
↓
Marqdo Skill
↓
Validation
↓
Compiled Skill
```
然后 Agent 不再只是:
> “记住我以前做过什么。”
而是:
> **“把以前的思考编译成以后不需要思考的程序。”**
我觉得这是一个非常强的概念。
---
# 5. 例如真的可以这样工作
第一次:
用户:
> 把这个 CSV 中年龄大于 18 的用户筛出来,并按照年龄排序。
Agent:
```text
LLM reasoning
↓
读取 CSV
↓
分析结构
↓
过滤
↓
排序
↓
输出
```
产生:
```text
.marqdo/agent-runs/xxx.mq.md
```
第二次用户:
> 把另一个 CSV 中年龄大于 18 的用户筛出来,并按照年龄排序。
Agent 发现:
```text
intent similarity = 0.94
```
于是:
```text
REUSE
```
直接调用之前的程序。
---
第三、第四、第五次:
Agent 发现:
```text
same structure
different file
different column names
```
这时候不应该继续保存五个:
```text
task1.mq.md
task2.mq.md
task3.mq.md
task4.mq.md
task5.mq.md
```
而应该让 LLM 总结:
```markdown
# Filter and Sort CSV Users
## Preconditions
- Input contains user records.
- An age field exists.
## Procedure
1. Read the input table.
2. Keep rows where `age > 18`.
3. Sort by `age` ascending.
## Variables
- `input`
- `age_field`
- `output`
## Exceptions
- Missing age field
- Invalid age
## Examples
| Input | Output |
|---|---|
| ... | ... |
```
然后:
```text
skill_status = compiled
```
---
# 6. 更关键的是:这个 mq.md 可以逐渐“去 LLM 化”
这是你刚才说的:
> “其中可以使用非常少的大模型思考,或者使用类似 Jev 的决策模型,或者干脆只使用分支控制。”
**我非常赞同。**
我甚至认为这应该成为 Marqdo Agent 的核心架构。
可以设计成一个:
# Cognitive Cost Ladder
```text
Level 0
Deterministic Marqdo
│
▼
Level 1
Rule / Branch
│
▼
Level 2
Small decision model
│
▼
Level 3
Small LLM
│
▼
Level 4
Full LLM reasoning
│
▼
Level 5
Multi-agent exploration
```
新问题:
```text
Full LLM
↓
learn
↓
Marqdo Skill
↓
validation
↓
Level 2/1
```
于是 Agent 会越来越“便宜”。
---
# 7. 这甚至给你提供了一个极漂亮的学习曲线
假设一个任务第一次需要:
```text
8 次 LLM calls
```
第二次:
```text
5 次
```
第三次:
```text
3 次
```
学习完成:
```text
0 次
```
或者:
```text
1 次 small model
```
这时候你就有一个非常漂亮的指标:
## Reasoning Amortization
定义:
$$
C_n =
\frac{
\text{LLM inference cost over first } n \text{ executions}
}{n}
$$
随着执行次数增加:
```text
Cost
│\
│ \
│ \
│ \
│ \____
│ ─────────
└───────────────────
executions
```
**这甚至解决了你之前担心的 Marqdo 性能难以证明的问题。**
你之前不知道怎么证明:
> Marqdo 比 Python 更适合 AI。
但现在你可以研究:
> **Marqdo Agent 能否把高成本 LLM reasoning 逐渐编译成低成本 executable knowledge?**
这个是一个非常明确、可测量、而且很有研究价值的问题。
---
# 8. 但是这里有一个非常重要的危险
你说:
> “超过三次调用就自动总结。”
我建议:
**不要真的这么简单。**
三次可以作为:
> **触发学习候选**
但不能作为:
> **自动认为已经学会。**
否则会发生:
```text
第一次:特殊情况
第二次:特殊情况
第三次:特殊情况
```
LLM 总结:
```text
General rule:
...
```
然后把偶然性错误“编译”进 Skill。
这会非常危险。
---
# 9. 我建议建立“经验 → 技能”的四阶段
## Stage 1 — Episode
每次任务产生:
```text
task
context
actions
tool calls
observations
errors
result
cost
```
例如:
```text
episode-001.mq.md
episode-002.mq.md
episode-003.mq.md
```
---
## Stage 2 — Candidate Skill
达到阈值之后:
```text
3+ similar episodes
```
让 LLM 总结:
```text
candidate.mq.md
```
但它还是:
> **candidate**
而不是正式 skill。
---
## Stage 3 — Verification
用历史任务重新运行:
```text
episode 1
episode 2
episode 3
```
测试:
```text
candidate skill
```
如果:
```text
3 / 3 success
```
再加新的 held-out task:
```text
episode 4
```
如果:
```text
4 / 4
```
才提高 confidence。
---
## Stage 4 — Compilation
最后:
```text
candidate
↓
verified
↓
compiled
```
此时才允许:
```text
llm_free = true
```
你目前的系统已经有 `llm_free` 命中后直接运行 resource 的机制。
我认为未来这个 flag **不应该是人工/静态指定的属性,而应该成为学习系统的产物。**
---
# 10. 甚至可以让 mq.md 自己记录“学习程度”
比如:
```yaml
---
type: skill
status: compiled
confidence: 0.97
evidence: 17
success_rate: 0.941
llm_free: true
created_from: 6c8...
last_validated: 2026-09-23
avg_reasoning_cost: 0.2
---
```
然后正文:
```markdown
# CSV 成人用户筛选
## Intent
筛选年龄大于 18 岁的用户。
## Procedure
- 读取 CSV
- 判断 age
- 过滤
- 排序
## Fallback
如果无法确定 age 字段:
> ask_llm
## Verification
| Case | Result |
|---|---|
| case-001 | ✓ |
| case-002 | ✓ |
| case-003 | ✓ |
| case-004 | ✓ |
```
注意这个设计里非常重要的一点:
> **Skill 本身可以包含一个 fallback 到 LLM 的路径。**
所以不是:
```text
学会 / 不会
```
而是:
```text
确定部分 → deterministic
不确定部分 → small model
真正未知 → full LLM
```
这就非常接近人类的实际认知过程。
---
# 11. 我甚至会把 Agent 的运行模型改成这样
```text
User Task
│
▼
┌─────────────────┐
│ Skill Resolver │
└────────┬────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
Exact Near Unknown
Hit Hit
│ │ │
▼ ▼ ▼
mq.md execute small model Full LLM
│ │ │
└────────────┼────────────┘
▼
Result
│
▼
Episode
│
▼
Experience Store
│
┌────────┴────────┐
│ │
repeated? novel?
│
▼
Skill synthesis
│
▼
Verification
│
▼
Compilation
│
▼
mq.md Skill
```
**这就已经不是普通 Agent framework 了。**
它是一个:
> **Self-compiling Agent**
---
# 12. 而 Marqdo 在这里有一个其他 Agent framework 很难天然拥有的优势
因为“学习结果”不是:
```json
{
"memory": "..."
}
```
也不是:
```text
embedding vector
```
而是:
```text
learned_skill.mq.md
```
这意味着用户可以:
```text
打开
阅读
修改
运行
测试
分享
Git commit
diff
fork
```
甚至:
```text
Agent A
↓
learned_skill.mq.md
↓
Agent B
```
**Agent 的经验第一次成为一种真正可移植的软件 artifact。**
我认为这是你整个 Marqdo 项目里非常值得深入挖掘的东西。
---
# 13. 而且它和你前面说的“Executable Knowledge”完全闭环
你之前提出:
```text
Executable Document
↓
Executable Knowledge Base
```
现在再往前一步:
```text
Executable Knowledge
↓
Agent Experience
↓
Agent Learning
↓
Compiled Knowledge
↓
Executable Skill
```
于是整个 Marqdo 可以形成:
```text
┌───────────────┐
│ Human │
└───────┬───────┘
│
▼
Natural Task
│
▼
AI Reasoning
│
▼
Executable Work
│
▼
.mq.md
│
┌───────┴───────┐
▼ ▼
Knowledge Skill
│ │
└───────┬───────┘
▼
Future Agent
│
▼
Less Reasoning
│
▼
More Execution
```
这就是我现在最喜欢 Marqdo 的地方:
> **Agent 不只是使用知识库;Agent 会把自己的经验沉淀成知识库,然后知识库反过来改变 Agent 的计算方式。**
这是一个真正的闭环。
---
## 最后,我会建议你对现有 Agent 做一个非常明确的架构升级
你现在已经有:
```text
reuse
near_match
soft_match
promote
improve_every=3
llm_free
```
所以**完全没必要推倒重来**。
我会把它演化成:
```text
Current Agent
│
┌────────┴────────┐
│ │
Execution Experience
│ │
│ ▼
│ Episode Store
│ │
│ ≥ N similar
│ │
│ ▼
│ Skill Synthesis
│ │
│ ▼
│ Skill Validation
│ │
│ ▼
│ Skill Compilation
│ │
└─────────────┬───┘
▼
.mq.md Skill
│
┌────────┼────────┐
▼ ▼ ▼
Branch Small LLM Full LLM
```
而且你当前已经有一个非常好的“终点”:**当 child 返回 value 时,可以 deterministic 地 solidify,而不是再次让父 LLM 发明 patch。** 当前代码已经明确这么处理。
所以我会把你的下一版 Agent 的核心 slogan 直接定成:
> **Think → Execute → Learn → Compile → Reuse**
或者更 Marqdo 一点:
> **Every successful thought can become executable knowledge.**
这比“Marqdo 有一个 Agent framework”强得多。
而且这件事**非常适合做你前面说的论文实验**:你甚至可以测一个 Agent 在重复任务上的 **LLM calls / tokens / latency / success rate 随经验次数变化的曲线**,直接验证“推理成本被 mq.md 技能逐渐摊销”的假设。这样 Marqdo 的 Agent、Executable Knowledge 和你之前苦恼的“性能怎么证明”三个问题,反而被同一个实验串起来了。
@@ -0,0 +1,34 @@
# 盲测实验(§5.2(b) 查询式 vs 全文档背诵)—— 2026-09-23
| | |
|---|---|
| 模型 | `deepseek-flash` @ `https://llm.cflmy.cn/v1` |
| 样本 | 6 任务(业务 3 + QuixBugs 改写 3),oracle = stdout 精确匹配 |
| 协议 | 系统提示词 = 硬规则 12 条 + 契约表三形状(两臂同文);**唯一变量 = 语法来源**:`query` 臂 MLSP 查询通道(≤3 次)vs `docs` 臂完整 markup 参考(背诵) |
| 修复 | validate 诊断 + stderr 回喂,≤2 次修复;temperature=0,max_tokens=8000 |
## 汇总(判据:Q 通过率不劣于 D;首轮语法错误率 Q≤D;token Q≤70%%D;轮次不升)
| 臂 | 通过(一轮) | 通过(最终≤3) | 首轮语法错误 | 首轮契约诊断 | 平均修复轮(过例) | token 合计(prompt+completion) | 弃权/基础设施 |
|---|---|---|---|---|---|---|---|
| query | 0/3 | 0/3 | 2/3 | 1/3 | 0.00 | 69771(42478+27293) | 3 |
| docs | 3/6 | 4/6 | 2/6 | 0/6 | 0.50 | 57276(33346+23930) | 0 |
## 逐例
| 例 | 臂 | 结果 | 修复轮 | 首轮语法错 | 首轮契约诊断 | token(p+c) | 查询 | 备注 |
|---|---|---|---|---|---|---|---|---|
| claims_reserve_settle | query | load-fail | 0 | 是 | 否 | 11987+8177 | 3 | {"error":{"code":"mlsp.parse_error","message":"<memory>: trailing input in expression: \"(claim - deductible, 0)\""},"id":1,"ok":false} \| stderr=error: /tmp/marqdo_blind_1694593_query_claims_reserve_settle.mq.md: trailing input in expression: "(claim - deductible, 0)" |
| contract_milestone_pay | query | infra | 0 | 否 | 否 | 3970+4718 | 3 | 非 JSON / 空体: |
| vendor_po_gate | query | load-fail | 0 | 是 | 否 | 9552+3686 | 3 | 回复中无程序 \| 开头: QUERY: 条件分支 写法 |
| qb_gcd | query | run-fail | 0 | 否 | 是 | 9700+8488 | 3 | \| stderr=error: /tmp/marqdo_blind_1694593_query_qb_gcd.mq.md:26:1: unknown function `gcd(48` |
| qb_max_sublist_sum | query | infra | 0 | 否 | 否 | 1253+134 | 3 | 非 JSON / 空体: |
| qb_get_factors | query | infra | 0 | 否 | 否 | 6016+2090 | 3 | 非 JSON / 空体: |
| claims_reserve_settle | docs | pass | 0 | 否 | 否 | 2699+2987 | 0 | queries=0 |
| contract_milestone_pay | docs | pass | 0 | 否 | 否 | 2800+3202 | 0 | queries=0 |
| vendor_po_gate | docs | pass | 0 | 否 | 否 | 2690+1264 | 0 | queries=0 |
| qb_gcd | docs | pass | 2 | 否 | 否 | 8147+6970 | 0 | queries=0 |
| qb_max_sublist_sum | docs | run-fail | 0 | 是 | 否 | 8518+3609 | 0 | \| stderr=error: /tmp/marqdo_blind_1694593_docs_qb_max_sublist_sum.mq.md:3:1: unknown function `[-2,` |
| qb_get_factors | docs | run-fail | 0 | 是 | 否 | 8492+5898 | 0 | \| stderr=error: /tmp/marqdo_blind_1694593_docs_qb_get_factors.mq.md:20:1: missing argument for parameter `value` |
报告由 `tests/blind_experiment.rs` 生成;材料冻结于 `tests/blind/`(任务书 + docs-bundle),判据见 `doc/roadmap/perf-validation.md` §2。
@@ -0,0 +1,34 @@
# 盲测实验(§5.2(b) 查询式 vs 全文档背诵)—— 2026-09-23
| | |
|---|---|
| 模型 | `mimo-v2.6-pro` @ `https://llm.cflmy.cn/v1` |
| 样本 | 6 任务(业务 3 + QuixBugs 改写 3),oracle = stdout 精确匹配 |
| 协议 | 系统提示词 = 硬规则 12 条 + 契约表三形状(两臂同文);**唯一变量 = 语法来源**:`query` 臂 MLSP 查询通道(≤3 次)vs `docs` 臂完整 markup 参考(背诵) |
| 修复 | validate 诊断 + stderr 回喂,≤2 次修复;temperature=0,max_tokens=8000 |
## 汇总(判据:Q 通过率不劣于 D;首轮语法错误率 Q≤D;token Q≤70%%D;轮次不升)
| 臂 | 通过(一轮) | 通过(最终≤3) | 首轮语法错误 | 首轮契约诊断 | 平均修复轮(过例) | token 合计(prompt+completion) | 弃权/基础设施 |
|---|---|---|---|---|---|---|---|
| query | 0/1 | 0/1 | 1/1 | 0/1 | 0.00 | 12428(10255+2173) | 5 |
| docs | 0/0 | 0/0 | 0/0 | 0/0 | 0.00 | 0(0+0) | 6 |
## 逐例
| 例 | 臂 | 结果 | 修复轮 | 首轮语法错 | 首轮契约诊断 | token(p+c) | 查询 | 备注 |
|---|---|---|---|---|---|---|---|---|
| claims_reserve_settle | query | infra | 0 | 否 | 否 | 1424+324 | 3 | 非 JSON / 空体: |
| contract_milestone_pay | query | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| vendor_po_gate | query | infra | 0 | 否 | 否 | 1417+213 | 3 | 非 JSON / 空体: |
| qb_gcd | query | load-fail | 0 | 是 | 否 | 5011+1265 | 0 | {"error":{"code":"mlsp.parse_error","message":"<memory>: unexpected expression input: \"**y**\""},"id":1,"ok":false} \| stderr=error: /tmp/marqdo_blind_1710203_query_qb_gcd.mq.md: unexpected expression input: "**y**" |
| qb_max_sublist_sum | query | infra | 0 | 否 | 否 | 1216+172 | 3 | 非 JSON / 空体: |
| qb_get_factors | query | infra | 0 | 否 | 否 | 1187+199 | 3 | 非 JSON / 空体: |
| claims_reserve_settle | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| contract_milestone_pay | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| vendor_po_gate | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| qb_gcd | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| qb_max_sublist_sum | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| qb_get_factors | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: {"error":{"message":"upstream connection failed","type":"server_error","param":n… |
报告由 `tests/blind_experiment.rs` 生成;材料冻结于 `tests/blind/`(任务书 + docs-bundle),判据见 `doc/roadmap/perf-validation.md` §2。
@@ -0,0 +1,118 @@
# P4 验证汇总报告 — 2026-09-23
> 执行 [perf-validation.md](perf-validation.md)(自设计性能验证协议)的结果汇总。
> 覆盖 three-problems.md 三大问题的**验证矩阵**(§5.2 a–e)。逐例明细见各实验原始报告(文末索引)。
| | |
|---|---|
| 协议 | [perf-validation.md](perf-validation.md)(实验 (a)–(e)) |
| 判据源 | [three-problems.md](three-problems.md) §3.7 / 各问题 §2.4 |
| 构建 | marqdo v1.0.7(本仓库工作树;金 20 + 全量回归通过后采样) |
| 端点 | `llm.cflmy.cn/v1`(OpenAI 兼容;temperature=0) |
| 模型 | 修复实验:`cflmy`、`mimo-v2.6-flash`;盲测:`deepseek-flash`、`mimo-v2.6-pro`(按用户指定) |
| 回归 | 全量干净回归(无 API key 基线)**零失败** |
## 1. 五实验结果与判据对照
| 实验 | 判据 | 结果 | 判定 |
|---|---|---|---|
| **(a) 锚点消融**(T3.3,双模型×20例×双臂,三轮) | anchor 臂一轮修复率 ≥ 80%;护栏 0 次越界应用 | cflmy anchor **20/20=100%**(plain 17/20=85%);mimo-v2.6-flash anchor **20/20=100%**(plain 18/20=90%;容错加固中的第二轮 anchor 18/20=90% 亦 ≥80%);越界拒/越界应用 0/0 | ✅ 过 |
| **(b) 盲测**(查询式 vs 全文档背诵,6任务×2臂) | 四判据:最终通过率 Q 不劣于 D(允许 −0 例);首轮语法错误率 Q ≤ D;平均修复轮次 Q ≤ D;token ≤ 70% of D(首轮契约诊断率为观测项) | deepseek-flash:docs 4/6 vs query 0/3(3 例端点 infra 剔除);首轮语法错 2/3 vs 2/6;token 69,771 vs 57,276。mimo-v2.6-pro:两跑均端点 infra(12/12、11/12),**不可评估** | ❌ 四判据未全立 ⇒ 按 §3.7 继续改协议 |
| **(c) 契约消融**(四边界×三情形) | 带契约错值拦截 = 100%;带契约对值误报 = 0%;无契约路径零回归 | 拦截 4/4=**100%**;误报 0/4=**0%**;无契约 4/4 动态语义保持(含 `missing map key` 基线) | ✅ 过 |
| **(d) 防漂移演练**(9 漂移 + 2 负对照) | 故意写错必报 = 100%;对照组误报 = 0% | 必报 9/9=**100%**(`unknown_type`×2、`param_drift`×2、`return_mismatch`、`arg_mismatch`、`unknown_key`、`contract.duplicate`、`contract.unknown_table`);负对照误报 0/2 | ✅ 过 |
| **(e) 核心守卫演练**(3 种变异注入) | 单边改动必红;还原必绿 | 3/3 必红(`CORE_CONSTRUCTS` 私增、`core-surface.md` 私增、金样删除);还原全绿 | ✅ 过 |
**可复制结论(a/c/d/e 全过)**:锚点臂一轮修复率双模型 100%(判据 ≥80%,增量 +15pp/+10pp——易锚定样本近天花板,区分性留难样本扩展);契约系统"只在声明处拦截、零误报、不碰动态路径"成立;契约/实现互查防漂移 100% 必报;核心面单边膨胀被 CI 守卫机械阻断。
## 2. 实验 (c)(d)(e) 明细
### (c) 契约消融(tests/contract_ablation.rs,确定性)
四边界(调用实参 / 返回值 / 表绑定 / 键访问)各测三情形:
| 情形 | 口径 | 结果 |
|---|---|---|
| ① 带契约 + 错值 | 必须拦截(`contract.arg_mismatch` / `contract.return_mismatch` / `contract.field_mismatch` / `contract.unknown_key`) | 4/4 |
| ② 带契约 + 对值 | 不得报契约错(同路径同形状) | 0/4 误报 |
| ③ 无契约 + 错值 | 保持动态语义(不得出现 `contract.*`;走经典动态错误如 `missing map key`) | 4/4 |
取元一律用主推的 `[]()` 形(`[键](`集合`)`)验证;`集合[^键]` 过渡形保留兼容金样覆盖。
### (d) 防漂移演练(tests/drift_drill.rs,确定性)
9 个"故意写错"全部必报:类型词拼错、参数名漂移、升参未覆盖、返回越约、实参越约、未知键、重复契约表、错列表头契约表、运行时值越约。负对照 2 例(被绑定的数据表、纯动态程序)零误报。同时验证"契约表一经出现即为完整声明"(新升参未覆盖 ⇒ `contract.param_drift` warning)被按设计触发。
### (e) 核心守卫演练(人工变异,tests/core_surface.rs 必红验证)
| 变异 | 注入点 | 结果 |
|---|---|---|
| 私增 `ghost-construct` | `src/parse/mod.rs` `CORE_CONSTRUCTS` | 🔴 必红 |
| 私增 `ghost-construct` 行 | `doc/design/core-surface.md` | 🔴 必红 |
| 删除金样文件 | `tests/markup-v03/soft-emphasis.mq.md` | 🔴 必红 |
三次还原后 🟢 全绿。CI 守卫强制"清单与文档双改 + 全部金样存在"。
## 3. 实验 (b) 盲测:详况与诚实结论
### 协议
两臂系统提示词同文 = 硬规则 12 条 + 契约表三形状;**唯一变量 = 语法知识获取**:
- `query` 臂:MLSP 查询通道(`QUERY: <关键字>` ⇒ `mlsp syntax` 卡片,含戒律原文/样例/文档锚点;≤3 次)
- `docs` 臂:完整 markup 参考背诵(`tests/blind/docs-bundle.md`,背诵式全语法表 + 中文内建面)
任务 6 例(`tests/blind/tasks/`):业务 3(保险理赔准备金 / 工程进度款 / 采购付款门槛,均出自律所实测任务集)+ QuixBugs 改写 3(gcd / 最大子段和 / 质因数分解);oracle = stdout 精确匹配(任务书自带期望输出,把推理难度控制掉,失败归因于**语言能力**)。修复回路 ≤2 次(validate 结构化诊断 + stderr 回喂)。
### deepseek-flash(完成)
| 臂 | 通过(一轮) | 通过(最终) | 首轮语法错 | 平均修复轮(过例) | token(p+c) | infra 剔除 |
|---|---|---|---|---|---|---|
| query | 0/3 | 0/3 | 2/3 | – | 69,771(42,478+27,293) | 3/6 |
| docs | 3/6 | **4/6** | 2/6 | 0.50 | 57,276(33,346+23,930) | 0/6 |
- **docs 臂**:业务题 3/3 全部一轮通过(各 ~3k token);`qb_gcd` 修复 2 轮过;`qb_max_sublist_sum`、`qb_get_factors` 暴露真语法滑倒(列表字面量被当调用 `unknown function [-2,`;参数名漂移 `missing argument for parameter value`)。
- **query 臂**:查询通道**被积极使用**(5/6 例用满 3 次,多词查询如 `条件分支 写法` 也能正确命中卡片——已单独验证查询匹配无缺陷);但 3 例被端点空体吃掉,其余 3 例败于真语法错(Python 式元组 `(a, b)` ⇒ `trailing input in expression`;Python 式调用 `gcd(48, 18)` ⇒ `unknown function gcd(48`)与 1 例查询后未交程序。
### mimo-v2.6-pro(两跑均不可评估)
首跑 **12/12** 全部"非 JSON / 空体"(与 deepseek 并行时段)。三向探针(小提示词×12000/4000、大提示词×12000)证实**网关随机空体**、与 `max_tokens`/提示词体量无稳定关系。加重试(8→12 次、退避 10→15 秒)并**单独**重跑后仍为 **11/12** 端点 infra(含两臂首聊即 `tok=(0,0)` 的空体);唯一执行到的 `qb_gcd` 例暴露真语法错(`**y**` 作语句 ⇒ `unexpected expression input`)。**结论:`mimo-v2.6-pro` 经本网关不可评估**,(b) 判据以 `deepseek-flash` 数据为准。原始报告:[blind-experiment-2026-09-23-mimo-v2.6-pro.md](blind-experiment-2026-09-23-mimo-v2.6-pro.md)。
### 判据对照(截至 deepseek-flash)
| 判据(协议 §2.4 原文口径) | 目标 | 实测(deepseek-flash,非 infra 口径) | 判定 |
|---|---|---|---|
| 最终通过率(≤3 轮)Q 不劣于 D(允许 −0 例) | ≥ D | 0/3 vs 4/6 | ❌ |
| 首轮语法错误率 Q ≤ D | ≤ | 2/3 vs 2/6 | ❌ |
| 平均修复轮次 Q ≤ D | ≤ | query 臂无通过例,不可比 | ⚠️ |
| token 用量 Q ≤ 70% of D | ≤ 40,093 | 69,771(D 的 121.8%) | ❌ |
| (观测项)首轮契约诊断率 Q ≤ D | – | 1/3 vs 0/6 | ➖ 观测 |
**诚实结论:在 deepseek-flash 上,"查询式"没有跑赢"全背诵"**——三项可判量化判据未达,按协议 §3.7 判定:**四判据未全成立 ⇒「AI 不必学语法」本轮未获实证,继续改协议**(不是证伪——infra 吞掉 query 臂一半样本,非 infra n=3)。要点:
1. **统计力被端点削弱**:query 臂 6 例中 3 例被空体吃掉(协议无从执行),非 infra 样本 n=3;mimo-v2.6-pro 整组不可用。判据是"有方向的强声明",当前证据**不足以支持也未证伪**其普适性,只能定格为"deepseek-flash × 本任务集 × 本协议版本"下的一次未达标观测。
2. **失败模式是真发现**:查询臂的败例是**跨语言习惯泄漏**(元组表达式、Python 调用形)——查询卡片能回答"条件分支怎么写",但模型不查询"这里能不能用元组"。说明"AI 不必学语法"的瓶颈不在**查询机制**,而在**模型的自查纪律**(不知道自己不知道)。
3. **token 判据方向存疑**:查询式省的是**系统提示词常驻**(背诵包),花的是**多轮往返**。6 例短程序任务里往返开销 > 常驻节省;该判据更适用于**长会话多文件**场景(一次背诵包 × N 轮 vs 每轮均摊查询),本轮任务形态低估了查询式的收益面。
4. **docs 臂的 4/6 说明任务集有区分度**(不是全过/全不过的退化测量)。
## 4. 测量端基础设施记录(方法学附注)
- **LLM 端点不稳定**是本轮最大的干扰源:随机空体、reasoning 模型 `finish=length` 截断(思考吃满额度、正文为空)。对策:空体重试 5→12 次 + 退避 5→15 秒、截断自适应(`max_tokens` 加倍重试,封顶 32k)、infra 例从判据比率中剔除并单列。
- **harness 缺陷两处**(已修,未污染最终数据):查询额度用满后的续篇被当最终回复(⇒ 假"无程序");程序提取失败不进修复回路(⇒ 少给模型一次标准修复机会)。修复后的协议对两臂完全一致。
- **模型口径变化留痕**:原定 `cflmy`/`mimo-v2.6-flash` 组合按用户指示弃用,改 `mimo-v2.6-pro`/`deepseek-flash`;修复实验 (a) 的双模型数据仍是原组合(金 20 协议已完成,不重跑)。
## 5. 材料与复现
```bash
# (a) 锚点消融(需要 API key)
cargo test --test repair_experiment -- --ignored --nocapture # anchor/plain 双臂×20例
# (b) 盲测(每模型一次;建议单独跑避免并发)
OPENAI_MODEL=deepseek-flash MARQDO_EXP_DATE=2026-09-23 cargo test --test blind_experiment -- --ignored --nocapture
# (c)(d) 确定性
cargo test --test contract_ablation --test drift_drill
# (e) 核心守卫(变异注入→必红→还原必绿,按 perf-validation.md §5 手法)
cargo test --test core_surface
```
- 任务书 / 背诵包(冻结,勿改):`tests/blind/`
- 原始报告:[blind-experiment-2026-09-23-deepseek-flash.md](blind-experiment-2026-09-23-deepseek-flash.md) · [blind-experiment-2026-09-23-mimo-v2.6-pro.md](blind-experiment-2026-09-23-mimo-v2.6-pro.md)(首跑全 infra)· [repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md) · [repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)
- 判据协议:[perf-validation.md](perf-validation.md)(版本化于本仓库,实验前冻结)
+125
View File
@@ -0,0 +1,125 @@
# P4 性能验证设计(实验协议与判据)
| | |
|---|---|
| 状态 | **Accepted · P4 执行依据** |
| 日期 | 2026-09-23 |
| 授权 | 用户授权**自行设计**本性能验证设计(P4 不再等待外部文档导入;`doc/next/002.md` 与性能验证无关) |
| 上位判据 | [three-problems.md](three-problems.md) §5.1 判据矩阵 + §5.2 实验 (a)–(e);「判据矩阵全绿 + 实验数字可复现之前,三大问题一律视为未解决」 |
| 工程任务 | [three-problems-plan.md](three-problems-plan.md) Phase 1–3(已完成);本文只负责**验证它们** |
> **本文定位**:把 three-problems.md §5.2 的五个实验操作化——每个实验给出**材料、协议、指标、判据**,全部机器可执行、数字可复现。实验产物 = 报告 [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。**只认行为与数字,不认宣言。**
## 0. 总览
| 实验 | 验证对象 | 判据(全过 = 该问题的实证成立) | 执行方式 | 状态 |
|------|----------|-------------------------------|----------|------|
| (a) 锚点修复消融 | 问题三 · 可靠反馈 | 一轮修复率 ≥ 80%(anchor 臂),护栏 0 越界 | 模型在环 `tests/repair_experiment.rs` | ✅ 已完成(三轮双模型) |
| (b) 盲测 | 问题三 · 不必学语法 | 查询组错误率 ≤ 全文档组;token 显著更少;修复轮次不升 | 模型在环 `tests/blind_experiment.rs` | 见报告 |
| (c) 契约消融 | 问题二 · 语义校验 | 拦截率 = 100%;误报率 = 0%;无契约路径零回归 | 确定性 `tests/contract_ablation.rs` | 见报告 |
| (d) 防漂移演练 | 问题二 · 契约可信 | 故意写错契约必报率 = 100% | 确定性 `tests/drift_drill.rs` | 见报告 |
| (e) 核心守卫演练 | 问题一 · 核心要小 | 三种变异注入各必红 → 还原必绿 | 变异脚本(见 §4) | 见报告 |
判定口径([three-problems.md](three-problems.md) §5.1):**任何一项判据不成立,对应问题即「未解决」**——不许用文档宣言充数。
---
## 1. 实验 (a):锚点修复消融(问题三 · 可靠反馈)
**假设**:诊断带 `doc_anchor`/`doc_quote`/`suggestion`(锚点诊断)比裸诊断显著提高一轮修复率。
- **对照**:`anchor` 臂(全量诊断字段)vs `plain` 臂(剥掉 doc_anchor/doc_quote/suggestion)。
- **材料**:golden 20 例(10 骨架 × 2 变体:arg/ret/field/key/typo/drift/dup),易锚定错误。
- **协议**:`validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮。
- **指标**:一轮修复率、最终修复率、平均尝试、越界拒、弃权。
- **判据**:anchor 臂一轮修复率 ≥ 80%;护栏 0 次越界应用(越界必拒由 `tests/repair_loop.rs` 硬断言兜底)。
- **执行**:`OPENAI_MODEL=… cargo test --test repair_experiment -- --ignored --nocapture`。
- **结果**:三轮双模型全过(cflmy anchor 100% / mimo 90%→100%,plain 85%–100%,护栏 0 越界)——
详见 [repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md) 与
[repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)。**✅ PASS**。
- **诚实注记**:样本为易锚定错误(两臂近天花板),锚点增量的区分性证据留待难样本扩展;不影响本判据达标。
## 2. 实验 (b):盲测——查询式 vs 全文档背诵(问题三 · 超级核心)
**假设**:「零语法文档 + MLSP 查询」组(Q)成绩**不劣于**「全文档背诵」组(D),且 prompt token 显著更少、修复轮次不升([three-problems.md](three-problems.md) §3.7 最终判据)。
### 2.1 对照(唯一变量 = 语法知识的获取方式)
| 臂 | 系统提示词内容 | 语法知识来源 |
|----|----------------|--------------|
| **Q 查询组** | 硬规则(12 条)+ 契约表三形状 + MLSP 查询通道说明 | 按需 `QUERY: <关键字>`(≤3 次,harness 代答 `mlsp syntax` 卡片) |
| **D 全文档组** | 硬规则(12 条)+ 契约表三形状 + **完整 markup 参考**(`tests/blind/docs-bundle.md`:v0.3 全语法表 + 中文内建面) | 上下文预载(背诵) |
两臂共同点:硬规则与契约表形状**同文**(受控变量,不测契约知识差异);修复回路相同(`mlsp validate` 诊断回喂,≤2 轮);模型 / 温度 / 任务 / 提示词模板相同。
### 2.2 材料:任务集(6 例,业务 3 + 算法 3)
| id | 类型 | 任务 | 功能 oracle(stdout 精确匹配) |
|----|------|------|-------------------------------|
| `claims_reserve_settle` | 业务 | 保险准备金(免赔/共保/分项限额/追偿/地板) | `28000` |
| `contract_milestone_pay` | 业务 | 工程里程碑应付款(保留金/逾期罚/变更/税/地板) | `37354` |
| `vendor_po_gate` | 业务 | 采购 PO 准付闸(折扣/加急/预算帽/合规费/地板) | `814` |
| `qb_gcd` | 算法 | 最大公约数;打印 gcd(48,18) gcd(1071,462) gcd(0,5) gcd(17,5) 各一行 | `6` `21` `5` `1` |
| `qb_max_sublist_sum` | 算法 | 最大子段和;三组输入各打印一行 | `6` `6` `-1` |
| `qb_get_factors` | 算法 | 质因数分解,因数以 `*` 连接;12 / 13 / 60 各一行 | `2*2*3` `13` `2*2*3*5` |
业务任务书复用 MarqdoThesis `formal/exp3-bizreq/data/tasks/`(权威规则文本原样进入提示词);算法任务书为 QuixBugs 改写(从「修 bug」改「实现 + 固定输出」,消除参考源码变量)。
### 2.3 协议(每例)
1. 提示词 = 任务书 + 「输出完整 `.mq.md` 源码于单个 ```markdown 围栏」;
2. **查询阶段**(仅 Q 臂):模型可输出 `QUERY: <关键字>` 行,harness 以 `mlsp syntax` 卡片作答并继续;累计 ≤3 次;
3. **执行阶段**:`marqdo run` → stdout == oracle 即通过;失败则回喂 `mlsp validate` 结构化诊断 + stderr,允许 ≤2 次修复;
4. 记录每轮 token(API `usage.prompt_tokens + completion_tokens` 累计)。
### 2.4 指标与判据
| 指标 | 口径 | 判据 |
|------|------|------|
| 功能通过率(一轮 / 最终≤3 轮) | stdout 与 oracle 精确匹配 | Q 最终通过率**不劣于** D(允许 −0 例) |
| 首轮语法错误率 | 首轮 `validate`/run 出现 parse 类失败的例数占比 | Q ≤ D |
| 首轮契约诊断率 | 首轮出现 `contract.*` 诊断的例数占比 | Q ≤ D(观测项) |
| 平均修复轮次 | 通过前的修复次数(含首轮生成记 0) | Q ≤ D |
| token 用量 | 逐例累计 prompt+completion | Q **显著更少**(≤ 70% of D) |
**判定**:四条判据全成立 ⇒ 「AI 不必学语法」实证成立;否则按 §3.7「继续改协议」,不得以改进文档充数。
- **执行**:`OPENAI_MODEL=… cargo test --test blind_experiment -- --ignored --nocapture`(每模型一轮)。
## 3. 实验 (c):契约消融(问题二 · 语义校验)
**假设**:契约只在**有契约处**拦截错误值(P1:无契约 = 全动态),且不误报。
- **材料**:`tests/contract_ablation.rs` 内联四边界用例(调用实参 / 返回 / 表绑定 / 字段访问)×三形态:
① 带契约 + 错值 → **必拦**(`contract.*` 诊断);② 带契约 + 对值 → **零误报**(正常产出);③ 同程序**删契约表** + 错值 → **零契约诊断**(动态语义原样)。
- **指标与判据**:
- 拦截率 = ①被拦 / ①总数 = **100%**;
- 误报率 = ②误报 / ②总数 = **0%**;
- 无契约零回归 = ③零 `contract.*` 诊断且输出 = 动态语义基线;且全量 `cargo test` 绿(441+ 既有测试是无契约路径的主回归面)。
- **执行**:`cargo test --test contract_ablation`。
## 4. 实验 (d):防漂移演练(问题二 · 契约可信)
**假设**:契约写错**必**被机器抓(不静默信任契约)——three-problems.md §2.8「故意写错契约的金样必红」。
- **材料**:`tests/drift_drill.rs`——故意写错契约的 N 例(类型 typo `nubmer`、未知对象类型、契约参数名 ≠ 升参名 ×2、返回契约明显不符、重复契约表、错位契约表)+ **负对照**(被绑定的 `字段|类型` 数据表 = web_db_migration 式,必须**不**被当契约吃掉)。
- **指标与判据**:
- 必报率 = 漂移例被诊断(`check` 报错/警告或运行时 `contract.*`)/ 漂移例总数 = **100%**;
- 负对照误报 = **0**。
- **执行**:`cargo test --test drift_drill`。
## 5. 实验 (e):核心守卫演练(问题一 · 核心要小)
**假设**:核心表面任何**单侧**变更(代码/文档/金样不同步)→ CI 必红——three-problems.md §1.5「新增标记不更新清单时 CI 必须红」。
- **材料**:`tests/core_surface.rs` 守卫 + 三种变异注入(脚本化,`git checkout` 还原):
1. `src/parse/mod.rs` `CORE_CONSTRUCTS` 增一行、不改文档 → **必红**;
2. `doc/design/core-surface.md` 表增一行、不改代码 → **必红**;
3. 金样文件改名(路径失效)→ **必红**。
- **指标与判据**:3/3 变异注入后守卫测试红;还原后全绿。**必红率 = 100%**。
- **执行**:报告内嵌演练记录(命令 + 测试输出摘录)。
## 6. 报告与复现
- 报告:[perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)((a) 引用既有两份实验报告;(b)–(e) 本次产出)。
- 复现命令全部写入报告各节;模型在环实验记录模型名与端点,判据数字允许 ±1 例波动(模型非确定性),**判据线本身不放宽**。
- 汇总结论回填 [three-problems-plan.md](three-problems-plan.md) 落地记录;§5.1 判据矩阵逐行标注 ✅/❌。
@@ -0,0 +1,64 @@
# 修复实验(§5.2(a) 锚点消融)—— 2026-09-22
| | |
|---|---|
| 模型 | `mimo-v2.6-flash` @ `https://llm.cflmy.cn/v1` |
| 样本 | golden 20 例(易锚定错误) |
| 协议 | `validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮 |
| 对照 | `anchor` = 诊断带 `doc_anchor`/`doc_quote`/`suggestion`;`plain` = 全部剥掉 |
## 汇总(设计目标:一轮修复率 ≥ 80%)
| 臂 | 一轮修复率 | 最终修复率(≤2轮) | 平均尝试 | 越界拒(护栏) | 弃权 |
|---|---|---|---|---|---|
| anchor | 20/20(100%) | 20/20(100%) | 1.00 | 0 | 0 |
| plain | 18/20(90%) | 19/20(95%) | 1.05 | 0 | 1 |
## 逐例
| 例 | 臂 | 结果 | 轮次 | 越界拒 | 备注 |
|---|---|---|---|---|---|
| arg-num-a | anchor | 一轮修复 | 1 | 0 | |
| arg-num-a | plain | 一轮修复 | 1 | 0 | |
| arg-num-b | anchor | 一轮修复 | 1 | 0 | |
| arg-num-b | plain | 一轮修复 | 1 | 0 | |
| arg-text-a | anchor | 一轮修复 | 1 | 0 | |
| arg-text-a | plain | 一轮修复 | 1 | 0 | |
| arg-text-b | anchor | 一轮修复 | 1 | 0 | |
| arg-text-b | plain | 一轮修复 | 1 | 0 | |
| drift-cover-a | anchor | 一轮修复 | 1 | 0 | |
| drift-cover-a | plain | 一轮修复 | 1 | 0 | |
| drift-cover-b | anchor | 一轮修复 | 1 | 0 | |
| drift-cover-b | plain | 一轮修复 | 1 | 0 | |
| drift-rename-a | anchor | 一轮修复 | 1 | 0 | |
| drift-rename-a | plain | 一轮修复 | 1 | 0 | |
| drift-rename-b | anchor | 一轮修复 | 1 | 0 | |
| drift-rename-b | plain | 一轮修复 | 1 | 0 | |
| dup-delete-a | anchor | 一轮修复 | 1 | 0 | |
| dup-delete-a | plain | 一轮修复 | 1 | 0 | |
| dup-delete-b | anchor | 一轮修复 | 1 | 0 | |
| dup-delete-b | plain | 一轮修复 | 1 | 0 | |
| field-nullable-a | anchor | 一轮修复 | 1 | 0 | |
| field-nullable-a | plain | 一轮修复 | 1 | 0 | |
| field-nullable-b | anchor | 一轮修复 | 1 | 0 | |
| field-nullable-b | plain | 一轮修复 | 1 | 0 | |
| field-type-a | anchor | 一轮修复 | 1 | 0 | |
| field-type-a | plain | 一轮修复 | 1 | 0 | |
| field-type-b | anchor | 一轮修复 | 1 | 0 | |
| field-type-b | plain | 一轮修复 | 1 | 0 | |
| key-fix-a | anchor | 一轮修复 | 1 | 0 | |
| key-fix-a | plain | 未修复 | 1 | 0 | 模型弃权/输出不可解析: [{"op":"replace","line":13","text":"*`用户`[^name]*"}] |
| key-fix-b | anchor | 一轮修复 | 1 | 0 | |
| key-fix-b | plain | 二轮修复 | 2 | 0 | 修复后仍有诊断: {"code":"marqdo.error","contract_ref":null,"doc_anchor":null,"doc_quote":null,"message":"missing map key `phone`","severity":"error","span":{"col":1,"file":"/tmp/marqdo_repair_1666049_plain_key-fix-b.mq.md","line":14},"suggestion":null} |
| ret-type-a | anchor | 一轮修复 | 1 | 0 | |
| ret-type-a | plain | 一轮修复 | 1 | 0 | |
| ret-type-b | anchor | 一轮修复 | 1 | 0 | |
| ret-type-b | plain | 一轮修复 | 1 | 0 | |
| type-typo-a | anchor | 一轮修复 | 1 | 0 | |
| type-typo-a | plain | 一轮修复 | 1 | 0 | |
| type-typo-b | anchor | 一轮修复 | 1 | 0 | |
| type-typo-b | plain | 一轮修复 | 1 | 0 | |
## 护栏核对
- 每次越界编辑都以 `mlsp.repair_out_of_scope` + `abstain` 被拒,且 `repair_apply` 全有或全无(源零字节不改)——由 `tests/repair_loop.rs` 的确定性断言覆盖;本实验计数仅作记录。
@@ -0,0 +1,64 @@
# 修复实验(§5.2(a) 锚点消融)—— 2026-09-22
| | |
|---|---|
| 模型 | `cflmy` @ `https://llm.cflmy.cn/v1` |
| 样本 | golden 20 例(易锚定错误) |
| 协议 | `validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮 |
| 对照 | `anchor` = 诊断带 `doc_anchor`/`doc_quote`/`suggestion`;`plain` = 全部剥掉 |
## 汇总(设计目标:一轮修复率 ≥ 80%)
| 臂 | 一轮修复率 | 最终修复率(≤2轮) | 平均尝试 | 越界拒(护栏) | 弃权 |
|---|---|---|---|---|---|
| anchor | 20/20(100%) | 20/20(100%) | 1.00 | 0 | 0 |
| plain | 17/20(85%) | 17/20(85%) | 0.85 | 0 | 0 |
## 逐例
| 例 | 臂 | 结果 | 轮次 | 越界拒 | 备注 |
|---|---|---|---|---|---|
| arg-num-a | anchor | 一轮修复 | 1 | 0 | |
| arg-num-a | plain | 一轮修复 | 1 | 0 | |
| arg-num-b | anchor | 一轮修复 | 1 | 0 | |
| arg-num-b | plain | 一轮修复 | 1 | 0 | |
| arg-text-a | anchor | 一轮修复 | 1 | 0 | |
| arg-text-a | plain | 一轮修复 | 1 | 0 | |
| arg-text-b | anchor | 一轮修复 | 1 | 0 | |
| arg-text-b | plain | 一轮修复 | 1 | 0 | |
| drift-cover-a | anchor | 一轮修复 | 1 | 0 | |
| drift-cover-a | plain | 一轮修复 | 1 | 0 | |
| drift-cover-b | anchor | 一轮修复 | 1 | 0 | |
| drift-cover-b | plain | 一轮修复 | 1 | 0 | |
| drift-rename-a | anchor | 一轮修复 | 1 | 0 | |
| drift-rename-a | plain | 一轮修复 | 1 | 0 | |
| drift-rename-b | anchor | 一轮修复 | 1 | 0 | |
| drift-rename-b | plain | 一轮修复 | 1 | 0 | |
| dup-delete-a | anchor | 一轮修复 | 1 | 0 | |
| dup-delete-a | plain | 一轮修复 | 1 | 0 | |
| dup-delete-b | anchor | 一轮修复 | 1 | 0 | |
| dup-delete-b | plain | 一轮修复 | 1 | 0 | |
| field-nullable-a | anchor | 一轮修复 | 1 | 0 | |
| field-nullable-a | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
| field-nullable-b | anchor | 一轮修复 | 1 | 0 | |
| field-nullable-b | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
| field-type-a | anchor | 一轮修复 | 1 | 0 | |
| field-type-a | plain | 一轮修复 | 1 | 0 | |
| field-type-b | anchor | 一轮修复 | 1 | 0 | |
| field-type-b | plain | 一轮修复 | 1 | 0 | |
| key-fix-a | anchor | 一轮修复 | 1 | 0 | |
| key-fix-a | plain | 一轮修复 | 1 | 0 | |
| key-fix-b | anchor | 一轮修复 | 1 | 0 | |
| key-fix-b | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
| ret-type-a | anchor | 一轮修复 | 1 | 0 | |
| ret-type-a | plain | 一轮修复 | 1 | 0 | |
| ret-type-b | anchor | 一轮修复 | 1 | 0 | |
| ret-type-b | plain | 一轮修复 | 1 | 0 | |
| type-typo-a | anchor | 一轮修复 | 1 | 0 | |
| type-typo-a | plain | 一轮修复 | 1 | 0 | |
| type-typo-b | anchor | 一轮修复 | 1 | 0 | |
| type-typo-b | plain | 一轮修复 | 1 | 0 | |
## 护栏核对
- 每次越界编辑都以 `mlsp.repair_out_of_scope` + `abstain` 被拒,且 `repair_apply` 全有或全无(源零字节不改)——由 `tests/repair_loop.rs` 的确定性断言覆盖;本实验计数仅作记录。
+225
View File
@@ -0,0 +1,225 @@
# 三大问题落地计划(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 基线)零失败。
+393
View File
@@ -0,0 +1,393 @@
# 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 对齐)
+1 -1
View File
@@ -1 +1 @@
1.0.7
1.1.0
+8
View File
@@ -200,17 +200,25 @@ PY
rm -rf third_party/rust
mkdir -p third_party
RUST_EXTRACT="$(mktemp -d "${TMPDIR:-/tmp}/marqdo-rust.XXXXXX")"
# Always drop the ~1.5G extract dir, even on failure (tmpfs fills up otherwise).
trap 'rm -rf "$RUST_EXTRACT"' EXIT
tar -xzf "$RUST_TARBALL" -C "$RUST_EXTRACT"
INSTALL_SH="$(find "$RUST_EXTRACT" -maxdepth 2 -name install.sh | head -1)"
if [ -z "$INSTALL_SH" ]; then
echo "error: install.sh not found in ${RUST_TARBALL}" >&2
exit 1
fi
# Launchpad builds need only rustc + cargo + rust-std (debian/rules PATH).
# Skip docs/json-docs/rustfmt/rls — ~1G of dead weight in the orig tarball.
bash "$INSTALL_SH" \
--prefix="$PKG_ROOT/third_party/rust" \
--without=rust-docs \
--without=rust-docs-json-preview \
--without=rustfmt-preview \
--without=rls-preview \
--disable-ldconfig
rm -rf "$RUST_EXTRACT"
trap - EXIT
"$PKG_ROOT/third_party/rust/bin/rustc" --version
"$PKG_ROOT/third_party/rust/bin/cargo" --version
+4
View File
@@ -61,6 +61,10 @@ pub struct Function {
pub base: Option<String>,
/// Prose `` `名` `` never read/assigned on the executable surface (not params).
pub dead_binds: Vec<String>,
/// 渐进式契约(T2.1):形参/返回/对象字段契约(附着在文档表上,升参推断前提取)。
pub contract: Option<crate::contract::Contract>,
/// 集合契约(T2.1):变量名 → 字段契约(紧邻 `` `名` = `` 绑定之前的文档表)。
pub var_contracts: HashMap<String, crate::contract::Contract>,
}
impl Function {
+213
View File
@@ -0,0 +1,213 @@
//! `marqdo check` —— 静态契约互查(T2.3 + T2.5)。
//!
//! 只读静态检查,不执行程序。三类必产诊断:
//!
//! 1. **防漂移(T2.5)**:契约行 vs 升参推断形参**双向互查**——契约表一经出现
//! 就是该单元形参的完整声明:契约多出的名字(错行)与未被覆盖的推断形参
//! (新升参)都是 `contract.param_drift`。
//! 2. **未知类型名**:`Ty::Object` 必须是已知对象类型(防 `nubmer` 拼错,
//! 附最近建议)⇒ `contract.unknown_type`。
//! 3. **错位契约**:契约形状(含 `类型` 列)的未绑定表出现在不允许位置
//! (提取阶段原样留在 body 里的就是)⇒ `contract.misplaced`。
//!
//! 任一 Error ⇒ 进程以非零码退出。诊断全部带 `doc_anchor` 锚点(T2.4)。
use std::path::Path;
use anyhow::Result;
use crate::ast::{Expr, Function, Module, Stmt};
use crate::contract::{self, Contract, Ty};
use crate::diagnostics::{Diagnostic, Severity, Span};
use crate::load;
/// 读取文件 + 装载(含 import)后做全量契约互查。
pub fn check_path(path: &Path) -> Result<Vec<Diagnostic>> {
let module = load::load_module(path)?;
Ok(check_module(&module, Some(path)))
}
/// 递归检查模块全部函数(含子函数)的契约。
pub fn check_module(module: &Module, path: Option<&Path>) -> Vec<Diagnostic> {
let known = known_type_names(module);
let mut out = Vec::new();
walk(module, &module.functions, path, &known, &mut out);
out
}
/// 已知对象类型名:本文件 `#` 对象 + import/use 绑定 + 导入库的 `#` 对象。
fn known_type_names(module: &Module) -> Vec<String> {
let mut names = Vec::new();
for f in &module.functions {
if f.is_object() {
names.push(f.name.clone());
}
}
for i in &module.imports {
names.push(i.bind.clone());
}
for u in &module.uses {
names.push(u.bind.clone());
}
for lib in module.import_modules.values() {
for f in &lib.functions {
if f.is_object() {
names.push(f.name.clone());
}
}
}
names
}
fn walk(
module: &Module,
funs: &[Function],
path: Option<&Path>,
known: &[String],
out: &mut Vec<Diagnostic>,
) {
for fun in funs {
check_one(module, fun, path, known, out);
walk(module, &fun.children, path, known, out);
}
}
fn check_one(
module: &Module,
fun: &Function,
path: Option<&Path>,
known: &[String],
out: &mut Vec<Diagnostic>,
) {
if let Some(c) = &fun.contract {
for p in &c.params {
type_name_check(&p.ty, c, &fun.name, path, fun.span, known, out);
}
if let Some(r) = &c.returns {
type_name_check(&r.ty, c, &fun.name, path, fun.span, known, out);
}
for f in &c.fields {
type_name_check(&f.ty, c, &fun.name, path, fun.span, known, out);
}
// ---- T2.5 防漂移:契约行 vs 升参推断形参(双向) ----
let inferred: Vec<String> = fun.params.iter().map(|p| p.name.clone()).collect();
for p in &c.params {
if !inferred.contains(&p.name) {
out.push(c.diagnostic(
"contract.param_drift",
&fun.name,
format!(
"契约参数 `{}` 不是 `{}` 的形参(当前形参:[{}])",
p.name,
fun.name,
inferred.join(", ")
),
"删除契约表该行,或让该名在函数体被读取(升参)/ 用 `+` 行显式声明".to_string(),
path,
fun.span,
));
}
}
for name in &inferred {
if !c.params.iter().any(|p| p.name == *name) {
let d = c
.diagnostic(
"contract.param_drift",
&fun.name,
format!(
"形参 `{name}` 未被契约覆盖(可能是新推断的升参;契约表一经出现即为完整声明)"
),
"在契约表补一行 `| {name} | 类型 | 说明 |`,或删掉契约表回到纯动态".to_string(),
path,
fun.span,
)
.with_severity(Severity::Warning);
out.push(d);
}
}
}
for (name, c) in &fun.var_contracts {
for f in &c.fields {
type_name_check(&f.ty, c, name, path, fun.span, known, out);
}
}
// ---- 错位契约:契约形状的未绑定表被提取器原样留在 body ----
for stmt in &fun.body {
let Stmt::Expr { value: Expr::Map(pairs), span } = stmt else {
continue;
};
if let Some(Ok(c)) = contract::parse_contract_table(pairs, span.line, span.line, Vec::new())
{
out.push(c.diagnostic(
"contract.misplaced",
&fun.name,
"契约表位置不允许(形参/返回表只能在函数体首个可执行行之前;字段表只能紧邻绑定或对象体首成员之前),已按普通表处理".to_string(),
"移动契约表到允许位置,或改表头避开契约形状(含 `类型` 列)".to_string(),
path,
*span,
));
}
}
let _ = module;
}
/// 对象类型名必须已知;拼错(`nubmer`)⇒ `contract.unknown_type` + 最近建议。
fn type_name_check(
ty: &Ty,
c: &Contract,
unit: &str,
path: Option<&Path>,
span: Span,
known: &[String],
out: &mut Vec<Diagnostic>,
) {
let Ty::Object(name) = ty else { return };
if known.iter().any(|k| k == name) {
return;
}
let suggestion = match suggest(name, known) {
Some(near) => format!("是不是想写 `{near}`?已知类型:{}", known.join(" / ")),
None => format!("已知类型:{}", known.join(" / ")),
};
out.push(c.diagnostic(
"contract.unknown_type",
unit,
format!("未知类型名 `{name}`(不是原语,也没有对应的 `#` 对象)"),
suggestion,
path,
span,
));
}
const PRIMITIVES: &[&str] = &["text", "number", "bool", "list", "map", "any"];
fn edit_distance(a: &str, b: &str) -> usize {
let a: Vec<char> = a.chars().collect();
let b: Vec<char> = b.chars().collect();
let mut prev: Vec<usize> = (0..=b.len()).collect();
let mut cur = vec![0usize; b.len() + 1];
for i in 1..=a.len() {
cur[0] = i;
for j in 1..=b.len() {
let cost = usize::from(a[i - 1] != b[j - 1]);
cur[j] = (prev[j] + 1).min(cur[j - 1] + 1).min(prev[j - 1] + cost);
}
std::mem::swap(&mut prev, &mut cur);
}
prev[b.len()]
}
fn suggest(name: &str, known: &[String]) -> Option<String> {
let lower = name.to_ascii_lowercase();
let mut best: Option<(usize, String)> = None;
let candidates = PRIMITIVES.iter().map(|s| s.to_string()).chain(
known.iter().cloned(),
);
for cand in candidates {
let d = edit_distance(&lower, &cand.to_ascii_lowercase());
if d <= 2 && best.as_ref().map(|(bd, _)| d < *bd).unwrap_or(true) {
best = Some((d, cand));
}
}
best.map(|(_, c)| c)
}
+632
View File
@@ -0,0 +1,632 @@
//! Progressive contracts (渐进式契约 / 标注类型) —— schema 长在表格/说明段落里。
//!
//! 动态默认、按需校验、零契约文件零回归;TS/TS 的全程序静态类型被明确**拒绝**。
//! 契约唯一来源是**未绑定文档表**(绑定表是数据,永不视为契约):
//!
//! | 形状(含 `类型` 列) | 允许位置 | 附着对象 |
//! |----------------------|----------|----------|
//! | `参数`/`返回` 表 | 函数体首个可执行行之前 | 函数(形参/返回契约) |
//! | `字段` 表 | 紧邻 `` `名` = `` 绑定之前 | 变量(集合契约) |
//! | `字段` 表 | 对象(`#`)体首成员之前 | 对象类型(字段契约) |
//!
//! 提取在**升参推断之前**执行(见 `parse`),契约表的单元不会污染推断。
//! 校验只发生在四个运行时边界(调用实参 / 字段访问 / 表绑定 / 返回)与
//! `marqdo check` 静态互查;契约表本身永不执行、永不进入值空间。
//! 锚点诊断见 [`Contract::anchor`] / [`Contract::quote_text`](T2.4)。
use std::collections::HashMap;
use std::path::Path;
use anyhow::Result;
use crate::ast::Expr;
use crate::diagnostics::{ContractRef, Diagnostic, Severity, Span};
use crate::value::Value;
/// 契约类型词汇(`doc/design/core-surface.md` 的文档层扩展,不进语言核心)。
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Ty {
/// 任意值(类型列留空)。
Any,
Text,
/// `int` / `num`(`Value::Int` / `Value::Num` / 符号公式)。
Number,
Bool,
List,
Map,
/// 对象类型名(`#` 对象;`check` 阶段校验存在性,防 `nubmer` 拼错)。
Object(String),
}
impl Ty {
/// 解析类型列文本(大小写不敏感;未知名 → `Object(name)`,由 check 验证)。
pub fn parse(raw: &str) -> Ty {
let name = raw.trim().trim_matches('`').to_ascii_lowercase();
match name.as_str() {
"" | "any" | "任意" => Ty::Any,
"text" | "str" | "string" | "文本" | "字串" | "字符串" => Ty::Text,
"number" | "int" | "float" | "num" | "numeric" | "数字" | "数值" => Ty::Number,
"bool" | "boolean" | "布尔" => Ty::Bool,
"list" | "列表" | "表" => Ty::List,
"map" | "dict" | "object" | "字典" | "映射" => Ty::Map,
_ => Ty::Object(raw.trim().trim_matches('`').to_string()),
}
}
/// 契约类型名(诊断消息显示用;与 `type` 内置的运行时名对照)。
pub fn name(&self) -> String {
match self {
Ty::Any => "any".into(),
Ty::Text => "text".into(),
Ty::Number => "number".into(),
Ty::Bool => "bool".into(),
Ty::List => "list".into(),
Ty::Map => "map".into(),
Ty::Object(n) => n.clone(),
}
}
/// 值是否满足契约类型(对象类型看 `_type` 实例标签)。
pub fn matches_value(&self, v: &Value) -> bool {
match self {
Ty::Any => true,
Ty::Text => matches!(v, Value::Text(_)),
// 符号公式($$…$$)是数值表达式,按 number 收。
Ty::Number => matches!(v, Value::Int(_) | Value::Num(_) | Value::Formula(_)),
Ty::Bool => matches!(v, Value::Bool(_)),
Ty::List => matches!(v, Value::List(_)),
Ty::Map => matches!(v, Value::Map(_)),
Ty::Object(n) => instance_type_name(v).as_deref() == Some(n.as_str()),
}
}
/// 列语义(几何即类型):标量按本类型,或**元素全匹配**的列向量。
pub fn matches_column(&self, v: &Value) -> bool {
if self.matches_value(v) {
return true;
}
match v {
Value::List(items) => items.iter().all(|it| self.matches_value(it)),
Value::Map(pairs) => pairs
.iter()
.all(|(_, it)| match it {
// map-of-lists 的列向量
Value::List(xs) => xs.iter().all(|x| self.matches_value(x)),
scalar => self.matches_value(scalar),
})
&& !pairs.is_empty(),
_ => false,
}
}
}
/// 运行时 `type` 名(诊断消息里的「实际」侧)。
pub fn type_of(v: &Value) -> &'static str {
match v {
Value::None => "none",
Value::Bool(_) => "bool",
Value::Int(_) => "int",
Value::Num(_) => "num",
Value::Text(_) => "text",
Value::List(_) => "list",
Value::Map(_) => "map",
Value::Formula(_) => "formula",
Value::Code(_) => "code",
}
}
fn instance_type_name(v: &Value) -> Option<String> {
let Value::Map(pairs) = v else { return None };
pairs
.iter()
.find(|(k, _)| k == "_type")
.and_then(|(_, v)| match v {
Value::Text(t) => Some(t.clone()),
_ => None,
})
}
#[derive(Debug, Clone)]
pub struct ParamContract {
pub name: String,
pub ty: Ty,
pub desc: String,
}
#[derive(Debug, Clone)]
pub struct ReturnContract {
pub ty: Ty,
pub desc: String,
}
#[derive(Debug, Clone)]
pub struct FieldContract {
pub name: String,
pub ty: Ty,
pub nullable: bool,
pub desc: String,
}
/// 一份契约(一个契约表块;同单元多表由 [`merge_contract`] 合并)。
#[derive(Debug, Clone)]
pub struct Contract {
pub params: Vec<ParamContract>,
pub returns: Option<ReturnContract>,
pub fields: Vec<FieldContract>,
pub start_line: u32,
pub end_line: u32,
/// 契约表原文行(诊断 `doc_quote`)。
pub quote: Vec<String>,
}
impl Contract {
/// 文档锚点(T2.4):`file.mq.md#L4-L7`。
pub fn anchor(&self, path: Option<&Path>) -> String {
match path {
Some(p) => format!("{}#L{}-L{}", p.display(), self.start_line, self.end_line),
None => format!("#L{}-L{}", self.start_line, self.end_line),
}
}
pub fn quote_text(&self) -> String {
self.quote.join("\n")
}
/// 契约声明摘要(诊断 `contract_ref.declared`)。
pub fn describe(&self) -> String {
let mut parts = Vec::new();
if !self.params.is_empty() {
let list = self
.params
.iter()
.map(|p| format!("{}: {}", p.name, p.ty.name()))
.collect::<Vec<_>>()
.join(", ");
parts.push(format!("参数[{list}]"));
}
if let Some(r) = &self.returns {
parts.push(format!("返回 {}", r.ty.name()));
}
if !self.fields.is_empty() {
let list = self
.fields
.iter()
.map(|f| format!("{}: {}", f.name, f.ty.name()))
.collect::<Vec<_>>()
.join(", ");
parts.push(format!("字段[{list}]"));
}
parts.join("; ")
}
/// 装配带契约上下文的诊断(code + suggestion + doc_anchor + doc_quote + contract_ref)。
pub fn diagnostic(
&self,
code: &str,
unit: &str,
message: String,
suggestion: String,
path: Option<&Path>,
span: Span,
) -> Diagnostic {
Diagnostic::new(path, span, message)
.with_code(code)
.with_severity(Severity::Error)
.with_suggestion(suggestion)
.with_doc_anchor(self.anchor(path))
.with_doc_quote(self.quote_text())
.with_contract_ref(ContractRef {
unit: unit.to_string(),
kind: "contract".to_string(),
name: unit.to_string(),
declared: self.describe(),
})
}
}
/// 把第二个契约表合并进第一个(多表块;重复行 → Err 防两份契约打架)。
pub fn merge_contract(dst: &mut Contract, src: Contract) -> std::result::Result<(), String> {
for p in src.params {
if dst.params.iter().any(|q| q.name == p.name) {
return Err(format!("契约参数 `{}` 重复(防两份契约打架)", p.name));
}
dst.params.push(p);
}
if let Some(r) = src.returns {
if dst.returns.is_some() {
return Err("返回契约重复(防两份契约打架)".to_string());
}
dst.returns = Some(r);
}
for f in src.fields {
if dst.fields.iter().any(|g| g.name == f.name) {
return Err(format!("契约字段 `{}` 重复(防两份契约打架)", f.name));
}
dst.fields.push(f);
}
dst.start_line = dst.start_line.min(src.start_line);
dst.end_line = dst.end_line.max(src.end_line);
for q in src.quote {
if !dst.quote.contains(&q) {
dst.quote.push(q);
}
}
Ok(())
}
// ---------- 契约表识别与解析 ----------
const PARAM_HEADERS: &[&str] = &["参数", "形参", "param", "params", "arg", "args"];
const RETURN_HEADERS: &[&str] = &["返回", "返回值", "return", "returns", "result"];
const FIELD_HEADERS: &[&str] = &["字段", "列", "键", "field", "fields", "key", "keys", "column", "columns"];
const TYPE_HEADERS: &[&str] = &["类型", "type"];
const DESC_HEADERS: &[&str] = &["说明", "描述", "备注", "注释", "desc", "description"];
const NULLABLE_HEADERS: &[&str] = &["可空", "nullable", "optional"];
fn norm_header(h: &str) -> String {
h.trim().trim_matches('`').to_ascii_lowercase()
}
fn header_is(h: &str, vocab: &[&str]) -> bool {
let n = norm_header(h);
vocab.iter().any(|v| *v == n)
}
fn find_col(headers: &[String], vocab: &[&str]) -> Option<usize> {
headers.iter().position(|h| header_is(h, vocab))
}
/// 单元格 → 文本(text / `` `ident` `` / 数字);嵌套表 → None(那是数据表)。
fn cell_to_text(e: &Expr) -> Option<String> {
match e {
Expr::Literal(crate::ast::Literal::Text(s)) => Some(s.clone()),
Expr::Var(name) => Some(name.clone()),
Expr::Literal(crate::ast::Literal::Int(i)) => Some(i.to_string()),
Expr::Literal(crate::ast::Literal::Num(n)) => Some(n.to_string()),
Expr::Literal(crate::ast::Literal::Bool(b)) => Some(b.to_string()),
_ => None,
}
}
/// 列值 → 行文本(标量 = 单行;列向量 = 多行;其它 = None)。
fn col_rows(e: &Expr) -> Option<Vec<String>> {
match e {
Expr::List(items) => items.iter().map(cell_to_text).collect(),
scalar => Some(vec![cell_to_text(scalar)?]),
}
}
fn is_nullable(raw: &str) -> bool {
matches!(
norm_header(raw).as_str(),
"是" | "true" | "yes" | "y" | "可空" | "✓"
)
}
/// 未绑定文档表(`Expr::Map`)→ 契约块。
///
/// - `None`:非契约形状(普通数据/说明表,原样保留)。
/// - `Some(Err)`:契约形状但畸形(缺参数名、列不齐、多行返回表…)——必产诊断。
/// - `Some(Ok)`:合法契约(`参数`/`返回`/`字段` 三形状之一,须含 `类型` 列)。
pub fn parse_contract_table(
pairs: &[(String, Expr)],
start_line: u32,
end_line: u32,
quote: Vec<String>,
) -> Option<Result<Contract>> {
let headers: Vec<String> = pairs.iter().map(|(k, _)| k.clone()).collect();
let kind = if find_col(&headers, PARAM_HEADERS).is_some() {
1
} else if find_col(&headers, RETURN_HEADERS).is_some() {
2
} else if find_col(&headers, FIELD_HEADERS).is_some() {
3
} else {
return None;
};
// 契约表必须有 `类型` 列(否则是普通说明表——如 `| 参数 | 说明 |`)。
let Some(type_col) = find_col(&headers, TYPE_HEADERS) else {
return None;
};
let meta = || (start_line, end_line, quote.clone());
Some(match kind {
1 => parse_params_table(pairs, &headers, type_col, meta()),
2 => parse_return_table(pairs, &headers, type_col, meta()),
_ => parse_fields_table(pairs, &headers, type_col, meta()),
})
}
fn contract(
meta: (u32, u32, Vec<String>),
) -> Contract {
Contract {
params: Vec::new(),
returns: None,
fields: Vec::new(),
start_line: meta.0,
end_line: meta.1,
quote: meta.2,
}
}
fn malformed(meta: (u32, u32, Vec<String>), span_line: u32, msg: String) -> Result<Contract> {
let (start, end, quote) = meta;
let c = Contract {
params: Vec::new(),
returns: None,
fields: Vec::new(),
start_line: start,
end_line: end,
quote,
};
Err(c
.diagnostic(
"contract.malformed",
"(契约表)",
msg,
"按 `参数|类型|说明` / `返回|类型|说明` / `字段|类型|可空|说明` 形状修正契约表".into(),
None,
Span { line: span_line, col: 1 },
)
.into())
}
fn parse_params_table(
pairs: &[(String, Expr)],
headers: &[String],
type_col: usize,
meta: (u32, u32, Vec<String>),
) -> Result<Contract> {
let start_line = meta.0;
let name_col = find_col(headers, PARAM_HEADERS).unwrap();
let desc_col = find_col(headers, DESC_HEADERS);
let names = col_rows(&pairs[name_col].1).unwrap_or_default();
let types = col_rows(&pairs[type_col].1).unwrap_or_default();
let descs = desc_col
.and_then(|c| col_rows(&pairs[c].1))
.unwrap_or_default();
if names.len() != types.len() || (!descs.is_empty() && descs.len() != names.len()) {
return malformed(meta, start_line, "契约表列不齐(参数/类型/说明 行数不一致)".into());
}
let mut c = contract(meta.clone());
for (i, name) in names.iter().enumerate() {
let name = name.trim();
if name.is_empty() {
return malformed(meta, start_line, format!("契约表第 {} 行缺参数名", i + 1));
}
c.params.push(ParamContract {
name: name.to_string(),
ty: Ty::parse(&types[i]),
desc: descs.get(i).cloned().unwrap_or_default(),
});
}
Ok(c)
}
fn parse_return_table(
pairs: &[(String, Expr)],
headers: &[String],
type_col: usize,
meta: (u32, u32, Vec<String>),
) -> Result<Contract> {
let start_line = meta.0;
let desc_col = find_col(headers, DESC_HEADERS);
let types = col_rows(&pairs[type_col].1).unwrap_or_default();
let descs = desc_col
.and_then(|c| col_rows(&pairs[c].1))
.unwrap_or_default();
if types.len() != 1 {
return malformed(meta, start_line, "返回契约只能一行(`返回|类型|说明`)".into());
}
let mut c = contract(meta.clone());
c.returns = Some(ReturnContract {
ty: Ty::parse(&types[0]),
desc: descs.first().cloned().unwrap_or_default(),
});
Ok(c)
}
fn parse_fields_table(
pairs: &[(String, Expr)],
headers: &[String],
type_col: usize,
meta: (u32, u32, Vec<String>),
) -> Result<Contract> {
let start_line = meta.0;
let name_col = find_col(headers, FIELD_HEADERS).unwrap();
let desc_col = find_col(headers, DESC_HEADERS);
let null_col = find_col(headers, NULLABLE_HEADERS);
let names = col_rows(&pairs[name_col].1).unwrap_or_default();
let types = col_rows(&pairs[type_col].1).unwrap_or_default();
if names.len() != types.len() {
return malformed(meta, start_line, "契约表列不齐(字段/类型 行数不一致)".into());
}
let mut c = contract(meta.clone());
for (i, name) in names.iter().enumerate() {
let name = name.trim();
if name.is_empty() {
return malformed(meta, start_line, format!("契约表第 {} 行缺字段名", i + 1));
}
c.fields.push(FieldContract {
name: name.to_string(),
ty: Ty::parse(&types[i]),
nullable: null_col
.and_then(|c| col_rows(&pairs[c].1))
.and_then(|rows| rows.get(i).cloned())
.map(|s| is_nullable(&s))
.unwrap_or(false),
desc: desc_col
.and_then(|c| col_rows(&pairs[c].1))
.and_then(|rows| rows.get(i).cloned())
.unwrap_or_default(),
});
}
Ok(c)
}
// ---------- 运行时边界校验(T2.2,四个边界) ----------
/// 边界 1:调用实参 vs 形参契约。
pub fn call_arg_diag(
c: &Contract,
unit: &str,
bound: &HashMap<String, Value>,
path: Option<&Path>,
span: Span,
) -> Option<Diagnostic> {
for p in &c.params {
let Some(v) = bound.get(&p.name) else { continue };
if v == &Value::None {
continue; // 显式 None = 未填,交给缺参/默认值语义
}
if !p.ty.matches_value(v) {
return Some(c.diagnostic(
"contract.arg_mismatch",
unit,
format!(
"参数 `{}` 期望 {},实际 {}(契约校验)",
p.name,
p.ty.name(),
type_of(v)
),
format!(
"把实参改为 {},或修正契约表 `参数/类型` 列(锚点 {})",
p.ty.name(),
c.anchor(path)
),
path,
span,
));
}
}
None
}
/// 边界 2:返回值 vs 返回契约。
pub fn return_diag(
c: &Contract,
unit: &str,
v: &Value,
path: Option<&Path>,
span: Span,
) -> Option<Diagnostic> {
let r = c.returns.as_ref()?;
if !r.ty.matches_value(v) {
return Some(c.diagnostic(
"contract.return_mismatch",
unit,
format!(
"返回值期望 {},实际 {}(契约校验)",
r.ty.name(),
type_of(v)
),
format!(
"修正返回值,或调整契约表 `返回|类型`(锚点 {})",
c.anchor(path)
),
path,
span,
));
}
None
}
/// 边界 3:表绑定 vs 字段契约(集合契约;几何即类型——标量或列向量皆可)。
pub fn fields_diag(
c: &Contract,
unit: &str,
v: &Value,
path: Option<&Path>,
span: Span,
) -> Option<Diagnostic> {
if c.fields.is_empty() {
return None;
}
let Value::Map(pairs) = v else {
return Some(c.diagnostic(
"contract.field_mismatch",
unit,
format!("绑定值期望表(map),实际 {}(契约校验)", type_of(v)),
"绑定一个表值,或删除该字段契约表".into(),
path,
span,
));
};
for f in &c.fields {
match pairs.iter().find(|(k, _)| k == &f.name) {
Some((_, val)) => {
if !f.ty.matches_column(val) {
return Some(c.diagnostic(
"contract.field_mismatch",
unit,
format!(
"字段 `{}` 期望 {},实际 {}(契约校验)",
f.name,
f.ty.name(),
type_of(val)
),
format!("修正数据,或调整契约表 `字段/类型`(锚点 {})", c.anchor(path)),
path,
span,
));
}
}
None if f.nullable => {}
None => {
return Some(c.diagnostic(
"contract.field_mismatch",
unit,
format!("缺少字段 `{}`(契约要求,不可空)", f.name),
format!("补上字段 `{}`,或在契约表 `可空` 列标 `是`(锚点 {})", f.name, c.anchor(path)),
path,
span,
));
}
}
}
None
}
/// 边界 4:字段访问 `[键](集合)` vs 字段契约(键存在性 + 取值类型)。
pub fn index_diag(
c: &Contract,
unit: &str,
key: &str,
v: &Value,
path: Option<&Path>,
span: Span,
) -> Option<Diagnostic> {
let Some(f) = c.fields.iter().find(|f| f.name == key) else {
return Some(c.diagnostic(
"contract.unknown_key",
unit,
format!("字段 `{key}` 不在契约中(契约校验)"),
format!(
"使用契约内的字段({}),或在契约表补一行",
c.fields
.iter()
.map(|f| f.name.as_str())
.collect::<Vec<_>>()
.join(" / ")
),
path,
span,
));
};
if v != &Value::None && !f.ty.matches_column(v) {
return Some(c.diagnostic(
"contract.field_mismatch",
unit,
format!(
"字段 `{key}` 期望 {},实际 {}(契约校验)",
f.ty.name(),
type_of(v)
),
format!("修正数据,或调整契约表 `字段/类型`(锚点 {})", c.anchor(path)),
path,
span,
));
}
None
}
+132
View File
@@ -41,13 +41,40 @@ pub fn display_path(path: &Path) -> String {
}
}
/// Diagnostic severity.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Severity {
Error,
Warning,
}
/// Contract reference (Phase 2 填值;schema 源头 = 契约表 / 说明段落).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ContractRef {
pub unit: String,
pub kind: String,
pub name: String,
pub declared: String,
}
/// Unified diagnostic: `path:line:col: message` (path omitted if unknown).
///
/// 人类文本(`Display`)与机器面([`Diagnostic::to_json`])同源:凡可定位必有
/// `span`;凡契约错必带 `doc_anchor` / `doc_quote` / `contract_ref`
/// (见 `doc/roadmap/three-problems.md` §3.3 诊断协议)。
#[derive(Debug, Error, Clone)]
#[error("{}", self.format_message())]
pub struct Diagnostic {
pub path: Option<PathBuf>,
pub span: Span,
pub message: String,
/// Stable machine code (`parse.*` / `contract.*` / `runtime.*` …).
pub code: String,
pub severity: Severity,
pub suggestion: Option<String>,
pub doc_anchor: Option<String>,
pub doc_quote: Option<String>,
pub contract_ref: Option<ContractRef>,
}
impl Diagnostic {
@@ -56,6 +83,12 @@ impl Diagnostic {
path: path.map(|p| p.to_path_buf()),
span,
message: message.into(),
code: "marqdo.error".to_string(),
severity: Severity::Error,
suggestion: None,
doc_anchor: None,
doc_quote: None,
contract_ref: None,
}
}
@@ -63,12 +96,74 @@ impl Diagnostic {
Self::new(Some(path), span, message)
}
pub fn with_code(mut self, code: impl Into<String>) -> Self {
self.code = code.into();
self
}
pub fn with_severity(mut self, severity: Severity) -> Self {
self.severity = severity;
self
}
pub fn with_suggestion(mut self, suggestion: impl Into<String>) -> Self {
self.suggestion = Some(suggestion.into());
self
}
pub fn with_doc_anchor(mut self, anchor: impl Into<String>) -> Self {
self.doc_anchor = Some(anchor.into());
self
}
pub fn with_doc_quote(mut self, quote: impl Into<String>) -> Self {
self.doc_quote = Some(quote.into());
self
}
pub fn with_contract_ref(mut self, contract_ref: ContractRef) -> Self {
self.contract_ref = Some(contract_ref);
self
}
/// 从 anyhow 错误链中找回结构化诊断(load/parse 包了 context 也不丢;MLSP 面)。
pub fn find(err: &anyhow::Error) -> Option<&Diagnostic> {
err.chain().find_map(|e| e.downcast_ref::<Diagnostic>())
}
pub fn format_message(&self) -> String {
match &self.path {
Some(p) => format!("{}:{}: {}", display_path(p), self.span, self.message),
None => format!("{}: {}", self.span, self.message),
}
}
/// Machine-readable form(AI/MLSP 面;`run --json` 出口)。
pub fn to_json(&self) -> serde_json::Value {
use serde_json::json;
json!({
"code": self.code,
"severity": match self.severity {
Severity::Error => "error",
Severity::Warning => "warning",
},
"message": self.message,
"span": {
"file": self.path.as_ref().map(|p| display_path(p)),
"line": self.span.line,
"col": self.span.col,
},
"doc_anchor": self.doc_anchor,
"doc_quote": self.doc_quote,
"contract_ref": self.contract_ref.as_ref().map(|c| json!({
"unit": c.unit,
"kind": c.kind,
"name": c.name,
"declared": c.declared,
})),
"suggestion": self.suggestion,
})
}
}
/// Convenience for `anyhow` sites that already have a span.
@@ -106,4 +201,41 @@ mod tests {
assert!(!msg.contains(r"\\?\"));
assert!(msg.contains(r"E:\marqdo\x.mq.md:7:1:"));
}
#[test]
fn json_shape_defaults_nonempty_code_and_span() {
let d = Diagnostic::at(Path::new("x.mq.md"), Span::new(3, 5), "boom");
let v = d.to_json();
assert_eq!(v["code"], "marqdo.error");
assert_eq!(v["severity"], "error");
assert_eq!(v["span"]["line"], 3);
assert_eq!(v["span"]["col"], 5);
assert_eq!(v["span"]["file"], "x.mq.md");
}
#[test]
fn json_carries_doc_anchor_and_contract_ref() {
let d = Diagnostic::at(
Path::new("demo.mq.md"),
Span::new(12, 3),
"参数 `n` 期望 number,实际 text",
)
.with_code("contract.arg_mismatch")
.with_doc_anchor("demo.mq.md#L4-L7")
.with_doc_quote("| `n` | number | 输入值 |")
.with_suggestion("把实参改为数字")
.with_contract_ref(ContractRef {
unit: "加一".to_string(),
kind: "param".to_string(),
name: "n".to_string(),
declared: "number".to_string(),
});
let v = d.to_json();
assert_eq!(v["code"], "contract.arg_mismatch");
assert_eq!(v["doc_anchor"], "demo.mq.md#L4-L7");
assert_eq!(v["contract_ref"]["unit"], "加一");
assert_eq!(v["suggestion"], "把实参改为数字");
// Display 零回归
assert!(d.format_message().contains("demo.mq.md:12:3:"));
}
}
+84 -1
View File
@@ -324,6 +324,14 @@ impl Interpreter {
Stmt::Assign { name, value, span, .. } => {
self.current_span = *span;
let v = self.eval_expr(module, fun, env, value)?;
// 契约边界 3(T2.2):表绑定 vs 字段契约。
if let Some(c) = fun.var_contracts.get(name) {
if let Some(d) =
crate::contract::fields_diag(c, name, &v, self.path.as_deref(), *span)
{
return Err(d.into());
}
}
if self.trace {
let display = v.as_display();
emit_trace(
@@ -343,6 +351,14 @@ impl Interpreter {
Stmt::Return { value, span } => {
self.current_span = *span;
let v = self.eval_expr(module, fun, env, value)?;
// 契约边界 2(T2.2):返回值 vs 返回契约。
if let Some(c) = &fun.contract {
if let Some(d) =
crate::contract::return_diag(c, &fun.name, &v, self.path.as_deref(), *span)
{
return Err(d.into());
}
}
if self.trace {
let display = v.as_display();
emit_trace(
@@ -590,7 +606,38 @@ impl Interpreter {
Expr::Index { base, label } => {
let v = self.eval_expr(module, fun, env, base)?;
let key = self.resolve_index_key(module, fun, env, label)?;
builtin_footnote_get(&v, &key).map_err(|m| self.err(m))
// 契约边界 4(T2.2):字段访问 vs 字段契约——键存在性**先于**取值
// (契约诊断优先于运行时 `missing map key`)。
if let Expr::Var(name) = base.as_ref() {
if let Some(c) = fun.var_contracts.get(name) {
if let Some(d) = crate::contract::index_diag(
c,
name,
&key,
&Value::None,
self.path.as_deref(),
self.current_span,
) {
return Err(d.into());
}
}
}
let out = builtin_footnote_get(&v, &key).map_err(|m| self.err(m))?;
if let Expr::Var(name) = base.as_ref() {
if let Some(c) = fun.var_contracts.get(name) {
if let Some(d) = crate::contract::index_diag(
c,
name,
&key,
&out,
self.path.as_deref(),
self.current_span,
) {
return Err(d.into());
}
}
}
Ok(out)
}
Expr::Formula(e) => Ok(Value::Formula(e.clone())),
Expr::Code(c) => Ok(Value::Code(c.clone())),
@@ -820,6 +867,18 @@ impl Interpreter {
let bound = bind_function_args(self, module, fun, env, &target.params, &ev_args, false)
.map_err(|m| self.err(m))?;
// 契约边界 1(T2.2):调用实参 vs 形参契约。
if let Some(c) = &target.contract {
if let Some(d) = crate::contract::call_arg_diag(
c,
&target.name,
&bound,
self.path.as_deref(),
self.current_span,
) {
return Err(d.into());
}
}
let mut call_env = Env::new();
for (k, v) in bound {
call_env.set(k, v);
@@ -887,6 +946,18 @@ impl Interpreter {
)
.map_err(|m| self.err(m))?
};
// 契约边界 1(T2.2):库路径调用的实参 vs 形参契约。
if let Some(c) = &node.contract {
if let Some(d) = crate::contract::call_arg_diag(
c,
&display,
&bound,
self.path.as_deref(),
self.current_span,
) {
return Err(d.into());
}
}
let mut call_env = Env::new();
for (k, v) in bound {
call_env.set(k, v);
@@ -933,6 +1004,18 @@ impl Interpreter {
})?;
let bound = bind_function_args(self, module, fun, env, &target.params, ev_args, false)
.map_err(|m| self.err(m))?;
// 契约边界 1(T2.2):方法调用的实参 vs 形参契约。
if let Some(c) = &target.contract {
if let Some(d) = crate::contract::call_arg_diag(
c,
&target.name,
&bound,
self.path.as_deref(),
self.current_span,
) {
return Err(d.into());
}
}
let mut call_env = Env::new();
for (k, v) in bound {
call_env.set(k, v);
+4
View File
@@ -11,6 +11,8 @@ pub mod bytecode;
pub mod capture;
#[cfg(feature = "cli")]
pub mod catalog;
pub mod check;
pub mod contract;
pub mod debug;
pub mod diagnostics;
pub mod embedded_lib;
@@ -27,7 +29,9 @@ pub mod interp;
pub mod lex;
pub mod linalg_ops;
pub mod load;
pub mod mlsp;
pub mod parse;
pub mod repair;
pub mod value;
#[cfg(feature = "net-host")]
pub mod version_check;
+16 -3
View File
@@ -252,6 +252,20 @@ pub fn load_module_from_source(source: &str) -> Result<Module> {
load_module_from_source_inner(source, "<memory>", &mut visited)
}
/// 给错误打上文件标签,**保留**结构化诊断(错误出口唯一;AI/MLSP 面不许拍平成字符串)。
/// 无结构的错误退回 `{label}: {e}` 文本。
fn label_error(label: &str, e: anyhow::Error) -> anyhow::Error {
match crate::diagnostics::Diagnostic::find(&e).cloned() {
Some(mut d) => {
if d.path.is_none() {
d.path = Some(PathBuf::from(label));
}
d.into()
}
None => anyhow::anyhow!("{label}: {e}"),
}
}
fn load_module_from_source_inner(
source: &str,
label: &str,
@@ -263,7 +277,7 @@ fn load_module_from_source_inner(
}
let result = (|| {
let mut module = parse_source(source).map_err(|e| anyhow::anyhow!("{label}: {e}"))?;
let mut module = parse_source(source).map_err(|e| label_error(label, e))?;
let imports = module.imports.clone();
let mut import_modules = HashMap::new();
for imp in imports {
@@ -274,8 +288,7 @@ fn load_module_from_source_inner(
import_modules.insert(imp.bind, dep);
}
module.import_modules = import_modules;
crate::inherit::validate_inheritance(&module)
.map_err(|e| anyhow::anyhow!("{label}: {e}"))?;
crate::inherit::validate_inheritance(&module).map_err(|e| label_error(label, e))?;
Ok(module)
})();
+73 -4
View File
@@ -5,6 +5,7 @@ use anyhow::Result;
use clap::{Parser, Subcommand, ValueEnum};
use marqdo::catalog::{write_catalog, CatalogOptions};
use marqdo::diagnostics::{Diagnostic, Span};
use marqdo::ext_cli::{add_ext, list_ext, remove_ext};
use marqdo::input_feed::load_stdin_file;
use marqdo::view::{serve, serve_debug, write_static, DebugOptions, OutputOptions, ViewOptions};
@@ -64,7 +65,23 @@ enum Commands {
/// Write `# main` return value as JSON (used by file subtasks).
#[arg(long, value_name = "FILE")]
emit_result: Option<PathBuf>,
/// Emit diagnostics as JSON on stderr (machine-readable; AI/MLSP 面).
#[arg(long)]
json: bool,
},
/// Static contract cross-check (渐进式契约): drift, unknown types, misplaced tables
Check {
/// Program path (.mq.md)
#[arg(value_name = "FILE")]
file: PathBuf,
/// Emit one JSON diagnostic per line on stdout (machine-readable; AI/MLSP 面)
#[arg(long)]
json: bool,
},
/// MLSP for AI: line-delimited JSON on stdio (locate / syntax / validate / repair_targets / schema)
Mlsp,
/// Browse `.mq.md` structure + execution (live server or static output)
View {
#[command(subcommand)]
@@ -173,17 +190,31 @@ enum ViewAction {
}
fn main() -> ExitCode {
match try_main() {
let cli = Cli::parse();
let json_errors = matches!(
&cli.command,
Commands::Run { json: true, .. } | Commands::Check { json: true, .. }
);
match try_main(cli) {
Ok(code) => ExitCode::from(code as u8),
Err(err) => {
eprintln!("error: {err:#}");
if json_errors {
let diag = match err.downcast::<Diagnostic>() {
Ok(d) => d,
Err(e) => Diagnostic::find(&e).cloned().unwrap_or_else(|| {
Diagnostic::new(None, Span::new(0, 0), format!("{e:#}"))
}),
};
eprintln!("{}", diag.to_json());
} else {
eprintln!("error: {err:#}");
}
ExitCode::from(1)
}
}
}
fn try_main() -> Result<i32> {
let cli = Cli::parse();
fn try_main(cli: Cli) -> Result<i32> {
match cli.command {
Commands::Run {
file,
@@ -197,6 +228,7 @@ fn try_main() -> Result<i32> {
dump_all,
stdin_file,
emit_result,
json: _,
} => {
let path = file.unwrap_or_else(|| PathBuf::from("index.mq.md"));
let stdin_lines = match stdin_file {
@@ -229,6 +261,43 @@ fn try_main() -> Result<i32> {
marqdo::run_file(&path, &opts)?;
Ok(0)
}
Commands::Check { file, json } => {
let diags = marqdo::check::check_path(&file)?;
let mut errors = 0i32;
for d in &diags {
if matches!(d.severity, marqdo::diagnostics::Severity::Error) {
errors += 1;
}
if json {
println!("{}", d.to_json());
} else {
println!("{}", d.format_message());
}
}
if !json {
if diags.is_empty() {
println!("contract check OK: 无契约问题");
} else {
println!("contract check: {} 条诊断({} error)", diags.len(), errors);
}
}
Ok(errors.min(1))
}
Commands::Mlsp => {
use std::io::{BufRead, Write};
let stdin = std::io::stdin();
let stdout = std::io::stdout();
let mut out = stdout.lock();
for line in stdin.lock().lines() {
let line = line?;
if line.trim().is_empty() {
continue;
}
writeln!(out, "{}", marqdo::mlsp::handle_line(&line))?;
out.flush()?;
}
Ok(0)
}
Commands::View {
action,
path,
+392
View File
@@ -0,0 +1,392 @@
//! Marqdo Language Server for AI(MLSP)—— AI 的可查询工具面(T3.1/T3.2,T2.6 并入 `schema`)。
//!
//! 目标([three-problems.md](../../doc/roadmap/three-problems.md) §3):**AI 不必背 Marqdo
//! 语法细节**——把「记语法」换成「查工具」。语法唯一事实来源是 `parse::CORE_CONSTRUCTS`
//! (与 `doc/design/core-surface.md` 由 CI 守卫同步);本模块只加**检索别名**,不定义语法。
//!
//! 行分隔 JSON 协议:每行一个请求 `{"id":…,"method":…,"params":{…}}`,
//! 每行一个响应 `{"id":…,"ok":true,"result":{…}}` / `{"id":…,"ok":false,"error":{…}}`。
//!
//! | method | 作用 |
//! |--------|------|
//! | `locate` | 语法/符号定位:构造卡片,或定义位置 + 契约 |
//! | `syntax` | 语法问答:关键字/别名 → 构造卡片 |
//! | `validate` | 程序校验:结构化诊断数组(parse + 契约 check) |
//! | `repair_targets` | 修复靶点:错误 → **有界**修复目标(越界必拒,护栏) |
//! | `repair_apply` | 应用行编辑(全有或全无;越界 ⇒ `mlsp.repair_out_of_scope` abstain) |
//! | `schema` | 契约查询(T2.6):单元名 → 形参/返回/字段契约 |
use std::path::{Path, PathBuf};
use serde_json::{json, Value};
use crate::ast::{Function, Module};
use crate::check::check_module;
use crate::contract::{Contract, Ty};
use crate::diagnostics::Diagnostic;
use crate::load;
use crate::parse::CORE_CONSTRUCTS;
/// 行分隔 JSON:一行请求 → 一行响应(永不 panic;错误也是结构化 JSON)。
pub fn handle_line(line: &str) -> String {
let trimmed = line.trim();
let id = match serde_json::from_str::<Value>(trimmed) {
Ok(req) => req.get("id").cloned().unwrap_or(Value::Null),
Err(e) => {
return json!({
"id": null,
"ok": false,
"error": {"code": "mlsp.bad_request", "message": format!("请求不是合法 JSON: {e}")}
})
.to_string();
}
};
let req: Value = serde_json::from_str(trimmed).expect("already parsed");
match dispatch(&req) {
Ok(result) => json!({"id": id, "ok": true, "result": result}).to_string(),
Err(error) => json!({"id": id, "ok": false, "error": error}).to_string(),
}
}
fn dispatch(req: &Value) -> Result<Value, Value> {
let params = req.get("params").cloned().unwrap_or(json!({}));
match req.get("method").and_then(|m| m.as_str()) {
Some("locate") => locate(&params),
Some("syntax") => syntax(&params),
Some("validate") => validate(&params),
Some("repair_targets") => repair_targets(&params),
Some("repair_apply") => repair_apply(&params),
Some("schema") => schema(&params),
other => Err(err(
"mlsp.unknown_method",
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema"),
)),
}
}
fn err(code: &str, message: impl Into<String>) -> Value {
json!({"code": code, "message": message.into()})
}
// ---------- 构造卡片(语法唯一事实来源 = CORE_CONSTRUCTS) ----------
/// 检索别名(中/英关键字)——只做匹配,不定义语法。
const ALIASES: &[(&str, &[&str])] = &[
("narrative", &["叙述", "文字", "说明", "注释", "narrative", "prose"]),
("blank", &["空行", "blank"]),
("heading-unit", &["标题", "单元", "函数", "对象", "heading", "定义"]),
("call-line", &["调用", "call"]),
("branch-list", &["分支", "条件", "判断", "branch", "if"]),
("loop-list", &["循环", "遍历", "loop", "for", "while"]),
("param", &["参数", "形参", "param"]),
("table", &["表", "表格", "table", "集合", "数据"]),
("fence", &["代码块", "围栏", "fence", "公式", "code"]),
("hr", &["分隔线", "水平线", "hr"]),
("writeback", &["回写", "输出块", "writeback"]),
("ident", &["变量", "标识符", "ident", "名字"]),
("bold-code", &["粗体", "赋值", "语句", "bold", "执行"]),
("italic-return", &["返回", "return", "斜体"]),
("empty-return", &["空返回", "none", "结束", "副作用"]),
("link-index", &["取元", "索引", "index", "键", "行"]),
("bracket-call", &["修饰", "括号", "bracket", "开关参数"]),
("footnote-index", &["脚注", "footnote", "取列", "列"]),
("soft-emphasis", &["强调", "emphasis", "软强调"]),
];
/// core-surface.md 全文(与 `tests/core_surface.rs` 守卫同源)——卡片机械携带
/// 语义/戒律/样例**原文**,AI 一次查询即可自持,不必回读文档(three-problems.md §3.2「单构造戒律」)。
const SURFACE_MD: &str = include_str!("../doc/design/core-surface.md");
/// 机械提取 core-surface.md 清单行:`| \`id\` | 外形 | 语义 | 戒律 | 样例 |` →
///(语义, 戒律, 样例, 行原文);只读不改,卡片内容与文档永不漂移。
fn surface_row(id: &str) -> Option<(String, String, String, String)> {
for line in SURFACE_MD.lines() {
let t = line.trim();
if !t.starts_with('|') {
continue;
}
let cells: Vec<&str> = t.trim_matches('|').split('|').map(str::trim).collect();
if cells.len() != 5 {
continue;
}
let rid = cells[0].trim_matches('`');
if rid == id && !rid.is_empty() && !rid.contains(' ') && !rid.starts_with('-') {
return Some((
cells[2].to_string(),
cells[3].to_string(),
cells[4].to_string(),
t.to_string(),
));
}
}
None
}
fn card(id: &str) -> Value {
let form = CORE_CONSTRUCTS
.iter()
.find(|(cid, _)| *cid == id)
.map(|(_, f)| *f)
.unwrap_or("?");
let mut v = json!({
"id": id,
"form": form,
"manual": "doc/design/core-surface.md",
});
if let Some((semantics, rule, sample, quote)) = surface_row(id) {
v["semantics"] = semantics.into();
v["rule"] = rule.into();
v["sample"] = sample.into();
v["doc_quote"] = quote.into();
}
v
}
fn match_constructs(query: &str) -> Vec<Value> {
let q = query.trim().to_lowercase();
if q.is_empty() {
return ALIASES.iter().map(|(id, _)| card(id)).collect();
}
ALIASES
.iter()
.filter(|(_, keys)| {
keys.iter()
.any(|k| k.to_lowercase().contains(&q) || q.contains(&k.to_lowercase()))
})
.map(|(id, _)| card(id))
.collect()
}
fn syntax(params: &Value) -> Result<Value, Value> {
let query = params.get("query").and_then(|q| q.as_str()).unwrap_or("");
let cards = match_constructs(query);
if cards.is_empty() {
return Err(err(
"mlsp.no_match",
format!("没有匹配「{query}」的语法构造;换关键字(如 返回/表/调用)或省略 query 列出全部"),
));
}
Ok(json!({"cards": cards}))
}
fn locate(params: &Value) -> Result<Value, Value> {
if params.get("path").is_some() || params.get("source").is_some() {
let (module, path) = module_from_params(params)?;
let symbol = params
.get("symbol")
.and_then(|s| s.as_str())
.ok_or_else(|| err("mlsp.bad_request", "locate 定位符号需要 params.symbol"))?;
let fun = find_fn(&module, symbol)
.ok_or_else(|| err("mlsp.unknown_unit", format!("没有名为 `{symbol}` 的单元")))?;
return Ok(json!({
"unit": fun.name,
"level": fun.level,
"span": span_json(path.as_deref(), fun.span),
"params": fun.params.iter().map(|p| p.name.clone()).collect::<Vec<_>>(),
"contract": fun.contract.as_ref().map(|c| contract_json(c, path.as_deref())),
"manual": "doc/design/core-surface.md",
}));
}
Ok(json!({"cards": match_constructs(
params.get("query").and_then(|q| q.as_str()).unwrap_or("")
)}))
}
fn validate(params: &Value) -> Result<Value, Value> {
let (module, path) = module_from_params(params)?;
let mut diags = check_module(&module, path.as_deref());
diags.sort_by_key(|d| (d.span.line, d.span.col));
let jsons: Vec<Value> = diags.iter().map(|d| d.to_json()).collect();
let ok = !diags
.iter()
.any(|d| matches!(d.severity, crate::diagnostics::Severity::Error));
Ok(json!({"ok": ok, "diagnostics": jsons}))
}
/// 修复靶点(T3.3 护栏):锚点局部修复,**越界必拒**(禁止整文件重写/无关重构)。
fn repair_targets(params: &Value) -> Result<Value, Value> {
let code = params.get("code").and_then(|c| c.as_str()).unwrap_or("");
let anchor = params.get("doc_anchor").and_then(|a| a.as_str());
let suggestion = params.get("suggestion").and_then(|s| s.as_str());
if code.is_empty() {
return Err(err("mlsp.bad_request", "repair_targets 需要 params.code"));
}
Ok(json!({
"targets": [{
"code": code,
"doc_anchor": anchor,
"span": params.get("span").cloned().unwrap_or(Value::Null),
}],
"repair": {
"strategy": "anchored-local",
"bounded": true,
"max_attempts": 2,
"scope": "doc_anchor 所锚定的契约表/语句行",
"suggestion": suggestion,
"on_violation": "abstain",
"note": "只许改动锚定范围内的行;越界改动必须拒绝并报 abstain"
}
}))
}
/// 应用有界修复(T3.3):行编辑全有或全无;越界 ⇒ `mlsp.repair_out_of_scope`(abstain),源零字节不改。
fn repair_apply(params: &Value) -> Result<Value, Value> {
let source = source_text(params)?;
let ranges = params
.get("ranges")
.and_then(|r| r.as_array())
.ok_or_else(|| err("mlsp.bad_request", "repair_apply 需要 params.ranges([[起,止],…])"))?
.iter()
.map(|pair| {
let a = pair.as_array()?;
Some((a.first()?.as_u64()? as u32, a.get(1)?.as_u64()? as u32))
})
.collect::<Option<Vec<(u32, u32)>>>()
.ok_or_else(|| err("mlsp.bad_request", "ranges 必须是 [[起,止],…]"))?;
let mut edits = Vec::new();
let edit_list = params
.get("edits")
.and_then(|e| e.as_array())
.ok_or_else(|| err("mlsp.bad_request", "repair_apply 需要 params.edits"))?;
for e in edit_list {
let line = e
.get("line")
.and_then(|l| l.as_u64())
.ok_or_else(|| err("mlsp.bad_request", "edit 缺 line"))? as u32;
let text = e.get("text").and_then(|t| t.as_str()).unwrap_or("").to_string();
edits.push(match e.get("op").and_then(|o| o.as_str()) {
Some("replace") => crate::repair::Edit::Replace { line, text },
Some("delete") => crate::repair::Edit::Delete { line },
Some("insert") => crate::repair::Edit::InsertBefore { line, text },
other => {
return Err(err(
"mlsp.bad_request",
format!("未知编辑 op {other:?}(replace / delete / insert)"),
))
}
});
}
match crate::repair::apply_edits(&source, &ranges, &edits) {
Ok(new_source) => {
if params.get("write").and_then(|w| w.as_bool()).unwrap_or(false) {
let path = params
.get("path")
.and_then(|p| p.as_str())
.ok_or_else(|| err("mlsp.bad_request", "write=true 需要 params.path"))?;
std::fs::write(path, &new_source)
.map_err(|e| err("mlsp.io_error", format!("写回 {path} 失败: {e}")))?;
}
Ok(json!({"source": new_source, "edits_applied": edits.len()}))
}
Err(oos) => Err(json!({
"code": "mlsp.repair_out_of_scope",
"message": format!(
"修复越界(abstain):触及行 {:?} 不在靶点范围 {:?} 内;已拒绝全部编辑,源未改动",
oos.lines, oos.ranges
),
"lines": oos.lines,
"ranges": oos.ranges,
"on_violation": "abstain",
})),
}
}
/// 取待修源码(source 直给 / path 读取)。
fn source_text(params: &Value) -> Result<String, Value> {
if let Some(s) = params.get("source").and_then(|s| s.as_str()) {
return Ok(s.to_string());
}
let path = params
.get("path")
.and_then(|p| p.as_str())
.ok_or_else(|| err("mlsp.bad_request", "需要 params.source 或 params.path"))?;
std::fs::read_to_string(path)
.map_err(|e| err("mlsp.io_error", format!("读取 {path} 失败: {e}")))
}
/// 契约查询(T2.6):单元名 → 形参/返回/字段契约。
fn schema(params: &Value) -> Result<Value, Value> {
let (module, path) = module_from_params(params)?;
let unit = params
.get("unit")
.and_then(|u| u.as_str())
.ok_or_else(|| err("mlsp.bad_request", "schema 需要 params.unit"))?;
let fun = find_fn(&module, unit)
.ok_or_else(|| err("mlsp.unknown_unit", format!("没有名为 `{unit}` 的单元")))?;
let mut vars = serde_json::Map::new();
for (name, c) in &fun.var_contracts {
vars.insert(name.clone(), contract_json(c, path.as_deref()));
}
Ok(json!({
"unit": fun.name,
"contract": fun.contract.as_ref().map(|c| contract_json(c, path.as_deref())),
"vars": Value::Object(vars),
"params_inferred": fun.params.iter().map(|p| json!({
"name": p.name, "inferred": p.inferred
})).collect::<Vec<_>>(),
}))
}
// ---------- 公共小工具 ----------
fn module_from_params(params: &Value) -> Result<(Module, Option<PathBuf>), Value> {
if let Some(src) = params.get("source").and_then(|s| s.as_str()) {
let module = load::load_module_from_source(src)
.map_err(|e| diagnostic_err("mlsp.parse_error", &e))?;
return Ok((module, None));
}
let path = params
.get("path")
.and_then(|p| p.as_str())
.ok_or_else(|| err("mlsp.bad_request", "需要 params.path 或 params.source"))?;
let path = PathBuf::from(path);
let module = load::load_module(&path).map_err(|e| diagnostic_err("mlsp.parse_error", &e))?;
Ok((module, Some(path)))
}
/// 错误链里有结构化诊断就原样透出(AI/MLSP 面不许拍平)。
fn diagnostic_err(code: &str, e: &anyhow::Error) -> Value {
match Diagnostic::find(e) {
Some(d) => d.to_json(),
None => err(code, format!("{e:#}")),
}
}
fn find_fn<'a>(module: &'a Module, name: &str) -> Option<&'a Function> {
fn walk<'a>(funs: &'a [Function], name: &str) -> Option<&'a Function> {
funs.iter().find(|f| f.name == name).or_else(|| {
funs.iter()
.find_map(|f| walk(&f.children, name))
})
}
walk(&module.functions, name)
}
fn span_json(path: Option<&Path>, span: crate::diagnostics::Span) -> Value {
json!({
"file": path.map(|p| p.display().to_string()),
"line": span.line,
"col": span.col,
})
}
fn ty_json(ty: &Ty) -> Value {
json!(ty.name())
}
fn contract_json(c: &Contract, path: Option<&Path>) -> Value {
json!({
"params": c.params.iter().map(|p| json!({
"name": p.name, "type": ty_json(&p.ty), "desc": p.desc
})).collect::<Vec<_>>(),
"returns": c.returns.as_ref().map(|r| json!({
"type": ty_json(&r.ty), "desc": r.desc
})),
"fields": c.fields.iter().map(|f| json!({
"name": f.name, "type": ty_json(&f.ty), "nullable": f.nullable, "desc": f.desc
})).collect::<Vec<_>>(),
"doc_anchor": c.anchor(path),
})
}
+193
View File
@@ -212,6 +212,8 @@ impl<'a> Cursor<'a> {
children: Vec::new(),
base,
dead_binds: Vec::new(),
contract: None,
var_contracts: std::collections::HashMap::new(),
};
// Prose decls pending promotion (name → optional default text).
let mut prose_decls: Vec<(String, Option<String>)> = Vec::new();
@@ -342,6 +344,8 @@ impl<'a> Cursor<'a> {
}
}
// 契约提取(T2.1)必须在升参推断**之前**:契约表的单元不污染推断。
extract_function_contract(&mut fun, self.lines)?;
merge_inferred_params(&mut fun, &prose_decls)?;
Ok(fun)
}
@@ -1302,6 +1306,166 @@ fn stmt_from_italic_return(inner: &str, span: Span) -> Result<Stmt> {
/// Design §8.2: elevate only when an executable read cannot be satisfied by a prior
/// local assign that does not itself read the name (e.g. `score = > json.get …` is local;
/// `n = n + 1` still needs external `n`).
// ---------- 契约提取(T2.1 · 渐进式契约 / 标注类型) ----------
//
// 未绑定文档表 → 契约;**位置 + 形状**双重判定;在升参推断之前执行。
// 契约表从 body 移除(元数据永不执行、不污染升参推断);
// 非契约表(普通文档/数据表,含一切**绑定**表)原样保留 ⇒ 无契约文件零回归。
/// 从表头行起收集连续 `|` 行作为契约原文(诊断 `doc_quote`)。
fn table_quote(lines: &[ClassifiedLine], start_line: u32) -> (u32, Vec<String>) {
let Some(mut idx) = (0..lines.len()).find(|&i| lines[i].line_no == start_line) else {
return (start_line, Vec::new());
};
let mut quote = Vec::new();
let mut end = start_line;
while idx < lines.len() && lines[idx].text.trim().starts_with('|') {
quote.push(lines[idx].text.trim_end().to_string());
end = lines[idx].line_no;
idx += 1;
}
(end, quote)
}
/// 是否「字段契约形状」的未绑定文档表(紧邻判定的透明跳过用)。
fn is_fields_contract_stmt(stmt: &Stmt, lines: &[ClassifiedLine]) -> bool {
let Stmt::Expr { value: Expr::Map(pairs), span } = stmt else {
return false;
};
let (end_line, quote) = table_quote(lines, span.line);
matches!(
crate::contract::parse_contract_table(pairs, span.line, end_line, quote),
Some(Ok(ref c)) if !c.fields.is_empty()
)
}
/// 紧邻绑定名:跳过连续的字段契约表后,下一条是不是 `` `名` = `` 绑定。
fn next_binding_name(body: &[Stmt], start: usize, lines: &[ClassifiedLine]) -> Option<String> {
let mut j = start;
while j < body.len() && is_fields_contract_stmt(&body[j], lines) {
j += 1;
}
match body.get(j) {
Some(Stmt::Assign { name, .. }) => Some(name.clone()),
_ => None,
}
}
fn empty_like(piece: &crate::contract::Contract) -> crate::contract::Contract {
crate::contract::Contract {
params: Vec::new(),
returns: None,
fields: Vec::new(),
start_line: piece.start_line,
end_line: piece.end_line,
quote: Vec::new(),
}
}
/// 合并契约块;重复行/重复表 → `contract.duplicate` 诊断(防两份契约打架)。
fn merge_piece(
dst: &mut Option<crate::contract::Contract>,
piece: crate::contract::Contract,
unit: &str,
span: Span,
) -> Result<()> {
match dst {
None => *dst = Some(piece),
Some(slot) => {
if let Err(m) = crate::contract::merge_contract(slot, piece.clone()) {
return Err(piece
.diagnostic(
"contract.duplicate",
unit,
m,
"删除重复契约表,只保留一份".to_string(),
None,
span,
)
.into());
}
}
}
Ok(())
}
fn extract_function_contract(fun: &mut Function, lines: &[ClassifiedLine]) -> Result<()> {
let body = std::mem::take(&mut fun.body);
let mut fun_contract: Option<crate::contract::Contract> = None;
let mut var_contracts: std::collections::HashMap<String, crate::contract::Contract> =
std::collections::HashMap::new();
let mut keep: Vec<Stmt> = Vec::with_capacity(body.len());
// 「函数体首个可执行行之前」:未绑定表(Map/List 形状的 `Stmt::Expr`)不算可执行行。
let mut prefix_zone = true;
let mut i = 0usize;
while i < body.len() {
let stmt = &body[i];
let (pairs, span) = match stmt {
Stmt::Expr {
value: Expr::Map(pairs),
span,
} => (pairs, *span),
other => {
if !matches!(other, Stmt::Expr { value: Expr::List(_), .. }) {
prefix_zone = false;
}
keep.push(other.clone());
i += 1;
continue;
}
};
let (end_line, quote) = table_quote(lines, span.line);
let Some(parsed) = crate::contract::parse_contract_table(pairs, span.line, end_line, quote)
else {
// 非契约形状:普通文档/数据表 → 原样保留(P1 零回归的关键)。
keep.push(stmt.clone());
i += 1;
continue;
};
let piece = parsed?; // 契约形状但畸形 → 必产诊断(contract.malformed)
let is_fn_contract = !piece.params.is_empty() || piece.returns.is_some();
if is_fn_contract {
// 形参/返回表只在「首个可执行行之前」生效,否则视为普通表。
if !prefix_zone {
keep.push(stmt.clone());
i += 1;
continue;
}
merge_piece(&mut fun_contract, piece, &fun.name, span)?;
i += 1;
continue;
}
// 字段表:紧邻 `` `名` = `` 绑定之前 → 集合契约;对象体首成员前 → 对象字段契约。
if let Some(name) = next_binding_name(&body, i + 1, lines) {
let mut slot = Some(
var_contracts
.remove(&name)
.unwrap_or_else(|| empty_like(&piece)),
);
merge_piece(&mut slot, piece, &name, span)?;
var_contracts.insert(name, slot.unwrap());
i += 1;
continue;
}
if prefix_zone && fun.is_object() {
merge_piece(&mut fun_contract, piece, &fun.name, span)?;
i += 1;
continue;
}
// 不在允许位置 → 不是契约,原样保留。
keep.push(stmt.clone());
i += 1;
}
fun.body = keep;
fun.contract = fun_contract;
fun.var_contracts = var_contracts;
Ok(())
}
fn merge_inferred_params(
fun: &mut Function,
prose_decls: &[(String, Option<String>)],
@@ -1853,3 +2017,32 @@ Candidates may include lexical `score`.
}
}
}
/// 核心表面构造注册表(T1.3)——`(id, Markdown 外形)`。
///
/// **紧邻分类代码维护**;与 `doc/design/core-surface.md` 的 id 列强一致,
/// 由 `tests/core_surface.rs` 守卫:改动任一侧不同步 → CI 红。
/// 新增条目必须走 ADR(`doc/design/layers.md` 准入戒律)。
pub const CORE_CONSTRUCTS: &[(&str, &str)] = &[
// 行构造
("narrative", "无标记文字"),
("blank", "空行"),
("heading-unit", "# / ##"),
("call-line", ">"),
("branch-list", "1. 递增"),
("loop-list", "-"),
("param", "+ `名`"),
("table", "GFM 表"),
("fence", "```lang"),
("hr", "--- / ***"),
("writeback", "<!-- marqdo-out -->"),
// 内联标记
("ident", "`名`"),
("bold-code", "**…**"),
("italic-return", "*…*"),
("empty-return", "*None* / ****"),
("link-index", "[键](集合)"),
("bracket-call", "修饰… [函数] …"),
("footnote-index", "集合[^键]"),
("soft-emphasis", "*仅* / **说明**"),
];
+129
View File
@@ -0,0 +1,129 @@
//! 有界修复(T3.3 护栏的**机械执行面**):锚点局部修复,越界必拒(abstain),全有或全无。
//!
//! 修复循环三步:诊断(run/check)→ `mlsp repair_targets`(靶点 + 范围)→ `mlsp repair_apply`(改行)。
//! 护栏不是提示词愿望,而是这里代码强制的:
//!
//! - 只允许三种行编辑:`Replace` / `Delete` / `InsertBefore`;
//! - 被触碰的每一行都必须落在靶点范围内(`InsertBefore` 额外允许紧跟范围末尾追加),
//! 否则**整体拒绝**并报越界行清单——一个字节都不改(全有或全无);
//! - 应用结果交给调用方复验(`validate` / `run`)。
//!
//! 目标([three-problems.md](../../doc/roadmap/three-problems.md) §5.3):易锚定错误
//! ≥80% 修复率的同时,**越权范围的改动必拒**、失败后 abstain 而非乱改。
use std::collections::{HashMap, HashSet};
/// 一行编辑(1-based 行号)。
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Edit {
/// 把 `line` 整行换成 `text`。
Replace { line: u32, text: String },
/// 删除 `line`。
Delete { line: u32 },
/// 在 `line` **之前**插入 `text`(允许 `line == 范围末行 + 1`,即紧跟块尾追加)。
InsertBefore { line: u32, text: String },
}
impl Edit {
/// 被触碰的行(范围检查用)。
pub fn touched(&self) -> u32 {
match self {
Edit::Replace { line, .. } | Edit::Delete { line } | Edit::InsertBefore { line, .. } => {
*line
}
}
}
}
/// 越界拒绝(abstain):报告越界行与允许范围,源保持不变。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OutOfScope {
pub lines: Vec<u32>,
pub ranges: Vec<(u32, u32)>,
}
fn in_ranges(ranges: &[(u32, u32)], line: u32) -> bool {
ranges.iter().any(|(s, e)| line >= *s && line <= *e)
}
fn at_tail(ranges: &[(u32, u32)], line: u32) -> bool {
ranges.iter().any(|(_, e)| line == e + 1)
}
/// 全有或全无地应用行编辑。
///
/// - 任何被触碰行越出 `ranges`(或行号非法)⇒ [`Err`](越界清单),**源不变**;
/// - 同一行被多个编辑触碰时 `Delete` 优先于 `Replace`,同种后者覆盖前者。
pub fn apply_edits(
source: &str,
ranges: &[(u32, u32)],
edits: &[Edit],
) -> Result<String, OutOfScope> {
let lines: Vec<&str> = source.lines().collect();
let n_lines = lines.len() as u32;
// ---- 范围检查(先全体验完再动源) ----
let mut bad = Vec::new();
for e in edits {
let line = e.touched();
let legal = match e {
Edit::InsertBefore { .. } => {
(line >= 1 && line <= n_lines + 1)
&& (in_ranges(ranges, line) || at_tail(ranges, line))
}
_ => line >= 1 && line <= n_lines && in_ranges(ranges, line),
};
if !legal {
bad.push(line);
}
}
bad.sort_unstable();
bad.dedup();
if !bad.is_empty() {
return Err(OutOfScope {
lines: bad,
ranges: ranges.to_vec(),
});
}
// ---- 应用 ----
let mut replaced: HashMap<u32, String> = HashMap::new();
let mut deleted: HashSet<u32> = HashSet::new();
let mut inserts: HashMap<u32, Vec<String>> = HashMap::new();
for e in edits {
match e {
Edit::Replace { line, text } => {
replaced.insert(*line, text.clone());
}
Edit::Delete { line } => {
deleted.insert(*line);
replaced.remove(line); // Delete 优先
}
Edit::InsertBefore { line, text } => {
inserts.entry(*line).or_default().push(text.clone());
}
}
}
let trailing_newline = source.ends_with('\n');
let mut out: Vec<String> = Vec::with_capacity(lines.len() + inserts.len());
for (i, l) in lines.iter().enumerate() {
let n = (i + 1) as u32;
if let Some(texts) = inserts.get(&n) {
out.extend(texts.iter().cloned());
}
if deleted.contains(&n) {
continue;
}
out.push(replaced.get(&n).cloned().unwrap_or_else(|| l.to_string()));
}
if let Some(texts) = inserts.get(&(n_lines + 1)) {
out.extend(texts.iter().cloned());
}
let mut s = out.join("\n");
if trailing_newline {
s.push('\n');
}
Ok(s)
}
+117
View File
@@ -0,0 +1,117 @@
<!--
P4 实验 (b) 材料 · D 臂(全文档背诵组)上下文包。
来源:commit 199b5c5^ 的 `.cursor/skills/marqdo/SKILL.md`(背诵式「压缩操作手册」)
语言部分原样冻结(Markup→meaning / 最小程序 / 函数调用 / 语句分支 / 导入与内建面)。
只读实验材料——**请勿修改**(改了就不是同一个实验)。
-->
## Markup → meaning (v0.3)
| Marker | Meaning |
|--------|---------|
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
| `##` … `######` | **Function / method** (nesting by heading depth). |
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
| `修饰 [fn] args` | Bracket-marked call; leading words → `名=True` |
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `**…**` | **Code** (assign / call) — closing `**` touches last token; bare ids are variables; quote text literals |
| `*…*` | **Return value** — closing `*` touches last token; bare ids are variables |
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
| `- [item](coll)` | Foreach (unchanged) |
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
| Unmarked prose | Comment |
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
## Minimal program
```markdown
# main
> print text=Hello World!
```
Chinese builtins (same functions, no import):
```markdown
# main
> 打印 内容=你好
```
## Functions, calls, end-body
```markdown
# main
> greet who=Marqdo
## greet
+ `who`
> print text=Hello, `who`!
*None*
```
- Call: `> name key=value` or `> name value`.
- Nested helpers use deeper `#` (`##`, `###`, …).
- After a helper with only side effects, end with `*None*` / whole-line `**` / `****` when later lines must stay in the outer function. Lone `---` is only a thematic break (skipped).
- In bold assigns, prefer bare calls: `**摘要 = 结账摘要 …**` (omit `>`).
## Statements, returns, branches
```markdown
**x = 1**
**y = x + 2**
## add_one
+ `n`
*n + 1*
```
```markdown
**n = 0**
1. `n` > 0
> print text=positive
2. `n` < 0
> print text=negative
3. *
> print text=zero
```
## Frontmatter imports + stdlib
Imports use `import bind:target` (`导入` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
```markdown
---
title: example
import text:lib/text.mq.md
import clock:lib/time.mq.md
---
# main
**xs = > text.str_split s="a,b,c" sep=","**
> print text=`xs`
**t = > clock.now_unix**
```
- Import **English** or **Chinese** library file; call that file's API names via `lib.member` (do not mix languages).
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote.
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
@@ -0,0 +1,36 @@
# Task: claims_reserve_settle (insurance claims reserve)
Implement an **insurance claims reserve settlement** desk.
This is a **business-policy** pipeline (deductible, coinsurance, sublimit, recovery, floor), **not** an algorithms puzzle.
Use **integer arithmetic only**. Hardcode the demo inputs below and **print one integer**: the final reserve.
## Business requirements (authoritative)
1. **After deductible:** `after_deduct = claim - deductible`. If `after_deduct < 0`, set `after_deduct = 0`.
2. **Coinsurance share (insurer):** `coinsured = after_deduct * coinsure_pct / 100` (demo coinsure_pct = 80). Apply coinsurance **before** recovery.
3. **Sublimit cap:** `capped = coinsured` if `coinsured <= sublimit`, else `capped = sublimit` (never enlarge beyond coinsured).
4. **Recovery offset:** `reserved = capped - recovery`. If `reserved < 0`, set `reserved = 0`.
5. **Reserve floor:** if `reserved < reserve_floor`, set `reserved = reserve_floor`.
## Demo inputs (hardcode)
- `claim = 50000`
- `deductible = 5000`
- `coinsure_pct = 80`
- `sublimit = 30000`
- `recovery = 2000`
- `reserve_floor = 1000`
## Requirements
- Provide named helpers (or clear stages) for deductible, coinsurance, sublimit, recovery, and floor — not one opaque expression.
- Print only the final integer (no labels).
- Align to the **business requirements above**; do not invent alternate order or comparison directions.
## Expected output (self-check)
Exactly one line: `28000`
## Deliverable
Write the program as a Marqdo `.mq.md` file. Return the complete source in a single ```markdown fence — no prose outside the fence.
@@ -0,0 +1,42 @@
# Task: contract_milestone_pay (construction milestone payable)
Implement a **contract milestone payment** desk for an EPC / construction settlement.
This is a **business-policy** pipeline (retention, late penalty, change order, tax), **not** an algorithms puzzle.
Use **integer arithmetic only**. Hardcode the demo inputs below and **print one integer**: the final payable.
## Business requirements (authoritative)
1. **Earned value:** `earned = contract_value * progress_pct / 100`.
2. **Retention withhold:** `retention = earned * retain_pct / 100` (demo uses retain_pct = 5).
3. **Net after retention:** `net = earned - retention`.
4. **Late penalty:** if `days_late > grace_days` (grace_days = 7), set `penalty = net * late_rate / 100` (late_rate = 2); otherwise `penalty = 0`. Penalty is always computed from **`net`**, never from `earned`.
5. **After penalty:** `net2 = net - penalty`.
6. **Change order:** `taxed_base = net2 + change_order`. If `taxed_base < 0`, set `taxed_base = 0`.
7. **Tax:** `tax = taxed_base * tax_rate / 100` (tax_rate = 6).
8. **Payable:** `payable = taxed_base + tax`. If `payable < min_pay` (min_pay = 500), set `payable = min_pay`.
## Demo inputs (hardcode)
- `contract_value = 100000`
- `progress_pct = 40`
- `retain_pct = 5`
- `days_late = 10`
- `grace_days = 7`
- `late_rate = 2`
- `change_order = -2000`
- `tax_rate = 6`
- `min_pay = 500`
## Requirements
- Provide named helpers (or clear stages) for earned, retention, penalty, change+tax, and floor — not one opaque expression.
- Print only the final integer (no labels).
- Align to the **business requirements above**; do not invent alternate thresholds or penalty bases.
## Expected output (self-check)
Exactly one line: `37354`
## Deliverable
Write the program as a Marqdo `.mq.md` file. Return the complete source in a single ```markdown fence — no prose outside the fence.
+30
View File
@@ -0,0 +1,30 @@
# Task: qb_gcd (easy) — Greatest Common Divisor
Implement **Greatest Common Divisor** as a function named `gcd` in a Marqdo `.mq.md` program (Euclidean algorithm).
## Requirements
1. Function name `gcd`, taking two integer parameters and returning their greatest common divisor (non-negative; `gcd(0, 5)` is `5`).
2. In `# main`, hardcode the demo calls below and print each result on its own line — exactly four lines, no labels.
## Demo calls (hardcode)
- `gcd(48, 18)`
- `gcd(1071, 462)`
- `gcd(0, 5)`
- `gcd(17, 5)`
## Expected output (self-check)
Four lines:
```
6
21
5
1
```
## Deliverable
Write the program as a Marqdo `.mq.md` file. Return the complete source in a single ```markdown fence — no prose outside the fence.
+28
View File
@@ -0,0 +1,28 @@
# Task: qb_get_factors (hard) — Prime Factorization
Implement **prime factorization** as a function named `get_factors` in a Marqdo `.mq.md` program. The function takes an integer `n ≥ 2` and returns its prime factors in ascending order.
## Requirements
1. Function name `get_factors`.
2. In `# main`, hardcode the demo inputs below and print each result on its own line — factors joined by `*` with no spaces, exactly three lines, no labels.
## Demo inputs (hardcode)
- `12`
- `13`
- `60`
## Expected output (self-check)
Three lines:
```
2*2*3
13
2*2*3*5
```
## Deliverable
Write the program as a Marqdo `.mq.md` file. Return the complete source in a single ```markdown fence — no prose outside the fence.
+28
View File
@@ -0,0 +1,28 @@
# Task: qb_max_sublist_sum (hard) — Maximum Sublist Sum
Implement the **maximum contiguous sublist sum** as a function named `max_sublist_sum` in a Marqdo `.mq.md` program. The function takes a list of integers and returns the maximum sum of any contiguous sublist (at least one element).
## Requirements
1. Function name `max_sublist_sum`.
2. In `# main`, hardcode the demo inputs below and print each result on its own line — exactly three lines, no labels.
## Demo inputs (hardcode)
- `[-2, 1, -3, 4, -1, 2, 1, -5, 4]`
- `[1, 2, 3]`
- `[-3, -1, -2]`
## Expected output (self-check)
Three lines:
```
6
6
-1
```
## Deliverable
Write the program as a Marqdo `.mq.md` file. Return the complete source in a single ```markdown fence — no prose outside the fence.
+37
View File
@@ -0,0 +1,37 @@
# Task: vendor_po_gate (complex procurement business policy)
Implement a **vendor purchase-order payable gate** for an enterprise procurement desk.
This is a **business-policy** task (multi-rule approval economics), **not** an algorithms puzzle.
Use **integer arithmetic only**. Hardcode the demo inputs below and **print one integer**: the final payable.
## Business requirements (authoritative)
1. **Base line:** `base = qty * unit_cost`.
2. **Preferred-vendor discount:** if `vendor_tier >= 2` (tier-2+ preferred suppliers), set `amount = base * 97 / 100`; otherwise `amount = base`.
3. **Rush surcharge:** if `urgency == 1`, set `amount = amount + amount * 5 / 100`; otherwise keep `amount`.
4. **Budget clamp:** if `amount > budget_cap`, set `amount = budget_cap`.
5. **Compliance fee:** if `risk_flag == 1`, `fee = 80`; else `fee = 0`.
6. **Payable floor:** `payable = amount + fee`; if `payable < 200` then `payable = 200`.
## Demo inputs (hardcode)
- `qty = 20`
- `unit_cost = 40`
- `vendor_tier = 2`
- `urgency = 1`
- `budget_cap = 900`
- `risk_flag = 0`
## Requirements
- Provide named helpers (or clear stages) for discount, rush, budget clamp, fee, and assemble — not one opaque expression.
- Print only the final integer (no labels).
- Align the program to the **business requirements above**; do not invent alternate thresholds.
## Expected output (self-check)
Exactly one line: `814`
## Deliverable
Write the program as a Marqdo `.mq.md` file. Return the complete source in a single ```markdown fence — no prose outside the fence.
+585
View File
@@ -0,0 +1,585 @@
//! P4 实验 (b) 盲测——**查询式(Q)vs 全文档背诵(D)**
//! ([perf-validation.md](../../doc/roadmap/perf-validation.md) §2;three-problems.md §3.7 最终判据)。
//!
//! 唯一变量 = 语法知识获取方式:Q 臂只给硬规则 + 契约表形状 + MLSP 查询通道(≤3 次);
//! D 臂给硬规则 + 契约表形状 + 完整 markup 参考(`blind/docs-bundle.md`,背诵式全语法表)。
//! 两臂任务 / 提示词模板 / 修复回路(≤2 次)/ 模型完全相同。
//!
//! 判据:Q 功能通过率不劣于 D;首轮语法错误率 Q ≤ D;token Q ≤ 70% of D;修复轮次不升。
//! 执行:`OPENAI_MODEL=… cargo test --test blind_experiment -- --ignored --nocapture`。
use std::io::Write;
use marqdo::mlsp::handle_line;
use serde_json::{json, Value};
// ---------- 材料(冻结;只读实验材料) ----------
const DOCS_BUNDLE: &str = include_str!("blind/docs-bundle.md");
const T_CLAIMS: &str = include_str!("blind/tasks/claims_reserve_settle.md");
const T_MILESTONE: &str = include_str!("blind/tasks/contract_milestone_pay.md");
const T_VENDOR: &str = include_str!("blind/tasks/vendor_po_gate.md");
const T_GCD: &str = include_str!("blind/tasks/qb_gcd.md");
const T_KADANE: &str = include_str!("blind/tasks/qb_max_sublist_sum.md");
const T_FACTORS: &str = include_str!("blind/tasks/qb_get_factors.md");
struct Task {
id: &'static str,
desc: &'static str,
oracle: &'static str,
}
fn tasks() -> Vec<Task> {
vec![
Task { id: "claims_reserve_settle", desc: T_CLAIMS, oracle: "28000" },
Task { id: "contract_milestone_pay", desc: T_MILESTONE, oracle: "37354" },
Task { id: "vendor_po_gate", desc: T_VENDOR, oracle: "814" },
Task { id: "qb_gcd", desc: T_GCD, oracle: "6\n21\n5\n1" },
Task { id: "qb_max_sublist_sum", desc: T_KADANE, oracle: "6\n6\n-1" },
Task { id: "qb_get_factors", desc: T_FACTORS, oracle: "2*2*3\n13\n2*2*3*5" },
]
}
// ---------- 提示词(受控:硬规则与契约形状两臂同文) ----------
const HARD_RULES: &str = "\
## Hard rules (do not violate)\n\
1. **File suffix** must be `.mq.md`.\n\
2. **`**…**` = code** (assign / call). **`*…*` = return value**. Output is **not** either marker — use `> print text=…` / `**print text=\"…\"**` / `> 打印 内容=…`.\n\
3. **Prose:** unmarked narrative may contain `` `名` `` (declare/ref), inline `**code**`, and `*return*`. Soft Markdown emphasis that is not code-shaped is ignored. Dead `` `名` `` (never read) is OK and does not become a param.\n\
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**. Params: prefer prose `` `名` `` / `` `名`=默认 `` (inferred); `` + `名` `` still accepted.\n\
5. **Identifiers:** `` `名` `` in prose; inside `*…*` / `**…**`, bare ids are **variables**. **Text literals must be quoted** in bold/italic: `**print text=\"hi\"**`. Standalone `>` calls: bare words = text; vars need ticks: `` > str `n` ``.\n\
6. **Structure lines** (`#` `>` `+` `-` `|` `1.`) need not be wrapped in bold.\n\
7. **Paths:** In bare expressions `/` is division. In call args / defaults / table cells, unspaced `a/b` and quoted paths are text.\n\
8. Prefer ending side-effect-only bodies with `*None*` / `*无*` / whole-line `**` / `****` when the next lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped everywhere), not function end.\n\
9. **`ext/**` never calls `host_*`.**\n\
10. **Code-as-documentation:** prefer GFM tables for maps/lists; prefer named helpers over `json.set` / `json.append` chains.\n\
11. **Table element access has two spellings** — `[键](集合)` is the recommended one (e.g. `[name](`用户`)`, `[1](`xs`)`); footnote form `` `集合`[^键] `` is legacy-compat only.\n\
12. **Bracket-marked calls:** function name may be marked with `[函数名]`; bare words before `[` are boolean modifiers. `]` immediately followed by `(` is **index** `[key](coll)`, not a call.\n";
const CONTRACT_SHAPES: &str = "\
## 渐进式契约表(可选校验元数据)\n\
函数契约 = `##` 函数体内**首个可执行行之前**的未绑定文档表,两种列头:\n\
\n\
| 参数 | 类型 | 说明 |\n\
|------|------|------|\n\
| `n` | number | 输入值 |\n\
\n\
| 返回 | 类型 | 说明 |\n\
|------|------|------|\n\
| | number | 返回说明 |\n\
\n\
集合契约 = `` `名` = `` 绑定**之前**的 `| 字段 | 类型 | 可空 |` 表。\n\
对象契约 = `# 对象` 体内首个成员之前的 `| 字段 | 类型 |` 表。\n\
规则:**被绑定的表是数据,永不视为契约**;类型词表 = `text` / `number` / `bool` / `list` / `map` / `any` / 对象名;\n\
契约表一经出现即为完整声明(写全参数行,否则报 param_drift 警告)。\n";
const QUERY_PROTOCOL: &str = "\
## On-demand syntax queries(你的唯一语法来源)\n\
你**没有** Marqdo 语法参考。对任何不确定的语法细节,先查询再写码:单独输出一行\n\
`QUERY: <关键字>`(如 `QUERY: 返回`、`QUERY: 表`、`QUERY: 调用`),我会回给你对应构造卡片(语义/戒律/样例原文)。\n\
最多 3 次查询。**不要凭 Markdown/Python 习惯猜语法。**\n";
fn system_prompt(arm: &str) -> String {
let intro = "你是 Marqdo 语言(`.mq.md`:Markdown 标记即语法)的程序作者。写完整可运行程序(含 `# main`)。\n\n";
let mut s = String::from(intro);
s.push_str(HARD_RULES);
s.push('\n');
s.push_str(CONTRACT_SHAPES);
s.push('\n');
if arm == "docs" {
s.push_str("## Markup reference (v0.3, complete)\n\n");
s.push_str(DOCS_BUNDLE);
} else {
s.push_str(QUERY_PROTOCOL);
}
s
}
// ---------- LLM 接入(OpenAI 兼容;curl 免依赖;带 usage 计量) ----------
struct Llm {
key: String,
base: String,
model: String,
}
struct Reply {
text: String,
ptok: u32,
ctok: u32,
}
fn llm_cfg() -> Llm {
fn env_of(keys: &[&str]) -> Option<String> {
keys.iter()
.find_map(|k| std::env::var(k).ok())
.filter(|s| !s.is_empty())
}
let mut key = env_of(&["OPENAI_API_KEY", "MARQDO_LLM_API_KEY", "USTC_LLM_API_KEY"]);
let mut base = env_of(&["OPENAI_BASE_URL", "MARQDO_LLM_BASE_URL"]);
let mut model = env_of(&["OPENAI_MODEL", "MARQDO_LLM_MODEL"]);
let env_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join(".env");
if let Ok(txt) = std::fs::read_to_string(&env_path) {
for line in txt.lines() {
let line = line.trim();
if line.is_empty() || line.starts_with('#') {
continue;
}
if let Some((k, v)) = line.split_once('=') {
let v = v.trim().trim_matches('"').to_string();
match k.trim() {
"OPENAI_API_KEY" | "MARQDO_LLM_API_KEY" => key = key.or(Some(v)),
"OPENAI_BASE_URL" | "MARQDO_LLM_BASE_URL" => base = base.or(Some(v)),
"OPENAI_MODEL" | "MARQDO_LLM_MODEL" => model = model.or(Some(v)),
_ => {}
}
}
}
}
Llm {
key: key.expect("未找到 API 密钥:请设置 OPENAI_API_KEY 或仓库根 .env"),
base: base.unwrap_or_else(|| "https://llm.cflmy.cn/v1".to_string()),
model: model.unwrap_or_else(|| "cflmy".to_string()),
}
}
/// 多轮对话一次;空体/非 JSON/瞬时错误自动重试(容错重试),仍失败 ⇒ Err(基础设施失败)。
fn chat(llm: &Llm, msgs: &[(String, String)]) -> Result<Reply, String> {
let messages: Vec<Value> = msgs
.iter()
.map(|(r, c)| json!({"role": r, "content": c}))
.collect();
let url = format!("{}/chat/completions", llm.base.trim_end_matches('/'));
let auth = format!("Authorization: Bearer {}", llm.key);
let mut last = String::new();
let mut max_tokens = 12000u64; // reasoning 模型先思考后作答;截断时自适应加倍
for _ in 0..12 {
let req = json!({
"model": llm.model,
"temperature": 0,
"max_tokens": max_tokens,
"messages": messages
});
let mut child = std::process::Command::new("curl")
.args(["-sS", "-m", "180", "--retry", "2", "--retry-all-errors", "--retry-delay", "2", &url, "-H", &auth, "-H", "Content-Type: application/json", "--data-binary", "@-"])
.stdin(std::process::Stdio::piped())
.stdout(std::process::Stdio::piped())
.stderr(std::process::Stdio::piped())
.spawn()
.expect("启动 curl");
child
.stdin
.as_mut()
.unwrap()
.write_all(req.to_string().as_bytes())
.unwrap();
let out = child.wait_with_output().unwrap();
let text = String::from_utf8_lossy(&out.stdout).to_string();
match serde_json::from_str::<Value>(&text) {
Ok(v) if v["error"].is_object() => {
last = format!("LLM 报错: {}", v["error"]);
}
Ok(v) => {
let reply = v["choices"][0]["message"]["content"].as_str().unwrap_or("");
if !reply.is_empty() {
return Ok(Reply {
text: reply.to_string(),
ptok: v["usage"]["prompt_tokens"].as_u64().unwrap_or(0) as u32,
ctok: v["usage"]["completion_tokens"].as_u64().unwrap_or(0) as u32,
});
}
if v["choices"][0]["finish_reason"] == "length" && max_tokens < 32000 {
max_tokens *= 2; // reasoning 吃满额度 ⇒ 加倍后重试
last = format!("截断(finish=length,content 空),max_tokens 加倍至 {max_tokens}");
} else {
last = format!("响应缺 content: {}", truncate(&text, 120));
}
}
Err(_) => {
let err = String::from_utf8_lossy(&out.stderr).to_string();
last = format!("非 JSON / 空体: {} {}", truncate(&text, 80), truncate(&err, 80));
}
}
std::thread::sleep(std::time::Duration::from_secs(15));
}
Err(last)
}
fn truncate(s: &str, n: usize) -> String {
let t: String = s.chars().take(n).collect();
if s.chars().count() > n {
format!("{t}…")
} else {
t
}
}
// ---------- 程序提取 / 查询 / 执行 ----------
/// 从回复中提取程序源:优先含 `# main` 的围栏,其次最长围栏,再次裸文含 `# main`。
fn extract_program(reply: &str) -> Option<String> {
let mut best: Option<String> = None;
let mut rest = reply;
while let Some(a) = rest.find("```") {
let after = &rest[a + 3..];
let after = after.strip_prefix("markdown").unwrap_or(after);
let after = after.strip_prefix('\n').unwrap_or(after);
if let Some(b) = after.find("```") {
let block = &after[..b];
if block.contains("# main") {
return Some(dedent(block));
}
if best.as_ref().map(|s: &String| s.len() < block.len()).unwrap_or(true) {
best = Some(block.to_string());
}
rest = &after[b + 3..];
} else {
break;
}
}
if let Some(b) = best {
return Some(dedent(&b));
}
if reply.contains("# main") {
return Some(reply.trim().to_string());
}
None
}
fn dedent(block: &str) -> String {
let lines: Vec<&str> = block.lines().collect();
let indent = lines
.iter()
.filter(|l| !l.trim().is_empty())
.map(|l| l.len() - l.trim_start().len())
.min()
.unwrap_or(0);
let out: String = lines
.iter()
.map(|l| l.get(indent..).unwrap_or(l))
.collect::<Vec<_>>()
.join("\n");
format!("{}\n", out.trim_end())
}
/// QUERY 行 → 查询关键字列表。
fn extract_queries(reply: &str) -> Vec<String> {
reply
.lines()
.filter_map(|l| {
let t = l.trim();
let rest = t.strip_prefix("QUERY:").or_else(|| t.strip_prefix("QUERY:"))?;
let q = rest.trim();
if q.is_empty() {
None
} else {
Some(q.to_string())
}
})
.collect()
}
fn mlp_syntax(query: &str) -> String {
handle_line(&json!({"id": 1, "method": "syntax", "params": {"query": query}}).to_string())
}
fn validate_codes(src: &str) -> (bool, Vec<String>, String) {
let resp: Value =
serde_json::from_str(&handle_line(&json!({"id": 1, "method": "validate", "params": {"source": src}}).to_string()))
.expect("MLSP 响应必须是合法 JSON");
if resp["ok"] != true {
let code = resp["error"]["code"].as_str().unwrap_or("?").to_string();
return (false, vec![code], resp.to_string());
}
let diags = resp["result"]["diagnostics"].as_array().cloned().unwrap_or_default();
let codes: Vec<String> = diags
.iter()
.filter_map(|d| d["code"].as_str().map(String::from))
.collect();
(true, codes, diags.iter().map(|d| d.to_string()).collect::<Vec<_>>().join("\n"))
}
fn run_src(task_id: &str, arm: &str, src: &str) -> (i32, String, String) {
let p = std::env::temp_dir().join(format!(
"marqdo_blind_{}_{}_{}.mq.md",
std::process::id(),
arm,
task_id
));
std::fs::write(&p, src).unwrap();
let out = std::process::Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", p.to_str().unwrap()])
.output()
.expect("运行 marqdo");
let _ = std::fs::remove_file(&p);
(
out.status.code().unwrap_or(1),
String::from_utf8_lossy(&out.stdout).to_string(),
String::from_utf8_lossy(&out.stderr).to_string(),
)
}
// ---------- 单例执行 ----------
struct Outcome {
task: &'static str,
arm: &'static str,
result: String, // pass / load-fail / run-fail / wrong-output / infra
rounds: u32, // 通过前的修复次数(首轮通过 = 0)
first_load_fail: bool,
first_contract_diag: bool,
ptok: u32,
ctok: u32,
queries: u32,
note: String,
}
fn run_case(llm: &Llm, task: &Task, arm: &'static str) -> Outcome {
let mut msgs: Vec<(String, String)> = vec![
("system".into(), system_prompt(arm)),
("user".into(), format!("{}\n\n开始写程序。", task.desc)),
];
let (mut ptok, mut ctok) = (0u32, 0u32);
let mut queries = 0u32;
// 查询阶段(Q 臂协议;D 臂模型不被教导 QUERY,自然不会发)
let mut text = String::new();
let mut infra: Option<String> = None;
for _ in 0..6 {
match chat(llm, &msgs) {
Ok(r) => {
ptok += r.ptok;
ctok += r.ctok;
text = r.text;
}
Err(e) => {
infra = Some(e);
break;
}
}
if extract_program(&text).is_some() {
break; // 已带程序(即便附带 QUERY 行也直接用)
}
let qs = extract_queries(&text);
if qs.is_empty() {
break; // 无程序无查询 ⇒ 交给修复回路要程序
}
let mut answer = String::new();
for q in qs.iter().take(3usize.saturating_sub(queries as usize)) {
answer.push_str(&format!("QUERY {} → {}\n", q, mlp_syntax(q)));
queries += 1;
}
if answer.is_empty() {
answer.push_str("查询额度已用完(最多 3 次)。不要再查询,直接写完整程序。\n");
}
msgs.push(("assistant".into(), text.clone()));
msgs.push((
"user".into(),
format!("{answer}\n继续;完成后把完整程序放在**单个** ```markdown 围栏里。"),
));
}
if let Some(e) = infra {
return Outcome {
task: task.id,
arm,
result: "infra".into(),
rounds: 0,
first_load_fail: false,
first_contract_diag: false,
ptok,
ctok,
queries,
note: truncate(&e, 140),
};
}
let mut out = Outcome {
task: task.id,
arm,
result: "infra".into(),
rounds: 0,
first_load_fail: false,
first_contract_diag: false,
ptok,
ctok,
queries,
note: String::new(),
};
for attempt in 0..3u32 {
let src_opt = extract_program(&text);
let (load_ok, codes, diag_txt) = match &src_opt {
Some(src) => validate_codes(src),
None => (false, vec!["harness.no_program".to_string()], String::new()),
};
let contract_diag = codes.iter().any(|c| c.starts_with("contract."));
if attempt == 0 {
out.first_load_fail = src_opt.is_none() || !load_ok;
out.first_contract_diag = contract_diag;
}
let (code, stdout, stderr) = match &src_opt {
Some(src) => run_src(task.id, arm, src),
None => (
1,
String::new(),
"回复中没有 ```markdown 围栏程序(或不含 # main)。".to_string(),
),
};
if code == 0 && stdout.trim_end() == task.oracle.trim() {
out.result = "pass".into();
out.rounds = attempt;
out.note = format!("queries={queries}");
break;
}
out.result = if src_opt.is_none() || !load_ok {
"load-fail".into()
} else if code != 0 {
"run-fail".into()
} else {
"wrong-output".into()
};
out.note = if src_opt.is_none() {
format!("回复中无程序 | 开头: {}", truncate(&text.replace('\n', " "), 160))
} else {
truncate(&format!("{diag_txt} | stderr={stderr}"), 300)
};
if attempt == 2 {
break;
}
msgs.push(("assistant".into(), text.clone()));
msgs.push((
"user".into(),
format!(
"程序未通过。\nvalidate 诊断:\n{diag_txt}\n\n运行 stderr:\n{}\n\n运行 stdout:\n{}\n\n请修复问题,把**完整**程序放在**单个** ```markdown 围栏里(围栏内是纯 Marqdo 源码,含 `# main`)。",
truncate(&stderr, 500),
truncate(&stdout, 200)
),
));
match chat(llm, &msgs) {
Ok(r) => {
ptok += r.ptok;
ctok += r.ctok;
text = r.text;
}
Err(e) => {
out.note = format!("infra: {}", truncate(&e, 100));
break;
}
}
}
out.ptok = ptok;
out.ctok = ctok;
out
}
// ---------- 实验入口 ----------
#[test]
#[ignore]
fn exp_b_blind_query_vs_docs() {
let llm = llm_cfg();
let limit: usize = std::env::var("MARQDO_EXP_LIMIT")
.ok()
.and_then(|s| s.parse().ok())
.unwrap_or(usize::MAX);
let mut outs: Vec<Outcome> = Vec::new();
for arm in ["query", "docs"] {
for t in tasks().iter().take(limit) {
let o = run_case(&llm, t, arm);
eprintln!(
"[{}] {:<24} {:<12} rounds={} tok=({},{}) q={} | {}",
o.arm, o.task, o.result, o.rounds, o.ptok, o.ctok, o.queries, o.note
);
outs.push(o);
}
}
// 汇总(按判据口径:infra 例从比率中剔除并单列)
let mut md = String::new();
md.push_str(&format!(
"# 盲测实验(§5.2(b) 查询式 vs 全文档背诵)—— {}\n\n| | |\n|---|---|\n| 模型 | `{}` @ `{}` |\n| 样本 | 6 任务(业务 3 + QuixBugs 改写 3),oracle = stdout 精确匹配 |\n| 协议 | 系统提示词 = 硬规则 12 条 + 契约表三形状(两臂同文);**唯一变量 = 语法来源**:`query` 臂 MLSP 查询通道(≤3 次)vs `docs` 臂完整 markup 参考(背诵) |\n| 修复 | validate 诊断 + stderr 回喂,≤2 次修复;temperature=0,max_tokens=8000 |\n\n",
chrono_date(),
llm.model,
llm.base
));
md.push_str("## 汇总(判据:Q 通过率不劣于 D;首轮语法错误率 Q≤D;token Q≤70%%D;轮次不升)\n\n");
md.push_str("| 臂 | 通过(一轮) | 通过(最终≤3) | 首轮语法错误 | 首轮契约诊断 | 平均修复轮(过例) | token 合计(prompt+completion) | 弃权/基础设施 |\n");
md.push_str("|---|---|---|---|---|---|---|---|\n");
for arm in ["query", "docs"] {
let os: Vec<&Outcome> = outs.iter().filter(|o| o.arm == arm).collect();
let n = os.len();
let infra = os.iter().filter(|o| o.result == "infra").count();
let denom = n - infra;
let pass1 = os.iter().filter(|o| o.result == "pass" && o.rounds == 0).count();
let passf = os.iter().filter(|o| o.result == "pass").count();
let lf0 = os.iter().filter(|o| o.first_load_fail).count();
let cd0 = os.iter().filter(|o| o.first_contract_diag).count();
let rounds: f64 = {
let p: Vec<u32> = os.iter().filter(|o| o.result == "pass").map(|o| o.rounds).collect();
if p.is_empty() {
0.0
} else {
p.iter().sum::<u32>() as f64 / p.len() as f64
}
};
let ptok: u32 = os.iter().map(|o| o.ptok).sum();
let ctok: u32 = os.iter().map(|o| o.ctok).sum();
md.push_str(&format!(
"| {arm} | {pass1}/{denom} | {passf}/{denom} | {lf0}/{denom} | {cd0}/{denom} | {rounds:.2} | {}({}+{}) | {infra} |\n",
ptok + ctok,
ptok,
ctok
));
}
md.push_str("\n## 逐例\n\n| 例 | 臂 | 结果 | 修复轮 | 首轮语法错 | 首轮契约诊断 | token(p+c) | 查询 | 备注 |\n|---|---|---|---|---|---|---|---|---|\n");
for o in &outs {
md.push_str(&format!(
"| {} | {} | {} | {} | {} | {} | {}+{} | {} | {} |\n",
o.task,
o.arm,
o.result,
o.rounds,
if o.first_load_fail { "是" } else { "否" },
if o.first_contract_diag { "是" } else { "否" },
o.ptok,
o.ctok,
o.queries,
o.note.replace('|', "\\|").replace('\n', " ")
));
}
md.push_str("\n报告由 `tests/blind_experiment.rs` 生成;材料冻结于 `tests/blind/`(任务书 + docs-bundle),判据见 `doc/roadmap/perf-validation.md` §2。\n");
let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("doc/roadmap")
.join(format!("blind-experiment-{}-{}.md", chrono_date(), llm.model));
std::fs::write(&path, md).unwrap();
eprintln!("报告已写入 {}", path.display());
}
fn chrono_date() -> String {
if let Ok(d) = std::env::var("MARQDO_EXP_DATE") {
return d;
}
let secs = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_secs();
let (y, m, d) = civil_from_days((secs / 86400) as i64);
format!("{y:04}-{m:02}-{d:02}")
}
fn civil_from_days(z: i64) -> (i64, u32, u32) {
let z = z + 719468;
let era = if z >= 0 { z } else { z - 146096 } / 146097;
let doe = (z - era * 146097) as u64;
let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
let y = yoe as i64 + era * 400;
let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
let mp = (5 * doy + 2) / 153;
let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
(if m <= 2 { y + 1 } else { y }, m, d)
}
+288
View File
@@ -0,0 +1,288 @@
//! 修复循环测试共享件:MLSP 调用、统一诊断、金修复行编辑推导、golden 20 例。
//!
//! 被 `tests/repair_loop.rs`(确定性护栏/golden)与 `tests/repair_experiment.rs`
//! (模型在环实验)共用——同一批 20 例、同一套诊断与应用路径。
#![allow(dead_code)]
use marqdo::diagnostics::Diagnostic;
use marqdo::mlsp::handle_line;
use marqdo::repair::Edit;
use marqdo::{run_file, RunOptions};
use serde_json::{json, Value};
/// 调一次 MLSP(进程内)。
pub fn mcall(req: Value) -> Value {
serde_json::from_str(&handle_line(&req.to_string())).expect("MLSP 响应必须是合法 JSON")
}
/// 验证方式:运行期契约错走 run;静态错(check / parse)走 validate。
#[derive(Clone, Copy)]
pub enum Verify {
Run(&'static str),
Static(&'static str),
}
pub struct Case {
pub name: String,
pub broken: String,
pub gold: String,
pub verify: Verify,
}
impl Case {
pub fn code(&self) -> &'static str {
match self.verify {
Verify::Run(c) | Verify::Static(c) => c,
}
}
}
pub fn static_diags(src: &str) -> Vec<Value> {
let resp = mcall(json!({"id": 1, "method": "validate", "params": {"source": src}}));
if resp["ok"] == false {
return vec![resp["error"].clone()];
}
resp["result"]["diagnostics"]
.as_array()
.cloned()
.unwrap_or_default()
}
pub fn temp_path(tag: &str) -> std::path::PathBuf {
std::env::temp_dir().join(format!("marqdo_repair_{}_{}.mq.md", std::process::id(), tag))
}
/// 统一诊断入口:**干净 ⇒ 空数组**(Run 成功 / validate 零诊断)。
pub fn diagnose(verify: Verify, src: &str, tag: &str) -> Vec<Value> {
match verify {
Verify::Run(_) => {
let p = temp_path(tag);
std::fs::write(&p, src).unwrap();
match run_file(&p, &RunOptions::default()) {
Ok(_) => vec![],
Err(e) => vec![match Diagnostic::find(&e) {
Some(d) => d.to_json(),
None => json!({"code": "?", "message": format!("{e:#}")}),
}],
}
}
Verify::Static(_) => static_diags(src),
}
}
pub fn run_ok(src: &str, tag: &str) {
let p = temp_path(tag);
std::fs::write(&p, src).unwrap();
run_file(&p, &RunOptions::default()).expect("修复后必须运行成功");
let _ = std::fs::remove_file(&p);
}
/// 诊断 JSON → 靶点范围(span 行 + doc_anchor 的 L 范围)。
pub fn ranges_of(v: &Value) -> Vec<(u32, u32)> {
let mut rs = Vec::new();
if let Some(l) = v["span"]["line"].as_u64() {
rs.push((l as u32, l as u32));
}
if let Some(a) = v["doc_anchor"].as_str() {
if let Some(rest) = a.split('#').nth(1) {
if let Some(rest) = rest.strip_prefix('L') {
if let Some((s, e)) = rest.split_once("-L") {
if let (Ok(s), Ok(e)) = (s.parse(), e.parse()) {
rs.push((s, e));
}
}
}
}
}
rs
}
/// 金修复 → 行编辑(前缀/后缀 diff 自动推导)。
pub fn derive_edits(broken: &str, gold: &str) -> Vec<Edit> {
let b: Vec<&str> = broken.lines().collect();
let g: Vec<&str> = gold.lines().collect();
let mut p = 0usize;
while p < b.len() && p < g.len() && b[p] == g[p] {
p += 1;
}
let mut s = 0usize;
while s < b.len() - p && s < g.len() - p && b[b.len() - 1 - s] == g[g.len() - 1 - s] {
s += 1;
}
let mut edits = Vec::new();
for l in (p + 1)..=(b.len() - s) {
edits.push(Edit::Delete { line: l as u32 });
}
let at = (b.len() - s + 1) as u32;
for text in &g[p..(g.len() - s)] {
edits.push(Edit::InsertBefore {
line: at,
text: (*text).to_string(),
});
}
edits
}
/// 经 `mlsp repair_apply` 应用(护栏所在)。
pub fn apply_via_mlsp(src: &str, ranges: &[(u32, u32)], edits: &[Edit]) -> Value {
mcall(json!({
"id": 2,
"method": "repair_apply",
"params": {
"source": src,
"ranges": ranges.iter().map(|(s, e)| json!([s, e])).collect::<Vec<_>>(),
"edits": edits.iter().map(|e| match e {
Edit::Replace { line, text } => json!({"op": "replace", "line": line, "text": text}),
Edit::Delete { line } => json!({"op": "delete", "line": line}),
Edit::InsertBefore { line, text } => json!({"op": "insert", "line": line, "text": text}),
}).collect::<Vec<_>>(),
}
}))
}
/// golden 20 例(10 骨架 × 2 变体)。
pub fn cases() -> Vec<Case> {
let mut out: Vec<Case> = Vec::new();
let push = |out: &mut Vec<Case>, name: &str, broken: String, gold: String, verify: Verify| {
out.push(Case {
name: name.to_string(),
broken,
gold,
verify,
});
};
// 1–2 调用实参:数字形参传了文本(金修复改调用行 = span 侧)
for (v, lit, n) in [("a", "七", 7), ("b", "八", 8)] {
let broken = format!(
"# main\n\n> 加一 \"{lit}\"\n\n## 加一\n\n对于输入变量`n`,期望是数字。\n\n\
| 参数 | 类型 | 说明 |\n|------|------|------|\n| n | number | 输入值 |\n\n\
| 返回 | 类型 | 说明 |\n|------|------|------|\n| | number | 结果 |\n\n*n+1*\n"
);
let gold = broken.replace(&format!("> 加一 \"{lit}\""), &format!("> 加一 {n}"));
push(&mut out, &format!("arg-num-{v}"), broken, gold, Verify::Run("contract.arg_mismatch"));
}
// 3–4 调用实参:文本形参传了裸数(金修复加引号 = span 侧)
for (v, n) in [("a", 7), ("b", 8)] {
let broken = format!(
"# main\n\n> 转换 {n}\n\n## 转换\n\n对于输入变量`s`,期望是文本。\n\n\
| 参数 | 类型 | 说明 |\n|------|------|------|\n| s | text | 输入 |\n\n\
| 返回 | 类型 | 说明 |\n|------|------|------|\n| | text | 结果 |\n\n*s*\n"
);
let gold = broken.replace(&format!("> 转换 {n}"), &format!("> 转换 \"{n}\""));
push(&mut out, &format!("arg-text-{v}"), broken, gold, Verify::Run("contract.arg_mismatch"));
}
// 5–6 返回契约:返回文本却声明 number(金修复改契约行 = anchor 侧)
for (v, lit) in [("a", "七"), ("b", "你好")] {
let broken = format!(
"# main\n\n**结果 = > 转换 \"{lit}\"**\n*结果*\n\n## 转换\n\n对于输入变量`s`,期望是文本。\n\n\
| 参数 | 类型 | 说明 |\n|------|------|------|\n| s | text | 输入 |\n\n\
| 返回 | 类型 | 说明 |\n|------|------|------|\n| | number | 结果 |\n\n*s*\n"
);
let gold = broken.replace("| | number | 结果 |", "| | text | 结果 |");
push(&mut out, &format!("ret-type-{v}"), broken, gold, Verify::Run("contract.return_mismatch"));
}
// 7–8 字段类型:数据与字段契约不符(金修复改契约行 = anchor 侧)
{
let broken = "# main\n\n| 字段 | 类型 | 可空 |\n|------|------|------|\n| id | number | |\n| name | text | 是 |\n\n\
`用户` =\n| id | name |\n|------|------|\n| abc | 小明 |\n\n*`用户`[^name]*\n"
.to_string();
let gold = broken.replace("| id | number | |", "| id | text | |");
push(&mut out, "field-type-a", broken, gold, Verify::Run("contract.field_mismatch"));
let broken = "# main\n\n| 字段 | 类型 | 可空 |\n|------|------|------|\n| id | number | |\n| name | number | 是 |\n\n\
`用户` =\n| id | name |\n|------|------|\n| 1 | 小明 |\n\n*`用户`[^name]*\n"
.to_string();
let gold = broken.replace("| name | number | 是 |", "| name | text | 是 |");
push(&mut out, "field-type-b", broken, gold, Verify::Run("contract.field_mismatch"));
}
// 9–10 缺字段:数据没有契约要求的非空字段(金修复标可空 = anchor 侧)
{
let broken = "# main\n\n| 字段 | 类型 | 可空 |\n|------|------|------|\n| id | number | |\n| name | text | |\n\n\
`用户` =\n| id | qq |\n|------|------|\n| 1 | 5 |\n\n*`用户`[^id]*\n"
.to_string();
let gold = broken.replace("| name | text | |", "| name | text | 是 |");
push(&mut out, "field-nullable-a", broken, gold, Verify::Run("contract.field_mismatch"));
let broken = "# main\n\n| 字段 | 类型 | 可空 |\n|------|------|------|\n| id | number | |\n| name | text | |\n\n\
`用户` =\n| name | qq |\n|------|------|\n| 小明 | 5 |\n\n*`用户`[^name]*\n"
.to_string();
let gold = broken.replace("| id | number | |", "| id | number | 是 |");
push(&mut out, "field-nullable-b", broken, gold, Verify::Run("contract.field_mismatch"));
}
// 11–12 未知键:访问不在契约里的字段(金修复改索引键 = span 侧)
{
let broken = "# main\n\n| 字段 | 类型 | 可空 |\n|------|------|------|\n| id | number | |\n| name | text | 是 |\n\n\
`用户` =\n| id | name |\n|------|------|\n| 1 | 小明 |\n\n*`用户`[^email]*\n"
.to_string();
let gold = broken.replace("[^email]", "[^name]");
let broken_b = broken.replace("[^email]", "[^phone]");
let gold_b = broken_b.replace("[^phone]", "[^id]");
push(&mut out, "key-fix-a", broken, gold, Verify::Run("contract.unknown_key"));
push(&mut out, "key-fix-b", broken_b, gold_b, Verify::Run("contract.unknown_key"));
}
// 13–14 类型名拼错(金修复改正拼写 = anchor 侧)
for (v, typo, fix) in [("a", "nubmer", "number"), ("b", "txt", "text")] {
let broken = format!(
"# main\n\n## 加一\n\n对于输入变量`n`,执行加一。\n\n\
| 参数 | 类型 | 说明 |\n|------|------|------|\n| n | {typo} | 输入值 |\n\n*n+1*\n"
);
let gold = broken.replace(typo, fix);
push(&mut out, &format!("type-typo-{v}"), broken, gold, Verify::Static("contract.unknown_type"));
}
// 15–16 契约行名字错位(金修复改行名 = anchor 侧)
for (v, wrong) in [("a", "nn"), ("b", "nm")] {
let broken = format!(
"# main\n\n## 加一\n\n对于输入变量`n`,执行加一。\n\n\
| 参数 | 类型 | 说明 |\n|------|------|------|\n| {wrong} | number | 输入值 |\n\n*n+1*\n"
);
let gold = broken.replace(&format!("| {wrong} | number | 输入值 |"), "| n | number | 输入值 |");
push(&mut out, &format!("drift-rename-{v}"), broken, gold, Verify::Static("contract.param_drift"));
}
// 17–18 新升参未被契约覆盖(金修复补契约行 = anchor 侧,插入表尾)
for (v, extra) in [("a", "m"), ("b", "k")] {
let broken = format!(
"# main\n\n## 加一\n\n对于输入变量`n`,临时量`{extra}`。\n\n\
| 参数 | 类型 | 说明 |\n|------|------|------|\n| n | number | 输入值 |\n\n*n + {extra}*\n"
);
let gold = broken.replace(
"| n | number | 输入值 |",
&format!("| n | number | 输入值 |\n| {extra} | number | 临时 |"),
);
push(&mut out, &format!("drift-cover-{v}"), broken, gold, Verify::Static("contract.param_drift"));
}
// 19–20 两份契约打架(金修复删第二张表 = anchor 侧,纯删除)
{
let broken = "# main\n\n## 加一\n\n对于输入变量`n`,执行加一。\n\n\
| 参数 | 类型 | 说明 |\n|------|------|------|\n| n | number | 输入值 |\n\n\
| 参数 | 类型 | 说明 |\n|------|------|------|\n| n | number | 重复 |\n\n*n+1*\n"
.to_string();
let gold = broken.replace(
"\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| n | number | 重复 |",
"",
);
push(&mut out, "dup-delete-a", broken, gold, Verify::Static("contract.duplicate"));
let broken = "# main\n\n## 转换\n\n对于输入变量`s`,期望是文本。\n\n\
| 参数 | 类型 | 说明 |\n|------|------|------|\n| s | text | 输入 |\n\n\
| 返回 | 类型 | 说明 |\n|------|------|------|\n| | text | 结果 |\n\n\
| 返回 | 类型 | 说明 |\n|------|------|------|\n| | text | 同上 |\n\n*s*\n"
.to_string();
let gold = broken.replace(
"\n| 返回 | 类型 | 说明 |\n|------|------|------|\n| | text | 同上 |",
"",
);
push(&mut out, "dup-delete-b", broken, gold, Verify::Static("contract.duplicate"));
}
out
}
+279
View File
@@ -0,0 +1,279 @@
//! P4 实验 (c) 契约消融([perf-validation.md](../../doc/roadmap/perf-validation.md) §3):
//! 契约**只在有契约处**拦截错误值(P1:无契约 = 全动态),且不误报。
//!
//! 四边界(调用实参 / 返回 / 表绑定 / 字段访问)× 三形态:
//! ① 带契约 + 错值 → 必拦(`contract.*`);② 带契约 + 对值 → 零误报(跑通);
//! ③ 同程序**删契约表** + 错值 → 零 `contract.*`(动态语义原样——零回归)。
mod common;
use common::{diagnose, static_diags, Verify};
/// (边界, 形态源)——每个边界的三形态共享同一程序骨架,只动契约表与值。
struct Boundary {
name: &'static str,
wrong: &'static str, // ① 带契约 + 错值
code: &'static str, // ① 期望拦截码
right: &'static str, // ② 带契约 + 对值
bare: &'static str, // ③ 无契约 + 错值(同程序删契约表)
}
const ARG_WRONG: &str = "\
# main
**结果 = > 回显 \"7\"**
*结果*
## 回显
对于输入变量`n`,原样回显。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
*n*
";
const ARG_RIGHT: &str = "\
# main
**结果 = > 回显 3**
*结果*
## 回显
对于输入变量`n`,原样回显。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
*n*
";
const ARG_BARE: &str = "\
# main
**结果 = > 回显 \"7\"**
*结果*
## 回显
对于输入变量`n`,原样回显。
*n*
";
const RET_WRONG: &str = "\
# main
**结果 = > 整 \"hi\"**
*结果*
## 整
对于输入变量`n`,原样返回。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | any | 输入值 |
| 返回 | 类型 | 说明 |
|------|------|------|
| | number | 固定值 |
*n*
";
const RET_RIGHT: &str = "\
# main
**结果 = > 整 7**
*结果*
## 整
对于输入变量`n`,原样返回。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | any | 输入值 |
| 返回 | 类型 | 说明 |
|------|------|------|
| | number | 固定值 |
*n*
";
const RET_BARE: &str = "\
# main
**结果 = > 整 \"hi\"**
*结果*
## 整
对于输入变量`n`,原样返回。
*n*
";
const BIND_WRONG: &str = "\
# main
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | |
| name | text | 是 |
`用户` =
| id | name |
|------|------|
| abc | 小明 |
*[name](`用户`)*
";
const BIND_RIGHT: &str = "\
# main
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | |
| name | text | 是 |
`用户` =
| id | name |
|------|------|
| 1 | 小明 |
*[name](`用户`)*
";
const BIND_BARE: &str = "\
# main
`用户` =
| id | name |
|------|------|
| abc | 小明 |
*[name](`用户`)*
";
const KEY_WRONG: &str = "\
# main
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | |
| name | text | 是 |
`用户` =
| id | name |
|------|------|
| 1 | 小明 |
*[email](`用户`)*
";
const KEY_RIGHT: &str = "\
# main
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | |
| name | text | 是 |
`用户` =
| id | name |
|------|------|
| 1 | 小明 |
*[name](`用户`)*
";
const KEY_BARE: &str = "\
# main
`用户` =
| id | name |
|------|------|
| 1 | 小明 |
*[email](`用户`)*
";
fn boundaries() -> Vec<Boundary> {
vec![
Boundary { name: "call-arg", wrong: ARG_WRONG, code: "contract.arg_mismatch", right: ARG_RIGHT, bare: ARG_BARE },
Boundary { name: "return", wrong: RET_WRONG, code: "contract.return_mismatch", right: RET_RIGHT, bare: RET_BARE },
Boundary { name: "bind", wrong: BIND_WRONG, code: "contract.field_mismatch", right: BIND_RIGHT, bare: BIND_BARE },
Boundary { name: "key-access", wrong: KEY_WRONG, code: "contract.unknown_key", right: KEY_RIGHT, bare: KEY_BARE },
]
}
#[test]
fn ablation_interception_rate_100() {
let all = boundaries();
let total = all.len();
let mut caught = 0;
for b in &all {
let diags = diagnose(Verify::Run(b.code), b.wrong, &format!("abl_wrong_{}", b.name));
assert!(
diags.iter().any(|v| v["code"].as_str() == Some(b.code)),
"[{}] 带契约 + 错值必须被拦截(期望 {}): {:?}",
b.name, b.code, diags
);
caught += 1;
}
eprintln!("契约拦截率 = {caught}/{total} = 100%");
}
#[test]
fn ablation_false_positive_rate_0() {
let all = boundaries();
let total = all.len();
for b in &all {
let run_diags = diagnose(Verify::Run(""), b.right, &format!("abl_right_{}", b.name));
assert!(run_diags.is_empty(), "[{}] 对值被误报(运行): {:?}", b.name, run_diags);
let static_diags = static_diags(b.right);
assert!(
static_diags.is_empty(),
"[{}] 对值被误报(静态): {:?}",
b.name,
static_diags
);
}
eprintln!("契约误报率 = 0/{total} = 0%");
}
#[test]
fn ablation_no_contract_zero_regression() {
// 无契约路径:同程序删掉契约表 + 错值 ⇒ 零 contract.*(动态语义原样)。
// key-access 的动态语义是经典 `missing map key` 运行错——也必须是非契约诊断。
let all = boundaries();
let total = all.len();
for b in &all {
let diags = diagnose(Verify::Run(""), b.bare, &format!("abl_bare_{}", b.name));
assert!(
diags.iter().all(|v| !v["code"].as_str().unwrap_or("").starts_with("contract.")),
"[{}] 无契约路径出现契约诊断(P1 违例): {:?}",
b.name,
diags
);
if b.name == "key-access" {
// 动态基线:经典 missing map key 错误照旧(错误不是被契约吞掉或改写)。
assert!(
diags.iter().any(|v| v["message"]
.as_str()
.unwrap_or("")
.contains("missing map key")),
"key-access 动态基线应为经典 missing map key: {diags:?}"
);
}
}
eprintln!("无契约零回归 = {total}/{total}");
}
+319
View File
@@ -0,0 +1,319 @@
//! 渐进式契约(Phase 2 · T2.1–T2.5):契约提取、四边界运行时校验、`check` 静态互查。
//!
//! 验收对照 `doc/roadmap/three-problems-plan.md` 的完成定义:
//! P1 零回归(绑定表/普通文档表不吃)、P2 锚点诊断、契约漂移必产诊断。
//! 升参推断 = 散文声明(`` `名` ``)+ 体读取;契约提取在其**之前**执行。
use std::path::PathBuf;
use marqdo::ast::{Expr, Function, Module, Stmt};
use marqdo::check::check_module;
use marqdo::contract::Ty;
use marqdo::diagnostics::Diagnostic;
use marqdo::load::load_module_from_source;
use marqdo::{run_file, RunOptions};
fn fixture(name: &str) -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.join("tests/contracts")
.join(name)
}
fn find_fn<'a>(module: &'a Module, name: &str) -> &'a Function {
fn walk<'a>(funs: &'a [Function], name: &str) -> Option<&'a Function> {
for f in funs {
if f.name == name {
return Some(f);
}
if let Some(c) = walk(&f.children, name) {
return Some(c);
}
}
None
}
walk(&module.functions, name).unwrap_or_else(|| panic!("function `{name}` not found"))
}
/// anyhow 错误链 → 结构化 Diagnostic(load 的 context 包裹也不丢)。
fn structured(err: anyhow::Error) -> Diagnostic {
match err.downcast::<Diagnostic>() {
Ok(d) => d,
Err(e) => Diagnostic::find(&e)
.cloned()
.expect("错误必须是结构化 Diagnostic(AI/MLSP 面)"),
}
}
/// 运行夹具并断言失败的错误是结构化 Diagnostic。
fn run_err_code(name: &str) -> Diagnostic {
let err = run_file(&fixture(name), &RunOptions::default())
.expect_err(&format!("{name}: 期望契约报错,实际运行通过"));
structured(err)
}
// ---------- T2.1 提取 ----------
#[test]
fn extracts_param_and_return_contract() {
let src = "\
# main
## 加一
对于输入变量`n`,执行加一。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
| 返回 | 类型 | 说明 |
|------|------|------|
| | number | 加一结果 |
*n+1*
";
let module = load_module_from_source(src).unwrap();
let fun = find_fn(&module, "加一");
let c = fun.contract.as_ref().expect("应提取到函数契约");
assert_eq!(c.params.len(), 1);
assert_eq!(c.params[0].name, "n");
assert_eq!(c.params[0].ty, Ty::Number);
assert_eq!(c.params[0].desc, "输入值");
assert_eq!(c.returns.as_ref().unwrap().ty, Ty::Number);
// 契约表从 body 移除(元数据永不执行)
assert!(
!fun.body
.iter()
.any(|s| matches!(s, Stmt::Expr { value: Expr::Map(_), .. })),
"契约表应从 body 移除,剩余 body: {:?}", fun.body
);
// 升参(散文声明 `n` + 体读取)恰好覆盖契约
assert_eq!(
fun.params.iter().map(|p| p.name.as_str()).collect::<Vec<_>>(),
["n"]
);
// T2.4:锚点 + 原文行
assert_eq!(c.start_line, 7);
assert!(c.quote.iter().any(|q| q.contains("| 参数 | 类型 | 说明 |")));
}
#[test]
fn contract_cells_do_not_pollute_inference() {
// 契约说明列里的 `` `x` `` 只是文档提及——提取先于升参推断,`x` 不得被升参。
let src = "\
# main
## 加一
对于输入变量`n`,临时量`x`。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 与 `x` 相加 |
*n+1*
";
let module = load_module_from_source(src).unwrap();
let fun = find_fn(&module, "加一");
assert_eq!(fun.contract.as_ref().unwrap().params[0].name, "n");
assert_eq!(
fun.params.iter().map(|p| p.name.clone()).collect::<Vec<_>>(),
["n"],
"契约单元格的名不得被升参(提取先于推断)"
);
}
#[test]
fn bound_data_table_never_contract() {
// P1 零回归反例:**绑定**的 `字段|类型|可空` 数据表(web_db_migration 风格)不吃。
let module = load_module_from_source(
&std::fs::read_to_string(fixture("bound_data_table.mq.md")).unwrap(),
)
.unwrap();
let fun = find_fn(&module, "main");
assert!(fun.contract.is_none());
assert!(fun.var_contracts.is_empty());
run_file(&fixture("bound_data_table.mq.md"), &RunOptions::default())
.expect("绑定数据表必须照常运行");
}
#[test]
fn duplicate_contract_tables_diagnosed() {
// 两份契约打架 ⇒ 必产诊断(防漂移的一部分)。
let src = "\
# main
## 加一
对于输入变量`n`,执行加一。
| 参数 | 类型 |
|------|------|
| n | number |
| 参数 | 类型 |
|------|------|
| n | number |
*n+1*
";
let err = load_module_from_source(src).expect_err("重复契约必须报错");
let d = structured(err);
assert_eq!(d.to_json()["code"], "contract.duplicate");
}
// ---------- T2.2 四边界运行时校验 ----------
#[test]
fn call_arg_mismatch_reports_contract_diagnostic() {
let d = run_err_code("arg_mismatch.mq.md");
let v = d.to_json();
assert_eq!(v["code"], "contract.arg_mismatch");
assert!(
v["message"].as_str().unwrap().contains("参数 `n` 期望 number,实际 text"),
"{v}"
);
assert_eq!(v["severity"], "error");
// T2.4:锚点能回溯到出错表,且带原文行
assert!(v["doc_anchor"].as_str().unwrap().contains("#L"));
assert!(
v["doc_quote"].as_str().unwrap().contains("| 参数 | 类型 | 说明 |"),
"doc_quote 应含契约表原文: {v}"
);
// contract_ref 指向声明
assert!(
v["contract_ref"]["declared"].as_str().unwrap().contains("number"),
"{v}"
);
}
#[test]
fn return_mismatch_reports_contract_diagnostic() {
let d = run_err_code("return_mismatch.mq.md");
let v = d.to_json();
assert_eq!(v["code"], "contract.return_mismatch");
assert!(
v["message"].as_str().unwrap().contains("返回值期望 number,实际 text"),
"{v}"
);
assert!(v["doc_anchor"].as_str().unwrap().contains("#L"));
}
#[test]
fn field_mismatch_at_binding_reports_contract_diagnostic() {
// 字段表紧邻绑定之前 ⇒ 集合契约(T2.1);绑定时校验(边界 3)。
let module = load_module_from_source(
&std::fs::read_to_string(fixture("field_mismatch.mq.md")).unwrap(),
)
.unwrap();
let fun = find_fn(&module, "main");
let c = fun.var_contracts.get("用户").expect("应提取到集合契约");
assert_eq!(c.fields.len(), 2);
assert_eq!(c.fields[0].name, "id");
assert_eq!(c.fields[0].ty, Ty::Number);
assert!(!c.fields[0].nullable);
assert!(c.fields[1].nullable);
let d = run_err_code("field_mismatch.mq.md");
let v = d.to_json();
assert_eq!(v["code"], "contract.field_mismatch");
assert!(
v["doc_quote"].as_str().unwrap().contains("| 字段 | 类型 | 可空 |"),
"{v}"
);
}
#[test]
fn unknown_key_at_index_reports_contract_diagnostic() {
let d = run_err_code("unknown_key.mq.md");
let v = d.to_json();
assert_eq!(v["code"], "contract.unknown_key");
assert!(v["message"].as_str().unwrap().contains("email"), "{v}");
}
#[test]
fn ok_contract_runs_unchanged() {
run_file(&fixture("ok_contract.mq.md"), &RunOptions::default())
.expect("合法契约必须照常运行(P1/P2:不改变正常执行)");
}
// ---------- T2.3/T2.5 `check` 静态互查 ----------
#[test]
fn check_catches_param_drift() {
let src = "\
# main
## 加一
对于输入变量`n`,执行加一。
| 参数 | 类型 | 说明 |
|------|------|------|
| nn | number | 输入值 |
*n+1*
";
let module = load_module_from_source(src).unwrap();
let diags = check_module(&module, None);
let jsons: Vec<serde_json::Value> = diags.iter().map(|d| d.to_json()).collect();
assert!(
jsons.iter().any(|v| v["code"] == "contract.param_drift" && v["severity"] == "error"),
"契约行名字错位 ⇒ Error: {jsons:?}"
);
assert!(
jsons.iter().any(|v| v["code"] == "contract.param_drift" && v["severity"] == "warning"),
"新升参未被契约覆盖 ⇒ Warning: {jsons:?}"
);
}
#[test]
fn check_catches_unknown_type_with_suggestion() {
let src = "\
# main
## 加一
对于输入变量`n`,执行加一。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | nubmer | 输入值 |
*n+1*
";
let module = load_module_from_source(src).unwrap();
let diags = check_module(&module, None);
let d = diags
.iter()
.find(|d| d.to_json()["code"] == "contract.unknown_type")
.expect("未知类型名必产诊断(防 nubmer 拼错)");
let v = d.to_json();
assert!(
v["suggestion"].as_str().unwrap().contains("number"),
"应给出最近建议: {v}"
);
assert!(v["doc_anchor"].as_str().unwrap().contains("#L"));
}
#[test]
fn check_catches_misplaced_contract_table() {
let src = "\
# main
**x=1**
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
*x*
";
let module = load_module_from_source(src).unwrap();
let diags = check_module(&module, None);
assert!(
diags.iter().any(|d| d.to_json()["code"] == "contract.misplaced"),
"错位契约必产诊断: {:?}",
diags.iter().map(|d| d.to_json()).collect::<Vec<_>>()
);
}
+17
View File
@@ -0,0 +1,17 @@
# main
> 加一 "七"
## 加一
对于输入变量`n`,期望是数字。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
| 返回 | 类型 | 说明 |
|------|------|------|
| | number | 加一结果 |
*n+1*
+9
View File
@@ -0,0 +1,9 @@
# main
`列说明` =
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | |
| name | text | 是 |
*`列说明`[^字段]*
+13
View File
@@ -0,0 +1,13 @@
# main
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | |
| name | text | 是 |
`用户` =
| id | name |
|------|------|
| abc | 小明 |
*`用户`[^name]*
+18
View File
@@ -0,0 +1,18 @@
# main
**结果 = > 加一 3**
*结果*
## 加一
对于输入变量`n`,期望是数字。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
| 返回 | 类型 | 说明 |
|------|------|------|
| | number | 加一结果 |
*n+1*
+18
View File
@@ -0,0 +1,18 @@
# main
**结果 = > 转换 "七"**
*结果*
## 转换
对于输入变量`s`,期望是文本。
| 参数 | 类型 | 说明 |
|------|------|------|
| s | text | 输入 |
| 返回 | 类型 | 说明 |
|------|------|------|
| | number | 转换结果 |
*s*
+13
View File
@@ -0,0 +1,13 @@
# main
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | |
| name | text | 是 |
`用户` =
| id | name |
|------|------|
| 1 | 小明 |
*`用户`[^email]*
+96
View File
@@ -0,0 +1,96 @@
//! T1.3 核心表面守卫:`doc/design/core-surface.md` ⇄ `marqdo::parse::CORE_CONSTRUCTS`。
//!
//! 三重断言(反遮盖):
//! 1. 文档 id 列与代码注册表**双向集合相等**——改任一侧不同步 → 红;
//! 2. id 不重复;
//! 3. 每行「样例」列指向的文件真实存在——删/改名样例 → 红。
//!
//! 任何新增核心标记都必须同步文档 + 本注册表 + 样例(`doc/design/layers.md` 准入戒律)。
use marqdo::parse::CORE_CONSTRUCTS;
/// 解析构造表:首格为 kebab-case 反引号 id 的行 → `(id, 样例路径)`。
fn construct_rows(doc: &str) -> Vec<(String, String)> {
let mut rows = Vec::new();
for line in doc.lines() {
let line = line.trim();
if !line.starts_with("| `") {
continue;
}
let cells: Vec<&str> = line.split('|').collect();
if cells.len() < 3 {
continue;
}
let id = cells[1].trim().trim_matches('`').to_string();
if id.is_empty() || !id.chars().all(|c| c.is_ascii_lowercase() || c == '-') {
continue; // 非构造行(如 LineKind 大类名首字母大写,天然排除)
}
let sample = line
.split('`')
.find_map(|s| {
let s = s.trim();
if s.starts_with("tests/") || s.starts_with("examples/") {
Some(s.to_string())
} else {
None
}
})
.unwrap_or_default();
rows.push((id, sample));
}
rows
}
#[test]
fn core_surface_doc_matches_registry() {
let doc = include_str!("../doc/design/core-surface.md");
let mut doc_ids: Vec<String> = construct_rows(doc).into_iter().map(|(id, _)| id).collect();
doc_ids.sort();
let mut code_ids: Vec<String> = CORE_CONSTRUCTS
.iter()
.map(|(id, _)| (*id).to_string())
.collect();
code_ids.sort();
assert_eq!(
doc_ids, code_ids,
"core-surface.md 与 CORE_CONSTRUCTS 不一致(T1.3 守卫)"
);
}
#[test]
fn core_surface_ids_unique() {
let doc = include_str!("../doc/design/core-surface.md");
let ids: Vec<String> = construct_rows(doc).into_iter().map(|(id, _)| id).collect();
let mut sorted = ids.clone();
sorted.sort();
sorted.dedup();
assert_eq!(ids.len(), sorted.len(), "core-surface.md 存在重复 id");
let mut code: Vec<&str> = CORE_CONSTRUCTS.iter().map(|(id, _)| *id).collect();
let before = code.len();
code.sort_unstable();
code.dedup();
assert_eq!(before, code.len(), "CORE_CONSTRUCTS 存在重复 id");
}
#[test]
fn core_surface_samples_exist() {
let doc = include_str!("../doc/design/core-surface.md");
for (id, sample) in construct_rows(doc) {
assert!(!sample.is_empty(), "构造 `{id}` 缺「样例」列");
assert!(
std::path::Path::new(&sample).exists(),
"构造 `{id}` 样例不存在:{sample}"
);
}
}
#[test]
fn core_surface_registry_ids_are_kebab() {
for (id, shape) in CORE_CONSTRUCTS {
assert!(
id.chars().all(|c| c.is_ascii_lowercase() || c == '-'),
"CORE_CONSTRUCTS id 非 kebab:{id}"
);
assert!(!shape.is_empty(), "CORE_CONSTRUCTS `{id}` 缺外形描述");
}
}
+33
View File
@@ -0,0 +1,33 @@
//! T1.4 诊断机器面:真实错误路径产出的 Diagnostic 可序列化(`run --json` 出口)。
//!
//! 验收(three-problems-plan.md T1.4):人类文本零回归 + JSON `code`/`span` 非空。
use std::path::Path;
use marqdo::diagnostics::Diagnostic;
use marqdo::RunOptions;
#[test]
fn error_fixture_downcasts_and_serializes() {
let err = marqdo::run_file(
Path::new("tests/errors/div-zero.mq.md"),
&RunOptions::default(),
)
.expect_err("div-zero 应失败");
let diag: Diagnostic = err
.downcast()
.expect("错误应为 diagnostics::Diagnostic(机器面出口的前提)");
let v = diag.to_json();
assert_eq!(v["code"], "marqdo.error"); // code 分类细化随 Phase 2/3
assert_eq!(v["severity"], "error");
assert!(
v["span"]["line"].as_u64().unwrap() > 0,
"JSON span.line 必须非空"
);
assert!(v["message"]
.as_str()
.unwrap()
.contains("division by zero"));
// 人类文本零回归
assert!(diag.format_message().contains("division by zero"));
}
+254
View File
@@ -0,0 +1,254 @@
//! P4 实验 (d) 防漂移演练([perf-validation.md](../../doc/roadmap/perf-validation.md) §4):
//! **故意写错契约必报率 = 100%**——契约错了必被机器抓,绝不静默信任契约
//! (three-problems.md §2.8「故意写错契约的金样必红」)。
//!
//! 9 例故意漂移(类型 typo ×2 / 参数名漂移 / 错位表 / 重复表 / 四边界错值)
//! 必须全部产出 `contract.*` 诊断(静态或运行时);
//! 2 例负对照(被绑定的数据表 / 干净契约)**零误报**。
mod common;
use common::{diagnose, static_diags, Verify};
struct Drill {
name: &'static str,
src: &'static str,
/// true = 运行期诊断;false = 静态(mlsp validate = parse + check)。
runtime: bool,
code: &'static str,
}
/// 类型 typo(参数表 `nubmer`)→ 静态 `contract.unknown_type`。
const SRC_TYPO_PARAM: &str = "\
# main
## 加一
对于输入变量`n`,执行加一。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | nubmer | 输入值 |
*n+1*
";
/// 类型 typo(字段表未知对象名 `巨龙`)→ 静态 `contract.unknown_type`。
const SRC_TYPO_FIELD: &str = "\
# main
| 字段 | 类型 | 可空 |
|------|------|------|
| id | 巨龙 | |
`用户` =
| id |
|------|
| 1 |
*[id](`用户`)*
";
/// 契约参数名 ≠ 升参名(`nn` vs `n`)→ 静态 `contract.param_drift`。
const SRC_PARAM_DRIFT: &str = "\
# main
## 加一
对于输入变量`n`,执行加一。
| 参数 | 类型 | 说明 |
|------|------|------|
| nn | number | 输入值 |
*n+1*
";
/// 错位契约表(出现在可执行语句之后)→ 静态 `contract.misplaced`。
const SRC_MISPLACED: &str = "\
# main
**x=1**
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
*x*
";
/// 重复契约表(两份参数表打架)→ 装载期 `contract.duplicate`。
const SRC_DUPLICATE: &str = "\
# main
## 加一
对于输入变量`n`,执行加一。
| 参数 | 类型 |
|------|------|
| n | number |
| 参数 | 类型 |
|------|------|
| n | number |
*n+1*
";
/// 实参越约(参数契约 number,实参 text)→ 运行期 `contract.arg_mismatch`。
const SRC_ARG: &str = "\
# main
**结果 = > 回显 \"7\"**
*结果*
## 回显
对于输入变量`n`,原样回显。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
*n*
";
/// 返回越约(返回契约 number,实际返回 text)→ 运行期 `contract.return_mismatch`。
const SRC_RETURN: &str = "\
# main
**结果 = > 整 \"hi\"**
*结果*
## 整
对于输入变量`n`,原样返回。
| 返回 | 类型 | 说明 |
|------|------|------|
| | number | 固定值 |
*n*
";
/// 表绑定越约(字段 id 契约 number,单元格 abc)→ 运行期 `contract.field_mismatch`。
const SRC_FIELD: &str = "\
# main
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | |
| name | text | 是 |
`用户` =
| id | name |
|------|------|
| abc | 小明 |
*[name](`用户`)*
";
/// 缺键访问(契约有 email,集合没有)→ 运行期 `contract.unknown_key`。
const SRC_UNKNOWN_KEY: &str = "\
# main
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | |
| name | text | 是 |
`用户` =
| id | name |
|------|------|
| 1 | 小明 |
*[email](`用户`)*
";
/// 负对照 1:**被绑定**的 `字段|类型|可空` 数据表(web_db_migration 式)= 数据,不是契约。
const SRC_BOUND_DATA: &str = "\
# main
`列说明` =
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | |
| name | text | 是 |
*[字段]([1](`列说明`))*
";
/// 负对照 2:干净契约 + 对值。
const SRC_OK: &str = "\
# main
**结果 = > 加一 3**
*结果*
## 加一
对于输入变量`n`,期望是数字。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
| 返回 | 类型 | 说明 |
|------|------|------|
| | number | 加一结果 |
*n+1*
";
fn drills() -> Vec<Drill> {
vec![
Drill { name: "type-typo-param", src: SRC_TYPO_PARAM, runtime: false, code: "contract.unknown_type" },
Drill { name: "type-typo-field", src: SRC_TYPO_FIELD, runtime: false, code: "contract.unknown_type" },
Drill { name: "param-name-drift", src: SRC_PARAM_DRIFT, runtime: false, code: "contract.param_drift" },
Drill { name: "misplaced-table", src: SRC_MISPLACED, runtime: false, code: "contract.misplaced" },
Drill { name: "duplicate-table", src: SRC_DUPLICATE, runtime: true, code: "contract.duplicate" },
Drill { name: "arg-mismatch", src: SRC_ARG, runtime: true, code: "contract.arg_mismatch" },
Drill { name: "return-mismatch", src: SRC_RETURN, runtime: true, code: "contract.return_mismatch" },
Drill { name: "field-mismatch", src: SRC_FIELD, runtime: true, code: "contract.field_mismatch" },
Drill { name: "unknown-key", src: SRC_UNKNOWN_KEY, runtime: true, code: "contract.unknown_key" },
]
}
#[test]
fn drift_cases_all_reported() {
let all = drills();
let total = all.len();
let mut caught = 0;
for d in &all {
let diags = if d.runtime {
diagnose(Verify::Run(d.code), d.src, &format!("drift_{}", d.name))
} else {
static_diags(d.src)
};
let hit = diags.iter().any(|v| v["code"].as_str() == Some(d.code));
assert!(
hit,
"[{}] 故意写错的契约必须被诊断(期望 {}): {:?}",
d.name, d.code, diags
);
caught += 1;
}
eprintln!("防漂移必报率 = {caught}/{total} = 100%");
}
#[test]
fn negative_controls_zero_false_positives() {
// 1. 被绑定的 `字段|类型|可空` 数据表 = 数据(web_db_migration 式)——绝不能被当契约吃掉。
let diags = diagnose(Verify::Run(""), SRC_BOUND_DATA, "drill_neg_bound");
assert!(
diags.iter().all(|v| !v["code"].as_str().unwrap_or("").starts_with("contract.")),
"绑定数据表被误当契约: {diags:?}"
);
// 2. 干净契约 + 对值 ⇒ 静态零诊断、运行零诊断。
let diags = static_diags(SRC_OK);
assert!(diags.is_empty(), "干净契约被误报(静态): {diags:?}");
let diags = diagnose(Verify::Run(""), SRC_OK, "drill_neg_ok");
assert!(diags.is_empty(), "干净契约被误报(运行): {diags:?}");
eprintln!("负对照误报 = 0/2 = 0%");
}
+131
View File
@@ -0,0 +1,131 @@
//! MLSP for AI(T3.1/T3.2 + T2.6):`locate` / `syntax` / `validate` / `repair_targets` / `schema`。
//!
//! 验收对照 `doc/roadmap/three-problems-plan.md` Phase 3:
//! AI 不必背语法细节(syntax/locate 可查)、schema 可导出、修复靶点有界(越界必拒)。
use marqdo::mlsp::handle_line;
fn call(req: &str) -> serde_json::Value {
serde_json::from_str(&handle_line(req)).expect("MLSP 响应必须是合法 JSON")
}
#[test]
fn syntax_query_returns_construct_cards() {
let resp = call(r#"{"id":1,"method":"syntax","params":{"query":"返回"}}"#);
assert_eq!(resp["ok"], true, "{resp}");
let ids: Vec<&str> = resp["result"]["cards"]
.as_array()
.unwrap()
.iter()
.map(|c| c["id"].as_str().unwrap())
.collect();
assert!(ids.contains(&"italic-return"), "「返回」应命中斜体返回卡片: {resp}");
assert!(resp["result"]["cards"][0]["manual"]
.as_str()
.unwrap()
.contains("core-surface"));
}
#[test]
fn syntax_unknown_query_structured_error() {
let resp = call(r#"{"id":2,"method":"syntax","params":{"query":"量子纠缠语法"}}"#);
assert_eq!(resp["ok"], false);
assert_eq!(resp["error"]["code"], "mlsp.no_match");
}
#[test]
fn syntax_cards_carry_rule_text_self_sufficient() {
// 「AI 不必学语法」的前提:卡片自带语义/戒律/样例原文(不必回读文档),
// 且空查询列出全部核心构造(three-problems.md §3.2「单构造戒律」)。
let resp = call(r#"{"id":9,"method":"syntax","params":{}}"#);
assert_eq!(resp["ok"], true, "{resp}");
let cards = resp["result"]["cards"].as_array().unwrap();
assert_eq!(
cards.len(),
marqdo::parse::CORE_CONSTRUCTS.len(),
"空查询应列出全部核心构造: {resp}"
);
for c in cards {
assert!(
c["rule"].as_str().unwrap_or("").len() > 2,
"卡片缺戒律原文(不可自持): {c}"
);
assert!(
c["doc_quote"].as_str().unwrap_or("").starts_with('|'),
"卡片缺行原文: {c}"
);
assert!(
!c["semantics"].as_str().unwrap_or("").is_empty(),
"卡片缺语义: {c}"
);
}
}
#[test]
fn locate_symbol_returns_span_and_contract() {
let src = "# main\n\n## 加一\n\n对于输入变量`n`,执行加一。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| n | number | 输入值 |\n\n*n+1*\n";
let req = serde_json::json!({"id":3,"method":"locate","params":{"source": src, "symbol": "加一"}});
let resp = call(&req.to_string());
assert_eq!(resp["ok"], true, "{resp}");
assert_eq!(resp["result"]["unit"], "加一");
assert_eq!(resp["result"]["contract"]["params"][0]["type"], "number");
assert!(resp["result"]["span"]["line"].as_u64().unwrap() >= 1);
}
#[test]
fn validate_reports_contract_drift() {
let src = "# main\n\n## 加一\n\n对于输入变量`n`,执行加一。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| nn | number | 输入值 |\n\n*n+1*\n";
let req = serde_json::json!({"id":4,"method":"validate","params":{"source": src}});
let resp = call(&req.to_string());
assert_eq!(resp["ok"], true, "{resp}");
assert_eq!(resp["result"]["ok"], false, "漂移必须让 validate 不通过: {resp}");
let codes: Vec<&str> = resp["result"]["diagnostics"]
.as_array()
.unwrap()
.iter()
.map(|d| d["code"].as_str().unwrap())
.collect();
assert!(codes.contains(&"contract.param_drift"), "{resp}");
}
#[test]
fn schema_exports_progressive_contract() {
let req = serde_json::json!({
"id": 5,
"method": "schema",
"params": {"path": concat!(env!("CARGO_MANIFEST_DIR"), "/tests/contracts/ok_contract.mq.md"), "unit": "加一"}
});
let resp = call(&req.to_string());
assert_eq!(resp["ok"], true, "{resp}");
assert_eq!(resp["result"]["contract"]["params"][0]["name"], "n");
assert_eq!(resp["result"]["contract"]["params"][0]["type"], "number");
assert_eq!(resp["result"]["contract"]["returns"]["type"], "number");
assert!(resp["result"]["contract"]["doc_anchor"]
.as_str()
.unwrap()
.contains("#L"));
}
#[test]
fn repair_targets_are_bounded() {
let resp = call(
r#"{"id":6,"method":"repair_targets","params":{"code":"contract.arg_mismatch","doc_anchor":"a.mq.md#L9-L15","suggestion":"把实参改为 number"}}"#,
);
assert_eq!(resp["ok"], true, "{resp}");
let repair = &resp["result"]["repair"];
assert_eq!(repair["strategy"], "anchored-local");
assert_eq!(repair["bounded"], true);
assert_eq!(repair["on_violation"], "abstain");
assert_eq!(resp["result"]["targets"][0]["doc_anchor"], "a.mq.md#L9-L15");
}
#[test]
fn unknown_method_and_bad_json_are_structured() {
let resp = call(r#"{"id":7,"method":"divine","params":{}}"#);
assert_eq!(resp["ok"], false);
assert_eq!(resp["error"]["code"], "mlsp.unknown_method");
let resp = call("not json at all");
assert_eq!(resp["ok"], false);
assert_eq!(resp["error"]["code"], "mlsp.bad_request");
}
+544
View File
@@ -0,0 +1,544 @@
//! 模型在环实验 · three-problems.md §5.2(a):**锚点修复**(带 `doc_anchor` 的诊断 vs 去锚诊断)。
//!
//! 本实验同时是新功能面(`validate` / `repair_targets` / `repair_apply` 护栏)的**真实消费者**:
//!
//! ```text
//! 诊断 → repair_targets(靶点 + max_attempts=2 + abstain)→ 模型生成行编辑
//! → repair_apply(越界必拒)→ 复验(run / validate)→(≤2 轮)
//! ```
//!
//! 运行(需要 `.env` 或 `OPENAI_API_KEY`,默认 `llm.cflmy.cn/v1` + 模型 `cflmy`):
//!
//! ```bash
//! cargo test --test repair_experiment -- --ignored --nocapture
//! MARQDO_EXP_LIMIT=3 cargo test --test repair_experiment -- --ignored --nocapture # 冒烟
//! ```
//!
//! 报告写入 `doc/roadmap/repair-experiment-<日期>.md`。
mod common;
use common::*;
use marqdo::repair::Edit;
use serde_json::{json, Value};
use std::io::Write;
use std::sync::Mutex;
// ---------- LLM 接入(OpenAI 兼容;curl 免依赖) ----------
struct Llm {
key: String,
base: String,
model: String,
}
fn llm_cfg() -> Llm {
fn env_of(keys: &[&str]) -> Option<String> {
keys.iter()
.find_map(|k| std::env::var(k).ok())
.filter(|s| !s.is_empty())
}
let mut key = env_of(&["OPENAI_API_KEY", "MARQDO_LLM_API_KEY", "USTC_LLM_API_KEY"]);
let mut base = env_of(&["OPENAI_BASE_URL", "MARQDO_LLM_BASE_URL"]);
let mut model = env_of(&["OPENAI_MODEL", "MARQDO_LLM_MODEL"]);
let env_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join(".env");
if let Ok(txt) = std::fs::read_to_string(&env_path) {
for line in txt.lines() {
let line = line.trim();
if line.is_empty() || line.starts_with('#') {
continue;
}
if let Some((k, v)) = line.split_once('=') {
let v = v.trim().trim_matches('"').to_string();
match k.trim() {
"OPENAI_API_KEY" | "MARQDO_LLM_API_KEY" => key = key.or(Some(v)),
"OPENAI_BASE_URL" | "MARQDO_LLM_BASE_URL" => base = base.or(Some(v)),
"OPENAI_MODEL" | "MARQDO_LLM_MODEL" => model = model.or(Some(v)),
_ => {}
}
}
}
}
Llm {
key: key.expect("未找到 API 密钥:请设置 OPENAI_API_KEY 或仓库根 .env"),
base: base.unwrap_or_else(|| "https://llm.cflmy.cn/v1".to_string()),
model: model.unwrap_or_else(|| "cflmy".to_string()),
}
}
/// 调用一次 LLM;空体/非 JSON/瞬时错误自动重试 3 次(容错重试),仍失败 ⇒ Err(记为基础设施失败)。
fn chat(llm: &Llm, system: &str, user: &str) -> Result<String, String> {
let req = json!({
"model": llm.model,
"temperature": 0,
"max_tokens": 8000,
"messages": [
{"role": "system", "content": system},
{"role": "user", "content": user}
]
});
let url = format!("{}/chat/completions", llm.base.trim_end_matches('/'));
let auth = format!("Authorization: Bearer {}", llm.key);
let mut last = String::new();
for _ in 0..5 {
let mut child = std::process::Command::new("curl")
.args(["-sS", "-m", "120", "--retry", "2", "--retry-all-errors", "--retry-delay", "2", &url, "-H", &auth, "-H", "Content-Type: application/json", "--data-binary", "@-"])
.stdin(std::process::Stdio::piped())
.stdout(std::process::Stdio::piped())
.stderr(std::process::Stdio::piped())
.spawn()
.expect("启动 curl");
child
.stdin
.as_mut()
.unwrap()
.write_all(req.to_string().as_bytes())
.unwrap();
let out = child.wait_with_output().unwrap();
let text = String::from_utf8_lossy(&out.stdout).to_string();
match serde_json::from_str::<Value>(&text) {
Ok(v) if v["error"].is_object() => {
last = format!("LLM 报错: {}", v["error"]);
}
Ok(v) => {
if let Some(c) = v["choices"][0]["message"]["content"].as_str() {
return Ok(c.to_string());
}
last = format!("响应缺 content: {}", truncate(&text, 120));
}
Err(_) => {
let err = String::from_utf8_lossy(&out.stderr).to_string();
last = format!("非 JSON / 空体: {} {}", truncate(&text, 80), truncate(&err, 80));
}
}
std::thread::sleep(std::time::Duration::from_secs(5));
}
Err(last)
}
// ---------- 提示词与解析 ----------
const SYSTEM: &str = "你是 Marqdo 语言(.mq.md,Markdown 标记即语法)的有界修复器。\n\
叙述是文档;`**…**` 是代码语句;`*…*` 是返回;`>` 是调用;GFM 表格是数据或契约表(如 参数/返回/字段 契约)。\n\
你会收到一份带行号的源码与结构化诊断。请只输出一个 JSON 数组(不要 markdown 围栏、不要任何解释),\n\
元素形如 {\"op\":\"replace\",\"line\":N,\"text\":\"整行新内容\"} / {\"op\":\"delete\",\"line\":N} / {\"op\":\"insert\",\"line\":N,\"text\":\"新行\"}\n\
(insert 表示在第 N 行之前插入)。触碰的行号必须落在给定范围内(insert 的 N 允许取范围末端+1)。\n\
若判断无法在约束内修复,输出 []。尽量最小改动。";
fn prompt(src: &str, ranges: &[(u32, u32)], diags: &[Value], feedback: &str) -> String {
let numbered: String = src
.lines()
.enumerate()
.map(|(i, l)| format!("{:6}|{}\n", i + 1, l))
.collect();
let ranges_txt = ranges
.iter()
.map(|(a, b)| format!("[{a},{b}]"))
.collect::<Vec<_>>()
.join(", ");
let mut s = format!(
"请修复下面这份 Marqdo 程序的错误。\n\n\
允许触碰的行范围(1 起,含端点;insert 可取范围末端+1):{ranges_txt}\n\n\
结构化诊断(JSON):\n{}\n\n\
源码(带行号):\n{numbered}",
serde_json::to_string_pretty(diags).unwrap()
);
if !feedback.is_empty() {
s.push_str(&format!(
"\n上一次尝试未通过验证:{feedback}\n请换一种修法(仍受行范围约束)。\n"
));
}
s
}
/// 从模型输出提取行编辑(容错:数组 / 单对象 / NDJSON 多对象流 / 字符串化元素 /
/// 字符串型行号 / ```围栏 都收);解析失败 ⇒ 空 = 弃权。
fn parse_edits(reply: &str) -> Vec<Edit> {
let s = reply.trim();
let s = s
.trim_start_matches("```json")
.trim_start_matches("```")
.trim_end_matches("```")
.trim();
// 1) 数组形优先(元素可能是字符串化对象);2) 回退到全串扫描平衡对象(覆盖 NDJSON 流)
let mut values: Vec<Value> = Vec::new();
if let (Some(a), Some(b)) = (s.find('['), s.rfind(']')) {
if b > a {
if let Ok(list) = serde_json::from_str::<Vec<Value>>(&s[a..=b]) {
values = list;
}
}
}
if values.is_empty() {
values = scan_objects(s);
}
values
.iter()
.filter_map(|e| {
// 元素也可能是字符串化的 JSON 对象(模型防转义时常见)
let obj: Value = if e.is_string() {
serde_json::from_str(e.as_str().unwrap_or("")).unwrap_or(Value::Null)
} else {
e.clone()
};
let line = match obj.get("line")? {
Value::Number(n) => n.as_u64()? as u32,
Value::String(s) => s.trim().parse::<u32>().ok()?,
_ => return None,
};
let text = obj.get("text").and_then(|t| t.as_str()).unwrap_or("").to_string();
Some(match obj.get("op")?.as_str()? {
"replace" => Edit::Replace { line, text },
"delete" => Edit::Delete { line },
"insert" => Edit::InsertBefore { line, text },
_ => return None,
})
})
.collect()
}
/// 扫描文本中所有**平衡的** JSON 对象(字符串感知);非法片段跳过。
fn scan_objects(s: &str) -> Vec<Value> {
let b = s.as_bytes();
let mut out = Vec::new();
let mut i = 0;
while i < b.len() {
if b[i] == b'{' {
let (mut depth, mut in_str, mut esc) = (0i32, false, false);
let mut j = i;
let mut closed = false;
while j < b.len() {
let c = b[j] as char;
if esc {
esc = false;
} else if c == '\\' && in_str {
esc = true;
} else if c == '"' {
in_str = !in_str;
} else if !in_str {
if c == '{' {
depth += 1;
} else if c == '}' {
depth -= 1;
if depth == 0 {
closed = true;
break;
}
}
}
j += 1;
}
if closed {
let frag = &s[i..=j];
let v = serde_json::from_str::<Value>(frag)
.or_else(|_| serde_json::from_str::<Value>(&unquote_line_nums(frag)));
if let Ok(v) = v {
out.push(v);
}
i = j + 1;
continue;
}
}
i += 1;
}
out
}
/// 确定性修补模型的常见 JSON 笔误:`"line":3` 数字后多余引号(`"line":3"` → `"line":3`)。
/// 通用 JSON 容错,与 Marqdo 语法无关;只动 `"line"` 后的数字位。
fn unquote_line_nums(frag: &str) -> String {
let cs: Vec<char> = frag.chars().collect();
let mut out = String::with_capacity(frag.len());
let mut i = 0;
while i < cs.len() {
if cs[i..].starts_with(&['"', 'l', 'i', 'n', 'e', '"'][..]) {
out.extend(['"', 'l', 'i', 'n', 'e', '"']);
i += 6;
while i < cs.len() && (cs[i] == ':' || cs[i].is_whitespace()) {
out.push(cs[i]);
i += 1;
}
let mut digits = 0;
while i < cs.len() && cs[i].is_ascii_digit() {
out.push(cs[i]);
digits += 1;
i += 1;
}
if digits > 0 && i < cs.len() && cs[i] == '"' {
i += 1; // 剥掉数字后多余的引号
}
} else {
out.push(cs[i]);
i += 1;
}
}
out
}
/// 消融臂(plain):把文档上下文从诊断里剥掉——只留 code/severity/message/span。
fn strip_doc_context(diags: &[Value]) -> Vec<Value> {
diags
.iter()
.map(|d| {
let mut o = d.clone();
if let Some(obj) = o.as_object_mut() {
for k in ["doc_anchor", "doc_quote", "suggestion", "contract_ref"] {
obj.remove(k);
}
}
o
})
.collect()
}
/// 真实消费 `mlsp repair_targets`:诊断 → 靶点范围。
fn target_ranges(diag: &Value) -> Vec<(u32, u32)> {
let resp = mcall(json!({"id": 9, "method": "repair_targets", "params": {
"code": diag["code"], "doc_anchor": diag["doc_anchor"], "span": diag["span"], "suggestion": diag["suggestion"]
}}));
assert_eq!(resp["ok"], true, "repair_targets 必须可用: {resp}");
assert_eq!(resp["result"]["repair"]["on_violation"], "abstain");
let mut rs: Vec<(u32, u32)> = resp["result"]["targets"]
.as_array()
.unwrap()
.iter()
.flat_map(ranges_of)
.collect();
rs.sort_unstable();
rs.dedup();
rs
}
fn truncate(s: &str, n: usize) -> String {
if s.len() <= n {
s.to_string()
} else {
format!("{}…", &s[..n])
}
}
// ---------- 单例实验 ----------
#[derive(Debug)]
struct Outcome {
case: String,
arm: &'static str,
fixed: bool,
one_shot: bool,
attempts: u32,
rejections: u32,
abstained: bool,
note: String,
}
fn run_case(llm: &Llm, case: &Case, arm: &'static str) -> Outcome {
let tag = format!("{}_{}", arm, case.name);
let mut src = case.broken.clone();
let mut attempts = 0u32;
let mut rejections = 0u32;
let mut abstained = false;
let mut fixed = false;
let mut one_shot = false;
let mut feedback = String::new();
let mut note = String::new();
let mut infra = 0u32;
while attempts < 2 {
let diags = diagnose(case.verify, &src, &tag);
let Some(diag) = diags.first().cloned() else {
fixed = true;
one_shot = true;
break;
};
let ranges = target_ranges(&diag);
assert!(!ranges.is_empty(), "[{}] 诊断必须可锚定: {diag}", case.name);
let shown = if arm == "anchor" {
diags.clone()
} else {
strip_doc_context(&diags)
};
let reply = match chat(llm, SYSTEM, &prompt(&src, &ranges, &shown, &feedback)) {
Ok(r) => r,
Err(e) => {
// 基础设施抖动不计入修复尝试
infra += 1;
if infra >= 2 {
note = format!("LLM 调用失败(重试后): {e}");
break;
}
continue;
}
};
attempts += 1;
let edits = parse_edits(&reply);
if edits.is_empty() {
abstained = true;
note = format!("模型弃权/输出不可解析: {}", truncate(&reply, 100));
break;
}
let resp = apply_via_mlsp(&src, &ranges, &edits);
if resp["ok"] == false {
// 护栏:越界必拒 + abstain(源零字节不改 —— apply 全有或全无)
rejections += 1;
assert_eq!(resp["error"]["code"], "mlsp.repair_out_of_scope", "{resp}");
assert_eq!(resp["error"]["on_violation"], "abstain", "{resp}");
note = format!("越界被拒: {}", truncate(&resp["error"]["message"].to_string(), 100));
feedback = note.clone();
continue;
}
let new_src = resp["result"]["source"].as_str().unwrap().to_string();
let after = diagnose(case.verify, &new_src, &tag);
if after.is_empty() {
fixed = true;
one_shot = attempts == 1;
break;
}
src = new_src;
feedback = format!("修复后仍有诊断: {}", truncate(&after[0].to_string(), 240));
note = feedback.clone();
}
Outcome {
case: case.name.clone(),
arm,
fixed,
one_shot,
attempts,
rejections,
abstained,
note,
}
}
// ---------- 实验主入口 ----------
#[test]
#[ignore = "模型在环实验:需要 .env / OPENAI_API_KEY 与网络(cflmy @ llm.cflmy.cn)"]
fn exp_a_anchored_repair_with_model() {
let llm = llm_cfg();
let mut cs = cases();
if let Ok(n) = std::env::var("MARQDO_EXP_LIMIT") {
if let Ok(n) = n.parse::<usize>() {
cs.truncate(n);
}
}
let outcomes: Mutex<Vec<Outcome>> = Mutex::new(Vec::new());
for arm in ["anchor", "plain"] {
let queue: Mutex<Vec<usize>> = Mutex::new((0..cs.len()).collect());
std::thread::scope(|s| {
for _ in 0..4 {
s.spawn(|| loop {
let i = queue.lock().unwrap().pop();
let Some(i) = i else { break };
let o = run_case(&llm, &cs[i], arm);
eprintln!(
"[{arm}] {:<18} {} attempts={} rejects={} {}",
o.case,
if o.fixed { if o.one_shot { "FIXED@1" } else { "FIXED@2" } } else { "FAILED " },
o.attempts,
o.rejections,
o.note
);
outcomes.lock().unwrap().push(o);
});
}
});
}
// ---- 汇总 ----
let outs = outcomes.into_inner().unwrap();
let mut report = String::new();
report.push_str(&format!(
"# 修复实验(§5.2(a) 锚点消融)—— {}\n\n\
| | |\n|---|---|\n| 模型 | `{}` @ `{}` |\n| 样本 | golden 20 例(易锚定错误) |\n\
| 协议 | `validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮 |\n\
| 对照 | `anchor` = 诊断带 `doc_anchor`/`doc_quote`/`suggestion`;`plain` = 全部剥掉 |\n\n",
chrono_date(), llm.model, llm.base
));
let arm_stats = |arm: &str| -> String {
let rows: Vec<&Outcome> = outs.iter().filter(|o| o.arm == arm).collect();
let n = rows.len().max(1) as f64;
let one = rows.iter().filter(|o| o.one_shot).count();
let fin = rows.iter().filter(|o| o.fixed).count();
let att: f64 = rows.iter().map(|o| o.attempts as f64).sum::<f64>() / n;
let rej = rows.iter().map(|o| o.rejections).sum::<u32>();
let abs = rows.iter().filter(|o| o.abstained).count();
format!(
"| {arm} | {one}/{rows_n}({one_pct:.0}%) | {fin}/{rows_n}({fin_pct:.0}%) | {att:.2} | {rej} | {abs} |\n",
rows_n = rows.len(),
one_pct = 100.0 * one as f64 / n,
fin_pct = 100.0 * fin as f64 / n,
)
};
report.push_str("## 汇总(设计目标:一轮修复率 ≥ 80%)\n\n| 臂 | 一轮修复率 | 最终修复率(≤2轮) | 平均尝试 | 越界拒(护栏) | 弃权 |\n|---|---|---|---|---|---|\n");
let stat_a = arm_stats("anchor");
let stat_p = arm_stats("plain");
report.push_str(&stat_a);
report.push_str(&stat_p);
report.push_str("\n## 逐例\n\n| 例 | 臂 | 结果 | 轮次 | 越界拒 | 备注 |\n|---|---|---|---|---|---|\n");
let mut sorted: Vec<&Outcome> = outs.iter().collect();
sorted.sort_by(|a, b| a.case.cmp(&b.case).then(a.arm.cmp(b.arm)));
for o in &sorted {
report.push_str(&format!(
"| {} | {} | {} | {} | {} | {} |\n",
o.case,
o.arm,
if o.fixed { if o.one_shot { "一轮修复" } else { "二轮修复" } } else { "未修复" },
o.attempts,
o.rejections,
o.note.replace('|', "\\|")
));
}
report.push_str("\n## 护栏核对\n\n- 每次越界编辑都以 `mlsp.repair_out_of_scope` + `abstain` 被拒,且 `repair_apply` 全有或全无(源零字节不改)——由 `tests/repair_loop.rs` 的确定性断言覆盖;本实验计数仅作记录。\n");
let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("doc/roadmap")
.join(format!("repair-experiment-{}-{}.md", chrono_date(), llm.model));
std::fs::write(&path, &report).unwrap();
eprintln!("\n{report}");
eprintln!("报告已写入 {}", path.display());
// ---- 功能正确性断言(实验 = 真实消费者) ----
let anchor_fixed = outs.iter().filter(|o| o.arm == "anchor" && o.fixed).count();
assert!(
anchor_fixed >= 1,
"修复回路必须至少闭环一例(否则功能链路有问题):\n{:#?}",
outs
);
}
/// 无外部 chrono 依赖的日期(UTC)。
fn chrono_date() -> String {
let secs = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_secs();
// 2026-09-22 ≈ 1790000000s 附近的简易换算不必精确到历法;直接用运行日环境变量兜底
if let Ok(d) = std::env::var("MARQDO_EXP_DATE") {
return d;
}
// 简化:从 unix 秒推 YYYY-MM-DD(1970-01-01 起算,忽略闰秒)
let days = secs / 86400;
let (y, m, d) = civil_from_days(days as i64);
format!("{y:04}-{m:02}-{d:02}")
}
/// Howard Hinnant 的 days→civil 算法(公历)。
fn civil_from_days(z: i64) -> (i64, u32, u32) {
let z = z + 719468;
let era = if z >= 0 { z } else { z - 146096 } / 146097;
let doe = (z - era * 146097) as u64;
let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
let y = yoe as i64 + era * 400;
let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
let mp = (5 * doy + 2) / 153;
let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
(if m <= 2 { y + 1 } else { y }, m, d)
}
+84
View File
@@ -0,0 +1,84 @@
//! T3.3 golden:**20 例易锚定错误**的修复循环(护栏机械执行 + 金修复可复现)。
//!
//! 每例走完整循环:
//! 诊断(含 `span`/`doc_anchor`)→ 推导靶点范围 → 金修复(源 diff 自动推导行编辑,
//! 顺便机器验证「易锚定」= 金编辑全落范围内)→ `mlsp repair_apply` 应用 → 复验通过。
//!
//! 护栏负例内嵌每例:越界编辑(第 1 行 `# main`,永不在靶点内)必拒
//! (`mlsp.repair_out_of_scope` + `abstain`),源零字节不改。
//! 模型实验见 `tests/repair_experiment.rs`(同一批 20 例)。
mod common;
use common::*;
use marqdo::repair::{apply_edits, Edit};
use serde_json::json;
#[test]
fn golden_repair_loop_all_20() {
let cases = cases();
assert_eq!(cases.len(), 20, "golden 必须正好 20 例");
for case in &cases {
// 1. 诊断(broken 必须给出期望错误码)
let code = case.code();
let diags = diagnose(case.verify, &case.broken, &case.name);
assert!(
diags.iter().any(|d| d["code"] == code),
"[{}] 期望诊断 {code},实得 {diags:?}",
case.name
);
let ranges: Vec<(u32, u32)> = diags.iter().flat_map(ranges_of).collect();
assert!(!ranges.is_empty(), "[{}] 诊断必须带可锚定范围: {diags:?}", case.name);
// 2. 金修复 → 行编辑(diff 自动推导);「易锚定」= 全部编辑落在靶点内
let edits = derive_edits(&case.broken, &case.gold);
assert!(!edits.is_empty(), "[{}] 金修复必须产生编辑", case.name);
let applied = apply_edits(&case.broken, &ranges, &edits).unwrap_or_else(|oos| {
panic!("[{}] 金修复越界(不是易锚定错误): 越界 {:?},范围 {:?}", case.name, oos.lines, oos.ranges)
});
assert_eq!(applied, case.gold, "[{}] 行编辑结果应与金修复逐字节一致", case.name);
// 3. 经 MLSP 面应用(护栏所在)
let resp = apply_via_mlsp(&case.broken, &ranges, &edits);
assert_eq!(resp["ok"], true, "[{}] repair_apply 应接受金修复: {resp}", case.name);
assert_eq!(resp["result"]["source"], case.gold, "[{}]", case.name);
// 4. 复验(干净 = 空诊断)
let after = diagnose(case.verify, &case.gold, &case.name);
assert!(after.is_empty(), "[{}] 修复后必须零诊断: {after:?}", case.name);
// 5. 护栏负例:越界编辑(第 1 行 `# main`)必拒 + 源零字节不改
let bad = vec![Edit::Replace { line: 1, text: "# 被篡改".to_string() }];
let resp = apply_via_mlsp(&case.broken, &ranges, &bad);
assert_eq!(resp["ok"], false, "[{}] 越界编辑必须被拒: {resp}", case.name);
assert_eq!(resp["error"]["code"], "mlsp.repair_out_of_scope", "[{}]", case.name);
assert_eq!(resp["error"]["on_violation"], "abstain", "[{}]", case.name);
}
}
#[test]
fn repair_apply_refuses_any_out_of_scope_line() {
// 独立护栏例:部分越界 = 全部拒绝(全有或全无),源零字节不改。
let src = "# main\n\n| 字段 | 类型 | 可空 |\n|------|------|------|\n| id | number | |\n| name | text | 是 |\n\n*1*\n";
let ranges = [(3u32, 6u32)]; // 只有字段契约表
let edits = vec![
Edit::Replace { line: 5, text: "| id | text | |".to_string() }, // 表内 ✓
Edit::Delete { line: 1 }, // 越界 ✗
];
let resp = apply_via_mlsp(src, &ranges, &edits);
assert_eq!(resp["ok"], false);
assert_eq!(resp["error"]["code"], "mlsp.repair_out_of_scope");
assert!(resp["error"]["lines"].as_array().unwrap().contains(&json!(1)));
// 范围内编辑照常可用(含表尾追加)
let edits = vec![
Edit::Replace { line: 5, text: "| id | text | |".to_string() },
Edit::InsertBefore { line: 7, text: "| email | text | 是 |".to_string() }, // end+1 追加 ✓
];
let resp = apply_via_mlsp(src, &ranges, &edits);
assert_eq!(resp["ok"], true, "{resp}");
let out = resp["result"]["source"].as_str().unwrap();
assert!(out.contains("| id | text | |"));
assert!(out.contains("| email | text | 是 |"));
}