Compare commits

..
12 Commits
Author SHA1 Message Date
cflmyandCursor dc853fb580 release: bump to 2.1.2 (EK production chain + View V0–V3 bar)
Ship evidence/closure invalidation, verify/adjudicate, reuse_execute and
agent bind/publish gates, document.extract, KnowledgePresentation + SSE
page_token, and upload max_bytes with the 45-test offline gate.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-24 22:52:03 +08:00
cflmy 0b80ff8e50 docs: redesign view knowledge reading experience 2026-10-24 02:51:03 +00:00
cflmyandCursor b8a4ddd38f release: bump to 2.1.1 (executable-knowledge spine)
Ship BoundCall/NarrativeRef/generation CURRENT notes with Cargo, ext pack, README, debian, and release Highlights.

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

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

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

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

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

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

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

No files matched your search

+36 -53
View File
@@ -14,66 +14,49 @@ description: >-
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
<!-- CORE_SYNTAX_V2.1: must stay at the top so skill_brief budgets never truncate it -->
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
## CORE SYNTAX (v2.1 Occlusion — mandatory)
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
These rules are the **current default**. Do **not** teach Classic `[key](map)` index or “bold is return of print”. Classic migration only: [migration-classic.md](migration-classic.md).
1. **File suffix** `.mq.md`. Print with `> print text=…` / `> 打印 内容=…` — never use `**…**` to print.
2. **`**…**` = code / return expression.** `*…*` = statement (bind / expr). Closing markers touch the last token (no trailing space).
3. **`[描述](payload)` = occlusion:** `[]` is prose (never executed); `()` is the only executed part. Empty `()` → `None` stub.
4. **Read collections with `access(coll, key)`** (aliases `取` / `取值`). **Never** use `[key](map)` as index under default Occlusion.
5. **Foreach:** `- [描述](遍历 coll 为 item)` (`遍历`/`for`, `为`/`as`/`in`). Prefer explicit traversal when generating new code.
6. **Import / call:** frontmatter `import:` / `导入:`; call `lib.member`. One language (EN or ZH) per file.
7. **Control flow:** `#` object/type, `##`+ function, `+` params, `1.`/`2.` branches, `-` loops, `N. *` else. No invented `if`/`for`/`def`/`return` keywords.
8. **Prose vs code:** blank line separates comment paragraphs from executable lines.
9. **GFM tables** for data; prefer `table.put` over `json.set` chains. `ext/**` never calls `host_*`.
10. Body narrative `[描述](target)` is lazy (NarrativeRef) — reading does not execute side effects.
| Marker | Meaning (v2.1) |
|--------|----------------|
| `#` / `##`+ | Object/type · function/method |
| `*…*` | Statement |
| `**…**` | Return / code expression |
| `[描述](payload)` | Occlusion step (payload executes) |
| `access(c, k)` | Collection read |
| `> fn …` | Call |
| GFM table | Collection literal |
Canonical: `doc/design/core-surface.md`, `doc/design/document-native-development-guide.md`. Deeper tables: [reference.md](reference.md). Patterns: [examples.md](examples.md). Authoring craft: [marqdo-dev](../marqdo-dev/SKILL.md). Release: [marqdo-release](../marqdo-release/SKILL.md).
Executable-knowledge gate: [`tests/executable_knowledge/`](../../tests/executable_knowledge/README.md).
## Hard rules (do not violate)
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
8. Prefer ending side-effect-only function bodies with `*None*` / `*无*` / whole-line `**` / `****` when later lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped), not function end.
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. Read collections with **`[key](map)`**, not footnote indexes for new code. In `markup: occlusion` files read with **`access(map, key)`** — there `[x](y)` is occlusion, not index. **Positive copy-paste shapes** (result map, soft-error pack, sparse `table.put`): [marqdo-dev](../marqdo-dev/SKILL.md) §2 · [examples.md](examples.md) §6e. Do **not** extend legacy `json.set` in `ext/ai` — refactor to tables.
12. **One language per file:** Do not mix EN and ZH API names in the same `.mq.md` (imports, calls, params). Pick English *or* Chinese mirrors for the whole program.
13. **Sandbox trial habit (Agent / generated `.mq.md`):** Prefer `agent.trial` / `run sandbox=True` / `sandbox.open`→`run`→`diff`→`commit` before promoting to the host tree. Host files must stay unchanged until a successful commit. Caps live in `sandbox.profile` GFM tables — do not invent a second dialect.
1. Obey **CORE SYNTAX** above — Occlusion is default; do not emit Classic index links.
2. **Identifiers:** params `` + `name` ``; inside `*…*` / `**…**` bare ids are variables. Quote text literals. Standalone `>` calls: backticks where bare would be text.
3. **Structure lines** (`#` `>` `+` `-` `|`) are not wrapped in italics.
4. **Paths:** bare `/` in expressions is division; in call args / table cells unspaced `a/b` is path text. Ratios as text need quotes (`"1/5"`).
5. End side-effect-only helpers with `*None*` / `*空*` / `**` / `****` when the outer function continues. Lone `---` is a thematic break, not function end.
6. **`ext/**` never calls `host_*`.** Prefer tables over `json.set` / `json.append`.
7. **One language per file.** Sandbox trial before promoting Agent-generated trees.
8. Browser: Marqdo on WASM + `lib/browser` tables; do not hand-write business JS.
## Markup → meaning (v0.2)
| Marker | Meaning |
|--------|---------|
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
| `##` … `######` | **Function / method** (nesting by heading depth). |
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
| Frontmatter nested `import:` / `导入:` map | Import file (`bind: path.mq.md`) or short name (`bind: lib.member`) |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
| `****` or `**` + spaces + `**` | Return `None` and end function body |
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
| GFM table after empty RHS bind | Collection; get with `access(coll, "key")` (legacy `` `m`[^key] `` remains available) |
| `- [item](遍历 coll 为 item)` | Foreach |
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
| Unmarked prose | Comment |
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
## Occlusion syntax (v2.1.0)
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.
- `[描述](实现)` — `[]` 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))`.
- Foreach: `- [篮子里的每个果子](遍历 篮子 为 果)` (accepts `遍历`/`for` and `为`/`as`/`in`).
- Calls inside `()`: `加(1)` / `加(1, 2)` / `加一 号(31)` / `txt.str_trim(" x ")` — `)` terminates, commas optional.
- Tooling: `marqdo labels pending` (stub ledger) · `marqdo labels --grep 词 --count` · `marqdo migrate labels . --mark --write` · `marqdo check` reports `label.missing` / `label.empty_payload` / `label.ref_dangling`.
## Minimal program
```markdown
@@ -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"
+5 -3
View File
@@ -126,9 +126,11 @@ 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.2**:可执行知识生产链——证据/闭包 · verify/adjudicate · reuse_execute/bind_execute · document.extract · View KnowledgePresentation + SSE page_token · 上传限流
- **v2.1.2**: Executable-knowledge production chain — evidence/closure, verify/adjudicate, reuse_execute/bind_execute, document.extract, View KnowledgePresentation + SSE page_token, upload caps
- **v2.1.2 ext**:扩展包同步 2.1.2 / Ext pack 2.1.2
- **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
- **v1.5.2**:外联 v3 P0/P1——raw stdin + 每 cell 输入 · plan API · snapshot · `view capture` · Persist
- **v1.5.2**: Foreign v3 P0/P1 — raw stdin + per-cell inputs, plan API, snapshot export/import/replay, `view capture`, Persist
- **v1.5.2 ext**:扩展包同步 1.5.2 / Ext pack 1.5.2
+1
View File
@@ -103,3 +103,4 @@ tests/ext/_sbx_cow/
tests/ext/_sbx_*/
examples/**/_example_sbx/
.secrets/
+73
View File
@@ -69,6 +69,79 @@ marqdo ext add web
## Unreleased
### Added
### Fixed
### Changed
## v2.1.2 — 2026-10-24
### Highlights
**可执行知识生产消费链 + View 阅读体验发版门槛**:证据摘要进闭包/句柄;`artifact.verify` / `knowledge adjudicate` 结构化裁决;`artifact.reuse_execute` 与 `agent_eng_bind_execute` / `publish_gate` 实际复用(非 n-gram);`document.extract` 文本/Markdown + PDF/OCR 显式失败;View `KnowledgePresentation`、说明锚点、SSE `page_token` 过期包拒绝;上传 `max_bytes`;门禁 45 项(含 100/1000 单元)。CLI · wasm · ext **2.1.2**。
```bash
git checkout v2.1.2 && cargo build --release
marqdo ext add web
cargo test --offline --locked --test executable_knowledge
```
**核心表面 Δ(Core surface Δ)**:**无增删关键词**——语义/MLSP/View/Agent 宿主扩展;不改变默认 Occlusion 链接读法与表几何。
### Added
- **证据与闭包(F0/M02)**:来源 digests 进入 artifact/evidence/closure;business handle 改/删来源失效;锚点/可读性诊断。
- **验证裁决(F0/M03)**:`artifact.verify` 结构化 `may_bind` / `may_publish`;policy 枚举;`knowledge adjudicate`;CLI `--fail`。
- **语法 Skill(F0/M05)**:CORE SYNTAX 置顶;`migration-classic.md`;`skill_core_card` 与预算截断防护。
- **绑定执行(F1/M04)**:`artifact.reuse_execute`;`agent_eng_bind_execute` + `eng_publish_gate`(`candidate_only` / product gate);host_query `mlsp`;`tests/ext/agent-eng-bind-gate.mq.md`。
- **发布与来源(F2/M06–M07)**:统一 `EXCLUDED_DIRS`;`publish_manifest.json`;`function_sources` 函数级来源覆盖。
- **文档提取(F3/M01)**:`document.extract` DocumentSource→ExtractedDocument;PDF/DOCX/OCR 显式 `failed`;超限截断 `partial`;Web 上传 `MaxBytesReader` / `LimitReader`。
- **View V0–V3(子集)**:正文优先;no-exec;`KnowledgePresentation`(`semantic_generation` / `page_token` / `local_deps`);SSE 过期包拒绝与帧选择保留;print/响应式;1000 单元 compile smoke。
- **故事门禁(M08)**:建库→复用→来源变更失效→修复重绑。
### Fixed
- View 说明链接 raw-string 截断;skill_brief / CORE SYNTAX 预算不被冲突旧规则吃掉。
- 上传体积限制在 multipart 解析前生效(不再只靠内存 form 预算)。
### Changed
- CLI / wasm / `ext/VERSION` **同步 2.1.2**。
- `tests/executable_knowledge` 门禁扩至 45 项;README 切片进度表与发版子集对齐。
## v2.1.1 — 2026-10-23
### Highlights
**可执行知识主链落地(S0–S6)**:BoundCall 双后端共享解析、正文 NarrativeRef、来源/适用期、digest 保护补丁与纯表达式提取、整代 `CURRENT` 投影与闭包摘要;订单发票示例双后端输出 `113`;离线门禁含 100 单元语料与 CLI 冒烟。
```bash
git checkout v2.1.1 && cargo build --release
marqdo ext add web
marqdo run examples/executable-knowledge/docs/invoice-answer.mq.md
```
**核心表面 Δ**:**无增删关键词**——同模块 `Type.member` 纳入 BoundCall;语义投影新增 `bound_calls` / `dynamic_calls` / `hashes.closure` / NarrativeRef 步骤;不改变默认 Occlusion 链接读法。
### Added
- **BoundCall / DynamicCall**:`sema::bind::resolve_for_exec`;Tree 与 Bytecode 静态路径对齐;`bound_calls.json` / `dynamic_calls.json`;同模块定义树路径绑定。
- **NarrativeRef**:注释行 Markdown 链接 → `narrate` / `navigation` 步骤;围栏与行内代码不计步骤。
- **来源与适用性**:frontmatter `sources` / `valid_until` → `evidence=sourced|expired|missing_source`;`artifact.bind policy=business`。
- **局部编辑与提取**:MLSP `artifact.patch`(digest + wording 回滚);`artifact.extract_pure` 纯表达式预览。
- **整代与闭包**:`generations/<id>/` + `CURRENT`;`hashes.closure` 随依赖变化;锁报告 `classes`。
- **门禁**:`tests/executable_knowledge`(含 100 单元);CI `.github/workflows/executable-knowledge.yml`;项目扫描 depth/size/count 上限。
- **示例**:`examples/executable-knowledge` 发票含税链可运行;负知识文档。
### Fixed
- Bytecode 裸名解析不再跨 import scope 误连同名函数;同模块 `Type.member` 写入 path_index 供兄弟调用。
### Changed
- Agent / reuse 发现结果标记 `discovery_only` + `bind_required` / `bind_targets`,不可把打分结果直接当可执行目标。
## v1.5.2 — 2026-10-18
### Highlights
Generated
+2 -2
View File
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "2.1.0"
version = "2.1.2"
dependencies = [
"anyhow",
"assert_cmd",
@@ -610,7 +610,7 @@ dependencies = [
[[package]]
name = "marqdo-wasm"
version = "2.1.0"
version = "2.1.2"
dependencies = [
"marqdo",
"serde_json",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "2.1.0"
version = "2.1.2"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
+7 -5
View File
@@ -281,9 +281,11 @@ marqdo catalog public -o .marqdo
---
## 现状(v2.1.0)
## 现状(v2.1.2)
- **链接语法(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.2)**:证据/闭包失效 · `verify`/`adjudicate` · `reuse_execute` / `eng_bind_execute`+`publish_gate` · `document.extract` · View `KnowledgePresentation`+SSE `page_token` · 上传限流 · 门禁 45 项(100/1000 单元)· 扩展包同步 **2.1.2**
- **可执行知识主链(v2.1.1)**:BoundCall 双后端 · NarrativeRef · 来源/适用期 · `artifact.patch` / `extract_pure` · 整代 `CURRENT` + closure · 发票示例 `113`
- **链接语法(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 +321,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.2)
**安装解释器(任选其一)**
@@ -334,7 +336,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.2 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -373,7 +375,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.2
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "2.1.0"
version = "2.1.2"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
+15
View File
@@ -1,3 +1,18 @@
marqdo (2.1.2-1ppa1) noble; urgency=medium
* Marqdo 2.1.2: executable-knowledge F0–F3 + View V0–V3 release bar
(evidence/closure, verify gates, bind/reuse_execute, document.extract,
KnowledgePresentation, SSE page_token, upload max_bytes).
-- cflmy <pingan@cflmy.cn> Sat, 24 Oct 2026 14:50:00 +0000
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
+11 -3
View File
@@ -13,12 +13,18 @@
## 当前文档
> **可执行知识下一阶段的规范优先级**:实现 `[]()`、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/view-knowledge-reading-experience-2026-10-24.md](design/view-knowledge-reading-experience-2026-10-24.md) | **View 知识阅读体验重设计(建议)**:正文优先、结构导航、就地知识说明、来源与运行状态、响应式线框、实现契约与验收;含当前呈现和 no-exec 反例 |
| [roadmap/qdagent-knowledge-support-gaps-2026-10-24.md](roadmap/qdagent-knowledge-support-gaps-2026-10-24.md) | **求道知识沉淀与文档编译支撑缺口**:2.1.1 源码复核、来源/依赖失效反例、验证与 Agent 协议、语法提示词、导入底座及跨库分工 |
| [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 +118,8 @@
| [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 |
| [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 |
| [next/Marqdo_Executable_Knowledge_Testing.md](next/Marqdo_Executable_Knowledge_Testing.md) | **可执行知识语法测试与兼容性规程**:标准库、扩展库、CLI、Tree/Bytecode 的仓库级门禁 |
| [roadmap/executable-knowledge-gaps-2026-10-23.md](roadmap/executable-knowledge-gaps-2026-10-23.md) | **v2.1 现状与规划缺口审计(方向修订)**:保留 G01–G12 代码证据,以可读步骤、确定执行、早期 AI 复用和局部修改重排 S0–S6,严格治理按场景增加 |
| [../tests/executable_knowledge/README.md](../tests/executable_knowledge/README.md) | **S0 作者基线门禁**:六类任务语料、作者成本计数、预期失败与 Bytecode 同名误连缺陷指纹 |
| [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 |
| [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 |
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
@@ -1,5 +1,7 @@
# 语义评估:参数能否从上下文推断(含叙述式调用)
> **2026-10-23 审阅裁决**:保留参数来源可见、避免隐藏调用者环境的边界;下文已被否决的 L0 建议不可重新启用。自然语言只连接和解释,不能成为隐式执行触发器;当前指导见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **§3 的 L0 方案已被否决**(违反「只执行标记」原则);L1/L2 结论仍有效 |
@@ -1,5 +1,7 @@
# 评定:`[描述](语句)` —— 方括号读作「人话」,圆括号读作「机器话」
> **2026-10-23 审阅裁决**:本文的 Classic 冲突统计和兼容取舍属于迁移历史;v2.1 默认采用描述包裹 payload,不能据旧冲突恢复默认 `[键](集合)`。保留标签的阅读/检索/步骤价值,不强制所有子表达式命名,也不把标签当作目标或权限依据。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **已决策:走「路线二 纯度」**(落地见 [label-freshness-and-repair.md](label-freshness-and-repair.md)) |
+2
View File
@@ -1,5 +1,7 @@
# 调用实参:具名与位置
> **2026-10-23 适用范围校正**:本文保留早期调用尾部规则和历史示例,不是 v2.1 全部调用语法。当前已有 `f(args)` 及具名实参;默认紧邻 `](` 是描述包裹 payload,不再是下文所述的 Classic 取元。语法审阅与开发取舍见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),当前行为须由默认模式测试复核。
| | |
|---|---|
| 状态 | 已定(v0.1 增补;2026-09-14:方括号标记调用) |
+2
View File
@@ -1,5 +1,7 @@
# 语法设计:标记如何构成调用(在「只执行标记」原则下)
> **2026-10-23 审阅裁决**:保留显式标记和正文默认安全;性能数值是旧实验,不作为当前基准。持久跨文档接口优先具名参数,但不禁止位置参数;反引号声明与顺序改变可能是接口变化。当前调用与开发方向见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(未改代码) |
+9 -7
View File
@@ -3,22 +3,24 @@
| | |
|---|---|
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
| 日期 | 2026-09-22 |
| 日期 | 2026-09-22;2026-10-23 校正 v2.1 默认链接语义 |
| 守卫 | `tests/core_surface.rs` ⇄ `src/parse/mod.rs` `CORE_CONSTRUCTS`(改动任一侧不同步 → CI 红) |
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)(语义宪法)· [layers.md](layers.md)(准入戒律)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.1/T1.3 |
> **戒律总纲**:核心标记是**封闭集合**(约 19 个构造)。新增任何一行必须走 ADR(见 [layers.md](layers.md) 准入戒律)并回答「为什么现有标记不够」;生态需求的默认答案是**进 ext**。本表 id 列与守卫测试强一致:改表不同步 `CORE_CONSTRUCTS`(或反之)、样例文件缺失,一律 CI 红。
> **版本边界**:构造 ID 是历史守卫标识,不是固定不变的语义说明。`link-index` ID 暂保留以匹配注册表,但默认 `[]()` 已是描述包裹 payload;旧索引语义仅属于显式 Classic 兼容路径。未来步骤/知识投影见[文档原生指导](document-native-development-guide.md),不要把目标能力当作当前已实现。核心数量之外,还要审查上下文例外和作者负担。
## 1. 行构造
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `narrative` | 无标记文字 | 叙述(注释) | 段落内延续到空行;**默认安全**——永远不存在「叙述被执行」的路径 | `tests/markup-v03/soft-emphasis.mq.md` |
| `narrative` | 无标记文字 | 叙述(不执行) | 段落内延续到空行;普通叙述不触发执行;未来知识引用投影也不改变此权限边界 | `tests/markup-v03/soft-emphasis.mq.md` |
| `blank` | 空行 | 段落边界 | 叙述分段的唯一手段;不得被赋予其它语义 | `tests/markup-v03/inc-prose.mq.md` |
| `heading-unit` | `#` / `##` | 对象 / 函数单元 | 标题即单元边界,按深度嵌套;正文禁止用 `##` 做版式(会变成函数) | `tests/markup-v03/decl-ident-only.mq.md` |
| `call-line` | `>` | 调用行 | 输出等副作用 = **普通函数**,不是架构标记 | `tests/markup-v03/dual-call.mq.md` |
| `branch-list` | 体内 `1.` 递增 | 分支 | 自 `1.` 起序号递增构成一个判断;重出 `1.` 开新判断;`N. *` = else;**不是所有有序列表都是 if** | `tests/markup-v03/greet-default.mq.md` |
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [项](集合)` | `tests/structure/loop.mq.md` |
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [说明](遍历 集合 为 项)`;描述不是绑定变量名 | `tests/structure/loop.mq.md` |
| `param` | `` + `名` `` | 形参(兼容形) | 首选叙述 `` `名` `` 升参(宪法 §8);`+` 形仅兼容保留 | `tests/markup-v03/greet-default.mq.md` |
| `table` | GFM 表 | 集合 | 几何即类型([tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md));**绑定 = 数据,未绑定 = 文档表** | `tests/structure/collection.mq.md` |
| `fence` | ` ```lang ` | 外联 | 语言块原样外联,不进 Marqdo 语义 | `tests/lib/foreign-python.mq.md` |
@@ -30,12 +32,12 @@
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.mq.md` |
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 只有粗体进入执行;判别序:赋值 → 调用 → 表达式 | `tests/markup-v03/multi-bold.mq.md` |
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 粗体内代码判别序:赋值 → 调用 → 表达式;不取消调用行、返回等其它显式执行入口 | `tests/markup-v03/multi-bold.mq.md` |
| `italic-return` | `*…*` | 返回 | 改变控制流(**返回是架构**);返回即结束函数体 | `tests/markup-v03/inc-prose.mq.md` |
| `empty-return` | `*None*` / `****` | 空返回 | 返回 `None` 并结束函数体 | `tests/markup-v03/empty-return-none.mq.md` |
| `link-index` | `[键](集合)` | 取元 / foreach | **主取元语法**;与 bracket-call 靠 `]` 后是否紧邻 `(` 消歧 | `tests/lib/table-collections.mq.md` |
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;与 link-index 消歧同上 | `tests/structure/bracket-call.mq.md` |
| `footnote-index` | `集合[^键]` | 过渡取元 | **仅兼容**;新代码一律写 link-index | `tests/structure/footnote-index.mq.md` |
| `link-index` | `[描述](表达式)` | 描述包裹 payload(历史 ID) | 默认 Occlusion;取元可写 `[说明](access(集合, 键))`,不按描述取键;循环载荷见上 | `tests/occlusion/access-and-loop.mq.md` |
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;紧邻 `](` 的默认语义为 payload 遮蔽,不是旧索引 | `tests/structure/bracket-call.mq.md` |
| `footnote-index` | `集合[^键]` | 兼容取元 | 保留既有能力;新代码优先 `access(...)`,需要解释时包裹描述,不再推荐旧 `[键](集合)` | `tests/structure/footnote-index.mq.md` |
| `soft-emphasis` | `*仅*` / `**说明**` | 忽略 | 非代码形强调**不执行**——默认安全的关键消歧规则 | `tests/markup-v03/soft-emphasis.mq.md` |
## 3. 词法大类(LineKind,`src/lex/mod.rs`)
@@ -0,0 +1,284 @@
# Marqdo 文档原生开发指导:让知识的表达、执行与复用成为同一件事
| 项目 | 约定 |
|---|---|
| 状态 | 下一阶段开发指导与规划修订;不表示下述目标接口已经实现 |
| 日期 / 审阅基线 | 2026-10-23 / `main`,`7674ebb`;继承缺口审计的 `434be9f` 代码证据 |
| 原始意图 | [009](../next/009.md)、[附属设计](../next/Marqdo_Executable_Knowledge_Design.md)、[附属示例](../next/Marqdo_Executable_Knowledge_Example.md) |
| 配套实施文件 | [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)、[缺口与交付路线](../roadmap/executable-knowledge-gaps-2026-10-23.md) |
| 本轮边界 | 校正开发方向、作者体验、AI 工作协议和验收;不新增语法,不宣称实现新能力 |
## 1. 审阅结论与规范关系
Marqdo 的优势不在于给传统程序换一套 Markdown 符号,而在于:**读者解释知识、作者修改知识、程序执行知识、AI 查找并复用知识,能够指向同一份有结构的文档和其中的同一步。** 标题、叙述、表格、链接描述、输入输出、来源及执行行为不应分散在彼此手工同步的系统中。
现有规划没有放弃这一目标,但工程排序存在偏移:把身份、图、证据、锁、句柄、晋升全部铺完,再验证人和 AI 是否更容易使用。这样可能交付一个功能齐全的制品管理系统,却让文档作者承担另一套注册、声明、审核和配置工作。需要改变交付方法,不必推翻确定性编译、绑定和权限机制。
本指导规定**为何开发、作者维护什么、怎样证明值得开发**;详细规范规定语义模型与执行约束;路线图规定当前缺口、切片与完成证据。三者不是三套平行设计。遇到冲突,依次采用:`009` 的产品意图 → 本指导对作者负担、场景分级和交付次序的修订 → 详细规范的工程规则 → 附属概念示例。当前代码与测试证明“已实现什么”,不能把代码局限升级为永久语言禁令;原始讨论保留,不据其重新引入已被否决的方案。
### 1.1 方向修订清单
| 容易偏移的做法 | 修订后的要求 | 必须保留的技术约束 |
|---|---|---|
| 先做完整知识治理平台,再给作者使用 | 从一篇可读、可运行、可定位步骤的文档交付,逐层扩展 | 每个已支持路径都有准确的目标和效应边界 |
| 为进入知识库再写 YAML、注册表和索引 | 从源码推导;只有不能推导的领域事实才需作者补充 | 生成物有版本,可重建,可检查来源 |
| 所有逻辑先封装成可登记函数/类 | 一次性逻辑直接写;需要命名、解释或复用时逐步提取 | 作用域、形参、返回与副作用明确 |
| 所有调用先审核、锁定、签发远程凭据 | 本地探索、项目复用、严格业务、远程执行分级 | 精确目标、运行时权限不能被标签或模型绕过 |
| AI 只能搜文档、填工具参数 | AI 可以读步骤、组合、选择候选、局部修改、提取和验证 | 模型的选择必须转成显式目标,由编译器校验 |
| 为“独特”拒绝普通调用或新增更多标记 | 保留简单 payload;让 Markdown 结构提供程序之外的信息 | 无第二套表达式文法,无裸词隐式执行 |
| 核心构造数量不增长就是简单 | 同时检查上下文例外、记忆负担和诊断成本 | 新构造需 ADR;不靠把新规则藏进旧构造绕过审查 |
### 1.2 四个不能互相替代的完成条件
1. **读得懂**:不打开生成图,也能从源文件看出目的、关键步骤、参数角色和限制。
2. **执行同一件事**:标签表达意图,payload 决定计算;运行 trace 能回到源码步骤,不能执行另一个同名目标。
3. **改得动**:人或 AI 能修改一个明确步骤,看到影响与验证结果,不必重写整份文档或同步多份签名。
4. **复用得对**:找到已有能力后实际调用它;不满足条件时给出具体拒绝原因,而非用复制源码掩盖失败。
“更适合 AI”是待验证的产品假设,不是 Markdown 文件后缀自动赋予的性质。正确性和作者成本优先于 token 下降;错误复用更便宜不算优化。
## 2. 语法审查的保留、修正与暂缓
以下裁决针对审查结论的适用范围,不重写历史实验记录。旧文档中的原型、性能数值和当时的 `Value`/AST 限制,不能直接当作 v2.1 的规范或测试结果。
| 审查材料 | 保留的洞见 | 需要修正的外推 / 本轮处置 |
|---|---|---|
| [函数即命名](function-as-naming-philosophy.md) | 从正文计算出发,命名应降低理解和复用成本;避免无意义包装 | “具名给值缺失”是历史观察,当前有具名参数;替换模型是教学解释,不意味着禁止递归、前向引用或必须文本展开 |
| [方括号作为标签](bracket-as-label-evaluation.md) | 描述与 payload 共址;标签帮助解释、检索和拆步骤 | Classic 冲突是迁移历史,不据此恢复默认 `[键](集合)`;不强制每个常量或子表达式都有标签 |
| [圆括号与可读调用](paren-call-and-readable-invocation.md) | 调用标记应明确;保留 `f(args)` 的局部可读性 | 原型撤回不代表现有版本缺少该能力;Marqdo 的独特性不依赖消灭熟悉的表达式形式 |
| [从标记推导调用](call-syntax-from-marks.md) | 语义成分有明确标记;自然语言是连接与解释,不参与猜测调用 | 持久跨文档接口优先具名实参;短而稳定的位置参数仍合法。推断参数的声明次序变化属于接口变化,不承诺任意润色都无影响 |
| [环境参数](ambient-parameters-evaluation.md) | 参数来源应可见,避免调用者隐式环境影响复用 | 文档顶部已否决 L0 裸“执行”触发,正文旧建议不能重新生效;文件级常量也须有明确绑定与依赖,不变成动态作用域 |
| [函数作为值](functions-as-values-evaluation.md) | 区分名称数据、一等函数、有限查表;避免无需求增加核心复杂度 | “匿名函数必不能索引”“动态调用必然破坏契约”不是普遍定理。将来可研究稳定节点身份与运行时契约;本轮不引入闭包,也不永久禁止 |
| [函数作为表格](function-as-table-semantics.md) | 数据表几何有既定含义;契约表不可另造一份参数声明 | 不把表格全部变成函数,也不把“现有实现不支持”写成“表格不能计算”;有限决策表先评估库方案,只有明确角色和歧义测试后才讨论语言扩展 |
| [核心表面](core-surface.md)、[分层](layers.md) | 核心小、标记可解释、构造有测试与准入流程 | 清单中的旧取元/循环说明需随迁移更新;固定数量不等于低认知成本,守卫通过也不证明文档语义正确 |
| [链接设计](link-syntax.md)、[告警疲劳](warning-fatigue-control.md) | 单一 payload 文法;标签漂移可提示;默认安静、按需严格 | 标签不是纯粹可丢弃的注释,也不是事实证明;不做每次运行重复的批准仪式,不靠词汇相似度证明描述与代码一致 |
### 2.1 继续冻结的语法边界
- 默认 `[]()` 是描述包裹 payload;旧取元只能在显式历史兼容路径下解释。现行取元用 `access(...)` 等已支持形式;循环使用明确遍历载荷。
- `[]()` 不等于“仅函数调用”:计算、取元、调用、遍历、叙述引用都需要各自语义角色,不能只收集 call 边就宣称完成知识步骤。
- 正文引用与可执行位置有不同调度权限。普通句子不因出现“执行”“发送”或工具名而运行;正文解析成引用也不自动求值。
- 不把所有 `#` 解释成某种知识对象,或把继承悄悄变成实例关系。标题的既有语义必须兼容,IR 可区分 Type、Entity、Fact、Function。
- 不给同一参数增加正文声明、签名表、工具 schema 三套作者真相。规范签名和工具 schema 是投影;契约表补充类型、约束和说明,不偷偷增加形参。
- 可读源文件是硬要求;普通 Markdown 渲染器是否把含空格/嵌套表达式的链接渲染成可点击链接是另一件事。不能承诺全部标准渲染器理解执行语义。
### 2.2 哪些编辑不能当成“只是改文案”
不含语义标记的普通叙述润色,应保持执行结果和实现摘要;标签改名应保留 payload 行为,但更新展示/检索内容。反引号声明、首次出现顺序、标题名称/层级、粗斜体、表格几何、契约、来源和适用范围的改变则可能影响程序或知识可信性。编辑器必须展示真实差异,不能统一标为 prose-only。
标签漂移诊断应说明“描述或实现可能需要复核”,不能自动替作者改写业务意图。自然语言一致性检查可作辅助建议,确定性检查仍需可定位的符号、类型、契约或测试证据。
## 3. 作者工作流:先写清楚,再获得复用能力
### 3.1 一次性计算不需要预先建知识模型
下面是当前默认语法的完整最小程序。无模式开关、无项目注册、无知识 ID、无锁文件。
```markdown
# main
这是演示订单,单价与数量直接写在计算处。
**小计 = [两件商品的小计](2 * 30)**
> print text=`小计`
```
可读意图和精确计算共址。这个标签值得保留,因为它说明本次计算的业务角色;不要求把 `2`、`30`、乘法分别命名。
### 3.2 需要解释或复用时才提取命名能力
```markdown
## 商品小计
根据购买数量`数量`和商品单价`单价`计算小计。
*[按数量与单价计算](数量 * 单价)*
# main
计算同一笔演示订单。
**小计 = [两件商品的小计](商品小计(数量=2, 单价=30))**
> print text=`小计`
```
两个完整程序在本轮本地现有 `target/debug/marqdo` 上分别以 Tree 和 Bytecode 执行,均输出 `60`。这仅验证基础语法,不证明步骤身份、重构工具或 Agent 闭环已经实现;也不是全仓测试报告。可将各块保存为 `.mq.md` 后用 `marqdo run 文件 --backend tree` / `--backend bytecode` 复核。
**后续工具目标**:从选中表达式提取为标题单元,推导自由变量为参数、保持求值顺序与 effect 次数、生成具名调用,并给出可审阅补丁。反向内联也应保留契约和来源关联;无法证明安全的捕获变量、递归、控制流、动态目标或有副作用表达式,先拒绝自动变换并说明原因,不伪称等价。
### 3.3 跨文档复用与事实说明分别增长
当第二篇文档需要这段计算,才提取模块并显式 import;不要为十行单文件强制创建 `corpus/knowledge/apps` 目录树。项目索引按约定发现,明确边界或外部来源时再加入配置。
当“商品小计”依赖政策、时间、币种等条件,再就地补契约与来源。简单乘法不要求假造现实来源;“某商店当前折扣为九折”则不能仅凭函数返回 `0.9` 声称真实。
正文可以说明结果为何成立,目标是引用同一能力和同一次受控执行的结果,而非手抄另一份公式。正文引用 AST、结果投影和绑定身份尚需开发;完整业务链使用[目标示例](../next/Marqdo_Executable_Knowledge_Example.md)验收,不把它冒充当前全部可运行的教程。
### 3.4 维护时看到知识变化,而不只是文件变化
目标维护流程:修改上游规则 → 显示受影响的计算、正文陈述和消费者 → 执行相关测试 → 展示结果/证据/接口各自变化 → 按使用策略接受更新。普通显示文案变更不应触发全库业务审批;证据过期也不必使无关纯工具全部失效。
## 4. 人维护语义,编译器维护机械关联
| 信息 | 作者责任 | 编译器 / 工具责任 |
|---|---|---|
| 目的与步骤 | 有帮助的标题、叙述、标签;避免空泛重复 | 保留源位置和层级,生成步骤投影,不要求手工节点注册 |
| 输入输出 | 一份参数来源和必要契约;领域单位不能靠猜 | 推断规范签名、检查调用、生成 schema 和签名视图 |
| 目标与依赖 | 显式 import、可读名称、必要消歧 | 绑定唯一 SymbolId,生成依赖边与闭包;不要求手写 ID |
| 效应 | 扩展作者声明宿主能力;业务作者必要时收窄允许范围 | 汇总直接及传递效应;未知不得推断 pure;运行时执行能力上限 |
| 事实与来源 | 原始资料、范围、有效期、人工审阅等不可推导信息 | 关联来源、记录验证事件、传播失效;不将文件路径视为事实证明 |
| 身份与版本 | 有意移动/更名时确认必要迁移 | 区分身份与内容摘要;报告歧义,不靠猜测维持假稳定 |
| view / AI 索引 | 不维护第二份可执行描述 | 同一语义模型投影;显示生成代、验证政策和缺失字段 |
生成信息不等于免费:首次编译、缓存修复、错误定位都要可理解。失败时应回到源文档中可修改的位置,而不是只报内部 Artifact 字段名。
稳定身份要诚实:同一次编译内引用和 trace 必须一致;普通文本编辑不应打乱无关节点;复制相似步骤、跨文件移动等无法唯一识别时,要求确认迁移或明确生成新身份。禁止用文本相似度悄悄继承已审核的知识身份。
## 5. AI 原生工作协议:读步骤、改步骤、验证步骤
本节是**待实现的协议约束**,不是新增 CLI 命令清单。优先扩展现有 MLSP、view、EKC 和 Agent 工作簿,不另造一套 Agent 框架或知识库。
### 5.1 发现后的最小上下文包
一次检索返回可展开的上下文卡,而非强制倾倒整个文件或只给函数 schema:
1. 标题路径、任务相关叙述、标签和精确源码片段;
2. SymbolId/步骤节点、source span、源码摘要、生成代;
3. 输入角色、返回、单位、默认值和适用条件;
4. 直接依赖、效应、必要来源及分层验证状态;
5. 支持该能力的例子/测试,相关失败经验、禁用条件和替代能力;
6. 还缺哪些检查、能否在当前 policy 下运行、为何被拒绝。
来源不可用、字段未推导、上下文被截断都须显式标识。按预算可展开依赖,但不能悄悄省略改变适用性或权限的重要信息。原始资料及标签是内容,不是可以覆盖 Agent 策略的指令。
### 5.2 复用、适配、新建的分界
- **REUSE**:AI 可根据任务选候选,提交精确目标与输入;resolver 确认目标、契约、适用性、版本和 effect,执行既有制品。复用不靠“没有生成文件”推断,必须有实际调用 trace。
- **ADAPT**:已有能力接近但不适用;说明差异,保留依赖/来源关联,在局部副本或补丁中改变必要部分,再验证。不为了通过测试改写原始来源或放宽全局策略。
- **CREATE**:没有合适候选或明确需要新语义;记录检索范围和失败原因,在任务预算及写权限允许时新建。不能把检索服务故障当作“仓库没有能力”。
- **ASK / STOP**:缺业务决策、权限或关键证据时报告具体缺口。编译器无法决定的真实意图不交给近似匹配默默补全。
AI 并非只能发现和解释。它可以提出精确目标、组合已有能力、改进表达、重构及补测试;不能以自然语言自报正确来替代执行验证,也不能把含糊名称传给后端任意选一个目标。
### 5.3 局部修改的事务边界
编辑请求至少携带目标文件/节点、期望源码摘要、补丁范围和预期行为变化。应用前检查摘要,源已变化则重新定位和审阅,不覆盖用户改动。应用后重新解析受影响文档,生成语义 diff:参数/返回、目标、effect、控制流、证据与依赖是否改变。
对“只改措辞”请求,检测到接口或实现改变时停止自动合并;对“改计算”请求,运行相关正负例并展示影响。原始文本、格式与未知 metadata 尽量保留,不通过整篇重生成来完成一行修改。禁止修改生成图伪装修复源码。
首个试点只支持可确定定位的纯计算步骤与普通函数,不等待通用 AST 编辑器、跨项目事务或完整知识治理。安全拒绝超范围输入也属于验收。
### 5.4 解释和负知识必须有落点
解释结果应关联到“哪一步、用了哪个目标、哪些输入、哪份来源、哪次验证”,区分已执行观察和模型推断。运行 trace 可以证明程序路径,不能证明任意自然语言论证正确。
失败经验需要保存适用范围、触发条件、关联能力、原因与失效时间/版本。例如“此折扣不适用于退款”应在查询定价能力时可见,而不是埋在另一份聊天记录里。先由普通文档与结构化关联承载,不先新增通用推理语言;过期负知识也要撤销,不能永久拦截修复后的能力。
## 6. 渐进严格:不把治理门槛塞进每一行正文
下面是目标政策分级,不是当前已有四种 CLI 模式。政策由项目/宿主配置和调用上下文选定,源文档保持同一种语法。
| 场景 | 必需条件 | 默认不要求 |
|---|---|---|
| 本地探索、单文件运行 | 明确语法与目标、已有运行时契约、宿主能力限制;如实显示未知状态 | lock、来源、ready 晋升、远程签名句柄 |
| 项目内自动复用 | 精确绑定、输入/适用性检查、效应许可、状态满足所选政策、执行 trace | 所有纯工具都有人审证据、每次独立确认 |
| 严格业务/可复现任务 | 相关依赖与证据锁定、必要验证新鲜度、受控环境和审计;明确不可重放部分 | 对无关文案变化重审整个项目 |
| 远程/多租户/不受信调用方 | 上述相关约束,加可信授权主体、范围、服务端能力上限、撤销/期限与防伪设计 | 把客户端提交的 `allow_effects` 当授权本身 |
`ready` 是“对某项 policy 和输入/上下文已具备复用条件”,不是永久万能认证。未验证的本地草稿可以被检索、查看和按明确权限试跑;不能冒充满足严格政策的可复用事实。测试通过与事实证实分别报告。
正文 `check/view static` 不执行外部效应。用户主动打开的纯预览可复用项目或会话已有政策,不要求每个链接弹窗;effectful 运行始终受宿主能力和明确执行上下文控制。锁和摘要是完整性机制,不自动等于远程授权;可信本地引用无需先搭建凭据服务。
## 7. 交付切片:每片都有文档作者与 AI 能看见的结果
编号与[缺口路线图 §7](../roadmap/executable-knowledge-gaps-2026-10-23.md#7-依赖顺序与可合并切片)一致;G 编号沿用现状证据,M0–M6 保留为工程能力映射,不再被理解为必须全部串行完成的墙。
### S0 作者基线与最小语料
- 选定单文件计算、提取函数、两文档引用、表格取元/遍历、业务政策及拒绝复用六类任务;记录当前写法、输出、诊断和作者重复维护项。
- 优先整理 `doc/README`、核心语法卡片、教程与运行示例的版本状态;不要先扩展通用库数量。
- 为最小样例建立无网络门禁。100 单元及更大语料逐步增长,不阻塞首个可读文档切片。
- 完成证据:别人按当前入口能写出正确默认语法;已实现与预期失败分开报告,不能把待实现测试跳过计为成功。
### S1 可读步骤与唯一目标
- 主要落点:`src/parse/`、`src/ast.rs`、`src/sema/`、`src/knowledge/compile.rs`、`src/view/`。
- 在最小故事内联合完成 G01/G03:保留 label、payload、上下文和跨度;每类步骤有输入输出与依赖投影;旧 EKC 查询索引不再覆盖语义图。
- 普通导航、正文引用、可执行表达式、循环分别处理,正文保持惰性。先确保支持范围内同一引用在源码、view、图中是同一个目标,再扩展覆盖范围。
- 完成证据:作者能从渲染步骤返回对应源码;同名目标不误连;计算/取元/循环不是伪造的 call;重复构建可对照;未支持上下文明示。
### S2 确定执行与早期 AI 复用试点
- 主要落点:`src/sema/`、`src/interp.rs`、`src/bytecode/`、`src/mlsp.rs` 与现有 Agent 入口。
- 完成静态普通函数、显式 import、关联函数的 BoundCall 主链;G02 与 G06 的效应安全下限不可延期。小范围可先用明确纯操作白名单,未知路径必须拒绝纯证明,而非猜 pure。
- 实现最小上下文卡与本地绑定引用;以 stub/no-LLM 测试验证协议,然后用现有 Agent 跑相同故事。无需先完成远程鉴权平台或全面来源审核。
- 完成证据:同一需求实际调用既有函数,不新增同义实现;两个后端 trace 对上图中目标;改目标、错误输入、未知效应、权限不足不能静默执行。
### S3 局部编辑、提取与库可读性
- 主要落点:MLSP 编辑/定位、相关 sema/检查入口、`lib/`、`ext/`、教程与测试。
- 按 §5.3 实现受摘要保护的局部修改和语义 diff;实现受限纯表达式提取,或明确标为待实现,不用人工演示冒充工具能力。
- 迁移标准库/扩展时删掉重复包装与噪音标签,保留有意义的业务步骤、契约和负例;中英镜像含义一致。兼容旧调用接口,不用增加旧语法解释救迁移遗漏。
- 完成证据:同义润色不改执行;改反引号声明能检测签名变化;表达式提取前后结果/effect 次数一致;冲突补丁拒绝;CLI、库、扩展与 view 既有能力继续通过。
### S4 业务知识的来源与适用性
- 主要落点:契约、SourceRef/VerificationRecord、验证事件、Agent 候选解释;完成 G05 与 G07 的项目政策部分。
- 选定书店案例的币种、数量边界、会员范围与政策有效期;给 schema、拒绝诊断及可运行负例,不泛化为全能业务规则语言。
- 同步补齐传递效应与相关负知识;生成契约/状态展示,减少作者重复填写。
- 完成证据:同一计算因输入或证据不同而正确通过/拒绝;来源过期不被 `tests=passed` 覆盖;普通纯工具无需虚构 SourceRef。
### S5 变化传播与严格复用
- 主要落点:`src/sema/lock.rs`、图/impact、产物提交与消费者;完成 G04/G08 和严格 handle 复核。
- 区分身份/接口/实现/证据/闭包,给出可读升级 diff;整代快照保证消费者不会读取混代数据。并发读写一旦开放,该一致性就是前置条件,不能等到此片才承认风险。
- 完成证据:修改依赖政策后,下游计算和正文解释进入影响集合;文案变化不误判实现变化;并发编辑或构建崩溃不导致错目标执行;锁不声称重放网络/随机/LLM。
### S6 生态验收与发布
- G10/G11 从 S0 起每片执行;S6 汇总兼容矩阵、真实工作流和打包后冒烟,不把测试留到最后。
- G12 随实际规模需求推进;远程凭据/多租户是有条件的独立交付。它们不阻塞受信本地试点,也不得被本地通过的测试覆盖为“已安全支持”。
- 完成证据:当前默认语法的 lib/ext/CLI/MLSP/view/WASM 等受影响消费者有明确结果;目标示例中的已发布子集实际可运行,未发布部分保留状态;发布声明与证据一一对应。
## 8. 验证 Marqdo 优势,而不只验证组件存在
### 8.1 必须收集的产品指标
| 维度 | 记录方法 | 失败信号 |
|---|---|---|
| 作者负担 | 完成同一任务所需手写声明、重复字段、配置、跳转和确认次数 | 简单本地算式也必须填写制品清单 |
| 阅读与定位 | 给定问题,定位正确步骤/限制的准确率、耗时与上下文量 | 只看 label 会误导,必须打开生成 JSON 才理解源文档 |
| 可修改性 | 修改范围、无关 diff、语义变化检测率、冲突覆盖数 | 为改一步而重生成全文件;措辞调整偷偷改变接口 |
| 复用质量 | 已有能力发现率、实际调用率、重复实现率、误用率 | 检索命中却重新写代码;正确拒绝算成任务失败而被优化掉 |
| 知识可追溯性 | 结果关联目标、步骤、输入、来源和验证的覆盖率 | `tested` 被当作事实正确;解释引用未执行的步骤 |
| 总成本 | 正确完成任务的 token、工具调用、轮次、总耗时及编译成本 | 只报模型 tokens,隐藏额外注册/审核/修复成本 |
### 8.2 对照实验与门槛
1. 固定任务、可访问能力、输入数据、模型版本、工具能力、预算与超时;比较普通 Markdown+代码/RAG、当前 EKC 和新方案。不能给新方案更多现成实现再声称语法更优。
2. 任务包括成功复用、同名冲突、近似但不适用、未知 effect、过期来源、正文不执行、局部修改及库升级。加入自然语言诱导绕过 policy 的负例。
3. 先测确定性协议,再测多次 AI 运行,保留种子(支持时)、原始 trace、版本、失败样本与分布;小样本不夸大收益。
4. 正确目标、无越权和正文无外部 effect 是硬门槛。原有兼容测试不得降低;效率阈值先测基线再登记,不捏造提升百分比。
5. 若作者负担增加或误用率上升,回到交互/语义设计分析原因,不能只用“更多治理更安全”或“模型更便宜”解释过去。
### 8.3 发布声明分层
- “支持新语法”需语法、迁移、双后端与库兼容证据,不意味着完整知识复用已经交付。
- “本地确定性知识复用”需 S1/S2 支持范围内的端到端与拒绝用例;范围外路径显式不支持,不能回落为模糊执行。
- “严格业务知识复用”还需相关 S4/S5 来源、适用性、失效、锁和一致性证据。
- “安全远程知识执行”需额外的授权、能力上限、凭据/撤销及隔离测试;本地 JSON handle 不等于远程安全。
## 9. 每个开发变更必须回答的问题
提交设计或实现时给出一份短而具体的审阅记录:
- 用户要读/写/改/复用的知识是什么?附源文档前后对照,不只给内部结构图。
- 利用了哪种文档原生信息?若只增加通用框架能力,与主线的必要关系是什么?
- 新增了哪些作者必须手工维护的信息?为什么不能从现有语义推导?
- 是否改变标记、作用域、求值顺序、形参顺序、表格几何或正文安全?分别有哪些测试?
- 人、CLI、view、图和 Agent 是否看到同一目标与状态?失败能否回到源码修复?
- AI 的正确复用/局部编辑如何证明?哪些部分仍需模型判断,哪些由编译器决定?
- 标准库和扩展是否先迁移?是否保住既有公开接口、输出与 effect?
- 这是已实现、受限试点还是设计目标?文档和发布声明是否一致?
**准入原则**:内部可以使用成熟编译器、数据库和协议技术;外部必须减少知识在“说明、程序、索引、工具描述”之间的重复翻译。独特性由这条链的实际收益体现,不由新符号数量或与其他语言不同的程度体现。
+3 -1
View File
@@ -51,7 +51,9 @@ Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识
`implements` · `uses` · `depends_on` · `tested_by` · `documented_by` · `constrained_by` · `decided_by` · `supersedes` · `conflicts_with` · `deprecated_by` · `derived_from` · `failed_by` · `related_to`
落盘:`.marqdo/graph/graph.json` · `edges.json` · `index.json`。
落盘(G01 分离后):
- **权威语义图**:`.marqdo/graph/edges.json` · `nodes.json`(`SemanticProject`,含 `authority` 字段)· `steps.json`
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json`
## 5. CLI
@@ -1,5 +1,7 @@
# 语法设计哲学:函数在「代码即文档」里为何水土不服,以及用什么语义取代
> **2026-10-23 审阅裁决**:保留“正文优先、按需命名”的方向;下文语料统计和“具名给值缺失”等判断属于当时快照。当前已有具名实参;“调用即代入”不规定文本展开实现,也不禁止递归。下一阶段以[文档原生指导 §2–3](document-native-development-guide.md#2-语法审查的保留修正与暂缓)的范围和验收为准,本文不是替换整个函数模型的已批准语法提案。
| | |
|---|---|
| 状态 | **Proposed · 哲学层讨论**(不涉及实现,不含语法提案细节) |
@@ -1,5 +1,7 @@
# 语义探析:代码函数能否解释为一张 GFM 表
> **2026-10-23 审阅裁决**:下文 v1.5.2 实验不替代当前回归。保留现有数据表几何与契约表角色,不重复声明参数;“现有实现不支持函数表”不等于表格不能表达计算。有限决策表和生成式签名视图按真实用例评估,见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(未修改任何代码) |
@@ -1,5 +1,7 @@
# 方案评估:函数能否作为变量的一种(函数即表)
> **2026-10-23 审阅裁决**:以下是旧实现约束与方案权衡,不是“匿名函数无法索引”或“动态调用无法检查契约”的普遍结论。一等函数/闭包本轮暂缓而非永久禁止;有限决策表先评估现有库表达,文中建议的新辅助函数不因此成为已实现能力。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(未修改任何代码) |
@@ -1,5 +1,7 @@
# 调用写法评估:`[函数名](参数)` 与更接近人读的调用形式
> **2026-10-23 审阅裁决**:“原型回退”仅描述当时实验,当前 payload 已支持 `f(args)` 和具名实参。旧 Classic 索引冲突不再决定默认语法;保留熟悉的调用形态与文档原生描述并不矛盾。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),不要把本文备选形式当作已批准的新语法。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(原型已验证并已回退,未合入代码) |
@@ -0,0 +1,463 @@
# View 可执行知识阅读体验重设计
| 项目 | 说明 |
|---|---|
| 日期 | 2026-10-24 |
| 状态 | 详细设计建议,待实施;不是已交付能力声明 |
| 审计基线 | `b8a4ddd` / Marqdo 2.1.1;使用当前源码构建的 debug CLI 复核 |
| 输入 | 用户提供的 view 截图:Executable Knowledge 在 Structure 前,Steps、Target、Kind、Signature、Effects、Verification、Lock digest 等字段大量铺开 |
| 范围 | Live view、静态导出、正文结构、知识说明、运行结果、来源与状态呈现;不改语言语义,不增加作者必填的展示 DSL |
| 关联 | [文档原生开发指导](document-native-development-guide.md)、[View 总体设计](view.md)、[文档面与标注](view-document-annotations.md)、[求道相关框架缺口](../roadmap/qdagent-knowledge-support-gaps-2026-10-24.md) |
## 1. 设计决策
**View 首先呈现知识文档本身,结构帮助读者理解和定位,机器信息解释当前所读内容。** 正文、程序结构、知识关系与执行证据应由同一份源文档关联起来,而不是顺序展示几份互相脱节的报告。
确定以下方向:
1. 移除正文之前整块展开的 Executable Knowledge。主阅读流首先出现作者的标题、介绍和内容;不把完整机器报告简单搬到正文后继续平铺。
2. 保留并改进现有 Structure 的叙述保真文档面,面向读者命名为“文档”。正文、表格、公式、函数和可执行步骤在原位置阅读,不生成一份模型改写的平行说明书。
3. 右侧“本文结构”负责章节与知识单元定位;选中知识片段后,在同一辅助栏展示它的解释、输入输出、来源和验证依据。源码标识、摘要与完整协议放在可展开的技术详情中。
4. 运行结果就地关联到对应步骤,明确运行实例与输入;完整日志、运行控制和源码放在正文后。看见一个数值时,读者必须能知道它是文档声明、计算结果还是历史快照。
5. 静态分析、程序运行、测试断言、来源关联和领域确认分别表达。不能用一个 `ok`、`pure` 或绿色“已验证”覆盖不同事实。
6. 功能渐进增强:无 JavaScript、静态导出、移动端、打印时仍能读完文档、定位知识和查看必要依据。普通短文不变成复杂仪表盘。
这些决策恢复 [view.md](view.md) 原有“文档面为主、Browse 与 Debug 分工”的方向,同时修订过度依赖引出线和默认展开技术面板的呈现方式。
## 2. 现状审计:为什么截图难读
### 2.1 可定位的实现依据
| 观察 | 当前代码 | 对阅读的影响 |
|---|---|---|
| 知识面板位于正文前 | [html.rs / page_file](../../src/view/html.rs) 的模板顺序为 notebook → knowledge → Structure → Execution → Source | 必须先越过辅助资料才能看到文档;模块越多越严重 |
| 所有制品一律展开 | [render.rs / render_knowledge_html](../../src/view/render.rs) 按文件筛选 artifacts,并逐项输出完整 `<dl>` | module/type/function 同等突出,容器元信息挤占知识内容 |
| Steps 脱离所属结构 | 同函数把当前文件所有 steps 放在单一 `<ol>` 中,展示 kind、label、完整目标 ID | 静态步骤容易被误读为实际执行顺序;调用/循环/正文引用混在一起 |
| 内部字段未经阅读转译 | URI、签名、effects、verification 拼接文本、完整 sha256 默认可见 | 读者仍不知道这项知识解决什么问题、怎样用、依据在哪里 |
| “Lock digest”名实不符 | 该字段实际显示 `artifact.hashes.artifact`;[mod.rs](../../src/view/mod.rs) 编译使用 `LockMode::Off` | 制品摘要被误读为已经锁定且通过复现检查 |
| 静态说明与运行脱节 | 每张卡固定输出 `Not executed by knowledge preview.`;实际 run capture 在另一条路径 | 即使页面有运行结果,也很难理解“未执行”到底指什么 |
| 分析失败静默消失 | `build_file_view` 对语义编译结果使用 `unwrap_or_default` | 无知识、分析失败、尚未分析在界面上都可能表现为空 |
| 标题与层级表达较弱 | `page_file` 标题取文件名;[document.rs / render_fun_heading](../../src/view/document.rs)统一用 h3 | 作者 frontmatter 标题未用于页标题,嵌套结构主要靠其它线索判断 |
| 知识组件缺少专用布局 | `knowledge-*` 在 HTML 中有类名,但 `html.rs` 没有与面板匹配的专用样式规则 | 大量使用默认列表/定义列表排版,空白多、关系弱,和正文主题缺少一致约束 |
| 新旧皮肤叠加 | `html.rs` 内基础 view CSS 与 `notebook_ui` 大块 notebook 主题共存 | 正文、注释、知识区的字号和密度不一致;不能只修一个卡片颜色 |
| 验收主要看元素存在 | [executable_knowledge.rs](../../tests/executable_knowledge.rs) 的 view 用例检查 step 类名、kind 和 `#stmt-` 链接 | 没检查正文优先、跳转目标存在、可读文案和实际布局 |
已有能力应保留:[document.rs](../../src/view/document.rs) 的叙述/表格保真、Occlusion 描述与实现分离、函数大纲、调用帧/循环帧选择、[annot.rs](../../src/view/annot.rs) 的真实执行标注。重新设计应基于这些能力,而不是退回 AST 卡片浏览器。
### 2.2 对截图的解释边界
截图可直接确认:机器字段先于正文、Steps 只有 `call print`、长 URI/摘要显著占位、英文状态串缺少解释,以及深色底上的孤立黑色短线。
黑色短线的具体来源尚未在浏览器中复现。代码中存在 annotation leader、布局重算和主题覆盖,可能需要检查,但本文件不把它们断言为唯一根因。实施时应使用用户截图对应页面复现,检查实际 DOM、computed style 和几何位置;不能用全局隐藏所有 SVG/边框来掩盖问题。
### 2.3 本轮实际复核
把 [public/features/01-phase-i-treewalk.mq.md](../../public/features/01-phase-i-treewalk.mq.md) 复制到临时目录,使用 debug 2.1.1 执行静态导出并检查生成 HTML:knowledge 确实在 structure 前,共 3 个 `knowledge-card`(含 Steps)和 2 个完整 sha256。该短文的核心只是介绍 tree-walk 流程并打印一句话,当前辅助内容明显过重。
另用隔离临时文件复核 `view output --no-exec`:嵌入的 `fs.write_text` 仍创建了临时标记文件。原因是 [output.rs / write_static](../../src/view/output.rs) 先调用会执行的 `build_file_view`,再在 `opts.no_exec` 分支清空结果。**这是已复现的执行/呈现不一致,必须修复,不能仅把标签改成“未运行”。** §9 给出新的构建边界。未执行线上浏览器像素比对,本文线框为目标设计。
## 3. 读者任务与设计成效
| 读者任务 | 默认应看到 | 按需展开 | 成功判据 |
|---|---|---|---|
| 理解这篇文档 | 作者标题、介绍、正文和核心表格/步骤 | 完整源码 | 不滚过机器报告就能开始阅读 |
| 看懂文档结构 | 章节、类/规则/函数的真实层级,当前位置 | 参数和局部步骤树 | 能判断一个步骤属于哪个知识单元 |
| 理解某项知识 | 描述、简洁公式/调用、条件、返回含义 | payload、契约、精确目标 | 能解释它做什么、需要什么、产生什么 |
| 判断结果是否可信 | 来源状态和所选运行的明确结果 | 测试、来源片段、版本和诊断 | 能区分“可以运行”和“事实成立” |
| 跟踪跨文档复用 | 友好目标名、所属文档、输入输出 | 依赖关系、完整标识 | 能到达定义并返回原阅读位置 |
| 检查某次运行 | 本次输入、选中调用/迭代、对应结果 | 日志、历史帧 | 不把不同运行的值混在一起 |
不要求所有读者理解 SymbolId、IR、hash 或 effect 协议。开发者仍能找到这些信息,但它们不再成为阅读的前置条件。
## 4. 页面信息架构
### 4.1 默认桌面布局
```text
┌ Marqdo 项目 / 文档路径 搜索 主题 ┐
├───────────┬───────────────────────────────┬────────────┤
│ 文件目录 │ Phase I — tree-walk interpreter│ 本文结构 │
│ │ Lex · parse · check … │ 介绍 │
│ 当前文件 │ [运行记录:尚未运行] [详情] │ main 入口 │
│ │ │ │
│ │ Milestone: Phase I … │ │
│ │ Pipeline: load → … → eval │ 选中后: │
│ │ │ 当前知识 │
│ │ main · 入口 │ 作用 │
│ │ 输出说明 print text=… [说明] │ 输入/返回 │
│ │ │ 来源/条件 │
│ │ ▸ 运行与结果 │ 检查/运行 │
│ │ ▸ 完整源码 │ 技术详情 ▸ │
└───────────┴───────────────────────────────┴────────────┘
```
布局是文件导航、主文档、一个辅助栏,不能增加第四条永久侧栏。右栏上部保留可收起的“本文结构”;用户选中片段后,下部显示“当前知识”。空间不足时以当前知识替换下部内容,并提供“返回目录”操作。打开/关闭详情不改变正文宽度,避免重排导致阅读位置跳动。
主文档的默认顺序:
1. 文档标题、已有 description、简短状态入口;title 缺失时退回文件名。
2. 源文档的正文、结构和轻量就地知识说明,保持作者顺序。
3. “运行与结果”:运行按钮、输入、所选运行结果、输出图形/日志;已有重要失败有就地入口。
4. “完整源码”及“文档技术信息”,默认折叠。
不在顶部强制生成内容摘要、全量函数清单、巨大状态矩阵或知识关系图。没有 description 时不调用 LLM 补写。结构大纲始终可达,正文不因折叠辅助栏而变成无结构的文章。
### 4.2 尺寸与响应式规则(设计目标)
| 可用宽度 | 布局 |
|---|---|
| ≥1280 CSS px | 文件栏约 220–260px;正文弹性;辅助栏约 280–320px;正文中文行长约 32–44 字 |
| 900–1279px | 文件栏可收起;正文优先,辅助栏可切换为有标题的侧抽屉 |
| <900px | 单列文档;“目录”“当前知识”作为明确按钮打开抽屉或块内 details |
| 320–390px 手机 | 标题、正文、状态不横向溢出;长表格/代码局部滚动,整页不左右拖动 |
| 打印 | 正文展开,必要来源/验证摘要转为节后附注;交互按钮和导航隐藏;技术原始字段按导出选项包含 |
在 1440×900、100% 缩放的短文验收样例中,首屏应包含至少一段正文和首个主要结构单元;状态头不得因每个 artifact 增长而把正文推出首屏。此约束不截断作者自己的长标题或介绍。
### 4.3 普通文档与复杂知识文档采用同一布局
- 普通说明页只有 main/print:显示原文与输出操作,技术区保留模块信息;不强制展示“1 项可执行知识”卡。
- 可复用函数库:目录列出函数;函数标题下出现紧凑签名和“说明”入口;即使无 main,也能正常阅读。
- 事实/规则文档:来源、条件与验证紧邻相应知识;来源问题不能藏进页尾。
- 教程/Notebook:保留源文档的代码单元与结果;全局单元运行条收进运行区域或显式工作模式,不能把所有文章永久变为 notebook 工具台。
- 大文档:目录按真实层级和顺序组织,可搜索;正文不因知识数量膨胀为另一份报告。
## 5. 文档与结构呈现规范
### 5.1 标题、类与函数层级
页标题优先来自解析后的 frontmatter `title`,其次使用合适的源文档标题,再回退文件名;不要自行用正则重解析 YAML。保留原文标题内容,不擅自把技术名称改成模型生成的名称。
“本文结构”同时服务阅读和程序定位,但明确区分:
- 作者章节按实际文档关系展示。
- 可执行的类/类型、函数、入口附轻量类型词,例如“规则”“函数”“入口”;类型词来自编译结果或已声明元数据,不由标题猜业务类型。
- 同一节点既是章节又是函数时只有一个目录项,旁边标类型,避免两棵树重复。
- 嵌套函数、分支、循环在对应父节点下展开;语义归属与 Markdown 可视层级分别保留,不把所有内容都扁平化为 h3。
- 普通段落引用不提升为函数;module 容器不自动成为一张与业务函数同权的卡。
DOM 标题使用连续、可访问的层级;实际语法的 `#`/`##` 层数在源码面保留。用户复制源码时取得原始合法语法,而非为了 HTML 标题级别改写过的内容。
### 5.2 可执行步骤:就地解释并保留上下文
| 编译器步骤 | 默认阅读文案 | 展开后 |
|---|---|---|
| observe | “读取:商品单价” | 集合、取元表达式、字段说明、当前调用下的值 |
| derive | “计算:商品小计” | 公式、输入来源、计算条件、当前结果 |
| call | 优先作者标签;无标签时“调用 商品小计” | 目标、所属文档、实参映射、返回和运行记录 |
| iterate | “逐项处理:订单商品” | 集合、循环体、迭代数、所选迭代 |
| narrate | 正文保留作者描述,附“知识引用”入口 | 定义与来源;不当作已执行步骤 |
| navigation | 标准文档链接 | 正常导航,不显示虚构的执行结果 |
| 空 payload / stub | 作者描述 + “待实现” | 缺失的实现和已有诊断,不能展示成功数值 |
名称来自当前节点的 label、声明说明、目标可读名,依次回退;没有业务描述时就显示“调用 print”,不得自动声称它是“验证知识”或“输出最终结论”。普通 print 在所属文档位置解释输出作用,放在“输出”类信息中,不作为高价值知识卡突出。
“步骤”列表只在当前知识详情中显示,标为“文档中的步骤”或“结构步骤”。静态序号不能暗示实际执行时序;实际轨迹另按运行事件呈现,分支和循环保留嵌套。
### 5.3 描述、实现与结果的三层关系
以 `**总价 = [计算订单小计](pricing.小计(数量, 单价))**` 为说明示意:
```text
计算订单小计 [说明]
总价 = pricing.小计(数量, 单价) ← 简短实现,次一级视觉
本次示例:数量 2,单价 30 → 60 ← 仅有匹配运行记录时出现
```
作者的上下文句、返回说明、单位和条件仍在原位。短公式/实现可次级显示,长 payload 默认折叠到详情;显式“展开实现”控制可对当前知识单元生效。不得把所有代码完全藏掉,使“代码即文档”退化成只有自然语言标签。
复制操作区分“复制说明”和“复制源码”;源码来自源 span,保留必要定界符、参数和 import 依赖提示。显示为漂亮文本的结果不能被复制成伪造的可执行代码。
### 5.4 表格、条件与关系
数据表按作者结构呈现,表头固定语义,单位与列说明常显;契约表按输入/返回/约束组织。显示层不能把 Marqdo 列向集合悄悄换成行向记录;需要另一种预览时明确标为预览,并能查看真实形状。
前提条件与失败分支不得因“简洁”隐藏。默认显示全部分支结构,所选运行只突出实际命中的分支,继续遵守 [调用帧与结构保真](view-frame-selection.md)。
跨文档关系默认用可读链接,例如“使用:标准税率 · tax.mq.md”,而非 `mq://…`。直接依赖与被引用者各列前几项并可展开;可选局部关系图放在详情层,不作为默认阅读画布。关系图必须有等价文字列表,并显示未知/动态关系,不能补画不存在的边。
## 6. 当前知识详情:回答问题,而非列出字段
### 6.1 内容顺序
```text
商品小计 函数
根据数量与单价计算商品金额。 ← 仅引用已有描述
输入 数量:整数;单价:金额 ← 类型/单位未知则明确未知
返回 金额
条件 数量非负 ← 仅当已声明且可定位
实现 数量 × 单价
来源 定价说明 / 第 2 节 [打开]
检查 契约未检查;测试未运行 [查看依据]
运行记录 示例 #2:2 × 30 → 60 [定位输出]
使用 … [查看定义]
▸ 技术详情:精确标识、完整签名、效应、摘要、诊断 JSON
```
此处“金额”“数量非负”等只用于解释布局,不宣称当前样例具有这些元数据。没有信息就省略非关键行或写“未声明”,不得推断成“无限制”“没有来源也可靠”。缺失影响可用性时常显;纯工具没有业务来源并不自动是错误。
### 6.2 当前字段的去向
| 当前字段 | 新的主要位置与文案 |
|---|---|
| Target / `mq://…` | 标题处可读定义链接;完整 ID 在技术详情,可复制 |
| Kind / callable | 标题旁简短类型词;module 信息进入文档技术信息 |
| Signature | 输入/返回紧凑表;完整规范签名可展开 |
| Effects | “涉及的操作”,说明文件读写、网络等;未知明确显示,非纯不等于失败 |
| Verification 长串 | 分项检查和证据表,见 §7 |
| Lock digest | 更名“制品摘要”,技术详情内显示;锁状态单独来自真实 lock report |
| Depends on | 可读目标列表,指向定义与引用位置;未分析不能写“无依赖” |
| Execution 固定句 | 匹配运行记录,或“尚无该知识的运行记录” |
| SourceRef / applicability | 当前遗漏的关键内容:放入“来源”和“适用条件” |
默认不铺完整 hash。技术详情可显示缩略摘要并提供全值/复制;缩略值不用于识别唯一性。没有读取锁报告时写“未检查锁定状态”,不能把拥有摘要显示成“已锁定”。
### 6.3 交互、跳转与返回
1. 点击正文的“说明”或目录知识项,选中同一 `node_id`;正文轻量高亮,右栏同步。键盘和触屏具有等价入口,不依赖 hover。
2. 跳转到定义时保留来源文件、锚点、滚动位置和所选运行;返回恢复阅读位置。
3. 文件、符号与语句不能只靠显示名称匹配。同名函数的详情显示所在文档和父结构。
4. 默认不自动抢焦点、不因滚动不停替换用户正在阅读的详情。滚动只更新目录当前位置;点击选择才改变详情。
5. 手机抽屉有标题、关闭、返回焦点和滚动管理;无 JS 时使用正文附近的原生 details 或页尾知识附注锚点。
6. 当前 URI 不在导出范围内时显示“定义未包含在此次导出”,提供可读路径和复制引用;禁止输出必然失效的 `mq://` 或 live `/file` 链接。
## 7. 状态设计:读者必须知道什么被证明了
### 7.1 分离三个状态来源
| 状态来源 | 可以说明 | 不能说明 |
|---|---|---|
| 编译/静态分析 | 结构解析、目标绑定、契约检查结果、已建模效应 | 程序已运行、答案正确、资料真实 |
| 运行记录 | 指定输入、环境、源码版本下的执行与输出 | 覆盖所有输入、测试通过、来源可信 |
| 证据/验证记录 | 哪个断言/测试/来源核验通过,何时失效 | 未执行或未核验的其它部分也可靠 |
顶部仅给紧凑事实,例如“静态分析完成 · 尚无运行记录”,或“有 1 项来源问题 · 查看”。普通 unknown/unchecked 不应制造全页红色警报;与当前结论直接相关的失败、过期、未解析必须就地提示且可定位。
### 7.2 分项文案映射
| 机器状态 | 阅读文案 |
|---|---|
| parse=passed | 文档结构可解析 |
| resolve=passed | 此项检查报告目标已解析;覆盖范围见详情 |
| contract=unchecked | 契约尚未检查 |
| execution=not_run | 尚无执行记录 |
| tests=unknown | 尚无测试记录 |
| evidence=sourced | 已关联来源,内容尚未核验 |
| evidence=unverified | 来源内容尚未核验;结合来源列表判断是否已关联 |
| missing_source / expired | 来源缺失 / 已过适用期 |
| domain=unreviewed | 尚无领域审阅记录 |
| effects=pure | 静态分析未发现已建模的外部操作;展开可看范围 |
| effects=unknown | 涉及的操作尚不能完全确定 |
| 无对应字段 | 未提供该项检查结果 |
分项取值不能自动升级成综合“可信”。只有宿主选定的政策实际给出聚合结论,才显示“满足 ×× 政策”,同时附政策名称、版本与证据;业务条件还须明确展示。
### 7.3 结果来源与失效
每个运行值绑定 `run_id + source_digest + node_id + call_id + loop/iteration` 中适用的字段,展示本次输入或简短上下文。无节点映射时只展示整次运行输出,不硬塞到某个函数旁边。
静态导出有快照时标“导出快照”,附生成时间/输入;读者切换调用帧是在看历史结果,不叫“重新计算”。源码、依赖或来源与记录不匹配时标“历史结果,版本已变化”,不继续用成功样式绑定到新正文。
正文里的字面量可以显示为“文档声明值”;解释器实际执行得到的值才叫“运行结果”。没有值、返回 None、stdout 为空、尚未运行、执行失败必须分开,不能统一成 `(no stdout)`。
### 7.4 空态与错误态
| 情况 | 处理 |
|---|---|
| 没有可识别知识单元 | 正常显示文档,不插空知识面板 |
| 语义分析失败 | 保留可读正文/源码,显示“知识关系暂不可用”及可定位诊断 |
| 局部未解析 | 仅对应片段显示问题,保留其它已知结果 |
| 无运行或 no-exec | 运行区说明原因,使用中性状态,无绿色运行成功标记 |
| 运行失败 | 错误摘要定位到源片段;日志在运行区,静态知识仍可读 |
| 证据过期/冲突 | 相关知识常显问题、来源与影响;不静默选择一个结论 |
| 分析被截断/超过扫描范围 | 显示范围和未覆盖项;“未发现”不能替代“没有” |
## 8. 视觉、密度与可访问性
### 8.1 排版与主题
正文建议 16–18px、行高约 1.65;辅助说明 13–14px、行高约 1.5;代码使用等宽字体,全文不因进入 notebook 主题缩为密集工具面板。主次依赖字号、间距和位置共同表达,不能仅靠颜色。
使用现有系统字体和主题机制,建立统一的 view tokens:正文/辅助文字、背景、细分隔、焦点、成功/警告/错误。知识组件只依赖 tokens,不硬编码黑色线条或白底。支持明暗主题,首次尊重系统/显式设置,不为这次改版再写第三套皮肤。
表格与长公式允许局部滚动;ID、路径在详情中可换行;主文无整页水平滚动。重要来源和适用条件不使用极浅灰隐藏。对比度验收目标:普通文字至少 4.5:1,大字和必要非文本边界至少 3:1;这些是实现验收目标,尚非本轮测量结果。
### 8.2 注释和连线
默认使用紧邻内容的短结果行或有标签的注释块,优先通过“同一节点名 + 明确位置”关联。长 L-leader 不再是默认必需元素;复杂节点可保留短连线,必须满足端点存在、在同一块内、不交叉、不覆盖文字。
当目标折叠、帧过滤、元素隐藏或几何测量失败时,不绘制连线。主题/字体/容器宽度变化后只重算当前可见块;采用可取消的局部布局更新,不全页不断测量。窄屏、打印、reduced-motion 下直接使用有编号的注释。截图中的孤立线条归入专门视觉回归场景。
### 8.3 键盘、屏幕阅读器与退化
- 目录用 nav,正文用 main/article,详情用有名字的 aside/section;标题层级连续。
- 展开按钮有 `aria-expanded/controls`;选中状态、失败和待验证都有文字,不依赖颜色或图标。
- 深链接滚动有 `scroll-margin-top`,聚焦目标不被固定工具条遮住;关闭详情后焦点回到触发点。
- 不使用只有鼠标悬停才能看到的来源、代码或错误。大表格有标题与表头关系,日志可复制。
- 无 JS 时正文、目录锚点、来源链接、原生 details 和静态结果仍工作;只失去实时联动与运行操作。
- 选择帧不隐藏源结构;隐藏实现也不能删除文档含义和必需条件。
## 9. 技术设计与数据契约
### 9.1 从预拼 HTML 改为可关联的展示模型
当前 `FileViewModel.knowledge_html` 是独立 HTML 字符串,难以与正文、trace、诊断同步。建议新增结构化 `KnowledgePresentation`,在 Rust 端形成同一份模型,由正文、目录、详情共同消费。兼容阶段可保留旧字段,但不让它继续成为唯一知识接口。
```text
ViewDocument
document_id, source_digest, semantic_generation, title, description
blocks[] 保真正文结构及 source span
outline[] 标题/知识单元父子关系
knowledge_nodes[] 对应 artifact/ref/step,不复制语义解释器
diagnostics[] 范围、严重性、可读说明、定位
execution_state 明确未运行/运行中/成功/失败/快照
run_records[] 与文档版本相匹配的证据
KnowledgeNode
node_id, artifact_id?, symbol_id?, ref_id?, step_id?
owner_id?, source_span, display_name, authored_description?
kind, signature?, payload?, dependencies[], provenance[]
applicability?, verification[], effects, coverage
execution_refs[]
```
这些字段为建议契约,未承诺当前 IR 已提供所有信息。语义事实来自 `SemanticProject`,文档叙述来自解析后的源结构,执行事实来自 capture;缺少关系时展示 unknown,不让 UI 用名称模糊匹配或调用模型编造。
### 9.2 数据流
```mermaid
flowchart LR
S[源文档与项目边界] --> P[解析与语义分析]
P --> B[正文块与结构]
P --> K[知识节点与诊断]
R[显式运行或匹配的历史快照] --> T[执行记录]
B --> V[统一展示模型]
K --> V
T --> V
V --> D[正文与就地说明]
V --> O[目录与当前知识]
V --> E[运行区域与技术详情]
```
知识模型不通过“render HTML → 再抓取文本”生成。页面分析失败不可用空字符串吞掉,应保留有状态的结果;部分成功与整体失败分开。
### 9.3 源位置、稳定身份与锚点
目前 step 跳转用 `#stmt-{line}`,函数用 `#fn-{line}`。一行多个表达式、正文段落合并、同名函数、源码插行都会使单纯行号不够。
新增内部节点锚点注册表,将文档块、函数、语义 step/ref 与真实 DOM id 映射;使用 artifact/node 身份和源 span 生成页内唯一 ID,不把未经编码的 URI 当 DOM id。当前编译器没有稳定 SyntaxNodeId 的地方,退化为“源码版本 + span”,明确跨版本不可保证稳定;不能只把行号哈希一下就宣称稳定身份。
兼容现有 `#structure`、`#fn-N`、`#stmt-N` 链接,保留别名或定位映射;所有生成链接都验目标存在。跨文件 href 复用 [html.rs 的 LinkMode/href_file](../../src/view/html.rs),静态导出保持相对路径;路径展示解码与 URL 安全编码分离。
### 9.4 分离分析与执行,修正 no-exec
将当前 `build_file_view` 拆成可组合路径(名称为建议):
1. `analyze_document`:读取、解析、语义检查、生成静态展示数据,不执行目标程序。
2. `capture_execution`:只有执行策略明确允许时调用 run/cell runtime,返回真实状态与源版本。
3. `assemble_view`:关联正文、语义和匹配的结果,生成同一个展示模型。
`--no-exec` 必须在第 2 步之前分支,不能先跑后清空;snapshot 模式使用匹配快照,不为了构造 UI 又运行一次。Live 现有自动执行兼容行为在首轮不静默改变,必须通过显式 execution policy 传入并如实标注;若后续将 live 默认改为阅读时不执行,作为独立 CLI 行为变更发布和迁移。点击详情、查看来源、展开关系等阅读操作绝不能触发执行。
知识详情不要求通过运行得出静态信息。实现参数预览/试跑时,使用既有受控执行路径,不因“pure”字样绕过宿主能力边界。本文不新增一套求值器或权限系统。
### 9.5 Live 更新一致性
当前 SSE 会替换 structure_html/bindings_html/trace_json,而知识面板来自另一次静态编译,容易新旧混用。建议更新包包含文档摘要、语义代、run_id 和变更节点;前端仅合并兼容版本的数据。
运行写回导致源码变化时,重新分析后一次更新相互关联的正文、目录、知识与运行映射。原选中节点仍存在则保留选择/焦点/滚动;已消失则明确提示,不能悄悄指向同名节点。旧请求返回晚于新请求时按版本丢弃,不覆盖较新阅读状态。
### 9.6 性能与导出体积
避免每个页面重复编译整个项目。一次静态导出共享同一项目语义结果,逐页投影;live 按项目源指纹、编译器版本、配置和适用性时钟缓存,读取使用一致的语义代。来源/有效期变化必须使相关状态失效,不能无限缓存 sourced。
正文服务端生成,不等待 JS 初始化或全部知识图完成才出现。默认只嵌入当前文档必要知识,深层依赖按需取;静态导出则包含保证离线可用的局部数据与明确范围。大量结果采用折叠/分页,但不能让屏幕阅读器和查找失去正文。
性能验收目标:100 个知识单元的本地选择/展开交互 p95 ≤100ms;1000 单元目录可搜索而不阻塞正文滚动;导出项目的语义编译次数不随页面数线性重复。记录硬件、样例和体积,目标未达时先优化数据重复和布局测量,不以截断关键来源达标。
## 10. 实施文件与兼容策略
| 位置 | 建议变更 |
|---|---|
| [src/view/render.rs](../../src/view/render.rs) | 提取知识展示模型;替换全量 dl 面板;关联步骤归属、友好名称与诊断 |
| [src/view/document.rs](../../src/view/document.rs) | 源块/知识节点映射、正文就地入口、层级标题、可复制原始 span |
| [src/view/html.rs](../../src/view/html.rs) | 正文优先布局、辅助栏、详情/目录交互、状态组件、统一 tokens;保留 LinkMode |
| [src/view/mod.rs](../../src/view/mod.rs) | 分离分析/执行、保留诊断、组装统一模型、项目分析缓存 |
| [src/view/output.rs](../../src/view/output.rs) | 提前应用 no-exec/snapshot 策略、共享项目分析、静态详情与相对跳转 |
| [src/view/annot.rs](../../src/view/annot.rs) | 运行标注与节点/帧/版本关联,减少重复输出;缺映射不伪绑定 |
| [src/view/debug_page.rs](../../src/view/debug_page.rs) | 仅回归检查共享组件;不把阅读布局强加给 debug |
| [tests/executable_knowledge.rs](../../tests/executable_knowledge.rs)、view 单测 | 从字符串存在升级到顺序、锚点、状态和执行边界断言 |
| 文档与 public 示例 | 更新旧 View 布局说明、截图和行为描述,区分历史默认与新设计 |
默认展示不要求作者补特殊 frontmatter;title/description、函数说明、契约和来源已有时直接受益。尚无信息的旧文档保真显示,并在详情中如实缺省。
与现有文档的关系:保留 [view-document-annotations](view-document-annotations.md) 的叙述主导和真实结果,修订“长 L-leader 为默认”;保留 [view-frame-selection](view-frame-selection.md) 的源码常显与帧隔离;[view-markup-surface](view-markup-surface.md) 的历史 Classic 例子需按当前默认语法同步,不能在新 UI 继续教授旧取元。外联/WASM 交互沿既有独立路线发展,不作为完成本次阅读改版的前置。
## 11. 分阶段交付
### V0:先纠正顺序、误导状态和执行边界
正文提前;完整知识报告收进明确的辅助入口,module/type 容器默认不铺卡;“Lock digest”改为准确的摘要标签;状态不再共用一个 ok。修复 no-exec 先执行问题,分析错误可见。暂不等待完整节点模型,就能显著改善截图场景。
V0 不算最终完成:仅把面板搬到后面/折叠,仍未解决正文与知识的关联。
### V1:完成阅读与结构理解的主闭环
统一展示模型、标题/目录层级、就地说明、当前知识详情、友好定义跳转与返回。完成函数、计算、来源、空态与基本运行结果的正负例;live/static 共用。
### V2:贯通运行、来源和跨文档关系
匹配运行实例与版本、调用/循环帧、来源定位/失效、局部依赖关系、SSE 原子更新。上游证据能力尚不完整的地方明确显示未知,不能以 UI 补出“验证通过”。
### V3:移动端、离线和规模验收
完成键盘/读屏、无 JS、打印、暗色/浅色、100/1000 单元性能、视觉回归与读者测试。发布前同步 public 示例与说明,保留旧锚点兼容。
## 12. 验收矩阵
### 12.1 必测文档
| 样例 | 必须验证 |
|---|---|
| 截图对应 Phase I 页 | 正文先出现;无 full URI/hash 瀑布;print 在所属正文解释;无孤立线条 |
| 纯叙述/少量 Markdown 页 | 阅读无知识空卡、无误导运行徽章 |
| 单个纯函数,无 main | 参数/返回与调用方式清楚,不因无入口标全文失败 |
| 订单定价、多文档 import | 小计/税率/总额归属和依赖可追踪;输入和结果可对应 |
| 带来源的事实与过期/缺失来源 | sourced 不显示已证实;问题在对应知识旁可见 |
| 同名函数、多次调用和循环分支 | 定义唯一;切换帧只改结果和高亮,不隐藏结构 |
| 空 payload、动态调用、未解析引用 | 待实现/动态/未解析准确可辨,不能展示虚构结果 |
| 一行多个链接、嵌套表达式、中英文/长路径 | span 对应、锚点唯一、文本不丢失、不水平溢出 |
| 运行失败、分析失败、快照过期 | 三种情况分开,仍能读到正文与具体诊断 |
| 外联单元、变量大表、长日志 | 单层主体与对应结果,不重复三份输出;局部滚动 |
### 12.2 自动化判据
1. DOM 中文档主体先于全量知识技术详情,标题来自既有元数据;短文没有隐藏正文的默认展开报告。
2. 每个知识/目录链接都能定位真实节点;一行多节点和同名跨模块不冲突;live/static 路径均有效。
3. 验证、运行、来源状态按固定真值表渲染;无证据时绝不输出综合已验证。
4. no-exec 用隔离目录的副作用计数测试证明没有执行;snapshot 不重跑;展开详情也不执行。
5. 帧选择和 SSE 更新保留正文结构、选中身份与焦点,拒绝过期结果包。
6. 明暗主题/320、390、1024、1440 宽度/200% 缩放下无遮挡、截断关键条件和整页横向溢出;孤立 leader 数为零。
7. 无 JS、file 静态打开、打印预览都保留正文、定义/来源导航和必要证据说明。
8. 输出中的作者内容、label、URI/属性与嵌入 JSON 按原上下文转义;资料中的 HTML/脚本不能因为新详情组件被直接执行。
字符串断言只能覆盖结构,不能替代浏览器布局验收;需截图基线和真实键盘交互测试。可复用现有测试基础,避免测试只镜像组件实现。
### 12.3 读者任务测试
建议用至少 5 位未参与实现的读者,分别完成三个任务,并与当前页面对照:
- 在 30 秒内说清文档目的并找到主要规则/函数。
- 在 60 秒内找到某个结果的输入、定义和原始来源。
- 正确区分“来源已关联但未核验”“本次运行成功”“未运行/历史结果”,不得误认为都已验证。
目标为至少 4/5 完成前两项,第三项无误导性判断;小样本仅作为可用性门槛,不声称统计显著。记录失败位置并修正信息架构,不能只问“是否好看”。
## 13. 完成定义与本次交付边界
完成的 view 应让读者先读懂文档,再自然看到其中的知识与执行结构;需要深入时能沿着一个具体片段追到实现、输入、结果和证据。全量技术字段仍可查,但不要求读者先理解编译器才能读文档。
本次只提交设计文档与索引,不修改渲染实现。实证包括用户截图、当前模板/渲染路径、静态 HTML 顺序检查和临时 no-exec 反例;布局尺寸、交互、性能和读者任务结果均为待实施的验收目标。
@@ -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` 自动推广为本路线的完成。
@@ -0,0 +1,250 @@
# Marqdo 支撑求道知识沉淀与文档编译的框架缺口
| 项目 | 基线 |
|---|---|
| 日期 | 2026-10-24 |
| 框架源码 | `b8a4ddd`,Cargo 声明 2.1.1 |
| 消费者源码 | 工作区 qdagent,`7f8f19d` |
| 文档性质 | 当前源码复核、实测反例和增量建议;不重开已完成的 S0–S6 工作 |
| 配套文档 | [求道产品侧缺口](../../../qdagent/doc/gaps/03-knowledge-ingestion-and-sedimentation-2026-10-24.md) |
| 设计依据 | [文档原生开发指导](../design/document-native-development-guide.md)、[既有缺口路线](executable-knowledge-gaps-2026-10-23.md) |
## 1. 核心判断
Marqdo 已具备让求道采用文档原生知识的主要语言和执行基础。求道尚未接入的能力,不能统称为“框架不支持”。本轮框架侧优先工作是:**让生成知识的语言指导可信,让来源和验证真正约束发布与复用,让新语义制品进入默认 Agent 链路,并提供文档导入所需的通用适配接口。**
`knowledge` 编译的是已有源码和声明,不是把任意 PDF/DOCX 自动变成正确知识的转换器。上传、抽取、模型建模、语义编译、验证、发布是不同阶段。语义编译器保证程序和依赖的确定性;来源支撑、业务适用性以及领域审阅需要明确证据,不能由成功退出或 LLM 自述推导。
现有 [2026-10-23 路线](executable-knowledge-gaps-2026-10-23.md)的审计基线较早,之后已有多次实现提交。本文件按当前源码重新划分:已实现、有限子集、仍有断点;不照抄旧文档中的“无正文引用”“未知效应全为 pure”“两图互相覆盖”等历史判断。
## 2. 当前可直接复用的能力
| 能力 | 当前证据 | 给求道的边界说明 |
|---|---|---|
| 默认 Occlusion、`access`、显式遍历 | [核心表面](../design/core-surface.md)、[基线 01–04](../../tests/executable_knowledge/README.md) | 求道须迁移旧取元;无需增加新语法 |
| 函数、契约、表格、import、关联函数 | `src/parse/`、[check.rs](../../src/check.rs)、[sema/bind.rs](../../src/sema/bind.rs) | 支持编写可复用知识;不是所有知识都要塞进 main 或建类 |
| 项目身份、语义制品、绑定调用 | [project](../../src/project/mod.rs)、[symbols](../../src/sema/symbols.rs)、[IR](../../src/sema/ir.rs) | 已有 SymbolId/ArtifactId、BoundCall/DynamicCall;消费方不另造执行身份 |
| 语义图与检索图隔离 | [knowledge/compile.rs](../../src/knowledge/compile.rs) | 权威语义 `graph/` 与检索 `ekc/graph/` 已分开,旧覆盖问题不再作为未实现项 |
| 知识步骤、正文引用、view | `collect_named_steps`、NarrativeRef、现有集成测试 | 已含 observe/derive/iterate/call/narrate/navigation 子集;正文引用保持惰性 |
| 来源与适用期初版 | [provenance.rs](../../src/sema/provenance.rs) | 已解析 `sources` block list、region、valid_until;sourced 不等于事实已经验证 |
| 精确绑定与本地执行 | [mlsp.rs](../../src/mlsp.rs) 的 artifact.find/inspect/bind/execute | 已有摘要及 SymbolId 检查、按源行定位函数、pure 效应门槛;剩余失效问题见 M02/M03 |
| 局部修改 | MLSP artifact.patch / artifact.extract_pure | 已有摘要保护、措辞修改守卫、纯片段提取;不应要求模型每次重写整库 |
| 整代语义投影、锁、影响 | `write_semantic_projections`、[lock.rs](../../src/sema/lock.rs) | 已有 generations/CURRENT 与多类摘要;覆盖边界及实测失败见 M02/M06 |
| Agent 工作簿、技能、沙箱 | [ext/ai/agent](../../ext/ai/agent.mq.md)、[plugins/agent](../../plugins/agent/src/lib.rs) | 可复用 Runtime、CoW、工具协议和诊断修复;求道不另建 Agent loop |
| 文件上传/存储 | [storage.mq.md](../../ext/data/storage.mq.md)、[routes_media.go](../../plugins/web/internal/httpx/routes_media.go) | 已有上传路由、类型/大小验证和保存;不等于文档知识转换已存在 |
本轮离线执行 `cargo test --offline --locked --test executable_knowledge`:**25 passed / 1 failed / 0 ignored**。通过项包括双后端基线、绑定复用、正文引用、来源状态、局部补丁、100 单元和 CLI 冒烟。失败项为 `s5_closure_digest_moves_with_dependency`,单独重跑仍失败。存在大量有效基础,也存在需要先处理的失效缺口。
## 3. 框架缺口与可验收交付
### M01 · P1:上传底座尚未形成文档提取与来源映射协议
**现状。** Web 插件已注册 `web_upload_validate/save/app_upload`,`handleUpload` 接收 multipart 并存储字节。本轮在 `src/`、`plugins/`、`ext/` 的搜索未找到可供求道直接调用的 PDF/DOCX/OCR → 标准化正文 → 页段来源映射的完整链路。不要把 HTTP 文件保存或 `knowledge compile` 命令包装成已有文档转换器。
**建议。** 在扩展/插件层定义通用 `DocumentSource → ExtractedDocument` 协议,字段至少包括原件 URI/摘要、格式、提取器版本、段落/表格/页码定位、可提取文本、缺失部分、置信度及诊断。先支持 text/Markdown;PDF/DOCX/OCR 可通过独立插件或受控外部提取器接入。格式解析留在扩展,语言核心不引入 OCR 或模型业务。
知识生成由求道选模式、检索既有知识、调用模型并提供 patch;框架提供 compile/diagnostics/sandbox,而不是默默替作者推断领域真相。转换的外部程序必须服从宿主权限和资源边界。
**现有上传实现需补强的具体点。** `handleUpload` 先 `ParseMultipartForm(32 << 20)`、`io.ReadAll`,再按完整字节数做 Validate;32 MiB 是 multipart 内存阈值,不是请求总量硬限。应在解析/读取前限制请求与文件字节数,采用受限流式读取,并测试清理临时文件与失败路径。已有类型/路径验证应复用,不能将此描述为“没有任何上传校验”。
**验收。** 对文本、表格、跨页、坏编码、空文档、密码 PDF、扫描件、超限文件分别返回成功/部分/失败;每条抽取事实都可定位回原件;上传 `.mq.md` 不自动执行;相同文件及提取器版本输出可比较,重试不产生不同身份。
**责任。** Marqdo 提供提取与存储适配规范;求道负责上传界面、任务进度、知识库选择、发布政策与业务模型。
### M02 · P0:来源与依赖变化未完整进入摘要、锁与执行失效
**来源反例(实测)。** 2.1.1 下给函数声明 `sources: source.md#missing-anchor`,实际文件存在但锚点不存在,仍得 `evidence=sourced`;business bind 成功。修改 source.md 后 SourceRef.content_digest 变化,artifact.hashes.artifact 不变;旧 handle 继续执行。删除 source.md 后,旧 business handle 仍执行并返回原值。
**源码原因与边界。** [provenance.resolve_provenance](../../src/sema/provenance.rs)将 `#anchor` 存为 locator,但没有校验锚点;对来源文件计算哈希后,[IR artifact_for_function](../../src/sema/ir.rs)仍用 `digest(contract_summary(&contract))` 构造 evidence 摘要,没有包含来源内容和适用条件。`artifact.execute` 重编译并比较自身 artifact 摘要,但不重验 handle.policy 对应的证据状态。来源改变、来源删除、时间到期可以不改变函数实现,因此自身摘要检查不足。
**依赖反例(实测)。** [现有集成测试](../../tests/executable_knowledge.rs) `s5_closure_digest_moves_with_dependency` 中 `main` 调用 `d.rate()`,仅将被依赖函数返回值从 0.13 改为 0.14;测试读取到的 main closure 摘要未变。已重复验证。这里只确认该夹具失败:需要区分符号/模块同名选择、依赖边和闭包算法各自责任,不据此直接断言所有函数闭包都失效。
**其他源码缺口。** bind/execute 传递的是自身 `hashes.artifact`,没有把已有 `hashes.closure` 纳入句柄复核。`lock.impact` 从制品定义文件和依赖/正文边找反向影响,未把 `provenance` 的外部 corpus URI 纳入来源反向边。
**交付。**
1. evidence 摘要包含规范化来源 URI、定位、内容摘要、提取器/验证版本及适用性;锚点不存在返回不同于文件缺失的诊断。读取错误不能以空文件摘要冒充成功。
2. 修复上述闭包失败,并明确 type/module/function 的身份与测试选择。依赖递归/环用确定的 SCC 或等价闭包摘要规则;无关文件增删不应导致任意漂移。
3. 句柄记录并复核所需的依赖闭包、证据、政策及有效期;execute 重验 business/pure 等政策,不只相信 bind 时的状态。文件变化与时间变化都能使句柄失效。
4. 将 corpus → artifact → caller/answer 的影响关系纳入同一编译结果,来源改动能查询受影响对象;报告接口、实现、证据、依赖分别发生了什么变化。
**验收。** 仅修改来源、删来源、改锚点、时间越过有效期、改直接/传递依赖都拒绝不再有效的句柄;原有测试恢复通过。不得为让测试变绿删除断言或改成只检查命令成功。普通无业务来源要求的纯函数仍可按相应政策执行。
### M03 · P0:验证 API 尚不是可发布知识的完整判据
**现状。** `VerificationRecord` 已分 parse/resolve/contract/execution/tests/evidence/domain,但 `semantic_artifact` 的默认值仍包括 `contract=unchecked`、`execution=not_run`、`tests=unknown`、`domain=unreviewed`、`lifecycle=draft`。MLSP `artifact.verify` 主要返回编译记录并附 policy,没有实际执行对应测试或回写证据。不能把它宣传为已经验证业务事实。
`artifact.bind(policy=business)` 接受 sourced/verified,尚未检查 region 与本次输入、单位、前提、输入域等;`provenance` 用日期字符串比较有效期,没有完整日期格式校验。当前“business”至多表示来源已关联且未被判过期,不等于适用性或事实成立。unknown policy 字符串也未通过枚举校验形成明确拒绝。
`knowledge verify` 检查的是旧 EKC 结构一致性;`conflicts/stale` 是报告命令,`duplicate` 的默认行为也是报告。它们都有价值,但消费方不能从退出码 0 得出“候选可晋升”。求道正存在这种误用。
**交付。** 给调用方稳定的验证结果结构:验证对象/摘要、所选政策、每个检查的 passed/failed/unknown/skipped、证据记录、阻断原因、是否允许绑定或发布。测试运行器生成执行/断言事实;来源存在、引文一致、计算正确、领域结论分别报告。政策和结果字段应有版本化 schema,未知政策拒绝。
保留报告命令兼容性,提供清晰的机器裁决入口或明确 fail 选项;不要悄悄改变已有 CLI 的退出语义。发布政策可渐进:纯工具先证明程序行为,业务事实额外要求来源与适用条件,领域审阅按场景要求;不为所有函数强加人工审批。
**验收。** `sandbox failed`、模型声称“passed”、空证据、无效日期、地区不符、输入越界、测试未运行均不能被标成对应级别的 verified;缺证据与执行失败不同;实际通过的记录绑定内容摘要,修改后自动失效。
### M04 · P1:新语义复用协议尚未进入默认 Agent 学习与执行闭环
**现状。** [plugins/agent/eng.rs](../../plugins/agent/src/eng.rs) 的 `eng_reuse`、[knowledge/reuse.rs](../../src/knowledge/reuse.rs) 已输出 `discovery_only`、`bind_required`、`bind_targets`。这是真实进展,不再列为完全缺失。
但 [ext/ai/agent.mq.md](../../ext/ai/agent.mq.md) 的默认 `run` 仍以 route/resolve、agent-kb workbook、plan 为主;EFI 分支主要检查 create_allowed,未在该编排中找到 artifact.bind/execute 的完整消费。`run verify=True` 依据 `status==ok` 拼接 `verification="status: passed"`;随后可 maybe_learn/promote,并非调用 M03 所需的验证器。求道 BUILD 开启 `learn=True/promote=True` 后才做自己的 docgate,因此两层发布时序有冲突风险。
`build_step_context` 的 CALL 白名单只有名字协议;parent CALL 支持 ARGS 的能力与 step 工具路径不同。求道若要调用精确制品与输入,需要正式适配,不能在提示词中虚构已可调用的工具。
**交付。** 提供现有 Runtime 内的适配步骤:discover → inspect → bind → execute → record。执行工具使用宿主选择的 project/KB/policy,LLM 只提交候选及输入。REUSE 只有在绑定执行成功且有 trace 后计为实际复用;ADAPT 用现有 patch/extract 形成可审阅修改;CREATE 保留检索范围与原因。
提供产品可接入的发布前验证钩子或 candidate-only 模式:产品门禁失败时框架也不能先把技能标为可复用。知识文件、技能、episode 可以保留不同存储职责,但都关联同一版本化 artifact/evidence;不要新增另一套知识语义。
**验收。** 用真实 `agent.run` 编排和确定性假模型/工具响应验证,而不只直调 MLSP:已有知识被调用、无同义实现新增;错误来源/错输入被拒绝;验证失败无 promote;trace 对应符号、摘要、输入与输出。不得将 n-gram 高分或字符串 REUSE 当作成功。
### M05 · P0/P1:提供给模型的语言 Skill 与当前语法冲突
**源码事实。** [skills/marqdo/SKILL.md](../../skills/marqdo/SKILL.md) 前部 Hard rules 2/4 和 v0.2 表仍写“粗体是返回”、斜体是语句,旧 `[key](map)` 取元也仍在前部。后面虽有 v2.1 默认 Occlusion 段落,不能消除同一提示包的冲突。
[host/agent_rt.rs](../../src/host/agent_rt.rs) 的 `load_marqdo_skill/read_skill_pack` 加载 Skill/reference/examples;[agent.skill_brief](../../ext/ai/agent.mq.md) 默认只取前 1200 字符/80 行,deep 预算 4000 字符。因此旧规则可能优先进入窗口,新的说明反而被截掉。实际读取哪个包受 MARQDO_SKILL 和搜索路径影响,部署须记录真实来源,不能假定总在读工作区文件。
**交付。** 从现行核心表面、解析器与金样例维护一份版本化语法卡片,最前面即当前含义:`**…**` 代码、`*…*` 返回、`[描述](payload)`、`access`、显式 import/遍历、正文惰性。旧语法迁入独立迁移卡片,不继续与默认规则并列。模型可按需取契约、来源、表格、类/函数等卡片;语言核心规则和权限边界不可被预算截掉。
使用已有 MLSP syntax/schema/validate/repair 能力,但明确 validate 的范围:当前主要是契约/标签检查,不等于完整事实、所有变量/调用和业务验证。诊断附 span、相关源码、目标语法版本及建议修复范围;优先局部 patch,避免整篇重生成。
**验收。** `dump_step_context` 和 plan 上下文的脱敏快照中没有冲突规则;基础/deep 预算均保留必需语法。卡片中可执行示例在当前 CLI 双后端通过;同一批含旧取元、错误返回、表格几何误用、缺 import 的负例给明确诊断。记录实际 skill path/hash、CLI/Ext/schema/prompt 版本。
### M06 · P1:整代发布已存在,但扫描范围与消费者一致性仍需约束
**现状。** [IR](../../src/sema/ir.rs)已将语义投影写 generations,再原子替换 CURRENT;遵循 `semantic_generation_dir` 的读者可获得完整语义代。但随后还写根目录兼容镜像,[knowledge.compile](../../src/knowledge/compile.rs)另写 engineering.yaml / ekc 等检索投影;不能把语义代原子性推广为“所有消费者、所有索引都属于同一代”。并发构建共用 CURRENT.tmp、.tmp-sema-publish,需明确串行化或独占发布规则。
[project 扫描器](../../src/project/mod.rs)与 [EKC extract](../../src/knowledge/extract.rs)的排除集不同,后者遍历子目录时排除 data/docker,前者不排除 data。求道有多个原文、候选和运行目录,导入 `.mq.md` 后可能在不同消费者里出现不同可见性。已有 .marqdo 排除、深度/文件大小/数量限制值得保留,但尚不能替代显式源范围和信任范围。
**交付。** 项目配置声明 authored sources、corpus、draft/generated 的范围;语义、EKC、Agent/view 使用同一选择规则。发布 manifest 关联语义代、检索代、源码/证据摘要和 schema;消费者拒绝混代并能回退到旧完整代。多库使用独立项目身份,索引聚合不扩大执行文件范围。
**验收。** 暂存上传代码不会进入活动能力;data/ 路径不会因消费者不同而忽隐忽现;并发编译/失败注入期间读者只看到一套可用版本;旧索引可重建,源文档不受损。迁移期明确旧 graph 路径兼容期限。
### M07 · P1:来源粒度和知识类型不足以覆盖文档沉淀
**现状。** 来源主要来自模块 frontmatter,容易将一整篇资料附给该文件所有函数;SourceRef 有 uri/locator/digest,但缺少标准的“具体断言 → 原文片段/表格单元/页码 → 提取版本”关联。普通 EKC `KnowledgeKind` 有 Fact/Decision/Constraint 等,而语义 artifact 主要是 module/type/function;旧 `.md` Fact 的存在不等于可调用事实函数。作者写来源 inline list 时当前解析器会忽略,未知字段也缺少强诊断。
**交付。** 用现有 Markdown/frontmatter/契约表定义轻量知识约定,而不增加求道专属语法:可选的函数/断言级来源、适用范围、单位、负例、冲突/取代关系。明确知识内容类型与运行时类型的区别;事实可以是返回值、规则可以是函数、决策可以是声明性文档,类只用于真实模式复用。
由编译器生成身份、图边和 SourceRef,作者只维护实际内容与必要来源。为 plain note → draft fact/rule → verified callable 提供金样例和机器可读投影,不能仅把文本包在一个 print 中。字段不支持或位置错误时给诊断,避免“写了来源,编译却无声忽略”。
**验收。** 一文多来源、一事实多来源、原文冲突、缺失字段、单位不同、来源片段变化、声明性决策和可执行规则都能区分;无依据的信息保持 unknown;不要求每个纯工具函数带业务来源。
### M08 · P1/P2:生成式知识验收与真实复用评估不足
**现状。** 既有 26 项集成测试和 100 单元是有效基础,但不覆盖资料导入/模型沉淀全过程。现有 `eng_reuse` 协议测试证明 JSON 字段,不证明默认 Agent 调用了句柄;MLSP 直调测试证明本地纯函数复用,不证明模型按正确来源建库。测试 README、旧路线和示例中存在历史状态残留;此次 closure 测试失败也说明“done”必须和当前门禁分开。
**交付。** 两层评测:确定性 fixtures 验证协议和失败边界,固定任务集验证模型沉淀质量。每个样本保存原文、期望知识、可执行断言、来源定位、错误复用反例、实际上下文及版本;明确事实正确率与程序运行率不同。性能指标包括编译/检索延迟、上下文规模、修复轮次、真实 token、知识重复率和误晋升率。
**验收。** 用同一资料完成“首次建库→再次调用→原文更新→旧知识失效→修复发布”的完整故事;包括断网/缺插件/截断/OCR 错误/资料内指令/冲突来源。只统计有目标与结果 trace 的执行复用,不按 REUSE 决策估算零推理成本。核心发布门禁不能以 skip 计成功。
## 4. 建议的跨库接口边界
下表是待实现或待稳定的契约,不暗示现在已有同名函数/CLI。
| 契约 | Marqdo 保证 | 求道负责 |
|---|---|---|
| Document extraction | 原件摘要、标准正文、定位、诊断;扩展层实现格式转换 | 上传、任务、库范围、用户预览 |
| Knowledge draft | 当前语法卡片、检查/修复、可调用元数据 | 事实/规则选择、提示词、冲突与去重决策 |
| Verification report | 每个检查的真实状态、证据/制品摘要、阻断原因 | 项目政策、需要人工处理的歧义、发布编排 |
| Artifact handle | 唯一身份、依赖/证据失效、宿主能力边界 | 提交候选与输入、记录实际使用和解释 |
| Publish manifest | 一致的语义/索引代及可回滚读取 | 知识源码发布、迁移、当前活动版本 |
| Trace | 实际目标、输入、输出、版本与执行结果 | 回答来源展示、知识质量指标、运行记录关联 |
现有 `artifact.*`、sandbox、knowledge 等接口优先扩展;新增 façade 必须复用它们。工具协议、输出 schema 与提示词版本一起管理。首次本地试点可以使用固定目录与已授权项目政策;远程多租户的身份、凭据和隔离单独验收,不能把本地 MLSP 直接当公网授权协议。
## 5. 实施顺序
| 阶段 | 工作 | 完成条件 |
|---|---|---|
| F0 正确性基线 | M02/M03/M05:闭包反例、证据失效、验证状态、语法卡片 | 现有测试全过;来源变更/删除拒绝旧 business handle;提示词不含冲突语法 |
| F1 最小生产消费链 | M04 + 求道文本导入:candidate-only、验证钩子、绑定执行 trace | 同一资料第一次生成,第二次实际复用,门禁失败不学习发布 |
| F2 来源与更新 | M06/M07:统一源范围、来源定位/影响、发布 manifest | 改原文能找全受影响对象,发布失败旧版本仍可用 |
| F3 格式覆盖与评测 | M01/M08:PDF/DOCX/OCR 适配、资源限制、模型对照 | 文档可追溯,不完整提取显式报告,效果和失败分布有数据 |
框架不承担求道的登录界面、笔记列表、项目业务政策;求道不复制框架的 parser、binder、effect、lock 或执行器。无需为了这条主链先完成万能本体、全格式解析或远程授权平台。
## 6. 本轮可复核实验
### 6.1 当前门禁与失败复核
在框架仓库执行:
```bash
cargo test --offline --locked --test executable_knowledge
cargo test --offline --locked --test executable_knowledge \
s5_closure_digest_moves_with_dependency -- --exact
```
第一条结果为 25 passed、1 failed;第二条仍在 `tests/executable_knowledge.rs:586` 报 `caller closure digest must move with dependency`。两次比较结果相同。这是既有测试的执行结果;本次未修改其实现或断言。
审计开始时 `target/release/marqdo --version` 与旧 debug 都是 2.1.0;上述构建生成的 debug 是 2.1.1。后续最小实验使用新 debug,不能把旧 release 输出充当当前源码能力证据。
### 6.2 来源变化与旧句柄复现
以下程序仅在新建临时目录写测试文件,通过本地 MLSP 调用,不联网、不调用模型。构建当前 debug 后在仓库根运行:
```python
import json
import subprocess
import tempfile
from pathlib import Path
binary = str(Path("target/debug/marqdo").resolve())
root = Path(tempfile.mkdtemp(prefix="mq-source-audit-"))
def rpc(method, **params):
req = json.dumps({"method": method, "params": params}) + "\n"
proc = subprocess.run([binary, "mlsp"], input=req, text=True,
capture_output=True, check=True)
return json.loads(proc.stdout)
(root / "source.md").write_text("# rate\n\nrate = 0.13\n")
(root / "facts.mq.md").write_text(
"---\nsources:\n - source.md#missing-anchor\n"
"applicability:\n region: CN\n valid_until: 2099-12-31\n"
"---\n\n## rate\n\n*0.13*\n"
)
first = rpc("artifact.inspect", project=str(root), artifact_id="rate")["result"]
handle = rpc("artifact.bind", project=str(root), artifact_id="rate",
policy="business")["result"]["handle"]
(root / "source.md").write_text("# rate\n\nrate = 0.14\n")
second = rpc("artifact.inspect", project=str(root), artifact_id="rate")["result"]
print("evidence:", first["verification"]["evidence"])
print("source changed:", first["provenance"][-1]["content_digest"] !=
second["provenance"][-1]["content_digest"])
print("artifact changed:", first["hashes"]["artifact"] !=
second["hashes"]["artifact"])
print("after edit:", rpc("artifact.execute", handle=handle, inputs={}))
(root / "source.md").unlink()
print("after removal:", rpc("artifact.execute", handle=handle, inputs={}))
```
本轮观察:`evidence=sourced`、`source changed=True`、`artifact changed=False`;两次 execute 均 `ok=true`、result 为 `0.13`。正确修复后,缺锚点应先阻断相应来源政策;用有效锚点重新绑定后,改/删来源也应拒绝旧句柄或要求重验。不能只修复示例中的缺锚点而遗漏来源内容失效。
### 6.3 求道旧取元风险
以下代码在默认 2.1.1 中,第一行输出整个 map,第二行输出 False:
```markdown
# main
`m` =
| ok | status |
|---|---|
| False | denied |
**old = [ok](m)**
**new = access(m, "ok")**
> print text=`old`
> print text=`new`
```
这是默认语义变化,不是框架需要回退的新语法错误。求道需迁移;框架应提供一致的迁移指导、诊断和版本信息,而不是在 Skill 中继续教授冲突的旧默认。
## 7. 审计限制与后续文档同步
本次验证是源码审查、仓库固定测试和临时输入实验;没有执行真实 LLM 的建库质量评估,没有测试线上 Web 上传或真实 PDF/OCR。M01 的“缺少转换链”限定在所审查的主代码区域,不否定外部工具可以接入。M02 的闭包根因仍需按身份、依赖图、摘要计算分层定位。
完成后应同步当前 Skill、README、测试 README 和路线进度:分别标记语言能力、协议子集、产品已接入、当前测试结果。优先把失败样例转成稳定回归门禁,再扩大“可验证知识”“业务复用”“上传编译”的能力声明。此次文档提交不表示缺口已修复。
+28 -19
View File
@@ -1,35 +1,44 @@
# 可执行知识系统示例:订单含税总额
这是 [可执行知识系统设计](../../doc/design/executable-knowledge-system.md) 的目标示例。
它刻意展示 `[]()` 不只包“知识函数”:同一套语法同时命名取元、循环、推导、跨文件调用和正文结论。
这是 [可执行知识系统设计](../../doc/design/executable-knowledge-system.md) 的目标示例,
已按当前 occlusion 语法落地为**可运行**订单链(Tree / Bytecode)。
| 文件 | 图中的职责 | 关键步骤 |
|---|---|---|
| `corpus/tax-policy-2026.md` | E:证据 | 税率原文 |
| `schema/order.mq.md` | C:概念 | 订单/订单行字段与单位 |
| `knowledge/tax-2026.mq.md` | K:原子知识 | `[标准税率](0.13)` 及来源 |
| `knowledge/tax-2026.mq.md` | K:原子知识 | `标准税率.查询` + `sources:` |
| `knowledge/negative-refund.mq.md` | 负知识 | 折扣不适用于退款 |
| `capabilities/order-pricing.mq.md` | D:推导知识 | 取元、调用、循环、汇总 |
| `docs/invoice-answer.mq.md` | N:叙述知识 | 用同一个计算给人可读的回答 |
| `docs/invoice-answer.mq.md` | N:叙述知识 | 含税结论 + NarrativeRef |
## 运行
```bash
marqdo run examples/executable-knowledge/docs/invoice-answer.mq.md --backend tree
marqdo run examples/executable-knowledge/docs/invoice-answer.mq.md --backend bytecode
# → 113
marqdo knowledge examples/executable-knowledge -o /tmp/ek
marqdo knowledge impact "标准税率.查询" examples/executable-knowledge --json
```
门禁:`cargo test --test executable_knowledge s4_examples_bookstore_chain_runs_both_backends --locked`
## 读法
`[]()` 的每一次出现都是 `Named<T>`:
`[]()` 的每一次出现都是命名步骤(observe / derive / iterate / call / narrate):
```markdown
[订单行金额](at(行, "金额")) # observe
[本行含税价](订单行金额 * (1 + 税率)) # derive
[逐个订单行](遍历 订单.行 为 行) # iterate
[含税总价](pricing.订单定价.含税总额(订单)) # reuse / narrate
[订单行金额](access(行, "金额")) # observe
[本行含税价](金额 * (1 + 税率)) # derive
[逐个订单行](遍历 行列表 为 行) # iterate
这张订单的含税总额是[含税总价](总额)。 # narrate
```
它们不是四种语法。`()` 中仍是原有的取元、算术、循环和调用;`[]` 让每一步同时可读、可查、
可在图中定位。当前实现尚不能完整运行该目标形式(类函数、统一 `Named<T>`、步骤图仍是设计目标),
但它给出了实际项目中应当写成什么样子。
## 运行状态
## 预期闭环
1. `check` 从每个 `[]()` 提取观测、推导、遍历和调用依赖;
2. `view` 在“含税总额”旁显示所经过的订单行、标准税率和税率原文;
3. 税率原文变更时,`impact` 找到原子税率、订单定价、发票回答中的每一个命名步骤;
4. `verify` 只重算 pure 步骤,不执行写入或发送等 `act` 步骤;
5. agent 通过 catalog 得到“已有订单定价能力”和其证据链,不必从自然语言猜测。
| 子集 | 状态 | 证据 |
|---|---|---|
| 发票含税链双后端 `113` | **可运行** | 上表命令 / EK 门禁 |
| 来源 `sourced` + impact 下游 | **可运行** | knowledge 投影 + impact |
| 负知识文档 | **已收录** | `knowledge/negative-refund.mq.md`(发现层;非执行目标) |
@@ -1,27 +1,32 @@
---
markup: occlusion
id: capability.order-pricing
type: Capability
import:
tax: ../knowledge/tax-2026.mq.md
order: ../schema/order.mq.md
---
# 订单定价
## 含税价
+ `行`
按订单行取未税金额与品类,套用税率后汇总含税总额。
**金额 = [订单行金额](at(行, "金额"))**
**品类 = [订单行品类](at(行, "品类"))**
**税率 = [适用税率](tax.标准税率.查询(品类))**
## 含税价
`行`
**金额 = [订单行金额](access(行, "金额"))**
**品类 = [订单行品类](access(行, "品类"))**
**税率 = > tax.标准税率.查询 品类=`品类`**
**结果 = [本行含税价](金额 * (1 + 税率))**
**结果**
*结果*
## 含税总额
+ `订单`
- [逐个订单行](遍历 订单.行 为 行)
**行含税价 = [计算本行含税价](订单定价.含税价(行))**
`订单`
**总额 = [汇总全部行含税价](sum(行含税价))**
**总额**
**行列表 = [订单行列表](access(订单, "行"))**
`总额` = 0
- [逐个订单行](遍历 行列表 为 行)
**行含税价 = > 订单定价.含税价 行=`行`**
**总额 = [累加](总额 + 行含税价)**
*总额*
@@ -4,12 +4,16 @@ id: document.invoice-answer
type: Answer
import:
pricing: ../capabilities/order-pricing.mq.md
json: lib/json.mq.md
---
# 发票回答
# main
**总额 = [订单的含税总价](access(pricing.订单定价.含税总额(订单), "订单的含税总价"))**
发票回答:演示订单一行图书,未税金额 100。
`订单` = > json.parse text={"行":[{"金额":100,"品类":"书"}]}
**总额 = > pricing.订单定价.含税总额 订单=`订单`**
这张订单的含税总额是[含税总价](总额)。
> view 应可展开:含税总价 → 汇总全部行含税价 → 逐个订单行 → 本行含税价 → 适用税率 → 税率原文。
> print text=`总额`
@@ -0,0 +1,14 @@
---
markup: occlusion
id: knowledge.negative.discount-not-for-refund
type: Failure
title: 折扣不适用于退款
---
# 折扣不适用于退款
负知识:退款结算不得套用会员折扣。Agent 复用折扣能力时应拒绝该适用面。
## 说明
*[不适用](false)*
@@ -1,18 +1,20 @@
---
markup: occlusion
id: knowledge.tax.standard-2026
type: Fact
sources:
- ../corpus/tax-policy-2026.md#2026 年标准增值税率
applicability:
region: CN
valid_until: 2099-12-31
---
# 标准税率
当前政策下的标准增值税率。`品类` 预留给差异化税率;本演示固定返回标准税率。
## 查询
+ `品类`
| 返回 | 类型 | 来源 |
|---|---|---|
| 0.13 | number | corpus/tax-policy-2026.md#2026 年标准增值税率 |
`品类`
**税率 = [标准税率](0.13)**
**税率**
*[标准税率](0.13)*
+1 -1
View File
@@ -1 +1 @@
2.1.0
2.1.2
+80 -12
View File
@@ -849,25 +849,44 @@ Write a scratch tool workbook under `.marqdo/agent-runs/tools/<name>.mq.md`.
---
## skill_core_card
Protected v2.1 Occlusion card always prepended to skill_brief (M05). Must not be truncated by budget.
**esc = > json.parse text={"card":"## CORE SYNTAX (v2.1 Occlusion)\n1. Print with > print / > 打印 — never use bold markers to print.\n2. Bold markers = return/code; italic markers = statement.\n3. [desc](payload) = occlusion; brackets never execute.\n4. Read with access(coll, key) — never Classic [key](map) index.\n5. Foreach: - [desc](for coll as item). import + one language per file.\n6. # type · ## function · + params · numbered branches · - loops.\n"}**
*> json.get value=`esc` key="card"*
---
## skill_brief
+ `max_chars`=1200
+ `depth`=default
Budgeted marqdo skill text for prompts. `depth=deep` raises the char budget.
Budgeted marqdo skill text for prompts. Core Occlusion card is always included; remaining budget truncates the rest. `depth=deep` raises the char budget.
1. `depth` == deep
**budget = 4000**
2. *
**budget = max_chars**
**core = > skill_core_card**
**core_len = > len value=`core`**
**rest_budget = budget - core_len - 2**
1. `rest_budget` < 200
**rest_budget = 200**
2. *
**_ = 1**
**skill = > agent_marqdo_skill**
**full = > len value=`skill`**
**ex = > text_head_lines text=`skill` max_lines=80 max_chars=`budget`**
**rest = > text_head_lines text=`skill` max_lines=80 max_chars=`rest_budget`**
**esc = > json.parse text={"nl":"\n\n"}**
**nl = > json.get value=`esc` key="nl"**
**ex = core + nl + rest**
**used = > len value=`ex`**
1. `used` < `full`
**esc = > json.parse text={"a":"\n…[truncated skill_len=","b":" budget_chars=","c":"; emit READ:skill to deepen]"}**
**a = > json.get value=`esc` key="a"**
**b = > json.get value=`esc` key="b"**
**c = > json.get value=`esc` key="c"**
1. `used` < `full` + `core_len`
**esc2 = > json.parse text={"a":"\n…[truncated skill_len=","b":" budget_chars=","c":"; emit READ:skill to deepen]"}**
**a = > json.get value=`esc2` key="a"**
**b = > json.get value=`esc2` key="b"**
**c = > json.get value=`esc2` key="c"**
*ex + a + full + b + budget + c*
2. *
*ex*
@@ -1973,18 +1992,27 @@ O5: mark OKF skill `status: quarantine` and force `llm_free: false`. Regression
+ `memory_dir`=.marqdo/agent-memory
+ `improve_every`=3
+ `promote`=True
+ `candidate_only`=False
+ `product_gate_ok`=True
Offline learn gate: when ≥ `improve_every` successful episodes share a task hash, generalize → synthesize → compile → optional OKF promote (`llm_free`). Also attempts Policy Compilation for Adaptive Routing.
O2: promote path requires sandbox proof unless `require_proof=false`.
M04: `candidate_only=True` or `product_gate_ok=False` forces promote off via eng_publish_gate.
**gate = > `self`.eng_publish_gate project="." candidate_only=`candidate_only` product_gate_ok=`product_gate_ok`**
**may_prom = > json.get value=`gate` key="may_promote"**
1. not `may_prom`
**promote = False**
2. *
**_ = 1**
**skill_learn = > agent_maybe_learn task=`task` kb_dir=`kb_dir` memory_dir=`memory_dir` improve_every=`improve_every` promote=`promote`**
**policy_learn = > agent_maybe_compile_policy memory_dir=`memory_dir` min_evidence=`improve_every`**
**sl = > json.get value=`skill_learn` key="learned"**
`out` =
| learned | skill | policy |
|---------|-------|--------|
| `sl` | `skill_learn` | `policy_learn` |
| learned | skill | policy | promote_allowed | gate |
|---------|-------|--------|-----------------|------|
| `sl` | `skill_learn` | `policy_learn` | `may_prom` | `gate` |
*out*
@@ -2128,7 +2156,18 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o
1. `efi_st` == "missing_knowledge"
**_ = 1**
2. `efi_dec` == "REUSE"
**_ = 1**
**efi_exec = > agent_eng_bind_execute project="." query=`task` policy="pure" candidate_only=False**
**efi_ok = > json.get value=`efi_exec` key="ok"**
1. `efi_ok`
**exec_mode = "efi_bound"**
**out = **
| status | goal | result | summary | efi | reuse_trace |
|--------|------|--------|---------|-----|-------------|
| ok | `task` | `efi_exec` | EFI REUSE bound+executed | `efi_pf` | `efi_exec` |
2. *
**_ = 1**
3. `efi_dec` == "ADAPT"
**_ = 1**
4. `efi_allow`
@@ -2433,13 +2472,42 @@ Hard rule: generate only when `create_allowed` is true (or decision is REUSE/ADA
+ `root`="."
+ `marqdo_dir`=None
Alias of `preflight` focused on REUSE / ADAPT / CREATE payload.
Alias of `preflight` focused on REUSE / ADAPT / CREATE payload (discovery_only).
1. `marqdo_dir`
*> agent_eng_reuse task=`task` root=`root` marqdo_dir=`marqdo_dir`*
2. *
*> agent_eng_reuse task=`task` root=`root`*
---
## eng_bind_execute
+ `project`="."
+ `query`
+ `policy`="pure"
+ `inputs`=None
+ `candidate_only`=False
M04: discover → bind → execute → record. Prefer over treating eng_reuse scores as execution.
1. `inputs`
*> agent_eng_bind_execute project=`project` query=`query` policy=`policy` inputs=`inputs` candidate_only=`candidate_only`*
2. *
*> agent_eng_bind_execute project=`project` query=`query` policy=`policy` candidate_only=`candidate_only`*
---
## eng_publish_gate
+ `project`="."
+ `artifact_id`=None
+ `candidate_only`=False
+ `product_gate_ok`=True
+ `policy`="business"
Refuse promote when candidate_only or product/verification gate fails.
*> agent_eng_publish_gate project=`project` artifact_id=`artifact_id` candidate_only=`candidate_only` product_gate_ok=`product_gate_ok` policy=`policy`*
## eng_record
+ `decision`
+ `root`="."
+241 -7
View File
@@ -77,7 +77,10 @@ fn resolve_marqdo_root(start: &str) -> PathBuf {
}
for _ in 0..8 {
let cand = cur.join(".marqdo");
if cand.join("engineering.yaml").exists() || cand.join("graph/graph.json").exists() {
if cand.join("engineering.yaml").exists()
|| cand.join("ekc/graph/graph.json").exists()
|| cand.join("graph/graph.json").exists()
{
return cand;
}
if !cur.pop() {
@@ -289,7 +292,10 @@ pub fn eng_preflight(args: &Value) -> Result<Value, String> {
.map(PathBuf::from)
.unwrap_or_else(|| resolve_marqdo_root(root));
if !marqdo.join("engineering.yaml").exists() && !marqdo.join("graph/graph.json").exists() {
if !marqdo.join("engineering.yaml").exists()
&& !marqdo.join("ekc/graph/graph.json").exists()
&& !marqdo.join("graph/graph.json").exists()
{
return Ok(json!({
"status": "missing_knowledge",
"create_allowed": false,
@@ -424,18 +430,246 @@ 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)
}
/// M04: discover → inspect → bind → execute → record (actual reuse, not n-gram REUSE).
///
/// Requires host_query `mlsp`. Returns trace with artifact_id, digests, inputs, result.
/// Does **not** promote skills — callers pass `candidate_only=true` to skip learn/promote.
pub fn eng_bind_execute(args: &Value) -> Result<Value, String> {
let project = args
.get("project")
.or_else(|| args.get("root"))
.and_then(|v| v.as_str())
.unwrap_or(".");
let policy = args
.get("policy")
.and_then(|v| v.as_str())
.unwrap_or("pure");
let inputs = args.get("inputs").cloned().unwrap_or(json!({}));
let query = if let Some(q) = args.get("artifact_id").or_else(|| args.get("query")).and_then(|v| v.as_str()) {
q.to_string()
} else {
// Fall back to first bind_target from eng_reuse.
let reuse = eng_reuse(args)?;
let targets = reuse
.get("bind_targets")
.and_then(|v| v.as_array())
.cloned()
.unwrap_or_default();
targets
.first()
.and_then(|t| t.get("query").and_then(|q| q.as_str()))
.ok_or_else(|| {
"eng_bind_execute: no artifact_id/query and eng_reuse returned no bind_targets"
.to_string()
})?
.to_string()
};
let inspect = crate::host_query_json_args(
"mlsp",
&json!({"method":"artifact.inspect","params":{"project":project,"artifact_id":&query}}),
)?;
if inspect.get("ok") != Some(&json!(true)) {
return Ok(json!({
"ok": false,
"stage": "inspect",
"error": inspect.get("error").cloned().unwrap_or(json!("inspect failed")),
"query": query,
}));
}
let artifact_id = inspect["result"]["artifact_id"]
.as_str()
.unwrap_or(&query)
.to_string();
let bound = crate::host_query_json_args(
"mlsp",
&json!({"method":"artifact.bind","params":{"project":project,"artifact_id":&artifact_id,"policy":policy}}),
)?;
if bound.get("ok") != Some(&json!(true)) {
return Ok(json!({
"ok": false,
"stage": "bind",
"error": bound.get("error").cloned().unwrap_or(json!("bind failed")),
"artifact_id": artifact_id,
"discovery_only": false,
}));
}
let handle = bound["result"]["handle"].clone();
let executed = crate::host_query_json_args(
"mlsp",
&json!({"method":"artifact.execute","params":{"handle":&handle,"inputs":inputs}}),
)?;
if executed.get("ok") != Some(&json!(true)) {
return Ok(json!({
"ok": false,
"stage": "execute",
"error": executed.get("error").cloned().unwrap_or(json!("execute failed")),
"artifact_id": artifact_id,
"handle": handle,
}));
}
// Record only after successful bind+execute (actual reuse).
let _ = eng_record(&json!({
"decision": "REUSE",
"root": project,
"marqdo_dir": args.get("marqdo_dir"),
}));
Ok(json!({
"ok": true,
"stage": "executed",
"discovery_only": false,
"bind_required": false,
"actual_reuse": true,
"artifact_id": artifact_id,
"symbol_id": handle.get("symbol_id"),
"digest": handle.get("digest"),
"evidence_digest": handle.get("evidence_digest"),
"closure_digest": handle.get("closure_digest"),
"policy": policy,
"inputs": inputs,
"result": executed.get("result"),
"candidate_only": args.get("candidate_only").and_then(|v| v.as_bool()).unwrap_or(false),
"trace": {
"artifact_id": artifact_id,
"symbol_id": handle.get("symbol_id"),
"digest": handle.get("digest"),
"inputs": inputs,
"stdout": executed["result"]["stdout"],
"value": executed["result"]["result"],
},
}))
}
/// Gate promote/learn: when `candidate_only` or may_bind=false, refuse promotion.
pub fn eng_publish_gate(args: &Value) -> Result<Value, String> {
let candidate_only = matches!(args.get("candidate_only"), Some(Value::Bool(true)));
let product_ok = !matches!(args.get("product_gate_ok"), Some(Value::Bool(false)));
let project = args
.get("project")
.or_else(|| args.get("root"))
.and_then(|v| v.as_str())
.unwrap_or(".");
let policy = args
.get("policy")
.and_then(|v| v.as_str())
.unwrap_or("business");
let artifact = args
.get("artifact_id")
.or_else(|| args.get("query"))
.and_then(|v| v.as_str());
if candidate_only {
return Ok(json!({
"ok": true,
"may_promote": false,
"reason": "candidate_only — framework must not promote",
}));
}
if !product_ok {
return Ok(json!({
"ok": true,
"may_promote": false,
"reason": "product gate failed — framework must not promote",
}));
}
if let Some(id) = artifact {
let adj = crate::host_query_json_args(
"mlsp",
&json!({"method":"artifact.verify","params":{"project":project,"artifact_id":id,"policy":policy}}),
)?;
let may_bind = adj
.pointer("/result/may_bind")
.and_then(|v| v.as_bool())
.unwrap_or(false);
return Ok(json!({
"ok": true,
"may_promote": may_bind,
"verification": adj.get("result"),
"reason": if may_bind { "verification allows bind" } else { "verification denied bind" },
}));
}
Ok(json!({
"ok": true,
"may_promote": product_ok,
"reason": "no artifact_id; deferred to product_gate_ok",
}))
}
/// `agent_eng_record` — append reuse metrics under `.marqdo/agent/episodes`.
pub fn eng_record(args: &Value) -> Result<Value, String> {
let decision = arg_text(args, "decision")?;
+4
View File
@@ -831,6 +831,8 @@ kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear");
kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list");
kb_ffi!(agent_eng_preflight, eng::eng_preflight, "agent_eng_preflight");
kb_ffi!(agent_eng_reuse, eng::eng_reuse, "agent_eng_reuse");
kb_ffi!(agent_eng_bind_execute, eng::eng_bind_execute, "agent_eng_bind_execute");
kb_ffi!(agent_eng_publish_gate, eng::eng_publish_gate, "agent_eng_publish_gate");
kb_ffi!(agent_eng_record, eng::eng_record, "agent_eng_record");
#[no_mangle]
@@ -900,6 +902,8 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
("agent_maybe_compile_policy", "memory_dir,min_evidence", agent_maybe_compile_policy),
("agent_eng_preflight", "task", agent_eng_preflight),
("agent_eng_reuse", "task", agent_eng_reuse),
("agent_eng_bind_execute", "project,query,policy", agent_eng_bind_execute),
("agent_eng_publish_gate", "project,artifact_id,candidate_only", agent_eng_publish_gate),
("agent_eng_record", "decision", agent_eng_record),
("sandbox_open", "", sandbox::sandbox_open),
("sandbox_write", "", sandbox::sandbox_write),
+20 -2
View File
@@ -81,7 +81,16 @@ func (st *state) handleUpload(w http.ResponseWriter, r *http.Request, routePath
_, hadCookie := session.IDFromCookie(r.Header.Get("Cookie"))
sid, _, setCookie := resolveSession(r)
if err := r.ParseMultipartForm(32 << 20); err != nil {
// M01: hard-limit request body before multipart parse (32MiB was only in-memory
// form budget, not a request total). Cap at configured MaxBytes + 1MiB overhead.
maxBody := int64(cfg.MaxBytes)
if maxBody <= 0 {
maxBody = 32 << 20
}
overhead := int64(1 << 20)
r.Body = http.MaxBytesReader(w, r.Body, maxBody+overhead)
if err := r.ParseMultipartForm(maxBody + overhead); err != nil {
jsonErr(w, http.StatusBadRequest, fmt.Sprintf("multipart: %v", err))
return
}
@@ -109,11 +118,20 @@ func (st *state) handleUpload(w http.ResponseWriter, r *http.Request, routePath
return
}
defer f.Close()
b, err := io.ReadAll(f)
// Stream-capped read: never buffer more than MaxBytes.
lim := maxBody
if lim <= 0 {
lim = 32 << 20
}
b, err := io.ReadAll(io.LimitReader(f, lim+1))
if err != nil {
jsonErr(w, http.StatusBadRequest, fmt.Sprintf("read file: %v", err))
return
}
if int64(len(b)) > lim {
jsonErr(w, http.StatusRequestEntityTooLarge, "file exceeds max_bytes")
return
}
fileBytes = b
} else {
// Fallback: walk File map keys.
@@ -0,0 +1,45 @@
package httpx
import (
"bytes"
"mime/multipart"
"net/http"
"net/http/httptest"
"strings"
"testing"
)
func TestHandleUploadRejectsOversizedBeforeFullBuffer(t *testing.T) {
st := &state{
uploadRoutes: map[string]any{
"/upload": map[string]any{
"field": "file",
"storage_url": "memory://t",
"prefix": "u",
"max_bytes": float64(64),
},
},
}
cfg := parseUploadRoute(st.uploadRoutes["/upload"])
var body bytes.Buffer
w := multipart.NewWriter(&body)
part, err := w.CreateFormFile("file", "big.txt")
if err != nil {
t.Fatal(err)
}
if _, err := part.Write([]byte(strings.Repeat("x", 200))); err != nil {
t.Fatal(err)
}
_ = w.Close()
req := httptest.NewRequest(http.MethodPost, "/upload", &body)
req.Header.Set("Content-Type", w.FormDataContentType())
rr := httptest.NewRecorder()
st.handleUpload(rr, req, "/upload", cfg)
if rr.Code == http.StatusOK {
t.Fatalf("expected reject for oversized upload, got %d body=%s", rr.Code, rr.Body.String())
}
if rr.Code != http.StatusRequestEntityTooLarge && rr.Code != http.StatusBadRequest {
t.Fatalf("expected 413 or 400, got %d body=%s", rr.Code, rr.Body.String())
}
}
+36 -53
View File
@@ -14,66 +14,49 @@ description: >-
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
<!-- CORE_SYNTAX_V2.1: must stay at the top so skill_brief budgets never truncate it -->
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
## CORE SYNTAX (v2.1 Occlusion — mandatory)
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
These rules are the **current default**. Do **not** teach Classic `[key](map)` index or “bold is return of print”. Classic migration only: [migration-classic.md](migration-classic.md).
1. **File suffix** `.mq.md`. Print with `> print text=…` / `> 打印 内容=…` — never use `**…**` to print.
2. **`**…**` = code / return expression.** `*…*` = statement (bind / expr). Closing markers touch the last token (no trailing space).
3. **`[描述](payload)` = occlusion:** `[]` is prose (never executed); `()` is the only executed part. Empty `()` → `None` stub.
4. **Read collections with `access(coll, key)`** (aliases `取` / `取值`). **Never** use `[key](map)` as index under default Occlusion.
5. **Foreach:** `- [描述](遍历 coll 为 item)` (`遍历`/`for`, `为`/`as`/`in`). Prefer explicit traversal when generating new code.
6. **Import / call:** frontmatter `import:` / `导入:`; call `lib.member`. One language (EN or ZH) per file.
7. **Control flow:** `#` object/type, `##`+ function, `+` params, `1.`/`2.` branches, `-` loops, `N. *` else. No invented `if`/`for`/`def`/`return` keywords.
8. **Prose vs code:** blank line separates comment paragraphs from executable lines.
9. **GFM tables** for data; prefer `table.put` over `json.set` chains. `ext/**` never calls `host_*`.
10. Body narrative `[描述](target)` is lazy (NarrativeRef) — reading does not execute side effects.
| Marker | Meaning (v2.1) |
|--------|----------------|
| `#` / `##`+ | Object/type · function/method |
| `*…*` | Statement |
| `**…**` | Return / code expression |
| `[描述](payload)` | Occlusion step (payload executes) |
| `access(c, k)` | Collection read |
| `> fn …` | Call |
| GFM table | Collection literal |
Canonical: `doc/design/core-surface.md`, `doc/design/document-native-development-guide.md`. Deeper tables: [reference.md](reference.md). Patterns: [examples.md](examples.md). Authoring craft: [marqdo-dev](../marqdo-dev/SKILL.md). Release: [marqdo-release](../marqdo-release/SKILL.md).
Executable-knowledge gate: [`tests/executable_knowledge/`](../../tests/executable_knowledge/README.md).
## Hard rules (do not violate)
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
8. Prefer ending side-effect-only function bodies with `*None*` / `*无*` / whole-line `**` / `****` when later lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped), not function end.
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. Read collections with **`[key](map)`**, not footnote indexes for new code. In `markup: occlusion` files read with **`access(map, key)`** — there `[x](y)` is occlusion, not index. **Positive copy-paste shapes** (result map, soft-error pack, sparse `table.put`): [marqdo-dev](../marqdo-dev/SKILL.md) §2 · [examples.md](examples.md) §6e. Do **not** extend legacy `json.set` in `ext/ai` — refactor to tables.
12. **One language per file:** Do not mix EN and ZH API names in the same `.mq.md` (imports, calls, params). Pick English *or* Chinese mirrors for the whole program.
13. **Sandbox trial habit (Agent / generated `.mq.md`):** Prefer `agent.trial` / `run sandbox=True` / `sandbox.open`→`run`→`diff`→`commit` before promoting to the host tree. Host files must stay unchanged until a successful commit. Caps live in `sandbox.profile` GFM tables — do not invent a second dialect.
1. Obey **CORE SYNTAX** above — Occlusion is default; do not emit Classic index links.
2. **Identifiers:** params `` + `name` ``; inside `*…*` / `**…**` bare ids are variables. Quote text literals. Standalone `>` calls: backticks where bare would be text.
3. **Structure lines** (`#` `>` `+` `-` `|`) are not wrapped in italics.
4. **Paths:** bare `/` in expressions is division; in call args / table cells unspaced `a/b` is path text. Ratios as text need quotes (`"1/5"`).
5. End side-effect-only helpers with `*None*` / `*空*` / `**` / `****` when the outer function continues. Lone `---` is a thematic break, not function end.
6. **`ext/**` never calls `host_*`.** Prefer tables over `json.set` / `json.append`.
7. **One language per file.** Sandbox trial before promoting Agent-generated trees.
8. Browser: Marqdo on WASM + `lib/browser` tables; do not hand-write business JS.
## Markup → meaning (v0.2)
| Marker | Meaning |
|--------|---------|
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
| `##` … `######` | **Function / method** (nesting by heading depth). |
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
| Frontmatter nested `import:` / `导入:` map | Import file (`bind: path.mq.md`) or short name (`bind: lib.member`) |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
| `****` or `**` + spaces + `**` | Return `None` and end function body |
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
| `- [item](coll)` | Foreach (unchanged) |
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
| Unmarked prose | Comment |
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
## Occlusion syntax (v2.0.0)
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).
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
- `[顾客留存率](0.42)` · `[总价](at(价目表, "苹果") * 数量)` · `[功能开发中]()` → `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.
- Tooling: `marqdo labels pending` (stub ledger) · `marqdo labels --grep 词 --count` · `marqdo migrate labels . --write` · `marqdo check` reports `label.missing` / `label.empty_payload` / `label.ref_dangling`.
## Minimal program
```markdown
+12
View File
@@ -0,0 +1,12 @@
# Classic markup migration card (not default)
Use this card **only** when editing files that declare `markup: classic` / `标记: 经典`, or when the CLI is run with `--legacy-markup`. New documents must use Occlusion (see SKILL.md CORE SYNTAX).
| Classic (legacy) | Occlusion / current |
|---|---|
| `[key](map)` index read | `access(map, "key")` / `取(map, "key")` |
| `- [item](coll)` foreach by index form | `- [描述](遍历 coll 为 item)` |
| Teach `**…**` as “the return of print” | Print with `> print`; `**…**` is return/code expression |
| Default link = index | Default `[描述](payload)` = occlusion; `[]` never executes |
Do not place Classic rules in the front of the default Skill pack. After migration, remove `markup: classic` and verify with `marqdo run` / `marqdo check`.
+71 -18
View File
@@ -28,11 +28,14 @@ struct FlatFun {
path_index: HashMap<Vec<String>, usize>,
/// Short name from frontmatter `use` → path segments.
uses: HashMap<String, Vec<String>>,
/// Module collection scope (G02): bare-name resolve must not cross imports.
scope: u32,
}
pub fn compile_module(path: Option<&Path>, module: &Module) -> Result<Program> {
let mut flat = Vec::new();
let _exports = collect_module_tree(module, &mut flat);
let mut next_scope = 1u32;
let _exports = collect_module_tree(module, &mut flat, 0, &mut next_scope);
if flat.is_empty() {
bail!("bytecode: no functions to compile");
}
@@ -106,10 +109,21 @@ pub fn compile_module(path: Option<&Path>, module: &Module) -> Result<Program> {
/// Collect `module` and its imports into `flat`.
/// Returns relative export paths within this module (e.g. `["parse"]`, `["agent","step"]`).
fn collect_module_tree(module: &Module, flat: &mut Vec<FlatFun>) -> HashMap<Vec<String>, usize> {
///
/// Each module gets a distinct `scope` id. Bare-name `resolve_call` only searches
/// within the caller's scope so imported same-named functions cannot be silently
/// selected (BoundCall / G02). Cross-module calls must use `bind.member` paths.
fn collect_module_tree(
module: &Module,
flat: &mut Vec<FlatFun>,
scope: u32,
next_scope: &mut u32,
) -> HashMap<Vec<String>, usize> {
let mut path_index = HashMap::new();
for (bind, dep) in &module.import_modules {
let dep_exports = collect_module_tree(dep, flat);
let child_scope = *next_scope;
*next_scope += 1;
let dep_exports = collect_module_tree(dep, flat, child_scope, next_scope);
for (rel, idx) in dep_exports {
let mut full = Vec::with_capacity(rel.len() + 1);
full.push(bind.clone());
@@ -124,11 +138,23 @@ fn collect_module_tree(module: &Module, flat: &mut Vec<FlatFun>) -> HashMap<Vec<
.map(|u| (u.bind.clone(), u.path.clone()))
.collect();
let start = flat.len();
let mut exports = HashMap::new();
for fun in &module.functions {
let id = collect_fun(fun, None, flat, &path_index, &uses);
let id = collect_fun(fun, None, flat, &path_index, &uses, scope);
export_tree(&mut exports, &[], id, flat);
}
// Same-module BoundCall paths (`Type.member`) must be visible to siblings.
for (rel, idx) in &exports {
path_index.insert(rel.clone(), *idx);
}
for f in &mut flat[start..] {
if f.scope == scope {
for (rel, idx) in &exports {
f.path_index.insert(rel.clone(), *idx);
}
}
}
exports
}
@@ -152,6 +178,7 @@ fn collect_fun(
flat: &mut Vec<FlatFun>,
path_index: &HashMap<Vec<String>, usize>,
uses: &HashMap<String, Vec<String>>,
scope: u32,
) -> usize {
let id = flat.len();
flat.push(FlatFun {
@@ -166,10 +193,11 @@ fn collect_fun(
span: fun.span,
path_index: path_index.clone(),
uses: uses.clone(),
scope,
});
let mut child_ids = Vec::new();
for child in &fun.children {
child_ids.push(collect_fun(child, Some(id), flat, path_index, uses));
child_ids.push(collect_fun(child, Some(id), flat, path_index, uses, scope));
}
flat[id].children = child_ids;
id
@@ -323,28 +351,42 @@ impl<'a> FnCompiler<'a> {
s
}
/// BoundCall-equivalent bare-name resolve (G02): only the caller's module
/// scope. Imported functions are reachable solely via `path_index` paths.
fn resolve_call(&self, name: &str) -> Result<usize> {
let fun = &self.flat[self.fn_id];
let scope = fun.scope;
for &cid in &fun.children {
if self.flat[cid].name == name {
if self.flat[cid].name == name && self.flat[cid].scope == scope {
return Ok(cid);
}
}
let mut parent = fun.parent;
while let Some(pid) = parent {
if self.flat[pid].scope != scope {
break;
}
for &cid in &self.flat[pid].children {
if self.flat[cid].name == name {
if self.flat[cid].name == name && self.flat[cid].scope == scope {
return Ok(cid);
}
}
parent = self.flat[pid].parent;
}
let mut matches = Vec::new();
for (i, f) in self.flat.iter().enumerate() {
if f.parent.is_none() && f.name == name {
return Ok(i);
if f.parent.is_none() && f.scope == scope && f.name == name {
matches.push(i);
}
}
Err(self.err(format!("unknown function `{name}`")))
match matches.as_slice() {
[only] => Ok(*only),
[] => Err(self.err(format!("unknown function `{name}`"))),
_ => Err(self.err(format!(
"ambiguous function `{name}`: {} candidates in this module; use an explicit path",
matches.len()
))),
}
}
fn compile_stmt(&mut self, stmt: &Stmt) -> Result<()> {
@@ -470,13 +512,20 @@ impl<'a> FnCompiler<'a> {
}
fn compile_call(&mut self, call: &CallExpr, as_stmt: bool) -> Result<()> {
// Mirror `sema::bind::resolve_for_exec` (G02 BoundCall):
// static → Op::Call(fid); dynamic → MethodCall / CallFn / PluginCall.
let mut call = call
.with_modifiers_expanded()
.map_err(|m| self.err(m))?;
if let Some(recv) = &call.receiver {
return self.compile_method_call(recv, &call, as_stmt);
}
if let Some(path) = &call.path {
// Bare dotted callee `a.b`: if `a` is a local variable, it is a method
// receiver (Python-style unified namespace); otherwise it's a library path.
if path.len() == 2 && self.locals.contains_key(&path[0]) {
// Local-var method sugar before import path (same as Tree / resolve_for_exec).
if path.len() == 2
&& self.locals.contains_key(&path[0])
&& !self.flat[self.fn_id].path_index.keys().any(|p| p.first() == Some(&path[0]))
{
let recv = path[0].clone();
return self.compile_method_call(&recv, &call, as_stmt);
}
@@ -488,10 +537,6 @@ impl<'a> FnCompiler<'a> {
call.callee =
crate::aliases::normalize_call_callee_and_args(&call.callee, &mut call.args);
if let Some(recv) = &call.receiver {
return self.compile_method_call(recv, &call, as_stmt);
}
match call.callee.as_str() {
"print" => {
let text_expr = call
@@ -648,9 +693,17 @@ impl<'a> FnCompiler<'a> {
_ => {}
}
// BoundCall bare name (same-module scope only) or DynamicCall plugin.
match self.resolve_call(&call.callee) {
Ok(fid) => self.compile_user_call(fid, &call, as_stmt),
Err(_) => self.compile_plugin_call(&call, as_stmt),
Err(err) => {
let msg = format!("{err:#}");
if msg.contains("ambiguous function") {
return Err(err);
}
// DynamicCall(Plugin): unresolved bare names may be runtime plugins.
self.compile_plugin_call(&call, as_stmt)
}
}
}
+293
View File
@@ -0,0 +1,293 @@
//! Document extraction protocol (M01): DocumentSource → ExtractedDocument.
//!
//! Format parsers live here / in extensions — language core does not OCR.
//! First slice: plain text and Markdown. PDF/DOCX plug in later via the same shape.
use std::fs;
use std::path::Path;
use sha2::{Digest, Sha256};
use serde_json::{json, Value};
pub const EXTRACTOR_VERSION: &str = "marqdo-document-extract/1";
#[derive(Debug, Clone)]
pub struct DocumentSource {
pub path: std::path::PathBuf,
pub format_hint: Option<String>,
}
#[derive(Debug, Clone)]
pub struct ExtractedSegment {
pub id: String,
pub kind: String,
pub text: String,
pub locator: String,
pub confidence: f64,
}
#[derive(Debug, Clone)]
pub struct ExtractedDocument {
pub source_uri: String,
pub source_digest: String,
pub format: String,
pub extractor_version: String,
pub text: String,
pub segments: Vec<ExtractedSegment>,
pub missing: Vec<String>,
pub diagnostics: Vec<String>,
pub status: String,
}
impl ExtractedDocument {
pub fn to_json(&self) -> Value {
json!({
"schema_version": 1,
"source_uri": self.source_uri,
"source_digest": self.source_digest,
"format": self.format,
"extractor_version": self.extractor_version,
"status": self.status,
"text": self.text,
"segments": self.segments.iter().map(|s| json!({
"id": s.id,
"kind": s.kind,
"text": s.text,
"locator": s.locator,
"confidence": s.confidence,
})).collect::<Vec<_>>(),
"missing": self.missing,
"diagnostics": self.diagnostics,
})
}
}
/// Extract text/Markdown from a file. Uploaded `.mq.md` is treated as untrusted
/// source text and is never executed here.
pub fn extract_document(source: &DocumentSource) -> ExtractedDocument {
let path = &source.path;
let uri = path.to_string_lossy().replace('\\', "/");
let ext = path
.extension()
.and_then(|e| e.to_str())
.unwrap_or("")
.to_ascii_lowercase();
let name = path
.file_name()
.and_then(|n| n.to_str())
.unwrap_or("")
.to_ascii_lowercase();
let format = source
.format_hint
.clone()
.unwrap_or_else(|| {
if name.ends_with(".mq.md") || ext == "md" {
"markdown".into()
} else if matches!(ext.as_str(), "txt" | "text") {
"text".into()
} else if matches!(ext.as_str(), "pdf" | "docx") {
ext.clone()
} else {
"unknown".into()
}
});
if matches!(
format.as_str(),
"pdf" | "docx" | "ocr" | "png" | "jpg" | "jpeg" | "webp" | "tiff"
) || matches!(ext.as_str(), "pdf" | "docx" | "png" | "jpg" | "jpeg" | "webp" | "tiff")
{
let kind = if matches!(format.as_str(), "ocr")
|| matches!(ext.as_str(), "png" | "jpg" | "jpeg" | "webp" | "tiff")
{
"ocr/image".to_string()
} else {
format.clone()
};
return ExtractedDocument {
source_uri: uri,
source_digest: String::new(),
format,
extractor_version: EXTRACTOR_VERSION.into(),
text: String::new(),
segments: vec![],
missing: vec!["full_document".into()],
diagnostics: vec![format!(
"format `{kind}` requires an external extractor plugin (not in core); incomplete extraction is explicit failure"
)],
status: "failed".into(),
};
}
let bytes = match fs::read(path) {
Ok(b) => b,
Err(e) => {
return ExtractedDocument {
source_uri: uri,
source_digest: String::new(),
format,
extractor_version: EXTRACTOR_VERSION.into(),
text: String::new(),
segments: vec![],
missing: vec!["full_document".into()],
diagnostics: vec![format!("read error: {e}")],
status: "failed".into(),
};
}
};
if bytes.is_empty() {
return ExtractedDocument {
source_uri: uri,
source_digest: digest_bytes(&bytes),
format,
extractor_version: EXTRACTOR_VERSION.into(),
text: String::new(),
segments: vec![],
missing: vec!["content".into()],
diagnostics: vec!["empty document".into()],
status: "failed".into(),
};
}
// Resource limit: refuse to fully buffer huge uploads as text (M01).
const MAX_EXTRACT_BYTES: usize = 8 << 20;
if bytes.len() > MAX_EXTRACT_BYTES {
let head = &bytes[..MAX_EXTRACT_BYTES];
let lossy = String::from_utf8_lossy(head).into_owned();
let mut doc = extract_markdown_or_text(&uri, &digest_bytes(&bytes), &format, &lossy);
doc.missing.push("tail_beyond_limit".into());
doc.diagnostics.push(format!(
"document truncated at {MAX_EXTRACT_BYTES} bytes (got {}); extraction is partial",
bytes.len()
));
doc.status = "partial".into();
return doc;
}
let text = match String::from_utf8(bytes.clone()) {
Ok(t) => t,
Err(e) => {
let lossy = String::from_utf8_lossy(&bytes).into_owned();
let mut doc = extract_markdown_or_text(&uri, &digest_bytes(&bytes), &format, &lossy);
doc.diagnostics
.push(format!("invalid utf-8 ({e}); decoded lossy"));
doc.status = if doc.text.is_empty() {
"failed".into()
} else {
"partial".into()
};
return doc;
}
};
extract_markdown_or_text(&uri, &digest_bytes(&bytes), &format, &text)
}
fn extract_markdown_or_text(
uri: &str,
digest: &str,
format: &str,
text: &str,
) -> ExtractedDocument {
let mut segments = Vec::new();
let mut n = 0u32;
for (i, line) in text.lines().enumerate() {
let line_no = i + 1;
if let Some(rest) = line.trim().strip_prefix('#') {
n += 1;
let heading = rest.trim_start_matches('#').trim();
segments.push(ExtractedSegment {
id: format!("seg-{n}"),
kind: "heading".into(),
text: heading.to_string(),
locator: format!("L{line_no}"),
confidence: 1.0,
});
} else if line.trim().starts_with('|') {
n += 1;
segments.push(ExtractedSegment {
id: format!("seg-{n}"),
kind: "table_row".into(),
text: line.to_string(),
locator: format!("L{line_no}"),
confidence: 0.9,
});
} else if !line.trim().is_empty() {
n += 1;
segments.push(ExtractedSegment {
id: format!("seg-{n}"),
kind: "paragraph".into(),
text: line.to_string(),
locator: format!("L{line_no}"),
confidence: 1.0,
});
}
}
ExtractedDocument {
source_uri: uri.to_string(),
source_digest: digest.to_string(),
format: format.to_string(),
extractor_version: EXTRACTOR_VERSION.into(),
text: text.to_string(),
segments,
missing: vec![],
diagnostics: vec![],
status: "ok".into(),
}
}
fn digest_bytes(bytes: &[u8]) -> String {
let mut h = Sha256::new();
h.update(bytes);
format!("sha256:{:x}", h.finalize())
}
/// Convenience for tests / CLI: extract if path exists.
pub fn extract_path(path: &Path) -> ExtractedDocument {
extract_document(&DocumentSource {
path: path.to_path_buf(),
format_hint: None,
})
}
#[cfg(test)]
mod tests {
use super::*;
use std::io::Write;
#[test]
fn extracts_markdown_headings() {
let dir = std::env::temp_dir().join(format!("mq-extract-{}", std::process::id()));
let _ = fs::create_dir_all(&dir);
let path = dir.join("note.md");
let mut f = fs::File::create(&path).unwrap();
writeln!(f, "# rate\n\nhello").unwrap();
let doc = extract_path(&path);
assert_eq!(doc.status, "ok");
assert!(doc.segments.iter().any(|s| s.kind == "heading" && s.text == "rate"));
let _ = fs::remove_dir_all(&dir);
}
#[test]
fn pdf_reports_missing_extractor() {
let doc = extract_document(&DocumentSource {
path: Path::new("x.pdf").into(),
format_hint: Some("pdf".into()),
});
assert_eq!(doc.status, "failed");
assert!(!doc.diagnostics.is_empty());
}
#[test]
fn ocr_image_reports_missing_extractor() {
let doc = extract_document(&DocumentSource {
path: Path::new("scan.png").into(),
format_hint: Some("ocr".into()),
});
assert_eq!(doc.status, "failed");
assert!(doc.missing.contains(&"full_document".into()));
assert!(doc.diagnostics.iter().any(|d| d.contains("ocr") || d.contains("extractor")));
}
}
+18
View File
@@ -460,6 +460,24 @@ unsafe extern "C" fn host_query(
let cap = crate::run_file_capture(&p, &opts).map_err(|e| e.to_string())?;
value_to_json(&cap.value)
})(),
// M04: plugins may drive MLSP artifact.bind/execute without inventing a second protocol.
"mlsp" => (|| {
let raw = args_owned.as_deref().unwrap_or("{}");
let args: serde_json::Value = serde_json::from_str(if raw.trim().is_empty() {
"{}"
} else {
raw
})
.map_err(|e| format!("mlsp args: {e}"))?;
let method = args
.get("method")
.and_then(|v| v.as_str())
.ok_or_else(|| "mlsp requires `method`".to_string())?;
let params = args.get("params").cloned().unwrap_or(serde_json::json!({}));
let line = serde_json::json!({"method": method, "params": params}).to_string();
let resp = crate::mlsp::handle_line(&line);
serde_json::from_str(&resp).map_err(|e| format!("mlsp response: {e}"))
})(),
other => Err(format!("host_query: unknown `{other}`")),
};
+156 -100
View File
@@ -15,7 +15,7 @@ use crate::builtin::{
};
use crate::debug::{emit_trace, DebugController};
use crate::diagnostics::{bail_at, Span};
use crate::host::{call_host, HostContext, HostFn};
use crate::host::{call_host, HostContext};
use crate::input_feed::InputFeed;
use crate::capture::{
BranchHit, CallFrame, LoopFrame, LoopHit, LoopIter, StmtEvent, StmtEventKind, ViewTrace,
@@ -349,6 +349,17 @@ impl Interpreter {
) -> Result<Value> {
let fun = find_function_anywhere(module, name)
.ok_or_else(|| self.err(format!("unknown function `{name}`")))?;
self.invoke_bound_function(module, fun, args)
}
/// Run an already-bound function node (SymbolId / source-line identity).
/// Prefer this over name lookup so nested same-named functions cannot drift (G07).
pub fn invoke_bound_function(
&mut self,
module: &Module,
fun: &Function,
args: &[(String, Value)],
) -> Result<Value> {
self.run_function(module, fun, Env::new(), args, false)
}
@@ -1169,34 +1180,150 @@ impl Interpreter {
return self.eval_method_call(module, fun, env, recv_name, &call.callee, &ev_args);
}
// Local-var method sugar (`a.b` when `a` is in env) before BoundCall path resolve.
if let Some(path) = &call.path {
// Bare dotted callee `a.b`: if `a` is a local variable, it is a method
// receiver (Python-style unified namespace); otherwise it's a library path.
if path.len() == 2 && env.get(&path[0]).is_some() {
if path.len() == 2
&& env.get(&path[0]).is_some()
&& !module.import_modules.contains_key(&path[0])
{
let recv = path[0].clone();
let method = path[1].clone();
return self.eval_method_call(module, fun, env, &recv, &method, &ev_args);
}
return self.eval_path_call(module, path, &ev_args);
}
if let Some(u) = module.uses.iter().find(|u| u.bind == call.callee) {
return self.eval_path_call(module, &u.path, &ev_args);
use crate::sema::bind::{resolve_for_exec, DynamicReason, ExecTarget};
match resolve_for_exec(module, fun, &call) {
ExecTarget::Local(target) => {
self.eval_bound_function_call(module, fun, env, target, &ev_args)
}
ExecTarget::Import {
lib: lib_mod,
fun: target,
..
} => self.eval_bound_function_call(lib_mod, fun, env, target, &ev_args),
ExecTarget::Builtin(name) => self.eval_builtin_call(name, &ev_args),
ExecTarget::Host(hf) => {
let mut params: Vec<String> =
hf.required_params().iter().map(|s| (*s).to_string()).collect();
for p in hf.optional_params() {
params.push((*p).to_string());
}
let bound = bind_args(&params, &ev_args, true).map_err(|m| self.err(m))?;
for req in hf.required_params() {
if !bound.contains_key(*req) {
return Err(self.err(format!("{} requires `{req}`", hf.name())));
}
}
call_host(&mut self.host, hf, &bound).map_err(|m| self.err(m))
}
ExecTarget::Dynamic {
reason: DynamicReason::CallFn,
..
} => {
let bound = bind_args(&["name".into()], &ev_args, false)
.map_err(|m| self.err(m))?;
let name = match bound.get("name") {
Some(Value::Text(s)) => s.as_str(),
_ => return Err(self.err("call_fn requires text name")),
};
let target = lookup_function(module, fun, name).ok_or_else(|| {
self.err(format!("call_fn: unknown function `{name}`"))
})?;
if !target.params.is_empty() {
return Err(self.err(format!(
"call_fn: `{name}` must have no parameters"
)));
}
self.run_function(module, target, Env::new(), &[], false)
}
ExecTarget::Dynamic {
reason: DynamicReason::Plugin,
name,
} => {
if let Some(reg) = self.host.plugins.get(&name).cloned() {
let bound =
bind_args(&reg.params, &ev_args, false).map_err(|m| self.err(m))?;
return self
.call_plugin_registered(&name, &bound)
.map_err(|m| self.err(m));
}
Err(self.err(format!("unknown function `{name}`")))
}
ExecTarget::Dynamic {
reason: DynamicReason::MethodReceiver,
name,
} => {
if let Some(path) = &call.path {
if path.len() == 2 && env.get(&path[0]).is_some() {
return self.eval_method_call(
module,
fun,
env,
&path[0],
&path[1],
&ev_args,
);
}
}
Err(self.err(format!("unresolved dynamic call `{name}`")))
}
ExecTarget::Unresolved { message, .. } => Err(self.err(message)),
}
}
match call.callee.as_str() {
/// Invoke a function already resolved via [`crate::sema::bind::resolve_for_exec`].
fn eval_bound_function_call(
&mut self,
module: &Module,
caller: &Function,
env: &mut Env,
target: &Function,
ev_args: &[EvArg],
) -> Result<Value> {
let bound =
bind_function_args(self, module, caller, env, &target.params, ev_args, false)
.map_err(|m| self.err(m))?;
if let Some(c) = &target.contract {
if let Some(d) = crate::contract::call_arg_diag(
c,
&target.name,
&bound,
self.path.as_deref(),
self.current_span,
) {
return Err(d.into());
}
}
let mut call_env = Env::new();
for (k, v) in bound {
call_env.set(k, v);
}
self.host.push_call_site_line(self.host.current_line);
let result = self.run_function(module, target, call_env, &[], false);
self.host.pop_call_site_line();
let result = result?;
if target.is_object() {
Ok(tag_instance(&target.name, result))
} else {
Ok(result)
}
}
fn eval_builtin_call(&mut self, name: &str, ev_args: &[EvArg]) -> Result<Value> {
match name {
"print" => {
let bound = bind_args(&["text".into()], &ev_args, false)
let bound = bind_args(&["text".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let text = bound
.get("text")
.map(|v| v.as_display())
.ok_or_else(|| self.err("print requires text (named or positional)"))?;
self.emit_line(&text);
return Ok(Value::None);
Ok(Value::None)
}
"input" => {
let bound = bind_args(&["prompt".into()], &ev_args, true)
let bound = bind_args(&["prompt".into()], ev_args, true)
.map_err(|m| self.err(m))?;
let prompt = bound
.get("prompt")
@@ -1221,52 +1348,52 @@ impl Interpreter {
e
}
})?;
return Ok(Value::Text(line));
Ok(Value::Text(line))
}
"len" => {
let bound = bind_args(&["value".into()], &ev_args, false)
let bound = bind_args(&["value".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let v = bound
.get("value")
.ok_or_else(|| self.err("len requires value"))?;
let n = builtin_len(v).map_err(|m| self.err(m))?;
return Ok(Value::Int(n));
Ok(Value::Int(n))
}
"str" => {
let bound = bind_args(&["value".into()], &ev_args, false)
let bound = bind_args(&["value".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let v = bound
.get("value")
.ok_or_else(|| self.err("str requires value"))?;
return Ok(builtin_str(v));
Ok(builtin_str(v))
}
"int" => {
let bound = bind_args(&["value".into()], &ev_args, false)
let bound = bind_args(&["value".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let v = bound
.get("value")
.ok_or_else(|| self.err("int requires value"))?;
let n = builtin_int(v).map_err(|m| self.err(m))?;
return Ok(Value::Int(n));
Ok(Value::Int(n))
}
"type" => {
let bound = bind_args(&["value".into()], &ev_args, false)
let bound = bind_args(&["value".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let v = bound
.get("value")
.ok_or_else(|| self.err("type requires value"))?;
return Ok(builtin_type(v));
Ok(builtin_type(v))
}
"trim" => {
let bound = bind_args(&["value".into()], &ev_args, false)
let bound = bind_args(&["value".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let v = bound
.get("value")
.ok_or_else(|| self.err("trim requires value"))?;
return builtin_trim(v).map_err(|m| self.err(m));
builtin_trim(v).map_err(|m| self.err(m))
}
"split" => {
let bound = bind_args(&["value".into(), "sep".into()], &ev_args, false)
let bound = bind_args(&["value".into(), "sep".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let value = bound
.get("value")
@@ -1274,10 +1401,10 @@ impl Interpreter {
let sep = bound
.get("sep")
.ok_or_else(|| self.err("split requires sep"))?;
return builtin_split(value, sep).map_err(|m| self.err(m));
builtin_split(value, sep).map_err(|m| self.err(m))
}
"join" => {
let bound = bind_args(&["value".into(), "sep".into()], &ev_args, false)
let bound = bind_args(&["value".into(), "sep".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let value = bound
.get("value")
@@ -1285,10 +1412,10 @@ impl Interpreter {
let sep = bound
.get("sep")
.ok_or_else(|| self.err("join requires sep"))?;
return builtin_join(value, sep).map_err(|m| self.err(m));
builtin_join(value, sep).map_err(|m| self.err(m))
}
"at" => {
let bound = bind_args(&["value".into(), "index".into()], &ev_args, false)
let bound = bind_args(&["value".into(), "index".into()], ev_args, false)
.map_err(|m| self.err(m))?;
let value = bound
.get("value")
@@ -1296,80 +1423,9 @@ impl Interpreter {
let index = bound
.get("index")
.ok_or_else(|| self.err("at requires index"))?;
return builtin_at(value, index).map_err(|m| self.err(m));
builtin_at(value, index).map_err(|m| self.err(m))
}
"call_fn" => {
let bound = bind_args(&["name".into()], &ev_args, false)
.map_err(|m| self.err(m))?;
let name = match bound.get("name") {
Some(Value::Text(s)) => s.as_str(),
_ => return Err(self.err("call_fn requires text name")),
};
let target = lookup_function(module, fun, name).ok_or_else(|| {
self.err(format!("call_fn: unknown function `{name}`"))
})?;
if !target.params.is_empty() {
return Err(self.err(format!(
"call_fn: `{name}` must have no parameters"
)));
}
return self.run_function(module, target, Env::new(), &[], false);
}
other if HostFn::from_name(other).is_some() => {
let hf = HostFn::from_name(other).unwrap();
let mut params: Vec<String> =
hf.required_params().iter().map(|s| (*s).to_string()).collect();
for p in hf.optional_params() {
params.push((*p).to_string());
}
let bound = bind_args(&params, &ev_args, true).map_err(|m| self.err(m))?;
for req in hf.required_params() {
if !bound.contains_key(*req) {
return Err(self.err(format!("{} requires `{req}`", hf.name())));
}
}
return call_host(&mut self.host, hf, &bound).map_err(|m| self.err(m));
}
_ => {}
}
if let Some(reg) = self.host.plugins.get(&call.callee).cloned() {
let bound = bind_args(&reg.params, &ev_args, false).map_err(|m| self.err(m))?;
return self
.call_plugin_registered(&call.callee, &bound)
.map_err(|m| self.err(m));
}
let target = lookup_function(module, fun, &call.callee)
.ok_or_else(|| self.err(format!("unknown function `{}`", call.callee)))?;
let bound = bind_function_args(self, module, fun, env, &target.params, &ev_args, false)
.map_err(|m| self.err(m))?;
// 契约边界 1(T2.2):调用实参 vs 形参契约。
if let Some(c) = &target.contract {
if let Some(d) = crate::contract::call_arg_diag(
c,
&target.name,
&bound,
self.path.as_deref(),
self.current_span,
) {
return Err(d.into());
}
}
let mut call_env = Env::new();
for (k, v) in bound {
call_env.set(k, v);
}
self.host.push_call_site_line(self.host.current_line);
let result = self.run_function(module, target, call_env, &[], false);
self.host.pop_call_site_line();
let result = result?;
if target.is_object() {
Ok(tag_instance(&target.name, result))
} else {
Ok(result)
other => Err(self.err(format!("unknown builtin `{other}`"))),
}
}
+68 -20
View File
@@ -17,9 +17,9 @@ pub struct KnowledgeOptions {
}
pub fn compile(opts: KnowledgeOptions) -> Result<KnowledgeGraph> {
// The semantic projection is the authoritative machine-facing graph. The
// older EKC catalog below remains intentionally available as a compatible
// human/retrieval projection, but never substitutes for semantic binding.
// Authoritative execution/binding graph: SemanticProject under `graph/`.
// Legacy EKC retrieval catalog writes only under `ekc/` and must never
// overwrite `graph/edges.json` (G01).
let semantic_root = if opts.path.is_file() {
opts.path.parent().unwrap_or_else(|| Path::new(".")).to_path_buf()
} else {
@@ -37,8 +37,9 @@ pub fn compile(opts: KnowledgeOptions) -> Result<KnowledgeGraph> {
};
let graph = extract_graph(&extract_opts)?;
write_projections(&opts.out_dir, &graph)?;
write_publish_manifest(&opts.out_dir, &semantic, &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 +49,63 @@ pub fn compile(opts: KnowledgeOptions) -> Result<KnowledgeGraph> {
Ok(graph)
}
/// M06: associate semantic generation, retrieval generation, and source digests.
fn write_publish_manifest(
out_dir: &Path,
semantic: &crate::sema::Compilation,
graph: &KnowledgeGraph,
) -> Result<()> {
let current = fs::read_to_string(out_dir.join("CURRENT")).unwrap_or_default();
let generation = current.trim().to_string();
let source_digest = {
use sha2::{Digest, Sha256};
let mut h = Sha256::new();
for a in &semantic.semantics.artifacts {
h.update(a.hashes.artifact.0.as_bytes());
}
format!("sha256:{:x}", h.finalize())
};
let evidence_digest = {
use sha2::{Digest, Sha256};
let mut h = Sha256::new();
for a in &semantic.semantics.artifacts {
h.update(a.hashes.evidence.0.as_bytes());
}
format!("sha256:{:x}", h.finalize())
};
let manifest = json!({
"schema_version": 1,
"kind": "publish_manifest",
"semantic_generation": generation,
"retrieval": {
"ekc_graph": "ekc/graph",
"modules": graph.modules.len(),
"symbols": graph.symbols.len(),
"capabilities": graph.capabilities.len(),
"knowledge": graph.knowledge.len(),
},
"source_digest": source_digest,
"evidence_digest": evidence_digest,
"excluded_dirs": crate::project::EXCLUDED_DIRS,
"project_id": semantic.semantics.project_id,
});
let path = out_dir.join("publish_manifest.json");
fs::write(&path, serde_json::to_string_pretty(&manifest)?)
.with_context(|| format!("write {}", path.display()))?;
Ok(())
}
/// 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 +191,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 +209,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 +279,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)?,
)?;
+2 -14
View File
@@ -164,13 +164,7 @@ fn collect_mq_md(
let p = entry.path();
if p.is_dir() {
let name = p.file_name().and_then(|s| s.to_str()).unwrap_or("");
if name == "target"
|| name == ".git"
|| name == "node_modules"
|| name == "docker"
|| name == "data"
|| name == ".cursor"
{
if crate::project::is_excluded_dir_name(name) {
continue;
}
if let Ok(canon) = p.canonicalize() {
@@ -210,13 +204,7 @@ fn walk_knowledge_md(
let p = entry.path();
if p.is_dir() {
let name = p.file_name().and_then(|s| s.to_str()).unwrap_or("");
if name == "target"
|| name == ".git"
|| name == ".marqdo"
|| name == "docker"
|| name == "data"
|| name == ".cursor"
{
if crate::project::is_excluded_dir_name(name) {
continue;
}
if let Ok(canon) = p.canonicalize() {
+3 -1
View File
@@ -52,7 +52,9 @@ pub fn find_stale(graph: &KnowledgeGraph, root: &Path) -> Vec<StaleItem> {
if src.exists() {
if let (Ok(meta), Ok(proj_meta)) = (
fs::metadata(&src),
fs::metadata(root.join(".marqdo/graph/graph.json"))
fs::metadata(root.join(".marqdo/ekc/graph/graph.json"))
.or_else(|_| fs::metadata(root.join(".marqdo/graph/graph.json")))
.or_else(|_| fs::metadata(root.join("ekc/graph/graph.json")))
.or_else(|_| fs::metadata(root.join("graph/graph.json"))),
) {
if let (Ok(st), Ok(pt)) = (meta.modified(), proj_meta.modified()) {
+1 -1
View File
@@ -20,7 +20,7 @@ pub mod preflight;
pub mod reuse;
pub mod util;
pub use compile::{compile, ensure_compiled, load_graph, KnowledgeOptions};
pub use compile::{compile, ekc_graph_dir, ensure_compiled, load_graph, KnowledgeOptions};
pub use duplicate::{find_duplicates, format_duplicates_text};
pub use find::{find, find_json, format_find_text};
pub use impact::{format_impact_text, impact, impact_json};
+22
View File
@@ -274,6 +274,25 @@ pub fn format_reuse_text(task: &str, result: &ReuseResult) -> String {
}
pub fn reuse_json(task: &str, result: &ReuseResult) -> Value {
let bind_required = matches!(
result.decision,
ReuseDecision::Reuse | ReuseDecision::Adapt
);
let mut bind_targets = Vec::new();
if let Some(sym) = &result.symbol {
bind_targets.push(json!({
"query": sym,
"via": "reuse.symbol",
"note": "pass query to artifact.bind then artifact.execute",
}));
}
if let Some(src) = &result.source {
bind_targets.push(json!({
"query": src,
"via": "reuse.source",
"note": "pass query to artifact.bind then artifact.execute",
}));
}
json!({
"task": task,
"decision": result.decision.as_str(),
@@ -287,6 +306,9 @@ pub fn reuse_json(task: &str, result: &ReuseResult) -> Value {
"constraints": result.constraints,
"decisions": result.decisions,
"failures": result.failures,
"discovery_only": true,
"bind_required": bind_required,
"bind_targets": bind_targets,
"candidates": result.candidates.iter().map(|c| json!({
"id": c.id,
"kind": c.kind,
+1
View File
@@ -21,6 +21,7 @@ pub mod check;
pub mod contract;
pub mod debug;
pub mod diagnostics;
pub mod document_extract;
pub mod embedded_lib;
#[cfg(feature = "cli")]
pub mod ext_cli;
+96 -7
View File
@@ -323,6 +323,10 @@ enum Commands {
#[arg(long)]
json: bool,
/// Exit non-zero when conflicts found (CI gate; default remains report-only)
#[arg(long)]
fail: bool,
},
/// List stale / deprecated / superseded knowledge
Stale {
@@ -334,6 +338,10 @@ enum Commands {
#[arg(long)]
json: bool,
/// Exit non-zero when stale items found (CI gate; default remains report-only)
#[arg(long)]
fail: bool,
},
/// Detect duplicate capabilities via symbol fingerprints
Duplicate {
@@ -353,7 +361,7 @@ enum Commands {
#[arg(long)]
json: bool,
},
/// Verify code ↔ knowledge consistency
/// Verify code ↔ knowledge consistency (EKC structural; exit 1 only on errors)
Verify {
#[arg(value_name = "PATH")]
path: Option<PathBuf>,
@@ -363,6 +371,10 @@ enum Commands {
#[arg(long)]
json: bool,
/// Also fail on warnings (does not change default success-when-no-errors)
#[arg(long)]
fail_on_warning: bool,
},
/// Official extension installer (`list` / `add` / `remove`)
Ext {
@@ -415,6 +427,18 @@ enum KnowledgeAction {
#[arg(value_name = "SYMBOL_OR_PATH")]
query: String,
},
/// Machine adjudication of semantic artifacts (M03): may_bind / may_publish
Adjudicate {
/// Artifact id, symbol id, or display name (omit to report all functions)
#[arg(value_name = "ARTIFACT")]
artifact: Option<String>,
/// Policy: pure | business | static
#[arg(long, default_value = "business")]
policy: String,
/// Exit 1 when any reported artifact has may_bind=false
#[arg(long)]
fail: bool,
},
/// Run engineering preflight for a task
Preflight {
#[arg(value_name = "TASK")]
@@ -1324,6 +1348,51 @@ fn try_main(cli: Cli) -> Result<i32> {
1
})
}
KnowledgeAction::Adjudicate {
artifact,
policy,
fail,
} => {
let semantic_root = if path.is_file() {
path.parent()
.unwrap_or_else(|| std::path::Path::new("."))
.to_path_buf()
} else {
path.clone()
};
let report = marqdo::mlsp::adjudicate_project(
&semantic_root,
artifact.as_deref(),
&policy,
)
.map_err(|e| anyhow::anyhow!("{}", e))?;
if json {
println!("{report}");
} else {
println!(
"knowledge adjudicate policy={} may_bind_all={} count={}",
policy,
report["may_bind_all"],
report["count"]
);
for item in report["reports"].as_array().into_iter().flatten() {
println!(
" {} evidence={} may_bind={} may_publish={}",
item["artifact_id"].as_str().unwrap_or(""),
item["verification"]["evidence"].as_str().unwrap_or(""),
item["may_bind"],
item["may_publish"]
);
}
}
Ok(
if fail && report["may_bind_all"].as_bool() != Some(true) {
1
} else {
0
},
)
}
KnowledgeAction::Preflight {
task,
min_candidates,
@@ -1462,7 +1531,12 @@ fn try_main(cli: Cli) -> Result<i32> {
}
Ok(0)
}
Commands::Conflicts { path, out, json } => {
Commands::Conflicts {
path,
out,
json,
fail,
} => {
let path = path.unwrap_or_else(|| PathBuf::from("."));
let graph = ensure_compiled(&path, &out)?;
let items = find_conflicts(&graph);
@@ -1471,9 +1545,14 @@ fn try_main(cli: Cli) -> Result<i32> {
} else {
print!("{}", format_conflicts_text(&items));
}
Ok(0)
Ok(if fail && !items.is_empty() { 1 } else { 0 })
}
Commands::Stale { path, out, json } => {
Commands::Stale {
path,
out,
json,
fail,
} => {
let path = path.unwrap_or_else(|| PathBuf::from("."));
let graph = ensure_compiled(&path, &out)?;
let items = find_stale(&graph, &path);
@@ -1482,7 +1561,7 @@ fn try_main(cli: Cli) -> Result<i32> {
} else {
print!("{}", format_stale_text(&items));
}
Ok(0)
Ok(if fail && !items.is_empty() { 1 } else { 0 })
}
Commands::Duplicate {
path,
@@ -1517,7 +1596,12 @@ fn try_main(cli: Cli) -> Result<i32> {
Ok(0)
}
}
Commands::Verify { path, out, json } => {
Commands::Verify {
path,
out,
json,
fail_on_warning,
} => {
let path = path.unwrap_or_else(|| PathBuf::from("."));
let graph = ensure_compiled(&path, &out)?;
let issues = verify(&graph);
@@ -1527,7 +1611,12 @@ fn try_main(cli: Cli) -> Result<i32> {
print!("{}", format_verify_text(&issues));
}
let errors = issues.iter().filter(|i| i.severity == "error").count();
Ok(if errors > 0 { 1 } else { 0 })
let warnings = issues.iter().filter(|i| i.severity == "warning").count();
Ok(if errors > 0 || (fail_on_warning && warnings > 0) {
1
} else {
0
})
}
Commands::Ext { action } => {
match action {
+588 -11
View File
@@ -64,17 +64,45 @@ fn dispatch(req: &Value) -> Result<Value, Value> {
Some("artifact.impact") => artifact_impact(&params),
Some("artifact.bind") => artifact_bind(&params),
Some("artifact.execute") => artifact_execute(&params),
Some("artifact.reuse_execute") => artifact_reuse_execute(&params),
Some("document.extract") => document_extract(&params),
Some("artifact.patch") => artifact_patch(&params),
Some("artifact.extract_pure") => artifact_extract_pure(&params),
// `<TAB>` M9: occlusion label search (two-tier vocabulary).
Some("labels.search") => labels_search(&params),
// `<TAB>` M6: one-shot session summary (T1 staleness seen/fixed).
Some("session.summary") => session_summary(),
other => Err(err(
"mlsp.unknown_method",
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute"),
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute / artifact.reuse_execute / artifact.patch / artifact.extract_pure / document.extract"),
)),
}
}
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
@@ -103,6 +131,22 @@ fn artifact_query<'a>(project: &'a crate::sema::SemanticProject, query: &str) ->
}).collect()
}
fn document_extract(params: &Value) -> Result<Value, Value> {
let path = params
.get("path")
.and_then(Value::as_str)
.ok_or_else(|| err("mlsp.bad_request", "document.extract 需要 path"))?;
let hint = params
.get("format")
.and_then(Value::as_str)
.map(|s| s.to_string());
let doc = crate::document_extract::extract_document(&crate::document_extract::DocumentSource {
path: PathBuf::from(path),
format_hint: hint,
});
Ok(doc.to_json())
}
fn artifact_find(params: &Value) -> Result<Value, Value> {
let compilation = semantic_project(params)?;
let query = params.get("query").and_then(Value::as_str).unwrap_or("").to_ascii_lowercase();
@@ -147,10 +191,216 @@ fn artifact_verify(params: &Value) -> Result<Value, Value> {
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 artifact = candidates[0];
let mut record = crate::sema::artifact_json(artifact)["verification"].clone();
record["policy"] = params.get("policy").cloned().unwrap_or_else(|| json!("static"));
record["artifact_id"] = json!(artifact.artifact_id.0);
Ok(record)
let policy = params.get("policy").and_then(Value::as_str).unwrap_or("static");
Ok(build_verification_report(artifact, policy))
}
/// CLI / product machine adjudication over semantic artifacts (M03).
pub fn adjudicate_project(project: &std::path::Path, artifact: Option<&str>, policy: &str) -> Result<Value, Value> {
let compilation = semantic_project(&json!({"project": project}))?;
let targets: Vec<&crate::sema::SemanticArtifact> = if let Some(q) = artifact {
let c = artifact_query(&compilation.semantics, q);
if c.is_empty() {
return Err(err("artifact.unresolved", format!("没有制品 `{q}`")));
}
c
} else {
compilation
.semantics
.artifacts
.iter()
.filter(|a| a.kind == "function")
.collect()
};
let reports: Vec<Value> = targets
.iter()
.map(|a| build_verification_report(a, policy))
.collect();
let any_denied = reports.iter().any(|r| r["may_bind"] == false);
Ok(json!({
"schema_version": 1,
"policy": policy,
"count": reports.len(),
"may_bind_all": !any_denied,
"reports": reports,
}))
}
/// Known bind/verify policies (M03). Unknown strings are rejected.
fn parse_policy(policy: &str) -> Result<&str, Value> {
match policy {
"pure" | "business" | "static" => Ok(policy),
other => Err(json!({
"code": "artifact.unknown_policy",
"message": format!("未知政策 `{other}`;允许 pure / business / static"),
"policy": other,
})),
}
}
fn evidence_allows_business(status: &str) -> bool {
matches!(status, "sourced" | "verified")
}
fn build_verification_report(artifact: &crate::sema::SemanticArtifact, policy: &str) -> Value {
let policy = match parse_policy(policy) {
Ok(p) => p,
Err(e) => {
return json!({
"schema_version": 1,
"artifact_id": artifact.artifact_id.0,
"policy": policy,
"checks": {},
"blockers": [e],
"may_bind": false,
"may_publish": false,
"verification": crate::sema::artifact_json(artifact)["verification"].clone(),
});
}
};
let region_status = if artifact.applicability.contains("region=") {
"declared"
} else {
"unknown"
};
let checks = json!({
"parse": {"status": artifact.verification.parse, "detail": "static_project_compile"},
"resolve": {"status": artifact.verification.resolve, "detail": "symbol_bound"},
"contract": {"status": artifact.verification.contract, "detail": "not_executed_by_verify"},
"execution": {"status": artifact.verification.execution, "detail": "not_run"},
"tests": {"status": artifact.verification.tests, "detail": "no_test_runner_invoked"},
"evidence": {"status": artifact.verification.evidence, "detail": "compile_time_provenance"},
"domain": {"status": artifact.verification.domain, "detail": "unreviewed"},
"region": {"status": region_status, "detail": "input_domain_not_checked"},
"input_domain": {"status": "unknown", "detail": "not_checked_by_static_verify"},
});
let mut blockers = Vec::new();
// Never upgrade tests/execution to passed without a runner (M03).
if matches!(
artifact.verification.tests.as_str(),
"passed" | "verified"
) && artifact
.verification
.methods
.iter()
.all(|m| m == "static_project_compile")
{
blockers.push(json!({
"code": "artifact.tests_unproven",
"check": "tests",
"status": artifact.verification.tests,
"detail": "static compile must not claim tests passed",
}));
}
if policy == "business" && !evidence_allows_business(&artifact.verification.evidence) {
blockers.push(json!({
"code": "artifact.evidence_denied",
"check": "evidence",
"status": artifact.verification.evidence,
}));
}
if policy == "pure"
&& artifact
.effects
.values()
.iter()
.any(|e| e != "pure")
{
blockers.push(json!({
"code": "artifact.effect_denied",
"check": "effects",
"effects": artifact.effects.values(),
}));
}
let may_bind = blockers.is_empty()
&& match policy {
"business" => evidence_allows_business(&artifact.verification.evidence),
"pure" => artifact.effects.values().iter().all(|e| e == "pure"),
_ => true,
};
// Publish requires stronger evidence than bind; static verify never claims tests passed.
let may_publish = may_bind
&& artifact.verification.tests != "unknown"
&& artifact.verification.tests != "not_run"
&& artifact.verification.execution != "not_run"
&& !matches!(
artifact.verification.evidence.as_str(),
"unverified" | "missing_source" | "anchor_missing" | "expired" | "invalid_date"
);
json!({
"schema_version": 1,
"artifact_id": artifact.artifact_id.0,
"symbol_id": artifact.symbol_id.as_ref().map(|id| id.as_str()),
"digest": artifact.hashes.artifact.0,
"evidence_digest": artifact.hashes.evidence.0,
"closure_digest": artifact.hashes.closure.0,
"policy": policy,
"checks": checks,
"blockers": blockers,
"may_bind": may_bind,
"may_publish": may_publish,
"verification": {
"parse": artifact.verification.parse,
"resolve": artifact.verification.resolve,
"contract": artifact.verification.contract,
"execution": artifact.verification.execution,
"tests": artifact.verification.tests,
"evidence": artifact.verification.evidence,
"domain": artifact.verification.domain,
"methods": artifact.verification.methods,
},
})
}
/// M04: bind then execute in one call (actual reuse, not discovery scores).
fn artifact_reuse_execute(params: &Value) -> Result<Value, Value> {
let project = params
.get("project")
.or_else(|| params.get("path"))
.cloned()
.ok_or_else(|| err("mlsp.bad_request", "artifact.reuse_execute 需要 project"))?;
let query = params
.get("artifact_id")
.or_else(|| params.get("symbol_id"))
.or_else(|| params.get("query"))
.and_then(Value::as_str)
.ok_or_else(|| err("mlsp.bad_request", "artifact.reuse_execute 需要 artifact_id"))?;
let policy = params.get("policy").and_then(Value::as_str).unwrap_or("pure");
let inputs = params.get("inputs").cloned().unwrap_or(json!({}));
let bound = artifact_bind(&json!({
"project": project,
"artifact_id": query,
"policy": policy,
"expected_digest": params.get("expected_digest"),
}))?;
let handle = bound
.get("handle")
.cloned()
.ok_or_else(|| err("artifact.bind_failed", "bind 未返回 handle"))?;
let executed = artifact_execute(&json!({
"handle": handle,
"inputs": inputs,
"allow_effects": params.get("allow_effects"),
}))?;
Ok(json!({
"schema_version": 1,
"actual_reuse": true,
"discovery_only": false,
"artifact_id": executed.get("artifact_id"),
"symbol_id": executed.get("symbol_id"),
"digest": executed.get("digest"),
"result": executed.get("result"),
"stdout": executed.get("stdout"),
"effects": executed.get("effects"),
"trace": {
"artifact_id": executed.get("artifact_id"),
"symbol_id": executed.get("symbol_id"),
"digest": executed.get("digest"),
"inputs": inputs,
"value": executed.get("result"),
"stdout": executed.get("stdout"),
},
}))
}
fn artifact_impact(params: &Value) -> Result<Value, Value> {
@@ -171,7 +421,208 @@ 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 = parse_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" && !evidence_allows_business(&artifact.verification.evidence) {
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());
let valid_until = artifact
.applicability
.split(';')
.find_map(|part| {
part.trim()
.strip_prefix("valid_until=")
.map(|s| s.trim().to_string())
});
let provenance_digests: Vec<Value> = artifact
.provenance
.iter()
.filter(|p| p.relation == "supports")
.map(|p| {
json!({
"uri": p.uri,
"locator": p.locator,
"content_digest": p.content_digest.as_ref().map(|d| &d.0),
})
})
.collect();
Ok(json!({"schema_version":1,"handle":{
"artifact_id": artifact.artifact_id.0,
"symbol_id": symbol_id,
"digest": artifact.hashes.artifact.0,
"closure_digest": artifact.hashes.closure.0,
"evidence_digest": artifact.hashes.evidence.0,
"project": compilation.semantics.root,
"policy": policy,
"effects": effects,
"evidence": artifact.verification.evidence,
"valid_until": valid_until,
"provenance": provenance_digests,
"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> {
@@ -183,7 +634,76 @@ fn artifact_execute(params: &Value) -> Result<Value, Value> {
let candidates = artifact_query(&compilation.semantics, artifact_id);
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 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_closure) = handle.get("closure_digest").and_then(Value::as_str) {
if bound_closure != artifact.hashes.closure.0 {
return Err(json!({
"code": "artifact.stale_handle",
"message": "依赖闭包已改变;拒绝执行过期 handle",
"expected": bound_closure,
"actual": artifact.hashes.closure.0,
}));
}
}
if let Some(bound_evidence) = handle.get("evidence_digest").and_then(Value::as_str) {
if bound_evidence != artifact.hashes.evidence.0 {
return Err(json!({
"code": "artifact.stale_handle",
"message": "来源证据摘要已改变;拒绝执行过期 handle",
"expected": bound_evidence,
"actual": artifact.hashes.evidence.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,
}));
}
}
// Re-check policy at execute time (M02) — do not trust bind-time evidence string alone.
let policy = handle.get("policy").and_then(Value::as_str).unwrap_or("pure");
let _ = parse_policy(policy)?;
if policy == "business" && !evidence_allows_business(&artifact.verification.evidence) {
return Err(json!({
"code": "artifact.evidence_denied",
"message": "business 句柄在执行时证据状态不足(来源缺失、锚点失效或已过期)",
"policy": policy,
"evidence": artifact.verification.evidence,
}));
}
if policy == "pure"
&& artifact
.effects
.values()
.iter()
.any(|effect| effect != "pure")
{
return Err(json!({
"code": "artifact.effect_denied",
"message": "pure 句柄在执行时出现非纯效应",
"policy": policy,
"effects": artifact.effects.values(),
}));
}
if let Some(until) = handle.get("valid_until").and_then(Value::as_str) {
if crate::sema::provenance::valid_until_expired(until) {
return Err(json!({
"code": "artifact.expired",
"message": "句柄适用期已过",
"valid_until": until,
}));
}
}
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 +717,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 +1212,32 @@ mod tests {
let candidate = found["candidates"].as_array().unwrap().iter().find(|v| v["kind"] == "function").unwrap();
let id = candidate["artifact_id"].as_str().unwrap();
let bound = dispatch(&json!({"method":"artifact.bind","params":{"project":root,"artifact_id":id}})).unwrap();
let handle = bound["handle"].clone();
let handle = &bound["handle"];
assert!(handle.get("symbol_id").and_then(|v| v.as_str()).is_some());
assert!(handle.get("source").is_some());
let result = dispatch(&json!({"method":"artifact.execute","params":{"handle":handle,"inputs":{"x":4}}})).unwrap();
assert_eq!(result["result"], 5);
assert_eq!(result["symbol_id"], handle["symbol_id"]);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn artifact_bind_rejects_non_pure_under_pure_policy() {
let stamp = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos();
let root = std::env::temp_dir().join(format!("marqdo-mlsp-effect-{stamp}"));
fs::create_dir_all(&root).unwrap();
fs::write(
root.join("main.mq.md"),
"# main\n\n## save\n\n> fs.write_text path=t.txt text=x\n\n*1*\n",
)
.unwrap();
let found = dispatch(&json!({"method":"artifact.find","params":{"project":root,"query":"save"}})).unwrap();
let id = found["candidates"].as_array().unwrap().iter().find(|v| v["kind"] == "function").unwrap()["artifact_id"]
.as_str()
.unwrap();
let err = dispatch(&json!({"method":"artifact.bind","params":{"project":root,"artifact_id":id,"policy":"pure"}}))
.unwrap_err();
assert_eq!(err["code"], "artifact.effect_denied");
fs::remove_dir_all(root).unwrap();
}
+4 -1
View File
@@ -7,7 +7,10 @@ pub use expr::{
parse_call_after_gt, parse_call_arg_value, parse_expr, parse_expr_prefer_var,
parse_value_or_interp,
};
pub use prose::{scan_prose_line, ProseBit};
pub use prose::{
classify_narrative_target, scan_md_links_in_line, scan_narrative_links, scan_prose_line,
NarrativeLink, NarrativeLinkKind, ProseBit,
};
use anyhow::{bail, Result};
+186 -1
View File
@@ -2,8 +2,11 @@
//!
//! Soft Markdown emphasis that does not look like code/return is skipped (G2 —
//! [code-as-docs-gaps.md](../../../doc/design/code-as-docs-gaps.md)).
//!
//! Comment-line Markdown links `[label](target)` are NarrativeRef / navigation
//! sites (G03); they are never executed.
use crate::lex::{matching_bold_close_inline, matching_italic_close_inline};
use crate::lex::{matching_bold_close_inline, matching_italic_close_inline, LineKind};
pub use crate::lex::looks_like_bold_code;
@@ -22,6 +25,162 @@ pub enum ProseBit {
ItalicReturn { inner: String, at: usize },
}
/// Why a comment-line `[]()` is not an executable BoundCall (G03).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NarrativeLinkKind {
/// In-project symbol / binding / `#anchor` — inert explanation.
Narrate,
/// URL or file path — navigation only; never fetched by compile/run.
Navigation,
}
impl NarrativeLinkKind {
pub fn as_str(self) -> &'static str {
match self {
Self::Narrate => "narrate",
Self::Navigation => "navigation",
}
}
}
/// One Markdown link found on a comment (narrative) line.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NarrativeLink {
pub label: String,
pub target: String,
pub kind: NarrativeLinkKind,
/// 1-based source line.
pub line: u32,
pub at: usize,
}
/// Classify a link target without parsing it as an expression.
pub fn classify_narrative_target(target: &str) -> NarrativeLinkKind {
let t = target.trim();
if t.starts_with("http://")
|| t.starts_with("https://")
|| t.starts_with("mailto:")
|| t.starts_with("//")
{
return NarrativeLinkKind::Navigation;
}
if t.contains('/') || t.ends_with(".md") || t.ends_with(".mq.md") || t.ends_with(".html")
{
return NarrativeLinkKind::Navigation;
}
NarrativeLinkKind::Narrate
}
/// Scan whole-source comment lines for Markdown links; skip fences and code lines.
pub fn scan_narrative_links(source: &str) -> Vec<NarrativeLink> {
let classified = crate::lex::classify_source(source);
let mut out = Vec::new();
let mut in_fence = false;
for (i, cl) in classified.iter().enumerate() {
let line_no = (i + 1) as u32;
let trimmed = cl.text.trim();
if trimmed.starts_with("```") {
in_fence = !in_fence;
continue;
}
if in_fence {
continue;
}
if cl.kind != LineKind::Comment {
continue;
}
out.extend(scan_md_links_in_line(&cl.text, line_no));
}
out
}
/// Scan one line for `[label](target)`, skipping `` `inline` `` spans.
pub fn scan_md_links_in_line(line: &str, line_no: u32) -> Vec<NarrativeLink> {
let bytes = line.as_bytes();
let mut i = 0usize;
let mut out = Vec::new();
while i < bytes.len() {
if bytes[i] == b'`' {
if let Some(rel) = line[i + 1..].find('`') {
i = i + 1 + rel + 1;
continue;
}
i += 1;
continue;
}
if bytes[i] != b'[' {
i += 1;
continue;
}
let Some((label, target, next)) = parse_md_link(line, i) else {
i += 1;
continue;
};
let kind = classify_narrative_target(&target);
out.push(NarrativeLink {
label,
target,
kind,
line: line_no,
at: i,
});
i = next;
}
out
}
fn parse_md_link(line: &str, start: usize) -> Option<(String, String, usize)> {
if !line[start..].starts_with('[') {
return None;
}
let mut depth = 0i32;
let mut label_end = None;
for (rel, ch) in line[start..].char_indices() {
match ch {
'[' => depth += 1,
']' => {
depth -= 1;
if depth == 0 {
label_end = Some(start + rel);
break;
}
}
_ => {}
}
}
let label_end = label_end?;
let after = line.get(label_end + 1..)?;
if !after.starts_with('(') {
return None;
}
let mut depth = 0i32;
let mut target_end = None;
for (rel, ch) in after.char_indices() {
match ch {
'(' => depth += 1,
')' => {
depth -= 1;
if depth == 0 {
target_end = Some(rel);
break;
}
}
_ => {}
}
}
let target_end = target_end?;
let label = line[start + 1..label_end].to_string();
let target = after[1..target_end].trim().to_string();
if label.is_empty() || target.is_empty() {
return None;
}
// Executable occlusion payloads look like calls (`foo(…)` / `a.b(…)`); those
// live on Code lines already. If a comment link target is expression-shaped
// with `(`, still treat as narrate/navigation by target class — do not eval.
let next = label_end + 1 + target_end + 1;
Some((label, target, next))
}
/// Scan a narrative (or mixed) line for v0.3 inline bits, left to right.
pub fn scan_prose_line(line: &str) -> Vec<ProseBit> {
let bytes = line.as_bytes();
@@ -255,4 +414,30 @@ mod tests {
"glob-like ticks must not yield italic: {bits:?}"
);
}
#[test]
fn narrative_links_skip_fence_and_classify() {
let src = "---\nmarkup: occlusion\n---\n\n# main\n\n见[文档](https://example.com/a)与[总额](总额)。\n\n```\n[ignored](https://x.test)\n```\n\n行内跳过 `[not](x)` 标记。\n";
let links = scan_narrative_links(src);
assert!(
links.iter().any(|l| {
l.kind == NarrativeLinkKind::Navigation && l.target.contains("example.com")
}),
"{links:?}"
);
assert!(
links
.iter()
.any(|l| l.kind == NarrativeLinkKind::Narrate && l.target == "总额"),
"{links:?}"
);
assert!(
!links.iter().any(|l| l.target.contains("x.test")),
"fenced link must not become a step: {links:?}"
);
assert!(
!links.iter().any(|l| l.target == "x"),
"inline-code link must not become a step: {links:?}"
);
}
}
+64 -5
View File
@@ -72,16 +72,42 @@ impl ProjectRoot {
}
}
const EXCLUDED_DIRS: &[&str] = &[
/// Shared with EKC extract (M06): authored sources never include corpus/runtime bags.
pub const EXCLUDED_DIRS: &[&str] = &[
".git",
".marqdo",
"target",
"node_modules",
".cursor",
".agents",
"data",
"docker",
"drafts",
"candidates",
"corpus",
];
/// True when a directory basename is outside the authored source scan.
pub fn is_excluded_dir_name(name: &str) -> bool {
EXCLUDED_DIRS.iter().any(|excluded| name == *excluded)
}
/// 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 +126,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 +137,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 +218,20 @@ mod tests {
fs::remove_dir_all(root).unwrap();
}
#[test]
fn oversized_source_is_diagnosed() {
let root = fixture_root("too-large");
let big = "x".repeat((MAX_SOURCE_FILE_BYTES as usize) + 8);
fs::write(root.join("big.mq.md"), format!("# main\n\n{big}\n")).unwrap();
let project = ProjectRoot::new(&root).unwrap();
let err = project.source_files().unwrap_err().to_string();
assert!(
err.contains("project.scan_file_too_large"),
"expected size diagnostic, got {err}"
);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn nearest_marker_wins() {
let root = fixture_root("discover");
+241
View File
@@ -0,0 +1,241 @@
//! Shared call binding for execution (G02 BoundCall).
//!
//! Tree and Bytecode must agree: explicit import paths and same-module bare
//! names bind; bare names never silently pick an imported symbol; true
//! dynamics are marked separately.
use crate::ast::{CallExpr, Function, Module};
use crate::diagnostics::Span;
use crate::host::HostFn;
/// Why a call site is not a static BoundCall.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DynamicReason {
MethodReceiver,
CallFn,
Plugin,
}
impl DynamicReason {
pub fn as_str(self) -> &'static str {
match self {
Self::MethodReceiver => "method_receiver",
Self::CallFn => "call_fn",
Self::Plugin => "plugin",
}
}
}
/// Runtime resolution shared by Tree (and mirrored by Bytecode rules).
#[derive(Debug)]
pub enum ExecTarget<'a> {
/// Function in the calling module (or nested children).
Local(&'a Function),
/// `bind.member…` through `module.import_modules`.
Import {
bind: String,
lib: &'a Module,
fun: &'a Function,
path: Vec<String>,
},
Builtin(&'static str),
Host(HostFn),
/// Plugin / method / call_fn — not a static BoundCall.
Dynamic {
reason: DynamicReason,
name: String,
},
Unresolved {
message: String,
#[allow(dead_code)]
span_hint: Option<Span>,
},
}
pub fn call_display(call: &CallExpr) -> String {
if let Some(path) = &call.path {
return path.join(".");
}
if let Some(recv) = &call.receiver {
return format!("{recv}.{}", call.callee);
}
call.callee.clone()
}
fn find_in_children<'a>(fun: &'a Function, name: &str) -> Option<&'a Function> {
for child in &fun.children {
if child.name == name {
return Some(child);
}
if let Some(f) = find_in_children(child, name) {
return Some(f);
}
}
None
}
/// Same-module bare-name lookup (never searches imports).
pub fn lookup_local<'a>(
module: &'a Module,
current: &'a Function,
name: &str,
) -> Option<&'a Function> {
if let Some(f) = find_in_children(current, name) {
return Some(f);
}
module.functions.iter().find(|f| f.name == name)
}
fn walk_path<'a>(lib: &'a Module, path: &[String]) -> Result<&'a Function, String> {
let display = path.join(".");
if path.is_empty() {
return Err("empty knowledge path".into());
}
let mut parent_is_object = false;
let mut node = lib
.functions
.iter()
.find(|f| f.name == path[0])
.ok_or_else(|| format!("unknown `{display}`"))?;
for seg in &path[1..] {
parent_is_object = node.is_object();
node = node
.children
.iter()
.find(|c| c.name == *seg)
.ok_or_else(|| format!("unknown `{display}`"))?;
}
if parent_is_object && node.level != 1 && crate::ast::function_uses_receiver(node) {
return Err(format!(
"`{display}` is an instance method; call it as `var`.{}",
node.name
));
}
Ok(node)
}
fn resolve_import_path<'a>(module: &'a Module, path: &[String]) -> ExecTarget<'a> {
let display = path.join(".");
if path.len() < 2 {
return ExecTarget::Unresolved {
message: format!("library path `{display}`: need at least `lib.member`"),
span_hint: None,
};
}
let bind = &path[0];
let Some(lib) = module.import_modules.get(bind) else {
return ExecTarget::Unresolved {
message: format!("unknown library `{bind}` (import it in frontmatter)"),
span_hint: None,
};
};
match walk_path(lib, &path[1..]) {
Ok(fun) => ExecTarget::Import {
bind: bind.clone(),
lib,
fun,
path: path.to_vec(),
},
Err(message) => ExecTarget::Unresolved {
message,
span_hint: None,
},
}
}
/// Resolve a call for execution. Import bare-name leakage is forbidden (G02).
pub fn resolve_for_exec<'a>(
module: &'a Module,
current: &'a Function,
call: &CallExpr,
) -> ExecTarget<'a> {
if call.receiver.is_some() {
return ExecTarget::Dynamic {
reason: DynamicReason::MethodReceiver,
name: call_display(call),
};
}
if let Some(path) = &call.path {
if module.import_modules.contains_key(&path[0]) {
return resolve_import_path(module, path);
}
// Same-module definition-tree path (`Type.member` / nested), BoundCall.
if path.len() >= 2 {
match walk_path(module, path) {
Ok(fun) => return ExecTarget::Local(fun),
Err(_) if path.len() == 2 => {
// Possible local-variable method; caller checks env.
return ExecTarget::Dynamic {
reason: DynamicReason::MethodReceiver,
name: call_display(call),
};
}
Err(message) => {
return ExecTarget::Unresolved {
message,
span_hint: None,
};
}
}
}
return ExecTarget::Unresolved {
message: format!(
"library path `{}`: need at least `lib.member`",
path.join(".")
),
span_hint: None,
};
}
if let Some(u) = module.uses.iter().find(|u| u.bind == call.callee) {
return resolve_import_path(module, &u.path);
}
match call.callee.as_str() {
"print" | "input" | "len" | "str" | "int" | "type" | "trim" | "split" | "join" | "at" => {
return ExecTarget::Builtin(match call.callee.as_str() {
"print" => "print",
"input" => "input",
"len" => "len",
"str" => "str",
"int" => "int",
"type" => "type",
"trim" => "trim",
"split" => "split",
"join" => "join",
"at" => "at",
_ => unreachable!(),
});
}
"call_fn" => {
return ExecTarget::Dynamic {
reason: DynamicReason::CallFn,
name: "call_fn".into(),
};
}
other if HostFn::from_name(other).is_some() => {
return ExecTarget::Host(HostFn::from_name(other).unwrap());
}
_ => {}
}
if let Some(fun) = lookup_local(module, current, &call.callee) {
return ExecTarget::Local(fun);
}
ExecTarget::Dynamic {
reason: DynamicReason::Plugin,
name: call.callee.clone(),
}
}
pub fn is_static_bound(target: &ExecTarget<'_>) -> bool {
matches!(
target,
ExecTarget::Local(_)
| ExecTarget::Import { .. }
| ExecTarget::Builtin(_)
| ExecTarget::Host(_)
)
}
+150
View File
@@ -0,0 +1,150 @@
//! Restricted pure-expression extract (S3).
//!
//! Only Literal / Var / Unary / Binary / List / Map / Index payloads may be
//! lifted. Calls, host, and plugins are refused so effect counts stay zero.
use std::collections::BTreeSet;
use crate::ast::Expr;
use crate::parse::expr::parse_expr_prefer_var;
#[derive(Debug, Clone)]
pub struct ExtractPlan {
pub name: String,
pub params: Vec<String>,
pub expression: String,
pub heading: String,
pub call: String,
}
#[derive(Debug, Clone)]
pub struct ExtractError {
pub code: &'static str,
pub message: String,
}
/// Build an extract plan from a pure expression string (no file I/O).
pub fn plan_pure_extract(name: &str, expression: &str) -> Result<ExtractPlan, ExtractError> {
let name = name.trim();
if name.is_empty()
|| name.contains(|c: char| c.is_whitespace() || c == '.' || c == '/')
{
return Err(ExtractError {
code: "extract.bad_name",
message: "提取目标名必须是单个标识符".into(),
});
}
let expr = parse_expr_prefer_var(expression).map_err(|e| ExtractError {
code: "extract.parse",
message: format!("无法解析表达式: {e}"),
})?;
if !is_pure_payload(&expr) {
return Err(ExtractError {
code: "extract.not_pure",
message: "仅允许字面量/变量/算术/列表等纯载荷;拒绝调用与宿主效应".into(),
});
}
let params: Vec<String> = free_vars(&expr).into_iter().collect();
let call = if params.is_empty() {
format!("{name}()")
} else {
let args = params
.iter()
.map(|p| format!("{p}=`{p}`"))
.collect::<Vec<_>>()
.join(", ");
format!("{name}({args})")
};
let heading = if params.is_empty() {
format!("## {name}\n\n*{expression}*\n")
} else {
let decls = params
.iter()
.map(|p| format!("`{p}`"))
.collect::<Vec<_>>()
.join("、");
format!("## {name}\n\n参数:{decls}\n\n*{expression}*\n")
};
Ok(ExtractPlan {
name: name.into(),
params,
expression: expression.trim().into(),
heading,
call,
})
}
fn is_pure_payload(expr: &Expr) -> bool {
match expr {
Expr::Literal(_) | Expr::Var(_) => true,
Expr::Unary { expr, .. } => is_pure_payload(expr),
Expr::Binary { left, right, .. } => is_pure_payload(left) && is_pure_payload(right),
Expr::List(items) => items.iter().all(is_pure_payload),
Expr::Map(items) => items.iter().all(|(_, v)| is_pure_payload(v)),
Expr::Index { base, .. } => is_pure_payload(base),
Expr::Occluded { payload, .. } => payload
.as_ref()
.map(|p| is_pure_payload(p))
.unwrap_or(true),
Expr::Call(_) | Expr::Interp(_) | Expr::Formula(_) | Expr::Code(_) => false,
}
}
fn free_vars(expr: &Expr) -> BTreeSet<String> {
let mut out = BTreeSet::new();
walk(expr, &mut out);
out
}
fn walk(expr: &Expr, out: &mut BTreeSet<String>) {
match expr {
Expr::Var(name) => {
out.insert(name.clone());
}
Expr::Unary { expr, .. } => walk(expr, out),
Expr::Binary { left, right, .. } => {
walk(left, out);
walk(right, out);
}
Expr::List(items) => {
for item in items {
walk(item, out);
}
}
Expr::Map(items) => {
for (_, item) in items {
walk(item, out);
}
}
Expr::Index { base, .. } => walk(base, out),
Expr::Occluded { payload, .. } => {
if let Some(p) = payload {
walk(p, out);
}
}
Expr::Literal(_)
| Expr::Call(_)
| Expr::Interp(_)
| Expr::Formula(_)
| Expr::Code(_) => {}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn extracts_product() {
let plan = plan_pure_extract("商品小计", "数量 * 单价").unwrap();
assert_eq!(plan.params, vec!["单价".to_string(), "数量".to_string()]);
assert!(plan.heading.contains("## 商品小计"));
assert!(plan.call.contains("商品小计("));
}
#[test]
fn rejects_call() {
let err = plan_pure_extract("x", "save()").unwrap_err();
assert_eq!(err.code, "extract.not_pure");
}
}
+1064 -54
View File
File diff suppressed because it is too large. Load diff
+151 -20
View File
@@ -15,6 +15,8 @@ pub struct LockReport {
pub missing: Vec<String>,
pub changed: Vec<String>,
pub removed: Vec<String>,
/// Per-artifact which digest class drifted (G08).
pub classes: Vec<Value>,
}
impl LockReport {
@@ -29,6 +31,7 @@ impl LockReport {
"missing": self.missing,
"changed": self.changed,
"removed": self.removed,
"classes": self.classes,
})
}
}
@@ -63,26 +66,53 @@ 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)
}
/// Static reverse dependency closure. Queries can be an artifact/symbol URI,
/// a declaration suffix, or a project-relative source filename.
/// a declaration suffix, a project-relative source filename, or a corpus
/// provenance URI (`supports` relation — M02).
pub fn impact(project: &SemanticProject, query: &str) -> Value {
let mut seeds = BTreeSet::new();
for artifact in &project.artifacts {
@@ -90,7 +120,21 @@ 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)
|| artifact.provenance.iter().any(|p| {
p.relation == "supports"
&& (p.uri == query
|| p.uri.ends_with(query)
|| query.ends_with(&p.uri)
|| p.locator
.as_ref()
.is_some_and(|loc| format!("{}#{}", p.uri, loc) == query))
})
{
seeds.insert(artifact.artifact_id.0.clone());
}
@@ -98,29 +142,115 @@ 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());
}
// Corpus URI → citing artifact (provenance supports edges).
for prov in &artifact.provenance {
if prov.relation != "supports" {
continue;
}
reverse
.entry(prov.uri.clone())
.or_default()
.push(artifact.artifact_id.0.clone());
if let Some(loc) = &prov.locator {
reverse
.entry(format!("{}#{}", prov.uri, loc))
.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());
}
}
// Also seed reverse walk from corpus URI keys when query matches them.
if reverse.contains_key(query) {
seeds.insert(query.to_string());
}
let mut queue: VecDeque<String> = seeds.iter().cloned().collect();
let mut affected = BTreeSet::new();
while let Some(current) = queue.pop_front() {
if !affected.insert(current.clone()) { continue; }
if !affected.insert(current.clone()) {
continue;
}
if let Some(users) = reverse.get(&current) {
for user in users { queue.push_back(user.clone()); }
for user in users {
queue.push_back(user.clone());
}
}
}
let entries = affected.iter().filter_map(|id| project.artifacts.iter().find(|a| &a.artifact_id.0 == id)).map(|artifact| json!({
"artifact_id": artifact.artifact_id.0,
"symbol_id": artifact.symbol_id.as_ref().map(|id| id.as_str()),
"display_name": artifact.display_name,
"kind": artifact.kind,
"source": {"file": artifact.source.file, "line": artifact.source.line},
})).collect::<Vec<_>>();
// Drop pure corpus URI keys that are not artifacts from the affected set display.
let entries = affected
.iter()
.filter_map(|id| project.artifacts.iter().find(|a| &a.artifact_id.0 == id))
.map(|artifact| {
let classes = {
let mut c = Vec::new();
if !artifact.hashes.interface.0.is_empty() {
c.push("interface");
}
if !artifact.hashes.implementation.0.is_empty() {
c.push("implementation");
}
if !artifact.hashes.evidence.0.is_empty() {
c.push("evidence");
}
if !artifact.dependencies.is_empty() {
c.push("dependency");
}
c
};
json!({
"artifact_id": artifact.artifact_id.0,
"symbol_id": artifact.symbol_id.as_ref().map(|id| id.as_str()),
"display_name": artifact.display_name,
"kind": artifact.kind,
"source": {"file": artifact.source.file, "line": artifact.source.line},
"hash_classes": classes,
"evidence": artifact.verification.evidence,
})
})
.collect::<Vec<_>>();
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 +261,7 @@ fn lock_json(project: &SemanticProject) -> Value {
"implementation": artifact.hashes.implementation.0,
"evidence": artifact.hashes.evidence.0,
"artifact": artifact.hashes.artifact.0,
"closure": artifact.hashes.closure.0,
"dependencies": artifact.dependencies.iter().map(|item| &item.0).collect::<Vec<_>>(),
}));
}
+10 -2
View File
@@ -4,13 +4,21 @@
//! binding facts so runtime, EKC, view, and agents do not independently infer
//! the meaning of the same source text.
pub mod bind;
pub mod extract;
pub mod ir;
pub mod lock;
pub mod provenance;
pub mod symbols;
pub use bind::{
call_display, is_static_bound, lookup_local, resolve_for_exec, DynamicReason, ExecTarget,
};
pub use extract::{plan_pure_extract, ExtractError, ExtractPlan};
pub use ir::{
artifact_json, compile_project, write_semantic_projections, ArtifactId, CompileOptions, Compilation,
Digest, EffectSet, LockMode, SemanticArtifact, SemanticProject,
artifact_json, compile_project, semantic_generation_dir, write_semantic_projections, ArtifactId,
BoundCall, CompileOptions, Compilation, Digest, DynamicCall, EffectSet, LockMode,
SemanticArtifact, SemanticProject,
};
pub use lock::{check_links_lock, impact as semantic_impact, update_links_lock, LockReport};
pub use symbols::{CallableKind, ModuleId, ProjectIndex, SymbolDecl, SymbolId, SymbolKind};
+512
View File
@@ -0,0 +1,512 @@
//! Optional source / applicability facts from module frontmatter (G05 / M02).
//!
//! 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};
/// Provenance extractor / verifier identity hashed into evidence digests.
pub const PROVENANCE_EXTRACTOR_VERSION: &str = "marqdo-provenance/1";
#[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>,
/// True when author wrote `sources: [...]` inline (ignored by parser — M07).
pub inline_sources_ignored: bool,
/// Optional per-function source overrides (M07): `function_sources: { name: [uri…] }`.
pub function_sources: std::collections::BTreeMap<String, Vec<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;
let mut in_function_sources = false;
let mut current_fn: Option<String> = None;
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;
in_function_sources = false;
current_fn = None;
}
if trimmed == "sources:" || trimmed.starts_with("sources:") {
in_sources = true;
in_applicability = false;
in_function_sources = false;
if let Some(rest) = trimmed.strip_prefix("sources:") {
let rest = rest.trim();
if !rest.is_empty() && rest != "|" {
// inline list is not parsed — flag for diagnosis (M07).
out.inline_sources_ignored = true;
}
}
continue;
}
if trimmed == "function_sources:" || trimmed.starts_with("function_sources:") {
in_function_sources = true;
in_sources = false;
in_applicability = false;
current_fn = None;
continue;
}
if trimmed == "applicability:" || trimmed.starts_with("applicability:") {
in_applicability = true;
in_sources = false;
in_function_sources = false;
continue;
}
if in_function_sources {
// Indent levels: ` name:` then ` - uri`
let indent = line.len() - line.trim_start().len();
if trimmed.ends_with(':') && !trimmed.starts_with('-') {
let name = trimmed.trim_end_matches(':').trim().to_string();
if !name.is_empty() {
current_fn = Some(name.clone());
out.function_sources.entry(name).or_default();
}
continue;
}
if let Some(item) = trimmed.strip_prefix("- ") {
let path = item.trim().trim_matches('"').to_string();
if let Some(name) = &current_fn {
if !path.is_empty() {
out.function_sources
.entry(name.clone())
.or_default()
.push(path);
}
} else if indent >= 2 && !path.is_empty() {
// ignore orphan list items
}
}
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
}
/// Sources applicable to a named function: function_sources override, else module sources.
pub fn sources_for_function(prov: &ModuleProvenance, function_name: &str) -> Vec<String> {
if let Some(list) = prov.function_sources.get(function_name) {
if !list.is_empty() {
return list.clone();
}
}
prov.sources.clone()
}
#[derive(Debug, Clone)]
pub enum ProvenanceDiag {
Missing { path: String },
AnchorMissing { path: String, locator: String },
ReadError { path: String, message: String },
Expired { valid_until: String },
InvalidDate { valid_until: String },
InlineSourcesIgnored,
}
impl ProvenanceDiag {
pub fn code(&self) -> &'static str {
match self {
Self::Missing { .. } => "source.missing",
Self::AnchorMissing { .. } => "source.anchor_missing",
Self::ReadError { .. } => "source.read_error",
Self::Expired { .. } => "source.expired",
Self::InvalidDate { .. } => "source.invalid_date",
Self::InlineSourcesIgnored => "source.inline_ignored",
}
}
pub fn message(&self) -> String {
match self {
Self::Missing { path } => format!("来源文件缺失:`{path}`"),
Self::AnchorMissing { path, locator } => {
format!("来源锚点不存在:`{path}` 中找不到 `#{}`", locator)
}
Self::ReadError { path, message } => {
format!("来源文件无法读取:`{path}`({message})")
}
Self::Expired { valid_until } => {
format!("来源适用期已过(valid_until={valid_until})")
}
Self::InvalidDate { valid_until } => {
format!("适用期日期格式无效(期望 YYYY-MM-DD):`{valid_until}`")
}
Self::InlineSourcesIgnored => {
"sources 行内列表被忽略;请改用 YAML block list(`- path#anchor`)".into()
}
}
}
}
pub struct ProvenanceResolution {
pub refs: Vec<SourceRef>,
pub applicability: String,
pub evidence_status: String,
pub diagnostics: Vec<ProvenanceDiag>,
/// Canonical record hashed into `hashes.evidence` (M02).
pub evidence_record: String,
}
/// Resolve corpus paths relative to the module file; never mark verified here.
pub fn resolve_provenance(
module_path: &Path,
prov: &ModuleProvenance,
) -> ProvenanceResolution {
resolve_provenance_sources(module_path, prov, &prov.sources)
}
/// Resolve an explicit source list (module or per-function).
pub fn resolve_provenance_sources(
module_path: &Path,
prov: &ModuleProvenance,
sources: &[String],
) -> ProvenanceResolution {
let mut refs = Vec::new();
let mut diagnostics = Vec::new();
if prov.inline_sources_ignored {
diagnostics.push(ProvenanceDiag::InlineSourcesIgnored);
}
let base = module_path
.parent()
.map(|p| p.to_path_buf())
.unwrap_or_else(|| PathBuf::from("."));
for raw in 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 = match fs::read(&resolved) {
Ok(bytes) => bytes,
Err(e) => {
diagnostics.push(ProvenanceDiag::ReadError {
path: path_part.to_string(),
message: e.to_string(),
});
refs.push(SourceRef {
uri: path_part.to_string(),
locator,
content_digest: None,
relation: "supports".into(),
});
continue;
}
};
let mut hash = Sha256::new();
hash.update(&content);
let content_digest = Digest(format!("sha256:{:x}", hash.finalize()));
if let Some(loc) = locator.as_ref() {
let text = String::from_utf8_lossy(&content);
if !anchor_exists(&text, loc) {
diagnostics.push(ProvenanceDiag::AnchorMissing {
path: path_part.to_string(),
locator: loc.clone(),
});
}
}
refs.push(SourceRef {
uri: path_part.to_string(),
locator,
content_digest: Some(content_digest),
relation: "supports".into(),
});
}
if let Some(until) = &prov.valid_until {
match validate_date(until) {
DateCheck::Ok => {
if is_expired(until) {
diagnostics.push(ProvenanceDiag::Expired {
valid_until: until.clone(),
});
}
}
DateCheck::Invalid => {
diagnostics.push(ProvenanceDiag::InvalidDate {
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 { .. } | ProvenanceDiag::ReadError { .. }))
{
"missing_source".into()
} else if diagnostics
.iter()
.any(|d| matches!(d, ProvenanceDiag::AnchorMissing { .. }))
{
"anchor_missing".into()
} else if diagnostics
.iter()
.any(|d| matches!(d, ProvenanceDiag::Expired { .. }))
{
"expired".into()
} else if diagnostics
.iter()
.any(|d| matches!(d, ProvenanceDiag::InvalidDate { .. }))
{
"invalid_date".into()
} else if sources.is_empty() {
"unverified".into()
} else {
// Corpus present and in date — still not domain-verified by compile alone.
"sourced".into()
};
let prov_for_record = ModuleProvenance {
sources: sources.to_vec(),
valid_until: prov.valid_until.clone(),
region: prov.region.clone(),
inline_sources_ignored: prov.inline_sources_ignored,
function_sources: Default::default(),
};
let evidence_record = evidence_canonical_record(&prov_for_record, &refs);
ProvenanceResolution {
refs,
applicability,
evidence_status,
diagnostics,
evidence_record,
}
}
/// Canonical evidence inputs: extractor version, applicability, sorted source facts.
pub fn evidence_canonical_record(prov: &ModuleProvenance, refs: &[SourceRef]) -> String {
let mut parts = vec![
format!("extractor={PROVENANCE_EXTRACTOR_VERSION}"),
format!("region={}", prov.region.as_deref().unwrap_or("")),
format!("valid_until={}", prov.valid_until.as_deref().unwrap_or("")),
];
let mut source_parts: Vec<String> = refs
.iter()
.filter(|r| r.relation == "supports")
.map(|r| {
format!(
"{}#{}@{}",
r.uri,
r.locator.as_deref().unwrap_or(""),
r.content_digest
.as_ref()
.map(|d| d.0.as_str())
.unwrap_or("none")
)
})
.collect();
source_parts.sort();
parts.extend(source_parts);
parts.join("|")
}
/// Whether a Markdown heading / id matches the `#locator` fragment.
pub fn anchor_exists(content: &str, locator: &str) -> bool {
let loc = locator.trim().trim_start_matches('#').trim();
if loc.is_empty() {
return true;
}
for line in content.lines() {
let t = line.trim();
if let Some(rest) = t.strip_prefix('#') {
let heading = rest.trim_start_matches('#').trim();
let heading = heading
.split('{')
.next()
.unwrap_or(heading)
.trim();
if heading == loc || slugify_heading(heading) == loc {
return true;
}
}
if t.contains(&format!("id=\"{loc}\""))
|| t.contains(&format!("id='{loc}'"))
|| t.contains(&format!("{{#{loc}}}"))
{
return true;
}
}
false
}
fn slugify_heading(heading: &str) -> String {
let mut out = String::new();
for ch in heading.chars() {
if ch.is_ascii_alphanumeric() {
out.push(ch.to_ascii_lowercase());
} else if ch == ' ' || ch == '-' || ch == '_' {
if !out.ends_with('-') {
out.push('-');
}
} else if !ch.is_ascii() {
// Keep non-ASCII letters (common in ZH docs) without lowercasing rules.
out.push(ch);
}
}
out.trim_matches('-').to_string()
}
enum DateCheck {
Ok,
Invalid,
}
fn validate_date(valid_until: &str) -> DateCheck {
let parts: Vec<&str> = valid_until.split('-').collect();
if parts.len() != 3 {
return DateCheck::Invalid;
}
let Ok(y) = parts[0].parse::<i32>() else {
return DateCheck::Invalid;
};
let Ok(m) = parts[1].parse::<u32>() else {
return DateCheck::Invalid;
};
let Ok(d) = parts[2].parse::<u32>() else {
return DateCheck::Invalid;
};
if !(1..=12).contains(&m) || !(1..=31).contains(&d) || y < 1970 {
return DateCheck::Invalid;
}
if parts[0].len() != 4 || parts[1].len() != 2 || parts[2].len() != 2 {
return DateCheck::Invalid;
}
DateCheck::Ok
}
fn is_expired(valid_until: &str) -> bool {
let today = chrono_today();
!valid_until.is_empty() && valid_until < today.as_str()
}
/// Public recheck for handle.execute (M02).
pub fn valid_until_expired(valid_until: &str) -> bool {
matches!(validate_date(valid_until), DateCheck::Ok) && is_expired(valid_until)
}
fn chrono_today() -> String {
use std::time::{SystemTime, UNIX_EPOCH};
let secs = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap_or_default()
.as_secs() as i64;
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"));
}
#[test]
fn anchor_matches_heading() {
assert!(anchor_exists("# rate\n\nrate = 0.13\n", "rate"));
assert!(!anchor_exists("# rate\n\nrate = 0.13\n", "missing-anchor"));
}
#[test]
fn invalid_date_rejected() {
assert!(matches!(validate_date("2099-12-31"), DateCheck::Ok));
assert!(matches!(validate_date("not-a-date"), DateCheck::Invalid));
assert!(matches!(validate_date("2099-13-01"), DateCheck::Invalid));
}
}
+3 -2
View File
@@ -632,9 +632,10 @@ fn taken_arms_by_branch_line(annots: &[ViewAnnot]) -> HashMap<u32, usize> {
fn render_fun_heading(fun: &Function, annots: &[ViewAnnot]) -> String {
let mut s = format!(
r#"<div class="doc-fun" id="fn-{line}" data-fn="{name}" data-fn-path="{name}" data-line="{line}">
r##"<div class="doc-fun" id="fn-{line}" data-fn="{name}" data-fn-path="{name}" data-line="{line}">
<div class="doc-fun-bar">
<h3 class="doc-fun-title">{name}</h3>"#,
<h3 class="doc-fun-title">{name}</h3>
<a class="knowledge-explain" href="#knowledge-{name}" data-node="{name}">说明</a>"##,
line = fun.span.line,
name = escape(&fun.name),
);
+74 -10
View File
@@ -58,6 +58,17 @@ fn stylesheet() -> &'static str {
}
* { box-sizing: border-box; }
html { scroll-behavior: smooth; }
[id] { scroll-margin-top: 4.5rem; }
.knowledge-block summary { cursor: pointer; font-weight: 600; }
.knowledge-hint { color: var(--muted); font-size: 0.85em; margin: 0.25rem 0 0.5rem; }
.knowledge-error .err { color: #8b1a1a; }
@media print {
.topbar, .stdin-form, .stream-panel, .exec-clear, #notebook-bar, nav { display: none !important; }
.knowledge-block, .source-block { display: block; }
}
@media (prefers-reduced-motion: reduce) {
html { scroll-behavior: auto; }
}
body {
margin: 0;
min-height: 100vh;
@@ -2150,6 +2161,14 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
scrollIfPinned();
}}
if (thinkingEl && (answerNode && answerNode.data)) thinkingEl.open = false;
// V2: reject stale result packets when page_token mismatches (source changed).
var pageTok = window.MARQDO_VIEW_PAGE_TOKEN || "";
var pktTok = (typeof ev.page_token === "string") ? ev.page_token : "";
var acceptPacket = !pktTok || !pageTok || pktTok === pageTok;
if (!acceptPacket) {{
if (status) status.textContent = "stale result ignored";
return;
}}
if (typeof ev.bindings_html === "string") {{
var vp = document.getElementById("vars-panel");
if (vp) {{
@@ -2161,10 +2180,38 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
if (typeof ev.structure_html === "string" && ev.structure_html) {{
var structEl = document.getElementById("structure");
if (structEl) {{
// Preserve call/loop frame selection across SSE structure swap.
var savedCall = {{}};
structEl.querySelectorAll("select.call-picker").forEach(function(sel) {{
if (sel.id) savedCall[sel.id] = sel.value;
}});
var savedLoop = {{}};
structEl.querySelectorAll("select.loop-picker").forEach(function(sel) {{
if (sel.id) savedLoop[sel.id] = sel.value;
}});
var focusId = (document.activeElement && document.activeElement.id) || "";
structEl.innerHTML = ev.structure_html;
initAnnotLeaders();
initCallPickers();
initLoopPickers();
Object.keys(savedCall).forEach(function(id) {{
var el = document.getElementById(id);
if (el && savedCall[id]) {{
el.value = savedCall[id];
el.dispatchEvent(new Event("change", {{ bubbles: true }}));
}}
}});
Object.keys(savedLoop).forEach(function(id) {{
var el = document.getElementById(id);
if (el && savedLoop[id]) {{
el.value = savedLoop[id];
el.dispatchEvent(new Event("change", {{ bubbles: true }}));
}}
}});
if (focusId) {{
var fe = document.getElementById(focusId);
if (fe && fe.focus) try {{ fe.focus(); }} catch (e) {{}}
}}
}}
}}
if (typeof ev.trace_json === "string" && ev.trace_json) {{
@@ -4153,11 +4200,12 @@ pub fn page_file(files: &[PathBuf], rel: &str, vm: &FileViewModel, links: &LinkM
}
}
};
let title = Path::new(rel)
let fallback_title = Path::new(rel)
.file_name()
.and_then(|s| s.to_str())
.unwrap_or(rel)
.trim_end_matches(".mq.md");
let title = crate::view::title_from_source(&vm.source, fallback_title);
let plots_html = if vm.plots.is_empty() {
String::new()
} else {
@@ -4224,43 +4272,59 @@ pub fn page_file(files: &[PathBuf], rel: &str, vm: &FileViewModel, links: &LinkM
window.MARQDO_VIEW_LIVE = {live};
window.MARQDO_FILE_PATH = {path_js};
window.MARQDO_AUTO_STREAM = {auto_stream};
window.MARQDO_VIEW_PAGE_TOKEN = {page_token_js};
</script>
<script type="application/json" id="mq-view-trace">{trace}</script>
<h1 class="page">{title}<span class="status-pill {status}">{status_label}</span></h1>
<p class="meta">{rel}</p>
{notebook}
{knowledge}
<section class="block structure-block">
<h2>Structure</h2>
<section class="block structure-block" id="structure">
<h2>文档</h2>
{structure_block}
</section>
{knowledge}
<section class="block exec-block" id="exec-block">
<h2>Execution {exec_clear}</h2>
<h2>运行与结果 {exec_clear}</h2>
{stdin_panel}
{stream_panel}
{plan_card}
<div class="out {status}" id="exec-main">{out}</div>
{plots}
</section>
<section class="block source-block">
<h2>Source</h2>
<details class="block source-block">
<summary>完整源码</summary>
<pre class="source">{source}</pre>
</section>
</details>
"#,
live = live_flag,
path_js = escape_js_string(rel),
auto_stream = if vm.auto_stream { "true" } else { "false" },
page_token_js = escape_js_string(&vm.page_token),
trace = if trace_safe.is_empty() {
"{}"
} else {
trace_safe.as_str()
},
title = escape(title),
title = escape(&title),
status = status,
status_label = status_label,
rel = escape(rel),
notebook = notebook,
knowledge = if vm.knowledge_html.is_empty() { String::new() } else { format!("<section class=\"block knowledge-block\"><h2>Executable knowledge</h2>{}</section>", vm.knowledge_html) },
knowledge = {
if !vm.knowledge_error.is_empty() {
format!(
"<section class=\"block knowledge-block knowledge-error\"><h2>知识关系</h2><p class=\"err\">{}</p></section>",
escape(&vm.knowledge_error)
)
} else if vm.knowledge_html.is_empty() {
String::new()
} else {
format!(
"<details class=\"block knowledge-block\"><summary>可执行知识(辅助)</summary>{}</details>",
vm.knowledge_html
)
}
},
exec_clear = exec_clear,
structure_block = structure_block,
stdin_panel = stdin_panel,
+197
View File
@@ -0,0 +1,197 @@
//! V1 KnowledgePresentation model — structured facts shared by body, outline, and detail.
//!
//! Semantic facts come from SemanticProject; this module does not invent verification.
use crate::sema::{SemanticArtifact, SemanticProject};
use serde_json::{json, Value};
use sha2::{Digest, Sha256};
#[derive(Debug, Clone)]
pub struct KnowledgeNode {
pub node_id: String,
pub artifact_id: Option<String>,
pub display_name: String,
pub kind: String,
pub source_file: String,
pub source_line: u32,
pub signature: Option<String>,
pub effects: Vec<String>,
pub evidence: String,
pub dependencies: Vec<String>,
pub artifact_digest: String,
}
#[derive(Debug, Clone)]
pub struct KnowledgePresentation {
pub document_id: String,
pub title: String,
pub source_digest: String,
/// V2: semantic generation / run matching token (empty when not compiled under CURRENT).
pub semantic_generation: String,
/// V2: page token for SSE stale-packet rejection (digest of document facts).
pub page_token: String,
pub execution_state: String,
pub nodes: Vec<KnowledgeNode>,
pub diagnostics: Vec<String>,
}
impl KnowledgePresentation {
pub fn from_project(project: &SemanticProject, rel: &str, title: &str) -> Self {
let mut nodes = Vec::new();
for artifact in &project.artifacts {
if artifact.source.file != rel {
continue;
}
if artifact.kind == "module" {
continue;
}
nodes.push(node_from_artifact(artifact));
}
let mut hasher_parts: Vec<&str> = project
.artifacts
.iter()
.filter(|a| a.source.file == rel)
.map(|a| a.hashes.artifact.0.as_str())
.collect();
hasher_parts.sort();
let mut h = Sha256::new();
h.update(project.project_id.as_bytes());
h.update(rel.as_bytes());
for part in &hasher_parts {
h.update(part.as_bytes());
}
let digest_hex = format!("{:x}", h.finalize());
let source_digest = format!("sha256:{digest_hex}");
// page_token is filled by caller from raw source so SSE can match without recompile.
let page_token = String::new();
let semantic_generation = {
let mut gh = Sha256::new();
gh.update(project.project_id.as_bytes());
for a in &project.artifacts {
gh.update(a.hashes.artifact.0.as_bytes());
}
format!("{:x}", gh.finalize())[..16].to_string()
};
let mut diagnostics = Vec::new();
for n in &nodes {
if n.evidence == "sourced" {
// Never imply sourced == verified (V2).
diagnostics.push(format!(
"{}: 已关联来源,内容尚未核验",
n.display_name
));
}
}
Self {
document_id: rel.to_string(),
title: title.to_string(),
source_digest,
semantic_generation,
page_token,
execution_state: "not_run".into(),
nodes,
diagnostics,
}
}
pub fn to_json(&self) -> Value {
json!({
"schema_version": 1,
"document_id": self.document_id,
"title": self.title,
"source_digest": self.source_digest,
"semantic_generation": self.semantic_generation,
"page_token": self.page_token,
"execution_state": self.execution_state,
"nodes": self.nodes.iter().map(|n| json!({
"node_id": n.node_id,
"artifact_id": n.artifact_id,
"display_name": n.display_name,
"kind": n.kind,
"source": {"file": n.source_file, "line": n.source_line},
"signature": n.signature,
"effects": n.effects,
"evidence": n.evidence,
"dependencies": n.dependencies,
"artifact_digest": n.artifact_digest,
"verified_claim": false,
})).collect::<Vec<_>>(),
"local_deps": self.nodes.iter().flat_map(|n| {
n.dependencies.iter().map(|d| json!({
"from": n.node_id,
"to": d,
})).collect::<Vec<_>>()
}).collect::<Vec<_>>(),
"diagnostics": self.diagnostics,
})
}
}
/// V2: whether an SSE result packet may update the live document structure.
pub fn sse_accepts_packet(page_token: &str, packet_token: Option<&str>) -> bool {
match packet_token {
None | Some("") => true, // legacy packets without token still apply
Some(_tok) if page_token.is_empty() => true,
Some(tok) => tok == page_token,
}
}
/// Stable page token from raw source bytes (used by SSE run path).
pub fn page_token_from_source(rel: &str, source: &str) -> String {
let mut h = Sha256::new();
h.update(rel.as_bytes());
h.update(source.as_bytes());
let hex = format!("{:x}", h.finalize());
hex[..hex.len().min(32)].to_string()
}
fn node_from_artifact(artifact: &SemanticArtifact) -> KnowledgeNode {
let signature = artifact.signature.as_ref().map(|sig| {
let params = sig
.params
.iter()
.map(|p| format!("{}:{}", p.name, p.ty))
.collect::<Vec<_>>()
.join(", ");
format!("({params}) → {}", sig.returns)
});
KnowledgeNode {
node_id: artifact
.symbol_id
.as_ref()
.map(|id| id.as_str().to_string())
.unwrap_or_else(|| artifact.artifact_id.0.clone()),
artifact_id: Some(artifact.artifact_id.0.clone()),
display_name: artifact.display_name.clone(),
kind: artifact.kind.clone(),
source_file: artifact.source.file.clone(),
source_line: artifact.source.line,
signature,
effects: artifact.effects.values(),
evidence: artifact.verification.evidence.clone(),
dependencies: artifact.dependencies.iter().map(|d| d.0.clone()).collect(),
artifact_digest: artifact.hashes.artifact.0.clone(),
}
}
/// Pull `title:` from YAML frontmatter without a full YAML parser.
pub fn title_from_source(source: &str, fallback: &str) -> String {
let mut lines = source.lines();
if lines.next().map(|l| l.trim_end()) != Some("---") {
return fallback.to_string();
}
for line in lines {
let t = line.trim_end();
if t.trim() == "---" {
break;
}
let trimmed = t.trim();
if let Some(rest) = trimmed.strip_prefix("title:") {
let title = rest.trim().trim_matches('"').trim_matches('\'').to_string();
if !title.is_empty() {
return title;
}
}
}
fallback.to_string()
}
+100 -27
View File
@@ -6,10 +6,15 @@ mod debug_api;
mod debug_page;
mod document;
mod html;
mod knowledge_present;
mod notebook_api;
mod output;
mod render;
pub use knowledge_present::{
page_token_from_source, sse_accepts_packet, title_from_source, KnowledgePresentation,
};
/// Surface rendering of an expression (labels/diagnostics reuse). `<TAB>` M6
pub use render::expr_display;
@@ -383,6 +388,18 @@ pub(crate) fn build_file_view(
rel: &str,
stdin_lines: &[String],
live: bool,
) -> Result<FileViewModel> {
build_file_view_with_exec(root, abs, rel, stdin_lines, live, true)
}
/// Like [`build_file_view`], but `execute=false` skips `run_file_capture` entirely (V0 / `--no-exec`).
pub(crate) fn build_file_view_with_exec(
root: &ViewRoot,
abs: &Path,
rel: &str,
stdin_lines: &[String],
live: bool,
execute: bool,
) -> Result<FileViewModel> {
let mut source = fs::read_to_string(abs).with_context(|| format!("read {}", abs.display()))?;
// Structure shows this file only — do not merge imported lib bodies into the tree.
@@ -423,34 +440,43 @@ pub(crate) fn build_file_view(
// Optional: sandbox to the whole view tree so sibling folders are reachable.
opts.fs_root = Some(root.root.clone());
let mut captured: Option<crate::capture::RunCapture> = None;
let (stdout, stderr, ok, plots, mut bindings_html) = if awaiting_input || auto_stream {
(
String::new(),
String::new(),
true,
Vec::new(),
String::new(),
)
} else {
match run_file_capture(abs, &opts) {
Ok(cap) => {
let stdout = cap.stdout.clone();
let plots = cap.plots.iter().map(|p| p.svg.clone()).collect();
let bindings_html = render_bindings_html(&cap.bindings);
captured = Some(cap);
(stdout, String::new(), true, plots, bindings_html)
}
Err(e) => (
let (stdout, stderr, ok, plots, mut bindings_html) =
if !execute {
(
String::new(),
tidy_user_error(&format!("{e:#}"), abs, rel),
false,
"execution skipped (--no-exec)".into(),
true,
Vec::new(),
String::from(r#"<p class="vars-skipped">skipped</p>"#),
)
} else if awaiting_input || auto_stream {
(
String::new(),
String::new(),
true,
Vec::new(),
String::new(),
),
}
};
)
} else {
match run_file_capture(abs, &opts) {
Ok(cap) => {
let stdout = cap.stdout.clone();
let plots = cap.plots.iter().map(|p| p.svg.clone()).collect();
let bindings_html = render_bindings_html(&cap.bindings);
captured = Some(cap);
(stdout, String::new(), true, plots, bindings_html)
}
Err(e) => (
String::new(),
tidy_user_error(&format!("{e:#}"), abs, rel),
false,
Vec::new(),
String::new(),
),
}
};
// Re-read after run so writeback slots / workbook edits show in Structure.
if !awaiting_input && !auto_stream {
if execute && !awaiting_input && !auto_stream {
if let Ok(next) = fs::read_to_string(abs) {
source = next;
}
@@ -480,9 +506,52 @@ pub(crate) fn build_file_view(
};
// Analysis is intentionally independent from capture/run. If a document
// has side effects, its facts remain visible while its values stay absent.
let knowledge_html = crate::sema::compile_project(&crate::sema::CompileOptions {
project_root: root.root.clone(), entry: Some(abs.to_path_buf()), lock_mode: crate::sema::LockMode::Off,
}).map(|compilation| render_knowledge_html(&compilation.semantics, rel)).unwrap_or_default();
let title_guess = crate::view::title_from_source(&source, rel);
let (knowledge_html, knowledge_error, page_token) =
match crate::sema::compile_project(&crate::sema::CompileOptions {
project_root: root.root.clone(),
entry: Some(abs.to_path_buf()),
lock_mode: crate::sema::LockMode::Off,
}) {
Ok(compilation) => {
let html = render_knowledge_html(&compilation.semantics, rel);
// V1: also materialize structured presentation (JSON available to page scripts).
let mut presentation = crate::view::KnowledgePresentation::from_project(
&compilation.semantics,
rel,
&title_guess,
);
presentation.page_token = crate::view::page_token_from_source(rel, &source);
let json = presentation.to_json().to_string();
let with_model = if html.is_empty() {
format!(
r#"<script type="application/json" id="mq-knowledge-presentation">{json}</script>"#,
json = json.replace("</", "<\\/")
)
} else {
format!(
r#"{html}<script type="application/json" id="mq-knowledge-presentation">{json}</script>"#,
html = html,
json = json.replace("</", "<\\/")
)
};
(
with_model,
String::new(),
presentation.page_token.clone(),
)
}
Err(e) => (
String::new(),
format!("知识关系暂不可用:{}", tidy_user_error(&format!("{e:#}"), abs, rel)),
crate::view::page_token_from_source(rel, &source),
),
};
let page_token = if page_token.is_empty() {
crate::view::page_token_from_source(rel, &source)
} else {
page_token
};
Ok(FileViewModel {
rel_path: rel.to_string(),
source,
@@ -500,6 +569,8 @@ pub(crate) fn build_file_view(
bindings_html: std::mem::take(&mut bindings_html),
trace_json,
knowledge_html,
knowledge_error,
page_token,
})
}
@@ -752,6 +823,7 @@ fn api_run(root: &ViewRoot, mut request: Request) -> Result<()> {
}
Err(_) => (String::new(), String::new()),
};
let page_token = crate::view::page_token_from_source(&rel_clone, &source_now);
let done = serde_json::json!({
"type": "done",
"run_id": run_id,
@@ -761,6 +833,7 @@ fn api_run(root: &ViewRoot, mut request: Request) -> Result<()> {
"bindings_html": bindings_html,
"structure_html": structure_html,
"trace_json": trace_json,
"page_token": page_token,
});
crate::host::event_bus::EventBus::global().publish_json(&done.to_string());
}
+3 -21
View File
@@ -11,7 +11,7 @@ use crate::host::foreign_doc::DocumentSession;
use crate::host::json::json_to_value;
use crate::value::Value;
use crate::view::html::{escape, page_file, page_index, LinkMode};
use crate::view::{build_file_view, build_root, ViewRoot};
use crate::view::{build_file_view, build_file_view_with_exec, build_root, ViewRoot};
pub struct OutputOptions {
pub path: PathBuf,
@@ -280,26 +280,8 @@ pub fn write_static(opts: OutputOptions) -> Result<()> {
for rel_pb in &root.files {
let rel = rel_pb.to_string_lossy().replace('\\', "/");
let abs = resolve_abs(&root, &rel)?;
let mut vm = build_file_view(&root, &abs, &rel, &[], false)?;
if opts.no_exec {
vm.stdout.clear();
vm.stderr = "execution skipped (--no-exec)".into();
vm.ok = true;
vm.plots.clear();
vm.bindings_html = String::from(r#"<p class="vars-skipped">skipped</p>"#);
vm.trace_json.clear();
// Rebuild outline + Structure without run annotations.
if let Ok(module) = crate::parse::parse_source(&vm.source) {
let wb = crate::view::render::render_writeback_outline(&vm.source);
vm.outline_html =
crate::view::render::render_right_rail(&module, &vm.bindings_html, &wb);
vm.structure_html = crate::view::render::render_module_structure_with_annots(
&module,
&vm.source,
&[],
);
}
}
// V0: apply --no-exec before any capture run (do not execute then clear).
let vm = build_file_view_with_exec(&root, &abs, &rel, &[], false, !opts.no_exec)?;
let links = LinkMode::Static {
from: Some(rel.clone()),
};
+76 -5
View File
@@ -44,31 +44,102 @@ pub struct FileViewModel {
/// SVG plots from math lib (embedded in Execution).
pub plots: Vec<String>,
/// HTML for Variables panel (entry bindings after run).
#[allow(dead_code)]
pub bindings_html: String,
/// ViewExecutionReport JSON for AI / call-picker (empty if no run).
pub trace_json: String,
/// Static semantic facts; generated without evaluating the document.
pub knowledge_html: String,
/// Visible when semantic analysis fails (V0); empty when analysis succeeded or was skipped.
pub knowledge_error: String,
/// V2: page token for SSE stale-packet rejection (empty when unknown).
pub page_token: String,
}
/// A compact, textual (not colour-only) explanation of executable knowledge.
/// View deliberately compiles semantics without running the target, so a page
/// can show binding/effect/verification facts even in `--no-exec` exports.
///
/// V0: skip module/type container cards by default; rename lock digest accurately.
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 artifacts: Vec<_> = project
.artifacts
.iter()
.filter(|artifact| {
artifact.source.file == rel && artifact.kind != "module" && artifact.kind != "type"
})
.collect();
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>文档中的步骤</h3><p class="knowledge-hint">结构步骤(非实际执行时序)</p><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| {
let params = sig.params.iter().map(|param| format!("{}: {}{}", param.name, param.ty, if param.required { "" } else { "?" })).collect::<Vec<_>>().join(", ");
format!("({params}) → {}", sig.returns)
}).unwrap_or_else(|| "module/type declaration".into());
}).unwrap_or_else(|| "declaration".into());
let effects = artifact.effects.values().join(", ");
let deps = if artifact.dependencies.is_empty() { "none".to_string() } else { artifact.dependencies.iter().map(|id| id.0.as_str()).collect::<Vec<_>>().join(", ") };
// Short digest for display; full value in title for copy.
let digest = &artifact.hashes.artifact.0;
let digest_short = if digest.len() > 20 {
format!("{}…", &digest[..20])
} else {
digest.clone()
};
let evidence_note = match artifact.verification.evidence.as_str() {
"sourced" => "已关联来源,内容尚未核验",
"verified" => "证据已核验",
"unverified" => "尚无来源记录",
other => other,
};
out.push_str(&format!(
r#"<article class="knowledge-card"><h3>{}</h3><dl><dt>Target</dt><dd><code>{}</code></dd><dt>Kind</dt><dd>{}{}</dd><dt>Signature</dt><dd><code>{}</code></dd><dt>Effects</dt><dd>{}</dd><dt>Verification</dt><dd>parse: {}; resolve: {}; contract: {}; tests: {}; evidence: {}</dd><dt>Lock digest</dt><dd><code>{}</code></dd><dt>Depends on</dt><dd><code>{}</code></dd><dt>Execution</dt><dd>Not executed by knowledge preview.</dd></dl></article>"#,
escape(&artifact.display_name), escape(target), escape(&artifact.kind), artifact.callable.as_ref().map(|callable| format!(" ({})", escape(callable))).unwrap_or_default(), escape(&signature), escape(&effects), escape(&artifact.verification.parse), escape(&artifact.verification.resolve), escape(&artifact.verification.contract), escape(&artifact.verification.tests), escape(&artifact.verification.evidence), escape(&artifact.hashes.artifact.0), escape(&deps),
r#"<article class="knowledge-card" id="knowledge-{name}"><h3>{name} <span class="ks-kind">{kind}</span></h3><dl><dt>Target</dt><dd><code>{target}</code></dd><dt>Signature</dt><dd><code>{sig}</code></dd><dt>Effects</dt><dd>{effects}</dd><dt>Verification</dt><dd>parse: {parse}; resolve: {resolve}; contract: {contract}; tests: {tests}; evidence: {evidence}({evidence_note})</dd><dt>制品摘要</dt><dd><code title="{digest}">{digest_short}</code> <span class="knowledge-hint">(未检查锁定状态)</span></dd><dt>Depends on</dt><dd><code>{deps}</code></dd><dt>Execution</dt><dd>尚无该知识的运行记录(知识预览不执行)。</dd></dl></article>"#,
name = escape(&artifact.display_name),
kind = escape(&artifact.kind),
target = escape(target),
sig = escape(&signature),
effects = escape(&effects),
parse = escape(&artifact.verification.parse),
resolve = escape(&artifact.verification.resolve),
contract = escape(&artifact.verification.contract),
tests = escape(&artifact.verification.tests),
evidence = escape(&artifact.verification.evidence),
evidence_note = escape(evidence_note),
digest = escape(digest),
digest_short = escape(&digest_short),
deps = escape(&deps),
));
}
out.push_str("</div>");
File diff suppressed because it is too large. Load diff
+67
View File
@@ -0,0 +1,67 @@
# 可执行知识 — 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;扫描上限 |
| F0/M02 证据·闭包·句柄 | **done** | evidence 含来源摘要;锚点诊断;business handle 改/删来源失效;SCC closure;`m02_*` |
| F0/M03 验证裁决 | **done(子集)** | `artifact.verify` 结构化 may_bind;policy 枚举;`knowledge adjudicate` |
| F0/M05 语法 Skill | **done** | CORE SYNTAX 置顶;`migration-classic.md`;`skill_core_card` |
| View V0–V1 | **done** | 正文优先;no-exec 不执行;制品摘要;`KnowledgePresentation`;frontmatter title;说明锚点 |
| View V2 | **done(子集)** | `page_token`/`semantic_generation`;SSE 过期包拒绝;帧选择保留;`local_deps`;sourced≠verified |
| View V3 | **done(子集)** | print/响应式 CSS;100 单元确定性;1000 单元 compile smoke;无 JS 结构块仍在静态 HTML |
| F1/M04 bind 闭环 | **done** | `artifact.reuse_execute` 实际复用;`agent_eng_bind_execute` + `publish_gate`(candidate_only / product gate);`tests/ext/agent-eng-bind-gate.mq.md` |
| F2/M06–M07 | **done(子集)** | 统一 `EXCLUDED_DIRS`;`publish_manifest.json`;`function_sources`;story 失效/修复 |
| F3/M01 提取 | **done(子集)** | `document.extract` text/Markdown;PDF/DOCX/OCR 显式失败;超限截断 partial;上传 `max_bytes` |
## 与后续切片的关系
- 远程凭据/多租户授权、平台打包产物冒烟、作者/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 @@
# 标准税率
演示用政策原文(已过期样例)。标准税率为 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)*
+62
View File
@@ -0,0 +1,62 @@
---
markup: occlusion
title: F1 eng_bind_execute + publish_gate (no LLM)
description: >-
Deterministic fake-model substitute: bind+execute existing knowledge with
actual_reuse trace; candidate_only / product_gate_ok=false refuse promote.
Offline — no network / no LLM.
import:
fs: lib/fs.mq.md
json: lib/json.mq.md
plugin: lib/plugin.mq.md
sys: lib/sys.mq.md
---
# main
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=no-agent-plugin
> sys.exit code=1
**root = "tests/executable_knowledge/baseline/02-extract"**
`inputs` = > json.parse text={"数量":2,"单价":30}
**exec = > agent_eng_bind_execute project=`root` query="商品小计" policy="pure" inputs=`inputs` candidate_only=True**
**ok = > json.get value=`exec` key="ok"**
1. `ok`
> print text=bind-execute-ok
2. *
> print text=bind-execute-FAIL
> print text=`exec`
> sys.exit code=1
**reuse = > json.get value=`exec` key="actual_reuse"**
1. `reuse`
> print text=actual-reuse-ok
2. *
> print text=actual-reuse-MISSING
> sys.exit code=1
**gate1 = > agent_eng_publish_gate project=`root` artifact_id="商品小计" candidate_only=True product_gate_ok=True**
**promote1 = > json.get value=`gate1` key="may_promote"**
1. `promote1` == False
> print text=candidate-only-blocks-promote
2. *
> print text=candidate-only-FAIL
> print text=`gate1`
> sys.exit code=1
**gate2 = > agent_eng_publish_gate project=`root` artifact_id="商品小计" candidate_only=False product_gate_ok=False**
**promote2 = > json.get value=`gate2` key="may_promote"**
1. `promote2` == False
> print text=product-gate-blocks-promote
2. *
> print text=product-gate-FAIL
> print text=`gate2`
> sys.exit code=1
> print text=agent-eng-bind-gate-ok
*"agent-eng-bind-gate-ok"*
+15 -3
View File
@@ -1286,8 +1286,19 @@ fn knowledge_compile_engineering_fixture() {
]);
assert_eq!(code, 0, "{stderr}");
assert!(dir.join("catalog/repository.mq.md").exists());
assert!(dir.join("graph/graph.json").exists());
assert!(dir.join("graph/edges.json").exists());
// G01: SemanticProject owns graph/; EKC retrieval lives under ekc/.
assert!(dir.join("graph/edges.json").exists(), "semantic edges");
assert!(dir.join("ekc/graph/graph.json").exists(), "EKC retrieval graph");
assert!(dir.join("ekc/graph/edges.json").exists(), "EKC retrieval edges");
assert!(
!dir.join("graph/graph.json").exists(),
"EKC graph.json must not overwrite semantic graph/"
);
let edges: serde_json::Value =
serde_json::from_str(&std::fs::read_to_string(dir.join("graph/edges.json")).unwrap())
.unwrap();
assert_eq!(edges["authority"], "SemanticProject", "{edges}");
assert!(dir.join("steps.json").exists(), "semantic steps projection");
assert!(dir.join("engineering.yaml").exists());
assert!(dir.join("index.mq.md").exists());
let eng = std::fs::read_to_string(dir.join("engineering.yaml")).unwrap();
@@ -1432,7 +1443,8 @@ fn catalog_hooks_knowledge_by_default() {
assert_eq!(code, 0, "{stderr}");
assert!(dir.join("catalog.yaml").exists());
assert!(dir.join("engineering.yaml").exists());
assert!(dir.join("graph/graph.json").exists());
assert!(dir.join("ekc/graph/graph.json").exists());
assert!(dir.join("graph/edges.json").exists());
}
#[test]