Compare commits

..
10 Commits
Author SHA1 Message Date
cflmyandCursor b8a4ddd38f release: bump to 2.1.1 (executable-knowledge spine)
Ship BoundCall/NarrativeRef/generation CURRENT notes with Cargo, ext pack, README, debian, and release Highlights.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 23:40:35 +08:00
cflmyandCursor 352bc0d2c5 feat: finish remaining EK plan — bookstore chain, closure, 100-unit corpus
Make examples/executable-knowledge runnable on both backends, bind same-module
Type.member paths, add closure digests to locks/impact, and gate 100 corpus
units plus CLI smoke so S4–S6 leftover items have reviewable evidence.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 23:34:21 +08:00
cflmyandCursor 8a6d09d582 feat: pure extract, bookstore story subset, and project scan caps
Add artifact.extract_pure for restricted expression lifting, a runnable
bookstore tax story fixture, and G12 discovery limits so oversized or deep
trees fail with explicit diagnostics instead of hanging.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 23:27:05 +08:00
cflmyandCursor dcd3d329d4 feat: land S1–S6 executable-knowledge slices (NarrativeRef through CI)
Add comment-line NarrativeRef steps, generation CURRENT snapshots, frontmatter
sources/applicability, digest-guarded artifact.patch, lock change classes, and
an offline CI gate so the documented S0–S6 path has reviewable evidence.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 23:24:18 +08:00
cflmyandCursor 0e1bfb3359 feat: complete BoundCall dual-backend and reuse bind gate (G02)
Share resolve_for_exec across Tree/Bytecode and semantic projections,
emit bound_calls/dynamic_calls, and require eng_reuse bind_targets before
execute so discovery scores cannot be treated as handles.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 23:06:34 +08:00
cflmyandCursor e9ae7ff1ae fix: isolate bytecode bare-name resolve to module scope (G02)
Imported functions shared the flat call table, so bare same-named calls
could silently bind across imports. Scope tags keep path calls working
while rejecting ambiguous bare names on both backends.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 22:54:52 +08:00
cflmyandCursor ecbdd18303 feat: executable-knowledge S0–S1 gate plus effect and MLSP reuse subset
Establish author baseline fixtures and offline tests, make SemanticProject
the sole authority for graph edges, classify named steps, and tighten
local reuse so unknown effects are not pure and MLSP binds by SymbolId.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 22:52:06 +08:00
cflmy bedd53e212 docs: align executable knowledge roadmap with native workflow 2026-10-23 14:25:12 +00:00
cflmy 7674ebb869 docs: audit executable knowledge planning gaps 2026-10-23 13:54:08 +00:00
cflmy 434be9fd52 chore: ignore local release secrets 2026-10-23 13:37:54 +00:00
77 changed files with 4849 additions and 309 deletions

No files matched your search

+3 -1
View File
@@ -63,10 +63,12 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
## Occlusion syntax (v2.1.0)
## Occlusion syntax (v2.1.0+) · Executable knowledge (v2.1.1)
Occlusion is the default syntax. Shipped source declares `markup: occlusion` (or `标记: 遮蔽`) explicitly so imports stay deterministic. Legacy `[key](collection)` requires `markup: classic` or the one-cycle CLI flag `--legacy-markup`; `MARQDO_MARKUP` does not change parsing.
Executable-knowledge **S0 author baseline** (six tasks, offline gate): [`tests/executable_knowledge/`](../../../tests/executable_knowledge/README.md). Design goals ≠ shipped knowledge reuse — see [`doc/design/document-native-development-guide.md`](../../../doc/design/document-native-development-guide.md).
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
- `[顾客留存率](0.42)` · `[总价](access(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
- Read maps/lists with `access(集合, 键)` (aliases `取` / `取值`): `[第二项](access(列, 2))`.
@@ -0,0 +1,22 @@
name: executable-knowledge
on:
push:
branches: [main]
pull_request:
jobs:
gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- name: Offline executable-knowledge gate
run: cargo test --test executable_knowledge --locked
- name: no ignored tests counted as success
run: |
if grep -n '#\[ignore\]' tests/executable_knowledge.rs; then
echo "executable_knowledge must not use #[ignore] as success evidence" >&2
exit 1
fi
echo "ok: no #[ignore] in executable_knowledge gate"
+3 -3
View File
@@ -126,9 +126,9 @@ jobs:
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **v2.1.0**:文件级 Occlusion 默认语义——全仓迁移 · `migrate labels --mark` · `access` / `遍历` · 可执行知识语义投影
- **v2.1.0**: File-scoped Occlusion by default — corpus migration, `migrate labels --mark`, `access` / `for`, executable-knowledge projections
- **v2.1.0 ext**:扩展包同步 2.1.0 / Ext pack 2.1.0
- **v2.1.1**:可执行知识主链——BoundCall · NarrativeRef · 来源/适用期 · patch/extract · 整代 CURRENT + closure · 发票示例 113
- **v2.1.1**: Executable-knowledge spine — BoundCall, NarrativeRef, sources, patch/extract, generation CURRENT + closure, invoice example 113
- **v2.1.1 ext**:扩展包同步 2.1.1 / Ext pack 2.1.1
- **v1.5.2**:外联 v3 P0/P1——raw stdin + 每 cell 输入 · plan API · snapshot · `view capture` · Persist
- **v1.5.2**: Foreign v3 P0/P1 — raw stdin + per-cell inputs, plan API, snapshot export/import/replay, `view capture`, Persist
- **v1.5.2 ext**:扩展包同步 1.5.2 / Ext pack 1.5.2
+1
View File
@@ -103,3 +103,4 @@ tests/ext/_sbx_cow/
tests/ext/_sbx_*/
examples/**/_example_sbx/
.secrets/
+38
View File
@@ -69,6 +69,44 @@ marqdo ext add web
## Unreleased
### Added
### Fixed
### Changed
## v2.1.1 — 2026-10-23
### Highlights
**可执行知识主链落地(S0–S6)**:BoundCall 双后端共享解析、正文 NarrativeRef、来源/适用期、digest 保护补丁与纯表达式提取、整代 `CURRENT` 投影与闭包摘要;订单发票示例双后端输出 `113`;离线门禁含 100 单元语料与 CLI 冒烟。
```bash
git checkout v2.1.1 && cargo build --release
marqdo ext add web
marqdo run examples/executable-knowledge/docs/invoice-answer.mq.md
```
**核心表面 Δ**:**无增删关键词**——同模块 `Type.member` 纳入 BoundCall;语义投影新增 `bound_calls` / `dynamic_calls` / `hashes.closure` / NarrativeRef 步骤;不改变默认 Occlusion 链接读法。
### Added
- **BoundCall / DynamicCall**:`sema::bind::resolve_for_exec`;Tree 与 Bytecode 静态路径对齐;`bound_calls.json` / `dynamic_calls.json`;同模块定义树路径绑定。
- **NarrativeRef**:注释行 Markdown 链接 → `narrate` / `navigation` 步骤;围栏与行内代码不计步骤。
- **来源与适用性**:frontmatter `sources` / `valid_until` → `evidence=sourced|expired|missing_source`;`artifact.bind policy=business`。
- **局部编辑与提取**:MLSP `artifact.patch`(digest + wording 回滚);`artifact.extract_pure` 纯表达式预览。
- **整代与闭包**:`generations/<id>/` + `CURRENT`;`hashes.closure` 随依赖变化;锁报告 `classes`。
- **门禁**:`tests/executable_knowledge`(含 100 单元);CI `.github/workflows/executable-knowledge.yml`;项目扫描 depth/size/count 上限。
- **示例**:`examples/executable-knowledge` 发票含税链可运行;负知识文档。
### Fixed
- Bytecode 裸名解析不再跨 import scope 误连同名函数;同模块 `Type.member` 写入 path_index 供兄弟调用。
### Changed
- Agent / reuse 发现结果标记 `discovery_only` + `bind_required` / `bind_targets`,不可把打分结果直接当可执行目标。
## v1.5.2 — 2026-10-18
### Highlights
Generated
+2 -2
View File
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "2.1.0"
version = "2.1.1"
dependencies = [
"anyhow",
"assert_cmd",
@@ -610,7 +610,7 @@ dependencies = [
[[package]]
name = "marqdo-wasm"
version = "2.1.0"
version = "2.1.1"
dependencies = [
"marqdo",
"serde_json",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "2.1.0"
version = "2.1.1"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
+6 -5
View File
@@ -281,9 +281,10 @@ marqdo catalog public -o .marqdo
---
## 现状(v2.1.0)
## 现状(v2.1.1)
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock) · 扩展包同步 **2.1.0**
- **可执行知识主链(v2.1.1)**:BoundCall 双后端 · NarrativeRef · 来源/适用期 · `artifact.patch` / `extract_pure` · 整代 `CURRENT` + closure · 发票示例 `113` · 门禁 `tests/executable_knowledge`(含 100 单元)· 扩展包同步 **2.1.1**
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock)
- **外联 v3 P0/P1(v1.5.2)**:raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · `view capture` · Persist 按钮 · 扩展包同步 **1.5.2**
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin;扩展包同步 **1.5.0**
- **裸自增升参(v1.4.6)**:首次粗体赋值左值即声明;`**n = n + 1**` 无反引号也升为必选形参。扩展包仍为 **1.4.5**
@@ -319,7 +320,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(v2.1.0)
### 如何使用最新 Marqdo(v2.1.1)
**安装解释器(任选其一)**
@@ -334,7 +335,7 @@ marqdo catalog public -o .marqdo
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v2.1.0 # 或留在 main
git checkout v2.1.1 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -373,7 +374,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/v2.1.0
# https://github.com/cflmy/marqdo/releases/tag/v2.1.1
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "2.1.0"
version = "2.1.1"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
+7
View File
@@ -1,3 +1,10 @@
marqdo (2.1.1-1ppa1) noble; urgency=medium
* Marqdo 2.1.1: executable-knowledge spine (BoundCall, NarrativeRef,
sources/applicability, generation CURRENT + closure digests).
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 15:40:00 +0000
marqdo (2.1.0-1ppa1) noble; urgency=medium
* Marqdo 2.1.0: file-scoped Occlusion is the default syntax; migrated
+9 -3
View File
@@ -13,12 +13,16 @@
## 当前文档
> **可执行知识下一阶段的规范优先级**:实现 `[]()`、Semantic Artifact、知识绑定、验证、锁定、EKC/Agent 复用时,以 [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) 为实施基线。与其冲突的早期链接、遮蔽、知识分层或 EKC 设计只作历史参考。
> **可执行知识下一阶段的阅读顺序**:[原始意图 009](next/009.md) → [文档原生开发指导](design/document-native-development-guide.md)(作者体验、语法审查结论、AI 工作协议)→ [详细开发规范](next/Marqdo_Executable_Knowledge_Development.md)(目标语义与工程约束)→ [缺口与交付路线](roadmap/executable-knowledge-gaps-2026-10-23.md)(现状证据、S0–S6)。指导文档修订作者负担、场景政策和交付次序;不得把所有内部治理字段变成作者必填项。与之冲突的早期设计只作历史参考,设计目标不等于已实现能力。
>
> **可执行知识门禁**:[tests/executable_knowledge/](../tests/executable_knowledge/README.md) — S0–S2 BoundCall / 效应 / MLSP bind,以及后续 NarrativeRef、来源与整代投影子集;`cargo test --test executable_knowledge --locked`(CI:`.github/workflows/executable-knowledge.yml`)。`status: design` / 预期失败与已实现分开报告。
| 文档 | 摘要 |
|------|------|
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 草案:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断** |
| [design/document-native-development-guide.md](design/document-native-development-guide.md) | **下一阶段开发指导**:语法审查裁决、正文→命名→复用工作流、AI 上下文与局部编辑、渐进严格、作者成本及 S0–S6 验收 |
| [design/core-surface.md](design/core-surface.md) | **核心构造清单**:v2.1 默认链接/循环说明与构造守卫;不是全部实现状态清单 |
| [design/markdown-mapping.md](design/markdown-mapping.md) | **历史 v0.2 映射**:不再代表现行默认链接语义 |
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 设计背景**:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断;链接语义以 v2.1 规范和测试为准 |
| [adr/0005-prose-unified-markup.md](adr/0005-prose-unified-markup.md) | **Proposed:采纳 mapping v0.3** |
| [roadmap/markup-v0.3.md](roadmap/markup-v0.3.md) | **Markup v0.3 实现路线(M0–M5)** |
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
@@ -112,6 +116,8 @@
| [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 |
| [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 |
| [next/Marqdo_Executable_Knowledge_Testing.md](next/Marqdo_Executable_Knowledge_Testing.md) | **可执行知识语法测试与兼容性规程**:标准库、扩展库、CLI、Tree/Bytecode 的仓库级门禁 |
| [roadmap/executable-knowledge-gaps-2026-10-23.md](roadmap/executable-knowledge-gaps-2026-10-23.md) | **v2.1 现状与规划缺口审计(方向修订)**:保留 G01–G12 代码证据,以可读步骤、确定执行、早期 AI 复用和局部修改重排 S0–S6,严格治理按场景增加 |
| [../tests/executable_knowledge/README.md](../tests/executable_knowledge/README.md) | **S0 作者基线门禁**:六类任务语料、作者成本计数、预期失败与 Bytecode 同名误连缺陷指纹 |
| [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 |
| [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 |
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
@@ -1,5 +1,7 @@
# 语义评估:参数能否从上下文推断(含叙述式调用)
> **2026-10-23 审阅裁决**:保留参数来源可见、避免隐藏调用者环境的边界;下文已被否决的 L0 建议不可重新启用。自然语言只连接和解释,不能成为隐式执行触发器;当前指导见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **§3 的 L0 方案已被否决**(违反「只执行标记」原则);L1/L2 结论仍有效 |
@@ -1,5 +1,7 @@
# 评定:`[描述](语句)` —— 方括号读作「人话」,圆括号读作「机器话」
> **2026-10-23 审阅裁决**:本文的 Classic 冲突统计和兼容取舍属于迁移历史;v2.1 默认采用描述包裹 payload,不能据旧冲突恢复默认 `[键](集合)`。保留标签的阅读/检索/步骤价值,不强制所有子表达式命名,也不把标签当作目标或权限依据。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **已决策:走「路线二 纯度」**(落地见 [label-freshness-and-repair.md](label-freshness-and-repair.md)) |
+2
View File
@@ -1,5 +1,7 @@
# 调用实参:具名与位置
> **2026-10-23 适用范围校正**:本文保留早期调用尾部规则和历史示例,不是 v2.1 全部调用语法。当前已有 `f(args)` 及具名实参;默认紧邻 `](` 是描述包裹 payload,不再是下文所述的 Classic 取元。语法审阅与开发取舍见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),当前行为须由默认模式测试复核。
| | |
|---|---|
| 状态 | 已定(v0.1 增补;2026-09-14:方括号标记调用) |
+2
View File
@@ -1,5 +1,7 @@
# 语法设计:标记如何构成调用(在「只执行标记」原则下)
> **2026-10-23 审阅裁决**:保留显式标记和正文默认安全;性能数值是旧实验,不作为当前基准。持久跨文档接口优先具名参数,但不禁止位置参数;反引号声明与顺序改变可能是接口变化。当前调用与开发方向见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(未改代码) |
+9 -7
View File
@@ -3,22 +3,24 @@
| | |
|---|---|
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
| 日期 | 2026-09-22 |
| 日期 | 2026-09-22;2026-10-23 校正 v2.1 默认链接语义 |
| 守卫 | `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 红。
> **版本边界**:构造 ID 是历史守卫标识,不是固定不变的语义说明。`link-index` ID 暂保留以匹配注册表,但默认 `[]()` 已是描述包裹 payload;旧索引语义仅属于显式 Classic 兼容路径。未来步骤/知识投影见[文档原生指导](document-native-development-guide.md),不要把目标能力当作当前已实现。核心数量之外,还要审查上下文例外和作者负担。
## 1. 行构造
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `narrative` | 无标记文字 | 叙述(注释) | 段落内延续到空行;**默认安全**——永远不存在「叙述被执行」的路径 | `tests/markup-v03/soft-emphasis.mq.md` |
| `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` |
| `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` |
@@ -30,12 +32,12 @@
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.mq.md` |
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 只有粗体进入执行;判别序:赋值 → 调用 → 表达式 | `tests/markup-v03/multi-bold.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` |
| `link-index` | `[描述](表达式)` | 描述包裹 payload(历史 ID) | 默认 Occlusion;取元可写 `[说明](access(集合, 键))`,不按描述取键;循环载荷见上 | `tests/occlusion/access-and-loop.mq.md` |
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;紧邻 `](` 的默认语义为 payload 遮蔽,不是旧索引 | `tests/structure/bracket-call.mq.md` |
| `footnote-index` | `集合[^键]` | 兼容取元 | 保留既有能力;新代码优先 `access(...)`,需要解释时包裹描述,不再推荐旧 `[键](集合)` | `tests/structure/footnote-index.mq.md` |
| `soft-emphasis` | `*仅*` / `**说明**` | 忽略 | 非代码形强调**不执行**——默认安全的关键消歧规则 | `tests/markup-v03/soft-emphasis.mq.md` |
## 3. 词法大类(LineKind,`src/lex/mod.rs`)
@@ -0,0 +1,284 @@
# Marqdo 文档原生开发指导:让知识的表达、执行与复用成为同一件事
| 项目 | 约定 |
|---|---|
| 状态 | 下一阶段开发指导与规划修订;不表示下述目标接口已经实现 |
| 日期 / 审阅基线 | 2026-10-23 / `main`,`7674ebb`;继承缺口审计的 `434be9f` 代码证据 |
| 原始意图 | [009](../next/009.md)、[附属设计](../next/Marqdo_Executable_Knowledge_Design.md)、[附属示例](../next/Marqdo_Executable_Knowledge_Example.md) |
| 配套实施文件 | [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)、[缺口与交付路线](../roadmap/executable-knowledge-gaps-2026-10-23.md) |
| 本轮边界 | 校正开发方向、作者体验、AI 工作协议和验收;不新增语法,不宣称实现新能力 |
## 1. 审阅结论与规范关系
Marqdo 的优势不在于给传统程序换一套 Markdown 符号,而在于:**读者解释知识、作者修改知识、程序执行知识、AI 查找并复用知识,能够指向同一份有结构的文档和其中的同一步。** 标题、叙述、表格、链接描述、输入输出、来源及执行行为不应分散在彼此手工同步的系统中。
现有规划没有放弃这一目标,但工程排序存在偏移:把身份、图、证据、锁、句柄、晋升全部铺完,再验证人和 AI 是否更容易使用。这样可能交付一个功能齐全的制品管理系统,却让文档作者承担另一套注册、声明、审核和配置工作。需要改变交付方法,不必推翻确定性编译、绑定和权限机制。
本指导规定**为何开发、作者维护什么、怎样证明值得开发**;详细规范规定语义模型与执行约束;路线图规定当前缺口、切片与完成证据。三者不是三套平行设计。遇到冲突,依次采用:`009` 的产品意图 → 本指导对作者负担、场景分级和交付次序的修订 → 详细规范的工程规则 → 附属概念示例。当前代码与测试证明“已实现什么”,不能把代码局限升级为永久语言禁令;原始讨论保留,不据其重新引入已被否决的方案。
### 1.1 方向修订清单
| 容易偏移的做法 | 修订后的要求 | 必须保留的技术约束 |
|---|---|---|
| 先做完整知识治理平台,再给作者使用 | 从一篇可读、可运行、可定位步骤的文档交付,逐层扩展 | 每个已支持路径都有准确的目标和效应边界 |
| 为进入知识库再写 YAML、注册表和索引 | 从源码推导;只有不能推导的领域事实才需作者补充 | 生成物有版本,可重建,可检查来源 |
| 所有逻辑先封装成可登记函数/类 | 一次性逻辑直接写;需要命名、解释或复用时逐步提取 | 作用域、形参、返回与副作用明确 |
| 所有调用先审核、锁定、签发远程凭据 | 本地探索、项目复用、严格业务、远程执行分级 | 精确目标、运行时权限不能被标签或模型绕过 |
| AI 只能搜文档、填工具参数 | AI 可以读步骤、组合、选择候选、局部修改、提取和验证 | 模型的选择必须转成显式目标,由编译器校验 |
| 为“独特”拒绝普通调用或新增更多标记 | 保留简单 payload;让 Markdown 结构提供程序之外的信息 | 无第二套表达式文法,无裸词隐式执行 |
| 核心构造数量不增长就是简单 | 同时检查上下文例外、记忆负担和诊断成本 | 新构造需 ADR;不靠把新规则藏进旧构造绕过审查 |
### 1.2 四个不能互相替代的完成条件
1. **读得懂**:不打开生成图,也能从源文件看出目的、关键步骤、参数角色和限制。
2. **执行同一件事**:标签表达意图,payload 决定计算;运行 trace 能回到源码步骤,不能执行另一个同名目标。
3. **改得动**:人或 AI 能修改一个明确步骤,看到影响与验证结果,不必重写整份文档或同步多份签名。
4. **复用得对**:找到已有能力后实际调用它;不满足条件时给出具体拒绝原因,而非用复制源码掩盖失败。
“更适合 AI”是待验证的产品假设,不是 Markdown 文件后缀自动赋予的性质。正确性和作者成本优先于 token 下降;错误复用更便宜不算优化。
## 2. 语法审查的保留、修正与暂缓
以下裁决针对审查结论的适用范围,不重写历史实验记录。旧文档中的原型、性能数值和当时的 `Value`/AST 限制,不能直接当作 v2.1 的规范或测试结果。
| 审查材料 | 保留的洞见 | 需要修正的外推 / 本轮处置 |
|---|---|---|
| [函数即命名](function-as-naming-philosophy.md) | 从正文计算出发,命名应降低理解和复用成本;避免无意义包装 | “具名给值缺失”是历史观察,当前有具名参数;替换模型是教学解释,不意味着禁止递归、前向引用或必须文本展开 |
| [方括号作为标签](bracket-as-label-evaluation.md) | 描述与 payload 共址;标签帮助解释、检索和拆步骤 | Classic 冲突是迁移历史,不据此恢复默认 `[键](集合)`;不强制每个常量或子表达式都有标签 |
| [圆括号与可读调用](paren-call-and-readable-invocation.md) | 调用标记应明确;保留 `f(args)` 的局部可读性 | 原型撤回不代表现有版本缺少该能力;Marqdo 的独特性不依赖消灭熟悉的表达式形式 |
| [从标记推导调用](call-syntax-from-marks.md) | 语义成分有明确标记;自然语言是连接与解释,不参与猜测调用 | 持久跨文档接口优先具名实参;短而稳定的位置参数仍合法。推断参数的声明次序变化属于接口变化,不承诺任意润色都无影响 |
| [环境参数](ambient-parameters-evaluation.md) | 参数来源应可见,避免调用者隐式环境影响复用 | 文档顶部已否决 L0 裸“执行”触发,正文旧建议不能重新生效;文件级常量也须有明确绑定与依赖,不变成动态作用域 |
| [函数作为值](functions-as-values-evaluation.md) | 区分名称数据、一等函数、有限查表;避免无需求增加核心复杂度 | “匿名函数必不能索引”“动态调用必然破坏契约”不是普遍定理。将来可研究稳定节点身份与运行时契约;本轮不引入闭包,也不永久禁止 |
| [函数作为表格](function-as-table-semantics.md) | 数据表几何有既定含义;契约表不可另造一份参数声明 | 不把表格全部变成函数,也不把“现有实现不支持”写成“表格不能计算”;有限决策表先评估库方案,只有明确角色和歧义测试后才讨论语言扩展 |
| [核心表面](core-surface.md)、[分层](layers.md) | 核心小、标记可解释、构造有测试与准入流程 | 清单中的旧取元/循环说明需随迁移更新;固定数量不等于低认知成本,守卫通过也不证明文档语义正确 |
| [链接设计](link-syntax.md)、[告警疲劳](warning-fatigue-control.md) | 单一 payload 文法;标签漂移可提示;默认安静、按需严格 | 标签不是纯粹可丢弃的注释,也不是事实证明;不做每次运行重复的批准仪式,不靠词汇相似度证明描述与代码一致 |
### 2.1 继续冻结的语法边界
- 默认 `[]()` 是描述包裹 payload;旧取元只能在显式历史兼容路径下解释。现行取元用 `access(...)` 等已支持形式;循环使用明确遍历载荷。
- `[]()` 不等于“仅函数调用”:计算、取元、调用、遍历、叙述引用都需要各自语义角色,不能只收集 call 边就宣称完成知识步骤。
- 正文引用与可执行位置有不同调度权限。普通句子不因出现“执行”“发送”或工具名而运行;正文解析成引用也不自动求值。
- 不把所有 `#` 解释成某种知识对象,或把继承悄悄变成实例关系。标题的既有语义必须兼容,IR 可区分 Type、Entity、Fact、Function。
- 不给同一参数增加正文声明、签名表、工具 schema 三套作者真相。规范签名和工具 schema 是投影;契约表补充类型、约束和说明,不偷偷增加形参。
- 可读源文件是硬要求;普通 Markdown 渲染器是否把含空格/嵌套表达式的链接渲染成可点击链接是另一件事。不能承诺全部标准渲染器理解执行语义。
### 2.2 哪些编辑不能当成“只是改文案”
不含语义标记的普通叙述润色,应保持执行结果和实现摘要;标签改名应保留 payload 行为,但更新展示/检索内容。反引号声明、首次出现顺序、标题名称/层级、粗斜体、表格几何、契约、来源和适用范围的改变则可能影响程序或知识可信性。编辑器必须展示真实差异,不能统一标为 prose-only。
标签漂移诊断应说明“描述或实现可能需要复核”,不能自动替作者改写业务意图。自然语言一致性检查可作辅助建议,确定性检查仍需可定位的符号、类型、契约或测试证据。
## 3. 作者工作流:先写清楚,再获得复用能力
### 3.1 一次性计算不需要预先建知识模型
下面是当前默认语法的完整最小程序。无模式开关、无项目注册、无知识 ID、无锁文件。
```markdown
# main
这是演示订单,单价与数量直接写在计算处。
**小计 = [两件商品的小计](2 * 30)**
> print text=`小计`
```
可读意图和精确计算共址。这个标签值得保留,因为它说明本次计算的业务角色;不要求把 `2`、`30`、乘法分别命名。
### 3.2 需要解释或复用时才提取命名能力
```markdown
## 商品小计
根据购买数量`数量`和商品单价`单价`计算小计。
*[按数量与单价计算](数量 * 单价)*
# main
计算同一笔演示订单。
**小计 = [两件商品的小计](商品小计(数量=2, 单价=30))**
> print text=`小计`
```
两个完整程序在本轮本地现有 `target/debug/marqdo` 上分别以 Tree 和 Bytecode 执行,均输出 `60`。这仅验证基础语法,不证明步骤身份、重构工具或 Agent 闭环已经实现;也不是全仓测试报告。可将各块保存为 `.mq.md` 后用 `marqdo run 文件 --backend tree` / `--backend bytecode` 复核。
**后续工具目标**:从选中表达式提取为标题单元,推导自由变量为参数、保持求值顺序与 effect 次数、生成具名调用,并给出可审阅补丁。反向内联也应保留契约和来源关联;无法证明安全的捕获变量、递归、控制流、动态目标或有副作用表达式,先拒绝自动变换并说明原因,不伪称等价。
### 3.3 跨文档复用与事实说明分别增长
当第二篇文档需要这段计算,才提取模块并显式 import;不要为十行单文件强制创建 `corpus/knowledge/apps` 目录树。项目索引按约定发现,明确边界或外部来源时再加入配置。
当“商品小计”依赖政策、时间、币种等条件,再就地补契约与来源。简单乘法不要求假造现实来源;“某商店当前折扣为九折”则不能仅凭函数返回 `0.9` 声称真实。
正文可以说明结果为何成立,目标是引用同一能力和同一次受控执行的结果,而非手抄另一份公式。正文引用 AST、结果投影和绑定身份尚需开发;完整业务链使用[目标示例](../next/Marqdo_Executable_Knowledge_Example.md)验收,不把它冒充当前全部可运行的教程。
### 3.4 维护时看到知识变化,而不只是文件变化
目标维护流程:修改上游规则 → 显示受影响的计算、正文陈述和消费者 → 执行相关测试 → 展示结果/证据/接口各自变化 → 按使用策略接受更新。普通显示文案变更不应触发全库业务审批;证据过期也不必使无关纯工具全部失效。
## 4. 人维护语义,编译器维护机械关联
| 信息 | 作者责任 | 编译器 / 工具责任 |
|---|---|---|
| 目的与步骤 | 有帮助的标题、叙述、标签;避免空泛重复 | 保留源位置和层级,生成步骤投影,不要求手工节点注册 |
| 输入输出 | 一份参数来源和必要契约;领域单位不能靠猜 | 推断规范签名、检查调用、生成 schema 和签名视图 |
| 目标与依赖 | 显式 import、可读名称、必要消歧 | 绑定唯一 SymbolId,生成依赖边与闭包;不要求手写 ID |
| 效应 | 扩展作者声明宿主能力;业务作者必要时收窄允许范围 | 汇总直接及传递效应;未知不得推断 pure;运行时执行能力上限 |
| 事实与来源 | 原始资料、范围、有效期、人工审阅等不可推导信息 | 关联来源、记录验证事件、传播失效;不将文件路径视为事实证明 |
| 身份与版本 | 有意移动/更名时确认必要迁移 | 区分身份与内容摘要;报告歧义,不靠猜测维持假稳定 |
| view / AI 索引 | 不维护第二份可执行描述 | 同一语义模型投影;显示生成代、验证政策和缺失字段 |
生成信息不等于免费:首次编译、缓存修复、错误定位都要可理解。失败时应回到源文档中可修改的位置,而不是只报内部 Artifact 字段名。
稳定身份要诚实:同一次编译内引用和 trace 必须一致;普通文本编辑不应打乱无关节点;复制相似步骤、跨文件移动等无法唯一识别时,要求确认迁移或明确生成新身份。禁止用文本相似度悄悄继承已审核的知识身份。
## 5. AI 原生工作协议:读步骤、改步骤、验证步骤
本节是**待实现的协议约束**,不是新增 CLI 命令清单。优先扩展现有 MLSP、view、EKC 和 Agent 工作簿,不另造一套 Agent 框架或知识库。
### 5.1 发现后的最小上下文包
一次检索返回可展开的上下文卡,而非强制倾倒整个文件或只给函数 schema:
1. 标题路径、任务相关叙述、标签和精确源码片段;
2. SymbolId/步骤节点、source span、源码摘要、生成代;
3. 输入角色、返回、单位、默认值和适用条件;
4. 直接依赖、效应、必要来源及分层验证状态;
5. 支持该能力的例子/测试,相关失败经验、禁用条件和替代能力;
6. 还缺哪些检查、能否在当前 policy 下运行、为何被拒绝。
来源不可用、字段未推导、上下文被截断都须显式标识。按预算可展开依赖,但不能悄悄省略改变适用性或权限的重要信息。原始资料及标签是内容,不是可以覆盖 Agent 策略的指令。
### 5.2 复用、适配、新建的分界
- **REUSE**:AI 可根据任务选候选,提交精确目标与输入;resolver 确认目标、契约、适用性、版本和 effect,执行既有制品。复用不靠“没有生成文件”推断,必须有实际调用 trace。
- **ADAPT**:已有能力接近但不适用;说明差异,保留依赖/来源关联,在局部副本或补丁中改变必要部分,再验证。不为了通过测试改写原始来源或放宽全局策略。
- **CREATE**:没有合适候选或明确需要新语义;记录检索范围和失败原因,在任务预算及写权限允许时新建。不能把检索服务故障当作“仓库没有能力”。
- **ASK / STOP**:缺业务决策、权限或关键证据时报告具体缺口。编译器无法决定的真实意图不交给近似匹配默默补全。
AI 并非只能发现和解释。它可以提出精确目标、组合已有能力、改进表达、重构及补测试;不能以自然语言自报正确来替代执行验证,也不能把含糊名称传给后端任意选一个目标。
### 5.3 局部修改的事务边界
编辑请求至少携带目标文件/节点、期望源码摘要、补丁范围和预期行为变化。应用前检查摘要,源已变化则重新定位和审阅,不覆盖用户改动。应用后重新解析受影响文档,生成语义 diff:参数/返回、目标、effect、控制流、证据与依赖是否改变。
对“只改措辞”请求,检测到接口或实现改变时停止自动合并;对“改计算”请求,运行相关正负例并展示影响。原始文本、格式与未知 metadata 尽量保留,不通过整篇重生成来完成一行修改。禁止修改生成图伪装修复源码。
首个试点只支持可确定定位的纯计算步骤与普通函数,不等待通用 AST 编辑器、跨项目事务或完整知识治理。安全拒绝超范围输入也属于验收。
### 5.4 解释和负知识必须有落点
解释结果应关联到“哪一步、用了哪个目标、哪些输入、哪份来源、哪次验证”,区分已执行观察和模型推断。运行 trace 可以证明程序路径,不能证明任意自然语言论证正确。
失败经验需要保存适用范围、触发条件、关联能力、原因与失效时间/版本。例如“此折扣不适用于退款”应在查询定价能力时可见,而不是埋在另一份聊天记录里。先由普通文档与结构化关联承载,不先新增通用推理语言;过期负知识也要撤销,不能永久拦截修复后的能力。
## 6. 渐进严格:不把治理门槛塞进每一行正文
下面是目标政策分级,不是当前已有四种 CLI 模式。政策由项目/宿主配置和调用上下文选定,源文档保持同一种语法。
| 场景 | 必需条件 | 默认不要求 |
|---|---|---|
| 本地探索、单文件运行 | 明确语法与目标、已有运行时契约、宿主能力限制;如实显示未知状态 | lock、来源、ready 晋升、远程签名句柄 |
| 项目内自动复用 | 精确绑定、输入/适用性检查、效应许可、状态满足所选政策、执行 trace | 所有纯工具都有人审证据、每次独立确认 |
| 严格业务/可复现任务 | 相关依赖与证据锁定、必要验证新鲜度、受控环境和审计;明确不可重放部分 | 对无关文案变化重审整个项目 |
| 远程/多租户/不受信调用方 | 上述相关约束,加可信授权主体、范围、服务端能力上限、撤销/期限与防伪设计 | 把客户端提交的 `allow_effects` 当授权本身 |
`ready` 是“对某项 policy 和输入/上下文已具备复用条件”,不是永久万能认证。未验证的本地草稿可以被检索、查看和按明确权限试跑;不能冒充满足严格政策的可复用事实。测试通过与事实证实分别报告。
正文 `check/view static` 不执行外部效应。用户主动打开的纯预览可复用项目或会话已有政策,不要求每个链接弹窗;effectful 运行始终受宿主能力和明确执行上下文控制。锁和摘要是完整性机制,不自动等于远程授权;可信本地引用无需先搭建凭据服务。
## 7. 交付切片:每片都有文档作者与 AI 能看见的结果
编号与[缺口路线图 §7](../roadmap/executable-knowledge-gaps-2026-10-23.md#7-依赖顺序与可合并切片)一致;G 编号沿用现状证据,M0–M6 保留为工程能力映射,不再被理解为必须全部串行完成的墙。
### S0 作者基线与最小语料
- 选定单文件计算、提取函数、两文档引用、表格取元/遍历、业务政策及拒绝复用六类任务;记录当前写法、输出、诊断和作者重复维护项。
- 优先整理 `doc/README`、核心语法卡片、教程与运行示例的版本状态;不要先扩展通用库数量。
- 为最小样例建立无网络门禁。100 单元及更大语料逐步增长,不阻塞首个可读文档切片。
- 完成证据:别人按当前入口能写出正确默认语法;已实现与预期失败分开报告,不能把待实现测试跳过计为成功。
### S1 可读步骤与唯一目标
- 主要落点:`src/parse/`、`src/ast.rs`、`src/sema/`、`src/knowledge/compile.rs`、`src/view/`。
- 在最小故事内联合完成 G01/G03:保留 label、payload、上下文和跨度;每类步骤有输入输出与依赖投影;旧 EKC 查询索引不再覆盖语义图。
- 普通导航、正文引用、可执行表达式、循环分别处理,正文保持惰性。先确保支持范围内同一引用在源码、view、图中是同一个目标,再扩展覆盖范围。
- 完成证据:作者能从渲染步骤返回对应源码;同名目标不误连;计算/取元/循环不是伪造的 call;重复构建可对照;未支持上下文明示。
### S2 确定执行与早期 AI 复用试点
- 主要落点:`src/sema/`、`src/interp.rs`、`src/bytecode/`、`src/mlsp.rs` 与现有 Agent 入口。
- 完成静态普通函数、显式 import、关联函数的 BoundCall 主链;G02 与 G06 的效应安全下限不可延期。小范围可先用明确纯操作白名单,未知路径必须拒绝纯证明,而非猜 pure。
- 实现最小上下文卡与本地绑定引用;以 stub/no-LLM 测试验证协议,然后用现有 Agent 跑相同故事。无需先完成远程鉴权平台或全面来源审核。
- 完成证据:同一需求实际调用既有函数,不新增同义实现;两个后端 trace 对上图中目标;改目标、错误输入、未知效应、权限不足不能静默执行。
### S3 局部编辑、提取与库可读性
- 主要落点:MLSP 编辑/定位、相关 sema/检查入口、`lib/`、`ext/`、教程与测试。
- 按 §5.3 实现受摘要保护的局部修改和语义 diff;实现受限纯表达式提取,或明确标为待实现,不用人工演示冒充工具能力。
- 迁移标准库/扩展时删掉重复包装与噪音标签,保留有意义的业务步骤、契约和负例;中英镜像含义一致。兼容旧调用接口,不用增加旧语法解释救迁移遗漏。
- 完成证据:同义润色不改执行;改反引号声明能检测签名变化;表达式提取前后结果/effect 次数一致;冲突补丁拒绝;CLI、库、扩展与 view 既有能力继续通过。
### S4 业务知识的来源与适用性
- 主要落点:契约、SourceRef/VerificationRecord、验证事件、Agent 候选解释;完成 G05 与 G07 的项目政策部分。
- 选定书店案例的币种、数量边界、会员范围与政策有效期;给 schema、拒绝诊断及可运行负例,不泛化为全能业务规则语言。
- 同步补齐传递效应与相关负知识;生成契约/状态展示,减少作者重复填写。
- 完成证据:同一计算因输入或证据不同而正确通过/拒绝;来源过期不被 `tests=passed` 覆盖;普通纯工具无需虚构 SourceRef。
### S5 变化传播与严格复用
- 主要落点:`src/sema/lock.rs`、图/impact、产物提交与消费者;完成 G04/G08 和严格 handle 复核。
- 区分身份/接口/实现/证据/闭包,给出可读升级 diff;整代快照保证消费者不会读取混代数据。并发读写一旦开放,该一致性就是前置条件,不能等到此片才承认风险。
- 完成证据:修改依赖政策后,下游计算和正文解释进入影响集合;文案变化不误判实现变化;并发编辑或构建崩溃不导致错目标执行;锁不声称重放网络/随机/LLM。
### S6 生态验收与发布
- G10/G11 从 S0 起每片执行;S6 汇总兼容矩阵、真实工作流和打包后冒烟,不把测试留到最后。
- G12 随实际规模需求推进;远程凭据/多租户是有条件的独立交付。它们不阻塞受信本地试点,也不得被本地通过的测试覆盖为“已安全支持”。
- 完成证据:当前默认语法的 lib/ext/CLI/MLSP/view/WASM 等受影响消费者有明确结果;目标示例中的已发布子集实际可运行,未发布部分保留状态;发布声明与证据一一对应。
## 8. 验证 Marqdo 优势,而不只验证组件存在
### 8.1 必须收集的产品指标
| 维度 | 记录方法 | 失败信号 |
|---|---|---|
| 作者负担 | 完成同一任务所需手写声明、重复字段、配置、跳转和确认次数 | 简单本地算式也必须填写制品清单 |
| 阅读与定位 | 给定问题,定位正确步骤/限制的准确率、耗时与上下文量 | 只看 label 会误导,必须打开生成 JSON 才理解源文档 |
| 可修改性 | 修改范围、无关 diff、语义变化检测率、冲突覆盖数 | 为改一步而重生成全文件;措辞调整偷偷改变接口 |
| 复用质量 | 已有能力发现率、实际调用率、重复实现率、误用率 | 检索命中却重新写代码;正确拒绝算成任务失败而被优化掉 |
| 知识可追溯性 | 结果关联目标、步骤、输入、来源和验证的覆盖率 | `tested` 被当作事实正确;解释引用未执行的步骤 |
| 总成本 | 正确完成任务的 token、工具调用、轮次、总耗时及编译成本 | 只报模型 tokens,隐藏额外注册/审核/修复成本 |
### 8.2 对照实验与门槛
1. 固定任务、可访问能力、输入数据、模型版本、工具能力、预算与超时;比较普通 Markdown+代码/RAG、当前 EKC 和新方案。不能给新方案更多现成实现再声称语法更优。
2. 任务包括成功复用、同名冲突、近似但不适用、未知 effect、过期来源、正文不执行、局部修改及库升级。加入自然语言诱导绕过 policy 的负例。
3. 先测确定性协议,再测多次 AI 运行,保留种子(支持时)、原始 trace、版本、失败样本与分布;小样本不夸大收益。
4. 正确目标、无越权和正文无外部 effect 是硬门槛。原有兼容测试不得降低;效率阈值先测基线再登记,不捏造提升百分比。
5. 若作者负担增加或误用率上升,回到交互/语义设计分析原因,不能只用“更多治理更安全”或“模型更便宜”解释过去。
### 8.3 发布声明分层
- “支持新语法”需语法、迁移、双后端与库兼容证据,不意味着完整知识复用已经交付。
- “本地确定性知识复用”需 S1/S2 支持范围内的端到端与拒绝用例;范围外路径显式不支持,不能回落为模糊执行。
- “严格业务知识复用”还需相关 S4/S5 来源、适用性、失效、锁和一致性证据。
- “安全远程知识执行”需额外的授权、能力上限、凭据/撤销及隔离测试;本地 JSON handle 不等于远程安全。
## 9. 每个开发变更必须回答的问题
提交设计或实现时给出一份短而具体的审阅记录:
- 用户要读/写/改/复用的知识是什么?附源文档前后对照,不只给内部结构图。
- 利用了哪种文档原生信息?若只增加通用框架能力,与主线的必要关系是什么?
- 新增了哪些作者必须手工维护的信息?为什么不能从现有语义推导?
- 是否改变标记、作用域、求值顺序、形参顺序、表格几何或正文安全?分别有哪些测试?
- 人、CLI、view、图和 Agent 是否看到同一目标与状态?失败能否回到源码修复?
- AI 的正确复用/局部编辑如何证明?哪些部分仍需模型判断,哪些由编译器决定?
- 标准库和扩展是否先迁移?是否保住既有公开接口、输出与 effect?
- 这是已实现、受限试点还是设计目标?文档和发布声明是否一致?
**准入原则**:内部可以使用成熟编译器、数据库和协议技术;外部必须减少知识在“说明、程序、索引、工具描述”之间的重复翻译。独特性由这条链的实际收益体现,不由新符号数量或与其他语言不同的程度体现。
+3 -1
View File
@@ -51,7 +51,9 @@ Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识
`implements` · `uses` · `depends_on` · `tested_by` · `documented_by` · `constrained_by` · `decided_by` · `supersedes` · `conflicts_with` · `deprecated_by` · `derived_from` · `failed_by` · `related_to`
落盘:`.marqdo/graph/graph.json` · `edges.json` · `index.json`。
落盘(G01 分离后):
- **权威语义图**:`.marqdo/graph/edges.json` · `nodes.json`(`SemanticProject`,含 `authority` 字段)· `steps.json`
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json`
## 5. CLI
@@ -1,5 +1,7 @@
# 语法设计哲学:函数在「代码即文档」里为何水土不服,以及用什么语义取代
> **2026-10-23 审阅裁决**:保留“正文优先、按需命名”的方向;下文语料统计和“具名给值缺失”等判断属于当时快照。当前已有具名实参;“调用即代入”不规定文本展开实现,也不禁止递归。下一阶段以[文档原生指导 §2–3](document-native-development-guide.md#2-语法审查的保留修正与暂缓)的范围和验收为准,本文不是替换整个函数模型的已批准语法提案。
| | |
|---|---|
| 状态 | **Proposed · 哲学层讨论**(不涉及实现,不含语法提案细节) |
@@ -1,5 +1,7 @@
# 语义探析:代码函数能否解释为一张 GFM 表
> **2026-10-23 审阅裁决**:下文 v1.5.2 实验不替代当前回归。保留现有数据表几何与契约表角色,不重复声明参数;“现有实现不支持函数表”不等于表格不能表达计算。有限决策表和生成式签名视图按真实用例评估,见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(未修改任何代码) |
@@ -1,5 +1,7 @@
# 方案评估:函数能否作为变量的一种(函数即表)
> **2026-10-23 审阅裁决**:以下是旧实现约束与方案权衡,不是“匿名函数无法索引”或“动态调用无法检查契约”的普遍结论。一等函数/闭包本轮暂缓而非永久禁止;有限决策表先评估现有库表达,文中建议的新辅助函数不因此成为已实现能力。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(未修改任何代码) |
@@ -1,5 +1,7 @@
# 调用写法评估:`[函数名](参数)` 与更接近人读的调用形式
> **2026-10-23 审阅裁决**:“原型回退”仅描述当时实验,当前 payload 已支持 `f(args)` 和具名实参。旧 Classic 索引冲突不再决定默认语法;保留熟悉的调用形态与文档原生描述并不矛盾。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),不要把本文备选形式当作已批准的新语法。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(原型已验证并已回退,未合入代码) |
@@ -2,7 +2,7 @@
| | |
|---|---|
| 状态 | **实施基线(Draft for Implementation)** |
| 状态 | **目标实施规范;按文档原生指导修订交付与政策分级** |
| 日期 | 2026-10-23 |
| 适用版本 | v2.1 及后续兼容演进 |
| 真实意图来源 | [`009.md`](009.md)、[`Marqdo_Executable_Knowledge_Design.md`](Marqdo_Executable_Knowledge_Design.md)、[`Marqdo_Executable_Knowledge_Example.md`](Marqdo_Executable_Knowledge_Example.md) |
@@ -10,17 +10,17 @@
## 0. 文档地位与执行规则
本文把上述三份文档中的真实产品意图整理为可编码、可测试、可迁移、可验收的开发规范。开发本轮能力时,应以本文和三份意图来源为准;仓库中更早的链接、遮蔽、知识分层、类模型、OKF 或 EKC 文档若与本文冲突,不得据其改变本轮设计。
本文把上述三份文档中的真实产品意图整理为可编码、可测试、可迁移、可验收的开发规范。2026-10-23 的[文档原生开发指导](../design/document-native-development-guide.md)进一步约束作者负担、AI 编辑与复用、场景分级和交付顺序;本文的内部结构不能反向要求作者重复填写注册表、工具 schema 或知识图。仓库中更早的链接、遮蔽、知识分层、类模型、OKF 或 EKC 文档若与上述方向冲突,不得据其改变本轮设计。
优先级从高到低如下:
1. `009.md` 中确认的产品目标与边界;
2. 本文冻结的工程决策、数据结构和验收条件;
3. 两份附属文档中的概念设计与完整示例;
4. 当前代码的兼容事实;
2. [文档原生开发指导](../design/document-native-development-guide.md)对作者体验、政策分级和交付排序的修订;
3. 本文的工程决策、数据结构和验收条件;
4. 两份附属文档中的概念设计与完整示例;
5. 其他旧文档,仅可作为历史背景,不是规范依据。
本文不宣称目标能力已经实现。表格中“当前”表示仓库 v2.0.0 的实际行为,“目标”表示完成相应里程碑后的行为。任何阶段只有在对应的自动化测试、双后端一致性测试和迁移测试全部通过后,才可从“目标”改标为“已实现”。
本文不宣称目标能力已经实现。未另行标日期的“当前”表格与 §2 缺口保留最初 v2.0.0 审计背景,不能继续当作 v2.1 的实时状态:默认 Occlusion、线程局部解析作用域、关联函数与零参路径等已经演进。当前实现判断见[2026-10-23 缺口审计](../roadmap/executable-knowledge-gaps-2026-10-23.md)及对应源码/测试;代码事实证明实现范围,不自动取代产品目标。任何阶段只有在对应的自动化测试、双后端一致性测试和迁移测试全部通过后,才可改标为“已实现”。CLI/API 示意与结构定义仍是目标协议,使用前须核对实现。
---
@@ -56,7 +56,10 @@ Marqdo 不是“能运行 Markdown 中几段代码”的解释器,也不是“
- 代码、依赖、来源或验证状态变化时,影响范围能够被程序找出;
- Tree Interpreter 与 Bytecode VM 对同一已绑定程序产生一致结果和诊断;
- Agent 命中已有且适用的制品时,得到的是可调用句柄,不是让模型复制源码再写一遍;
- 系统从不把 `compiled`、`tested` 或 `source_present` 误报成“现实世界事实已证明正确”。
- 系统从不把 `compiled`、`tested` 或 `source_present` 误报成“现实世界事实已证明正确”;
- 作者能从正文计算开始,按需要提取命名能力与跨文档复用,不先建立知识治理工程;
- 人和 AI 能按标题/步骤获得最小上下文、局部修改并查看语义影响,不必整篇重生成;
- 每个交付切片同时证明阅读、修改或复用的实际收益,而不只证明内部字段存在。
### 1.3 不在本轮目标内
@@ -69,9 +72,17 @@ Marqdo 不是“能运行 Markdown 中几段代码”的解释器,也不是“
- 不把自然语言标签当作授权、契约或事实正确性的依据;
- 不让 EKC、view、check、Agent 各自再次解析源码并形成不同理解。
### 1.4 作者成本与渐进严格
标题、叙述、表格、链接描述和执行语句是作者的主要工作面;符号 ID、步骤 ID、规范签名、效应闭包、工具 schema、图和摘要由工具生成。不能推导的领域条件、来源和许可由作者明确补充,不要求每个纯工具函数都填写事实证据。
本地探索允许无锁运行草稿,但不绕过宿主能力限制;项目自动复用按所选 policy 校验;严格业务再增加必要证据、版本锁和新鲜度;远程/多租户另有可信授权与隔离门槛。这是同一语法上的政策分级,不是新的语法模式。纯预览可复用已授予的项目/会话政策,不做逐链接重复确认。详情见[指导 §6](../design/document-native-development-guide.md#6-渐进严格不把治理门槛塞进每一行正文)。
自然语言标签是发现、解释和局部编辑的重要信息,但不证明 payload 正确。AI 可以选候选、组合、适配、重构及补测试;编译器确定实际绑定、类型和效应,宿主决定能力上限。不得把“不用模型决定语义”误读成“模型只能搜索”。
---
## 2. 当前实现基线与真实缺口
## 2. 初始实现基线与缺口背景(非 v2.1 实时清单)
### 2.1 可以复用的现有基础
@@ -890,6 +901,10 @@ TASK
REUSE 的判据不是“搜索分数超过阈值”,而是候选已经精确绑定、输入满足契约、effect 获得许可、版本策略通过。搜索分数只用于候选排序。
`ready` 是对所选 policy、输入与上下文的判断,不是所有知识必须先获得的全局认证。AI 可以从候选中选择明确目标;歧义不能交给执行器按扫描顺序消解。ADAPT/CREATE 必须遵守任务写权限和预算,缺少业务决策时请求补充,而非擅自改变适用条件。草稿可被发现并在明确权限下探索执行,但不得冒充已通过严格政策的事实。
发现结果应按需包含标题/步骤、源码片段、输入角色、契约、效应、来源、验证缺口和相关失败经验。局部编辑须携带期望源码摘要,应用后检查语义 diff 与相关测试;不以重写整份文档作为默认修复方式。协议及受限试点范围见[指导 §5](../design/document-native-development-guide.md#5-ai-原生工作协议读步骤改步骤验证步骤)。
### 12.4 BoundArtifactHandle
```rust
@@ -906,17 +921,21 @@ pub struct BoundArtifactHandle {
Agent 执行必须携带 handle 和显式输入;runtime 再次核对摘要和权限,防止发现后到执行前目标变化。handle 是能力引用,不包含可由模型修改后悄悄执行的源码副本。
上述结构表达绑定内容,不独自构成远程授权凭据。受信本地调用可先采用精确引用和摘要复核;不受信/远程调用必须另有服务端认可的主体、能力范围、防伪及撤销/期限机制,客户端自报 `accepted_effects` 不能扩大宿主许可。handle 由工具产生,不要求作者维护;是否检查 lock 和来源新鲜度取决于明确的 policy。
### 12.5 Promote 门槛
Agent 新建或适配的知识进入可复用索引前,至少完成:
Agent 新建或适配的知识进入**共享自动复用的 ready 集合**前,按目标 policy 至少完成:
- Parse/Resolve/Type/Contract 通过;
- 声明 effect;
- effect 已由静态绑定与宿主/扩展元数据推导;不能推导时保留 unknown 并按政策拒绝或要求明确能力许可,不要求业务作者抄写闭包;
- pure 逻辑有测试,外部 effect 有 mock/沙箱证明或人工批准;
- 来源型知识附 SourceRef;
- 生命周期从 `draft` 开始;
- 生成者、输入、工具版本、变更 diff 可审计;
- 未达到门槛的内容只在 quarantine/draft index 中可见。
- 未达到门槛的内容保持 draft/quarantine 状态;可在同一权威索引中过滤展示,不另造语义身份。
这是晋升政策,不是普通 `.mq.md` 文件被索引、查看或本地执行的前置注册流程。简单纯计算不强制现实来源;声称业务事实成立的知识不能用测试通过替代所需证据。
---
@@ -1117,7 +1136,7 @@ View 至少展示:
## 17. 分阶段开发计划
每个里程碑都必须形成可独立合并的垂直切片;不得先大规模重构再等待最后一次性验收。
M0–M6 保留为工程能力与验收项目,不再作为顺序排期;部分迁移能力已经完成,状态见[现状审计](../roadmap/executable-knowledge-gaps-2026-10-23.md)。实际工作按[文档原生 S0–S6](../design/document-native-development-guide.md#7-交付切片每片都有文档作者与-ai-能看见的结果)形成可独立合并的垂直切片:早期联动 M1/M2/M3/M5 的安全子集,交付可读步骤和真实复用,不能等 M4 全部做完才让作者或 Agent 使用。100 单元生成器逐步增长,不阻塞最小故事;不得先大规模重构再等待最后一次性验收。
### M0:语义冻结与测试生成器
@@ -1218,7 +1237,7 @@ View 至少展示:
- 图中 calls 边与实际运行 trace 的静态目标一致;
- Agent 命中 ready 制品时执行 handle,不生成新函数;
- 只有模糊候选时不能直接执行;
- 未验证、过期、effect 不允许的制品不会被标记为 REUSE ready。
- 不满足所选验证政策、已过相关有效期或 effect 不允许的制品不会被标记为该 policy 下的 REUSE ready;本地探索不冒充严格验证。
### M6:迁移默认值与发布
@@ -1241,6 +1260,8 @@ View 至少展示:
## 18. 文件级实施清单
下表是目标职责映射,不是“所有文件尚未创建”的任务表。`src/project/`、`src/sema/` 和部分 API 已存在,先检查对应缺口与测试,再增量修改;不要依照旧“新建”措辞重复搭建模块或移走仍被消费者使用的能力。
| 文件/模块 | 修改 |
|---|---|
| `src/ast.rs` | 增加 SyntaxNodeId;`Occluded` 迁为 `Named`;承载 Narrative AST 的最小引用 |
@@ -1372,6 +1393,8 @@ View 至少展示:
- 总 token、工具调用、修复轮次和耗时;
- 回答能否追溯到 SymbolId、digest、输入和来源。
同时记录作者手写声明/重复字段/配置数量、阅读定位准确率、语义步骤修改范围、无关 diff、并发补丁冲突和首次写作成本。比较时各方案应获得同等现有能力与输入信息,不向新方案额外提供答案;将编译和人工准备成本计入总成本。先通过正确性与权限硬门槛,再讨论 token 和速度收益,参见[指导 §8](../design/document-native-development-guide.md#8-验证-marqdo-优势而不只验证组件存在)。
### 20.3 发布门槛
- 核心确定性套件 100% 通过;
@@ -1385,6 +1408,8 @@ View 至少展示:
不要只报告平均值;保存失败样本、任务定义、环境、置信区间和版本摘要。
以上按发布宣称的能力范围执行。语法兼容、本地确定性复用、严格业务复用、远程执行分别有独立证据,不以一个总体 `done` 替代。M0–M6 保留为工程能力检查项,实际交付顺序采用[修订路线 S0–S6](../roadmap/executable-knowledge-gaps-2026-10-23.md#7-依赖顺序与可合并切片):早期完成一篇文档的读/执行/复用闭环,再增加治理深度;任何已开放执行路径都不能延后安全门禁。
---
## 21. 书店示例的最终验收链
@@ -0,0 +1,230 @@
# Marqdo 现状与规划缺口:从可执行文档到可复用知识
| | |
|---|---|
| 状态 | 现状审计与下一阶段规划;不是已实现能力声明 |
| 审计基线 | `main` / `434be9f`,2026-10-23;后续改动须重新核验对应判断 |
| 产品意图 | [009.md](../next/009.md) · [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md) · [完整示例](../next/Marqdo_Executable_Knowledge_Example.md) |
| 目标 | **代码即文档,文档即知识库,知识库可执行,可执行知识可复用** |
| 方向修订 | 2026-10-23:按[文档原生开发指导](../design/document-native-development-guide.md)重排交付,G01–G12 保留为缺口证据,不等于作者必须经历的治理流程 |
## 1. 本文解决什么问题
仓库已经拥有语言运行时、双后端、标准库、扩展、文档站、EKC、Agent 和一批语义制品结构。现有[详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)定义了目标架构和 M0–M6,但它主要写于目标能力尚未落地之时;现在照它逐项勾选,容易把“结构存在”“CLI 可调用”“目标闭环成立”混为一谈。本文只补**现状与目标之间尚未被规划成可验证闭环的工作**。语法和产品目标仍以前述意图文档为准;旧文档中的 Classic 链接取元、单体知识类、或另一套知识索引不应反向规定新语义。
本轮判断以源码、可定位的测试和文档状态为证据。`done` 表示有可运行入口和回归测试;`partial` 表示有结构或单一路径,仍不满足产品判据;`design` 表示主要存在于文档和目标示例。**不能把能解析、能运行、能检索、能验证事实视作同一个结论。**
### 1.1 对上一版规划排序的修正
上一版把内部工程完整度放在主要位置,直到 S6/S7 才验收 Agent 复用和作者体验,容易造成“先建治理平台,再证明文档有用”的偏差。本版改为从可读步骤、确定执行和早期本地复用向外扩展;每片同时交付源码示例、诊断和消费者可见结果。工程基础按切片所需完成,不降低已开放路径的安全要求。
P0/P1/P2 分类改为缺口领域,不再按编号整组串行:G06 的未知效应安全下限必须进入最早执行试点,G09 的本地复用也不再等锁和远程授权全部完成。复杂业务的证据、严格锁和远程凭据按使用场景增加,不能强加给每个单文件程序。每片还须记录作者重复声明数、局部修改范围和实际复用结果,指标见[指导 §8](../design/document-native-development-guide.md#8-验证-marqdo-优势而不只验证组件存在)。
## 2. 设计思想落实为四个可证伪承诺
| 承诺 | 必须由什么证明 | 当前判定 |
|---|---|---|
| 代码即文档 | 一份 `.mq.md` 的叙述、契约、示例、可执行语句由同一解析结果驱动;改变语义会让说明/示例失配可见 | 运行与 view 已有基础;正文引用尚未进入完整语义 AST(partial) |
| 文档即知识库 | 可寻址的事实、规则、步骤、来源、适用范围和关系由编译器生成;不同消费者读取同一身份和图 | 项目索引与 Artifact 投影已起步;双图和占位字段仍存在(partial) |
| 知识库可执行 | 引用先绑定、检查参数/契约/效应/版本,再由运行时执行**绑定的目标**;正文默认不触发副作用 | CLI 可解析、运行时可执行,但两条路径未闭合(partial) |
| 可执行知识可复用 | Agent 发现候选后取得有条件、可失效的句柄,实际调用既有制品;trace 记录符号、摘要、输入和结果 | MLSP 有初版 handle;EKC/Agent 尚未统一到此协议(partial) |
这四条有语义依赖,但应在受限故事中逐步贯通,不是四个必须全部做完才能进入下一层的大项目。阅读体验和检索召回不能代替绑定;绑定不能证明知识内容正确;执行成功不能证明已经复用既有知识。
## 3. 仓库能力盘点与规范 M0–M6 的真实进度
| 既有里程碑 | 可复用成果 | 仍未满足的完成条件 |
|---|---|---|
| M0 语义与测试 | Occlusion 已为默认;[语法测试规程](../next/Marqdo_Executable_Knowledge_Testing.md)和部分金样存在;标准库、扩展库已经迁移 | `tests/executable_knowledge/` 系统夹具、100 单元生成器、导航/正文/效应负例矩阵未形成独立门禁 |
| M1 项目身份 | [`src/project/mod.rs`](../../src/project/mod.rs)确定项目根和扫描顺序;[`src/sema/symbols.rs`](../../src/sema/symbols.rs)产生 ModuleId/SymbolId;CLI `knowledge inspect/resolve` 可用 | 身份保留、移动/重命名、symlink/重复扫描、大项目增量与错误聚合还需完整策略和测试 |
| M2 统一链接与调用 | 裸零参路径和关联函数已有 Tree/Bytecode、CLI 金样;`Expr::Occluded` 已承载标签和 payload | [`src/ast.rs`](../../src/ast.rs)仍无统一 Named/正文引用节点;[`src/sema/ir.rs`](../../src/sema/ir.rs)只提取执行体部分调用;运行时仍独立按名称寻找调用目标 |
| M3 语义制品 | SemanticArtifact、EffectSet、SourceRef、VerificationRecord、JSON 投影已存在 | 适用性、来源证据、单位、真实验证状态、完整效应闭包与规范摘要仍缺;字段存在不代表语义已实现 |
| M4 锁与影响 | `knowledge lock/impact` 可用;[`src/sema/lock.rs`](../../src/sema/lock.rs)支持原子写入和反向依赖查询 | 锁只比较 artifact 摘要;目标、接口、实现、证据、传递闭包变更未独立报告;正文/证据边不在影响闭包内 |
| M5 消费者 | view 显示部分语义信息;MLSP 提供 `artifact.*`;EKC/Agent 有各自检索与复用能力 | 同一图/同一绑定尚未贯通;Agent 对 ready 的判定与执行句柄未被强制;trace 不足以证明实际复用 |
| M6 迁移与发布 | 全仓新语法迁移、`--legacy-markup` 入口、v2.1.0 发布已完成 | 发布不等于 M0–M5 已完成;目标示例仍注明“尚不能完整运行”,100 单元与 Agent 对照实验未过 |
`examples/executable-knowledge/README.md` 是目标示例,仍明确说明类函数、统一 `Named<T>` 和步骤图的完整运行是设计目标。它不得作为“产品闭环已完成”的发版证据。
### 3.1 相邻路线如何进入本规划
| 仓库区域 | 当前路线状态 | 与可执行知识主线的连接点 |
|---|---|---|
| Interpreter / 标准库 | Tree、Bytecode、`lib/` 与中英库有大量金样;[Mid2](stdlib-mid2.md)已完成 | 作为 BoundCall、效应声明、签名与迁移回归的基础;不为本路线重做通用库 |
| Web / 浏览器 | [Web](ext-web.md) W 波与 [WASM](browser-wasm.md) C 波已落地 | 作为 view/静态投影和宿主能力消费者;知识引用不能在静态导出或浏览器预览中偷跑服务端 effect |
| Agent / LLM / 沙盒 | [Agent](ext-agent-optimize.md) Wave B 有局部待项;[优化 O 波](ext-ai-optimize.md)已完成 | 工作簿、OKF、沙盒可复用;S2 接本地 bound handle,S4/S5 增强政策;不另建平行知识身份 |
| 外联 / Notebook | [外联 F4](foreign-v2.md)和[会话 D4–D5](notebook-session.md)尚有余项 | 外部内核、持久状态和重放需显式建模为 effect/环境依赖;不能把会话结果当纯制品缓存 |
| 领域扩展 | [Quantum Q8c](ext-quantum.md)等剩余项属领域体验;[宿主 H4b](ext-hosting.md)为可选 HTTP 能力 | 不阻塞语义主链;但扩展元数据与插件调用必须参加 G06/G10 的 effect 和兼容性门禁 |
这些路线各有自己的完成定义。本文不将其余项全部吸收到下一版核心范围;只规定它们与统一语义层交互时必须遵守的契约。
## 4. 语义一致性缺口:消除错误的语义真相
### G01 两份图与同名输出路径
**证据。** [`src/knowledge/compile.rs`](../../src/knowledge/compile.rs)先调用 `compile_project` 并写语义投影,随后重新用 `extract_graph` 从源码提取旧 EKC 图。后者的 `write_projections` 再写 `graph/edges.json`;[`src/knowledge/graph.rs`](../../src/knowledge/graph.rs)的调用边按短名选首个匹配符号。由此“语义边”和“检索边”既不是同一事实,也会争用同一个文件名。
**规划缺口。** 详细规范要求 EKC 是 `SemanticProject` 投影,却未给出**并行迁移期间的文件命名、读取优先级、冲突检测与废弃时点**。只新增语义图不解决消费者继续读旧边的问题。
**决策与交付。** 明确一个权威 `SemanticProject`;图边按稳定 `SymbolId/ArtifactId` 生成。旧检索索引仅含查询优化数据,不再自行确定 calls/uses。若迁移期保留旧 JSON,放入独立版本化路径并声明其非执行依据。`knowledge compile`、`view`、`check`、`impact`、MLSP、Agent 对同一引用应报告同一目标及诊断。
**验收。** 制造两个模块同名函数并让调用只 import 其中一个;语义图、CLI resolve、Tree/Bytecode trace、view 和 Agent handle 必须指向同一 ID。编译两次输出字节一致;生成物中没有同名文件被后续投影覆盖。
### G02 绑定没有成为执行的前置条件
**证据。** [`src/main.rs`](../../src/main.rs)的 `knowledge resolve` 走项目索引;[`src/mlsp.rs`](../../src/mlsp.rs)的 `link.resolve` 通过 artifact 名字/后缀匹配;[`src/interp.rs`](../../src/interp.rs)仍有自身的 `eval_path_call` 和函数查找;[`src/bytecode/`](../../src/bytecode/)也有独立调用实现。`compile_project` 目前只将同模块无接收者调用识别为静态依赖,其余记为 `external_or_dynamic`。这几条路径存在真实分叉。
**规划缺口。** 现有规范提出 Bound IR,但缺少**最小可合并的执行切面**以及动态调用的明确边界。不能先宣称图边覆盖执行调用,再等待后端改造。
**决策与交付。** 先让显式 import、普通函数、关联函数这三个静态路径通过唯一 resolver,生成 `BoundCall { target, signature, source_span, required_effects }`。Tree 和 Bytecode 只消费 BoundCall;确需动态解析的路径使用独立 `DynamicCall`,在图/诊断中显式标记,不能假装已绑定。`run/check/knowledge resolve/MLSP` 使用相同 import 范围和歧义规则。
**验收。** 同名跨模块、重命名、缺 import、实例方法误用、动态目标分别有稳定诊断;任一静态 trace 中执行的 SymbolId 与编译图边一致。错误不得因后端不同而变成另一目标。
### G03 `[]()` 只有标签,还没有完整知识步骤
**证据。** [`src/ast.rs`](../../src/ast.rs)保留 `Expr::Occluded`;[`src/parse/prose.rs`](../../src/parse/prose.rs)扫描粗体、斜体和反引号,但没有完整 Markdown 正文链接 AST。[`src/sema/ir.rs`](../../src/sema/ir.rs)当前 KnowledgeRef/KnowledgeStep 主要由调用点提取,步骤 `kind` 为 `call`;取元、推导、遍历、正文、导航尚未同等进入图。目标示例列出的 observe/derive/iterate/narrate 不能由现有投影证明。
**规划缺口。** 缺少正文 inline 的位置、逃逸、代码围栏、标准 URL 与知识引用的**一套无副作用解析协议**,以及 `[]()` 在表达式、循环和正文的统一节点身份。
**决策与交付。** 保留现有 payload 表达式解析器;为上下文建立稳定 SyntaxNodeId 与 `Named<T>`/等价 lowering。明确 `NavigationLink`、`NarrativeRef`、`ExecutableNamed`、`LoopNamed` 的互斥分类及 span。正文引用只解析和验证;主动纯预览可使用项目/会话既有政策,不要求逐链接确认;外部 effect 仍需明确执行上下文与宿主能力许可。各类型步骤的输入、输出、依赖和角色由编译器推导;标签是阅读、检索和局部编辑的上下文,但不参与授权和寻址。作者不手工填写步骤 ID 或生成图。
**验收。** 一份文档同时含 URL、锚点、带空格/嵌套括号载荷、围栏、行内代码、取元、计算、循环、正文引用;生成的 ref/step 数、分类和跨度稳定,正文 `run/check/view static` 不发生外部 effect。
### G04 生成物写入不是整代快照
**证据。** [`src/sema/ir.rs`](../../src/sema/ir.rs)将语义文件写到临时目录后,逐个删除并移动 `project.json`、`symbols.json`、`refs.json`、`artifacts/`、`graph/`、`verification/`;[`src/knowledge/compile.rs`](../../src/knowledge/compile.rs)再写旧投影。这不是消费者可原子读取的整代快照,构建中途可能看到混合版本。
**规划缺口。** 规范写了“原子写入”,未规定**整代提交、读者快照、失败恢复和旧版本保留**。
**决策与交付。** 使用带 schema/build-id 的代目录与原子指针或等价快照机制;所有消费者一次选择一代,读完整个结果后才释放。生成物可删除重建;崩溃后只能看到旧完整代或新完整代。
**验收。** 在写每个投影文件时注入故障并并发读取;不得出现 `project` 属于 A 代而 `edges` 属于 B 代,失败后旧代仍可读。
## 5. 可信执行缺口:按场景落实验证门槛
### G05 来源、适用性和验证状态仍是占位投影
**证据。** [`src/sema/ir.rs`](../../src/sema/ir.rs)给函数固定 `"no explicit applicability constraints"`,`SourceRef` 主要指向定义它的源码,`evidence` 摘要来自契约文本;验证记录固定 `contract=unchecked`、`tests=unknown`、`evidence=unverified`、`domain=unreviewed`。现有 [`src/knowledge/lifecycle.rs`](../../src/knowledge/lifecycle.rs)的 `verify` 是另一套 EKC 检查。因此“有 SourceRef”并不表示政策原文被关联或核验。
**规划缺口。** 规范列出字段和七层状态,但没有定义**作者如何写来源/适用性、如何证明测试确实覆盖此制品、谁可将 domain 从 unreviewed 提升、何时失效**。不确定现实真假的结论必须保留 unknown。
**决策与交付。** 用现有 Markdown/frontmatter/契约表表达可选的 `source`、有效区间、地域/单位/输入前提,形成可解析 schema;把编译、静态检查、实跑测试、来源内容、人工领域审阅作为独立证据事件。定义状态迁移、撤销和失效规则;生成物记录证据文件/测试运行摘要,不允许 CLI/Agent 自报 `verified`。
**验收。** 政策原文改变而函数未改时 evidence 状态下降;来源删除、过期、输入不满足分别给不同诊断;无来源的纯工具函数可运行,但不能被宣称为已证实业务事实。
### G06 效应识别存在“未知即纯”的漏洞
**证据。** [`src/sema/ir.rs`](../../src/sema/ir.rs)的 `effects_for_call` 依据名字前缀猜测 `fs/net/llm` 等,其余返回 `pure`;`direct_effects` 只汇总直接调用。未知插件、别名、包装函数和传递调用可能因此被标作纯。[`src/mlsp.rs`](../../src/mlsp.rs)以该集合做 `artifact.execute` 的效应拒绝。
**规划缺口。** 详细规范定义 EffectSet,却没有给出**跨宿主函数、标准库、扩展 ABI、动态调用的权威效应注册表和未知效应策略**。
**决策与交付。** 内核/标准库/插件元数据声明 effects,绑定后做调用图闭包;动态或缺元数据为 `unknown`,需要显式能力授予,不得降为 pure。`view` 静态、`verify pure`、Agent ready 门槛使用同一集合。实际宿主能力限制仍在执行时强制。
**验收。** 用自定义名字包住写文件/网络/插件调用;静态 effect 必须传递到入口,默认 pure 策略拒绝执行。循环调用图收敛;未知动态调用拒绝 pure 证明。
### G07 绑定句柄未表达可复用的授权与适用性
**证据。** [`src/mlsp.rs`](../../src/mlsp.rs)的 `artifact.bind` 主要检查目标唯一及可选 digest,返回 `artifact_id/digest/project/policy/effects`;它没有要求 ready、契约、适用性或来源状态。`artifact.execute` 重编译比对摘要后按 `display_name` 最后一段调用解释器;调用者提交的 `allow_effects` 会变为宿主能力。现阶段这是实验性执行接口,不是可信复用协议。
**规划缺口。** 缺少句柄的**发行者、主体、策略、输入约束、能力上限、过期/撤销、并发源变更**模型;也缺少“绑定到精确嵌套函数”在 runtime 的保证。
**决策与交付。** `bind` 必须验证 SymbolId、签名、输入、已声明适用性、所选验证政策及 effect 上限;政策要求锁时检查 lock。`execute` 复核同一目标与状态并按绑定符号调用。受信本地调用先采用精确绑定引用和摘要复核,不强制搭建签发服务;远程/多租户/不受信调用再加入可信发行者、主体、范围、期限/撤销及防伪机制。客户端参数不是远程授权来源;运行时能力上限始终由宿主强制。响应如实显示政策和未知状态,作者不手写 handle。
**验收。** 本地先覆盖改参数、改依赖、改效应策略、同名嵌套函数和并发源码变更,不得错调用或越权;严格政策增加来源与锁变更,远程增加伪造/过期/撤销测试。`ready` 必须注明相应 policy 与条件,不是全局永久认证。
### G08 锁定与影响分析未覆盖知识变化
**证据。** [`src/sema/lock.rs`](../../src/sema/lock.rs)的 lock 文件虽然写出 interface/implementation/evidence/dependencies,但检查时只比较 `artifact` 摘要。该摘要在 [`src/sema/ir.rs`](../../src/sema/ir.rs)只组合本地 interface/implementation/evidence,没有传递依赖闭包;impact 的边也只来自已识别的本地调用。`knowledge impact` 与语义 impact 是两套命令/图。
**规划缺口。** 未定义**锁的审阅单位、变更分类、依赖 SCC、证据变更如何传播到正文、升级冲突处理**。
**决策与交付。** 分别持久化 target/interface/implementation/evidence/closure 摘要,SCC 按确定规则求闭包;strict 对未审阅目标变化失败。impact 用同一图沿 calls/depends_on/supported_by/narrates 反向传播,并说明为何被影响。每次 lock update 留下人可审阅的差异报告。
**验收。** 本地函数源码不变而下游税率规则变了时 closure 变化;只改描述不混同事实证据变化;来源变更影响客服说明;同一个查询在 CLI、MLSP、view 展示相同受影响 ID 集合。
## 6. 作者与生态缺口:从早期切片持续验证
### G09 Agent 仍可能把候选当作可执行知识
**证据。** [`src/knowledge/reuse.rs`](../../src/knowledge/reuse.rs)、[`plugins/agent/`](../../plugins/agent/)和 `ext/ai/agent.mq.md` 有各自的检索、near-match、工作簿/Skill 固化流程;[`src/mlsp.rs`](../../src/mlsp.rs)另有 artifact handle。现有 [Agent 路线图](ext-agent-optimize.md)主要跟踪工作簿、路由和评测,没有把“发现→精确绑定→验证→调用既有制品→记账”设成强制路径。
**规划缺口。** 需要明确 **REUSE、ADAPT、CREATE 的进入条件与失败后分流**,以及“避免重复生成”用什么客观指标衡量。
**决策与交付。** near/soft-match 只能供候选发现;Agent 可以选择并提交精确候选,REUSE 前必须经同一 resolver 和 policy 得到 bound handle。不可用则记录原因,按权限进入 ADAPT/CREATE 或请求补充决策。新草稿可被发现、查看和在本地明确权限下试跑,进入共享自动复用的 ready 集合前按政策验证晋升。先提供含步骤、源码、约束、负知识和验证状态的最小上下文卡,再支持带期望摘要的局部补丁和语义 diff,避免整篇再生成。trace 包含任务、候选、选定 SymbolId、所有相关摘要、输入摘要、policy、实际执行结果及因果依赖;私密输入只存可审计脱敏摘要。
**验收。** 已有适用能力时实际调用而不新建同义函数;同名未消歧、违反所选政策的过期/未验证候选、权限不足不能自动执行。局部修改不覆盖并发编辑;只改措辞却改变签名必须可见。同样任务与预算下报告重复实现率、错误复用率、发现率、成功率、编辑范围、作者维护成本及失败样本。
### G10 标准库、扩展库与发布物缺少跨层一致性门禁
**证据。** [语法测试规程](../next/Marqdo_Executable_Knowledge_Testing.md)覆盖了部分零参路径金样;仓库有大量 `lib/`、`ext/`、`public/` 和示例。`.github/workflows/` 目前只有 release/pages,没有对每次提交运行可执行知识项目夹具的 CI;[目标示例](../../examples/executable-knowledge/README.md)仍不可端到端运行。现有 [lib/ext 路线图](lib-ext-code-as-docs.md)的历史“链接取元”已被 v2.1 默认遮蔽语义取代,`done` 不代表今天的知识引用集成已完成。
**规划缺口。** 对新语义没有固定的**全仓兼容矩阵、跨平台发布前检查、示例可运行状态标签、回滚规则**。
**决策与交付。** 分层门禁:parser/sema → Tree/Bytecode → 标准库中英镜像 → 扩展插件装载 → CLI/MLSP/view/静态导出 → 一体化书店/订单示例。每个负例也断言诊断码和副作用计数。每次语义变化先迁移 `lib/ext` 并保持 stdout 与 effect,不通过扩展旧语义来掩盖库的过时写法。CI 在 main 的 PR/push 执行无网络核心套件;需要插件/浏览器的平台测试单列结果;发布前检查包内标准库/扩展与二进制版本匹配。
**验收。** `cargo test --locked`、gold 单线程、可执行知识项目夹具、CLI JSON schema 和每个平台打包后冒烟通过;文档示例一旦标为可运行,CI 每次执行。没有 `skip` 可以充当核心能力成功证据。
### G11 文档状态本身缺少统一真相
**证据。** [`doc/README.md`](../README.md)仍将较早 mapping 称为“现行运行时”,将 [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)的 v2.0.0 基线直接当下一阶段实施依据;多个旧路线图的 `done` 和新语义目标相互交错。README 的 v2.1 链接/投影描述可能被误读为完整可执行知识系统已交付。
**规划缺口。** 缺少文档版本、优先级、状态和实现证据之间的**维护协议**。这会让人和 Agent 从旧文档学回被迁移掉的语义。
**决策与交付。** 文档顶部标明“目标规范 / 已实现 / 历史兼容 / 被取代”及适用版本;在 `doc/README.md` 提供唯一入口。每项能力把规范段落、代码位置、测试、示例、发布版本关联起来;任何 `done` 必须列出验收命令及结果。旧内容可以保留历史价值,但搜索结果与 Skill/教程默认指向当前规范。制定文档可运行片段的抽取或同步测试,降低“文字与实现分叉”。
**验收。** 新贡献者只读 README、doc 索引和 Skill 能写出默认语义的运行样例;旧取元写法在当前教学材料不会以默认形式出现;变更语法时 CI 能发现核心规范与构造卡片失配。
### G12 项目规模、缓存与权限边界尚无可量化 SLO
**证据。** [`src/project/mod.rs`](../../src/project/mod.rs)每次扫描目录;[`src/sema/ir.rs`](../../src/sema/ir.rs)重新读取并解析项目文件;view 和 MLSP 每次查询也可重新编译。`ProjectRoot::source_files` 特别处理 symlink,但没有明确的路径环/别名去重、资源上限与增量失效协议。当前规范虽列 1k/10k/100k 指标,却没有基线值和可接受阈值。
**规划缺口。** 项目发现、Symlink、外部 import、生成目录、并发编辑、overlay、缓存一致性和诊断聚合缺少一份可测试的**规模与信任边界规格**。
**决策与交付。** 先定义约定式项目发现、源文件唯一性、遍历深度/文件大小上限、外部来源许可和增量失效键;单文件与普通项目免额外注册,只有边界无法由约定表达时才要求显式 manifest。再建立 100/1k/10k 项目生成器、冷/热构建计时和内存基线;超过阈值的操作降级为明确诊断,不能静默跳过或返回旧图。MLSP overlay 要么被安全纳入快照,要么显式拒绝且不宣称即时编辑验证。
**验收。** 扫描顺序与重复路径不改变身份;symlink 环不挂起;修改单文件只失效正确下游;缓存损坏后结果与全量构建一致;目标机器上的时间与内存阈值由基准结果确定后固化进 CI。
## 7. 依赖顺序与可合并切片
| 切片 | 前置 | 作者 / AI 可见交付及工程关联 | 可复核的完成证据 |
|---|---|---|---|
| S0 作者基线与最小语料 | 无 | 六类实际写作/复用任务、当前语法入口、无网络最小门禁(G10/G11) | **已落地**:[tests/executable_knowledge/](../../tests/executable_knowledge/README.md) + `cargo test --test executable_knowledge` |
| S1 可读步骤与唯一目标 | S0 | 一份文档的源码/步骤/view 联动;统一 resolver、图与上下文节点(G01/G03) | **已落地**:G01 双图分离;G03 步骤 kind + NarrativeRef(`11-narrative-ref`)+ view 导航;同名 import resolve |
| S2 确定执行与早期 AI 复用 | S1 | BoundCall 双后端、最小上下文卡、本地 handle 与现有 Agent 试点(G02/G06/G07/G09 的安全子集) | **已落地**:G02 BoundCall;G06 效应;G07 MLSP bind/execute;eng_reuse `bind_required` |
| S3 局部编辑与库可读性 | S1–S2 | 摘要保护的局部补丁、语义 diff、受限纯表达式提取;lib/ext 示例优化(G03/G09/G10/G11) | **已落地**:`artifact.patch` + wording 回滚;`artifact.extract_pure` 纯表达式预览;全库润色仍可选后续 |
| S4 业务知识与适用性 | S2;与 S3 可交错 | 书店契约、来源/验证事件、传递效应及政策、负知识(G05/G06/G07/G09) | **已落地**:来源/过期;`13-bookstore` + `examples/executable-knowledge` 发票链 `113`;负知识文档 |
| S5 变化传播与严格复用 | S1–S2/S4 | 分类摘要、SCC 闭包、整代快照、impact、严格 handle 复核(G04/G08) | **已落地**:`generations/`+`CURRENT`;锁 `classes`+`closure`;impact 含 narrates;依赖变更推动 closure |
| S6 生态验收与发布 | 按发布声明选择 S1–S5 范围 | 全仓兼容矩阵、可运行端到端示例、平台冒烟、作者/AI 指标(G10/G11/G12) | **已落地**:CI;扫描上限;100 单元语料门禁;CLI version/check/knowledge 冒烟 |
每切片完成时同时更新 [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)的实现状态、相关示例及本表;只改文档状态不算完成。S1/S2 先用**无 LLM、无网络、无插件**测试证明确定性协议,随即接现有 Agent 验证实际复用;不等所有治理工程结束。G10/G11 是每片持续门禁,100 单元语料逐片增长;G04 的并发一致性必须在开放并发消费前完成,不能因为列在 S5 就忽略前置风险。
G12 大规模优化与远程凭据服务按场景安排;远程执行若开放,其授权测试就是硬前置。H4b MCP HTTP、dense embedding、更多语言糖和全面本体推理均不阻塞本地链。任务拆分、模块落点和作者验收详见[指导 §7](../design/document-native-development-guide.md#7-交付切片每片都有文档作者与-ai-能看见的结果)。
## 8. 横向验收场景与发布条件
### 8.1 必须固定的四个故事
1. **两文档事实**:李白出生年份定义、同名冲突、显式 import、正文惰性引用、来源变更、锁拒绝;验证“文档即知识库”。
2. **订单定价**:来源政策→税率/折扣→多步计算→正文解释;对每个 `[]()` 生成步骤,修改上游后 `impact` 找全下游;验证“知识可执行”。
3. **权限反例**:取一个无明显危险词的用户函数,内部经标准库/插件包装写文件或请求网络;静态未知或效应传递阻止静态预览和纯策略执行;验证默认安全。
4. **Agent 已有能力复用**:先存在 ready 制品,再给相似需求;Agent 发现后精确绑定并执行,trace 中有 SymbolId、摘要与结果,仓库不增加同义函数;再加入过期/不适用候选并验证拒绝。
每个故事覆盖成功与拒绝、Tree/Bytecode(执行适用时)、CLI/MLSP、view、生成图及清缓存重建。旧版本迁移另保存输入、输出、诊断和 effect 的对照;不以“测试通过”掩盖输出语义改变。
### 8.2 完整可执行知识声明的门槛
- 100 单元确定性夹具和四个故事在 CI 全绿;正文静态路径外部 effect 计数为零。
- 静态调用图与运行 trace 的 target ID 一致;两后端的值、目标、诊断一致;动态调用在结果中明确标记。
- 任何模糊/同名、unknown effect、无效适用性、过期 lock、缺失必需证据都不能被自动标为 ready。
- Agent 在已有适用能力的任务上实际执行 bound handle,且错误复用率、重复实现率与当前 EKC 基线同时报告;保存数据和失败样本。
- `lib/ext/public/examples` 当前语义全仓通过,安装包中的 CLI、标准库、扩展库版本和示例行为一致。
- README、教程、Skill 与目标示例明确区分已实现、实验性与设计态;运行示例由 CI 执行。
这些是完整链的门槛,不要求每次修补版等完整链全部完成。受限本地复用可在 S1/S2 对应正负例和兼容门禁通过后按精确范围发布;严格业务复用增加 S4/S5,远程执行另验授权和隔离,见[分层声明](../design/document-native-development-guide.md#83-发布声明分层)。未完成项不得被笼统“可执行知识已实现”覆盖。目前仍应表述为:**v2.1 已提供文件级新语法、项目索引与语义制品初版;知识验证和 Agent 复用闭环仍在建设。**
## 9. 明确的非目标
- 不要求作者为每个函数写一份重复的机器配置;优先从现有 Markdown、契约表和调用解析推导。
- 不要求每个取元、循环或纯工具函数都附现实世界证据;只有声称业务事实成立或需要高信任复用时才提高证据门槛。
- 不以 LLM 的模糊判断替代符号绑定、类型检查或权限授予;LLM 可选择精确候选、组合、编辑、适配和补测试,编译器校验实际目标与语义,宿主执行权限上限。
- 不把 `Type`、`Entity`、`Fact`、`Function` 强行折叠为“类”;兼容现有 `#`/`##` 表面,语义类型在 IR 中清楚区分。
- 不把 v2.1 的发布回退为未完成,也不把历史路线图的 `done` 自动推广为本路线的完成。
+28 -19
View File
@@ -1,35 +1,44 @@
# 可执行知识系统示例:订单含税总额
这是 [可执行知识系统设计](../../doc/design/executable-knowledge-system.md) 的目标示例。
它刻意展示 `[]()` 不只包“知识函数”:同一套语法同时命名取元、循环、推导、跨文件调用和正文结论。
这是 [可执行知识系统设计](../../doc/design/executable-knowledge-system.md) 的目标示例,
已按当前 occlusion 语法落地为**可运行**订单链(Tree / Bytecode)。
| 文件 | 图中的职责 | 关键步骤 |
|---|---|---|
| `corpus/tax-policy-2026.md` | E:证据 | 税率原文 |
| `schema/order.mq.md` | C:概念 | 订单/订单行字段与单位 |
| `knowledge/tax-2026.mq.md` | K:原子知识 | `[标准税率](0.13)` 及来源 |
| `knowledge/tax-2026.mq.md` | K:原子知识 | `标准税率.查询` + `sources:` |
| `knowledge/negative-refund.mq.md` | 负知识 | 折扣不适用于退款 |
| `capabilities/order-pricing.mq.md` | D:推导知识 | 取元、调用、循环、汇总 |
| `docs/invoice-answer.mq.md` | N:叙述知识 | 用同一个计算给人可读的回答 |
| `docs/invoice-answer.mq.md` | N:叙述知识 | 含税结论 + NarrativeRef |
## 运行
```bash
marqdo run examples/executable-knowledge/docs/invoice-answer.mq.md --backend tree
marqdo run examples/executable-knowledge/docs/invoice-answer.mq.md --backend bytecode
# → 113
marqdo knowledge examples/executable-knowledge -o /tmp/ek
marqdo knowledge impact "标准税率.查询" examples/executable-knowledge --json
```
门禁:`cargo test --test executable_knowledge s4_examples_bookstore_chain_runs_both_backends --locked`
## 读法
`[]()` 的每一次出现都是 `Named<T>`:
`[]()` 的每一次出现都是命名步骤(observe / derive / iterate / call / narrate):
```markdown
[订单行金额](at(行, "金额")) # observe
[本行含税价](订单行金额 * (1 + 税率)) # derive
[逐个订单行](遍历 订单.行 为 行) # iterate
[含税总价](pricing.订单定价.含税总额(订单)) # reuse / narrate
[订单行金额](access(行, "金额")) # observe
[本行含税价](金额 * (1 + 税率)) # derive
[逐个订单行](遍历 行列表 为 行) # iterate
这张订单的含税总额是[含税总价](总额)。 # narrate
```
它们不是四种语法。`()` 中仍是原有的取元、算术、循环和调用;`[]` 让每一步同时可读、可查、
可在图中定位。当前实现尚不能完整运行该目标形式(类函数、统一 `Named<T>`、步骤图仍是设计目标),
但它给出了实际项目中应当写成什么样子。
## 运行状态
## 预期闭环
1. `check` 从每个 `[]()` 提取观测、推导、遍历和调用依赖;
2. `view` 在“含税总额”旁显示所经过的订单行、标准税率和税率原文;
3. 税率原文变更时,`impact` 找到原子税率、订单定价、发票回答中的每一个命名步骤;
4. `verify` 只重算 pure 步骤,不执行写入或发送等 `act` 步骤;
5. agent 通过 catalog 得到“已有订单定价能力”和其证据链,不必从自然语言猜测。
| 子集 | 状态 | 证据 |
|---|---|---|
| 发票含税链双后端 `113` | **可运行** | 上表命令 / EK 门禁 |
| 来源 `sourced` + impact 下游 | **可运行** | knowledge 投影 + impact |
| 负知识文档 | **已收录** | `knowledge/negative-refund.mq.md`(发现层;非执行目标) |
@@ -1,27 +1,32 @@
---
markup: occlusion
id: capability.order-pricing
type: Capability
import:
tax: ../knowledge/tax-2026.mq.md
order: ../schema/order.mq.md
---
# 订单定价
## 含税价
+ `行`
按订单行取未税金额与品类,套用税率后汇总含税总额。
**金额 = [订单行金额](at(行, "金额"))**
**品类 = [订单行品类](at(行, "品类"))**
**税率 = [适用税率](tax.标准税率.查询(品类))**
## 含税价
`行`
**金额 = [订单行金额](access(行, "金额"))**
**品类 = [订单行品类](access(行, "品类"))**
**税率 = > tax.标准税率.查询 品类=`品类`**
**结果 = [本行含税价](金额 * (1 + 税率))**
**结果**
*结果*
## 含税总额
+ `订单`
- [逐个订单行](遍历 订单.行 为 行)
**行含税价 = [计算本行含税价](订单定价.含税价(行))**
`订单`
**总额 = [汇总全部行含税价](sum(行含税价))**
**总额**
**行列表 = [订单行列表](access(订单, "行"))**
`总额` = 0
- [逐个订单行](遍历 行列表 为 行)
**行含税价 = > 订单定价.含税价 行=`行`**
**总额 = [累加](总额 + 行含税价)**
*总额*
@@ -4,12 +4,16 @@ id: document.invoice-answer
type: Answer
import:
pricing: ../capabilities/order-pricing.mq.md
json: lib/json.mq.md
---
# 发票回答
# main
**总额 = [订单的含税总价](access(pricing.订单定价.含税总额(订单), "订单的含税总价"))**
发票回答:演示订单一行图书,未税金额 100。
`订单` = > json.parse text={"行":[{"金额":100,"品类":"书"}]}
**总额 = > pricing.订单定价.含税总额 订单=`订单`**
这张订单的含税总额是[含税总价](总额)。
> view 应可展开:含税总价 → 汇总全部行含税价 → 逐个订单行 → 本行含税价 → 适用税率 → 税率原文。
> print text=`总额`
@@ -0,0 +1,14 @@
---
markup: occlusion
id: knowledge.negative.discount-not-for-refund
type: Failure
title: 折扣不适用于退款
---
# 折扣不适用于退款
负知识:退款结算不得套用会员折扣。Agent 复用折扣能力时应拒绝该适用面。
## 说明
*[不适用](false)*
@@ -1,18 +1,20 @@
---
markup: occlusion
id: knowledge.tax.standard-2026
type: Fact
sources:
- ../corpus/tax-policy-2026.md#2026 年标准增值税率
applicability:
region: CN
valid_until: 2099-12-31
---
# 标准税率
当前政策下的标准增值税率。`品类` 预留给差异化税率;本演示固定返回标准税率。
## 查询
+ `品类`
| 返回 | 类型 | 来源 |
|---|---|---|
| 0.13 | number | corpus/tax-policy-2026.md#2026 年标准增值税率 |
`品类`
**税率 = [标准税率](0.13)**
**税率**
*[标准税率](0.13)*
+1 -1
View File
@@ -1 +1 @@
2.1.0
2.1.1
+72 -7
View File
@@ -77,7 +77,10 @@ fn resolve_marqdo_root(start: &str) -> PathBuf {
}
for _ in 0..8 {
let cand = cur.join(".marqdo");
if cand.join("engineering.yaml").exists() || cand.join("graph/graph.json").exists() {
if cand.join("engineering.yaml").exists()
|| cand.join("ekc/graph/graph.json").exists()
|| cand.join("graph/graph.json").exists()
{
return cand;
}
if !cur.pop() {
@@ -289,7 +292,10 @@ pub fn eng_preflight(args: &Value) -> Result<Value, String> {
.map(PathBuf::from)
.unwrap_or_else(|| resolve_marqdo_root(root));
if !marqdo.join("engineering.yaml").exists() && !marqdo.join("graph/graph.json").exists() {
if !marqdo.join("engineering.yaml").exists()
&& !marqdo.join("ekc/graph/graph.json").exists()
&& !marqdo.join("graph/graph.json").exists()
{
return Ok(json!({
"status": "missing_knowledge",
"create_allowed": false,
@@ -424,14 +430,73 @@ pub fn eng_preflight(args: &Value) -> Result<Value, String> {
}))
}
/// `agent_eng_reuse` — alias of preflight focused on decision payload.
/// `agent_eng_reuse` — discovery + REUSE|ADAPT|CREATE decision.
///
/// Scores and capability names are **not** executable targets (G02/G07).
/// When decision is REUSE/ADAPT, callers must `artifact.bind` a
/// `bind_targets[]` entry before `artifact.execute`.
pub fn eng_reuse(args: &Value) -> Result<Value, String> {
let mut pf = eng_preflight(args)?;
if let Some(obj) = pf.as_object_mut() {
obj.insert(
"protocol".into(),
json!("REUSE|ADAPT|CREATE"),
);
obj.insert("protocol".into(), json!("REUSE|ADAPT|CREATE"));
obj.insert("discovery_only".into(), json!(true));
let decision = obj
.get("decision")
.and_then(|v| v.as_str())
.unwrap_or("")
.to_ascii_uppercase();
let bind_required = matches!(decision.as_str(), "REUSE" | "ADAPT");
obj.insert("bind_required".into(), json!(bind_required));
let mut targets = Vec::new();
if let Some(cands) = obj.get("candidates").and_then(|v| v.as_array()) {
for c in cands {
if let Some(impls) = c.get("implemented_by").and_then(|v| v.as_array()) {
for t in impls {
if let Some(s) = t.as_str() {
if !s.is_empty() {
targets.push(json!({
"query": s,
"via": "implemented_by",
"capability": c.get("name"),
"note": "pass query to artifact.bind then artifact.execute",
}));
}
}
}
}
if let Some(id) = c.get("id").and_then(|v| v.as_str()) {
if id.contains(':') || id.contains('.') {
targets.push(json!({
"query": id,
"via": "candidate_id",
"capability": c.get("name"),
"note": "pass query to artifact.bind then artifact.execute",
}));
}
}
}
}
// Dedup by query
let mut seen = std::collections::HashSet::new();
targets.retain(|t| {
t.get("query")
.and_then(|q| q.as_str())
.map(|q| seen.insert(q.to_string()))
.unwrap_or(false)
});
obj.insert("bind_targets".into(), json!(targets));
if bind_required {
let mut reasons = obj
.get("reason")
.cloned()
.unwrap_or_else(|| json!([]));
if let Some(arr) = reasons.as_array_mut() {
arr.push(json!(
"scores are discovery-only; bind SymbolId/handle before execute (G02/G07)"
));
}
obj.insert("reason".into(), reasons);
}
}
Ok(pf)
}
+5 -3
View File
@@ -63,12 +63,14 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
## Occlusion syntax (v2.0.0)
## Occlusion syntax (v2.1 default)
A file with frontmatter `markup: occlusion` (or `标记: 遮蔽`) reads `[x](y)` as **occlusion**, not index — in that file only (`MARQDO_MARKUP=occlusion` sets the process default; classic files are unchanged).
**Default:** unmarked sources and `markup: occlusion` / `标记: 遮蔽` treat `[x](y)` as **occlusion** (description wraps payload), not classic index. Explicit Classic / `--legacy-markup` is a transition path only — do not teach `[键](集合)` as the default. Prefer `access(集合, 键)` for reads.
Executable-knowledge author baseline (six tasks, offline gate): [`tests/executable_knowledge/`](../../tests/executable_knowledge/README.md). Design goals ≠ shipped knowledge reuse; see [`doc/design/document-native-development-guide.md`](../../doc/design/document-native-development-guide.md).
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
- `[顾客留存率](0.42)` · `[总价](at(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
- `[顾客留存率](0.42)` · `[总价](access(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
- Read maps/lists with `access(集合, 键)` (aliases `取` / `取值`): `[第二项](access(列, 2))`.
- Foreach: `- [篮子里的每个果子](遍历 篮子 为 果)` (accepts `遍历`/`for` and `为`/`as`/`in`).
- Calls inside `()`: `加(1)` / `加(1, 2)` / `加一 号(31)` / `txt.str_trim(" x ")` — `)` terminates, commas optional.
+71 -18
View File
@@ -28,11 +28,14 @@ struct FlatFun {
path_index: HashMap<Vec<String>, usize>,
/// Short name from frontmatter `use` → path segments.
uses: HashMap<String, Vec<String>>,
/// Module collection scope (G02): bare-name resolve must not cross imports.
scope: u32,
}
pub fn compile_module(path: Option<&Path>, module: &Module) -> Result<Program> {
let mut flat = Vec::new();
let _exports = collect_module_tree(module, &mut flat);
let mut next_scope = 1u32;
let _exports = collect_module_tree(module, &mut flat, 0, &mut next_scope);
if flat.is_empty() {
bail!("bytecode: no functions to compile");
}
@@ -106,10 +109,21 @@ pub fn compile_module(path: Option<&Path>, module: &Module) -> Result<Program> {
/// Collect `module` and its imports into `flat`.
/// Returns relative export paths within this module (e.g. `["parse"]`, `["agent","step"]`).
fn collect_module_tree(module: &Module, flat: &mut Vec<FlatFun>) -> HashMap<Vec<String>, usize> {
///
/// Each module gets a distinct `scope` id. Bare-name `resolve_call` only searches
/// within the caller's scope so imported same-named functions cannot be silently
/// selected (BoundCall / G02). Cross-module calls must use `bind.member` paths.
fn collect_module_tree(
module: &Module,
flat: &mut Vec<FlatFun>,
scope: u32,
next_scope: &mut u32,
) -> HashMap<Vec<String>, usize> {
let mut path_index = HashMap::new();
for (bind, dep) in &module.import_modules {
let dep_exports = collect_module_tree(dep, flat);
let child_scope = *next_scope;
*next_scope += 1;
let dep_exports = collect_module_tree(dep, flat, child_scope, next_scope);
for (rel, idx) in dep_exports {
let mut full = Vec::with_capacity(rel.len() + 1);
full.push(bind.clone());
@@ -124,11 +138,23 @@ fn collect_module_tree(module: &Module, flat: &mut Vec<FlatFun>) -> HashMap<Vec<
.map(|u| (u.bind.clone(), u.path.clone()))
.collect();
let start = flat.len();
let mut exports = HashMap::new();
for fun in &module.functions {
let id = collect_fun(fun, None, flat, &path_index, &uses);
let id = collect_fun(fun, None, flat, &path_index, &uses, scope);
export_tree(&mut exports, &[], id, flat);
}
// Same-module BoundCall paths (`Type.member`) must be visible to siblings.
for (rel, idx) in &exports {
path_index.insert(rel.clone(), *idx);
}
for f in &mut flat[start..] {
if f.scope == scope {
for (rel, idx) in &exports {
f.path_index.insert(rel.clone(), *idx);
}
}
}
exports
}
@@ -152,6 +178,7 @@ fn collect_fun(
flat: &mut Vec<FlatFun>,
path_index: &HashMap<Vec<String>, usize>,
uses: &HashMap<String, Vec<String>>,
scope: u32,
) -> usize {
let id = flat.len();
flat.push(FlatFun {
@@ -166,10 +193,11 @@ fn collect_fun(
span: fun.span,
path_index: path_index.clone(),
uses: uses.clone(),
scope,
});
let mut child_ids = Vec::new();
for child in &fun.children {
child_ids.push(collect_fun(child, Some(id), flat, path_index, uses));
child_ids.push(collect_fun(child, Some(id), flat, path_index, uses, scope));
}
flat[id].children = child_ids;
id
@@ -323,28 +351,42 @@ impl<'a> FnCompiler<'a> {
s
}
/// BoundCall-equivalent bare-name resolve (G02): only the caller's module
/// scope. Imported functions are reachable solely via `path_index` paths.
fn resolve_call(&self, name: &str) -> Result<usize> {
let fun = &self.flat[self.fn_id];
let scope = fun.scope;
for &cid in &fun.children {
if self.flat[cid].name == name {
if self.flat[cid].name == name && self.flat[cid].scope == scope {
return Ok(cid);
}
}
let mut parent = fun.parent;
while let Some(pid) = parent {
if self.flat[pid].scope != scope {
break;
}
for &cid in &self.flat[pid].children {
if self.flat[cid].name == name {
if self.flat[cid].name == name && self.flat[cid].scope == scope {
return Ok(cid);
}
}
parent = self.flat[pid].parent;
}
let mut matches = Vec::new();
for (i, f) in self.flat.iter().enumerate() {
if f.parent.is_none() && f.name == name {
return Ok(i);
if f.parent.is_none() && f.scope == scope && f.name == name {
matches.push(i);
}
}
Err(self.err(format!("unknown function `{name}`")))
match matches.as_slice() {
[only] => Ok(*only),
[] => Err(self.err(format!("unknown function `{name}`"))),
_ => Err(self.err(format!(
"ambiguous function `{name}`: {} candidates in this module; use an explicit path",
matches.len()
))),
}
}
fn compile_stmt(&mut self, stmt: &Stmt) -> Result<()> {
@@ -470,13 +512,20 @@ impl<'a> FnCompiler<'a> {
}
fn compile_call(&mut self, call: &CallExpr, as_stmt: bool) -> Result<()> {
// Mirror `sema::bind::resolve_for_exec` (G02 BoundCall):
// static → Op::Call(fid); dynamic → MethodCall / CallFn / PluginCall.
let mut call = call
.with_modifiers_expanded()
.map_err(|m| self.err(m))?;
if let Some(recv) = &call.receiver {
return self.compile_method_call(recv, &call, as_stmt);
}
if let Some(path) = &call.path {
// Bare dotted callee `a.b`: if `a` is a local variable, it is a method
// receiver (Python-style unified namespace); otherwise it's a library path.
if path.len() == 2 && self.locals.contains_key(&path[0]) {
// Local-var method sugar before import path (same as Tree / resolve_for_exec).
if path.len() == 2
&& self.locals.contains_key(&path[0])
&& !self.flat[self.fn_id].path_index.keys().any(|p| p.first() == Some(&path[0]))
{
let recv = path[0].clone();
return self.compile_method_call(&recv, &call, as_stmt);
}
@@ -488,10 +537,6 @@ impl<'a> FnCompiler<'a> {
call.callee =
crate::aliases::normalize_call_callee_and_args(&call.callee, &mut call.args);
if let Some(recv) = &call.receiver {
return self.compile_method_call(recv, &call, as_stmt);
}
match call.callee.as_str() {
"print" => {
let text_expr = call
@@ -648,9 +693,17 @@ impl<'a> FnCompiler<'a> {
_ => {}
}
// BoundCall bare name (same-module scope only) or DynamicCall plugin.
match self.resolve_call(&call.callee) {
Ok(fid) => self.compile_user_call(fid, &call, as_stmt),
Err(_) => self.compile_plugin_call(&call, as_stmt),
Err(err) => {
let msg = format!("{err:#}");
if msg.contains("ambiguous function") {
return Err(err);
}
// DynamicCall(Plugin): unresolved bare names may be runtime plugins.
self.compile_plugin_call(&call, as_stmt)
}
}
}
+156 -100
View File
@@ -15,7 +15,7 @@ use crate::builtin::{
};
use crate::debug::{emit_trace, DebugController};
use crate::diagnostics::{bail_at, Span};
use crate::host::{call_host, HostContext, HostFn};
use crate::host::{call_host, HostContext};
use crate::input_feed::InputFeed;
use crate::capture::{
BranchHit, CallFrame, LoopFrame, LoopHit, LoopIter, StmtEvent, StmtEventKind, ViewTrace,
@@ -349,6 +349,17 @@ impl Interpreter {
) -> Result<Value> {
let fun = find_function_anywhere(module, name)
.ok_or_else(|| self.err(format!("unknown function `{name}`")))?;
self.invoke_bound_function(module, fun, args)
}
/// Run an already-bound function node (SymbolId / source-line identity).
/// Prefer this over name lookup so nested same-named functions cannot drift (G07).
pub fn invoke_bound_function(
&mut self,
module: &Module,
fun: &Function,
args: &[(String, Value)],
) -> Result<Value> {
self.run_function(module, fun, Env::new(), args, false)
}
@@ -1169,34 +1180,150 @@ impl Interpreter {
return self.eval_method_call(module, fun, env, recv_name, &call.callee, &ev_args);
}
// Local-var method sugar (`a.b` when `a` is in env) before BoundCall path resolve.
if let Some(path) = &call.path {
// Bare dotted callee `a.b`: if `a` is a local variable, it is a method
// receiver (Python-style unified namespace); otherwise it's a library path.
if path.len() == 2 && env.get(&path[0]).is_some() {
if path.len() == 2
&& env.get(&path[0]).is_some()
&& !module.import_modules.contains_key(&path[0])
{
let recv = path[0].clone();
let method = path[1].clone();
return self.eval_method_call(module, fun, env, &recv, &method, &ev_args);
}
return self.eval_path_call(module, path, &ev_args);
}
if let Some(u) = module.uses.iter().find(|u| u.bind == call.callee) {
return self.eval_path_call(module, &u.path, &ev_args);
use crate::sema::bind::{resolve_for_exec, DynamicReason, ExecTarget};
match resolve_for_exec(module, fun, &call) {
ExecTarget::Local(target) => {
self.eval_bound_function_call(module, fun, env, target, &ev_args)
}
ExecTarget::Import {
lib: lib_mod,
fun: target,
..
} => self.eval_bound_function_call(lib_mod, fun, env, target, &ev_args),
ExecTarget::Builtin(name) => self.eval_builtin_call(name, &ev_args),
ExecTarget::Host(hf) => {
let mut params: Vec<String> =
hf.required_params().iter().map(|s| (*s).to_string()).collect();
for p in hf.optional_params() {
params.push((*p).to_string());
}
let bound = bind_args(&params, &ev_args, true).map_err(|m| self.err(m))?;
for req in hf.required_params() {
if !bound.contains_key(*req) {
return Err(self.err(format!("{} requires `{req}`", hf.name())));
}
}
call_host(&mut self.host, hf, &bound).map_err(|m| self.err(m))
}
ExecTarget::Dynamic {
reason: DynamicReason::CallFn,
..
} => {
let bound = bind_args(&["name".into()], &ev_args, false)
.map_err(|m| self.err(m))?;
let name = match bound.get("name") {
Some(Value::Text(s)) => s.as_str(),
_ => return Err(self.err("call_fn requires text name")),
};
let target = lookup_function(module, fun, name).ok_or_else(|| {
self.err(format!("call_fn: unknown function `{name}`"))
})?;
if !target.params.is_empty() {
return Err(self.err(format!(
"call_fn: `{name}` must have no parameters"
)));
}
self.run_function(module, target, Env::new(), &[], false)
}
ExecTarget::Dynamic {
reason: DynamicReason::Plugin,
name,
} => {
if let Some(reg) = self.host.plugins.get(&name).cloned() {
let bound =
bind_args(&reg.params, &ev_args, false).map_err(|m| self.err(m))?;
return self
.call_plugin_registered(&name, &bound)
.map_err(|m| self.err(m));
}
Err(self.err(format!("unknown function `{name}`")))
}
ExecTarget::Dynamic {
reason: DynamicReason::MethodReceiver,
name,
} => {
if let Some(path) = &call.path {
if path.len() == 2 && env.get(&path[0]).is_some() {
return self.eval_method_call(
module,
fun,
env,
&path[0],
&path[1],
&ev_args,
);
}
}
Err(self.err(format!("unresolved dynamic call `{name}`")))
}
ExecTarget::Unresolved { message, .. } => Err(self.err(message)),
}
}
match call.callee.as_str() {
/// Invoke a function already resolved via [`crate::sema::bind::resolve_for_exec`].
fn eval_bound_function_call(
&mut self,
module: &Module,
caller: &Function,
env: &mut Env,
target: &Function,
ev_args: &[EvArg],
) -> Result<Value> {
let bound =
bind_function_args(self, module, caller, env, &target.params, ev_args, false)
.map_err(|m| self.err(m))?;
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);
}
self.host.push_call_site_line(self.host.current_line);
let result = self.run_function(module, target, call_env, &[], false);
self.host.pop_call_site_line();
let result = result?;
if target.is_object() {
Ok(tag_instance(&target.name, result))
} else {
Ok(result)
}
}
fn eval_builtin_call(&mut self, name: &str, ev_args: &[EvArg]) -> Result<Value> {
match name {
"print" => {
let bound = bind_args(&["text".into()], &ev_args, false)
let bound = bind_args(&["text".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let text = bound
.get("text")
.map(|v| v.as_display())
.ok_or_else(|| self.err("print requires text (named or positional)"))?;
self.emit_line(&text);
return Ok(Value::None);
Ok(Value::None)
}
"input" => {
let bound = bind_args(&["prompt".into()], &ev_args, true)
let bound = bind_args(&["prompt".into()], ev_args, true)
.map_err(|m| self.err(m))?;
let prompt = bound
.get("prompt")
@@ -1221,52 +1348,52 @@ impl Interpreter {
e
}
})?;
return Ok(Value::Text(line));
Ok(Value::Text(line))
}
"len" => {
let bound = bind_args(&["value".into()], &ev_args, false)
let bound = bind_args(&["value".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let v = bound
.get("value")
.ok_or_else(|| self.err("len requires value"))?;
let n = builtin_len(v).map_err(|m| self.err(m))?;
return Ok(Value::Int(n));
Ok(Value::Int(n))
}
"str" => {
let bound = bind_args(&["value".into()], &ev_args, false)
let bound = bind_args(&["value".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let v = bound
.get("value")
.ok_or_else(|| self.err("str requires value"))?;
return Ok(builtin_str(v));
Ok(builtin_str(v))
}
"int" => {
let bound = bind_args(&["value".into()], &ev_args, false)
let bound = bind_args(&["value".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let v = bound
.get("value")
.ok_or_else(|| self.err("int requires value"))?;
let n = builtin_int(v).map_err(|m| self.err(m))?;
return Ok(Value::Int(n));
Ok(Value::Int(n))
}
"type" => {
let bound = bind_args(&["value".into()], &ev_args, false)
let bound = bind_args(&["value".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let v = bound
.get("value")
.ok_or_else(|| self.err("type requires value"))?;
return Ok(builtin_type(v));
Ok(builtin_type(v))
}
"trim" => {
let bound = bind_args(&["value".into()], &ev_args, false)
let bound = bind_args(&["value".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let v = bound
.get("value")
.ok_or_else(|| self.err("trim requires value"))?;
return builtin_trim(v).map_err(|m| self.err(m));
builtin_trim(v).map_err(|m| self.err(m))
}
"split" => {
let bound = bind_args(&["value".into(), "sep".into()], &ev_args, false)
let bound = bind_args(&["value".into(), "sep".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let value = bound
.get("value")
@@ -1274,10 +1401,10 @@ impl Interpreter {
let sep = bound
.get("sep")
.ok_or_else(|| self.err("split requires sep"))?;
return builtin_split(value, sep).map_err(|m| self.err(m));
builtin_split(value, sep).map_err(|m| self.err(m))
}
"join" => {
let bound = bind_args(&["value".into(), "sep".into()], &ev_args, false)
let bound = bind_args(&["value".into(), "sep".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let value = bound
.get("value")
@@ -1285,10 +1412,10 @@ impl Interpreter {
let sep = bound
.get("sep")
.ok_or_else(|| self.err("join requires sep"))?;
return builtin_join(value, sep).map_err(|m| self.err(m));
builtin_join(value, sep).map_err(|m| self.err(m))
}
"at" => {
let bound = bind_args(&["value".into(), "index".into()], &ev_args, false)
let bound = bind_args(&["value".into(), "index".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let value = bound
.get("value")
@@ -1296,80 +1423,9 @@ impl Interpreter {
let index = bound
.get("index")
.ok_or_else(|| self.err("at requires index"))?;
return builtin_at(value, index).map_err(|m| self.err(m));
builtin_at(value, index).map_err(|m| self.err(m))
}
"call_fn" => {
let bound = bind_args(&["name".into()], &ev_args, false)
.map_err(|m| self.err(m))?;
let name = match bound.get("name") {
Some(Value::Text(s)) => s.as_str(),
_ => return Err(self.err("call_fn requires text name")),
};
let target = lookup_function(module, fun, name).ok_or_else(|| {
self.err(format!("call_fn: unknown function `{name}`"))
})?;
if !target.params.is_empty() {
return Err(self.err(format!(
"call_fn: `{name}` must have no parameters"
)));
}
return self.run_function(module, target, Env::new(), &[], false);
}
other if HostFn::from_name(other).is_some() => {
let hf = HostFn::from_name(other).unwrap();
let mut params: Vec<String> =
hf.required_params().iter().map(|s| (*s).to_string()).collect();
for p in hf.optional_params() {
params.push((*p).to_string());
}
let bound = bind_args(&params, &ev_args, true).map_err(|m| self.err(m))?;
for req in hf.required_params() {
if !bound.contains_key(*req) {
return Err(self.err(format!("{} requires `{req}`", hf.name())));
}
}
return call_host(&mut self.host, hf, &bound).map_err(|m| self.err(m));
}
_ => {}
}
if let Some(reg) = self.host.plugins.get(&call.callee).cloned() {
let bound = bind_args(&reg.params, &ev_args, false).map_err(|m| self.err(m))?;
return self
.call_plugin_registered(&call.callee, &bound)
.map_err(|m| self.err(m));
}
let target = lookup_function(module, fun, &call.callee)
.ok_or_else(|| self.err(format!("unknown function `{}`", call.callee)))?;
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);
}
self.host.push_call_site_line(self.host.current_line);
let result = self.run_function(module, target, call_env, &[], false);
self.host.pop_call_site_line();
let result = result?;
if target.is_object() {
Ok(tag_instance(&target.name, result))
} else {
Ok(result)
other => Err(self.err(format!("unknown builtin `{other}`"))),
}
}
+21 -20
View File
@@ -17,9 +17,9 @@ pub struct KnowledgeOptions {
}
pub fn compile(opts: KnowledgeOptions) -> Result<KnowledgeGraph> {
// The semantic projection is the authoritative machine-facing graph. The
// older EKC catalog below remains intentionally available as a compatible
// human/retrieval projection, but never substitutes for semantic binding.
// Authoritative execution/binding graph: SemanticProject under `graph/`.
// Legacy EKC retrieval catalog writes only under `ekc/` and must never
// overwrite `graph/edges.json` (G01).
let semantic_root = if opts.path.is_file() {
opts.path.parent().unwrap_or_else(|| Path::new(".")).to_path_buf()
} else {
@@ -38,7 +38,7 @@ pub fn compile(opts: KnowledgeOptions) -> Result<KnowledgeGraph> {
let graph = extract_graph(&extract_opts)?;
write_projections(&opts.out_dir, &graph)?;
eprintln!(
"marqdo knowledge: {} module(s), {} symbol(s), {} capability(ies), {} knowledge → {}",
"marqdo knowledge: {} module(s), {} symbol(s), {} capability(ies), {} knowledge → {} (semantic graph/; retrieval ekc/)",
graph.modules.len(),
graph.symbols.len(),
graph.capabilities.len(),
@@ -48,12 +48,17 @@ pub fn compile(opts: KnowledgeOptions) -> Result<KnowledgeGraph> {
Ok(graph)
}
/// Directory for the legacy EKC retrieval projection (not execution authority).
pub fn ekc_graph_dir(out_dir: &Path) -> std::path::PathBuf {
out_dir.join("ekc").join("graph")
}
pub fn load_graph(out_dir: &Path) -> Result<KnowledgeGraph> {
let graph_path = out_dir.join("graph").join("graph.json");
let edges_path = out_dir.join("graph").join("edges.json");
let graph_path = ekc_graph_dir(out_dir).join("graph.json");
let edges_path = ekc_graph_dir(out_dir).join("edges.json");
if !graph_path.exists() {
anyhow::bail!(
"no knowledge graph at {} — run `marqdo knowledge` first",
"no EKC retrieval graph at {} — run `marqdo knowledge` first",
graph_path.display()
);
}
@@ -139,14 +144,7 @@ pub fn load_graph(out_dir: &Path) -> Result<KnowledgeGraph> {
}
pub fn ensure_compiled(path: &Path, out_dir: &Path) -> Result<KnowledgeGraph> {
let graph_path = out_dir.join("graph").join("graph.json");
if graph_path.exists() {
// Always refresh from source when path given
return compile(KnowledgeOptions {
path: path.to_path_buf(),
out_dir: out_dir.to_path_buf(),
});
}
// Always refresh from source when path is given.
compile(KnowledgeOptions {
path: path.to_path_buf(),
out_dir: out_dir.to_path_buf(),
@@ -164,7 +162,7 @@ fn write_projections(out_dir: &Path, graph: &KnowledgeGraph) -> Result<()> {
"knowledge/patterns",
"knowledge/failures",
"knowledge/migrations",
"graph",
"ekc/graph",
"agent/policies",
"agent/skills",
"agent/contexts",
@@ -234,20 +232,23 @@ fn write_projections(out_dir: &Path, graph: &KnowledgeGraph) -> Result<()> {
fs::write(&path, body)?;
}
// Graph JSON
// Retrieval-only EKC graph (must not touch authoritative `graph/`).
let ekc = ekc_graph_dir(out_dir);
let graph_json = serde_json::to_string_pretty(&graph.to_graph_json())?;
fs::write(out_dir.join("graph/graph.json"), graph_json)?;
fs::write(ekc.join("graph.json"), graph_json)?;
let edges_json = serde_json::to_string_pretty(&graph.to_edges_json())?;
fs::write(out_dir.join("graph/edges.json"), edges_json)?;
fs::write(ekc.join("edges.json"), edges_json)?;
// Search index
let index = json!({
"type": "Marqdo Knowledge Index",
"role": "retrieval_only",
"note": "Not an execution authority; binding uses graph/edges.json (SemanticProject).",
"generated": { "by": graph.generated_by },
"entries": graph.index_map(),
});
fs::write(
out_dir.join("graph/index.json"),
ekc.join("index.json"),
serde_json::to_string_pretty(&index)?,
)?;
+3 -1
View File
@@ -52,7 +52,9 @@ pub fn find_stale(graph: &KnowledgeGraph, root: &Path) -> Vec<StaleItem> {
if src.exists() {
if let (Ok(meta), Ok(proj_meta)) = (
fs::metadata(&src),
fs::metadata(root.join(".marqdo/graph/graph.json"))
fs::metadata(root.join(".marqdo/ekc/graph/graph.json"))
.or_else(|_| fs::metadata(root.join(".marqdo/graph/graph.json")))
.or_else(|_| fs::metadata(root.join("ekc/graph/graph.json")))
.or_else(|_| fs::metadata(root.join("graph/graph.json"))),
) {
if let (Ok(st), Ok(pt)) = (meta.modified(), proj_meta.modified()) {
+1 -1
View File
@@ -20,7 +20,7 @@ pub mod preflight;
pub mod reuse;
pub mod util;
pub use compile::{compile, ensure_compiled, load_graph, KnowledgeOptions};
pub use compile::{compile, ekc_graph_dir, ensure_compiled, load_graph, KnowledgeOptions};
pub use duplicate::{find_duplicates, format_duplicates_text};
pub use find::{find, find_json, format_find_text};
pub use impact::{format_impact_text, impact, impact_json};
+22
View File
@@ -274,6 +274,25 @@ pub fn format_reuse_text(task: &str, result: &ReuseResult) -> String {
}
pub fn reuse_json(task: &str, result: &ReuseResult) -> Value {
let bind_required = matches!(
result.decision,
ReuseDecision::Reuse | ReuseDecision::Adapt
);
let mut bind_targets = Vec::new();
if let Some(sym) = &result.symbol {
bind_targets.push(json!({
"query": sym,
"via": "reuse.symbol",
"note": "pass query to artifact.bind then artifact.execute",
}));
}
if let Some(src) = &result.source {
bind_targets.push(json!({
"query": src,
"via": "reuse.source",
"note": "pass query to artifact.bind then artifact.execute",
}));
}
json!({
"task": task,
"decision": result.decision.as_str(),
@@ -287,6 +306,9 @@ pub fn reuse_json(task: &str, result: &ReuseResult) -> Value {
"constraints": result.constraints,
"decisions": result.decisions,
"failures": result.failures,
"discovery_only": true,
"bind_required": bind_required,
"bind_targets": bind_targets,
"candidates": result.candidates.iter().map(|c| json!({
"id": c.id,
"kind": c.kind,
+284 -6
View File
@@ -64,17 +64,43 @@ fn dispatch(req: &Value) -> Result<Value, Value> {
Some("artifact.impact") => artifact_impact(&params),
Some("artifact.bind") => artifact_bind(&params),
Some("artifact.execute") => artifact_execute(&params),
Some("artifact.patch") => artifact_patch(&params),
Some("artifact.extract_pure") => artifact_extract_pure(&params),
// `<TAB>` M9: occlusion label search (two-tier vocabulary).
Some("labels.search") => labels_search(&params),
// `<TAB>` M6: one-shot session summary (T1 staleness seen/fixed).
Some("session.summary") => session_summary(),
other => Err(err(
"mlsp.unknown_method",
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute"),
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute / artifact.patch / artifact.extract_pure"),
)),
}
}
fn artifact_extract_pure(params: &Value) -> Result<Value, Value> {
let name = params
.get("name")
.and_then(Value::as_str)
.ok_or_else(|| err("mlsp.bad_request", "artifact.extract_pure 需要 name"))?;
let expression = params
.get("expression")
.and_then(Value::as_str)
.ok_or_else(|| err("mlsp.bad_request", "artifact.extract_pure 需要 expression"))?;
match crate::sema::plan_pure_extract(name, expression) {
Ok(plan) => Ok(json!({
"schema_version": 1,
"name": plan.name,
"params": plan.params,
"expression": plan.expression,
"heading": plan.heading,
"call": plan.call,
"effects": ["pure"],
"note": "预览补丁;写入请配合 artifact.patch / 人工审阅",
})),
Err(e) => Err(json!({"code": e.code, "message": e.message})),
}
}
// ---------- Executable-knowledge artifact protocol ----------
/// All artifact methods compile the same semantic project as the CLI. They
@@ -171,7 +197,187 @@ fn artifact_bind(params: &Value) -> Result<Value, Value> {
if expected.is_some() && expected != Some(artifact.hashes.artifact.0.as_str()) {
return Err(json!({"code":"artifact.digest_mismatch","message":"目标摘要已变化,拒绝绑定","expected":expected,"actual":artifact.hashes.artifact.0}));
}
Ok(json!({"schema_version":1,"handle":{"artifact_id":artifact.artifact_id.0,"digest":artifact.hashes.artifact.0,"project":compilation.semantics.root,"policy":params.get("policy").cloned().unwrap_or_else(||json!("pure")),"effects":artifact.effects.values()}}))
let policy = params
.get("policy")
.and_then(Value::as_str)
.unwrap_or("pure");
let effects = artifact.effects.values();
if policy == "pure"
&& effects.iter().any(|effect| effect != "pure")
{
return Err(json!({
"code": "artifact.effect_denied",
"message": "pure 策略下不能绑定含非纯/未知效应的制品",
"policy": policy,
"effects": effects,
}));
}
if policy == "business"
&& !matches!(
artifact.verification.evidence.as_str(),
"sourced" | "verified"
)
{
return Err(json!({
"code": "artifact.evidence_denied",
"message": "business 策略要求来源已关联;当前证据状态不足",
"policy": policy,
"evidence": artifact.verification.evidence,
}));
}
let symbol_id = artifact
.symbol_id
.as_ref()
.map(|id| id.as_str().to_string())
.unwrap_or_else(|| artifact.artifact_id.0.clone());
Ok(json!({"schema_version":1,"handle":{
"artifact_id": artifact.artifact_id.0,
"symbol_id": symbol_id,
"digest": artifact.hashes.artifact.0,
"project": compilation.semantics.root,
"policy": policy,
"effects": effects,
"evidence": artifact.verification.evidence,
"source": {"file": artifact.source.file, "line": artifact.source.line},
}}))
}
/// Digest-guarded local patch (S3/G09). `intent: wording` refuses signature/effect drift.
fn artifact_patch(params: &Value) -> Result<Value, Value> {
let compilation = semantic_project(params)?;
let query = params
.get("artifact_id")
.or_else(|| params.get("symbol_id"))
.and_then(Value::as_str)
.ok_or_else(|| err("mlsp.bad_request", "artifact.patch 需要 artifact_id 或 symbol_id"))?;
let candidates = artifact_query(&compilation.semantics, query);
if candidates.len() != 1 {
return Err(err(
if candidates.is_empty() {
"artifact.unresolved"
} else {
"artifact.ambiguous"
},
format!("无法唯一修补 `{query}`"),
));
}
let before = candidates[0];
let expected = params
.get("expected_digest")
.and_then(Value::as_str)
.ok_or_else(|| {
err(
"mlsp.bad_request",
"artifact.patch 需要 expected_digest(hashes.implementation)",
)
})?;
if expected != before.hashes.implementation.0 {
return Err(json!({
"code": "artifact.digest_mismatch",
"message": "源码实现摘要已变化,拒绝覆盖",
"expected": expected,
"actual": before.hashes.implementation.0,
}));
}
let path = compilation.semantics.root.join(&before.source.file);
let original = std::fs::read_to_string(&path)
.map_err(|e| err("artifact.load", format!("读源失败: {e}")))?;
let edits_v = params
.get("edits")
.and_then(Value::as_array)
.ok_or_else(|| err("mlsp.bad_request", "artifact.patch 需要 edits"))?;
let mut edits = Vec::new();
for e in edits_v {
let line = e
.get("line")
.and_then(Value::as_u64)
.ok_or_else(|| err("mlsp.bad_request", "edit.line 必填"))? as u32;
let kind = e.get("op").and_then(Value::as_str).unwrap_or("replace");
match kind {
"replace" => {
let text = e
.get("text")
.and_then(Value::as_str)
.ok_or_else(|| err("mlsp.bad_request", "replace 需要 text"))?
.to_string();
edits.push(crate::repair::Edit::Replace { line, text });
}
"delete" => edits.push(crate::repair::Edit::Delete { line }),
"insert_before" => {
let text = e
.get("text")
.and_then(Value::as_str)
.unwrap_or("")
.to_string();
edits.push(crate::repair::Edit::InsertBefore { line, text });
}
other => {
return Err(err(
"mlsp.bad_request",
format!("未知 edit.op `{other}`"),
))
}
}
}
let start = before.source.line;
let end = before.source.end_line.max(start);
let ranges = [(start, end.max(start + 40))];
let patched = crate::repair::apply_edits(&original, &ranges, &edits).map_err(|o| {
json!({
"code": "mlsp.repair_out_of_scope",
"message": "补丁超出制品源码范围",
"lines": o.lines,
"ranges": o.ranges,
})
})?;
std::fs::write(&path, &patched)
.map_err(|e| err("artifact.write", format!("写源失败: {e}")))?;
let after_comp = semantic_project(params)?;
let after_cands = artifact_query(&after_comp.semantics, query);
if after_cands.len() != 1 {
// roll back
let _ = std::fs::write(&path, &original);
return Err(err(
"artifact.patch_ambiguous",
"补丁后制品无法唯一解析;已回滚",
));
}
let after = after_cands[0];
let signature_changed = before.hashes.interface.0 != after.hashes.interface.0;
let effects_changed = before.effects.values() != after.effects.values();
let implementation_changed =
before.hashes.implementation.0 != after.hashes.implementation.0;
let intent = params.get("intent").and_then(Value::as_str).unwrap_or("edit");
if intent == "wording" && (signature_changed || effects_changed) {
let _ = std::fs::write(&path, &original);
return Err(json!({
"code": "artifact.wording_broke_contract",
"message": "intent=wording 但签名或效应已变;已回滚",
"signature_changed": signature_changed,
"effects_changed": effects_changed,
}));
}
Ok(json!({
"schema_version": 1,
"artifact_id": after.artifact_id.0,
"symbol_id": after.symbol_id.as_ref().map(|id| id.as_str()),
"applied": true,
"diff": {
"signature_changed": signature_changed,
"effects_changed": effects_changed,
"implementation_changed": implementation_changed,
"before": {
"interface": before.hashes.interface.0,
"implementation": before.hashes.implementation.0,
"effects": before.effects.values(),
},
"after": {
"interface": after.hashes.interface.0,
"implementation": after.hashes.implementation.0,
"effects": after.effects.values(),
},
},
}))
}
fn artifact_execute(params: &Value) -> Result<Value, Value> {
@@ -184,6 +390,21 @@ fn artifact_execute(params: &Value) -> Result<Value, Value> {
if candidates.len() != 1 { return Err(err("artifact.stale_handle", "制品不再可唯一解析;请重新 bind")); }
let artifact = candidates[0];
if artifact.hashes.artifact.0 != digest { return Err(json!({"code":"artifact.stale_handle","message":"源码或契约已改变;拒绝执行过期 handle","expected":digest,"actual":artifact.hashes.artifact.0})); }
if let Some(bound_symbol) = handle.get("symbol_id").and_then(Value::as_str) {
let current = artifact
.symbol_id
.as_ref()
.map(|id| id.as_str())
.unwrap_or(artifact.artifact_id.0.as_str());
if bound_symbol != current {
return Err(json!({
"code": "artifact.stale_handle",
"message": "handle 绑定的 SymbolId 与当前制品不一致",
"expected": bound_symbol,
"actual": current,
}));
}
}
if artifact.kind != "function" || artifact.callable.as_deref() == Some("instance_method") { return Err(err("artifact.not_executable", "只有非实例函数制品可由 artifact.execute 直接执行")); }
let allowed: Vec<&str> = params.get("allow_effects").and_then(Value::as_array).map(|items| items.iter().filter_map(Value::as_str).collect()).unwrap_or_default();
let denied: Vec<String> = artifact.effects.values().into_iter().filter(|effect| effect != "pure" && !allowed.contains(&effect.as_str())).collect();
@@ -197,10 +418,44 @@ fn artifact_execute(params: &Value) -> Result<Value, Value> {
let caps = crate::host::HostCaps { fs_write: allowed.contains(&"fs.write"), exec: allowed.iter().any(|e| matches!(*e, "process.exec" | "plugin.call" | "llm.call")), net: allowed.iter().any(|e| matches!(*e, "network.read" | "network.write" | "llm.call")), plugin: allowed.contains(&"plugin.call") };
let host = crate::host::HostContext::for_capture(Some(&path), caps);
let mut interpreter = crate::interp::Interpreter::with_capture(Some(&path), false).with_host(host);
let name = artifact.display_name.rsplit('.').next().unwrap_or(&artifact.display_name);
let value = interpreter.invoke_function(&module, name, &args).map_err(|e| diagnostic_err("artifact.execution_failed", &e))?;
// Bind by source line / declaration identity — never by bare display_name suffix (G07).
let fun = find_function_at_line(&module.functions, artifact.source.line).ok_or_else(|| {
err(
"artifact.unresolved",
format!(
"无法在 {}:{} 定位绑定函数 {}",
artifact.source.file, artifact.source.line, artifact.display_name
),
)
})?;
let value = interpreter
.invoke_bound_function(&module, fun, &args)
.map_err(|e| diagnostic_err("artifact.execution_failed", &e))?;
let stdout = std::mem::take(&mut interpreter.captured_stdout);
Ok(json!({"schema_version":1,"artifact_id":artifact.artifact_id.0,"digest":digest,"result":crate::value_as_json(&value).map_err(|e|err("artifact.serialization",e))?,"stdout":stdout,"effects":artifact.effects.values()}))
Ok(json!({
"schema_version": 1,
"artifact_id": artifact.artifact_id.0,
"symbol_id": artifact.symbol_id.as_ref().map(|id| id.as_str()),
"digest": digest,
"result": crate::value_as_json(&value).map_err(|e| err("artifact.serialization", e))?,
"stdout": stdout,
"effects": artifact.effects.values(),
}))
}
fn find_function_at_line<'a>(
functions: &'a [crate::ast::Function],
line: u32,
) -> Option<&'a crate::ast::Function> {
for fun in functions {
if fun.span.line == line {
return Some(fun);
}
if let Some(found) = find_function_at_line(&fun.children, line) {
return Some(found);
}
}
None
}
fn err(code: &str, message: impl Into<String>) -> Value {
@@ -658,9 +913,32 @@ mod tests {
let candidate = found["candidates"].as_array().unwrap().iter().find(|v| v["kind"] == "function").unwrap();
let id = candidate["artifact_id"].as_str().unwrap();
let bound = dispatch(&json!({"method":"artifact.bind","params":{"project":root,"artifact_id":id}})).unwrap();
let handle = bound["handle"].clone();
let handle = &bound["handle"];
assert!(handle.get("symbol_id").and_then(|v| v.as_str()).is_some());
assert!(handle.get("source").is_some());
let result = dispatch(&json!({"method":"artifact.execute","params":{"handle":handle,"inputs":{"x":4}}})).unwrap();
assert_eq!(result["result"], 5);
assert_eq!(result["symbol_id"], handle["symbol_id"]);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn artifact_bind_rejects_non_pure_under_pure_policy() {
let stamp = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos();
let root = std::env::temp_dir().join(format!("marqdo-mlsp-effect-{stamp}"));
fs::create_dir_all(&root).unwrap();
fs::write(
root.join("main.mq.md"),
"# main\n\n## save\n\n> fs.write_text path=t.txt text=x\n\n*1*\n",
)
.unwrap();
let found = dispatch(&json!({"method":"artifact.find","params":{"project":root,"query":"save"}})).unwrap();
let id = found["candidates"].as_array().unwrap().iter().find(|v| v["kind"] == "function").unwrap()["artifact_id"]
.as_str()
.unwrap();
let err = dispatch(&json!({"method":"artifact.bind","params":{"project":root,"artifact_id":id,"policy":"pure"}}))
.unwrap_err();
assert_eq!(err["code"], "artifact.effect_denied");
fs::remove_dir_all(root).unwrap();
}
+4 -1
View File
@@ -7,7 +7,10 @@ pub use expr::{
parse_call_after_gt, parse_call_arg_value, parse_expr, parse_expr_prefer_var,
parse_value_or_interp,
};
pub use prose::{scan_prose_line, ProseBit};
pub use prose::{
classify_narrative_target, scan_md_links_in_line, scan_narrative_links, scan_prose_line,
NarrativeLink, NarrativeLinkKind, ProseBit,
};
use anyhow::{bail, Result};
+186 -1
View File
@@ -2,8 +2,11 @@
//!
//! Soft Markdown emphasis that does not look like code/return is skipped (G2 —
//! [code-as-docs-gaps.md](../../../doc/design/code-as-docs-gaps.md)).
//!
//! Comment-line Markdown links `[label](target)` are NarrativeRef / navigation
//! sites (G03); they are never executed.
use crate::lex::{matching_bold_close_inline, matching_italic_close_inline};
use crate::lex::{matching_bold_close_inline, matching_italic_close_inline, LineKind};
pub use crate::lex::looks_like_bold_code;
@@ -22,6 +25,162 @@ pub enum ProseBit {
ItalicReturn { inner: String, at: usize },
}
/// Why a comment-line `[]()` is not an executable BoundCall (G03).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NarrativeLinkKind {
/// In-project symbol / binding / `#anchor` — inert explanation.
Narrate,
/// URL or file path — navigation only; never fetched by compile/run.
Navigation,
}
impl NarrativeLinkKind {
pub fn as_str(self) -> &'static str {
match self {
Self::Narrate => "narrate",
Self::Navigation => "navigation",
}
}
}
/// One Markdown link found on a comment (narrative) line.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NarrativeLink {
pub label: String,
pub target: String,
pub kind: NarrativeLinkKind,
/// 1-based source line.
pub line: u32,
pub at: usize,
}
/// Classify a link target without parsing it as an expression.
pub fn classify_narrative_target(target: &str) -> NarrativeLinkKind {
let t = target.trim();
if t.starts_with("http://")
|| t.starts_with("https://")
|| t.starts_with("mailto:")
|| t.starts_with("//")
{
return NarrativeLinkKind::Navigation;
}
if t.contains('/') || t.ends_with(".md") || t.ends_with(".mq.md") || t.ends_with(".html")
{
return NarrativeLinkKind::Navigation;
}
NarrativeLinkKind::Narrate
}
/// Scan whole-source comment lines for Markdown links; skip fences and code lines.
pub fn scan_narrative_links(source: &str) -> Vec<NarrativeLink> {
let classified = crate::lex::classify_source(source);
let mut out = Vec::new();
let mut in_fence = false;
for (i, cl) in classified.iter().enumerate() {
let line_no = (i + 1) as u32;
let trimmed = cl.text.trim();
if trimmed.starts_with("```") {
in_fence = !in_fence;
continue;
}
if in_fence {
continue;
}
if cl.kind != LineKind::Comment {
continue;
}
out.extend(scan_md_links_in_line(&cl.text, line_no));
}
out
}
/// Scan one line for `[label](target)`, skipping `` `inline` `` spans.
pub fn scan_md_links_in_line(line: &str, line_no: u32) -> Vec<NarrativeLink> {
let bytes = line.as_bytes();
let mut i = 0usize;
let mut out = Vec::new();
while i < bytes.len() {
if bytes[i] == b'`' {
if let Some(rel) = line[i + 1..].find('`') {
i = i + 1 + rel + 1;
continue;
}
i += 1;
continue;
}
if bytes[i] != b'[' {
i += 1;
continue;
}
let Some((label, target, next)) = parse_md_link(line, i) else {
i += 1;
continue;
};
let kind = classify_narrative_target(&target);
out.push(NarrativeLink {
label,
target,
kind,
line: line_no,
at: i,
});
i = next;
}
out
}
fn parse_md_link(line: &str, start: usize) -> Option<(String, String, usize)> {
if !line[start..].starts_with('[') {
return None;
}
let mut depth = 0i32;
let mut label_end = None;
for (rel, ch) in line[start..].char_indices() {
match ch {
'[' => depth += 1,
']' => {
depth -= 1;
if depth == 0 {
label_end = Some(start + rel);
break;
}
}
_ => {}
}
}
let label_end = label_end?;
let after = line.get(label_end + 1..)?;
if !after.starts_with('(') {
return None;
}
let mut depth = 0i32;
let mut target_end = None;
for (rel, ch) in after.char_indices() {
match ch {
'(' => depth += 1,
')' => {
depth -= 1;
if depth == 0 {
target_end = Some(rel);
break;
}
}
_ => {}
}
}
let target_end = target_end?;
let label = line[start + 1..label_end].to_string();
let target = after[1..target_end].trim().to_string();
if label.is_empty() || target.is_empty() {
return None;
}
// Executable occlusion payloads look like calls (`foo(…)` / `a.b(…)`); those
// live on Code lines already. If a comment link target is expression-shaped
// with `(`, still treat as narrate/navigation by target class — do not eval.
let next = label_end + 1 + target_end + 1;
Some((label, target, next))
}
/// Scan a narrative (or mixed) line for v0.3 inline bits, left to right.
pub fn scan_prose_line(line: &str) -> Vec<ProseBit> {
let bytes = line.as_bytes();
@@ -255,4 +414,30 @@ mod tests {
"glob-like ticks must not yield italic: {bits:?}"
);
}
#[test]
fn narrative_links_skip_fence_and_classify() {
let src = "---\nmarkup: occlusion\n---\n\n# main\n\n见[文档](https://example.com/a)与[总额](总额)。\n\n```\n[ignored](https://x.test)\n```\n\n行内跳过 `[not](x)` 标记。\n";
let links = scan_narrative_links(src);
assert!(
links.iter().any(|l| {
l.kind == NarrativeLinkKind::Navigation && l.target.contains("example.com")
}),
"{links:?}"
);
assert!(
links
.iter()
.any(|l| l.kind == NarrativeLinkKind::Narrate && l.target == "总额"),
"{links:?}"
);
assert!(
!links.iter().any(|l| l.target.contains("x.test")),
"fenced link must not become a step: {links:?}"
);
assert!(
!links.iter().any(|l| l.target == "x"),
"inline-code link must not become a step: {links:?}"
);
}
}
+52 -4
View File
@@ -81,7 +81,22 @@ const EXCLUDED_DIRS: &[&str] = &[
".agents",
];
/// Soft limits so discovery fails with a clear diagnosis instead of hanging (G12).
pub const MAX_SOURCE_DEPTH: u32 = 32;
pub const MAX_SOURCE_FILE_BYTES: u64 = 2 * 1024 * 1024;
pub const MAX_SOURCE_FILES: usize = 10_000;
fn collect_sources(root: &Path, dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
collect_sources_at(root, dir, out, 0)
}
fn collect_sources_at(root: &Path, dir: &Path, out: &mut Vec<PathBuf>, depth: u32) -> Result<()> {
if depth > MAX_SOURCE_DEPTH {
bail!(
"project.scan_depth_exceeded: directory depth > {MAX_SOURCE_DEPTH} under {}",
dir.display()
);
}
let mut entries: Vec<_> = fs::read_dir(dir)
.with_context(|| format!("read project directory {}", dir.display()))?
.collect::<std::result::Result<Vec<_>, _>>()?;
@@ -100,9 +115,9 @@ fn collect_sources(root: &Path, dir: &Path, out: &mut Vec<PathBuf>) -> Result<()
continue;
}
if canonical.is_dir() {
collect_sources(root, &canonical, out)?;
collect_sources_at(root, &canonical, out, depth + 1)?;
} else if is_mq_md(&canonical) {
out.push(canonical);
push_source(out, &canonical)?;
}
continue;
}
@@ -111,14 +126,33 @@ fn collect_sources(root: &Path, dir: &Path, out: &mut Vec<PathBuf>) -> Result<()
if EXCLUDED_DIRS.iter().any(|excluded| name == *excluded) {
continue;
}
collect_sources(root, &path, out)?;
collect_sources_at(root, &path, out, depth + 1)?;
} else if file_type.is_file() && is_mq_md(&path) {
out.push(path);
push_source(out, &path)?;
}
}
Ok(())
}
fn push_source(out: &mut Vec<PathBuf>, path: &Path) -> Result<()> {
if out.len() >= MAX_SOURCE_FILES {
bail!(
"project.scan_count_exceeded: more than {MAX_SOURCE_FILES} `.mq.md` sources"
);
}
let meta = fs::metadata(path)
.with_context(|| format!("stat {}", path.display()))?;
if meta.len() > MAX_SOURCE_FILE_BYTES {
bail!(
"project.scan_file_too_large: {} is {} bytes (max {MAX_SOURCE_FILE_BYTES})",
path.display(),
meta.len()
);
}
out.push(path.to_path_buf());
Ok(())
}
fn is_mq_md(path: &Path) -> bool {
path.file_name()
.and_then(|name| name.to_str())
@@ -173,6 +207,20 @@ mod tests {
fs::remove_dir_all(root).unwrap();
}
#[test]
fn oversized_source_is_diagnosed() {
let root = fixture_root("too-large");
let big = "x".repeat((MAX_SOURCE_FILE_BYTES as usize) + 8);
fs::write(root.join("big.mq.md"), format!("# main\n\n{big}\n")).unwrap();
let project = ProjectRoot::new(&root).unwrap();
let err = project.source_files().unwrap_err().to_string();
assert!(
err.contains("project.scan_file_too_large"),
"expected size diagnostic, got {err}"
);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn nearest_marker_wins() {
let root = fixture_root("discover");
+241
View File
@@ -0,0 +1,241 @@
//! Shared call binding for execution (G02 BoundCall).
//!
//! Tree and Bytecode must agree: explicit import paths and same-module bare
//! names bind; bare names never silently pick an imported symbol; true
//! dynamics are marked separately.
use crate::ast::{CallExpr, Function, Module};
use crate::diagnostics::Span;
use crate::host::HostFn;
/// Why a call site is not a static BoundCall.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DynamicReason {
MethodReceiver,
CallFn,
Plugin,
}
impl DynamicReason {
pub fn as_str(self) -> &'static str {
match self {
Self::MethodReceiver => "method_receiver",
Self::CallFn => "call_fn",
Self::Plugin => "plugin",
}
}
}
/// Runtime resolution shared by Tree (and mirrored by Bytecode rules).
#[derive(Debug)]
pub enum ExecTarget<'a> {
/// Function in the calling module (or nested children).
Local(&'a Function),
/// `bind.member…` through `module.import_modules`.
Import {
bind: String,
lib: &'a Module,
fun: &'a Function,
path: Vec<String>,
},
Builtin(&'static str),
Host(HostFn),
/// Plugin / method / call_fn — not a static BoundCall.
Dynamic {
reason: DynamicReason,
name: String,
},
Unresolved {
message: String,
#[allow(dead_code)]
span_hint: Option<Span>,
},
}
pub fn call_display(call: &CallExpr) -> String {
if let Some(path) = &call.path {
return path.join(".");
}
if let Some(recv) = &call.receiver {
return format!("{recv}.{}", call.callee);
}
call.callee.clone()
}
fn find_in_children<'a>(fun: &'a Function, name: &str) -> Option<&'a Function> {
for child in &fun.children {
if child.name == name {
return Some(child);
}
if let Some(f) = find_in_children(child, name) {
return Some(f);
}
}
None
}
/// Same-module bare-name lookup (never searches imports).
pub fn lookup_local<'a>(
module: &'a Module,
current: &'a Function,
name: &str,
) -> Option<&'a Function> {
if let Some(f) = find_in_children(current, name) {
return Some(f);
}
module.functions.iter().find(|f| f.name == name)
}
fn walk_path<'a>(lib: &'a Module, path: &[String]) -> Result<&'a Function, String> {
let display = path.join(".");
if path.is_empty() {
return Err("empty knowledge path".into());
}
let mut parent_is_object = false;
let mut node = lib
.functions
.iter()
.find(|f| f.name == path[0])
.ok_or_else(|| format!("unknown `{display}`"))?;
for seg in &path[1..] {
parent_is_object = node.is_object();
node = node
.children
.iter()
.find(|c| c.name == *seg)
.ok_or_else(|| format!("unknown `{display}`"))?;
}
if parent_is_object && node.level != 1 && crate::ast::function_uses_receiver(node) {
return Err(format!(
"`{display}` is an instance method; call it as `var`.{}",
node.name
));
}
Ok(node)
}
fn resolve_import_path<'a>(module: &'a Module, path: &[String]) -> ExecTarget<'a> {
let display = path.join(".");
if path.len() < 2 {
return ExecTarget::Unresolved {
message: format!("library path `{display}`: need at least `lib.member`"),
span_hint: None,
};
}
let bind = &path[0];
let Some(lib) = module.import_modules.get(bind) else {
return ExecTarget::Unresolved {
message: format!("unknown library `{bind}` (import it in frontmatter)"),
span_hint: None,
};
};
match walk_path(lib, &path[1..]) {
Ok(fun) => ExecTarget::Import {
bind: bind.clone(),
lib,
fun,
path: path.to_vec(),
},
Err(message) => ExecTarget::Unresolved {
message,
span_hint: None,
},
}
}
/// Resolve a call for execution. Import bare-name leakage is forbidden (G02).
pub fn resolve_for_exec<'a>(
module: &'a Module,
current: &'a Function,
call: &CallExpr,
) -> ExecTarget<'a> {
if call.receiver.is_some() {
return ExecTarget::Dynamic {
reason: DynamicReason::MethodReceiver,
name: call_display(call),
};
}
if let Some(path) = &call.path {
if module.import_modules.contains_key(&path[0]) {
return resolve_import_path(module, path);
}
// Same-module definition-tree path (`Type.member` / nested), BoundCall.
if path.len() >= 2 {
match walk_path(module, path) {
Ok(fun) => return ExecTarget::Local(fun),
Err(_) if path.len() == 2 => {
// Possible local-variable method; caller checks env.
return ExecTarget::Dynamic {
reason: DynamicReason::MethodReceiver,
name: call_display(call),
};
}
Err(message) => {
return ExecTarget::Unresolved {
message,
span_hint: None,
};
}
}
}
return ExecTarget::Unresolved {
message: format!(
"library path `{}`: need at least `lib.member`",
path.join(".")
),
span_hint: None,
};
}
if let Some(u) = module.uses.iter().find(|u| u.bind == call.callee) {
return resolve_import_path(module, &u.path);
}
match call.callee.as_str() {
"print" | "input" | "len" | "str" | "int" | "type" | "trim" | "split" | "join" | "at" => {
return ExecTarget::Builtin(match call.callee.as_str() {
"print" => "print",
"input" => "input",
"len" => "len",
"str" => "str",
"int" => "int",
"type" => "type",
"trim" => "trim",
"split" => "split",
"join" => "join",
"at" => "at",
_ => unreachable!(),
});
}
"call_fn" => {
return ExecTarget::Dynamic {
reason: DynamicReason::CallFn,
name: "call_fn".into(),
};
}
other if HostFn::from_name(other).is_some() => {
return ExecTarget::Host(HostFn::from_name(other).unwrap());
}
_ => {}
}
if let Some(fun) = lookup_local(module, current, &call.callee) {
return ExecTarget::Local(fun);
}
ExecTarget::Dynamic {
reason: DynamicReason::Plugin,
name: call.callee.clone(),
}
}
pub fn is_static_bound(target: &ExecTarget<'_>) -> bool {
matches!(
target,
ExecTarget::Local(_)
| ExecTarget::Import { .. }
| ExecTarget::Builtin(_)
| ExecTarget::Host(_)
)
}
+150
View File
@@ -0,0 +1,150 @@
//! Restricted pure-expression extract (S3).
//!
//! Only Literal / Var / Unary / Binary / List / Map / Index payloads may be
//! lifted. Calls, host, and plugins are refused so effect counts stay zero.
use std::collections::BTreeSet;
use crate::ast::Expr;
use crate::parse::expr::parse_expr_prefer_var;
#[derive(Debug, Clone)]
pub struct ExtractPlan {
pub name: String,
pub params: Vec<String>,
pub expression: String,
pub heading: String,
pub call: String,
}
#[derive(Debug, Clone)]
pub struct ExtractError {
pub code: &'static str,
pub message: String,
}
/// Build an extract plan from a pure expression string (no file I/O).
pub fn plan_pure_extract(name: &str, expression: &str) -> Result<ExtractPlan, ExtractError> {
let name = name.trim();
if name.is_empty()
|| name.contains(|c: char| c.is_whitespace() || c == '.' || c == '/')
{
return Err(ExtractError {
code: "extract.bad_name",
message: "提取目标名必须是单个标识符".into(),
});
}
let expr = parse_expr_prefer_var(expression).map_err(|e| ExtractError {
code: "extract.parse",
message: format!("无法解析表达式: {e}"),
})?;
if !is_pure_payload(&expr) {
return Err(ExtractError {
code: "extract.not_pure",
message: "仅允许字面量/变量/算术/列表等纯载荷;拒绝调用与宿主效应".into(),
});
}
let params: Vec<String> = free_vars(&expr).into_iter().collect();
let call = if params.is_empty() {
format!("{name}()")
} else {
let args = params
.iter()
.map(|p| format!("{p}=`{p}`"))
.collect::<Vec<_>>()
.join(", ");
format!("{name}({args})")
};
let heading = if params.is_empty() {
format!("## {name}\n\n*{expression}*\n")
} else {
let decls = params
.iter()
.map(|p| format!("`{p}`"))
.collect::<Vec<_>>()
.join("、");
format!("## {name}\n\n参数:{decls}\n\n*{expression}*\n")
};
Ok(ExtractPlan {
name: name.into(),
params,
expression: expression.trim().into(),
heading,
call,
})
}
fn is_pure_payload(expr: &Expr) -> bool {
match expr {
Expr::Literal(_) | Expr::Var(_) => true,
Expr::Unary { expr, .. } => is_pure_payload(expr),
Expr::Binary { left, right, .. } => is_pure_payload(left) && is_pure_payload(right),
Expr::List(items) => items.iter().all(is_pure_payload),
Expr::Map(items) => items.iter().all(|(_, v)| is_pure_payload(v)),
Expr::Index { base, .. } => is_pure_payload(base),
Expr::Occluded { payload, .. } => payload
.as_ref()
.map(|p| is_pure_payload(p))
.unwrap_or(true),
Expr::Call(_) | Expr::Interp(_) | Expr::Formula(_) | Expr::Code(_) => false,
}
}
fn free_vars(expr: &Expr) -> BTreeSet<String> {
let mut out = BTreeSet::new();
walk(expr, &mut out);
out
}
fn walk(expr: &Expr, out: &mut BTreeSet<String>) {
match expr {
Expr::Var(name) => {
out.insert(name.clone());
}
Expr::Unary { expr, .. } => walk(expr, out),
Expr::Binary { left, right, .. } => {
walk(left, out);
walk(right, out);
}
Expr::List(items) => {
for item in items {
walk(item, out);
}
}
Expr::Map(items) => {
for (_, item) in items {
walk(item, out);
}
}
Expr::Index { base, .. } => walk(base, out),
Expr::Occluded { payload, .. } => {
if let Some(p) = payload {
walk(p, out);
}
}
Expr::Literal(_)
| Expr::Call(_)
| Expr::Interp(_)
| Expr::Formula(_)
| Expr::Code(_) => {}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn extracts_product() {
let plan = plan_pure_extract("商品小计", "数量 * 单价").unwrap();
assert_eq!(plan.params, vec!["单价".to_string(), "数量".to_string()]);
assert!(plan.heading.contains("## 商品小计"));
assert!(plan.call.contains("商品小计("));
}
#[test]
fn rejects_call() {
let err = plan_pure_extract("x", "save()").unwrap_err();
assert_eq!(err.code, "extract.not_pure");
}
}
+955 -53
View File
File diff suppressed because it is too large. Load diff
+82 -10
View File
@@ -15,6 +15,8 @@ pub struct LockReport {
pub missing: Vec<String>,
pub changed: Vec<String>,
pub removed: Vec<String>,
/// Per-artifact which digest class drifted (G08).
pub classes: Vec<Value>,
}
impl LockReport {
@@ -29,6 +31,7 @@ impl LockReport {
"missing": self.missing,
"changed": self.changed,
"removed": self.removed,
"classes": self.classes,
})
}
}
@@ -63,21 +66,47 @@ pub fn check_links_lock(out_dir: &Path, project: &SemanticProject) -> Result<Loc
..LockReport::default()
});
}
let expected = artifact_lock_map(project);
let expected = artifact_lock_entries(project);
let actual = raw.get("artifacts").and_then(Value::as_object).cloned().unwrap_or_default();
let mut report = LockReport::default();
for (id, digest) in &expected {
for (id, entry) in &expected {
match actual.get(id).and_then(Value::as_object) {
None => report.missing.push(id.clone()),
Some(found) if found.get("artifact").and_then(Value::as_str) != Some(digest.as_str()) => report.changed.push(id.clone()),
_ => {}
Some(found) => {
let mut drifted = Vec::new();
for key in ["interface", "implementation", "evidence", "artifact", "closure"] {
let want = entry.get(key).and_then(Value::as_str);
let got = found.get(key).and_then(Value::as_str);
if want != got {
drifted.push(key.to_string());
}
}
if !drifted.is_empty() {
report.changed.push(id.clone());
report.classes.push(json!({
"artifact_id": id,
"changed": drifted,
}));
}
}
}
}
for id in actual.keys() {
if !expected.contains_key(id) { report.removed.push(id.clone()); }
if !expected.contains_key(id) {
report.removed.push(id.clone());
}
}
report.missing.sort(); report.changed.sort(); report.removed.sort();
report.status = if report.missing.is_empty() && report.changed.is_empty() && report.removed.is_empty() { "clean".into() } else { "outdated".into() };
report.missing.sort();
report.changed.sort();
report.removed.sort();
report.status = if report.missing.is_empty()
&& report.changed.is_empty()
&& report.removed.is_empty()
{
"clean".into()
} else {
"outdated".into()
};
Ok(report)
}
@@ -90,6 +119,11 @@ pub fn impact(project: &SemanticProject, query: &str) -> Value {
|| artifact.symbol_id.as_ref().is_some_and(|id| id.as_str() == query)
|| artifact.display_name == query
|| artifact.source.file == query
|| artifact.source.file.ends_with(query)
|| std::path::Path::new(&artifact.source.file)
.file_stem()
.and_then(|s| s.to_str())
.is_some_and(|stem| stem == query || query.ends_with(stem))
|| artifact.artifact_id.0.ends_with(query)
{
seeds.insert(artifact.artifact_id.0.clone());
@@ -98,7 +132,29 @@ pub fn impact(project: &SemanticProject, query: &str) -> Value {
let mut reverse: BTreeMap<String, Vec<String>> = BTreeMap::new();
for artifact in &project.artifacts {
for dependency in &artifact.dependencies {
reverse.entry(dependency.0.clone()).or_default().push(artifact.artifact_id.0.clone());
reverse
.entry(dependency.0.clone())
.or_default()
.push(artifact.artifact_id.0.clone());
}
}
// NarrativeRef edges: step → symbol; impact includes the step's owning artifact.
for step in &project.steps {
if step.kind != "narrate" {
continue;
}
let owner = step
.id
.0
.split("#step-")
.next()
.unwrap_or(step.id.0.as_str())
.to_string();
for target in &step.calls {
reverse
.entry(target.as_str().to_string())
.or_default()
.push(owner.clone());
}
}
let mut queue: VecDeque<String> = seeds.iter().cloned().collect();
@@ -119,8 +175,23 @@ pub fn impact(project: &SemanticProject, query: &str) -> Value {
json!({"schema_version":SCHEMA_VERSION,"query":query,"resolved":!seeds.is_empty(),"seeds":seeds,"affected":entries})
}
fn artifact_lock_map(project: &SemanticProject) -> BTreeMap<String, String> {
project.artifacts.iter().map(|artifact| (artifact.artifact_id.0.clone(), artifact.hashes.artifact.0.clone())).collect()
fn artifact_lock_entries(project: &SemanticProject) -> BTreeMap<String, Value> {
project
.artifacts
.iter()
.map(|artifact| {
(
artifact.artifact_id.0.clone(),
json!({
"interface": artifact.hashes.interface.0,
"implementation": artifact.hashes.implementation.0,
"evidence": artifact.hashes.evidence.0,
"artifact": artifact.hashes.artifact.0,
"closure": artifact.hashes.closure.0,
}),
)
})
.collect()
}
fn lock_json(project: &SemanticProject) -> Value {
@@ -131,6 +202,7 @@ fn lock_json(project: &SemanticProject) -> Value {
"implementation": artifact.hashes.implementation.0,
"evidence": artifact.hashes.evidence.0,
"artifact": artifact.hashes.artifact.0,
"closure": artifact.hashes.closure.0,
"dependencies": artifact.dependencies.iter().map(|item| &item.0).collect::<Vec<_>>(),
}));
}
+10 -2
View File
@@ -4,13 +4,21 @@
//! binding facts so runtime, EKC, view, and agents do not independently infer
//! the meaning of the same source text.
pub mod bind;
pub mod extract;
pub mod ir;
pub mod lock;
pub mod provenance;
pub mod symbols;
pub use bind::{
call_display, is_static_bound, lookup_local, resolve_for_exec, DynamicReason, ExecTarget,
};
pub use extract::{plan_pure_extract, ExtractError, ExtractPlan};
pub use ir::{
artifact_json, compile_project, write_semantic_projections, ArtifactId, CompileOptions, Compilation,
Digest, EffectSet, LockMode, SemanticArtifact, SemanticProject,
artifact_json, compile_project, semantic_generation_dir, write_semantic_projections, ArtifactId,
BoundCall, CompileOptions, Compilation, Digest, DynamicCall, EffectSet, LockMode,
SemanticArtifact, SemanticProject,
};
pub use lock::{check_links_lock, impact as semantic_impact, update_links_lock, LockReport};
pub use symbols::{CallableKind, ModuleId, ProjectIndex, SymbolDecl, SymbolId, SymbolKind};
+251
View File
@@ -0,0 +1,251 @@
//! Optional source / applicability facts from module frontmatter (G05).
//!
//! Authors declare `sources:` and optional `applicability:` / `valid_until` in
//! frontmatter. Absence means a pure tool may still run but must stay
//! `evidence=unverified` — never invent a business SourceRef.
use std::fs;
use std::path::{Path, PathBuf};
use sha2::{Digest as _, Sha256};
use super::ir::{Digest, SourceRef};
#[derive(Debug, Clone, Default)]
pub struct ModuleProvenance {
/// Relative corpus paths, optional `#anchor`.
pub sources: Vec<String>,
pub valid_until: Option<String>,
pub region: Option<String>,
}
/// Scan YAML-ish frontmatter for sources / applicability (no full YAML parser).
pub fn parse_module_provenance(source: &str) -> ModuleProvenance {
let mut lines = source.lines();
if lines.next().map(|l| l.trim_end()) != Some("---") {
return ModuleProvenance::default();
}
let mut out = ModuleProvenance::default();
let mut in_sources = false;
let mut in_applicability = false;
for line in lines {
let t = line.trim_end();
if t.trim() == "---" {
break;
}
let trimmed = t.trim();
if trimmed.is_empty() {
continue;
}
if !line.starts_with(' ') && !line.starts_with('\t') {
in_sources = false;
in_applicability = false;
}
if trimmed == "sources:" || trimmed.starts_with("sources:") {
in_sources = true;
in_applicability = false;
if let Some(rest) = trimmed.strip_prefix("sources:") {
let rest = rest.trim();
if !rest.is_empty() && rest != "|" {
// inline list not used; ignore
}
}
continue;
}
if trimmed == "applicability:" || trimmed.starts_with("applicability:") {
in_applicability = true;
in_sources = false;
continue;
}
if in_sources {
if let Some(item) = trimmed.strip_prefix("- ") {
let path = item.trim().trim_matches('"').to_string();
if !path.is_empty() {
out.sources.push(path);
}
}
continue;
}
if in_applicability {
if let Some(rest) = trimmed.strip_prefix("valid_until:") {
out.valid_until = Some(rest.trim().trim_matches('"').to_string());
} else if let Some(rest) = trimmed.strip_prefix("region:") {
out.region = Some(rest.trim().trim_matches('"').to_string());
}
}
}
out
}
#[derive(Debug, Clone)]
pub enum ProvenanceDiag {
Missing { path: String },
Expired { valid_until: String },
}
impl ProvenanceDiag {
pub fn code(&self) -> &'static str {
match self {
Self::Missing { .. } => "source.missing",
Self::Expired { .. } => "source.expired",
}
}
pub fn message(&self) -> String {
match self {
Self::Missing { path } => format!("来源文件缺失:`{path}`"),
Self::Expired { valid_until } => {
format!("来源适用期已过(valid_until={valid_until})")
}
}
}
}
pub struct ProvenanceResolution {
pub refs: Vec<SourceRef>,
pub applicability: String,
pub evidence_status: String,
pub diagnostics: Vec<ProvenanceDiag>,
}
/// Resolve corpus paths relative to the module file; never mark verified here.
pub fn resolve_provenance(
module_path: &Path,
prov: &ModuleProvenance,
) -> ProvenanceResolution {
let mut refs = Vec::new();
let mut diagnostics = Vec::new();
let base = module_path
.parent()
.map(|p| p.to_path_buf())
.unwrap_or_else(|| PathBuf::from("."));
for raw in &prov.sources {
let (path_part, locator) = match raw.split_once('#') {
Some((p, a)) => (p.trim(), Some(a.trim().to_string())),
None => (raw.as_str(), None),
};
let resolved = base.join(path_part);
if !resolved.is_file() {
diagnostics.push(ProvenanceDiag::Missing {
path: raw.clone(),
});
refs.push(SourceRef {
uri: path_part.to_string(),
locator,
content_digest: None,
relation: "supports".into(),
});
continue;
}
let content = fs::read(&resolved).unwrap_or_default();
let mut hash = Sha256::new();
hash.update(&content);
refs.push(SourceRef {
uri: path_part.to_string(),
locator,
content_digest: Some(Digest(format!("sha256:{:x}", hash.finalize()))),
relation: "supports".into(),
});
}
if let Some(until) = &prov.valid_until {
if is_expired(until) {
diagnostics.push(ProvenanceDiag::Expired {
valid_until: until.clone(),
});
}
}
let applicability = match (&prov.region, &prov.valid_until) {
(None, None) if prov.sources.is_empty() => {
"no explicit applicability constraints".into()
}
(region, until) => {
let mut parts = Vec::new();
if let Some(r) = region {
parts.push(format!("region={r}"));
}
if let Some(u) = until {
parts.push(format!("valid_until={u}"));
}
if parts.is_empty() {
"sources declared".into()
} else {
parts.join("; ")
}
}
};
let evidence_status = if diagnostics.iter().any(|d| matches!(d, ProvenanceDiag::Missing { .. }))
{
"missing_source".into()
} else if diagnostics
.iter()
.any(|d| matches!(d, ProvenanceDiag::Expired { .. }))
{
"expired".into()
} else if prov.sources.is_empty() {
"unverified".into()
} else {
// Corpus present and in date — still not domain-verified by compile alone.
"sourced".into()
};
ProvenanceResolution {
refs,
applicability,
evidence_status,
diagnostics,
}
}
fn is_expired(valid_until: &str) -> bool {
// Expect YYYY-MM-DD; compare lexicographically to today's UTC date.
let today = chrono_today();
!valid_until.is_empty() && valid_until < today.as_str()
}
fn chrono_today() -> String {
// Avoid new dependency: use system local date via `date` is bad; use
// SystemTime → rough days since epoch is fragile. Prefer `time` crate if
// present, else format via `js_sys` — check Cargo.toml.
use std::time::{SystemTime, UNIX_EPOCH};
let secs = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap_or_default()
.as_secs() as i64;
// UTC civil date from days since epoch (proleptic Gregorian).
let days = secs.div_euclid(86_400);
let (y, m, d) = civil_from_days(days);
format!("{y:04}-{m:02}-{d:02}")
}
/// Algorithm from Howard Hinnant (public domain).
fn civil_from_days(z: i64) -> (i32, u32, u32) {
let z = z + 719_468;
let era = if z >= 0 { z } else { z - 146_096 }.div_euclid(146_097);
let doe = (z - era * 146_097) as u64;
let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146_096) / 365;
let y = (yoe as i64 + era * 400) as i32;
let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
let mp = (5 * doy + 2) / 153;
let d = doy - (153 * mp + 2) / 5 + 1;
let m = if mp < 10 { mp + 3 } else { mp - 9 };
let y = if m <= 2 { y + 1 } else { y };
(y, m as u32, d as u32)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parse_sources_and_valid_until() {
let src = "---\nsources:\n - ../corpus/tax.md#rate\napplicability:\n region: CN\n valid_until: 2099-12-31\n---\n\n# main\n";
let p = parse_module_provenance(src);
assert_eq!(p.sources, vec!["../corpus/tax.md#rate"]);
assert_eq!(p.region.as_deref(), Some("CN"));
assert_eq!(p.valid_until.as_deref(), Some("2099-12-31"));
}
}
+31 -1
View File
@@ -56,8 +56,38 @@ pub struct FileViewModel {
/// can show binding/effect/verification facts even in `--no-exec` exports.
pub fn render_knowledge_html(project: &crate::sema::SemanticProject, rel: &str) -> String {
let artifacts: Vec<_> = project.artifacts.iter().filter(|artifact| artifact.source.file == rel).collect();
if artifacts.is_empty() { return String::new(); }
let steps: Vec<_> = project.steps.iter().filter(|step| step.source.file == rel).collect();
if artifacts.is_empty() && steps.is_empty() { return String::new(); }
let mut out = String::from(r#"<div class="knowledge-panel" aria-label="Executable knowledge">"#);
if !steps.is_empty() {
out.push_str(r#"<article class="knowledge-card knowledge-steps"><h3>Steps</h3><ol class="knowledge-step-list">"#);
for step in &steps {
let label = project
.refs
.iter()
.find(|r| r.id == step.reference)
.map(|r| r.label.as_str())
.unwrap_or(step.reference.as_str());
let line = step.source.line;
let target_ids = if step.calls.is_empty() {
String::new()
} else {
format!(
r#" <span class="knowledge-step-targets">→ {}</span>"#,
escape(&step.calls.iter().map(|id| id.as_str()).collect::<Vec<_>>().join(", "))
)
};
// Structure pane uses #stmt-{line}; jump there for source navigation.
out.push_str(&format!(
"<li class=\"knowledge-step\" data-step-kind=\"{0}\" data-line=\"{1}\"><a href=\"#stmt-{1}\"><code class=\"ks-kind\">{0}</code> {2}</a>{3}</li>",
escape(&step.kind),
line,
escape(label),
target_ids,
));
}
out.push_str("</ol></article>");
}
for artifact in artifacts {
let target = artifact.symbol_id.as_ref().map(|id| id.as_str()).unwrap_or(artifact.artifact_id.0.as_str());
let signature = artifact.signature.as_ref().map(|sig| {
File diff suppressed because it is too large. Load diff
+58
View File
@@ -0,0 +1,58 @@
# 可执行知识 — S0 作者基线
| | |
|---|---|
| 状态 | **S0 基线语料与无网络门禁**;不是 S1+ 能力声明 |
| 规范 | [文档原生指导](../../doc/design/document-native-development-guide.md) §3 / §7 S0 · [缺口路线](../../doc/roadmap/executable-knowledge-gaps-2026-10-23.md) |
| 门禁 | `cargo test --test executable_knowledge --locked`(无网络) |
## 六类任务
| ID | 目录 | 状态 | 期望 | 作者手工维护项(基线计数) |
|---|---|---|---|---|
| 01 | `baseline/01-inline/` | implemented | Tree/Bytecode → `60` | 0(无注册/无锁/无知识 ID) |
| 02 | `baseline/02-extract/` | implemented | → `60` | 标题名 + 叙述形参 `` `数量` `` `` `单价` ``(2) |
| 03 | `baseline/03-import/` | implemented | → `60` | frontmatter `import` 一行(1) |
| 04 | `baseline/04-access-loop/` | implemented | 取元+遍历输出 | `import json` + `access`/`遍历` 写法(与现网一致) |
| 05 | `baseline/05-policy-draft/` | **design** | 可试跑 → `113`;**不**宣称税率事实已证实 | 叙述中的来源意图(尚未有强制 schema) |
| 06a | `baseline/06-reject/missing-import.mq.md` | expected_failure | 双后端均非 0 | 0(正确拒绝) |
| 06b | `baseline/06-reject/ambiguous.mq.md` | expected_failure | **双后端均拒绝**裸名同名(G02) | — |
| 10 | `baseline/10-boundcall/` | implemented | BoundCall 路径 SymbolId + DynamicCall(`call_fn`);双后端 `hi`/`60` | import 一行 |
| 11 | `baseline/11-narrative-ref/` | implemented | `narrate`/`navigation` 步骤;围栏不计;run 不拉 URL | 0 |
| 12 | `baseline/12-tax-source/` | implemented | `sources:` → evidence=sourced;过期 → expired;可试跑 `113` | sources + valid_until |
| 13 | `baseline/13-bookstore/` | implemented | 书店含税可运行子集 + narrate;输出 `113` | import + sources |
### 同名裸调用(G02)
`06-reject/ambiguous.mq.md` 同时 `import` 了 `a` 与 `b`(同名 `商品小计`),正文用**裸名**调用。双后端均须拒绝;正确写法是 `a.商品小计` / `b.商品小计` 等显式路径。
`10-boundcall`:显式 `pricing.商品小计` 写入 `bound_calls.json`(`binding: BoundCall` + SymbolId);`call_fn` 写入 `dynamic_calls.json`(不得假装已绑定)。
## 不计为成功的项
- `status: design` 样例通过运行 ≠ 来源/适用性/ready 已实现(G05/G07)
- 任何 `#[ignore]` / skip **不得**充当核心能力证据
- 目标示例 [`examples/executable-knowledge/`](../../examples/executable-knowledge/) 仍为设计态,不在本门禁
## 切片进度(本目录门禁)
| 切片 | 状态 | 证据 |
|---|---|---|
| S0 | **done** | `s0_*` 基线正负例 |
| S1/G01 | **done** | `graph/` 权威 + `ekc/graph/` 检索分离 |
| S1/G03 | **done** | 步骤 kind ≠ 全 call;`steps.json`;view `#stmt-` 导航 |
| S1 同名 | **done** | `08-same-name` resolve→A + 运行 `60` |
| S2/G06 | **done** | 包装继承 `fs.write`;未知不标 pure |
| S2/G07 子集 | **done** | MLSP bind 含 `symbol_id`;execute 按源行绑定;pure 拒非纯 |
| S2/G02 BoundCall | **done** | 共享 `resolve_for_exec`;Tree/Bytecode 静态路径绑定;`bound_calls.json` / `dynamic_calls.json`;`10-boundcall` + `06b` |
| S2/G07 eng_reuse | **done(子集)** | `reuse_json` / `agent_eng_reuse`:`discovery_only` + `bind_required` + `bind_targets`;执行仍须 MLSP bind |
| S1/G03 NarrativeRef | **done(子集)** | 注释行 `[]()` → narrate/navigation;`11-narrative-ref` |
| S4/G05 来源 | **done(子集)** | frontmatter `sources`/`valid_until`;`12-tax-source`;business bind |
| S3 patch / extract | **done** | `artifact.patch`;`artifact.extract_pure` |
| S4 书店 | **done** | `13-bookstore` + `examples/executable-knowledge` 发票链 |
| S5/G04·G08 | **done** | 整代 `CURRENT`;锁 classes+closure;impact |
| S6 CI / 语料 / 冒烟 | **done** | CI;100 单元;CLI smoke;扫描上限 |
## 与后续切片的关系
- 远程凭据/多租户授权、平台打包产物冒烟、作者/AI 对照实验指标 — 按发布声明另验;不得用本地门禁覆盖为「已安全支持远程」
@@ -0,0 +1,12 @@
---
markup: occlusion
title: S0 单文件内联计算
status: implemented
---
# main
这是演示订单,单价与数量直接写在计算处。
**小计 = [两件商品的小计](2 * 30)**
> print text=`小计`
@@ -0,0 +1,18 @@
---
markup: occlusion
title: S0 提取命名函数
status: implemented
---
## 商品小计
根据购买数量`数量`和商品单价`单价`计算小计。
*[按数量与单价计算](数量 * 单价)*
# main
计算同一笔演示订单。
**小计 = [两件商品的小计](商品小计(数量=2, 单价=30))**
> print text=`小计`
@@ -0,0 +1,14 @@
---
markup: occlusion
title: S0 两文档显式 import
status: implemented
import:
pricing: pricing.mq.md
---
# main
跨文档复用已提取的定价能力。
**小计 = [两件商品的小计](pricing.商品小计(数量=2, 单价=30))**
> print text=`小计`
@@ -0,0 +1,11 @@
---
markup: occlusion
title: S0 定价能力(被引用模块)
status: implemented
---
## 商品小计
根据购买数量`数量`和商品单价`单价`计算小计。
*[按数量与单价计算](数量 * 单价)*
@@ -0,0 +1,19 @@
---
markup: occlusion
title: S0 表格取元与遍历
status: implemented
import:
json: lib/json.mq.md
---
# main
`表` = > json.parse text={"键":"值"}
`列` = > json.parse text=["一","二"]
**a = [取表项](access(`表`, "键"))**
**b = [取列表第二项](access(`列`, 2))**
> print text="a=" + `a`
> print text="b=" + `b`
- [篮子里的每个果子](遍历 `列` 为 `果`)
> print text="果子=" + `果`
@@ -0,0 +1,21 @@
---
markup: occlusion
title: S0 业务政策草稿(设计态)
status: design
description: >
展示作者将来如何就地写来源与适用条件。当前运行时尚未强制 SourceRef /
适用性校验(见缺口 G05)。本文件可本地试跑纯计算,但不计入「业务事实已证实」。
---
# main
某地区标准增值税率为 13%。若要成为可复用业务事实,还需要原始资料、有效期、
适用范围与验证事件——这些**尚未由编译器强制**,故本样例标为 design。
## 标准税率
*[当前标准税率](0.13)*
**税率 = [读取标准税率](标准税率())**
**含税 = [演示含税价](100 * (1 + 税率))**
> print text=`含税`
@@ -0,0 +1,11 @@
---
markup: occlusion
title: S0 同名模块 A
status: expected_failure
---
## 商品小计
根据购买数量`数量`和商品单价`单价`计算小计(A 侧)。
*[A 侧实现](数量 * 单价)*
@@ -0,0 +1,17 @@
---
markup: occlusion
title: S0 拒绝复用:裸名无法消歧(现状基线)
status: expected_failure
description: >
两模块均定义「商品小计」。当前默认语法要求显式路径调用;
裸名调用不导入任何一方时,应失败而非猜一个目标。
(同名已 import 仍误连是 S1 验收项,不在本负例。)
import:
a: a.mq.md
b: b.mq.md
---
# main
**小计 = [未消歧的同名调用](商品小计(数量=2, 单价=30))**
> print text=`小计`
@@ -0,0 +1,11 @@
---
markup: occlusion
title: S0 同名模块 B
status: expected_failure
---
## 商品小计
根据购买数量`数量`和商品单价`单价`计算小计(B 侧加倍)。
*[B 侧实现](数量 * 单价 * 2)*
@@ -0,0 +1,12 @@
---
markup: occlusion
title: S0 拒绝复用:缺 import
status: expected_failure
---
# main
未 import 时不得静默解析外部模块。
**小计 = [误用外部定价](pricing.商品小计(数量=2, 单价=30))**
> print text=`小计`
@@ -0,0 +1,18 @@
---
markup: occlusion
title: S1 步骤 kind 分类样例
status: implemented
import:
json: lib/json.mq.md
---
# main
`列` = > json.parse text=["一","二"]
**a = [取列表首项](access(`列`, 1))**
**b = [两件商品的小计](2 * 30)**
- [篮子里的每个果子](遍历 `列` 为 `果`)
> print text=`果`
> print text=`a`
> print text=`b`
@@ -0,0 +1,11 @@
---
markup: occlusion
title: S1 同名模块 A(应被选中)
status: implemented
---
## 商品小计
根据购买数量`数量`和商品单价`单价`计算(A)。
*[A 侧](数量 * 单价)*
@@ -0,0 +1,11 @@
---
markup: occlusion
title: S1 同名模块 B(不应被选中)
status: implemented
---
## 商品小计
根据购买数量`数量`和商品单价`单价`计算(B 加倍)。
*[B 侧](数量 * 单价 * 2)*
@@ -0,0 +1,14 @@
---
markup: occlusion
title: S1 同名仅 import A
status: implemented
import:
pricing: a.mq.md
---
# main
只 import A;不得落到 B。
**小计 = [两件商品的小计](pricing.商品小计(数量=2, 单价=30))**
> print text=`小计`
@@ -0,0 +1,24 @@
---
markup: occlusion
title: S2 G06 效应传递与未知不纯
status: implemented
---
## save
写入演示文件。
> fs.write_text path=out.txt text=ok
*1*
## wrap
无危险词包装,内部调用 save。
> save
*None*
# main
> wrap
> print text=ok
@@ -0,0 +1,21 @@
---
markup: occlusion
title: S2 G02 BoundCall 路径绑定与动态标记
status: implemented
import:
pricing: pricing.mq.md
---
## helper
动态目标演示用无参函数。
> print text=hi
# main
显式 import 路径必须进 BoundCall;`call_fn` 必须进 DynamicCall。
**小计 = [两件](pricing.商品小计(数量=2, 单价=30))**
> call_fn name=helper
> print text=`小计`
@@ -0,0 +1,11 @@
---
markup: occlusion
title: BoundCall 目标定价
status: implemented
---
## 商品小计
根据购买数量`数量`和商品单价`单价`计算小计。
*[按数量与单价计算](数量 * 单价)*
@@ -0,0 +1,25 @@
---
markup: occlusion
title: S1 G03 正文 NarrativeRef
status: implemented
---
## 总额
订单含税合计。
*100*
# main
正文引用同一目标;URL 只作导航,围栏内链接不计步骤。
这张订单的含税总额是[含税总价](总额)。详见[政策原文](https://example.com/tax-policy)。
```
[围栏内](https://example.com/ignored)
```
行内代码 `[skip](总额)` 不计。
> print text=ok
@@ -0,0 +1,3 @@
# 2026 年标准增值税率
演示用政策原文。标准税率为 13%。
@@ -0,0 +1,20 @@
---
markup: occlusion
title: S4 G05 来源与适用期
status: implemented
sources:
- corpus.md#标准税率
applicability:
region: CN
valid_until: 2099-12-31
---
## 标准税率
*[当前标准税率](0.13)*
# main
**税率 = [读取标准税率](标准税率())**
**含税 = [演示含税价](100 * (1 + 税率))**
> print text=`含税`
@@ -0,0 +1,3 @@
# 2026 年标准增值税率
演示用政策原文。标准税率为 13%。
@@ -0,0 +1,18 @@
---
markup: occlusion
title: S4 G05 过期来源
status: implemented
sources:
- corpus.md#标准税率
applicability:
region: CN
valid_until: 2020-01-01
---
## 标准税率
*[过期政策下的税率演示](0.13)*
# main
> print text=ok
@@ -0,0 +1,3 @@
# 标准税率
书店演示政策原文:增值税标准税率 13%。
@@ -0,0 +1,16 @@
---
markup: occlusion
title: S4 书店订单含税(可运行子集)
status: implemented
import:
tax: tax.mq.md
---
# main
一行订单:金额 100,按标准税率含税。
**税率 = [适用税率](tax.标准税率())**
**含税 = [本行含税价](100 * (1 + 税率))**
这是[含税总价](含税)的可读结论。
> print text=`含税`
@@ -0,0 +1,14 @@
---
markup: occlusion
title: 书店税率(可运行子集)
status: implemented
sources:
- corpus.md#标准税率
applicability:
region: CN
valid_until: 2099-12-31
---
## 标准税率
*[当前标准税率](0.13)*
+15 -3
View File
@@ -1286,8 +1286,19 @@ fn knowledge_compile_engineering_fixture() {
]);
assert_eq!(code, 0, "{stderr}");
assert!(dir.join("catalog/repository.mq.md").exists());
assert!(dir.join("graph/graph.json").exists());
assert!(dir.join("graph/edges.json").exists());
// G01: SemanticProject owns graph/; EKC retrieval lives under ekc/.
assert!(dir.join("graph/edges.json").exists(), "semantic edges");
assert!(dir.join("ekc/graph/graph.json").exists(), "EKC retrieval graph");
assert!(dir.join("ekc/graph/edges.json").exists(), "EKC retrieval edges");
assert!(
!dir.join("graph/graph.json").exists(),
"EKC graph.json must not overwrite semantic graph/"
);
let edges: serde_json::Value =
serde_json::from_str(&std::fs::read_to_string(dir.join("graph/edges.json")).unwrap())
.unwrap();
assert_eq!(edges["authority"], "SemanticProject", "{edges}");
assert!(dir.join("steps.json").exists(), "semantic steps projection");
assert!(dir.join("engineering.yaml").exists());
assert!(dir.join("index.mq.md").exists());
let eng = std::fs::read_to_string(dir.join("engineering.yaml")).unwrap();
@@ -1432,7 +1443,8 @@ fn catalog_hooks_knowledge_by_default() {
assert_eq!(code, 0, "{stderr}");
assert!(dir.join("catalog.yaml").exists());
assert!(dir.join("engineering.yaml").exists());
assert!(dir.join("graph/graph.json").exists());
assert!(dir.join("ekc/graph/graph.json").exists());
assert!(dir.join("graph/edges.json").exists());
}
#[test]