Compare commits

..
9 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
309 changed files with 38184 additions and 7458 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
+20 -10
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
@@ -26,7 +26,7 @@ These rules are the **current default**. Do **not** teach Classic `[key](map)` i
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.
@@ -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.
@@ -136,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
---
@@ -186,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/).
@@ -195,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`.
@@ -221,7 +231,7 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
- `invoke` returns a record (`ok`, `code`, `stdout`, `stderr`, `ms`, `timed_out`, `truncated`, `result`); pass `input` for JSON stdin and `output="json"` for a parsed result.
- `call` is JSON-in / JSON-out; `call_many` fans out one program over a list with ordered results.
- `session_open` returns an opaque `handle` (not text; not JSON-serializable). `session_eval` / `set` / `get` borrow the handle; `session_close` consumes it (double-close / use-after-close fault). Prefer `foreign.replay_check` / language-level `foreign.oracle_journal` when comparing recordings (`replay_snapshot` only re-runs). JSON integers outside \(\pm(2^{53}-1)\) and ragged table columns are refused (`doc/design/v-safe-json.md`, `foreign-strong-correspondence.md`, `oracle-journal-values.md`).
- `session_open` starts a persistent Python/Node kernel; `session_eval` evaluates source; `session_set` / `session_get` bridge values explicitly as JSON. Close it with `session_close`.
- A view document opts into kernel state with `会话 = > foreign.session kernels=... cells=...`; the table names are free. `view` consumes only the `会话` handle and never scans source lines or reserved table names. Without `会话`, cells are stateless one-shot runs; no kernel is created. Clearing outputs calls `/api/session/clear` and keeps persistent kernel state. There is no separate notebook CLI mode or command, and no new Markdown marker exists.
- The same source remains the authority; state crossing kernels is explicit, never implicitly mirrored.
+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 -53
View File
@@ -126,59 +126,14 @@ jobs:
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **v2.5.1**:View 连线优化——真实源码锚点、连续 S 形曲线、错落与避让;工具栏文字标签;保留深浅色配色
- **v2.5.1**: View annotation refinement — exact source anchors, flowing S-curves, staggered notes and collision avoidance; labeled toolbar; preserved themes
- **v2.5.1 ext**:扩展包同步 2.5.1 / Ext pack 2.5.1
- **v2.5.0**:View 阅读界面重构——暖白金色主题、新 Logo、左右执行标注、导航搜索与悬浮工具栏;离线公式;重跑同次捕获刷新
- **v2.5.0**: View reader redesign — warm paper theme, new logo, margin execution notes, navigation/search and floating controls; offline math; same-capture live refresh
- **v2.5.0 ext**:扩展包同步 2.5.0 / Ext pack 2.5.0
- **v2.4.0**:Oracle journal 作语言值——`foreign.oracle_journal`/`replay_check`;bytecode/frontend 硬化;MSRV 1.81
- **v2.4.0**: Oracle journal as language values — foreign.oracle_journal/replay_check; bytecode/frontend hardening; MSRV 1.81
- **v2.4.0 ext**:扩展包同步 2.4.0 / Ext pack 2.4.0
- **v2.3.0**:Foreign Strong——不透明 `handle`、仿射 close、`replay_check`/oracle journal、表 arity refuse、Ω∈V_safe
- **v2.3.0**: Foreign Strong — opaque handle, affine close, replay_check/oracle journal, table arity refuse, Ω∈V_safe
- **v2.3.0 ext**:扩展包同步 2.3.0 / Ext pack 2.3.0
- **v2.2.1**:view / 静态导出——修复 occlusion 与中等宽度下大纲侧栏掉到正文下方
- **v2.2.1**: view / static export — fix outline rail nested under document (occlusion + mid-width layout)
- **v2.2.1 ext**:扩展包同步 2.2.1 / Ext pack 2.2.1
- **v2.2.0**:函数级调用 `marqdo call`——同一份 .mq.md 就是文档、知识和工具;Tree/Bytecode 执行被点名的函数;外部调用默认只跑纯函数
- **v2.2.0**: `marqdo call` runs one function in any .mq.md — the file is the document, the knowledge and the tool; Tree and Bytecode execute that function; external calls stay pure
- **v2.2.0 ext**:扩展包同步 2.2.0 / Ext pack 2.2.0
- **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
+2
View File
@@ -87,6 +87,8 @@ plugins/*/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/
+47
View File
@@ -8,6 +8,53 @@
### 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
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.5.1"
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.5.1"
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"
+3 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "2.5.1"
version = "2.6.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -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).
+12 -4
View File
@@ -12,6 +12,10 @@ v2.2.0 起,`marqdo call` 可以直接调用这份文件里的一个函数。
---
标准库单文件本身就是手册:直接阅读[文件库](lib/文件.mq.md)、[集合库](lib/表.mq.md)等源码,按函数标题下的参数表、返回契约和动作说明调用;[工程实践](examples/stdlib-handbook/索引.mq.md)演示文件整理、CSV 汇总与文档维护。
开发标准库和拓展库请直接阅读[可执行库开发指南](doc/library-development.mq.md):契约表、叙述式实现、遮蔽调用与多文件工程组织均有可运行示范。
## 核心优势:可执行知识(Executable Knowledge)
> **Knowledge That Can Run —— 知识即可执行。**
@@ -284,7 +288,11 @@ marqdo catalog public -o .marqdo
---
## 现状(v2.5.1)
## 现状(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**。
@@ -337,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.5.1)
### 如何使用最新 Marqdo(v2.6.0)
**安装解释器(任选其一)**
@@ -352,7 +360,7 @@ marqdo catalog public -o .marqdo
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v2.5.1 # 或留在 main
git checkout v2.6.0 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -393,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.5.1
# 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.5.1"
version = "2.6.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
+8
View File
@@ -1,3 +1,11 @@
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,
+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)。
+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. 波次
+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) |
+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 盖章失败,不改全局配置。
+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。
失败记录只说明这次操作没有成功;它不会捕获任意语言错误,也不会替调用者授予权限。
+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 改动。
+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.5.1
2.6.0
+3435 -1930
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.
+355 -191
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,173 +109,272 @@ Alias: `stream_result`.
**_ = 1**
1. not `answer`
**answer = ""**
*answer*
We retain **answer = ""**.
Return *answer*.
## collect_usage
+ `events`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 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`).
**tokens = None**
We retain **tokens = None**.
1. `events`
- [ev](遍历 events 为 ev)
**t = > json.get value=`ev` key="type"**
**raw = None**
We retain **`t` = [Read the type field](json.get(value=`ev`, key="type"))**.
We retain **raw = None**.
1. `t` == "data"
**raw = > json.get value=`ev` key="data"**
We retain **`raw` = [Read the data field](json.get(value=`ev`, key="data"))**.
2. *
**u0 = > json.get value=`ev` key="usage"**
We retain **`u0` = [Read the usage field](json.get(value=`ev`, key="usage"))**.
1. `u0`
**tt0 = > json.get value=`u0` key="total_tokens"**
We retain **`tt0` = [Read the total_tokens field](json.get(value=`u0`, key="total_tokens"))**.
1. `tt0` != None
**tokens = `tt0`**
We retain **tokens = `tt0`**.
1. `raw`
1. not `raw` == "[DONE]"
**parsed = > json.parse text=`raw`**
We retain **`parsed` = [Parse the JSON transport text](json.parse(text=`raw`))**.
1. `parsed`
**u = > json.get value=`parsed` key="usage"**
We retain **`u` = [Read the usage field](json.get(value=`parsed`, key="usage"))**.
1. `u`
**tt = > json.get value=`u` key="total_tokens"**
We retain **`tt` = [Read the total_tokens field](json.get(value=`u`, key="total_tokens"))**.
1. `tt` != None
**tokens = `tt`**
*tokens*
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.
@@ -263,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. *
@@ -277,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` =
@@ -340,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**
@@ -390,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` =
@@ -417,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`))*.
+104 -73
View File
@@ -15,31 +15,40 @@ import:
---
## 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. |
Use `data` as the inputs for this operation.
Extract `{prompt_tokens,completion_tokens,total_tokens}` from an OpenAI-shaped response map.
**u = > json.get value=`data` key="usage"**
We retain **`u` = [Read the usage field](json.get(value=`data`, key="usage"))**.
1. `u`
**pt = > json.get value=`u` key="prompt_tokens"**
**ct = > json.get value=`u` key="completion_tokens"**
**tt = > json.get value=`u` key="total_tokens"**
We retain **`pt` = [Read the prompt_tokens field](json.get(value=`u`, key="prompt_tokens"))**.
We retain **`ct` = [Read the completion_tokens field](json.get(value=`u`, key="completion_tokens"))**.
We retain **`tt` = [Read the total_tokens field](json.get(value=`u`, key="total_tokens"))**.
1. not `pt`
**pt = 0**
We retain **pt = 0**.
2. *
**_ = 1**
1. not `ct`
**ct = 0**
We retain **ct = 0**.
2. *
**_ = 1**
1. not `tt`
**tt = pt + ct**
We retain **tt = pt + ct**.
2. *
**_ = 1**
2. *
**pt = 0**
**ct = 0**
**tt = 0**
We retain **pt = 0**.
We retain **ct = 0**.
We retain **tt = 0**.
`usage` =
@@ -47,58 +56,77 @@ Extract `{prompt_tokens,completion_tokens,total_tokens}` from an OpenAI-shaped r
|---------------|-------------------|--------------|
| `pt` | `ct` | `tt` |
*usage*
Return *usage*.
## tool_calls_from
+ `data`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| data | any | required | Structured input supplied to this adapter or resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Extract OpenAI-shaped `choices[0].message.tool_calls` as a list (or empty list). |
Use `data` as the inputs for this operation.
Extract OpenAI-shaped `choices[0].message.tool_calls` as a list (or empty list).
**choices = > json.get value=`data` key="choices"**
We retain **`choices` = [Read the choices field](json.get(value=`data`, key="choices"))**.
1. not `choices`
*> table.empty_list*
Return *[Empty list](table.empty_list())*.
2. *
**c0 = [1](access(choices, "1"))**
**msg = > json.get value=`c0` key="message"**
We retain **`c0` = [Read 1 field](access(`choices`, "1"))**.
We retain **`msg` = [Read the message field](json.get(value=`c0`, key="message"))**.
1. not `msg`
*> table.empty_list*
Return *[Empty list](table.empty_list())*.
2. *
**tc = > json.get value=`msg` key="tool_calls"**
We retain **`tc` = [Read the tool_calls field](json.get(value=`msg`, key="tool_calls"))**.
1. `tc`
*tc*
Return *tc*.
2. *
*> table.empty_list*
Return *[Empty list](table.empty_list())*.
## chat_completions
+ `base_url`
+ `api_key`
+ `model`
+ `prompt`=None
+ `messages`=None
+ `selection`=None
+ `strict_selection`=False
+ `auth_mode`=None
+ `stream`=False
+ `echo`=False
+ `stream_kind`="delta"
+ `suffix`=/chat/completions
+ `bearer`="Bearer "
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 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 | 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 |
| auth_mode | any | None | Authentication mode used by the provider 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 |
| suffix | any | "/chat/completions" | Provider endpoint suffix |
| bearer | any | "Bearer " | Bearer credential supplied by the configured provider |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | POST `/chat/completions` (or stream SSE). Prefers `plugins/llm` ABI (`llm_chat_completions`) when the native plugin is resolvable; otherwise `lib/net` HTTP/SSE. Non-stream → `{text,usage,finish,tool_calls}`; stream → `{events,finish}`. Soft transport / HTTP failures return `finish=error` packs (never abort the VM). Pass either `messages=` (role/content list) or legacy `prompt=` (single user message). Optional `selection=` is a ModelSelectionV1 snapshot; `strict_selection=True` refuses env fallbacks inside the plugin. |
Use `base_url`, `api_key`, `model`, `prompt`=None, `messages`=None, `selection`=None, `strict_selection`=False, `auth_mode`=None, `stream`=False, `echo`=False, `stream_kind`="delta", `suffix`="/chat/completions", `bearer`="Bearer " as the inputs for this operation.
POST `/chat/completions` (or stream SSE). Prefers `plugins/llm` ABI (`llm_chat_completions`) when the native plugin is resolvable; otherwise `lib/net` HTTP/SSE. Non-stream → `{text,usage,finish,tool_calls}`; stream → `{events,finish}`. Soft transport / HTTP failures return `finish=error` packs (never abort the VM).
Pass either `messages=` (role/content list) or legacy `prompt=` (single user message). Optional `selection=` is a ModelSelectionV1 snapshot; `strict_selection=True` refuses env fallbacks inside the plugin.
`stream_kind` tags live EventBus frames: `delta` (answer tokens) or `plan` (parent protocol — UI process trail, not the bubble).
**p = > plugin.native_path name="llm"**
We retain **`p` = [Locate the installed native plugin](plugin.native_path(name="llm"))**.
1. `p`
> plugin.load path=`p`
*> llm_chat_completions base_url=`base_url` api_key=`api_key` model=`model` prompt=`prompt` messages=`messages` selection=`selection` strict_selection=`strict_selection` auth_mode=`auth_mode` stream=`stream` echo=`echo` stream_kind=`stream_kind` suffix=`suffix` bearer=`bearer`*
We **[Load the native plugin required by this operation](plugin.load(path=`p`))**.
Return *[Llm chat completions](llm_chat_completions(base_url=`base_url`, api_key=`api_key`, model=`model`, prompt=`prompt`, messages=`messages`, selection=`selection`, strict_selection=`strict_selection`, auth_mode=`auth_mode`, stream=`stream`, echo=`echo`, stream_kind=`stream_kind`, suffix=`suffix`, bearer=`bearer`))*.
2. *
**url = base_url + suffix**
**auth = bearer + api_key**
**headers = > table.put in=None at="Authorization" value=`auth`**
We retain **url = base_url + suffix**.
We retain **auth = bearer + api_key**.
We retain **`headers` = [Set the Authorization field in the new record](table.put(in=None, at="Authorization", value=`auth`))**.
1. not `messages`
`messages` =
| @ | role | content |
@@ -114,19 +142,20 @@ Pass either `messages=` (role/content list) or legacy `prompt=` (single user mes
| `model` | `messages` |
1. `stream`
**req = > table.put in=`req` at="stream" value=True**
We retain **`req` = [Set the stream field in the new record](table.put(in=`req`, at="stream", value=True))**.
`stream_opts` =
| include_usage |
|---------------|
| True |
**req = > table.put in=`req` at="stream_options" value=`stream_opts`**
**body = > json.stringify value=`req`**
**resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`**
**st = > json.get value=`resp` key="status"**
We retain **`req` = [Set the stream_options field in the new record](table.put(in=`req`, at="stream_options", value=`stream_opts`))**.
We retain **`body` = [Encode the structured value as JSON text](json.stringify(value=`req`))**.
We retain **`resp` = [Http post sse](net.http_post_sse(url=`url`, body=`body`, headers=`headers`, echo=`echo`))**.
We retain **`st` = [Read the status field](json.get(value=`resp`, key="status"))**.
1. `st` == 200
**evs = > json.get value=`resp` key="events"**
We retain **`evs` = [Read the events field](json.get(value=`resp`, key="events"))**.
`pack` =
@@ -134,45 +163,46 @@ Pass either `messages=` (role/content list) or legacy `prompt=` (single user mes
|--------|--------|
| stop | `evs` |
*pack*
Return *pack*.
2. *
Soft transport / HTTP failure — structured pack, never abort the VM.
**msg = "HTTP " + `st`**
**evs = > json.get value=`resp` key="events"**
We retain **msg = "HTTP " + `st`**.
We retain **`evs` = [Read the events field](json.get(value=`resp`, key="events"))**.
1. `evs`
**e0 = > at value=`evs` index=0**
**m2 = > json.get value=`e0` key="message"**
We retain **`e0` = [At](at(value=`evs`, index=0))**.
We retain **`m2` = [Read the message field](json.get(value=`e0`, key="message"))**.
1. `m2`
**msg = `m2`**
We retain **msg = `m2`**.
`pack` =
| finish | text | error | events |
|--------|------|-------|--------|
| error | "" | `msg` | `evs` |
*pack*
Return *pack*.
2. *
**body = > json.stringify value=`req`**
**resp = > net.http_post url=`url` body=`body` headers=`headers`**
**st = > json.get value=`resp` key="status"**
We retain **`body` = [Encode the structured value as JSON text](json.stringify(value=`req`))**.
We retain **`resp` = [Http post](net.http_post(url=`url`, body=`body`, headers=`headers`))**.
We retain **`st` = [Read the status field](json.get(value=`resp`, key="status"))**.
1. `st` == 200
**raw = > json.get value=`resp` key="body"**
**data = > json.parse text=`raw`**
**choices = > json.get value=`data` key="choices"**
**choice0 = > at value=`choices` index=0**
**msg = > json.get value=`choice0` key="message"**
**text = > json.get value=`msg` key="content"**
We retain **`raw` = [Read the body field](json.get(value=`resp`, key="body"))**.
We retain **`data` = [Parse the JSON transport text](json.parse(text=`raw`))**.
We retain **`choices` = [Read the choices field](json.get(value=`data`, key="choices"))**.
We retain **`choice0` = [At](at(value=`choices`, index=0))**.
We retain **`msg` = [Read the message field](json.get(value=`choice0`, key="message"))**.
We retain **`text` = [Read the content field](json.get(value=`msg`, key="content"))**.
1. not `text`
**text = ""**
We retain **text = ""**.
2. *
**_ = 1**
**usage = > usage_from data=`data`**
**fr = > json.get value=`choice0` key="finish_reason"**
We retain **`usage` = [Usage from](usage_from(data=`data`))**.
We retain **`fr` = [Read the finish_reason field](json.get(value=`choice0`, key="finish_reason"))**.
1. not `fr`
**fr = "stop"**
We retain **fr = "stop"**.
2. *
**_ = 1**
**tc = > tool_calls_from data=`data`**
We retain **`tc` = [Tool calls from](tool_calls_from(data=`data`))**.
`pack` =
@@ -180,20 +210,21 @@ Pass either `messages=` (role/content list) or legacy `prompt=` (single user mes
|--------|------|-------|------------|
| `fr` | `text` | `usage` | `tc` |
*pack*
Return *pack*.
2. *
Soft transport / HTTP failure — structured pack, never abort the VM.
**raw = > json.get value=`resp` key="body"**
**msg = "HTTP " + `st`**
We retain **`raw` = [Read the body field](json.get(value=`resp`, key="body"))**.
We retain **msg = "HTTP " + `st`**.
1. `raw`
**msg = `msg` + ": " + `raw`**
We retain **msg = `msg` + ": " + `raw`**.
`usage0` =
| prompt_tokens | completion_tokens | total_tokens |
|---------------|-------------------|--------------|
| 0 | 0 | 0 |
**empty_tc = > table.empty_list**
We retain **`empty_tc` = [Empty list](table.empty_list())**.
`pack` =
@@ -201,4 +232,4 @@ Pass either `messages=` (role/content list) or legacy `prompt=` (single user mes
|--------|------|-------|-------|------------|
| error | "" | `msg` | `usage0` | `empty_tc` |
*pack*
Return *pack*.
+21 -3
View File
@@ -6,21 +6,39 @@ description: >
Readable authority for agent.step_route; do not invent a second dialect.
---
# Step class → backend
Step class to backend.
Authors and `agent.step_route` read this table. Backends match Adaptive Routing:
`marqdo` | `small-llm` | `llm` | `auto`.
## routes
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Return the same readable route table used by the agent policy reader. |
Return the same readable route table used by the agent policy reader.
Each column is a list with the same row order. Lookup and sandbox execution prefer Marqdo, patch work prefers the small model, and network-oriented work uses the model route. The default row leaves the final choice to the existing router. Returning these values does not load or invoke a backend.
**routes = **
| kind | backend | note |
|------|---------|------|
| lookup | marqdo | OKF / kb skill hit — no parent LLM |
| patch | small-llm | Local patch / soft match |
| sandbox_run | marqdo | CoW trial of `.mq.md` |
| sandbox_run | marqdo | "CoW trial of .mq.md" |
| net | llm | Needs network / toolful turn |
| default | auto | Cascade policy → kb → small-llm |
Return *routes*.
# main
*routes*
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | The entry returns the policy data without creating a second routing dialect. |
The entry returns the policy data without creating a second routing dialect.
Return *[Routes](routes())*.
+198 -71
View File
@@ -15,17 +15,34 @@ Load the agent plugin once per call (same pattern as other `ext/ai` helpers).
Capability profiles are GFM tables under `## profile` (readable authority; `open` / `inspect` echo them). Do not invent a second table dialect.
CoW trial operations belong here; attaching a sandbox profile to another result does not isolate execution. [The AI entry](index.mq.md) explains the relation to model and agent resources. A trial produces inspectable changes; promotion is a separate existing operation with its own checks. Keep cancellation, failed execution and explicit promotion visible, and never equate a generated source file with a committed successful outcome.
## ensure_plugin
**p = plugin.native_path name="agent"**
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | No business value on completion; a missing native plugin reports the cause and exits this run. |
Resolve and load the required native ABI plugin; missing binaries report a diagnostic message and stop this run.
We retain **`p` = [Locate the installed native plugin](plugin.native_path(name="agent"))**.
1. `p`
> plugin.load path=`p`
We **[Load the native plugin required by this operation](plugin.load(path=`p`))**.
2. *
> print text=ext/ai/sandbox: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent)
> sys.exit code=1
We **[Print the prepared message](print(text="ext/ai/sandbox: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent)"))**.
We **[End this run with the selected exit status](sys.exit(code=1))**.
## profile
+ `name`=default
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | any | "default" | Name registered or looked up by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Named caps row as a map table (`name`, `fs_write`, `exec`, `net`, `plugin`). Unknown names → `default`. Catalog (documentation + authority): |
Use `name`="default" as the inputs for this operation.
Named caps row as a map table (`name`, `fs_write`, `exec`, `net`, `plugin`). Unknown names → `default`.
@@ -50,139 +67,249 @@ Catalog (documentation + authority):
|------|----------|------|-----|--------|
| default | true | false | false | false |
*row*
Return *row*.
## open_native
+ `root`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| root | any | None | Explicit root directory for discovery or isolated execution |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Native CoW open (plugin ABI italic return). Prefer `## open` for the profile-aware facade. |
Use `root`=None as the inputs for this operation.
Native CoW open (plugin ABI italic return). Prefer `## open` for the profile-aware facade.
> ensure_plugin
We **[Load the native plugin required by this operation](ensure_plugin())**.
1. `root`
*> sandbox_open root=`root`*
Return *[Native CoW open (plugin ABI italic return). Prefer ## open for the profile-aware facade.](sandbox_open(root=`root`))*.
2. *
*> sandbox_open*
Return *[Native CoW open (plugin ABI italic return). Prefer ## open for the profile-aware facade.](sandbox_open())*.
## open
+ `root`=None
+ `profile`=default
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| root | any | None | Explicit root directory for discovery or isolated execution |
| profile | any | "default" | Capability profile selected for the trial |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Open a CoW session. Optional `root=` (directory). Default: entry file directory. |
Use `root`=None, `profile`="default" as the inputs for this operation.
Open a CoW session. Optional `root=` (directory). Default: entry file directory.
`profile=` selects the caps row from `## profile` (echoed by `inspect`).
**sess = open_native root=`root`**
**prof = profile name=`profile`**
**sess = table.put in=`sess` at="profile" value=`prof`**
*sess*
We retain **`sess` = [Open native](open_native(root=`root`))**.
We retain **`prof` = [Profile](profile(name=`profile`))**.
We retain **`sess` = [Set the profile field in the new record](table.put(in=`sess`, at="profile", value=`prof`))**.
Return *sess*.
## write
+ `id`
+ `path`
+ `text`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| text | any | required | Text supplied to the transformation or adapter |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Write text into the session upper layer (host tree unchanged until `commit`). |
Use `id`, `path`, `text` as the inputs for this operation.
Write text into the session upper layer (host tree unchanged until `commit`).
> ensure_plugin
*> sandbox_write id=`id` path=`path` text=`text`*
We **[Load the native plugin required by this operation](ensure_plugin())**.
Return *[Write text into the session upper layer (host tree unchanged until commit).](sandbox_write(id=`id`, path=`path`, text=`text`))*.
## read
+ `id`
+ `path`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Read through CoW (upper, else lower; whiteout misses). |
Use `id`, `path` as the inputs for this operation.
Read through CoW (upper, else lower; whiteout misses).
> ensure_plugin
*> sandbox_read id=`id` path=`path`*
We **[Load the native plugin required by this operation](ensure_plugin())**.
Return *[Read through CoW (upper, else lower; whiteout misses).](sandbox_read(id=`id`, path=`path`))*.
## remove
+ `id`
+ `path`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Logical delete (whiteout). |
Use `id`, `path` as the inputs for this operation.
Logical delete (whiteout).
> ensure_plugin
*> sandbox_remove id=`id` path=`path`*
We **[Load the native plugin required by this operation](ensure_plugin())**.
Return *[Logical delete (whiteout).](sandbox_remove(id=`id`, path=`path`))*.
## diff
+ `id`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | List of `{ path, kind }` pending changes (`write` &#124; `remove`). |
Use `id` as the inputs for this operation.
List of `{ path, kind }` pending changes (`write` | `remove`).
> ensure_plugin
*> sandbox_diff id=`id`*
We **[Load the native plugin required by this operation](ensure_plugin())**.
Return *[List of { path, kind } pending changes (write | remove).](sandbox_diff(id=`id`))*.
## commit
+ `id`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Apply upper / whiteout to the real workspace root. |
Use `id` as the inputs for this operation.
Apply upper / whiteout to the real workspace root.
> ensure_plugin
*> sandbox_commit id=`id`*
We **[Load the native plugin required by this operation](ensure_plugin())**.
Return *[Apply upper / whiteout to the real workspace root.](sandbox_commit(id=`id`))*.
## discard
+ `id`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Drop the session without writing the host tree. |
Use `id` as the inputs for this operation.
Drop the session without writing the host tree.
> ensure_plugin
*> sandbox_discard id=`id`*
We **[Load the native plugin required by this operation](ensure_plugin())**.
Return *[Drop the session without writing the host tree.](sandbox_discard(id=`id`))*.
## run
+ `id`
+ `source`=None
+ `path`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| source | any | None | Source text inspected or prepared by this operation |
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Run Marqdo under sandbox caps (`exec` / `net` / `plugin` off; fs via CoW). Pass `source=` or `path=` (relative to session root). |
Use `id`, `source`=None, `path`=None as the inputs for this operation.
Run Marqdo under sandbox caps (`exec` / `net` / `plugin` off; fs via CoW).
Pass `source=` or `path=` (relative to session root).
> ensure_plugin
We **[Load the native plugin required by this operation](ensure_plugin())**.
1. `source`
*> sandbox_run id=`id` source=`source`*
Return *[Run Marqdo under sandbox caps (exec / net / plugin off; fs via CoW). Pass source= or path= (relative to session root).](sandbox_run(id=`id`, source=`source`))*.
2. `path`
*> sandbox_run id=`id` path=`path`*
Return *[Run Marqdo under sandbox caps (exec / net / plugin off; fs via CoW). Pass source= or path= (relative to session root).](sandbox_run(id=`id`, path=`path`))*.
3. *
> print text=ext/ai/sandbox.run: need source= or path=
> sys.exit code=1
We **[Print the prepared message](print(text="ext/ai/sandbox.run: need", source="or", path=""))**.
We **[End this run with the selected exit status](sys.exit(code=1))**.
## inspect_native
+ `id`
> ensure_plugin
*> sandbox_inspect id=`id`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Inspect an existing native CoW session without promoting its writes. |
Use `id` as the inputs for this operation.
Inspect an existing native CoW session without promoting its writes.
We **[Load the native plugin required by this operation](ensure_plugin())**.
Return *[Inspect an existing native CoW session without promoting its writes.](sandbox_inspect(id=`id`))*.
## inspect
+ `id`
+ `profile`=default
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| profile | any | "default" | Capability profile selected for the trial |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Native caps / change counts, plus the GFM `## profile` row under key `profile`. |
Use `id`, `profile`="default" as the inputs for this operation.
Native caps / change counts, plus the GFM `## profile` row under key `profile`.
**raw = inspect_native id=`id`**
**prof = profile name=`profile`**
**out = table.put in=`raw` at="profile" value=`prof`**
*out*
We retain **`raw` = [Inspect native](inspect_native(id=`id`))**.
We retain **`prof` = [Profile](profile(name=`profile`))**.
We retain **`out` = [Set the profile field in the new record](table.put(in=`raw`, at="profile", value=`prof`))**.
Return *out*.
## report
+ `id`
+ `path`=sandbox-diff.md
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| path | any | "sandbox-diff.md" | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | O4: write a markdown review of `## diff` for `marqdo view` / HITL (static report file, not a UI rewrite). |
Use `id`, `path`="sandbox-diff.md" as the inputs for this operation.
O4: write a markdown review of `## diff` for `marqdo view` / HITL (static report file, not a UI rewrite).
**pending = diff id=`id`**
**n = len value=`pending`**
**body = "# Sandbox diff report\n\nPending changes: "**
**body = body + n**
**body = body + "\n\n| path | kind |\n|------|------|\n"**
We retain **`pending` = [Diff](diff(id=`id`))**.
We retain **`n` = [Len](len(value=`pending`))**.
We retain **body = "# Sandbox diff report\n\nPending changes: "**.
We retain **body = body + n**.
We retain **body = body + "\n\n| path | kind |\n|------|------|\n"**.
- [row](遍历 pending 为 row)
**p = [path](access(row, "path"))**
**k = [kind](access(row, "kind"))**
**body = body + "| "**
**body = body + p**
**body = body + " | "**
**body = body + k**
**body = body + " |\n"**
> fs.write_text path=`path` text=`body`
We retain **`p` = [Read path field](access(`row`, "path"))**.
We retain **`k` = [Read kind field](access(`row`, "kind"))**.
We retain **body = body + "| "**.
We retain **body = body + p**.
We retain **body = body + " | "**.
We retain **body = body + k**.
We retain **body = body + " |\n"**.
We **[Write the prepared text to the selected file](fs.write_text(path=`path`, text=`body`))**.
**out = **
@@ -190,4 +317,4 @@ O4: write a markdown review of `## diff` for `marqdo view` / HITL (static report
|------|-------|
| `path` | `n` |
*out*
Return *out*.
+342 -147
View File
@@ -5,6 +5,7 @@ description: >-
Marqdo 大模型智能原语 — 提问 / 流式 / 收集 / 命名句柄。
OpenAI 兼容与 Ollama HTTP 藏在语义面之后。
导入:
table: lib/table.mq.md
系统: lib/系统.mq.md
json: lib/json.mq.md
文件: lib/文件.mq.md
@@ -12,64 +13,90 @@ description: >-
openai: ext/ai/llm/openai.mq.md
---
## 加载环境
+ `路径`=None
本文件是中文模型资源门面;从[中文入口](索引.mq.md)可以先运行无需联网的事件收集示例。提供方请求实现位于 llm 子目录,智能体编排位于智能体文件。创建资源只解析配置;真实请求还需插件、服务和授权。修改时同时核对英文模型面、语义事件、用量字段与传输失败,不把空文本当作可靠的成功信号。
*> 系统.加载环境 路径=`路径`*
## 加载环境
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 路径 | any | None | 授权根目录内的文件路径 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 读取指定 dotenv 文件且保留已有环境变量;它不发送模型请求。 |
这里使用`路径`=None。
读取指定 dotenv 文件且保留已有环境变量;它不发送模型请求。
完成后返回*[调用 加载环境](系统.加载环境(路径=`路径`))*。
## 收集
+ `事件`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 事件 | any | 必填 | 按顺序排列的流事件记录 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | Collapse stream events to text. Supports semantic `delta`/`done.result` and native-plugin raw frames (`type=data` + OpenAI chunk JSON). |
这里使用`事件`。
Collapse stream events to text. Supports semantic `delta`/`done.result` and
native-plugin raw frames (`type=data` + OpenAI chunk JSON).
**answer = ""**
例如先收到两个 delta 再收到 done 时,以最后非空 result 为准;只收到无内容事件则返回空文本。按事件顺序处理文本:delta 与 text 的 text 字段追加到当前回答;done 中非空的 result 覆盖累积文本;error 中非空的 message 也成为当前文本。因此返回的是收集文本,不是独立的成功状态。调用方若需区分失败,应同时检查原始事件,不能把非空文本当成请求成功。
兼容的 data 事件承载提供方 JSON。结束标记 [DONE] 不作为正文;普通数据从首条 choice 的 delta.content 或 message.content 读取。缺失内容不会凭空产生片段,JSON 解码失败仍遵循解析库的诊断。这里不排序、不重试,也不发送模型请求;输入顺序决定最终文字,空事件序列得到空字符串。
得到**answer = ""**。
- [ev](遍历 事件 为 ev)
**t = [type](access(ev, "type"))**
得到**`t` = [读取 type 字段](access(`ev`, "type"))**。
1. `t` == "done"
**done_r = [result](access(ev, "result"))**
得到**`done_r` = [读取 result 字段](access(`ev`, "result"))**。
1. `done_r`
**answer = `done_r`**
得到**answer = `done_r`**。
2. *
**_ = 1**
2. `t` == "error"
**em = [message](access(ev, "message"))**
得到**`em` = [读取 message 字段](access(`ev`, "message"))**。
1. `em`
**answer = `em`**
得到**answer = `em`**。
2. *
**_ = 1**
3. `t` == "delta"
4. `t` == "text"
**chunk = [text](access(ev, "text"))**
得到**`chunk` = [读取 text 字段](access(`ev`, "text"))**。
1. `chunk`
**answer = answer + chunk**
得到**answer = answer + chunk**。
2. *
**_ = 1**
5. `t` == "data"
**raw = [data](access(ev, "data"))**
得到**`raw` = [读取 data 字段](access(`ev`, "data"))**。
1. `raw`
1. `raw` == "[DONE]"
**_ = 1**
2. *
**parsed = > json.parse text=`raw`**
得到**`parsed` = [解析 JSON 传输文本](json.parse(text=`raw`))**。
1. `parsed`
**choices = [choices](access(parsed, "choices"))**
得到**`choices` = [读取 choices 字段](access(`parsed`, "choices"))**。
1. `choices`
**c0 = [1](access(choices, "1"))**
**delta = [delta](access(c0, "delta"))**
得到**`c0` = [读取 1 字段](access(`choices`, "1"))**。
得到**`delta` = [读取 delta 字段](access(`c0`, "delta"))**。
1. `delta`
**piece = [content](access(delta, "content"))**
得到**`piece` = [读取 content 字段](access(`delta`, "content"))**。
1. `piece`
**answer = answer + piece**
得到**answer = answer + piece**。
2. *
**_ = 1**
2. *
**msg = [message](access(c0, "message"))**
得到**`msg` = [读取 message 字段](access(`c0`, "message"))**。
1. `msg`
**piece = [content](access(msg, "content"))**
得到**`piece` = [读取 content 字段](access(`msg`, "content"))**。
1. `piece`
**answer = answer + piece**
得到**answer = answer + piece**。
2. *
**_ = 1**
2. *
@@ -84,180 +111,291 @@ native-plugin raw frames (`type=data` + OpenAI chunk JSON).
**_ = 1**
1. not `answer`
**answer = ""**
*answer*
得到**answer = ""**。
完成后返回*answer*。
## 流式结果
+ `事件`
*> 收集 事件=`事件`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 事件 | any | 必填 | 按顺序排列的流事件记录 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 将流事件交给同源收集器,返回最终回答文本。 |
这里使用`事件`。
将流事件交给同源收集器,返回最终回答文本。
完成后返回*[调用 收集](收集(事件=`事件`))*。
## 用量
+ `数据`
*> openai.usage_from data=`数据`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 数据 | any | 必填 | 交给本操作处理的结构化数据 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 从提供方响应中提取 token 用量,缺失计数采用公开实现约定。 |
这里使用`数据`。
从提供方响应中提取 token 用量,缺失计数采用公开实现约定。
完成后返回*[调用 usage from](openai.usage_from(data=`数据`))*。
## 创建
+ `模型`=None
+ `基址`=None
+ `密钥`=None
+ `后端`=openai-compatible
+ `名`=None
**h = > 大模型 模型=`模型` 基址=`基址` 密钥=`密钥` 后端=`后端` 名=`名`**
*h*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 模型 | any | None | 已配置的模型资源或模型标识 |
| 基址 | any | None | 提供方 API 基址 |
| 密钥 | any | None | 可信运行配置提供的凭据,不应写入日志 |
| 后端 | any | "openai-compatible" | 明确选择的执行或模型后端 |
| 名 | any | None | 本操作注册或查找的名称 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 按模型、基址和鉴权配置创建可复用的大模型资源;此步骤不请求回答。 |
这里使用`模型`=None、`基址`=None、`密钥`=None、`后端`="openai-compatible"、`名`=None。
按模型、基址和鉴权配置创建可复用的大模型资源;此步骤不请求回答。
得到**`h` = [调用 大模型](大模型(模型=`模型`, 基址=`基址`, 密钥=`密钥`, 后端=`后端`, 名=`名`))**。
完成后返回*h*。
## 快速
+ `模型`=None
+ `基址`=None
+ `密钥`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 模型 | any | None | 已配置的模型资源或模型标识 |
| 基址 | any | None | 提供方 API 基址 |
| 密钥 | any | None | 可信运行配置提供的凭据,不应写入日志 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 将当前输入交给 创建,保留同源能力的返回值和失败语义。 |
这里使用`模型`=None、`基址`=None、`密钥`=None。
1. `模型`
**mdl = 模型**
得到**mdl = 模型**。
2. *
**mdl = > 系统.取环境 名="MARQDO_LLM_FAST_MODEL"**
得到**`mdl` = [调用 取环境](系统.取环境(名="MARQDO_LLM_FAST_MODEL"))**。
*> 创建 模型=`mdl` 基址=`基址` 密钥=`密钥` 名="fast" 后端="openai-compatible"*
完成后返回*[调用 创建](创建(模型=`mdl`, 基址=`基址`, 密钥=`密钥`, 名="fast", 后端="openai-compatible"))*。
## 推理
+ `模型`=None
+ `基址`=None
+ `密钥`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 模型 | any | None | 已配置的模型资源或模型标识 |
| 基址 | any | None | 提供方 API 基址 |
| 密钥 | any | None | 可信运行配置提供的凭据,不应写入日志 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 将当前输入交给 创建,保留同源能力的返回值和失败语义。 |
这里使用`模型`=None、`基址`=None、`密钥`=None。
1. `模型`
**mdl = 模型**
得到**mdl = 模型**。
2. *
**mdl = > 系统.取环境 名="MARQDO_LLM_REASONING_MODEL"**
得到**`mdl` = [调用 取环境](系统.取环境(名="MARQDO_LLM_REASONING_MODEL"))**。
*> 创建 模型=`mdl` 基址=`基址` 密钥=`密钥` 名="reasoning" 后端="openai-compatible"*
完成后返回*[调用 创建](创建(模型=`mdl`, 基址=`基址`, 密钥=`密钥`, 名="reasoning", 后端="openai-compatible"))*。
## 提示正文
+ `源`
**sw = > 文本.开头是 内容=`源` 前缀="---"**
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 源 | any | 必填 | 提示正文或源码来源 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 从指定文本构造提示正文,保留输入内容而不请求模型。 |
这里使用`源`。
从指定文本构造提示正文,保留输入内容而不请求模型。
这里只识别源文本开头的前置元数据,且仅对声明为 prompt 或提示的文档提取正文。普通 Markdown、没有结束分隔线的文本和其他类型文档原样保留。正文只取当前分隔实现得到的首段并去掉两端空白,不承担通用 YAML 解析或提示模板插值;需要完整文件时使用文件库读取。
得到**`sw` = [调用 开头是](文本.开头是(内容=`源`, 前缀="---"))**。
1. 非 `sw`
*源*
完成后返回*源*。
2. *
**parts = > split value=`源` sep="\n---\n"**
**n = > len value=`parts`**
得到**`parts` = [调用 split](split(value=`源`, sep="\n---\n"))**。
得到**`n` = [调用 len](len(value=`parts`))**。
1. `n` < 2
*源*
完成后返回*源*。
2. *
**fm = > at value=`parts` index=0**
**is_p = > 文本.包含 内容=`fm` 子串="type: prompt"**
得到**`fm` = [调用 at](at(value=`parts`, index=0))**。
得到**`is_p` = [调用 包含](文本.包含(内容=`fm`, 子串="type: prompt"))**。
1. 非 `is_p`
**is_p = > 文本.包含 内容=`fm` 子串="类型: 提示"**
得到**`is_p` = [调用 包含](文本.包含(内容=`fm`, 子串="类型: 提示"))**。
2. *
**_ = 1**
1. `is_p`
**body = > at value=`parts` index=1**
*> 文本.去空白 s=`body`*
得到**`body` = [调用 at](at(value=`parts`, index=1))**。
完成后返回*[调用 去空白](文本.去空白(s=`body`))*。
2. *
*源*
完成后返回*源*。
## 加载提示
+ `路径`
**raw = > 文件.读文本 路径=`路径`**
*> 提示正文 源=`raw`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 路径 | any | 必填 | 授权根目录内的文件路径 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 从指定文件加载提示正文;文件访问仍受宿主文件权限限制。 |
这里使用`路径`。
从指定文件加载提示正文;文件访问仍受宿主文件权限限制。
得到**`raw` = [读取指定文件的 UTF-8 正文](文件.读文本(路径=`路径`))**。
完成后返回*[调用 提示正文](提示正文(源=`raw`))*。
## 提示
+ `路径`=None
+ `文本`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 路径 | any | None | 授权根目录内的文件路径 |
| 文本 | any | None | 本操作接收的文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 将当前输入交给 提示正文,保留同源能力的返回值和失败语义。 |
这里使用`路径`=None、`文本`=None。
1. `路径`
*> 加载提示 路径=`路径`*
完成后返回*[调用 加载提示](加载提示(路径=`路径`))*。
2. `文本`
*> 提示正文 源=`文本`*
完成后返回*[调用 提示正文](提示正文(源=`文本`))*。
3. *
> 打印 内容=ext/ai/大模型.提示: 请传 路径= 或 文本=
> 系统.退出 码=1
这里**[输出本步已准备的消息](打印(内容="ext/ai/大模型.提示: 请传", 路径="或", 文本=""))**。
这里**[调用 退出](系统.退出(码=1))**。
## 提问
+ `提示`=None
+ `路径`=None
+ `模型`=None
+ `基址`=None
+ `密钥`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 提示 | any | None | 提供给模型的提示内容 |
| 路径 | any | None | 授权根目录内的文件路径 |
| 模型 | any | None | 已配置的模型资源或模型标识 |
| 基址 | any | None | 提供方 API 基址 |
| 密钥 | any | None | 可信运行配置提供的凭据,不应写入日志 |
| p | any | 必填 | Prompt value passed to the selected model |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 将当前输入交给 access,保留同源能力的返回值和失败语义。 |
这里使用`提示`=None、`路径`=None、`模型`=None、`基址`=None、`密钥`=None、`p`。
1. `路径`
**p = > 加载提示 路径=`路径`**
得到**`p` = [调用 加载提示](加载提示(路径=`路径`))**。
2. `提示`
**p = 提示**
得到**p = 提示**。
3. *
> 打印 内容=ext/ai/大模型.提问: 请传 提示= 或 路径=
> 系统.退出 码=1
这里**[输出本步已准备的消息](打印(内容="ext/ai/大模型.提问: 请传", 提示="或", 路径=""))**。
这里**[调用 退出](系统.退出(码=1))**。
**m = > 创建 模型=`模型` 基址=`基址` 密钥=`密钥`**
**r = > m.提问 提示=`p`**
*[text](access(r, "text"))*
得到**`m` = [调用 创建](创建(模型=`模型`, 基址=`基址`, 密钥=`密钥`))**。
得到**`r` = [调用 提问](m.提问(提示=`p`))**。
完成后返回*[text](access(r, "text"))*。
# 大模型
+ `模型`=None
+ `基址`=None
+ `密钥`=None
+ `后端`=openai-compatible
+ `名`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 模型 | any | None | 已配置的模型资源或模型标识 |
| 基址 | any | None | 提供方 API 基址 |
| 密钥 | any | None | 可信运行配置提供的凭据,不应写入日志 |
| 后端 | any | "openai-compatible" | 明确选择的执行或模型后端 |
| 名 | any | None | 本操作注册或查找的名称 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 将当前输入交给 运行,保留同源能力的返回值和失败语义。 |
这里使用`模型`=None、`基址`=None、`密钥`=None、`后端`="openai-compatible"、`名`=None。
1. `密钥`
**key = 密钥**
构造器只整理连接配置并返回资源记录,不在此请求回答。显式传入的密钥优先,其后依次读取 OPENAI_API_KEY 与 MARQDO_LLM_API_KEY。兼容后端没有密钥会输出原因并以非零状态结束;本地 ollama 使用占位凭据以维持相同资源结构。记录包含实际凭据,应由调用方保管,避免直接打印整个句柄。
基址的选择同样保留显式值。ollama 未配置时使用本机兼容接口;其他后端依次尝试 OPENAI_BASE_URL、MARQDO_LLM_BASE_URL,最后采用公开默认地址。模型名依次来自显式值、OPENAI_MODEL、MARQDO_LLM_MODEL,最后按后端选用默认模型。默认模型名称只是现有运行约定,不保证提供方已开通、服务器已安装或网络可达。
返回记录保存后续请求所需的模型、后端、请求后缀、认证前缀和可选名称。实例方法从这个记录读取配置;改变环境不会自动重建已有句柄。需要切换配置时重新构造,不要把资源创建成功等同于鉴权或连通性验证。真实请求还要准备对应原生插件与运行授权;离线读取配置和真实网络调用是两个阶段。
例如在没有外部服务的离线配置检查中,可以显式选择 ollama、提供模型名与本地基址,只核对返回字段而不调用提问。在线验收则必须再检查真实请求的结束原因和用量。删除或覆盖环境配置前,也应考虑已有句柄仍保存旧凭据;本构造器不会主动清理其他资源或替调用方撤销密钥。
得到**key = 密钥**。
2. *
**key = > 系统.取环境 名="OPENAI_API_KEY"**
得到**`key` = [调用 取环境](系统.取环境(名="OPENAI_API_KEY"))**。
1. 非 `key`
**key = > 系统.取环境 名="MARQDO_LLM_API_KEY"**
得到**`key` = [调用 取环境](系统.取环境(名="MARQDO_LLM_API_KEY"))**。
2. *
**_ = 1**
1. `后端` == ollama
1. 非 `key`
**key = "ollama"**
得到**key = "ollama"**。
2. *
**_ = 1**
2. 非 `key`
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
> 系统.退出 码=1
这里**[输出本步已准备的消息](打印(内容="ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY"))**。
这里**[调用 退出](系统.退出(码=1))**。
3. *
**_ = 1**
1. `基址`
**url = 基址**
得到**url = 基址**。
2. `后端` == ollama
**url = > 系统.取环境 名="OLLAMA_HOST"**
得到**`url` = [调用 取环境](系统.取环境(名="OLLAMA_HOST"))**。
1. 非 `url`
**url = "http://127.0.0.1:11434/v1"**
得到**url = "http://127.0.0.1:11434/v1"**。
2. *
**_ = 1**
3. *
**url = > 系统.取环境 名="OPENAI_BASE_URL"**
得到**`url` = [调用 取环境](系统.取环境(名="OPENAI_BASE_URL"))**。
1. 非 `url`
**url = > 系统.取环境 名="MARQDO_LLM_BASE_URL"**
得到**`url` = [调用 取环境](系统.取环境(名="MARQDO_LLM_BASE_URL"))**。
2. *
**_ = 1**
1. 非 `url`
**url = "https://api.openai.com/v1"**
得到**url = "https://api.openai.com/v1"**。
2. *
**_ = 1**
1. `模型`
**mdl = 模型**
得到**mdl = 模型**。
2. *
**mdl = > 系统.取环境 名="OPENAI_MODEL"**
得到**`mdl` = [调用 取环境](系统.取环境(名="OPENAI_MODEL"))**。
1. 非 `mdl`
**mdl = > 系统.取环境 名="MARQDO_LLM_MODEL"**
得到**`mdl` = [调用 取环境](系统.取环境(名="MARQDO_LLM_MODEL"))**。
2. *
**_ = 1**
1. 非 `mdl`
1. `后端` == ollama
**mdl = "llama3.2"**
得到**mdl = "llama3.2"**。
2. *
**mdl = "gpt-4o-mini"**
得到**mdl = "gpt-4o-mini"**。
2. *
**_ = 1**
1. `名`
**nm = 名**
得到**nm = 名**。
2. *
**nm = None**
得到**nm = None**。
`h` =
@@ -265,36 +403,52 @@ native-plugin raw frames (`type=data` + OpenAI chunk JSON).
|-------|---------|---------|----------|-------|--------|--------|------|
| 大模型 | `后端` | `key` | `url` | `mdl` | /chat/completions | "Bearer " | `nm` |
*h*
完成后返回*h*。
## 提问
+ `提示`=None
+ `路径`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 提示 | any | None | 提供给模型的提示内容 |
| 路径 | any | None | 授权根目录内的文件路径 |
| p | any | 必填 | Prompt value passed to the selected model |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 将当前输入交给 access,保留同源能力的返回值和失败语义。 |
这里使用`提示`=None、`路径`=None、`p`。
1. `路径`
**p = > 加载提示 路径=`路径`**
2. `提示`
**p = 提示**
3. *
> 打印 内容=ext/ai/大模型: 提问需要 提示= 或 路径=
> 系统.退出 码=1
路径与直接提示同时存在时,先从路径加载提示;否则使用非空提示。两者都缺失时明确结束运行。当前接口还保留历史推断得到的 p 输入,表中如实列出其签名;本方法实际按上述分支重新设置请求正文,调用方不应把这个内部兼容参数当成另一种提示来源。
**pack = > 自.完整结果 提示=`p` 流式=False 打印增量=False**
**text = > json.get value=`pack` key="text"**
**usage = > json.get value=`pack` key="usage"**
**finish = > json.get value=`pack` key="finish"**
**tc = > json.get value=`pack` key="tool_calls"**
完整结果提供文本、结束原因、工具调用与用量。这里将它们整理为含模型与后端的记录;工具调用缺失时给出空列表。tokens 取 usage 中的 total_tokens,不能由回答字符数推算。llm_calls 是该接口的调用计数字段,并非计费凭据或独立的成功证明。网络失败应按完整结果的 finish 和相关诊断处理,不能只看 text 是否非空。
例如消费返回值时,先确认 finish,再取 text 展示;若 tool_calls 非空,则由上层明确决定是否进入受授权的工具流程。本方法只整理模型响应,不会看到工具请求就自动执行,也不会为调用方写入会话记录或文件。
得到**`p` = [调用 加载提示](加载提示(路径=`路径`))**。
2. `提示`
得到**p = 提示**。
3. *
这里**[输出本步已准备的消息](打印(内容="ext/ai/大模型: 提问需要", 提示="或", 路径=""))**。
这里**[调用 退出](系统.退出(码=1))**。
得到**`pack` = [调用 完整结果](自.完整结果(提示=`p`, 流式=False, 打印增量=False))**。
得到**`text` = [读取 text 字段](json.get(value=`pack`, key="text"))**。
得到**`usage` = [读取 usage 字段](json.get(value=`pack`, key="usage"))**。
得到**`finish` = [读取 finish 字段](json.get(value=`pack`, key="finish"))**。
得到**`tc` = [读取 tool_calls 字段](json.get(value=`pack`, key="tool_calls"))**。
1. not `tc`
**tc = > json.parse text=[]**
没有工具调用时,使用**tc = [创建空工具调用列表](table.empty_list())**,避免将缺失值误作一条调用。
2. *
**_ = 1**
表单元格会遮蔽 `自` / 列名,先取出字段再组结果表。
**mdl = [model](access(自, "model"))**
**b = [backend](access(自, "backend"))**
**nm = [name](access(自, "name"))**
**tt = [total_tokens](access(usage, "total_tokens"))**
得到**`mdl` = [读取 model 字段](access(`自`, "model"))**。
得到**`b` = [读取 backend 字段](access(`自`, "backend"))**。
得到**`nm` = [读取 name 字段](access(`自`, "name"))**。
得到**`tt` = [读取 total_tokens 字段](access(`usage`, "total_tokens"))**。
`result` =
@@ -302,45 +456,86 @@ native-plugin raw frames (`type=data` + OpenAI chunk JSON).
|------|-------|--------|---------|-------|------|-----------|--------|------------|
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | 1 | `tt` | `tc` |
*result*
完成后返回*result*。
## 流式
+ `提示`=None
+ `路径`=None
+ `打印增量`=False
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 提示 | any | None | 提供给模型的提示内容 |
| 路径 | any | None | 授权根目录内的文件路径 |
| 打印增量 | any | False | 是否输出流式增量文本 |
| p | any | 必填 | Prompt value passed to the selected model |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 将当前输入交给 运行,保留同源能力的返回值和失败语义。 |
这里使用`提示`=None、`路径`=None、`打印增量`=False、`p`。
1. `路径`
**p = > 加载提示 路径=`路径`**
得到**`p` = [调用 加载提示](加载提示(路径=`路径`))**。
2. `提示`
**p = 提示**
得到**p = 提示**。
3. *
> 打印 内容=ext/ai/大模型: 流式需要 提示= 或 路径=
> 系统.退出 码=1
这里**[输出本步已准备的消息](打印(内容="ext/ai/大模型: 流式需要", 提示="或", 路径=""))**。
这里**[调用 退出](系统.退出(码=1))**。
*> 自.运行 提示=`p` 流式=True 打印增量=`打印增量`*
完成后返回*[调用 运行](自.运行(提示=`p`, 流式=True, 打印增量=`打印增量`))*。
## 完整结果
+ `提示`
+ `流式`=False
+ `打印增量`=False
*> openai.chat_completions base_url=[base_url](access(自, "base_url")) api_key=[api_key](access(自, "api_key")) model=[model](access(自, "model")) prompt=`提示` stream=`流式` echo=`打印增量` suffix=[suffix](access(自, "suffix")) bearer=[bearer](access(自, "bearer"))*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 提示 | any | 必填 | 提供给模型的提示内容 |
| 流式 | any | False | 是否使用流式调用 |
| 打印增量 | any | False | 是否输出流式增量文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 使用此大模型资源请求完整响应,保留文本、用量和失败信息。 |
这里使用`提示`、`流式`=False、`打印增量`=False。
使用此大模型资源请求完整响应,保留文本、用量和失败信息。
完成后返回*[调用 chat completions](openai.chat_completions(base_url=[base_url](access(`自`, "base_url")), api_key=[api_key](access(`自`, "api_key")), model=[model](access(`自`, "model")), prompt=`提示`, stream=`流式`, echo=`打印增量`, suffix=[suffix](access(`自`, "suffix")), bearer=[bearer](access(`自`, "bearer"))))*。
## 运行
+ `提示`
+ `流式`=False
+ `打印增量`=False
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 提示 | any | 必填 | 提供给模型的提示内容 |
| 流式 | any | False | 是否使用流式调用 |
| 打印增量 | any | False | 是否输出流式增量文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 将当前输入交给 access,保留同源能力的返回值和失败语义。 |
这里使用`提示`、`流式`=False、`打印增量`=False。
1. `流式`
**pack = > 自.完整结果 提示=`提示` 流式=True 打印增量=`打印增量`**
*[events](access(pack, "events"))*
得到**`pack` = [调用 完整结果](自.完整结果(提示=`提示`, 流式=True, 打印增量=`打印增量`))**。
完成后返回*[events](access(pack, "events"))*。
2. *
**pack = > 自.完整结果 提示=`提示` 流式=False 打印增量=`打印增量`**
*[text](access(pack, "text"))*
得到**`pack` = [调用 完整结果](自.完整结果(提示=`提示`, 流式=False, 打印增量=`打印增量`))**。
完成后返回*[text](access(pack, "text"))*。
## 聊天
+ `提示`
+ `流式`=False
+ `打印增量`=False
*> 自.运行 提示=`提示` 流式=`流式` 打印增量=`打印增量`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 提示 | any | 必填 | 提供给模型的提示内容 |
| 流式 | any | False | 是否使用流式调用 |
| 打印增量 | any | False | 是否输出流式增量文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 使用此资源执行带历史消息的聊天请求,并保留公开实现的返回形态。 |
这里使用`提示`、`流式`=False、`打印增量`=False。
使用此资源执行带历史消息的聊天请求,并保留公开实现的返回形态。
完成后返回*[调用 运行](自.运行(提示=`提示`, 流式=`流式`, 打印增量=`打印增量`))*。
+360 -210
View File
@@ -14,82 +14,127 @@ description: 文档驱动智能体 v2 — 单步 / 多步 / 运行;技能编
插件: lib/插件.mq.md
---
本文件保留中文智能体的模型运行接口与工具调用流程。[中文入口](索引.mq.md)说明模型、编排与试跑的职责边界。内部函数的存在不代表它已进入模型白名单;工具请求必须由作者明确授权。开发时用离线模型替身核对历史、调用点、结果与写回,再测试真实传输。需要隔离执行时使用实际试跑入口,不能仅向结果附加配置记录。
## 构建单步上下文
+ `智能体`
+ `任务`
+ `源码深度`=default
+ `技能深度`=default
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 智能体 | any | 必填 | 本库创建的智能体配置或接收者 |
| 任务 | any | 必填 | 本次执行的任务文本或结构化记录 |
| 源码深度 | any | "default" | 源码上下文读取深度,默认遵循预算 |
| 技能深度 | any | "default" | 技能上下文读取深度,默认遵循预算 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 组装可读提示:站立提示、任务、*调用位置*、工具、*预算*源码 + Skill,以及人可见的行动约定。 编排 `.mq.md` 即真相源(代码即文档)。默认预算防爆窗;可先 `读取:source&#124;skill` 加深再答或 `调用:`。 实现委托 `agent.build_step_context`(与英文版同源)。 |
这里使用`智能体`、`任务`、`源码深度`="default"、`技能深度`="default"。
组装可读提示:站立提示、任务、*调用位置*、工具、*预算*源码 + Skill,以及人可见的行动约定。
编排 `.mq.md` 即真相源(代码即文档)。默认预算防爆窗;可先 `读取:source|skill` 加深再答或 `调用:`。
实现委托 `agent.build_step_context`(与英文版同源)。
*> agent.build_step_context agent=`智能体` task=`任务` source_depth=`源码深度` skill_depth=`技能深度`*
完成后返回*[调用 build step context](agent.build_step_context(agent=`智能体`, task=`任务`, source_depth=`源码深度`, skill_depth=`技能深度`))*。
---
## 提取工具名
+ `回复`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 回复 | any | 必填 | 待解析的模型回复,不直接作为执行授权 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 解析人可读调用行:`CALL:<名>` 或 `调用:<名>` / `调用:<名>`。 |
这里使用`回复`。
解析人可读调用行:`CALL:<名>` 或 `调用:<名>` / `调用:<名>`。
**esc = > json.parse text={"nl":"\n"}**
**nl = > json.get value=`esc` key="nl"**
**text = > trim value=`回复`**
**lines = > split value=`text` sep=`nl`**
**found = 空**
这里按行识别工具协议,先去掉行两端空白,再按半角冒号分隔。CALL 或“调用”作为前缀时,后面的片段成为候选工具名;没有匹配则返回空值。当前实现不把任意自然语言中的函数名当作请求,也不在这里执行函数。候选值仍要经过运行工具的白名单判断。
注意实际分隔符是半角冒号,全角冒号的示意不能保证被本函数识别。同一回复包含多个有效协议行时,后面的匹配会覆盖前面的候选;工具名中的额外冒号也不作为完整名称保留。生成端应只输出一条明确的 CALL:name,避免依赖这种兼容解析。
保留所需的文本分隔符,先**esc = [Keep the exact separator](table.put(in=None, at="nl", value="\n"))**。
得到**`nl` = [读取 nl 字段](json.get(value=`esc`, key="nl"))**。
得到**`text` = [调用 trim](trim(value=`回复`))**。
得到**`lines` = [调用 split](split(value=`text`, sep=`nl`))**。
得到**found = 空**。
- [line](遍历 `lines` 为 `line`)
**t = > trim value=`line`**
**parts = > split value=`t` sep=:**
**n = > len value=`parts`**
得到**`t` = [调用 trim](trim(value=`line`))**。
得到**`parts` = [调用 split](split(value=`t`, sep=":"))**。
得到**`n` = [调用 len](len(value=`parts`))**。
1. `n` > 1
**head = > at value=`parts` index=0**
**head = > trim value=`head`**
**rest = > at value=`parts` index=1**
**rest = > trim value=`rest`**
得到**`head` = [调用 at](at(value=`parts`, index=0))**。
得到**`head` = [调用 trim](trim(value=`head`))**。
得到**`rest` = [调用 at](at(value=`parts`, index=1))**。
得到**`rest` = [调用 trim](trim(value=`rest`))**。
1. `head` == CALL
**found = rest**
得到**found = rest**。
2. `head` == 调用
**found = rest**
得到**found = rest**。
3. *
**_ = 1**
2. *
**_ = 1**
*found*
完成后返回*found*。
---
## 运行工具
+ `工具`
+ `名`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 工具 | any | 必填 | 明确允许的工具白名单或工具记录 |
| 名 | any | 必填 | 本操作注册或查找的名称 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 白名单校验后,经 `lib/子任务`(`启动 函数=` → `等待`)调用 runbook 中的 `##`。 |
这里使用`工具`、`名`。
白名单校验后,经 `lib/子任务`(`启动 函数=` → `等待`)调用 runbook 中的 `##`。
**allowed = > agent_tool_allowed tools=`工具` name=`名`**
得到**`allowed` = [调用 tool allowed](agent_tool_allowed(tools=`工具`, name=`名`))**。
1. `allowed`
**id = > 子任务.启动 函数=`名`**
*> 子任务.等待 id=`id`*
得到**`id` = [调用 启动](子任务.启动(函数=`名`))**。
完成后返回*[调用 等待](子任务.等待(id=`id`))*。
2. *
**msg = "Tool not allowed:"**
*msg + `名`*
得到**msg = "Tool not allowed:"**。
完成后返回*msg + `名`*。
# 智能体
+ `大模型`
+ `工具`
+ `站立提示`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 大模型 | any | 必填 | 按提供方配置创建的模型资源 |
| 工具 | any | 必填 | 明确允许的工具白名单或工具记录 |
| 站立提示 | any | 必填 | 作者提供的常驻任务说明 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 加载 ABI v2 agent 插件(会话袋 + 上下文查询)。 |
这里使用`大模型`、`工具`、`站立提示`。
加载 ABI v2 agent 插件(会话袋 + 上下文查询)。
**p = > 插件.原生路径 名="agent"**
创建记录同时注册历史会话;传入的模型应提供运行方法,工具来自作者明确给出的清单。构造成功表示资源就绪,不表示已执行任务。
得到**`p` = [定位已安装的原生插件](插件.原生路径(名="agent"))**。
1. `p`
> 插件.加载 路径=`p`
这里**[调用 加载](插件.加载(路径=`p`))**。
2. *
> 打印 内容=ext/ai/智能体: 未找到原生 agent 插件(请先 cargo build -p marqdo_plugin_agent 或 marqdo ext add agent)
> 系统.退出 码=1
这里**[输出本步已准备的消息](打印(内容="ext/ai/智能体: 未找到原生 agent 插件(请先 cargo build -p marqdo_plugin_agent 或 marqdo ext add agent)"))**。
这里**[调用 退出](系统.退出(码=1))**。
得到**`id` = [调用 alloc](agent_alloc())**。
**id = > agent_alloc**
`h` =
| _type | id | model | tools |
@@ -97,49 +142,81 @@ description: 文档驱动智能体 v2 — 单步 / 多步 / 运行;技能编
| 智能体 | `id` | `大模型` | `工具` |
1. `站立提示`
**h = table.put in=`h` at="standing" value=`站立提示`**
得到**`h` = [在新记录中设置 standing 字段](table.put(in=`h`, at="standing", value=`站立提示`))**。
2. *
**_ = 1**
*h*
完成后返回*h*。
## 清空历史
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 清空本智能体 id 的插件会话袋。 |
清空本智能体 id 的插件会话袋。
**id = > json.get value=`自` key="id"**
> agent_history_clear id=`id`
****
得到**`id` = [读取 id 字段](json.get(value=`自`, key="id"))**。
这里**[调用 history clear](agent_history_clear(id=`id`))**。
完成后返回*None*。
## 试跑
+ `路径`=None
+ `源码`=None
+ `根目录`=None
+ `写入路径`=None
+ `文本`=None
+ `提交`=真
+ `配置`=default
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 路径 | any | None | 授权根目录内的文件路径 |
| 源码 | any | None | 本次检查或试跑的源码文本 |
| 根目录 | any | None | 明确选择的工程或试运行根目录 |
| 写入路径 | any | None | 明确的产物路径,或不写出时使用 None |
| 文本 | any | None | 本操作接收的文本 |
| 提交 | any | True | 是否在验证完成后晋升试运行变更 |
| 配置 | any | "default" | 试运行使用的能力配置 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | O1 可选沙盒试跑。转发 `agent.trial`(表风格返回;宿主树在成功 `提交` 前不变)。 |
这里使用`路径`=None、`源码`=None、`根目录`=None、`写入路径`=None、`文本`=None、`提交`=True、`配置`="default"。
O1 可选沙盒试跑。转发 `agent.trial`(表风格返回;宿主树在成功 `提交` 前不变)。
*> agent.trial path=`路径` source=`源码` root=`根目录` write_path=`写入路径` text=`文本` commit=`提交` profile=`配置`*
完成后返回*[调用 trial](agent.trial(path=`路径`, source=`源码`, root=`根目录`, write_path=`写入路径`, text=`文本`, commit=`提交`, profile=`配置`))*。
## 单步
+ `任务`
+ `写回`=真
+ `流式`=假
+ `打印增量`=假
+ `沙盒`=假
+ `沙盒配置`=default
原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 *map*(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。默认(`写回=真`)将结果写入调用行下的命名槽 `ok` / `error`;传 `写回=假` 可关闭。
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 任务 | any | 必填 | 本次执行的任务文本或结构化记录 |
| 写回 | any | True | 是否向任务文档写回观察结果 |
| 流式 | any | False | 是否使用流式调用 |
| 打印增量 | any | False | 是否输出流式增量文本 |
| 沙盒 | any | False | 是否采用 CoW 试运行路径 |
| 沙盒配置 | any | "default" | CoW 试运行能力配置 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 map 记录(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。默认(`写回=真`)将结果写入调用行下的命名槽 `ok` / `error`;传 `写回=假` 可关闭。 流式=真 时走 SSE;打印增量=真 边读边打印。返回 map 仍是最终 result 文本。`沙盒=真` 时结果附带沙盒配置行。 |
这里使用`任务`、`写回`=True、`流式`=False、`打印增量`=False、`沙盒`=False、`沙盒配置`="default"。
原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 map 记录(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。默认(`写回=真`)将结果写入调用行下的命名槽 `ok` / `error`;传 `写回=假` 可关闭。
流式=真 时走 SSE;打印增量=真 边读边打印。返回 map 仍是最终 result 文本。`沙盒=真` 时结果附带沙盒配置行。
**ctx = > 构建单步上下文 智能体=`自` 任务=`任务`**
**id = > json.get value=`自` key="id"**
**model = > json.get value=`自` key="model"**
**tools = > json.get value=`自` key="tools"**
默认会写回调用文档;若只想观察结果,请显式传入写回=False,避免演示修改任务源码。这一轮先把用户任务写入当前会话历史,再用调用点上下文请求模型。流式分支先收集事件得到最终文本,普通分支直接取得回复。随后只把明确的工具协议视作调用候选;其余文字作为回答保留。中文兼容面使用模型的运行方法,并不要求调用方假装它具有英文资源的全部接口。
有工具候选时,运行工具负责核对作者白名单并等待子任务。拒绝结果进入 error 字段;成功结果被序列化后提供给模型,再形成面向用户的回答。tool_result 因而保存的是序列化文本,消费它时不要误当原始业务记录。没有工具候选时直接使用本次回复,避免重复请求。
这一步会把最终助手回复追加到同一历史,并按写回开关将完整记录放入调用点的 ok 或 error 槽。演示或只读任务应明确关闭写回,生产流程则要为实际文件操作准备权限。返回记录中的 status、decision、result 和工具字段分别说明流程状态、原始决定与最终答案,它们不能相互替代;任务特有的正确性仍由调用方验证。
这里的沙盒开关只给返回记录附加所选配置行,不会把上述模型或工具调用迁移到 CoW 环境。需要隔离试运行,应调用试跑入口或使用具有实际 CoW 执行边界的工程运行流程。不要依据 sandbox_profile 字段的存在宣称副作用已经隔离。写回失败、插件失败和传输失败仍沿既有运行诊断报告,函数没有通用事务回滚能力。
开发此方法时,先使用只返回固定文本的离线模型替身确认上下文、历史与结果字段,再分别验证工具允许、工具拒绝和写回开关。涉及真实模型的测试还应覆盖流式结束、错误事件和无文本结果。保持这两类验证分开,才能判断错误来自编排还是传输,避免用一次线上回答掩盖未执行的分支。
得到**`ctx` = [调用 构建单步上下文](构建单步上下文(智能体=`自`, 任务=`任务`))**。
得到**`id` = [读取 id 字段](json.get(value=`自`, key="id"))**。
得到**`model` = [读取 model 字段](json.get(value=`自`, key="model"))**。
得到**`tools` = [读取 tools 字段](json.get(value=`自`, key="tools"))**。
`user_turn` =
@@ -147,17 +224,18 @@ O1 可选沙盒试跑。转发 `agent.trial`(表风格返回;宿主树在成
|------|---------|
| user | `任务` |
> agent_history_append id=`id` item=`user_turn`
这里**[将本项追加到新列表](agent_history_append(id=`id`, item=`user_turn`))**。
1. `流式`
**evs = > model.运行 提示=`ctx` 流式=真 打印增量=`打印增量`**
**reply = > 大模型.流式结果 事件=`evs`**
得到**`evs` = [调用 运行](model.运行(提示=`ctx`, 流式=True, 打印增量=`打印增量`))**。
得到**`reply` = [调用 流式结果](大模型.流式结果(事件=`evs`))**。
2. *
**reply = > model.运行 提示=`ctx`**
得到**`reply` = [调用 运行](model.运行(提示=`ctx`))**。
得到**`reply` = [调用 trim](trim(value=`reply`))**。
得到**decision = reply**。
得到**`tool_name` = [调用 提取工具名](提取工具名(回复=`reply`))**。
**reply = > trim value=`reply`**
**decision = reply**
**tool_name = > 提取工具名 回复=`reply`**
`out` =
| status | task | decision |
@@ -165,208 +243,280 @@ O1 可选沙盒试跑。转发 `agent.trial`(表风格返回;宿主树在成
| ok | `任务` | `decision` |
1. `tool_name`
**tool_out = > 运行工具 工具=`tools` 名=`tool_name`**
**tool_s = > json.stringify value=`tool_out`**
**deny = > split value=`tool_s` sep="Tool not allowed"**
**deny_n = > len value=`deny`**
得到**`tool_out` = [调用 运行工具](运行工具(工具=`tools`, 名=`tool_name`))**。
得到**`tool_s` = [将结构化值编码为 JSON 文本](json.stringify(value=`tool_out`))**。
得到**`deny` = [调用 split](split(value=`tool_s`, sep="Tool not allowed"))**。
得到**`deny_n` = [调用 len](len(value=`deny`))**。
1. `deny_n` > 1
**out = table.put in=`out` at="status" value="error"**
**out = table.put in=`out` at="error" value=`tool_s`**
**reply = tool_s**
得到**`out` = [在新记录中设置 status 字段](table.put(in=`out`, at="status", value="error"))**。
得到**`out` = [在新记录中设置 error 字段](table.put(in=`out`, at="error", value=`tool_s`))**。
得到**reply = tool_s**。
2. *
**task_s = > json.stringify value=`任务`**
**fp = "The user asked:"**
**fp = fp + task_s**
**fp = fp + ". Tool"**
**fp = fp + tool_name**
**fp = fp + "ran via subtask and returned:"**
**fp = fp + tool_s**
**fp = fp + ". Reply to the user briefly."**
得到**`task_s` = [将结构化值编码为 JSON 文本](json.stringify(value=`任务`))**。
得到**fp = "The user asked:"**。
得到**fp = fp + task_s**。
得到**fp = fp + ". Tool"**。
得到**fp = fp + tool_name**。
得到**fp = fp + "ran via subtask and returned:"**。
得到**fp = fp + tool_s**。
得到**fp = fp + ". Reply to the user briefly."**。
1. `流式`
**evs2 = > model.运行 提示=`fp` 流式=真 打印增量=`打印增量`**
**reply = > 大模型.流式结果 事件=`evs2`**
得到**`evs2` = [调用 运行](model.运行(提示=`fp`, 流式=True, 打印增量=`打印增量`))**。
得到**`reply` = [调用 流式结果](大模型.流式结果(事件=`evs2`))**。
2. *
**reply = > model.运行 提示=`fp`**
**out = table.put in=`out` at="tool" value=`tool_name`**
**out = table.put in=`out` at="tool_result" value=`tool_s`**
**out = table.put in=`out` at="result" value=`reply`**
得到**`reply` = [调用 运行](model.运行(提示=`fp`))**。
得到**`out` = [在新记录中设置 tool 字段](table.put(in=`out`, at="tool", value=`tool_name`))**。
得到**`out` = [在新记录中设置 tool_result 字段](table.put(in=`out`, at="tool_result", value=`tool_s`))**。
得到**`out` = [在新记录中设置 result 字段](table.put(in=`out`, at="result", value=`reply`))**。
2. *
**out = table.put in=`out` at="result" value=`reply`**
得到**`out` = [在新记录中设置 result 字段](table.put(in=`out`, at="result", value=`reply`))**。
`as_turn` =
| role | content |
|------|---------|
| assistant | `reply` |
> agent_history_append id=`id` item=`as_turn`
这里**[将本项追加到新列表](agent_history_append(id=`id`, item=`as_turn`))**。
1. `沙盒`
**配置行 = sandbox.profile name=`沙盒配置`**
**out = table.put in=`out` at="sandbox_profile" value=`配置行`**
得到**`配置行` = [调用 profile](sandbox.profile(name=`沙盒配置`))**。
得到**`out` = [在新记录中设置 sandbox_profile 字段](table.put(in=`out`, at="sandbox_profile", value=`配置行`))**。
2. *
**_ = 1**
1. `写回`
**body = > json.stringify value=`out`**
**st = > json.get value=`out` key="status"**
得到**`body` = [将结构化值编码为 JSON 文本](json.stringify(value=`out`))**。
得到**`st` = [读取 status 字段](json.get(value=`out`, key="status"))**。
1. `st` == "ok"
> 自写回.写回 值=`body` 键="ok"
这里**[调用 写回](自写回.写回(值=`body`, 键="ok"))**。
2. *
> 自写回.写回 值=`body` 键="error"
这里**[调用 写回](自写回.写回(值=`body`, 键="error"))**。
2. *
**_ = 1**
*out*
完成后返回*out*。
## 工程预检
+ `任务`
+ `根目录`="."
+ `知识目录`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 任务 | any | 必填 | 本次执行的任务文本或结构化记录 |
| 根目录 | any | "." | 明确选择的工程或试运行根目录 |
| 知识目录 | any | None | 检索和写回所用的知识目录 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | Engineering First Information 门闩。转发 `agent.preflight`。 |
这里使用`任务`、`根目录`="."、`知识目录`=None。
Engineering First Information 门闩。转发 `agent.preflight`。
*> agent.preflight task=`任务` root=`根目录` marqdo_dir=`知识目录`*
完成后返回*[调用 preflight](agent.preflight(task=`任务`, root=`根目录`, marqdo_dir=`知识目录`))*。
## 多步
+ `目标`
+ `工作簿目录`=None
+ `工作簿`=None
+ `最大轮次`=4
+ `确认分解`=False
+ `写回`=True
+ `骨架`=single
+ `复用`=True
+ `优化`=False
+ `强制`=False
+ `软命中`=False
+ `近义命中`=True
+ `近义阈值`=0.78
+ `晋升`=True
+ `知识库目录`=.marqdo/agent-kb
+ `改进周期`=3
+ `探索次数`=3
+ `流式`=False
+ `打印增量`=False
+ `轨迹`=False
+ `工程预检`=False
+ `工程知识目录`=.marqdo
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 目标 | any | 必填 | 当前人类任务目标 |
| 工作簿目录 | any | None | 本次规划拥有的工作簿目录 |
| 工作簿 | any | None | 工作簿路径或工作簿引用 |
| 最大轮次 | any | 4 | 允许的工作簿规划轮数上限 |
| 确认分解 | any | False | 是否要求确认任务分解 |
| 写回 | any | True | 是否向任务文档写回观察结果 |
| 骨架 | any | "single" | 用于生成工作簿的源码模板 |
| 复用 | any | True | 是否先检索已有能力 |
| 优化 | any | False | 是否采用已说明的改进路径 |
| 强制 | any | False | 本操作支持的显式覆盖选项,不绕过宿主授权 |
| 软命中 | any | False | 是否考虑有界近似匹配 |
| 近义命中 | any | True | 是否考虑近义能力候选 |
| 近义阈值 | any | 0.78 | 近义匹配所需的最低得分 |
| 晋升 | any | True | 是否允许将已验证证据晋升 |
| 知识库目录 | any | ".marqdo/agent-kb" | 知识库的明确目录 |
| 改进周期 | any | 3 | 触发一次改进前所需的观察次数 |
| 探索次数 | any | 3 | 有界探索尝试次数上限 |
| 流式 | any | False | 是否使用流式调用 |
| 打印增量 | any | False | 是否输出流式增量文本 |
| 轨迹 | any | False | 是否保留已说明的执行轨迹 |
| 工程预检 | any | False | 是否进行工程能力复用预检 |
| 工程知识目录 | any | ".marqdo" | 工程检索使用的知识目录 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 多步工作簿默认写入 OKF `知识库目录/resources/<slug>.mq.md`;仅当传入 `工作簿目录` 时才用临时 runs。转发至英文 `agent.plan`。`流式` / `打印增量` / `轨迹` 对应 `stream` / `echo` / `trace`;`软命中` → `soft_match`;`近义命中` / `近义阈值` → `near_match` / `near_threshold`。`工程预检` → `eng_preflight`。 |
这里使用`目标`、`工作簿目录`=None、`工作簿`=None、`最大轮次`=4、`确认分解`=False、`写回`=True、`骨架`="single"、`复用`=True、`优化`=False、`强制`=False、`软命中`=False、`近义命中`=True、`近义阈值`=0.78、`晋升`=True、`知识库目录`=".marqdo/agent-kb"、`改进周期`=3、`探索次数`=3、`流式`=False、`打印增量`=False、`轨迹`=False、`工程预检`=False、`工程知识目录`=".marqdo"。
多步工作簿默认写入 OKF `知识库目录/resources/<slug>.mq.md`;仅当传入 `工作簿目录` 时才用临时 runs。转发至英文 `agent.plan`。`流式` / `打印增量` / `轨迹` 对应 `stream` / `echo` / `trace`;`软命中` → `soft_match`;`近义命中` / `近义阈值` → `near_match` / `near_threshold`。`工程预检` → `eng_preflight`。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.plan goal=`目标` workbook_dir=`工作簿目录` workbook=`工作簿` max_rounds=`最大轮次` confirm=`确认分解` writeback=`写回` skeleton=`骨架` reuse=`复用` optimize=`优化` force=`强制` soft_match=`软命中` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` kb_dir=`知识库目录` improve_every=`改进周期` explore_n=`探索次数` stream=`流式` echo=`打印增量` trace=`轨迹` eng_preflight=`工程预检` marqdo_dir=`工程知识目录`*
得到**`model` = [读取 model 字段](json.get(value=`self`, key="model"))**。
得到**`tools` = [读取 tools 字段](json.get(value=`self`, key="tools"))**。
得到**`standing` = [读取 standing 字段](json.get(value=`self`, key="standing"))**。
得到**`en` = [调用 agent](agent.agent(model=`model`, tools=`tools`, standing=`standing`))**。
完成后返回*[调用 plan](en.plan(goal=`目标`, workbook_dir=`工作簿目录`, workbook=`工作簿`, max_rounds=`最大轮次`, confirm=`确认分解`, writeback=`写回`, skeleton=`骨架`, reuse=`复用`, optimize=`优化`, force=`强制`, soft_match=`软命中`, near_match=`近义命中`, near_threshold=`近义阈值`, promote=`晋升`, kb_dir=`知识库目录`, improve_every=`改进周期`, explore_n=`探索次数`, stream=`流式`, echo=`打印增量`, trace=`轨迹`, eng_preflight=`工程预检`, marqdo_dir=`工程知识目录`))*。
## 解析
+ `任务`
+ `知识库目录`=.marqdo/agent-kb
+ `近义命中`=True
+ `近义阈值`=0.78
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 任务 | any | 必填 | 本次执行的任务文本或结构化记录 |
| 知识库目录 | any | ".marqdo/agent-kb" | 知识库的明确目录 |
| 近义命中 | any | True | 是否考虑近义能力候选 |
| 近义阈值 | any | 0.78 | 近义匹配所需的最低得分 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 技能解析(v2):exact → alias → canonical → near。 |
这里使用`任务`、`知识库目录`=".marqdo/agent-kb"、`近义命中`=True、`近义阈值`=0.78。
技能解析(v2):exact → alias → canonical → near。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.resolve task=`任务` kb_dir=`知识库目录` near_match=`近义命中` near_threshold=`近义阈值`*
得到**`model` = [读取 model 字段](json.get(value=`self`, key="model"))**。
得到**`tools` = [读取 tools 字段](json.get(value=`self`, key="tools"))**。
得到**`standing` = [读取 standing 字段](json.get(value=`self`, key="standing"))**。
得到**`en` = [调用 agent](agent.agent(model=`model`, tools=`tools`, standing=`standing`))**。
完成后返回*[调用 resolve](en.resolve(task=`任务`, kb_dir=`知识库目录`, near_match=`近义命中`, near_threshold=`近义阈值`))*。
## 记录情景
+ `任务`
+ `状态`=ok
+ `结果`=None
+ `模式`=explore
+ `技能`=none
+ `观察`=None
+ `工作簿`=None
+ `缓存`=None
+ `匹配`=None
+ `大模型次数`=0
+ `工具次数`=0
+ `错误`=None
+ `记忆目录`=.marqdo/agent-memory
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 任务 | any | 必填 | 本次执行的任务文本或结构化记录 |
| 状态 | any | "ok" | 当前结构化执行状态 |
| 结果 | any | None | 前一步返回的结构化结果 |
| 模式 | any | "explore" | 本函数说明支持的操作模式 |
| 技能 | any | "none" | 准备检查或调用的技能引用 |
| 观察 | any | None | 保留给后续步骤的工具或工作簿观察 |
| 工作簿 | any | None | 工作簿路径或工作簿引用 |
| 缓存 | any | None | 是否使用已说明的结果缓存 |
| 匹配 | any | None | 已解析的能力匹配结果 |
| 大模型次数 | any | 0 | 实际观测到的模型调用次数 |
| 工具次数 | any | 0 | 实际观测到的工具调用次数 |
| 错误 | any | None | 可恢复失败记录 |
| 记忆目录 | any | ".marqdo/agent-memory" | 情景或策略记忆所在目录 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 将一次执行沉淀为 `.mq.md` 情景记忆。 |
这里使用`任务`、`状态`="ok"、`结果`=None、`模式`="explore"、`技能`="none"、`观察`=None、`工作簿`=None、`缓存`=None、`匹配`=None、`大模型次数`=0、`工具次数`=0、`错误`=None、`记忆目录`=".marqdo/agent-memory"。
将一次执行沉淀为 `.mq.md` 情景记忆。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.record_episode task=`任务` status=`状态` result=`结果` mode=`模式` skill=`技能` observation=`观察` workbook=`工作簿` cache=`缓存` match=`匹配` llm_calls=`大模型次数` tool_calls=`工具次数` error=`错误` memory_dir=`记忆目录`*
得到**`model` = [读取 model 字段](json.get(value=`self`, key="model"))**。
得到**`tools` = [读取 tools 字段](json.get(value=`self`, key="tools"))**。
得到**`standing` = [读取 standing 字段](json.get(value=`self`, key="standing"))**。
得到**`en` = [调用 agent](agent.agent(model=`model`, tools=`tools`, standing=`standing`))**。
完成后返回*[调用 record episode](en.record_episode(task=`任务`, status=`状态`, result=`结果`, mode=`模式`, skill=`技能`, observation=`观察`, workbook=`工作簿`, cache=`缓存`, match=`匹配`, llm_calls=`大模型次数`, tool_calls=`工具次数`, error=`错误`, memory_dir=`记忆目录`))*。
## 尝试学习
+ `任务`
+ `知识库目录`=.marqdo/agent-kb
+ `记忆目录`=.marqdo/agent-memory
+ `改进周期`=3
+ `晋升`=True
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 任务 | any | 必填 | 本次执行的任务文本或结构化记录 |
| 知识库目录 | any | ".marqdo/agent-kb" | 知识库的明确目录 |
| 记忆目录 | any | ".marqdo/agent-memory" | 情景或策略记忆所在目录 |
| 改进周期 | any | 3 | 触发一次改进前所需的观察次数 |
| 晋升 | any | True | 是否允许将已验证证据晋升 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 情景足够时:归纳 → 合成候选 → 编译 → 可选晋升为 `llm_free` 技能。 |
这里使用`任务`、`知识库目录`=".marqdo/agent-kb"、`记忆目录`=".marqdo/agent-memory"、`改进周期`=3、`晋升`=True。
情景足够时:归纳 → 合成候选 → 编译 → 可选晋升为 `llm_free` 技能。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.maybe_learn task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` improve_every=`改进周期` promote=`晋升`*
得到**`model` = [读取 model 字段](json.get(value=`self`, key="model"))**。
得到**`tools` = [读取 tools 字段](json.get(value=`self`, key="tools"))**。
得到**`standing` = [读取 standing 字段](json.get(value=`self`, key="standing"))**。
得到**`en` = [调用 agent](agent.agent(model=`model`, tools=`tools`, standing=`standing`))**。
完成后返回*[调用 maybe learn](en.maybe_learn(task=`任务`, kb_dir=`知识库目录`, memory_dir=`记忆目录`, improve_every=`改进周期`, promote=`晋升`))*。
## 运行
+ `任务`
+ `知识库目录`=.marqdo/agent-kb
+ `记忆目录`=.marqdo/agent-memory
+ `学习`=True
+ `校验`=True
+ `写回`=True
+ `复用`=True
+ `近义命中`=True
+ `近义阈值`=0.78
+ `晋升`=True
+ `改进周期`=3
+ `探索次数`=3
+ `最大轮次`=4
+ `流式`=False
+ `打印增量`=False
+ `轨迹`=False
+ `强制`=False
+ `路由`=auto
+ `路由模型`=None
+ `沙盒`=False
+ `沙盒配置`=default
+ `工程预检`=True
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 任务 | any | 必填 | 本次执行的任务文本或结构化记录 |
| 知识库目录 | any | ".marqdo/agent-kb" | 知识库的明确目录 |
| 记忆目录 | any | ".marqdo/agent-memory" | 情景或策略记忆所在目录 |
| 学习 | any | True | 是否记录观察或进行学习 |
| 校验 | any | True | 是否运行已说明的校验器 |
| 写回 | any | True | 是否向任务文档写回观察结果 |
| 复用 | any | True | 是否先检索已有能力 |
| 近义命中 | any | True | 是否考虑近义能力候选 |
| 近义阈值 | any | 0.78 | 近义匹配所需的最低得分 |
| 晋升 | any | True | 是否允许将已验证证据晋升 |
| 改进周期 | any | 3 | 触发一次改进前所需的观察次数 |
| 探索次数 | any | 3 | 有界探索尝试次数上限 |
| 最大轮次 | any | 4 | 允许的工作簿规划轮数上限 |
| 流式 | any | False | 是否使用流式调用 |
| 打印增量 | any | False | 是否输出流式增量文本 |
| 轨迹 | any | False | 是否保留已说明的执行轨迹 |
| 强制 | any | False | 本操作支持的显式覆盖选项,不绕过宿主授权 |
| 路由 | any | "auto" | 路由配置或已选路由 |
| 路由模型 | any | None | 用于路由决策的模型资源 |
| 沙盒 | any | False | 是否采用 CoW 试运行路径 |
| 沙盒配置 | any | "default" | CoW 试运行能力配置 |
| 工程预检 | any | True | 是否进行工程能力复用预检 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | v2+P4 主入口:自适应路由 → 执行 → 记录情景 → 尝试学习(技能 + 策略)。`路由`=`auto`&#124;`marqdo`&#124;`small-llm`&#124;`llm`(`jev` 为 `small-llm` 兼容别名);决策器用 `路由模型`(任意 llm 句柄)。`沙盒=真` 走 CoW 试跑;`工程预检` 对应 `efi`。 |
这里使用`任务`、`知识库目录`=".marqdo/agent-kb"、`记忆目录`=".marqdo/agent-memory"、`学习`=True、`校验`=True、`写回`=True、`复用`=True、`近义命中`=True、`近义阈值`=0.78、`晋升`=True、`改进周期`=3、`探索次数`=3、`最大轮次`=4、`流式`=False、`打印增量`=False、`轨迹`=False、`强制`=False、`路由`="auto"、`路由模型`=None、`沙盒`=False、`沙盒配置`="default"、`工程预检`=True。
v2+P4 主入口:自适应路由 → 执行 → 记录情景 → 尝试学习(技能 + 策略)。`路由`=`auto`|`marqdo`|`small-llm`|`llm`(`jev` 为 `small-llm` 兼容别名);决策器用 `路由模型`(任意 llm 句柄)。`沙盒=真` 走 CoW 试跑;`工程预检` 对应 `efi`。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.run task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` learn=`学习` verify=`校验` writeback=`写回` reuse=`复用` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` improve_every=`改进周期` explore_n=`探索次数` max_rounds=`最大轮次` stream=`流式` echo=`打印增量` trace=`轨迹` force=`强制` router=`路由` router_model=`路由模型` sandbox=`沙盒` sandbox_profile=`沙盒配置` efi=`工程预检`*
得到**`model` = [读取 model 字段](json.get(value=`self`, key="model"))**。
得到**`tools` = [读取 tools 字段](json.get(value=`self`, key="tools"))**。
得到**`standing` = [读取 standing 字段](json.get(value=`self`, key="standing"))**。
得到**`en` = [调用 agent](agent.agent(model=`model`, tools=`tools`, standing=`standing`))**。
完成后返回*[调用 run](en.run(task=`任务`, kb_dir=`知识库目录`, memory_dir=`记忆目录`, learn=`学习`, verify=`校验`, writeback=`写回`, reuse=`复用`, near_match=`近义命中`, near_threshold=`近义阈值`, promote=`晋升`, improve_every=`改进周期`, explore_n=`探索次数`, max_rounds=`最大轮次`, stream=`流式`, echo=`打印增量`, trace=`轨迹`, force=`强制`, router=`路由`, router_model=`路由模型`, sandbox=`沙盒`, sandbox_profile=`沙盒配置`, efi=`工程预检`))*。
## 路由
+ `任务`
+ `后端`=auto
+ `知识库目录`=.marqdo/agent-kb
+ `记忆目录`=.marqdo/agent-memory
+ `阈值`=0.78
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 任务 | any | 必填 | 本次执行的任务文本或结构化记录 |
| 后端 | any | "auto" | 明确选择的执行或模型后端 |
| 知识库目录 | any | ".marqdo/agent-kb" | 知识库的明确目录 |
| 记忆目录 | any | ".marqdo/agent-memory" | 情景或策略记忆所在目录 |
| 阈值 | any | 0.78 | 当前操作要求满足的策略阈值 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 自适应路由(阶段 4):`marqdo` / `small-llm` / `llm` / `auto`(`jev`→别名)。 |
这里使用`任务`、`后端`="auto"、`知识库目录`=".marqdo/agent-kb"、`记忆目录`=".marqdo/agent-memory"、`阈值`=0.78。
自适应路由(阶段 4):`marqdo` / `small-llm` / `llm` / `auto`(`jev`→别名)。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.route task=`任务` backend=`后端` kb_dir=`知识库目录` memory_dir=`记忆目录` threshold=`阈值`*
得到**`model` = [读取 model 字段](json.get(value=`self`, key="model"))**。
得到**`tools` = [读取 tools 字段](json.get(value=`self`, key="tools"))**。
得到**`standing` = [读取 standing 字段](json.get(value=`self`, key="standing"))**。
得到**`en` = [调用 agent](agent.agent(model=`model`, tools=`tools`, standing=`standing`))**。
完成后返回*[调用 route](en.route(task=`任务`, backend=`后端`, kb_dir=`知识库目录`, memory_dir=`记忆目录`, threshold=`阈值`))*。
## 编译策略
+ `记忆目录`=.marqdo/agent-memory
+ `最少证据`=3
+ `强制`=False
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 记忆目录 | any | ".marqdo/agent-memory" | 情景或策略记忆所在目录 |
| 最少证据 | any | 3 | 允许晋升前所需的证据数量 |
| 强制 | any | False | 本操作支持的显式覆盖选项,不绕过宿主授权 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 策略编译:稳定的 task→skill 映射 → `policies/router.mq.md`。 |
这里使用`记忆目录`=".marqdo/agent-memory"、`最少证据`=3、`强制`=False。
策略编译:稳定的 task→skill 映射 → `policies/router.mq.md`。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.compile_policy memory_dir=`记忆目录` min_evidence=`最少证据` force=`强制`*
得到**`model` = [读取 model 字段](json.get(value=`self`, key="model"))**。
得到**`tools` = [读取 tools 字段](json.get(value=`self`, key="tools"))**。
得到**`standing` = [读取 standing 字段](json.get(value=`self`, key="standing"))**。
得到**`en` = [调用 agent](agent.agent(model=`model`, tools=`tools`, standing=`standing`))**。
完成后返回*[调用 compile policy](en.compile_policy(memory_dir=`记忆目录`, min_evidence=`最少证据`, force=`强制`))*。
+127 -28
View File
@@ -7,59 +7,158 @@ import:
sandbox: ext/ai/sandbox.mq.md
---
## 打开
+ `根`=None
本文件提供中文试跑门面,对应[试跑实现](sandbox.mq.md)。先读[中文入口](索引.mq.md)了解模型调用与 CoW 试跑的区别。试跑产生的文件变更和诊断供调用者检查,提升变更必须走已有显式流程;试跑返回不等于宿主工作区已经更新。保持失败、取消和提升的结果可区分,避免复制一份隔离实现。
*> sandbox.open root=`根`*
## 打开
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 根 | any | None | 当前会话或工程明确授权的根目录 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 按根目录与能力配置打开同源 CoW 试运行会话,不立即修改真实文件树。 |
这里使用`根`=None。
按根目录与能力配置打开同源 CoW 试运行会话,不立即修改真实文件树。
完成后返回*[调用 open](sandbox.open(root=`根`))*。
## 写入
+ `id`
+ `路径`
+ `文本`
*> sandbox.write id=`id` path=`路径` text=`文本`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | 必填 | Identifier produced or selected by the corresponding resource operation |
| 路径 | any | 必填 | 授权根目录内的文件路径 |
| 文本 | any | 必填 | 本操作接收的文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 把文本写入试运行会话的覆盖层,提交前不改真实文件。 |
这里使用`id`、`路径`、`文本`。
把文本写入试运行会话的覆盖层,提交前不改真实文件。
完成后返回*[调用 write](sandbox.write(id=`id`, path=`路径`, text=`文本`))*。
## 读取
+ `id`
+ `路径`
*> sandbox.read id=`id` path=`路径`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | 必填 | Identifier produced or selected by the corresponding resource operation |
| 路径 | any | 必填 | 授权根目录内的文件路径 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 透过试运行覆盖层读取文本,遵循白化删除和下层读取语义。 |
这里使用`id`、`路径`。
透过试运行覆盖层读取文本,遵循白化删除和下层读取语义。
完成后返回*[调用 read](sandbox.read(id=`id`, path=`路径`))*。
## 删除
+ `id`
+ `路径`
*> sandbox.remove id=`id` path=`路径`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | 必填 | Identifier produced or selected by the corresponding resource operation |
| 路径 | any | 必填 | 授权根目录内的文件路径 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 在试运行覆盖层标记删除,不直接删除宿主文件。 |
这里使用`id`、`路径`。
在试运行覆盖层标记删除,不直接删除宿主文件。
完成后返回*[调用 remove](sandbox.remove(id=`id`, path=`路径`))*。
## 差异
+ `id`
*> sandbox.diff id=`id`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | 必填 | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 读取会话中的真实变更清单,供决定提交或丢弃。 |
这里使用`id`。
读取会话中的真实变更清单,供决定提交或丢弃。
完成后返回*[调用 diff](sandbox.diff(id=`id`))*。
## 提交
+ `id`
*> sandbox.commit id=`id`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | 必填 | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 把明确选择的试运行变更提交到宿主文件树,此操作会产生真实写入。 |
这里使用`id`。
把明确选择的试运行变更提交到宿主文件树,此操作会产生真实写入。
完成后返回*[调用 commit](sandbox.commit(id=`id`))*。
## 丢弃
+ `id`
*> sandbox.discard id=`id`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | 必填 | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 丢弃会话覆盖层中的变更,保留原始宿主文件。 |
这里使用`id`。
丢弃会话覆盖层中的变更,保留原始宿主文件。
完成后返回*[调用 discard](sandbox.discard(id=`id`))*。
## 运行
+ `id`
+ `源码`=None
+ `路径`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | 必填 | Identifier produced or selected by the corresponding resource operation |
| 源码 | any | None | 本次检查或试跑的源码文本 |
| 路径 | any | None | 授权根目录内的文件路径 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 将当前输入交给 run,保留同源能力的返回值和失败语义。 |
这里使用`id`、`源码`=None、`路径`=None。
1. `源码`
*> sandbox.run id=`id` source=`源码`*
完成后返回*[调用 run](sandbox.run(id=`id`, source=`源码`))*。
2. `路径`
*> sandbox.run id=`id` path=`路径`*
完成后返回*[调用 run](sandbox.run(id=`id`, path=`路径`))*。
3. *
> print text=沙盒.运行: 需要 源码= 或 路径=
> sys.exit code=1
这里**[输出本步已准备的消息](print(text="沙盒.运行: 需要", 源码="或", 路径=""))**。
这里**[按指定退出码结束本次运行](sys.exit(code=1))**。
## 检查
+ `id`
*> sandbox.inspect id=`id`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | 必填 | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | any | 检查当前试运行会话及能力配置,不把检查等同于提交成功。 |
这里使用`id`。
检查当前试运行会话及能力配置,不把检查等同于提交成功。
完成后返回*[调用 inspect](sandbox.inspect(id=`id`))*。
+60
View File
@@ -0,0 +1,60 @@
---
markup: occlusion
title: AI 工程入口:模型、智能体与试运行
import:
大模型: ext/ai/大模型.mq.md
---
从本入口选择任务:[大模型](大模型.mq.md)负责提示、配置、请求和流收集;
[智能体](智能体.mq.md)提供中文使用面,[同源编排实现](agent.mq.md)负责上下文、
白名单工具、路由、工作簿和继续执行;[沙盒](沙盒.mq.md)管理试运行覆盖层及晋升。
[提供方适配入口](llm/index.mq.md)解释 HTTP 适配,[路由策略](policies/step-route.mq.md)
保留可读表数据。[英文入口](index.mq.md)给出相同职责划分。
可以先运行完全离线的流收集,不需要凭据、模型服务或原生插件:
```sh
marqdo call ext/ai/索引.mq.md 离线示例 --json
```
真实请求前明确模型基址和可信凭据,智能体还需要已构建的 agent 插件与工具白名单。
生成的调用文本不是执行授权,文件写入、网络和进程仍受宿主限制。工具失败、取消、
超预算或恢复时应保留观察与效果状态,不因继续工作簿而重复不可逆操作。
新增提供方去适配目录,公共模型行为去大模型模块,规划和上下文去智能体模块,
隔离修改去沙盒模块;保持中英文默认值与行为一致。先用本地可控替身验证成功与失败,
再在明确运行配置下测试真实服务。不能用固定完成标记冒充已经调用模型或验证了工具。
## 收集事件
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 事件 | list | 必填 | 按顺序排列的语义流或公开收集器支持的提供方事件 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | text | 由公共收集器组装的最终回答文本 |
输入`事件`是已经观测的数据,不会触发新请求或执行其中的工具文本。
本工具复用公开大模型库的 delta/text 与 done.result 收集约定,
直接返回*[把已有事件组装成最终文本](大模型.收集(事件=`事件`))*,
使离线处理与真实传输复用同一份组装规则。
## 离线示例
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | text | Hello world,由下面的实际事件组装得到 |
下面是一条确定的增量事件和一条完成事件。表格把输入内容完整列出,
读者可以比较局部文本与完成结果,不需要相信一个自报通过的标志。
此流程只验证流收集,不暗示模型服务或网络已经可用。
`事件` =
| @ | type | text | result |
|---|---|---|---|
| 1 | delta | "Hello " | None |
| 2 | done | None | "Hello world" |
最后返回*[根据列出的事件得到最终文本](收集事件(事件=`事件`))*,供下一步展示或保存。
+94 -25
View File
@@ -8,55 +8,124 @@ import:
table: lib/table.mq.md
---
Cache values belong to the selected backend and process lifetime. Use memory: only for process-local demonstration; choose and configure persistent backends explicitly. [The data entry](index.mq.md) demonstrates set, get and deletion through one receiver. Retain native ok/error fields and expiry behavior when extending this leaf; a cache miss is not evidence that a remote write succeeded.
## _load
**p = > plugin.native_path name="web"**
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | No business value on completion; a missing native plugin reports the cause and exits this run. |
Resolve and load the native web plugin before resource operations; missing binaries stop this run.
We retain **`p` = [Locate the installed native plugin](plugin.native_path(name="web"))**.
1. `p`
> plugin.load path=`p`
We **[Load the native plugin required by this operation](plugin.load(path=`p`))**.
2. *
> print text=ext/data: native web plugin not found
> sys.exit code=1
****
We **[Print the prepared message](print(text="ext/data: native web plugin not found"))**.
We **[End this run with the selected exit status](sys.exit(code=1))**.
Return *None*.
# cache
+ `url`="memory:"
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | any | "memory:" | Resource connection URL; scheme selects the documented backend |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Key–value cache. Use `memory:` for in-process (tests / single process) or `redis://host:6379/0` for Redis. |
Use `url`="memory:" as the inputs for this operation.
Key–value cache. Use `memory:` for in-process (tests / single process) or `redis://host:6379/0` for Redis.
> _load
*> web_cache_new url=`url`*
We **[Load the native plugin required by this operation](_load())**.
Return *[Key–value cache. Use memory: for in-process (tests / single process) or redis://host:6379/0 for Redis.](web_cache_new(url=`url`))*.
## get
+ `key`
**url = [url](access(self, "url"))**
*> web_cache_get url=`url` key=`key`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | any | required | Entry or field key within the selected resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Read the cached value associated with a key; a miss is reported by the cache result. |
Use `key` as the inputs for this operation.
Read the cached value associated with a key; a miss is reported by the cache result.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Read the cached value associated with a key; a miss is reported by the cache result.](web_cache_get(url=`url`, key=`key`))*.
## set
+ `key`
+ `value`
+ `ttl`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | any | required | Entry or field key within the selected resource |
| value | any | required | Value supplied to this operation; immutable transformations return a new value |
| ttl | any | None | Expiry duration in seconds; None uses the backend default |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Optional `ttl` is seconds until expiry. |
Use `key`, `value`, `ttl`=None as the inputs for this operation.
Optional `ttl` is seconds until expiry.
**url = [url](access(self, "url"))**
*> web_cache_set url=`url` key=`key` value=`value` ttl=`ttl`*
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Optional ttl is seconds until expiry.](web_cache_set(url=`url`, key=`key`, value=`value`, ttl=`ttl`))*.
## del
+ `key`
**url = [url](access(self, "url"))**
*> web_cache_del url=`url` key=`key`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | any | required | Entry or field key within the selected resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Delete a cached key without changing other entries. |
Use `key` as the inputs for this operation.
Delete a cached key without changing other entries.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Delete a cached key without changing other entries.](web_cache_del(url=`url`, key=`key`))*.
## exists
+ `key`
**url = [url](access(self, "url"))**
*> web_cache_exists url=`url` key=`key`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | any | required | Entry or field key within the selected resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Test whether the cache currently holds the selected key. |
Use `key` as the inputs for this operation.
Test whether the cache currently holds the selected key.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Test whether the cache currently holds the selected key.](web_cache_exists(url=`url`, key=`key`))*.
## ttl
+ `key`
**url = [url](access(self, "url"))**
*> web_cache_ttl url=`url` key=`key`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | any | required | Entry or field key within the selected resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Read the remaining lifetime of a cached key using the backend TTL convention. |
Use `key` as the inputs for this operation.
Read the remaining lifetime of a cached key using the backend TTL convention.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Read the remaining lifetime of a cached key using the backend TTL convention.](web_cache_ttl(url=`url`, key=`key`))*.
+376 -131
View File
@@ -8,246 +8,491 @@ import:
table: lib/table.mq.md
---
Database receivers own a connection URL. Begin a transaction with the database receiver, use its returned identifier for transaction operations, then commit or roll back explicitly. Read [the data workflow](index.mq.md) for a real isolated SQLite example and temporary-directory ownership. Native URLs resolve differently from filesystem helpers: validate an absolute SQLite path inside the granted root before passing it to the plugin. New query behavior belongs in the native web database implementation; schema and filters remain readable tables here.
## _load
**p = > plugin.native_path name="web"**
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | No business value on completion; a missing native plugin reports the cause and exits this run. |
Resolve and load the native web plugin before resource operations; missing binaries stop this run.
We retain **`p` = [Locate the installed native plugin](plugin.native_path(name="web"))**.
1. `p`
> plugin.load path=`p`
We **[Load the native plugin required by this operation](plugin.load(path=`p`))**.
2. *
> print text=ext/data: native web plugin not found
> sys.exit code=1
****
We **[Print the prepared message](print(text="ext/data: native web plugin not found"))**.
We **[End this run with the selected exit status](sys.exit(code=1))**.
Return *None*.
# db
+ `url`="sqlite:site.db"
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | any | "sqlite:site.db" | Resource connection URL; scheme selects the documented backend |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Open a database handle. URL schemes: `sqlite:path` (default), `postgres://…` / `postgresql://…` (same CRUD methods). |
Use `url`="sqlite:site.db" as the inputs for this operation.
Open a database handle. URL schemes: `sqlite:path` (default), `postgres://…` / `postgresql://…` (same CRUD methods).
> _load
*> web_db_new url=`url`*
We **[Load the native plugin required by this operation](_load())**.
Return *[Open a database handle. URL schemes: sqlite:path (default), postgres://… / postgresql://… (same CRUD methods).](web_db_new(url=`url`))*.
## init
+ `name`
+ `fields`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | any | required | Name registered or looked up by this operation |
| fields | any | required | Readable field definitions with the columns described by this resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Create a table from a schema table. Optional columns: `唯一`/`unique`, `索引`/`index` (creates UNIQUE / INDEX), `外键`/`fk`/`references` (e.g. `posts.id` or `posts(id)`). Columns named `created_at` / `updated_at` are filled automatically on insert/update when present. |
Use `name`, `fields` as the inputs for this operation.
Create a table from a schema table. Optional columns: `唯一`/`unique`, `索引`/`index` (creates UNIQUE / INDEX), `外键`/`fk`/`references` (e.g. `posts.id` or `posts(id)`). Columns named `created_at` / `updated_at` are filled automatically on insert/update when present.
**url = [url](access(self, "url"))**
*> web_db_init url=`url` name=`name` fields=`fields`*
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Create a table from a schema table](web_db_init(url=`url`, name=`name`, fields=`fields`))*.
## insert
+ `table`
+ `rows`
+ `txn`=None
**url = [url](access(self, "url"))**
*> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| rows | any | required | Input row records to insert or process |
| txn | any | None | Open transaction returned by the same database resource; None runs outside a transaction |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Insert the supplied row records, optionally within the selected open transaction. |
Use `table`, `rows`, `txn`=None as the inputs for this operation.
Insert the supplied row records, optionally within the selected open transaction.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Insert the supplied row records, optionally within the selected open transaction.](web_db_insert(url=`url`, table=`table`, rows=`rows`, txn=`txn`))*.
## select
+ `table`
+ `where`=None
+ `limit`=200
+ `order`=None
+ `txn`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| where | any | None | Explicit filter map or comparison-row table; omitted means no extra filter |
| limit | any | 200 | Maximum returned entries or candidates; this is not a success threshold |
| order | any | None | Field order specification, with a leading minus for descending database order |
| txn | any | None | Open transaction returned by the same database resource; None runs outside a transaction |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Simple filters: one-row map of column→value (AND `=`), or rows `&#124;字段&#124;操作&#124;值&#124;` (`=` `!=` `>` `>=` `<` `<=` `like` `in` `between` `is null`; add `&#124;或&#124;` = `是` to join a row with `OR`). `order` is a column name with optional `-` prefix for descending (`"created_at"`, `"-created_at"`), comma-separated for multiple keys. Pass `txn` to read inside an open transaction. For pages (with a total), use `paginate`. |
Use `table`, `where`=None, `limit`=200, `order`=None, `txn`=None as the inputs for this operation.
Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作|值|` (`=` `!=` `>` `>=` `<` `<=` `like` `in` `between` `is null`; add `|或|` = `是` to join a row with `OR`). `order` is a column name with optional `-` prefix for descending (`"created_at"`, `"-created_at"`), comma-separated for multiple keys. Pass `txn` to read inside an open transaction. For pages (with a total), use `paginate`.
**url = [url](access(self, "url"))**
**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`**
*[rows](access(r, "rows"))*
We retain **`url` = [Read url field](access(`self`, "url"))**.
We retain **`r` = [Simple filters: one-row map of column→value (AND =), or rows |字段|操作|值| (= != > >= < <= like in between is null; add |或| = 是 to join a row with OR)](web_db_select(url=`url`, table=`table`, where=`where`, limit=`limit`, order=`order`, offset=None, txn=`txn`))**.
Return *[rows](access(r, "rows"))*.
## paginate
+ `table`
+ `where`=None
+ `limit`=200
+ `order`=None
+ `跳过`=0
+ `txn`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| where | any | None | Explicit filter map or comparison-row table; omitted means no extra filter |
| limit | any | 200 | Maximum returned entries or candidates; this is not a success threshold |
| order | any | None | Field order specification, with a leading minus for descending database order |
| 跳过 | any | 0 | Number of matching rows skipped before the database page |
| txn | any | None | Open transaction returned by the same database resource; None runs outside a transaction |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Like `select` but returns `{ rows, total }` — the total counts rows matching `where` regardless of `limit`/`跳过`, so you can render `上一页 / 下一页`. Set `跳过` to the number of rows to skip (e.g. page 2 with 10 per page ⇒ `跳过`=10). |
Use `table`, `where`=None, `limit`=200, `order`=None, `跳过`=0, `txn`=None as the inputs for this operation.
Like `select` but returns `{ rows, total }` — the total counts rows matching `where` regardless of `limit`/`跳过`, so you can render `上一页 / 下一页`. Set `跳过` to the number of rows to skip (e.g. page 2 with 10 per page ⇒ `跳过`=10).
**url = [url](access(self, "url"))**
*> web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=`跳过` txn=`txn`*
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Like select but returns { rows, total } — the total counts rows matching where regardless of limit/跳过, so you can render 上一页 / 下一页](web_db_select(url=`url`, table=`table`, where=`where`, limit=`limit`, order=`order`, offset=`跳过`, txn=`txn`))*.
## get
+ `table`
+ `id`
+ `txn`=None
**url = [url](access(self, "url"))**
*> web_db_get url=`url` table=`table` id=`id` txn=`txn`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| txn | any | None | Open transaction returned by the same database resource; None runs outside a transaction |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Read a single row by its identifier from the selected database table. |
Use `table`, `id`, `txn`=None as the inputs for this operation.
Read a single row by its identifier from the selected database table.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Read a single row by its identifier from the selected database table.](web_db_get(url=`url`, table=`table`, id=`id`, txn=`txn`))*.
## update
+ `table`
+ `id`
+ `row`
+ `txn`=None
**url = [url](access(self, "url"))**
*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| row | any | required | Field/value record to apply to the selected row |
| txn | any | None | Open transaction returned by the same database resource; None runs outside a transaction |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Update the supplied fields of the selected row; use update_if when a revision comparison is required. |
Use `table`, `id`, `row`, `txn`=None as the inputs for this operation.
Update the supplied fields of the selected row; use update_if when a revision comparison is required.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Update the supplied fields of the selected row; use update_if when a revision comparison is required.](web_db_update(url=`url`, table=`table`, id=`id`, row=`row`, txn=`txn`))*.
## update_if
+ `table`
+ `id`
+ `row`
+ `expect_col`
+ `expect_val`
+ `txn`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| row | any | required | Field/value record to apply to the selected row |
| expect_col | any | required | Column checked atomically in the conditional database update |
| expect_val | any | required | Expected current value of the comparison column |
| txn | any | None | Open transaction returned by the same database resource; None runs outside a transaction |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Conditional update (CAS) for task/revision control: `UPDATE … WHERE id=? AND expect_col=expect_val`. Returns `{ ok, updated, matched }`; `updated=0` means conflict — do not simulate atomicity with read-then-write in `.mq.md`. |
Use `table`, `id`, `row`, `expect_col`, `expect_val`, `txn`=None as the inputs for this operation.
Conditional update (CAS) for task/revision control: `UPDATE … WHERE id=? AND expect_col=expect_val`. Returns `{ ok, updated, matched }`; `updated=0` means conflict — do not simulate atomicity with read-then-write in `.mq.md`.
**url = [url](access(self, "url"))**
*> web_db_update_if url=`url` table=`table` id=`id` row=`row` expect_col=`expect_col` expect_val=`expect_val` txn=`txn`*
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Conditional update (CAS) for task/revision control: UPDATE … WHERE id=? AND expect_col=expect_val](web_db_update_if(url=`url`, table=`table`, id=`id`, row=`row`, expect_col=`expect_col`, expect_val=`expect_val`, txn=`txn`))*.
## delete
+ `table`
+ `id`
+ `txn`=None
**url = [url](access(self, "url"))**
*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| txn | any | None | Open transaction returned by the same database resource; None runs outside a transaction |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Delete the selected row, optionally inside the caller-owned transaction. |
Use `table`, `id`, `txn`=None as the inputs for this operation.
Delete the selected row, optionally inside the caller-owned transaction.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Delete the selected row, optionally inside the caller-owned transaction.](web_db_delete(url=`url`, table=`table`, id=`id`, txn=`txn`))*.
## exec
+ `sql`
+ `args`=None
+ `txn`=None
**url = [url](access(self, "url"))**
*> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sql | any | required | SQL statement; dynamic values belong in bound args rather than concatenated SQL |
| args | any | None | Arguments passed to the selected command or operation |
| txn | any | None | Open transaction returned by the same database resource; None runs outside a transaction |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Execute SQL with bound arguments and return the native execution outcome. |
Use `sql`, `args`=None, `txn`=None as the inputs for this operation.
Execute SQL with bound arguments and return the native execution outcome.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Execute SQL with bound arguments and return the native execution outcome.](web_db_exec(url=`url`, sql=`sql`, args=`args`, txn=`txn`))*.
## query
+ `sql`
+ `args`=None
+ `txn`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sql | any | required | SQL statement; dynamic values belong in bound args rather than concatenated SQL |
| args | any | None | Arguments passed to the selected command or operation |
| txn | any | None | Open transaction returned by the same database resource; None runs outside a transaction |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Run bare SQL and return the result set — count / join / group / subqueries. Returns `{ rows, count }`. |
Use `sql`, `args`=None, `txn`=None as the inputs for this operation.
Run bare SQL and return the result set — count / join / group / subqueries. Returns `{ rows, count }`.
**url = [url](access(self, "url"))**
*> web_db_query url=`url` sql=`sql` args=`args` txn=`txn`*
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Run bare SQL and return the result set — count / join / group / subqueries. Returns { rows, count }.](web_db_query(url=`url`, sql=`sql`, args=`args`, txn=`txn`))*.
## count
+ `table`
+ `where`=None
+ `txn`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| where | any | None | Explicit filter map or comparison-row table; omitted means no extra filter |
| txn | any | None | Open transaction returned by the same database resource; None runs outside a transaction |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Count rows matching a `where` filter (same syntax as `select`). Returns a number. |
Use `table`, `where`=None, `txn`=None as the inputs for this operation.
Count rows matching a `where` filter (same syntax as `select`). Returns a number.
**url = [url](access(self, "url"))**
**r = > web_db_count url=`url` table=`table` where=`where` txn=`txn`**
*[count](access(r, "count"))*
We retain **`url` = [Read url field](access(`self`, "url"))**.
We retain **`r` = [Count rows matching a where filter (same syntax as select). Returns a number.](web_db_count(url=`url`, table=`table`, where=`where`, txn=`txn`))**.
Return *[count](access(r, "count"))*.
## migrate
+ `steps`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| steps | any | required | Ordered migration or operation records in the documented table shape |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Apply versioned SQL migrations. `steps` is a `&#124;version&#124;sql&#124;` / `&#124;版本&#124;SQL&#124;` table. Applied versions are recorded in `_marqdo_migrations`. Re-running is a no-op for already-applied versions. SQLite only. |
Use `steps` as the inputs for this operation.
Apply versioned SQL migrations. `steps` is a `|version|sql|` / `|版本|SQL|` table. Applied versions are recorded in `_marqdo_migrations`. Re-running is a no-op for already-applied versions. SQLite only.
**url = [url](access(self, "url"))**
*> web_db_migrate url=`url` steps=`steps`*
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Apply versioned SQL migrations](web_db_migrate(url=`url`, steps=`steps`))*.
## fts
+ `table`
+ `columns`
+ `name`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| columns | any | required | Column-name list or column definitions required by this operation |
| name | any | None | Name registered or looked up by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Create an FTS5 index on `table` for the listed content columns (CSV string or list). Default FTS name is `{table}_fts`. Keeps the index in sync via triggers. Requires integer `id` PK. SQLite only. |
Use `table`, `columns`, `name`=None as the inputs for this operation.
Create an FTS5 index on `table` for the listed content columns (CSV string or list). Default FTS name is `{table}_fts`. Keeps the index in sync via triggers. Requires integer `id` PK. SQLite only.
**url = [url](access(self, "url"))**
*> web_db_fts_create url=`url` table=`table` columns=`columns` name=`name`*
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Create an FTS5 index on table for the listed content columns (CSV string or list)](web_db_fts_create(url=`url`, table=`table`, columns=`columns`, name=`name`))*.
## search
+ `table`
+ `q`
+ `limit`=20
+ `name`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| q | any | required | Full-text search query |
| limit | any | 20 | Maximum returned entries or candidates; this is not a success threshold |
| name | any | None | Name registered or looked up by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Full-text search (`MATCH`) against the FTS5 index from `fts`. Returns `{ rows, count }` with a `rank` column (bm25). SQLite only. |
Use `table`, `q`, `limit`=20, `name`=None as the inputs for this operation.
Full-text search (`MATCH`) against the FTS5 index from `fts`. Returns `{ rows, count }` with a `rank` column (bm25). SQLite only.
**url = [url](access(self, "url"))**
*> web_db_search url=`url` table=`table` q=`q` limit=`limit` name=`name`*
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Full-text search (MATCH) against the FTS5 index from fts. Returns { rows, count } with a rank column (bm25). SQLite only.](web_db_search(url=`url`, table=`table`, q=`q`, limit=`limit`, name=`name`))*.
## 事务
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Begin a transaction: borrows the pooled connection exclusively and returns a Every statement runs on the same connection, so a batch is atomic. |
Begin a transaction: borrows the pooled connection exclusively and returns a
`txn` handle. Write inside it, then `提交` (commit) or `回滚` (roll back).
Every statement runs on the same connection, so a batch is atomic.
**url = [url](access(self, "url"))**
*> web_db_begin url=`url`*
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Begin a transaction: borrows the pooled connection exclusively and returns a Every statement runs on the same connection, so a batch is atomic.](web_db_begin(url=`url`))*.
# txn
+ `txn`
+ `url`
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| txn | any | required | Open transaction returned by the same database resource; None runs outside a transaction |
| url | any | required | Resource connection URL; scheme selects the documented backend |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | A transaction handle from `db.事务`. All CRUD here runs on the transaction's connection; finish with `提交` or `回滚`. The transaction identifier and connection URL remain explicit fields for every method. |
Use `txn`, `url` as the inputs for this operation.
A transaction handle from `db.事务`. All CRUD here runs on the transaction's
connection; finish with `提交` or `回滚`.
*self*
The transaction identifier and connection URL remain explicit fields for every method.
`handle` =
| txn | url |
|---|---|
| `txn` | `url` |
Return *handle*.
## insert
+ `table`
+ `rows`
**url = [url](access(self, "url"))**
**txn = [txn](access(self, "txn"))**
*> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| rows | any | required | Input row records to insert or process |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Delegate to web_db_insert with the supplied inputs, preserving its result and failure behavior. |
Use `table`, `rows` as the inputs for this operation.
Delegate to web_db_insert with the supplied inputs, preserving its result and failure behavior.
We retain **`url` = [Read url field](access(`self`, "url"))**.
We retain **`txn` = [Read txn field](access(`self`, "txn"))**.
Return *[Delegate to web_db_insert with the supplied inputs, preserving its result and failure behavior.](web_db_insert(url=`url`, table=`table`, rows=`rows`, txn=`txn`))*.
## select
+ `table`
+ `where`=None
+ `limit`=200
+ `order`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| where | any | None | Explicit filter map or comparison-row table; omitted means no extra filter |
| limit | any | 200 | Maximum returned entries or candidates; this is not a success threshold |
| order | any | None | Field order specification, with a leading minus for descending database order |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Same filters as `db.select`; runs inside the transaction. |
Use `table`, `where`=None, `limit`=200, `order`=None as the inputs for this operation.
Same filters as `db.select`; runs inside the transaction.
**url = [url](access(self, "url"))**
**txn = [txn](access(self, "txn"))**
**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`**
*[rows](access(r, "rows"))*
We retain **`url` = [Read url field](access(`self`, "url"))**.
We retain **`txn` = [Read txn field](access(`self`, "txn"))**.
We retain **`r` = [Same filters as db.select; runs inside the transaction.](web_db_select(url=`url`, table=`table`, where=`where`, limit=`limit`, order=`order`, offset=None, txn=`txn`))**.
Return *[rows](access(r, "rows"))*.
## get
+ `table`
+ `id`
**url = [url](access(self, "url"))**
**txn = [txn](access(self, "txn"))**
*> web_db_get url=`url` table=`table` id=`id` txn=`txn`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Delegate to web_db_get with the supplied inputs, preserving its result and failure behavior. |
Use `table`, `id` as the inputs for this operation.
Delegate to web_db_get with the supplied inputs, preserving its result and failure behavior.
We retain **`url` = [Read url field](access(`self`, "url"))**.
We retain **`txn` = [Read txn field](access(`self`, "txn"))**.
Return *[Delegate to web_db_get with the supplied inputs, preserving its result and failure behavior.](web_db_get(url=`url`, table=`table`, id=`id`, txn=`txn`))*.
## update
+ `table`
+ `id`
+ `row`
**url = [url](access(self, "url"))**
**txn = [txn](access(self, "txn"))**
*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| row | any | required | Field/value record to apply to the selected row |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Delegate to web_db_update with the supplied inputs, preserving its result and failure behavior. |
Use `table`, `id`, `row` as the inputs for this operation.
Delegate to web_db_update with the supplied inputs, preserving its result and failure behavior.
We retain **`url` = [Read url field](access(`self`, "url"))**.
We retain **`txn` = [Read txn field](access(`self`, "txn"))**.
Return *[Delegate to web_db_update with the supplied inputs, preserving its result and failure behavior.](web_db_update(url=`url`, table=`table`, id=`id`, row=`row`, txn=`txn`))*.
## delete
+ `table`
+ `id`
**url = [url](access(self, "url"))**
**txn = [txn](access(self, "txn"))**
*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | Database table name or form submission table |
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Delegate to web_db_delete with the supplied inputs, preserving its result and failure behavior. |
Use `table`, `id` as the inputs for this operation.
Delegate to web_db_delete with the supplied inputs, preserving its result and failure behavior.
We retain **`url` = [Read url field](access(`self`, "url"))**.
We retain **`txn` = [Read txn field](access(`self`, "txn"))**.
Return *[Delegate to web_db_delete with the supplied inputs, preserving its result and failure behavior.](web_db_delete(url=`url`, table=`table`, id=`id`, txn=`txn`))*.
## exec
+ `sql`
+ `args`=None
**url = [url](access(self, "url"))**
**txn = [txn](access(self, "txn"))**
*> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sql | any | required | SQL statement; dynamic values belong in bound args rather than concatenated SQL |
| args | any | None | Arguments passed to the selected command or operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Delegate to web_db_exec with the supplied inputs, preserving its result and failure behavior. |
Use `sql`, `args`=None as the inputs for this operation.
Delegate to web_db_exec with the supplied inputs, preserving its result and failure behavior.
We retain **`url` = [Read url field](access(`self`, "url"))**.
We retain **`txn` = [Read txn field](access(`self`, "txn"))**.
Return *[Delegate to web_db_exec with the supplied inputs, preserving its result and failure behavior.](web_db_exec(url=`url`, sql=`sql`, args=`args`, txn=`txn`))*.
## 提交
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Commit the transaction and return its connection to the pool. |
Commit the transaction and return its connection to the pool.
**txn = [txn](access(self, "txn"))**
*> web_db_commit txn=`txn`*
We retain **`txn` = [Read txn field](access(`self`, "txn"))**.
Return *[Commit the transaction and return its connection to the pool.](web_db_commit(txn=`txn`))*.
## 回滚
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Roll the transaction back (undo every write) and return its connection. |
Roll the transaction back (undo every write) and return its connection.
**txn = [txn](access(self, "txn"))**
*> web_db_rollback txn=`txn`*
We retain **`txn` = [Read txn field](access(`self`, "txn"))**.
Return *[Roll the transaction back (undo every write) and return its connection.](web_db_rollback(txn=`txn`))*.
+109 -29
View File
@@ -8,62 +8,142 @@ import:
table: lib/table.mq.md
---
This leaf projects form schema and submission operations through the native web runtime. Read [the data entry](index.mq.md) before connecting a form to persistent storage. Schema validation and route authorization are different responsibilities: an accepted field value does not authenticate its submitter. Keep schema rows, validation failures and persistence results visible when changing this resource.
## _load
**p = > plugin.native_path name="web"**
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | No business value on completion; a missing native plugin reports the cause and exits this run. |
Resolve and load the native web plugin before resource operations; missing binaries stop this run.
We retain **`p` = [Locate the installed native plugin](plugin.native_path(name="web"))**.
1. `p`
> plugin.load path=`p`
We **[Load the native plugin required by this operation](plugin.load(path=`p`))**.
2. *
> print text=ext/data: native web plugin not found
> sys.exit code=1
****
We **[Print the prepared message](print(text="ext/data: native web plugin not found"))**.
We **[End this run with the selected exit status](sys.exit(code=1))**.
Return *None*.
# form
+ `table`=None
+ `action`=insert
+ `id`=None
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | None | Database table name or form submission table |
| action | any | "insert" | Form submission action such as insert or update |
| id | any | None | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Field table + rules table; submit writes through `# db`. |
Use `table`=None, `action`="insert", `id`=None as the inputs for this operation.
Field table + rules table; submit writes through `# db`.
> _load
*> web_form_new table=`table` action=`action` id=`id`*
We **[Load the native plugin required by this operation](_load())**.
Return *[Field table + rules table; submit writes through # db.](web_form_new(table=`table`, action=`action`, id=`id`))*.
## fields
+ `fields`
*> web_form_fields form=`self` fields=`fields`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| fields | any | required | Readable field definitions with the columns described by this resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Attach the readable field definitions to this form and return the updated resource. |
Use `fields` as the inputs for this operation.
Attach the readable field definitions to this form and return the updated resource.
Return *[Attach the readable field definitions to this form and return the updated resource.](web_form_fields(form=`self`, fields=`fields`))*.
## rules
+ `rules`
*> web_form_rules form=`self` rules=`rules`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| rules | any | required | Readable validation-rule records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Attach validation rules to this form without submitting user data. |
Use `rules` as the inputs for this operation.
Attach validation rules to this form without submitting user data.
Return *[Attach validation rules to this form without submitting user data.](web_form_rules(form=`self`, rules=`rules`))*.
## labels
+ `submit`="Submit"
+ `cancel`="cancel"
+ `cancel_href`=""
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| submit | any | "Submit" | Displayed submit-button label |
| cancel | any | "cancel" | Displayed cancel-button label |
| cancel_href | any | "" | Navigation target of the cancel action |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Localized submit / cancel copy for rendered forms. |
Use `submit`="Submit", `cancel`="cancel", `cancel_href`="" as the inputs for this operation.
Localized submit / cancel copy for rendered forms.
*> web_form_labels form=`self` submit=`submit` cancel=`cancel` cancel_href=`cancel_href`*
Return *[Localized submit / cancel copy for rendered forms.](web_form_labels(form=`self`, submit=`submit`, cancel=`cancel`, cancel_href=`cancel_href`))*.
## validate
+ `rules`=None
+ `data`
*> web_form_validate form=`self` rules=`rules` data=`data`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| rules | any | None | Readable validation-rule records |
| data | any | required | Structured input supplied to this adapter or resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Validate supplied field values and return the native validation result; this does not submit to the database. |
Use `rules`=None, `data` as the inputs for this operation.
Validate supplied field values and return the native validation result; this does not submit to the database.
Return *[Validate supplied field values and return the native validation result; this does not submit to the database.](web_form_validate(form=`self`, rules=`rules`, data=`data`))*.
## render
+ `id`=form
+ `data`=None
+ `errors`=None
*> web_form_render form=`self` id=`id` data=`data` errors=`errors`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | "form" | Identifier produced or selected by the corresponding resource operation |
| data | any | None | Structured input supplied to this adapter or resource |
| errors | any | None | Field/error record returned by validation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Render this form using its data and field errors; rendering is separate from database submission. |
Use `id`="form", `data`=None, `errors`=None as the inputs for this operation.
Render this form using its data and field errors; rendering is separate from database submission.
Return *[Render this form using its data and field errors; rendering is separate from database submission.](web_form_render(form=`self`, id=`id`, data=`data`, errors=`errors`))*.
## submit
+ `data`
+ `db`
**url = [url](access(db, "url"))**
*> web_form_submit form=`self` data=`data` url=`url`*
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| data | any | required | Structured input supplied to this adapter or resource |
| db | any | required | Database resource created by the public database constructor |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Submit validated form data through the selected database resource and configured action. |
Use `data`, `db` as the inputs for this operation.
Submit validated form data through the selected database resource and configured action.
We retain **`url` = [Read url field](access(`db`, "url"))**.
Return *[Submit validated form data through the selected database resource and configured action.](web_form_submit(form=`self`, data=`data`, url=`url`))*.
+121
View File
@@ -0,0 +1,121 @@
---
markup: occlusion
title: Data resources — database, cache, storage and forms
import:
cache_api: ext/data/cache.mq.md
db_api: ext/data/db.mq.md
fs: lib/fs.mq.md
path: lib/path.mq.md
---
Start here when a program needs persistent records, short-lived values, object storage or forms.
The public resource files remain the implementation: [database](db.mq.md) owns schemas and
transactions, [cache](cache.mq.md) owns expiry, [storage](storage.mq.md) owns blobs and upload
validation, and [forms](form.mq.md) separates validation, rendering and submission.
These modules use the native web plugin. In this source checkout build it with
scripts/build-web-plugin.sh; installed packages follow the web package installation route.
Commands below run at the repository root. The cache example uses memory only. The transaction example creates a SQLite file
in an owned temporary directory. Prepare an existing disposable directory and export MQ_WORK to its
absolute path; the transaction report returns work_dir for cleanup after this process exits.
Neither example needs a cloud account, credentials or an external service.
```sh
marqdo call ext/data/index.mq.md memory_cache 'key="manual"' 'value="ready"' --effects plugin --json
marqdo call ext/data/index.mq.md transaction_roundtrip "root=\"$MQ_WORK\"" --effects plugin,fs.write --fs-root "$MQ_WORK" --json
```
A resource constructor creates an object; its methods need that actual receiver. Use the free
workflow tools below for a single CLI call, or import the resource file and keep the object in
your program. Do not pass an instance method to call without its receiver or reconstruct a
transaction from guessed fields. Native resource URLs select their own backend: the marqdo
filesystem root does not rewrite a SQLite, S3 or Redis URL. Grant plugin access deliberately.
For development, keep backend operations in the native web resource implementation and expose
small, documented compositions here. Specify row/filter shapes, transaction ownership, conflicts,
expiry units and cleanup. Add an operation to its responsible leaf file and exercise it through
this facade or a real author program. Run the source-handbook regression and database/cache gold
cases on both backends. A successful transport record is not proof that a business update matched.
## memory_cache
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | text | "manual" | Key owned by this short-lived demonstration |
| value | any | "ready" | Value written and then read back from the in-process cache |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Actual cache get result; value contains the stored value |
Use `key`="manual" and `value`="ready" unless the caller supplies different data. This
workflow uses memory: storage, so values belong to the current native plugin process.
It removes its key after reading; do not use a production key for an illustrative roundtrip.
First **cache = [Create a process-local cache](cache_api.cache(url="memory:"))**.
We then **[Store the supplied value with a sixty-second expiry](> `cache`.set key=`key` value=`value` ttl=60 )**
and retain **stored = [Read the same cache entry](> `cache`.get key=`key` )**.
Once the value has been captured, **[Remove the demonstration key](> `cache`.del key=`key` )**
so another operation does not inherit it. Return *stored* as observed, including its backend fields.
## transaction_roundtrip
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| root | text | required | Absolute disposable root, matching --fs-root; native resource URLs need an absolute path |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | The committed row list and native commit/rollback outcomes; the second insert is rolled back |
Use the absolute `root` supplied for --fs-root. This isolated-file example shows the whole ownership sequence: create a schema, begin a transaction,
write through its receiver, finish it, and read outside it. A second transaction is explicitly
rolled back. The standalone txn constructor wraps the actual native identifier and connection URL;
it does not begin another transaction or invent an identifier.
First **directory = [Create an owned temporary directory under the granted root](fs.temp_dir(prefix="data-manual"))**.
The filesystem helper returns a root-relative name. We retain **work_dir = [Resolve that owned name against the explicit root](path.join(a=`root`, b=`directory`))**
and **[Check that this absolute directory is inside the granted filesystem root](fs.stat(path=`work_dir`))**
before giving any path to the native database. We select **database_path = [Choose the SQLite file inside that directory](path.join(a=`work_dir`, b="manual.db"))**
and select **database_url = "sqlite:" + database_path** before creating
the receiver **store = [Open only that explicitly selected SQLite resource](db_api.db(url=`database_url`))**.
The table schema is ordinary readable data; both columns and their nullability remain visible.
`fields` =
| 字段 | 类型 | 可空 |
|---|---|---|
| title | text | False |
| body | text | True |
We **[Create the isolated demonstration table](> `store`.init name="manual_notes" fields=`fields` )**
before borrowing the transaction connection. Next **native = [Begin the first transaction](> `store`.事务 )**.
To retain the exact identifier, **identifier = [Read the returned transaction identifier](access(native, "txn"))**
and **connection = [Read its connection URL](access(native, "url"))**.
Now **transaction = [Wrap those actual fields as a transaction receiver](db_api.txn(txn=`identifier`, url=`connection`))**.
`row` =
| title | body |
|---|---|
| committed | kept |
We **[Insert the first row inside its transaction](> `transaction`.insert table="manual_notes" rows=`row` )**
and keep **committed = [Commit that transaction](> `transaction`.提交 )**.
The second **cancelled = [Begin an independent transaction](> `store`.事务 )** is a native
transaction receiver, which can be used directly because its type and resource fields are retained.
We **[Insert a row that will be discarded](> `cancelled`.insert table="manual_notes" rows=`row` )**
then capture **rolled_back = [Roll back the second transaction](> `cancelled`.回滚 )**.
Finally **rows = [Read the committed state outside a transaction](> `store`.select table="manual_notes" order="id" )**.
`report` =
| rows | committed | rolled_back | work_dir |
|---|---|---|---|
| `rows` | `committed` | `rolled_back` | `work_dir` |
This example ends with one committed row. Real programs must also arrange rollback when a later
operation fails. This plugin pools open connections, so remove the owned work_dir only after this
CLI process exits and the connection is closed, including on failure. Do not assume sqlite::memory:
is in-memory through this ABI: relative resource paths are resolved against the module directory.
Return *report* with the real row data, completion records and cleanup location.
Loaded 100 of 309 files, more files were not shown because too many files have changed in this diff. Show more