Files
marqdo/doc/next/Marqdo_Executable_Knowledge_Testing.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

84 lines
4.5 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 可执行知识语法:仓库级测试与兼容性规程
本文是 `Marqdo_Executable_Knowledge_Development.md` 的验证规程。它约束稳定符号 URI、零参数知识路径、关联函数/实例方法区分及其 CLI 解析进入标准库、扩展库和发布流程后的测试方式。
## 覆盖目标
新写法只在需要值的位置把零参数路径解释为调用:
```marqdo
**pi = math.pi**
**year = facts.Person.birth_year**
```
旧的 `**pi = > math.pi**` 和 `> math.pi` 继续兼容。对象子函数不读取 `self` / `自` 时是 `associated_function`;读取接收者时是 `instance_method`,不能由 `Type.method` 直接执行。
每项语法变更必须同时证明:新写法正确、旧写法未回归、Tree/Bytecode 一致、CLI 静态解析和运行时规则一致,并且标准库与扩展库仍能加载、运行。
## 自动化测试矩阵
| 层级 | 覆盖内容 | 命令 | 通过条件 |
|---|---|---|---|
| 解析 | 零参路径降级 Call;带参路径不能静默执行 | `cargo test --locked --lib parse::expr` | AST、参数数与诊断稳定 |
| 语义 | ProjectRoot、ModuleId、SymbolId、关联/实例分类、歧义 | `cargo test --locked --lib sema::` | 扫描顺序不影响结果;分类不改变 SymbolId |
| Tree | 标准库裸路径、关联函数、旧写法 | `cargo test --locked --test gold structure_new_path_stdlib structure_ns_associated_function` | stdout 金样一致 |
| Bytecode | 同一正例的后端一致性 | `cargo test --locked --test gold bytecode_new_path_stdlib bytecode_ns_associated_function` | stdout、退出码一致 |
| 负例 | 接收者依赖路径被拒绝 | `cargo test --locked --test gold error_ns_instance_method knowledge_resolve_rejects_instance_path` | 不构造对象、不执行方法 |
| CLI | `inspect` / `resolve` JSON | `cargo test --locked --test gold knowledge_resolve_new_path` | 返回 URI、source、callable;resolve 不执行代码 |
| 标准库 | 英文/中文零参知识 | `cargo test --locked --test gold lib_log_uuid_smoke lib_log_uuid_zh_smoke` | `uuid.v4` 等裸路径可用 |
| 扩展库 | 改写后的扩展调用和插件加载 | `cargo test --locked --test gold ext_quantum_gates_smoke` | `math.pi` 新写法输出不变 |
## 每次语法改动的执行顺序
```bash
source scripts/dev-env.sh
cargo check --locked
cargo test --locked --lib
cargo test --locked --test gold -- --test-threads=1
cargo test --locked
cargo build --locked
```
发布前再做可观察的 CLI/双后端冒烟:
```bash
target/debug/marqdo knowledge tests/structure/ns --json resolve \
helpers.Box.birth_year --from tests/structure/ns/associated.mq.md
target/debug/marqdo run tests/structure/new-path-stdlib.mq.md --backend tree
target/debug/marqdo run tests/structure/new-path-stdlib.mq.md --backend bytecode
```
完整 gold 会构建部分原生/Go 扩展,必须单线程执行。网络、真实 LLM 与 ignored 实验不属于离线语法门禁,不能以其失败掩盖核心回归。
## 标准库与扩展库改写准则
仅改写可机械证明等价的值表达式:
| 原写法 | 新写法 | 前提 |
|---|---|---|
| `**x = > math.pi**` | `**x = math.pi**` | 目标零参数、值位置 |
| `**id = > uuid.v4**` | `**id = uuid.v4**` | 目标零参数、值位置 |
| `**x = > Type.fact**` | `**x = Type.fact**` | 目标为关联函数 |
禁止自动改写副作用语句、带必填参数函数、实例方法、文本/围栏/URL/导航链接,以及不能同时通过 Tree/Bytecode 的变更。本轮用 `math.pi`(量子扩展夹具)、`数学.圆周率`(中文标准库夹具)和 `uuid.v4`(标准库夹具)作为真实金样。
## CLI 合约
```text
marqdo knowledge PATH --json inspect SYMBOL
marqdo knowledge PATH --json resolve REFERENCE --from CALLER.mq.md
```
`resolve` 只绑定、不执行。它依据 `--from` 的 frontmatter import 解析第一个路径段,不会在项目中按名字猜测目标。关联函数返回 `resolution: "symbol"`;实例方法返回 `resolution: "instance_only"` 并以退出码 1 拒绝直接路径调用。
## 发布门槛
1. `git diff --check` 无错误;
2. Rust 核心、gold、完整 `cargo test --locked` 通过;
3. 每个新正例有 Tree、Bytecode 和 CLI(适用时)覆盖;
4. 每个语义拒绝路径有稳定负例;
5. 标准库/扩展库改写保留原 stdout 金样;
6. 不提交 `.marqdo/`、插件构建物或本地凭据。
失败报告必须记录命令、后端、夹具、stdout/stderr、插件/网络依赖及与旧写法的差异。