Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
b8a4ddd38f | ||
|
|
352bc0d2c5 | ||
|
|
8a6d09d582 | ||
|
|
dcd3d329d4 | ||
|
|
0e1bfb3359 | ||
|
|
e9ae7ff1ae | ||
|
|
ecbdd18303 | ||
|
|
bedd53e212 | ||
|
|
7674ebb869 | ||
|
|
434be9fd52 |
No files matched your search
@@ -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"
|
||||
@@ -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
|
||||
|
||||
@@ -103,3 +103,4 @@ tests/ext/_sbx_cow/
|
||||
|
||||
tests/ext/_sbx_*/
|
||||
examples/**/_example_sbx/
|
||||
.secrets/
|
||||
@@ -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
@@ -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
@@ -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"
|
||||
|
||||
@@ -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,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)"
|
||||
|
||||
Vendored
+7
@@ -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
@@ -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)) |
|
||||
|
||||
@@ -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:方括号标记调用) |
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 语法设计:标记如何构成调用(在「只执行标记」原则下)
|
||||
|
||||
> **2026-10-23 审阅裁决**:保留显式标记和正文默认安全;性能数值是旧实验,不作为当前基准。持久跨文档接口优先具名参数,但不禁止位置参数;反引号声明与顺序改变可能是接口变化。当前调用与开发方向见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未改代码) |
|
||||
|
||||
@@ -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?
|
||||
- 这是已实现、受限试点还是设计目标?文档和发布声明是否一致?
|
||||
|
||||
**准入原则**:内部可以使用成熟编译器、数据库和协议技术;外部必须减少知识在“说明、程序、索引、工具描述”之间的重复翻译。独特性由这条链的实际收益体现,不由新符号数量或与其他语言不同的程度体现。
|
||||
@@ -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` 自动推广为本路线的完成。
|
||||
@@ -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
@@ -1 +1 @@
|
||||
2.1.0
|
||||
2.1.1
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -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
@@ -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
@@ -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(¶ms, &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(®.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(¶ms, &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(®.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
@@ -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)?,
|
||||
)?;
|
||||
|
||||
|
||||
@@ -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()) {
|
||||
|
||||
@@ -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};
|
||||
|
||||
@@ -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
@@ -64,17 +64,43 @@ fn dispatch(req: &Value) -> Result<Value, Value> {
|
||||
Some("artifact.impact") => artifact_impact(¶ms),
|
||||
Some("artifact.bind") => artifact_bind(¶ms),
|
||||
Some("artifact.execute") => artifact_execute(¶ms),
|
||||
Some("artifact.patch") => artifact_patch(¶ms),
|
||||
Some("artifact.extract_pure") => artifact_extract_pure(¶ms),
|
||||
// `<TAB>` M9: occlusion label search (two-tier vocabulary).
|
||||
Some("labels.search") => labels_search(¶ms),
|
||||
// `<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
@@ -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
@@ -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
@@ -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");
|
||||
|
||||
@@ -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(_)
|
||||
)
|
||||
}
|
||||
@@ -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
File diff suppressed because it is too large.
Load diff
+82
-10
@@ -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
@@ -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};
|
||||
@@ -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
@@ -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
@@ -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
@@ -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]
|
||||
|
||||
Reference in new issue
Block a user