Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
1e5e6f4891 | ||
|
|
4c37e79dae | ||
|
|
9a8545b725 | ||
|
|
ee3116513b | ||
|
|
729357b7c0 | ||
|
|
07ab7d52c6 | ||
|
|
d7be903297 | ||
|
|
d0b184939f | ||
|
|
c36383bf28 | ||
|
|
eba0d703c5 | ||
|
|
dfb27d41dc | ||
|
|
cf4dbdeade | ||
|
|
f3fe7f268e | ||
|
|
88fe076216 | ||
|
|
4956460773 | ||
|
|
eafa203205 | ||
|
|
7317a653c7 | ||
|
|
0fddc3bf05 | ||
|
|
724a22e48d | ||
|
|
6db3da1cc0 | ||
|
|
86bfb0648c | ||
|
|
c6360adccb | ||
|
|
2d51f29199 | ||
|
|
323449c2c3 | ||
|
|
6808d56c9d | ||
|
|
e3b0314382 | ||
|
|
a900fd550f | ||
|
|
034f52b7e7 | ||
|
|
e7c9c21a49 | ||
|
|
be6223f1fb | ||
|
|
da9fc75b1e | ||
|
|
7645dd4c1f | ||
|
|
7dfa161422 | ||
|
|
b84e82eb56 | ||
|
|
d7924ea8c7 | ||
|
|
bd5555afaa | ||
|
|
f275d1e030 | ||
|
|
1bf414c745 | ||
|
|
ecc92f473a | ||
|
|
56b9bfa5a3 | ||
|
|
209dc4fc5d | ||
|
|
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 | ||
|
|
2e65c055b8 | ||
|
|
3da7b276d3 | ||
|
|
63e5be80ab | ||
|
|
92d88fe761 | ||
|
|
c4ffb9473f | ||
|
|
3a7e11c995 | ||
|
|
b0c777c480 | ||
|
|
b00b018056 | ||
|
|
b974f10c6e | ||
|
|
72777a8c74 | ||
|
|
e08cd839be | ||
|
|
5309848292 | ||
|
|
1271aafcdd | ||
|
|
54a507d906 | ||
|
|
ea17ae1074 | ||
|
|
fe9046cecf | ||
|
|
b5e9d15391 | ||
|
|
dcd0cdb8f7 | ||
|
|
a53ebb65ee | ||
|
|
a5d30c00b3 | ||
|
|
fd36b92224 | ||
|
|
30cd39fd8f | ||
|
|
31a4b69bbd | ||
|
|
7848180454 | ||
|
|
69fecaeaab | ||
|
|
04098db74c | ||
|
|
96a7c6ce76 |
No files matched your search
@@ -0,0 +1,244 @@
|
||||
---
|
||||
name: marqdo
|
||||
description: >-
|
||||
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
|
||||
syntax (functions, calls, statements, returns, control flow). Use when writing
|
||||
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
|
||||
importing lib/* or ext/web or ext/quantum, running marqdo CLI, building dynamic
|
||||
sites with ext/web, quantum circuits with ext/quantum, or when the user
|
||||
mentions Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, or
|
||||
quantum/量子 extension.
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
|
||||
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
|
||||
|
||||
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
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` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
|
||||
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. 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. `# 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). **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 `import bind:path.mq.md` / `导入` | Import file (bind library name) |
|
||||
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` in function body | End function body (no value) |
|
||||
| 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 |
|
||||
|
||||
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
Chinese builtins (same functions, no import):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好
|
||||
```
|
||||
|
||||
## Functions, calls, end-body
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
- Call: `> name key=value` or `> name value`.
|
||||
- Nested helpers use deeper `#` (`##`, `###`, …).
|
||||
- After a helper with only side effects, end with `---` / `***`.
|
||||
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
```markdown
|
||||
*n = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. `n` < 0
|
||||
> print text=negative
|
||||
3. *
|
||||
> print text=zero
|
||||
```
|
||||
|
||||
## Frontmatter imports + stdlib
|
||||
|
||||
Imports use `import bind:target` (`导入` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: example
|
||||
import text:lib/text.mq.md
|
||||
import clock:lib/time.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*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 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.
|
||||
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (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)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz + Q8 themed SVG (see below).
|
||||
- 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).
|
||||
|
||||
## Official extension: `ext/web` (dynamic sites)
|
||||
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`.
|
||||
|
||||
Import **one language file** — never mix EN/ZH API names in the same `.mq.md`:
|
||||
|
||||
- EN: `import web:ext/web/web.mq.md`
|
||||
- ZH: `导入 网页:ext/web/网页.mq.md`
|
||||
|
||||
**Hard rules (web):**
|
||||
|
||||
- Authors use **GFM tables + `#` classes** — no `json.parse` / `json.set` glue, no hand-built part JSON.
|
||||
- Table cells stay **literal strings**; path text like `` `posts`.`title` `` is resolved by web classes.
|
||||
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI.
|
||||
- HTTPS: terminate at reverse proxy; set `cookie_secure=True` on auth (no in-process TLS).
|
||||
|
||||
**Typical layout:**
|
||||
|
||||
```text
|
||||
index.mq.md # entry + home page table + listen
|
||||
pages/ # sub-pages
|
||||
components/ # reusable |属性|值|样式| tables
|
||||
styles/ # CSS modules
|
||||
db/ # schema + open/init
|
||||
data/ # sqlite runtime (gitignore)
|
||||
```
|
||||
|
||||
**Core objects (EN / ZH):** `# page`/`页面`, `# style`/`样式`, `# db`/`数据库`, `# form`/`表单`, `# app`/`应用`, `# auth`/`鉴权`, `# cache`/`缓存`, `# storage`/`存储`.
|
||||
|
||||
**Typical flow:** `db.init` → `page.compose_components` + `page.compose_main` → `page.render` → `app` with `route` / `static` / `configure` / `listen`.
|
||||
|
||||
**Shipped surface (W0–W7 + P3):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads.
|
||||
|
||||
Design: [ext-web.md](../../doc/design/ext-web.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
|
||||
|
||||
Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md).
|
||||
|
||||
## Official extension: `ext/quantum` (circuits + Q7/Q8)
|
||||
|
||||
Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --release -p marqdo_plugin_quantum`, then **`marqdo ext add quantum` again** so view loads the new `libquantum.so` (stale plugin = old black/white circuits).
|
||||
|
||||
- EN: `import quantum:ext/quantum/quantum.mq.md`
|
||||
- ZH: `导入 量子:ext/quantum/量子.mq.md`
|
||||
|
||||
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; ≤12 qubits for statevector; density-matrix ops ≤6 qubits; one language file per program; quote draw string args (`kind="…"`, `theme="…"`).
|
||||
|
||||
**Core:** `# circuit` / `# gate` / `# density` — table `steps=` or method chain; `simulate` / `probabilities` / `run` / `draw`.
|
||||
|
||||
**Q7 linear algebra:** `density`, `partial_trace`, `eig`, `expect` (Pauli string, left=high bit), `purity`, `kron`, `schmidt`, `fidelity`.
|
||||
|
||||
**Draw kinds:** `circuit|probs|bloch|hinton|city|density|paulivec|qsphere|multibloch`.
|
||||
|
||||
**Q8 themes (circuit / probs / bloch):** `theme="dark"|"light"|"bw"` (ZH `主题=`; **default `dark`** — slate lab look, gate-family colors, label chips so wires never cross `q0` text). View plot chrome follows `data-theme` on the SVG. Advanced kinds (hinton/…) still Q8c pending full re-skin.
|
||||
|
||||
```markdown
|
||||
*_ = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*_ = > `qc`.draw kind="probs" theme="light"*
|
||||
```
|
||||
|
||||
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
2. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
3. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
4. On `path:line:col: message`, fix that span; re-run until exit 0.
|
||||
5. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
|
||||
## Anti-patterns (common model mistakes)
|
||||
|
||||
| Wrong | Right |
|
||||
|-------|-------|
|
||||
| `**Hello**` to print | `> print text=Hello` |
|
||||
| `# main` then prose then code with no blank line | Blank line before code |
|
||||
| `if x > 0:` | `1. `x` > 0` |
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
|
||||
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
|
||||
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
|
||||
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
|
||||
| `json.set` to build page parts | GFM tables + `page.compose_*` / `web.page` methods |
|
||||
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
|
||||
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
|
||||
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
|
||||
| Bare `kind=hinton` inside `*…*` | `kind="hinton"` — quote text literals |
|
||||
| Bare `theme=dark` inside `*…*` | `theme="dark"` — quote; ZH `主题="dark"` |
|
||||
| Rebuild plugin but skip `ext add` | `cargo build -p marqdo_plugin_quantum` then `marqdo ext add quantum` (or set `MARQDO_QUANTUM_PLUGIN`) |
|
||||
|
||||
## Checklist before finishing
|
||||
|
||||
- [ ] File ends with `.mq.md`
|
||||
- [ ] Print via `print` / `打印`, not bold
|
||||
- [ ] Blank lines separate comment paragraphs from code
|
||||
- [ ] `# main` exists when the file is an entry program
|
||||
- [ ] Nested functions ended with `---` / `***` / `****` when needed
|
||||
- [ ] Imports and call names share the same language file
|
||||
- [ ] Web sites: tables + web classes only (no JSON glue); `data/` gitignored
|
||||
- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view
|
||||
- [ ] `marqdo run` succeeds (or errors addressed)
|
||||
@@ -0,0 +1,302 @@
|
||||
# Marqdo examples (AI)
|
||||
|
||||
## 1. Hello (English)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
## 2. Hello (Chinese builtins)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
## 3. Function + named call + body end
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
Greeting via a nested function:
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## 4. Bindings and return
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*a = 2*
|
||||
*b = > add_one n=`a`*
|
||||
> print text=`b`
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
## 5. Branch with else
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*n = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. `n` < 0
|
||||
> print text=negative
|
||||
3. *
|
||||
> print text=zero
|
||||
```
|
||||
|
||||
## 6. Foreach loop
|
||||
|
||||
```markdown
|
||||
# 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
|
||||
---
|
||||
title: split demo
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*parts = > split value=a,b,c sep=,*
|
||||
> print text=`parts`
|
||||
```
|
||||
|
||||
## 8. Comment paragraphs (blank-line rule)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
This whole paragraph is a comment, including lines that look like code:
|
||||
*not_executed = 1*
|
||||
> print text=also still comment
|
||||
|
||||
After a blank line, code runs:
|
||||
|
||||
> print text=this runs
|
||||
```
|
||||
|
||||
## 9. Frontmatter import only
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: loads math
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*t = > num value=3.5*
|
||||
> print text=`t`
|
||||
```
|
||||
|
||||
## 10. Object handle + method
|
||||
|
||||
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
|
||||
---
|
||||
import agent:ext/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_native
|
||||
|
||||
*ws = > agent*
|
||||
*n = > `ws`.ensure_layout*
|
||||
> print text=`n`
|
||||
```
|
||||
|
||||
Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see `doc/design/ext-agent.md`).
|
||||
|
||||
## 12. What not to emit
|
||||
|
||||
```markdown
|
||||
# BAD — bold is return, not print
|
||||
**Hello**
|
||||
|
||||
# BAD — Python control keywords
|
||||
if x > 0:
|
||||
print(x)
|
||||
|
||||
# BAD — wrapping a call in italics
|
||||
*> print text=hi*
|
||||
|
||||
# BAD — old branch syntax (removed)
|
||||
+ `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
|
||||
```
|
||||
|
||||
## 13. Dynamic site (ext/web, minimal)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: hello-site
|
||||
import web:ext/web/web.mq.md
|
||||
import db:db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`shell` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav | |
|
||||
|
||||
`main` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| title | posts.title | |
|
||||
| body | posts.summary | |
|
||||
|
||||
*store = > db.open*
|
||||
*css = "body{font-family:sans-serif}"*
|
||||
*page = > web.page title="Hello"*
|
||||
*page = > page.compose_components components=`shell`*
|
||||
*page = > page.compose_main main=`main`*
|
||||
*page = > page.css css=`css`*
|
||||
*app = > web.app page=`page` port=8080*
|
||||
*app = > app.static prefix="/static" dir="static"*
|
||||
> listen app=`app`
|
||||
```
|
||||
|
||||
- Import `ext/web/web.mq.md` **or** `ext/web/网页.mq.md` — not both; match API language to the file.
|
||||
- Full blog/CMS patterns: `examples/marqdo-blog/` (routes, SEO, RSS, auth, upload, WS).
|
||||
- Run after `marqdo ext add web` and building `marqdo_plugin_web`.
|
||||
|
||||
## 14. Quantum entanglement lab (ext/quantum Q7/Q8)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`steps` =
|
||||
|
||||
| step | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
*qc = > quantum.circuit qubits=2 steps=`steps`*
|
||||
*rho = > `qc`.density*
|
||||
*red = > `rho`.partial_trace keep=0*
|
||||
*sch = > `qc`.schmidt cut=1*
|
||||
*_ = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*_ = > `qc`.draw kind="hinton"*
|
||||
> print text=`red`
|
||||
```
|
||||
|
||||
- Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`.
|
||||
- `theme="dark"|"light"|"bw"` (default dark) on `circuit` / `probs` / `bloch`. Quote `kind=` / `theme=`.
|
||||
- After rebuilding the plugin: `marqdo ext add quantum` so view loads the new native lib.
|
||||
@@ -0,0 +1,180 @@
|
||||
# Marqdo reference (AI)
|
||||
|
||||
Load this when you need stdlib names, CLI, or edge cases. Core rules stay in [SKILL.md](SKILL.md).
|
||||
|
||||
## CLI
|
||||
|
||||
```text
|
||||
marqdo --version
|
||||
marqdo run FILE.mq.md
|
||||
marqdo run FILE.mq.md --backend bytecode
|
||||
marqdo view PATH # docs browser, default port 7429
|
||||
marqdo debug PATH # debugger UI, default port 7430
|
||||
marqdo catalog PATH -o .marqdo
|
||||
marqdo ext list
|
||||
marqdo ext add llm|agent|web|quantum
|
||||
marqdo ext remove llm|agent|web|quantum
|
||||
```
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
|
||||
**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.
|
||||
|
||||
官方扩展(`ext/…`,非 stdlib):`marqdo ext add` 装到 `MARQDO_EXT` 或 `~/.marqdo/ext`;导入仍写 `import llm:ext/llm.mq.md`。解析还含 cwd `ext/`、二进制旁 `ext/`。对象:`doc/design/objects.md`。Agent:`doc/design/ext-agent.md` · 安装器:`doc/design/ext-cli.md`。
|
||||
|
||||
## Builtins (no import)
|
||||
|
||||
| EN | ZH | Role |
|
||||
|----|----|------|
|
||||
| `print` | `打印` | stdout; arg `text` / `内容` |
|
||||
| `input` | `输入` | one line; arg `prompt` / `提示` |
|
||||
| `len` | `长度` | length; arg `value` / `值` |
|
||||
| `str` | `文本` | to text; arg `value` / `值` |
|
||||
| `int` | `整数` | to int; arg `value` / `值` |
|
||||
|
||||
Keywords (not variable names): `True`/`真`, `False`/`假`, `None`/`空`, `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
## Standard library files
|
||||
|
||||
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` | `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`) |
|
||||
| `lib/time.mq.md` | `lib/时间.mq.md` | time/format |
|
||||
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) helpers (+ optional headers) |
|
||||
| `lib/json.mq.md` | (see design) | JSON (+ `quote`) |
|
||||
| `lib/math.mq.md` | `lib/数学.mq.md` | num, trig, random, formula, plot |
|
||||
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
|
||||
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
|
||||
| `ext/agent.mq.md` | `ext/智能体.mq.md` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.md`) |
|
||||
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
|
||||
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
|
||||
|
||||
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
|
||||
|
||||
## ext/web (dynamic sites)
|
||||
|
||||
Install: `marqdo ext add web` (`网页`). Native: `cargo build --release -p marqdo_plugin_web`.
|
||||
|
||||
| EN import | ZH import | Core types |
|
||||
|-----------|-----------|------------|
|
||||
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | `# page` `# style` `# db` `# form` `# app` `# auth` `# cache` `# storage` |
|
||||
|
||||
| Area | EN methods (representative) | Notes |
|
||||
|------|----------------------------|-------|
|
||||
| Page | `compose_components`, `compose_main`, `render`, `meta`, `paginate` | GFM tables; cells are literal path strings |
|
||||
| DB | `init`, `insert`, `select`, `paginate`, `get`, `update`, `delete`, `migrate`, `fts`, `search`, `count`, `事务`/`txn` | init supports `unique`/`index`/`fk`; auto `created_at`/`updated_at` |
|
||||
| App | `route`, `static`, `configure`, `listen`, `auth`, `gate`, `upload`, `download`, `gallery`, `route_rss`, `redirect`, `error_page`, `sitemap`, `robots` | W0–W7 + P3 complete |
|
||||
| Auth | `login`, `check`, `logout`, `hash_password` | argon2 + CSRF + SQLite sessions; `role` for RBAC |
|
||||
|
||||
Drivers (Postgres / Redis / S3): `db url=postgres://…`, `cache url=memory:`, `storage url=file:…` — see `doc/design/ext-web-drivers.md`.
|
||||
|
||||
Example project: `examples/marqdo-blog/`. Capability matrix: `doc/design/web-net-capabilities.md`.
|
||||
|
||||
## ext/quantum (circuits + Q7/Q8)
|
||||
|
||||
Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p marqdo_plugin_quantum`, then re-run `ext add` so view picks up the new `.so`.
|
||||
|
||||
| EN import | ZH import | Core types |
|
||||
|-----------|-----------|------------|
|
||||
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | `# circuit` `# gate` `# density` |
|
||||
|
||||
| Area | EN APIs | Notes |
|
||||
|------|---------|-------|
|
||||
| Circuit | `h`/`cx`/…, `simulate`, `probabilities`, `run`, `draw`, `noise` | `steps=` GFM table; ≤12 qubits |
|
||||
| Gate | `matrix`, `matches_matrix`, `draw` | named or `matrix=` custom unitary |
|
||||
| Density (Q7) | `purity`, `partial_trace`, `eig`, `expect`, `draw` | ≤6 qubits for dense ρ |
|
||||
| Free (Q7) | `kron`, `schmidt`, `fidelity` | top-level on import bind |
|
||||
| Draw kinds | `circuit\|probs\|bloch\|hinton\|city\|density\|paulivec\|qsphere\|multibloch` | quote `kind="…"` |
|
||||
| Themes (Q8) | `theme="dark"\|"light"\|"bw"` (ZH `主题=`) | default **dark**; circuit/probs/bloch themed; SVG `data-theme` |
|
||||
|
||||
Examples: `examples/quantum-bell/`, `examples/quantum-entanglement/`. Design: `doc/design/ext-quantum.md` · Q7: `doc/design/ext-quantum-q7.md` · Q8: `doc/design/ext-quantum-viz-style.md`.
|
||||
|
||||
## Formula + plot (math)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*_svg = > plot formula=`f` var=x min=-3 max=3*
|
||||
```
|
||||
|
||||
Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only `$$` without binding is display, not assignment.
|
||||
|
||||
## Foreign (Python example)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
```
|
||||
|
||||
Lines starting with `` ` `` can be code (binding). Keep a blank line before/after fences per comment rules.
|
||||
|
||||
## Function-end details
|
||||
|
||||
| Form | Effect |
|
||||
|------|--------|
|
||||
| Lone `---` or `***` (≥3 same chars) at function body top level | End function; no return value |
|
||||
| `****` or empty bold | Return `None` and end body |
|
||||
| `**expr**` | Return `expr`; does **not** by itself cut off later sibling statements — still use HR or shallower heading |
|
||||
|
||||
File-leading paired `---` is frontmatter only; body `---` is not frontmatter.
|
||||
|
||||
## Call arguments
|
||||
|
||||
- Named: `> greet who=World`
|
||||
- Positional: `> greet World`
|
||||
- Spaces in values: allowed in named forms as in docs (`who=marqdo user`)
|
||||
- Inline call in statement: `` *`n` = > len value=`s`* ``
|
||||
|
||||
See `doc/design/call-arguments.md`.
|
||||
|
||||
## Identifiers
|
||||
|
||||
- Variables: `` `name` ``
|
||||
- Comparisons: `==` `>` `<` `>=` `<=`
|
||||
- Do not use keyword tokens as names
|
||||
|
||||
## Design docs (repo)
|
||||
|
||||
| Doc | Topic |
|
||||
|-----|--------|
|
||||
| `doc/design/markdown-mapping.md` | Syntax constitution |
|
||||
| `doc/design/objects.md` | `#` objects / `##` methods |
|
||||
| `doc/design/keywords.md` | Builtins / keywords |
|
||||
| `doc/design/return-hr-and-code-surface.md` | Function end / surfaces |
|
||||
| `doc/design/stdlib-i18n.md` | EN/ZH lib files |
|
||||
| `doc/design/stdlib-modules.md` | L1 modules including plugin |
|
||||
| `doc/design/ext-abi.md` | Native C ABI v1 |
|
||||
| `doc/design/ext-llm.md` | `ext/llm` |
|
||||
| `doc/design/ext-agent.md` | `ext/agent` agent **framework** (layout shipped; LLM orchestration roadmap) |
|
||||
| `doc/design/ext-cli.md` | `marqdo ext list/add/remove` |
|
||||
| `doc/design/ext-web.md` | `ext/web` dynamic sites (author API) |
|
||||
| `doc/design/web-net-capabilities.md` | ext/web capability matrix (W0–W7 + P3) |
|
||||
| `doc/design/ext-quantum.md` | `ext/quantum` circuits |
|
||||
| `doc/design/ext-quantum-q7.md` | Q7 density linear algebra + advanced SVG |
|
||||
| `doc/design/ext-quantum-viz-style.md` | Q8 themed SVG (`dark`/`light`/`bw`; circuit/probs/bloch) |
|
||||
| `doc/design/view-debug.md` | view / debug hosts |
|
||||
@@ -0,0 +1,48 @@
|
||||
# Build public/ with marqdo and publish to the gh-pages branch.
|
||||
name: User docs site
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, master]
|
||||
paths:
|
||||
- "public/**"
|
||||
- "src/**"
|
||||
- "Cargo.toml"
|
||||
- "Cargo.lock"
|
||||
- ".github/workflows/pages.yml"
|
||||
- "scripts/build-public.*"
|
||||
- "scripts/run-public-pages.sh"
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
build-and-deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Build & export site
|
||||
shell: bash
|
||||
run: bash scripts/run-public-pages.sh
|
||||
|
||||
- name: Verify site shape
|
||||
run: |
|
||||
if grep -R "tests/errors" public --include='*.html' ; then
|
||||
echo "user site must not include tests/errors fixtures" >&2
|
||||
exit 1
|
||||
fi
|
||||
test -f public/index.html
|
||||
test -f public/00-welcome.mq.md
|
||||
|
||||
- name: Deploy to gh-pages
|
||||
uses: peaceiris/actions-gh-pages@v4
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./public
|
||||
publish_branch: gh-pages
|
||||
force_orphan: true
|
||||
@@ -0,0 +1,128 @@
|
||||
# Build and attach release binaries when a version tag is pushed.
|
||||
name: Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "v*"
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
windows:
|
||||
runs-on: windows-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Install Node (VS Code extension)
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "20"
|
||||
|
||||
- name: Build release
|
||||
run: cargo build --release
|
||||
|
||||
- name: Checkout extension sources (branch vscode-extension only)
|
||||
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
|
||||
|
||||
- name: Build VSIX
|
||||
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
|
||||
npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-$ver.vsix"
|
||||
Pop-Location
|
||||
|
||||
- name: Package
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ver = "${{ github.ref_name }}".TrimStart("v")
|
||||
$target = "x86_64-pc-windows-msvc"
|
||||
New-Item -ItemType Directory -Force -Path dist | Out-Null
|
||||
$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
|
||||
Copy-Item target/release/marqdo.exe "$stage/marqdo.exe"
|
||||
Copy-Item lib "$stage/lib" -Recurse
|
||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
||||
$stageLib = "dist/stage-stdlib"
|
||||
if (Test-Path $stageLib) { Remove-Item $stageLib -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stageLib | Out-Null
|
||||
Copy-Item lib "$stageLib/lib" -Recurse
|
||||
if (Test-Path "dist/$stdlib") { Remove-Item "dist/$stdlib" -Force }
|
||||
Compress-Archive -Path "$stageLib/*" -DestinationPath "dist/$stdlib" -Force
|
||||
echo "EXE=$exe" >> $env:GITHUB_ENV
|
||||
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
|
||||
with:
|
||||
body: |
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### Highlights — v0.3
|
||||
- **`ext/web`**: W0–W7 + P3 complete (sessions, cache, upload, WebSocket, style assembly); see marqdo-blog
|
||||
- **`ext/quantum`**: Q7 linalg + Q8 themed SVG viz
|
||||
- **`ext/agent`**: A1–A4 (OKF reuse, events, context budget, RAG/MCP fixtures)
|
||||
- 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) · [README](https://github.com/cflmy/marqdo/blob/main/README.md)
|
||||
|
||||
Also: embedded stdlib, writeback/subtask, Variables modal in `view`, VSIX from branch **`vscode-extension`**.
|
||||
|
||||
### Downloads
|
||||
|
||||
| Asset | Contents |
|
||||
|-------|----------|
|
||||
| `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: [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 }}
|
||||
+49
@@ -1,9 +1,36 @@
|
||||
/target/
|
||||
/dist/
|
||||
|
||||
# Copied by gold harness for ABI plugins
|
||||
/tests/lib/demo.dll
|
||||
/tests/lib/libdemo.so
|
||||
/tests/lib/libdemo.dylib
|
||||
/tests/ext/agent.dll
|
||||
/tests/ext/libagent.so
|
||||
/tests/ext/libagent.dylib
|
||||
/tests/ext/skel.mq.md
|
||||
/tests/ext/out-demo.mq.md
|
||||
/tests/ext/ticket.txt
|
||||
/tests/ext/ticket-stub.txt
|
||||
/tests/ext/agents/
|
||||
/tests/ext/runbooks/
|
||||
/tests/ext/templates/
|
||||
/tests/ext/reports/
|
||||
**/*.rs.bk
|
||||
.idea/
|
||||
.vscode/
|
||||
*.pdb
|
||||
.DS_Store
|
||||
.marqdo/
|
||||
**/.marqdo/
|
||||
.env
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
/public/index.html
|
||||
/public/pages/
|
||||
|
||||
# VS Code extension: source only on branch `vscode-extension` (see doc/design/vscode-extension-commit.md)
|
||||
/vscode-extension/
|
||||
|
||||
# Python spike venv (local)
|
||||
spike/.venv/
|
||||
@@ -11,3 +38,25 @@ 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/
|
||||
/tests/ext/entrydir-fixtures/data/
|
||||
/examples/web-site/data/
|
||||
/examples/web-site-zh/data/
|
||||
/examples/web-net-site/data/
|
||||
/examples/web-net-site-zh/data/
|
||||
/examples/marqdo-blog/data/
|
||||
|
||||
# Quantum draw/SVG runtime outputs (sources & gold .mq.md stay tracked)
|
||||
/tests/ext/quantum-*.svg
|
||||
/examples/quantum-*/**/*.svg
|
||||
/examples/quantum-*/*.svg
|
||||
|
||||
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
|
||||
/ext/native/
|
||||
+128
@@ -0,0 +1,128 @@
|
||||
# Changelog
|
||||
|
||||
## Unreleased
|
||||
|
||||
## v0.3.0 — 2026-08-29
|
||||
|
||||
### Highlights
|
||||
|
||||
本版把 **`ext/web` 网络能力(W0–W7 + P3)**、**`ext/quantum` Q7/Q8**、**`ext/agent` A1–A4** 一并收口到正式发布;并修了网页扩展叙述行误解析、补充 ASGI/生产部署说明与 agent 下一波(B0–B5)缺口调研。
|
||||
|
||||
**如何拿到本版**
|
||||
|
||||
```bash
|
||||
# 从源码(推荐跟 main / 本 tag)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v0.3.0
|
||||
cargo build --release
|
||||
./target/release/marqdo version
|
||||
|
||||
# 或从 GitHub Releases 下载 Windows 包 / 源码 zip(见 Release 资产)
|
||||
marqdo version --check
|
||||
```
|
||||
|
||||
**扩展(非 stdlib)**
|
||||
|
||||
```bash
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
|
||||
marqdo ext add web && marqdo ext add agent && marqdo ext add quantum
|
||||
# 中文 id:网页 / 智能体 / 量子 / 大模型
|
||||
```
|
||||
|
||||
### Added
|
||||
- **调研:`ext/agent` A0–A4 之后缺口** ([agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)):产品化示例、评测 harness、真 MCP、plan resume/HITL、飞轮指标与建议分期 B0–B5;挂到 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md) 与 [doc/README.md](doc/README.md)。
|
||||
- **生产部署调研(ASGI)** ([web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)):不能挂 Daphne/Uvicorn;路径为反向代理 → 嵌入式 `listen`(axum)。
|
||||
- **`ext/agent` A4(RAG/MCP 证据工具)**: `corpus_search` 本地语料关键词检索;`mcp_list_tools` / `mcp_call` 读 JSON fixture;返回 `authority=workbook`。金样 `agent-tools-rag-a4`。
|
||||
- **`ext/agent` A3(上下文预算)**: `source_brief` / 加深版 `skill_brief`;`build_step_context` 默认截断并提示 `READ:source|skill`;`step` 支持最多 `max_reads` 次加深;父 `READ:skill`。金样 `agent-context-budget-a3`。
|
||||
- **`ext/agent` A2(过程可见)**: `plan` 过程事件默认写入返回 map 的 `events`(SSE 仍仅 `stream=True`);OKF 命中记 `REUSE` decision;view plan 卡渲染过程时间线。对齐 [agent-streaming.md](doc/roadmap/agent-streaming.md)。
|
||||
- **`ext/agent` A1(OKF 复用飞轮)**: `agent_kb_list_tasks` 返回 description/aliases/status/llm_free/hits;`plan` 命中路径暴露 `match`/`score`(summary 含 match kind);soft_match 策展提示带 status/llm_free/description;view plan 卡显示 match。金样 `agent-kb-plan-hit`。路线 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md)。
|
||||
- **`ext/web` 样式装配(`web_style` / `网页.样式装配`)**: 样式即数据表格 —— GFM 样式表(`|选择器|属性|值|`,可用 `|媒体|` 列分组进 `@media` 块)经 `样式装配` 函数转成 CSS 文本,再拼装成完整主题。替代"整段手写 CSS 字符串"的写法,贯彻 文档即代码。见 [marqdo-blog](examples/marqdo-blog/styles/theme.mq.md)。
|
||||
- **网络能力调研(`doc/design/web-net-capabilities.md`)**: 盘点 `ext/web` + `plugins/web` + `lib/net` 现状,对照主流语言网络栈(FastAPI / Express / Flask / axum),给出「开发一个完整 Web 项目」所需能力的差距清单与分波次补强路线(W1–W7 + P3,**2026-08-28 已全部落地**)。
|
||||
- **AI Skill + 文档(ext/web 完结复核)**: `skills/marqdo/` 与 `.cursor/skills/marqdo/` 增加 **ext/web 动态站** 专节(硬规则、API 摘要、§13 最小站点样例);`doc/design/web-net-capabilities.md` 结论/对照表与 W7+P3 实现对齐;`doc/design/ai-skill.md` 更新用途说明。
|
||||
- **`ext/quantum` Q7(高阶线性代数 + 高级可视化)**: 密度矩阵 / 部分迹 / Hermitian 谱 / Schmidt / Pauli 期望 / 纯度;SVG:hinton、city、density、paulivec、qsphere、multibloch。全部经 `plugins/quantum` ABI。设计 [ext-quantum-q7.md](doc/design/ext-quantum-q7.md);金样 `quantum-linalg-smoke`、`quantum-viz-advanced-smoke`;示例 [quantum-entanglement](examples/quantum-entanglement/)。
|
||||
- **`ext/quantum` Q8a/Q8b(可视化美学)**: `draw theme=dark|light|bw`(默认 dark);标签芯片 + gutter 消除线穿字;门族分色;probs/bloch 共用令牌;view 对 `data-theme` 换图框。设计 [ext-quantum-viz-style.md](doc/design/ext-quantum-viz-style.md)。改插件后须 `marqdo ext add quantum` 再开 view。
|
||||
|
||||
### Fixed
|
||||
- **`ext/web` / `网页.mq.md`**:叙述行勿以反引号开头,避免被解析为语句(`examples/marqdo-blog` 可正常 `listen`)。
|
||||
|
||||
### Changed
|
||||
- **Frontmatter import syntax**: `import bind:target` / `导入 bind:target` (file `.mq.md` or short name `lib.member`). Removed legacy `> path.mq.md` / `> use` imports. See [module-namespace.md](doc/design/module-namespace.md).
|
||||
|
||||
## 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
|
||||
- **Embedded standard library**: official `lib/*.mq.md` ships inside the `marqdo` binary; disk `lib/` and `MARQDO_LIB` still override.
|
||||
- **`lib/writeback`** / **`lib/subtask`**: Jupyter-style writeback; concurrent subtasks (file / function / foreign).
|
||||
- **Surface syntax v0.2**: `` + `param` `` parameters, `1.` ordered branches, backtick identifiers, quoted strings.
|
||||
- **`marqdo version --check`**: compare installed CLI with latest GitHub release.
|
||||
- **VS Code extension v0.0.6** (branch **`vscode-extension` only**): v0.2 grammar, update check — see [doc/design/vscode-extension-commit.md](doc/design/vscode-extension-commit.md)
|
||||
|
||||
### Changed
|
||||
- Subtask `spawn` accepts `path=`, `fn=`, `code=`, or `lang=`+`source=` (not file-only).
|
||||
- Release notes: standalone `.exe` includes stdlib; bundle/stdlib zips remain optional for overrides.
|
||||
|
||||
## v0.1.1
|
||||
|
||||
- v0.2 syntax migration, writeback/subtask v1 (file subprocess only), view input deferral, optional parameters.
|
||||
|
||||
## v0.1.0
|
||||
|
||||
- Initial public releases: tree + bytecode backends, `view` / `debug` / `catalog`, core stdlib, `ext/` installer.
|
||||
Generated
+2122
-8
File diff suppressed because it is too large.
Load diff
+18
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.0.1"
|
||||
version = "0.3.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -13,10 +13,27 @@ path = "src/main.rs"
|
||||
|
||||
[dependencies]
|
||||
anyhow = "1"
|
||||
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
|
||||
clap = { version = "=4.4.18", features = ["derive"] }
|
||||
pulldown-cmark = "0.12"
|
||||
serde_json = "1"
|
||||
thiserror = "1"
|
||||
tiny_http = "0.12"
|
||||
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"] }
|
||||
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", "plugins/web", "plugins/quantum"]
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
assert_cmd = "=2.0.14"
|
||||
predicates = "=3.1.0"
|
||||
tokio = { version = "1", features = ["rt-multi-thread", "macros", "time", "net"] }
|
||||
tokio-tungstenite = "0.24"
|
||||
futures-util = "0.3"
|
||||
@@ -1,67 +1,169 @@
|
||||
# Marqdo
|
||||
|
||||
**代码即文档。文档即代码。**
|
||||
**代码即文档。文档即代码。文档即知识库。**
|
||||
|
||||
Marqdo:Markdown **标记即语法**。源文件 `.mq.md` 既是文稿也是程序。
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 示例布局:[examples-and-tests.md](doc/design/examples-and-tests.md) · 浏览:[view.md](doc/design/view.md) · 示例:[examples/](examples/)
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.1)
|
||||
## 为什么重要
|
||||
|
||||
| 痛点 | Marqdo 的答案 |
|
||||
|------|----------------|
|
||||
| 文档过期、示例跑不通 | **一份源文件**:叙述、结构与执行结果同源 |
|
||||
| 知识散落在 Wiki / 注释 / 脚本里 | **`.mq.md` 即知识单元**,可浏览、可运行、可检索 |
|
||||
| 人写给人看,AI / 工具另起一套 | **人机同读同写同构**:标记语言对人类友好,对解释器确定 |
|
||||
| 大仓里「文档站」与「代码仓」脱节 | `view` 文档站 + `debug` 调试面 + `catalog` 清单,同一棵树长大 |
|
||||
|
||||
这不是「再做一个 Markdown 渲染器」,而是:**把文档升格为可解释的程序与可生长的知识库**,让协作在大型项目里依然站得住。
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.2)
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| 无标记行 | 注释 |
|
||||
| 无标记行 | 注释(空行分段) |
|
||||
| `*…*` | 程序语句 |
|
||||
| `**…**` | **返回值**(架构) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||||
| `#` / `##` | 函数与作用域 |
|
||||
| `+` / `1.` | 分支(臂头单独 `*` = else) |
|
||||
| `-` | 循环(头下纯名则为形参) |
|
||||
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
|
||||
| `##` … | 函数 / 方法(按标题深度嵌套) |
|
||||
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
|
||||
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) `` / `` - [`项`](`集合`) ``) |
|
||||
| 表格 | 集合 |
|
||||
| `---` / `***` | 可选:框住分支/循环(不强制) |
|
||||
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
|
||||
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
---
|
||||
|
||||
## 加一
|
||||
- n
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
|
||||
|
||||
---
|
||||
|
||||
## 理念
|
||||
|
||||
1. 叙述默认安全(无标记 = 注释)。
|
||||
2. 返回是架构;打印只是函数。
|
||||
3. 依赖清单由工具生成(OKF 风格),不是手填配置。
|
||||
4. **正经解释器(Rust)**:词法/行分类 → 递归下降语法 → 语义 → 树遍历 → 日后字节码;**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md) 与 [依赖说明](doc/design/dependencies.md)。
|
||||
1. **叙述默认安全**(无标记 = 注释)。
|
||||
2. **返回是架构;打印只是函数。**
|
||||
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
|
||||
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||||
|
||||
---
|
||||
|
||||
## 现状
|
||||
## OKF 风格清单(自动生成)
|
||||
|
||||
- 映射 v0.1:[markdown-mapping.md](doc/design/markdown-mapping.md)
|
||||
- 解释器路线图:[interpreter.md](doc/roadmap/interpreter.md)
|
||||
- **Phase I(树遍历)已通**:`examples/structure/` 与 `examples/keywords/` 金样例均可 `marqdo run`
|
||||
- **view**:`marqdo view examples` 按 AST 浏览结构与输出
|
||||
- 依赖(Rust,无 Flex/Bison):[dependencies.md](doc/design/dependencies.md)
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
||||
从源码派生 YAML / Markdown 知识包(勿手改生成物):
|
||||
|
||||
```bash
|
||||
cargo run -- run examples/structure/hello.mq.md
|
||||
cargo run -- run examples/structure/hello.mq.md --backend bytecode
|
||||
cargo run -- view examples --no-open
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
```
|
||||
|
||||
当前发布:**v0.0.1**(Phase I 树遍历 + `view` + M5 字节码原型)。M5 见 [bytecode.md](doc/design/bytecode.md);errors 见 `examples/errors/`。
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
|
||||
| `-o` / `--out` | `.marqdo` | 输出目录 |
|
||||
|
||||
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||||
|
||||
智能体框架横向调研(LangGraph / CrewAI / 厂商 SDK 等 vs Marqdo 文档驱动优势):[agent-frameworks-and-marqdo.md](doc/research/agent-frameworks-and-marqdo.md) · 优化路线 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md)。
|
||||
|
||||
```bash
|
||||
cargo run -- catalog public -o .marqdo
|
||||
# 或已安装二进制时:
|
||||
marqdo catalog public -o .marqdo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.3.0)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`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,本版收口):
|
||||
- **`web`**:W0–W7 + P3 完结(会话 / 缓存 / 上传 / WebSocket / 样式装配等);示例 [marqdo-blog](examples/marqdo-blog/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)(反向代理 → 嵌入式 `listen`,非 Daphne/Uvicorn)
|
||||
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
|
||||
- **`agent`**:A1–A4(OKF 复用、过程事件、上下文预算、RAG/MCP fixture);下一波缺口 [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
|
||||
- **`llm`**:OpenAI 兼容对话
|
||||
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
|
||||
- **原生插件 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)
|
||||
|
||||
### 如何使用最新 Marqdo(v0.3.0)
|
||||
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v0.3.0 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
marqdo version --check
|
||||
|
||||
# 2) 跑解释器 / 文档站 / catalog
|
||||
marqdo run tests/structure/hello.mq.md
|
||||
marqdo run tests/structure/hello.mq.md --backend bytecode
|
||||
marqdo view public --no-open
|
||||
marqdo debug public --no-open
|
||||
marqdo catalog public -o .marqdo
|
||||
|
||||
# 3) 安装官方扩展(需先编原生插件)
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
|
||||
marqdo ext add web # 或:网页
|
||||
marqdo ext add agent # 或:智能体
|
||||
marqdo ext add quantum # 或:量子
|
||||
marqdo ext add llm # 或:大模型
|
||||
|
||||
# 4) 动态站示例(扩展装好后)
|
||||
marqdo run examples/marqdo-blog/index.mq.md
|
||||
# 浏览器打开终端打印的 listen 地址
|
||||
|
||||
# 5) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v0.3.0
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
```bash
|
||||
cargo run -- run tests/structure/hello.mq.md
|
||||
cargo run -- view public --no-open
|
||||
cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`import …:lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add …` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md) · 变更 [CHANGELOG.md](CHANGELOG.md)
|
||||
---
|
||||
|
||||
## 命名
|
||||
|
||||
+38
-5
@@ -16,23 +16,56 @@
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.1 语法宪法** |
|
||||
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
|
||||
| [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) | **英文最小关键字 / 内置 `print` `input`** |
|
||||
| [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/网络/数学/外联/插件** |
|
||||
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
|
||||
| [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`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 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/web-asgi-servers-and-marqdo.md](design/web-asgi-servers-and-marqdo.md) | **Daphne/Uvicorn 等 vs Marqdo**:不能直接托管;反代 + axum `listen` |
|
||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **示例即金样例目录布局** |
|
||||
| [design/view.md](design/view.md) | **`marqdo view` 源结构浏览器** |
|
||||
| [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/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/`)** |
|
||||
| [design/bytecode.md](design/bytecode.md) | **M5 字节码 / 双后端** |
|
||||
| [design/pipeline-debug.md](design/pipeline-debug.md) | **流水线 `--dump-*` 可视调试** |
|
||||
| [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 调研 |
|
||||
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点**(产品化 / 评测 / MCP / resume) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` 深入优化 A0–A4**(已完成) |
|
||||
|
||||
示例与验收集:[`examples/`](../examples/)。Spike 存档:[`spike/`](../spike/)。
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
## 写作原则
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@
|
||||
## 后果
|
||||
|
||||
- 正式代码以 Cargo 工程生长;不把 Flex/Bison/LLVM 列入 v1 依赖。
|
||||
- 金样例仍为 `examples/`;行为与宪法一致。
|
||||
- 金样例仍为 `tests/`;行为与宪法一致。
|
||||
- 此前「Python 作参考实现」的倾向由本修订取代;Spike 结论(行扫描等)仍然有效并迁入 Rust。
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# Marqdo AI Skill
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已提供 |
|
||||
| 日期 | 2026-08-05(初版)· 2026-08-28(ext/web 完结复核 · ext/quantum Q8) |
|
||||
| 路径 | [`skills/marqdo/`](../../skills/marqdo/)(权威);Cursor 镜像 [`.cursor/skills/marqdo/`](../../.cursor/skills/marqdo/) |
|
||||
|
||||
---
|
||||
|
||||
## 目的
|
||||
|
||||
让接入方(Cursor Agent、其它支持 Agent Skills 的模型宿主)在**加载本 skill 后**即可按 v0.2 语法正确编写 / 修改 `.mq.md`,并在使用 **`ext/web` 动态站** 或 **`ext/quantum` 电路/可视化** 时遵循官方作者面(不混中英 API、不写 JSON 袋胶水;量子绘图须引用 `kind=`/`theme=` 字符串)。
|
||||
|
||||
## 内容
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `SKILL.md` | 必读:硬规则、标记表、**ext/web**、**ext/quantum(Q7/Q8)**、工作流、反模式 |
|
||||
| `reference.md` | 按需:CLI、stdlib/ext 索引、web/quantum API 摘要 |
|
||||
| `examples.md` | 按需:可复制样例(§13 最小站点 · §14 纠缠实验) |
|
||||
|
||||
## 使用
|
||||
|
||||
- **本仓库 Cursor**:项目 skill 已在 `.cursor/skills/marqdo/`;描述含 `.mq.md` / Marqdo 触发词,可自动选用。
|
||||
- **其它 AI**:将 `skills/marqdo/` 整目录作为 skill 包导入,或把 `SKILL.md` 贴进系统/项目说明并允许模型按需打开 `reference.md` / `examples.md`。
|
||||
- **校验**:生成后执行 `marqdo run <file>.mq.md`,按 `path:line:col` 诊断迭代。
|
||||
|
||||
语法真相仍以 [markdown-mapping.md](markdown-mapping.md) 与 [keywords.md](keywords.md) 为准;skill 是面向模型的压缩操作手册。
|
||||
@@ -67,8 +67,9 @@
|
||||
| `keywords/bool-logic` | ✅ | ✅ |
|
||||
| `structure/nested-call` | ✅ | ✅ |
|
||||
| `structure/positional-call` | ✅ | ✅ |
|
||||
| `structure/import/*` | ✅ | ✅(load 合并 AST 后编译) |
|
||||
| `examples/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) |
|
||||
| `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) |
|
||||
|
||||
---
|
||||
|
||||
@@ -32,7 +32,13 @@ positional ::= value_token
|
||||
|
||||
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
|
||||
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
|
||||
- 内置 `print` 形参名为 `text`:`> print Hi` 与 `> print text=Hi` 等价。
|
||||
- 实参值中 `` `变量` `` 后**紧跟** `[^…]` 时按**脚注取元**解析(可链式),而非文本:`> print text=苹果单价:`水果价格`[^苹果]`、`> print text=`订单`[^2][^品名]`。
|
||||
- **独立 `>` 调用**:裸词 = 文本字面量。
|
||||
- **`*…*` / `**…**` 段内的调用**(如 `*x = > text.split value=src sep=","*`):裸词 = **变量**(Python 统一命名空间),文本字面量必须加引号(`value="a,b"`);`` `名` `` 变量形式仍合法。
|
||||
- 内置 `print` / `打印` 形参:`text` ≡ `内容`。
|
||||
- `input` / `输入`:`prompt` ≡ `提示`。
|
||||
- `len` / `长度`、`str` / `文本`、`int` / `整数`:`value` ≡ `值`。
|
||||
- 完整中英双名见 [keywords-i18n.md](keywords-i18n.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -47,4 +53,4 @@ positional ::= value_token
|
||||
|
||||
## 4. 金样例
|
||||
|
||||
见 `examples/structure/positional-call.mq.md` 与更新后的 `examples/structure/import/`。
|
||||
见 `tests/structure/positional-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
|
||||
@@ -0,0 +1,127 @@
|
||||
# OKF 兼容清单:`marqdo catalog`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(O1 + O3:工程目录包 + agent-kb 概念并入) |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 |
|
||||
| 相关 | [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` 派生的生成物**,不是手写配置。完整词汇、任务知识包与路线图见 [**okf.md**](okf.md)。生成式方向见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
|
||||
|
||||
本文件规定 **CLI 与工程目录包落盘格式**(含 O3:扫入本地 `agent-kb` 概念,供人与工具同览)。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI
|
||||
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
# 别名(与早期草案一致)
|
||||
marqdo sync [PATH] -o OUT_DIR
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
|
||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
|
||||
|
||||
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 生成物
|
||||
|
||||
```
|
||||
OUT_DIR/
|
||||
catalog.yaml # 机器向总清单(OKF 风格字段)
|
||||
index.md # 人可读总览:Modules + Agent knowledge
|
||||
modules/
|
||||
<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
|
||||
# GENERATED by marqdo — do not edit by hand
|
||||
type: Marqdo Catalog
|
||||
title: marqdo-project
|
||||
generated:
|
||||
by: marqdo/0.1.2
|
||||
modules:
|
||||
- id: structure/hello
|
||||
resource: structure/hello.mq.md
|
||||
title: Hello World
|
||||
imports: []
|
||||
exports:
|
||||
- name: Hello World
|
||||
kind: fn
|
||||
- id: structure/import/main
|
||||
resource: structure/import/main.mq.md
|
||||
imports:
|
||||
- utils.mq.md
|
||||
exports:
|
||||
- name: main
|
||||
kind: fn
|
||||
concepts: [] # 有 agent-kb 时为 Task/Skill 条目列表
|
||||
```
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) |
|
||||
| `modules[].resource` | 相对 `PATH` 的源路径 |
|
||||
| `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` |
|
||||
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`) |
|
||||
| `modules[].verified` / `sources` | 源 frontmatter 有则透传(O3) |
|
||||
| `concepts[]` | 本地 agent-kb 概念摘要(`id`/`type`/`page`/…) |
|
||||
| `generated.by` | `marqdo/<crate version>` |
|
||||
|
||||
不在现行范围:版本锁定哈希、跨仓 URL、完整符号类型、`log.md`(见 okf O4)。
|
||||
|
||||
### 3.2 模块概念页
|
||||
|
||||
Frontmatter 仍用 `depends` 字符串列表(机器可读);**正文 Dependencies** 链到同包其它 Module 页(人可点)。源若带 `verified` / `sources` 则写入页头。
|
||||
|
||||
### 3.3 Agent knowledge
|
||||
|
||||
`index.md` 的 **Agent knowledge** 节列出扫到的 Task/Skill,链到 `concepts/…`。概念页内容从本地 `agent-kb` **复制**,与 Agent 运行时包同源,便于人审阅晋升结果。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 `view output` 的分工
|
||||
|
||||
| 命令 | 产物 | 受众 |
|
||||
|------|------|------|
|
||||
| `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
|
||||
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引(含 agent-kb) | 人浏览依赖/技能 · 工具 / Agent |
|
||||
|
||||
二者都从同一源树生成,互不替代。发布用户文档时可同时:
|
||||
|
||||
```bash
|
||||
marqdo view output public -o public
|
||||
marqdo catalog tests -o .marqdo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml`、`modules/`、`concepts:` 键。
|
||||
2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。
|
||||
3. 模块页 Dependencies 对已解析导入为 Markdown 链接。
|
||||
4. 若扫描根下有 `.marqdo/agent-kb/concepts/`,则复制进 `OUT_DIR/concepts/` 且 `index.md` 有 Agent knowledge 条目。
|
||||
5. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
|
||||
6. `marqdo sync` 与 `catalog` 行为一致。
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 与 mapping v0.1 / keywords 对齐 |
|
||||
| 状态 | 与 mapping v0.1 / keywords 对齐(成段注释) |
|
||||
| 日期 | 2026-08-04 |
|
||||
|
||||
---
|
||||
@@ -11,12 +11,20 @@
|
||||
|
||||
| 层 | 形态 | 角色 |
|
||||
|----|------|------|
|
||||
| **叙述面** | 无标记行 | 注释;内部标记无语义 |
|
||||
| **叙述面** | 成段注释(空行分段) | 注释;段内任意标记无语义 |
|
||||
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
|
||||
| **外联面** | ` ```lang ` | 其它语言(FFI) |
|
||||
|
||||
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
|
||||
|
||||
### 成段注释
|
||||
|
||||
- 以**空行**划分段落。
|
||||
- 段首行:首字符非标记 → 注释。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
|
||||
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
|
||||
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
|
||||
|
||||
---
|
||||
|
||||
## 语句 vs 返回 vs 输出
|
||||
@@ -25,4 +33,6 @@
|
||||
|-----------|------|------------|
|
||||
| `*…*` | 程序语句 | 是 |
|
||||
| `**…**` | 返回值 | 是 |
|
||||
| `****` / 空粗体 | 空返回 + 结束函数体 | 是 |
|
||||
| `> print …` | 打印副作用 | 否(内置函数) |
|
||||
| 函数体 `---` / `***` | 结束函数体 | 是(边界) |
|
||||
@@ -1,4 +1,4 @@
|
||||
# Marqdo 实现依赖说明(Rust 参考解释器)
|
||||
# Marqdo 实现依赖说明(Rust 参考解释器)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -41,7 +41,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
│
|
||||
├─① 行分类(自研) 无标记 → 注释;有标记 → 代码行
|
||||
├─② GFM 块/行内(库) 标题、表、强调、列表结构
|
||||
├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `> file.mq.md`
|
||||
├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `import file:file.mq.md`
|
||||
└─④ Marqdo 语法(自研) 递归下降:Module/Fun/Stmt/Expr → AST
|
||||
└─ 表达式子语言 可手写,或仅对 Expr 用 pest/nom
|
||||
```
|
||||
@@ -80,7 +80,8 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
@@ -94,7 +95,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| Crate | 角色 |
|
||||
|-------|------|
|
||||
| **rust 自带** `#[test]` | 单元测试 |
|
||||
| **insta** 或手写金文件 | examples 期望 stdout 快照(可选) |
|
||||
| **insta** 或手写金文件 | tests 期望 stdout 快照(可选) |
|
||||
| **assert_cmd** / **predicates** | CLI 集成测试(可选) |
|
||||
|
||||
#### Phase II(字节码 VM,后加)
|
||||
@@ -142,8 +143,8 @@ crates/marqdo/ # 或根包 marqdo
|
||||
interp/ # Phase I
|
||||
bytecode/ # Phase II
|
||||
runtime/
|
||||
tests/
|
||||
examples/ # 金样例(已有)
|
||||
tests/ # gold.rs + structure|keywords|errors
|
||||
public/ # 用户可执行文档
|
||||
spike/ # Python 风险探测存档(可保留,非运行时依赖)
|
||||
```
|
||||
|
||||
@@ -152,7 +153,7 @@ spike/ # Python 风险探测存档(可保留,非运行
|
||||
```bash
|
||||
cargo build
|
||||
cargo test
|
||||
cargo run -- run examples/structure/nested-call.mq.md
|
||||
cargo run -- run tests/structure/nested-call.mq.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -3,34 +3,45 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 原则 | **示例即金样例**:`examples/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view` 也可直接浏览 |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 原则 | **夹具即金样例**:`tests/{structure,keywords,errors}/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view tests` 也可浏览 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目录
|
||||
|
||||
只保留 **`tests/`**,用子目录区分类别(不再另设 `examples/`):
|
||||
|
||||
```
|
||||
examples/
|
||||
README.md # 本树说明
|
||||
tests/
|
||||
README.md
|
||||
gold.rs # 集成测试入口
|
||||
structure/ # 代码基础结构(Markup 架构)
|
||||
hello.mq.md
|
||||
nested-call.mq.md # 原 index:嵌套函数 + 调用
|
||||
positional-call.mq.md # 位置实参
|
||||
nested-call.mq.md
|
||||
positional-call.mq.md
|
||||
branch.mq.md
|
||||
loop.mq.md
|
||||
collection.mq.md
|
||||
import/
|
||||
main.mq.md # 原 with-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 # True/False/None、and/or/not
|
||||
bool-logic.mq.md
|
||||
ext/
|
||||
agent-run-live.mq.md
|
||||
errors/ # 期望失败(诊断文案稳定后再加金样例)
|
||||
.gitkeep
|
||||
ns-instance-method.mq.md
|
||||
…
|
||||
```
|
||||
|
||||
Rust 集成测试:`tests/gold.rs` 扫描约定路径,比对 stdout。
|
||||
面向访客的可执行介绍在 [`public/`](../../public/)(无 `errors/`),见 [user-site.md](user-site.md)。
|
||||
开发设计文稿在 [`doc/`](../)(单数)。
|
||||
|
||||
---
|
||||
|
||||
@@ -38,39 +49,28 @@ Rust 集成测试:`tests/gold.rs` 扫描约定路径,比对 stdout。
|
||||
|
||||
| 类别 | 测什么 | 不测什么 |
|
||||
|------|--------|----------|
|
||||
| **structure** | `#`/`##`、形参、`>` 调用、`*`/`**`、`+`/`-`、表、导入、位置/具名实参 | 关键字边角 |
|
||||
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、点号路径 / `use`、位置/具名实参 | 关键字边角 |
|
||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
||||
|
||||
未单独建夹、但应覆盖的其它测试(放 `tests/` 单测或日后 `examples/runtime/`):
|
||||
未单独建夹、但应覆盖的其它测试(`src/**` 单测或日后 `tests/runtime/`):
|
||||
|
||||
- **流水线调试**:`--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`)
|
||||
|
||||
---
|
||||
|
||||
## 3. 金样例约定
|
||||
|
||||
每个可执行 `.mq.md` 在 `tests/gold.rs`(或旁路 `.out` 文件)登记期望 stdout。
|
||||
每个可执行 `.mq.md` 在 `tests/gold.rs` 登记期望 stdout。
|
||||
`errors/` 内文件登记期望 stderr 子串与非零退出码。
|
||||
|
||||
Frontmatter 可写:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: …
|
||||
expect_stdout: |
|
||||
line1
|
||||
line2
|
||||
---
|
||||
```
|
||||
|
||||
(可选;v0 先以测试代码内嵌期望为主。)
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 `view` 的关系
|
||||
## 4. 与 `view` / `public` 的关系
|
||||
|
||||
`marqdo view examples` 按上述文件夹生成侧栏索引;`structure` / `keywords` 为一级分组。
|
||||
- `marqdo view tests`:开发者浏览金样例(含 errors)。
|
||||
- `marqdo view public`:用户文档站源;**不要**把 `tests/errors` 编进 `public/`。
|
||||
@@ -0,0 +1,105 @@
|
||||
# Native plugin ABI (v2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted |
|
||||
| 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) |
|
||||
|
||||
## Goals
|
||||
|
||||
- Optional **native** extensions as shared libraries (`.dll` / `.so` / `.dylib`).
|
||||
- **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 = 2` (host accepts plugins with version `1..=2`).
|
||||
|
||||
Every plugin exports:
|
||||
|
||||
| Symbol | Role |
|
||||
|--------|------|
|
||||
| `marqdo_plugin_abi_version` | `1` or `2` |
|
||||
| `marqdo_plugin_init` | Register functions via `MarqdoHostApi` |
|
||||
| `marqdo_plugin_shutdown` | Teardown |
|
||||
|
||||
Host provides `register_fn`, `alloc`, `free`, and (v2) `host_query`.
|
||||
|
||||
### Wire format
|
||||
|
||||
Arguments and results are **UTF-8 JSON**:
|
||||
|
||||
- Args: JSON object keyed by parameter names (from `params` CSV at registration).
|
||||
- Result: any JSON value mappable to Marqdo `Value` (same rules as `lib/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 |
|
||||
|---------|---------|------|
|
||||
| `## load` (`path`) | `## 加载` (`路径`) | `host_plugin_load` |
|
||||
| `## unload` | `## 卸载` | `host_plugin_unload` |
|
||||
| `## list` | `## 列出` | `host_plugin_list` |
|
||||
| `## native_path` (`name`) | `## 原生路径` (`名`) | `host_ext_native_path` |
|
||||
|
||||
```markdown
|
||||
---
|
||||
import plugin:lib/plugin.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load path=demo.dll
|
||||
|
||||
*`sum` = > demo_add a=1 b=2 *
|
||||
> print text=`sum`
|
||||
```
|
||||
|
||||
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 unless trusted (`MARQDO_EXT` / `MARQDO_AGENT_PLUGIN` / built `libagent.*`). Prefer `native_path name=agent` for the official agent plugin.
|
||||
|
||||
## Demo / agent
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_demo
|
||||
cargo build -p marqdo_plugin_agent
|
||||
```
|
||||
|
||||
- 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`.
|
||||
|
||||
## 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
|
||||
- Arbitrary HostFn passthrough via `host_query`
|
||||
- **Third-party** plugin / package registry
|
||||
@@ -0,0 +1,150 @@
|
||||
# 父智能体 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` |
|
||||
| `skill_brief`(父 / 子) | ~1.2KiB(`skill_brief`) | `READ:skill` → ~4KiB |
|
||||
| `has_worker_step` / `solidify_on_done` | 布尔提示 | — |
|
||||
|
||||
`## step` 同样默认注入 **预算后的** `source_brief` + `skill_brief`(非全文);截断处带 `[truncated …; emit READ:…]` 标记,子轮最多 `max_reads` 次加深后再 CALL/作答。
|
||||
|
||||
`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` |
|
||||
| `corpus_search` | 本地语料关键词检索(RAG-lite;`ARGS.query` / `root`) |
|
||||
| `mcp_list_tools` / `mcp_call` | MCP 形 JSON fixture 列工具 / 调用(离线证据) |
|
||||
|
||||
以上 **corpus / mcp** 返回一律带 `authority=workbook`:检索与外置工具只是证据,**可跑的 `.mq.md` 工作簿 / OKF 技能仍是权威真相**。
|
||||
|
||||
### 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) · [调研:主流框架与 Marqdo](../research/agent-frameworks-and-marqdo.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-…
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
import subtask: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 程序——程序里的智能体可多可少,写回默认打开,能写成代码的就不要再问模型。**
|
||||
@@ -0,0 +1,349 @@
|
||||
# Official agent development framework (`ext/ai/agent`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 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 / 任务知识包**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [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) |
|
||||
|
||||
## 0. 为什么要改掉旧方案
|
||||
|
||||
旧版把智能体做成「黑盒对话循环」:隐藏提示拼装、`TOOL:<name>` 协议、host 历史袋、一次(或几次)模型往返。这是对 LangChain 类框架的平移,**背离了 Marqdo 的初衷**。
|
||||
|
||||
Marqdo 的宪法是 **代码即文档、文档即知识库**:
|
||||
|
||||
| 旧方案的问题 | Marqdo 应有的形态 |
|
||||
|--------------|-------------------|
|
||||
| 提示词藏在框架字符串里,与编排源码分离 | 提示、工具、任务、结果都在 `.mq.md` 里,人与模型同读同写 |
|
||||
| 执行过程是不透明的 chat transcript | 思考与行动写回文档;`view` / `debug` 可跟可审 |
|
||||
| 复杂任务与简单任务同一套循环 | **单步**与**多步(工作簿)**两级模型 |
|
||||
| 成功经验留在进程内存 | **自写回**做成果缓存与失败知识;同类任务可复用 |
|
||||
|
||||
本文件锁定新方向。仓库里现有的 `ext/ai/agent.mq.md` / `智能体.mq.md`(TOOL: 薄循环)视为 **待替换实现**,以本文为准。
|
||||
|
||||
---
|
||||
|
||||
## 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 # 模型 I/O
|
||||
agent.mq.md / 智能体.mq.md # 本框架(按本文重写)
|
||||
```
|
||||
|
||||
| 层 | 职责 |
|
||||
|----|------|
|
||||
| **应用 runbook** | 领域 `##` 工具、任务表、是否人工确认分解 |
|
||||
| **`ext/ai/agent`** | 单步 / 多步、工作簿生成、子智能体编排、写回约定 |
|
||||
| **`ext/ai/llm`** | 补全 / 聊天 |
|
||||
| **`lib/writeback`** | 持久化输出块 |
|
||||
| **`lib/subtask`** | **工具调用与(多步时)子智能体并行的执行通道**;见 [stdlib-subtask.md](stdlib-subtask.md) |
|
||||
|
||||
安装:[`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`(`.mq.md` + `native/libagent.so`)。导入:`导入 智能体:ext/ai/智能体.mq.md`。
|
||||
|
||||
**原生插件(ABI v2)**:`ext/ai/agent` 经 `lib/plugin` 加载;优先 `> plugin.native_path name=agent`,否则按序查找:
|
||||
|
||||
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` 安装)
|
||||
|
||||
本地开发须先 `cargo build -p marqdo_plugin_agent`(或 `ext add agent` / 设 `MARQDO_AGENT_PLUGIN`)。详见 [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md)。
|
||||
|
||||
**分层纪律(硬规则,勿破)**:
|
||||
|
||||
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`。
|
||||
|
||||
官方 `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
|
||||
`工具表` =
|
||||
| 工具 |
|
||||
|------|
|
||||
| 获取时间 |
|
||||
| 读取摘要 |
|
||||
```
|
||||
|
||||
- 单列表 → 名称列表。
|
||||
- 多列表 → 从列 `工具` / `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/`。
|
||||
|
||||
---
|
||||
|
||||
## 7. 上下文注入(每次单步 / 子步)
|
||||
|
||||
必须可注入(实现可切片,但不得默默丢掉「代码即文档」):
|
||||
|
||||
| 片段 | 来源 |
|
||||
|------|------|
|
||||
| 站立提示 | 构造参数 / 文档正文 |
|
||||
| 任务 / 目标 | 方法实参 |
|
||||
| 工具表(人可读) | 构造参数 |
|
||||
| **当前 `.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` |
|
||||
|
||||
禁止:把整份 Skill + 全文源码藏进不可审查的二进制提示且不在文档中留迹。框架拼装的提示应能在调试时落盘或写回(至少摘要)。
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
*`out` = > `助手`.step task=… *
|
||||
*`回复` = > json.get value=`out` key=result *
|
||||
# 默认已写回;若 writeback=False 则需自行 record:
|
||||
# > writeback.record value=`body` key=ok
|
||||
```
|
||||
|
||||
命名槽 `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 约束写入形态;多步生成文件限于工作簿目录 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 相对旧 API 的迁移
|
||||
|
||||
| 旧(废弃方向) | 新 |
|
||||
|----------------|----|
|
||||
| 唯一的 `## 执行` / `## run` + 隐藏 TOOL: 循环 | `## 单步` / `## 多步` |
|
||||
| host 历史袋为真相 | 文档写回 + 工作簿为真相;历史袋至多辅助 |
|
||||
| 提示全在框架字符串 | 站立提示与任务在 `.mq.md`;源码注入 |
|
||||
| `tests/ext/agent-smoke` 测 TOOL 上下文拼接 | 重写为单步离线 / 写回 / 工作簿骨架测试 |
|
||||
|
||||
兼容:可短期保留 `## 执行` 作为 `## 单步` 的别名,但文档与金样例迁到新名后删除别名。
|
||||
|
||||
---
|
||||
|
||||
## 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)。
|
||||
@@ -0,0 +1,72 @@
|
||||
# Official extension installer (`marqdo ext`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted (v0.1)** |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) |
|
||||
|
||||
## Commands
|
||||
|
||||
```text
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext remove llm
|
||||
marqdo ext remove agent
|
||||
```
|
||||
|
||||
## Install root
|
||||
|
||||
1. `MARQDO_EXT` if set
|
||||
2. Else `~/.marqdo/ext`
|
||||
|
||||
Imports use paths like `import llm:ext/ai/llm.mq.md` (see [`load.rs`](../../src/load.rs)).
|
||||
|
||||
## Source for `add`
|
||||
|
||||
1. `MARQDO_EXT_SOURCE` — directory containing `ai/llm.mq.md` …
|
||||
2. Else repo `./ext` near cwd / binary
|
||||
|
||||
## Layout (`ext/`)
|
||||
|
||||
Official extensions live under **`ext/ai/`** (LLM + agent framework only). Do not add flat `.mq.md` files at `ext/` root — keeps the tree from accumulating unrelated modules.
|
||||
|
||||
```text
|
||||
ext/
|
||||
ai/
|
||||
llm.mq.md
|
||||
大模型.mq.md
|
||||
agent.mq.md
|
||||
智能体.mq.md
|
||||
```
|
||||
|
||||
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`, **`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` ([`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md); needs `tests/ext/.env` + built `libagent`).
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Third-party registry
|
||||
- Merging into `lib/`
|
||||
- Bundling domain/task helpers in official ext
|
||||
@@ -0,0 +1,85 @@
|
||||
# Official extensions (`ext/`) — LLM
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted (v0.1.x) |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) |
|
||||
|
||||
## Scope
|
||||
|
||||
`ext/ai/` holds **official LLM + agent** extensions. Import paths:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import llm:ext/ai/llm.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
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) / [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 `import llm:ext/ai/llm.mq.md` from repo or install root.
|
||||
|
||||
## Platform prerequisites
|
||||
|
||||
| Capability | Surface |
|
||||
|------------|---------|
|
||||
| HTTPS + headers | `lib/net` → `http_post` / `headers=` map |
|
||||
| Dotenv | `## load_env` in ext (or `load_dotenv` / `lib/sys`) |
|
||||
| JSON quote | `lib/json` → `quote` |
|
||||
|
||||
## `ext/ai/llm` / `ext/ai/大模型` (object handles)
|
||||
|
||||
| English | Chinese | Role |
|
||||
|---------|---------|------|
|
||||
| `## load_env` | `## 加载环境` | Free function: load `.env` |
|
||||
| `## stream_result` | `## 流式结果` | Collapse event list → final text |
|
||||
| `# llm` | `# 大模型` | Object ctor → handle map |
|
||||
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods; optional `stream` / `流式`, `echo` / `打印增量` |
|
||||
|
||||
```markdown
|
||||
---
|
||||
import llm:ext/ai/llm.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_env
|
||||
|
||||
*`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):
|
||||
|
||||
```env
|
||||
OPENAI_API_KEY=sk-...
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
OPENAI_MODEL=gpt-4o-mini
|
||||
```
|
||||
|
||||
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 `## 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,230 @@
|
||||
# `ext/quantum` Q7 — 高阶线性代数 + 高级可视化
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · Q7a/Q7b/Q7c 已落地** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 父设计 | [ext-quantum.md](ext-quantum.md) |
|
||||
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| 对照 | [IBM Quantum state plots](https://quantum.cloud.ibm.com/docs/en/guides/plot-quantum-states) · [QuTiP visualization](https://qutip.readthedocs.io/en/latest/guide/guide-visualization.html) · Cirq `plot_density_matrix` |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
在 **Q0–Q6 态向量教学模拟**之上,补齐两块「教科书级」能力:
|
||||
|
||||
1. **高阶线性代数**(密度矩阵、Kronecker、部分迹、Hermitian 谱分解、Schmidt / SVD、Pauli 期望值)
|
||||
2. **高级静态 SVG 展示**(Hinton / City / Pauli 向量 / QSphere 风格 / 多比特布洛赫)
|
||||
|
||||
全部经 **`plugins/quantum` ABI**;`ext/quantum/**` 只做 L1 表包装,**禁止** `host_*`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机与业界对照(联网调研 2026-08)
|
||||
|
||||
### 1.1 为何现在做
|
||||
|
||||
| 已有(Q0–Q6) | 缺口 |
|
||||
|---------------|------|
|
||||
| 纯态态向量 + 施门 + 采样 | 混态 / 约化子系统无法一等公民表达 |
|
||||
| `bloch` 单比特约化 | 纠缠与多比特关联只能猜 |
|
||||
| `gate.draw kind=matrix` 热力图 | 无密度矩阵 / Pauli 分解 / 球面振幅布局 |
|
||||
| 内部 `apply_unitary` / Kronecker | **未**暴露为作者面 API |
|
||||
|
||||
教学文档写「贝尔态纠缠」时,读者需要:**约化密度矩阵 → 纯度 < 1 → Schmidt 系数 → Hinton/QSphere 图**。这些正是 Qiskit / QuTiP / Cirq 的标配。
|
||||
|
||||
### 1.2 可视化对标(只取可静态 SVG 落地的子集)
|
||||
|
||||
| 业界 | 含义 | Q7 决策 |
|
||||
|------|------|---------|
|
||||
| Qiskit `plot_state_hinton` | 元大小表示幅值,色表示正负 | ✅ `kind=hinton` |
|
||||
| Qiskit `plot_state_city` | Re/Im 三维条 | ✅ **2.5D 等轴测 SVG**(非 Matplotlib) |
|
||||
| Qiskit `plot_state_paulivec` | Pauli 串期望值柱 | ✅ `kind=paulivec` |
|
||||
| Qiskit `plot_state_qsphere` | 振幅点在球面上,色=相位 | ✅ `kind=qsphere`(教学投影) |
|
||||
| Qiskit `plot_bloch_multivector` | 每比特一球 | ✅ `kind=multibloch` |
|
||||
| Cirq density Argand 格 | 每元幅值圆 + 相位针 | ✅ 并入 `kind=density`(默认) |
|
||||
| QuTiP Wigner / 过程层析 | 连续相空间 / χ 矩阵 | ❌ 本切片不做 |
|
||||
|
||||
### 1.3 线性代数对标(经典模拟侧,非量子算法)
|
||||
|
||||
| 能力 | 教学用途 | Q7 |
|
||||
|------|----------|-----|
|
||||
| ρ = \|ψ⟩⟨ψ\| | 纯→密度 | ✅ |
|
||||
| Kronecker / 张量积 | 复合系统 | ✅ |
|
||||
| 部分迹 | 约化、纠缠证据 | ✅ |
|
||||
| Hermitian 本征分解 | 谱 / 测量可观测量 | ✅(小维) |
|
||||
| Schmidt(纯态二分)= 整形 SVD | 纠缠熵入口 | ✅ |
|
||||
| Pauli 期望 ⟨P⟩ | 布洛赫 / paulivec 数据源 | ✅ |
|
||||
| 纯度 Tr(ρ²)、保真度 | 混态度量 | ✅ 最小 |
|
||||
| 量子奇异值变换 / VQSVD / 云后端 | 算法研究 | ❌ |
|
||||
|
||||
---
|
||||
|
||||
## 2. 硬约束(沿用 + 本切片追加)
|
||||
|
||||
1. **仅 ABI**:新 FFI 全部注册在 `marqdo_plugin_init`;L1 经 `plugin.load`。
|
||||
2. **`ext/**` 无 `host_*`**。
|
||||
3. **中英分文件**,禁止混 API。
|
||||
4. **维数上限**:
|
||||
- 态向量模拟:仍 ≤ 12 qubits(既有)。
|
||||
- **密度矩阵稠密运算**(部分迹结果展示、谱分解、Hinton/City):默认 **≤ 6 qubits**(dim ≤ 64);超限显式报错。
|
||||
5. **无新核心依赖**:插件内手写复数矩阵 + Jacobi / 薄 SVD;**不**捆绑 BLAS / nalgebra(可后续再议)。
|
||||
6. **view**:仍走 `host_query("record_plot")` + `quantum_svg`;无外链字体/CDN。
|
||||
|
||||
---
|
||||
|
||||
## 3. 新运行时类型
|
||||
|
||||
| `_type`(英) | 中文 | 字段(锁定) |
|
||||
|---------------|------|----------------|
|
||||
| `quantum_state` | `量子态` | 既有:`qubits`, `amplitudes:[{re,im}]` |
|
||||
| `quantum_density` | `密度矩阵` | `qubits`, `dim`, `matrix`(dim×dim 嵌套 `{re,im}`) |
|
||||
| `quantum_spectrum` | `谱` | `eigenvalues:[f64]`, `eigenvectors`(列向量嵌套 list) |
|
||||
| `quantum_schmidt` | `施密特` | `coeffs:[f64]`, `ua`, `ub`(局域基),`entropy`(可选) |
|
||||
| `quantum_svg` | — | 既有;`kind` 扩展见 §5 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 作者面 API
|
||||
|
||||
### 4.1 英文(`ext/quantum/quantum.mq.md`)
|
||||
|
||||
在既有 `# circuit` / `# gate` 之外增加(或扩展方法):
|
||||
|
||||
```markdown
|
||||
# density
|
||||
+ `state`=None # quantum_state 或 circuit(先 simulate)
|
||||
+ `matrix`=None # 直接给定 ρ
|
||||
|
||||
## matrix # → 嵌套 list
|
||||
## purity # Tr(ρ²)
|
||||
## expect
|
||||
+ `obs` # Pauli 串 "ZI" / "XX" 或门矩阵
|
||||
## partial_trace
|
||||
+ `keep` # 保留的比特列表(LSB=0)
|
||||
## eig # Hermitian 谱 → quantum_spectrum
|
||||
## draw
|
||||
+ `kind`=hinton # hinton|city|density|paulivec
|
||||
+ `path`=None
|
||||
|
||||
# linop # 自由线性代数(也可挂在 quantum.* 模块函数)
|
||||
## kron
|
||||
+ `a`
|
||||
+ `b` # 矩阵或态 → 张量积
|
||||
## schmidt
|
||||
+ `state`
|
||||
+ `cut`=1 # 前 cut 个比特为 A,其余为 B
|
||||
## fidelity
|
||||
+ `a`
|
||||
+ `b` # 两态或两密度(纯态公式优先)
|
||||
```
|
||||
|
||||
**电路侧便捷方法**(返回新句柄,不改旧对象):
|
||||
|
||||
```markdown
|
||||
## density # simulate 后 ρ=|ψ⟩⟨ψ|
|
||||
## expect
|
||||
+ `obs`
|
||||
## schmidt
|
||||
+ `cut`=1
|
||||
## draw
|
||||
+ `kind`=… # 扩展:hinton|city|density|paulivec|qsphere|multibloch
|
||||
```
|
||||
|
||||
### 4.2 中文对称
|
||||
|
||||
| 英文 | 中文 |
|
||||
|------|------|
|
||||
| `density` | `密度` |
|
||||
| `partial_trace` | `部分迹` |
|
||||
| `purity` | `纯度` |
|
||||
| `expect` | `期望` |
|
||||
| `eig` | `本征` |
|
||||
| `kron` | `张量积` |
|
||||
| `schmidt` | `施密特` |
|
||||
| `fidelity` | `保真度` |
|
||||
| `hinton` / `city` / `paulivec` / `qsphere` / `multibloch` | 同音译或 `欣顿`/`城市`/`泡利向量`/`球`/`多布洛赫`(L1 锁定中英别名表) |
|
||||
|
||||
### 4.3 ABI 函数名(稳定英文)
|
||||
|
||||
| FFI | 作用 |
|
||||
|-----|------|
|
||||
| `quantum_density_from_state` | 态 / 电路 → `quantum_density` |
|
||||
| `quantum_density_from_matrix` | 校验 Hermitian / 维数 → 句柄 |
|
||||
| `quantum_density_matrix` | 取出嵌套矩阵 |
|
||||
| `quantum_density_purity` | Tr(ρ²) |
|
||||
| `quantum_density_partial_trace` | keep 列表 |
|
||||
| `quantum_density_eig` | Jacobi Hermitian |
|
||||
| `quantum_density_expect` | Pauli 串或矩阵 |
|
||||
| `quantum_density_draw` | hinton/city/density/paulivec |
|
||||
| `quantum_kron` | 两矩阵或两态振幅 |
|
||||
| `quantum_schmidt` | 纯态二分 |
|
||||
| `quantum_fidelity` | 两态 |
|
||||
| `quantum_draw_circuit` | **扩展** kind 枚举(向后兼容) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 高级绘图语义
|
||||
|
||||
| `kind` | 输入 | SVG 要点 |
|
||||
|--------|------|----------|
|
||||
| `hinton` | ρ | 网格方块;边长 ∝ √\|ρᵢⱼ\|;正 Re 浅 / 负深;小 dim 可标数值 |
|
||||
| `city` | ρ | 等轴测「楼宇」:左 Re、右 Im 两城,或单城双色柱 |
|
||||
| `density` | ρ | Cirq 风格:每格幅值圆 + 相位线段;对角概率矩形 |
|
||||
| `paulivec` | 态或 ρ | 全 Pauli 基(n≤3)或用户 `ops=` 列表;柱高 = ⟨P⟩ |
|
||||
| `qsphere` | 纯态 | 基矢点映射到球/圆;半径∝振幅,色相∝arg;n≤4 推荐 |
|
||||
| `multibloch` | 纯态 | 每比特约化布洛赫并排 |
|
||||
|
||||
既有 `circuit|probs|bloch|gate|matrix` **不变**。
|
||||
|
||||
---
|
||||
|
||||
## 6. 数值语义(锁定)
|
||||
|
||||
| 项 | 规则 |
|
||||
|----|------|
|
||||
| 比特序 | **qubit 0 = LSB**(与既有概率标签一致) |
|
||||
| `partial_trace keep=` | 保留比特升序组成新系统的 LSB…MSB |
|
||||
| Pauli 串 | 左→右 = **高位→低位** 或文档写死「左=qubit n-1」——**锁定:字符串左端 = 最高比特(qubit n−1)**,与 Qiskit 习惯一致;文档 + 金样双锁 |
|
||||
| Hermitian 检查 | ‖ρ−ρ†‖_F < 1e-8,否则报错 |
|
||||
| 谱 | 实特征值降序;特征向量列归一 |
|
||||
| Schmidt | 将 \|ψ⟩ 整形为 `2^cut × 2^(n-cut)` 复矩阵做薄 SVD;奇异值 = Schmidt 系数 |
|
||||
| 纯度 | 纯态 ≈ 1;最大混态 = 1/dim |
|
||||
|
||||
---
|
||||
|
||||
## 7. 分期交付
|
||||
|
||||
| 子阶段 | 内容 | 验收 |
|
||||
|--------|------|------|
|
||||
| **Q7a** | density / kron / partial_trace / eig / schmidt / expect / purity / fidelity + L1 中英 | `tests/ext/quantum-linalg-smoke.mq.md`(+ zh) |
|
||||
| **Q7b** | draw kinds:hinton, city, density, paulivec, qsphere, multibloch | `tests/ext/quantum-viz-advanced-smoke.mq.md`(SVG 含关键标记) |
|
||||
| **Q7c** | 示例页 + 用户站短页 + skill/reference 摘要 | `examples/quantum-entanglement/` 或扩展 bell |
|
||||
|
||||
---
|
||||
|
||||
## 8. 刻意不做(本 Q7)
|
||||
|
||||
- 任意 Kraus / 完整 CPTP 通道库(仍用 Q5 轨迹噪声)
|
||||
- >6 qubit 稠密 ρ 的谱 / Hinton(请用态向量 API)
|
||||
- Matplotlib / WebGL / 交互拖拽
|
||||
- 量子线性系统算法(HHL)、QSVT 电路构造
|
||||
- 把线性代数并入 `lib/math`
|
||||
|
||||
---
|
||||
|
||||
## 9. 评审清单
|
||||
|
||||
1. 密度矩阵上限 6 qubits 是否可接受?
|
||||
2. Pauli 串左右端比特约定是否锁定为「左=高比特」?
|
||||
3. City 用 2.5D SVG 而非真 3D 是否足够?
|
||||
4. `# density` 独立类 vs 仅 `circuit.density` —— **两者都提供**(类用于给定矩阵;电路方法便捷)?
|
||||
|
||||
评审默认:**全部锁定为上文**;实现按 Q7a → Q7b → Q7c。
|
||||
|
||||
---
|
||||
|
||||
## 10. 一句话
|
||||
|
||||
**Q7 让 Marqdo 量子文档能「算清纠缠、画清态」:线性代数在 ABI 里跑,高级图用自绘 SVG 进 view——仍是代码即文档。**
|
||||
@@ -0,0 +1,153 @@
|
||||
# `ext/quantum` Q8 — 可视化美学升级(科技感电路图)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · Q8a/Q8b landed · Q8c pending** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 父设计 | [ext-quantum.md](ext-quantum.md) · [ext-quantum-q7.md](ext-quantum-q7.md) |
|
||||
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| 对照 | [IBM Quantum Composer](https://quantum.cloud.ibm.com/docs/guides/composer) · [Qiskit `iqp` / `iqp-dark`](https://quantum.cloud.ibm.com/docs/api/qiskit/qiskit.visualization.circuit_drawer) · Cirq / Quirk 视觉习惯 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
修复 view 内嵌量子 SVG 的**文字–导线粘连**,并把电路 / 概率 / 布洛赫 / 密度类图统一到一套**量子实验室科技感**视觉令牌(深底、门族分色、清晰留白)——仍只输出自包含 SVG,无外链字体/CDN。
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题诊断(对照用户截图)
|
||||
|
||||
| 现象 | 根因(`plugins/quantum/src/draw.rs`) |
|
||||
|------|----------------------------------------|
|
||||
| `q0`/`q1` 与导线穿过文字 | 导线从 `x=8` 起画满宽;标签 `x=4` 且基线对齐导线中心 → 线穿字 |
|
||||
| 「不好看 / 无科技感」 | 单色 `#1a1a1a` + 浅灰盒;无门族色、无背景板、无线宽层次 |
|
||||
| 门盒贴线、略挤 | `COL_W=56`、盒 28×28、标签栏与第一列无独立 gutter |
|
||||
| 测量/控点辨识弱 | 与单比特门同色同描边,缺少语义色 |
|
||||
|
||||
**不在本切片**:交互拖拽、WebGL、外链字体、第二套 view 皮肤。
|
||||
|
||||
---
|
||||
|
||||
## 2. 业界对照(联网 2026-08)
|
||||
|
||||
| 来源 | 可借鉴点 | 本仓取舍 |
|
||||
|------|----------|----------|
|
||||
| **Qiskit `iqp` / `iqp-dark`** | 门族 `displaycolor`(面色+字色);深色底;线色弱于门 | 移植**色板与分类**,不绑 matplotlib |
|
||||
| **IBM Composer** | 经典门深蓝、相位门浅蓝、非酉灰;导出 light/dark | 默认 **dark tech**(view 卡片上更醒目);可选 `theme=light` |
|
||||
| **Quirk** | 高对比栅格、测量仪表清晰 | 测量盒保留仪表符号,加强描边/填充对比 |
|
||||
| **教科书 bw** | 印刷友好 | 保留为 `theme=bw` 后备,非默认 |
|
||||
|
||||
**刻意避开**:紫白渐变「AI 默认皮肤」;过重 glow 光晕(打印/浅底卡片会糊)。科技感靠:**深 slate 底 + 青/靛门色 + 清晰层级 + 留白**,而非堆霓虹。
|
||||
|
||||
---
|
||||
|
||||
## 3. 视觉令牌(锁定 `marqdo-iqp`)
|
||||
|
||||
### 3.1 主题
|
||||
|
||||
| `theme` | 用途 |
|
||||
|---------|------|
|
||||
| `dark`(**默认**) | view / 教学演示科技感 |
|
||||
| `light` | 浅底文档打印 |
|
||||
| `bw` | 无彩色、高对比 |
|
||||
|
||||
作者面:
|
||||
|
||||
```markdown
|
||||
*`svg` = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*`svg` = > `qc`.draw kind="probs" theme="light"*
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `kind` | `circuit` | 既有枚举不变 |
|
||||
| `theme` | `dark` | 新增;非法值报错 |
|
||||
| `path` | — | 既有 |
|
||||
|
||||
中文:`主题=dark|light|bw`。ABI:`quantum_draw_circuit` 增可选 `theme`(circuit/probs/bloch 已生效;gate/density 高级图见 Q8c)。
|
||||
|
||||
### 3.2 Dark 色板(默认)
|
||||
|
||||
| 令牌 | 色 | 用途 |
|
||||
|------|-----|------|
|
||||
| `bg` | `#0a0e14` → `#141c28` 渐变 | SVG 圆角底板 |
|
||||
| `wire` | `#6b7f96` | 比特线(双层描边) |
|
||||
| `label` / `chip` | `#e8eef6` / `#1e2a3a` | `q0` 芯片标签(线不穿字) |
|
||||
| `gate.clifford` | 面 `#4c6fff` / 字 `#f2f6ff` | H、X、Y、CX、SWAP… |
|
||||
| `gate.phase` | 面 `#2de2e6` / 字 `#042024` | S、T、Rz、CZ… |
|
||||
| `gate.rotation` | 面 `#3dd6c6` / 字 `#041a18` | Rx、Ry |
|
||||
| `gate.measure` | 面 `#8fa3b8` / 字 `#0a1018` | MEASURE |
|
||||
| `barrier` | `#9aafc0` 虚线 | BARRIER |
|
||||
| `ctrl` | `#f0f5ff` | 控制点 / ⊕ |
|
||||
|
||||
Light / bw 在实现里各给一套平行表;金样以 dark 主断言(SVG 含 `data-theme="dark"` 与背景色)。
|
||||
|
||||
### 3.3 布局(消灭粘连)
|
||||
|
||||
```text
|
||||
| pad | label_col | gutter | col0 | … | colN | pad |
|
||||
^q0 芯片标签 ^导线从此开始(不穿过文字)
|
||||
```
|
||||
|
||||
| 常量 | 实现值 |
|
||||
|------|--------|
|
||||
| `LABEL_W` | 52 |
|
||||
| `GUTTER` | 20 |
|
||||
| `PAD_X` / `PAD_Y` | 24 / 36 |
|
||||
| `COL_W` | 80 |
|
||||
| `ROW_H` | 64 |
|
||||
| 门盒 | 40×40,`rx=8` |
|
||||
| 线宽 | 导线双层 3.2+1.8;门描边 ~1.1;控制竖线 2.25 |
|
||||
|
||||
标签:圆角芯片 + 居中文字;导线 `x1 = PAD_X + LABEL_W + GUTTER`。
|
||||
|
||||
### 3.4 门族映射
|
||||
|
||||
| 族 | 门名(归一化后) |
|
||||
|----|------------------|
|
||||
| clifford | I X Y Z H CX CNOT SWAP |
|
||||
| phase | S T RZ CZ |
|
||||
| rotation | RX RY |
|
||||
| measure | MEASURE M |
|
||||
| barrier | BARRIER |
|
||||
| custom / U | clifford 色或中性 `#546e7a` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 作者面(增量,向后兼容)
|
||||
|
||||
见 §3.1。字符串参数须加引号:`kind="circuit"`、`theme="dark"`(中文 `种类=` / `主题=`)。改插件后须 `marqdo ext add quantum` 再开 view,否则仍加载旧 `.so`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 分期
|
||||
|
||||
| 子阶段 | 内容 | 验收 |
|
||||
|--------|------|------|
|
||||
| **Q8a** | 电路轨线:布局 gutter + dark/light/bw 令牌 + 门族分色 | 标签不与线相交;SVG 含 `data-theme`;更新 draw smoke |
|
||||
| **Q8b** | probs / bloch / gate heatmap 共用令牌 | 柱/球/热力与电路同族色 |
|
||||
| **Q8c** | hinton / city / qsphere / paulivec / multibloch 换肤 | 高级图不「脱节」;viz-advanced smoke 仍绿 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 实现约束
|
||||
|
||||
1. 仅改 `plugins/quantum` 绘图 + L1 透传 `theme`;**不**改 Marqdo 核心。
|
||||
2. SVG **内联**颜色与字体栈(`ui-sans-serif, system-ui, …`);无 `@import` / CDN。
|
||||
3. view 仍走 `record_plot`;底板自带圆角矩形,避免白底卡片上「漂浮黑线」。
|
||||
4. 金样:断言结构标记(`data-theme`、`data-gate-family`)+ 既有 kind;不像素比对。
|
||||
|
||||
---
|
||||
|
||||
## 7. 非目标
|
||||
|
||||
- 复制 Qiskit matplotlib 像素级一致
|
||||
- 动画 / 3D 电路
|
||||
- 用户自定义完整 JSON 主题文件(可 Q9)
|
||||
|
||||
---
|
||||
|
||||
## 8. 一句话
|
||||
|
||||
**先把字从线上挪开,再给门族涂上实验室色——默认 dark tech,打印用 light,论文用 bw。**
|
||||
@@ -0,0 +1,408 @@
|
||||
# 官方扩展:`ext/quantum` 量子计算模拟
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · Q0–Q7 完结 · Q8a/Q8b 完结**([ext-quantum-q7.md](ext-quantum-q7.md) · [ext-quantum-viz-style.md](ext-quantum-viz-style.md);Q8c 高级态图换肤待做) |
|
||||
| 日期 | 2026-08-12(初版)· 2026-08-28(Q7 · Q8 viz) |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [ext-web.md](ext-web.md) · [view.md](view.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| 安装(目标) | `marqdo ext add quantum`(中英:`quantum` / `量子`) |
|
||||
| 本文目的 | 锁定**作者面**、**模拟语义**、**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
|
||||
---
|
||||
import quantum: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 产物
|
||||
+ `kind`=circuit # circuit|probs|bloch|hinton|…(见 Q7)
|
||||
+ `theme`=dark # dark|light|bw(Q8;电路/概率/布洛赫)
|
||||
## 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` | `绘图` |
|
||||
| `kind` | `种类` |
|
||||
| `theme` | `主题` |
|
||||
| `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`;Q8 默认 `theme=dark`(标签芯片 + 门族分色) |
|
||||
| 测量概率条形图 | **必须** | `probabilities` / `run` 后可 `draw kind=probs` |
|
||||
| 单比特布洛赫球(SVG) | 应有 | 仅 n=1 或指定 qubit 约化(纯态投影) |
|
||||
| 门矩阵热力图 | **必须** | `gate.draw kind=matrix`(幅值热图 + 小数标注) |
|
||||
| 高级态图(hinton/city/…) | Q7 | 见 [ext-quantum-q7.md](ext-quantum-q7.md);换肤见 Q8c |
|
||||
| 交互拖拽编辑电路 | **不做** | 静态文档足够 |
|
||||
|
||||
视觉:内联 SVG 色与字体栈;**无外链**字体/CDN(同 view 硬规则)。主题令牌与布局:[ext-quantum-viz-style.md](ext-quantum-viz-style.md)。view 对 `svg[data-theme=dark]` 使用深色图框。
|
||||
|
||||
---
|
||||
|
||||
## 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` |
|
||||
| **Q6** | 公式/`matrix=` 自定义门 | [ext-quantum-custom-gate.md](ext-quantum-custom-gate.md) |
|
||||
| **Q7** | 密度矩阵线性代数 + Hinton/City/QSphere 等 SVG + 纠缠示例 | [ext-quantum-q7.md](ext-quantum-q7.md) ✅ |
|
||||
| **Q8** | 可视化美学:`theme` + 标签 gutter + 门族分色 | [ext-quantum-viz-style.md](ext-quantum-viz-style.md) · Q8a/Q8b ✅ · Q8c 待做 |
|
||||
|
||||
实现路线图跟踪见 [roadmap/ext-quantum.md](../roadmap/ext-quantum.md)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 规范示例(目标作者体验)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Bell state
|
||||
import quantum: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,124 @@
|
||||
# `ext/web` 驱动:Postgres · Redis · S3
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 已落地** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 相关 | [ext-web.md](ext-web.md) · [roadmap/ext-web.md](../roadmap/ext-web.md) · [ext-abi.md](ext-abi.md) |
|
||||
| 目标 | 在**不改作者面 CRUD 心智**的前提下,用 URL 方案切换数据库;另增缓存与对象存储两类驱动。贯彻「表格 + 类方法」:配置即数据,装配即函数。 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**`# db` 的 `url=` 决定后端**:`sqlite:` 默认;`postgres://` / `postgresql://` 走 Postgres,作者面 API 不变。
|
||||
**缓存**与**对象存储**是独立类(`# cache` / `# storage`),不塞进 `# db`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 边界
|
||||
|
||||
| 能力 | 归属 | 理由 |
|
||||
|------|------|------|
|
||||
| SQLite / Postgres CRUD | `plugins/web` + `ext/web` `# db` | 同一套 `init/select/insert/…`;热路径 ABI |
|
||||
| Redis 缓存 | `plugins/web` + `ext/web` `# cache` | 键值语义,不是表 CRUD |
|
||||
| S3 / MinIO 对象 | `plugins/web` + `ext/web` `# storage` | 对象键 + 字节/路径,不是行 |
|
||||
| 禁止 | 核心 `src/host/` | 驱动依赖重,只进 ABI 插件 |
|
||||
|
||||
---
|
||||
|
||||
## 2. URL 方案(锁定)
|
||||
|
||||
| 方案 | 含义 | 例 |
|
||||
|------|------|-----|
|
||||
| `sqlite:` / 裸路径 | SQLite 文件(既有) | `sqlite:data/site.db` |
|
||||
| `postgres://` / `postgresql://` | Postgres | `postgres://user:pass@127.0.0.1:5432/app` |
|
||||
| `redis://` / `rediss://` | Redis | `redis://127.0.0.1:6379/0` |
|
||||
| `memory:` | **进程内** Redis 兼容后端(金样/离线) | `memory:` |
|
||||
| `s3://bucket` + 查询参数 | S3 兼容(含 MinIO) | `s3://mybucket?endpoint=http://127.0.0.1:9000®ion=us-east-1` |
|
||||
| `file:` | **本地目录**对象存储(金样/离线) | `file:data/blobs` |
|
||||
|
||||
凭证:优先 URL 内嵌;S3 亦读环境变量 `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`(或 `S3_ACCESS_KEY` / `S3_SECRET_KEY`)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 作者面(代码即文档)
|
||||
|
||||
### 3.1 数据库 — 只换 URL
|
||||
|
||||
英文:
|
||||
|
||||
```markdown
|
||||
import web:ext/web/web.mq.md
|
||||
|
||||
# main
|
||||
|
||||
*store = > web.db url="postgres://marqdo:marqdo@127.0.0.1:5432/site"*
|
||||
*store = > store.init name="posts" fields=`schema`*
|
||||
```
|
||||
|
||||
中文:`网页.数据库` + `url=` 同形。`init` / `select` / `insert` / `paginate` / `事务` **API 不变**。
|
||||
|
||||
Postgres 差异(实现层消化,作者尽量无感):
|
||||
|
||||
- `id INTEGER PRIMARY KEY` → `SERIAL PRIMARY KEY`(或 `GENERATED …`)
|
||||
- 占位符 `?` → `$1,$2,…`
|
||||
- 标识符双引号规则对齐
|
||||
|
||||
### 3.2 缓存 `# cache` / `# 缓存`
|
||||
|
||||
```markdown
|
||||
*c = > web.cache url="memory:"*
|
||||
*c = > c.set key="k" value="v" ttl=60*
|
||||
*v = > c.get key="k"*
|
||||
*c = > c.del key="k"*
|
||||
```
|
||||
|
||||
方法:`get` · `set`(可选 `ttl` 秒)· `del` · `exists` · `ttl`。
|
||||
|
||||
配置表可选(装配时合并进 url / 默认 TTL):
|
||||
|
||||
| 键 | 值 |
|
||||
|----|-----|
|
||||
| url | redis://127.0.0.1:6379/0 |
|
||||
| ttl | 3600 |
|
||||
|
||||
### 3.3 对象存储 `# storage` / `# 存储`
|
||||
|
||||
```markdown
|
||||
*blob = > web.storage url="file:data/blobs"*
|
||||
> `blob`.put key="avatar/1.png" path="local.png" content_type="image/png"
|
||||
*got = > `blob`.get key="avatar/1.png"*
|
||||
> `blob`.delete key="avatar/1.png"
|
||||
*keys = > `blob`.list prefix="avatar/"*
|
||||
```
|
||||
|
||||
方法:`put`(`path=` 本地文件或 `body=` 文本)· `get`(返回 `{ok, body|path, content_type}`)· `delete` · `list`。
|
||||
|
||||
---
|
||||
|
||||
## 4. ABI 名
|
||||
|
||||
| ABI | 说明 |
|
||||
|-----|------|
|
||||
| 既有 `web_db_*` | 内部按 `url` 方案分发 SQLite / Postgres |
|
||||
| `web_cache_new/get/set/del/exists/ttl` | 缓存 |
|
||||
| `web_storage_new/put/get/delete/list` | 对象存储 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
| 金样 | 内容 |
|
||||
|------|------|
|
||||
| `tests/ext/web-drivers-smoke.mq.md` | `memory:` 缓存往返;`file:` 存储 put/get/list/delete;`web_db_new` 接受 `postgres://` 句柄形状(不要求本机有库) |
|
||||
| 可选 live | `MARQDO_TEST_POSTGRES` / `MARQDO_TEST_REDIS` / `MARQDO_TEST_S3` 非空时跑真实连通(CI 默认关) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 非本波次
|
||||
|
||||
- 连接池大小 / 读写分离配置表
|
||||
- Redis 集群 / Sentinel
|
||||
- S3 预签名 URL 作者面糖(可后续加方法)
|
||||
- 把 session 默认改存 Redis(仍默认 SQLite 表;可选后续)
|
||||
@@ -0,0 +1,285 @@
|
||||
# 网络扩展波次:`ext/web` 鉴权 · WebSocket · 标准库网络原语
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Draft(本波次锁定设计)** |
|
||||
| 日期 | 2026-08-24 |
|
||||
| 相关 | [ext-web.md](ext-web.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-cli.md](ext-cli.md) |
|
||||
| 目标 | 补齐 `ext/web` 登录鉴权(session/cookie)、WebSocket 端点;为网络扩展所需的**基础设施解析原语**适当补强 `lib/net`(标准库)。 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**领域能力(鉴权、WebSocket 服务器)全部走 ABI 插件 `plugins/web`;纯解析基础设施(cookie / multipart 解析、WS 客户端)按需进入标准库 `lib/net`,因为标准库需要支撑扩展库开发。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 边界判定:什么进标准库 `lib/net`,什么进扩展
|
||||
|
||||
### 1.1 跨语言调研结论
|
||||
|
||||
| 语言 | 标准库 | 扩展/生态 | 边界准则 |
|
||||
|------|--------|----------|---------|
|
||||
| Python | `urllib`(URL/基础 HTTP)、`http.cookies`(**cookie 解析器在标准库**) | `requests`/`httpx`(session/连接池/便利层) | 标准库 = 基础设施原语(解析器);便利层 = 第三方 |
|
||||
| Node.js | `http`/`https`/`http2`(低层流式,不解析 body) | express、ws、formidable | 足够 fancy 就不进核心;核心只放几乎人人要用的低层原语;**先 userland 验证再拉进 core** |
|
||||
| Go | `net/http`(服务器+客户端都在标准库)、`net/http/cookiejar`(**RFC 6265 cookie jar 在标准库**) | `golang.org/x/net`(publicsuffix 等演进性) | HTTP 是「与 stdin 同级」的核心能力;**cookie 解析/管理进标准库**;持久化等演进性能力在外 |
|
||||
| Rust | 极小 std(无 HTTP) | `http`(词汇)→ `hyper`(传输)→ `reqwest`(便利) | 分层;HTTP 因生态多样不进 std |
|
||||
|
||||
**共识**:
|
||||
1. **cookie 解析/管理(RFC 6265)**在 Python/Go 都是**标准库**(`http.cookies`、`net/http/cookiejar`)。
|
||||
2. **multipart/form-data 解析**在 Go 是标准库(`net/http`),在 Python 是第三方 `multipart`。
|
||||
3. **WebSocket** 几乎总在扩展/第三方(Node `ws`、Python `websockets`、Go `gorilla/websocket`),**很少进语言标准库**。
|
||||
4. **session 是领域级便利**,几乎所有语言都在框架层(express-session、Django session),不在语言标准库。
|
||||
|
||||
### 1.2 Marqdo 判定(锁定)
|
||||
|
||||
| 能力 | 类型 | 归属 | 理由 |
|
||||
|------|------|------|------|
|
||||
| `cookie.parse` / `cookie.parse_response` | 基础设施解析 | **`lib/net`(标准库)** | 对齐 Go/Python 标准库;`ext/web` 鉴权依赖 |
|
||||
| `multipart.parse` | 基础设施解析 | **`lib/net`(标准库)** | 对齐 Go 标准库;`ext/web` 文件上传依赖 |
|
||||
| `ws.connect`(客户端) | 基础连接 | **`plugins/web`(ABI)+ `ext/web`** | WS 栈(tokio-tungstenite)已在 web 插件依赖链;核心 `Cargo.toml` 锁定 rustc 1.81 不宜再引入 WS 栈;符合「尽量只 ABI」 |
|
||||
| `web.session_*`(session 管理) | 领域 | **`plugins/web`(ABI)+ `ext/web`** | session 是框架层便利,不进标准库 |
|
||||
| `/admin` 登录鉴权 | 领域 | **`plugins/web`(ABI)+ `ext/web`** | 网站领域能力 |
|
||||
| `web_ws`(服务器端点) | 领域 | **`plugins/web`(ABI)+ `ext/web`** | WebSocket 服务器是网站能力 |
|
||||
|
||||
**实现约束(用户要求)**:
|
||||
- 标准库新增的**解析原语**(cookie/multipart)是纯函数、无网络 I/O,作为 L0.5 宿主原语进 `src/host/`(与 `url_encode` 同模式),由 `lib/net` 薄包装——这符合「标准库需要支持扩展库开发」。
|
||||
- **涉及网络 I/O 的 WS 能力**(客户端 + 服务器端点)一律进 `plugins/web`(ABI v2),由 `ext/web` / `ext/web/网页.mq.md` 包装。核心运行时(rustc 1.81 锁定)**不再新增** WS 栈依赖。
|
||||
- **网站领域能力**(session、鉴权中间件)一律进 `plugins/web`(ABI v2),由 `ext/web` 包装。
|
||||
- **禁止**:为这些能力修改核心语法;禁止在 `src/host/` 塞领域逻辑。
|
||||
|
||||
---
|
||||
|
||||
## 2. 标准库 `lib/net` 新增(基础设施原语)
|
||||
|
||||
### 2.1 `cookie.parse` / `解析Cookie`
|
||||
- 形参:`text`(`Cookie:` 请求头或 `Set-Cookie:` 响应头)
|
||||
- 结果:`[{name, value, path, domain, expires, max_age, secure, http_only, same_site}]`
|
||||
- 行为:RFC 6265 解析;`Set-Cookie` 多 cookie 分条;无属性则字段为空。
|
||||
|
||||
**英文(`lib/net.mq.md`):**
|
||||
```markdown
|
||||
## cookie_parse
|
||||
+ `text`
|
||||
|
||||
**> host_cookie_parse text=`text`**
|
||||
```
|
||||
|
||||
**中文(`lib/网络.mq.md`):**
|
||||
```markdown
|
||||
## 解析Cookie
|
||||
+ `内容`
|
||||
|
||||
**> host_cookie_parse text=`内容`**
|
||||
```
|
||||
|
||||
### 2.2 `multipart.parse` / `解析多部分`
|
||||
- 形参:`body`(文本)、`boundary`
|
||||
- 结果:`[{name, filename, content_type, value}]`(`value` 为字段值;文件字段用 `filename` + `content_type` + `value`(base64 或文本))
|
||||
- 行为:解析 `multipart/form-data` 正文;字段名 → value;文件字段带 filename。
|
||||
|
||||
**英文:**
|
||||
```markdown
|
||||
## multipart_parse
|
||||
+ `body`
|
||||
+ `boundary`
|
||||
|
||||
**> host_multipart_parse body=`body` boundary=`boundary`**
|
||||
```
|
||||
|
||||
**中文:**
|
||||
```markdown
|
||||
## 解析多部分
|
||||
+ `正文`
|
||||
+ `边界`
|
||||
|
||||
**> host_multipart_parse body=`正文` boundary=`边界`**
|
||||
```
|
||||
|
||||
### 2.3 WebSocket 客户端 — 见 §3.4(`plugins/web` ABI)
|
||||
|
||||
WS 客户端为领域能力,放 `plugins/web`(ABI)而非标准库,理由见 §1.2。`lib/net` 不新增 WS 客户端包装,避免标准库依赖 ext 插件。
|
||||
|
||||
---
|
||||
|
||||
## 3. `plugins/web`(ABI v2)新增:领域能力
|
||||
|
||||
### 3.1 Session 存储(`web_session_*`)
|
||||
插件进程内 `static` 内存存储(`HashMap<session_id, HashMap<String,Value>>`),与 `web_listen` 同生命周期。
|
||||
|
||||
| ABI 名 | 形参 | 结果 |
|
||||
|--------|------|------|
|
||||
| `web_session_new` | 可选 `ttl_sec` | `{id}`(新 session id) |
|
||||
| `web_session_set` | `id`, `key`, `value` | `{ok:true}` |
|
||||
| `web_session_get` | `id`, `key` | 值或 `{ok:false}` |
|
||||
| `web_session_del` | `id`, `key` | `{ok:true}` |
|
||||
| `web_session_destroy` | `id` | `{ok:true}` |
|
||||
|
||||
### 3.2 `/admin` 登录鉴权(`web_auth_*`)
|
||||
- 作者面:`web.auth` 类(`网页.鉴权`),形参 `admin_users`(`|用户名|密码|` 表)、可选 `session_ttl`。
|
||||
- `listen` 时若配置了 auth:`/admin*` 未登录 → 跳转 `/admin/login`;登录页 `POST` → 校验 `admin_users` 表 → 写 session cookie → 重定向。
|
||||
- 登出:`/admin/logout` → 销毁 session。
|
||||
|
||||
| ABI 名 | 形参 | 结果 |
|
||||
|--------|------|------|
|
||||
| `web_auth_login` | `username`, `password`, `users`, `session_ttl` | `{ok:true, session_id}` 或 `{ok:false}` |
|
||||
| `web_auth_check` | `session_id`, `users` | `{ok:true}` 或 `{ok:false}` |
|
||||
| `web_auth_logout` | `session_id` | `{ok:true}` |
|
||||
|
||||
### 3.3 WebSocket 服务器端点(`web_ws_route`)
|
||||
- 作者面:`app.route_ws` / `应用.路由实时`,形参 `path`、可选 `echo=True`。
|
||||
- `listen` 时 `{path}` 升级为 WS:`echo=True` 回发原文;否则接收并丢弃(扩展点)。
|
||||
|
||||
| ABI 名 | 形参 | 结果 |
|
||||
|--------|------|------|
|
||||
| `web_app_route_ws` | `app`, `path`, `echo` | `{app}`(登记 WS 端点) |
|
||||
|
||||
### 3.4 WebSocket 客户端(`web_ws_connect`)
|
||||
- 作者面:`web.ws` / `网页.实时`,形参 `url`、`message`、可选 `headers`、`timeout_sec`。
|
||||
- 行为:客户端连接一次 WS,发 `message`,收**全部**服务器回文后关闭。**单请求-响应式**(非长驻),与 Marqdo 同步模型一致。
|
||||
|
||||
| ABI 名 | 形参 | 结果 |
|
||||
|--------|------|------|
|
||||
| `web_ws_connect` | `url`, `message`, `headers`(map), `timeout_sec` | `{ok:true, messages:[…]}` 或 `{ok:false, error}` |
|
||||
|
||||
**英文(`ext/web/web.mq.md`):**
|
||||
```markdown
|
||||
# ws
|
||||
+ `timeout_sec`=30
|
||||
|
||||
## connect
|
||||
+ `url`
|
||||
+ `message`
|
||||
+ `headers`=None
|
||||
```
|
||||
|
||||
**中文(`ext/web/网页.mq.md`):**
|
||||
```markdown
|
||||
# 实时
|
||||
+ `超时秒`=30
|
||||
|
||||
## 连接
|
||||
+ `地址`
|
||||
+ `消息`
|
||||
+ `headers`=None
|
||||
```
|
||||
|
||||
> `plugins/web` 用 `tokio-tungstenite`(与 axum WS 同栈,版本兼容 rustc 1.81)。
|
||||
|
||||
---
|
||||
|
||||
## 4. `ext/web` 作者面新增
|
||||
|
||||
### 4.1 英文面(`web.mq.md`)
|
||||
|
||||
```markdown
|
||||
# auth
|
||||
+ `users` # |用户名|密码| 表
|
||||
+ `session_ttl`=3600
|
||||
|
||||
## login
|
||||
+ `username`
|
||||
+ `password`
|
||||
|
||||
## check
|
||||
+ `session_id`
|
||||
|
||||
## logout
|
||||
+ `session_id`
|
||||
```
|
||||
|
||||
`# app` 新增 `## route_ws`:
|
||||
```markdown
|
||||
## route_ws
|
||||
+ `path`
|
||||
+ `echo`=True
|
||||
```
|
||||
|
||||
### 4.2 中文面(`网页.mq.md`)
|
||||
|
||||
```markdown
|
||||
# 鉴权
|
||||
+ `用户表`
|
||||
+ `会话时长`=3600
|
||||
|
||||
## 登录
|
||||
+ `用户名`
|
||||
+ `密码`
|
||||
|
||||
## 校验
|
||||
+ `会话id`
|
||||
|
||||
## 登出
|
||||
+ `会话id`
|
||||
```
|
||||
|
||||
`# 应用` 新增 `## 路由实时`:
|
||||
```markdown
|
||||
## 路由实时
|
||||
+ `路径`
|
||||
+ `回显`=真
|
||||
```
|
||||
|
||||
### 4.3 用法示例(英文)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`admins` =
|
||||
| 用户名 | 密码 |
|
||||
|--------|------|
|
||||
| admin | secret |
|
||||
|
||||
*store = > db.open *
|
||||
*page = > web.page title="Site" *
|
||||
*app = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
|
||||
*app = > `app`.route_ws path="/live" echo=True *
|
||||
*app = > web.auth users=`admins` *
|
||||
> `app`.listen
|
||||
|
||||
*echo = > web.ws.connect url="ws://127.0.0.1:18081/live" message="hi" *
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. form 完善(现有功能验证 + 补测试)
|
||||
|
||||
现状已具备(无需改代码,需验证):
|
||||
- `action=update`:hidden `id` + `db.update`(form.rs `from_schema`/`submit` 已实现)
|
||||
- 校验失败页级回显:`submit_and_respond` → `render_page_ex`(http.rs 已实现)
|
||||
|
||||
本波次为 update 流程和页级回显补 gold 测试,确认端到端可用。
|
||||
|
||||
---
|
||||
|
||||
## 6. 测试与验收
|
||||
|
||||
| 测试 | 内容 |
|
||||
|------|------|
|
||||
| `tests/ext/web-net-smoke.mq.md` | session new/set/get/del + auth login/check/logout + `route_ws`/`app.auth` 登记 + ws 连接失败路径(离线) |
|
||||
| `tests/lib/net-cookie.mq.md` | `cookie_parse` 解析 |
|
||||
| `tests/lib/net-multipart.mq.md` | `multipart_parse` 解析 |
|
||||
| `tests/ext/web-admin-smoke.mq.md` | form `action=update` 全流程 + 校验失败 `errors` 回显 |
|
||||
| 现有 gold | 全量回归(树遍历 + 字节码) |
|
||||
|
||||
验收:`cargo test --test gold` 全绿(除网络 live),双后端一致。
|
||||
|
||||
### 6.1 字典操作约束(作者面)
|
||||
|
||||
Marqdo 原生字典操作:GFM 横表**构造**、脚注取元 `变量[^键]` **读取**。`ext/web` 作者面**不使用** `json.get` / `json.set` 做字典读取/改写——所有字段读取一律 `self[^键]`(或实例变量 `[^键]`),避免"用 json 标准库做字典操作"的反模式。`json.parse` / `json.stringify` 仅用于文本 ↔ 结构化数据的序列化转换(如 HTTP body 解析),不用于本地字典读写。
|
||||
|
||||
### 6.2 相对路径按入口脚本解析(host_query `entry_dir`)
|
||||
|
||||
`static_dir`(如 `public`)与相对 db 路径(如 `sqlite:data/site.db`)此前按**进程 cwd** 解析——从仓库根目录跑 `examples/*/index.mq.md` 时,`/static` 404、db 会建到根目录,这是错误行为。
|
||||
|
||||
本波次修复:宿主新增 `host_query("entry_dir")`(返回入口 `.mq.md` 所在目录的绝对路径,回退 cwd),`plugins/web` 的 `web_listen` 将相对 `static_dir`、`db_url_of` 将相对 db 路径统一 `entry_dir().join(...)` 到绝对路径。于是无论从仓库根目录还是示例目录运行,静态资源与数据库都落在**脚本目录**下。绝对路径不受影响;`host_query` 不可用时回退旧 cwd 行为。
|
||||
|
||||
---
|
||||
|
||||
## 7. 非本波次
|
||||
|
||||
- Postgres / Redis / S3 驱动(roadmap W4,另行)
|
||||
- WS 广播房间、多客户端(先 echo 单连接)
|
||||
- session 持久化到 SQLite / 文件(先内存)
|
||||
- 复杂权限 / RBAC
|
||||
@@ -0,0 +1,600 @@
|
||||
# 官方扩展:`ext/web` 动态网站
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · W0–W7 + P3 完结**(SQLite/Postgres 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / RBAC / 上传相册 / SEO·RSS·sitemap;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`(作者面唯一样板)
|
||||
|
||||
**语言与导入绑定(锁定,纠正手写混用):**
|
||||
|
||||
| 导入 | 库名(默认茎) | 类 / 方法 / 形参 |
|
||||
|------|----------------|------------------|
|
||||
| `import web:ext/web/web.mq.md` | `web` | **仅英文**:`page` · `compose_components` · `db` · `app` · `components=` … |
|
||||
| `导入 网页:ext/web/网页.mq.md` | `网页` | **仅中文**:`页面` · `组件装配` · `数据库` · `应用` · `组件=` … |
|
||||
|
||||
禁止:`import web: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.
|
||||
import web:ext/web/web.mq.md
|
||||
import shell:styles/shell.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import side:components/side.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import articles:db/articles.mq.md
|
||||
import db:db/index.mq.md
|
||||
---
|
||||
|
||||
# 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
|
||||
import shell:styles/shell.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import side:components/side.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import articles:db/articles.mq.md
|
||||
import db:db/index.mq.md
|
||||
---
|
||||
|
||||
# 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) 为准** |
|
||||
---
|
||||
|
||||
## 决策
|
||||
@@ -28,7 +28,7 @@ Marqdo 项目中的 **YAML(及由其组成的 OKF 风格知识包)是工具
|
||||
|
||||
**唯一手写真相**仍是 `.mq.md` 源文件正文。YAML 清单是派生工件;过时则重新生成,禁止当成第二套权威配置去手改(除非工具链明确支持的「生成后微调」流程,且须可复现)。
|
||||
|
||||
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `> other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
|
||||
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `import other:other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
|
||||
|
||||
---
|
||||
|
||||
@@ -149,11 +149,11 @@ Marqdo 有两层「文档」,不要混为一谈:
|
||||
|
||||
## 待决问题(后续 ADR)
|
||||
|
||||
- [ ] 生成物落盘路径(例如 `.marqdo/` vs `docs/catalog/`)及是否提交进 git
|
||||
- [ ] 单文件是否仍写入「生成型 frontmatter」,还是全部集中在工程级 OKF 包
|
||||
- [ ] 与 `Cargo.toml` 式「可手写包身份(name/version)」的边界:是否允许极少量非生成的包清单,与全自动 OKF 目录如何分工
|
||||
- [ ] `marqdo sync` / `marqdo doc` 命令的具体行为
|
||||
- [ ] 是否沿用 OKF v0.2 的 `generated` / `sources` 字段描述溯源
|
||||
- [x] 生成物默认路径:`.marqdo/`(`-o` 可改)— 见 [catalog-cli.md](catalog-cli.md)
|
||||
- [x] `marqdo catalog` / `sync`;静态用户文档:`marqdo view output` — 见 [view.md](view.md)
|
||||
- [ ] 是否提交生成物进 git(项目自定;CI 可校验干净生成)
|
||||
- [ ] 与「可手写包身份 name/version」的边界
|
||||
- [ ] 是否沿用 OKF v0.2 的 `sources` 等溯源字段
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,137 @@
|
||||
# 内置关键字 / 函数:中英双名(草案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定(已实现)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 原则 | **无需导入**;中英为**同一语义的别名**,不是语言模式开关 |
|
||||
| 相关 | [keywords.md](keywords.md) · [stdlib-i18n.md](stdlib-i18n.md) · [call-arguments.md](call-arguments.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
Marqdo 要中英文都能自然书写。标准库已约定「**库文件名区分语言**」(见 [stdlib-i18n.md](stdlib-i18n.md));对**不必导入**的一层——字面量关键字与极少内置函数——也要对等提供中文名。
|
||||
|
||||
正因为每增加一个内置名,就要同时维护中英(及日后更多语言)别名,所以:
|
||||
|
||||
> **关键字 / 内置必须少而精**——体积在「名字 × 语言」上放大,而不是在功能清单上堆满。
|
||||
|
||||
更多能力进可导入的 `lib/`,用中英**不同库文件、不同函数名**扩展,不膨胀解释器内核。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层(与标准库对齐)
|
||||
|
||||
| 层 | 是否导入 | 中英怎么区分 |
|
||||
|----|----------|--------------|
|
||||
| **L0 内核** | 否 | **同一文件内双名**:`print` ≡ `打印`;`True` ≡ `真` |
|
||||
| **L1 标准库** | 是(`import …:lib/…`) | **不同文件**:`text.mq.md` vs `文本.mq.md`(见 i18n 草案) |
|
||||
|
||||
L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英文,写中文名就用中文,可在同一程序里混用。
|
||||
|
||||
---
|
||||
|
||||
## 3. 范围:哪些要双名
|
||||
|
||||
### 3.1 字面量 / 逻辑关键字(词法保留)
|
||||
|
||||
控制流仍靠 Markdown(`#` `1.` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。形参用 `+`。
|
||||
|
||||
| 英文 | 中文(提案) | 备注 |
|
||||
|------|--------------|------|
|
||||
| `True` | `真` | 布尔真 |
|
||||
| `False` | `假` | 布尔假 |
|
||||
| `None` | `空` | 空值 |
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
中英文名均**不可作变量名**(同一保留集)。
|
||||
|
||||
### 3.2 内置函数(可调用、无需导入)
|
||||
|
||||
**仅**下列核心五项做中英双名(与「少而精」一致):
|
||||
|
||||
| 英文 | 中文(提案) | 作用 |
|
||||
|------|--------------|------|
|
||||
| `print` | `打印` | 写 stdout |
|
||||
| `input` | `输入` | 读一行 |
|
||||
| `len` | `长度` | 文本/表长度 |
|
||||
| `str` | `文本` | 转为显示文本 |
|
||||
| `int` | `整数` | 转为整数 |
|
||||
|
||||
形参名也提供中英别名(便于纯中文调用):
|
||||
|
||||
| 英文形参 | 中文形参 | 用于 |
|
||||
|----------|----------|------|
|
||||
| `text` | `内容` | `print` / `打印` |
|
||||
| `prompt` | `提示` | `input` / `输入` |
|
||||
| `value` | `值` | `len`/`str`/`int` 及对应中文名 |
|
||||
|
||||
示例(等价):
|
||||
|
||||
```markdown
|
||||
> print text=Hello
|
||||
> 打印 内容=你好
|
||||
|
||||
*`n` = > len `s`*
|
||||
*`n` = > 长度 值=`s`*
|
||||
```
|
||||
|
||||
### 3.3 明确不进 L0 双名表
|
||||
|
||||
下列若已在解释器中实现,视为**宿主原语 / 过渡 API**,**不**再批中文内核别名;应迁入或仅通过标准库暴露(中英分文件):
|
||||
|
||||
| 英文名 | 去向 |
|
||||
|--------|------|
|
||||
| `type` | L1 或维持实现细节,不进「关键字最少集」宣传 |
|
||||
| `trim` `split` `join` | L1:`lib/text.mq.md` / `lib/文本.mq.md` |
|
||||
| `at` | L1:`lib/table.mq.md` / `lib/表.mq.md` |
|
||||
|
||||
这样 L0 公开面 ≈ **6 个关键字词 ×2 + 5 个函数 ×2**,而不是「每个工具函数都 ×2」。
|
||||
|
||||
---
|
||||
|
||||
## 4. 语义规则
|
||||
|
||||
1. **别名等价**:中英文名绑定同一实现;诊断文案可用英文稳定串(金样例已有),用户文档中英均可举例。
|
||||
2. **可混用**:同一文件可同时出现 `print` 与 `打印`、`True` 与 `真`。
|
||||
3. **遮蔽**:用户 `# 打印` 与 `# print` 均会遮蔽对应内置名(实现阶段应警告)。
|
||||
4. **大小写**:英文关键字保持 Python 风格(`True`/`False`/`None`);中文无名感大小写问题。
|
||||
5. **扩语言**:日后日文等 → 再为 L0 增加第三个别名列;仍无「名字表」而非语言开关。标准库继续用**文件名**区分(见 i18n 草案)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与旧决议的关系
|
||||
|
||||
- 旧文「中文 `print` 废弃、统一为 `print`」:**废止**;改为正式双名 `print` / `打印`。
|
||||
- [keywords.md](keywords.md) 原则条「英文标识」改为「**内核双名;标准库分文件**」——实现阶段改正文。
|
||||
- 不引入中文控制流关键字(`如果`/`循环` 等);分支用 `1.` …,循环用 `-`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 文档与金样例义务(实现时)
|
||||
|
||||
| 项 | 要求 |
|
||||
|----|------|
|
||||
| `keywords.md` | L0 表改为中英并列;砍掉对 `trim`/`split`/… 的「内核关键字」宣传 |
|
||||
| `public/` | 英 / 中文件同目录并列(拉丁名 vs 中文名) |
|
||||
| `tests/` | 中文关键字 / `打印`·`长度` 等金样例;与英文样例对等 |
|
||||
| 诊断 | 位置格式不变;message 可暂维持英文,或中英均可接受(另开小节) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 实现备忘(暂不开发)
|
||||
|
||||
1. 词法 / 解析:字面量与 `and`/`or`/`not` 识别中文别名。
|
||||
2. 调用解析:内置表按别名归一到同一 `BuiltinId`。
|
||||
3. 形参绑定:`text`≡`内容`,`prompt`≡`提示`,`value`≡`值`。
|
||||
4. **不要**加 `lang:` 或全局「中文模式」。
|
||||
5. 与 [stdlib-i18n.md](stdlib-i18n.md) 一并落地时:先收束 L0 公开面,再铺 `lib/text` ↔ `lib/文本`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 一句话
|
||||
|
||||
**内核:中英别名、无需导入、必须少;标准库:中英分文件、靠导入路径选择——这样 Marqdo 才能中英文通用而不把解释器撑爆。**
|
||||
+51
-38
@@ -2,51 +2,65 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(前期够用) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 原则 | **英文**;参考 [Python](https://realpython.com/python-keywords/) 但远更少;控制流仍靠 Markdown 标记,不引入 `if`/`while`/`def` |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) |
|
||||
| 状态 | 已定(中英双名) |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 原则 | **少而精**;控制流靠 Markdown;内核中英**别名等价**(见 [keywords-i18n.md](keywords-i18n.md)) |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords-i18n.md](keywords-i18n.md) · [stdlib-i18n.md](stdlib-i18n.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计原则
|
||||
|
||||
1. **标记承担架构**:函数=`#`,分支=`+`,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
2. **英文标识**:内置与字面量用英文,便于工具高亮与国际协作。
|
||||
3. **学 Python 的边界**:Python 3 里 [`print` / `input` 是内置函数,不是关键字](https://realpython.com/python-keywords/);布尔与空值是字面量关键字。Marqdo 同样区分 **关键字** vs **内置函数名**。
|
||||
4. **宁少勿多**:前期只列执行 examples 所需;要加再进 ADR。
|
||||
1. **标记承担架构**:函数=`#`,**形参=`+`**,**分支=`1.`…**,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
2. **内核双名**:字面量 / 逻辑词 / 五个核心内置函数均有中英别名,**无需导入**,可混用。
|
||||
3. **学 Python 的边界**:区分 **关键字** vs **内置函数名**。
|
||||
4. **宁少勿多**:扩展能力进可导入标准库(中英分文件,见 [stdlib-i18n.md](stdlib-i18n.md))。
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键字(词法保留,不可作变量名)
|
||||
|
||||
| 关键字 | 含义 | 备注 |
|
||||
|--------|------|------|
|
||||
| `True` | 布尔真 | 对齐 Python 大小写 |
|
||||
| `False` | 布尔假 | |
|
||||
| `None` | 空值 | |
|
||||
| `and` | 逻辑与 | 表达式内 |
|
||||
| `or` | 逻辑或 | |
|
||||
| `not` | 逻辑非 | |
|
||||
| 英文 | 中文 | 含义 |
|
||||
|------|------|------|
|
||||
| `True` | `真` | 布尔真 |
|
||||
| `False` | `假` | 布尔假 |
|
||||
| `None` | `空` | 空值 |
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
**本期不引入:** `if` `else` `elif` `while` `for` `def` `class` `return` `import` `pass` `break` `continue` `in` `is` `lambda` …
|
||||
(`else` 分支臂仍用臂头单独的 `*` 标记,不是单词 `else`。)
|
||||
**不引入:** `if` `else` `while` `for` `def` `return` …(分支臂 `*` 不是单词 `else`。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 内置函数(可调用名,建议勿遮蔽)
|
||||
## 3. 内置函数(可调用,无需导入)
|
||||
|
||||
| 名称 | 作用 | 调用示例 |
|
||||
|------|------|----------|
|
||||
| `print` | 写到 stdout(副作用) | `> print text=Hello` 或 `> print Hello`(位置实参,见 [call-arguments.md](call-arguments.md)) |
|
||||
| `input` | 从 stdin 读一行(返回文本) | `*`name` = > input prompt=Name: *` |
|
||||
| 英文 | 中文 | 作用 |
|
||||
|------|------|------|
|
||||
| `print` | `打印` | 写 stdout |
|
||||
| `input` | `输入` | 读一行;capture / view 用 frontmatter `stdin:` / `输入:`、表单或 `--stdin-file` 预置 |
|
||||
| `len` | `长度` | 文本/表长度 |
|
||||
| `str` | `文本` | 转为显示文本 |
|
||||
| `int` | `整数` | 转为整数 |
|
||||
|
||||
参数约定(v0):
|
||||
**文本**:裸 token 按字面量;需 `\n` 等转义时用 `"..."`(见 [markdown-mapping.md](markdown-mapping.md) §7)。
|
||||
|
||||
- `print`:具名实参 `text`(必填);日后可扩展 `end` 等。
|
||||
- `input`:可选 `prompt`;返回用户输入字符串(不含换行)。
|
||||
形参别名:
|
||||
|
||||
旧文档中的中文 `print` **废弃**,统一为 `print`。
|
||||
| 英文 | 中文 | 用于 |
|
||||
|------|------|------|
|
||||
| `text` | `内容` | `print` / `打印` |
|
||||
| `prompt` | `提示` | `input` / `输入` |
|
||||
| `value` | `值` | `len`/`str`/`int` 及其中文名 |
|
||||
|
||||
```markdown
|
||||
> print text=Hello
|
||||
> 打印 内容=你好
|
||||
|
||||
*`n` = > 长度 值=`s`*
|
||||
```
|
||||
|
||||
宿主原语 `type` / `trim` / `split` / `join` / `at` **无**内核中文别名;文本/表扩展走标准库文件(见 [stdlib-i18n.md](stdlib-i18n.md))。转换错误见 [stdlib.md](stdlib.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -55,30 +69,29 @@
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
> 打印 内容=Hello World!
|
||||
|
||||
*`n` = 1*
|
||||
|
||||
+ `n` > 0
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
+ *
|
||||
> print text=other
|
||||
2. *
|
||||
> 打印 内容=other
|
||||
```
|
||||
|
||||
- `>` 是**调用标记**(架构)。
|
||||
- `print` 是**被调名字**(内置库)。
|
||||
- 用户自定义 `# print` 会遮蔽内置(实现应警告)。
|
||||
- `>` 是调用标记;`print` / `打印` 是同一内置的别名。
|
||||
- 用户 `# print` 或 `# 打印` 会遮蔽对应名字。
|
||||
|
||||
---
|
||||
|
||||
## 5. 标识符规则(摘要)
|
||||
|
||||
- 变量:行内 `` `name` ``;`name` 不可为上表关键字。
|
||||
- 函数名:`#` 标题文本;建议 ASCII/英文,中文标题仍允许但内置名保持英文。
|
||||
- 比较:`==` `>` `<` `>=` `<=`;逻辑:`and` `or` `not`。
|
||||
- 变量:`` `name` ``;不可为上表任一中英文关键字。
|
||||
- 函数名:`#` 标题;中英文均可。
|
||||
- 比较:`==` `>` `<` `>=` `<=`;逻辑:`and`/`且`、`or`/`或`、`not`/`非`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 后续可增(未批准)
|
||||
|
||||
`len`、`str`、`int`、`float`、`range`;以及 `break`/`continue`(若循环需要)。增加前开短 ADR。
|
||||
`float`、`range`;以及 `break`/`continue`。增加前开短 ADR,并同步考虑是否值得占用双名配额。
|
||||
+205
-61
@@ -1,11 +1,11 @@
|
||||
# Marqdo 语法映射 v0.1(Markup-as-Syntax)
|
||||
# Marqdo 语法映射 v0.2(Markup-as-Syntax)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定论(修订:语句 / 返回 / 输出职责分离) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 取代 | v0 中「`**`=输出、`*`=返回」 |
|
||||
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
|
||||
| 状态 | 已定论(修订:形参 `+`、分支 `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) · [module-namespace.md](module-namespace.md) |
|
||||
|
||||
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
|
||||
|
||||
@@ -14,50 +14,72 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
## 1. 哲学
|
||||
|
||||
1. `.mq.md`:打开即文档,运行即程序。
|
||||
2. **无标记行 = 叙述注释**(内部任何标记无语义)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. 作用域 = `#` 层数;入口 = `index.mq.md`。
|
||||
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
5. **标识符默认反引号**:形参、绑定、引用写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
|
||||
**豁免:**
|
||||
- foreach 头 `` - [项](集合) `` 允许裸名或反引号(可混用),推荐裸名;循环体内引用仍用 `` `名` ``。
|
||||
- 脚注取元 `` 名[^键] ``:基名在紧跟 `` [^…] `` 时可省略反引号(`` `名`[^键] `` 仍合法);链式同理。
|
||||
- **斜体语句 / 粗体返回内部**:裸标识符默认是**变量**(含调用实参与方法接收者);文本字面量须 `"…"` 或 `'…'` 或引号实参(`key="文本"`);`` `名` `` 仍合法。这是 **Python 统一命名空间**:裸点号 `a.b` 在 `a` 为局部变量时为方法调用,否则为库路径。
|
||||
|
||||
---
|
||||
|
||||
## 2. 行首判别
|
||||
## 2. 行首判别与成段注释
|
||||
|
||||
跳过前导空白后:
|
||||
跳过前导空白后,对**段首行**(空行之后的第一行,或文件起始):
|
||||
|
||||
| 首字符 | 分类 |
|
||||
|--------|------|
|
||||
| 普通文字 / 空 | **注释** |
|
||||
| 标记字符 | **代码** |
|
||||
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的分割线 `---` / `***`(见 §11)。
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
|
||||
|
||||
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
|
||||
|
||||
---
|
||||
|
||||
## 3. 映射总表(v0.1)
|
||||
## 3. 映射总表(v0.2)
|
||||
|
||||
| 标记 | 语义 |
|
||||
|------|------|
|
||||
| `#` … `######` | 函数;层数 = 作用域 |
|
||||
| 函数头下 `-` 纯名 | 形参 |
|
||||
| 体内 `-` | 循环 |
|
||||
| 体内 `+` 或 `1.` | 分支 |
|
||||
| 分支臂头整行恰为 `*` | else |
|
||||
| `#` … `######` | **`#` = 对象/类型**(可 `# Child = > Parent`);**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
|
||||
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
|
||||
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
|
||||
| 体内 `-` | **循环**(`while` 条件,或 `[项](集合)` / `` [`项`](`集合`) `` 遍历) |
|
||||
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
|
||||
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
|
||||
| frontmatter `> path.mq.md` | 跨文件导入 |
|
||||
| `` > `对象`.方法 … `` | 方法调用(独立 `>`;实例 map 须含 `_type`)。`*…*` 段内接收者裸名:`*x = > 对象.方法 …*` |
|
||||
| frontmatter `import bind:path.mq.md` / `导入` | 导入文件并绑定库名 |
|
||||
| frontmatter `import bind:lib.member` / `导入` | 将库路径成员绑为本地短名(与文件导入同形) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | 点号路径调用(路径段裸名、无反引号) |
|
||||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
||||
| `**…**` | **返回值**(架构级;函数结果) |
|
||||
| 无标记行 | 注释 |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| 无标记行 / 成段续行 | 注释(空行分段,见 §2) |
|
||||
| GFM 表格 | 集合 |
|
||||
| 空 RHS 赋值 + 后随 `$$…$$`(或同行 `$$…$$`) | **公式赋值** → 运行时 `formula`(见 [stdlib-math.md](stdlib-math.md));叙述面无名 `$$` 仅展示 |
|
||||
| ` ```lang ` | 外联异种代码 |
|
||||
| `---` / `***` | **可选**:框住分支/循环块(美化/分组;v0.1 不强制,见 §11) |
|
||||
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) |
|
||||
|
||||
### `+` / `-` / `1.` 消歧
|
||||
|
||||
| 位置 | `+` | `1.` … | `-` |
|
||||
|------|-----|--------|-----|
|
||||
| 函数标题后、**首条体语句前** | 形参:`` + `名` `` / `` + `名`=默认 `` | (非法) | (非法作形参) |
|
||||
| 函数体内 | (非法作分支) | 分支臂:`1. `条件`` / `2. *` | 循环 |
|
||||
|
||||
**分支从未使用 `+`。** 自 v0 起即采用 GFM 有序列表;`+` 在 v0.2 专用于形参,与 `-` 循环彻底分离。
|
||||
|
||||
### 输出不是架构
|
||||
|
||||
| 错误(旧) | 正确(v0.1) |
|
||||
| 错误(旧) | 正确(v0.2) |
|
||||
|------------|--------------|
|
||||
| `**Hello**` 表示打印 | `> print text=Hello` |
|
||||
| 中文名 `输出`(已废弃) | 统一英文内置 `print` |
|
||||
| 输出与返回抢粗体 | 粗体只表示 **返回** |
|
||||
| `+ `x` > 0` 作分支 | `1. `x` > 0` |
|
||||
| `- 谁` 作形参 | `` + `谁` `` |
|
||||
| `[果](篮子)` 裸名遍历 | **仍合法**(foreach 豁免);亦可用 `` [`果`](`篮子`) `` |
|
||||
|
||||
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
|
||||
|
||||
@@ -68,22 +90,27 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
### 程序语句(斜体)
|
||||
|
||||
```markdown
|
||||
*`x` = 1*
|
||||
|
||||
*`y` = `x` + 2*
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
*answer = ev[^message]*
|
||||
*亦可用 = 1*
|
||||
```
|
||||
|
||||
行首已是结构标记的构造(`#` `>` `+` `-` `|`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
斜体内部:裸标识符 = 变量;字符串写 `"…"` / `'…'`。行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
|
||||
### 返回值(粗体)
|
||||
|
||||
```markdown
|
||||
# 加一
|
||||
- n
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
**"ok"**
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
粗体内部与斜体相同的值语法(裸词 = 变量;文本须引号)。
|
||||
|
||||
### 输出(内置函数 `print`)
|
||||
|
||||
```markdown
|
||||
@@ -94,7 +121,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
### else 与斜体消歧
|
||||
|
||||
- 分支臂**第一行整行只有一个** `*` → else。
|
||||
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
|
||||
- `*中间有内容*` → 程序语句。
|
||||
- `**…**` → 返回(与 else 无关)。
|
||||
|
||||
@@ -102,14 +129,18 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
## 5. Frontmatter 与跨文件
|
||||
|
||||
同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。
|
||||
文件头 `---` 对为元信息。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
|
||||
|
||||
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 函数、作用域、提升
|
||||
## 6. 对象、函数、形参
|
||||
|
||||
规则同 v0。推荐:
|
||||
- `# Name`:对象(构造体);`# main` 为入口对象。
|
||||
- `# Child = > Parent`:单继承(基类须为已定义对象名;方法沿链查找,子类可覆盖)。见 [objects.md](objects.md) §5。
|
||||
- `##` / `###` …:函数或方法;挂在对象下则为方法。
|
||||
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -117,53 +148,166 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
> print text=Hello World!
|
||||
|
||||
## 加问候
|
||||
- 谁
|
||||
+ `谁`
|
||||
|
||||
**你好,`谁`**
|
||||
```
|
||||
|
||||
(需要打印时对返回值再 `> print`,或直接 `> print`。)
|
||||
可选形参:
|
||||
|
||||
形参 `- 名` → 体内 `` `名` ``。
|
||||
```markdown
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
```
|
||||
|
||||
方法体内自动绑定 `` `自` `` / `` `self` ``。
|
||||
|
||||
---
|
||||
|
||||
## 7. 绑定与比较
|
||||
## 7. 绑定、比较与字符串
|
||||
|
||||
| 写法 | 含义 |
|
||||
|------|------|
|
||||
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定(两种均允许;实现应统一) |
|
||||
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定 |
|
||||
| `` `x` == 1 `` | 相等比较 |
|
||||
| `"text"` | **双引号字符串**(复杂文本;见下) |
|
||||
| `hello` / `路径` | **裸 token**(无转义,按字面量) |
|
||||
|
||||
v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致;行首 `` ` `` 仍合法以便表格右值绑定。
|
||||
### 双引号字符串(复杂文本)
|
||||
|
||||
需要转义或嵌入变量时用 `"..."`;**裸 token 不转义**,保持文档简洁:
|
||||
|
||||
```markdown
|
||||
> input prompt="你叫什么名字\n"
|
||||
*`msg` = "Hello, `name`!\n"*
|
||||
```
|
||||
|
||||
| 转义 | 含义 |
|
||||
|------|------|
|
||||
| `\n` | 换行 |
|
||||
| `\t` | 制表 |
|
||||
| `\r` | 回车 |
|
||||
| `\\` | `\` |
|
||||
| `\"` | `"` |
|
||||
| `\'` | `'` |
|
||||
| `\xHH` | 十六进制字符(如 `\x22` → `"`) |
|
||||
| `\u{...}` | Unicode 码点(如 `\u{4e2d}` → `中`) |
|
||||
|
||||
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。未知转义(如 `\q`)按字面保留,不报错。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分支与循环
|
||||
|
||||
分支(`+` / 有序),循环(`-`),语义同 v0。臂体内打印改为调用 `print`:
|
||||
分支(**有序列表** `1.` `2.` …),循环(`-`):
|
||||
|
||||
```markdown
|
||||
*`x` = 0*
|
||||
|
||||
+ `x` > 0
|
||||
1. `x` > 0
|
||||
> print text=正数
|
||||
+ `x` < 0
|
||||
2. `x` < 0
|
||||
> print text=负数
|
||||
+ *
|
||||
3. *
|
||||
> print text=零
|
||||
```
|
||||
|
||||
```markdown
|
||||
*`bool_value` = True*
|
||||
|
||||
1. `bool_value` == True
|
||||
> print text=True
|
||||
2. *
|
||||
> 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
|
||||
- `n` > 0
|
||||
> print text=`n`
|
||||
*`n` = `n` - 1*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 个条目」。
|
||||
- 基名:`` `名`[^键] `` 与 `` 名[^键] `` 等价;无 `` [^ `` 时裸词仍是**文本字面量**(不是变量)。
|
||||
- **插值中的取元**:在调用实参值 / 引号字符串里,`` `变量` `` 后**紧跟**(无空白)`` [^…] `` 时按取元解析,而不是字面文本:`> print text=苹果单价:`水果价格`[^苹果]`;链式 `` `货架`[^苹果][^1] `` 同理。`` `变量` [^…] ``(有空白)则 `` [^…] `` 仍是文本。
|
||||
- 文末 `[^1]: …` 定义块仍是注释,与取元无关。
|
||||
- foreach:`List` 遍历元素;`Map` 遍历**键**(值用脚注取)。
|
||||
|
||||
---
|
||||
|
||||
@@ -172,40 +316,40 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
|
||||
1. 加载 `index.mq.md` + 导入。
|
||||
2. Pass1 收集定义。
|
||||
3. Pass2 执行 `# main`。
|
||||
4. `*` 语句、`**` 返回、`>` 调用、`+`/`-` 控制流、表绑定按语义执行;`> print` 写 stdout。
|
||||
4. `*` 语句、`**` 返回、`>` 调用、`1.` 分支、`-` 循环、表绑定按语义执行;`> print` 写 stdout。
|
||||
|
||||
---
|
||||
|
||||
## 11. 分割线框住分支/循环(可选、非强制)
|
||||
|
||||
允许用 `---` 或 `***` 将分支/循环块视觉框起来,便于阅读:
|
||||
## 11. 函数体结束(`---` / `***` / 空返回)
|
||||
|
||||
```markdown
|
||||
---
|
||||
+ `x` > 0
|
||||
> print text=正
|
||||
+ *
|
||||
> print text=其它
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| v0.1 | **不强制**;无框同样合法 |
|
||||
| 语义 | 若使用,框内仍是原列表语义;分割线本身不产生控制流 |
|
||||
| 保留 | 日后若缺「块」类关键语法,可升级分割线为强制块边界 |
|
||||
| 消歧 | 仅文件开头的 `---` 对 = frontmatter;函数体内成对/成段的 `---`/`***` = 可选框 |
|
||||
| `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** |
|
||||
| `****` / 空粗体 | 空返回(`None`),并结束本函数体 |
|
||||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息 |
|
||||
|
||||
---
|
||||
|
||||
## 12. v0.1 非目标
|
||||
## 12. v0.2 非目标
|
||||
|
||||
- break/continue、完整错误模型、静态类型、完整 FFI
|
||||
- 强制分割线框
|
||||
- 用 `*` 作无序列表符
|
||||
- `+` 作分支、`+`/`-` 作形参(**不保留**)
|
||||
|
||||
---
|
||||
|
||||
## 13. 示例索引
|
||||
|
||||
见 [`examples/`](../../examples/)。
|
||||
见 [`tests/`](../../tests/)。
|
||||
@@ -0,0 +1,220 @@
|
||||
# 模块命名空间(import / 点号寻址)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted;统一 `import bind:target` 已锁定** |
|
||||
| 日期 | 2026-08-13 |
|
||||
| 相关 | [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. 动机
|
||||
|
||||
加载器曾把每个导入文件的顶层 `#` / `##` **扁平合并**进同一全局函数表;同名则**后导入静默覆盖**。
|
||||
|
||||
后果:
|
||||
|
||||
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存。
|
||||
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
|
||||
- 旧 frontmatter `import path:path.mq.md` 对 Markdown / 编辑器不友好,且与调用标记 `>` 抢外形。
|
||||
|
||||
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为可读的 `import bind:target`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
### 2.1 目标
|
||||
|
||||
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
|
||||
2. **点号寻址调用**:`库.成员`、`库.对象.成员`;`.` 表示定义树寻址。
|
||||
3. **库名不是变量**:路径段为**裸标识符**,不加反引号。
|
||||
4. **短名与文件导入同形**:`import fmt:time.format`,废除独立 `use` 关键字。
|
||||
5. **中英对等**:`import` / `导入`。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
- 第三方包管理 / 版本求解。
|
||||
- 旧 `> path.mq.md` / `> use` 双轨兼容。
|
||||
- `` `time`.parse ``(库名加反引号)。
|
||||
- `import fmt:time.*` 通配。
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心语义
|
||||
|
||||
### 3.1 模块 / 库
|
||||
|
||||
| 内容 | 归属 |
|
||||
|------|------|
|
||||
| 顶层 `##` 自由函数 | 库根下的**函数** |
|
||||
| 顶层 `#` 对象 | 库根下的**类型(对象)** |
|
||||
| 类型下的 `##` 方法 | 该对象节点下的**成员函数** |
|
||||
| 被导入文件的 `# main` | **不**作为入口执行 |
|
||||
|
||||
### 3.2 导入句法(frontmatter)
|
||||
|
||||
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。
|
||||
|
||||
| 含义 | 英文 | 中文 |
|
||||
|------|------|------|
|
||||
| 导入文件 | `import utils:utils.mq.md` | `导入 utils:utils.mq.md` |
|
||||
| 标准库 | `import json:lib/json.mq.md` | `导入 json:lib/json.mq.md` |
|
||||
| 短名(成员) | `import fmt:time.format` | `导入 fmt:时间.格式化` |
|
||||
|
||||
规则:
|
||||
|
||||
- **绑定名必填**,在 `:` 左侧(裸名,无反引号)。
|
||||
- `:` 右侧 `target`:
|
||||
- 以 `.mq.md` 结尾 → **文件导入**;
|
||||
- 否则为 **点号路径**(≥2 段),把该成员绑为本地短名(须先有对应文件导入)。
|
||||
- 同一文件内绑定名不得冲突(文件库名与短名共用命名空间)→ 硬错误。
|
||||
- 旧写法 `> ….mq.md`、`> … as …`、`> use …`、`> 使用 …` → **硬错误**,并提示新句法。
|
||||
|
||||
### 3.3 废除的旧规则
|
||||
|
||||
不再支持:
|
||||
|
||||
- 省略绑定名时用文件名茎作库名;
|
||||
- 导入侧 `as` / `作为`;
|
||||
- 独立关键字 `use` / `使用`。
|
||||
|
||||
### 3.4 调用解析顺序
|
||||
|
||||
1. **点号路径 callee**(§4)→ 按段在导入库 / 类型树上寻址。
|
||||
2. **当前文件**顶层 `#` / `##` 与 frontmatter **短名绑定**。
|
||||
3. **L0 内置**。
|
||||
4. **插件注册名**。
|
||||
5. 否则 → 未知 callee。
|
||||
|
||||
---
|
||||
|
||||
## 4. 点号寻址(核心外形)
|
||||
|
||||
### 4.1 文法
|
||||
|
||||
```text
|
||||
path_callee ::= ident ('.' ident)+
|
||||
```
|
||||
|
||||
### 4.2 二段:`库.成员`
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import json: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`
|
||||
```
|
||||
|
||||
### 4.3 三段:`库.对象.成员`
|
||||
|
||||
```markdown
|
||||
> agent.agent # 库 → 类型:构造
|
||||
```
|
||||
|
||||
实例方法须 `` > `var`.method ``;无接收者的 `库.类型.方法` → 硬错误。
|
||||
|
||||
### 4.4 变量 / 实例 vs 库路径(Python 统一命名空间)
|
||||
|
||||
| 写法 | 含义 |
|
||||
|------|------|
|
||||
| `time.parse` | 库路径(裸名,第一段非变量) |
|
||||
| `` > `助手`.step `` | 独立 `>` 调用:实例方法(接收者反引号) |
|
||||
| `*回复 = > 助手.step …*` | `*…*` 段内:若 `助手` 是变量 → 实例方法;否则 → 库路径 |
|
||||
|
||||
**统一规则**(与 Python 一致):对裸点号 `a.b`,当 `a` 是当前作用域**局部变量**时解释为**方法调用**(`a` 为接收者);否则解释为**库路径**(`lib.a.b`)。此规则同时应用于树遍历与字节码两后端。
|
||||
|
||||
- 在**独立 `>` 调用**中裸词 = 文本,故方法接收者仍须反引号:`` > `助手`.step ``。
|
||||
- 在 **`*…*` / `**…**` 段内**裸词 = 变量,接收者不加反引号:`*回复 = 助手.step …*`。
|
||||
|
||||
### 4.5 短名示例
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import fmt:time.format
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*t = > time.now_unix*
|
||||
*s = > fmt unix=`t` pattern="%Y-%m-%d"*
|
||||
```
|
||||
|
||||
### 4.6 应用侧完整示例
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`助手` = > agent.agent model=… tools=… *
|
||||
*`out` = > `助手`.step task=… *
|
||||
*`body` = > json.stringify value=`out` *
|
||||
> writeback.record value=`body` key=ok
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 导出面
|
||||
|
||||
默认:库内顶层 `#` / `##` 均可被路径访问。本版不引入 `private`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 与旧行为的关系(破坏性变更)
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| `import time:lib/time.mq.md` | `import time:lib/time.mq.md` |
|
||||
| `import t`:lib/time.mq.md | `import t:lib/time.mq.md` |
|
||||
| `import fmt`:time.format
|
||||
| 茎名默认库名 | 绑定名始终显式 |
|
||||
| 扁平合并进全局 | 仅库绑定 + 可选短名 |
|
||||
|
||||
不提供旧 `>` 导入过渡开关。
|
||||
|
||||
---
|
||||
|
||||
## 7. 对分层与 ext 的影响
|
||||
|
||||
| 层 | 影响 |
|
||||
|----|------|
|
||||
| L0 内置 | 仍为全局短名 |
|
||||
| L1 / 官方 ext | 经库路径调用;**`ext/**/*.mq.md` 严禁 `host_*`** |
|
||||
| ABI 插件 | 插件注册表 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 实现要点
|
||||
|
||||
1. frontmatter 只解析 `import` / `导入` 行;右侧分流文件 / 成员。
|
||||
2. AST 仍用 `Import`(文件)与 `Use`(短名)存储,对外无 `use` 关键字。
|
||||
3. 金样例:`tests/structure/import/`、`tests/structure/ns/`。
|
||||
|
||||
| 阶段 | 内容 |
|
||||
|------|------|
|
||||
| M1+M2 | 点号路径 + 短名 — 已落地 |
|
||||
| **Import 句法** | 统一 `import bind:target` — **本波次** |
|
||||
|
||||
---
|
||||
|
||||
## 9. 决议摘要
|
||||
|
||||
1. 导入 = `import bind:target`(`导入` 等价)。
|
||||
2. target = `.mq.md` 文件 **或** `库.成员` 点号路径。
|
||||
3. 调用以裸名点号路径寻址;实例方法用反引号接收者(仅独立 `>` 调用;`*…*`/`**…**` 段内接收者不加反引号)。
|
||||
4. 裸点号 `a.b`:`a` 为局部变量 → 方法调用,否则 → 库路径(Python 统一命名空间)。
|
||||
@@ -0,0 +1,104 @@
|
||||
# Objects(`#`)与函数(`##`+)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | Accepted |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [ext-llm.md](ext-llm.md) |
|
||||
|
||||
## 1. 约定
|
||||
|
||||
| 标题层 | 含义 |
|
||||
|--------|------|
|
||||
| `#`(恰好一层) | **对象 / 类型**。正文 = 构造体;调用类型名 = 构造实例。 |
|
||||
| `##` 及更深 | **函数**(自由函数或方法)。层数差表示嵌套,与 v0.1 相同。 |
|
||||
|
||||
`# main` 是**入口对象**:运行文件 = 执行其构造体。若无 `main`,且文件恰好只有一个无参顶层 `#` 对象(如 `# Hello World`),则把它当作入口。
|
||||
|
||||
## 2. 实例句柄
|
||||
|
||||
构造返回值若为 `map`,运行时写入 `_type`(文本,值为类型名),形成句柄。
|
||||
方法调用通过 `_type` 找到定义对象,再解析其下的 `##` 方法。
|
||||
|
||||
方法体内自动绑定:
|
||||
|
||||
- `自`(中文)
|
||||
- `self`(英文)
|
||||
|
||||
二者同一接收者。
|
||||
|
||||
## 3. 调用外形
|
||||
|
||||
```markdown
|
||||
# 大模型
|
||||
+ `模型名`
|
||||
|
||||
*自 = …配置 map…*
|
||||
**自**
|
||||
|
||||
## 运行
|
||||
+ `提示`
|
||||
|
||||
…使用 `自` …
|
||||
**内容**
|
||||
|
||||
# main
|
||||
|
||||
*模型 = > 大模型 模型名="gpt-4o-mini"*
|
||||
*回复 = > 模型.运行 提示="你好"*
|
||||
> print text=`回复`
|
||||
```
|
||||
|
||||
- `> 大模型 …` — 构造
|
||||
- `` > `模型`.运行 … `` — 方法(接收者 + `.` + 方法名;**独立 `>` 调用**需反引号接收者 `` `模型` ``;**在 `*…*` / `**…**` 段内**接收者不加反引号:`*回复 = > 模型.运行 提示="你好"*`)
|
||||
- `## 自由函数` 挂在模块顶层(非某对象子标题)— 与旧版顶层 `# http_get` 对等,现写为 `## http_get`
|
||||
|
||||
## 4. 标准库
|
||||
|
||||
官方 `lib/*.mq.md` 以**顶层自由函数**为主:全部为 `##`(不再使用 `#` 冒充类型)。
|
||||
真正的类型化扩展(如 `ext/llm`)使用 `# 类型` + `##` 方法。
|
||||
|
||||
## 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(表格仍表示数据集合;见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md))
|
||||
|
||||
## 7. 迁移摘要
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| 库顶层 `# http_get` | `## http_get` |
|
||||
| `# main` + `## 嵌套` | 不变(main = 入口对象) |
|
||||
| `ext` 顶层 `# complete` | `# llm` / `# 大模型` 构造 + `## complete` / `## 运行` |
|
||||
@@ -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 分管工程目录与自我成长。**
|
||||
@@ -1,4 +1,4 @@
|
||||
# 解释器流水线可视调试
|
||||
# 解释器流水线可视调试
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -27,15 +27,17 @@ marqdo dump FILE --stage lines|tokens|ast|sema|all
|
||||
| `--dump-tokens` | 词法 | Token 流:`type lexeme line:col` |
|
||||
| `--dump-ast` | 语法 | S 表达式或缩进树(模块/函数/语句) |
|
||||
| `--dump-sema` | 语义 | 作用域、导入图、提升后的符号表 |
|
||||
| `--trace-eval` | 求值 | 进入/离开函数、绑定、分支臂选择、`print` 调用 |
|
||||
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(见 [bytecode.md](bytecode.md)) |
|
||||
| `--trace-eval` | 求值 | **JSON 行**(stderr):语句级事件,含 `path` / `span`(`line:col`) |
|
||||
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(指令旁带 `@line:col`;见 [bytecode.md](bytecode.md)) |
|
||||
| `--backend tree\|bytecode` | 执行后端 | 默认 `tree`;`bytecode` 走栈式 VM |
|
||||
| `--dump-all` | 以上全部 | 按管道顺序打印,段之间用横幅分隔 |
|
||||
|
||||
格式约定:
|
||||
|
||||
- 人类可读优先;段首统一:`=== marqdo: <stage> ===`
|
||||
- 可选 `--dump-format=text|json`(json 后置,text 先做)
|
||||
- dump 人类可读优先;段首统一:`=== marqdo: <stage> ===`
|
||||
- `--trace-eval`:每条事件一行 JSON,例如
|
||||
`{"event":"stmt","path":"…","span":"5:1","kind":"call","callee":"print"}`
|
||||
树遍历:`enter_fn` / `stmt` / `leave_fn`;字节码:`op`(`print`/`input`/`call`/`return`)。
|
||||
- 有 dump 时:若求值未实现,仍打印已实现阶段再以非 0 退出(便于 M1 只测 lines)
|
||||
|
||||
---
|
||||
@@ -43,7 +45,7 @@ marqdo dump FILE --stage lines|tokens|ast|sema|all
|
||||
## 3. 横幅示例
|
||||
|
||||
```
|
||||
=== marqdo: lines (examples/hello.mq.md) ===
|
||||
=== marqdo: lines (tests/structure/hello.mq.md) ===
|
||||
1 Blank
|
||||
2 Comment | # Hello World
|
||||
3 Blank
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已决议(并入 mapping v0.1 + keywords) |
|
||||
| 状态 | 已决议(并入 mapping v0.1 + keywords;2026-08-04 修订函数收束) |
|
||||
| 日期 | 2026-08-04 |
|
||||
|
||||
---
|
||||
@@ -10,9 +10,10 @@
|
||||
## 决议
|
||||
|
||||
1. **`*…*` = 程序语句**。
|
||||
2. **`**…**` = 返回值**(架构级)。
|
||||
2. **`**…**` = 返回值**(架构级);空粗体 `****` / `** **` = 空返回(`None`)并结束函数体。
|
||||
3. **输出**用内置函数 **`print`**(英文),不是粗体,不是中文名。
|
||||
4. **`---` / `***`**:可选框住分支/循环,不强制。
|
||||
5. **否决**:无标记行 = 默认代码。
|
||||
4. **`---` / `***`(函数体顶层)**:结束本函数体(无返回值函数收束);**不是**分支/循环装饰框。
|
||||
5. **成段注释**:空行分段;段内续行不因首字符升级为代码。
|
||||
6. **否决**:无标记行 = 默认代码。
|
||||
|
||||
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)。
|
||||
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)、[code-vs-comment.md](code-vs-comment.md)。
|
||||
@@ -0,0 +1,49 @@
|
||||
# 外联 / 胶水标准库
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(v1)** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原则
|
||||
|
||||
**导入即用**:`lib/foreign` / `lib/外联`。解释器来自用户本机(PATH / `set_cmd` / `MARQDO_FOREIGN_*`)。live view 可点 Run;静态导出展示源码,Run 禁用。
|
||||
|
||||
---
|
||||
|
||||
## 2. 绑定语法(与公式同构)
|
||||
|
||||
```markdown
|
||||
`hi` =
|
||||
```python
|
||||
print("hello")
|
||||
```
|
||||
|
||||
*`out` = > run code=`hi` *
|
||||
```
|
||||
|
||||
得到运行时类型 **`code`**(`lang` + `source`)。未绑定的 \`\`\` 围栏仍是叙述注释。
|
||||
|
||||
曾用的 \`\`\`python name=hi **已移除**。
|
||||
|
||||
---
|
||||
|
||||
## 3. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `set_cmd` | `设置命令` | `lang`, `cmd` | None |
|
||||
| `run` | `运行` | `code`(code 值) | 文本 stdout |
|
||||
| `run_lang` | `按语言运行` | `lang`, `source` | 文本 |
|
||||
| `langs` | `语言表` | | 列表 |
|
||||
|
||||
live view:Structure 中 code 卡片带命令框 + Run → `POST /api/foreign-run`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 一句话
|
||||
|
||||
**`name` = + \`\`\`lang 围栏 → code 值;显式 run;本机解释器可配置。**
|
||||
@@ -0,0 +1,146 @@
|
||||
# 标准库多语言命名(草案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **草案(先文档、后实现)** |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 原则 | **不指定语言**;靠**库文件名**区分中英(及日后其它语言) |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [keywords.md](keywords.md) · [keywords-i18n.md](keywords-i18n.md) · [user-site.md](user-site.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 要解决什么
|
||||
|
||||
- 内置(解释器里的名字)必须**少而精**;更多能力放进可 `>` 导入的标准库。
|
||||
- 标准库需要**中英两套 API**(函数名不同),并方便以后再加日文、西班牙文等。
|
||||
- **不要**用 frontmatter `lang:`、环境变量默认语言、或「同一导入路径再解析语言」——那是负累,也不符合「文档即代码」的直观性。
|
||||
|
||||
---
|
||||
|
||||
## 2. 方案(采用)
|
||||
|
||||
**导入哪个库文件,就用哪套函数名。**
|
||||
文件名本身表达语言;解释器只做路径解析,不做语言推断。
|
||||
|
||||
### 2.1 推荐:库名用目标语言书写
|
||||
|
||||
| 导入 | 库内函数名(示例) |
|
||||
|------|-------------------|
|
||||
| `import text:lib/text.mq.md` | `trim` · `split` · `join` |
|
||||
| `导入 文本:lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
|
||||
| `import table:lib/table.mq.md` | `put` · `rows` · `row_at` · list/map(见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| `导入 表:lib/表.mq.md` | `行数` · `取行` |
|
||||
|
||||
示例:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
*`xs` = > split value=a,b,c sep=,*
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
导入 文本:lib/文本.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
*`xs` = > 拆分 s=a,b,c sep=,*
|
||||
```
|
||||
|
||||
读者看到导入路径就能知道后面该用英文还是中文函数名——**无需再声明语言**。
|
||||
|
||||
### 2.2 可选:同概念用后缀区分(同目录、同「概念」)
|
||||
|
||||
若希望「同一概念」在文件名上仍共享拉丁词根,可用:
|
||||
|
||||
| 导入 | 含义 |
|
||||
|------|------|
|
||||
| `import text-en:lib/text-en.mq.md` | 英文 API |
|
||||
| `import text-zh:lib/text-zh.mq.md` | 中文 API |
|
||||
|
||||
这与 §2.1 **等价可选**,不是第二套解析器:仍然是「写哪个路径就加载哪个文件」。
|
||||
**优先推荐 §2.1**(`text` / `文本`),后缀形式留给需要 ASCII-only 路径的环境。
|
||||
|
||||
### 2.3 明确不做
|
||||
|
||||
| 不做 | 原因 |
|
||||
|------|------|
|
||||
| `lang: zh` / `MARQDO_LANG` | 隐式状态,难读、难测 |
|
||||
| `> std/text` 再按语言展开 | 多一次魔法 |
|
||||
| 同一文件内中英函数双份导出 | 遮蔽与文档混乱 |
|
||||
| 强制用户只许用中文或只许用英文 | Marqdo 本就多语言友好 |
|
||||
|
||||
---
|
||||
|
||||
## 2.4 特例:JSON
|
||||
|
||||
`JSON` 为专有缩写,**不强求**中文库名或中文 API 翻译。官方只提供:
|
||||
|
||||
```text
|
||||
lib/json.mq.md # 中英文档均 `import json:lib/json.mq.md`;函数 parse / stringify / get / keys
|
||||
```
|
||||
|
||||
不设 `lib/数据.mq.md` 等平行文件。其余模块仍遵守 §2.1。详见 [stdlib-modules.md](stdlib-modules.md) §3.4。
|
||||
|
||||
---
|
||||
|
||||
## 3. 与「少而精内置」的边界
|
||||
|
||||
| 层 | 内容 | 如何获得 |
|
||||
|----|------|----------|
|
||||
| **内置(L0)** | 极少:`print` `input` `len` `str` `int`(及语言字面量关键字) | 直接调用,无需导入 |
|
||||
| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `import …:lib/…` |
|
||||
| **宿主原语(实现细节)** | 若 `trim`/`split` 等暂由解释器实现 | 仅供标准库包装调用;**文档与用户站引导走 L1**,不鼓励当「关键字」堆砌 |
|
||||
|
||||
日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。
|
||||
|
||||
---
|
||||
|
||||
## 4. 目录与扩展约定
|
||||
|
||||
```text
|
||||
lib/
|
||||
text.mq.md / 文本.mq.md
|
||||
table.mq.md / 表.mq.md
|
||||
# 本波:fs/文件 · sys/系统 · time/时间 · json(中英同文件)· net/网络
|
||||
# 暂缓:math/数学 · foreign/外联
|
||||
# 其它语言:texte.mq.md / テキスト.mq.md …
|
||||
```
|
||||
|
||||
扩展新语言时:
|
||||
|
||||
1. **新加一个库文件**(文件名用该语言或 `概念-xx`)。
|
||||
2. 库内函数名用该语言习惯。
|
||||
3. 文档表增加一行映射;**无需改解释器语言开关**。
|
||||
|
||||
导入解析仍沿用现有规则:相对路径 → 官方 `lib/` 根(`MARQDO_LIB` / 工作区 `lib/` 等),**不增加语言分支**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 文档与示例义务
|
||||
|
||||
- 用户站:英/中库各一页(或同页两小节),导入路径与调用名并排;**JSON** 可共用一页、同一导入。
|
||||
- 金样例:分文件模块中英导入至少各一条;JSON 测 `lib/json.mq.md` 即可。
|
||||
- [keywords.md](keywords.md) 只列 L0;L1 指向本文 + [stdlib.md](stdlib.md) + [stdlib-modules.md](stdlib-modules.md)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 实现备忘(暂不开发)
|
||||
|
||||
实现阶段仅需:
|
||||
|
||||
1. 落地 `lib/text.mq.md` 与 `lib/文本.mq.md`(及 table / 表)两套文件与函数名。
|
||||
2. 更新导入示例与金样例;删除「仅中文库名」的单轨示例。
|
||||
3. **不要**实现 `lang:`、默认语言、或 `std/text` 自动选语言。
|
||||
|
||||
若历史上加过 `Module.lang` / `lang:` 解析,应撤回,与本草案对齐。
|
||||
|
||||
---
|
||||
|
||||
## 7. 一句话
|
||||
|
||||
**标准库用文件名区分语言(导入即选择);JSON 为缩写特例,中英共用 `lib/json.mq.md`——无语言开关。**
|
||||
@@ -0,0 +1,230 @@
|
||||
# 数学标准库(方案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已实现(M1–M4)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) |
|
||||
| 导入 | `lib/math.mq.md`(英)· `lib/数学.mq.md`(中) |
|
||||
| 范围 | **高中数学**(初等函数、导数、圆锥曲线、简单方程);非大学 CAS |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **公式类型**:解析 `$$…$$`(及行内 `$…$` 的可选支持),得到可绑定、可传递的 **`formula` 值**——语义上像「公式常量 / 公式变量」。
|
||||
2. **数学库对 `formula`(及文本表达式)做操作**:求值、化简、求导、求解、作图等。
|
||||
3. **数值 + 随机**:日常算术与可复现随机。
|
||||
4. **作图**:view / 静态页内嵌 SVG;CLI 写本地文件(可指定 `path`)。
|
||||
|
||||
**难度自觉:** 只覆盖高中知识面,自研小型表达式 AST + 规则即可,**不**追求 Mathematica / SymPy 完备性。
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心模型:`formula` 类型
|
||||
|
||||
### 2.1 运行时
|
||||
|
||||
| 类型 | `type` 标签 | 说明 |
|
||||
|------|-------------|------|
|
||||
| `Value::Num(f64)` | `num` | 浮点 |
|
||||
| `Value::Formula(…)` | `formula` | 已解析的表达式树(或等价内部表示) |
|
||||
|
||||
`print` / `str` 对 `formula`:输出规范 ASCII(如 `2*x + 1`)或保留源 LaTeX 的一种(实现时写死并文档化;建议 **ASCII 规范式** 便于测试)。
|
||||
|
||||
### 2.2 文档中的 `$$` = 公式赋值(与表格同构)
|
||||
|
||||
在可执行面用 **空 RHS 赋值** 后跟展示数学块,把公式绑到变量(与 `` `xs` = `` 后跟表格一致):
|
||||
|
||||
````markdown
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
sin(x) + x
|
||||
$$
|
||||
|
||||
*`df` = > diff formula=`f` var=x *
|
||||
|
||||
> plot formula=`f` var=x min=-3 max=3 path=f.svg
|
||||
````
|
||||
|
||||
也支持:
|
||||
|
||||
- 单行围栏:下一行 `$$x^2 - 2$$`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`
|
||||
|
||||
**废除:** `$$:name` / `$$ name=…` 模块级具名块(不再产生绑定)。
|
||||
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区若出现未挂在赋值上的裸 `$$` 围栏 → 报错,提示使用 `` `name` = `` + 围栏。
|
||||
|
||||
**行内 `$…$`:** v1 不做绑定;需要时用 `> formula text=…` 显式构造。
|
||||
|
||||
### 2.3 从文本构造
|
||||
|
||||
| 英文 | 中文 | 说明 |
|
||||
|------|------|------|
|
||||
| `formula` | `公式` | `text=` 解析为 `formula`(ASCII 或简单 LaTeX 子集) |
|
||||
|
||||
数学库函数形参统一接受:**`formula` 值**,或能解析的 **文本**(内部先 `formula` 化)。
|
||||
|
||||
### 2.4 与叙述面的关系
|
||||
|
||||
- `` `f` = `` + `$$…$$`:代码面赋值,得到 `formula` 值。
|
||||
- 成段注释里的 `$$`:仍是注释,不解析为公式。
|
||||
- view:公式赋值在 Structure 中显示为绑定,不是 comment。
|
||||
|
||||
(见 [markdown-mapping.md](markdown-mapping.md):空 RHS + `$$` → 公式赋值。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 知识范围(高中)
|
||||
|
||||
### 3.1 表达式与符号(S)
|
||||
|
||||
| 纳入 | 例子 |
|
||||
|------|------|
|
||||
| 多项式 | `x^2 - 3*x + 2` |
|
||||
| 初等函数 | `sin` `cos` `tan` `ln` `exp` `sqrt` `abs` |
|
||||
| 四则、幂 | `+ - * / ^` |
|
||||
| 化简 / 展开 | 合并同类项、基本三角恒等(小集合) |
|
||||
| 求导 | 单变元,初等函数求导法则 |
|
||||
| 代入求值 | `subs` → `num` 或公式 |
|
||||
| 求解 | 一元一次 / 二次闭式;其它用数值求根并标明 |
|
||||
|
||||
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、矩阵、复数完备、任意证明。
|
||||
|
||||
### 3.2 作图(P)
|
||||
|
||||
| 纳入 | 说明 |
|
||||
|------|------|
|
||||
| 显函数 `y=f(x)` | 采样折线 SVG |
|
||||
| 导数曲线 | 对 `formula` 先 `diff` 再画,或 `plot` 选项 `derivative=true` |
|
||||
| 圆锥曲线 | 标准形:圆、椭圆、双曲线、抛物线(参数方程或隐式采样) |
|
||||
| 点列 | `plot_points` |
|
||||
|
||||
**不做:** 三维、隐函数通用求解器、交互缩放(静态 SVG 足够)。
|
||||
|
||||
### 3.3 数值与随机(N)
|
||||
|
||||
常数、四则、三角、对数、取整、`num` 转换、`random` / `random_int` / `seed`(同前稿)。
|
||||
|
||||
---
|
||||
|
||||
## 4. API 草图(对 `formula` 操作)
|
||||
|
||||
### 4.1 构造与数值
|
||||
|
||||
| 英文 | 中文 | 要点 |
|
||||
|------|------|------|
|
||||
| `formula` | `公式` | 文本 → formula |
|
||||
| `pi` `e` | `圆周率` `自然底数` | → num |
|
||||
| `add`… / `sin`… | `加`… / `正弦`… | 对 num;若传入 formula 则返回 formula(符号)或报错——**v1 建议:算术函数只接 num;符号用 simplify/diff/subs** |
|
||||
| `eval` | `求值` | `formula` + 变量赋值 → num |
|
||||
| `random` / `random_int` / `seed` | `随机` / `随机整数` / `设种子` | 见前 |
|
||||
|
||||
### 4.2 符号
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `simplify` | `化简` | `formula` | formula |
|
||||
| `expand` | `展开` | `formula` | formula |
|
||||
| `diff` | `求导` | `formula`, `var` | formula |
|
||||
| `subs` | `代入` | `formula`, `var`, `value` | formula 或 num |
|
||||
| `solve` | `求解` | `formula`, `var`,可选区间 | list(num 或公式根) |
|
||||
|
||||
### 4.3 作图
|
||||
|
||||
| 英文 | 中文 | 形参 |
|
||||
|------|------|------|
|
||||
| `plot` | `绘图` | **`formula`**(或 `expr` 文本), `var`, `min`, `max`;可选 `steps`, `path`, `derivative`, **`grid`**(默认开;`False`/`假` 关) |
|
||||
| `plot_conic` | `绘圆锥` | `kind`(circle/ellipse/hyperbola/parabola)+ 系数;可选 `path`, `grid` |
|
||||
| `plot_points` | `绘点列` | `xs`, `ys`;可选 `path`, `grid` |
|
||||
|
||||
返回 **SVG 文本**;坐标轴带箭头与刻度,默认网格;写文件与 view 嵌入规则同前(§5)。
|
||||
|
||||
`diff` / `simplify` / `expand` / 未完全数值化的 `subs` 返回 **`formula`**,可继续链式调用。
|
||||
|
||||
示例:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*`roots` = > solve formula=`f` var=x *
|
||||
|
||||
> print text=`roots`
|
||||
|
||||
*`svg` = > plot formula=`f` var=x min=-3 max=3 path=parabola.svg *
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 作图:CLI / view / 静态(不变精神)
|
||||
|
||||
| 场景 | 行为 |
|
||||
|------|------|
|
||||
| 带 `path=` | 写 SVG 到该路径(沙箱内) |
|
||||
| CLI 无 path | 自动 `{stem}-plot-{n}.svg` + 一行 `plot: …` |
|
||||
| view / 导出无 path | 不强制写盘;加入 **plots 产物列表**,Execution 内嵌 |
|
||||
| view / 导出有 path | 写盘 + 内嵌 |
|
||||
|
||||
不把整段 SVG 默认灌进 CLI stdout。
|
||||
|
||||
---
|
||||
|
||||
## 6. 分期
|
||||
|
||||
| 期 | 交付 |
|
||||
|----|------|
|
||||
| **M1** | `Num` + 数值/随机;`Formula` AST + `` `name` = `` + `$$…$$` 赋值绑定 |
|
||||
| **M2** | `simplify` / `diff` / `subs` / `eval` / 二次 `solve`(高中子集) |
|
||||
| **M3** | `plot` / `plot_points` / `plot_conic` + view 内嵌 + path 写盘 |
|
||||
| **M4** | 用户文档 `public/stdlib/math*` · 金样例 · mapping 文档补丁 |
|
||||
|
||||
M1–M3 可在同一发版列车上连续落地;验收以「公式赋值 → 求导 → 作图」一条龙为准。
|
||||
|
||||
---
|
||||
|
||||
## 7. 实现要点
|
||||
|
||||
```text
|
||||
src/formula/ # 词法/AST/化简/求导/求值(高中规则表)
|
||||
src/host/math.rs # 数值、随机、对 formula 的 host 入口
|
||||
src/host/plot.rs # SVG
|
||||
lex/parse:空 RHS 赋值 + $$ 围栏 → Expr::Formula
|
||||
Value::Num / Value::Formula
|
||||
Interpreter.plots: Vec<Stringimport math:lib/math.mq.md · lib/数学.mq.md
|
||||
```
|
||||
|
||||
依赖:纯 Rust;不绑 SymPy。公式复杂度、采样点、SVG 大小设硬上限。
|
||||
|
||||
---
|
||||
|
||||
## 8. 刻意不做
|
||||
|
||||
- `$$:name` 模块级具名绑定(已废除)。
|
||||
- 无名 `$$` 自动进运行时。
|
||||
- 大学级数 / 完备积分 / 定理证明。
|
||||
- 通用隐函数作图引擎。
|
||||
- 3D、交互式图表库。
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收
|
||||
|
||||
1. `` `f` = `` + `$$…$$` + `diff` / `solve` / `plot` 金样例(中英库)。
|
||||
2. 固定 `seed` 的随机金样例。
|
||||
3. `plot` + `path` 在 CLI 落盘;view HTML 含 `<svg`。
|
||||
4. `type` 对公式为 `formula`,对浮点为 `num`。
|
||||
5. view Structure 将公式赋值显示为绑定,而非 comment。
|
||||
|
||||
---
|
||||
|
||||
## 10. 一句话
|
||||
|
||||
**`` `f` = `` + `$$…$$` 产出 `formula` 值;数学库对它做高中范围的符号运算、求解与作图——数值与随机并行,图在 view 内嵌、在 CLI 写文件。**
|
||||
@@ -0,0 +1,195 @@
|
||||
# 标准库 L1 模块
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
|
||||
| 日期 | 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) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本与可选原生扩展。标准库**必须导入**才可用。
|
||||
|
||||
| 模块族 | 英文库 | 中文库 | 状态 |
|
||||
|--------|--------|--------|------|
|
||||
| 文本 | `lib/text.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` | 已有 |
|
||||
| JSON | `lib/json.mq.md` | **同文件** | 已有(含 `quote`) |
|
||||
| 网络 | `lib/net.mq.md` | `lib/网络.mq.md` | 已有(HTTPS + headers) |
|
||||
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | 已有 |
|
||||
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | 已有 |
|
||||
| **插件** | `lib/plugin.mq.md` | `lib/插件.mq.md` | **已有**(加载 C ABI 共享库) |
|
||||
| **自写回** | `lib/writeback.mq.md` | `lib/自写回.mq.md` | **已有**(Jupyter 式输出写回) |
|
||||
| **子任务** | `lib/subtask.mq.md` | `lib/子任务.mq.md` | **已有**(OS 子进程 + KillOnDrop) |
|
||||
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` — 见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层与实现分工
|
||||
|
||||
```text
|
||||
用户 .mq.md
|
||||
│ import fs:lib/fs.mq.md / import llm:ext/llm.mq.md
|
||||
▼
|
||||
L1 官方库 / 官方 ext(.mq.md)
|
||||
│
|
||||
▼
|
||||
L0.5 宿主原语(Rust)或 原生插件(ABI v1)
|
||||
│
|
||||
▼
|
||||
OS / HTTP / 时钟 / 共享库 …
|
||||
```
|
||||
|
||||
| 层 | 谁实现 | 用户是否直接调用 |
|
||||
|----|--------|------------------|
|
||||
| **L0** | 解释器内置 | 是(`print`/`len`/…) |
|
||||
| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装;ABI v2 `host_query` 仅插件可调 |
|
||||
| **L1 官方库** | `lib/*.mq.md` | **是** |
|
||||
| **官方 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 可选项 |
|
||||
|
||||
**无**扁平合并回退;**无**裸名双轨兼容。
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心模块 API(摘要)
|
||||
|
||||
文件 / 系统 / 时间 / JSON / 网络 API 见下文历史草图(已实现)。补充:
|
||||
|
||||
### 3.2 系统 — 已含 dotenv
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 新写入的键数量;缺文件 → `0`;不覆盖已有环境变量 |
|
||||
|
||||
### 3.4 JSON — 已含 `quote`
|
||||
|
||||
| 函数 | 形参 | 结果 |
|
||||
|------|------|------|
|
||||
| `quote` | `text` | JSON 字符串字面量(含引号) |
|
||||
|
||||
### 3.5 网络 — HTTPS
|
||||
|
||||
仅 **HTTP / HTTPS**(ureq);可选 `headers=`(map)、`content_type=`。
|
||||
|
||||
### 3.6 插件 — `plugin` / `插件`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `load` | `加载` | `path` / `路径` | 注册函数个数 |
|
||||
| `unload` | `卸载` | (无) | `None` |
|
||||
| `list` | `列出` | (无) | 已注册名列表 |
|
||||
|
||||
契约:[ext-abi.md](ext-abi.md)。路径受 cwd/fs_root 沙箱约束。
|
||||
|
||||
### 3.1–3.5 历史 API 草图
|
||||
|
||||
#### 文件 — `fs` / `文件`
|
||||
|
||||
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|
||||
|------|------|-----------------|------|
|
||||
| `read_text` | `读文本` | `path` / `路径` | 文本 |
|
||||
| `write_text` | `写文本` | `path`, `text` / `路径`, `内容` | `None` |
|
||||
| `append_text` | `追加文本` | 同上 | `None` |
|
||||
| `exists` | `存在` | `path` / `路径` | 布尔 |
|
||||
| `list_dir` | `列目录` | `path` / `路径` | 文本列表 |
|
||||
| `make_dir` | `建目录` | `path` / `路径` | `None` |
|
||||
| `remove` | `删除` | `path` / `路径` | `None` |
|
||||
|
||||
#### 系统 — `sys` / `系统`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `env_get` | `取环境` | `name` / `名` | 文本或 `None` |
|
||||
| `env_set` | `设环境` | `name`, `value` / `名`, `值` | `None` |
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 见上 |
|
||||
| `args` | `参数表` | (无) | 文本列表 |
|
||||
| `cwd` | `工作目录` | (无) | 文本 |
|
||||
| `exit` | `退出` | `code` / `码` | 不返回 |
|
||||
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码 |
|
||||
|
||||
#### 时间 — `time` / `时间`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `now_unix` | `此刻秒` | (无) | 整数(Unix 秒) |
|
||||
| `now_ms` | `此刻毫秒` | (无) | 整数 |
|
||||
| `format` | `格式化` | `unix`, `pattern` / `秒`, `格式` | 文本 |
|
||||
| `sleep_ms` | `睡眠毫秒` | `ms` / `毫秒` | `None` |
|
||||
| `parse` | `解析时间` | `text`, `pattern` / `内容`, `格式` | 整数秒或诊断失败 |
|
||||
|
||||
#### JSON — `json`
|
||||
|
||||
| 函数 | 形参 | 结果 |
|
||||
|------|------|------|
|
||||
| `parse` | `text` | 值 |
|
||||
| `stringify` | `value`, 可选 `indent` | JSON 文本 |
|
||||
| `get` | `value`, `key` | 值或 `None` |
|
||||
| `keys` | `value` | 文本列表 |
|
||||
| `quote` | `text` | JSON 字符串字面量 |
|
||||
|
||||
#### 网络 — `net` / `网络`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `http_get` | `获取` | `url` / `地址` | 响应文本 |
|
||||
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` / `headers` | 同上 |
|
||||
| `url_encode` | `编码地址` | `text` / `内容` | 文本 |
|
||||
|
||||
**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
|
||||
|
||||
---
|
||||
|
||||
## 4. 中英路径总表
|
||||
|
||||
```text
|
||||
lib/
|
||||
text.mq.md / 文本.mq.md
|
||||
table.mq.md / 表.mq.md
|
||||
fs.mq.md / 文件.mq.md
|
||||
sys.mq.md / 系统.mq.md
|
||||
time.mq.md / 时间.mq.md
|
||||
json.mq.md # 中英共用
|
||||
net.mq.md / 网络.mq.md
|
||||
math.mq.md / 数学.mq.md
|
||||
foreign.mq.md / 外联.mq.md
|
||||
plugin.mq.md / 插件.mq.md
|
||||
|
||||
ext/ # 非 stdlib
|
||||
llm.mq.md / 大模型.mq.md
|
||||
agent.mq.md / 智能体.mq.md
|
||||
```
|
||||
|
||||
别名:`std/…` ≡ `lib/…`。扩展解析:`MARQDO_EXT` / `./ext` / 二进制旁 `ext/`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 安全与 view / 静态导出
|
||||
|
||||
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**。差异仅在软退出 / sleep 钳制。相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。插件路径同沙箱。
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话
|
||||
|
||||
**L1 含文件 / 系统 / 时间 / JSON / 网络 / 数学 / 外联 / 插件;`ext/` 为可选官方扩展(llm、agent)。**
|
||||
@@ -0,0 +1,29 @@
|
||||
# 子任务标准库(subtask)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | v2 |
|
||||
| 库 | `lib/subtask.mq.md` · `lib/子任务.mq.md` |
|
||||
|
||||
## 定位
|
||||
|
||||
**并发**执行单元。`spawn` 四选一:
|
||||
|
||||
| 参数 | 执行方式 | `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`。
|
||||
|
||||
Host:`host_subtask_*`(`src/host/subtask.rs`)。
|
||||
@@ -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
|
||||
---
|
||||
import table: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_*`。
|
||||
@@ -0,0 +1,59 @@
|
||||
# 自写回标准库(writeback)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | v1 已落地 |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 库 | `lib/writeback.mq.md` · `lib/自写回.mq.md` |
|
||||
|
||||
## 定位
|
||||
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
|
||||
|
||||
## 存储格式
|
||||
|
||||
```markdown
|
||||
*`n` = > len value=`xs` *
|
||||
<!-- marqdo-out
|
||||
42
|
||||
-->
|
||||
```
|
||||
|
||||
命名槽(智能体成功/失败互不覆盖):
|
||||
|
||||
```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`、`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`);智能体侧经 `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)。
|
||||
@@ -0,0 +1,106 @@
|
||||
# 标准库(P2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 + L1 全模块落地** |
|
||||
| 日期 | 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)。
|
||||
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 分层
|
||||
|
||||
| 层 | 内容 |
|
||||
|----|------|
|
||||
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
|
||||
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
|
||||
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
|
||||
| **L2** | catalog / 用户站收录(随发版) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 内置一览(S0 + S1)
|
||||
|
||||
| 名 | 形参 | 结果 |
|
||||
|----|------|------|
|
||||
| `len` | `value` | 文本标量数或列表长度 |
|
||||
| `str` | `value` | 显示文本 |
|
||||
| `int` | `value` | 整数(失败 → 诊断) |
|
||||
| `type` | `value` | `none`/`bool`/`int`/`text`/`list`/`map` |
|
||||
| `trim` | `value` | 去首尾空白 |
|
||||
| `split` | `value`, `sep` | 文本列表 |
|
||||
| `join` | `value`, `sep` | 拼接文本 |
|
||||
| `at` | `value`, `index` | 列表下标(越界 → `None`) |
|
||||
|
||||
表(单列表格)在运行时是 `list`:行数用 `len`,取行用 `at`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 官方库导入(S2)
|
||||
|
||||
Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可改)。成员经点号路径调用(`time.parse`、`json.get`),不倒进全局短名。完整语义见 [module-namespace.md](module-namespace.md)。
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
调用示例:`> time.now_unix`、`> json.parse text=…`。需要本地短名时用 `导入 format`(冲突:time.format`(冲突 → 硬错误)。
|
||||
|
||||
`std/text.mq.md` 等价于 `lib/text.mq.md`。解析顺序:
|
||||
|
||||
1. 相对当前文件
|
||||
2. `MARQDO_LIB`(可指向 `lib` 目录或仓库根)
|
||||
3. 当前工作目录的 `lib/`
|
||||
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
|
||||
5. **内嵌 stdlib**(v0.1.2+,编译进二进制;无磁盘 `lib/` 时自动使用)
|
||||
|
||||
当前模块(API 多为 `##` 自由函数;见 [objects.md](objects.md)):
|
||||
|
||||
| 路径 | 导出 |
|
||||
|------|------|
|
||||
| `lib/fs.mq.md` / `lib/文件.mq.md` | `read_text`… / `读文本`… |
|
||||
| `lib/time.mq.md` / `lib/时间.mq.md` | `now_unix`… / `此刻秒`… |
|
||||
| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`…、`load_dotenv`… / `取环境`…、`加载环境`… |
|
||||
| `lib/json.mq.md` | `parse` `stringify` `get` `keys` `quote`(中英同文件) |
|
||||
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`…(HTTPS)/ `获取`… |
|
||||
| `lib/math.mq.md` / `lib/数学.mq.md` | 数值 / 随机 / 公式 / 绘图 |
|
||||
| `lib/foreign.mq.md` / `lib/外联.mq.md` | 具名围栏外联 |
|
||||
| `lib/plugin.mq.md` / `lib/插件.mq.md` | `load` / `unload` / `list`(原生 ABI) |
|
||||
| `lib/writeback.mq.md` / `lib/自写回.mq.md` | `record` `get` `clear` `list` |
|
||||
| `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` | `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)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 转换错误约定(S3)
|
||||
|
||||
用户可见失败统一为:
|
||||
|
||||
```text
|
||||
path:line:col: message
|
||||
```
|
||||
|
||||
内置转换相关文案(稳定子集,金样例断言):
|
||||
|
||||
| 情况 | message |
|
||||
|------|---------|
|
||||
| 非法整数文本 | `cannot convert to int: "…"` |
|
||||
| `int` 类型不对 | `int needs int, bool, or text` |
|
||||
| `len` 类型不对 | `len needs text or list` |
|
||||
| `trim` 非文本 | `trim needs text` |
|
||||
| `split`/`join` 参数类型 | `split needs text value` 等 |
|
||||
| 空分隔符 | `split sep must not be empty` |
|
||||
|
||||
不引入独立异常类型对象;一律走 `Diagnostic`。
|
||||
@@ -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**。
|
||||
@@ -1,4 +1,4 @@
|
||||
# 参考实现:技术选型分析(尚未拍板)
|
||||
# 参考实现:技术选型分析(尚未拍板)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -18,7 +18,7 @@
|
||||
2. **对齐 GFM** 的结构:标题、列表(`-`/`+`/`1.`)、强调、表格、围栏、链接
|
||||
3. **Lower**:行首判别、标题树作用域、列表符语义、注释剥离
|
||||
4. **两遍**:收集定义 + 导入 → 求值
|
||||
5. **CLI** + **金样例测试**(`examples/`)
|
||||
5. **CLI** + **金样例测试**(`tests/`)
|
||||
|
||||
可选后期:字节码/编译、LSP、格式化。首版目标是**验证语法宪法**,不是上生产编译器。
|
||||
|
||||
@@ -51,7 +51,7 @@
|
||||
→ Marqdo AST
|
||||
→ 语义:导入图、提升、作用域
|
||||
→ 后端:解释器(v0)/日后编译
|
||||
→ 测试:examples → 期望 stdout
|
||||
→ 测试:tests 金样例 → 期望 stdout
|
||||
```
|
||||
|
||||
**前端可复用成熟 GFM 库,也可自研**;Middle/后端必须自研(这是语言本体)。
|
||||
@@ -130,7 +130,7 @@
|
||||
- 候选 A:TS + remark-gfm — 能否区分 `-`/`+` bullet、解析单列表格、读 strong/emphasis。
|
||||
- 候选 B:Rust + comrak/pulldown — 同上。
|
||||
- (可选)C 或 D 若团队有偏好再做。
|
||||
2. **对照验收用例**(固定):`examples/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `> x.mq.md` 的 frontmatter 行。
|
||||
2. **对照验收用例**(固定):`tests/structure/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `import x:x.mq.md` 的 frontmatter 行。
|
||||
3. **出 ADR**:选定「验证期实现」与(可选)「生产目标实现」是否同一语言。
|
||||
4. **再**建仓库脚手架与测试——禁止在 ADR 前默认生成 `package.json` / `Cargo.toml` 当既成事实。
|
||||
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# 用户静态文档站(public / gh-pages)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [view.md](view.md) · 源目录 [`public/`](../../public/) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 分工
|
||||
|
||||
| 路径 | 是否入库 | 职责 |
|
||||
|------|----------|------|
|
||||
| `doc/` | 是 | 开发者设计 / ADR / 路线图(单数 `doc`,勿再造 `docs/`) |
|
||||
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / **stdlib** / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列。stdlib 含 `plugin`;特性页覆盖对象与 `ext/`(llm / agent) |
|
||||
| `public/index.html`、`public/pages/` | **否**(ignore) | `marqdo view output` 生成的 HTML |
|
||||
| `tests/{structure,keywords,errors}/` | 是 | 金样例与失败夹具(含 errors) |
|
||||
| 远程分支 `gh-pages` | 发布产物 | 发布整个 `public/`(源文件 + 生成 HTML) |
|
||||
|
||||
**禁止**把 `tests/errors/` 编进用户站。
|
||||
|
||||
---
|
||||
|
||||
## 2. 生成
|
||||
|
||||
```bash
|
||||
cargo run --release -- view output public -o public
|
||||
# 或
|
||||
./scripts/build-public.sh
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
产物写在源旁:
|
||||
|
||||
```
|
||||
public/
|
||||
*.mq.md / structure/ / … # 入库源
|
||||
index.html # 生成(ignore)
|
||||
pages/… # 生成(ignore)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 发布分支
|
||||
|
||||
将构建后的 `public/` 推到 **`gh-pages`**。CI:`.github/workflows/pages.yml`。
|
||||
|
||||
仓库 Settings → Pages → Source = Deploy from branch → `gh-pages` / root。
|
||||
|
||||
---
|
||||
|
||||
## 4. 内容分层(用户站)
|
||||
|
||||
| 目录 | 内容 |
|
||||
|------|------|
|
||||
| `public/stdlib/` | L1 模块页(含 `plugin` / `插件`);概述注明 `ext/` 非 stdlib |
|
||||
| `public/features/` | 迭代特性:树遍历、字节码、view、**对象**、**官方扩展** |
|
||||
|
||||
设计文档仍在 `doc/design/`(`objects.md`、`ext-llm.md`、`ext-abi.md`、`ext-agent.md`)。
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. `public/` 下每个 `.mq.md`(除纯工具模块外)`marqdo run` 退出码 0。
|
||||
2. `view output public -o public` 后首页为欢迎页,侧栏无 errors。
|
||||
3. 主分支跟踪 `public/**/*.mq.md`;不提交 `public/index.html` / `public/pages/`。
|
||||
@@ -0,0 +1,42 @@
|
||||
# View 调试(`marqdo debug`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **v1(独立 debug 页)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
|
||||
## 分工
|
||||
|
||||
| 命令 | 角色 |
|
||||
|------|------|
|
||||
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
|
||||
|
||||
静态 `gh-pages` / `view output` **不能**真断点。
|
||||
|
||||
## Debug 布局(对齐常见调试器)
|
||||
|
||||
参考 VS Code / Chrome DevTools / Jupyter debugger:
|
||||
|
||||
```
|
||||
┌ Toolbar: Start · Continue (F5) · Step (F10) · Stop · status ─┐
|
||||
├ Files ─┬─ Structure (gutter BP) + outline ─┬─ Variables ┤
|
||||
│ │ ├─ Breakpoints │
|
||||
│ │ └─ Call stack │
|
||||
├────────┴────────────────────────────────────┴────────────────┤
|
||||
│ Debug Console (session stdout) │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- 暂停粒度:语句起点(树遍历)。
|
||||
- 无断点时 Start 停在第一句。
|
||||
- Structure 为断点面(非 Source 行)。
|
||||
|
||||
## API
|
||||
|
||||
与此前相同:`POST /api/debug/start|continue|step|stop|breakpoints`(仅 debug 服务)。
|
||||
|
||||
## View 大纲
|
||||
|
||||
Structure 旁(或窄屏下方)函数树:`#fn-{line}` 锚点 + 搜索框过滤 `data-fn` / `data-fn-path`。
|
||||
+117
-75
@@ -1,24 +1,44 @@
|
||||
# `marqdo view` — 源结构浏览器
|
||||
# `marqdo view` — 源结构浏览器与静态文档导出
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(实现中) |
|
||||
| 状态 | 已定(v0.0.2 方向) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [pipeline-debug.md](pipeline-debug.md) · AST(`src/ast.rs`) |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
`.mq.md` 既是文档也是程序。需要一种**可读渲染**,而不仅是纯文本或 `run` 的 stdout:
|
||||
`.mq.md` 既是文档也是程序。需要:
|
||||
|
||||
- 按语法树展示函数、分支、循环、调用、返回;
|
||||
- 同页展示**执行结果**;
|
||||
- 支持打开**单个文件**或**文件夹**(扫描全部 `.mq.md` + 结构索引)。
|
||||
1. **本地浏览**:按 AST 展示结构 + 执行结果;
|
||||
2. **静态导出**:同一套渲染写成 HTML,作为**用户文档站点**(勿手写第二套站点);
|
||||
3. **启动快**:样式极简,无外链字体/厚主题,避免 view 冷启动慢。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI
|
||||
## 2. 视觉(Apple HIG / Docs 极简)
|
||||
|
||||
对齐 [Apple HIG](https://developer.apple.com/design/human-interface-guidelines) 的 **clarity / deference / white space**,并参考常见 docs 布局(sticky 侧栏 + 居中主栏,见 Nextra / Docusaurus 类站点):**系统灰底、白内容面、浅分隔线、系统字体**。作者站 [id.cflmy.cn](https://id.cflmy.cn) 仍作克制感参考,但不强行纯黑描边。
|
||||
|
||||
| 规则 | 要求 |
|
||||
|------|------|
|
||||
| 色板 | 页底 `#f5f5f7`;内容面 `#ffffff`;正文 `#1d1d1f`;次要字 `#6e6e73`;分隔 `#d2d2d7`;选中侧栏项反白 |
|
||||
| 布局 | 壳层 `max-width ≈ 1680px`;侧栏 ≈280px;主内容 `max-width ≈ 76rem`;Structure 旁函数大纲;**≤800px 侧栏收起** |
|
||||
| 默认页 | 打开目录时 **直接展示排序后的第一个 `.mq.md`**(实时 `/` 与静态 `index.html` 同),不要求用户先从欢迎页点选 |
|
||||
| 字体 | 仅系统栈:`-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif`;等宽 `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` |
|
||||
| 外链 | **禁止** Google Fonts / CDN 样式;CSS 全部内联于 HTML |
|
||||
| 装饰 | 无多层阴影、无渐变、无发光;圆角 ≈12px;结构区为分组列表(底部分隔),非堆叠厚卡片 |
|
||||
| 诊断路径 | 展示时去掉 Windows `\\?\` 前缀,并优先用相对 view 根的路径 |
|
||||
|
||||
验收:首屏无外网字体请求;宽屏主栏明显宽于早期 `58rem` 方案(现约 `76rem` / 壳 `1680px`)。
|
||||
|
||||
---
|
||||
|
||||
## 3. CLI
|
||||
|
||||
### 3.1 实时浏览
|
||||
|
||||
```bash
|
||||
marqdo view [PATH] [--port PORT] [--host HOST] [--no-open]
|
||||
@@ -26,94 +46,116 @@ marqdo view [PATH] [--port PORT] [--host HOST] [--no-open]
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | `.mq.md` 文件,或目录(递归扫描 `*.mq.md`) |
|
||||
| `--port` | `7429` | HTTP 端口 |
|
||||
| `--host` | `127.0.0.1` | 仅本地 |
|
||||
| `--no-open` | 关 | 不尝试打开系统浏览器 |
|
||||
| `PATH` | `.` | `.mq.md` 或目录 |
|
||||
| `--port` | `7429` | |
|
||||
| `--host` | `127.0.0.1` | |
|
||||
| `--no-open` | 关 | 不打开浏览器 |
|
||||
|
||||
### 3.2 静态导出(文档生成)
|
||||
|
||||
```bash
|
||||
marqdo view output [PATH] -o OUT_DIR [--no-exec]
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 与 `view` 相同扫描范围 |
|
||||
| `-o` / `--out` | (必填) | 输出目录(不存在则创建) |
|
||||
| `--no-exec` | 关 | 不跑程序,执行区显示「skipped」 |
|
||||
|
||||
**产物布局:**
|
||||
|
||||
```
|
||||
OUT_DIR/
|
||||
index.html # 默认 = 排序后第一个 .mq.md 的完整页(侧栏高亮该项)
|
||||
pages/
|
||||
<相对路径>.html # 每个 .mq.md 一页;路径中的 `/` 保留为子目录
|
||||
# 例:structure/hello.mq.md → pages/structure/hello.mq.md.html
|
||||
```
|
||||
|
||||
- 页内链接一律**相对路径**,可用任意静态服务器或 `file://`(同目录结构下)打开。
|
||||
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
|
||||
- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
|
||||
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
|
||||
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
|
||||
|
||||
示例:
|
||||
|
||||
```bash
|
||||
marqdo view examples/structure/hello.mq.md
|
||||
marqdo view examples
|
||||
marqdo view examples/keywords --port 8080
|
||||
marqdo view output public -o public
|
||||
marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
```
|
||||
|
||||
启动后打印 `http://127.0.0.1:7429/`,阻塞直至 Ctrl+C。
|
||||
|
||||
---
|
||||
|
||||
## 3. 信息架构
|
||||
## 4. 信息架构
|
||||
|
||||
### 3.1 目录模式
|
||||
侧栏文件索引 + 主区:结构(AST+注释)· 执行 · 源码。结构旁**右侧栏**(现有 outline 槽)为:
|
||||
|
||||
```
|
||||
┌─────────────┬──────────────────────────────────┐
|
||||
│ 索引 │ 选中文件 / 欢迎页 │
|
||||
│ structure/ │ │
|
||||
│ hello │ [源码结构] [执行结果] [原始文本] │
|
||||
│ branch │ │
|
||||
│ keywords/ │ │
|
||||
└─────────────┴──────────────────────────────────┘
|
||||
```
|
||||
| 区块 | 内容 |
|
||||
|------|------|
|
||||
| **Functions** | 原函数大纲 + 搜索;可折叠(默认展开) |
|
||||
| **Variables** | 跑完后的入口(`# main`)顶层绑定只读快照;List/Map/`@` 行向渲成 HTML 表;可折叠(默认展开) |
|
||||
|
||||
- 侧栏:相对 `PATH` 的目录树;只列出 `.mq.md`。
|
||||
- 点击文件:主区切换为该文件的三栏/三节视图。
|
||||
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板。
|
||||
|
||||
### 3.2 单文件模式
|
||||
|
||||
无侧栏列表(或仅当前文件);主区同「选中文件」视图。仍提供「执行」结果。
|
||||
表达式为表面语法。**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 主区三节
|
||||
|
||||
### 4.1 源码结构(AST 渲染)
|
||||
|
||||
不依赖浏览器 Markdown 猜测语义,而用服务端已解析的 AST:
|
||||
|
||||
| AST 节点 | 视觉 |
|
||||
|----------|------|
|
||||
| `Function` | 卡片:标题层级、形参芯片、子函数嵌套;**中间的注释行仍展示**(来自源行分类,不在 AST 内) |
|
||||
| `Stmt::*` | 绑定 / 返回 / 调用 / 分支 / 循环;表达式用**表面语法**(如 `` `x` > 0 ``),不用 Debug |
|
||||
|
||||
样式:清晰分区,避免「通用仪表盘」堆砌;结构层级一眼可读。
|
||||
|
||||
### 4.2 执行结果
|
||||
|
||||
服务端对该文件跑与 `marqdo run` 相同的管线,**捕获 stdout/stderr** 与退出状态,展示在「输出」区。
|
||||
含 `input` 的程序:view 中标注「需交互,未在 view 执行」或提供只读说明(v0:跳过/失败信息)。
|
||||
|
||||
### 4.3 原始文本
|
||||
|
||||
等宽展示源文件;可选行分类着色(Code / Comment / Blank),与 `--dump-lines` 一致。
|
||||
|
||||
---
|
||||
|
||||
## 5. HTTP API(实现细节)
|
||||
## 5. HTTP(实时模式)
|
||||
|
||||
| 方法 | 路径 | 含义 |
|
||||
|------|------|------|
|
||||
| `GET` | `/` | 索引 HTML |
|
||||
| `GET` | `/file?path=…` | 单文件页(path 相对根,防 `..` 逃逸) |
|
||||
| `GET` | `/api/tree` | JSON 文件树 |
|
||||
| `GET` | `/api/file?path=…` | JSON:`{ source, ast_html 或 ast_json, stdout, stderr, ok }` |
|
||||
| `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` | 外联代码块试跑 |
|
||||
|
||||
v0 可全部服务端渲染 HTML,API 可选。
|
||||
根目录锁死;拒绝 `..` 逃逸。默认页加载仍可整页执行;Stream 为增强路径。
|
||||
|
||||
安全:根目录锁死为 CLI 给定的 `PATH`(若为文件则其父目录为根、仅一文件);拒绝根外路径。
|
||||
### 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` 为增量。
|
||||
|
||||
---
|
||||
|
||||
## 6. 依赖
|
||||
## 6. 验收
|
||||
|
||||
本地同步 HTTP 即可(如 `tiny_http`),无强制前端构建;HTML/CSS/少量 JS 内嵌于 Rust。
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收
|
||||
|
||||
1. `marqdo view examples/structure/hello.mq.md` 显示结构 + `Hello World!` 输出。
|
||||
2. `marqdo view examples` 侧栏含 `structure/` 与 `keywords/` 分组。
|
||||
3. 分支/循环样例在结构区可区分臂与循环体。
|
||||
4. 路径逃逸被拒绝。
|
||||
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件;函数大纲可搜索跳转。
|
||||
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
|
||||
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
|
||||
4. 冷启动无明显外网依赖。
|
||||
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
|
||||
6. Stream:`fetch`+SSE 局部更新;Thinking/Answer 分栏;stick-to-bottom;rAF 合批;页载不常连 EventSource。
|
||||
@@ -0,0 +1,82 @@
|
||||
# VS Code 扩展 — 分支与提交约定
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **强制约定**(勿在 `main` 提交扩展源码) |
|
||||
| 扩展分支 | **`vscode-extension`** |
|
||||
| 设计说明 | [vscode-extension.md](vscode-extension.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原则(必读)
|
||||
|
||||
| 分支 | 是否跟踪 `vscode-extension/` |
|
||||
|------|-------------------------------|
|
||||
| **`main`** | **否** — `.gitignore` 含 `/vscode-extension/` |
|
||||
| **`vscode-extension`** | **是** — 扩展唯一源码所在分支 |
|
||||
|
||||
**禁止**在 `main` 上:
|
||||
|
||||
- 删除 `.gitignore` 里的 `/vscode-extension/`
|
||||
- `git add vscode-extension/`
|
||||
- 把扩展目录「合并进 main」以便发版
|
||||
|
||||
发版时从 **`vscode-extension` 分支检出**扩展目录打 VSIX(见 §4),**不是**把扩展提交进 `main`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 日常开发(扩展)
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git checkout vscode-extension
|
||||
cd vscode-extension && npm ci && npm run compile
|
||||
```
|
||||
|
||||
改语法、CLI 检测、扩展版本 → **只在 `vscode-extension` 分支提交**:
|
||||
|
||||
```bash
|
||||
git add vscode-extension/
|
||||
git commit -m "vscode-extension: <简要说明>"
|
||||
git push origin vscode-extension
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 日常开发(CLI / 语言)
|
||||
|
||||
在 **`main`** 上改 `src/`、`lib/`、`public/`、`tests/` 等;**不要**顺带提交 `vscode-extension/`。
|
||||
|
||||
若本地为了调试 checkout 过扩展目录,工作区里可以有 `vscode-extension/` 文件夹,但应被 ignore,且 **`git status` 不应出现**该目录下文件。
|
||||
|
||||
---
|
||||
|
||||
## 4. 发版(CLI tag + VSIX)
|
||||
|
||||
1. **`main`**:打 tag(如 `v0.1.2`),CI 构建 `marqdo.exe` 等。
|
||||
2. **VSIX**:Release 工作流在 tag 构建时执行:
|
||||
```bash
|
||||
git fetch origin vscode-extension
|
||||
git checkout origin/vscode-extension -- vscode-extension
|
||||
cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package
|
||||
```
|
||||
3. 本地脚本 `scripts/release-windows.ps1` 同样假定:先 `git checkout origin/vscode-extension -- vscode-extension`(或已在 `vscode-extension` 分支),再打 VSIX。
|
||||
|
||||
扩展版本号与最低 CLI 要求写在 **`vscode-extension/package.json`** 与分支 README,**不要**在 `main` 的 CHANGELOG 里冒充已合并扩展源码。
|
||||
|
||||
---
|
||||
|
||||
## 5. 给 Agent / 协作者
|
||||
|
||||
执行「更新 VS Code 插件」类任务时:
|
||||
|
||||
1. **切到或基于 `vscode-extension` 分支**改 `vscode-extension/**`
|
||||
2. **不要**移除 `main` 上 `.gitignore` 的 `/vscode-extension/`
|
||||
3. **不要**在 `main` 的 release 提交里包含 `vscode-extension/package-lock.json` 等大文件
|
||||
4. 仅需在 `main` 更新时:改 `doc/design/vscode-extension.md`、Release 说明、**本文件** — 指针文档即可
|
||||
|
||||
---
|
||||
|
||||
## 6. 历史说明
|
||||
|
||||
v0.1.2 准备阶段曾误将 `vscode-extension/` 并入 `main`(并删除 ignore),导致推送体积过大。已恢复:**扩展仅 `vscode-extension` 分支**;`main` 只保留本约定与设计指针。
|
||||
@@ -0,0 +1,31 @@
|
||||
# VS Code 扩展(分支指针)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定分支模型** |
|
||||
| 代码分支 | **`vscode-extension`**(同仓库) |
|
||||
| 目录 | 工作区 `vscode-extension/`(**仅在该分支跟踪;`main` 在 `.gitignore` 忽略**) |
|
||||
| 提交约定 | **[vscode-extension-commit.md](vscode-extension-commit.md)**(必读,避免误提交到 `main`) |
|
||||
|
||||
---
|
||||
|
||||
## 分工(类比 `public` / `gh-pages`)
|
||||
|
||||
| 分支 | 内容 |
|
||||
|------|------|
|
||||
| `main` | Marqdo 语言 / CLI / `public/*.mq.md`;**不**存放扩展实现 |
|
||||
| `vscode-extension` | VS Code 扩展源码、TextMate 语法、VSIX 发版 |
|
||||
| `gh-pages` | 用户站生成 HTML |
|
||||
|
||||
```bash
|
||||
git checkout vscode-extension
|
||||
cd vscode-extension && npm install
|
||||
```
|
||||
|
||||
规范入口(在 **`vscode-extension` 分支**上阅读):
|
||||
|
||||
- `vscode-extension/README.md` — 目标与目录
|
||||
- `vscode-extension/DEVELOPMENT.md` — 日常流程
|
||||
- `vscode-extension/ARCHITECTURE.md` — 与 CLI 边界
|
||||
|
||||
扩展是 CLI 的薄宿主;语法真相仍是 [markdown-mapping.md](markdown-mapping.md)。
|
||||
@@ -0,0 +1,164 @@
|
||||
# 调研:Marqdo `ext/web` 能否对接 Daphne / 业界应用服务器
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记** |
|
||||
| 日期 | 2026-08-29 |
|
||||
| 范围 | Daphne、Uvicorn、Gunicorn、Hypercorn 等 ASGI/WSGI 服务器;对照 Marqdo `plugins/web`(axum) |
|
||||
| 相关 | [web-net-capabilities.md](web-net-capabilities.md) · [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) |
|
||||
| 触发 | `app.listen` 已能本地起站;问「能否像业界一样用 Daphne 等服务器」 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**不能把 Marqdo 站点「塞进」Daphne / Uvicorn / Gunicorn 当 Python ASGI/WSGI 应用跑。**
|
||||
|
||||
Marqdo 的 HTTP 服务**已经是**应用服务器:`plugins/web` 内嵌 **axum + tokio**,由 `` `app`.listen `` / `` `应用`.监听 `` 绑定端口。这在 Rust 生态里的角色,约等于 Python 里的 **Uvicorn/Daphne**,而不是 Django/Flask「应用代码」。
|
||||
|
||||
业界生产部署要支持的,通常不是「换成 Daphne」,而是:
|
||||
|
||||
1. **反代 + TLS**(Nginx / Caddy / Traefik)→ 已文档锁定;
|
||||
2. **进程监督**(systemd / Docker / k8s)→ 运维层,与框架无关;
|
||||
3. (可选)多进程 / 多副本水平扩展 → 需会话外置等,见下文。
|
||||
|
||||
---
|
||||
|
||||
## 1. Daphne「等」服务器是什么
|
||||
|
||||
| 名称 | 协议面 | 典型搭档 | 角色 |
|
||||
|------|--------|----------|------|
|
||||
| **Daphne** | ASGI | Django Channels | Python 异步/WebSocket 参考服务器 |
|
||||
| **Uvicorn** | ASGI | FastAPI、Django ASGI | 高性能 ASGI(常作 Gunicorn worker) |
|
||||
| **Gunicorn** | 主要为 WSGI | Django/Flask | 进程管理 + worker;**不能**直接跑 ASGI/WebSocket |
|
||||
| **Hypercorn** | ASGI | 需 HTTP/2/3 时 | ASGI 另一实现 |
|
||||
| **Granian** | ASGI(Rust 实现) | Python 应用 | 用 Rust 加速 Python ASGI |
|
||||
|
||||
共同点:它们都假设应用暴露 **Python ASGI/WSGI callable**(`application` / `asgi.py`)。服务器负责 accept、协议解析、生命周期;**业务在 Python 进程里**。
|
||||
|
||||
2026 常见生产组合示例:
|
||||
|
||||
```text
|
||||
Internet → Nginx/Caddy (TLS) → Uvicorn/Daphne (ASGI) → Django/FastAPI 应用
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Marqdo 今天怎么起服务
|
||||
|
||||
```text
|
||||
.mq.md(ext/web 作者面)
|
||||
→ ABI:web_listen / 路由装配
|
||||
→ plugins/web:组装 axum::Router
|
||||
→ tokio TcpListener + axum::serve ← 这里就是「应用服务器」
|
||||
```
|
||||
|
||||
关键事实(实现):
|
||||
|
||||
- `plugins/web/src/http.rs`:`TcpListener::bind` + `axum::serve`;
|
||||
- 依赖:`axum` 0.8、`tokio` multi-thread;含 WS、multipart、中间件层;
|
||||
- HTTPS:设计上 **进程内 TLS 不作为默认**;生产用反代终止 TLS + `cookie_secure`(见 [web-net-capabilities.md](web-net-capabilities.md) W7)。
|
||||
|
||||
因此:
|
||||
|
||||
| 问法 | 答案 |
|
||||
|------|------|
|
||||
| 能否 `daphne marqdo_app:app`? | **否** — 没有 Python ASGI 入口 |
|
||||
| 能否 `gunicorn -k uvicorn.workers…`? | **否** — 同上 |
|
||||
| 能否用 Nginx 反代到 `127.0.0.1:18085`? | **是** — 推荐生产路径 |
|
||||
| Marqdo 有没有「业界级」HTTP 栈? | **有** — axum/hyper 即 Rust 侧业界默认之一 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 分层对照(避免角色错位)
|
||||
|
||||
| 层级 | Python 典型 | Marqdo 对应 |
|
||||
|------|-------------|-------------|
|
||||
| 应用 / 路由 / 模板 / DB | Django / FastAPI | `ext/web` + `plugins/web` 装配 |
|
||||
| 应用服务器(accept / HTTP / WS) | Daphne / Uvicorn | **内嵌 axum::serve** |
|
||||
| 反代 / TLS / 静态边缘 | Nginx / Caddy | **外置反代**(文档已写) |
|
||||
| 进程管理 | systemd / Gunicorn master | systemd / Docker / k8s |
|
||||
|
||||
把 Daphne 接到 Marqdo,相当于要求「用 Python ASGI 服务器去托管 Rust axum 应用」——协议面不匹配,没有现成插槽。
|
||||
|
||||
---
|
||||
|
||||
## 4. 若目标是「生产级部署」,已支持什么 / 还差什么
|
||||
|
||||
### 4.1 已支持(或已锁定)
|
||||
|
||||
| 能力 | 状态 |
|
||||
|------|------|
|
||||
| 本地 / 内网 `listen` | ✅ |
|
||||
| HTTP + WebSocket | ✅(axum) |
|
||||
| 反代终止 HTTPS | ✅ 文档路径 |
|
||||
| 访问日志、限速、CORS、安全头等 | ✅ W1–W7 |
|
||||
| 会话可 SQLite 持久化 | ✅(单机多启需注意) |
|
||||
|
||||
### 4.2 与「Daphne 集群」对等时仍需注意
|
||||
|
||||
| 主题 | 说明 |
|
||||
|------|------|
|
||||
| **多进程副本** | 每进程各自 `listen` 时,内存会话 / 内存 cache / 内存 WS hub **不共享**;多副本需 sticky session,或会话/缓存外置(Redis 等,驱动面已有雏形) |
|
||||
| **优雅重启 / 零停机** | axum 可接 signal;未做成一等作者 API(运维可用 systemd + 反代) |
|
||||
| **HTTP/2 末端** | 多由反代提供;进程内 HTTP/1.1 足够常见场景 |
|
||||
| **与 Python 生态混部** | 可同机 Nginx 分流:`/api/py` → Uvicorn,`/` → Marqdo;**不是**共用一个 Daphne |
|
||||
|
||||
### 4.3 不建议的路线
|
||||
|
||||
1. **实现完整 ASGI 适配器让 Daphne 加载 Marqdo**
|
||||
成本高、收益低:等于在 Python 进程里再调一层 FFI/子进程,丢掉 axum 直驱优势。
|
||||
2. **把 axum 拆掉、改写为「纯应用、外挂任意服务器」**
|
||||
Rust 没有统一 ASGI;外挂只能是自定义协议或「只当 CGI」,与当前架构相反。
|
||||
|
||||
### 4.4 可选增强(若要对标「可换服务器」的体验)
|
||||
|
||||
| 方向 | 含义 | 优先级建议 |
|
||||
|------|------|------------|
|
||||
| **A. 部署文档 + 示例 Compose** | Nginx/Caddy + `marqdo run` + systemd | **高**(满足绝大多数「业界部署」诉求) |
|
||||
| **B. listen 运维旋钮** | workers 说明、graceful shutdown、Unix socket | 中 |
|
||||
| **C. 多副本清单** | 会话/WS/cache 外置检查表 | 中 |
|
||||
| **D. 反向:Marqdo 作边缘、反代到既有 ASGI** | 已可用 HTTP 客户端/路由外置服务 | 按需 |
|
||||
| **E. ASGI bridge** | 明确 **非目标** | 不做 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 推荐生产拓扑(等价于「Nginx + Daphne」)
|
||||
|
||||
```text
|
||||
客户端
|
||||
│ HTTPS
|
||||
▼
|
||||
Nginx / Caddy / Traefik ← TLS、压缩、限流、静态可旁路
|
||||
│ HTTP proxy_pass
|
||||
▼
|
||||
marqdo run index.mq.md ← 内部 axum::serve(角色 ≈ Uvicorn/Daphne)
|
||||
(host=127.0.0.1 port=18085,cookie_secure=True)
|
||||
```
|
||||
|
||||
要点:
|
||||
|
||||
- Marqdo **只绑回环**;对外只暴露反代。
|
||||
- WebSocket:反代需 `Upgrade` / `Connection` 正确转发(与反代 Daphne 相同注意点)。
|
||||
- 多机:共享 DB(或 Postgres 驱动)、共享会话存储;WS 广播跨机需外置 pub/sub(当前 hub 为进程内)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 结论与建议
|
||||
|
||||
| 问题 | 结论 |
|
||||
|------|------|
|
||||
| 能支持 Daphne 吗? | **不能直接托管**;协议是 Python ASGI,Marqdo 是 Rust axum 自托管。 |
|
||||
| 能支持「业界服务器」吗? | **能**:用 **Nginx/Caddy 等业界反代** 挂在 `listen` 前面;应用服务器层已由 axum 承担。 |
|
||||
| 缺的是换 Daphne,还是缺部署体验? | 主要是 **部署文档 / Compose / 多副本约定**,不是再嵌一套 ASGI 运行时。 |
|
||||
|
||||
**建议下一刀(若产品化):** 写一份 `examples/` 或 `doc/design` 下的「反代部署」最小样例(Caddyfile / nginx.conf + `cookie_secure`),而不是调研 ASGI bridge。
|
||||
|
||||
---
|
||||
|
||||
## 7. 参考
|
||||
|
||||
- 本仓:[web-net-capabilities.md](web-net-capabilities.md)(HTTPS 反代锁定)· [ext-web.md](ext-web.md)
|
||||
- Daphne:Django Channels 参考 ASGI 服务器
|
||||
- Uvicorn / Gunicorn worker:当代 Python ASGI 生产主流组合
|
||||
- axum:Tokio 生态 HTTP 应用框架(Rust 侧与 Uvicorn 同层)
|
||||
@@ -0,0 +1,265 @@
|
||||
# 网络能力调研:从「能跑」到「完整项目」
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · W0–W7 + P3 完结**(2026-08-28 复核) |
|
||||
| 日期 | 2026-08-26(初稿)· 2026-08-28(完结复核) |
|
||||
| 相关 | [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) |
|
||||
| 目标 | 盘点 `ext/web` + `plugins/web` + `lib/net` 现状,对照主流语言网络栈,给出「开发一个完整 Web 项目」所需能力的差距清单与补强路线 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**`ext/web` + `plugins/web` 已完成 W0–W7 + P3 路线图**:中间件/JSON API、数据层(连接池/事务/分页/FTS/迁移/外键/审计时间戳)、安全硬化(argon2/CSRF/会话持久化/限速/RBAC)、内容站点标配(SEO/RSS/Markdown/分页 UI)、上传下载/相册/ETag、sitemap/robots/错误页/重定向、WebSocket 广播与访问日志。足以在 Marqdo 上实现博客/CMS/中小型 API 站点;**未内置**的仅剩标签页模板(D6,可用路由+`db.count` 自建)与应用层反垃圾。边界不变:**纯解析进 `lib/net`,HTTP 服务器与领域能力进 `plugins/web` + `ext/web` 作者面**。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状盘点(2026-08-26 实测)
|
||||
|
||||
### 1.1 `lib/net`(标准库,L0.5 宿主原语薄包装)
|
||||
|
||||
| 能力 | 归属 | 现状 |
|
||||
|---|---|---|
|
||||
| `http_get` / `获取` | host `net.rs` (ureq) | ✅ GET,返回 `{status, body}` |
|
||||
| `http_post` / `提交` | host `net.rs` | ✅ POST,默认 JSON CT |
|
||||
| `http_request` / `请求` | host `net.rs` | ✅ 通用 method+body+headers |
|
||||
| `http_post_sse` / `提交流式` | host `net.rs` | ✅ OpenAI 兼容 SSE 流式消费 |
|
||||
| `openai_sse_parse` / `解析流式` | host `net.rs` | ✅ 离线 SSE 解析 |
|
||||
| `url_encode` / `编码地址` | host `net.rs` | ✅ URL 编码 |
|
||||
| `cookie_parse` / `解析Cookie` | host `net.rs` | ✅ RFC6265 子集(请求头/响应头) |
|
||||
| `multipart_parse` / `解析多部分` | host `net.rs` | ✅ multipart/form-data 解析 |
|
||||
| `markdown_parse` / `解析Markdown` | host `net.rs` | ✅ GFM/Markdown → HTML(纯解析,W4c) |
|
||||
|
||||
**标准库网络原语已齐备**:客户端 GET/POST/SSE、URL 编码、cookie、multipart、Markdown 解析。服务器侧上传/下载/ETag 在 `plugins/web`(A5/P3)。
|
||||
|
||||
### 1.2 `plugins/web`(ABI v2,领域能力)
|
||||
|
||||
**服务器侧已实现:**
|
||||
|
||||
| 域 | ABI | 能力 |
|
||||
|---|---|---|
|
||||
| 页面 | `web_page_new` · `web_compose_components` · `web_compose_main` · `web_page_query` · `web_page_order` · `web_page_link_prefix` · `web_page_css` · `web_page_detail` | 页面装配、列表/排序、CSS、详情页 |
|
||||
| 样式 | `web_style` | GFM 表 → CSS(`make_style`/`样式装配`) |
|
||||
| 表单 | `web_form_new/fields/rules/validate/render/submit/from_schema` · `web_compose_form` | 字段表、校验表、渲染、提交、schema→form |
|
||||
| 数据库 | `web_db_new/init/insert/select/get/update/delete/exec/table_info/list_tables` | SQLite CRUD + where + order + limit |
|
||||
| 应用 | `web_app_new/route/mount_form/static/auth` · `web_app_route_ws` | 路由、静态目录、admin、鉴权、WS 端点 |
|
||||
| 会话 | `web_session_new/set/get/del/destroy` | 内存 TTL 会话 |
|
||||
| 鉴权 | `web_auth_login/check/logout/new` · `web_app_auth` | `/admin` 登录门禁 |
|
||||
| WebSocket | `web_ws_connect`(客户端)· `web_app_route_ws`(服务器) | 单请求-响应式客户端 + echo 服务器 |
|
||||
|
||||
**关键实现事实(2026-08-28 W7+P3 后):**
|
||||
|
||||
- **中间件 + JSON API**(W1):`app.configure` 装配 CORS、安全头、gzip、请求体上限、JSON 端点。
|
||||
- **数据层**(W2/W6/W7/P3):连接池、事务、分页、OR/IN/BETWEEN、`db.count`、迁移、FTS5 搜索、init 唯一/索引/外键、审计时间戳。
|
||||
- **安全**(W3s/P3):argon2、CSRF、SQLite 会话、CSPRNG session id、登录限速、RBAC(`app.gate` + 用户 `role`)。
|
||||
- **内容站点**(W4c/W7):SEO `page.meta`、RSS、Markdown 正文、`page.paginate`、sitemap/robots。
|
||||
- **媒体**(W5/P3):multipart 上传、下载、`app.gallery`、ETag/Cache-Control。
|
||||
- **运维向**(W6/W7):访问日志、自定义 404/500、301/307 重定向、WS 广播;HTTPS 由反代终止 + `cookie_secure`。
|
||||
- **仍属应用层约定**:标签聚合页模板(D6)、评论反垃圾、草稿/定时发布(表+where 即可)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 2. 主流网络栈对照(联网调研 2026-08)
|
||||
|
||||
### 2.1 分层共识(决定「标准库 vs 扩展」边界)
|
||||
|
||||
| 语言 | 标准库网络能力 | 扩展/框架能力 | 边界准则 |
|
||||
|---|---|---|---|
|
||||
| Python | `urllib`(HTTP 客户端)、`http.cookies`(cookie 解析器)、`http.server`(简易服务器)、`email` 多部分解析 | `requests`/`httpx`(连接池/session)、`FastAPI`/`Flask`(中间件/校验/模板) | 解析器进标准库;便利层/框架层在第三方 |
|
||||
| Node.js | `node:http`(低层流式,**不解析 body**)、`node:https` | express、fastify、ws、formidable | 低层原语进核心;fancy 功能 userland 验证后再进 core |
|
||||
| Go | `net/http`(服务器+客户端**都在标准库**)、`net/http/cookiejar`(RFC6265)、`net/smtp` | `golang.org/x/net`(演进性)、gin/echo | HTTP 与 stdin 同级的核心能力;cookie 解析进标准库 |
|
||||
| Rust | 极小 std(无 HTTP) | `hyper`→`reqwest`→`axum` | 分层;HTTP 生态多样不进 std |
|
||||
|
||||
**对本项目的三处判定(与 [ext-web-net.md](ext-web-net.md) 一致并延伸):**
|
||||
|
||||
1. **纯解析原语**(cookie / multipart / url)→ `lib/net` 标准库。✅ 已达成。
|
||||
2. **HTTP 服务器结构能力**(JSON / 中间件 / 上传下载 / HTTPS / 缓存头)→ `plugins/web`(ABI)。这是 axum 本身就在依赖链里的,不需要新增核心依赖。
|
||||
3. **领域能力**(session / auth / 分页 / 搜索 / RSS / SEO / 限流)→ `plugins/web` + `ext/web` 作者面。
|
||||
|
||||
### 2.2 「完整 Web 框架」能力清单(FastAPI / Express / Flask / axum 共通项)
|
||||
|
||||
> **marqdo 列**反映 **2026-08-28 W7+P3 完结** 后状态(见 §3 差距表)。
|
||||
|
||||
| 能力 | FastAPI | Express | Flask | axum | marqdo |
|
||||
|---|---|---|---|---|---|
|
||||
| 路由(含动态参数) | ✅ | ✅ | ✅ | ✅ | ✅ 动态路由 `/post/{slug}` |
|
||||
| 中间件管道 | ✅ | ✅ | ✅ | ✅(tower) | ✅ W1 `app.configure` |
|
||||
| CORS | ✅ 内置 | ✅ 中间件 | ✅ flask-cors | ✅ tower-http | ✅ W1 |
|
||||
| JSON 请求/响应 | ✅ 原生 | ✅ | ✅ | ✅ | ✅ W1 JSON API 表 |
|
||||
| 校验(schema/字段) | ✅ Pydantic | 手动(zod) | 手动 | ✅ extractor | ✅ form 校验表 |
|
||||
| 静态文件 | ✅ Starlette | ✅ | ✅ | ✅ | ✅ `app.static` |
|
||||
| 模板/渲染 | ✅ Jinja | ✅ | ✅ | ✅ | ✅ GFM 表装配 |
|
||||
| 会话 | ✅ | ✅ express-session | ✅ | ✅ | ✅ SQLite 持久化(W3s) |
|
||||
| 鉴权 | ✅ OAuth2/APIKey | ✅ | ✅ | ✅ | ✅ admin + RBAC(P3) |
|
||||
| 文件上传 | ✅ | ✅ multer | ✅ | ✅ | ✅ W5 upload |
|
||||
| WebSocket | ✅ | ✅ ws | ✅ Flask-SocketIO | ✅ | ✅ echo + 广播(W6) |
|
||||
| 安全头 | ✅ | ✅ helmet | ✅ | ✅ tower-http | ✅ W1 |
|
||||
| 限流 | ✅ | ✅ | ✅ | ✅ | ✅ 登录限速(W3s) |
|
||||
| 日志 | ✅ | ✅ morgan | ✅ | ✅ | ✅ access_log(W6) |
|
||||
| gzip 压缩 | ✅ | ✅ | ✅ | ✅ | ✅ W1 |
|
||||
| 分页 | 手动 | 手动 | ✅ paginate | ✅ | ✅ db + page UI(W2/W4c) |
|
||||
| 迁移 | ✅ alembic | ✅ | ✅ | ✅ sqlx | ✅ W6 `db.migrate` |
|
||||
| 测试工具 | ✅ TestClient | ✅ supertest | ✅ | ✅ | gold 测试(`tests/ext/web-*`) |
|
||||
| HTTPS/TLS | 反代 | 反代 | 反代 | ✅ rustls | 反代 + `cookie_secure`(W7 文档锁定) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 3. 差距分析:按「完整项目」四类需求
|
||||
|
||||
### 3.1 类 A:结构化 HTTP 基础设施(做 API / 前后端分离 / SPA 支撑)
|
||||
|
||||
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| A1 | **JSON 请求/响应**(`Json` extractor、`application/json` 响应、body 大小限制) | ✅ **已实现(W1)**:`接口` 表声明 JSON API 端点;`请求体上限` 配置 body 限制 | `plugins/web` | **P0 ✅** |
|
||||
| A2 | **中间件管道**(`app.configure` / `应用.装配`:CORS、安全头、压缩、请求体限制统一挂载) | ✅ **已实现(W1)**:`middleware.rs` 装配 GFM 表并 `app.layer` 挂到 axum | `plugins/web` | **P0 ✅** |
|
||||
| A3 | **CORS 支持**(`Access-Control-Allow-Origin` 可配) | ✅ **已实现(W1)**:`跨域` 表 `|允许来源|方法|头|暴露头|凭证|` | `plugins/web` | P1 ✅ |
|
||||
| A4 | **安全响应头**(CSP / X-Frame-Options / X-Content-Type-Options / HSTS / Referrer-Policy / 去 `X-Powered-By`) | ✅ **已实现(W1)**:`安全` 表 `|头|值|` | `plugins/web` | P1 ✅ |
|
||||
| A5 | **文件上传接收**(multipart extractor → 校验类型/大小 → 落盘)与**下载**(`Content-Disposition`) | ✅ **已实现(W5)**:`app.upload` / `app.download`;`file:` storage;离线 + curl live 金样 | `plugins/web` | P1 ✅ |
|
||||
| A6 | **HTTPS / TLS**(rustls 终止或反代提示) | ✅ **文档锁定(W7)**:进程内 TLS 不启用;反代终止 HTTPS,并设 `cookie_secure=True` | 文档 + `cookie_secure` | P2 ✅ |
|
||||
| A7 | **gzip / br 压缩** + **ETag / Cache-Control 缓存头** | gzip ✅(W1);Cache-Control ✅(W7);ETag ✅ **已实现(P3,下载/相册 + If-None-Match→304)** | `plugins/web` | P2 ✅ |
|
||||
| A8 | **访问日志**(请求方法/路径/状态/耗时) | ✅ **已实现(W6b)**:`configure access_log=True` → stderr | `plugins/web` | P2 ✅ |
|
||||
| A9 | **自定义 404/500 错误页** | ✅ **已实现(W7)**:`app.error_page` / `应用.错误页`;404 fallback + 500 页袋 | `plugins/web` | P2 ✅ |
|
||||
| A10 | **重定向增强**(permanent/自定义状态码) | ✅ **已实现(W7)**:`app.redirect` → 301/307 | `plugins/web` | P3 ✅ |
|
||||
|
||||
### 3.2 类 B:数据层深化(内容站点/社区的根基)
|
||||
|
||||
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| B1 | **连接池 / busy_timeout / WAL** | 高并发下 `database is locked`、每请求重连开销 | `plugins/web`(db.rs) | **P0 ✅** |
|
||||
| B2 | **事务 API**(`begin` / `commit` / `rollback`,或 `with_transaction` 包装) | 批量/多表写无原子性 | `plugins/web` | **P0 ✅** |
|
||||
| B3 | **结果集型裸查询**(exec 返回 rows) | count / join / group / 子查询完全不可用 | `plugins/web` | P1 ✅ |
|
||||
| B4 | **分页**(db 层 `limit`+`offset`;页面层上一页/下一页) | 列表页只能限量 | `plugins/web` + `ext/web` | P1 ✅(db 层;页面 UI 属 D4) |
|
||||
| B5 | **查询表达力**:OR / IN / BETWEEN / IS NULL / LIKE 转义 / 括号组合 | where 只能 AND | `plugins/web` | P1 ✅ |
|
||||
| B6 | **迁移机制**(schema 版本表 + 迁移脚本) | ✅ **已实现(W6)**:`db.migrate` + `_marqdo_migrations`(SQLite) | `plugins/web` + `ext/web` | P2 ✅ |
|
||||
| B7 | **索引 / 唯一 / 外键声明**(init 表增强) | ✅ **已实现(W7+P3)**:`唯一`/`索引`/`外键`(`posts.id` / `posts`) | `plugins/web` | P2 ✅ |
|
||||
| B8 | **聚合辅助**:count / group 便捷 API | 统计面板、标签计数 | `plugins/web` | P2 ✅(`db.count`) |
|
||||
| B9 | **全文搜索**(SQLite FTS5) | ✅ **已实现(W6)**:`db.fts` + `db.search`(bm25) | `plugins/web`(FTS5 现成) | P2 ✅ |
|
||||
| B10 | **时间戳 / 审计字段自动维护** | ✅ **已实现(P3)**:表含 `created_at`/`updated_at` 时 insert/update 自动写入 | `plugins/web` | P3 ✅ |
|
||||
|
||||
### 3.3 类 C:安全硬化(能上线的前提)
|
||||
|
||||
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| C1 | **密码哈希**(argon2/bcrypt/sha+盐,替代明文) | ✅ **已实现(W3s)**:argon2 | `plugins/web` | **P0 ✅** |
|
||||
| C2 | **CSRF 防护**(session-bound token,写操作校验) | ✅ **已实现(W3s)** | `plugins/web` | **P0 ✅** |
|
||||
| C3 | **登录限速/失败锁定**(每 IP/用户名 5 次/15min) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ |
|
||||
| C4 | **会话持久化**(SQLite/文件,替代内存) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ |
|
||||
| C5 | **加密安全 session id**(CSPRNG + 碰撞重试) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ |
|
||||
| C6 | **cookie 增强**:`Secure` 标志、签名、滑动过期 | ✅ **已实现**:`cookie_secure` + 滑动 TTL(touch);cookie 签名未单独做 | `plugins/web` | P2 ✅ |
|
||||
| C7 | **防暴力破解 / 会话上限 / 后台过期清理** | ✅ 限速 + prune;会话条数硬上限可后续 | `plugins/web` | P2 ✅ |
|
||||
| C8 | **RBAC / 多角色**(作者/管理员/访客) | ✅ **已实现(P3)**:用户表 `role`/`角色`;`app.gate`;`/admin*` 默认需 `admin` | `plugins/web` + `ext/web` | P3 ✅ |
|
||||
|
||||
### 3.4 类 D:内容站点标配(博客/CMS 特有)
|
||||
|
||||
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| D1 | **SEO**:每页 `<title>`/`meta description`/OG 标签/`canonical`/结构化数据 | ✅ **已实现(W4c)**:`page.meta` | `ext/web` | **P0 ✅** |
|
||||
| D2 | **sitemap.xml / robots.txt** 生成 | ✅ **已实现(W7)**:`app.sitemap` / `app.robots` | `plugins/web` + `ext/web` | P1 ✅ |
|
||||
| D3 | **RSS/Atom 输出**(`content_type=application/rss+xml` 路由) | ✅ **已实现(W4c)**:`route_rss` | `ext/web` + 插件 | P1 ✅ |
|
||||
| D4 | **分页导航 UI**(上一页/下一页,依赖 B4) | ✅ **已实现(W4c)**:`page.paginate` | `ext/web` | P1 ✅ |
|
||||
| D5 | **Markdown 渲染**(正文存储为 Markdown,渲染为 HTML) | ✅ **已实现(W4c)**:`lib/net` + 页面装配 | `lib/net` | **P0 ✅** |
|
||||
| D6 | **标签/分类聚合页**(`/tag/{slug}` 动态路由 + 计数) | 可用路由+`db.count` 自建(未内置模板) | `ext/web` | P2 |
|
||||
| D7 | **评论系统**(表单 + 审核 + 反垃圾) | ✅ 约定:表+表单+where(W6);反垃圾属应用层 | `ext/web` | P2 ✅ |
|
||||
| D8 | **草稿/发布/定时**(状态字段 + 过滤查询) | ✅ 约定:`status` + where(W6) | `ext/web` + db where | P2 ✅ |
|
||||
| D9 | **图片/附件库**(依赖 A5 上传 + 相册页) | ✅ **已实现(P3)**:`app.gallery` HTML 相册 + A5 上传/下载 | `ext/web` + `plugins/web` | P3 ✅ |
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 4. 补强路线(分波次,按「标准库 vs 扩展」边界)
|
||||
|
||||
### 4.1 波次建议(每波独立可交付、可回归)
|
||||
|
||||
| 波次 | 主题 | 内容 | 对应差距 |
|
||||
|---|---|---|---|
|
||||
| **W1** | 服务器基础设施 | 中间件管道(CORS/安全头/压缩/请求体限制)+ JSON API(`application/json` 响应 + DB 查询端点) | A1 A2 A3 A4 A7 ✅ **已完成** |
|
||||
| **W2** | 数据层深化 | 连接池/busy_timeout/WAL + 事务 API + 结果集裸查询 + 分页(offset) + OR/IN/BETWEEN + 聚合 count | B1 B2 B3 B4 B5 B8 ✅ **已完成** |
|
||||
| **W3** | 安全硬化 | 密码哈希 + CSRF + 会话持久化 + CSPRNG session id + cookie 增强 + 登录限速/锁定 | C1–C7 ✅ |
|
||||
| **W4** | 内容站点标配 | SEO 元数据 + sitemap/robots + RSS + Markdown 渲染 + 分页导航 UI + 标签/分类 | D1–D5 ✅;D6 约定 |
|
||||
| **W5** | 上传与媒体 | multipart 文件上传接收 + 落盘 + 下载 + 图片库 | A5 ✅;D9 相册 P3 ✅ |
|
||||
| **W6** | 进阶 | 全文搜索(FTS5) + 迁移机制 + 评论系统 + 草稿/发布 + WS 广播 | B6 B9 ✅;WS 广播 + access_log ✅;D7/D8 用表+where ✅ |
|
||||
| **W7** | 完结打磨 | Cache-Control、自定义 404/500、301 重定向、sitemap/robots、init 唯一/索引、HTTPS 反代文档 | A6 A7 A9 A10 B7 D2 ✅ |
|
||||
| **P3** | 真·网络扩展补齐 | 审计时间戳、外键、RBAC 门禁、媒体相册、下载 ETag | B10 C8 D9 + ETag/FK ✅ |
|
||||
|
||||
### 4.2 边界判定要点(严格遵守既有约束)
|
||||
|
||||
1. **进标准库 `lib/net`**(纯解析、无网络 I/O、支持扩展库开发):
|
||||
- `markdown_parse`(GFM/Markdown → HTML,纯解析)→ D5 ✅。
|
||||
- `xml_escape` / RSS/Atom 纯文本装配辅助(如需)→ D3(作者面 `route_rss` 已够用)。
|
||||
- **不得**放进标准库:JSON API、中间件、上传接收、事务、会话(均涉 I/O 或领域语义)。
|
||||
2. **进 `plugins/web`(ABI)**:A1–A10、B1–B10、C1–C8、D7–D8 的插件侧 — **均已落地**(2026-08-28)。
|
||||
3. **进 `ext/web` 作者面(Marqdo)**:D1–D4、A5/D2/D9 等 GFM 表包装 — **均已落地**(中英 `web.mq.md` / `网页.mq.md`)。
|
||||
4. **已具备、无需新增**:动态路由、静态文件、表单校验/回显、session、admin/RBAC、WebSocket、SSE 客户端、cookie/multipart/Markdown 解析。
|
||||
|
||||
### 4.3 作者面示例(示 W4 落地形态,保持「代码即文档」)
|
||||
|
||||
**SEO 元数据(扩展页面表):**
|
||||
|
||||
```markdown
|
||||
`meta` =
|
||||
|
||||
| 键 | 值 |
|
||||
|---|---|
|
||||
| `title` | 文章标题 |
|
||||
| `description` | 摘要 |
|
||||
| `og_type` | article |
|
||||
| `canonical` | /post/{slug} |
|
||||
```
|
||||
|
||||
页面装配时并入 `<head>` —— 仍是「表 + 函数装配」,不引入 `json.*` 袋。
|
||||
|
||||
**RSS(扩展路由,响应头 `content_type=application/rss+xml`):**
|
||||
|
||||
```markdown
|
||||
*feed = > 页面.列出表 rows=`文章` 分页=20 排序="published desc"*
|
||||
*xml = > 文本.拼装 xs=`rss 片段们`*
|
||||
*`app` = > `应用`.路由 路径="/feed.xml" 内容=`xml` 类型="application/rss+xml"*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 结论
|
||||
|
||||
**W0–W7 + P3 已全部落地**(路线图见 [roadmap/ext-web.md](../roadmap/ext-web.md))。验收覆盖:
|
||||
|
||||
- 离线/在线 gold:`tests/ext/web-*-smoke.mq.md`(含 security、drivers、upload、w6、w7、p3)
|
||||
- 完整示例:`examples/marqdo-blog/`(列表/详情/标签/RSS/后台/上传/WS)
|
||||
- 作者面:`ext/web/web.mq.md` · `ext/web/网页.mq.md`
|
||||
- AI 编写指引:`skills/marqdo/`(§ ext/web)
|
||||
|
||||
**后续可选(非阻塞)**:标签页内置模板(D6)、cookie 签名、会话条数硬上限、应用层反垃圾、进程内 TLS(仍建议反代)。
|
||||
|
||||
**部署对照(Daphne / Uvicorn / 反代):** 见 [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md) — Marqdo **不能**被 Daphne 托管;生产等价路径是 **反代 → 内嵌 axum `listen`**。
|
||||
|
||||
**一句话:`ext/web` 已是可上线级别的 Marqdo 动态站扩展;博客/CMS/中小型 API 可在表格 + 类方法作者面上完整实现。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 附:博客示例能力对照(`examples/marqdo-blog`)
|
||||
|
||||
| 博客功能 | 现状 |
|
||||
|---|---|
|
||||
| 文章列表(首页) | ✅ |
|
||||
| 文章详情(动态路由) | ✅ |
|
||||
| 标签/分类 | ✅ 路由 + `db.where` + `db.count` |
|
||||
| 分页 | ✅ `db.paginate` + `page.paginate` |
|
||||
| 搜索 | ✅ FTS5 `db.search` |
|
||||
| SEO 元数据 | ✅ `page.meta` |
|
||||
| RSS | ✅ `app.route_rss` |
|
||||
| 评论 | ✅ 表 + form + where(反垃圾属应用层) |
|
||||
| 后台写文章 | ✅ admin CRUD + RBAC |
|
||||
| 草稿/发布 | ✅ `status` 字段 + where |
|
||||
| 上传配图 | ✅ `app.upload` + `app.gallery` |
|
||||
| 用户登录 | ✅ argon2 + CSRF + SQLite 会话 + 限速 |
|
||||
| sitemap / robots | ✅ W7 |
|
||||
| 实时终端(WS) | ✅ W6 广播 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 附:Markdown 正文渲染(D5,已落地)
|
||||
|
||||
博客详情页正文经 `lib/net.markdown_parse`(`host_markdown_parse`)解析为 HTML,由 `plugins/web` 渲染层在页面装配时调用(W4c)。作者存储 Markdown 字符串于 DB,展示侧自动渲染 GFM 子集(标题、列表、链接、代码块等)。纯解析留在标准库;**不得**在 `ext/web` 作者面直接调 `host_*`。
|
||||
+28
-5
@@ -33,7 +33,7 @@ cd marqdo
|
||||
|
||||
cargo build
|
||||
cargo test
|
||||
cargo run -- run examples/structure/hello.mq.md
|
||||
cargo run -- run tests/structure/hello.mq.md
|
||||
```
|
||||
|
||||
当前 M0:`run` 会读入文件并明确报错「evaluation not implemented」(脚手架,非静默假成功)。
|
||||
@@ -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,11 +63,33 @@ cargo build
|
||||
|
||||
```toml
|
||||
[http]
|
||||
proxy = "http://127.0.0.1:7897"
|
||||
proxy = "http://127.0.0.1:7890"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3.5 Git 推送(遇网络失败时使用代理)
|
||||
|
||||
直连 `git push` 偶尔会报 `RPC failed; curl 35 Recv failure: Connection reset by peer` 或 `curl 56`(远端挂断,常见于数据包稍大时)。此时**通过本机代理 7890 推送**:
|
||||
|
||||
```bash
|
||||
# Linux/macOS(本机 clash 监听 127.0.0.1:7890)
|
||||
git -c http.proxy=http://127.0.0.1:7890 -c http.postBuffer=524288000 push origin main
|
||||
```
|
||||
|
||||
要点:
|
||||
|
||||
- 代理可用性先探测:`curl -x http://127.0.0.1:7890 -o /dev/null -w "%{http_code}\n" https://github.com`,返回 `200` 再推。
|
||||
- `http.postBuffer=524288000`(500 MB)用于规避推送大包被断开(`curl 56`);两个 `-c` 可叠加。
|
||||
- 该命令**一次性生效**,不写死仓库配置。若想长期默认走代理,可执行:
|
||||
```bash
|
||||
git config http.proxy http://127.0.0.1:7890
|
||||
git config http.postBuffer 524288000
|
||||
```
|
||||
- 若是别的代理端口,把 `7890` 换成实际端口(如 Windows 示例里 `$env:HTTPS_PROXY` 的同款端口)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 目录约定
|
||||
|
||||
| 路径 | 含义 |
|
||||
@@ -75,7 +97,8 @@ proxy = "http://127.0.0.1:7897"
|
||||
| `src/lex` | 行分类 / 词法(自研) |
|
||||
| `src/parse` | 递归下降语法 |
|
||||
| `src/diagnostics` | 诊断 |
|
||||
| `examples/` | 金样例(宪法) |
|
||||
| `tests/` | 金样例 + 集成测试(`structure` / `keywords` / `errors`) |
|
||||
| `public/` | 用户可执行文档(无 errors) |
|
||||
| `spike/` | 旧 Python 风险探测,非运行时依赖 |
|
||||
| `doc/` | 设计与路线图 |
|
||||
|
||||
|
||||
@@ -0,0 +1,190 @@
|
||||
# 调研:`ext/agent` 在 A0–A4 之后还差什么
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 缺口盘点(A0–A4 闭环之后)** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 前置调研 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md)(优势与优化原则) |
|
||||
| 已落地路线 | [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)(**A0–A4 done**) |
|
||||
| 设计 | [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) · [okf.md](../design/okf.md) |
|
||||
| 邻近规划 | [agent-streaming.md](../roadmap/agent-streaming.md) · [okf-near-match.md](../roadmap/okf-near-match.md) |
|
||||
| 外部对照(2026) | LangGraph persistence / CrewAI+Flows / MCP 工具协议 / 业界 Agent 评测与记忆层讨论 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
调研驱动的 **A0–A4** 已把 Marqdo 智能体的**差异化内核**补齐:工作簿补丁可靠、OKF 复用飞轮可读可用、过程事件可审、上下文有预算、外置检索/MCP 只作证据。
|
||||
|
||||
相对 2026 年主流框架(LangGraph、CrewAI、厂商 SDK、MCP 生态),Marqdo **不再缺「能跑的 Agent loop」**;缺口集中在:
|
||||
|
||||
1. **产品化与可发现性**(示例、文档新鲜度、上手路径)
|
||||
2. **生产配套**(评测 harness、真 MCP、断点续跑、HITL、飞轮指标)
|
||||
3. **可选扩展面**(并行 fan-out、多 Agent/A2A、trace 外发)
|
||||
|
||||
**不要**用缺口清单去证明应回退到隐藏 TOOL: 循环或把向量库升为权威真相——那与宪法冲突,也抵消已落地的优势。
|
||||
|
||||
---
|
||||
|
||||
## 1. 已落地基线(A0–A4)
|
||||
|
||||
| 波次 | 主题 | 验收要点 |
|
||||
|------|------|----------|
|
||||
| **A0** | 工作簿补丁 / 固化 | 整文件 FIND 护栏;`soft` 仅 miss;`workbook_solidify`;金样 `agent-workbook-patch-a0` |
|
||||
| **A1** | OKF 复用飞轮 | `list_tasks` 策展字段;`plan` 暴露 `match`/`score`;金样 `agent-kb-plan-hit` |
|
||||
| **A2** | 过程可见 | `events` 默认落盘;view plan 过程卡;SSE 仍仅 `stream=True` |
|
||||
| **A3** | 上下文预算 | `source_brief` / `skill_brief`;`READ:source|skill`;`step max_reads` |
|
||||
| **A4** | RAG/MCP 证据工具 | `corpus_search`;fixture `mcp_*`;`authority=workbook` |
|
||||
|
||||
原则回顾(见前置调研 §9):强化差异化;资源砸在工作簿 / 写回 / 固化 / OKF / 过程可视;外置 RAG/MCP **只作工具**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 相对业界:已经「够格」的部分
|
||||
|
||||
下列能力若取消「可执行 Markdown 为权威」即消失——这是护城河,不是功能点攀比:
|
||||
|
||||
| 能力 | Marqdo 形态 | 业界常见替代 |
|
||||
|------|-------------|--------------|
|
||||
| 单一真相源 | 源码即提示 + 调用点注入 | Prompt Hub / 字符串 system |
|
||||
| 过程可审 | 写回块 + `events` + view 过程卡 | Langfuse / LangSmith 外挂 |
|
||||
| 成功可复用 | OKF 任务技能再跑 | transcript 再聊 / 向量片段召回 |
|
||||
| 复杂任务边界 | 工作簿文件 + `subtask` | 无限加长 chat / 临时工具输出 |
|
||||
| 确定步骤降本 | solidify → `llm_free` 快路径 | 每轮仍问模型 |
|
||||
|
||||
自评四问(前置调研 §9)粗判:
|
||||
|
||||
| 问 | 现状 |
|
||||
|----|------|
|
||||
| 新人能否只读一份 `.mq.md` 理解 Agent? | **部分** — 机制在,缺 canonical 示例教程 |
|
||||
| 失败后能否在 git + view 复盘、不强制外部 trace? | **基本可以** |
|
||||
| 成功任务下周能否以同一技能复用? | **可以**(金样已锁二次命中) |
|
||||
| 确定步骤是否越来越多变成普通 `##`、模型调用下降? | **路径有**(solidify / llm_free),缺量化看板证明 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 缺口总表(按优先级)
|
||||
|
||||
| 优先级 | 缺口 | 为何还缺 | 建议验收线索 |
|
||||
|--------|------|----------|--------------|
|
||||
| **高** | 官方端到端示例 + 文档新鲜度 | 无独立 `examples/agent-*`;Skill/参考里仍有「layout / roadmap」陈旧表述;外人难「照抄即跑通 plan→固化→二次命中」 | `examples/agent-pong`(或同类)+ README;Skill 专节与 A0–A4 对齐 |
|
||||
| **高** | Agent 评测 / 回归 harness | 有离线金样,缺成本·恢复·命中率·补丁质量的系统评测;业界强调 evaluation 先于上线 | `tests/` 或脚本:命中率、llm_free 占比、失败恢复、可选 live 预算 |
|
||||
| **高** | 真 MCP(HTTP/SSE)与凭证 | A4 仅 JSON fixture;缺 streamable HTTP、鉴权、resources/prompts | 金样打 mock MCP server;返回仍带 `authority=workbook` |
|
||||
| **中** | Plan 断点续跑 | 工作簿在盘上,缺显式 checkpoint / resume(对标 LangGraph checkpointer) | `plan resume=` 从第 N 轮 DECISION 继续;进程崩溃可恢复 |
|
||||
| **中** | 人机协同(HITL)加深 | 仅有 `confirm=True` 建簿即停;缺审批卡、拒绝重开、view 一键继续 | view 审批控件 + 金样 |
|
||||
| **中** | 飞轮可观测指标 | `hits` / `improve_every` / `llm_free` 有字段,缺汇总与 CLI/view 报表 | `agent_kb_stats` 或 view 面板:命中率、探索浪费 |
|
||||
| **中** | 受控并行 fan-out | `subtask` 能并行,plan 主路径偏串行 | 父协议允许有界并行调研再合并 |
|
||||
| **低** | 多 Agent / A2A | dual skeleton 有;缺角色班组、跨进程 A2A | 多数场景可用「多工作簿 + 父 CALL」覆盖;有明确跨组织需求再开 |
|
||||
| **低** | Trace 外发(OTLP / Langfuse) | 本地复盘已够;外发是集成题 | 可选 adapter;默认不依赖 |
|
||||
| **刻意不做** | Dense embedding 默认化 | [okf-near-match.md](../roadmap/okf-near-match.md) **E** 仅在 n-gram 证据不足时评估 | 不宣传为默认向量库 |
|
||||
| **刻意不做** | 私有 JSON TOOL 主路径 / 整文件 LLM 重写 | 与宪法及 parent 设计冲突 | 继续禁止 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 分项说明
|
||||
|
||||
### 4.1 产品化(高)
|
||||
|
||||
**问题**
|
||||
内核能力已超过「能演示」门槛,但**可感知产品体验**仍依赖读设计文档与翻 `tests/ext/`。对照 quantum / web 已有 `examples/`,agent 侧空白最明显。
|
||||
|
||||
**建议**
|
||||
1. 一份最小可运行示例:`step` → `plan` → promote → 二次 `plan` 打印 `cache=hit`。
|
||||
2. 同步 Skill / `doc/README` / 公开页,删掉「仅 layout」类过时句。
|
||||
3. 示例强调「权威在 `.mq.md`」,corpus/mcp 仅作证据旁路。
|
||||
|
||||
### 4.2 评测 harness(高)
|
||||
|
||||
**问题**
|
||||
金样锁行为正确性;不锁「飞轮是否在变好」「一次失败后能否恢复」「live 成本是否失控」。2026 多 Agent 讨论普遍把 **evaluation** 列为上线前缺失步骤。
|
||||
|
||||
**建议**
|
||||
- 离线:命中路径、补丁护栏、预算截断(已有)再加 **stats 断言**。
|
||||
- 半自动 / live:固定小 goal 集,记录 rounds、cache 分布、token 粗估(若可从供应商响应取得)。
|
||||
- 明确:评测消费的是工作簿与 kb,而不是外部 transcript 库。
|
||||
|
||||
### 4.3 真 MCP(高)与「证据≠权威」(不变)
|
||||
|
||||
**问题**
|
||||
Fixture 证明协议形状与权威字段;生产要接真实 MCP server(工具、资源、鉴权)。
|
||||
|
||||
**约束**
|
||||
- 工具结果进入 observation / CALL 回执,**不得**静默写成 OKF 权威技能。
|
||||
- 晋升仍走 promote / solidify / 人审(既有路径)。
|
||||
|
||||
### 4.4 断点续跑与 HITL(中)
|
||||
|
||||
**问题**
|
||||
LangGraph 类框架的 checkpointer / interrupt 是生产差异点。Marqdo 已有文件化状态(工作簿、写回、events),差的是**一等恢复 API**与**可视审批**。
|
||||
|
||||
**建议方向**
|
||||
- Resume:序列化「当前 round、path、last observation、events」到约定槽或旁路文件,重启后跳过已完成子跑。
|
||||
- HITL:扩展 `confirm` 语义(建簿 / 危险 PATCH / promote);view 展示 pending 卡。
|
||||
|
||||
### 4.5 飞轮指标与并行(中)
|
||||
|
||||
**问题**
|
||||
第四问(模型调用是否下降)需要数字。并行能缩短探索,但须有界,避免工作簿爆炸(见 [ext-agent.md](../design/ext-agent.md) §9)。
|
||||
|
||||
### 4.6 多 Agent / A2A / 外发 trace(低)
|
||||
|
||||
**问题**
|
||||
业界热度高(Crews、A2A、共享记忆层)。Marqdo 的「父 + 多工作簿」已覆盖多数单组织编排;跨组织 A2A 与共享记忆库是另一产品层,可用 MCP/证据工具接入,而不必把记忆权威搬出 `.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议的下一波分期(草案 B)
|
||||
|
||||
> 非正式锁定;落地时再写入 [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) 或独立 `ext-agent-productize.md`。
|
||||
|
||||
| 波次 | 主题 | 验收线索 |
|
||||
|------|------|----------|
|
||||
| **B0** | 官方示例 + Skill/文档去陈 | `examples/agent-*` 可 `marqdo run`;Skill 与 A0–A4 一致 |
|
||||
| **B1** | 评测 harness | 命中率 / llm_free / 恢复用例可一键跑 |
|
||||
| **B2** | Live MCP 客户端 | mock server 金样;`authority=workbook` 不变 |
|
||||
| **B3** | Plan resume + HITL | 崩溃可续;view 审批 |
|
||||
| **B4** | kb stats 面板 | CLI 或 view 展示飞轮数字 |
|
||||
| **B5** | 有界并行(可选) | fan-out 上限 + 合并观察 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 明确「不是缺口」的清单
|
||||
|
||||
避免把差异化优势误判为缺陷:
|
||||
|
||||
1. **没有默认 dense 向量库** — 有意;OKF near 是稀疏词法;corpus 是关键词证据。
|
||||
2. **没有隐藏 TOOL: JSON 主协议** — 有意;CALL/READ/DECISION 与文档同构。
|
||||
3. **子任务默认 quiet** — 有意;答案走返回值,过程走 events/stream。
|
||||
4. **ext 不直调 host_*** — 有意;Agent 域在插件,防核心膨胀。
|
||||
5. **不捆绑领域工单技能** — 有意;官方框架保持可教、可审、可扩展。
|
||||
|
||||
---
|
||||
|
||||
## 7. 结论与推荐下一刀
|
||||
|
||||
A0–A4 之后,Marqdo `ext/agent` 在「文档驱动智能体」叙事上已经**自洽且可演示**。相对业界,短板是 **被人用起来的路径** 与 **生产级配套**,不是再堆一条编排 DSL。
|
||||
|
||||
**推荐下一刀顺序:**
|
||||
|
||||
1. **B0 官方示例 + 文档去陈**(最低成本、最高感知)
|
||||
2. **B1 评测 harness**(锁住飞轮与质量,防止回退)
|
||||
3. 按真实用户需求选 **B2 live MCP** 或 **B3 resume/HITL**
|
||||
|
||||
若四问在 B0–B1 后均可回答「是」,再考虑 B4/B5 与低优先级项。
|
||||
|
||||
---
|
||||
|
||||
## 8. 参考
|
||||
|
||||
### 本仓
|
||||
|
||||
- [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md)
|
||||
- [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)
|
||||
- [okf-near-match.md](../roadmap/okf-near-match.md)(E dense 仍非默认)
|
||||
- [agent-streaming.md](../roadmap/agent-streaming.md)
|
||||
|
||||
### 外部(抽样,2026)
|
||||
|
||||
- LangGraph Persistence(checkpointer / store)
|
||||
- CrewAI Crews + Flows;MCP 作为工具连接层而非编排本体
|
||||
- 业界对 Agent evaluation、durable memory / A2A 状态层的讨论(共享记忆 ≠ 应取代可执行文档权威)
|
||||
@@ -0,0 +1,533 @@
|
||||
# 调研:主流智能体开发框架与 Marqdo「代码即文档 / 文档即知识库」优势
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 供 `ext/agent` 深入优化参考** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 范围 | 2025–2026 开源/厂商智能体框架形态;对照 Marqdo `ext/ai/agent` 设计 |
|
||||
| 相关设计 | [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) · [okf.md](../design/okf.md) · [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md) |
|
||||
| 姊妹调研 | [okf-and-marqdo.md](okf-and-marqdo.md) · **A0–A4 后缺口** [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
|
||||
| 外部对照(抽样) | [Langfuse 框架对比(2026-07)](https://langfuse.com/blog/2025-03-19-ai-agent-comparison) · [LangGraph persistence](https://docs.langchain.com/oss/python/langgraph/persistence) · [Microsoft Agent Framework / AutoGen 维护模式](https://github.com/microsoft/autogen) · CrewAI / OpenAI Agents SDK / Claude Agent SDK / Google ADK / LlamaIndex 公开文档 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
主流智能体框架几乎都在解决同一组工程问题——**编排、工具、状态、记忆、可观测、人机协同**——但它们的「权威真相」默认落在 **Python/TS 对象图 + 会话 transcript + 外部 Store/向量库** 上。
|
||||
|
||||
Marqdo 的宪法把权威真相定在 **可执行 Markdown(`.mq.md`)**:人写的程序、模型读的提示、执行后的写回、可复用的任务技能,是**同一份文档的不同生命阶段**。这不是「又一个 Agent SDK」,而是把 **Agent 开发本身做成文档工程**。
|
||||
|
||||
由此产生的突出优势(后文展开):
|
||||
|
||||
1. **编排可读 = 提示词不再黑盒**(源码即上下文)
|
||||
2. **过程可审 = 写回进源文件,而不是只进遥测平台**
|
||||
3. **记忆可 git = 成功经验晋升为任务知识包(OKF),审计=仓库历史**
|
||||
4. **复杂任务=子程序,而不是无限加长的 chat**(工作簿 + `subtask`)
|
||||
5. **确定步骤固化为代码,不确定步骤才问模型**(父 Plan-and-Move)
|
||||
6. **语言与知识形态同构**(与 Google OKF「Markdown 知识包」同向,但多走「可执行」一步)
|
||||
|
||||
**优化 `ext/agent` 时应守住这些差异化,而不是向 LangChain 类「隐藏循环 + TOOL: 协议」回退。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 调研方法与边界
|
||||
|
||||
### 1.1 做了什么
|
||||
|
||||
| 动作 | 说明 |
|
||||
|------|------|
|
||||
| 横向扫盘 | 2026 年主流开源框架:LangGraph / LangChain DeepAgents、CrewAI、OpenAI Agents SDK、Claude Agent SDK、Google ADK、Microsoft Agent Framework(AutoGen 继承者)、Pydantic AI、LlamaIndex、Strands、Mastra / Vercel AI SDK、smolagents 等 |
|
||||
| 结构抽象 | 抽取「框架如何形成」的共性分层,而不是比 GitHub stars |
|
||||
| 对照本仓 | 精读 `ext-agent*`、`okf`、`writeback`、`subtask`、parent Plan-and-Move;对照旧 TOOL: 薄循环为何被否定 |
|
||||
| 找优越点 | 只保留 **Marqdo 结构上必然领先**、而非「以后可以加插件追上」的点 |
|
||||
|
||||
### 1.2 不做的
|
||||
|
||||
- 不宣称 Marqdo 在吞吐、多模态、托管运维上已全面领先(这些不是当前差异化)。
|
||||
- 不把「有没有向量检索」当成胜负手——那是应用层可加能力。
|
||||
- 不做厂商营销话术复读;优缺点按**开发者体验与系统真相源**评。
|
||||
|
||||
---
|
||||
|
||||
## 2. 智能体框架是怎么「形成」的
|
||||
|
||||
无论品牌如何包装,成熟框架通常收敛为同一条装配线:
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 1. Model I/O │
|
||||
│ 补全 / 工具调用 / 流式 / 多模供应商适配 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 2. Agent 单元 │
|
||||
│ 指令(system) + 工具表 + 可选角色/人设 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 3. 编排(Orchestration) │
|
||||
│ 图 / 角色队 / 对话群 / 工作流 API / supervisor │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 4. 状态与记忆 │
|
||||
│ 短:thread checkpoint / 会话历史 │
|
||||
│ 长:Store / 向量 RAG / 用户偏好库 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 5. 工具与行动面 │
|
||||
│ 函数 schema、MCP、沙箱、权限、CodeAct │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 6. 可观测与治理 │
|
||||
│ Trace、评测、护栏、HITL、配额 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.1 三种主流「编排哲学」
|
||||
|
||||
| 范式 | 核心隐喻 | 代表 | 可预测性 | 原型速度 |
|
||||
|------|----------|------|----------|----------|
|
||||
| **图 / 状态机** | 节点=步骤,边=转移,状态显式 | LangGraph、Google ADK workflow、MAF workflows | 高 | 中–慢(先画图) |
|
||||
| **角色协作** | Agent=工种,Crew=班组 | CrewAI、早期 AutoGen 群聊 | 中 | 快 |
|
||||
| **薄循环 + 工具** | 「模型自己决定下一步」 | OpenAI Agents SDK、Claude Agent SDK、Strands、smolagents | 低–中(靠护栏) | 最快 |
|
||||
|
||||
2026 年的趋势不是「哪个范式消灭其它」,而是:
|
||||
|
||||
- **生产复杂流** → 图(可控、可恢复、HITL)。
|
||||
- **内容/研究班组** → 角色。
|
||||
- **编码助手 / 生态绑定** → 厂商 SDK 自带 hardened loop。
|
||||
- **LangChain DeepAgents** 等开始把「规划器 + 子代理 + 文件记忆」打包成 opinionated harness——说明业界也意识到:纯 chat 不够,需要**文件与子上下文**。
|
||||
|
||||
### 2.2 记忆层的行业共识(与 Marqdo 对照的关键)
|
||||
|
||||
以 LangGraph 文档为代表(行业事实上的标准划分):
|
||||
|
||||
| 层 | 行业做法 | 作用 |
|
||||
|----|----------|------|
|
||||
| **短时** | Checkpointer / thread_id | 会话续跑、崩溃恢复、time-travel |
|
||||
| **长时** | BaseStore / 向量库 / Mem0·Zep 等 | 跨会话事实、偏好 |
|
||||
| **检索知识** | RAG corpus | 领域文档,不与会话状态混用 |
|
||||
|
||||
常见架构错误:把 checkpointer 当成长时记忆——换 `thread_id` 就「失忆」。
|
||||
|
||||
**这一点对 Marqdo 极关键:**
|
||||
行业把「记忆」拆成多个后端;Marqdo 默认把**任务级成功经验**落成 **`.mq.md` + agent-kb(OKF)**,用文件系统与 git 当记忆平面——见 §7。
|
||||
|
||||
### 2.3 框架「形成产品」的路径
|
||||
|
||||
```text
|
||||
PoC(脚本循环)
|
||||
→ SDK(Agent + tools)
|
||||
→ 编排(图 / 多代理)
|
||||
→ 持久化(checkpoint / store)
|
||||
→ 平台(托管、评测、护栏、计费)
|
||||
```
|
||||
|
||||
越往后,**编排源码与运行时真相越分离**:提示在字符串常量或 Prompt Hub,状态在 DB,轨迹在 Langfuse,知识在向量库。人要复盘一次失败,往往要开四个系统。
|
||||
|
||||
Marqdo 的赌注是:**尽量把真相拉回单一 `.mq.md` 时间线**。
|
||||
|
||||
---
|
||||
|
||||
## 3. 代表框架解剖(如何形成 + 优缺点)
|
||||
|
||||
### 3.1 LangGraph(显式状态图)
|
||||
|
||||
**如何形成**
|
||||
|
||||
- 把 Agent 步骤建模为 **有向图**:节点读/写共享 state,条件边决定下一跳。
|
||||
- 编译为可执行应用;挂 checkpointer → 持久化、HITL interrupt、故障续跑。
|
||||
- 长时记忆另挂 Store;生态上接 LangChain 工具与 LangSmith/Langfuse 轨迹。
|
||||
|
||||
**优点**
|
||||
|
||||
- 生产向可控性最强;分支、重试、并行边清晰。
|
||||
- 状态类型化后,测试与回放(time-travel)可行。
|
||||
- 云中立:图在你自己的进程里跑。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 上手成本高:先设计图,再写节点。
|
||||
- 「提示词 / 业务说明」仍常散落在 Python 字符串;**图代码 ≠ 给人读的说明书**。
|
||||
- 记忆与知识仍依赖外置 Store/RAG;审计链路长。
|
||||
- DeepAgents 等上层 harness 说明:光有图仍不够「文件化协作」。
|
||||
|
||||
**对 Marqdo 的启示**
|
||||
|
||||
- 要学其「显式控制与可恢复」;不要学其「状态默认在对象里」。
|
||||
- Marqdo 多步的工作簿修订环 ≈ **把图展开成磁盘上的可执行文档**。
|
||||
|
||||
---
|
||||
|
||||
### 3.2 CrewAI(角色班组 + Flows)
|
||||
|
||||
**如何形成**
|
||||
|
||||
- Agent = role / goal / backstory;Crew 协调任务;近年加 **Flows** 把确定性业务逻辑包住自治班组。
|
||||
|
||||
**优点**
|
||||
|
||||
- 多代理叙事直观,原型极快。
|
||||
- 适合内容流水线、调研班组。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 协作转移大量靠描述,**可预测性弱于图**。
|
||||
- 过程真相仍是运行时对象与日志;与「文档即程序」无关。
|
||||
- HITL / 企业治理相对弱。
|
||||
|
||||
**对 Marqdo 的启示**
|
||||
|
||||
- 「多角色」可用多个 `# 智能体` / 多个工作簿表达,但应以**可跑文档**为边界,而不是隐式群聊。
|
||||
|
||||
---
|
||||
|
||||
### 3.3 AutoGen → Microsoft Agent Framework(MAF)
|
||||
|
||||
**如何形成**
|
||||
|
||||
- AutoGen:对话对 / 群聊驱动;历史在内存。
|
||||
- 2026:AutoGen **维护模式**;能力并入 **Microsoft Agent Framework**(与 Semantic Kernel 合流):ChatAgent + 多种编排(sequential / concurrent / handoff / group / Magentic)+ 工作流图 + Azure Foundry 治理面。
|
||||
|
||||
**优点**
|
||||
|
||||
- 企业栈(.NET / Azure)一体;A2A、MCP、护栏、托管轨迹。
|
||||
- CodeAct 等模式:让 Agent **写代码执行**而非只吐 JSON——与「固化为代码」方向有共鸣。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 生产治理深度常绑定云平台;开源核心与托管能力分层。
|
||||
- 编排语言仍是通用编程语言;**业务知识与程序不同构**。
|
||||
- 对话范式易导致「无限闲聊」式多代理。
|
||||
|
||||
**对 Marqdo 的启示**
|
||||
|
||||
- CodeAct / 固化步骤:与 Marqdo「确定步骤写成 `##`」同向,但 MAF 写的是 Python;Marqdo 写的是**人与模型共用的 `.mq.md`**。
|
||||
|
||||
---
|
||||
|
||||
### 3.4 OpenAI Agents SDK / Claude Agent SDK / Google ADK / Strands
|
||||
|
||||
**如何形成(共性)**
|
||||
|
||||
- 提供 **hardened agent loop**(工具、handoff、权限、会话)。
|
||||
- 深度绑定自家模型或云(OpenAI / Anthropic Claude Code harness / Gemini+ADK / Bedrock)。
|
||||
|
||||
**优点**
|
||||
|
||||
- 最快接入「能干活的助手」;权限与工具路径经过产品锤炼(尤其 Claude Code 同源 SDK)。
|
||||
- 官方 tracing、realtime 等增值。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 编排与提示仍在宿主语言;**跨团队知识复用靠复制仓库或 Prompt 平台**。
|
||||
- 供应商锁定风险;换模时常换范式。
|
||||
- 「记忆」默认会话式;企业知识仍外挂。
|
||||
|
||||
**对 Marqdo 的启示**
|
||||
|
||||
- 模型 I/O 应继续放在 `ext/llm`,**不要**在 agent 里重造聊天栈。
|
||||
- 不要把「官方 loop」当哲学:Marqdo 的哲学是文档驱动,不是 SDK 驱动。
|
||||
|
||||
---
|
||||
|
||||
### 3.5 LlamaIndex / Haystack(文档与 RAG 优先)
|
||||
|
||||
**如何形成**
|
||||
|
||||
- 以索引、检索、查询引擎为中心;Agent 是检索之上的编排层。
|
||||
|
||||
**优点**
|
||||
|
||||
- 企业文档智能、多格式摄取成熟。
|
||||
- 「知识」有一等公民地位。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 知识默认是 **被检索的被动语料**,不是 **可执行的任务程序**。
|
||||
- Agent 编排能力弱于 LangGraph 系;常需再叠一层框架。
|
||||
- 索引与源文档易漂移(双源真相)。
|
||||
|
||||
**对 Marqdo 的启示(尖锐对比)**
|
||||
|
||||
- LlamaIndex:**文档 → 向量 → 检索 → 回答**。
|
||||
- Marqdo:**文档 → 可执行语法 → 运行 → 写回 →(可选)晋升为任务知识包**。
|
||||
同一「Markdown 知识」在 Marqdo 里可以是 **会跑的技能**,而不仅是 chunk。
|
||||
|
||||
---
|
||||
|
||||
### 3.6 Pydantic AI / Mastra / Vercel AI SDK
|
||||
|
||||
**如何形成**
|
||||
|
||||
- 强调类型安全(Pydantic)或 TS 全栈 DX(Mastra / Vercel)。
|
||||
- 把 Agent 当普通后端组件:校验、otel、耐久执行。
|
||||
|
||||
**优点**
|
||||
|
||||
- 工程化体验好;与现有 Web/API 栈融合。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 仍是「代码库里的 Agent」;非技术干系人无法直接打开同一份编排当说明书。
|
||||
- 知识沉淀路径仍外置。
|
||||
|
||||
---
|
||||
|
||||
### 3.7 横向对比表(开发者真相源)
|
||||
|
||||
| 维度 | 典型框架落点 | Marqdo 落点 |
|
||||
|------|--------------|-------------|
|
||||
| 编排定义 | Python/TS 图或类 | `.mq.md` 标题/表/调用 |
|
||||
| 系统提示 | 字符串 / Prompt Hub | 站立提示写在同一文档 |
|
||||
| 工具 | 装饰器函数 / MCP | runbook 内 `##` + `subtask` |
|
||||
| 短时状态 | checkpoint / session | 工作簿文件 + 写回块 + view |
|
||||
| 长时记忆 | Store / 向量 | agent-kb(OKF)+ git |
|
||||
| 复杂任务 | 子图 / 子代理上下文窗 | **子 `.mq.md` 程序** `spawn path=` |
|
||||
| 复盘 | Langfuse trace | `git log` + 打开工作簿 + view output-card |
|
||||
| 成功复用 | 手工抽 prompt / 存 Store | **固化 + OKF 晋升 / lookup** |
|
||||
|
||||
---
|
||||
|
||||
## 4. 行业共性痛点(框架越强,痛点越清晰)
|
||||
|
||||
下列痛点在 LangGraph、CrewAI、厂商 SDK 文档与实践文章中反复出现;它们正是 Marqdo 要正面打穿的:
|
||||
|
||||
### 4.1 提示词与编排分离
|
||||
|
||||
- 行为由 system prompt + 隐藏模板决定;code review 审不到「模型真正看见什么」。
|
||||
- Prompt 漂移与代码漂移双轨发生。
|
||||
|
||||
### 4.2 过程不透明或只对平台透明
|
||||
|
||||
- 本地只有最终返回值;细节在 SaaS trace。
|
||||
- 合规团队要的「这份文档当时怎么决策的」难以直接交付。
|
||||
|
||||
### 4.3 记忆碎片化
|
||||
|
||||
- thread / store / RAG / 日志四套系统;「上次同类任务怎么做成的」检索成本高。
|
||||
- 成功经验很少自动变成**可再执行资产**。
|
||||
|
||||
### 4.4 多步任务变成超长 transcript
|
||||
|
||||
- 上下文窗口被工具输出撑爆;DeepAgents 才开始「卸到文件系统」。
|
||||
- 说明业界被迫走向 **文件化**——而 Marqdo **一开始就以文件为执行边界**。
|
||||
|
||||
### 4.5 确定性逻辑仍反复问模型
|
||||
|
||||
- 已验证的步骤下一轮又被重新「推理」,浪费且不稳。
|
||||
- 缺少「晋升为普通代码」的一等路径。
|
||||
|
||||
### 4.6 Agent 框架与知识格式断裂
|
||||
|
||||
- Google OKF 等推动「知识用 Markdown 包交换」,但主流 Agent 框架并不把 **可执行程序** 当作知识页。
|
||||
- 结果:知识包给人策展,Agent 另跑一套 Python。
|
||||
|
||||
---
|
||||
|
||||
## 5. Marqdo 在智能体域的设计思想(必须找准)
|
||||
|
||||
### 5.1 宪法重申
|
||||
|
||||
| 口号 | 在 Agent 语境下的含义 |
|
||||
|------|------------------------|
|
||||
| **代码即文档** | 智能体编排、工具表、站立提示、任务叙述写在同一份 `.mq.md`;打开即读、即可跑 |
|
||||
| **文档即知识库** | 写回块、工作簿、OKF 任务页都是知识;Agent 与人共用同一交换面 |
|
||||
| **文档能跑通 = 约定成立** | 金样 / `marqdo run` / view 是验收,不是「旁边另有一份真实现状」 |
|
||||
|
||||
旧「TOOL: 黑盒循环」被官方设计明确否定,正是因为它把 Marqdo **降级成了 LangChain 的薄壳**。
|
||||
|
||||
### 5.2 两级执行(与业界范式对齐但不抄袭)
|
||||
|
||||
| Marqdo | 业界近似 | 关键差异 |
|
||||
|--------|----------|----------|
|
||||
| `## step` 单步 | 薄 Agent loop | 注入**本文件源码 + 调用位置 + Skill**;默认写回 |
|
||||
| `## plan` 多步 | 规划器 + 子代理 | 产物是 **工作簿 `.mq.md`**;经 `subtask` 整文件执行;父以补丁演进 |
|
||||
| 父 Plan-and-Move | supervisor / orchestrator | 行动面:READ/CALL/DECISION;**禁止整文件 LLM 重写** |
|
||||
| OKF agent-kb | long-term store | 命中的是 **可再跑的任务技能**,不是抽象 embedding 片段(可再叠加 soft near) |
|
||||
|
||||
### 5.3 执行与隔离
|
||||
|
||||
- 工具与子工作簿走 `lib/subtask`(`spawn fn=` / `spawn path=`),与主推理隔离——对应业界「子代理独立上下文」,但边界是 **文件与子进程语义**,不是仅换一个 message list。
|
||||
|
||||
---
|
||||
|
||||
## 6. Marqdo 的必要突出优势(核心章节)
|
||||
|
||||
下列优势要求满足:**若取消「可执行 Markdown 为权威」,优势即消失**。这才是「必要」优越点,而不是功能清单攀比。
|
||||
|
||||
### 6.1 单一真相源:编排 / 提示 / 结果共址
|
||||
|
||||
**优势陈述**
|
||||
模型在 `step`/`plan` 中看到的上下文,可以就是**人类正在编辑的那份源码**(及调用点)。站立提示不是隐藏 system blob,而是文档段落。
|
||||
|
||||
**为何必要**
|
||||
消除「提示词仓库 vs 代码仓库」双源;code review、教学、合规审计面对同一人造物。
|
||||
|
||||
**相对框架**
|
||||
LangGraph/CrewAI/SDK:提示常在字符串或控制台配置;trace 在另一系统。Marqdo:`view` 在语句下挂 output-card,与源同行。
|
||||
|
||||
### 6.2 写回 = 内建的「Notebook 输出单元」式过程记忆
|
||||
|
||||
**优势陈述**
|
||||
`lib/writeback` 把成功/失败写入 `<!-- marqdo-out … -->`,锚在调用行下。智能体默认写回后,**过程留在源文件**,不是只留在遥测。
|
||||
|
||||
**为何必要**
|
||||
教学与调试要「看见刚才那一步」;失败成为可读避坑记录;成功可被后续命中。
|
||||
|
||||
**相对框架**
|
||||
业界靠 Langfuse/LangSmith;本地仓库往往是空的。Marqdo 仓库本身就是过程库(可再导出到 trace,但不依赖它才能复盘)。
|
||||
|
||||
### 6.3 复杂任务 = 生成并演进子程序,而不是堆 transcript
|
||||
|
||||
**优势陈述**
|
||||
`plan` 创建 `.marqdo/agent-runs/*.mq.md`,用 `spawn path=` 跑完整 `# main`。父观察**真实退出码、返回值、写回、源码**,再 FIND/REPLACE 补丁。
|
||||
|
||||
**为何必要**
|
||||
上下文窗口有限;长工具输出必须卸出。DeepAgents 用「文件系统抽象」补课;Marqdo **语言层原生就是文件程序**。
|
||||
|
||||
**相对框架**
|
||||
子代理多是「新对话 + 摘要」;Marqdo 子任务是 **可独立 `marqdo run` 的文档**,可被人类直接打开修改后重跑。
|
||||
|
||||
### 6.4 确定步骤固化为代码;模型只处理不确定残差
|
||||
|
||||
**优势陈述**
|
||||
父作为「智能体开发大师」:能写成 `##` 的就固化;子智能体只跑不确定的 `step`。`DECISION: DONE` 可 solidify + OKF 晋升。
|
||||
|
||||
**为何必要**
|
||||
降本、降方差、形成组织资产。业界常把每次任务重新推理;Marqdo 把「学会的技能」编译回语言。
|
||||
|
||||
**相对框架**
|
||||
MAF CodeAct 写出的是通用语言脚本;Marqdo 固化的是 **仍保持文档属性的 `.mq.md` 技能**——人不用会 Python 也能读懂并改。
|
||||
|
||||
### 6.5 文档即知识库 + OKF:记忆可交换、可策展、可信任
|
||||
|
||||
**优势陈述**
|
||||
任务知识包(`.marqdo/agent-kb/`)以 OKF 形承载 `Marqdo Task` / skill,`resource:` 必须指向可执行 `.mq.md`。lookup / near / soft_match 走插件,不进核心 host。
|
||||
|
||||
**为何必要**
|
||||
Google OKF 证明行业需要「Markdown 知识包」;Marqdo 多走一步:**知识页声明的可执行资源真能跑**。记忆不是不可解释的向量命中,而是 **带路径的技能复用**。
|
||||
|
||||
**相对框架**
|
||||
LlamaIndex 检索散文块;Store 存 JSON 事实。Marqdo agent-kb:**命中 → 再跑同一技能路径**(精确 / 规范化 / near / 父裁决)。
|
||||
|
||||
### 6.6 审计与协作默认路径 = Git
|
||||
|
||||
**优势陈述**
|
||||
工作簿演进、写回、晋升都是文件变更 → `git log` / PR / blame。
|
||||
|
||||
**为何必要**
|
||||
企业已有代码治理;不必为 Agent 另建「提示治理平台」才能起步。
|
||||
|
||||
**相对框架**
|
||||
多数框架的状态在 DB;要审计得接专用平台。Marqdo 从第一天就兼容软件工程工作流。
|
||||
|
||||
### 6.7 中英双面 API 与「说明书即程序」教学属性
|
||||
|
||||
**优势陈述**
|
||||
`# 智能体` / `# agent`、`单步`/`step`、`多步`/`plan` 对称;教程文档可以直接是金样。
|
||||
|
||||
**为何必要**
|
||||
智能体开发教育成本高;Marqdo 把教材和运行物合一(与 quantum/math 扩展同一哲学)。
|
||||
|
||||
### 6.8 分层纪律:扩展不脏核心
|
||||
|
||||
**优势陈述**
|
||||
`ext/**` 禁 `host_*`;agent-kb 在 `plugins/agent`;核心保持瘦。
|
||||
|
||||
**为何必要**
|
||||
避免「Agent 框架把语言运行时变成巨石」——这是许多 Python Agent 栈的终局病。
|
||||
|
||||
---
|
||||
|
||||
## 7. 优势地图(一图看懂定位)
|
||||
|
||||
```text
|
||||
可预测性 / 生产控制
|
||||
▲
|
||||
│ LangGraph / MAF workflows
|
||||
│
|
||||
│ ★ Marqdo plan
|
||||
│ (workbook = program)
|
||||
│
|
||||
角色班组 ──────────┼────────────── 薄循环 SDK
|
||||
CrewAI │ OpenAI / Claude SDK
|
||||
│
|
||||
│ LlamaIndex (RAG)
|
||||
│
|
||||
└────────────────────────────►
|
||||
文档/知识一等公民程度
|
||||
|
||||
★ Marqdo 同时偏右上:控制来自「可执行文档+补丁环」,
|
||||
知识来自「同源 Markdown + OKF」,而非向量库单独称王。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 诚实边界:什么时候不该硬吹 Marqdo
|
||||
|
||||
| 场景 | 更合适的选择 | 原因 |
|
||||
|------|--------------|------|
|
||||
| 超大规模并行图、成熟 Python 数据栈 | LangGraph + 现有 infra | 生态与库广度 |
|
||||
| 强绑定 Azure 治理 / .NET | MAF | 平台一体 |
|
||||
| 纯文档问答 / 海量非结构化语料 | LlamaIndex 等 | 摄取与检索成熟;Marqdo 可 **调用** 它们作工具,不必重造 |
|
||||
| 只要一个 ChatGPT 式助手周末原型 | 厂商 Agents SDK | 启动最快 |
|
||||
| 需要强实时语音 / 多模原生 | 厂商 SDK | 非 Marqdo 当前主场 |
|
||||
|
||||
Marqdo 的正确叙事不是「取代所有 Agent 框架」,而是:
|
||||
|
||||
> **当你希望智能体开发成果沉淀为组织可维护的文档资产,并且编排本身必须可教、可审、可跑时——选 Marqdo。**
|
||||
|
||||
---
|
||||
|
||||
## 9. 对 `ext/agent` 深入优化的建议方向(调研导出)
|
||||
|
||||
优化应强化 §6 优势,避免回退到「隐藏 TOOL 循环」。
|
||||
|
||||
| 优先级 | 方向 | 理由 |
|
||||
|--------|------|------|
|
||||
| P0 | **工作簿质量与补丁可靠性**(精确 FIND/REPLACE、固化、观察切片) | 直接决定「子程序演进」是否优于 transcript |
|
||||
| P0 | **OKF 命中体验**(精确 / near / soft_match 默认真策略、策展 UX) | 落实「文档即知识库」的复用飞轮 |
|
||||
| P1 | **过程可见**(streaming / view 过程卡,见 [agent-streaming.md](../roadmap/agent-streaming.md)) | 对标 Langfuse,但真相仍写回文档 |
|
||||
| P1 | **Skill / 源码注入的预算与渐进披露** | 避免上下文爆炸,同时保持「源码即提示」 |
|
||||
| P2 | **与外部 RAG/MCP 的工具化接入** | 补齐语料检索,但不把向量库升为权威真相 |
|
||||
| P2 | **评测金样:同类任务二次 plan 应命中 kb 快路径** | 用测试锁住差异化 |
|
||||
| 避免 | 再引入私有 JSON 工具协议作主路径 | 与宪法冲突 |
|
||||
| 避免 | 整文件 LLM 重写工作簿 | 已在 parent 设计禁止 |
|
||||
|
||||
验收提问(产品自评):
|
||||
|
||||
1. 新人能否只读一份 `.mq.md` 理解 Agent 在干什么?
|
||||
2. 失败后能否在 git 与 view 内完成复盘,不强制打开外部 trace?
|
||||
3. 成功任务下周能否以 **跑同一技能** 的方式复用,而不是「再聊一遍」?
|
||||
4. 确定步骤是否越来越多地变成普通 `##`,模型调用是否下降?
|
||||
|
||||
若四问皆是——优化方向正确。
|
||||
|
||||
---
|
||||
|
||||
## 10. 结论
|
||||
|
||||
2026 年的智能体框架市场在 **图控、角色班组、厂商 hardened loop、RAG 知识** 四条线上分化;共同短板是 **真相源碎片化** 与 **成功经验难以变成可执行组织资产**。
|
||||
|
||||
Marqdo 用「代码即文档、文档即知识库」把 Agent 开发收束到 **可执行 Markdown 生命循环**:
|
||||
|
||||
**书写 → 注入模型 → 执行 → 写回 →(多步)补丁演进 → 固化 → OKF 晋升 → 再命中。**
|
||||
|
||||
这不是功能点堆砌,而是架构级选择。深入优化 `ext/agent` 时,应把资源砸在 **工作簿、写回、固化、知识包命中、过程可视** 上,把「文档驱动的智能体开发框架」做成可感知的产品体验——这才是相对 LangGraph / CrewAI / 厂商 SDK **不可替代** 的优越点。
|
||||
|
||||
---
|
||||
|
||||
## 11. 参考与延伸阅读
|
||||
|
||||
### 本仓
|
||||
|
||||
- [ext-agent.md](../design/ext-agent.md) — 框架总设计(否定 TOOL 薄循环)
|
||||
- [ext-agent-plan.md](../design/ext-agent-plan.md) — 多步工作簿
|
||||
- [ext-agent-parent.md](../design/ext-agent-parent.md) — 父 Plan-and-Move
|
||||
- [okf.md](../design/okf.md) · [okf-and-marqdo.md](okf-and-marqdo.md)
|
||||
- [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md)
|
||||
- [roadmap/agent-streaming.md](../roadmap/agent-streaming.md) · [roadmap/okf-near-match.md](../roadmap/okf-near-match.md) · [roadmap/ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)
|
||||
- [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) — A0–A4 之后还差什么
|
||||
|
||||
### 外部(抽样,2025–2026)
|
||||
|
||||
- Langfuse: *Comparing Open-Source AI Agent Frameworks*(2026-07 更新盘点)
|
||||
- LangGraph docs: Persistence(checkpointer vs store)
|
||||
- Microsoft: AutoGen maintenance → Agent Framework migration
|
||||
- CrewAI: Crews + Flows
|
||||
- OpenAI Agents SDK / Claude Agent SDK / Google ADK 公开 README
|
||||
- Google OKF SPEC v0.2(知识包形态;与 Marqdo 可执行源对照)
|
||||
@@ -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,33 @@
|
||||
# `ext/agent` 深入优化(调研驱动)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **A0–A4 完成**(调研驱动优化闭环;A4:corpus/MCP 证据工具,权威仍是 `.mq.md`) |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · **缺口盘点** [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.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) · [okf.md](../design/okf.md) |
|
||||
| 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 优化原则(来自调研)
|
||||
|
||||
1. **强化差异化,不向 LangChain 薄循环回退**(禁止隐藏 TOOL: 主路径、禁止整文件 LLM 重写工作簿)。
|
||||
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视**。
|
||||
3. 外部 RAG/MCP 只作**工具**,不升为权威真相源。
|
||||
|
||||
自评四问见调研 §9。A0–A4 之后的缺口与建议分期 **B0–B5** 见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 建议分期(摘要)
|
||||
|
||||
| 波次 | 主题 | 验收线索 |
|
||||
|------|------|----------|
|
||||
| **A0** | 工作簿补丁 / 固化可靠性 | **done** — 整文件 FIND 护栏;`soft` 仅 miss;decompose `n` 检查;`workbook_solidify` 单测;金样 `agent-workbook-patch-a0`(双 CONTINUE + solidify) |
|
||||
| **A1** | OKF 复用飞轮(lookup / near / soft_match UX) | **done** — `list_tasks` 含 description/aliases/status/llm_free/hits;`plan` 命中路径暴露 `match`/`score`;soft_match 策展行含 meta;view plan 卡显示 match;金样 `agent-kb-plan-hit`(exact hit + near soft-hit) |
|
||||
| **A2** | 过程可见(stream + view 过程卡) | **done** — `plan_append_*` / `plan_finish_stream` 始终写入 `events`(SSE 仍仅 `stream=True`);OKF REUSE 记 `decision`;view `plan-card` 渲染过程时间线(跳过 delta);金样断言 `events-ok`;对齐 [agent-streaming.md](agent-streaming.md) |
|
||||
| **A3** | 上下文预算(源码/Skill 渐进披露) | **done** — `source_brief` / 加深 `skill_brief`;`build_step_context` 默认预算 + `READ:source|skill`;`step max_reads`;父 `READ:skill`;金样 `agent-context-budget-a3` |
|
||||
| **A4** | 可选:RAG/MCP 工具适配器 | **done** — `corpus_search`(本地语料关键词);`mcp_list_tools` / `mcp_call`(JSON fixture);`authority=workbook`;金样 `agent-tools-rag-a4` |
|
||||
|
||||
细节与行业对照以调研正文为准;本文件只跟踪 **A0–A4** 实现分期。后续产品化 / 评测 / live MCP 等见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) §5(草案 B0–B5)。
|
||||
@@ -0,0 +1,62 @@
|
||||
# 官方扩展:`ext/quantum` 实现路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Q0–Q7 完结 · Q8a/Q8b 完结 · Q8c 待做** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| **锁定设计** | [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** |
|
||||
| **Q7a** | 密度矩阵 / Kronecker / 部分迹 / Hermitian 谱 / Schmidt / Pauli 期望 / 纯度·保真度 — [ext-quantum-q7.md](../design/ext-quantum-q7.md) | **done** |
|
||||
| **Q7b** | 高级 SVG:hinton / city / density / paulivec / qsphere / multibloch | **done** |
|
||||
| **Q7c** | 纠缠示例 + 用户文档 / skill 摘要 | **done** |
|
||||
| **Q8a** | 电路 SVG:标签 gutter + dark/light/bw 门族分色 — [ext-quantum-viz-style.md](../design/ext-quantum-viz-style.md) | **done** |
|
||||
| **Q8b** | probs / bloch / heatmap 共用令牌 | **done** (probs/bloch;heatmap → Q8c) |
|
||||
| **Q8c** | 高级态图(hinton/city/…)换肤 | **pending** |
|
||||
|
||||
验收金样:既有 `tests/ext/quantum-*-smoke.mq.md`;Q7:`quantum-linalg-smoke`、`quantum-viz-advanced-smoke`。示例:`examples/quantum-bell/`、`examples/quantum-entanglement/`。
|
||||
|
||||
---
|
||||
|
||||
## 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,59 @@
|
||||
# 官方扩展:`ext/web` 实现路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **W0–W7 + P3 完结**(审计/RBAC/相册/ETag/外键已落地) |
|
||||
| 日期 | 2026-08-28 |
|
||||
| **锁定设计** | [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** |
|
||||
| **W3s** | 安全硬化:argon2 密码哈希、CSRF、SQLite 会话持久化、CSPRNG、登录限速 | **done** |
|
||||
| **W3.5** | 人写面首版:`web.assemble` + `` `表`.`字段` `` + `examples/man-write-site` | **done**(编排袋仍可再瘦) |
|
||||
| **W4** | Postgres;Redis / S3 驱动(见 [ext-web-drivers.md](../design/ext-web-drivers.md)) | **done** |
|
||||
| **W4c** | 内容标配:SEO / Markdown / RSS / 分页 UI(见 [web-net-capabilities.md](../design/web-net-capabilities.md)) | **done** |
|
||||
| **W5** | 上传与媒体:multipart 接收 + 落盘 + 下载(见 [web-net-capabilities.md](../design/web-net-capabilities.md) A5) | **done** |
|
||||
| **W6** | 迁移 + FTS5 搜索;草稿/评论用既有 where/表;WS 广播 + 访问日志 | **done** |
|
||||
| **W7** | Cache-Control / 404·500 / 重定向 / sitemap·robots / init 唯一·索引 / HTTPS 反代说明 | **done** |
|
||||
| **P3** | 审计时间戳 / 外键 / RBAC / 相册 / ETag | **done** |
|
||||
|
||||
验收金样:`tests/ext/web-smoke.mq.md`、`tests/ext/web-security-smoke.mq.md`、`tests/ext/web-drivers-smoke.mq.md`、`tests/ext/web-upload-smoke.mq.md`、`tests/ext/web-db-w6-smoke.mq.md`、`tests/ext/web-w7-finish-smoke.mq.md`、`tests/ext/web-p3-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` |
|
||||
+12
-12
@@ -1,4 +1,4 @@
|
||||
# Marqdo 参考实现:正经解释器路线图
|
||||
# Marqdo 参考实现:正经解释器路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -47,7 +47,7 @@ index.mq.md (+ 导入的 .mq.md)
|
||||
│
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 0. 源加载 / 模块图 │ frontmatter `> a.mq.md` → 依赖图
|
||||
│ 0. 源加载 / 模块图 │ frontmatter `import a:a.mq.md` → 依赖图
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
@@ -62,12 +62,12 @@ index.mq.md (+ 导入的 .mq.md)
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入合并
|
||||
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入模块树(见 module-namespace)
|
||||
│ │ 作用域链、形参、未定义名诊断
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 4a. 树遍历解释器 │ ← Phase I(必须先完成,跑通全部 examples)
|
||||
│ 4a. 树遍历解释器 │ ← Phase I(必须先完成,跑通全部 tests 金样例)
|
||||
│ 或 │
|
||||
│ 4b. 字节码编译+VM │ ← Phase II(性能与「更像真语言实现」)
|
||||
└─────────┬─────────┘
|
||||
@@ -86,7 +86,7 @@ Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对
|
||||
- 包名:`marqdo`(`src/marqdo/` 或 `marqdo/`)
|
||||
- CLI:`marqdo run <file.mq.md>`,默认找目录下 `index.mq.md`
|
||||
- 诊断:带文件名、行号、列号
|
||||
- 测试:每个 `examples/*.mq.md` 有期望 stdout(金样例);CI 可跑
|
||||
- 测试:每个 `tests/{structure,keywords}/*.mq.md` 有期望 stdout(金样例);CI 可跑
|
||||
|
||||
### Phase I — 可运行的语言核心(树遍历)
|
||||
|
||||
@@ -96,7 +96,7 @@ Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对
|
||||
2. **语法 → AST**:函数、形参、`*` 语句、`**` 返回、`>` 调用、`+` 分支、`-` 循环、表格集合、绑定与 `==`。
|
||||
3. **语义**:提升、嵌套作用域、`##` 私有、frontmatter 导入公有顶层。
|
||||
4. **运行时**:环境、调用栈、值(文/数/表/记录)、内置 `print`。
|
||||
5. **验收**:`examples/structure/*` 与 `examples/keywords/*` 全部 `marqdo run` 通过。
|
||||
5. **验收**:`tests/structure/*` 与 `tests/keywords/*` 全部 `marqdo run` 通过。
|
||||
|
||||
### Phase II — 字节码 VM(正经化)
|
||||
|
||||
@@ -140,11 +140,11 @@ Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对
|
||||
|
||||
```
|
||||
Cargo.toml
|
||||
crates/marqdo/ # 或根包
|
||||
src/lex/ parse/ ast/ sema/ interp/ bytecode/ runtime/
|
||||
tests/
|
||||
examples/
|
||||
spike/ # Python 存档,非运行时依赖
|
||||
tests/ # gold.rs + structure|keywords|errors 夹具
|
||||
public/ # 用户可执行文档
|
||||
doc/ # 设计文稿
|
||||
spike/ # Python 存档,非运行时依赖
|
||||
```
|
||||
|
||||
---
|
||||
@@ -170,9 +170,9 @@ spike/ # Python 存档,非运行时依赖
|
||||
在仓库根或任意含 `index.mq.md` 的目录:
|
||||
|
||||
```bash
|
||||
marqdo run examples/structure/nested-call.mq.md
|
||||
marqdo run tests/structure/nested-call.mq.md
|
||||
# 或
|
||||
marqdo run examples/structure/import/main.mq.md
|
||||
marqdo run tests/structure/import/main.mq.md
|
||||
```
|
||||
|
||||
输出与金样例一致;错误带位置;新增语法必须加金样例与单测。这才是「一门解释型语言」的最低合格线。
|
||||
@@ -0,0 +1,220 @@
|
||||
# 下一阶段:从玩具到可用语言
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **进行中**(P3-D1–D3 live view 断点 v1) |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 目标 | 交互 I/O、可信诊断、可生长标准库;view 渐进成为调试宿主 |
|
||||
| 相关 | [interpreter.md](interpreter.md) · [keywords.md](../design/keywords.md) · [pipeline-debug.md](../design/pipeline-debug.md) · [view.md](../design/view.md) · [view-debug.md](../design/view-debug.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 现状快照(决策依据)
|
||||
|
||||
| 能力 | 现状 | 结论 |
|
||||
|------|------|------|
|
||||
| **`print`** | 树遍历 + 字节码均可用 | 够用 |
|
||||
| **`input`** | CLI 双后端 + `--stdin-file`;frontmatter `stdin:`/`输入:`;live view 表单覆盖;无预置时 capture 提示补线 | **P1a + P1b 完成** |
|
||||
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
|
||||
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
|
||||
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
|
||||
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
|
||||
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
|
||||
|
||||
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
|
||||
|
||||
---
|
||||
|
||||
## 1. 轻重缓急(总序)
|
||||
|
||||
```text
|
||||
P0 诊断加固(短、撬动后续一切)
|
||||
P1 输入补完(先 CLI,再 view)
|
||||
P2 最小标准库(内置 + 可选 .mq.md 库)
|
||||
P3 view 调试(断点 / 单步)—— 在 P0 之后分期,勿一上来做 DAP
|
||||
```
|
||||
|
||||
| 优先级 | 主题 | 为何此刻 | 不做的代价 |
|
||||
|--------|------|----------|------------|
|
||||
| **P0** | 诊断完备度 | 便宜;给金样例、字节码、调试打地基 | 断点停错行;双后端错误体验分裂 |
|
||||
| **P1** | `input` | 「真语言」最低交互面;已有半截实现 | 只能写纯计算/打印 demo |
|
||||
| **P2** | 标准库 | 无库则用户无法写稍大程序 | 人人自造轮子、示例膨胀 |
|
||||
| **P3** | 前端调试 | 差异化(文档即调试);成本最高 | view 仍停留在「跑完看 stdout」 |
|
||||
|
||||
**原则:** 先让 **CLI 树遍历**成为完备参考实现;字节码跟进同语义;view 只接「已有事件/钩子」,不单独发明第二套语义。
|
||||
|
||||
---
|
||||
|
||||
## 2. P0 — 诊断与错误模型(约 3–7 天)
|
||||
|
||||
### 目标
|
||||
|
||||
所有用户可见失败统一为:
|
||||
|
||||
```text
|
||||
path:line:col: message
|
||||
```
|
||||
|
||||
树遍历与字节码**同文案、同位置粒度(至少语句级)**;金样例断言位置而不只子串。
|
||||
|
||||
### 工作项
|
||||
|
||||
1. **统一出口**
|
||||
- 解析侧尽量只产 `Diagnostic`(减少裸 `bail!("7:1: …")`)。
|
||||
- 字节码编译/VM:错误携带 `Span`(或指令 → 源行映射)。
|
||||
2. **位置粒度**
|
||||
- 短期:保持「语句起点」亦可;中期:为 `Expr`/`CallExpr` 补 `span`,让「未定义名」落在标识符上。
|
||||
3. **金样例**
|
||||
- `tests/errors/*`:断言完整 `path:line:col` 前缀(或相对路径规范化后的形式)。
|
||||
- 补:类型错误、除零、循环条件、capture 下 `input` 等。
|
||||
4. **文档**
|
||||
- 更新 [pipeline-debug.md](../design/pipeline-debug.md):错误码/严重级别可列为 P0.5(可选 `E0001` 一类,不阻塞)。
|
||||
|
||||
### 完成定义
|
||||
|
||||
- `cargo test`:errors 金样例含位置。
|
||||
- 同一 `.mq.md` 在 `--backend tree|bytecode` 下诊断一致(允许实现细节差异写进豁免表)。
|
||||
- view 执行失败区仍可读,路径无 `\\?\`。
|
||||
|
||||
### 刻意不做
|
||||
|
||||
- IDE DAP、完整堆栈 UI、sourcemap 可视化编辑器。
|
||||
|
||||
---
|
||||
|
||||
## 3. P1 — 输入(约 1–2 周)
|
||||
|
||||
分两轨:**CLI 必须先绿**;**view 交互后做**。
|
||||
|
||||
### P1a — CLI 完备(高优先级)
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 树遍历 | 已实现 stdin;补 `tests/keywords/input.mq.md`(用管道喂入) |
|
||||
| 字节码 | 增加 `Op::Input`(或等价 host call);与树同语义;capture 下同样拒绝或改走注入 API |
|
||||
| 文档/用户站 | `public/keywords/input.mq.md`;说明「view 默认无交互 stdin」 |
|
||||
|
||||
完成定义:`echo Alice | marqdo run …` 与字节码后端输出一致;金样例稳定。
|
||||
|
||||
### P1b — view / 静态站中的输入(中优先级,接在 P1a 后)
|
||||
|
||||
当前 `run_file_capture` **不能**接真实 stdin——这是设计,不是偶然 bug。
|
||||
|
||||
推荐路径(由易到难):
|
||||
|
||||
1. **脚本化注入(无 UI)**
|
||||
- `marqdo run --stdin-file answers.txt` 或 frontmatter/`---` 旁测数据。
|
||||
- view:执行前提供「预置输入行」文本框,一次性灌入队列。
|
||||
2. **实时交互(live view)**
|
||||
- 执行到 `input` → 暂停 → HTTP/WS 返回 prompt → 用户提交一行 → 继续。
|
||||
- 依赖 P3 的「可暂停执行」钩子;可与断点共用会话模型。
|
||||
3. **静态 `view output`**
|
||||
- 无服务器则只支持预置输入或跳过并标明 `input skipped`。
|
||||
|
||||
完成定义:live `marqdo view` 下至少一个带 `input` 的示例可点按跑通;静态导出行为有文档。
|
||||
|
||||
---
|
||||
|
||||
## 4. P2 — 标准库(约 2–3 周,可与 P1b/P3 前半重叠)
|
||||
|
||||
### 分层
|
||||
|
||||
```text
|
||||
L0 内置函数(解释器内) len / str / int / float? / type?
|
||||
L1 标准库模块(.mq.md) 文本、表/集合小工具;官方路径如 lib/ 或 std/
|
||||
L2 生态约定 catalog 收录;用户站专章
|
||||
```
|
||||
|
||||
### 建议落地顺序
|
||||
|
||||
| 迭代 | 内容 | 依据 |
|
||||
|------|------|------|
|
||||
| **S0** | `len`(文本/表)、`str`、`int` | keywords.md 已列候选;字节码已有闲置 `Op::Len` 可接线 |
|
||||
| **S1** | 表工具:取列、行数;字符串 trim/split(先内置或纯 mq 实现二选一) | 文档型语言高频 |
|
||||
| **S2** | 官方 `lib/` 或 `std/` + 导入约定(仍可用 frontmatter;或日后 `import text:std/text.mq.md`) | 可生长而不破现有导入 |
|
||||
| **S3** | 错误类型约定(如非法 `int` 文本 → 诊断) | 依赖 P0 |
|
||||
|
||||
### 完成定义(S0)
|
||||
|
||||
- 金样例 + 双后端;`public/` 有对应介绍页。
|
||||
- 不引入 `if`/`while` 英文关键字(控制流仍归 Markdown 标记)。
|
||||
|
||||
### 刻意不做(本阶段)
|
||||
|
||||
- 完整面向对象、包管理器、异步 I/O、HTTP 客户端(可列远期)。
|
||||
|
||||
---
|
||||
|
||||
## 5. P3 — 前端成为调试机构(约 3–6 周,分里程碑)
|
||||
|
||||
**不要从 DAP/VS Code 插件开干。** view 已有 Structure / Source / Execution,是天然宿主。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
P0loc[P0 可信位置] --> Pause[语句边界暂停钩子]
|
||||
Pause --> Sess[调试会话 API]
|
||||
Sess --> UI[view 断点与单步 UI]
|
||||
UI --> DAP[可选 DAP 适配]
|
||||
```
|
||||
|
||||
| 里程碑 | 交付 | 依赖 |
|
||||
|--------|------|------|
|
||||
| **D0** | 语句级源映射(树优先;字节码指令→行) | P0 |
|
||||
| **D1** | 运行时钩子:进入语句前可 pause;`--trace-eval` 结构化事件(JSON 行) | D0 |
|
||||
| **D2** | 进程内调试会话:设/清断点、continue、step over(先树遍历) | D1 |
|
||||
| **D3** | **view debug 模式**:源码行点击断点;高亮当前行;侧栏 locals/栈;与文档模式切换 | D2 + 少量 JS 或服务端推进 |
|
||||
| **D4** | 与 P1b 合流:`input` 暂停复用同一会话 | P1b |
|
||||
| **D5**(可选) | DAP 薄适配,供外部 IDE | D2 稳定后 |
|
||||
|
||||
### 完成定义(D3 即「可用调试」)
|
||||
|
||||
- 用户能在 `marqdo view` 对某 `.mq.md` 设断点、单步、看变量。
|
||||
- 文档站默认模式不变(一次执行);debug 为显式开关。
|
||||
- 断点命中行与 P0 诊断行一致(允许文档说明「语句起点」语义)。
|
||||
|
||||
### 风险与边界
|
||||
|
||||
- 静态 `gh-pages` **无法**真断点(无常驻 VM);调试仅 **live view**(或未来 WASM 解释器)。
|
||||
- 字节码调试可晚于树遍历一个迭代。
|
||||
|
||||
---
|
||||
|
||||
## 6. 推荐排期(可执行流程)
|
||||
|
||||
按「每段都可合并、可演示」切周,避免大爆炸:
|
||||
|
||||
| 周序 | 主题 | 可合并交付 |
|
||||
|------|------|------------|
|
||||
| **W1** | P0 诊断统一 + errors 金样例加固 | 双后端错误位置一致 |
|
||||
| **W2** | P1a `input` 字节码 + 管道金样例 + 用户文档 | CLI 交互闭环 |
|
||||
| **W3** | P2-S0 `len`/`str`/`int` + 样例 | 「有点像语言」的第一批库 |
|
||||
| **W4** | P1b 预置输入(view 文本框 / `--stdin-file`) | view 可跑含 input 的 demo |
|
||||
| **W5–W6** | P3-D0–D2 暂停与会话 | 无 UI 也能用 API/CLI 单步 |
|
||||
| **W7–W8** | P3-D3 view 断点 UI + D4 与 input 暂停 | **调试机构**第一版 |
|
||||
| **并行/随后** | P2-S1/S2 扩库;P3-D5 DAP | 按反馈加 |
|
||||
|
||||
若人力紧:**砍掉顺序为 D5 → S2 花活 → 字节码调试**;**不可砍:P0、P1a、P2-S0、D3 之前的 D0–D2。**
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收总表(「真正可用」最低线)
|
||||
|
||||
1. **I/O**:CLI 上 `print`/`input` 双后端一致;view 至少支持预置或交互输入之一。
|
||||
2. **错误**:失败必有稳定位置;常见错误有金样例;用户站不靠「瞎猜 stderr」。
|
||||
3. **库**:至少 `len`/`str`/`int` 可用并有文档。
|
||||
4. **调试**:live view 可断点 + 单步 + 看当前绑定(树遍历即可宣称 v1)。
|
||||
5. **不破坏**:现有 `tests/` 金样例与 `public/` 用户站回归绿。
|
||||
|
||||
---
|
||||
|
||||
## 8. 文档与工程动作(开工时)
|
||||
|
||||
1. 本文件定为「下一阶段宪法」;开工后把各 P 拆到 `doc/design/` 子设计(`input-interactive.md`、`stdlib.md`、`view-debug.md`)。
|
||||
2. 每个里程碑:金样例 → 实现 → `public/` 更新 →(若行为用户可见)再发版 / 刷 `gh-pages`。
|
||||
3. 版本建议:P1a+P0 可打 `v0.0.4`;P2-S0 打 `v0.0.5`;P3-D3 打 `v0.1.0`(「可用调试」语义升级)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话路线
|
||||
|
||||
**先把错误说准、把输入在 CLI 做完,再长出最小标准库;最后把现有 view 升级成可暂停的调试宿主——而不是先做 IDE 插件或大而全标准库。**
|
||||
@@ -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,88 @@
|
||||
# 第 1 章:Marqdo 是什么
|
||||
|
||||
## 1.1 一句话介绍
|
||||
|
||||
**Marqdo = Markdown(Marq)+ 执行(do)**。它把 Markdown 的**标记当作编程语法**:同一个 `.mq.md` 文件,打开给人看是文档,运行给机器看是程序。
|
||||
|
||||
在大型项目里,说明、示例与实现往往分叉成三份「真相」,改一处忘另一处。Marqdo 让这三者**同源**——你写的文档本身就是可执行的代码。
|
||||
|
||||
## 1.2 与其他语言的区别
|
||||
|
||||
传统编程语言(如 Python)需要单独写文档和注释;Marqdo 反过来了——**文档本身就是程序**。
|
||||
|
||||
| 传统语言 | Marqdo |
|
||||
|----------|--------|
|
||||
| 代码在 `.py`,文档在 `.md` | 代码与文档同在 `.mq.md` |
|
||||
| `def` / `if` / `for` / `return` 是关键字 | 用 Markdown 标记 `##` / `1.` / `-` / `**…**` 表达 |
|
||||
| 注释用 `#` 或 `//` | **无标记的叙述就是注释** |
|
||||
| 大括号 `{}` 或缩进界定代码块 | 标题层级 `#` / `##` 界定作用域 |
|
||||
|
||||
关键点:**不要**试图写 `if`、`else`、`while`、`for`、`def`、`return` 这些关键字——它们不是 Marqdo 的语法。控制流由 Markdown 承担。
|
||||
|
||||
## 1.3 安装
|
||||
|
||||
Marqdo 用 Rust 编写。从以下任一方式获取:
|
||||
|
||||
- **发布包**:从 GitHub Releases 下载预编译二进制(已内置标准库)。
|
||||
- **源码构建**:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/cflmy/marqdo.git
|
||||
cd marqdo
|
||||
cargo build --release
|
||||
# 二进制位于 target/release/marqdo
|
||||
```
|
||||
|
||||
验证安装:
|
||||
|
||||
```bash
|
||||
marqdo --version
|
||||
```
|
||||
|
||||
## 1.4 第一个程序
|
||||
|
||||
创建一个文件 `hello.mq.md`:
|
||||
|
||||
```markdown
|
||||
# Hello World
|
||||
|
||||
这是叙述文字,也就是注释。
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
- `# Hello World` —— 对象标题。`# main` 是入口;当文件只有唯一一个顶层 `#` 对象时,它也可作为入口。
|
||||
- 空行后的普通文字是**注释**(叙述)。
|
||||
- `> print text=Hello World!` —— 调用内置函数 `print` 输出一行文本。
|
||||
|
||||
运行:
|
||||
|
||||
```bash
|
||||
marqdo run hello.mq.md
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
Hello World!
|
||||
```
|
||||
|
||||
## 1.5 中英双语内核
|
||||
|
||||
Marqdo 内核内置函数都有中英别名,**无需导入,可混用**:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
`打印` 与 `print` 是同一个内置函数,`内容` 与 `text` 是同一个参数名。
|
||||
|
||||
## 1.6 文件后缀:`.mq.md`
|
||||
|
||||
Marqdo 程序的**后缀必须是 `.mq.md`**(可执行源文件),不能用普通的 `.md`。一个 `.md` 文件默认只是文档;一个 `.mq.md` 文件既是文档又是程序。
|
||||
|
||||
## 1.7 下一步
|
||||
|
||||
你已经能写出并运行第一个程序了。接下来学习[第 2 章:基本语法](./02-基本语法.md)——理解 `.mq.md` 里哪些是代码、哪些是注释,以及标识符的写法。
|
||||
@@ -0,0 +1,151 @@
|
||||
# 第 2 章:基本语法
|
||||
|
||||
## 2.1 文件结构
|
||||
|
||||
一个 `.mq.md` 文件由以下几部分组成:
|
||||
|
||||
1. **Frontmatter**(可选):文件开头的成对 `---` 之间的元信息,如标题、导入。
|
||||
2. **对象 / 函数定义**:以 `#` / `##` 开头的标题。
|
||||
3. **叙述注释**:无标记的普通文字段落。
|
||||
4. **可执行语句**:以标记开头的行。
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 我的程序
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这是叙述段落,整段都是注释。
|
||||
|
||||
> print text=Hello
|
||||
```
|
||||
|
||||
## 2.2 代码 vs 注释:空行分段规则
|
||||
|
||||
Marqdo 的注释规则很特别:**无标记的叙述就是注释**,靠空行分段。
|
||||
|
||||
规则:
|
||||
|
||||
- 空行之后的第一行若**无标记**(普通文字)→ 这一段是**注释**。
|
||||
- 注释段内的**每一行**(直到下一个空行)都是注释——即使它长得像代码。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
这段注释里有一行看起来像代码,但它不会执行:
|
||||
*not_executed = 1*
|
||||
> print text=这也是注释
|
||||
|
||||
空行之后,代码开始运行:
|
||||
|
||||
> print text=这行会运行
|
||||
```
|
||||
|
||||
> **注意**:叙述与可执行代码之间**必须空一行**。忘记空行会让本意是注释的文字被当作代码,或让代码被吞进注释段。
|
||||
|
||||
## 2.3 标记一览表
|
||||
|
||||
以下标记表示「这是代码」:
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| `#` | 对象 / 类型(`# main` = 入口) |
|
||||
| `##` … `######` | 函数 / 方法(嵌套按标题深度) |
|
||||
| `` + `名` `` | 函数标题下的形参 |
|
||||
| `1.` `2.` … | 条件分支 |
|
||||
| `-` | 循环(遍历或 while) |
|
||||
| `> 函数 参数` | 调用 |
|
||||
| `*…*` | 程序语句(赋值 / 表达式) |
|
||||
| `**…**` | 返回值 |
|
||||
| `|` 开头的 GFM 表格 | 集合(列表 / 字典) |
|
||||
| `---` / `***`(函数体内) | 结束函数体 |
|
||||
|
||||
## 2.4 标识符与反引号
|
||||
|
||||
Marqdo 中,**变量、参数名用反引号 `` ` `` 包裹**,这与 Markdown 的代码/链接语法脱钩,避免歧义。
|
||||
|
||||
```markdown
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello, `谁`!
|
||||
```
|
||||
|
||||
- `+ `谁`` —— 声明形参 `谁`
|
||||
- `> print text=Hello, `谁`!` —— 在字符串中引用变量 `谁`
|
||||
|
||||
> **注意**:反引号规则有例外。在 `*…*`(斜体语句)和 `**…**`(粗体返回)内部,**裸标识符就是变量**,反引号可以省略(详见 [第 3 章](./03-变量与赋值.md))。
|
||||
|
||||
## 2.5 字面量
|
||||
|
||||
Marqdo 的字面量:
|
||||
|
||||
| 类型 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| 数字 | `1` `3.14` `-5` | 整数 / 浮点 / 负数 |
|
||||
| 布尔 | `True` `False`(`真` `假`) | 布尔值 |
|
||||
| 空值 | `None`(`空`) | 空值 |
|
||||
| 文本 | `hello`(裸 token) | 无转义,按字面量 |
|
||||
| 字符串 | `"Hello\n"` | 双引号,支持转义与变量插值 |
|
||||
| 列表 | `[1, 2, 3]` | 通过表格构造 |
|
||||
| 字典 | `{"a": 1}` | 通过表格构造 |
|
||||
|
||||
文本 vs 字符串的区别:
|
||||
|
||||
- **裸 token**(如 `hello`、`路径`):按字面量,不转义,适合简短文本。
|
||||
- **双引号字符串**:需要转义(`\n` 等)或嵌入变量时使用。
|
||||
|
||||
```markdown
|
||||
> print text=Hello World! # 裸 token,按字面量
|
||||
*msg = "Hello, `name`!\n"* # 字符串,可插值、可转义
|
||||
```
|
||||
|
||||
## 2.6 关键字(不可作变量名)
|
||||
|
||||
以下单词是 Marqdo 的**保留关键字**,不能用作变量名:
|
||||
|
||||
| 英文 | 中文 | 含义 |
|
||||
|------|------|------|
|
||||
| `True` | `真` | 布尔真 |
|
||||
| `False` | `假` | 布尔假 |
|
||||
| `None` | `空` | 空值 |
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
**不要**尝试用 `if` / `else` / `while` / `for` / `def` / `return` ——它们不是关键字,也没有意义。
|
||||
|
||||
## 2.7 一个完整的例子
|
||||
|
||||
把学到的串起来:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
这是一个完整示例:定义函数、调用、输出。
|
||||
|
||||
> 问候 谁=Marqdo
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=你好,`谁`!
|
||||
|
||||
---
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
运行输出:
|
||||
|
||||
```text
|
||||
你好,Marqdo!
|
||||
```
|
||||
|
||||
## 2.8 下一步
|
||||
|
||||
你已经理解 `.mq.md` 的基本结构了。接下来学习[第 3 章:变量与赋值](./03-变量与赋值.md),掌握 Marqdo 的值存储方式。
|
||||
@@ -0,0 +1,121 @@
|
||||
# 第 3 章:变量与赋值
|
||||
|
||||
## 3.1 什么是变量
|
||||
|
||||
变量是给数据起的一个名字。Marqdo 中,变量在**斜体语句 `*…*`** 中通过 `=` 绑定:
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*name = "Marqdo"*
|
||||
*ok = True*
|
||||
```
|
||||
|
||||
> **重要**:在 `*…*` / `**…**` 内部,**裸标识符就是变量**——不需要反引号。这是 Marqdo 的关键约定。
|
||||
|
||||
## 3.2 绑定的三种写法
|
||||
|
||||
### 写法一:斜体语句 `*…*`(推荐)
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
```
|
||||
|
||||
这是最常用的绑定方式。裸标识符就是变量。
|
||||
|
||||
### 写法二:行首反引号绑定(无 `*…*`)
|
||||
|
||||
```markdown
|
||||
`x` = 1
|
||||
```
|
||||
|
||||
不带 `*…*` 的绑定,变量名**需要反引号**。常用于绑定集合(表格)或公式:
|
||||
|
||||
```markdown
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
```
|
||||
|
||||
### 写法三:绑定调用结果
|
||||
|
||||
```markdown
|
||||
*len_s = > len value="hello"*
|
||||
```
|
||||
|
||||
`*…*` 内用 `= >` 表示「把调用结果赋给变量」。
|
||||
|
||||
## 3.3 引用变量
|
||||
|
||||
在 `*…*` 内部,直接写变量名即可:
|
||||
|
||||
```markdown
|
||||
*a = 5*
|
||||
*b = a * 2*
|
||||
> print text=`b` # 独立 > 调用中,变量要反引号
|
||||
```
|
||||
|
||||
> **关键区别**:在**独立 `>` 调用**(如 `> print …`)里,裸词是**文本**,所以引用变量要加反引号:`> print text=`b``。而在 `*…*` / `**…**` 内,裸词是**变量**:`*b = a * 2*`。
|
||||
|
||||
## 3.4 字符串与插值
|
||||
|
||||
### 双引号字符串
|
||||
|
||||
```markdown
|
||||
*msg = "Hello, World!"*
|
||||
```
|
||||
|
||||
### 转义字符
|
||||
|
||||
| 转义 | 含义 |
|
||||
|------|------|
|
||||
| `\n` | 换行 |
|
||||
| `\t` | 制表 |
|
||||
| `\r` | 回车 |
|
||||
| `\\` | 反斜杠 `\` |
|
||||
| `\"` | 双引号 `"` |
|
||||
| `\'` | 单引号 `'` |
|
||||
| `\xHH` | 十六进制字符(如 `\x22` → `"`) |
|
||||
| `\u{...}` | Unicode 码点(如 `\u{4e2d}` → `中`) |
|
||||
|
||||
未知转义(如 `\q`)**按字面保留**(`\q` → `\q`),不报错。
|
||||
|
||||
### 变量插值
|
||||
|
||||
字符串内用 `` `变量` `` 插值:
|
||||
|
||||
```markdown
|
||||
*name = "Marqdo"*
|
||||
*msg = "Hello, `name`!"*
|
||||
> print text=`msg` # 输出:Hello, Marqdo!
|
||||
```
|
||||
|
||||
## 3.5 完整示例
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*name = "Alice"*
|
||||
*age = 30*
|
||||
*next_age = age + 1*
|
||||
|
||||
> print text=名字:`name`
|
||||
> print text=明年:`next_age` 岁
|
||||
|
||||
*msg = "你好,`name`!你明年 `next_age` 岁。"*
|
||||
> print text=`msg`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
名字:Alice
|
||||
明年:31 岁
|
||||
你好,Alice!你明年 31 岁。
|
||||
```
|
||||
|
||||
## 3.6 下一步
|
||||
|
||||
你已经会存取数据了。接下来学习[第 4 章:输出与输入](./04-输出与输入.md),与用户交互。
|
||||
@@ -0,0 +1,93 @@
|
||||
# 第 4 章:输出与输入
|
||||
|
||||
## 4.1 输出:`print` / `打印`
|
||||
|
||||
`print`(中文 `打印`)是内置函数,用于向标准输出写一行文本。**输出不是 `**粗体**`**——粗体是返回值,不是打印。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
中英等价:
|
||||
|
||||
```markdown
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
| 英文 | 中文 | 参数 |
|
||||
|------|------|------|
|
||||
| `> print text=…` | `> 打印 内容=…` | `text` ≡ `内容` |
|
||||
|
||||
### 输出变量
|
||||
|
||||
独立 `>` 调用中,变量用反引号:
|
||||
|
||||
```markdown
|
||||
*x = 42*
|
||||
> print text=`x` # 输出:42
|
||||
```
|
||||
|
||||
### 输出拼接
|
||||
|
||||
```markdown
|
||||
*name = "Marqdo"*
|
||||
> print text=欢迎使用 `name`!
|
||||
```
|
||||
|
||||
## 4.2 输入:`input` / `输入`
|
||||
|
||||
`input`(中文 `输入`)读取一行用户输入:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> input prompt=你叫什么名字?
|
||||
```
|
||||
|
||||
| 英文 | 中文 | 参数 |
|
||||
|------|------|------|
|
||||
| `> input prompt=…` | `> 输入 提示=…` | `prompt` ≡ `提示` |
|
||||
|
||||
### 读取并保存输入
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*name = > input prompt="请输入名字:"*
|
||||
> print text=你好,`name`!
|
||||
```
|
||||
|
||||
> `input` 的 `prompt` 参数可省略(缺省)。
|
||||
|
||||
## 4.3 完整示例:一个问答程序
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
这是一个人机问答程序。
|
||||
|
||||
*name = > input prompt="你叫什么名字?\n"*
|
||||
> print text=你好,`name`!
|
||||
|
||||
*age = > int value=`age_input`*
|
||||
```
|
||||
|
||||
> **注意**:上面的示例为了展示 `int` 用法,`age_input` 尚未定义。实际中你需要先从 `input` 得到字符串,再用 `int` 转换。完整可运行版本:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*name = > input prompt="你叫什么名字?\n"*
|
||||
> print text=你好,`name`!
|
||||
|
||||
*age_str = > input prompt="你几岁?\n"*
|
||||
*age = > int value=`age_str`*
|
||||
*next_age = age + 1*
|
||||
> print text=`name`,你明年 `next_age` 岁。
|
||||
```
|
||||
|
||||
## 4.4 下一步
|
||||
|
||||
你已经能与用户交互了。接下来学习[第 5 章:运算符与比较](./05-运算符与比较.md)。
|
||||
@@ -0,0 +1,122 @@
|
||||
# 第 5 章:运算符与比较
|
||||
|
||||
## 5.1 算术运算符
|
||||
|
||||
在 `*…*` 表达式内部:
|
||||
|
||||
```markdown
|
||||
*a = 10*
|
||||
*b = 3*
|
||||
|
||||
*sum = a + b* # 13
|
||||
*diff = a - b* # 7
|
||||
*prod = a * b* # 30
|
||||
*quo = a / b* # 3.33…(浮点除法)
|
||||
```
|
||||
|
||||
| 运算符 | 含义 |
|
||||
|--------|------|
|
||||
| `+` | 加法 / 拼接 |
|
||||
| `-` | 减法 |
|
||||
| `*` | 乘法 |
|
||||
| `/` | 除法 |
|
||||
|
||||
> **注意**:在裸表达式里 `/` 是除法;但在**调用实参 / 参数默认值**中,不空格相连的 `a/b` 会被当作路径文本(详见[第 11 章](./11-模块与导入.md))。
|
||||
|
||||
## 5.2 字符串拼接
|
||||
|
||||
`+` 也可以拼接字符串:
|
||||
|
||||
```markdown
|
||||
*first = "Hello, "*
|
||||
*second = "World!"*
|
||||
*msg = first + second*
|
||||
> print text=`msg` # Hello, World!
|
||||
```
|
||||
|
||||
> 在 `*…*` 内变量是裸名;若拼接的是字符串字面量,要加引号。
|
||||
|
||||
## 5.3 比较运算符
|
||||
|
||||
| 运算符 | 含义 |
|
||||
|--------|------|
|
||||
| `==` | 相等 |
|
||||
| `>` | 大于 |
|
||||
| `<` | 小于 |
|
||||
| `>=` | 大于等于 |
|
||||
| `<=` | 小于等于 |
|
||||
|
||||
```markdown
|
||||
*n = 5*
|
||||
|
||||
1. `n` > 3
|
||||
> print text=大于 3
|
||||
2. *
|
||||
> print text=小于等于 3
|
||||
```
|
||||
|
||||
## 5.4 逻辑运算符
|
||||
|
||||
| 英文 | 中文 | 含义 |
|
||||
|------|------|------|
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
```markdown
|
||||
*age = 20*
|
||||
*has_id = True*
|
||||
|
||||
1. `age` >= 18 and `has_id`
|
||||
> print text=可以进入
|
||||
2. *
|
||||
> print text=不能进入
|
||||
```
|
||||
|
||||
## 5.5 布尔值
|
||||
|
||||
布尔值字面量:`True` / `False`(中文 `真` / `假`)。
|
||||
|
||||
```markdown
|
||||
*is_admin = False*
|
||||
|
||||
1. `is_admin` == True
|
||||
> print text=管理员
|
||||
2. *
|
||||
> print text=普通用户
|
||||
```
|
||||
|
||||
也可以直接用布尔变量作条件:
|
||||
|
||||
```markdown
|
||||
*flag = True*
|
||||
|
||||
1. `flag`
|
||||
> print text=为真
|
||||
2. *
|
||||
> print text=为假
|
||||
```
|
||||
|
||||
## 5.6 完整示例
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*score = 85*
|
||||
*passed = score >= 60*
|
||||
*bonus = passed and score >= 80*
|
||||
|
||||
> print text=及格:`passed`
|
||||
> print text=优秀:`bonus`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
及格:True
|
||||
优秀:True
|
||||
```
|
||||
|
||||
## 5.7 下一步
|
||||
|
||||
你已经能计算和判断了。接下来学习[第 6 章:函数](./06-函数.md),把逻辑封装起来复用。
|
||||
@@ -0,0 +1,188 @@
|
||||
# 第 6 章:函数
|
||||
|
||||
## 6.1 定义函数
|
||||
|
||||
在 Marqdo 中,函数用 `##`(及更深)标题定义:
|
||||
|
||||
```markdown
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
- `## 加一` —— 函数名
|
||||
- `+ `n`` —— 参数
|
||||
- `**n + 1**` —— 返回值(**粗体 = 返回**)
|
||||
|
||||
函数可以挂在 `# main` 之下作为嵌套函数,也可以作为顶层自由函数。
|
||||
|
||||
## 6.2 调用函数
|
||||
|
||||
使用 `>` 调用(具名参数或位置参数):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> greet who=World # 具名参数
|
||||
> greet World # 位置参数
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### 具名 vs 位置
|
||||
|
||||
```markdown
|
||||
> 问候 谁=Marqdo # 具名:名=值
|
||||
> 问候 Marqdo # 位置:按形参顺序
|
||||
```
|
||||
|
||||
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。
|
||||
|
||||
> 具名实参的值可以含空格,直到下一个 `名=` 边界;位置实参是单个词法单元(不含空格)。
|
||||
|
||||
## 6.3 参数与默认值
|
||||
|
||||
可选参数用 `=默认值`:
|
||||
|
||||
```markdown
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
|
||||
1. `礼貌`
|
||||
> print text=您好,`谁`!
|
||||
2. *
|
||||
> print text=嗨,`谁`!
|
||||
```
|
||||
|
||||
调用:
|
||||
|
||||
```markdown
|
||||
> 问候 谁=小明
|
||||
> 问候 谁=小明 礼貌=True
|
||||
```
|
||||
|
||||
## 6.4 返回值:`**…**`
|
||||
|
||||
用 `**…**` 返回表达式结果:
|
||||
|
||||
```markdown
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
调用并绑定结果:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*b = > 加一 n=1*
|
||||
> print text=`b` # 2
|
||||
```
|
||||
|
||||
### 返回 None:`****`
|
||||
|
||||
`****`(或空粗体 `**` + 空白 + `**`)返回 `None` 并结束函数体:
|
||||
|
||||
```markdown
|
||||
## 静默
|
||||
+ `x`
|
||||
|
||||
****
|
||||
```
|
||||
|
||||
### 字符串返回
|
||||
|
||||
```markdown
|
||||
## 问候语
|
||||
+ `谁`
|
||||
|
||||
**"你好," + 谁 + "!"**
|
||||
```
|
||||
|
||||
## 6.5 结束函数体:`---` / `***`
|
||||
|
||||
对于**没有返回值、只有副作用**的函数,用单独一行 `---` 或 `***` 结束函数体,避免后续兄弟语句被吞掉:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello, `谁`!
|
||||
|
||||
---
|
||||
|
||||
## 下一个函数
|
||||
...
|
||||
```
|
||||
|
||||
> `---` 仅在**函数体顶层单独一行**时表示「结束本函数」;文件开头的成对 `---` 是 frontmatter,不会混淆。
|
||||
|
||||
## 6.6 完整示例
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=Alice 礼貌=True
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
|
||||
1. `礼貌`
|
||||
> print text=您好,`谁`!
|
||||
2. *
|
||||
> print text=嗨,`谁`!
|
||||
|
||||
---
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
您好,Alice!
|
||||
```
|
||||
|
||||
## 6.7 函数嵌套(标题深度)
|
||||
|
||||
嵌套辅助函数用更深的标题:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 处理 名字=小明
|
||||
|
||||
## 处理
|
||||
+ `名字`
|
||||
|
||||
*上 = > 大写 文本=`名字`*
|
||||
> print text=`上`
|
||||
|
||||
### 大写
|
||||
+ `文本`
|
||||
|
||||
**> str `文本`**
|
||||
```
|
||||
|
||||
> 深度约定:`##` 是 `#` 的子级,`###` 是 `##` 的子级……按标题深度嵌套。
|
||||
|
||||
## 6.8 下一步
|
||||
|
||||
你已经会封装函数了。接下来学习[第 7 章:条件分支](./07-条件分支.md)。
|
||||
@@ -0,0 +1,138 @@
|
||||
# 第 7 章:条件分支
|
||||
|
||||
## 7.1 基本分支:`1.` `2.` …
|
||||
|
||||
Marqdo 用**有序列表** `1.` `2.` `3.` … 表达条件分支:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*n = 5*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=正数
|
||||
2. `n` < 0
|
||||
> print text=负数
|
||||
3. *
|
||||
> print text=零
|
||||
```
|
||||
|
||||
- `1. 条件` —— 第一个分支(条件为真时执行其下的缩进行)
|
||||
- `2. 条件` —— 第二个分支
|
||||
- `3. *` —— else 臂(`N. *` = 否则)
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
正数
|
||||
```
|
||||
|
||||
## 7.2 else 臂:`N. *`
|
||||
|
||||
在 `1.` 之后的任意臂上,**整行恰为 `*`** 表示 else:
|
||||
|
||||
```markdown
|
||||
*age = 15*
|
||||
|
||||
1. `age` >= 18
|
||||
> print text=成年
|
||||
2. *
|
||||
> print text=未成年
|
||||
```
|
||||
|
||||
## 7.3 布尔分支
|
||||
|
||||
```markdown
|
||||
*is_admin = False*
|
||||
|
||||
1. `is_admin`
|
||||
> print text=管理员
|
||||
2. *
|
||||
> print text=普通用户
|
||||
```
|
||||
|
||||
## 7.4 多条件分支
|
||||
|
||||
```markdown
|
||||
*score = 85*
|
||||
|
||||
1. `score` >= 90
|
||||
> print text=优秀
|
||||
2. `score` >= 80
|
||||
> print text=良好
|
||||
3. `score` >= 60
|
||||
> print text=及格
|
||||
4. *
|
||||
> print text=不及格
|
||||
```
|
||||
|
||||
## 7.5 逻辑组合条件
|
||||
|
||||
```markdown
|
||||
*age = 25*
|
||||
*has_id = True*
|
||||
|
||||
1. `age` >= 18 and `has_id`
|
||||
> print text=可以进入
|
||||
2. *
|
||||
> print text=不能进入
|
||||
```
|
||||
|
||||
## 7.6 多个独立分支语句
|
||||
|
||||
**一条分支语句 = 从 `1.` 起、序号递增的一段有序列表。** 同级缩进上**再次出现 `1.`** 会开启**下一条**独立分支语句:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*a = True*
|
||||
*b = False*
|
||||
|
||||
1. `a`
|
||||
> print text=A 为真
|
||||
2. *
|
||||
> print text=A 为假
|
||||
|
||||
1. `b`
|
||||
> print text=B 为真
|
||||
2. *
|
||||
> print text=B 为假
|
||||
```
|
||||
|
||||
这是**两次独立判断**,不是「四个臂的一个分支」。输出:
|
||||
|
||||
```text
|
||||
A 为真
|
||||
B 为假
|
||||
```
|
||||
|
||||
> 臂序号在同一分支内递增(`1.` → `2.` → `3.` …);不要在同一分支中途把序号重置为 `1.`。
|
||||
|
||||
## 7.7 完整示例:成绩评级
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*score = 72*
|
||||
|
||||
1. `score` >= 90
|
||||
> print text=评级:A
|
||||
2. `score` >= 80
|
||||
> print text=评级:B
|
||||
3. `score` >= 70
|
||||
> print text=评级:C
|
||||
4. `score` >= 60
|
||||
> print text=评级:D
|
||||
5. *
|
||||
> print text=评级:F
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
评级:C
|
||||
```
|
||||
|
||||
## 7.8 下一步
|
||||
|
||||
你已经能根据条件走不同路线了。接下来学习[第 8 章:循环](./08-循环.md)。
|
||||
@@ -0,0 +1,179 @@
|
||||
# 第 8 章:循环
|
||||
|
||||
## 8.1 遍历循环:`- [项](集合)`
|
||||
|
||||
Marqdo 用 `-`(无序列表)表达循环。遍历列表用 `- [项](集合)`:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
|
||||
- [果](篮子)
|
||||
> print text=今天吃`果`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
今天吃苹果
|
||||
今天吃梨
|
||||
今天吃桃
|
||||
```
|
||||
|
||||
- `[果](篮子)` —— 遍历 `篮子` 列表,每个元素绑定到 `果`
|
||||
- 循环体内用 `` `果` `` 引用元素(独立 `>` 调用中变量要反引号)
|
||||
|
||||
反引号形式等价(可混用):
|
||||
|
||||
```markdown
|
||||
- [`果`](`篮子`)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
## 8.2 遍历字典:遍历键
|
||||
|
||||
`Map`(字典)用 `- [键](映射)` 遍历**键**:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`分类` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 水果 | 蔬菜 |
|
||||
|
||||
- [键](分类)
|
||||
> print text=`键`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
苹果
|
||||
黄瓜
|
||||
```
|
||||
|
||||
> 遍历字典遍历的是键;要取值,用脚注取元(见[第 9 章](./09-集合.md))。
|
||||
|
||||
## 8.3 while 循环:`- 条件`
|
||||
|
||||
`-` 后直接写条件就是 while 循环:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*n = 3*
|
||||
|
||||
- `n` > 0
|
||||
> print text=`n`
|
||||
*n = n - 1*
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
3
|
||||
2
|
||||
1
|
||||
```
|
||||
|
||||
> 循环体内用 `*…*` 语句更新变量。
|
||||
|
||||
## 8.4 嵌套循环
|
||||
|
||||
循环可以嵌套:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`外层` =
|
||||
|
||||
| 项 |
|
||||
|----|
|
||||
| A |
|
||||
| B |
|
||||
|
||||
`内层` =
|
||||
|
||||
| 项 |
|
||||
|----|
|
||||
| 1 |
|
||||
| 2 |
|
||||
|
||||
- [o](外层)
|
||||
- [i](内层)
|
||||
> print text=`o``i`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
A1
|
||||
A2
|
||||
B1
|
||||
B2
|
||||
```
|
||||
|
||||
## 8.5 循环 + 分支组合
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`数字` =
|
||||
|
||||
| 值 |
|
||||
|----|
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
|
||||
- [n](数字)
|
||||
1. `n` >= 3
|
||||
> print text=`n` 是大数
|
||||
2. *
|
||||
> print text=`n` 是小数
|
||||
```
|
||||
|
||||
> 循环体里的 `1.` / `2.` 是分支语句(见[第 7 章](./07-条件分支.md)),与 `-` 循环嵌套使用。
|
||||
|
||||
## 8.6 完整示例:累计求和
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`数字` =
|
||||
|
||||
| 值 |
|
||||
|----|
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
| 5 |
|
||||
|
||||
*sum = 0*
|
||||
|
||||
- [n](数字)
|
||||
*sum = sum + n*
|
||||
|
||||
> print text=总和:`sum`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
总和:15
|
||||
```
|
||||
|
||||
## 8.7 下一步
|
||||
|
||||
你已经掌握循环了。接下来学习[第 9 章:集合(表格)](./09-集合.md),深入理解列表、字典与记录。
|
||||
@@ -0,0 +1,203 @@
|
||||
# 第 9 章:集合(表格)
|
||||
|
||||
Marqdo 用 **GFM 表格**直接构造数据集合。表格的**几何形状**决定值的类型——这是 Marqdo 最有特色的部分:你看到的 Markdown 表格就是数据结构。
|
||||
|
||||
## 9.1 绑定一个集合
|
||||
|
||||
集合绑定用「空右侧赋值 + 表格」:
|
||||
|
||||
```markdown
|
||||
`名字` =
|
||||
|
||||
| 表头1 | 表头2 |
|
||||
|-------|-------|
|
||||
| 值 | 值 |
|
||||
```
|
||||
|
||||
表格绑定变量名**需要反引号**(不在 `*…*` 内)。
|
||||
|
||||
## 9.2 单列竖表 → 列表(List)
|
||||
|
||||
**恰好 1 列** → 列表:
|
||||
|
||||
```markdown
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
```
|
||||
|
||||
等价于 `["苹果", "梨", "桃"]`。表头 `果` 是元素逻辑名(foreach 绑定名),**不进入列表元素**。
|
||||
|
||||
```markdown
|
||||
- [果](篮子)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
## 9.3 多列 + 一行 → 字典(Map)
|
||||
|
||||
**≥2 列 + 恰好 1 行数据** → 字典,键 = 表头:
|
||||
|
||||
```markdown
|
||||
`分类` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 水果 | 蔬菜 |
|
||||
```
|
||||
|
||||
等价于 `{"苹果": "水果", "黄瓜": "蔬菜"}`。
|
||||
|
||||
## 9.4 多列 + 多行 → 字典套列表
|
||||
|
||||
**≥2 列 + ≥2 行数据** → 字典,值为该列的列表(列向聚合):
|
||||
|
||||
```markdown
|
||||
`货架` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 红富士 | 青瓜 |
|
||||
| 嘎啦 | 黄瓜条 |
|
||||
```
|
||||
|
||||
等价于:
|
||||
|
||||
```text
|
||||
{"苹果": ["红富士", "嘎啦"], "黄瓜": ["青瓜", "黄瓜条"]}
|
||||
```
|
||||
|
||||
## 9.5 行向记录表 → 记录列表
|
||||
|
||||
首列表头为 `@` / `行` / `row` 时,整表改为**行向**(SQL/CSV 风格):
|
||||
|
||||
```markdown
|
||||
`订单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
| 2 | 梨 | 3 |
|
||||
```
|
||||
|
||||
等价于:
|
||||
|
||||
```text
|
||||
[{"品名": "苹果", "数量": 2}, {"品名": "梨", "数量": 3}]
|
||||
```
|
||||
|
||||
标记列(`行`)不进入记录字段。
|
||||
|
||||
## 9.6 表格形状速查
|
||||
|
||||
| 形状 | 值类型 |
|
||||
|------|--------|
|
||||
| 1 列 | `List` |
|
||||
| ≥2 列 + 1 行 | `Map`(标量值) |
|
||||
| ≥2 列 + ≥2 行 | `Map`(值均为 `List`) |
|
||||
| ≥2 列 + 0 行 | `Map`(键存在,值空列表) |
|
||||
| 首列 `@`/`行`/`row` | `List` of `Map`(行向记录) |
|
||||
|
||||
## 9.7 脚注取元:`[^…]`
|
||||
|
||||
用 Markdown 脚注外形从集合取元素(**表达式级**,可链式)。
|
||||
|
||||
### 从列表按下标取
|
||||
|
||||
**下标是 1-based**(与人类读表一致):
|
||||
|
||||
```markdown
|
||||
*第一 = 篮子[^1]*
|
||||
> print text=`第一` # 苹果
|
||||
```
|
||||
|
||||
### 从字典按键取
|
||||
|
||||
```markdown
|
||||
*种 = 分类[^苹果]*
|
||||
> print text=`种` # 水果
|
||||
```
|
||||
|
||||
### 嵌套取元
|
||||
|
||||
```markdown
|
||||
*第一种苹果 = 货架[^苹果][^1]* # 先键,再下标 → 红富士
|
||||
```
|
||||
|
||||
### 基名的反引号
|
||||
|
||||
`` 名[^键] `` 与 `` `名`[^键] `` 等价(紧跟 `[^` 时可省略反引号):
|
||||
|
||||
```markdown
|
||||
*种 = `分类`[^苹果]*
|
||||
```
|
||||
|
||||
### 插值中的取元
|
||||
|
||||
在**调用实参值 / 引号字符串**里,`` `变量` `` 后**紧跟**(无空白)`[^…]` 时也按取元解析,而不必先绑定再输出:
|
||||
|
||||
```markdown
|
||||
> print text=苹果单价:`水果价格`[^苹果] # 输出:苹果单价:5
|
||||
> print text=第一种:`货架`[^苹果][^1] # 链式取元 → 红富士
|
||||
> print text="价 `水果价格`[^香蕉] 元" # 引号字符串内也可取元 → 价 3 元
|
||||
```
|
||||
|
||||
> 规则:`` `变量` [^…] ``(**有空白**)时 `[^…]` 仍是普通文本;只有 `` `变量`[^…] ``(无空白)才算取元。
|
||||
|
||||
> 规则:
|
||||
> - **List**:标签须为纯数字(1-based);`[^0]` 或越界 → 报错。
|
||||
> - **Map**:标签为键文本(含纯数字键,如 `[^00]`);缺键 → 报错。
|
||||
> - 文末的 `[^1]: …` 定义块仍是注释,与取元无关。
|
||||
|
||||
## 9.8 表格单元格是表达式
|
||||
|
||||
数据单元格支持表达式(与调用实参值语法相同):裸词、数字、`` `var` ``、算术、引号串。URL / `gpt-4o-mini` 等按路径/连字符折叠为文本。
|
||||
|
||||
```markdown
|
||||
*k = "secret"*
|
||||
|
||||
`cfg` =
|
||||
|
||||
| api_key | model |
|
||||
|---------|-------|
|
||||
| `k` | gpt-4o-mini |
|
||||
```
|
||||
|
||||
## 9.9 完整示例
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`水果价格` =
|
||||
|
||||
| 苹果 | 香蕉 |
|
||||
|------|------|
|
||||
| 5 | 3 |
|
||||
|
||||
> print text=苹果单价:`水果价格`[^苹果]
|
||||
|
||||
`购物单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
| 2 | 香蕉 | 3 |
|
||||
|
||||
- [行](购物单)
|
||||
> print text=`行`[^品名] × `行`[^数量]
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
苹果单价:5
|
||||
苹果 × 2
|
||||
香蕉 × 3
|
||||
```
|
||||
|
||||
## 9.10 下一步
|
||||
|
||||
你已经掌握 Marqdo 的数据组织了。接下来学习[第 10 章:对象与方法](./10-对象与方法.md)。
|
||||
@@ -0,0 +1,195 @@
|
||||
# 第 10 章:对象与方法
|
||||
|
||||
Marqdo 用 `#` 标题定义**对象 / 类型**,用 `##` 定义其下的**方法**。这是一种轻量、可读的面向对象写法。
|
||||
|
||||
## 10.1 定义对象(类型)
|
||||
|
||||
`#`(恰好一层)定义一个对象 / 类型,其正文是**构造体**:
|
||||
|
||||
```markdown
|
||||
# 大模型
|
||||
+ `模型名`
|
||||
|
||||
*配置 = > json.parse text={"model":"gpt-4o-mini"}*
|
||||
**配置**
|
||||
```
|
||||
|
||||
- `# 大模型` —— 类型名
|
||||
- `+ `模型名`` —— 构造参数
|
||||
- 构造体执行后 `**…**` 返回一个 map,运行时写入 `_type` 字段,形成实例句柄
|
||||
|
||||
## 10.2 构造实例
|
||||
|
||||
调用类型名即可构造实例:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*模型 = > 大模型 模型名="gpt-4o-mini"*
|
||||
```
|
||||
|
||||
## 10.3 定义方法
|
||||
|
||||
对象下的 `##` 标题是方法:
|
||||
|
||||
```markdown
|
||||
# 计数器
|
||||
+ `初始值`
|
||||
|
||||
*状态 = > json.parse text={"n":0}*
|
||||
*状态 = > json.set map=`状态` key="n" value=`初始值`*
|
||||
**状态**
|
||||
|
||||
## 加一
|
||||
|
||||
*n = > json.get value=`self` key="n"*
|
||||
*n2 = n + 1*
|
||||
*t = > json.set map=`self` key="n" value=`n2`*
|
||||
**t**
|
||||
```
|
||||
|
||||
方法体内自动绑定:
|
||||
|
||||
- `self`(英文)
|
||||
- `自`(中文)
|
||||
|
||||
二者是同一个接收者,指向当前实例。
|
||||
|
||||
## 10.4 调用方法
|
||||
|
||||
### 独立 `>` 调用(接收者加反引号)
|
||||
|
||||
```markdown
|
||||
*计数器 = > 计数器 初始值=3*
|
||||
*新值 = > `计数器`.加一*
|
||||
```
|
||||
|
||||
### `*…*` 段内调用(接收者裸名)
|
||||
|
||||
```markdown
|
||||
*计数器 = > 计数器 初始值=3*
|
||||
*新值 = > 计数器.加一*
|
||||
```
|
||||
|
||||
> **重要**:在 `*…*` / `**…**` 段内,裸词是变量,所以**方法接收者不加反引号**:`*新值 = > 计数器.加一*`。而在独立 `>` 调用中,裸词是文本,接收者需要反引号:`> `计数器`.加一`。
|
||||
|
||||
## 10.5 完整对象示例
|
||||
|
||||
对象(`#`)定义在**顶层**,与 `# main` 平级:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*c = > 计数器 初始值=5*
|
||||
*ty = > json.get value=`c` key="_type"*
|
||||
> print text=类型:`ty`
|
||||
|
||||
*c2 = > c.加一*
|
||||
*n = > json.get value=`c2` key="n"*
|
||||
> print text=加一后:`n`
|
||||
|
||||
# 计数器
|
||||
+ `初始值`
|
||||
|
||||
*状态 = > json.parse text={"n":0}*
|
||||
*状态 = > json.set map=`状态` key="n" value=`初始值`*
|
||||
**状态**
|
||||
|
||||
## 加一
|
||||
|
||||
*n = > json.get value=`self` key="n"*
|
||||
*n2 = n + 1*
|
||||
*t = > json.set map=`self` key="n" value=`n2`*
|
||||
**t**
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
类型:计数器
|
||||
加一后:6
|
||||
```
|
||||
|
||||
## 10.6 继承:`# Child = > Parent`
|
||||
|
||||
```markdown
|
||||
# Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*msg = "Hello, `who`!"*
|
||||
**msg**
|
||||
|
||||
# Loud = > Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*msg = "HELLO, `who`!"*
|
||||
**msg**
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| 语法 | `# Child = > Parent` |
|
||||
| `_type` | 构造后仍为**最具体子类名** |
|
||||
| 方法查找 | 先子类 `##`,未命中再沿基类链;同名则子类覆盖 |
|
||||
| 构造 | **不**隐式调用父构造(无 auto-super) |
|
||||
| 多继承 | 不支持 |
|
||||
|
||||
### 显式调用父构造
|
||||
|
||||
子类需要父字段时,在子类正文首行显式调用父构造:
|
||||
|
||||
```markdown
|
||||
# Child = > Parent
|
||||
+ `name`
|
||||
|
||||
*self = > Parent name=`name`*
|
||||
*self = > json.set map=`self` key="role" value="child"*
|
||||
**self**
|
||||
```
|
||||
|
||||
## 10.7 完整继承示例
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*c = > Child name="Ada"*
|
||||
*ty = > json.get value=`c` key="_type"*
|
||||
*role = > json.get value=`c` key="role"*
|
||||
> print text=`ty`
|
||||
> print text=`role`
|
||||
|
||||
# Parent
|
||||
+ `name`
|
||||
|
||||
*out = > json.parse text={"role":"parent"}*
|
||||
*out = > json.set map=`out` key="name" value=`name`*
|
||||
**out**
|
||||
|
||||
# Child = > Parent
|
||||
+ `name`
|
||||
|
||||
*self = > Parent name=`name`*
|
||||
*self = > json.set map=`self` key="role" value="child"*
|
||||
**self**
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
Child
|
||||
child
|
||||
```
|
||||
|
||||
## 10.8 下一步
|
||||
|
||||
你已经会面向对象编程了。接下来学习[第 11 章:模块与导入](./11-模块与导入.md),组织大型项目。
|
||||
@@ -0,0 +1,175 @@
|
||||
# 第 11 章:模块与导入
|
||||
|
||||
大型项目需要把代码拆成多个文件。Marqdo 用 **frontmatter 导入**和**点号寻址**组织模块。
|
||||
|
||||
## 11.1 Frontmatter 元信息
|
||||
|
||||
文件开头的成对 `---` 之间是 frontmatter,存放元信息(标题、描述、导入):
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 我的程序
|
||||
description: 描述文字
|
||||
---
|
||||
```
|
||||
|
||||
## 11.2 导入文件:`import 绑定:路径.mq.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
import time:lib/time.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
- `text` —— 绑定名(本地库名)
|
||||
- `lib/text.mq.md` —— 目标文件路径
|
||||
|
||||
导入后得到一个**库(模块)绑定**,成员**不会**倒进全局。
|
||||
|
||||
中文等价:`导入 文本:lib/文本.mq.md`。
|
||||
|
||||
## 11.3 点号寻址调用:`库.成员`
|
||||
|
||||
导入后用裸点号路径调用库成员:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*t = > time.now_unix*
|
||||
*s = > time.format unix=`t` pattern="%Y-%m-%d"*
|
||||
> print text=`s`
|
||||
```
|
||||
|
||||
- `time.now_unix` —— 调用 `time` 库的 `now_unix` 函数
|
||||
- `time.format` —— 调用 `time` 库的 `format` 函数
|
||||
|
||||
**库名不是变量**:路径段是裸标识符,不加反引号。
|
||||
|
||||
## 11.4 三段路径:`库.类型.方法`
|
||||
|
||||
```markdown
|
||||
---
|
||||
import agent:ext/ai/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*助手 = > agent.agent model="gpt-4o-mini"* # 库 → 类型:构造
|
||||
```
|
||||
|
||||
`agent.agent` —— `agent` 库中的 `agent` 类型(构造)。
|
||||
|
||||
## 11.5 短名:`import 绑定:库.成员`
|
||||
|
||||
把库路径成员绑为本地短名:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import fmt:time.format
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*t = > time.now_unix*
|
||||
*s = > fmt unix=`t` pattern="%Y-%m-%d"*
|
||||
```
|
||||
|
||||
`fmt` 现在是 `time.format` 的短名。
|
||||
|
||||
## 11.6 方法调用 vs 库路径(Python 统一命名空间)
|
||||
|
||||
对裸点号 `a.b`,规则是:
|
||||
|
||||
- 若 `a` 是当前作用域的**局部变量** → **方法调用**(`a` 为接收者)
|
||||
- 否则 → **库路径**
|
||||
|
||||
| 写法 | 含义 |
|
||||
|------|------|
|
||||
| `time.parse` | 库路径(裸名,第一段非变量) |
|
||||
| `` > `助手`.step `` | 独立 `>` 调用:实例方法(接收者反引号) |
|
||||
| `*回复 = > 助手.step …*` | `*…*` 段内:`助手` 是变量 → 实例方法;否则 → 库路径 |
|
||||
|
||||
```markdown
|
||||
---
|
||||
import agent:ext/ai/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*助手 = > agent.agent model="gpt-4o-mini"*
|
||||
*out = > 助手.step task="你好"* # 助手是变量 → 方法调用
|
||||
```
|
||||
|
||||
## 11.7 完整示例:多模块程序
|
||||
|
||||
假设项目结构:
|
||||
|
||||
```text
|
||||
project/
|
||||
├── main.mq.md
|
||||
├── lib/
|
||||
│ ├── 数学.mq.md
|
||||
│ └── 问候.mq.md
|
||||
```
|
||||
|
||||
`lib/数学.mq.md`:
|
||||
|
||||
```markdown
|
||||
## 加倍
|
||||
+ `n`
|
||||
|
||||
**n * 2**
|
||||
```
|
||||
|
||||
`lib/问候.mq.md`:
|
||||
|
||||
```markdown
|
||||
## 你好
|
||||
+ `谁`
|
||||
|
||||
> print text=你好,`谁`!
|
||||
```
|
||||
|
||||
`main.mq.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import 数学:lib/数学.mq.md
|
||||
import 问候:lib/问候.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*结果 = > 数学.加倍 n=21*
|
||||
> print text=`结果`
|
||||
|
||||
> 问候.你好 谁=世界
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
42
|
||||
你好,世界!
|
||||
```
|
||||
|
||||
## 11.8 库路径解析
|
||||
|
||||
`lib/…` 按以下顺序解析:
|
||||
|
||||
1. 环境变量 `MARQDO_LIB`
|
||||
2. 当前目录下的 `lib/`
|
||||
3. `marqdo` 可执行文件旁边的 `lib/`(及几个父目录)
|
||||
|
||||
官方扩展(`ext/`)用 `marqdo ext add llm|agent|web|quantum` 安装,导入仍写 `import llm:ext/llm.mq.md` 等。
|
||||
|
||||
## 11.9 下一步
|
||||
|
||||
你已经能组织大型项目了。接下来学习[第 12 章:标准库](./12-标准库.md),使用官方能力。
|
||||
@@ -0,0 +1,172 @@
|
||||
# 第 12 章:标准库
|
||||
|
||||
Marqdo 内置函数无需导入即可使用;更丰富的能力通过导入 `lib/` 模块获得。
|
||||
|
||||
## 12.1 内置函数(无需导入)
|
||||
|
||||
| 英文 | 中文 | 作用 |
|
||||
|------|------|------|
|
||||
| `print` | `打印` | 写标准输出(参数 `text` ≡ `内容`) |
|
||||
| `input` | `输入` | 读一行(参数 `prompt` ≡ `提示`) |
|
||||
| `len` | `长度` | 文本 / 集合长度(参数 `value` ≡ `值`) |
|
||||
| `str` | `文本` | 转为显示文本(参数 `value` ≡ `值`) |
|
||||
| `int` | `整数` | 转为整数(参数 `value` ≡ `值`) |
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello
|
||||
|
||||
*s = "Marqdo"*
|
||||
*n = > len value=`s`*
|
||||
> print text=长度:`n`
|
||||
```
|
||||
|
||||
## 12.2 标准库模块
|
||||
|
||||
导入一个 `lib/` 文件,使用**该文件**的函数名:
|
||||
|
||||
| 英文导入 | 中文导入 | 典型功能 |
|
||||
|----------|----------|----------|
|
||||
| `lib/text.mq.md` | `lib/文本.mq.md` | 文本处理(去空白、拆分、拼接) |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | 列表 / 字典元素更新 |
|
||||
| `lib/fs.mq.md` | `lib/文件.mq.md` | 文件系统 |
|
||||
| `lib/sys.mq.md` | `lib/系统.mq.md` | 进程 / 当前目录 / 加载环境变量 |
|
||||
| `lib/plugin.mq.md` | `lib/插件.mq.md` | 加载原生 ABI 插件 |
|
||||
| `lib/time.mq.md` | `lib/时间.mq.md` | 时间 / 格式化 |
|
||||
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) |
|
||||
| `lib/json.mq.md` | — | JSON 解析 / 序列化 |
|
||||
| `lib/math.mq.md` | `lib/数学.mq.md` | 数值、三角函数、随机、公式、绘图 |
|
||||
| `lib/foreign.mq.md` | `lib/外联.mq.md` | 运行异种语言代码块 |
|
||||
|
||||
> **语言一致性**:导入英文库文件,就用其英文 API;导入中文库文件,就用其中文 API。不要混用语言。
|
||||
|
||||
## 12.3 JSON 模块示例
|
||||
|
||||
`json` 模块负责**文本 ↔ 结构化数据**的序列化转换,以及把文本字符串里的 `\n` 等转义还原:
|
||||
|
||||
| 函数 | 作用 |
|
||||
|------|------|
|
||||
| `json.parse` | 解析 JSON 文本 |
|
||||
| `json.stringify` | 序列化为 JSON 文本 |
|
||||
| `json.get` | 取字段(键) |
|
||||
| `json.keys` | 取所有键 |
|
||||
| `json.set` | 设字段 |
|
||||
| `json.append` | 向列表追加 |
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*obj = > json.parse text={"a":1}*
|
||||
*out = > json.stringify value=`obj`*
|
||||
> print text=`out` # {"a":1}
|
||||
|
||||
*nl = > json.parse text={"n":"\n"}*
|
||||
> print text=第一行`nl`[^n]第二行 # 换行还原
|
||||
```
|
||||
|
||||
> **字典操作**:本地字典的读取用脚注取元 `变量[^键]`,**不要**用 `json.get`。`json.get` / `json.set` 仅用于跨文本边界的序列化场景(例如与外部 JSON API 交换数据时)。构造字典用 GFM 横表(见[第 9 章](./09-集合.md))。
|
||||
`json` 常用函数:
|
||||
|
||||
| 函数 | 作用 |
|
||||
|------|------|
|
||||
| `json.parse` | 解析 JSON 文本 |
|
||||
| `json.stringify` | 序列化为 JSON 文本 |
|
||||
| `json.get` | 取字段(键) |
|
||||
| `json.keys` | 取所有键 |
|
||||
| `json.set` | 设字段 |
|
||||
| `json.append` | 向列表追加 |
|
||||
|
||||
## 12.4 文本模块示例
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*parts = > text.str_split s="a,b,c" sep=","*
|
||||
> print text=`parts`
|
||||
|
||||
*joined = > text.str_join xs=`parts` sep="-"*
|
||||
> print text=`joined` # a-b-c
|
||||
```
|
||||
|
||||
## 12.5 数学模块:公式与绘图
|
||||
|
||||
```markdown
|
||||
---
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*值 = > math.num value=3.5*
|
||||
> print text=`值`
|
||||
```
|
||||
|
||||
公式绑定:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*_svg = > math.plot formula=`f` var=x min=-3 max=3*
|
||||
```
|
||||
|
||||
空 RHS 赋值 + 后随 `$$…$$` 绑定一个公式值。
|
||||
|
||||
## 12.6 官方扩展库(`ext/`)
|
||||
|
||||
扩展库不是 stdlib,需安装:
|
||||
|
||||
```bash
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
导入仍写 `import …:ext/….mq.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import llm:ext/llm.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*模型 = > llm.llm model="gpt-4o-mini"*
|
||||
```
|
||||
|
||||
| 扩展 | 功能 |
|
||||
|------|------|
|
||||
| `llm` | 大模型对话 |
|
||||
| `agent` | 文档驱动的智能体框架 |
|
||||
| `web` | Web 应用 |
|
||||
| `quantum` | 量子电路模拟 |
|
||||
|
||||
## 12.7 查看库的精确 API
|
||||
|
||||
打开 `lib/` 或 `ext/` 下对应的 `.mq.md` 文件,即可看到精确的 `##` / `#` 名称和参数。例如 `lib/json.mq.md` 顶层就是 `## parse`、`## stringify` 等。
|
||||
|
||||
## 12.8 下一步
|
||||
|
||||
你已经会使用标准库了。继续学习:
|
||||
|
||||
- [第 13 章:命令行工具](./13-命令行工具.md) —— 运行、调试、扩展管理
|
||||
- [第 14 章:网络与 Web 扩展](./14-网络与Web扩展.md) —— `lib/net` 与 `ext/web` 实战
|
||||
@@ -0,0 +1,111 @@
|
||||
# 第 13 章:命令行工具
|
||||
|
||||
Marqdo 提供一组命令行工具,覆盖运行、浏览、调试、发布全流程。
|
||||
|
||||
## 13.1 命令总览
|
||||
|
||||
```text
|
||||
marqdo --version # 查看版本
|
||||
marqdo run 文件.mq.md # 运行程序
|
||||
marqdo view 路径 # 文档浏览器(默认端口 7429)
|
||||
marqdo debug 路径 # 调试界面(默认端口 7430)
|
||||
marqdo catalog 路径 -o 目录 # 生成 OKF 风格清单
|
||||
marqdo sync 路径 -o 目录 # catalog 的别名
|
||||
marqdo ext list # 列出扩展
|
||||
marqdo ext add llm|agent|web|quantum
|
||||
marqdo ext remove llm|agent|web|quantum
|
||||
```
|
||||
|
||||
## 13.2 运行程序:`run`
|
||||
|
||||
```bash
|
||||
marqdo run hello.mq.md
|
||||
```
|
||||
|
||||
指定后端(树遍历默认 / 字节码):
|
||||
|
||||
```bash
|
||||
marqdo run hello.mq.md --backend bytecode
|
||||
```
|
||||
|
||||
### 错误诊断
|
||||
|
||||
诊断信息格式:`path:line:col: message`(行 / 列从 1 开始)。
|
||||
|
||||
```text
|
||||
error: hello.mq.md:5:1: undefined variable `x`
|
||||
```
|
||||
|
||||
根据 `path:line:col` 定位并修复,再重新运行直到退出码为 0。
|
||||
|
||||
## 13.3 文档浏览器:`view`
|
||||
|
||||
`view` 启动一个本地文档浏览器,把 `.mq.md` 渲染成可浏览的文档站:
|
||||
|
||||
```bash
|
||||
marqdo view public --no-open
|
||||
```
|
||||
|
||||
浏览器打开后可看到:
|
||||
|
||||
- Structure(结构)
|
||||
- 函数大纲 / 搜索
|
||||
- Execution(执行)
|
||||
- Variables(变量浮窗)
|
||||
|
||||
## 13.4 调试器:`debug`
|
||||
|
||||
```bash
|
||||
marqdo debug public --no-open
|
||||
```
|
||||
|
||||
提供独立调试页面,支持:
|
||||
|
||||
- 断点
|
||||
- 单步执行
|
||||
- 局部变量查看
|
||||
|
||||
## 13.5 生成清单:`catalog` / `sync`
|
||||
|
||||
从源码派生 OKF 风格的 YAML / Markdown 知识包:
|
||||
|
||||
```bash
|
||||
marqdo catalog public -o .marqdo
|
||||
# 或
|
||||
marqdo sync public -o .marqdo
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
|
||||
| `-o` / `--out` | `.marqdo` | 输出目录 |
|
||||
|
||||
产物:`catalog.yaml`、`index.md`、`modules/*.md` 等。
|
||||
|
||||
## 13.6 扩展管理:`ext`
|
||||
|
||||
```bash
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext remove llm
|
||||
```
|
||||
|
||||
扩展默认安装到 `~/.marqdo/ext`(或 `MARQDO_EXT`)。
|
||||
|
||||
## 13.7 标准库与可执行文件解析
|
||||
|
||||
- **标准库**:内置于二进制;磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。
|
||||
- **库路径解析**:`MARQDO_LIB` → 当前目录 `lib/` → 可执行文件旁 `lib/`。
|
||||
|
||||
## 13.8 下一步
|
||||
|
||||
恭喜!你已经完成了 Marqdo 语法教程。你现在可以:
|
||||
|
||||
- 写出带输入输出、函数、分支、循环的程序
|
||||
- 用表格组织列表、字典、记录
|
||||
- 用对象和方法做面向对象编程
|
||||
- 拆分模块、使用标准库和扩展
|
||||
- 用命令行工具运行、调试、发布
|
||||
|
||||
祝你在「代码即文档」的世界里愉快!
|
||||
@@ -0,0 +1,205 @@
|
||||
# 第 14 章:网络与 Web 扩展
|
||||
|
||||
Marqdo 的网络能力分两层:**标准库 `lib/net`**(HTTP 客户端、cookie / multipart 解析)与**官方扩展 `ext/web`**(网页应用、数据库、表单、登录鉴权、WebSocket)。分层的依据是「代码即文档」的可读性——基础、通用、低依赖的进标准库;领域性强、依赖重、只在 Web 场景才用的进扩展。
|
||||
|
||||
## 14.1 概览
|
||||
|
||||
| 能力 | 位置 | 典型函数 |
|
||||
|------|------|----------|
|
||||
| HTTP(S) 客户端 | `lib/net` | `http_get` / `http_post` / `http_request` |
|
||||
| Cookie 解析 | `lib/net` | `cookie_parse` |
|
||||
| multipart/form-data 解析 | `lib/net` | `multipart_parse` |
|
||||
| 网页应用 / 路由 / 静态 | `ext/web` | `web.page` / `web.app` |
|
||||
| SQLite 数据库 | `ext/web` | `web.db` |
|
||||
| 表单 | `ext/web` | `web.form` |
|
||||
| 登录鉴权(session) | `ext/web` | `web.auth` / `app.auth` |
|
||||
| WebSocket 客户端 / 端点 | `ext/web` | `web.ws` / `app.route_ws` |
|
||||
|
||||
```bash
|
||||
# 运行使用 ext/web 的程序前,先安装扩展
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
## 14.2 HTTP 客户端(`lib/net`)
|
||||
|
||||
导入 `lib/net.mq.md`(中文 `lib/网络.mq.md`),用 `http_get` / `http_post` 发请求:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import net:lib/net.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*resp = > net.http_get url="https://api.example.com/status"*
|
||||
> print text=`resp`[^status]
|
||||
```
|
||||
|
||||
`http_post` 默认以 JSON 提交,可用 `content_type=` / `headers=` 覆盖:
|
||||
|
||||
```markdown
|
||||
*body = > net.http_post url="https://api.example.com/echo" body={"msg":"hi"}*
|
||||
> print text=`body`
|
||||
```
|
||||
|
||||
> **字典操作**:返回值是字典(如 `resp`),直接取元 `resp[^键]`,不要用 `json.get`。
|
||||
|
||||
### Cookie 解析
|
||||
|
||||
`cookie_parse` 把 `Cookie` 请求头或 `Set-Cookie` 响应头解析成列表:
|
||||
|
||||
```markdown
|
||||
*req = > net.cookie_parse text="session=abc123; theme=dark"*
|
||||
> print text=`req`[^1][^name] # session
|
||||
> print text=`req`[^1][^value] # abc123
|
||||
|
||||
*resp = > net.cookie_parse text="id=42; Path=/; HttpOnly; SameSite=Lax" is_response=True*
|
||||
> print text=`resp`[^1][^http_only] # True
|
||||
```
|
||||
|
||||
### multipart 解析
|
||||
|
||||
`multipart_parse` 解析 `multipart/form-data` 正文(给定 `boundary`):
|
||||
|
||||
```markdown
|
||||
*parts = > net.multipart_parse body=`body` boundary="----WebKitFormBoundary"*
|
||||
*field = parts[^1]*
|
||||
> print text=`field`[^name]
|
||||
```
|
||||
|
||||
## 14.3 网页应用(`ext/web`)
|
||||
|
||||
`ext/web` 用类 + 方法装配页面。导入 `web:ext/web/web.mq.md`(中文 `网页:ext/web/网页.mq.md`)。
|
||||
|
||||
### 页面、组件、主体
|
||||
|
||||
```markdown
|
||||
---
|
||||
import web:ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`首页` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`导航` | shell.`顶栏` |
|
||||
|
||||
*page = > web.page title="我的站点" intro="<h1>你好</h1>"*
|
||||
*page = > `page`.compose_components components=`首页`*
|
||||
*html = > `page`.render*
|
||||
> print text=`html`
|
||||
```
|
||||
|
||||
### 应用 + 路由 + 监听
|
||||
|
||||
```markdown
|
||||
*app = > web.app page=`page` host=127.0.0.1 port=18081*
|
||||
*app = > `app`.route path="/about" page=`关于`*
|
||||
> web_listen app=`app`
|
||||
```
|
||||
|
||||
`listen` 提供 `/`、路由页、表单端点 `/_form/{id}`、可选静态目录与 `/admin`。
|
||||
|
||||
### 数据库(SQLite)
|
||||
|
||||
```markdown
|
||||
*store = > web.db url="sqlite:site.db"*
|
||||
> `store`.init name=articles fields=`字段表`
|
||||
> `store`.insert table=articles rows=`数据`
|
||||
*rows = > `store`.select table=articles limit=10*
|
||||
- [行](rows)
|
||||
> print text=`行`[^title]
|
||||
```
|
||||
|
||||
## 14.4 登录鉴权(session / cookie)
|
||||
|
||||
给 `/admin*` 加登录门禁:`app.auth` 挂用户表,未登录重定向到 `/admin/login`。
|
||||
|
||||
```markdown
|
||||
`管理员` =
|
||||
|
||||
| 行 | 用户名 | 密码 |
|
||||
|----|--------|------|
|
||||
| 1 | admin | secret |
|
||||
| 2 | 站长 | pw123 |
|
||||
|
||||
*app = > web.app page=`page` admin=True*
|
||||
*app = > `app`.auth users=`管理员` session_ttl=3600*
|
||||
> web_listen app=`app`
|
||||
```
|
||||
|
||||
`session_ttl` 是会话有效期(秒),过期后重新登录。
|
||||
|
||||
**独立鉴权工具** `web.auth`:登录、校验、登出(不依赖页面),返回 `{ok, session_id, username}`:
|
||||
|
||||
```markdown
|
||||
*auth = > web.auth users=`管理员` session_ttl=3600*
|
||||
*login = > `auth`.login username="admin" password="secret"*
|
||||
1. `login`[^ok]
|
||||
> print text=登录成功:`login`[^username]
|
||||
2. *
|
||||
> print text=登录失败
|
||||
|
||||
*sid = login[^session_id]*
|
||||
*check = > `auth`.check session_id=`sid`*
|
||||
> print text=`check`[^username]
|
||||
|
||||
> `auth`.logout session_id=`sid`
|
||||
```
|
||||
|
||||
## 14.5 WebSocket
|
||||
|
||||
`app.route_ws` 注册端点,`web.ws.connect` 单次请求–响应:
|
||||
|
||||
```markdown
|
||||
*app = > `app`.route_ws path="/live" echo=True*
|
||||
> web_listen app=`app`
|
||||
```
|
||||
|
||||
客户端(另开终端):
|
||||
|
||||
```markdown
|
||||
*ws = > web.ws timeout_sec=30*
|
||||
*echo = > `ws`.connect url="ws://127.0.0.1:18081/live" message="hi"*
|
||||
1. `echo`[^ok]
|
||||
> print text=`echo`[^messages]
|
||||
2. *
|
||||
> print text=连接失败:`echo`[^error]
|
||||
```
|
||||
|
||||
## 14.6 字典操作:用表格与取元,不用 `json.get`/`json.set`
|
||||
|
||||
Marqdo 用 **GFM 表格**构造字典、用 **脚注取元 `变量[^键]`** 读取字典——这是语言原生能力,是「代码即文档」的体现。**不要**用 `json.get` / `json.set` 读写本地字典(那只用于文本 ↔ 结构化的序列化,如 `json.parse` / `json.stringify`)。
|
||||
|
||||
构造字典(横表,≥2 列 + 1 行):
|
||||
|
||||
```markdown
|
||||
`配置` =
|
||||
|
||||
| 主机 | 端口 |
|
||||
|------|------|
|
||||
| 127.0.0.1 | 18081 |
|
||||
```
|
||||
|
||||
读取字典(取元):
|
||||
|
||||
```markdown
|
||||
> print text=`配置`[^主机] # 127.0.0.1
|
||||
> print text=`配置`[^端口] # 18081
|
||||
```
|
||||
|
||||
读取函数返回的字典字段,同样直接取元:
|
||||
|
||||
```markdown
|
||||
*login = > `auth`.login username="admin" password="secret"*
|
||||
> print text=`login`[^ok] # 而不是 json.get value=`login` key="ok"
|
||||
```
|
||||
|
||||
## 14.7 下一步
|
||||
|
||||
你已经掌握 Marqdo 的网络与 Web 能力。继续探索:
|
||||
|
||||
- [第 13 章:命令行工具](./13-命令行工具.md) —— `marqdo ext` 管理扩展
|
||||
- 设计文档:[`doc/design/ext-web-net.md`](../design/ext-web-net.md) —— 本波次网络扩展的完整设计与边界判定
|
||||
@@ -0,0 +1,94 @@
|
||||
# Marqdo 语法教程
|
||||
|
||||
> **代码即文档,文档即代码。** Marqdo 把 Markdown 的标记当作编程语法:同一个 `.mq.md` 文件既是给人读的文稿,也是给机器跑的程序。
|
||||
|
||||
本教程面向所有读者——从没写过代码的文档作者,到熟悉 Python 的工程师。每章都配有可直接运行的完整示例。
|
||||
|
||||
## 目录
|
||||
|
||||
### 第一部分 · 入门
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 1 章:Marqdo 是什么](./01-入门.md) | 理念、安装、第一个程序、运行 | 写出并运行你的第一个 `.mq.md` 程序 |
|
||||
| [第 2 章:基本语法](./02-基本语法.md) | 文件结构、注释、标识符、字面量 | 看懂 `.mq.md` 里哪些是代码、哪些是注释 |
|
||||
|
||||
### 第二部分 · 变量与数据
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 3 章:变量与赋值](./03-变量与赋值.md) | 绑定、变量引用、字符串 | 存取值,拼接文本 |
|
||||
| [第 4 章:输出与输入](./04-输出与输入.md) | `print` / `打印`、`input` / `输入` | 与用户交互 |
|
||||
| [第 5 章:运算符与比较](./05-运算符与比较.md) | 算术、比较、逻辑 | 计算与判断 |
|
||||
|
||||
### 第三部分 · 流程控制
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 6 章:函数](./06-函数.md) | 定义、参数、返回值、函数结束 | 封装可复用逻辑 |
|
||||
| [第 7 章:条件分支](./07-条件分支.md) | `1.` `2.` 分支、else | 让程序根据条件走不同路线 |
|
||||
| [第 8 章:循环](./08-循环.md) | `-` 遍历、`-` while | 重复执行 |
|
||||
|
||||
### 第四部分 · 数据集合
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 9 章:集合(表格)](./09-集合.md) | 列表、字典、记录、脚注取元 | 用 Markdown 表格组织数据 |
|
||||
|
||||
### 第五部分 · 面向对象与模块
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 10 章:对象与方法](./10-对象与方法.md) | `#` 类型、构造、方法、继承 | 面向对象编程 |
|
||||
| [第 11 章:模块与导入](./11-模块与导入.md) | frontmatter、import、库路径、短名 | 组织大型项目 |
|
||||
|
||||
### 第六部分 · 进阶
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 12 章:标准库](./12-标准库.md) | 内置函数、`lib/` 模块 | 直接使用官方能力 |
|
||||
| [第 13 章:命令行工具](./13-命令行工具.md) | `run` / `view` / `debug` / `catalog` | 运行、浏览、调试、发布 |
|
||||
| [第 14 章:网络与 Web 扩展](./14-网络与Web扩展.md) | `lib/net`、`ext/web`、鉴权、WebSocket | 构建 HTTP 客户端与网页应用 |
|
||||
|
||||
---
|
||||
|
||||
## 快速示例
|
||||
|
||||
一个完整的 Marqdo 程序长这样:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello, `谁`!
|
||||
|
||||
---
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
- `# main` —— 入口
|
||||
- `> 问候 谁=World` —— 调用函数(具名参数)
|
||||
- `## 问候` + `+ `谁`` —— 定义函数及其参数
|
||||
- `> print text=…` —— 输出(副作用,是普通函数)
|
||||
- `**n + 1**` —— 返回值
|
||||
- 单独一行 `---` —— 结束函数体
|
||||
|
||||
---
|
||||
|
||||
## 运行方式
|
||||
|
||||
```bash
|
||||
marqdo run 文件.mq.md
|
||||
```
|
||||
|
||||
更多运行、浏览、调试、发布方式见 [第 13 章](./13-命令行工具.md)。
|
||||
|
||||
> **提示**:语法宪法与精确定义见 [`doc/design/markdown-mapping.md`](../design/markdown-mapping.md);本教程是它的通俗讲解版。
|
||||
@@ -1,15 +0,0 @@
|
||||
# Marqdo examples(金样例)
|
||||
|
||||
本目录即测试夹具,见 [doc/design/examples-and-tests.md](../doc/design/examples-and-tests.md)。
|
||||
|
||||
| 目录 | 内容 |
|
||||
|------|------|
|
||||
| [`structure/`](structure/) | 函数、调用、分支、循环、表、导入、位置实参 |
|
||||
| [`keywords/`](keywords/) | `print`、布尔与 `and`/`or`/`not` |
|
||||
| [`errors/`](errors/) | 期望失败(未定义名 / 未知函数 / 实参 / 语法) |
|
||||
|
||||
```bash
|
||||
cargo test
|
||||
marqdo run examples/structure/hello.mq.md
|
||||
marqdo view examples
|
||||
```
|
||||
@@ -0,0 +1,50 @@
|
||||
# examples/marqdo-blog
|
||||
|
||||
一个用 Marqdo 的 `ext/web` 网络扩展库搭建的博客系统示例:美观大气的现代化主题、
|
||||
SQLite 驱动的文章/标签、动态路由、WebSocket 实时终端、以及受会话门禁保护的后台 CRUD。
|
||||
|
||||
## 运行
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_web
|
||||
cargo run -- examples/marqdo-blog/index.mq.md
|
||||
```
|
||||
|
||||
打开 http://127.0.0.1:18085/:
|
||||
|
||||
- `/` — 首页:文章卡片网格 + 实时 WebSocket 终端
|
||||
- `/post/{slug}` — 动态路由渲染单篇文章(标题/日期/标签/正文)
|
||||
- `/tags` — 标签归档;`/tag/{slug}` 查看某标签下的文章
|
||||
- `/about` — 关于页
|
||||
- `/admin` — 会话门禁后台,登录 `admin` / `marqdo`,可增删改文章与标签
|
||||
- `/live` — WebSocket 回显端点
|
||||
- `/static/*` — 静态资源(`public/` 下的 `live.js`)
|
||||
|
||||
## 设计亮点(文档即代码)
|
||||
|
||||
- **样式即数据表格,装配即函数**(`styles/theme.mq.md`):
|
||||
主题不再是一大段手写 CSS 字符串,而是由一张张 GFM 样式表组成 ——
|
||||
`|选择器|属性|值|` 规则行(同一选择器多行自动合并成一条规则),
|
||||
响应式用 `|媒体|选择器|属性|值|` 分组进 `@media` 块。
|
||||
每个 `## 段`(基础/顶栏/侧栏/主体/卡片/页脚/表单/响应式)导出一张样式表,
|
||||
`## 全局` 用 `网页.样式装配` 函数把每张表装配成 CSS 文本,再 `text.str_join` 拼成完整样式表,
|
||||
最后经 `页面.样式` 注入页面。样式保持可读的数据表格,不写胶水代码。
|
||||
- **页面 = 组件装配 + 主体绑定**(`index.mq.md`):
|
||||
导航/侧栏/页脚用 `|组件|样式|` 表装配,文章列表用 `|属性|值|` 绑定 SQLite 字段。
|
||||
- **动态路由**:`/post/{slug}` 的 `slug` 注入查询条件,`页面.详情` 把首行渲染成文章。
|
||||
- **数据模型**(`db/`):`schema.mq.md` 定义 `posts`/`tags`/`post_tags` 三张表,
|
||||
`seed.mq.md` 提供种子数据,`index.mq.md` 幂等建表 + 灌数据。
|
||||
|
||||
## 冒烟测试
|
||||
|
||||
服务器启动后(端口 18085),运行:
|
||||
|
||||
```bash
|
||||
bash examples/marqdo-blog/smoke.sh
|
||||
```
|
||||
|
||||
覆盖:首页/卡片/主题 CSS/媒体查询、静态资源、动态路由详情、标签归档、鉴权门禁、
|
||||
登录会话、后台表单、WebSocket 回显。全部通过时输出 `通过 N / N`。
|
||||
|
||||
可从仓库根目录或本目录运行:相对 `static_dir`(`public`)与相对数据库路径
|
||||
(`data/marqdo-blog.db`)都按**入口脚本所在目录**解析,不依赖终端工作目录。
|
||||
@@ -0,0 +1,13 @@
|
||||
## 页脚
|
||||
|
||||
站点页脚。放版权与概览链接。
|
||||
|
||||
`页脚` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| © 2026 Marqdo 博客 | / | |
|
||||
| 关于 | /about | |
|
||||
| 后台 | /admin | |
|
||||
|
||||
**`页脚`**
|
||||
@@ -0,0 +1,15 @@
|
||||
## 导航
|
||||
|
||||
站点顶部导航。首项是站点名(渐变 Logo 由主题 CSS 处理),`后台` 指向需要登录的 `/admin`。
|
||||
|
||||
`导航` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Marqdo 博客 | / | |
|
||||
| 首页 | / | |
|
||||
| 标签 | /tags | |
|
||||
| 关于 | /about | |
|
||||
| 后台 | /admin | |
|
||||
|
||||
**`导航`**
|
||||
@@ -0,0 +1,15 @@
|
||||
## 侧栏
|
||||
|
||||
右侧归档面板:文章入口、标签、实时小部件。
|
||||
|
||||
`侧栏` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 全部文章 | / | |
|
||||
| 标签归档 | /tags | |
|
||||
| 关于本站 | /about | |
|
||||
| 发布文章 | /admin/new | |
|
||||
| 实时终端 | /#live | |
|
||||
|
||||
**`侧栏`**
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: db/index
|
||||
description: 打开 sqlite、建三张表、幂等种子。
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import schema:schema.mq.md
|
||||
import seed:seed.mq.md
|
||||
---
|
||||
|
||||
## 打开
|
||||
|
||||
*store = > 网页.数据库 地址="sqlite:data/marqdo-blog.db"*
|
||||
*字段 = > schema.posts*
|
||||
*标签字段 = > schema.tags*
|
||||
*关联字段 = > schema.post_tags*
|
||||
> `store`.初始化 名=posts 字段=`字段`
|
||||
> `store`.初始化 名=tags 字段=`标签字段`
|
||||
> `store`.初始化 名=post_tags 字段=`关联字段`
|
||||
*行 = > store.查询 表="posts" 上限=1*
|
||||
1. `行`
|
||||
**store**
|
||||
2. *
|
||||
*文章 = > seed.posts*
|
||||
*标签 = > seed.tags*
|
||||
*关联 = > seed.post_tags*
|
||||
> `store`.插入 表=posts 行=`文章`
|
||||
> `store`.插入 表=tags 行=`标签`
|
||||
> `store`.插入 表=post_tags 行=`关联`
|
||||
**store**
|
||||
@@ -0,0 +1,46 @@
|
||||
## posts
|
||||
|
||||
文章主表结构。`slug` 用于详情页 `/post/{slug}` 的动态路由;`content` 存 Markdown 正文;`tag` 是主标签(tags 表 slug)。
|
||||
|
||||
`schema` =
|
||||
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | integer | false |
|
||||
| title | text | false |
|
||||
| slug | text | false |
|
||||
| summary | text | true |
|
||||
| content | text | true |
|
||||
| tag | text | true |
|
||||
| created_at | text | true |
|
||||
| updated_at | text | true |
|
||||
|
||||
**`schema`**
|
||||
|
||||
## tags
|
||||
|
||||
标签表结构。
|
||||
|
||||
`tags` =
|
||||
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | integer | false |
|
||||
| name | text | false |
|
||||
| slug | text | false |
|
||||
|
||||
**`tags`**
|
||||
|
||||
## post_tags
|
||||
|
||||
文章-标签关联表结构。
|
||||
|
||||
`post_tags` =
|
||||
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | integer | false |
|
||||
| post_id | integer | false |
|
||||
| tag_id | integer | false |
|
||||
|
||||
**`post_tags`**
|
||||
@@ -0,0 +1,53 @@
|
||||
## posts
|
||||
|
||||
种子文章。首页与详情页的初始数据。created_at 用于按时间倒序展示;tag 是主标签 slug。
|
||||
|
||||
`posts` =
|
||||
|
||||
| 行 | title | slug | summary | content | tag | created_at | updated_at |
|
||||
|----|-------|------|---------|---------|-----|------------|------------|
|
||||
| 1 | 你好,Marqdo 博客 | hello-marqdo | 用 Marqdo 的 web 扩展库搭建的第一个博客。表格即组件、文档即代码。 | 这是一篇介绍博客系统的文章。它由 Marqdo 脚本在启动时写入 SQLite,通过 ext/web 的组件装配渲染成页面。 | marqdo | 2026-08-01 | 2026-08-02 |
|
||||
| 2 | 动态路由与文章详情 | dynamic-routing | 如何用 /post/{slug} 动态路由渲染单篇文章。 | 本文说明动态路由机制:作者面注册带 {slug} 占位符的路由,请求时把路径参数注入页面查询条件。 | web | 2026-08-05 | 2026-08-05 |
|
||||
| 3 | 用 GFM 表格表达数据 | gfm-tables | Marqdo 的字典操作不依赖 json 库,GFM 表格即可完成。 | 表格即数据、表格即组件。这篇文章展示如何在 .mq.md 里用横向表写种子数据,用脚注索引读取字段。 | tutorial | 2026-08-10 | 2026-08-11 |
|
||||
| 4 | WebSocket 实时小部件 | websocket-live | 给博客加一个实时回显的 WebSocket 端点。 | 通过 app.路由实时 注册 /live 端点,配合 public/live.js 在首页显示实时连接状态。 | realtime | 2026-08-15 | 2026-08-15 |
|
||||
| 5 | 会话与登录鉴权 | session-auth | 后台用 session 门禁保护,只有登录用户能发布文章。 | 用 app.鉴权 配置管理员用户表,/admin 下的 CRUD 页面都需要有效会话。 | web | 2026-08-18 | 2026-08-20 |
|
||||
| 6 | 数据库与 CRUD | database-crud | 博客的文章、标签、关联全部由 SQLite 支撑。 | db.初始化 建表、db.插入 写种子、后台表单增删改。文章与标签通过 post_tags 关联。 | database | 2026-08-20 | 2026-08-21 |
|
||||
|
||||
**`posts`**
|
||||
|
||||
## tags
|
||||
|
||||
种子标签。
|
||||
|
||||
`tags` =
|
||||
|
||||
| 行 | name | slug |
|
||||
|----|------|------|
|
||||
| 1 | Marqdo | marqdo |
|
||||
| 2 | Web | web |
|
||||
| 3 | 教程 | tutorial |
|
||||
| 4 | 数据库 | database |
|
||||
| 5 | 实时 | realtime |
|
||||
|
||||
**`tags`**
|
||||
|
||||
## post_tags
|
||||
|
||||
种子文章-标签关联。
|
||||
|
||||
`post_tags` =
|
||||
|
||||
| 行 | post_id | tag_id |
|
||||
|----|---------|--------|
|
||||
| 1 | 1 | 1 |
|
||||
| 2 | 1 | 2 |
|
||||
| 3 | 2 | 2 |
|
||||
| 4 | 3 | 1 |
|
||||
| 5 | 3 | 3 |
|
||||
| 6 | 4 | 5 |
|
||||
| 7 | 4 | 2 |
|
||||
| 8 | 5 | 2 |
|
||||
| 9 | 6 | 4 |
|
||||
| 10 | 6 | 1 |
|
||||
|
||||
**`post_tags`**
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: Marqdo 博客
|
||||
description: 用 web 扩展库搭建的博客系统示例:首页列表、动态文章详情、标签归档、登录门禁后台。
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import theme:styles/theme.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import side:components/side.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import db:db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`首页` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`导航` | |
|
||||
| side.`侧栏` | |
|
||||
| foot.`页脚` | |
|
||||
|
||||
`列表` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| title | posts.title | |
|
||||
| body | posts.summary | |
|
||||
| meta | posts.created_at | |
|
||||
| tag | posts.tag | |
|
||||
| href | posts.slug | |
|
||||
|
||||
`详情绑定` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| title | posts.title | |
|
||||
| meta | posts.created_at | |
|
||||
| tag | posts.tag | |
|
||||
| body | posts.content | |
|
||||
|
||||
`标签列表` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| title | tags.name | |
|
||||
| meta | 点击查看该标签下的文章 | |
|
||||
| href | tags.slug | |
|
||||
|
||||
`文章条件` =
|
||||
|
||||
| 字段 | 操作 | 值 |
|
||||
|------|------|-----|
|
||||
| slug | = | {slug} |
|
||||
|
||||
`标签条件` =
|
||||
|
||||
| 字段 | 操作 | 值 |
|
||||
|------|------|-----|
|
||||
| tag | = | {slug} |
|
||||
|
||||
`管理员` =
|
||||
|
||||
| 行 | 用户名 | 密码 |
|
||||
|----|--------|------|
|
||||
| 1 | admin | marqdo |
|
||||
|
||||
*store = > db.打开*
|
||||
|
||||
*首页CSS = > theme.全局*
|
||||
|
||||
*page = > 网页.页面 标题="Marqdo 博客" 引言="<h1>Marqdo 博客</h1><p>用 web 扩展库搭建的博客:表格装配页面、SQLite 数据、动态路由、实时终端。</p><h2 id=\"live\">实时终端</h2><p id=\"live-status\" class=\"live-pill\">connecting…</p><input id=\"live-msg\" placeholder=\"输入一条消息…\"><button id=\"live-send\" disabled>发送</button><div id=\"live-out\"></div><script src=\"/static/live.js\"></script>"*
|
||||
*page = > page.组件装配 组件=`首页`*
|
||||
*page = > page.主体装配 主体=`列表`*
|
||||
*page = > page.排序 排序="-created_at"*
|
||||
*page = > page.样式 样式=`首页CSS`*
|
||||
|
||||
*about = > 网页.页面 标题="关于" 引言="<h1>关于本站</h1><p>一个用 Marqdo 的 web 扩展库(ext/web)写成的博客系统。</p><p>它演示了:GFM 表格装配导航与侧栏、SQLite 驱动的主体绑定、动态路由 /post/{slug}、标签归档、以及受 session 保护的后台 CRUD。</p>"*
|
||||
*about = > about.组件装配 组件=`首页`*
|
||||
*about = > about.样式 样式=`首页CSS`*
|
||||
|
||||
*post = > 网页.页面 标题="文章"*
|
||||
*post = > post.组件装配 组件=`首页`*
|
||||
*post = > post.主体装配 主体=`详情绑定`*
|
||||
*post = > post.查询条件 条件=`文章条件`*
|
||||
*post = > post.详情 详情=True*
|
||||
*post = > post.样式 样式=`首页CSS`*
|
||||
|
||||
*tags = > 网页.页面 标题="标签归档" 引言="<h1>标签归档</h1><p>点击标签查看该主题下的文章。</p>"*
|
||||
*tags = > tags.组件装配 组件=`首页`*
|
||||
*tags = > tags.主体装配 主体=`标签列表`*
|
||||
*tags = > tags.链接前缀 前缀="/tag/"*
|
||||
*tags = > tags.样式 样式=`首页CSS`*
|
||||
|
||||
*tagged = > 网页.页面 标题="标签"*
|
||||
*tagged = > tagged.组件装配 组件=`首页`*
|
||||
*tagged = > tagged.主体装配 主体=`列表`*
|
||||
*tagged = > tagged.查询条件 条件=`标签条件`*
|
||||
*tagged = > tagged.排序 排序="-created_at"*
|
||||
*tagged = > tagged.样式 样式=`首页CSS`*
|
||||
|
||||
*app = > 网页.应用 页面=page 数据库=store 后台=True 主机="127.0.0.1" 端口=18085*
|
||||
*app = > app.路由 路径="/about" 页面=about*
|
||||
*app = > app.路由 路径="/post/{slug}" 页面=post*
|
||||
*app = > app.路由 路径="/tags" 页面=tags*
|
||||
*app = > app.路由 路径="/tag/{slug}" 页面=tagged*
|
||||
*app = > app.静态 目录="public" 挂载="/static"*
|
||||
*app = > app.路由实时 路径="/live" 回显=True*
|
||||
*app = > app.鉴权 用户表=`管理员` 会话时长=3600*
|
||||
> `app`.监听
|
||||
@@ -0,0 +1,40 @@
|
||||
// 实时 WebSocket 小部件(连接 /live 端点)。
|
||||
// 连接 ws://host/live,发送输入,展示服务器回显。
|
||||
(function () {
|
||||
var out = document.getElementById("live-out");
|
||||
var input = document.getElementById("live-msg");
|
||||
var btn = document.getElementById("live-send");
|
||||
var status = document.getElementById("live-status");
|
||||
if (!out || !input || !btn || !status) return;
|
||||
|
||||
var proto = location.protocol === "https:" ? "wss" : "ws";
|
||||
var ws = new WebSocket(proto + "://" + location.host + "/live");
|
||||
status.textContent = "connecting…";
|
||||
|
||||
ws.onopen = function () {
|
||||
status.textContent = "connected";
|
||||
btn.disabled = false;
|
||||
};
|
||||
ws.onmessage = function (ev) {
|
||||
var p = document.createElement("p");
|
||||
p.textContent = "echo: " + ev.data;
|
||||
out.appendChild(p);
|
||||
out.scrollTop = out.scrollHeight;
|
||||
};
|
||||
ws.onclose = function () {
|
||||
status.textContent = "closed";
|
||||
btn.disabled = true;
|
||||
};
|
||||
ws.onerror = function () {
|
||||
status.textContent = "error";
|
||||
btn.disabled = true;
|
||||
};
|
||||
|
||||
btn.onclick = function () {
|
||||
var m = input.value.trim();
|
||||
if (m) ws.send(m);
|
||||
};
|
||||
input.addEventListener("keydown", function (e) {
|
||||
if (e.key === "Enter") btn.onclick();
|
||||
});
|
||||
})();
|
||||
Executable
+68
@@ -0,0 +1,68 @@
|
||||
#!/usr/bin/env bash
|
||||
# 冒烟测试:marqdo-blog 全功能验证。
|
||||
# 用法:bash examples/marqdo-blog/smoke.sh
|
||||
set -uo pipefail
|
||||
BASE="http://127.0.0.1:18085"
|
||||
PASS=0; FAIL=0
|
||||
ok() { echo " ok: $1"; PASS=$((PASS+1)); }
|
||||
bad() { echo " FAIL: $1"; FAIL=$((FAIL+1)); }
|
||||
|
||||
echo "== 首页 =="
|
||||
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/")
|
||||
[ "$code" = "200" ] && ok "GET / -> $code" || bad "GET / -> $code"
|
||||
curl -s "$BASE/" | grep -q '<title>Marqdo 博客</title>' && ok "title" || bad "title"
|
||||
curl -s "$BASE/" | grep -q 'class="card"' && ok "卡片渲染" || bad "卡片缺失"
|
||||
curl -s "$BASE/" | grep -q 'aside.side' && ok "主题 CSS 注入" || bad "主题 CSS 缺失"
|
||||
curl -s "$BASE/" | grep -q '@media (max-width: 860px)' && ok "响应式媒体查询" || bad "媒体查询缺失"
|
||||
|
||||
echo "== 静态 =="
|
||||
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/static/live.js")
|
||||
[ "$code" = "200" ] && ok "GET /static/live.js -> $code" || bad "static -> $code"
|
||||
|
||||
echo "== 动态路由 =="
|
||||
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/post/hello-marqdo")
|
||||
[ "$code" = "200" ] && ok "GET /post/hello-marqdo -> $code" || bad "post detail -> $code"
|
||||
curl -s "$BASE/post/hello-marqdo" | grep -q 'article-title' && ok "文章详情渲染" || bad "文章详情缺失"
|
||||
|
||||
echo "== 标签 =="
|
||||
curl -s "$BASE/tags" | grep -q 'href="/tag/marqdo"' && ok "标签归档链接" || bad "标签链接缺失"
|
||||
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/tag/web")
|
||||
[ "$code" = "200" ] && ok "GET /tag/web -> $code" || bad "tag page -> $code"
|
||||
|
||||
echo "== 鉴权门禁 =="
|
||||
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/admin")
|
||||
[ "$code" = "303" ] && ok "未登录 /admin -> $code (重定向登录)" || bad "未登录 /admin -> $code"
|
||||
|
||||
echo "== 登录 =="
|
||||
rm -f /tmp/mq_smoke_cookies.txt /tmp/mq_smoke_headers.txt
|
||||
curl -s -D /tmp/mq_smoke_headers.txt -o /dev/null -d "username=admin&password=marqdo" "$BASE/admin/login"
|
||||
sid=$(grep -i "set-cookie" /tmp/mq_smoke_headers.txt | sed 's/.*marqdo_sid=\([^;]*\).*/\1/')
|
||||
[ -n "$sid" ] && ok "登录获取会话 cookie" || bad "登录未返回 cookie"
|
||||
code=$(curl -s -b "marqdo_sid=$sid" -o /dev/null -w "%{http_code}" "$BASE/admin")
|
||||
[ "$code" = "200" ] && ok "带会话访问 /admin -> $code" || bad "带会话 /admin -> $code"
|
||||
|
||||
echo "== 发布文章 (CRUD) =="
|
||||
code=$(curl -s -b "marqdo_sid=$sid" -o /dev/null -w "%{http_code}" "$BASE/admin/posts/new")
|
||||
[ "$code" = "200" ] && ok "GET /admin/posts/new -> $code" || bad "new form -> $code"
|
||||
|
||||
echo "== WebSocket =="
|
||||
wsok=$(python3 -c "
|
||||
import socket, base64, os
|
||||
s = socket.create_connection(('127.0.0.1', 18085), timeout=3)
|
||||
key = base64.b64encode(os.urandom(16)).decode()
|
||||
s.sendall((f'GET /live HTTP/1.1\r\nHost: x\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Key: {key}\r\nSec-WebSocket-Version: 13\r\n\r\n').encode())
|
||||
r = s.recv(1024).decode(errors='replace')
|
||||
if '101' not in r.split('\r\n')[0]:
|
||||
print('NO'); s.close(); raise SystemExit
|
||||
mask = os.urandom(4); payload = b'ping'
|
||||
m = bytes(b ^ mask[i%4] for i, b in enumerate(payload))
|
||||
s.sendall(bytes([0x81, 0x80|len(payload)]) + mask + m)
|
||||
d = s.recv(1024)
|
||||
print('OK' if b'ping' in d else 'NO')
|
||||
s.close()
|
||||
" 2>/dev/null)
|
||||
[ "$wsok" = "OK" ] && ok "WebSocket /live 回显" || bad "WebSocket 回显 $wsok"
|
||||
|
||||
echo
|
||||
echo "通过 $PASS / $((PASS+FAIL))"
|
||||
[ "$FAIL" = "0" ] || exit 1
|
||||
@@ -0,0 +1,405 @@
|
||||
---
|
||||
title: styles/theme
|
||||
description: 博客主题:样式即数据表格,装配即函数。
|
||||
import 网页:ext/web/网页.mq.md
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
博客主题的样式即数据表格:每个 `## 段` 导出一张 GFM 样式表(`|选择器|属性|值|`,
|
||||
或用 `|媒体|选择器|属性|值|` 表达响应式),`## 全局` 用 `样式装配` 函数把它们
|
||||
装配成一份完整 CSS。这符合 文档即代码 —— 样式是可读的表格,装配是显式调用。
|
||||
|
||||
## 基础
|
||||
|
||||
配色与字体变量、页面骨架。衬线标题 + 无衬线正文,暖白纸感背景。
|
||||
|
||||
`基础` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| :root | --ink | #1c1917 |
|
||||
| :root | --ink-soft | #44403c |
|
||||
| :root | --muted | #78716c |
|
||||
| :root | --faint | #a8a29e |
|
||||
| :root | --paper | #f7f5f2 |
|
||||
| :root | --card | #ffffff |
|
||||
| :root | --line | #e7e5e4 |
|
||||
| :root | --accent | #4f46e5 |
|
||||
| :root | --accent-2 | #7c3aed |
|
||||
| :root | --accent-ink | #ffffff |
|
||||
| :root | --radius | 16px |
|
||||
| :root | --shadow | 0 1px 2px rgba(28,25,23,.05), 0 8px 24px rgba(28,25,23,.06) |
|
||||
| :root | --shadow-lg | 0 4px 12px rgba(28,25,23,.08), 0 20px 48px rgba(28,25,23,.12) |
|
||||
| :root | --serif | "Noto Serif SC", Georgia, "Songti SC", serif |
|
||||
| :root | --sans | "Noto Sans SC", "IBM Plex Sans", system-ui, -apple-system, sans-serif |
|
||||
| html | scroll-behavior | smooth |
|
||||
| * | box-sizing | border-box |
|
||||
| ::selection | background | rgba(79,70,229,.18) |
|
||||
| body | margin | 0 |
|
||||
| body | font-family | var(--sans) |
|
||||
| body | background | var(--paper) |
|
||||
| body | color | var(--ink) |
|
||||
| body | display | grid |
|
||||
| body | min-height | 100vh |
|
||||
| body | line-height | 1.7 |
|
||||
| body | grid-template-rows | auto 1fr auto |
|
||||
| body.has-sidebar | grid-template-columns | 15rem 1fr |
|
||||
| body.has-sidebar | grid-template-areas | "top top" "side main" "foot foot" |
|
||||
| body.no-sidebar | grid-template-areas | "top" "main" "foot" |
|
||||
|
||||
**`基础`**
|
||||
|
||||
## 顶栏
|
||||
|
||||
吸顶导航:磨砂玻璃 + 细分隔线,Logo 处用渐变强调。
|
||||
|
||||
`顶栏` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| header.topnav | grid-area | top |
|
||||
| header.topnav | position | sticky |
|
||||
| header.topnav | top | 0 |
|
||||
| header.topnav | z-index | 20 |
|
||||
| header.topnav | background | rgba(255,255,255,.82) |
|
||||
| header.topnav | backdrop-filter | blur(10px) |
|
||||
| header.topnav | -webkit-backdrop-filter | blur(10px) |
|
||||
| header.topnav | border-bottom | 1px solid var(--line) |
|
||||
| header.topnav | padding | .9rem 2rem |
|
||||
| header.topnav | display | flex |
|
||||
| header.topnav | align-items | center |
|
||||
| header.topnav | justify-content | space-between |
|
||||
| ul.nav | list-style | none |
|
||||
| ul.nav | margin | 0 |
|
||||
| ul.nav | padding | 0 |
|
||||
| ul.nav | display | flex |
|
||||
| ul.nav | align-items | center |
|
||||
| ul.nav | gap | .35rem |
|
||||
| ul.nav li | margin | 0 |
|
||||
| ul.nav a | display | inline-block |
|
||||
| ul.nav a | padding | .45rem .9rem |
|
||||
| ul.nav a | border-radius | 999px |
|
||||
| ul.nav a | color | var(--ink-soft) |
|
||||
| ul.nav a | font-weight | 500 |
|
||||
| ul.nav a | text-decoration | none |
|
||||
| ul.nav a | transition | background .18s ease, color .18s ease |
|
||||
| ul.nav a:hover | background | rgba(79,70,229,.1) |
|
||||
| ul.nav a:hover | color | var(--accent) |
|
||||
| ul.nav li:first-child a | font-family | var(--serif) |
|
||||
| ul.nav li:first-child a | font-size | 1.25rem |
|
||||
| ul.nav li:first-child a | font-weight | 700 |
|
||||
| ul.nav li:first-child a | background | linear-gradient(120deg, var(--accent), var(--accent-2)) |
|
||||
| ul.nav li:first-child a | -webkit-background-clip | text |
|
||||
| ul.nav li:first-child a | background-clip | text |
|
||||
| ul.nav li:first-child a | -webkit-text-fill-color | transparent |
|
||||
| ul.nav li:first-child a | color | transparent |
|
||||
| ul.nav li:first-child a | padding-left | .2rem |
|
||||
| ul.nav li:first-child a | padding-right | .2rem |
|
||||
|
||||
**`顶栏`**
|
||||
|
||||
## 侧栏
|
||||
|
||||
归档面板:浅底圆角卡片,链接胶囊化。
|
||||
|
||||
`侧栏` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| aside.side | grid-area | side |
|
||||
| aside.side | padding | 2rem 1.25rem |
|
||||
| aside.side | border-right | 1px solid var(--line) |
|
||||
| aside.side | background | linear-gradient(180deg, #fbfaf8, #f3f1ec) |
|
||||
| ul.side-nav | list-style | none |
|
||||
| ul.side-nav | margin | 0 |
|
||||
| ul.side-nav | padding | 0 |
|
||||
| ul.side-nav | display | flex |
|
||||
| ul.side-nav | flex-direction | column |
|
||||
| ul.side-nav | gap | .25rem |
|
||||
| ul.side-nav li | margin | 0 |
|
||||
| ul.side-nav a | display | block |
|
||||
| ul.side-nav a | padding | .55rem .85rem |
|
||||
| ul.side-nav a | border-radius | 10px |
|
||||
| ul.side-nav a | color | var(--ink-soft) |
|
||||
| ul.side-nav a | text-decoration | none |
|
||||
| ul.side-nav a | font-weight | 500 |
|
||||
| ul.side-nav a | transition | background .15s ease, transform .15s ease, color .15s ease |
|
||||
| ul.side-nav a:hover | background | #fff |
|
||||
| ul.side-nav a:hover | color | var(--accent) |
|
||||
| ul.side-nav a:hover | transform | translateX(4px) |
|
||||
| ul.side-nav a:hover | box-shadow | 0 1px 3px rgba(28,25,23,.08) |
|
||||
|
||||
**`侧栏`**
|
||||
|
||||
## 主体
|
||||
|
||||
内容区留白与节奏。
|
||||
|
||||
`主体` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| main.main | grid-area | main |
|
||||
| main.main | padding | 2.5rem 2.5rem 3.5rem |
|
||||
| main.main | max-width | 76rem |
|
||||
| main.main | width | 100% |
|
||||
| .main-intro | margin-bottom | .5rem |
|
||||
| .main-intro h1 | font-family | var(--serif) |
|
||||
| .main-intro h1 | margin | 0 0 .5rem |
|
||||
| .main-intro h1 | font-size | clamp(2rem, 5vw, 2.9rem) |
|
||||
| .main-intro h1 | line-height | 1.2 |
|
||||
| .main-intro h1 | font-weight | 700 |
|
||||
| .main-intro h1 | letter-spacing | -.01em |
|
||||
| .main-intro p | color | var(--muted) |
|
||||
| .main-intro p | margin | 0 |
|
||||
| .main-intro p | font-size | 1.05rem |
|
||||
|
||||
**`主体`**
|
||||
|
||||
## 卡片
|
||||
|
||||
文章卡片:白底大圆角、柔和阴影、hover 抬升,整卡可点。
|
||||
|
||||
`卡片` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| .content.cards | display | grid |
|
||||
| .content.cards | gap | 1.5rem |
|
||||
| .content.cards | margin-top | 2rem |
|
||||
| .content.cards | grid-template-columns | repeat(auto-fill, minmax(17rem, 1fr)) |
|
||||
| .content.cards article.card | background | var(--card) |
|
||||
| .content.cards article.card | border | 1px solid var(--line) |
|
||||
| .content.cards article.card | border-radius | var(--radius) |
|
||||
| .content.cards article.card | padding | 1.6rem 1.7rem |
|
||||
| .content.cards article.card | box-shadow | var(--shadow) |
|
||||
| .content.cards article.card | transition | transform .22s ease, box-shadow .22s ease, border-color .22s ease |
|
||||
| .content.cards article.card | display | flex |
|
||||
| .content.cards article.card | flex-direction | column |
|
||||
| .content.cards article.card | gap | .55rem |
|
||||
| .content.cards article.card:hover | transform | translateY(-6px) |
|
||||
| .content.cards article.card:hover | box-shadow | var(--shadow-lg) |
|
||||
| .content.cards article.card:hover | border-color | rgba(79,70,229,.35) |
|
||||
| .content.cards a.card-link | text-decoration | none |
|
||||
| .content.cards a.card-link | color | inherit |
|
||||
| .content.cards a.card-link | display | flex |
|
||||
| .content.cards a.card-link | flex-direction | column |
|
||||
| .content.cards a.card-link | gap | .55rem |
|
||||
| .content.cards a.card-link | height | 100% |
|
||||
| .content.cards a.card-link:hover | color | inherit |
|
||||
| .content.cards h2 | font-family | var(--serif) |
|
||||
| .content.cards h2 | margin | 0 |
|
||||
| .content.cards h2 | font-size | 1.35rem |
|
||||
| .content.cards h2 | line-height | 1.35 |
|
||||
| .content.cards h2 | font-weight | 700 |
|
||||
| .content.cards h2 | transition | color .18s ease |
|
||||
| .content.cards a.card-link:hover h2 | color | var(--accent) |
|
||||
| .card-meta | font-size | .82rem |
|
||||
| .card-meta | color | var(--faint) |
|
||||
| .card-meta | letter-spacing | .04em |
|
||||
| .card-meta | text-transform | uppercase |
|
||||
| .card-tag | align-self | flex-start |
|
||||
| .card-tag | font-size | .78rem |
|
||||
| .card-tag | color | var(--accent) |
|
||||
| .card-tag | background | rgba(79,70,229,.08) |
|
||||
| .card-tag | padding | .15rem .65rem |
|
||||
| .card-tag | border-radius | 999px |
|
||||
| .card-tag | font-weight | 600 |
|
||||
| .content.cards p | color | var(--muted) |
|
||||
| .content.cards p | margin | 0 |
|
||||
| .content.cards p | font-size | .95rem |
|
||||
| .content.cards p | flex | 1 |
|
||||
|
||||
**`卡片`**
|
||||
|
||||
## 页脚
|
||||
|
||||
`页脚` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| footer.foot | grid-area | foot |
|
||||
| footer.foot | padding | 1.4rem 2rem |
|
||||
| footer.foot | border-top | 1px solid var(--line) |
|
||||
| footer.foot | color | var(--muted) |
|
||||
| footer.foot | background | #fff |
|
||||
| footer.foot | font-size | .9rem |
|
||||
| footer.foot | display | flex |
|
||||
| footer.foot | justify-content | space-between |
|
||||
| footer.foot | align-items | center |
|
||||
| footer.foot | flex-wrap | wrap |
|
||||
| footer.foot | gap | .5rem |
|
||||
| ul.foot-nav | list-style | none |
|
||||
| ul.foot-nav | margin | 0 |
|
||||
| ul.foot-nav | padding | 0 |
|
||||
| ul.foot-nav | display | flex |
|
||||
| ul.foot-nav | gap | 1rem |
|
||||
| ul.foot-nav | flex-wrap | wrap |
|
||||
| ul.foot-nav li | margin | 0 |
|
||||
| ul.foot-nav a | color | var(--muted) |
|
||||
| ul.foot-nav a | text-decoration | none |
|
||||
| ul.foot-nav a:hover | color | var(--accent) |
|
||||
|
||||
**`页脚`**
|
||||
|
||||
## 表单
|
||||
|
||||
后台表单统一风格。
|
||||
|
||||
`表单` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| .site-form | margin-top | 1.75rem |
|
||||
| .site-form | max-width | 34rem |
|
||||
| .site-form | background | var(--card) |
|
||||
| .site-form | border | 1px solid var(--line) |
|
||||
| .site-form | border-radius | var(--radius) |
|
||||
| .site-form | padding | 1.8rem |
|
||||
| .site-form | box-shadow | var(--shadow) |
|
||||
| .site-form form | display | grid |
|
||||
| .site-form form | gap | 1rem |
|
||||
| .site-form label | display | grid |
|
||||
| .site-form label | gap | .35rem |
|
||||
| .site-form label | font-size | .92rem |
|
||||
| .site-form label | font-weight | 600 |
|
||||
| .site-form label | color | var(--ink-soft) |
|
||||
| .site-form input | padding | .65rem .8rem |
|
||||
| .site-form input | border | 1px solid var(--line) |
|
||||
| .site-form input | border-radius | 10px |
|
||||
| .site-form input | font | inherit |
|
||||
| .site-form input | background | #fdfcfb |
|
||||
| .site-form input | transition | border-color .15s ease, box-shadow .15s ease |
|
||||
| .site-form textarea | padding | .65rem .8rem |
|
||||
| .site-form textarea | border | 1px solid var(--line) |
|
||||
| .site-form textarea | border-radius | 10px |
|
||||
| .site-form textarea | font | inherit |
|
||||
| .site-form textarea | background | #fdfcfb |
|
||||
| .site-form textarea | transition | border-color .15s ease, box-shadow .15s ease |
|
||||
| .site-form select | padding | .65rem .8rem |
|
||||
| .site-form select | border | 1px solid var(--line) |
|
||||
| .site-form select | border-radius | 10px |
|
||||
| .site-form select | font | inherit |
|
||||
| .site-form select | background | #fdfcfb |
|
||||
| .site-form select | transition | border-color .15s ease, box-shadow .15s ease |
|
||||
| .site-form input:focus | outline | none |
|
||||
| .site-form input:focus | border-color | var(--accent) |
|
||||
| .site-form input:focus | box-shadow | 0 0 0 3px rgba(79,70,229,.12) |
|
||||
| .site-form textarea:focus | outline | none |
|
||||
| .site-form textarea:focus | border-color | var(--accent) |
|
||||
| .site-form textarea:focus | box-shadow | 0 0 0 3px rgba(79,70,229,.12) |
|
||||
| .site-form select:focus | outline | none |
|
||||
| .site-form select:focus | border-color | var(--accent) |
|
||||
| .site-form select:focus | box-shadow | 0 0 0 3px rgba(79,70,229,.12) |
|
||||
| .site-form input[readonly] | background | #f5f5f4 |
|
||||
| .site-form input[readonly] | color | var(--muted) |
|
||||
| .site-form textarea | min-height | 10rem |
|
||||
| .site-form textarea | resize | vertical |
|
||||
| .site-form .err | color | #b91c1c |
|
||||
| .site-form .err | font-size | .85rem |
|
||||
| .site-form .actions | display | flex |
|
||||
| .site-form .actions | gap | .75rem |
|
||||
| .site-form .actions | align-items | center |
|
||||
| .site-form .actions | flex-wrap | wrap |
|
||||
| .site-form .actions | padding-top | .25rem |
|
||||
| .site-form button | background | linear-gradient(120deg, var(--accent), var(--accent-2)) |
|
||||
| .site-form button | color | var(--accent-ink) |
|
||||
| .site-form button | border | 0 |
|
||||
| .site-form button | padding | .6rem 1.3rem |
|
||||
| .site-form button | border-radius | 999px |
|
||||
| .site-form button | cursor | pointer |
|
||||
| .site-form button | font-weight | 600 |
|
||||
| .site-form button | font-size | .95rem |
|
||||
| .site-form button | transition | opacity .15s ease, transform .15s ease, box-shadow .15s ease |
|
||||
| .site-form button:hover | opacity | .92 |
|
||||
| .site-form button:hover | transform | translateY(-1px) |
|
||||
| .site-form button:hover | box-shadow | 0 6px 18px rgba(79,70,229,.3) |
|
||||
| .site-form a.btn | display | inline-block |
|
||||
| .site-form a.btn | padding | .6rem 1.3rem |
|
||||
| .site-form a.btn | border-radius | 999px |
|
||||
| .site-form a.btn | border | 1px solid var(--line) |
|
||||
| .site-form a.btn | color | var(--ink-soft) |
|
||||
| .site-form a.btn | text-decoration | none |
|
||||
| .site-form a.btn | font-weight | 500 |
|
||||
| .site-form a.btn | font-size | .95rem |
|
||||
| .site-form .meta | color | var(--muted) |
|
||||
| .site-form .meta | font-size | .9rem |
|
||||
| .site-form .admin-list | margin | 0 |
|
||||
| .site-form .admin-list | padding | 0 |
|
||||
| .site-form .admin-list | list-style | none |
|
||||
| .site-form .admin-list | display | grid |
|
||||
| .site-form .admin-list | gap | .5rem |
|
||||
| .site-form .admin-list li | background | #fdfcfb |
|
||||
| .site-form .admin-list li | border | 1px solid var(--line) |
|
||||
| .site-form .admin-list li | border-radius | 10px |
|
||||
| .site-form .admin-list li | padding | .6rem .9rem |
|
||||
| .site-form .admin-list li | display | flex |
|
||||
| .site-form .admin-list li | justify-content | space-between |
|
||||
| .site-form .admin-list li | align-items | center |
|
||||
| .site-form .admin-list li | gap | 1rem |
|
||||
| .site-form .admin-list a | color | var(--accent) |
|
||||
| .site-form .admin-list a | text-decoration | none |
|
||||
| .site-form .admin-list a | font-size | .9rem |
|
||||
|
||||
**`表单`**
|
||||
|
||||
## 响应式
|
||||
|
||||
窄屏收为单栏,导航换行。
|
||||
|
||||
`响应式` =
|
||||
|
||||
| 媒体 | 选择器 | 属性 | 值 |
|
||||
|------|--------|------|-----|
|
||||
| (max-width: 860px) | body.has-sidebar | grid-template-columns | 1fr |
|
||||
| (max-width: 860px) | body.has-sidebar | grid-template-areas | "top" "main" "side" "foot" |
|
||||
| (max-width: 860px) | aside.side | border-right | 0 |
|
||||
| (max-width: 860px) | aside.side | border-bottom | 1px solid var(--line) |
|
||||
| (max-width: 860px) | aside.side | padding | 1rem 2rem |
|
||||
| (max-width: 860px) | ul.side-nav | flex-direction | row |
|
||||
| (max-width: 860px) | ul.side-nav | flex-wrap | wrap |
|
||||
| (max-width: 860px) | main.main | padding | 1.75rem 1.25rem 2.5rem |
|
||||
| (max-width: 860px) | header.topnav | padding | .75rem 1.25rem |
|
||||
| (max-width: 860px) | footer.foot | padding | 1.2rem 1.25rem |
|
||||
| (max-width: 860px) | .content.cards | grid-template-columns | 1fr |
|
||||
| (max-width: 520px) | ul.nav | flex-wrap | wrap |
|
||||
|
||||
**`响应式`**
|
||||
|
||||
## 全局
|
||||
|
||||
用 样式装配 函数逐个把段落表装配成 CSS,再拼接成完整样式表。
|
||||
|
||||
*基础表 = > 基础*
|
||||
*顶栏表 = > 顶栏*
|
||||
*侧栏表 = > 侧栏*
|
||||
*主体表 = > 主体*
|
||||
*卡片表 = > 卡片*
|
||||
*页脚表 = > 页脚*
|
||||
*表单表 = > 表单*
|
||||
*响应式表 = > 响应式*
|
||||
|
||||
*css基础 = > 网页.样式装配 名="基础" 表=`基础表`*
|
||||
*css顶栏 = > 网页.样式装配 名="顶栏" 表=`顶栏表`*
|
||||
*css侧栏 = > 网页.样式装配 名="侧栏" 表=`侧栏表`*
|
||||
*css主体 = > 网页.样式装配 名="主体" 表=`主体表`*
|
||||
*css卡片 = > 网页.样式装配 名="卡片" 表=`卡片表`*
|
||||
*css页脚 = > 网页.样式装配 名="页脚" 表=`页脚表`*
|
||||
*css表单 = > 网页.样式装配 名="表单" 表=`表单表`*
|
||||
*css响应式 = > 网页.样式装配 名="响应式" 表=`响应式表`*
|
||||
|
||||
`css段` =
|
||||
|
||||
| css |
|
||||
|-----|
|
||||
| `css基础` |
|
||||
| `css顶栏` |
|
||||
| `css侧栏` |
|
||||
| `css主体` |
|
||||
| `css卡片` |
|
||||
| `css页脚` |
|
||||
| `css表单` |
|
||||
| `css响应式` |
|
||||
|
||||
*css = > text.str_join xs=`css段` sep=""*
|
||||
**css**
|
||||
Loaded 100 of 533 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user