Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
aa0c4d0f55 | ||
|
|
c50c515c4a | ||
|
|
16c44588d5 | ||
|
|
5080136d65 | ||
|
|
cc5277d2b5 | ||
|
|
bb06dad134 | ||
|
|
24dcb97354 | ||
|
|
76aa02846a | ||
|
|
0e389f34ec |
No files matched your search
@@ -140,15 +140,17 @@ Matching surrounding **legacy** `json.set` in `ext/ai/*.mq.md` is **not** compli
|
||||
3. `##` handlers: short prose OK; data as tables; return via `browser.*` / `web.*` / one `table.put`.
|
||||
4. Blank line between comment paragraphs and code.
|
||||
5. Run `marqdo run path.mq.md` from repo root.
|
||||
6. **Calls in narrative:** prefer `**结果 = 某函数 名=`x`**` (no `>` on the RHS). Bracket form `礼貌 [问候] "x"` / `**出 = [put] …**` is fine when modifiers help. Use `> …` for standalone step lists. See `examples/code-as-docs/`.
|
||||
6. **Calls in narrative:** explain the action in its sentence, for example `` 读取之后得到**结果 = [读取文件](文件.读文本(路径=`路径`))**。 `` Return in the sentence with `` 完成后返回*结果*。 `` Keep real control structures and data tables separate when that improves reading. The label describes intent; the payload contains the actual call. See the executable library development guide.
|
||||
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
|
||||
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
|
||||
8. **Index:** use `access(collection, key)` (or `取`); `[描述](payload)` is executable occlusion, never an index by label.
|
||||
|
||||
Browser client programs: prefer 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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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/`.
|
||||
@@ -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 |
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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/
|
||||
|
||||
@@ -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
@@ -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
@@ -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,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,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)"
|
||||
|
||||
Vendored
+8
@@ -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,
|
||||
|
||||
@@ -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/网络/数学/外联/插件** |
|
||||
|
||||
@@ -93,8 +93,8 @@ web.plugin # absolute path hint
|
||||
|----|-----------------------------|
|
||||
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **native `agent`** |
|
||||
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **native `web`** |
|
||||
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **native `quantum`** |
|
||||
| `web` | `web/index.mq.md` + facade/modules + `layout/` · `布局/` + `网页.mq.md`, **native `web`** |
|
||||
| `quantum` | `quantum/`(含 `量子/` 中文树), **native `quantum`** |
|
||||
|
||||
## Release assets (native)
|
||||
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
# 扩展库:index 即代码 · 文档 · SKILL · tools
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active**(契约卡;完整开发范式见下行) |
|
||||
| 日期 | 2026-11-06 |
|
||||
| 愿景 | [doc/next/012.md](../next/012.md)(手写真相源,本文不修改它) |
|
||||
| 范式长文 | [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md)(布局、陷阱、验收清单、推广顺序) |
|
||||
| 试点 | `ext/quantum/`;[手册闭环与当前契约位置修正](ext-quantum-handbook.md) |
|
||||
| 相关 | [ext-abi.md](ext-abi.md) · [ext-quantum.md](ext-quantum.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [function-as-table-semantics.md](function-as-table-semantics.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
扩展包里**每一份** `.mq.md` 同时是可执行代码、可读 SKILL、以及可 `marqdo call` 的 tools 面;**函数即工具**,`###` 即子工具;禁止第二套 catalog / OpenAPI 真相源。开发新包或迁包时以 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 的验收清单为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 整包统一作者契约(无例外)
|
||||
|
||||
适用于包内全部 `.mq.md`(含 `index`、子依赖、`_capability`、兼容层、中英镜像):
|
||||
|
||||
| 要求 | 含义 |
|
||||
|------|------|
|
||||
| 代码 | 标记可执行;实现可薄委托 ABI / 兄弟模块 |
|
||||
| SKILL | `#` 下写清领域、何时用、**For AI agents → `marqdo call` 本文件** |
|
||||
| tools | `##` / `###` 即工具树;无旁路 schema |
|
||||
| 版式 | **形参契约表紧贴标题下**;**返回契约表也在首条执行语句之前**(当前解析器只在此提取契约) |
|
||||
| 叙述 | 每个函数单元叙述占比 **≥ 50%**;公式与约定写进人话 |
|
||||
| 禁止 | `+` 清单当主表面;ABI 名罗列充文档;「内部文件免检」 |
|
||||
|
||||
形参仍由叙述/体中的 `` `名` `` 推断 arity;`| 参数 | 类型 | 说明 |` 为契约表(见 `tests/contracts/`)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 包布局(quantum 试点)
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
index.mq.md # EN 根 SKILL:无上下文也能照抄 marqdo call
|
||||
circuit/index.mq.md # call 工具 + 作者 # circuit
|
||||
gate/ · simulate/ · state/ · density/ · viz/
|
||||
_capability/index.mq.md
|
||||
量子/ # ZH 同包(勿再把 量子/ 抬到 ext/ 顶层)
|
||||
索引.mq.md
|
||||
电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
|
||||
```
|
||||
|
||||
`index` = 总图与编排,必须写明 FILE/FUNCTION/`--effects plugin`;每个子目录的 `index.mq.md` 单独拿到也要能执行。无单独「兼容层」文件。
|
||||
|
||||
---
|
||||
|
||||
## 3. `marqdo call` 与会话
|
||||
|
||||
```text
|
||||
marqdo call <FILE> <FUNCTION> [k=v…]
|
||||
[--json] [--backend tree|bytecode]
|
||||
[--effects none|plugin] # 默认 none
|
||||
[--session <id>]
|
||||
[--toget <name>] # 或尾部 toget <name>
|
||||
```
|
||||
|
||||
- 默认:仅纯函数(今日行为)。
|
||||
- `--effects plugin`:允许 `plugin.call`(及附属的 `output.write`);仍拒绝 fs.write / network / process.exec / llm 等。
|
||||
- `toget` + `--session`:绑定写入 `.marqdo/call-sessions/<id>.json`;参数 `$name` 引用会话值;跨进程 **plugin 句柄经 journal 重放** 重建。
|
||||
- 嵌套子工具:`parent.child`(`###` 路径)。
|
||||
|
||||
值字面量:整数/小数/引号文本/True|False|None;以 `[` / `{` 开头时按 JSON 解析为 List/Map。
|
||||
|
||||
---
|
||||
|
||||
## 4. 叙述 ≥ 50%
|
||||
|
||||
`marqdo check --narrative-ratio`(及 `lib/lint/narrative.mq.md` skill)按函数单元统计叙述字符占比;`ext/quantum/**/*.mq.md` **全量零豁免**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与 ADR 0007
|
||||
|
||||
作者程序与业务路径仍不写 `ensure_plugin` / `host_*`;插件经 `_capability` / facade 加载。Agent 用 `--effects plugin` 调用 facade,不把 capability 当日常工具(文件本身仍须达标 skill)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-11-06 | 初稿:012 试点契约、call effects/toget、quantum 模块树 |
|
||||
| 2026-11-06 | quantum 中文树收进 `ext/quantum/量子/`;根 skill 增加「选哪条路」;`ext add` 拒绝装进源码树 |
|
||||
| 2026-11-06 | 链到 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 作为开发范式长文 |
|
||||
@@ -0,0 +1,71 @@
|
||||
# Quantum:从「拆分过的库」到可执行开发手册
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 日期 | 2026-11-08 |
|
||||
| 使用与开发真相源 | [英文根入口](../../ext/quantum/index.mq.md) · [中文根入口](../../ext/quantum/量子/索引.mq.md) |
|
||||
| 回归门禁 | [quantum_handbook.rs](../../tests/quantum_handbook.rs) |
|
||||
| 思想来源 | [next/010](../next/010.md) · [next/011](../next/011.md) · [next/012](../next/012.md) |
|
||||
| 本文定位 | 记录本次修正的原因与边界;日常使用无需先读本文 |
|
||||
|
||||
上一轮把量子库拆成了模块树,也加入了 `call` 与叙述比例,但没有形成「只沿 index 就能使用和开发」的闭环。问题出在验收标准:目录、工具和叙述存在,并不能证明一个陌生开发者能完成实验、理解结果,再正确扩展它。
|
||||
|
||||
## 已确认的缺口
|
||||
|
||||
| 缺口 | 后果 | 本轮修正 |
|
||||
|------|------|----------|
|
||||
| `## For AI agents`、`## Package layout` 等说明标题 | 解析成无业务意义的真实函数,污染工具树 | 说明用自然段,标题保留给工具/对象 |
|
||||
| 裸 `$qc`、缺会话或只有消费者没有生产者 | 照抄命令失效,Rust argv 测试发现不了 shell 展开 | 每页完整实验;引用和文本字面量用 shell 单引号 |
|
||||
| 字符串 `kind="bitflip"` 的双引号被 shell 去掉 | CLI 拒绝未带字面量引号的文本 | 使用 `'kind="bitflip"'`,通过真实 shell 测试 |
|
||||
| 默认值后紧贴英文标点,如容差后的问号 | 标点被叙述扫描器纳入默认值,number 变成 text | 标点与默认值分隔,实跑覆盖省略参数 |
|
||||
| 旋转、自定义门应用、追加、矩阵导出藏在对象方法里 | 命令行只能走很窄的 Bell 演示路径 | 补齐自由工具,保留既有作者对象方法 |
|
||||
| 重复「本方法返回句柄」等通用套话 | 满足比例却没有解释科学语义 | 移除旧填充,加入来源、单位、边界、预期和下一步 |
|
||||
| 缺源码归属与验证方式 | AI 知道怎么调用,却不知道怎么开发 | 各模块写新增配方/原语的修改位置、镜像和既有金样 |
|
||||
|
||||
## 同一个入口承担四个职责
|
||||
|
||||
使用路径是「打开根入口 → 根据科学问题选模块 → 复制完整实验 → 核对独立期望」。每个子入口也能单独冷启动,包括输入生产者、参数、结果形状、何时转到兄弟模块。
|
||||
|
||||
开发路径从最小必要变化开始:新实验组合已有工具;新酉矩阵使用 `gate.custom`;只有真实能力缺口才改原生实现。每个模块给出它负责的 Rust 文件、ABI 导出、中英镜像及应保留的测试。根入口的 `bell_analysis` 是这种开发方式的具体配方。
|
||||
|
||||
`bell_circuit` 返回可继续组合的电路;原有 `bell_phi_plus` / `贝尔态` 保留概率结果;新增 `bell_analysis` / `纠缠分析` 返回整体纯度、约化纯度、ZZ 关联和 Schmidt 数据。相同概率的经典混合不能冒充 Bell 纯态,所以不能只验证 00/11 概率。
|
||||
|
||||
工具入口继续是普通 `.mq.md` 函数。没有添加 Skill 编译器、MCP 包装、额外工具 manifest 或另一套 schema。符号与契约依靠现有解析和 `knowledge inspect`;符合 next/011 的简洁核心。
|
||||
|
||||
## 契约位置必须符合当前解析器
|
||||
|
||||
旧范式要求「返回表放在体末、返回标记前」,但 `src/parse/mod.rs::extract_function_contract` 只在首条可执行语句前提取参数与返回契约。放到 `cap.load` 之后的返回表会成为普通表,无法承担预期校验。
|
||||
|
||||
本轮以实现为准:参数表紧跟标题;返回表也位于首条执行语句之前;意图叙述仍可与后续执行步骤交错。对象构造器和方法同样补齐契约。叙述声明承载默认值,表说明类型和含义,不把 `any` 句柄伪装成新增的领域类型系统。
|
||||
|
||||
`check --narrative-ratio` 仍是最低门槛,但不再充当手册完成的唯一证据。测试同时检查每个可调用单元具有真正提取出的返回契约、参数无漂移,根符号只有三个实际实验工具。
|
||||
|
||||
## 只承诺已有能力
|
||||
|
||||
手册明确以下区别,而不把 next 的愿景写成已经实现的功能:
|
||||
|
||||
- `call`、跨进程 journal 会话、双后端和稳定符号查询已有实现。
|
||||
- 状态向量默认 12 比特、硬上限 16;密度和 Schmidt 最多六比特。
|
||||
- 理想态与概率忽略教学噪声;只有 `run` 采样施噪。
|
||||
- 密度矩阵构造检查形状和厄米性,不认证半正定与归一化。
|
||||
- Schmidt 熵使用自然对数;局部纯度和关联需要结合整体态解释。
|
||||
- `draw_state` / `画态` 补上现有 qsphere、multibloch 能力;高级态图换肤仍是 Q8c 规划。
|
||||
- `call --effects plugin` 允许绘图返回 SVG,但宿主仍禁文件写入;实际落盘走作者程序的 `run`。
|
||||
- 插件 journal 重放可能重复插件效果;会话不是无副作用的永久对象仓库。
|
||||
- 智能体决定持久交互分支和复杂自我改进并非本轮实现。
|
||||
|
||||
## 验证与推广条件
|
||||
|
||||
先构建 `marqdo_plugin_quantum`,再执行:
|
||||
|
||||
```bash
|
||||
cargo test --locked --test quantum_handbook
|
||||
cargo test --locked --test call_cli quantum_
|
||||
cargo test --locked --test gold ext_quantum -- --test-threads=1
|
||||
```
|
||||
|
||||
手册门禁直接提取双语源码中的 `sh` 围栏,经过 bash 执行原命令,逐次检查退出码与 JSON,不抄写另一份命令目录。作者程序也从 `marqdo` 围栏提取执行。两类示例都验证 Tree/Bytecode,并比较独立数学期望与中间结果;会话放在临时目录隔离。
|
||||
|
||||
组合工具另覆盖具名旋转门、矩阵导出、应用、追加和密度矩阵观察。既有 gold 继续覆盖公式、自定义门、噪声、振幅阻尼、作者方法与 SVG。
|
||||
|
||||
向其他扩展推广时,复用的是这些验证问题:陌生人能否独立启动、能否解释结果、能否找到修改归属、示例是否来自源码且持续执行。无需把 Quantum 的具体物理工具或新的模板套到每个库。
|
||||
@@ -88,7 +88,7 @@
|
||||
|
||||
## 4. 作者面 API
|
||||
|
||||
### 4.1 英文(`ext/quantum/quantum.mq.md`)
|
||||
### 4.1 英文(`ext/quantum/circuit/index.mq.md`)
|
||||
|
||||
在既有 `# circuit` / `# gate` 之外增加(或扩展方法):
|
||||
|
||||
|
||||
+26
-11
@@ -6,6 +6,7 @@
|
||||
| 日期 | 2026-08-12(初版)· 2026-08-28(Q7 · Q8 viz) |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [ext-web.md](ext-web.md) · [view.md](view.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| 安装(目标) | `marqdo ext add quantum`(中英:`quantum` / `量子`) |
|
||||
| 当前手册 | [根入口](../../ext/quantum/index.mq.md) · [中文入口](../../ext/quantum/量子/索引.mq.md) · [2026-11-08 优化记录](ext-quantum-handbook.md) |
|
||||
| 本文目的 | 锁定**作者面**、**模拟语义**、**view 可视化**与**分期**;指导 ABI 插件实现 |
|
||||
|
||||
---
|
||||
@@ -72,7 +73,7 @@ math 是**高中符号与曲线**;quantum 是**离散希尔伯特空间上的
|
||||
|
||||
1. **仅 ABI 插件接入**:`plugins/quantum` → `libquantum.so`;L1 在 `ext/quantum/*.mq.md`。
|
||||
2. **`ext/quantum/**` 禁止 `host_*`**;经 `plugin.native_path` + `plugin.load`(同 web/agent)。
|
||||
3. **中英分文件**:`quantum.mq.md` / `量子.mq.md`,**禁止**混排 API([stdlib-i18n.md](stdlib-i18n.md))。
|
||||
3. **中英分文件**:同一包 `ext/quantum/` 内英文模块树 + `量子/` 中文树,**禁止**混排 API([stdlib-i18n.md](stdlib-i18n.md))。
|
||||
4. **不改核心语法**;电路表单元格保持字面量;门名/比特下标由类方法解析。
|
||||
5. **模拟器有硬上限**(默认 ≤ 12 qubits);超限报错,不静默截断。
|
||||
6. **view 必须有专项展示**(结构卡 + 执行区 SVG),禁止只 dump JSON。
|
||||
@@ -81,17 +82,31 @@ math 是**高中符号与曲线**;quantum 是**离散希尔伯特空间上的
|
||||
|
||||
## 3. 布局与安装
|
||||
|
||||
Skill / tools 树(012 试点;契约 [ext-index-skill-tools.md](ext-index-skill-tools.md),范式 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md)):
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
quantum.mq.md # 英文类 API
|
||||
量子.mq.md # 中文类 API
|
||||
ext/quantum/ # 一个扩展包(同 web/ai:中英同目录)
|
||||
index.mq.md # EN 根 SKILL
|
||||
circuit/ · gate/ · simulate/ · state/ · density/ · viz/
|
||||
_capability/index.mq.md
|
||||
量子/ # ZH 根与模块(同等 skill 标准)
|
||||
索引.mq.md
|
||||
电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
|
||||
plugins/quantum/
|
||||
Cargo.toml
|
||||
src/lib.rs # ABI v2:线性代数 / 施门 / 画 SVG
|
||||
examples/quantum-bell/ # 规范示例(Q3)
|
||||
src/lib.rs # ABI v2
|
||||
examples/quantum-bell/
|
||||
tests/ext/quantum-*.mq.md
|
||||
```
|
||||
|
||||
安装产物(`~/.marqdo/ext` 或 `MARQDO_EXT`,**不是**仓库 `ext/` 源码树):
|
||||
|
||||
```text
|
||||
quantum/...
|
||||
native/libquantum.so
|
||||
quantum.plugin # 绝对路径提示;勿提交
|
||||
```
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_quantum
|
||||
marqdo ext add quantum
|
||||
@@ -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 |Φ+⟩
|
||||
|
||||
@@ -0,0 +1,227 @@
|
||||
# 扩展库开发范式:code = document = skill = tools
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active**(quantum 试点已落地;其它官方扩展按本范式推广) |
|
||||
| 日期 | 2026-11-06 |
|
||||
| 愿景 | [doc/next/012.md](../next/012.md)(手写真相源,本文不修改它) |
|
||||
| 契约摘要 | [ext-index-skill-tools.md](ext-index-skill-tools.md) |
|
||||
| 试点 | [`ext/quantum/`](../../ext/quantum/)(完成)· [`ext/web/`](../../ext/web/)(迁移中,含[布局范式](ext-web-layout-paradigm.md)) |
|
||||
| 相关 | [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [ext-quantum.md](ext-quantum.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [stdlib-i18n.md](stdlib-i18n.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
一份 `.mq.md` **同时是**可执行代码、给人读的文档、给智能体的 SKILL、以及可 `marqdo call` 的 tools 面。
|
||||
**函数即工具**(`##`),**子函数即子工具**(`###`)。禁止旁路 catalog / OpenAPI / MCP 包装成为第二真相源。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么这样设计
|
||||
|
||||
| 传统拆法 | 本范式 |
|
||||
|----------|--------|
|
||||
| README + SDK + tool schema 三套漂移 | 同一文件既可跑又可讲 |
|
||||
| Agent 调 MCP,作者调库 API | 智能体与作者共读同一路径;智能体默认 `marqdo call` |
|
||||
| 扩展 = 功能清单 | 扩展 = 可执行知识包:根 skill 先教会「怎么调」 |
|
||||
|
||||
智能体冷启动时只应:打开根 `index.mq.md` → 按「选哪条路」→ 照抄 `marqdo call`。不必发明第二套 API。
|
||||
|
||||
---
|
||||
|
||||
## 2. 包布局(强制形态)
|
||||
|
||||
一个官方扩展 **一个目录**(与 `web` / `ai` 一致)。中英 **同包分文件**,不要把中文树抬到 `ext/` 顶层变成「第二个包」。
|
||||
|
||||
```text
|
||||
ext/<id>/
|
||||
index.mq.md # EN 根 SKILL(先读)
|
||||
<module>/index.mq.md # 模块:## call 工具 + 可选 # 作者对象
|
||||
_capability/index.mq.md # 仅插件加载(日常勿当业务工具)
|
||||
<中文名>/ # ZH 镜像树(同等标准)
|
||||
索引.mq.md
|
||||
<模块>/索引.mq.md
|
||||
```
|
||||
|
||||
试点现状:
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
index.mq.md · circuit/ · gate/ · simulate/ · state/ · density/ · viz/
|
||||
_capability/
|
||||
量子/索引.mq.md · 电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
|
||||
```
|
||||
|
||||
安装后落在 `~/.marqdo/ext`(或 `MARQDO_EXT`),**不是**仓库源码 `ext/`:
|
||||
|
||||
```text
|
||||
~/.marqdo/ext/
|
||||
quantum/...
|
||||
native/libquantum.so
|
||||
quantum.plugin # 路径提示;勿提交源码树
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 根 skill 怎么写
|
||||
|
||||
根 `index.mq.md` / `索引.mq.md` 是冷启动入口,须按顺序包含:
|
||||
|
||||
1. **选哪条路**(表格,勿用 `1.` 列表——在 Marqdo 里 `1.` 是分支语法)
|
||||
- 只要演示结果 → 根上的编排工具(如 `bell_phi_plus` / `贝尔态`)
|
||||
- 要句柄继续 → 贴出分步 `call`(同一 `--session` + `--toget`)
|
||||
- 换语言 → 指向另一语言树,禁止混用 EN/ZH 工具名
|
||||
2. **如何执行任意工具**:固定 CLI 形状、`--effects plugin`、`--json`、`$name`
|
||||
3. **包布局**:每个模块路径 + 一句用途
|
||||
4. **可选一键编排工具**(如贝尔态):无参或极少参,便于验收
|
||||
|
||||
智能体默认路径是 `##` + `marqdo call`。`# circuit` / `# 电路` 等对象是 **作者程序** import 用的,须在根 skill 写明,避免代理误走方法链。
|
||||
|
||||
---
|
||||
|
||||
## 4. 模块文件怎么写
|
||||
|
||||
每个 `index.mq.md` 单独拿到也要能用:
|
||||
|
||||
| 块 | 要求 |
|
||||
|----|------|
|
||||
| 开篇叙述 | 领域是什么、何时打开本文件 |
|
||||
| For AI agents / 给智能体 | 可照抄的 `marqdo call`;缺能力时 **写明下一步打开哪个兄弟模块**(例如 circuit 造线后概率在 simulate) |
|
||||
| `##` 工具 | 形参契约表紧贴标题下;返回契约表也在首条执行语句前(当前解析器边界);叙述 ≥ 50% |
|
||||
| `#` 对象(可选) | 作者链式 API;加载插件走 facade(如 `cap.load` / `能力.加载`),禁止作者面 `host_*` |
|
||||
|
||||
薄实现:工具体调用 ABI(`*> quantum_…*`)或转发兄弟模块即可,真相在叙述与契约表。
|
||||
|
||||
---
|
||||
|
||||
## 5. `marqdo call` 与会话
|
||||
|
||||
```text
|
||||
marqdo call <FILE> <FUNCTION> [k=v…]
|
||||
[--json]
|
||||
[--effects none|plugin] # 默认 none;ABI 扩展必须 plugin
|
||||
[--session <id>]
|
||||
[--toget <name>] # 或尾部 toget <name>
|
||||
```
|
||||
|
||||
| 机制 | 用途 |
|
||||
|------|------|
|
||||
| `--effects plugin` | 允许 `plugin.call`;仍拒 fs/network/process/llm 等 |
|
||||
| `--session` + `--toget` | 跨进程保存返回值;`$name` 引用;plugin 句柄经 journal 重放 |
|
||||
| `parent.child` | 嵌套 `###` 子工具 |
|
||||
|
||||
参数字面量:数字、引号文本、True/False/None、以 `[`/`{` 开头的 JSON、或 `$name`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 叙述 ≥ 50%
|
||||
|
||||
```bash
|
||||
marqdo check --narrative-ratio ext/<id>/path/index.mq.md
|
||||
```
|
||||
|
||||
- 按函数单元计;契约表计为叙述;语言代码围栏计为代码。
|
||||
- 试点包 `ext/quantum/**` **零豁免**(含 `_capability` 与中文树)。
|
||||
- 狗粮 skill:`lib/lint/narrative.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 7. ABI 与 capability
|
||||
|
||||
- 原生能力只经 `plugin.native_path` + `plugin.load`(集中在 `_capability` / `能力`)。
|
||||
- 领域模块在工具开头调用 `cap.load` / `能力.加载`,**不**把 capability 当日常业务工具。
|
||||
- 遵守 ADR 0007:作者程序与 `ext/**` 业务面不写 `host_*` / `ensure_plugin` 垃圾抽屉。
|
||||
|
||||
---
|
||||
|
||||
## 8. 中英与导入
|
||||
|
||||
| 规则 | 做法 |
|
||||
|------|------|
|
||||
| 分文件 | EN 与 ZH 两套树;禁止同一文件混排 API 名 |
|
||||
| 同包 | `ext/<id>/` 内放中文子树,勿 `ext/<中文包名>/` 顶层并列 |
|
||||
| 作者导入 | `import: circuit: ext/quantum/circuit/index.mq.md` → `circuit.circuit` |
|
||||
| 中文导入 | `导入 量子:ext/quantum/量子/电路/索引.mq.md` → `量子.电路` |
|
||||
| 智能体 | 打开对应语言的根 skill,工具名与路径保持同语言 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 安装与源码卫生
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_<id> # 若有原生插件
|
||||
MARQDO_EXT_SOURCE=/path/to/repo/ext \
|
||||
marqdo ext add <id> # 装到 ~/.marqdo/ext
|
||||
```
|
||||
|
||||
| 禁止 | 原因 |
|
||||
|------|------|
|
||||
| `MARQDO_EXT` 指向仓库 `ext/` 再 `ext add` | 同文件 `fs::copy` 会清空源码;并写入 `*.plugin` / `native/` |
|
||||
| 提交 `ext/*.plugin`、`ext/native/` | 安装产物;已 gitignore |
|
||||
|
||||
`marqdo ext add` **拒绝**把安装根设成源码 `ext/`(防再踩坑)。
|
||||
|
||||
---
|
||||
|
||||
## 10. 常见陷阱
|
||||
|
||||
| 陷阱 | 正确做法 |
|
||||
|------|----------|
|
||||
| 正文写 `1. xxx` 当条目 | 用表格或项目符号;`1.` 是分支 |
|
||||
| 漏 `--effects plugin` | 根 skill 与模块 For AI 段反复写明 |
|
||||
| 只发 `circuit` 文件却找 `probabilities` | 在 circuit 的智能体段贴出 simulate 的完整 call |
|
||||
| 智能体去调 `#` 对象方法 | 根 skill「选哪条路」声明默认走 `##` call |
|
||||
| 中英混用 `新建` + `ext/quantum/circuit` | 选定一棵树用到底 |
|
||||
| 用「兼容层」大文件双挂 API | 删除;模块树即唯一面 |
|
||||
|
||||
---
|
||||
|
||||
Quantum 的完整实验、开发路线与源码示例门禁,见 [2026-11-08 手册修正](ext-quantum-handbook.md)。叙述比例是最低门槛,不能替代照抄执行与独立期望验证。
|
||||
|
||||
## 11. 开发验收清单
|
||||
|
||||
新扩展或把旧包迁到本范式时,逐项打勾:
|
||||
|
||||
- [ ] `ext/<id>/index.mq.md`:选哪条路 + call 形状 + 布局 +(可选)一键编排
|
||||
- [ ] 每个模块 `index.mq.md`:For AI agents 可单独照抄;缺能力时指向兄弟模块
|
||||
- [ ] 全部 `.mq.md`:`marqdo check --narrative-ratio` 通过
|
||||
- [ ] 需要 ABI:`_capability` 唯一加载;领域只调 facade
|
||||
- [ ] 中文:同包子树,路径与 ## 名全中文
|
||||
- [ ] `ext_cli` catalog 的 `mq_files` 列全 EN+ZH 源文件
|
||||
- [ ] 金样:`marqdo call` 一键工具 +(若有句柄)分步 `--session`/`--toget`
|
||||
- [ ] 作者 smoke:import 模块后的 `#` 对象链仍绿
|
||||
- [ ] 未把安装产物写进仓库 `ext/`
|
||||
|
||||
---
|
||||
|
||||
## 12. 智能体视角(试点自检)
|
||||
|
||||
任务「制备 Bell 态」时,合格根 skill 应使代理:
|
||||
|
||||
1. 打开 `ext/quantum/index.mq.md`(或中文 `量子/索引.mq.md`)
|
||||
2. 只要结果 → `bell_phi_plus` / `贝尔态`
|
||||
3. 要句柄 → 照抄 circuit→simulate 四条 call,同一 session
|
||||
|
||||
不必阅读 gate/density,不必发明 Python/MCP。
|
||||
|
||||
---
|
||||
|
||||
## 13. 推广顺序(建议)
|
||||
|
||||
1. **已完成试点**:`ext/quantum/`(含 `量子/`)
|
||||
2. **进行中**:`ext/web/` — 根 `index` + `layout` + 模块树 `page|route|…/index.mq.md` + 中文 `网页/`;作者门面 `web.mq.md`/`网页.mq.md` 保持兼容;call 金样与站点示例对齐继续补齐
|
||||
3. **下一优先**:`linalg` 公式面、`ai` agent 面
|
||||
4. **`ext/net` / `ext/data` / `ext/security`**:随 web 站点场景补根 skill,勿把 DB/鉴权 API 塞回 `web` facade
|
||||
|
||||
每迁一包:更新本文件「试点/推广」表与该包 `doc/design/ext-*.md` 布局节,并加 call 金样。
|
||||
**Web 特有**:布局工程必须写进包内 skill(见 [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md)),不能只放在外部 README。
|
||||
|
||||
---
|
||||
|
||||
## 14. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-11-06 | web:模块树 + `网页/` 镜像 + page session call 金样推进 |
|
||||
| 2026-11-06 | 初版:由 quantum 试点归纳的整包开发范式与验收清单 |
|
||||
@@ -7,7 +7,7 @@
|
||||
| ADR | [0007-web-document-endpoint.md](../adr/0007-web-document-endpoint.md) |
|
||||
| 讨论稿 | [doc/next/007.md](../next/007.md)(superseded) |
|
||||
| 安装 | `marqdo ext add web`(`web` / `网页`) |
|
||||
| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) |
|
||||
| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md) · [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) |
|
||||
|
||||
---
|
||||
|
||||
@@ -33,13 +33,17 @@
|
||||
|
||||
```text
|
||||
ext/web/
|
||||
web.mq.md · 网页.mq.md # facade: page route serve render inspect
|
||||
index.mq.md · 网页.mq.md # 根 skill(智能体先读;含布局铁律)
|
||||
layout/ · 布局/ # 文件划分布局工程 tools
|
||||
web.mq.md # EN facade: page route serve render inspect
|
||||
page.mq.md · route.mq.md · component.mq.md · dom.mq.md · client.mq.md
|
||||
ext/net/ http.mq.md · websocket.mq.md · url.mq.md
|
||||
ext/data/ db.mq.md · cache.mq.md · storage.mq.md
|
||||
ext/security/ auth.mq.md · oidc.mq.md · rbac.mq.md
|
||||
```
|
||||
|
||||
**布局工程**(反 HTML/CSS 注入):见 [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md);包内 `ext/web/layout/index.mq.md`。
|
||||
|
||||
作者入口通常:
|
||||
|
||||
```text
|
||||
@@ -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` 仅逃逸舱) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
# Web:可执行手册与递归布局工程
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 日期 | 2026-11-08 |
|
||||
| 使用与开发入口 | [英文 index](../../ext/web/index.mq.md) · [中文索引](../../ext/web/网页/索引.mq.md) |
|
||||
| 工程规范 | [布局拆分](ext-web-layout-paradigm.md) |
|
||||
| 参考工程 | [英文](../../examples/web-layout-handbook/index.mq.md) · [中文](../../examples/web-layout-handbook-zh/index.mq.md) |
|
||||
| 自动验收 | [源手册与活站点](../../tests/web_handbook.rs) · [浏览器布局](../../tests/web/layout.browser.cjs) |
|
||||
| 思想来源 | [next/010](../next/010.md) · [next/011](../next/011.md) · [next/012](../next/012.md) · [Quantum 优化](ext-quantum-handbook.md) |
|
||||
|
||||
## 原有规范为什么没有落实
|
||||
|
||||
原有 Web skill 已写「拆到简单」,但缺少可沿着文件树复现的工程。原生 `RenderNodes` 仅渲染平面 title/text/link/html;拼接两张表只产生兄弟节点,不会产生双栏。`serve` 又只把 Document 正文当 Markdown,没有执行文档里的组件装配。只加强口头禁止 HTML,无法补上这些实际缺口。
|
||||
|
||||
本轮以一个完整首页检验规范:导航、主体、页脚分开;页脚拆品牌与链接;链接再拆文档与社区。所有末端 content.md 都是普通 Markdown。每个父 index.mq.md 只负责其下一层排列关系。
|
||||
|
||||
## 使用同一份 View 表表示父与叶
|
||||
|
||||
沿用 `type | slot | value | attrs | style`,不新增核心语法、不建立第二套布局方言:
|
||||
|
||||
| 类型 | 值列 | 含义 |
|
||||
|------|------|------|
|
||||
| markdown / 正文 | Markdown 文本 | 内容叶子 |
|
||||
| row / 横排 | 子节点列表 | 响应式分栏 |
|
||||
| column / 纵排 | 子节点列表 | 上下排列 |
|
||||
| nav/header/footer/section/aside | 子节点列表 | 语义区域 |
|
||||
| 既有 title/text/link/html | 兼容原值 | 保留旧节点行为;html 为显式兼容边界 |
|
||||
|
||||
纯 `component.markdown` / `正文` 与 `component.wrap` / `包裹` 构造节点,`layout.stack` / `纵排` 和 `layout.columns` / `分栏` 声明几何。`merge` 接受 @ 记录列表,确定兄弟顺序并保留嵌套值;不再声称它会自动归一化所有列式表或把平面表变成双栏。
|
||||
|
||||
递归渲染保留节点类型,不把子表转成 `map[...]` 字符串。原生渲染器诊断无效子节点、列长不等和过深嵌套。运行时固定的布局样式提供基础响应式几何,样式列继续是类名引用,并非 CSS 编译器。叶子正文经过既有 Markdown 渲染器。
|
||||
|
||||
## 显式 Document 装配
|
||||
|
||||
普通 `type: web` 保留既有 Markdown/数据源路径。需要结构化页面时显式增加 `view: main`(中文 `视图: main`),普通 `# main` 返回 View 节点列表。`serve` 在启动时通过已有 `run_artifact` 回调执行装配,用与离线预览相同的渲染器生成文档,不再套入旧站点的另一份导航/页脚壳。
|
||||
|
||||
这是启动时装配,修改内容后重启;不声称具备自动请求期模板绑定。装配函数不再次调用渲染器或启动服务器。请求期业务仍用 Endpoint。自动 `data_source` 绑定使用普通 Document;与 `view: main` 混用会明确报错,避免静默忽略数据源。
|
||||
|
||||
`web.inspect root=...` / `网页.检视 根=...` 新增离线扫描入口,不启动进程也不执行组件。空应用的新进程无法读取另一个活进程的私有路由;手册不再将此作为活站点检视方法。检视结果加入 `_type: web_inspection`,使不同长度的 declared/system 列表保持对象语义,而不被 JSON 边界当作列式表。
|
||||
|
||||
## 手册与工具一致
|
||||
|
||||
另修复既有元数据型 Endpoint 在 Bytecode 没有函数时误报编译错误的问题:与 Tree 共用声明摘要路径,普通无入口程序仍然拒绝执行。
|
||||
|
||||
全部 Web 模块清理说明性伪函数,参数和返回契约均放在执行前;对象 API 保留。纯 DOM 构造与客户端描述不再无故加载插件。命令示例保护文本引号与会话美元引用。布尔/数字默认值与相邻标点分开,保证真正省略参数时仍符合契约。
|
||||
|
||||
原 `accept_component` 仅根据名称和职责就返回 ok=True,无法代表实际验收。现在返回明确的 checklist 状态,实际验收依据源码职责、渲染结构和运行结果。`site_playbook` 讲流程,`preview_markdown` / `preview_nodes` 给真实预览,不再把增加叙述字数当作完成指标。
|
||||
|
||||
## 验证
|
||||
|
||||
```bash
|
||||
bash scripts/build-web-plugin.sh
|
||||
cargo test --locked --test web_handbook
|
||||
cargo test --locked --test call_cli web_
|
||||
cargo test --locked --test gold ext_web -- --test-threads=1
|
||||
```
|
||||
|
||||
手册门禁直接执行 18 份包内入口的双语 sh 围栏,在 Tree/Bytecode 共执行 80 次命令;同样执行根手册的作者程序。参考工程的双语双后端检查实际预览、启动服务,核对首页与预览相同、关于页仍走普通 Document、API 正常返回 JSON;不把路由声明误当作已经监听。
|
||||
|
||||
浏览器检查可对参考预览或活站点执行,按环境指定现有 Playwright 模块和 Chromium:
|
||||
|
||||
```bash
|
||||
node tests/web/layout.browser.cjs /absolute/path/to/preview.html
|
||||
```
|
||||
|
||||
它测量 1440px 下的外层与内层双栏、390px 下的两层纵向折叠,并检查无横向溢出。无需外部资源或业务 JavaScript。Go 单元测试覆盖递归 Markdown、顺序、带类型列式表、错误形状与 Document 显式执行边界。
|
||||
|
||||
既有 Anlian 渲染测试已从硬编码个人数据库改为临时目录建表并注入已知数据,使完整 Go 套件无需个人站点状态。
|
||||
|
||||
Web 提交时,全库 Rust 为 436 通过、25 项既有策略/回放失败,基线失败集合相同。后续已单独修复 Rust→Lean 命令缺字段的问题:所有操作发送完整的 op、steps、value,进程错误保留退出码与 stderr。原 25 项失败全部消除,新增诊断回归后库级测试为 462 通过、0 失败。策略判定仍由 Lean 执行。
|
||||
@@ -0,0 +1,65 @@
|
||||
# Web 布局工程:先拆布局,直到 Markdown 叶子
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 状态 | Active,2026-11-08 可执行参考工程与浏览器门禁已落地 |
|
||||
| 包内手册 | [英文根入口](../../ext/web/index.mq.md) · [中文根入口](../../ext/web/网页/索引.mq.md) |
|
||||
| 布局工具 | [layout](../../ext/web/layout/index.mq.md) · [布局](../../ext/web/布局/索引.mq.md) |
|
||||
| 实现与边界 | [Web 手册优化](ext-web-handbook.md) · [Artifact](ext-web-artifact.md) · [ADR 0007](../adr/0007-web-document-endpoint.md) |
|
||||
|
||||
## 先建立区域树,再写内容
|
||||
|
||||
首页先拆成导航、主体、页脚。页脚若有左右两栏,拆成品牌与链接;链接区若还有双栏,再拆成文档与社区。继续按内部独立布局拆分,直到叶子只剩简单 Markdown 可以直接表达的内容。
|
||||
|
||||
```text
|
||||
index.mq.md → components/index.mq.md(纵排)
|
||||
├─ nav/index.mq.md → content.md
|
||||
├─ main/index.mq.md → content.md
|
||||
└─ footer/index.mq.md(分栏)
|
||||
├─ brand/index.mq.md → content.md
|
||||
└─ links/index.mq.md(分栏)
|
||||
├─ docs/index.mq.md → content.md
|
||||
└─ community/index.mq.md → content.md
|
||||
```
|
||||
|
||||
父文件只导入子块、合并兄弟节点并声明一层排列。叶子文件只说明一种内容职责;内容较长时,使用相邻的普通 content.md,避免字符串转义。拆分终点不是行数或文件数量,更不是每句话建一个文件。
|
||||
|
||||
## 何时继续拆、何时停止
|
||||
|
||||
| 观察 | 决定 |
|
||||
|------|------|
|
||||
| 导航、正文、页脚混在一个内容块 | 拆成父级装配和三个职责块 |
|
||||
| 页脚内部仍同时负责品牌与链接排布 | 再拆左右子块 |
|
||||
| 链接子块内部仍包含两个独立栏目 | 继续拆到各栏目 Markdown |
|
||||
| 叶子只包含标题、段落、列表、链接、表格、图片 | 停止;已可用普通 Markdown 表达 |
|
||||
| 父文件含大量正文、HTML 标签、CSS 字符串 | 职责或表达方式仍未收敛,继续拆解 |
|
||||
| 结构已经简单,只为减少行数而再拆 | 不必拆;以可读职责为准 |
|
||||
|
||||
表单、数据源、交互各有自己的领域职责,应调用对应模块,不以“Markdown 不表达交互”为由恢复整页 HTML 壳。只有确实需要兼容宿主能力时,才在隔离边界使用已有 raw/css 接口并说明原因。
|
||||
|
||||
## 同一表结构贯穿所有层
|
||||
|
||||
公共列是 `type | slot | value | attrs | style`,中文可用 `类型 | 槽 | 值 | 属性 | 样式`。使用 @ 记录表产生节点列表。
|
||||
|
||||
- `component.markdown` / `组件.正文`:叶子值为普通 Markdown。
|
||||
- `component.wrap` / `组件.包裹`:值中保留子节点列表,可标记 nav/footer/section 等语义区域。
|
||||
- `layout.stack` / `布局.纵排`:声明上下关系。
|
||||
- `layout.columns` / `布局.分栏`:声明响应式横向栏目。
|
||||
- `merge`:只确定兄弟顺序,不会自动产生双栏,也不提前渲染 HTML。
|
||||
|
||||
原生运行时提供基本布局几何,窄屏自动折叠。style 列引用类名,不承载 CSS 源码,也不会自动定义主题。父块始终保留结构值;先渲染子块再拼 HTML 会丢失这条统一路径。
|
||||
|
||||
## 从文件走到真正页面
|
||||
|
||||
[英文参考工程](../../examples/web-layout-handbook/index.mq.md)与[中文参考工程](../../examples/web-layout-handbook-zh/index.mq.md)实现上面的整个拆分树。先运行 preview.mq.md 检查真实渲染,再进入工程目录运行 serve.mq.md。
|
||||
|
||||
结构化 Document 显式声明 `view: main` / `视图: main`,main 返回节点;服务启动时装配一次。普通 Markdown Document 保留既有行为,Endpoint 单独处理请求期互动。改动结构或叶子内容后重启。自动数据源绑定继续使用普通 Document,避免与启动装配混用。
|
||||
|
||||
验收同时检查源码和产物:叶子只含普通 Markdown,父文件只表达其一层关系;桌面页脚出现真正的两层分栏,手机两层都折叠;关于页、API 仍能工作。规则清单本身不是“已经通过”的证明。
|
||||
|
||||
```bash
|
||||
cargo test --locked --test web_handbook
|
||||
node tests/web/layout.browser.cjs /absolute/path/to/preview.html
|
||||
```
|
||||
|
||||
详细测试方式和当前能力边界见[优化记录](ext-web-handbook.md)。
|
||||
@@ -1,5 +1,7 @@
|
||||
# 标准库 / 扩展库:代码即文档
|
||||
|
||||
当前可执行开发规范见[库开发指南](../library-development.mq.md),其中的真实函数示范叙述内赋值、遮蔽调用、表格数据与返回。本页保留设计背景与历史波次。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
@@ -10,39 +12,51 @@
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`lib/*` 与 `ext/*` 的 `.mq.md` 应**可当说明书读、可当程序跑**。薄库不写长文;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。
|
||||
`lib/*` 与 `ext/*` 的 `.mq.md` 应**可当说明书读、可当程序跑**。薄库用充分且具体的叙述解释短实现;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。
|
||||
|
||||
## 2. 薄库模板(默认)
|
||||
## 2. 单文件标准库模板
|
||||
|
||||
每个导出函数 / 方法尽量按此骨架(中英分文件锁步):
|
||||
标准库通常是一个 `lib/*.mq.md` 文件,源码自身承担使用手册、开发说明与 SKILL。
|
||||
直接阅读、导入或调用此文件,不增加强制 `index.mq.md` 或平行模块手册。
|
||||
多文件拓展库才用 `index.mq.md` 组织模块与开发路线。
|
||||
|
||||
1. **目的句**(一句人话,无标记即可)。
|
||||
2. **叙述形参**:正文里出现 `` `名` `` / `` `名`=默认 ``(推断签名);过渡期可保留 `` + `名` ``。
|
||||
3. **一例**:粗体或 `>` 调用;优先可读表面。
|
||||
4. **实现**:短;取元用 `[键](集合)`,**禁止新增**脚注取元 `` `m`[^k] ``(旧解析仍可用)。
|
||||
每个函数依次提供:标题、参数表(名称、类型、默认值、含义)、返回契约、效应说明、
|
||||
叙述形参、用途与真实调用例子、简短实现。无参数函数直接放返回表。
|
||||
参数和返回契约位于第一条执行语句之前;标准库不再保留旧 `+` 形参清单。
|
||||
|
||||
调用示例(三种等价,试点期任选;新叙述优先括号标记或粗体):
|
||||
叙述形参使用正文中的反引号名称,默认值紧跟等号;表格说明与实际默认值必须一致。
|
||||
例如正文写「输入路径 `path`」,调用时即可提供 path。含标点的文本默认值使用完整引号。
|
||||
不透明类型保留渐进式 any,并说明其产生途径和限制。
|
||||
|
||||
## 3. 可读性与调用规范
|
||||
|
||||
每个函数单元的叙述比例必须超过 50%,同时说明真实用途和边界;不能靠重复套话凑比例。
|
||||
参数和返回契约表属于文档面,绑定的数据表仍须表达真实数据。
|
||||
|
||||
宿主等不透明调用用遮蔽语法表达动作:`[]` 写做什么,`()` 写实际执行代码。
|
||||
返回和赋值仍遵循原有标记;标签不执行,也不替代失败处理。
|
||||
|
||||
```markdown
|
||||
**出 = [put] 入=`表` 键="a" 值=1**
|
||||
## read_text
|
||||
|
||||
**出 = put 入=`表` 键="a" 值=1**
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| path | text | 必填 | 授权根目录内的文件路径 |
|
||||
|
||||
> put 入=`表` 键="a" 值=1
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | text | UTF-8 文本;无效编码或读取失败产生诊断 |
|
||||
|
||||
输入路径 `path`。此操作读取整个文件;大文件应改用分块读取。
|
||||
文件根目录由调用方授权,不能通过传入路径绕过权限。
|
||||
|
||||
读取完成后,我们返回*[读取授权范围内的 UTF-8 文本](> host_read_text path=`path`)*,供调用方继续处理。
|
||||
```
|
||||
|
||||
带布尔开关时可用前置修饰:`严格 [parse] text=`源`` → `严格=True`(形参名与修饰语字面一致;核心不剥「的」等词缀)。
|
||||
|
||||
## 3. 硬约束
|
||||
|
||||
| 要 | 不要 |
|
||||
|----|------|
|
||||
| GFM 表作数据;`table.put` / 具名助手 | `json.set` 链当字典构造器 |
|
||||
| 作者程序用 `[k](c)` 取元;`- [项](集合)` foreach | 新代码写 `` m[^k] `` |
|
||||
| 中英 API 对称(见 [stdlib-i18n.md](stdlib-i18n.md)) | 只改一侧 |
|
||||
| 一例跑通即文档(public/stdlib 或 examples) | 另开第二套「文档站」手写说明 |
|
||||
|
||||
**库函数体内的叙述坑:** 函数体里的链接形 `[k](c)`、以及单独的 `**强调**` 会被当成可执行代码。库内说明用「链接取元 / link-index」等字面描述;可执行示例放在 `public/stdlib` 或 `examples/`,不要写在 `##` 体内当叙述。
|
||||
集合读取使用 access(collection, key),不使用旧链接取元;循环使用显式遍历。
|
||||
用 GFM 表和具名助手表达结构化数据,避免 json.set/json.append 链。
|
||||
说明中的调用示例放在未绑定代码围栏内,不能让示例意外成为函数执行步骤。
|
||||
中英文源码保持语义、默认值与行为一致;检查叙述比例、契约并执行真实示例。
|
||||
|
||||
## 4. 波次
|
||||
|
||||
|
||||
@@ -0,0 +1,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)。
|
||||
@@ -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) |
|
||||
|
||||
@@ -16,17 +16,22 @@
|
||||
|
||||
| AST / 概念 | View 优先显示 | 备注 |
|
||||
|------------|---------------|------|
|
||||
| `Expr::Index` | `[键](基)` | 嵌套 `[k2]([k1](base))` |
|
||||
| `InterpPart::Index` | 同上嵌套链接形 | 不再默认 `` `base`[^k] `` |
|
||||
| `Expr::Occluded` | 正文只读动作说明,实际实现进入侧注 | 每个片段独立关联,不把整句改成一次赋值 |
|
||||
| 空遮蔽 `()` | 待补充实际逻辑 | 当前空遮蔽返回 None,不伪装成已接通工具 |
|
||||
| `Expr::Index` / `InterpPart::Index` | 保留经典或脚注取元的兼容说明 | 当前作者程序优先用 access 读取集合;默认链接形是遮蔽 |
|
||||
| `CallExpr` + `bracket_marked` / `pre_modifiers` | `修饰 [callee] 实参…` 或 `[callee] 实参…` | 仅经典 `>` 解析时仍显示 `> callee …` |
|
||||
| 赋值 / 返回 | 粗体 / 斜体语义即可 | 不强制还原整句叙述 |
|
||||
| foreach | `- [项](集合)` | 不变 |
|
||||
| 赋值 / 返回 | 保留原叙述句子,在真实执行片段上标明语句或返回 | 普通链接与字面量不冒充执行遮蔽 |
|
||||
| foreach | `- [动作](遍历 集合 为 项)` | 正文显示动作,控制逻辑见侧注;迭代选择器只切换已有运行记录 |
|
||||
|
||||
## 3. 非目标
|
||||
|
||||
- 不把 view 做成第二语法;解析真相仍在 mapping / call-arguments。
|
||||
- 不删除对脚注取元、旧 `>` 调用的兼容显示需求时,可用次要提示,但默认推荐面优先。
|
||||
|
||||
当前阅读器的实现与验收见 [view-readable-actions.md](view-readable-actions.md)。
|
||||
可执行知识先展示输入、返回、调用边界、依赖和各项依据;摘要和机器身份按需展开。
|
||||
源码说明与运行标注分开,展开侧注或知识卡片不会执行代码。
|
||||
|
||||
## 4. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
# View:动作留在正文,逻辑留在侧注
|
||||
|
||||
本轮针对阅读界面,不改变语言求值和工具权限。阅读示例为
|
||||
[view-reading.mq.md](../../examples/view-reading.mq.md)。
|
||||
|
||||
遮蔽按真实 AST 识别,随后按源片段保留句子:方括号的动作说明留在正文,圆括号中的
|
||||
实现进入独立侧注。同一句话可以包含多个调用和返回,不再把整行当成一次赋值。
|
||||
文字字面量中的链接、普通 Markdown 导航与 classic 取元不冒充执行遮蔽。
|
||||
空圆括号明确显示“待补充实际逻辑”,并说明当前空遮蔽返回 None。
|
||||
|
||||
宽屏实现侧注与运行标注共用现有的左右避碰及引出线布局,彼此有明确名称区分。
|
||||
实现侧注标记“源码说明 · 不是运行结果”,不带调用帧或迭代帧身份。
|
||||
密集区域、窄屏和无脚本页面使用可原生展开的 details;动作按钮可按需查看完整逻辑。
|
||||
悬停与键盘聚焦关联实际源片段,不触发运行。
|
||||
|
||||
“怎样读这份可执行文档”沿用核心构造注册表,说明参数、赋值、返回、调用、条件、
|
||||
循环、数据表、代码块、公式、写回与兼容标记。公式和外语代码仍使用既有卡片,
|
||||
不新增语法或作者必填的展示配置。
|
||||
|
||||
可执行知识按真实源单元分组。默认先读输入、返回、调用边界、依赖和验证依据,
|
||||
身份、摘要与原始状态收进技术详情。契约说明来自已解析的参数和返回表;缺失时如实说明。
|
||||
语法检查、契约检查、测试、来源和领域审阅分别展示,静态分析不代表实际执行或内容正确。
|
||||
源码结构步骤与实际运行时序分开;内存面板先展示最终绑定与调用记录,再按需展开原始报告。
|
||||
|
||||
函数的说明链接和知识卡片使用当前文档源行定位,避免同名方法共用一个 DOM 身份。
|
||||
单文件阅读只分析它和实际导入的依赖,避免无关同目录模块重名导致知识区整体失败。
|
||||
目录阅读保留项目分析。来源身份及版本匹配沿用现有编译器和页面 token,不另建求值器。
|
||||
|
||||
验收入口:
|
||||
|
||||
```sh
|
||||
cargo test --offline --lib view::
|
||||
cargo test --offline --test view_readability
|
||||
cargo test --offline --test gold view_
|
||||
cargo test --offline --test executable_knowledge
|
||||
marqdo view output examples/view-reading.mq.md --no-exec --out /tmp/marqdo-reading
|
||||
```
|
||||
|
||||
浏览器验收脚本是 [readability.browser.cjs](../../tests/view/readability.browser.cjs),
|
||||
接收真实页面 URL,支持 MARQDO_PLAYWRIGHT_MODULE、MARQDO_CHROMIUM 和 MARQDO_SCREENSHOT_DIR。
|
||||
覆盖七种宽度、侧注边界与碰撞、多动作句子、空逻辑、知识卡片、正文定位和无脚本回退。
|
||||
原有 [reader.browser.cjs](../../tests/view/reader.browser.cjs)继续覆盖曲线、帧选择及实时/静态交互。
|
||||
|
||||
本轮实际验收(2026-11-08):67 项 view 相关单元测试、2 项新增只读导出测试通过;
|
||||
全量回归 984 通过、0 失败、2 个原有忽略项。真实 Chromium 验证静态快照、
|
||||
只读导出和实时页面,覆盖七种宽度、无脚本阅读、曲线与帧切换、源码定位及实时重新运行。
|
||||
GOFLAGS 仅对完整回归命令关闭工作区所有权引起的 Go VCS 盖章失败,不改全局配置。
|
||||
@@ -0,0 +1,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。
|
||||
失败记录只说明这次操作没有成功;它不会捕获任意语言错误,也不会替调用者授予权限。
|
||||
@@ -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的设计中包含有### 更深层的函数,这就是子工具了
|
||||
@@ -1,5 +1,7 @@
|
||||
# 调研:Mid M1–M6 之后标准库还缺什么
|
||||
|
||||
历史调研快照:以下缺口已由 Mid2 和后续标准库闭环分批解决,不能作为当前缺失清单。当前能力请从[标准库源码](../../lib/文件.mq.md)与[验收说明](../design/stdlib-handbook.md)核对。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 缺口盘点(M1–M6 闭环之后)** |
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Q0–Q7 完结 · Q8a/Q8b 完结 · Q8c 待做** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 日期 | 2026-08-28 · 2026-11-08 手册闭环 |
|
||||
| **锁定设计** | [design/ext-quantum.md](../design/ext-quantum.md) |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) |
|
||||
| 安装 | `marqdo ext add quantum`(`quantum` / `量子`) |
|
||||
@@ -41,6 +41,8 @@
|
||||
|
||||
---
|
||||
|
||||
2026-11-08:双语 index 已补完整实验、开发路线与真实契约;新增手册源示例的双后端测试。使用与开发从[根入口](../../ext/quantum/index.mq.md)开始,修改动机见[手册优化记录](../design/ext-quantum-handbook.md)。
|
||||
|
||||
## 3. 已收敛的原开放点
|
||||
|
||||
| 原疑问 | 锁定结论(见设计文) |
|
||||
@@ -48,7 +50,7 @@
|
||||
| 并进 math? | **否**,独立 `ext/quantum` |
|
||||
| 电路表 | **要做**(Q3),与方法链等价 |
|
||||
| view 图 | 自绘 SVG;优先 `host_query("record_plot")`;不依赖 web |
|
||||
| 自由函数面 | **不**与对象面并行 |
|
||||
| 自由函数面 | 普通函数供 `call`,对象方法保留作者链;共用既有 ABI,见[手册修正](../design/ext-quantum-handbook.md) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# 库源码叙述式重构验收
|
||||
|
||||
本轮以[可执行开发指南](../library-development.mq.md)为准,覆盖 lib 与 ext 的全部 mq 源码。
|
||||
重构前为 117 个文件、1,258 个函数或对象单元;349 个缺少契约,956 条旧显式形参声明。
|
||||
完成后为 125 个文件、1,273 个单元。其中 61 份公开标准库保持单文件结构,提供 650 个函数;
|
||||
另有 lint 库单元。数据、安全、网络、线性代数和 AI 补齐工程入口,独立多文件职责由 index 组织。
|
||||
原工作区阅读器改动及本轮之前的功能实现保留。
|
||||
|
||||
- [x] 标准库保持单文件,赋值、调用与返回融入叙述,宿主调用有动作说明。
|
||||
- [x] 量子、网页的契约紧接标题,入口与叶子采用同一叙述规范。
|
||||
- [x] 数据、安全、网络、线性代数补齐契约、输入来源、真实工作流与多文件索引。
|
||||
- [x] AI 补齐公开与内部单元的职责说明,解释上下文、路由、工具、工作簿和失败处理。
|
||||
- [x] 所有单元移除旧形参,参数与返回表对应真实接口;不以占位工具或固定通过标志验收。
|
||||
- [x] 逐函数严格检查叙述超过 50%,行内表达式与绑定数据表仍计作代码。
|
||||
- [x] 既有接口与实际行为回归;真实工作流和源码示例在 Tree、Bytecode 执行。
|
||||
- [x] 扩展安装清单包含新入口及其源文件依赖,精简构建、WASM 与全量回归通过。
|
||||
|
||||
源码与工程组织
|
||||
|
||||
标准库不增加强制 index 或平行手册层。每个函数先给参数与返回契约,再说明输入、
|
||||
调用效应、用途、边界与实现。新 table.from_pairs / 表.键值转记录将较宽的具名记录改为
|
||||
可读的 key/value 行表;空列表、空值、重复键更新、键顺序与输入不可变性均有双后端验证。
|
||||
|
||||
拓展库入口解释任务选择、依赖、权限、结果跨步骤传递与开发归属。网页继续采用递归布局:
|
||||
首页拆导航、主体、页脚;页脚与链接的双栏继续拆,直到内部只是单一 Markdown 内容职责。
|
||||
父 index 只负责一层关系,叶子保留普通正文。已有双语参考站点验证真实嵌套、预览、服务与 API。
|
||||
|
||||
AI 中的静态提示、目录与工作簿片段改为普通表格数据,保留原字符、字段顺序和换行;
|
||||
真正的传输 JSON 仍交给 JSON 库解析。复杂函数解释决策顺序、工具授权、上下文预算、
|
||||
事件收集、去重账本和写回责任。中文单步的 sandbox 参数只附加配置行,实际隔离需调用
|
||||
CoW 试跑;工具名解析的半角冒号边界也已如实说明。
|
||||
|
||||
兼容性审核
|
||||
|
||||
[审核器](../../examples/library_audit.rs)使用真实解析器,对比参数顺序、默认值、对象层级、
|
||||
接收者、控制流与计算。遮蔽标签不参与执行;审核只对明确支持的纯常量构造做等价折叠,
|
||||
重复 JSON 键、不安全数值、非常量与未知调用均不会被当作等价常量。折叠规则有独立测试。
|
||||
原始源码快照保留在本次执行环境的临时目录;它不是另一套工具签名或运行时协议。
|
||||
|
||||
对比只有三项旧缺陷修复产生的八条 AST 差异,其余既有单元的参数、默认值与规范化执行结构一致。
|
||||
[精确修复记录](library-authoring-reviewed-fixes.json)保存差异名称、修复前后摘要与原因;
|
||||
审核器只接受摘要完全匹配的记录,新增差异或失效记录都会失败。
|
||||
|
||||
| 旧问题 | 实际修复与验证 |
|
||||
|---|---|
|
||||
| 中文单步说明中的斜体 map 被当作提前返回,实现错误落入构造器 | 说明恢复为文字,单步真正执行;离线模型替身验证上下文调用与最终结果 |
|
||||
| 事务构造器返回未绑定的 self | 用实际 txn 与 url 构造句柄;验证提交、回滚及事务外读取,不额外开启事务 |
|
||||
| 策略说明标题被误认成对象,main 返回未绑定的 routes | 恢复说明与真实 routes 工具,main 调用它;验证 lookup 和默认后端,文件后缀保持文字 |
|
||||
|
||||
执行证据(2026-11-08)
|
||||
|
||||
| 检查 | 结果 |
|
||||
|---|---|
|
||||
| `cargo test --offline --test library_authoring` | 5 项通过;覆盖全部 125 份源码与 1,273 单元、包工作流、旧缺陷、双语记录与安装依赖 |
|
||||
| `cargo test --offline --test stdlib_tasks --test quantum_handbook --test web_handbook` | 18 + 4 + 3 项通过;源码中的真实命令与作者程序在双后端运行 |
|
||||
| `cargo run --offline --quiet --example stdlib_catalog -- --check` | 650 个公开函数,0 条效应说明需要更新 |
|
||||
| AST 原始快照对比及精确修复记录检查 | 8 条已审查修复差异,0 条未解释差异,0 条失效记录 |
|
||||
| `GOFLAGS=-buildvcs=false cargo test --offline --all-targets` | 982 通过、0 失败、2 个原有忽略项,包含千文档编译与 312 项金样例 |
|
||||
| `cargo check --offline --no-default-features --features wasm-core` | 通过;保留已有未使用代码告警 |
|
||||
| 版本匹配工具链的实际 wasm32 构建与 Node 验收 | ABI、桥接、标准库、32 位边界、双语记录、转义表格及句中遮蔽计算通过 |
|
||||
| `git diff --check` | 通过 |
|
||||
|
||||
GOFLAGS 仅用于当前命令绕过工作区所有权引起的 Go VCS 盖章问题,不修改全局配置。
|
||||
WASM 使用临时目录中版本匹配的官方工具链;不以本机编译代替真实 wasm 运行。
|
||||
网络和身份提供方示例使用离线数据或本机可控服务;没有把构造配置、清单或演示结果
|
||||
宣称成生产服务已验证。Node 验收不代表重新完成浏览器 DOM 几何验收。
|
||||
@@ -0,0 +1,50 @@
|
||||
[
|
||||
{
|
||||
"after": "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",
|
||||
"before": "754acb518e0d5f0c5c6f6ae6d48c94a1df69ddbdfff13395114786cbe63edf5e",
|
||||
"difference": "removed ext/ai/policies/step-route.mq.md \"Step class → backend\"",
|
||||
"reason": "修复说明标题被误认成对象、路由表未绑定且 main 返回未定义 routes;真实 routes 工具返回原策略数据,沙盒行文件后缀显式写为文字。双后端验证 lookup 和默认后端。"
|
||||
},
|
||||
{
|
||||
"after": "62bd87e62802aeaefbc635715481451d5eee3b918aefe8db9c816039ef91b04f",
|
||||
"before": "f6c5aecc836c461f7593ffabe9cc2c236a3738a90c49c9c2b5c12a767d97c94c",
|
||||
"difference": "ext/ai/policies/step-route.mq.md \"main\" changed body",
|
||||
"reason": "修复说明标题被误认成对象、路由表未绑定且 main 返回未定义 routes;真实 routes 工具返回原策略数据,沙盒行文件后缀显式写为文字。双后端验证 lookup 和默认后端。"
|
||||
},
|
||||
{
|
||||
"after": "fcbcf165908dd18a9e49f7ff27810176db8e9f63b4352213741664245224f8aa",
|
||||
"before": "b5bea41b6c623f7c09f1bf24dcae58ebab3c0cdd90ad966bc43a45b44867e12b",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体\" changed receiver",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "888398739b40074de2e2f93943516541eec872cecc284835968650b3ef72a24d",
|
||||
"before": "a7553f00f8f05c97c2c44299fd2fcd4641c8f5e9acbb6a246874b096a2acdc0a",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体\" changed body",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "b5bea41b6c623f7c09f1bf24dcae58ebab3c0cdd90ad966bc43a45b44867e12b",
|
||||
"before": "fcbcf165908dd18a9e49f7ff27810176db8e9f63b4352213741664245224f8aa",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体.单步\" changed receiver",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "e3853fac627ca88f1557132aabb6b818ecc805ab53e6feacb3b08c77e503ece4",
|
||||
"before": "aae371909b83bdaec63671897c5581a8ba7f14a5e113bd825fca0576df403e2b",
|
||||
"difference": "ext/ai/智能体.mq.md \"智能体.单步\" changed body",
|
||||
"reason": "修复单步说明中的 返回 *map* 被当作提前返回,使实现落入构造器且无法执行的问题;正文保留自然语言说明,单步实际完成上下文、模型调用和结果处理。离线模型替身在双后端验证。"
|
||||
},
|
||||
{
|
||||
"after": "fcbcf165908dd18a9e49f7ff27810176db8e9f63b4352213741664245224f8aa",
|
||||
"before": "b5bea41b6c623f7c09f1bf24dcae58ebab3c0cdd90ad966bc43a45b44867e12b",
|
||||
"difference": "ext/data/db.mq.md \"txn\" changed receiver",
|
||||
"reason": "事务构造器原来返回未绑定的 self;改为保留调用者传入的真实 txn 和 url 句柄,不额外开始事务。双后端验证构造、提交、回滚与事务外读取。"
|
||||
},
|
||||
{
|
||||
"after": "0a51bc7e7fe4577f32aae9a76ea461213c3547ea9e937f280e17b6e8075194c5",
|
||||
"before": "92096850522e76cff3350d582b57ae3124fd400635ad25fd63f208a1994514f0",
|
||||
"difference": "ext/data/db.mq.md \"txn\" changed body",
|
||||
"reason": "事务构造器原来返回未绑定的 self;改为保留调用者传入的真实 txn 和 url 句柄,不额外开始事务。双后端验证构造、提交、回滚与事务外读取。"
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,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 改动。
|
||||
@@ -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("ed)
|
||||
);
|
||||
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());
|
||||
}
|
||||
}
|
||||
@@ -3,7 +3,7 @@ markup: occlusion
|
||||
title: 贝尔态:两个量子比特如何一起回答
|
||||
description: 从一条假设开始,搭电路、看概率、画图,并用断言验收。
|
||||
import:
|
||||
quantum: ext/quantum/quantum.mq.md
|
||||
quantum: ext/quantum/circuit/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -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
|
||||
---
|
||||
|
||||
@@ -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,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`
|
||||
@@ -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`
|
||||
@@ -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*
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
markup: occlusion
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
A file task returns its answer; stdout is not the answer channel.
|
||||
|
||||
*17*
|
||||
@@ -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*
|
||||
@@ -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()
|
||||
}
|
||||
@@ -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="没有数量"))**。
|
||||
|
||||
把已经计算的值整理成一行记录,字段名称说明每一项的来源。
|
||||
|
||||
`摘要` =
|
||||
|
||||
| 第一笔 | 第二笔 | 总数 |
|
||||
|---|---|---|
|
||||
| `第一笔` | `第二笔` | `总数` |
|
||||
|
||||
最后返回*摘要*,调用者得到的是结构化记录;上面的预留函数并未在本流程中调用。
|
||||
@@ -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" 端口=`监听端口`
|
||||
@@ -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"*
|
||||
@@ -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`
|
||||
@@ -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
@@ -1 +1 @@
|
||||
2.5.1
|
||||
2.6.0
|
||||
+3435
-1930
File diff suppressed because it is too large.
Load diff
@@ -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
@@ -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`))*.
|
||||
@@ -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
@@ -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
@@ -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*.
|
||||
@@ -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
@@ -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` | `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
@@ -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
@@ -14,82 +14,127 @@ description: 文档驱动智能体 v2 — 单步 / 多步 / 运行;技能编
|
||||
插件: lib/插件.mq.md
|
||||
---
|
||||
|
||||
本文件保留中文智能体的模型运行接口与工具调用流程。[中文入口](索引.mq.md)说明模型、编排与试跑的职责边界。内部函数的存在不代表它已进入模型白名单;工具请求必须由作者明确授权。开发时用离线模型替身核对历史、调用点、结果与写回,再测试真实传输。需要隔离执行时使用实际试跑入口,不能仅向结果附加配置记录。
|
||||
|
||||
## 构建单步上下文
|
||||
+ `智能体`
|
||||
+ `任务`
|
||||
+ `源码深度`=default
|
||||
+ `技能深度`=default
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 智能体 | any | 必填 | 本库创建的智能体配置或接收者 |
|
||||
| 任务 | any | 必填 | 本次执行的任务文本或结构化记录 |
|
||||
| 源码深度 | any | "default" | 源码上下文读取深度,默认遵循预算 |
|
||||
| 技能深度 | any | "default" | 技能上下文读取深度,默认遵循预算 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 结果 | any | 组装可读提示:站立提示、任务、*调用位置*、工具、*预算*源码 + Skill,以及人可见的行动约定。 编排 `.mq.md` 即真相源(代码即文档)。默认预算防爆窗;可先 `读取:source|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`|`marqdo`|`small-llm`|`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
@@ -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`))*。
|
||||
@@ -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
@@ -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
@@ -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 `|字段|操作|值|` (`=` `!=` `>` `>=` `<` `<=` `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`. |
|
||||
|
||||
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 `|version|sql|` / `|版本|SQL|` 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
@@ -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`))*.
|
||||
@@ -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
Reference in new issue
Block a user