Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
aa0c4d0f55 | ||
|
|
c50c515c4a | ||
|
|
16c44588d5 | ||
|
|
5080136d65 | ||
|
|
cc5277d2b5 | ||
|
|
bb06dad134 | ||
|
|
24dcb97354 | ||
|
|
76aa02846a | ||
|
|
0e389f34ec | ||
|
|
492790e985 | ||
|
|
ca434a8bab | ||
|
|
6195ad1d5d | ||
|
|
a87c2154ff | ||
|
|
8f1010f967 | ||
|
|
e3d9021bb6 | ||
|
|
142ab523d6 | ||
|
|
82c8d78fd3 | ||
|
|
58791fc7d9 | ||
|
|
1730f26fc7 | ||
|
|
4018e9928a | ||
|
|
628e3b6e5d | ||
|
|
5c6c612edd | ||
|
|
41587f319e | ||
|
|
298fbd51ea | ||
|
|
265dfdbcc4 | ||
|
|
42a43f5ffd | ||
|
|
037a963547 | ||
|
|
a32638e935 | ||
|
|
43eebe5671 | ||
|
|
e833dc05e2 | ||
|
|
11bb7ef277 | ||
|
|
6bd90bb2d0 | ||
|
|
4683f2e067 | ||
|
|
5912164039 | ||
|
|
303c06f773 | ||
|
|
a1086fd6c3 | ||
|
|
6ffe5ceb19 | ||
|
|
6b568aff3d | ||
|
|
16f26d7d60 | ||
|
|
b8265a92aa | ||
|
|
9af929971c | ||
|
|
2c4fa4bb05 | ||
|
|
3cabe53da2 | ||
|
|
58e13ee6d3 | ||
|
|
1b11fe063a | ||
|
|
b792f44556 | ||
|
|
9ea5bebfc3 | ||
|
|
c7c329341b | ||
|
|
8cf5288481 | ||
|
|
69c4e74872 | ||
|
|
af0bda2e40 | ||
|
|
090b026547 | ||
|
|
03396afd02 | ||
|
|
663a8ba2c0 | ||
|
|
dc853fb580 | ||
|
|
0b80ff8e50 | ||
|
|
b8a4ddd38f | ||
|
|
352bc0d2c5 | ||
|
|
8a6d09d582 | ||
|
|
dcd3d329d4 | ||
|
|
0e1bfb3359 | ||
|
|
e9ae7ff1ae | ||
|
|
ecbdd18303 | ||
|
|
bedd53e212 | ||
|
|
7674ebb869 | ||
|
|
434be9fd52 | ||
|
|
ae97891266 | ||
|
|
aea86746e7 | ||
|
|
c773503938 | ||
|
|
939e23ee88 | ||
|
|
687c168014 | ||
|
|
eac9b45263 | ||
|
|
74b298e80d | ||
|
|
fc7097bae4 | ||
|
|
b624084745 | ||
|
|
0bbe735c3c | ||
|
|
92de46aca4 | ||
|
|
8bbe017a5e | ||
|
|
1a13989230 | ||
|
|
5ad1a07f5c | ||
|
|
bcfc763ba4 |
No files matched your search
@@ -140,15 +140,17 @@ Matching surrounding **legacy** `json.set` in `ext/ai/*.mq.md` is **not** compli
|
||||
3. `##` handlers: short prose OK; data as tables; return via `browser.*` / `web.*` / one `table.put`.
|
||||
4. Blank line between comment paragraphs and code.
|
||||
5. Run `marqdo run path.mq.md` from repo root.
|
||||
6. **Calls in narrative:** prefer `**结果 = 某函数 名=`x`**` (no `>` on the RHS). Bracket form `礼貌 [问候] "x"` / `**出 = [put] …**` is fine when modifiers help. Use `> …` for standalone step lists. See `examples/code-as-docs/`.
|
||||
6. **Calls in narrative:** explain the action in its sentence, for example `` 读取之后得到**结果 = [读取文件](文件.读文本(路径=`路径`))**。 `` Return in the sentence with `` 完成后返回*结果*。 `` Keep real control structures and data tables separate when that improves reading. The label describes intent; the payload contains the actual call. See the executable library development guide.
|
||||
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
|
||||
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
|
||||
8. **Index:** use `access(collection, key)` (or `取`); `[描述](payload)` is executable occlusion, never an index by label.
|
||||
|
||||
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/*`)
|
||||
|
||||
Canonical thin-template + waves: [lib-code-as-docs.md](../../doc/design/lib-code-as-docs.md) · [roadmap/lib-ext-code-as-docs.md](../../doc/roadmap/lib-ext-code-as-docs.md).
|
||||
Start with the [executable library development guide](../../../doc/library-development.mq.md): parameter/return tables below headings, prose >50%, inline assignments/returns and occlusion labels. Single-file stdlib needs no index; multi-file extensions organize through index.mq.md.
|
||||
|
||||
Design background + waves: [lib-code-as-docs.md](../../doc/design/lib-code-as-docs.md) · [roadmap/lib-ext-code-as-docs.md](../../doc/roadmap/lib-ext-code-as-docs.md).
|
||||
|
||||
### Goals
|
||||
|
||||
@@ -156,14 +158,20 @@ Canonical thin-template + waves: [lib-code-as-docs.md](../../doc/design/lib-code
|
||||
- One concern per helper; name the effect (`set_text`, `canvas`, …), do not expose bag surgery.
|
||||
- EN + ZH pair when shipping user-facing libs (`lib/browser.mq.md` ↔ `lib/浏览器.mq.md`, `ext/web` ↔ `ext/web/网页.mq.md`).
|
||||
- `ext/**` never calls `host_*` — use plugins / public lib only (`doc/design/ext-agent.md`).
|
||||
- Collection get: **`[key](coll)`** (no new footnote indexes). Calls in examples may use `修饰 [fn] …` or classic `>` / bold.
|
||||
- Collection get: **`access(coll, key)`**; bracket labels are inert descriptions. Calls in examples may use `修饰 [fn] …` or classic `>` / bold.
|
||||
|
||||
### Library checklist
|
||||
|
||||
- [ ] Purpose sentence + prose params + one example + short body
|
||||
- [ ] Single-file stdlib is its own handbook; no forced index/module guide directory
|
||||
- [ ] Parameter/type/default table directly below the function heading, then return contract
|
||||
- [ ] Prose parameters; remove legacy `+` declarations in standard library sources
|
||||
- [ ] Explain purpose, real input shape, output, failure and limits; narrative >50% per function
|
||||
- [ ] Put assignments, occlusion calls and returns in explanatory sentences where natural; reserve separate blocks for real structure
|
||||
- [ ] Use `[action](actual code)` inside return/statement markers for opaque host calls
|
||||
- [ ] One actual example + short implementation; never pad prose to satisfy the ratio
|
||||
- [ ] Public examples use **tables + helpers**, not json glue
|
||||
- [ ] Index with `[k](c)`; foreach `- [item](coll)`
|
||||
- [ ] Helpers documented with a one-line purpose above `##`
|
||||
- [ ] Read with `access(c, k)`; foreach `- [description](遍历 coll 为 item)`
|
||||
- [ ] Function heading names the tool; tables and task explanation follow it
|
||||
- [ ] Defaults on params; omit `None` fields in merged maps
|
||||
- [ ] No `json.set` chains in new code — use `table.put` / `table.merge` / GFM
|
||||
- [ ] `marqdo run` on a tiny demo under `examples/` or inline smoke
|
||||
@@ -186,7 +194,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
|
||||
|
||||
|
||||
@@ -28,6 +28,7 @@ Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagg
|
||||
9. **Extension packs always publish to both** Cloudflare R2 (`https://ext.marqdo.com` via `scripts/upload-ext-r2.py`) **and** GitHub (Release assets / `ext-v*` tag). Credentials only in `~/.marqdo/r2.env` / CI — **never** commit. See [ext-cdn.md](../../../doc/design/ext-cdn.md).
|
||||
10. **CLI Ubuntu package = PPA** (`ppa:cflmy/marqdo`) via `./scripts/ppa-ship.sh` / `ppa-build-source.sh`. GitHub zips remain for Windows and non-apt Linux.
|
||||
11. **When a step needs the user** (sudo password, GPG passphrase, Launchpad UI, interactive `dput`): **stop, state what failed, and give the exact commands** to run in their terminal. Do not pretend the step succeeded.
|
||||
12. **GitHub auto-build must be green before declaring a release done.** For full/cli: wait for the tag-triggered **Release** workflow (`windows` + `linux`) **and** the push-triggered **`executable-knowledge`** workflow on the release commit / `main` tip. Release asset zips alone are **not** sufficient — a green Release job with a red EK gate is an incomplete release. Do not skip or reframe a red `executable-knowledge` as “assets already uploaded.”
|
||||
|
||||
## Release modes
|
||||
|
||||
@@ -78,6 +79,7 @@ Release progress:
|
||||
```
|
||||
|
||||
Checks: clean tree; `main` ff-only; smoke tests; CHANGELOG Unreleased; no secrets.
|
||||
Also confirm the latest `main` **`executable-knowledge`** Actions run is green (or that this release commit will be covered after push) — do not proceed to tag if EK is already red on tip without a fix in the same release PR.
|
||||
|
||||
## Phase 2 — Docs & version bumps (main)
|
||||
|
||||
@@ -129,7 +131,9 @@ git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER
|
||||
|
||||
## Phase 5 — GitHub Release notes & assets
|
||||
|
||||
1. Wait for Actions (full/cli): both `windows` and `linux` green when ext natives required.
|
||||
1. Wait for Actions (full/cli):
|
||||
- Tag **Release** workflow: both `windows` and `linux` green when ext natives required.
|
||||
- Push **`executable-knowledge`** workflow on the release commit / `main`: **must be success**. Poll with `gh run list --workflow=executable-knowledge.yml --branch main` / `gh run watch`. If EK is red → **stop**; fix plugin/harness on `main`, re-run; do **not** declare the release complete from assets alone.
|
||||
2. Rewrite release body 中英双语 — [reference.md § Notes](reference.md).
|
||||
3. Confirm Linux `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` when mode ships ext.
|
||||
|
||||
@@ -174,10 +178,11 @@ On Launchpad failure: read the build log, fix `debian/` or bundle script, bump `
|
||||
## Phase 8 — Post-release
|
||||
|
||||
1. `gh release view TAG` — assets + notes.
|
||||
2. CDN `https://ext.marqdo.com/vVER/` (if ext shipped).
|
||||
3. PPA build green (if cli shipped).
|
||||
4. Tell user URLs: GitHub release, CDN, PPA install one-liner.
|
||||
5. Optional gh-pages only if asked.
|
||||
2. Confirm **`executable-knowledge`** and **Release** Actions are both green for this tag/commit; if either is red, say so and do not claim “发版完成”.
|
||||
3. CDN `https://ext.marqdo.com/vVER/` (if ext shipped).
|
||||
4. PPA build green (if cli shipped).
|
||||
5. Tell user URLs: GitHub release, CDN, PPA install one-liner.
|
||||
6. Optional gh-pages only if asked.
|
||||
|
||||
## Extension-only release (mode=ext)
|
||||
|
||||
@@ -194,7 +199,8 @@ On Launchpad failure: read the build log, fix `debian/` or bundle script, bump `
|
||||
| `gh` / git TLS or Clash `7890` refused | Unset bad proxy; see [reference § Proxy](reference.md) |
|
||||
| GitHub blocked | proxy.cflmy.top, then HK jump; **print commands** if agent cannot push |
|
||||
| Tag exists | Stop; ask user |
|
||||
| CI red | Fix on main; retag only if user allows |
|
||||
| CI red (Release assets) | Fix on main; retag only if user allows |
|
||||
| `executable-knowledge` red | Fix agent plugin / test harness (e.g. `ensure_agent_plugin_built`); push `main`; wait for EK green. **Do not** treat uploaded Release zips as a successful release |
|
||||
| R2 upload fails | Print `upload-ext-r2.py` command; do not skip silently |
|
||||
| PPA / sudo / GPG | Print `./scripts/ppa-ship.sh noble` (or `dput …`); do not skip silently |
|
||||
| Launchpad `Cargo.lock` v4 / old cargo | Ensure bundled `third_party/rust` via current `ppa-build-source.sh`; bump `1ppaN` |
|
||||
|
||||
@@ -304,6 +304,15 @@ gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else f
|
||||
|
||||
Current Release workflow is **tag-push only**. Red CI after tag → fix on `main`, then either new patch tag or **user-approved** delete+recreate tag (dangerous; prefer patch).
|
||||
|
||||
**Also required before declaring release done:** the push-triggered **`executable-knowledge`** workflow on the release commit / `main` tip must be **success**. Poll with:
|
||||
|
||||
```bash
|
||||
gh run list --workflow=executable-knowledge.yml --branch main --limit 5
|
||||
gh run watch <run-id>
|
||||
```
|
||||
|
||||
A green Release asset job with a red `executable-knowledge` gate is an **incomplete** release — fix the plugin/harness (e.g. `ensure_agent_plugin_built` for agent-dependent EK tests), push `main`, and wait for EK green. Do not skip.
|
||||
|
||||
### HK SSH jump (Paramiko CONNECT)
|
||||
|
||||
**When to use:** local → GitHub fails (timeout / TLS / Clash flaky / reverse-proxy `proxy.cflmy.top` connect drops), but this host can reach an overseas box that has stable GitHub (default `hk.cflmy.de`). Proven path for v0.3.9 push/tag/`gh`.
|
||||
|
||||
@@ -7,73 +7,73 @@ description: >-
|
||||
importing lib/* or ext/web or ext/quantum, running marqdo CLI, building dynamic
|
||||
sites with ext/web, quantum circuits with ext/quantum, or when the user
|
||||
mentions Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, or
|
||||
quantum/量子 extension.
|
||||
quantum/量子 extension (ZH under ext/quantum/量子/).
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
|
||||
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
|
||||
|
||||
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
<!-- CORE_SYNTAX_V2.1: must stay at the top so skill_brief budgets never truncate it -->
|
||||
|
||||
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
|
||||
## CORE SYNTAX (v2.1 Occlusion — mandatory)
|
||||
|
||||
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
|
||||
These rules are the **current default**. Do **not** teach Classic `[key](map)` index or “bold is return of print”. Classic migration only: [migration-classic.md](migration-classic.md).
|
||||
|
||||
1. **File suffix** `.mq.md`. Print with `> print text=…` / `> 打印 内容=…` — never use `**…**` to print.
|
||||
2. **`**…**` = statement** (assign / call / expression). `*…*` = return. Closing markers touch the last token (no trailing space).
|
||||
3. **`[描述](payload)` = occlusion:** `[]` is prose (never executed); `()` is the only executed part. Empty `()` → `None` stub.
|
||||
4. **Read collections with `access(coll, key)`** (aliases `取` / `取值`). **Never** use `[key](map)` as index under default Occlusion.
|
||||
5. **Foreach:** `- [描述](遍历 coll 为 item)` (`遍历`/`for`, `为`/`as`/`in`). Prefer explicit traversal when generating new code.
|
||||
6. **Import / call:** frontmatter `import:` / `导入:`; call `lib.member`. One language (EN or ZH) per file.
|
||||
7. **Control flow:** `#` object/type, `##`+ function, prose params (legacy `+` remains parseable), `1.`/`2.` branches, `-` loops, `N. *` else. No invented `if`/`for`/`def`/`return` keywords.
|
||||
8. **Prose vs code:** blank line separates comment paragraphs from executable lines.
|
||||
9. **GFM tables** for data; prefer `table.put` over `json.set` chains. `ext/**` never calls `host_*`.
|
||||
10. Body narrative `[描述](target)` is lazy (NarrativeRef) — reading does not execute side effects.
|
||||
|
||||
| Marker | Meaning (v2.1) |
|
||||
|--------|----------------|
|
||||
| `#` / `##`+ | Object/type · function/method |
|
||||
| `**…**` | Statement (assign / call / expression) |
|
||||
| `*…*` | Return |
|
||||
| `[描述](payload)` | Occlusion step (payload executes) |
|
||||
| `access(c, k)` | Collection read |
|
||||
| `> fn …` | Call |
|
||||
| GFM table | Collection literal |
|
||||
|
||||
Canonical: `doc/design/core-surface.md`, `doc/design/document-native-development-guide.md`. Deeper tables: [reference.md](reference.md). Patterns: [examples.md](examples.md). Authoring craft: [marqdo-dev](../marqdo-dev/SKILL.md). Release: [marqdo-release](../marqdo-release/SKILL.md).
|
||||
|
||||
Executable-knowledge gate: [`tests/executable_knowledge/`](../../tests/executable_knowledge/README.md).
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
|
||||
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
|
||||
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
|
||||
8. Prefer ending side-effect-only function bodies with `*None*` / `*无*` / whole-line `**` / `****` when later lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped), not function end.
|
||||
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
|
||||
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. Read collections with **`[key](map)`**, not footnote indexes for new code. In `markup: occlusion` files read with **`access(map, key)`** — there `[x](y)` is occlusion, not index. **Positive copy-paste shapes** (result map, soft-error pack, sparse `table.put`): [marqdo-dev](../marqdo-dev/SKILL.md) §2 · [examples.md](examples.md) §6e. Do **not** extend legacy `json.set` in `ext/ai` — refactor to tables.
|
||||
12. **One language per file:** Do not mix EN and ZH API names in the same `.mq.md` (imports, calls, params). Pick English *or* Chinese mirrors for the whole program.
|
||||
13. **Sandbox trial habit (Agent / generated `.mq.md`):** Prefer `agent.trial` / `run sandbox=True` / `sandbox.open`→`run`→`diff`→`commit` before promoting to the host tree. Host files must stay unchanged until a successful commit. Caps live in `sandbox.profile` GFM tables — do not invent a second dialect.
|
||||
1. Obey **CORE SYNTAX** above — Occlusion is default; do not emit Classic index links.
|
||||
2. **Identifiers:** declare library parameters in prose as `` input `name` `` (defaults follow `=`); inside `*…*` / `**…**` bare ids are variables. Quote text literals. Standalone `>` calls: backticks where bare would be text.
|
||||
3. **Structure lines** (`#` `>` `+` `-` `|`) are not wrapped in italics.
|
||||
4. **Paths:** bare `/` in expressions is division; in call args / table cells unspaced `a/b` is path text. Ratios as text need quotes (`"1/5"`).
|
||||
5. End side-effect-only helpers with `*None*` / `*空*` / `**` / `****` when the outer function continues. Lone `---` is a thematic break, not function end.
|
||||
6. **`ext/**` never calls `host_*`.** Prefer tables over `json.set` / `json.append`.
|
||||
7. **One language per file.** Sandbox trial before promoting Agent-generated trees.
|
||||
8. Browser: Marqdo on WASM + `lib/browser` tables; do not hand-write business JS.
|
||||
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
## Call one function
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
|
||||
| `##` … `######` | **Function / method** (nesting by heading depth). |
|
||||
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
|
||||
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
|
||||
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
|
||||
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
|
||||
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
|
||||
| `- [item](coll)` | Foreach (unchanged) |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
|
||||
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
|
||||
| Unmarked prose | Comment |
|
||||
```markdown
|
||||
# 计算器
|
||||
|
||||
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
|
||||
## 加法
|
||||
|
||||
## Occlusion syntax (v2.0.0)
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
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).
|
||||
*[计算结果](a + b)*
|
||||
```
|
||||
|
||||
- `[描述](实现)` — `[]` is prose (never executed); `()` is the **only** executed part.
|
||||
- `[顾客留存率](0.42)` · `[总价](at(价目表, "苹果") * 数量)` · `[功能开发中]()` → `None` (stub; `label.empty_payload` warning).
|
||||
- Read maps/lists with `access(集合, 键)` (aliases `取` / `取值`): `[第二项](access(列, 2))`.
|
||||
- Foreach: `- [篮子里的每个果子](遍历 篮子 为 果)` (accepts `遍历`/`for` and `为`/`as`/`in`).
|
||||
- Calls inside `()`: `加(1)` / `加(1, 2)` / `加一 号(31)` / `txt.str_trim(" x ")` — `)` terminates, commas optional.
|
||||
- Tooling: `marqdo labels pending` (stub ledger) · `marqdo labels --grep 词 --count` · `marqdo migrate labels . --write` · `marqdo check` reports `label.missing` / `label.empty_payload` / `label.ref_dangling`.
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
prints `5`. The same command works on any `.mq.md`; the file does not need a special skill name.
|
||||
|
||||
## Minimal program
|
||||
|
||||
@@ -114,13 +114,13 @@ Chinese builtins (same functions, no import):
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
**x = 1**
|
||||
**y = x + 2**
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
```markdown
|
||||
@@ -136,20 +136,24 @@ 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:
|
||||
A standard library is normally one `lib/*.mq.md` file: read/import/call that file directly. It is its own manual and skill; no `index.mq.md` or module handbook directory is required. Each function puts parameter/default and return tables directly below its heading, explains purpose, failures and limits, and keeps narrative above 50%. Use prose parameters, not legacy `+` declarations. Describe opaque instructions with `[what it does](actual code)` inside statement/return markers; labels do not execute. Multi-file extensions use an index to organize their files. File tools require explicit `--effects fs.read` or `--effects fs.write` with `--fs-root`; real workflows live in `examples/stdlib-handbook`. Read the [executable authoring guide](../../../doc/library-development.mq.md) for inline prose and complete runnable examples.
|
||||
|
||||
|
||||
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
|
||||
|
||||
*xs = > text.split value="a,b,c" sep=","*
|
||||
**xs = > text.split value="a,b,c" sep=","**
|
||||
> print text=`xs`
|
||||
*t = > clock.now_unix*
|
||||
**t = > clock.now_unix**
|
||||
```
|
||||
|
||||
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
|
||||
@@ -185,8 +189,12 @@ Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifa
|
||||
|
||||
**Do not degrade:** Document/Endpoint metadata; facade `web.page|route|serve|render|inspect`; View `|type|slot|value|attrs|style|` only; no `compose_*` / `configure` / author `ensure_plugin`. DB → `ext/data`; auth → `ext/security`; net → `ext/net`.
|
||||
|
||||
- EN: `import web:ext/web/web.mq.md`
|
||||
- ZH: `导入 网页:ext/web/网页.mq.md`
|
||||
- **Root skill (agents first):** [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · ZH [`ext/web/网页/索引.mq.md`](../../ext/web/网页/索引.mq.md)(作者门面仍为 `网页.mq.md`)
|
||||
- **Layout law (in-package):** file-partition pages (nav/sidebar/footer/…) until simple; no HTML/CSS injection as default — [`ext/web/layout/index.mq.md`](../../ext/web/layout/index.mq.md) · [ext-web-layout-paradigm.md](../../doc/design/ext-web-layout-paradigm.md)
|
||||
- **Recursive practice:** home → nav/main/footer → footer brand/links → links docs/community; continue until a leaf is plain Markdown. Parents import children and declare one relationship. Use `component.markdown`, `component.wrap`, `layout.stack`, and `layout.columns`; merge alone gives siblings, not columns.
|
||||
- **Runnable reference:** [web-layout-handbook](../../../examples/web-layout-handbook/index.mq.md) and [Chinese reference](../../../examples/web-layout-handbook-zh/index.mq.md). A composed Document declares `view: main` and returns node rows at startup; ordinary Documents keep their Markdown/data-source path. Use `inspect root=...` for disk routes, and `run` for a live server.
|
||||
- EN author facade: `import web:ext/web/web.mq.md`
|
||||
- Agent: `marqdo call ext/web/layout/index.mq.md rules --json` then facade tools with `--effects plugin`
|
||||
|
||||
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
|
||||
|
||||
@@ -194,12 +202,15 @@ Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · example:
|
||||
|
||||
Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --release -p marqdo_plugin_quantum`, then **`marqdo ext add quantum` again** so view loads the new `libquantum.so` (stale plugin = old black/white circuits).
|
||||
|
||||
- EN: `import quantum:ext/quantum/quantum.mq.md`
|
||||
- ZH: `导入 量子:ext/quantum/量子.mq.md`
|
||||
- **Root skill (read first):** [`ext/quantum/index.mq.md`](../../ext/quantum/index.mq.md) — explains every module and exact `marqdo call` commands for agents with no other context.
|
||||
- **Ext paradigm:** [`doc/design/ext-skill-tools-paradigm.md`](../../doc/design/ext-skill-tools-paradigm.md) — code=doc=skill=tools; checklist for new packs.
|
||||
- **Modules:** `circuit/` · `gate/` · `simulate/` · `state/` · `density/` · `viz/` · `_capability/` (each has `index.mq.md`). ZH package: `ext/quantum/量子/`(根 `索引.mq.md`,模块同名中文目录).
|
||||
- **Agent:** `marqdo call ext/quantum/<module>/index.mq.md <fn> … --effects plugin` (`--toget` / `$name`). Narration: `marqdo check --narrative-ratio FILE`.
|
||||
- **Author import example:** `circuit: ext/quantum/circuit/index.mq.md` then `circuit.circuit` / method chain.
|
||||
|
||||
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; ≤12 qubits for statevector; density-matrix ops ≤6 qubits; one language file per program; quote draw string args (`kind="…"`, `theme="…"`).
|
||||
|
||||
**Core:** `# circuit` / `# gate` / `# density` — table `steps=` or method chain; `simulate` / `probabilities` / `run` / `draw`.
|
||||
**Core:** domain skills above (`# circuit` / `# gate` / `# density` on module files) — table `steps=` or method chain; `simulate` / `probabilities` / `run` / `draw`.
|
||||
|
||||
**Q7 linear algebra:** `density`, `partial_trace`, `eig`, `expect` (Pauli string, left=high bit), `purity`, `kron`, `schmidt`, `fidelity`.
|
||||
|
||||
@@ -208,8 +219,8 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
|
||||
**Q8 themes (circuit / probs / bloch):** `theme="dark"|"light"|"bw"` (ZH `主题=`; **default `dark`** — slate lab look, gate-family colors, label chips so wires never cross `q0` text). View plot chrome follows `data-theme` on the SVG. Advanced kinds (hinton/…) still Q8c pending full re-skin.
|
||||
|
||||
```markdown
|
||||
*_ = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*_ = > `qc`.draw kind="probs" theme="light"*
|
||||
**_ = > `qc`.draw kind="circuit" theme="dark"**
|
||||
**_ = > `qc`.draw kind="probs" theme="light"**
|
||||
```
|
||||
|
||||
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
|
||||
@@ -240,8 +251,8 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
|
||||
| `# main` then prose then code with no blank line | Blank line before code |
|
||||
| `if x > 0:` | `1. `x` > 0` |
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `**a = 1**` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (italic is return, and bare text args) | `**xs = > text.split value="a,b" sep=","**` — statement; quote text literals |
|
||||
| Forgetting empty return after nested `##` helper when outer continues | Add `*None*` / `**` / `****` (not `---`) |
|
||||
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
|
||||
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
|
||||
|
||||
@@ -1,7 +1,5 @@
|
||||
# Marqdo examples (AI)
|
||||
|
||||
v0.3: `**…**` = code (assign / call); `*…*` = return. Prefer `[key](coll)` over footnote get. Bracket calls: `礼貌 [问候] x`.
|
||||
|
||||
## 1. Hello (English)
|
||||
|
||||
```markdown
|
||||
@@ -18,7 +16,7 @@ v0.3: `**…**` = code (assign / call); `*…*` = return. Prefer `[key](coll)` o
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
## 3. Function + named call + empty return
|
||||
## 3. Function + named call + body end
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -32,24 +30,22 @@ Greeting via a nested function:
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
*None*
|
||||
---
|
||||
```
|
||||
|
||||
Or end with a whole-line empty bold return: `**` / `****`. Lone `---` is a thematic break (skipped), not function end.
|
||||
|
||||
## 4. Bindings and return
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**a = 2**
|
||||
**b = add_one n=`a`**
|
||||
**打印 内容=`b`**
|
||||
*a = 2*
|
||||
*b = > add_one n=`a`*
|
||||
> print text=`b`
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
*n + 1*
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
## 5. Branch with else
|
||||
@@ -57,7 +53,7 @@ Or end with a whole-line empty bold return: `**` / `****`. Lone `---` is a thema
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**n = 0**
|
||||
*n = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
@@ -82,7 +78,8 @@ Or end with a whole-line empty bold return: `**` / `****`. Lone `---` is a thema
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
## 6b. Map table + link-index get
|
||||
|
||||
## 6b. Map table + footnote get
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -93,20 +90,13 @@ Or end with a whole-line empty bold return: `**` / `****`. Lone `---` is a thema
|
||||
|------|------|
|
||||
| 水果 | 蔬菜 |
|
||||
|
||||
**种 = [苹果](分类)**
|
||||
**打印 内容=`种`**
|
||||
*种 = 分类[^苹果]*
|
||||
> print text=`种`
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
|
||||
**第一 = [1](篮子)**
|
||||
**打印 内容=`第一`**
|
||||
*第一 = 篮子[^1]*
|
||||
```
|
||||
|
||||
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Prefer `[key](coll)` (lists are 1-based). Legacy `` coll[^key] `` still parses. Foreach on a map walks **keys**.
|
||||
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Data cells are expressions (same as call-arg values): bare words, numbers, `` `var` ``, quoted strings; URLs and `gpt-4o-mini` stay text via path/hyphen folding. Footnotes: lists use 1-based digit indices; maps use key text (including digit keys like `[^00]`). Foreach on a map walks **keys**.
|
||||
|
||||
Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of maps (marker column excluded):
|
||||
|
||||
@@ -117,31 +107,15 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
|
||||
**名 = [品名]([1](订单))**
|
||||
*名 = 订单[^1][^品名]*
|
||||
```
|
||||
|
||||
## 6c. Bracket-marked call + modifiers
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**打印 内容=(礼貌 [问候] "Marqdo")**
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
|
||||
**出 = `礼貌` + ", " + `谁` + "!"**
|
||||
*出*
|
||||
```
|
||||
|
||||
`礼貌 [问候] …` → `礼貌=True`. `]` immediately followed by `(` is index, not a call.
|
||||
|
||||
## 6d. Browser effects — tables + lib/browser (not json.set)
|
||||
## 6c. Browser effects — tables + lib/browser (not json.set)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import browser:lib/browser.mq.md
|
||||
import:
|
||||
browser: lib/browser.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -155,108 +129,26 @@ import browser:lib/browser.mq.md
|
||||
**`wire`**
|
||||
|
||||
## bump
|
||||
**count = count + 1**
|
||||
**label = str count**
|
||||
*`count` = count + 1*
|
||||
*`label` = > str count*
|
||||
**> browser.set_text sel="#count" text=label**
|
||||
```
|
||||
|
||||
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
|
||||
|
||||
## 6e. Agent / LLM result maps — GFM first (positive)
|
||||
|
||||
Return and soft-error packs are **tables**, not `json.set` pipelines. Full style contract: [marqdo-dev](../marqdo-dev/SKILL.md) §2.
|
||||
|
||||
```markdown
|
||||
---
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
## step_ok
|
||||
+ `task`
|
||||
+ `reply`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | result |
|
||||
|--------|------|--------|
|
||||
| ok | `task` | `reply` |
|
||||
|
||||
*out*
|
||||
|
||||
## step_err
|
||||
+ `task`
|
||||
+ `err`
|
||||
|
||||
`out` =
|
||||
|
||||
| status | task | error |
|
||||
|--------|------|-------|
|
||||
| error | `task` | `err` |
|
||||
|
||||
*out*
|
||||
|
||||
## soft_http_pack
|
||||
+ `msg`
|
||||
+ `usage0`
|
||||
|
||||
**empty_tc = > table.empty_list**
|
||||
|
||||
`pack` =
|
||||
|
||||
| finish | text | error | usage | tool_calls |
|
||||
|--------|------|-------|-------|------------|
|
||||
| error | "" | `msg` | `usage0` | `empty_tc` |
|
||||
|
||||
*pack*
|
||||
```
|
||||
|
||||
Do **not** mirror legacy `ext/ai/agent.mq.md` `json.parse`+`json.set` chains when adding new arms — convert the shape to a table.
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: split demo
|
||||
import text:lib/text.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**parts = [text.str_split] s="a,b,c" sep=","**
|
||||
**打印 内容=`parts`**
|
||||
```
|
||||
|
||||
## 7b. Mid M1 — regex + encoding (no plugin)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import re:lib/re.mq.md
|
||||
import enc:lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**`ok` = [re.is_match] text="a@b.c" pattern="@"**
|
||||
**`b64` = [enc.base64_encode] text="hi"**
|
||||
**打印 内容=`ok`**
|
||||
**打印 内容=`b64`**
|
||||
```
|
||||
|
||||
## 7c. Mid M6 — log + uuid
|
||||
|
||||
```markdown
|
||||
---
|
||||
import log:lib/log.mq.md
|
||||
import uuid:lib/uuid.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> log.info text="start"
|
||||
> log.set_level level="debug"
|
||||
> log.debug text="detail"
|
||||
**id = [uuid.v4]**
|
||||
**打印 内容=`id`**
|
||||
*parts = > split value=a,b,c sep=,*
|
||||
> print text=`parts`
|
||||
```
|
||||
|
||||
## 8. Comment paragraphs (blank-line rule)
|
||||
@@ -265,7 +157,7 @@ import uuid:lib/uuid.mq.md
|
||||
# main
|
||||
|
||||
This whole paragraph is a comment, including lines that look like code:
|
||||
**not_executed = 1**
|
||||
*not_executed = 1*
|
||||
> print text=also still comment
|
||||
|
||||
After a blank line, code runs:
|
||||
@@ -278,18 +170,19 @@ After a blank line, code runs:
|
||||
```markdown
|
||||
---
|
||||
description: loads math
|
||||
import math:lib/math.mq.md
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**t = > num value=3.5**
|
||||
**打印 内容=`t`**
|
||||
*t = > num value=3.5*
|
||||
> print text=`t`
|
||||
```
|
||||
|
||||
## 10. Object handle + method
|
||||
|
||||
See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
|
||||
See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
|
||||
|
||||
## 10b. Object inheritance
|
||||
|
||||
@@ -299,16 +192,16 @@ See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` const
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
**msg = "Hello, `who`!"**
|
||||
*msg*
|
||||
*msg = "Hello, `who`!"*
|
||||
**msg**
|
||||
|
||||
# Loud = > Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
**msg = "HELLO, `who`!"**
|
||||
*msg*
|
||||
*msg = "HELLO, `who`!"*
|
||||
**msg**
|
||||
```
|
||||
|
||||
`_type` stays the most specific name (`Loud`). Methods walk the base chain; same-name `##` on the child overrides. **No implicit super** — if the child needs parent fields, call the parent explicitly:
|
||||
@@ -317,25 +210,26 @@ See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` const
|
||||
# Child = > Parent
|
||||
+ `name`
|
||||
|
||||
**self = > Parent name=`name`**
|
||||
**self = [table.put] in=`self` at="extra" value=1**
|
||||
*self*
|
||||
*self = > Parent name=`name`*
|
||||
*self = > json.set map=`self` key=extra value=1*
|
||||
**self**
|
||||
```
|
||||
|
||||
## 11. Agent layout (ABI)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import agent:ext/agent.mq.md
|
||||
import:
|
||||
agent: ext/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_native
|
||||
|
||||
**ws = > agent**
|
||||
**n = > `ws`.ensure_layout**
|
||||
**打印 内容=`n`**
|
||||
*ws = > agent*
|
||||
*n = > `ws`.ensure_layout*
|
||||
> print text=`n`
|
||||
```
|
||||
|
||||
Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see `doc/design/ext-agent.md`).
|
||||
@@ -343,14 +237,14 @@ Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see
|
||||
## 12. What not to emit
|
||||
|
||||
```markdown
|
||||
# BAD — bare bold that is not code-shaped (decorative OK); do not use bold/italic as print
|
||||
# BAD — bold is return, not print
|
||||
**Hello**
|
||||
|
||||
# BAD — Python control keywords
|
||||
if x > 0:
|
||||
print(x)
|
||||
|
||||
# BAD — wrapping a call in italics as if it were a statement
|
||||
# BAD — wrapping a call in italics
|
||||
*> print text=hi*
|
||||
|
||||
# BAD — old branch syntax (removed)
|
||||
@@ -367,56 +261,48 @@ if x > 0:
|
||||
> print text=y-pos
|
||||
2. *
|
||||
> print text=y-other
|
||||
|
||||
# GOOD — print / return
|
||||
**打印 内容="hi"**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
## 13. Dynamic site (ext/web, minimal)
|
||||
## 13. Dynamic site (Web Artifact, minimal)
|
||||
|
||||
`index.mq.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: hello-site
|
||||
import web:ext/web/web.mq.md
|
||||
import db:db/index.mq.md
|
||||
type: web
|
||||
title: Hello
|
||||
route: /
|
||||
method: GET
|
||||
---
|
||||
|
||||
# Hello
|
||||
|
||||
Executable document as a page.
|
||||
```
|
||||
|
||||
`serve.mq.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`shell` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav | |
|
||||
|
||||
`main` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| title | posts.title | |
|
||||
| body | posts.summary | |
|
||||
|
||||
**store = > db.open**
|
||||
**css = "body{font-family:sans-serif}"**
|
||||
**page = > web.page title="Hello"**
|
||||
**page = > page.compose_components components=`shell`**
|
||||
**page = > page.compose_main main=`main`**
|
||||
**page = > page.css css=`css`**
|
||||
**app = > web.app page=`page` port=8080**
|
||||
**app = > app.static prefix="/static" dir="static"**
|
||||
> listen app=`app`
|
||||
> web.serve root="." host="127.0.0.1" port=8080
|
||||
```
|
||||
|
||||
- Import `ext/web/web.mq.md` **or** `ext/web/网页.mq.md` — not both; match API language to the file.
|
||||
- Full blog/CMS patterns: `examples/marqdo-blog/` (routes, SEO, RSS, auth, upload, WS).
|
||||
- Run after `marqdo ext add web` and building `marqdo_plugin_web`.
|
||||
- Import `ext/web/web.mq.md` **or** `ext/web/网页.mq.md` — not both.
|
||||
- Full Artifact blog: `examples/marqdo-blog/` (`pages/` · `api/` · `db/` · `data_source`).
|
||||
- Design: `doc/design/ext-web-artifact.md` · ADR 0007. No `compose_*` / `configure`.
|
||||
|
||||
## 14. Quantum entanglement lab (ext/quantum Q7/Q8)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
import:
|
||||
quantum: ext/quantum/circuit/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -428,42 +314,15 @@ import quantum:ext/quantum/quantum.mq.md
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
**qc = > quantum.circuit qubits=2 steps=`steps`**
|
||||
**rho = > `qc`.density**
|
||||
**red = > `rho`.partial_trace keep=0**
|
||||
**sch = > `qc`.schmidt cut=1**
|
||||
**_ = > `qc`.draw kind="circuit" theme="dark"**
|
||||
**_ = > `qc`.draw kind="hinton"**
|
||||
**打印 内容=`red`**
|
||||
*qc = > quantum.circuit qubits=2 steps=`steps`*
|
||||
*rho = > `qc`.density*
|
||||
*red = > `rho`.partial_trace keep=0*
|
||||
*sch = > `qc`.schmidt cut=1*
|
||||
*_ = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*_ = > `qc`.draw kind="hinton"*
|
||||
> print text=`red`
|
||||
```
|
||||
|
||||
- Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`.
|
||||
- `theme="dark"|"light"|"bw"` (default dark) on `circuit` / `probs` / `bloch`. Quote `kind=` / `theme=`.
|
||||
- After rebuilding the plugin: `marqdo ext add quantum` so view loads the new native lib.
|
||||
|
||||
## 15. Linear algebra (ext/linalg)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**`A` = > la.symbol name="A" rows=2 cols=2**
|
||||
**`B` = > la.symbol name="B" rows=2 cols=2**
|
||||
**`C` = `A` + `B`**
|
||||
**`P` = `A` * `B`**
|
||||
```
|
||||
|
||||
Prefer:
|
||||
|
||||
```markdown
|
||||
**`env` = > la.declare table=`shapes`**
|
||||
**`P` = [A](env) * [B](env)**
|
||||
**`t` = > `P`.T_ascii**
|
||||
```
|
||||
|
||||
- Infix `+` / `-` / `*`;`ascii` / `T_ascii` 默认化简(`raw=True` 可关)。
|
||||
- Formula-doc design: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
|
||||
- Examples: `examples/linalg-transpose/`, `examples/linalg-svd/`, `examples/linalg-least-squares/`.
|
||||
@@ -12,13 +12,13 @@ marqdo view PATH # docs browser, default port 7429
|
||||
marqdo debug PATH # debugger UI, default port 7430
|
||||
marqdo catalog PATH -o .marqdo
|
||||
marqdo ext list
|
||||
marqdo ext add llm|agent|web|quantum|linalg
|
||||
marqdo ext remove llm|agent|web|quantum|linalg
|
||||
marqdo ext add llm|agent|web|quantum
|
||||
marqdo ext remove llm|agent|web|quantum
|
||||
```
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
|
||||
**v0.3 surface:** `**…**` = code; `*…*` = return; parameters `` + `name` `` (or prose-inferred); branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [item](coll) ``; get `` [key](coll) ``; bracket calls `` mod [fn] args ``. See `doc/design/markdown-mapping-v0.3.md`.
|
||||
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [item](coll) `` or `` - [`item`](`coll`) ``; identifiers in backticks (foreach header may omit ticks). See `doc/design/markdown-mapping.md`.
|
||||
|
||||
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
|
||||
|
||||
@@ -44,15 +44,6 @@ Import one file; use **that** file’s function names.
|
||||
|-----------|-----------|-------------------------|
|
||||
| `lib/text.mq.md` | `lib/文本.mq.md` | text helpers / 去空白·拆分·拼接… |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | `put`/`改` + list/map(见 `doc/design/stdlib-table.md`) |
|
||||
| `lib/re.mq.md` | `lib/正则.mq.md` | Mid:`is_match`/`find`/`replace`/… |
|
||||
| `lib/encoding.mq.md` | `lib/编码.mq.md` | Mid:base64/hex |
|
||||
| `lib/path.mq.md` | `lib/路径.mq.md` | Mid:join/normalize/… |
|
||||
| `lib/hash.mq.md` | `lib/哈希.mq.md` | Mid:sha256/hmac/… |
|
||||
| `lib/secrets.mq.md` | `lib/机密.mq.md` | Mid:token_hex/urlsafe |
|
||||
| `lib/csv.mq.md` | `lib/逗号表.mq.md` | Mid:parse/stringify |
|
||||
| `lib/cli.mq.md` | `lib/命令行.mq.md` | Mid:`parse` flags |
|
||||
| `lib/log.mq.md` | `lib/日志.mq.md` | Mid:level-filtered one-line logs |
|
||||
| `lib/uuid.mq.md` | `lib/标识.mq.md` | Mid:UUID v4 |
|
||||
| `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM client effect helpers(GFM + `set_text`/`canvas`/…;见 marqdo-dev) |
|
||||
| `lib/fs.mq.md` | `lib/文件.mq.md` | filesystem |
|
||||
| `lib/sys.mq.md` | `lib/系统.mq.md` | process / cwd / load_dotenv |
|
||||
@@ -64,30 +55,37 @@ Import one file; use **that** file’s function names.
|
||||
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
|
||||
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
|
||||
| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) |
|
||||
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
|
||||
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
|
||||
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | formula MatExpr + factorize/draw — see **ext/linalg** below |
|
||||
| `ext/web/index.mq.md` · `web.mq.md` | `ext/web/网页/索引.mq.md` · `网页.mq.md` | dynamic sites — see **ext/web** section below |
|
||||
| `ext/quantum/index.mq.md` + modules | `ext/quantum/量子/索引.mq.md` + modules | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
|
||||
|
||||
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
|
||||
|
||||
## ext/web (dynamic sites)
|
||||
## ext/web (Artifact sites · ADR 0007)
|
||||
|
||||
Install: `marqdo ext add web` (`网页`). Native: `cargo build --release -p marqdo_plugin_web`.
|
||||
Install: `marqdo ext add web` (`网页`). Native: `bash scripts/build-web-plugin.sh`.
|
||||
|
||||
| EN import | ZH import | Core types |
|
||||
|-----------|-----------|------------|
|
||||
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | `# page` `# style` `# db` `# form` `# app` `# auth` `# cache` `# storage` |
|
||||
Layout practice: split home into nav/main/footer; split footer into brand/links,
|
||||
then links into docs/community until content leaves are ordinary Markdown.
|
||||
Use `component.markdown|wrap`, `layout.stack|columns`, and @ record lists.
|
||||
A parent value holds child rows of the same five-column View schema.
|
||||
Explicit `view: main` Documents assemble once at startup; `inspect root=...`
|
||||
scans disk declarations. See the Web root handbook and reference layout site.
|
||||
|
||||
| Area | EN methods (representative) | Notes |
|
||||
|------|----------------------------|-------|
|
||||
| Page | `compose_components`, `compose_main`, `render`, `meta`, `paginate` | GFM tables; cells are literal path strings |
|
||||
| DB | `init`, `insert`, `select`, `paginate`, `get`, `update`, `delete`, `migrate`, `fts`, `search`, `count`, `事务`/`txn` | init supports `unique`/`index`/`fk`; auto `created_at`/`updated_at` |
|
||||
| App | `route`, `static`, `configure`, `listen`, `auth`, `gate`, `upload`, `download`, `gallery`, `route_rss`, `redirect`, `error_page`, `sitemap`, `robots` | W0–W7 + P3 complete |
|
||||
| Auth | `login`, `check`, `logout`, `hash_password` | argon2 + CSRF + SQLite sessions; `role` for RBAC |
|
||||
|
||||
Drivers (Postgres / Redis / S3): `db url=postgres://…`, `cache url=memory:`, `storage url=file:…` — see `doc/design/ext-web-drivers.md`.
|
||||
| EN import | ZH import | Surface |
|
||||
|-----------|-----------|---------|
|
||||
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | facade: `page` · `route` · `serve` · `render` · `inspect` · `use` |
|
||||
|
||||
Example project: `examples/marqdo-blog/`. Capability matrix: `doc/design/web-net-capabilities.md`.
|
||||
| Kind | Metadata | Notes |
|
||||
|------|----------|-------|
|
||||
| Document | `type: web` / `类型: 网页` | `route` · `data_source` · `data_order` · `data_where` |
|
||||
| Endpoint | `type: endpoint` / `类型: 端点` | `path` · `method` · `# main` handler · `request`/`response` |
|
||||
| View | `|type|slot|value|attrs|style|` | `web.render nodes=` |
|
||||
| Resource | `ext/data` · `ext/security` · `ext/net` | db/cache/storage · auth/rbac/oidc · websocket |
|
||||
|
||||
Do **not** use `compose_*` / `app.configure` / author `ensure_plugin`.
|
||||
|
||||
Example: `examples/marqdo-blog/`. Design: `doc/design/ext-web-artifact.md`. Historical matrix: `doc/design/web-net-capabilities.md`.
|
||||
|
||||
## ext/quantum (circuits + Q7/Q8)
|
||||
|
||||
@@ -95,7 +93,7 @@ Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p
|
||||
|
||||
| EN import | ZH import | Core types |
|
||||
|-----------|-----------|------------|
|
||||
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | `# circuit` `# gate` `# density` |
|
||||
| `ext/quantum/circuit/index.mq.md` (etc.) | `ext/quantum/量子/电路/索引.mq.md` (etc.) | `# circuit` / `# 电路` · `# gate` / `# 门` · `# density` / `# 密度` + call tools |
|
||||
|
||||
| Area | EN APIs | Notes |
|
||||
|------|---------|-------|
|
||||
@@ -108,21 +106,12 @@ Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p
|
||||
|
||||
Examples: `examples/quantum-bell/`, `examples/quantum-entanglement/`. Design: `doc/design/ext-quantum.md` · Q7: `doc/design/ext-quantum-q7.md` · Q8: `doc/design/ext-quantum-viz-style.md`.
|
||||
|
||||
## ext/linalg (formula-first linear algebra)
|
||||
|
||||
Install: `marqdo ext add linalg` (`线性代数`). Native: `cargo build --release -p marqdo_plugin_linalg`, then re-run `ext add`.
|
||||
|
||||
| EN import | ZH import | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | Top-level `symbol`/`mul`/`factorize`/`draw` |
|
||||
|
||||
Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc/design/ext-linalg.md` · formula-doc: `doc/design/ext-linalg-formula-doc.md` · roadmap: `doc/roadmap/ext-linalg.md`.
|
||||
|
||||
## Formula + plot (math)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import math:lib/math.mq.md
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -141,7 +130,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
|
||||
@@ -183,8 +173,7 @@ See `doc/design/call-arguments.md`.
|
||||
|
||||
| Doc | Topic |
|
||||
|-----|--------|
|
||||
| `doc/design/markdown-mapping-v0.3.md` | Syntax constitution (runtime) |
|
||||
| `doc/design/markdown-mapping.md` | Legacy v0.2 notes |
|
||||
| `doc/design/markdown-mapping.md` | Syntax constitution |
|
||||
| `doc/design/objects.md` | `#` objects / `##` methods |
|
||||
| `doc/design/keywords.md` | Builtins / keywords |
|
||||
| `doc/design/return-hr-and-code-surface.md` | Function end / surfaces |
|
||||
@@ -199,6 +188,4 @@ See `doc/design/call-arguments.md`.
|
||||
| `doc/design/ext-quantum.md` | `ext/quantum` circuits |
|
||||
| `doc/design/ext-quantum-q7.md` | Q7 density linear algebra + advanced SVG |
|
||||
| `doc/design/ext-quantum-viz-style.md` | Q8 themed SVG (`dark`/`light`/`bw`; circuit/probs/bloch) |
|
||||
| `doc/design/ext-linalg.md` | `ext/linalg` formula MatExpr + factorize/draw |
|
||||
| `doc/design/ext-linalg-formula-doc.md` | 公式文档面:跑通即正确 · 代数/计算两面 |
|
||||
| `doc/design/view-debug.md` | view / debug hosts |
|
||||
@@ -0,0 +1,34 @@
|
||||
name: executable-knowledge
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
gate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- name: Build agent + llm plugins (EK / workbench gates)
|
||||
run: |
|
||||
cargo build -p marqdo_plugin_agent --locked
|
||||
cargo build -p marqdo_plugin_llm --locked
|
||||
- name: Workbench contracts (M00–M06 / F-subset)
|
||||
run: cargo test --test workbench_contracts --locked
|
||||
- name: Offline executable-knowledge gate
|
||||
run: cargo test --test executable_knowledge --locked
|
||||
- name: Isolated execute MR-01 (dual 60s SSE + short reads)
|
||||
run: |
|
||||
cargo build -p marqdo_plugin_llm --locked
|
||||
bash scripts/build-web-plugin.sh
|
||||
cargo test --test isolated_execute_mr01 --locked -- --nocapture
|
||||
timeout-minutes: 5
|
||||
- name: no ignored tests counted as success
|
||||
run: |
|
||||
if grep -n '#\[ignore\]' tests/executable_knowledge.rs; then
|
||||
echo "executable_knowledge must not use #[ignore] as success evidence" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "ok: no #[ignore] in executable_knowledge gate"
|
||||
@@ -126,35 +126,14 @@ 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
|
||||
- **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
|
||||
- **v1.5.1**:view 静态/动态统一 + 外联值传递——共用执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin
|
||||
- **v1.5.1**: View static/live unified + foreign value passing — shared execution path, build-time run with stdout injection, `foreign.session` value passing, cell stdin
|
||||
- **v1.5.0**:外联 v2 + 文档原生 Notebook——invoke/JSON call/并行/持久 Python·Node/状态桥 · cell 单步 · 高对比 view
|
||||
- **v1.5.0**: Foreign v2 + document-native notebooks — invoke, JSON calls, fan-out, persistent Python/Node, state bridge, cell stepping, high-contrast view
|
||||
- **v1.5.0 ext**:扩展包同步 1.5.0 / Ext pack 1.5.0
|
||||
- **v1.4.6**:裸自增升参——首次粗体赋值左值即声明;`n = n + 1` 无反引号也是必选形参
|
||||
- **v1.4.6**: Bare self-increment is a required parameter — first bold assignment LHS is a declaration
|
||||
- **v1.4.5**:Streamable HTTP MCP + web invoke Bearer/401 · openai/agent json.get 硬化
|
||||
- **v1.4.5**: Streamable HTTP MCP + web invoke Bearer/401; openai/agent json.get hardening
|
||||
- **v1.4.2**:Agent/LLM 优化 O1–O5——sandbox trial · promote proof · step_route/EFI/cost · lint · quarantine
|
||||
- **v1.4.2**: Agent/LLM optimize O1–O5 — sandbox trial, promote proof, step_route/EFI/cost, lint, quarantine
|
||||
- **v1.4.1**:view 标注连线——SVG mid→mid(underline 底中 → chip 顶中)· 帧 chip id 对齐 · L→R 密度
|
||||
- **v1.4.1**: View annot leaders — SVG mid→mid (mark bottom-center → chip top-center), frame chip id unify, L→R density
|
||||
- **v1.4.0**:叙述统一——`% marqdo: var=` · 臂/循环体叙述 · foreach 中英糖 · 图片自写回 · view 推断形参
|
||||
- **v1.4.0**: Prose-unified control flow — formula meta bind, arm/loop narrative, foreach sugar, image writeback, inferred-param view
|
||||
- **v1.3.3**:view 文档面 Structure——叙述保真 · 标记面 · 调用/循环帧 · `#mq-view-trace` · 静态站同源
|
||||
- **v1.3.3**: Browse document-surface Structure — narration, markers, call/loop frames, `#mq-view-trace`, static site parity
|
||||
- **v1.3.0**:Engineering Knowledge Compiler——L0–L4 · `reuse`/`find`/`duplicate` · Agent preflight(REUSE→ADAPT→CREATE)
|
||||
- **v1.3.0**: Engineering Knowledge Compiler — L0–L4 catalog, reuse/find/duplicate, Agent preflight (REUSE→ADAPT→CREATE)
|
||||
- **v1.2.0**:Web Artifact(ADR 0007)——Document/Endpoint · `web.serve`/`render`/`inspect` · `ext/data|security|net` · 移除 `compose_*`/`configure`
|
||||
- **v1.2.0**: Web Artifact (ADR 0007) — Document/Endpoint, web.serve/render/inspect, ext/data|security|net, compose_*/configure removed
|
||||
- **Linux 包必出**:`*-native-x86_64-unknown-linux-gnu.zip` + Linux CLI bundle
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-ai-optimize](https://github.com/cflmy/marqdo/blob/main/doc/roadmap/ext-ai-optimize.md)
|
||||
- **2.6.0**:标准库与拓展库成为可执行手册;650 个公开标准库函数,标题下契约、叙述形参与句中调用。
|
||||
- **2.6.0**: Executable library handbooks, 650 public standard-library functions, inline actions and source contracts.
|
||||
- 文件/字节/集合/Result/文档/HTTP/任务/TOML/时区工程能力;Quantum 实验与 Web 递归 Markdown 布局。
|
||||
- File, binary, collection, document and task workflows; executable Quantum experiments and recursive Web layouts.
|
||||
- View 正文读动作,左右侧注看逻辑;空逻辑明确提示;知识区按输入、返回和依据组织。
|
||||
- View keeps action text in prose, implementation in margin notes, and readable knowledge facts separate from execution.
|
||||
- CLI · wasm · ext · VS Code extension: **2.6.0**. Core surface unchanged: **19 constructs**.
|
||||
- Linux CLI and native plugin zips are required; see CHANGELOG for exact platform/effect boundaries.
|
||||
|
||||
### Downloads
|
||||
|
||||
|
||||
@@ -79,11 +79,16 @@ plugins/*/tmp/
|
||||
# Plot SVGs emitted beside tests / notebooks when demos run
|
||||
/tests/**/*-plot-*.svg
|
||||
|
||||
# Lean Lake build outputs (sources under verification/ stay tracked)
|
||||
**/.lake/
|
||||
|
||||
# PLDI / thesis harness scratch must never land in this tree
|
||||
.lx*-tmp/
|
||||
|
||||
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
|
||||
/ext/native/
|
||||
# Install-root path hints from `marqdo ext add` — never belong in the source tree
|
||||
/ext/*.plugin
|
||||
|
||||
# Go web plugin c-shared build output (./scripts/build-web-plugin.sh)
|
||||
/plugins/web/build/
|
||||
@@ -103,3 +108,4 @@ tests/ext/_sbx_cow/
|
||||
|
||||
tests/ext/_sbx_*/
|
||||
examples/**/_example_sbx/
|
||||
.secrets/
|
||||
+406
@@ -1,5 +1,318 @@
|
||||
# Changelog
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
## v2.6.0 — 2026-11-08
|
||||
|
||||
### Highlights / 亮点
|
||||
|
||||
标准库、拓展库与阅读界面共同围绕“源码即手册,文档即 SKILL,函数即工具”完成更新。
|
||||
CLI、WASM、扩展包与 VS Code 扩展统一为 2.6.0。
|
||||
|
||||
- 标准库新增完整文件整理、二进制与分块、集合处理、结构化数据、文档修改、HTTP、子任务与时区能力。
|
||||
- 61 份公开标准库提供 650 个函数,保持单文件自述;多文件拓展库通过 index 组织真实工作流。
|
||||
- Quantum 提供可执行实验与会话句柄;Web 明确从区域树递归拆到 Markdown 叶子的工程方式。
|
||||
- View 正文只呈现动作说明,实际逻辑进入左右侧注,空括号明确提示待补逻辑;知识区按输入输出与依据组织。
|
||||
- Standard libraries add practical file, binary, collection, structured-data, document, HTTP, task and timezone workflows.
|
||||
- Libraries are executable handbooks with contracts, narrative parameters and readable inline operations; View separates action text, implementation and observed results.
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:无增删,仍为 19 个核心构造。新增能力属于 Runtime / Document;
|
||||
行内遮蔽边界与 GFM 转义修复沿用既有标记,不引入另一套语法或 Skill 编译器。
|
||||
|
||||
### Added
|
||||
|
||||
- 文件:查找、行读写、JSON/CSV 读写、二进制字节和分块操作、临时资源、单文件原子写、摘要检查、目录批处理与可选 ZIP。
|
||||
- 集合:范围、枚举、投影、筛选、首项/任一/全部判断、分组汇总、连接、集合运算、模式校验及 key/value 行记录构造。
|
||||
- 数据与工程:Result、完整 TOML、IANA 时区/DST、结构化 HTTP 结果与下载、子任务超时/并发/取消、保留周围叙述的受控文档修改。
|
||||
- 标准库单文件手册、开发指南、真实工程示例,以及数据、安全、网络、线性代数、AI 的工程入口与安装依赖。
|
||||
- Quantum 任务导航、实验与双语门面;Web 递归布局、普通 Markdown 叶子和双语参考站点;call 会话中传递实际资源句柄。
|
||||
- View 核心语法阅读指南、实现侧注、可读知识卡片、最终绑定与调用记录,以及静态/实时/无脚本浏览器验收。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 修复中文智能体单步被说明中的斜体 map 提前返回、事务构造器返回未绑定 self、策略说明标题被误识别为对象等旧问题。
|
||||
- 修复行内遮蔽中标签星号和载荷乘法的结束边界,以及 GFM 单元格的转义竖线。
|
||||
- 修复整句遮蔽只处理首个链接、改写叙述的问题;普通导航与文字字面量不冒充可执行逻辑。
|
||||
- 单文件 View 只分析实际依赖闭包,避免无关同目录模块重名使知识说明整体不可用。
|
||||
- 修复回放策略 wire 命令与 agent smoke 工具注册,保持可执行知识门禁可复现。
|
||||
|
||||
### Changed
|
||||
|
||||
- 标准库和拓展库的参数与返回表紧接标题;移除库源码中的旧加号形参,使用叙述形参与句中赋值、调用、返回。
|
||||
- 每个库单元叙述超过 50%;行内代码和绑定数据表仍计作代码,避免以模板或排版替代说明。
|
||||
- 知识区将身份和摘要折叠为技术详情,分别呈现静态检查、测试、来源与领域审阅;阅读操作不会执行代码。
|
||||
- 既有可用接口、默认值和副作用边界保持兼容。原生专属能力不宣称在 WASM 可用,目录批处理不宣称事务,摘要写入不宣称内核 CAS。
|
||||
|
||||
### Validation
|
||||
|
||||
- 本地全量回归 984 通过、0 失败、2 个原有忽略项;发布提交与打包产物另行复核。
|
||||
- 实际 wasm32 产物通过 ABI、桥接、双语集合与 32 位边界验收。
|
||||
- Chromium 验证七种宽度、实时与静态页面、无脚本回退、源码定位、曲线、帧切换与重新运行。
|
||||
|
||||
## v2.5.1 — 2026-11-07
|
||||
|
||||
### Highlights
|
||||
|
||||
**View 标注连线与工具栏优化 / View annotation and toolbar refinement**:执行标注精确绑定源码行与字节区间;连续 S 形曲线取代水平长线,标注贴近正文错落排布,并避让正文和相邻连线;浮动工具栏增加文字说明。CLI · wasm · ext **2.5.1**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造);无 Markdown 语法或插件 ABI 变更。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 执行标注从实际源码片段引出并连接标注标题,不再从正文边缘引出;多调用帧与循环轮次共用准确的源码区间,避免按类型猜测锚点。
|
||||
- 处理源码换行、重跑、窗口变化与字体加载后的连线定位;保留密集区域和窄屏的文内降级。
|
||||
- 连线连续弯曲、柔和金绿过渡,并为相邻曲线保留间距;宽屏标注更靠近正文,横纵方向错落排布。
|
||||
|
||||
### Changed
|
||||
|
||||
- 底部工具栏显示“刷新、设置、运行、清理、更多”,保留深浅色配色与原有操作行为。
|
||||
- 新增七种屏宽、曲率、连线交叉、两端定位及共享源码帧绑定的浏览器回归。
|
||||
- CLI、WASM、扩展包和 VS Code / Cursor 扩展同步 **2.5.1**;扩展包功能沿用 v2.5.0。
|
||||
|
||||
## v2.5.0 — 2026-11-07
|
||||
|
||||
### Highlights
|
||||
|
||||
**View 文档阅读界面重构 / View reader redesign**:暖白金色排版、新 Marqdo 标志与花枝羽毛素材;宽屏执行信息左右引出,窄屏回到正文下方;导航、搜索与悬浮工具栏;实时 view 与静态导出同源,公式和素材离线可用。CLI · wasm · ext **2.5.0**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)。本次变更集中于 view 展示与普通文档执行结果刷新;无 Markdown 语法或插件 ABI 变更。
|
||||
|
||||
```bash
|
||||
marqdo view public
|
||||
marqdo view output public -o site
|
||||
```
|
||||
|
||||
### Added
|
||||
|
||||
- 暖白/深色阅读主题、新 Logo、透明花枝与羽毛;顶部导航、正文/函数/文件搜索、阅读设置和悬浮工具栏。
|
||||
- 宽屏执行标注左右排布与避让,点击查看完整捕获值;窄屏、密集段落和打印采用正文内标注。
|
||||
- 内嵌 KaTeX 0.16.22、字体和装饰素材,静态页面断网仍可渲染公式。
|
||||
- 六种屏宽的 live/static 浏览器回归与普通文档重跑结果一致性回归。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 普通文档重跑后,从同一次执行捕获刷新正文、变量与轨迹,避免为更新标注重复执行。
|
||||
- 移除重复的正文 `id="structure"`,确保刷新定位到实际正文;修复搜索框 Escape 关闭与隐藏目录焦点行为。
|
||||
|
||||
### Changed
|
||||
|
||||
- 函数和变量面板按需打开;调用帧与循环轮次选择保留;高级 notebook 操作从工具菜单进入。
|
||||
- CLI、WASM、扩展包和 VS Code / Cursor 扩展同步为 **2.5.0**;扩展包功能沿用 v2.4.0 已发布内容。
|
||||
|
||||
## v2.4.0 — 2026-11-06
|
||||
|
||||
### Highlights
|
||||
|
||||
**Oracle journal 作语言值**:`foreign.oracle_journal` / `foreign.replay_check` 把观测与纯比较暴露为普通 Marqdo 值(非仅 notebook API);handle/code 不得入 journal;`copy` 拒绝 code。Bytecode / frontend / foreign session 模块化与 applications 金样例;`verification/replay-policy` Lean 策略身份。CLI · wasm · ext **2.4.0**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——变更在 `lib/foreign` 宿主表面与实现结构,不增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **`foreign.oracle_journal` / `foreign.replay_check`**:文档级观测列表与纯 journal 比较(`doc/design/oracle-journal-values.md`)。
|
||||
- **回归**:`foreign-oracle-{journal,names,failure}`、`foreign-{,session-}copy-code-refuse`、`tests/oracle_journal.rs`、applications 四场景、`verification/replay-policy`。
|
||||
- **文档**:`oracle-journal-values.md`;frontend-call / foreign-library 方向笔记。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **view notebook API**:`OnceLock` 初始化等待兼容 MSRV **1.81**(不再调用 ≥1.84 的 `wait`)。
|
||||
- JSON `float_roundtrip` 特征,减少外联浮点往返失真。
|
||||
|
||||
### Changed
|
||||
|
||||
- Bytecode compile/VM、foreign_doc/session、sema resolution、notebook interrupt 路径拆模块(行为对齐既有 Strong 契约)。
|
||||
|
||||
## v2.3.0 — 2026-11-01
|
||||
|
||||
### Highlights
|
||||
|
||||
**Foreign Strong(session / value / replay)**:会话句柄改为不透明 `handle`(不可 JSON 过桥、禁止 text 伪造);`close` 仿射消费(双 close / use-after-close 故障);`replay_check` 对照 oracle journal(旧 `replay_snapshot` 仅重跑保留);GFM 表行 arity 与列长映射拒绝静默补空;Ω 返回域外整数故障。对齐 PLDI Strong 叙事与 Lean SessionReg / \(V_{\mathsf{safe}}\)。CLI · wasm · ext **2.3.0**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——破坏面在宿主 foreign/session/JSON 与表解析纪律,不增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **`Value::Handle`**:`session_open` 返回句柄;session 操作拒绝 text 伪造。
|
||||
- **`DocumentSession::replay_check`** + API `/api/session/snapshot/replay_check`;snapshot 录音字段 + **`oracle_journal`**(与 execution journal 分名)。
|
||||
- **API** `/api/session/oracle_journal`。
|
||||
- **文档**:`doc/design/foreign-strong-correspondence.md`;`v-safe-json.md` 补 Handle / 列 arity / Ω 门。
|
||||
- **回归**:`foreign-session-{use-before-open,use-after-close,double-close,cold-replay-empty,isolation,handle-no-serialize,result-vsafe-refuse}`;`tests/errors/table-arity.mq.md`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 不等宽 GFM 表不再静默补空单元格;解析报 `table row arity mismatch`。
|
||||
- Py/Node session bootstrap:Ω 结果 OOD 整数不再 `default=str` 偷渡,宿主升级为故障。
|
||||
|
||||
### Changed
|
||||
|
||||
- **`session_close`**:未知 / 已关闭句柄 → 故障(不再返回 `False`)。
|
||||
- **`session_list`**:`id` 字段为 `handle`。
|
||||
- Snapshot export 含 `ok`/`code`/`stdout`/`result`/`source_hash` 与 `oracle_journal`。
|
||||
|
||||
## v2.2.2 — 2026-11-01
|
||||
|
||||
### Highlights
|
||||
|
||||
**\(V_{\mathsf{safe}}\) JSON 整数契约落地**:外联 / `json.parse` / `json.stringify` / `session_set` 等共用映射对齐 Lean ForeignJSON——`|n| > 2^{53}-1` 的 JSON 整数显式拒绝(错误前缀 `json: integer outside V_safe`),禁止 Node 路径静默扭曲;宽整数仍用十进制字符串 + 对端 `BigInt`。CLI · wasm · ext **2.2.2**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——宿主 JSON 契约与测试,不改 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **`doc/design/v-safe-json.md`**:宿主 ↔ Lean \(V_{\mathsf{safe}}\) 契约锁定(`MAX_SAFE`、encode/decode refuse、嵌套、float 为宿主扩展)。
|
||||
- **回归**:`tests/lib/json-vsafe-*`、`foreign-vsafe-*`、`foreign-session-vsafe-refuse`(含算术后越界 refuse)。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`src/host/json.rs`**:对域外整数与 `u64 > i64::MAX` 显式失败;不再经 `f64`/`Text` 静默降级。
|
||||
- **`doc/design/foreign-kernel.md`**:Int→number 仅当 `|n| ≤ 2^{53}-1`;宽整数走 string 桥。
|
||||
|
||||
### Changed
|
||||
|
||||
- 外联 JSON 桥与 `lib/json` 行为:OOD 整数从「可能静默失真」改为「诊断失败」。
|
||||
|
||||
## v2.2.1 — 2026-10-30
|
||||
|
||||
### Highlights
|
||||
|
||||
**view / 静态导出大纲侧栏修复**:带遮蔽(occlusion)语句的文档页里,Functions / Variables 右侧栏会掉到正文下面;中等窗口宽度下也会被错误叠成单列。CLI · wasm · ext **2.2.1**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——布局与 HTML 闭合修复,不改 Markdown 标记。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`marqdo view` / `view output`**:occlusion 行提前返回时未关闭 `.doc-block`,把 `#outline-rail` 嵌进 `document-surface`,侧栏排到文档下方;现已闭合并保留标注带。
|
||||
- **view 壳 CSS**:大纲折叠改为按主栏 `@container mq-panel` 宽度(32rem),不再用视口 `960px` 媒体查询把右侧栏压到正文下;极窄时大纲上移到文档上方。
|
||||
|
||||
## v2.2.0 — 2026-10-30
|
||||
|
||||
### Highlights
|
||||
|
||||
**函数级调用 `marqdo call`**:同一份 `.mq.md` 已经是文档、知识和程序。这一版补上从外部调用其中某个函数的入口。人继续读这一页;开发者、测试和 Agent 用同一条命令传入参数并执行。知识复用、把函数当工具、逐个函数做测试、改完再跑,都是这一入口的用法,不是另一套 Skill 系统。CLI · wasm · ext **2.2.0**。
|
||||
|
||||
```bash
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
# 5
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 --json
|
||||
```
|
||||
|
||||
**作用**:最小可执行单位从「整份文件」扩展到「文件里的一个函数」。不必为了试一个函数再写 `# main`、打印和包装程序。
|
||||
|
||||
**价值**:说明和实现仍在同一页。Agent 读函数旁边的叙述,定位函数,传入参数,得到可检查的结果。正式发布和权限仍走已有的项目验证;`call` 默认不开放写文件、进程、网络和插件。
|
||||
|
||||
说明页:[public/features/22-函数调用.mq.md](public/features/22-函数调用.mq.md) · [public/features/22-call.mq.md](public/features/22-call.mq.md)
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——新增的是 CLI 入口,不新增 Markdown 标记。`**…**` 仍是语句,`*…*` 仍是返回。
|
||||
|
||||
### Added
|
||||
|
||||
- **`marqdo call <文件.mq.md> <函数> [名字=值 ...]`**:加载该文件及其 import,按显示路径、SymbolId 或唯一短名定位函数,用现有签名和契约绑定参数,再用现有运行时执行。
|
||||
- **`--json`**:成功 `{"ok":true,"result":...}`,失败 `{"ok":false,"error":...}`,错误带诊断 `code`。`--backend tree|bytecode` 与 `marqdo run` 相同;指定函数时两个后端都不会改去跑 `# main`。
|
||||
- **默认纯函数**:效应含写入、网络、进程或插件时,执行前返回 `artifact.effect_denied`,副作用不会发生。
|
||||
- **参照文档** `examples/calculator.mq.md`,以及用户说明页 `public/features/22-*`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 官方语法说明与 Agent 语法卡的标记极性与解析器对齐:粗体是语句,斜体是返回。同步测试会实际运行说明里的调用示例。
|
||||
- Bytecode 的 `marqdo run --call-lib-path` 执行被点名的导入函数,不再忽略该参数去跑入口。
|
||||
- 隔离运行时冒烟测试补上 `InvokeContext.fs_root`,`--tests` 可以编过。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.2.0**。扩展包版本号对齐;这一版的新能力在 CLI。
|
||||
|
||||
## v2.1.5 — 2026-10-27
|
||||
|
||||
### Highlights
|
||||
|
||||
**Agent 可靠工作台 + EKC 热路径**:ResourceView(JSON/CSV/PDF/image `blob_ref`、locator 页/行)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制面与 execute 槽隔离。CLI · wasm · ext **2.1.5**。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.5 && cargo build --release
|
||||
marqdo ext add web # CDN / Releases → 2.1.5
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——工作台协议与 Agent 运行时合同,不新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **ResourceView v1**:有界 JSON/CSV 渲染;PDF/image `blob_ref`;`locator.page` / 行定位;CSV `text` 供 TablePreview。
|
||||
- **Agent 合同**:ToolSpec 注册与 authorize-before-call;CheckpointV2 原子 resume;AgentErrorV1;输出通道;ContextPackV2;EffectLedger(含 mutating `run_tool` 水印)。
|
||||
- **Workbench fixtures/schemas**:`tests/workbench_contracts` 协议金样例。
|
||||
- **EKC `ir.json` 快照**:`marqdo knowledge` 写入 `.marqdo/ekc/graph/ir.json`;查询命令暖机热加载,免全量重编译。
|
||||
- **`--refresh`**:`knowledge preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify` 可强制重编译。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **工程预检热路径**:`knowledge preflight`(及 find/reuse 等)默认不再每次 `ensure_compiled` 全量 compile,修复聊天「工程预检」墙钟过长。
|
||||
- **Web 槽隔离**:`short`/`read`/`control` 不再填满 execute 槽;disconnect≠cancel。
|
||||
- **CSV ResourceView**:去掉尾部空行伪影。
|
||||
|
||||
### Changed
|
||||
|
||||
- 查询类 knowledge CLI:**缺投影才 compile**;CI / 源变更请先 `marqdo knowledge` 或 `--refresh`。
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.5**。
|
||||
|
||||
## v2.1.4 — 2026-10-26
|
||||
|
||||
### Highlights
|
||||
|
||||
**默认隔离 HTTP execute(ADR 0009)**:`class=execute` / `sse-live` / `stream:true` 经 Supervisor worker 池(`marqdo run --call-lib-path`),父进程不再 `CallLibPath` 占 `INVOKE_LOCK`;短读 / 未声明非流式仍 `legacy_serial`(ADR 0008)。`/_runtime/*` 控制面;`runtime.isolated_execution=1`;MR-01 双 60s 假 SSE + 短读金样例。CLI · wasm · ext **2.1.4**。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.4 && cargo build --release
|
||||
marqdo ext add web # CDN / Releases → 2.1.4
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——隔离运行时与 Web execute 路径,不新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **默认隔离 execute(ADR 0009)**:HTTP `execute` / `sse-live` / `stream:true` 经 Supervisor worker 池(`marqdo run --call-lib-path`),父进程不再 `CallLibPath` 占 `INVOKE_LOCK`;可选 route `class`;`/_runtime/*` 控制面;`runtime.isolated_execution=1`。
|
||||
- **MR-01 金样例**:`tests/isolated_execute_mr01.rs` + `tests/ext/isolated-execute-site/`(双 60s 假 SSE + 短读并行;槽满拒绝);接入 `executable-knowledge` workflow。
|
||||
- **Worker CLI**:`marqdo run --call-lib-path` / `--fs-root` / `--args-json` / `--emit-result`;host `runtime` admit/dispatch/cancel/events。
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
- **compile 1000 门禁**:executable-knowledge / workbench 路径恢复与能力探测诚实(isolated 默认开启)。
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.4**。
|
||||
|
||||
## v2.1.3 — 2026-10-25
|
||||
|
||||
### Highlights
|
||||
|
||||
**知识工作台运行时合同(M00–M06)**:`ModelSelectionV1` / `RunContextV1` / `ModelCallUsageV1` / `DocumentViewV1` / locator / snapshot;严格 selection;usage null≠0;`view document` 只读嵌入;LLM messages + cancel;agent.step selection 继承假模型 e2e;USTC 兼容 live smoke(env 注入)。CLI · wasm · ext **2.1.3**。设计证据仍为 Partial(原生适配器 unavailable;完整宿主 F12 留给应用)。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.3 && cargo build --release
|
||||
marqdo ext add llm # CDN / Releases → 2.1.3
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——工作台合同与 View/LLM/Agent 扩展面,不新增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **Workbench M00–M06**:capabilities / selection / RunContext / usage / DocumentView / locator / SnapshotManifest;`tests/workbench_contracts`(含 F02 agent.step+resume、F14 并发);`marqdo view document --out` 只读 HTML 嵌入。
|
||||
- **LLM**:`messages=` / `selection=` / `strict_selection`;cancel token;reasoning_content 回退;双端点隔离门禁。
|
||||
- **Live**:`tests/workbench_live`(`OPENAI_*` env only;`MARQDO_EXT` 指向仓内 `ext/`)。
|
||||
- **Agent skeleton**:子工作簿禁 `llm.llm`,从 env selection `llm.create`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`llm.ask` 升参**:hoist `p` 避免缺参 `missing argument for parameter p`;避免 `~/.marqdo/ext` 陈旧包遮蔽仓内 `ext/`(测试强制 `MARQDO_EXT`)。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.3**。
|
||||
|
||||
## v2.0.0 — 2026-10-22
|
||||
|
||||
### Highlights
|
||||
@@ -41,6 +354,32 @@ marqdo ext add web # CDN → 2.0.0
|
||||
- **语料迁移(M7)**:`public/` `ext/` `tests/` `examples/` `doc/` 等语料加 `markup: occlusion`,改写 **80 个语料文件 / 256 处取元 / 23 处循环**;新增 `tests/ratchet` 锁定标签债务。
|
||||
- **文档**:遮蔽语法总纲 + M0–M10 变更记录、标签新鲜度 / 修复回路、函数作为值 6 篇评估、代码体量审计;`doc/design/code-volume-audit.md` 记 53k 行构成。
|
||||
|
||||
## v2.1.0 — 2026-10-23
|
||||
|
||||
### Highlights
|
||||
|
||||
**文件级可执行知识语义**:标准库、扩展库、示例与公开文档全部采用显式 `markup: occlusion`;`[描述](实现)` 成为默认链接语义,`access` 与 `遍历` 承担原有取元与循环职责。迁移工具可离线证明语法形状等价,Tree 与 Bytecode 均完成全量回归。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.0 && cargo build --release
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
**核心表面 Δ**:默认链接语义从 Classic 切换到 Occlusion。未迁移的旧 `[键](集合)` 仅可用 `markup: classic` 或一个版本周期内的 `marqdo run --legacy-markup` / `check --legacy-markup` 执行。
|
||||
|
||||
### Added
|
||||
|
||||
- **文件级新语义迁移**:`marqdo migrate labels --mark` 可把整个库/目录迁移到显式 `markup: occlusion`,即使文件没有旧式索引也不再依赖进程默认值。迁移验证为语法级、无导入解析依赖,并在写入前比较 Classic 与 Occlusion AST 形状。
|
||||
- **显式过渡入口**:`marqdo run --legacy-markup` 与 `marqdo check --legacy-markup` 可在一个版本周期内审阅未迁移的旧文件;环境变量不再改变语法。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 标准库、扩展库、示例、公开文档与可解析测试夹具迁移为文件级 Occlusion;旧的 `[键](集合)` 和 `- [项](集合)` 分别改为 `access` 与 `遍历`。
|
||||
|
||||
### Changed
|
||||
|
||||
- 未标注源码默认采用 Occlusion。Classic 仅能通过明确的 frontmatter 或 `--legacy-markup` 进入,避免同一文档因进程配置而静默改变含义。
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
@@ -49,6 +388,73 @@ marqdo ext add web # CDN → 2.0.0
|
||||
|
||||
### Changed
|
||||
|
||||
## v2.1.2 — 2026-10-24
|
||||
|
||||
### Highlights
|
||||
|
||||
**可执行知识生产消费链 + View 阅读体验发版门槛**:证据摘要进闭包/句柄;`artifact.verify` / `knowledge adjudicate` 结构化裁决;`artifact.reuse_execute` 与 `agent_eng_bind_execute` / `publish_gate` 实际复用(非 n-gram);`document.extract` 文本/Markdown + PDF/OCR 显式失败;View `KnowledgePresentation`、说明锚点、SSE `page_token` 过期包拒绝;上传 `max_bytes`;门禁 45 项(含 100/1000 单元)。CLI · wasm · ext **2.1.2**。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.2 && cargo build --release
|
||||
marqdo ext add web
|
||||
cargo test --offline --locked --test executable_knowledge
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删关键词**——语义/MLSP/View/Agent 宿主扩展;不改变默认 Occlusion 链接读法与表几何。
|
||||
|
||||
### Added
|
||||
|
||||
- **证据与闭包(F0/M02)**:来源 digests 进入 artifact/evidence/closure;business handle 改/删来源失效;锚点/可读性诊断。
|
||||
- **验证裁决(F0/M03)**:`artifact.verify` 结构化 `may_bind` / `may_publish`;policy 枚举;`knowledge adjudicate`;CLI `--fail`。
|
||||
- **语法 Skill(F0/M05)**:CORE SYNTAX 置顶;`migration-classic.md`;`skill_core_card` 与预算截断防护。
|
||||
- **绑定执行(F1/M04)**:`artifact.reuse_execute`;`agent_eng_bind_execute` + `eng_publish_gate`(`candidate_only` / product gate);host_query `mlsp`;`tests/ext/agent-eng-bind-gate.mq.md`。
|
||||
- **发布与来源(F2/M06–M07)**:统一 `EXCLUDED_DIRS`;`publish_manifest.json`;`function_sources` 函数级来源覆盖。
|
||||
- **文档提取(F3/M01)**:`document.extract` DocumentSource→ExtractedDocument;PDF/DOCX/OCR 显式 `failed`;超限截断 `partial`;Web 上传 `MaxBytesReader` / `LimitReader`。
|
||||
- **View V0–V3(子集)**:正文优先;no-exec;`KnowledgePresentation`(`semantic_generation` / `page_token` / `local_deps`);SSE 过期包拒绝与帧选择保留;print/响应式;1000 单元 compile smoke。
|
||||
- **故事门禁(M08)**:建库→复用→来源变更失效→修复重绑。
|
||||
|
||||
### Fixed
|
||||
|
||||
- View 说明链接 raw-string 截断;skill_brief / CORE SYNTAX 预算不被冲突旧规则吃掉。
|
||||
- 上传体积限制在 multipart 解析前生效(不再只靠内存 form 预算)。
|
||||
|
||||
### Changed
|
||||
|
||||
- CLI / wasm / `ext/VERSION` **同步 2.1.2**。
|
||||
- `tests/executable_knowledge` 门禁扩至 45 项;README 切片进度表与发版子集对齐。
|
||||
|
||||
## v2.1.1 — 2026-10-23
|
||||
|
||||
### Highlights
|
||||
|
||||
**可执行知识主链落地(S0–S6)**:BoundCall 双后端共享解析、正文 NarrativeRef、来源/适用期、digest 保护补丁与纯表达式提取、整代 `CURRENT` 投影与闭包摘要;订单发票示例双后端输出 `113`;离线门禁含 100 单元语料与 CLI 冒烟。
|
||||
|
||||
```bash
|
||||
git checkout v2.1.1 && cargo build --release
|
||||
marqdo ext add web
|
||||
marqdo run examples/executable-knowledge/docs/invoice-answer.mq.md
|
||||
```
|
||||
|
||||
**核心表面 Δ**:**无增删关键词**——同模块 `Type.member` 纳入 BoundCall;语义投影新增 `bound_calls` / `dynamic_calls` / `hashes.closure` / NarrativeRef 步骤;不改变默认 Occlusion 链接读法。
|
||||
|
||||
### Added
|
||||
|
||||
- **BoundCall / DynamicCall**:`sema::bind::resolve_for_exec`;Tree 与 Bytecode 静态路径对齐;`bound_calls.json` / `dynamic_calls.json`;同模块定义树路径绑定。
|
||||
- **NarrativeRef**:注释行 Markdown 链接 → `narrate` / `navigation` 步骤;围栏与行内代码不计步骤。
|
||||
- **来源与适用性**:frontmatter `sources` / `valid_until` → `evidence=sourced|expired|missing_source`;`artifact.bind policy=business`。
|
||||
- **局部编辑与提取**:MLSP `artifact.patch`(digest + wording 回滚);`artifact.extract_pure` 纯表达式预览。
|
||||
- **整代与闭包**:`generations/<id>/` + `CURRENT`;`hashes.closure` 随依赖变化;锁报告 `classes`。
|
||||
- **门禁**:`tests/executable_knowledge`(含 100 单元);CI `.github/workflows/executable-knowledge.yml`;项目扫描 depth/size/count 上限。
|
||||
- **示例**:`examples/executable-knowledge` 发票含税链可运行;负知识文档。
|
||||
|
||||
### Fixed
|
||||
|
||||
- Bytecode 裸名解析不再跨 import scope 误连同名函数;同模块 `Type.member` 写入 path_index 供兄弟调用。
|
||||
|
||||
### Changed
|
||||
|
||||
- Agent / reuse 发现结果标记 `discovery_only` + `bind_required` / `bind_targets`,不可把打分结果直接当可执行目标。
|
||||
|
||||
## v1.5.2 — 2026-10-18
|
||||
|
||||
### Highlights
|
||||
|
||||
Generated
+173
-15
@@ -186,6 +186,27 @@ dependencies = [
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "chrono-tz"
|
||||
version = "0.10.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cd6dd8046d00723a59a2f8c5f295c515b9bb9a331ee4f8f3d4dd49e428acd3b6"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"chrono-tz-build",
|
||||
"phf",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "chrono-tz-build"
|
||||
version = "0.4.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8f10f8c9340e31fc120ff885fcdb54a0b48e474bbd77cab557f0c30a3e569402"
|
||||
dependencies = [
|
||||
"parse-zoneinfo",
|
||||
"phf_codegen",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "chunked_transfer"
|
||||
version = "1.5.0"
|
||||
@@ -264,9 +285,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "crossbeam-utils"
|
||||
version = "0.8.21"
|
||||
version = "0.8.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
|
||||
checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
|
||||
|
||||
[[package]]
|
||||
name = "crypto-common"
|
||||
@@ -307,6 +328,12 @@ version = "0.3.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "780955b8b195a21ab8e4ac6b60dd1dbdcec1dc6c51c0617964b08c81785e12c9"
|
||||
|
||||
[[package]]
|
||||
name = "equivalent"
|
||||
version = "1.0.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826"
|
||||
|
||||
[[package]]
|
||||
name = "find-msvc-tools"
|
||||
version = "0.1.10"
|
||||
@@ -414,6 +441,12 @@ dependencies = [
|
||||
"wasi",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "hashbrown"
|
||||
version = "0.15.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
|
||||
|
||||
[[package]]
|
||||
name = "heck"
|
||||
version = "0.4.1"
|
||||
@@ -525,6 +558,16 @@ dependencies = [
|
||||
"quote",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "indexmap"
|
||||
version = "2.7.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8c9c992b02b5b4c94ea26e32fe5bccb7aa7d9f390ab5c1221ff895bc7ea8b652"
|
||||
dependencies = [
|
||||
"equivalent",
|
||||
"hashbrown",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "is_terminal_polyfill"
|
||||
version = "1.70.2"
|
||||
@@ -539,9 +582,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
|
||||
|
||||
[[package]]
|
||||
name = "js-sys"
|
||||
version = "0.3.104"
|
||||
version = "0.3.106"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0e0c1080212aad755ea003d18543e8768dd432c48819efd73a7bf1e39b7a5a3a"
|
||||
checksum = "7883d941dae510fb2d978fc3fe018c71c9e2892fd38854de3e8b92c2e5ad9cc5"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"futures-util",
|
||||
@@ -572,11 +615,12 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "2.0.0"
|
||||
version = "2.6.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
"chrono",
|
||||
"chrono-tz",
|
||||
"clap",
|
||||
"futures-util",
|
||||
"getrandom",
|
||||
@@ -589,6 +633,7 @@ dependencies = [
|
||||
"predicates",
|
||||
"pulldown-cmark",
|
||||
"regex",
|
||||
"serde",
|
||||
"serde_json",
|
||||
"sha1",
|
||||
"sha2",
|
||||
@@ -596,6 +641,7 @@ dependencies = [
|
||||
"tiny_http",
|
||||
"tokio",
|
||||
"tokio-tungstenite",
|
||||
"toml",
|
||||
"ureq",
|
||||
"zeroize",
|
||||
"zip",
|
||||
@@ -610,7 +656,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "2.0.0"
|
||||
version = "2.6.0"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
@@ -726,12 +772,59 @@ version = "1.70.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
|
||||
|
||||
[[package]]
|
||||
name = "parse-zoneinfo"
|
||||
version = "0.3.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1f2a05b18d44e2957b88f96ba460715e295bc1d7510468a2f3d3b44535d26c24"
|
||||
dependencies = [
|
||||
"regex",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "percent-encoding"
|
||||
version = "2.3.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
|
||||
|
||||
[[package]]
|
||||
name = "phf"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1fd6780a80ae0c52cc120a26a1a42c1ae51b247a253e4e06113d23d2c2edd078"
|
||||
dependencies = [
|
||||
"phf_shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "phf_codegen"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "aef8048c789fa5e851558d709946d6d79a8ff88c0440c587967f8e94bfb1216a"
|
||||
dependencies = [
|
||||
"phf_generator",
|
||||
"phf_shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "phf_generator"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
|
||||
dependencies = [
|
||||
"phf_shared",
|
||||
"rand",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "phf_shared"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "67eabc2ef2a60eb7faa00097bd1ffdb5bd28e62bf39990626a582201b7a754e5"
|
||||
dependencies = [
|
||||
"siphasher",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pin-project-lite"
|
||||
version = "0.2.17"
|
||||
@@ -970,6 +1063,15 @@ dependencies = [
|
||||
"zmij",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_spanned"
|
||||
version = "0.6.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
|
||||
dependencies = [
|
||||
"serde",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "sha1"
|
||||
version = "0.10.6"
|
||||
@@ -1004,6 +1106,12 @@ version = "0.3.10"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
|
||||
|
||||
[[package]]
|
||||
name = "siphasher"
|
||||
version = "1.0.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "33f4fe9184a62d842c9ef383018f3306d8ba224fd9d836f56d7288308847c256"
|
||||
|
||||
[[package]]
|
||||
name = "slab"
|
||||
version = "0.4.12"
|
||||
@@ -1151,6 +1259,47 @@ dependencies = [
|
||||
"tungstenite",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml"
|
||||
version = "0.8.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
|
||||
dependencies = [
|
||||
"serde",
|
||||
"serde_spanned",
|
||||
"toml_datetime",
|
||||
"toml_edit",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml_datetime"
|
||||
version = "0.6.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
|
||||
dependencies = [
|
||||
"serde",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml_edit"
|
||||
version = "0.22.27"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
|
||||
dependencies = [
|
||||
"indexmap",
|
||||
"serde",
|
||||
"serde_spanned",
|
||||
"toml_datetime",
|
||||
"toml_write",
|
||||
"winnow",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml_write"
|
||||
version = "0.1.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
|
||||
|
||||
[[package]]
|
||||
name = "tungstenite"
|
||||
version = "0.24.0"
|
||||
@@ -1290,9 +1439,9 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen"
|
||||
version = "0.2.127"
|
||||
version = "0.2.129"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70"
|
||||
checksum = "9bb54f33acc68fd454578d9820b0bde1a1a3d17aa17bb7b6595806d02886d409"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"once_cell",
|
||||
@@ -1303,9 +1452,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro"
|
||||
version = "0.2.127"
|
||||
version = "0.2.129"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1"
|
||||
checksum = "2e29d0c35b16e224a7eeb5cd2d25e3e1968fbd65604117b44d3b789d00ee8535"
|
||||
dependencies = [
|
||||
"quote",
|
||||
"wasm-bindgen-macro-support",
|
||||
@@ -1313,22 +1462,22 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro-support"
|
||||
version = "0.2.127"
|
||||
version = "0.2.129"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284"
|
||||
checksum = "6f501a8bc3719dba86ef8ae4728879c08001bea749eb1333ac5b91e040e2a6b7"
|
||||
dependencies = [
|
||||
"bumpalo",
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 2.0.119",
|
||||
"syn 3.0.3",
|
||||
"wasm-bindgen-shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-shared"
|
||||
version = "0.2.127"
|
||||
version = "0.2.129"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf"
|
||||
checksum = "23f0c9c52aa7cd7d77769a4cfe2a9adb1b331f489a41d912ce14513d5ab995c6"
|
||||
dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
@@ -1492,6 +1641,15 @@ version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
|
||||
|
||||
[[package]]
|
||||
name = "winnow"
|
||||
version = "0.7.15"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
|
||||
dependencies = [
|
||||
"memchr",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "zerocopy"
|
||||
version = "0.8.56"
|
||||
|
||||
+5
-2
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "2.0.0"
|
||||
version = "2.6.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -29,7 +29,8 @@ anyhow = "1"
|
||||
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
|
||||
clap = { version = "=4.4.18", features = ["derive"], optional = true }
|
||||
pulldown-cmark = "0.12"
|
||||
serde_json = "1"
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = { version = "1", features = ["float_roundtrip"] }
|
||||
thiserror = "1"
|
||||
tiny_http = { version = "0.12", optional = true }
|
||||
sha2 = { version = "=0.10.9", default-features = false }
|
||||
@@ -48,6 +49,8 @@ zip = { version = "=0.6.6", default-features = false, features = ["deflate"], op
|
||||
libloading = { version = "=0.8.6", optional = true }
|
||||
include_dir = "0.7"
|
||||
libc = { version = "0.2", optional = true }
|
||||
chrono-tz = "=0.10.0"
|
||||
toml = "=0.8.23"
|
||||
|
||||
[target.'cfg(target_arch = "wasm32")'.dependencies]
|
||||
# Custom entropy — no `js`/wasm-bindgen imports (raw mq_* ABI + marqdo-bridge.js).
|
||||
|
||||
@@ -4,12 +4,18 @@
|
||||
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
|
||||
|
||||
v2.2.0 起,`marqdo call` 可以直接调用这份文件里的一个函数。读的是同一页说明,跑的是同一个实现。知识因此可以当工具用,测试也不必再包一层 `# main`。
|
||||
|
||||
欢迎访问 [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)
|
||||
|
||||
---
|
||||
|
||||
标准库单文件本身就是手册:直接阅读[文件库](lib/文件.mq.md)、[集合库](lib/表.mq.md)等源码,按函数标题下的参数表、返回契约和动作说明调用;[工程实践](examples/stdlib-handbook/索引.mq.md)演示文件整理、CSV 汇总与文档维护。
|
||||
开发标准库和拓展库请直接阅读[可执行库开发指南](doc/library-development.mq.md):契约表、叙述式实现、遮蔽调用与多文件工程组织均有可运行示范。
|
||||
|
||||
|
||||
## 核心优势:可执行知识(Executable Knowledge)
|
||||
|
||||
> **Knowledge That Can Run —— 知识即可执行。**
|
||||
@@ -29,15 +35,97 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
| 真正的核心优势 | 说明 |
|
||||
|------|------|
|
||||
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
|
||||
| **函数即工具**<br>`marqdo call` | 最小可执行单位是文件中的函数,不只是整份文件。人阅读函数旁边的叙述;开发者、测试和 Agent 用 `marqdo call 文件 函数 名字=值` 执行它。知识复用、工具调用、函数级测试和局部改进是同一入口的四种用法。 |
|
||||
| **默认安全,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 +133,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 +152,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 +227,9 @@ Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。
|
||||
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
|
||||
```
|
||||
|
||||
`[]` 里是**自由描述**(不执行);`()` 里是**实现**(唯一执行)。这条语法叫**遮蔽**:
|
||||
把不可读或未完成的实现藏到括号里,人读描述、机器读代码。
|
||||
`[]` 里是**自由描述**(不执行);`()` 里是**目标**(唯一执行)。这条语法叫**链接语法**:
|
||||
目标是本地表达式时,就是**遮蔽**(把代码折叠在括号里);目标是 `类.函数` 时,就是**跨文档类调用**。
|
||||
v2.1 实现了文件级链接语义与可执行知识投影(见 [link-syntax.md](doc/design/link-syntax.md))。
|
||||
|
||||
**四条约定**
|
||||
|
||||
@@ -147,15 +242,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 +288,28 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v2.0.0)
|
||||
## 现状(v2.6.0)
|
||||
|
||||
- **遮蔽语法(v2.0.0)**:`[描述](实现)` 描述不执行 · `()` 内调用(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 遮蔽循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels` · 诊断 `label.missing` / `empty_payload` / `ref_dangling` · view 描述正文 + 代码片 + 桩徽章 · 扩展包同步 **2.0.0**
|
||||
- **标准库与拓展库手册(v2.6.0)**:61 份公开标准库、650 个函数;源码内参数/返回契约、叙述形参、句中遮蔽调用与真实工程。新增文件/字节/集合/Result/文档/HTTP/任务/TOML/时区工作流;多文件拓展库以 index 组织。
|
||||
- **View 可读动作与知识(v2.6.0)**:正文读动作,侧注看实现,运行标注看实际结果;空逻辑明确提示待补。知识说明先看输入、返回、依赖和依据,技术身份按需展开。
|
||||
- **Quantum / Web 工程实践(v2.6.0)**:可执行实验、会话句柄与双语门面;网页先递归拆布局,直到叶子可以直接用 Markdown 表达。CLI · wasm · ext · VS Code 扩展同步 **2.6.0**。
|
||||
|
||||
- **View 连线与工具栏(v2.5.1)**:真实源码锚点、连续 S 形曲线、错落标注与连线避让;底部工具栏增加文字标签。深浅色配色保持一致。CLI · wasm · ext 同步 **2.5.1**。
|
||||
|
||||
- **View 阅读界面(v2.5.0)**:暖白金色主题、新 Logo 与花枝装饰;真实执行信息左右引出、窄屏内联;导航/搜索/阅读设置/工具栏;重跑同步刷新与离线公式。CLI · wasm · ext 同步 **2.5.0**。
|
||||
|
||||
- **Oracle journal 语言值(v2.4.0)**:`foreign.oracle_journal` / `foreign.replay_check` 作普通值;handle/code 拒入 journal;bytecode/frontend 硬化;扩展包同步 **2.4.0**
|
||||
- **Foreign Strong(v2.3.0)**:会话 `handle`(不可过桥)· 仿射 close · `replay_check`/oracle journal · 表 arity refuse · Ω∈\(V_{\mathsf{safe}}\)。扩展包同步 **2.3.0**
|
||||
- **\(V_{\mathsf{safe}}\) JSON 整数(v2.2.2)**:外联与 `lib/json` 拒绝 `|n| > 2^{53}-1` 的 JSON 整数(对齐 Lean ForeignJSON);宽整数用十进制字符串 + Node `BigInt`。
|
||||
- **view 大纲侧栏(v2.2.1)**:修复 occlusion 文档与中等宽度下 Functions / Variables 掉到正文下方的问题;静态 `view output` 同源。
|
||||
- **函数级调用(v2.2.0)**:`marqdo call <文件.mq.md> <函数> 名字=值`。同一份文档给人读,也按函数执行;Tree 与 Bytecode 都跑被点名的函数,不回退到 `# main`。默认只执行纯函数。`--json` 给 Agent 读取结果或诊断。说明与价值见 [22-函数调用](public/features/22-函数调用.mq.md)。示例:`marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3` → `5`。扩展包同步 **2.2.1**
|
||||
- **Agent 可靠工作台(v2.1.5)**:ResourceView(JSON/CSV/PDF/image)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制与 execute 槽隔离;扩展包同步 **2.1.5**
|
||||
- **默认隔离 HTTP execute(v2.1.4 · ADR 0009)**:`execute` / `sse-live` / `stream:true` → Supervisor worker 池(`--call-lib-path`);父进程不再占 `INVOKE_LOCK`;`/_runtime/*`;`runtime.isolated_execution=1`;MR-01 金样例
|
||||
- **知识工作台运行时(v2.1.3)**:ModelSelection / RunContext / usage null≠0 · `view document` 只读嵌入 · LLM selection/messages/cancel · agent.step selection e2e · live smoke(设计 Partial:原生适配器 unavailable)
|
||||
|
||||
- **可执行知识生产链(v2.1.2)**:证据/闭包失效 · `verify`/`adjudicate` · `reuse_execute` / `eng_bind_execute`+`publish_gate` · `document.extract` · View `KnowledgePresentation`+SSE `page_token` · 上传限流 · 门禁 45 项(100/1000 单元)
|
||||
- **可执行知识主链(v2.1.1)**:BoundCall 双后端 · NarrativeRef · 来源/适用期 · `artifact.patch` / `extract_pure` · 整代 `CURRENT` + closure · 发票示例 `113`
|
||||
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock)
|
||||
- **外联 v3 P0/P1(v1.5.2)**:raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · `view capture` · Persist 按钮 · 扩展包同步 **1.5.2**
|
||||
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin;扩展包同步 **1.5.0**
|
||||
- **裸自增升参(v1.4.6)**:首次粗体赋值左值即声明;`**n = n + 1**` 无反引号也升为必选形参。扩展包仍为 **1.4.5**
|
||||
@@ -231,7 +345,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.6.0)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -246,14 +360,16 @@ 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.6.0 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
marqdo version --check
|
||||
|
||||
# 2) 跑解释器 / 文档站 / catalog
|
||||
# 2) 跑整个文件,或只调用其中一个函数
|
||||
marqdo run tests/structure/hello.mq.md
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 --json
|
||||
marqdo run tests/structure/hello.mq.md --backend bytecode
|
||||
marqdo view public --no-open
|
||||
marqdo debug public --no-open
|
||||
@@ -285,7 +401,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.6.0
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "2.0.0"
|
||||
version = "2.6.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"
|
||||
Vendored
+110
@@ -1,3 +1,113 @@
|
||||
marqdo (2.6.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Executable standard/extension handbooks and practical file/data/task tools.
|
||||
* Readable View action notes, knowledge contracts and offline reader support.
|
||||
* Preserve effect, platform and source compatibility boundaries.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sun, 08 Nov 2026 23:01:35 +0800
|
||||
|
||||
marqdo (2.5.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.5.1: exact source anchors, flowing annotation curves,
|
||||
staggered margin notes, connector avoidance and a labeled toolbar.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 07 Nov 2026 13:05:55 +0800
|
||||
|
||||
marqdo (2.5.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.5.0: redesigned document reader, margin execution annotations,
|
||||
offline math/assets, navigation/search, and consistent live result refresh.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 07 Nov 2026 10:00:00 +0800
|
||||
|
||||
marqdo (2.4.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.4.0: oracle journal as language values (foreign.oracle_journal /
|
||||
replay_check), bytecode/frontend hardening, MSRV 1.81 OnceLock wait fix.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Fri, 06 Nov 2026 15:15:00 +0800
|
||||
|
||||
marqdo (2.3.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.3.0: Strong foreign session — opaque Handle, affine close,
|
||||
replay_check vs oracle journal, table arity refuse, Omega V_safe gate.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 01 Nov 2026 14:45:00 +0800
|
||||
|
||||
marqdo (2.2.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.2: V_safe JSON integer contract on foreign/json bridge —
|
||||
refuse integers outside +/- (2^53-1); wide ints via decimal string.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Sat, 01 Nov 2026 09:45:00 +0800
|
||||
|
||||
marqdo (2.2.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.1: fix view/static-export outline rail under document
|
||||
(occlusion doc-block close + panel container query layout).
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 11:45:00 +0800
|
||||
|
||||
marqdo (2.2.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.0: marqdo call runs one named function in any .mq.md.
|
||||
The same file stays the document, the knowledge and the program.
|
||||
Tree and bytecode both execute that function. External calls stay
|
||||
pure: write, process, network and plugin stay off by default.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 09:20:00 +0800
|
||||
|
||||
marqdo (2.1.5-1ppa2) noble; urgency=medium
|
||||
|
||||
* Rebuild 2.1.5 against Launchpad (previous 1ppa1 failed with no build log).
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 09:35:49 +0000
|
||||
|
||||
marqdo (2.1.5-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.5: agent reliability workbench — ResourceView / ToolSpec /
|
||||
CheckpointV2 / EffectLedger; EKC ir.json warm-load; web short/read lanes.
|
||||
|
||||
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 07:39:08 +0000
|
||||
|
||||
marqdo (2.1.4-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.4: default isolated HTTP execute (ADR 0009) — Supervisor
|
||||
worker pool for execute/sse-live/stream, /_runtime/* control plane,
|
||||
MR-01 dual 60s SSE gold sample, runtime.isolated_execution=1.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Mon, 26 Oct 2026 10:00:00 +0000
|
||||
|
||||
marqdo (2.1.3-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.3: workbench M00–M06 runtime contracts (ModelSelection,
|
||||
RunContext, DocumentView, usage null≠0, LLM selection/cancel,
|
||||
agent.step selection e2e, view document CLI, live smoke).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sun, 25 Oct 2026 15:20:00 +0000
|
||||
|
||||
marqdo (2.1.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.2: executable-knowledge F0–F3 + View V0–V3 release bar
|
||||
(evidence/closure, verify gates, bind/reuse_execute, document.extract,
|
||||
KnowledgePresentation, SSE page_token, upload max_bytes).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Sat, 24 Oct 2026 14:50:00 +0000
|
||||
|
||||
marqdo (2.1.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.1: executable-knowledge spine (BoundCall, NarrativeRef,
|
||||
sources/applicability, generation CURRENT + closure digests).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 15:40:00 +0000
|
||||
|
||||
marqdo (2.1.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.1.0: file-scoped Occlusion is the default syntax; migrated
|
||||
standard/extension libraries and executable-knowledge projections.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 12:00:00 +0000
|
||||
|
||||
marqdo (2.0.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.0.0: Occlusion syntax — [description](payload), where the
|
||||
|
||||
+27
-2
@@ -13,10 +13,26 @@
|
||||
|
||||
## 当前文档
|
||||
|
||||
> **可执行知识下一阶段的阅读顺序**:[原始意图 009](next/009.md) → [文档原生开发指导](design/document-native-development-guide.md)(作者体验、语法审查结论、AI 工作协议)→ [详细开发规范](next/Marqdo_Executable_Knowledge_Development.md)(目标语义与工程约束)→ [缺口与交付路线](roadmap/executable-knowledge-gaps-2026-10-23.md)(现状证据、S0–S6)。指导文档修订作者负担、场景政策和交付次序;不得把所有内部治理字段变成作者必填项。与之冲突的早期设计只作历史参考,设计目标不等于已实现能力。
|
||||
>
|
||||
> **可执行知识门禁**:[tests/executable_knowledge/](../tests/executable_knowledge/README.md) — S0–S2 BoundCall / 效应 / MLSP bind,以及后续 NarrativeRef、来源与整代投影子集;`cargo test --test executable_knowledge --locked`(CI:`.github/workflows/executable-knowledge.yml`)。`status: design` / 预期失败与已实现分开报告。
|
||||
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
|
||||
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 草案:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断** |
|
||||
| [roadmap/agent-reliability-crossrepo-2026-10-27.md](roadmap/agent-reliability-crossrepo-2026-10-27.md) | **Proposed:跨仓 Agent 可靠性开发计划**;M-A0–M-A6 ∥ Q-A0–Q-A7 排期、依赖图、F01–F20 映射、MA-T*/QA-* 验收与第一刀切片;协议真源仍见下方设计文档 |
|
||||
| [design/agent-reliability-tools-resources-2026-10-27.md](design/agent-reliability-tools-resources-2026-10-27.md) | **Proposed:智能体能力补足**;基于 `16f26d7`,增量设计错误恢复、检查点/效应账本、结构化工具、输出通道、上下文与只读资源视图;含跨仓边界、阶段计划和故障验收 |
|
||||
| [research/agent-capabilities-2026-10-27.md](research/agent-capabilities-2026-10-27.md) | **官方能力调研与源码复核**;OpenAI/Claude/Gemini/LangGraph/Deep Agents/MCP,求道当前问题 F01–F20;区分现有能力、设计推导与待实测项 |
|
||||
| [design/isolated-web-runtime-development-2026-10-26.md](design/isolated-web-runtime-development-2026-10-26.md) | **隔离执行与响应式 Web 运行时**:进程池、控制/读取分离、取消、事件恢复、发布一致性;实现见 `src/runtime/` |
|
||||
| [adr/0009-isolated-web-runtime.md](adr/0009-isolated-web-runtime.md) | **ADR 0009**:隔离 Web 运行时决策;金样例通过后替代 ADR 0008 的并行性结论 |
|
||||
| [跨库缺陷复核(2026-10-26)](../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md) | **最新源码与测试证据**:实际 HTTP 路由、知识发布/阅读断点、旧缺陷处置及 1000 单元编译性能失败;需同级 qdagent checkout |
|
||||
| [design/qdagent-workbench-runtime-and-view-2026-10-25.md](design/qdagent-workbench-runtime-and-view-2026-10-25.md) | **qdagent 知识工作台框架支持**:M00–M05 合同落地中(`src/workbench/`、MLSP `capabilities` / `view.document` / `view.reference_resolve`、`tests/workbench_contracts.rs`);完整 verified 以切片验收证据为准 |
|
||||
| [design/view-knowledge-reading-experience-2026-10-24.md](design/view-knowledge-reading-experience-2026-10-24.md) | **View 知识阅读体验重设计(建议)**:正文优先、结构导航、就地知识说明、来源与运行状态、响应式线框、实现契约与验收;含当前呈现和 no-exec 反例 |
|
||||
| [design/view-readable-actions.md](design/view-readable-actions.md) | **View 阅读优化实现**:动作留在正文、实际逻辑引到侧注、空逻辑明确标识;语法阅读指南、输入输出与依据卡片、单文件依赖分析及浏览器验收 |
|
||||
| [roadmap/qdagent-knowledge-support-gaps-2026-10-24.md](roadmap/qdagent-knowledge-support-gaps-2026-10-24.md) | **求道知识沉淀与文档编译支撑缺口**:2.1.1 源码复核、来源/依赖失效反例、验证与 Agent 协议、语法提示词、导入底座及跨库分工 |
|
||||
| [design/document-native-development-guide.md](design/document-native-development-guide.md) | **下一阶段开发指导**:语法审查裁决、正文→命名→复用工作流、AI 上下文与局部编辑、渐进严格、作者成本及 S0–S6 验收 |
|
||||
| [design/core-surface.md](design/core-surface.md) | **核心构造清单**:v2.1 默认链接/循环说明与构造守卫;不是全部实现状态清单 |
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **历史 v0.2 映射**:不再代表现行默认链接语义 |
|
||||
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 设计背景**:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断;链接语义以 v2.1 规范和测试为准 |
|
||||
| [adr/0005-prose-unified-markup.md](adr/0005-prose-unified-markup.md) | **Proposed:采纳 mapping v0.3** |
|
||||
| [roadmap/markup-v0.3.md](roadmap/markup-v0.3.md) | **Markup v0.3 实现路线(M0–M5)** |
|
||||
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
|
||||
@@ -33,6 +49,7 @@
|
||||
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置函数** |
|
||||
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
|
||||
| [design/module-namespace.md](design/module-namespace.md) | **模块命名空间:导入绑定库名、`库.成员` / `use`(M1+M2 已落地)** |
|
||||
| [library-development.mq.md](library-development.mq.md) | **可执行库开发指南**:单文件标准库、多文件拓展库、叙述超过 50%、标题下参数与返回表、句中赋值/返回和遮蔽调用;含真实调用及失败场景 |
|
||||
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** |
|
||||
| [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** |
|
||||
| [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** |
|
||||
@@ -106,6 +123,13 @@
|
||||
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
|
||||
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
|
||||
| [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 |
|
||||
| [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 |
|
||||
| [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 |
|
||||
| [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 |
|
||||
| [next/Marqdo_Executable_Knowledge_Testing.md](next/Marqdo_Executable_Knowledge_Testing.md) | **可执行知识语法测试与兼容性规程**:标准库、扩展库、CLI、Tree/Bytecode 的仓库级门禁 |
|
||||
| [roadmap/executable-knowledge-gaps-2026-10-23.md](roadmap/executable-knowledge-gaps-2026-10-23.md) | **v2.1 现状与规划缺口审计(方向修订)**:保留 G01–G12 代码证据,以可读步骤、确定执行、早期 AI 复用和局部修改重排 S0–S6,严格治理按场景增加 |
|
||||
| [../tests/executable_knowledge/README.md](../tests/executable_knowledge/README.md) | **S0 作者基线门禁**:六类任务语料、作者成本计数、预期失败与 Bytecode 同名误连缺陷指纹 |
|
||||
| [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 |
|
||||
| [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 |
|
||||
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
|
||||
| [design/label-freshness-and-repair.md](design/label-freshness-and-repair.md) | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 |
|
||||
@@ -114,6 +138,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/)。
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
# ADR 0008:Web 热路径单解释器串行化(设计缺陷与缓解)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted**(缺陷已记录;缓解已落地;真并行见 [ADR 0009](0009-isolated-web-runtime.md)) |
|
||||
| Date | 2026-10-26 |
|
||||
| Related | [web-invoke-serialization.md](../design/web-invoke-serialization.md) · [ADR 0009](0009-isolated-web-runtime.md) · ADR [0004](0004-web-plugin-go.md) · ADR [0007](0007-web-document-endpoint.md) · [ext-abi.md](../design/ext-abi.md) · [ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- Go `plugins/web` 的 HTTP 服务是**多 goroutine** 的:每个请求可并发进入 `handleInvoke` / `handleInvokeLiveSSE`。
|
||||
- 每个 Endpoint 最终经 C ABI `host_query("call_lib_path", …)` 回到 Rust 宿主,在**同一个** `HostContext`(Marqdo 解释器状态)上执行作者 `.mq.md`。
|
||||
- `HostContext` **不是** `Sync`:共享可变会话、库装载、写回、事件总线等状态不能安全地被多线程同时求值。
|
||||
- 因此宿主用进程级 `INVOKE_LOCK`(`src/host/plugin.rs`)串行化所有来自 worker 线程的 `call_lib_path`。
|
||||
|
||||
### 常见误解
|
||||
|
||||
> 「web 都是单线程的吗?不能多线程吗?」
|
||||
|
||||
| 层 | 并发模型 |
|
||||
|----|----------|
|
||||
| Go HTTP / SSE flush / 取消 | **多线程(多 goroutine)** |
|
||||
| Marqdo 解释器 `call_lib_path` | **单飞(一把全局锁)** |
|
||||
| 浏览器 UI | 与后端锁无关;但若短 API 同步阻塞等待锁,会表现为「整页卡死」 |
|
||||
|
||||
**缺陷不在「HTTP 单线程」,而在「多 HTTP 工作线程共享一个非 Sync 解释器」。**
|
||||
真并行需要多解释器实例(或可共享的隔离运行时),不是去掉 Go 侧并发。
|
||||
|
||||
### 事故形态(已观测)
|
||||
|
||||
长对话(`return=sse-live` / `stream:true`)在 `CallLibPath` 期间一直持有 `INVOKE_LOCK`。并发的短路由(如 `/v1/models`、设置页探测)在旧实现里对锁 **无限期** `lock()`,HTTP 挂起 → 前端 `fetch` 无超时 → 页面无响应。重启进程可恢复,但属于运维掩盖,不是正确错误处理。
|
||||
|
||||
## Decision
|
||||
|
||||
1. **承认并文档化**本限制为宿主架构缺陷(单 `HostContext` + 全局 `INVOKE_LOCK`),不得再被表述为「web 插件只能单线程」。
|
||||
2. **缓解(已实现,非根治)**:
|
||||
- `call_lib_path` 从 worker 进入时用 **限时 try-lock**(默认 `MARQDO_INVOKE_WAIT_MS=1500`),超时返回错误串 `interpreter busy: …`。
|
||||
- Go `handleInvoke` 将含 `interpreter busy` 的错误映射为 **HTTP 503**,并设 `Retry-After: 2`。
|
||||
- **禁止**在 SSE 期间把进程级 `MARQDO_INVOKE_WAIT_MS` 拉长:那会让并发短请求重新卡死。
|
||||
- 长 SSE 在启动时用同一短预算争锁;一旦拿到则持有至调用结束(对话本来就要跑完)。
|
||||
3. **客户端契约**:短 API 必须有超时与 503 文案;不得假设「任意时刻都能同步进入解释器」。
|
||||
4. **根治(未决,另案)**:解释器池 / per-request isolate / 可 `Send` 的会话切片。未落地前,产品行为以本 ADR 的 503 语义为准。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- 对话进行中,设置/模型列表等短请求约 1.5s 内失败并可读,UI 不再无限挂起。
|
||||
- 缺陷有名有姓,后续多解释器工作不会被「修好了」的假象挡住。
|
||||
|
||||
### Negative / Risks
|
||||
|
||||
- 同一进程仍无法真正并行跑两个 Marqdo Endpoint 体;第二个长 SSE 也会在短预算后失败。
|
||||
- 极短窗口内,短请求若正好撞上锁交接,可能偶发 503(可重试)。
|
||||
- `MARQDO_INVOKE_WAIT_MS` 是进程环境变量;误设过大仍会复现卡顿。
|
||||
|
||||
### Neutral
|
||||
|
||||
- Go 多 goroutine、SSE 桥(`MARQDO_EVENT_FORWARD`)、取消令牌(`MARQDO_CANCEL_TOKEN`)保持不变。
|
||||
- 不改变 Document / Endpoint 作者面(ADR 0007);只约束宿主与 web 插件错误语义。
|
||||
|
||||
## Implementation pointers
|
||||
|
||||
| 位置 | 职责 |
|
||||
|------|------|
|
||||
| `src/host/plugin.rs` → `acquire_invoke_lock` | 限时争锁;失败 `set_err("interpreter busy…")` |
|
||||
| `plugins/web/.../routes_invoke.go` → `handleInvoke` | `interpreter busy` → 503 + `Retry-After` |
|
||||
| 设计长文 | [web-invoke-serialization.md](../design/web-invoke-serialization.md) |
|
||||
@@ -0,0 +1,33 @@
|
||||
# ADR 0009: Isolated Web Runtime (worker process pool)
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**;HTTP **execute** 路径正式替代 [ADR 0008](0008-web-invoke-serialization.md) 的并行性结论。`legacy_serial`(未声明且非流式)仍引用 0008 单飞 / 父进程 `CallLibPath`。 |
|
||||
| 日期 | 2026-10-26(修订 2026-10-27:disconnect≠cancel;control/read/short 无父锁) |
|
||||
| 设计 | [isolated-web-runtime-development-2026-10-26.md](../design/isolated-web-runtime-development-2026-10-26.md) |
|
||||
| 金样例 | `tests/isolated_execute_mr01.rs`(MR-01 双 60s SSE + short reads;同文件 MR-02 槽满拒绝;disconnect-keeps-running;control-under-dual-execute) |
|
||||
|
||||
## 背景
|
||||
|
||||
ADR 0008 确认:Go HTTP 多线程,但所有 Endpoint 共享一把解释器锁与进程级 SSE 桥环境变量。1500ms busy → 503 只是缓解,不是并行。
|
||||
|
||||
## 决策
|
||||
|
||||
1. **首选架构**:预热的一次性 Marqdo worker 进程池;每个租约独占一个进程与 HostContext。
|
||||
2. **HTTP 默认**:`class=execute` 或 `return=sse-live` / body `stream:true` → `admit` → `dispatch`(`--call-lib-path` worker);**禁止**父进程 `CallLibPath` / `Setenv` / `legacySSEBridgeMu`。声明的 `short`/`read`/`control` 走父进程短路径(execute 已离进程,父锁通常空闲);未声明非流式 → `legacy_serial`。
|
||||
3. **控制/读取分离**:`/_runtime/*`(cancel、events、task get)不进入解释器锁。短读勿挤占 execute worker 槽(池默认 2);产品 cancel 优先 `/_runtime`。
|
||||
4. **订阅 ≠ 取消**:`sse-live` 观察者 `ctx.Done()` 默认**只结束订阅**,不 `runtime.cancel`;后台仍 reap worker 以释放槽。仅显式 header `X-Marqdo-Cancel-On-Disconnect: 1` 才 disconnect=cancel。同步 `waitIsolatedJSON` 可保留 disconnect 取消。重连:`GET /_runtime/tasks/{id}/events` + `Last-Event-ID` / `after_seq`。
|
||||
5. **协议**:`InvokeRequestV2` / worker env + NDJSON `MARQDO_EVENT_FORWARD` + `--emit-result`(首期);`/_runtime/*` 控制面。
|
||||
6. **能力探测**:`runtime.isolated_execution=1`、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`、`runtime.read_lane=1`(短读不与 execute 抢父锁)。
|
||||
7. **发布**:`expected_generation` CAS + publish journal;逻辑文档 ID 与物理 generation 路径解耦。
|
||||
|
||||
## 后果
|
||||
|
||||
- Execute / live SSE 不再抢进程级 SSE 桥;双流可并行(MR-01)。
|
||||
- 短读走父进程:在 dual execute 下通常仍 200(父锁空闲);勿把 short/read/control 塞进 2 槽 execute 池。
|
||||
- Legacy 未声明非流式路径仍可走父进程锁(ADR 0008)。
|
||||
- 产品(qdagent)`turn_events` / Last-Event-ID / cancel CAS 接线由 qdagent 验收;框架侧 disconnect≠cancel 与 `/_runtime` 无锁控制面已落地。
|
||||
|
||||
## 验收(摘要)
|
||||
|
||||
MR-01 绿:双假上游 60s 流不混字、短读全 200、两 worker `--call-lib-path`、第三路槽满 429/503、`runtime.isolated_execution=1`、`runtime.read_lane=1`。观察者断连后任务仍跑完并可经 `/_runtime` 重放。其余见设计文档 §12。
|
||||
@@ -0,0 +1,348 @@
|
||||
# Marqdo 智能体能力补足:恢复、工具、上下文与资源视图
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Proposed**;本次交付设计,不代表以下新接口已实现 |
|
||||
| 日期 / 基线 | 2026-10-27(Asia/Shanghai);Marqdo `16f26d7` / 2.1.4;qdagent `68b757e` |
|
||||
| 调研与现状 | [官方资料与源码证据 F01–F20](../research/agent-capabilities-2026-10-27.md) |
|
||||
| 产品配套 | [qdagent 智能体能力与预览设计](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
|
||||
| 继承 | [ext/agent](ext-agent.md)、[隔离 Web 运行时](isolated-web-runtime-development-2026-10-26.md)、[工作台合同](qdagent-workbench-runtime-and-view-2026-10-25.md) |
|
||||
|
||||
## 1. 目标与架构边界
|
||||
|
||||
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;让工具可发现、可验证、可审计;让结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位,不把框架改成第二套产品聊天服务。
|
||||
|
||||
现有 `src/runtime/` 已实现隔离进程、任务/事件与控制通道,本设计在其上补 Agent 步骤语义。现有 `ext/ai/agent.mq.md` 已有 step/plan/run、CALL/READ、观察压缩,继续扩展。框架不持有求道“笔记”业务表、中文按钮、默认回答字数或具体供应商账户。
|
||||
|
||||
| 议题 | Marqdo 所有 | qdagent 所有 |
|
||||
|---|---|---|
|
||||
| 恢复 | 错误分类、预算、检查点、工具效应、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
|
||||
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
|
||||
| 回答 | 结果分通道、输出预算、角色消息、finish reason | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD 行为 |
|
||||
| 资源 | ResourceRef、只读内容/派生预览、定位、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览组件和布局 |
|
||||
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
|
||||
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
APP[qdagent 产品策略与授权] --> RUN[ext/ai/agent step / plan / run]
|
||||
RUN --> CTX[ContextPack 与预算]
|
||||
RUN --> LLM[LLM Adapter]
|
||||
RUN --> DISPATCH[Tool Dispatcher]
|
||||
DISPATCH --> LOCAL[受控 Marqdo 函数]
|
||||
DISPATCH --> MCP[MCP Client]
|
||||
DISPATCH --> RES[资源读取 / 转换]
|
||||
RUN --> REC[Checkpoint / Effect Ledger]
|
||||
REC --> RT[既有 runtime task store / event log]
|
||||
RUN --> OUTPUT[answer / artifact / progress / diagnostic]
|
||||
RES --> VIEW[DocumentView / ResourceView]
|
||||
OUTPUT --> APP
|
||||
VIEW --> APP
|
||||
```
|
||||
|
||||
## 2. 现状与增量
|
||||
|
||||
| 已有能力 | 本轮不能误判为缺失 | 要补的具体语义 |
|
||||
|---|---|---|
|
||||
| runtime.task_control_v2/event_replay/read_lane | 不再新建一套队列与 SSE 框架 | Agent 步骤恢复与传输重放的边界 |
|
||||
| resume_save/load | 不再新建平行 checkpoint 命名空间 | 原子提交、版本摘要、作用域、效应关联 |
|
||||
| CALL、ARGS、READ、plan patch | 不废弃文档式编排 | 类型化 schema、校验错误、有限修复、稳定 call_id |
|
||||
| MCP stdio client | 不从零重写连接器 | timeout/cancel、resource、远程 transport 的能力探测 |
|
||||
| DocumentViewV1 / Locator | 不另写 `.mq.md` 解析器 | 普通资源类型、明确 renderer、历史与相对资源处理 |
|
||||
| LLM messages/usage | 不把 provider 行为交给产品猜测 | 输出预算、原生工具适配探测、角色边界与分通道 |
|
||||
|
||||
新模块路径及协议名以下均是**建议落点**。首批开发先固化 schema 与 fixture,再开放 feature bit;不得只更新 capabilities 把未实现能力标真。
|
||||
|
||||
## 3. 错误和恢复合同
|
||||
|
||||
### 3.1 ErrorV1
|
||||
|
||||
现有字符串错误保留兼容适配,新工具与 Agent 结果返回:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentErrorV1",
|
||||
"code": "tool.timeout",
|
||||
"category": "transient",
|
||||
"stage": "tool",
|
||||
"message": "读取资源超时",
|
||||
"retryable": true,
|
||||
"retry_after_ms": 1200,
|
||||
"effect_state": "none",
|
||||
"recovery_action": "retry_step",
|
||||
"call_id": "call_01",
|
||||
"details_ref": "resource:diagnostic_01"
|
||||
}
|
||||
```
|
||||
|
||||
`retryable` 仅是候选信息,最终动作由可信策略结合效应、截止时间、预算、取消状态决定。远端工具声称 readOnly/idempotent 不构成授权依据。凭证和原始堆栈不进入公开 message。
|
||||
|
||||
| 错误类别 / 例子 | 框架动作 | 不允许的动作 |
|
||||
|---|---|---|
|
||||
| transient:429、部分 5xx、连接失败 | 只在安全步骤重试,遵守 Retry-After | 无限重试、复用同一流片段直接追加 |
|
||||
| invalid_arguments:schema 不匹配 | 把字段级错误作为 observation,最多 1 次参数修复 | 启动工具后才校验;静默丢弃字段 |
|
||||
| validation_failed:编译/文档校验 | 保留候选与诊断,局部修复后重新验证 | 将未验证草稿标为成功 |
|
||||
| context_overflow | 压缩可重建上下文,保留任务/限制/未决效应 | 丢失最新用户指令、授权或版本 |
|
||||
| auth / forbidden | 直接 needs_input/blocked,交应用处理 | 换身份、扩大范围或匿名绕过 |
|
||||
| conflict / stale_revision | 重新读取版本并重新规划 | 覆盖用户修改、对写操作盲重试 |
|
||||
| capability_unavailable | 返回可行替代操作清单 | 假称已搜索、已渲染或已执行 |
|
||||
| policy_denied | 显式拒绝该动作 | 把限制当工具错误让模型规避 |
|
||||
| budget_exhausted | 保存状态与已完成结果,返回 partial | 自动增预算或伪造 completed |
|
||||
| unknown_effect / worker_crash | 对账、查询外部状态,不能判断则 needs_reconciliation | 重跑整个工作簿 |
|
||||
| cancelled | 停止新调用、保留可读产物、传播取消 | 在后台悄悄修复或恢复 |
|
||||
|
||||
初始建议:传输最多 2 次重试(总 3 次尝试),指数退避基准 0.5/1 秒并加 jitter;有 Retry-After 时使用服务端建议并受总 deadline 限制。参数修复最多 1 次,内容修复最多 2 次。预算由应用传入,框架只提供默认上限与执行机制。所有重试、修复和摘要模型调用计入同一成本账本。
|
||||
|
||||
错误指纹 `hash(tool_id, normalized_arguments, error_code, relevant_revision)` 连续出现 2 次且没有新证据时中止该策略,允许一次有依据的替代路径;不能通过改写错误文本绕过循环检测。
|
||||
|
||||
### 3.2 四类“恢复”必须分开
|
||||
|
||||
1. **续订事件**:客户端从 cursor 重放和订阅同一个 task,不发起新推理。
|
||||
2. **重试步骤**:相同逻辑 operation、同幂等键;新 invocation attempt,复用成功的前序结果。
|
||||
3. **恢复工作流**:从兼容 checkpoint 建立新 runtime task / attempt,关联 `resumed_from`,不把旧终态改回 running。
|
||||
4. **重新生成答案**:新的输出版本;已有成功工具结果可复用,用户明确重新执行才重新产生效应。
|
||||
|
||||
当前 TaskState 把 interrupted/needs_reconciliation 视为终态,沿用此约定。新增 `AgentRun` 逻辑关联只管理目标和 attempt 链;调度权仍在原 runtime。恢复请求带 `expected_revision`、checkpoint digest 与幂等键,相同请求返回同一新 attempt,冲突返回 409 对应的框架错误。
|
||||
|
||||
执行失败不必丢掉有用内容:`outcome.status = succeeded | partial | failed | needs_input | cancelled`,伴随 `answer_ref/artifacts/error/recovery_options`。HTTP 调用成功与 Agent 业务 succeeded 不再混为同一字段。
|
||||
|
||||
## 4. 检查点与工具效应
|
||||
|
||||
### 4.1 CheckpointV2
|
||||
|
||||
在 `plugins/agent/src/resume.rs` 扩展已有实现,统一根目录由宿主提供,客户端不能传任意绝对路径。保留 legacy load,但旧 checkpoint 无效应信息时默认 `manual_review`,不能自动重做写操作。
|
||||
|
||||
| 字段组 | 内容 |
|
||||
|---|---|
|
||||
| 身份 | schema、checkpoint_id、logical_run_id、task_id、attempt_id、step_id、parent_checkpoint_id |
|
||||
| 作用域 | principal_ref、workspace_id、session_id、授权 scope digest |
|
||||
| 输入 | task revision、workbook revision/hash、输入资源 revisions、knowledge generation |
|
||||
| 运行配置 | ModelSnapshot public ref、tool registry digest、policy revision、runtime compatibility |
|
||||
| 进度 | completed_steps、pending_operation、observation refs、context summary ref |
|
||||
| 约束 | 剩余 token/tool/time/cost 预算、deadline、cancel epoch |
|
||||
| 一致性 | effect ledger watermark、event seq、manifest digest、committed_at |
|
||||
|
||||
写入协议:写唯一临时文件→flush/fsync→原子 rename→提交 checkpoint 指针;持久化配置下目录 fsync 按平台支持实现。所有引用 blob 在指针提交前落盘。损坏记录报 `checkpoint.corrupt` 并尝试上一个完整版本,不能读取半个 JSON 当无历史。
|
||||
|
||||
恢复前校验身份/授权、源版本、工具 schema 与模型兼容性。权限撤销立即生效;checkpoint 不是永久授权。源文件改变返回 `checkpoint.input_changed`,重新计划受影响步骤,不能偷偷使用最新文件继续旧验证结果。
|
||||
|
||||
### 4.2 Effect ledger
|
||||
|
||||
```text
|
||||
prepared → started → committed
|
||||
↘ failed_no_effect
|
||||
↘ unknown → reconciled_committed | reconciled_no_effect | needs_input
|
||||
```
|
||||
|
||||
每个 operation 持久记录 `operation_id/idempotency_key/args_digest/resource_scope/expected_revision/effect_class/result_ref`。幂等键作用域是 principal + workspace + logical_run + step + operation,不用随机 attempt ID 替换稳定 operation key。对同 key 不同 payload 拒绝。
|
||||
|
||||
读工具可重试;确定幂等写由服务端去重;可补偿写仅在补偿明确安全时执行;未知写先查询 receipt/版本。对外部系统不能承诺通用 exactly-once。关键 crash 窗口是“远端已成功、本地尚未记账”,必须返回 unknown 并对账。
|
||||
|
||||
本地文件使用 expected revision + staging + atomic replace;变更提交后检查点失败也靠 operation receipt 恢复。`tool.completed` 必须在结果与 receipt 可读取后提交,再对外发事件。事件发送失败不回滚已发生的业务效应。
|
||||
|
||||
不要复制 runtime 事件存储:Agent ledger 与 artifact manifest 是步骤事实,现有 runtime event log 是传输/调度事实;以 ID 关联,采用可重建投影与 outbox。跨 DB/文件不能声称一个事务完成,使用 manifest 提交点和恢复扫描补齐索引。
|
||||
|
||||
## 5. 结构化工具与调度
|
||||
|
||||
### 5.1 ToolSpecV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ToolSpecV1",
|
||||
"id": "workspace.read",
|
||||
"version": "1",
|
||||
"description": "读取授权资源的指定行范围",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"resource_id": {"type": "string"},
|
||||
"revision": {"type": "string"},
|
||||
"start_line": {"type": "integer", "minimum": 1},
|
||||
"max_lines": {"type": "integer", "minimum": 1, "maximum": 500}
|
||||
},
|
||||
"required": ["resource_id"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"output_schema_ref": "ResourceReadV1",
|
||||
"effect": "read",
|
||||
"scopes": ["workspace:read"],
|
||||
"timeout_ms": 10000,
|
||||
"max_result_bytes": 65536,
|
||||
"idempotency": "safe",
|
||||
"concurrency_group": "resource-read",
|
||||
"availability": "ready"
|
||||
}
|
||||
```
|
||||
|
||||
定义由宿主/可信模块注册;用户认证、scope 与资源根由宿主注入,不接受模型提供 principal 或任意 root。`read`、`write`、`execute`、`external_write` 是策略分类,不是靠工具命名推断。
|
||||
|
||||
ToolCallV1:`call_id/tool_id/tool_version/arguments/operation_id/parent_span_id`。ToolResultV1:`ok/status/summary/structured_content/resources/citations/error/usage/truncated/next_cursor/effect_receipt_ref`。超限结果先写 artifact,再返回摘要和范围读取句柄;不把几十 MB 文本送进 prompt。
|
||||
|
||||
### 5.2 一条执行通道
|
||||
|
||||
```text
|
||||
发现 → 加载 schema → schema 校验 → 授权与范围解析 → 预算/取消检查
|
||||
→ 幂等查询 → 执行 → 结果 schema/大小校验 → receipt/结果提交 → 事件 → observation
|
||||
```
|
||||
|
||||
provider 原生 function call 与文档 `CALL:name + ARGS:{...}` 都归一到该通道。保留旧白名单适配,已有 `.mq.md ##` 可根据形参推导初始 schema,再允许显式描述收紧。转换不允许调用未暴露的框架内部函数。禁止对模型参数使用 eval/任意代码反序列化。
|
||||
|
||||
`tools.search` 返回已授权且当前可用的工具摘要;`tools.describe` 按 ID 返回完整 schema。核心 5–8 个工具可常驻,其余按需加载;此数量是产品起始配置,不写死框架。每次真正调用仍重新检查授权;搜索索引可列 unavailable 原因供诊断,但不能让未授权工具名字泄露私有连接信息。
|
||||
|
||||
初始支持 JSON Schema 的明确子集并公开能力;不支持的 schema 拒绝注册,不静默放宽。原生工具能力、并行工具调用、图片输入、结构化输出分别探测;纯文本兼容 provider 继续走 CALL,但并发和可靠性承诺按测试能力开放。
|
||||
|
||||
### 5.3 并发、MCP 与程序化执行
|
||||
|
||||
独立只读调用可并发,默认最多 4 个;修改同一资源的调用串行且用 revision CAS。依赖链、审批与取消检查保持顺序。一个并发调用失败不丢弃其他已成功结果。
|
||||
|
||||
MCP 扩展现有 client:先完善 timeout/cancel、错误映射、工具分页与 schema、resource read/link,再按 capability 增加远程 Streamable HTTP 与连接认证。stdio 不应允许模型选择任意宿主可执行文件。连接元数据归应用,凭证通过 secret handle 注入 worker,工具输出和 trace 不记录密钥。
|
||||
|
||||
工具 annotations 只是提示,可信策略确定真实效应。外部结果全部为数据,不能提升为 standing/system。MCP resource URI 转成宿主授权 ResourceRef,不允许前端直接请求任意 file:// 或内部网地址。
|
||||
|
||||
程序化工具编排和子 Agent 为后续切片:在沙箱中仅暴露注册 dispatcher,逐次执行同样的授权、预算和效应日志;禁止通过一段脚本绕过逐工具控制。子任务继承更小权限和共享总预算,不默认开放写同一资源。
|
||||
|
||||
## 6. 输出通道与上下文
|
||||
|
||||
### 6.1 AgentOutputV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "AgentOutputV1",
|
||||
"status": "succeeded",
|
||||
"answer": {"format": "markdown", "text": "已整理为三点,完整笔记见右侧。"},
|
||||
"artifacts": [{"resource_id": "res_note_01", "revision": "sha256:example"}],
|
||||
"citations": [],
|
||||
"validation": {"status": "passed", "report_ref": "resource:verify_01"},
|
||||
"finish_reason": "completed",
|
||||
"recovery_options": []
|
||||
}
|
||||
```
|
||||
|
||||
这是结果传输协议,不要求模型每次逐字生成这张 JSON。文档式编排仍可产出 `.mq.md`,框架把稳定产物、摘要与事件归一化。普通文本回答可没有 artifact 和 validation;未运行的内容标 `not_applicable/not_run`,不能填 passed。
|
||||
|
||||
channel 至少区分 `answer/artifact/progress/diagnostic`。只有 answer delta 可追加到聊天正文;工作簿 token 和工具日志进入其他通道。进度是可观察动作摘要,不要求或泄露模型内部思维链。
|
||||
|
||||
应用传 `ResponsePolicy`:detail level、目标长度、最大输出 tokens、是否允许 artifact、用户显式需求。框架负责 budget 和 finish_reason,中文字符数与最终文案由应用决定。达到 token 上限返回 `length_limited` 和完整/不完整标记,不能裁剪 JSON/代码后假装成功。
|
||||
|
||||
优先从已验证产物结构投影摘要。必要时增加一次受预算控制的摘要模型调用;摘要不得新增未经证据支持的结论。修复成功后 accepted candidate、结果正文、artifact revision 与 verification digest 必须全部一致。
|
||||
|
||||
### 6.2 ContextPackV2
|
||||
|
||||
按优先级组装:可信运行规则→最新用户目标/约束→用户选中资源范围→未决操作/成功步骤摘要→检索证据→近期对话→可回读历史。保持角色结构,不把用户/工具文本简单拼进系统指令。
|
||||
|
||||
每个 item 携带 `origin/trust/resource_ref/revision/token_estimate/priority`。预算初值建议保留模型窗口 20% 给输出与协议开销;上下文使用达到可用预算 70% 时触发整理,具体比例配置化。优先剔除可重读的完整工具输出,保留摘要、引用和失败恢复锚点。
|
||||
|
||||
Compaction 必须保留:目标、用户限制、当前计划、已完成步骤、待决写入、授权范围、输入版本、已接受产物与引用、余量。summary 绑定其 source event range 和 digest,不能当成新的已验证知识。工具输入过时须重读,不能依赖压缩摘要执行写入。
|
||||
|
||||
已有 EKC/agent memory 继续提供知识发现和复用。长期用户记忆的创建/修改/删除政策归 qdagent;网页中的指令不能自动变成长期偏好。
|
||||
|
||||
## 7. 统一资源与只读视图
|
||||
|
||||
### 7.1 ResourceRefV1 / ResourceViewV1
|
||||
|
||||
ResourceRef 统一携带 `resource_id/workspace_id/kind/media_type/revision/digest/title/size/origin/locator`;opaque ID 由宿主映射,不将浏览器 path 直接当文件权限。revision 是内容版本,generation 是知识发布代,两者不混用。
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "ResourceViewV1",
|
||||
"resource": {
|
||||
"resource_id": "res_01", "workspace_id": "ws_01", "kind": "file",
|
||||
"revision": "sha256:example", "media_type": "text/markdown", "title": "设计说明"
|
||||
},
|
||||
"renderer": {"id": "markdown", "version": "1", "trust": "sanitized"},
|
||||
"render": {"format": "sanitized_html", "fragment": "<p>正文</p>"},
|
||||
"outline": [],
|
||||
"locators": [],
|
||||
"completeness": "complete",
|
||||
"no_exec": true,
|
||||
"diagnostics": [],
|
||||
"next_cursor": null
|
||||
}
|
||||
```
|
||||
|
||||
继续把 `.mq.md` 交 `view.document`,ResourceView 只包装/扩展,不能另解释一套 Marqdo 语义。普通 `.md/.txt/代码/JSON/CSV` 走媒体类型处理,避免全仓语义编译。浏览器组件由 qdagent 实现,框架只提供可读内容、受控片段或短期授权 blob 引用。
|
||||
|
||||
`fragment`、`text`、`blob_ref` 是互斥载荷,按严格 format enum 解码。未知格式返回 unsupported,不能用 `format.includes('html')` 猜测 HTML。为空与加载失败必须有独立状态。
|
||||
|
||||
### 7.2 格式矩阵
|
||||
|
||||
| 格式 | 框架提供 | 前端消费 | 未具备能力时 |
|
||||
|---|---|---|---|
|
||||
| `.mq.md` | 静态 DocumentView、outline、节点/引用 | 正文、语义链接、源码切换 | 只读源码 + 明确诊断,不执行 |
|
||||
| Markdown / 笔记正文 | 共享静态 Markdown→受控结构/HTML、相对资源引用 | 标题、列表、表格、代码、链接 | 纯文本 |
|
||||
| 文本/代码 | 分页行片段、编码信息、行定位 | 行号与语法高亮 | 编码提示/下载 |
|
||||
| JSON / CSV | 有界解析、路径/行列定位、分页 | 树/表/源码 | 原始文本,标格式错误 |
|
||||
| 图片 | 授权 blob、尺寸/元信息 | 缩放/旋转/替代文本 | 下载,不暗示已做 OCR |
|
||||
| PDF | blob、页元信息,可选提取插件 | PDF.js 页渲染与定位 | 文件卡;提取不可用不阻止支持的视觉预览 |
|
||||
| DOCX/XLSX/PPTX | 受限转换插件,可选 PDF/HTML 派生物 | 按派生格式预览 | 未安装转换器,保留下载 |
|
||||
| HTML/SVG | 默认源码;允许时经严格清洗或受限派生物 | 隔离预览 | 不以内联可执行页面显示 |
|
||||
| 未知二进制/压缩包 | 元数据 | 下载卡 | 不自动解压/执行 |
|
||||
|
||||
提取、预览、执行各有独立 capability。办公转换、OCR 使用受限 worker,禁宏与网络、限制时间/内存/页数/解压膨胀比;结果绑定原件 digest、转换器版本和参数。首期不承诺保真编辑。
|
||||
|
||||
### 7.3 安全、定位、缓存
|
||||
|
||||
所有读取先校验宿主授予的 workspace/resource scope,canonicalize 并处理 symlink 逃逸;读取句柄与校验对象一致,防路径检查后替换。读取原件的身份权限不可被缓存绕过。
|
||||
|
||||
预览绝不调用 `run/verify` 或有执行副作用的 view 路径;正文中的 Marqdo 调用链接只展示语义与导航,执行需单独工具调用与授权。远程图片、相对链接、资源 URL 经受控解析;下载入口不允许任意内网 fetch。
|
||||
|
||||
HTML 清洗在框架产出侧和浏览器插入侧都有明确边界;用成熟 allowlist 实现而非正则。禁止 script/event handler、危险 URI、任意 style/form/嵌入对象。前端配 CSP;对需要交互的产物另建无权限 sandbox,不复用文档渲染器。
|
||||
|
||||
缓存 key:workspace + resource ID + revision + renderer version + render options + policy version;命中前重新授权。历史 revision 不存在就返回 `version_unavailable`,不能默默展示当前版。locator 支持 node/span/line/page/cell,失效时标 stale 并提供用户主动查看最新版的操作。
|
||||
|
||||
建议首期限制:文本片段 256 KiB、代码单次 500 行、CSV 单次 200 行;更大内容分页,完整文件保留。数值需压测校准,不作为现有系统性能声明。
|
||||
|
||||
## 8. 事件、可观测性与能力协商
|
||||
|
||||
复用 RuntimeEventV2 的 task/run/attempt/seq/event_id。拟增加事件类型:`agent.step.started/completed`、`tool.started/completed/failed`、`recovery.scheduled/exhausted`、`checkpoint.committed`、`artifact.updated`、`answer.delta/committed`、`context.compacted`。现有 `message.delta` 由兼容适配映射 answer channel,不能同时重复消费两套事件。
|
||||
|
||||
终态提交包含 accepted output manifest、last_seq、result digest;断流客户端能通过快照补齐最终答案。stream delta 是预览,最终 committed revision 是权威。统计每次尝试的 usage,摘要和修复调用分别标 purpose;未知计量保持 unknown。
|
||||
|
||||
拟新增 capability:`agent.error_v1`、`agent.checkpoint_v2`、`agent.tool_schema_v1`、`agent.output_channels_v1`、`agent.context_pack_v2`、`resource.view_v1`,以及各 media renderer 的独立版本/可用状态。保持现有 probe,新增字段向后兼容;未知 feature 当不可用。
|
||||
|
||||
trace 记录因果 ID、耗时、错误类别、参数摘要、资源版本和 effect receipt。正文与密钥按配置脱敏,不默认把用户全文件复制进日志。输出中不包含模型私有推理;可审计的是实际动作与结果。
|
||||
|
||||
## 9. 分阶段实现与文件落点
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 依赖 / 退出条件 |
|
||||
|---|---|---|---|
|
||||
| M-A0 | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | 上述协议、旧适配、状态映射 | 先冻结跨仓字段,未知字段/版本可降级 |
|
||||
| M-A1 | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、新 recovery/effects 支撑模块 | 分类错误、有界修复、accepted candidate、原子检查点 | M-A0;故障注入不重复写、旧记录不冒险自动恢复 |
|
||||
| M-A2 | `plugins/agent/src/lib.rs`、`mcp_client.rs`、新 tool registry/dispatcher | schema 工具、调用统一、分页与结果资源 | M-A0;未授权调用为 0,失败结果结构正确 |
|
||||
| M-A3 | `src/workbench/document_view.rs`、新 resource_view、媒体适配模块 | ResourceRef/View、普通格式静态阅读、no-exec | M-A0;资源定位与安全语料通过 |
|
||||
| M-A4 | `ext/ai/agent.mq.md`、`plugins/llm/src/lib.rs`、`src/workbench/run_context.rs` | 输出分通道、预算、ContextPackV2 | M-A1/2;原生和纯文本 provider fixture 都可用 |
|
||||
| M-A5 | `src/runtime/` 的既有存储/事件适配、MCP 与转换插件 | 恢复对账、PDF/Office 插件、远程 MCP | M-A1/2/3;持久模式 crash/restart 通过 |
|
||||
| M-A6 | plan/subtask/sandbox 扩展 | 程序化工具、有界委派与可选浏览器 | 后置;须证明任务收益和预算/效应可控 |
|
||||
|
||||
先交 M-A0 与 qdagent P0 的静态阅读/错误结果修复;不要让完整 checkpoint v2 阻塞笔记预览。M-A1 可先上只读重试,写恢复待 ledger 通过再开放。新特性默认关闭直到对应合同实测通过,旧路径继续可读。
|
||||
|
||||
## 10. 验收与评测
|
||||
|
||||
所有目标是 proposed gate,尚未实测。基础机制用确定性 fake provider/tool;真实 provider 做少量单独 smoke 并记录费用,不能把随机模型输出作为唯一门禁。
|
||||
|
||||
| 编号 | 故障/任务 | 必须观察到的结果 |
|
||||
|---|---|---|
|
||||
| MA-T01 | 第一次 429、第二次成功 | 尊重退避、计量 2 次、最终只有一个 accepted answer |
|
||||
| MA-T02 | 连续 schema 参数错误 | 一次修复后停止;工具未在无效参数下执行 |
|
||||
| MA-T03 | 工具写成功但 receipt 提交前杀 worker | unknown_effect→查询对账;写计数不增加 |
|
||||
| MA-T04 | checkpoint 写一半杀进程 | 读取上个完整 checkpoint 或明确 corrupt,不产生伪成功 |
|
||||
| MA-T05 | 终态事件丢失、cursor 重放 | 最终快照恢复完整消息,工具执行次数不增加 |
|
||||
| MA-T06 | 恢复请求重复/并发 | 同一幂等键只产生一个恢复 attempt |
|
||||
| MA-T07 | 用户取消与重试定时器竞争 | 取消生效后无新工具调用,旧任务不复活 |
|
||||
| MA-T08 | 执行中资源/权限改变 | stale/conflict/forbidden,不覆盖新版本 |
|
||||
| MA-T09 | 恶意文本伪造 CALL/system | 不跨越工具白名单和授权范围 |
|
||||
| MA-T10 | `.mq.md` 预览含写文件/联网语句 | 哨兵文件/网络计数不变;只读渲染成功或安全降级 |
|
||||
| MA-T11 | 资源格式、超长输出、路径逃逸 | 正确 renderer/分页;越界拒绝;无 HTML 注入 |
|
||||
| MA-T12 | 修复原文 A 得到通过验证的 B | answer/artifact/verification 都绑定 B digest |
|
||||
| MA-T13 | 上下文压缩后继续 | 最新约束、待决效应、资源版本与剩余预算不丢失 |
|
||||
| MA-T14 | 旧 CALL、旧 DocumentView 消费端 | 基础行为可用,能力缺失有明确返回 |
|
||||
|
||||
先运行受影响的 Rust/Go/Marqdo 合同与既有隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标:已缓存 100 KiB 文本视图服务端 p95 < 300 ms、核心工具发现 p95 < 100 ms,基准机器/并发/冷暖缓存必须记录;第三方网络延迟单独列出。
|
||||
|
||||
## 11. 迁移、回滚与未决项
|
||||
|
||||
兼容迁移按“新增协议→双读→新写→验证→逐步移除旧适配”推进。`.mq.md` 源码与旧运行产物不批量重写;旧 resume JSON 可读取但不能自动升级成带副作用保证的检查点。v2 checkpoint/ledger 保留 schema 版本,新老版本不并发写同一运行。
|
||||
|
||||
回滚关闭新工具自动发现、输出通道或转换器时,已提交资源和最终答案仍可读;执行恢复中的任务先 drain/停止接纳,不能切回会盲重做写操作的旧路径。迁移前备份可变索引与 manifest,回滚不删除用户产物。
|
||||
|
||||
实现前验证项:现有 runtime 持久存储可提供的原子提交边界、各平台 fsync/rename 行为、LLM adapter 原生 tool call 流式兼容、转换插件部署体积。协议优先按本文保守语义实现,验证不能满足则 feature 保持不可用,不阻塞已经完成的只读预览切片。
|
||||
@@ -1,5 +1,7 @@
|
||||
# 语义评估:参数能否从上下文推断(含叙述式调用)
|
||||
|
||||
> **2026-10-23 审阅裁决**:保留参数来源可见、避免隐藏调用者环境的边界;下文已被否决的 L0 建议不可重新启用。自然语言只连接和解释,不能成为隐式执行触发器;当前指导见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **§3 的 L0 方案已被否决**(违反「只执行标记」原则);L1/L2 结论仍有效 |
|
||||
|
||||
@@ -36,7 +36,8 @@ type: llm
|
||||
model: ${env.OPENAI_MODEL ?? "gpt-4o-mini"}
|
||||
api_key: ${secret.OPENAI_API_KEY!}
|
||||
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
|
||||
import sys:lib/sys.mq.md
|
||||
import:
|
||||
sys: lib/sys.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 评定:`[描述](语句)` —— 方括号读作「人话」,圆括号读作「机器话」
|
||||
|
||||
> **2026-10-23 审阅裁决**:本文的 Classic 冲突统计和兼容取舍属于迁移历史;v2.1 默认采用描述包裹 payload,不能据旧冲突恢复默认 `[键](集合)`。保留标签的阅读/检索/步骤价值,不强制所有子表达式命名,也不把标签当作目标或权限依据。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已决策:走「路线二 纯度」**(落地见 [label-freshness-and-repair.md](label-freshness-and-repair.md)) |
|
||||
|
||||
@@ -156,7 +156,8 @@ source: &str (+ optional import map)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 调用实参:具名与位置
|
||||
|
||||
> **2026-10-23 适用范围校正**:本文保留早期调用尾部规则和历史示例,不是 v2.1 全部调用语法。当前已有 `f(args)` 及具名实参;默认紧邻 `](` 是描述包裹 payload,不再是下文所述的 Classic 取元。语法审阅与开发取舍见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),当前行为须由默认模式测试复核。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.1 增补;2026-09-14:方括号标记调用) |
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 语法设计:标记如何构成调用(在「只执行标记」原则下)
|
||||
|
||||
> **2026-10-23 审阅裁决**:保留显式标记和正文默认安全;性能数值是旧实验,不作为当前基准。持久跨文档接口优先具名参数,但不禁止位置参数;反引号声明与顺序改变可能是接口变化。当前调用与开发方向见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未改代码) |
|
||||
|
||||
@@ -3,22 +3,24 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
|
||||
| 日期 | 2026-09-22 |
|
||||
| 日期 | 2026-09-22;2026-10-23 校正 v2.1 默认链接语义 |
|
||||
| 守卫 | `tests/core_surface.rs` ⇄ `src/parse/mod.rs` `CORE_CONSTRUCTS`(改动任一侧不同步 → CI 红) |
|
||||
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)(语义宪法)· [layers.md](layers.md)(准入戒律)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.1/T1.3 |
|
||||
|
||||
> **戒律总纲**:核心标记是**封闭集合**(约 19 个构造)。新增任何一行必须走 ADR(见 [layers.md](layers.md) 准入戒律)并回答「为什么现有标记不够」;生态需求的默认答案是**进 ext**。本表 id 列与守卫测试强一致:改表不同步 `CORE_CONSTRUCTS`(或反之)、样例文件缺失,一律 CI 红。
|
||||
|
||||
> **版本边界**:构造 ID 是历史守卫标识,不是固定不变的语义说明。`link-index` ID 暂保留以匹配注册表,但默认 `[]()` 已是描述包裹 payload;旧索引语义仅属于显式 Classic 兼容路径。未来步骤/知识投影见[文档原生指导](document-native-development-guide.md),不要把目标能力当作当前已实现。核心数量之外,还要审查上下文例外和作者负担。
|
||||
|
||||
## 1. 行构造
|
||||
|
||||
| id | 外形 | 语义 | 戒律 | 样例 |
|
||||
|----|------|------|------|------|
|
||||
| `narrative` | 无标记文字 | 叙述(注释) | 段落内延续到空行;**默认安全**——永远不存在「叙述被执行」的路径 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
| `narrative` | 无标记文字 | 叙述(不执行) | 段落内延续到空行;普通叙述不触发执行;未来知识引用投影也不改变此权限边界 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
| `blank` | 空行 | 段落边界 | 叙述分段的唯一手段;不得被赋予其它语义 | `tests/markup-v03/inc-prose.mq.md` |
|
||||
| `heading-unit` | `#` / `##` | 对象 / 函数单元 | 标题即单元边界,按深度嵌套;正文禁止用 `##` 做版式(会变成函数) | `tests/markup-v03/decl-ident-only.mq.md` |
|
||||
| `call-line` | `>` | 调用行 | 输出等副作用 = **普通函数**,不是架构标记 | `tests/markup-v03/dual-call.mq.md` |
|
||||
| `branch-list` | 体内 `1.` 递增 | 分支 | 自 `1.` 起序号递增构成一个判断;重出 `1.` 开新判断;`N. *` = else;**不是所有有序列表都是 if** | `tests/markup-v03/greet-default.mq.md` |
|
||||
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [项](集合)` | `tests/structure/loop.mq.md` |
|
||||
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [说明](遍历 集合 为 项)`;描述不是绑定变量名 | `tests/structure/loop.mq.md` |
|
||||
| `param` | `` + `名` `` | 形参(兼容形) | 首选叙述 `` `名` `` 升参(宪法 §8);`+` 形仅兼容保留 | `tests/markup-v03/greet-default.mq.md` |
|
||||
| `table` | GFM 表 | 集合 | 几何即类型([tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md));**绑定 = 数据,未绑定 = 文档表** | `tests/structure/collection.mq.md` |
|
||||
| `fence` | ` ```lang ` | 外联 | 语言块原样外联,不进 Marqdo 语义 | `tests/lib/foreign-python.mq.md` |
|
||||
@@ -30,12 +32,12 @@
|
||||
| id | 外形 | 语义 | 戒律 | 样例 |
|
||||
|----|------|------|------|------|
|
||||
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.mq.md` |
|
||||
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 只有粗体进入执行;判别序:赋值 → 调用 → 表达式 | `tests/markup-v03/multi-bold.mq.md` |
|
||||
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 粗体内代码判别序:赋值 → 调用 → 表达式;不取消调用行、返回等其它显式执行入口 | `tests/markup-v03/multi-bold.mq.md` |
|
||||
| `italic-return` | `*…*` | 返回 | 改变控制流(**返回是架构**);返回即结束函数体 | `tests/markup-v03/inc-prose.mq.md` |
|
||||
| `empty-return` | `*None*` / `****` | 空返回 | 返回 `None` 并结束函数体 | `tests/markup-v03/empty-return-none.mq.md` |
|
||||
| `link-index` | `[键](集合)` | 取元 / foreach | **主取元语法**;与 bracket-call 靠 `]` 后是否紧邻 `(` 消歧 | `tests/lib/table-collections.mq.md` |
|
||||
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;与 link-index 消歧同上 | `tests/structure/bracket-call.mq.md` |
|
||||
| `footnote-index` | `集合[^键]` | 过渡取元 | **仅兼容**;新代码一律写 link-index | `tests/structure/footnote-index.mq.md` |
|
||||
| `link-index` | `[描述](表达式)` | 描述包裹 payload(历史 ID) | 默认 Occlusion;取元可写 `[说明](access(集合, 键))`,不按描述取键;循环载荷见上 | `tests/occlusion/access-and-loop.mq.md` |
|
||||
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;紧邻 `](` 的默认语义为 payload 遮蔽,不是旧索引 | `tests/structure/bracket-call.mq.md` |
|
||||
| `footnote-index` | `集合[^键]` | 兼容取元 | 保留既有能力;新代码优先 `access(...)`,需要解释时包裹描述,不再推荐旧 `[键](集合)` | `tests/structure/footnote-index.mq.md` |
|
||||
| `soft-emphasis` | `*仅*` / `**说明**` | 忽略 | 非代码形强调**不执行**——默认安全的关键消歧规则 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
|
||||
## 3. 词法大类(LineKind,`src/lex/mod.rs`)
|
||||
|
||||
@@ -80,7 +80,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;嵌套 `import:` 映射与其它 YAML 键一并解析 |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
| **regex** (=1.13.1) | 正则 | Mid M1 `lib/re`;`default-features=false` + `std`/`unicode`;无回溯引用 |
|
||||
| **sha2** (=0.10.9) / **sha1** (=0.10.6) / **md-5** (=0.10.6) / **hmac** (=0.12.1) | 摘要 | Mid M3 `lib/hash` |
|
||||
|
||||
@@ -0,0 +1,284 @@
|
||||
# Marqdo 文档原生开发指导:让知识的表达、执行与复用成为同一件事
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | 下一阶段开发指导与规划修订;不表示下述目标接口已经实现 |
|
||||
| 日期 / 审阅基线 | 2026-10-23 / `main`,`7674ebb`;继承缺口审计的 `434be9f` 代码证据 |
|
||||
| 原始意图 | [009](../next/009.md)、[附属设计](../next/Marqdo_Executable_Knowledge_Design.md)、[附属示例](../next/Marqdo_Executable_Knowledge_Example.md) |
|
||||
| 配套实施文件 | [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)、[缺口与交付路线](../roadmap/executable-knowledge-gaps-2026-10-23.md) |
|
||||
| 本轮边界 | 校正开发方向、作者体验、AI 工作协议和验收;不新增语法,不宣称实现新能力 |
|
||||
|
||||
## 1. 审阅结论与规范关系
|
||||
|
||||
Marqdo 的优势不在于给传统程序换一套 Markdown 符号,而在于:**读者解释知识、作者修改知识、程序执行知识、AI 查找并复用知识,能够指向同一份有结构的文档和其中的同一步。** 标题、叙述、表格、链接描述、输入输出、来源及执行行为不应分散在彼此手工同步的系统中。
|
||||
|
||||
现有规划没有放弃这一目标,但工程排序存在偏移:把身份、图、证据、锁、句柄、晋升全部铺完,再验证人和 AI 是否更容易使用。这样可能交付一个功能齐全的制品管理系统,却让文档作者承担另一套注册、声明、审核和配置工作。需要改变交付方法,不必推翻确定性编译、绑定和权限机制。
|
||||
|
||||
本指导规定**为何开发、作者维护什么、怎样证明值得开发**;详细规范规定语义模型与执行约束;路线图规定当前缺口、切片与完成证据。三者不是三套平行设计。遇到冲突,依次采用:`009` 的产品意图 → 本指导对作者负担、场景分级和交付次序的修订 → 详细规范的工程规则 → 附属概念示例。当前代码与测试证明“已实现什么”,不能把代码局限升级为永久语言禁令;原始讨论保留,不据其重新引入已被否决的方案。
|
||||
|
||||
### 1.1 方向修订清单
|
||||
|
||||
| 容易偏移的做法 | 修订后的要求 | 必须保留的技术约束 |
|
||||
|---|---|---|
|
||||
| 先做完整知识治理平台,再给作者使用 | 从一篇可读、可运行、可定位步骤的文档交付,逐层扩展 | 每个已支持路径都有准确的目标和效应边界 |
|
||||
| 为进入知识库再写 YAML、注册表和索引 | 从源码推导;只有不能推导的领域事实才需作者补充 | 生成物有版本,可重建,可检查来源 |
|
||||
| 所有逻辑先封装成可登记函数/类 | 一次性逻辑直接写;需要命名、解释或复用时逐步提取 | 作用域、形参、返回与副作用明确 |
|
||||
| 所有调用先审核、锁定、签发远程凭据 | 本地探索、项目复用、严格业务、远程执行分级 | 精确目标、运行时权限不能被标签或模型绕过 |
|
||||
| AI 只能搜文档、填工具参数 | AI 可以读步骤、组合、选择候选、局部修改、提取和验证 | 模型的选择必须转成显式目标,由编译器校验 |
|
||||
| 为“独特”拒绝普通调用或新增更多标记 | 保留简单 payload;让 Markdown 结构提供程序之外的信息 | 无第二套表达式文法,无裸词隐式执行 |
|
||||
| 核心构造数量不增长就是简单 | 同时检查上下文例外、记忆负担和诊断成本 | 新构造需 ADR;不靠把新规则藏进旧构造绕过审查 |
|
||||
|
||||
### 1.2 四个不能互相替代的完成条件
|
||||
|
||||
1. **读得懂**:不打开生成图,也能从源文件看出目的、关键步骤、参数角色和限制。
|
||||
2. **执行同一件事**:标签表达意图,payload 决定计算;运行 trace 能回到源码步骤,不能执行另一个同名目标。
|
||||
3. **改得动**:人或 AI 能修改一个明确步骤,看到影响与验证结果,不必重写整份文档或同步多份签名。
|
||||
4. **复用得对**:找到已有能力后实际调用它;不满足条件时给出具体拒绝原因,而非用复制源码掩盖失败。
|
||||
|
||||
“更适合 AI”是待验证的产品假设,不是 Markdown 文件后缀自动赋予的性质。正确性和作者成本优先于 token 下降;错误复用更便宜不算优化。
|
||||
|
||||
## 2. 语法审查的保留、修正与暂缓
|
||||
|
||||
以下裁决针对审查结论的适用范围,不重写历史实验记录。旧文档中的原型、性能数值和当时的 `Value`/AST 限制,不能直接当作 v2.1 的规范或测试结果。
|
||||
|
||||
| 审查材料 | 保留的洞见 | 需要修正的外推 / 本轮处置 |
|
||||
|---|---|---|
|
||||
| [函数即命名](function-as-naming-philosophy.md) | 从正文计算出发,命名应降低理解和复用成本;避免无意义包装 | “具名给值缺失”是历史观察,当前有具名参数;替换模型是教学解释,不意味着禁止递归、前向引用或必须文本展开 |
|
||||
| [方括号作为标签](bracket-as-label-evaluation.md) | 描述与 payload 共址;标签帮助解释、检索和拆步骤 | Classic 冲突是迁移历史,不据此恢复默认 `[键](集合)`;不强制每个常量或子表达式都有标签 |
|
||||
| [圆括号与可读调用](paren-call-and-readable-invocation.md) | 调用标记应明确;保留 `f(args)` 的局部可读性 | 原型撤回不代表现有版本缺少该能力;Marqdo 的独特性不依赖消灭熟悉的表达式形式 |
|
||||
| [从标记推导调用](call-syntax-from-marks.md) | 语义成分有明确标记;自然语言是连接与解释,不参与猜测调用 | 持久跨文档接口优先具名实参;短而稳定的位置参数仍合法。推断参数的声明次序变化属于接口变化,不承诺任意润色都无影响 |
|
||||
| [环境参数](ambient-parameters-evaluation.md) | 参数来源应可见,避免调用者隐式环境影响复用 | 文档顶部已否决 L0 裸“执行”触发,正文旧建议不能重新生效;文件级常量也须有明确绑定与依赖,不变成动态作用域 |
|
||||
| [函数作为值](functions-as-values-evaluation.md) | 区分名称数据、一等函数、有限查表;避免无需求增加核心复杂度 | “匿名函数必不能索引”“动态调用必然破坏契约”不是普遍定理。将来可研究稳定节点身份与运行时契约;本轮不引入闭包,也不永久禁止 |
|
||||
| [函数作为表格](function-as-table-semantics.md) | 数据表几何有既定含义;契约表不可另造一份参数声明 | 不把表格全部变成函数,也不把“现有实现不支持”写成“表格不能计算”;有限决策表先评估库方案,只有明确角色和歧义测试后才讨论语言扩展 |
|
||||
| [核心表面](core-surface.md)、[分层](layers.md) | 核心小、标记可解释、构造有测试与准入流程 | 清单中的旧取元/循环说明需随迁移更新;固定数量不等于低认知成本,守卫通过也不证明文档语义正确 |
|
||||
| [链接设计](link-syntax.md)、[告警疲劳](warning-fatigue-control.md) | 单一 payload 文法;标签漂移可提示;默认安静、按需严格 | 标签不是纯粹可丢弃的注释,也不是事实证明;不做每次运行重复的批准仪式,不靠词汇相似度证明描述与代码一致 |
|
||||
|
||||
### 2.1 继续冻结的语法边界
|
||||
|
||||
- 默认 `[]()` 是描述包裹 payload;旧取元只能在显式历史兼容路径下解释。现行取元用 `access(...)` 等已支持形式;循环使用明确遍历载荷。
|
||||
- `[]()` 不等于“仅函数调用”:计算、取元、调用、遍历、叙述引用都需要各自语义角色,不能只收集 call 边就宣称完成知识步骤。
|
||||
- 正文引用与可执行位置有不同调度权限。普通句子不因出现“执行”“发送”或工具名而运行;正文解析成引用也不自动求值。
|
||||
- 不把所有 `#` 解释成某种知识对象,或把继承悄悄变成实例关系。标题的既有语义必须兼容,IR 可区分 Type、Entity、Fact、Function。
|
||||
- 不给同一参数增加正文声明、签名表、工具 schema 三套作者真相。规范签名和工具 schema 是投影;契约表补充类型、约束和说明,不偷偷增加形参。
|
||||
- 可读源文件是硬要求;普通 Markdown 渲染器是否把含空格/嵌套表达式的链接渲染成可点击链接是另一件事。不能承诺全部标准渲染器理解执行语义。
|
||||
|
||||
### 2.2 哪些编辑不能当成“只是改文案”
|
||||
|
||||
不含语义标记的普通叙述润色,应保持执行结果和实现摘要;标签改名应保留 payload 行为,但更新展示/检索内容。反引号声明、首次出现顺序、标题名称/层级、粗斜体、表格几何、契约、来源和适用范围的改变则可能影响程序或知识可信性。编辑器必须展示真实差异,不能统一标为 prose-only。
|
||||
|
||||
标签漂移诊断应说明“描述或实现可能需要复核”,不能自动替作者改写业务意图。自然语言一致性检查可作辅助建议,确定性检查仍需可定位的符号、类型、契约或测试证据。
|
||||
|
||||
## 3. 作者工作流:先写清楚,再获得复用能力
|
||||
|
||||
### 3.1 一次性计算不需要预先建知识模型
|
||||
|
||||
下面是当前默认语法的完整最小程序。无模式开关、无项目注册、无知识 ID、无锁文件。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
这是演示订单,单价与数量直接写在计算处。
|
||||
|
||||
**小计 = [两件商品的小计](2 * 30)**
|
||||
> print text=`小计`
|
||||
```
|
||||
|
||||
可读意图和精确计算共址。这个标签值得保留,因为它说明本次计算的业务角色;不要求把 `2`、`30`、乘法分别命名。
|
||||
|
||||
### 3.2 需要解释或复用时才提取命名能力
|
||||
|
||||
```markdown
|
||||
## 商品小计
|
||||
|
||||
根据购买数量`数量`和商品单价`单价`计算小计。
|
||||
|
||||
*[按数量与单价计算](数量 * 单价)*
|
||||
|
||||
# main
|
||||
|
||||
计算同一笔演示订单。
|
||||
|
||||
**小计 = [两件商品的小计](商品小计(数量=2, 单价=30))**
|
||||
> print text=`小计`
|
||||
```
|
||||
|
||||
两个完整程序在本轮本地现有 `target/debug/marqdo` 上分别以 Tree 和 Bytecode 执行,均输出 `60`。这仅验证基础语法,不证明步骤身份、重构工具或 Agent 闭环已经实现;也不是全仓测试报告。可将各块保存为 `.mq.md` 后用 `marqdo run 文件 --backend tree` / `--backend bytecode` 复核。
|
||||
|
||||
**后续工具目标**:从选中表达式提取为标题单元,推导自由变量为参数、保持求值顺序与 effect 次数、生成具名调用,并给出可审阅补丁。反向内联也应保留契约和来源关联;无法证明安全的捕获变量、递归、控制流、动态目标或有副作用表达式,先拒绝自动变换并说明原因,不伪称等价。
|
||||
|
||||
### 3.3 跨文档复用与事实说明分别增长
|
||||
|
||||
当第二篇文档需要这段计算,才提取模块并显式 import;不要为十行单文件强制创建 `corpus/knowledge/apps` 目录树。项目索引按约定发现,明确边界或外部来源时再加入配置。
|
||||
|
||||
当“商品小计”依赖政策、时间、币种等条件,再就地补契约与来源。简单乘法不要求假造现实来源;“某商店当前折扣为九折”则不能仅凭函数返回 `0.9` 声称真实。
|
||||
|
||||
正文可以说明结果为何成立,目标是引用同一能力和同一次受控执行的结果,而非手抄另一份公式。正文引用 AST、结果投影和绑定身份尚需开发;完整业务链使用[目标示例](../next/Marqdo_Executable_Knowledge_Example.md)验收,不把它冒充当前全部可运行的教程。
|
||||
|
||||
### 3.4 维护时看到知识变化,而不只是文件变化
|
||||
|
||||
目标维护流程:修改上游规则 → 显示受影响的计算、正文陈述和消费者 → 执行相关测试 → 展示结果/证据/接口各自变化 → 按使用策略接受更新。普通显示文案变更不应触发全库业务审批;证据过期也不必使无关纯工具全部失效。
|
||||
|
||||
## 4. 人维护语义,编译器维护机械关联
|
||||
|
||||
| 信息 | 作者责任 | 编译器 / 工具责任 |
|
||||
|---|---|---|
|
||||
| 目的与步骤 | 有帮助的标题、叙述、标签;避免空泛重复 | 保留源位置和层级,生成步骤投影,不要求手工节点注册 |
|
||||
| 输入输出 | 一份参数来源和必要契约;领域单位不能靠猜 | 推断规范签名、检查调用、生成 schema 和签名视图 |
|
||||
| 目标与依赖 | 显式 import、可读名称、必要消歧 | 绑定唯一 SymbolId,生成依赖边与闭包;不要求手写 ID |
|
||||
| 效应 | 扩展作者声明宿主能力;业务作者必要时收窄允许范围 | 汇总直接及传递效应;未知不得推断 pure;运行时执行能力上限 |
|
||||
| 事实与来源 | 原始资料、范围、有效期、人工审阅等不可推导信息 | 关联来源、记录验证事件、传播失效;不将文件路径视为事实证明 |
|
||||
| 身份与版本 | 有意移动/更名时确认必要迁移 | 区分身份与内容摘要;报告歧义,不靠猜测维持假稳定 |
|
||||
| view / AI 索引 | 不维护第二份可执行描述 | 同一语义模型投影;显示生成代、验证政策和缺失字段 |
|
||||
|
||||
生成信息不等于免费:首次编译、缓存修复、错误定位都要可理解。失败时应回到源文档中可修改的位置,而不是只报内部 Artifact 字段名。
|
||||
|
||||
稳定身份要诚实:同一次编译内引用和 trace 必须一致;普通文本编辑不应打乱无关节点;复制相似步骤、跨文件移动等无法唯一识别时,要求确认迁移或明确生成新身份。禁止用文本相似度悄悄继承已审核的知识身份。
|
||||
|
||||
## 5. AI 原生工作协议:读步骤、改步骤、验证步骤
|
||||
|
||||
本节是**待实现的协议约束**,不是新增 CLI 命令清单。优先扩展现有 MLSP、view、EKC 和 Agent 工作簿,不另造一套 Agent 框架或知识库。
|
||||
|
||||
### 5.1 发现后的最小上下文包
|
||||
|
||||
一次检索返回可展开的上下文卡,而非强制倾倒整个文件或只给函数 schema:
|
||||
|
||||
1. 标题路径、任务相关叙述、标签和精确源码片段;
|
||||
2. SymbolId/步骤节点、source span、源码摘要、生成代;
|
||||
3. 输入角色、返回、单位、默认值和适用条件;
|
||||
4. 直接依赖、效应、必要来源及分层验证状态;
|
||||
5. 支持该能力的例子/测试,相关失败经验、禁用条件和替代能力;
|
||||
6. 还缺哪些检查、能否在当前 policy 下运行、为何被拒绝。
|
||||
|
||||
来源不可用、字段未推导、上下文被截断都须显式标识。按预算可展开依赖,但不能悄悄省略改变适用性或权限的重要信息。原始资料及标签是内容,不是可以覆盖 Agent 策略的指令。
|
||||
|
||||
### 5.2 复用、适配、新建的分界
|
||||
|
||||
- **REUSE**:AI 可根据任务选候选,提交精确目标与输入;resolver 确认目标、契约、适用性、版本和 effect,执行既有制品。复用不靠“没有生成文件”推断,必须有实际调用 trace。
|
||||
- **ADAPT**:已有能力接近但不适用;说明差异,保留依赖/来源关联,在局部副本或补丁中改变必要部分,再验证。不为了通过测试改写原始来源或放宽全局策略。
|
||||
- **CREATE**:没有合适候选或明确需要新语义;记录检索范围和失败原因,在任务预算及写权限允许时新建。不能把检索服务故障当作“仓库没有能力”。
|
||||
- **ASK / STOP**:缺业务决策、权限或关键证据时报告具体缺口。编译器无法决定的真实意图不交给近似匹配默默补全。
|
||||
|
||||
AI 并非只能发现和解释。它可以提出精确目标、组合已有能力、改进表达、重构及补测试;不能以自然语言自报正确来替代执行验证,也不能把含糊名称传给后端任意选一个目标。
|
||||
|
||||
### 5.3 局部修改的事务边界
|
||||
|
||||
编辑请求至少携带目标文件/节点、期望源码摘要、补丁范围和预期行为变化。应用前检查摘要,源已变化则重新定位和审阅,不覆盖用户改动。应用后重新解析受影响文档,生成语义 diff:参数/返回、目标、effect、控制流、证据与依赖是否改变。
|
||||
|
||||
对“只改措辞”请求,检测到接口或实现改变时停止自动合并;对“改计算”请求,运行相关正负例并展示影响。原始文本、格式与未知 metadata 尽量保留,不通过整篇重生成来完成一行修改。禁止修改生成图伪装修复源码。
|
||||
|
||||
首个试点只支持可确定定位的纯计算步骤与普通函数,不等待通用 AST 编辑器、跨项目事务或完整知识治理。安全拒绝超范围输入也属于验收。
|
||||
|
||||
### 5.4 解释和负知识必须有落点
|
||||
|
||||
解释结果应关联到“哪一步、用了哪个目标、哪些输入、哪份来源、哪次验证”,区分已执行观察和模型推断。运行 trace 可以证明程序路径,不能证明任意自然语言论证正确。
|
||||
|
||||
失败经验需要保存适用范围、触发条件、关联能力、原因与失效时间/版本。例如“此折扣不适用于退款”应在查询定价能力时可见,而不是埋在另一份聊天记录里。先由普通文档与结构化关联承载,不先新增通用推理语言;过期负知识也要撤销,不能永久拦截修复后的能力。
|
||||
|
||||
## 6. 渐进严格:不把治理门槛塞进每一行正文
|
||||
|
||||
下面是目标政策分级,不是当前已有四种 CLI 模式。政策由项目/宿主配置和调用上下文选定,源文档保持同一种语法。
|
||||
|
||||
| 场景 | 必需条件 | 默认不要求 |
|
||||
|---|---|---|
|
||||
| 本地探索、单文件运行 | 明确语法与目标、已有运行时契约、宿主能力限制;如实显示未知状态 | lock、来源、ready 晋升、远程签名句柄 |
|
||||
| 项目内自动复用 | 精确绑定、输入/适用性检查、效应许可、状态满足所选政策、执行 trace | 所有纯工具都有人审证据、每次独立确认 |
|
||||
| 严格业务/可复现任务 | 相关依赖与证据锁定、必要验证新鲜度、受控环境和审计;明确不可重放部分 | 对无关文案变化重审整个项目 |
|
||||
| 远程/多租户/不受信调用方 | 上述相关约束,加可信授权主体、范围、服务端能力上限、撤销/期限与防伪设计 | 把客户端提交的 `allow_effects` 当授权本身 |
|
||||
|
||||
`ready` 是“对某项 policy 和输入/上下文已具备复用条件”,不是永久万能认证。未验证的本地草稿可以被检索、查看和按明确权限试跑;不能冒充满足严格政策的可复用事实。测试通过与事实证实分别报告。
|
||||
|
||||
正文 `check/view static` 不执行外部效应。用户主动打开的纯预览可复用项目或会话已有政策,不要求每个链接弹窗;effectful 运行始终受宿主能力和明确执行上下文控制。锁和摘要是完整性机制,不自动等于远程授权;可信本地引用无需先搭建凭据服务。
|
||||
|
||||
## 7. 交付切片:每片都有文档作者与 AI 能看见的结果
|
||||
|
||||
编号与[缺口路线图 §7](../roadmap/executable-knowledge-gaps-2026-10-23.md#7-依赖顺序与可合并切片)一致;G 编号沿用现状证据,M0–M6 保留为工程能力映射,不再被理解为必须全部串行完成的墙。
|
||||
|
||||
### S0 作者基线与最小语料
|
||||
|
||||
- 选定单文件计算、提取函数、两文档引用、表格取元/遍历、业务政策及拒绝复用六类任务;记录当前写法、输出、诊断和作者重复维护项。
|
||||
- 优先整理 `doc/README`、核心语法卡片、教程与运行示例的版本状态;不要先扩展通用库数量。
|
||||
- 为最小样例建立无网络门禁。100 单元及更大语料逐步增长,不阻塞首个可读文档切片。
|
||||
- 完成证据:别人按当前入口能写出正确默认语法;已实现与预期失败分开报告,不能把待实现测试跳过计为成功。
|
||||
|
||||
### S1 可读步骤与唯一目标
|
||||
|
||||
- 主要落点:`src/parse/`、`src/ast.rs`、`src/sema/`、`src/knowledge/compile.rs`、`src/view/`。
|
||||
- 在最小故事内联合完成 G01/G03:保留 label、payload、上下文和跨度;每类步骤有输入输出与依赖投影;旧 EKC 查询索引不再覆盖语义图。
|
||||
- 普通导航、正文引用、可执行表达式、循环分别处理,正文保持惰性。先确保支持范围内同一引用在源码、view、图中是同一个目标,再扩展覆盖范围。
|
||||
- 完成证据:作者能从渲染步骤返回对应源码;同名目标不误连;计算/取元/循环不是伪造的 call;重复构建可对照;未支持上下文明示。
|
||||
|
||||
### S2 确定执行与早期 AI 复用试点
|
||||
|
||||
- 主要落点:`src/sema/`、`src/interp.rs`、`src/bytecode/`、`src/mlsp.rs` 与现有 Agent 入口。
|
||||
- 完成静态普通函数、显式 import、关联函数的 BoundCall 主链;G02 与 G06 的效应安全下限不可延期。小范围可先用明确纯操作白名单,未知路径必须拒绝纯证明,而非猜 pure。
|
||||
- 实现最小上下文卡与本地绑定引用;以 stub/no-LLM 测试验证协议,然后用现有 Agent 跑相同故事。无需先完成远程鉴权平台或全面来源审核。
|
||||
- 完成证据:同一需求实际调用既有函数,不新增同义实现;两个后端 trace 对上图中目标;改目标、错误输入、未知效应、权限不足不能静默执行。
|
||||
|
||||
### S3 局部编辑、提取与库可读性
|
||||
|
||||
- 主要落点:MLSP 编辑/定位、相关 sema/检查入口、`lib/`、`ext/`、教程与测试。
|
||||
- 按 §5.3 实现受摘要保护的局部修改和语义 diff;实现受限纯表达式提取,或明确标为待实现,不用人工演示冒充工具能力。
|
||||
- 迁移标准库/扩展时删掉重复包装与噪音标签,保留有意义的业务步骤、契约和负例;中英镜像含义一致。兼容旧调用接口,不用增加旧语法解释救迁移遗漏。
|
||||
- 完成证据:同义润色不改执行;改反引号声明能检测签名变化;表达式提取前后结果/effect 次数一致;冲突补丁拒绝;CLI、库、扩展与 view 既有能力继续通过。
|
||||
|
||||
### S4 业务知识的来源与适用性
|
||||
|
||||
- 主要落点:契约、SourceRef/VerificationRecord、验证事件、Agent 候选解释;完成 G05 与 G07 的项目政策部分。
|
||||
- 选定书店案例的币种、数量边界、会员范围与政策有效期;给 schema、拒绝诊断及可运行负例,不泛化为全能业务规则语言。
|
||||
- 同步补齐传递效应与相关负知识;生成契约/状态展示,减少作者重复填写。
|
||||
- 完成证据:同一计算因输入或证据不同而正确通过/拒绝;来源过期不被 `tests=passed` 覆盖;普通纯工具无需虚构 SourceRef。
|
||||
|
||||
### S5 变化传播与严格复用
|
||||
|
||||
- 主要落点:`src/sema/lock.rs`、图/impact、产物提交与消费者;完成 G04/G08 和严格 handle 复核。
|
||||
- 区分身份/接口/实现/证据/闭包,给出可读升级 diff;整代快照保证消费者不会读取混代数据。并发读写一旦开放,该一致性就是前置条件,不能等到此片才承认风险。
|
||||
- 完成证据:修改依赖政策后,下游计算和正文解释进入影响集合;文案变化不误判实现变化;并发编辑或构建崩溃不导致错目标执行;锁不声称重放网络/随机/LLM。
|
||||
|
||||
### S6 生态验收与发布
|
||||
|
||||
- G10/G11 从 S0 起每片执行;S6 汇总兼容矩阵、真实工作流和打包后冒烟,不把测试留到最后。
|
||||
- G12 随实际规模需求推进;远程凭据/多租户是有条件的独立交付。它们不阻塞受信本地试点,也不得被本地通过的测试覆盖为“已安全支持”。
|
||||
- 完成证据:当前默认语法的 lib/ext/CLI/MLSP/view/WASM 等受影响消费者有明确结果;目标示例中的已发布子集实际可运行,未发布部分保留状态;发布声明与证据一一对应。
|
||||
|
||||
## 8. 验证 Marqdo 优势,而不只验证组件存在
|
||||
|
||||
### 8.1 必须收集的产品指标
|
||||
|
||||
| 维度 | 记录方法 | 失败信号 |
|
||||
|---|---|---|
|
||||
| 作者负担 | 完成同一任务所需手写声明、重复字段、配置、跳转和确认次数 | 简单本地算式也必须填写制品清单 |
|
||||
| 阅读与定位 | 给定问题,定位正确步骤/限制的准确率、耗时与上下文量 | 只看 label 会误导,必须打开生成 JSON 才理解源文档 |
|
||||
| 可修改性 | 修改范围、无关 diff、语义变化检测率、冲突覆盖数 | 为改一步而重生成全文件;措辞调整偷偷改变接口 |
|
||||
| 复用质量 | 已有能力发现率、实际调用率、重复实现率、误用率 | 检索命中却重新写代码;正确拒绝算成任务失败而被优化掉 |
|
||||
| 知识可追溯性 | 结果关联目标、步骤、输入、来源和验证的覆盖率 | `tested` 被当作事实正确;解释引用未执行的步骤 |
|
||||
| 总成本 | 正确完成任务的 token、工具调用、轮次、总耗时及编译成本 | 只报模型 tokens,隐藏额外注册/审核/修复成本 |
|
||||
|
||||
### 8.2 对照实验与门槛
|
||||
|
||||
1. 固定任务、可访问能力、输入数据、模型版本、工具能力、预算与超时;比较普通 Markdown+代码/RAG、当前 EKC 和新方案。不能给新方案更多现成实现再声称语法更优。
|
||||
2. 任务包括成功复用、同名冲突、近似但不适用、未知 effect、过期来源、正文不执行、局部修改及库升级。加入自然语言诱导绕过 policy 的负例。
|
||||
3. 先测确定性协议,再测多次 AI 运行,保留种子(支持时)、原始 trace、版本、失败样本与分布;小样本不夸大收益。
|
||||
4. 正确目标、无越权和正文无外部 effect 是硬门槛。原有兼容测试不得降低;效率阈值先测基线再登记,不捏造提升百分比。
|
||||
5. 若作者负担增加或误用率上升,回到交互/语义设计分析原因,不能只用“更多治理更安全”或“模型更便宜”解释过去。
|
||||
|
||||
### 8.3 发布声明分层
|
||||
|
||||
- “支持新语法”需语法、迁移、双后端与库兼容证据,不意味着完整知识复用已经交付。
|
||||
- “本地确定性知识复用”需 S1/S2 支持范围内的端到端与拒绝用例;范围外路径显式不支持,不能回落为模糊执行。
|
||||
- “严格业务知识复用”还需相关 S4/S5 来源、适用性、失效、锁和一致性证据。
|
||||
- “安全远程知识执行”需额外的授权、能力上限、凭据/撤销及隔离测试;本地 JSON handle 不等于远程安全。
|
||||
|
||||
## 9. 每个开发变更必须回答的问题
|
||||
|
||||
提交设计或实现时给出一份短而具体的审阅记录:
|
||||
|
||||
- 用户要读/写/改/复用的知识是什么?附源文档前后对照,不只给内部结构图。
|
||||
- 利用了哪种文档原生信息?若只增加通用框架能力,与主线的必要关系是什么?
|
||||
- 新增了哪些作者必须手工维护的信息?为什么不能从现有语义推导?
|
||||
- 是否改变标记、作用域、求值顺序、形参顺序、表格几何或正文安全?分别有哪些测试?
|
||||
- 人、CLI、view、图和 Agent 是否看到同一目标与状态?失败能否回到源码修复?
|
||||
- AI 的正确复用/局部编辑如何证明?哪些部分仍需模型判断,哪些由编译器决定?
|
||||
- 标准库和扩展是否先迁移?是否保住既有公开接口、输出与 effect?
|
||||
- 这是已实现、受限试点还是设计目标?文档和发布声明是否一致?
|
||||
|
||||
**准入原则**:内部可以使用成熟编译器、数据库和协议技术;外部必须减少知识在“说明、程序、索引、工具描述”之间的重复翻译。独特性由这条链的实际收益体现,不由新符号数量或与其他语言不同的程度体现。
|
||||
@@ -51,22 +51,25 @@ Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识
|
||||
|
||||
`implements` · `uses` · `depends_on` · `tested_by` · `documented_by` · `constrained_by` · `decided_by` · `supersedes` · `conflicts_with` · `deprecated_by` · `derived_from` · `failed_by` · `related_to`
|
||||
|
||||
落盘:`.marqdo/graph/graph.json` · `edges.json` · `index.json`。
|
||||
落盘(G01 分离后):
|
||||
- **权威语义图**:`.marqdo/graph/edges.json` · `nodes.json`(`SemanticProject`,含 `authority` 字段)· `steps.json`
|
||||
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json` · **`ir.json`**(完整 IR 快照,供查询热路径)
|
||||
|
||||
## 5. CLI
|
||||
|
||||
```bash
|
||||
marqdo knowledge [PATH] -o .marqdo # compile(默认)
|
||||
marqdo knowledge preflight "task"
|
||||
marqdo knowledge [PATH] -o .marqdo # compile(默认;写投影 + ir.json)
|
||||
marqdo knowledge preflight "task" # 暖机读 ir.json;缺图才 compile
|
||||
marqdo knowledge preflight "task" --refresh # 强制全量重编译后再预检
|
||||
marqdo knowledge record REUSE
|
||||
marqdo knowledge learn --task ... --failure ...
|
||||
marqdo find "authentication"
|
||||
marqdo find "authentication" # 同上:缺图才 compile;--refresh 强制
|
||||
marqdo reuse "implement oauth login"
|
||||
marqdo impact path/to/file.mq.md
|
||||
marqdo conflicts | stale | duplicate [--fail] | verify
|
||||
```
|
||||
|
||||
统一 `--json`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
|
||||
统一 `--json`。查询类命令(`preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`)默认 **读已编译投影**;CI 或源变更后应先 `marqdo knowledge` 或加 `--refresh`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
|
||||
|
||||
## 6. Reuse 协议
|
||||
|
||||
|
||||
@@ -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;让一次变更能回到具体的 `[]()` 和具体句子。
|
||||
|
||||
验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的
|
||||
取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。**
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
---
|
||||
|
||||
# 总目标
|
||||
|
||||
@@ -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
|
||||
---
|
||||
|
||||
## 获取时间
|
||||
|
||||
@@ -93,8 +93,8 @@ web.plugin # absolute path hint
|
||||
|----|-----------------------------|
|
||||
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **native `agent`** |
|
||||
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **native `web`** |
|
||||
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **native `quantum`** |
|
||||
| `web` | `web/index.mq.md` + facade/modules + `layout/` · `布局/` + `网页.mq.md`, **native `web`** |
|
||||
| `quantum` | `quantum/`(含 `量子/` 中文树), **native `quantum`** |
|
||||
|
||||
## Release assets (native)
|
||||
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
# 扩展库:index 即代码 · 文档 · SKILL · tools
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active**(契约卡;完整开发范式见下行) |
|
||||
| 日期 | 2026-11-06 |
|
||||
| 愿景 | [doc/next/012.md](../next/012.md)(手写真相源,本文不修改它) |
|
||||
| 范式长文 | [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md)(布局、陷阱、验收清单、推广顺序) |
|
||||
| 试点 | `ext/quantum/`;[手册闭环与当前契约位置修正](ext-quantum-handbook.md) |
|
||||
| 相关 | [ext-abi.md](ext-abi.md) · [ext-quantum.md](ext-quantum.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [function-as-table-semantics.md](function-as-table-semantics.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
扩展包里**每一份** `.mq.md` 同时是可执行代码、可读 SKILL、以及可 `marqdo call` 的 tools 面;**函数即工具**,`###` 即子工具;禁止第二套 catalog / OpenAPI 真相源。开发新包或迁包时以 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 的验收清单为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 整包统一作者契约(无例外)
|
||||
|
||||
适用于包内全部 `.mq.md`(含 `index`、子依赖、`_capability`、兼容层、中英镜像):
|
||||
|
||||
| 要求 | 含义 |
|
||||
|------|------|
|
||||
| 代码 | 标记可执行;实现可薄委托 ABI / 兄弟模块 |
|
||||
| SKILL | `#` 下写清领域、何时用、**For AI agents → `marqdo call` 本文件** |
|
||||
| tools | `##` / `###` 即工具树;无旁路 schema |
|
||||
| 版式 | **形参契约表紧贴标题下**;**返回契约表也在首条执行语句之前**(当前解析器只在此提取契约) |
|
||||
| 叙述 | 每个函数单元叙述占比 **≥ 50%**;公式与约定写进人话 |
|
||||
| 禁止 | `+` 清单当主表面;ABI 名罗列充文档;「内部文件免检」 |
|
||||
|
||||
形参仍由叙述/体中的 `` `名` `` 推断 arity;`| 参数 | 类型 | 说明 |` 为契约表(见 `tests/contracts/`)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 包布局(quantum 试点)
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
index.mq.md # EN 根 SKILL:无上下文也能照抄 marqdo call
|
||||
circuit/index.mq.md # call 工具 + 作者 # circuit
|
||||
gate/ · simulate/ · state/ · density/ · viz/
|
||||
_capability/index.mq.md
|
||||
量子/ # ZH 同包(勿再把 量子/ 抬到 ext/ 顶层)
|
||||
索引.mq.md
|
||||
电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
|
||||
```
|
||||
|
||||
`index` = 总图与编排,必须写明 FILE/FUNCTION/`--effects plugin`;每个子目录的 `index.mq.md` 单独拿到也要能执行。无单独「兼容层」文件。
|
||||
|
||||
---
|
||||
|
||||
## 3. `marqdo call` 与会话
|
||||
|
||||
```text
|
||||
marqdo call <FILE> <FUNCTION> [k=v…]
|
||||
[--json] [--backend tree|bytecode]
|
||||
[--effects none|plugin] # 默认 none
|
||||
[--session <id>]
|
||||
[--toget <name>] # 或尾部 toget <name>
|
||||
```
|
||||
|
||||
- 默认:仅纯函数(今日行为)。
|
||||
- `--effects plugin`:允许 `plugin.call`(及附属的 `output.write`);仍拒绝 fs.write / network / process.exec / llm 等。
|
||||
- `toget` + `--session`:绑定写入 `.marqdo/call-sessions/<id>.json`;参数 `$name` 引用会话值;跨进程 **plugin 句柄经 journal 重放** 重建。
|
||||
- 嵌套子工具:`parent.child`(`###` 路径)。
|
||||
|
||||
值字面量:整数/小数/引号文本/True|False|None;以 `[` / `{` 开头时按 JSON 解析为 List/Map。
|
||||
|
||||
---
|
||||
|
||||
## 4. 叙述 ≥ 50%
|
||||
|
||||
`marqdo check --narrative-ratio`(及 `lib/lint/narrative.mq.md` skill)按函数单元统计叙述字符占比;`ext/quantum/**/*.mq.md` **全量零豁免**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与 ADR 0007
|
||||
|
||||
作者程序与业务路径仍不写 `ensure_plugin` / `host_*`;插件经 `_capability` / facade 加载。Agent 用 `--effects plugin` 调用 facade,不把 capability 当日常工具(文件本身仍须达标 skill)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-11-06 | 初稿:012 试点契约、call effects/toget、quantum 模块树 |
|
||||
| 2026-11-06 | quantum 中文树收进 `ext/quantum/量子/`;根 skill 增加「选哪条路」;`ext add` 拒绝装进源码树 |
|
||||
| 2026-11-06 | 链到 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 作为开发范式长文 |
|
||||
@@ -197,7 +197,8 @@
|
||||
|
||||
````markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# 转置反序
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -20,7 +20,8 @@ Import:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import:
|
||||
llm: ext/ai/llm.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
# Quantum:从「拆分过的库」到可执行开发手册
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 日期 | 2026-11-08 |
|
||||
| 使用与开发真相源 | [英文根入口](../../ext/quantum/index.mq.md) · [中文根入口](../../ext/quantum/量子/索引.mq.md) |
|
||||
| 回归门禁 | [quantum_handbook.rs](../../tests/quantum_handbook.rs) |
|
||||
| 思想来源 | [next/010](../next/010.md) · [next/011](../next/011.md) · [next/012](../next/012.md) |
|
||||
| 本文定位 | 记录本次修正的原因与边界;日常使用无需先读本文 |
|
||||
|
||||
上一轮把量子库拆成了模块树,也加入了 `call` 与叙述比例,但没有形成「只沿 index 就能使用和开发」的闭环。问题出在验收标准:目录、工具和叙述存在,并不能证明一个陌生开发者能完成实验、理解结果,再正确扩展它。
|
||||
|
||||
## 已确认的缺口
|
||||
|
||||
| 缺口 | 后果 | 本轮修正 |
|
||||
|------|------|----------|
|
||||
| `## For AI agents`、`## Package layout` 等说明标题 | 解析成无业务意义的真实函数,污染工具树 | 说明用自然段,标题保留给工具/对象 |
|
||||
| 裸 `$qc`、缺会话或只有消费者没有生产者 | 照抄命令失效,Rust argv 测试发现不了 shell 展开 | 每页完整实验;引用和文本字面量用 shell 单引号 |
|
||||
| 字符串 `kind="bitflip"` 的双引号被 shell 去掉 | CLI 拒绝未带字面量引号的文本 | 使用 `'kind="bitflip"'`,通过真实 shell 测试 |
|
||||
| 默认值后紧贴英文标点,如容差后的问号 | 标点被叙述扫描器纳入默认值,number 变成 text | 标点与默认值分隔,实跑覆盖省略参数 |
|
||||
| 旋转、自定义门应用、追加、矩阵导出藏在对象方法里 | 命令行只能走很窄的 Bell 演示路径 | 补齐自由工具,保留既有作者对象方法 |
|
||||
| 重复「本方法返回句柄」等通用套话 | 满足比例却没有解释科学语义 | 移除旧填充,加入来源、单位、边界、预期和下一步 |
|
||||
| 缺源码归属与验证方式 | AI 知道怎么调用,却不知道怎么开发 | 各模块写新增配方/原语的修改位置、镜像和既有金样 |
|
||||
|
||||
## 同一个入口承担四个职责
|
||||
|
||||
使用路径是「打开根入口 → 根据科学问题选模块 → 复制完整实验 → 核对独立期望」。每个子入口也能单独冷启动,包括输入生产者、参数、结果形状、何时转到兄弟模块。
|
||||
|
||||
开发路径从最小必要变化开始:新实验组合已有工具;新酉矩阵使用 `gate.custom`;只有真实能力缺口才改原生实现。每个模块给出它负责的 Rust 文件、ABI 导出、中英镜像及应保留的测试。根入口的 `bell_analysis` 是这种开发方式的具体配方。
|
||||
|
||||
`bell_circuit` 返回可继续组合的电路;原有 `bell_phi_plus` / `贝尔态` 保留概率结果;新增 `bell_analysis` / `纠缠分析` 返回整体纯度、约化纯度、ZZ 关联和 Schmidt 数据。相同概率的经典混合不能冒充 Bell 纯态,所以不能只验证 00/11 概率。
|
||||
|
||||
工具入口继续是普通 `.mq.md` 函数。没有添加 Skill 编译器、MCP 包装、额外工具 manifest 或另一套 schema。符号与契约依靠现有解析和 `knowledge inspect`;符合 next/011 的简洁核心。
|
||||
|
||||
## 契约位置必须符合当前解析器
|
||||
|
||||
旧范式要求「返回表放在体末、返回标记前」,但 `src/parse/mod.rs::extract_function_contract` 只在首条可执行语句前提取参数与返回契约。放到 `cap.load` 之后的返回表会成为普通表,无法承担预期校验。
|
||||
|
||||
本轮以实现为准:参数表紧跟标题;返回表也位于首条执行语句之前;意图叙述仍可与后续执行步骤交错。对象构造器和方法同样补齐契约。叙述声明承载默认值,表说明类型和含义,不把 `any` 句柄伪装成新增的领域类型系统。
|
||||
|
||||
`check --narrative-ratio` 仍是最低门槛,但不再充当手册完成的唯一证据。测试同时检查每个可调用单元具有真正提取出的返回契约、参数无漂移,根符号只有三个实际实验工具。
|
||||
|
||||
## 只承诺已有能力
|
||||
|
||||
手册明确以下区别,而不把 next 的愿景写成已经实现的功能:
|
||||
|
||||
- `call`、跨进程 journal 会话、双后端和稳定符号查询已有实现。
|
||||
- 状态向量默认 12 比特、硬上限 16;密度和 Schmidt 最多六比特。
|
||||
- 理想态与概率忽略教学噪声;只有 `run` 采样施噪。
|
||||
- 密度矩阵构造检查形状和厄米性,不认证半正定与归一化。
|
||||
- Schmidt 熵使用自然对数;局部纯度和关联需要结合整体态解释。
|
||||
- `draw_state` / `画态` 补上现有 qsphere、multibloch 能力;高级态图换肤仍是 Q8c 规划。
|
||||
- `call --effects plugin` 允许绘图返回 SVG,但宿主仍禁文件写入;实际落盘走作者程序的 `run`。
|
||||
- 插件 journal 重放可能重复插件效果;会话不是无副作用的永久对象仓库。
|
||||
- 智能体决定持久交互分支和复杂自我改进并非本轮实现。
|
||||
|
||||
## 验证与推广条件
|
||||
|
||||
先构建 `marqdo_plugin_quantum`,再执行:
|
||||
|
||||
```bash
|
||||
cargo test --locked --test quantum_handbook
|
||||
cargo test --locked --test call_cli quantum_
|
||||
cargo test --locked --test gold ext_quantum -- --test-threads=1
|
||||
```
|
||||
|
||||
手册门禁直接提取双语源码中的 `sh` 围栏,经过 bash 执行原命令,逐次检查退出码与 JSON,不抄写另一份命令目录。作者程序也从 `marqdo` 围栏提取执行。两类示例都验证 Tree/Bytecode,并比较独立数学期望与中间结果;会话放在临时目录隔离。
|
||||
|
||||
组合工具另覆盖具名旋转门、矩阵导出、应用、追加和密度矩阵观察。既有 gold 继续覆盖公式、自定义门、噪声、振幅阻尼、作者方法与 SVG。
|
||||
|
||||
向其他扩展推广时,复用的是这些验证问题:陌生人能否独立启动、能否解释结果、能否找到修改归属、示例是否来自源码且持续执行。无需把 Quantum 的具体物理工具或新的模板套到每个库。
|
||||
@@ -88,7 +88,7 @@
|
||||
|
||||
## 4. 作者面 API
|
||||
|
||||
### 4.1 英文(`ext/quantum/quantum.mq.md`)
|
||||
### 4.1 英文(`ext/quantum/circuit/index.mq.md`)
|
||||
|
||||
在既有 `# circuit` / `# gate` 之外增加(或扩展方法):
|
||||
|
||||
|
||||
+28
-11
@@ -6,6 +6,7 @@
|
||||
| 日期 | 2026-08-12(初版)· 2026-08-28(Q7 · Q8 viz) |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [ext-web.md](ext-web.md) · [view.md](view.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| 安装(目标) | `marqdo ext add quantum`(中英:`quantum` / `量子`) |
|
||||
| 当前手册 | [根入口](../../ext/quantum/index.mq.md) · [中文入口](../../ext/quantum/量子/索引.mq.md) · [2026-11-08 优化记录](ext-quantum-handbook.md) |
|
||||
| 本文目的 | 锁定**作者面**、**模拟语义**、**view 可视化**与**分期**;指导 ABI 插件实现 |
|
||||
|
||||
---
|
||||
@@ -72,7 +73,7 @@ math 是**高中符号与曲线**;quantum 是**离散希尔伯特空间上的
|
||||
|
||||
1. **仅 ABI 插件接入**:`plugins/quantum` → `libquantum.so`;L1 在 `ext/quantum/*.mq.md`。
|
||||
2. **`ext/quantum/**` 禁止 `host_*`**;经 `plugin.native_path` + `plugin.load`(同 web/agent)。
|
||||
3. **中英分文件**:`quantum.mq.md` / `量子.mq.md`,**禁止**混排 API([stdlib-i18n.md](stdlib-i18n.md))。
|
||||
3. **中英分文件**:同一包 `ext/quantum/` 内英文模块树 + `量子/` 中文树,**禁止**混排 API([stdlib-i18n.md](stdlib-i18n.md))。
|
||||
4. **不改核心语法**;电路表单元格保持字面量;门名/比特下标由类方法解析。
|
||||
5. **模拟器有硬上限**(默认 ≤ 12 qubits);超限报错,不静默截断。
|
||||
6. **view 必须有专项展示**(结构卡 + 执行区 SVG),禁止只 dump JSON。
|
||||
@@ -81,17 +82,31 @@ math 是**高中符号与曲线**;quantum 是**离散希尔伯特空间上的
|
||||
|
||||
## 3. 布局与安装
|
||||
|
||||
Skill / tools 树(012 试点;契约 [ext-index-skill-tools.md](ext-index-skill-tools.md),范式 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md)):
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
quantum.mq.md # 英文类 API
|
||||
量子.mq.md # 中文类 API
|
||||
ext/quantum/ # 一个扩展包(同 web/ai:中英同目录)
|
||||
index.mq.md # EN 根 SKILL
|
||||
circuit/ · gate/ · simulate/ · state/ · density/ · viz/
|
||||
_capability/index.mq.md
|
||||
量子/ # ZH 根与模块(同等 skill 标准)
|
||||
索引.mq.md
|
||||
电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
|
||||
plugins/quantum/
|
||||
Cargo.toml
|
||||
src/lib.rs # ABI v2:线性代数 / 施门 / 画 SVG
|
||||
examples/quantum-bell/ # 规范示例(Q3)
|
||||
src/lib.rs # ABI v2
|
||||
examples/quantum-bell/
|
||||
tests/ext/quantum-*.mq.md
|
||||
```
|
||||
|
||||
安装产物(`~/.marqdo/ext` 或 `MARQDO_EXT`,**不是**仓库 `ext/` 源码树):
|
||||
|
||||
```text
|
||||
quantum/...
|
||||
native/libquantum.so
|
||||
quantum.plugin # 绝对路径提示;勿提交
|
||||
```
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_quantum
|
||||
marqdo ext add quantum
|
||||
@@ -101,11 +116,12 @@ marqdo ext add quantum
|
||||
|
||||
```markdown
|
||||
---
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
import:
|
||||
quantum: ext/quantum/circuit/index.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
或中文:`导入 量子:ext/quantum/量子.mq.md`。
|
||||
或中文:`导入 量子:ext/quantum/量子/电路/索引.mq.md`(根 skill:`ext/quantum/量子/索引.mq.md`)。
|
||||
|
||||
---
|
||||
|
||||
@@ -151,7 +167,7 @@ $$
|
||||
|
||||
## 5. 作者面 API(锁定草图)
|
||||
|
||||
### 5.1 英文 `ext/quantum/quantum.mq.md`
|
||||
### 5.1 英文 `ext/quantum/circuit/index.mq.md`
|
||||
|
||||
```markdown
|
||||
# gate
|
||||
@@ -198,7 +214,7 @@ $$
|
||||
|
||||
门方法返回**更新后的 circuit 句柄**(与 web `compose_*` 相同:`` `qc` = > `qc`.h qubit=0 *``)。
|
||||
|
||||
### 5.2 中文 `ext/quantum/量子.mq.md`
|
||||
### 5.2 中文 `ext/quantum/量子/`(根 `索引.mq.md`)
|
||||
|
||||
| 英文 | 中文 |
|
||||
|------|------|
|
||||
@@ -341,7 +357,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/circuit/index.mq.md
|
||||
---
|
||||
|
||||
# Bell |Φ+⟩
|
||||
|
||||
@@ -0,0 +1,227 @@
|
||||
# 扩展库开发范式:code = document = skill = tools
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active**(quantum 试点已落地;其它官方扩展按本范式推广) |
|
||||
| 日期 | 2026-11-06 |
|
||||
| 愿景 | [doc/next/012.md](../next/012.md)(手写真相源,本文不修改它) |
|
||||
| 契约摘要 | [ext-index-skill-tools.md](ext-index-skill-tools.md) |
|
||||
| 试点 | [`ext/quantum/`](../../ext/quantum/)(完成)· [`ext/web/`](../../ext/web/)(迁移中,含[布局范式](ext-web-layout-paradigm.md)) |
|
||||
| 相关 | [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [ext-quantum.md](ext-quantum.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [stdlib-i18n.md](stdlib-i18n.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
一份 `.mq.md` **同时是**可执行代码、给人读的文档、给智能体的 SKILL、以及可 `marqdo call` 的 tools 面。
|
||||
**函数即工具**(`##`),**子函数即子工具**(`###`)。禁止旁路 catalog / OpenAPI / MCP 包装成为第二真相源。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么这样设计
|
||||
|
||||
| 传统拆法 | 本范式 |
|
||||
|----------|--------|
|
||||
| README + SDK + tool schema 三套漂移 | 同一文件既可跑又可讲 |
|
||||
| Agent 调 MCP,作者调库 API | 智能体与作者共读同一路径;智能体默认 `marqdo call` |
|
||||
| 扩展 = 功能清单 | 扩展 = 可执行知识包:根 skill 先教会「怎么调」 |
|
||||
|
||||
智能体冷启动时只应:打开根 `index.mq.md` → 按「选哪条路」→ 照抄 `marqdo call`。不必发明第二套 API。
|
||||
|
||||
---
|
||||
|
||||
## 2. 包布局(强制形态)
|
||||
|
||||
一个官方扩展 **一个目录**(与 `web` / `ai` 一致)。中英 **同包分文件**,不要把中文树抬到 `ext/` 顶层变成「第二个包」。
|
||||
|
||||
```text
|
||||
ext/<id>/
|
||||
index.mq.md # EN 根 SKILL(先读)
|
||||
<module>/index.mq.md # 模块:## call 工具 + 可选 # 作者对象
|
||||
_capability/index.mq.md # 仅插件加载(日常勿当业务工具)
|
||||
<中文名>/ # ZH 镜像树(同等标准)
|
||||
索引.mq.md
|
||||
<模块>/索引.mq.md
|
||||
```
|
||||
|
||||
试点现状:
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
index.mq.md · circuit/ · gate/ · simulate/ · state/ · density/ · viz/
|
||||
_capability/
|
||||
量子/索引.mq.md · 电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
|
||||
```
|
||||
|
||||
安装后落在 `~/.marqdo/ext`(或 `MARQDO_EXT`),**不是**仓库源码 `ext/`:
|
||||
|
||||
```text
|
||||
~/.marqdo/ext/
|
||||
quantum/...
|
||||
native/libquantum.so
|
||||
quantum.plugin # 路径提示;勿提交源码树
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 根 skill 怎么写
|
||||
|
||||
根 `index.mq.md` / `索引.mq.md` 是冷启动入口,须按顺序包含:
|
||||
|
||||
1. **选哪条路**(表格,勿用 `1.` 列表——在 Marqdo 里 `1.` 是分支语法)
|
||||
- 只要演示结果 → 根上的编排工具(如 `bell_phi_plus` / `贝尔态`)
|
||||
- 要句柄继续 → 贴出分步 `call`(同一 `--session` + `--toget`)
|
||||
- 换语言 → 指向另一语言树,禁止混用 EN/ZH 工具名
|
||||
2. **如何执行任意工具**:固定 CLI 形状、`--effects plugin`、`--json`、`$name`
|
||||
3. **包布局**:每个模块路径 + 一句用途
|
||||
4. **可选一键编排工具**(如贝尔态):无参或极少参,便于验收
|
||||
|
||||
智能体默认路径是 `##` + `marqdo call`。`# circuit` / `# 电路` 等对象是 **作者程序** import 用的,须在根 skill 写明,避免代理误走方法链。
|
||||
|
||||
---
|
||||
|
||||
## 4. 模块文件怎么写
|
||||
|
||||
每个 `index.mq.md` 单独拿到也要能用:
|
||||
|
||||
| 块 | 要求 |
|
||||
|----|------|
|
||||
| 开篇叙述 | 领域是什么、何时打开本文件 |
|
||||
| For AI agents / 给智能体 | 可照抄的 `marqdo call`;缺能力时 **写明下一步打开哪个兄弟模块**(例如 circuit 造线后概率在 simulate) |
|
||||
| `##` 工具 | 形参契约表紧贴标题下;返回契约表也在首条执行语句前(当前解析器边界);叙述 ≥ 50% |
|
||||
| `#` 对象(可选) | 作者链式 API;加载插件走 facade(如 `cap.load` / `能力.加载`),禁止作者面 `host_*` |
|
||||
|
||||
薄实现:工具体调用 ABI(`*> quantum_…*`)或转发兄弟模块即可,真相在叙述与契约表。
|
||||
|
||||
---
|
||||
|
||||
## 5. `marqdo call` 与会话
|
||||
|
||||
```text
|
||||
marqdo call <FILE> <FUNCTION> [k=v…]
|
||||
[--json]
|
||||
[--effects none|plugin] # 默认 none;ABI 扩展必须 plugin
|
||||
[--session <id>]
|
||||
[--toget <name>] # 或尾部 toget <name>
|
||||
```
|
||||
|
||||
| 机制 | 用途 |
|
||||
|------|------|
|
||||
| `--effects plugin` | 允许 `plugin.call`;仍拒 fs/network/process/llm 等 |
|
||||
| `--session` + `--toget` | 跨进程保存返回值;`$name` 引用;plugin 句柄经 journal 重放 |
|
||||
| `parent.child` | 嵌套 `###` 子工具 |
|
||||
|
||||
参数字面量:数字、引号文本、True/False/None、以 `[`/`{` 开头的 JSON、或 `$name`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 叙述 ≥ 50%
|
||||
|
||||
```bash
|
||||
marqdo check --narrative-ratio ext/<id>/path/index.mq.md
|
||||
```
|
||||
|
||||
- 按函数单元计;契约表计为叙述;语言代码围栏计为代码。
|
||||
- 试点包 `ext/quantum/**` **零豁免**(含 `_capability` 与中文树)。
|
||||
- 狗粮 skill:`lib/lint/narrative.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 7. ABI 与 capability
|
||||
|
||||
- 原生能力只经 `plugin.native_path` + `plugin.load`(集中在 `_capability` / `能力`)。
|
||||
- 领域模块在工具开头调用 `cap.load` / `能力.加载`,**不**把 capability 当日常业务工具。
|
||||
- 遵守 ADR 0007:作者程序与 `ext/**` 业务面不写 `host_*` / `ensure_plugin` 垃圾抽屉。
|
||||
|
||||
---
|
||||
|
||||
## 8. 中英与导入
|
||||
|
||||
| 规则 | 做法 |
|
||||
|------|------|
|
||||
| 分文件 | EN 与 ZH 两套树;禁止同一文件混排 API 名 |
|
||||
| 同包 | `ext/<id>/` 内放中文子树,勿 `ext/<中文包名>/` 顶层并列 |
|
||||
| 作者导入 | `import: circuit: ext/quantum/circuit/index.mq.md` → `circuit.circuit` |
|
||||
| 中文导入 | `导入 量子:ext/quantum/量子/电路/索引.mq.md` → `量子.电路` |
|
||||
| 智能体 | 打开对应语言的根 skill,工具名与路径保持同语言 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 安装与源码卫生
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_<id> # 若有原生插件
|
||||
MARQDO_EXT_SOURCE=/path/to/repo/ext \
|
||||
marqdo ext add <id> # 装到 ~/.marqdo/ext
|
||||
```
|
||||
|
||||
| 禁止 | 原因 |
|
||||
|------|------|
|
||||
| `MARQDO_EXT` 指向仓库 `ext/` 再 `ext add` | 同文件 `fs::copy` 会清空源码;并写入 `*.plugin` / `native/` |
|
||||
| 提交 `ext/*.plugin`、`ext/native/` | 安装产物;已 gitignore |
|
||||
|
||||
`marqdo ext add` **拒绝**把安装根设成源码 `ext/`(防再踩坑)。
|
||||
|
||||
---
|
||||
|
||||
## 10. 常见陷阱
|
||||
|
||||
| 陷阱 | 正确做法 |
|
||||
|------|----------|
|
||||
| 正文写 `1. xxx` 当条目 | 用表格或项目符号;`1.` 是分支 |
|
||||
| 漏 `--effects plugin` | 根 skill 与模块 For AI 段反复写明 |
|
||||
| 只发 `circuit` 文件却找 `probabilities` | 在 circuit 的智能体段贴出 simulate 的完整 call |
|
||||
| 智能体去调 `#` 对象方法 | 根 skill「选哪条路」声明默认走 `##` call |
|
||||
| 中英混用 `新建` + `ext/quantum/circuit` | 选定一棵树用到底 |
|
||||
| 用「兼容层」大文件双挂 API | 删除;模块树即唯一面 |
|
||||
|
||||
---
|
||||
|
||||
Quantum 的完整实验、开发路线与源码示例门禁,见 [2026-11-08 手册修正](ext-quantum-handbook.md)。叙述比例是最低门槛,不能替代照抄执行与独立期望验证。
|
||||
|
||||
## 11. 开发验收清单
|
||||
|
||||
新扩展或把旧包迁到本范式时,逐项打勾:
|
||||
|
||||
- [ ] `ext/<id>/index.mq.md`:选哪条路 + call 形状 + 布局 +(可选)一键编排
|
||||
- [ ] 每个模块 `index.mq.md`:For AI agents 可单独照抄;缺能力时指向兄弟模块
|
||||
- [ ] 全部 `.mq.md`:`marqdo check --narrative-ratio` 通过
|
||||
- [ ] 需要 ABI:`_capability` 唯一加载;领域只调 facade
|
||||
- [ ] 中文:同包子树,路径与 ## 名全中文
|
||||
- [ ] `ext_cli` catalog 的 `mq_files` 列全 EN+ZH 源文件
|
||||
- [ ] 金样:`marqdo call` 一键工具 +(若有句柄)分步 `--session`/`--toget`
|
||||
- [ ] 作者 smoke:import 模块后的 `#` 对象链仍绿
|
||||
- [ ] 未把安装产物写进仓库 `ext/`
|
||||
|
||||
---
|
||||
|
||||
## 12. 智能体视角(试点自检)
|
||||
|
||||
任务「制备 Bell 态」时,合格根 skill 应使代理:
|
||||
|
||||
1. 打开 `ext/quantum/index.mq.md`(或中文 `量子/索引.mq.md`)
|
||||
2. 只要结果 → `bell_phi_plus` / `贝尔态`
|
||||
3. 要句柄 → 照抄 circuit→simulate 四条 call,同一 session
|
||||
|
||||
不必阅读 gate/density,不必发明 Python/MCP。
|
||||
|
||||
---
|
||||
|
||||
## 13. 推广顺序(建议)
|
||||
|
||||
1. **已完成试点**:`ext/quantum/`(含 `量子/`)
|
||||
2. **进行中**:`ext/web/` — 根 `index` + `layout` + 模块树 `page|route|…/index.mq.md` + 中文 `网页/`;作者门面 `web.mq.md`/`网页.mq.md` 保持兼容;call 金样与站点示例对齐继续补齐
|
||||
3. **下一优先**:`linalg` 公式面、`ai` agent 面
|
||||
4. **`ext/net` / `ext/data` / `ext/security`**:随 web 站点场景补根 skill,勿把 DB/鉴权 API 塞回 `web` facade
|
||||
|
||||
每迁一包:更新本文件「试点/推广」表与该包 `doc/design/ext-*.md` 布局节,并加 call 金样。
|
||||
**Web 特有**:布局工程必须写进包内 skill(见 [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md)),不能只放在外部 README。
|
||||
|
||||
---
|
||||
|
||||
## 14. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-11-06 | web:模块树 + `网页/` 镜像 + page session call 金样推进 |
|
||||
| 2026-11-06 | 初版:由 quantum 试点归纳的整包开发范式与验收清单 |
|
||||
@@ -7,7 +7,7 @@
|
||||
| ADR | [0007-web-document-endpoint.md](../adr/0007-web-document-endpoint.md) |
|
||||
| 讨论稿 | [doc/next/007.md](../next/007.md)(superseded) |
|
||||
| 安装 | `marqdo ext add web`(`web` / `网页`) |
|
||||
| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) |
|
||||
| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md) · [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) |
|
||||
|
||||
---
|
||||
|
||||
@@ -33,13 +33,17 @@
|
||||
|
||||
```text
|
||||
ext/web/
|
||||
web.mq.md · 网页.mq.md # facade: page route serve render inspect
|
||||
index.mq.md · 网页.mq.md # 根 skill(智能体先读;含布局铁律)
|
||||
layout/ · 布局/ # 文件划分布局工程 tools
|
||||
web.mq.md # EN facade: page route serve render inspect
|
||||
page.mq.md · route.mq.md · component.mq.md · dom.mq.md · client.mq.md
|
||||
ext/net/ http.mq.md · websocket.mq.md · url.mq.md
|
||||
ext/data/ db.mq.md · cache.mq.md · storage.mq.md
|
||||
ext/security/ auth.mq.md · oidc.mq.md · rbac.mq.md
|
||||
```
|
||||
|
||||
**布局工程**(反 HTML/CSS 注入):见 [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md);包内 `ext/web/layout/index.mq.md`。
|
||||
|
||||
作者入口通常:
|
||||
|
||||
```text
|
||||
@@ -62,8 +66,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
|
||||
@@ -76,6 +81,7 @@ Welcome to the executable web.
|
||||
| `type` | `类型` | `web` / `网页` |
|
||||
| `route` | `路由` | 路径,可含 `{param}` |
|
||||
| `method` | `方法` | 默认 `GET` |
|
||||
| `view` | `视图` | 可选 main:启动时执行主程序,返回递归 View 节点;不与自动 data_source 绑定混用 |
|
||||
| `title` | `标题` | 文档标题 / `<title>` |
|
||||
| `data_source` | `数据源` | 表名 |
|
||||
| `data_order` | `排序` | 如 `-created_at` |
|
||||
@@ -92,6 +98,8 @@ Welcome to the executable web.
|
||||
| title | title | Marqdo | | title |
|
||||
```
|
||||
|
||||
2026-11-08:View 已支持 row/column 容器与 markdown 叶子,容器值保持子表;显式 `view: main` Document 通过普通函数装配。完整工程见[布局实践](ext-web-layout-paradigm.md),实现边界见[优化说明](ext-web-handbook.md)。
|
||||
|
||||
`page.render nodes=` 是**唯一**主装配路径。禁止 `compose_main` / `compose_intro` 等碎片 DSL。
|
||||
|
||||
---
|
||||
@@ -106,7 +114,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 …**
|
||||
@@ -189,6 +198,7 @@ Middleware 一等:`web.use` / `route.use`,表驱动;**禁止** `configure(
|
||||
| A6 | 禁止恢复 `compose_*` / `app.configure` / god page 变异堆 |
|
||||
| A7 | 能力只许迁移/提升;删除须本设计明示 + tests 同步 |
|
||||
| A8 | 设计未锁定处停工提问,禁止自行发明 DSL |
|
||||
| A9 | **文件划分布局**:页面拆到简单组件文件为止;默认禁止整页 HTML/CSS 注入(`dom.raw`/`page.css` 仅逃逸舱) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -49,7 +49,8 @@
|
||||
英文:
|
||||
|
||||
```markdown
|
||||
import web:ext/web/web.mq.md
|
||||
import:
|
||||
web: ext/web/web.mq.md
|
||||
|
||||
# main
|
||||
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
# Web:可执行手册与递归布局工程
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 日期 | 2026-11-08 |
|
||||
| 使用与开发入口 | [英文 index](../../ext/web/index.mq.md) · [中文索引](../../ext/web/网页/索引.mq.md) |
|
||||
| 工程规范 | [布局拆分](ext-web-layout-paradigm.md) |
|
||||
| 参考工程 | [英文](../../examples/web-layout-handbook/index.mq.md) · [中文](../../examples/web-layout-handbook-zh/index.mq.md) |
|
||||
| 自动验收 | [源手册与活站点](../../tests/web_handbook.rs) · [浏览器布局](../../tests/web/layout.browser.cjs) |
|
||||
| 思想来源 | [next/010](../next/010.md) · [next/011](../next/011.md) · [next/012](../next/012.md) · [Quantum 优化](ext-quantum-handbook.md) |
|
||||
|
||||
## 原有规范为什么没有落实
|
||||
|
||||
原有 Web skill 已写「拆到简单」,但缺少可沿着文件树复现的工程。原生 `RenderNodes` 仅渲染平面 title/text/link/html;拼接两张表只产生兄弟节点,不会产生双栏。`serve` 又只把 Document 正文当 Markdown,没有执行文档里的组件装配。只加强口头禁止 HTML,无法补上这些实际缺口。
|
||||
|
||||
本轮以一个完整首页检验规范:导航、主体、页脚分开;页脚拆品牌与链接;链接再拆文档与社区。所有末端 content.md 都是普通 Markdown。每个父 index.mq.md 只负责其下一层排列关系。
|
||||
|
||||
## 使用同一份 View 表表示父与叶
|
||||
|
||||
沿用 `type | slot | value | attrs | style`,不新增核心语法、不建立第二套布局方言:
|
||||
|
||||
| 类型 | 值列 | 含义 |
|
||||
|------|------|------|
|
||||
| markdown / 正文 | Markdown 文本 | 内容叶子 |
|
||||
| row / 横排 | 子节点列表 | 响应式分栏 |
|
||||
| column / 纵排 | 子节点列表 | 上下排列 |
|
||||
| nav/header/footer/section/aside | 子节点列表 | 语义区域 |
|
||||
| 既有 title/text/link/html | 兼容原值 | 保留旧节点行为;html 为显式兼容边界 |
|
||||
|
||||
纯 `component.markdown` / `正文` 与 `component.wrap` / `包裹` 构造节点,`layout.stack` / `纵排` 和 `layout.columns` / `分栏` 声明几何。`merge` 接受 @ 记录列表,确定兄弟顺序并保留嵌套值;不再声称它会自动归一化所有列式表或把平面表变成双栏。
|
||||
|
||||
递归渲染保留节点类型,不把子表转成 `map[...]` 字符串。原生渲染器诊断无效子节点、列长不等和过深嵌套。运行时固定的布局样式提供基础响应式几何,样式列继续是类名引用,并非 CSS 编译器。叶子正文经过既有 Markdown 渲染器。
|
||||
|
||||
## 显式 Document 装配
|
||||
|
||||
普通 `type: web` 保留既有 Markdown/数据源路径。需要结构化页面时显式增加 `view: main`(中文 `视图: main`),普通 `# main` 返回 View 节点列表。`serve` 在启动时通过已有 `run_artifact` 回调执行装配,用与离线预览相同的渲染器生成文档,不再套入旧站点的另一份导航/页脚壳。
|
||||
|
||||
这是启动时装配,修改内容后重启;不声称具备自动请求期模板绑定。装配函数不再次调用渲染器或启动服务器。请求期业务仍用 Endpoint。自动 `data_source` 绑定使用普通 Document;与 `view: main` 混用会明确报错,避免静默忽略数据源。
|
||||
|
||||
`web.inspect root=...` / `网页.检视 根=...` 新增离线扫描入口,不启动进程也不执行组件。空应用的新进程无法读取另一个活进程的私有路由;手册不再将此作为活站点检视方法。检视结果加入 `_type: web_inspection`,使不同长度的 declared/system 列表保持对象语义,而不被 JSON 边界当作列式表。
|
||||
|
||||
## 手册与工具一致
|
||||
|
||||
另修复既有元数据型 Endpoint 在 Bytecode 没有函数时误报编译错误的问题:与 Tree 共用声明摘要路径,普通无入口程序仍然拒绝执行。
|
||||
|
||||
全部 Web 模块清理说明性伪函数,参数和返回契约均放在执行前;对象 API 保留。纯 DOM 构造与客户端描述不再无故加载插件。命令示例保护文本引号与会话美元引用。布尔/数字默认值与相邻标点分开,保证真正省略参数时仍符合契约。
|
||||
|
||||
原 `accept_component` 仅根据名称和职责就返回 ok=True,无法代表实际验收。现在返回明确的 checklist 状态,实际验收依据源码职责、渲染结构和运行结果。`site_playbook` 讲流程,`preview_markdown` / `preview_nodes` 给真实预览,不再把增加叙述字数当作完成指标。
|
||||
|
||||
## 验证
|
||||
|
||||
```bash
|
||||
bash scripts/build-web-plugin.sh
|
||||
cargo test --locked --test web_handbook
|
||||
cargo test --locked --test call_cli web_
|
||||
cargo test --locked --test gold ext_web -- --test-threads=1
|
||||
```
|
||||
|
||||
手册门禁直接执行 18 份包内入口的双语 sh 围栏,在 Tree/Bytecode 共执行 80 次命令;同样执行根手册的作者程序。参考工程的双语双后端检查实际预览、启动服务,核对首页与预览相同、关于页仍走普通 Document、API 正常返回 JSON;不把路由声明误当作已经监听。
|
||||
|
||||
浏览器检查可对参考预览或活站点执行,按环境指定现有 Playwright 模块和 Chromium:
|
||||
|
||||
```bash
|
||||
node tests/web/layout.browser.cjs /absolute/path/to/preview.html
|
||||
```
|
||||
|
||||
它测量 1440px 下的外层与内层双栏、390px 下的两层纵向折叠,并检查无横向溢出。无需外部资源或业务 JavaScript。Go 单元测试覆盖递归 Markdown、顺序、带类型列式表、错误形状与 Document 显式执行边界。
|
||||
|
||||
既有 Anlian 渲染测试已从硬编码个人数据库改为临时目录建表并注入已知数据,使完整 Go 套件无需个人站点状态。
|
||||
|
||||
Web 提交时,全库 Rust 为 436 通过、25 项既有策略/回放失败,基线失败集合相同。后续已单独修复 Rust→Lean 命令缺字段的问题:所有操作发送完整的 op、steps、value,进程错误保留退出码与 stderr。原 25 项失败全部消除,新增诊断回归后库级测试为 462 通过、0 失败。策略判定仍由 Lean 执行。
|
||||
@@ -0,0 +1,65 @@
|
||||
# Web 布局工程:先拆布局,直到 Markdown 叶子
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 状态 | Active,2026-11-08 可执行参考工程与浏览器门禁已落地 |
|
||||
| 包内手册 | [英文根入口](../../ext/web/index.mq.md) · [中文根入口](../../ext/web/网页/索引.mq.md) |
|
||||
| 布局工具 | [layout](../../ext/web/layout/index.mq.md) · [布局](../../ext/web/布局/索引.mq.md) |
|
||||
| 实现与边界 | [Web 手册优化](ext-web-handbook.md) · [Artifact](ext-web-artifact.md) · [ADR 0007](../adr/0007-web-document-endpoint.md) |
|
||||
|
||||
## 先建立区域树,再写内容
|
||||
|
||||
首页先拆成导航、主体、页脚。页脚若有左右两栏,拆成品牌与链接;链接区若还有双栏,再拆成文档与社区。继续按内部独立布局拆分,直到叶子只剩简单 Markdown 可以直接表达的内容。
|
||||
|
||||
```text
|
||||
index.mq.md → components/index.mq.md(纵排)
|
||||
├─ nav/index.mq.md → content.md
|
||||
├─ main/index.mq.md → content.md
|
||||
└─ footer/index.mq.md(分栏)
|
||||
├─ brand/index.mq.md → content.md
|
||||
└─ links/index.mq.md(分栏)
|
||||
├─ docs/index.mq.md → content.md
|
||||
└─ community/index.mq.md → content.md
|
||||
```
|
||||
|
||||
父文件只导入子块、合并兄弟节点并声明一层排列。叶子文件只说明一种内容职责;内容较长时,使用相邻的普通 content.md,避免字符串转义。拆分终点不是行数或文件数量,更不是每句话建一个文件。
|
||||
|
||||
## 何时继续拆、何时停止
|
||||
|
||||
| 观察 | 决定 |
|
||||
|------|------|
|
||||
| 导航、正文、页脚混在一个内容块 | 拆成父级装配和三个职责块 |
|
||||
| 页脚内部仍同时负责品牌与链接排布 | 再拆左右子块 |
|
||||
| 链接子块内部仍包含两个独立栏目 | 继续拆到各栏目 Markdown |
|
||||
| 叶子只包含标题、段落、列表、链接、表格、图片 | 停止;已可用普通 Markdown 表达 |
|
||||
| 父文件含大量正文、HTML 标签、CSS 字符串 | 职责或表达方式仍未收敛,继续拆解 |
|
||||
| 结构已经简单,只为减少行数而再拆 | 不必拆;以可读职责为准 |
|
||||
|
||||
表单、数据源、交互各有自己的领域职责,应调用对应模块,不以“Markdown 不表达交互”为由恢复整页 HTML 壳。只有确实需要兼容宿主能力时,才在隔离边界使用已有 raw/css 接口并说明原因。
|
||||
|
||||
## 同一表结构贯穿所有层
|
||||
|
||||
公共列是 `type | slot | value | attrs | style`,中文可用 `类型 | 槽 | 值 | 属性 | 样式`。使用 @ 记录表产生节点列表。
|
||||
|
||||
- `component.markdown` / `组件.正文`:叶子值为普通 Markdown。
|
||||
- `component.wrap` / `组件.包裹`:值中保留子节点列表,可标记 nav/footer/section 等语义区域。
|
||||
- `layout.stack` / `布局.纵排`:声明上下关系。
|
||||
- `layout.columns` / `布局.分栏`:声明响应式横向栏目。
|
||||
- `merge`:只确定兄弟顺序,不会自动产生双栏,也不提前渲染 HTML。
|
||||
|
||||
原生运行时提供基本布局几何,窄屏自动折叠。style 列引用类名,不承载 CSS 源码,也不会自动定义主题。父块始终保留结构值;先渲染子块再拼 HTML 会丢失这条统一路径。
|
||||
|
||||
## 从文件走到真正页面
|
||||
|
||||
[英文参考工程](../../examples/web-layout-handbook/index.mq.md)与[中文参考工程](../../examples/web-layout-handbook-zh/index.mq.md)实现上面的整个拆分树。先运行 preview.mq.md 检查真实渲染,再进入工程目录运行 serve.mq.md。
|
||||
|
||||
结构化 Document 显式声明 `view: main` / `视图: main`,main 返回节点;服务启动时装配一次。普通 Markdown Document 保留既有行为,Endpoint 单独处理请求期互动。改动结构或叶子内容后重启。自动数据源绑定继续使用普通 Document,避免与启动装配混用。
|
||||
|
||||
验收同时检查源码和产物:叶子只含普通 Markdown,父文件只表达其一层关系;桌面页脚出现真正的两层分栏,手机两层都折叠;关于页、API 仍能工作。规则清单本身不是“已经通过”的证明。
|
||||
|
||||
```bash
|
||||
cargo test --locked --test web_handbook
|
||||
node tests/web/layout.browser.cjs /absolute/path/to/preview.html
|
||||
```
|
||||
|
||||
详细测试方式和当前能力边界见[优化记录](ext-web-handbook.md)。
|
||||
+16
-14
@@ -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
|
||||
|
||||
@@ -214,19 +214,23 @@ template = ["php", "-r", "{inline}"]
|
||||
|
||||
### 4.1 值映射
|
||||
|
||||
Canonical integer contract: [`v-safe-json.md`](v-safe-json.md) (Lean \(V_{\mathsf{safe}}\): `|n| ≤ 2^{53}-1`).
|
||||
|
||||
| Marqdo | JSON |
|
||||
|---|---|
|
||||
| None | null |
|
||||
| Bool | bool |
|
||||
| Int | number |
|
||||
| Num | number(NaN/Inf → null) |
|
||||
| Text | string |
|
||||
| List | array |
|
||||
| Map | object |
|
||||
| Int | number **仅当** `|n| ≤ 2^{53}-1`;越界 → 显式失败(禁止静默扭曲) |
|
||||
| Num | number(NaN/Inf → null);float 为宿主扩展,∉ mechanized \(V_{\mathsf{safe}}\) |
|
||||
| Text | string(宽整数用十进制字符串过桥,对端 `BigInt` / Python `int`) |
|
||||
| List | array(子树递归;任一越界整数使整体失败) |
|
||||
| Map | object(同上) |
|
||||
| Formula | 矩阵 → 二维数组;其它 → 数字或字符串 |
|
||||
| Code | 源码字符串 |
|
||||
| Secret | JSON 中 `<secret>`;`env` 显式交付时取真实值 |
|
||||
|
||||
错误前缀:`json: integer outside V_safe (±(2^53-1)): <n>`。
|
||||
|
||||
### 4.2 输入
|
||||
|
||||
- `input=` → JSON;写 stdin;同时提供 `MARQDO_INPUT`(≤8 KiB)与 `MARQDO_INPUT_FILE`(任意大小)。
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# 外联库论文的研究方向
|
||||
|
||||
作者于 2026-11-05 将论文主线明确为:**叙述本身是程序,外部代码是值**。
|
||||
Marqdo 的外联库用于在这一宿主模型中组合既有语言的计算能力,统一说明、控制流、
|
||||
代码复用、状态与显式数据交换。论文应先解释 Notebook/文学编程中的实际设计问题,
|
||||
再给出解决方案、可核验的收益、形式化依据和应用实验。
|
||||
|
||||
后续实现工作围绕绑定的代码值、参数化调用、持久会话、复制值和文档计划展开。
|
||||
生命周期、值域和重放机制为这个统一设计提供保证;不能将重放检查器重新提升成
|
||||
取代外联库与叙述式编程的论文主题。不得把未测的人因优势或未证明的实现正确性
|
||||
写成既成事实。
|
||||
|
||||
完整方向文件在论文工作区:
|
||||
|
||||
- 方向(当前):`MarqdoThesis/PLDI/design/V7-NARRATIVE-FIRST-DIRECTION-2026-11-05.md`
|
||||
- v6 方向(历史):`MarqdoThesis/PLDI/design/V6-NARRATIVE-FIRST-DIRECTION-2026-11-05.md`
|
||||
- 证据映射:`MarqdoThesis/PLDI/design/V6-EVIDENCE-MAP-2026-11-05.md`
|
||||
- 章节与页预算:`MarqdoThesis/PLDI/design/V6-OUTLINE-2026-11-05.md`
|
||||
|
||||
当前稿位于 `MarqdoThesis/PLDI/paper-v7`;v6 保留,历史 v5 及其证据保留。方向文件取代了
|
||||
此前把论文缩成“外联会话值 + 因果重放”的 N3 路线:重放是支撑机制,不是主线。
|
||||
|
||||
2026-11-05 交付:`MarqdoThesis/PLDI/paper-v7/main.pdf`,正文(含 AI Use)20 页。
|
||||
v6 保留为上一版尝试;更早的 v6 草稿保留在 `paper-v6-draft-2026-11-05/`。
|
||||
@@ -0,0 +1,44 @@
|
||||
# Foreign Strong: Lean ↔ host correspondence
|
||||
|
||||
2026-11-02 补充:`ForeignSource.lean` 对显式局部环境、返回、函数调用/递归、
|
||||
分支和有界 while 的源解释器与独立 effect 编译器证明一般精化,并推出安全
|
||||
观察和旧句柄不可复活。`CheckForeignSource.lean` 消费真实加载后 AST 的显式
|
||||
适配格式,用独立 counter oracle 对照 tree/bytecode 的返回、journal、fault
|
||||
与故障后 n。它已用于发现并修复 tree 的父词法作用域查找缺陷。
|
||||
这是源控制流层的证明与实现 translation validation;Rust parser/adapter、
|
||||
全部 AST 构造、机器数值运算和物理调度的完整 refinement 仍须完成。
|
||||
模型中的 fuel 是分析界限,不能称为真实程序必然终止或有界取消。
|
||||
|
||||
Pinned with PLDI Strong / paper-v5 (sessions as values; three gates).
|
||||
Marqdo **2.3.0** host implements the same objects the Lean development decides.
|
||||
|
||||
| Lean / paper rule | Host surface | Evidence |
|
||||
|---|---|---|
|
||||
| `SessionReg` + `sessionOpen` / `Close` / `sessionEval` | `HostContext.foreign_sessions` + `Value::Handle` | `DocCalc.lean` S1–S6, `requires_live`; `foreign_session.rs` |
|
||||
| `Ω(s, τ, c)` | Persistent kernel + process order | Oracle journal `(cell, source_hash, stdout, result)` |
|
||||
| `SafeVal` / Encode / Decode | `src/host/json.rs` + bootstrap sanitize | `ForeignJSON.lean`; gold `foreign-*-vsafe-*` |
|
||||
| Handle ∉ \(V_{\mathsf{safe}}\) | `value_to_json(Handle) → Err` | `foreign-session-handle-no-serialize.mq.md` |
|
||||
| Closed / Closed-Close | use-after-close / double-close `Err` | gold misuse; `sessionClose_then_eval_none_w` |
|
||||
| Oracle-Domain | Ω OOD integer → host `Err` | `foreign-session-result-vsafe-refuse.mq.md` |
|
||||
| Table arity stuck | Parse refuse unequal GFM; JSON unequal columns | `Surface.lean`; `tests/errors/table-arity.mq.md` |
|
||||
| Snapshot hash match/mismatch | `view/output.rs` `snapshot_page` | unit snapshot hash tests |
|
||||
| **Thm. corr** (`corr_fresh_functional`) | Cold `evaldoc`; step values = Ω | `corr_step_eq_omega`; `corr_doc_fresh_foreign`; foreign-session gold |
|
||||
| `OracleJournal` / `replayCheck` | `oracle_journal` + `DocumentSession::replay_check` | `replayCheck_*`; fate R1–R3 |
|
||||
| `corr_fail_warm_store` / `corr_fail_reordered_plan` | cold vs warm / schedule order | DocCalc witnesses; Table corr-fail |
|
||||
| Dual-backend differential | `tests/gold.rs` tree + bytecode | 308 × 2; foreign session/V_safe subset |
|
||||
|
||||
## Scope (not distance)
|
||||
|
||||
- SafeVal mechanization covers the **integer** fragment; finite floats are admitted by the host under the same refuse-not-coerce bridge policy for non-integers already in SafeVal.
|
||||
- Session discipline is a **dynamic registry** (affine close + borrow-use). Static linear types over OS-killable processes are out of scope by design, not an unfinished host feature.
|
||||
- Correspondence is mechanized for the **closed / fresh-open / functional-Ω** fragment (`corr_fresh_functional`): per-step interactive value = Ω answer, interactive runner = normative runner, `replayCheck` on the journal. Broken hypotheses are `corr_fail_*`. Host discharge is foreign-session gold plus R1–R3, not R1–R3 alone.
|
||||
|
||||
## Reviewer-driven implementation update (2026-11-01)
|
||||
|
||||
The independent live cursor and multisession action-plan simulation are in
|
||||
`DocCalc.runForeignLive_simulation` and `MarqdoProof.ForeignTrace`. The language
|
||||
now exposes oracle observations and pure journal comparison through
|
||||
`foreign.oracle_journal` / `foreign.replay_check`. Strict interactive snapshot
|
||||
replay uses the full oracle history with source identity and per-step input.
|
||||
See `oracle-journal-values.md` for the API and the research experiment manifest
|
||||
under `PLDI/experiments/reviewer-v5/` for exact source hashes and actual runs.
|
||||
@@ -0,0 +1,336 @@
|
||||
# Executable call and integer semantics
|
||||
|
||||
This describes the implementation contract exercised by
|
||||
`src/frontend_elaboration_tests.rs`; it is not a claim of a verified parser.
|
||||
|
||||
All explicit actual arguments evaluate once in authored order, including extra
|
||||
named arguments whose values the callee does not read. Binding then permutes
|
||||
already computed values into parameter slots. Named arguments take precedence
|
||||
over positional filling; duplicate names and excess positional arguments fail.
|
||||
A duplicate-actual binding fault occurs only when its call is reached, after
|
||||
all explicit actuals have evaluated; it cannot reject an unused function at
|
||||
compile time or erase an earlier argument effect.
|
||||
Local calls and imported calls use the same order. Builtins and host primitives
|
||||
must not reorder expression evaluation when selecting their parameter values.
|
||||
|
||||
All supplied parameters are available before defaults. Missing defaults execute
|
||||
in parameter declaration order, once per call, in the target definition's
|
||||
module and lexical scope. A default can see supplied parameters, earlier
|
||||
computed defaults, and an explicitly bound method receiver. It cannot capture
|
||||
the caller's locals. A still omitted later parameter is unbound. Explicit None
|
||||
is a supplied value and never triggers a default. Required-argument validation
|
||||
precedes default execution. Default expressions participate in receiver
|
||||
classification, dependency analysis and transitive effect inference.
|
||||
|
||||
A dynamic method's signature belongs to the resolved receiver and selected
|
||||
method; a different object's same-named method cannot supply its parameter
|
||||
list. Imported definitions retain their module scope. A compiled document's
|
||||
entry is selected only from its own module; an imported `main` is not an entry.
|
||||
|
||||
The bytecode retains argument names and explicit presence bits. Callee
|
||||
prologues evaluate defaults in their own frame. Local slots distinguish an
|
||||
unbound slot from a slot holding None. Local, constant, call-layout and jump
|
||||
indices use container-sized indices rather than unchecked 8/16-bit casts.
|
||||
Scratch slots are reused across sequential calls while pending outer actuals
|
||||
remain live. Scalar constant interning uses a hash table; floating constants
|
||||
are keyed by their exact bits.
|
||||
|
||||
Host integers are signed 64-bit values. Add, subtract, multiply, divide and
|
||||
negation report a language error on overflow in every build profile; division
|
||||
by zero is a separate error. Division truncates toward zero. The negative
|
||||
endpoint has a valid signed literal. Float-to-int conversion rejects nonfinite
|
||||
or out-of-range inputs instead of silently saturating. This local integer
|
||||
domain is distinct from the narrower continuous foreign-copy domain.
|
||||
|
||||
The Lean call-combinator proof preserves complete interaction programs for
|
||||
arbitrary argument evaluators, including failure and reply-dependent requests.
|
||||
The integer model specifies exact arithmetic followed by representability
|
||||
checking. Native documents, independently derived Python expectations, a Lean
|
||||
arithmetic consumer and isolated source mutations validate the implementation
|
||||
links. These do not prove the entire Rust parser, binder, object representation
|
||||
or adapter. The research coverage ledger must keep those obligations explicit.
|
||||
|
||||
## Module identity, entry inputs and source-bound invocation
|
||||
|
||||
Instances retain the existing map representation and safe-copy domain. The
|
||||
reserved `_type_module` field is a list of import binding names, paired with
|
||||
`_type`. Class selection uses that module instance within the active import
|
||||
tree; inherited methods resolve their bases in the defining module. Equal
|
||||
class names in different imports remain distinct. These fields are ordinary,
|
||||
forgeable data, not capabilities or globally portable nominal identities.
|
||||
Round trips through Python/Node preserve these descriptors in the same module
|
||||
context. Opaque session handles remain outside the copy domain.
|
||||
|
||||
Entry metadata is passed to `Vm::run`, never compiled into `main`'s body.
|
||||
Explicit named/recursive invocations of `main` therefore keep their own inputs.
|
||||
Defaults run with the invocation's actual registry; a session-valued default
|
||||
must not be evaluated in a separate interpreter and then injected into a VM.
|
||||
Reads appearing only in explicit/prose defaults participate in input inference
|
||||
and effect analysis. Default failures use the parameter declaration's span.
|
||||
Source-bound APIs preserve the selected declaration's source identity and
|
||||
span, even when two declarations have the same dotted path. Textual path calls
|
||||
retain the existing first-declaration rule. Duplicate parameter names are
|
||||
rejected because they cannot define distinct binding slots.
|
||||
|
||||
Both backends retain parameter, return and local field contracts. Bytecode
|
||||
checks supplied/defaulted inputs before the body, explicit returns before
|
||||
returning, table bindings before writing a local and direct footnote accesses
|
||||
before/after lookup. Unknown fields report the contract error before a generic
|
||||
missing-key error. Entry/raw invocations also check their completed inputs.
|
||||
Contract diagnostics retain the declaration quote and the failure location.
|
||||
|
||||
## Refinement obligations and current evidence
|
||||
|
||||
| Link | Mechanized result or implementation evidence | Remaining obligation |
|
||||
|---|---|---|
|
||||
| Raw Markdown to executable AST | Native explicit/prose defaults, source snapshots, parameter spans, inference and duplicate-parameter diagnostics | Prove the actual Rust classifier/parser and extraction rules; the older abstract grammar is not that proof |
|
||||
| Loaded module tree to flattened declarations | Independent inventories of source digests, module instances, lexical parents, class/method ownership and resolved bases | Connect the actual resolver to the Lean namespace lookup model, including failed/ambiguous resolution |
|
||||
| Effectful actual evaluation to parameter values | `FrontendCalls` proves interaction-program equality for arbitrary expression evaluators; native authored-order/unused-actual/builtin/foreign probes | Prove Rust scratch allocation, every expression case and its stack invariant against that combinator |
|
||||
| Default evaluation and invocation inputs | Native callee-scope, presence, receiver, entry/raw/metadata, inference, error-span and stateful-session cases | A complete default-binding semantics and universal compiler refinement, including errors and host context |
|
||||
| Module-qualified object dispatch | `ModularObjects` proves namespace flattening lookup, resolved-parent dispatch and safe descriptor round trips | Connect every real object constructor, resolver and copied descriptor to the model; justify Rust module-root lifetimes |
|
||||
| Machine integers | `MachineInts` exact signed-64 model, checked boundary implementation, independent Python and Lean consumers | Connect Rust checked arithmetic and every conversion to the mathematical evaluator; floats remain an extension |
|
||||
| Progressive contracts | Four real source boundary failures preserve codes, anchors and failure spans; valid contract execution | Universal contract-preservation theorem and imported declaration/call-site attribution |
|
||||
| Source-bound external calls | Two same-path declarations execute their separately selected source lines on both backends | Full external argument validation, effect-policy and environment-injection refinement |
|
||||
|
||||
The ledger deliberately does not turn a new model lemma, a finite passing
|
||||
corpus, or independent reconstruction into a complete frontend theorem. Those
|
||||
remaining proof links are required to discharge the full frontend objective.
|
||||
|
||||
## Default prologue proof and imported contract attribution (November 4)
|
||||
|
||||
`DefaultPrologue.default_prologue_refines` relates source default binding, which
|
||||
rechecks the current environment for omission, to a guarded block machine with
|
||||
an immutable initial presence mask. It proves whole interaction-program equality
|
||||
for arbitrary effectful evaluators, assuming distinct parameter slots and an
|
||||
initially faithful presence mask. Earlier default stores preserve that invariant
|
||||
for later parameters. The duplicate-slot counterexample issues two requests in
|
||||
the machine versus one in the source, demonstrating why slot uniqueness matters.
|
||||
Explicit None skips and immediate failure stopping are separately checked.
|
||||
This is a model of guard/evaluate/store blocks, not a proof of the Rust emitter,
|
||||
flat instruction stepping, actual expression compilation or parser.
|
||||
|
||||
The generated implementation family crosses all 27 omitted/int/None states for
|
||||
three parameters with all six declaration orders. An independent environment
|
||||
model checks 162 documents and 324 executions, including 34 faults when a default
|
||||
reads a later omitted parameter. Source text is reconstructed independently;
|
||||
expected traces are not derived from either backend. This finite family does
|
||||
not prove arbitrary defaults. Imported argument-contract diagnostics now retain
|
||||
the caller's failure span and source revision while pointing the declaration
|
||||
anchor and suggestion at the actual library. Supplied and defaulted invalid
|
||||
arguments both refuse before entering the callee body.
|
||||
|
||||
## Concrete name and flat-code interfaces
|
||||
|
||||
The compiler now borrows each original declaration and owning module while
|
||||
flattening. Bare-call selection uses the same source `lookup_local` operation
|
||||
as Tree, then maps the selected declaration identity to its flat index. This
|
||||
removes a second, subtly different lookup algorithm: repeated top-level names
|
||||
previously selected the first declaration in Tree but failed compilation in VM.
|
||||
It does not prove the source lookup operation itself.
|
||||
|
||||
`NameSlots` proves reads, writes and the complete named-argument binding fold
|
||||
commute with an injective local-name vector. Unknown names and repeated raw
|
||||
API names are covered; repeated raw names retain last-write semantics. A
|
||||
presence mask computed from initialized slots is faithful by construction.
|
||||
The Rust raw entry and argument binder now derive their mask from the actual
|
||||
initial logical slots. Method receiver aliases are overlaid only for default
|
||||
evaluation, and restored into the body frame after logical argument checks.
|
||||
`ReceiverDefaults` supplies the additional environment reasoning for explicitly
|
||||
declared self/自 parameters; the slot theorem alone does not cover that case.
|
||||
|
||||
Every compiled Program is structurally verified before return, and the VM
|
||||
verifies even publicly constructed/mutated Programs before any instruction.
|
||||
All current opcode variants are handled exhaustively. Checks include operand
|
||||
bounds, parameter/local prefix and injectivity, declaration and inheritance
|
||||
forests, call-layout and function references, spans, reachable stack underflow,
|
||||
branch/loop join heights and absence of leaked stack values on return. Missing
|
||||
variable values remain language faults; this checker does not prohibit them.
|
||||
|
||||
Rust exports the computed per-PC heights alongside the real emitted opcode
|
||||
text. `CheckFlatCertificate.lean` independently decodes that text and applies
|
||||
an executable checker whose soundness is proved in `FlatCertificate`. Accepted
|
||||
certificates preserve heights along every finite path and guarantee a valid
|
||||
fetch with sufficient operands on each reachable PC, including loop prefixes.
|
||||
The independent reader rejects unmodeled opcodes. Rust debug serialization and
|
||||
opcode-to-concrete-VM-step correspondence remain interfaces to justify; a
|
||||
structural certificate does not establish source/bytecode functional equality.
|
||||
|
||||
Neither this ordinary bytecode verification technique nor reuse of a resolver
|
||||
is an originality claim. Complete functional lowering, parser semantics and the
|
||||
Rust implementation correspondence remain open proof obligations.
|
||||
|
||||
## Functional expression checks and receiver views (November 4)
|
||||
|
||||
The emitter now records source-directed expression rules before emission, with
|
||||
child order and exact instruction intervals. The mandatory native verifier
|
||||
checks literal identity (including floating-point bits), local names, unary and
|
||||
binary operators, short-circuit targets, interpolation, collections, indexing
|
||||
and occlusion. Calls delegate staging and selection checks to `bytecode/call.rs`;
|
||||
resolution and dispatch semantics remain explicit boundaries.
|
||||
All seven statement forms have source-directed templates; a separate forest
|
||||
check covers the entire default prologue, statement body and implicit return.
|
||||
These checks detect stack-preserving semantic corruption, including Add to Sub,
|
||||
and refuse it before host effects. A forged source witness remains outside this
|
||||
check's guarantee; the recorder and actual AST correspondence need justification.
|
||||
|
||||
`ExpressionLowering` proves postfix expression compilation preserves complete
|
||||
interaction programs for arbitrary effectful leaves and operator interpretations,
|
||||
including faults and an arbitrary caller stack and continuation. `ShortCircuit`
|
||||
proves the exact absolute-PC AND/OR macros under arbitrary effectful child
|
||||
evaluation. `CheckExpressionLowering.lean` independently reads actual emitted
|
||||
operators, constants and local names, and applies the proved core checker.
|
||||
It counts call, collection, index and interpolation boundaries explicitly.
|
||||
Child inlining, Rust VM stepping, leaf interpretation and source-witness fidelity
|
||||
remain obligations; none of these results is whole-frontend functional refinement.
|
||||
|
||||
`ReceiverDefaults` proves that the source's separately maintained default
|
||||
environment equals the machine's receiver view after every successful prefix.
|
||||
The mask describes logical argument slots, while omitted self/自 defaults may
|
||||
replace the evaluation view. Supplied None remains present. The real receiver
|
||||
is restored before entering the body; argument contracts check both the logical
|
||||
arguments at the call site and the restored frame at the declaration, preserving
|
||||
source identity and diagnostic frames. The theorem composes this view invariant
|
||||
with `DefaultPrologue` for arbitrary effectful defaults and distinct slots.
|
||||
|
||||
Concrete repairs also share scalar/unary semantics across evaluators, stringify
|
||||
every interpolation part, allocate fresh loop temporaries, restrict dynamic
|
||||
calls to their defining module scope, and enforce the existing one-million
|
||||
truthy-iteration limit in VM as well as Tree. Regression evidence records each
|
||||
repair separately from proof claims. These compiler techniques are not new
|
||||
originality claims.
|
||||
|
||||
## Actual call staging and bounded control-flow macros
|
||||
|
||||
Every emitted call now has a separate source obligation captured before actuals
|
||||
are replaced with scratch reads. The checker covers authored actual order,
|
||||
evaluate/store/pop triples, source-local and loop-slot separation, nested-call
|
||||
scratch separation, argument reloads, layouts, builtin selection/defaults, host
|
||||
primitive identity, plugin name/pair ordering, method name/receiver and resolved
|
||||
user target/tag. Every call expression must have exactly one obligation. The
|
||||
reserved source-local prefix is established before any synthetic slots are
|
||||
allocated. Disjoint nested calls may reuse scratch slots after their lifetimes.
|
||||
|
||||
`CallStaging` proves the flat evaluate/save/pop program restores an arbitrary
|
||||
caller stack and has the same effects and failures as authored-order collection.
|
||||
It proves outside slots unchanged and unique staged slots read back the exact
|
||||
actual vector. The dispatch continuation is arbitrary and effectful, so binding,
|
||||
defaults and receiver effects can follow collection without commuting effects.
|
||||
`CheckCallStaging.lean` decodes real stores and reloads, applies the proved stage
|
||||
checker and independently checks the complete selection/dispatch template.
|
||||
Source-expression callback correspondence, name resolution and the semantics of
|
||||
each dispatch continuation remain proof interfaces. Host parameter metadata is
|
||||
an exported registry interface, not an independently verified registry theorem.
|
||||
|
||||
`WhileLowering` proves the condition/JF/check/body/backedge macro preserves the
|
||||
complete interaction program for a bounded loop, including a final false
|
||||
condition, condition/body faults, the truthy-iteration limit and early returns.
|
||||
It relates an increasing native counter to a decreasing model budget and proves
|
||||
admitted increments below one million fit u32. Model machine-step fuel is
|
||||
distinct from this language-visible iteration budget.
|
||||
`CheckStatementLowering.lean` checks actual default prologues, all seven statement
|
||||
templates, forests and implicit returns, including the exact while macro layout.
|
||||
The while theorem uses condition/body callbacks; concrete child inlining and the
|
||||
full Rust state machine are not discharged by checking those layouts. Branches
|
||||
and foreach currently have independent template evidence, not new functional
|
||||
refinement theorems. No ordinary compiler-checking technique is a novelty claim.
|
||||
|
||||
## Loaded executable AST and coherent witness corruption
|
||||
|
||||
`SourceFunction` now captures parameters, defaults, executable bodies and complete
|
||||
contract data directly from the loaded declaration before emission. The native
|
||||
source checker walks that snapshot separately from the rule recorder, checks
|
||||
ordered expression/statement correspondence and complete witness ownership,
|
||||
and accounts for the generated scratch reloads explicitly. It also compares
|
||||
full contracts with structural Rust equality, including types, nullable fields,
|
||||
descriptions, source lines and declaration quotes. Contract presence alone would
|
||||
not detect a Number-to-Any weakening.
|
||||
|
||||
The evidence exports the executable AST separately from the original module and
|
||||
from the compiled snapshot. `CheckSourceWitness.lean` matches declaration
|
||||
identities and applies `SourceWitness`'s proved ordered-tree reconstruction
|
||||
checker. Interpolation parts, index labels, code payloads and formula structure
|
||||
are retained; all formula floats and matrix entries retain their exact bits.
|
||||
The old Debug formula text was insufficient for NaN payload identity. Inert
|
||||
occlusion prose and pre-inference parser metadata are not execution-tree nodes.
|
||||
|
||||
Ten native coordinated-corruption cases change code together with its witness,
|
||||
including operators, constants, variables, assignments, callees, NaN payloads,
|
||||
index keys, interpolation, contract metadata and an orphan expression record.
|
||||
Eight independent source-witness negatives include changing the compiled snapshot
|
||||
as well. A coordinated wrong operator is a positive acceptance control for all
|
||||
four earlier independent consumers and a rejection control for the AST checker.
|
||||
This distinguishes trusted source correspondence from agreement among emitted
|
||||
metadata fields.
|
||||
|
||||
The theorem proves exact correspondence of the supplied executable trees, hence
|
||||
preservation under any interpretation of those trees. The native and JSON AST
|
||||
adapters, normalization helpers and snapshot capture remain trusted interfaces.
|
||||
No theorem here verifies the actual Markdown classifier/parser/inference or
|
||||
connects every concrete Rust operation to the semantic models. A caller who
|
||||
changes both the reference AST and its program has supplied a different
|
||||
translation-validation input; this is not source authentication.
|
||||
|
||||
## Runtime argument-preparation faults
|
||||
|
||||
The expanded AST audit exposed a concrete acceptance mismatch: Tree can execute
|
||||
main while an unused function contains a conflicting bracket modifier, whereas
|
||||
VM compilation previously rejected the entire module. Modifier preparation now
|
||||
lowers its failure to `RejectArgumentExpansion` before actual evaluation. A
|
||||
provided default parameter, including explicit None, skips that fault; reaching
|
||||
it preserves prior output and stops before actual effects or a suffix. The
|
||||
error's message, span, source revision and diagnostic frames match Tree.
|
||||
|
||||
`CallExpr::for_evaluation` normalizes bare aliases before modifier expansion,
|
||||
matching Tree's existing order. The expression checker validates an effect-free
|
||||
fault leaf and the independent decoder handles its actual terminal opcode.
|
||||
The AST adapter explicitly represents that executable fault without children;
|
||||
unexecuted actual expressions are not falsely counted as evaluated code.
|
||||
Two independent fault-opcode/message negatives and a positive AST-identity-only
|
||||
control keep representation checking distinct from instruction interpretation.
|
||||
|
||||
The independent Python oracle now compares JSON values with exact recursive
|
||||
types and requires integer arithmetic inputs to be actual integers. Python's
|
||||
True==1 and 1==1.0 equalities must not erase language-visible value distinctions.
|
||||
Four type-corruption controls are added. These improvements do not discharge
|
||||
other call-error timing, parser, resolver, dispatch or Rust-step proof obligations.
|
||||
|
||||
## Native binding and declaration graph validation
|
||||
|
||||
Builtins, host primitives and plugins retain authored labels in native bytecode.
|
||||
The shared value-independent binding plan selects named parameters before
|
||||
positionals, preserves omitted optional bindings and unknown named extras, and
|
||||
reports duplicate, missing and surplus positional arguments after actual effects.
|
||||
Plugin lookup precedes signature binding. Eighteen reached/unreached error cases
|
||||
check explicit expected output, messages, spans, source revisions and frames.
|
||||
A registered C ABI echo probe checks mixed and extra named arguments. Execution
|
||||
uses the native VM and plugin bridge throughout.
|
||||
|
||||
The source and flat declaration views share ordered resolution. A loaded snapshot
|
||||
captures ordinal declaration paths, levels, child/root counts, imports and ordered
|
||||
use aliases before emission. Verification checks identity, parent/child/root order,
|
||||
module scopes and object/method names, then derives call targets independently of
|
||||
emitted target records. Two-component paths check runtime receiver presence before
|
||||
static fallback; an unbound reserved slot differs from a supplied None. Imports
|
||||
retain priority. Resolution failures are native terminal instructions after actuals.
|
||||
|
||||
`NameResolution` proves first-match, path and lexical commutation under an
|
||||
ordered embedding. Its rank checker proves sufficient depth and connects a
|
||||
well-founded total source policy to flat lookup. Rust uses the same parent-chain
|
||||
policy; parent-view extraction remains a trusted adapter. The finite checkers consume actual AST/flat evidence in
|
||||
`CheckNameResolution.lean`. Nine native corruptions and seven independent graph
|
||||
negatives test this boundary. A coordinated wrong target remains a positive control
|
||||
for the older stack, staging and AST-shape consumers. Ordinary compiler correctness
|
||||
ingredients are not novelty claims. Snapshot/JSON adapters, primitive registries,
|
||||
parent-view extraction and concrete Rust
|
||||
instruction refinement remain explicit obligations; universal frontend verification
|
||||
and overall paper readiness are not established by these results.
|
||||
|
||||
`ArgumentBinding` separately models per-parameter omission permission and proves
|
||||
value substitution preserves selections and faults. A successful index plan has
|
||||
a finite-index witness. `CheckArgumentBinding.lean` checks actual static call
|
||||
plans and an independently enumerated mask/label corpus. User VM calls now use
|
||||
the shared planner with the callee default mask, correcting their surplus-count
|
||||
diagnostic and preserving missing-required-before-default priority. Default
|
||||
evaluation, contracts, dynamic signature selection and concrete Rust/JSON steps
|
||||
remain separate interfaces. The mathematical planner is not a proof of the
|
||||
entire native binding implementation.
|
||||
@@ -1,5 +1,7 @@
|
||||
# 语法设计哲学:函数在「代码即文档」里为何水土不服,以及用什么语义取代
|
||||
|
||||
> **2026-10-23 审阅裁决**:保留“正文优先、按需命名”的方向;下文语料统计和“具名给值缺失”等判断属于当时快照。当前已有具名实参;“调用即代入”不规定文本展开实现,也不禁止递归。下一阶段以[文档原生指导 §2–3](document-native-development-guide.md#2-语法审查的保留修正与暂缓)的范围和验收为准,本文不是替换整个函数模型的已批准语法提案。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 哲学层讨论**(不涉及实现,不含语法提案细节) |
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 语义探析:代码函数能否解释为一张 GFM 表
|
||||
|
||||
> **2026-10-23 审阅裁决**:下文 v1.5.2 实验不替代当前回归。保留现有数据表几何与契约表角色,不重复声明参数;“现有实现不支持函数表”不等于表格不能表达计算。有限决策表和生成式签名视图按真实用例评估,见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未修改任何代码) |
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 方案评估:函数能否作为变量的一种(函数即表)
|
||||
|
||||
> **2026-10-23 审阅裁决**:以下是旧实现约束与方案权衡,不是“匿名函数无法索引”或“动态调用无法检查契约”的普遍结论。一等函数/闭包本轮暂缓而非永久禁止;有限决策表先评估现有库表达,文中建议的新辅助函数不因此成为已实现能力。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(未修改任何代码) |
|
||||
|
||||
@@ -0,0 +1,326 @@
|
||||
# 隔离执行与响应式 Web 运行时:详细开发设计
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Verified**(execute 路径);HTTP `execute` / `sse-live` / `stream:true` 默认走 Supervisor worker 池(不再经父进程 `CallLibPath` / `INVOKE_LOCK`);`runtime.isolated_execution=1`;MR-01 金样例 `tests/isolated_execute_mr01.rs`;未声明非流式仍 `legacy_serial`(ADR 0008) |
|
||||
| 基线 | Marqdo `1b11fe0` / 2.1.3;qdagent `64b97e5`;2026-10-26 |
|
||||
| 问题依据 | [单解释器缺陷](web-invoke-serialization.md)、[ADR 0008](../adr/0008-web-invoke-serialization.md)、[本轮跨库复核 R01–R14](../../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md) |
|
||||
| 产品配套 | [qdagent 可靠工作台开发设计](../../../qdagent/doc/design/reliable-workbench-development-2026-10-26.md) |
|
||||
| 继承合同 | [工作台 M00–M06](qdagent-workbench-runtime-and-view-2026-10-25.md) 中 ModelSelection、ModelSnapshot、Usage、DocumentView、Locator;保留文档原生作者面 |
|
||||
|
||||
## 1. 目标、边界与不变量
|
||||
|
||||
目标是让用户在长对话、导入和构建过程中持续打开模型列表、读取来源、修改下一轮设置并可靠停止任务。高并发容量按资源预算显式限制;不能让所有请求进入一把解释器锁再超时。
|
||||
|
||||
Marqdo 负责通用执行隔离、资源调度、事件/取消、语义分析和制品校验。qdagent 负责用户/工作区授权、业务状态与发布政策。产品仍通过 `.mq.md` 调用 Marqdo Agent,不增加第二套模型循环或知识编译器。
|
||||
|
||||
必须保持的系统不变量:
|
||||
|
||||
1. 同一个可变 HostContext 同时最多一个求值者;不删除锁、不增加虚假的 `unsafe impl Sync` 来获得并行。
|
||||
2. 一个执行租约只属于一个 run/attempt;凭证、事件、取消、cwd、权限和模型选择不可流入另一请求。
|
||||
3. 控制与读取具有独立容量,不被 LLM 等待占满;停止不需要重新进入正在执行的解释器。
|
||||
4. 事件可以重投,外部副作用不默认重做;不宣称跨网络 exactly-once。
|
||||
5. 已确认终态不能被晚到完成/取消覆盖;取消不回滚已经完成的外部写入。
|
||||
6. 阅读不执行 `.mq.md`,缓存不绕过授权或版本校验;缓存命中必须实际复用结果。
|
||||
7. 正文、依赖、证据和编译代属于同一不可变快照;不会把两个代的结果拼成一次阅读或执行。
|
||||
8. 任何能力开关都以实际探测和测试为依据;新 API/schema 在落地前都属于本文提案。
|
||||
|
||||
## 2. 架构选择
|
||||
|
||||
| 方案 | 优点 | 当前代价 | 本轮选择 |
|
||||
|---|---|---|---|
|
||||
| 继续全局锁,只增加 Go handler | 改动小 | 长任务依然阻塞所有 Endpoint,串扰变量也未消失 | 只保留作兼容模式 |
|
||||
| 同进程多 HostContext | 潜在内存复用较好 | GLOBAL_HOST、插件回调、环境、cwd、事件 sink 生命周期需系统重做 | 后续优化,不是首个交付门槛 |
|
||||
| 独立 Marqdo worker 进程 + 控制/读取通道 | 隔离现有全局状态,可强制回收卡死任务,复用现有语言与 Agent | IPC、进程启动、内存、发布写协调 | **首选实现** |
|
||||
| 引入外部通用队列和新业务 Runtime | 容易扩到集群 | 运维复杂度及第二套编排风险 | 单机阶段不引入 |
|
||||
|
||||
首期采用**预热的一次性执行进程池**:进程可预装运行时和非用户特定模块,分配任务后独占,结束即退出并异步补充。这样不用假设清空部分字段就能安全复用 HostContext。长寿命多租约 worker 只有通过状态泄漏、插件资源与 RSS 回归后才开启。只读分析服务可以长寿命运行,但不得加载有副作用的求值插件。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
UI[浏览器 / CLI / MCP] --> WEB[Go HTTP / 认证入口 / 限流]
|
||||
WEB --> CTRL[任务控制与事件服务]
|
||||
WEB --> SHORT[短业务请求容量]
|
||||
WEB --> READ[只读分析服务]
|
||||
SHORT --> POLICY[qdagent .mq.md 授权与业务规则]
|
||||
POLICY --> CTRL
|
||||
CTRL --> DB[(任务索引 / outbox / 事件日志)]
|
||||
CTRL --> SUP[Rust Supervisor / 有界调度]
|
||||
SUP --> A[Marqdo worker A / 一个租约]
|
||||
SUP --> B[Marqdo worker B / 一个租约]
|
||||
A --> AGENT[既有 Marqdo Agent / LLM / sandbox]
|
||||
B --> AGENT
|
||||
A --> STAGE[每任务暂存目录]
|
||||
B --> STAGE
|
||||
STAGE --> COMMIT[按资源串行提交与 revision CAS]
|
||||
COMMIT --> SNAP[(不可变知识代 / 发布 manifest)]
|
||||
READ --> SNAP
|
||||
A --> CTRL
|
||||
B --> CTRL
|
||||
CTRL --> UI
|
||||
```
|
||||
|
||||
“短业务请求容量”依旧可执行产品 `.mq.md`,但有独立 worker 预算和短 deadline。控制服务只做通用接纳、状态 CAS、取消与日志投递,不把模型选型、知识晋升等业务逻辑搬进 Go。读取服务接收经过授权的资源句柄;不得直接相信浏览器提交的绝对路径。
|
||||
|
||||
## 3. 路由分类与接纳
|
||||
|
||||
### 3.1 执行类别
|
||||
|
||||
在 Endpoint 装配中新增可选 metadata(字段名待 schema 固定):
|
||||
|
||||
| 类别 | 示例 | 资源预算与规则 |
|
||||
|---|---|---|
|
||||
| `control` | 任务查询、事件订阅、取消、health | 不执行用户代码;认证后访问任务存储/租约注册表 |
|
||||
| `read` | view.document、引用解析、已发布模型列表投影 | 只读快照;不写用户源码;可缓存 |
|
||||
| `short` | 保存设置、创建导入、接纳任务 | 无 LLM 长等待;默认 deadline 2s,较慢动作转为任务 |
|
||||
| `execute` | ASK/BUILD/生成/验证 | 有界队列、专属进程、显式任务 deadline |
|
||||
| `commit` | 切换知识代、合并受控文件变更 | 按 workspace/kb 的短临界区;执行前检查 revision |
|
||||
|
||||
旧 Endpoint 未声明时仍走 legacy_serial;不能自动猜测任意函数是纯读。纯度来自静态能力和注册配置,实际写权限仍由宿主限制。文件上传字节传输不占解释器,应先落隔离存储,再进入短接纳路径。
|
||||
|
||||
### 3.2 接纳步骤
|
||||
|
||||
1. HTTP 层解析受限请求,验证身份、格式、速率与连接数量。
|
||||
2. 产品短入口解析 workspace/model/policy;授权版本与模型配置 revision 一并冻结。返回规范化任务请求,不执行 Agent。
|
||||
3. 控制服务在同一数据库事务中登记作用域化 idempotency key、payload hash、task 和 dispatch outbox;重复请求读回已有 task,同键异内容返回 409。
|
||||
4. 提交事务后才返回 202/Location。调度器消费 outbox 分配租约,租约带 attempt/epoch。
|
||||
5. 对同步兼容 API,先完成接纳,再挂接结果;等待客户端超时不等于安全重做。
|
||||
|
||||
队列入库前容量不足返回 429 + Retry-After;服务不可用返回 503;接纳失败不发送 started。控制通道须保留槽位,不能因为数据流连接占满而无法取消。
|
||||
|
||||
## 4. Supervisor、生命周期与调度
|
||||
|
||||
### 4.1 Worker 生命周期
|
||||
|
||||
`starting → ready → leased → running → draining → exited`;启动失败/心跳丢失走 `unhealthy → terminating → exited`。任务状态由控制服务维护,进程状态不能直接当作业务成功。
|
||||
|
||||
- worker 启动握手报告 CLI/ext/native、protocol_version、能力、构建摘要;不匹配不进入 ready。
|
||||
- 预热阶段不读取用户凭证、不挂载工作区写权限。分配租约后挂载当前任务的 capability roots、只读快照和独立 staging。
|
||||
- 每任务具有随机 lease_id、run_id、attempt_id、epoch、绝对 deadline 和资源限制。
|
||||
- Supervisor 持有进程句柄、子进程组、事件通道与取消句柄。worker 不能自行修改其他 worker 状态。
|
||||
- 返回业务结果后仍须 drain 事件/用量并提交最终 checkpoint,控制服务持久化终态后确认 ACK,之后释放租约。
|
||||
- 超时或断连清理不能遗留孤儿子任务;正常优雅退出后再删除临时文件。异常由独立 janitor 按租约过期回收。
|
||||
|
||||
### 4.2 有界、公平与资源预算
|
||||
|
||||
初始验证配置建议 4 vCPU/8 GiB、执行槽 2、短请求槽 1、读取服务 1。具体容量由每类任务的 RSS p95 和 CPU profile 决定,不能把这个数当所有机器的默认。执行槽上限:
|
||||
|
||||
`min(CPU约束, floor((可用内存 - 系统/控制/缓存预留) / worker_RSS_p95))`。
|
||||
|
||||
运行队列按 workspace 轮转,再按 session FIFO;一个 session 默认只允许一个活动 turn,跨 session 可并行。相同知识库的生成可并行,发布只占短提交锁。interactive 优先于后台索引,但后台使用老化提升或最低服务配额,防永久饥饿。
|
||||
|
||||
全局队列初始上限 64、单工作区 16、单会话待处理 4,均可配置;队列超限及时返回,不能悄悄丢任务。显示队列位置或“前方有任务”,没有可靠完成时间估计时不显示虚构倒计时。
|
||||
|
||||
### 4.3 副作用与重试
|
||||
|
||||
任务声明 `read_only / staged_write / external_effect`,由工具权限校验而非模型自报。read_only 可按政策重试;staged_write 丢弃未提交 staging 后重试;external_effect 出现超时/失联时标记 `effect_unknown`,等待核对,不自动重复支付、发信或写入。
|
||||
|
||||
稳定的操作键使用 `task_id + logical_step_id`,attempt_id 只标记传输尝试,不应导致同一外部动作生成新的去重键。工具不支持幂等查询时,只能明确报告不确定。工作簿记录已完成与未知副作用;“已停止”不意味着“全部撤销”。
|
||||
|
||||
## 5. IPC 与请求上下文
|
||||
|
||||
首期使用本机 Unix socket 或匿名管道,采用长度前缀 JSON 控制帧与独立事件通道。协议禁止无上限 JSON/单行日志;控制帧初始上限 1 MiB,大文档通过授权 blob handle 传递。普通 stdout/stderr 仅诊断,不与协议混流。当前 NDJSON 文件桥保留为 legacy fallback。
|
||||
|
||||
新增 `InvokeRequestV2` 示例(提案):
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "InvokeRequestV2",
|
||||
"schema_version": 2,
|
||||
"task_id": "task_01",
|
||||
"run_id": "run_01",
|
||||
"attempt_id": "attempt_01",
|
||||
"lease": {"id": "lease_01", "epoch": 3},
|
||||
"entry": {"module": "agent/qdagent.mq.md", "function": "run"},
|
||||
"args_ref": "blob:sha256:...",
|
||||
"context": {
|
||||
"workspace_id": "ws_01",
|
||||
"snapshot_id": "generation_01",
|
||||
"selection_ref": "model-snapshot_01",
|
||||
"capabilities_ref": "grant_01",
|
||||
"deadline_at": "2026-10-26T08:10:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`grant_01` 是服务端验证的短寿命授权句柄,内容包括 principal、scope、根目录、允许效应、授权 revision、失效时间。worker 不使用浏览器任意传入的 fn/path。权限撤回后,新的工具调用必须重新验证 lease/grant,已开始的外部调用记录撤回时间与实际结果。
|
||||
|
||||
`RunContextV1` 保留原有字段与序列化兼容,内部增补显式 Context 对象;扩展 V2 由能力协商启用。event_sink、usage_sink、cancel_token 使用句柄,不使用外部可控路径。子任务通过 IPC/Command.env 显式继承,禁止父进程 `setenv`/`set_current_dir` 承担请求状态。
|
||||
|
||||
凭证在租约启动时通过受保护 IPC 或继承 FD 注入;不落任务 JSON、argv、日志或通用事件。模型快照可含 credential_ref,不含 api_key。即使选择相同 provider,不同请求的授权也不得合并。
|
||||
|
||||
## 6. 取消协议与状态 CAS
|
||||
|
||||
任务基础状态:`accepted → queued → running → finalizing → succeeded/failed`;queued/running 可进入 `cancel_requested → cancelled`;worker 失联进入 `interrupted`,副作用不明时进入 `needs_reconciliation`。这些是提案,产品可以将 succeeded 映射为 completed。
|
||||
|
||||
取消顺序:
|
||||
|
||||
1. 验证调用者对 task 的权限,CAS 写 cancel_requested、revision 与 requested_at;终态返回原状态,未知 ID 返回 404。
|
||||
2. 向匹配 lease/epoch 的控制通道发送 Cancel;不经任务解释器锁。queued 任务原子移出待派发队列。
|
||||
3. worker 在每次 LLM/工具调用、重试、子任务启动和提交之前检查 token;网络请求使用可中断句柄,不能仅在一行输出结束后才检查。
|
||||
4. 收到 ACK 仍不等于任务停止。等待 worker 报 stopped、落未完成副作用和用量,再 CAS 到 cancelled。
|
||||
5. 默认 2s 协作宽限、额外 3s 进程退出宽限,之后回收进程组。强制退出记 interrupted/needs_reconciliation,不能伪造干净 cancelled。
|
||||
|
||||
完成与取消竞争的线性化点是控制存储的 CAS:终态先提交则 cancel 返回 already_terminal;取消先提交则晚到 result 只可作为证据追加,不能重新变 succeeded。若外部动作已发生但响应晚到,记录 effect outcome,不撤销取消事实。
|
||||
|
||||
兼容文件 token 统一:不存在/空/`0` 为未取消,`1`/`cancelled` 为取消;读取失败返回诊断并按明确策略处理。删除 token 只能发生在持有者退出之后。移除全局 `MARQDO_CANCEL` 对多个任务的隐式作用域。
|
||||
|
||||
## 7. 事件、SSE 与背压
|
||||
|
||||
### 7.1 事件权威
|
||||
|
||||
生产者发出 `(run_id, attempt_id, local_seq)`,控制服务去重、持久化并分配 task 内单调 seq/event_id;客户端游标来自持久化日志,不是 handler 重连后从 1 开始计数。终态事件唯一,usage 可以在终态后以更高 usage revision 补录,但不能再次结束任务。
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "RuntimeEventV2",
|
||||
"schema_version": 2,
|
||||
"event_id": "task_01:42",
|
||||
"seq": 42,
|
||||
"task_id": "task_01",
|
||||
"run_id": "run_01",
|
||||
"attempt_id": "attempt_01",
|
||||
"type": "message.delta",
|
||||
"payload": {"message_id": "msg_01", "offset": 24, "text": "结果"}
|
||||
}
|
||||
```
|
||||
|
||||
不要直接破坏 RuntimeEventV1;新增字段/新版本由能力协商确定。普通用户可见 progress 只描述工具、阶段、文件等结构化事实;模型内部 reasoning 不作为完成证据,也不默认写入公开事件。
|
||||
|
||||
### 7.2 App SSE
|
||||
|
||||
新增任务 API 的事件订阅用 `GET /tasks/{id}/events`(最终产品前缀见配套设计),发送 SSE `id`/`event`/`data`;每个 data 是一个完整 JSON。客户端支持 Last-Event-ID、CRLF、多行 data、任意 UTF-8 分块和 EOF 未完成帧。重复事件按 ID 去重;message offset 检查缺口,缺口时恢复快照。
|
||||
|
||||
心跳 15s,客户端空闲探测建议 45s;二者可配置。事件保留建议 24h,最终结果/审计按项目政策更长保留。游标早于保留边界返回 410 `event.cursor_expired` 和快照入口,不能默默从最新开始丢字。
|
||||
|
||||
订阅断开默认只关闭订阅。App 显式停止通过 cancel API,切页/移动网络重连可恢复同一任务。传统同步 OpenAI 调用可保持 disconnect=cancel 的兼容策略,但必须显式区分,不能统一把所有浏览器断流当取消。
|
||||
|
||||
### 7.3 OpenAI 兼容流
|
||||
|
||||
`/v1/chat/completions stream=true` 输出 OpenAI chunk 与 `[DONE]`;App 运行事件由独立入口或协商的协议提供。禁止仅凭任意 JSON body 中 stream=true 将不相关路由自动改为 RuntimeEvent 协议。已发 header 后的错误使用该协议允许的错误帧;发 header 前可用 429/503/401 等正确状态码。
|
||||
|
||||
token delta 与最终完整答复分开:最终事件持有结果引用/摘要和 finish reason,不再次追加整篇正文。无 token 能力的适配器报告 `evented_batch`,界面用阶段状态,不把整包人为拆字伪装成实时。
|
||||
|
||||
### 7.4 背压和旧桥修复
|
||||
|
||||
worker→事件服务与服务→订阅者均有界。建议每订阅者 256 KiB 待发送内存,超出后断开慢消费者并允许按游标重连;事件正文已持久化所以不能静默丢 token。允许合并短时间 delta,必须保留 message offset;usage/终态/错误不丢弃。磁盘压力时停止接纳新任务,已有任务使用保留终态空间并按策略中断,不能无限写事件。
|
||||
|
||||
legacy NDJSON tailer 只消费换行已完整到达的字节;保留残片,offset 按真实消费字节移动。超长行、I/O error、文件旋转显式报协议错误。测试至少分三次写一个 JSON、中文多字节边界、恰好 EOF、超过上限、取消与尾帧竞争。禁止吞掉 Scanner.Err() 继续宣告成功。
|
||||
|
||||
## 8. 只读快照与真正有效的缓存
|
||||
|
||||
### 8.1 快照一致性
|
||||
|
||||
分析服务构建 SnapshotKey:规范化 project identity、允许扫描范围、源文件闭包摘要、依赖/来源/配置摘要、compiler/lib/ext 版本、policy/schema、解析选项。输入由编译器枚举,不另造“前 200 个根目录文件”规则。
|
||||
|
||||
读取一次快照内的正文、语义和来源,完成后复核输入 manifest;文件在分析中发生变化则重试一次或返回 `snapshot.changed`。对不可变发布代直接读其 manifest。mtime/size 只用于快速发现候选变更,不能代替内容摘要;watcher 丢事件后以完整扫描修复。
|
||||
|
||||
### 8.2 缓存结构
|
||||
|
||||
- `AnalysisCache<SnapshotKey, Arc<Compilation>>`:实际编译结果。
|
||||
- `DocumentCache<(SnapshotKey, document_digest, renderer_version, view_options), DocumentView>`:安全 fragment、outline、nodes。
|
||||
- 同 key single-flight 的 follower 等待同一个 Result,不再次 compile。
|
||||
- RAII guard 在 error/panic/cancel 时清除 inflight 并唤醒 waiters;等待者有自己的 deadline。
|
||||
- compile 失败只返回给当前等待者,短暂错误缓存需显式 TTL;不得调用“finish_success”标记失败结果可复用。
|
||||
- LRU 按字节而非条数上限管理;初始预算按部署内存的 10% 且设硬上限,长文档超限不缓存或分页;记录淘汰原因。
|
||||
- 每次读取先授权再查缓存;权限敏感的响应按 scope/policy 分区。全局缓存只共享不含用户秘密且访问已验证的不可变语义数据。
|
||||
|
||||
性能证据必须统计 `compile_invocations`、输入字节、缓存结果命中、leader/follower、wait_ms、evictions;现有 hit counter 不能证明减少编译。
|
||||
|
||||
### 8.3 HTML 与来源定位
|
||||
|
||||
沿用 DocumentViewV1,明确 `render.format=plain_text|sanitized_html`。HTML 通过解析器白名单清洗标签/属性/URL scheme,剥离脚本、事件属性、危险 CSS/嵌入与可执行 SVG;相对资源经受限资源端点解析。纯文本始终转义,不以 `<` 字符判断类型。
|
||||
|
||||
node_id、revision、generation 必须从定位到读取到浏览器滚动完整传递。不存在历史快照返回 version_unavailable;返回当前版是用户显式操作且标明版本变化。no_exec 测试分别验证“无语言副作用”和“浏览器无脚本执行”,二者不能互相替代。
|
||||
|
||||
### 8.4 首次编译的性能改造
|
||||
|
||||
本轮 `v3_corpus_1000_compile_smoke` 在 debug 下 243.012s,超过既有 180s 门禁;缓存不能缩短一个全新项目的第一次编译。先为 `knowledge::compile` 的语义编译、语义落盘、检索 extract、检索落盘、manifest 分别加 span,再细分 `ProjectIndex::build`、源枚举/解析、导入挂接、绑定、效应传播、闭包摘要。记录文件数/总字节、节点/边数、parse 次数与序列化字节量。
|
||||
|
||||
源码中 `sema::compile_project` 在每个文件查找 module path、每个 module 过滤全量 symbols,属于值得测量的重复扫描;未取得 profile 前不将其认定为 243s 的唯一根因。优化候选按证据选择:建立 path→module 与 module→symbols 索引;同一输入快照共享 parsed module;绑定/依赖图用稳定索引;效应传播用 worklist;闭包按 SCC DAG 计算并保留循环依赖语义;减少每制品重复序列化和小文件写入。
|
||||
|
||||
任何优化须保持排序确定性、SymbolId/ArtifactId 与证据摘要规则,禁止通过跳过来源校验、删掉复杂 fixture 或改大超时过关。用 100/1000/10000 单元、无依赖/链/菱形/循环四种图分别测时间与 RSS;给出随 V/E 增长的曲线。release 和 debug 分开;已有 debug 门禁恢复通过只是第一步,§12 的 release 预算仍须独立验收。
|
||||
|
||||
## 9. 写入、发布与数据库边界
|
||||
|
||||
执行 worker 只写任务 staging;需要写工程时通过沙箱产生文件 diff。发布以 kb 资源锁 + expected_generation CAS 提交。锁只覆盖校验当前版本和切换 manifest,不覆盖 LLM、全文编译或网络调用。
|
||||
|
||||
完整发布代先写临时目录、校验摘要、完成必要 fsync,再原子 rename 到不可变 generation 目录;最后在同一文件系统原子替换 CURRENT。源码、编译投影和证据在该 manifest 下对齐。SQLite 中的产品“published”是投影,不参与虚构的文件/数据库跨系统原子事务。通过 publish journal + outbox 恢复:CURRENT 已切换但 DB 未更新时重放;未切换时旧代继续有效。
|
||||
|
||||
project_id 与逻辑文档 ID 不随 staging/generation 的物理目录名变化。manifest 保存稳定 project identity、逻辑相对路径和实际 blob/generation 映射;导入引用按项目规则解析,不能因复制到发布目录而重新生成全部符号身份。框架若尚不能区分逻辑身份与物理根,先补该能力,再启用 generation 目录发布;迁移 fixture 必须断言未修改的知识 ID 和跨文档绑定保持稳定。
|
||||
|
||||
任务表/幂等/CAS/outbox 需要通用事务能力:先审计 `ext/data` 是否支持事务、条件更新、受影响行数、复合唯一键;缺少则在 Marqdo 数据层补齐,不能用 `.mq.md` 的先读后写模拟原子性。SQLite 使用短事务和有界 busy timeout;WAL/连接池是否开启需按现有插件适配测试确认。单主本地盘为首期部署范围,跨主机共享 SQLite/NFS 不在首期承诺内。
|
||||
|
||||
## 10. 临时缓解与迁移
|
||||
|
||||
### 10.1 进程池完成前
|
||||
|
||||
- 保留 1500ms busy 预算和 Retry-After;展示繁忙,而非无限 spinner。
|
||||
- 在接纳任何 SSE 之前取得覆盖整个 bridge 生命周期的 legacy 单飞许可,第二条流在修改环境变量/发送 200 前失败;普通请求不得绕过许可观察被污染的状态。
|
||||
- 断连只标记该任务取消,清理由监督者等待执行结束后负责;无法确认停止时报告 stopping/interrupted。
|
||||
- 上述步骤只降低 R02/R03 风险,仍不算并行 Endpoint。
|
||||
|
||||
### 10.2 功能开关(新增提案)
|
||||
|
||||
`runtime.isolated_execution`、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`、`runtime.read_lane`。探测返回 feature version 和限制。二进制版本相同不等于所有 native 插件都有该能力。
|
||||
|
||||
先离线 fixture → 本地假模型 → 新 workspace → 只读 ASK → staging BUILD → 真正发布。禁止对有副作用的请求做双执行 shadow;允许 shadow 只读分析并比较摘要。
|
||||
|
||||
回滚先停接新任务、drain 已接纳任务、保留任务/事件和新 schema;不能将活动任务交给不认识 lease 的旧进程。只读当前发布代可以保留,写入能力按版本协商关闭。ADR 0008 仅在并行金样例与回滚演练通过后由新 ADR 正式替代。
|
||||
|
||||
## 11. 开发包与依赖
|
||||
|
||||
下列新模块路径是建议,不代表文件已存在。
|
||||
|
||||
| 包 | 建议落点与改动 | 前置 | 验收 |
|
||||
|---|---|---|---|
|
||||
| M-R0 基线/缓解 | `host/plugin.rs`、`httpx/routes_invoke.go`;固定并发屏障、旧桥许可、取消清理 | 无 | 双流 busy 不改写 A 的桥;断连无提前清理 |
|
||||
| M-R1 请求上下文 | `workbench/run_context.rs`、`host/subtask.rs`、LLM 插件;统一 token 与显式 sink | M-R0 | 父子运行模型/事件/取消不串;空 token 不取消 |
|
||||
| M-R2 Worker/IPC | 新 `runtime/{supervisor,worker,protocol,lease}.rs`;独立进程与握手 | M-R1 | 两任务并行、超时回收、子进程无孤儿 |
|
||||
| M-R3 接纳/控制 | 新 `runtime/{task_store,scheduler,control}.rs` 与 ext/data 事务 primitives | M-R2 | 原子幂等、队列公平、取消与结果 CAS |
|
||||
| M-R4 事件协议 | `workbench/event_sink.rs`、Web stream/IPC、协议适配器 | M-R3 | 断点恢复/去重/半帧/慢消费/磁盘错误 |
|
||||
| M-R5 读服务/缓存 | `analysis_cache.rs`、`document_view.rs`、`locator.rs`、MLSP transport | M-R1,可独立推进 | 100 同 key 真正只编译一次;嵌套变更正确失效 |
|
||||
| M-R5b 首次编译性能 | `knowledge/compile.rs`、`sema/ir.rs`、ProjectIndex;分阶段 profile 与按热点优化 | 基线语义回归 | 现有 1000 单元门禁恢复;release 与规模曲线报告,身份和语义不变 |
|
||||
| M-R6 提交底座 | `knowledge` generation/manifest、publish journal、条件更新 | M-R3 | 崩溃点恢复,旧代不被半发布污染 |
|
||||
| M-R7 整合与发布 | 版本探测、CI、release、文档/ADR | M-R4–R6 + 产品接入 | §12 全部必要门禁与回滚演练 |
|
||||
|
||||
先以本地文件和单机进程解决明确缺陷;不要把集群、远程 worker、复杂 Actor 系统设为第一阶段依赖。
|
||||
|
||||
## 12. 验收、性能预算与可观测性
|
||||
|
||||
### 12.1 正确性矩阵
|
||||
|
||||
| 编号 | 场景 | 必须观察到的结果 |
|
||||
|---|---|---|
|
||||
| MR-01 | A/B 两个 60s 假模型流 + 20 次/s 模型/设置读取 | 两流不混字、不混模型;短请求 200;无 interpreter busy |
|
||||
| MR-02 | B 在 A 运行时接纳失败/断连 | A 事件和取消句柄完全不变 |
|
||||
| MR-03 | 同时取消 A、完成 B;取消重复/晚到 | A 正确停;B 成功;终态不回退;审计只结算一次 |
|
||||
| MR-04 | 帧拆字节、多行、EOF 半帧、重连 | 无丢字/重字;协议错误可见;游标恢复精确 |
|
||||
| MR-05 | 慢消费者、磁盘满、worker 崩溃 | 内存有界;事件不静默丢失;状态可恢复 |
|
||||
| MR-06 | 100 个相同读取并发 | 实际编译一次;后续结果复用;失败 leader 不挂死 follower |
|
||||
| MR-07 | 改子目录依赖、第 201 个文件、配置、来源 | SnapshotKey 改变;缓存失效;旧业务句柄拒绝 |
|
||||
| MR-08 | 上传有写文件/网络代码、HTML 事件属性 | 阅读不求值;浏览器脚本不执行;正文可读 |
|
||||
| MR-09 | 发布每个持久化边界 kill | 仅旧完整代或新完整代可见;DB 投影最终追上 |
|
||||
| MR-10 | 并发幂等请求、取消队列、权限撤回 | 单一 task;同键异内容 409;无越权派发 |
|
||||
| MR-11 | kill 后副作用未知 | 不自动重放,显示 needs_reconciliation |
|
||||
| MR-12 | 降级/升级、混合 CLI/ext/native | 缺能力明确禁用,不报已支持 |
|
||||
|
||||
### 12.2 性能目标(待测验收预算)
|
||||
|
||||
基准机:Linux 4 vCPU/8 GiB SSD;release 构建;1000 个知识单元、文档总量 10 MiB、500 条历史 run;假上游固定 60s、每秒 20 个增量;30s 预热、5min 采样、3 轮,报告 p50/p95/p99、错误率、CPU、RSS、磁盘。另测 10k 单元和 100 MiB 以确定容量上限,不能直接沿用小数据阈值。
|
||||
|
||||
| 指标 | 初始预算 | 说明 |
|
||||
|---|---|---|
|
||||
| 短读/任务接纳 | p95 ≤200ms,p99 ≤500ms | 两个长任务运行时;过载拒绝另统计 |
|
||||
| 取消受理 | p95 ≤200ms | 独立于任务停止耗时 |
|
||||
| 协作取消收敛 | p95 ≤2s | 假上游/可中断工具;不可中断外部动作按不确定处理 |
|
||||
| 已就绪 worker 调度 | p95 ≤100ms | 不含排队、模型首 token 时间 |
|
||||
| 事件到订阅者新增延迟 | p95 ≤100ms | 从已收到 provider delta 计,不承诺上游 TTFT |
|
||||
| 1000 单元首次分析 | p95 ≤2s | 候选目标,超标先剖析,不降低正确性 |
|
||||
| 热 DocumentView | p95 ≤100ms | 真实复用结果;长文档另测分页 |
|
||||
| 慢消费者缓冲 | 每订阅 ≤256 KiB | 总连接数也必须受限 |
|
||||
| 压测结束内存 | 稳态可回收、无持续增长 | 记录每次重复轮次 RSS;不能只看一次峰值 |
|
||||
|
||||
新指标至少有 queue_depth/wait、worker_active/recycle、admission_rejected、cancel_ack/stop、orphan_count、event_lag/replay/duplicate、compile_invocations/cache_result_hit、publish_conflict/recovery。指标标签禁止 task_id、原始路径、prompt 等高基数/敏感值;trace 中可记录脱敏 task/attempt/lease 与构建摘要。
|
||||
|
||||
现有测试继续保留:`cargo test --offline --locked --test workbench_contracts --test executable_knowledge`、LLM 插件单测、Go httpx 测试。新增集成门禁必须启动真实 HTTP→IPC→worker 路径并使用本地假模型;不能以手写 fixture 或写 token 文件代替端到端行为。本轮执行结果统一记录在[跨库复核 §5](../../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md)。
|
||||
@@ -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 对应 |
|
||||
@@ -1,5 +1,7 @@
|
||||
# 标准库 / 扩展库:代码即文档
|
||||
|
||||
当前可执行开发规范见[库开发指南](../library-development.mq.md),其中的真实函数示范叙述内赋值、遮蔽调用、表格数据与返回。本页保留设计背景与历史波次。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
@@ -10,39 +12,51 @@
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`lib/*` 与 `ext/*` 的 `.mq.md` 应**可当说明书读、可当程序跑**。薄库不写长文;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。
|
||||
`lib/*` 与 `ext/*` 的 `.mq.md` 应**可当说明书读、可当程序跑**。薄库用充分且具体的叙述解释短实现;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。
|
||||
|
||||
## 2. 薄库模板(默认)
|
||||
## 2. 单文件标准库模板
|
||||
|
||||
每个导出函数 / 方法尽量按此骨架(中英分文件锁步):
|
||||
标准库通常是一个 `lib/*.mq.md` 文件,源码自身承担使用手册、开发说明与 SKILL。
|
||||
直接阅读、导入或调用此文件,不增加强制 `index.mq.md` 或平行模块手册。
|
||||
多文件拓展库才用 `index.mq.md` 组织模块与开发路线。
|
||||
|
||||
1. **目的句**(一句人话,无标记即可)。
|
||||
2. **叙述形参**:正文里出现 `` `名` `` / `` `名`=默认 ``(推断签名);过渡期可保留 `` + `名` ``。
|
||||
3. **一例**:粗体或 `>` 调用;优先可读表面。
|
||||
4. **实现**:短;取元用 `[键](集合)`,**禁止新增**脚注取元 `` `m`[^k] ``(旧解析仍可用)。
|
||||
每个函数依次提供:标题、参数表(名称、类型、默认值、含义)、返回契约、效应说明、
|
||||
叙述形参、用途与真实调用例子、简短实现。无参数函数直接放返回表。
|
||||
参数和返回契约位于第一条执行语句之前;标准库不再保留旧 `+` 形参清单。
|
||||
|
||||
调用示例(三种等价,试点期任选;新叙述优先括号标记或粗体):
|
||||
叙述形参使用正文中的反引号名称,默认值紧跟等号;表格说明与实际默认值必须一致。
|
||||
例如正文写「输入路径 `path`」,调用时即可提供 path。含标点的文本默认值使用完整引号。
|
||||
不透明类型保留渐进式 any,并说明其产生途径和限制。
|
||||
|
||||
## 3. 可读性与调用规范
|
||||
|
||||
每个函数单元的叙述比例必须超过 50%,同时说明真实用途和边界;不能靠重复套话凑比例。
|
||||
参数和返回契约表属于文档面,绑定的数据表仍须表达真实数据。
|
||||
|
||||
宿主等不透明调用用遮蔽语法表达动作:`[]` 写做什么,`()` 写实际执行代码。
|
||||
返回和赋值仍遵循原有标记;标签不执行,也不替代失败处理。
|
||||
|
||||
```markdown
|
||||
**出 = [put] 入=`表` 键="a" 值=1**
|
||||
## read_text
|
||||
|
||||
**出 = put 入=`表` 键="a" 值=1**
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| path | text | 必填 | 授权根目录内的文件路径 |
|
||||
|
||||
> put 入=`表` 键="a" 值=1
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | text | UTF-8 文本;无效编码或读取失败产生诊断 |
|
||||
|
||||
输入路径 `path`。此操作读取整个文件;大文件应改用分块读取。
|
||||
文件根目录由调用方授权,不能通过传入路径绕过权限。
|
||||
|
||||
读取完成后,我们返回*[读取授权范围内的 UTF-8 文本](> host_read_text path=`path`)*,供调用方继续处理。
|
||||
```
|
||||
|
||||
带布尔开关时可用前置修饰:`严格 [parse] text=`源`` → `严格=True`(形参名与修饰语字面一致;核心不剥「的」等词缀)。
|
||||
|
||||
## 3. 硬约束
|
||||
|
||||
| 要 | 不要 |
|
||||
|----|------|
|
||||
| GFM 表作数据;`table.put` / 具名助手 | `json.set` 链当字典构造器 |
|
||||
| 作者程序用 `[k](c)` 取元;`- [项](集合)` foreach | 新代码写 `` m[^k] `` |
|
||||
| 中英 API 对称(见 [stdlib-i18n.md](stdlib-i18n.md)) | 只改一侧 |
|
||||
| 一例跑通即文档(public/stdlib 或 examples) | 另开第二套「文档站」手写说明 |
|
||||
|
||||
**库函数体内的叙述坑:** 函数体里的链接形 `[k](c)`、以及单独的 `**强调**` 会被当成可执行代码。库内说明用「链接取元 / link-index」等字面描述;可执行示例放在 `public/stdlib` 或 `examples/`,不要写在 `##` 体内当叙述。
|
||||
集合读取使用 access(collection, key),不使用旧链接取元;循环使用显式遍历。
|
||||
用 GFM 表和具名助手表达结构化数据,避免 json.set/json.append 链。
|
||||
说明中的调用示例放在未绑定代码围栏内,不能让示例意外成为函数执行步骤。
|
||||
中英文源码保持语义、默认值与行为一致;检查叙述比例、契约并执行真实示例。
|
||||
|
||||
## 4. 波次
|
||||
|
||||
|
||||
@@ -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 图 |
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted;统一 `import bind:target` 已锁定** |
|
||||
| 状态 | **Accepted;嵌套 YAML `import:` / `导入:` 映射已锁定** |
|
||||
| 日期 | 2026-08-13 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
@@ -16,9 +16,9 @@
|
||||
|
||||
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存。
|
||||
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
|
||||
- 旧 frontmatter `import path:path.mq.md` 对 Markdown / 编辑器不友好,且与调用标记 `>` 抢外形。
|
||||
- 旧 frontmatter 一行式 `import bind:target` 在 YAML 里会变成带空格的键,与正规元信息不兼容。
|
||||
|
||||
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为可读的 `import bind:target`。
|
||||
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为嵌套 YAML 映射 `import:\n bind: target`。
|
||||
|
||||
---
|
||||
|
||||
@@ -29,8 +29,8 @@
|
||||
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
|
||||
2. **点号寻址调用**:`库.成员`、`库.对象.成员`;`.` 表示定义树寻址。
|
||||
3. **库名不是变量**:路径段为**裸标识符**,不加反引号。
|
||||
4. **短名与文件导入同形**:`import fmt:time.format`,废除独立 `use` 关键字。
|
||||
5. **中英对等**:`import` / `导入`。
|
||||
4. **短名与文件导入同形**:同在 `import:` 映射下写 `fmt: time.format`,废除独立 `use` 关键字。
|
||||
5. **中英对等**:`import:` / `导入:`。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
@@ -54,27 +54,38 @@
|
||||
|
||||
### 3.2 导入句法(frontmatter)
|
||||
|
||||
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。
|
||||
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。键为合法 YAML:`import:` / `导入:`,值为嵌套映射。
|
||||
|
||||
```yaml
|
||||
---
|
||||
import:
|
||||
utils: utils.mq.md
|
||||
json: lib/json.mq.md
|
||||
fmt: time.format
|
||||
---
|
||||
```
|
||||
|
||||
| 含义 | 英文 | 中文 |
|
||||
|------|------|------|
|
||||
| 导入文件 | `import utils:utils.mq.md` | `导入 utils:utils.mq.md` |
|
||||
| 标准库 | `import json:lib/json.mq.md` | `导入 json:lib/json.mq.md` |
|
||||
| 短名(成员) | `import fmt:time.format` | `导入 fmt:时间.格式化` |
|
||||
| 导入文件 | `import:` → `utils: utils.mq.md` | `导入:` → `utils: utils.mq.md` |
|
||||
| 标准库 | `json: lib/json.mq.md` | 同左(或中文库路径) |
|
||||
| 短名(成员) | `fmt: time.format` | `fmt: 时间.格式化` |
|
||||
|
||||
规则:
|
||||
|
||||
- **绑定名必填**,在 `:` 左侧(裸名,无反引号)。
|
||||
- `:` 右侧 `target`:
|
||||
- **绑定名必填**,为映射键(裸名,无反引号);冒号后须有空格(正规 YAML)。
|
||||
- 映射值 `target`:
|
||||
- 以 `.mq.md` 结尾 → **文件导入**;
|
||||
- 否则为 **点号路径**(≥2 段),把该成员绑为本地短名(须先有对应文件导入)。
|
||||
- 同一文件内绑定名不得冲突(文件库名与短名共用命名空间)→ 硬错误。
|
||||
- 旧写法 `> ….mq.md`、`> … as …`、`> use …`、`> 使用 …` → **硬错误**,并提示新句法。
|
||||
- 同一文件不得同时出现 `import:` 与 `导入:`。
|
||||
- 旧写法一行式 `import bind:target`、`> ….mq.md`、`> use …` → **硬错误**;可用 `marqdo migrate imports --write` 迁移。
|
||||
|
||||
### 3.3 废除的旧规则
|
||||
|
||||
不再支持:
|
||||
|
||||
- 一行式 `import bind:target` / `导入 bind:target`;
|
||||
- 省略绑定名时用文件名茎作库名;
|
||||
- 导入侧 `as` / `作为`;
|
||||
- 独立关键字 `use` / `使用`。
|
||||
@@ -101,8 +112,9 @@ path_callee ::= ident ('.' ident)+
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
time: lib/time.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -139,8 +151,9 @@ import json:lib/json.mq.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import fmt:time.format
|
||||
import:
|
||||
time: lib/time.mq.md
|
||||
fmt: time.format
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -153,10 +166,11 @@ import fmt:time.format
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
time: lib/time.mq.md
|
||||
writeback: lib/writeback.mq.md
|
||||
agent: ext/ai/agent.mq.md
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -179,13 +193,12 @@ import json:lib/json.mq.md
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| `import time:lib/time.mq.md` | `import time:lib/time.mq.md` |
|
||||
| `import t`:lib/time.mq.md | `import t:lib/time.mq.md` |
|
||||
| `import fmt`:time.format
|
||||
| `import time:lib/time.mq.md` | `import:` → `time: lib/time.mq.md` |
|
||||
| `import fmt:time.format` | `import:` → `fmt: time.format` |
|
||||
| 茎名默认库名 | 绑定名始终显式 |
|
||||
| 扁平合并进全局 | 仅库绑定 + 可选短名 |
|
||||
|
||||
不提供旧 `>` 导入过渡开关。
|
||||
不提供旧一行式 / `>` 导入过渡开关;`marqdo migrate imports --write` 可机械迁移。
|
||||
|
||||
---
|
||||
|
||||
@@ -201,20 +214,20 @@ import json:lib/json.mq.md
|
||||
|
||||
## 8. 实现要点
|
||||
|
||||
1. frontmatter 只解析 `import` / `导入` 行;右侧分流文件 / 成员。
|
||||
1. frontmatter 解析嵌套 `import:` / `导入:` 映射;子项分流文件 / 成员。
|
||||
2. AST 仍用 `Import`(文件)与 `Use`(短名)存储,对外无 `use` 关键字。
|
||||
3. 金样例:`tests/structure/import/`、`tests/structure/ns/`。
|
||||
|
||||
| 阶段 | 内容 |
|
||||
|------|------|
|
||||
| M1+M2 | 点号路径 + 短名 — 已落地 |
|
||||
| **Import 句法** | 统一 `import bind:target` — **本波次** |
|
||||
| **Import 句法** | 嵌套 YAML `import:` — **本波次** |
|
||||
|
||||
---
|
||||
|
||||
## 9. 决议摘要
|
||||
|
||||
1. 导入 = `import bind:target`(`导入` 等价)。
|
||||
1. 导入 = 嵌套 `import:` / `导入:` 映射(`bind: target`)。
|
||||
2. target = `.mq.md` 文件 **或** `库.成员` 点号路径。
|
||||
3. 调用以裸名点号路径寻址;实例方法用反引号接收者(仅独立 `>` 调用;`*…*`/`**…**` 段内接收者不加反引号)。
|
||||
4. 裸点号 `a.b`:`a` 为局部变量 → 方法调用,否则 → 库路径(Python 统一命名空间)。
|
||||
@@ -1,5 +1,35 @@
|
||||
# 文档会话(View Cells)
|
||||
|
||||
## 2026-11-02:并发控制与完整历史 v5
|
||||
|
||||
以下为当前实现;后文保留首版设计与当时的状态表。
|
||||
|
||||
- HTTP `kernel/interrupt` 查找已存在的会话,经独立控制器发送请求,不等待单元执行锁或其他文档的初始化。未打开、尚在初始化的会话返回错误,不启动新内核。已加载文档的源码文件被删除后仍可取消正在执行的单元。
|
||||
- 内核的中断能力绑定其持有的子进程,并在回收前撤销;旧能力不能指向后来启动的内核。引导阶段的取消被暂存,收到 ready 后投递。逻辑取消输入会合并重复信号;投递错误明确返回。Windows 尚无对应的保状态中断实现。
|
||||
- 取消使 Run All 在当前单元结束后停止,返回实际 `ran`、`remaining` 和 `cancelled`;不会继续运行后续单元。内核没有退出时,取消前已发生的状态修改保留。close 撤销 API 会话,重新打开不会激活旧引用。
|
||||
- 完整历史 v5 将并发取消作为所在操作的 `controls` 输入记录:操作起点之后的微秒偏移及各内核的真实接收结果。严格回放按输入重新投递并重新观察回执;操作先结束时撤销剩余定时请求,不能流入下一操作。实际回执或观察不匹配就报告差异。v4 无控制输入的历史仍可检查;v4 中出现 controls 字段会被拒绝。
|
||||
- 严格检查先完成纯验证,再启动回放内核。实际执行中,每次协议请求必须先与预期请求一致;实际回复和每个单元的观察、批次结果也立即比较。首个差异后停止依赖后缀,包括同一个 Run All 内的后续单元。未执行的观察标记 `compared=false`,不冒充已比较的第二个差异。
|
||||
|
||||
快照导出支持可选 `compact:true`。默认仍为完整 JSON;紧凑格式
|
||||
`marqdo.history.dag` v1 对相同子值做自底向上共享,整数使用十进制文本、
|
||||
浮点数保存 IEEE 位模式,保留映射顺序和全部历史字段。导入和严格回放会自动
|
||||
识别格式。SHA-256 校验只检测内容一致性,不提供来源认证。
|
||||
解码要求规范节点、向后引用、全部可达和唯一键,并在展开前检查最多
|
||||
1,000,000 个节点、8,000,000 个展开值、512 MiB 保守展开预算、128 层深度;
|
||||
展开后再次检查安全值域。此格式减少导出字节数,尚未减少录制时内存,也不保证更快。
|
||||
|
||||
实际取消实验覆盖 Unix 上同步 Python/Node 持久会话;不能推导任意外部代码均有界停止。
|
||||
[Python 3.14 信号文档](https://docs.python.org/3.14/library/signal.html#execution-of-python-signal-handlers)
|
||||
说明纯 C 计算可延迟信号处理;
|
||||
[Node 22.22.1 vm 文档](https://nodejs.org/download/release/v22.22.1/docs/api/vm.html#timeout-interactions-with-asynchronous-tasks-and-promises)
|
||||
说明异步任务可能逃出同步求值的中断范围。完整源码 elaboration、控制适配器、
|
||||
真实时钟与信号调度到形式模型的 refinement 仍需完成,不能以这些测试代替。
|
||||
|
||||
相关实现:`foreign_session/control.rs`、`foreign_doc/control.rs`、
|
||||
`foreign_doc/packing.rs`、`foreign_doc/replay.rs` 与 `view/notebook_api.rs`。
|
||||
真实 TCP/HTTP 取消、逐单元副作用屏障和独立快照消费记录位于论文
|
||||
`PLDI/experiments/reviewer-v5/`。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **D1–D3 首版已实现;D4/D5 待做** |
|
||||
|
||||
@@ -0,0 +1,131 @@
|
||||
# Document oracle observations and strict replay
|
||||
|
||||
`foreign.oracle_journal` returns a copy of this evaluation's observations as
|
||||
ordinary `index/channel/value` records. Successful admitted `session_eval`,
|
||||
`session_get`, and document `json.parse` operations append `eval`, `get`, and
|
||||
`decode`, respectively. Set/open/close do not append. An observation is
|
||||
validated recursively before append; handles and code objects cannot enter.
|
||||
Each new HostContext starts with an empty observation list.
|
||||
|
||||
`foreign.replay_check expected=J observed=J2` is a pure comparison, with no
|
||||
foreign execution. It validates contiguous zero-based indices, channel tags
|
||||
and crossing-domain membership. Records compare structurally by field name,
|
||||
independent of field order. The result contains `ok`, the least mismatching
|
||||
`index`, and both records (None for a missing entry). Two empty journals
|
||||
match. Failure to provide a valid journal is an error, not a match.
|
||||
|
||||
The interactive `DocumentSession::replay_check(snapshot)` is a different layer:
|
||||
it executes a recorded trace from fresh state. Version-2 snapshots contain the
|
||||
full chronological oracle trace, recorded stdin per step, its declared count,
|
||||
the plan and source identity. Preflight validates every step before any foreign
|
||||
execution. Every step is compared; none is skipped. Repeated cell executions
|
||||
are distinct observations. Execution timing logs and cell display summaries
|
||||
are not comparison inputs. Matching input values in a supplied snapshot is
|
||||
consistency checking, not cryptographic authentication of the recording.
|
||||
|
||||
Snapshots carry the SHA-256 of the loaded document text. Import checks it
|
||||
before restoring foreign bindings, and preflights all crossing payloads before
|
||||
mutation. Reload retains prior oracle observations with their original source
|
||||
hashes, so a later checker can reject an incompatible trace.
|
||||
|
||||
Lean: DocCalc's independent `runForeignLive` cursor simulates `runForeignAcc`
|
||||
for arbitrary prefixes, observation accumulators and code sequences, including
|
||||
oracle failures. `ForeignTrace` composes the registry's open/eval/close
|
||||
judgments using independent normative and interactive execution control;
|
||||
`trace_simulation`, `trace_correspondence`, and `trace_replay` quantify arbitrary
|
||||
multisession action sequences, also when a run faults. These supplement the
|
||||
existing theorems without removing them.
|
||||
|
||||
Tests: `tests/oracle_journal.rs` runs the public document API on both evaluators;
|
||||
`host::oracle::tests` covers journal equality and length localization;
|
||||
`host::foreign_doc::tests` covers the live trace preflight and actual replay;
|
||||
`host::foreign_session::tests` includes generated two-session model checks and
|
||||
Python/Node boundary and process-failure experiments. The research runner is
|
||||
`MarqdoThesis/PLDI/experiments/reviewer-v5/run.py`.
|
||||
|
||||
## Stateful requests and semantic projection
|
||||
|
||||
`HostContext.foreign_protocol_steps` records internal request attempts and
|
||||
replies, including set values, copied eval input and raw stdin. It is separate
|
||||
from the admitted language journal: rejected inbound responses belong to the
|
||||
protocol evidence, while only admitted values belong to the oracle journal.
|
||||
An input refused before send produces no protocol request. A response refused
|
||||
after execution does not undo kernel effects; the post-state is retained.
|
||||
|
||||
Language observations are recorded at the document API boundary and by live
|
||||
cell evaluation. Low-level get/names used during snapshot export do not append
|
||||
language observations. A successful eval projects to its result. A failed eval
|
||||
projects to a record of stable status, output and diagnostics. Process timing,
|
||||
commands and handles are not semantic values. The exact source path allocated
|
||||
for one-shot execution is alpha-renamed only in diagnostic fields; raw stderr
|
||||
and stdout remain available unchanged, and ordinary paths/error differences
|
||||
are still compared. Live oracle records carry this same projected `value`.
|
||||
|
||||
Python/Node replies mark serialization-domain failure with `domain_error`.
|
||||
Error text is not used to infer this flag. Python refuses non-string object
|
||||
keys; Node sanitizes objects with a null prototype to preserve special keys.
|
||||
The common strict JSON decoder checks duplicate keys before materializing a
|
||||
map, rather than losing them through overwrite.
|
||||
|
||||
`ForeignState.lean` refines the earlier eval-only fragment with opaque kernel
|
||||
state, complete request histories, set/get/eval input/decode, monotonic handle
|
||||
allocation and fault outcomes carrying the admitted prefix. An adaptive
|
||||
Program has continuations on actual observations; its correspondence theorem
|
||||
covers data-dependent next actions, not just a fixed schedule. Mapping actual
|
||||
document elaboration and host bindings to this program is a further proof
|
||||
obligation recorded in the research status file.
|
||||
|
||||
## Complete history, snapshot version 4 (2026-11-02)
|
||||
|
||||
Strict interactive replay now records operations, not just successful cells.
|
||||
Each public execution/mutation boundary records typed arguments, success or
|
||||
failure, admitted observations, cell-oracle records, and stable resulting
|
||||
state. Nested implementation calls are grouped under the user's operation.
|
||||
The history includes set/get, run/step/run-all, restart, reload, plan edits,
|
||||
clear, snapshot inspection and imported values. Failed attempts remain in the
|
||||
history; rejected handles and secrets have only non-capability/redacted tags.
|
||||
Clearing display outputs cannot erase the history's oracle projection.
|
||||
|
||||
The snapshot stores the materialized initial plan and historical reload plans.
|
||||
Entry text is parsed at its original path, retaining relative imports without
|
||||
rewriting the user's document. Initial bindings are reapplied when a kernel is
|
||||
reopened; unchanged reload kernels retain state, whereas changed language or
|
||||
command retires the incompatible process. Loaded source/metadata and cached
|
||||
cell outputs are updated consistently.
|
||||
|
||||
Preflight checks the entire operation stream, all source revisions, plan edits,
|
||||
binding/cursor/generation transitions, and oracle projections before starting
|
||||
any replay kernel. Executing the trace compares each result, admitted value,
|
||||
cell result and stable state. The first mismatch stops its dependent suffix;
|
||||
`executed_actions` and `remaining_actions` make this explicit. `matched` counts
|
||||
admitted observations and `matched_actions` counts operations. No missing
|
||||
record is silently accepted or skipped.
|
||||
|
||||
The HTTP replay-check endpoint performs an isolated comparison and retains an
|
||||
existing warm session. It validates malformed input before starting even a
|
||||
seed kernel; duplicate JSON fields are refused before overwrite. Verification
|
||||
can still run recorded foreign work and its external effects: isolation is of
|
||||
the document session, not a process sandbox. `replay_snapshot` remains the
|
||||
separate legacy cell re-run API and makes no strict-history comparison claim.
|
||||
Older version-2/3 snapshots may be used by legacy restoration/re-run surfaces;
|
||||
they cannot prove a complete action history and strict checking requires v4.
|
||||
|
||||
`ForeignHistory.lean` models explicit command boundaries. A fault terminates
|
||||
its command, a later command receives the actual retained registry, and the
|
||||
history retains all command faults and admitted observations. It proves
|
||||
command-history correspondence, journal membership and no alias resurrection
|
||||
through arbitrary recovery histories. This extends the adaptive Program
|
||||
results; the general source-elaboration refinement is a separate outstanding
|
||||
proof obligation.
|
||||
|
||||
Experiment source inputs are frozen before running, checked again afterward,
|
||||
and archived with their hashes. The current passing bundle is identified by
|
||||
`MarqdoThesis/PLDI/experiments/reviewer-v5/LATEST-PASSING.json`.
|
||||
|
||||
Each operation also retains its internal protocol attempts/replies, including
|
||||
refused inspection results. Those records are compared even when an inspector
|
||||
could not return a value. They are control evidence and do not admit rejected
|
||||
payloads into the language journal. An explicit document session_names request
|
||||
adds its admitted array on the decode channel; internal names/get probes do not.
|
||||
Reload records either a historical source/plan input or its input-read error;
|
||||
replay consumes that captured version input and does not rewrite past files.
|
||||
@@ -1,5 +1,7 @@
|
||||
# 调用写法评估:`[函数名](参数)` 与更接近人读的调用形式
|
||||
|
||||
> **2026-10-23 审阅裁决**:“原型回退”仅描述当时实验,当前 payload 已支持 `f(args)` 和具名实参。旧 Classic 索引冲突不再决定默认语法;保留熟悉的调用形态与文档原生描述并不矛盾。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),不要把本文备选形式当作已批准的新语法。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 待决策**(原型已验证并已回退,未合入代码) |
|
||||
|
||||
@@ -0,0 +1,435 @@
|
||||
# qdagent 知识工作台所需的多模型运行与 View 嵌入支持
|
||||
|
||||
日期:2026-10-25。状态:Partial / in progress(M00–M06 合同门禁 + F02 agent.step/resume 假模型 e2e + USTC live selection smoke + DocumentView 浏览器只读核对已落地;F 矩阵未全绿,不得整文宣称 Verified;原生非兼容适配器仍 unavailable)。
|
||||
|
||||
源码基线:Marqdo `dc853fb`(2.1.2),qdagent `643dd31`,已同步远端。应用侧配套:[qdagent 多提供商与知识工作台](../../../qdagent/doc/design/multi-provider-and-knowledge-workbench-2026-10-25.md)。跨仓相对链接以兄弟仓库工作区布局为准。
|
||||
|
||||
沿用 [文档原生开发指导](document-native-development-guide.md)、[可执行知识规范](../next/Marqdo_Executable_Knowledge_Development.md) 与 [View 阅读体验设计](view-knowledge-reading-experience-2026-10-24.md)。本规格补充嵌入、调用身份和运行观测,不另造语言或第二套知识真相。
|
||||
|
||||
## 1. 框架目标与责任边界
|
||||
|
||||
让任何宿主应用可以按请求构造模型、追踪所有真实模型调用、以只读 View 展示知识文档,并从引用定位到版本一致的知识与来源。qdagent 的设置页、模型目录持久化、账单展示、会话导航、工作区授权和画像管理由应用实现。
|
||||
|
||||
| 能力 | Marqdo 拥有 | qdagent 拥有 |
|
||||
|---|---|---|
|
||||
| 多提供商 | 协议适配、模型 handle、能力协商、调用参数、归一化错误 | 提供商账户/端点/模型 CRUD、默认选择、凭证管理 |
|
||||
| 模型路由 | Runtime 执行显式选择和允许的辅助模型策略 | 用户选择、工作区模型允许列表、路由授权 |
|
||||
| 用量 | 每次请求/重试的身份、usage 来源与完整性、子任务传播 | 持久化账本、价格版本、费用估算、筛选/导出/预算策略 |
|
||||
| 实时运行 | 逐事件输出、取消传播、背压、终态 | HTTP 会话鉴权、轮次映射、持久化事件重放、断线 UX |
|
||||
| View | 文档语义、正文/目录/步骤、纯读取、稳定定位、可嵌入输出 | 容器/主题/深链/阅读历史/产品操作 |
|
||||
| 知识引用 | 解析/歧义/版本/来源定位、验证多维事实 | 消息引用标识、授权、历史资料保存与入口 |
|
||||
| 工作区 | 按显式 project 编译/查询,缓存及输出隔离 | 工作区 registry、root 解析、用户权限、文件管理 |
|
||||
| 画像与笔记 | 通用文档渲染、来源关联、验证/编译原语 | 内容策略、提案/确认、生命周期、展示和上下文选择 |
|
||||
|
||||
不在语言核心添加 provider/workspace/profile 关键字;沿用 `.mq.md` 函数、结构化参数、扩展插件和 MLSP。不得让“可读”取决于用户手填 hash、node id、source span 等机器字段。
|
||||
|
||||
## 2. 2.1.2 已完成的基础与剩余缺口
|
||||
|
||||
### 2.1 当前可复用基础
|
||||
|
||||
| 源码 | 已有内容 | 本规格的增量 |
|
||||
|---|---|---|
|
||||
| [ext/ai/llm](../../ext/ai/llm.mq.md) | `create(model,base_url,api_key,backend,name)`、命名 handle、ask/stream | 无需重做基础 handle;增加隔离策略、协议能力、完整消息与调用身份 |
|
||||
| [LLM plugin](../../plugins/llm/src/lib.rs) | 兼容 chat completions HTTP、SSE 文本读取、非流 usage 三项 | SSE usage/异常终态/每次调用观测、可取消持续输出 |
|
||||
| [Agent](../../ext/ai/agent.mq.md) | Agent 唯一 loop、router_model、EFI、绑定/发布门闩 | 主/路由/修复/生成工作簿的模型及计量上下文传播 |
|
||||
| [语义 IR](../../src/sema/ir.rs) | Artifact、KnowledgeStep、KnowledgeRef、SourceLocation、BoundCall | View 面向阅读的完整投影及 ID/版本映射 |
|
||||
| [MLSP](../../src/mlsp.rs) | `artifact.inspect`、`link.resolve`、verify/bind/execute、document.extract | 只读 document/引用解析及 capabilities 版本握手 |
|
||||
| [KnowledgePresentation](../../src/view/knowledge_present.rs) | schema v1,artifact nodes、依赖、generation/page token | 保留兼容,新增正文/目录/refs/source spans/结构化诊断 |
|
||||
| [View output](../../src/view/output.rs) | `--no-exec` 在构建前跳过 capture | 将纯读取能力暴露给嵌入客户端,不复用会执行的 live 默认路径 |
|
||||
| [document extract](../../src/document_extract.rs) | TXT/MD,partial,PDF/DOCX/OCR 显式不支持 | 能力查询及稳定来源定位;不要求本阶段重造 OCR |
|
||||
| [数据资源](../../ext/data/db.mq.md) | SQLite migrate/exec/事务、唯一/索引声明 | 应用可直接承载 registry/账本/索引;不需另加产品专用数据库框架 |
|
||||
|
||||
2.1.2 已把知识辅助块移到正文后并折叠,跳过 module/type 卡片,显示“结构步骤非实际执行时序”。旧 View 截图中的最初顺序问题已有改进;但这不意味着已提供能直接放进 qdagent 右栏的独立阅读 SDK。
|
||||
|
||||
### 2.2 直接影响集成的事实
|
||||
|
||||
1. `llm.complete_result` 当前仍走 `openai.chat_completions`,Ollama 也是兼容路径;`backend` 名称不是任意原生协议适配器。
|
||||
2. `plugins/llm::chat_completions` 从 `prompt` 构造一条 user 消息,没有完整消息列表契约;不能靠模型选择 UI 弥补历史丢失。
|
||||
3. `usage_from` 缺字段填零;Agent `model_turn(stream=True)` 直接 `tokens=0`,最终 `token_cost=tokens`。现有输出无法支撑准确货币或流式用量显示。
|
||||
4. 原生 LLM SSE parser 返回事件数组;`ext/ai` 有流事件机制,但应用所用 [web invoke](../../plugins/web/internal/httpx/routes_invoke.go) 在 `CallLibPath` 返回后才写 `{sse}`。需要打通实际增量路径,不能只换 Content-Type。
|
||||
5. Agent 生成子工作簿的模板仍能构造默认 `llm.llm`;只传主 agent handle 不足以证明嵌套调用沿用了用户选定模型。
|
||||
6. `build_file_view` 默认传 `execute=true`;live GET 路径使用它。嵌入阅读绝不能直接暴露这个入口。
|
||||
7. Presentation 目前按 artifacts 投影,缺全量 prose/heading/step/ref 的统一阅读树;`render_knowledge_html` 另从 steps/refs 渲染,容易与 JSON 事实发生覆盖差异。
|
||||
8. `source_digest` 当前由语义 artifact hashes 汇总,`semantic_generation` 是语义散列截短,`page_token` 来自原文件。它们不能直接分别冒充原文 revision、`.marqdo/CURRENT` generation 和跨请求完整版本。
|
||||
9. `sse_accepts_packet` 对缺 token 的 legacy 包放行;正式嵌入客户端必须采用严格版本匹配,而不是继承这项兼容宽容。
|
||||
10. `artifact.inspect/link.resolve` 每次走当前 semantic_project;现有入口不保证可以读任意历史 generation。历史引用需要明确的保留与解析合同。
|
||||
|
||||
## 3. 共用合同、版本与能力发现
|
||||
|
||||
合同名字固定为 `ModelSelectionV1`、`ModelCallUsageV1`、`RuntimeEventV1`、`DocumentViewV1`、`KnowledgeLocatorV1`;它们是这次扩展的 v1,与当前 KnowledgePresentation `schema_version:1` 不混用。新增 read model 不强行给已有 JSON 改含义。
|
||||
|
||||
新增 MLSP `capabilities`(拟议):
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"runtime_version": "implementation-version",
|
||||
"features": {
|
||||
"llm.explicit_selection": 1,
|
||||
"llm.call_usage": 1,
|
||||
"runtime.event_stream": 1,
|
||||
"runtime.cancel": 1,
|
||||
"view.document": 1,
|
||||
"view.reference_resolve": 1
|
||||
},
|
||||
"adapters": [{"id": "openai-compatible", "available": true}],
|
||||
"extract_formats": [{"format": "text", "available": true}],
|
||||
"loaded_plugins": [{"name": "llm", "capabilities": ["call_usage_v1"]}]
|
||||
}
|
||||
```
|
||||
|
||||
只返回实际探测且加载可用的功能。不能仅从 CLI 版本推断 native plugin 符号存在;字段未知时应用降级或解释不支持。协议允许新增可选字段;删除/改变状态语义必须提升 major contract version。能力查询不调用供应商、不执行项目代码。
|
||||
|
||||
MLSP 继续使用现有 `{id,ok,result|error}` envelope;qdagent `/api/app` 转为自己的 `{ok,schema_version,data|error}`,不要要求它们共享同一层 envelope。所有合同提供成功、partial、unknown、unsupported、stale、cancelled、错误 fixtures 与 JSON Schema;应用和框架从相同样本跑消费测试。
|
||||
|
||||
## 4. M01:请求级模型身份与适配器
|
||||
|
||||
### 4.1 显式选择合同
|
||||
|
||||
应用将配置解析成可信 `ModelSelectionV1` 后传入 runtime,核心字段:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"selection_id": "sel-1",
|
||||
"provider_id": "provider-1",
|
||||
"model_id": "model-2",
|
||||
"provider_revision": 3,
|
||||
"model_revision": 5,
|
||||
"adapter": "openai-compatible",
|
||||
"endpoint_ref": "endpoint-local-1",
|
||||
"credential_ref": "credential-local-1",
|
||||
"credential_version": 2,
|
||||
"upstream_model_id": "example-model",
|
||||
"parameters": {"max_output_tokens": 2048},
|
||||
"fallback_policy": "disabled"
|
||||
}
|
||||
```
|
||||
|
||||
endpoint/credential 引用由宿主 resolver 解析为调用局部配置;短期直接向现有 `llm.create` 传参数亦可,但这不是可序列化的 public snapshot。API key 不能出现在 events、debug JSON、生成工作簿、prompt、错误 URI 或持久化模型对象中。
|
||||
|
||||
当前显式 args 优先的能力保留;新增 strict selection 模式:字段缺失报错,不回退 process env/frontmatter。无凭证端点通过 `auth_mode:none` 显式表达,避免 falsy key 触发环境 fallback。legacy 命令行未传 selection 时仍可沿用原有 env 行为;本地便利兼容不扩散到应用请求。
|
||||
|
||||
每个运行绑定 selection snapshot,后续设置改变不修改它。主模型与 router_model 分开但同属受控 selection 集;manual 模式所有需要 LLM 的步骤固定选择,REUSE 无模型调用仍允许。fallback 必须由宿主明确授予、列出允许目标,不能因额度/网络错误静默转到另一个供应商。
|
||||
|
||||
### 4.2 子任务和工作簿传播
|
||||
|
||||
统一 `RunContextV1 = run_id,parent_run_id?,turn_id?,workspace_scope,selection_context,usage_sink,event_sink,cancellation_token`。进入 ask/step/plan、repair、summary、learn、子工作簿时显式继承;新 run/call id 关联父节点。
|
||||
|
||||
生成工作簿只包含不可重放滥用的运行上下文引用,不写密钥;执行时宿主注入/解析。独立导出工作簿在缺凭证/选择时清晰要求配置,不偷偷取默认模型。在任何 child/spawn/resume 路径遗漏 selection 都应由 strict 模式拒绝并给出定位诊断。
|
||||
|
||||
同时审查环境变量不只是凭证:project root、temp request、输出目录、event sink 也必须请求局部,不能在并发运行中依靠进程可变状态串联。
|
||||
|
||||
### 4.3 适配器与消息
|
||||
|
||||
适配器最小职责:验证 selection、报告能力、序列化请求、解析增量结果、usage 归一化、取消传输、错误归一化。可选 discovery/probe;无模型列表 API 仍允许手工配置。
|
||||
|
||||
V1 消息包含 role 和 content parts,parts 最低 text,附件通过受控引用;tool call/result 要保持配对及 role。不支持的 part/parameter 返回 `llm.unsupported_input/parameter`,不能悄悄转成空字符串。适配器决定协议格式,Agent 决定行为;qdagent 不拥有供应商协议代码。
|
||||
|
||||
阶段一验证两个不同兼容端点,分别至少两个模型,以及无密钥本地兼容服务。阶段二增加原生非兼容协议:每个适配器需具名能力、流式/非流式/错误/取消/usage fixtures 和独立接入说明后才能在 capabilities 中置 available。不能把所有厂商默认走兼容接口后统称全支持。
|
||||
|
||||
统一参数采用 `max_output_tokens,temperature?,stop?,reasoning?` 等语义键,能力不支持时明确拒绝;不随意透传客户端未知参数。实际 upstream model 若与请求 id 不同,在 result 中保留 requested/resolved 两者。供应商版本与价格随时变化,本文仅锁定内部合同;实施原生适配器时另附当时官方协议核验记录。
|
||||
|
||||
## 5. M02:用量、事件流与取消
|
||||
|
||||
### 5.1 ModelCallUsageV1
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"call_id": "call-1",
|
||||
"attempt_id": "attempt-1",
|
||||
"parent_call_id": null,
|
||||
"run_id": "run-1",
|
||||
"turn_id": "turn-1",
|
||||
"workspace_scope": "ws-1",
|
||||
"purpose": "answer",
|
||||
"selection_id": "sel-1",
|
||||
"provider_id": "provider-1",
|
||||
"model_id": "model-2",
|
||||
"requested_model": "example-model",
|
||||
"resolved_model": "example-model",
|
||||
"status": "succeeded",
|
||||
"usage_state": "final",
|
||||
"measurement_source": "provider",
|
||||
"input_tokens": 1200,
|
||||
"output_tokens": 300,
|
||||
"total_tokens": 1500,
|
||||
"cached_input_tokens": 800,
|
||||
"reasoning_output_tokens": null,
|
||||
"revision": 2,
|
||||
"provider_request_id": "opaque-provider-id",
|
||||
"started_at": "2026-10-25T01:00:00Z",
|
||||
"finished_at": "2026-10-25T01:00:03Z"
|
||||
}
|
||||
```
|
||||
|
||||
字段要求:tokens 非负整数或 null;`usage_state = pending|partial|final|unknown`;`measurement_source = provider|estimated|none`。估算可作为单独 estimate 字段返回,不能覆盖实测字段。供应商没有报告时用 null/unknown,传输失败不能自动解释成零消耗。
|
||||
|
||||
`status = started|succeeded|failed|cancelled|interrupted`,status 和 usage_state 独立。每个真实发出的 HTTP attempt 一个唯一 id;预检拒绝只产生 call-rejected 事件,不伪造已发送请求。框架重试必须可观测:所有 attempts 包括失败/有部分输出的 attempt;重复 delivery 的 usage revision 不算新请求。
|
||||
|
||||
累计 SSE usage 在同 attempt 内按 revision 发布完整快照,不让上层猜是 delta 还是 total。provider 总量与 input/output 不一致时保留原始读数及 `usage.inconsistent` 诊断,不自行强制改账;细分字段要标 inclusion 关系以避免缓存、reasoning 与总量重复相加。只保留脱敏的必要 provider usage 扩展字段,不把完整原始响应当 public usage。
|
||||
|
||||
纯知识复用用 run summary 中 `llm_calls=0`、`measurement_source=none` 表示,而不是伪造一条耗费为零的模型请求。框架输出 `call_count,known_tokens,unknown_call_count`,宿主据此显示覆盖程度。
|
||||
|
||||
### 5.2 事件流合同
|
||||
|
||||
```text
|
||||
run.started
|
||||
→ model.resolved
|
||||
→ model.call.started
|
||||
→ message.delta / tool.progress / usage.updated(零到多次)
|
||||
→ model.call.finished(每个 attempt 各一条)
|
||||
→ document.produced / citation.produced(仅有真实对象时)
|
||||
→ run.completed | run.failed | run.cancelled | run.interrupted
|
||||
```
|
||||
|
||||
`RuntimeEventV1` 公共字段:`schema_version,event_id,seq,run_id,parent_run_id?,turn_id?,workspace_scope,timestamp,type,payload`。seq 每个 run 单调;不同子 run 可以并发,宿主按所属 turn 另分配产品流序号。runtime terminal 事件仅一次;后续补全计量用有 revision 的 `usage.updated`,不能改变内容终态。
|
||||
|
||||
事件 sink 支持有界队列和背压;慢客户端不能无限堆积 token。丢弃可合并 progress 时记录 gap;内容与终态事件不可无声丢失。连接终止不会自动重跑;持久化/重放由应用,但框架需在实时回调后仍提供可核对的 final result/call summaries。
|
||||
|
||||
同一真实调用所有数据使用同一 run/call identity,不能流与最终结果各生成一套 id。工具参数/结果按 policy 脱敏,不把 secret、完整私有文件、模型内部推理链写入默认进度事件。
|
||||
|
||||
### 5.3 打通传输而不重造 Agent
|
||||
|
||||
需要同时打通 LLM provider reader → Agent event sink → host callback → web streaming handler → 浏览器。现有 `sys.stream_publish` 可以作为底座,但要验证它是否绑定正确请求且在 `CallLibPath` 返回前可写出;不能用进程全局事件广播混流。
|
||||
|
||||
可实施路径:新增 web 流式 invoke/job primitive,由框架注册 run handle 和 event sink;调用返回 handle 后宿主可订阅/取消。采用插件 ABI 增量接口及能力检测,旧 ABI 未支持时拒绝新 streaming 模式,保留旧完整返回。qdagent 只挂产品鉴权、event id 持久化和 HTTP 端点,不添加另一个推理循环。
|
||||
|
||||
SSE parser 必须处理任意 TCP 分块、UTF-8 跨块、CRLF、多行 data、注释 heartbeat、尾帧、usage-only 帧、[DONE]、连接在结束前关闭。未知可选事件可忽略且记诊断;已知事件无效、异常截断不能静默当成功完成。公共 framing 不包含供应商私有认证信息。
|
||||
|
||||
### 5.4 取消与重试
|
||||
|
||||
取消 token 传到 HTTP reader、循环、工具边界、子任务。取消后不得启动新模型调用/新工具;正在进行的不可抢占操作返回 `cancelling` 和是否仍运行,结束后才报告 cancelled。明确“停止生成”不能撤销已经完成的外部写入。
|
||||
|
||||
调用超时、连接错误、鉴权失败、限流、协议错误分开;错误字段包含 `code,retryable,retry_after_ms?,call_id,attempt_id,usage_state`。不要将原始包含密钥/完整 prompt 的错误直接传到 UI。限流/短暂网络错误按有界策略重试;已产生输出的重试不能接在同一条文字后假装连续,也不能把未知结果的外部工具操作自动重做。
|
||||
|
||||
费用价格由应用管理。框架保留 legacy `tokens/token_cost` 并标注 deprecated/单位为 token,新功能只消费 ModelCallUsageV1,避免破坏旧脚本的同时停止误用。
|
||||
|
||||
## 6. M03:无执行的嵌入式 View
|
||||
|
||||
### 6.1 新入口与纯度约束
|
||||
|
||||
新增内部公共服务 `analyze_document → project_read_model → render_fragment`;MLSP 暴露 `view.document`,可选 CLI `view document --json --no-exec` 与它共享实现。不要让新入口先进入 `build_file_view` 再隐藏按钮/清空输出。
|
||||
|
||||
读取允许:授权范围内原文/已编译快照/已有验证记录。读取禁止:运行模块入口、加载文档声明插件、执行外国代码、LLM、自动抓取 URL、写回、重新验证执行测试、隐式发布/重编译写盘。静态分析/内存投影允许;缺完整依赖时明确 partial。任何需要执行的行为必须另走显式 execute/verify 产品流程。
|
||||
|
||||
当前 `compile_project` 声明不加载插件/不求值/不抓取来源,可复用;缓存写入若需要,作为单独的宿主管理路径,不能把“读文档”隐含写项目目录。
|
||||
|
||||
### 6.2 DocumentViewV1 结构
|
||||
|
||||
请求由宿主传入受控 project 和文档定位,宿主必须已授权;框架仍做路径边界校验。
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "view.document",
|
||||
"params": {
|
||||
"project": "/authorized/project",
|
||||
"document": "knowledge/example.mq.md",
|
||||
"revision": "sha256:requested-source",
|
||||
"generation": "generation-id-or-null",
|
||||
"mode": "read",
|
||||
"node_id": "optional-node",
|
||||
"include": ["fragment", "outline", "nodes", "refs", "diagnostics"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "DocumentViewV1",
|
||||
"schema_version": 1,
|
||||
"document": {
|
||||
"id": "project-relative-document-id",
|
||||
"title": "知识标题",
|
||||
"source_revision": "sha256:raw-bytes-digest",
|
||||
"semantic_digest": "sha256:semantic-facts",
|
||||
"generation_id": null,
|
||||
"presentation_token": "opaque-token"
|
||||
},
|
||||
"execution": {"state": "not_run", "run_id": null},
|
||||
"render": {"format": "sanitized_html", "fragment": "<article class=\"mq-document\">…</article>", "renderer_version": "1"},
|
||||
"outline": [],
|
||||
"nodes": [],
|
||||
"refs": [],
|
||||
"diagnostics": [],
|
||||
"completeness": "complete",
|
||||
"capabilities": {"read_only": true, "has_semantics": true}
|
||||
}
|
||||
```
|
||||
|
||||
`generation_id` 来自实际编译投影;即时分析但未编译发布时为 null,同时给 semantic_digest。`source_revision` 是原始文件字节摘要,不能复用当前基于 artifacts 的 `source_digest`;`presentation_token` 覆盖 source revision、generation/semantic digest、依赖版本、renderer/schema、读取策略与请求范围。应用缓存还必须含用户授权范围。
|
||||
|
||||
`completeness = complete|partial`;语法损坏时允许返回原文与结构化诊断,但不能展示猜测出来的正常知识图。失败用 error envelope,不能空字符串伪装“文档无内容”。大文档 response 支持 section cursor 和 truncated 标识,限制要可配置并在响应中标明。
|
||||
|
||||
### 6.3 统一正文、目录、节点与引用
|
||||
|
||||
节点包含 `id,parent_id,kind,label,order,source_span,artifact_id?,ref_ids[],children[]`。kind 包括 heading/prose/table/code/observe/derive/call/iterate/narrate/navigation;正文树来自 parser/classifier/sema 的共同投影,不能只枚举 functions 后把每个步骤标 call。
|
||||
|
||||
outline 描述读者文档层级,不简单把函数和对象全铺成同一级。HTML 中节点带 `data-mq-node`,引用带 `data-mq-ref`;实现 payload 按需展开,说明作为正文。动态调用/无法解析引用保持原文并解释原因,不虚构执行边。
|
||||
|
||||
首批 renderer 共享 `src/view/document.rs` 的文档表面,standalone/full page 和嵌入模式调用同一 read model;只改变容器和导航外观,不产生第二种语义解释。替换当前 `KnowledgePresentation` 与 `render_knowledge_html` 双路径重复组装。
|
||||
|
||||
稳定 ID 的保证范围要写明:
|
||||
|
||||
- 同一 revision 再次读取,node/ref id 必须相同。
|
||||
- 仅前插空行/叙述时,已有命名符号保持 symbol id;步骤 id 由结构身份映射,不能只靠行号。
|
||||
- 同一行多个节点需要 column/offset/span 区分,不能都映射成 `stmt-N`。
|
||||
- 匿名步骤重排/重复同名内容可能无法唯一映射;返回 unmapped/ambiguous,不能声称任意编辑下永恒稳定。
|
||||
- source span 明确 1-based line/column 和 UTF-8 byte offset;JavaScript UTF-16 偏移不直接当 Rust 字节偏移。
|
||||
|
||||
旧 `#stmt-{line}` 可保留为当前版本兼容锚点,但不得作为跨版本唯一身份。
|
||||
|
||||
### 6.4 嵌入渲染、主题与访问性
|
||||
|
||||
fragment 不包含 html/body、应用导航、运行按钮、内联可执行 script、全局 CSS;CSS 以 `.mq-document` namespace 限定。主题暴露 `--mq-bg/surface/text/muted/border/accent/font-body/font-code`,宿主映射自己的设计 tokens;不把独立 View 的全局 `*`/body 样式注入 qdagent。
|
||||
|
||||
首批推荐 fragment + 结构化引用 + 宿主事件代理;无需为 iframe 和 React 各重做 parser。可选 iframe embedded shell 必须只读、无重复导航,宿主/子页通信校验 origin/source/nonce/schema,仅允许 open-reference/selection/ready 等已定义消息,不能从内容发任意运行指令。
|
||||
|
||||
所有文本/属性转义,允许的 Markdown HTML 白名单净化;链接 scheme 限制;外部资源不默认跨网加载;代码/公式不得执行。静态导出、独立页面、嵌入三者都测试恶意文本/闭合标签/危险 URL。不要把 KnowledgePresentation 内 JSON 的转义当作所有正文 XSS 防护。
|
||||
|
||||
标题/列表/表格用语义 HTML;说明链接有可访问名称,焦点可见,视觉排序和键盘顺序一致。折叠只隐藏技术细节,不隐藏理解结论所需的正文。320–720px 容器宽、暗色、200% 缩放和 print 都要能读,不出现遮住正文的关系连线。无 JS 时仍能读正文和普通链接。
|
||||
|
||||
## 7. M04:知识、来源与历史引用定位
|
||||
|
||||
### 7.1 KnowledgeLocatorV1
|
||||
|
||||
统一 locator:`project_id,document_id,source_revision,generation_id?,artifact_id?,node_id?,source_ref_id?,span?,relation`。relation 区分 cites/supports/derived_from/executes。普通链接导航、NarrativeRef 和 BoundCall 都能定位,但语义不同;点击说明永不成为 BoundCall 的执行。
|
||||
|
||||
新增 `view.reference_resolve`:接受 locator 或当前文档 ref_id,返回 `resolution = resolved|stale|unresolved|ambiguous|version_unavailable|unsupported`、目标 locator、候选(若有)、定位精度、诊断、读者标签。框架内部路径不作为浏览器 href,应用根据授权映射为 document/source route。
|
||||
|
||||
扩展 `artifact.inspect` 的版本参数,旧无版本调用仍查当前;新调用带 expected source/generation mismatch 时不能自动降到当前。来源读取接口可由宿主取实际文件,再调用框架 locator 映射;框架不自动 fetch 外部网页。`mq://` 必须按框架规则解析,不能交给浏览器或把 URI 直接当文件路径。
|
||||
|
||||
### 7.2 历史版本与保留责任
|
||||
|
||||
生成 artifact/generation 元数据不等于保存了原文历史。框架须输出可保存的 snapshot manifest:原文 revision、依赖 revision、source refs、artifact hashes、renderer/schema version;应用决定哪些源版本随引用保留及保留周期。已有 Git 或内容寻址存储可提供 snapshot resolver;不强制应用部署 Git。
|
||||
|
||||
source revision 定位到存储快照后,框架基于该快照解析;缺失任何必要版本时返回 version_unavailable/partial,不读取最新文件填充旧快照。如果只留 artifact 元数据、原始资料已删除,仍可展示历史元数据但明确“原文不可读取”。
|
||||
|
||||
知识改名、移动或 source anchor 改变可返回候选映射,只有唯一可靠匹配才自动导航;否则用户选择最新版/候选。保持旧引用与新引用两个对象,防止历史回答证据在后台悄悄改变。
|
||||
|
||||
### 7.3 验证和运行事实
|
||||
|
||||
节点详情至少携带 purpose/description、signature、applicability、provenance、effects、dependencies,以及 parse/resolve/contract/tests/evidence/execution 各自状态与记录来源。sourced 只能说“已关联来源”;static verify 成功不表示执行成功或适用业务正确。
|
||||
|
||||
真实执行证据独立结构 `run_id,artifact_digest,closure_digest,source_revision,generation_id,inputs_digest,executed_at,result_state,evidence_ref`,展示时匹配版本。旧运行结果不涂成当前文档的绿色通过。知识复用必须存在实际 bind/execute trace,不能凭 find 命中显示“已执行”。
|
||||
|
||||
View 不运行验证测试以填满状态。若用户点“验证”,应用走已有 verify/policy 门禁并记录新 evidence,之后读取才刷新详情。
|
||||
|
||||
### 7.4 错误与授权协作
|
||||
|
||||
| 内部结果 | 应用建议呈现 | 不能做 |
|
||||
|---|---|---|
|
||||
| unresolved | 无法定位该知识,可读原引用 | 跳转到第一个同名 artifact |
|
||||
| ambiguous | 显示已授权候选和位置 | 自动选择或暴露不可见候选 |
|
||||
| stale | 该知识/来源已变化,提供版本选择 | 静默替换旧引用 |
|
||||
| version_unavailable | 回答所用版本不可用,可查看最新版 | 用最新版伪装历史证据 |
|
||||
| partial | 部分依赖或来源缺失,说明范围 | 默认绿色通过 |
|
||||
| permission denied(应用) | 无权访问 | 在错误中泄漏标题、路径、片段 |
|
||||
|
||||
用户权限归应用;框架服务在调用边界接受 scoped project/source resolver,不把传来一个 root 视为可遍历整个服务器。所有路径经过 canonicalize/symlink 检查;缓存的语义事实可共享,带原文的响应必须按权限复核,不能只靠 artifact id 缓存授权。
|
||||
|
||||
## 8. M05:工作区、笔记与导入所需的通用底座
|
||||
|
||||
不为 qdagent 画像加语言特殊节点。通用能力应支持普通文档元信息读取、来源范围、内容修订、diff/patch 的 expected digest、提取格式 capability。
|
||||
|
||||
document.extract 继续使用 DocumentSource→ExtractedDocument,报告 format/status/segments/source locator/diagnostics。TXT/MD 可支持;PDF/DOCX/OCR 没有适配器时明确 unsupported/failed,不能将空文本当成功。partial 保留已提取片段及原文范围、遗漏原因;发布政策由应用决定。
|
||||
|
||||
同一资料可产生多个知识单元,provenance 必须到具体片段,不能所有函数只指向文件根。原始资料 digest 改动的失效由现有 provenance/closure 保证;应用用户画像也可用普通来源引用,但不自动进入公共知识发布。
|
||||
|
||||
ProjectRoot/CompileOptions 显式传递,工作区 A/B 的 source id、输出 generation、缓存、临时目录必须隔离。避免每读一个节点就全项目编译:引入按 project snapshot 复用的分析服务,针对来源/依赖变化失效;并发同 snapshot 请求合并,不能分别写同一个 CURRENT。
|
||||
|
||||
上传 multipart/大小限制已有 web 底座,框架只提供安全提取和可消费结果;浏览器上传、作业生命周期、发布确认、权限和历史保存仍在 qdagent。多文件任务桥接采用结构化参数,禁止拼接用户文件名进 shell/JSON 或共用固定请求临时文件。
|
||||
|
||||
## 9. 实现落点与兼容策略
|
||||
|
||||
| 模块 | 改动方向 | 兼容要求 |
|
||||
|---|---|---|
|
||||
| `plugins/llm/src/lib.rs` | adapter boundary、消息数组、usage、event sink、取消 | 保留已有符号;新能力有 probe 和合同版本 |
|
||||
| `ext/ai/llm.mq.md` 与 `ext/ai/llm/*` | strict selection、结构化 result、public snapshot | 无 selection 的旧调用仍可运行;不得回显密钥 |
|
||||
| `ext/ai/agent.mq.md` | run context、子工作簿传播、逐调用观测 | 不复制 Agent loop,EFI/verify/publish_gate 不被绕过 |
|
||||
| `plugins/agent/src/*` | 子任务/恢复上下文、cancel、event identity | resume 不重发已结算请求;不可恢复说明 interrupted |
|
||||
| `src/host/*`、插件 SDK、web invoke | 请求局部 event/cancel 桥接 | ABI 旧宿主不伪支持;并发请求不混流 |
|
||||
| `src/view/knowledge_present.rs` | DocumentView read model/兼容 adapter | 旧 presentation v1 不被新字段语义污染 |
|
||||
| `src/view/document.rs,render.rs,html.rs,mod.rs,output.rs` | 共享纯读取、fragment、scope CSS、定位 | live/debug 与 read 明确分离;旧 no-exec 门禁保留 |
|
||||
| `src/mlsp.rs` | capabilities、view/document/reference、版本 inspect | 使用现有 envelope;未知 feature 可探测 |
|
||||
| `src/sema/ir.rs,provenance.rs` | span、snapshot/locator、依赖与来源失效 | 不改变核心语法,不把读请求变为执行 |
|
||||
| `src/document_extract.rs` | capability 和片段定位完整性 | 保留不支持格式的显式失败 |
|
||||
|
||||
测试分层对应 plugin HTTP fixtures、Agent 假模型、MLSP read contracts、web 持续流集成、独立/嵌入 DOM 和浏览器交互。应用共享样本文件必须注明 schema 版本;两仓 PR 在各自文档索引相互链接对应实现说明。
|
||||
|
||||
迁移顺序为新增合同/接口 → 旧输出 adapter → qdagent 按 capability 接入 → 切默认 → 后续版本再考虑弃用。不要同时移除 legacy 行为且要求应用一次完成全链升级。发布包对 CLI/ext/native 插件做组合测试,缺插件给功能不可用诊断而非 unknown function 直到用户点击才暴露。
|
||||
|
||||
## 10. 交付切片与验收门槛
|
||||
|
||||
| 切片 | 前置 | 验收输出 | 支撑应用任务 |
|
||||
|---|---|---|---|
|
||||
| M00 合同冻结/探测 | 无 | schemas、fixtures、capabilities、版本和插件清单 | Q00、所有升级探测 |
|
||||
| M01 多模型隔离 | M00 | 兼容适配器、strict handles、history、子任务选择一致 | Q01/Q02 |
|
||||
| M02 调用观测与流 | M01 | 每 attempt usage、真流式、取消、错误/重放一致 | Q03/Q06 |
|
||||
| M03 只读嵌入 View | M00,可与模型线独立 | DocumentViewV1、fragment、目录/节点、无执行证明 | Q04 |
|
||||
| M04 引用与快照 | M03 | 历史 locator、来源详情、版本失效/歧义 | Q05 |
|
||||
| M05 文档工作区底座 | M03/M04 + 已有 extract | 范围隔离、提取定位、并发与缓存 | Q07/Q08 |
|
||||
| M06 集成与性能 | 全部所选切片 | 旧门禁 + 新 contracts + 浏览器与负载报告 | Q09 |
|
||||
|
||||
M01 支持多个兼容提供商不等待原生协议全做完;但原生适配器需另列完成状态。M03 不等待计费系统。M04 未完成历史快照前,应用可以显示当前文档,但必须把历史引用标“版本不可用”,不能宣布引用链闭合。
|
||||
|
||||
每个切片的 Definition of Done:实际接口可调用、失败合同覆盖、无副作用/隔离测试、文档示例由测试消费、版本能力可探测、qdagent integration fixture 通过。只有可运行的验收证据才可将 proposed 改为 verified。
|
||||
|
||||
## 11. 框架测试矩阵
|
||||
|
||||
| 编号 | 用例 | 断言 |
|
||||
|---|---|---|
|
||||
| F01 | 两端点各两模型、并行 A/B、无密钥本地端点 | 请求 payload/端点/鉴权正确,环境不串扰 |
|
||||
| F02 | step/plan/router/repair/child/resume | strict selection 和 parent identity 完整,不退回默认模型 |
|
||||
| F03 | multi-turn、system/tool roles、超限/不支持模态 | 顺序和边界完整,不吞最新 user,不静默降级 |
|
||||
| F04 | 非流/流式/usage-only/缺 usage/错误后部分 usage | null 与 0 区分,终态和用量独立 |
|
||||
| F05 | 相同累计 usage 多次、重放、新重试 | 同 attempt revision 覆盖,不重复相加;真重试新增 attempt |
|
||||
| F06 | 慢供应商、慢消费者、断连、取消、超时 | 完成前有 delta;队列有界;取消不启动后续工具/模型 |
|
||||
| F07 | 外部工具已写后取消、恢复未知状态 | 不声称撤销,不自动重做可能有副作用的动作 |
|
||||
| F08 | 带写文件/网络/foreign/插件的文档被阅读 | read API 不加载/运行这些效果,无项目写回 |
|
||||
| F09 | prose/heading/6 类步骤、同一行多引用、中文 span | HTML/outline/节点/ref 同源,定位唯一准确 |
|
||||
| F10 | 仅说明变化、依赖变化、旧 SSE 包、无 token | token 正确失效,嵌入 strict 拒绝过期/无身份包 |
|
||||
| F11 | 来源改删、历史 generation 未留原文、同名歧义 | 明确 stale/unavailable/ambiguous,无猜测替代 |
|
||||
| F12 | no-js/390px/暗色/长表格/键盘 | 正文可读,可返回,有清晰标题和焦点 |
|
||||
| F13 | 原始 HTML/危险 URL/闭合 script/越界路径 | 无脚本执行/越权读取/泄漏;不靠应用猜净化 |
|
||||
| F14 | 两项目同相对路径/并发 100 读取 | scope 缓存隔离,同 snapshot 合并分析 |
|
||||
| F15 | 编译成功但验证/证据未知、旧执行记录 | 各状态独立;不把 static/sourced 标 verified |
|
||||
| F16 | CLI/ext/native 版本错配 | capability 早发现不可用,而非运行时静默失败 |
|
||||
|
||||
性能目标需实测而非发版文字:固定机器与 release/debug 分开记录,1000 单元分析冷/热、单文档 fragment 体积/时间、并发读取 P95/内存、UI 首屏。应用目标见 Q 文档;如果全量 compile 超时,优先分析重复全库扫描、依赖计算与缓存,不通过删除 fixture 或抬高阈值宣布可用。
|
||||
|
||||
## 12. 本次验证结果与已知阻碍
|
||||
|
||||
### 12.1 M00–M06 落地证据(2026-10-25 续)
|
||||
|
||||
命令(本机):
|
||||
|
||||
```bash
|
||||
cargo test --offline --locked --test workbench_contracts
|
||||
cargo test --offline --locked -p marqdo_plugin_llm
|
||||
cargo test --offline --locked --test executable_knowledge f1_agent_eng_bind_gate_mq_offline -- --exact
|
||||
```
|
||||
|
||||
已交付并通过自动化子集(**非** F01–F16 全绿):
|
||||
|
||||
| 切片 | 证据 |
|
||||
|---|---|
|
||||
| M00 | fixtures + JSON Schema 消费;`capabilities`;`force_unloaded` / `force_*_off`(F16) |
|
||||
| M01 | strict selection;`RunContextV1` 并行不串扰;llm plugin messages/roles;workbook 禁 `llm.llm`;**F02** `m01_f02_agent_step_selection_and_resume`(mock HTTP + `llm.create` 抗 env poison + resume save/load) |
|
||||
| M02 | usage null≠0;revision 替换(F05);cancel token(F06/F07);event_sink;web `sse-live` 断连 cancel |
|
||||
| M03 | `view.document`;CJK outline/nodes;path escape;静态 a11y 子集;F08 无副作用标记;**浏览器** `workbench-docview.html`(`article.mq-document`、0 script、无 `javascript:`) |
|
||||
| M04 | stale / version_unavailable / **ambiguous**;`SnapshotManifestV1` 输出(retention=application);`artifact.version_mismatch`;embed strict SSE |
|
||||
| M05 | extract `:B`;analysis_cache begin/finish;**F14 并发 100** 同 snapshot + 跨 project 隔离 |
|
||||
| M06 | CI 预构建 agent+llm + `workbench_contracts`;Go `drainForward` / cancel-token 桥 |
|
||||
| Live | `tests/workbench_live.rs`:USTC OpenAI-compatible(`OPENAI_*` env only)`qwen3.8-chat` / `deepseek-flash` selection ask → `pong` + usage;`MARQDO_EXT` 指向仓内 `ext/` 避免 `~/.marqdo/ext` 陈旧遮蔽 |
|
||||
|
||||
已知限制(发版前须书面接受或继续补):
|
||||
|
||||
- F02 repair/plan **全路径**假模型仍薄于 step+resume;RunContext 三级继承 + skeleton 禁 `llm.llm` + 子任务 env 已有。
|
||||
- 历史正文由应用按 SnapshotManifest 保留;框架缺快照 → `version_unavailable`(不静默降级)。
|
||||
- 完整宿主嵌入 F12 / 产品鉴权留给 qdagent;原生适配器 / PDF/OCR 仍 unavailable。
|
||||
|
||||
### 12.2 历史基线记录(设计起草时)
|
||||
|
||||
起草时 `executable_knowledge` 曾出现 `f1` 缺插件与 `v3_corpus_1000` debug 超时;其后 `ensure_agent_plugin_built` + CI 预构建已修复 f1 路径。1000 单元性能仍按剖面单独记录。
|
||||
@@ -0,0 +1,130 @@
|
||||
# 标准库:代码、文档、SKILL 与 tools 同源
|
||||
|
||||
标准库通常是单文件:直接阅读并调用 [fs.mq.md](../../lib/fs.mq.md)、[文件.mq.md](../../lib/文件.mq.md)、[table.mq.md](../../lib/table.mq.md) 或其他任务所需源码。
|
||||
31 个模块族对应 61 份公开标准库单文件;源码本身承担手册与 SKILL,不设强制总入口或模块 index。
|
||||
多文件拓展库的 index 用于组织多文件,标准库沿用其可读性和调用规范。
|
||||
|
||||
## 源码就是手册
|
||||
|
||||
每个函数标题下立即放参数表(名称、类型、默认、含义),随后是返回契约、效应、叙述形参、
|
||||
用途和边界、实际调用例子及短实现。无参数函数直接放返回表。旧 `+` 形参已移除。
|
||||
契约表位于首条执行语句之前;默认值和参数顺序保持兼容。
|
||||
|
||||
叙述比例逐函数超过 50%;既检查比例,也检查真实契约、调用和错误语义。
|
||||
不透明宿主指令使用遮蔽调用,例如 `` *[读取 UTF-8 文本](> host_read_text path=`path`)* ``:
|
||||
方括号说明目的,圆括号执行真实代码;赋值语句同样采用描述标签。
|
||||
标签不替代参数与权限,也不能用空标签或重复模板代替说明。调用与返回自然写入正文;
|
||||
行内表达式仍计作代码,绑定数据表不冒充叙述。125 份库源码的统一验收见
|
||||
[本轮记录](../roadmap/library-authoring-refactor.md),公共标准库当前为 650 个函数。
|
||||
键值行记录可用 table.from_pairs / 表.键值转记录生成具名记录,保留空值和重复键更新语义。
|
||||
|
||||
## 接口事实来自编译器
|
||||
|
||||
现有 call、catalog、MLSP 与编译器读取同一份标准库源码,不额外包装一层目录函数或示例函数。
|
||||
`examples/stdlib_catalog.rs` 使用实际装载、签名和效应结果检查源码中的效应说明;
|
||||
--json 输出接口事实,--write 仅刷新效应说明,不生成第二套手册。
|
||||
人工维护用途、参数含义、失败处理和工程实践。不透明值保留渐进式 any,并说明来源和限制。
|
||||
|
||||
```sh
|
||||
cargo run --example stdlib_catalog -- --json
|
||||
cargo run --example stdlib_catalog -- --check
|
||||
marqdo check lib/文件.mq.md --narrative-ratio
|
||||
cargo test --test stdlib_tasks
|
||||
```
|
||||
|
||||
测试直接读取 61 份公开源码中的实际命令,在 Tree 与 Bytecode 执行 126 次。
|
||||
验证每个函数的参数/返回契约、标题下表格、无旧形参声明以及逐函数叙述比例。
|
||||
|
||||
## 能力与兼容性
|
||||
|
||||
| 任务 | 新的公共入口 | 关键契约 |
|
||||
|---|---|---|
|
||||
| 文件整理 | fs.find/read_lines/write_lines/read_json/write_json/read_csv/write_csv | 明确根目录、格式和资源上限 |
|
||||
| 文件修改 | atomic_write/write_changed/write_checked | 单文件原子替换;摘要检查不是内核 CAS,竞争写入仍需协调 |
|
||||
| 批量文件 | copy_tree/sync_tree/rename_many | 先预检冲突,覆盖需选择;不承诺多文件事务;目录复制面向普通文件,不复制权限、链接与空目录 |
|
||||
| 临时文件 | make_temp/temp_dir | 在授权根目录创建,由调用方明确清理;真实工程演示清理 |
|
||||
| 二进制 | bytes 与 fs.read_bytes/write_bytes/read_chunk/append_bytes/file_hash | 普通 bytes 记录,Base64 跨 CLI/JSON/插件传递,字节偏移从零起 |
|
||||
| 集合 | range/enumerate/pluck/project/where/find/any/all | 不增加回调字符串求值或新的查询方言 |
|
||||
| 表数据 | group_by/aggregate/summarize/join/rename/unique_by/sort_keys | 行记录、分组键和字段含义明确;批量汇总避免作者循环反复复制列表 |
|
||||
| 数据形态 | from_columns/to_columns/cast/try_cast/validate | 不猜测列式表与普通对象;列长、字段及类型错误有明确结果 |
|
||||
| 集合运算 | union/intersection/difference | 返回保序列表,沿用运行时值相等规则 |
|
||||
| 网络 | net.get/request/download/header_values | 超时、响应上限、重复响应头、字节响应;失败下载保留原文件 |
|
||||
| 配置与日期 | toml.parse/stringify、datetime.parse_local/add_calendar | 标准 TOML;内嵌 IANA 规则;夏令时缺口和重叠明确失败或选择 |
|
||||
| 子任务 | wait_timeout/cancel_all/run_many | 文件任务并发上限、超时终止回收、父权限与根目录继承 |
|
||||
| 文档维护 | document.sections/section/tables/links/code_blocks/replace_section/replace_table | 与渲染共用 Markdown 解析器,不执行文档,保留周围源码 |
|
||||
| 归档 | archive.pack/unpack | 可选 ZIP,预检路径、链接、重复项和展开上限,目标必须不存在 |
|
||||
|
||||
旧 remove 保持递归删除行为,公开文档已纠正;新代码用 remove_file/remove_empty_dir。
|
||||
access 与 put 的整数路径从一开始;旧 at/slice/insert/remove_at 等接口从零开始,不能混用。
|
||||
更新返回新集合,原值保留;单次追加仍有复制成本。规模任务使用批量变换,去重使用分桶并保留原相等语义。
|
||||
混合排序采用明确类型顺序,修复数字与文本混排造成非传递比较的问题。
|
||||
大下标在 32/64 位目标上保持一致:取元越界为空,更新越界为诊断,巨大分块大小不会截断成零或导致死循环。
|
||||
|
||||
## 权限与错误
|
||||
|
||||
宿主身份声明效应,编译器沿解析后的依赖传播,不依据 fs、net 等导入别名猜测。
|
||||
函数、BoundCall 和步骤共享最终效应,外部标准库和中英文别名也使用同一逻辑。
|
||||
|
||||
```sh
|
||||
marqdo call lib/fs.mq.md read_text 'path="notes.md"' --effects fs.read --fs-root /absolute/project --json
|
||||
marqdo call lib/fs.mq.md atomic_write 'path="notes.md"' 'text="updated"' --effects fs.write --fs-root /absolute/project --json
|
||||
```
|
||||
|
||||
默认 none 只准纯函数;fs.write 包含读取授权,其余能力仍需明确选择。
|
||||
plugin 保留加载提示所需的既有能力,不增加文件写入、网络或进程执行授权。
|
||||
根目录检查覆盖新文件的最近已存在父路径与符号链接越界。
|
||||
会话保存规范化根目录与可持久化结果;重建会话不重复文件、网络或进程写操作。
|
||||
不可重放写操作缺少快照时明确拒绝,不能为了重建句柄偷偷重做。
|
||||
|
||||
可恢复操作统一返回 `{ok,value,error}`,错误含 code/message/operation,校验错误可附 details。
|
||||
代码来自明确错误标签与 IO 错误种类,不扫描任意路径文本猜类别。Result 不授权操作,也不捕获任意语言错误。
|
||||
CLI 外层 ok 表示调用成功;函数值的 Result.ok 表示操作协议成功;HTTP status、子进程 code 仍需按领域判断。
|
||||
语法、契约与不可恢复运行错误继续使用原有结构化 Diagnostic,保留库来源和调用点。
|
||||
|
||||
## 平台与资源边界
|
||||
|
||||
| 能力 | 原生 | WebAssembly 浏览器目标 | CoW 试运行 |
|
||||
|---|---|---|---|
|
||||
| 集合、文本、JSON/CSV/TOML、字节数据、文档结构、静态时区计算 | 支持 | 纯计算可构建;具体浏览器熵/时钟依赖桥接 | 支持 |
|
||||
| 原生文件与分块 IO | 支持 | 未接入浏览器文件系统时明确不可用 | 文件内容经覆盖层;已有目录枚举/元数据为宿主快照,试运行变更用 sandbox.diff/inspect |
|
||||
| 文件复制、移动、追加与文本补丁 | 支持 | 无原生 FS | 经覆盖层;复制最多 64 MiB,不绕过试运行写入真实文件 |
|
||||
| 目录状态、目录树批处理、归档、流式下载 | 支持 | 原生专属能力不可用 | 未建模的目录/原生任务明确拒绝 |
|
||||
| HTTP、进程、动态插件 | 按构建特性支持 | 原生接口不可用;浏览器使用 browser 效果与桥接 | 依 profile/caps,不以库包装绕过 |
|
||||
| 子任务取消 | 进程可终止并回收 | 不提供原生子进程 | 函数线程仅逻辑取消;有界批处理只接收文件任务 |
|
||||
|
||||
新增有界读取默认 8 MiB、上限 64 MiB;旧 read_text 及其格式组合接口保留整文件读取语义,大文件使用 read_chunk/file_hash;原生文件摘要和下载使用 64 KiB 缓冲区。
|
||||
查找最多十万条目;序列和连接最多一百万结果;文件批处理最多一万任务、六十四并发。
|
||||
HTTP 时限与字节上限由调用方明确设置;不自动重试可能修改远端状态的请求。
|
||||
TOML 日期转换为 ISO 文本;写出不保留注释,None 和非有限数没有支持的表示。
|
||||
IANA 数据随锁定依赖交付,不声称总是最新政策数据。ZIP 不提供完整备份语义。
|
||||
|
||||
## 真实工程与验收
|
||||
|
||||
[标准库工程](../../examples/stdlib-handbook/index.mq.md)和[中文入口](../../examples/stdlib-handbook/索引.mq.md)同时完成:
|
||||
|
||||
1. 扫描 Markdown,保留逐文件读取结果;坏 UTF-8 不阻止其他记录。
|
||||
2. 读取 CSV,转换字段,筛选并批量分组汇总,输出 CSV。
|
||||
3. 精确替换章节,以读取文本的摘要检查来源,保留其他叙述并原子写入。
|
||||
|
||||
`tests/stdlib_tasks.rs` 验证公开文档和双后端,而非只测私有宿主调用。
|
||||
附加测试覆盖 CoW 不落盘、写入快照不重放、超时后继续等待、网络参数预检、重复响应头、
|
||||
失败下载保留目标、ZIP 越界与链接、夏令时、TOML、混合排序和十万项去重。
|
||||
旧诊断测试从编译器 AST 定位库指令,继续严格检查独立调用点;不再因添加文档而依赖固定行号。
|
||||
|
||||
## 构建验证
|
||||
|
||||
原生默认特性、精简 wasm-core 特性、真实 wasm32 交叉编译均已验证。
|
||||
浏览器 ABI 与 `tests/wasm/stdlib.mjs` 在当前 wasm 产物上由 Node 执行,覆盖集合、字节、
|
||||
文档、TOML、IANA/DST、32 位大下标与嵌套路径诊断。Node 验收不是浏览器 DOM 布局验收。
|
||||
|
||||
发行版 rustc 与官方 wasm 标准库的构建元数据不能混用;本次使用同版本匹配的官方组件,
|
||||
校验后在临时目录构建并执行,不依赖修改系统工具链。复现时使用已安装对应 wasm32 标准库的工具链:
|
||||
|
||||
```sh
|
||||
cargo check --no-default-features --features wasm-core
|
||||
cargo build -p marqdo-wasm --target wasm32-unknown-unknown
|
||||
node tests/wasm/smoke.mjs target/wasm32-unknown-unknown/debug/marqdo_wasm.wasm
|
||||
node tests/wasm/stdlib.mjs target/wasm32-unknown-unknown/debug/marqdo_wasm.wasm
|
||||
```
|
||||
单文件结构修正后,全量 970 项测试通过,0 失败,2 个原有忽略项;其中包括 17 项标准库工程测试。
|
||||
完整命令、分轮计数和交叉目标结果见[实施验收记录](../roadmap/stdlib-executable-handbook.md)。
|
||||
@@ -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
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 标准库 L1 模块
|
||||
|
||||
直接阅读并导入标准库单文件,例如 [文件](../../lib/文件.mq.md)和[表](../../lib/表.mq.md)。每个文件自身就是手册,函数标题下给出参数表、返回契约和动作说明;不要求额外 index。模块分层与历史波次见下表,当前规范见[标准库说明](stdlib-handbook.md)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **核心已落地**;**Mid M1–M6 已落地**;**Mid2 规划中** · [stdlib-mid2.md](stdlib-mid2.md) / [roadmap/stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
|
||||
|
||||
@@ -17,7 +17,8 @@
|
||||
|
||||
```markdown
|
||||
---
|
||||
import table:lib/table.mq.md
|
||||
import:
|
||||
table: lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -51,8 +51,9 @@ Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import:
|
||||
text: lib/text.mq.md
|
||||
table: lib/table.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
# \(V_{\mathsf{safe}}\) JSON integer contract (host ↔ Lean)
|
||||
|
||||
Canonical Lean model: `MarqdoThesis/PLDI/proofs/MarqdoProof/MarqdoProof/ForeignJSON.lean`.
|
||||
Host mapper: `src/host/json.rs` (`json_to_value` / `value_to_json`).
|
||||
|
||||
This document freezes **runtime conformance** of the Marqdo JSON bridge to the
|
||||
mechanized \(V_{\mathsf{safe}}\) integer domain. It is **not** a verified
|
||||
compilation of the Rust interpreter.
|
||||
|
||||
## Domain
|
||||
|
||||
```
|
||||
MAX_SAFE = 9007199254740991 # 2^53 - 1
|
||||
```
|
||||
|
||||
\(V_{\mathsf{safe}}\) values (mechanized):
|
||||
|
||||
| JSON | Marqdo |
|
||||
|---|---|
|
||||
| `null` | `None` |
|
||||
| `bool` | `Bool` |
|
||||
| integer with `\|n\| ≤ MAX_SAFE` | `Int` |
|
||||
| `string` | `Text` |
|
||||
| `array` | `List` |
|
||||
| `object` | `Map` |
|
||||
|
||||
**Host extension (not in Lean `SafeVal`):** JSON non-integer numbers → `Value::Num(f64)`. Non-finite numbers (NaN/Inf) are refused on encode and in Python/Node oracle responses, including nested payloads. Floats are documented host behavior; they are **not** claimed as mechanized \(V_{\mathsf{safe}}\) fidelity.
|
||||
|
||||
## Encode (`value_to_json`)
|
||||
|
||||
- `Value::Int(n)` with `|n| ≤ MAX_SAFE` → JSON number.
|
||||
- `Value::Int(n)` with `|n| > MAX_SAFE` → **refuse** (error).
|
||||
- `Value::Handle(_)` → **refuse** (`json: session handle cannot be serialized`).
|
||||
- Column-table `Map` whose fields are all `List` with **unequal lengths** →
|
||||
**refuse** (`json: table column arity mismatch`).
|
||||
- Nested `List` / `Map`: any child refuse fails the whole tree.
|
||||
- GFM table **parse** also refuses unequal row width
|
||||
(`table row arity mismatch`) before a value is built.
|
||||
- Wide integers that must cross a language boundary: author converts to a
|
||||
**decimal string** (∈ \(V_{\mathsf{safe}}\)); the foreign program may use
|
||||
`BigInt` / Python `int` on that string.
|
||||
|
||||
## Foreign oracle (`session_eval` / `session_get`)
|
||||
|
||||
Python/Node session bootstraps sanitize results with the same integer gate
|
||||
before JSON emission. An Ω response containing an OOD integer is a **fault**
|
||||
(host `Err`), not a soft `ok:false` cell record. Stdout text that authors
|
||||
`json.parse` themselves is still gated by host `json_to_value`.
|
||||
|
||||
## Decode (`json_to_value`)
|
||||
|
||||
- JSON integer with `|n| ≤ MAX_SAFE` → `Int`.
|
||||
- JSON integer with `|n| > MAX_SAFE` → **refuse**.
|
||||
- JSON unsigned integer `> i64::MAX` → **refuse** (do **not** coerce via `f64` or `Text`).
|
||||
- Nested array/object: any child refuse fails the whole tree.
|
||||
- Decimal-string encodings of wide integers → `Text` (in domain).
|
||||
|
||||
## Error prefix
|
||||
|
||||
All refuse messages use a fixed prefix for probes and diagnostics:
|
||||
|
||||
```
|
||||
json: integer outside V_safe (±(2^53-1)): <n>
|
||||
```
|
||||
|
||||
## In-domain roundtrip
|
||||
|
||||
`±MAX_SAFE`, bool, null, string, array, and object roundtrips through
|
||||
`encode → decode` must succeed. Integers `MAX_SAFE+1`, `-MAX_SAFE-1`, `2^53`,
|
||||
`2^60`, `2^60+1` (and nested forms) must refuse.
|
||||
|
||||
## Non-claims
|
||||
|
||||
- Not verified Rust ↔ Lean compilation.
|
||||
- Not arbitrary host-object fidelity (DataFrame, functions, heap sharing).
|
||||
- Not automatic BigInt promotion inside Node/Python bootstraps.
|
||||
- Document-level `Value::Int` may still hold i64 values that are OOD for JSON;
|
||||
the gate fires when those values enter JSON encode/decode.
|
||||
|
||||
## Strict request boundary update
|
||||
|
||||
The numeric gate applies to the represented value, including integer-valued
|
||||
floats and exponent notation. `9007199254740992.0` and
|
||||
`9.007199254740992e15` are refused; fractions such as `1.5` remain in the host
|
||||
extension. `serde_json` uses `float_roundtrip` to avoid endpoint decoding loss.
|
||||
The strict text decoder rejects duplicate object keys and unequal column maps
|
||||
before information is lost. One-shot, call_many and persistent input paths
|
||||
use recursive domain admission; code, handle and secret values are not copied
|
||||
implicitly. Auto-detection may leave non-JSON output as text, but valid JSON
|
||||
outside the domain is a refusal, including in batch results.
|
||||
@@ -0,0 +1,463 @@
|
||||
# View 可执行知识阅读体验重设计
|
||||
|
||||
| 项目 | 说明 |
|
||||
|---|---|
|
||||
| 日期 | 2026-10-24 |
|
||||
| 状态 | 详细设计建议,待实施;不是已交付能力声明 |
|
||||
| 审计基线 | `b8a4ddd` / Marqdo 2.1.1;使用当前源码构建的 debug CLI 复核 |
|
||||
| 输入 | 用户提供的 view 截图:Executable Knowledge 在 Structure 前,Steps、Target、Kind、Signature、Effects、Verification、Lock digest 等字段大量铺开 |
|
||||
| 范围 | Live view、静态导出、正文结构、知识说明、运行结果、来源与状态呈现;不改语言语义,不增加作者必填的展示 DSL |
|
||||
| 关联 | [文档原生开发指导](document-native-development-guide.md)、[View 总体设计](view.md)、[文档面与标注](view-document-annotations.md)、[求道相关框架缺口](../roadmap/qdagent-knowledge-support-gaps-2026-10-24.md) |
|
||||
|
||||
## 1. 设计决策
|
||||
|
||||
**View 首先呈现知识文档本身,结构帮助读者理解和定位,机器信息解释当前所读内容。** 正文、程序结构、知识关系与执行证据应由同一份源文档关联起来,而不是顺序展示几份互相脱节的报告。
|
||||
|
||||
确定以下方向:
|
||||
|
||||
1. 移除正文之前整块展开的 Executable Knowledge。主阅读流首先出现作者的标题、介绍和内容;不把完整机器报告简单搬到正文后继续平铺。
|
||||
2. 保留并改进现有 Structure 的叙述保真文档面,面向读者命名为“文档”。正文、表格、公式、函数和可执行步骤在原位置阅读,不生成一份模型改写的平行说明书。
|
||||
3. 右侧“本文结构”负责章节与知识单元定位;选中知识片段后,在同一辅助栏展示它的解释、输入输出、来源和验证依据。源码标识、摘要与完整协议放在可展开的技术详情中。
|
||||
4. 运行结果就地关联到对应步骤,明确运行实例与输入;完整日志、运行控制和源码放在正文后。看见一个数值时,读者必须能知道它是文档声明、计算结果还是历史快照。
|
||||
5. 静态分析、程序运行、测试断言、来源关联和领域确认分别表达。不能用一个 `ok`、`pure` 或绿色“已验证”覆盖不同事实。
|
||||
6. 功能渐进增强:无 JavaScript、静态导出、移动端、打印时仍能读完文档、定位知识和查看必要依据。普通短文不变成复杂仪表盘。
|
||||
|
||||
这些决策恢复 [view.md](view.md) 原有“文档面为主、Browse 与 Debug 分工”的方向,同时修订过度依赖引出线和默认展开技术面板的呈现方式。
|
||||
|
||||
## 2. 现状审计:为什么截图难读
|
||||
|
||||
### 2.1 可定位的实现依据
|
||||
|
||||
| 观察 | 当前代码 | 对阅读的影响 |
|
||||
|---|---|---|
|
||||
| 知识面板位于正文前 | [html.rs / page_file](../../src/view/html.rs) 的模板顺序为 notebook → knowledge → Structure → Execution → Source | 必须先越过辅助资料才能看到文档;模块越多越严重 |
|
||||
| 所有制品一律展开 | [render.rs / render_knowledge_html](../../src/view/render.rs) 按文件筛选 artifacts,并逐项输出完整 `<dl>` | module/type/function 同等突出,容器元信息挤占知识内容 |
|
||||
| Steps 脱离所属结构 | 同函数把当前文件所有 steps 放在单一 `<ol>` 中,展示 kind、label、完整目标 ID | 静态步骤容易被误读为实际执行顺序;调用/循环/正文引用混在一起 |
|
||||
| 内部字段未经阅读转译 | URI、签名、effects、verification 拼接文本、完整 sha256 默认可见 | 读者仍不知道这项知识解决什么问题、怎样用、依据在哪里 |
|
||||
| “Lock digest”名实不符 | 该字段实际显示 `artifact.hashes.artifact`;[mod.rs](../../src/view/mod.rs) 编译使用 `LockMode::Off` | 制品摘要被误读为已经锁定且通过复现检查 |
|
||||
| 静态说明与运行脱节 | 每张卡固定输出 `Not executed by knowledge preview.`;实际 run capture 在另一条路径 | 即使页面有运行结果,也很难理解“未执行”到底指什么 |
|
||||
| 分析失败静默消失 | `build_file_view` 对语义编译结果使用 `unwrap_or_default` | 无知识、分析失败、尚未分析在界面上都可能表现为空 |
|
||||
| 标题与层级表达较弱 | `page_file` 标题取文件名;[document.rs / render_fun_heading](../../src/view/document.rs)统一用 h3 | 作者 frontmatter 标题未用于页标题,嵌套结构主要靠其它线索判断 |
|
||||
| 知识组件缺少专用布局 | `knowledge-*` 在 HTML 中有类名,但 `html.rs` 没有与面板匹配的专用样式规则 | 大量使用默认列表/定义列表排版,空白多、关系弱,和正文主题缺少一致约束 |
|
||||
| 新旧皮肤叠加 | `html.rs` 内基础 view CSS 与 `notebook_ui` 大块 notebook 主题共存 | 正文、注释、知识区的字号和密度不一致;不能只修一个卡片颜色 |
|
||||
| 验收主要看元素存在 | [executable_knowledge.rs](../../tests/executable_knowledge.rs) 的 view 用例检查 step 类名、kind 和 `#stmt-` 链接 | 没检查正文优先、跳转目标存在、可读文案和实际布局 |
|
||||
|
||||
已有能力应保留:[document.rs](../../src/view/document.rs) 的叙述/表格保真、Occlusion 描述与实现分离、函数大纲、调用帧/循环帧选择、[annot.rs](../../src/view/annot.rs) 的真实执行标注。重新设计应基于这些能力,而不是退回 AST 卡片浏览器。
|
||||
|
||||
### 2.2 对截图的解释边界
|
||||
|
||||
截图可直接确认:机器字段先于正文、Steps 只有 `call print`、长 URI/摘要显著占位、英文状态串缺少解释,以及深色底上的孤立黑色短线。
|
||||
|
||||
黑色短线的具体来源尚未在浏览器中复现。代码中存在 annotation leader、布局重算和主题覆盖,可能需要检查,但本文件不把它们断言为唯一根因。实施时应使用用户截图对应页面复现,检查实际 DOM、computed style 和几何位置;不能用全局隐藏所有 SVG/边框来掩盖问题。
|
||||
|
||||
### 2.3 本轮实际复核
|
||||
|
||||
把 [public/features/01-phase-i-treewalk.mq.md](../../public/features/01-phase-i-treewalk.mq.md) 复制到临时目录,使用 debug 2.1.1 执行静态导出并检查生成 HTML:knowledge 确实在 structure 前,共 3 个 `knowledge-card`(含 Steps)和 2 个完整 sha256。该短文的核心只是介绍 tree-walk 流程并打印一句话,当前辅助内容明显过重。
|
||||
|
||||
另用隔离临时文件复核 `view output --no-exec`:嵌入的 `fs.write_text` 仍创建了临时标记文件。原因是 [output.rs / write_static](../../src/view/output.rs) 先调用会执行的 `build_file_view`,再在 `opts.no_exec` 分支清空结果。**这是已复现的执行/呈现不一致,必须修复,不能仅把标签改成“未运行”。** §9 给出新的构建边界。未执行线上浏览器像素比对,本文线框为目标设计。
|
||||
|
||||
## 3. 读者任务与设计成效
|
||||
|
||||
| 读者任务 | 默认应看到 | 按需展开 | 成功判据 |
|
||||
|---|---|---|---|
|
||||
| 理解这篇文档 | 作者标题、介绍、正文和核心表格/步骤 | 完整源码 | 不滚过机器报告就能开始阅读 |
|
||||
| 看懂文档结构 | 章节、类/规则/函数的真实层级,当前位置 | 参数和局部步骤树 | 能判断一个步骤属于哪个知识单元 |
|
||||
| 理解某项知识 | 描述、简洁公式/调用、条件、返回含义 | payload、契约、精确目标 | 能解释它做什么、需要什么、产生什么 |
|
||||
| 判断结果是否可信 | 来源状态和所选运行的明确结果 | 测试、来源片段、版本和诊断 | 能区分“可以运行”和“事实成立” |
|
||||
| 跟踪跨文档复用 | 友好目标名、所属文档、输入输出 | 依赖关系、完整标识 | 能到达定义并返回原阅读位置 |
|
||||
| 检查某次运行 | 本次输入、选中调用/迭代、对应结果 | 日志、历史帧 | 不把不同运行的值混在一起 |
|
||||
|
||||
不要求所有读者理解 SymbolId、IR、hash 或 effect 协议。开发者仍能找到这些信息,但它们不再成为阅读的前置条件。
|
||||
|
||||
## 4. 页面信息架构
|
||||
|
||||
### 4.1 默认桌面布局
|
||||
|
||||
```text
|
||||
┌ Marqdo 项目 / 文档路径 搜索 主题 ┐
|
||||
├───────────┬───────────────────────────────┬────────────┤
|
||||
│ 文件目录 │ Phase I — tree-walk interpreter│ 本文结构 │
|
||||
│ │ Lex · parse · check … │ 介绍 │
|
||||
│ 当前文件 │ [运行记录:尚未运行] [详情] │ main 入口 │
|
||||
│ │ │ │
|
||||
│ │ Milestone: Phase I … │ │
|
||||
│ │ Pipeline: load → … → eval │ 选中后: │
|
||||
│ │ │ 当前知识 │
|
||||
│ │ main · 入口 │ 作用 │
|
||||
│ │ 输出说明 print text=… [说明] │ 输入/返回 │
|
||||
│ │ │ 来源/条件 │
|
||||
│ │ ▸ 运行与结果 │ 检查/运行 │
|
||||
│ │ ▸ 完整源码 │ 技术详情 ▸ │
|
||||
└───────────┴───────────────────────────────┴────────────┘
|
||||
```
|
||||
|
||||
布局是文件导航、主文档、一个辅助栏,不能增加第四条永久侧栏。右栏上部保留可收起的“本文结构”;用户选中片段后,下部显示“当前知识”。空间不足时以当前知识替换下部内容,并提供“返回目录”操作。打开/关闭详情不改变正文宽度,避免重排导致阅读位置跳动。
|
||||
|
||||
主文档的默认顺序:
|
||||
|
||||
1. 文档标题、已有 description、简短状态入口;title 缺失时退回文件名。
|
||||
2. 源文档的正文、结构和轻量就地知识说明,保持作者顺序。
|
||||
3. “运行与结果”:运行按钮、输入、所选运行结果、输出图形/日志;已有重要失败有就地入口。
|
||||
4. “完整源码”及“文档技术信息”,默认折叠。
|
||||
|
||||
不在顶部强制生成内容摘要、全量函数清单、巨大状态矩阵或知识关系图。没有 description 时不调用 LLM 补写。结构大纲始终可达,正文不因折叠辅助栏而变成无结构的文章。
|
||||
|
||||
### 4.2 尺寸与响应式规则(设计目标)
|
||||
|
||||
| 可用宽度 | 布局 |
|
||||
|---|---|
|
||||
| ≥1280 CSS px | 文件栏约 220–260px;正文弹性;辅助栏约 280–320px;正文中文行长约 32–44 字 |
|
||||
| 900–1279px | 文件栏可收起;正文优先,辅助栏可切换为有标题的侧抽屉 |
|
||||
| <900px | 单列文档;“目录”“当前知识”作为明确按钮打开抽屉或块内 details |
|
||||
| 320–390px 手机 | 标题、正文、状态不横向溢出;长表格/代码局部滚动,整页不左右拖动 |
|
||||
| 打印 | 正文展开,必要来源/验证摘要转为节后附注;交互按钮和导航隐藏;技术原始字段按导出选项包含 |
|
||||
|
||||
在 1440×900、100% 缩放的短文验收样例中,首屏应包含至少一段正文和首个主要结构单元;状态头不得因每个 artifact 增长而把正文推出首屏。此约束不截断作者自己的长标题或介绍。
|
||||
|
||||
### 4.3 普通文档与复杂知识文档采用同一布局
|
||||
|
||||
- 普通说明页只有 main/print:显示原文与输出操作,技术区保留模块信息;不强制展示“1 项可执行知识”卡。
|
||||
- 可复用函数库:目录列出函数;函数标题下出现紧凑签名和“说明”入口;即使无 main,也能正常阅读。
|
||||
- 事实/规则文档:来源、条件与验证紧邻相应知识;来源问题不能藏进页尾。
|
||||
- 教程/Notebook:保留源文档的代码单元与结果;全局单元运行条收进运行区域或显式工作模式,不能把所有文章永久变为 notebook 工具台。
|
||||
- 大文档:目录按真实层级和顺序组织,可搜索;正文不因知识数量膨胀为另一份报告。
|
||||
|
||||
## 5. 文档与结构呈现规范
|
||||
|
||||
### 5.1 标题、类与函数层级
|
||||
|
||||
页标题优先来自解析后的 frontmatter `title`,其次使用合适的源文档标题,再回退文件名;不要自行用正则重解析 YAML。保留原文标题内容,不擅自把技术名称改成模型生成的名称。
|
||||
|
||||
“本文结构”同时服务阅读和程序定位,但明确区分:
|
||||
|
||||
- 作者章节按实际文档关系展示。
|
||||
- 可执行的类/类型、函数、入口附轻量类型词,例如“规则”“函数”“入口”;类型词来自编译结果或已声明元数据,不由标题猜业务类型。
|
||||
- 同一节点既是章节又是函数时只有一个目录项,旁边标类型,避免两棵树重复。
|
||||
- 嵌套函数、分支、循环在对应父节点下展开;语义归属与 Markdown 可视层级分别保留,不把所有内容都扁平化为 h3。
|
||||
- 普通段落引用不提升为函数;module 容器不自动成为一张与业务函数同权的卡。
|
||||
|
||||
DOM 标题使用连续、可访问的层级;实际语法的 `#`/`##` 层数在源码面保留。用户复制源码时取得原始合法语法,而非为了 HTML 标题级别改写过的内容。
|
||||
|
||||
### 5.2 可执行步骤:就地解释并保留上下文
|
||||
|
||||
| 编译器步骤 | 默认阅读文案 | 展开后 |
|
||||
|---|---|---|
|
||||
| observe | “读取:商品单价” | 集合、取元表达式、字段说明、当前调用下的值 |
|
||||
| derive | “计算:商品小计” | 公式、输入来源、计算条件、当前结果 |
|
||||
| call | 优先作者标签;无标签时“调用 商品小计” | 目标、所属文档、实参映射、返回和运行记录 |
|
||||
| iterate | “逐项处理:订单商品” | 集合、循环体、迭代数、所选迭代 |
|
||||
| narrate | 正文保留作者描述,附“知识引用”入口 | 定义与来源;不当作已执行步骤 |
|
||||
| navigation | 标准文档链接 | 正常导航,不显示虚构的执行结果 |
|
||||
| 空 payload / stub | 作者描述 + “待实现” | 缺失的实现和已有诊断,不能展示成功数值 |
|
||||
|
||||
名称来自当前节点的 label、声明说明、目标可读名,依次回退;没有业务描述时就显示“调用 print”,不得自动声称它是“验证知识”或“输出最终结论”。普通 print 在所属文档位置解释输出作用,放在“输出”类信息中,不作为高价值知识卡突出。
|
||||
|
||||
“步骤”列表只在当前知识详情中显示,标为“文档中的步骤”或“结构步骤”。静态序号不能暗示实际执行时序;实际轨迹另按运行事件呈现,分支和循环保留嵌套。
|
||||
|
||||
### 5.3 描述、实现与结果的三层关系
|
||||
|
||||
以 `**总价 = [计算订单小计](pricing.小计(数量, 单价))**` 为说明示意:
|
||||
|
||||
```text
|
||||
计算订单小计 [说明]
|
||||
总价 = pricing.小计(数量, 单价) ← 简短实现,次一级视觉
|
||||
本次示例:数量 2,单价 30 → 60 ← 仅有匹配运行记录时出现
|
||||
```
|
||||
|
||||
作者的上下文句、返回说明、单位和条件仍在原位。短公式/实现可次级显示,长 payload 默认折叠到详情;显式“展开实现”控制可对当前知识单元生效。不得把所有代码完全藏掉,使“代码即文档”退化成只有自然语言标签。
|
||||
|
||||
复制操作区分“复制说明”和“复制源码”;源码来自源 span,保留必要定界符、参数和 import 依赖提示。显示为漂亮文本的结果不能被复制成伪造的可执行代码。
|
||||
|
||||
### 5.4 表格、条件与关系
|
||||
|
||||
数据表按作者结构呈现,表头固定语义,单位与列说明常显;契约表按输入/返回/约束组织。显示层不能把 Marqdo 列向集合悄悄换成行向记录;需要另一种预览时明确标为预览,并能查看真实形状。
|
||||
|
||||
前提条件与失败分支不得因“简洁”隐藏。默认显示全部分支结构,所选运行只突出实际命中的分支,继续遵守 [调用帧与结构保真](view-frame-selection.md)。
|
||||
|
||||
跨文档关系默认用可读链接,例如“使用:标准税率 · tax.mq.md”,而非 `mq://…`。直接依赖与被引用者各列前几项并可展开;可选局部关系图放在详情层,不作为默认阅读画布。关系图必须有等价文字列表,并显示未知/动态关系,不能补画不存在的边。
|
||||
|
||||
## 6. 当前知识详情:回答问题,而非列出字段
|
||||
|
||||
### 6.1 内容顺序
|
||||
|
||||
```text
|
||||
商品小计 函数
|
||||
根据数量与单价计算商品金额。 ← 仅引用已有描述
|
||||
|
||||
输入 数量:整数;单价:金额 ← 类型/单位未知则明确未知
|
||||
返回 金额
|
||||
条件 数量非负 ← 仅当已声明且可定位
|
||||
实现 数量 × 单价
|
||||
|
||||
来源 定价说明 / 第 2 节 [打开]
|
||||
检查 契约未检查;测试未运行 [查看依据]
|
||||
运行记录 示例 #2:2 × 30 → 60 [定位输出]
|
||||
使用 … [查看定义]
|
||||
|
||||
▸ 技术详情:精确标识、完整签名、效应、摘要、诊断 JSON
|
||||
```
|
||||
|
||||
此处“金额”“数量非负”等只用于解释布局,不宣称当前样例具有这些元数据。没有信息就省略非关键行或写“未声明”,不得推断成“无限制”“没有来源也可靠”。缺失影响可用性时常显;纯工具没有业务来源并不自动是错误。
|
||||
|
||||
### 6.2 当前字段的去向
|
||||
|
||||
| 当前字段 | 新的主要位置与文案 |
|
||||
|---|---|
|
||||
| Target / `mq://…` | 标题处可读定义链接;完整 ID 在技术详情,可复制 |
|
||||
| Kind / callable | 标题旁简短类型词;module 信息进入文档技术信息 |
|
||||
| Signature | 输入/返回紧凑表;完整规范签名可展开 |
|
||||
| Effects | “涉及的操作”,说明文件读写、网络等;未知明确显示,非纯不等于失败 |
|
||||
| Verification 长串 | 分项检查和证据表,见 §7 |
|
||||
| Lock digest | 更名“制品摘要”,技术详情内显示;锁状态单独来自真实 lock report |
|
||||
| Depends on | 可读目标列表,指向定义与引用位置;未分析不能写“无依赖” |
|
||||
| Execution 固定句 | 匹配运行记录,或“尚无该知识的运行记录” |
|
||||
| SourceRef / applicability | 当前遗漏的关键内容:放入“来源”和“适用条件” |
|
||||
|
||||
默认不铺完整 hash。技术详情可显示缩略摘要并提供全值/复制;缩略值不用于识别唯一性。没有读取锁报告时写“未检查锁定状态”,不能把拥有摘要显示成“已锁定”。
|
||||
|
||||
### 6.3 交互、跳转与返回
|
||||
|
||||
1. 点击正文的“说明”或目录知识项,选中同一 `node_id`;正文轻量高亮,右栏同步。键盘和触屏具有等价入口,不依赖 hover。
|
||||
2. 跳转到定义时保留来源文件、锚点、滚动位置和所选运行;返回恢复阅读位置。
|
||||
3. 文件、符号与语句不能只靠显示名称匹配。同名函数的详情显示所在文档和父结构。
|
||||
4. 默认不自动抢焦点、不因滚动不停替换用户正在阅读的详情。滚动只更新目录当前位置;点击选择才改变详情。
|
||||
5. 手机抽屉有标题、关闭、返回焦点和滚动管理;无 JS 时使用正文附近的原生 details 或页尾知识附注锚点。
|
||||
6. 当前 URI 不在导出范围内时显示“定义未包含在此次导出”,提供可读路径和复制引用;禁止输出必然失效的 `mq://` 或 live `/file` 链接。
|
||||
|
||||
## 7. 状态设计:读者必须知道什么被证明了
|
||||
|
||||
### 7.1 分离三个状态来源
|
||||
|
||||
| 状态来源 | 可以说明 | 不能说明 |
|
||||
|---|---|---|
|
||||
| 编译/静态分析 | 结构解析、目标绑定、契约检查结果、已建模效应 | 程序已运行、答案正确、资料真实 |
|
||||
| 运行记录 | 指定输入、环境、源码版本下的执行与输出 | 覆盖所有输入、测试通过、来源可信 |
|
||||
| 证据/验证记录 | 哪个断言/测试/来源核验通过,何时失效 | 未执行或未核验的其它部分也可靠 |
|
||||
|
||||
顶部仅给紧凑事实,例如“静态分析完成 · 尚无运行记录”,或“有 1 项来源问题 · 查看”。普通 unknown/unchecked 不应制造全页红色警报;与当前结论直接相关的失败、过期、未解析必须就地提示且可定位。
|
||||
|
||||
### 7.2 分项文案映射
|
||||
|
||||
| 机器状态 | 阅读文案 |
|
||||
|---|---|
|
||||
| parse=passed | 文档结构可解析 |
|
||||
| resolve=passed | 此项检查报告目标已解析;覆盖范围见详情 |
|
||||
| contract=unchecked | 契约尚未检查 |
|
||||
| execution=not_run | 尚无执行记录 |
|
||||
| tests=unknown | 尚无测试记录 |
|
||||
| evidence=sourced | 已关联来源,内容尚未核验 |
|
||||
| evidence=unverified | 来源内容尚未核验;结合来源列表判断是否已关联 |
|
||||
| missing_source / expired | 来源缺失 / 已过适用期 |
|
||||
| domain=unreviewed | 尚无领域审阅记录 |
|
||||
| effects=pure | 静态分析未发现已建模的外部操作;展开可看范围 |
|
||||
| effects=unknown | 涉及的操作尚不能完全确定 |
|
||||
| 无对应字段 | 未提供该项检查结果 |
|
||||
|
||||
分项取值不能自动升级成综合“可信”。只有宿主选定的政策实际给出聚合结论,才显示“满足 ×× 政策”,同时附政策名称、版本与证据;业务条件还须明确展示。
|
||||
|
||||
### 7.3 结果来源与失效
|
||||
|
||||
每个运行值绑定 `run_id + source_digest + node_id + call_id + loop/iteration` 中适用的字段,展示本次输入或简短上下文。无节点映射时只展示整次运行输出,不硬塞到某个函数旁边。
|
||||
|
||||
静态导出有快照时标“导出快照”,附生成时间/输入;读者切换调用帧是在看历史结果,不叫“重新计算”。源码、依赖或来源与记录不匹配时标“历史结果,版本已变化”,不继续用成功样式绑定到新正文。
|
||||
|
||||
正文里的字面量可以显示为“文档声明值”;解释器实际执行得到的值才叫“运行结果”。没有值、返回 None、stdout 为空、尚未运行、执行失败必须分开,不能统一成 `(no stdout)`。
|
||||
|
||||
### 7.4 空态与错误态
|
||||
|
||||
| 情况 | 处理 |
|
||||
|---|---|
|
||||
| 没有可识别知识单元 | 正常显示文档,不插空知识面板 |
|
||||
| 语义分析失败 | 保留可读正文/源码,显示“知识关系暂不可用”及可定位诊断 |
|
||||
| 局部未解析 | 仅对应片段显示问题,保留其它已知结果 |
|
||||
| 无运行或 no-exec | 运行区说明原因,使用中性状态,无绿色运行成功标记 |
|
||||
| 运行失败 | 错误摘要定位到源片段;日志在运行区,静态知识仍可读 |
|
||||
| 证据过期/冲突 | 相关知识常显问题、来源与影响;不静默选择一个结论 |
|
||||
| 分析被截断/超过扫描范围 | 显示范围和未覆盖项;“未发现”不能替代“没有” |
|
||||
|
||||
## 8. 视觉、密度与可访问性
|
||||
|
||||
### 8.1 排版与主题
|
||||
|
||||
正文建议 16–18px、行高约 1.65;辅助说明 13–14px、行高约 1.5;代码使用等宽字体,全文不因进入 notebook 主题缩为密集工具面板。主次依赖字号、间距和位置共同表达,不能仅靠颜色。
|
||||
|
||||
使用现有系统字体和主题机制,建立统一的 view tokens:正文/辅助文字、背景、细分隔、焦点、成功/警告/错误。知识组件只依赖 tokens,不硬编码黑色线条或白底。支持明暗主题,首次尊重系统/显式设置,不为这次改版再写第三套皮肤。
|
||||
|
||||
表格与长公式允许局部滚动;ID、路径在详情中可换行;主文无整页水平滚动。重要来源和适用条件不使用极浅灰隐藏。对比度验收目标:普通文字至少 4.5:1,大字和必要非文本边界至少 3:1;这些是实现验收目标,尚非本轮测量结果。
|
||||
|
||||
### 8.2 注释和连线
|
||||
|
||||
默认使用紧邻内容的短结果行或有标签的注释块,优先通过“同一节点名 + 明确位置”关联。长 L-leader 不再是默认必需元素;复杂节点可保留短连线,必须满足端点存在、在同一块内、不交叉、不覆盖文字。
|
||||
|
||||
当目标折叠、帧过滤、元素隐藏或几何测量失败时,不绘制连线。主题/字体/容器宽度变化后只重算当前可见块;采用可取消的局部布局更新,不全页不断测量。窄屏、打印、reduced-motion 下直接使用有编号的注释。截图中的孤立线条归入专门视觉回归场景。
|
||||
|
||||
### 8.3 键盘、屏幕阅读器与退化
|
||||
|
||||
- 目录用 nav,正文用 main/article,详情用有名字的 aside/section;标题层级连续。
|
||||
- 展开按钮有 `aria-expanded/controls`;选中状态、失败和待验证都有文字,不依赖颜色或图标。
|
||||
- 深链接滚动有 `scroll-margin-top`,聚焦目标不被固定工具条遮住;关闭详情后焦点回到触发点。
|
||||
- 不使用只有鼠标悬停才能看到的来源、代码或错误。大表格有标题与表头关系,日志可复制。
|
||||
- 无 JS 时正文、目录锚点、来源链接、原生 details 和静态结果仍工作;只失去实时联动与运行操作。
|
||||
- 选择帧不隐藏源结构;隐藏实现也不能删除文档含义和必需条件。
|
||||
|
||||
## 9. 技术设计与数据契约
|
||||
|
||||
### 9.1 从预拼 HTML 改为可关联的展示模型
|
||||
|
||||
当前 `FileViewModel.knowledge_html` 是独立 HTML 字符串,难以与正文、trace、诊断同步。建议新增结构化 `KnowledgePresentation`,在 Rust 端形成同一份模型,由正文、目录、详情共同消费。兼容阶段可保留旧字段,但不让它继续成为唯一知识接口。
|
||||
|
||||
```text
|
||||
ViewDocument
|
||||
document_id, source_digest, semantic_generation, title, description
|
||||
blocks[] 保真正文结构及 source span
|
||||
outline[] 标题/知识单元父子关系
|
||||
knowledge_nodes[] 对应 artifact/ref/step,不复制语义解释器
|
||||
diagnostics[] 范围、严重性、可读说明、定位
|
||||
execution_state 明确未运行/运行中/成功/失败/快照
|
||||
run_records[] 与文档版本相匹配的证据
|
||||
|
||||
KnowledgeNode
|
||||
node_id, artifact_id?, symbol_id?, ref_id?, step_id?
|
||||
owner_id?, source_span, display_name, authored_description?
|
||||
kind, signature?, payload?, dependencies[], provenance[]
|
||||
applicability?, verification[], effects, coverage
|
||||
execution_refs[]
|
||||
```
|
||||
|
||||
这些字段为建议契约,未承诺当前 IR 已提供所有信息。语义事实来自 `SemanticProject`,文档叙述来自解析后的源结构,执行事实来自 capture;缺少关系时展示 unknown,不让 UI 用名称模糊匹配或调用模型编造。
|
||||
|
||||
### 9.2 数据流
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
S[源文档与项目边界] --> P[解析与语义分析]
|
||||
P --> B[正文块与结构]
|
||||
P --> K[知识节点与诊断]
|
||||
R[显式运行或匹配的历史快照] --> T[执行记录]
|
||||
B --> V[统一展示模型]
|
||||
K --> V
|
||||
T --> V
|
||||
V --> D[正文与就地说明]
|
||||
V --> O[目录与当前知识]
|
||||
V --> E[运行区域与技术详情]
|
||||
```
|
||||
|
||||
知识模型不通过“render HTML → 再抓取文本”生成。页面分析失败不可用空字符串吞掉,应保留有状态的结果;部分成功与整体失败分开。
|
||||
|
||||
### 9.3 源位置、稳定身份与锚点
|
||||
|
||||
目前 step 跳转用 `#stmt-{line}`,函数用 `#fn-{line}`。一行多个表达式、正文段落合并、同名函数、源码插行都会使单纯行号不够。
|
||||
|
||||
新增内部节点锚点注册表,将文档块、函数、语义 step/ref 与真实 DOM id 映射;使用 artifact/node 身份和源 span 生成页内唯一 ID,不把未经编码的 URI 当 DOM id。当前编译器没有稳定 SyntaxNodeId 的地方,退化为“源码版本 + span”,明确跨版本不可保证稳定;不能只把行号哈希一下就宣称稳定身份。
|
||||
|
||||
兼容现有 `#structure`、`#fn-N`、`#stmt-N` 链接,保留别名或定位映射;所有生成链接都验目标存在。跨文件 href 复用 [html.rs 的 LinkMode/href_file](../../src/view/html.rs),静态导出保持相对路径;路径展示解码与 URL 安全编码分离。
|
||||
|
||||
### 9.4 分离分析与执行,修正 no-exec
|
||||
|
||||
将当前 `build_file_view` 拆成可组合路径(名称为建议):
|
||||
|
||||
1. `analyze_document`:读取、解析、语义检查、生成静态展示数据,不执行目标程序。
|
||||
2. `capture_execution`:只有执行策略明确允许时调用 run/cell runtime,返回真实状态与源版本。
|
||||
3. `assemble_view`:关联正文、语义和匹配的结果,生成同一个展示模型。
|
||||
|
||||
`--no-exec` 必须在第 2 步之前分支,不能先跑后清空;snapshot 模式使用匹配快照,不为了构造 UI 又运行一次。Live 现有自动执行兼容行为在首轮不静默改变,必须通过显式 execution policy 传入并如实标注;若后续将 live 默认改为阅读时不执行,作为独立 CLI 行为变更发布和迁移。点击详情、查看来源、展开关系等阅读操作绝不能触发执行。
|
||||
|
||||
知识详情不要求通过运行得出静态信息。实现参数预览/试跑时,使用既有受控执行路径,不因“pure”字样绕过宿主能力边界。本文不新增一套求值器或权限系统。
|
||||
|
||||
### 9.5 Live 更新一致性
|
||||
|
||||
当前 SSE 会替换 structure_html/bindings_html/trace_json,而知识面板来自另一次静态编译,容易新旧混用。建议更新包包含文档摘要、语义代、run_id 和变更节点;前端仅合并兼容版本的数据。
|
||||
|
||||
运行写回导致源码变化时,重新分析后一次更新相互关联的正文、目录、知识与运行映射。原选中节点仍存在则保留选择/焦点/滚动;已消失则明确提示,不能悄悄指向同名节点。旧请求返回晚于新请求时按版本丢弃,不覆盖较新阅读状态。
|
||||
|
||||
### 9.6 性能与导出体积
|
||||
|
||||
避免每个页面重复编译整个项目。一次静态导出共享同一项目语义结果,逐页投影;live 按项目源指纹、编译器版本、配置和适用性时钟缓存,读取使用一致的语义代。来源/有效期变化必须使相关状态失效,不能无限缓存 sourced。
|
||||
|
||||
正文服务端生成,不等待 JS 初始化或全部知识图完成才出现。默认只嵌入当前文档必要知识,深层依赖按需取;静态导出则包含保证离线可用的局部数据与明确范围。大量结果采用折叠/分页,但不能让屏幕阅读器和查找失去正文。
|
||||
|
||||
性能验收目标:100 个知识单元的本地选择/展开交互 p95 ≤100ms;1000 单元目录可搜索而不阻塞正文滚动;导出项目的语义编译次数不随页面数线性重复。记录硬件、样例和体积,目标未达时先优化数据重复和布局测量,不以截断关键来源达标。
|
||||
|
||||
## 10. 实施文件与兼容策略
|
||||
|
||||
| 位置 | 建议变更 |
|
||||
|---|---|
|
||||
| [src/view/render.rs](../../src/view/render.rs) | 提取知识展示模型;替换全量 dl 面板;关联步骤归属、友好名称与诊断 |
|
||||
| [src/view/document.rs](../../src/view/document.rs) | 源块/知识节点映射、正文就地入口、层级标题、可复制原始 span |
|
||||
| [src/view/html.rs](../../src/view/html.rs) | 正文优先布局、辅助栏、详情/目录交互、状态组件、统一 tokens;保留 LinkMode |
|
||||
| [src/view/mod.rs](../../src/view/mod.rs) | 分离分析/执行、保留诊断、组装统一模型、项目分析缓存 |
|
||||
| [src/view/output.rs](../../src/view/output.rs) | 提前应用 no-exec/snapshot 策略、共享项目分析、静态详情与相对跳转 |
|
||||
| [src/view/annot.rs](../../src/view/annot.rs) | 运行标注与节点/帧/版本关联,减少重复输出;缺映射不伪绑定 |
|
||||
| [src/view/debug_page.rs](../../src/view/debug_page.rs) | 仅回归检查共享组件;不把阅读布局强加给 debug |
|
||||
| [tests/executable_knowledge.rs](../../tests/executable_knowledge.rs)、view 单测 | 从字符串存在升级到顺序、锚点、状态和执行边界断言 |
|
||||
| 文档与 public 示例 | 更新旧 View 布局说明、截图和行为描述,区分历史默认与新设计 |
|
||||
|
||||
默认展示不要求作者补特殊 frontmatter;title/description、函数说明、契约和来源已有时直接受益。尚无信息的旧文档保真显示,并在详情中如实缺省。
|
||||
|
||||
与现有文档的关系:保留 [view-document-annotations](view-document-annotations.md) 的叙述主导和真实结果,修订“长 L-leader 为默认”;保留 [view-frame-selection](view-frame-selection.md) 的源码常显与帧隔离;[view-markup-surface](view-markup-surface.md) 的历史 Classic 例子需按当前默认语法同步,不能在新 UI 继续教授旧取元。外联/WASM 交互沿既有独立路线发展,不作为完成本次阅读改版的前置。
|
||||
|
||||
## 11. 分阶段交付
|
||||
|
||||
### V0:先纠正顺序、误导状态和执行边界
|
||||
|
||||
正文提前;完整知识报告收进明确的辅助入口,module/type 容器默认不铺卡;“Lock digest”改为准确的摘要标签;状态不再共用一个 ok。修复 no-exec 先执行问题,分析错误可见。暂不等待完整节点模型,就能显著改善截图场景。
|
||||
|
||||
V0 不算最终完成:仅把面板搬到后面/折叠,仍未解决正文与知识的关联。
|
||||
|
||||
### V1:完成阅读与结构理解的主闭环
|
||||
|
||||
统一展示模型、标题/目录层级、就地说明、当前知识详情、友好定义跳转与返回。完成函数、计算、来源、空态与基本运行结果的正负例;live/static 共用。
|
||||
|
||||
### V2:贯通运行、来源和跨文档关系
|
||||
|
||||
匹配运行实例与版本、调用/循环帧、来源定位/失效、局部依赖关系、SSE 原子更新。上游证据能力尚不完整的地方明确显示未知,不能以 UI 补出“验证通过”。
|
||||
|
||||
### V3:移动端、离线和规模验收
|
||||
|
||||
完成键盘/读屏、无 JS、打印、暗色/浅色、100/1000 单元性能、视觉回归与读者测试。发布前同步 public 示例与说明,保留旧锚点兼容。
|
||||
|
||||
## 12. 验收矩阵
|
||||
|
||||
### 12.1 必测文档
|
||||
|
||||
| 样例 | 必须验证 |
|
||||
|---|---|
|
||||
| 截图对应 Phase I 页 | 正文先出现;无 full URI/hash 瀑布;print 在所属正文解释;无孤立线条 |
|
||||
| 纯叙述/少量 Markdown 页 | 阅读无知识空卡、无误导运行徽章 |
|
||||
| 单个纯函数,无 main | 参数/返回与调用方式清楚,不因无入口标全文失败 |
|
||||
| 订单定价、多文档 import | 小计/税率/总额归属和依赖可追踪;输入和结果可对应 |
|
||||
| 带来源的事实与过期/缺失来源 | sourced 不显示已证实;问题在对应知识旁可见 |
|
||||
| 同名函数、多次调用和循环分支 | 定义唯一;切换帧只改结果和高亮,不隐藏结构 |
|
||||
| 空 payload、动态调用、未解析引用 | 待实现/动态/未解析准确可辨,不能展示虚构结果 |
|
||||
| 一行多个链接、嵌套表达式、中英文/长路径 | span 对应、锚点唯一、文本不丢失、不水平溢出 |
|
||||
| 运行失败、分析失败、快照过期 | 三种情况分开,仍能读到正文与具体诊断 |
|
||||
| 外联单元、变量大表、长日志 | 单层主体与对应结果,不重复三份输出;局部滚动 |
|
||||
|
||||
### 12.2 自动化判据
|
||||
|
||||
1. DOM 中文档主体先于全量知识技术详情,标题来自既有元数据;短文没有隐藏正文的默认展开报告。
|
||||
2. 每个知识/目录链接都能定位真实节点;一行多节点和同名跨模块不冲突;live/static 路径均有效。
|
||||
3. 验证、运行、来源状态按固定真值表渲染;无证据时绝不输出综合已验证。
|
||||
4. no-exec 用隔离目录的副作用计数测试证明没有执行;snapshot 不重跑;展开详情也不执行。
|
||||
5. 帧选择和 SSE 更新保留正文结构、选中身份与焦点,拒绝过期结果包。
|
||||
6. 明暗主题/320、390、1024、1440 宽度/200% 缩放下无遮挡、截断关键条件和整页横向溢出;孤立 leader 数为零。
|
||||
7. 无 JS、file 静态打开、打印预览都保留正文、定义/来源导航和必要证据说明。
|
||||
8. 输出中的作者内容、label、URI/属性与嵌入 JSON 按原上下文转义;资料中的 HTML/脚本不能因为新详情组件被直接执行。
|
||||
|
||||
字符串断言只能覆盖结构,不能替代浏览器布局验收;需截图基线和真实键盘交互测试。可复用现有测试基础,避免测试只镜像组件实现。
|
||||
|
||||
### 12.3 读者任务测试
|
||||
|
||||
建议用至少 5 位未参与实现的读者,分别完成三个任务,并与当前页面对照:
|
||||
|
||||
- 在 30 秒内说清文档目的并找到主要规则/函数。
|
||||
- 在 60 秒内找到某个结果的输入、定义和原始来源。
|
||||
- 正确区分“来源已关联但未核验”“本次运行成功”“未运行/历史结果”,不得误认为都已验证。
|
||||
|
||||
目标为至少 4/5 完成前两项,第三项无误导性判断;小样本仅作为可用性门槛,不声称统计显著。记录失败位置并修正信息架构,不能只问“是否好看”。
|
||||
|
||||
## 13. 完成定义与本次交付边界
|
||||
|
||||
完成的 view 应让读者先读懂文档,再自然看到其中的知识与执行结构;需要深入时能沿着一个具体片段追到实现、输入、结果和证据。全量技术字段仍可查,但不要求读者先理解编译器才能读文档。
|
||||
|
||||
本次只提交设计文档与索引,不修改渲染实现。实证包括用户截图、当前模板/渲染路径、静态 HTML 顺序检查和临时 no-exec 反例;布局尺寸、交互、性能和读者任务结果均为待实施的验收目标。
|
||||
@@ -16,17 +16,22 @@
|
||||
|
||||
| AST / 概念 | View 优先显示 | 备注 |
|
||||
|------------|---------------|------|
|
||||
| `Expr::Index` | `[键](基)` | 嵌套 `[k2]([k1](base))` |
|
||||
| `InterpPart::Index` | 同上嵌套链接形 | 不再默认 `` `base`[^k] `` |
|
||||
| `Expr::Occluded` | 正文只读动作说明,实际实现进入侧注 | 每个片段独立关联,不把整句改成一次赋值 |
|
||||
| 空遮蔽 `()` | 待补充实际逻辑 | 当前空遮蔽返回 None,不伪装成已接通工具 |
|
||||
| `Expr::Index` / `InterpPart::Index` | 保留经典或脚注取元的兼容说明 | 当前作者程序优先用 access 读取集合;默认链接形是遮蔽 |
|
||||
| `CallExpr` + `bracket_marked` / `pre_modifiers` | `修饰 [callee] 实参…` 或 `[callee] 实参…` | 仅经典 `>` 解析时仍显示 `> callee …` |
|
||||
| 赋值 / 返回 | 粗体 / 斜体语义即可 | 不强制还原整句叙述 |
|
||||
| foreach | `- [项](集合)` | 不变 |
|
||||
| 赋值 / 返回 | 保留原叙述句子,在真实执行片段上标明语句或返回 | 普通链接与字面量不冒充执行遮蔽 |
|
||||
| foreach | `- [动作](遍历 集合 为 项)` | 正文显示动作,控制逻辑见侧注;迭代选择器只切换已有运行记录 |
|
||||
|
||||
## 3. 非目标
|
||||
|
||||
- 不把 view 做成第二语法;解析真相仍在 mapping / call-arguments。
|
||||
- 不删除对脚注取元、旧 `>` 调用的兼容显示需求时,可用次要提示,但默认推荐面优先。
|
||||
|
||||
当前阅读器的实现与验收见 [view-readable-actions.md](view-readable-actions.md)。
|
||||
可执行知识先展示输入、返回、调用边界、依赖和各项依据;摘要和机器身份按需展开。
|
||||
源码说明与运行标注分开,展开侧注或知识卡片不会执行代码。
|
||||
|
||||
## 4. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
# View:动作留在正文,逻辑留在侧注
|
||||
|
||||
本轮针对阅读界面,不改变语言求值和工具权限。阅读示例为
|
||||
[view-reading.mq.md](../../examples/view-reading.mq.md)。
|
||||
|
||||
遮蔽按真实 AST 识别,随后按源片段保留句子:方括号的动作说明留在正文,圆括号中的
|
||||
实现进入独立侧注。同一句话可以包含多个调用和返回,不再把整行当成一次赋值。
|
||||
文字字面量中的链接、普通 Markdown 导航与 classic 取元不冒充执行遮蔽。
|
||||
空圆括号明确显示“待补充实际逻辑”,并说明当前空遮蔽返回 None。
|
||||
|
||||
宽屏实现侧注与运行标注共用现有的左右避碰及引出线布局,彼此有明确名称区分。
|
||||
实现侧注标记“源码说明 · 不是运行结果”,不带调用帧或迭代帧身份。
|
||||
密集区域、窄屏和无脚本页面使用可原生展开的 details;动作按钮可按需查看完整逻辑。
|
||||
悬停与键盘聚焦关联实际源片段,不触发运行。
|
||||
|
||||
“怎样读这份可执行文档”沿用核心构造注册表,说明参数、赋值、返回、调用、条件、
|
||||
循环、数据表、代码块、公式、写回与兼容标记。公式和外语代码仍使用既有卡片,
|
||||
不新增语法或作者必填的展示配置。
|
||||
|
||||
可执行知识按真实源单元分组。默认先读输入、返回、调用边界、依赖和验证依据,
|
||||
身份、摘要与原始状态收进技术详情。契约说明来自已解析的参数和返回表;缺失时如实说明。
|
||||
语法检查、契约检查、测试、来源和领域审阅分别展示,静态分析不代表实际执行或内容正确。
|
||||
源码结构步骤与实际运行时序分开;内存面板先展示最终绑定与调用记录,再按需展开原始报告。
|
||||
|
||||
函数的说明链接和知识卡片使用当前文档源行定位,避免同名方法共用一个 DOM 身份。
|
||||
单文件阅读只分析它和实际导入的依赖,避免无关同目录模块重名导致知识区整体失败。
|
||||
目录阅读保留项目分析。来源身份及版本匹配沿用现有编译器和页面 token,不另建求值器。
|
||||
|
||||
验收入口:
|
||||
|
||||
```sh
|
||||
cargo test --offline --lib view::
|
||||
cargo test --offline --test view_readability
|
||||
cargo test --offline --test gold view_
|
||||
cargo test --offline --test executable_knowledge
|
||||
marqdo view output examples/view-reading.mq.md --no-exec --out /tmp/marqdo-reading
|
||||
```
|
||||
|
||||
浏览器验收脚本是 [readability.browser.cjs](../../tests/view/readability.browser.cjs),
|
||||
接收真实页面 URL,支持 MARQDO_PLAYWRIGHT_MODULE、MARQDO_CHROMIUM 和 MARQDO_SCREENSHOT_DIR。
|
||||
覆盖七种宽度、侧注边界与碰撞、多动作句子、空逻辑、知识卡片、正文定位和无脚本回退。
|
||||
原有 [reader.browser.cjs](../../tests/view/reader.browser.cjs)继续覆盖曲线、帧选择及实时/静态交互。
|
||||
|
||||
本轮实际验收(2026-11-08):67 项 view 相关单元测试、2 项新增只读导出测试通过;
|
||||
全量回归 984 通过、0 失败、2 个原有忽略项。真实 Chromium 验证静态快照、
|
||||
只读导出和实时页面,覆盖七种宽度、无脚本阅读、曲线与帧切换、源码定位及实时重新运行。
|
||||
GOFLAGS 仅对完整回归命令关闭工作区所有权引起的 Go VCS 盖章失败,不改全局配置。
|
||||
@@ -0,0 +1,64 @@
|
||||
# View botanical reader
|
||||
|
||||
Implemented 2026-11-07 for the shared `marqdo view` and `marqdo view output` shell.
|
||||
|
||||
The default is warm paper, serif document text, olive runtime notes, gold accents,
|
||||
and generated transparent blossom/feather ornaments. The M/book logo is embedded
|
||||
SVG. Navigation and the floating toolbar are code-native SVG icons and CSS.
|
||||
|
||||
`src/view/reader.css` is the final theme layer after notebook component styles;
|
||||
`src/view/reader.js` owns reader navigation, dialogs and annotation geometry.
|
||||
Notebook APIs and controls remain available through More → advanced tools.
|
||||
Welcome files get a larger introduction; ordinary files retain compact titles.
|
||||
|
||||
## Runtime notes
|
||||
|
||||
Annotations keep their existing owner band, stable IDs, source anchor, call frame
|
||||
and loop iteration data. Chips serialize source line and byte spans so another
|
||||
call/iteration frame can find the same source mark without guessing by kind.
|
||||
On viewports wider than 1000px with 180px available on each side, notes use both
|
||||
page margins, varying horizontal reach and vertical offset with collision
|
||||
avoidance. Dense bands that would drift more than 170px retain inline notes.
|
||||
Compact screens, printing, and expanded overflow bands use ordinary document
|
||||
flow. A shared SVG overlay draws continuously curved connections from the actual
|
||||
mark's source-facing lower edge to the annotation title. The default is a full
|
||||
S-curve with restrained gold/olive gradient; candidate sweeps are checked against
|
||||
visible source text and already drawn connections. Tight prose uses two joined
|
||||
curves below the text baseline and through the free margin, with no straight rail.
|
||||
Notes sit closer to the document with varying horizontal/vertical offsets, rather
|
||||
than stretching every connector across the entire page. Wrapped source marks use
|
||||
their actual line fragments. Hover/focus highlights the exact source and connector.
|
||||
Unresolved source anchors retain inline results instead of inventing a connection.
|
||||
Clicking a note shows its full captured detail. No explanatory prose or runtime
|
||||
values are invented.
|
||||
|
||||
Layout updates after window/font/structure resize, frame selection and live DOM
|
||||
replacement. Static HTML includes the same code and embedded assets. All KaTeX
|
||||
scripts, CSS and fonts are bundled for offline math. Optional syntax highlighting
|
||||
retains the previous CDN progressive enhancement; code remains readable offline.
|
||||
|
||||
`api/session/run_document` now returns prose HTML, bindings and trace JSON from
|
||||
its own capture. The reader applies that capture without rerunning the program.
|
||||
Page tokens prevent a changed source from receiving mismatched annotations.
|
||||
|
||||
## Navigation
|
||||
|
||||
Document returns to prose. Functions/Variables move the real existing panels into
|
||||
a modal and restore them on close, preserving their existing event handlers.
|
||||
Memory shows the captured execution report, labeled as a snapshot on exports.
|
||||
Run navigates to the output section. Search finds document, function and file text.
|
||||
The floating toolbar labels its icons 刷新 / 设置 / 运行 / 清理 / 更多.
|
||||
The bottom play button invokes actual live execution; static pages explain how to
|
||||
start a live view. Static clear hides captured output locally; reload restores it.
|
||||
Settings control light/dark theme, text size and annotation visibility. More keeps
|
||||
source, advanced execution controls, file navigation and print within reach.
|
||||
|
||||
## Validation
|
||||
|
||||
Run `cargo test --offline --lib view::` and `cargo test --offline --test gold view_`.
|
||||
The browser regression is `tests/view/reader.browser.cjs <URL>`; it accepts
|
||||
`MARQDO_PLAYWRIGHT_MODULE`, `MARQDO_CHROMIUM`, and optional
|
||||
`MARQDO_SCREENSHOT_DIR`. It blocks HTTPS resources to exercise offline reading,
|
||||
checks seven viewport widths, note bounds/collisions, source/label curve endpoints, visible curvature and non-crossing paths,
|
||||
shared-source frame binding, stable redraw, real panel restoration,
|
||||
search, frame selection, note inspection and live/static run behavior.
|
||||
@@ -0,0 +1,163 @@
|
||||
# Web 热路径:单解释器串行化(设计缺陷说明)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**(缺陷记录 + 缓解已落地) |
|
||||
| 日期 | 2026-10-26 |
|
||||
| 规范决策 | [ADR 0008](../adr/0008-web-invoke-serialization.md) |
|
||||
| 相关 | [ext-web-go-rewrite.md](ext-web-go-rewrite.md) · [ext-abi.md](ext-abi.md) · [ADR 0004](../adr/0004-web-plugin-go.md) · [ADR 0007](../adr/0007-web-document-endpoint.md) |
|
||||
|
||||
本文把「页面卡死 / 像单线程」拆成可验证的架构事实、错误语义与演进边界。
|
||||
**结论先行:HTTP 是多线程的;卡住是因为所有 Endpoint 共享一把解释器锁。**
|
||||
|
||||
增量实施提案见 [隔离执行与响应式 Web 运行时(2026-10-26)](isolated-web-runtime-development-2026-10-26.md):独立进程池、控制/读取容量、请求级事件与取消、缓存和恢复。提案通过验收前,本文件及 ADR 0008 的现行单飞约束不变。
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题陈述
|
||||
|
||||
### 1.1 用户可见症状
|
||||
|
||||
1. 发起一次长对话(OpenAI 兼容 `POST …/v1/chat/completions` + `stream:true` / `sse-live`)。
|
||||
2. 对话尚未结束时,打开设置、拉 `/v1/models`、或其它短 JSON API。
|
||||
3. **旧行为**:浏览器请求一直 pending,整页像死机;只能杀 `marqdo run serve…` 恢复。
|
||||
4. **目标行为**:短请求在约 1.5s 内得到 **HTTP 503**,错误体标明 `interpreter busy`;对话 SSE 继续;结束后短请求立刻恢复 200。
|
||||
|
||||
### 1.2 错误归因(不要再说错)
|
||||
|
||||
| 错误说法 | 正确说法 |
|
||||
|----------|----------|
|
||||
| 「web 插件是单线程的」 | Go `net/http` 与 SSE 刷写是多 goroutine |
|
||||
| 「忘记启动进程所以卡死」 | 进程在跑;是 **锁争用** 导致短请求永不返回 |
|
||||
| 「把 SSE 的等待时间调大就能修好」 | 进程级拉长 `MARQDO_INVOKE_WAIT_MS` 会让短请求一起卡死 |
|
||||
| 「去掉 INVOKE_LOCK 即可并行」 | `HostContext` 非 Sync,无锁并行会数据竞争 / 未定义行为 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 调用栈与锁边界
|
||||
|
||||
```
|
||||
Browser
|
||||
│ GET /v1/models POST /v1/chat/completions (SSE)
|
||||
▼
|
||||
Go plugins/web (多 goroutine)
|
||||
handleInvoke / handleInvokeLiveSSE
|
||||
│
|
||||
▼ C ABI host_query("call_lib_path", {path, args})
|
||||
Rust src/host/plugin.rs
|
||||
┌─────────────────────────────┐
|
||||
│ INVOKE_LOCK (进程级 Mutex) │ ← 同一时刻只允许一个 worker 进入
|
||||
└─────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
HostContext:装载/求值作者 .mq.md、写回、事件总线、LLM 插件回调…
|
||||
```
|
||||
|
||||
要点:
|
||||
|
||||
1. **锁在宿主,不在 Go 业务路由表。** 增加更多 Go handler 不会自动并行执行 Marqdo。
|
||||
2. **SSE 持锁时间 ≈ 整次 Endpoint 求值时间**(含多次 LLM 往返),可达数十秒到数分钟。
|
||||
3. **事件转发**(`MARQDO_EVENT_FORWARD` NDJSON)与 **取消**(`MARQDO_CANCEL_TOKEN`)在持锁期间仍可由其它 goroutine 写文件/读桥;它们不进入解释器,故不受 `INVOKE_LOCK` 保护,也不应误设长等待。
|
||||
|
||||
---
|
||||
|
||||
## 3. 为何不能简单「多线程跑 Marqdo」
|
||||
|
||||
`HostContext` 持有(非穷尽):
|
||||
|
||||
- 当前模块图、函数表、写回缓冲与 FS 根;
|
||||
- 插件注册与 `CURRENT_HOST` / 全局 host 指针;
|
||||
- Agent / LLM 运行时与 stream 发布钩子;
|
||||
- 与文档写回、会话态相关的可变结构。
|
||||
|
||||
这些状态在实现上按**单线程求值**建模。把它标成 `Sync` 或去掉 `INVOKE_LOCK` 而没有隔离运行时,属于未定义行为,不是性能优化。
|
||||
|
||||
**真并行的合法方向(未实现):**
|
||||
|
||||
1. **解释器池**:每请求或每会话一个 `HostContext`(或可重置的 isolate),路由层选闲置实例;
|
||||
2. **只读快照 + 写队列**:热路径只读克隆,写回串行合并(适合纯查询 Endpoint,不适合带写回的 agent);
|
||||
3. **把长任务移出解释器**:Marqdo 只做编排,重活在独立进程/队列(与「代码即文档」主路径权衡后再定)。
|
||||
|
||||
在上述任一方案落地并经金样例验收前,**产品必须以「单飞解释器」为约束设计 UX**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 缓解契约(已实现)
|
||||
|
||||
### 4.1 宿主:限时争锁
|
||||
|
||||
文件:`src/host/plugin.rs`
|
||||
|
||||
- 仅当从 worker 线程进入(`CURRENT_HOST` 为空、走全局 host)时争 `INVOKE_LOCK`。
|
||||
- `acquire_invoke_lock`:`try_lock` 循环,预算默认 **1500ms**(`MARQDO_INVOKE_WAIT_MS`,最小 1)。
|
||||
- 超时:`set_err("interpreter busy: another request holds the Marqdo invoke lock (waited …ms)")`,返回非 0。
|
||||
- **不要**在 SSE 入口把该环境变量设成数分钟:它是进程级的,会污染并发短请求。
|
||||
|
||||
### 4.2 Web 插件:503
|
||||
|
||||
文件:`plugins/web/internal/httpx/routes_invoke.go`
|
||||
|
||||
- 普通 JSON invoke:错误信息含 `interpreter busy` → **503** + `Retry-After: 2` + `{ok:false, error:…}`。
|
||||
- Live SSE:若启动时即 busy,以失败事件/错误结束该流,**不得**无限挂起握手。
|
||||
|
||||
### 4.3 客户端:超时与文案
|
||||
|
||||
短 API(模型列表、设置、registry 探测等)必须:
|
||||
|
||||
- 设置合理 `fetch` 超时(秒级,例如 8s);
|
||||
- 将 503 / `interpreter busy` 展示为「服务正忙(对话进行中)」类可读提示,而不是空白转圈。
|
||||
|
||||
(qdagent 前端 `frontend/src/lib/api.ts` 已按此契约处理。)
|
||||
|
||||
### 4.4 验收探针
|
||||
|
||||
在本地 serve 上:
|
||||
|
||||
```bash
|
||||
# 终端 A:启动长 SSE 对话(持锁)
|
||||
curl -N -m 120 -H 'Authorization: Bearer …' -H 'Content-Type: application/json' \
|
||||
-d '{"stream":true,…}' http://127.0.0.1:PORT/v1/chat/completions
|
||||
|
||||
# 终端 B:对话进行中
|
||||
curl -sS -w 'http=%{http_code} time=%{time_total}\n' --max-time 5 \
|
||||
-H 'Authorization: Bearer …' http://127.0.0.1:PORT/v1/models
|
||||
# 期望:http=503,time≈1.5,body 含 interpreter busy
|
||||
|
||||
# 对话结束后再打同一 URL → http=200,time≪1s
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 运维与调参
|
||||
|
||||
| 变量 | 默认 | 含义 |
|
||||
|------|------|------|
|
||||
| `MARQDO_INVOKE_WAIT_MS` | `1500` | worker 进入解释器前最长等待;超时 → busy |
|
||||
|
||||
建议:
|
||||
|
||||
- 开发机 / 产品默认保持 1–3s。
|
||||
- **禁止**为「让第二个聊天排队」而把默认调到分钟级——那等于恢复卡死。
|
||||
- 需要排队时,应在 **应用层**(会话队列、UI 禁用「再发一条」),而不是拉长宿主锁等待。
|
||||
|
||||
---
|
||||
|
||||
## 6. 与其它机制的边界
|
||||
|
||||
| 机制 | 与 INVOKE_LOCK 的关系 |
|
||||
|------|----------------------|
|
||||
| `MARQDO_EVENT_FORWARD` | SSE 期间写 NDJSON;不替代争锁;不延长等待 |
|
||||
| `MARQDO_CANCEL_TOKEN` | 断开连接时可取消 LLM;释放锁仍取决于解释器何时回到 FFI |
|
||||
| `web.serve` / 静态资源 | 通常不经 `call_lib_path`,不受本锁影响 |
|
||||
| 插件内部 Tokio/Go 并发 | 可以;只要不再次 `call_lib_path` 进同一 HostContext |
|
||||
|
||||
---
|
||||
|
||||
## 7. 演进检查清单(根治前勿宣称「已支持并行 Endpoint」)
|
||||
|
||||
- [ ] 多 `HostContext` 或 isolate 的生命周期与 ABI(装载、shutdown、写回冲突)有设计稿与金样例。
|
||||
- [ ] 池化后 `call_lib_path` 不再依赖进程级单锁,或锁粒度降到实例级。
|
||||
- [ ] 两个并发长 SSE + 一个短 `/v1/models` 的压力测试:短请求稳定 200,长请求互不污染会话写回。
|
||||
- [ ] 更新本文件与 ADR 0008 Status(例如改为 Superseded by ADR NNNN)。
|
||||
|
||||
在清单完成前,对外与文档中应明确:**Marqdo Web Endpoint 求值在单进程内串行;HTTP 层并发,解释器层单飞。**
|
||||
+26
-1
@@ -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
|
||||
|
||||
@@ -0,0 +1,256 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 库开发指南:源码即手册,手册即 SKILL,函数即工具
|
||||
description: 标准库与拓展库的叙述式开发规范,包含可以直接调用的真实示例。
|
||||
import:
|
||||
文件: lib/文件.mq.md
|
||||
---
|
||||
|
||||
库开发指南:让说明、调用和实现长在同一份源码里。
|
||||
|
||||
本文件供人和 AI 开发标准库、拓展库时直接阅读。目标是把库文件交给一个没有读过
|
||||
完整语法手册的模型,它仍能判断何时使用、提供哪些输入、如何调用、如何消费结果,
|
||||
以及遇到失败时怎么办。完成这些任务所需的信息必须在库文件中,不依赖聊天历史、
|
||||
隐藏提示词、另一份签名清单或模型猜测。修改实现所需的最少标记也在本文就地示范。
|
||||
|
||||
这份指南本身可以执行。下方三个函数分别演示句中计算、结构化数据和可恢复文件读取;
|
||||
它们返回真实结果,不返回“已遵守规范”之类的固定通过标志。直接使用的命令为:
|
||||
|
||||
```sh
|
||||
marqdo call doc/library-development.mq.md 计算金额 单价=12 数量=3 --json
|
||||
marqdo call doc/library-development.mq.md 形成订单摘要 '商品="笔记本"' 单价=12 数量=3 --json
|
||||
marqdo call doc/library-development.mq.md 尝试读取正文 '路径="doc/library-development.mq.md"' --effects fs.read --fs-root . --json
|
||||
```
|
||||
|
||||
第一条返回 36,第二条返回商品为笔记本、数量为 3、金额为 36 的记录。
|
||||
第三条返回包含本文源码的成功结果记录。需要读写权限的工具必须给出授权命令及路径基准;
|
||||
纯计算不要求插件、网络或文件授权。读到一个工具时,读者应该能直接复制其真实命令。
|
||||
|
||||
---
|
||||
|
||||
一、先确定文件承担的任务。
|
||||
|
||||
标准库通常是一份 lib/名称.mq.md:这个单文件本身就是手册和 SKILL,直接导入或调用。
|
||||
不要为了文档另造一个 index、目录包装函数或同名模块手册。文件开头写清用途、适用范围、
|
||||
输入来源、权限、运行环境、共享数据形态和一个真实工作流;每个函数再就地说明自己的契约。
|
||||
|
||||
拓展库需要多个文件时,以 index.mq.md 为入口组织工程。入口要说明先读什么、任务在哪个
|
||||
模块、依赖怎样安装或准备、有哪些可运行流程,以及新能力应该加在哪里。
|
||||
子目录有独立职责和多个文件时,也用自己的 index.mq.md 收拢接口与开发路线;
|
||||
叶子只有一个文件时直接使用该文件,不为空目录层级继续增加入口。
|
||||
中文镜像遵守已有命名约定,并说明其与英文模块的对应关系。
|
||||
|
||||
下面只是目录组织示意,不是已经存在、可以直接调用的拓展包:
|
||||
|
||||
```text
|
||||
ext/sample/
|
||||
index.mq.md 任务导航、安装和权限、主流程、公开门面、开发路线
|
||||
core.mq.md 单一职责的纯计算;本文件自身就是手册
|
||||
parse/
|
||||
index.mq.md 解析任务入口,组合本目录的格式能力
|
||||
markdown.mq.md Markdown 叶子能力,保留可独立调用的契约
|
||||
csv.mq.md CSV 叶子能力
|
||||
examples/
|
||||
workflow.mq.md 使用公开 API 的完整业务流程
|
||||
tests/
|
||||
acceptance.mq.md 工程自有的可执行验收场景
|
||||
```
|
||||
|
||||
入口沿用公开能力进行组合,避免复制一份底层实现。索引中的路径和命令必须可用,
|
||||
还要说明输入与产物怎样跨步骤传递,而不只是列文件名。工具 schema、签名和效应由现有
|
||||
编译器、call、catalog、MLSP 从源码投影,不另建一套由作者同步维护的工具协议。
|
||||
本指南也无需安装为另一套 SKILL 包;开发者或 AI 读这份源码即可使用其中的规范与示例。
|
||||
|
||||
---
|
||||
|
||||
二、标题下面立即交代参数与返回。
|
||||
|
||||
每个真正可调用的函数使用函数标题。紧接标题先写参数表,再写返回表;没有参数时直接
|
||||
放返回表。表格必须位于第一条执行语句之前。正文中的普通小节使用说明段和分隔线,
|
||||
不要把“安装说明”“注意事项”等叙述标题误做成空函数。
|
||||
|
||||
参数表逐项写名称、类型、默认值和含义。含义应包含输入来源、数据形态、单位、索引基数、
|
||||
是否允许为空及必要限制,而非“运行时参数”或把参数名复述一次。返回表写实际值的类型、
|
||||
字段和含义,指出是新集合、文件路径、句柄、普通值还是可恢复结果,并说明失败出口。
|
||||
正文进一步解释这些约束的原因与处理方式,不能把关键边界埋到另一个文件才找得到。
|
||||
|
||||
新库用正文中的叙述形参,不保留旧的加号形参清单。参数表提供类型契约和说明,
|
||||
不是另一套参数声明器:名称、顺序和默认值要与正文和实际实现一致。
|
||||
有默认值的形参在正文首次声明时紧跟等号,文本默认值加完整引号;无默认值的输入
|
||||
必须由调用方提供。下面的真实函数展示完整排版,不需要先学另一份模板语法。
|
||||
|
||||
---
|
||||
|
||||
三、先把函数写成能读懂的文章,再让必要部分执行。
|
||||
|
||||
每个函数单元的叙述比例超过 50%,整份文件也保持说明充分。目的、适用条件、步骤之间
|
||||
的因果、数据含义、返回去向和失败处理都属于有用叙述。不要用重复套话、巨型契约表、
|
||||
无关背景或在文件头堆文章来掩盖某个函数仍然难读。短实现也需要说明为什么这样做。
|
||||
|
||||
检查按每个真实函数单元分别计算,契约表与说明文字属于叙述;绑定的数据表与代码围栏
|
||||
属于实现。句中粗体、返回表达式和遮蔽圆括号中的代码仍计入代码,方括号中的动作说明
|
||||
计入叙述。因此把整段代码搬进一句话,并不会把它全部变成说明文字。比例只是最低门槛,
|
||||
还应逐段检查输入来源、分支理由、失败出口与可执行示例。
|
||||
|
||||
尽量让语句成为句子的组成部分。粗体标记执行赋值、调用或表达式;单斜体标记返回。
|
||||
例如,下方计算金额函数在解释金额来源的句子中完成赋值,在交代用途的句子中返回结果。
|
||||
先读句子能够理解意图,展开其中的精确表达式又能看清实际执行的代码。
|
||||
|
||||
使用当前已支持的句中返回写法:`完成上述操作后,我们返回*结果*,供调用方继续使用。`
|
||||
其中“返回”直接引出单斜体。不要把粗体当作返回,也不要假定任意句中出现的单斜体强调
|
||||
都会结束函数。返回立即结束当前函数;同一句后面的文字只能解释,不能安排后续执行动作。
|
||||
讲解标记本身或展示尚不执行的示例时,使用行内代码或未绑定的代码围栏,避免意外执行。
|
||||
|
||||
确实需要单独成块的表格、分支和循环可以保留结构化排版。减少孤立代码的目的在于
|
||||
保留可读因果,而不是把长循环硬塞到一句话里。每个结构块前说明判断或遍历的目的,
|
||||
块内使用清楚的变量名与动作标签,块后说明产物;不要让读者靠追踪临时变量猜流程。
|
||||
|
||||
---
|
||||
|
||||
四、用遮蔽语法把意图和精确实现放在同一处。
|
||||
|
||||
方括号写“要做什么”,圆括号写实际代码。标签应解释领域动作、输入与结果之间的关系,
|
||||
例如“按单价和购买数量计算金额”“在授权根目录读取 UTF-8 正文”,而不是“执行操作”
|
||||
或原样复述宿主函数名。简单算术、取元、库调用和宿主调用都可以按需要使用这种写法。
|
||||
|
||||
下方函数会在叙述中执行赋值,赋值右侧用遮蔽表达式写出动作和实现。返回也可以直接
|
||||
包住一个有说明的表达式;以下围栏只是排版示例,不会在阅读本指南时执行文件操作:
|
||||
|
||||
```markdown
|
||||
读取阶段先**正文 = [读取授权范围内的 UTF-8 文本](文件.读文本(路径=`路径`))**,得到后续使用的内容。
|
||||
读取完成后,我们返回*正文*,供调用方继续处理。
|
||||
```
|
||||
|
||||
如果不需要中间命名,也可以用下面的直接返回替代上面整个过程。二者是两种写法,
|
||||
不是连续执行的两个读取步骤;不要为了叙述或展示再调用一次有副作用的能力。
|
||||
|
||||
```markdown
|
||||
读取阶段直接返回*[读取授权范围内的 UTF-8 文本](文件.读文本(路径=`路径`))*,把内容交给调用方。
|
||||
```
|
||||
|
||||
执行位置很重要:普通正文中的链接样式是叙述引用或导航,单靠写出一个动作标签不会
|
||||
自动执行它。需要执行的表达式应放在赋值、语句、返回等明确的执行位置;
|
||||
不要用一个没有实现的空圆括号假装功能已完成。标签不参与参数求值,也不能证明实现
|
||||
符合描述;修改标签或实现后仍要检查二者是否一致,并执行相关场景。
|
||||
|
||||
---
|
||||
|
||||
五、用表格表达结构,用模块表达职责。
|
||||
|
||||
静态记录、行列表、配置、命令和视图结构优先写成 GFM 表格。一列表达列表,
|
||||
一行多列表达记录;多行多列默认是列式数据,要表达行记录列表时把首列写成 @。
|
||||
调用产生的值先计算并命名,再在单元格中引用,不能假定表格里任意一段函数文本会执行。
|
||||
普通值用列表和记录传递;读取集合使用 access,不能把描述标签误当作集合键。
|
||||
|
||||
不可变更新要保存返回的新值。少量动态键用表库的具名助手;解析与序列化才使用 JSON。
|
||||
不要用长串 json.set/json.append 来拼原本一张表就能读懂的数据,也不要为每个数字或
|
||||
单个字段创建层层转发的空壳函数。只有当一段逻辑需要解释、复用或独立验证时才提取职责。
|
||||
|
||||
网页工程从最小布局拆分开始:首页拆为导航、主体、底部,底部再拆为品牌和链接双栏,
|
||||
链接栏还可拆成文档与社区。一直拆到叶子内部能够用简单 Markdown 表达内容;
|
||||
父模块负责导入、组合与布局,叶子负责内容。使用现有 web 的文档、组件与 View 表能力,
|
||||
让结构与内容保持统一语言,避免大段原生 HTML/CSS、转义字符串和手写业务 JavaScript。
|
||||
|
||||
通用组合优先写在 mq 源码里。仅在 OS、算法或原生 ABI 边界加入小型宿主原语,
|
||||
声明实际效应与资源限制;拓展库通过公开标准库或插件接口使用能力,不直接调用 host_*。
|
||||
中英文镜像保持契约、默认值与行为一致。不要把未来规划写成当前已经可用的接口。
|
||||
|
||||
---
|
||||
|
||||
六、把运行边界和工程验收写在开发者找得到的位置。
|
||||
|
||||
有副作用的能力写明授权、根目录、平台、超时、资源上限以及重试与清理责任。
|
||||
返回可恢复结果时先检查其中的 ok,再读取 value 或 error;CLI 外层的 ok 只说明调用
|
||||
是否完成,不替代函数结果、HTTP 状态或子进程退出码的判断。未知副作用不能声称为纯函数。
|
||||
文件原子替换不等于多文件事务;条件写入也不等于无竞争的内核 CAS。
|
||||
|
||||
文件类示例使用明确的临时根目录,说明产物是否保留、失败是否留下临时文件、由谁清理。
|
||||
需要插件、外部服务或凭据时写明前提,验收优先使用本地可控替身,不把线上写入作为
|
||||
阅读文档的隐含步骤。维护原有库时保留既有调用语义,必要变更要说明迁移路径。
|
||||
|
||||
交付时至少检查四件事:首次读源码能否完成一次真实调用;契约和正文是否一致;
|
||||
叙述是否超过半数且解释了真实行为;正常、边界、错误场景是否返回预期结果。
|
||||
修改源码中的示例时同步执行它们;公共调用面需要兼顾 Tree 和 Bytecode。
|
||||
检查叙述比例是可读性门槛,不是功能正确性的证明,更不能代替业务与失败场景。
|
||||
|
||||
本文件可用以下命令检查。第二条是仓库内的可执行指南验收,覆盖叙述内赋值、
|
||||
默认参数、结构化返回以及可恢复读取;修改库时还应运行该库本身相关的回归。
|
||||
|
||||
```sh
|
||||
marqdo check doc/library-development.mq.md --narrative-ratio
|
||||
cargo test --test stdlib_tasks library_development_guide_examples_match_their_contracts
|
||||
```
|
||||
|
||||
现有能力可直接参考 [文件库](../lib/文件.mq.md)、[表库](../lib/表.mq.md)、
|
||||
[量子工程入口](../ext/quantum/index.mq.md)和[网页工程入口](../ext/web/index.mq.md)。
|
||||
需要了解解析与语义的边界时再阅读[文档原生开发指导](design/document-native-development-guide.md)。
|
||||
以下是真实可调用的单文件示例,也是前面三个命令的实现。
|
||||
|
||||
## 计算金额
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 单价 | number | 必填 | 单件商品的金额;币种由调用方保持一致 |
|
||||
| 数量 | number | 1 | 参与乘法的购买数量;调用方按业务规则校验其范围 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 结果 | number | 单价乘以数量的金额,不含税费、折扣或币种转换 |
|
||||
|
||||
输入单价为`单价`,购买数量`数量`=1,没有指定数量时按一件计算。
|
||||
本示例只演示透明的乘法组合,不暗示商品有效、允许负数交易或具有货币精度保证;
|
||||
需要货币精度时由领域库采用整数最小货币单位,并补充其单位和范围约束。
|
||||
|
||||
为得到这笔购买的基础金额,我们先**结果 = [按单价和购买数量计算金额](单价 * 数量)**,
|
||||
后续说明仍留在同一段落,使读者无需从一条孤立赋值反推它的业务目的。
|
||||
|
||||
完成上述计算后,我们返回*结果*,调用方可以继续计算税费、折扣或生成订单摘要。
|
||||
|
||||
## 形成订单摘要
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 商品 | text | 必填 | 调用方提供的商品显示名称;此函数不查商品库 |
|
||||
| 单价 | number | 必填 | 与数量相乘的单件金额,币种与调用方约定 |
|
||||
| 数量 | number | 1 | 购买数量,默认一件;业务校验由调用方完成 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 摘要 | map | 商品、数量、金额三个字段组成的新记录 |
|
||||
|
||||
本函数接收商品名`商品`、单件金额`单价`以及购买数量`数量`=1,
|
||||
只生成供下一步展示或保存的数据,不会下单、扣款、写文件或访问外部服务。
|
||||
因此调用者可以在纯计算权限下验证完整的数据组合过程。
|
||||
|
||||
我们复用同一文件的计算能力,先**金额 = [计算本次购买的基础金额](计算金额(单价=`单价`, 数量=`数量`))**,
|
||||
避免在订单摘要中再维护一份乘法规则。接着将需要交给调用方的字段直接列成记录,
|
||||
让阅读者能逐项看到商品名称、数量和金额从哪里来,而无需解码字典构造链。
|
||||
|
||||
`摘要` =
|
||||
|
||||
| 商品 | 数量 | 金额 |
|
||||
|---|---|---|
|
||||
| `商品` | `数量` | `金额` |
|
||||
|
||||
表格中的反引号引用已经得到的值,未增加一层隐式求值。字段准备好后,我们返回*摘要*,
|
||||
调用方可以把它交给其他库继续展示或序列化;本函数不会修改传入的值。
|
||||
|
||||
## 尝试读取正文
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 路径 | text | 必填 | 授权文件根目录内的 UTF-8 文件路径;不是相对本指南的导航链接 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 读取结果 | map | ok/value/error 记录;成功的 value 是正文,失败的 error 含 code/message/operation |
|
||||
|
||||
输入文件`路径`由调用者提供,执行时需要 fs.read,路径以 --fs-root 为基准;
|
||||
省略根目录时采用被调用文件的目录。本函数复用文件库的有界读取,不能绕过根目录、
|
||||
编码检查或资源上限。此例不执行读到的代码,也不从正文推断额外的文件访问权限。
|
||||
|
||||
为了让一次读取失败仍能作为数据交给下一步,我们先**读取结果 = [在授权范围读取 UTF-8 正文并保留失败信息](文件.尝试读文本(路径=`路径`))**,
|
||||
由公开文件库统一处理已定义的可恢复失败,而不是在此复制宿主 IO 或假造成功文本。
|
||||
|
||||
读取结束后,我们返回*读取结果*,调用者先检查记录中的 ok,再使用 value 或 error。
|
||||
失败记录只说明这次操作没有成功;它不会捕获任意语言错误,也不会替调用者授予权限。
|
||||
+576
@@ -0,0 +1,576 @@
|
||||
# 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 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。
|
||||
|
||||
# Marqdo 可执行知识体系:设计规范与完整范例
|
||||
|
||||
我已经基于 Marqdo 当前仓库的语法规范、`[]()` 设计、知识分层、对象模型和 EKC,整理了两份详细文档。
|
||||
|
||||
这次设计保留了你的原始理念:
|
||||
|
||||
> 代码即文档,文档即知识库,知识即可执行。
|
||||
|
||||
核心目标不是让 AI 更容易生成 Marqdo 代码,而是让 AI 尽可能不必重新生成已经存在的知识,转而通过编译器确定性地发现、引用、验证和执行既有知识。
|
||||
|
||||
第一份:完整架构设计规范
|
||||
|
||||
涵盖语义制品、知识引用、编译器架构、解析优先级、效应安全、版本管理、EKC 集成、Agent 复用协议和实施验收。
|
||||
|
||||
阅读设计文档
|
||||
|
||||
第二份:多文件可执行知识范例
|
||||
|
||||
以虚构书店定价为例,从原始政策文档开始,逐步构造知识定义、对象、计算能力、业务入口、AI 问答、知识复用和错误验证。
|
||||
|
||||
阅读完整示例
|
||||
|
||||
两份文档打包
|
||||
|
||||
下载 ZIP
|
||||
|
||||
## 一、这份设计最重要的三个决定
|
||||
|
||||
# Marqdo 可执行知识体系:核心设计纲领
|
||||
|
||||
**核心理念:代码即文档,文档即知识库,知识即可执行。**
|
||||
|
||||
## 1. 知识是可编译的语义制品
|
||||
|
||||
文档经过 Marqdo 编译器处理后,不只产生可执行逻辑,还应产生具有稳定身份、类型、签名、契约、依赖关系、来源和验证状态的语义制品(Semantic Artifact)。
|
||||
|
||||
知识可以表现为事实、函数、能力、约束、数据集或类型。它们无需全部被强制编码为类。
|
||||
|
||||
## 2. `[]()` 是知识使用的统一入口
|
||||
|
||||
`[描述](目标)` 保留 Markdown 的可读性。
|
||||
|
||||
- `[]` 面向人类,描述意图、意义或用途。
|
||||
- `()` 面向编译器,包含既有 Marqdo 表达式或者可解析的知识目标。
|
||||
- 描述不改变执行结果,也不能作为可信性依据。
|
||||
- 编译器负责将目标解析为确定的符号身份,并验证使用条件。
|
||||
|
||||
既支持隐藏不易阅读的代码,也支持引用已经编译的知识。
|
||||
|
||||
## 3. AI 复用知识,而不是重新解释知识
|
||||
|
||||
AI 面对新任务时,应该遵循:
|
||||
|
||||
**Discover → Resolve → Verify → Reuse → Execute → Trace**
|
||||
|
||||
当知识缺失或不适用时,才进入 ADAPT 或 CREATE 流程。
|
||||
|
||||
检索可以模糊,但最终绑定必须确定。验证必须区分程序可执行性、契约符合性和现实事实正确性。
|
||||
|
||||
## 4. 编译器是知识系统的基础
|
||||
|
||||
AST、Semantic IR、符号索引、链接关系和知识验证应当由同一套语义体系产生。
|
||||
|
||||
解释器、字节码 VM、View、EKC 和 Agent 消费统一的编译结果,而不是各自重新解析文档。
|
||||
|
||||
## 5. 最终验收标准
|
||||
|
||||
一个 AI 能够发现现有知识、确定其身份、检查适用条件、直接执行既有能力、引用结果和来源,并在知识发生变化时识别受影响的调用者。
|
||||
|
||||
只有这条链条成立,Marqdo 才真正实现知识的可执行复用。
|
||||
|
||||
## 二、示例将展示什么
|
||||
|
||||
我选择了一个具有明确规则和复用价值的业务案例,而不只是使用“李白出生年份”这样的静态事实。
|
||||
|
||||
用户购买两件单价 60 元的商品,金卡折扣为 90%,满 100 元免运费。
|
||||
|
||||
AI 要处理的业务请求
|
||||
|
||||
> 请计算这笔金卡订单的最终应付款,并解释依据。
|
||||
|
||||
传统路径
|
||||
|
||||
检索政策 → AI 阅读规则 → 重新推导计算 → 生成新代码或答案
|
||||
|
||||
Marqdo 目标路径
|
||||
|
||||
发现定价能力 → 绑定已编译函数 → 检查输入与政策 → 执行 → 引用结果
|
||||
|
||||
目标语法示意(v2.1+,不是 v2.0.0 实测)
|
||||
|
||||
```
|
||||
**应付 = [订单最终应付款](定价.计算应付金额(60, 2, "金卡"))**
|
||||
```
|
||||
|
||||
根据演示政策计算
|
||||
|
||||
# ¥108
|
||||
|
||||
这套例子进一步展示了参数和返回值、类与继承、表格、条件分支、循环、跨文档调用、自然语言遮蔽,以及知识来源改变时的影响分析。
|
||||
|
||||
## 三、与当前版本的兼容边界
|
||||
|
||||
我特别保留了一个重要区分:设计目标不等于当前已经实现的功能。
|
||||
|
||||
根据这次读取的仓库内容,v2.0.0 已支持本地表达式遮蔽、对象、方法、控制流、表格集合、导入以及现有 EKC 基础;但无实例类函数调用、跨文档知识自动解析、完整 LinkInfo 和语义制品绑定仍需要进一步开发。
|
||||
|
||||
因此示例文档明确标注了目标语法和现有兼容写法,没有将尚未验证的代码描述为已经跑通。
|
||||
|
||||
## 四、我的主要架构建议
|
||||
|
||||
我认为接下来的开发不应该从 `[]()` 的外观继续扩展,而应该先实现:
|
||||
|
||||
统一符号索引 → 稳定知识身份 → 引用绑定 → 契约验证 → EKC 复用。
|
||||
|
||||
还有一点值得特别强调:我不赞成为了建立知识系统,再单独实现一个与 Marqdo 解释器并列的“知识编译器”。那样会重新制造你希望消除的表示碎片。
|
||||
|
||||
更合适的架构是让现有 Marqdo 编译管线产出统一的语义中间表示,然后由运行时、View、EKC 和 Agent 各自消费。
|
||||
|
||||
这意味着 Marqdo 的知识体系不是一个外挂的 RAG 框架,而是语言本身的语义能力。
|
||||
|
||||
我认为这才是整个设计中最值得投入资源,也最有可能形成独立研究贡献的部分。
|
||||
+374
@@ -0,0 +1,374 @@
|
||||
请你重新阅读marqdo的官方库,掌握marqdo的最新进度。在我对marqdo项目的仔细审视之下我发现有一点没有闭环,我终于找到了,考虑现在智能体开发最常用的SKILL,这是一个markdown文件写明了智能体该干什么,我想要更推荐一步,因为marqdo使用markdown语法,支持叙述和代码相互混合,这就使得marqdo满足这样一个条件,当分章节的SKILL撰写下来,只要经过调整就能成为一份marqdo代码其中包含若干函数,我打算开发新的CLI命令marqdo > 函数名 函数参数或者marqdo call 函数名 函数参数 此时SKILL的不同章节就变成了不同的函数,智能体就真正的成为了将知识复现的作用,这让代码即文档、文档即知识,知识即可执行推进了一步变成了知识即工具,真正发挥了marqdo的优势,同样这样的执行还以为着智能体能够自行改进SKILL并接受确定的问题后修改而不会出错,这让自我进化的智能体成为了具备理论支撑和清晰边界的可能
|
||||
|
||||
# Marqdo 从“可执行知识”走向“知识即工具”:最新仓库审查与架构建议
|
||||
|
||||
我认为你这次找到了 Marqdo 一个非常重要、而且比单纯增加 `marqdo call` 命令更深层的突破口。
|
||||
|
||||
你实际上提出了一个新的统一关系:
|
||||
|
||||
> SKILL 是人和 AI 都能阅读的操作知识;Marqdo 可以让其中具有确定性执行语义的章节,直接成为可调用的工具。
|
||||
|
||||
这样,Agent 的职责就有机会从“阅读说明、理解步骤、临时生成实现”,转向“定位已有能力、填入参数、执行和验证结果”。
|
||||
|
||||
这与 Marqdo 原来的三句话是连续的,不需要推翻原来的定位:
|
||||
|
||||
代码即文档 → 文档即知识库 → 知识即可执行 → 知识即可作为工具使用。
|
||||
|
||||
不过我建议把“知识即工具”视为可执行知识的对外使用形态,而不是再创造一套与语言、知识库平行的 Skill 运行系统。
|
||||
|
||||
## 一、重新检查仓库后的最新情况
|
||||
|
||||
本次核对的是 [cflmy/marqdo](https://github.com/cflmy/marqdo?utm_source=chatgpt.com) 的 `main` 分支,HEAD 为 `4018e992`,`Cargo.toml` 版本为 2.1.5。最近的 v2.1.5 版本记录日期是 2026 年 10 月 27 日。
|
||||
|
||||
与我们之前讨论 v2.0.0 时相比,项目已经完成了不少与你的构想直接相关的基础建设。
|
||||
|
||||
| 相关能力 | 最新仓库证据 | 判断 |
|
||||
| --------------------- | ---------------------------------------------------------------- | -------- |
|
||||
| 跨文档确定性函数绑定 | `BoundCall`、`SymbolId`,Tree/Bytecode 双后端测试 | 已有核心基础 |
|
||||
| 已编译知识的执行复用 | MLSP `artifact.bind`、`artifact.execute`、`artifact.reuse_execute` | 已有子集 |
|
||||
| Agent 复用已有函数 | `agent_eng_bind_execute`、发布门禁 | 已有子集 |
|
||||
| 指定函数执行 | `marqdo run --call-lib-path`、JSON 参数、隔离 worker | 已有底层入口 |
|
||||
| 智能体工具规范 | `ToolSpecV1`、效应分类、权限检查与恢复设计 | 已有框架基础 |
|
||||
| 章节式 SKILL 自动成为 CLI 工具 | 目前没有独立的 `marqdo call` 或 Skill 编译命令 | 待开发 |
|
||||
| SKILL 自修改、自动测试和受控发布 | 已有局部修改、验证与沙盒组件 | 尚未形成完整闭环 |
|
||||
|
||||
因此,现在不是重新开发一个 Skill 执行器,而是将已存在的 Marqdo 函数、知识制品、工具协议和 Agent 机制统一起来。
|
||||
|
||||
还有一个与你的新构想直接相关的问题值得先修复:
|
||||
|
||||
最新官方 `skills/marqdo/SKILL.md` 的核心语法说明,与仓库中的现行解析器、v0.3 语法规范和可执行测试存在冲突。
|
||||
|
||||
目前解析器与测试使用的是:
|
||||
|
||||
- `**…**`:代码、赋值、调用等语句;
|
||||
- `*…*`:返回值。
|
||||
|
||||
但官方 Skill 顶部却把两者反过来描述。这不是小的文档笔误:如果 Agent 按照错误规则自我修改 Skill,就可能产生与实际运行时不一致的程序。
|
||||
|
||||
这个真实存在的不一致,恰好证明了你所说的闭环为什么重要——SKILL 不能仅靠自然语言说明自己的正确性,它需要由语言编译器和实际测试提供独立验证。
|
||||
|
||||
## 二、你真正提出的是一种新的 Skill 体系
|
||||
|
||||
我建议把它暂时命名为 Executable Skill(可执行技能)。
|
||||
|
||||
它不应被理解为“给 Markdown Skill 增加一点代码”,而应当满足一个更严格的定义:
|
||||
|
||||
> Executable Skill 是一份以 Markdown 为人类可读接口、以 Marqdo 函数为确定性执行单元、以编译后的语义制品为工具身份、能够由 Agent 发现、调用、验证和改进的技能文档。
|
||||
|
||||
传统 Skill 与你的目标之间,存在一个非常重要的区别。
|
||||
|
||||
| 维度 | 普通 Markdown Skill | Marqdo Executable Skill |
|
||||
| ---- | ----------------------- | ----------------------- |
|
||||
| 技能说明 | 自然语言 | 自然语言 |
|
||||
| 操作步骤 | Agent 阅读后自行实施 | 可以绑定已有 Marqdo 函数 |
|
||||
| 函数接口 | 通常需要额外编写工具代码 | 从 `.mq.md` 的函数和契约生成 |
|
||||
| 执行 | 依赖 Agent 选择工具、生成代码或操作软件 | 对已实现的步骤直接执行 |
|
||||
| 输出验证 | 往往需要单独建立 | 可连接编译器、契约和测试 |
|
||||
| 改进 | 编辑说明或脚本 | 编辑同源的知识与实现,验证后发布 |
|
||||
| 可追踪性 | 主要依赖工具日志 | 可关联 SymbolId、源码、版本和执行结果 |
|
||||
|
||||
但不是每个 Skill 章节都应该自动变成可执行函数。
|
||||
|
||||
比如“适用场景”“注意事项”“禁止操作”是知识或约束;“检查订单”“生成报价”“汇总报告”才可能成为可调用能力。编译器应区分文档章节与可执行章节,不能把所有二级标题不加判断地暴露成工具。
|
||||
|
||||
### 这实际上使 Agent 的结构发生变化
|
||||
|
||||
SKILL.md
|
||||
|
||||
目标 · 流程 · 函数 · 契约 · 示例 · 约束
|
||||
|
||||
Marqdo Skill Compiler
|
||||
|
||||
章节解析 · 符号绑定 · 类型检查 · 效应分析
|
||||
|
||||
Knowledge View
|
||||
|
||||
Agent 阅读技能与限制
|
||||
|
||||
Tool Registry
|
||||
|
||||
Agent 调用已编译函数
|
||||
|
||||
Agent:选择、组合、执行、观察与改进
|
||||
|
||||
由语言运行时执行确定性部分,由模型处理非确定性判断
|
||||
|
||||
特别值得注意的是:这不仅是执行接口的统一,还是知识交付接口的统一。
|
||||
|
||||
同一份 Skill 能够投影成可读说明、CLI 函数、Agent Tool Schema、MCP 工具描述,以及知识库中的能力节点。实现这些投影的系统仍是同一个 Marqdo 编译器。
|
||||
|
||||
## 三、CLI 应采用 `marqdo call`,不要采用 `marqdo >`
|
||||
|
||||
你提出了两个命令形式:
|
||||
|
||||
```
|
||||
marqdo > 函数名 函数参数
|
||||
marqdo call 函数名 函数参数
|
||||
```
|
||||
|
||||
我明确建议采用第二种。
|
||||
|
||||
原因是 `>` 在 Bash、PowerShell、CMD 等 Shell 中已经具有输出重定向语义。`marqdo > xxx` 会被 Shell 先行解释,无法可靠地作为传递给 Marqdo 的函数调用语法。
|
||||
|
||||
推荐设计为:
|
||||
|
||||
```
|
||||
# 按函数名调用
|
||||
marqdo call "订单计算.商品小计" \
|
||||
--skill ./skills/order-calculator \
|
||||
--arg 单价=30 \
|
||||
--arg 数量=2
|
||||
|
||||
# 结构化调用,供 Agent 使用
|
||||
marqdo call "订单计算.商品小计" \
|
||||
--skill ./skills/order-calculator \
|
||||
--args-json inputs.json \
|
||||
--output json \
|
||||
--policy pure
|
||||
```
|
||||
|
||||
上述是建议新增的 CLI 接口,不是 v2.1.5 已支持的命令。
|
||||
|
||||
我还建议在 CLI 层保留一个便利别名:`marqdo skill call`。它与 `marqdo call` 进入同一个 dispatcher,不应分别实现两套调用逻辑。
|
||||
|
||||
### 最小必要的 CLI 能力
|
||||
|
||||
| 命令 | 作用 |
|
||||
| ---------------------------- | ----------------------- |
|
||||
| `marqdo skill inspect PATH` | 解析 Skill 文档、章节、可调用函数和依赖 |
|
||||
| `marqdo skill list PATH` | 列出对 Agent 暴露的工具 |
|
||||
| `marqdo skill check PATH` | 检查语法、绑定、签名、效应和工具导出规则 |
|
||||
| `marqdo call TARGET` | 调用指定 Marqdo 函数并返回结果 |
|
||||
| `marqdo skill test PATH` | 执行 Skill 的测试与契约检查 |
|
||||
| `marqdo skill export PATH` | 生成通用工具描述或 MCP 暴露接口 |
|
||||
| `marqdo skill trial PATH` | 对修改后的候选版本进行隔离验证 |
|
||||
| `marqdo skill promote PATH` | 在门禁通过后发布新版本 |
|
||||
| `marqdo skill rollback PATH` | 恢复到指定已接受版本 |
|
||||
|
||||
不过不建议一次性实现这九项命令。最小可用产品只需要 `inspect`、`call`、`check`、`test` 四项,版本发布与改进机制可以随后补齐。
|
||||
|
||||
最重要的技术决策是:
|
||||
|
||||
`marqdo call` 必须调用现有编译器绑定的函数,不得重新用字符串搜索源码、猜测章节位置再执行。
|
||||
|
||||
当前 [src/mlsp.rs](https://github.com/cflmy/marqdo/blob/main/src/mlsp.rs?utm_source=chatgpt.com) 已有 `artifact.bind` 与 `artifact.execute`,能够检查制品指纹、依赖闭包、来源摘要和效应策略。新的 CLI 应复用相同的应用服务和语义校验,而不是通过进程内调用 MLSP JSON 接口制造另一层重复协议。
|
||||
|
||||
还有一个现有实现细节:`marqdo run --call-lib-path` 已支持隔离 worker 通过 JSON 参数调用函数,但当前 `src/lib.rs` 的这个入口只在树遍历分支中处理,Bytecode 分支仍按普通程序入口执行。新的公开 `call` 命令需要补齐这一差异,或者明确在第一版只支持 Tree backend,不能静默忽略所选后端。
|
||||
|
||||
## 四、完整示例:让一份 Skill 同时成为文档、知识和工具
|
||||
|
||||
我建议第一版尽量保持作者体验简单:人只维护一份 Markdown 源文件,编译器自动生成工具描述、函数索引和知识制品。
|
||||
|
||||
例如,我们建立一个订单计算 Skill。
|
||||
|
||||
下面是目标设计示例。其中 `runtime` 和 `tools` 是我建议为 Skill 编译增加的元数据约定,目前不能将这份 `SKILL.md` 直接交给 v2.1.5 的 CLI,期待自动注册工具。
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
name: order-calculator
|
||||
description: 订单价格计算,包括商品小计和含税金额
|
||||
runtime: marqdo
|
||||
tools:
|
||||
- 订单计算.商品小计
|
||||
- 订单计算.含税金额
|
||||
---
|
||||
|
||||
# 订单计算
|
||||
|
||||
这份技能用于计算订单金额。
|
||||
|
||||
所有金额使用同一货币单位。税率使用小数表示,
|
||||
例如 0.10 表示 10%。
|
||||
|
||||
## 商品小计
|
||||
|
||||
给定商品单价`单价`和购买数量`数量`,
|
||||
计算未税商品小计。
|
||||
|
||||
*[商品小计](单价 * 数量)*
|
||||
|
||||
## 含税金额
|
||||
|
||||
给定商品单价`单价`、购买数量`数量`
|
||||
和适用税率`税率`,计算含税金额。
|
||||
|
||||
**小计 = [计算商品小计](订单计算.商品小计(单价=单价, 数量=数量))**
|
||||
|
||||
*[最终含税金额](小计 * (1 + 税率))*
|
||||
|
||||
```
|
||||
|
||||
这里的计算是演示规则。正式业务技能还需要校验数量范围、金额精度、货币单位、税率适用条件与舍入规则;这些不能由函数名字自动推断为正确。
|
||||
|
||||
### 这份 Skill 会产生三种投影
|
||||
|
||||
给人阅读: 它是一份正常的 Markdown 文档。读者能理解每个步骤的目的,以及所需输入和返回值。
|
||||
|
||||
给 Marqdo 编译器: 两个 `##` 单元构成可解析的函数;第二个函数可以确定性地调用第一个函数;符号索引能够记录它们的依赖关系。
|
||||
|
||||
给 Agent 使用: 编译器输出两个工具的结构化描述。Agent 不需要重新生成乘法计算程序,只需选择工具并提供参数。
|
||||
|
||||
例如,编译后的工具描述可以是:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "order-calculator::订单计算.商品小计",
|
||||
"description": "计算未税商品小计",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"单价": {"type": "number"},
|
||||
"数量": {"type": "number"}
|
||||
},
|
||||
"required": ["单价", "数量"]
|
||||
},
|
||||
"output_schema": {
|
||||
"type": "number"
|
||||
},
|
||||
"effect": "pure"
|
||||
}
|
||||
```
|
||||
|
||||
但这个 Schema 必须由明确的类型契约和编译器检查生成。若源文件没有足够的类型信息,应标记为未知或要求补全,不能因为变量参加了乘法就无条件断言它一定是 `number`。
|
||||
|
||||
需要强调:不是 `##` 标题自动等于一个公开工具。 `##` 让章节具备 Marqdo 函数的结构,`tools` 则声明哪些函数允许对外暴露。这样才能避免“安全说明”一类章节被意外注册成工具,也避免内部辅助函数被 Agent 随意调用。
|
||||
|
||||
### 为什么采用显式的 `runtime: marqdo`?
|
||||
|
||||
因为普通 Skill 的 Markdown 本来就可能包含 `**加粗内容**`、编号列表、代码块和二级标题。这些在现有 Marqdo 中可能具有执行语义。
|
||||
|
||||
如果直接把所有 `SKILL.md` 当成 `.mq.md` 执行,很可能发生严重的语义误读。
|
||||
|
||||
所以我建议:
|
||||
|
||||
- 未明确声明 Marqdo 运行时的 `SKILL.md`,仍然是普通 Markdown 文档。
|
||||
- 明确声明 `runtime: marqdo` 的 Skill 才进入 Marqdo 编译流程。
|
||||
- 内嵌示例代码块不应因展示而执行。
|
||||
- 编辑器应对具有执行意义的 Markdown 标记提供可视化提示。
|
||||
- 导出的工具必须经过独立检查和授权。
|
||||
|
||||
未来还可以支持从已有普通 Skill 中自动提取候选函数,但那应当是生成可审阅的转换补丁,而不是默认把自然语言步骤当成已经实现的代码。
|
||||
|
||||
## 五、这次最有价值的部分:自我改进的 Skill
|
||||
|
||||
你提出的第二层意义,我认为甚至比 `marqdo call` 更值得研究。
|
||||
|
||||
传统 Agent 修改一个 Skill 时,常见问题是:它修改了一段说明或脚本,却无法可靠判断其他步骤是否受到影响。
|
||||
|
||||
Marqdo 已经具备一些适合解决这个问题的基础,例如 `SymbolId`、依赖闭包、`artifact.patch`、`artifact.verify` 和知识影响分析。
|
||||
|
||||
但是,不能由此推出“智能体修改 Skill 就不会出错”。
|
||||
|
||||
更精确的目标是:智能体可以提出改进,系统能够判定一组明确、可测试的性质是否被保持,并且只有通过门禁的版本才有资格替换原有 Skill。
|
||||
|
||||
我建议采用以下演化协议:
|
||||
|
||||
已发布 Skill v1
|
||||
|
||||
现有稳定版本与完整依赖
|
||||
|
||||
1\. 发现确定的问题
|
||||
|
||||
失败测试、诊断、复现步骤或用户提出的明确修改要求
|
||||
|
||||
2\. AI 生成局部修改候选
|
||||
|
||||
只修改获准的章节或函数,记录版本与修改意图
|
||||
|
||||
3\. 编译与静态验证
|
||||
|
||||
语法、符号、参数、返回类型、效应、依赖关系
|
||||
|
||||
4\. 隔离测试与回归验证
|
||||
|
||||
目标问题修复、历史行为保持、异常输入、性能与权限边界
|
||||
|
||||
5\. 发布门禁
|
||||
|
||||
仅当策略允许且必要验证通过时晋升新版本;否则保留旧版本
|
||||
|
||||
Skill v2 · 已接受版本
|
||||
|
||||
可追溯、可回滚、后续调用绑定到明确版本
|
||||
|
||||
### 举一个真正的自我改进案例
|
||||
|
||||
原 Skill 中存在:
|
||||
|
||||
```
|
||||
## 商品小计
|
||||
|
||||
商品单价`单价`,购买数量`数量`。
|
||||
|
||||
*[小计](单价 * 数量)*
|
||||
```
|
||||
|
||||
现在发现一个确定的问题:输入 `数量=-1` 时,函数返回负数,但业务要求数量必须大于零。
|
||||
|
||||
Agent 不应该只是把说明修改成“数量必须大于零”。这不会改变执行行为。
|
||||
|
||||
它应当在候选版本中增加可执行的校验逻辑,并补充至少三个测试:
|
||||
|
||||
| 测试 | 输入 | 期望 |
|
||||
| ---- | ----------- | ------------- |
|
||||
| 正常订单 | 单价 30,数量 2 | 返回 60 |
|
||||
| 非法数量 | 单价 30,数量 -1 | 返回结构化参数错误 |
|
||||
| 边界数量 | 单价 30,数量 0 | 根据业务契约决定接受或拒绝 |
|
||||
|
||||
如果 Marqdo 尚不具备合适的语言级错误返回或异常处理方式,这个案例还会暴露一个语言能力缺口:需要一种由 Marqdo 程序自身构造、传递和处理错误的机制,而不是只能依赖 Rust 宿主报错。
|
||||
|
||||
这与此前我们讨论的通用语言能力重构是直接关联的。
|
||||
|
||||
### 自我进化的边界必须比普通代码修改更严格
|
||||
|
||||
我建议把以下约束固定下来:
|
||||
|
||||
1. 修改不能自动扩大权限。 原 Skill 只有纯计算权限,新版本不能因为 Agent 自己添加网络或文件操作就获得这些权限。
|
||||
2. 候选版不能直接覆盖运行中的正式版本。 需要隔离工作区、原子发布和固定引用版本。
|
||||
3. 必须证明目标问题被修复。 不允许通过删除测试、放宽断言或隐藏失败来宣称成功。
|
||||
4. 测试通过不是绝对正确的证明。 未覆盖的业务情况、外部事实和依赖服务仍可能出错。
|
||||
5. 高风险修改需要更严格的发布决策。 尤其是支付、外部写入、删除、凭证和安全策略变更,不能由被修改的 Skill 自己批准。
|
||||
|
||||
最新仓库的 `artifact.patch` 已经提供基于摘要的修改和有限回滚,但它还不是完整的候选版本事务与测试后晋升系统。现有 `HostCaps` 的默认值也允许文件写入、执行、网络和插件,因此新 `call` 的安全默认值应当收紧,不能简单继承普通本地运行的全部宿主权限。
|
||||
|
||||
这就是“有界自我进化”的含义:不保证 Agent 永不犯错,而是让它能够在可验证、可回滚、可限制权限的范围内持续改进。
|
||||
|
||||
## 六、我建议如何安排开发
|
||||
|
||||
| 阶段 | 目标 | 关键验收 |
|
||||
| ---------------- | ---------------------------------------- | ------------------------ |
|
||||
| S0 · Skill 语义一致性 | 修复官方 Skill 与解析器的标记冲突,建立 Skill 语法同步测试 | Skill 记载的每条核心语法都有可运行金样例 |
|
||||
| S1 · 函数调用 CLI | `marqdo call` 调用已绑定的普通函数、类函数和跨文档函数 | JSON 参数正确绑定;错误路径和双后端行为明确 |
|
||||
| S2 · Skill 编译 | 对显式启用的 `SKILL.md` 解析章节和可执行函数 | 自动产生 SymbolId、签名、依赖、导出清单 |
|
||||
| S3 · 知识即工具 | 将公开函数编译为 ToolSpec,并接入现有 Agent dispatcher | Agent 不重新生成实现即可调用并取得结果 |
|
||||
| S4 · Skill 测试 | 增加 `skill check/test`、负例、效应门禁和回归测试 | 未通过验证的 Skill 不得自动发布 |
|
||||
| S5 · Skill 演化 | 实现候选修改、隔离验证、影响分析、版本晋升与回滚 | 修改失败不影响已发布版本,权限不能自行扩大 |
|
||||
|
||||
这里还需要一项对你的研究目标尤其重要的对照实验。
|
||||
|
||||
让相同模型分别使用普通 Markdown Skill、Markdown Skill 加外部脚本工具、以及 Marqdo Executable Skill 完成相同的一组任务。分别测量正确率、模型需要重新生成的代码量、工具调用参数错误、修改后的回归失败率、token 消耗和完成时间。
|
||||
|
||||
只有与“Markdown + 现有工具调用”进行公平对照,才能证明 Marqdo 的优势来自文档、程序与知识的统一,而不只是因为它额外提供了一个执行器。
|
||||
|
||||
## 七、我对这项构想的最终评价
|
||||
|
||||
我认为这次构想具有三个非常值得肯定的性质。
|
||||
|
||||
第一,它有明确的语言基础。`#`、`##`、自然语言叙述、函数参数、`[]()`、契约表和跨文档符号绑定并不是为了 Skill 重新创造的。Skill 可以成为现有语言的一种应用形态。
|
||||
|
||||
第二,它有真实的工程基础。当前 Marqdo 已经具备部分确定性绑定、制品验证、Agent 复用与隔离运行能力。你需要做的是将这些能力收敛到统一的公开接口,而不是重新实现一套 Agent 框架。
|
||||
|
||||
第三,它能够引出一个更有研究价值的问题:自然语言描述的操作知识,如何逐步转化为可调用、可检查、可维护,并可由 Agent 在受限条件下自行改进的程序制品?
|
||||
|
||||
但是,“SKILL 章节即函数”本身还不足以证明新的编程范式。Markdown 章节映射函数,与文学编程、文档驱动工作流及现有工具包装有明显的共同点。
|
||||
|
||||
更有价值的是把三个原本需要单独维护的对象——Skill 说明、函数实现、Agent Tool Schema——统一为一个可编译的源事实,并展示这种统一确实降低了错误、维护成本和重复生成成本。
|
||||
|
||||
我建议为 Marqdo 保留原来的核心理念,并将这一阶段的技术方向明确为:
|
||||
|
||||
> 知识即工具(Knowledge as Tool):将可执行知识直接编译为 Agent 能够发现、调用和验证的工具,并允许智能体在明确的语义、测试和权限边界内持续改进这些知识。
|
||||
|
||||
这可能是 Marqdo 从“AI 可以使用的编程语言”,进一步走向“AI 能够使用并维护的可执行知识体系”的关键一步。
|
||||
|
||||
备注,这里实际上有一点叙述错误,marqdo支持mq.md文件,所以最好针对SKILL也是SKILL.mq.md这样会比较统一。
|
||||
+249
@@ -0,0 +1,249 @@
|
||||
SKILL的名称应该是.mq.md有一点必须提及,SKILL其实命名不一定必须得是SKILL,平常的一个marqdo文件也可以是一份skill这里的设计太复杂了没有抽离出来核心本质,你看对于一个平常的marqdo文件,完全也可以和SKILL一样,这都是没有区别的,所谓的知识即工具作为高度抽象本质就是带参数调用函数,所以你的inspect等等命令其实完全可以对传统的marqdo也生效而不是非要绑定SKILL对吧,而且这样处理还有好处是方面智能体做单元测试,单个函数是否可以带参数直接运行,换句话说,你仔细思考就会发现这些好处是marqdo的设计哲学在增加一点点call自然派生的优势,所以不需要繁复的设计
|
||||
|
||||
你说得对。这次我认为你抓住了真正的核心,而且我的上一版设计确实把一个本来很自然的语言能力复杂化了。
|
||||
|
||||
Marqdo 根本不需要引入一种叫作 Executable Skill 的新概念,也不需要专门建立 Skill 编译器。
|
||||
|
||||
因为在 Marqdo 的设计哲学下:
|
||||
|
||||
> 一个 `.mq.md` 文件本身就是文档、知识与程序。只要允许从外部直接调用其中的函数,它自然也就能够成为 Skill。
|
||||
|
||||
这不是为 Skill 开发一套新系统,而是为 Marqdo 补齐一个非常基础的语言使用入口。
|
||||
|
||||
## 一、真正缺少的只有一件事:函数级执行入口
|
||||
|
||||
Marqdo 当前已经支持函数定义、参数、返回值、模块引用,以及确定性符号绑定。
|
||||
|
||||
但是日常使用时,我们往往仍然站在“运行整个文件”的角度:
|
||||
|
||||
```
|
||||
marqdo run example.mq.md
|
||||
```
|
||||
|
||||
你现在提出的是:
|
||||
|
||||
```
|
||||
marqdo call example.mq.md 函数名 参数
|
||||
```
|
||||
|
||||
这实际上意味着:
|
||||
|
||||
Marqdo 的最小可执行单位,从文件进一步扩展为文件中的任意可调用函数。
|
||||
|
||||
而这一点会自然派生大量优势。
|
||||
|
||||
普通 `.mq.md` 文件
|
||||
|
||||
自然语言叙述 + 函数 + 参数 + 返回值
|
||||
|
||||
marqdo call
|
||||
|
||||
指定函数 + 绑定参数 + 直接执行
|
||||
|
||||
知识复用
|
||||
|
||||
调用已存在的实现
|
||||
|
||||
Agent Skill
|
||||
|
||||
直接暴露函数为工具
|
||||
|
||||
单元测试
|
||||
|
||||
逐个函数验证结果
|
||||
|
||||
自我改进
|
||||
|
||||
修改函数并重新测试
|
||||
|
||||
这里不存在四套实现,只有一个底层能力的四种使用方式。
|
||||
|
||||
## 二、一个普通的 Marqdo 文件就足够了
|
||||
|
||||
比如,文件 `calculator.mq.md`:
|
||||
|
||||
```
|
||||
# 计算器
|
||||
|
||||
这是一个普通的 Marqdo 文档。
|
||||
|
||||
其中包含一些可以复用的数学计算知识。
|
||||
|
||||
## 加法
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
*[计算结果](a + b)*
|
||||
|
||||
## 乘法
|
||||
|
||||
计算两个数字`a`和`b`的积。
|
||||
|
||||
*[计算结果](a * b)*
|
||||
```
|
||||
|
||||
它既是可阅读的文档,也包含两个函数。
|
||||
|
||||
现在只需要支持:
|
||||
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
返回:
|
||||
|
||||
```
|
||||
5
|
||||
```
|
||||
|
||||
再比如:
|
||||
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.乘法 a=4 b=6
|
||||
```
|
||||
|
||||
返回:
|
||||
|
||||
```
|
||||
24
|
||||
```
|
||||
|
||||
以上 `marqdo call` 是拟新增的命令形式;函数示例遵循当前 `*…*` 返回、`[]()` 遮蔽的语义。
|
||||
|
||||
这时候,一个 Agent 只要能够读取这个 `.mq.md` 文档,就可以理解函数的用途;只要能够调用 Marqdo CLI,就能执行其中的能力。
|
||||
|
||||
它根本不需要关心这个文件是不是 Skill,也不需要一份特殊的 `SKILL.md`。
|
||||
|
||||
如果 Agent 把它当成 Skill 阅读和使用,它就是 Skill;如果开发者把它当成程序库调用,它就是程序库;如果研究者把它作为知识库中的一部分,它就是可执行知识。
|
||||
|
||||
文件的身份没有变化,变化的是使用方式。
|
||||
|
||||
## 三、这项能力会自然解决三个问题
|
||||
|
||||
### 1. 让知识成为工具
|
||||
|
||||
传统 Skill:
|
||||
|
||||
Agent 阅读操作说明,决定如何完成任务。
|
||||
|
||||
Marqdo:
|
||||
|
||||
Agent 阅读函数说明,找到适合的函数,传入参数,直接执行。
|
||||
|
||||
这就将原来的:
|
||||
|
||||
知识 → Agent 理解 → 重新实现 → 执行
|
||||
|
||||
缩短为:
|
||||
|
||||
知识 → 函数定位 → 参数调用 → 执行
|
||||
|
||||
但模型仍然需要负责判断应该调用哪个函数、传入哪些参数。确定性的是被调用函数的语言语义,而不是整个 Agent 决策过程。
|
||||
|
||||
### 2. 让单元测试成为语言的天然能力
|
||||
|
||||
我非常赞同你提到的单元测试价值。
|
||||
|
||||
有了 `marqdo call`,可以直接测试:
|
||||
|
||||
```
|
||||
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
|
||||
# 期望 5
|
||||
|
||||
marqdo call calculator.mq.md 计算器.加法 a=-2 b=3
|
||||
# 期望 1
|
||||
|
||||
marqdo call calculator.mq.md 计算器.乘法 a=0 b=100
|
||||
# 期望 0
|
||||
```
|
||||
|
||||
不必为了测试一个函数,再创建一个 `# main`,再编写调用、打印和结果检查的包装程序。
|
||||
|
||||
未来即使增加 `marqdo test`,底层仍然可以复用同一个函数调用接口。
|
||||
|
||||
### 3. 让 Agent 可以针对知识进行局部改进
|
||||
|
||||
这是你提出的最有意义的延伸。
|
||||
|
||||
假设一个 Agent 发现 `计算器.乘法` 对某类输入存在错误。
|
||||
|
||||
它可以:
|
||||
|
||||
1. 阅读相应函数及其上下文。
|
||||
2. 修改这个 `.mq.md` 文件中的函数实现。
|
||||
3. 直接用 `marqdo call` 传入错误输入验证。
|
||||
4. 再运行该函数的历史测试。
|
||||
5. 如果检查通过,就提交候选修改;否则保留原有实现。
|
||||
|
||||
这使得 Agent 的改进对象不再仅仅是自然语言提示词,而是有明确输入、输出和可执行语义的知识单元。
|
||||
|
||||
当然,测试不能证明函数在所有输入上都正确;正式发布和权限控制仍需要遵循已有的项目验证机制。但不需要为此创造一套 Skill 专属的演化协议。
|
||||
|
||||
## 四、真正的 CLI 设计可以非常简单
|
||||
|
||||
我建议第一阶段只做一个命令:
|
||||
|
||||
```
|
||||
marqdo call <文件> <函数> [具名参数...]
|
||||
```
|
||||
|
||||
比如:
|
||||
|
||||
```
|
||||
marqdo call book.mq.md 订单.计算总价 单价=30 数量=2
|
||||
```
|
||||
|
||||
它只需要完成五件事:
|
||||
|
||||
| 步骤 | 职责 |
|
||||
| -- | -------------------- |
|
||||
| 1 | 加载指定 `.mq.md` 文件及其导入 |
|
||||
| 2 | 解析并唯一定位目标函数 |
|
||||
| 3 | 根据现有函数签名绑定、校验参数 |
|
||||
| 4 | 使用现有运行时执行该函数 |
|
||||
| 5 | 返回函数结果和结构化错误 |
|
||||
|
||||
额外提供一个 `--json` 输出选项就足够方便 Agent 调用。
|
||||
|
||||
如果未来需要 `marqdo inspect`,它也应该针对任何 `.mq.md` 文件,列出其中函数、参数和文档描述,而非限定 Skill。
|
||||
|
||||
此外,当前仓库已经有 `--call-lib-path` 和 `artifact.execute` 的相关基础,因此实现时应尽量复用现有函数定位与执行机制,而不是重复开发解释器。
|
||||
|
||||
唯一值得坚持的边界是:外部调用仍必须经过现有权限检查,不能因为新增了 `call` 就默认允许 Agent 对任意函数执行文件删除、网络写入等操作。
|
||||
|
||||
## 五、我认为你的设计哲学现在更加清晰了
|
||||
|
||||
你原来的理念:
|
||||
|
||||
> 代码即文档,文档即知识库,知识即可执行。
|
||||
|
||||
实际上已经足够完整。
|
||||
|
||||
“知识即工具”不是额外的设计理念,而是“知识即可执行”在函数级调用能力成熟后自然出现的结果。
|
||||
|
||||
进一步看,这件事还有一个很漂亮的对称性:
|
||||
|
||||
| 参与者 | 对同一个 `.mq.md` 的使用方式 |
|
||||
| ---------- | ------------------- |
|
||||
| 人类 | 阅读文档、理解知识 |
|
||||
| 编译器 | 解析并验证函数 |
|
||||
| 开发者 | 调用函数、组合程序 |
|
||||
| Agent | 发现知识、调用工具 |
|
||||
| 测试系统 | 输入参数、检查结果 |
|
||||
| 维护者或 Agent | 修改实现、验证改进 |
|
||||
|
||||
这些角色并没有要求作者维护六份不同的东西。
|
||||
|
||||
同一份文件,同一套语义,同一个函数调用接口。
|
||||
|
||||
这也恰恰是我认为 Marqdo 相比传统“Markdown 文档 + 外部工具”组合最值得证明的优势:知识描述与执行实现共址,而且能够直接由语言工具链消费,避免维护重复的工具包装和操作说明。
|
||||
|
||||
所以,我现在的建议与上一轮不同:
|
||||
|
||||
不要开发 Executable Skill 系统。不要设计 Skill 专属语法。不要引入新的 Skill 注册、编译和执行机制。
|
||||
|
||||
先完成 `marqdo call`,使普通 `.mq.md` 中的可调用函数都能被精确定位、传参执行,并用现有语义系统验证。
|
||||
|
||||
这是一个相对很小的接口变化,却可能自然打通 Marqdo 的编程、知识复用、Agent 工具调用和函数级测试四个场景。
|
||||
|
||||
我认为这才是你所说的:让 Marqdo 自己的设计哲学发挥作用,而不是不断增加外部框架来证明它的价值。
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: 作者对于marqdo的价值认识
|
||||
author: cflmy
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
诚实的说,作者其实一直都很纠结说marqdo是否具有存在的必要,不过在逐渐的开发和了解中,marqdo
|
||||
是有价值的,我此时此刻确信这一点。
|
||||
|
||||
在过去的很长时间中,我一直在思考,marqdo代码即文档,文档即知识库,知识库可执行有什么作用呢?
|
||||
|
||||
## code as document,document as skill,skill is tools
|
||||
|
||||
现在我给出的答案是,code as document,document as skill,skill is tools.
|
||||
|
||||
试想一个.mq.md文件,只需要撰写下来,智能体只需要每次执行:
|
||||
```
|
||||
marqdo call 文件名 函数名 函数参数
|
||||
```
|
||||
就能直接的得到执行结果,之后进行下一步的判断,更近一步,我们甚至可以在函数内写分支,但是让智能体决定走哪一个分支,让skill和tools不再强行分离。
|
||||
|
||||
甚至更近一步
|
||||
|
||||
```
|
||||
marqdo call 文件名 函数名 函数参数 toget 返回值
|
||||
```
|
||||
|
||||
得到返回值,在同一个会话进行多次的操作,之后记录下来,我们以后必定能够复现出来。
|
||||
|
||||
再进一步呢,智能体的输出就是marqdo脚本,只需要单步运行就能够得到结果。
|
||||
|
||||
## ABI插件
|
||||
|
||||
除此之外还有编程语言的特色,ABI插件,在deepseek harness中插件被证明是skill、mcp等的极好
|
||||
接入方式,那么有没有可能marqdo可以实现每一个插件都是通过ABI接入的?
|
||||
|
||||
我想答案似乎是可以的。
|
||||
|
||||
这种情况下拓展库应该怎么设计呢?
|
||||
|
||||
我觉得应该按照模块设计
|
||||
|
||||
index.mq.md
|
||||
依赖1
|
||||
……
|
||||
依赖2
|
||||
……
|
||||
|
||||
其中index.mq.md就是这个拓展库的SKILL文档,AI只需要阅读这个文档就知道该怎么使用这个拓展库。
|
||||
|
||||
甚至更近一步的,index.mq.md本身就是一个可执行的文档,包含拓展库的全部功能。
|
||||
|
||||
## 叙述代码是否足够?
|
||||
|
||||
我想叙述性文字在AI编程中是非常重要的,所以,我在这里提出一个编程规范:
|
||||
|
||||
> 所有的函数叙述性文字必须和实际文字混合且超过50%
|
||||
|
||||
进行**校验**如果通过则**通过**否则**不通过**
|
||||
|
||||
这应该是我写的第一个SKILL即tools吧
|
||||
|
||||
所有的拓展库都要规划成为这样。
|
||||
|
||||
skill即tools有一个绝妙的地方那就是tools是函数,函数本身就对应一个操作,这个操作就是一个工具,所以每个skill都只需要调用本身就可以是tools了,同时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、插件/网络依赖及与旧写法的差异。
|
||||
@@ -0,0 +1,102 @@
|
||||
# 智能体能力调研与求道差距复核(2026-10-27)
|
||||
|
||||
| 项目 | 说明 |
|
||||
|---|---|
|
||||
| 状态 | Research / 设计输入;不是功能交付声明 |
|
||||
| 调研日期 | 2026-10-27,Asia/Shanghai |
|
||||
| 源码基线 | Marqdo `16f26d7d60ce9fbc62feb0e8e83f93951f7b53fe`;qdagent `68b757e02ebfb64833b5262b0c8a683512581e8b` |
|
||||
| 框架设计 | [Agent 恢复、工具与资源协议](../design/agent-reliability-tools-resources-2026-10-27.md) |
|
||||
| 产品设计 | [求道智能体能力与预览体验](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级仓库) |
|
||||
|
||||
## 1. 方法与结论边界
|
||||
|
||||
先以 `git pull --ff-only` 同步两仓,再追踪真实调用链与前端入口;对比公开官方文档,不以营销介绍、工具数量或旧设计中的 done 标签代替实现证据。本次是静态源码复核与官方资料研究,没有启动部署实例,没有调用付费模型,没有进行竞品账号实测。因此,下表“源码确认”仅代表代码路径可见,“设计判断”与“待实测”不能写成已复现或已交付。
|
||||
|
||||
主流能力的共同方向是:可恢复的执行、结构化工具与资源、按需上下文、可追溯结果、独立产物展示。不同产品和模型支持范围不同;这里不是市场占有率调查,也不声称所有智能体都具备全部能力。求道应保留文档原生、EKC、验证后沉淀的定位,吸收机制,不引入第二套 Agent Runtime。
|
||||
|
||||
## 2. 官方资料与可借鉴机制
|
||||
|
||||
以下页面均在调研日实际打开;MCP 特意引用固定 `2025-06-18` 版本,作为兼容基线,不宣称它是最新协议。厂商专有能力必须探测,不能因为端点兼容 `/v1` 就认为全部可用。
|
||||
|
||||
| 编号 | 官方来源 | 已核实内容 | 对求道的设计启示 |
|
||||
|---|---|---|---|
|
||||
| S01 | [OpenAI Agents:集成与可观测性](https://developers.openai.com/api/docs/guides/agents/integrations-observability) | MCP 接入与运行、模型、工具等 tracing | 统一 call/attempt/span 关联;产品只显示阶段摘要,详细事件可展开 |
|
||||
| S02 | [OpenAI:Memory 与 Compaction](https://developers.openai.com/cookbook/examples/agents_sdk/building_reliable_agents_memory_compaction) | 区分当前任务上下文压缩、跨运行记忆、可审阅产物 | 历史不要无限拼接;完整产物不等于聊天全文 |
|
||||
| S03 | [LangGraph Persistence](https://docs.langchain.com/oss/python/langgraph/persistence) | checkpointer 保存 thread 状态,store 支撑跨 thread 数据 | 恢复执行状态和用户长期知识是两种生命周期 |
|
||||
| S04 | [LangGraph Interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts) | 恢复时节点代码可能重新执行 | 检查点不能单独保证写操作只执行一次,必须记录效应与幂等键 |
|
||||
| S05 | [Claude Tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) | 工具定义按需进入模型上下文 | 工具多不代表每轮注入全部定义;检索后再校验权限 |
|
||||
| S06 | [Claude Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | 在执行环境中编排工具、筛选结果 | 大批量只读处理可减少模型往返;后置于基础工具可靠性 |
|
||||
| S07 | [Deep Agents overview](https://docs.langchain.com/oss/python/deepagents/overview) | 文件系统、上下文管理、子任务与可选规划能力 | 规划应按任务启用;简单问答不强制复杂工作流 |
|
||||
| S08 | [Gemini Tools](https://ai.google.dev/gemini-api/docs/tools) | 检索、URL、文件搜索、代码执行等工具面 | 覆盖“找资料—读内容—计算—形成产物”,不能只有工程检索 |
|
||||
| S09 | [Gemini File search](https://ai.google.dev/gemini-api/docs/file-search) | 文件检索与引用信息 | 命中要能定位原文,检索摘要不能代替源文件版本 |
|
||||
| S10 | [MCP Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) | schema、结构化结果、资源链接;annotations 有信任边界 | 工具结果包含短摘要和资源引用;注解不是权限凭证 |
|
||||
| S11 | [MCP Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources) | URI 资源、读取和应用决定的上下文注入 | “预览”“加入上下文”“执行”必须是独立动作 |
|
||||
| S12 | [Claude Artifacts](https://support.claude.com/en/articles/17153992-what-are-artifacts-and-how-do-i-use-them) | 产物在会话旁独立打开,可继续查看与编辑 | 右栏应承载正文;不应只提供离开当前会话的入口 |
|
||||
| S13 | [Mozilla PDF.js](https://mozilla.github.io/pdf.js/) | Web PDF 解析和渲染 | PDF 视觉预览和 OCR/知识提取分开交付 |
|
||||
| S14 | [DOMPurify 官方仓库](https://github.com/cure53/DOMPurify) | DOM 清洗、标签/属性配置;插入前清洗 | 替换前端正则“清洗器”,配合同源资源代理和 CSP |
|
||||
|
||||
上述设计启示是本次推导,相关性能收益、成本下降比例不照搬厂商基准。工程路线不绑定某个最新模型或套餐。
|
||||
|
||||
## 3. 源码事实清单
|
||||
|
||||
下列 qdagent 路径相对该仓库;Marqdo 路径相对本仓库。基线 commit 已固定,后续实现需按符号再定位。
|
||||
|
||||
| 编号 | 当前实现证据 | 结论与限制 |
|
||||
|---|---|---|
|
||||
| F01 | qdagent `agent/qdagent.mq.md::契约提示`、`ask` | ASK 和 BUILD 都要求完整六段式 `.mq.md`,包含 main、验证和元数据;普通回答变长有明确结构性诱因。不能断言这是唯一原因 |
|
||||
| F02 | 同文件 `ask` 的门禁修复分支 | `r2` 送入第二次门禁后,成功分支仍 `result = raw`;可能展示修复前内容,设计必须绑定同一 accepted candidate |
|
||||
| F03 | 同文件 `ask` 返回表 | `gated_error` 路径仍可能保留 `status=ok` 且返回 `ok=True`;必须明确业务失败与输送成功的不同含义 |
|
||||
| F04 | 同文件 `eng_tools` | 默认白名单是 `tool_find/reuse/bind/verify/summarize` 五个工程工具;不是整个框架只有五个工具,也不代表已覆盖网页、笔记、文件编辑 |
|
||||
| F05 | `ext/ai/agent.mq.md` | 有 step/plan/run、READ、CALL、观察压缩、工作簿和恢复接口;应扩展这些原语,不另造循环 |
|
||||
| F06 | `plugins/agent/src/resume.rs::resume_save` | JSON 直接 `fs::write`;现有恢复接口不等于具备原子检查点、工具效应对账及任意步骤自动续跑 |
|
||||
| F07 | `src/runtime/`、`src/workbench/capabilities.rs` | 已有隔离执行、取消、事件回放与读通道;这一轮是 Agent 级恢复补足,不重新规划整个进程池 |
|
||||
| F08 | qdagent `session-store.ts::resumeTurn` | 终态 completed/failed/interrupted 直接返回;已有事件续订,但终态消息补齐与中断后的执行恢复需分别处理 |
|
||||
| F09 | qdagent `DesktopFrame.tsx::RightNotesPanel` | 实际只有“查看全部笔记”导航至 `/notes`,没有侧栏笔记正文 |
|
||||
| F10 | 同文件 `RightFilesPanel`、`WorkspacePage.tsx::openFile` | 文件点击已调 `openTarget`;右栏取首个 workspace,根目录最多 40 个非目录项。不能笼统写“所有按钮都跳转” |
|
||||
| F11 | `DesktopFrame.tsx` 的 reader/rightbar 条件 | `DocumentReader` 与右侧 tab 容器互斥,且使用两套开关/宽度状态;不是统一的资源浏览面板 |
|
||||
| F12 | qdagent `NotesPage.tsx` detail | 剥离 frontmatter 后以 `whiteSpace: pre-wrap` 显示文本;没有 Markdown/Marqdo 正文结构渲染 |
|
||||
| F13 | qdagent `DocumentReader.tsx` | 已有 DocumentView、引用版本传递、请求代数防迟到覆盖;`profile_item` target 未进入读取分支,格式不是通用资源分派 |
|
||||
| F14 | 同文件 `sanitizeHtmlFragment` | 主要靠正则移除 script/事件/javascript URL;不能当作完整 HTML 白名单安全边界。未在本次做漏洞利用实验 |
|
||||
| F15 | `src/workbench/document_view.rs` | 有只读文档视图,注释与实现明确避开执行路径;已解析语义应继续复用 |
|
||||
| F16 | `src/workbench/capabilities.rs` | text/markdown 提取可用,pdf/docx/ocr 标 unavailable;提取能力与浏览器 PDF 预览能力须分别探测 |
|
||||
| F17 | qdagent `lib/web_search.mq.md` | 既有网页搜索桥使用 legacy 脚本和固定 `last_web_search.json`;存在并发覆盖设计风险,不能直接作为新工具通道 |
|
||||
| F18 | `plugins/agent/src/mcp_client.rs` | 已有 stdio connect/list/call/close;不能把本轮描述为“从零添加 MCP”,远程连接和资源能力需另验 |
|
||||
| F19 | qdagent `compose_messages` / `ask` | 对话按角色标记拼成字符串注入 standing;会话语义、上下文预算和外部内容信任层级仍需强化 |
|
||||
| F20 | qdagent `lib/workbench.mq.md::documents_read` | 临时文件名以秒和环境 RANDOM 构造,RANDOM 缺失又退到秒;设计仍需真正唯一临时文件。workspace 缺省 `.` 不应作为新授权资源接口规则 |
|
||||
|
||||
这些是本轮优先级依据。10-26 release notes 所列修复作为已有基础保留,但“Implemented(本仓)”不能替代浏览器、真实 HTTP、进程中断与模型输出的联合验收。
|
||||
|
||||
## 4. 能力覆盖与差距优先级
|
||||
|
||||
| 能力 | 当前基础 | 本轮目标 | 优先级 / 归属 |
|
||||
|---|---|---|---|
|
||||
| 自动纠错 | 一次文档门禁修复、plan patch | 分类错误、有限修复、正确结果替换、可恢复失败 | P0 / 两仓 |
|
||||
| 执行恢复 | 任务隔离、取消、事件回放、JSON checkpoint | 传输续订与执行续跑分离;效应对账 | P0 / Marqdo 原语,qdagent UX |
|
||||
| 回答长度 | 六段式文档、完整历史 | 直接回答、摘要+产物、显式详述三种表达 | P0 / qdagent 策略,Marqdo 输出通道 |
|
||||
| 资源阅读 | DocumentView / Locator | 笔记、工作文件、引用、产物统一入口 | P0 / 两仓 |
|
||||
| 侧栏预览 | 两套状态与导航入口 | 单一右栏,点击即预览,聊天不中断 | P0 / qdagent |
|
||||
| 工具使用 | 五工具默认白名单、MCP/库原语 | schema 注册、按需发现、资源读取/搜索/写入/验证 | P1 / 两仓 |
|
||||
| 联网研究 | legacy 搜索脚本 | search+fetch、来源时间、限量正文、可定位引用 | P1 / 两仓 |
|
||||
| 上下文与记忆 | EFI pack、profile、history | 分层上下文、预算、可编辑记忆、资源 pin | P1 / 两仓 |
|
||||
| 多格式 | 文档视图、文本提取 | text/md/mq/code/json/csv/image;PDF 后续 | P0→P1 / 两仓 |
|
||||
| 长任务与计划 | plan 工作簿 | 里程碑、预算、暂停/继续、产物进度 | P1 / 两仓 |
|
||||
| 多智能体与浏览器 | 不作为当前完成前提 | 有界委派、隔离执行、受控浏览器工具 | P2 / 框架主导 |
|
||||
| 可观测评测 | usage、事件与既有测试 | 工具/恢复指标、实际任务语料、回归门禁 | P0 起持续 / 两仓 |
|
||||
|
||||
## 5. 采用与暂缓的决策
|
||||
|
||||
采用:有界失败恢复;工具结果摘要+资源引用;结构化参数;步骤效应账本;产物与聊天投影分离;资源预览与“加入上下文”分离;用户可检查的引用;按需工具发现。原有源码、知识、工作簿与验证证据仍是权威,衍生视图可重建。
|
||||
|
||||
暂缓:全自动跨站电脑操作、任意外部 MCP 自动信任、默认多智能体协作、所有 Office 格式保真编辑、每次问答都规划/运行代码。它们不能先于当前恢复、工具授权和预览闭环。
|
||||
|
||||
不采用:把长回答直接 substring 截断、把失败原文当最终成功、前端断流即重发任务、把所有文件当 HTML、用网页内容改写 system 指令、把预览等同于执行可执行文档。
|
||||
|
||||
## 6. 必须补做的动态验证
|
||||
|
||||
1. 在真实聊天中验证六段式输出与门禁失败/修复的最终消息和持久产物是否一致。
|
||||
2. 丢弃最后一帧、断网、刷新、worker 崩溃分别注入,确认事件重放不重做工具副作用。
|
||||
3. 使用真实 HTTP 入口验证右栏笔记、嵌套文件、历史引用、跨 workspace 资源;不只调用兄弟辅助函数。
|
||||
4. 用恶意/畸形 HTML、路径与符号链接、过大文件验证预览隔离;no-exec 通过哨兵副作用测试。
|
||||
5. 对无凭证模型、text-only provider、不可用转换器做明确降级;记录版本与环境,禁止以 mock 成功声称上线成功。
|
||||
|
||||
后续设计文档中的时间、轮数、字符数、成功率阈值均为拟定验收目标,需用该语料校准。
|
||||
File diff suppressed because it is too large.
Load diff
@@ -1,5 +1,7 @@
|
||||
# 调研:Mid M1–M6 之后标准库还缺什么
|
||||
|
||||
历史调研快照:以下缺口已由 Mid2 和后续标准库闭环分批解决,不能作为当前缺失清单。当前能力请从[标准库源码](../../lib/文件.mq.md)与[验收说明](../design/stdlib-handbook.md)核对。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 缺口盘点(M1–M6 闭环之后)** |
|
||||
|
||||
@@ -0,0 +1,194 @@
|
||||
# 跨仓 Agent 可靠性开发计划(2026-10-27)
|
||||
|
||||
| 项目 | 约定 |
|
||||
|---|---|
|
||||
| 状态 | **Proposed / planning**;本文是排期与验收编排,**不是**已实现声明 |
|
||||
| 日期 | 2026-10-27(Asia/Shanghai) |
|
||||
| 基线 | Marqdo `6ffe5ce` / 2.1.4;qdagent `c4c976c`(设计文档基线曾为 `16f26d7` / `68b757e`;排期以当前 HEAD 为准) |
|
||||
| 协议真源 | [智能体能力补足设计](../design/agent-reliability-tools-resources-2026-10-27.md) |
|
||||
| 产品真源 | [qdagent 智能体能力与预览](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
|
||||
| 证据 | [官方调研与 F01–F20](../research/agent-capabilities-2026-10-27.md) |
|
||||
| 产品侧镜像 | [qdagent 开发计划镜像](../../../qdagent/doc/roadmap/agent-capabilities-development-2026-10-27.md) |
|
||||
|
||||
本文只编排依赖、落点、门禁与发布次序。**不发明第二套 Agent Framework**;不修改 `doc/next/`;不把 capability bit 在合同实测前标真。协议字段以设计文档为准,路线图只引用不另造 schema。
|
||||
|
||||
## 1. 目标与架构边界
|
||||
|
||||
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;工具可发现、可验证、可审计;结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位。
|
||||
|
||||
| 议题 | Marqdo 所有 | qdagent 所有 |
|
||||
|---|---|---|
|
||||
| 恢复 | ErrorV1、预算、CheckpointV2、效应账本、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
|
||||
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
|
||||
| 回答 | AgentOutput 分通道、输出预算、ContextPackV2 | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD |
|
||||
| 资源 | ResourceRef/View、只读预览、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览布局 |
|
||||
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
|
||||
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
|
||||
|
||||
## 2. 现状(不再重做)
|
||||
|
||||
| 已落地基础 | 说明 |
|
||||
|---|---|
|
||||
| Agent A0–A4、O1–O5 | 文档原生 step/plan/run、沙盒与优化波次;扩展 `ext/ai/agent`,不另造循环 |
|
||||
| 隔离 Web 运行时(ADR 0009) | `src/runtime/` Verified;本轮补 Agent 步骤语义,不重建进程池 |
|
||||
| Workbench 合同切片 | DocumentView / Locator / capabilities;Partial,随本轮补 F 矩阵 |
|
||||
| 可执行知识 S0–S6 | 本地确定性子集已门禁;**不重开 S0–S6** |
|
||||
|
||||
本轮增量(设计已锁、代码待做):`AgentErrorV1`、`CheckpointV2` + effect ledger、`ToolSpecV1` 统一调度、`ResourceViewV1`、`AgentOutputV1` 通道、`ContextPackV2`。
|
||||
|
||||
**产品措辞约束**:本地门禁绿 ≠ 远程/多租户安全;≠「知识验证 + Agent 复用闭环」全产品完成。
|
||||
|
||||
## 3. 跨仓依赖与日历顺序
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
MA0[M-A0 contracts] --> QA0[Q-A0 fixtures]
|
||||
MA0 --> MA3[M-A3 ResourceView]
|
||||
MA0 --> MA1[M-A1 Error and Checkpoint]
|
||||
MA0 --> MA2[M-A2 ToolSpec]
|
||||
QA0 --> QA1[Q-A1 answer outcome]
|
||||
QA0 --> QA2[Q-A2 right panel]
|
||||
MA3 --> QA2
|
||||
QA1 --> QA3[Q-A3 recovery UX]
|
||||
MA1 --> QA3
|
||||
MA2 --> QA4[Q-A4 product tools]
|
||||
MA1 --> MA4[M-A4 channels ContextPack]
|
||||
MA2 --> MA4
|
||||
MA4 --> QA4
|
||||
MA3 --> QA5[Q-A5 formats]
|
||||
MA5[M-A5 ledger PDF MCP] --> QA5
|
||||
MA4 --> QA6[Q-A6 plan memory]
|
||||
MA5 --> QA7[Q-A7 connectors]
|
||||
MA6[M-A6 subagents] --> QA7
|
||||
```
|
||||
|
||||
### 3.1 强制顺序原则
|
||||
|
||||
1. 先 **M-A0 ∥ Q-A0** 冻结跨仓字段与缺陷 fixtures。
|
||||
2. 立刻 **Q-A1 + Q-A2 + M-A3(文本/md/mq)**——**不得**被完整 CheckpointV2 阻塞。
|
||||
3. **M-A1** 可先上只读重试 + 原子 checkpoint;**Q-A3** 终态快照可先行,写恢复等 effect ledger。
|
||||
4. 再 **M-A2 ∥ Q-A4** → **M-A4 / Q-A6** → **M-A5 / Q-A5** → **M-A6 / Q-A7**。
|
||||
5. 四类恢复必须分开:事件续订 / 步骤重试 / 工作流 resume(新 attempt + `resumed_from`)/ 答案再生成。
|
||||
|
||||
## 4. 阶段包明细
|
||||
|
||||
### Wave 0 — 合同
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A0** | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | Error/Tool/Resource/Output/Context 协议、旧适配、状态映射;capability **默认 false** | 跨仓字段冻结;未知字段/版本可降级 |
|
||||
| **Q-A0** | 缺陷样例、HTTP 路由清单、answer/resource fixtures;设计入口 | 固化 F01–F20 相关 fixtures;`mock`/`live` 证据区分 | 与 M-A0 字段一致;不把 mock 当 live |
|
||||
|
||||
### Wave 1 — 可见痛点
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **Q-A1** | `agent/qdagent.mq.md`、`gateway/openai`、api 映射 | accepted candidate;`outcome` ≠ HTTP `ok`;摘要投影;ASK 不强制六节 | 修复后只展示 B;未通过不标成功(F01/F02/F03) |
|
||||
| **M-A3(首批)** | `src/workbench/document_view.rs`、新 `resource_view`、媒体适配 | ResourceRef/View;md/txt/code/mq 静态阅读;no-exec | 资源定位与安全语料通过(F15) |
|
||||
| **Q-A2** | `DesktopFrame`、panel store、`DocumentReader`、ResourcePanel/Preview | 统一右栏;笔记/文件点击不导航;同 renderer | 所有入口同预览(F09–F14) |
|
||||
|
||||
### Wave 2 — 恢复
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A1** | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、recovery/effects 模块 | ErrorV1、有界修复、accepted candidate 绑定、CheckpointV2 原子写 | 故障注入不重复写;旧记录不冒险自动恢复(F06) |
|
||||
| **Q-A3** | `execution/turns`、session store、`api.ts` | 终态快照补齐、恢复动作、错误卡 | 事件恢复 0 工具调用;写恢复须 ledger(F08) |
|
||||
|
||||
### Wave 3 — 工具与通道
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A2** | `plugins/agent/src/lib.rs`、`mcp_client.rs`、tool registry/dispatcher | ToolSpec/Call/Result;CALL+native 单通道;分页与结果资源 | 未授权调用为 0;失败结果结构正确(F04/F05/F18) |
|
||||
| **M-A4** | `ext/ai/agent.mq.md`、`plugins/llm`、`src/workbench/run_context.rs` | AgentOutput 通道、预算、ContextPackV2 | 原生与纯文本 provider fixture 可用(F01/F19) |
|
||||
| **Q-A4** | `agent/tools/`、工具目录、ContextAttachment | 业务工具;保留旧五工程工具别名 | 找→读→改→验证→预览真实闭环 |
|
||||
| **Q-A6** | 计划折叠、预算 UI、profile 忘记、候选沉淀 | ResponsePolicy UX、记忆边界 | 压缩与恢复不丢用户约束 |
|
||||
|
||||
### Wave 4 — 持久与格式
|
||||
|
||||
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|
||||
|---|---|---|---|
|
||||
| **M-A5** | `src/runtime/` 存储/事件适配、MCP 与转换插件 | ledger↔runtime 对账、PDF/Office 插件、远程 MCP | crash/restart 通过;诚实探测(F16–F18) |
|
||||
| **Q-A5** | JSON/CSV/图片/PDF UI、网页来源与页/行引用 | 格式扩展与转换进度 | 缺插件可读降级;PDF 不假称 OCR |
|
||||
| **M-A6 / Q-A7** | plan/subtask/sandbox;MCP 配置与委派 | 程序化工具、有界委派、可选浏览器 | **后置**;须证明收益与预算/效应可控 |
|
||||
|
||||
## 5. F01–F20 → 包映射
|
||||
|
||||
| ID | 摘要 | Marqdo | qdagent | 主要验收 |
|
||||
|---|---|---|---|---|
|
||||
| F01 | ASK/BUILD 强制六节 | M-A4 输出通道 | Q-A1 ResponsePolicy | QA-01、MA-T12 |
|
||||
| F02 | 修复后仍返回 raw | M-A1 accepted 绑定 | Q-A1 | QA-03、MA-T12 |
|
||||
| F03 | `gated_error` 仍 `status=ok` | M-A0/M-A1 ErrorV1 | Q-A1 envelope | QA-04 |
|
||||
| F04 | 默认仅五工程工具 | M-A2 registry | Q-A4 目录 | QA-17 |
|
||||
| F05 | 已有 step/plan/run | **扩展** agent.mq.md | — | 不另造 loop |
|
||||
| F06 | `resume_save` 裸 `fs::write` | M-A1 CheckpointV2 | Q-A3 UX | MA-T03/T04 |
|
||||
| F07 | runtime 已有 | 复用,不重建 | 接线恢复 API | — |
|
||||
| F08 | `resumeTurn` 终态直返 | 事件 vs 再执行分离 | Q-A3 快照补齐 | QA-13、MA-T05 |
|
||||
| F09–F12 | 右栏/笔记预览缺陷 | M-A3 ResourceView | Q-A2 | QA-06–QA-09 |
|
||||
| F13 | DocumentReader 非通用分派 | DocumentView 保留 mq;ResourceView 其它 | 预览分派 | QA-09 |
|
||||
| F14 | 正则 HTML 清洗 | 生产侧 allowlist | DOMPurify + CSP | QA-11、MA-T11 |
|
||||
| F15 | DocumentView no-exec | 保持;ResourceView 禁 run/verify | — | MA-T10 |
|
||||
| F16 | pdf/docx/ocr unavailable | M-A5 插件 + 诚实探测 | Q-A5 | QA-10 |
|
||||
| F17 | legacy web_search 临时文件 | 优先框架 net 工具 | 迁移工具 | QA-17、F20 |
|
||||
| F18 | MCP stdio 已有 | M-A2/5 timeout/cancel/remote | 连接器配置 | MA-T07 |
|
||||
| F19 | 历史字符串 standing | M-A4 ContextPackV2 | compose_messages | QA-19、MA-T13 |
|
||||
| F20 | 弱临时名;workspace `.` | 安全临时文件 + ResourceRef | 资源解析 | QA-08、MA-T11 |
|
||||
|
||||
## 6. 验收与发布
|
||||
|
||||
### 6.1 Marqdo 门禁(MA-T01–T14)
|
||||
|
||||
以设计文档 §10 为准;基础机制用确定性 fake provider/tool;真实 provider 少量单独 smoke 并记费用。摘要:
|
||||
|
||||
| 编号 | 必须观察到 |
|
||||
|---|---|
|
||||
| MA-T01 | 429 后成功:退避、计量、单一 accepted answer |
|
||||
| MA-T02 | schema 连续错:一次修复后停;无效参数不执行工具 |
|
||||
| MA-T03 | 写成功但 receipt 前提杀:unknown_effect→对账;写计数不增 |
|
||||
| MA-T04 | checkpoint 写一半杀进程:完整上一检查点或明确 corrupt |
|
||||
| MA-T05 | 终态事件丢失:快照恢复完整消息;工具次数不增 |
|
||||
| MA-T06 | 重复/并发恢复:同一幂等键一个 attempt |
|
||||
| MA-T07 | 取消 vs 重试:取消后无新工具调用 |
|
||||
| MA-T08 | 权限/版本变更:stale/conflict/forbidden |
|
||||
| MA-T09 | 伪造 CALL/system:不越白名单 |
|
||||
| MA-T10 | `.mq.md` 预览含写/联网:哨兵不变;只读或安全降级 |
|
||||
| MA-T11 | 格式/超长/路径逃逸:正确 renderer;越界拒绝;无注入 |
|
||||
| MA-T12 | 修复 A→B:answer/artifact/verification 均绑定 B digest |
|
||||
| MA-T13 | 上下文压缩后:约束、待决效应、版本、预算不丢 |
|
||||
| MA-T14 | 旧 CALL/DocumentView:基础可用;缺失能力明确返回 |
|
||||
|
||||
先跑受影响的 Rust/Go/Marqdo 合同与隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标(须记录机器/并发/冷暖缓存):已缓存 100 KiB 文本视图服务端 p95 < 300 ms;核心工具发现 p95 < 100 ms。
|
||||
|
||||
### 6.2 qdagent 门禁(QA-01–QA-20)
|
||||
|
||||
以产品设计 §13 为准;路径必须 `serve → api → 权威业务函数 →` 真实前端。零容忍:重复写效应、预览执行副作用、跨 workspace 越权。
|
||||
|
||||
实现时:`python3 scripts/check-contracts.py`、相关 workbench 测试、前端 `npm test` / `npm run build`,再跑 Playwright;无服务时 E2E 须明确 skip/失败原因。
|
||||
|
||||
### 6.3 Feature flags 与灰度
|
||||
|
||||
建议开关:`agent_output_v2`、`resource_panel_v2`、`agent_tools_v1`、`agent_recovery_v2`。启用取决于 runtime capability + 服务端政策,不由前端单独决定。
|
||||
|
||||
灰度:内部单 workspace → 多 workspace → 真 provider/断网 → 默认开启。关闭恢复时必须停止接纳新恢复请求并保留 attempt 状态,**禁止**切回会盲重做写操作的旧路径。
|
||||
|
||||
兼容迁移:新增协议 → 双读 → 新写 → 验证 → 逐步移除旧适配。旧 resume JSON 可读但不能自动升级成带副作用保证的检查点。
|
||||
|
||||
## 7. 伴生轨(登记,不阻塞主线)
|
||||
|
||||
| 轨 | 动作 |
|
||||
|---|---|
|
||||
| 可执行知识 S0–S6 | **不重开**;消费 BoundCall/EKC;话术保持「本地子集」 |
|
||||
| 知识支撑 F0(M02/M03/M05) | **并行伴生**:provenance/closure invalidate、真 verify API、Skill 无冲突 |
|
||||
| Workbench Partial | 随 M-A0/M-A3 补 F 矩阵与 adapters;不重写 M00–M05 |
|
||||
| 语言 next-phase P3 / Wave B1 评测 | **延后** |
|
||||
| Web Document/Endpoint | 遵守 ADR 0007;禁止 compose_/json bag 回退 |
|
||||
|
||||
## 8. 下一步开工(第一刀实现切片)
|
||||
|
||||
确认本路线图入库后,**另开实现回合**(本文件仅文档):
|
||||
|
||||
1. **M-A0 + Q-A0**:合同与 fixtures
|
||||
2. **Q-A1**:raw→accepted、outcome 一致性
|
||||
3. **Q-A3 子集**:终态快照补齐
|
||||
4. **Q-A2 + M-A3 子集**:右栏真实预览(笔记 / md / mq / txt / code)
|
||||
|
||||
发布判据是 MA-T* / QA-* 与真实 HTTP/browser 证据,不是接口返回 200 或代码中出现某符号名。
|
||||
@@ -0,0 +1,230 @@
|
||||
# Marqdo 现状与规划缺口:从可执行文档到可复用知识
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 现状审计与下一阶段规划;不是已实现能力声明 |
|
||||
| 审计基线 | `main` / `434be9f`,2026-10-23;后续改动须重新核验对应判断 |
|
||||
| 产品意图 | [009.md](../next/009.md) · [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md) · [完整示例](../next/Marqdo_Executable_Knowledge_Example.md) |
|
||||
| 目标 | **代码即文档,文档即知识库,知识库可执行,可执行知识可复用** |
|
||||
| 方向修订 | 2026-10-23:按[文档原生开发指导](../design/document-native-development-guide.md)重排交付,G01–G12 保留为缺口证据,不等于作者必须经历的治理流程 |
|
||||
|
||||
## 1. 本文解决什么问题
|
||||
|
||||
仓库已经拥有语言运行时、双后端、标准库、扩展、文档站、EKC、Agent 和一批语义制品结构。现有[详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)定义了目标架构和 M0–M6,但它主要写于目标能力尚未落地之时;现在照它逐项勾选,容易把“结构存在”“CLI 可调用”“目标闭环成立”混为一谈。本文只补**现状与目标之间尚未被规划成可验证闭环的工作**。语法和产品目标仍以前述意图文档为准;旧文档中的 Classic 链接取元、单体知识类、或另一套知识索引不应反向规定新语义。
|
||||
|
||||
本轮判断以源码、可定位的测试和文档状态为证据。`done` 表示有可运行入口和回归测试;`partial` 表示有结构或单一路径,仍不满足产品判据;`design` 表示主要存在于文档和目标示例。**不能把能解析、能运行、能检索、能验证事实视作同一个结论。**
|
||||
|
||||
### 1.1 对上一版规划排序的修正
|
||||
|
||||
上一版把内部工程完整度放在主要位置,直到 S6/S7 才验收 Agent 复用和作者体验,容易造成“先建治理平台,再证明文档有用”的偏差。本版改为从可读步骤、确定执行和早期本地复用向外扩展;每片同时交付源码示例、诊断和消费者可见结果。工程基础按切片所需完成,不降低已开放路径的安全要求。
|
||||
|
||||
P0/P1/P2 分类改为缺口领域,不再按编号整组串行:G06 的未知效应安全下限必须进入最早执行试点,G09 的本地复用也不再等锁和远程授权全部完成。复杂业务的证据、严格锁和远程凭据按使用场景增加,不能强加给每个单文件程序。每片还须记录作者重复声明数、局部修改范围和实际复用结果,指标见[指导 §8](../design/document-native-development-guide.md#8-验证-marqdo-优势而不只验证组件存在)。
|
||||
|
||||
## 2. 设计思想落实为四个可证伪承诺
|
||||
|
||||
| 承诺 | 必须由什么证明 | 当前判定 |
|
||||
|---|---|---|
|
||||
| 代码即文档 | 一份 `.mq.md` 的叙述、契约、示例、可执行语句由同一解析结果驱动;改变语义会让说明/示例失配可见 | 运行与 view 已有基础;正文引用尚未进入完整语义 AST(partial) |
|
||||
| 文档即知识库 | 可寻址的事实、规则、步骤、来源、适用范围和关系由编译器生成;不同消费者读取同一身份和图 | 项目索引与 Artifact 投影已起步;双图和占位字段仍存在(partial) |
|
||||
| 知识库可执行 | 引用先绑定、检查参数/契约/效应/版本,再由运行时执行**绑定的目标**;正文默认不触发副作用 | CLI 可解析、运行时可执行,但两条路径未闭合(partial) |
|
||||
| 可执行知识可复用 | Agent 发现候选后取得有条件、可失效的句柄,实际调用既有制品;trace 记录符号、摘要、输入和结果 | MLSP 有初版 handle;EKC/Agent 尚未统一到此协议(partial) |
|
||||
|
||||
这四条有语义依赖,但应在受限故事中逐步贯通,不是四个必须全部做完才能进入下一层的大项目。阅读体验和检索召回不能代替绑定;绑定不能证明知识内容正确;执行成功不能证明已经复用既有知识。
|
||||
|
||||
## 3. 仓库能力盘点与规范 M0–M6 的真实进度
|
||||
|
||||
| 既有里程碑 | 可复用成果 | 仍未满足的完成条件 |
|
||||
|---|---|---|
|
||||
| M0 语义与测试 | Occlusion 已为默认;[语法测试规程](../next/Marqdo_Executable_Knowledge_Testing.md)和部分金样存在;标准库、扩展库已经迁移 | `tests/executable_knowledge/` 系统夹具、100 单元生成器、导航/正文/效应负例矩阵未形成独立门禁 |
|
||||
| M1 项目身份 | [`src/project/mod.rs`](../../src/project/mod.rs)确定项目根和扫描顺序;[`src/sema/symbols.rs`](../../src/sema/symbols.rs)产生 ModuleId/SymbolId;CLI `knowledge inspect/resolve` 可用 | 身份保留、移动/重命名、symlink/重复扫描、大项目增量与错误聚合还需完整策略和测试 |
|
||||
| M2 统一链接与调用 | 裸零参路径和关联函数已有 Tree/Bytecode、CLI 金样;`Expr::Occluded` 已承载标签和 payload | [`src/ast.rs`](../../src/ast.rs)仍无统一 Named/正文引用节点;[`src/sema/ir.rs`](../../src/sema/ir.rs)只提取执行体部分调用;运行时仍独立按名称寻找调用目标 |
|
||||
| M3 语义制品 | SemanticArtifact、EffectSet、SourceRef、VerificationRecord、JSON 投影已存在 | 适用性、来源证据、单位、真实验证状态、完整效应闭包与规范摘要仍缺;字段存在不代表语义已实现 |
|
||||
| M4 锁与影响 | `knowledge lock/impact` 可用;[`src/sema/lock.rs`](../../src/sema/lock.rs)支持原子写入和反向依赖查询 | 锁只比较 artifact 摘要;目标、接口、实现、证据、传递闭包变更未独立报告;正文/证据边不在影响闭包内 |
|
||||
| M5 消费者 | view 显示部分语义信息;MLSP 提供 `artifact.*`;EKC/Agent 有各自检索与复用能力 | 同一图/同一绑定尚未贯通;Agent 对 ready 的判定与执行句柄未被强制;trace 不足以证明实际复用 |
|
||||
| M6 迁移与发布 | 全仓新语法迁移、`--legacy-markup` 入口、v2.1.0 发布已完成 | 发布不等于 M0–M5 已完成;目标示例仍注明“尚不能完整运行”,100 单元与 Agent 对照实验未过 |
|
||||
|
||||
`examples/executable-knowledge/README.md` 是目标示例,仍明确说明类函数、统一 `Named<T>` 和步骤图的完整运行是设计目标。它不得作为“产品闭环已完成”的发版证据。
|
||||
|
||||
### 3.1 相邻路线如何进入本规划
|
||||
|
||||
| 仓库区域 | 当前路线状态 | 与可执行知识主线的连接点 |
|
||||
|---|---|---|
|
||||
| Interpreter / 标准库 | Tree、Bytecode、`lib/` 与中英库有大量金样;[Mid2](stdlib-mid2.md)已完成 | 作为 BoundCall、效应声明、签名与迁移回归的基础;不为本路线重做通用库 |
|
||||
| Web / 浏览器 | [Web](ext-web.md) W 波与 [WASM](browser-wasm.md) C 波已落地 | 作为 view/静态投影和宿主能力消费者;知识引用不能在静态导出或浏览器预览中偷跑服务端 effect |
|
||||
| Agent / LLM / 沙盒 | [Agent](ext-agent-optimize.md) Wave B 有局部待项;[优化 O 波](ext-ai-optimize.md)已完成 | 工作簿、OKF、沙盒可复用;S2 接本地 bound handle,S4/S5 增强政策;不另建平行知识身份 |
|
||||
| 外联 / Notebook | [外联 F4](foreign-v2.md)和[会话 D4–D5](notebook-session.md)尚有余项 | 外部内核、持久状态和重放需显式建模为 effect/环境依赖;不能把会话结果当纯制品缓存 |
|
||||
| 领域扩展 | [Quantum Q8c](ext-quantum.md)等剩余项属领域体验;[宿主 H4b](ext-hosting.md)为可选 HTTP 能力 | 不阻塞语义主链;但扩展元数据与插件调用必须参加 G06/G10 的 effect 和兼容性门禁 |
|
||||
|
||||
这些路线各有自己的完成定义。本文不将其余项全部吸收到下一版核心范围;只规定它们与统一语义层交互时必须遵守的契约。
|
||||
|
||||
## 4. 语义一致性缺口:消除错误的语义真相
|
||||
|
||||
### G01 两份图与同名输出路径
|
||||
|
||||
**证据。** [`src/knowledge/compile.rs`](../../src/knowledge/compile.rs)先调用 `compile_project` 并写语义投影,随后重新用 `extract_graph` 从源码提取旧 EKC 图。后者的 `write_projections` 再写 `graph/edges.json`;[`src/knowledge/graph.rs`](../../src/knowledge/graph.rs)的调用边按短名选首个匹配符号。由此“语义边”和“检索边”既不是同一事实,也会争用同一个文件名。
|
||||
|
||||
**规划缺口。** 详细规范要求 EKC 是 `SemanticProject` 投影,却未给出**并行迁移期间的文件命名、读取优先级、冲突检测与废弃时点**。只新增语义图不解决消费者继续读旧边的问题。
|
||||
|
||||
**决策与交付。** 明确一个权威 `SemanticProject`;图边按稳定 `SymbolId/ArtifactId` 生成。旧检索索引仅含查询优化数据,不再自行确定 calls/uses。若迁移期保留旧 JSON,放入独立版本化路径并声明其非执行依据。`knowledge compile`、`view`、`check`、`impact`、MLSP、Agent 对同一引用应报告同一目标及诊断。
|
||||
|
||||
**验收。** 制造两个模块同名函数并让调用只 import 其中一个;语义图、CLI resolve、Tree/Bytecode trace、view 和 Agent handle 必须指向同一 ID。编译两次输出字节一致;生成物中没有同名文件被后续投影覆盖。
|
||||
|
||||
### G02 绑定没有成为执行的前置条件
|
||||
|
||||
**证据。** [`src/main.rs`](../../src/main.rs)的 `knowledge resolve` 走项目索引;[`src/mlsp.rs`](../../src/mlsp.rs)的 `link.resolve` 通过 artifact 名字/后缀匹配;[`src/interp.rs`](../../src/interp.rs)仍有自身的 `eval_path_call` 和函数查找;[`src/bytecode/`](../../src/bytecode/)也有独立调用实现。`compile_project` 目前只将同模块无接收者调用识别为静态依赖,其余记为 `external_or_dynamic`。这几条路径存在真实分叉。
|
||||
|
||||
**规划缺口。** 现有规范提出 Bound IR,但缺少**最小可合并的执行切面**以及动态调用的明确边界。不能先宣称图边覆盖执行调用,再等待后端改造。
|
||||
|
||||
**决策与交付。** 先让显式 import、普通函数、关联函数这三个静态路径通过唯一 resolver,生成 `BoundCall { target, signature, source_span, required_effects }`。Tree 和 Bytecode 只消费 BoundCall;确需动态解析的路径使用独立 `DynamicCall`,在图/诊断中显式标记,不能假装已绑定。`run/check/knowledge resolve/MLSP` 使用相同 import 范围和歧义规则。
|
||||
|
||||
**验收。** 同名跨模块、重命名、缺 import、实例方法误用、动态目标分别有稳定诊断;任一静态 trace 中执行的 SymbolId 与编译图边一致。错误不得因后端不同而变成另一目标。
|
||||
|
||||
### G03 `[]()` 只有标签,还没有完整知识步骤
|
||||
|
||||
**证据。** [`src/ast.rs`](../../src/ast.rs)保留 `Expr::Occluded`;[`src/parse/prose.rs`](../../src/parse/prose.rs)扫描粗体、斜体和反引号,但没有完整 Markdown 正文链接 AST。[`src/sema/ir.rs`](../../src/sema/ir.rs)当前 KnowledgeRef/KnowledgeStep 主要由调用点提取,步骤 `kind` 为 `call`;取元、推导、遍历、正文、导航尚未同等进入图。目标示例列出的 observe/derive/iterate/narrate 不能由现有投影证明。
|
||||
|
||||
**规划缺口。** 缺少正文 inline 的位置、逃逸、代码围栏、标准 URL 与知识引用的**一套无副作用解析协议**,以及 `[]()` 在表达式、循环和正文的统一节点身份。
|
||||
|
||||
**决策与交付。** 保留现有 payload 表达式解析器;为上下文建立稳定 SyntaxNodeId 与 `Named<T>`/等价 lowering。明确 `NavigationLink`、`NarrativeRef`、`ExecutableNamed`、`LoopNamed` 的互斥分类及 span。正文引用只解析和验证;主动纯预览可使用项目/会话既有政策,不要求逐链接确认;外部 effect 仍需明确执行上下文与宿主能力许可。各类型步骤的输入、输出、依赖和角色由编译器推导;标签是阅读、检索和局部编辑的上下文,但不参与授权和寻址。作者不手工填写步骤 ID 或生成图。
|
||||
|
||||
**验收。** 一份文档同时含 URL、锚点、带空格/嵌套括号载荷、围栏、行内代码、取元、计算、循环、正文引用;生成的 ref/step 数、分类和跨度稳定,正文 `run/check/view static` 不发生外部 effect。
|
||||
|
||||
### G04 生成物写入不是整代快照
|
||||
|
||||
**证据。** [`src/sema/ir.rs`](../../src/sema/ir.rs)将语义文件写到临时目录后,逐个删除并移动 `project.json`、`symbols.json`、`refs.json`、`artifacts/`、`graph/`、`verification/`;[`src/knowledge/compile.rs`](../../src/knowledge/compile.rs)再写旧投影。这不是消费者可原子读取的整代快照,构建中途可能看到混合版本。
|
||||
|
||||
**规划缺口。** 规范写了“原子写入”,未规定**整代提交、读者快照、失败恢复和旧版本保留**。
|
||||
|
||||
**决策与交付。** 使用带 schema/build-id 的代目录与原子指针或等价快照机制;所有消费者一次选择一代,读完整个结果后才释放。生成物可删除重建;崩溃后只能看到旧完整代或新完整代。
|
||||
|
||||
**验收。** 在写每个投影文件时注入故障并并发读取;不得出现 `project` 属于 A 代而 `edges` 属于 B 代,失败后旧代仍可读。
|
||||
|
||||
## 5. 可信执行缺口:按场景落实验证门槛
|
||||
|
||||
### G05 来源、适用性和验证状态仍是占位投影
|
||||
|
||||
**证据。** [`src/sema/ir.rs`](../../src/sema/ir.rs)给函数固定 `"no explicit applicability constraints"`,`SourceRef` 主要指向定义它的源码,`evidence` 摘要来自契约文本;验证记录固定 `contract=unchecked`、`tests=unknown`、`evidence=unverified`、`domain=unreviewed`。现有 [`src/knowledge/lifecycle.rs`](../../src/knowledge/lifecycle.rs)的 `verify` 是另一套 EKC 检查。因此“有 SourceRef”并不表示政策原文被关联或核验。
|
||||
|
||||
**规划缺口。** 规范列出字段和七层状态,但没有定义**作者如何写来源/适用性、如何证明测试确实覆盖此制品、谁可将 domain 从 unreviewed 提升、何时失效**。不确定现实真假的结论必须保留 unknown。
|
||||
|
||||
**决策与交付。** 用现有 Markdown/frontmatter/契约表表达可选的 `source`、有效区间、地域/单位/输入前提,形成可解析 schema;把编译、静态检查、实跑测试、来源内容、人工领域审阅作为独立证据事件。定义状态迁移、撤销和失效规则;生成物记录证据文件/测试运行摘要,不允许 CLI/Agent 自报 `verified`。
|
||||
|
||||
**验收。** 政策原文改变而函数未改时 evidence 状态下降;来源删除、过期、输入不满足分别给不同诊断;无来源的纯工具函数可运行,但不能被宣称为已证实业务事实。
|
||||
|
||||
### G06 效应识别存在“未知即纯”的漏洞
|
||||
|
||||
**证据。** [`src/sema/ir.rs`](../../src/sema/ir.rs)的 `effects_for_call` 依据名字前缀猜测 `fs/net/llm` 等,其余返回 `pure`;`direct_effects` 只汇总直接调用。未知插件、别名、包装函数和传递调用可能因此被标作纯。[`src/mlsp.rs`](../../src/mlsp.rs)以该集合做 `artifact.execute` 的效应拒绝。
|
||||
|
||||
**规划缺口。** 详细规范定义 EffectSet,却没有给出**跨宿主函数、标准库、扩展 ABI、动态调用的权威效应注册表和未知效应策略**。
|
||||
|
||||
**决策与交付。** 内核/标准库/插件元数据声明 effects,绑定后做调用图闭包;动态或缺元数据为 `unknown`,需要显式能力授予,不得降为 pure。`view` 静态、`verify pure`、Agent ready 门槛使用同一集合。实际宿主能力限制仍在执行时强制。
|
||||
|
||||
**验收。** 用自定义名字包住写文件/网络/插件调用;静态 effect 必须传递到入口,默认 pure 策略拒绝执行。循环调用图收敛;未知动态调用拒绝 pure 证明。
|
||||
|
||||
### G07 绑定句柄未表达可复用的授权与适用性
|
||||
|
||||
**证据。** [`src/mlsp.rs`](../../src/mlsp.rs)的 `artifact.bind` 主要检查目标唯一及可选 digest,返回 `artifact_id/digest/project/policy/effects`;它没有要求 ready、契约、适用性或来源状态。`artifact.execute` 重编译比对摘要后按 `display_name` 最后一段调用解释器;调用者提交的 `allow_effects` 会变为宿主能力。现阶段这是实验性执行接口,不是可信复用协议。
|
||||
|
||||
**规划缺口。** 缺少句柄的**发行者、主体、策略、输入约束、能力上限、过期/撤销、并发源变更**模型;也缺少“绑定到精确嵌套函数”在 runtime 的保证。
|
||||
|
||||
**决策与交付。** `bind` 必须验证 SymbolId、签名、输入、已声明适用性、所选验证政策及 effect 上限;政策要求锁时检查 lock。`execute` 复核同一目标与状态并按绑定符号调用。受信本地调用先采用精确绑定引用和摘要复核,不强制搭建签发服务;远程/多租户/不受信调用再加入可信发行者、主体、范围、期限/撤销及防伪机制。客户端参数不是远程授权来源;运行时能力上限始终由宿主强制。响应如实显示政策和未知状态,作者不手写 handle。
|
||||
|
||||
**验收。** 本地先覆盖改参数、改依赖、改效应策略、同名嵌套函数和并发源码变更,不得错调用或越权;严格政策增加来源与锁变更,远程增加伪造/过期/撤销测试。`ready` 必须注明相应 policy 与条件,不是全局永久认证。
|
||||
|
||||
### G08 锁定与影响分析未覆盖知识变化
|
||||
|
||||
**证据。** [`src/sema/lock.rs`](../../src/sema/lock.rs)的 lock 文件虽然写出 interface/implementation/evidence/dependencies,但检查时只比较 `artifact` 摘要。该摘要在 [`src/sema/ir.rs`](../../src/sema/ir.rs)只组合本地 interface/implementation/evidence,没有传递依赖闭包;impact 的边也只来自已识别的本地调用。`knowledge impact` 与语义 impact 是两套命令/图。
|
||||
|
||||
**规划缺口。** 未定义**锁的审阅单位、变更分类、依赖 SCC、证据变更如何传播到正文、升级冲突处理**。
|
||||
|
||||
**决策与交付。** 分别持久化 target/interface/implementation/evidence/closure 摘要,SCC 按确定规则求闭包;strict 对未审阅目标变化失败。impact 用同一图沿 calls/depends_on/supported_by/narrates 反向传播,并说明为何被影响。每次 lock update 留下人可审阅的差异报告。
|
||||
|
||||
**验收。** 本地函数源码不变而下游税率规则变了时 closure 变化;只改描述不混同事实证据变化;来源变更影响客服说明;同一个查询在 CLI、MLSP、view 展示相同受影响 ID 集合。
|
||||
|
||||
## 6. 作者与生态缺口:从早期切片持续验证
|
||||
|
||||
### G09 Agent 仍可能把候选当作可执行知识
|
||||
|
||||
**证据。** [`src/knowledge/reuse.rs`](../../src/knowledge/reuse.rs)、[`plugins/agent/`](../../plugins/agent/)和 `ext/ai/agent.mq.md` 有各自的检索、near-match、工作簿/Skill 固化流程;[`src/mlsp.rs`](../../src/mlsp.rs)另有 artifact handle。现有 [Agent 路线图](ext-agent-optimize.md)主要跟踪工作簿、路由和评测,没有把“发现→精确绑定→验证→调用既有制品→记账”设成强制路径。
|
||||
|
||||
**规划缺口。** 需要明确 **REUSE、ADAPT、CREATE 的进入条件与失败后分流**,以及“避免重复生成”用什么客观指标衡量。
|
||||
|
||||
**决策与交付。** near/soft-match 只能供候选发现;Agent 可以选择并提交精确候选,REUSE 前必须经同一 resolver 和 policy 得到 bound handle。不可用则记录原因,按权限进入 ADAPT/CREATE 或请求补充决策。新草稿可被发现、查看和在本地明确权限下试跑,进入共享自动复用的 ready 集合前按政策验证晋升。先提供含步骤、源码、约束、负知识和验证状态的最小上下文卡,再支持带期望摘要的局部补丁和语义 diff,避免整篇再生成。trace 包含任务、候选、选定 SymbolId、所有相关摘要、输入摘要、policy、实际执行结果及因果依赖;私密输入只存可审计脱敏摘要。
|
||||
|
||||
**验收。** 已有适用能力时实际调用而不新建同义函数;同名未消歧、违反所选政策的过期/未验证候选、权限不足不能自动执行。局部修改不覆盖并发编辑;只改措辞却改变签名必须可见。同样任务与预算下报告重复实现率、错误复用率、发现率、成功率、编辑范围、作者维护成本及失败样本。
|
||||
|
||||
### G10 标准库、扩展库与发布物缺少跨层一致性门禁
|
||||
|
||||
**证据。** [语法测试规程](../next/Marqdo_Executable_Knowledge_Testing.md)覆盖了部分零参路径金样;仓库有大量 `lib/`、`ext/`、`public/` 和示例。`.github/workflows/` 目前只有 release/pages,没有对每次提交运行可执行知识项目夹具的 CI;[目标示例](../../examples/executable-knowledge/README.md)仍不可端到端运行。现有 [lib/ext 路线图](lib-ext-code-as-docs.md)的历史“链接取元”已被 v2.1 默认遮蔽语义取代,`done` 不代表今天的知识引用集成已完成。
|
||||
|
||||
**规划缺口。** 对新语义没有固定的**全仓兼容矩阵、跨平台发布前检查、示例可运行状态标签、回滚规则**。
|
||||
|
||||
**决策与交付。** 分层门禁:parser/sema → Tree/Bytecode → 标准库中英镜像 → 扩展插件装载 → CLI/MLSP/view/静态导出 → 一体化书店/订单示例。每个负例也断言诊断码和副作用计数。每次语义变化先迁移 `lib/ext` 并保持 stdout 与 effect,不通过扩展旧语义来掩盖库的过时写法。CI 在 main 的 PR/push 执行无网络核心套件;需要插件/浏览器的平台测试单列结果;发布前检查包内标准库/扩展与二进制版本匹配。
|
||||
|
||||
**验收。** `cargo test --locked`、gold 单线程、可执行知识项目夹具、CLI JSON schema 和每个平台打包后冒烟通过;文档示例一旦标为可运行,CI 每次执行。没有 `skip` 可以充当核心能力成功证据。
|
||||
|
||||
### G11 文档状态本身缺少统一真相
|
||||
|
||||
**证据。** [`doc/README.md`](../README.md)仍将较早 mapping 称为“现行运行时”,将 [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)的 v2.0.0 基线直接当下一阶段实施依据;多个旧路线图的 `done` 和新语义目标相互交错。README 的 v2.1 链接/投影描述可能被误读为完整可执行知识系统已交付。
|
||||
|
||||
**规划缺口。** 缺少文档版本、优先级、状态和实现证据之间的**维护协议**。这会让人和 Agent 从旧文档学回被迁移掉的语义。
|
||||
|
||||
**决策与交付。** 文档顶部标明“目标规范 / 已实现 / 历史兼容 / 被取代”及适用版本;在 `doc/README.md` 提供唯一入口。每项能力把规范段落、代码位置、测试、示例、发布版本关联起来;任何 `done` 必须列出验收命令及结果。旧内容可以保留历史价值,但搜索结果与 Skill/教程默认指向当前规范。制定文档可运行片段的抽取或同步测试,降低“文字与实现分叉”。
|
||||
|
||||
**验收。** 新贡献者只读 README、doc 索引和 Skill 能写出默认语义的运行样例;旧取元写法在当前教学材料不会以默认形式出现;变更语法时 CI 能发现核心规范与构造卡片失配。
|
||||
|
||||
### G12 项目规模、缓存与权限边界尚无可量化 SLO
|
||||
|
||||
**证据。** [`src/project/mod.rs`](../../src/project/mod.rs)每次扫描目录;[`src/sema/ir.rs`](../../src/sema/ir.rs)重新读取并解析项目文件;view 和 MLSP 每次查询也可重新编译。`ProjectRoot::source_files` 特别处理 symlink,但没有明确的路径环/别名去重、资源上限与增量失效协议。当前规范虽列 1k/10k/100k 指标,却没有基线值和可接受阈值。
|
||||
|
||||
**规划缺口。** 项目发现、Symlink、外部 import、生成目录、并发编辑、overlay、缓存一致性和诊断聚合缺少一份可测试的**规模与信任边界规格**。
|
||||
|
||||
**决策与交付。** 先定义约定式项目发现、源文件唯一性、遍历深度/文件大小上限、外部来源许可和增量失效键;单文件与普通项目免额外注册,只有边界无法由约定表达时才要求显式 manifest。再建立 100/1k/10k 项目生成器、冷/热构建计时和内存基线;超过阈值的操作降级为明确诊断,不能静默跳过或返回旧图。MLSP overlay 要么被安全纳入快照,要么显式拒绝且不宣称即时编辑验证。
|
||||
|
||||
**验收。** 扫描顺序与重复路径不改变身份;symlink 环不挂起;修改单文件只失效正确下游;缓存损坏后结果与全量构建一致;目标机器上的时间与内存阈值由基准结果确定后固化进 CI。
|
||||
|
||||
## 7. 依赖顺序与可合并切片
|
||||
|
||||
| 切片 | 前置 | 作者 / AI 可见交付及工程关联 | 可复核的完成证据 |
|
||||
|---|---|---|---|
|
||||
| S0 作者基线与最小语料 | 无 | 六类实际写作/复用任务、当前语法入口、无网络最小门禁(G10/G11) | **已落地**:[tests/executable_knowledge/](../../tests/executable_knowledge/README.md) + `cargo test --test executable_knowledge` |
|
||||
| S1 可读步骤与唯一目标 | S0 | 一份文档的源码/步骤/view 联动;统一 resolver、图与上下文节点(G01/G03) | **已落地**:G01 双图分离;G03 步骤 kind + NarrativeRef(`11-narrative-ref`)+ view 导航;同名 import resolve |
|
||||
| S2 确定执行与早期 AI 复用 | S1 | BoundCall 双后端、最小上下文卡、本地 handle 与现有 Agent 试点(G02/G06/G07/G09 的安全子集) | **已落地**:G02 BoundCall;G06 效应;G07 MLSP bind/execute;eng_reuse `bind_required` |
|
||||
| S3 局部编辑与库可读性 | S1–S2 | 摘要保护的局部补丁、语义 diff、受限纯表达式提取;lib/ext 示例优化(G03/G09/G10/G11) | **已落地**:`artifact.patch` + wording 回滚;`artifact.extract_pure` 纯表达式预览;全库润色仍可选后续 |
|
||||
| S4 业务知识与适用性 | S2;与 S3 可交错 | 书店契约、来源/验证事件、传递效应及政策、负知识(G05/G06/G07/G09) | **已落地**:来源/过期;`13-bookstore` + `examples/executable-knowledge` 发票链 `113`;负知识文档 |
|
||||
| S5 变化传播与严格复用 | S1–S2/S4 | 分类摘要、SCC 闭包、整代快照、impact、严格 handle 复核(G04/G08) | **已落地**:`generations/`+`CURRENT`;锁 `classes`+`closure`;impact 含 narrates;依赖变更推动 closure |
|
||||
| S6 生态验收与发布 | 按发布声明选择 S1–S5 范围 | 全仓兼容矩阵、可运行端到端示例、平台冒烟、作者/AI 指标(G10/G11/G12) | **已落地**:CI;扫描上限;100 单元语料门禁;CLI version/check/knowledge 冒烟 |
|
||||
|
||||
每切片完成时同时更新 [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)的实现状态、相关示例及本表;只改文档状态不算完成。S1/S2 先用**无 LLM、无网络、无插件**测试证明确定性协议,随即接现有 Agent 验证实际复用;不等所有治理工程结束。G10/G11 是每片持续门禁,100 单元语料逐片增长;G04 的并发一致性必须在开放并发消费前完成,不能因为列在 S5 就忽略前置风险。
|
||||
|
||||
G12 大规模优化与远程凭据服务按场景安排;远程执行若开放,其授权测试就是硬前置。H4b MCP HTTP、dense embedding、更多语言糖和全面本体推理均不阻塞本地链。任务拆分、模块落点和作者验收详见[指导 §7](../design/document-native-development-guide.md#7-交付切片每片都有文档作者与-ai-能看见的结果)。
|
||||
|
||||
## 8. 横向验收场景与发布条件
|
||||
|
||||
### 8.1 必须固定的四个故事
|
||||
|
||||
1. **两文档事实**:李白出生年份定义、同名冲突、显式 import、正文惰性引用、来源变更、锁拒绝;验证“文档即知识库”。
|
||||
2. **订单定价**:来源政策→税率/折扣→多步计算→正文解释;对每个 `[]()` 生成步骤,修改上游后 `impact` 找全下游;验证“知识可执行”。
|
||||
3. **权限反例**:取一个无明显危险词的用户函数,内部经标准库/插件包装写文件或请求网络;静态未知或效应传递阻止静态预览和纯策略执行;验证默认安全。
|
||||
4. **Agent 已有能力复用**:先存在 ready 制品,再给相似需求;Agent 发现后精确绑定并执行,trace 中有 SymbolId、摘要与结果,仓库不增加同义函数;再加入过期/不适用候选并验证拒绝。
|
||||
|
||||
每个故事覆盖成功与拒绝、Tree/Bytecode(执行适用时)、CLI/MLSP、view、生成图及清缓存重建。旧版本迁移另保存输入、输出、诊断和 effect 的对照;不以“测试通过”掩盖输出语义改变。
|
||||
|
||||
### 8.2 完整可执行知识声明的门槛
|
||||
|
||||
- 100 单元确定性夹具和四个故事在 CI 全绿;正文静态路径外部 effect 计数为零。
|
||||
- 静态调用图与运行 trace 的 target ID 一致;两后端的值、目标、诊断一致;动态调用在结果中明确标记。
|
||||
- 任何模糊/同名、unknown effect、无效适用性、过期 lock、缺失必需证据都不能被自动标为 ready。
|
||||
- Agent 在已有适用能力的任务上实际执行 bound handle,且错误复用率、重复实现率与当前 EKC 基线同时报告;保存数据和失败样本。
|
||||
- `lib/ext/public/examples` 当前语义全仓通过,安装包中的 CLI、标准库、扩展库版本和示例行为一致。
|
||||
- README、教程、Skill 与目标示例明确区分已实现、实验性与设计态;运行示例由 CI 执行。
|
||||
|
||||
这些是完整链的门槛,不要求每次修补版等完整链全部完成。受限本地复用可在 S1/S2 对应正负例和兼容门禁通过后按精确范围发布;严格业务复用增加 S4/S5,远程执行另验授权和隔离,见[分层声明](../design/document-native-development-guide.md#83-发布声明分层)。未完成项不得被笼统“可执行知识已实现”覆盖。目前仍应表述为:**v2.1 已提供文件级新语法、项目索引与语义制品初版;知识验证和 Agent 复用闭环仍在建设。**
|
||||
|
||||
## 9. 明确的非目标
|
||||
|
||||
- 不要求作者为每个函数写一份重复的机器配置;优先从现有 Markdown、契约表和调用解析推导。
|
||||
- 不要求每个取元、循环或纯工具函数都附现实世界证据;只有声称业务事实成立或需要高信任复用时才提高证据门槛。
|
||||
- 不以 LLM 的模糊判断替代符号绑定、类型检查或权限授予;LLM 可选择精确候选、组合、编辑、适配和补测试,编译器校验实际目标与语义,宿主执行权限上限。
|
||||
- 不把 `Type`、`Entity`、`Fact`、`Function` 强行折叠为“类”;兼容现有 `#`/`##` 表面,语义类型在 IR 中清楚区分。
|
||||
- 不把 v2.1 的发布回退为未完成,也不把历史路线图的 `done` 自动推广为本路线的完成。
|
||||
@@ -3,7 +3,7 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Q0–Q7 完结 · Q8a/Q8b 完结 · Q8c 待做** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 日期 | 2026-08-28 · 2026-11-08 手册闭环 |
|
||||
| **锁定设计** | [design/ext-quantum.md](../design/ext-quantum.md) |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) |
|
||||
| 安装 | `marqdo ext add quantum`(`quantum` / `量子`) |
|
||||
@@ -41,6 +41,8 @@
|
||||
|
||||
---
|
||||
|
||||
2026-11-08:双语 index 已补完整实验、开发路线与真实契约;新增手册源示例的双后端测试。使用与开发从[根入口](../../ext/quantum/index.mq.md)开始,修改动机见[手册优化记录](../design/ext-quantum-handbook.md)。
|
||||
|
||||
## 3. 已收敛的原开放点
|
||||
|
||||
| 原疑问 | 锁定结论(见设计文) |
|
||||
@@ -48,7 +50,7 @@
|
||||
| 并进 math? | **否**,独立 `ext/quantum` |
|
||||
| 电路表 | **要做**(Q3),与方法链等价 |
|
||||
| view 图 | 自绘 SVG;优先 `host_query("record_plot")`;不依赖 web |
|
||||
| 自由函数面 | **不**与对象面并行 |
|
||||
| 自由函数面 | 普通函数供 `call`,对象方法保留作者链;共用既有 ABI,见[手册修正](../design/ext-quantum-handbook.md) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# 库源码叙述式重构验收
|
||||
|
||||
本轮以[可执行开发指南](../library-development.mq.md)为准,覆盖 lib 与 ext 的全部 mq 源码。
|
||||
重构前为 117 个文件、1,258 个函数或对象单元;349 个缺少契约,956 条旧显式形参声明。
|
||||
完成后为 125 个文件、1,273 个单元。其中 61 份公开标准库保持单文件结构,提供 650 个函数;
|
||||
另有 lint 库单元。数据、安全、网络、线性代数和 AI 补齐工程入口,独立多文件职责由 index 组织。
|
||||
原工作区阅读器改动及本轮之前的功能实现保留。
|
||||
|
||||
- [x] 标准库保持单文件,赋值、调用与返回融入叙述,宿主调用有动作说明。
|
||||
- [x] 量子、网页的契约紧接标题,入口与叶子采用同一叙述规范。
|
||||
- [x] 数据、安全、网络、线性代数补齐契约、输入来源、真实工作流与多文件索引。
|
||||
- [x] AI 补齐公开与内部单元的职责说明,解释上下文、路由、工具、工作簿和失败处理。
|
||||
- [x] 所有单元移除旧形参,参数与返回表对应真实接口;不以占位工具或固定通过标志验收。
|
||||
- [x] 逐函数严格检查叙述超过 50%,行内表达式与绑定数据表仍计作代码。
|
||||
- [x] 既有接口与实际行为回归;真实工作流和源码示例在 Tree、Bytecode 执行。
|
||||
- [x] 扩展安装清单包含新入口及其源文件依赖,精简构建、WASM 与全量回归通过。
|
||||
|
||||
源码与工程组织
|
||||
|
||||
标准库不增加强制 index 或平行手册层。每个函数先给参数与返回契约,再说明输入、
|
||||
调用效应、用途、边界与实现。新 table.from_pairs / 表.键值转记录将较宽的具名记录改为
|
||||
可读的 key/value 行表;空列表、空值、重复键更新、键顺序与输入不可变性均有双后端验证。
|
||||
|
||||
拓展库入口解释任务选择、依赖、权限、结果跨步骤传递与开发归属。网页继续采用递归布局:
|
||||
首页拆导航、主体、页脚;页脚与链接的双栏继续拆,直到内部只是单一 Markdown 内容职责。
|
||||
父 index 只负责一层关系,叶子保留普通正文。已有双语参考站点验证真实嵌套、预览、服务与 API。
|
||||
|
||||
AI 中的静态提示、目录与工作簿片段改为普通表格数据,保留原字符、字段顺序和换行;
|
||||
真正的传输 JSON 仍交给 JSON 库解析。复杂函数解释决策顺序、工具授权、上下文预算、
|
||||
事件收集、去重账本和写回责任。中文单步的 sandbox 参数只附加配置行,实际隔离需调用
|
||||
CoW 试跑;工具名解析的半角冒号边界也已如实说明。
|
||||
|
||||
兼容性审核
|
||||
|
||||
[审核器](../../examples/library_audit.rs)使用真实解析器,对比参数顺序、默认值、对象层级、
|
||||
接收者、控制流与计算。遮蔽标签不参与执行;审核只对明确支持的纯常量构造做等价折叠,
|
||||
重复 JSON 键、不安全数值、非常量与未知调用均不会被当作等价常量。折叠规则有独立测试。
|
||||
原始源码快照保留在本次执行环境的临时目录;它不是另一套工具签名或运行时协议。
|
||||
|
||||
对比只有三项旧缺陷修复产生的八条 AST 差异,其余既有单元的参数、默认值与规范化执行结构一致。
|
||||
[精确修复记录](library-authoring-reviewed-fixes.json)保存差异名称、修复前后摘要与原因;
|
||||
审核器只接受摘要完全匹配的记录,新增差异或失效记录都会失败。
|
||||
|
||||
| 旧问题 | 实际修复与验证 |
|
||||
|---|---|
|
||||
| 中文单步说明中的斜体 map 被当作提前返回,实现错误落入构造器 | 说明恢复为文字,单步真正执行;离线模型替身验证上下文调用与最终结果 |
|
||||
| 事务构造器返回未绑定的 self | 用实际 txn 与 url 构造句柄;验证提交、回滚及事务外读取,不额外开启事务 |
|
||||
| 策略说明标题被误认成对象,main 返回未绑定的 routes | 恢复说明与真实 routes 工具,main 调用它;验证 lookup 和默认后端,文件后缀保持文字 |
|
||||
|
||||
执行证据(2026-11-08)
|
||||
|
||||
| 检查 | 结果 |
|
||||
|---|---|
|
||||
| `cargo test --offline --test library_authoring` | 5 项通过;覆盖全部 125 份源码与 1,273 单元、包工作流、旧缺陷、双语记录与安装依赖 |
|
||||
| `cargo test --offline --test stdlib_tasks --test quantum_handbook --test web_handbook` | 18 + 4 + 3 项通过;源码中的真实命令与作者程序在双后端运行 |
|
||||
| `cargo run --offline --quiet --example stdlib_catalog -- --check` | 650 个公开函数,0 条效应说明需要更新 |
|
||||
| AST 原始快照对比及精确修复记录检查 | 8 条已审查修复差异,0 条未解释差异,0 条失效记录 |
|
||||
| `GOFLAGS=-buildvcs=false cargo test --offline --all-targets` | 982 通过、0 失败、2 个原有忽略项,包含千文档编译与 312 项金样例 |
|
||||
| `cargo check --offline --no-default-features --features wasm-core` | 通过;保留已有未使用代码告警 |
|
||||
| 版本匹配工具链的实际 wasm32 构建与 Node 验收 | ABI、桥接、标准库、32 位边界、双语记录、转义表格及句中遮蔽计算通过 |
|
||||
| `git diff --check` | 通过 |
|
||||
|
||||
GOFLAGS 仅用于当前命令绕过工作区所有权引起的 Go VCS 盖章问题,不修改全局配置。
|
||||
WASM 使用临时目录中版本匹配的官方工具链;不以本机编译代替真实 wasm 运行。
|
||||
网络和身份提供方示例使用离线数据或本机可控服务;没有把构造配置、清单或演示结果
|
||||
宣称成生产服务已验证。Node 验收不代表重新完成浏览器 DOM 几何验收。
|
||||
@@ -0,0 +1,50 @@
|
||||
[
|
||||
{
|
||||
"after": "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",
|
||||
"before": "754acb518e0d5f0c5c6f6ae6d48c94a1df69ddbdfff13395114786cbe63edf5e",
|
||||
"difference": "removed ext/ai/policies/step-route.mq.md \"Step class → backend\"",
|
||||
"reason": "修复说明标题被误认成对象、路由表未绑定且 main 返回未定义 routes;真实 routes 工具返回原策略数据,沙盒行文件后缀显式写为文字。双后端验证 lookup 和默认后端。"
|
||||
},
|
||||
{
|
||||
"after": "62bd87e62802aeaefbc635715481451d5eee3b918aefe8db9c816039ef91b04f",
|
||||
"before": "f6c5aecc836c461f7593ffabe9cc2c236a3738a90c49c9c2b5c12a767d97c94c",
|
||||
"difference": "ext/ai/policies/step-route.mq.md \"main\" changed body",
|
||||
"reason": "修复说明标题被误认成对象、路由表未绑定且 main 返回未定义 routes;真实 routes 工具返回原策略数据,沙盒行文件后缀显式写为文字。双后端验证 lookup 和默认后端。"
|
||||
},
|
||||
{
|
||||
"after": "fcbcf165908dd18a9e49f7ff27810176db8e9f63b4352213741664245224f8aa",
|
||||
"before": "b5bea41b6c623f7c09f1bf24dcae58ebab3c0cdd90ad966bc43a45b44867e12b",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体\" changed receiver",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "888398739b40074de2e2f93943516541eec872cecc284835968650b3ef72a24d",
|
||||
"before": "a7553f00f8f05c97c2c44299fd2fcd4641c8f5e9acbb6a246874b096a2acdc0a",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体\" changed body",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "b5bea41b6c623f7c09f1bf24dcae58ebab3c0cdd90ad966bc43a45b44867e12b",
|
||||
"before": "fcbcf165908dd18a9e49f7ff27810176db8e9f63b4352213741664245224f8aa",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体.单步\" changed receiver",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "e3853fac627ca88f1557132aabb6b818ecc805ab53e6feacb3b08c77e503ece4",
|
||||
"before": "aae371909b83bdaec63671897c5581a8ba7f14a5e113bd825fca0576df403e2b",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体.单步\" changed body",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "fcbcf165908dd18a9e49f7ff27810176db8e9f63b4352213741664245224f8aa",
|
||||
"before": "b5bea41b6c623f7c09f1bf24dcae58ebab3c0cdd90ad966bc43a45b44867e12b",
|
||||
"difference": "ext/data/db.mq.md \"txn\" changed receiver",
|
||||
"reason": "事务构造器原来返回未绑定的 self;改为保留调用者传入的真实 txn 和 url 句柄,不额外开始事务。双后端验证构造、提交、回滚与事务外读取。"
|
||||
},
|
||||
{
|
||||
"after": "0a51bc7e7fe4577f32aae9a76ea461213c3547ea9e937f280e17b6e8075194c5",
|
||||
"before": "92096850522e76cff3350d582b57ae3124fd400635ad25fd63f208a1994514f0",
|
||||
"difference": "ext/data/db.mq.md \"txn\" changed body",
|
||||
"reason": "事务构造器原来返回未绑定的 self;改为保留调用者传入的真实 txn 和 url 句柄,不额外开始事务。双后端验证构造、提交、回滚与事务外读取。"
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,250 @@
|
||||
# Marqdo 支撑求道知识沉淀与文档编译的框架缺口
|
||||
|
||||
| 项目 | 基线 |
|
||||
|---|---|
|
||||
| 日期 | 2026-10-24 |
|
||||
| 框架源码 | `b8a4ddd`,Cargo 声明 2.1.1 |
|
||||
| 消费者源码 | 工作区 qdagent,`7f8f19d` |
|
||||
| 文档性质 | 当前源码复核、实测反例和增量建议;不重开已完成的 S0–S6 工作 |
|
||||
| 配套文档 | [求道产品侧缺口](../../../qdagent/doc/gaps/03-knowledge-ingestion-and-sedimentation-2026-10-24.md) |
|
||||
| 设计依据 | [文档原生开发指导](../design/document-native-development-guide.md)、[既有缺口路线](executable-knowledge-gaps-2026-10-23.md) |
|
||||
|
||||
## 1. 核心判断
|
||||
|
||||
Marqdo 已具备让求道采用文档原生知识的主要语言和执行基础。求道尚未接入的能力,不能统称为“框架不支持”。本轮框架侧优先工作是:**让生成知识的语言指导可信,让来源和验证真正约束发布与复用,让新语义制品进入默认 Agent 链路,并提供文档导入所需的通用适配接口。**
|
||||
|
||||
`knowledge` 编译的是已有源码和声明,不是把任意 PDF/DOCX 自动变成正确知识的转换器。上传、抽取、模型建模、语义编译、验证、发布是不同阶段。语义编译器保证程序和依赖的确定性;来源支撑、业务适用性以及领域审阅需要明确证据,不能由成功退出或 LLM 自述推导。
|
||||
|
||||
现有 [2026-10-23 路线](executable-knowledge-gaps-2026-10-23.md)的审计基线较早,之后已有多次实现提交。本文件按当前源码重新划分:已实现、有限子集、仍有断点;不照抄旧文档中的“无正文引用”“未知效应全为 pure”“两图互相覆盖”等历史判断。
|
||||
|
||||
## 2. 当前可直接复用的能力
|
||||
|
||||
| 能力 | 当前证据 | 给求道的边界说明 |
|
||||
|---|---|---|
|
||||
| 默认 Occlusion、`access`、显式遍历 | [核心表面](../design/core-surface.md)、[基线 01–04](../../tests/executable_knowledge/README.md) | 求道须迁移旧取元;无需增加新语法 |
|
||||
| 函数、契约、表格、import、关联函数 | `src/parse/`、[check.rs](../../src/check.rs)、[sema/bind.rs](../../src/sema/bind.rs) | 支持编写可复用知识;不是所有知识都要塞进 main 或建类 |
|
||||
| 项目身份、语义制品、绑定调用 | [project](../../src/project/mod.rs)、[symbols](../../src/sema/symbols.rs)、[IR](../../src/sema/ir.rs) | 已有 SymbolId/ArtifactId、BoundCall/DynamicCall;消费方不另造执行身份 |
|
||||
| 语义图与检索图隔离 | [knowledge/compile.rs](../../src/knowledge/compile.rs) | 权威语义 `graph/` 与检索 `ekc/graph/` 已分开,旧覆盖问题不再作为未实现项 |
|
||||
| 知识步骤、正文引用、view | `collect_named_steps`、NarrativeRef、现有集成测试 | 已含 observe/derive/iterate/call/narrate/navigation 子集;正文引用保持惰性 |
|
||||
| 来源与适用期初版 | [provenance.rs](../../src/sema/provenance.rs) | 已解析 `sources` block list、region、valid_until;sourced 不等于事实已经验证 |
|
||||
| 精确绑定与本地执行 | [mlsp.rs](../../src/mlsp.rs) 的 artifact.find/inspect/bind/execute | 已有摘要及 SymbolId 检查、按源行定位函数、pure 效应门槛;剩余失效问题见 M02/M03 |
|
||||
| 局部修改 | MLSP artifact.patch / artifact.extract_pure | 已有摘要保护、措辞修改守卫、纯片段提取;不应要求模型每次重写整库 |
|
||||
| 整代语义投影、锁、影响 | `write_semantic_projections`、[lock.rs](../../src/sema/lock.rs) | 已有 generations/CURRENT 与多类摘要;覆盖边界及实测失败见 M02/M06 |
|
||||
| Agent 工作簿、技能、沙箱 | [ext/ai/agent](../../ext/ai/agent.mq.md)、[plugins/agent](../../plugins/agent/src/lib.rs) | 可复用 Runtime、CoW、工具协议和诊断修复;求道不另建 Agent loop |
|
||||
| 文件上传/存储 | [storage.mq.md](../../ext/data/storage.mq.md)、[routes_media.go](../../plugins/web/internal/httpx/routes_media.go) | 已有上传路由、类型/大小验证和保存;不等于文档知识转换已存在 |
|
||||
|
||||
本轮离线执行 `cargo test --offline --locked --test executable_knowledge`:**25 passed / 1 failed / 0 ignored**。通过项包括双后端基线、绑定复用、正文引用、来源状态、局部补丁、100 单元和 CLI 冒烟。失败项为 `s5_closure_digest_moves_with_dependency`,单独重跑仍失败。存在大量有效基础,也存在需要先处理的失效缺口。
|
||||
|
||||
## 3. 框架缺口与可验收交付
|
||||
|
||||
### M01 · P1:上传底座尚未形成文档提取与来源映射协议
|
||||
|
||||
**现状。** Web 插件已注册 `web_upload_validate/save/app_upload`,`handleUpload` 接收 multipart 并存储字节。本轮在 `src/`、`plugins/`、`ext/` 的搜索未找到可供求道直接调用的 PDF/DOCX/OCR → 标准化正文 → 页段来源映射的完整链路。不要把 HTTP 文件保存或 `knowledge compile` 命令包装成已有文档转换器。
|
||||
|
||||
**建议。** 在扩展/插件层定义通用 `DocumentSource → ExtractedDocument` 协议,字段至少包括原件 URI/摘要、格式、提取器版本、段落/表格/页码定位、可提取文本、缺失部分、置信度及诊断。先支持 text/Markdown;PDF/DOCX/OCR 可通过独立插件或受控外部提取器接入。格式解析留在扩展,语言核心不引入 OCR 或模型业务。
|
||||
|
||||
知识生成由求道选模式、检索既有知识、调用模型并提供 patch;框架提供 compile/diagnostics/sandbox,而不是默默替作者推断领域真相。转换的外部程序必须服从宿主权限和资源边界。
|
||||
|
||||
**现有上传实现需补强的具体点。** `handleUpload` 先 `ParseMultipartForm(32 << 20)`、`io.ReadAll`,再按完整字节数做 Validate;32 MiB 是 multipart 内存阈值,不是请求总量硬限。应在解析/读取前限制请求与文件字节数,采用受限流式读取,并测试清理临时文件与失败路径。已有类型/路径验证应复用,不能将此描述为“没有任何上传校验”。
|
||||
|
||||
**验收。** 对文本、表格、跨页、坏编码、空文档、密码 PDF、扫描件、超限文件分别返回成功/部分/失败;每条抽取事实都可定位回原件;上传 `.mq.md` 不自动执行;相同文件及提取器版本输出可比较,重试不产生不同身份。
|
||||
|
||||
**责任。** Marqdo 提供提取与存储适配规范;求道负责上传界面、任务进度、知识库选择、发布政策与业务模型。
|
||||
|
||||
### M02 · P0:来源与依赖变化未完整进入摘要、锁与执行失效
|
||||
|
||||
**来源反例(实测)。** 2.1.1 下给函数声明 `sources: source.md#missing-anchor`,实际文件存在但锚点不存在,仍得 `evidence=sourced`;business bind 成功。修改 source.md 后 SourceRef.content_digest 变化,artifact.hashes.artifact 不变;旧 handle 继续执行。删除 source.md 后,旧 business handle 仍执行并返回原值。
|
||||
|
||||
**源码原因与边界。** [provenance.resolve_provenance](../../src/sema/provenance.rs)将 `#anchor` 存为 locator,但没有校验锚点;对来源文件计算哈希后,[IR artifact_for_function](../../src/sema/ir.rs)仍用 `digest(contract_summary(&contract))` 构造 evidence 摘要,没有包含来源内容和适用条件。`artifact.execute` 重编译并比较自身 artifact 摘要,但不重验 handle.policy 对应的证据状态。来源改变、来源删除、时间到期可以不改变函数实现,因此自身摘要检查不足。
|
||||
|
||||
**依赖反例(实测)。** [现有集成测试](../../tests/executable_knowledge.rs) `s5_closure_digest_moves_with_dependency` 中 `main` 调用 `d.rate()`,仅将被依赖函数返回值从 0.13 改为 0.14;测试读取到的 main closure 摘要未变。已重复验证。这里只确认该夹具失败:需要区分符号/模块同名选择、依赖边和闭包算法各自责任,不据此直接断言所有函数闭包都失效。
|
||||
|
||||
**其他源码缺口。** bind/execute 传递的是自身 `hashes.artifact`,没有把已有 `hashes.closure` 纳入句柄复核。`lock.impact` 从制品定义文件和依赖/正文边找反向影响,未把 `provenance` 的外部 corpus URI 纳入来源反向边。
|
||||
|
||||
**交付。**
|
||||
|
||||
1. evidence 摘要包含规范化来源 URI、定位、内容摘要、提取器/验证版本及适用性;锚点不存在返回不同于文件缺失的诊断。读取错误不能以空文件摘要冒充成功。
|
||||
2. 修复上述闭包失败,并明确 type/module/function 的身份与测试选择。依赖递归/环用确定的 SCC 或等价闭包摘要规则;无关文件增删不应导致任意漂移。
|
||||
3. 句柄记录并复核所需的依赖闭包、证据、政策及有效期;execute 重验 business/pure 等政策,不只相信 bind 时的状态。文件变化与时间变化都能使句柄失效。
|
||||
4. 将 corpus → artifact → caller/answer 的影响关系纳入同一编译结果,来源改动能查询受影响对象;报告接口、实现、证据、依赖分别发生了什么变化。
|
||||
|
||||
**验收。** 仅修改来源、删来源、改锚点、时间越过有效期、改直接/传递依赖都拒绝不再有效的句柄;原有测试恢复通过。不得为让测试变绿删除断言或改成只检查命令成功。普通无业务来源要求的纯函数仍可按相应政策执行。
|
||||
|
||||
### M03 · P0:验证 API 尚不是可发布知识的完整判据
|
||||
|
||||
**现状。** `VerificationRecord` 已分 parse/resolve/contract/execution/tests/evidence/domain,但 `semantic_artifact` 的默认值仍包括 `contract=unchecked`、`execution=not_run`、`tests=unknown`、`domain=unreviewed`、`lifecycle=draft`。MLSP `artifact.verify` 主要返回编译记录并附 policy,没有实际执行对应测试或回写证据。不能把它宣传为已经验证业务事实。
|
||||
|
||||
`artifact.bind(policy=business)` 接受 sourced/verified,尚未检查 region 与本次输入、单位、前提、输入域等;`provenance` 用日期字符串比较有效期,没有完整日期格式校验。当前“business”至多表示来源已关联且未被判过期,不等于适用性或事实成立。unknown policy 字符串也未通过枚举校验形成明确拒绝。
|
||||
|
||||
`knowledge verify` 检查的是旧 EKC 结构一致性;`conflicts/stale` 是报告命令,`duplicate` 的默认行为也是报告。它们都有价值,但消费方不能从退出码 0 得出“候选可晋升”。求道正存在这种误用。
|
||||
|
||||
**交付。** 给调用方稳定的验证结果结构:验证对象/摘要、所选政策、每个检查的 passed/failed/unknown/skipped、证据记录、阻断原因、是否允许绑定或发布。测试运行器生成执行/断言事实;来源存在、引文一致、计算正确、领域结论分别报告。政策和结果字段应有版本化 schema,未知政策拒绝。
|
||||
|
||||
保留报告命令兼容性,提供清晰的机器裁决入口或明确 fail 选项;不要悄悄改变已有 CLI 的退出语义。发布政策可渐进:纯工具先证明程序行为,业务事实额外要求来源与适用条件,领域审阅按场景要求;不为所有函数强加人工审批。
|
||||
|
||||
**验收。** `sandbox failed`、模型声称“passed”、空证据、无效日期、地区不符、输入越界、测试未运行均不能被标成对应级别的 verified;缺证据与执行失败不同;实际通过的记录绑定内容摘要,修改后自动失效。
|
||||
|
||||
### M04 · P1:新语义复用协议尚未进入默认 Agent 学习与执行闭环
|
||||
|
||||
**现状。** [plugins/agent/eng.rs](../../plugins/agent/src/eng.rs) 的 `eng_reuse`、[knowledge/reuse.rs](../../src/knowledge/reuse.rs) 已输出 `discovery_only`、`bind_required`、`bind_targets`。这是真实进展,不再列为完全缺失。
|
||||
|
||||
但 [ext/ai/agent.mq.md](../../ext/ai/agent.mq.md) 的默认 `run` 仍以 route/resolve、agent-kb workbook、plan 为主;EFI 分支主要检查 create_allowed,未在该编排中找到 artifact.bind/execute 的完整消费。`run verify=True` 依据 `status==ok` 拼接 `verification="status: passed"`;随后可 maybe_learn/promote,并非调用 M03 所需的验证器。求道 BUILD 开启 `learn=True/promote=True` 后才做自己的 docgate,因此两层发布时序有冲突风险。
|
||||
|
||||
`build_step_context` 的 CALL 白名单只有名字协议;parent CALL 支持 ARGS 的能力与 step 工具路径不同。求道若要调用精确制品与输入,需要正式适配,不能在提示词中虚构已可调用的工具。
|
||||
|
||||
**交付。** 提供现有 Runtime 内的适配步骤:discover → inspect → bind → execute → record。执行工具使用宿主选择的 project/KB/policy,LLM 只提交候选及输入。REUSE 只有在绑定执行成功且有 trace 后计为实际复用;ADAPT 用现有 patch/extract 形成可审阅修改;CREATE 保留检索范围与原因。
|
||||
|
||||
提供产品可接入的发布前验证钩子或 candidate-only 模式:产品门禁失败时框架也不能先把技能标为可复用。知识文件、技能、episode 可以保留不同存储职责,但都关联同一版本化 artifact/evidence;不要新增另一套知识语义。
|
||||
|
||||
**验收。** 用真实 `agent.run` 编排和确定性假模型/工具响应验证,而不只直调 MLSP:已有知识被调用、无同义实现新增;错误来源/错输入被拒绝;验证失败无 promote;trace 对应符号、摘要、输入与输出。不得将 n-gram 高分或字符串 REUSE 当作成功。
|
||||
|
||||
### M05 · P0/P1:提供给模型的语言 Skill 与当前语法冲突
|
||||
|
||||
**源码事实。** [skills/marqdo/SKILL.md](../../skills/marqdo/SKILL.md) 前部 Hard rules 2/4 和 v0.2 表仍写“粗体是返回”、斜体是语句,旧 `[key](map)` 取元也仍在前部。后面虽有 v2.1 默认 Occlusion 段落,不能消除同一提示包的冲突。
|
||||
|
||||
[host/agent_rt.rs](../../src/host/agent_rt.rs) 的 `load_marqdo_skill/read_skill_pack` 加载 Skill/reference/examples;[agent.skill_brief](../../ext/ai/agent.mq.md) 默认只取前 1200 字符/80 行,deep 预算 4000 字符。因此旧规则可能优先进入窗口,新的说明反而被截掉。实际读取哪个包受 MARQDO_SKILL 和搜索路径影响,部署须记录真实来源,不能假定总在读工作区文件。
|
||||
|
||||
**交付。** 从现行核心表面、解析器与金样例维护一份版本化语法卡片,最前面即当前含义:`**…**` 代码、`*…*` 返回、`[描述](payload)`、`access`、显式 import/遍历、正文惰性。旧语法迁入独立迁移卡片,不继续与默认规则并列。模型可按需取契约、来源、表格、类/函数等卡片;语言核心规则和权限边界不可被预算截掉。
|
||||
|
||||
使用已有 MLSP syntax/schema/validate/repair 能力,但明确 validate 的范围:当前主要是契约/标签检查,不等于完整事实、所有变量/调用和业务验证。诊断附 span、相关源码、目标语法版本及建议修复范围;优先局部 patch,避免整篇重生成。
|
||||
|
||||
**验收。** `dump_step_context` 和 plan 上下文的脱敏快照中没有冲突规则;基础/deep 预算均保留必需语法。卡片中可执行示例在当前 CLI 双后端通过;同一批含旧取元、错误返回、表格几何误用、缺 import 的负例给明确诊断。记录实际 skill path/hash、CLI/Ext/schema/prompt 版本。
|
||||
|
||||
### M06 · P1:整代发布已存在,但扫描范围与消费者一致性仍需约束
|
||||
|
||||
**现状。** [IR](../../src/sema/ir.rs)已将语义投影写 generations,再原子替换 CURRENT;遵循 `semantic_generation_dir` 的读者可获得完整语义代。但随后还写根目录兼容镜像,[knowledge.compile](../../src/knowledge/compile.rs)另写 engineering.yaml / ekc 等检索投影;不能把语义代原子性推广为“所有消费者、所有索引都属于同一代”。并发构建共用 CURRENT.tmp、.tmp-sema-publish,需明确串行化或独占发布规则。
|
||||
|
||||
[project 扫描器](../../src/project/mod.rs)与 [EKC extract](../../src/knowledge/extract.rs)的排除集不同,后者遍历子目录时排除 data/docker,前者不排除 data。求道有多个原文、候选和运行目录,导入 `.mq.md` 后可能在不同消费者里出现不同可见性。已有 .marqdo 排除、深度/文件大小/数量限制值得保留,但尚不能替代显式源范围和信任范围。
|
||||
|
||||
**交付。** 项目配置声明 authored sources、corpus、draft/generated 的范围;语义、EKC、Agent/view 使用同一选择规则。发布 manifest 关联语义代、检索代、源码/证据摘要和 schema;消费者拒绝混代并能回退到旧完整代。多库使用独立项目身份,索引聚合不扩大执行文件范围。
|
||||
|
||||
**验收。** 暂存上传代码不会进入活动能力;data/ 路径不会因消费者不同而忽隐忽现;并发编译/失败注入期间读者只看到一套可用版本;旧索引可重建,源文档不受损。迁移期明确旧 graph 路径兼容期限。
|
||||
|
||||
### M07 · P1:来源粒度和知识类型不足以覆盖文档沉淀
|
||||
|
||||
**现状。** 来源主要来自模块 frontmatter,容易将一整篇资料附给该文件所有函数;SourceRef 有 uri/locator/digest,但缺少标准的“具体断言 → 原文片段/表格单元/页码 → 提取版本”关联。普通 EKC `KnowledgeKind` 有 Fact/Decision/Constraint 等,而语义 artifact 主要是 module/type/function;旧 `.md` Fact 的存在不等于可调用事实函数。作者写来源 inline list 时当前解析器会忽略,未知字段也缺少强诊断。
|
||||
|
||||
**交付。** 用现有 Markdown/frontmatter/契约表定义轻量知识约定,而不增加求道专属语法:可选的函数/断言级来源、适用范围、单位、负例、冲突/取代关系。明确知识内容类型与运行时类型的区别;事实可以是返回值、规则可以是函数、决策可以是声明性文档,类只用于真实模式复用。
|
||||
|
||||
由编译器生成身份、图边和 SourceRef,作者只维护实际内容与必要来源。为 plain note → draft fact/rule → verified callable 提供金样例和机器可读投影,不能仅把文本包在一个 print 中。字段不支持或位置错误时给诊断,避免“写了来源,编译却无声忽略”。
|
||||
|
||||
**验收。** 一文多来源、一事实多来源、原文冲突、缺失字段、单位不同、来源片段变化、声明性决策和可执行规则都能区分;无依据的信息保持 unknown;不要求每个纯工具函数带业务来源。
|
||||
|
||||
### M08 · P1/P2:生成式知识验收与真实复用评估不足
|
||||
|
||||
**现状。** 既有 26 项集成测试和 100 单元是有效基础,但不覆盖资料导入/模型沉淀全过程。现有 `eng_reuse` 协议测试证明 JSON 字段,不证明默认 Agent 调用了句柄;MLSP 直调测试证明本地纯函数复用,不证明模型按正确来源建库。测试 README、旧路线和示例中存在历史状态残留;此次 closure 测试失败也说明“done”必须和当前门禁分开。
|
||||
|
||||
**交付。** 两层评测:确定性 fixtures 验证协议和失败边界,固定任务集验证模型沉淀质量。每个样本保存原文、期望知识、可执行断言、来源定位、错误复用反例、实际上下文及版本;明确事实正确率与程序运行率不同。性能指标包括编译/检索延迟、上下文规模、修复轮次、真实 token、知识重复率和误晋升率。
|
||||
|
||||
**验收。** 用同一资料完成“首次建库→再次调用→原文更新→旧知识失效→修复发布”的完整故事;包括断网/缺插件/截断/OCR 错误/资料内指令/冲突来源。只统计有目标与结果 trace 的执行复用,不按 REUSE 决策估算零推理成本。核心发布门禁不能以 skip 计成功。
|
||||
|
||||
## 4. 建议的跨库接口边界
|
||||
|
||||
下表是待实现或待稳定的契约,不暗示现在已有同名函数/CLI。
|
||||
|
||||
| 契约 | Marqdo 保证 | 求道负责 |
|
||||
|---|---|---|
|
||||
| Document extraction | 原件摘要、标准正文、定位、诊断;扩展层实现格式转换 | 上传、任务、库范围、用户预览 |
|
||||
| Knowledge draft | 当前语法卡片、检查/修复、可调用元数据 | 事实/规则选择、提示词、冲突与去重决策 |
|
||||
| Verification report | 每个检查的真实状态、证据/制品摘要、阻断原因 | 项目政策、需要人工处理的歧义、发布编排 |
|
||||
| Artifact handle | 唯一身份、依赖/证据失效、宿主能力边界 | 提交候选与输入、记录实际使用和解释 |
|
||||
| Publish manifest | 一致的语义/索引代及可回滚读取 | 知识源码发布、迁移、当前活动版本 |
|
||||
| Trace | 实际目标、输入、输出、版本与执行结果 | 回答来源展示、知识质量指标、运行记录关联 |
|
||||
|
||||
现有 `artifact.*`、sandbox、knowledge 等接口优先扩展;新增 façade 必须复用它们。工具协议、输出 schema 与提示词版本一起管理。首次本地试点可以使用固定目录与已授权项目政策;远程多租户的身份、凭据和隔离单独验收,不能把本地 MLSP 直接当公网授权协议。
|
||||
|
||||
## 5. 实施顺序
|
||||
|
||||
| 阶段 | 工作 | 完成条件 |
|
||||
|---|---|---|
|
||||
| F0 正确性基线 | M02/M03/M05:闭包反例、证据失效、验证状态、语法卡片 | 现有测试全过;来源变更/删除拒绝旧 business handle;提示词不含冲突语法 |
|
||||
| F1 最小生产消费链 | M04 + 求道文本导入:candidate-only、验证钩子、绑定执行 trace | 同一资料第一次生成,第二次实际复用,门禁失败不学习发布 |
|
||||
| F2 来源与更新 | M06/M07:统一源范围、来源定位/影响、发布 manifest | 改原文能找全受影响对象,发布失败旧版本仍可用 |
|
||||
| F3 格式覆盖与评测 | M01/M08:PDF/DOCX/OCR 适配、资源限制、模型对照 | 文档可追溯,不完整提取显式报告,效果和失败分布有数据 |
|
||||
|
||||
框架不承担求道的登录界面、笔记列表、项目业务政策;求道不复制框架的 parser、binder、effect、lock 或执行器。无需为了这条主链先完成万能本体、全格式解析或远程授权平台。
|
||||
|
||||
## 6. 本轮可复核实验
|
||||
|
||||
### 6.1 当前门禁与失败复核
|
||||
|
||||
在框架仓库执行:
|
||||
|
||||
```bash
|
||||
cargo test --offline --locked --test executable_knowledge
|
||||
cargo test --offline --locked --test executable_knowledge \
|
||||
s5_closure_digest_moves_with_dependency -- --exact
|
||||
```
|
||||
|
||||
第一条结果为 25 passed、1 failed;第二条仍在 `tests/executable_knowledge.rs:586` 报 `caller closure digest must move with dependency`。两次比较结果相同。这是既有测试的执行结果;本次未修改其实现或断言。
|
||||
|
||||
审计开始时 `target/release/marqdo --version` 与旧 debug 都是 2.1.0;上述构建生成的 debug 是 2.1.1。后续最小实验使用新 debug,不能把旧 release 输出充当当前源码能力证据。
|
||||
|
||||
### 6.2 来源变化与旧句柄复现
|
||||
|
||||
以下程序仅在新建临时目录写测试文件,通过本地 MLSP 调用,不联网、不调用模型。构建当前 debug 后在仓库根运行:
|
||||
|
||||
```python
|
||||
import json
|
||||
import subprocess
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
|
||||
binary = str(Path("target/debug/marqdo").resolve())
|
||||
root = Path(tempfile.mkdtemp(prefix="mq-source-audit-"))
|
||||
|
||||
def rpc(method, **params):
|
||||
req = json.dumps({"method": method, "params": params}) + "\n"
|
||||
proc = subprocess.run([binary, "mlsp"], input=req, text=True,
|
||||
capture_output=True, check=True)
|
||||
return json.loads(proc.stdout)
|
||||
|
||||
(root / "source.md").write_text("# rate\n\nrate = 0.13\n")
|
||||
(root / "facts.mq.md").write_text(
|
||||
"---\nsources:\n - source.md#missing-anchor\n"
|
||||
"applicability:\n region: CN\n valid_until: 2099-12-31\n"
|
||||
"---\n\n## rate\n\n*0.13*\n"
|
||||
)
|
||||
first = rpc("artifact.inspect", project=str(root), artifact_id="rate")["result"]
|
||||
handle = rpc("artifact.bind", project=str(root), artifact_id="rate",
|
||||
policy="business")["result"]["handle"]
|
||||
(root / "source.md").write_text("# rate\n\nrate = 0.14\n")
|
||||
second = rpc("artifact.inspect", project=str(root), artifact_id="rate")["result"]
|
||||
print("evidence:", first["verification"]["evidence"])
|
||||
print("source changed:", first["provenance"][-1]["content_digest"] !=
|
||||
second["provenance"][-1]["content_digest"])
|
||||
print("artifact changed:", first["hashes"]["artifact"] !=
|
||||
second["hashes"]["artifact"])
|
||||
print("after edit:", rpc("artifact.execute", handle=handle, inputs={}))
|
||||
(root / "source.md").unlink()
|
||||
print("after removal:", rpc("artifact.execute", handle=handle, inputs={}))
|
||||
```
|
||||
|
||||
本轮观察:`evidence=sourced`、`source changed=True`、`artifact changed=False`;两次 execute 均 `ok=true`、result 为 `0.13`。正确修复后,缺锚点应先阻断相应来源政策;用有效锚点重新绑定后,改/删来源也应拒绝旧句柄或要求重验。不能只修复示例中的缺锚点而遗漏来源内容失效。
|
||||
|
||||
### 6.3 求道旧取元风险
|
||||
|
||||
以下代码在默认 2.1.1 中,第一行输出整个 map,第二行输出 False:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`m` =
|
||||
|
||||
| ok | status |
|
||||
|---|---|
|
||||
| False | denied |
|
||||
|
||||
**old = [ok](m)**
|
||||
**new = access(m, "ok")**
|
||||
> print text=`old`
|
||||
> print text=`new`
|
||||
```
|
||||
|
||||
这是默认语义变化,不是框架需要回退的新语法错误。求道需迁移;框架应提供一致的迁移指导、诊断和版本信息,而不是在 Skill 中继续教授冲突的旧默认。
|
||||
|
||||
## 7. 审计限制与后续文档同步
|
||||
|
||||
本次验证是源码审查、仓库固定测试和临时输入实验;没有执行真实 LLM 的建库质量评估,没有测试线上 Web 上传或真实 PDF/OCR。M01 的“缺少转换链”限定在所审查的主代码区域,不否定外部工具可以接入。M02 的闭包根因仍需按身份、依赖图、摘要计算分层定位。
|
||||
|
||||
完成后应同步当前 Skill、README、测试 README 和路线进度:分别标记语言能力、协议子集、产品已接入、当前测试结果。优先把失败样例转成稳定回归门禁,再扩大“可验证知识”“业务复用”“上传编译”的能力声明。此次文档提交不表示缺口已修复。
|
||||
@@ -0,0 +1,60 @@
|
||||
# 标准库:可执行手册与通用能力闭环
|
||||
|
||||
目标:代码即文档,文档即 SKILL,SKILL 即 tools。AI 直接阅读任务对应的 `lib/*.mq.md` 单文件,理解输入来源、输出形态、效应、失败处理和可执行示例;保持既有导入兼容。
|
||||
本清单记录真实交付状态,未完成项不能因文档或接口占位而标为完成。
|
||||
|
||||
## 阶段与验收
|
||||
|
||||
- [x] A. 宿主效应作为唯一事实来源;直调、导入别名、中英文和双后端一致。
|
||||
- [x] A. `call` 明确授权文件读写及根目录;会话重放保留权限范围。
|
||||
- [x] A. 明确递归删除、索引基数、不可变更新、结构化可恢复错误契约。
|
||||
- [x] B. 文件筛选、行/JSON/CSV 读写、目录树复制、批量改名/同步及冲突策略。
|
||||
- [x] B. 原子/条件写入、临时目录与清理、路径相对化与扩展名替换。
|
||||
- [x] C. 序列、投影、筛选、分组/聚合、连接、按键去重/多键排序和表形态转换。
|
||||
- [x] C. 字段类型转换与记录校验;避免回调字符串求值及新集合方言。
|
||||
- [x] D. 字节与分块 IO、文件哈希、网络下载、压缩归档及明确资源上限。
|
||||
- [x] D. HTTP 响应头、可配置超时、一致的错误结果;保留既有入口兼容。
|
||||
- [x] E. 子任务超时、并发上限、批量取消与资源回收。
|
||||
- [x] E. 日期完整时区/DST、配置读写边界、规模性能。
|
||||
- [x] F. 文档章节/表格/代码块/链接提取和保留叙述的受控局部修改,复用解析器。
|
||||
- [x] G. 全标准库单文件手册、标题下参数表、叙述形参和遮蔽调用;叙述超过 50%;提供契约与真实示例;不以伪函数或叙述比例代替正确性。
|
||||
- [x] G. 三个端到端工程:文件整理、CSV 数据处理、文档维护;示例直接提取执行。
|
||||
- [x] G. 相关回归、双后端、默认/最小特性构建及平台能力矩阵。
|
||||
|
||||
## 实施约束
|
||||
|
||||
保留工作区已有的 reader 改动。通用组合优先 `.mq.md`,OS/算法边界使用小型宿主原语;
|
||||
不增加第二套 Skill 编译器、字符串 eval 或应用模板语法。递归删除保留旧入口行为,
|
||||
新增清晰的窄接口;每次修改都同时写清兼容性和失败语义。
|
||||
|
||||
## 验证记录
|
||||
|
||||
按用户澄清修正为 31 个模块族、61 份公开标准库单文件;撤除先前误增的 64 份目录与模块手册。648 个公开函数的名称、参数顺序和默认值 AST 与迁移前逐项一致;不再保留旧 + 形参。源码中的实际调用在 Tree 与 Bytecode 共执行 126 次,并检查操作结果。17 项标准库工程测试通过;所有函数的叙述比例均超过 50%。
|
||||
|
||||
先前能力实现的验证记录如下;单文件结构与遮蔽调用修正后的全量复验记录在表后追加。
|
||||
|
||||
| 验证 | 真实结果 |
|
||||
|---|---|
|
||||
| `GOFLAGS=-buildvcs=false cargo test --offline --all-targets` | 首次全量 967 通过、0 失败、2 个原有忽略项,包含千文档编译测试 |
|
||||
| `GOFLAGS=-buildvcs=false cargo test --offline --all-targets -- --skip v3_corpus_1000_compile_smoke` | 结构修正前回归 968 通过、0 失败、2 个原有忽略项;跳过的千文档测试已在首次全量通过,合计覆盖 969 个不同通过项 |
|
||||
| `cargo check --offline --no-default-features --features wasm-core` | 通过;保留已有未使用代码告警 |
|
||||
| `cargo run --offline --quiet --example stdlib_catalog -- --check` | 0 条源码效应说明需要更新 |
|
||||
| `cargo check/build --offline -p marqdo-wasm --target wasm32-unknown-unknown` | 使用临时目录内版本匹配的官方工具链通过 |
|
||||
| `node tests/wasm/smoke.mjs <wasm产物>` | ABI 与桥接通过 |
|
||||
| `node tests/wasm/stdlib.mjs <wasm产物>` | 集合、字节、文档、TOML、IANA/DST 与 32 位边界通过 |
|
||||
| `git diff --check` | 通过 |
|
||||
|
||||
最终全量回归包含 17 项标准库工程测试。`GOFLAGS` 仅对本次命令关闭工作区所有权导致的 Go VCS 盖章失败,不修改全局 Git 配置。wasm 检查和运行使用同一构建产物,Node 验收不代表浏览器 DOM 布局验收。
|
||||
|
||||
单文件结构与遮蔽调用修正后的复验:
|
||||
|
||||
- `GOFLAGS=-buildvcs=false cargo test --offline --all-targets`:970 通过、0 失败、2 个原有忽略项,包含千文档编译、312 项金样例及 17 项标准库工程测试。
|
||||
- 61 份公开源码包含 63 条真实命令,Tree 与 Bytecode 共执行 126 次;操作返回 Result 时同时检查其 ok。
|
||||
- 648 个函数的名称、参数顺序与默认值 AST 逐项保持一致;每个函数叙述均超过 50%,标题下有完整契约,且不再保留旧形参。
|
||||
- 编译器效应检查:0 条源码效应说明需要更新;--json 直接输出 648 条真实接口记录。
|
||||
- 精简 wasm-core 构建通过;当前源码重新构建的 wasm32 产物通过 ABI、桥接和标准库 Node 运行验证。
|
||||
- `git diff --check` 通过。保留原有 reader 工作区修改。
|
||||
|
||||
删除旧形参后,沿用现有叙述形参推断;修复引号内星号、分号、空格被误作默认值边界的问题,并增加扫描回归测试。宿主调用的遮蔽标签不参与执行,诊断测试继续穿过标签定位真实指令和独立调用点。
|
||||
|
||||
[设计与能力边界](../design/stdlib-handbook.md)记录平台能力矩阵、兼容索引基数、资源上限、CoW 限制、目录复制范围、条件写入并发边界及线程取消语义。这些边界均为明确契约,不以占位实现宣称支持。保留工作区既有 reader 改动。
|
||||
@@ -79,7 +79,8 @@ Marqdo 用 `#` 标题定义**对象 / 类型**,用 `##` 定义其下的**方
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
import:
|
||||
json: lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
+16
-10
@@ -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
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`。
|
||||
|
||||
@@ -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
|
||||
|
||||
Loaded 100 of 1081 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user