Compare commits

...
22 Commits
Author SHA1 Message Date
cflmy aa0c4d0f55 release: v2.6.0 — executable library handbooks and readable actions 2026-11-08 23:30:17 +08:00
cflmy c50c515c4a Refactor executable library handbooks and improve document reading 2026-11-08 22:19:11 +08:00
cflmy 16c44588d5 Fix replay policy wire commands and register the agent smoke tool
Send complete op/steps/value records to the Lean decoder for every operation. Preserve companion exit status and a bounded stderr tail on transport failure. Register the smoke fixture read tool explicitly without weakening the allowlist or changing its output assertion.

Validation: 462 library tests and 312 gold tests passed. The repository regression run passed 946 tests with two existing ignored experiments; the previously passed 1000-document scale test was not repeated.
2026-11-08 21:50:01 +08:00
cflmy 5080136d65 Make Web an executable handbook with recursive Markdown layouts 2026-11-08 21:50:01 +08:00
cflmy cc5277d2b5 Make Quantum an executable handbook with verified experiments 2026-11-08 21:50:01 +08:00
cflmyandCursor bb06dad134 Start web skill=tools migration with in-package layout law.
Add root/index and layout skills that force file-partitioned pages and ban
HTML/CSS injection as the default path; wire ext add, docs, and call coverage.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-08 21:50:01 +08:00
cflmyandCursor 24dcb97354 Document the ext skill=tools development paradigm.
Capture the quantum pilot as a checklist-driven guide: layout, root skill
paths, call/session, narration, i18n, install hygiene, and rollout order.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-08 21:50:01 +08:00
cflmyandCursor 76aa02846a Clarify quantum agent paths for Bell preparation.
Root skills get a choose-a-path table; circuit modules spell the simulate
handoff; call_cli covers ZH bell and stepwise session probabilities.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-08 21:50:01 +08:00
cflmyandCursor 0e389f34ec Ship quantum skill=tools tree with call session and ZH package.
Split ext/quantum into index + modules, add marqdo call --effects/--session/--toget,
narrative-ratio checks, and a same-package 量子/ tree so agents can follow a
decision path for Bell demos without inventing a second API.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-08 21:50:01 +08:00
cflmy 492790e985 release: v2.5.1 — flowing source annotations and labeled toolbar 2026-11-07 13:08:09 +08:00
cflmy ca434a8bab docs: keep 2.5.0 reader version prose out of branch syntax 2026-11-07 10:11:36 +08:00
cflmy 6195ad1d5d release: v2.5.0 — document reader redesign 2026-11-07 10:06:58 +08:00
cflmyandCursor a87c2154ff release: v2.4.0 oracle journal language values
Expose foreign.oracle_journal/replay_check as values, bump CLI/ext/wasm to
2.4.0, and fix notebook OnceLock wait for MSRV 1.81 so EK can compile.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-06 15:09:34 +08:00
cflmyandCursor 8f1010f967 Ship oracle journal values, bytecode/frontend hardening, and replay-policy Lean.
Host exposes oracle journals as language values with refuse/copy gates; bytecode and foreign session paths get modularized; applications and verification replay-policy sources land with Lake builds ignored.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-06 15:04:27 +08:00
cflmyandCursor e3d9021bb6 docs: align foreign Strong correspondence with mechanized Thm. corr
Record corr_fresh_functional and host discharge (foreign gold + R1–R3)
for the closed/fresh/functional fragment instead of conformance-only wording.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-01 20:03:44 +08:00
cflmyandCursor 142ab523d6 release: v2.3.0 Foreign Strong session/handle/replay/arity
Opaque session handles, affine close, replay_check vs oracle journal,
table arity refuse, and Ω∈V_safe gate for the Strong foreign narrative.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-01 14:46:08 +08:00
cflmyandCursor 82c8d78fd3 release: v2.2.2 V_safe JSON integer refuse on foreign bridge
Align host json encode/decode with Lean ForeignJSON: refuse OOD integers
instead of silent Node distortion; keep decimal-string BigInt author path.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-01 09:43:51 +08:00
cflmyandCursor 58791fc7d9 release: v2.2.1 fix view outline rail under document
Occlusion left .doc-block open and mid-width CSS stacked the Functions/Variables rail below Structure; close the block and stack by panel container width instead.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-30 11:41:49 +08:00
cflmyandCursor 1730f26fc7 release: v2.2.0 call one function in any .mq.md
The same page is the document, the knowledge and the program. marqdo call runs that function with arguments, so reuse, tools and tests do not need a second skill system.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-30 09:07:23 +08:00
cflmyandCursor 4018e9928a fix(ai): stream usage events and accept free-form plan replies
Request stream_options.include_usage, emit usage SSE events for collect_usage,
propagate plan tokens through run, and treat unknown prose decisions as DONE.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-28 11:56:51 +08:00
cflmyandCursor 628e3b6e5d chore(ppa): bump 2.1.5 to 1ppa2 after Launchpad no-log failure
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 17:38:04 +08:00
cflmyandCursor 5c6c612edd fix(test): coerce MARQDO_SITE_PORT for MR-01 isolated execute
Env port strings must be json.parsed to int; pin main site to 18220 so
inherited MARQDO_SITE_PORT cannot steal the fixture bind.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 16:05:24 +08:00
448 changed files with 60302 additions and 9100 deletions

No files matched your search

+15 -7
View File
@@ -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 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
+49 -21
View File
@@ -7,7 +7,7 @@ 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
@@ -21,12 +21,12 @@ Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation a
These rules are the **current default**. Do **not** teach Classic `[key](map)` index or “bold is return of print”. Classic migration only: [migration-classic.md](migration-classic.md).
1. **File suffix** `.mq.md`. Print with `> print text=…` / `> 打印 内容=…` — never use `**…**` to print.
2. **`**…**` = code / return expression.** `*…*` = statement (bind / expr). Closing markers touch the last token (no trailing space).
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, `+` params, `1.`/`2.` branches, `-` loops, `N. *` else. No invented `if`/`for`/`def`/`return` keywords.
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.
@@ -34,8 +34,8 @@ These rules are the **current default**. Do **not** teach Classic `[key](map)` i
| Marker | Meaning (v2.1) |
|--------|----------------|
| `#` / `##`+ | Object/type · function/method |
| `*…*` | Statement |
| `**…**` | Return / code expression |
| `**…**` | Statement (assign / call / expression) |
| `*…*` | Return |
| `[描述](payload)` | Occlusion step (payload executes) |
| `access(c, k)` | Collection read |
| `> fn …` | Call |
@@ -48,7 +48,7 @@ Executable-knowledge gate: [`tests/executable_knowledge/`](../../tests/executabl
## Hard rules (do not violate)
1. Obey **CORE SYNTAX** above — Occlusion is default; do not emit Classic index links.
2. **Identifiers:** params `` + `name` ``; inside `*…*` / `**…**` bare ids are variables. Quote text literals. Standalone `>` calls: backticks where bare would be text.
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.
@@ -57,6 +57,24 @@ Executable-knowledge gate: [`tests/executable_knowledge/`](../../tests/executabl
8. Browser: Marqdo on WASM + `lib/browser` tables; do not hand-write business JS.
## Call one function
```markdown
# 计算器
## 加法
计算两个数字`a`和`b`的和。
*[计算结果](a + b)*
```
```
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
```markdown
@@ -96,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
@@ -118,7 +136,10 @@ Chinese builtins (same functions, no import):
## Frontmatter imports + stdlib
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:
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
---
@@ -130,9 +151,9 @@ import:
# 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).
@@ -168,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/).
@@ -177,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`.
@@ -191,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/).
@@ -223,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 文本) |
+65 -216
View File
@@ -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,27 +107,10 @@ 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
---
@@ -156,64 +129,13 @@ import:
**`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
@@ -225,43 +147,8 @@ import:
# 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
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
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)
@@ -270,7 +157,7 @@ import:
# 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:
@@ -289,13 +176,13 @@ import:
# 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
@@ -305,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:
@@ -323,9 +210,9 @@ 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)
@@ -340,9 +227,9 @@ import:
> 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`).
@@ -350,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)
@@ -374,58 +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
---
type: web
title: Hello
route: /
method: GET
---
# Hello
Executable document as a page.
```
`serve.mq.md`:
```markdown
---
title: hello-site
import:
web: ext/web/web.mq.md
db: db/index.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
quantum: ext/quantum/circuit/index.mq.md
---
# main
@@ -437,43 +314,15 @@ import:
| 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/`.
+28 -43
View File
@@ -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,16 +106,6 @@ 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
@@ -185,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 |
@@ -201,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 |
+8 -35
View File
@@ -126,41 +126,14 @@ jobs:
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **v2.1.5**:Agent 可靠工作台——ResourceView / ToolSpec / CheckpointV2 / EffectLedger · EKC ir.json 暖机 · Web 短读槽隔离
- **v2.1.5**: Agent reliability workbench — ResourceView / ToolSpec / CheckpointV2 / EffectLedger, EKC ir.json warm-load, web short/read lane isolation
- **v2.1.5 ext**:扩展包同步 2.1.5 / Ext pack 2.1.5
- **v2.1.4**:默认隔离 HTTP execute(ADR 0009)——worker 池 / `--call-lib-path` · `/_runtime/*` · MR-01 双流金样例 · `runtime.isolated_execution=1`
- **v2.1.4**: Default isolated HTTP execute (ADR 0009) — worker pool / `--call-lib-path`, `/_runtime/*`, MR-01 dual-stream gold, `runtime.isolated_execution=1`
- **v2.1.3**:知识工作台运行时——ModelSelection/RunContext/usage · view document 只读嵌入 · LLM selection/messages/cancel · agent selection e2e
- **v2.1.3**: Workbench runtime — ModelSelection/RunContext/usage, view document read-only embed, LLM selection/messages/cancel, agent selection e2e
- **v2.1.1**:可执行知识主链——BoundCall · NarrativeRef · 来源/适用期 · patch/extract · 整代 CURRENT + closure · 发票示例 113
- **v2.1.1**: Executable-knowledge spine — BoundCall, NarrativeRef, sources, patch/extract, generation CURRENT + closure, invoice example 113
- **v1.5.2**:外联 v3 P0/P1——raw stdin + 每 cell 输入 · plan API · snapshot · `view capture` · Persist
- **v1.5.2**: Foreign v3 P0/P1 — raw stdin + per-cell inputs, plan API, snapshot export/import/replay, `view capture`, Persist
- **v1.5.2 ext**:扩展包同步 1.5.2 / Ext pack 1.5.2
- **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
+5
View File
@@ -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/
+219
View File
@@ -8,6 +8,225 @@
### 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
Generated
+160 -3
View File
@@ -1,6 +1,6 @@
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 3
version = 4
[[package]]
name = "adler2"
@@ -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"
@@ -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"
@@ -572,11 +615,12 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "2.1.5"
version = "2.6.0"
dependencies = [
"anyhow",
"assert_cmd",
"chrono",
"chrono-tz",
"clap",
"futures-util",
"getrandom",
@@ -597,6 +641,7 @@ dependencies = [
"tiny_http",
"tokio",
"tokio-tungstenite",
"toml",
"ureq",
"zeroize",
"zip",
@@ -611,7 +656,7 @@ dependencies = [
[[package]]
name = "marqdo-wasm"
version = "2.1.5"
version = "2.6.0"
dependencies = [
"marqdo",
"serde_json",
@@ -727,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"
@@ -971,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"
@@ -1005,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"
@@ -1152,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"
@@ -1493,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"
+4 -2
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "2.1.5"
version = "2.6.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -30,7 +30,7 @@ chrono = { version = "0.4", default-features = false, features = ["clock", "std"
clap = { version = "=4.4.18", features = ["derive"], optional = true }
pulldown-cmark = "0.12"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
serde_json = { version = "1", features = ["float_roundtrip"] }
thiserror = "1"
tiny_http = { version = "0.12", optional = true }
sha2 = { version = "=0.10.9", default-features = false }
@@ -49,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).
+27 -5
View File
@@ -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/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,6 +35,7 @@ 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`。取元使用 `access(集合, "键")`,链接 `[描述](表达式)` 只承载叙述与执行体。这是 literate programming 的下一步。 |
@@ -281,8 +288,21 @@ marqdo catalog public -o .marqdo
---
## 现状(v2.1.5)
## 现状(v2.6.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)
@@ -325,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.1.5)
### 如何使用最新 Marqdo(v2.6.0)
**安装解释器(任选其一)**
@@ -340,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.1.5 # 或留在 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
@@ -379,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.1.5
# https://github.com/cflmy/marqdo/releases/tag/v2.6.0
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "2.1.5"
version = "2.6.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
+65
View File
@@ -1,3 +1,68 @@
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 /
+2
View File
@@ -27,6 +27,7 @@
| [跨库缺陷复核(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 默认链接/循环说明与构造守卫;不是全部实现状态清单 |
@@ -48,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/网络/数学/外联/插件** |
+2 -2
View File
@@ -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)
+91
View File
@@ -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) 作为开发范式长文 |
+71
View File
@@ -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 的具体物理工具或新的模板套到每个库。
+1 -1
View File
@@ -88,7 +88,7 @@
## 4. 作者面 API
### 4.1 英文(`ext/quantum/quantum.mq.md`)
### 4.1 英文(`ext/quantum/circuit/index.mq.md`)
在既有 `# circuit` / `# gate` 之外增加(或扩展方法):
+26 -11
View File
@@ -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
@@ -102,11 +117,11 @@ marqdo ext add quantum
```markdown
---
import:
quantum: ext/quantum/quantum.mq.md
quantum: ext/quantum/circuit/index.mq.md
---
```
或中文:`导入 量子:ext/quantum/量子.mq.md`。
或中文:`导入 量子:ext/quantum/量子/电路/索引.mq.md`(根 skill:`ext/quantum/量子/索引.mq.md`)。
---
@@ -152,7 +167,7 @@ $$
## 5. 作者面 API(锁定草图)
### 5.1 英文 `ext/quantum/quantum.mq.md`
### 5.1 英文 `ext/quantum/circuit/index.mq.md`
```markdown
# gate
@@ -199,7 +214,7 @@ $$
门方法返回**更新后的 circuit 句柄**(与 web `compose_*` 相同:`` `qc` = > `qc`.h qubit=0 *``)。
### 5.2 中文 `ext/quantum/量子.mq.md`
### 5.2 中文 `ext/quantum/量子/`(根 `索引.mq.md`)
| 英文 | 中文 |
|------|------|
@@ -343,7 +358,7 @@ Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-
---
title: Bell state
import:
quantum: ext/quantum/quantum.mq.md
quantum: ext/quantum/circuit/index.mq.md
---
# Bell |Φ+⟩
+227
View File
@@ -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 试点归纳的整包开发范式与验收清单 |
+10 -2
View File
@@ -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
@@ -77,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` |
@@ -93,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。
---
@@ -191,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` 仅逃逸舱) |
---
+71
View File
@@ -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 执行。
+65
View File
@@ -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)。
+9 -5
View File
@@ -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.
+37 -23
View File
@@ -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. 波次
+30
View File
@@ -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 待做** |
+131
View File
@@ -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.
+130
View File
@@ -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)。
+2
View File
@@ -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) |
+90
View File
@@ -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.
+9 -4
View File
@@ -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. 修订历史
| 日期 | 说明 |
+47
View File
@@ -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 盖章失败,不改全局配置。
+64
View File
@@ -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.
+256
View File
@@ -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。
失败记录只说明这次操作没有成功;它不会捕获任意语言错误,也不会替调用者授予权限。
+374
View File
@@ -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
View File
@@ -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 自己的设计哲学发挥作用,而不是不断增加外部框架来证明它的价值。
+66
View File
@@ -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的设计中包含有### 更深层的函数,这就是子工具了
+2
View File
@@ -1,5 +1,7 @@
# 调研:Mid M1–M6 之后标准库还缺什么
历史调研快照:以下缺口已由 Mid2 和后续标准库闭环分批解决,不能作为当前缺失清单。当前能力请从[标准库源码](../../lib/文件.mq.md)与[验收说明](../design/stdlib-handbook.md)核对。
| | |
|---|---|
| 状态 | **调研笔记 · 缺口盘点(M1–M6 闭环之后)** |
+4 -2
View File
@@ -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) |
---
+66
View File
@@ -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 句柄,不额外开始事务。双后端验证构造、提交、回滚与事务外读取。"
}
]
+60
View File
@@ -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 改动。
+17
View File
@@ -0,0 +1,17 @@
# 计算器
这是一个普通的 Marqdo 文档。
其中包含一些可以复用的数学计算知识。
## 加法
计算两个数字`a`和`b`的和。
*[计算结果](a + b)*
## 乘法
计算两个数字`a`和`b`的积。
*[计算结果](a * b)*
+803
View File
@@ -0,0 +1,803 @@
//! Audit library source with the real parser, and compare executable ASTs across prose refactors.
use anyhow::{Context, Result};
use marqdo::{ast::*, diagnostics::Span};
use serde_json::{json, Value};
use std::{
fs,
path::{Path, PathBuf},
};
fn files(dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
for entry in fs::read_dir(dir)? {
let p = entry?.path();
if p.is_dir() {
files(&p, out)?
} else if p.to_string_lossy().ends_with(".mq.md") {
out.push(p)
}
}
Ok(())
}
fn expr(e: Expr) -> Expr {
match e {
Expr::Occluded { payload, .. } => payload
.map(|p| expr(*p))
.unwrap_or(Expr::Literal(Literal::None)),
Expr::Unary { op, expr: e } => Expr::Unary {
op,
expr: Box::new(expr(*e)),
},
Expr::Binary { op, left, right } => Expr::Binary {
op,
left: Box::new(expr(*left)),
right: Box::new(expr(*right)),
},
Expr::Call(c) => {
let c = call(c);
pure_literal_call(&c).unwrap_or(Expr::Call(c))
}
Expr::List(xs) => Expr::List(xs.into_iter().map(expr).collect()),
Expr::Map(xs) => Expr::Map(xs.into_iter().map(|(k, v)| (k, expr(v))).collect()),
Expr::Index { base, label } => Expr::Index {
base: Box::new(expr(*base)),
label,
},
other => other,
}
}
fn call(mut c: CallExpr) -> CallExpr {
for a in &mut c.args {
match a {
Arg::Positional(e) | Arg::Named { value: e, .. } => *e = expr(e.clone()),
}
}
c
}
// Only the explicitly supported pure literal-building cases are folded. This is
// a refactor audit, not an evaluator: unknown calls and nonconstant data remain.
fn literal_json_value(v: serde_json::Value) -> Option<Expr> {
use serde_json::Value as J;
Some(Expr::Literal(match v {
J::Null => Literal::None,
J::Bool(b) => Literal::Bool(b),
J::String(s) => Literal::Text(s),
J::Number(n) => {
if let Some(i) = n.as_i64() {
if i.unsigned_abs() > 9_007_199_254_740_991 {
return None;
}
Literal::Int(i)
} else {
let n = n.as_f64()?;
if !n.is_finite() || (n.fract() == 0.0 && n.abs() > 9_007_199_254_740_991.0) {
return None;
}
Literal::Num(n)
}
}
_ => return None,
}))
}
// Read JSON literals without accepting duplicate keys or unsafe numeric coercions.
fn flat_json_record(text: &str) -> Option<Expr> {
struct Constant;
impl<'de> serde::Deserialize<'de> for ConstantExpr {
fn deserialize<D: serde::Deserializer<'de>>(de: D) -> Result<Self, D::Error> {
de.deserialize_any(Constant).map(ConstantExpr)
}
}
struct ConstantExpr(Expr);
impl<'de> serde::de::Visitor<'de> for Constant {
type Value = Expr;
fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
f.write_str("constant JSON in the exact audit numeric domain")
}
fn visit_unit<E: serde::de::Error>(self) -> Result<Expr, E> {
Ok(Expr::Literal(Literal::None))
}
fn visit_bool<E: serde::de::Error>(self, b: bool) -> Result<Expr, E> {
Ok(Expr::Literal(Literal::Bool(b)))
}
fn visit_str<E: serde::de::Error>(self, s: &str) -> Result<Expr, E> {
Ok(Expr::Literal(Literal::Text(s.into())))
}
fn visit_i64<E: serde::de::Error>(self, n: i64) -> Result<Expr, E> {
literal_json_value(n.into()).ok_or_else(|| E::custom("unsafe integer"))
}
fn visit_u64<E: serde::de::Error>(self, n: u64) -> Result<Expr, E> {
literal_json_value(n.into()).ok_or_else(|| E::custom("unsafe integer"))
}
fn visit_f64<E: serde::de::Error>(self, n: f64) -> Result<Expr, E> {
let n = serde_json::Number::from_f64(n).ok_or_else(|| E::custom("nonfinite number"))?;
literal_json_value(n.into()).ok_or_else(|| E::custom("unsafe number"))
}
fn visit_seq<A: serde::de::SeqAccess<'de>>(self, mut seq: A) -> Result<Expr, A::Error> {
let mut values = Vec::new();
while let Some(ConstantExpr(v)) = seq.next_element()? {
values.push(v);
}
Ok(Expr::List(values))
}
fn visit_map<A: serde::de::MapAccess<'de>>(self, mut map: A) -> Result<Expr, A::Error> {
use serde::de::Error;
let mut fields = std::collections::BTreeMap::new();
while let Some((key, ConstantExpr(value))) = map.next_entry::<String, ConstantExpr>()? {
if fields.insert(key, value).is_some() {
return Err(A::Error::custom("duplicate key"));
}
}
Ok(Expr::Map(fields.into_iter().collect()))
}
}
let ConstantExpr(value) = serde_json::from_str::<ConstantExpr>(text).ok()?;
Some(value)
}
fn pure_literal_call(c: &CallExpr) -> Option<Expr> {
let name = c
.path
.as_ref()
.map(|p| p.join("."))
.unwrap_or_else(|| c.callee.clone());
let get = |key: &str| {
c.args.iter().find_map(|a| match a {
Arg::Named { name, value } if name == key => Some(value),
_ => None,
})
};
match name.as_str() {
"json.parse" => {
if let Expr::Literal(Literal::Text(text)) = get("text")? {
flat_json_record(text)
} else {
None
}
}
"table.put" if matches!(get("in")?, Expr::Literal(Literal::None)) => {
if let Expr::Literal(Literal::Text(key)) = get("at")? {
let value = get("value")?;
if matches!(value, Expr::Literal(_)) {
Some(Expr::Map(vec![(key.clone(), value.clone())]))
} else {
None
}
} else {
None
}
}
"table.empty_list" => Some(Expr::List(Vec::new())),
"table.from_pairs" => {
let Expr::List(rows) = get("pairs")? else {
return None;
};
let mut fields = Vec::new();
let mut seen = std::collections::BTreeSet::new();
for row in rows {
let Expr::Map(pairs) = row else {
return None;
};
let Some((_, Expr::Literal(Literal::Text(key)))) =
pairs.iter().find(|(k, _)| k == "key")
else {
return None;
};
let Some((_, value)) = pairs.iter().find(|(k, _)| k == "value") else {
return None;
};
if !constant(value) || !seen.insert(key.clone()) {
return None;
}
fields.push((key.clone(), value.clone()));
}
Some(Expr::Map(fields))
}
"text.str_join" => {
let Expr::List(rows) = get("xs")? else {
return None;
};
let Expr::Literal(Literal::Text(separator)) = get("sep")? else {
return None;
};
let rows = rows
.iter()
.map(|e| {
if let Expr::Literal(Literal::Text(s)) = e {
Some(s.as_str())
} else {
None
}
})
.collect::<Option<Vec<_>>>()?;
Some(Expr::Literal(Literal::Text(rows.join(separator))))
}
_ => None,
}
}
fn constant(e: &Expr) -> bool {
match e {
Expr::Literal(_) => true,
Expr::List(xs) => xs.iter().all(constant),
Expr::Map(xs) => xs.iter().all(|(_, v)| constant(v)),
_ => false,
}
}
fn substitute(e: Expr, temps: &std::collections::BTreeMap<String, Expr>) -> Expr {
let e = match e {
Expr::Var(name) if temps.contains_key(&name) => temps[&name].clone(),
Expr::Call(mut c) => {
for a in &mut c.args {
match a {
Arg::Named { value, .. } | Arg::Positional(value) => {
*value = substitute(value.clone(), temps)
}
}
}
Expr::Call(c)
}
Expr::Map(xs) => Expr::Map(
xs.into_iter()
.map(|(k, v)| (k, substitute(v, temps)))
.collect(),
),
Expr::List(xs) => Expr::List(xs.into_iter().map(|v| substitute(v, temps)).collect()),
Expr::Occluded {
payload: Some(v), ..
} => substitute(*v, temps),
Expr::Unary { op, expr: v } => Expr::Unary {
op,
expr: Box::new(substitute(*v, temps)),
},
Expr::Binary { op, left, right } => Expr::Binary {
op,
left: Box::new(substitute(*left, temps)),
right: Box::new(substitute(*right, temps)),
},
other => other,
};
expr(e)
}
fn canonical_statements(statements: Vec<Stmt>) -> Vec<Stmt> {
fn block(
statements: Vec<Stmt>,
mut temps: std::collections::BTreeMap<String, Expr>,
) -> Vec<Stmt> {
let mut out = Vec::new();
for s in statements {
let s = statement(s);
let s = match s {
Stmt::Assign {
name,
value,
span,
end_line,
} => {
let value = substitute(value, &temps);
if name.starts_with("_literal_") && constant(&value) {
temps.insert(name, value);
continue;
}
Stmt::Assign {
name,
value,
span,
end_line,
}
}
Stmt::Return { value, span } => Stmt::Return {
value: substitute(value, &temps),
span,
},
Stmt::Expr { value, span } => Stmt::Expr {
value: substitute(value, &temps),
span,
},
Stmt::Branch { arms, span } => Stmt::Branch {
arms: arms
.into_iter()
.map(|a| BranchArm {
condition: a.condition.map(|e| substitute(e, &temps)),
body: block(a.body, temps.clone()),
})
.collect(),
span,
},
Stmt::ForEach {
item,
collection,
label,
body,
span,
} => Stmt::ForEach {
item,
collection,
label,
body: block(body, temps.clone()),
span,
},
Stmt::While {
condition,
body,
span,
} => Stmt::While {
condition: substitute(condition, &temps),
body: block(body, temps.clone()),
span,
},
other => other,
};
out.push(s);
}
out
}
block(statements, std::collections::BTreeMap::new())
}
fn statement(s: Stmt) -> Stmt {
let span = Span::new(0, 0);
match s {
Stmt::Assign { name, value, .. } => Stmt::Assign {
name,
value: expr(value),
span,
end_line: 0,
},
Stmt::Return { value, .. } => Stmt::Return {
value: expr(value),
span,
},
Stmt::Call { call: c, .. } => Stmt::Expr {
value: Expr::Call(call(c)),
span,
},
Stmt::Expr { value, .. } => Stmt::Expr {
value: expr(value),
span,
},
Stmt::Branch { arms, .. } => Stmt::Branch {
arms: arms
.into_iter()
.map(|a| BranchArm {
condition: a.condition.map(expr),
body: a.body.into_iter().map(statement).collect(),
})
.collect(),
span,
},
Stmt::While {
condition, body, ..
} => Stmt::While {
condition: expr(condition),
body: body.into_iter().map(statement).collect(),
span,
},
Stmt::ForEach {
item,
collection,
body,
..
} => Stmt::ForEach {
item,
collection,
body: body.into_iter().map(statement).collect(),
span,
label: None,
},
}
}
fn quote(s: &str) -> String {
serde_json::to_string(s).unwrap().replace('`', "\\`")
}
fn render(e: &Expr) -> Result<String> {
Ok(match e {
Expr::Literal(l) => match l {
Literal::None => "None".into(),
Literal::Bool(b) => if *b { "True" } else { "False" }.into(),
Literal::Int(n) => n.to_string(),
Literal::Num(n) => {
let text = n.to_string();
if text.contains('.') || text.contains(['e', 'E']) {
text
} else {
format!("{text}.0")
}
}
Literal::Text(s) => quote(s),
},
Expr::Var(n) => format!("`{n}`"),
Expr::Interp(parts) => {
let mut s = String::new();
for p in parts {
match p {
InterpPart::Lit(t) => s.push_str(&t.replace('`', "\\`")),
InterpPart::Var(v) => s.push_str(&format!("`{v}`")),
InterpPart::Index { .. } => {
anyhow::bail!("legacy interpolated index needs review")
}
}
}
serde_json::to_string(&s)?.replace("\\\\`", "\\`")
}
Expr::Call(c) => render_call(c)?,
Expr::Unary { op, expr: e } => format!(
"({}{})",
match op {
UnaryOp::Not => "not ",
UnaryOp::Neg => "-",
},
render(e)?
),
Expr::Binary { op, left, right } => format!(
"({} {} {})",
render(left)?,
match op {
BinaryOp::Add => "+",
BinaryOp::Sub => "-",
BinaryOp::Mul => "*",
BinaryOp::Div => "/",
BinaryOp::Eq => "==",
BinaryOp::Ne => "!=",
BinaryOp::Lt => "<",
BinaryOp::Le => "<=",
BinaryOp::Gt => ">",
BinaryOp::Ge => ">=",
BinaryOp::And => "and",
BinaryOp::Or => "or",
},
render(right)?
),
Expr::List(xs) => format!(
"[{}]",
xs.iter()
.map(render)
.collect::<Result<Vec<_>>>()?
.join(", ")
),
Expr::Map(xs) => format!(
"{{{}}}",
xs.iter()
.map(|(k, v)| Ok(format!("{}: {}", quote(k), render(v)?)))
.collect::<Result<Vec<_>>>()?
.join(", ")
),
Expr::Occluded {
label,
payload: Some(p),
} => format!("[{}]({})", label.replace(']', "\\]"), render(p)?),
Expr::Occluded { payload: None, .. } => "None".into(),
_ => anyhow::bail!("expression needs manual rendering: {e:?}"),
})
}
fn render_call(c: &CallExpr) -> Result<String> {
let target = if let Some(r) = &c.receiver {
format!("`{r}`.{}", c.callee)
} else if let Some(p) = &c.path {
p.join(".")
} else {
c.callee.clone()
};
let c = c.with_modifiers_expanded().map_err(anyhow::Error::msg)?;
let args = c
.args
.iter()
.map(|a| {
Ok(match a {
Arg::Positional(e) => render(e)?,
Arg::Named { name, value } => format!("{name}={}", render(value)?),
})
})
.collect::<Result<Vec<_>>>()?;
if c.receiver.is_some() {
Ok(format!("> {target} {} ", args.join(" ")))
} else {
Ok(format!("{target}({})", args.join(", ")))
}
}
fn receiver_call(c: &CallExpr, f: &Function, imports: &[String]) -> CallExpr {
let mut c = c.clone();
if let Some(path) = &c.path {
if path.len() == 2
&& f.params.iter().any(|p| p.name == path[0])
&& !imports.contains(&path[0])
{
c.receiver = Some(path[0].clone());
c.path = None;
}
}
c
}
fn render_value(v: &Expr, f: &Function, imports: &[String]) -> Result<String> {
match v {
Expr::Call(c) => render_call(&receiver_call(c, f, imports)),
Expr::Occluded {
label,
payload: Some(v),
} => Ok(format!(
"[{}]({})",
label.replace(']', "\\]"),
render_value(v, f, imports)?
)),
other => render(other),
}
}
// A qualified call through a parameter and its explicit receiver form resolve
// the same object when that name is not an imported module binding.
fn normalize_receiver_text(mut body: String, params: &Value, imports: &[String]) -> String {
for p in params.as_array().unwrap() {
let name = p["name"].as_str().unwrap();
if imports.iter().any(|i| i == name) {
continue;
}
let quoted = serde_json::to_string(name).unwrap();
let pattern = format!(
r#"path: Some\(\[{}, "[^"\n]+"\]\), receiver: None"#,
regex::escape(&quoted)
);
let re = regex::Regex::new(&pattern).unwrap();
body = re
.replace_all(&body, format!("path: None, receiver: Some({quoted})"))
.into_owned();
}
body
}
fn collect(fs: &[Function], prefix: &str, source: &str, imports: &[String], out: &mut Vec<Value>) {
for f in fs {
let name = if prefix.is_empty() {
f.name.clone()
} else {
format!("{prefix}.{}", f.name)
};
let mut calls = Vec::new();
marqdo::ast::walk_stmts(f, &mut |s| {
if let Stmt::Call { call, span } = s {
calls.push(json!({"line":span.line,"rendered":render_call(&receiver_call(call, f, imports)).ok(),"call":format!("{call:?}")}))
}
});
let mut statements = Vec::new();
marqdo::ast::walk_stmts(f, &mut |s| {
let (kind, name, value, line, end) = match s {
Stmt::Assign {
name,
value,
span,
end_line,
} => (
"assign",
Some(name.as_str()),
Some(value),
span.line,
*end_line,
),
Stmt::Return { value, span } => ("return", None, Some(value), span.line, span.line),
Stmt::Expr { value, span } => ("expr", None, Some(value), span.line, span.line),
Stmt::Call { call, span } => {
statements.push(json!({"kind":"call", "line":span.line, "rendered":render_call(&receiver_call(call, f, imports)).ok(), "callee":call.callee, "path":call.path, "receiver":call.receiver}));
return;
}
_ => return,
};
let mut inner = value;
while let Some(Expr::Occluded {
payload: Some(p), ..
}) = inner
{
inner = Some(p);
}
let target = match inner {
Some(Expr::Call(c)) => {
Some(json!({"callee":c.callee,"path":c.path,"receiver":c.receiver}))
}
_ => None,
};
statements.push(json!({"kind":kind,"name":name,"line":line,"end":end,"rendered":value.and_then(|v|render_value(v, f, imports).ok()),"target":target,"value":value.map(|v|format!("{v:?}"))}));
});
out.push(json!({"name":name,"short_name":f.name,"line":f.span.line,"level":f.level,"base":f.base,"receiver":function_uses_receiver(f),"params":f.params.iter().map(|p|json!({"name":p.name,"line":p.span.line,"default":p.default.as_ref().map(|e|format!("{:?}",expr(e.clone()))),"default_source":p.default.as_ref().and_then(|e|render(e).ok()),"type":f.contract.as_ref().and_then(|c|c.params.iter().find(|x|x.name==p.name)).map(|p|p.ty.name()).unwrap_or("any".into())})).collect::<Vec<_>>(),"returns":f.contract.as_ref().and_then(|c|c.returns.as_ref()).map(|r|r.ty.name()).unwrap_or("any".into()),"contract":f.contract.as_ref().map(|c|format!("{c:?}")),"body":format!("{:?}",canonical_statements(f.body.clone())),"calls":calls,"statements":statements,"narrative":marqdo::narrative_ratio::measure_source_units(source,std::slice::from_ref(f)).first().map(|r|r.ratio)}));
collect(&f.children, &name, source, imports, out);
}
}
fn difference(description: String, before: Value, after: Value) -> Value {
use sha2::Digest;
let digest = |value: Value| {
format!(
"{:x}",
sha2::Sha256::digest(serde_json::to_vec(&value).unwrap())
)
};
json!({"difference":description,"before":digest(before),"after":digest(after)})
}
fn main() -> Result<()> {
let args: Vec<_> = std::env::args().collect();
let baseline = args
.iter()
.position(|x| x == "--compare")
.map(|i| fs::read_to_string(&args[i + 1]))
.transpose()?
.map(|s| serde_json::from_str::<Value>(&s))
.transpose()?;
let original = args
.iter()
.position(|x| x == "--from")
.map(|i| fs::read_to_string(&args[i + 1]))
.transpose()?
.map(|s| serde_json::from_str::<Value>(&s))
.transpose()?;
let mut paths = Vec::new();
files(Path::new("lib"), &mut paths)?;
files(Path::new("ext"), &mut paths)?;
paths.sort();
if let Some(input) = &original {
paths.retain(|p| input.get(p.to_str().unwrap()).is_some());
}
let mut result = serde_json::Map::new();
let mut differences = Vec::new();
for path in paths {
let key = path.to_str().context("UTF-8 library path")?;
let source = if let Some(s) = original
.as_ref()
.and_then(|m| m.get(key))
.and_then(|m| m["source"].as_str())
{
s.to_owned()
} else {
fs::read_to_string(&path)?
};
let module = marqdo::parse::parse_source(&source).with_context(|| key.to_owned())?;
let mut functions = Vec::new();
let imports: Vec<_> = module
.imports
.iter()
.map(|i| i.bind.clone())
.chain(module.uses.iter().map(|i| i.bind.clone()))
.collect();
collect(&module.functions, "", &source, &imports, &mut functions);
let reports = marqdo::narrative_ratio::measure_source_units(&source, &module.functions);
for f in &mut functions {
let report = reports.iter().find(|r| json!(r.line) == f["line"]).unwrap();
f["narrative_chars"] = json!(report.narrative);
f["code_chars"] = json!(report.total - report.narrative);
f["narrative"] = json!(
reports
.iter()
.find(|r| json!(r.line) == f["line"])
.unwrap()
.ratio
);
}
if let Some(old) = baseline.as_ref().and_then(|b| b.get(key)) {
for o in old["functions"].as_array().unwrap() {
match functions.iter().find(|f| f["name"] == o["name"]) {
None => differences.push(difference(
format!("removed {key} {}", o["name"]),
json!({"level":o["level"],"base":o["base"],"receiver":o["receiver"],"params":o["params"].as_array().unwrap().iter().map(|p|json!([p["name"],p["default"]])).collect::<Vec<_>>(),"body":o["body"]}),
Value::Null,
)),
Some(n) => {
for field in ["level", "base", "receiver", "body"] {
let same = if field == "body" {
normalize_receiver_text(
n[field].as_str().unwrap().to_owned(),
&o["params"],
&imports,
) == normalize_receiver_text(
o[field].as_str().unwrap().to_owned(),
&o["params"],
&imports,
)
} else {
n[field] == o[field]
};
if !same {
differences.push(difference(format!("{key} {} changed {field}", o["name"]), o[field].clone(), n[field].clone()));
}
}
let sig = |f: &Value| {
f["params"]
.as_array()
.unwrap()
.iter()
.map(|p| json!([p["name"], p["default"]]))
.collect::<Vec<_>>()
};
if sig(n) != sig(o) {
differences.push(difference(format!("{key} {} changed parameters", o["name"]),json!(sig(o)),json!(sig(n))));
}
}
}
}
}
result.insert(
key.to_owned(),
json!({"source": source, "functions": functions}),
);
}
if let Some(i) = args.iter().position(|x| x == "--snapshot") {
fs::write(&args[i + 1], serde_json::to_vec_pretty(&result)?)?;
}
println!(
"{} library files, {} functions",
result.len(),
result
.values()
.map(|f| f["functions"].as_array().unwrap().len())
.sum::<usize>()
);
if let Some(i) = args.iter().position(|x| x == "--differences") {
fs::write(&args[i + 1], serde_json::to_vec_pretty(&differences)?)?;
}
if baseline.is_some() {
let reviewed = args
.iter()
.position(|x| x == "--reviewed-fixes")
.map(|i| fs::read_to_string(&args[i + 1]))
.transpose()?
.map(|text| serde_json::from_str::<Vec<Value>>(&text))
.transpose()?
.unwrap_or_default();
let matches = |d: &Value, r: &Value| {
["difference", "before", "after"]
.iter()
.all(|k| d[*k] == r[*k])
&& r["reason"].as_str().is_some_and(|s| !s.trim().is_empty())
};
let unreviewed: Vec<_> = differences
.iter()
.filter(|d| !reviewed.iter().any(|r| matches(d, r)))
.collect();
let stale: Vec<_> = reviewed
.iter()
.filter(|r| !differences.iter().any(|d| matches(d, r)))
.collect();
println!("{} executable differences, {} exact reviewed fixes, {} unreviewed, {} stale review records",
differences.len(),differences.len()-unreviewed.len(),unreviewed.len(),stale.len());
for d in &unreviewed {
println!("{}", d["difference"]);
}
if !unreviewed.is_empty() || !stale.is_empty() {
anyhow::bail!(
"review executable differences; only exact before/after digests are accepted"
);
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn json_literal_audit_rejects_duplicates_unsafe_numbers_and_trailing_data() {
for text in [
r#"{"x":1,"x":2}"#,
r#"{"nested":{"x":1,"x":2}}"#,
r#"{"x":9007199254740992}"#,
r#"{} false"#,
r#"{"x":NaN}"#,
] {
assert!(flat_json_record(text).is_none(), "{text}");
}
let value = flat_json_record(r#"{"z":[null,true,"a\nb"],"a":1}"#).unwrap();
assert!(constant(&value));
let Expr::Map(fields) = value else {
panic!("map expected");
};
assert_eq!(fields[0].0, "a");
assert_eq!(fields[1].0, "z");
}
#[test]
fn only_supported_constant_builders_are_folded() {
for code in [
"unknown(text=\"{}\")",
"json.parse(text=`input`)",
"table.put(in=`input`, at=\"key\", value=1)",
"text.str_join(xs=`rows`, sep=\"\\n\")",
] {
let Expr::Call(call) = marqdo::parse::expr::parse_expr(code).unwrap() else {
panic!("call expected");
};
assert!(pure_literal_call(&call).is_none(), "{code}");
}
let Expr::Call(call) =
marqdo::parse::expr::parse_expr("json.parse(text=\"{\\\"key\\\":null}\")").unwrap()
else {
panic!("call expected");
};
assert!(pure_literal_call(&call).is_some());
}
}
+1 -1
View File
@@ -3,7 +3,7 @@ markup: occlusion
title: 贝尔态:两个量子比特如何一起回答
description: 从一条假设开始,搭电路、看概率、画图,并用断言验收。
import:
quantum: ext/quantum/quantum.mq.md
quantum: ext/quantum/circuit/index.mq.md
---
# main
+1 -1
View File
@@ -3,7 +3,7 @@ markup: occlusion
title: Bell state
description: H then CX; probabilities ≈ 1/2; circuit SVG.
import:
quantum: ext/quantum/quantum.mq.md
quantum: ext/quantum/circuit/index.mq.md
math: lib/math.mq.md
json: lib/json.mq.md
---
+1 -1
View File
@@ -3,7 +3,7 @@ markup: occlusion
title: Entanglement lab
description: Bell state — density, partial trace, Schmidt, themed SVG (Q7/Q8).
import:
quantum: ext/quantum/quantum.mq.md
quantum: ext/quantum/circuit/index.mq.md
math: lib/math.mq.md
---
+3 -2
View File
@@ -3,7 +3,8 @@ markup: occlusion
title: GHZ state
description: 3-qubit GHZ; |000⟩/|111⟩ ≈ 1/2; probs + H matrix heatmap.
import:
quantum: ext/quantum/quantum.mq.md
quantum: ext/quantum/circuit/index.mq.md
gate: ext/quantum/gate/index.mq.md
---
# GHZ
@@ -24,7 +25,7 @@ H on qubit 0, CX(0→1), CX(0→2). Ideal: |000⟩ and |111⟩ each with probabi
**p = > qc.probabilities**
**_ = > qc.draw path="ghz.svg"**
**_ = > qc.draw kind="probs" path="ghz-probs.svg"**
**H = > quantum.gate name="H"**
**H = > gate.gate name="H"**
**_ = > H.draw kind="matrix" path="ghz-h-matrix.svg"**
> print text=`p`
+21
View File
@@ -0,0 +1,21 @@
---
markup: occlusion
title: Quantum skill call demo
description: >-
Agent-style flow via ext/quantum index and domain modules (Bell probabilities).
import:
circuit: ext/quantum/circuit/index.mq.md
simulate: ext/quantum/simulate/index.mq.md
---
# main
Build Phi-plus with domain skills, then print ideal probabilities. Prefer the
same steps via marqdo call with --effects plugin and toget when an agent drives
the session.
**qc = > circuit.new qubits=2 steps=None**
**qc = > circuit.hadamard circuit=`qc` qubit=0**
**qc = > circuit.cnot circuit=`qc` control=0 target=1**
**p = > simulate.probabilities circuit=`qc`**
> print text=`p`
+169
View File
@@ -0,0 +1,169 @@
---
markup: occlusion
title: Standard library engineering practice
import:
fs: lib/fs.mq.md
path: lib/path.mq.md
table: lib/table.mq.md
csv: lib/csv.mq.md
document: lib/document.mq.md
hash: lib/hash.mq.md
bytes: lib/bytes.mq.md
---
This project demonstrates file inventory, typed CSV aggregation and controlled
Markdown maintenance using the public standard library. No foreign program,
plugin or alternate data syntax is involved. Each operation below is callable.
The demo creates its own directory under the filesystem root and removes it
when successful; it returns the real inventory, report and update outcome.
Create a disposable directory and set MQ_WORK to its absolute path before the
following command. All relative IO is confined to that directory. The Rust
acceptance test prepares this directory and runs the same source on both runtimes.
```sh
marqdo call examples/stdlib-handbook/index.mq.md demo --fs-root "$MQ_WORK" --effects fs.write --json
```
For production, call inventory on your source directory, summarize_csv on text
from fs.read_text, or update_section with an explicit title and replacement body.
Inspect each operation Result before using its value. File inventory keeps one
unreadable file from aborting other records. Directory cleanup and the update are
separate operations, not a transaction. For high-volume inputs use the batched
collection transforms; this report uses batch transforms, including grouping and aggregation.
## inventory
+ `root`
| 参数 | 类型 | 说明 |
|---|---|---|
| root | text | Directory relative to the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | One path/ok/characters/error record per Markdown file |
Discover Markdown files, then retain each read outcome. A bad UTF-8 document
is represented as an error record; valid documents still contribute counts.
**names = fs.find path=`root` pattern="**/*.md"**
**out = table.empty_list**
- [inspect each discovered file](遍历 names 为 name)
**file = path.join a=`root` b=`name`**
**read = fs.try_read_text path=`file`**
**characters = None**
1. [read succeeded](access(`read`, "ok"))
**body = access(read, "value")**
**characters = len `body`**
2. *
**characters = None**
**success = access(read, "ok")**
**error = access(read, "error")**
`record` =
| path | ok | characters | error |
|---|---|---|---|
| `name` | `success` | `characters` | `error` |
**out = table.append list=`out` item=`record`**
*out*
## summarize_csv
+ `text`
| 参数 | 类型 | 说明 |
|---|---|---|
| text | text | Header-based CSV: team, amount and active fields |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | CSV with team/total/count for active rows |
CSV cells start as text. Convert them deliberately, select active rows, group
by team, and sum integer amounts with overflow checks. Nothing passes through SQL.
**rows = csv.parse text=`text`**
`schema` =
| amount | active |
|---|---|
| int | bool |
**typed = table.cast rows=`rows` schema=`schema`**
**selected = table.where list=`typed` key="active" value=True**
**summary = table.summarize list=`selected` key="team" field="amount"**
`names` =
| key | value |
|---|---|
| team | total |
**renamed = table.rename list=`summary` fields=`names`**
`fields` =
| field |
|---|
| team |
| total |
| count |
**report = table.project list=`renamed` keys=`fields`**
*> csv.stringify rows=`report`*
## update_section
+ `path`
+ `title`
+ `body`
| 参数 | 类型 | 说明 |
|---|---|---|
| path | text | Existing Markdown file under the granted root |
| title | text | Exact, unique heading title |
| body | text | Replacement section body, without its heading |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Recoverable replacement/write outcome |
Compute the expected digest from the exact source that was read. Transform
only the selected body; fs.write_checked detects stale content before replacing.
Concurrent writers still need coordination: this is not a kernel CAS primitive.
**source = fs.read_text path=`path`**
**expected = hash.sha256 text=`source`**
**changed = document.replace_section text=`source` title=`title` body=`body`**
1. [section replacement succeeded](access(`changed`, "ok"))
**next = access(changed, "value")**
*> fs.write_checked path=`path` text=`next` expected_sha256=`expected`*
2. *
*changed*
## demo
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Actual file inventory, CSV report and document update |
Prepare a small valid corpus and an invalid UTF-8 file, then run all three
operations. Validate the returned data; this function never fabricates a pass flag.
**work = fs.temp_dir prefix="stdlib-demo"**
**note = path.join a=`work` b="notes.md"**
**bad = path.join a=`work` b="invalid.md"**
**corpus = "# Notes\n\n## Status\n\nOld status.\n\n# Appendix\n\nKeep this paragraph.\n"**
> fs.atomic_write path=`note` text=`corpus`
**binary = bytes.from_base64 text="/w=="**
> fs.write_bytes path=`bad` data=`binary`
**files = inventory root=`work`**
**data = "team,amount,active\na,10,true\nb,4,false\na,20,true\n"**
**report = summarize_csv text=`data`**
**update = update_section path=`note` title="Status" body="Updated through public standard libraries."**
**after = fs.read_text path=`note`**
> fs.remove_tree path=`work`
`out` =
| inventory | csv | update | document |
|---|---|---|---|
| `files` | `report` | `update` | `after` |
*out*
+9
View File
@@ -0,0 +1,9 @@
---
markup: occlusion
---
# main
A file task returns its answer; stdout is not the answer channel.
*17*
+29
View File
@@ -0,0 +1,29 @@
---
markup: occlusion
title: 标准库工程实践
import:
practice: index.mq.md
---
本工程把文件整理、CSV 数据处理和文档维护连为真实工作流。
中文入口复用同一份实现,避免双语版本逐渐分叉。准备一个可丢弃目录,
把其绝对路径设为 MQ_WORK,再执行下面的工具;成功后会清理自己的临时子目录。
返回值包含真实的文件结果、CSV 报表及修改后文档,不以一个通过标志代替验收。
```sh
marqdo call examples/stdlib-handbook/索引.mq.md 演示 --fs-root "$MQ_WORK" --effects fs.write --json
```
生产使用时先阅读[同源实现](index.mq.md),选择文件清单、汇总报表或更新章节。
读取失败以每文件错误记录保留;CSV 字段先显式转换类型;章节替换保留周围叙述,
写入前检查来源摘要。根目录、失败结果和并发写入限制都在真实函数旁说明。
## 演示
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 三项真实工作流的结果 |
执行同源工程,保留所有实际返回数据和失败行为。
*> practice.demo*
+123
View File
@@ -0,0 +1,123 @@
//! Inspect real single-file standard library signatures; no index module is required.
//! --json emits compiler metadata; --check validates source effect notes;
//! --write refreshes only effect notes, preserving authored prose and examples.
use anyhow::{bail, Context, Result};
use std::{
fs,
path::{Path, PathBuf},
};
fn main() -> Result<()> {
let args: Vec<_> = std::env::args().collect();
let write = args.iter().any(|arg| arg == "--write");
let json = args.iter().any(|arg| arg == "--json");
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let mut sources: Vec<_> = fs::read_dir(root.join("lib"))?
.map(|entry| entry.map(|e| e.path()))
.collect::<std::io::Result<_>>()?;
sources.retain(|p| p.is_file() && p.to_string_lossy().ends_with(".mq.md"));
sources.sort();
let mut changed = 0;
let mut tools = Vec::new();
for source in sources {
let module = marqdo::load::load_module(&source)?;
let compilation = marqdo::sema::compile_file_closure(&source)?;
let content = fs::read_to_string(&source)?;
let mut lines: Vec<_> = content.lines().map(str::to_owned).collect();
let mut edits = Vec::new();
let zh = source
.file_name()
.unwrap()
.to_string_lossy()
.chars()
.any(|c| !c.is_ascii());
for (index, function) in module.functions.iter().enumerate() {
let artifact = compilation
.semantics
.artifacts
.iter()
.find(|a| {
a.kind == "function"
&& a.source.line == function.span.line
&& same_source(&compilation.semantics.root, &a.source.file, &source)
})
.context("missing compiler function artifact")?;
let signature = artifact
.signature
.as_ref()
.context("missing compiler signature")?;
let effects: Vec<_> = artifact
.effects
.values()
.into_iter()
.filter(|e| *e != "pure")
.collect();
let effects = if effects.is_empty() {
"pure".to_owned()
} else {
effects.join(",")
};
let expected = if zh {
format!("调用效应:{effects}。")
} else {
format!("Effects: {effects}.")
};
let start = function.span.line as usize;
let end = module
.functions
.get(index + 1)
.map(|f| (f.span.line as usize).saturating_sub(1))
.unwrap_or(lines.len());
let notes: Vec<_> = (start..end)
.filter(|i| {
lines[*i].starts_with("Effects: ") || lines[*i].starts_with("调用效应:")
})
.collect();
if notes.len() != 1 {
bail!(
"{} {} needs one effect note in its source",
source.display(),
function.name
);
}
if lines[notes[0]] != expected {
changed += 1;
if write {
edits.push((notes[0], expected));
} else if !json {
eprintln!("stale effect note: {} {}", source.display(), function.name);
}
}
tools.push(serde_json::json!({
"name": function.name,
"parameters": signature.params.iter().map(|p| serde_json::json!({"name":p.name,"type":p.ty,"required":p.required,"default_digest":p.default_digest.as_ref().map(|d| &d.0),"unit":p.unit})).collect::<Vec<_>>(),
"returns": signature.returns,
"effects": artifact.effects.values(),
"source": source.strip_prefix(&root)?,
"line": function.span.line
}));
}
if !edits.is_empty() {
for (line, text) in edits {
lines[line] = text;
}
fs::write(&source, lines.join("\n") + "\n")?;
}
}
if json {
println!("{}", serde_json::to_string_pretty(&tools)?);
} else if changed > 0 && !write {
bail!("{changed} effect notes differ from compiler metadata; run with --write");
} else {
println!(
"{} source effect notes {}; {} public functions",
changed,
if write { "updated" } else { "need updating" },
tools.len()
);
}
Ok(())
}
fn same_source(root: &Path, relative: &str, source: &Path) -> bool {
root.join(relative).canonicalize().ok() == source.canonicalize().ok()
}
+80
View File
@@ -0,0 +1,80 @@
---
markup: occlusion
title: 在正文里读懂一段程序
description: 用同一份源码演示动作遮蔽、输入输出、数据表、条件、循环和待补逻辑。
---
这份示例把计算留在文章里。动作说明可以直接阅读,展开侧注才看到实际表达式。
侧注说明“准备怎样计算”,运行标注说明“这一次得到什么”;两种信息有不同的来源。
用 marqdo view examples/view-reading.mq.md 打开实时阅读,或执行下面的离线导出命令。
导出时的 --no-exec 只分析和排版,不运行示例,也不触发任何动作。
```sh
marqdo view output examples/view-reading.mq.md --no-exec --out /tmp/marqdo-reading
```
## 计算小计
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 单价 | number | 必填 | 每件商品的价格,使用调用方选定的同一种货币单位 |
| 数量 | number | 1 | 购买的件数;本例由调用方保证非负 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 小计 | number | 单价乘以数量得到的金额,不包含额外税费或优惠 |
已知商品的`单价`,未指定时购买`数量`=1。这里没有网络请求或文件写入;
价格与数量由调用者提供,不会从屏幕上的说明自动推测。
完成乘法后,我们返回*[按件数计算金额](单价 * 数量)*,让后面的步骤继续使用。
## 预留逻辑
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 当前返回 None;尚未接入实际业务实现 |
此函数演示空遮蔽的显示。它没有实现业务行为,不能作为“功能已完成”的证据。
目前返回*[由作者补充具体业务]()*;阅读器会明确标出待补逻辑,而不会假装已有结果。
# main
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | map | 两笔金额与遍历计算的总数,均来自这一次实际执行 |
先**第一笔 = [购买两件商品](计算小计(单价=12, 数量=2))**,再**第二笔 = [使用默认件数](计算小计(单价=8))**。
两个动作可以在同一句话里出现,各自关联自己的逻辑侧注。金额的实际数值只在运行后产生。
下面的单列表是三个数量组成的列表;绑定名让它成为数据,和上面的参数契约表不同。
`数量列表` =
| 数量 |
|---|
| 1 |
| 2 |
| 3 |
从**总数 = 0**开始累计,每次迭代读取一个值。切换迭代记录只是在查看既有结果,不会重跑循环。
- [依次累计数量](遍历 数量列表 为 项)
把当前项加入已有累计,得到**总数 = 总数 + 项**。
下面按计算结果选择分支;未进入的分支仍然属于源码,不会因为查看运行记录而消失。
1. `总数` > 0
确认这次遍历已有数据后,执行**[输出累计值](print(text=`总数`))**。
2. *
没有数量时,执行**[说明输入为空](print(text="没有数量"))**。
把已经计算的值整理成一行记录,字段名称说明每一项的来源。
`摘要` =
| 第一笔 | 第二笔 | 总数 |
|---|---|---|
| `第一笔` | `第二笔` | `总数` |
最后返回*摘要*,调用者得到的是结构化记录;上面的预留函数并未在本流程中调用。
+22
View File
@@ -0,0 +1,22 @@
# Layout decomposition reference
Read [the page](index.mq.md), then follow [components](components/index.mq.md) to
navigation, main and footer. Footer splits into brand and links; links splits
again into docs and community. Every terminal content.md is plain Markdown.
Parent .mq.md files only load/compose child rows and choose one relationship.
From the repository root, preview with:
```bash
marqdo run examples/web-layout-handbook-zh/preview.mq.md
```
To serve, change into this directory, then run:
```bash
marqdo run serve.mq.md
```
Check /, /about and /api/ping. Geometry comes from the runtime's row/column
containers. No authored HTML or CSS is needed. view: main is evaluated once at
startup; restart after edits. Request-time interaction belongs in Endpoints.
@@ -0,0 +1,18 @@
---
markup: occlusion
类型: 端点
路径: /api/ping
方法: GET
请求: none
响应: json
---
# main
`result` =
| ok | ping |
|----|------|
| True | pong |
*result*
@@ -0,0 +1,3 @@
### Marqdo
代码即文档,文档即可执行。
@@ -0,0 +1,18 @@
---
markup: occlusion
import:
文件: lib/文件.mq.md
组件: ext/web/网页/组件/索引.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
此叶子只负责footer/brand 的 Markdown 内容,父组件决定排列。修改文字只改相邻 content.md,
不添加 HTML 标签或内部分栏;出现第二种布局职责时再开子目录。
**body = 文件.读文本 路径="components/footer/brand/content.md"**
*> 组件.正文 文本=`body` 槽="footer-brand"*
@@ -0,0 +1,24 @@
---
markup: occlusion
import:
组件: ext/web/网页/组件/索引.mq.md
布局: ext/web/布局/索引.mq.md
brand: ./brand/index.mq.md
links: ./links/index.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
本层只安排品牌内容与链接子树之间的关系,正文仍留在对应 Markdown 叶子中。
若子块仍含独立分栏,就继续沿对应目录的 index.mq.md 分解。
不要把渲染后的字符串放回值列,子节点在整个装配过程中保持结构。
**brand_nodes = > brand.节点**
**links_nodes = > links.节点**
**siblings = 组件.合并 甲=`brand_nodes` 乙=`links_nodes`**
**footer_columns = 布局.分栏 子节点=`siblings` 槽="footer"**
*> 组件.包裹 子节点=`footer_columns` 种类="footer" 槽="footer"*
@@ -0,0 +1,5 @@
### 社区
[关于项目](/about)
[返回首页](/)
@@ -0,0 +1,18 @@
---
markup: occlusion
import:
文件: lib/文件.mq.md
组件: ext/web/网页/组件/索引.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
此叶子只负责footer/links/community 的 Markdown 内容,父组件决定排列。修改文字只改相邻 content.md,
不添加 HTML 标签或内部分栏;出现第二种布局职责时再开子目录。
**body = 文件.读文本 路径="components/footer/links/community/content.md"**
*> 组件.正文 文本=`body` 槽="footer-links-community"*
@@ -0,0 +1,5 @@
### 文档
[开发手册](/about)
[服务状态](/api/ping)
@@ -0,0 +1,18 @@
---
markup: occlusion
import:
文件: lib/文件.mq.md
组件: ext/web/网页/组件/索引.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
此叶子只负责footer/links/docs 的 Markdown 内容,父组件决定排列。修改文字只改相邻 content.md,
不添加 HTML 标签或内部分栏;出现第二种布局职责时再开子目录。
**body = 文件.读文本 路径="components/footer/links/docs/content.md"**
*> 组件.正文 文本=`body` 槽="footer-links-docs"*
@@ -0,0 +1,23 @@
---
markup: occlusion
import:
组件: ext/web/网页/组件/索引.mq.md
布局: ext/web/布局/索引.mq.md
docs: ./docs/index.mq.md
community: ./community/index.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
本层只安排文档链接与社区链接之间的关系,正文仍留在对应 Markdown 叶子中。
若子块仍含独立分栏,就继续沿对应目录的 index.mq.md 分解。
不要把渲染后的字符串放回值列,子节点在整个装配过程中保持结构。
**docs_nodes = > docs.节点**
**community_nodes = > community.节点**
**siblings = 组件.合并 甲=`docs_nodes` 乙=`community_nodes`**
*> 布局.分栏 子节点=`siblings` 槽="footer-links"*
@@ -0,0 +1,26 @@
---
markup: occlusion
import:
组件: ext/web/网页/组件/索引.mq.md
布局: ext/web/布局/索引.mq.md
nav: ./nav/index.mq.md
content: ./main/index.mq.md
footer: ./footer/index.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
本层只安排导航、主体、页脚之间的关系,正文仍留在对应 Markdown 叶子中。
若子块仍含独立分栏,就继续沿对应目录的 index.mq.md 分解。
不要把渲染后的字符串放回值列,子节点在整个装配过程中保持结构。
**nav_nodes = > nav.节点**
**content_nodes = > content.节点**
**footer_nodes = > footer.节点**
**upper_regions = 组件.合并 甲=`nav_nodes` 乙=`content_nodes`**
**home_regions = 组件.合并 甲=`upper_regions` 乙=`footer_nodes`**
*> 布局.纵排 子节点=`home_regions` 槽="home"*
@@ -0,0 +1,3 @@
# 可执行文档站点
先拆布局,再写内容。**叶子只负责 Markdown。**
@@ -0,0 +1,18 @@
---
markup: occlusion
import:
文件: lib/文件.mq.md
组件: ext/web/网页/组件/索引.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
此叶子只负责main 的 Markdown 内容,父组件决定排列。修改文字只改相邻 content.md,
不添加 HTML 标签或内部分栏;出现第二种布局职责时再开子目录。
**body = 文件.读文本 路径="components/main/content.md"**
*> 组件.正文 文本=`body` 槽="main"*
@@ -0,0 +1 @@
[首页](/) · [关于](/about) · [状态](/api/ping)
@@ -0,0 +1,18 @@
---
markup: occlusion
import:
文件: lib/文件.mq.md
组件: ext/web/网页/组件/索引.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
此叶子只负责nav 的 Markdown 内容,父组件决定排列。修改文字只改相邻 content.md,
不添加 HTML 标签或内部分栏;出现第二种布局职责时再开子目录。
**body = 文件.读文本 路径="components/nav/content.md"**
*> 组件.正文 文本=`body` 槽="nav"*
@@ -0,0 +1,16 @@
---
markup: occlusion
类型: 网页
视图: main
标题: Marqdo 布局实践
路由: /
import:
home: ./components/index.mq.md
---
# main
页面只选择布局根,具体拆分沿 components/index.mq.md 继续。
此主程序返回结构而不是 HTML;view 元数据让服务在启动时执行它。
*> home.节点*
@@ -0,0 +1,10 @@
---
markup: occlusion
类型: 网页
标题: 关于
路由: /about
---
# 关于
这是普通 Markdown Document,不执行布局函数。
@@ -0,0 +1,12 @@
---
markup: occlusion
import:
home: ./components/index.mq.md
网页: ext/web/网页.mq.md
---
# main
**nodes = > home.节点**
**html = 网页.渲染 节点=`nodes` 标题="Marqdo 布局实践"**
> 打印 内容=`html`
@@ -0,0 +1,12 @@
---
markup: occlusion
import:
网页: ext/web/网页.mq.md
---
# main
端口 `端口`=18081 可通过 --bind 覆盖。启动器不包含页面布局。
**监听端口 = 整数 值=`端口`**
> 网页.服务 根="." 主机="127.0.0.1" 端口=`监听端口`
+22
View File
@@ -0,0 +1,22 @@
# Layout decomposition reference
Read [the page](index.mq.md), then follow [components](components/index.mq.md) to
navigation, main and footer. Footer splits into brand and links; links splits
again into docs and community. Every terminal content.md is plain Markdown.
Parent .mq.md files only load/compose child rows and choose one relationship.
From the repository root, preview with:
```bash
marqdo run examples/web-layout-handbook/preview.mq.md
```
To serve, change into this directory, then run:
```bash
marqdo run serve.mq.md
```
Check /, /about and /api/ping. Geometry comes from the runtime's row/column
containers. No authored HTML or CSS is needed. view: main is evaluated once at
startup; restart after edits. Request-time interaction belongs in Endpoints.
@@ -0,0 +1,18 @@
---
markup: occlusion
type: endpoint
path: /api/ping
method: GET
request: none
response: json
---
# main
`result` =
| ok | ping |
|----|------|
| True | pong |
*result*
@@ -0,0 +1,3 @@
### Marqdo
Code is documentation. Documents are executable.
@@ -0,0 +1,19 @@
---
markup: occlusion
import:
fs: lib/fs.mq.md
component: ext/web/component/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
This leaf owns only the footer/brand Markdown content; its parent owns placement.
Edit adjacent content.md to change prose. Add a child directory when a second
layout responsibility appears instead of introducing HTML into the content.
**body = fs.read_text path="components/footer/brand/content.md"**
*> component.markdown text=`body` slot="footer-brand"*
@@ -0,0 +1,24 @@
---
markup: occlusion
import:
component: ext/web/component/index.mq.md
layout: ext/web/layout/index.mq.md
brand: ./brand/index.mq.md
links: ./links/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
This parent arranges brand content and the link-region subtree. Content stays
in their Markdown leaves; this file owns their one placement relationship. Continue into each child index when another independent layout
remains. Preserve node lists rather than rendering children into HTML strings.
**brand_nodes = > brand.nodes**
**links_nodes = > links.nodes**
**siblings = component.merge a=`brand_nodes` b=`links_nodes`**
**footer_columns = layout.columns children=`siblings` slot="footer"**
*> component.wrap children=`footer_columns` kind="footer" slot="footer"*
@@ -0,0 +1,5 @@
### Community
[About the project](/about)
[Return home](/)
@@ -0,0 +1,19 @@
---
markup: occlusion
import:
fs: lib/fs.mq.md
component: ext/web/component/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
This leaf owns only the footer/links/community Markdown content; its parent owns placement.
Edit adjacent content.md to change prose. Add a child directory when a second
layout responsibility appears instead of introducing HTML into the content.
**body = fs.read_text path="components/footer/links/community/content.md"**
*> component.markdown text=`body` slot="footer-links-community"*
@@ -0,0 +1,5 @@
### Documentation
[Handbook](/about)
[Service status](/api/ping)
@@ -0,0 +1,19 @@
---
markup: occlusion
import:
fs: lib/fs.mq.md
component: ext/web/component/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
This leaf owns only the footer/links/docs Markdown content; its parent owns placement.
Edit adjacent content.md to change prose. Add a child directory when a second
layout responsibility appears instead of introducing HTML into the content.
**body = fs.read_text path="components/footer/links/docs/content.md"**
*> component.markdown text=`body` slot="footer-links-docs"*
@@ -0,0 +1,23 @@
---
markup: occlusion
import:
component: ext/web/component/index.mq.md
layout: ext/web/layout/index.mq.md
docs: ./docs/index.mq.md
community: ./community/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
This parent arranges documentation links and community links. Content stays
in their Markdown leaves; this file owns their one placement relationship. Continue into each child index when another independent layout
remains. Preserve node lists rather than rendering children into HTML strings.
**docs_nodes = > docs.nodes**
**community_nodes = > community.nodes**
**siblings = component.merge a=`docs_nodes` b=`community_nodes`**
*> layout.columns children=`siblings` slot="footer-links"*
@@ -0,0 +1,26 @@
---
markup: occlusion
import:
component: ext/web/component/index.mq.md
layout: ext/web/layout/index.mq.md
nav: ./nav/index.mq.md
content: ./main/index.mq.md
footer: ./footer/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
This parent arranges navigation, main content and footer. Content stays
in their Markdown leaves; this file owns their one placement relationship. Continue into each child index when another independent layout
remains. Preserve node lists rather than rendering children into HTML strings.
**nav_nodes = > nav.nodes**
**content_nodes = > content.nodes**
**footer_nodes = > footer.nodes**
**upper_regions = component.merge a=`nav_nodes` b=`content_nodes`**
**home_regions = component.merge a=`upper_regions` b=`footer_nodes`**
*> layout.stack children=`home_regions` slot="home"*
@@ -0,0 +1,3 @@
# Executable documents
Split the layout before writing content. **Leaves own Markdown only.**
@@ -0,0 +1,19 @@
---
markup: occlusion
import:
fs: lib/fs.mq.md
component: ext/web/component/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
This leaf owns only the main Markdown content; its parent owns placement.
Edit adjacent content.md to change prose. Add a child directory when a second
layout responsibility appears instead of introducing HTML into the content.
**body = fs.read_text path="components/main/content.md"**
*> component.markdown text=`body` slot="main"*
@@ -0,0 +1 @@
[Home](/) · [About](/about) · [Status](/api/ping)
@@ -0,0 +1,19 @@
---
markup: occlusion
import:
fs: lib/fs.mq.md
component: ext/web/component/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
This leaf owns only the nav Markdown content; its parent owns placement.
Edit adjacent content.md to change prose. Add a child directory when a second
layout responsibility appears instead of introducing HTML into the content.
**body = fs.read_text path="components/nav/content.md"**
*> component.markdown text=`body` slot="nav"*
+16
View File
@@ -0,0 +1,16 @@
---
markup: occlusion
type: web
view: main
title: Marqdo layout handbook
route: /
import:
home: ./components/index.mq.md
---
# main
The page selects the layout root; follow components/index.mq.md for decomposition.
This main returns rows rather than HTML; view metadata opts into startup assembly.
*> home.nodes*
@@ -0,0 +1,10 @@
---
markup: occlusion
type: web
title: About
route: /about
---
# About
An ordinary Markdown Document keeps its original rendering path.
@@ -0,0 +1,12 @@
---
markup: occlusion
import:
home: ./components/index.mq.md
web: ext/web/web.mq.md
---
# main
**nodes = > home.nodes**
**html = web.render nodes=`nodes` title="Marqdo layout handbook"**
> print text=`html`
+12
View File
@@ -0,0 +1,12 @@
---
markup: occlusion
import:
web: ext/web/web.mq.md
---
# main
The `port`=18081 may be overridden with --bind. This launcher owns no layout.
**listen_port = int value=`port`**
> web.serve root="." host="127.0.0.1" port=`listen_port`
+1 -1
View File
@@ -1 +1 @@
2.1.5
2.6.0
+3462 -1893
View File
File diff suppressed because it is too large. Load diff
+72
View File
@@ -0,0 +1,72 @@
---
markup: occlusion
title: AI workflows — model adapters, agents, workbooks and trials
import:
model_api: ext/ai/llm.mq.md
---
Start here to choose an AI task. [Model calls](llm.mq.md) own prompts, model configuration,
stream collection and usage; [provider adapters](llm/index.mq.md) describe OpenAI-compatible
and Ollama requests. [Agents](agent.mq.md) own call-site context, the explicit tool registry,
policy routing, observations, workbook planning and continuation. [CoW trials](sandbox.mq.md)
own isolated file changes and promotion. [Step routing](policies/step-route.mq.md) is readable
policy data, not a second agent language. Chinese users can start at [索引](索引.mq.md).
Begin with this offline stream example; it does not request credentials, install a plugin or
contact a model. Commands run from the repository root:
```sh
marqdo call ext/ai/index.mq.md offline_example --json
```
For a live model call, configure its provider and credentials before invoking the existing llm
resource. A configured language or adapter does not prove a remote endpoint is available.
Agent operations require the native agent plugin, an explicit model and the permitted tools;
use cargo build -p marqdo_plugin_agent in this checkout. Never let a generated CALL line select
an arbitrary internal function. File, process and network permissions remain bounded by the host.
Develop one responsibility at a time: provider request shaping belongs under llm/, common model
state in llm.mq.md, planner orchestration in agent.mq.md and trial behavior in sandbox.mq.md.
Keep the agent's call-site and source budgets intact when changing its internal helpers; moving
an operation can affect context and replay. Review effect preparation, transitions and saved
results before adding retries, and do not repeat writes merely to reconstruct a checkpoint.
Use deterministic stream fixtures and local provider substitutes before live tests. Verify text,
usage, failed tools, lost responses, cancellation, context limits and durable continuation;
model output is data until an authorized tool target and arguments have been resolved.
## collect_events
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| events | list | required | Ordered semantic or supported provider stream-event records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Final text assembled by the public stream collector |
The supplied `events` are an already-observed stream, not instructions to request a new model
response or execute a tool. The shared collector understands delta/text, done.result and its
existing provider-frame conventions. We return *[Collect the existing stream into final text](model_api.collect(events=`events`))*
so offline processing and live transport use the same public assembly behavior.
## offline_example
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Hello world, assembled from actual semantic events without a model request |
The event table is a deterministic stream fixture. A delta introduces partial text, then the
final done result supplies the completed answer. Passing these through the public collector
verifies useful behavior; this tool does not manufacture a passed flag or a fake model answer.
`events` =
| @ | type | text | result |
|---|---|---|---|
| 1 | delta | "Hello " | None |
| 2 | done | None | "Hello world" |
We return *[Assemble the final text from the displayed stream](collect_events(events=`events`))*.
A real transport failure still needs its domain error handling; this fixture only demonstrates
stream assembly, and it deliberately performs no network operation.
+371 -178
View File
@@ -13,68 +13,88 @@ import:
openai: ext/ai/llm/openai.mq.md
---
Choose the public model resource here for ask, stream and collected response behavior. [The AI entry](index.mq.md) provides an offline event workflow; [the adapter entry](llm/index.mq.md) owns provider configuration and transport shapes. Agents and workbook orchestration belong in agent.mq.md. A created handle is configuration, not proof that authentication or a model request succeeded. Keep transport errors, semantic events and usage counters visible when extending this file.
## load_env
+ `path`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Load `.env` from cwd (optional `path=`). Does not override existing variables. |
Use `path`=None as the inputs for this operation.
Load `.env` from cwd (optional `path=`). Does not override existing variables.
*> sys.load_dotenv path=`path`*
Return *[Load dotenv](sys.load_dotenv(path=`path`))*.
## collect
+ `events`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| events | any | required | Ordered semantic or provider stream-event records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Collapse a stream event list to final answer text. Accepts semantic events (`delta` / `text` / `done.result` / `error.message`) and native-plugin raw SSE frames (`type=data` with OpenAI chunk JSON in `data`). Alias: `stream_result`. |
Use `events` as the inputs for this operation.
Collapse a stream event list to final answer text.
Accepts semantic events (`delta` / `text` / `done.result` / `error.message`) and
native-plugin raw SSE frames (`type=data` with OpenAI chunk JSON in `data`).
Alias: `stream_result`.
**answer = ""**
We retain **answer = ""**.
- [ev](遍历 events 为 ev)
**t = > json.get value=`ev` key="type"**
We retain **`t` = [Read the type field](json.get(value=`ev`, key="type"))**.
1. `t` == "done"
**done_r = > json.get value=`ev` key="result"**
We retain **`done_r` = [Read the result field](json.get(value=`ev`, key="result"))**.
1. `done_r`
**answer = `done_r`**
We retain **answer = `done_r`**.
2. *
**_ = 1**
2. `t` == "error"
**em = > json.get value=`ev` key="message"**
We retain **`em` = [Read the message field](json.get(value=`ev`, key="message"))**.
1. `em`
**answer = `em`**
We retain **answer = `em`**.
2. *
**_ = 1**
3. `t` == "delta"
4. `t` == "text"
**chunk = > json.get value=`ev` key="text"**
We retain **`chunk` = [Read the text field](json.get(value=`ev`, key="text"))**.
1. `chunk`
**answer = answer + chunk**
We retain **answer = answer + chunk**.
2. *
**_ = 1**
5. `t` == "data"
**raw = > json.get value=`ev` key="data"**
We retain **`raw` = [Read the data field](json.get(value=`ev`, key="data"))**.
1. `raw`
1. `raw` == "[DONE]"
**_ = 1**
2. *
**parsed = > json.parse text=`raw`**
We retain **`parsed` = [Parse the JSON transport text](json.parse(text=`raw`))**.
1. `parsed`
**choices = > json.get value=`parsed` key="choices"**
We retain **`choices` = [Read the choices field](json.get(value=`parsed`, key="choices"))**.
1. `choices`
**c0 = [1](access(choices, "1"))**
**delta = > json.get value=`c0` key="delta"**
We retain **`c0` = [Read 1 field](access(`choices`, "1"))**.
We retain **`delta` = [Read the delta field](json.get(value=`c0`, key="delta"))**.
1. `delta`
**piece = > json.get value=`delta` key="content"**
We retain **`piece` = [Read the content field](json.get(value=`delta`, key="content"))**.
1. `piece`
**answer = answer + piece**
We retain **answer = answer + piece**.
2. *
**_ = 1**
2. *
**msg = > json.get value=`c0` key="message"**
We retain **`msg` = [Read the message field](json.get(value=`c0`, key="message"))**.
1. `msg`
**piece = > json.get value=`msg` key="content"**
We retain **`piece` = [Read the content field](json.get(value=`msg`, key="content"))**.
1. `piece`
**answer = answer + piece**
We retain **answer = answer + piece**.
2. *
**_ = 1**
2. *
@@ -89,144 +109,272 @@ Alias: `stream_result`.
**_ = 1**
1. not `answer`
**answer = ""**
*answer*
We retain **answer = ""**.
Return *answer*.
## collect_usage
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| events | any | required | Ordered semantic or provider stream-event records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Best-effort `total_tokens` from stream frames (requires `stream_options.include_usage`). |
Use `events` as the inputs for this operation.
Best-effort `total_tokens` from stream frames (requires `stream_options.include_usage`).
We retain **tokens = None**.
1. `events`
- [ev](遍历 events 为 ev)
We retain **`t` = [Read the type field](json.get(value=`ev`, key="type"))**.
We retain **raw = None**.
1. `t` == "data"
We retain **`raw` = [Read the data field](json.get(value=`ev`, key="data"))**.
2. *
We retain **`u0` = [Read the usage field](json.get(value=`ev`, key="usage"))**.
1. `u0`
We retain **`tt0` = [Read the total_tokens field](json.get(value=`u0`, key="total_tokens"))**.
1. `tt0` != None
We retain **tokens = `tt0`**.
1. `raw`
1. not `raw` == "[DONE]"
We retain **`parsed` = [Parse the JSON transport text](json.parse(text=`raw`))**.
1. `parsed`
We retain **`u` = [Read the usage field](json.get(value=`parsed`, key="usage"))**.
1. `u`
We retain **`tt` = [Read the total_tokens field](json.get(value=`u`, key="total_tokens"))**.
1. `tt` != None
We retain **tokens = `tt`**.
Return *tokens*.
## stream_result
+ `events`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| events | any | required | Ordered semantic or provider stream-event records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Compatibility alias for `collect`. |
Use `events` as the inputs for this operation.
Compatibility alias for `collect`.
*> collect events=`events`*
Return *[Collect](collect(events=`events`))*.
## usage_from
+ `data`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| data | any | required | Structured input supplied to this adapter or resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Extract `{prompt_tokens,completion_tokens,total_tokens}` from an OpenAI-shaped response map (or empty zeros). |
Use `data` as the inputs for this operation.
Extract `{prompt_tokens,completion_tokens,total_tokens}` from an OpenAI-shaped response map (or empty zeros).
*> openai.usage_from data=`data`*
Return *[Usage from](openai.usage_from(data=`data`))*.
## create
+ `model`=None
+ `base_url`=None
+ `api_key`=None
+ `backend`=openai-compatible
+ `name`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | None | Model resource or provider model identifier, as required by this operation |
| base_url | any | None | Provider API base URL |
| api_key | any | None | Provider credential from trusted runtime configuration |
| backend | any | "openai-compatible" | Configured execution or provider backend |
| name | any | None | Name registered or looked up by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Factory for an LLM handle (same as constructing `# llm`). Env fallbacks apply inside the constructor. Optional `name=` tags the handle (`fast` / `reasoning`). |
Use `model`=None, `base_url`=None, `api_key`=None, `backend`="openai-compatible", `name`=None as the inputs for this operation.
Factory for an LLM handle (same as constructing `# llm`). Env fallbacks apply inside the constructor. Optional `name=` tags the handle (`fast` / `reasoning`).
**h = > llm model=`model` base_url=`base_url` api_key=`api_key` backend=`backend` name=`name`**
*h*
We retain **`h` = [Llm](llm(model=`model`, base_url=`base_url`, api_key=`api_key`, backend=`backend`, name=`name`))**.
Return *h*.
## fast
+ `model`=None
+ `base_url`=None
+ `api_key`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | None | Model resource or provider model identifier, as required by this operation |
| base_url | any | None | Provider API base URL |
| api_key | any | None | Provider credential from trusted runtime configuration |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Named small/fast handle. Model from arg, else `MARQDO_LLM_FAST_MODEL`, else default create model. |
Use `model`=None, `base_url`=None, `api_key`=None as the inputs for this operation.
Named small/fast handle. Model from arg, else `MARQDO_LLM_FAST_MODEL`, else default create model.
1. `model`
**mdl = `model`**
We retain **mdl = `model`**.
2. *
**mdl = > sys.env_get name="MARQDO_LLM_FAST_MODEL"**
We retain **`mdl` = [Env get](sys.env_get(name="MARQDO_LLM_FAST_MODEL"))**.
*> create model=`mdl` base_url=`base_url` api_key=`api_key` name="fast" backend="openai-compatible"*
Return *[Create](create(model=`mdl`, base_url=`base_url`, api_key=`api_key`, name="fast", backend="openai-compatible"))*.
## reasoning
+ `model`=None
+ `base_url`=None
+ `api_key`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | None | Model resource or provider model identifier, as required by this operation |
| base_url | any | None | Provider API base URL |
| api_key | any | None | Provider credential from trusted runtime configuration |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Named strong/reasoning handle. Model from arg, else `MARQDO_LLM_REASONING_MODEL`, else default create model. |
Use `model`=None, `base_url`=None, `api_key`=None as the inputs for this operation.
Named strong/reasoning handle. Model from arg, else `MARQDO_LLM_REASONING_MODEL`, else default create model.
1. `model`
**mdl = `model`**
We retain **mdl = `model`**.
2. *
**mdl = > sys.env_get name="MARQDO_LLM_REASONING_MODEL"**
We retain **`mdl` = [Env get](sys.env_get(name="MARQDO_LLM_REASONING_MODEL"))**.
*> create model=`mdl` base_url=`base_url` api_key=`api_key` name="reasoning" backend="openai-compatible"*
Return *[Create](create(model=`mdl`, base_url=`base_url`, api_key=`api_key`, name="reasoning", backend="openai-compatible"))*.
## prompt_body
+ `src`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| src | any | required | Prompt source or source-reference value |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | If `src` starts with YAML frontmatter declaring `type: prompt` / `类型: 提示`, return the body after the closing `---`; otherwise return `src` unchanged. |
Use `src` as the inputs for this operation.
If `src` starts with YAML frontmatter declaring `type: prompt` / `类型: 提示`, return the body after the closing `---`; otherwise return `src` unchanged.
**sw = > text.starts_with text=`src` prefix="---"**
We retain **`sw` = [Starts with](text.starts_with(text=`src`, prefix="---"))**.
1. not `sw`
*src*
Return *src*.
2. *
**parts = > split value=`src` sep="\n---\n"**
**n = > len value=`parts`**
We retain **`parts` = [Split](split(value=`src`, sep="\n---\n"))**.
We retain **`n` = [Len](len(value=`parts`))**.
1. `n` < 2
*src*
Return *src*.
2. *
**fm = > at value=`parts` index=0**
**is_p = > text.contains text=`fm` sub="type: prompt"**
We retain **`fm` = [At](at(value=`parts`, index=0))**.
We retain **`is_p` = [Contains](text.contains(text=`fm`, sub="type: prompt"))**.
1. not `is_p`
**is_p = > text.contains text=`fm` sub="类型: 提示"**
We retain **`is_p` = [Contains](text.contains(text=`fm`, sub="类型: 提示"))**.
2. *
**_ = 1**
1. `is_p`
**body = > at value=`parts` index=1**
*> text.str_trim s=`body`*
We retain **`body` = [At](at(value=`parts`, index=1))**.
Return *[Str trim](text.str_trim(s=`body`))*.
2. *
*src*
Return *src*.
## prompt_load
+ `path`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Load a prompt artifact (`.mq.md` / `.md`) from disk for `ask`. |
Use `path` as the inputs for this operation.
Load a prompt artifact (`.mq.md` / `.md`) from disk for `ask`.
**raw = > fs.read_text path=`path`**
*> prompt_body src=`raw`*
We retain **`raw` = [Read UTF-8 text from the selected file](fs.read_text(path=`path`))**.
Return *[Prompt body](prompt_body(src=`raw`))*.
## prompt
+ `path`=None
+ `text`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| text | any | None | Text supplied to the transformation or adapter |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Prompt artifact helper: `path=` loads a file; `text=` strips `type: prompt` frontmatter from an in-memory string. |
Use `path`=None, `text`=None as the inputs for this operation.
Prompt artifact helper: `path=` loads a file; `text=` strips `type: prompt` frontmatter from an in-memory string.
1. `path`
*> prompt_load path=`path`*
Return *[Prompt load](prompt_load(path=`path`))*.
2. `text`
*> prompt_body src=`text`*
Return *[Prompt body](prompt_body(src=`text`))*.
3. *
> print text=ext/ai/llm.prompt: pass path= or text=
> sys.exit code=1
We **[Print the prepared message](print(text="ext/ai/llm.prompt: pass", path="or", text=""))**.
We **[End this run with the selected exit status](sys.exit(code=1))**.
## ask
+ `prompt`=None
+ `path`=None
+ `model`=None
+ `base_url`=None
+ `api_key`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | None | Prompt text or structured prompt expected by this adapter |
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| model | any | None | Model resource or provider model identifier, as required by this operation |
| base_url | any | None | Provider API base URL |
| api_key | any | None | Provider credential from trusted runtime configuration |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Module convenience: create a default handle and return **answer text**. Pass `path=` to load a prompt document, `prompt=` text, or omit both to use the entry `.mq.md` as a prompt artifact (`type: prompt` body via `sys.module_source`). |
Use `prompt`=None, `path`=None, `model`=None, `base_url`=None, `api_key`=None as the inputs for this operation.
Module convenience: create a default handle and return **answer text**. Pass `path=` to load a prompt document, `prompt=` text, or omit both to use the entry `.mq.md` as a prompt artifact (`type: prompt` body via `sys.module_source`).
**p = `prompt`**
We retain **p = `prompt`**.
1. `path`
**p = > prompt_load path=`path`**
We retain **`p` = [Prompt load](prompt_load(path=`path`))**.
2. `prompt`
**p = `prompt`**
We retain **p = `prompt`**.
3. *
**raw = > sys.module_source**
We retain **`raw` = [Module source](sys.module_source())**.
1. not `raw`
> print text=ext/ai/llm.ask: pass prompt= or path= (or run a prompt document as entry)
> sys.exit code=1
We **[Print the prepared message](print(text="ext/ai/llm.ask: pass", prompt="or", path="(or run a prompt document as entry)"))**.
We **[End this run with the selected exit status](sys.exit(code=1))**.
2. *
**p = > prompt_body src=`raw`**
We retain **`p` = [Prompt body](prompt_body(src=`raw`))**.
**m = > create model=`model` base_url=`base_url` api_key=`api_key`**
**r = > m.ask prompt=`p`**
**_ret = > json.get value=`r` key="text"**
*_ret*
We retain **`m` = [Create](create(model=`model`, base_url=`base_url`, api_key=`api_key`))**.
We retain **`r` = [Ask](m.ask(prompt=`p`))**.
We retain **`_ret` = [Read the text field](json.get(value=`r`, key="text"))**.
Return *_ret*.
# llm
+ `model`=None
+ `base_url`=None
+ `api_key`=None
+ `backend`=openai-compatible
+ `name`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | None | Model resource or provider model identifier, as required by this operation |
| base_url | any | None | Provider API base URL |
| api_key | any | None | Provider credential from trusted runtime configuration |
| backend | any | "openai-compatible" | Configured execution or provider backend |
| name | any | None | Name registered or looked up by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | LLM handle — intelligence primitive, not an HTTP client. Resolution: explicit args → entry-scope / Artifact Metadata (`sys.meta_get`) → `sys.env_get` → defaults. Prefer declaring `model` / `api_key` / `base_url` in frontmatter Binding, then use the lifted names. |
Use `model`=None, `base_url`=None, `api_key`=None, `backend`="openai-compatible", `name`=None as the inputs for this operation.
LLM handle — intelligence primitive, not an HTTP client.
@@ -234,13 +382,13 @@ Resolution: explicit args → entry-scope / Artifact Metadata (`sys.meta_get`)
Prefer declaring `model` / `api_key` / `base_url` in frontmatter Binding, then use the lifted names.
1. `api_key`
**key = `api_key`**
We retain **key = `api_key`**.
2. *
**key = > sys.meta_get key="api_key"**
We retain **`key` = [Meta get](sys.meta_get(key="api_key"))**.
1. not `key`
**key = > sys.env_get name="OPENAI_API_KEY"**
We retain **`key` = [Env get](sys.env_get(name="OPENAI_API_KEY"))**.
1. not `key`
**key = > sys.env_get name="MARQDO_LLM_API_KEY"**
We retain **`key` = [Env get](sys.env_get(name="MARQDO_LLM_API_KEY"))**.
2. *
**_ = 1**
2. *
@@ -248,62 +396,62 @@ Prefer declaring `model` / `api_key` / `base_url` in frontmatter Binding, then u
1. `backend` == ollama
1. not `key`
**key = "ollama"**
We retain **key = "ollama"**.
2. *
**_ = 1**
2. not `key`
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY (or pass api_key= / metadata api_key)
> sys.exit code=1
We **[Print the prepared message](print(text="ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY (or pass api_key= / metadata api_key)"))**.
We **[End this run with the selected exit status](sys.exit(code=1))**.
3. *
**_ = 1**
1. `base_url`
**url = `base_url`**
We retain **url = `base_url`**.
2. *
**url = > sys.meta_get key="base_url"**
We retain **`url` = [Meta get](sys.meta_get(key="base_url"))**.
1. `url`
**_ = 1**
2. `backend` == ollama
**url = > sys.env_get name="OLLAMA_HOST"**
We retain **`url` = [Env get](sys.env_get(name="OLLAMA_HOST"))**.
1. not `url`
**url = "http://127.0.0.1:11434/v1"**
We retain **url = "http://127.0.0.1:11434/v1"**.
2. *
**_ = 1**
3. *
**url = > sys.env_get name="OPENAI_BASE_URL"**
We retain **`url` = [Env get](sys.env_get(name="OPENAI_BASE_URL"))**.
1. not `url`
**url = > sys.env_get name="MARQDO_LLM_BASE_URL"**
We retain **`url` = [Env get](sys.env_get(name="MARQDO_LLM_BASE_URL"))**.
2. *
**_ = 1**
1. not `url`
**url = "https://api.openai.com/v1"**
We retain **url = "https://api.openai.com/v1"**.
2. *
**_ = 1**
1. `model`
**mdl = `model`**
We retain **mdl = `model`**.
2. *
**mdl = > sys.meta_get key="model"**
We retain **`mdl` = [Meta get](sys.meta_get(key="model"))**.
1. `mdl`
**_ = 1**
2. *
**mdl = > sys.env_get name="OPENAI_MODEL"**
We retain **`mdl` = [Env get](sys.env_get(name="OPENAI_MODEL"))**.
1. not `mdl`
**mdl = > sys.env_get name="MARQDO_LLM_MODEL"**
We retain **`mdl` = [Env get](sys.env_get(name="MARQDO_LLM_MODEL"))**.
2. *
**_ = 1**
1. not `mdl`
1. `backend` == ollama
**mdl = "llama3.2"**
We retain **mdl = "llama3.2"**.
2. *
**mdl = "gpt-4o-mini"**
We retain **mdl = "gpt-4o-mini"**.
2. *
**_ = 1**
1. `name`
**nm = `name`**
We retain **nm = `name`**.
2. *
**nm = None**
We retain **nm = None**.
`h` =
@@ -311,49 +459,58 @@ Prefer declaring `model` / `api_key` / `base_url` in frontmatter Binding, then u
|-------|---------|---------|----------|-------|--------|--------|------|
| llm | `backend` | `key` | `url` | `mdl` | /chat/completions | "Bearer " | `nm` |
*h*
Return *h*.
## ask
+ `prompt`=None
+ `path`=None
+ `messages`=None
+ `selection`=None
+ `strict_selection`=False
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | None | Prompt text or structured prompt expected by this adapter |
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| messages | any | None | Ordered chat message records |
| selection | any | None | Explicit runtime/model selection |
| strict_selection | any | False | Whether an unresolved selection is an error |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Semantic ask → **LLMResult** (`text`, `model`, `finish`, `backend`, `usage`, `name`, `tool_calls`). Prefer `[text](result)` for the answer string. Omit `prompt=` / `path=` to use the entry document (`sys.module_source` + `prompt_body`). Pass `messages=` for multi-turn history (M01). `selection=` + `strict_selection=True` freeze request identity without env fallback. |
Use `prompt`=None, `path`=None, `messages`=None, `selection`=None, `strict_selection`=False as the inputs for this operation.
Semantic ask → **LLMResult** (`text`, `model`, `finish`, `backend`, `usage`, `name`, `tool_calls`). Prefer `[text](result)` for the answer string. Omit `prompt=` / `path=` to use the entry document (`sys.module_source` + `prompt_body`). Pass `messages=` for multi-turn history (M01). `selection=` + `strict_selection=True` freeze request identity without env fallback.
**p = `prompt`**
We retain **p = `prompt`**.
1. `messages`
**p = None**
We retain **p = None**.
2. `path`
**p = > prompt_load path=`path`**
We retain **`p` = [Prompt load](prompt_load(path=`path`))**.
3. `prompt`
**p = `prompt`**
We retain **p = `prompt`**.
4. *
**raw = > sys.module_source**
We retain **`raw` = [Module source](sys.module_source())**.
1. not `raw`
**p = ""**
We retain **p = ""**.
2. *
**p = > prompt_body src=`raw`**
**pack = > self.complete_result prompt=`p` messages=`messages` selection=`selection` strict_selection=`strict_selection` stream=False echo=False**
**text = > json.get value=`pack` key="text"**
**usage = > json.get value=`pack` key="usage"**
**finish = > json.get value=`pack` key="finish"**
**err = > json.get value=`pack` key="error"**
**tc = > json.get value=`pack` key="tool_calls"**
We retain **`p` = [Prompt body](prompt_body(src=`raw`))**.
We retain **`pack` = [Complete result](self.complete_result(prompt=`p`, messages=`messages`, selection=`selection`, strict_selection=`strict_selection`, stream=False, echo=False))**.
We retain **`text` = [Read the text field](json.get(value=`pack`, key="text"))**.
We retain **`usage` = [Read the usage field](json.get(value=`pack`, key="usage"))**.
We retain **`finish` = [Read the finish field](json.get(value=`pack`, key="finish"))**.
We retain **`err` = [Read the error field](json.get(value=`pack`, key="error"))**.
We retain **`tc` = [Read the tool_calls field](json.get(value=`pack`, key="tool_calls"))**.
1. not `tc`
**tc = > table.empty_list**
We retain **`tc` = [Empty list](table.empty_list())**.
2. *
**_ = 1**
1. not `text`
**text = ""**
We retain **text = ""**.
2. *
**_ = 1**
1. not `finish`
1. `err`
**finish = "error"**
We retain **finish = "error"**.
2. *
**finish = "stop"**
We retain **finish = "stop"**.
2. *
**_ = 1**
@@ -361,26 +518,26 @@ Hoist receiver fields before the result table — table cells can shadow `self`
column names (`model`, `usage`), so `[model](self)` / `[total_tokens](usage)`
inside the table is unsafe.
**mdl = > json.get value=`self` key="model"**
**b = > json.get value=`self` key="backend"**
**nm = > json.get value=`self` key="name"**
We retain **`mdl` = [Read the model field](json.get(value=`self`, key="model"))**.
We retain **`b` = [Read the backend field](json.get(value=`self`, key="backend"))**.
We retain **`nm` = [Read the name field](json.get(value=`self`, key="name"))**.
1. `usage`
**tt = > json.get value=`usage` key="total_tokens"**
**ustate = > json.get value=`usage` key="usage_state"**
We retain **`tt` = [Read the total_tokens field](json.get(value=`usage`, key="total_tokens"))**.
We retain **`ustate` = [Read the usage_state field](json.get(value=`usage`, key="usage_state"))**.
2. *
**tt = None**
**ustate = "unknown"**
We retain **tt = None**.
We retain **ustate = "unknown"**.
1. `ustate` == "unknown"
Keep null — never coerce missing usage to zero tokens (M02 / F04).
**tt = None**
We retain **tt = None**.
2. not `tt`
**tt = None**
We retain **tt = None**.
3. *
**_ = 1**
1. `err`
**calls = 0**
We retain **calls = 0**.
2. *
**calls = 1**
We retain **calls = 1**.
`result` =
@@ -388,66 +545,102 @@ inside the table is unsafe.
|------|-------|--------|---------|-------|------|-----------|--------|------------|-------|-----------|
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | `calls` | `tt` | `tc` | `err` | `selection` |
*result*
Return *result*.
## stream
+ `prompt`=None
+ `path`=None
+ `echo`=False
+ `stream_kind`="delta"
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | None | Prompt text or structured prompt expected by this adapter |
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| echo | any | False | Whether to print the documented incremental output |
| stream_kind | any | "delta" | Streaming event projection selected by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Semantic stream: return the event list (use `llm.collect` to reduce to text). Omit `prompt=` / `path=` to use the entry document. |
Use `prompt`=None, `path`=None, `echo`=False, `stream_kind`="delta" as the inputs for this operation.
Semantic stream: return the event list (use `llm.collect` to reduce to text). Omit `prompt=` / `path=` to use the entry document.
`stream_kind=plan` tags EventBus frames for the parent plan protocol (process trail).
1. `path`
**p = > prompt_load path=`path`**
We retain **`p` = [Prompt load](prompt_load(path=`path`))**.
2. `prompt`
**p = `prompt`**
We retain **p = `prompt`**.
3. *
**raw = > sys.module_source**
We retain **`raw` = [Module source](sys.module_source())**.
1. not `raw`
**p = ""**
We retain **p = ""**.
2. *
**p = > prompt_body src=`raw`**
We retain **`p` = [Prompt body](prompt_body(src=`raw`))**.
*> self.complete prompt=`p` stream=True echo=`echo` stream_kind=`stream_kind`*
Return *[Complete](self.complete(prompt=`p`, stream=True, echo=`echo`, stream_kind=`stream_kind`))*.
## complete_result
+ `prompt`=None
+ `messages`=None
+ `selection`=None
+ `strict_selection`=False
+ `stream`=False
+ `echo`=False
+ `stream_kind`="delta"
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | None | Prompt text or structured prompt expected by this adapter |
| messages | any | None | Ordered chat message records |
| selection | any | None | Explicit runtime/model selection |
| strict_selection | any | False | Whether an unresolved selection is an error |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| stream_kind | any | "delta" | Streaming event projection selected by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Transport pack via `ext/ai/llm/openai` (Ollama uses the same OpenAI-compatible path). Non-stream → `{text,usage,finish}`; stream → `{events}`. Prefer `messages=` for multi-turn; optional `selection=` (ModelSelectionV1) with `strict_selection=True` for request-scoped identity (M01). |
Use `prompt`=None, `messages`=None, `selection`=None, `strict_selection`=False, `stream`=False, `echo`=False, `stream_kind`="delta" as the inputs for this operation.
Transport pack via `ext/ai/llm/openai` (Ollama uses the same OpenAI-compatible path). Non-stream → `{text,usage,finish}`; stream → `{events}`. Prefer `messages=` for multi-turn; optional `selection=` (ModelSelectionV1) with `strict_selection=True` for request-scoped identity (M01).
*> openai.chat_completions base_url=[base_url](access(self, "base_url")) api_key=[api_key](access(self, "api_key")) model=[model](access(self, "model")) prompt=`prompt` messages=`messages` selection=`selection` strict_selection=`strict_selection` stream=`stream` echo=`echo` stream_kind=`stream_kind` suffix=[suffix](access(self, "suffix")) bearer=[bearer](access(self, "bearer"))*
Return *[Chat completions](openai.chat_completions(base_url=[base_url](access(`self`, "base_url")), api_key=[api_key](access(`self`, "api_key")), model=[model](access(`self`, "model")), prompt=`prompt`, messages=`messages`, selection=`selection`, strict_selection=`strict_selection`, stream=`stream`, echo=`echo`, stream_kind=`stream_kind`, suffix=[suffix](access(`self`, "suffix")), bearer=[bearer](access(`self`, "bearer"))))*.
## complete
+ `prompt`
+ `stream`=False
+ `echo`=False
+ `stream_kind`="delta"
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | required | Prompt text or structured prompt expected by this adapter |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| stream_kind | any | "delta" | Streaming event projection selected by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Internal / compatibility primitive. Prefer `ask` / `stream` in new code. |
Use `prompt`, `stream`=False, `echo`=False, `stream_kind`="delta" as the inputs for this operation.
Internal / compatibility primitive. Prefer `ask` / `stream` in new code.
1. `stream`
**pack = > self.complete_result prompt=`prompt` stream=True echo=`echo` stream_kind=`stream_kind`**
**_ret = > json.get value=`pack` key="events"**
*_ret*
We retain **`pack` = [Complete result](self.complete_result(prompt=`prompt`, stream=True, echo=`echo`, stream_kind=`stream_kind`))**.
We retain **`_ret` = [Read the events field](json.get(value=`pack`, key="events"))**.
Return *_ret*.
2. *
**pack = > self.complete_result prompt=`prompt` stream=False echo=`echo` stream_kind=`stream_kind`**
**_ret = > json.get value=`pack` key="text"**
*_ret*
We retain **`pack` = [Complete result](self.complete_result(prompt=`prompt`, stream=False, echo=`echo`, stream_kind=`stream_kind`))**.
We retain **`_ret` = [Read the text field](json.get(value=`pack`, key="text"))**.
Return *_ret*.
## chat
+ `prompt`
+ `stream`=False
+ `echo`=False
+ `stream_kind`="delta"
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | any | required | Prompt text or structured prompt expected by this adapter |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| stream_kind | any | "delta" | Streaming event projection selected by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Alias for `complete` (compat). |
Use `prompt`, `stream`=False, `echo`=False, `stream_kind`="delta" as the inputs for this operation.
Alias for `complete` (compat).
*> self.complete prompt=`prompt` stream=`stream` echo=`echo` stream_kind=`stream_kind`*
Return *[Complete](self.complete(prompt=`prompt`, stream=`stream`, echo=`echo`, stream_kind=`stream_kind`))*.
+60
View File
@@ -0,0 +1,60 @@
---
markup: occlusion
title: Provider adapters — requests, configuration and usage
import:
ollama: ext/ai/llm/ollama.mq.md
openai: ext/ai/llm/openai.mq.md
---
This directory owns provider adaptation. [OpenAI-compatible requests](openai.mq.md) encode chat
messages, decode replies and usage, and retain streaming/error conventions. [Ollama](ollama.mq.md)
selects its documented local defaults while reusing compatible transport. The parent [model API](../llm.mq.md)
creates author model resources; [the AI root](../index.mq.md) explains agent and trial responsibilities.
This offline usage example inspects response data only. It does not read credentials, load a
plugin or contact the provider:
```sh
marqdo call ext/ai/llm/index.mq.md usage 'data={"usage":{"prompt_tokens":2,"completion_tokens":3,"total_tokens":5}}' --json
```
For local configuration, resolve_local reads the documented environment fallbacks and therefore
needs environment.read. Sending chat_completions is a real HTTP effect and requires an explicitly
configured endpoint, timeout and credential handling. Do not print a live configuration record
containing secrets merely to prove that an adapter exists.
When adding a provider, preserve semantic message/event/result shapes at the public model boundary.
Keep provider-specific headers and endpoint paths in the adapter, document supported response
variants and test them against local fixtures before live traffic. A usage fixture does not verify
provider availability, streaming latency or authentication.
## usage
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| data | map | required | Already received OpenAI-compatible response record |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Public prompt_tokens/completion_tokens/total_tokens usage projection |
The `data` record is an observation rather than a request body. Missing counters follow the
public adapter convention; the example above contains two input tokens, three output tokens and
five total tokens. We return *[Read actual usage counters from the supplied response](openai.usage_from(data=`data`))*
without claiming to have measured a new model invocation.
## resolve_local
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | None | Explicit local model override; None uses the adapter fallback |
| base_url | any | None | Explicit local API base URL; None uses the documented environment/default |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Actual Ollama configuration selected by the existing resolver |
The caller may supply `model`=None and `base_url`=None to use the shared local configuration
rules. Resolving the configuration does not launch a service or ask the model for a response.
We return *[Resolve local model fields with the existing adapter](ollama.resolve(model=`model`, base_url=`base_url`))*.
Treat the resulting configuration as runtime data and only execute a request after granting its effects.
+39 -19
View File
@@ -9,32 +9,41 @@ import:
---
## resolve
+ `model`=None
+ `base_url`=None
+ `api_key`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | None | Model resource or provider model identifier, as required by this operation |
| base_url | any | None | Provider API base URL |
| api_key | any | None | Provider credential from trusted runtime configuration |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Resolve Ollama handle fields: default host `http://127.0.0.1:11434/v1`, key `ollama`, model `llama3.2`. |
Use `model`=None, `base_url`=None, `api_key`=None as the inputs for this operation.
Resolve Ollama handle fields: default host `http://127.0.0.1:11434/v1`, key `ollama`, model `llama3.2`.
1. `api_key`
**key = api_key**
We retain **key = api_key**.
2. *
**key = "ollama"**
We retain **key = "ollama"**.
1. `base_url`
**url = base_url**
We retain **url = base_url**.
2. *
**url = > sys.env_get name="OLLAMA_HOST"**
We retain **`url` = [Env get](sys.env_get(name="OLLAMA_HOST"))**.
1. not `url`
**url = "http://127.0.0.1:11434/v1"**
We retain **url = "http://127.0.0.1:11434/v1"**.
2. *
**_ = 1**
1. `model`
**mdl = model**
We retain **mdl = model**.
2. *
**mdl = > sys.env_get name="MARQDO_LLM_MODEL"**
We retain **`mdl` = [Env get](sys.env_get(name="MARQDO_LLM_MODEL"))**.
1. not `mdl`
**mdl = "llama3.2"**
We retain **mdl = "llama3.2"**.
2. *
**_ = 1**
@@ -44,14 +53,25 @@ Resolve Ollama handle fields: default host `http://127.0.0.1:11434/v1`, key `oll
|---------|---------|----------|-------|
| ollama | `key` | `url` | `mdl` |
*cfg*
Return *cfg*.
## chat_completions
+ `base_url`
+ `api_key`
+ `model`
+ `prompt`
+ `stream`=False
+ `echo`=False
*> openai.chat_completions base_url=`base_url` api_key=`api_key` model=`model` prompt=`prompt` stream=`stream` echo=`echo`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| base_url | any | required | Provider API base URL |
| api_key | any | required | Provider credential from trusted runtime configuration |
| model | any | required | Model resource or provider model identifier, as required by this operation |
| prompt | any | required | Prompt text or structured prompt expected by this adapter |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Send the prepared chat request through this provider adapter and retain its usage, stream and failure conventions. |
Use `base_url`, `api_key`, `model`, `prompt`, `stream`=False, `echo`=False as the inputs for this operation.
Send the prepared chat request through this provider adapter and retain its usage, stream and failure conventions.
Return *[Chat completions](openai.chat_completions(base_url=`base_url`, api_key=`api_key`, model=`model`, prompt=`prompt`, stream=`stream`, echo=`echo`))*.
Loaded 100 of 448 files, more files were not shown because too many files have changed in this diff. Show more