Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
db27f5c8d3 | ||
|
|
106e1d5136 | ||
|
|
d269ccb7e7 | ||
|
|
505d478724 | ||
|
|
b842644686 | ||
|
|
60d570756f | ||
|
|
eea6fe1a0e | ||
|
|
25b7be6739 | ||
|
|
91d51f3f0a | ||
|
|
ff6425e6c5 | ||
|
|
e853b00fe2 | ||
|
|
4a7a33e29a | ||
|
|
25b6b86c26 | ||
|
|
e4be0b0492 | ||
|
|
db6158e9e2 | ||
|
|
a0c56fa352 | ||
|
|
c181b74a88 | ||
|
|
02b3dfab48 | ||
|
|
b09538d242 | ||
|
|
0dcd9e3d03 | ||
|
|
897db76aa7 | ||
|
|
ee019fb1c2 | ||
|
|
9599303c4c | ||
|
|
8041a2274c | ||
|
|
ab8ea8438f | ||
|
|
f240bdf156 | ||
|
|
ff84c43c10 | ||
|
|
dbb2765553 | ||
|
|
7e3b193d49 | ||
|
|
2a9fceb51c | ||
|
|
d1ddb74235 | ||
|
|
b6bb42e460 | ||
|
|
5456d9ff83 | ||
|
|
a23fdedfa2 | ||
|
|
3463628165 | ||
|
|
d1b33c78c6 | ||
|
|
fbece725e1 | ||
|
|
1f23e2ed93 | ||
|
|
99132ac8fc | ||
|
|
118448538c |
No files matched your search
@@ -20,29 +20,32 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
|
||||
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
|
||||
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Identifiers use backticks** — params `` + `name` ``, bindings `` `x` ``, foreach `` [`item`](`coll`) ``. **Complex text** uses `"..."` with escapes; bare tokens stay literal (no `\n` magic).
|
||||
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are variables (strings need `"…"` / `'…'`; ticks still ok).
|
||||
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
7. **Paths in bare expressions:** `/` is division. Prefer `` `path` `` vars, same-dir names, or call args — not raw `a/b` in expressions.
|
||||
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed.
|
||||
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
|
||||
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
| `#` | **Object / type** (constructor body). `# main` = entry object. |
|
||||
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
|
||||
| `##` … `######` | **Function / method** (nesting by heading depth). |
|
||||
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
|
||||
| `1.` `2.` … in body | Branch arm (condition or `N. *` else) |
|
||||
| `- …` inside body | Loop (`while` or `` [`item`](`coll`) ``) |
|
||||
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
|
||||
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `> path.mq.md` | Import |
|
||||
| Frontmatter `> path.mq.md` [`as` / `作为` name] | Import (binds library name) |
|
||||
| Frontmatter `> use lib.member` [`as` name] / `使用` | Bind short name to a library path |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `*…*` | Statement (bind / expr) |
|
||||
| `**…**` | Return value |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` in function body | End function body (no value) |
|
||||
| GFM table after empty RHS bind | Collection |
|
||||
| GFM table after empty RHS bind | Collection (1-col list / ≥2-col map / `@`·`行`·`row` → list of maps); `` `x`[^1] `` / `` `m`[^key] `` |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
|
||||
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
|
||||
| Unmarked prose | Comment |
|
||||
@@ -109,22 +112,29 @@ Chinese builtins (same functions, no import):
|
||||
|
||||
## Frontmatter imports + stdlib
|
||||
|
||||
Imports bind a **library name** (default = file stem; optional `as` / `作为`). Members are **not** flattened into the caller. Call with a bare dotted path:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: example
|
||||
> lib/text.mq.md
|
||||
> lib/time.mq.md as clock
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`xs` = > split value=a,b,c sep=,*
|
||||
*`xs` = > text.split value=a,b,c sep=,*
|
||||
> print text=`xs`
|
||||
*`t` = > clock.now_unix *
|
||||
```
|
||||
|
||||
- Import **English** or **Chinese** library file; call that file’s API names (do not mix).
|
||||
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
|
||||
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
|
||||
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm` / `add agent` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — agent framework (layout + ABI; compose LLM per `doc/design/ext-agent.md`).
|
||||
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm` / `add agent` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — document-driven agents: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)).
|
||||
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
|
||||
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
|
||||
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
Stdlib map: [reference.md](reference.md).
|
||||
@@ -146,7 +156,8 @@ Stdlib map: [reference.md](reference.md).
|
||||
| `if x > 0:` | `1. `x` > 0` |
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
|
||||
| Import `lib/text` then call `拆分` | Match file language |
|
||||
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
|
||||
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
|
||||
|
||||
## Checklist before finishing
|
||||
|
||||
|
||||
@@ -69,14 +69,46 @@ Greeting via a nested function:
|
||||
# main
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
|
||||
- [`果`](`篮子`)
|
||||
- [果](篮子)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
## 6b. Map table + footnote get
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`分类` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 水果 | 蔬菜 |
|
||||
|
||||
*`种` = 分类[^苹果] *
|
||||
> print text=`种`
|
||||
|
||||
*`第一` = 篮子[^1] *
|
||||
```
|
||||
|
||||
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):
|
||||
|
||||
```markdown
|
||||
`订单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
|
||||
*`名` = `订单`[^1][^品名] *
|
||||
```
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
@@ -123,6 +155,37 @@ description: loads math
|
||||
|
||||
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
|
||||
|
||||
```markdown
|
||||
# Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*`msg` = "Hello, `who`!" *
|
||||
**`msg`**
|
||||
|
||||
# Loud = > Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*`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:
|
||||
|
||||
```markdown
|
||||
# Child = > Parent
|
||||
+ `name`
|
||||
|
||||
*`self` = > Parent name=`name` *
|
||||
*`self` = > json.set map=`self` key=extra value=1 *
|
||||
**`self`**
|
||||
```
|
||||
|
||||
## 11. Agent layout (ABI)
|
||||
|
||||
```markdown
|
||||
@@ -159,4 +222,13 @@ if x > 0:
|
||||
|
||||
# GOOD — ordered list arms
|
||||
1. `x` > 0
|
||||
> print text=pos
|
||||
2. *
|
||||
> print text=other
|
||||
|
||||
# GOOD — another independent branch (restart at 1.)
|
||||
1. `y` > 0
|
||||
> print text=y-pos
|
||||
2. *
|
||||
> print text=y-other
|
||||
```
|
||||
@@ -18,7 +18,7 @@ marqdo ext remove llm|agent
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
|
||||
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * ``; loops `` - [`item`](`coll`) ``; identifiers in backticks. See `doc/design/markdown-mapping.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.
|
||||
|
||||
@@ -43,7 +43,7 @@ Import one file; use **that** file’s function names.
|
||||
| EN import | ZH import | Typical APIs (EN / ZH) |
|
||||
|-----------|-----------|-------------------------|
|
||||
| `lib/text.mq.md` | `lib/文本.mq.md` | text helpers / 去空白·拆分·拼接… |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | table/rows helpers |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | `put`/`改` + list/map(见 `doc/design/stdlib-table.md`) |
|
||||
| `lib/fs.mq.md` | `lib/文件.mq.md` | filesystem |
|
||||
| `lib/sys.mq.md` | `lib/系统.mq.md` | process / cwd / load_dotenv |
|
||||
| `lib/plugin.mq.md` | `lib/插件.mq.md` | load native ABI plugins (`doc/design/ext-abi.md`) |
|
||||
|
||||
@@ -35,6 +35,7 @@ jobs:
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ver = "${{ github.ref_name }}".TrimStart("v")
|
||||
New-Item -ItemType Directory -Force -Path dist | Out-Null
|
||||
Push-Location vscode-extension
|
||||
npm ci
|
||||
npm run compile
|
||||
@@ -50,8 +51,20 @@ jobs:
|
||||
$exe = "marqdo-$ver-$target.exe"
|
||||
$zip = "marqdo-$ver-$target.zip"
|
||||
$stdlib = "marqdo-$ver-stdlib.zip"
|
||||
$source = "marqdo-$ver-source.zip"
|
||||
$vsix = "marqdo-$ver.vsix"
|
||||
$public = "marqdo-$ver-public.zip"
|
||||
$extZip = "marqdo-$ver-ext.zip"
|
||||
Copy-Item target/release/marqdo.exe "dist/$exe"
|
||||
git archive --format=zip -o "dist/$source" HEAD
|
||||
./target/release/marqdo view output public -o public
|
||||
Compress-Archive -Path public/* -DestinationPath "dist/$public" -Force
|
||||
$stageExt = "dist/stage-ext"
|
||||
if (Test-Path $stageExt) { Remove-Item $stageExt -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stageExt | Out-Null
|
||||
Copy-Item ext "$stageExt/ext" -Recurse
|
||||
if (Test-Path "dist/$extZip") { Remove-Item "dist/$extZip" -Force }
|
||||
Compress-Archive -Path "$stageExt/*" -DestinationPath "dist/$extZip" -Force
|
||||
$stage = "dist/stage-bundle"
|
||||
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stage | Out-Null
|
||||
@@ -69,6 +82,9 @@ jobs:
|
||||
echo "ZIP=$zip" >> $env:GITHUB_ENV
|
||||
echo "STDLIB=$stdlib" >> $env:GITHUB_ENV
|
||||
echo "VSIX=$vsix" >> $env:GITHUB_ENV
|
||||
echo "SOURCE=$source" >> $env:GITHUB_ENV
|
||||
echo "PUBLIC=$public" >> $env:GITHUB_ENV
|
||||
echo "EXT=$extZip" >> $env:GITHUB_ENV
|
||||
|
||||
- name: Upload release assets
|
||||
uses: softprops/action-gh-release@v2
|
||||
@@ -76,11 +92,13 @@ jobs:
|
||||
body: |
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### Highlights
|
||||
- **Embedded stdlib** (v0.1.2+): `lib/*.mq.md` built into the binary
|
||||
- **writeback** + **subtask** stdlibs
|
||||
- **`marqdo version --check`**
|
||||
- VSIX built from branch **`vscode-extension`** (not tracked on `main`)
|
||||
### Highlights — extension libraries
|
||||
- Official **`ext/`** packages: `llm`, `agent`, `web`, `quantum` (not stdlib)
|
||||
- Install: `marqdo ext list` / `marqdo ext add llm|agent|web|quantum`
|
||||
- Native plugins: `cargo build --release -p marqdo_plugin_*` then `ext add`
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-cli.md](https://github.com/cflmy/marqdo/blob/main/doc/design/ext-cli.md)
|
||||
|
||||
Also: embedded stdlib, writeback/subtask, Variables modal in `view`, VSIX from branch **`vscode-extension`**.
|
||||
|
||||
### Downloads
|
||||
|
||||
@@ -89,14 +107,20 @@ jobs:
|
||||
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
|
||||
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` (optional disk override) |
|
||||
| `marqdo-*-stdlib.zip` | `lib/` only |
|
||||
| `marqdo-*-ext.zip` | Official `ext/` L1 sources (for `MARQDO_EXT_SOURCE` / local `./ext`) |
|
||||
| `marqdo-*-source.zip` | Source snapshot (`git archive`) |
|
||||
| `marqdo-*.vsix` | VS Code / Cursor extension |
|
||||
| `marqdo-*-public.zip` | Static user docs site |
|
||||
|
||||
Extension workflow: [doc/design/vscode-extension-commit.md](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)
|
||||
Extension workflow: [vscode-extension-commit.md](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)
|
||||
files: |
|
||||
dist/${{ env.EXE }}
|
||||
dist/${{ env.ZIP }}
|
||||
dist/${{ env.STDLIB }}
|
||||
dist/${{ env.EXT }}
|
||||
dist/${{ env.VSIX }}
|
||||
dist/${{ env.SOURCE }}
|
||||
dist/${{ env.PUBLIC }}
|
||||
fail_on_unmatched_files: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
+11
@@ -22,6 +22,7 @@
|
||||
*.pdb
|
||||
.DS_Store
|
||||
.marqdo/
|
||||
**/.marqdo/
|
||||
.env
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
@@ -37,3 +38,13 @@ spike/__pycache__/
|
||||
spike/.pytest_cache/
|
||||
**/__pycache__/
|
||||
*.pyc
|
||||
|
||||
# Local sqlite / scratch
|
||||
/data/
|
||||
/tmp/
|
||||
plugins/*/tmp/
|
||||
# web smoke/example DBs (cwd-relative or fixture data dirs)
|
||||
/web-fixtures/
|
||||
/tests/ext/web-fixtures/data/
|
||||
/examples/web-site/data/
|
||||
/examples/web-site-zh/data/
|
||||
@@ -1,5 +1,63 @@
|
||||
# Changelog
|
||||
|
||||
## v0.2.0 — 2026-08-12
|
||||
|
||||
### Highlights — official extension libraries
|
||||
|
||||
This release centers on **`ext/`**: optional packages that are **not** part of the embedded stdlib. Install them with the CLI; native plugins (`.so` / `.dll`) ship beside L1 Markdown APIs.
|
||||
|
||||
**How to get extensions**
|
||||
|
||||
```bash
|
||||
# List what the installer knows about
|
||||
marqdo ext list
|
||||
|
||||
# Install from the repo's ./ext (or MARQDO_EXT_SOURCE), into ~/.marqdo/ext (or MARQDO_EXT)
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
|
||||
# Chinese ids work the same (大模型 / 智能体 / 网页 / 量子)
|
||||
marqdo ext add 量子
|
||||
|
||||
marqdo ext remove quantum
|
||||
```
|
||||
|
||||
Native plugins (agent / web / quantum) must be built once, then `ext add` copies them into `MARQDO_EXT/native/`:
|
||||
|
||||
```bash
|
||||
cargo build --release -p marqdo_plugin_agent
|
||||
cargo build --release -p marqdo_plugin_web
|
||||
cargo build --release -p marqdo_plugin_quantum
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
Runtime also resolves plugins from `CARGO_TARGET_DIR`, `target/`, next to the `marqdo` binary, or `MARQDO_*_PLUGIN` env vars. Design: [ext-cli.md](doc/design/ext-cli.md) · [ext-abi.md](doc/design/ext-abi.md).
|
||||
|
||||
| Package | What you get |
|
||||
|---------|----------------|
|
||||
| **llm** | OpenAI-compatible chat — [ext-llm.md](doc/design/ext-llm.md) |
|
||||
| **agent** | Agent layout / orchestration helpers + native plugin — [ext-agent.md](doc/design/ext-agent.md) |
|
||||
| **web** | HTTP + SQLite site helpers + native plugin — [ext-web.md](doc/design/ext-web.md) |
|
||||
| **quantum** | State-vector circuits, draw, noise, formula `matrix=` custom gates — [ext-quantum.md](doc/design/ext-quantum.md) |
|
||||
|
||||
User-facing intro: [`public/features/05-extensions.mq.md`](public/features/05-extensions.mq.md) / [`05-扩展.mq.md`](public/features/05-扩展.mq.md).
|
||||
|
||||
### Added
|
||||
- Full **ext CLI** catalog: `llm`, `agent`, `web`, `quantum` (EN/ZH ids).
|
||||
- **Quantum (Q0–Q6)**: gates, `run`/`steps`, draw (circuit/probs/bloch), heatmaps, teaching noise incl. amplitude damping, **custom gates from `$$` / `matrix=`**.
|
||||
- **Web** extension (listen / render / SQLite) with L1 EN/ZH.
|
||||
- **Agent** native plugin path + installer copy into `native/`.
|
||||
- View **Variables** panel: previews + click-to-open rich modal (matrices / KaTeX).
|
||||
- Formula matrix parse (`pmatrix` / `[[…]]`) for executable gate matrices.
|
||||
|
||||
### Changed
|
||||
- Release notes and docs emphasize extensions vs embedded stdlib.
|
||||
- Highlight.js CDN path for view pages; Variables panel script escaping fixed.
|
||||
|
||||
## v0.1.2 — 2026-08-07
|
||||
|
||||
### Added
|
||||
|
||||
Generated
+515
-17
@@ -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"
|
||||
@@ -8,6 +8,18 @@ version = "2.0.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
|
||||
|
||||
[[package]]
|
||||
name = "ahash"
|
||||
version = "0.8.12"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"once_cell",
|
||||
"version_check",
|
||||
"zerocopy",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "aho-corasick"
|
||||
version = "1.1.5"
|
||||
@@ -103,12 +115,70 @@ dependencies = [
|
||||
"wait-timeout",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "atomic-waker"
|
||||
version = "1.1.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
|
||||
|
||||
[[package]]
|
||||
name = "autocfg"
|
||||
version = "1.5.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
|
||||
|
||||
[[package]]
|
||||
name = "axum"
|
||||
version = "0.8.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90"
|
||||
dependencies = [
|
||||
"axum-core",
|
||||
"bytes",
|
||||
"form_urlencoded",
|
||||
"futures-util",
|
||||
"http",
|
||||
"http-body",
|
||||
"http-body-util",
|
||||
"hyper",
|
||||
"hyper-util",
|
||||
"itoa",
|
||||
"matchit",
|
||||
"memchr",
|
||||
"mime",
|
||||
"percent-encoding",
|
||||
"pin-project-lite",
|
||||
"serde_core",
|
||||
"serde_json",
|
||||
"serde_path_to_error",
|
||||
"serde_urlencoded",
|
||||
"sync_wrapper",
|
||||
"tokio",
|
||||
"tower",
|
||||
"tower-layer",
|
||||
"tower-service",
|
||||
"tracing",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "axum-core"
|
||||
version = "0.5.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1"
|
||||
dependencies = [
|
||||
"bytes",
|
||||
"futures-core",
|
||||
"http",
|
||||
"http-body",
|
||||
"http-body-util",
|
||||
"mime",
|
||||
"pin-project-lite",
|
||||
"sync_wrapper",
|
||||
"tower-layer",
|
||||
"tower-service",
|
||||
"tracing",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "base64"
|
||||
version = "0.22.1"
|
||||
@@ -139,10 +209,16 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
|
||||
|
||||
[[package]]
|
||||
name = "cc"
|
||||
version = "1.4.0"
|
||||
name = "bytes"
|
||||
version = "1.12.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9"
|
||||
checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
|
||||
|
||||
[[package]]
|
||||
name = "cc"
|
||||
version = "1.4.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5d262e149917187838d5b42777c8253bcb64500067342904e7d429499a6f277e"
|
||||
dependencies = [
|
||||
"find-msvc-tools",
|
||||
"shlex",
|
||||
@@ -245,10 +321,32 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "780955b8b195a21ab8e4ac6b60dd1dbdcec1dc6c51c0617964b08c81785e12c9"
|
||||
|
||||
[[package]]
|
||||
name = "find-msvc-tools"
|
||||
name = "errno"
|
||||
version = "0.3.14"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
|
||||
dependencies = [
|
||||
"libc",
|
||||
"windows-sys 0.61.2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "fallible-iterator"
|
||||
version = "0.3.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649"
|
||||
|
||||
[[package]]
|
||||
name = "fallible-streaming-iterator"
|
||||
version = "0.1.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
|
||||
checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"
|
||||
|
||||
[[package]]
|
||||
name = "find-msvc-tools"
|
||||
version = "0.1.10"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "26b73573e6edcd2af0cdf47bd6cb58f0b3839491263c314eaad1ccf24430e1de"
|
||||
|
||||
[[package]]
|
||||
name = "flate2"
|
||||
@@ -278,12 +376,27 @@ dependencies = [
|
||||
"percent-encoding",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "futures-channel"
|
||||
version = "0.3.33"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae"
|
||||
dependencies = [
|
||||
"futures-core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "futures-core"
|
||||
version = "0.3.33"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
|
||||
|
||||
[[package]]
|
||||
name = "futures-sink"
|
||||
version = "0.3.34"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d"
|
||||
|
||||
[[package]]
|
||||
name = "futures-task"
|
||||
version = "0.3.33"
|
||||
@@ -322,18 +435,116 @@ dependencies = [
|
||||
"wasi",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "hashbrown"
|
||||
version = "0.14.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
|
||||
dependencies = [
|
||||
"ahash",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "hashlink"
|
||||
version = "0.9.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "6ba4ff7128dee98c7dc9794b6a411377e1404dba1c97deb8d1a55297bd25d8af"
|
||||
dependencies = [
|
||||
"hashbrown",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "heck"
|
||||
version = "0.4.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8"
|
||||
|
||||
[[package]]
|
||||
name = "http"
|
||||
version = "1.5.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0"
|
||||
dependencies = [
|
||||
"bytes",
|
||||
"itoa",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "http-body"
|
||||
version = "1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"
|
||||
dependencies = [
|
||||
"bytes",
|
||||
"http",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "http-body-util"
|
||||
version = "0.1.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e9f41fd6a08e4d4ec69df65976da761afd5ad5e58a9d4acb46bd1c953a9e3ff2"
|
||||
dependencies = [
|
||||
"bytes",
|
||||
"futures-core",
|
||||
"http",
|
||||
"http-body",
|
||||
"pin-project-lite",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "http-range-header"
|
||||
version = "0.4.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9171a2ea8a68358193d15dd5d70c1c10a2afc3e7e4c5bc92bc9f025cebd7359c"
|
||||
|
||||
[[package]]
|
||||
name = "httparse"
|
||||
version = "1.10.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
|
||||
|
||||
[[package]]
|
||||
name = "httpdate"
|
||||
version = "1.0.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
|
||||
|
||||
[[package]]
|
||||
name = "hyper"
|
||||
version = "1.11.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d22053281f852e11534f5198498373cbb59295120a20771d90f7ed1897490a72"
|
||||
dependencies = [
|
||||
"atomic-waker",
|
||||
"bytes",
|
||||
"futures-channel",
|
||||
"futures-core",
|
||||
"http",
|
||||
"http-body",
|
||||
"httparse",
|
||||
"httpdate",
|
||||
"itoa",
|
||||
"pin-project-lite",
|
||||
"smallvec",
|
||||
"tokio",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "hyper-util"
|
||||
version = "0.1.20"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
|
||||
dependencies = [
|
||||
"bytes",
|
||||
"http",
|
||||
"http-body",
|
||||
"hyper",
|
||||
"pin-project-lite",
|
||||
"tokio",
|
||||
"tower-service",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "iana-time-zone"
|
||||
version = "0.1.65"
|
||||
@@ -422,9 +633,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
|
||||
|
||||
[[package]]
|
||||
name = "js-sys"
|
||||
version = "0.3.103"
|
||||
version = "0.3.104"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
|
||||
checksum = "0e0c1080212aad755ea003d18543e8768dd432c48819efd73a7bf1e39b7a5a3a"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"futures-util",
|
||||
@@ -447,6 +658,17 @@ dependencies = [
|
||||
"windows-targets",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "libsqlite3-sys"
|
||||
version = "0.30.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "2e99fb7a497b1e3339bc746195567ed8d3e24945ecd636e3619d20b9de9e9149"
|
||||
dependencies = [
|
||||
"cc",
|
||||
"pkg-config",
|
||||
"vcpkg",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "log"
|
||||
version = "0.4.33"
|
||||
@@ -455,7 +677,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "0.1.2"
|
||||
version = "0.2.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
@@ -463,6 +685,7 @@ dependencies = [
|
||||
"clap",
|
||||
"idna_adapter",
|
||||
"include_dir",
|
||||
"libc",
|
||||
"libloading",
|
||||
"predicates",
|
||||
"pulldown-cmark",
|
||||
@@ -477,6 +700,7 @@ dependencies = [
|
||||
name = "marqdo_plugin_agent"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
@@ -487,12 +711,54 @@ dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_quantum"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"serde",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_web"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"axum",
|
||||
"rusqlite",
|
||||
"serde",
|
||||
"serde_json",
|
||||
"tokio",
|
||||
"tower-http",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "matchit"
|
||||
version = "0.8.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
|
||||
|
||||
[[package]]
|
||||
name = "memchr"
|
||||
version = "2.8.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
|
||||
|
||||
[[package]]
|
||||
name = "mime"
|
||||
version = "0.3.17"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
|
||||
|
||||
[[package]]
|
||||
name = "mime_guess"
|
||||
version = "2.0.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f7c44f8e672c00fe5308fa235f821cb4198414e1c77935c1ab6948d3fd78550e"
|
||||
dependencies = [
|
||||
"mime",
|
||||
"unicase",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "miniz_oxide"
|
||||
version = "0.8.9"
|
||||
@@ -503,6 +769,17 @@ dependencies = [
|
||||
"simd-adler32",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "mio"
|
||||
version = "1.2.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427"
|
||||
dependencies = [
|
||||
"libc",
|
||||
"wasi",
|
||||
"windows-sys 0.61.2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "normalize-line-endings"
|
||||
version = "0.3.0"
|
||||
@@ -542,6 +819,12 @@ version = "0.2.17"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
|
||||
|
||||
[[package]]
|
||||
name = "pkg-config"
|
||||
version = "0.3.33"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
|
||||
|
||||
[[package]]
|
||||
name = "predicates"
|
||||
version = "3.1.0"
|
||||
@@ -652,6 +935,20 @@ dependencies = [
|
||||
"windows-sys 0.52.0",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rusqlite"
|
||||
version = "0.32.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7753b721174eb8ff87a9a0e799e2d7bc3749323e773db92e0984debb00019d6e"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
"fallible-iterator",
|
||||
"fallible-streaming-iterator",
|
||||
"hashlink",
|
||||
"libsqlite3-sys",
|
||||
"smallvec",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustls"
|
||||
version = "0.22.4"
|
||||
@@ -692,6 +989,12 @@ version = "1.0.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
|
||||
|
||||
[[package]]
|
||||
name = "ryu"
|
||||
version = "1.0.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
|
||||
|
||||
[[package]]
|
||||
name = "serde"
|
||||
version = "1.0.229"
|
||||
@@ -699,6 +1002,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
|
||||
dependencies = [
|
||||
"serde_core",
|
||||
"serde_derive",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -734,12 +1038,45 @@ dependencies = [
|
||||
"zmij",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_path_to_error"
|
||||
version = "0.1.20"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457"
|
||||
dependencies = [
|
||||
"itoa",
|
||||
"serde",
|
||||
"serde_core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_urlencoded"
|
||||
version = "0.7.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd"
|
||||
dependencies = [
|
||||
"form_urlencoded",
|
||||
"itoa",
|
||||
"ryu",
|
||||
"serde",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "shlex"
|
||||
version = "2.0.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
|
||||
|
||||
[[package]]
|
||||
name = "signal-hook-registry"
|
||||
version = "1.4.8"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
|
||||
dependencies = [
|
||||
"errno",
|
||||
"libc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "simd-adler32"
|
||||
version = "0.3.10"
|
||||
@@ -758,6 +1095,16 @@ version = "1.15.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
|
||||
|
||||
[[package]]
|
||||
name = "socket2"
|
||||
version = "0.6.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
|
||||
dependencies = [
|
||||
"libc",
|
||||
"windows-sys 0.61.2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "strsim"
|
||||
version = "0.10.0"
|
||||
@@ -792,6 +1139,12 @@ dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "sync_wrapper"
|
||||
version = "1.0.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
|
||||
|
||||
[[package]]
|
||||
name = "termtree"
|
||||
version = "0.5.1"
|
||||
@@ -845,6 +1198,119 @@ version = "0.1.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
|
||||
|
||||
[[package]]
|
||||
name = "tokio"
|
||||
version = "1.53.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
|
||||
dependencies = [
|
||||
"bytes",
|
||||
"libc",
|
||||
"mio",
|
||||
"pin-project-lite",
|
||||
"signal-hook-registry",
|
||||
"socket2",
|
||||
"tokio-macros",
|
||||
"windows-sys 0.61.2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tokio-macros"
|
||||
version = "2.7.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 3.0.3",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tokio-util"
|
||||
version = "0.7.19"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
|
||||
dependencies = [
|
||||
"bytes",
|
||||
"futures-core",
|
||||
"futures-sink",
|
||||
"pin-project-lite",
|
||||
"tokio",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tower"
|
||||
version = "0.5.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
|
||||
dependencies = [
|
||||
"futures-core",
|
||||
"futures-util",
|
||||
"pin-project-lite",
|
||||
"sync_wrapper",
|
||||
"tokio",
|
||||
"tower-layer",
|
||||
"tower-service",
|
||||
"tracing",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tower-http"
|
||||
version = "0.6.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
"bytes",
|
||||
"futures-core",
|
||||
"futures-util",
|
||||
"http",
|
||||
"http-body",
|
||||
"http-body-util",
|
||||
"http-range-header",
|
||||
"httpdate",
|
||||
"mime",
|
||||
"mime_guess",
|
||||
"percent-encoding",
|
||||
"pin-project-lite",
|
||||
"tokio",
|
||||
"tokio-util",
|
||||
"tower-layer",
|
||||
"tower-service",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tower-layer"
|
||||
version = "0.3.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"
|
||||
|
||||
[[package]]
|
||||
name = "tower-service"
|
||||
version = "0.3.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
|
||||
|
||||
[[package]]
|
||||
name = "tracing"
|
||||
version = "0.1.44"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
|
||||
dependencies = [
|
||||
"log",
|
||||
"pin-project-lite",
|
||||
"tracing-core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tracing-core"
|
||||
version = "0.1.36"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
|
||||
dependencies = [
|
||||
"once_cell",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "unicase"
|
||||
version = "2.9.0"
|
||||
@@ -931,6 +1397,18 @@ version = "0.2.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
|
||||
|
||||
[[package]]
|
||||
name = "vcpkg"
|
||||
version = "0.2.15"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
|
||||
|
||||
[[package]]
|
||||
name = "version_check"
|
||||
version = "0.9.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
|
||||
|
||||
[[package]]
|
||||
name = "wait-timeout"
|
||||
version = "0.2.1"
|
||||
@@ -948,9 +1426,9 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen"
|
||||
version = "0.2.126"
|
||||
version = "0.2.127"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
|
||||
checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"once_cell",
|
||||
@@ -961,9 +1439,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro"
|
||||
version = "0.2.126"
|
||||
version = "0.2.127"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
|
||||
checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1"
|
||||
dependencies = [
|
||||
"quote",
|
||||
"wasm-bindgen-macro-support",
|
||||
@@ -971,9 +1449,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-macro-support"
|
||||
version = "0.2.126"
|
||||
version = "0.2.127"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
|
||||
checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284"
|
||||
dependencies = [
|
||||
"bumpalo",
|
||||
"proc-macro2",
|
||||
@@ -984,9 +1462,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen-shared"
|
||||
version = "0.2.126"
|
||||
version = "0.2.127"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
|
||||
checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf"
|
||||
dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
@@ -1150,6 +1628,26 @@ version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
|
||||
|
||||
[[package]]
|
||||
name = "zerocopy"
|
||||
version = "0.8.56"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "556764e583adb45a9f8d413c2a147fa7e8d821e48e12b14fd560b607998b75eb"
|
||||
dependencies = [
|
||||
"zerocopy-derive",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "zerocopy-derive"
|
||||
version = "0.8.56"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f2ab42fc20575779bd240faa45f94a74256f755c0fa9e89f0ede20d91d0cdfc1"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn 2.0.119",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "zeroize"
|
||||
version = "1.8.1"
|
||||
|
||||
+3
-2
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.1.2"
|
||||
version = "0.2.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -25,9 +25,10 @@ idna_adapter = "=1.1.0"
|
||||
zeroize = "=1.8.1"
|
||||
libloading = "=0.8.6"
|
||||
include_dir = "0.7"
|
||||
libc = "0.2"
|
||||
|
||||
[workspace]
|
||||
members = ["plugins/demo", "plugins/agent"]
|
||||
members = ["plugins/demo", "plugins/agent", "plugins/web", "plugins/quantum"]
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
|
||||
@@ -36,7 +36,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
| `##` … | 函数 / 方法(按标题深度嵌套) |
|
||||
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
|
||||
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [`项`](`集合`) ``) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) `` / `` - [`项`](`集合`) ``) |
|
||||
| 表格 | 集合 |
|
||||
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
|
||||
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
|
||||
@@ -97,17 +97,17 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.1.2)
|
||||
## 现状(v0.2.0)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
|
||||
- **`marqdo version --check`**:与 GitHub 最新 release 对比
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
|
||||
- **官方扩展 `ext/`**(非 stdlib):[`ext/llm`](doc/design/ext-llm.md);[`ext/agent`](doc/design/ext-agent.md) 智能体开发框架。安装:`marqdo ext list` / `add llm|agent` / `remove`(见 [ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext` 或 `MARQDO_EXT`)
|
||||
- **原生插件 ABI v1**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);demo `plugins/demo`
|
||||
- **官方扩展库 `ext/`**(本版重点,**非** stdlib):`llm` · `agent` · `web` · `quantum`。安装:`marqdo ext list` / `add …` / `remove`(见 [ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext` 或 `MARQDO_EXT`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`。设计:[ext-llm](doc/design/ext-llm.md) · [ext-agent](doc/design/ext-agent.md) · [ext-web](doc/design/ext-web.md) · [ext-quantum](doc/design/ext-quantum.md)
|
||||
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}`
|
||||
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
|
||||
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
||||
@@ -122,7 +122,7 @@ cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
**发布包(GitHub Releases)**:自 **v0.1.2** 起,单独 `.exe` **已内置**官方 `lib/`(`> lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发;`ext/` 与原生插件 `.dll` 仍须单独安装。`marqdo version --check` 可查看是否有新版本。OpenAI 兼容聊天见 [ext-llm.md](doc/design/ext-llm.md)。智能体布局见 [ext-agent.md](doc/design/ext-agent.md)。
|
||||
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`> lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add llm|agent|web|quantum` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。`marqdo version --check` 可查看是否有新版本。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
|
||||
|
||||
|
||||
+14
-3
@@ -20,12 +20,15 @@
|
||||
| [design/ai-skill.md](design/ai-skill.md) | **AI 接入 Skill**([`skills/marqdo/`](../skills/marqdo/)) |
|
||||
| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述 / 可执行 / 外联 |
|
||||
| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 |
|
||||
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单 |
|
||||
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单(早期方向) |
|
||||
| [design/okf.md](design/okf.md) | **Marqdo OKF 实现规范**(catalog v0 + 任务知识包) |
|
||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
||||
| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
|
||||
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
|
||||
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
|
||||
| [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 已落地)** |
|
||||
| [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/网络/数学/外联/插件** |
|
||||
@@ -33,13 +36,14 @@
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
|
||||
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
|
||||
| [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** |
|
||||
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(智能体开发框架;布局已落地,编排/大模型组合路线已记录)** |
|
||||
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** |
|
||||
| [design/ext-agent-plan.md](design/ext-agent-plan.md) | **`## 多步` / `## plan` 锁定设计**(工作簿文件、subtask 执行、修订循环、`step` 默认写回) |
|
||||
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
|
||||
| [design/ext-web.md](design/ext-web.md) | **官方扩展 `ext/web`(页面/库表/绑定/后台;ABI + CLI;设计锁定)** |
|
||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
|
||||
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
|
||||
| [design/user-site.md](design/user-site.md) | **用户站:`public/` → `gh-pages`** |
|
||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
||||
| [design/view-debug.md](design/view-debug.md) | **`marqdo debug` 独立调试页** |
|
||||
| [design/vscode-extension.md](design/vscode-extension.md) | **VS Code 扩展:分支 `vscode-extension`(main 不跟踪源码)** |
|
||||
| [design/vscode-extension-commit.md](design/vscode-extension-commit.md) | **扩展提交约定(禁止在 main 提交 `vscode-extension/`)** |
|
||||
@@ -48,6 +52,13 @@
|
||||
| [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) |
|
||||
| [roadmap/interpreter.md](roadmap/interpreter.md) | 正经解释器路线图 |
|
||||
| [roadmap/next-phase.md](roadmap/next-phase.md) | **下一阶段:input / 诊断 / 标准库 / view 调试** |
|
||||
| [roadmap/okf-near-match.md](roadmap/okf-near-match.md) | **规划:OKF 相近任务命中**(精确 sig 之外的可选软复用) |
|
||||
| [roadmap/agent-streaming.md](roadmap/agent-streaming.md) | **流式输出**(SSE + `complete`/`step` stream;S0–S1 已落地) |
|
||||
| [roadmap/object-inheritance.md](roadmap/object-inheritance.md) | **对象继承**(`# 子类 = > 父类`;I0–I2 已落地) |
|
||||
| [roadmap/tables-maps-footnotes.md](roadmap/tables-maps-footnotes.md) | **表格语义**(竖表 / 横表字典 / 脚注取元 / 行向记录 / **单元格表达式 T5**) |
|
||||
| [design/table-cell-expressions.md](design/table-cell-expressions.md) | **表数据单元格 = 表达式**(同调用实参值语法;Accepted) |
|
||||
| [roadmap/ext-web.md](roadmap/ext-web.md) | **实现路线:`ext/web`**(W0–W4;设计见 [ext-web.md](../design/ext-web.md)) |
|
||||
| [roadmap/ext-quantum.md](roadmap/ext-quantum.md) | **规划:`ext/quantum` 量子模拟**(基础门·电路·ABI·`ext add`) |
|
||||
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
@@ -67,7 +67,8 @@
|
||||
| `keywords/bool-logic` | ✅ | ✅ |
|
||||
| `structure/nested-call` | ✅ | ✅ |
|
||||
| `structure/positional-call` | ✅ | ✅ |
|
||||
| `structure/import/*` | ✅ | ✅(load 合并 AST 后编译) |
|
||||
| `structure/import/*` | ✅ | ✅(导入模块树后编译) |
|
||||
| `structure/ns/*` | ✅ | ✅ |
|
||||
| `tests/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) |
|
||||
|
||||
核心金样例双后端已对齐;后续可扩展 Op、优化与更好的调试信息。
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.1 增补) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) |
|
||||
|
||||
---
|
||||
|
||||
@@ -50,4 +50,4 @@ positional ::= value_token
|
||||
|
||||
## 4. 金样例
|
||||
|
||||
见 `tests/structure/positional-call.mq.md` 与更新后的 `tests/structure/import/`。
|
||||
见 `tests/structure/positional-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
|
||||
+32
-33
@@ -2,18 +2,18 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0 命令落地) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 状态 | 已定(O1 + O3:工程目录包 + agent-kb 概念并入) |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 |
|
||||
| 相关 | [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
|
||||
| 相关 | [okf.md](okf.md)(**实现规范总览**)· [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 决策(重申)
|
||||
|
||||
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。详见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
|
||||
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。完整词汇、任务知识包与路线图见 [**okf.md**](okf.md)。生成式方向见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
|
||||
|
||||
本文件规定 **CLI 与 v0 落盘格式**。
|
||||
本文件规定 **CLI 与工程目录包落盘格式**(含 O3:扫入本地 `agent-kb` 概念,供人与工具同览)。
|
||||
|
||||
---
|
||||
|
||||
@@ -28,26 +28,31 @@ marqdo sync [PATH] -o OUT_DIR
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
|
||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件) |
|
||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
|
||||
|
||||
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 生成物(v0)
|
||||
## 3. 生成物
|
||||
|
||||
```
|
||||
OUT_DIR/
|
||||
catalog.yaml # 机器向总清单(OKF 风格字段)
|
||||
index.md # 人/Agent 可读总览(含 YAML frontmatter)
|
||||
index.md # 人可读总览:Modules + Agent knowledge
|
||||
modules/
|
||||
<stem>.md # 每个 .mq.md 一个概念页(frontmatter + 摘要)
|
||||
<stem>.md # 每个工程 .mq.md 一个 Module 页
|
||||
concepts/ # 从 **/.marqdo/agent-kb/concepts/ 复制(O3)
|
||||
tasks/…
|
||||
skills/…
|
||||
```
|
||||
|
||||
路径中的目录层级拍扁为文件名时用 `__` 连接,例如:
|
||||
|
||||
`structure/import/main.mq.md` → `modules/structure__import__main.md`
|
||||
|
||||
`.marqdo/agent-kb/` 下的可执行 `.mq.md` **不**进 Module 表(由 Task/Skill 概念页的 `resource` 指向)。
|
||||
|
||||
### 3.1 `catalog.yaml`(示意)
|
||||
|
||||
```yaml
|
||||
@@ -55,12 +60,11 @@ OUT_DIR/
|
||||
type: Marqdo Catalog
|
||||
title: marqdo-project
|
||||
generated:
|
||||
by: marqdo/0.0.1
|
||||
# at: 可选 ISO8601;CI 比对时可忽略
|
||||
by: marqdo/0.1.2
|
||||
modules:
|
||||
- id: structure/hello
|
||||
resource: structure/hello.mq.md
|
||||
title: Hello World # 来自源 frontmatter title,缺省用文件名
|
||||
title: Hello World
|
||||
imports: []
|
||||
exports:
|
||||
- name: Hello World
|
||||
@@ -72,35 +76,28 @@ modules:
|
||||
exports:
|
||||
- name: main
|
||||
kind: fn
|
||||
concepts: [] # 有 agent-kb 时为 Task/Skill 条目列表
|
||||
```
|
||||
|
||||
字段约定(v0 最小集):
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) |
|
||||
| `modules[].resource` | 相对 `PATH` 的源路径 |
|
||||
| `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` |
|
||||
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`);嵌套 `##` 列入 `children`(可选,v0 可扁平只列顶层) |
|
||||
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`) |
|
||||
| `modules[].verified` / `sources` | 源 frontmatter 有则透传(O3) |
|
||||
| `concepts[]` | 本地 agent-kb 概念摘要(`id`/`type`/`page`/…) |
|
||||
| `generated.by` | `marqdo/<crate version>` |
|
||||
|
||||
不在 v0:版本锁定哈希、跨仓 URL、完整符号类型。
|
||||
不在现行范围:版本锁定哈希、跨仓 URL、完整符号类型、`log.md`(见 okf O4)。
|
||||
|
||||
### 3.2 模块概念页 frontmatter
|
||||
### 3.2 模块概念页
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Marqdo Module
|
||||
title: …
|
||||
resource: structure/hello.mq.md
|
||||
depends: [] # imports 列表
|
||||
exports: [Hello World]
|
||||
generated:
|
||||
by: marqdo/0.0.1
|
||||
---
|
||||
```
|
||||
Frontmatter 仍用 `depends` 字符串列表(机器可读);**正文 Dependencies** 链到同包其它 Module 页(人可点)。源若带 `verified` / `sources` 则写入页头。
|
||||
|
||||
正文含「请勿手改」提示、依赖列表、导出列表;可链到同包其它模块页。
|
||||
### 3.3 Agent knowledge
|
||||
|
||||
`index.md` 的 **Agent knowledge** 节列出扫到的 Task/Skill,链到 `concepts/…`。概念页内容从本地 `agent-kb` **复制**,与 Agent 运行时包同源,便于人审阅晋升结果。
|
||||
|
||||
---
|
||||
|
||||
@@ -109,7 +106,7 @@ generated:
|
||||
| 命令 | 产物 | 受众 |
|
||||
|------|------|------|
|
||||
| `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
|
||||
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引 | 工具 / Agent / 依赖总览 |
|
||||
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引(含 agent-kb) | 人浏览依赖/技能 · 工具 / Agent |
|
||||
|
||||
二者都从同一源树生成,互不替代。发布用户文档时可同时:
|
||||
|
||||
@@ -122,7 +119,9 @@ marqdo catalog tests -o .marqdo
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml` 与 `modules/`。
|
||||
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml`、`modules/`、`concepts:` 键。
|
||||
2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。
|
||||
3. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
|
||||
4. `marqdo sync` 与 `catalog` 行为一致。
|
||||
3. 模块页 Dependencies 对已解析导入为 Markdown 链接。
|
||||
4. 若扫描根下有 `.marqdo/agent-kb/concepts/`,则复制进 `OUT_DIR/concepts/` 且 `index.md` 有 Agent knowledge 条目。
|
||||
5. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
|
||||
6. `marqdo sync` 与 `catalog` 行为一致。
|
||||
@@ -3,7 +3,7 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 原则 | **夹具即金样例**:`tests/{structure,keywords,errors}/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view tests` 也可浏览 |
|
||||
|
||||
---
|
||||
@@ -26,10 +26,17 @@ tests/
|
||||
import/
|
||||
main.mq.md
|
||||
utils.mq.md
|
||||
ns/
|
||||
helpers.mq.md
|
||||
path3.mq.md
|
||||
use.mq.md
|
||||
keywords/ # 关键字与内置名
|
||||
print.mq.md
|
||||
bool-logic.mq.md
|
||||
ext/
|
||||
agent-run-live.mq.md
|
||||
errors/ # 期望失败(诊断文案稳定后再加金样例)
|
||||
ns-instance-method.mq.md
|
||||
…
|
||||
```
|
||||
|
||||
@@ -42,7 +49,7 @@ tests/
|
||||
|
||||
| 类别 | 测什么 | 不测什么 |
|
||||
|------|--------|----------|
|
||||
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、位置/具名实参 | 关键字边角 |
|
||||
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、点号路径 / `use`、位置/具名实参 | 关键字边角 |
|
||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
||||
|
||||
@@ -51,7 +58,8 @@ tests/
|
||||
- **流水线调试**:`--dump-lines` / `--dump-ast` / `--trace-eval`
|
||||
- **CLI**:默认 `index.mq.md`、退出码
|
||||
- **view**:目录扫描、单文件页、执行区(见 [view.md](view.md))
|
||||
- **模块图**:循环导入拒绝
|
||||
- **模块图**:循环导入拒绝;`errors/ns-instance-method`(实例方法路径)
|
||||
- **ext live**:`ext/agent-run-live`(需 `.env` + `libagent`)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+35
-15
@@ -1,9 +1,9 @@
|
||||
# Native plugin ABI (v1)
|
||||
# Native plugin ABI (v2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted |
|
||||
| Date | 2026-08-06 |
|
||||
| Date | 2026-08-07 |
|
||||
| Header | [`include/marqdo_abi.h`](../../include/marqdo_abi.h) |
|
||||
| Related | [ext-agent.md](ext-agent.md) · [stdlib-modules.md](stdlib-modules.md) |
|
||||
|
||||
@@ -13,20 +13,21 @@
|
||||
- **Not** linked into the `marqdo` binary; load at runtime.
|
||||
- Stable **C** ABI only (no cross-compiler Rust ABI for plugins).
|
||||
- Official / local paths only — **no** third-party package registry.
|
||||
- **v2**: allowlisted `host_query` so plugins can read entry source / call site / skill without baking agent logic into the core.
|
||||
|
||||
## Contract
|
||||
|
||||
`MARQDO_ABI_VERSION = 1`.
|
||||
`MARQDO_ABI_VERSION = 2` (host accepts plugins with version `1..=2`).
|
||||
|
||||
Every plugin exports:
|
||||
|
||||
| Symbol | Role |
|
||||
|--------|------|
|
||||
| `marqdo_plugin_abi_version` | Must equal host’s supported version |
|
||||
| `marqdo_plugin_abi_version` | `1` or `2` |
|
||||
| `marqdo_plugin_init` | Register functions via `MarqdoHostApi` |
|
||||
| `marqdo_plugin_shutdown` | Teardown |
|
||||
|
||||
Host provides `register_fn(name, params_csv, fn)`, `alloc`, `free`.
|
||||
Host provides `register_fn`, `alloc`, `free`, and (v2) `host_query`.
|
||||
|
||||
### Wire format
|
||||
|
||||
@@ -37,6 +38,18 @@ Arguments and results are **UTF-8 JSON**:
|
||||
|
||||
Plugin fn returns `0` + `*out_json` on success; non-zero + optional `*err_msg` on failure. Host frees both strings with the host `free`.
|
||||
|
||||
### `host_query` allowlist (v2)
|
||||
|
||||
| name | Result JSON | Notes |
|
||||
|------|-------------|--------|
|
||||
| `module_source` | string | Entry `.mq.md` text |
|
||||
| `call_site` | `{path,function,line}` | Active call site |
|
||||
| `marqdo_skill` | string | Skill pack text |
|
||||
| `cwd` | string | Host `cwd` (entry file directory) for path resolution |
|
||||
| `record_plot` | `{ok:true}` | Args `{svg}` + optional `path`; push SVG into host plots (view embed / CLI auto-write), same channel as math plots |
|
||||
|
||||
Unknown names fail. Queries are only valid during a plugin function call (host sets thread-local context).
|
||||
|
||||
## Marqdo surface (`lib/plugin` / `lib/插件`)
|
||||
|
||||
| English | Chinese | Host |
|
||||
@@ -44,6 +57,7 @@ Plugin fn returns `0` + `*out_json` on success; non-zero + optional `*err_msg` o
|
||||
| `## load` (`path`) | `## 加载` (`路径`) | `host_plugin_load` |
|
||||
| `## unload` | `## 卸载` | `host_plugin_unload` |
|
||||
| `## list` | `## 列出` | `host_plugin_list` |
|
||||
| `## native_path` (`name`) | `## 原生路径` (`名`) | `host_ext_native_path` |
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -60,26 +74,32 @@ Plugin fn returns `0` + `*out_json` on success; non-zero + optional `*err_msg` o
|
||||
|
||||
After `load`, registered names are callable like other functions (plugin registry lookup after fixed host fns, before user `#`/`##` defs).
|
||||
|
||||
**Path sandbox:** `path` resolves under the program’s cwd / `fs_root` (same as `lib/fs`). Absolute paths outside the root are rejected. Prefer a same-directory filename, or pass a path via a variable / env (see gold tests).
|
||||
**Path sandbox:** `path` resolves under the program’s cwd / `fs_root` (same as `lib/fs`). Absolute paths outside the root are rejected unless trusted (`MARQDO_EXT` / `MARQDO_AGENT_PLUGIN` / built `libagent.*`). Prefer `native_path name=agent` for the official agent plugin.
|
||||
|
||||
## Demo
|
||||
## Demo / agent
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_demo
|
||||
# Windows: target/debug/demo.dll
|
||||
# Linux: target/debug/libdemo.so
|
||||
# macOS: target/debug/libdemo.dylib
|
||||
cargo build -p marqdo_plugin_agent
|
||||
```
|
||||
|
||||
Registers `demo_add(a,b)`, `demo_echo(text)`. Gold: [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
|
||||
- Demo (ABI v1): `demo_add`, `demo_echo` — [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
|
||||
- Agent (ABI v2): … **OKF agent-kb** …
|
||||
- Web (ABI v2): HTTP listen + SQLite + page render (`web_listen`, `web_render`, `web_db_*`) — [`plugins/web`](../../plugins/web); used by [`ext/web/web.mq.md`](../../ext/web/web.mq.md). Lookup: `plugin.native_path name=web` / `MARQDO_WEB_PLUGIN` / `marqdo ext add web`.
|
||||
|
||||
Official agent layout plugin: [`plugins/agent`](../../plugins/agent) — see [ext-agent.md](ext-agent.md).
|
||||
## Layering
|
||||
|
||||
| Layer | May call `host_*` |
|
||||
|-------|-------------------|
|
||||
| `lib/*` | Yes (only L1 wrappers of generic L0.5) |
|
||||
| `ext/*` | **No** — compose `lib/*` or ABI plugin names via `lib/plugin` |
|
||||
| Application `.mq.md` | Prefer same as ext; do not add agent/OKF originals to `src/host` |
|
||||
|
||||
**Hard rule:** agent / OKF domain primitives live in `plugins/agent`, never in `HostFn` / `src/host/kb.rs`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Embedding plugins in the release exe by default
|
||||
- Callbacks from plugin into arbitrary Marqdo evaluation
|
||||
- OS sandbox / seccomp
|
||||
- Arbitrary HostFn passthrough via `host_query`
|
||||
- **Third-party** plugin / package registry
|
||||
|
||||
Official install of known extensions (`marqdo ext add …`) is **planned** — see [ext-cli.md](ext-cli.md). That is not a public marketplace.
|
||||
@@ -0,0 +1,143 @@
|
||||
# 父智能体 Plan-and-Move(`## plan` 行动面)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted** |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 父文档 | [ext-agent-plan.md](ext-agent-plan.md) · [ext-agent.md](ext-agent.md) |
|
||||
| 相关 | [stdlib-subtask.md](stdlib-subtask.md) · [okf.md](okf.md) · [ai-skill.md](ai-skill.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 一句话
|
||||
|
||||
**父智能体 = Plan-and-Move 控制器**:观察工作簿与子任务结果 → 规划下一步 → 行动(读 / 调工具 / 补丁 / 再跑 / 停);Marqdo「文档即代码」让工具、记忆与程序都落在 `.mq.md` 上。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为何需要强化
|
||||
|
||||
单靠 `DECISION: DONE|CONTINUE|RUN` 时,父侧几乎没有「手」:
|
||||
|
||||
| 缺口 | 后果 |
|
||||
|------|------|
|
||||
| 看不到子源码 / 报错 / stdout | 空想 FIND/REPLACE,输出又臭又长 |
|
||||
| 标准库未进入行动表 | 无法在规划环内用 `fs` / `json` / `subtask` 等 |
|
||||
| 不能用 Marqdo 造工具 | 无法把可复用步骤沉淀为 `##` |
|
||||
| 提示词过长且互相打架 | 模型「继续帮忙」而不停机 |
|
||||
|
||||
业界对 agent 回环的共识:成功标准、停机动作、**确定性行动面**三者必须写清;停机最终靠代码护栏,不只靠 prompt。
|
||||
|
||||
---
|
||||
|
||||
## 3. Marqdo 赋予的特性(相对通用 Plan-and-Move)
|
||||
|
||||
| 特性 | 含义 |
|
||||
|------|------|
|
||||
| 工作簿即程序 | 子执行物是可 `spawn path=` 的 `.mq.md`,不是隐式任务图 |
|
||||
| 固化即记忆 | `DECISION: DONE` → `agent_workbook_solidify` + OKF 晋升 |
|
||||
| `lib/*` 即工具 | 标准库是父可调度能力;经父 helper 或写入工作簿/`tools/` 后调用 |
|
||||
| 补丁即改代码 | `CONTINUE` + 精确 FIND/REPLACE;禁止整文件 LLM 重写 |
|
||||
| 文档即提示 | 站立提示、Skill 摘要、观察切片都是可读 Markdown,而非黑盒 system blob |
|
||||
|
||||
---
|
||||
|
||||
## 4. 循环形状(锁定)
|
||||
|
||||
```text
|
||||
┌──────────────┐
|
||||
│ Plan (LLM) │
|
||||
└──────┬───────┘
|
||||
│ 协议回复
|
||||
┌─────────────┼─────────────┐
|
||||
▼ ▼ ▼
|
||||
READ:/CALL: DECISION: (无效 → error)
|
||||
│ DONE/RUN/
|
||||
│ CONTINUE
|
||||
▼ ▼
|
||||
Act 工具 Move(固化/补丁/spawn)
|
||||
│ │
|
||||
└──────┬──────┘
|
||||
▼
|
||||
Observe(有界)
|
||||
│
|
||||
└──► 回到 Plan 或终止
|
||||
```
|
||||
|
||||
优先级(解析父回复时):
|
||||
|
||||
1. **`CALL:<name>` / `调用:`** — 跑父侧工具,结果并入 observation,再 Plan
|
||||
2. **`READ:<kind>` / `读取:`** — 加深某一观察切片,再 Plan
|
||||
3. **`DECISION:`** — Move(含运行时 solidify / apply_patch / spawn)
|
||||
|
||||
---
|
||||
|
||||
## 5. 观察面(有界、可加深)
|
||||
|
||||
`inspect_workbook` / `await_workbook` 在磁盘上可持有全文;**注入父 prompt 的默认紧凑观察**必须可行动且短:
|
||||
|
||||
| 字段 | 默认 | `READ:` 加深 |
|
||||
|------|------|----------------|
|
||||
| `source_excerpt` | 去 `<!-- … -->` 后的结构摘录,硬顶 ~4KiB / ~80 行 | `READ:source` → 更大但仍有硬顶的摘录 |
|
||||
| `stderr_tail` / `stdout_tail` | 子任务捕获尾部 ~2KiB | `READ:stderr` / `READ:stdout` |
|
||||
| `value` | ≤200 字;否则 `value_preview` + `value_len` | (一般不必加深) |
|
||||
| `slots` | `{key,line,body_len}`;`error` 槽可带短预览 | `READ:slots` |
|
||||
| `has_worker_step` / `solidify_on_done` | 布尔提示 | — |
|
||||
|
||||
`quiet=True` **只表示不污染父 TTY**;file `wait` 仍返回截断后的 `stdout` / `stderr` 供父观察。
|
||||
|
||||
---
|
||||
|
||||
## 6. 工具面
|
||||
|
||||
### 6.1 父侧内建 helper(`CALL:` 首批)
|
||||
|
||||
写在 `ext/ai/agent.mq.md`,由 plan 循环直接调度(**不用** OpenAI function calling):
|
||||
|
||||
| 名称 | 作用 |
|
||||
|------|------|
|
||||
| `workbook_read` | 按 depth 读工作簿摘录 |
|
||||
| `workbook_excerpt` | 结构摘录(默认观察同源) |
|
||||
| `lib_catalog` | 枚举 `lib/*.mq.md` 能力摘要 |
|
||||
| `scratch_tool_write` | 写入 `.marqdo/agent-runs/tools/<name>.mq.md` |
|
||||
|
||||
### 6.2 标准库与造工具
|
||||
|
||||
- **标准库直调(白名单)**:`CALL:lib.fs.read_text`(及 `exists` / `list_dir` / `json.parse` / `json.stringify` / `sys.cwd`)+ 可选 `ARGS:{…}` JSON 行;拒绝 `net.*` / `sys.exec` / 写删类。
|
||||
- **目录**:`lib_catalog` 列出可 CALL 的 dotted 名。
|
||||
- **造工具**:优先 `CONTINUE` + 短 PATCH 在工作簿内新增 `##`;或 `CALL:scratch_tool_write` 沉淀独立工具文件。
|
||||
- **流式**:父 CALL/READ 发 `tool_start` / `tool_end`(view Tool 卡)。
|
||||
- **非目标**:全量 `lib/*` JSON schema 反射;OpenAI function calling。
|
||||
|
||||
---
|
||||
|
||||
## 7. 输出纪律(停机规则)
|
||||
|
||||
父回复**只允许**协议行 + 一行 `SUMMARY` + 短 PATCH(`<20` 行)。禁止长独白 / 行程散文 / 把 observation 粘进 REPLACE。
|
||||
|
||||
修订阶段硬规则(自上而下):
|
||||
|
||||
1. `exit_code==0` 且 `has_value` → **立刻** `DECISION: DONE`(运行时 solidify);`has_worker_step` **不是** CONTINUE 的理由。
|
||||
2. 仅失败 / 无值 / 明确未达目标时才 `CONTINUE`。
|
||||
3. 代码护栏:非 `improve` 时,子已返回值则 **跳过父 LLM**,直接 solidify + DONE。
|
||||
|
||||
---
|
||||
|
||||
## 8. 与 `## step` 的关系
|
||||
|
||||
| | `step`(子) | `plan`(父) |
|
||||
|---|-------------|-------------|
|
||||
| 协议 | `CALL:` 或最终答案 | `CALL:` / `READ:` / `DECISION:` |
|
||||
| 工具来源 | 工作簿 / 调用方 allowlist | 父 helper + 写入的 Marqdo `##` |
|
||||
| 成功出口 | 返回答案文本 | `DONE` + solidify / promote |
|
||||
|
||||
---
|
||||
|
||||
## 9. 实现落点
|
||||
|
||||
| 组件 | 路径 |
|
||||
|------|------|
|
||||
| 设计(本文) | `doc/design/ext-agent-parent.md` |
|
||||
| 多步总设计增量 | `doc/design/ext-agent-plan.md` §4.1 / 协议 |
|
||||
| 子任务 I/O | `src/host/subtask.rs`、`lib/subtask.mq.md` |
|
||||
| 父循环 / 观察 / 提示 | `ext/ai/agent.mq.md` |
|
||||
@@ -0,0 +1,356 @@
|
||||
# 智能体多步(`## 多步` / `## plan`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted;D2a–D2f 已落地;父 Plan-and-Move / OKF 软命中见配套文档** |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 父文档 | [ext-agent.md](ext-agent.md) |
|
||||
| 相关 | [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move 行动面**) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [module-namespace.md](module-namespace.md) · [ai-skill.md](ai-skill.md) · [objects.md](objects.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
单步(`## 单步` / `## step`)适合原子任务。复杂目标需要:
|
||||
|
||||
1. **把分解与执行过程落成一份可运行的 `.mq.md`**(工作簿),而不是藏在进程内的任务图。
|
||||
2. **用子任务真正跑这份工作簿**,与主推理隔离。
|
||||
3. **父智能体作为「智能体开发大师」**:结构化读取执行结果与写回,再二次规划;用**精确补丁**改工作簿代码,并把确定步骤**固化为普通 Marqdo `##`**。
|
||||
4. **允许工作簿演化**——代码与 `<!-- marqdo-out … -->` 均可更新,但**禁止**以整文件 LLM 重写作为修订主路径。
|
||||
5. 子智能体只做不确定的 `单步`;能写成代码的就不要再问模型。
|
||||
|
||||
本文锁定 **`## 多步` / `## plan`** 的语义。总览与分层见 [ext-agent.md](ext-agent.md);实现以 D2 为准。
|
||||
|
||||
---
|
||||
|
||||
## 2. 一句话
|
||||
|
||||
**多步 = 父智能体(开发大师)生成并演进一份子 Marqdo 程序:经 `lib/subtask` 运行它,结构化观察写回与源码,再二次规划并精确打补丁;子 `# 智能体` 只跑 `单步`,确定步骤固化为代码。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 角色与产物
|
||||
|
||||
| 角色 | 职责 |
|
||||
|------|------|
|
||||
| **父智能体** | 持有目标;创建 / 改写工作簿;`spawn path=` 运行工作簿;读执行结果与写回块;决定改代码还是改提示;汇总并写回父文档 |
|
||||
| **工作簿 `.mq.md`** | 任务实现的**详细步骤文档兼程序**:导入、工具、一个或多个子智能体、可固化的普通函数与 `# main` 编排 |
|
||||
| **子智能体** | 工作簿内的 `# 智能体` / `# agent`;走 `单步`(默认);工具表白名单可收窄 |
|
||||
| **子任务通道** | `lib/subtask`:`spawn path=<工作簿>` → `wait`;与工具 `spawn fn=` 同一套能力 |
|
||||
|
||||
| 产物 | 说明 |
|
||||
|------|------|
|
||||
| 工作簿路径 | 默认目录 `.marqdo/agent-runs/`(可参数覆盖);文件名含时间 / 短 id |
|
||||
| 父侧返回值 | 结构化 map:`status`、`goal`、`workbook`(路径)、`result`(子 `# main` 返回值优先)、`summary` / `error`;可选 `observation` |
|
||||
| 写回 | 工作簿内各 `单步` 默认落盘;父 `多步` 调用行亦可汇总写回 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 调用流水线(锁定)
|
||||
|
||||
```text
|
||||
父:`助手`.多步 目标=…
|
||||
▼
|
||||
① 解析参数(目录、深度、是否确认分解、是否覆盖已有工作簿…)
|
||||
▼
|
||||
② 创建(或打开)工作簿 .mq.md
|
||||
- frontmatter:导入 ext/ai/llm|agent、json、writeback、subtask…
|
||||
- **大模型配置与父智能体一致**(见 §5)
|
||||
- 正文:总目标叙述 + 子智能体骨架 / 或父模型生成的首版步骤
|
||||
▼
|
||||
③ 父模型「分解」(非 OKF 命中路径必跑):`phase=decompose`,尚未 spawn;可 `DECISION: RUN` / `CONTINUE`+补丁 / 固化后 `DONE`
|
||||
▼
|
||||
④ lib/subtask:spawn path=<工作簿绝对或相对路径>
|
||||
▼
|
||||
⑤ wait → 收集 `{code, value}`(`# main` 返回)+ 工作簿内写回块;TTY 默认静默
|
||||
▼
|
||||
⑥ 父智能体 **结构化观察**(工作簿最新源码 + 写回槽 + 退出码 + `value`)
|
||||
- 充分 → 汇总,写回父文档,返回
|
||||
- 不足 / 失败 → **二次规划** → 对工作簿打**精确补丁**(禁止整文件重写)→ 回到 ④
|
||||
▼
|
||||
⑦ 触达最大修订轮次或深度 → 以 error / 部分摘要返回
|
||||
```
|
||||
|
||||
要点:
|
||||
|
||||
- **创建文件发生在 `多步` 内**,不是调用方手写脚手架(调用方可传已有 `工作簿=` 路径以续跑)。
|
||||
- **执行工作簿 = 子任务跑整文件**(入口 `# main`),不是父进程内嵌解释子 AST。
|
||||
- **父是智能体开发大师**:读真实执行结果再规划;修订靠精确补丁与代码固化,不靠整文件重生。
|
||||
- **修订循环属于父智能体职责**:同一 `多步` 调用内可多轮「观察 → 规划 → 补丁 → 再 spawn」。
|
||||
|
||||
---
|
||||
|
||||
## 4.1 观察面与补丁(锁定)
|
||||
|
||||
父每次二次规划前必须拿到观察 map(`inspect_workbook` / `await_workbook`)。磁盘可持全文;**注入父 LLM 的默认观察为有界紧凑面**(摘录 + I/O 尾部)。完整语义与 `READ:` / `CALL:` 行动面见 [ext-agent-parent.md](ext-agent-parent.md)。
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `path` | 工作簿路径 |
|
||||
| `source` | 最新全文(磁盘);prompt 默认用 `source_excerpt` |
|
||||
| `exit_code` | 上一轮子任务退出码 |
|
||||
| `value` | 子 `# main` 返回值(经 `await_workbook` / `wait.value`) |
|
||||
| `stdout` / `stderr` | 子任务捕获(`quiet` 仅静音 TTY,不丢弃数据) |
|
||||
| `slots` | 命名写回列表(`key` + `body`) |
|
||||
| `last_ok` / `last_error` | 便捷字段 |
|
||||
|
||||
二次规划输出协议(机器可解析;**禁止**只输出整份 `.mq.md`;**禁止**长独白):
|
||||
|
||||
```text
|
||||
CALL:<parent-tool>
|
||||
READ:source|stderr|stdout|slots
|
||||
|
||||
DECISION: DONE
|
||||
SUMMARY: <一行>
|
||||
|
||||
DECISION: RUN
|
||||
|
||||
DECISION: CONTINUE
|
||||
PATCH:
|
||||
<<<
|
||||
FIND
|
||||
<确切旧片段>
|
||||
===
|
||||
REPLACE
|
||||
<新片段>
|
||||
>>>
|
||||
```
|
||||
|
||||
解析优先级:`CALL` → `READ` → `DECISION`。应用器对文件做**精确** FIND→REPLACE;找不到则报错。`DONE` 时运行时 `agent_workbook_solidify` 固化答案(不必靠长 REPLACE 粘贴子散文)。
|
||||
|
||||
---
|
||||
|
||||
## 4.2 多轮哲学:仅子智能体接力(模式 C)
|
||||
|
||||
复杂 / 多轮目标 = **多份可执行 `.mq.md` 接力**,经 OKF 索引与复用;父 `plan` 聚合各子 `wait.value` 为 `result`。
|
||||
|
||||
| 做 | 不做 |
|
||||
|----|------|
|
||||
| 每主题 / 子目标一份工作簿(`resources/` / `explore/`) | 单文件无限追加「对话日志」 |
|
||||
| OKF task/skill 做索引与命中 | 单文件状态机表冒充流程 UI |
|
||||
| `# main` **返回**答案;`quiet` 只管 TTY | 依赖子 `print` 把答案刷到父终端 |
|
||||
---
|
||||
|
||||
## 5. 大模型配置与父保持一致
|
||||
|
||||
工作簿内构造子智能体时:
|
||||
|
||||
| 从父继承 | 说明 |
|
||||
|----------|------|
|
||||
| `model` / `大模型` 句柄字段 | `api_key`、`base_url`、`model`、`suffix`、`bearer` 及拼装前缀等与父相同 |
|
||||
| 默认站立提示基调 | 可追加「只负责本工作簿内子任务」等收窄句;不得更换供应商端点 |
|
||||
|
||||
实现约定(D2):
|
||||
|
||||
1. 父把当前 llm 句柄 **序列化进工作簿**(例如构造段直接写 `> llm.llm` 前先 `load_env`,或写入由父生成的配置表 / 环境约定)。
|
||||
2. 优先:**工作簿与父共享同一套 `OPENAI_*` / `.env` 加载路径**,子文件内 `> llm.load_env` + `> llm.llm`(或中文面),避免把密钥明文写进工作簿。
|
||||
3. 若父句柄来自非默认 env,父须在生成工作簿时写出等价构造(仍禁止把密钥写进 git 跟踪路径;工作簿目录应默认被 ignore)。
|
||||
|
||||
**禁止**:子工作簿默默改用另一 `base_url` / 另一模型名,除非调用方显式参数允许覆盖(v1 不提供覆盖;一律继承)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 工作簿内容形态
|
||||
|
||||
### 6.1 推荐:多个子智能体
|
||||
|
||||
面对多种情形时,**多个 `# 智能体`(或一个类型多次构造)** 优于单一巨型提示:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: agent-run-…
|
||||
> ext/ai/llm.mq.md
|
||||
> ext/ai/agent.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/writeback.mq.md
|
||||
> lib/subtask.mq.md
|
||||
---
|
||||
|
||||
# 总目标
|
||||
|
||||
(父写入的目标叙述)
|
||||
|
||||
## 工具甲
|
||||
…
|
||||
|
||||
# main
|
||||
|
||||
> llm.load_env path=…
|
||||
|
||||
*`模型` = > llm.llm *
|
||||
|
||||
*`调研` = > agent.agent model=`模型` tools=`表甲` standing=… *
|
||||
*`撰写` = > agent.agent model=`模型` tools=`表乙` standing=… *
|
||||
|
||||
*`a` = > `调研`.step task=… *
|
||||
*`b` = > `撰写`.step task=… *
|
||||
```
|
||||
|
||||
### 6.2 也可:一个智能体多次单步
|
||||
|
||||
适合线性流水线;每次 `step` 仍默认写回,便于中断续跑。
|
||||
|
||||
### 6.3 固化为代码(强烈推荐)
|
||||
|
||||
一旦某步输入输出稳定(例如「取今日日期」「解析固定 JSON」),父智能体应把该步 **改写成普通 `##` 函数 + 直接调用**,不再经子智能体推理:
|
||||
|
||||
| 不确定 | 已确定 |
|
||||
|--------|--------|
|
||||
| `` > `子`.step task=… `` | `` *`x` = > 本地函数 … `` |
|
||||
| 宽工具表 + 长 standing | 窄函数、表驱动、分支 `1.` / `2.` |
|
||||
|
||||
**多步的价值之一就是把「试出来的正确步骤」沉淀成工作簿里的代码**,而不仅是 chat 痕迹。
|
||||
|
||||
### 6.4 持续更新的两类内容
|
||||
|
||||
| 更新 | 含义 |
|
||||
|------|------|
|
||||
| **代码更新** | 增删 `##`、改 `# main` 编排、改工具表、把 step 换成固化调用、修分支 |
|
||||
| **写回注释更新** | `<!-- marqdo-out ok|error -->` 被单步 / 父汇总刷新;替换时**不得累积空行**(见 writeback 实现约定) |
|
||||
|
||||
工作簿是活文档:子任务跑完后磁盘上的 `.mq.md` 应比创建时更「像最终报告」。
|
||||
|
||||
---
|
||||
|
||||
## 7. 单步自动写回(服务多步)
|
||||
|
||||
### 7.1 决议
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **默认** | `单步` / `step` **自动写回** 本步结果(命名槽) |
|
||||
| **开关** | 参数 `写回` / `writeback`(布尔,默认 `真` / `True`) |
|
||||
| **槽** | 成功 → `key=ok`;失败 → `key=error`;正文为结构化 map 的 JSON(或与现 live 样例一致的 stringify) |
|
||||
| **锚点** | 本步调用行(与现 `writeback.record` 锚点规则一致) |
|
||||
|
||||
这样:
|
||||
|
||||
- 父 / 工作簿**不必**靠提示词强迫模型「请记得写回」。
|
||||
- 编排方仍可 `写回=假` 拿到纯 map,自行 `writeback.record`(测试、嵌套去重时有用)。
|
||||
|
||||
### 7.2 与父写回的分工
|
||||
|
||||
| 层级 | 写什么 |
|
||||
|------|--------|
|
||||
| 子 `step`(默认开) | 该步 decision / tool / result 或 error |
|
||||
| 父 `plan` | 工作簿路径、轮次、汇总摘要;可选把关键子 ok 块索引写在父调用行下 |
|
||||
|
||||
**推荐**:载荷以子 `# main` 返回值(`wait.value` → `plan.result`)为准;写回作审计与 step 缓存。避免只靠 stdout(默认静默会丢弃)。
|
||||
|
||||
### 7.3 返回值
|
||||
|
||||
`step` 仍返回结构化 map(与现 D1 一致)。自动写回是**附加副作用**,不取代返回值。
|
||||
|
||||
---
|
||||
|
||||
## 8. 父智能体上下文(每次修订 / 汇总前)
|
||||
|
||||
父在多步循环中每次「想下一步」时,注入不得弱于单步,且额外包含工作簿:
|
||||
|
||||
| 片段 | 来源 |
|
||||
|------|------|
|
||||
| 站立提示 | 父构造 |
|
||||
| 总目标 | `多步` 实参 |
|
||||
| **父文件源码** | `agent_module_source` |
|
||||
| **调用位置** | `agent_call_site` |
|
||||
| **Marqdo Skill** | `agent_marqdo_skill` |
|
||||
| 工作簿全文 / 写回 / 子返回 | `inspect_workbook`(源码 + slots + 退出码 + `value`) |
|
||||
| 子任务退出码 | `subtask.wait` |
|
||||
| 对话 / 历史 | 父 session;真相以写回为准 |
|
||||
|
||||
父模型输出必须是 **DONE / CONTINUE+精确补丁** 协议(见 §4.1),禁止整文件重写。
|
||||
|
||||
---
|
||||
|
||||
## 9. 公开 API(D2 契约)
|
||||
|
||||
### 9.1 `## 多步` / `## plan`
|
||||
|
||||
| 参数 | 中 / 英 | 默认 | 说明 |
|
||||
|------|---------|------|------|
|
||||
| 目标 | `目标` / `goal` | 必填 | 复杂任务描述 |
|
||||
| 工作簿目录 | `工作簿目录` / `workbook_dir` | `.marqdo/agent-runs` | 新建文件所在目录 |
|
||||
| 工作簿 | `工作簿` / `workbook` | 空 | 若给路径则**续跑 / 修订**该文件,跳过空白创建 |
|
||||
| 最大深度 | `最大深度` / `max_depth` | `2` | 工作簿内再调 `多步` 的嵌套上限;叶强制单步 |
|
||||
| 最大轮次 | `最大轮次` / `max_rounds` | 实现选定(如 `4`) | 父「改文件 → 再执行」循环上限 |
|
||||
| 确认分解 | `确认分解` / `confirm` | `假` | `真` 时首版工作簿生成后暂停(返回 pending + 路径),不自动 spawn |
|
||||
| 写回 | `写回` / `writeback` | `真` | 父侧汇总写回 |
|
||||
| 骨架 | `骨架` / `skeleton` | `single` | `single` 单 worker;`dual` 为 research→writer 两子智能体 |
|
||||
|
||||
返回 map(字段名英文字段,中文面可读同一结构):
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `status` | `ok` / `error` / `pending`(待确认) |
|
||||
| `goal` | 回显目标 |
|
||||
| `workbook` | 工作簿路径 |
|
||||
| `rounds` | 实际执行轮次 |
|
||||
| `summary` | 成功时的汇总 |
|
||||
| `error` | 失败信息 |
|
||||
|
||||
### 9.2 `## 单步` / `## step`(修订)
|
||||
|
||||
在 D1 参数上增加:
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `写回` / `writeback` | `真` | 是否自动 `record` 到 ok/error 槽 |
|
||||
|
||||
### 9.3 内部辅助(非稳定对外)
|
||||
|
||||
工作簿模板渲染、从父句柄生成子文件 frontmatter、解析子写回摘要等——可随实现调整。
|
||||
|
||||
---
|
||||
|
||||
## 10. 安全与边界
|
||||
|
||||
| 风险 | 对策 |
|
||||
|------|------|
|
||||
| 无限修订 / 嵌套 | `最大轮次`、`最大深度`;叶任务禁止再 `plan` |
|
||||
| 工作簿写爆仓库 | 默认目录 `.marqdo/agent-runs/` + gitignore;禁止默认写到 `lib/` / `ext/` |
|
||||
| 密钥进工作簿 | 继承 env / load_dotenv,不写明文 key |
|
||||
| 子文件乱改父仓 | 子任务 cwd / fs_root 落到工作簿目录;工具表白名单 |
|
||||
| 写回空行膨胀 | 替换跨度含 `-->` 行尾换行(已实现) |
|
||||
| 并发写同一工作簿 | writeback 全局锁;同一 plan 内串行 spawn 为 v1 默认 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 与旧 §3.2 叙述的差异(显式)
|
||||
|
||||
| 旧粗述 | 本文锁定 |
|
||||
|--------|----------|
|
||||
| 分解表 + 每行一个子智能体实例 | **整文件工作簿**可含多智能体与固化代码;表只是可选骨架 |
|
||||
| 子任务默认单步,写回在流水线步骤里点到为止 | **单步默认自动写回**;父负责修订循环与汇总 |
|
||||
| 缓存命中略写 | **以 OKF 任务知识包为准**([okf.md §7](okf.md)):Task→Skill→resource 命中则跳过父模型;D2 + O2 已落地;人读目录见 O3 `marqdo catalog` |
|
||||
| 父上下文未强调工作簿全文 | 父每次修订前必须能读**最新工作簿 + 写回** |
|
||||
|
||||
---
|
||||
|
||||
## 12. 实现路线(D2)
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| D2a | `step` 增加 `writeback=`(默认真);金样例改默认行为并保留 `writeback=False` 测例 | **done** |
|
||||
| D2b | 工作簿模板 + 创建路径 + 父 llm 继承;`inspect_workbook` 观察面 | **done** |
|
||||
| D2c | `plan`:生成 → `spawn path` → wait → **观察** → 返回;`confirm` | **done** |
|
||||
| D2d | 二次规划 + **精确补丁**循环(`max_rounds`);禁止整文件重写 | **done**(主路径) |
|
||||
| D2e | 多子智能体模板与固化提示 | **done**(`skeleton=dual` + Solidify 段 + 父规划优先级) |
|
||||
| D2f | 离线骨架金样例 + 可选 live 多步 | **done**(decision 离线 + `agent-plan-live`) |
|
||||
|
||||
---
|
||||
|
||||
## 13. 决议摘要
|
||||
|
||||
1. **`多步` 自动创建(或续跑)工作簿 `.mq.md`**,内容为任务的详细可执行步骤。
|
||||
2. **子文件大模型配置与父一致**(共享 env / 等价句柄;v1 无静默换模)。
|
||||
3. **经 `lib/subtask` 启动该文件**;可多轮执行。
|
||||
4. **工作簿内推荐多个智能体**;也允许单智能体多 `step`;**确定步骤固化为代码**。
|
||||
5. **工作簿持续更新**:代码 + `marqdo-out`。
|
||||
6. **`单步` 默认自动写回**(`写回=` 可关);父维护汇总写回。
|
||||
7. **父具备源码、Skill、位置、历史与工作簿观察面**,二次规划后以**精确补丁**修改再执行(禁止整文件重写主路径)。
|
||||
|
||||
---
|
||||
|
||||
## 14. 一句话
|
||||
|
||||
**多步不是更长的聊天,而是父智能体编写、运行、修订一份子 Marqdo 程序——程序里的智能体可多可少,写回默认打开,能写成代码的就不要再问模型。**
|
||||
+299
-87
@@ -2,136 +2,348 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted · **thin agent loop locked** |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [objects.md](objects.md) |
|
||||
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
|
||||
## What we are building
|
||||
## 0. 为什么要改掉旧方案
|
||||
|
||||
An **agent-development framework** — smallest runtime surface for agents on Marqdo.
|
||||
旧版把智能体做成「黑盒对话循环」:隐藏提示拼装、`TOOL:<name>` 协议、host 历史袋、一次(或几次)模型往返。这是对 LangChain 类框架的平移,**背离了 Marqdo 的初衷**。
|
||||
|
||||
**Not** task-dispatch, **not** bundled domain tools, **not** layout/match/ticket helpers in official ext.
|
||||
Marqdo 的宪法是 **代码即文档、文档即知识库**:
|
||||
|
||||
| In scope | Out of scope (your runbook / your code) |
|
||||
|----------|-------------------------------------------|
|
||||
| `# 智能体` ctor | `## 技能匹配` · `## 分配任务` · `## 创建工单` … |
|
||||
| `## 执行` | Anything task-specific in `ext/` |
|
||||
| `## 清空历史` | |
|
||||
| Auto context: source, position, history, Marqdo skill | |
|
||||
| 旧方案的问题 | Marqdo 应有的形态 |
|
||||
|--------------|-------------------|
|
||||
| 提示词藏在框架字符串里,与编排源码分离 | 提示、工具、任务、结果都在 `.mq.md` 里,人与模型同读同写 |
|
||||
| 执行过程是不透明的 chat transcript | 思考与行动写回文档;`view` / `debug` 可跟可审 |
|
||||
| 复杂任务与简单任务同一套循环 | **单步**与**多步(工作簿)**两级模型 |
|
||||
| 成功经验留在进程内存 | **自写回**做成果缓存与失败知识;同类任务可复用 |
|
||||
|
||||
## Repo layout (`ext/`)
|
||||
本文件锁定新方向。仓库里现有的 `ext/ai/agent.mq.md` / `智能体.mq.md`(TOOL: 薄循环)视为 **待替换实现**,以本文为准。
|
||||
|
||||
Official extensions for LLM + agent live under **`ext/ai/`** only. No flat `.mq.md` at `ext/` root; future domains get their own subdir.
|
||||
---
|
||||
|
||||
## 1. 我们在建什么
|
||||
|
||||
一个 **文档驱动的智能体开发框架**:编排本身就是可读的 `.mq.md`;模型吃的是这份文档与调用位置;写回让思考过程可控、可调试、可沉淀。
|
||||
|
||||
**不是** 外挂任务队列、**不是** 官方捆绑领域工具、**不是** 第二套聊天栈(模型 I/O 仍用 `ext/ai/llm`)。
|
||||
|
||||
| 在范围内 | 在范围外(应用 / runbook) |
|
||||
|----------|---------------------------|
|
||||
| `# 智能体` / `# agent` 构造 | 领域工具:`## 查天气`、`## 分配任务` … |
|
||||
| `## 单步` / `## step` | 业务表格、队列、工单流程 |
|
||||
| `## 多步` / `## plan`(生成并驱动工作簿) | 具体分解策略模板库(可放用户仓) |
|
||||
| 上下文:源码、调用位置、工作簿路径、Skill | 第二套 HTTP / 聊天协议 |
|
||||
| 与 `lib/writeback`、**`lib/subtask`(工具执行通道)**、**`lib/plugin` + ABI v2 `plugins/agent`** 协作 | 把领域技能塞进官方 `ext/ai/`;在 `ext` 内直调 `host_*` |
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心理念:编排可读,过程可写回
|
||||
|
||||
1. **提示词与代码不分离**
|
||||
站立提示、工具表、任务叙述都写在 `.mq.md` 里。框架把**当前模块源码**与**调用位置**交给模型,而不是另起一套 system prompt 黑盒。
|
||||
|
||||
2. **把 Marqdo 源码交给智能体**
|
||||
每次推理可注入:入口 / 工作簿 `.mq.md` 全文(或相关切片)、`host_call_site`(路径、函数、行)、`skills/marqdo`(写 / 读 `.mq.md` 的语法纪律)。模型输出应优先是 **可解释的决策** 与 **对文档的结构化改动意图**,而不是私有 JSON 协议。
|
||||
|
||||
3. **自写回 = 思考轨迹 + 成果缓存**
|
||||
成功或失败都写回文档(见 [stdlib-writeback.md](stdlib-writeback.md))。成功块可被后续同类任务命中,避免重复失败;失败块成为可读的「避坑记录」。`marqdo view` 在语句下展示 output-card,调试面可对齐同一份真相。
|
||||
|
||||
4. **相对其他框架的优势**
|
||||
无需外挂向量库 / 状态机才能「记住」某次子任务已成功:记忆就是仓库里的 Markdown。审计、合规、复盘 = `git log` + 打开工作簿。
|
||||
|
||||
---
|
||||
|
||||
## 3. 两级执行模型
|
||||
|
||||
### 3.1 模式 A — 单步(原子任务)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **输入** | 小任务描述 + 必要上下文(工具表、站立提示、源码切片) |
|
||||
| **过程** | 一次(或有限次)推理;可选调用 **runbook 内** 的工具函数;结果写回 |
|
||||
| **输出** | 原子结果(文本 / 表 / 句柄字段) |
|
||||
| **适用** | 问答、单一工具、确定性一步 |
|
||||
|
||||
公开方法(中 / 英):`## 单步` / `## step`。
|
||||
|
||||
示意(语法外形;实现以落地代码为准):
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/智能体.mq.md
|
||||
> ext/ai/大模型.mq.md
|
||||
> lib/自写回.mq.md
|
||||
> lib/时间.mq.md
|
||||
---
|
||||
|
||||
## 获取时间
|
||||
|
||||
*`u` = > 时间.此刻秒 *
|
||||
**> 时间.格式化 秒=`u` 格式=%Y-%m-%d**
|
||||
|
||||
# main
|
||||
|
||||
*`模型` = > 大模型.大模型 *
|
||||
`工具表` =
|
||||
| 工具 |
|
||||
|------|
|
||||
| 获取时间 |
|
||||
|
||||
*`助手` = > 智能体 大模型=`模型` 工具=`工具表` 站立提示=你是可调试的 Marqdo 助手。 *
|
||||
|
||||
*`结果` = > `助手`.单步 任务=今天日期是什么?请在需要时调用工具。 *
|
||||
> 打印 内容=`结果`
|
||||
```
|
||||
|
||||
单步约定:
|
||||
|
||||
- 模型看到的上下文 **包含本文件源码与调用位置**,因此「有哪些 `##` 工具」对模型是可见的;行动约定写在提示里(人可读),例如单独一行 `CALL:<工具名>` / `调用:<工具名>`,最终答案则直接正文回复。
|
||||
- 工具仍是 **runbook 里的 `##` 函数**(v1 以零参为主;可经 `args=` 扩展)。
|
||||
- **调用工具走 [`lib/subtask`](stdlib-subtask.md)**:白名单校验通过后 `spawn fn=<名>`(中文面 `启动 函数=`)→ `wait` / `等待`,而不是进程内直接 `call_fn`。这样工具与主推理隔离在子任务语义下,并可与并行、超时、探测同一套主机能力对齐。
|
||||
- 结束后用自写回记录:任务摘要、选用工具、结果或错误。
|
||||
|
||||
### 3.2 模式 B — 多步 / 复杂执行(工作簿)
|
||||
|
||||
> **完整锁定设计**见 [**ext-agent-plan.md**](ext-agent-plan.md)。以下为摘要。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **输入** | 复杂目标 |
|
||||
| **过程** | 父智能体**创建(或续跑)工作簿** →(非命中)**父先分解** → **`lib/subtask` spawn** 跑子文件 → 观察写回 → **父修订补丁后再执行**(有轮次上限) |
|
||||
| **输出** | 汇总 map(含 `result`)+ 磁盘上的工作簿(代码与 `marqdo-out` 均可演化) |
|
||||
| **适用** | 需分解、多情形、可固化步骤、可复用子成果的任务 |
|
||||
|
||||
公开方法:`## 多步` / `## plan`。
|
||||
|
||||
流水线要点:
|
||||
|
||||
1. **创建工作簿** — 默认 `.marqdo/agent-runs/`;内容为任务的详细可执行步骤(导入、工具、`# main`、子智能体)。
|
||||
2. **模型配置继承父智能体** — 共享 env / 等价 llm 句柄;v1 不静默换模。
|
||||
3. **子任务执行整文件** — 不是父进程内嵌解释。
|
||||
4. **工作簿内推荐多个 `# 智能体`**;也允许一个智能体多次 `单步`;**已确定步骤应固化为返回答案的普通代码**(多轮 = 多文件接力 + OKF,见 [ext-agent-plan.md §4.2](ext-agent-plan.md))。
|
||||
5. **持续更新** — 代码修订 + 写回注释刷新(替换不累积空行)。
|
||||
6. **`单步` 默认自动写回**(`写回=` / `writeback=` 可关),父侧再汇总写回。
|
||||
7. **父上下文** — 与单步同级的源码 / Skill / 调用位置 / 历史,外加工作簿全文与子写回。
|
||||
|
||||
示意:
|
||||
|
||||
```markdown
|
||||
*`报告` = > `编排`.多步 目标=调研并汇总三篇资料的要点 *
|
||||
> 打印 内容=`报告`
|
||||
```
|
||||
|
||||
工作簿概念形状与修订循环细节 → [ext-agent-plan.md](ext-agent-plan.md)。
|
||||
## 4. 分层与仓库布局
|
||||
|
||||
```text
|
||||
ext/
|
||||
ai/
|
||||
llm.mq.md
|
||||
大模型.mq.md
|
||||
agent.mq.md
|
||||
智能体.mq.md
|
||||
llm.mq.md / 大模型.mq.md # 模型 I/O
|
||||
agent.mq.md / 智能体.mq.md # 本框架(按本文重写)
|
||||
```
|
||||
|
||||
Import: `> ext/ai/智能体.mq.md` · `> ext/ai/llm.mq.md`
|
||||
| 层 | 职责 |
|
||||
|----|------|
|
||||
| **应用 runbook** | 领域 `##` 工具、任务表、是否人工确认分解 |
|
||||
| **`ext/ai/agent`** | 单步 / 多步、工作簿生成、子智能体编排、写回约定 |
|
||||
| **`ext/ai/llm`** | 补全 / 聊天 |
|
||||
| **`lib/writeback`** | 持久化输出块 |
|
||||
| **`lib/subtask`** | **工具调用与(多步时)子智能体并行的执行通道**;见 [stdlib-subtask.md](stdlib-subtask.md) |
|
||||
|
||||
## Layering
|
||||
安装:[`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`(`.mq.md` + `native/libagent.so`)。导入:`> ext/ai/智能体.mq.md`。
|
||||
|
||||
| Layer | Role |
|
||||
|-------|------|
|
||||
| **Your runbook** | Tables, loops, **your** tools & logic |
|
||||
| **`ext/ai/llm`** | Model I/O |
|
||||
| **`ext/ai/agent`** | Framework: ctor + `执行` + `清空历史` |
|
||||
| **`lib/*`** | Generic I/O |
|
||||
**原生插件(ABI v2)**:`ext/ai/agent` 经 `lib/plugin` 加载;优先 `> plugin.native_path name=agent`,否则按序查找:
|
||||
|
||||
```text
|
||||
> ext/ai/智能体.mq.md
|
||||
▼
|
||||
# 智能体 (大模型, 工具, 用户提示信息?)
|
||||
## 执行
|
||||
## 清空历史
|
||||
```
|
||||
1. `MARQDO_AGENT_PLUGIN`(显式 `.so` / `.dylib` 路径)
|
||||
2. `CARGO_TARGET_DIR/{debug,release}/libagent.so`(或 `.dylib`)
|
||||
3. cwd `target/{debug,release}/`
|
||||
4. 可执行文件旁 `libagent.*` 或 `target/debug/`
|
||||
5. `MARQDO_EXT/native/libagent.*`(`marqdo ext add agent` 安装)
|
||||
|
||||
`工具` = caller-supplied **function catalog** (table of `##` names); framework resolves names via `call_fn` / `调用` and runs the matching zero-arg function in the runbook module.
|
||||
本地开发须先 `cargo build -p marqdo_plugin_agent`(或 `ext add agent` / 设 `MARQDO_AGENT_PLUGIN`)。详见 [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md)。
|
||||
|
||||
Install: [`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`.
|
||||
**分层纪律(硬规则,勿破)**:
|
||||
|
||||
### Tools (v1)
|
||||
1. `ext/**/*.mq.md` **禁止**出现任何 `host_*` / `host_` 调用。
|
||||
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
|
||||
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
|
||||
4. 进程退出用 `sys.exit` / `系统.退出`,不用裸 `exit`。
|
||||
|
||||
Tools are **not** framework builtins — you define `## 函数名` in your runbook and list names in a table:
|
||||
官方 `ext/ai/` 用 `lib/*` 包装或插件注册名;见 [module-namespace.md](module-namespace.md) §8 · [ext-abi.md](ext-abi.md)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 公开 API(目标契约)
|
||||
|
||||
| 中文 | 英文 | 角色 |
|
||||
|------|------|------|
|
||||
| `# 智能体` | `# agent` | 构造:`大模型`/`model`,`工具`/`tools`,可选 `站立提示`/`standing` |
|
||||
| `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;返回结构化 map;**默认自动写回**(`写回=` / `writeback=` 可关) |
|
||||
| `## 多步` | `## plan` | 建/续工作簿 → subtask 跑文件 → 修订循环 → 汇总(见 [ext-agent-plan.md](ext-agent-plan.md)) |
|
||||
| `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 |
|
||||
| `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 |
|
||||
|
||||
构造参数(v1):
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `大模型` / `model` | `ext/ai/llm` 句柄 |
|
||||
| `工具` / `tools` | 工具名表(单列文本,或多列且含 `工具`/`tools`/`name`) |
|
||||
| `站立提示` / `standing` | 写在文档里的常驻说明(可空) |
|
||||
|
||||
`## 单步` 参数:`任务` / `task`;可选 `写回` / `writeback`(默认真)、深度、是否强制不用缓存等。
|
||||
`## 多步` 参数:`目标` / `goal`;可选 `工作簿目录`、`工作簿`(续跑路径)、`最大深度`、`最大轮次`、`确认分解` —— 详见 [ext-agent-plan.md §9](ext-agent-plan.md)。
|
||||
|
||||
模块内辅助函数(组装上下文、解析模型回复、匹配写回缓存)**不是**稳定对外契约,可随实现调整。
|
||||
|
||||
---
|
||||
|
||||
## 6. 工具表与子任务调用
|
||||
|
||||
工具 **不是** 框架内置能力。在 runbook 定义 `##`,再用表登记名称:
|
||||
|
||||
```markdown
|
||||
`工具表` =
|
||||
| 工具 |
|
||||
|------|
|
||||
| 获取时间 |
|
||||
| 分配任务 |
|
||||
| 读取摘要 |
|
||||
```
|
||||
|
||||
- Single-column table → list of function **names** (text).
|
||||
- Multi-column table → each row is a map; name from column `工具` / `tools` / `name`.
|
||||
- Marqdo has no first-class function values in tables yet; the name must match a `##` in the same module (or imports). `执行` calls it with `call_fn` after the model replies `TOOL:<name>`.
|
||||
- Do **not** use `parse text=["fn"]` for the tools list — unquoted identifiers inside `parse` are evaluated as calls.
|
||||
- 单列表 → 名称列表。
|
||||
- 多列表 → 从列 `工具` / `tools` / `name` 取名。
|
||||
- 名称须对应当前模块(或导入可见)的 `##`。
|
||||
- **不要** 用 `parse text=["fn"]` 列工具(未加引号的标识符会被当成调用)。
|
||||
|
||||
### 6.1 调用路径(锁定)
|
||||
|
||||
```text
|
||||
模型回复含 CALL:<名> / 调用:<名>
|
||||
▼
|
||||
host_tool_allowed(工具表白名单)
|
||||
▼
|
||||
lib/subtask:spawn fn=<名> → wait
|
||||
▼
|
||||
工具返回值写回上下文 / 自写回
|
||||
```
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 英文面 | `> spawn fn=`名`` → `> wait id=`…`` |
|
||||
| 中文面 | `> 启动 函数=`名`` → `> 等待 id=`…`` |
|
||||
| 可选 | `args=` / `参数=` 传给带形参的工具;多工具并行时多次 `spawn` 再 `wait_all` / `等待全部` |
|
||||
|
||||
**非目标:** 以裸 `call_fn` 作为框架默认工具通道(应用仍可直接 `call_fn`,但官方智能体走子任务库)。
|
||||
|
||||
领域逻辑永远留在应用文件,不进官方 `ext/ai/`。
|
||||
|
||||
---
|
||||
|
||||
## Public API (v1)
|
||||
## 7. 上下文注入(每次单步 / 子步)
|
||||
|
||||
| | Role |
|
||||
|--|------|
|
||||
| `# 智能体` / `# agent` | **大模型**, **工具**, optional **用户提示信息** |
|
||||
| `## 执行` / `## run` | **额外信息**; context + LLM + history append |
|
||||
| `## 清空历史` / `## clear_history` | Wipe history on this handle |
|
||||
必须可注入(实现可切片,但不得默默丢掉「代码即文档」):
|
||||
|
||||
Module-level `##` helpers (e.g. context assembly) are internal — not public contract.
|
||||
| 片段 | 来源 |
|
||||
|------|------|
|
||||
| 站立提示 | 构造参数 / 文档正文 |
|
||||
| 任务 / 目标 | 方法实参 |
|
||||
| 工具表(人可读) | 构造参数 |
|
||||
| **当前 `.mq.md` 源码** | 插件 `agent_module_source`(经 ABI v2 `host_query`) |
|
||||
| **调用位置** | 插件 `agent_call_site` |
|
||||
| **Marqdo skill** | 插件 `agent_marqdo_skill` |
|
||||
| Marqdo Skill | `skills/marqdo/`(`MARQDO_SKILL` 可覆盖) |
|
||||
| 相关写回块 | `lib/writeback` 的 `get` / `list` |
|
||||
|
||||
### Auto context (each `执行`)
|
||||
|
||||
- `.mq.md` source
|
||||
- Call-site / position
|
||||
- Conversation history on this handle
|
||||
- Marqdo skill (`skills/marqdo/`)
|
||||
|
||||
### History (v1)
|
||||
|
||||
- Host-backed id per handle
|
||||
- Append after each successful `执行`
|
||||
- `清空历史` ships with `执行`
|
||||
禁止:把整份 Skill + 全文源码藏进不可审查的二进制提示且不在文档中留迹。框架拼装的提示应能在调试时落盘或写回(至少摘要)。
|
||||
|
||||
---
|
||||
|
||||
## Example runbook (application — not framework)
|
||||
## 8. 自写回与缓存语义
|
||||
|
||||
依赖 [stdlib-writeback.md](stdlib-writeback.md):`record` / `写回` → `<!-- marqdo-out … -->`。
|
||||
|
||||
### 8.1 单步返回值与默认写回
|
||||
|
||||
`单步` / `step` 返回结构化 map,并在 **`写回` / `writeback` 默认真** 时自动 `record` 到命名槽(成功 `ok` / 失败 `error`)。关闭写回则行为与早期「纯返回值」一致,由编排方自行 `writeback.record`。
|
||||
|
||||
| 字段 | 何时 | 含义 |
|
||||
|------|------|------|
|
||||
| `status` | 总是 | `ok` / `error` |
|
||||
| `task` | 总是 | 本步任务 |
|
||||
| `decision` | 总是 | 模型首轮输出(含 CALL 行等) |
|
||||
| `tool` / `tool_result` | 成功且调了工具 | 工具名与子任务返回 |
|
||||
| `result` | 成功 | 最终答复 |
|
||||
| `error` | 失败 | 错误信息 |
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/智能体.mq.md
|
||||
> ext/ai/大模型.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`模型` = > 大模型 *
|
||||
*`工具名` = | 技能匹配 | 分配任务 | … |
|
||||
*`助手` = > 智能体 大模型=`模型` 工具=`工具名` 用户提示信息=… *
|
||||
|
||||
- [任务](任务队列)
|
||||
> `助手`.清空历史
|
||||
*`结果` = > `助手`.执行 额外信息=`任务` *
|
||||
*`out` = > `助手`.step task=… *
|
||||
*`回复` = > json.get value=`out` key=result *
|
||||
# 默认已写回;若 writeback=False 则需自行 record:
|
||||
# > writeback.record value=`body` key=ok
|
||||
```
|
||||
|
||||
Domain `##` functions live in **this file** or your lib — never in `ext/ai/`.
|
||||
命名槽 `ok` / `error` 互不覆盖;锚点为调用行。多步工作簿内依赖此默认写回,避免靠提示词强制落盘 —— 见 [ext-agent-plan.md §7](ext-agent-plan.md)。
|
||||
|
||||
**命中规则(后续缓存)**:读 `key=ok` 且非占位时可复用。失败知识读 `key=error`。
|
||||
用户可 `clear key=ok` / `clear key=error` 强制重跑。
|
||||
|
||||
复杂执行中,子结果写回优先落在 **工作簿** 文件;父 `多步` 维护汇总写回。
|
||||
|
||||
### 8.2 Live 金样例
|
||||
|
||||
[`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md):`agent.step`(**默认写回** `ok`/`error`)+ 子任务工具。凭证:`tests/ext/.env`;`> llm.load_env path=.env` 相对**源文件目录**。需已构建 agent 原生库(见 §4)。
|
||||
---
|
||||
|
||||
## 9. 安全与边界
|
||||
|
||||
| 风险 | 对策 |
|
||||
|------|------|
|
||||
| 无限多步递归 | `最大深度`(默认小,如 2);叶任务强制单步 |
|
||||
| 工具越权 | 仅工具表白名单;子智能体可传更窄的表 |
|
||||
| 工作簿爆炸 | 统一目录、命名含时间 / id;可选总超时 |
|
||||
| 缓存过期 | 签名 + 时间戳;手动清块 |
|
||||
| 模型乱改仓库 | 写回 API 约束写入形态;多步生成文件限于工作簿目录 |
|
||||
|
||||
---
|
||||
|
||||
## Shipped / roadmap
|
||||
## 10. 相对旧 API 的迁移
|
||||
|
||||
| Item | Status |
|
||||
|------|--------|
|
||||
| `ext/ai/` + framework + context injection | in progress |
|
||||
| Live `执行` test (`tests/ext/agent-run-live.mq.md` + `.env`) | shipped |
|
||||
| Tool-call loop in `执行` (`TOOL:<name>` → `call_fn`) | shipped |
|
||||
| 旧(废弃方向) | 新 |
|
||||
|----------------|----|
|
||||
| 唯一的 `## 执行` / `## run` + 隐藏 TOOL: 循环 | `## 单步` / `## 多步` |
|
||||
| host 历史袋为真相 | 文档写回 + 工作簿为真相;历史袋至多辅助 |
|
||||
| 提示全在框架字符串 | 站立提示与任务在 `.mq.md`;源码注入 |
|
||||
| `tests/ext/agent-smoke` 测 TOOL 上下文拼接 | 重写为单步离线 / 写回 / 工作簿骨架测试 |
|
||||
|
||||
### Non-goals
|
||||
兼容:可短期保留 `## 执行` 作为 `## 单步` 的别名,但文档与金样例迁到新名后删除别名。
|
||||
|
||||
- Domain tools in official ext
|
||||
- Flat `ext/*.mq.md` at repo root
|
||||
- Second chat stack beside llm
|
||||
---
|
||||
|
||||
## 11. 实现路线(文档锁定后)
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| D0 | 本文 Accepted;废弃 thin TOOL 设计叙述 | **本文件** |
|
||||
| D1 | 重写 `ext/ai/agent.mq.md` / `智能体.mq.md`:`单步` + 源码/位置注入 + **子任务调工具** + **结构化返回值**;运行时经 **ABI v2 agent 插件**(禁 ext 直调 host) | **done** |
|
||||
| D2 | `多步`:按 [ext-agent-plan.md](ext-agent-plan.md)(观察→精确补丁;禁止整文件重写);**D2a–D2f 主路径已落地** | **done** |
|
||||
| D3 | 金样例:离线单步 / 写回;**live 单步**(`tests/ext/agent-run-live.mq.md`);多步骨架(可不打网) | **live done** |
|
||||
| D4 | `view` / `debug` 对工作簿与写回块的导航体验 | done(workbook 链到 `/file?path=`;写回槽 `ok`/`error`/`trace` 徽章 + `#wb-{line}`;plan 结果卡) |
|
||||
| O2 | OKF 任务知识包:`plan` reuse/promote([okf.md §7](okf.md)) | **done** |
|
||||
|
||||
### 非目标
|
||||
|
||||
- 在官方 `ext/ai/` 捆绑领域工具或工单技能
|
||||
- 在 `ext/` 根目录摊平 `.mq.md`
|
||||
- 平行再造一套 LLM HTTP 栈
|
||||
- 以不可读的私有二进制协议作为编排主界面
|
||||
|
||||
---
|
||||
|
||||
## 12. 一句话
|
||||
|
||||
**智能体框架必须让编排看起来像文档、跑起来像程序、留痕像知识库。**
|
||||
单步解决原子问题(默认写回);多步让父智能体编写并修订子 Marqdo 工作簿、经子任务执行、把确定步骤固化为代码——详见 [ext-agent-plan.md](ext-agent-plan.md)。
|
||||
|
||||
流式:`## step` / `## plan` 支持 `stream=True` / `echo=True`(SSE 增量;返回 map 不变;`plan` 另附 `events`,可选 `trace` 写回)。非命中时先流式父分解再 spawn 子任务。见 [agent-streaming.md](../roadmap/agent-streaming.md)。
|
||||
+16
-5
@@ -3,8 +3,8 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted (v0.1)** |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) |
|
||||
|
||||
## Commands
|
||||
|
||||
@@ -41,18 +41,29 @@ ext/
|
||||
智能体.mq.md
|
||||
```
|
||||
|
||||
Future optional ext domains get their own subdirs (e.g. `ext/foo/`), not mixed into `ai/`.
|
||||
Future optional ext domains get their own subdirs (e.g. `ext/web/`, `ext/quantum/`), not mixed into `ai/`.
|
||||
|
||||
## Catalog
|
||||
|
||||
| Id | Installs under `MARQDO_EXT` |
|
||||
|----|-----------------------------|
|
||||
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **`native/libagent.so`** (or `.dylib`) |
|
||||
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **`native/libweb.so`** — 见 [ext-web.md](ext-web.md) · [roadmap](../roadmap/ext-web.md) |
|
||||
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](ext-quantum.md) · [roadmap](../roadmap/ext-quantum.md) |
|
||||
|
||||
`add agent` copies the built native plugin into `MARQDO_EXT/native/`. Build it first:
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_agent
|
||||
marqdo ext add agent
|
||||
```
|
||||
|
||||
Without install, runtime resolves the plugin via `plugin.native_path name=agent` (see [ext-abi.md](ext-abi.md)): `MARQDO_AGENT_PLUGIN` → `CARGO_TARGET_DIR/{debug,release}/` → cwd `target/…` → beside `marqdo` binary → `MARQDO_EXT/native/`.
|
||||
|
||||
## Tests
|
||||
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` (needs `tests/ext/.env`).
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` ([`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md); needs `tests/ext/.env` + built `libagent`).
|
||||
|
||||
## Non-goals
|
||||
|
||||
|
||||
+19
-4
@@ -18,7 +18,9 @@
|
||||
|
||||
Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)).
|
||||
|
||||
Other official ext: [ext-agent.md](ext-agent.md) (**agent development framework** — layout shipped; orchestration + LLM composition on roadmap). Installer CLI (planned): [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
|
||||
Other official ext: [ext-agent.md](ext-agent.md) / [ext-agent-plan.md](ext-agent-plan.md) (**document-driven agent** — step with default writeback / plan workbook; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
|
||||
|
||||
Streaming: `complete stream=True` returns an event list (`reasoning` / `delta` / `done` / `error`); `echo=True` prints thinking (`reasoning_content`) and answer tokens as they arrive. See [agent-streaming.md](../roadmap/agent-streaming.md). Default (`stream=False`) is unchanged (answer string).
|
||||
|
||||
**Note:** Prefer `marqdo ext add llm`. Import `> ext/ai/llm.mq.md` from repo or install root.
|
||||
|
||||
@@ -35,8 +37,9 @@ Other official ext: [ext-agent.md](ext-agent.md) (**agent development framework*
|
||||
| English | Chinese | Role |
|
||||
|---------|---------|------|
|
||||
| `## load_env` | `## 加载环境` | Free function: load `.env` |
|
||||
| `## stream_result` | `## 流式结果` | Collapse event list → final text |
|
||||
| `# llm` | `# 大模型` | Object ctor → handle map |
|
||||
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods on the handle |
|
||||
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods; optional `stream` / `流式`, `echo` / `打印增量` |
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -50,6 +53,15 @@ Other official ext: [ext-agent.md](ext-agent.md) (**agent development framework*
|
||||
*`model` = > llm *
|
||||
*`reply` = > `model`.complete prompt=Say hi in one word *
|
||||
> print text=`reply`
|
||||
|
||||
*`events` = > `model`.complete prompt=Say hi stream=True *
|
||||
- [`ev`](`events`)
|
||||
*`t` = > json.get value=`ev` key=type *
|
||||
1. `t` == "delta"
|
||||
*`chunk` = > json.get value=`ev` key=text *
|
||||
> print text=`chunk`
|
||||
2. *
|
||||
*`_` = 1*
|
||||
```
|
||||
|
||||
Environment (create a **project-local** `.env`; do not commit secrets):
|
||||
@@ -65,6 +77,9 @@ Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`.
|
||||
## Tests
|
||||
|
||||
- Import smoke: `tests/ext/llm-import.mq.md`
|
||||
- Offline stream: `tests/ext/llm-stream-offline.mq.md` + `tests/lib/net-openai-sse.mq.md`
|
||||
- Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env`
|
||||
- Live agent `执行`: `tests/ext/agent-run-live.mq.md` + same `.env` (gold: `ext_agent_run_live`, skips if missing)
|
||||
- Offline agent smoke: `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`)
|
||||
- Live agent `## step`: `tests/ext/agent-run-live.mq.md` (DeepSeek; gold: `ext_agent_run_live`)
|
||||
- Agent smoke (real `llm` handle): `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`)
|
||||
- Live complete: `tests/ext/llm-complete.mq.md` (gold: `ext_llm_complete_live`)
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
# `ext/quantum` — 自定义酉门(公式矩阵 → 可施加)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 已落地** |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 父设计 | [ext-quantum.md](ext-quantum.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
作者用 `$$…$$`(或嵌套 list)写出酉矩阵 → `quantum.gate matrix=…` 得到可复用门句柄 → `` `qc`.apply gate=… qubits=… `` 施加到电路。
|
||||
|
||||
---
|
||||
|
||||
## 2. 公式矩阵
|
||||
|
||||
`$$` 围栏若含 `[[…]]` 或 `\begin{pmatrix}` / `\begin{bmatrix}`,在**解析期**求值为嵌套数值 list(非整棵 `Formula` 标量树)。
|
||||
|
||||
支持:
|
||||
|
||||
- ASCII:`[[1,0],[0,-1]]`、`(1/sqrt(2))*[[1,1],[1,-1]]`
|
||||
- LaTeX 子集:`\frac{…}{…}`、`\sqrt{…}`、`pmatrix` / `bmatrix`(`&` / `\\`)
|
||||
|
||||
复数:list 路径仍可用 `{re,im}` 或 `[re,im]`;公式路径本切片以实矩阵为主。
|
||||
|
||||
---
|
||||
|
||||
## 3. API
|
||||
|
||||
```markdown
|
||||
*`U` = > quantum.gate matrix=`H_matrix` name=U *
|
||||
# 或构造参数 matrix=;name 可选(默认 U)
|
||||
|
||||
*`qc` = > `qc`.apply gate=`U` qubits=0 *
|
||||
# qubits= 标量或 list;矩阵维数须为 2^k
|
||||
```
|
||||
|
||||
中文:`量子.门 矩阵=` / `` `qc`.施加 门= 比特= ``。
|
||||
|
||||
具名门仍可用 `name=H`;`matrix` / `matches_matrix` / `draw` 对自定义门同样有效。
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收
|
||||
|
||||
- 公式(或 list)定义的 H 与内置 `H` 概率一致
|
||||
- EN/ZH 金样
|
||||
@@ -0,0 +1,48 @@
|
||||
# `ext/quantum` Q5.5 — 振幅阻尼(教学轨迹)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 已落地** |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 父设计 | [ext-quantum.md](ext-quantum.md) · [ext-quantum-q5.md](ext-quantum-q5.md) |
|
||||
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在 Q5 的 `bitflip` / `depolarizing` 之外,补一种**耗散**教学噪声:`amplitude_damping`(中文 `振幅阻尼`),仍只影响 `run` 轨迹;`simulate` / `probabilities` 忽略。
|
||||
|
||||
**刻意不做:** 完整 Kraus 表 API、任意算符噪声、密度矩阵引擎、相位阻尼完整 Lindblad。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者面
|
||||
|
||||
```markdown
|
||||
*`qc` = > `qc`.noise kind=amplitude_damping p=0.1 *
|
||||
# 中文
|
||||
*`qc` = > `qc`.噪声 种类=振幅阻尼 概率=0.1 *
|
||||
```
|
||||
|
||||
别名:`amp_damp` / `amplitude-damping`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 模拟语义
|
||||
|
||||
与 Q5 相同:每个改态门后,对涉及比特独立掷骰。
|
||||
|
||||
对每个比特,以概率 `p` 施加**跳跃**算符 \(E_1 = |0\rangle\langle 1|\)(只作用该比特),再归一化:
|
||||
|
||||
- 若态在该比特上几乎全为 `|0⟩`(范数 ≈ 0),跳跃无效,态不变。
|
||||
- 否则振幅从 `|…1…⟩` 搬到对应 `|…0…⟩` 并归一化。
|
||||
|
||||
金样:`X` 后 `amplitude_damping p=1` → 全部 shot 落在 `|0⟩`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收
|
||||
|
||||
- `tests/ext/quantum-amp-damp-smoke.mq.md`(+ 中文对称)
|
||||
- L1 EN/ZH 文档列出第三种 `kind`
|
||||
@@ -0,0 +1,69 @@
|
||||
# `ext/quantum` Q5 — 最小噪声(教学用)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 最小实现已落地** |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 父设计 | [ext-quantum.md](ext-quantum.md) |
|
||||
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在 **不** 引入完整开放系统 / 云后端的前提下,让教学文档能写「带噪声的采样」,金样可复现。
|
||||
|
||||
**刻意不做(本 Q5 切片):** 任意 Kraus 组、振幅阻尼完整表、>12 qubits 张量网络、噪声参数学习。振幅阻尼教学轨迹见 [ext-quantum-q5.5.md](ext-quantum-q5.5.md)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者面
|
||||
|
||||
电路上可选噪声字段(方法链设置,返回新句柄):
|
||||
|
||||
```markdown
|
||||
*`qc` = > `qc`.noise kind=bitflip p=0.05 *
|
||||
# 或
|
||||
*`qc` = > `qc`.noise kind=depolarizing p=0.02 *
|
||||
```
|
||||
|
||||
| 参数 | 含义 |
|
||||
|------|------|
|
||||
| `kind` | `bitflip` \| `depolarizing`(中文:`比特翻转` / `退极化`) |
|
||||
| `p` | 每比特、每个非 `barrier`/`measure` 门后的错误概率,`0…1` |
|
||||
|
||||
`simulate` / `probabilities`:**忽略噪声**(仍为理想酉演化),避免概率图被蒙特卡洛抖动。
|
||||
`run shots= seed=`:**启用噪声**(若 `p>0`):按轨迹采样,结果可复现。
|
||||
|
||||
---
|
||||
|
||||
## 3. 模拟语义(轨迹)
|
||||
|
||||
每个 shot:
|
||||
|
||||
1. 从 `|0…0⟩` 施电路门(跳过 `BARRIER`;`MEASURE` 不改变酉演化)。
|
||||
2. 每施一个会改态的门后,对**该门涉及的每个比特**独立:
|
||||
- `bitflip`:以概率 `p` 施 `X`;
|
||||
- `depolarizing`:以概率 `p` 均匀随机施 `X`/`Y`/`Z` 之一。
|
||||
3. 若电路含 `MEASURE` 标记:只对标记比特做计算基采样;否则测全部比特。
|
||||
|
||||
RNG:与现有 `run seed=` 同一 SplitMix64 流(门后噪声与最终采样共用)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与作者面补齐的关系
|
||||
|
||||
| API | 行为 |
|
||||
|-----|------|
|
||||
| `barrier` | 仅可视化;模拟跳过 |
|
||||
| `measure` | 可视化测量符号;决定 `run` 读出哪些比特 |
|
||||
| `append` | 追加另一 `circuit` 的 `ops`(或单门) |
|
||||
| `state` | 等价于当前理想 `simulate` 结果(`quantum_state`) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
- 金样:理想 Bell `run` 不变;`noise kind=bitflip p=1` 在已知电路上计数偏离理想(`seed=` 固定)。
|
||||
- `barrier`/`measure` 出现在 `draw kind=circuit` SVG。
|
||||
- 中英 L1 对称;仍无 `host_*` 于 `ext/**`。
|
||||
@@ -0,0 +1,400 @@
|
||||
# 官方扩展:`ext/quantum` 量子计算模拟
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · Q0–Q5.5 已落地**(教学噪声含振幅阻尼;完整开放系统另文) |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 相关 | [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` / `量子`) |
|
||||
| 本文目的 | 锁定**作者面**、**模拟语义**、**view 可视化**与**分期**;指导 ABI 插件实现 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
`ext/quantum` 用 **GFM 表格 + 类方法 +(可选)`$$` 狄拉克/矩阵公式** 描述量子门与电路;**经典状态向量模拟**给出概率与采样。
|
||||
文档能跑通,公式与电路约定就成立——这是 Marqdo「代码即文档」在量子教学上的最强展示位。
|
||||
|
||||
**不改 Marqdo 核心语法**;热路径只在 ABI 插件;**禁止**把量子核链进 `marqdo` 主二进制或在 `ext/**` 里调用 `host_*`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何做量子扩展(与 math 的关系)
|
||||
|
||||
### 1.1 与 `lib/math` 的相似处
|
||||
|
||||
| math | quantum |
|
||||
|------|---------|
|
||||
| `` `f` = `` + `$$…$$` → `formula` | 门矩阵 / 态矢量可用 `$$` **展示与核对** |
|
||||
| 库函数对公式求值、求导、作图 | 类方法对电路施门、模拟、画图 |
|
||||
| view 内嵌 SVG;CLI 可 `path=` | view 内嵌**电路图 / 概率条 / 布洛赫**;CLI 可落盘 |
|
||||
| 金样例失败 = 文档/公式错 | 金样例失败 = 门定义或电路叙述错 |
|
||||
|
||||
math 是**高中符号与曲线**;quantum 是**离散希尔伯特空间上的可执行电路文档**。两者都是「写出公式 → 跑通 → 证明文档正确」。
|
||||
|
||||
### 1.2 与 math 的刻意分界
|
||||
|
||||
| 做 | 不做 |
|
||||
|----|------|
|
||||
| 量子在 **`ext/quantum`**,经 `plugin.load` | **不**并进 `lib/math`(避免 stdlib 膨胀) |
|
||||
| 复数振幅用 `{re, im}` map(与现有 `Value` 兼容) | **不**为量子在核心新增 `Value::Complex`(可二期) |
|
||||
| 角度可用 `math.pi` 等常量 | **不**在 quantum 插件内重写 CAS |
|
||||
|
||||
### 1.3 「代码即文档」在这里的作用
|
||||
|
||||
典型教学页:
|
||||
|
||||
```markdown
|
||||
# 贝尔态 |Φ+⟩
|
||||
|
||||
对 qubit 0 施 H,再 CNOT(0→1)。理想测量:`00` 与 `11` 各约 1/2。
|
||||
|
||||
# main
|
||||
|
||||
`steps` =
|
||||
|
||||
| 步 | 门 | 比特 |
|
||||
|----|----|------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
|
||||
*`p` = > `qc`.probabilities *
|
||||
```
|
||||
|
||||
- 叙述与表格是**给人看的电路说明**;
|
||||
- 同一文件是**可执行程序**;
|
||||
- gold / CI 断言概率 → **文档与物理约定同步**,无需另维护「幻灯片公式」。
|
||||
|
||||
---
|
||||
|
||||
## 2. 硬约束(评审锁定)
|
||||
|
||||
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))。
|
||||
4. **不改核心语法**;电路表单元格保持字面量;门名/比特下标由类方法解析。
|
||||
5. **模拟器有硬上限**(默认 ≤ 12 qubits);超限报错,不静默截断。
|
||||
6. **view 必须有专项展示**(结构卡 + 执行区 SVG),禁止只 dump JSON。
|
||||
|
||||
---
|
||||
|
||||
## 3. 布局与安装
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
quantum.mq.md # 英文类 API
|
||||
量子.mq.md # 中文类 API
|
||||
plugins/quantum/
|
||||
Cargo.toml
|
||||
src/lib.rs # ABI v2:线性代数 / 施门 / 画 SVG
|
||||
examples/quantum-bell/ # 规范示例(Q3)
|
||||
tests/ext/quantum-*.mq.md
|
||||
```
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_quantum
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
导入:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/quantum/quantum.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
或中文:`> ext/quantum/量子.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 核心模型
|
||||
|
||||
### 4.1 运行时句柄(JSON map + `_type`)
|
||||
|
||||
| `_type`(英) | 中文类名 | 含义 |
|
||||
|---------------|----------|------|
|
||||
| `quantum_gate` | `量子门` | 具名门或自定义酉矩阵 |
|
||||
| `quantum_circuit` | `量子电路` | n qubits + 有序门列表 |
|
||||
| `quantum_state` | `量子态` | 状态向量(振幅列表) |
|
||||
| `quantum_result` | `量子结果` | 概率 / 采样 / 可选坍缩态 |
|
||||
| `quantum_svg` | (产物) | 带 `svg` 字段的可视化结果 |
|
||||
|
||||
插件返回 map;Marqdo 对象系统挂 `_type` 后可用方法链。
|
||||
|
||||
### 4.2 状态表示
|
||||
|
||||
- **纯态**状态向量:长度 `2^n`,每元 `{re, im}`(f64)。
|
||||
- 默认初态:`|0…0⟩`(仅 index 0 振幅为 1)。
|
||||
- 门作用后可选重归一化(阈值误差阈值,默认开)。
|
||||
|
||||
### 4.3 公式面(对齐 math 精神,不抢 math 实现)
|
||||
|
||||
允许用 `` `G` = `` + `$$…$$` 书写门矩阵(**可执行**,见 [ext-quantum-custom-gate.md](ext-quantum-custom-gate.md)):
|
||||
|
||||
````markdown
|
||||
`H_matrix` =
|
||||
$$
|
||||
\frac{1}{\sqrt{2}}\begin{pmatrix}1&1\\1&-1\end{pmatrix}
|
||||
$$
|
||||
|
||||
*`U` = > quantum.gate matrix=`H_matrix` *
|
||||
*`qc` = > `qc`.apply gate=`U` qubits=0 *
|
||||
*`ok` = > `H`.matches_matrix matrix=`H_matrix` *
|
||||
````
|
||||
|
||||
- v1:**具名门**以插件内置酉矩阵为准;`matrix=` 可从嵌套 list / `$$` 矩阵围栏构造自定义门。
|
||||
- `$$` 含 `[[…]]` 或 `\begin{pmatrix}` 时解析期求值为数值 list;标量公式仍为 `Formula`。
|
||||
- `matches_matrix` 仍可用于核对。
|
||||
---
|
||||
|
||||
## 5. 作者面 API(锁定草图)
|
||||
|
||||
### 5.1 英文 `ext/quantum/quantum.mq.md`
|
||||
|
||||
```markdown
|
||||
# gate
|
||||
+ `name`=None # H X Y Z S T I CX CZ SWAP …
|
||||
+ `theta`=None # Rx/Ry/Rz
|
||||
|
||||
## matrix # → 振幅表 / 嵌套 list(文档与调试)
|
||||
## draw # → quantum_svg(`kind=gate|matrix` 符号 / 热力图)
|
||||
## matches_matrix
|
||||
+ `matrix`
|
||||
+ `tol`=1e-9
|
||||
|
||||
# circuit
|
||||
+ `qubits`
|
||||
+ `steps`=None # 可选:GFM 门序列表
|
||||
|
||||
## h / x / y / z / s / t
|
||||
+ `qubit`
|
||||
## rx / ry / rz
|
||||
+ `qubit`
|
||||
+ `theta`
|
||||
## cx / cz
|
||||
+ `control`
|
||||
+ `target`
|
||||
## swap
|
||||
+ `a`
|
||||
+ `b`
|
||||
## barrier # 仅可视化分隔,不改变态
|
||||
## measure # 标记测量(模拟时按计算基)
|
||||
+ `qubits`=None # 默认全部
|
||||
## append # 追加另一电路或门
|
||||
+ `op`
|
||||
## simulate # → quantum_state(不坍缩)
|
||||
## probabilities # → map 基矢标签 → 概率
|
||||
## run
|
||||
+ `shots`=1024
|
||||
+ `seed`=None # → quantum_result(计数直方图)
|
||||
## draw
|
||||
+ `path`=None # SVG;无 path 时仍可进 view 产物
|
||||
## state # 当前缓存态(若已 simulate)
|
||||
```
|
||||
|
||||
门方法返回**更新后的 circuit 句柄**(与 web `compose_*` 相同:`` `qc` = > `qc`.h qubit=0 *``)。
|
||||
|
||||
### 5.2 中文 `ext/quantum/量子.mq.md`
|
||||
|
||||
| 英文 | 中文 |
|
||||
|------|------|
|
||||
| `gate` | `门` |
|
||||
| `circuit` | `电路` |
|
||||
| `h` | `哈达玛` |
|
||||
| `x` / `y` / `z` | `泡利X` / `泡利Y` / `泡利Z` |
|
||||
| `cx` | `控非` |
|
||||
| `cz` | `控相` |
|
||||
| `rx`/`ry`/`rz` | `绕X`/`绕Y`/`绕Z` |
|
||||
| `simulate` | `模拟` |
|
||||
| `probabilities` | `概率` |
|
||||
| `run` | `运行` |
|
||||
| `draw` | `绘图` |
|
||||
| `measure` | `测量` |
|
||||
| `qubits` | `比特数` |
|
||||
| `steps` | `步骤` |
|
||||
| `shots` / `seed` | `次数` / `种子` |
|
||||
|
||||
插件 FFI 名稳定英文:`quantum_circuit_new`、`quantum_h`、`quantum_cx`、`quantum_simulate`、`quantum_draw_circuit`…
|
||||
|
||||
### 5.3 电路表(文档优先写法)
|
||||
|
||||
```markdown
|
||||
`steps` =
|
||||
|
||||
| 步 | 门 | 比特 | 参数 |
|
||||
|----|----|------|------|
|
||||
| 1 | H | 0 | |
|
||||
| 2 | CX | 0,1 | |
|
||||
| 3 | RZ | 1 | pi/4 |
|
||||
```
|
||||
|
||||
列名中英兼容:`步|step`、`门|gate`、`比特|qubits|qubit`、`参数|theta|params`。
|
||||
|
||||
*`qc` = > quantum.circuit qubits=2 steps=`steps` *` 与方法链**等价**;表更适合「整页即电路说明书」。
|
||||
|
||||
### 5.4 返回值形态
|
||||
|
||||
| 方法 | 返回 |
|
||||
|------|------|
|
||||
| `simulate` | `{_type, qubits, dim, amplitudes:[{re,im},…]}` |
|
||||
| `probabilities` | `{ "00": 0.5, "11": 0.5 }`(标签为小端比特串,文档写死) |
|
||||
| `run` | `{ counts: {…}, shots, seed }` |
|
||||
| `draw` | `{_type: quantum_svg, kind: circuit\|gate\|probs\|bloch, svg: "…" }` |
|
||||
|
||||
---
|
||||
|
||||
## 6. 模拟器语义
|
||||
|
||||
| 项 | 锁定 |
|
||||
|----|------|
|
||||
| 模型 | 封闭系统纯态;计算基测量 |
|
||||
| 默认上限 | **12 qubits**;`MARQDO_QUANTUM_MAX_QUBITS` 可下调(不可暗中上调超过编译期硬顶,硬顶建议 16) |
|
||||
| 超限 | 错误信息含当前 n 与上限 |
|
||||
| `simulate` / `probabilities` | **无 RNG**、确定性 |
|
||||
| `run` | 多项式采样;`seed=` 可复现(金样必用) |
|
||||
| 数值 | f64;门后 ‖ψ‖ 偏离阈值则重归一化并可选 warning 字段 |
|
||||
|
||||
实现:插件内 Kronecker / 按比特作用稀疏更新;可用 `nalgebra` 或手写,**不**捆绑外部量子云。
|
||||
|
||||
---
|
||||
|
||||
## 7. view 模式支持(专项)
|
||||
|
||||
对齐 [view.md](view.md) 与 math 作图:**Structure / Execution / Source 共用渲染**;禁止第二套皮肤。
|
||||
|
||||
### 7.1 Structure(结构区)
|
||||
|
||||
| 源形态 | 展示 |
|
||||
|--------|------|
|
||||
| `` `qc` = `` + 电路表 | **circuit-card**:比特数、门序列时间线(文本/紧凑 SVG) |
|
||||
| `` `G` = `` + `$$` 门矩阵 | 沿用 **formula-card**(KaTeX);徽章可标 `gate`(若绑定来自 quantum.gate) |
|
||||
| 方法链语句 | 普通调用行;不强制每步展开 |
|
||||
|
||||
### 7.2 Execution(执行区)
|
||||
|
||||
| 产物 | 展示 |
|
||||
|------|------|
|
||||
| `quantum_svg` | 与 math `plots` 同级:**内嵌 SVG**(电路轨线图 / 概率直方图 / 单比特布洛赫) |
|
||||
| `probabilities` / `counts` | 表格 + 可选自动条形 SVG |
|
||||
| `quantum_state` | 默认折叠振幅表;小 n(≤3)可并排显示基矢 |
|
||||
|
||||
### 7.3 产物如何进入 view(实现锁定)
|
||||
|
||||
插件**不能**直接碰核心 `HostContext.plots`。采用其一(实现时二选一,优先 A):
|
||||
|
||||
| 方案 | 做法 |
|
||||
|------|------|
|
||||
| **A(推荐)** | ABI `host_query("record_plot")`:参数 JSON `{svg}`;写入与 math 相同的 plots 列表([ext-abi.md](ext-abi.md) allowlist 增补一条) |
|
||||
| **B** | 仅返回 `quantum_svg`;view 在渲染执行值时识别 `_type`/`svg` 字段并内嵌(不扩 ABI) |
|
||||
|
||||
CLI:`draw path=bell.svg` 写沙箱文件;无 path 时不把整段 SVG 灌 stdout(同 math §5)。
|
||||
|
||||
### 7.4 可视化内容(v1 必须 / 可后)
|
||||
|
||||
| 图 | v1 | 说明 |
|
||||
|----|----|------|
|
||||
| 电路轨线(qubit 线 + 门盒 + 控点) | **必须** | `circuit.draw` |
|
||||
| 测量概率条形图 | **必须** | `probabilities` / `run` 后可 `draw kind=probs` |
|
||||
| 单比特布洛赫球(SVG) | 应有 | 仅 n=1 或指定 qubit 约化(纯态投影) |
|
||||
| 门矩阵热力图 | **必须** | `gate.draw kind=matrix`(幅值热图 + 小数标注) |
|
||||
| 交互拖拽编辑电路 | **不做** | 静态文档足够 |
|
||||
|
||||
视觉:内联 CSS;**无外链**字体/CDN(同 view 硬规则)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分期(开发计划)
|
||||
|
||||
```text
|
||||
Q0 脚手架:CATALOG + plugins/quantum Hello + L1 ensure_plugin
|
||||
Q1 态向量 + I/X/H/CX + simulate/probabilities;贝尔态 gold
|
||||
Q2 Y/Z/S/T/Rx/Ry/Rz/CZ/SWAP + run(seed) + 中英 API 对齐
|
||||
Q3 电路表 steps= + draw 电路 SVG + view record_plot/识别;examples/
|
||||
Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-quantum-q5.md) ← **done(最小)**
|
||||
```
|
||||
|
||||
| 阶段 | 交付物 | 验收 |
|
||||
|------|--------|------|
|
||||
| **Q0** | `marqdo_plugin_quantum` 注册 `quantum_ping`;L1 加载失败可读 | `ext add quantum` 路径通 |
|
||||
| **Q1** | 贝尔态 `probabilities` ≈ 0.5/0.5 | `tests/ext/quantum-bell-smoke.mq.md` |
|
||||
| **Q2** | 旋转门 + `run seed=` 计数稳定 | 中英双金样 |
|
||||
| **Q3** | `steps=` 表;`draw` SVG 在 `view` HTML 含 `<svg` | 与 math-plot 同级断言 |
|
||||
| **Q4** | 概率图 + 布洛赫;`matches_matrix`;用户文档页 | `quantum-draw-smoke` / `quantum-gate-matrix-smoke`;`view output` 可浏览示例 |
|
||||
| **Q5** | `noise` 轨迹;`barrier`/`measure`/`append`/`state` | `quantum-noise-smoke` / `quantum-author-api-smoke` |
|
||||
|
||||
实现路线图跟踪见 [roadmap/ext-quantum.md](../roadmap/ext-quantum.md)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 规范示例(目标作者体验)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Bell state
|
||||
> ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# Bell |Φ+⟩
|
||||
|
||||
H on qubit 0, then CNOT. Expect |00⟩ and |11⟩ each with probability 1/2.
|
||||
|
||||
# main
|
||||
|
||||
`steps` =
|
||||
|
||||
| step | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
|
||||
*`p` = > `qc`.probabilities *
|
||||
*`svg` = > `qc`.draw *
|
||||
|
||||
> print text=`p`
|
||||
```
|
||||
|
||||
中文面对称:`量子.电路`、`哈达玛`、`控非`、`概率`、`绘图`。
|
||||
|
||||
---
|
||||
|
||||
## 10. 刻意不做(本 Accepted 范围)
|
||||
|
||||
- 真机 / 云后端(IBM、Braket…)
|
||||
- 开放系统、完整噪声模型(可 Q5+)
|
||||
- 符号电路编译优化器
|
||||
- 交互式电路编辑器
|
||||
- 把量子并入 `lib/math` 或核心 opcode
|
||||
- 无上限比特的「生产级」模拟
|
||||
|
||||
---
|
||||
|
||||
## 11. 开放点(已收敛 / 剩余)
|
||||
|
||||
| 议题 | 结论 |
|
||||
|------|------|
|
||||
| 对象面 vs 自由函数 | **主推对象/方法链**;自由函数不平行提供 |
|
||||
| 电路表 | **v1 纳入**(Q3),与方法链等价 |
|
||||
| 振幅过大 | v1 全进 Value;n≤12 可接受;超限已挡 |
|
||||
| view 产物 | **优先** `host_query("record_plot")` |
|
||||
| 与 web | **不依赖** web 做可视化;SVG 自绘 |
|
||||
|
||||
---
|
||||
|
||||
## 12. 评审清单
|
||||
|
||||
1. ABI-only + 中英分文件是否认可?
|
||||
2. 默认 12 qubits 上限是否合适?
|
||||
3. 电路表列设计(步/门/比特/参数)是否够用?
|
||||
4. view:电路轨线 + 概率条为 v1 必须,是否同意?
|
||||
5. `$$` 矩阵核对放 Q4,是否同意先表驱动?
|
||||
|
||||
评审通过后:本文冻结为 Accepted → 按 §8 从 Q0 实现。
|
||||
|
||||
---
|
||||
|
||||
## 13. 一句话
|
||||
|
||||
**表格写出电路,类方法模拟与绘图;跑通金样即证明文档中的量子公式与步骤成立——math 管曲线,quantum 管希尔伯特空间上的可执行说明书。**
|
||||
@@ -0,0 +1,600 @@
|
||||
# 官方扩展:`ext/web` 动态网站
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 完成**(SQLite 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / `app.static`;Postgres 等见 §9) |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) |
|
||||
| 安装(目标) | `marqdo ext add web`(中英:`web` / `网页`) |
|
||||
| 本文目的 | 锁定**作者面**与**类 API**;指导实现 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
`ext/web` 用 **GFM 表格 + Marqdo 类方法** 描述动态网站:表仍是字典/列表嵌套;类方法把表装配成可渲染页面。
|
||||
**不改 Marqdo 核心语法**;扩展库存在的理由,正是让「文档即代码」在网站场景下成立。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何要做网络扩展库
|
||||
|
||||
### 1.1 问题
|
||||
|
||||
若没有专用扩展,作者只能:
|
||||
|
||||
- 手写 JSON 袋、`json.set` 拼装组件/样式;或
|
||||
- 要求改语言(让表格单元格求值、点号取值等)。
|
||||
|
||||
二者都破坏 Marqdo 的「代码即文档」。
|
||||
|
||||
### 1.2 答案
|
||||
|
||||
在 **`ext/web/web.mq.md`(英文)** 与 **`ext/web/网页.mq.md`(中文)** 中各提供一套 **`#` 类**:
|
||||
|
||||
- 作者只写**表** + **少量实例方法调用**;
|
||||
- 表单元格保持**字面量**;
|
||||
- **寻址字符串**由类方法解析;
|
||||
- **导入英文文件 → 只用英文 API;导入中文文件 → 只用中文 API**(见 [stdlib-i18n.md](stdlib-i18n.md))。
|
||||
|
||||
### 1.3 硬约束(评审锁定)
|
||||
|
||||
| # | 约束 |
|
||||
|---|------|
|
||||
| C1 | **禁止**为 web 改动 Marqdo 核心:单元格求值、import、点号值读取等保持不变 |
|
||||
| C2 | 作者面**禁止** `json.parse` / `json.set` 袋胶水、手写 part JSON、手写 assemble 袋 |
|
||||
| C3 | 能力以 **`#` 类 + `##` 方法** 暴露;**英文库文件只用英文名,中文库文件只用中文名**(见 [stdlib-i18n.md](stdlib-i18n.md));同一 `.mq.md` 内禁止中英 API 混排 |
|
||||
| C4 | 首页在 **`index.mq.md`**:页面表在此;可复用片段进 `components/`;主体可就地写 |
|
||||
| C5 | **旧有网络扩展库全部废弃**:`plugins/web`、`ext/web/**`(含现网示例/gold 中依赖旧 API 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进 |
|
||||
| C6 | `# db` / `# 数据库` 必须提供完整**增删改查**;列表查询英文方法名为 **`select`**(中文 **`查询`**);后台 `/admin` 与表单提交走同一套写库 API |
|
||||
| C7 | 用户输入经 `# form` / `# 表单`:字段表 + 校验表;**服务端校验必须在写库前执行**(见 §5.5) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者心智与目录
|
||||
|
||||
```text
|
||||
myapp/
|
||||
index.mq.md # 入口 + 首页:页面表 +(可选)就地主体表 + 类方法 + listen
|
||||
pages/ # 子页:同形的页面表(导出布局表或由入口再装配)
|
||||
components/ # 可复用组件:导出与路径同名的 ##,体为 |属性|值|样式|
|
||||
styles/ # 样式模块:每个样式一个 ##,体为 |属性|值|
|
||||
db/ # 库:schema 表 +(可选)open/种子
|
||||
data/ # sqlite 等运行时数据(gitignore)
|
||||
```
|
||||
|
||||
| 表种 | 列 | 一句话 |
|
||||
|------|-----|--------|
|
||||
| **页面表** | `组件` \| `样式` | 本页用哪些组件、各套哪套样式 |
|
||||
| **组件 / 主体表** | `属性` \| `值` \| `样式` | 前端属性 ↔ 取值(库字段或字面量)↔ 样式名 |
|
||||
| **样式表** | `属性` \| `值` | CSS 声明 |
|
||||
| **库结构表** | `字段` \| `类型` \| `可空` | schema |
|
||||
|
||||
---
|
||||
|
||||
## 3. 表内寻址约定(单元格仍是字符串)
|
||||
|
||||
单元格**不求值**。下列写法是 **web 扩展约定的路径文本**,由 `# 页面` / `# 样式` / `# 数据库` 的方法解析。
|
||||
|
||||
### 3.1 反引号与裸名
|
||||
|
||||
| 含义 | 写法 | 例 |
|
||||
|------|------|-----|
|
||||
| 要「去导入树 / 定义里解析」的名字 | 反引号 `` `名` `` | `` `nav` ``、`` `title` ``、`` `topnav` ``、`` `articles` ``(表名) |
|
||||
| 字面量(文案、URL、CSS 属性名/值、SQL 类型、**列名**) | **裸**或 `"…"` | `首页`、`/about`、`font-size`、`integer`、`title`(作为列名时) |
|
||||
|
||||
### 3.2 路径形态(锁定)
|
||||
|
||||
| 场景 | 形态 | 例 | 方法内语义 |
|
||||
|------|------|-----|------------|
|
||||
| 引用导入模块的导出 | `模块.`导出`` | `nav.`nav``、`shell.`topnav`` | 在**站点入口模块**的 import 树上调用 `模块.导出`(零参 `##`),取回表 Value |
|
||||
| 引用库字段 | `模块.`表`.列` | `articles.`articles`.title` | 模块名 = 命名空间(对应导入的 db 文件);`` `表` `` = 库表名;**列名裸写**(列不是变量)→ 运行时绑定 `表.列` |
|
||||
| 前端属性名 | `` `title` `` | 组件表「属性」列 | 解析为字段名 `title` |
|
||||
| 样式引用 | 同「模块.导出」或纯样式名 | `shell.`card-title`` | 取回 `|属性|值|` 表并编译为 CSS 类 |
|
||||
|
||||
**刻意不做的事:**
|
||||
|
||||
- 不把「组件变量名」魔法等同于「库表名」;
|
||||
- 不要求作者写 `json.set` 才能把 `nav` 放进袋;
|
||||
- 不把 `articles.`articles`.title` 做成语言级表达式。
|
||||
|
||||
### 3.3 与模块命名空间的关系
|
||||
|
||||
- 库名来自 frontmatter 导入(茎名或 `as`),**裸名**,见 [module-namespace.md](module-namespace.md)。
|
||||
- `nav.`nav`` 中:前段 `nav` = 导入库名;`` `nav` `` = 该库上的 `## nav` 导出。
|
||||
- 组件/样式文件应导出 **与路径第二段同名的 `##`**,直接返回表(不要 `## bag` / `## bind` 袋)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 规范示例:`index.mq.md`(作者面唯一样板)
|
||||
|
||||
**语言与导入绑定(锁定,纠正手写混用):**
|
||||
|
||||
| 导入 | 库名(默认茎) | 类 / 方法 / 形参 |
|
||||
|------|----------------|------------------|
|
||||
| `> ext/web/web.mq.md` | `web` | **仅英文**:`page` · `compose_components` · `db` · `app` · `components=` … |
|
||||
| `> ext/web/网页.mq.md` | `网页` | **仅中文**:`页面` · `组件装配` · `数据库` · `应用` · `组件=` … |
|
||||
|
||||
禁止:`> ext/web/web.mq.md` 后写 `web.页面` / `` `页`.组件装配 ``(英文库混中文成员)。
|
||||
禁止:在 `web.mq.md` 文件内定义中文 `## 组件装配` 别名。中英对等靠**两个文件**,不靠同一文件双份导出。
|
||||
|
||||
### 4.1 英文面(导入 `web.mq.md`)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: web-site
|
||||
description: Home = page table; main may be inline; class methods assemble.
|
||||
> ext/web/web.mq.md
|
||||
> styles/shell.mq.md
|
||||
> components/nav.mq.md
|
||||
> components/side.mq.md
|
||||
> components/foot.mq.md
|
||||
> db/articles.mq.md
|
||||
> db/index.mq.md as db
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`home` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`nav` | shell.`topnav` |
|
||||
| side.`side` | shell.`side-panel` |
|
||||
| foot.`foot` | |
|
||||
|
||||
Main content is not a reusable component, so it is authored here.
|
||||
|
||||
`index` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| `title` | articles.`articles`.title | shell.`card-title` |
|
||||
| `body` | articles.`articles`.body | shell.`card-body` |
|
||||
|
||||
*`store` = > db.open *
|
||||
*`page` = > web.page title="Marqdo Web Site" intro="<h1>Web Site</h1>" *
|
||||
*`page` = > `page`.compose_components components=`home` *
|
||||
*`page` = > `page`.compose_main main=`index` *
|
||||
*`app` = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
|
||||
> `app`.listen
|
||||
```
|
||||
|
||||
说明:表头列名可用中文(`组件`/`样式`/`属性`/`值`)——那是**表约定词汇**,不是库成员名;库成员必须与导入语言一致。
|
||||
|
||||
### 4.2 中文面(导入 `网页.mq.md`)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 站点
|
||||
> ext/web/网页.mq.md
|
||||
> styles/shell.mq.md
|
||||
> components/nav.mq.md
|
||||
> components/side.mq.md
|
||||
> components/foot.mq.md
|
||||
> db/articles.mq.md
|
||||
> db/index.mq.md as db
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`首页` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`nav` | shell.`topnav` |
|
||||
| side.`side` | shell.`side-panel` |
|
||||
| foot.`foot` | |
|
||||
|
||||
主体不是可复用组件,因此就地撰写。
|
||||
|
||||
`index` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| `title` | articles.`articles`.title | shell.`card-title` |
|
||||
| `body` | articles.`articles`.body | shell.`card-body` |
|
||||
|
||||
*`库` = > db.open *
|
||||
*`页` = > 网页.页面 标题="站点" 引言="<h1>站点</h1>" *
|
||||
*`页` = > `页`.组件装配 组件=`首页` *
|
||||
*`页` = > `页`.主体装配 主体=`index` *
|
||||
*`应用` = > 网页.应用 页面=`页` 数据库=`库` 后台=True 主机=127.0.0.1 端口=18081 *
|
||||
> `应用`.监听
|
||||
```
|
||||
|
||||
**允许出现在 index 的非表内容:** frontmatter 导入、开库一行、构造页面/应用并装配、`listen` / `监听`。
|
||||
**不允许:** `json.*` 袋、手写 `/_part` 注册、中英 API 混用。
|
||||
|
||||
---
|
||||
|
||||
## 5. 类 API(分文件 · 分语言)
|
||||
|
||||
依据 [stdlib-i18n.md](stdlib-i18n.md):**导入哪个文件,就用哪套名字。**
|
||||
`ext/web/web.mq.md` = 全英文;`ext/web/网页.mq.md` = 全中文。中文实现可委托插件同一套原语,或薄封装英文库,但**对外导出的 `#` / `##` / 形参名必须是中文**。
|
||||
|
||||
### 5.1 页面 · `page` / `页面`
|
||||
|
||||
**英文(`web.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# page
|
||||
+ `title`=…
|
||||
+ `intro`=…
|
||||
|
||||
## compose_components
|
||||
+ `components` # page table |组件|样式|
|
||||
|
||||
## compose_main
|
||||
+ `main` # bind table |属性|值|样式|
|
||||
```
|
||||
|
||||
**中文(`网页.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# 页面
|
||||
+ `标题`=…
|
||||
+ `引言`=…
|
||||
|
||||
## 组件装配
|
||||
+ `组件`
|
||||
|
||||
## 主体装配
|
||||
+ `主体`
|
||||
```
|
||||
|
||||
| 行为 | 说明 |
|
||||
|------|------|
|
||||
| compose_components / 组件装配 | 解析组件·样式路径 → 填 nav/sidebar/footer → CSS → 登记 part |
|
||||
| compose_main / 主体装配 | 解析库字段与样式路径 → 填 main → 登记 part(如 id=`index`) |
|
||||
|
||||
**槽位推断:** 由组件导出名决定(`nav`→顶栏,`side`→侧栏,`foot`→底栏;其余→main)。
|
||||
|
||||
### 5.2 样式 · `style` / `样式`
|
||||
|
||||
**英文:** `# style` · `## process` · `+ style=` / `name=` / `path=`
|
||||
**中文:** `# 样式` · `## 样式处理` · `+ 样式=` / `名=` / `路径=`
|
||||
|
||||
页面装配可内部调用;作者一般不必在 index 显式调。
|
||||
|
||||
### 5.3 数据库 · `db` / `数据库`
|
||||
|
||||
完整**增删改查**;页面绑定、种子、`/admin`、表单提交共用。
|
||||
|
||||
**英文(`web.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# db
|
||||
+ `url`=…
|
||||
|
||||
## init
|
||||
+ `name`
|
||||
+ `fields` # or table= schema
|
||||
|
||||
## insert
|
||||
+ `table`
|
||||
+ `rows`
|
||||
|
||||
## select
|
||||
+ `table`
|
||||
+ `where`=None # optional simple filters
|
||||
+ `limit`=200
|
||||
|
||||
## get
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
## update
|
||||
+ `table`
|
||||
+ `id`
|
||||
+ `row`
|
||||
|
||||
## delete
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
## exec
|
||||
+ `sql`
|
||||
+ `args`=None # escape hatch: raw SQL (not everyday authoring)
|
||||
```
|
||||
|
||||
**中文(`网页.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# 数据库
|
||||
+ `地址`=…
|
||||
|
||||
## 初始化
|
||||
+ `数据库表` # 或 名= + 字段=
|
||||
|
||||
## 插入
|
||||
+ `表`
|
||||
+ `行` # 或 多行=
|
||||
|
||||
## 查询
|
||||
+ `表`
|
||||
+ `条件`=None
|
||||
+ `上限`=200
|
||||
|
||||
## 获取
|
||||
+ `表`
|
||||
+ `id`
|
||||
|
||||
## 更新
|
||||
+ `表`
|
||||
+ `id`
|
||||
+ `行`
|
||||
|
||||
## 删除
|
||||
+ `表`
|
||||
+ `id`
|
||||
|
||||
## 执行
|
||||
+ `sql`
|
||||
+ `参数`=None
|
||||
```
|
||||
|
||||
| 中文 | 英文 | 职责 |
|
||||
|------|------|------|
|
||||
| 初始化 | `init` | 建表;登记表名 |
|
||||
| 插入 | `insert` | 增 |
|
||||
| 查询 | `select` | 查列表(可带简单条件 / limit) |
|
||||
| 获取 | `get` | 按主键一行 |
|
||||
| 更新 | `update` | 改 |
|
||||
| 删除 | `delete` | 删 |
|
||||
| 执行 | `exec` | 可选原始 SQL(进阶) |
|
||||
|
||||
`table=` / `表=` 接受表名或句柄;行数据优先 GFM 表。
|
||||
**命名锁定:** 列表查询用 `select` / `查询`,**不用** `all`;原始 SQL 用 `exec` / `执行`,避免与 `select` 混淆。
|
||||
|
||||
### 5.4 应用 · `app` / `应用`
|
||||
|
||||
**英文:** `# app` · `## route` · `## static` · `## listen` · 形参 `page` `db` `admin` `host` `port`
|
||||
**中文:** `# 应用` · `## 路由` · `## 静态` · `## 监听` · 形参 `页面` `数据库` `后台` `主机` `端口`
|
||||
|
||||
`listen` / `监听`:加载插件、注入 `db_url`、按页面 part 提供 `/_part/{id}`(首页)与 `{path}/_part/{id}`(`app.route` 页)、可选 `static` 目录挂载、启动 HTTP。作者不必手写 part 注册。
|
||||
|
||||
`static` / `静态`:`dir=`(或 `目录=`)+ 可选 `mount=`(默认 `/static`);`listen` 时用 `tower-http` 提供只读文件服务。
|
||||
|
||||
### 5.5 表单 · `form` / `表单`(规划锁定)
|
||||
|
||||
用户输入也走「表 + 类方法」,与页面/库同一心智;**提交最终调用 `# db` 的 insert/update**,不另开旁路。
|
||||
|
||||
**英文(`web.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# form
|
||||
+ `table`=None # bound db table name (optional until submit)
|
||||
+ `action`=insert # insert | update
|
||||
+ `id`=None # required when action=update
|
||||
|
||||
## fields
|
||||
+ `fields` # |字段|标签|类型|必填|默认|…
|
||||
|
||||
## validate
|
||||
+ `rules`=None # |字段|规则|消息|… (optional extra rules)
|
||||
+ `data` # submitted row / map
|
||||
|
||||
## render
|
||||
# → HTML form (or form descriptor for page slot)
|
||||
|
||||
## submit
|
||||
+ `data`
|
||||
+ `db` # db handle
|
||||
```
|
||||
|
||||
**中文(`网页.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# 表单
|
||||
+ `表`=None
|
||||
+ `动作`=插入 # 插入 | 更新
|
||||
+ `id`=None
|
||||
|
||||
## 字段
|
||||
+ `字段`
|
||||
|
||||
## 校验
|
||||
+ `规则`=None
|
||||
+ `数据`
|
||||
|
||||
## 渲染
|
||||
|
||||
## 提交
|
||||
+ `数据`
|
||||
+ `数据库`
|
||||
```
|
||||
|
||||
#### 5.5.1 字段表(作者面)
|
||||
|
||||
```markdown
|
||||
`文章表单` =
|
||||
|
||||
| 字段 | 标签 | 类型 | 必填 | 默认 |
|
||||
|------|------|------|------|------|
|
||||
| title | 标题 | text | true | |
|
||||
| body | 正文 | textarea | false | |
|
||||
```
|
||||
|
||||
| 列 | 含义 |
|
||||
|----|------|
|
||||
| `字段` | 对应库列名(裸名或 `` `列` ``,与 schema 对齐) |
|
||||
| `标签` | 展示文案(字面量) |
|
||||
| `类型` | 控件/值类型:`text` `textarea` `number` `email` `url` `checkbox` `select` … |
|
||||
| `必填` | 是否必填 |
|
||||
| `默认` | 可选默认值 |
|
||||
|
||||
#### 5.5.2 校验表(作者面)
|
||||
|
||||
```markdown
|
||||
`文章校验` =
|
||||
|
||||
| 字段 | 规则 | 消息 |
|
||||
|------|------|------|
|
||||
| title | required | 标题不能为空 |
|
||||
| title | max:120 | 标题过长 |
|
||||
| body | max:8000 | 正文过长 |
|
||||
```
|
||||
|
||||
| 规则(初版) | 含义 |
|
||||
|--------------|------|
|
||||
| `required` | 非空 |
|
||||
| `min:N` / `max:N` | 字符串长度或数值范围 |
|
||||
| `email` / `url` | 格式 |
|
||||
| `match:字段` | 与另一字段相等(如确认密码) |
|
||||
| `in:a,b,c` | 枚举 |
|
||||
|
||||
schema 上的「可空 / 类型」在 **submit 时自动并入校验**(不必重复写 `required`,但校验表可覆盖消息)。
|
||||
|
||||
#### 5.5.3 行为流程
|
||||
|
||||
```text
|
||||
render → 按字段表出 HTML(或嵌入 page 主区)
|
||||
用户填写 → POST /_form/{id} 或同页提交
|
||||
validate → 合并 schema + 校验表;失败则带回字段级错误、不写库
|
||||
submit → action=insert → db.insert;action=update → db.update
|
||||
→ 成功后刷新槽位或跳转(由 form 选项约定)
|
||||
```
|
||||
|
||||
| 层 | 校验 |
|
||||
|----|------|
|
||||
| **服务端(必须)** | `validate` 在写库前执行;唯一可信边界 |
|
||||
| **浏览器(可选增强)** | 同源规则可生成 `required`/`maxlength` 等 HTML 属性;**不能**替代服务端 |
|
||||
|
||||
`/admin` 的新建/编辑页 = 内置 form:字段来自 schema,校验来自类型/可空;与站点自定义 form **同一套** `validate` + `db.insert`/`update`。
|
||||
|
||||
#### 5.5.4 与页面的关系
|
||||
|
||||
- 表单可以是独立路由页,或页面表里的一个「组件」导出(仍用 `|属性|值|样式|` 描述展示,提交走 form 类)。
|
||||
- **`page.compose_form id=… form=…`**:把 form 嵌入该页主区;`listen` 从首页与路由页收集表单并挂载 `/_form/{id}`(`app.mount_form` 仍可用)。校验失败时若表单有所属页,则带回该页壳重渲染。
|
||||
|
||||
### 5.6 文件职责
|
||||
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| `ext/web/web.mq.md` | 英文 `# page` `# style` `# db` `# form` `# app` |
|
||||
| `ext/web/网页.mq.md` | 中文 `# 页面` `# 样式` `# 数据库` `# 表单` `# 应用`(可包装英文实现,**不得**把中文名写进 `web.mq.md`) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 模块导出形状(配合寻址)
|
||||
|
||||
### 6.1 组件 `components/nav.mq.md`
|
||||
|
||||
```markdown
|
||||
## nav
|
||||
|
||||
`nav` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| `title` | `nav`.`title` | |
|
||||
| `href` | `nav`.`href` | |
|
||||
|
||||
**`nav`**
|
||||
```
|
||||
|
||||
说明:组件**内部**绑定仍可用 `` `表`.`列` ``(表名+列名皆引用)。与 index 主体里「模块命名空间 + 裸列名」的 `articles.`articles`.title` 分工:
|
||||
|
||||
- **跨文件、带导入命名空间** → `模块.`表`.列`;
|
||||
- **组件文件内、表已明确** → `` `表`.`列` `` 即可。
|
||||
|
||||
(若评审希望全站统一为一种形态,可在评审意见中二选一;默认允许上述两种。)
|
||||
|
||||
### 6.2 样式 `styles/shell.mq.md`
|
||||
|
||||
每个样式一个 `##`,**禁止** `## bag` + `json.set`:
|
||||
|
||||
```markdown
|
||||
## topnav
|
||||
… |属性|值| …
|
||||
**`topnav`**
|
||||
|
||||
## card-title
|
||||
…
|
||||
```
|
||||
|
||||
### 6.3 库 `db/articles.mq.md` / `db/index.mq.md`
|
||||
|
||||
- `articles`:`## schema`(或同名导出)返回结构表;
|
||||
- `index`:`## open` → 确保插件、建库、init、幂等种子,返回 `# 数据库` 句柄。
|
||||
|
||||
---
|
||||
|
||||
## 7. 运行时职责划分
|
||||
|
||||
```text
|
||||
作者 .mq.md 表(字面量单元格)
|
||||
│
|
||||
▼
|
||||
ext/web 类方法(Marqdo)
|
||||
│ 解析路径;需要时经 ABI host_query
|
||||
│ 调用入口模块 import 树上的 lib.member
|
||||
▼
|
||||
plugins/web(HTTP / SQL / HTML 壳)
|
||||
│
|
||||
▼
|
||||
浏览器:四区布局 + /_part 局部刷新 + /admin(可选)
|
||||
```
|
||||
|
||||
| 层 | 做 | 不做 |
|
||||
|----|----|------|
|
||||
| Marqdo 核心 | 表→Value、类/方法、import | 不识别 web 路径语法 |
|
||||
| `ext/web/*.mq.md` | 作者 API、中英面、委托插件 | 不直接 `host_*` |
|
||||
| `plugins/web` | 路径解析辅助、装配结果、listen、SQL、渲染 | 不要求作者写袋 |
|
||||
|
||||
**实现要点(评审通过后再做):**
|
||||
|
||||
1. ABI `host_query("call_lib_path")`:在**站点入口模块**上执行 `lib.member`;
|
||||
2. 插件函数由类方法调用(如 compose_components / compose_main);
|
||||
3. `listen` 合并页面内 part,注入 `db_url`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 全部废弃 · 从头开发(锁定)
|
||||
|
||||
**旧有网络扩展库内容一律作废**,包括但不限于:
|
||||
|
||||
| 范围 | 处理 |
|
||||
|------|------|
|
||||
| [`plugins/web/`](../../plugins/web/) | 评审通过后**删除或清空**,按本文重写 cdylib |
|
||||
| [`ext/web/`](../../ext/web/)(`web.mq.md` / `网页.mq.md` / templates) | 同上,**不**在旧 L1 上打补丁 |
|
||||
| 依赖旧 API 的示例(如当前 `examples/web-site`、`web-demo`、`man-write-site` 可跑胶水版) | 按 §4 规范重写或暂时移除 |
|
||||
| 依赖旧 API 的 gold / 单测 | 删除后按新 API 重写 |
|
||||
| 本文之前的袋式 / assemble / wire / `## bag` 等作者面 | 永久移出正典 |
|
||||
|
||||
**禁止**:在遗留代码上「修到能跑」再文档化。
|
||||
**允许**:实现时参考旧代码中的 HTTP/SQLite 技术经验,但**新树另起**,不以 ABI 表面或作者面兼容为目标。
|
||||
|
||||
历史摸索中明确不再回归的作者面模式:
|
||||
|
||||
- `json.parse` / `json.set` 拼 components/styles 袋;
|
||||
- 手写 `web.assemble` + 袋参数;
|
||||
- 手写 part JSON + `` `app`.part ``;
|
||||
- `|前端变量|后端数据库|` 填路由;
|
||||
- 「变量名即表名」魔法默认表;
|
||||
- 样式 `## bag`;掏空 index 只留 `wire.boot`。
|
||||
|
||||
---
|
||||
|
||||
## 9. 非本波次(可记入路线图)
|
||||
|
||||
- Postgres / Redis / S3 驱动细节(SQLite 已落地);
|
||||
- 复杂权限与多租户;
|
||||
- 子页路由糖的更多约定(`# 应用.route` 已够用)。
|
||||
|
||||
---
|
||||
|
||||
## 10. 评审清单
|
||||
|
||||
请确认或批注:
|
||||
|
||||
1. **§3 路径**:`模块.`导出`` 与 `模块.`表`.列`(列裸名)是否定为唯一正典?组件内 `` `表`.`列` `` 是否保留?
|
||||
2. **§4 index**:开库是否允许单独一行 `` db.open ``,还是必须进一步藏进 `web.应用`?
|
||||
3. **§5 分文件**:英文 `web.mq.md` / 中文 `网页.mq.md` 是否严格分语言、禁止混排?
|
||||
4. **§5.3**:列表查询用 `select` / `查询`、原始 SQL 用 `exec` / `执行` 是否认可?
|
||||
5. **§5.5 表单/校验**:字段表、校验表、服务端必校、admin 共用是否认可?
|
||||
6. **§5 槽位**:仅由组件导出名推断,是否足够?
|
||||
7. **§8 废弃**:是否确认**全部推倒重来**、不兼容旧实现?
|
||||
|
||||
评审通过后:冻结本文为 Accepted → **清空旧 web 扩展代码** → 按本文从零实现(骨架 → db CRUD/`select` → form/validate → 页面装配 → app listen → 规范示例 → gold)。
|
||||
@@ -4,9 +4,9 @@
|
||||
|---|---|
|
||||
| 状态 | 草案(已采纳方向;修正「配置文件」误解) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) |
|
||||
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) · **实现规范 [okf.md](okf.md)** |
|
||||
| 取代 | 此前「YAML = 人手写的编译器配置 / frontmatter 契约」的表述 |
|
||||
|
||||
| 说明 | 原则仍有效;**类型表、任务知识包、路线图以 [okf.md](okf.md) 为准** |
|
||||
---
|
||||
|
||||
## 决策
|
||||
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、标识符反引号、`-` 专用于循环) |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、同级再 `1.` 为新分支、标识符反引号、`-` 专用于循环) |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 |
|
||||
| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
|
||||
| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [module-namespace.md](module-namespace.md) |
|
||||
|
||||
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
|
||||
|
||||
@@ -17,7 +17,11 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
5. **标识符一律反引号**:凡表示变量槽位(形参、绑定、引用、遍历项、集合名)均写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
|
||||
5. **标识符默认反引号**:形参、绑定、引用写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
|
||||
**豁免:**
|
||||
- foreach 头 `` - [项](集合) `` 允许裸名或反引号(可混用),推荐裸名;循环体内引用仍用 `` `名` ``。
|
||||
- 脚注取元 `` 名[^键] ``:基名在紧跟 `` [^…] `` 时可省略反引号(`` `名`[^键] `` 仍合法);链式同理。
|
||||
- **斜体语句 / 粗体返回内部**:裸标识符默认是**变量**;字符串须 `"…"` 或 `'…'`;`` `名` `` 仍合法。
|
||||
|
||||
---
|
||||
|
||||
@@ -40,14 +44,16 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
| 标记 | 语义 |
|
||||
|------|------|
|
||||
| `#` … `######` | **`#` = 对象/类型**;**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
|
||||
| `#` … `######` | **`#` = 对象/类型**(可 `# Child = > Parent`);**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
|
||||
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
|
||||
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
|
||||
| 体内 `-` | **循环**(`while` 条件,或 `` [`项`](`集合`) `` 遍历) |
|
||||
| 体内 `-` | **循环**(`while` 条件,或 `[项](集合)` / `` [`项`](`集合`) `` 遍历) |
|
||||
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
|
||||
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
|
||||
| `` > `对象`.方法 … `` | 方法调用(实例 map 须含 `_type`) |
|
||||
| frontmatter `> path.mq.md` | 跨文件导入 |
|
||||
| frontmatter `> path.mq.md` [`as` / `作为` name] | 导入(绑定库名;默认 = 文件名茎) |
|
||||
| frontmatter `> use lib.member` [`as` name] / `使用` | 将库路径成员绑为本地短名 |
|
||||
| `> lib.member …` / `> lib.Type.member …` | 点号路径调用(路径段裸名、无反引号) |
|
||||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
||||
| `**…**` | **返回值**(架构级;函数结果) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
@@ -73,7 +79,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
| `**Hello**` 表示打印 | `> print text=Hello` |
|
||||
| `+ `x` > 0` 作分支 | `1. `x` > 0` |
|
||||
| `- 谁` 作形参 | `` + `谁` `` |
|
||||
| `[果](篮子)` 裸名遍历 | `` [`果`](`篮子`) `` |
|
||||
| `[果](篮子)` 裸名遍历 | **仍合法**(foreach 豁免);亦可用 `` [`果`](`篮子`) `` |
|
||||
|
||||
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
|
||||
|
||||
@@ -84,12 +90,13 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
### 程序语句(斜体)
|
||||
|
||||
```markdown
|
||||
*`x` = 1*
|
||||
|
||||
*`y` = `x` + 2*
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
*answer = ev[^message]*
|
||||
*`亦可用` = 1*
|
||||
```
|
||||
|
||||
行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
斜体内部:裸标识符 = 变量;字符串写 `"…"` / `'…'`。行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
|
||||
### 返回值(粗体)
|
||||
|
||||
@@ -97,9 +104,13 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
**"ok"**
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
粗体内部与斜体相同的值语法(裸词 = 变量;文本须引号)。
|
||||
|
||||
### 输出(内置函数 `print`)
|
||||
|
||||
```markdown
|
||||
@@ -118,7 +129,8 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
## 5. Frontmatter 与跨文件
|
||||
|
||||
同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。
|
||||
文件头 `---` 对为元信息。其中 `> file.mq.md` 为**导入**(绑定库名,成员不倒进全局);`> use lib.member` / `> 使用 库.成员` 引入本地短名。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法须 `` > `var`.method ``。详见 [module-namespace.md](module-namespace.md)。
|
||||
|
||||
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
|
||||
|
||||
---
|
||||
@@ -126,6 +138,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
## 6. 对象、函数、形参
|
||||
|
||||
- `# Name`:对象(构造体);`# main` 为入口对象。
|
||||
- `# Child = > Parent`:单继承(基类须为已定义对象名;方法沿链查找,子类可覆盖)。见 [objects.md](objects.md) §5。
|
||||
- `##` / `###` …:函数或方法;挂在对象下则为方法。
|
||||
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
|
||||
|
||||
@@ -206,11 +219,29 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
> print text=False
|
||||
```
|
||||
|
||||
**一条分支语句 = 从 `1.` 起、序号递增的一段有序列表。** 同级缩进上**再次出现 `1.`**(无论中间有无空行)开启**下一条**独立分支语句,不得并入上一段的臂列表:
|
||||
|
||||
```markdown
|
||||
- [`果`](`篮子`)
|
||||
1. `a`
|
||||
> print text=A
|
||||
2. *
|
||||
> print text=not-A
|
||||
|
||||
1. `b`
|
||||
> print text=B
|
||||
2. *
|
||||
> print text=not-B
|
||||
```
|
||||
|
||||
上例为两次独立判断(先 `a` 再 `b`),不是「四个臂的一个分支」。臂序号在同一分支内递增(`1.` → `2.` → `3.` …);**不要**在同一分支中途把序号重置为 `1.`。
|
||||
|
||||
```markdown
|
||||
- [果](篮子)
|
||||
> print text=今天吃`果`
|
||||
```
|
||||
|
||||
反引号形式等价:`` - [`果`](`篮子`) ``。两侧可混用。
|
||||
|
||||
`while`:
|
||||
|
||||
```markdown
|
||||
@@ -223,7 +254,56 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
## 9. 集合(表格)
|
||||
|
||||
同 v0。`` `篮子` = `` 后接 GFM 表。
|
||||
`` `名` = `` 后接 GFM 表;几何决定值类型(详见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md)):
|
||||
|
||||
| 形状 | 值 |
|
||||
|------|-----|
|
||||
| **1 列**(竖表) | `List`(表头 = foreach 元素名,不进入元素) |
|
||||
| **≥2 列 + 1 行数据**(横表) | `Map`:键 = 表头,值 = 该列标量 |
|
||||
| **≥2 列 + ≥2 行数据** | `Map`:键 = 表头,值 = 该列 `List`(列向) |
|
||||
| **≥2 列 + 0 行数据** | `Map`:键存在,值为空列表 |
|
||||
| **首列表头 `@` / `行` / `row`** | **行向** `List` of `Map`(标记列不进入字段;任意数据行数) |
|
||||
| 重复表头 | 诊断错误 |
|
||||
|
||||
**数据单元格是表达式**(与调用实参值语法相同:裸词、数字、`` `var` ``、算术、引号串;URL / `gpt-4o-mini` 等按路径·连字符折叠为文本)。表头仍是键名文本。细则:[table-cell-expressions.md](table-cell-expressions.md)。
|
||||
|
||||
```markdown
|
||||
*`k` = secret *
|
||||
|
||||
`cfg` =
|
||||
|
||||
| api_key | model |
|
||||
|---------|-------|
|
||||
| `k` | gpt-4o-mini |
|
||||
```
|
||||
|
||||
行向示例:
|
||||
|
||||
```markdown
|
||||
`订单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
| 2 | 梨 | 3 |
|
||||
|
||||
*`名` = `订单`[^1][^品名] *
|
||||
```
|
||||
|
||||
**脚注取元**(表达式级;可链式):
|
||||
|
||||
```markdown
|
||||
*`第一` = 篮子[^1] * # 基名可省略反引号(`[^` 已标明取元)
|
||||
*`种` = 分类[^苹果] *
|
||||
*`第一种苹果` = 货架[^苹果][^1] *
|
||||
*`亦可用` = `分类`[^苹果] * # 反引号形式并存
|
||||
```
|
||||
|
||||
- **List**:标签须为纯数字(1-based);`[^0]` / 越界 → 报错。
|
||||
- **Map**:标签为键文本(含 `"00"` 这类数字串键);缺键 → 报错。同一外形按接收值类型分派,不把 map 上的 `[^1]` 当成「第 1 个条目」。
|
||||
- 基名:`` `名`[^键] `` 与 `` 名[^键] `` 等价;无 `` [^ `` 时裸词仍是**文本字面量**(不是变量)。
|
||||
- 文末 `[^1]: …` 定义块仍是注释,与取元无关。
|
||||
- foreach:`List` 遍历元素;`Map` 遍历**键**(值用脚注取)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,266 @@
|
||||
# 模块命名空间(import / 点号寻址)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted;M1+M2 已落地** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
今日加载器把每个导入文件的顶层 `#` / `##` **扁平合并**进同一全局函数表;同名则**后导入静默覆盖**(`merge_top_level`)。
|
||||
|
||||
后果:
|
||||
|
||||
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存;import 顺序决定谁赢,错误表现为「缺 `pattern`」这类误导信息。
|
||||
- `lib/writeback` 的 `get` 盖住 `lib/json` 的 `get`。
|
||||
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
|
||||
|
||||
**结论**:Marqdo 必须支持**模块命名空间**与**点号寻址**。扁平静默覆盖不是可保留的「兼容糖」,而是会**掩盖冲突**的缺陷行为;本设计予以废除(落地时为破坏性变更,不设双轨裸名回退)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
### 2.1 目标
|
||||
|
||||
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
|
||||
2. **点号寻址调用**:`库.成员`、并预留 `库.对象.成员` 等多段路径;`.` 表示在定义树上的寻址,不是字段运算。
|
||||
3. **库名不是变量**:寻址段为**裸标识符**,**不加**反引号。反引号只用于值槽位(变量 / 形参 / 实例句柄)。
|
||||
4. **模块内名字默认不进全局**;需要本地短名时必须**显式** `use`,且冲突**报错**。
|
||||
5. **中英对等**:路径中英分文件;`as` / `作为` 与默认库名规则双语一致。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
- 第三方包管理 / 版本求解。
|
||||
- 在兼容期内继续支持扁平合并旧语义。
|
||||
- 「裸名仍可从最后一次导入解析」——**明确拒绝**。
|
||||
- 把库名写成 `` `time`.parse ``——**明确拒绝**(会把库名误当成变量)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心语义
|
||||
|
||||
### 3.1 模块 / 库
|
||||
|
||||
每个可导入的 `.mq.md` 文件是一个**库模块**:
|
||||
|
||||
| 内容 | 归属 |
|
||||
|------|------|
|
||||
| 顶层 `##` 自由函数 | 库根下的**函数** |
|
||||
| 顶层 `#` 对象 | 库根下的**类型(对象)** |
|
||||
| 类型下的 `##` 方法 | 该对象节点下的**成员函数**(可被路径寻址;实例调用见 §4.4) |
|
||||
| 被导入文件的 `# main` | **不**作为入口执行 |
|
||||
|
||||
### 3.2 导入句法(frontmatter)
|
||||
|
||||
| 英文 | 中文 | 含义 |
|
||||
|------|------|------|
|
||||
| `> lib/time.mq.md` | `> lib/时间.mq.md` | 导入;默认库名见 §3.3 |
|
||||
| `> lib/time.mq.md as time` | `> lib/时间.mq.md 作为 时间` | 导入并以给定库名绑定 |
|
||||
|
||||
规则:
|
||||
|
||||
- `as` / `作为` 后为**裸库名**(不加反引号)。
|
||||
- 同一文件内两个导入不得绑定同一库名 → 硬错误。
|
||||
- 禁止「只写路径、成员洒进全局」的旧语义。
|
||||
|
||||
### 3.3 默认库名
|
||||
|
||||
省略 `as` / `作为` 时,库名 = **文件名茎**(去掉 `.mq.md`):
|
||||
|
||||
| 路径 | 默认库名 |
|
||||
|------|----------|
|
||||
| `lib/time.mq.md` | `time` |
|
||||
| `lib/时间.mq.md` | `时间` |
|
||||
| `ext/ai/agent.mq.md` | `agent` |
|
||||
| `ext/ai/智能体.mq.md` | `智能体` |
|
||||
|
||||
### 3.4 调用解析顺序
|
||||
|
||||
1. **点号路径 callee**(§4)→ 按段在导入库 / 类型树上寻址。
|
||||
2. **当前文件**顶层 `#` / `##`(无点号的短名)。
|
||||
3. **L0 内置**。
|
||||
4. **插件注册名**(`lib/plugin` 加载后的全局表)。
|
||||
5. 否则 → 未知 callee。
|
||||
|
||||
---
|
||||
|
||||
## 4. 点号寻址(核心外形)
|
||||
|
||||
### 4.1 文法
|
||||
|
||||
```text
|
||||
path_callee ::= ident ('.' ident)+
|
||||
```
|
||||
|
||||
- 每一段都是**裸标识符**(库名、类型名、函数名)。
|
||||
- **整条路径都不使用反引号**。
|
||||
- `.` 只表示寻址分隔,与「变量上的方法调用」分流(§4.4)。
|
||||
|
||||
### 4.2 二段:`库.成员`
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/time.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`t` = > time.now_unix *
|
||||
*`s` = > time.format unix=`t` pattern=%Y-%m-%d *
|
||||
*`obj` = > json.parse text={"a":1} *
|
||||
*`a` = > json.get value=`obj` key=a *
|
||||
> print text=`s`
|
||||
```
|
||||
|
||||
| 路径 | 解析 |
|
||||
|------|------|
|
||||
| `time.now_unix` | 库 `time` → 函数 `now_unix` |
|
||||
| `json.parse` | 库 `json` → 函数 `parse` |
|
||||
| `agent.agent` | 库 `agent` → **类型** `agent`(构造) |
|
||||
|
||||
库根下的函数调用**不**注入 `self` / `自`。
|
||||
|
||||
### 4.3 三段及以上:`库.对象.成员`(预留并锁定语义)
|
||||
|
||||
后续常见形态:
|
||||
|
||||
```markdown
|
||||
> agent.agent # 库 → 类型:构造
|
||||
> 某库.某对象.某函数 # 库 → 类型 → 该类型下的 ## 成员
|
||||
```
|
||||
|
||||
解析规则(锁定):
|
||||
|
||||
1. 第一段必须是**已导入库名**。
|
||||
2. 第二段起在上一段节点的子表中查找:类型节点或函数节点。
|
||||
3. 若最终落在**函数**上则发起调用;若落在**类型**上则发起构造。
|
||||
4. 路径中任一段缺失 → 硬错误(禁止模糊回落到全局短名)。
|
||||
|
||||
实例方法若需要接收者,仍走 §4.4;`库.对象.方法` 表示定义树上的该成员(无接收者时:仅当该成员可作为无 `self` 的关联函数调用,否则报错「需要实例」)。这样 `.` 始终是**定义寻址**,逻辑一致。
|
||||
|
||||
中文库同理:`时间.格式化`、`智能体.智能体`、`智能体.智能体.单步`(若对类型成员做路径调用)。
|
||||
|
||||
### 4.4 变量 / 实例 vs 库路径(反引号分界)
|
||||
|
||||
| 写法 | 左侧重 | 是否反引号 |
|
||||
|------|--------|------------|
|
||||
| `time.parse` | 库名(绑定) | 路径段皆**裸名** |
|
||||
| `agent.agent` | 库名.类型名 | 裸名 |
|
||||
| `` > `助手`.step `` | **变量**(实例句柄) | 接收者**必须**反引号 |
|
||||
| `` > `out`.… `` | 变量 | 反引号 |
|
||||
|
||||
原则:
|
||||
|
||||
- **名在定义/导入空间里** → 点号路径,无 `` ` ` ``。
|
||||
- **名在值环境里**(绑定结果、形参、`self`)→ 反引号标识符;方法调用保持现有 `` > `obj`.method ``。
|
||||
|
||||
禁止混写 `` > `time`.parse ``(把库当成变量)。
|
||||
|
||||
### 4.5 应用侧完整示例
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/time.mq.md
|
||||
> lib/writeback.mq.md
|
||||
> ext/ai/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`助手` = > agent.agent model=… tools=… *
|
||||
*`out` = > `助手`.step task=… *
|
||||
*`body` = > json.stringify value=`out` *
|
||||
> writeback.record value=`body` key=ok
|
||||
```
|
||||
|
||||
(上例假定 `json` 已导入;`stringify` 为该库成员。)
|
||||
|
||||
---
|
||||
|
||||
## 5. 导出面
|
||||
|
||||
默认:库内顶层 `#` / `##` 均可被路径访问。
|
||||
|
||||
类型下的 `##` 挂在该类型节点下,供 `库.类型.成员` 寻址;实例调用仍用 `` `变量`.成员 ``。
|
||||
|
||||
本版不引入 `private`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 显式 `use`(可选短名,非静默兼容)
|
||||
|
||||
| 英文 | 中文 |
|
||||
|------|------|
|
||||
| `> use time.format` | `> 使用 时间.格式化` |
|
||||
| `> use time.format as fmt` | `> 使用 时间.格式化 作为 fmt` |
|
||||
|
||||
- `use` 右侧为**点号路径**(裸名寻址)。
|
||||
- 引入后本地短名可见;与导入库名或当前文件顶层同名 → **硬错误**。
|
||||
- **禁止** `use time.*`(无通配 `use`)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 与旧行为的关系(破坏性变更)
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| 导入 = 合并进全局 | 导入 = 绑定库名 |
|
||||
| 同名后写覆盖 | 无跨库扁平同名 |
|
||||
| `> parse` 来源不明 | 必须 `json.parse` 或显式 `use` |
|
||||
| (若曾设想)`` `time`.parse `` | **否**;库路径不加反引号 |
|
||||
|
||||
不提供扁平合并过渡开关。
|
||||
|
||||
---
|
||||
|
||||
## 8. 对分层与 ext 的影响
|
||||
|
||||
| 层 | 影响 |
|
||||
|----|------|
|
||||
| L0 内置 | 仍为全局短名 |
|
||||
| L1 / 官方 ext | 经库路径调用;**`ext/**/*.mq.md` 严禁 `host_*`** |
|
||||
| ABI 插件 | 插件注册表;agent/OKF 等领域逻辑放这里,**不得**塞进 `HostFn` |
|
||||
|
||||
**硬规则**:不得为「方便」把 `ext/ai` 领域能力写进 `src/host/dispatch.rs` / `src/host/*.rs`。标准库可走 `lib/*` → 薄 `host_*`;智能体专属走 `plugins/agent` 注册名(见 [ext-agent.md](ext-agent.md) §4)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 实现要点
|
||||
|
||||
1. 加载返回模块树(库 → 类型 → 成员);取消跨文件 `merge_top_level` 泼洒。
|
||||
2. 调用方解析 `path_callee`:按 `.` 分段,自导入表下行。
|
||||
3. 区分路径 callee 与 `` `变量`.方法 ``(词法:首段是否反引号 / 是否含裸点号路径)。
|
||||
4. 金样例与 stdlib 文档改为 `time.parse` 形态。
|
||||
|
||||
| 阶段 | 内容 |
|
||||
|------|------|
|
||||
| M0 | 本文 Accepted(含本修订) |
|
||||
| M1 | 二段路径 `库.成员` + 破坏旧扁平 — **已落地**(tree + bytecode;`as`/`作为`;stdlib/ext/tests 已迁) |
|
||||
| M2 | 三段 `库.对象.成员`;`use` / `使用` — **已落地**(实例方法路径调用报错,须 `` `var`.method ``) |
|
||||
| M3 | 诊断工具(可选) |
|
||||
|
||||
**双后端**:tree 与 bytecode 均支持点号路径调用与 `use` / `使用`(与 M1/M2 同语义)。
|
||||
|
||||
**金样例**:
|
||||
|
||||
| 路径 | 测什么 |
|
||||
|------|--------|
|
||||
| `tests/structure/ns/` | 二段/三段路径、`use`、导入 `as` |
|
||||
| `tests/errors/ns-instance-method.mq.md` | `库.类型.方法` 无接收者 → 硬错误(须 `` `var`.method ``) |
|
||||
|
||||
**L1 薄包装**:命名空间下 `net.http_post` 等解析到 **`lib/*.mq.md` 的 `##` 包装**,不是宿主别名。包装未声明的可选形参会被静默丢弃(曾导致 live agent 401:`headers` 未传到 `host_http_post`)。规则见 [stdlib-modules.md](stdlib-modules.md) §2.1。
|
||||
|
||||
---
|
||||
|
||||
## 10. 决议摘要
|
||||
|
||||
1. 导入绑定**库名**;成员不进全局。
|
||||
2. 调用以**裸名点号路径**寻址:`库.成员`,并支持 `库.对象.成员`;`.` = 定义树寻址。
|
||||
3. **库名 / 路径段不加反引号**;反引号只用于值变量与实例接收者。
|
||||
4. 拒绝扁平合并与裸名双轨兼容;短名仅显式单成员 `use`。
|
||||
5. M1/M2 已实现;M3 另开。
|
||||
+35
-4
@@ -58,13 +58,44 @@
|
||||
官方 `lib/*.mq.md` 以**顶层自由函数**为主:全部为 `##`(不再使用 `#` 冒充类型)。
|
||||
真正的类型化扩展(如 `ext/llm`)使用 `# 类型` + `##` 方法。
|
||||
|
||||
## 5. 非目标(本波)
|
||||
## 5. 继承(`# 子类 = > 父类`)
|
||||
|
||||
- 继承 / 接口 / 可见性
|
||||
```markdown
|
||||
# Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*`msg` = "Hello, `who`!" *
|
||||
**`msg`**
|
||||
|
||||
# Loud = > Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*`msg` = "HELLO, `who`!" *
|
||||
**`msg`**
|
||||
```
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| 语法 | `# Child = > Parent`(右侧必须是 `>` + 简单类型名;无路径) |
|
||||
| `_type` | 构造后仍为**最具体子类名** |
|
||||
| 方法查找 | 先子类 `##`,未命中再沿基类链;同名则子类覆盖 |
|
||||
| 构造 | **不**隐式调用父构造(无 auto-super)。需要父字段时在子类正文首行显式 `` `self` = > Parent … ``,再改字段并 `**`self`**`;返回 map 的 `_type` 仍为子类名 |
|
||||
| 多继承 | 不支持 |
|
||||
| 诊断 | 未知基类、循环继承、非法 RHS(如 `# Foo = 1`) |
|
||||
|
||||
详见 [object-inheritance.md](../roadmap/object-inheritance.md)。
|
||||
|
||||
## 6. 非目标(本波)
|
||||
|
||||
- 接口 / 可见性 / 多继承
|
||||
- 无 `_type` 的「鸭子」方法分发
|
||||
- 用表格声明字段 schema(表格仍表示集合)
|
||||
- 用表格声明字段 schema(表格仍表示数据集合;见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md))
|
||||
|
||||
## 6. 迁移摘要
|
||||
## 7. 迁移摘要
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
|
||||
@@ -0,0 +1,482 @@
|
||||
# Marqdo 的 OKF 实现
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted(规范);实现分层见 §10** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 调研 | [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
|
||||
| 命令现状 | [catalog-cli.md](catalog-cli.md)(v0 已落地) |
|
||||
| 生成式清单方向 | [generated-yaml-manifest.md](generated-yaml-manifest.md) |
|
||||
| 智能体消费面 | [ext-agent.md](ext-agent.md) · [ext-agent-plan.md](ext-agent-plan.md) · 任务知识包见本文 §7 |
|
||||
| 外部规范 | [OKF SPEC v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) |
|
||||
|
||||
本文是 **Marqdo 语言侧 OKF 实现的详细设计**:界定我们借鉴什么、已经实现什么、下一阶段必须补什么。
|
||||
**不把 Google OKF 整本照搬进语言语义**;Marqdo 的可执行真相永远是 `.mq.md` 源。
|
||||
|
||||
---
|
||||
|
||||
## 1. 定位
|
||||
|
||||
### 1.1 OKF 是什么(对我们)
|
||||
|
||||
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog) 用 **目录中的 Markdown + YAML frontmatter** 表示可交换知识:概念一页一文、路径即 ID、链接成图、最小强制面(几乎只强制 `type`),并在 v0.2 加入信任信号。
|
||||
|
||||
Marqdo 对齐的判断是:
|
||||
|
||||
> 人类可读的 Markdown 可以成为人与 Agent 的一等交换面;**程序本身也应能投影成同一形态的知识包**。
|
||||
|
||||
### 1.2 Marqdo 多走的一步
|
||||
|
||||
| | OKF(通用知识) | Marqdo |
|
||||
|--|-----------------|--------|
|
||||
| 正文 | 自由散文 | **可执行语法**(`.mq.md`) |
|
||||
| 成功标准 | 互通、可策展、可信任 | 能跑 + 能读 + 可被 Agent 索引 |
|
||||
| 清单角色 | 知识本身 | **从源派生的投影**(非第二套权威配置) |
|
||||
|
||||
一句话:
|
||||
|
||||
**OKF 形、Marqdo 义 — 形态对齐 OKF;词汇与生命周期服务模块、依赖、任务技能与信任,而不是 BigQuery 业务概念表。**
|
||||
|
||||
### 1.3 三层文档(勿混)
|
||||
|
||||
| 层 | 谁写 | 是什么 |
|
||||
|----|------|--------|
|
||||
| **源** | 人 / 编码 Agent | `.mq.md`:唯一语义权威,打开即读、即可跑 |
|
||||
| **工程目录包** | `marqdo catalog` | 模块依赖/导出总览(`Marqdo Module`) |
|
||||
| **任务知识包** | `plan` 晋升等 | 任务↔技能↔可执行资源(`Marqdo Task` / `Marqdo Agent Skill`) |
|
||||
|
||||
`marqdo view output` 出 HTML 站点,与 OKF 包**分工**:人读程序站 vs Agent/工具读知识包。见 [view.md](view.md)、[catalog-cli.md](catalog-cli.md) §4。
|
||||
|
||||
---
|
||||
|
||||
## 2. 设计原则(锁定)
|
||||
|
||||
1. **源为唯一权威** — 依赖、导出、可执行行为以 `.mq.md` 为准;知识包是提取或晋升结果。
|
||||
2. **生成、可复现** — 同一源树 + 同一工具版本 → 同一工程目录包(时间戳字段可规范化忽略)。
|
||||
3. **勿手改生成物** — 文件头 / `generated` 标明 GENERATED;手改不被承认为权威。
|
||||
4. **最小强制面** — 互通只要求:合法 frontmatter、`type` 字段、可解析的 `resource` / 链接;未知 `type` **必须优雅降级**(仍可读正文与已知字段)。
|
||||
5. **格式而非平台** — 包可 `cat` / `git clone`;不绑定某一云或某一模型。
|
||||
6. **清单可删可再生** — 无 catalog 时解释器仍能直接从源工作;catalog **不是**语言语义的一部分。
|
||||
7. **可执行资源显式** — 凡声称「可跑」的概念必须有 `resource:` 指向 `.mq.md`(或等价路径),禁止只靠散文描述冒充程序。
|
||||
|
||||
---
|
||||
|
||||
## 3. 概念模型
|
||||
|
||||
### 3.1 Bundle(知识包)
|
||||
|
||||
一个 OKF 风格 bundle 是目录树:
|
||||
|
||||
```text
|
||||
<bundle-root>/
|
||||
index.md # 可选:人/Agent 总览
|
||||
log.md # 可选:变更史(策展用)
|
||||
catalog.yaml # 可选:机器向总清单
|
||||
concepts/… # 或 modules/…:概念页(frontmatter + Markdown)
|
||||
resources/… # 可选:被引用的可执行 .mq.md(任务包常用)
|
||||
```
|
||||
|
||||
**Concept ID** = 相对 bundle 根、去掉扩展名的路径(OKF 惯例)。
|
||||
例:`concepts/tasks/a1b2c3d4e5f6.md` → ID `concepts/tasks/a1b2c3d4e5f6`。
|
||||
|
||||
**联系** = frontmatter 中的路径字段 + 正文中的 Markdown 链接,形成可遍历图。
|
||||
|
||||
### 3.2 Marqdo 使用的两类 bundle
|
||||
|
||||
| Bundle | 默认根 | 生产者 | 消费者 |
|
||||
|--------|--------|--------|--------|
|
||||
| **工程目录包** | `.marqdo/`(`-o` 可改) | `marqdo catalog` / `sync` | 人、CI、未来编译加速、通用 Agent |
|
||||
| **任务知识包** | `.marqdo/agent-kb/` | `ext/ai` 的 `plan` 晋升等 | 父智能体快路径、策展、复用 |
|
||||
|
||||
二者词汇共享(`type` / `generated` / `verified` / `status`),目录职责分离:
|
||||
**不要**把探索用的 `agent-runs/` 时间戳文件当成稳定概念 ID。
|
||||
|
||||
---
|
||||
|
||||
## 4. Frontmatter 词汇表
|
||||
|
||||
### 4.1 所有概念页的公共字段
|
||||
|
||||
| 字段 | 必填 | 含义 |
|
||||
|------|------|------|
|
||||
| `type` | **是** | 概念类型字符串(见 §5) |
|
||||
| `title` | 推荐 | 短标题 |
|
||||
| `description` | 可选 | 一句话说明 |
|
||||
| `tags` | 可选 | 字符串列表 |
|
||||
| `resource` | 视类型 | 指向权威源或可执行 `.mq.md` 的相对路径 |
|
||||
| `status` | 推荐 | `draft` \| `stable` \| `deprecated` |
|
||||
| `generated` | 生成物必有 | `{ by, at? }` — 谁生成 |
|
||||
| `verified` | 可选 | `{ by, at? }` — 谁核验(非 LLM 口述) |
|
||||
| `sources` | 可选 | 出处列表(OKF v0.2) |
|
||||
| `stale_after` | 可选 | 绝对日期,过期后消费者应降级信任 |
|
||||
| 未知字段 | — | **保留、不拒绝** |
|
||||
|
||||
信任档位(推导,不必单独存字段):
|
||||
|
||||
| 条件 | 档位 |
|
||||
|------|------|
|
||||
| 无 `verified` | 未验证(机器生成草稿) |
|
||||
| 有 `verified.by` 为确定性工具(如 `marqdo-agent/spawn`) | 机器确认 |
|
||||
| 有人工审核约定(未来) | 人工审核 |
|
||||
|
||||
### 4.2 工程模块页额外字段(v0 已用)
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `depends` | 导入列表(从源 frontmatter `> path` 提取) |
|
||||
| `exports` | 顶层 `#` 导出名列表 |
|
||||
|
||||
### 4.3 任务 / 技能页额外字段(目标词汇)
|
||||
|
||||
| 字段 | 所在 type | 含义 |
|
||||
|------|-----------|------|
|
||||
| `skill` | `Marqdo Task` | 指向 Skill 概念页的相对路径 |
|
||||
| `goal` 或正文中的规范化 goal | `Marqdo Task` | 匹配材料(规范化规则见 §7.3) |
|
||||
| `llm_free` | `Marqdo Agent Skill` | 资源是否仍含 `agent.step` / LLM 调用(机器启发) |
|
||||
| `quality` | `Marqdo Agent Skill` | 整数启发分(长度、llm_free 等),**非**模型打分 |
|
||||
|
||||
---
|
||||
|
||||
## 5. `type` 注册表(Marqdo 义)
|
||||
|
||||
未知 type **不得**导致解析失败;工具可跳过专用逻辑,仍展示 title/正文/链接。
|
||||
|
||||
| `type` | 状态 | 含义 | 主要生产者 |
|
||||
|--------|------|------|------------|
|
||||
| `Marqdo Catalog` | **v0 已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
|
||||
| `Marqdo Module` | **v0 已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
|
||||
| `Marqdo Task` | **规范已定;实现待做** | 一项可匹配的任务意图 | `plan` 晋升 |
|
||||
| `Marqdo Agent Skill` | **规范已定;实现待做** | 指向可执行工作簿的技能 | `plan` 晋升 |
|
||||
| 其他 | 开放 | 第三方/未来扩展 | — |
|
||||
|
||||
**不**引入 Google OKF 的 `Metric` / BigQuery 表类型作为 Marqdo 核心词汇;需要时可由用户包自行使用,运行时降级。
|
||||
|
||||
---
|
||||
|
||||
## 6. 工程目录包(v0 — 已实现)
|
||||
|
||||
### 6.1 CLI
|
||||
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
marqdo sync [PATH] -o OUT_DIR # 别名
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或单文件;目录则递归 `*.mq.md` |
|
||||
| `-o` | `.marqdo` | 输出根;写入前创建,**覆盖**同名生成文件 |
|
||||
|
||||
实现:[`src/catalog.rs`](../../src/catalog.rs)。金样:`tests/gold.rs` → `catalog_writes_yaml`、`catalog_includes_agent_kb_concepts`。
|
||||
|
||||
### 6.2 生成物布局
|
||||
|
||||
```text
|
||||
OUT_DIR/
|
||||
catalog.yaml
|
||||
index.md
|
||||
modules/
|
||||
<path-with-__>.md
|
||||
concepts/ # O3:从 **/.marqdo/agent-kb/concepts/ 复制
|
||||
tasks/…
|
||||
skills/…
|
||||
```
|
||||
|
||||
路径拍扁:`structure/import/main.mq.md` → `modules/structure__import__main.md`。
|
||||
`agent-kb` 下的可执行 `.mq.md` **不**进 Module 表(避免与概念/资源重复);Task/Skill 概念页进 `concepts/` 与 `catalog.yaml` 的 `concepts:`。
|
||||
|
||||
### 6.3 `catalog.yaml`(现行字段)
|
||||
|
||||
```yaml
|
||||
# GENERATED by marqdo — do not edit by hand
|
||||
type: Marqdo Catalog
|
||||
title: marqdo-project
|
||||
generated:
|
||||
by: marqdo/<crate-version>
|
||||
modules:
|
||||
- id: structure/hello # resource 去掉 .mq.md
|
||||
resource: structure/hello.mq.md
|
||||
title: … # 源 frontmatter title,否则用路径
|
||||
imports: [] # 或 ["lib/x.mq.md as x", …]
|
||||
exports:
|
||||
- name: Hello World
|
||||
kind: fn
|
||||
# 可选(源 frontmatter 有则透传):
|
||||
# verified: { by: … }
|
||||
# sources: […]
|
||||
concepts: [] # 或 Task/Skill 条目(O3)
|
||||
# - id: concepts/tasks/<sig>
|
||||
# type: Marqdo Task
|
||||
# title: …
|
||||
# status: …
|
||||
# page: concepts/tasks/<sig>.md
|
||||
# resource: …
|
||||
# skill: …
|
||||
```
|
||||
|
||||
提取规则:
|
||||
|
||||
- **imports**:源文件 YAML frontmatter 中以 `>` 开头的导入行(经 `parse_import_spec`)。
|
||||
- **exports**:解析成功则用 AST 顶层函数名;否则回退扫描 `# ` 标题行。
|
||||
- **verified / sources**:源 frontmatter 有则写入 module/concept 条目(O3)。
|
||||
- **concepts**:扫描 `**/.marqdo/agent-kb/concepts/**/*.md`,复制到 `OUT_DIR/concepts/`。
|
||||
- **不**提取正文 `>` 动态调用图、不写锁哈希、不写跨仓 URL。
|
||||
|
||||
### 6.4 模块概念页(现行)
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Marqdo Module
|
||||
title: …
|
||||
resource: path/to/file.mq.md
|
||||
depends: […]
|
||||
exports: […]
|
||||
generated:
|
||||
by: marqdo/<version>
|
||||
# verified / sources:源有则透传
|
||||
---
|
||||
```
|
||||
|
||||
正文含「勿手改」、**可点击依赖链接**(解析到同包其它 Module 页)、导出表。`index.md` 含 Modules 表与 **Agent knowledge** 节(链到 `concepts/`)。
|
||||
|
||||
### 6.5 仍相对完整 OKF 愿景的缺口
|
||||
|
||||
| 缺口 | 说明 |
|
||||
|------|------|
|
||||
| 无通用 Concept ID 遍历 API | catalog 为生成物;无独立查询命令 |
|
||||
| 无 `stale_after` / Attested 再现 | 信任信号仅可选 `verified`/`sources` |
|
||||
| 无 `log.md` | 无策展历史(O4) |
|
||||
| 运行时不读 catalog | 解释器不依赖生成物(有意为之) |
|
||||
|
||||
O2/O3 已补:Task/Skill 知识包、catalog 扫入 agent-kb、模块页可点依赖、可选信任字段。
|
||||
|
||||
---
|
||||
|
||||
## 7. 任务知识包(规范 — 实现路线 O2)
|
||||
|
||||
服务「父智能体优化过的工作簿,同任务应直接执行」:把子 Marqdo / 技能登记为 OKF 概念,用 ID 与链接匹配,而不是私有 `index.json`。
|
||||
|
||||
### 7.1 布局(锁定)
|
||||
|
||||
```text
|
||||
.marqdo/
|
||||
agent-runs/workbook-<slug>-<ts>.mq.md # 仅当显式 workbook_dir= 时(可 gc)
|
||||
agent-kb/ # 任务知识包 bundle(默认首次 plan 就写这里)
|
||||
index.md
|
||||
log.md # 可选
|
||||
catalog.yaml # 可选;可由 promote 或 catalog 刷新
|
||||
concepts/
|
||||
tasks/<slug>.md # type: Marqdo Task;sig 在 frontmatter
|
||||
skills/<slug>.md # type: Marqdo Agent Skill
|
||||
resources/
|
||||
<slug>.mq.md # 默认可执行工作簿(探索与晋升同一路径)
|
||||
```
|
||||
|
||||
默认根可通过 `plan` 参数 `kb_dir` / `知识库目录` 覆盖。`.gitignore` 已忽略 `**/.marqdo/`。
|
||||
|
||||
路径用可读 **slug**(由 goal 派生:拉丁小写、CJK 保留、其它变 `-`,最长约 48 字符)。**`sig` 仅写在 frontmatter**,用于精确匹配。同 slug 异 sig 时用 `slug-<sig前4位>`。旧包若仍以 `<sig>` 为文件名,lookup 会回退识别。
|
||||
|
||||
### 7.2 概念页模板
|
||||
|
||||
**Task**(匹配入口):
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Marqdo Task
|
||||
title: <短摘要>
|
||||
description: <规范化 goal>
|
||||
sig: <12hex>
|
||||
status: stable
|
||||
tags: [agent-task]
|
||||
skill: ../skills/<slug>.md
|
||||
generated:
|
||||
by: marqdo-agent/plan
|
||||
verified:
|
||||
by: marqdo-agent/spawn
|
||||
at: <ISO8601>
|
||||
---
|
||||
|
||||
# Task
|
||||
|
||||
See [skill](../skills/<slug>.md).
|
||||
```
|
||||
|
||||
**Skill**(可执行绑定):
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Marqdo Agent Skill
|
||||
title: <短名>
|
||||
sig: <12hex>
|
||||
resource: ../../resources/<slug>.mq.md
|
||||
status: stable | candidate
|
||||
llm_free: true | false
|
||||
quality: <int>
|
||||
hits: <int>
|
||||
generated:
|
||||
by: marqdo-agent/plan
|
||||
at: <ISO8601>
|
||||
verified:
|
||||
by: marqdo-agent/spawn
|
||||
at: <ISO8601>
|
||||
---
|
||||
|
||||
# Skill
|
||||
|
||||
Prefer spawning `resource` over re-planning.
|
||||
```
|
||||
|
||||
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。
|
||||
|
||||
### 7.3 任务签名 → Concept 路径
|
||||
|
||||
材料:
|
||||
|
||||
1. `goal`:Unicode NFC → trim → 连续空白折叠为单空格。
|
||||
2. 若调用方工具表非空:工具名排序后追加进材料。
|
||||
3. **不**把父 `standing` 计入签名(易变导致永不命中)。
|
||||
|
||||
输出:稳定短哈希 `sig`(`agent_goal_sig`)+ 可读 `slug`(`agent_goal_slug`)。路径:
|
||||
|
||||
- `concepts/tasks/<slug>.md`
|
||||
- `concepts/skills/<slug>.md`
|
||||
- `resources/<slug>.mq.md`
|
||||
|
||||
匹配顺序:
|
||||
|
||||
1. **精确**:slug 试探 + frontmatter `sig` → 扫目录 `sig:` → 旧 hex 文件名。
|
||||
2. **别名(Accepted)**:精确 miss 后,扫 Task FM `aliases:`(YAML 列表或 `[a, b]`);`normalize_goal(query)` 与某条 alias **精确相等**则命中同一 Skill/resource。lookup 返回 `match: exact|alias`;`plan` 对 alias 写 `cache=soft-hit`。
|
||||
3. **规范句(Accepted)**:仍 miss 时对 goal 做轻量 `agent_kb_canonicalize`(剥站立前缀、去尾标点),再精确/别名各试一次;命中返回 `match: canonical`,`cache=soft-hit`。
|
||||
4. **近义(Accepted,默认开)**:仍 miss 且 `near_match=True` 时,对 Task `title|description|aliases` 做本地**字符 bigram 词袋 + 余弦**;`best.score >= near_threshold`(默认 `0.78`)则 `match: near` 并带 `score`,`cache=soft-hit`,并可 `agent_kb_add_alias`。这是稀疏词法近邻,**不是** embedding 模型。
|
||||
5. **父裁决 soft_match(Accepted,默认关)**:仍 miss 且 `plan soft_match=True` 时,把 `agent_kb_near_match` 排序候选(含 score;空则退回 `list_tasks`)交给父模型:`DECISION: REUSE` + `SLUG:` 或 `DECISION: NEW`;REUSE 后可 `agent_kb_add_alias`。
|
||||
6. **不做**默认 dense embedding / 远程向量库。远期 dense 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) E。
|
||||
|
||||
`agent_kb_promote` 可选 `aliases=`(字符串或列表)写入 Task;再晋升时合并既有 aliases。
|
||||
|
||||
### 7.4 与 `## plan` 的契约
|
||||
|
||||
| 参数 | 默认 | 含义 |
|
||||
|------|------|------|
|
||||
| `reuse` / `复用` | `True` | 允许知识包快路径 |
|
||||
| `optimize` / `优化` | `False` | 跳过知识包,强制再规划 |
|
||||
| `force` / `强制` | `False` | 忽略知识包 |
|
||||
| `soft_match` / `软命中` | `False` | miss 后父裁决 REUSE/NEW(须显式打开;候选为 near 排序列表) |
|
||||
| `near_match` / `近义命中` | `True` | lookup 第四趟本地 n-gram;`False` 关闭 |
|
||||
| `near_threshold` / `近义阈值` | `0.78` | near 自动命中最低余弦分 |
|
||||
| `promote` / `晋升` | `True` | DONE 后固化并写入/更新概念与 resource |
|
||||
| `kb_dir` / `知识库目录` | `.marqdo/agent-kb` | bundle 根 |
|
||||
| `workbook_dir` / `工作簿目录` | `None` | 默认直接写 `kb_dir/resources/<slug>.mq.md`;显式传入则用该目录下的临时 `workbook-<slug>-<ts>.mq.md` |
|
||||
| `improve_every` / `改进周期` | `3` | candidate 每 N 次命中触发 ≤1 轮改进 |
|
||||
| `explore_n` / `探索次数` | `3` | 同任务已有文件数 `< N` 且非 `llm_free` 时,强制新建 `explore/<slug>/<k>.mq.md` 尝试不同路径(第 2 次默认 dual 骨架) |
|
||||
|
||||
调用示例(路径可直接写在参数里,无需 `json.parse`):
|
||||
|
||||
```markdown
|
||||
> `助手`.plan goal=… max_rounds=3
|
||||
> `助手`.plan goal=… workbook_dir=".marqdo/agent-runs"
|
||||
> `助手`.plan goal=… explore_n=3
|
||||
```
|
||||
|
||||
快路径:
|
||||
|
||||
1. lookup 命中且 resource **llm_free**(含现场检测已固化源)→ spawn → `cache=hit`,**父 LLM 不调用**。
|
||||
2. 否则若任务相关文件数 `< explore_n` → 写入新的 explore 变体,父 LLM 被提示尝试不同路径;成功则固化并晋升。
|
||||
3. 否则走 candidate 命中 / `improve_every` 改进逻辑。
|
||||
|
||||
`DECISION: DONE` 时先 `agent_workbook_solidify`(把仍含 `worker.step` 的簿固化为 `# main` **返回**答案,而非仅 `print`),再晋升并写 `verified`。
|
||||
显式 `workbook=` 续跑优先于知识包查找。
|
||||
|
||||
质量启发(覆盖 skill 时,不调模型):`llm_free` 优先;源更短优先;同质取较新。更差 `quality` 不覆盖现 skill。
|
||||
|
||||
### 7.5 自我成长如何落在 OKF 上
|
||||
|
||||
| 能力 | 机制 |
|
||||
|------|------|
|
||||
| 优化 | 规划循环固化代码 → 更优 `resources/<slug>.mq.md` |
|
||||
| 迭代 | 同 Concept slug/`sig` 覆盖 resource + 刷新 `generated`/`verified` |
|
||||
| 成长 | 命中快路径;`candidate`/`hits`/`improve_every` 驱动再优化;`log.md` 可审计 |
|
||||
| 分发 | 整包 `agent-kb/` 可复制(格式即契约) |
|
||||
|
||||
---
|
||||
|
||||
## 8. 运行时与工具职责
|
||||
|
||||
| 组件 | 读 OKF? | 写 OKF? | 备注 |
|
||||
|------|----------|----------|------|
|
||||
| 解释器 / 字节码 VM | 否(语义) | 否 | 只跑 `.mq.md` |
|
||||
| `marqdo catalog` | — | 工程目录包 | v0 |
|
||||
| `plugins/agent`(`agent_kb_*`)+ `ext/ai` `plan` | 任务包 | 晋升时写任务包 | O2;**不**进核心 `src/host` |
|
||||
| `lib/fs` | 通用文件 | 通用文件 | L1 包装 |
|
||||
| `marqdo view` | 否 | 否 | HTML 另一轨 |
|
||||
| 未来 `marqdo kb query` | 是 | 否 | 可选:按 type/tag/链接查询 |
|
||||
|
||||
agent-kb 运行时实现归属 **agent 插件**(`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / `agent_kb_record_hit` / `agent_workbook_solidify` / `agent_kb_task_files`),由 `ext/ai/agent` 调用;禁止把这些原语加回 `HostFn`。
|
||||
|
||||
解释器**不得**因缺少 catalog 而拒绝运行源文件。
|
||||
|
||||
---
|
||||
|
||||
## 9. 安全与边界
|
||||
|
||||
| 风险 | 对策 |
|
||||
|------|------|
|
||||
| 把生成物当配置手改 | 文档 + GENERATED 头;CI 可选校验 |
|
||||
| 错误技能被复用 | 快路径必 spawn+inspect;失败标 `draft` 并重规划 |
|
||||
| 签名过宽 | tools 指纹;文档强调 exact goal |
|
||||
| 密钥进入知识包 | 继承 env;禁止把 key 写入 resource/概念正文 |
|
||||
| 包膨胀 | runs 与 kb 分离;仅 DONE 晋升 |
|
||||
| 与语言语义耦合 | catalog/kb 失败不影响 `marqdo run` 源文件 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 实现路线
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **O0** | 调研 + 生成式清单方向 + `.mq.md` 后缀 | **done** |
|
||||
| **O1** | `marqdo catalog` / `sync`:Module + Catalog YAML | **done**(v0) |
|
||||
| **O2** | 本文锁定的任务知识包:`Marqdo Task` / `Agent Skill`;`plan` reuse/promote | **done**(host kb_* + plan 快路径) |
|
||||
| **O3** | catalog 增强:`verified`/`sources` 可选;模块页可点击依赖;扫入 `agent-kb` 概念供人浏览 | **done** |
|
||||
| **O4** | `log.md` 策展、可选 `kb query`、Attested-style「再现跑通」收据(非 BigQuery) | 远期 |
|
||||
| **O5** | 相近任务软命中:aliases + canonicalize + 本地 n-gram `near` + `soft_match` 父裁决已落地;dense embedding 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) E | **A/B/C/D-near done** |
|
||||
|
||||
O2 设计落盘后,智能体侧实现文档可薄化为指向本文 §7,避免两套真理。
|
||||
|
||||
---
|
||||
|
||||
## 11. 非目标
|
||||
|
||||
- 在 Marqdo 内核实现完整 OKF 验证器产品或云托管知识库。
|
||||
- 用 OKF 清单替代模块命名空间 / 导入语义([module-namespace.md](module-namespace.md))。
|
||||
- 强制用户提交 `.marqdo/` 进 git。
|
||||
- **默认**语义相似检索 / 向量库(可选软命中见 O5 / [okf-near-match.md](../roadmap/okf-near-match.md);不进内核)。
|
||||
- 跨仓技能市场(可后续在概念图上扩展)。
|
||||
- 照搬 OKF `Attested Computation` 的 BigQuery executor 模型。
|
||||
|
||||
---
|
||||
|
||||
## 12. 与既有文档的关系
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [okf-and-marqdo.md](../research/okf-and-marqdo.md) | 调研;产业背景与借鉴边界 |
|
||||
| [generated-yaml-manifest.md](generated-yaml-manifest.md) | 早期「生成式清单」方向;**词汇与原则并入本文,命令细节见 catalog-cli** |
|
||||
| [catalog-cli.md](catalog-cli.md) | O1 CLI 与 v0 落盘的操作说明 |
|
||||
| [ext-agent-plan.md](ext-agent-plan.md) | 多步执行;缓存/复用应引用本文 §7 |
|
||||
| [ext-agent.md](ext-agent.md) | 框架总览;自写回 ≠ 跨调用 OKF 知识包 |
|
||||
|
||||
---
|
||||
|
||||
## 13. 决议摘要
|
||||
|
||||
1. Marqdo 的 OKF 实现 = **形态对齐 + Marqdo 类型词汇 + 生成/晋升管道**,不是语言换皮。
|
||||
2. **O1–O3 已落地**(工程目录包、任务知识包、catalog 扫入 agent-kb + 人读链接图);**O4** 策展/查询为远期。
|
||||
3. 可执行真相是 `.mq.md`;概念页负责**寻址、信任与联系**——人与 Agent 都是闭环里的一环。
|
||||
4. 父智能体复用优化结果,应走 **Task → Skill → resource → spawn**,而不是私有 JSON 缓存主路径。
|
||||
5. 未知 `type` 降级;无清单亦可运行源码。
|
||||
|
||||
---
|
||||
|
||||
## 14. 一句话
|
||||
|
||||
**Marqdo 用 OKF 风格的知识包索引程序与任务技能:源负责跑,概念负责找与信,catalog 与 agent-kb 分管工程目录与自我成长。**
|
||||
@@ -28,7 +28,7 @@
|
||||
|------|-------------------|
|
||||
| `> lib/text.mq.md` | `trim` · `split` · `join` |
|
||||
| `> lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
|
||||
| `> lib/table.mq.md` | `rows` · `row_at` |
|
||||
| `> lib/table.mq.md` | `put` · `rows` · `row_at` · list/map(见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| `> lib/表.mq.md` | `行数` · `取行` |
|
||||
|
||||
示例:
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
|
||||
|
||||
---
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
| 模块族 | 英文库 | 中文库 | 状态 |
|
||||
|--------|--------|--------|------|
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有 |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有(`put`/`改` + list/map;见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
|
||||
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
|
||||
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
|
||||
@@ -52,9 +52,23 @@ OS / HTTP / 时钟 / 共享库 …
|
||||
| 层 | 谁实现 | 用户是否直接调用 |
|
||||
|----|--------|------------------|
|
||||
| **L0** | 解释器内置 | 是(`print`/`len`/…) |
|
||||
| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装 |
|
||||
| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装;ABI v2 `host_query` 仅插件可调 |
|
||||
| **L1 官方库** | `lib/*.mq.md` | **是** |
|
||||
| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`) |
|
||||
| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`);**禁止** `host_*`,经 `lib/*` 或插件注册名 |
|
||||
|
||||
> **已变更(M1+M2)**:[module-namespace.md](module-namespace.md) — 取消跨文件扁平合并;L1/ext 经**裸名点号路径**调用(`time.parse`、`agent.agent`;M2:`库.对象.成员` + `use`),库名不加反引号;实例方法须 `` `var`.method ``;不再靠 import 顺序覆盖同名。
|
||||
|
||||
### 2.1 L1 薄包装 → 宿主(命名空间后必读)
|
||||
|
||||
点号路径 `net.http_post` / `json.stringify` 等解析到 **`lib/*.mq.md` 的 `##` 函数**,再转发 `host_*`。未在包装形参表声明的可选实参会被**静默丢弃**(曾导致 live agent 401:`Authorization` 等 `headers` 从未到达宿主)。
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| 每个 `host_*` 包装 | 须在 `+` 形参表声明**全部**宿主可选参数,默认 `None`,并在 `**> host_…**` 中**原样转发** |
|
||||
| `http_post` / `提交` | `content_type=None` 时宿主按默认 JSON charset 处理 |
|
||||
| 已对齐(2026-08-07) | `net`/`网络`(headers、content_type、body)、`sys`/`系统`(load_dotenv、exec)、`ext/ai/llm`(load_env / 加载环境 path)、`json.stringify` indent、`foreign`/`外联` stdin、`math`/`数学` plot*/solve 可选项 |
|
||||
|
||||
**无**扁平合并回退;**无**裸名双轨兼容。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -9,15 +9,19 @@
|
||||
|
||||
**并发**执行单元。`spawn` 四选一:
|
||||
|
||||
| 参数 | 执行方式 | `join` 返回值 |
|
||||
|------|----------|---------------|
|
||||
| `path=` | `marqdo run <file>` 子进程 | 退出码 `Int` |
|
||||
| 参数 | 执行方式 | `join` / `wait` 返回值 |
|
||||
|------|----------|------------------------|
|
||||
| `path=` | `marqdo run <file> --emit-result <tmp>` 子进程 | map `{ code, value, stdout?, stderr? }`(`# main` 返回值;quiet 时 piped 捕获 I/O 尾部,不 inherit TTY) |
|
||||
| `fn=` + 可选 `args=` | 当前入口模块中的函数(进程内线程) | 函数返回值 `Value` |
|
||||
| `code=` | 外联代码块(`Value::Code`)子进程 | stdout `Text` |
|
||||
| `lang=` + `source=` | 外联源码子进程 | stdout `Text` |
|
||||
|
||||
`args=`:文件子任务为 `List`(命令行参数);函数子任务为 `Map`(形参绑定)或 `List`(按 `arg0`… 命名)。
|
||||
|
||||
`quiet=` / `静默=`(默认 `True`):仅影响 **文件** 子任务的 **TTY**。默认 **piped 捕获** stdout/stderr(父终端不被污染,`wait` map 带截断后的 `stdout`/`stderr` 供父智能体观察);`False` 时继承父进程 stdout/stderr(map 中 I/O 字段为空)。**答案载荷仍以 `# main` 返回值为主**(经 `--emit-result` 旁路)。外联子任务仍经管道收集 stdout 供 `join` 返回,不受此参数影响。
|
||||
|
||||
**事件转发(文件子任务)**:spawn 时设置 `MARQDO_EVENT_FORWARD=<临时 ndjson>`;子进程内 `EventBus.publish` 追加写入该文件;父在 `wait` 阻塞期间 tail 并 republish(加 `source=child`)。这样子 LLM `stream=True` 的 token 能进 `marqdo view` SSE,而不破坏 quiet TTY 契约。函数子任务在同进程内,本来就共享 EventBus。
|
||||
|
||||
父进程结束(含 panic)时 **KillOnDrop** 终止所有文件/外联子进程;函数线程标记为 killed 并 detach(无法强杀 OS 线程)。
|
||||
|
||||
`poll` → `{ status: running | done | failed, … }`;函数 done 时含 `value`,进程/外联 failed 时含 `code` 或 `error`。
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
# `lib/table` / `lib/表` — 列表与字典
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地**(可用级集合 API) |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [table-cell-expressions.md](table-cell-expressions.md) · [roadmap/tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 读写对
|
||||
|
||||
| 读 | 写 |
|
||||
|----|----|
|
||||
| 脚注 `` `xs`[^1] `` / `` `m`[^key] `` / 嵌套 `` `m`[^a][^1] `` | **`table.put` / `表.改`** |
|
||||
|
||||
`put` / `改` 的 `at=`(`于=`)与脚注同构:文本键、**1-based** 整数下标,或键/下标组成的路径列表。
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`h` = > table.put in=None at=Authorization value=Bearer-x*
|
||||
|
||||
`xs` =
|
||||
|
||||
| v |
|
||||
|---|
|
||||
| a |
|
||||
| b |
|
||||
|
||||
*`xs` = > table.put in=`xs` at=1 value=A*
|
||||
```
|
||||
|
||||
`in=None` 且 `at=` 为单个文本键 → 新建单键字典。值一律不可变更新(返回新集合)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 索引约定
|
||||
|
||||
| API | 基数 |
|
||||
|-----|------|
|
||||
| `put` / `改` 路径中的整数;脚注 `[^n]` | **1-based** |
|
||||
| `at` / `row_at` / `set_at` / `insert` / `remove_at` / `slice` / `index_of` | **0-based** |
|
||||
|
||||
---
|
||||
|
||||
## 3. API 摘要(EN ↔ ZH)
|
||||
|
||||
| EN | ZH | 说明 |
|
||||
|----|----|------|
|
||||
| `put` | `改` | 按路径改一元(首选写入) |
|
||||
| `len` / `rows` | `长度` / `行数` | 长度 |
|
||||
| `at` / `row_at` | `取` / `取行` | 0-based 取元 |
|
||||
| `append` / `prepend` / `concat` | `追加` / `前插` / `拼接` | 列表 |
|
||||
| `insert` / `set_at` / `remove_at` / `pop` | `插入` / `改位` / `删位` / `弹出` | 列表位操作 |
|
||||
| `first` / `last` / `slice` | `首` / `末` / `切片` | |
|
||||
| `contains` / `index_of` / `reverse` | `含有` / `下标` / `反转` | |
|
||||
| `clear` | `清空` | 列表或字典 |
|
||||
| `get` / `set` / `delete` / `has` | `取键` / `设` / `删键` / `有键` | 浅层字典 |
|
||||
| `keys` / `values` / `items` / `merge` / `size` | `键表` / `值表` / `项表` / `合并` / `键数` | |
|
||||
| `empty_list` / `empty_map` | `空表` / `空字典` | |
|
||||
|
||||
嵌套改写优先 `put`/`改`;`set`/`set_at` 仅浅层。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 `lib/json`
|
||||
|
||||
| 用途 | 用 |
|
||||
|------|----|
|
||||
| 解析 / 序列化 / `quote` | `json.parse` · `json.stringify` · `json.quote` |
|
||||
| 集合读写 | **`table.*` / `表.*`** |
|
||||
| 兼容 | `json.set` / `json.append` / `json.get` / `json.keys` 仍为别名,新代码勿依赖 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 宿主
|
||||
|
||||
`host_collection_put` + list/map 原语(见 `src/host/collection.rs`)。作者面经 `lib/table` / `lib/表` 调用,不直接写 `host_*`。
|
||||
@@ -3,6 +3,7 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | v1 已落地 |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 库 | `lib/writeback.mq.md` · `lib/自写回.mq.md` |
|
||||
|
||||
## 定位
|
||||
@@ -18,19 +19,41 @@
|
||||
-->
|
||||
```
|
||||
|
||||
- 注释内仅保留 `marqdo-out` 标识,**不存行号**(避免写回后行号漂移)
|
||||
- 默认在**调用行下方**插入或替换紧邻块(中间可有空行)
|
||||
- `at_end=true` / `末尾=true`:在文件末尾保留单块(替换已有末尾块)
|
||||
命名槽(智能体成功/失败互不覆盖):
|
||||
|
||||
```markdown
|
||||
<!-- marqdo-out ok
|
||||
status=ok result=…
|
||||
-->
|
||||
<!-- marqdo-out error
|
||||
pending
|
||||
-->
|
||||
```
|
||||
|
||||
- 注释内为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
|
||||
- 默认在**调用行下方**插入或替换紧邻**无键**块
|
||||
- `at_end=true`:替换文件末尾的**无键**块
|
||||
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽(智能体单步用父调用行,即 `step` 语句下方);`ensure` 在缺失时写入占位且不覆盖已有正文。命名槽互不覆盖,也不使用文件末尾单块。
|
||||
- `line=` / `行=`:显式锚点行号。子任务 / 异步写回必须带上,否则会锚到子任务内部调用行。主机侧有全局互斥锁,写前从磁盘重读入口源,避免并发写互相覆盖。
|
||||
|
||||
### 替换跨度与空行
|
||||
|
||||
替换 `<!-- marqdo-out … -->` 时,被替换跨度**包含**注释块结束 `-->` 后的**单个**换行符(不把该换行留在文件里)。这样多次 `record` **不会**在块下方累积多余空行。
|
||||
|
||||
命名槽仍锚在调用行(如 `step` / `写回`)下方;整簇结束后保留**一条**有意空行即可,且应稳定。
|
||||
|
||||
## API
|
||||
|
||||
| EN | ZH | 说明 |
|
||||
|----|-----|------|
|
||||
| `record` | `写回` | `value=`,可选 `at_end=false` |
|
||||
| `get` | `取` | 可选 `at_end=false` |
|
||||
| `clear` | `清除` | 可选 `at_end=false` |
|
||||
| `list` | `列出` | 全文所有输出块(含推断锚点行) |
|
||||
| `record` | `写回` | `value=`;可选 `at_end`、`key`、`line` |
|
||||
| `get` | `取` | 可选 `at_end`、`key`、`line` |
|
||||
| `clear` | `清除` | 可选 `at_end`、`key`、`line` |
|
||||
| `ensure` | `确保` | `key=` + 可选 `placeholder=`、`line=`;槽已存在则不动 |
|
||||
| `list` | `列出` | 全文所有输出块(命名槽含 `key` 字段) |
|
||||
|
||||
可选参数语法:`` + `参数名`=默认值 ``(与现有参数列表兼容)。
|
||||
|
||||
Host:`host_writeback_*`(`src/host/writeback.rs`)。
|
||||
Host:`host_writeback_*`(`src/host/writeback.rs`);智能体侧经 `lib/subtask` 异步调用写回,避免阻塞推理主路径。
|
||||
|
||||
**与 `ext/ai/agent`:** `## step` / `## 单步` 在 D2 起 **默认自动** `record` 到 `ok`/`error` 槽(参数 `writeback=` / `写回=` 可关)。多步工作簿依赖此默认,见 [ext-agent-plan.md](ext-agent-plan.md) · [ext-agent.md](ext-agent.md)。
|
||||
@@ -3,8 +3,8 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 + L1 全模块落地** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
|
||||
|
||||
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
|
||||
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
@@ -42,7 +42,7 @@
|
||||
|
||||
## 3. 官方库导入(S2)
|
||||
|
||||
Frontmatter:
|
||||
Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可改)。成员经点号路径调用(`time.parse`、`json.get`),不倒进全局短名。完整语义见 [module-namespace.md](module-namespace.md)。
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -51,6 +51,8 @@ Frontmatter:
|
||||
---
|
||||
```
|
||||
|
||||
调用示例:`> time.now_unix`、`> json.parse text=…`。需要本地短名时用 `> use time.format`(冲突 → 硬错误)。
|
||||
|
||||
`std/text.mq.md` 等价于 `lib/text.mq.md`。解析顺序:
|
||||
|
||||
1. 相对当前文件
|
||||
@@ -75,8 +77,8 @@ Frontmatter:
|
||||
| `lib/subtask.mq.md` / `lib/子任务.mq.md` | `spawn` `poll` `wait` `kill` `wait_all` |
|
||||
| `lib/text.mq.md` | `str_trim` `str_split` `str_join` |
|
||||
| `lib/文本.mq.md` | `去空白` `拆分` `拼接` |
|
||||
| `lib/table.mq.md` | `rows` `row_at` |
|
||||
| `lib/表.mq.md` | `行数` `取行` |
|
||||
| `lib/table.mq.md` | `put` 为首选写入;`rows`/`row_at` 及完整 list/map API — 见 [stdlib-table.md](stdlib-table.md) |
|
||||
| `lib/表.mq.md` | `改` 为首选写入;`行数`/`取行` 及完整 list/map API |
|
||||
|
||||
完整清单见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
---
|
||||
title: table cell expressions
|
||||
status: Accepted
|
||||
date: 2026-08-12
|
||||
related: markdown-mapping.md · roadmap/tables-maps-footnotes.md · call-arguments.md
|
||||
---
|
||||
|
||||
# 表单元格表达式(T5)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted** |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [call-arguments.md](call-arguments.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
v1 把 GFM 数据单元格一律收成 **字面量**(`Int` / `Text`)。结果虽是 `Map` / `List`,却不能写:
|
||||
|
||||
```markdown
|
||||
`h` =
|
||||
|
||||
| api_key | model |
|
||||
|---------|-------|
|
||||
| `api_key` | `model` |
|
||||
```
|
||||
|
||||
作者只好用 `json.set` 链或 JSON 字符串拼接——这是**实现缺口**,不是「字典只能装字面量」的语义必然。
|
||||
|
||||
---
|
||||
|
||||
## 2. 锁定规则
|
||||
|
||||
### 2.1 数据单元格 = 与调用实参相同的值语法
|
||||
|
||||
每个**数据**单元格(非表头、非分隔行)按 [`parse_call_arg_value`](../../src/parse/expr.rs) 解析,再在绑定求值时执行:
|
||||
|
||||
| 单元格写法 | 含义 |
|
||||
|------------|------|
|
||||
| `苹果` / `Alpha` | 裸词 → 文本字面量(与今日竖表兼容) |
|
||||
| `42` | 整数 |
|
||||
| `` `api_key` `` | 变量引用 |
|
||||
| `` `a` + `b` `` | 普通表达式 |
|
||||
| `True` / `假` / `None` | 布尔 / 空 |
|
||||
| `"https://…"` / `".marqdo/x"` | 引号字符串(可含 `/`、插值) |
|
||||
| `https://api.openai.com/v1` | **路径折叠**:无空格的 `Text/Text/…` 除法链收成整段文本(同调用实参) |
|
||||
| `gpt-4o-mini` | **连字符散文**:不拆成减法(同调用实参) |
|
||||
| `` /about ``、`` /chat/completions `` | 以 `/` 开头的路径散文 → 整段文本 |
|
||||
| 空单元格 | 空文本 `""` |
|
||||
|
||||
### 2.2 表头仍是键名文本
|
||||
|
||||
表头单元格**不**求值:键 = trim 后的表头字符串(与今日一致)。不允许 `` | `k` | `` 当动态键(v1 非目标;需要时另文)。
|
||||
|
||||
### 2.3 几何语义不变
|
||||
|
||||
竖表 / 横表单行 Map / 多行列向 Map / `@`·`行`·`row` 行向记录——**形状规则不变**;只把「单元格 → `Expr::Literal`」换成「单元格 → 完整 `Expr`」。
|
||||
|
||||
求值已由解释器对 `Expr::List` / `Expr::Map` 递归完成,字节码后端已发射列表/字典,**无需新 AST 节点**。
|
||||
|
||||
### 2.4 求值时机
|
||||
|
||||
表出现在 `` `名` = `` 右侧时,在**该绑定语句**求值:单元格内变量读**当时**环境。构造函数体里的表与语句表规则相同。
|
||||
|
||||
### 2.5 错误
|
||||
|
||||
- 单元格表达式非法 → 与别处表达式相同的 `path:line:col` 诊断(行号取该表行)。
|
||||
- 变量未定义 → 求值期报错。
|
||||
- 不引入「单元格静默当字面量」的回退(除 §2.1 已列的路径/连字符折叠,与调用实参对齐)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 作者示例(目标体验)
|
||||
|
||||
```markdown
|
||||
*`api_key` = > sys.env_get name=OPENAI_API_KEY *
|
||||
*`model` = "gpt-4o-mini" *
|
||||
|
||||
`handle` =
|
||||
|
||||
| api_key | base_url | model | suffix |
|
||||
|---------|----------|-------|--------|
|
||||
| `api_key` | https://api.openai.com/v1 | `model` | /chat/completions |
|
||||
```
|
||||
|
||||
`handle` 为含运行时 `api_key` / `model` 的字典;静态 URL 与 suffix 仍可裸写(路径折叠)。
|
||||
|
||||
嵌套:
|
||||
|
||||
```markdown
|
||||
*`prompt` = hello *
|
||||
|
||||
`msg` =
|
||||
|
||||
| role | content |
|
||||
|------|---------|
|
||||
| user | `prompt` |
|
||||
|
||||
*`messages` = > json.append list=None item=`msg` *
|
||||
```
|
||||
|
||||
(列表字面量表仍可用竖表;需要「单行记录」时用横表或 `@` 行向表。)
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容性
|
||||
|
||||
| 旧写法 | 行为 |
|
||||
|--------|------|
|
||||
| 纯中文/英文词、整数 | **不变** |
|
||||
| `gpt-4o-mini`、URL、`/path` | **不变**(折叠规则与调用实参一致) |
|
||||
| 真正要做除法 / 减法 | 用空格或括号:`` `n` / 2 ``、`` `a` - 1 ``;或先在表外算再 `` `x` `` 填入 |
|
||||
|
||||
破坏性:几乎无。唯一需注意的是「想在单元格里写算术且两侧是裸词」——与调用实参同一套消歧。
|
||||
|
||||
---
|
||||
|
||||
## 5. 非目标(本阶段)
|
||||
|
||||
- 表头动态键
|
||||
- 单元格内 `>` 调用(可用表外算完再引用)
|
||||
- 单元格内多语句 / 分支
|
||||
- 把叙述区(注释段)里的 GFM 表当成可执行(仍为注释)
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收
|
||||
|
||||
| 项 | 标准 |
|
||||
|----|------|
|
||||
| 金样 | 横表单元格 `` `var` `` 读环境;竖表旧金样全绿 |
|
||||
| 路径 | `https://…`、`/chat/completions`、`gpt-4o-mini` 仍为文本 |
|
||||
| 扩展 | `ext/ai/llm` 构造可用表写入运行时字段,去掉无必要的 `json.set` 链 |
|
||||
| 文档 | 本页 + roadmap T5 + markdown-mapping §9 同步 |
|
||||
|
||||
实现跟踪见 [roadmap/tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) **T5**。
|
||||
+49
-4
@@ -90,8 +90,16 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
|
||||
## 4. 信息架构
|
||||
|
||||
侧栏文件索引 + 主区:结构(AST+注释;旁侧函数大纲可搜索)· 执行 · 源码。表达式为表面语法。
|
||||
**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||||
侧栏文件索引 + 主区:结构(AST+注释)· 执行 · 源码。结构旁**右侧栏**(现有 outline 槽)为:
|
||||
|
||||
| 区块 | 内容 |
|
||||
|------|------|
|
||||
| **Functions** | 原函数大纲 + 搜索;可折叠(默认展开) |
|
||||
| **Variables** | 跑完后的入口(`# main`)顶层绑定只读快照;List/Map/`@` 行向渲成 HTML 表;可折叠(默认展开) |
|
||||
|
||||
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板。
|
||||
|
||||
表达式为表面语法。**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -102,8 +110,44 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
| `GET` | `/` | 默认打开第一个 `.mq.md`(无文件时为空提示) |
|
||||
| `GET` | `/file?path=…` | 单文件页 |
|
||||
| `GET` | `/api/tree` | JSON 树(可选) |
|
||||
| `GET` | `/api/events?path=…` | 可选长订 EventBus(调试);**Stream 面板默认不用**(避免页载常连导致标签页一直转圈) |
|
||||
| `POST` | `/api/run` | JSON `{path, stdin?}` → **直接返回** `text/event-stream`(本次 run 的事件);结束后关流 |
|
||||
| `POST` | `/api/foreign-run` | 外联代码块试跑 |
|
||||
|
||||
根目录锁死;拒绝 `..` 逃逸。
|
||||
根目录锁死;拒绝 `..` 逃逸。默认页加载仍可整页执行;Stream 为增强路径。
|
||||
|
||||
### 5.1 Stream 面板(对齐主流 LLM 呈现)
|
||||
|
||||
**仅当**当前文件 frontmatter 导入了 `ext/ai/llm` / `大模型` 或 `ext/ai/agent` / `智能体`(及等价路径)时,在 live Execution 区显示;普通脚本页不出现该组件。
|
||||
|
||||
参考常见助手产品(思考折叠 + 正文流式、工具/子步骤独立卡片):**不要**把所有 SSE 事件打成一条混色终端日志。
|
||||
|
||||
| 区块 | 事件 | 呈现 |
|
||||
|------|------|------|
|
||||
| **Thinking** | `reasoning` | 可折叠;流式追加到同一块;默认展开直至本轮 `delta`/`done` 开始,之后可收起 |
|
||||
| **Answer** | `delta` | **主文**;token 连续拼进同一段落(禁止每 token 换行);主色正文 |
|
||||
| **Decision** | `decision` | 时间线条目标记(`RUN` / `CONTINUE` / `DONE` / `REUSE` / `NEW` + 可选 summary) |
|
||||
| **Tool** | `tool_start` / `tool_end` | 父 Plan-and-Move 的 CALL/READ:名称 + kind;`tool_end` 可带截断 `result` |
|
||||
| **Phase** | `decompose` | 父 pre-run 分解开始(workbook 链);填补「决策后到首 token」空隙 |
|
||||
| **Child / Workbook** | `await` → `round` | `await`:Child **running…** 占位卡(quiet 子任务等待中);`round`:升级为完成卡(退出码 + 可选 `result`) |
|
||||
| **Status** | `run_start` / `done` / `error` | 顶栏状态 + 错误行;嵌套 LLM `done`(无 `run_id`)只冲刷 drip,不改顶栏;终态 `done.result` 仅在无 Answer 时作摘要 |
|
||||
|
||||
**传输与流畅度(对齐 ChatGPT 类产品):**
|
||||
|
||||
1. **Run = 一次 `fetch` POST**,用 `ReadableStream` 读响应体里的 SSE 帧;**不要**页载常驻 `EventSource`。
|
||||
2. **「Run with input」拦截表单**:`preventDefault` 后走同一 Stream `/api/run`,**禁止整页重载**;带 `?stdin=` 进入时 live 页也不再阻塞跑完,改为自动开 Stream。
|
||||
3. **只改 Stream 对话框 DOM**;token **按动画帧合批一次写入**(rAF coalesce,不人为节流;打字感来自网络到达节奏)。
|
||||
4. **Stick-to-bottom**:仅在用户仍贴底时跟随;程序化 `scrollTop` 产生的 scroll 事件忽略;上拉后不抢滚动,可点「↓ Latest」。
|
||||
5. **Stop**:`AbortController` 中止 fetch。
|
||||
6. **子任务并发进度**:`spawn` 立即返回;`wait` 阻塞父循环期间,子进程经 `MARQDO_EVENT_FORWARD` 把 EventBus 帧实时转发到父 SSE;view 把 `source=child` 的 delta 画进 Child 卡。quiet 仍不污染父 TTY。
|
||||
|
||||
视觉约束(与 §2 一致):
|
||||
|
||||
- 浅色内容面,不用深色「伪终端」底;Thinking 用次要字色 / 浅底。
|
||||
- 一屏只突出 Answer;Thinking 与 Child 是附属。
|
||||
- plan 多轮:每一轮 Child 一张卡;父侧 Thinking/Answer 按 decision 分轮,不清空历史。
|
||||
|
||||
事件字段约定(与 [agent-streaming.md](../roadmap/agent-streaming.md) 一致):`round` 可带 `result`(子 `# main` 返回值摘要);`reasoning`/`delta` 的 `text` 为增量。
|
||||
|
||||
---
|
||||
|
||||
@@ -113,4 +157,5 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
|
||||
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
|
||||
4. 冷启动无明显外网依赖。
|
||||
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
|
||||
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
|
||||
6. Stream:`fetch`+SSE 局部更新;Thinking/Answer 分栏;stick-to-bottom;rAF 合批;页载不常连 EventSource。
|
||||
+3
-3
@@ -54,8 +54,8 @@ cargo clippy --all-targets
|
||||
|
||||
```bash
|
||||
# Windows PowerShell 示例
|
||||
$env:HTTPS_PROXY="http://127.0.0.1:7897"
|
||||
$env:HTTP_PROXY="http://127.0.0.1:7897"
|
||||
$env:HTTPS_PROXY="http://127.0.0.1:7890"
|
||||
$env:HTTP_PROXY="http://127.0.0.1:7890"
|
||||
cargo build
|
||||
```
|
||||
|
||||
@@ -63,7 +63,7 @@ cargo build
|
||||
|
||||
```toml
|
||||
[http]
|
||||
proxy = "http://127.0.0.1:7897"
|
||||
proxy = "http://127.0.0.1:7890"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -192,7 +192,7 @@ OKF 规范强调:一页纸能讲清 v0.1 的互通面;v0.2 只**加词汇、
|
||||
来自本次调研、建议在 `design/` 或 `adr/` 中跟进:
|
||||
|
||||
1. **`.mq.md` 的双重解析模型** — Markdown CST 与 Marqdo AST 如何共享同一文本、何处分叉。
|
||||
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳,见 [design/generated-yaml-manifest.md](../design/generated-yaml-manifest.md))。
|
||||
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳;**实现规范见 [okf.md](../design/okf.md)**,命令见 [catalog-cli.md](../design/catalog-cli.md))。
|
||||
3. **正文中的依赖声明语法** — import / 链接如何写出,供工具提取进生成清单。
|
||||
4. **Agent 友好但不 Agent 绑定** — 源格式对 LLM 可写,语义对确定性工具可检。
|
||||
5. **可渲染结果的 attestation(后期)** — 文档内求值结果的可验证性。
|
||||
|
||||
@@ -0,0 +1,181 @@
|
||||
# 智能体流式输出(未来规划)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 已落地**(view SSE) |
|
||||
| 日期 | 2026-08-10 |
|
||||
| 相关 | [ext-llm.md](../design/ext-llm.md) · [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md)(父 Plan-and-Move / CALL·READ) · [stdlib-subtask.md](../design/stdlib-subtask.md) · [view.md](../design/view.md) |
|
||||
| 痛点 | `complete` / `step` / `plan` 均为整段返回;用户看不到思考与中间输出 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
当前体验:
|
||||
|
||||
| 路径 | 行为 | 体验问题 |
|
||||
|------|------|----------|
|
||||
| `` `model`.complete `` | 等 HTTP 整包结束再返回字符串 | 长推理「卡住」无反馈 |
|
||||
| `` `助手`.step `` | 拼提示 → complete → 解析 CALL/答案 | 工具轮次与模型吐字均不可见 |
|
||||
| `` `助手`.plan `` | 多轮 spawn + 父 LLM;子任务默认 `quiet` | 父侧只有最终 `result` map;过程静默 |
|
||||
|
||||
这与「文档驱动、过程可审计」并不矛盾——**落盘真相**仍可以是工作簿与写回;缺的是**运行时的渐进呈现**(TTY / view / 调用方回调)。
|
||||
|
||||
约束回顾(不得破坏):
|
||||
|
||||
1. 文件子任务默认静默:答案走 `# main` **返回值**([stdlib-subtask.md](../design/stdlib-subtask.md))。
|
||||
2. `ext/**` 不直调 `host_*`;流式原语进 `ext/ai/llm` + 必要时薄 host/net。
|
||||
3. 多轮哲学仍是模式 C(子文件接力 + OKF),不是把 transcript 堆进单文件。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标
|
||||
|
||||
1. **可选**流式看到:模型增量文本、(可选)工具调用开始/结束、plan 轮次边界。
|
||||
2. 默认保持今日语义:未开流式 = 整段 `complete` / 整包 `result`。
|
||||
3. 流式是**呈现与旁路**,不替代 `**返回**` / `plan.result` / 写回。
|
||||
4. CLI、`marqdo view`、嵌入调用方可共用同一事件模型。
|
||||
|
||||
非目标(本规划):
|
||||
|
||||
- 把 Marqdo 做成聊天产品 UI 框架。
|
||||
- 强制所有 `print` 改流式 API。
|
||||
- 在 quiet 子进程里把子 `print` 默认真传父 TTY(与返回优先冲突)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 分层设计
|
||||
|
||||
```text
|
||||
LLM 供应商 SSE / chunked
|
||||
↓
|
||||
ext/ai/llm stream=True → 事件迭代 / 回调 / 写 channel
|
||||
↓
|
||||
ext/ai/agent step/plan 订阅事件 → 可选透传或写回「过程槽」
|
||||
↓
|
||||
呈现面:TTY | view EventSource | 调用方 foreach 事件表
|
||||
```
|
||||
|
||||
### 3.1 事件模型(锁定方向)
|
||||
|
||||
统一为可 JSON 化的小 map(便于写回与 view):
|
||||
|
||||
| `type` | 含义 | 主要字段 |
|
||||
|--------|------|----------|
|
||||
| `reasoning` | 模型思考增量(如 DeepSeek `reasoning_content`) | `text` |
|
||||
| `delta` | 模型答案增量文本 | `text` |
|
||||
| `tool_start` / `tool_end` | 工具轮(父 plan CALL/READ 已发;view Tool 卡) | `name`, `kind?`, `result?` |
|
||||
| `round` | plan 轮次边界(子工作簿跑完) | `round`, `workbook`, `exit_code?`, `result?`(子返回值摘要) |
|
||||
| `decision` | DONE / CONTINUE / RUN | `decision`, `summary?` |
|
||||
| `done` | 本调用结束 | `result`(答案正文;不含 thinking) |
|
||||
| `error` | 失败 | `message` |
|
||||
|
||||
中英键名可在 L1 包装层镜像;插件/wire 先用英文 `type`。
|
||||
|
||||
### 3.2 `llm`:流式完成
|
||||
|
||||
```markdown
|
||||
*`model` = > llm *
|
||||
*`stream` = > `model`.complete prompt=… stream=True *
|
||||
- [`ev`](`stream`)
|
||||
*`t` = > json.get value=`ev` key=type *
|
||||
1. `t` == delta
|
||||
*`chunk` = > json.get value=`ev` key=text *
|
||||
> print text=`chunk`
|
||||
2. `t` == done
|
||||
*`answer` = > json.get value=`ev` key=result *
|
||||
```
|
||||
|
||||
或回调形(若日后支持函数值作实参):`on_delta=` —— v1 优先 **事件列表 / 可迭代句柄**,少发明回调语法。
|
||||
|
||||
实现要点:
|
||||
|
||||
- `lib/net` 或 llm 插件支持 **读 SSE / chunked body**(今日 `http_post` 偏整包)。
|
||||
- `stream=False`(默认)路径零行为变化。
|
||||
- 金样:mock SSE fixture,不强制打真网。
|
||||
|
||||
### 3.3 `agent.step` / `plan`:过程透传
|
||||
|
||||
| 开关(草案) | 默认 | 行为 |
|
||||
|--------------|------|------|
|
||||
| `stream=False` | ✓ | 与今日相同 |
|
||||
| `stream=True` | | 向**当前进程**呈现面推送事件;返回值仍是最终 map |
|
||||
| `trace=True` | 可选 | 把事件追加写入调用行写回槽 `trace`(审计);与 TTY 流式可分立 |
|
||||
|
||||
plan 特有:
|
||||
|
||||
- `await_workbook` **前**发 `await`(view Child running 占位);结束后发 `round`。
|
||||
- 父 pre-run 分解发 `decompose`。
|
||||
- 父 LLM 的 `complete` 若 `stream=True`,`delta` 冒泡到 plan 的 stream。
|
||||
- **子文件 quiet 不变(TTY)**;默认骨架 `step stream=True`,子 EventBus 经 `MARQDO_EVENT_FORWARD` **实时转发**到父 SSE(`source=child`)。答案仍以 `# main` 返回为准。
|
||||
|
||||
### 3.4 呈现面
|
||||
|
||||
| 面 | 做法 |
|
||||
|----|------|
|
||||
| CLI | `delta` 直接写 stdout(无额外 JSON 包装);结构化事件可 `--trace-events` 走 stderr / 旁路文件 |
|
||||
| `marqdo view` | Execution 区 Stream 面板订阅 SSE(见 [view.md](../design/view.md) §5.1):Thinking / Answer / Child 分栏,非混色日志 |
|
||||
| 库调用方 | foreach 事件集合,自行决定 UI |
|
||||
|
||||
**view Stream 锁定(S3 UI):**
|
||||
|
||||
1. `reasoning` → 可折叠 Thinking;`delta` → 主文 Answer(连续拼接)。
|
||||
2. `round` → 独立 Child/Workbook 卡(路径链 + 可选 `result`);不与父 Answer 混排。
|
||||
3. `decision` → 时间线条目标记。
|
||||
4. 视觉跟 view HIG 浅色壳,不用深色终端底。
|
||||
5. **传输**:`POST /api/run` 直接 SSE;前端 `fetch`+`ReadableStream`(非页载 EventSource);rAF 合批;stick-to-bottom。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与「返回优先」的关系
|
||||
|
||||
| 通道 | 职责 |
|
||||
|------|------|
|
||||
| stream / trace | **过程**(体验、调试、审计) |
|
||||
| `# main` `**…**` / `plan.result` | **结果**(编排、OKF、调用方消费) |
|
||||
| writeback `ok`/`error` | **落盘摘要**(默认可关) |
|
||||
|
||||
禁止:仅靠 stream 文本当作子任务成功条件;DONE / 固化仍看退出码、返回值与源码形态。
|
||||
|
||||
---
|
||||
|
||||
## 5. 推荐落地顺序
|
||||
|
||||
```text
|
||||
S0 net/llm:SSE 读 + complete stream=True + 事件 foreach ✅
|
||||
S1 step stream=True(echo 增量;返回 map 不变) ✅
|
||||
S2 plan stream=True:round + 父 delta;trace 写回可选 ✅
|
||||
S3 view 订阅(EventBus + GET /api/events + POST /api/run) ✅
|
||||
```
|
||||
|
||||
### 开放点决议(S0)
|
||||
|
||||
1. **Eager 事件列表**(非惰性句柄):`complete stream=True` 返回 `List` of maps,可用今日 foreach。
|
||||
2. **默认不自动 print**:`echo=False`;需要边读边打时传 `echo=True` / `打印增量=真`。
|
||||
3. 中文:`## 运行` 用 `流式=` / `打印增量=`。
|
||||
|
||||
### 开放点决议(S2)
|
||||
|
||||
1. `plan` / `多步` 增加 `stream` / `echo` / `trace`(中文 `流式` / `打印增量` / `轨迹`)。
|
||||
2. 事件挂在返回 map 的 `events`;父 `complete` 只冒泡 `delta`/`error`(嵌套 `done` 不进列表)。
|
||||
3. `trace=True` → 写回槽 `trace`(与 TTY `echo` 可分立)。
|
||||
4. **体验(父先子后)**:非命中路径先 `decompose`(SSE + 可选 TTY `plan:decompose`),再 `await`(SSE 占位 + 可选 TTY `plan:await`),子 quiet。修订轮仍是观察后父决策。SSE 本身用 `tests/ext/llm-stream-live.mq.md`。
|
||||
|
||||
验收:
|
||||
|
||||
1. 未传 `stream` 的金样零 diff。
|
||||
2. `stream=True` 时用户在首包 token 到达前不应长时间无输出(允许短连接建立延迟)。
|
||||
3. 最终 `result` 与非流式路径一致(同 prompt fixture)。
|
||||
4. quiet 子任务仍不污染父 TTY。
|
||||
|
||||
---
|
||||
|
||||
## 6. 开放点
|
||||
|
||||
1. ~~Eager vs 惰性~~ → S0 选 eager;惰性句柄可后补。
|
||||
2. ~~delta 默认 print~~ → 默认关;`echo=True` 可选。
|
||||
3. ~~中文面~~ → `流式=` / `打印增量=`。
|
||||
4. ~~S2~~ → `plan stream=True`:`round` / 父 delta / `decision` / `done`;可选 `trace`。
|
||||
5. ~~**S3**~~ → `marqdo view`:进程内 EventBus;`GET /api/events`(SSE);`POST /api/run` 后台执行;Execution 区 EventSource 面板。CLI 默认不订阅。
|
||||
|
||||
S0 可与 [okf-near-match.md](okf-near-match.md) 并行,互不阻塞。
|
||||
@@ -0,0 +1,56 @@
|
||||
# 官方扩展:`ext/quantum` 实现路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Q0–Q6 已落地**(含公式自定义门;更大 n / 完整开放系统另文) |
|
||||
| 日期 | 2026-08-12 |
|
||||
| **锁定设计** | [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` / `量子`) |
|
||||
|
||||
本文只跟踪**实现阶段**。作者面、模拟语义、view 可视化、分期以设计文为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标回顾(一句)
|
||||
|
||||
**可运行的量子电路文档**:表声明门序列 → ABI 模拟概率/采样 → view 内嵌电路/概率 SVG;文档跑通即公式约定成立。
|
||||
|
||||
---
|
||||
|
||||
## 2. 落地阶段
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **Q0** | CATALOG + `plugins/quantum` ping + L1 `ensure_plugin` | **done** |
|
||||
| **Q1** | 态向量;I/X/H/CX;`simulate` / `probabilities`;贝尔态 gold | **done** |
|
||||
| **Q2** | Y/Z/S/T/R\* /CZ/SWAP;`run seed=`;中英 API | **done** |
|
||||
| **Q3** | `steps=` 电路表;`draw` 轨线 SVG;view `record_plot` 或值识别 | **done** |
|
||||
| **Q4** | 概率条 / 布洛赫;`matches_matrix`;examples + 用户文档 | **done** |
|
||||
| **Q5** | 教学噪声 + barrier/measure/append/state — [ext-quantum-q5.md](../design/ext-quantum-q5.md) | **done(最小)** |
|
||||
| **Q5.5** | `amplitude_damping` 轨迹 — [ext-quantum-q5.5.md](../design/ext-quantum-q5.5.md) | **done** |
|
||||
| **Q6** | 公式/`matrix=` 自定义门 + `apply` — [ext-quantum-custom-gate.md](../design/ext-quantum-custom-gate.md) | **done** |
|
||||
|
||||
验收金样:`tests/ext/quantum-bell-smoke.mq.md`、`quantum-draw-smoke.mq.md`、`quantum-gate-matrix-smoke.mq.md`、`quantum-gate-heatmap-smoke.mq.md`、`quantum-author-api-smoke.mq.md`、`quantum-noise-smoke.mq.md`、`quantum-amp-damp-smoke.mq.md`、`quantum-custom-gate-smoke.mq.md`、中文对称样例。
|
||||
|
||||
---
|
||||
|
||||
## 3. 已收敛的原开放点
|
||||
|
||||
| 原疑问 | 锁定结论(见设计文) |
|
||||
|--------|----------------------|
|
||||
| 并进 math? | **否**,独立 `ext/quantum` |
|
||||
| 电路表 | **要做**(Q3),与方法链等价 |
|
||||
| view 图 | 自绘 SVG;优先 `host_query("record_plot")`;不依赖 web |
|
||||
| 自由函数面 | **不**与对象面并行 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 与其它文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [design/ext-quantum.md](../design/ext-quantum.md) | **真理** |
|
||||
| [stdlib-math.md](../design/stdlib-math.md) | 公式/作图精神对照;实现分离 |
|
||||
| [ext-web.md](../design/ext-web.md) | 同属官方 ext + ABI + `ext add` 模板 |
|
||||
| [view.md](../design/view.md) | 结构卡 + Execution 内嵌 SVG |
|
||||
@@ -0,0 +1,53 @@
|
||||
# 官方扩展:`ext/web` 实现路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **W0–W3 骨架已落地;W4 待** |
|
||||
| 日期 | 2026-08-11 |
|
||||
| **锁定设计** | [design/ext-web.md](../design/ext-web.md) |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [ext-llm.md](../design/ext-llm.md) |
|
||||
| 安装 | `marqdo ext add web`(`web` / `网页`) |
|
||||
|
||||
本文只跟踪**实现阶段**。类模型、赋值绑定、后台、`.env`、异步边界、ABI 名等以设计文为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标回顾(一句)
|
||||
|
||||
**表格完成动态站**:页面表拼组件、组件表绑库与样式、样式表定外观;热路径进 ABI 插件;可选 S3 / Redis。人写目标见设计 §0.1 与 `examples/man-write-site/`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 落地阶段
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **W0** | CATALOG + L1 + `web_listen` Hello | **done** |
|
||||
| **W1** | env 端口;`page` 四栏;nav 表;static | **done** |
|
||||
| **W2** | SQLite `define`/`migrate`/`all` | **done** |
|
||||
| **W3** | 三列绑定;变量名即表名;`/admin` CRUD+日志+布局 | **done**(登录鉴权仍简) |
|
||||
| **W3.5** | 人写面首版:`web.assemble` + `` `表`.`字段` `` + `examples/man-write-site` | **done**(编排袋仍可再瘦) |
|
||||
| **W4** | Postgres;Redis / S3 驱动 | pending |
|
||||
|
||||
验收金样:`tests/ext/web-smoke.mq.md`、`ext_cli_add_web`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 已收敛的原开放点
|
||||
|
||||
| 原疑问 | 锁定结论(见设计文) |
|
||||
|--------|----------------------|
|
||||
| listen 阻塞 vs 后台任务 | `# main` 内 `listen` **同步阻塞**;插件内部异步 |
|
||||
| handler 形态 | **不主推**手写 REST;表 href + bind + 自动后台 |
|
||||
| `marqdo web` 子命令 | scaffold 经 `web.scaffold`;`marqdo web new` 可后续补 |
|
||||
| Windows + SQLite | 路径用 `DATABASE_URL` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 与其它文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [design/ext-web.md](../design/ext-web.md) | **真理** |
|
||||
| [user-site.md](../design/user-site.md) | 静态站互补 |
|
||||
| [ext-quantum.md](ext-quantum.md) | 同属官方 ext + ABI + `ext add` |
|
||||
@@ -62,7 +62,7 @@ index.mq.md (+ 导入的 .mq.md)
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入合并
|
||||
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入模块树(见 module-namespace)
|
||||
│ │ 作用域链、形参、未定义名诊断
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
|
||||
@@ -19,7 +19,7 @@
|
||||
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
|
||||
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
|
||||
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
|
||||
| **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 |
|
||||
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
|
||||
|
||||
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
|
||||
|
||||
|
||||
@@ -0,0 +1,167 @@
|
||||
# 对象继承语法(未来规划)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **I0–I3 已落地**(显式父构造约定;**不做**隐式 auto-super) |
|
||||
| 日期 | 2026-08-10 |
|
||||
| 相关 | [objects.md](../design/objects.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [keywords.md](../design/keywords.md) |
|
||||
| 提案语法 | `# 子类 = > 父类` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
今日 [`objects.md`](../design/objects.md) 明确非目标:**继承 / 接口 / 可见性**。
|
||||
实际扩展(如 `# agent` / `# llm`)靠「再写一个对象 + 组合句柄」,缺少:
|
||||
|
||||
- 复用父构造 / 父方法而不复制 `.mq.md`
|
||||
- 子类型在 `_type` 链上解析方法
|
||||
- 与 Markdown 标题体系一致的、可读的继承声明
|
||||
|
||||
需要一种**不引入 `class`/`extends` 关键字**、且与现有 `=`(绑定)与 `>`(调用)语义兼容的写法。
|
||||
|
||||
---
|
||||
|
||||
## 2. 锁定语法(提案)
|
||||
|
||||
```markdown
|
||||
# 子类 = > 父类
|
||||
```
|
||||
|
||||
| 片段 | 既有含义 | 组合后含义 |
|
||||
|------|----------|------------|
|
||||
| `# 子类` | 定义对象 / 类型 | 子类型名 |
|
||||
| `=` | 绑定 / 赋值 | 类型关系写在「类型定义槽」上 |
|
||||
| `> 父类` | 调用(此处为类型名) | **基类引用**(不是构造实例) |
|
||||
|
||||
可选带参基类(若基类本身是泛化构造,v1 可暂不支持):
|
||||
|
||||
```markdown
|
||||
# 特化智能体 = > 智能体
|
||||
```
|
||||
|
||||
中英对称:
|
||||
|
||||
```markdown
|
||||
# Child = > Parent
|
||||
# 子类 = > 父类
|
||||
```
|
||||
|
||||
### 2.1 为何不冲突
|
||||
|
||||
1. **今日** `# 名` 后接的是构造体正文,不是 `` `# 名 = …` `` 标题行。
|
||||
2. **语句绑定**是 `*…*` 或行内 `` `x` = ``,不是 ATX `#` 标题。
|
||||
3. **`> 父类` 在标题行**出现在 `=` 右侧:解析器可把「`#` 标题含 `=` 与 `>`」识别为**类型声明**,而非执行构造。
|
||||
4. 真正构造实例仍是正文或 `# main` 里的 `` `x` = > 子类 … ``。
|
||||
|
||||
反例(仍是今日语义,不变):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`a` = > 父类 *
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 运行时语义(草案)
|
||||
|
||||
### 3.1 方法解析
|
||||
|
||||
实例 map 仍有 `_type` = 构造时的类型名(子类名)。
|
||||
|
||||
查找 `` `obj`.方法 ``:
|
||||
|
||||
1. 在 `_type` 对应对象上找 `## 方法`
|
||||
2. 未找到 → 沿 **基类链** 查找
|
||||
3. 仍无 → 报错(带类型链)
|
||||
|
||||
构造:
|
||||
|
||||
1. 若子类构造体未显式处理,可先调基类构造(见开放点:是否自动 `super`)。
|
||||
2. 返回 map 的 `_type` = **最具体子类名**(不是父类名)。
|
||||
|
||||
### 3.2 子类正文
|
||||
|
||||
```markdown
|
||||
# 工蜂 = > 智能体
|
||||
|
||||
## 采蜜
|
||||
+ `花`
|
||||
|
||||
*`out` = > `self`.step task=`花` *
|
||||
**`out`**
|
||||
```
|
||||
|
||||
- 子类可定义新 `##`
|
||||
- 可覆盖同名 `##`(子类优先)
|
||||
- 站立提示 / 字段约定:文档层说明,v1 不引入可见性关键字
|
||||
|
||||
### 3.3 多继承
|
||||
|
||||
**v1 不支持。** 一个 `# 子 = > 父` 仅一条基类。混入用组合(句柄字段)而非多 `>`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 解析与 AST
|
||||
|
||||
标题形态需在 [markdown-mapping.md](../design/markdown-mapping.md) / parse 中新增一种 object decl:
|
||||
|
||||
| 字段 | 值 |
|
||||
|------|-----|
|
||||
| `name` | 子类 |
|
||||
| `base` | 父类(标识符) |
|
||||
| `body` | 与今日 object body 相同 |
|
||||
|
||||
歧义处理:
|
||||
|
||||
- `# Foo = 1` → **非法**(右侧必须是 `> 类型名`)
|
||||
- `# Foo = > bar.baz` → v1 **非法**(基类须为已定义对象名,不走任意调用表达式)
|
||||
- 基类尚未定义 → Pass1 收集后解析;循环继承报错
|
||||
|
||||
---
|
||||
|
||||
## 5. 与标准库 / 扩展
|
||||
|
||||
| 用途 | 例子 |
|
||||
|------|------|
|
||||
| 扩展官方智能体 | `# 客服 = > agent` / `# 客服 = > 智能体` |
|
||||
| 扩展 llm 句柄 | 一般不必要;优先组合 |
|
||||
| 用户域模型 | `# 订单服务 = > 服务基类` |
|
||||
|
||||
官方 `lib/*` 仍以自由函数为主;继承主要服务 `ext/` 与用户对象。
|
||||
|
||||
---
|
||||
|
||||
## 6. 推荐落地顺序
|
||||
|
||||
```text
|
||||
I0 语法 + AST + 金样(解析/循环继承错误) ✅
|
||||
I1 方法解析沿基类链;构造 _type=子类 ✅
|
||||
I2 覆盖方法;文档更新 objects.md ✅
|
||||
I3 显式父构造约定(**不做**隐式 auto-super) ✅
|
||||
```
|
||||
|
||||
验收:
|
||||
|
||||
1. 无继承文件行为不变。
|
||||
2. 子类实例能调父类 `##`;覆盖后只走子类。
|
||||
3. `` # A = > B `` / `` # B = > A `` 诊断清晰。
|
||||
4. Skill / 金样:`tests/structure/inherit-*.mq.md`(含显式 `` `self` = > Parent ``)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 开放点
|
||||
|
||||
1. ~~**隐式 super**~~ → **不做**:子类构造体不自动跑父构造。需要父初始化时正文写 `` `self` = > 父类 … `` 再改字段后 `**`self`**`;构造完成时 `_type` 仍为最具体子类名。
|
||||
2. 中英基类别名:`> agent` 与 `> 智能体` 是否同一对象(取决于模块导出)。
|
||||
3. 继承是否写入 OKF Module 页(catalog 展示 `extends`)——可随 O3/O4 增强。
|
||||
|
||||
---
|
||||
|
||||
## 8. 非目标
|
||||
|
||||
- 接口 / 抽象方法 / 可见性(`public`)
|
||||
- 多继承、mixin 关键字
|
||||
- 用继承替代 `plan` 工作簿接力
|
||||
- 把 `# 子 = > 父` 解析成「定义时立即构造父实例」
|
||||
@@ -0,0 +1,108 @@
|
||||
# OKF 相近任务命中
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **A 规范句 + B aliases + C 父裁决(soft_match)+ D 本地 n-gram `near` 已落地**;E dense embedding 仍非目标 |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 相关 | [okf.md](../design/okf.md) §7 · [ext-agent-plan.md](../design/ext-agent-plan.md) §4.2 · [ext-agent.md](../design/ext-agent.md) |
|
||||
| 触发观察 | `man-test`:相近 goal 生成两份独立 resource |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
v1 agent-kb **精确命中仍是默认快路径**:
|
||||
|
||||
1. `normalize_goal`:去首尾空白、合并连续空白(**不做**近义改写)。
|
||||
2. `sig` = 规范化字符串的稳定短哈希;`slug` = 可读路径名。
|
||||
3. `agent_kb_lookup`:精确 → aliases → canonicalize → **本地 n-gram `near`(默认开)**;仍 miss 且 `plan soft_match=True` 时父裁决 REUSE/NEW(候选为排序 near 列表)。
|
||||
|
||||
历史痛点(已由 A/B/C/D 缓解):
|
||||
|
||||
| goal(调用方输入) | 旧行为 |
|
||||
|--------------------|--------|
|
||||
| `你是一个智能体,帮我规划明天的行程` | 独立 slug,与下方不命中 |
|
||||
| `帮我规划明天的行程` | 另一份 resource |
|
||||
| `帮我规划明天行程` | 又一份(近句碎片) |
|
||||
|
||||
调用方直觉:「这不是同一件事吗?」——现可用 canonicalize、默认 `near_match`,或显式 `soft_match` 父裁决。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为何精确指纹仍优先
|
||||
|
||||
| 理由 | 说明 |
|
||||
|------|------|
|
||||
| 假阳性代价高 | 错复用旧工作簿比多建一个文件更糟 |
|
||||
| 可审计 | `sig` 可复算;`near` 留下 `match`/`score` |
|
||||
| 哲学 | 多轮 = 子文件接力 + OKF 索引,不是聊天式模糊检索 |
|
||||
|
||||
**结论:** 精确命中长期保留为**默认快路径**;`near` 是可关闭的第四趟(`near_match=False`)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 已落地层
|
||||
|
||||
### A. 规范化后再精确命中 — **已落地**
|
||||
|
||||
`agent_kb_canonicalize`:剥站立前缀、去尾标点;`match: canonical`。
|
||||
|
||||
### B. 别名 / 标签表 — **已落地**
|
||||
|
||||
Task FM `aliases:`;`match: alias`。
|
||||
|
||||
### C. 父智能体软裁决 — **已落地(默认关)**
|
||||
|
||||
`plan soft_match=True`:`agent_kb_near_match` 排序候选(含 `score`;空则退回 `list_tasks`)→ 父 `DECISION: REUSE` + `SLUG:` 或 `DECISION: NEW`。
|
||||
|
||||
### D. 本地字符 bigram + 余弦 — **已落地(默认开)**
|
||||
|
||||
| | |
|
||||
|--|--|
|
||||
| 做法 | 稀疏词法向量化(**不是** embedding 模型):canonicalize 后对 goal 与 Task `title\|description\|aliases` 建字符 bigram 词袋,算余弦 |
|
||||
| API | `agent_kb_near_match`;`agent_kb_lookup` 第四趟 |
|
||||
| 参数 | `near_match`/`近义命中` 默认 `True`;`near_threshold`/`近义阈值` 默认 `0.78` |
|
||||
| 痕迹 | `match: near` + `score`;`cache=soft-hit`;可写 alias |
|
||||
|
||||
术语:这是 **sparse lexical near-match**,勿宣传为向量库 / embedding 检索。
|
||||
|
||||
### E. Dense embedding(可选远期)
|
||||
|
||||
远程 / 本地 dense 向量与 ANN **仍非本仓默认目标**;仅当 D 在真实包体量下证据不足时再评估。
|
||||
|
||||
---
|
||||
|
||||
## 4. 演进顺序
|
||||
|
||||
```text
|
||||
精确 sig(永不删除)
|
||||
→ A 规范句 + B aliases(已落地)
|
||||
→ C soft_match 父裁决(已落地,默认关)
|
||||
→ D 本地 n-gram near(已落地,默认开)
|
||||
→ E dense embedding(仅有证据再开)
|
||||
```
|
||||
|
||||
验收原则:
|
||||
|
||||
1. `near_match=False` 时与无 near 行为一致;`force`/`optimize` 仍跳过 reuse。
|
||||
2. 软/近义命中留下 `cache=soft-hit` / `match` / 可选 `score`。
|
||||
3. 假阳性可被 `force=True` / 显式 `workbook=` / 调高 `near_threshold` 覆盖。
|
||||
4. 实现仍在 **agent 插件 + `ext/ai`**,不进核心 `src/host`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 调用方建议
|
||||
|
||||
- 固定规范 goal;站立语可由 canonicalize 剥掉。
|
||||
- 近句碎片依赖默认 `near_match`;字面差更大时开 `soft_match=True`。
|
||||
- 策展:合并重复 task,次要措辞写入 `aliases`(O4)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 与现有路线图的关系
|
||||
|
||||
| 条目 | 关系 |
|
||||
|------|------|
|
||||
| [okf.md](../design/okf.md) O2 / O5 | 精确 reuse + A/B/C/D;E dense 仍待 |
|
||||
| [okf.md](../design/okf.md) O4 | `kb query` / 策展可继续扩 aliases |
|
||||
| [ext-agent-plan.md](../design/ext-agent-plan.md) | 多轮仍只走子文件接力;软命中只影响「选哪个子文件」 |
|
||||
@@ -0,0 +1,303 @@
|
||||
# 表格语义打磨:列表 · 字典 · 嵌套 · 脚注取元(未来规划)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **T0–T5 已落地**(单元格表达式见 [table-cell-expressions.md](../design/table-cell-expressions.md)) |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 相关 | [markdown-mapping.md](../design/markdown-mapping.md) §9 · [table-cell-expressions.md](../design/table-cell-expressions.md) · [objects.md](../design/objects.md) · [stdlib.md](../design/stdlib.md)(`lib/table`) · [keywords.md](../design/keywords.md) |
|
||||
| 现状金样 | [tests/structure/collection.mq.md](../../tests/structure/collection.mq.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
### 1.1 今日表格 =「竖表 → 列表」
|
||||
|
||||
```markdown
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
```
|
||||
|
||||
语义(已落地):绑定为**列表**(列值);表头名供 `` [`果`](`篮子`) `` 遍历。
|
||||
单列表头是当前唯一一等集合外形;**没有**一等「横表 = 字典」。
|
||||
|
||||
### 1.2 缺字典外形与嵌套
|
||||
|
||||
用户期望:GFM 表的两种几何对应两种结构,并允许嵌套——这样「多行表格」才有稳定、可教的含义。
|
||||
|
||||
### 1.3 不能按下标 / 键直接取元
|
||||
|
||||
今日要从列表取第 *n* 项,往往只能遍历或走 `lib/table`(`row_at` 等),**语言级**缺少与 Markdown 同构的取元语法。字典亦然。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标
|
||||
|
||||
1. **竖表**继续表示列表(兼容现有金样)。
|
||||
2. **横表**(多列表头 + 数据行)表示字典及「字典 ↔ 列表」嵌套。
|
||||
3. 用 **Markdown 脚注外形** 做列表下标 / 字典键的取元(表达式级)。
|
||||
4. 不引入 `[]` 下标关键字风暴;少而精,与「标记即语法」一致。
|
||||
|
||||
非目标:
|
||||
|
||||
- 完整电子表格公式引擎
|
||||
- 用表声明对象字段 schema(仍见 objects 非目标;与数据集合分开)
|
||||
- 破坏现有单列竖表金样
|
||||
|
||||
---
|
||||
|
||||
## 3. 表格几何 → 值(锁定提案)
|
||||
|
||||
判定在 **绑定右侧的 GFM 表** 上做(`` `名` = `` 后接表)。
|
||||
|
||||
### 3.1 竖表 → 列表(现状,保留)
|
||||
|
||||
**形状:** 恰好 **1** 列。
|
||||
|
||||
```markdown
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
```
|
||||
|
||||
| 结果 | 说明 |
|
||||
|------|------|
|
||||
| 值 | `List`:`["苹果","梨","桃"]` |
|
||||
| 表头 | 元素逻辑名(foreach 绑定名);不进入列表元素 |
|
||||
|
||||
### 3.2 横表单数据行 → 字典
|
||||
|
||||
**形状:** ≥2 列,且 **恰好 1 行数据**(表头 + 分隔 + 一行)。
|
||||
|
||||
```markdown
|
||||
`分类` =
|
||||
|
||||
| 苹果 | 黄瓜 | 鼠标 |
|
||||
|------|------|------|
|
||||
| 水果 | 蔬菜 | 数码用品 |
|
||||
```
|
||||
|
||||
| 结果 | 说明 |
|
||||
|------|------|
|
||||
| 值 | `Map`:`苹果→水果`, `黄瓜→蔬菜`, `鼠标→数码用品` |
|
||||
| 键 | 表头单元格文本(规范化空白后) |
|
||||
| 值 | 唯一数据行对应列 |
|
||||
|
||||
### 3.3 横表多数据行 → 字典套列表(默认)
|
||||
|
||||
**形状:** ≥2 列,且 **≥2 行数据**。
|
||||
|
||||
```markdown
|
||||
`货架` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 红富士 | 青瓜 |
|
||||
| 嘎啦 | 黄瓜条 |
|
||||
```
|
||||
|
||||
**默认语义(锁定):列向聚合**
|
||||
|
||||
```text
|
||||
{
|
||||
"苹果": ["红富士", "嘎啦"],
|
||||
"黄瓜": ["青瓜", "黄瓜条"]
|
||||
}
|
||||
```
|
||||
|
||||
即:**键 = 表头,值 = 该列数据行组成的列表**。
|
||||
这与竖表「一列 = 一列表」在多列时自然推广,嵌套外形稳定。
|
||||
|
||||
**备选语义(不默认):行向记录列表**
|
||||
|
||||
```text
|
||||
[
|
||||
{"苹果":"红富士","黄瓜":"青瓜"},
|
||||
{"苹果":"嘎啦","黄瓜":"黄瓜条"}
|
||||
]
|
||||
```
|
||||
|
||||
更像 SQL / CSV。若未来需要,用显式标记区分(见 §3.5),**不得**与默认列向字典静默混用。
|
||||
|
||||
### 3.4 单列多行 vs 多列
|
||||
|
||||
| 列数 | 数据行 | 值类型 |
|
||||
|------|--------|--------|
|
||||
| 1 | ≥0 | `List` |
|
||||
| ≥2 | 1 | `Map`(标量值) |
|
||||
| ≥2 | ≥2 | `Map`(值均为 `List`) |
|
||||
| ≥2 | 0 | `Map`(键存在,值空列表或错误——开工时锁定为「空列表」) |
|
||||
|
||||
### 3.5 显式形态标记(行向记录)— **已落地**
|
||||
|
||||
首列表头为下列之一时,整表改为**行向**(不静默混用列向默认):
|
||||
|
||||
| 标记 | 说明 |
|
||||
|------|------|
|
||||
| `@` | ASCII 短标记 |
|
||||
| `行` | 中文 |
|
||||
| `row` | 英文 |
|
||||
|
||||
规则:
|
||||
|
||||
1. 标记列**不进入**记录字段(数据格可写行号给人看)。
|
||||
2. 其余列 → 每行一个 `Map`;整体为 `List`。
|
||||
3. 须至少有一列字段(仅 `| 行 |` → 诊断)。
|
||||
4. 数据行数任意(含 0 → 空列表;1 行仍是 `List` of one `Map`,不是列向 `Map`)。
|
||||
|
||||
```markdown
|
||||
`订单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
| 2 | 梨 | 3 |
|
||||
```
|
||||
|
||||
→ `[{品名: 苹果, 数量: 2}, {品名: 梨, 数量: 3}]`。取元:`` `订单`[^1][^品名] ``。
|
||||
|
||||
---
|
||||
|
||||
## 4. 脚注取元(提案)
|
||||
|
||||
### 4.1 为何用脚注外形
|
||||
|
||||
- Markdown 已有 `[^…]` 引用形态,读者不陌生。
|
||||
- 避免 `篮子[0]` 与链接 / 图片语法纠缠。
|
||||
- 与「标识符反引号」组合清晰:`` `篮子`[^1] ``。
|
||||
|
||||
### 4.2 列表:按下标
|
||||
|
||||
```markdown
|
||||
*`第一` = `篮子`[^1] *
|
||||
> print text=`第一`
|
||||
```
|
||||
|
||||
| 约定 | 选择(提案) |
|
||||
|------|----------------|
|
||||
| 下标基准 | **1-based**(与 Markdown / 人类表格行语感一致;脚注 `[^1]` 即第一项) |
|
||||
| `[^0]` | 报错(保留 0 不用)或日后表示「最后一项」—— v1 **报错** |
|
||||
| 越界 | 清晰诊断 `path:line:col` |
|
||||
|
||||
### 4.3 字典:按键
|
||||
|
||||
键为脚注标签文本(推荐与表头一致;**允许纯数字键**,如基矢标签 `00`)。基名可写 `` `概率`[^00] `` 或 `` 概率[^00] ``(紧跟 `[^` 时可省略反引号):
|
||||
|
||||
```markdown
|
||||
*`种` = `分类`[^苹果] *
|
||||
*`p00` = `概率`[^00] *
|
||||
> print text=`种`
|
||||
```
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| `[^苹果]` | 键文本 `苹果` |
|
||||
| `[^00]` / `[^1]` | 键文本 `00` / `1`(**不是**「第 n 个 map 条目」) |
|
||||
| 含空格的键 | 允许 `[^数码用品]`;极端键用引号策略开工前定 |
|
||||
| 缺失键 | 报错或 `None`——建议 v1 **报错**(少静默) |
|
||||
|
||||
### 4.4 嵌套取元
|
||||
|
||||
列向字典套列表:
|
||||
|
||||
```markdown
|
||||
*`货架` = …多行横表… *
|
||||
*`第一种苹果` = `货架`[^苹果][^1] *
|
||||
```
|
||||
|
||||
从左到右:先键、再下标。
|
||||
类型不对(对 List 用非数字键名脚注)→ 诊断。Map 上的纯数字标签按**键名**解析。
|
||||
|
||||
### 4.5 与 GFM「定义脚注」正文
|
||||
|
||||
标准 Markdown 文末 `[^1]: 说明` 是**注释/文献**,不是取元。
|
||||
|
||||
规则:
|
||||
|
||||
- **表达式位置**的 `` `名`[^…] `` → 取元。
|
||||
- **文末脚注定义块** → 仍作注释(或不支持,避免混用)。
|
||||
- 不要求为每个 `[^1]` 写定义;Marqdo 取元**不依赖**定义块。
|
||||
|
||||
### 4.6 与 `lib/table` 关系
|
||||
|
||||
| 层 | 职责 |
|
||||
|----|------|
|
||||
| 语言脚注取元 | 一等、短、金样覆盖 |
|
||||
| `lib/table` | 行列切片、整表变换;可逐步把 `row_at` 文档改为「等价于脚注」 |
|
||||
|
||||
---
|
||||
|
||||
## 5. foreach 与字典
|
||||
|
||||
今日:`` [果](篮子) `` / `` [`果`](`篮子`) `` 遍历列表(裸名与反引号均可)。
|
||||
|
||||
扩展草案:
|
||||
|
||||
| 集合 | 遍历 |
|
||||
|------|------|
|
||||
| List | 不变,项为元素 |
|
||||
| Map | `` [`键`](`映射`) `` 遍历键;或 `` [`对`](`映射`) `` 若引入对类型—— v1 建议 **遍历键**,值用 `` `映射`[^…] `` / 辅助 |
|
||||
|
||||
具体键值对遍历语法开工前写一小段进 mapping;避免与链接外形 `` [`x`](`y`) `` 冲突(今日已是 foreach)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 推荐落地顺序
|
||||
|
||||
```text
|
||||
T0 横表单行 → Map;金样;竖表回归 ✅
|
||||
T1 横表多行 → Map of List(列向);嵌套金样 ✅
|
||||
T2 脚注取元:List [^n]、Map [^键]、链式 ✅
|
||||
T3 文档:markdown-mapping §9;Skill / examples;table 库 ✅
|
||||
T4 行向记录表:首列 `@` / `行` / `row` ✅
|
||||
T5 数据单元格 = 表达式(同调用实参值语法) ✅
|
||||
```
|
||||
|
||||
验收:
|
||||
|
||||
1. `tests/structure/collection.mq.md` 行为不变。
|
||||
2. 新金样:`collection-map.mq.md`、`collection-map-list.mq.md`、`footnote-index.mq.md`。
|
||||
3. 错误下标 / 缺键带 `line:col`。
|
||||
4. 双后端(tree / bytecode)一致。
|
||||
5. **T5:** 单元格 `` `var` `` / 算术;URL 与 `gpt-4o-mini` 仍为文本;设计见 [table-cell-expressions.md](../design/table-cell-expressions.md)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 教学对照(写入 Skill 的素材)
|
||||
|
||||
| 几何 | 含义 | 取元 |
|
||||
|------|------|------|
|
||||
| 单列竖表 | 列表 | `` `a`[^1] `` |
|
||||
| 多列 + 一行 | 字典 | `` `m`[^键] `` |
|
||||
| 多列 + 多行 | 字典 → 列表 | `` `m`[^键][^1] `` |
|
||||
| 首列 `@`/`行`/`row` | 记录列表 | `` `r`[^1][^字段] `` |
|
||||
|
||||
竖表表头是「元素名」;横表表头是「键名」——几何决定角色,减少「这张表到底是啥」的歧义。
|
||||
|
||||
---
|
||||
|
||||
## 8. 开放点
|
||||
|
||||
1. 表头重复列名:报错还是后缀 `_2`?建议 **报错**。
|
||||
2. 数字表头:字典键为文本 `"1"` 还是整数?建议 **文本**(与单元格一致)。
|
||||
3. 脚注 1-based 与宿主语言习惯(0-based)的文档警示。
|
||||
4. 字节码:`Index` / `KeyGet` 操作码是否与 T2 同批。
|
||||
|
||||
---
|
||||
|
||||
## 9. 与其它规划的关系
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [object-inheritance.md](object-inheritance.md) | 正交;表不表示类字段 schema |
|
||||
| [agent-streaming.md](agent-streaming.md) | 正交;事件列表可用竖表金样演示 foreach |
|
||||
| [okf-near-match.md](okf-near-match.md) | 正交 |
|
||||
@@ -0,0 +1,10 @@
|
||||
# quantum-bell
|
||||
|
||||
Bell |Φ⁺⟩ via `ext/quantum` circuit table + draw.
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_quantum
|
||||
marqdo run examples/quantum-bell/index.mq.md
|
||||
```
|
||||
|
||||
Writes `bell.svg` next to the program (sandbox cwd).
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: Bell state
|
||||
description: H then CX; probabilities ≈ 1/2; circuit SVG.
|
||||
> ext/quantum/quantum.mq.md
|
||||
> lib/math.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
# Bell |Φ+⟩
|
||||
|
||||
H on qubit 0, then CNOT(0→1). Ideal measurement: |00⟩ and |11⟩ each with probability 1/2.
|
||||
|
||||
# main
|
||||
|
||||
`steps` =
|
||||
|
||||
| step | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
|
||||
*`p` = > `qc`.probabilities *
|
||||
*`_` = > `qc`.draw path=bell.svg *
|
||||
*`_` = > `qc`.draw kind=probs path=bell-probs.svg *
|
||||
|
||||
> print text=`p`
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: GHZ state
|
||||
description: 3-qubit GHZ; |000⟩/|111⟩ ≈ 1/2; probs + H matrix heatmap.
|
||||
> ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# GHZ
|
||||
|
||||
H on qubit 0, CX(0→1), CX(0→2). Ideal: |000⟩ and |111⟩ each with probability 1/2.
|
||||
|
||||
# main
|
||||
|
||||
`steps` =
|
||||
|
||||
| step | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
| 3 | CX | 0,2 |
|
||||
|
||||
*`qc` = > quantum.circuit qubits=3 steps=`steps` *
|
||||
*`p` = > `qc`.probabilities *
|
||||
*`_` = > `qc`.draw path=ghz.svg *
|
||||
*`_` = > `qc`.draw kind=probs path=ghz-probs.svg *
|
||||
*`H` = > quantum.gate name=H *
|
||||
*`_` = > `H`.draw kind=matrix path=ghz-h-matrix.svg *
|
||||
|
||||
> print text=`p`
|
||||
@@ -0,0 +1,10 @@
|
||||
# examples/web-site-zh
|
||||
|
||||
中文作者面示例:只导入 `ext/web/网页.mq.md`(不用英文 `web.mq.md`)。
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_web
|
||||
cargo run -- examples/web-site-zh/index.mq.md
|
||||
```
|
||||
|
||||
打开 http://127.0.0.1:18082/ — `/about`、`/new`、`/admin`、`/static/site.css`。
|
||||
@@ -0,0 +1,9 @@
|
||||
## foot
|
||||
|
||||
`foot` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Marqdo | https://github.com | |
|
||||
|
||||
**`foot`**
|
||||
@@ -0,0 +1,12 @@
|
||||
## nav
|
||||
|
||||
`nav` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 首页 | / | |
|
||||
| 关于 | /about | |
|
||||
| 写文章 | /new | |
|
||||
| 后台 | /admin | |
|
||||
|
||||
**`nav`**
|
||||
@@ -0,0 +1,10 @@
|
||||
## side
|
||||
|
||||
`side` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 笔记 | / | |
|
||||
| 文档 | https://github.com | |
|
||||
|
||||
**`side`**
|
||||
@@ -0,0 +1,22 @@
|
||||
## schema
|
||||
|
||||
`fields` =
|
||||
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | integer | false |
|
||||
| title | text | false |
|
||||
| body | text | true |
|
||||
|
||||
**`fields`**
|
||||
|
||||
## seed
|
||||
|
||||
`rows` =
|
||||
|
||||
| id | title | body |
|
||||
|----|-------|------|
|
||||
| 1 | 你好 Marqdo | 第一篇来自 GFM 表格。 |
|
||||
| 2 | 代码即文档 | 页面表就是程序。 |
|
||||
|
||||
**`rows`**
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: db/index
|
||||
description: 打开 sqlite、建表、幂等种子。
|
||||
> ext/web/网页.mq.md
|
||||
> articles.mq.md as articles
|
||||
---
|
||||
|
||||
## open
|
||||
|
||||
*`store` = > 网页.数据库 地址="sqlite:data/site-zh.db" *
|
||||
*`fields` = > articles.schema *
|
||||
> `store`.初始化 名=articles 字段=`fields`
|
||||
*`rows` = > `store`.查询 表=articles 上限=1 *
|
||||
1. `rows`
|
||||
**`store`**
|
||||
2. *
|
||||
*`seed` = > articles.seed *
|
||||
> `store`.插入 表=articles 行=`seed`
|
||||
**`store`**
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: 中文站点示例
|
||||
description: Home + /about + /new(表单嵌入)+ 后台;只用 ext/web/网页.mq.md。
|
||||
> ext/web/网页.mq.md
|
||||
> styles/shell.mq.md
|
||||
> components/nav.mq.md
|
||||
> components/side.mq.md
|
||||
> components/foot.mq.md
|
||||
> db/articles.mq.md
|
||||
> db/index.mq.md as db
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`home` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`nav` | shell.`topnav` |
|
||||
| side.`side` | shell.`side_panel` |
|
||||
| foot.`foot` | |
|
||||
|
||||
`index` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| `title` | articles.`articles`.title | shell.`card_title` |
|
||||
| `body` | articles.`articles`.body | shell.`card_body` |
|
||||
|
||||
`article_fields` =
|
||||
|
||||
| 字段 | 标签 | 类型 | 必填 | 默认 |
|
||||
|------|------|------|------|------|
|
||||
| title | 标题 | text | true | |
|
||||
| body | 正文 | textarea | false | |
|
||||
|
||||
`article_rules` =
|
||||
|
||||
| 字段 | 规则 | 消息 |
|
||||
|------|------|------|
|
||||
| title | required | 标题不能为空 |
|
||||
| title | max:120 | 标题太长 |
|
||||
| body | max:8000 | 正文太长 |
|
||||
|
||||
*`store` = > db.open *
|
||||
*`page` = > 网页.页面 标题="Marqdo 中文站" 引言="<h1>中文站</h1><p>表格 + 类方法。</p>" *
|
||||
*`page` = > `page`.组件装配 组件=`home` *
|
||||
*`page` = > `page`.主体装配 主体=`index` *
|
||||
|
||||
*`about` = > 网页.页面 标题="关于" 引言="<h1>关于</h1><p>导入网页.mq.md 即用中文 API。</p>" *
|
||||
*`about` = > `about`.组件装配 组件=`home` *
|
||||
|
||||
*`article_form` = > 网页.表单 表=articles 动作=插入 *
|
||||
*`article_form` = > `article_form`.字段 字段=`article_fields` *
|
||||
*`article_form` = > `article_form`.规则 规则=`article_rules` *
|
||||
|
||||
*`new` = > 网页.页面 标题="写文章" 引言="<h1>写文章</h1><p>表单嵌在主区。</p>" *
|
||||
*`new` = > `new`.组件装配 组件=`home` *
|
||||
*`new` = > `new`.表单装配 id=article 表单=`article_form` *
|
||||
|
||||
*`app` = > 网页.应用 页面=`page` 数据库=`store` 后台=True 主机=127.0.0.1 端口=18082 *
|
||||
*`app` = > `app`.路由 路径=/about 页面=`about` *
|
||||
*`app` = > `app`.路由 路径=/new 页面=`new` *
|
||||
*`app` = > `app`.静态 目录=public 挂载=/static *
|
||||
> `app`.监听
|
||||
@@ -0,0 +1,5 @@
|
||||
/* 可选站点样式 — /static/site.css */
|
||||
body.site-hint::before {
|
||||
content: "static ok";
|
||||
display: none;
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
## topnav
|
||||
|
||||
`topnav` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #ffffff |
|
||||
| border-bottom | 1px solid #e7e5e4 |
|
||||
|
||||
**`topnav`**
|
||||
|
||||
## side_panel
|
||||
|
||||
`side_panel` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #f5f5f4 |
|
||||
|
||||
**`side_panel`**
|
||||
|
||||
## card_title
|
||||
|
||||
`card_title` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| font-size | 1.15rem |
|
||||
| margin | 0 0 0.35rem |
|
||||
|
||||
**`card_title`**
|
||||
|
||||
## card_body
|
||||
|
||||
`card_body` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| color | #57534e |
|
||||
| margin | 0 |
|
||||
|
||||
**`card_body`**
|
||||
@@ -0,0 +1,10 @@
|
||||
# examples/web-site
|
||||
|
||||
Canonical English sample for `ext/web` (design §4).
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_web
|
||||
cargo run -- examples/web-site/index.mq.md
|
||||
```
|
||||
|
||||
Then open http://127.0.0.1:18081/ — `/about`, `/new` (form in page slot), `/admin`, `/static/site.css`.
|
||||
@@ -0,0 +1,9 @@
|
||||
## foot
|
||||
|
||||
`foot` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Marqdo | https://github.com | |
|
||||
|
||||
**`foot`**
|
||||
@@ -0,0 +1,14 @@
|
||||
## nav
|
||||
|
||||
Static top links for the shell.
|
||||
|
||||
`nav` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Home | / | |
|
||||
| About | /about | |
|
||||
| New | /new | |
|
||||
| Admin | /admin | |
|
||||
|
||||
**`nav`**
|
||||
@@ -0,0 +1,10 @@
|
||||
## side
|
||||
|
||||
`side` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Notes | / | |
|
||||
| Docs | https://github.com | |
|
||||
|
||||
**`side`**
|
||||
@@ -0,0 +1,22 @@
|
||||
## schema
|
||||
|
||||
`fields` =
|
||||
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | integer | false |
|
||||
| title | text | false |
|
||||
| body | text | true |
|
||||
|
||||
**`fields`**
|
||||
|
||||
## seed
|
||||
|
||||
`rows` =
|
||||
|
||||
| id | title | body |
|
||||
|----|-------|------|
|
||||
| 1 | Hello Marqdo | First article from a GFM table. |
|
||||
| 2 | Code as docs | The page table is the program. |
|
||||
|
||||
**`rows`**
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: db/index
|
||||
description: Open sqlite, init articles, seed once.
|
||||
> ext/web/web.mq.md
|
||||
> articles.mq.md as articles
|
||||
> lib/fs.mq.md
|
||||
---
|
||||
|
||||
## open
|
||||
|
||||
*`store` = > web.db url="sqlite:data/site.db" *
|
||||
*`fields` = > articles.schema *
|
||||
> `store`.init name=articles fields=`fields`
|
||||
*`rows` = > `store`.select table=articles limit=1 *
|
||||
1. `rows`
|
||||
**`store`**
|
||||
2. *
|
||||
*`seed` = > articles.seed *
|
||||
> `store`.insert table=articles rows=`seed`
|
||||
**`store`**
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: web-site
|
||||
description: Home + /about + /new (form in page slot) + admin.
|
||||
> ext/web/web.mq.md
|
||||
> styles/shell.mq.md
|
||||
> components/nav.mq.md
|
||||
> components/side.mq.md
|
||||
> components/foot.mq.md
|
||||
> db/articles.mq.md
|
||||
> db/index.mq.md as db
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`home` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`nav` | shell.`topnav` |
|
||||
| side.`side` | shell.`side_panel` |
|
||||
| foot.`foot` | |
|
||||
|
||||
Main content is not a reusable component, so it is authored here.
|
||||
|
||||
`index` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| `title` | articles.`articles`.title | shell.`card_title` |
|
||||
| `body` | articles.`articles`.body | shell.`card_body` |
|
||||
|
||||
Article create form (design §5.5): field table + rules table.
|
||||
|
||||
`article_fields` =
|
||||
|
||||
| 字段 | 标签 | 类型 | 必填 | 默认 |
|
||||
|------|------|------|------|------|
|
||||
| title | Title | text | true | |
|
||||
| body | Body | textarea | false | |
|
||||
|
||||
`article_rules` =
|
||||
|
||||
| 字段 | 规则 | 消息 |
|
||||
|------|------|------|
|
||||
| title | required | Title is required |
|
||||
| title | max:120 | Title is too long |
|
||||
| body | max:8000 | Body is too long |
|
||||
|
||||
*`store` = > db.open *
|
||||
*`page` = > web.page title="Marqdo Web Site" intro="<h1>Web Site</h1><p>Tables + class methods.</p>" *
|
||||
*`page` = > `page`.compose_components components=`home` *
|
||||
*`page` = > `page`.compose_main main=`index` *
|
||||
|
||||
About page: same shell, different intro (no main bind).
|
||||
|
||||
*`about` = > web.page title="About" intro="<h1>About</h1><p>Marqdo web = tables + class methods.</p>" *
|
||||
*`about` = > `about`.compose_components components=`home` *
|
||||
|
||||
*`article_form` = > web.form table=articles action=insert *
|
||||
*`article_form` = > `article_form`.fields fields=`article_fields` *
|
||||
*`article_form` = > `article_form`.rules rules=`article_rules` *
|
||||
|
||||
New article: form embedded in the page main slot (design §5.5.4).
|
||||
|
||||
*`new` = > web.page title="New article" intro="<h1>New article</h1><p>Form lives in the main slot.</p>" *
|
||||
*`new` = > `new`.compose_components components=`home` *
|
||||
*`new` = > `new`.compose_form id=article form=`article_form` *
|
||||
|
||||
*`app` = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
|
||||
*`app` = > `app`.route path=/about page=`about` *
|
||||
*`app` = > `app`.route path=/new page=`new` *
|
||||
*`app` = > `app`.static dir=public mount=/static *
|
||||
> `app`.listen
|
||||
@@ -0,0 +1,5 @@
|
||||
/* Optional site stylesheet — served at /static/site.css */
|
||||
body.site-hint::before {
|
||||
content: "static ok";
|
||||
display: none;
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
## topnav
|
||||
|
||||
`topnav` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #ffffff |
|
||||
| border-bottom | 1px solid #e7e5e4 |
|
||||
|
||||
**`topnav`**
|
||||
|
||||
## side_panel
|
||||
|
||||
`side_panel` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #f5f5f4 |
|
||||
|
||||
**`side_panel`**
|
||||
|
||||
## card_title
|
||||
|
||||
`card_title` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| font-size | 1.15rem |
|
||||
| margin | 0 0 0.35rem |
|
||||
|
||||
**`card_title`**
|
||||
|
||||
## card_body
|
||||
|
||||
`card_body` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| color | #57534e |
|
||||
| margin | 0 |
|
||||
|
||||
**`card_body`**
|
||||
+1821
-73
File diff suppressed because it is too large.
Load diff
+90
-94
@@ -4,127 +4,123 @@ description: OpenAI-compatible LLM object (English). Import ext/ai/llm.mq.md.
|
||||
> lib/sys.mq.md
|
||||
> lib/net.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/table.mq.md
|
||||
---
|
||||
|
||||
## load_env
|
||||
+ `path`=None
|
||||
|
||||
Load `.env` from cwd (optional named arg `path=`). Does not override existing variables.
|
||||
|
||||
**> load_dotenv**
|
||||
**> sys.load_dotenv path=`path`**
|
||||
|
||||
## stream_result
|
||||
+ `events`
|
||||
|
||||
Reduce a `complete stream=True` event list to the final `done.result` text (or `error.message`). Unknown event types abort.
|
||||
|
||||
*answer = ""*
|
||||
|
||||
- [ev](events)
|
||||
*t = ev[^type]*
|
||||
1. `t` == "done"
|
||||
*answer = ev[^result]*
|
||||
2. `t` == "error"
|
||||
*answer = ev[^message]*
|
||||
3. `t` == "delta"
|
||||
4. *
|
||||
> print text=ext/ai/llm: unexpected SSE event type
|
||||
> print text=`t`
|
||||
> sys.exit code=1
|
||||
|
||||
**answer**
|
||||
|
||||
# llm
|
||||
|
||||
Construct an LLM handle from `OPENAI_*` / `MARQDO_LLM_*` (default base OpenAI v1, model `gpt-4o-mini`).
|
||||
Construct an LLM handle from `OPENAI_*` / `MARQDO_LLM_*`.
|
||||
|
||||
*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} *
|
||||
*api_key = > sys.env_get name=OPENAI_API_KEY*
|
||||
1. not `api_key`
|
||||
*api_key = > sys.env_get name=MARQDO_LLM_API_KEY*
|
||||
|
||||
*`api_key` = > env_get name=OPENAI_API_KEY *
|
||||
1. `api_key`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`api_key` = > env_get name=MARQDO_LLM_API_KEY *
|
||||
3. `api_key`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
1. not `api_key`
|
||||
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY
|
||||
> exit code=1
|
||||
> sys.exit code=1
|
||||
|
||||
*`base_url` = > env_get name=OPENAI_BASE_URL *
|
||||
1. `base_url`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`base_url` = > env_get name=MARQDO_LLM_BASE_URL *
|
||||
3. `base_url`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`base_url` = > get value=`d` key=base *
|
||||
*base_url = > sys.env_get name=OPENAI_BASE_URL*
|
||||
1. not `base_url`
|
||||
*base_url = > sys.env_get name=MARQDO_LLM_BASE_URL*
|
||||
1. not `base_url`
|
||||
*base_url = "https://api.openai.com/v1"*
|
||||
|
||||
*`model` = > env_get name=OPENAI_MODEL *
|
||||
1. `model`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`model` = > env_get name=MARQDO_LLM_MODEL *
|
||||
3. `model`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`model` = > get value=`d` key=model *
|
||||
*model = > sys.env_get name=OPENAI_MODEL*
|
||||
1. not `model`
|
||||
*model = > sys.env_get name=MARQDO_LLM_MODEL*
|
||||
1. not `model`
|
||||
*model = "gpt-4o-mini"*
|
||||
|
||||
*`q_key` = > quote text=`api_key` *
|
||||
*`q_base` = > quote text=`base_url` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`suffix` = > get value=`d` key=suffix *
|
||||
*`bearer` = > get value=`d` key=bearer *
|
||||
*`p1` = > get value=`d` key=p1 *
|
||||
*`p2` = > get value=`d` key=p2 *
|
||||
*`p3` = > get value=`d` key=p3 *
|
||||
*`h1` = > get value=`d` key=h1 *
|
||||
*`h2` = > get value=`d` key=h2 *
|
||||
*`q_suf` = > quote text=`suffix` *
|
||||
*`q_br` = > quote text=`bearer` *
|
||||
*`q_p1` = > quote text=`p1` *
|
||||
*`q_p2` = > quote text=`p2` *
|
||||
*`q_p3` = > quote text=`p3` *
|
||||
*`q_h1` = > quote text=`h1` *
|
||||
*`q_h2` = > quote text=`h2` *
|
||||
*`a1` = > get value=`d` key=a1 *
|
||||
*`a2` = > get value=`d` key=a2 *
|
||||
*`a3` = > get value=`d` key=a3 *
|
||||
*`a4` = > get value=`d` key=a4 *
|
||||
*`a5` = > get value=`d` key=a5 *
|
||||
*`a6` = > get value=`d` key=a6 *
|
||||
*`a7` = > get value=`d` key=a7 *
|
||||
*`a8` = > get value=`d` key=a8 *
|
||||
*`a9` = > get value=`d` key=a9 *
|
||||
*`a10` = > get value=`d` key=a10 *
|
||||
*`a11` = > get value=`d` key=a11 *
|
||||
*`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` *
|
||||
**> parse text=`raw`**
|
||||
`h` =
|
||||
|
||||
| api_key | base_url | model | suffix | bearer |
|
||||
|---------|----------|-------|--------|--------|
|
||||
| `api_key` | `base_url` | `model` | /chat/completions | "Bearer " |
|
||||
|
||||
**h**
|
||||
|
||||
## complete
|
||||
+ `prompt`
|
||||
+ `stream`=False
|
||||
+ `echo`=False
|
||||
|
||||
Chat completion using `self` / `自` handle fields.
|
||||
Chat completion using `self` handle fields.
|
||||
|
||||
*`api_key` = > get value=`self` key=api_key *
|
||||
*`base_url` = > get value=`self` key=base_url *
|
||||
*`model` = > get value=`self` key=model *
|
||||
*`suffix` = > get value=`self` key=suffix *
|
||||
*`bearer` = > get value=`self` key=bearer *
|
||||
*`p1` = > get value=`self` key=p1 *
|
||||
*`p2` = > get value=`self` key=p2 *
|
||||
*`p3` = > get value=`self` key=p3 *
|
||||
*`h1` = > get value=`self` key=h1 *
|
||||
*`h2` = > get value=`self` key=h2 *
|
||||
*`url` = `base_url` + `suffix` *
|
||||
*`auth` = `bearer` + `api_key` *
|
||||
*`q_auth` = > quote text=`auth` *
|
||||
*`hdr_raw` = `h1` + `q_auth` + `h2` *
|
||||
*`headers` = > parse text=`hdr_raw` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`q_prompt` = > quote text=`prompt` *
|
||||
*`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` *
|
||||
*`resp` = > http_post url=`url` body=`body` headers=`headers` *
|
||||
*`status` = > get value=`resp` key=status *
|
||||
*`raw` = > get value=`resp` key=body *
|
||||
Wire body is `{model, messages:[{role,content}], stream?}`. Messages are an `@` row table; headers and optional `stream` use `table.put`. `json` is only for stringify/parse.
|
||||
|
||||
1. `status` == 200
|
||||
*`data` = > parse text=`raw` *
|
||||
*`choices` = > get value=`data` key=choices *
|
||||
*`first` = > at value=`choices` index=0 *
|
||||
*`message` = > get value=`first` key=message *
|
||||
*`content` = > get value=`message` key=content *
|
||||
**`content`**
|
||||
*url = self[^base_url] + self[^suffix]*
|
||||
*auth = self[^bearer] + self[^api_key]*
|
||||
*headers = > table.put in=None at=Authorization value=`auth`*
|
||||
|
||||
`messages` =
|
||||
|
||||
| @ | role | content |
|
||||
|---|------|---------|
|
||||
| 1 | user | `prompt` |
|
||||
|
||||
`req` =
|
||||
|
||||
| model | messages |
|
||||
|-------|----------|
|
||||
| self[^model] | `messages` |
|
||||
|
||||
1. `stream`
|
||||
*req = > table.put in=`req` at=stream value=True*
|
||||
*body = > json.stringify value=`req`*
|
||||
*resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`*
|
||||
1. resp[^status] == 200
|
||||
**resp[^events]**
|
||||
2. *
|
||||
> print text=ext/ai/llm: HTTP error (stream)
|
||||
> print text=resp[^status]
|
||||
> sys.exit code=1
|
||||
2. *
|
||||
> print text=ext/ai/llm: HTTP error
|
||||
> print text=`status`
|
||||
> print text=`raw`
|
||||
> exit code=1
|
||||
*body = > json.stringify value=`req`*
|
||||
*resp = > net.http_post url=`url` body=`body` headers=`headers`*
|
||||
1. resp[^status] == 200
|
||||
*data = > json.parse text=resp[^body]*
|
||||
**data[^choices][^1][^message][^content]**
|
||||
2. *
|
||||
> print text=ext/ai/llm: HTTP error
|
||||
> print text=resp[^status]
|
||||
> print text=resp[^body]
|
||||
> sys.exit code=1
|
||||
|
||||
---
|
||||
|
||||
## chat
|
||||
+ `prompt`
|
||||
+ `stream`=False
|
||||
+ `echo`=False
|
||||
|
||||
Alias for `complete`.
|
||||
|
||||
**> `self`.complete prompt=`prompt`**
|
||||
**> `self`.complete prompt=`prompt` stream=`stream` echo=`echo`**
|
||||
+92
-96
@@ -4,127 +4,123 @@ description: OpenAI 兼容大模型对象(中文)。导入 ext/ai/大模型.
|
||||
> lib/系统.mq.md
|
||||
> lib/网络.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/表.mq.md
|
||||
---
|
||||
|
||||
## 加载环境
|
||||
+ `路径`=None
|
||||
|
||||
从工作目录加载 `.env`(可选具名实参 `path=`)。不覆盖已有变量。
|
||||
从工作目录加载 `.env`(可选命名实参 `路径=`)。不覆盖已有变量。
|
||||
|
||||
**> load_dotenv**
|
||||
**> 系统.加载环境 路径=`路径`**
|
||||
|
||||
## 流式结果
|
||||
+ `事件`
|
||||
|
||||
把 `运行 流式=真` 的事件列表收成最终 `done.result`(或 `error.message`)。未知事件类型直接失败。
|
||||
|
||||
*answer = ""*
|
||||
|
||||
- [ev](事件)
|
||||
*t = ev[^type]*
|
||||
1. `t` == "done"
|
||||
*answer = ev[^result]*
|
||||
2. `t` == "error"
|
||||
*answer = ev[^message]*
|
||||
3. `t` == "delta"
|
||||
4. *
|
||||
> 打印 内容=ext/ai/大模型: 未预期的 SSE 事件类型
|
||||
> 打印 内容=`t`
|
||||
> 系统.退出 码=1
|
||||
|
||||
**answer**
|
||||
|
||||
# 大模型
|
||||
|
||||
从 `OPENAI_*` / `MARQDO_LLM_*` 构造句柄(默认 OpenAI v1 + `gpt-4o-mini`)。
|
||||
从 `OPENAI_*` / `MARQDO_LLM_*` 构造句柄。
|
||||
|
||||
*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} *
|
||||
*api_key = > 系统.取环境 名=OPENAI_API_KEY*
|
||||
1. 非 `api_key`
|
||||
*api_key = > 系统.取环境 名=MARQDO_LLM_API_KEY*
|
||||
|
||||
*`api_key` = > 取环境 名=OPENAI_API_KEY *
|
||||
1. `api_key`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`api_key` = > 取环境 名=MARQDO_LLM_API_KEY *
|
||||
3. `api_key`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
1. 非 `api_key`
|
||||
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
|
||||
> 退出 码=1
|
||||
> 系统.退出 码=1
|
||||
|
||||
*`base_url` = > 取环境 名=OPENAI_BASE_URL *
|
||||
1. `base_url`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`base_url` = > 取环境 名=MARQDO_LLM_BASE_URL *
|
||||
3. `base_url`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`base_url` = > get value=`d` key=base *
|
||||
*base_url = > 系统.取环境 名=OPENAI_BASE_URL*
|
||||
1. 非 `base_url`
|
||||
*base_url = > 系统.取环境 名=MARQDO_LLM_BASE_URL*
|
||||
1. 非 `base_url`
|
||||
*base_url = "https://api.openai.com/v1"*
|
||||
|
||||
*`model` = > 取环境 名=OPENAI_MODEL *
|
||||
1. `model`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`model` = > 取环境 名=MARQDO_LLM_MODEL *
|
||||
3. `model`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`model` = > get value=`d` key=model *
|
||||
*model = > 系统.取环境 名=OPENAI_MODEL*
|
||||
1. 非 `model`
|
||||
*model = > 系统.取环境 名=MARQDO_LLM_MODEL*
|
||||
1. 非 `model`
|
||||
*model = "gpt-4o-mini"*
|
||||
|
||||
*`q_key` = > quote text=`api_key` *
|
||||
*`q_base` = > quote text=`base_url` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`suffix` = > get value=`d` key=suffix *
|
||||
*`bearer` = > get value=`d` key=bearer *
|
||||
*`p1` = > get value=`d` key=p1 *
|
||||
*`p2` = > get value=`d` key=p2 *
|
||||
*`p3` = > get value=`d` key=p3 *
|
||||
*`h1` = > get value=`d` key=h1 *
|
||||
*`h2` = > get value=`d` key=h2 *
|
||||
*`q_suf` = > quote text=`suffix` *
|
||||
*`q_br` = > quote text=`bearer` *
|
||||
*`q_p1` = > quote text=`p1` *
|
||||
*`q_p2` = > quote text=`p2` *
|
||||
*`q_p3` = > quote text=`p3` *
|
||||
*`q_h1` = > quote text=`h1` *
|
||||
*`q_h2` = > quote text=`h2` *
|
||||
*`a1` = > get value=`d` key=a1 *
|
||||
*`a2` = > get value=`d` key=a2 *
|
||||
*`a3` = > get value=`d` key=a3 *
|
||||
*`a4` = > get value=`d` key=a4 *
|
||||
*`a5` = > get value=`d` key=a5 *
|
||||
*`a6` = > get value=`d` key=a6 *
|
||||
*`a7` = > get value=`d` key=a7 *
|
||||
*`a8` = > get value=`d` key=a8 *
|
||||
*`a9` = > get value=`d` key=a9 *
|
||||
*`a10` = > get value=`d` key=a10 *
|
||||
*`a11` = > get value=`d` key=a11 *
|
||||
*`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` *
|
||||
**> parse text=`raw`**
|
||||
`h` =
|
||||
|
||||
| api_key | base_url | model | suffix | bearer |
|
||||
|---------|----------|-------|--------|--------|
|
||||
| `api_key` | `base_url` | `model` | /chat/completions | "Bearer " |
|
||||
|
||||
**h**
|
||||
|
||||
## 运行
|
||||
+ `提示`
|
||||
+ `流式`=False
|
||||
+ `打印增量`=False
|
||||
|
||||
使用 `自` / `self` 句柄字段做聊天补全。
|
||||
使用 `自` 句柄字段做聊天补全。
|
||||
|
||||
*`api_key` = > get value=`自` key=api_key *
|
||||
*`base_url` = > get value=`自` key=base_url *
|
||||
*`model` = > get value=`自` key=model *
|
||||
*`suffix` = > get value=`自` key=suffix *
|
||||
*`bearer` = > get value=`自` key=bearer *
|
||||
*`p1` = > get value=`自` key=p1 *
|
||||
*`p2` = > get value=`自` key=p2 *
|
||||
*`p3` = > get value=`自` key=p3 *
|
||||
*`h1` = > get value=`自` key=h1 *
|
||||
*`h2` = > get value=`自` key=h2 *
|
||||
*`url` = `base_url` + `suffix` *
|
||||
*`auth` = `bearer` + `api_key` *
|
||||
*`q_auth` = > quote text=`auth` *
|
||||
*`hdr_raw` = `h1` + `q_auth` + `h2` *
|
||||
*`headers` = > parse text=`hdr_raw` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`q_prompt` = > quote text=`提示` *
|
||||
*`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` *
|
||||
*`resp` = > http_post url=`url` body=`body` headers=`headers` *
|
||||
*`status` = > get value=`resp` key=status *
|
||||
*`raw` = > get value=`resp` key=body *
|
||||
线上 body 为 `{model, messages:[{role,content}], stream?}`。消息用 `@` 行向表;headers 与可选 `stream` 用 `表.改`。`json` 只做 stringify/parse。
|
||||
|
||||
1. `status` == 200
|
||||
*`data` = > parse text=`raw` *
|
||||
*`choices` = > get value=`data` key=choices *
|
||||
*`first` = > at value=`choices` index=0 *
|
||||
*`message` = > get value=`first` key=message *
|
||||
*`content` = > get value=`message` key=content *
|
||||
**`content`**
|
||||
*url = 自[^base_url] + 自[^suffix]*
|
||||
*auth = 自[^bearer] + 自[^api_key]*
|
||||
*headers = > 表.改 入=None 于=Authorization 值=`auth`*
|
||||
|
||||
`messages` =
|
||||
|
||||
| @ | role | content |
|
||||
|---|------|---------|
|
||||
| 1 | user | `提示` |
|
||||
|
||||
`req` =
|
||||
|
||||
| model | messages |
|
||||
|-------|----------|
|
||||
| 自[^model] | `messages` |
|
||||
|
||||
1. `流式`
|
||||
*req = > 表.改 入=`req` 于=stream 值=True*
|
||||
*body = > json.stringify value=`req`*
|
||||
*resp = > 网络.提交流式 地址=`url` 内容=`body` headers=`headers` 打印增量=`打印增量`*
|
||||
1. resp[^status] == 200
|
||||
**resp[^events]**
|
||||
2. *
|
||||
> 打印 内容=ext/ai/大模型: HTTP 错误(流式)
|
||||
> 打印 内容=resp[^status]
|
||||
> 系统.退出 码=1
|
||||
2. *
|
||||
> 打印 内容=ext/ai/大模型: HTTP 错误
|
||||
> 打印 内容=`status`
|
||||
> 打印 内容=`raw`
|
||||
> 退出 码=1
|
||||
*body = > json.stringify value=`req`*
|
||||
*resp = > 网络.提交 地址=`url` 内容=`body` headers=`headers`*
|
||||
1. resp[^status] == 200
|
||||
*data = > json.parse text=resp[^body]*
|
||||
**data[^choices][^1][^message][^content]**
|
||||
2. *
|
||||
> 打印 内容=ext/ai/大模型: HTTP 错误
|
||||
> 打印 内容=resp[^status]
|
||||
> 打印 内容=resp[^body]
|
||||
> 系统.退出 码=1
|
||||
|
||||
---
|
||||
|
||||
## 聊天
|
||||
+ `提示`
|
||||
+ `流式`=False
|
||||
+ `打印增量`=False
|
||||
|
||||
`运行` 的别名。
|
||||
运行 的别名。
|
||||
|
||||
**> `自`.运行 提示=`提示`**
|
||||
**> `自`.运行 提示=`提示` 流式=`流式` 打印增量=`打印增量`**
|
||||
+197
-73
@@ -1,60 +1,119 @@
|
||||
---
|
||||
title: ext/ai/智能体
|
||||
description: 薄智能体框架 — 仅构造、执行、清空历史。
|
||||
description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务;运行时经 ABI v2 agent 插件。
|
||||
> ext/ai/大模型.mq.md
|
||||
> ext/ai/agent.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/系统.mq.md
|
||||
> lib/自写回.mq.md
|
||||
> lib/子任务.mq.md
|
||||
> lib/插件.mq.md
|
||||
---
|
||||
|
||||
## 构建上下文
|
||||
## 构建单步上下文
|
||||
+ `智能体`
|
||||
+ `额外信息`
|
||||
+ `任务`
|
||||
|
||||
内部:组装提示(用户提示、额外信息、工具列表、源码、位置、历史、Marqdo skill)。
|
||||
组装可读提示:站立提示、任务、工具、调用位置、源码、Skill,以及人可见的行动约定。
|
||||
|
||||
*`user_prompt` = > get value=`智能体` key=user_prompt *
|
||||
1. `user_prompt`
|
||||
*`up` = `user_prompt`*
|
||||
*`standing` = > json.get value=`智能体` key=standing *
|
||||
1. `standing`
|
||||
*`up` = `standing`*
|
||||
2. *
|
||||
*`up` = 空*
|
||||
|
||||
*`tools` = > get value=`智能体` key=tools *
|
||||
*`tools_s` = > host_format_tools_for_llm tools=`tools` *
|
||||
*`src` = > host_module_source *
|
||||
*`site` = > host_call_site *
|
||||
*`site_s` = > stringify value=`site` *
|
||||
*`id` = > get value=`智能体` key=id *
|
||||
*`hist` = > host_agent_history_get id=`id` *
|
||||
*`hist_s` = > stringify value=`hist` *
|
||||
*`skill` = > host_marqdo_skill *
|
||||
*`extra_s` = > stringify value=`额外信息` *
|
||||
*`tools` = > json.get value=`智能体` key=tools *
|
||||
*`tools_s` = > agent_format_tools tools=`tools` *
|
||||
*`src` = > agent_module_source *
|
||||
*`site` = > agent_call_site *
|
||||
*`site_s` = > json.stringify value=`site` *
|
||||
*`skill` = > agent_marqdo_skill *
|
||||
*`task_s` = > json.stringify value=`任务` *
|
||||
|
||||
*`sep` = > parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- extra ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source ---\n","f":"\n\n--- history ---\n","g":"\n\n--- marqdo skill ---\n"} *
|
||||
*`a` = > get value=`sep` key=a *
|
||||
*`b` = > get value=`sep` key=b *
|
||||
*`c` = > get value=`sep` key=c *
|
||||
*`d` = > get value=`sep` key=d *
|
||||
*`e` = > get value=`sep` key=e *
|
||||
*`f` = > get value=`sep` key=f *
|
||||
*`g` = > get value=`sep` key=g *
|
||||
*`esc` = > json.parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- task ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source (.mq.md) ---\n","f":"\n\n--- marqdo skill ---\n","g":"\n\n--- how to act ---\nTools are ## functions in the source above. To call one, reply with exactly one line: CALL:<name>\n(Chinese ok: 调用:<name>)\nOtherwise reply with the final answer only.\nTools run via Marqdo subtask (spawn fn / wait).\n"} *
|
||||
*`a` = > json.get value=`esc` key=a *
|
||||
*`b` = > json.get value=`esc` key=b *
|
||||
*`c` = > json.get value=`esc` key=c *
|
||||
*`d` = > json.get value=`esc` key=d *
|
||||
*`e` = > json.get value=`esc` key=e *
|
||||
*`f` = > json.get value=`esc` key=f *
|
||||
*`g` = > json.get value=`esc` key=g *
|
||||
|
||||
*`tool_proto` = \n\n--- tool protocol ---\nEach tool is a zero-arg Marqdo function in this module (see tools list). To call one, reply with exactly one line: TOOL:<name>. No other text on that line.\nAfter the tool runs you will get its output and should answer the user.\n *
|
||||
|
||||
*`p` = You are a Marqdo agent. Follow Marqdo skill rules when reading or writing .mq.md. *
|
||||
*`p` = `p` + `a` + `up` + `b` + `extra_s` + `c` + `tool_proto` + `tools_s` + `d` + `site_s` + `e` + `src` + `f` + `hist_s` + `g` + `skill` *
|
||||
*`p` = "You are a Marqdo agent. The runbook source is your ground truth — code is documentation." *
|
||||
*`p` = `p` + `a` + `up` + `b` + `task_s` + `c` + `tools_s` + `g` + `d` + `site_s` + `e` + `src` + `f` + `skill` *
|
||||
**`p`**
|
||||
|
||||
---
|
||||
|
||||
## 提取工具名
|
||||
+ `回复`
|
||||
|
||||
解析人可读调用行:`CALL:<名>` 或 `调用:<名>` / `调用:<名>`。
|
||||
|
||||
*`esc` = > json.parse text={"nl":"\n"} *
|
||||
*`nl` = > json.get value=`esc` key=nl *
|
||||
*`text` = > trim value=`回复` *
|
||||
*`lines` = > split value=`text` sep=`nl` *
|
||||
*`found` = 空*
|
||||
|
||||
- [`line`](`lines`)
|
||||
*`t` = > trim value=`line` *
|
||||
*`parts` = > split value=`t` sep=: *
|
||||
*`n` = > len value=`parts` *
|
||||
1. `n` > 1
|
||||
*`head` = > at value=`parts` index=0 *
|
||||
*`head` = > trim value=`head` *
|
||||
*`rest` = > at value=`parts` index=1 *
|
||||
*`rest` = > trim value=`rest` *
|
||||
1. `head` == CALL
|
||||
*`found` = `rest`*
|
||||
2. `head` == 调用
|
||||
*`found` = `rest`*
|
||||
3. *
|
||||
*`_` = 1*
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`found`**
|
||||
|
||||
---
|
||||
|
||||
## 运行工具
|
||||
+ `工具`
|
||||
+ `名`
|
||||
|
||||
白名单校验后,经 `lib/子任务`(`启动 函数=` → `等待`)调用 runbook 中的 `##`。
|
||||
|
||||
*`allowed` = > agent_tool_allowed tools=`工具` name=`名` *
|
||||
1. `allowed`
|
||||
*`id` = > 子任务.启动 函数=`名` *
|
||||
**> 子任务.等待 id=`id`**
|
||||
2. *
|
||||
*`msg` = "Tool not allowed:" *
|
||||
**`msg` + `名`**
|
||||
|
||||
# 智能体
|
||||
+ `大模型`
|
||||
+ `工具`
|
||||
+ `用户提示信息`
|
||||
+ `站立提示`
|
||||
|
||||
*`id` = > host_agent_alloc *
|
||||
*`h` = > parse text={"_type":"智能体"} *
|
||||
*`h` = > map_set map=`h` key=id value=`id` *
|
||||
*`h` = > map_set map=`h` key=model value=`大模型` *
|
||||
*`h` = > map_set map=`h` key=tools value=`工具` *
|
||||
加载 ABI v2 agent 插件(会话袋 + 上下文查询)。
|
||||
|
||||
1. `用户提示信息`
|
||||
*`h` = > map_set map=`h` key=user_prompt value=`用户提示信息` *
|
||||
*`p` = > 插件.原生路径 名=agent *
|
||||
1. `p`
|
||||
> 插件.加载 路径=`p`
|
||||
2. *
|
||||
> 打印 内容=ext/ai/智能体: 未找到原生 agent 插件(请先 cargo build -p marqdo_plugin_agent 或 marqdo ext add agent)
|
||||
> 系统.退出 码=1
|
||||
|
||||
*`id` = > agent_alloc *
|
||||
*`h` = > json.parse text={"_type":"智能体"} *
|
||||
*`h` = > json.set map=`h` key=id value=`id` *
|
||||
*`h` = > json.set map=`h` key=model value=`大模型` *
|
||||
*`h` = > json.set map=`h` key=tools value=`工具` *
|
||||
|
||||
1. `站立提示`
|
||||
*`h` = > json.set map=`h` key=standing value=`站立提示` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
@@ -62,50 +121,115 @@ description: 薄智能体框架 — 仅构造、执行、清空历史。
|
||||
|
||||
## 清空历史
|
||||
|
||||
*`id` = > get value=`自` key=id *
|
||||
> host_agent_history_clear id=`id`
|
||||
清空本智能体 id 的插件会话袋。
|
||||
|
||||
*`id` = > json.get value=`自` key=id *
|
||||
> agent_history_clear id=`id`
|
||||
****
|
||||
|
||||
## 执行
|
||||
+ `额外信息`
|
||||
## 单步
|
||||
+ `任务`
|
||||
+ `写回`=真
|
||||
+ `流式`=假
|
||||
+ `打印增量`=假
|
||||
|
||||
*`ctx` = > 构建上下文 智能体=`自` 额外信息=`额外信息` *
|
||||
*`id` = > get value=`自` key=id *
|
||||
原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 **map**(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。默认(`写回=真`)将结果写入调用行下的命名槽 `ok` / `error`;传 `写回=假` 可关闭。
|
||||
|
||||
*`user_turn` = > parse text={"role":"user"} *
|
||||
*`user_turn` = > map_set map=`user_turn` key=content value=`额外信息` *
|
||||
> host_agent_history_append id=`id` item=`user_turn`
|
||||
流式=真 时走 SSE;打印增量=真 边读边打印。返回 map 仍是最终 result 文本。
|
||||
|
||||
*`ctx` = > 构建单步上下文 智能体=`自` 任务=`任务` *
|
||||
*`id` = > json.get value=`自` key=id *
|
||||
*`model` = > json.get value=`自` key=model *
|
||||
*`tools` = > json.get value=`自` key=tools *
|
||||
|
||||
*`user_turn` = > json.parse text={"role":"user"} *
|
||||
*`user_turn` = > json.set map=`user_turn` key=content value=`任务` *
|
||||
> agent_history_append id=`id` item=`user_turn`
|
||||
|
||||
1. `流式`
|
||||
*`evs` = > `model`.运行 提示=`ctx` 流式=真 打印增量=`打印增量` *
|
||||
*`reply` = > 大模型.流式结果 事件=`evs` *
|
||||
2. *
|
||||
*`reply` = > `model`.运行 提示=`ctx` *
|
||||
|
||||
*`model` = > get value=`自` key=model *
|
||||
*`reply` = > `model`.运行 提示=`ctx` *
|
||||
*`tools` = > get value=`自` key=tools *
|
||||
*`reply` = > trim value=`reply` *
|
||||
*`decision` = `reply`*
|
||||
*`tool_name` = > 提取工具名 回复=`reply` *
|
||||
*`out` = > json.parse text={"status":"ok"} *
|
||||
*`out` = > json.set map=`out` key=task value=`任务` *
|
||||
*`out` = > json.set map=`out` key=decision value=`decision` *
|
||||
|
||||
*`parts` = > split value=`reply` sep=: *
|
||||
*`head` = > at value=`parts` index=0 *
|
||||
*`tool_name` = > at value=`parts` index=1 *
|
||||
*`tool_name` = > trim value=`tool_name` *
|
||||
|
||||
1. `head` == TOOL
|
||||
*`allowed` = > host_tool_allowed tools=`tools` name=`tool_name` *
|
||||
1. `allowed`
|
||||
*`tool_out` = > 调用 名=`tool_name` *
|
||||
*`tool_s` = > stringify value=`tool_out` *
|
||||
*`extra_s` = > stringify value=`额外信息` *
|
||||
*`fp` = The user asked: *
|
||||
*`fp` = `fp` + `extra_s` *
|
||||
*`fp` = `fp` + . You invoked tool *
|
||||
*`fp` = `fp` + `tool_name` *
|
||||
*`fp` = `fp` + which returned: *
|
||||
*`fp` = `fp` + `tool_s` *
|
||||
*`fp` = `fp` + . Reply to the user in one brief sentence. *
|
||||
*`reply` = > `model`.运行 提示=`fp` *
|
||||
1. `tool_name`
|
||||
*`tool_out` = > 运行工具 工具=`tools` 名=`tool_name` *
|
||||
*`tool_s` = > json.stringify value=`tool_out` *
|
||||
*`deny` = > split value=`tool_s` sep=Tool not allowed *
|
||||
*`deny_n` = > len value=`deny` *
|
||||
1. `deny_n` > 1
|
||||
*`out` = > json.set map=`out` key=status value=error *
|
||||
*`out` = > json.set map=`out` key=error value=`tool_s` *
|
||||
*`reply` = `tool_s`*
|
||||
2. *
|
||||
*`reply` = Tool not allowed: `tool_name` *
|
||||
*`task_s` = > json.stringify value=`任务` *
|
||||
*`fp` = "The user asked:" *
|
||||
*`fp` = `fp` + `task_s` *
|
||||
*`fp` = `fp` + ". Tool" *
|
||||
*`fp` = `fp` + `tool_name` *
|
||||
*`fp` = `fp` + "ran via subtask and returned:" *
|
||||
*`fp` = `fp` + `tool_s` *
|
||||
*`fp` = `fp` + ". Reply to the user briefly." *
|
||||
1. `流式`
|
||||
*`evs2` = > `model`.运行 提示=`fp` 流式=真 打印增量=`打印增量` *
|
||||
*`reply` = > 大模型.流式结果 事件=`evs2` *
|
||||
2. *
|
||||
*`reply` = > `model`.运行 提示=`fp` *
|
||||
*`out` = > json.set map=`out` key=tool value=`tool_name` *
|
||||
*`out` = > json.set map=`out` key=tool_result value=`tool_s` *
|
||||
*`out` = > json.set map=`out` key=result value=`reply` *
|
||||
2. *
|
||||
*`out` = > json.set map=`out` key=result value=`reply` *
|
||||
|
||||
*`as_turn` = > json.parse text={"role":"assistant"} *
|
||||
*`as_turn` = > json.set map=`as_turn` key=content value=`reply` *
|
||||
> agent_history_append id=`id` item=`as_turn`
|
||||
|
||||
1. `写回`
|
||||
*`body` = > json.stringify value=`out` *
|
||||
*`st` = > json.get value=`out` key=status *
|
||||
1. `st` == ok
|
||||
> 自写回.写回 值=`body` 键=ok
|
||||
2. *
|
||||
> 自写回.写回 值=`body` 键=error
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
*`as_turn` = > parse text={"role":"assistant"} *
|
||||
*`as_turn` = > map_set map=`as_turn` key=content value=`reply` *
|
||||
> host_agent_history_append id=`id` item=`as_turn`
|
||||
**`reply`**
|
||||
**`out`**
|
||||
|
||||
## 多步
|
||||
+ `目标`
|
||||
+ `工作簿目录`=None
|
||||
+ `工作簿`=None
|
||||
+ `最大轮次`=4
|
||||
+ `确认分解`=False
|
||||
+ `写回`=True
|
||||
+ `骨架`=single
|
||||
+ `复用`=True
|
||||
+ `优化`=False
|
||||
+ `强制`=False
|
||||
+ `软命中`=False
|
||||
+ `近义命中`=True
|
||||
+ `近义阈值`=0.78
|
||||
+ `晋升`=True
|
||||
+ `知识库目录`=.marqdo/agent-kb
|
||||
+ `改进周期`=3
|
||||
+ `探索次数`=3
|
||||
+ `流式`=False
|
||||
+ `打印增量`=False
|
||||
+ `轨迹`=False
|
||||
|
||||
多步工作簿默认写入 OKF `知识库目录/resources/<slug>.mq.md`;仅当传入 `工作簿目录` 时才用临时 runs。转发至英文 `agent.plan`。`流式` / `打印增量` / `轨迹` 对应 `stream` / `echo` / `trace`;`软命中` → `soft_match`;`近义命中` / `近义阈值` → `near_match` / `near_threshold`。
|
||||
|
||||
*`model` = > json.get value=`self` key=model *
|
||||
*`tools` = > json.get value=`self` key=tools *
|
||||
*`standing` = > json.get value=`self` key=standing *
|
||||
*`en` = > agent.agent model=`model` tools=`tools` standing=`standing` *
|
||||
**> `en`.plan goal=`目标` workbook_dir=`工作簿目录` workbook=`工作簿` max_rounds=`最大轮次` confirm=`确认分解` writeback=`写回` skeleton=`骨架` reuse=`复用` optimize=`优化` force=`强制` soft_match=`软命中` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` kb_dir=`知识库目录` improve_every=`改进周期` explore_n=`探索次数` stream=`流式` echo=`打印增量` trace=`轨迹`**
|
||||
@@ -0,0 +1,201 @@
|
||||
---
|
||||
title: ext/quantum/quantum
|
||||
description: Official quantum circuit simulator (English). Gates + circuits; ABI plugin.
|
||||
> lib/plugin.mq.md
|
||||
> lib/sys.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## ensure_plugin
|
||||
|
||||
Load the ABI v2 `quantum` plugin once.
|
||||
|
||||
*`p` = > plugin.native_path name=quantum *
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/quantum: native quantum plugin not found (build marqdo_plugin_quantum or marqdo ext add quantum)
|
||||
> sys.exit code=1
|
||||
****
|
||||
|
||||
# circuit
|
||||
+ `qubits`=1
|
||||
+ `steps`=None
|
||||
|
||||
State-vector circuit (default |0…0⟩). Optional `steps=` gate table (column or row records). Methods append gates and return an updated handle.
|
||||
|
||||
> ensure_plugin
|
||||
**> quantum_circuit_new qubits=`qubits` steps=`steps`**
|
||||
|
||||
## h
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_h circuit=`self` qubit=`qubit`**
|
||||
|
||||
## x
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_x circuit=`self` qubit=`qubit`**
|
||||
|
||||
## y
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_y circuit=`self` qubit=`qubit`**
|
||||
|
||||
## z
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_z circuit=`self` qubit=`qubit`**
|
||||
|
||||
## s
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_s circuit=`self` qubit=`qubit`**
|
||||
|
||||
## t
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_t circuit=`self` qubit=`qubit`**
|
||||
|
||||
## i
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_i circuit=`self` qubit=`qubit`**
|
||||
|
||||
## rx
|
||||
+ `qubit`=0
|
||||
+ `theta`
|
||||
|
||||
**> quantum_rx circuit=`self` qubit=`qubit` theta=`theta`**
|
||||
|
||||
## ry
|
||||
+ `qubit`=0
|
||||
+ `theta`
|
||||
|
||||
**> quantum_ry circuit=`self` qubit=`qubit` theta=`theta`**
|
||||
|
||||
## rz
|
||||
+ `qubit`=0
|
||||
+ `theta`
|
||||
|
||||
**> quantum_rz circuit=`self` qubit=`qubit` theta=`theta`**
|
||||
|
||||
## cx
|
||||
+ `control`=0
|
||||
+ `target`=1
|
||||
|
||||
**> quantum_cx circuit=`self` control=`control` target=`target`**
|
||||
|
||||
## cz
|
||||
+ `control`=0
|
||||
+ `target`=1
|
||||
|
||||
**> quantum_cz circuit=`self` control=`control` target=`target`**
|
||||
|
||||
## swap
|
||||
+ `a`=0
|
||||
+ `b`=1
|
||||
|
||||
**> quantum_swap circuit=`self` a=`a` b=`b`**
|
||||
|
||||
## barrier
|
||||
|
||||
Visual separator only (no state change).
|
||||
|
||||
**> quantum_barrier circuit=`self`**
|
||||
|
||||
## measure
|
||||
+ `qubits`=None
|
||||
|
||||
Mark computational-basis readout (`None` / empty = all qubits). Affects which bits `run` reports.
|
||||
|
||||
**> quantum_measure circuit=`self` qubits=`qubits`**
|
||||
|
||||
## append
|
||||
+ `op`
|
||||
|
||||
Append another circuit's ops or a `{gate,qubits}` op map.
|
||||
|
||||
**> quantum_append circuit=`self` op=`op`**
|
||||
|
||||
## apply
|
||||
+ `gate`
|
||||
+ `qubits`=0
|
||||
|
||||
Apply a gate handle (named or custom `matrix=`) on `qubits` (int or list).
|
||||
|
||||
**> quantum_apply circuit=`self` gate=`gate` qubits=`qubits`**
|
||||
|
||||
## noise
|
||||
+ `kind`
|
||||
+ `p`
|
||||
|
||||
Teaching noise for `run` trajectories (`bitflip` / `depolarizing` / `amplitude_damping`). Ignored by `simulate` / `probabilities`.
|
||||
|
||||
**> quantum_noise circuit=`self` kind=`kind` p=`p`**
|
||||
|
||||
## simulate
|
||||
|
||||
Return state vector amplitudes `{re,im}` (ideal; no noise).
|
||||
|
||||
**> quantum_simulate circuit=`self`**
|
||||
|
||||
## state
|
||||
|
||||
Ideal state vector (same amplitudes as `simulate`).
|
||||
|
||||
**> quantum_state circuit=`self`**
|
||||
|
||||
## probabilities
|
||||
|
||||
Return map of basis label → probability (qubit 0 = rightmost bit). Ideal; ignores noise.
|
||||
|
||||
**> quantum_probabilities circuit=`self`**
|
||||
|
||||
## run
|
||||
+ `shots`=1024
|
||||
+ `seed`=1
|
||||
|
||||
Sample computational-basis shots (deterministic with `seed=`). Applies circuit `noise` if set.
|
||||
|
||||
**> quantum_run circuit=`self` shots=`shots` seed=`seed`**
|
||||
|
||||
## draw
|
||||
+ `path`=None
|
||||
+ `kind`=circuit
|
||||
+ `qubit`=0
|
||||
|
||||
Circuit rail / probability bars / Bloch sphere SVG (`kind=circuit|probs|bloch`). Records into view/CLI plots via host `record_plot`.
|
||||
|
||||
**> quantum_draw_circuit circuit=`self` path=`path` kind=`kind` qubit=`qubit`**
|
||||
|
||||
# gate
|
||||
+ `name`=None
|
||||
+ `theta`=None
|
||||
+ `matrix`=None
|
||||
|
||||
Named built-in gate (`name=H`) or custom unitary from `matrix=` (nested list / `$$` matrix fence). Optional `name=` label for custom gates (default `U`).
|
||||
|
||||
> ensure_plugin
|
||||
1. `matrix`
|
||||
**> quantum_gate_from_matrix matrix=`matrix` name=`name`**
|
||||
2. *
|
||||
**> quantum_gate_new name=`name` theta=`theta`**
|
||||
|
||||
## matrix
|
||||
|
||||
**> quantum_gate_matrix gate=`self`**
|
||||
|
||||
## matches_matrix
|
||||
+ `matrix`
|
||||
+ `tol`=0.000000001
|
||||
|
||||
**> quantum_gate_matches_matrix gate=`self` matrix=`matrix` tol=`tol`**
|
||||
|
||||
## draw
|
||||
+ `path`=None
|
||||
+ `kind`=gate
|
||||
|
||||
Gate glyph or complex-matrix heatmap (`kind=gate|matrix`). Records via host `record_plot`.
|
||||
|
||||
**> quantum_gate_draw gate=`self` path=`path` kind=`kind`**
|
||||
@@ -0,0 +1,201 @@
|
||||
---
|
||||
title: ext/quantum/量子
|
||||
description: 官方量子电路模拟(中文)。门 + 电路;ABI 插件。
|
||||
> lib/plugin.mq.md
|
||||
> lib/sys.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## 确保插件
|
||||
|
||||
加载 ABI v2 `quantum` 插件。
|
||||
|
||||
*`p` = > plugin.native_path name=quantum *
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/quantum: 未找到原生 quantum 插件(请 build marqdo_plugin_quantum 或 marqdo ext add quantum)
|
||||
> sys.exit code=1
|
||||
****
|
||||
|
||||
# 电路
|
||||
+ `比特数`=1
|
||||
+ `步骤`=None
|
||||
|
||||
状态向量电路(默认 |0…0⟩)。可选 `步骤=` 门序列表。方法追加门并返回更新后的句柄。
|
||||
|
||||
> 确保插件
|
||||
**> quantum_circuit_new qubits=`比特数` steps=`步骤`**
|
||||
|
||||
## 哈达玛
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_h circuit=`self` qubit=`比特`**
|
||||
|
||||
## 泡利X
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_x circuit=`self` qubit=`比特`**
|
||||
|
||||
## 泡利Y
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_y circuit=`self` qubit=`比特`**
|
||||
|
||||
## 泡利Z
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_z circuit=`self` qubit=`比特`**
|
||||
|
||||
## 相位S
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_s circuit=`self` qubit=`比特`**
|
||||
|
||||
## 相位T
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_t circuit=`self` qubit=`比特`**
|
||||
|
||||
## 单位
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_i circuit=`self` qubit=`比特`**
|
||||
|
||||
## 绕X
|
||||
+ `比特`=0
|
||||
+ `参数`
|
||||
|
||||
**> quantum_rx circuit=`self` qubit=`比特` theta=`参数`**
|
||||
|
||||
## 绕Y
|
||||
+ `比特`=0
|
||||
+ `参数`
|
||||
|
||||
**> quantum_ry circuit=`self` qubit=`比特` theta=`参数`**
|
||||
|
||||
## 绕Z
|
||||
+ `比特`=0
|
||||
+ `参数`
|
||||
|
||||
**> quantum_rz circuit=`self` qubit=`比特` theta=`参数`**
|
||||
|
||||
## 控非
|
||||
+ `控制`=0
|
||||
+ `目标`=1
|
||||
|
||||
**> quantum_cx circuit=`self` control=`控制` target=`目标`**
|
||||
|
||||
## 控相
|
||||
+ `控制`=0
|
||||
+ `目标`=1
|
||||
|
||||
**> quantum_cz circuit=`self` control=`控制` target=`目标`**
|
||||
|
||||
## 交换
|
||||
+ `比特甲`=0
|
||||
+ `比特乙`=1
|
||||
|
||||
**> quantum_swap circuit=`self` a=`比特甲` b=`比特乙`**
|
||||
|
||||
## 屏障
|
||||
|
||||
仅可视化分隔(不改态)。
|
||||
|
||||
**> quantum_barrier circuit=`self`**
|
||||
|
||||
## 测量
|
||||
+ `比特`=None
|
||||
|
||||
标记计算基读出(空 = 全部比特)。影响 `运行` 报告哪些位。
|
||||
|
||||
**> quantum_measure circuit=`self` qubits=`比特`**
|
||||
|
||||
## 追加
|
||||
+ `操作`
|
||||
|
||||
追加另一电路的 ops,或 `{gate,qubits}` 操作表。
|
||||
|
||||
**> quantum_append circuit=`self` op=`操作`**
|
||||
|
||||
## 施加
|
||||
+ `门`
|
||||
+ `比特`=0
|
||||
|
||||
将门句柄(具名或 `矩阵=` 自定义)施加到 `比特`(整数或列表)。
|
||||
|
||||
**> quantum_apply circuit=`self` gate=`门` qubits=`比特`**
|
||||
|
||||
## 噪声
|
||||
+ `种类`
|
||||
+ `概率`
|
||||
|
||||
教学噪声,供 `运行` 轨迹使用(`bitflip` / `depolarizing` / `amplitude_damping`,或中文:比特翻转 / 退极化 / 振幅阻尼)。`模拟` / `概率` 忽略。
|
||||
|
||||
**> quantum_noise circuit=`self` kind=`种类` p=`概率`**
|
||||
|
||||
## 模拟
|
||||
|
||||
返回态矢量振幅 `{re,im}`(理想;无噪声)。
|
||||
|
||||
**> quantum_simulate circuit=`self`**
|
||||
|
||||
## 态
|
||||
|
||||
理想态矢量(与 `模拟` 相同振幅)。
|
||||
|
||||
**> quantum_state circuit=`self`**
|
||||
|
||||
## 概率
|
||||
|
||||
基矢标签 → 概率(qubit 0 为最右侧比特)。理想;忽略噪声。
|
||||
|
||||
**> quantum_probabilities circuit=`self`**
|
||||
|
||||
## 运行
|
||||
+ `次数`=1024
|
||||
+ `种子`=1
|
||||
|
||||
计算基采样(`种子=` 可复现)。若设置了电路噪声则启用。
|
||||
|
||||
**> quantum_run circuit=`self` shots=`次数` seed=`种子`**
|
||||
|
||||
## 绘图
|
||||
+ `路径`=None
|
||||
+ `种类`=circuit
|
||||
+ `比特`=0
|
||||
|
||||
电路轨线 / 概率条 / 布洛赫球(种类 circuit、probs 或 bloch)。经 record_plot 进入 view/CLI plots。
|
||||
|
||||
**> quantum_draw_circuit circuit=`self` path=`路径` kind=`种类` qubit=`比特`**
|
||||
|
||||
# 门
|
||||
+ `名`=None
|
||||
+ `参数`=None
|
||||
+ `矩阵`=None
|
||||
|
||||
具名内置门(`名=H`)或由 `矩阵=`(嵌套 list / `$$` 矩阵围栏)定义的自定义酉门。自定义门可选 `名=`(默认 `U`)。
|
||||
|
||||
> 确保插件
|
||||
1. `矩阵`
|
||||
**> quantum_gate_from_matrix matrix=`矩阵` name=`名`**
|
||||
2. *
|
||||
**> quantum_gate_new name=`名` theta=`参数`**
|
||||
|
||||
## 矩阵
|
||||
|
||||
**> quantum_gate_matrix gate=`self`**
|
||||
|
||||
## 匹配矩阵
|
||||
+ `矩阵`
|
||||
+ `容差`=0.000000001
|
||||
|
||||
**> quantum_gate_matches_matrix gate=`self` matrix=`矩阵` tol=`容差`**
|
||||
|
||||
## 绘图
|
||||
+ `路径`=None
|
||||
+ `种类`=gate
|
||||
|
||||
门符号或复矩阵热力图(`种类=gate|matrix`)。经 `record_plot` 记录。
|
||||
|
||||
**> quantum_gate_draw gate=`self` path=`路径` kind=`种类`**
|
||||
@@ -0,0 +1,31 @@
|
||||
# ext/web
|
||||
|
||||
Official dynamic website extension: **GFM tables + class methods**.
|
||||
Design: [`doc/design/ext-web.md`](../../doc/design/ext-web.md).
|
||||
|
||||
| Surface | Import | Classes |
|
||||
|---------|--------|---------|
|
||||
| English | `> ext/web/web.mq.md` | `page` · `db` · `app` · `form` · `style` |
|
||||
| Chinese | `> ext/web/网页.mq.md` | `页面` · `数据库` · `应用` · `表单` · `样式` |
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_web
|
||||
# optional install into ~/.marqdo/ext
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
Canonical sample (design §4): [`examples/web-site/`](../../examples/web-site/).
|
||||
|
||||
```bash
|
||||
cargo run -- run examples/web-site/index.mq.md
|
||||
# http://127.0.0.1:18081/
|
||||
# /_form/article · /admin · /admin/articles/new
|
||||
```
|
||||
|
||||
Offline smokes: `tests/ext/web-smoke.mq.md`, `web-form-smoke.mq.md`, `web-admin-smoke.mq.md`.
|
||||
|
||||
| Feature | Notes |
|
||||
|---------|--------|
|
||||
| Form §5.5 | field/rules tables · `validate` · `submit` · `mount_form` → `GET\|POST /_form/{id}` |
|
||||
| Admin CRUD | `admin=True` · schema → same form path · new/edit/delete under `/admin/{table}` |
|
||||
| Route | `` `app`.route path=/about page=`about` `` → `GET /about` |
|
||||
@@ -0,0 +1,213 @@
|
||||
---
|
||||
title: ext/web/web
|
||||
description: Official web site classes (English). Tables + methods; no bag glue.
|
||||
> lib/plugin.mq.md
|
||||
> lib/sys.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## ensure_plugin
|
||||
|
||||
Load the ABI v2 `web` plugin once.
|
||||
|
||||
*`p` = > plugin.native_path name=web *
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/web: native web plugin not found (build marqdo_plugin_web or marqdo ext add web)
|
||||
> sys.exit code=1
|
||||
****
|
||||
|
||||
# page
|
||||
+ `title`="Marqdo Web"
|
||||
+ `intro`=""
|
||||
|
||||
> ensure_plugin
|
||||
**> web_page_new title=`title` intro=`intro`**
|
||||
|
||||
## compose_components
|
||||
+ `components`
|
||||
|
||||
Assemble nav / sidebar / footer from a page table (`|组件|样式|` or `|src|style|`).
|
||||
|
||||
**> web_compose_components page=`self` components=`components`**
|
||||
|
||||
## compose_main
|
||||
+ `main`
|
||||
|
||||
Assemble main from a bind table (`|属性|值|样式|` or `|front|back|css|`).
|
||||
|
||||
**> web_compose_main page=`self` main=`main`**
|
||||
|
||||
## compose_form
|
||||
+ `form`
|
||||
+ `id`
|
||||
|
||||
Embed a form into the page main slot. `listen` auto-registers `GET|POST /_form/{id}` from page/route forms (optional `app.mount_form`).
|
||||
|
||||
**> web_compose_form page=`self` form=`form` id=`id`**
|
||||
|
||||
## render
|
||||
+ `db`=None
|
||||
|
||||
Offline HTML for tests / previews.
|
||||
|
||||
1. `db`
|
||||
*`url` = > json.get value=`db` key=url *
|
||||
**> web_render page=`self` url=`url`**
|
||||
2. *
|
||||
**> web_render page=`self`**
|
||||
|
||||
# style
|
||||
+ `name`=""
|
||||
|
||||
Style tables live as `##` exports in site style modules; compose resolves them by path.
|
||||
|
||||
**`self`**
|
||||
|
||||
## process
|
||||
+ `style`=None
|
||||
+ `name`=None
|
||||
+ `path`=None
|
||||
|
||||
**`self`**
|
||||
|
||||
# db
|
||||
+ `url`="sqlite:site.db"
|
||||
|
||||
> ensure_plugin
|
||||
**> web_db_new url=`url`**
|
||||
|
||||
## init
|
||||
+ `name`
|
||||
+ `fields`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_init url=`url` name=`name` fields=`fields`**
|
||||
|
||||
## insert
|
||||
+ `table`
|
||||
+ `rows`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_insert url=`url` table=`table` rows=`rows`**
|
||||
|
||||
## select
|
||||
+ `table`
|
||||
+ `where`=None
|
||||
+ `limit`=200
|
||||
|
||||
Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作|值|` (`=` `!=` `>` `>=` `<` `<=` `like`).
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
*`r` = > web_db_select url=`url` table=`table` where=`where` limit=`limit` *
|
||||
**> json.get value=`r` key=rows**
|
||||
|
||||
## get
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_get url=`url` table=`table` id=`id`**
|
||||
|
||||
## update
|
||||
+ `table`
|
||||
+ `id`
|
||||
+ `row`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_update url=`url` table=`table` id=`id` row=`row`**
|
||||
|
||||
## delete
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_delete url=`url` table=`table` id=`id`**
|
||||
|
||||
## exec
|
||||
+ `sql`
|
||||
+ `args`=None
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_exec url=`url` sql=`sql` args=`args`**
|
||||
|
||||
# form
|
||||
+ `table`=None
|
||||
+ `action`=insert
|
||||
+ `id`=None
|
||||
|
||||
Field table + rules table; submit writes through `# db`.
|
||||
|
||||
> ensure_plugin
|
||||
**> web_form_new table=`table` action=`action` id=`id`**
|
||||
|
||||
## fields
|
||||
+ `fields`
|
||||
|
||||
**> web_form_fields form=`self` fields=`fields`**
|
||||
|
||||
## rules
|
||||
+ `rules`
|
||||
|
||||
**> web_form_rules form=`self` rules=`rules`**
|
||||
|
||||
## validate
|
||||
+ `rules`=None
|
||||
+ `data`
|
||||
|
||||
**> web_form_validate form=`self` rules=`rules` data=`data`**
|
||||
|
||||
## render
|
||||
+ `id`=form
|
||||
+ `data`=None
|
||||
+ `errors`=None
|
||||
|
||||
**> web_form_render form=`self` id=`id` data=`data` errors=`errors`**
|
||||
|
||||
## submit
|
||||
+ `data`
|
||||
+ `db`
|
||||
|
||||
*`url` = > json.get value=`db` key=url *
|
||||
**> web_form_submit form=`self` data=`data` url=`url`**
|
||||
|
||||
# app
|
||||
+ `page`
|
||||
+ `db`=None
|
||||
+ `admin`=False
|
||||
+ `host`=127.0.0.1
|
||||
+ `port`=18081
|
||||
|
||||
> ensure_plugin
|
||||
**> web_app_new page=`page` db=`db` admin=`admin` host=`host` port=`port`**
|
||||
|
||||
## route
|
||||
+ `path`
|
||||
+ `page`
|
||||
|
||||
Mount an assembled page at `path` (e.g. `/about`). `/` is the home `page=`.
|
||||
|
||||
**> web_app_route app=`self` path=`path` page=`page`**
|
||||
|
||||
## mount_form
|
||||
+ `id`
|
||||
+ `form`
|
||||
|
||||
Register `GET|POST /_form/{id}` for listen when the form is not already embedded via `page.compose_form`.
|
||||
|
||||
**> web_app_mount_form app=`self` id=`id` form=`form`**
|
||||
|
||||
## static
|
||||
+ `dir`
|
||||
+ `mount`=/static
|
||||
|
||||
Serve files from `dir` under `mount` (default `/static`). Path is resolved from the process working directory at listen time.
|
||||
|
||||
**> web_app_static app=`self` dir=`dir` mount=`mount`**
|
||||
|
||||
## listen
|
||||
|
||||
Serve `/`, routed pages, `/_part/{id}` (home) and `{path}/_part/{id}` (routes), `/_form/{id}` (from mounts + page embeds), optional `/static` (or custom mount), and optional `/admin`.
|
||||
|
||||
**> web_listen app=`self`**
|
||||
@@ -0,0 +1,203 @@
|
||||
---
|
||||
title: ext/web/网页
|
||||
description: 官方网站类(中文)。表格 + 方法;不写袋式胶水。
|
||||
> lib/plugin.mq.md
|
||||
> lib/sys.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## 确保插件
|
||||
|
||||
加载 ABI v2 `web` 插件。
|
||||
|
||||
*`p` = > plugin.native_path name=web *
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/web: 未找到原生 web 插件(请 build marqdo_plugin_web 或 marqdo ext add web)
|
||||
> sys.exit code=1
|
||||
****
|
||||
|
||||
# 页面
|
||||
+ `标题`="站点"
|
||||
+ `引言`=""
|
||||
|
||||
> 确保插件
|
||||
**> web_page_new title=`标题` intro=`引言`**
|
||||
|
||||
## 组件装配
|
||||
+ `组件`
|
||||
|
||||
**> web_compose_components page=`self` components=`组件`**
|
||||
|
||||
## 主体装配
|
||||
+ `主体`
|
||||
|
||||
**> web_compose_main page=`self` main=`主体`**
|
||||
|
||||
## 表单装配
|
||||
+ `表单`
|
||||
+ `id`
|
||||
|
||||
将表单嵌入页面主区。`listen` 会从页面/路由上的表单自动挂载 `GET|POST /_form/{id}`(可选再 `挂载表单`)。
|
||||
|
||||
**> web_compose_form page=`self` form=`表单` id=`id`**
|
||||
|
||||
## 渲染
|
||||
+ `数据库`=None
|
||||
|
||||
1. `数据库`
|
||||
*`url` = > json.get value=`数据库` key=url *
|
||||
**> web_render page=`self` url=`url`**
|
||||
2. *
|
||||
**> web_render page=`self`**
|
||||
|
||||
# 样式
|
||||
+ `名`=""
|
||||
|
||||
**`self`**
|
||||
|
||||
## 样式处理
|
||||
+ `样式`=None
|
||||
+ `名`=None
|
||||
+ `路径`=None
|
||||
|
||||
**`self`**
|
||||
|
||||
# 数据库
|
||||
+ `地址`="sqlite:site.db"
|
||||
|
||||
> 确保插件
|
||||
**> web_db_new url=`地址`**
|
||||
|
||||
## 初始化
|
||||
+ `名`
|
||||
+ `字段`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_init url=`url` name=`名` fields=`字段`**
|
||||
|
||||
## 插入
|
||||
+ `表`
|
||||
+ `行`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_insert url=`url` table=`表` rows=`行`**
|
||||
|
||||
## 查询
|
||||
+ `表`
|
||||
+ `条件`=None
|
||||
+ `上限`=200
|
||||
|
||||
简单条件:单行列→值映射(AND `=`),或 `|字段|操作|值|` 表(`=` `!=` `>` `>=` `<` `<=` `like`)。
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
*`r` = > web_db_select url=`url` table=`表` where=`条件` limit=`上限` *
|
||||
**> json.get value=`r` key=rows**
|
||||
|
||||
## 获取
|
||||
+ `表`
|
||||
+ `id`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_get url=`url` table=`表` id=`id`**
|
||||
|
||||
## 更新
|
||||
+ `表`
|
||||
+ `id`
|
||||
+ `行`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_update url=`url` table=`表` id=`id` row=`行`**
|
||||
|
||||
## 删除
|
||||
+ `表`
|
||||
+ `id`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_delete url=`url` table=`表` id=`id`**
|
||||
|
||||
## 执行
|
||||
+ `sql`
|
||||
+ `参数`=None
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_exec url=`url` sql=`sql` args=`参数`**
|
||||
|
||||
# 表单
|
||||
+ `表`=None
|
||||
+ `动作`=插入
|
||||
+ `id`=None
|
||||
|
||||
字段表 + 校验表;提交经 `# 数据库` 写入。
|
||||
|
||||
> 确保插件
|
||||
**> web_form_new table=`表` action=`动作` id=`id`**
|
||||
|
||||
## 字段
|
||||
+ `字段`
|
||||
|
||||
**> web_form_fields form=`self` fields=`字段`**
|
||||
|
||||
## 规则
|
||||
+ `规则`
|
||||
|
||||
**> web_form_rules form=`self` rules=`规则`**
|
||||
|
||||
## 校验
|
||||
+ `规则`=None
|
||||
+ `数据`
|
||||
|
||||
**> web_form_validate form=`self` rules=`规则` data=`数据`**
|
||||
|
||||
## 渲染
|
||||
+ `id`=form
|
||||
+ `数据`=None
|
||||
+ `错误`=None
|
||||
|
||||
**> web_form_render form=`self` id=`id` data=`数据` errors=`错误`**
|
||||
|
||||
## 提交
|
||||
+ `数据`
|
||||
+ `数据库`
|
||||
|
||||
*`url` = > json.get value=`数据库` key=url *
|
||||
**> web_form_submit form=`self` data=`数据` url=`url`**
|
||||
|
||||
# 应用
|
||||
+ `页面`
|
||||
+ `数据库`=None
|
||||
+ `后台`=False
|
||||
+ `主机`=127.0.0.1
|
||||
+ `端口`=18081
|
||||
|
||||
> 确保插件
|
||||
**> web_app_new page=`页面` db=`数据库` admin=`后台` host=`主机` port=`端口`**
|
||||
|
||||
## 路由
|
||||
+ `路径`
|
||||
+ `页面`
|
||||
|
||||
将已装配页面挂到 `路径`(如 `/about`)。`/` 由首页 `页面=` 提供。
|
||||
|
||||
**> web_app_route app=`self` path=`路径` page=`页面`**
|
||||
|
||||
## 挂载表单
|
||||
+ `id`
|
||||
+ `表单`
|
||||
|
||||
**> web_app_mount_form app=`self` id=`id` form=`表单`**
|
||||
|
||||
## 静态
|
||||
+ `目录`
|
||||
+ `挂载`=/static
|
||||
|
||||
将 `目录` 下的文件挂到 `挂载`(默认 `/static`)。路径在 `监听` 时相对进程工作目录解析。
|
||||
|
||||
**> web_app_static app=`self` dir=`目录` mount=`挂载`**
|
||||
|
||||
## 监听
|
||||
|
||||
提供 `/`、路由页、首页 `/_part/{id}`、路由 `{路径}/_part/{id}`、`/_form/{id}`、可选静态目录,以及可选 `/admin`。
|
||||
|
||||
**> web_listen app=`self`**
|
||||
+14
-2
@@ -1,7 +1,10 @@
|
||||
/* Marqdo plugin ABI v1 — C contract (source of truth).
|
||||
/* Marqdo plugin ABI v2 — C contract (source of truth).
|
||||
*
|
||||
* Plugins are optional shared libraries (.dll / .so / .dylib), never linked
|
||||
* into the marqdo binary. Values cross the boundary as UTF-8 JSON.
|
||||
*
|
||||
* v1: register_fn, alloc, free
|
||||
* v2: + host_query (allowlisted host introspection for plugins)
|
||||
*/
|
||||
#ifndef MARQDO_ABI_H
|
||||
#define MARQDO_ABI_H
|
||||
@@ -13,7 +16,8 @@
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#define MARQDO_ABI_VERSION 1u
|
||||
#define MARQDO_ABI_VERSION 2u
|
||||
#define MARQDO_ABI_VERSION_MIN 1u
|
||||
|
||||
/* Plugin function: args_json is a UTF-8 JSON object whose keys are param names.
|
||||
* On success: return 0, set *out_json to a heap string (host frees via free).
|
||||
@@ -22,6 +26,12 @@ extern "C" {
|
||||
*/
|
||||
typedef int (*MarqdoPluginFn)(const char *args_json, char **out_json, char **err_msg);
|
||||
|
||||
/* Host → plugin query (v2). `name` is an allowlisted query id.
|
||||
* Same success/failure convention as MarqdoPluginFn.
|
||||
*/
|
||||
typedef int (*MarqdoHostQueryFn)(void *userdata, const char *name, const char *args_json,
|
||||
char **out_json, char **err_msg);
|
||||
|
||||
typedef struct MarqdoHostApi {
|
||||
void *userdata;
|
||||
/* params: comma-separated param names in order, e.g. "a,b". May be "". */
|
||||
@@ -29,6 +39,8 @@ typedef struct MarqdoHostApi {
|
||||
MarqdoPluginFn fn);
|
||||
void *(*alloc)(size_t n);
|
||||
void (*free)(void *p);
|
||||
/* v2: NULL for hosts that only speak v1; required when plugin abi >= 2 */
|
||||
MarqdoHostQueryFn host_query;
|
||||
} MarqdoHostApi;
|
||||
|
||||
/* Required exports from every plugin shared library. */
|
||||
|
||||
+4
-2
@@ -11,14 +11,16 @@ description: Run bound code fences and inline sources via local interpreters
|
||||
|
||||
## run
|
||||
+ `code`
|
||||
+ `stdin`=None
|
||||
|
||||
**> host_foreign_run code=`code`**
|
||||
**> host_foreign_run code=`code` stdin=`stdin`**
|
||||
|
||||
## run_lang
|
||||
+ `lang`
|
||||
+ `source`
|
||||
+ `stdin`=None
|
||||
|
||||
**> host_foreign_run_lang lang=`lang` source=`source`**
|
||||
**> host_foreign_run_lang lang=`lang` source=`source` stdin=`stdin`**
|
||||
|
||||
## langs
|
||||
|
||||
|
||||
@@ -39,3 +39,20 @@ description: English filesystem wrappers
|
||||
+ `path`
|
||||
|
||||
**> host_remove path=`path`**
|
||||
|
||||
## text_patch
|
||||
+ `path`
|
||||
+ `find`
|
||||
+ `replace`
|
||||
|
||||
Exact FIND→REPLACE once in a UTF-8 text file. `find` must match exactly once.
|
||||
|
||||
**> host_text_patch path=`path` find=`find` replace=`replace`**
|
||||
|
||||
## apply_patch_blocks
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
Apply plan-style `<<<` / FIND / === / REPLACE / `>>>` blocks from `text` to `path`.
|
||||
|
||||
**> host_apply_patch_blocks path=`path` text=`text`**
|
||||
+2
-1
@@ -10,8 +10,9 @@ description: JSON parse/stringify (shared EN/ZH import)
|
||||
|
||||
## stringify
|
||||
+ `value`
|
||||
+ `indent`=None
|
||||
|
||||
**> host_json_stringify value=`value`**
|
||||
**> host_json_stringify value=`value` indent=`indent`**
|
||||
|
||||
## get
|
||||
+ `value`
|
||||
|
||||
+17
-4
@@ -176,25 +176,38 @@ description: High-school math — num, random, formula, plot
|
||||
## solve
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`=None
|
||||
+ `max`=None
|
||||
|
||||
**> host_solve formula=`formula` var=`var`**
|
||||
**> host_solve formula=`formula` var=`var` min=`min` max=`max`**
|
||||
|
||||
## plot
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`
|
||||
+ `max`
|
||||
+ `steps`=None
|
||||
+ `path`=None
|
||||
+ `derivative`=None
|
||||
+ `grid`=None
|
||||
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max` steps=`steps` path=`path` derivative=`derivative` grid=`grid`**
|
||||
|
||||
## plot_points
|
||||
+ `xs`
|
||||
+ `ys`
|
||||
+ `path`=None
|
||||
+ `grid`=None
|
||||
|
||||
**> host_plot_points xs=`xs` ys=`ys`**
|
||||
**> host_plot_points xs=`xs` ys=`ys` path=`path` grid=`grid`**
|
||||
|
||||
## plot_conic
|
||||
+ `kind`
|
||||
+ `a`
|
||||
+ `b`=None
|
||||
+ `h`=None
|
||||
+ `k`=None
|
||||
+ `path`=None
|
||||
+ `grid`=None
|
||||
|
||||
**> host_plot_conic kind=`kind` a=`a`**
|
||||
**> host_plot_conic kind=`kind` a=`a` b=`b` h=`h` k=`k` path=`path` grid=`grid`**
|
||||
+28
-3
@@ -5,26 +5,51 @@ description: English HTTP(S) wrappers. Optional headers / content_type via host
|
||||
|
||||
## http_get
|
||||
+ `url`
|
||||
+ `headers`=None
|
||||
|
||||
HTTPS supported. Optional named arg `headers=` (map).
|
||||
|
||||
**> host_http_get url=`url`**
|
||||
**> host_http_get url=`url` headers=`headers`**
|
||||
|
||||
## http_post
|
||||
+ `url`
|
||||
+ `body`
|
||||
+ `content_type`=None
|
||||
+ `headers`=None
|
||||
|
||||
Default content type is JSON. Optional `content_type=` / `headers=` (map).
|
||||
|
||||
**> host_http_post url=`url` body=`body`**
|
||||
**> host_http_post url=`url` body=`body` content_type=`content_type` headers=`headers`**
|
||||
|
||||
## http_post_sse
|
||||
+ `url`
|
||||
+ `body`
|
||||
+ `content_type`=None
|
||||
+ `headers`=None
|
||||
+ `echo`=False
|
||||
|
||||
POST and consume OpenAI-compatible SSE. Returns `{status, events}` where `events` is a list of `{type, …}` maps (`delta` / `done` / `error`). Optional `echo=True` prints delta text to stdout as chunks arrive.
|
||||
|
||||
**> host_http_post_sse url=`url` body=`body` content_type=`content_type` headers=`headers` echo=`echo`**
|
||||
|
||||
## openai_sse_parse
|
||||
+ `text`
|
||||
+ `echo`=False
|
||||
|
||||
Offline: parse an OpenAI chat SSE body into the same event list (no network).
|
||||
|
||||
**> host_openai_sse_parse text=`text` echo=`echo`**
|
||||
|
||||
## http_request
|
||||
+ `method`
|
||||
+ `url`
|
||||
+ `body`=None
|
||||
+ `content_type`=None
|
||||
+ `headers`=None
|
||||
|
||||
Optional `body=` / `content_type=` / `headers=`.
|
||||
|
||||
**> host_http_request method=`method` url=`url`**
|
||||
**> host_http_request method=`method` url=`url` body=`body` content_type=`content_type` headers=`headers`**
|
||||
|
||||
## url_encode
|
||||
+ `text`
|
||||
|
||||
@@ -15,3 +15,10 @@ description: Load optional native ABI plugins (.dll / .so / .dylib)
|
||||
## list
|
||||
|
||||
**> host_plugin_list**
|
||||
|
||||
## native_path
|
||||
+ `name`
|
||||
|
||||
Resolve installed / local native plugin path (e.g. `agent`).
|
||||
|
||||
**> host_ext_native_path name=`name`**
|
||||
+7
-1
@@ -11,8 +11,14 @@ description: Concurrent subtasks — file, function, or foreign code
|
||||
+ `lang`=None
|
||||
+ `source`=None
|
||||
+ `stdin`=None
|
||||
+ `quiet`=True
|
||||
|
||||
**> host_subtask_spawn path=`path` fn=`fn` args=`args` code=`code` lang=`lang` source=`source` stdin=`stdin`**
|
||||
File children are silent by default (`quiet=True`: piped capture, no TTY noise).
|
||||
Set `quiet=False` to inherit parent stdout/stderr.
|
||||
File `wait` returns `{code, value}` plus optional `stdout`/`stderr` tails when quiet-captured.
|
||||
`value` is the child's `# main` return (not stdout).
|
||||
|
||||
**> host_subtask_spawn path=`path` fn=`fn` args=`args` code=`code` lang=`lang` source=`source` stdin=`stdin` quiet=`quiet`**
|
||||
|
||||
## poll
|
||||
+ `id`
|
||||
|
||||
+11
-2
@@ -15,10 +15,11 @@ description: English system wrappers (load_dotenv accepts optional path via host
|
||||
**> host_env_set name=`name` value=`value`**
|
||||
|
||||
## load_dotenv
|
||||
+ `path`=None
|
||||
|
||||
Load `.env` (optional named arg `path=`). Existing process env is not overridden.
|
||||
|
||||
**> host_dotenv_load**
|
||||
**> host_dotenv_load path=`path`**
|
||||
|
||||
## args
|
||||
|
||||
@@ -35,5 +36,13 @@ Load `.env` (optional named arg `path=`). Existing process env is not overridden
|
||||
|
||||
## exec
|
||||
+ `cmd`
|
||||
+ `args`=None
|
||||
|
||||
**> host_exec cmd=`cmd`**
|
||||
**> host_exec cmd=`cmd` args=`args`**
|
||||
|
||||
## stream_publish
|
||||
+ `event`
|
||||
|
||||
Publish a stream event map onto the process EventBus (`marqdo view` SSE). No-op when nothing is subscribed.
|
||||
|
||||
**> host_stream_publish event=`event`**
|
||||
+190
-1
@@ -1,15 +1,204 @@
|
||||
---
|
||||
title: lib/table
|
||||
description: English table helpers over len / at
|
||||
description: >-
|
||||
List and map helpers. Prefer put (1-based path, same as footnotes); at/set_at/slice
|
||||
are 0-based. json is for parse/stringify.
|
||||
---
|
||||
|
||||
## put
|
||||
+ `in`
|
||||
+ `at`
|
||||
+ `value`
|
||||
|
||||
Directly update one element. `at=` is a text key, a **1-based** list index, or a list path of keys/indices (same nesting as footnotes).
|
||||
|
||||
**> host_collection_put in=`in` at=`at` value=`value`**
|
||||
|
||||
## len
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
## rows
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
## at
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
Index is zero-based (same as builtin `at`). Out of range → `None`.
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
|
||||
## row_at
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
|
||||
## append
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_append list=`list` item=`item`**
|
||||
|
||||
## prepend
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_prepend list=`list` item=`item`**
|
||||
|
||||
## concat
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_list_concat a=`a` b=`b`**
|
||||
|
||||
## insert
|
||||
+ `list`
|
||||
+ `index`
|
||||
+ `item`
|
||||
|
||||
Index is zero-based (may insert at `len` to append).
|
||||
|
||||
**> host_list_insert list=`list` index=`index` item=`item`**
|
||||
|
||||
## set_at
|
||||
+ `list`
|
||||
+ `index`
|
||||
+ `item`
|
||||
|
||||
Zero-based replace. Prefer `put` with 1-based index for author-facing edits.
|
||||
|
||||
**> host_list_set_at list=`list` index=`index` item=`item`**
|
||||
|
||||
## remove_at
|
||||
+ `list`
|
||||
+ `index`
|
||||
|
||||
**> host_list_remove_at list=`list` index=`index`**
|
||||
|
||||
## pop
|
||||
+ `list`
|
||||
|
||||
Drop the last item (errors if empty). Use `last` first when you need the removed value.
|
||||
|
||||
*`n` = > len `list`*
|
||||
1. `n` > 0
|
||||
**> host_list_remove_at list=`list` index=`n` - 1**
|
||||
2. *
|
||||
**> host_list_remove_at list=`list` index=0**
|
||||
|
||||
## first
|
||||
+ `list`
|
||||
|
||||
**> host_list_first list=`list`**
|
||||
|
||||
## last
|
||||
+ `list`
|
||||
|
||||
**> host_list_last list=`list`**
|
||||
|
||||
## slice
|
||||
+ `list`
|
||||
+ `start`
|
||||
+ `end`=None
|
||||
|
||||
Zero-based half-open range from `start` to `end`.
|
||||
|
||||
**> host_list_slice list=`list` start=`start` end=`end`**
|
||||
|
||||
## contains
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_contains list=`list` item=`item`**
|
||||
|
||||
## index_of
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
Zero-based index or `None`.
|
||||
|
||||
**> host_list_index_of list=`list` item=`item`**
|
||||
|
||||
## reverse
|
||||
+ `list`
|
||||
|
||||
**> host_list_reverse list=`list`**
|
||||
|
||||
## clear
|
||||
+ `value`
|
||||
|
||||
Empty list or empty map (by type).
|
||||
|
||||
**> host_collection_clear value=`value`**
|
||||
|
||||
## get
|
||||
+ `map`
|
||||
+ `key`
|
||||
|
||||
Missing key → `None`.
|
||||
|
||||
**> host_map_get map=`map` key=`key`**
|
||||
|
||||
## set
|
||||
+ `map`
|
||||
+ `key`
|
||||
+ `value`
|
||||
|
||||
Shallow map update. Prefer `put` for nested paths.
|
||||
|
||||
**> host_map_set map=`map` key=`key` value=`value`**
|
||||
|
||||
## delete
|
||||
+ `map`
|
||||
+ `key`
|
||||
|
||||
**> host_map_delete map=`map` key=`key`**
|
||||
|
||||
## has
|
||||
+ `map`
|
||||
+ `key`
|
||||
|
||||
**> host_map_has map=`map` key=`key`**
|
||||
|
||||
## keys
|
||||
+ `map`
|
||||
|
||||
**> host_map_keys map=`map`**
|
||||
|
||||
## values
|
||||
+ `map`
|
||||
|
||||
**> host_map_values map=`map`**
|
||||
|
||||
## items
|
||||
+ `map`
|
||||
|
||||
Rows shaped as key/value maps.
|
||||
|
||||
**> host_map_items map=`map`**
|
||||
|
||||
## merge
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
Right-hand keys win.
|
||||
|
||||
**> host_map_merge a=`a` b=`b`**
|
||||
|
||||
## size
|
||||
+ `map`
|
||||
|
||||
**> host_map_size map=`map`**
|
||||
|
||||
## empty_list
|
||||
|
||||
**> host_list_concat a=None b=None**
|
||||
|
||||
## empty_map
|
||||
|
||||
**> host_map_merge a=None b=None**
|
||||
+29
-7
@@ -6,27 +6,49 @@ description: Persist run output in .mq.md (Jupyter-style writeback)
|
||||
## record
|
||||
+ `value`
|
||||
+ `at_end`=False
|
||||
+ `key`=None
|
||||
+ `line`=None
|
||||
|
||||
Write `value` to `<!-- marqdo-out … -->` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` appends a single block at EOF.
|
||||
Write `value` to `<!-- marqdo-out … -->` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` replaces the unkeyed EOF block. With `key=` (e.g. `ok` / `error`), replace or create that **named** slot only — slots do not overwrite each other. Optional `line=` anchors the block under that source line (needed when writing from a subtask).
|
||||
|
||||
**> host_writeback_record value=`value` at_end=`at_end`**
|
||||
**> host_writeback_record value=`value` at_end=`at_end` key=`key` line=`line`**
|
||||
|
||||
## get
|
||||
+ `at_end`=False
|
||||
+ `key`=None
|
||||
+ `line`=None
|
||||
|
||||
Read persisted output for the current call site (adjacent block), or the EOF block when `at_end=true`.
|
||||
Read persisted output for the current call site (adjacent unkeyed block), the unkeyed EOF block when `at_end=true`, or a named slot when `key=` is set.
|
||||
|
||||
**> host_writeback_get at_end=`at_end`**
|
||||
**> host_writeback_get at_end=`at_end` key=`key` line=`line`**
|
||||
|
||||
## clear
|
||||
+ `at_end`=False
|
||||
+ `key`=None
|
||||
+ `line`=None
|
||||
|
||||
Remove the adjacent or EOF output block.
|
||||
Remove the adjacent, EOF, or named output block.
|
||||
|
||||
**> host_writeback_clear at_end=`at_end`**
|
||||
**> host_writeback_clear at_end=`at_end` key=`key` line=`line`**
|
||||
|
||||
## ensure
|
||||
+ `key`
|
||||
+ `placeholder`=pending
|
||||
+ `line`=None
|
||||
|
||||
Create a named slot with `placeholder` if missing. Never overwrites an existing slot body.
|
||||
|
||||
**> host_writeback_ensure key=`key` placeholder=`placeholder` line=`line`**
|
||||
|
||||
## list
|
||||
|
||||
List all output blocks in the entry file.
|
||||
List all output blocks in the entry file (includes `key` when named).
|
||||
|
||||
**> host_writeback_list**
|
||||
|
||||
## scan_path
|
||||
+ `path`
|
||||
|
||||
List `<!-- marqdo-out … -->` slots in any file (workbook inspection).
|
||||
|
||||
**> host_writeback_scan_path path=`path`**
|
||||
+4
-2
@@ -11,14 +11,16 @@ description: 通过本机解释器运行绑定的代码围栏与内联源码
|
||||
|
||||
## 运行
|
||||
+ `代码`
|
||||
+ `标准输入`=None
|
||||
|
||||
**> host_foreign_run code=`代码`**
|
||||
**> host_foreign_run code=`代码` stdin=`标准输入`**
|
||||
|
||||
## 按语言运行
|
||||
+ `语言`
|
||||
+ `源码`
|
||||
+ `标准输入`=None
|
||||
|
||||
**> host_foreign_run_lang lang=`语言` source=`源码`**
|
||||
**> host_foreign_run_lang lang=`语言` source=`源码` stdin=`标准输入`**
|
||||
|
||||
## 语言表
|
||||
|
||||
|
||||
+6
-1
@@ -11,8 +11,13 @@ description: 并发子任务 — 文件、函数或外联代码
|
||||
+ `语言`=None
|
||||
+ `源码`=None
|
||||
+ `输入`=None
|
||||
+ `静默`=True
|
||||
|
||||
**> host_subtask_spawn path=`路径` fn=`函数` args=`参数` code=`代码` lang=`语言` source=`源码` stdin=`输入`**
|
||||
文件子任务默认静默(`静默=真`:管道捕获 stdout/stderr,不污染父终端)。
|
||||
`静默=假` 时继承父进程终端输出。
|
||||
文件 `等待` 返回 `{code, value}`,静默捕获时另含截断的 `stdout`/`stderr`;`value` 为子 `# main` 返回值。
|
||||
|
||||
**> host_subtask_spawn path=`路径` fn=`函数` args=`参数` code=`代码` lang=`语言` source=`源码` stdin=`输入` quiet=`静默`**
|
||||
|
||||
## 探测
|
||||
+ `id`
|
||||
|
||||
@@ -15,3 +15,10 @@ description: 加载可选原生 ABI 插件(.dll / .so / .dylib)
|
||||
## 列出
|
||||
|
||||
**> host_plugin_list**
|
||||
|
||||
## 原生路径
|
||||
+ `名`
|
||||
|
||||
解析已安装或本地原生插件路径(如 `agent`)。
|
||||
|
||||
**> host_ext_native_path name=`名`**
|
||||
+17
-4
@@ -176,25 +176,38 @@ description: 高中数学 — 数值、随机、公式、作图
|
||||
## 求解
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`=None
|
||||
+ `max`=None
|
||||
|
||||
**> host_solve formula=`formula` var=`var`**
|
||||
**> host_solve formula=`formula` var=`var` min=`min` max=`max`**
|
||||
|
||||
## 绘图
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`
|
||||
+ `max`
|
||||
+ `steps`=None
|
||||
+ `path`=None
|
||||
+ `derivative`=None
|
||||
+ `grid`=None
|
||||
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max` steps=`steps` path=`path` derivative=`derivative` grid=`grid`**
|
||||
|
||||
## 绘点列
|
||||
+ `xs`
|
||||
+ `ys`
|
||||
+ `path`=None
|
||||
+ `grid`=None
|
||||
|
||||
**> host_plot_points xs=`xs` ys=`ys`**
|
||||
**> host_plot_points xs=`xs` ys=`ys` path=`path` grid=`grid`**
|
||||
|
||||
## 绘圆锥
|
||||
+ `kind`
|
||||
+ `a`
|
||||
+ `b`=None
|
||||
+ `h`=None
|
||||
+ `k`=None
|
||||
+ `path`=None
|
||||
+ `grid`=None
|
||||
|
||||
**> host_plot_conic kind=`kind` a=`a`**
|
||||
**> host_plot_conic kind=`kind` a=`a` b=`b` h=`h` k=`k` path=`path` grid=`grid`**
|
||||
@@ -39,3 +39,20 @@ description: 中文文件系统包装
|
||||
+ `路径`
|
||||
|
||||
**> host_remove path=`路径`**
|
||||
|
||||
## 文本补丁
|
||||
+ `路径`
|
||||
+ `查找`
|
||||
+ `替换`
|
||||
|
||||
对 UTF-8 文本文件做精确 FIND→REPLACE(`查找` 必须唯一匹配一次)。
|
||||
|
||||
**> host_text_patch path=`路径` find=`查找` replace=`替换`**
|
||||
|
||||
## 应用补丁块
|
||||
+ `路径`
|
||||
+ `文本`
|
||||
|
||||
解析规划回复中的 `<<<` / FIND / === / REPLACE / `>>>` 块并应用到 `路径`。
|
||||
|
||||
**> host_apply_patch_blocks path=`路径` text=`文本`**
|
||||
+11
-2
@@ -15,10 +15,11 @@ description: 中文系统包装(加载环境 可选 路径=)
|
||||
**> host_env_set name=`名` value=`值`**
|
||||
|
||||
## 加载环境
|
||||
+ `路径`=None
|
||||
|
||||
加载 `.env`(可选具名实参 `路径=`)。不覆盖已有进程环境变量。
|
||||
|
||||
**> host_dotenv_load**
|
||||
**> host_dotenv_load path=`路径`**
|
||||
|
||||
## 参数表
|
||||
|
||||
@@ -35,5 +36,13 @@ description: 中文系统包装(加载环境 可选 路径=)
|
||||
|
||||
## 执行
|
||||
+ `命令`
|
||||
+ `参数`=None
|
||||
|
||||
**> host_exec cmd=`命令`**
|
||||
**> host_exec cmd=`命令` args=`参数`**
|
||||
|
||||
## 发布流事件
|
||||
+ `事件`
|
||||
|
||||
向进程内 EventBus 发布流事件(供 `marqdo view` SSE)。无订阅者时为空操作。
|
||||
|
||||
**> host_stream_publish event=`事件`**
|
||||
+28
-3
@@ -5,26 +5,51 @@ description: 中文 HTTP(S) 包装。可选 headers / content_type 经宿主别
|
||||
|
||||
## 获取
|
||||
+ `地址`
|
||||
+ `headers`=None
|
||||
|
||||
支持 HTTPS。可选具名实参 `headers=`(映射)。
|
||||
|
||||
**> host_http_get url=`地址`**
|
||||
**> host_http_get url=`地址` headers=`headers`**
|
||||
|
||||
## 提交
|
||||
+ `地址`
|
||||
+ `内容`
|
||||
+ `content_type`=None
|
||||
+ `headers`=None
|
||||
|
||||
默认 Content-Type 为 JSON。可选 `content_type=` / `headers=`。
|
||||
|
||||
**> host_http_post url=`地址` body=`内容`**
|
||||
**> host_http_post url=`地址` body=`内容` content_type=`content_type` headers=`headers`**
|
||||
|
||||
## 提交流式
|
||||
+ `地址`
|
||||
+ `内容`
|
||||
+ `content_type`=None
|
||||
+ `headers`=None
|
||||
+ `打印增量`=False
|
||||
|
||||
POST 并消费 OpenAI 兼容 SSE。返回 `{status, events}`(`delta` / `done` / `error`)。`打印增量=真` 时边读边打印增量文本。
|
||||
|
||||
**> host_http_post_sse url=`地址` body=`内容` content_type=`content_type` headers=`headers` echo=`打印增量`**
|
||||
|
||||
## 解析流式
|
||||
+ `内容`
|
||||
+ `打印增量`=False
|
||||
|
||||
离线解析 OpenAI 聊天 SSE 正文为事件列表(不联网)。
|
||||
|
||||
**> host_openai_sse_parse text=`内容` echo=`打印增量`**
|
||||
|
||||
## 请求
|
||||
+ `方法`
|
||||
+ `地址`
|
||||
+ `body`=None
|
||||
+ `content_type`=None
|
||||
+ `headers`=None
|
||||
|
||||
可选 `body=` / `content_type=` / `headers=`。
|
||||
|
||||
**> host_http_request method=`方法` url=`地址`**
|
||||
**> host_http_request method=`方法` url=`地址` body=`body` content_type=`content_type` headers=`headers`**
|
||||
|
||||
## 编码地址
|
||||
+ `内容`
|
||||
|
||||
+28
-6
@@ -6,25 +6,47 @@ description: 将运行结果写回 .mq.md(Jupyter 式自写回)
|
||||
## 写回
|
||||
+ `值`
|
||||
+ `末尾`=False
|
||||
+ `键`=None
|
||||
+ `行`=None
|
||||
|
||||
在入口文件中写入 `<!-- marqdo-out … -->`。默认在调用行下方插入或替换;`末尾=true` 时在文件末尾保留单块。
|
||||
在入口文件中写入 `<!-- marqdo-out … -->`。默认在调用行下方插入或替换;`末尾=true` 时替换无键末尾块。带 `键=`(如 `ok` / `error` / `成功` / `失败`)时只更新该命名槽,互不覆盖。可选 `行=` 锚定到指定源码行(子任务写回时需要)。
|
||||
|
||||
**> host_writeback_record value=`值` at_end=`末尾`**
|
||||
**> host_writeback_record value=`值` at_end=`末尾` key=`键` line=`行`**
|
||||
|
||||
## 取
|
||||
+ `末尾`=False
|
||||
+ `键`=None
|
||||
+ `行`=None
|
||||
|
||||
读取当前调用处紧邻块,或 `末尾=true` 时读取文件末尾块。
|
||||
读取当前调用处紧邻无键块、无键末尾块,或命名槽。
|
||||
|
||||
**> host_writeback_get at_end=`末尾`**
|
||||
**> host_writeback_get at_end=`末尾` key=`键` line=`行`**
|
||||
|
||||
## 清除
|
||||
+ `末尾`=False
|
||||
+ `键`=None
|
||||
+ `行`=None
|
||||
|
||||
删除紧邻块或末尾块。
|
||||
删除紧邻块、末尾块或命名槽。
|
||||
|
||||
**> host_writeback_clear at_end=`末尾`**
|
||||
**> host_writeback_clear at_end=`末尾` key=`键` line=`行`**
|
||||
|
||||
## 确保
|
||||
+ `键`
|
||||
+ `占位`=pending
|
||||
+ `行`=None
|
||||
|
||||
若命名槽不存在则创建并写入占位;已存在则不改动。
|
||||
|
||||
**> host_writeback_ensure key=`键` placeholder=`占位` line=`行`**
|
||||
|
||||
## 列出
|
||||
|
||||
**> host_writeback_list**
|
||||
|
||||
## 扫描路径
|
||||
+ `路径`
|
||||
|
||||
扫描任意文件中的 `<!-- marqdo-out … -->` 槽(工作簿观察)。
|
||||
|
||||
**> host_writeback_scan_path path=`路径`**
|
||||
+188
-1
@@ -1,15 +1,202 @@
|
||||
---
|
||||
title: lib/表
|
||||
description: 中文表库:行数 / 取行
|
||||
description: >-
|
||||
列表与字典。优先用「改」(路径 1-based,与脚注同构);取/改位/切片为 0-based。
|
||||
json 只管解析/序列化。
|
||||
---
|
||||
|
||||
## 改
|
||||
+ `入`
|
||||
+ `于`
|
||||
+ `值`
|
||||
|
||||
直接改某一元。`于=` 为文本键、**1-based** 下标,或键/下标组成的路径列表(与脚注嵌套同构)。
|
||||
|
||||
**> host_collection_put in=`入` at=`于` value=`值`**
|
||||
|
||||
## 长度
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
## 行数
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
## 取
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
下标从零起(与内置 `at` 相同)。越界 → `None`。
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
|
||||
## 取行
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
|
||||
## 追加
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_append list=`list` item=`item`**
|
||||
|
||||
## 前插
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_prepend list=`list` item=`item`**
|
||||
|
||||
## 拼接
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_list_concat a=`a` b=`b`**
|
||||
|
||||
## 插入
|
||||
+ `list`
|
||||
+ `index`
|
||||
+ `item`
|
||||
|
||||
下标从零起。
|
||||
|
||||
**> host_list_insert list=`list` index=`index` item=`item`**
|
||||
|
||||
## 改位
|
||||
+ `list`
|
||||
+ `index`
|
||||
+ `item`
|
||||
|
||||
从零起替换;日常嵌套改写请用「改」。
|
||||
|
||||
**> host_list_set_at list=`list` index=`index` item=`item`**
|
||||
|
||||
## 删位
|
||||
+ `list`
|
||||
+ `index`
|
||||
|
||||
**> host_list_remove_at list=`list` index=`index`**
|
||||
|
||||
## 弹出
|
||||
+ `list`
|
||||
|
||||
去掉末项(空表报错)。需要末值时先「末」。
|
||||
|
||||
*`n` = > len `list`*
|
||||
1. `n` > 0
|
||||
**> host_list_remove_at list=`list` index=`n` - 1**
|
||||
2. *
|
||||
**> host_list_remove_at list=`list` index=0**
|
||||
|
||||
## 首
|
||||
+ `list`
|
||||
|
||||
**> host_list_first list=`list`**
|
||||
|
||||
## 末
|
||||
+ `list`
|
||||
|
||||
**> host_list_last list=`list`**
|
||||
|
||||
## 切片
|
||||
+ `list`
|
||||
+ `start`
|
||||
+ `end`=None
|
||||
|
||||
从零起的半开区间,从 `start` 到 `end`。
|
||||
|
||||
**> host_list_slice list=`list` start=`start` end=`end`**
|
||||
|
||||
## 含有
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_contains list=`list` item=`item`**
|
||||
|
||||
## 下标
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
从零起的下标;没有 → `None`。
|
||||
|
||||
**> host_list_index_of list=`list` item=`item`**
|
||||
|
||||
## 反转
|
||||
+ `list`
|
||||
|
||||
**> host_list_reverse list=`list`**
|
||||
|
||||
## 清空
|
||||
+ `value`
|
||||
|
||||
**> host_collection_clear value=`value`**
|
||||
|
||||
## 取键
|
||||
+ `map`
|
||||
+ `key`
|
||||
|
||||
缺键 → `None`。
|
||||
|
||||
**> host_map_get map=`map` key=`key`**
|
||||
|
||||
## 设
|
||||
+ `map`
|
||||
+ `key`
|
||||
+ `value`
|
||||
|
||||
浅层设键;嵌套请用「改」。
|
||||
|
||||
**> host_map_set map=`map` key=`key` value=`value`**
|
||||
|
||||
## 删键
|
||||
+ `map`
|
||||
+ `key`
|
||||
|
||||
**> host_map_delete map=`map` key=`key`**
|
||||
|
||||
## 有键
|
||||
+ `map`
|
||||
+ `key`
|
||||
|
||||
**> host_map_has map=`map` key=`key`**
|
||||
|
||||
## 键表
|
||||
+ `map`
|
||||
|
||||
**> host_map_keys map=`map`**
|
||||
|
||||
## 值表
|
||||
+ `map`
|
||||
|
||||
**> host_map_values map=`map`**
|
||||
|
||||
## 项表
|
||||
+ `map`
|
||||
|
||||
键值对行表。
|
||||
|
||||
**> host_map_items map=`map`**
|
||||
|
||||
## 合并
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
右侧覆盖左侧。
|
||||
|
||||
**> host_map_merge a=`a` b=`b`**
|
||||
|
||||
## 键数
|
||||
+ `map`
|
||||
|
||||
**> host_map_size map=`map`**
|
||||
|
||||
## 空表
|
||||
|
||||
**> host_list_concat a=None b=None**
|
||||
|
||||
## 空字典
|
||||
|
||||
**> host_map_merge a=None b=None**
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: ext/agent plan live (DeepSeek)
|
||||
description: Full plan loop — spawn workbook, inspect; simple pong goal.
|
||||
> ext/ai/llm.mq.md
|
||||
> ext/ai/agent.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/fs.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`goal`=> input "你想完成什么任务?"*
|
||||
|
||||
> llm.load_env path=.env
|
||||
|
||||
*`model` = > llm.llm *
|
||||
*`tools` = > json.parse text=[] *
|
||||
*`助手` = > agent.agent model=`model` tools=`tools` standing=You are a Marqdo agent-development master. Prefer DONE when the workbook already satisfies the goal. *
|
||||
|
||||
流式开在 plan 上:非命中先 plan:decompose(父分解增量),再 plan:await(子 quiet),然后父修订轮。
|
||||
|
||||
*`out` = > `助手`.plan goal=`goal` max_rounds=3 writeback=False stream=True echo=True force=True *
|
||||
|
||||
*`result` = > json.get value=`out` key=result *
|
||||
> print text=`result`
|
||||
@@ -20,14 +20,14 @@ $$
|
||||
|
||||
> print text=`ty`
|
||||
|
||||
*`df` = > diff formula=`f` var=x *
|
||||
*`df` = > math.diff formula=`f` var=x *
|
||||
|
||||
> print text=`df`
|
||||
|
||||
*`roots` = > solve formula=`f` var=x *
|
||||
*`roots` = > math.solve formula=`f` var=x *
|
||||
|
||||
> print text=`roots`
|
||||
|
||||
*`y` = > eval formula=`f` var=x value=3 *
|
||||
*`y` = > math.eval formula=`f` var=x value=3 *
|
||||
|
||||
> print text=`y`
|
||||
Loaded 100 of 304 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user