Compare commits

...
15 Commits
Author SHA1 Message Date
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
631 changed files with 11164 additions and 1472 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
+11 -11
View File
@@ -49,31 +49,30 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
| 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`) |
| Frontmatter nested `import:` / `导入:` map | Import file (`bind: path.mq.md`) or short name (`bind: lib.member`) |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
| `****` or `**` + spaces + `**` | Return `None` and end function body |
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
| `- [item](coll)` | Foreach (unchanged) |
| GFM table after empty RHS bind | Collection; get with `access(coll, "key")` (legacy `` `m`[^key] `` remains available) |
| `- [item](遍历 coll 为 item)` | Foreach |
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
| Unmarked prose | Comment |
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
## Occlusion syntax (v2.0.0)
## Occlusion syntax (v2.1.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).
Occlusion is the default syntax. Shipped source declares `markup: occlusion` (or `标记: 遮蔽`) explicitly so imports stay deterministic. Legacy `[key](collection)` requires `markup: classic` or the one-cycle CLI flag `--legacy-markup`; `MARQDO_MARKUP` does not change parsing.
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
- `[顾客留存率](0.42)` · `[总价](at(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
- `[顾客留存率](0.42)` · `[总价](access(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
- Read maps/lists with `access(集合, 键)` (aliases `取` / `取值`): `[第二项](access(列, 2))`.
- Foreach: `- [篮子里的每个果子](遍历 篮子 为 果)` (accepts `遍历`/`for` and `为`/`as`/`in`).
- Calls inside `()`: `加(1)` / `加(1, 2)` / `加一 号(31)` / `txt.str_trim(" x ")` — `)` terminates, commas optional.
- 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`.
- Tooling: `marqdo labels pending` (stub ledger) · `marqdo labels --grep 词 --count` · `marqdo migrate labels . --mark --write` · `marqdo check` reports `label.missing` / `label.empty_payload` / `label.ref_dangling`.
## Minimal program
@@ -136,13 +135,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
+3 -3
View File
@@ -126,9 +126,9 @@ 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.0**:文件级 Occlusion 默认语义——全仓迁移 · `migrate labels --mark` · `access` / `遍历` · 可执行知识语义投影
- **v2.1.0**: File-scoped Occlusion by default — corpus migration, `migrate labels --mark`, `access` / `for`, executable-knowledge projections
- **v2.1.0 ext**:扩展包同步 2.1.0 / Ext pack 2.1.0
- **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
+21 -1
View File
@@ -41,14 +41,34 @@ 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 行构成。
## Unreleased
## 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
## 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.0"
dependencies = [
"anyhow",
"assert_cmd",
@@ -610,7 +610,7 @@ dependencies = [
[[package]]
name = "marqdo-wasm"
version = "2.0.0"
version = "2.1.0"
dependencies = [
"marqdo",
"serde_json",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "2.0.0"
version = "2.1.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
+108 -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,9 @@ marqdo catalog public -o .marqdo
---
## 现状(v2.0.0)
## 现状(v2.1.0)
- **遮蔽语法(v2.0.0)**:`[描述](实现)` 描述不执行 · `()` 内调用(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 遮蔽循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels` · 诊断 `label.missing` / `empty_payload` / `ref_dangling` · view 描述正文 + 代码片 + 桩徽章 · 扩展包同步 **2.0.0**
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock) · 扩展包同步 **2.1.0**
- **外联 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 +319,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.0)
**安装解释器(任选其一)**
@@ -246,7 +334,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.0 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -285,7 +373,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.0
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+2 -2
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "2.0.0"
version = "2.1.0"
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"
+7
View File
@@ -1,3 +1,10 @@
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
+8
View File
@@ -13,6 +13,8 @@
## 当前文档
> **可执行知识下一阶段的规范优先级**:实现 `[]()`、Semantic Artifact、知识绑定、验证、锁定、EKC/Agent 复用时,以 [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) 为实施基线。与其冲突的早期链接、遮蔽、知识分层或 EKC 设计只作历史参考。
| 文档 | 摘要 |
|------|------|
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
@@ -106,6 +108,11 @@
| [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 的仓库级门禁 |
| [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 +121,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/)。
+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
---
```
+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
+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` |
+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
+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 统一命名空间)。
+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
---
```
+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
+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.
---
+35
View File
@@ -0,0 +1,35 @@
# 可执行知识系统示例:订单含税总额
这是 [可执行知识系统设计](../../doc/design/executable-knowledge-system.md) 的目标示例。
它刻意展示 `[]()` 不只包“知识函数”:同一套语法同时命名取元、循环、推导、跨文件调用和正文结论。
| 文件 | 图中的职责 | 关键步骤 |
|---|---|---|
| `corpus/tax-policy-2026.md` | E:证据 | 税率原文 |
| `schema/order.mq.md` | C:概念 | 订单/订单行字段与单位 |
| `knowledge/tax-2026.mq.md` | K:原子知识 | `[标准税率](0.13)` 及来源 |
| `capabilities/order-pricing.mq.md` | D:推导知识 | 取元、调用、循环、汇总 |
| `docs/invoice-answer.mq.md` | N:叙述知识 | 用同一个计算给人可读的回答 |
## 读法
`[]()` 的每一次出现都是 `Named<T>`:
```markdown
[订单行金额](at(行, "金额")) # observe
[本行含税价](订单行金额 * (1 + 税率)) # derive
[逐个订单行](遍历 订单.行 为 行) # iterate
[含税总价](pricing.订单定价.含税总额(订单)) # reuse / narrate
```
它们不是四种语法。`()` 中仍是原有的取元、算术、循环和调用;`[]` 让每一步同时可读、可查、
可在图中定位。当前实现尚不能完整运行该目标形式(类函数、统一 `Named<T>`、步骤图仍是设计目标),
但它给出了实际项目中应当写成什么样子。
## 预期闭环
1. `check` 从每个 `[]()` 提取观测、推导、遍历和调用依赖;
2. `view` 在“含税总额”旁显示所经过的订单行、标准税率和税率原文;
3. 税率原文变更时,`impact` 找到原子税率、订单定价、发票回答中的每一个命名步骤;
4. `verify` 只重算 pure 步骤,不执行写入或发送等 `act` 步骤;
5. agent 通过 catalog 得到“已有订单定价能力”和其证据链,不必从自然语言猜测。
@@ -0,0 +1,27 @@
---
id: capability.order-pricing
type: Capability
import:
tax: ../knowledge/tax-2026.mq.md
order: ../schema/order.mq.md
---
# 订单定价
## 含税价
+ `行`
**金额 = [订单行金额](at(行, "金额"))**
**品类 = [订单行品类](at(行, "品类"))**
**税率 = [适用税率](tax.标准税率.查询(品类))**
**结果 = [本行含税价](金额 * (1 + 税率))**
**结果**
## 含税总额
+ `订单`
- [逐个订单行](遍历 订单.行 为 行)
**行含税价 = [计算本行含税价](订单定价.含税价(行))**
**总额 = [汇总全部行含税价](sum(行含税价))**
**总额**
@@ -0,0 +1,5 @@
# 2026 年标准增值税率
本示例的原始证据:标准税率为 13%。
此文件只作来源定位,不执行。
@@ -0,0 +1,15 @@
---
markup: occlusion
id: document.invoice-answer
type: Answer
import:
pricing: ../capabilities/order-pricing.mq.md
---
# 发票回答
**总额 = [订单的含税总价](access(pricing.订单定价.含税总额(订单), "订单的含税总价"))**
这张订单的含税总额是[含税总价](总额)。
> view 应可展开:含税总价 → 汇总全部行含税价 → 逐个订单行 → 本行含税价 → 适用税率 → 税率原文。
@@ -0,0 +1,18 @@
---
id: knowledge.tax.standard-2026
type: Fact
sources:
- ../corpus/tax-policy-2026.md#2026 年标准增值税率
---
# 标准税率
## 查询
+ `品类`
| 返回 | 类型 | 来源 |
|---|---|---|
| 0.13 | number | corpus/tax-policy-2026.md#2026 年标准增值税率 |
**税率 = [标准税率](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"**
+5 -3
View File
@@ -1,7 +1,9 @@
---
markup: occlusion
title: Transpose identity (formula document)
description: (AB)^T = B^T A^T as a runnable lecture fragment.
import la:ext/linalg/linalg.mq.md
import:
la: ext/linalg/linalg.mq.md
---
# Transpose reverses products
@@ -18,8 +20,8 @@ Declare shapes in a table, form \(P = AB\), then check \((AB)^\top = B^\top A^\t
| 2 | B | 3 | 2 |
**`env` = > la.declare table=`shapes`**
**`A` = [A](env)**
**`B` = [B](env)**
**`A` = [A](access(env, "A"))**
**`B` = [B](access(env, "B"))**
**`P` = `A` * `B`**
**`t` = > `P`.T_ascii**
> print text=`t`
+109
View File
@@ -0,0 +1,109 @@
# 链接语法示例:两文档,一次类调用
这个目录是 [链接语法设计声明](../../doc/design/link-syntax.md) 的**目标示例**:
> `[李白的出生年份](李白.李白的出生年份)`
> 不是新的语法:`[]` 是 Markdown 链接的描述,`()` 是已有调用;
> `# 李白` 是类,`## 李白的出生年份` 是函数,`李白.李白的出生年份` 是类调用。
## 文件
| 文件 | 作用 | v2.0.0 可跑 | v2.1 目标 |
|------|------|-------------|-----------|
| `libai.mq.md` | 知识文档:`# 李白` → `## 李白的出生年份` → `*701*` | ✅ | ✅ |
| `main.mq.md` | 用户原始示例:正文链接 + 类调用 | ❌(安静无输出) | ✅ view 显示;`run` 加 print 输出 |
| `main.compat.mq.md` | 当前等价写法:`import` + 实例 + 本地链接 | ✅(输出 `701`) | ✅ |
| `expected-link-info.json` | 目标 `LinkInfo` 形状 | — | — |
| `links.lock.yaml` | 可选锁文件形状 | — | — |
> **v2.0.0 的 `main.mq.md` 不会报错,也不会有输出**——因为:
> 1. 正文链接默认不执行(叙述默认安全);
> 2. `李白.李白的出生年份` 目前被当成变量/实例方法路径,类调用还没实现。
>
> v2.1 的目标是:`view` 显示这个链接的目标、类、函数、签名、值;`check` 返回 LinkInfo;
> 要终端输出,就在代码链接里加 `print`。
## 今天可跑
```bash
marqdo run examples/link-syntax/main.compat.mq.md
# 701
```
`main.compat.mq.md` 用当前能力完成了同一件事:
```markdown
---
markup: occlusion
import libai:libai.mq.md
---
# main
**li = > libai.李白**
**year = [李白的出生年份](li.李白的出生年份())**
> print text=`year`
```
- `import` 绑定知识文档;
- `> libai.李白` 构造对象(当前 `#` 是对象/类型);
- `li.李白的出生年份()` 调用实例方法;
- `[]()` 把调用包成一句人话。
这正是 v2.0.0 的「实例方法」路径;v2.1 要把 `##` 恢复为**类函数**,
让 `李白.李白的出生年份` 直接调用,去掉 `import`/实例两步。
## 目标形式
`main.mq.md`:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
v2.1 期望:
```bash
$ marqdo run examples/link-syntax/main.mq.md
# 无输出(正文链接不执行;加 print 才有输出)
$ marqdo check examples/link-syntax/main.mq.md --json
{"code":"link.ok", ...}
```
`view` 期望:
```text
用户想要知道李白的出生年份,我们要告诉用户 701。
↑
悬浮:李白的出生年份 → 李白.李白的出生年份
class 李白 · function · () -> number · value 701
```
要终端输出:
```markdown
# main
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
```bash
$ marqdo run examples/link-syntax/main.mq.md
701
```
## 为什么是 `李白.李白的出生年份`
- `# 李白` 是类;
- `## 李白的出生年份` 是类下的函数;
- `李白.李白的出生年份` 是**类调用**;
- `[]` 是描述,`()` 是已有调用;没有新语法,没有协议前缀,没有别名开关。
## 相关
- 设计声明:[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,22 @@
{
"label": "李白的出生年份",
"source": {
"file": "main.mq.md",
"line": 2,
"col": 26
},
"target": {
"class": "李白",
"function": "李白的出生年份",
"doc": "libai.mq.md",
"kind": "class_function",
"signature": {
"params": [],
"returns": "number"
},
"instance_only": false
},
"status": "ok",
"value": null,
"fingerprint": "sha256:<target-body-hash>"
}
+22
View File
@@ -0,0 +1,22 @@
---
markup: occlusion
type: Fact
id: libai
title: 李白
description: 李白知识文档:一个可被其他文档链接调用的知识单元
status: stable
---
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
李白的出生年份是公元 701 年。
| 返回 | 类型 | 说明 |
|------|------|------|
| 701 | number | 公元 701 年 |
*701*
+9
View File
@@ -0,0 +1,9 @@
version: 1
generated_by: marqdo/2.1.0
links:
- from: main.mq.md
label: 李白的出生年份
to: libai.mq.md::李白.李白的出生年份
kind: class_function
signature: "() -> number"
fingerprint: sha256:<target-body-hash>
+11
View File
@@ -0,0 +1,11 @@
---
markup: occlusion
import:
libai: libai.mq.md
---
# main
**li = > libai.李白**
**year = [李白的出生年份](li.李白的出生年份())**
> print text=`year`
+6
View File
@@ -0,0 +1,6 @@
---
markup: occlusion
---
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
+1
View File
@@ -1,4 +1,5 @@
---
markup: occlusion
type: endpoint
method: POST
path: /api/echo
+1
View File
@@ -1,4 +1,5 @@
---
markup: occlusion
type: endpoint
method: GET
path: /api/ping
@@ -1,3 +1,7 @@
---
markup: occlusion
---
## 页脚
站点页脚。放版权与概览链接。
@@ -1,3 +1,7 @@
---
markup: occlusion
---
## 导航
站点顶部导航。首项是站点名(渐变 Logo 由主题 CSS 处理),`后台` 指向需要登录的 `/admin`。
@@ -1,3 +1,7 @@
---
markup: occlusion
---
## 侧栏
右侧归档面板:文章入口、标签、实时小部件。
+3 -1
View File
@@ -1,6 +1,8 @@
---
markup: occlusion
title: blog posts schema
import data:ext/data/db.mq.md
import:
data: ext/data/db.mq.md
---
## schema
+4
View File
@@ -1,3 +1,7 @@
---
markup: occlusion
---
## posts
文章主表结构。`slug` 用于详情页 `/post/{slug}` 的动态路由;`content` 存 Markdown 正文;`tag` 是主标签(tags 表 slug)。
+4
View File
@@ -1,3 +1,7 @@
---
markup: occlusion
---
## posts
种子文章。首页与详情页的初始数据。created_at 用于按时间倒序展示;tag 是主标签 slug。
+3 -1
View File
@@ -1,4 +1,5 @@
---
markup: occlusion
type: web
title: Marqdo 博客
route: /
@@ -7,7 +8,8 @@ data_source: posts
data_order: -created_at
description: >-
Document Artifact 首页(ADR 0007):正文即文档,列表来自 data_source。
导入 网页:ext/web/网页.mq.md
导入:
网页: ext/web/网页.mq.md
---
# Marqdo 博客
+1
View File
@@ -1,4 +1,5 @@
---
markup: occlusion
类型: 网页
路由: /about
方法: GET
Loaded 100 of 631 files, more files were not shown because too many files have changed in this diff. Show more