Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
aa0c4d0f55 | ||
|
|
c50c515c4a | ||
|
|
16c44588d5 | ||
|
|
5080136d65 | ||
|
|
cc5277d2b5 | ||
|
|
bb06dad134 | ||
|
|
24dcb97354 | ||
|
|
76aa02846a | ||
|
|
0e389f34ec | ||
|
|
492790e985 | ||
|
|
ca434a8bab | ||
|
|
6195ad1d5d | ||
|
|
a87c2154ff | ||
|
|
8f1010f967 | ||
|
|
e3d9021bb6 | ||
|
|
142ab523d6 |
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` starts a persistent Python/Node kernel; `session_eval` evaluates source; `session_set` / `session_get` bridge values explicitly as JSON. Close it with `session_close`. JSON integers outside \(\pm(2^{53}-1)\) are refused (`json: integer outside V_safe`); use a decimal string + host `BigInt` for wider ints (`doc/design/v-safe-json.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,50 +126,14 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v2.2.2**:\(V_{\mathsf{safe}}\) JSON 整数——外联/`json` 拒绝域外整数,禁止静默扭曲;宽整数用十进制字符串
|
||||
- **v2.2.2**: \(V_{\mathsf{safe}}\) JSON integers — foreign/`json` refuse OOD ints (no silent distortion); wide ints via decimal strings
|
||||
- **v2.2.2 ext**:扩展包同步 2.2.2 / Ext pack 2.2.2
|
||||
- **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
|
||||
|
||||
|
||||
@@ -79,11 +79,16 @@ plugins/*/tmp/
|
||||
# Plot SVGs emitted beside tests / notebooks when demos run
|
||||
/tests/**/*-plot-*.svg
|
||||
|
||||
# Lean Lake build outputs (sources under verification/ stay tracked)
|
||||
**/.lake/
|
||||
|
||||
# PLDI / thesis harness scratch must never land in this tree
|
||||
.lx*-tmp/
|
||||
|
||||
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
|
||||
/ext/native/
|
||||
# Install-root path hints from `marqdo ext add` — never belong in the source tree
|
||||
/ext/*.plugin
|
||||
|
||||
# Go web plugin c-shared build output (./scripts/build-web-plugin.sh)
|
||||
/plugins/web/build/
|
||||
|
||||
+147
@@ -8,6 +8,153 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## v2.6.0 — 2026-11-08
|
||||
|
||||
### Highlights / 亮点
|
||||
|
||||
标准库、拓展库与阅读界面共同围绕“源码即手册,文档即 SKILL,函数即工具”完成更新。
|
||||
CLI、WASM、扩展包与 VS Code 扩展统一为 2.6.0。
|
||||
|
||||
- 标准库新增完整文件整理、二进制与分块、集合处理、结构化数据、文档修改、HTTP、子任务与时区能力。
|
||||
- 61 份公开标准库提供 650 个函数,保持单文件自述;多文件拓展库通过 index 组织真实工作流。
|
||||
- Quantum 提供可执行实验与会话句柄;Web 明确从区域树递归拆到 Markdown 叶子的工程方式。
|
||||
- View 正文只呈现动作说明,实际逻辑进入左右侧注,空括号明确提示待补逻辑;知识区按输入输出与依据组织。
|
||||
- Standard libraries add practical file, binary, collection, structured-data, document, HTTP, task and timezone workflows.
|
||||
- Libraries are executable handbooks with contracts, narrative parameters and readable inline operations; View separates action text, implementation and observed results.
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:无增删,仍为 19 个核心构造。新增能力属于 Runtime / Document;
|
||||
行内遮蔽边界与 GFM 转义修复沿用既有标记,不引入另一套语法或 Skill 编译器。
|
||||
|
||||
### Added
|
||||
|
||||
- 文件:查找、行读写、JSON/CSV 读写、二进制字节和分块操作、临时资源、单文件原子写、摘要检查、目录批处理与可选 ZIP。
|
||||
- 集合:范围、枚举、投影、筛选、首项/任一/全部判断、分组汇总、连接、集合运算、模式校验及 key/value 行记录构造。
|
||||
- 数据与工程:Result、完整 TOML、IANA 时区/DST、结构化 HTTP 结果与下载、子任务超时/并发/取消、保留周围叙述的受控文档修改。
|
||||
- 标准库单文件手册、开发指南、真实工程示例,以及数据、安全、网络、线性代数、AI 的工程入口与安装依赖。
|
||||
- Quantum 任务导航、实验与双语门面;Web 递归布局、普通 Markdown 叶子和双语参考站点;call 会话中传递实际资源句柄。
|
||||
- View 核心语法阅读指南、实现侧注、可读知识卡片、最终绑定与调用记录,以及静态/实时/无脚本浏览器验收。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 修复中文智能体单步被说明中的斜体 map 提前返回、事务构造器返回未绑定 self、策略说明标题被误识别为对象等旧问题。
|
||||
- 修复行内遮蔽中标签星号和载荷乘法的结束边界,以及 GFM 单元格的转义竖线。
|
||||
- 修复整句遮蔽只处理首个链接、改写叙述的问题;普通导航与文字字面量不冒充可执行逻辑。
|
||||
- 单文件 View 只分析实际依赖闭包,避免无关同目录模块重名使知识说明整体不可用。
|
||||
- 修复回放策略 wire 命令与 agent smoke 工具注册,保持可执行知识门禁可复现。
|
||||
|
||||
### Changed
|
||||
|
||||
- 标准库和拓展库的参数与返回表紧接标题;移除库源码中的旧加号形参,使用叙述形参与句中赋值、调用、返回。
|
||||
- 每个库单元叙述超过 50%;行内代码和绑定数据表仍计作代码,避免以模板或排版替代说明。
|
||||
- 知识区将身份和摘要折叠为技术详情,分别呈现静态检查、测试、来源与领域审阅;阅读操作不会执行代码。
|
||||
- 既有可用接口、默认值和副作用边界保持兼容。原生专属能力不宣称在 WASM 可用,目录批处理不宣称事务,摘要写入不宣称内核 CAS。
|
||||
|
||||
### Validation
|
||||
|
||||
- 本地全量回归 984 通过、0 失败、2 个原有忽略项;发布提交与打包产物另行复核。
|
||||
- 实际 wasm32 产物通过 ABI、桥接、双语集合与 32 位边界验收。
|
||||
- Chromium 验证七种宽度、实时与静态页面、无脚本回退、源码定位、曲线、帧切换与重新运行。
|
||||
|
||||
## v2.5.1 — 2026-11-07
|
||||
|
||||
### Highlights
|
||||
|
||||
**View 标注连线与工具栏优化 / View annotation and toolbar refinement**:执行标注精确绑定源码行与字节区间;连续 S 形曲线取代水平长线,标注贴近正文错落排布,并避让正文和相邻连线;浮动工具栏增加文字说明。CLI · wasm · ext **2.5.1**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造);无 Markdown 语法或插件 ABI 变更。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 执行标注从实际源码片段引出并连接标注标题,不再从正文边缘引出;多调用帧与循环轮次共用准确的源码区间,避免按类型猜测锚点。
|
||||
- 处理源码换行、重跑、窗口变化与字体加载后的连线定位;保留密集区域和窄屏的文内降级。
|
||||
- 连线连续弯曲、柔和金绿过渡,并为相邻曲线保留间距;宽屏标注更靠近正文,横纵方向错落排布。
|
||||
|
||||
### Changed
|
||||
|
||||
- 底部工具栏显示“刷新、设置、运行、清理、更多”,保留深浅色配色与原有操作行为。
|
||||
- 新增七种屏宽、曲率、连线交叉、两端定位及共享源码帧绑定的浏览器回归。
|
||||
- CLI、WASM、扩展包和 VS Code / Cursor 扩展同步 **2.5.1**;扩展包功能沿用 v2.5.0。
|
||||
|
||||
## v2.5.0 — 2026-11-07
|
||||
|
||||
### Highlights
|
||||
|
||||
**View 文档阅读界面重构 / View reader redesign**:暖白金色排版、新 Marqdo 标志与花枝羽毛素材;宽屏执行信息左右引出,窄屏回到正文下方;导航、搜索与悬浮工具栏;实时 view 与静态导出同源,公式和素材离线可用。CLI · wasm · ext **2.5.0**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)。本次变更集中于 view 展示与普通文档执行结果刷新;无 Markdown 语法或插件 ABI 变更。
|
||||
|
||||
```bash
|
||||
marqdo view public
|
||||
marqdo view output public -o site
|
||||
```
|
||||
|
||||
### Added
|
||||
|
||||
- 暖白/深色阅读主题、新 Logo、透明花枝与羽毛;顶部导航、正文/函数/文件搜索、阅读设置和悬浮工具栏。
|
||||
- 宽屏执行标注左右排布与避让,点击查看完整捕获值;窄屏、密集段落和打印采用正文内标注。
|
||||
- 内嵌 KaTeX 0.16.22、字体和装饰素材,静态页面断网仍可渲染公式。
|
||||
- 六种屏宽的 live/static 浏览器回归与普通文档重跑结果一致性回归。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 普通文档重跑后,从同一次执行捕获刷新正文、变量与轨迹,避免为更新标注重复执行。
|
||||
- 移除重复的正文 `id="structure"`,确保刷新定位到实际正文;修复搜索框 Escape 关闭与隐藏目录焦点行为。
|
||||
|
||||
### Changed
|
||||
|
||||
- 函数和变量面板按需打开;调用帧与循环轮次选择保留;高级 notebook 操作从工具菜单进入。
|
||||
- CLI、WASM、扩展包和 VS Code / Cursor 扩展同步为 **2.5.0**;扩展包功能沿用 v2.4.0 已发布内容。
|
||||
|
||||
## v2.4.0 — 2026-11-06
|
||||
|
||||
### Highlights
|
||||
|
||||
**Oracle journal 作语言值**:`foreign.oracle_journal` / `foreign.replay_check` 把观测与纯比较暴露为普通 Marqdo 值(非仅 notebook API);handle/code 不得入 journal;`copy` 拒绝 code。Bytecode / frontend / foreign session 模块化与 applications 金样例;`verification/replay-policy` Lean 策略身份。CLI · wasm · ext **2.4.0**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——变更在 `lib/foreign` 宿主表面与实现结构,不增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **`foreign.oracle_journal` / `foreign.replay_check`**:文档级观测列表与纯 journal 比较(`doc/design/oracle-journal-values.md`)。
|
||||
- **回归**:`foreign-oracle-{journal,names,failure}`、`foreign-{,session-}copy-code-refuse`、`tests/oracle_journal.rs`、applications 四场景、`verification/replay-policy`。
|
||||
- **文档**:`oracle-journal-values.md`;frontend-call / foreign-library 方向笔记。
|
||||
|
||||
### Fixed
|
||||
|
||||
- **view notebook API**:`OnceLock` 初始化等待兼容 MSRV **1.81**(不再调用 ≥1.84 的 `wait`)。
|
||||
- JSON `float_roundtrip` 特征,减少外联浮点往返失真。
|
||||
|
||||
### Changed
|
||||
|
||||
- Bytecode compile/VM、foreign_doc/session、sema resolution、notebook interrupt 路径拆模块(行为对齐既有 Strong 契约)。
|
||||
|
||||
## v2.3.0 — 2026-11-01
|
||||
|
||||
### Highlights
|
||||
|
||||
**Foreign Strong(session / value / replay)**:会话句柄改为不透明 `handle`(不可 JSON 过桥、禁止 text 伪造);`close` 仿射消费(双 close / use-after-close 故障);`replay_check` 对照 oracle journal(旧 `replay_snapshot` 仅重跑保留);GFM 表行 arity 与列长映射拒绝静默补空;Ω 返回域外整数故障。对齐 PLDI Strong 叙事与 Lean SessionReg / \(V_{\mathsf{safe}}\)。CLI · wasm · ext **2.3.0**。
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——破坏面在宿主 foreign/session/JSON 与表解析纪律,不增 Markdown 标记。
|
||||
|
||||
### Added
|
||||
|
||||
- **`Value::Handle`**:`session_open` 返回句柄;session 操作拒绝 text 伪造。
|
||||
- **`DocumentSession::replay_check`** + API `/api/session/snapshot/replay_check`;snapshot 录音字段 + **`oracle_journal`**(与 execution journal 分名)。
|
||||
- **API** `/api/session/oracle_journal`。
|
||||
- **文档**:`doc/design/foreign-strong-correspondence.md`;`v-safe-json.md` 补 Handle / 列 arity / Ω 门。
|
||||
- **回归**:`foreign-session-{use-before-open,use-after-close,double-close,cold-replay-empty,isolation,handle-no-serialize,result-vsafe-refuse}`;`tests/errors/table-arity.mq.md`。
|
||||
|
||||
### Fixed
|
||||
|
||||
- 不等宽 GFM 表不再静默补空单元格;解析报 `table row arity mismatch`。
|
||||
- Py/Node session bootstrap:Ω 结果 OOD 整数不再 `default=str` 偷渡,宿主升级为故障。
|
||||
|
||||
### Changed
|
||||
|
||||
- **`session_close`**:未知 / 已关闭句柄 → 故障(不再返回 `False`)。
|
||||
- **`session_list`**:`id` 字段为 `handle`。
|
||||
- Snapshot export 含 `ok`/`code`/`stdout`/`result`/`source_hash` 与 `oracle_journal`。
|
||||
|
||||
## v2.2.2 — 2026-11-01
|
||||
|
||||
### Highlights
|
||||
|
||||
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.2.2"
|
||||
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.2.2"
|
||||
version = "2.6.0"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
@@ -727,12 +772,59 @@ version = "1.70.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
|
||||
|
||||
[[package]]
|
||||
name = "parse-zoneinfo"
|
||||
version = "0.3.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1f2a05b18d44e2957b88f96ba460715e295bc1d7510468a2f3d3b44535d26c24"
|
||||
dependencies = [
|
||||
"regex",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "percent-encoding"
|
||||
version = "2.3.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
|
||||
|
||||
[[package]]
|
||||
name = "phf"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1fd6780a80ae0c52cc120a26a1a42c1ae51b247a253e4e06113d23d2c2edd078"
|
||||
dependencies = [
|
||||
"phf_shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "phf_codegen"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "aef8048c789fa5e851558d709946d6d79a8ff88c0440c587967f8e94bfb1216a"
|
||||
dependencies = [
|
||||
"phf_generator",
|
||||
"phf_shared",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "phf_generator"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
|
||||
dependencies = [
|
||||
"phf_shared",
|
||||
"rand",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "phf_shared"
|
||||
version = "0.11.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "67eabc2ef2a60eb7faa00097bd1ffdb5bd28e62bf39990626a582201b7a754e5"
|
||||
dependencies = [
|
||||
"siphasher",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pin-project-lite"
|
||||
version = "0.2.17"
|
||||
@@ -971,6 +1063,15 @@ dependencies = [
|
||||
"zmij",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_spanned"
|
||||
version = "0.6.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
|
||||
dependencies = [
|
||||
"serde",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "sha1"
|
||||
version = "0.10.6"
|
||||
@@ -1005,6 +1106,12 @@ version = "0.3.10"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
|
||||
|
||||
[[package]]
|
||||
name = "siphasher"
|
||||
version = "1.0.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "33f4fe9184a62d842c9ef383018f3306d8ba224fd9d836f56d7288308847c256"
|
||||
|
||||
[[package]]
|
||||
name = "slab"
|
||||
version = "0.4.12"
|
||||
@@ -1152,6 +1259,47 @@ dependencies = [
|
||||
"tungstenite",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml"
|
||||
version = "0.8.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
|
||||
dependencies = [
|
||||
"serde",
|
||||
"serde_spanned",
|
||||
"toml_datetime",
|
||||
"toml_edit",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml_datetime"
|
||||
version = "0.6.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
|
||||
dependencies = [
|
||||
"serde",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml_edit"
|
||||
version = "0.22.27"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
|
||||
dependencies = [
|
||||
"indexmap",
|
||||
"serde",
|
||||
"serde_spanned",
|
||||
"toml_datetime",
|
||||
"toml_write",
|
||||
"winnow",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "toml_write"
|
||||
version = "0.1.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
|
||||
|
||||
[[package]]
|
||||
name = "tungstenite"
|
||||
version = "0.24.0"
|
||||
@@ -1493,6 +1641,15 @@ version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
|
||||
|
||||
[[package]]
|
||||
name = "winnow"
|
||||
version = "0.7.15"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
|
||||
dependencies = [
|
||||
"memchr",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "zerocopy"
|
||||
version = "0.8.56"
|
||||
|
||||
+4
-2
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "2.2.2"
|
||||
version = "2.6.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -30,7 +30,7 @@ chrono = { version = "0.4", default-features = false, features = ["clock", "std"
|
||||
clap = { version = "=4.4.18", features = ["derive"], optional = true }
|
||||
pulldown-cmark = "0.12"
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
serde_json = "1"
|
||||
serde_json = { version = "1", features = ["float_roundtrip"] }
|
||||
thiserror = "1"
|
||||
tiny_http = { version = "0.12", optional = true }
|
||||
sha2 = { version = "=0.10.9", default-features = false }
|
||||
@@ -49,6 +49,8 @@ zip = { version = "=0.6.6", default-features = false, features = ["deflate"], op
|
||||
libloading = { version = "=0.8.6", optional = true }
|
||||
include_dir = "0.7"
|
||||
libc = { version = "0.2", optional = true }
|
||||
chrono-tz = "=0.10.0"
|
||||
toml = "=0.8.23"
|
||||
|
||||
[target.'cfg(target_arch = "wasm32")'.dependencies]
|
||||
# Custom entropy — no `js`/wasm-bindgen imports (raw mq_* ABI + marqdo-bridge.js).
|
||||
|
||||
@@ -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,9 +288,19 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v2.2.2)
|
||||
## 现状(v2.6.0)
|
||||
|
||||
- **\(V_{\mathsf{safe}}\) JSON 整数(v2.2.2)**:外联与 `lib/json` 拒绝 `|n| > 2^{53}-1` 的 JSON 整数(对齐 Lean ForeignJSON);宽整数用十进制字符串 + Node `BigInt`。扩展包同步 **2.2.2**
|
||||
- **标准库与拓展库手册(v2.6.0)**:61 份公开标准库、650 个函数;源码内参数/返回契约、叙述形参、句中遮蔽调用与真实工程。新增文件/字节/集合/Result/文档/HTTP/任务/TOML/时区工作流;多文件拓展库以 index 组织。
|
||||
- **View 可读动作与知识(v2.6.0)**:正文读动作,侧注看实现,运行标注看实际结果;空逻辑明确提示待补。知识说明先看输入、返回、依赖和依据,技术身份按需展开。
|
||||
- **Quantum / Web 工程实践(v2.6.0)**:可执行实验、会话句柄与双语门面;网页先递归拆布局,直到叶子可以直接用 Markdown 表达。CLI · wasm · ext · VS Code 扩展同步 **2.6.0**。
|
||||
|
||||
- **View 连线与工具栏(v2.5.1)**:真实源码锚点、连续 S 形曲线、错落标注与连线避让;底部工具栏增加文字标签。深浅色配色保持一致。CLI · wasm · ext 同步 **2.5.1**。
|
||||
|
||||
- **View 阅读界面(v2.5.0)**:暖白金色主题、新 Logo 与花枝装饰;真实执行信息左右引出、窄屏内联;导航/搜索/阅读设置/工具栏;重跑同步刷新与离线公式。CLI · wasm · ext 同步 **2.5.0**。
|
||||
|
||||
- **Oracle journal 语言值(v2.4.0)**:`foreign.oracle_journal` / `foreign.replay_check` 作普通值;handle/code 拒入 journal;bytecode/frontend 硬化;扩展包同步 **2.4.0**
|
||||
- **Foreign Strong(v2.3.0)**:会话 `handle`(不可过桥)· 仿射 close · `replay_check`/oracle journal · 表 arity refuse · Ω∈\(V_{\mathsf{safe}}\)。扩展包同步 **2.3.0**
|
||||
- **\(V_{\mathsf{safe}}\) JSON 整数(v2.2.2)**:外联与 `lib/json` 拒绝 `|n| > 2^{53}-1` 的 JSON 整数(对齐 Lean ForeignJSON);宽整数用十进制字符串 + Node `BigInt`。
|
||||
- **view 大纲侧栏(v2.2.1)**:修复 occlusion 文档与中等宽度下 Functions / Variables 掉到正文下方的问题;静态 `view output` 同源。
|
||||
- **函数级调用(v2.2.0)**:`marqdo call <文件.mq.md> <函数> 名字=值`。同一份文档给人读,也按函数执行;Tree 与 Bytecode 都跑被点名的函数,不回退到 `# main`。默认只执行纯函数。`--json` 给 Agent 读取结果或诊断。说明与价值见 [22-函数调用](public/features/22-函数调用.mq.md)。示例:`marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3` → `5`。扩展包同步 **2.2.1**
|
||||
- **Agent 可靠工作台(v2.1.5)**:ResourceView(JSON/CSV/PDF/image)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制与 execute 槽隔离;扩展包同步 **2.1.5**
|
||||
@@ -331,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.2.2)
|
||||
### 如何使用最新 Marqdo(v2.6.0)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -346,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.2.2 # 或留在 main
|
||||
git checkout v2.6.0 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -387,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.2.2
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v2.6.0
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "2.2.2"
|
||||
version = "2.6.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
Vendored
+36
@@ -1,3 +1,39 @@
|
||||
marqdo (2.6.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Executable standard/extension handbooks and practical file/data/task tools.
|
||||
* Readable View action notes, knowledge contracts and offline reader support.
|
||||
* Preserve effect, platform and source compatibility boundaries.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sun, 08 Nov 2026 23:01:35 +0800
|
||||
|
||||
marqdo (2.5.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.5.1: exact source anchors, flowing annotation curves,
|
||||
staggered margin notes, connector avoidance and a labeled toolbar.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 07 Nov 2026 13:05:55 +0800
|
||||
|
||||
marqdo (2.5.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.5.0: redesigned document reader, margin execution annotations,
|
||||
offline math/assets, navigation/search, and consistent live result refresh.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 07 Nov 2026 10:00:00 +0800
|
||||
|
||||
marqdo (2.4.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.4.0: oracle journal as language values (foreign.oracle_journal /
|
||||
replay_check), bytecode/frontend hardening, MSRV 1.81 OnceLock wait fix.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Fri, 06 Nov 2026 15:15:00 +0800
|
||||
|
||||
marqdo (2.3.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.3.0: Strong foreign session — opaque Handle, affine close,
|
||||
replay_check vs oracle journal, table arity refuse, Omega V_safe gate.
|
||||
|
||||
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 01 Nov 2026 14:45:00 +0800
|
||||
|
||||
marqdo (2.2.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 2.2.2: V_safe JSON integer contract on foreign/json bridge —
|
||||
|
||||
@@ -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)。
|
||||
@@ -0,0 +1,24 @@
|
||||
# 外联库论文的研究方向
|
||||
|
||||
作者于 2026-11-05 将论文主线明确为:**叙述本身是程序,外部代码是值**。
|
||||
Marqdo 的外联库用于在这一宿主模型中组合既有语言的计算能力,统一说明、控制流、
|
||||
代码复用、状态与显式数据交换。论文应先解释 Notebook/文学编程中的实际设计问题,
|
||||
再给出解决方案、可核验的收益、形式化依据和应用实验。
|
||||
|
||||
后续实现工作围绕绑定的代码值、参数化调用、持久会话、复制值和文档计划展开。
|
||||
生命周期、值域和重放机制为这个统一设计提供保证;不能将重放检查器重新提升成
|
||||
取代外联库与叙述式编程的论文主题。不得把未测的人因优势或未证明的实现正确性
|
||||
写成既成事实。
|
||||
|
||||
完整方向文件在论文工作区:
|
||||
|
||||
- 方向(当前):`MarqdoThesis/PLDI/design/V7-NARRATIVE-FIRST-DIRECTION-2026-11-05.md`
|
||||
- v6 方向(历史):`MarqdoThesis/PLDI/design/V6-NARRATIVE-FIRST-DIRECTION-2026-11-05.md`
|
||||
- 证据映射:`MarqdoThesis/PLDI/design/V6-EVIDENCE-MAP-2026-11-05.md`
|
||||
- 章节与页预算:`MarqdoThesis/PLDI/design/V6-OUTLINE-2026-11-05.md`
|
||||
|
||||
当前稿位于 `MarqdoThesis/PLDI/paper-v7`;v6 保留,历史 v5 及其证据保留。方向文件取代了
|
||||
此前把论文缩成“外联会话值 + 因果重放”的 N3 路线:重放是支撑机制,不是主线。
|
||||
|
||||
2026-11-05 交付:`MarqdoThesis/PLDI/paper-v7/main.pdf`,正文(含 AI Use)20 页。
|
||||
v6 保留为上一版尝试;更早的 v6 草稿保留在 `paper-v6-draft-2026-11-05/`。
|
||||
@@ -0,0 +1,44 @@
|
||||
# Foreign Strong: Lean ↔ host correspondence
|
||||
|
||||
2026-11-02 补充:`ForeignSource.lean` 对显式局部环境、返回、函数调用/递归、
|
||||
分支和有界 while 的源解释器与独立 effect 编译器证明一般精化,并推出安全
|
||||
观察和旧句柄不可复活。`CheckForeignSource.lean` 消费真实加载后 AST 的显式
|
||||
适配格式,用独立 counter oracle 对照 tree/bytecode 的返回、journal、fault
|
||||
与故障后 n。它已用于发现并修复 tree 的父词法作用域查找缺陷。
|
||||
这是源控制流层的证明与实现 translation validation;Rust parser/adapter、
|
||||
全部 AST 构造、机器数值运算和物理调度的完整 refinement 仍须完成。
|
||||
模型中的 fuel 是分析界限,不能称为真实程序必然终止或有界取消。
|
||||
|
||||
Pinned with PLDI Strong / paper-v5 (sessions as values; three gates).
|
||||
Marqdo **2.3.0** host implements the same objects the Lean development decides.
|
||||
|
||||
| Lean / paper rule | Host surface | Evidence |
|
||||
|---|---|---|
|
||||
| `SessionReg` + `sessionOpen` / `Close` / `sessionEval` | `HostContext.foreign_sessions` + `Value::Handle` | `DocCalc.lean` S1–S6, `requires_live`; `foreign_session.rs` |
|
||||
| `Ω(s, τ, c)` | Persistent kernel + process order | Oracle journal `(cell, source_hash, stdout, result)` |
|
||||
| `SafeVal` / Encode / Decode | `src/host/json.rs` + bootstrap sanitize | `ForeignJSON.lean`; gold `foreign-*-vsafe-*` |
|
||||
| Handle ∉ \(V_{\mathsf{safe}}\) | `value_to_json(Handle) → Err` | `foreign-session-handle-no-serialize.mq.md` |
|
||||
| Closed / Closed-Close | use-after-close / double-close `Err` | gold misuse; `sessionClose_then_eval_none_w` |
|
||||
| Oracle-Domain | Ω OOD integer → host `Err` | `foreign-session-result-vsafe-refuse.mq.md` |
|
||||
| Table arity stuck | Parse refuse unequal GFM; JSON unequal columns | `Surface.lean`; `tests/errors/table-arity.mq.md` |
|
||||
| Snapshot hash match/mismatch | `view/output.rs` `snapshot_page` | unit snapshot hash tests |
|
||||
| **Thm. corr** (`corr_fresh_functional`) | Cold `evaldoc`; step values = Ω | `corr_step_eq_omega`; `corr_doc_fresh_foreign`; foreign-session gold |
|
||||
| `OracleJournal` / `replayCheck` | `oracle_journal` + `DocumentSession::replay_check` | `replayCheck_*`; fate R1–R3 |
|
||||
| `corr_fail_warm_store` / `corr_fail_reordered_plan` | cold vs warm / schedule order | DocCalc witnesses; Table corr-fail |
|
||||
| Dual-backend differential | `tests/gold.rs` tree + bytecode | 308 × 2; foreign session/V_safe subset |
|
||||
|
||||
## Scope (not distance)
|
||||
|
||||
- SafeVal mechanization covers the **integer** fragment; finite floats are admitted by the host under the same refuse-not-coerce bridge policy for non-integers already in SafeVal.
|
||||
- Session discipline is a **dynamic registry** (affine close + borrow-use). Static linear types over OS-killable processes are out of scope by design, not an unfinished host feature.
|
||||
- Correspondence is mechanized for the **closed / fresh-open / functional-Ω** fragment (`corr_fresh_functional`): per-step interactive value = Ω answer, interactive runner = normative runner, `replayCheck` on the journal. Broken hypotheses are `corr_fail_*`. Host discharge is foreign-session gold plus R1–R3, not R1–R3 alone.
|
||||
|
||||
## Reviewer-driven implementation update (2026-11-01)
|
||||
|
||||
The independent live cursor and multisession action-plan simulation are in
|
||||
`DocCalc.runForeignLive_simulation` and `MarqdoProof.ForeignTrace`. The language
|
||||
now exposes oracle observations and pure journal comparison through
|
||||
`foreign.oracle_journal` / `foreign.replay_check`. Strict interactive snapshot
|
||||
replay uses the full oracle history with source identity and per-step input.
|
||||
See `oracle-journal-values.md` for the API and the research experiment manifest
|
||||
under `PLDI/experiments/reviewer-v5/` for exact source hashes and actual runs.
|
||||
@@ -0,0 +1,336 @@
|
||||
# Executable call and integer semantics
|
||||
|
||||
This describes the implementation contract exercised by
|
||||
`src/frontend_elaboration_tests.rs`; it is not a claim of a verified parser.
|
||||
|
||||
All explicit actual arguments evaluate once in authored order, including extra
|
||||
named arguments whose values the callee does not read. Binding then permutes
|
||||
already computed values into parameter slots. Named arguments take precedence
|
||||
over positional filling; duplicate names and excess positional arguments fail.
|
||||
A duplicate-actual binding fault occurs only when its call is reached, after
|
||||
all explicit actuals have evaluated; it cannot reject an unused function at
|
||||
compile time or erase an earlier argument effect.
|
||||
Local calls and imported calls use the same order. Builtins and host primitives
|
||||
must not reorder expression evaluation when selecting their parameter values.
|
||||
|
||||
All supplied parameters are available before defaults. Missing defaults execute
|
||||
in parameter declaration order, once per call, in the target definition's
|
||||
module and lexical scope. A default can see supplied parameters, earlier
|
||||
computed defaults, and an explicitly bound method receiver. It cannot capture
|
||||
the caller's locals. A still omitted later parameter is unbound. Explicit None
|
||||
is a supplied value and never triggers a default. Required-argument validation
|
||||
precedes default execution. Default expressions participate in receiver
|
||||
classification, dependency analysis and transitive effect inference.
|
||||
|
||||
A dynamic method's signature belongs to the resolved receiver and selected
|
||||
method; a different object's same-named method cannot supply its parameter
|
||||
list. Imported definitions retain their module scope. A compiled document's
|
||||
entry is selected only from its own module; an imported `main` is not an entry.
|
||||
|
||||
The bytecode retains argument names and explicit presence bits. Callee
|
||||
prologues evaluate defaults in their own frame. Local slots distinguish an
|
||||
unbound slot from a slot holding None. Local, constant, call-layout and jump
|
||||
indices use container-sized indices rather than unchecked 8/16-bit casts.
|
||||
Scratch slots are reused across sequential calls while pending outer actuals
|
||||
remain live. Scalar constant interning uses a hash table; floating constants
|
||||
are keyed by their exact bits.
|
||||
|
||||
Host integers are signed 64-bit values. Add, subtract, multiply, divide and
|
||||
negation report a language error on overflow in every build profile; division
|
||||
by zero is a separate error. Division truncates toward zero. The negative
|
||||
endpoint has a valid signed literal. Float-to-int conversion rejects nonfinite
|
||||
or out-of-range inputs instead of silently saturating. This local integer
|
||||
domain is distinct from the narrower continuous foreign-copy domain.
|
||||
|
||||
The Lean call-combinator proof preserves complete interaction programs for
|
||||
arbitrary argument evaluators, including failure and reply-dependent requests.
|
||||
The integer model specifies exact arithmetic followed by representability
|
||||
checking. Native documents, independently derived Python expectations, a Lean
|
||||
arithmetic consumer and isolated source mutations validate the implementation
|
||||
links. These do not prove the entire Rust parser, binder, object representation
|
||||
or adapter. The research coverage ledger must keep those obligations explicit.
|
||||
|
||||
## Module identity, entry inputs and source-bound invocation
|
||||
|
||||
Instances retain the existing map representation and safe-copy domain. The
|
||||
reserved `_type_module` field is a list of import binding names, paired with
|
||||
`_type`. Class selection uses that module instance within the active import
|
||||
tree; inherited methods resolve their bases in the defining module. Equal
|
||||
class names in different imports remain distinct. These fields are ordinary,
|
||||
forgeable data, not capabilities or globally portable nominal identities.
|
||||
Round trips through Python/Node preserve these descriptors in the same module
|
||||
context. Opaque session handles remain outside the copy domain.
|
||||
|
||||
Entry metadata is passed to `Vm::run`, never compiled into `main`'s body.
|
||||
Explicit named/recursive invocations of `main` therefore keep their own inputs.
|
||||
Defaults run with the invocation's actual registry; a session-valued default
|
||||
must not be evaluated in a separate interpreter and then injected into a VM.
|
||||
Reads appearing only in explicit/prose defaults participate in input inference
|
||||
and effect analysis. Default failures use the parameter declaration's span.
|
||||
Source-bound APIs preserve the selected declaration's source identity and
|
||||
span, even when two declarations have the same dotted path. Textual path calls
|
||||
retain the existing first-declaration rule. Duplicate parameter names are
|
||||
rejected because they cannot define distinct binding slots.
|
||||
|
||||
Both backends retain parameter, return and local field contracts. Bytecode
|
||||
checks supplied/defaulted inputs before the body, explicit returns before
|
||||
returning, table bindings before writing a local and direct footnote accesses
|
||||
before/after lookup. Unknown fields report the contract error before a generic
|
||||
missing-key error. Entry/raw invocations also check their completed inputs.
|
||||
Contract diagnostics retain the declaration quote and the failure location.
|
||||
|
||||
## Refinement obligations and current evidence
|
||||
|
||||
| Link | Mechanized result or implementation evidence | Remaining obligation |
|
||||
|---|---|---|
|
||||
| Raw Markdown to executable AST | Native explicit/prose defaults, source snapshots, parameter spans, inference and duplicate-parameter diagnostics | Prove the actual Rust classifier/parser and extraction rules; the older abstract grammar is not that proof |
|
||||
| Loaded module tree to flattened declarations | Independent inventories of source digests, module instances, lexical parents, class/method ownership and resolved bases | Connect the actual resolver to the Lean namespace lookup model, including failed/ambiguous resolution |
|
||||
| Effectful actual evaluation to parameter values | `FrontendCalls` proves interaction-program equality for arbitrary expression evaluators; native authored-order/unused-actual/builtin/foreign probes | Prove Rust scratch allocation, every expression case and its stack invariant against that combinator |
|
||||
| Default evaluation and invocation inputs | Native callee-scope, presence, receiver, entry/raw/metadata, inference, error-span and stateful-session cases | A complete default-binding semantics and universal compiler refinement, including errors and host context |
|
||||
| Module-qualified object dispatch | `ModularObjects` proves namespace flattening lookup, resolved-parent dispatch and safe descriptor round trips | Connect every real object constructor, resolver and copied descriptor to the model; justify Rust module-root lifetimes |
|
||||
| Machine integers | `MachineInts` exact signed-64 model, checked boundary implementation, independent Python and Lean consumers | Connect Rust checked arithmetic and every conversion to the mathematical evaluator; floats remain an extension |
|
||||
| Progressive contracts | Four real source boundary failures preserve codes, anchors and failure spans; valid contract execution | Universal contract-preservation theorem and imported declaration/call-site attribution |
|
||||
| Source-bound external calls | Two same-path declarations execute their separately selected source lines on both backends | Full external argument validation, effect-policy and environment-injection refinement |
|
||||
|
||||
The ledger deliberately does not turn a new model lemma, a finite passing
|
||||
corpus, or independent reconstruction into a complete frontend theorem. Those
|
||||
remaining proof links are required to discharge the full frontend objective.
|
||||
|
||||
## Default prologue proof and imported contract attribution (November 4)
|
||||
|
||||
`DefaultPrologue.default_prologue_refines` relates source default binding, which
|
||||
rechecks the current environment for omission, to a guarded block machine with
|
||||
an immutable initial presence mask. It proves whole interaction-program equality
|
||||
for arbitrary effectful evaluators, assuming distinct parameter slots and an
|
||||
initially faithful presence mask. Earlier default stores preserve that invariant
|
||||
for later parameters. The duplicate-slot counterexample issues two requests in
|
||||
the machine versus one in the source, demonstrating why slot uniqueness matters.
|
||||
Explicit None skips and immediate failure stopping are separately checked.
|
||||
This is a model of guard/evaluate/store blocks, not a proof of the Rust emitter,
|
||||
flat instruction stepping, actual expression compilation or parser.
|
||||
|
||||
The generated implementation family crosses all 27 omitted/int/None states for
|
||||
three parameters with all six declaration orders. An independent environment
|
||||
model checks 162 documents and 324 executions, including 34 faults when a default
|
||||
reads a later omitted parameter. Source text is reconstructed independently;
|
||||
expected traces are not derived from either backend. This finite family does
|
||||
not prove arbitrary defaults. Imported argument-contract diagnostics now retain
|
||||
the caller's failure span and source revision while pointing the declaration
|
||||
anchor and suggestion at the actual library. Supplied and defaulted invalid
|
||||
arguments both refuse before entering the callee body.
|
||||
|
||||
## Concrete name and flat-code interfaces
|
||||
|
||||
The compiler now borrows each original declaration and owning module while
|
||||
flattening. Bare-call selection uses the same source `lookup_local` operation
|
||||
as Tree, then maps the selected declaration identity to its flat index. This
|
||||
removes a second, subtly different lookup algorithm: repeated top-level names
|
||||
previously selected the first declaration in Tree but failed compilation in VM.
|
||||
It does not prove the source lookup operation itself.
|
||||
|
||||
`NameSlots` proves reads, writes and the complete named-argument binding fold
|
||||
commute with an injective local-name vector. Unknown names and repeated raw
|
||||
API names are covered; repeated raw names retain last-write semantics. A
|
||||
presence mask computed from initialized slots is faithful by construction.
|
||||
The Rust raw entry and argument binder now derive their mask from the actual
|
||||
initial logical slots. Method receiver aliases are overlaid only for default
|
||||
evaluation, and restored into the body frame after logical argument checks.
|
||||
`ReceiverDefaults` supplies the additional environment reasoning for explicitly
|
||||
declared self/自 parameters; the slot theorem alone does not cover that case.
|
||||
|
||||
Every compiled Program is structurally verified before return, and the VM
|
||||
verifies even publicly constructed/mutated Programs before any instruction.
|
||||
All current opcode variants are handled exhaustively. Checks include operand
|
||||
bounds, parameter/local prefix and injectivity, declaration and inheritance
|
||||
forests, call-layout and function references, spans, reachable stack underflow,
|
||||
branch/loop join heights and absence of leaked stack values on return. Missing
|
||||
variable values remain language faults; this checker does not prohibit them.
|
||||
|
||||
Rust exports the computed per-PC heights alongside the real emitted opcode
|
||||
text. `CheckFlatCertificate.lean` independently decodes that text and applies
|
||||
an executable checker whose soundness is proved in `FlatCertificate`. Accepted
|
||||
certificates preserve heights along every finite path and guarantee a valid
|
||||
fetch with sufficient operands on each reachable PC, including loop prefixes.
|
||||
The independent reader rejects unmodeled opcodes. Rust debug serialization and
|
||||
opcode-to-concrete-VM-step correspondence remain interfaces to justify; a
|
||||
structural certificate does not establish source/bytecode functional equality.
|
||||
|
||||
Neither this ordinary bytecode verification technique nor reuse of a resolver
|
||||
is an originality claim. Complete functional lowering, parser semantics and the
|
||||
Rust implementation correspondence remain open proof obligations.
|
||||
|
||||
## Functional expression checks and receiver views (November 4)
|
||||
|
||||
The emitter now records source-directed expression rules before emission, with
|
||||
child order and exact instruction intervals. The mandatory native verifier
|
||||
checks literal identity (including floating-point bits), local names, unary and
|
||||
binary operators, short-circuit targets, interpolation, collections, indexing
|
||||
and occlusion. Calls delegate staging and selection checks to `bytecode/call.rs`;
|
||||
resolution and dispatch semantics remain explicit boundaries.
|
||||
All seven statement forms have source-directed templates; a separate forest
|
||||
check covers the entire default prologue, statement body and implicit return.
|
||||
These checks detect stack-preserving semantic corruption, including Add to Sub,
|
||||
and refuse it before host effects. A forged source witness remains outside this
|
||||
check's guarantee; the recorder and actual AST correspondence need justification.
|
||||
|
||||
`ExpressionLowering` proves postfix expression compilation preserves complete
|
||||
interaction programs for arbitrary effectful leaves and operator interpretations,
|
||||
including faults and an arbitrary caller stack and continuation. `ShortCircuit`
|
||||
proves the exact absolute-PC AND/OR macros under arbitrary effectful child
|
||||
evaluation. `CheckExpressionLowering.lean` independently reads actual emitted
|
||||
operators, constants and local names, and applies the proved core checker.
|
||||
It counts call, collection, index and interpolation boundaries explicitly.
|
||||
Child inlining, Rust VM stepping, leaf interpretation and source-witness fidelity
|
||||
remain obligations; none of these results is whole-frontend functional refinement.
|
||||
|
||||
`ReceiverDefaults` proves that the source's separately maintained default
|
||||
environment equals the machine's receiver view after every successful prefix.
|
||||
The mask describes logical argument slots, while omitted self/自 defaults may
|
||||
replace the evaluation view. Supplied None remains present. The real receiver
|
||||
is restored before entering the body; argument contracts check both the logical
|
||||
arguments at the call site and the restored frame at the declaration, preserving
|
||||
source identity and diagnostic frames. The theorem composes this view invariant
|
||||
with `DefaultPrologue` for arbitrary effectful defaults and distinct slots.
|
||||
|
||||
Concrete repairs also share scalar/unary semantics across evaluators, stringify
|
||||
every interpolation part, allocate fresh loop temporaries, restrict dynamic
|
||||
calls to their defining module scope, and enforce the existing one-million
|
||||
truthy-iteration limit in VM as well as Tree. Regression evidence records each
|
||||
repair separately from proof claims. These compiler techniques are not new
|
||||
originality claims.
|
||||
|
||||
## Actual call staging and bounded control-flow macros
|
||||
|
||||
Every emitted call now has a separate source obligation captured before actuals
|
||||
are replaced with scratch reads. The checker covers authored actual order,
|
||||
evaluate/store/pop triples, source-local and loop-slot separation, nested-call
|
||||
scratch separation, argument reloads, layouts, builtin selection/defaults, host
|
||||
primitive identity, plugin name/pair ordering, method name/receiver and resolved
|
||||
user target/tag. Every call expression must have exactly one obligation. The
|
||||
reserved source-local prefix is established before any synthetic slots are
|
||||
allocated. Disjoint nested calls may reuse scratch slots after their lifetimes.
|
||||
|
||||
`CallStaging` proves the flat evaluate/save/pop program restores an arbitrary
|
||||
caller stack and has the same effects and failures as authored-order collection.
|
||||
It proves outside slots unchanged and unique staged slots read back the exact
|
||||
actual vector. The dispatch continuation is arbitrary and effectful, so binding,
|
||||
defaults and receiver effects can follow collection without commuting effects.
|
||||
`CheckCallStaging.lean` decodes real stores and reloads, applies the proved stage
|
||||
checker and independently checks the complete selection/dispatch template.
|
||||
Source-expression callback correspondence, name resolution and the semantics of
|
||||
each dispatch continuation remain proof interfaces. Host parameter metadata is
|
||||
an exported registry interface, not an independently verified registry theorem.
|
||||
|
||||
`WhileLowering` proves the condition/JF/check/body/backedge macro preserves the
|
||||
complete interaction program for a bounded loop, including a final false
|
||||
condition, condition/body faults, the truthy-iteration limit and early returns.
|
||||
It relates an increasing native counter to a decreasing model budget and proves
|
||||
admitted increments below one million fit u32. Model machine-step fuel is
|
||||
distinct from this language-visible iteration budget.
|
||||
`CheckStatementLowering.lean` checks actual default prologues, all seven statement
|
||||
templates, forests and implicit returns, including the exact while macro layout.
|
||||
The while theorem uses condition/body callbacks; concrete child inlining and the
|
||||
full Rust state machine are not discharged by checking those layouts. Branches
|
||||
and foreach currently have independent template evidence, not new functional
|
||||
refinement theorems. No ordinary compiler-checking technique is a novelty claim.
|
||||
|
||||
## Loaded executable AST and coherent witness corruption
|
||||
|
||||
`SourceFunction` now captures parameters, defaults, executable bodies and complete
|
||||
contract data directly from the loaded declaration before emission. The native
|
||||
source checker walks that snapshot separately from the rule recorder, checks
|
||||
ordered expression/statement correspondence and complete witness ownership,
|
||||
and accounts for the generated scratch reloads explicitly. It also compares
|
||||
full contracts with structural Rust equality, including types, nullable fields,
|
||||
descriptions, source lines and declaration quotes. Contract presence alone would
|
||||
not detect a Number-to-Any weakening.
|
||||
|
||||
The evidence exports the executable AST separately from the original module and
|
||||
from the compiled snapshot. `CheckSourceWitness.lean` matches declaration
|
||||
identities and applies `SourceWitness`'s proved ordered-tree reconstruction
|
||||
checker. Interpolation parts, index labels, code payloads and formula structure
|
||||
are retained; all formula floats and matrix entries retain their exact bits.
|
||||
The old Debug formula text was insufficient for NaN payload identity. Inert
|
||||
occlusion prose and pre-inference parser metadata are not execution-tree nodes.
|
||||
|
||||
Ten native coordinated-corruption cases change code together with its witness,
|
||||
including operators, constants, variables, assignments, callees, NaN payloads,
|
||||
index keys, interpolation, contract metadata and an orphan expression record.
|
||||
Eight independent source-witness negatives include changing the compiled snapshot
|
||||
as well. A coordinated wrong operator is a positive acceptance control for all
|
||||
four earlier independent consumers and a rejection control for the AST checker.
|
||||
This distinguishes trusted source correspondence from agreement among emitted
|
||||
metadata fields.
|
||||
|
||||
The theorem proves exact correspondence of the supplied executable trees, hence
|
||||
preservation under any interpretation of those trees. The native and JSON AST
|
||||
adapters, normalization helpers and snapshot capture remain trusted interfaces.
|
||||
No theorem here verifies the actual Markdown classifier/parser/inference or
|
||||
connects every concrete Rust operation to the semantic models. A caller who
|
||||
changes both the reference AST and its program has supplied a different
|
||||
translation-validation input; this is not source authentication.
|
||||
|
||||
## Runtime argument-preparation faults
|
||||
|
||||
The expanded AST audit exposed a concrete acceptance mismatch: Tree can execute
|
||||
main while an unused function contains a conflicting bracket modifier, whereas
|
||||
VM compilation previously rejected the entire module. Modifier preparation now
|
||||
lowers its failure to `RejectArgumentExpansion` before actual evaluation. A
|
||||
provided default parameter, including explicit None, skips that fault; reaching
|
||||
it preserves prior output and stops before actual effects or a suffix. The
|
||||
error's message, span, source revision and diagnostic frames match Tree.
|
||||
|
||||
`CallExpr::for_evaluation` normalizes bare aliases before modifier expansion,
|
||||
matching Tree's existing order. The expression checker validates an effect-free
|
||||
fault leaf and the independent decoder handles its actual terminal opcode.
|
||||
The AST adapter explicitly represents that executable fault without children;
|
||||
unexecuted actual expressions are not falsely counted as evaluated code.
|
||||
Two independent fault-opcode/message negatives and a positive AST-identity-only
|
||||
control keep representation checking distinct from instruction interpretation.
|
||||
|
||||
The independent Python oracle now compares JSON values with exact recursive
|
||||
types and requires integer arithmetic inputs to be actual integers. Python's
|
||||
True==1 and 1==1.0 equalities must not erase language-visible value distinctions.
|
||||
Four type-corruption controls are added. These improvements do not discharge
|
||||
other call-error timing, parser, resolver, dispatch or Rust-step proof obligations.
|
||||
|
||||
## Native binding and declaration graph validation
|
||||
|
||||
Builtins, host primitives and plugins retain authored labels in native bytecode.
|
||||
The shared value-independent binding plan selects named parameters before
|
||||
positionals, preserves omitted optional bindings and unknown named extras, and
|
||||
reports duplicate, missing and surplus positional arguments after actual effects.
|
||||
Plugin lookup precedes signature binding. Eighteen reached/unreached error cases
|
||||
check explicit expected output, messages, spans, source revisions and frames.
|
||||
A registered C ABI echo probe checks mixed and extra named arguments. Execution
|
||||
uses the native VM and plugin bridge throughout.
|
||||
|
||||
The source and flat declaration views share ordered resolution. A loaded snapshot
|
||||
captures ordinal declaration paths, levels, child/root counts, imports and ordered
|
||||
use aliases before emission. Verification checks identity, parent/child/root order,
|
||||
module scopes and object/method names, then derives call targets independently of
|
||||
emitted target records. Two-component paths check runtime receiver presence before
|
||||
static fallback; an unbound reserved slot differs from a supplied None. Imports
|
||||
retain priority. Resolution failures are native terminal instructions after actuals.
|
||||
|
||||
`NameResolution` proves first-match, path and lexical commutation under an
|
||||
ordered embedding. Its rank checker proves sufficient depth and connects a
|
||||
well-founded total source policy to flat lookup. Rust uses the same parent-chain
|
||||
policy; parent-view extraction remains a trusted adapter. The finite checkers consume actual AST/flat evidence in
|
||||
`CheckNameResolution.lean`. Nine native corruptions and seven independent graph
|
||||
negatives test this boundary. A coordinated wrong target remains a positive control
|
||||
for the older stack, staging and AST-shape consumers. Ordinary compiler correctness
|
||||
ingredients are not novelty claims. Snapshot/JSON adapters, primitive registries,
|
||||
parent-view extraction and concrete Rust
|
||||
instruction refinement remain explicit obligations; universal frontend verification
|
||||
and overall paper readiness are not established by these results.
|
||||
|
||||
`ArgumentBinding` separately models per-parameter omission permission and proves
|
||||
value substitution preserves selections and faults. A successful index plan has
|
||||
a finite-index witness. `CheckArgumentBinding.lean` checks actual static call
|
||||
plans and an independently enumerated mask/label corpus. User VM calls now use
|
||||
the shared planner with the callee default mask, correcting their surplus-count
|
||||
diagnostic and preserving missing-required-before-default priority. Default
|
||||
evaluation, contracts, dynamic signature selection and concrete Rust/JSON steps
|
||||
remain separate interfaces. The mathematical planner is not a proof of the
|
||||
entire native binding implementation.
|
||||
@@ -1,5 +1,7 @@
|
||||
# 标准库 / 扩展库:代码即文档
|
||||
|
||||
当前可执行开发规范见[库开发指南](../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. 波次
|
||||
|
||||
|
||||
@@ -1,5 +1,35 @@
|
||||
# 文档会话(View Cells)
|
||||
|
||||
## 2026-11-02:并发控制与完整历史 v5
|
||||
|
||||
以下为当前实现;后文保留首版设计与当时的状态表。
|
||||
|
||||
- HTTP `kernel/interrupt` 查找已存在的会话,经独立控制器发送请求,不等待单元执行锁或其他文档的初始化。未打开、尚在初始化的会话返回错误,不启动新内核。已加载文档的源码文件被删除后仍可取消正在执行的单元。
|
||||
- 内核的中断能力绑定其持有的子进程,并在回收前撤销;旧能力不能指向后来启动的内核。引导阶段的取消被暂存,收到 ready 后投递。逻辑取消输入会合并重复信号;投递错误明确返回。Windows 尚无对应的保状态中断实现。
|
||||
- 取消使 Run All 在当前单元结束后停止,返回实际 `ran`、`remaining` 和 `cancelled`;不会继续运行后续单元。内核没有退出时,取消前已发生的状态修改保留。close 撤销 API 会话,重新打开不会激活旧引用。
|
||||
- 完整历史 v5 将并发取消作为所在操作的 `controls` 输入记录:操作起点之后的微秒偏移及各内核的真实接收结果。严格回放按输入重新投递并重新观察回执;操作先结束时撤销剩余定时请求,不能流入下一操作。实际回执或观察不匹配就报告差异。v4 无控制输入的历史仍可检查;v4 中出现 controls 字段会被拒绝。
|
||||
- 严格检查先完成纯验证,再启动回放内核。实际执行中,每次协议请求必须先与预期请求一致;实际回复和每个单元的观察、批次结果也立即比较。首个差异后停止依赖后缀,包括同一个 Run All 内的后续单元。未执行的观察标记 `compared=false`,不冒充已比较的第二个差异。
|
||||
|
||||
快照导出支持可选 `compact:true`。默认仍为完整 JSON;紧凑格式
|
||||
`marqdo.history.dag` v1 对相同子值做自底向上共享,整数使用十进制文本、
|
||||
浮点数保存 IEEE 位模式,保留映射顺序和全部历史字段。导入和严格回放会自动
|
||||
识别格式。SHA-256 校验只检测内容一致性,不提供来源认证。
|
||||
解码要求规范节点、向后引用、全部可达和唯一键,并在展开前检查最多
|
||||
1,000,000 个节点、8,000,000 个展开值、512 MiB 保守展开预算、128 层深度;
|
||||
展开后再次检查安全值域。此格式减少导出字节数,尚未减少录制时内存,也不保证更快。
|
||||
|
||||
实际取消实验覆盖 Unix 上同步 Python/Node 持久会话;不能推导任意外部代码均有界停止。
|
||||
[Python 3.14 信号文档](https://docs.python.org/3.14/library/signal.html#execution-of-python-signal-handlers)
|
||||
说明纯 C 计算可延迟信号处理;
|
||||
[Node 22.22.1 vm 文档](https://nodejs.org/download/release/v22.22.1/docs/api/vm.html#timeout-interactions-with-asynchronous-tasks-and-promises)
|
||||
说明异步任务可能逃出同步求值的中断范围。完整源码 elaboration、控制适配器、
|
||||
真实时钟与信号调度到形式模型的 refinement 仍需完成,不能以这些测试代替。
|
||||
|
||||
相关实现:`foreign_session/control.rs`、`foreign_doc/control.rs`、
|
||||
`foreign_doc/packing.rs`、`foreign_doc/replay.rs` 与 `view/notebook_api.rs`。
|
||||
真实 TCP/HTTP 取消、逐单元副作用屏障和独立快照消费记录位于论文
|
||||
`PLDI/experiments/reviewer-v5/`。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **D1–D3 首版已实现;D4/D5 待做** |
|
||||
|
||||
@@ -0,0 +1,131 @@
|
||||
# Document oracle observations and strict replay
|
||||
|
||||
`foreign.oracle_journal` returns a copy of this evaluation's observations as
|
||||
ordinary `index/channel/value` records. Successful admitted `session_eval`,
|
||||
`session_get`, and document `json.parse` operations append `eval`, `get`, and
|
||||
`decode`, respectively. Set/open/close do not append. An observation is
|
||||
validated recursively before append; handles and code objects cannot enter.
|
||||
Each new HostContext starts with an empty observation list.
|
||||
|
||||
`foreign.replay_check expected=J observed=J2` is a pure comparison, with no
|
||||
foreign execution. It validates contiguous zero-based indices, channel tags
|
||||
and crossing-domain membership. Records compare structurally by field name,
|
||||
independent of field order. The result contains `ok`, the least mismatching
|
||||
`index`, and both records (None for a missing entry). Two empty journals
|
||||
match. Failure to provide a valid journal is an error, not a match.
|
||||
|
||||
The interactive `DocumentSession::replay_check(snapshot)` is a different layer:
|
||||
it executes a recorded trace from fresh state. Version-2 snapshots contain the
|
||||
full chronological oracle trace, recorded stdin per step, its declared count,
|
||||
the plan and source identity. Preflight validates every step before any foreign
|
||||
execution. Every step is compared; none is skipped. Repeated cell executions
|
||||
are distinct observations. Execution timing logs and cell display summaries
|
||||
are not comparison inputs. Matching input values in a supplied snapshot is
|
||||
consistency checking, not cryptographic authentication of the recording.
|
||||
|
||||
Snapshots carry the SHA-256 of the loaded document text. Import checks it
|
||||
before restoring foreign bindings, and preflights all crossing payloads before
|
||||
mutation. Reload retains prior oracle observations with their original source
|
||||
hashes, so a later checker can reject an incompatible trace.
|
||||
|
||||
Lean: DocCalc's independent `runForeignLive` cursor simulates `runForeignAcc`
|
||||
for arbitrary prefixes, observation accumulators and code sequences, including
|
||||
oracle failures. `ForeignTrace` composes the registry's open/eval/close
|
||||
judgments using independent normative and interactive execution control;
|
||||
`trace_simulation`, `trace_correspondence`, and `trace_replay` quantify arbitrary
|
||||
multisession action sequences, also when a run faults. These supplement the
|
||||
existing theorems without removing them.
|
||||
|
||||
Tests: `tests/oracle_journal.rs` runs the public document API on both evaluators;
|
||||
`host::oracle::tests` covers journal equality and length localization;
|
||||
`host::foreign_doc::tests` covers the live trace preflight and actual replay;
|
||||
`host::foreign_session::tests` includes generated two-session model checks and
|
||||
Python/Node boundary and process-failure experiments. The research runner is
|
||||
`MarqdoThesis/PLDI/experiments/reviewer-v5/run.py`.
|
||||
|
||||
## Stateful requests and semantic projection
|
||||
|
||||
`HostContext.foreign_protocol_steps` records internal request attempts and
|
||||
replies, including set values, copied eval input and raw stdin. It is separate
|
||||
from the admitted language journal: rejected inbound responses belong to the
|
||||
protocol evidence, while only admitted values belong to the oracle journal.
|
||||
An input refused before send produces no protocol request. A response refused
|
||||
after execution does not undo kernel effects; the post-state is retained.
|
||||
|
||||
Language observations are recorded at the document API boundary and by live
|
||||
cell evaluation. Low-level get/names used during snapshot export do not append
|
||||
language observations. A successful eval projects to its result. A failed eval
|
||||
projects to a record of stable status, output and diagnostics. Process timing,
|
||||
commands and handles are not semantic values. The exact source path allocated
|
||||
for one-shot execution is alpha-renamed only in diagnostic fields; raw stderr
|
||||
and stdout remain available unchanged, and ordinary paths/error differences
|
||||
are still compared. Live oracle records carry this same projected `value`.
|
||||
|
||||
Python/Node replies mark serialization-domain failure with `domain_error`.
|
||||
Error text is not used to infer this flag. Python refuses non-string object
|
||||
keys; Node sanitizes objects with a null prototype to preserve special keys.
|
||||
The common strict JSON decoder checks duplicate keys before materializing a
|
||||
map, rather than losing them through overwrite.
|
||||
|
||||
`ForeignState.lean` refines the earlier eval-only fragment with opaque kernel
|
||||
state, complete request histories, set/get/eval input/decode, monotonic handle
|
||||
allocation and fault outcomes carrying the admitted prefix. An adaptive
|
||||
Program has continuations on actual observations; its correspondence theorem
|
||||
covers data-dependent next actions, not just a fixed schedule. Mapping actual
|
||||
document elaboration and host bindings to this program is a further proof
|
||||
obligation recorded in the research status file.
|
||||
|
||||
## Complete history, snapshot version 4 (2026-11-02)
|
||||
|
||||
Strict interactive replay now records operations, not just successful cells.
|
||||
Each public execution/mutation boundary records typed arguments, success or
|
||||
failure, admitted observations, cell-oracle records, and stable resulting
|
||||
state. Nested implementation calls are grouped under the user's operation.
|
||||
The history includes set/get, run/step/run-all, restart, reload, plan edits,
|
||||
clear, snapshot inspection and imported values. Failed attempts remain in the
|
||||
history; rejected handles and secrets have only non-capability/redacted tags.
|
||||
Clearing display outputs cannot erase the history's oracle projection.
|
||||
|
||||
The snapshot stores the materialized initial plan and historical reload plans.
|
||||
Entry text is parsed at its original path, retaining relative imports without
|
||||
rewriting the user's document. Initial bindings are reapplied when a kernel is
|
||||
reopened; unchanged reload kernels retain state, whereas changed language or
|
||||
command retires the incompatible process. Loaded source/metadata and cached
|
||||
cell outputs are updated consistently.
|
||||
|
||||
Preflight checks the entire operation stream, all source revisions, plan edits,
|
||||
binding/cursor/generation transitions, and oracle projections before starting
|
||||
any replay kernel. Executing the trace compares each result, admitted value,
|
||||
cell result and stable state. The first mismatch stops its dependent suffix;
|
||||
`executed_actions` and `remaining_actions` make this explicit. `matched` counts
|
||||
admitted observations and `matched_actions` counts operations. No missing
|
||||
record is silently accepted or skipped.
|
||||
|
||||
The HTTP replay-check endpoint performs an isolated comparison and retains an
|
||||
existing warm session. It validates malformed input before starting even a
|
||||
seed kernel; duplicate JSON fields are refused before overwrite. Verification
|
||||
can still run recorded foreign work and its external effects: isolation is of
|
||||
the document session, not a process sandbox. `replay_snapshot` remains the
|
||||
separate legacy cell re-run API and makes no strict-history comparison claim.
|
||||
Older version-2/3 snapshots may be used by legacy restoration/re-run surfaces;
|
||||
they cannot prove a complete action history and strict checking requires v4.
|
||||
|
||||
`ForeignHistory.lean` models explicit command boundaries. A fault terminates
|
||||
its command, a later command receives the actual retained registry, and the
|
||||
history retains all command faults and admitted observations. It proves
|
||||
command-history correspondence, journal membership and no alias resurrection
|
||||
through arbitrary recovery histories. This extends the adaptive Program
|
||||
results; the general source-elaboration refinement is a separate outstanding
|
||||
proof obligation.
|
||||
|
||||
Experiment source inputs are frozen before running, checked again afterward,
|
||||
and archived with their hashes. The current passing bundle is identified by
|
||||
`MarqdoThesis/PLDI/experiments/reviewer-v5/LATEST-PASSING.json`.
|
||||
|
||||
Each operation also retains its internal protocol attempts/replies, including
|
||||
refused inspection results. Those records are compared even when an inspector
|
||||
could not return a value. They are control evidence and do not admit rejected
|
||||
payloads into the language journal. An explicit document session_names request
|
||||
adds its admitted array on the decode channel; internal names/get probes do not.
|
||||
Reload records either a historical source/plan input or its input-read error;
|
||||
replay consumes that captured version input and does not rewrite past files.
|
||||
@@ -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) |
|
||||
|
||||
@@ -24,17 +24,29 @@ MAX_SAFE = 9007199254740991 # 2^53 - 1
|
||||
| `array` | `List` |
|
||||
| `object` | `Map` |
|
||||
|
||||
**Host extension (not in Lean `SafeVal`):** JSON non-integer numbers → `Value::Num(f64)` (NaN/Inf encode as `null`). Floats are documented host behavior; they are **not** claimed as mechanized \(V_{\mathsf{safe}}\) fidelity.
|
||||
**Host extension (not in Lean `SafeVal`):** JSON non-integer numbers → `Value::Num(f64)`. Non-finite numbers (NaN/Inf) are refused on encode and in Python/Node oracle responses, including nested payloads. Floats are documented host behavior; they are **not** claimed as mechanized \(V_{\mathsf{safe}}\) fidelity.
|
||||
|
||||
## Encode (`value_to_json`)
|
||||
|
||||
- `Value::Int(n)` with `|n| ≤ MAX_SAFE` → JSON number.
|
||||
- `Value::Int(n)` with `|n| > MAX_SAFE` → **refuse** (error).
|
||||
- `Value::Handle(_)` → **refuse** (`json: session handle cannot be serialized`).
|
||||
- Column-table `Map` whose fields are all `List` with **unequal lengths** →
|
||||
**refuse** (`json: table column arity mismatch`).
|
||||
- Nested `List` / `Map`: any child refuse fails the whole tree.
|
||||
- GFM table **parse** also refuses unequal row width
|
||||
(`table row arity mismatch`) before a value is built.
|
||||
- Wide integers that must cross a language boundary: author converts to a
|
||||
**decimal string** (∈ \(V_{\mathsf{safe}}\)); the foreign program may use
|
||||
`BigInt` / Python `int` on that string.
|
||||
|
||||
## Foreign oracle (`session_eval` / `session_get`)
|
||||
|
||||
Python/Node session bootstraps sanitize results with the same integer gate
|
||||
before JSON emission. An Ω response containing an OOD integer is a **fault**
|
||||
(host `Err`), not a soft `ok:false` cell record. Stdout text that authors
|
||||
`json.parse` themselves is still gated by host `json_to_value`.
|
||||
|
||||
## Decode (`json_to_value`)
|
||||
|
||||
- JSON integer with `|n| ≤ MAX_SAFE` → `Int`.
|
||||
@@ -64,3 +76,15 @@ json: integer outside V_safe (±(2^53-1)): <n>
|
||||
- Not automatic BigInt promotion inside Node/Python bootstraps.
|
||||
- Document-level `Value::Int` may still hold i64 values that are OOD for JSON;
|
||||
the gate fires when those values enter JSON encode/decode.
|
||||
|
||||
## Strict request boundary update
|
||||
|
||||
The numeric gate applies to the represented value, including integer-valued
|
||||
floats and exponent notation. `9007199254740992.0` and
|
||||
`9.007199254740992e15` are refused; fractions such as `1.5` remain in the host
|
||||
extension. `serde_json` uses `float_roundtrip` to avoid endpoint decoding loss.
|
||||
The strict text decoder rejects duplicate object keys and unequal column maps
|
||||
before information is lost. One-shot, call_many and persistent input paths
|
||||
use recursive domain admission; code, handle and secret values are not copied
|
||||
implicitly. Auto-detection may leave non-JSON output as text, but valid JSON
|
||||
outside the domain is a refusal, including in batch results.
|
||||
@@ -16,17 +16,22 @@
|
||||
|
||||
| AST / 概念 | View 优先显示 | 备注 |
|
||||
|------------|---------------|------|
|
||||
| `Expr::Index` | `[键](基)` | 嵌套 `[k2]([k1](base))` |
|
||||
| `InterpPart::Index` | 同上嵌套链接形 | 不再默认 `` `base`[^k] `` |
|
||||
| `Expr::Occluded` | 正文只读动作说明,实际实现进入侧注 | 每个片段独立关联,不把整句改成一次赋值 |
|
||||
| 空遮蔽 `()` | 待补充实际逻辑 | 当前空遮蔽返回 None,不伪装成已接通工具 |
|
||||
| `Expr::Index` / `InterpPart::Index` | 保留经典或脚注取元的兼容说明 | 当前作者程序优先用 access 读取集合;默认链接形是遮蔽 |
|
||||
| `CallExpr` + `bracket_marked` / `pre_modifiers` | `修饰 [callee] 实参…` 或 `[callee] 实参…` | 仅经典 `>` 解析时仍显示 `> callee …` |
|
||||
| 赋值 / 返回 | 粗体 / 斜体语义即可 | 不强制还原整句叙述 |
|
||||
| foreach | `- [项](集合)` | 不变 |
|
||||
| 赋值 / 返回 | 保留原叙述句子,在真实执行片段上标明语句或返回 | 普通链接与字面量不冒充执行遮蔽 |
|
||||
| foreach | `- [动作](遍历 集合 为 项)` | 正文显示动作,控制逻辑见侧注;迭代选择器只切换已有运行记录 |
|
||||
|
||||
## 3. 非目标
|
||||
|
||||
- 不把 view 做成第二语法;解析真相仍在 mapping / call-arguments。
|
||||
- 不删除对脚注取元、旧 `>` 调用的兼容显示需求时,可用次要提示,但默认推荐面优先。
|
||||
|
||||
当前阅读器的实现与验收见 [view-readable-actions.md](view-readable-actions.md)。
|
||||
可执行知识先展示输入、返回、调用边界、依赖和各项依据;摘要和机器身份按需展开。
|
||||
源码说明与运行标注分开,展开侧注或知识卡片不会执行代码。
|
||||
|
||||
## 4. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
# View:动作留在正文,逻辑留在侧注
|
||||
|
||||
本轮针对阅读界面,不改变语言求值和工具权限。阅读示例为
|
||||
[view-reading.mq.md](../../examples/view-reading.mq.md)。
|
||||
|
||||
遮蔽按真实 AST 识别,随后按源片段保留句子:方括号的动作说明留在正文,圆括号中的
|
||||
实现进入独立侧注。同一句话可以包含多个调用和返回,不再把整行当成一次赋值。
|
||||
文字字面量中的链接、普通 Markdown 导航与 classic 取元不冒充执行遮蔽。
|
||||
空圆括号明确显示“待补充实际逻辑”,并说明当前空遮蔽返回 None。
|
||||
|
||||
宽屏实现侧注与运行标注共用现有的左右避碰及引出线布局,彼此有明确名称区分。
|
||||
实现侧注标记“源码说明 · 不是运行结果”,不带调用帧或迭代帧身份。
|
||||
密集区域、窄屏和无脚本页面使用可原生展开的 details;动作按钮可按需查看完整逻辑。
|
||||
悬停与键盘聚焦关联实际源片段,不触发运行。
|
||||
|
||||
“怎样读这份可执行文档”沿用核心构造注册表,说明参数、赋值、返回、调用、条件、
|
||||
循环、数据表、代码块、公式、写回与兼容标记。公式和外语代码仍使用既有卡片,
|
||||
不新增语法或作者必填的展示配置。
|
||||
|
||||
可执行知识按真实源单元分组。默认先读输入、返回、调用边界、依赖和验证依据,
|
||||
身份、摘要与原始状态收进技术详情。契约说明来自已解析的参数和返回表;缺失时如实说明。
|
||||
语法检查、契约检查、测试、来源和领域审阅分别展示,静态分析不代表实际执行或内容正确。
|
||||
源码结构步骤与实际运行时序分开;内存面板先展示最终绑定与调用记录,再按需展开原始报告。
|
||||
|
||||
函数的说明链接和知识卡片使用当前文档源行定位,避免同名方法共用一个 DOM 身份。
|
||||
单文件阅读只分析它和实际导入的依赖,避免无关同目录模块重名导致知识区整体失败。
|
||||
目录阅读保留项目分析。来源身份及版本匹配沿用现有编译器和页面 token,不另建求值器。
|
||||
|
||||
验收入口:
|
||||
|
||||
```sh
|
||||
cargo test --offline --lib view::
|
||||
cargo test --offline --test view_readability
|
||||
cargo test --offline --test gold view_
|
||||
cargo test --offline --test executable_knowledge
|
||||
marqdo view output examples/view-reading.mq.md --no-exec --out /tmp/marqdo-reading
|
||||
```
|
||||
|
||||
浏览器验收脚本是 [readability.browser.cjs](../../tests/view/readability.browser.cjs),
|
||||
接收真实页面 URL,支持 MARQDO_PLAYWRIGHT_MODULE、MARQDO_CHROMIUM 和 MARQDO_SCREENSHOT_DIR。
|
||||
覆盖七种宽度、侧注边界与碰撞、多动作句子、空逻辑、知识卡片、正文定位和无脚本回退。
|
||||
原有 [reader.browser.cjs](../../tests/view/reader.browser.cjs)继续覆盖曲线、帧选择及实时/静态交互。
|
||||
|
||||
本轮实际验收(2026-11-08):67 项 view 相关单元测试、2 项新增只读导出测试通过;
|
||||
全量回归 984 通过、0 失败、2 个原有忽略项。真实 Chromium 验证静态快照、
|
||||
只读导出和实时页面,覆盖七种宽度、无脚本阅读、曲线与帧切换、源码定位及实时重新运行。
|
||||
GOFLAGS 仅对完整回归命令关闭工作区所有权引起的 Go VCS 盖章失败,不改全局配置。
|
||||
@@ -0,0 +1,64 @@
|
||||
# View botanical reader
|
||||
|
||||
Implemented 2026-11-07 for the shared `marqdo view` and `marqdo view output` shell.
|
||||
|
||||
The default is warm paper, serif document text, olive runtime notes, gold accents,
|
||||
and generated transparent blossom/feather ornaments. The M/book logo is embedded
|
||||
SVG. Navigation and the floating toolbar are code-native SVG icons and CSS.
|
||||
|
||||
`src/view/reader.css` is the final theme layer after notebook component styles;
|
||||
`src/view/reader.js` owns reader navigation, dialogs and annotation geometry.
|
||||
Notebook APIs and controls remain available through More → advanced tools.
|
||||
Welcome files get a larger introduction; ordinary files retain compact titles.
|
||||
|
||||
## Runtime notes
|
||||
|
||||
Annotations keep their existing owner band, stable IDs, source anchor, call frame
|
||||
and loop iteration data. Chips serialize source line and byte spans so another
|
||||
call/iteration frame can find the same source mark without guessing by kind.
|
||||
On viewports wider than 1000px with 180px available on each side, notes use both
|
||||
page margins, varying horizontal reach and vertical offset with collision
|
||||
avoidance. Dense bands that would drift more than 170px retain inline notes.
|
||||
Compact screens, printing, and expanded overflow bands use ordinary document
|
||||
flow. A shared SVG overlay draws continuously curved connections from the actual
|
||||
mark's source-facing lower edge to the annotation title. The default is a full
|
||||
S-curve with restrained gold/olive gradient; candidate sweeps are checked against
|
||||
visible source text and already drawn connections. Tight prose uses two joined
|
||||
curves below the text baseline and through the free margin, with no straight rail.
|
||||
Notes sit closer to the document with varying horizontal/vertical offsets, rather
|
||||
than stretching every connector across the entire page. Wrapped source marks use
|
||||
their actual line fragments. Hover/focus highlights the exact source and connector.
|
||||
Unresolved source anchors retain inline results instead of inventing a connection.
|
||||
Clicking a note shows its full captured detail. No explanatory prose or runtime
|
||||
values are invented.
|
||||
|
||||
Layout updates after window/font/structure resize, frame selection and live DOM
|
||||
replacement. Static HTML includes the same code and embedded assets. All KaTeX
|
||||
scripts, CSS and fonts are bundled for offline math. Optional syntax highlighting
|
||||
retains the previous CDN progressive enhancement; code remains readable offline.
|
||||
|
||||
`api/session/run_document` now returns prose HTML, bindings and trace JSON from
|
||||
its own capture. The reader applies that capture without rerunning the program.
|
||||
Page tokens prevent a changed source from receiving mismatched annotations.
|
||||
|
||||
## Navigation
|
||||
|
||||
Document returns to prose. Functions/Variables move the real existing panels into
|
||||
a modal and restore them on close, preserving their existing event handlers.
|
||||
Memory shows the captured execution report, labeled as a snapshot on exports.
|
||||
Run navigates to the output section. Search finds document, function and file text.
|
||||
The floating toolbar labels its icons 刷新 / 设置 / 运行 / 清理 / 更多.
|
||||
The bottom play button invokes actual live execution; static pages explain how to
|
||||
start a live view. Static clear hides captured output locally; reload restores it.
|
||||
Settings control light/dark theme, text size and annotation visibility. More keeps
|
||||
source, advanced execution controls, file navigation and print within reach.
|
||||
|
||||
## Validation
|
||||
|
||||
Run `cargo test --offline --lib view::` and `cargo test --offline --test gold view_`.
|
||||
The browser regression is `tests/view/reader.browser.cjs <URL>`; it accepts
|
||||
`MARQDO_PLAYWRIGHT_MODULE`, `MARQDO_CHROMIUM`, and optional
|
||||
`MARQDO_SCREENSHOT_DIR`. It blocks HTTPS resources to exercise offline reading,
|
||||
checks seven viewport widths, note bounds/collisions, source/label curve endpoints, visible curvature and non-crossing paths,
|
||||
shared-source frame binding, stable redraw, real panel restoration,
|
||||
search, frame selection, note inspection and live/static run behavior.
|
||||
@@ -0,0 +1,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.2.2
|
||||
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。
|
||||
|
||||
使用此资源执行带历史消息的聊天请求,并保留公开实现的返回形态。
|
||||
|
||||
完成后返回*[调用 运行](自.运行(提示=`提示`, 流式=`流式`, 打印增量=`打印增量`))*。
|
||||
Loaded 100 of 418 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user