Compare commits

...
27 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
cflmy ae97891266 release: v2.1.0 — file-scoped occlusion 2026-10-23 12:59:28 +00:00
cflmy aea86746e7 feat: migrate corpus to file-scoped occlusion 2026-10-23 12:45:01 +00:00
cflmy c773503938 Merge branch 'main' of https://github.com/cflmy/marqdo
# Conflicts:
#	tests/migrate.rs
#	tests/occlusion/classic-index.mq.md
2026-10-23 12:11:58 +00:00
cflmy 939e23ee88 refactor: scope markup compatibility per invocation 2026-10-23 12:11:26 +00:00
cflmyandCursor 687c168014 feat(parse): use nested YAML import: maps instead of one-liner binds
Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target
entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the
old one-liner form, and migrate lib/ext/examples/tests/docs accordingly.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 19:33:58 +08:00
cflmy eac9b45263 feat: compile executable knowledge semantic artifacts 2026-10-23 09:16:52 +00:00
cflmy 74b298e80d build: add portable development toolchain setup 2026-10-23 09:00:56 +00:00
cflmy fc7097bae4 test: validate executable knowledge syntax across libraries 2026-10-23 08:47:49 +00:00
cflmy b624084745 feat: classify associated and instance symbols 2026-10-23 08:26:33 +00:00
cflmy 0bbe735c3c feat: add stable executable knowledge symbols 2026-10-23 08:24:10 +00:00
cflmy 92de46aca4 docs: define executable knowledge implementation baseline 2026-10-23 08:06:38 +00:00
cflmy 8bbe017a5e docs: define executable knowledge step architecture 2026-10-23 15:46:02 +08:00
cflmy 1a13989230 fix(ext/ai): 变量引用补反引号;prompt 缺失回退空串
- llm/agent 模板中的变量引用统一加反引号
- ask/stream 在 prompt/path 均缺失时回退空串,避免直接退出
- 修正 stream 分支返回缩进;agent workbook 模板改用 ** 代码块
2026-10-23 14:52:26 +08:00
cflmy 5ad1a07f5c docs(language): 链接语法与知识分层设计声明 + 示例
- []() 零新语法:描述 + 已有类/函数调用,不引入 ref/别名/开关
- # 是类、## 是函数;类.函数 是类调用;跨文档用项目类索引
- 知识分层:原始语料 / 本体 / 单体知识类 / 调用面;出处与还原验证
- 新增 link-syntax、knowledge-layers 设计声明与两组可运行/目标示例
2026-10-23 14:52:23 +08:00
cflmy bcfc763ba4 fix(parse): 孤立 * 行不再 panic(exit 101 → 干净诊断)
qdagent 全仓 labels 扫描期间实测:任何 .mq.md 里有一行只含单个 `*`
(markdown 强调残留)时,`*…* = 返回` 分支同时满足 starts_with/ends_with('*'),
切片 &trimmed[1..0] 越界,整条 labels 扫描被一个文件打死(exit 101)。

修复:斜体返回分支要求 len >= 2,裸 `*` 落回 "unrecognized statement"
干净错误而非崩溃。

实测:
- tests/errors/lone-asterisk.mq.md → check 报 "unrecognized statement: *",
  exit 1(不再 101)
- gold 回归 error_lone_asterisk_line 通过
- cargo test --release 全套件 0 failed
2026-10-22 19:04:25 +08:00
693 changed files with 19511 additions and 1817 deletions

No files matched your search

+2 -2
View File
@@ -144,7 +144,7 @@ Matching surrounding **legacy** `json.set` in `ext/ai/*.mq.md` is **not** compli
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: Artifact Metadata (`type: web|endpoint`) + `ext/web` facade + `ext/data` / `ext/security` / `ext/net` — see [ext-web-artifact.md](../../doc/design/ext-web-artifact.md). **Never** restore `compose_*` / `app.configure`.
Browser client programs: prefer nested `import:` with `browser: lib/browser.mq.md` (no native plugin). Server sites: Artifact Metadata (`type: web|endpoint`) + `ext/web` facade + `ext/data` / `ext/security` / `ext/net` — see [ext-web-artifact.md](../../doc/design/ext-web-artifact.md). **Never** restore `compose_*` / `app.configure`.
## Developing libraries (`lib/*`, `ext/*`)
@@ -186,7 +186,7 @@ When editing a file full of `json.set`:
1. Turn static structures into GFM tables.
2. Replace repeated effect shapes with `browser.*` / `web.text_patch` / `web.dom_patch`.
3. Leave at most sparse `table.put` for dynamic keys.
4. Drop `import json:…` if unused.
4. Drop unused `json:` (or other) entries under nested `import:`.
## Anti-patterns
+40 -57
View File
@@ -14,67 +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 `import bind:path.mq.md` / `导入` | Import file (bind library name) |
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `*…*` | 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
@@ -136,13 +118,14 @@ Chinese builtins (same functions, no import):
## Frontmatter imports + stdlib
Imports use `import bind:target` (`导入` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
Imports use nested YAML `import:` (`导入:` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
```markdown
---
title: example
import text:lib/text.mq.md
import clock:lib/time.mq.md
import:
text: lib/text.mq.md
clock: lib/time.mq.md
---
# main
+23 -13
View File
@@ -141,7 +141,8 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
```markdown
---
import browser:lib/browser.mq.md
import:
browser: lib/browser.mq.md
---
# main
@@ -168,7 +169,8 @@ Return and soft-error packs are **tables**, not `json.set` pipelines. Full style
```markdown
---
import table:lib/table.mq.md
import:
table: lib/table.mq.md
---
## step_ok
@@ -217,7 +219,8 @@ Do **not** mirror legacy `ext/ai/agent.mq.md` `json.parse`+`json.set` chains whe
```markdown
---
title: split demo
import text:lib/text.mq.md
import:
text: lib/text.mq.md
---
# main
@@ -230,8 +233,9 @@ import text:lib/text.mq.md
```markdown
---
import re:lib/re.mq.md
import enc:lib/encoding.mq.md
import:
re: lib/re.mq.md
enc: lib/encoding.mq.md
---
# main
@@ -246,8 +250,9 @@ import enc:lib/encoding.mq.md
```markdown
---
import log:lib/log.mq.md
import uuid:lib/uuid.mq.md
import:
log: lib/log.mq.md
uuid: lib/uuid.mq.md
---
# main
@@ -278,7 +283,8 @@ After a blank line, code runs:
```markdown
---
description: loads math
import math:lib/math.mq.md
import:
math: lib/math.mq.md
---
# main
@@ -326,7 +332,8 @@ See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` const
```markdown
---
import agent:ext/agent.mq.md
import:
agent: ext/agent.mq.md
---
# main
@@ -378,8 +385,9 @@ if x > 0:
```markdown
---
title: hello-site
import web:ext/web/web.mq.md
import db:db/index.mq.md
import:
web: ext/web/web.mq.md
db: db/index.mq.md
---
# main
@@ -416,7 +424,8 @@ import db:db/index.mq.md
```markdown
---
import quantum:ext/quantum/quantum.mq.md
import:
quantum: ext/quantum/quantum.mq.md
---
# main
@@ -445,7 +454,8 @@ import quantum:ext/quantum/quantum.mq.md
```markdown
---
import la:ext/linalg/linalg.mq.md
import:
la: ext/linalg/linalg.mq.md
---
# main
+4 -2
View File
@@ -122,7 +122,8 @@ Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc
```markdown
---
import math:lib/math.mq.md
import:
math: lib/math.mq.md
---
# main
@@ -141,7 +142,8 @@ Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only
```markdown
---
import foreign:lib/foreign.mq.md
import:
foreign: lib/foreign.mq.md
---
# main
@@ -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.0.0**:遮蔽语法——`[描述](实现)` 描述不执行 · `()` 内调用 · `access` 取元 · 遮蔽循环 · `labels` / `migrate labels` · view 桩徽章
- **v2.0.0**: Occlusion syntax — `[label](payload)` inert prose, paren calls, `access`, occlusion loops, `labels` / `migrate labels`, view stub badges
- **v2.0.0 ext**:扩展包同步 2.0.0 / Ext pack 2.0.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/
+93
View File
@@ -41,6 +41,32 @@ marqdo ext add web # CDN → 2.0.0
- **语料迁移(M7)**:`public/` `ext/` `tests/` `examples/` `doc/` 等语料加 `markup: occlusion`,改写 **80 个语料文件 / 256 处取元 / 23 处循环**;新增 `tests/ratchet` 锁定标签债务。
- **文档**:遮蔽语法总纲 + M0–M10 变更记录、标签新鲜度 / 修复回路、函数作为值 6 篇评估、代码体量审计;`doc/design/code-volume-audit.md` 记 53k 行构成。
## v2.1.0 — 2026-10-23
### Highlights
**文件级可执行知识语义**:标准库、扩展库、示例与公开文档全部采用显式 `markup: occlusion`;`[描述](实现)` 成为默认链接语义,`access` 与 `遍历` 承担原有取元与循环职责。迁移工具可离线证明语法形状等价,Tree 与 Bytecode 均完成全量回归。
```bash
git checkout v2.1.0 && cargo build --release
marqdo ext add web
```
**核心表面 Δ**:默认链接语义从 Classic 切换到 Occlusion。未迁移的旧 `[键](集合)` 仅可用 `markup: classic` 或一个版本周期内的 `marqdo run --legacy-markup` / `check --legacy-markup` 执行。
### Added
- **文件级新语义迁移**:`marqdo migrate labels --mark` 可把整个库/目录迁移到显式 `markup: occlusion`,即使文件没有旧式索引也不再依赖进程默认值。迁移验证为语法级、无导入解析依赖,并在写入前比较 Classic 与 Occlusion AST 形状。
- **显式过渡入口**:`marqdo run --legacy-markup` 与 `marqdo check --legacy-markup` 可在一个版本周期内审阅未迁移的旧文件;环境变量不再改变语法。
### Fixed
- 标准库、扩展库、示例、公开文档与可解析测试夹具迁移为文件级 Occlusion;旧的 `[键](集合)` 和 `- [项](集合)` 分别改为 `access` 与 `遍历`。
### Changed
- 未标注源码默认采用 Occlusion。Classic 仅能通过明确的 frontmatter 或 `--legacy-markup` 进入,避免同一文档因进程配置而静默改变含义。
## Unreleased
### Added
@@ -49,6 +75,73 @@ marqdo ext add web # CDN → 2.0.0
### 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.0.0"
version = "2.1.2"
dependencies = [
"anyhow",
"assert_cmd",
@@ -610,7 +610,7 @@ dependencies = [
[[package]]
name = "marqdo-wasm"
version = "2.0.0"
version = "2.1.2"
dependencies = [
"marqdo",
"serde_json",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "2.0.0"
version = "2.1.2"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
+110 -20
View File
@@ -6,7 +6,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
**链接语法**:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
---
@@ -31,13 +31,94 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
| **默认安全,AI 友好** | 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥**不会污染**文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。 |
| **multi-view artifact**<br>`.mq.md` 双后缀即开放接口 | `.mq` 告诉解释器「可执行」,`.md` 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。**Marqdo 不占有知识,只是给 Markdown 增加执行语义。** |
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元 `[键](集合)` 也是 Markdown 链接形。这是 literate programming 的下一步。 |
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元使用 `access(集合, "键")`,链接 `[描述](表达式)` 只承载叙述与执行体。这是 literate programming 的下一步。 |
| **语义干净** | **返回是架构,打印只是函数**:`*…*` 改变控制流,`print` 只是副作用函数;分支与循环长在 Markdown 结构上(`1.` `2.` 递增 = 分支,`-` = 循环),不是所有列表都被粗暴当成 if。 |
| **AI 的可靠上下文与长期记忆** | 一个 `.mq.md` 同时是 documentation + schema + code + examples + knowledge + executable behavior;AI 不必再拼装 README + OpenAPI + JSON Schema + prompt。整个工程天然就是 AI 的**世界模型**——比 RAG 更接近 Executable RAG。 |
| **链接即调用**<br>Link as Call | 文档里的 `[描述](类.函数)` 不是装饰,是跨文档类调用;编译器解析类/函数并返回 **LinkInfo**,`view` 显示调用点,EKC 建边,`links.lock` 可选复现。**v2.1 已实现可执行知识基础设施**。 |
| **完整工程,不是玩具** | Rust 正经解释器(词法 / 语法 / 语义 / 树遍历 + 字节码后端)、stdlib、模块与对象、debugger、viewer、catalog、WASM、原生插件 ABI、VS Code 扩展、agent / LLM / MCP。 |
---
## 链接语法:链接即调用(v2.1 设计声明)
> **这是 v2.1 的可执行知识模型。**
> `[]()` 不新增语法:`[]` 是 Markdown 链接的描述;`()` 是**已有代码**,与 `**代码**` 同权。
> `#` 是类,`##` 是函数;`类.函数` 是**类调用**。
> 链接只是给这次调用一个名字;`view` 显示调用信息,编译器返回 **LinkInfo**,EKC 建边。
### 两文档,一次类调用
知识文档 `libai.mq.md`:
```markdown
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
*701*
```
- `# 李白` = 类;
- `## 李白的出生年份` = 函数;
- `*701*` = 返回值。
调用文档 `main.mq.md`:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`——**类 `李白` 调用函数 `李白的出生年份`**。
不需要 `print`:`view` 模式天然显示 `()` 的调用信息(类、函数、签名、值)。
要终端输出,就把同一段代码放进代码链接并加 `print`:
```markdown
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
输出:`701`。
### 四条语义
1. **`[]` 永不执行**:描述只给人读、给检索/诊断/展示用。
2. **`()` 与 `**代码**` 同权**:同一套 parser/evaluator;`类.函数` 是类调用,`obj.函数` 是实例调用。
3. **`#` 是类,`##` 是函数**:不使用 `self`/`自` 的函数是**类函数**,可直接 `类.函数` 调用;使用 `self`/`自` 的是**实例函数**。
4. **链接 = 描述 + 调用**:`view` 显示调用点;编译器返回 `LinkInfo`;EKC 建边;`links.lock` 可选复现。
### 现状与目标
| 能力 | v2.0.0 | v2.1 |
|------|-------------|-----------|
| 本地表达式链接(遮蔽) | ✅ `markup: occlusion` | ✅ |
| `()` 与 `**代码**` 同权 | ✅ 表达式/调用 | ✅ |
| 类调用 `类.函数` | ❌ 需先构造实例 | ✅ 直接调用 |
| 跨文档类索引 | ❌ 需 `import` + 实例 | ✅ 项目类索引 |
| 正文链接 `view` 信息 | ❌ | ✅ 目标/签名/值 |
| LinkInfo / check | ❌(`check` 只查契约) | ✅ `link.*` |
| 链接图边(EKC) | ❌ | ✅ `calls` / `references` |
| `links.lock` 可复现 | ❌ | ✅ 可选 |
### 知识分层:本体 → 知识个体 → 调用面
| 层 | 写法 | 语义 |
|----|------|------|
| L1 本体 | `# 诗人` + 字段/类型表 | 类/模式 |
| L2 知识个体 | `# 李白 = > 诗人` + `## 出生年份` + `*701*` | 单体知识类(不是运行时实例) |
| L3 调用面 | `[出生年份](李白.出生年份)` | 类调用/链接 |
> `# 李白 = > 诗人` 语法上是继承/特化,语义上是「李白是诗人」的知识个体;
> 运行时实例仍是 `> 诗人` / `> 李白`。详见 [knowledge-layers.md](doc/design/knowledge-layers.md)。
兼容迁移示例见 [examples/link-syntax/main.compat.mq.md](examples/link-syntax/main.compat.mq.md)。
设计宪法:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 链接示例:[examples/link-syntax/](examples/link-syntax/) · 知识分层示例:[examples/knowledge-layers/](examples/knowledge-layers/) · 证据复核:[occlusion-vs-executable-knowledge-2026-10.md](doc/research/occlusion-vs-executable-knowledge-2026-10.md)
---
## 愿景与期许
不把「AI 能写 Marqdo」当终点,而是 **「AI 能可靠地生成可验证的 Marqdo」**:
@@ -45,7 +126,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
1. **AI 可验证语言**:`LLM → Marqdo AST → 语义检查 → 结构化诊断 → LLM 修复 → 合格程序`。让类型与语义检查成为 AI 编程闭环里的强约束,堵住「语义看似合理、类型实则不对」的生成。
2. **Marqdo Schema / Language Server for AI**:机器可读的语言 Schema(`get_syntax` / `validate` / `repair` …),AI 不必读千行文档猜语法,而是 discover → construct → validate → execute → inspect。
3. **程序即 AI 长期记忆**:`.mq.md` 工程 = 可执行知识库 = AI 的世界模型(Executable Knowledge Representation)。
4. **可执行知识图**:`.mq.md` 之间的 Markdown 链接天然长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
4. **链接即调用 / 可执行知识图**:`[描述](类.函数)` 既是文档链接,也是类/函数调用;编译器解析目标、校验签名、返回 LinkInfo;`view` 显示调用点;`.mq.md` 之间的链接长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
5. **知识可测试**:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
@@ -64,24 +145,30 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
---
## 语法速览(v0.3)
## 语法速览
| 标记 | 含义 |
|------|------|
| 无标记行 | 叙述(注释);行内 `` `名` `` 可声明 |
| `**…**` | **代码**(赋值 / 调用 / 表达式) |
| `[描述](表达式)` | **链接(本地)**:描述 + 代码;`()` 与 `**…**` 同权(默认语义) |
| `[描述](类.函数)` | **链接(跨文档/类调用)**:描述 + 已有类函数调用;可解析、可执行(v2.1 目标) |
| `[描述](url)` | 普通 Markdown 导航链接(惰性,不执行) |
| `*…*` | **返回值**(整行、`返回*n*`、或表达式形) |
| `****` / 整行 `**` / `*None*` | **空返回**(`None`),并结束本函数体 |
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
| `##` … | 函数 / 方法(按标题深度嵌套) |
| `#` | **类 / 类型**(知识命名空间;`# main` = 入口) |
| `##` … | **函数**(类下函数;使用 `self`/`自` 时为实例方法) |
| `类.函数` | **类调用**(不使用 `self` 的函数;v2.1 目标) |
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
| 表格 | 集合(几何即类型,见下);取元优先 `[键](集合)` |
| `-` | 循环(`` - `条件` `` 或 `` - [项](遍历 集合 为 项) ``) |
| 表格 | 集合(几何即类型,见下);取元使用 `access(集合, "键")` |
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
> `[键](集合)` / `- [项](集合)` 是旧取元/循环形;迁移后使用 `access(集合, "键")` 与 `- [描述](遍历 集合 为 项)`。旧形只在显式 `markup: classic` 或 `--legacy-markup` 过渡入口中保留,见 [link-syntax.md](doc/design/link-syntax.md)。
```markdown
# main
@@ -133,8 +220,9 @@ Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
```
`[]` 里是**自由描述**(不执行);`()` 里是**实现**(唯一执行)。这条语法叫**遮蔽**:
把不可读或未完成的实现藏到括号里,人读描述、机器读代码。
`[]` 里是**自由描述**(不执行);`()` 里是**目标**(唯一执行)。这条语法叫**链接语法**:
目标是本地表达式时,就是**遮蔽**(把代码折叠在括号里);目标是 `类.函数` 时,就是**跨文档类调用**。
v2.1 实现了文件级链接语义与可执行知识投影(见 [link-syntax.md](doc/design/link-syntax.md))。
**四条约定**
@@ -147,15 +235,15 @@ Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。
**盘点与门禁**
```bash
marqdo labels pending # 内置口径:还有多少未完成
marqdo labels search --grep "接口未联调,联调中" # 用你自己的说法
marqdo labels search --grep 联调 --also-builtin # 自定义 + 内置一起数
marqdo labels pending --count --baseline .marqdo/pending.json --fail-on-increase
marqdo labels --count # 内置口径:还有多少未完成
marqdo labels --grep "接口未联调,联调中" --count # 用你自己的说法
marqdo labels --grep 联调 --also-builtin --count # 自定义 + 内置一起数
marqdo labels --count --baseline .marqdo/pending.json --fail-on-increase
```
最后一条是**棘轮**:只拦"新增未完成",不追旧账。
设计依据:[occlusion-syntax.md](doc/design/occlusion-syntax.md) ·
设计依据:[link-syntax.md](doc/design/link-syntax.md) · [occlusion-syntax.md](doc/design/occlusion-syntax.md) ·
[occlusion-description-and-search.md](doc/design/occlusion-description-and-search.md)
---
@@ -193,9 +281,11 @@ marqdo catalog public -o .marqdo
---
## 现状(v2.0.0)
## 现状(v2.1.2)
- **遮蔽语法(v2.0.0)**:`[描述](实现)` 描述不执行 · `()` 内调用(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 遮蔽循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels` · 诊断 `label.missing` / `empty_payload` / `ref_dangling` · view 描述正文 + 代码片 + 桩徽章 · 扩展包同步 **2.0.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**
@@ -231,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.0.0)
### 如何使用最新 Marqdo(v2.1.2)
**安装解释器(任选其一)**
@@ -246,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.0.0 # 或留在 main
git checkout v2.1.2 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -285,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.0.0
# https://github.com/cflmy/marqdo/releases/tag/v2.1.2
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+2 -2
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "2.0.0"
version = "2.1.2"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
@@ -12,4 +12,4 @@ crate-type = ["cdylib", "rlib"]
[dependencies]
marqdo = { path = "../..", default-features = false, features = ["wasm-core"] }
serde_json = "1"
serde_json = "1"
+22
View File
@@ -1,3 +1,25 @@
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
standard/extension libraries and executable-knowledge projections.
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 12:00:00 +0000
marqdo (2.0.0-1ppa1) noble; urgency=medium
* Marqdo 2.0.0: Occlusion syntax — [description](payload), where the
+18 -2
View File
@@ -13,10 +13,18 @@
## 当前文档
> **可执行知识下一阶段的阅读顺序**:[原始意图 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) | **`#` 对象 / `##` 函数与方法** |
@@ -106,6 +114,13 @@
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
| [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 |
| [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 |
| [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 计划 |
| [design/label-freshness-and-repair.md](design/label-freshness-and-repair.md) | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 |
@@ -114,6 +129,7 @@
| [design/t1-session-staleness.md](design/t1-session-staleness.md) | 会话内陈旧检测:为何模型在结构上收不到重复警告 |
| [tutorial/15-常见陷阱.md](tutorial/15-常见陷阱.md) | **使用向陷阱手册**:行首数字、跨函数作用域、空格函数名、导入路径、`table.put` 非原地(1.5.2 实测) |
| [research/qdagent-refactor-defects-2026-10.md](research/qdagent-refactor-defects-2026-10.md) | **qdagent 重构期缺陷实录 D1–D7**(沙箱 profile 不生效 · 全角 CALL 静默丢失 …) |
| [research/occlusion-vs-executable-knowledge-2026-10.md](research/occlusion-vs-executable-knowledge-2026-10.md) | **遮蔽 vs 可执行知识复核**:v2.0.0 的 `[]()` 只做了呈现层 · 两文档例子实测不可执行 · `check`/`labels`/图边工程漂移证据 · 原始设计=类-函数调用(见 link-syntax) |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
@@ -1,5 +1,7 @@
# 语义评估:参数能否从上下文推断(含叙述式调用)
> **2026-10-23 审阅裁决**:保留参数来源可见、避免隐藏调用者环境的边界;下文已被否决的 L0 建议不可重新启用。自然语言只连接和解释,不能成为隐式执行触发器;当前指导见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **§3 的 L0 方案已被否决**(违反「只执行标记」原则);L1/L2 结论仍有效 |
+2 -1
View File
@@ -36,7 +36,8 @@ type: llm
model: ${env.OPENAI_MODEL ?? "gpt-4o-mini"}
api_key: ${secret.OPENAI_API_KEY!}
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
import sys:lib/sys.mq.md
import:
sys: lib/sys.mq.md
---
```
@@ -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 -1
View File
@@ -156,7 +156,8 @@ source: &str (+ optional import map)
```markdown
---
import json:lib/json.mq.md
import:
json: lib/json.mq.md
---
# main
+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`)
+1 -1
View File
@@ -80,7 +80,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
| **clap** | CLI | `marqdo run [path]` |
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;嵌套 `import:` 映射与其它 YAML 键一并解析 |
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
| **regex** (=1.13.1) | 正则 | Mid M1 `lib/re`;`default-features=false` + `std`/`unicode`;无回溯引用 |
| **sha2** (=0.10.9) / **sha1** (=0.10.6) / **md-5** (=0.10.6) / **hmac** (=0.12.1) | 摘要 | Mid M3 `lib/hash` |
@@ -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
+206
View File
@@ -0,0 +1,206 @@
# 可执行知识系统:`[]()` 的统一语法与跨文件闭环
| | |
|---|---|
| 状态 | **Design Draft · v2.1 语义重构** |
| 核心判断 | `[]()` 不是“普通代码”与“知识链接”的分界;每一个 `[]()` 同时是代码、文档和知识图节点。 |
| 关联 | [link-syntax.md](link-syntax.md) · [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) |
| 示例 | [examples/executable-knowledge/](../../examples/executable-knowledge/) |
---
## 0. 一句话
> **`[名称](载荷)` 是一个命名的可执行知识步骤:`()` 做原有的任何事,`[]` 说明这一步对人意味着什么;编译器把它们一起编入知识图。**
它不增加、替代或限制 payload 语法。字典取元、表操作、算术、函数调用、嵌套调用、遍历/循环、
甚至受控副作用,都保留原有解释器语义。差别只在于:原来不可见的一步现在获得一个稳定的人话名字、
源位置、输入/输出、依赖和影响范围。
```text
代码投影: eval([名称](载荷)) = eval(载荷)
文档投影: 读者看到 名称,必要时展开载荷、输入与输出
知识投影: 编译器生成 KnowledgeStep(名称, 载荷, 依赖, 类型, 效果, 来源位置)
```
这三种投影缺一不可。只保留前两者是“带标签的代码”;只保留后两者会牺牲可运行性;
三者同源,才是代码即文档、文档即知识、知识即可执行。
---
## 1. 统一节点:`Named<T>`
`[]()` 的正确抽象不是“链接调用”,而是泛型 AST 装饰器:
```text
Named<T> { label, inner: T, span }
```
`T` 是它出现位置原有的语法节点,绝不另造“知识表达式” parser:
| 既有位置 | `T` | 示例 | 知识角色 |
|---|---|---|---|
| 表达式 | `Expr` | `[收件人](at(订单, "收件人"))` | 观测/取值 |
| 表达式 | `Expr` | `[含税价](金额 * (1 + 税率))` | 推导 |
| 表达式 | `Expr` | `[适用税率](税率.查询(地区, 品类))` | 复用/查询 |
| 遍历位置 | `LoopSpec` | `[逐个订单行](遍历 订单.行 为 行)` | 过程/展开 |
| 正文位置 | `InlinePayload` | `订单总额为[含税总价](定价.总额(订单))。` | 叙述中的可执行槽 |
| URL/路径 | `NavigationLink` | `[税率原文](corpus/tax.md)` | 导航/证据定位 |
运行时只执行 `inner`;`label` 不进符号表、不改变作用域、不重复计算。与此同时,
parse/check/catalog 保留整个 `Named<T>`。所以循环不会被误判成“返回一个事实”,取元也不会
被迫拥有来源表;但两者都能在图中被看见、被搜索、被影响分析。
### 1.1 每个节点都有角色,而不是两套语法
角色由既有 AST、类型、效果和依赖推导,必要时由所在 `#`/`##` 的契约约束:
| role | 如何识别 | `check` 应问什么 |
|---|---|---|
| `observe` | 取元、读取字段、读取表/文档 | 读什么、类型是什么、是否可用 |
| `derive` | 纯计算、聚合、映射 | 输入、输出、公式/依赖是否完整 |
| `reuse` | 调用已解析的 `##` / 模块能力 | 调用到哪个稳定符号、参数/返回是否匹配 |
| `iterate` | 已有遍历/循环载荷 | 遍历什么、绑定什么、循环体依赖什么 |
| `act` | 写入、请求、打印等副作用 | 权限、幂等性、影响目标 |
| `narrate` | 正文中的命名载荷 | 它在句中替代什么值、依赖是否可解析 |
一个节点可以有多个 role,例如 `[同步并记录](写入(...) + 记录(...))` 是 `act`,也依赖
若干 `observe`/`reuse` 节点。角色是编译结果,不是作者需要记忆的关键字。
---
## 2. 知识层不是目录隔离,而是同一图的不同投影
“几层知识”不应把语法和项目切断。它们是同一个 `Named<T>` 图中不同职责的节点;
同一份 `.mq.md` 可以同时有多层节点。
| 投影层 | 在统一图中的节点 | 由什么语法产生 | 它回答的问题 |
|---|---|---|---|
| **E 证据** | 原文、数据、文件/表读取节点 | Markdown 链接、`at(...)`、读取调用 | 事实从哪里来? |
| **C 概念** | 类型、字段、术语、约束 | `#`、字段/契约表 | 这些值是什么意思、能否组合? |
| **K 原子知识** | 命名个体、事实、规则 | `# 个体`、`##`、`Named<Expr>` | 哪个可调用单元给出什么知识? |
| **D 推导知识** | 聚合、计算、决策、工作流步骤 | 任意 `Named<Expr>` / `Named<LoopSpec>` | 如何从已有知识得到新结论/行动? |
| **N 叙述知识** | 段落与正文调用槽 | 正文 `Named<InlinePayload>` | 如何把结论说给人或 agent? |
同一条边可以跨层:`[出生年份](at(人物表, "出生年份"))` 同时是 E 的观测、K 的事实值和
可被 N 层引用的节点。`[逐个订单行](遍历...)` 是 D 的过程知识,也为其内部每个推导提供上下文。
这正是通用语法本身兼容知识体系的含义。
### 2.1 `#` / `##` 的位置
- `#` 给一组知识步骤提供可读命名空间、类型/个体语义和文档边界;
- `##` 给可复用步骤提供稳定的公开入口、参数与返回契约;
- `[]()` 给入口内部的**每一小步**命名,并将它们暴露给文档、图和工具;
- `> 类型` 仍只构造运行时实例;知识个体不等于运行时 map。
因此 `## 含税总额` 不是黑盒函数:其函数体中的 `[订单行](...)`、`[逐行计税](遍历...)`、
`[汇总](sum(...))` 都是可检索、可解释、可追踪的知识步骤。函数是知识单元的边界,
`[]()` 是知识单元的内部结构。
---
## 3. 大项目的寻址:可读短名与稳定身份同时成立
全局只靠 `# 李白` 寻址在大项目中不可行:同名、重命名和加载顺序都会让图不稳定。
但这不意味着作者要失去 `李白.出生年份` 的自然语言体验。
1. 文件的既有 frontmatter `id` 是稳定身份;
2. 现有 `import bind:target` 是代码中的规范加载/寻址;
3. `#` / `##` 是人可读的路径段;
4. 正文短地址由 catalog 发现,解析成功后写入 LinkInfo/lock 的稳定 `symbol_id`;歧义必须报错。
```markdown
---
id: knowledge.people.li-bai
import:
li_bai: knowledge/people/li-bai.mq.md
---
# 回答
**year = [李白的出生年份](li_bai.李白.出生年份)**
李白出生于[公元 701 年](李白.出生年份)。
```
第一处是可运行代码,使用显式 import;第二处是正文的发现地址。它们编译后都指向
`knowledge.people.li-bai::李白.出生年份`。短地址从来不是“按项目扫描第一个名字”,
而是可读的查询,必须由 lock 固化。
---
## 4. 每个 `[]()` 产生统一的知识记录
不要把 LinkInfo 固定成单一的 `target`。任意载荷都可能含有多个读、写、调用和循环依赖:
```json
{
"label": "逐个订单行",
"payload_kind": "loop",
"roles": ["iterate"],
"source": {"file": "capabilities/order-pricing.mq.md", "line": 22},
"inputs": ["订单.行"],
"outputs": ["行"],
"dependencies": [
{"kind": "local_value", "path": "订单.行"},
{"kind": "symbol", "id": "capability.order-pricing::订单定价.含税价"}
],
"effect": "pure",
"fingerprint": "sha256:…"
}
```
此记录就是统一知识图节点:
- 本地取元有输入/类型边;
- 纯计算有输入/输出/公式边;
- 循环有集合、变量绑定和循环体边;
- 调用有 `calls`/`uses` 边;
- 有来源的事实再增加 `derived_from` 边;
- 正文节点有 `narrates` 边,连接它所在句子和计算结果;
- 副作用节点有权限/影响目标边,不能被 `view` 或 `verify` 静默执行。
来源不是每个节点的前提,而是图中的一种边。没有来源的字典取元仍是知识步骤;
若它最终支撑对外事实,沿依赖链应能找到来源,否则在“发布/验证事实”时才报证据不足。
---
## 5. 闭环:写、跑、看、查、变
```text
作者写 Named<T>
│
├─ run:擦除 label,按原语义执行
├─ view:显示 label,可展开值、输入、步骤和来源
└─ check:解析所有依赖,编译统一知识图
│
catalog / lock / context pack
│
来源、规则、代码任一变化 ── impact / verify ──> 所有受影响 Named<T> 与叙述句子
│
作者或 agent 修复后重新 check/verify
```
### 5.1 命令边界
| 操作 | 做什么 | 不做什么 |
|---|---|---|
| `run` | 执行代码位置的原 payload | 不因为正文出现 `[]()` 而执行副作用 |
| `check` | 建图、解析类型/符号/依赖、检查 label 漂移 | 不求值、不伪造运行结果 |
| `view` | 呈现命名步骤及可选值/来源 | 静态模式不执行;live 模式遵守 effect 权限 |
| `verify` | 在沙箱中重算 pure 节点、核对来源/指纹 | 不执行 `act` 节点 |
| `impact` | 从变更节点反查依赖、函数、文档 span | 不按文本猜测关系 |
这样,任意通用代码一开始就属于知识图;只有在执行/验证权限上分级,而不是在语法上被分裂。
---
## 6. 实施顺序
1. 在表达式、遍历和正文三处统一保留 `Named<T>`;payload 复用各自现有 parser。
2. 为任意 `Named<T>` 提取 `inputs`、`outputs`、`dependencies`、`effect`、`roles`;从单 target 演进为依赖集合。
3. 让 `#`/`##` 契约为内部步骤提供类型/公开边界;让 frontmatter `id` + import 提供跨文件稳定解析。
4. 把现有 EKC 图扩展为步骤图:`observes`、`derives`、`iterates`、`calls`、`acts`、`narrates`、`derived_from`。
5. 接入 `check`、`view`、`verify`、`impact` 与 lock;让一次变更能回到具体的 `[]()` 和具体句子。
验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的
取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。**
+2 -1
View File
@@ -61,7 +61,8 @@ Unknown names fail. Queries are only valid during a plugin function call (host s
```markdown
---
import plugin:lib/plugin.mq.md
import:
plugin: lib/plugin.mq.md
---
# main
+6 -5
View File
@@ -159,11 +159,12 @@ REPLACE
```markdown
---
title: agent-run-…
import llm:ext/ai/llm.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
import writeback:lib/writeback.mq.md
import subtask:lib/subtask.mq.md
import:
llm: ext/ai/llm.mq.md
agent: ext/ai/agent.mq.md
json: lib/json.mq.md
writeback: lib/writeback.mq.md
subtask: lib/subtask.mq.md
---
# 总目标
+5 -4
View File
@@ -72,10 +72,11 @@ Marqdo 的宪法是 **代码即文档、文档即知识库**:
```markdown
---
导入 智能体:ext/ai/智能体.mq.md
导入 大模型:ext/ai/大模型.mq.md
导入 自写回:lib/自写回.mq.md
导入 时间:lib/时间.mq.md
导入:
智能体: ext/ai/智能体.mq.md
大模型: ext/ai/大模型.mq.md
自写回: lib/自写回.mq.md
时间: lib/时间.mq.md
---
## 获取时间
+2 -1
View File
@@ -197,7 +197,8 @@
````markdown
---
import la:ext/linalg/linalg.mq.md
import:
la: ext/linalg/linalg.mq.md
---
# 转置反序
+3 -2
View File
@@ -201,8 +201,9 @@ $$
````markdown
---
import la:ext/linalg/linalg.mq.md
import table:lib/table.mq.md
import:
la: ext/linalg/linalg.mq.md
table: lib/table.mq.md
---
# main
+2 -1
View File
@@ -20,7 +20,8 @@ Import:
```markdown
---
import llm:ext/ai/llm.mq.md
import:
llm: ext/ai/llm.mq.md
---
```
+4 -2
View File
@@ -101,7 +101,8 @@ marqdo ext add quantum
```markdown
---
import quantum:ext/quantum/quantum.mq.md
import:
quantum: ext/quantum/quantum.mq.md
---
```
@@ -341,7 +342,8 @@ Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-
```markdown
---
title: Bell state
import quantum:ext/quantum/quantum.mq.md
import:
quantum: ext/quantum/quantum.mq.md
---
# Bell |Φ+⟩
+5 -3
View File
@@ -62,8 +62,9 @@ route: /
method: GET
data_source: posts
data_order: -created_at
import web:ext/web/web.mq.md
import data:ext/data/db.mq.md
import:
web: ext/web/web.mq.md
data: ext/data/db.mq.md
---
# Marqdo
@@ -106,7 +107,8 @@ path: /api/posts
request: json
response: json
auth: member
import data:ext/data/db.mq.md
import:
data: ext/data/db.mq.md
---
**post = > data.db.insert …**
+2 -1
View File
@@ -49,7 +49,8 @@
英文:
```markdown
import web:ext/web/web.mq.md
import:
web: ext/web/web.mq.md
# main
+16 -14
View File
@@ -128,13 +128,14 @@ myapp/
---
title: web-site
description: Home = page table; main may be inline; class methods assemble.
import web:ext/web/web.mq.md
import shell:styles/shell.mq.md
import nav:components/nav.mq.md
import side:components/side.mq.md
import foot:components/foot.mq.md
import articles:db/articles.mq.md
import db:db/index.mq.md
import:
web: ext/web/web.mq.md
shell: styles/shell.mq.md
nav: components/nav.mq.md
side: components/side.mq.md
foot: components/foot.mq.md
articles: db/articles.mq.md
db: db/index.mq.md
---
# main
@@ -171,13 +172,14 @@ Main content is not a reusable component, so it is authored here.
```markdown
---
title: 站点
导入 网页:ext/web/网页.mq.md
import shell:styles/shell.mq.md
import nav:components/nav.mq.md
import side:components/side.mq.md
import foot:components/foot.mq.md
import articles:db/articles.mq.md
import db:db/index.mq.md
导入:
网页: ext/web/网页.mq.md
shell: styles/shell.mq.md
nav: components/nav.mq.md
side: components/side.mq.md
foot: components/foot.mq.md
articles: db/articles.mq.md
db: db/index.mq.md
---
# main
@@ -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 · 待决策**(未修改任何代码) |
+443
View File
@@ -0,0 +1,443 @@
# 知识分层:原始语料、可执行知识、调用面
| | |
|---|---|
| 状态 | **Design Review · Recommended(v2.1 语法设计评审)** |
| 日期 | 2026-10-23 |
| 问题 | 「诗人类 → 用李白知识实例化 → `[]()` 调用」的三/四层模型,从**语法设计**上是否自洽? |
| 推荐 | **单体知识类(singleton knowledge class)**:`# 诗人` 是类,`# 李白 = > 诗人` 是知识个体;`李白.出生年份` 是类调用;零新语法 |
| 关联 | [link-syntax.md](link-syntax.md) · [objects.md](objects.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) · [okf.md](okf.md) |
| 示例 | [examples/knowledge-layers/](../../examples/knowledge-layers/) |
---
## 0. 结论先行
### 0.1 一句话
> **分层逻辑是自洽的;不自洽的是「实例化」这个词与当前 `#`/`= >` 语法。**
> 如果「实例化」指**知识个体**,用 `# 李白 = > 诗人` 编码即可,零新语法;
> 如果「实例化」指**运行时对象**,就需要新的可寻址实例声明/注册表,语法成本明显更高。
### 0.2 三层 / 四层:推荐四层
| 层 | 名称 | 内容 | 语法载体 |
|----|------|------|---------|
| **L0** | 原始语料 | 原文、出处、引用、版本 | `.md` / `.mq.md` 叙述 + `来源` 表 |
| **L1** | 本体 / 模式 | 类、字段、类型、约束 | `# 诗人` + 字段/类型表 |
| **L2** | 可执行知识 | 知识个体、事实、返回值、出处 | `# 李白 = > 诗人` + `## 出生年份` + `*701*` |
| **L3** | 调用面 | 链接、类调用、view、LinkInfo、EKC、agent | `[出生年份](李白.出生年份)` |
三层版可以把 L1/L2 合并为「可执行知识体系」;四层版把**本体**与**个体**分开,正好对应 EKC 的 schema/knowledge 分层。
### 0.3 核心判断
| 判断 | 结论 |
|------|------|
| 原始语料 → 可执行知识 → 调用面,逻辑成立 | ✅ |
| 可执行知识能还原/验证回原始语料 | ✅ 需要出处/校验约定,语法上可行 |
| `# 诗人` 是类 | ✅ 现有 `#` 语义 |
| `# 李白 = > 诗人` 是「实例化」 | ⚠️ **语法上是继承/特化,不是运行时实例化** |
| `李白.出生年份` 是类调用 | ✅ 需要类函数 + 项目类索引(v2.1 目标) |
| `[]()` 是调用面,不新增语法 | ✅ `[描述](类.函数)` = 描述 + 已有调用 |
---
## 1. 你的模型(精确复述)
1. 有一个**诗人**类(`# 诗人`),定义诗人应该有什么字段/函数;
2. 用**李白的知识**把这个类「实例化」:
- 李白是诗人;
- 李白有姓名、出生年份等事实;
3. 通过 `[]()` 链接语法调用这个知识:
- `[出生年份](李白.出生年份)`;
4. 整个体系分层:
- 原始语料;
- 改写/抽象后的可执行知识(可还原验证回原始知识);
- 智能体回答/思考时的调用面。
这个模型在**知识架构**上没有问题;问题只在第 2 步的「实例化」如何落到语法。
---
## 2. 当前语法事实
| 语法 | 当前语义 | 对模型的影响 |
|------|---------|-------------|
| `# 诗人` | 类/类型;正文是构造体 | ✅ 可做本体 |
| `# 李白 = > 诗人` | **继承/子类**;不是实例 | ⚠️ 与「实例化」字面不符 |
| `## 李白的出生年份` | 方法;可用 `self`/`自` | ⚠️ 当前是实例方法 |
| `> 李白` | 构造实例(map + `_type`) | ✅ 运行时实例 |
| `李白.李白的出生年份` | 当前被当变量/实例方法路径 | ❌ 类调用未实现 |
| `[描述](...)` | 描述 + 表达式 | ✅ 调用面 |
| `import` | 跨文档绑定 | ⚠️ 当前跨文档继承/调用需 import |
**实测**(`marqdo 2.0.0`):
- `# 李白 = > 诗人` 在**另一个文档**定义 `# 诗人` 时,未 import 会报 `unknown base type 诗人`;
- import 后可以继承,但调用仍需 `> libai.李白` 构造实例,再 `` `li`.李白的出生年份() `` → `701`;
- `李白.李白的出生年份` 直接调用报 `undefined variable`;
- 跨文档类索引不存在。
所以「诗人类 → 李白实例 → 链接调用」在**目标模型**上成立,在**当前语法**上只完成了「类 + 继承 + 实例方法」,缺「类调用 + 类索引」。
---
## 3. 自洽性检查:逐层
### 3.1 L0 原始语料
| 问题 | 结论 |
|------|------|
| 原始语料是否可执行? | 否;它是出处,不是程序 |
| 能否被引用? | ✅ 现有 Markdown 相对链接/`来源` 表 |
| 能否保留原文? | ✅ 叙述、引用块、表格 |
| 语法负担 | 零:就是现有文档 |
**要点**:原始语料必须保持「不可执行」的独立身份;一旦把原文改写成代码,就失去了「还原验证」的基准。所以 L0 与 L2 要**物理/逻辑分离**(`corpus/` vs `knowledge/`)。
### 3.2 L1 本体 / 模式
```markdown
# 诗人
| 字段 | 类型 | 说明 |
|------|------|------|
| 姓名 | text | 诗人姓名 |
| 出生年份 | number | 公元年份 |
```
| 问题 | 结论 |
|------|------|
| `# 诗人` 能否表达类? | ✅ `#` 就是类/类型 |
| 字段/类型能否表达? | ✅ 现有表格 + 契约表 |
| 是否需要新语法? | ❌ 不需要;用字段/类型表的列名约定 |
| 是否能被检查? | 需要新增 `knowledge.schema_*` 检查(工具,不是语法) |
**语法结论**:L1 完全用现有 `#` + 表格;只需要约定「字段表」的列名与语义。
### 3.3 L2 可执行知识:关键歧义
「用李白的知识实例化诗人」有两种落法:
#### A. 单体知识类(推荐)
```markdown
# 李白 = > 诗人
## 李白的出生年份
*701*
```
- 语法:`# 李白 = > 诗人` = 继承/特化;
- 语义:李白是诗人(is-a),并且 `# 李白` 是一个**命名的知识个体**;
- 调用:`李白.李白的出生年份` = 类调用(不使用 `self` 的函数);
- 地址:`# 李白` 是文档里的稳定类名,可被项目类索引解析;
- 运行时:如果需要 map,仍可 `> 李白` 构造实例;
- 代价:**术语上不是「实例」**,是「单体类/知识个体」。
#### B. 运行时实例(不推荐作为 v2.1 语法)
```markdown
# 诗人
## 李白
*> 诗人 姓名="李白" 出生年份=701*
```
- 语法:`## 李白` 是函数,返回一个实例 map;
- 调用:`李白().出生年份`(函数返回实例,再取方法);
- 地址:`李白` 是函数名,不是实体;跨文档要函数索引/缓存;
- 代价:每次调用可能新构造实例;没有稳定的知识实体地址;EKC 节点是函数,不是个体;
- 需要:实例注册表/导出机制,或函数级索引;这比 A 多一层运行时概念。
#### C. 显式个体声明(未来可选)
```markdown
# 李白 : 诗人
```
- `:` 明确「李白是诗人个体」;
- 语法更贴近本体(instance-of),但**新增一个标记**;
- 与 `# Child = > Parent` 形成两种关系,需要决定何时用哪种;
- 不建议 v2.1 引入;可作为 v2.2 的候选。
### 3.4 L3 调用面
```markdown
[出生年份](李白.李白的出生年份)
```
| 问题 | 结论 |
|------|------|
| `[]` 是描述、`()` 是调用? | ✅ 现有语义 |
| `()` 与 `**` 同权? | ✅ 同一 parser/evaluator |
| 跨文档类名能否解析? | 需要项目类索引(v2.1) |
| 正文链接是否执行? | view/check 解析;run 不执行(安全) |
| 终端输出? | 代码链接 + `print` |
| 编译器能否返回 LinkInfo? | 需要新增(工具,不是语法) |
| view 能否显示调用点? | 需要新增(工具,不是语法) |
**语法结论**:L3 不需要新语法;缺的是**解析器/类索引/视图/编译器输出**。
---
## 4. 推荐模型:单体知识类
### 4.1 定义
> **单体知识类**:一个 `# 名称 = > 父类` 的类,代表一个知识个体;它的 `##` 函数是该个体的知识字段/事实;它不需要运行时实例即可被 `类.函数` 调用。
```markdown
# 诗人
| 字段 | 类型 | 说明 |
|------|------|------|
| 姓名 | text | 诗人姓名 |
| 出生年份 | number | 公元年份 |
# 李白 = > 诗人
## 李白的出生年份
| 返回 | 类型 | 来源 |
|------|------|------|
| 701 | number | corpus/libai.md#出生年份 |
*701*
```
调用:
```markdown
# main
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
输出:`701`。
### 4.2 为什么推荐 A
| 维度 | A 单体类 | B 运行时实例 |
|------|---------|-------------|
| 语法新增 | **零** | 需要实例导出/注册/函数索引 |
| 地址稳定 | ✅ 类名 | ❌ 函数返回值 |
| 跨文档 | ✅ 项目类索引 | ❌ 需要实例注册表 |
| EKC 映射 | ✅ 文档/类/函数节点 | ❌ 实例不是文档节点 |
| 可还原 | ✅ 类/函数 + 来源表 | ⚠️ 实例是运行时值 |
| 可检查 | ✅ 类/函数/契约 | ⚠️ 实例状态难静态检查 |
| 术语 | ⚠️ 叫「个体」不叫「实例」 | ✅ 叫实例 |
| 多实例 | ⚠️ 每个个体一个类 | ✅ 自然 |
**结论**:在「文档即知识库」的约束下,A 的语法成本最低、可检查性最好;B 的「实例」语义更纯,但需要新的运行时/注册表,和「零新语法」冲突。
### 4.3 术语约定
| 术语 | 含义 | 语法 |
|------|------|------|
| **类 / 本体** | 诗人的模式 | `# 诗人` |
| **知识个体(单体类)** | 李白这个知识实体 | `# 李白 = > 诗人` |
| **知识字段 / 事实** | 李白的出生年份 | `## 李白的出生年份` + `*701*` |
| **类调用** | 读取知识个体的字段 | `李白.李白的出生年份` |
| **运行时实例** | 代码里 `> 李白` 得到的 map | `> 李白` / `_type` |
| **知识链接** | 描述 + 类调用 | `[出生年份](李白.李白的出生年份)` |
> **重要**:语法文档里不要再用「实例化」描述 `# 李白 = > 诗人`;用「知识个体化/单体类」。
> 「实例」保留给运行时 `> 诗人` 产生的 map。这样语法、文档、EKC 三者才一致。
### 4.4 多诗人怎么办
```markdown
# 李白 = > 诗人
# 杜甫 = > 诗人
# 王维 = > 诗人
```
- 每个个体是一个单体类;项目类索引登记它们;
- `李白.出生年份` / `杜甫.出生年份` 分别解析;
- 这是「命名个体注册表」,不是运行时实例集合;
- 如果个体成千上万,类索引会变大;v2.2 可引入表驱动的个体注册(但不改变调用语法)。
---
## 5. 与 EKC 的映射
| 层 | EKC 层 | 节点/边 |
|----|--------|---------|
| L0 原始语料 | Repository / sources | `documented_by` / `derived_from` |
| L1 本体 | Capability / Schema | `# 诗人` class 节点 |
| L2 知识个体 | Knowledge / Symbol | `# 李白` class 节点 + `##` fact 节点;`specializes` 边 → `诗人` |
| L3 调用面 | Symbol / Capability | `[]()` 链接 → `calls` 边;LinkInfo |
| L4 Agent | Agent / Context Pack | `find`/`reuse`/`link.resolve` |
**新增边(建议)**:
- `specializes`:`# 李白 = > 诗人`(语法上是继承;知识语义上是 is-a);
- `derived_from`:fact → 原始语料;
- `calls`:调用文档 → `李白.出生年份`;
- `has_fact`:`# 李白` → `## 出生年份`。
EKC 现有 `depends_on`/`uses`/`implements`/`documented_by` 可以复用;`specializes` 建议新增。
---
## 6. 还原 / 验证(L2 → L0)
「可执行知识能还原验证回原始知识」需要三件事:
### 6.1 出处是数据,不是注释
```markdown
## 李白的出生年份
| 返回 | 类型 | 来源 |
|------|------|------|
| 701 | number | corpus/libai.md#出生年份 |
*701*
```
- `来源` 列指向原始语料(路径 + 标题/锚点);
- 也可以放 frontmatter `sources:`;
- `check` 验证来源存在;`verify` 验证值/引文一致(能自动化的部分)。
### 6.2 可还原的渲染
- `view` 把 `# 李白` 渲染成「知识文档」:字段 + 值 + 来源;
- `catalog` 生成 OKF `Fact` 页,`resource:` 指向 `.mq.md`;
- 渲染结果与原始语料可人工/机器对照;
- 这不是新语法,是 view/catalog 的输出。
### 6.3 漂移检查
| 诊断 | 触发 |
|------|------|
| `knowledge.source_missing` | 事实没有来源 |
| `knowledge.source_dangling` | 来源路径/锚点不存在 |
| `knowledge.value_mismatch` | 事实值与来源引文不一致(可自动判断时) |
| `knowledge.schema_mismatch` | `# 李白` 字段与 `# 诗人` 不匹配 |
| `knowledge.fact_drift` | 原始语料变了,知识未复核 |
这些是**工具诊断**,不是语法。
---
## 7. 调用面:智能体如何使用
```markdown
# main
用户想知道李白的出生年份,我们回答:[李白的出生年份](李白.李白的出生年份)
```
- `view` 显示:`李白.李白的出生年份` → `701` → 来源 `corpus/libai.md#出生年份`;
- `check --json` 返回 LinkInfo(class/function/value/source);
- agent 通过 `link.resolve` / `find` 取到值 + 出处,回答时可引用来源;
- `run` 加 `print` 才输出;正文链接不执行,保证叙述安全。
**这就是「调用面」**:不是自然语言猜,而是可解析、可验证、可引用的类调用。
---
## 8. 反例与边界
| 场景 | 用 A 单体类 | 说明 |
|------|-----------|------|
| 李白、杜甫、王维 | 三个单体类 | 类索引;命名个体 |
| 同一诗人的多个版本 | 多个事实/来源,或子个体 | 版本是事实维度,不是实例 |
| 需要运行时状态(可变对象) | `> 李白` 构造实例 | 运行时实例仍存在,但与知识个体分离 |
| 上千个诗人 | 类索引/表驱动注册 | v2.2 优化;语法不变 |
| 需要 `instanceof` | `# 李白 = > 诗人` 的 `specializes` 边 | 知识语义;不是运行时 `_type` |
| 需要多继承 | 现有不支持 | 不在本设计范围 |
---
## 9. 决策建议
1. **v2.1 采用 A(单体知识类)**:`# 诗人` + `# 李白 = > 诗人` + `##` 事实 + `[]()` 类调用;零新语法。
2. **术语冻结**:`# 李白 = > 诗人` 叫「知识个体/单体类」,不叫「实例」;`> 诗人` 才是运行时实例。
3. **补类函数与类索引**:不使用 `self` 的 `##` 是类函数;项目类索引解析跨文档 `李白`。
4. **补出处/验证**:`来源` 列或 `sources:`;`check`/`verify`;`view`/`catalog` 可还原。
5. **EKC 边**:`specializes` / `derived_from` / `calls` / `has_fact`。
6. **保留 B/C 作为未来**:如果真需要运行时实例/个体声明,再评估 `# 李白 : 诗人` 或实例注册表;不在 v2.1 引入。
### 9.1 备选:frontmatter 个体声明(零语法,但换元数据)
如果不想把 `= >` 的继承语义借给「个体」,可以用 frontmatter 标记:
```markdown
---
type: Individual
class: 诗人
id: libai
---
# 李白
## 出生年份
*701*
```
| 维度 | 单体类 A | frontmatter 个体 |
|------|----------|------------------|
| 可见性 | `# 李白 = > 诗人` 一眼可见 | 类型在 frontmatter,正文只看到 `# 李白` |
| 语法 | 现有 `= >` | 现有 frontmatter,无新标记 |
| 语义纯度 | 继承/特化 | 明确 individual-of |
| EKC | class + specializes | individual + instance_of |
| 代价 | 术语「个体」不是「实例」 | 两套 is-a 表达(`= >` 与 `class:`)需要约定 |
**建议**:v2.1 先用 A(可读、零语法);如果 EKC/本体需要严格区分 class/individual,再启用 frontmatter `type: Individual`,并规定「`= >` 只用于类-类,个体用 frontmatter」。
---
## 10. 结论
> **三层/四层模型自洽;「实例化」是唯一需要修正的词。**
> 在 Marqdo 的语法里,`# 李白 = > 诗人` 是**继承/特化**,不是运行时实例;
> 把它用作**单体知识类**,就能在不新增语法的情况下得到「李白是诗人、李白有出生年份、`李白.出生年份` 可调用」。
> 这正是 EKC 的「文档即知识、知识可执行」:**类是本体的地址,单体类是知识个体的地址,`[]()` 是调用面。**
---
## 附录 A:一页对照
```markdown
# L1 本体
# 诗人
| 字段 | 类型 | 说明 |
| 姓名 | text | ... |
| 出生年份 | number | ... |
# L2 知识个体(单体类)
# 李白 = > 诗人
## 李白的出生年份
| 返回 | 类型 | 来源 |
| 701 | number | corpus/libai.md#出生年份 |
*701*
# L3 调用面
[李白的出生年份](李白.李白的出生年份)
```
| 层 | 语法 | 语义 |
|----|------|------|
| L0 | `.md` 原文 + 来源 | 不可执行 |
| L1 | `# 诗人` + 字段表 | 类/模式 |
| L2 | `# 李白 = > 诗人` + `##` + `*701*` | 知识个体/事实 |
| L3 | `[描述](类.函数)` | 类调用/链接 |
| 运行时 | `> 诗人` / `> 李白` | map 实例(可选) |
## 附录 B:与现有文档的关系
| 文档 | 关系 |
|------|------|
| [link-syntax.md](link-syntax.md) | 调用面的语法;本文补知识分层与单体类 |
| [objects.md](objects.md) | `#`/`##`/`= >` 的对象模型;本文把 `= >` 用于知识个体 |
| [module-namespace.md](module-namespace.md) | 跨文档解析;本文用项目类索引 |
| [engineering-knowledge.md](engineering-knowledge.md) | EKC L0–L4;本文映射到四层 |
| [okf.md](okf.md) | Fact/Concept/路径即身份;本文的 L2 与 Fact 对应 |
+799
View File
@@ -0,0 +1,799 @@
# 链接语法:命名载荷、类-函数调用与可执行知识
| | |
|---|---|
| 状态 | **Design Review · v2.1 语义重构(v2.0.0 仅实现本地表达式链接)** |
| 日期 | 2026-10-23 |
| 定位 | `[]()` **不新增语法**:它是 Markdown 链接 + 已有表达式 + 已有 `#`/`##` 类/函数模型的组合;它为任意既有载荷附上人话名称,并产出 view/compiler/知识图元数据 |
| 取代/扩展 | 取代 [occlusion-syntax.md](occlusion-syntax.md) 的「遮蔽」单一框架;把「遮蔽」保留为**显示属性** |
| 证据复核 | [occlusion-vs-executable-knowledge-2026-10.md](../research/occlusion-vs-executable-knowledge-2026-10.md) |
| 示例 | [examples/link-syntax/](../../examples/link-syntax/) |
| 关联 | [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [engineering-knowledge.md](engineering-knowledge.md) · [view.md](view.md) |
---
## 0. 设计声明
### 0.1 一句话
> **`[]()` 本身不制作新语法。**
> `[]` 是 Markdown 链接的可见文本;`()` 是**已经存在的 Marqdo 代码**,与 `**代码**` 同权。
> `#` 是类,`##` 是函数;`类.函数` 就是类调用。
> 链接把「一次已有载荷」写进文档,并为它附上一个人话名称;view 显示步骤与依赖,编译器返回链接信息。
### 0.1.1 还缺的一步:链接是「命名的可执行步骤」
`()` 可以是任意既有语法:取元、计算、调用、表操作、嵌套表达式或遍历/循环载荷。
所以 `[]()` 不能只被定义成“事实主张 + 函数调用”;那会把通用语法割裂在知识体系之外。
> **`[名称](载荷)` 是命名的可执行步骤:`()` 按原语义执行,`[]` 说明这一步对人意味着什么;编译器把整个步骤写入知识图。**
它始终同时有三种投影:
| 投影 | 规则 | 目的 |
|------|------|------|
| **代码投影** | `execute([label](payload)) = execute(payload)` | 与裸 payload 共用 parser/evaluator,结果、效果和执行代价不变 |
| **文档投影** | 保留 `label` 与所在句子/代码块 | 读者先读每一步的意图,必要时再展开实现 |
| **知识投影** | 产出 `KnowledgeStep { label, kind, inputs, outputs, dependencies, effect, span }` | 让取元、计算、循环、调用和叙述都可检索、解释、验证和影响分析 |
`label` 不进符号表、不改变作用域,也不替 `payload` 背书为“事实”;但它绝不是可丢弃的显示文字。
它是这段代码的人话接口。`payload` 提供操作,`label` 提供意图,二者共同形成可执行知识步骤。
例如:
```markdown
**name = [订单收件人](at(订单, "收件人"))**
**gross = [含税金额](金额 * (1 + 税率))**
- [逐个订单行](遍历 订单.行 为 行)
订单总额为[含税总价](定价.订单定价.含税总价(订单))。
```
它们分别是观测、推导、过程和叙述调用;四者使用同一个 `[]()`,在运行时都复用已有载荷语义,
但在图中拥有不同的输入/输出/依赖/效果边。只有一条步骤最终支撑对外事实时,才沿其依赖链要求来源;
不能要求每一次取元或循环都伪造来源表。
这才同时实现三件事:
- **代码即文档**:函数内部的每一步都有可读意图,不是一个黑盒;
- **文档即代码**:正文中的命名步骤能解析到实际依赖和可选值;
- **知识即可执行**:项目中任意代码步骤都是统一知识图的一部分,来源/规则/函数变化可反查到具体步骤和句子。
完整的跨文件闭环、稳定寻址和层次投影见
[executable-knowledge-system.md](executable-knowledge-system.md)。
### 0.2 三个「不新增」
| 不新增 | 说明 |
|--------|------|
| **不新增链接专用协议前缀 / 别名** | `()` 里就是普通表达式/调用;跨文档代码复用现有 `import bind:target`,正文可用唯一短地址发现 |
| **不新增执行开关 / 模式关键字** | 不引入 frontmatter 别名或执行开关;解析靠已有类/函数/文档结构 |
| **不新增括号 / 标记** | 不引入 `[[...]]` / `@[...]` / `link:`;`[]()` 仍是 Markdown 链接形 |
**本文定义四件事**:
1. **语义**:`#`/`##` 如何形成类/函数,`类.函数` 如何成为类调用;`label` 如何命名任意既有载荷并形成知识步骤;
2. **解析**:`()` 与 `**代码**` 共用 parser/evaluator;跨文档按类索引解析;
3. **校验**:步骤的输入、输出、依赖、效果与来源边分开记录;变更后能定位受影响的代码和句子;
4. **呈现**:view 显示调用点与证据;编译器返回 LinkInfo;EKC 建边;lock 可选。
> **作者不需要学习新标记**:正文链接仍是 `[描述](...)`;`view`/`check` 多了一项「把 payload 解析成类/函数」的能力,而不是要求作者写协议前缀、别名或执行开关。
### 0.3 原始意图
第一个可执行文档:
```markdown
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
李白出生于*某年*
```
在 Marqdo 里:
- `# 李白` = **类**;
- `## 李白的出生年份` = 该类下的**函数**;
- `李白.李白的出生年份` = **类调用这个函数**。
> 注意:正文「李白出生于*某年*」是**叙述**;函数要可调用,需要显式返回值(`*701*` 或表,见 §2.6)。
第二个文档:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`。它不需要 `print`:
**view 模式天然显示 `()` 的调用信息**。如果要终端输出,加一行 `print` 即可:
```markdown
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
这不是两套语法,而是同一套语法的两种呈现:
- `**year = 李白.李白的出生年份**` 是代码;
- `[李白的出生年份](李白.李白的出生年份)` 是**带描述的同一段代码**;
- `[描述](...)` 唯一新增的是「描述」与「view/compiler 元数据」,不是执行规则。
### 0.4 当前实现的偏差
v2.0.0 把「类-函数」收窄成了「实例方法」:
| 设计意图 | 当前实现 | 后果 |
|----------|---------|------|
| `# 李白` 是类 | `# 李白` 是对象/类型 | 可以,但 `##` 被当成实例方法 |
| `## 李白的出生年份` 是函数 | `##` 是实例方法,需要 `self`/接收者 | `李白.李白的出生年份` 被拒绝 |
| `类.函数` 是类调用 | 必须 `> 李白` 构造实例,再 `obj.函数()` | 多一步实例化,知识不能直接调用 |
| 跨文档按类名链接 | 裸类名不解析,必须 `import` + 绑定 | 第二个文档的链接是 `undefined variable` |
| 链接是「命名载荷 + 已有语义」 | 被收窄成「遮蔽/本地表达式」 | 取元/循环/调用的步骤图、跨文档链接、view 依赖信息缺失 |
这正是「功能被阉割」的地方:**不是 `[]()` 不够,而是 `#`/`##` 的调用语义被实现成了实例方法,跨文档类索引没有建立。**
### 0.5 三个统一
| 统一 | 链接语法的作用 |
|------|---------------|
| **代码即文档** | 调用写在文档里;`**` 是代码,`[]()` 是同一段代码 + 人话描述 |
| **文档即知识库** | `#` 类是知识命名空间,`##` 函数是知识单元;`类.函数` 是地址 |
| **知识即可执行** | 链接解析到类/函数并求值;view 显示调用点;编译器返回 LinkInfo |
形式化:
> **`[label](expr) ≡ expr`;`expr` 可以是 `类.函数`。**
> 链接不改变求值;它增加 label/上下文所形成的命名步骤,以及 view 呈现、编译器元数据和图关系。
---
## 1. 术语
| 术语 | 定义 |
|------|------|
| **链接语法** | `[描述](载荷)`;描述在运行时 inert、在知识层是步骤名称;载荷复用所在位置的已有代码/结构语法 |
| **描述 / 名称(label)** | `[]` 内自由文本;不参与运行时求值,但用于显示、检索、诊断、LinkInfo、意图漂移校验与新鲜度复核 |
| **载荷(payload)** | `()` 内的表达式;与 `**代码**` 同权;唯一执行体 |
| **类(class)** | `# 名称`;知识命名空间/类型 |
| **函数(function)** | `## 名称`(及更深);类下或模块顶层的可调用单元 |
| **类调用(class call)** | `类.函数`;不构造实例,直接调用类函数 |
| **实例调用(instance call)** | `对象.函数`;对象是局部变量/实例,函数可使用 `self`/`自` |
| **知识链接** | 目标为类/函数的 `[]()`;view 显示目标与值 |
| **代码链接** | 出现在 `**...**` / `*...*` / 调用实参/表格单元格里的 `[]()`;参与表达式 |
| **正文链接** | 出现在叙述里的 `[]()`;view/check 解析,`run` 不执行(除非加 `print` 或代码链接) |
| **LinkInfo** | 编译器返回的命名步骤信息:描述与上下文、源位置、payload 类型、输入/输出、依赖、效果、值/来源/指纹 |
| **链接图** | 文档/类/函数/命名步骤为点,读、推导、遍历、调用、效果、叙述、来源为边;EKC/catalog/view 共用 |
| **遮蔽** | 链接的显示属性:`()` 的代码在 Markdown 里被折叠,读者只看描述与结果 |
---
## 2. 语义
### 2.1 描述永不执行,载荷唯一执行
```text
[label](expr) ≡ expr
```
- `[]` 不进符号表、不参与运行时求值、不改变作用域;但它进入 LinkInfo,作为命名步骤的人话接口;
- `()` 是唯一执行体;空 `()` 值为 `None`;
- `label.missing` / `label.empty_payload` 仍是结构诊断;
- 链接的**可执行性**来自 `payload` 的原有语法;链接的**知识性**来自 `label`、位置以及编译器提取的输入/输出/依赖/效果。任意载荷都可成为知识步骤,不以是否类调用为前提。
### 2.2 `#` 是类,`##` 是函数
| 标记 | 语义 |
|------|------|
| `# 名称` | 类/知识命名空间;正文是构造体 |
| `## 名称` | 类下的函数;可被 `类.函数` 调用 |
| `###` … | 更深层函数/子命名空间 |
| 顶层 `## 名称` | 模块级自由函数;可被 `模块.函数` 调用 |
**函数与实例的关系**:
- 函数体使用 `self` / `自` → **实例函数**,只能通过实例调用(`obj.函数`);
- 函数体不使用 `self` / `自` → **类函数**,可被 `类.函数` 直接调用;
- 类函数不执行 `# 类` 的构造体,不产生实例;
- 实例函数保留现有 `> 对象.函数` / `obj.函数()` 语义。
这条规则只用已有语法(`#`、`##`、`self`/`自`、`.`),不新增标记。
### 2.3 `类.函数` 是类调用
| 写法 | 语义 |
|------|------|
| `李白.李白的出生年份` | 类 `李白` 的零参函数 `李白的出生年份`;**隐式调用** |
| `李白.问候("世界")` | 类 `李白` 的函数 `问候`,带位置参数 |
| `李白.计税(档位=2, 金额=100)` | 具名参数,复用现有实参文法 |
| `obj.李白的出生年份()` | 实例调用;`obj` 是局部变量/实例 |
| `文档.李白.李白的出生年份` | 文档限定;用于同名类消歧 |
**隐式调用规则**:当点号路径解析到一个**零参函数**时,路径表达式就是调用,值为函数返回值;
带参数时必须写 `(...)`;解析到类名本身(无函数段)时,仍是类型/构造,不隐式调用。
> 这条规则不是新语法:它只规定「点号路径解析到函数」时的语义。
> 它让 `李白.李白的出生年份` 与 `**李白.李白的出生年份**` 同权,也让链接与代码同权。
### 2.4 跨文档:模块身份优先,类索引只做发现
链接目标可以跨文档。可运行代码的解析顺序:
1. **局部变量/对象**:第一段是当前作用域变量 → 实例调用;
2. **当前文档类/函数**:`# 类` / `## 函数`;
3. **已 import 的模块**:现有 `import bind:target` 绑定;
4. **内置/插件**。
文件 frontmatter 的 `id` + 现有 `import bind:target` 是规范地址;例如
`li_bai.李白.出生年份`。项目类索引仍是**编译器/链接器的发现索引**,不是运行时的
按名加载机制:
- 索引 `id`、`# 类` 名、`## 函数` 名、签名、文件位置;
- 排除 `# main`;
- 正文短地址同名 → `link.ambiguous`;解析成功后 LinkInfo/lock 固化 `id`、文件与指纹;
- 索引只在项目根内(`--fs-root`),不访问网络;
- 索引可缓存(按文件 mtime)。
> 正文可以直接写 `李白.出生年份`,由 catalog 唯一发现并 lock;
> 代码仍应使用显式 import,避免同名、重命名和加载顺序使大型项目失去可复现性。
### 2.5 `()` 与 `**代码**` 同权
| 能力 | `**代码**` | `[描述](载荷)` 的 `()` |
|------|-----------|----------------------|
| 算术/比较/布尔 | ✅ | ✅ 同一 parser |
| 变量/插值 | ✅ | ✅ |
| 本地调用 `callee(args)` | ✅ | ✅ |
| 类调用 `类.函数` | ✅ | ✅ |
| 实例调用 `obj.函数` | ✅ | ✅ |
| 表/列/映射 | ✅ | ✅ |
| 返回值 | Value | Value(同类型系统) |
| 副作用 | 可 | 可(受沙箱限制) |
**实现约束**:表达式位置的 `[label](payload)` 必须复用 `**代码**` 的表达式入口;遍历位置的
`[label](payload)` 必须复用既有 LoopSpec 入口;禁止另造「简化知识表达式」或「知识循环」。
**代码链接 vs 正文链接**:
| 上下文 | `[]()` 行为 |
|--------|-------------|
| `**...**` / `*...*` / 调用实参 / 表格单元格 | 代码链接:求值,参与表达式 |
| 正文(叙述) | 正文链接:view/check 解析并显示;`run` 不执行 |
| 标题 / frontmatter | 不执行;按普通文本处理 |
正文链接不执行,是为了保持「叙述默认安全」;它由 view 呈现、由 check 解析。
要终端输出,就把同一段代码放进代码链接并加 `print`。
**正文链接的识别**:`view`/`check` 扫描正文里的 Markdown 链接;payload 先按所在位置的既有
载荷文法解析,再提取其依赖与角色。URL/相对路径为导航;任意可解析的表达式、调用或遍历
都是命名步骤;解析歧义 → `link.ambiguous`。这仍是语义分类,不是新语法。
### 2.6 输出:值知识必须有值,过程知识必须声明效果
当一个 `##` 作为可被叙述或计算使用的值知识时,目标函数必须返回一个值:
```markdown
## 李白的出生年份
*701*
```
或者用表格/契约声明返回值。**正文叙述可以保留**(例如「李白出生于某年」),但**叙述不是值**;值知识要的是返回值/表。只有叙述、没有返回的函数:
- `run` 得到 `None`;
- `check` 报 `link.no_value`(warning/error,视知识链接用途);
- view 显示「无返回值」;
- 这不是语法问题,是值知识单元没有编码值。遍历、写入、请求等过程知识不必伪造返回值,
但 LinkInfo 必须记录输入、输出绑定和 `effect`,以便 view、权限检查与影响分析。
### 2.7 view 显示调用信息
**代码链接**:
```text
┌─ 链接 ─────────────────────────────┐
│ `year` = [李白的出生年份] │
│ → 李白.李白的出生年份 │
│ class 李白 · function · () -> number │
│ value 701 · ok │
└────────────────────────────────────┘
```
**正文链接**:
```text
用户想要知道李白的出生年份,我们要告诉用户 701。
↑
悬浮:李白的出生年份 → 李白.李白的出生年份
class 李白 · () -> number · value 701
```
- Structure 模式:显示 label + 目标类/函数 + 状态 + 源位置;
- Execution 模式:显示值;
- 点击目标:跳到目标文档/类/函数;
- 错误:错误 chip + 诊断码 + 修复建议;
- 无返回值:显示「无返回值」,不伪造值。
**这就是「示例不带 print」的原因**:view 显示调用信息;`run` 才需要 `print` 才有终端输出。
### 2.8 编译器返回 LinkInfo
每个 `[]()` 产出:
```json
{
"label": "逐个订单行",
"payload_kind": "loop",
"roles": ["iterate"],
"source": {"file": "pricing.mq.md", "line": 18, "col": 3},
"inputs": [{"path": "订单.行", "type": "list<订单行>"}],
"outputs": [{"name": "行", "type": "订单行"}],
"dependencies": [
{"kind": "local_value", "path": "订单.行"},
{"kind": "symbol", "id": "capability.pricing::订单定价.含税价"}
],
"effect": "pure",
"value": null,
"fingerprint": "sha256:…"
}
```
- `payload_kind`:`expr` / `loop` / `inline` / `navigation`;复用所在位置的已有文法;
- `roles`:`observe` / `derive` / `reuse` / `iterate` / `act` / `narrate`,由 AST、效果和依赖推导;
- `dependencies` 是集合而非单一 target;任意复杂表达式都可同时读表、调用多个知识函数和产生副作用;
- `value` 在 `check` 中为 `null`(不执行);在 `view`/`run` 中可填;
- `fingerprint` 是 label、payload、依赖解析及契约的指纹;用于意图漂移与 lock 检查。
### 2.8.1 LinkInfo 是统一知识步骤记录,不只是调用记录
`LinkInfo` 至少要区分三类状态:
| 层 | 要回答的问题 | 典型状态 |
|------|-------------|----------|
| **载荷状态** | `()` 能否按它原有语法解析/执行? | `ok` / `unresolved` / `arg_mismatch` / `type_mismatch` |
| **步骤状态** | 输入、输出、依赖和效果能否被提取? | `resolved` / `partial` / `ambiguous` |
| **证据状态** | 一个发布事实沿依赖链是否能抵达来源? | `supported` / `needs_review` / `unsupported` |
三者不能混为一谈:字典取元可以 `ok` 且完全不需要来源;但当它被一个事实函数或
正文结论使用时,最终的证据链仍可为 `unsupported`。反过来,来源充足也不能掩盖
`link.unresolved` 或副作用越权。
来源是统一步骤图上的 `derived_from` 边,不是只属于一种“知识链接”的特殊 payload。
这不是新增语法,而是让既有 `#`/`##`、表、表达式和 `[]()` 共同产生同一张图。
### 2.9 链接既是步骤节点,也是图边
```text
定价.订单定价 --contains--> step#逐个订单行
step#逐个订单行 --observes--> 订单.行
step#逐个订单行 --calls--> 定价.订单定价.含税价
定价.订单定价.含税价 --derived_from--> corpus/tax.md#税率
```
- 每个 `[]()` 都保留为步骤节点;`calls` 只是 `observes`/`derives`/`iterates`/`acts`/
`narrates` 等边的一种;
- EKC `graph.json` 增加 class/function/步骤节点和上述关系边;
- `catalog` 模块页显示「链接到/被链接」;
- `find`/`impact`/`verify` 沿步骤、调用和来源边遍历;表字段、循环、函数或来源变更时,
都可精确找出受影响的代码步骤和句子;
- view 的 Structure 面板显示上下游。
### 2.10 安全
| 风险 | 规则 |
|------|------|
| 类名歧义 | `link.ambiguous`;要求 `文档.类.函数` |
| 实例函数被类调用 | `link.instance_only`;提示用实例 |
| 构造副作用 | 类调用不执行构造体;不会隐式构造实例 |
| 函数副作用 | 目标函数可能写文件/发请求;`run`/live view 受沙箱限制;`check` 不执行 |
| 循环 | 链接图检测环;运行时深度/步数上限 |
| 路径逃逸 | 项目类索引只在根内;`--fs-root` 限制;不访问网络 |
| 标签欺骗 | 标签不可信;解析/权限只看 target,不看 label |
| view | 静态模式不执行;live 执行需用户操作;错误不吞 |
### 2.11 可复现(可选,生成物)
- LinkInfo 带 label、payload、依赖解析、效果与可用来源边的指纹;
- `marqdo links lock` 生成 `.marqdo/links.lock.yaml`;
- `check --locked` 校验;载荷、依赖、契约或来源边变化 → `link.stale` / `knowledge.needs_review`;
- 这是生成物/工具,不是新语法。
### 2.12 知识分层:类、知识个体、调用面
链接语法是**调用面**;它上面还有两层知识结构(详见 [knowledge-layers.md](knowledge-layers.md)):
```markdown
# 诗人 # L1 本体:类/模式
| 字段 | 类型 | 说明 |
| 姓名 | text | ... |
| 出生年份 | number | ... |
# 李白 = > 诗人 # L2 知识个体:单体知识类
## 李白的出生年份
| 返回 | 类型 | 来源 |
| 701 | number | corpus/libai.md#出生年份 |
*701*
# L3 调用面
[李白的出生年份](李白.李白的出生年份)
```
**术语**:
- `# 李白 = > 诗人` 是**知识个体/单体类**(语法上是继承/特化),不是运行时实例;
- `> 李白` 才是运行时实例(map + `_type`);
- `李白.李白的出生年份` 是类调用;
- `[]()` 是调用面,不新增语法。
**为什么不在 v2.1 引入运行时实例作为知识实体**:
- 运行时实例是值,不是文档里的稳定地址;跨文档链接需要实例注册表/导出;
- EKC 的节点是文档/类/函数,不是运行时 map;
- 单体类已经能表达「李白是诗人,李白有出生年份」,且零新语法。
---
## 3. 当前实现 vs 目标
### 3.1 已具备(v2.0.0)
| 能力 | 状态 | 证据 |
|------|------|------|
| `[描述](表达式)` 解析 | ✅ | `Expr::Occluded` / `markup: occlusion` |
| `()` 内 `callee(args)` | ✅ | M1;`加一 号(31)` |
| 本地表达式透明求值 | ✅ | `interp.rs:1117` |
| view 本地链接卡 | ✅ | `render.rs:1227` |
| 标签诊断/检索 | ✅ | `label.*` / `marqdo labels` |
| 实例调用 | ✅ | `obj.method()` / `> obj.method` |
### 3.2 缺失(v2.1 目标)
| 能力 | 状态 | 影响 |
|------|------|------|
| `类.函数` 类调用 | ❌ | `李白.李白的出生年份` 被当成变量/实例方法 |
| 跨文档类索引 | ❌ | 裸类名不解析;必须 import + 实例 |
| 统一 `[]()` 分类 | ❌ | 默认 Classic 下 `[]()` 是取元;需 `markup` |
| LinkInfo | ❌ | 编译器不返回链接信息 |
| view 目标/类/函数/值 | ⚠️ 只有本地卡片 | 没有跨文档目标信息 |
| 链接图边(EKC) | ❌ | 知识图不从链接取边 |
| 正文链接解析 | ❌ | 第二个文档的链接不解析 |
| 类函数契约/返回校验 | ❌ | 无返回值也不报 |
### 3.3 为什么旧例子失败
| 层 | 旧例子 | 设计要求 |
|----|--------|---------|
| 上下文 | 正文普通链接 | 正文链接由 view/check 解析(run 不执行) |
| 类索引 | 无 import | 项目类索引解析 `李白` |
| 调用 | `李白.李白的出生年份` 被当变量 | 解析为类函数,隐式调用 |
| 分派 | `##` 是实例方法 | 不使用 `self` 的函数是类函数 |
| 值 | 方法体无返回 | 知识函数必须返回 `701` |
| 静态检查 | 不解析 | `check` 报 `link.*` |
---
## 4. 编译器 / view / CLI 表面
### 4.1 `check --json`
- 解析所有 `[]()`(表达式、遍历、代码与正文),输出带载荷/步骤/证据状态的 LinkInfo 与 `link.*` / `knowledge.*` 诊断;
- 不执行目标函数;
- `link.ok` 可作 info,不阻断;
- `link.unresolved` / `link.ambiguous` / `link.instance_only` / `link.no_value` 按级别报。
### 4.2 MLSP
| method | 作用 |
|--------|------|
| `link.resolve` | 解析一个链接 → LinkInfo |
| `links.list` | 列出文件/项目所有链接 |
| `links.graph` | 返回链接图 |
| `link.check` | 校验一个链接 |
AI 闭环:`locate` → `link.resolve` → 构造/修复 → `check` → `view`/`run`。
### 4.3 `catalog` / EKC
- `catalog` 增加 `links:` 段与链接图;
- EKC `graph.json` 增加 class/function、命名步骤节点与 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates`/`derived_from` 边;
- `find`/`impact` 能按类/函数/步骤检索,也能从变更的字段、规则或来源反查受影响的代码与文档句子。
### 4.4 `links` CLI(可选)
```bash
marqdo links list [PATH] --json
marqdo links resolve FILE:LINE:COL
marqdo links graph [PATH] --json
marqdo links lock [PATH] # 可选,生成指纹锁
```
### 4.5 诊断
| code | 级别 | 触发 | 建议 |
|------|------|------|------|
| `link.unresolved` | error | 类/函数/文档不存在 | 检查类名/文档名/拼写 |
| `link.ambiguous` | error | 同名类/函数 | 用 `文档.类.函数` 限定 |
| `link.instance_only` | error | 类调用命中实例函数 | 用实例 `obj.函数`,或去掉 `self` |
| `link.no_value` | warning | 知识函数无返回 | 加 `*值*` 或表/契约 |
| `link.arg_mismatch` | error | 参数数量/名称不匹配 | 按签名补/删 |
| `link.type_mismatch` | error | 返回/参数类型不匹配(可静态判断) | 修契约/转换 |
| `link.cycle` | error | 链接图成环 | 拆分事实/减少互引 |
| `link.stale` | warning | 目标指纹变化(lock 模式) | 更新 lock 并复核 |
| `knowledge.unsupported` | warning | 对外发布的事实/结论沿步骤依赖链没有来源支撑 | 补来源边或将其标明为未验证推导 |
| `knowledge.needs_review` | warning | payload、依赖、规则或来源变化,受影响步骤/句子待复核 | 复核步骤与叙述后更新 lock |
| `label.missing` | error | 空描述 | 写一句人话 |
| `label.empty_payload` | warning | 空载荷 | 写 `None` 或真实目标 |
---
## 5. 开发指导
### 5.1 里程碑
| 阶段 | 目标 | 交付 |
|------|------|------|
| **L0** | 统一 `[]()` 节点 | `Bracket { label, payload }`;代码/正文两处解析;不新增语法 |
| **L1** | 步骤索引 + 解析 | `Named<T>` 的输入/输出/依赖/效果提取;类/模块解析;`link.*`/`knowledge.*` 诊断 |
| **L2** | 类调用运行时 | `类.函数` 隐式调用;参数;实例函数拒绝;双后端 |
| **L3** | view | 链接卡;正文链接信息;目标跳转;值/状态/源位置 |
| **L4** | 图 + lock | EKC 步骤节点/读写推导遍历调用来源边;catalog;可选 lock/stale |
| **L5** | 默认/迁移/文档 | 统一解析替代 `markup` 方言;旧取元迁移;README/示例 |
**顺序**:L0 → L1 → L2 → L3 → L4 → L5。
L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。
### 5.2 文件级改动
| 文件 | 改动 |
|------|------|
| `src/ast.rs` | `Bracket { label, payload }`(可由 `Occluded` 演进);不新增语法节点族 |
| `src/parse/expr.rs` | `[]()` 统一解析;payload 复用 `**` 表达式入口;保留 `markup` 兼容 |
| `src/parse/mod.rs` | 正文 `[]()` 扫描;行/列定位;表格单元格 |
| `src/link.rs`(新增) | 模块/类解析、`Named<T>` 步骤记录、依赖/效果提取、诊断、指纹、图边 |
| `src/load.rs` | 项目扫描/类索引缓存;`--fs-root`;循环检测 |
| `src/check.rs` | 链接解析集成;`link.*`;`--links/--no-links/--locked` |
| `src/interp.rs` | `类.函数` 类调用;隐式零参调用;实例函数拒绝;正文链接不执行 |
| `src/bytecode/compile.rs` + `vm.rs` | 类调用编译/执行;双后端一致 |
| `src/view/render.rs` | 链接卡;正文链接信息;目标/值/状态/跳转 |
| `src/view/document.rs` / `output.rs` | 正文链接扫描/渲染 |
| `src/knowledge/graph.rs` | class/function/命名步骤节点;读/推导/遍历/调用/效果/叙述/来源边 |
| `src/knowledge/extract.rs` | 类/函数/命名步骤提取;依赖与来源关系 |
| `src/catalog.rs` | links 段/图 |
| `src/mlsp.rs` | `link.resolve` / `links.list` / `links.graph` |
| `src/main.rs` | `links` 子命令;check 选项 |
| `README.md` | 链接语法章节(不新增语法) |
| `doc/README.md` | 登记本文/示例 |
| `examples/link-syntax/` | 用户原始示例 + compat |
### 5.3 关键实现点
1. **类函数判定**:扫描函数体是否出现 `self` / `自`;出现 → 实例函数;不出现 → 类函数。
2. **隐式调用**:点号路径解析到零参函数时,求值为调用;带参必须 `(...)`;解析到类名不调用。
3. **类索引**:只索引 `#`/`##` 名、签名、文件、行;排除 `# main`;同名报歧义。
4. **`[]()` 分类**:
- payload 是类/函数路径 → 知识链接;
- payload 是表达式(运算符/字面量/调用)→ 本地表达式链接;
- payload 是单标识符且解析为集合 → 旧取元(兼容;`markup` 模式可强制链接);
- 正文 `[]()` → 正文链接(view/check)。
5. **正文链接不执行**:`run` 不改行为;`view`/`check` 解析;要输出用代码链接 + `print`。
6. **LinkInfo**:check/view/catalog 共用;任意 `[]()` 都记录 payload kind、输入/输出、依赖、效果与步骤状态;无需执行即可得到结构图。
7. **图**:每个 `[]()` 是步骤节点;按角色建 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates` 边,来源只是其中一种边。
8. **安全**:类调用不构造实例;沙箱;根目录;标签不可信。
**最小改动原则**(证明「不新增语法」):
| 层 | 现状 | v2.1 改动 |
|----|------|-----------|
| parser | `[label](payload)` → `Occluded { label, payload }` | **不改 grammar**;可把节点改名为 `Bracket` 便于阅读 |
| payload | 已是表达式,`callee(args)` 已支持 | 不改;`类.函数` 是现有 dot path |
| AST | `Occluded { label, payload }` | 不新增 `Ref`/`Class` 节点;类/函数用现有 `Function`/`is_object` |
| resolver | 无 | **新增**:类索引 + `类.函数` 解析 + `self` 判定 |
| interp | 透明求值 payload | **新增**:dot path 解析到类函数时隐式调用 |
| view/check | 本地卡片/契约 | **新增**:正文 `[]()` 扫描 + LinkInfo |
| 语法 | — | **零新增**:没有协议前缀、别名、执行开关、模式关键字 |
> 当前 `李白.李白的出生年份` 在 AST 里是 `Var("李白.李白的出生年份")`(v2.0.0 实测报 `undefined variable`)。
> **不要依赖 parser 生成新节点**:resolver 按 `.` 拆分这个变量名,先找类 `李白`,再找函数 `李白的出生年份`;
> 找到后按类调用求值。若 parser 已生成 `Call { path: ["李白","李白的出生年份"] }`,同样按 path 解析。
### 5.4 测试
| 层 | 用例 |
|----|------|
| 单元 | `类.函数` 解析;零参隐式调用;带参;`self` 判定;同名歧义 |
| 集成 | 用户两文档:正文链接 view 显示 701;代码链接 + print 输出 701 |
| 诊断 | unresolved / ambiguous / instance_only / no_value / arg/type/cycle |
| view | 链接卡/正文链接/目标跳转/错误/无返回值 快照 |
| 图 | EKC 观测/推导/遍历/调用/效果/叙述/来源边;catalog;impact |
| 双后端 | tree + bytecode 一致 |
| 回归 | 现有 605 测试不减;实例调用不变;旧 `markup` 兼容 |
| 安全 | 根目录逃逸、循环、副作用、标签注入 |
### 5.5 迁移
- `#`/`##` 的实例调用保持;
- 不使用 `self` 的现有方法自动获得类调用能力(增量);
- `类.函数` 是新增解析,不改变旧调用;
- `[]()` 在 `markup: occlusion` 下继续是链接;在 Classic 下按 payload 分类,单标识符/集合仍是旧取元;
- 目标:v2.2 移除 `markup` 方言,统一按 payload 分类。
---
## 6. 示例
完整见 [examples/link-syntax/](../../examples/link-syntax/)。
### 6.1 用户原始示例(目标)
`libai.mq.md`:
```markdown
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
李白的出生年份是公元 701 年。
*701*
```
`main.mq.md`:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
- `view`:正文链接显示 `李白.李白的出生年份`、类 `李白`、函数、签名、值 `701`;
- `run`:无输出(正文链接不执行);加 `print` 才有终端输出;
- `check --json`:LinkInfo(target/class/function/signature/status);
- `catalog`:`main.mq.md --calls--> libai.mq.md::李白.李白的出生年份`。
### 6.2 加 print(终端输出)
```markdown
# main
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
输出:`701`。
### 6.3 带参数
```markdown
# main
**greeting = [问候](李白.问候("世界"))**
> print text=`greeting`
```
### 6.4 当前兼容写法(v2.0.0)
```markdown
---
markup: occlusion
import:
libai: libai.mq.md
---
# main
**li = > libai.李白**
**year = [李白的出生年份](li.李白的出生年份())**
> print text=`year`
```
输出 `701`。这只是**当前实现**的等价写法;v2.1 的目标是去掉 `import`/实例两步。
---
## 7. 验收标准
| # | 验收 | 判定 |
|---|------|------|
| 1 | 用户原始示例的 `view` 显示 `701` 与调用信息 | view 快照 |
| 2 | `**year = [..](李白.李白的出生年份)**` + `print` 输出 701 | run |
| 3 | `check --json` 返回 LinkInfo(class/function/signature/status) | link.ok |
| 4 | 类名改成不存在 → `link.unresolved` | 反例 |
| 5 | 同名类 → `link.ambiguous` | 反例 |
| 6 | 实例函数被类调用 → `link.instance_only` | 反例 |
| 7 | 无返回值 → `link.no_value` | 反例 |
| 8 | EKC 出现 `calls` 边 | graph.json |
| 9 | 正文链接 `run` 不执行;`view` 解析 | 行为 |
| 10 | 旧 605 测试不减;实例调用不变 | 回归 |
| 11 | 表字段、规则或来源变化后,受影响的取元/循环/推导/句子变为 `knowledge.needs_review` | impact 反例 |
**一句话验收**:
> **`[李白的出生年份](李白.李白的出生年份)` 不新增任何语法;`view` 能显示它,`check` 能解析它,`run` 加 `print` 能输出 701,`catalog` 能建边。**
> 四者缺一,说明 `#`/`##` 的类-函数语义还没补齐。
---
## 8. 风险与开放问题
| 风险 | 说明 | 缓解 |
|------|------|------|
| 类名歧义 | 多个 `# 李白` | `link.ambiguous`;`文档.类.函数` |
| 实例/类判定 | 依赖 `self`/`自` 扫描 | 明确规则;无法判定时 `link.instance_only` |
| 构造副作用 | 类调用不应构造实例 | 类调用不执行构造体;实例函数拒绝 |
| 无返回值 | 知识函数只有叙述 | `link.no_value`;要求 `*值*`/表 |
| 正文链接 | run 不执行 | view/check 解析;print 用代码链接 |
| 旧取元歧义 | `[key](collection)` | 单标识符/集合按旧取元;`markup` 兼容;逐步迁移 |
| 性能 | 大项目类索引 | 缓存;只索引签名;增量 |
| 安全 | 类函数执行副作用 | 沙箱;check 不执行;标签不可信 |
| 跨项目 | 类索引只在根内 | 用 import/模块;不引入新语法 |
**开放问题**:
1. 类函数是否允许访问类级常量/字段?v1 只允许函数体自包含;v1.1 再定义。
2. `# 类` 的构造体与类函数的关系?v1 类调用不构造;实例函数用 `self`。
3. 同名类跨文档是否允许?v1 报歧义;用 `文档.类.函数`。
4. 正文链接是否要在 `run` 中渲染?v1 不执行;view 显示;v1.1 可加 `--render-links`。
5. `[]()` 与旧取元的自动分类是否足够稳定?先保留 `markup` 兼容;v2.2 再移除。
6. 是否需要函数作为一等值?v1 不需要;`类.函数` 解析即调用。
---
## 9. 结论
> **`[]()` 不是新语法,它是「命名载荷 + 已有语义」的组合。**
> `#` 是类,`##` 是函数,`类.函数` 是类调用;`()` 与 `**` 同权。
> 链接不改变载荷;它把取元、计算、循环、调用和正文槽统一提升为能被读、查、验和追溯的知识步骤。
v2.0.0 把 `##` 实现成了实例方法,把跨文档链接实现成了 import + 实例,把 `[]()` 收窄成了本地遮蔽。
v2.1 要补的是**语义**,不是语法:
1. `#`/`##` → 类/函数;不使用 `self` 的函数是类函数;
2. `类.函数` → 类调用;跨文档用项目类索引;
3. `[]()` → 命名载荷 + 已有语义;表达式/循环按原规则执行,正文由 view/check 解析;
4. LinkInfo / view / EKC 的步骤节点与读、推导、遍历、调用、效果、来源边 —— 让代码与文档可查、可看、可验、可建图。
**一句话**:
> **不是给 `[]()` 加语法,而是让 `#`/`##` 真正成为类/函数,让 `类.函数` 真正可调用;`[]()` 只是把这次调用写成一句人话。**
---
## 附录 A:一页速查
```markdown
# 类
## 函数
*701*
# 代码链接(求值)
**year = [出生年份](李白.李白的出生年份)**
> print text=`year`
# 正文链接(view/check 解析,run 不执行)
李白出生于 [李白的出生年份](李白.李白的出生年份)。
# 带参类调用
**g = [问候](李白.问候("世界"))**
```
| 写法 | 执行 | 用途 |
|------|------|------|
| `**类.函数**` | ✅ | 普通代码/调用 |
| `[描述](类.函数)`(代码内) | ✅ | 带描述的类调用 |
| `[描述](类.函数)`(正文) | ❌ run / ✅ view/check | 知识链接 |
| `[描述](expr)`(代码内) | ✅ | 本地表达式链接 |
| `[描述](url)` | ❌ | 普通导航 |
## 附录 B:与旧文档的关系
| 旧文档 | 关系 |
|--------|------|
| [occlusion-syntax.md](occlusion-syntax.md) | 旧文把 `[]()` 定义为「遮蔽」;本文把它定义为「命名载荷 + 已有语义」;遮蔽只是显示属性 |
| [occlusion-description-and-search.md](occlusion-description-and-search.md) | 标签/桩/检索仍适用;本文把标签归入 LinkInfo |
| [change-m7-migration.md](change-m7-migration.md) | 旧取元迁移保留;v2.1 统一按 payload 分类,逐步移除 `markup` |
| [objects.md](objects.md) | 扩展:`#` 类是命名空间;`##` 不使用 `self` 时是类函数 |
| [module-namespace.md](module-namespace.md) | `import` 仍用于代码模块;链接额外支持项目类索引 |
| [engineering-knowledge.md](engineering-knowledge.md) | 链接边接入 EKC 图 |
+40 -27
View File
@@ -2,7 +2,7 @@
| | |
|---|---|
| 状态 | **Accepted;统一 `import bind:target` 已锁定** |
| 状态 | **Accepted;嵌套 YAML `import:` / `导入:` 映射已锁定** |
| 日期 | 2026-08-13 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) |
@@ -16,9 +16,9 @@
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存。
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
- 旧 frontmatter `import path:path.mq.md` 对 Markdown / 编辑器不友好,且与调用标记 `>` 抢外形。
- 旧 frontmatter 一行式 `import bind:target` 在 YAML 里会变成带空格的键,与正规元信息不兼容。
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为可读的 `import bind:target`。
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为嵌套 YAML 映射 `import:\n bind: target`。
---
@@ -29,8 +29,8 @@
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
2. **点号寻址调用**:`库.成员`、`库.对象.成员`;`.` 表示定义树寻址。
3. **库名不是变量**:路径段为**裸标识符**,不加反引号。
4. **短名与文件导入同形**:`import fmt:time.format`,废除独立 `use` 关键字。
5. **中英对等**:`import` / `导入`。
4. **短名与文件导入同形**:同在 `import:` 映射下写 `fmt: time.format`,废除独立 `use` 关键字。
5. **中英对等**:`import:` / `导入:`。
### 2.2 非目标
@@ -54,27 +54,38 @@
### 3.2 导入句法(frontmatter)
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。键为合法 YAML:`import:` / `导入:`,值为嵌套映射。
```yaml
---
import:
utils: utils.mq.md
json: lib/json.mq.md
fmt: time.format
---
```
| 含义 | 英文 | 中文 |
|------|------|------|
| 导入文件 | `import utils:utils.mq.md` | `导入 utils:utils.mq.md` |
| 标准库 | `import json:lib/json.mq.md` | `导入 json:lib/json.mq.md` |
| 短名(成员) | `import fmt:time.format` | `导入 fmt:时间.格式化` |
| 导入文件 | `import:` → `utils: utils.mq.md` | `导入:` → `utils: utils.mq.md` |
| 标准库 | `json: lib/json.mq.md` | 同左(或中文库路径) |
| 短名(成员) | `fmt: time.format` | `fmt: 时间.格式化` |
规则:
- **绑定名必填**,在 `:` 左侧(裸名,无反引号)。
- `:` 右侧 `target`:
- **绑定名必填**,为映射键(裸名,无反引号);冒号后须有空格(正规 YAML)。
- 映射值 `target`:
- 以 `.mq.md` 结尾 → **文件导入**;
- 否则为 **点号路径**(≥2 段),把该成员绑为本地短名(须先有对应文件导入)。
- 同一文件内绑定名不得冲突(文件库名与短名共用命名空间)→ 硬错误。
- 旧写法 `> ….mq.md`、`> … as …`、`> use …`、`> 使用 …` → **硬错误**,并提示新句法。
- 同一文件不得同时出现 `import:` 与 `导入:`。
- 旧写法一行式 `import bind:target`、`> ….mq.md`、`> use …` → **硬错误**;可用 `marqdo migrate imports --write` 迁移。
### 3.3 废除的旧规则
不再支持:
- 一行式 `import bind:target` / `导入 bind:target`;
- 省略绑定名时用文件名茎作库名;
- 导入侧 `as` / `作为`;
- 独立关键字 `use` / `使用`。
@@ -101,8 +112,9 @@ path_callee ::= ident ('.' ident)+
```markdown
---
import time:lib/time.mq.md
import json:lib/json.mq.md
import:
time: lib/time.mq.md
json: lib/json.mq.md
---
# main
@@ -139,8 +151,9 @@ import json:lib/json.mq.md
```markdown
---
import time:lib/time.mq.md
import fmt:time.format
import:
time: lib/time.mq.md
fmt: time.format
---
# main
@@ -153,10 +166,11 @@ import fmt:time.format
```markdown
---
import time:lib/time.mq.md
import writeback:lib/writeback.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
import:
time: lib/time.mq.md
writeback: lib/writeback.mq.md
agent: ext/ai/agent.mq.md
json: lib/json.mq.md
---
# main
@@ -179,13 +193,12 @@ import json:lib/json.mq.md
| 旧 | 新 |
|----|----|
| `import time:lib/time.mq.md` | `import time:lib/time.mq.md` |
| `import t`:lib/time.mq.md | `import t:lib/time.mq.md` |
| `import fmt`:time.format
| `import time:lib/time.mq.md` | `import:` → `time: lib/time.mq.md` |
| `import fmt:time.format` | `import:` → `fmt: time.format` |
| 茎名默认库名 | 绑定名始终显式 |
| 扁平合并进全局 | 仅库绑定 + 可选短名 |
不提供旧 `>` 导入过渡开关。
不提供旧一行式 / `>` 导入过渡开关;`marqdo migrate imports --write` 可机械迁移。
---
@@ -201,20 +214,20 @@ import json:lib/json.mq.md
## 8. 实现要点
1. frontmatter 只解析 `import` / `导入` 行;右侧分流文件 / 成员。
1. frontmatter 解析嵌套 `import:` / `导入:` 映射;子项分流文件 / 成员。
2. AST 仍用 `Import`(文件)与 `Use`(短名)存储,对外无 `use` 关键字。
3. 金样例:`tests/structure/import/`、`tests/structure/ns/`。
| 阶段 | 内容 |
|------|------|
| M1+M2 | 点号路径 + 短名 — 已落地 |
| **Import 句法** | 统一 `import bind:target` — **本波次** |
| **Import 句法** | 嵌套 YAML `import:` — **本波次** |
---
## 9. 决议摘要
1. 导入 = `import bind:target`(`导入` 等价)。
1. 导入 = 嵌套 `import:` / `导入:` 映射(`bind: target`)。
2. target = `.mq.md` 文件 **或** `库.成员` 点号路径。
3. 调用以裸名点号路径寻址;实例方法用反引号接收者(仅独立 `>` 调用;`*…*`/`**…**` 段内接收者不加反引号)。
4. 裸点号 `a.b`:`a` 为局部变量 → 方法调用,否则 → 库路径(Python 统一命名空间)。
@@ -1,5 +1,7 @@
# 调用写法评估:`[函数名](参数)` 与更接近人读的调用形式
> **2026-10-23 审阅裁决**:“原型回退”仅描述当时实验,当前 payload 已支持 `f(args)` 和具名实参。旧 Classic 索引冲突不再决定默认语法;保留熟悉的调用形态与文档原生描述并不矛盾。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),不要把本文备选形式当作已批准的新语法。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(原型已验证并已回退,未合入代码) |
+4 -2
View File
@@ -35,7 +35,8 @@
```markdown
---
import text:lib/text.mq.md
import:
text: lib/text.mq.md
---
# main
@@ -44,7 +45,8 @@ import text:lib/text.mq.md
```markdown
---
导入 文本:lib/文本.mq.md
导入:
文本: lib/文本.mq.md
---
# main
+2 -1
View File
@@ -17,7 +17,8 @@
```markdown
---
import table:lib/table.mq.md
import:
table: lib/table.mq.md
---
# main
+3 -2
View File
@@ -51,8 +51,9 @@ Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可
```markdown
---
import text:lib/text.mq.md
import table:lib/table.mq.md
import:
text: lib/text.mq.md
table: lib/table.mq.md
---
```
@@ -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 反例;布局尺寸、交互、性能和读者任务结果均为待实施的验收目标。
+26 -1
View File
@@ -13,6 +13,8 @@
|------|------|------|
| Rust + Cargo | stable,建议 ≥ 1.81(本机验证过 1.81) | `rustc --version` / `cargo --version` |
| Git | 任意近期版本 | `git --version` |
| GCC / Binutils | 原生依赖编译与链接 | `cc --version` / `ld --version` |
| Go | ≥ 1.22(仅构建 `plugins/web` 与 web 扩展测试需要) | `go version` |
安装 Rust(若尚未安装):
@@ -21,7 +23,17 @@
本仓库可选 `rust-toolchain.toml`(钉 1.81.0)。若本机无 `rustup`、但已有匹配的 `rustc`/`cargo`,也可直接开发。
**不需要:** Flex、Bison、LLVM、Node/npm(实现栈为 Rust)。
**不需要:** Flex、Bison、LLVM。Node/npm 只在开发 VS Code 扩展时需要;核心 Rust 开发不依赖它们。
本仓库提供了固定 Rust 版本:`rust-toolchain.toml` 使用 Rust 1.81.0,并启用
`rustfmt` / `clippy`。在受限开发容器中,推荐先加载仓库环境脚本:
```bash
source scripts/dev-env.sh
```
脚本会优先使用 `target/toolchain/` 下的工具链,普通开发机则回退到 PATH 中已有的工具,
并把 Cargo、Go 缓存和临时目录放在工作区内。
---
@@ -36,6 +48,12 @@ cargo test
cargo run -- run tests/structure/hello.mq.md
```
构建 Go web 插件(完整扩展开发需要):
```bash
bash scripts/build-web-plugin.sh
```
当前 M0:`run` 会读入文件并明确报错「evaluation not implemented」(脚手架,非静默假成功)。
> 若 `cargo build` 报 `edition2024` / 过新 crate:仓库已对 `clap` 等做兼容钉扎(见 `Cargo.toml`);请使用附带的 `Cargo.lock`,勿盲目 `cargo update` 到最新 major。
@@ -50,6 +68,13 @@ cargo fmt
cargo clippy --all-targets
```
只验证 Rust 核心时可运行 `cargo test --locked --lib`;包含全部扩展的 gold 测试需要 Go,
并建议单线程运行以避免共享临时夹具互相影响:
```bash
cargo test --locked --test gold -- --test-threads=1
```
代理下拉 crate(可选,与 git 推送类似):
```bash
+453
View File
@@ -0,0 +1,453 @@
# Marqdo 的 `[]()`:从可读语法走向可验证的知识引用
我重新读取了仓库当前 `main` 分支(提交 `1a139892`)的 README、链接语法设计、知识分层设计,以及仓库中针对现有实现的复核报告。
这次我认为应当调整之前对 Marqdo 的评价:你提出的 `[]()` 不只是改善语法外观,它确实有机会成为 Marqdo 从“可执行文档”走向“可复用知识系统”的关键入口。
但当前设计有一个尚未解决的根本问题:
它已经尝试统一“可读描述”和“可执行表达式”,却还没有真正统一“知识的身份、知识的含义、知识的实现、知识的证据,以及知识的版本”。
仅仅让链接能解析到一个函数,并不能保证 AI 没有用错知识。仅仅让函数有一个确定的编译结果,也不能保证这个结果所表达的知识是真的。
这恰恰可能是你不断修改设计,却始终没有得到预期效果的原因。
## 一、先区分仓库已经实现了什么
当前 README 标明的是 v2.0.0,`doc/design/link-syntax.md` 将跨文档类函数调用列为 v2.1 目标。
| 能力 | 仓库当前状态 |
| ---------------- | ---------------------------- |
| `[描述](表达式)` 本地遮蔽 | 已实现,主要通过 `markup: occlusion` |
| `()` 中表达式求值 | 已实现 |
| 用自然语言描述隐藏复杂代码 | 已实现基础能力 |
| `类.函数` 直接调用 | 设计目标,尚未按文档实现 |
| 跨文档自动解析知识目标 | 设计目标 |
| 编译器生成 LinkInfo | 设计目标 |
| 链接进入 EKC 知识图 | 设计目标 |
| 版本指纹和链接锁定 | 设计目标 |
仓库还有一份很重要的复核报告:[occlusion-vs-executable-knowledge-2026-10.md](https://github.com/cflmy/marqdo/blob/main/doc/research/occlusion-vs-executable-knowledge-2026-10.md?utm_source=chatgpt.com)。
它针对 v2.0.0 测试了一个典型案例:在一个文档里定义“李白的出生年份”,再由另一个文档通过链接读取。结果发现,正文链接没有进入执行 AST,跨文档类名没有得到解析,类函数不能直接调用,而且原始知识函数也没有实际返回值。
这份报告说明:问题不是 `[]()` 的形式不够优美,而是链接背后的知识语义基础尚未建成。
这也解释了为什么你已经设计了链接语法,却还没有获得想象中的知识复用能力。
## 二、我建议保留你的两个目标,但增加第三个目标
目标一 · Presentation
自然语言呈现
用 `[]` 给复杂、不适合人类直接阅读的可执行表达式一个清楚的描述。
目标二 · Executable Reference
确定性知识引用
让 `()` 可以绑定已经编译、可解析、可验证的知识单元,而不仅是临时拼出的表达式。
目标三 · Knowledge Integrity
知识一致性保障
当知识定义、实现、版本、证据或适用条件变化时,能检测引用是否仍然有效,阻止 AI 把“能够运行”误认为“知识正确”。
第三个目标不是另加一种语法,而是让前两个目标真正成立所必须的编译器能力。
我倾向于把它称为 Verified Knowledge Reference(可验证知识引用)。
## 三、关键转变:不要把“函数”直接等同于“知识”
目前 [link-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md?utm_source=chatgpt.com) 的核心设计是:
```
[label](expr) ≡ expr
```
它规定标签不改变计算语义,链接只为表达式增加人类描述和编译器元数据。
这个规则作为表达式语义是合理的,但作为完整知识模型还不够。
原因在于,至少有三种不同的东西可能进入 `()`:
| 内容 | 例子 | 实质 |
| ---- | ---------------------------- | --------------- |
| 表达式 | `[税额](amount * rate)` | 一次计算 |
| 函数 | `[计算税额](Tax.calculate(100))` | 一种计算能力的调用 |
| 知识事实 | `[适用税率](TaxPolicy.rate)` | 一项具有来源、范围、版本的知识 |
第三种不能只靠前两种来解释。
例如,编译器能确定 `TaxPolicy.rate` 返回 `0.10`,只能证明“目标被正确解析并返回该值”,不能证明“2026 年某个地区、某种业务适用的税率确实是 10%”。
确定性执行和知识真实性是两个独立维度。
我建议把 Marqdo 的知识模型扩展为以下结构:
Markdown 文档
自然语言叙述、表格、函数与知识定义
Semantic Artifact · 语义制品
稳定身份、类型、签名、实现、契约、依赖、证据
Verified Knowledge Reference
解析引用、检查约束、固定版本、判定可否复用
解释执行
知识检索
AI 复用
这里最重要的新概念不是链接,而是 Semantic Artifact(语义制品)。
它应当是 Marqdo 编译器第一次真正统一代码、文档与知识的中间产物。
### 一个语义制品应该包含什么?
建议最小模型如下。这里是我的架构提案,不是当前仓库已经实现的格式。
```
{
"id": "knowledge://project/TaxPolicy/rate",
"kind": "fact",
"signature": {
"params": [],
"returns": "number"
},
"implementation": {
"ir": "compiled-reference",
"digest": "sha256:..."
},
"contract": {
"unit": "ratio",
"scope": "example-policy",
"effects": "pure"
},
"provenance": {
"source": "policy.md#rate",
"digest": "sha256:..."
},
"verification": {
"status": "verified",
"methods": ["source-check", "contract-test"]
}
}
```
其中 `id` 是符号身份,`implementation.digest` 是编译内容指纹,`provenance` 是来源证据,`verification` 是验证记录。
这样一来,AI 复用的对象就不再是“某个名字看起来正确的函数”,而是一个具有明确身份和约束的知识制品。
需要注意:这里的 `verified` 只能表示通过了所声明的验证方法,不能凭此宣称该知识在所有现实情境下都正确。
## 四、重新定义 `[]()`:统一写法,不强行统一所有行为
我建议继续保持你所追求的语法纯度:
```
[人类可读的描述](机器可解析的目标)
```
不引入额外的 `knowledge:`、`call:` 或 `ref:` 前缀,也不让 AI 记忆复杂的新标记。
但编译器必须区分目标的性质,而不是把一切都当作普通表达式立即求值。
A · 表达式遮蔽
计算
```
**total = [应付总额](price * quantity + shipping)**
```
对原有表达式的透明包装。编译后仍是普通表达式,描述不改变值。
B · 能力引用
复用
```
**total = [计算应付总额](Pricing.total(订单))**
```
解析到已编译函数,检查参数、类型、依赖、权限和版本,然后调用。
C · 知识事实引用
知识
```
用户可以查阅[李白的出生年份](李白.出生年份)。
```
解析到知识制品;view 展示事实、来源和验证状态。正文保持惰性,不自动产生副作用。
这种设计保留了 `[label](expr) ≡ expr` 的计算规则,但增加了一个重要条件:编译器首先要解析 `expr` 的目标类型,然后才能决定它应该怎样验证、绑定和使用。
这不会使语言多出三套语法,反而能够避免当前设计中“语法统一了,但知识语义仍然散落在工具中”的问题。
## 五、你的第二个目标,最关键的是“绑定”而不是“调用”
假设有这样一份知识文档:
```
# 李白
## 出生年份
| 返回 | 类型 | 来源 |
|---|---|---|
| 701 | number | corpus/libai.md#birth |
*701*
```
另一个文档写:
```
李白的[出生年份](李白.出生年份)是 701 年。
```
理想情况下,编译器应该执行一条确定性的处理链:
Resolve — 查找 `李白.出生年份` 指向哪个知识单元
Bind — 绑定稳定 Symbol ID,而不是仅保存字符串
Validate — 检查返回类型、来源、契约与依赖
Pin — 根据需要固定知识版本和内容指纹
Evaluate — 仅在允许执行的上下文中求值
Trace — 将引用关系、验证结果与来源写入知识图
此时,编译器内部的引用不应该只是:
```
"李白.出生年份"
```
而应该更接近:
```
KnowledgeRef {
target_symbol_id,
resolved_artifact_id,
expected_signature,
pinned_digest,
verification_policy,
source_span
}
```
其中的 `target_symbol_id` 解决“引用谁”,`pinned_digest` 解决“引用哪个版本”,`verification_policy` 解决“什么时候可以信任它”。
这才是让 AI 不必重新生成已有知识,而是能够确定性地调用已有知识的技术基础。
还有一个必须考虑的问题:如果编译器只记录函数源码哈希,而函数内部调用的其他知识已经发生变化,那么源码没有变,实际执行语义也可能已经变化。因此,至少要对调用依赖形成可追踪的版本关系;对需要严格复现的纯函数,还应生成包含传递依赖的制品指纹。对于网络请求、时间、随机数等外部效应,则必须记录环境和执行条件,不能简单承诺重放一定得到相同结果。
## 六、仓库当前设计里,我最想修改的三个地方
### 1. 不要继续把类当作所有知识的唯一载体
[knowledge-layers.md](https://github.com/cflmy/marqdo/blob/main/doc/design/knowledge-layers.md?utm_source=chatgpt.com) 提出用 `# 李白 = > 诗人` 表示知识个体,也就是“单体知识类”。
这可以作为兼容实现路径,但我不建议把它提升为最终的知识本体。
因为“李白是诗人的一个个体”与“李白是诗人的子类”并不相同。让每一个事实实体都成为一个类,可能在知识库规模扩大后引入继承关系和个体关系的混淆。
更理想的是:让编译器内部明确区分 `Type`、`Entity`、`Fact`、`Function`、`Capability` 等制品类型。Markdown 源码可以继续使用现有的标题、表格和 frontmatter 承载这些信息,不要求立即增加新语法。
### 2. 不要让 `check` 与 EKC 各自维护一套知识理解
目前 EKC 已经有 Symbol、Capability、Knowledge、Graph 和 REUSE→ADAPT→CREATE 等概念。参见 [engineering-knowledge.md](https://github.com/cflmy/marqdo/blob/main/doc/design/engineering-knowledge.md?utm_source=chatgpt.com)。
这里完全没有必要再为 `[]()` 平行开发另一套知识注册表。
我建议把架构整理成:
- 编译器负责产出统一 Semantic IR、符号信息和引用关系;
- `check` 消费这些信息进行验证;
- EKC 将它们投影成知识图和上下文包;
- `view` 消费同一份信息展示可读知识;
- Agent 使用同一份引用解析接口,而不是重新理解 `.mq.md` 文本。
如此一来,编译器就是事实上的知识系统基础,EKC 不再承担第二次解释源码的职责。
### 3. 不要认为“描述过期”和“知识过期”是一回事
仓库中的 [occlusion-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/occlusion-syntax.md?utm_source=chatgpt.com) 已经意识到遮蔽会产生信任负债,并设计了标签引用一致性和新鲜度检查。这是有价值的方向。
但是,三类变化必须区分:
| 变化 | 应该检查什么 |
| ------------- | -------------- |
| 实现变了,描述没变 | 描述是否仍与行为一致 |
| 知识来源变了,函数没变 | 知识事实是否仍然有证据支持 |
| 引用目标变了,代码还能运行 | 是否仍满足原始契约和版本要求 |
尤其是第三种:AI 幻觉可能表现为调用了一个真实存在、类型也正确、但是业务含义完全错误的函数。
纯粹的符号解析和类型检查抓不住这种错误。因此,需要让能力契约、适用范围和知识来源成为可检查的制品属性,而不是只依赖 `[]` 中的自然语言。
## 七、建议的实施顺序
不要一次性实现完整知识图谱、版本锁定、自动修复和复杂本体系统。我建议分成四个阶段,每一阶段都必须有独立的可执行验收。
| 阶段 | 核心交付 | 必须通过的测试 |
| ------------ | ------------------------------------- | ---------------------------------- |
| P0 · 统一引用语义 | `[]()` 的统一 AST、目标类型识别、正文/代码上下文区分 | 不再因 Classic/Occlusion 模式造成静默错义 |
| P1 · 稳定寻址 | 项目符号索引、类函数解析、稳定 Symbol ID、静态 LinkInfo | 两文档李白示例无需实例化即可完成解析与引用 |
| P2 · 可验证知识制品 | Semantic Artifact、契约、来源、指纹、统一诊断 | 删除目标、修改签名、改变来源,均得到准确诊断 |
| P3 · 确定性复用 | 依赖图、制品锁定、EKC 集成、Agent 引用优先策略 | AI 不重新生成已存在的能力;错误、过期和不适用的知识被阻止直接复用 |
我特别建议设置一个不依赖 LLM 的核心验收实验:
准备 100 个知识单元,包含同名符号、跨文档引用、版本变更、类型不匹配、来源缺失、循环依赖和正常复用。由程序自动生成和验证预期结果。
先证明编译器能够正确识别、绑定和诊断这些情况,再引入 AI 测试上下文成本和幻觉率。否则很容易把模型能力、索引召回率与编译器的正确性混在一起。
## 八、重新评价 Marqdo 的研究主张
过去 Marqdo 的核心叙述是:
> 代码即文档,文档即知识库,知识即可执行。
我认为现在可以把它变得更加严格:
Marqdo 是一种将人类可读文档编译为可寻址、可验证、可执行、可复用的知识制品的语言与编译系统。
这个定位的价值不在于“Markdown 可以运行代码”,也不在于“Markdown 链接能调用函数”。这两点单独来看都不足以形成很强的研究贡献。
它真正值得探索的创新组合是:
一份自然语言与程序混合的源码,经过统一编译后,同时生成可执行程序、语义符号体系、验证证据、版本化知识引用和 AI 可消费的复用接口。
当然,这仍然是一个待证明的系统设计目标,而不是当前 v2.0.0 已经达到的状态。
## 最终判断
你的 `[]()` 方向值得保留,甚至值得作为下一轮 Marqdo 核心架构调整的切入点。但我不建议继续把主要精力投入到如何让 `[]()` 兼容更多语法、更多函数调用形式或更多 Markdown 场景。
你现在缺少的不是更漂亮的链接语法,而是一个由编译器负责维护的“知识身份与语义绑定层”。
这也是我认为应该优先修正当前 [link-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md?utm_source=chatgpt.com) 的地方:它现在主要把链接理解为“表达式 + 描述 + 元数据”;下一版应明确规定,表达式可以解析到独立的、具有身份与验证状态的知识制品。
当这种绑定成立时,`[]()` 才能够同时实现你的两个愿望:读者看到自然语言,AI 获取确定性知识引用,编译器负责确保引用并非凭空想象。
而且,这次改变不必要求用户学习更多语法。真正增加的复杂度应当留在编译器和知识中间表示内部,而不是继续转嫁到 `.mq.md` 的作者身上。
是的。我认为你这个判断是正确的,而且它指出了我上一轮分析中的一个偏差:我把实现可执行知识体系所需要的技术条件,提升成了 Marqdo 的最终目标。
实际上,这两者应当区分。
你最初提出的:
> 代码即文档,文档即知识库,知识即可执行。
并不只是一句理念性的口号,它本身已经包含了完整的目标链条:
1. 代码即文档:知识与程序不再被割裂为两套独立的表达体系。
2. 文档即知识库:文档中的内容不再只是供人阅读的信息,而是可以被组织、定位、理解和关联的知识。
3. 知识即可执行:知识不再停留在被检索和解释的阶段,而是能够被直接调用、组合和复用。
其中,知识复用就是第三阶段最重要的结果之一。
因此,我之前提出的“可寻址、可验证、可执行、可复用”,实际上是在描述达成第三阶段需要具备的工程性质,而不是一个比原始理念更高层次的新目标。
## 真正需要解决的是:什么才算知识被复用?
我认为这里才是 Marqdo 当前设计最值得深入的地方。
假设 AI 需要计算一笔订单的最终价格。
传统方式可能是:
- 检索价格计算文档;
- 阅读文档中的公式和约束;
- AI 自己理解并重新编写计算逻辑;
- 执行新生成的代码。
这个过程中,知识被读取了,但未必真正被复用。AI 仍然可能理解错误、遗漏约束或生成不一致的实现。
而你想实现的 Marqdo 应该是:
```
订单最终价格为[计算后的价格](订单.最终价格(订单数据))。
```
这里 AI 不需要重新理解定价公式并生成一套新算法,而是引用已经存在的知识实现。
如果该实现的身份、依赖、契约和适用条件都能被确定,那么 AI 的任务就从:
“根据知识重新生成答案或程序”
转变成:
“发现知识 → 判断是否适用 → 引用知识 → 执行知识 → 使用结果”
这才是 Marqdo 的核心价值。
## 所以,`[]()` 应该承担什么角色?
我建议将整个体系理解成:
代码即文档
统一人类叙述与机器可执行内容
文档即知识库
知识具有结构、身份、关联与约束
知识即可执行
知识能够被确定性引用、调用和组合
知识真正复用
AI 优先使用既有知识,而非反复解释和重新生成
`[]()` 不需要独自完成这一切。
它应该成为整个体系中知识从文档进入使用场景的统一入口。
而编译器、符号系统、知识索引、验证系统与 EKC,则共同保证这个入口背后的知识可以可靠使用。
这里有一个很重要的区别:
- `[]()` 负责表达“我要使用这段知识”。
- 编译器负责确定“究竟是哪段知识”。
- 验证系统负责判断“这段知识是否满足当前使用条件”。
- 运行时负责执行知识。
这些职责不应该全部压到 `[]()` 的语法设计上。
## 我现在更倾向于保留你的原始理念
甚至不建议用我之前那段冗长的定义替换它。
“代码即文档,文档即知识库,知识即可执行”已经足够准确。
真正值得补充的是它背后的一个技术原则:
> 知识复用应当基于已编译知识的确定性引用,而不是基于自然语言的重复解释与生成。
这句话比单纯强调“可寻址、可验证”更接近你真正想解决的 AI 问题。
不过还需要保持一个边界:确定性引用能够减少 AI 在重新解释和生成过程中产生的错误,却不能自动保证被引用的知识本身正确。因此验证仍然必要,只是它属于实现可靠复用的手段。
我认为 Marqdo 下一步最值得研究的,已经不是“如何让文档变成知识库”,而是一个更具体的问题:
如何让一个 AI 在面对新任务时,能够像编译器复用已有函数一样,直接复用知识库中已经编译的知识,而不必重新理解和生成它?
如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。
@@ -0,0 +1,295 @@
# Marqdo 可执行知识体系:统一语义制品与知识引用设计规范
> 状态:设计提案(非当前版本的已实现功能)
> 基线:仓库 main,2026-10-23;README 标记 v2.0.0;跨文档类调用与 LinkInfo 为 v2.1 目标
> 宗旨:**代码即文档,文档即知识库,知识即可执行。**
> 核心判据:当 AI 遇到任务时,能否先发现已有知识,并以确定性绑定复用,而不是再生成一份“看起来相同”的知识或实现?
## 1. 决策摘要
保持 `[描述](表达式或知识目标)` 的 Markdown 形态,不引入新的前缀或第二套表达式文法。`[]` 是面向读者的陈述,`()` 内的内容进入统一表达式解析器。语言内部建立稳定的 **Semantic Artifact(语义制品)** 和 **Verified Knowledge Reference(可验证知识引用)** 两种核心抽象。前者承载身份、语义、实现、依赖、契约与来源;后者是一个经编译期解析、受上下文约束的引用。它们不必对应新语法标记,而是 `.mq.md` 经语义分析得到的统一中间表示。
**三项不变式:**
1. **表达式透明性**:在求值上下文中 `[L](E)` 与 `E` 取得同一类型和值;`L` 不进入符号绑定或改变结果。引用额外产生诊断与溯源元数据。
2. **文本安全性**:叙述中的知识链接在 `check/view` 中解析;`run` 不因正文出现链接而隐式执行有副作用的函数。导航链接(HTTP、相对文档路径)仍属于普通 Markdown 链接。
3. **知识可信边界**:`resolved`、`compiled`、`tested`、`source_verified`、`domain_validated` 是不同状态。能执行不等于事实真;有来源不等于来源仍然适用。没有证据时允许展示,但不得向 agent 宣称为已验证知识。
### 1.1 不是要做的事
- 不将 Markdown 转成一个独立于解释器的新运行语言。
- 不把所有知识都强制构建为类,也不等同“知识 = 函数”。
- 不把自然语言标签作为权限或事实正确性的证明。
- 不把符号名的字符串匹配当成稳定知识复用。
- 不要求所有调用都锁版本:本地临时表达式可无锁,跨文档公共知识/关键业务则可选或强制锁定。
## 2. 以真实仓库为准的兼容边界
| 语法或能力 | 当前已支持 | 目标设计/注意事项 |
|---|---|---|
| `.mq.md` 和 Markdown 叙述 | 是 | 原有叙述默认安全 |
| `#` 对象/类型,`##` 函数/方法 | 是 | 目标:不依赖 `self` 的函数可通过类命名空间直接调用 |
| `**表达式**`、`*返回*` | 是 | 复用现有表达式解析器,不另造链接表达式 |
| `+ \`参数\``/叙述推断参数 | 是 | 签名必须能静态抽取并生成规范化形式 |
| `1.` 条件分支、`-` 循环 | 是 | 新版链接循环形式须通过模式迁移;旧式依赖 Classic |
| Markdown 表格→List/Map/列向表/行向记录 | 是 | 数据语义与契约表应从上下文区别 |
| Frontmatter `import` | 是 | 可作为当前跨文档路径的兼容实现 |
| `[描述](本地表达式)` | v2.0.0 已有,主要需 `markup: occlusion` | 统一后免模式开关;旧 `[键](集合)` 必须避免静默变义 |
| `类.函数` 无实例直接调用 | 未按目标实现 | **新能力**:区分类函数/实例方法、隐式零参调用 |
| 跨文档项目符号索引 | 尚缺 | **新能力**:可控作用域、同名消歧、增量索引 |
| LinkInfo/知识引用图/links.lock | 目标设计 | **新能力**;与已有 EKC 统一,拒绝第二套知识图 |
| 双执行后端(树遍历、字节码) | 是 | 引用语义必须在两个后端一致 |
项目示例分为:**V2-目标示例**(体现最终范式)与**V2.0-兼容示例**(现有调用方式)。所有目标示例是规范性设计,不宣称已在 v2.0.0 执行验证。
## 3. 知识不是代码字符串:规范化语义模型
### 3.1 Semantic Artifact
每个可引用实体编译为 `Artifact`,而非仅落入 AST 一个节点。
```text
Artifact {
symbol_id: StableSymbolId, // 跨增量构建稳定的身份(命名空间 + 显式/规范化路径)
kind: Type | Entity | Fact | Function | Capability | Constraint | Policy | Dataset,
visibility: Local | Module | Project | Exported,
source_span: SourceSpan,
signature: CanonicalSignature?, // 参数、返回值、默认值、单位与结构类型
ir: CompiledIR?, // 运行逻辑或规范化常量;普通叙述可无
effects: EffectSet, // pure / fs.read / fs.write / network / llm / time / random ...
dependencies: [SymbolId],
contract: [Predicate | Schema | Condition],
provenance: [SourceRef],
hashes: { interface, implementation, dependency_closure, evidence },
verification: VerificationRecord
}
```
区分以下四个概念:
- **Identity(身份)**:目标属于哪一知识单元;名称调整可使用迁移映射,不允许悄悄重绑定到不同实体。
- **Content(内容)**:符号当前定义和可执行 IR;代码变更指纹改变。
- **Applicability(适用性)**:参数、业务前提、单位、时间/地区/场景等约束;匹配才可复用。
- **Evidence(证据)**:来源、测试与验证结果。证据改变不等同于程序改变,但需要重新评估可信状态。
### 3.2 Knowledge Reference
```text
KnowledgeRef {
label: String,
payload_ast: Expr,
context: Narrative | Code | Return | Argument | Table | Heading,
resolution: ResolvedSymbol | LocalExpression | NavigationURL | Unresolved,
target_symbol_id: SymbolId?,
target_digest: Digest?,
expected_signature: Signature?,
required_verification: VerificationPolicy,
source_span: SourceSpan
}
```
`[描述](E)` 在运行语义上是透明的,但其静态解析必须构建 KnowledgeRef。在调用点将地址绑定到 `SymbolId`,不能每次由 AI 重新解释描述。
### 3.3 类型 / 知识实体 / 计算能力分别建模
- `# 诗人` 是 Type;`# 李白 = > 诗人` 在现有语法中仍是**继承/特化**。作为 v2.1 过渡方案可视为“单体知识类”,但不得默认为真正的 `instance_of`。
- 事实可以由 `## 出生年份` + 返回值 + 来源表承载;编译器推导为 Fact Artifact。是否是事实要根据可检查的声明/契约,不应仅凭函数名字猜测。
- 业务函数如 `## 计算应付` 是 Function/Capability;不应因为带中文说明就被误识别成事实。
- 未来需要大规模实体库时,Entity/Fact 应支持表驱动注册,不为每个实体强制生成 Rust 或 Marqdo 类。
## 4. `[]()` 的确定语义
### 4.1 一个表面形式、三种解析结果
| 表面形式 | 静态解释 | `run` | `check` / `view` |
|---|---|---|---|
| `**总额=[应付](数量*单价)**` | 本地表达式遮蔽 | 求值 | 保存标签、表达式和诊断 |
| `**总额=[计算总额](Pricing.计算总额(订单))**` | 知识能力调用 | 绑定后调用 | 检查签名、效应、依赖和版本 |
| `文中参见[税率](Policy.税率)` | 叙述知识引用 | 不执行 | 解析、展示受信任/未验证状态,纯目标可选择显式求值 |
| `[项目文档](./guide.md)` | 导航链接 | 不执行 | 保持 Markdown 导航 |
语法上的“同权”是 `()` 与 `**...**` 共用表达式文法;**不是正文和代码拥有相同的执行许可**。 `view` 对具外部效应的目标默认只展示元数据,必须明确授权才允许运行。
### 4.2 最小语义规则
```text
parse_bracket(label, payload, context) -> KnowledgeRef
context ∈ executable_context:
verify_resolved_target(); evaluate(payload_ast)
context ∈ narrative_context:
resolve_only(); never_schedule_effects()
payload ∈ ordinary_navigation:
preserve_as_markdown_link()
```
### 4.3 唯一性与优先级
1. 当前词法作用域的变量/接收者;
2. 当前文档的声明;
3. 显式 `import` 命名空间;
4. 项目导出索引(受 `--fs-root` 和导出策略约束);
5. 内置/已安装扩展。
如果两个候选都满足同一级优先规则,报 `link.ambiguous`;不能随文件顺序自动挑一个。解析失败必须有诊断,不能把知识目标悄悄解释成字面字符串或导航路径。
### 4.4 类函数 vs 实例方法
- 目标函数使用 `self/自` → 实例方法,必须有显式接收者。
- 函数不使用接收者 → 可由 `类.函数` 调用;不运行类的构造体。
- 路径解析到零参函数时可以省略 `()`,但**函数作为一等值的语义必须避免与隐式调用冲突**。建议只有被 `[]()` 用作知识目标、或显式值需求时才触发零参隐式调用;直接 `类.函数` 在函数值场景需明确消歧。最终以一致的形式化语义测试冻结。
### 4.5 版本策略与效应
`interface_digest` 代表签名兼容性,`implementation_digest` 代表实现变化,`dependency_closure_digest` 代表传递依赖;`evidence_digest` 代表证据状态。既存调用在接口未变时不必全部报错,但“严格复现”任务应使用 lock 来禁止目标悄然变化。
纯知识事实允许受控求值与缓存;依赖网络、时间、随机数、外部模型的调用即使锁了源码也不天然确定。必须记录输入快照、环境与效应,并明确“不保证结果复现”的状态。
## 5. 静态分析、来源与可信性
### 5.1 五层验证(必须分层报告)
1. **Parse**:Markdown 结构/语法可解析。
2. **Resolve**:目标存在,歧义可消除。
3. **Type/Contract**:签名、入参与结构类型、单位、前置条件匹配。
4. **Execution/Test**:纯函数或受控沙箱完成运行与测试。
5. **Evidence/Domain**:事实来源可访问,内容匹配,满足适用范围;复杂自然语言事实可能需要人工或 LLM 辅助复核,复核结果必须标识非确定性。
严禁将 `check OK` 展示成“现实知识已被证明正确”。
### 5.2 诊断码草案
| Code | 默认级别 | 含义 |
|---|---|---|
| `link.unresolved` | error | 找不到可绑定的目标 |
| `link.ambiguous` | error | 目标符号不唯一 |
| `link.kind_mismatch` | error | 把类型/实例/函数错当为可执行知识 |
| `link.instance_only` | error | 类调用命中实例方法 |
| `link.arg_mismatch` | error | 参数与签名不符 |
| `link.effect_forbidden` | error | 当前位置不允许此类副作用 |
| `link.target_changed` | warning/error | 被锁定或要求稳定的目标发生变更 |
| `knowledge.source_missing` | warning/error | 来源缺失 |
| `knowledge.source_changed` | warning | 来源指纹变化尚未复核 |
| `knowledge.constraint_unmet` | error | 当前输入不满足适用条件 |
| `knowledge.unverified` | info/warning | 可用但未得到所需级别的验证 |
| `label.ref_dangling` | error | 标签中反引号引用无法解析(保留已有规则) |
| `label.possibly_stale` | hint | 代码变更但描述未更新,需要人工检查 |
标签里提到的自然语言不能被静态类型系统完全证明。所有自动语义比对必须报告置信限制。
## 6. 编译器实施架构
```text
Markdown Source
│
├─ CommonMark/GFM-aware parse + Marqdo lexical context
▼
Syntax AST (prose + code + table + heading + bracket)
▼
Symbol Index (module, class, function, fact, export)
▼
Resolution & Type / Contract / Effect Analysis
▼
Semantic Artifact IR + KnowledgeRef IR
├──────────────┬──────────────────┬───────────────────────┐
▼ ▼ ▼ ▼
Tree Interpreter Bytecode VM View / Debug EKC/Catalog/MLSP
│ │
└──────────┬────────────┘
▼
Agent deterministic reuse
```
**实现优先原则**:统一在语义分析层生成符号与引用元信息。不要在 view、EKC、Agent 中分别重新解析 `.mq.md` 来猜同一段代码代表什么。
### 6.1 Markdown 链接兼容性
`[描述](含空格或括号的表达式)` 不是任意标准 Markdown 渲染器都可识别的合法 URL 目标。Marqdo 必须定义其**源码级别的上下文语义和渲染行为**:先保留有意义的源码跨度,再由专属 view 转为原生可读的标签及悬浮信息;不能假设 GitHub Markdown 会在所有表达式上正确渲染。代码围栏、行内代码、转义以及普通 URL 链接不能被误识别成可执行引用。
### 6.2 旧语法迁移
Classic 的 `[键](集合)` 曾用于取元,`- [项](集合)` 曾用于循环。默认统一为遮蔽含义前,需要 AST 辅助迁移:
```text
[key](table) → [可读描述](at(table, key))
- [item](list) → - [逐项遍历](遍历 list 为 item)
```
避免靠简单正则批量替换;不能把旧代码成功运行但产生不同值视为兼容。迁移应生成审计报告、变更 diff 与双后端对照测试。
## 7. EKC 与 Agent 复用协议
当前 EKC 已有 Symbol、Capability、Knowledge、Context Pack、REUSE→ADAPT→CREATE。将这些能力变为统一 Semantic Artifact 的**投影/索引**,不要再建第二套符号管理器。
Agent 必须按以下状态机处理:
```text
TASK → DISCOVER → RESOLVE → CONTRACT_CHECK
│ │
│ ├─ verified + applicable → REUSE → EXECUTE → TRACE
│ ├─ adaptable → ADAPT → VERIFY → PROMOTE
│ └─ absent/unusable → CREATE → VERIFY → PROMOTE
└─ ambiguous → REQUEST_DISAMBIGUATION / FAIL_CLOSED
```
- **Discovery 是召回**,可以模糊检索,不等于可信复用。
- **Resolve 必须精确**,让自然语言意图最终绑定到具体 `SymbolId`。
- **Reuse 是编译器行为**:Agent 持有可验证引用,并使用明确的输入与契约,不复制代码段。
- **Promote 是门槛**:新生成内容必须通过所需静态检查、测试与来源规则才可进入已验证知识索引。
- **Trace 可审计**:保存“这次回答具体用了哪些符号、哪些版本和哪些输入”,不是仅存 LLM 的解释文本。
建议新增的 MLSP 读接口:`artifact.find`、`artifact.inspect`、`link.resolve`、`artifact.verify`、`artifact.impact`、`artifact.bind`;后者在编译器确定性解析后返回可调用句柄/引用描述,不应凭自然语言标签直接执行。
## 8. 里程碑与硬验收
### M0 语义冻结
明确新语义与 Classic 的区别,形成机器可读 gold cases,涵盖 URL、嵌套括号、空标签、取元、循环、代码围栏、换行、标题、叙述链接与作用域。所有未经标注的旧语义变化不得静默放行。
### M1 符号身份与项目索引
构建导出符号表、稳定 `SymbolId`、同名诊断。验收:同仓两个 `李白` 定义应报歧义;限定名可解析;改变目录扫描顺序不影响绑定结果。
### M2 统一 Bracket IR 与类函数调用
语法识别→表达式解析→目标绑定→双后端执行。验收:含 `self` 与不含 `self` 的函数正确分派,构造不产生意外副作用;正文不自动执行。
### M3 Semantic Artifact / 验证
签名、effect、contract、provenance、验证记录与指纹。验收:接口修改、依赖修改、证据变化、适用条件不匹配得到不同诊断。
### M4 EKC、view、agent 集成
整个工具链共享 SymbolId/LinkInfo,生成 links graph、可查看调用与来源、可追踪复用。验收:图边与实际编译的调用目标完全一致;Agent 命中已有能力时不得偷偷生成新实现。
### M5 基准实验(对照 Python/Notebook/普通 Markdown+检索)
同一模型、同一任务集、相当的工具与提示预算;分别统计可执行成功率、知识错误引用率、重复实现比例、文件改动数、调用/修复次数、总 tokens、端到端时延、可复核程度。公开任务、生成器、冻结环境、置信区间和失败样本;不要使用只在 Marqdo 方案可解的夹具,也不要把编译器固有优势等同整个 Agent 的领先。
## 9. 设计原则冻结
1. **源码可读,编译结果确定**。
2. **知识是制品,不是文本片段**。
3. **检索可以模糊,绑定必须确定**。
4. **知识能够执行,但执行不等于真实**。
5. **知识可以复用,但必须满足契约与适用条件**。
6. **显示文字可自由,语义判断不依赖显示文字**。
7. **默认保持叙述安全,副作用需要明确执行上下文**。
8. **保持一种语法,一个语义解析器,一套符号索引**。
9. **双后端与 view/EKC 使用同一份语义中间表示**。
10. **失败必须可观察,不能因为链接看起来优雅而隐去错误**。
## 10. 来源依据
仓库:<https://github.com/cflmy/marqdo>。重点阅读:
- `README.md`(v2.0.0 现状与 v2.1 目标)
- `doc/design/markdown-mapping-v0.3.md`(基本语法)
- `doc/design/objects.md`(类、实例、自/self、继承)
- `doc/design/link-syntax.md`(现有链接设计声明)
- `doc/design/occlusion-syntax.md`(遮蔽与描述新鲜度)
- `doc/design/knowledge-layers.md`(知识分层、过渡型单体类)
- `doc/design/engineering-knowledge.md`(EKC 与复用流程)
- `.cursor/skills/marqdo/reference.md` 与 `examples.md`(参考语法;其部分 Classic 旧写法必须经过迁移)
附录项目:`Marqdo_Executable_Knowledge_Example.md`。其中对未实现特性逐项标注,所有业务数据均为虚构演示数据。
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,400 @@
# Marqdo 可执行知识范式:多文件完整示例与对照
> **规范性目标示例**:用于描述 v2.1+ 期望语义;并非宣称 v2.0.0 已能运行所有代码。示例内价格、折扣、门槛均为虚构业务数据。
> 展示:Markdown 叙述、frontmatter 导入、`#` 类型、`##` 函数、继承、表格集合、隐式形参、`**` 代码、`*` 返回、条件有序列表、循环无序列表、变量反引号、带描述的 `[]()`、对象、契约、来源、知识索引与 Agent 复用。
## 1. 实际业务场景
一家虚构的“云雀书店”需要将定价规则维护为**人类可阅读的运营文档**,由网站、客服机器人、后端结算、审计报告复用,而不是让四个 AI 分别根据文字重新写四次逻辑。业务规则:普通会员 100% 计价,银卡会员 95%,金卡会员 90%;订单满 100 元免 8 元运费;仅处理人民币订单,件数为正整数。所有规则均为示例,没有现实效力。
### 项目结构
```text
bookshop/
├─ corpus/
│ └─ pricing-policy.md # 业务原始资料(不可执行)
├─ knowledge/
│ ├─ policy.mq.md # 已编译的政策知识
│ ├─ order.mq.md # 数据类型及订单操作
│ └─ pricing.mq.md # 定价能力
├─ apps/
│ ├─ checkout.mq.md # 业务执行入口
│ ├─ assistant.mq.md # AI 问答呈现/知识引用
│ └─ batch.mq.md # 列表与循环
└─ .marqdo/ # 生成:catalog、symbols、graph、links.lock
```
## 2. 原始资料 `corpus/pricing-policy.md`
```markdown
# 云雀书店价格政策(演示)
生效范围:2026 年演示订单,人民币;不代表任何真实商店。
## 会员折扣
普通会员不优惠;银卡会员九五折;金卡会员九折。
## 运费
商品合计满 100 元免运费,否则运费为 8 元。
## 约束
商品单价不得为负;数量必须为正整数。会员等级仅允许普通、银卡、金卡。
```
这是原始证据,并非运行时调用目标。它可被查看、引用和版本化,但不能因为被 AI 读到就自动获得 `verified` 状态。
## 3. 政策知识 `knowledge/policy.mq.md`
使用现有类/函数、返回值与契约表,将业务知识拆成稳定的、可发现的编译单元。
```markdown
---
title: 云雀书店演示定价政策
type: policy
---
# 书店政策
这是云雀书店的演示业务政策,供结算、客服和审计引用。
规则只适用于人民币演示订单,来源为
[价格政策原文](../corpus/pricing-policy.md)。
## 金卡折扣
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 0.90 | number | ratio | corpus/pricing-policy.md#会员折扣 |
*0.90*
## 银卡折扣
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 0.95 | number | ratio | corpus/pricing-policy.md#会员折扣 |
*0.95*
## 免运费门槛
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 100 | number | CNY | corpus/pricing-policy.md#运费 |
*100*
## 基础运费
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 8 | number | CNY | corpus/pricing-policy.md#运费 |
*8*
## 获取折扣
根据输入会员等级`等级`确定折扣比例。
| 参数 | 类型 | 说明 |
|---|---|---|
| 等级 | text | 普通、银卡、金卡 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 比例 | number | 0 到 1 之间的比例 |
1. `等级` == "金卡"
*[金卡优惠比例](书店政策.金卡折扣)*
2. `等级` == "银卡"
*[银卡优惠比例](书店政策.银卡折扣)*
3. *
*1*
```
**说明**:`书店政策.金卡折扣` 等类函数直接调用属于 v2.1 目标;现有 `#` 类型/`##` 方法和表格、分支是当前语言能力。严格策略下,非法会员等级应报 `knowledge.constraint_unmet` 而不是无条件走默认分支;此处末尾 `3. *` 只是语言分支结构示范,正式实现需要额外拒绝非法等级。
## 4. 订单类型与继承 `knowledge/order.mq.md`
```markdown
# 订单
一个订单至少包含数量、单价和会员等级。
## 描述
本方法使用`自`读取对象字段,属于**实例方法**。
*自*
# 线上订单 = > 订单
线上订单是订单类型的一个特化。此处是实际继承语义,不把它误称为“知识实体实例化”。
## 渠道
*"online"*
```
注意:`# 线上订单 = > 订单` 在 Marqdo 中的确代表子类型继承;`> 线上订单` 构造实例,实例方法需要实例接收者。在知识分层中,普通 Fact 不应强制视为类实例。
## 5. 核心能力 `knowledge/pricing.mq.md`
这是“知识直接被复用”的核心,而不是把文字重新交给 AI 算一遍。
```markdown
---
title: 价格计算能力
import policy:knowledge/policy.mq.md
---
# 定价
下列函数实现演示书店的结算规则,适用于人民币演示订单。
## 计算商品小计
输入商品`单价`和`数量`。
| 参数 | 类型 | 约束 |
|---|---|---|
| 单价 | number | 大于等于 0;单位 CNY |
| 数量 | number | 大于 0,且为整数 |
| 返回 | 类型 | 单位 |
|---|---|---|
| 小计 | number | CNY |
**小计 = [商品小计](单价 * 数量)**
*小计*
## 计算运费
根据商品折扣后的金额`金额`决定是否免运费。
1. `金额` >= [免运费门槛](书店政策.免运费门槛)
*0*
2. *
*[基础运费](书店政策.基础运费)*
## 计算应付金额
接受`单价`、`数量`、`等级`;输出应付总金额。
**小计 = [商品小计](定价.计算商品小计(单价, 数量))**
**折扣 = [当前会员折扣](书店政策.获取折扣(等级))**
**折后价 = [折扣后商品金额](小计 * 折扣)**
**运费 = [应收运费](定价.计算运费(折后价))**
**应付 = [最终应付人民币金额](折后价 + 运费)**
*应付*
```
**目标能力标记**:这一示例使用 `类.函数` 静态调用、跨文档自动类索引以及嵌入条件表达式中的知识引用,这些是计划实现的语义。当前实际版本中,一般需要显式 `import` 和实例句柄。其余 `**代码**`、`*返回*`、契约表、分支为现有基础。
这里看得最清楚:对读者,整段代码是一个有清晰描述的计算故事;对编译器,括号内是有类型、依赖、来源的调用图;对 AI,复用的不是价格公式的自然语言解释,而是绑定到已有符号的能力。
## 6. 结算入口 `apps/checkout.mq.md`
```markdown
---
title: 演示结算
import pricing:knowledge/pricing.mq.md
---
# main
一位金卡用户购买两件单价 60 元的商品。
**单价 = 60**
**数量 = 2**
**等级 = "金卡"**
**应付 = [本次订单应付款](定价.计算应付金额(单价, 数量, 等级))**
> 打印 内容=`应付`
```
预期:`60 × 2 × 0.90 = 108` 元,达到免运费门槛,输出 `108`。这是目标语义下的预期值,而非当前版本的实测输出。
**对照(相对现有版本更接近可执行)**:使用 `import`、构造实例,再调用实例方法。下面的最小兼容样例来自仓库 `examples/link-syntax/main.compat.mq.md`:
```markdown
---
markup: occlusion
import libai:libai.mq.md
---
# main
**li = > libai.李白**
**year = [李白的出生年份](li.李白的出生年份())**
> print text=`year`
```
此兼容片段是仓库实例,不能直接替代上面的定价案例:它用于说明当前版本与目标引用模型之间的差距。
## 7. 文档问答 `apps/assistant.mq.md`
```markdown
# main
# 云雀书店结算说明
普通会员原价结算;金卡会员使用[已登记的金卡折扣](书店政策.金卡折扣)。
当前免运费门槛为[已登记的门槛金额](书店政策.免运费门槛)。
关于政策出处,参见[原始价格政策](../corpus/pricing-policy.md)。
```
这展示**知识链接与导航链接共存**:前两条必须由编译器解析知识目标,最后一条仍是传统 Markdown 导航。不应把全文正文都作为主动执行入口。UI 可以显示“来源文件/目标类型/验证状态/必要时的值”;若目标未验证,应明确标注。
## 8. 表格几何与循环 `apps/batch.mq.md`
演示一列 List、横表 Map、`@` 行向记录、无序列表循环和条件分支。根据 v2.0 新语义,旧 `[key](collection)` 取元改为 `at(collection,key)`。
```markdown
---
markup: occlusion
---
# main
`会员等级` =
| 等级 |
|---|
| 普通 |
| 银卡 |
| 金卡 |
`折扣说明` =
| 普通 | 银卡 | 金卡 |
|---|---|---|
| 1 | 0.95 | 0.90 |
`演示订单` =
| @ | 客户 | 等级 | 单价 | 数量 |
|---|---|---|---|---|
| 1 | 甲 | 金卡 | 60 | 2 |
| 2 | 乙 | 银卡 | 30 | 2 |
**银卡比例 = [银卡折扣值](at(折扣说明, "银卡"))**
- [逐个检查会员等级](遍历 会员等级 为 等级)
1. `等级` == "金卡"
> 打印 内容="识别到金卡会员"
2. *
> 打印 内容=`等级`
```
表格语义:单列→List;两列以上一数据行→Map;首列 `@`→按行组成的 List of Map。此处只演示集合构造、访问与循环,避免假定尚未验证的嵌套函数语义。`遍历` 链接循环是新设计形式,必须通过现有版本的解析器验收后才能标记为已实现。
## 9. 编译后的产物应当长什么样
下列均是**建议输出示意**,不是现有 CLI 的真实输出:
```json
{
"symbol": "knowledge://bookshop/定价/计算应付金额",
"kind": "capability",
"signature": {
"params": ["单价:number", "数量:number", "等级:text"],
"returns": "number:CNY"
},
"dependencies": [
"knowledge://bookshop/定价/计算商品小计",
"knowledge://bookshop/书店政策/获取折扣",
"knowledge://bookshop/定价/计算运费"
],
"effects": ["pure"],
"verification": {"parse": "ok", "resolve": "ok", "contracts": "ok", "evidence": "pending"}
}
```
假设用户把政策金卡折扣由 0.90 改为 0.88,正确行为应该是:
1. `书店政策.金卡折扣` 的实现摘要变化;
2. `书店政策.获取折扣` 与 `定价.计算应付金额` 的传递依赖指纹变化;
3. 所有引用这些知识的文档都能由 `impact` 找到;
4. 如果使用 lock,校验报告“知识目标变更”,而不是静默引用新版;
5. 修改政策的原始来源还需要单独复核,不把源码更新等同于证据更新;
6. Agent 必须先检查适用性和验证状态,不能拿一个未复核的版本装作确定事实。
## 10. AI 原生复用:有无语义制品的差别
**传统文档 + RAG**:
```text
用户问“金卡买两件 60 元的商品多少钱?”
→ 检索到价格政策.md
→ LLM 阅读、复述并临时写计算步骤
→ 得到 108(本次碰巧正确)
→ 下次又重新解释规则,可能遗漏免运费条件
```
**Marqdo 目标路径**:
```text
用户请求
→ EKC.find("计算应付金额") // 发现候选,不等于信任
→ artifact.inspect(定价.计算应付金额) // 得到签名、适用范围、来源
→ link.resolve(...) // 确定性绑定具体符号
→ verify(contract, input) // 单价60、数量2、等级金卡
→ execute(bound_symbol, input) // 执行编译制品,得到108
→ trace(symbol+digest+input+result) // 可审计记录
→ AI 用自然语言解释结果
```
AI 不必记住“满百免运费”的公式,也不用每次生成新的结算代码。它需要做的是找准能力、验证条件并引用它。
## 11. 演示必须通过的负例
| 变更/攻击输入 | 期待结果 |
|---|---|
| 将 `书店政策.金卡折扣` 改名但未迁移引用 | `link.unresolved` |
| 新增第二个同名 `书店政策` | `link.ambiguous` |
| 对 `定价.计算应付金额` 漏传数量 | `link.arg_mismatch` |
| 数量传入 0 | `knowledge.constraint_unmet` |
| 来源 `pricing-policy.md` 删除 | `knowledge.source_missing` |
| 来源内容变化但知识函数不变 | `knowledge.source_changed` |
| 来源规则仍然正确但业务已过期 | 需要过期/适用期检查,不能自动声称 verified |
| 尝试在正文链接里执行网络支付 | `link.effect_forbidden` 或只解析不执行 |
| 标签写“免费”但表达式仍产生费用 | 结构检查可能通过;标签语义审查需报警或人工审核,不得保证静态证明 |
| 类实例方法经 `类.方法` 直接调用 | `link.instance_only` |
## 12. 为什么这个范式更强
1. **人类维护规则**:读的是 Markdown 业务故事、表格与政策,不是必须遍历全仓源码。
2. **编译器复用行为**:跨文档引用已绑定语义制品,避免重复造轮子。
3. **错误能被提前拦截**:同名、失效、类型、契约、来源变化有各自诊断。
4. **审计能回答“依据是什么”**:结果、符号、版本、输入和来源可追踪。
5. **AI 只负责不确定环节**:意图匹配、适用性判断、结果解释;确定性的计算留给编译制品。
6. **上下文可以缩短,但不是无条件保证**:目标是让 Agent 读取能力摘要而非每次粘贴全部实现;是否节省 tokens 需要客观实验。
**核心竞争力不是 Markdown 链接本身,而是“自然语言描述 → 精确符号绑定 → 可验证语义制品 → 执行与复用”的完整链条。**
## 13. 语法覆盖与非目标
本示例涵盖语法主干,但“全部语法”还包括外联代码围栏、公式 `$$`、浏览器/WASM、原生插件 ABI、量子与线性代数扩展、MCP/Agent、网络和文件 API 等。它们的具体运行依赖扩展与环境,不能当作知识引用所必需的语言核心;统一 IR 应允许这些能力以受效应约束的 Artifact 注册和复用,而不必将每种扩展硬塞入同一个教学案例。
建议另建生态回归套件:
- foreign/LLM/network 函数注册为 EffectSet 的非纯函数;
- 数学公式与表格按返回类型编译为 Artifact;
- 浏览器和 Web 插件导出的能力经符号索引显式引用;
- Agent 的复用接口通过 MLSP 获得固定签名与效果说明。
## 14. 原仓库参考资料
- <https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/objects.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/knowledge-layers.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/engineering-knowledge.md>
- <https://github.com/cflmy/marqdo/blob/main/examples/link-syntax/main.compat.mq.md>
@@ -0,0 +1,83 @@
# 可执行知识语法:仓库级测试与兼容性规程
本文是 `Marqdo_Executable_Knowledge_Development.md` 的验证规程。它约束稳定符号 URI、零参数知识路径、关联函数/实例方法区分及其 CLI 解析进入标准库、扩展库和发布流程后的测试方式。
## 覆盖目标
新写法只在需要值的位置把零参数路径解释为调用:
```marqdo
**pi = math.pi**
**year = facts.Person.birth_year**
```
旧的 `**pi = > math.pi**` 和 `> math.pi` 继续兼容。对象子函数不读取 `self` / `自` 时是 `associated_function`;读取接收者时是 `instance_method`,不能由 `Type.method` 直接执行。
每项语法变更必须同时证明:新写法正确、旧写法未回归、Tree/Bytecode 一致、CLI 静态解析和运行时规则一致,并且标准库与扩展库仍能加载、运行。
## 自动化测试矩阵
| 层级 | 覆盖内容 | 命令 | 通过条件 |
|---|---|---|---|
| 解析 | 零参路径降级 Call;带参路径不能静默执行 | `cargo test --locked --lib parse::expr` | AST、参数数与诊断稳定 |
| 语义 | ProjectRoot、ModuleId、SymbolId、关联/实例分类、歧义 | `cargo test --locked --lib sema::` | 扫描顺序不影响结果;分类不改变 SymbolId |
| Tree | 标准库裸路径、关联函数、旧写法 | `cargo test --locked --test gold structure_new_path_stdlib structure_ns_associated_function` | stdout 金样一致 |
| Bytecode | 同一正例的后端一致性 | `cargo test --locked --test gold bytecode_new_path_stdlib bytecode_ns_associated_function` | stdout、退出码一致 |
| 负例 | 接收者依赖路径被拒绝 | `cargo test --locked --test gold error_ns_instance_method knowledge_resolve_rejects_instance_path` | 不构造对象、不执行方法 |
| CLI | `inspect` / `resolve` JSON | `cargo test --locked --test gold knowledge_resolve_new_path` | 返回 URI、source、callable;resolve 不执行代码 |
| 标准库 | 英文/中文零参知识 | `cargo test --locked --test gold lib_log_uuid_smoke lib_log_uuid_zh_smoke` | `uuid.v4` 等裸路径可用 |
| 扩展库 | 改写后的扩展调用和插件加载 | `cargo test --locked --test gold ext_quantum_gates_smoke` | `math.pi` 新写法输出不变 |
## 每次语法改动的执行顺序
```bash
source scripts/dev-env.sh
cargo check --locked
cargo test --locked --lib
cargo test --locked --test gold -- --test-threads=1
cargo test --locked
cargo build --locked
```
发布前再做可观察的 CLI/双后端冒烟:
```bash
target/debug/marqdo knowledge tests/structure/ns --json resolve \
helpers.Box.birth_year --from tests/structure/ns/associated.mq.md
target/debug/marqdo run tests/structure/new-path-stdlib.mq.md --backend tree
target/debug/marqdo run tests/structure/new-path-stdlib.mq.md --backend bytecode
```
完整 gold 会构建部分原生/Go 扩展,必须单线程执行。网络、真实 LLM 与 ignored 实验不属于离线语法门禁,不能以其失败掩盖核心回归。
## 标准库与扩展库改写准则
仅改写可机械证明等价的值表达式:
| 原写法 | 新写法 | 前提 |
|---|---|---|
| `**x = > math.pi**` | `**x = math.pi**` | 目标零参数、值位置 |
| `**id = > uuid.v4**` | `**id = uuid.v4**` | 目标零参数、值位置 |
| `**x = > Type.fact**` | `**x = Type.fact**` | 目标为关联函数 |
禁止自动改写副作用语句、带必填参数函数、实例方法、文本/围栏/URL/导航链接,以及不能同时通过 Tree/Bytecode 的变更。本轮用 `math.pi`(量子扩展夹具)、`数学.圆周率`(中文标准库夹具)和 `uuid.v4`(标准库夹具)作为真实金样。
## CLI 合约
```text
marqdo knowledge PATH --json inspect SYMBOL
marqdo knowledge PATH --json resolve REFERENCE --from CALLER.mq.md
```
`resolve` 只绑定、不执行。它依据 `--from` 的 frontmatter import 解析第一个路径段,不会在项目中按名字猜测目标。关联函数返回 `resolution: "symbol"`;实例方法返回 `resolution: "instance_only"` 并以退出码 1 拒绝直接路径调用。
## 发布门槛
1. `git diff --check` 无错误;
2. Rust 核心、gold、完整 `cargo test --locked` 通过;
3. 每个新正例有 Tree、Bytecode 和 CLI(适用时)覆盖;
4. 每个语义拒绝路径有稳定负例;
5. 标准库/扩展库改写保留原 stdout 金样;
6. 不提交 `.marqdo/`、插件构建物或本地凭据。
失败报告必须记录命令、后端、夹具、stdout/stderr、插件/网络依赖及与旧写法的差异。
File diff suppressed because it is too large. Load diff
@@ -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 和路线进度:分别标记语言能力、协议子集、产品已接入、当前测试结果。优先把失败样例转成稳定回归门禁,再扩大“可验证知识”“业务复用”“上传编译”的能力声明。此次文档提交不表示缺口已修复。
+2 -1
View File
@@ -79,7 +79,8 @@ Marqdo 用 `#` 标题定义**对象 / 类型**,用 `##` 定义其下的**方
```markdown
---
import json:lib/json.mq.md
import:
json: lib/json.mq.md
---
# main
+16 -10
View File
@@ -17,8 +17,9 @@ description: 描述文字
```markdown
---
import text:lib/text.mq.md
import time:lib/time.mq.md
import:
text: lib/text.mq.md
time: lib/time.mq.md
---
```
@@ -35,8 +36,9 @@ import time:lib/time.mq.md
```markdown
---
import time:lib/time.mq.md
import json:lib/json.mq.md
import:
time: lib/time.mq.md
json: lib/json.mq.md
---
# main
@@ -55,7 +57,8 @@ import json:lib/json.mq.md
```markdown
---
import agent:ext/ai/agent.mq.md
import:
agent: ext/ai/agent.mq.md
---
# main
@@ -71,8 +74,9 @@ import agent:ext/ai/agent.mq.md
```markdown
---
import time:lib/time.mq.md
import fmt:time.format
import:
time: lib/time.mq.md
fmt: time.format
---
# main
@@ -98,7 +102,8 @@ import fmt:time.format
```markdown
---
import agent:ext/ai/agent.mq.md
import:
agent: ext/ai/agent.mq.md
---
# main
@@ -143,8 +148,9 @@ project/
```markdown
---
import 数学:lib/数学.mq.md
import 问候:lib/问候.mq.md
import:
数学: lib/数学.mq.md
问候: lib/问候.mq.md
---
# main
+10 -5
View File
@@ -56,7 +56,8 @@ Marqdo 内置函数无需导入即可使用;更丰富的能力通过导入 `li
```markdown
---
import json:lib/json.mq.md
import:
json: lib/json.mq.md
---
# main
@@ -85,7 +86,8 @@ import json:lib/json.mq.md
```markdown
---
import text:lib/text.mq.md
import:
text: lib/text.mq.md
---
# main
@@ -101,7 +103,8 @@ import text:lib/text.mq.md
```markdown
---
import math:lib/math.mq.md
import:
math: lib/math.mq.md
---
# main
@@ -114,7 +117,8 @@ import math:lib/math.mq.md
```markdown
---
import math:lib/math.mq.md
import:
math: lib/math.mq.md
---
# main
@@ -145,7 +149,8 @@ marqdo ext add quantum
```markdown
---
import llm:ext/llm.mq.md
import:
llm: ext/llm.mq.md
---
# main
+11 -6
View File
@@ -29,7 +29,8 @@ marqdo ext add web
```markdown
---
import net:lib/net.mq.md
import:
net: lib/net.mq.md
---
# main
@@ -84,7 +85,8 @@ route: /
method: GET
data_source: posts
data_order: -created_at
import web:ext/web/web.mq.md
import:
web: ext/web/web.mq.md
---
# 我的站点
@@ -118,8 +120,9 @@ response: json
```markdown
---
import web:ext/web/web.mq.md
import posts:db/posts.mq.md
import:
web: ext/web/web.mq.md
posts: db/posts.mq.md
---
# main
@@ -145,7 +148,8 @@ import posts:db/posts.mq.md
```markdown
---
import data:ext/data/db.mq.md
import:
data: ext/data/db.mq.md
---
# main
@@ -162,7 +166,8 @@ HTTP 门禁与登录走 `ext/security`(`auth` / `rbac` / `oidc`),再用 `w
```markdown
---
import rbac:ext/security/rbac.mq.md
import:
rbac: ext/security/rbac.mq.md
---
# main
+4 -2
View File
@@ -318,7 +318,8 @@ error: cannot resolve import `../execution/docgate.mq.md` from
**跨目录**才用 `..`:
```markdown
import ctx:../knowledge/context.mq.md
import:
ctx: ../knowledge/context.mq.md
```
### 5.2 库名必须导入,不能用裸名
@@ -328,7 +329,8 @@ error: unknown library `json` (import it in frontmatter)
```
```markdown
import json:lib/json.mq.md
import:
json: lib/json.mq.md
```
标准库函数要**带库名前缀**:`json.parse`、`txt.contains`、`table.put`。
+8 -6
View File
@@ -1,12 +1,14 @@
---
markup: occlusion
title: agent-okf-flywheel (Wave B0)
description: Promote solidified workbook; second plan is cache=hit — document as knowledge base (OKF).
import llm:ext/ai/llm.mq.md
import agent:ext/ai/agent.mq.md
import fs:lib/fs.mq.md
import json:lib/json.mq.md
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import:
llm: ext/ai/llm.mq.md
agent: ext/ai/agent.mq.md
fs: lib/fs.mq.md
json: lib/json.mq.md
plugin: lib/plugin.mq.md
sys: lib/sys.mq.md
---
# main
+8 -6
View File
@@ -1,14 +1,16 @@
---
markup: occlusion
title: agent-pong (Wave B0)
description: >-
Constitution demo — call_site + source in step context; optional live CALL via .env.
Code is documentation; tools are ## in this same file.
import llm:ext/ai/llm.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import time:lib/time.mq.md
import:
llm: ext/ai/llm.mq.md
agent: ext/ai/agent.mq.md
json: lib/json.mq.md
plugin: lib/plugin.mq.md
sys: lib/sys.mq.md
time: lib/time.mq.md
---
## 获取时间
+9 -7
View File
@@ -1,9 +1,11 @@
---
markup: occlusion
title: agent-sandbox-okf — trial then commit
description: >
O1 example: opt-in sandbox trial with GFM-table returns and link-index reads.
import agent:ext/ai/agent.mq.md
import fs:lib/fs.mq.md
import:
agent: ext/ai/agent.mq.md
fs: lib/fs.mq.md
---
# main
@@ -19,8 +21,8 @@ Short demo: write via `agent.trial`, prove the host is clean until commit.
> fs.make_dir path="_example_sbx"
**dry = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=False**
**dry_ok = [ok](dry)**
**dry_committed = [committed](dry)**
**dry_ok = [ok](access(dry, "ok"))**
**dry_committed = [committed](access(dry, "committed"))**
1. `dry_ok`
1. not `dry_committed`
> print text=dry-ok
@@ -36,8 +38,8 @@ Short demo: write via `agent.trial`, prove the host is clean until commit.
> print text=host-clean
**wet = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=True**
**wet_ok = [ok](wet)**
**wet_committed = [committed](wet)**
**wet_ok = [ok](access(wet, "ok"))**
**wet_committed = [committed](access(wet, "committed"))**
1. `wet_ok`
1. `wet_committed`
> print text=wet-ok
@@ -52,7 +54,7 @@ Short demo: write via `agent.trial`, prove the host is clean until commit.
2. *
> print text=proof-missing
**pname = [name]([profile](wet))**
**pname = [name](access([profile](access(wet, "profile")), "name"))**
1. `pname` == "default"
> print text=profile-default
2. *
@@ -1,4 +1,5 @@
---
markup: occlusion
title: components/chrome
description: 暗恋见君壳层 — head 资源表、导航 HTML、页脚 HTML(对齐 Django base / site_footer)。
---
+3 -2
View File
@@ -2,8 +2,9 @@
markup: occlusion
title: components/feed
description: 帖子列表 / 新闻时间线 / 板块栏 HTML 片段(对齐 Django feed 与 home 局部模板)。
import table:lib/table.mq.md
import text:lib/text.mq.md
import:
table: lib/table.mq.md
text: lib/text.mq.md
---
## 帖子列表HTML
+4
View File
@@ -1,3 +1,7 @@
---
markup: occlusion
---
## 页脚
站点信息与站长链接(毛玻璃底由壳样式绘制)。
@@ -1,9 +1,11 @@
---
markup: occlusion
title: components/fragments
description: AJAX 片段 — /post/ten、/news/five。
导入 网页:ext/web/网页.mq.md
import db:../db/index.mq.md
import feed:feed.mq.md
导入:
网页: ext/web/网页.mq.md
db: ../db/index.mq.md
feed: feed.mq.md
---
## 帖子十
+4
View File
@@ -1,3 +1,7 @@
---
markup: occlusion
---
## 首页引言
英雄区 HTML(品牌标语 + CTA + 漂浮主图)。样式在 `styles/shell` 的 Hero / 动效表。
@@ -1,10 +1,12 @@
---
markup: occlusion
title: components/home_body
description: 首页主体 HTML — hero + 公告 + 新闻时间线 + 论坛帖子(对齐 Django home.html,无外层导航)。
导入 网页:ext/web/网页.mq.md
import table:lib/table.mq.md
import text:lib/text.mq.md
import feed:feed.mq.md
导入:
网页: ext/web/网页.mq.md
table: lib/table.mq.md
text: lib/text.mq.md
feed: feed.mq.md
---
## 装配
@@ -19,9 +21,9 @@ import feed:feed.mq.md
**帖子行 = > 库.查询 表="posts" 上限=10 排序="-created_at"**
**公告段 = None**
- [告](公告行)
**文 = [content](告)**
**时 = [created_at](告)**
- [告](遍历 公告行 为 告)
**文 = [content](access(告, "content"))**
**时 = [created_at](access(告, "created_at"))**
**一项 = "<div class=\"notice-item\"><article class=\"notice-content\">" + 文 + "</article><p class=\"notice-create-time\">" + 时 + "</p></div>"**
**公告段 = > table.append list=公告段 item=一项**
1. 公告段
+4
View File
@@ -1,3 +1,7 @@
---
markup: occlusion
---
## 导航
顶栏:首页、帖子、新闻、搜索、聊天、发帖(登录后)、后台。
+4 -2
View File
@@ -1,8 +1,10 @@
---
markup: occlusion
title: components/page
description: 用原站 chrome 包一层完整 HTML 引言(bare 布局)。
import text:lib/text.mq.md
import chrome:chrome.mq.md
import:
text: lib/text.mq.md
chrome: chrome.mq.md
---
## 包装
+5 -3
View File
@@ -1,9 +1,11 @@
---
markup: occlusion
title: db/index
description: 打开库、建全表、幂等种子、帖子全文索引。
导入 网页:ext/web/网页.mq.md
import schema:schema.mq.md
import seed:seed.mq.md
导入:
网页: ext/web/网页.mq.md
schema: schema.mq.md
seed: seed.mq.md
---
## 打开
+4
View File
@@ -1,3 +1,7 @@
---
markup: occlusion
---
## posts
帖子主表。`slug` 用于详情路径;`board` 为板块显示名,`board_id` 关联 `boards`。
+4
View File
@@ -1,3 +1,7 @@
---
markup: occlusion
---
## boards
帖子板块:日常 / 开发 / 聊天。
+19 -17
View File
@@ -1,15 +1,17 @@
---
markup: occlusion
title: 暗恋见君 · Marqdo
description: 对齐 Django 暗恋见君:原站 CSS/DOM、首页四段、列表详情、发帖门禁、聊天室、专题、搜索、API 指南。
导入 网页:ext/web/网页.mq.md
import table:lib/table.mq.md
import text:lib/text.mq.md
import chrome:components/chrome.mq.md
import page:components/page.mq.md
import home:components/home_body.mq.md
import feed:components/feed.mq.md
import fragments:components/fragments.mq.md
import db:db/index.mq.md
导入:
网页: ext/web/网页.mq.md
table: lib/table.mq.md
text: lib/text.mq.md
chrome: components/chrome.mq.md
page: components/page.mq.md
home: components/home_body.mq.md
feed: components/feed.mq.md
fragments: components/fragments.mq.md
db: db/index.mq.md
---
# main
@@ -140,10 +142,10 @@ import db:db/index.mq.md
**房间行 = > store.查询 表="chat_rooms" 上限=50**
**房间段 = None**
- [房](房间行)
**名 = [name](房)**
**链 = [slug](房)**
**摘 = [summary](房)**
- [房](遍历 房间行 为 房)
**名 = [name](access(房, "name"))**
**链 = [slug](access(房, "slug"))**
**摘 = [summary](access(房, "summary"))**
**项 = "<article class=\"chat-room-card\"><h3><a href=\"/chat/" + 链 + "\">" + 名 + "</a></h3><p>" + 摘 + "</p></article>"**
**房间段 = > table.append list=房间段 item=项**
**房间内 = > text.str_join xs=房间段 sep=""**
@@ -164,10 +166,10 @@ import db:db/index.mq.md
**专题行 = > store.查询 表="topics" 上限=50**
**专题段 = None**
- [题](专题行)
**题名 = [title](题)**
**链 = [slug](题)**
**摘 = [summary](题)**
- [题](遍历 专题行 为 题)
**题名 = [title](access(题, "title"))**
**链 = [slug](access(题, "slug"))**
**摘 = [summary](access(题, "summary"))**
**项 = "<article class=\"topic-card\"><h3>" + 题名 + "</h3><p>" + 摘 + "</p><p class=\"text-muted\">slug: " + 链 + "</p></article>"**
**专题段 = > table.append list=专题段 item=项**
**专题内 = > text.str_join xs=专题段 sep=""**
+12 -10
View File
@@ -1,12 +1,14 @@
---
markup: occlusion
title: anlian-mq offline smoke
description: 不 listen:装配库表/页面/门禁/WS 路由袋,验证可读路径可构造。
导入 网页:ext/web/网页.mq.md
import shell:styles/shell.mq.md
import nav:components/nav.mq.md
import foot:components/foot.mq.md
import db:db/index.mq.md
import sys:lib/sys.mq.md
导入:
网页: ext/web/网页.mq.md
shell: styles/shell.mq.md
nav: components/nav.mq.md
foot: components/foot.mq.md
db: db/index.mq.md
sys: lib/sys.mq.md
---
# main
@@ -44,7 +46,7 @@ import sys:lib/sys.mq.md
**应用 = > 应用.门禁 路径="/write" 角色="admin" 匹配="prefix" 拒绝="redirect"**
**应用 = > 应用.路由实时 路径="/chat/ws" 模式="broadcast"**
**gates = [gates](应用)**
**gates = [gates](access(应用, "gates"))**
**n = > len value=`gates`**
1. `n` >= 2
> print text=gates-ok
@@ -52,9 +54,9 @@ import sys:lib/sys.mq.md
> print text=gates-fail
> sys.exit code=1
**ws = [ws_routes](应用)**
**room = [/chat/ws](ws)**
**mode = [mode](room)**
**ws = [ws_routes](access(应用, "ws_routes"))**
**room = [/chat/ws](access(ws, "/chat/ws"))**
**mode = [mode](access(room, "mode"))**
1. `mode` == "broadcast"
> print text=ws-ok
2. *
+4 -2
View File
@@ -1,8 +1,10 @@
---
markup: occlusion
title: styles/shell
description: 暗恋见君壳样式——对照 Django 原站粉玻璃 + 动效,用表格声明。
导入 网页:ext/web/网页.mq.md
import text:lib/text.mq.md
导入:
网页: ext/web/网页.mq.md
text: lib/text.mq.md
---
对照原站 `config/static/front/css/{base,feed_common,footer,index/hero}.css`:
+4 -3
View File
@@ -2,9 +2,10 @@
markup: occlusion
title: browser-app (route E+)
description: list CRUD, storage, navigate, interval, fetch_all, ws — GFM + lib/browser
import browser:lib/browser.mq.md
import table:lib/table.mq.md
import text:lib/text.mq.md
import:
browser: lib/browser.mq.md
table: lib/table.mq.md
text: lib/text.mq.md
---
# main
+3 -1
View File
@@ -1,7 +1,9 @@
---
markup: occlusion
title: browser counter (C3)
description: wire table + browser.set_text — no json glue
import browser:lib/browser.mq.md
import:
browser: lib/browser.mq.md
---
# main
+3 -1
View File
@@ -1,7 +1,9 @@
---
markup: occlusion
title: browser fetch (C4)
description: fetch/after effects via lib/browser — no json glue
import browser:lib/browser.mq.md
import:
browser: lib/browser.mq.md
---
# main
+4 -2
View File
@@ -1,8 +1,10 @@
---
markup: occlusion
title: browser form (D3)
description: input wire passes value; effects via lib/browser
import browser:lib/browser.mq.md
import table:lib/table.mq.md
import:
browser: lib/browser.mq.md
table: lib/table.mq.md
---
# main
+118 -64
View File
@@ -197,6 +197,20 @@ export function eventArgsFromDom(ev, valueFromSel) {
args.fields = fields;
}
}
if (ev && (ev.type === "scroll" || ev.type === "resize")) {
try {
const doc = typeof document !== "undefined" ? document.documentElement : null;
const body = typeof document !== "undefined" ? document.body : null;
const scrollTop = (doc && (doc.scrollTop || 0)) || (body && body.scrollTop) || 0;
const height = doc ? (doc.scrollHeight - doc.clientHeight) || 1 : 1;
const ratio = Math.max(0, Math.min(1, scrollTop / height));
args.scroll_top = scrollTop;
args.scroll_max = height;
args.scroll_ratio = ratio;
} catch (_) {
/* ignore */
}
}
return args;
}
@@ -721,75 +735,88 @@ function runObserveEffect(exports, spec, onError) {
const kind = String(spec.kind || spec.type || "intersect").toLowerCase();
const sel = String(spec.sel || "");
const thenFn = spec.then;
const id = String(spec.id || `obs${++observeSeq}`);
const el = qsOne(sel);
if (!el || !thenFn) return;
const baseId = String(spec.id || `obs${++observeSeq}`);
const nodes = qsAll(sel);
if (!nodes.length || (!thenFn && !spec.add_class)) return;
const prev = observeHandles.get(id);
if (prev) {
try {
prev.disconnect();
} catch (_) {
/* ignore */
}
}
const fire = (payload) => {
try {
const result = call(exports, thenFn, payload);
if (!result.ok) {
if (onError) onError(result.error);
return;
nodes.forEach((el, idx) => {
const id = nodes.length === 1 ? baseId : `${baseId}_${idx}`;
const prev = observeHandles.get(id);
if (prev) {
try {
prev.disconnect();
} catch (_) {
/* ignore */
}
applyEffects(exports, result.value, { onError });
} catch (e) {
if (onError) onError(String(e));
}
};
if (kind === "resize" && typeof ResizeObserver !== "undefined") {
const ro = new ResizeObserver((entries) => {
const en = entries[0];
const cr = en?.contentRect;
fire({
ok: true,
kind: "resize",
id,
width: cr ? cr.width : 0,
height: cr ? cr.height : 0,
});
});
ro.observe(el);
observeHandles.set(id, ro);
return;
}
const fire = (payload) => {
try {
const result = call(exports, thenFn, payload);
if (!result.ok) {
if (onError) onError(result.error);
return;
}
applyEffects(exports, result.value, { onError });
} catch (e) {
if (onError) onError(String(e));
}
};
if (typeof IntersectionObserver !== "undefined") {
const io = new IntersectionObserver(
(entries) => {
if (kind === "resize" && typeof ResizeObserver !== "undefined") {
const ro = new ResizeObserver((entries) => {
const en = entries[0];
if (!en) return;
const cr = en?.contentRect;
fire({
ok: true,
kind: "intersect",
kind: "resize",
id,
intersecting: !!en.isIntersecting,
ratio: en.intersectionRatio,
width: cr ? cr.width : 0,
height: cr ? cr.height : 0,
});
if (spec.once && en.isIntersecting) {
try {
io.disconnect();
} catch (_) {
/* ignore */
});
ro.observe(el);
observeHandles.set(id, ro);
return;
}
if (typeof IntersectionObserver !== "undefined") {
const opts = { threshold: spec.threshold != null ? Number(spec.threshold) : 0.1 };
if (spec.rootMargin != null) opts.rootMargin = String(spec.rootMargin);
const io = new IntersectionObserver(
(entries) => {
const en = entries[0];
if (!en) return;
if (en.isIntersecting && spec.add_class) {
for (const c of String(spec.add_class).split(/\s+/).filter(Boolean)) {
el.classList.add(c);
}
}
observeHandles.delete(id);
}
},
{ threshold: spec.threshold != null ? Number(spec.threshold) : 0.1 },
);
io.observe(el);
observeHandles.set(id, io);
}
if (thenFn) {
fire({
ok: true,
kind: "intersect",
id,
intersecting: !!en.isIntersecting,
ratio: en.intersectionRatio,
target_id: el.id || "",
});
}
if (spec.once && en.isIntersecting) {
try {
io.disconnect();
} catch (_) {
/* ignore */
}
observeHandles.delete(id);
}
},
opts,
);
io.observe(el);
observeHandles.set(id, io);
}
});
}
function buildFetchInit(spec) {
@@ -921,8 +948,23 @@ function runIntervalEffect(exports, spec, onError) {
intervalHandles.set(id, handle);
}
const memoryKV = new Map();
function storageStore(scope) {
if (scope === "cookie") return null;
if (scope === "memory" || scope === "mem" || scope === "内存") {
return {
getItem(key) {
return memoryKV.has(key) ? memoryKV.get(key) : null;
},
setItem(key, value) {
memoryKV.set(key, String(value));
},
removeItem(key) {
memoryKV.delete(key);
},
};
}
if (typeof localStorage === "undefined") return null;
return scope === "session" ? sessionStorage : localStorage;
}
@@ -1371,12 +1413,24 @@ export async function autoMount(doc) {
const g = typeof globalThis !== "undefined" ? globalThis : undefined;
if (g && g.document) {
// Defer WASM boot until after first paint / load so LCP images are not
// contending with a ~1.6MB wasm download on the critical path.
const start = () => {
autoMount(g.document).catch((e) => console.error("marqdo autoMount:", e));
const run = () => {
autoMount(g.document).catch((e) => console.error("marqdo autoMount:", e));
};
const schedule = () => {
if (typeof g.requestIdleCallback === "function") {
g.requestIdleCallback(() => run(), { timeout: 1500 });
} else {
g.setTimeout(run, 0);
}
};
if (g.document.readyState === "complete") {
schedule();
} else {
g.addEventListener("load", schedule, { once: true });
}
};
if (g.document.readyState === "loading") {
g.document.addEventListener("DOMContentLoaded", start);
} else {
queueMicrotask(start);
}
start();
}
+4 -2
View File
@@ -1,8 +1,10 @@
---
markup: occlusion
title: browser-media (route F)
description: file / canvas / audio / observers / drag — GFM tables + lib/browser
import browser:lib/browser.mq.md
import table:lib/table.mq.md
import:
browser: lib/browser.mq.md
table: lib/table.mq.md
---
# main
@@ -1,4 +1,5 @@
---
markup: occlusion
title: resolve_config
capability: config.resolve
status: stable
@@ -1,4 +1,5 @@
---
markup: occlusion
title: Engineering Knowledge demo
description: Tiny project demonstrating Capability Catalog + reuse + decisions.
---
+44
View File
@@ -0,0 +1,44 @@
# 可执行知识系统示例:订单含税总额
这是 [可执行知识系统设计](../../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:原子知识 | `标准税率.查询` + `sources:` |
| `knowledge/negative-refund.mq.md` | 负知识 | 折扣不适用于退款 |
| `capabilities/order-pricing.mq.md` | D:推导知识 | 取元、调用、循环、汇总 |
| `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`
## 读法
`[]()` 的每一次出现都是命名步骤(observe / derive / iterate / call / narrate):
```markdown
[订单行金额](access(行, "金额")) # observe
[本行含税价](金额 * (1 + 税率)) # derive
[逐个订单行](遍历 行列表 为 行) # iterate
这张订单的含税总额是[含税总价](总额)。 # narrate
```
## 运行状态
| 子集 | 状态 | 证据 |
|---|---|---|
| 发票含税链双后端 `113` | **可运行** | 上表命令 / EK 门禁 |
| 来源 `sourced` + impact 下游 | **可运行** | knowledge 投影 + impact |
| 负知识文档 | **已收录** | `knowledge/negative-refund.mq.md`(发现层;非执行目标) |
@@ -0,0 +1,32 @@
---
markup: occlusion
id: capability.order-pricing
type: Capability
import:
tax: ../knowledge/tax-2026.mq.md
---
# 订单定价
按订单行取未税金额与品类,套用税率后汇总含税总额。
## 含税价
`行`
**金额 = [订单行金额](access(行, "金额"))**
**品类 = [订单行品类](access(行, "品类"))**
**税率 = > tax.标准税率.查询 品类=`品类`**
**结果 = [本行含税价](金额 * (1 + 税率))**
*结果*
## 含税总额
`订单`
**行列表 = [订单行列表](access(订单, "行"))**
`总额` = 0
- [逐个订单行](遍历 行列表 为 行)
**行含税价 = > 订单定价.含税价 行=`行`**
**总额 = [累加](总额 + 行含税价)**
*总额*
@@ -0,0 +1,5 @@
# 2026 年标准增值税率
本示例的原始证据:标准税率为 13%。
此文件只作来源定位,不执行。
@@ -0,0 +1,19 @@
---
markup: occlusion
id: document.invoice-answer
type: Answer
import:
pricing: ../capabilities/order-pricing.mq.md
json: lib/json.mq.md
---
# main
发票回答:演示订单一行图书,未税金额 100。
`订单` = > json.parse text={"行":[{"金额":100,"品类":"书"}]}
**总额 = > pricing.订单定价.含税总额 订单=`订单`**
这张订单的含税总额是[含税总价](总额)。
> print text=`总额`
@@ -0,0 +1,14 @@
---
markup: occlusion
id: knowledge.negative.discount-not-for-refund
type: Failure
title: 折扣不适用于退款
---
# 折扣不适用于退款
负知识:退款结算不得套用会员折扣。Agent 复用折扣能力时应拒绝该适用面。
## 说明
*[不适用](false)*
@@ -0,0 +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)*
@@ -0,0 +1,18 @@
---
markup: occlusion
id: schema.order
type: Schema
---
# 订单
| 字段 | 类型 | 说明 |
|---|---|---|
| 行 | list<订单行> | 待计价的订单行 |
## 订单行
| 字段 | 类型 | 说明 |
|---|---|---|
| 金额 | number | 未税金额 |
| 品类 | text | 用于选择税率 |
+91
View File
@@ -0,0 +1,91 @@
# 知识分层示例:本体 → 知识个体 → 调用面
这个目录演示 [知识分层设计](../../doc/design/knowledge-layers.md):
| 层 | 文件 | 内容 |
|----|------|------|
| **L0 原始语料** | `corpus/libai.md` | 李白原文;不执行,只作出处 |
| **L1 本体 / 模式** | `poet.mq.md` | `# 诗人` + 字段/类型表 |
| **L2 可执行知识** | `libai.mq.md` | `# 李白 = > 诗人` + `##` 事实 + 来源 |
| **L3 调用面** | `main.mq.md` / `main.compat.mq.md` | `[]()` 类调用 |
> **关键术语**:`# 李白 = > 诗人` 是**知识个体/单体知识类**(语法上是继承/特化),
> 不是运行时实例;`> 李白` 才是运行时 map 实例。
## 今天可跑(v2.0.0 兼容)
```bash
marqdo run examples/knowledge-layers/main.compat.mq.md
# 701
```
`main.compat.mq.md` 用当前能力完成同一件事:
```markdown
---
import libai:libai.mq.md
---
# main
**li = > libai.李白**
**year = > `li`.出生年份**
> print text=`year`
```
- `import` 绑定知识文档;
- `> libai.李白` 构造实例;
- `` `li`.出生年份 `` 调用实例方法;
- 当前 `libai.mq.md` 还保留 `import poet:poet.mq.md`,因为 v2.0.0 的跨文档继承需要 import;
v2.1 的项目类索引会去掉这个 import。
## 目标(v2.1)
`main.mq.md`:
```markdown
# main
诗人李白的出生年份是[出生年份](李白.出生年份)。
```
- `李白` 是项目类索引里的知识个体;
- `出生年份` 是它的类函数;
- 正文链接由 `view`/`check` 解析;`run` 不执行;
- 要终端输出,把同一段代码放进代码链接并加 `print`。
期望:
```bash
$ marqdo run examples/knowledge-layers/main.mq.md
# 无输出(正文链接不执行)
$ marqdo check examples/knowledge-layers/main.mq.md --json
{"code":"link.ok", ...}
```
`view` 期望显示:
```text
诗人李白的出生年份是 701。
↑
悬浮:出生年份 → 李白.出生年份
class 李白 · () -> number · value 701
来源:corpus/libai.md#出生年份
```
## 为什么 `# 李白 = > 诗人` 不是「实例化」
- `# 诗人` 是类/本体;
- `# 李白 = > 诗人` 是**继承/特化**,表达「李白是诗人」;
- 但它带有一个命名个体的全部事实,所以是**单体知识类**;
- `李白.出生年份` 是类调用,不需要 `> 李白` 构造实例;
- 如果要运行时实例,仍可 `**li = > 李白**`,它是 map + `_type`,和知识个体分离。
详见 [doc/design/knowledge-layers.md](../../doc/design/knowledge-layers.md)。
## 相关
- 链接语法:[doc/design/link-syntax.md](../../doc/design/link-syntax.md)
- 证据复核:[doc/research/occlusion-vs-executable-knowledge-2026-10.md](../../doc/research/occlusion-vs-executable-knowledge-2026-10.md)
- 旧遮蔽设计:[doc/design/occlusion-syntax.md](../../doc/design/occlusion-syntax.md)
@@ -0,0 +1,5 @@
# 李白
李白,字太白,唐代诗人,生于公元 701 年。
这段是**原始语料**:它不执行,只作为知识出处。
+22
View File
@@ -0,0 +1,22 @@
---
markup: occlusion
type: Fact
id: libai
title: 李白
import:
poet: poet.mq.md
---
# 李白 = > 诗人
## 姓名
*"李白"*
## 出生年份
| 返回 | 类型 | 说明 |
|------|------|------|
| 701 | number | 公元 701 年;来源:corpus/libai.md#出生年份 |
*701*
@@ -0,0 +1,11 @@
---
markup: occlusion
import:
libai: libai.mq.md
---
# main
**li = > libai.李白**
**year = > `li`.出生年份**
> print text=`year`
+7
View File
@@ -0,0 +1,7 @@
---
markup: occlusion
---
# main
诗人李白的出生年份是[出生年份](李白.出生年份)。
+10
View File
@@ -0,0 +1,10 @@
---
markup: occlusion
---
# 诗人
| 字段 | 类型 | 说明 |
|------|------|------|
| 姓名 | text | 诗人姓名 |
| 出生年份 | number | 公元年份 |
+6 -4
View File
@@ -1,8 +1,10 @@
---
markup: occlusion
title: Least squares via lstsq
description: Overdetermined Ax≈b with ext/linalg lstsq + heatmap.
import la:ext/linalg/linalg.mq.md
import math:lib/math.mq.md
import:
la: ext/linalg/linalg.mq.md
math: lib/math.mq.md
---
# Least squares from a runnable document
@@ -27,8 +29,8 @@ $$
**`_` = > la.draw factor=`A` kind="heatmap" theme="light" path="ls-heatmap.svg"**
**`ls` = > la.lstsq a=`A` b=`b`**
**`x` = [x](ls)**
**`resid` = [residual_fro](ls)**
**`x` = [x](access(ls, "x"))**
**`resid` = [residual_fro](access(ls, "residual_fro"))**
> print text=`x`
> print text=`resid`
+4 -2
View File
@@ -1,7 +1,9 @@
---
markup: occlusion
title: SVD structure demo
description: Diagonal SVD + structure SVG via ext/linalg.
import la:ext/linalg/linalg.mq.md
import:
la: ext/linalg/linalg.mq.md
---
# SVD from a runnable document
@@ -17,7 +19,7 @@ $$
**`M` = > la.from_formula formula=`M`**
**`f` = > la.factorize matrix=`M` kind="svd"**
**`S` = [S](f)**
**`S` = [S](access(f, "S"))**
**`_` = > la.draw factor=`f` kind="svd" theme="light" path="svd-structure.svg"**
**`hm` = > la.draw factor=`M` kind="hinton" path="svd-hinton.svg"**
Loaded 100 of 693 files, more files were not shown because too many files have changed in this diff. Show more