Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
db27f5c8d3 | ||
|
|
106e1d5136 | ||
|
|
d269ccb7e7 | ||
|
|
505d478724 | ||
|
|
b842644686 | ||
|
|
60d570756f | ||
|
|
eea6fe1a0e | ||
|
|
25b7be6739 | ||
|
|
91d51f3f0a | ||
|
|
ff6425e6c5 | ||
|
|
e853b00fe2 | ||
|
|
4a7a33e29a | ||
|
|
25b6b86c26 | ||
|
|
e4be0b0492 | ||
|
|
db6158e9e2 | ||
|
|
a0c56fa352 | ||
|
|
c181b74a88 | ||
|
|
02b3dfab48 | ||
|
|
b09538d242 | ||
|
|
0dcd9e3d03 | ||
|
|
897db76aa7 | ||
|
|
ee019fb1c2 | ||
|
|
9599303c4c | ||
|
|
8041a2274c | ||
|
|
ab8ea8438f | ||
|
|
f240bdf156 | ||
|
|
ff84c43c10 | ||
|
|
dbb2765553 | ||
|
|
7e3b193d49 | ||
|
|
2a9fceb51c | ||
|
|
d1ddb74235 | ||
|
|
b6bb42e460 | ||
|
|
5456d9ff83 | ||
|
|
a23fdedfa2 | ||
|
|
3463628165 | ||
|
|
d1b33c78c6 | ||
|
|
fbece725e1 | ||
|
|
1f23e2ed93 | ||
|
|
99132ac8fc | ||
|
|
118448538c | ||
|
|
2e65c055b8 | ||
|
|
3da7b276d3 | ||
|
|
63e5be80ab | ||
|
|
92d88fe761 | ||
|
|
c4ffb9473f | ||
|
|
3a7e11c995 | ||
|
|
b0c777c480 | ||
|
|
b00b018056 | ||
|
|
b974f10c6e | ||
|
|
72777a8c74 | ||
|
|
e08cd839be | ||
|
|
5309848292 | ||
|
|
1271aafcdd |
No files matched your search
@@ -0,0 +1,170 @@
|
||||
---
|
||||
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/*, running marqdo CLI, or when the user mentions Marqdo,
|
||||
mq.md, markup-as-syntax, or code-as-documentation.
|
||||
---
|
||||
|
||||
# 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 (strings need `"…"` / `'…'`; ticks still ok).
|
||||
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
7. **Paths:** In bare *expressions* `/` is division. 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 `> path.mq.md` [`as` / `作为` name] | Import (binds library name) |
|
||||
| Frontmatter `> use lib.member` [`as` name] / `使用` | Bind short name to a library path |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `*…*` | Statement (bind / expr) |
|
||||
| `**…**` | Return value |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` in function body | End function body (no value) |
|
||||
| GFM table after empty RHS bind | Collection (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 bind a **library name** (default = file stem; optional `as` / `作为`). Members are **not** flattened into the caller. Call with a bare dotted path:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: example
|
||||
> lib/text.mq.md
|
||||
> lib/time.mq.md as clock
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`xs` = > 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` / `add agent` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — document-driven agents: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)).
|
||||
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
|
||||
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
|
||||
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
Stdlib map: [reference.md](reference.md).
|
||||
|
||||
## 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` |
|
||||
| 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 文本) |
|
||||
|
||||
## 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
|
||||
- [ ] `marqdo run` succeeds (or errors addressed)
|
||||
@@ -0,0 +1,234 @@
|
||||
# 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
|
||||
> 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
|
||||
> 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
|
||||
---
|
||||
> 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
|
||||
```
|
||||
@@ -0,0 +1,135 @@
|
||||
# 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
|
||||
marqdo ext remove llm|agent
|
||||
```
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
|
||||
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * `` (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`;导入仍写 `> 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`) |
|
||||
|
||||
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
|
||||
|
||||
## Formula + plot (math)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> 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
|
||||
---
|
||||
> 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/view-debug.md` | view / debug hosts |
|
||||
@@ -14,13 +14,34 @@ jobs:
|
||||
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: |
|
||||
@@ -29,17 +50,77 @@ jobs:
|
||||
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"
|
||||
Compress-Archive -Path "dist/$exe" -DestinationPath "dist/$zip" -Force
|
||||
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 — extension libraries
|
||||
- Official **`ext/`** packages: `llm`, `agent`, `web`, `quantum` (not stdlib)
|
||||
- Install: `marqdo ext list` / `marqdo ext add llm|agent|web|quantum`
|
||||
- Native plugins: `cargo build --release -p marqdo_plugin_*` then `ext add`
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-cli.md](https://github.com/cflmy/marqdo/blob/main/doc/design/ext-cli.md)
|
||||
|
||||
Also: embedded stdlib, writeback/subtask, Variables modal in `view`, VSIX from branch **`vscode-extension`**.
|
||||
|
||||
### Downloads
|
||||
|
||||
| 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 }}
|
||||
+31
@@ -1,19 +1,50 @@
|
||||
/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/
|
||||
spike/__pycache__/
|
||||
spike/.pytest_cache/
|
||||
**/__pycache__/
|
||||
*.pyc
|
||||
|
||||
# Local sqlite / scratch
|
||||
/data/
|
||||
/tmp/
|
||||
plugins/*/tmp/
|
||||
# web smoke/example DBs (cwd-relative or fixture data dirs)
|
||||
/web-fixtures/
|
||||
/tests/ext/web-fixtures/data/
|
||||
/examples/web-site/data/
|
||||
/examples/web-site-zh/data/
|
||||
@@ -0,0 +1,80 @@
|
||||
# Changelog
|
||||
|
||||
## v0.2.0 — 2026-08-12
|
||||
|
||||
### Highlights — official extension libraries
|
||||
|
||||
This release centers on **`ext/`**: optional packages that are **not** part of the embedded stdlib. Install them with the CLI; native plugins (`.so` / `.dll`) ship beside L1 Markdown APIs.
|
||||
|
||||
**How to get extensions**
|
||||
|
||||
```bash
|
||||
# List what the installer knows about
|
||||
marqdo ext list
|
||||
|
||||
# Install from the repo's ./ext (or MARQDO_EXT_SOURCE), into ~/.marqdo/ext (or MARQDO_EXT)
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
|
||||
# Chinese ids work the same (大模型 / 智能体 / 网页 / 量子)
|
||||
marqdo ext add 量子
|
||||
|
||||
marqdo ext remove quantum
|
||||
```
|
||||
|
||||
Native plugins (agent / web / quantum) must be built once, then `ext add` copies them into `MARQDO_EXT/native/`:
|
||||
|
||||
```bash
|
||||
cargo build --release -p marqdo_plugin_agent
|
||||
cargo build --release -p marqdo_plugin_web
|
||||
cargo build --release -p marqdo_plugin_quantum
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
Runtime also resolves plugins from `CARGO_TARGET_DIR`, `target/`, next to the `marqdo` binary, or `MARQDO_*_PLUGIN` env vars. Design: [ext-cli.md](doc/design/ext-cli.md) · [ext-abi.md](doc/design/ext-abi.md).
|
||||
|
||||
| Package | What you get |
|
||||
|---------|----------------|
|
||||
| **llm** | OpenAI-compatible chat — [ext-llm.md](doc/design/ext-llm.md) |
|
||||
| **agent** | Agent layout / orchestration helpers + native plugin — [ext-agent.md](doc/design/ext-agent.md) |
|
||||
| **web** | HTTP + SQLite site helpers + native plugin — [ext-web.md](doc/design/ext-web.md) |
|
||||
| **quantum** | State-vector circuits, draw, noise, formula `matrix=` custom gates — [ext-quantum.md](doc/design/ext-quantum.md) |
|
||||
|
||||
User-facing intro: [`public/features/05-extensions.mq.md`](public/features/05-extensions.mq.md) / [`05-扩展.mq.md`](public/features/05-扩展.mq.md).
|
||||
|
||||
### Added
|
||||
- Full **ext CLI** catalog: `llm`, `agent`, `web`, `quantum` (EN/ZH ids).
|
||||
- **Quantum (Q0–Q6)**: gates, `run`/`steps`, draw (circuit/probs/bloch), heatmaps, teaching noise incl. amplitude damping, **custom gates from `$$` / `matrix=`**.
|
||||
- **Web** extension (listen / render / SQLite) with L1 EN/ZH.
|
||||
- **Agent** native plugin path + installer copy into `native/`.
|
||||
- View **Variables** panel: previews + click-to-open rich modal (matrices / KaTeX).
|
||||
- Formula matrix parse (`pmatrix` / `[[…]]`) for executable gate matrices.
|
||||
|
||||
### Changed
|
||||
- Release notes and docs emphasize extensions vs embedded stdlib.
|
||||
- Highlight.js CDN path for view pages; Variables panel script escaping fixed.
|
||||
|
||||
## v0.1.2 — 2026-08-07
|
||||
|
||||
### Added
|
||||
- **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
+914
-24
File diff suppressed because it is too large.
Load diff
+12
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -19,6 +19,17 @@ 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"
|
||||
|
||||
@@ -6,7 +6,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.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) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
|
||||
语法宪法:[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)
|
||||
|
||||
---
|
||||
|
||||
@@ -23,31 +23,44 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.1)
|
||||
## 语法速览(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)。
|
||||
|
||||
---
|
||||
|
||||
## 理念
|
||||
@@ -55,18 +68,48 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
1. **叙述默认安全**(无标记 = 注释)。
|
||||
2. **返回是架构;打印只是函数。**
|
||||
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
|
||||
4. **计划对齐 [OKF](doc/design/generated-yaml-manifest.md) 规范**:依赖与模块清单由工具生成(`marqdo catalog` / `sync`),不是手填配置——知识图谱与仓库结构同源生长。见 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
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)。
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.1.0)
|
||||
## OKF 风格清单(自动生成)
|
||||
|
||||
从源码派生 YAML / Markdown 知识包(勿手改生成物):
|
||||
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `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)。
|
||||
|
||||
```bash
|
||||
cargo run -- catalog public -o .marqdo
|
||||
# 或已安装二进制时:
|
||||
marqdo catalog public -o .marqdo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.2.0)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430)
|
||||
- 标准库:文本、文件、系统、时间、JSON、网络、数学(公式/绘图)、外联(Python 等)
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [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):`llm` · `agent` · `web` · `quantum`。安装:`marqdo ext list` / `add …` / `remove`(见 [ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext` 或 `MARQDO_EXT`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`。设计:[ext-llm](doc/design/ext-llm.md) · [ext-agent](doc/design/ext-agent.md) · [ext-web](doc/design/ext-web.md) · [ext-quantum](doc/design/ext-quantum.md)
|
||||
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}`
|
||||
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
|
||||
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
||||
|
||||
```bash
|
||||
@@ -74,11 +117,13 @@ cargo run -- run tests/structure/hello.mq.md
|
||||
cargo run -- run tests/structure/hello.mq.md --backend bytecode
|
||||
cargo run -- view public --no-open
|
||||
cargo run -- debug public --no-open
|
||||
cargo run -- catalog public -o .marqdo
|
||||
cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
cargo run -- catalog tests -o .marqdo
|
||||
```
|
||||
|
||||
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`> lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add llm|agent|web|quantum` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。`marqdo version --check` 可查看是否有新版本。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
|
||||
|
||||
---
|
||||
|
||||
+26
-6
@@ -16,29 +16,49 @@
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [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) | **英文最小关键字 / 内置函数** |
|
||||
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
|
||||
| [design/stdlib.md](design/stdlib.md) | **P2 标准库:内置 + `lib/` + 错误约定** |
|
||||
| [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/网络(JSON 中英同库)** |
|
||||
| [design/stdlib-math.md](design/stdlib-math.md) | **方案:数学库(数值/随机/作图/轻量求解)** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.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/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
|
||||
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
|
||||
| [design/user-site.md](design/user-site.md) | **用户站:`public/` → `gh-pages`** |
|
||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
||||
| [design/view-debug.md](design/view-debug.md) | **`marqdo debug` 独立调试页** |
|
||||
| [design/vscode-extension.md](design/vscode-extension.md) | **VS Code 扩展:分支 `vscode-extension`(main 不跟踪源码)** |
|
||||
| [design/vscode-extension-commit.md](design/vscode-extension-commit.md) | **扩展提交约定(禁止在 main 提交 `vscode-extension/`)** |
|
||||
| [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 调研 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# Marqdo AI Skill
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已提供 |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 路径 | [`skills/marqdo/`](../../skills/marqdo/)(权威);Cursor 镜像 [`.cursor/skills/marqdo/`](../../.cursor/skills/marqdo/) |
|
||||
|
||||
---
|
||||
|
||||
## 目的
|
||||
|
||||
让接入方(Cursor Agent、其它支持 Agent Skills 的模型宿主)在**加载本 skill 后**即可按 v0.1 语法正确编写 / 修改 `.mq.md`,而不把 Markdown 习惯或 Python 控制流误套到 Marqdo。
|
||||
|
||||
## 内容
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `SKILL.md` | 必读:硬规则、标记表、工作流、反模式 |
|
||||
| `reference.md` | 按需:CLI、stdlib 索引、边界 |
|
||||
| `examples.md` | 按需:可复制样例 |
|
||||
|
||||
## 使用
|
||||
|
||||
- **本仓库 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,7 +67,8 @@
|
||||
| `keywords/bool-logic` | ✅ | ✅ |
|
||||
| `structure/nested-call` | ✅ | ✅ |
|
||||
| `structure/positional-call` | ✅ | ✅ |
|
||||
| `structure/import/*` | ✅ | ✅(load 合并 AST 后编译) |
|
||||
| `structure/import/*` | ✅ | ✅(导入模块树后编译) |
|
||||
| `structure/ns/*` | ✅ | ✅ |
|
||||
| `tests/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) |
|
||||
|
||||
核心金样例双后端已对齐;后续可扩展 Op、优化与更好的调试信息。
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.1 增补) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) |
|
||||
|
||||
---
|
||||
|
||||
@@ -50,4 +50,4 @@ positional ::= value_token
|
||||
|
||||
## 4. 金样例
|
||||
|
||||
见 `tests/structure/positional-call.mq.md` 与更新后的 `tests/structure/import/`。
|
||||
见 `tests/structure/positional-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
|
||||
+32
-33
@@ -2,18 +2,18 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0 命令落地) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 状态 | 已定(O1 + O3:工程目录包 + agent-kb 概念并入) |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 |
|
||||
| 相关 | [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
|
||||
| 相关 | [okf.md](okf.md)(**实现规范总览**)· [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 决策(重申)
|
||||
|
||||
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。详见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
|
||||
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。完整词汇、任务知识包与路线图见 [**okf.md**](okf.md)。生成式方向见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
|
||||
|
||||
本文件规定 **CLI 与 v0 落盘格式**。
|
||||
本文件规定 **CLI 与工程目录包落盘格式**(含 O3:扫入本地 `agent-kb` 概念,供人与工具同览)。
|
||||
|
||||
---
|
||||
|
||||
@@ -28,26 +28,31 @@ marqdo sync [PATH] -o OUT_DIR
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
|
||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件) |
|
||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
|
||||
|
||||
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 生成物(v0)
|
||||
## 3. 生成物
|
||||
|
||||
```
|
||||
OUT_DIR/
|
||||
catalog.yaml # 机器向总清单(OKF 风格字段)
|
||||
index.md # 人/Agent 可读总览(含 YAML frontmatter)
|
||||
index.md # 人可读总览:Modules + Agent knowledge
|
||||
modules/
|
||||
<stem>.md # 每个 .mq.md 一个概念页(frontmatter + 摘要)
|
||||
<stem>.md # 每个工程 .mq.md 一个 Module 页
|
||||
concepts/ # 从 **/.marqdo/agent-kb/concepts/ 复制(O3)
|
||||
tasks/…
|
||||
skills/…
|
||||
```
|
||||
|
||||
路径中的目录层级拍扁为文件名时用 `__` 连接,例如:
|
||||
|
||||
`structure/import/main.mq.md` → `modules/structure__import__main.md`
|
||||
|
||||
`.marqdo/agent-kb/` 下的可执行 `.mq.md` **不**进 Module 表(由 Task/Skill 概念页的 `resource` 指向)。
|
||||
|
||||
### 3.1 `catalog.yaml`(示意)
|
||||
|
||||
```yaml
|
||||
@@ -55,12 +60,11 @@ OUT_DIR/
|
||||
type: Marqdo Catalog
|
||||
title: marqdo-project
|
||||
generated:
|
||||
by: marqdo/0.0.1
|
||||
# at: 可选 ISO8601;CI 比对时可忽略
|
||||
by: marqdo/0.1.2
|
||||
modules:
|
||||
- id: structure/hello
|
||||
resource: structure/hello.mq.md
|
||||
title: Hello World # 来自源 frontmatter title,缺省用文件名
|
||||
title: Hello World
|
||||
imports: []
|
||||
exports:
|
||||
- name: Hello World
|
||||
@@ -72,35 +76,28 @@ modules:
|
||||
exports:
|
||||
- name: main
|
||||
kind: fn
|
||||
concepts: [] # 有 agent-kb 时为 Task/Skill 条目列表
|
||||
```
|
||||
|
||||
字段约定(v0 最小集):
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) |
|
||||
| `modules[].resource` | 相对 `PATH` 的源路径 |
|
||||
| `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` |
|
||||
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`);嵌套 `##` 列入 `children`(可选,v0 可扁平只列顶层) |
|
||||
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`) |
|
||||
| `modules[].verified` / `sources` | 源 frontmatter 有则透传(O3) |
|
||||
| `concepts[]` | 本地 agent-kb 概念摘要(`id`/`type`/`page`/…) |
|
||||
| `generated.by` | `marqdo/<crate version>` |
|
||||
|
||||
不在 v0:版本锁定哈希、跨仓 URL、完整符号类型。
|
||||
不在现行范围:版本锁定哈希、跨仓 URL、完整符号类型、`log.md`(见 okf O4)。
|
||||
|
||||
### 3.2 模块概念页 frontmatter
|
||||
### 3.2 模块概念页
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Marqdo Module
|
||||
title: …
|
||||
resource: structure/hello.mq.md
|
||||
depends: [] # imports 列表
|
||||
exports: [Hello World]
|
||||
generated:
|
||||
by: marqdo/0.0.1
|
||||
---
|
||||
```
|
||||
Frontmatter 仍用 `depends` 字符串列表(机器可读);**正文 Dependencies** 链到同包其它 Module 页(人可点)。源若带 `verified` / `sources` 则写入页头。
|
||||
|
||||
正文含「请勿手改」提示、依赖列表、导出列表;可链到同包其它模块页。
|
||||
### 3.3 Agent knowledge
|
||||
|
||||
`index.md` 的 **Agent knowledge** 节列出扫到的 Task/Skill,链到 `concepts/…`。概念页内容从本地 `agent-kb` **复制**,与 Agent 运行时包同源,便于人审阅晋升结果。
|
||||
|
||||
---
|
||||
|
||||
@@ -109,7 +106,7 @@ generated:
|
||||
| 命令 | 产物 | 受众 |
|
||||
|------|------|------|
|
||||
| `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
|
||||
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引 | 工具 / Agent / 依赖总览 |
|
||||
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引(含 agent-kb) | 人浏览依赖/技能 · 工具 / Agent |
|
||||
|
||||
二者都从同一源树生成,互不替代。发布用户文档时可同时:
|
||||
|
||||
@@ -122,7 +119,9 @@ marqdo catalog tests -o .marqdo
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml` 与 `modules/`。
|
||||
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml`、`modules/`、`concepts:` 键。
|
||||
2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。
|
||||
3. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
|
||||
4. `marqdo sync` 与 `catalog` 行为一致。
|
||||
3. 模块页 Dependencies 对已解析导入为 Markdown 链接。
|
||||
4. 若扫描根下有 `.marqdo/agent-kb/concepts/`,则复制进 `OUT_DIR/concepts/` 且 `index.md` 有 Agent knowledge 条目。
|
||||
5. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
|
||||
6. `marqdo sync` 与 `catalog` 行为一致。
|
||||
@@ -21,7 +21,8 @@
|
||||
|
||||
- 以**空行**划分段落。
|
||||
- 段首行:首字符非标记 → 注释。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` 等开头)。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
|
||||
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
|
||||
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
|
||||
|
||||
---
|
||||
|
||||
@@ -81,6 +81,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 原则 | **夹具即金样例**:`tests/{structure,keywords,errors}/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view tests` 也可浏览 |
|
||||
|
||||
---
|
||||
@@ -26,10 +26,17 @@ tests/
|
||||
import/
|
||||
main.mq.md
|
||||
utils.mq.md
|
||||
ns/
|
||||
helpers.mq.md
|
||||
path3.mq.md
|
||||
use.mq.md
|
||||
keywords/ # 关键字与内置名
|
||||
print.mq.md
|
||||
bool-logic.mq.md
|
||||
ext/
|
||||
agent-run-live.mq.md
|
||||
errors/ # 期望失败(诊断文案稳定后再加金样例)
|
||||
ns-instance-method.mq.md
|
||||
…
|
||||
```
|
||||
|
||||
@@ -42,7 +49,7 @@ tests/
|
||||
|
||||
| 类别 | 测什么 | 不测什么 |
|
||||
|------|--------|----------|
|
||||
| **structure** | `#`/`##`、形参、`>` 调用、`*`/`**`、`+`/`-`、表、导入、位置/具名实参 | 关键字边角 |
|
||||
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、点号路径 / `use`、位置/具名实参 | 关键字边角 |
|
||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
||||
|
||||
@@ -51,7 +58,8 @@ tests/
|
||||
- **流水线调试**:`--dump-lines` / `--dump-ast` / `--trace-eval`
|
||||
- **CLI**:默认 `index.mq.md`、退出码
|
||||
- **view**:目录扫描、单文件页、执行区(见 [view.md](view.md))
|
||||
- **模块图**:循环导入拒绝
|
||||
- **模块图**:循环导入拒绝;`errors/ns-instance-method`(实例方法路径)
|
||||
- **ext live**:`ext/agent-run-live`(需 `.env` + `libagent`)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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
|
||||
---
|
||||
> 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,143 @@
|
||||
# 父智能体 Plan-and-Move(`## plan` 行动面)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted** |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 父文档 | [ext-agent-plan.md](ext-agent-plan.md) · [ext-agent.md](ext-agent.md) |
|
||||
| 相关 | [stdlib-subtask.md](stdlib-subtask.md) · [okf.md](okf.md) · [ai-skill.md](ai-skill.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 一句话
|
||||
|
||||
**父智能体 = Plan-and-Move 控制器**:观察工作簿与子任务结果 → 规划下一步 → 行动(读 / 调工具 / 补丁 / 再跑 / 停);Marqdo「文档即代码」让工具、记忆与程序都落在 `.mq.md` 上。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为何需要强化
|
||||
|
||||
单靠 `DECISION: DONE|CONTINUE|RUN` 时,父侧几乎没有「手」:
|
||||
|
||||
| 缺口 | 后果 |
|
||||
|------|------|
|
||||
| 看不到子源码 / 报错 / stdout | 空想 FIND/REPLACE,输出又臭又长 |
|
||||
| 标准库未进入行动表 | 无法在规划环内用 `fs` / `json` / `subtask` 等 |
|
||||
| 不能用 Marqdo 造工具 | 无法把可复用步骤沉淀为 `##` |
|
||||
| 提示词过长且互相打架 | 模型「继续帮忙」而不停机 |
|
||||
|
||||
业界对 agent 回环的共识:成功标准、停机动作、**确定性行动面**三者必须写清;停机最终靠代码护栏,不只靠 prompt。
|
||||
|
||||
---
|
||||
|
||||
## 3. Marqdo 赋予的特性(相对通用 Plan-and-Move)
|
||||
|
||||
| 特性 | 含义 |
|
||||
|------|------|
|
||||
| 工作簿即程序 | 子执行物是可 `spawn path=` 的 `.mq.md`,不是隐式任务图 |
|
||||
| 固化即记忆 | `DECISION: DONE` → `agent_workbook_solidify` + OKF 晋升 |
|
||||
| `lib/*` 即工具 | 标准库是父可调度能力;经父 helper 或写入工作簿/`tools/` 后调用 |
|
||||
| 补丁即改代码 | `CONTINUE` + 精确 FIND/REPLACE;禁止整文件 LLM 重写 |
|
||||
| 文档即提示 | 站立提示、Skill 摘要、观察切片都是可读 Markdown,而非黑盒 system blob |
|
||||
|
||||
---
|
||||
|
||||
## 4. 循环形状(锁定)
|
||||
|
||||
```text
|
||||
┌──────────────┐
|
||||
│ Plan (LLM) │
|
||||
└──────┬───────┘
|
||||
│ 协议回复
|
||||
┌─────────────┼─────────────┐
|
||||
▼ ▼ ▼
|
||||
READ:/CALL: DECISION: (无效 → error)
|
||||
│ DONE/RUN/
|
||||
│ CONTINUE
|
||||
▼ ▼
|
||||
Act 工具 Move(固化/补丁/spawn)
|
||||
│ │
|
||||
└──────┬──────┘
|
||||
▼
|
||||
Observe(有界)
|
||||
│
|
||||
└──► 回到 Plan 或终止
|
||||
```
|
||||
|
||||
优先级(解析父回复时):
|
||||
|
||||
1. **`CALL:<name>` / `调用:`** — 跑父侧工具,结果并入 observation,再 Plan
|
||||
2. **`READ:<kind>` / `读取:`** — 加深某一观察切片,再 Plan
|
||||
3. **`DECISION:`** — Move(含运行时 solidify / apply_patch / spawn)
|
||||
|
||||
---
|
||||
|
||||
## 5. 观察面(有界、可加深)
|
||||
|
||||
`inspect_workbook` / `await_workbook` 在磁盘上可持有全文;**注入父 prompt 的默认紧凑观察**必须可行动且短:
|
||||
|
||||
| 字段 | 默认 | `READ:` 加深 |
|
||||
|------|------|----------------|
|
||||
| `source_excerpt` | 去 `<!-- … -->` 后的结构摘录,硬顶 ~4KiB / ~80 行 | `READ:source` → 更大但仍有硬顶的摘录 |
|
||||
| `stderr_tail` / `stdout_tail` | 子任务捕获尾部 ~2KiB | `READ:stderr` / `READ:stdout` |
|
||||
| `value` | ≤200 字;否则 `value_preview` + `value_len` | (一般不必加深) |
|
||||
| `slots` | `{key,line,body_len}`;`error` 槽可带短预览 | `READ:slots` |
|
||||
| `has_worker_step` / `solidify_on_done` | 布尔提示 | — |
|
||||
|
||||
`quiet=True` **只表示不污染父 TTY**;file `wait` 仍返回截断后的 `stdout` / `stderr` 供父观察。
|
||||
|
||||
---
|
||||
|
||||
## 6. 工具面
|
||||
|
||||
### 6.1 父侧内建 helper(`CALL:` 首批)
|
||||
|
||||
写在 `ext/ai/agent.mq.md`,由 plan 循环直接调度(**不用** OpenAI function calling):
|
||||
|
||||
| 名称 | 作用 |
|
||||
|------|------|
|
||||
| `workbook_read` | 按 depth 读工作簿摘录 |
|
||||
| `workbook_excerpt` | 结构摘录(默认观察同源) |
|
||||
| `lib_catalog` | 枚举 `lib/*.mq.md` 能力摘要 |
|
||||
| `scratch_tool_write` | 写入 `.marqdo/agent-runs/tools/<name>.mq.md` |
|
||||
|
||||
### 6.2 标准库与造工具
|
||||
|
||||
- **标准库直调(白名单)**:`CALL:lib.fs.read_text`(及 `exists` / `list_dir` / `json.parse` / `json.stringify` / `sys.cwd`)+ 可选 `ARGS:{…}` JSON 行;拒绝 `net.*` / `sys.exec` / 写删类。
|
||||
- **目录**:`lib_catalog` 列出可 CALL 的 dotted 名。
|
||||
- **造工具**:优先 `CONTINUE` + 短 PATCH 在工作簿内新增 `##`;或 `CALL:scratch_tool_write` 沉淀独立工具文件。
|
||||
- **流式**:父 CALL/READ 发 `tool_start` / `tool_end`(view Tool 卡)。
|
||||
- **非目标**:全量 `lib/*` JSON schema 反射;OpenAI function calling。
|
||||
|
||||
---
|
||||
|
||||
## 7. 输出纪律(停机规则)
|
||||
|
||||
父回复**只允许**协议行 + 一行 `SUMMARY` + 短 PATCH(`<20` 行)。禁止长独白 / 行程散文 / 把 observation 粘进 REPLACE。
|
||||
|
||||
修订阶段硬规则(自上而下):
|
||||
|
||||
1. `exit_code==0` 且 `has_value` → **立刻** `DECISION: DONE`(运行时 solidify);`has_worker_step` **不是** CONTINUE 的理由。
|
||||
2. 仅失败 / 无值 / 明确未达目标时才 `CONTINUE`。
|
||||
3. 代码护栏:非 `improve` 时,子已返回值则 **跳过父 LLM**,直接 solidify + DONE。
|
||||
|
||||
---
|
||||
|
||||
## 8. 与 `## step` 的关系
|
||||
|
||||
| | `step`(子) | `plan`(父) |
|
||||
|---|-------------|-------------|
|
||||
| 协议 | `CALL:` 或最终答案 | `CALL:` / `READ:` / `DECISION:` |
|
||||
| 工具来源 | 工作簿 / 调用方 allowlist | 父 helper + 写入的 Marqdo `##` |
|
||||
| 成功出口 | 返回答案文本 | `DONE` + solidify / promote |
|
||||
|
||||
---
|
||||
|
||||
## 9. 实现落点
|
||||
|
||||
| 组件 | 路径 |
|
||||
|------|------|
|
||||
| 设计(本文) | `doc/design/ext-agent-parent.md` |
|
||||
| 多步总设计增量 | `doc/design/ext-agent-plan.md` §4.1 / 协议 |
|
||||
| 子任务 I/O | `src/host/subtask.rs`、`lib/subtask.mq.md` |
|
||||
| 父循环 / 观察 / 提示 | `ext/ai/agent.mq.md` |
|
||||
@@ -0,0 +1,356 @@
|
||||
# 智能体多步(`## 多步` / `## plan`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted;D2a–D2f 已落地;父 Plan-and-Move / OKF 软命中见配套文档** |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 父文档 | [ext-agent.md](ext-agent.md) |
|
||||
| 相关 | [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move 行动面**) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [module-namespace.md](module-namespace.md) · [ai-skill.md](ai-skill.md) · [objects.md](objects.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
单步(`## 单步` / `## step`)适合原子任务。复杂目标需要:
|
||||
|
||||
1. **把分解与执行过程落成一份可运行的 `.mq.md`**(工作簿),而不是藏在进程内的任务图。
|
||||
2. **用子任务真正跑这份工作簿**,与主推理隔离。
|
||||
3. **父智能体作为「智能体开发大师」**:结构化读取执行结果与写回,再二次规划;用**精确补丁**改工作簿代码,并把确定步骤**固化为普通 Marqdo `##`**。
|
||||
4. **允许工作簿演化**——代码与 `<!-- marqdo-out … -->` 均可更新,但**禁止**以整文件 LLM 重写作为修订主路径。
|
||||
5. 子智能体只做不确定的 `单步`;能写成代码的就不要再问模型。
|
||||
|
||||
本文锁定 **`## 多步` / `## plan`** 的语义。总览与分层见 [ext-agent.md](ext-agent.md);实现以 D2 为准。
|
||||
|
||||
---
|
||||
|
||||
## 2. 一句话
|
||||
|
||||
**多步 = 父智能体(开发大师)生成并演进一份子 Marqdo 程序:经 `lib/subtask` 运行它,结构化观察写回与源码,再二次规划并精确打补丁;子 `# 智能体` 只跑 `单步`,确定步骤固化为代码。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 角色与产物
|
||||
|
||||
| 角色 | 职责 |
|
||||
|------|------|
|
||||
| **父智能体** | 持有目标;创建 / 改写工作簿;`spawn path=` 运行工作簿;读执行结果与写回块;决定改代码还是改提示;汇总并写回父文档 |
|
||||
| **工作簿 `.mq.md`** | 任务实现的**详细步骤文档兼程序**:导入、工具、一个或多个子智能体、可固化的普通函数与 `# main` 编排 |
|
||||
| **子智能体** | 工作簿内的 `# 智能体` / `# agent`;走 `单步`(默认);工具表白名单可收窄 |
|
||||
| **子任务通道** | `lib/subtask`:`spawn path=<工作簿>` → `wait`;与工具 `spawn fn=` 同一套能力 |
|
||||
|
||||
| 产物 | 说明 |
|
||||
|------|------|
|
||||
| 工作簿路径 | 默认目录 `.marqdo/agent-runs/`(可参数覆盖);文件名含时间 / 短 id |
|
||||
| 父侧返回值 | 结构化 map:`status`、`goal`、`workbook`(路径)、`result`(子 `# main` 返回值优先)、`summary` / `error`;可选 `observation` |
|
||||
| 写回 | 工作簿内各 `单步` 默认落盘;父 `多步` 调用行亦可汇总写回 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 调用流水线(锁定)
|
||||
|
||||
```text
|
||||
父:`助手`.多步 目标=…
|
||||
▼
|
||||
① 解析参数(目录、深度、是否确认分解、是否覆盖已有工作簿…)
|
||||
▼
|
||||
② 创建(或打开)工作簿 .mq.md
|
||||
- frontmatter:导入 ext/ai/llm|agent、json、writeback、subtask…
|
||||
- **大模型配置与父智能体一致**(见 §5)
|
||||
- 正文:总目标叙述 + 子智能体骨架 / 或父模型生成的首版步骤
|
||||
▼
|
||||
③ 父模型「分解」(非 OKF 命中路径必跑):`phase=decompose`,尚未 spawn;可 `DECISION: RUN` / `CONTINUE`+补丁 / 固化后 `DONE`
|
||||
▼
|
||||
④ lib/subtask:spawn path=<工作簿绝对或相对路径>
|
||||
▼
|
||||
⑤ wait → 收集 `{code, value}`(`# main` 返回)+ 工作簿内写回块;TTY 默认静默
|
||||
▼
|
||||
⑥ 父智能体 **结构化观察**(工作簿最新源码 + 写回槽 + 退出码 + `value`)
|
||||
- 充分 → 汇总,写回父文档,返回
|
||||
- 不足 / 失败 → **二次规划** → 对工作簿打**精确补丁**(禁止整文件重写)→ 回到 ④
|
||||
▼
|
||||
⑦ 触达最大修订轮次或深度 → 以 error / 部分摘要返回
|
||||
```
|
||||
|
||||
要点:
|
||||
|
||||
- **创建文件发生在 `多步` 内**,不是调用方手写脚手架(调用方可传已有 `工作簿=` 路径以续跑)。
|
||||
- **执行工作簿 = 子任务跑整文件**(入口 `# main`),不是父进程内嵌解释子 AST。
|
||||
- **父是智能体开发大师**:读真实执行结果再规划;修订靠精确补丁与代码固化,不靠整文件重生。
|
||||
- **修订循环属于父智能体职责**:同一 `多步` 调用内可多轮「观察 → 规划 → 补丁 → 再 spawn」。
|
||||
|
||||
---
|
||||
|
||||
## 4.1 观察面与补丁(锁定)
|
||||
|
||||
父每次二次规划前必须拿到观察 map(`inspect_workbook` / `await_workbook`)。磁盘可持全文;**注入父 LLM 的默认观察为有界紧凑面**(摘录 + I/O 尾部)。完整语义与 `READ:` / `CALL:` 行动面见 [ext-agent-parent.md](ext-agent-parent.md)。
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `path` | 工作簿路径 |
|
||||
| `source` | 最新全文(磁盘);prompt 默认用 `source_excerpt` |
|
||||
| `exit_code` | 上一轮子任务退出码 |
|
||||
| `value` | 子 `# main` 返回值(经 `await_workbook` / `wait.value`) |
|
||||
| `stdout` / `stderr` | 子任务捕获(`quiet` 仅静音 TTY,不丢弃数据) |
|
||||
| `slots` | 命名写回列表(`key` + `body`) |
|
||||
| `last_ok` / `last_error` | 便捷字段 |
|
||||
|
||||
二次规划输出协议(机器可解析;**禁止**只输出整份 `.mq.md`;**禁止**长独白):
|
||||
|
||||
```text
|
||||
CALL:<parent-tool>
|
||||
READ:source|stderr|stdout|slots
|
||||
|
||||
DECISION: DONE
|
||||
SUMMARY: <一行>
|
||||
|
||||
DECISION: RUN
|
||||
|
||||
DECISION: CONTINUE
|
||||
PATCH:
|
||||
<<<
|
||||
FIND
|
||||
<确切旧片段>
|
||||
===
|
||||
REPLACE
|
||||
<新片段>
|
||||
>>>
|
||||
```
|
||||
|
||||
解析优先级:`CALL` → `READ` → `DECISION`。应用器对文件做**精确** FIND→REPLACE;找不到则报错。`DONE` 时运行时 `agent_workbook_solidify` 固化答案(不必靠长 REPLACE 粘贴子散文)。
|
||||
|
||||
---
|
||||
|
||||
## 4.2 多轮哲学:仅子智能体接力(模式 C)
|
||||
|
||||
复杂 / 多轮目标 = **多份可执行 `.mq.md` 接力**,经 OKF 索引与复用;父 `plan` 聚合各子 `wait.value` 为 `result`。
|
||||
|
||||
| 做 | 不做 |
|
||||
|----|------|
|
||||
| 每主题 / 子目标一份工作簿(`resources/` / `explore/`) | 单文件无限追加「对话日志」 |
|
||||
| OKF task/skill 做索引与命中 | 单文件状态机表冒充流程 UI |
|
||||
| `# main` **返回**答案;`quiet` 只管 TTY | 依赖子 `print` 把答案刷到父终端 |
|
||||
---
|
||||
|
||||
## 5. 大模型配置与父保持一致
|
||||
|
||||
工作簿内构造子智能体时:
|
||||
|
||||
| 从父继承 | 说明 |
|
||||
|----------|------|
|
||||
| `model` / `大模型` 句柄字段 | `api_key`、`base_url`、`model`、`suffix`、`bearer` 及拼装前缀等与父相同 |
|
||||
| 默认站立提示基调 | 可追加「只负责本工作簿内子任务」等收窄句;不得更换供应商端点 |
|
||||
|
||||
实现约定(D2):
|
||||
|
||||
1. 父把当前 llm 句柄 **序列化进工作簿**(例如构造段直接写 `> llm.llm` 前先 `load_env`,或写入由父生成的配置表 / 环境约定)。
|
||||
2. 优先:**工作簿与父共享同一套 `OPENAI_*` / `.env` 加载路径**,子文件内 `> llm.load_env` + `> llm.llm`(或中文面),避免把密钥明文写进工作簿。
|
||||
3. 若父句柄来自非默认 env,父须在生成工作簿时写出等价构造(仍禁止把密钥写进 git 跟踪路径;工作簿目录应默认被 ignore)。
|
||||
|
||||
**禁止**:子工作簿默默改用另一 `base_url` / 另一模型名,除非调用方显式参数允许覆盖(v1 不提供覆盖;一律继承)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 工作簿内容形态
|
||||
|
||||
### 6.1 推荐:多个子智能体
|
||||
|
||||
面对多种情形时,**多个 `# 智能体`(或一个类型多次构造)** 优于单一巨型提示:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: agent-run-…
|
||||
> ext/ai/llm.mq.md
|
||||
> ext/ai/agent.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/writeback.mq.md
|
||||
> lib/subtask.mq.md
|
||||
---
|
||||
|
||||
# 总目标
|
||||
|
||||
(父写入的目标叙述)
|
||||
|
||||
## 工具甲
|
||||
…
|
||||
|
||||
# main
|
||||
|
||||
> llm.load_env path=…
|
||||
|
||||
*`模型` = > llm.llm *
|
||||
|
||||
*`调研` = > agent.agent model=`模型` tools=`表甲` standing=… *
|
||||
*`撰写` = > agent.agent model=`模型` tools=`表乙` standing=… *
|
||||
|
||||
*`a` = > `调研`.step task=… *
|
||||
*`b` = > `撰写`.step task=… *
|
||||
```
|
||||
|
||||
### 6.2 也可:一个智能体多次单步
|
||||
|
||||
适合线性流水线;每次 `step` 仍默认写回,便于中断续跑。
|
||||
|
||||
### 6.3 固化为代码(强烈推荐)
|
||||
|
||||
一旦某步输入输出稳定(例如「取今日日期」「解析固定 JSON」),父智能体应把该步 **改写成普通 `##` 函数 + 直接调用**,不再经子智能体推理:
|
||||
|
||||
| 不确定 | 已确定 |
|
||||
|--------|--------|
|
||||
| `` > `子`.step task=… `` | `` *`x` = > 本地函数 … `` |
|
||||
| 宽工具表 + 长 standing | 窄函数、表驱动、分支 `1.` / `2.` |
|
||||
|
||||
**多步的价值之一就是把「试出来的正确步骤」沉淀成工作簿里的代码**,而不仅是 chat 痕迹。
|
||||
|
||||
### 6.4 持续更新的两类内容
|
||||
|
||||
| 更新 | 含义 |
|
||||
|------|------|
|
||||
| **代码更新** | 增删 `##`、改 `# main` 编排、改工具表、把 step 换成固化调用、修分支 |
|
||||
| **写回注释更新** | `<!-- marqdo-out ok|error -->` 被单步 / 父汇总刷新;替换时**不得累积空行**(见 writeback 实现约定) |
|
||||
|
||||
工作簿是活文档:子任务跑完后磁盘上的 `.mq.md` 应比创建时更「像最终报告」。
|
||||
|
||||
---
|
||||
|
||||
## 7. 单步自动写回(服务多步)
|
||||
|
||||
### 7.1 决议
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **默认** | `单步` / `step` **自动写回** 本步结果(命名槽) |
|
||||
| **开关** | 参数 `写回` / `writeback`(布尔,默认 `真` / `True`) |
|
||||
| **槽** | 成功 → `key=ok`;失败 → `key=error`;正文为结构化 map 的 JSON(或与现 live 样例一致的 stringify) |
|
||||
| **锚点** | 本步调用行(与现 `writeback.record` 锚点规则一致) |
|
||||
|
||||
这样:
|
||||
|
||||
- 父 / 工作簿**不必**靠提示词强迫模型「请记得写回」。
|
||||
- 编排方仍可 `写回=假` 拿到纯 map,自行 `writeback.record`(测试、嵌套去重时有用)。
|
||||
|
||||
### 7.2 与父写回的分工
|
||||
|
||||
| 层级 | 写什么 |
|
||||
|------|--------|
|
||||
| 子 `step`(默认开) | 该步 decision / tool / result 或 error |
|
||||
| 父 `plan` | 工作簿路径、轮次、汇总摘要;可选把关键子 ok 块索引写在父调用行下 |
|
||||
|
||||
**推荐**:载荷以子 `# main` 返回值(`wait.value` → `plan.result`)为准;写回作审计与 step 缓存。避免只靠 stdout(默认静默会丢弃)。
|
||||
|
||||
### 7.3 返回值
|
||||
|
||||
`step` 仍返回结构化 map(与现 D1 一致)。自动写回是**附加副作用**,不取代返回值。
|
||||
|
||||
---
|
||||
|
||||
## 8. 父智能体上下文(每次修订 / 汇总前)
|
||||
|
||||
父在多步循环中每次「想下一步」时,注入不得弱于单步,且额外包含工作簿:
|
||||
|
||||
| 片段 | 来源 |
|
||||
|------|------|
|
||||
| 站立提示 | 父构造 |
|
||||
| 总目标 | `多步` 实参 |
|
||||
| **父文件源码** | `agent_module_source` |
|
||||
| **调用位置** | `agent_call_site` |
|
||||
| **Marqdo Skill** | `agent_marqdo_skill` |
|
||||
| 工作簿全文 / 写回 / 子返回 | `inspect_workbook`(源码 + slots + 退出码 + `value`) |
|
||||
| 子任务退出码 | `subtask.wait` |
|
||||
| 对话 / 历史 | 父 session;真相以写回为准 |
|
||||
|
||||
父模型输出必须是 **DONE / CONTINUE+精确补丁** 协议(见 §4.1),禁止整文件重写。
|
||||
|
||||
---
|
||||
|
||||
## 9. 公开 API(D2 契约)
|
||||
|
||||
### 9.1 `## 多步` / `## plan`
|
||||
|
||||
| 参数 | 中 / 英 | 默认 | 说明 |
|
||||
|------|---------|------|------|
|
||||
| 目标 | `目标` / `goal` | 必填 | 复杂任务描述 |
|
||||
| 工作簿目录 | `工作簿目录` / `workbook_dir` | `.marqdo/agent-runs` | 新建文件所在目录 |
|
||||
| 工作簿 | `工作簿` / `workbook` | 空 | 若给路径则**续跑 / 修订**该文件,跳过空白创建 |
|
||||
| 最大深度 | `最大深度` / `max_depth` | `2` | 工作簿内再调 `多步` 的嵌套上限;叶强制单步 |
|
||||
| 最大轮次 | `最大轮次` / `max_rounds` | 实现选定(如 `4`) | 父「改文件 → 再执行」循环上限 |
|
||||
| 确认分解 | `确认分解` / `confirm` | `假` | `真` 时首版工作簿生成后暂停(返回 pending + 路径),不自动 spawn |
|
||||
| 写回 | `写回` / `writeback` | `真` | 父侧汇总写回 |
|
||||
| 骨架 | `骨架` / `skeleton` | `single` | `single` 单 worker;`dual` 为 research→writer 两子智能体 |
|
||||
|
||||
返回 map(字段名英文字段,中文面可读同一结构):
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `status` | `ok` / `error` / `pending`(待确认) |
|
||||
| `goal` | 回显目标 |
|
||||
| `workbook` | 工作簿路径 |
|
||||
| `rounds` | 实际执行轮次 |
|
||||
| `summary` | 成功时的汇总 |
|
||||
| `error` | 失败信息 |
|
||||
|
||||
### 9.2 `## 单步` / `## step`(修订)
|
||||
|
||||
在 D1 参数上增加:
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `写回` / `writeback` | `真` | 是否自动 `record` 到 ok/error 槽 |
|
||||
|
||||
### 9.3 内部辅助(非稳定对外)
|
||||
|
||||
工作簿模板渲染、从父句柄生成子文件 frontmatter、解析子写回摘要等——可随实现调整。
|
||||
|
||||
---
|
||||
|
||||
## 10. 安全与边界
|
||||
|
||||
| 风险 | 对策 |
|
||||
|------|------|
|
||||
| 无限修订 / 嵌套 | `最大轮次`、`最大深度`;叶任务禁止再 `plan` |
|
||||
| 工作簿写爆仓库 | 默认目录 `.marqdo/agent-runs/` + gitignore;禁止默认写到 `lib/` / `ext/` |
|
||||
| 密钥进工作簿 | 继承 env / load_dotenv,不写明文 key |
|
||||
| 子文件乱改父仓 | 子任务 cwd / fs_root 落到工作簿目录;工具表白名单 |
|
||||
| 写回空行膨胀 | 替换跨度含 `-->` 行尾换行(已实现) |
|
||||
| 并发写同一工作簿 | writeback 全局锁;同一 plan 内串行 spawn 为 v1 默认 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 与旧 §3.2 叙述的差异(显式)
|
||||
|
||||
| 旧粗述 | 本文锁定 |
|
||||
|--------|----------|
|
||||
| 分解表 + 每行一个子智能体实例 | **整文件工作簿**可含多智能体与固化代码;表只是可选骨架 |
|
||||
| 子任务默认单步,写回在流水线步骤里点到为止 | **单步默认自动写回**;父负责修订循环与汇总 |
|
||||
| 缓存命中略写 | **以 OKF 任务知识包为准**([okf.md §7](okf.md)):Task→Skill→resource 命中则跳过父模型;D2 + O2 已落地;人读目录见 O3 `marqdo catalog` |
|
||||
| 父上下文未强调工作簿全文 | 父每次修订前必须能读**最新工作簿 + 写回** |
|
||||
|
||||
---
|
||||
|
||||
## 12. 实现路线(D2)
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| D2a | `step` 增加 `writeback=`(默认真);金样例改默认行为并保留 `writeback=False` 测例 | **done** |
|
||||
| D2b | 工作簿模板 + 创建路径 + 父 llm 继承;`inspect_workbook` 观察面 | **done** |
|
||||
| D2c | `plan`:生成 → `spawn path` → wait → **观察** → 返回;`confirm` | **done** |
|
||||
| D2d | 二次规划 + **精确补丁**循环(`max_rounds`);禁止整文件重写 | **done**(主路径) |
|
||||
| D2e | 多子智能体模板与固化提示 | **done**(`skeleton=dual` + Solidify 段 + 父规划优先级) |
|
||||
| D2f | 离线骨架金样例 + 可选 live 多步 | **done**(decision 离线 + `agent-plan-live`) |
|
||||
|
||||
---
|
||||
|
||||
## 13. 决议摘要
|
||||
|
||||
1. **`多步` 自动创建(或续跑)工作簿 `.mq.md`**,内容为任务的详细可执行步骤。
|
||||
2. **子文件大模型配置与父一致**(共享 env / 等价句柄;v1 无静默换模)。
|
||||
3. **经 `lib/subtask` 启动该文件**;可多轮执行。
|
||||
4. **工作簿内推荐多个智能体**;也允许单智能体多 `step`;**确定步骤固化为代码**。
|
||||
5. **工作簿持续更新**:代码 + `marqdo-out`。
|
||||
6. **`单步` 默认自动写回**(`写回=` 可关);父维护汇总写回。
|
||||
7. **父具备源码、Skill、位置、历史与工作簿观察面**,二次规划后以**精确补丁**修改再执行(禁止整文件重写主路径)。
|
||||
|
||||
---
|
||||
|
||||
## 14. 一句话
|
||||
|
||||
**多步不是更长的聊天,而是父智能体编写、运行、修订一份子 Marqdo 程序——程序里的智能体可多可少,写回默认打开,能写成代码的就不要再问模型。**
|
||||
@@ -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 / 任务知识包**) · [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 `> 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
|
||||
---
|
||||
> 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 `> 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
|
||||
---
|
||||
> 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,400 @@
|
||||
# 官方扩展:`ext/quantum` 量子计算模拟
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · Q0–Q5.5 已落地**(教学噪声含振幅阻尼;完整开放系统另文) |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [ext-web.md](ext-web.md) · [view.md](view.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| 安装(目标) | `marqdo ext add quantum`(中英:`quantum` / `量子`) |
|
||||
| 本文目的 | 锁定**作者面**、**模拟语义**、**view 可视化**与**分期**;指导 ABI 插件实现 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
`ext/quantum` 用 **GFM 表格 + 类方法 +(可选)`$$` 狄拉克/矩阵公式** 描述量子门与电路;**经典状态向量模拟**给出概率与采样。
|
||||
文档能跑通,公式与电路约定就成立——这是 Marqdo「代码即文档」在量子教学上的最强展示位。
|
||||
|
||||
**不改 Marqdo 核心语法**;热路径只在 ABI 插件;**禁止**把量子核链进 `marqdo` 主二进制或在 `ext/**` 里调用 `host_*`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何做量子扩展(与 math 的关系)
|
||||
|
||||
### 1.1 与 `lib/math` 的相似处
|
||||
|
||||
| math | quantum |
|
||||
|------|---------|
|
||||
| `` `f` = `` + `$$…$$` → `formula` | 门矩阵 / 态矢量可用 `$$` **展示与核对** |
|
||||
| 库函数对公式求值、求导、作图 | 类方法对电路施门、模拟、画图 |
|
||||
| view 内嵌 SVG;CLI 可 `path=` | view 内嵌**电路图 / 概率条 / 布洛赫**;CLI 可落盘 |
|
||||
| 金样例失败 = 文档/公式错 | 金样例失败 = 门定义或电路叙述错 |
|
||||
|
||||
math 是**高中符号与曲线**;quantum 是**离散希尔伯特空间上的可执行电路文档**。两者都是「写出公式 → 跑通 → 证明文档正确」。
|
||||
|
||||
### 1.2 与 math 的刻意分界
|
||||
|
||||
| 做 | 不做 |
|
||||
|----|------|
|
||||
| 量子在 **`ext/quantum`**,经 `plugin.load` | **不**并进 `lib/math`(避免 stdlib 膨胀) |
|
||||
| 复数振幅用 `{re, im}` map(与现有 `Value` 兼容) | **不**为量子在核心新增 `Value::Complex`(可二期) |
|
||||
| 角度可用 `math.pi` 等常量 | **不**在 quantum 插件内重写 CAS |
|
||||
|
||||
### 1.3 「代码即文档」在这里的作用
|
||||
|
||||
典型教学页:
|
||||
|
||||
```markdown
|
||||
# 贝尔态 |Φ+⟩
|
||||
|
||||
对 qubit 0 施 H,再 CNOT(0→1)。理想测量:`00` 与 `11` 各约 1/2。
|
||||
|
||||
# main
|
||||
|
||||
`steps` =
|
||||
|
||||
| 步 | 门 | 比特 |
|
||||
|----|----|------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
|
||||
*`p` = > `qc`.probabilities *
|
||||
```
|
||||
|
||||
- 叙述与表格是**给人看的电路说明**;
|
||||
- 同一文件是**可执行程序**;
|
||||
- gold / CI 断言概率 → **文档与物理约定同步**,无需另维护「幻灯片公式」。
|
||||
|
||||
---
|
||||
|
||||
## 2. 硬约束(评审锁定)
|
||||
|
||||
1. **仅 ABI 插件接入**:`plugins/quantum` → `libquantum.so`;L1 在 `ext/quantum/*.mq.md`。
|
||||
2. **`ext/quantum/**` 禁止 `host_*`**;经 `plugin.native_path` + `plugin.load`(同 web/agent)。
|
||||
3. **中英分文件**:`quantum.mq.md` / `量子.mq.md`,**禁止**混排 API([stdlib-i18n.md](stdlib-i18n.md))。
|
||||
4. **不改核心语法**;电路表单元格保持字面量;门名/比特下标由类方法解析。
|
||||
5. **模拟器有硬上限**(默认 ≤ 12 qubits);超限报错,不静默截断。
|
||||
6. **view 必须有专项展示**(结构卡 + 执行区 SVG),禁止只 dump JSON。
|
||||
|
||||
---
|
||||
|
||||
## 3. 布局与安装
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
quantum.mq.md # 英文类 API
|
||||
量子.mq.md # 中文类 API
|
||||
plugins/quantum/
|
||||
Cargo.toml
|
||||
src/lib.rs # ABI v2:线性代数 / 施门 / 画 SVG
|
||||
examples/quantum-bell/ # 规范示例(Q3)
|
||||
tests/ext/quantum-*.mq.md
|
||||
```
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_quantum
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
导入:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/quantum/quantum.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
或中文:`> ext/quantum/量子.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 核心模型
|
||||
|
||||
### 4.1 运行时句柄(JSON map + `_type`)
|
||||
|
||||
| `_type`(英) | 中文类名 | 含义 |
|
||||
|---------------|----------|------|
|
||||
| `quantum_gate` | `量子门` | 具名门或自定义酉矩阵 |
|
||||
| `quantum_circuit` | `量子电路` | n qubits + 有序门列表 |
|
||||
| `quantum_state` | `量子态` | 状态向量(振幅列表) |
|
||||
| `quantum_result` | `量子结果` | 概率 / 采样 / 可选坍缩态 |
|
||||
| `quantum_svg` | (产物) | 带 `svg` 字段的可视化结果 |
|
||||
|
||||
插件返回 map;Marqdo 对象系统挂 `_type` 后可用方法链。
|
||||
|
||||
### 4.2 状态表示
|
||||
|
||||
- **纯态**状态向量:长度 `2^n`,每元 `{re, im}`(f64)。
|
||||
- 默认初态:`|0…0⟩`(仅 index 0 振幅为 1)。
|
||||
- 门作用后可选重归一化(阈值误差阈值,默认开)。
|
||||
|
||||
### 4.3 公式面(对齐 math 精神,不抢 math 实现)
|
||||
|
||||
允许用 `` `G` = `` + `$$…$$` 书写门矩阵(**可执行**,见 [ext-quantum-custom-gate.md](ext-quantum-custom-gate.md)):
|
||||
|
||||
````markdown
|
||||
`H_matrix` =
|
||||
$$
|
||||
\frac{1}{\sqrt{2}}\begin{pmatrix}1&1\\1&-1\end{pmatrix}
|
||||
$$
|
||||
|
||||
*`U` = > quantum.gate matrix=`H_matrix` *
|
||||
*`qc` = > `qc`.apply gate=`U` qubits=0 *
|
||||
*`ok` = > `H`.matches_matrix matrix=`H_matrix` *
|
||||
````
|
||||
|
||||
- v1:**具名门**以插件内置酉矩阵为准;`matrix=` 可从嵌套 list / `$$` 矩阵围栏构造自定义门。
|
||||
- `$$` 含 `[[…]]` 或 `\begin{pmatrix}` 时解析期求值为数值 list;标量公式仍为 `Formula`。
|
||||
- `matches_matrix` 仍可用于核对。
|
||||
---
|
||||
|
||||
## 5. 作者面 API(锁定草图)
|
||||
|
||||
### 5.1 英文 `ext/quantum/quantum.mq.md`
|
||||
|
||||
```markdown
|
||||
# gate
|
||||
+ `name`=None # H X Y Z S T I CX CZ SWAP …
|
||||
+ `theta`=None # Rx/Ry/Rz
|
||||
|
||||
## matrix # → 振幅表 / 嵌套 list(文档与调试)
|
||||
## draw # → quantum_svg(`kind=gate|matrix` 符号 / 热力图)
|
||||
## matches_matrix
|
||||
+ `matrix`
|
||||
+ `tol`=1e-9
|
||||
|
||||
# circuit
|
||||
+ `qubits`
|
||||
+ `steps`=None # 可选:GFM 门序列表
|
||||
|
||||
## h / x / y / z / s / t
|
||||
+ `qubit`
|
||||
## rx / ry / rz
|
||||
+ `qubit`
|
||||
+ `theta`
|
||||
## cx / cz
|
||||
+ `control`
|
||||
+ `target`
|
||||
## swap
|
||||
+ `a`
|
||||
+ `b`
|
||||
## barrier # 仅可视化分隔,不改变态
|
||||
## measure # 标记测量(模拟时按计算基)
|
||||
+ `qubits`=None # 默认全部
|
||||
## append # 追加另一电路或门
|
||||
+ `op`
|
||||
## simulate # → quantum_state(不坍缩)
|
||||
## probabilities # → map 基矢标签 → 概率
|
||||
## run
|
||||
+ `shots`=1024
|
||||
+ `seed`=None # → quantum_result(计数直方图)
|
||||
## draw
|
||||
+ `path`=None # SVG;无 path 时仍可进 view 产物
|
||||
## state # 当前缓存态(若已 simulate)
|
||||
```
|
||||
|
||||
门方法返回**更新后的 circuit 句柄**(与 web `compose_*` 相同:`` `qc` = > `qc`.h qubit=0 *``)。
|
||||
|
||||
### 5.2 中文 `ext/quantum/量子.mq.md`
|
||||
|
||||
| 英文 | 中文 |
|
||||
|------|------|
|
||||
| `gate` | `门` |
|
||||
| `circuit` | `电路` |
|
||||
| `h` | `哈达玛` |
|
||||
| `x` / `y` / `z` | `泡利X` / `泡利Y` / `泡利Z` |
|
||||
| `cx` | `控非` |
|
||||
| `cz` | `控相` |
|
||||
| `rx`/`ry`/`rz` | `绕X`/`绕Y`/`绕Z` |
|
||||
| `simulate` | `模拟` |
|
||||
| `probabilities` | `概率` |
|
||||
| `run` | `运行` |
|
||||
| `draw` | `绘图` |
|
||||
| `measure` | `测量` |
|
||||
| `qubits` | `比特数` |
|
||||
| `steps` | `步骤` |
|
||||
| `shots` / `seed` | `次数` / `种子` |
|
||||
|
||||
插件 FFI 名稳定英文:`quantum_circuit_new`、`quantum_h`、`quantum_cx`、`quantum_simulate`、`quantum_draw_circuit`…
|
||||
|
||||
### 5.3 电路表(文档优先写法)
|
||||
|
||||
```markdown
|
||||
`steps` =
|
||||
|
||||
| 步 | 门 | 比特 | 参数 |
|
||||
|----|----|------|------|
|
||||
| 1 | H | 0 | |
|
||||
| 2 | CX | 0,1 | |
|
||||
| 3 | RZ | 1 | pi/4 |
|
||||
```
|
||||
|
||||
列名中英兼容:`步|step`、`门|gate`、`比特|qubits|qubit`、`参数|theta|params`。
|
||||
|
||||
*`qc` = > quantum.circuit qubits=2 steps=`steps` *` 与方法链**等价**;表更适合「整页即电路说明书」。
|
||||
|
||||
### 5.4 返回值形态
|
||||
|
||||
| 方法 | 返回 |
|
||||
|------|------|
|
||||
| `simulate` | `{_type, qubits, dim, amplitudes:[{re,im},…]}` |
|
||||
| `probabilities` | `{ "00": 0.5, "11": 0.5 }`(标签为小端比特串,文档写死) |
|
||||
| `run` | `{ counts: {…}, shots, seed }` |
|
||||
| `draw` | `{_type: quantum_svg, kind: circuit\|gate\|probs\|bloch, svg: "…" }` |
|
||||
|
||||
---
|
||||
|
||||
## 6. 模拟器语义
|
||||
|
||||
| 项 | 锁定 |
|
||||
|----|------|
|
||||
| 模型 | 封闭系统纯态;计算基测量 |
|
||||
| 默认上限 | **12 qubits**;`MARQDO_QUANTUM_MAX_QUBITS` 可下调(不可暗中上调超过编译期硬顶,硬顶建议 16) |
|
||||
| 超限 | 错误信息含当前 n 与上限 |
|
||||
| `simulate` / `probabilities` | **无 RNG**、确定性 |
|
||||
| `run` | 多项式采样;`seed=` 可复现(金样必用) |
|
||||
| 数值 | f64;门后 ‖ψ‖ 偏离阈值则重归一化并可选 warning 字段 |
|
||||
|
||||
实现:插件内 Kronecker / 按比特作用稀疏更新;可用 `nalgebra` 或手写,**不**捆绑外部量子云。
|
||||
|
||||
---
|
||||
|
||||
## 7. view 模式支持(专项)
|
||||
|
||||
对齐 [view.md](view.md) 与 math 作图:**Structure / Execution / Source 共用渲染**;禁止第二套皮肤。
|
||||
|
||||
### 7.1 Structure(结构区)
|
||||
|
||||
| 源形态 | 展示 |
|
||||
|--------|------|
|
||||
| `` `qc` = `` + 电路表 | **circuit-card**:比特数、门序列时间线(文本/紧凑 SVG) |
|
||||
| `` `G` = `` + `$$` 门矩阵 | 沿用 **formula-card**(KaTeX);徽章可标 `gate`(若绑定来自 quantum.gate) |
|
||||
| 方法链语句 | 普通调用行;不强制每步展开 |
|
||||
|
||||
### 7.2 Execution(执行区)
|
||||
|
||||
| 产物 | 展示 |
|
||||
|------|------|
|
||||
| `quantum_svg` | 与 math `plots` 同级:**内嵌 SVG**(电路轨线图 / 概率直方图 / 单比特布洛赫) |
|
||||
| `probabilities` / `counts` | 表格 + 可选自动条形 SVG |
|
||||
| `quantum_state` | 默认折叠振幅表;小 n(≤3)可并排显示基矢 |
|
||||
|
||||
### 7.3 产物如何进入 view(实现锁定)
|
||||
|
||||
插件**不能**直接碰核心 `HostContext.plots`。采用其一(实现时二选一,优先 A):
|
||||
|
||||
| 方案 | 做法 |
|
||||
|------|------|
|
||||
| **A(推荐)** | ABI `host_query("record_plot")`:参数 JSON `{svg}`;写入与 math 相同的 plots 列表([ext-abi.md](ext-abi.md) allowlist 增补一条) |
|
||||
| **B** | 仅返回 `quantum_svg`;view 在渲染执行值时识别 `_type`/`svg` 字段并内嵌(不扩 ABI) |
|
||||
|
||||
CLI:`draw path=bell.svg` 写沙箱文件;无 path 时不把整段 SVG 灌 stdout(同 math §5)。
|
||||
|
||||
### 7.4 可视化内容(v1 必须 / 可后)
|
||||
|
||||
| 图 | v1 | 说明 |
|
||||
|----|----|------|
|
||||
| 电路轨线(qubit 线 + 门盒 + 控点) | **必须** | `circuit.draw` |
|
||||
| 测量概率条形图 | **必须** | `probabilities` / `run` 后可 `draw kind=probs` |
|
||||
| 单比特布洛赫球(SVG) | 应有 | 仅 n=1 或指定 qubit 约化(纯态投影) |
|
||||
| 门矩阵热力图 | **必须** | `gate.draw kind=matrix`(幅值热图 + 小数标注) |
|
||||
| 交互拖拽编辑电路 | **不做** | 静态文档足够 |
|
||||
|
||||
视觉:内联 CSS;**无外链**字体/CDN(同 view 硬规则)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分期(开发计划)
|
||||
|
||||
```text
|
||||
Q0 脚手架:CATALOG + plugins/quantum Hello + L1 ensure_plugin
|
||||
Q1 态向量 + I/X/H/CX + simulate/probabilities;贝尔态 gold
|
||||
Q2 Y/Z/S/T/Rx/Ry/Rz/CZ/SWAP + run(seed) + 中英 API 对齐
|
||||
Q3 电路表 steps= + draw 电路 SVG + view record_plot/识别;examples/
|
||||
Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-quantum-q5.md) ← **done(最小)**
|
||||
```
|
||||
|
||||
| 阶段 | 交付物 | 验收 |
|
||||
|------|--------|------|
|
||||
| **Q0** | `marqdo_plugin_quantum` 注册 `quantum_ping`;L1 加载失败可读 | `ext add quantum` 路径通 |
|
||||
| **Q1** | 贝尔态 `probabilities` ≈ 0.5/0.5 | `tests/ext/quantum-bell-smoke.mq.md` |
|
||||
| **Q2** | 旋转门 + `run seed=` 计数稳定 | 中英双金样 |
|
||||
| **Q3** | `steps=` 表;`draw` SVG 在 `view` HTML 含 `<svg` | 与 math-plot 同级断言 |
|
||||
| **Q4** | 概率图 + 布洛赫;`matches_matrix`;用户文档页 | `quantum-draw-smoke` / `quantum-gate-matrix-smoke`;`view output` 可浏览示例 |
|
||||
| **Q5** | `noise` 轨迹;`barrier`/`measure`/`append`/`state` | `quantum-noise-smoke` / `quantum-author-api-smoke` |
|
||||
|
||||
实现路线图跟踪见 [roadmap/ext-quantum.md](../roadmap/ext-quantum.md)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 规范示例(目标作者体验)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Bell state
|
||||
> ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# Bell |Φ+⟩
|
||||
|
||||
H on qubit 0, then CNOT. Expect |00⟩ and |11⟩ each with probability 1/2.
|
||||
|
||||
# main
|
||||
|
||||
`steps` =
|
||||
|
||||
| step | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
|
||||
*`p` = > `qc`.probabilities *
|
||||
*`svg` = > `qc`.draw *
|
||||
|
||||
> print text=`p`
|
||||
```
|
||||
|
||||
中文面对称:`量子.电路`、`哈达玛`、`控非`、`概率`、`绘图`。
|
||||
|
||||
---
|
||||
|
||||
## 10. 刻意不做(本 Accepted 范围)
|
||||
|
||||
- 真机 / 云后端(IBM、Braket…)
|
||||
- 开放系统、完整噪声模型(可 Q5+)
|
||||
- 符号电路编译优化器
|
||||
- 交互式电路编辑器
|
||||
- 把量子并入 `lib/math` 或核心 opcode
|
||||
- 无上限比特的「生产级」模拟
|
||||
|
||||
---
|
||||
|
||||
## 11. 开放点(已收敛 / 剩余)
|
||||
|
||||
| 议题 | 结论 |
|
||||
|------|------|
|
||||
| 对象面 vs 自由函数 | **主推对象/方法链**;自由函数不平行提供 |
|
||||
| 电路表 | **v1 纳入**(Q3),与方法链等价 |
|
||||
| 振幅过大 | v1 全进 Value;n≤12 可接受;超限已挡 |
|
||||
| view 产物 | **优先** `host_query("record_plot")` |
|
||||
| 与 web | **不依赖** web 做可视化;SVG 自绘 |
|
||||
|
||||
---
|
||||
|
||||
## 12. 评审清单
|
||||
|
||||
1. ABI-only + 中英分文件是否认可?
|
||||
2. 默认 12 qubits 上限是否合适?
|
||||
3. 电路表列设计(步/门/比特/参数)是否够用?
|
||||
4. view:电路轨线 + 概率条为 v1 必须,是否同意?
|
||||
5. `$$` 矩阵核对放 Q4,是否同意先表驱动?
|
||||
|
||||
评审通过后:本文冻结为 Accepted → 按 §8 从 Q0 实现。
|
||||
|
||||
---
|
||||
|
||||
## 13. 一句话
|
||||
|
||||
**表格写出电路,类方法模拟与绘图;跑通金样即证明文档中的量子公式与步骤成立——math 管曲线,quantum 管希尔伯特空间上的可执行说明书。**
|
||||
@@ -0,0 +1,600 @@
|
||||
# 官方扩展:`ext/web` 动态网站
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 完成**(SQLite 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / `app.static`;Postgres 等见 §9) |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) |
|
||||
| 安装(目标) | `marqdo ext add web`(中英:`web` / `网页`) |
|
||||
| 本文目的 | 锁定**作者面**与**类 API**;指导实现 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
`ext/web` 用 **GFM 表格 + Marqdo 类方法** 描述动态网站:表仍是字典/列表嵌套;类方法把表装配成可渲染页面。
|
||||
**不改 Marqdo 核心语法**;扩展库存在的理由,正是让「文档即代码」在网站场景下成立。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何要做网络扩展库
|
||||
|
||||
### 1.1 问题
|
||||
|
||||
若没有专用扩展,作者只能:
|
||||
|
||||
- 手写 JSON 袋、`json.set` 拼装组件/样式;或
|
||||
- 要求改语言(让表格单元格求值、点号取值等)。
|
||||
|
||||
二者都破坏 Marqdo 的「代码即文档」。
|
||||
|
||||
### 1.2 答案
|
||||
|
||||
在 **`ext/web/web.mq.md`(英文)** 与 **`ext/web/网页.mq.md`(中文)** 中各提供一套 **`#` 类**:
|
||||
|
||||
- 作者只写**表** + **少量实例方法调用**;
|
||||
- 表单元格保持**字面量**;
|
||||
- **寻址字符串**由类方法解析;
|
||||
- **导入英文文件 → 只用英文 API;导入中文文件 → 只用中文 API**(见 [stdlib-i18n.md](stdlib-i18n.md))。
|
||||
|
||||
### 1.3 硬约束(评审锁定)
|
||||
|
||||
| # | 约束 |
|
||||
|---|------|
|
||||
| C1 | **禁止**为 web 改动 Marqdo 核心:单元格求值、import、点号值读取等保持不变 |
|
||||
| C2 | 作者面**禁止** `json.parse` / `json.set` 袋胶水、手写 part JSON、手写 assemble 袋 |
|
||||
| C3 | 能力以 **`#` 类 + `##` 方法** 暴露;**英文库文件只用英文名,中文库文件只用中文名**(见 [stdlib-i18n.md](stdlib-i18n.md));同一 `.mq.md` 内禁止中英 API 混排 |
|
||||
| C4 | 首页在 **`index.mq.md`**:页面表在此;可复用片段进 `components/`;主体可就地写 |
|
||||
| C5 | **旧有网络扩展库全部废弃**:`plugins/web`、`ext/web/**`(含现网示例/gold 中依赖旧 API 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进 |
|
||||
| C6 | `# db` / `# 数据库` 必须提供完整**增删改查**;列表查询英文方法名为 **`select`**(中文 **`查询`**);后台 `/admin` 与表单提交走同一套写库 API |
|
||||
| C7 | 用户输入经 `# form` / `# 表单`:字段表 + 校验表;**服务端校验必须在写库前执行**(见 §5.5) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者心智与目录
|
||||
|
||||
```text
|
||||
myapp/
|
||||
index.mq.md # 入口 + 首页:页面表 +(可选)就地主体表 + 类方法 + listen
|
||||
pages/ # 子页:同形的页面表(导出布局表或由入口再装配)
|
||||
components/ # 可复用组件:导出与路径同名的 ##,体为 |属性|值|样式|
|
||||
styles/ # 样式模块:每个样式一个 ##,体为 |属性|值|
|
||||
db/ # 库:schema 表 +(可选)open/种子
|
||||
data/ # sqlite 等运行时数据(gitignore)
|
||||
```
|
||||
|
||||
| 表种 | 列 | 一句话 |
|
||||
|------|-----|--------|
|
||||
| **页面表** | `组件` \| `样式` | 本页用哪些组件、各套哪套样式 |
|
||||
| **组件 / 主体表** | `属性` \| `值` \| `样式` | 前端属性 ↔ 取值(库字段或字面量)↔ 样式名 |
|
||||
| **样式表** | `属性` \| `值` | CSS 声明 |
|
||||
| **库结构表** | `字段` \| `类型` \| `可空` | schema |
|
||||
|
||||
---
|
||||
|
||||
## 3. 表内寻址约定(单元格仍是字符串)
|
||||
|
||||
单元格**不求值**。下列写法是 **web 扩展约定的路径文本**,由 `# 页面` / `# 样式` / `# 数据库` 的方法解析。
|
||||
|
||||
### 3.1 反引号与裸名
|
||||
|
||||
| 含义 | 写法 | 例 |
|
||||
|------|------|-----|
|
||||
| 要「去导入树 / 定义里解析」的名字 | 反引号 `` `名` `` | `` `nav` ``、`` `title` ``、`` `topnav` ``、`` `articles` ``(表名) |
|
||||
| 字面量(文案、URL、CSS 属性名/值、SQL 类型、**列名**) | **裸**或 `"…"` | `首页`、`/about`、`font-size`、`integer`、`title`(作为列名时) |
|
||||
|
||||
### 3.2 路径形态(锁定)
|
||||
|
||||
| 场景 | 形态 | 例 | 方法内语义 |
|
||||
|------|------|-----|------------|
|
||||
| 引用导入模块的导出 | `模块.`导出`` | `nav.`nav``、`shell.`topnav`` | 在**站点入口模块**的 import 树上调用 `模块.导出`(零参 `##`),取回表 Value |
|
||||
| 引用库字段 | `模块.`表`.列` | `articles.`articles`.title` | 模块名 = 命名空间(对应导入的 db 文件);`` `表` `` = 库表名;**列名裸写**(列不是变量)→ 运行时绑定 `表.列` |
|
||||
| 前端属性名 | `` `title` `` | 组件表「属性」列 | 解析为字段名 `title` |
|
||||
| 样式引用 | 同「模块.导出」或纯样式名 | `shell.`card-title`` | 取回 `|属性|值|` 表并编译为 CSS 类 |
|
||||
|
||||
**刻意不做的事:**
|
||||
|
||||
- 不把「组件变量名」魔法等同于「库表名」;
|
||||
- 不要求作者写 `json.set` 才能把 `nav` 放进袋;
|
||||
- 不把 `articles.`articles`.title` 做成语言级表达式。
|
||||
|
||||
### 3.3 与模块命名空间的关系
|
||||
|
||||
- 库名来自 frontmatter 导入(茎名或 `as`),**裸名**,见 [module-namespace.md](module-namespace.md)。
|
||||
- `nav.`nav`` 中:前段 `nav` = 导入库名;`` `nav` `` = 该库上的 `## nav` 导出。
|
||||
- 组件/样式文件应导出 **与路径第二段同名的 `##`**,直接返回表(不要 `## bag` / `## bind` 袋)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 规范示例:`index.mq.md`(作者面唯一样板)
|
||||
|
||||
**语言与导入绑定(锁定,纠正手写混用):**
|
||||
|
||||
| 导入 | 库名(默认茎) | 类 / 方法 / 形参 |
|
||||
|------|----------------|------------------|
|
||||
| `> ext/web/web.mq.md` | `web` | **仅英文**:`page` · `compose_components` · `db` · `app` · `components=` … |
|
||||
| `> ext/web/网页.mq.md` | `网页` | **仅中文**:`页面` · `组件装配` · `数据库` · `应用` · `组件=` … |
|
||||
|
||||
禁止:`> ext/web/web.mq.md` 后写 `web.页面` / `` `页`.组件装配 ``(英文库混中文成员)。
|
||||
禁止:在 `web.mq.md` 文件内定义中文 `## 组件装配` 别名。中英对等靠**两个文件**,不靠同一文件双份导出。
|
||||
|
||||
### 4.1 英文面(导入 `web.mq.md`)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: web-site
|
||||
description: Home = page table; main may be inline; class methods assemble.
|
||||
> ext/web/web.mq.md
|
||||
> styles/shell.mq.md
|
||||
> components/nav.mq.md
|
||||
> components/side.mq.md
|
||||
> components/foot.mq.md
|
||||
> db/articles.mq.md
|
||||
> db/index.mq.md as db
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`home` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`nav` | shell.`topnav` |
|
||||
| side.`side` | shell.`side-panel` |
|
||||
| foot.`foot` | |
|
||||
|
||||
Main content is not a reusable component, so it is authored here.
|
||||
|
||||
`index` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| `title` | articles.`articles`.title | shell.`card-title` |
|
||||
| `body` | articles.`articles`.body | shell.`card-body` |
|
||||
|
||||
*`store` = > db.open *
|
||||
*`page` = > web.page title="Marqdo Web Site" intro="<h1>Web Site</h1>" *
|
||||
*`page` = > `page`.compose_components components=`home` *
|
||||
*`page` = > `page`.compose_main main=`index` *
|
||||
*`app` = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
|
||||
> `app`.listen
|
||||
```
|
||||
|
||||
说明:表头列名可用中文(`组件`/`样式`/`属性`/`值`)——那是**表约定词汇**,不是库成员名;库成员必须与导入语言一致。
|
||||
|
||||
### 4.2 中文面(导入 `网页.mq.md`)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 站点
|
||||
> ext/web/网页.mq.md
|
||||
> styles/shell.mq.md
|
||||
> components/nav.mq.md
|
||||
> components/side.mq.md
|
||||
> components/foot.mq.md
|
||||
> db/articles.mq.md
|
||||
> db/index.mq.md as db
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`首页` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`nav` | shell.`topnav` |
|
||||
| side.`side` | shell.`side-panel` |
|
||||
| foot.`foot` | |
|
||||
|
||||
主体不是可复用组件,因此就地撰写。
|
||||
|
||||
`index` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| `title` | articles.`articles`.title | shell.`card-title` |
|
||||
| `body` | articles.`articles`.body | shell.`card-body` |
|
||||
|
||||
*`库` = > db.open *
|
||||
*`页` = > 网页.页面 标题="站点" 引言="<h1>站点</h1>" *
|
||||
*`页` = > `页`.组件装配 组件=`首页` *
|
||||
*`页` = > `页`.主体装配 主体=`index` *
|
||||
*`应用` = > 网页.应用 页面=`页` 数据库=`库` 后台=True 主机=127.0.0.1 端口=18081 *
|
||||
> `应用`.监听
|
||||
```
|
||||
|
||||
**允许出现在 index 的非表内容:** frontmatter 导入、开库一行、构造页面/应用并装配、`listen` / `监听`。
|
||||
**不允许:** `json.*` 袋、手写 `/_part` 注册、中英 API 混用。
|
||||
|
||||
---
|
||||
|
||||
## 5. 类 API(分文件 · 分语言)
|
||||
|
||||
依据 [stdlib-i18n.md](stdlib-i18n.md):**导入哪个文件,就用哪套名字。**
|
||||
`ext/web/web.mq.md` = 全英文;`ext/web/网页.mq.md` = 全中文。中文实现可委托插件同一套原语,或薄封装英文库,但**对外导出的 `#` / `##` / 形参名必须是中文**。
|
||||
|
||||
### 5.1 页面 · `page` / `页面`
|
||||
|
||||
**英文(`web.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# page
|
||||
+ `title`=…
|
||||
+ `intro`=…
|
||||
|
||||
## compose_components
|
||||
+ `components` # page table |组件|样式|
|
||||
|
||||
## compose_main
|
||||
+ `main` # bind table |属性|值|样式|
|
||||
```
|
||||
|
||||
**中文(`网页.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# 页面
|
||||
+ `标题`=…
|
||||
+ `引言`=…
|
||||
|
||||
## 组件装配
|
||||
+ `组件`
|
||||
|
||||
## 主体装配
|
||||
+ `主体`
|
||||
```
|
||||
|
||||
| 行为 | 说明 |
|
||||
|------|------|
|
||||
| compose_components / 组件装配 | 解析组件·样式路径 → 填 nav/sidebar/footer → CSS → 登记 part |
|
||||
| compose_main / 主体装配 | 解析库字段与样式路径 → 填 main → 登记 part(如 id=`index`) |
|
||||
|
||||
**槽位推断:** 由组件导出名决定(`nav`→顶栏,`side`→侧栏,`foot`→底栏;其余→main)。
|
||||
|
||||
### 5.2 样式 · `style` / `样式`
|
||||
|
||||
**英文:** `# style` · `## process` · `+ style=` / `name=` / `path=`
|
||||
**中文:** `# 样式` · `## 样式处理` · `+ 样式=` / `名=` / `路径=`
|
||||
|
||||
页面装配可内部调用;作者一般不必在 index 显式调。
|
||||
|
||||
### 5.3 数据库 · `db` / `数据库`
|
||||
|
||||
完整**增删改查**;页面绑定、种子、`/admin`、表单提交共用。
|
||||
|
||||
**英文(`web.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# db
|
||||
+ `url`=…
|
||||
|
||||
## init
|
||||
+ `name`
|
||||
+ `fields` # or table= schema
|
||||
|
||||
## insert
|
||||
+ `table`
|
||||
+ `rows`
|
||||
|
||||
## select
|
||||
+ `table`
|
||||
+ `where`=None # optional simple filters
|
||||
+ `limit`=200
|
||||
|
||||
## get
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
## update
|
||||
+ `table`
|
||||
+ `id`
|
||||
+ `row`
|
||||
|
||||
## delete
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
## exec
|
||||
+ `sql`
|
||||
+ `args`=None # escape hatch: raw SQL (not everyday authoring)
|
||||
```
|
||||
|
||||
**中文(`网页.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# 数据库
|
||||
+ `地址`=…
|
||||
|
||||
## 初始化
|
||||
+ `数据库表` # 或 名= + 字段=
|
||||
|
||||
## 插入
|
||||
+ `表`
|
||||
+ `行` # 或 多行=
|
||||
|
||||
## 查询
|
||||
+ `表`
|
||||
+ `条件`=None
|
||||
+ `上限`=200
|
||||
|
||||
## 获取
|
||||
+ `表`
|
||||
+ `id`
|
||||
|
||||
## 更新
|
||||
+ `表`
|
||||
+ `id`
|
||||
+ `行`
|
||||
|
||||
## 删除
|
||||
+ `表`
|
||||
+ `id`
|
||||
|
||||
## 执行
|
||||
+ `sql`
|
||||
+ `参数`=None
|
||||
```
|
||||
|
||||
| 中文 | 英文 | 职责 |
|
||||
|------|------|------|
|
||||
| 初始化 | `init` | 建表;登记表名 |
|
||||
| 插入 | `insert` | 增 |
|
||||
| 查询 | `select` | 查列表(可带简单条件 / limit) |
|
||||
| 获取 | `get` | 按主键一行 |
|
||||
| 更新 | `update` | 改 |
|
||||
| 删除 | `delete` | 删 |
|
||||
| 执行 | `exec` | 可选原始 SQL(进阶) |
|
||||
|
||||
`table=` / `表=` 接受表名或句柄;行数据优先 GFM 表。
|
||||
**命名锁定:** 列表查询用 `select` / `查询`,**不用** `all`;原始 SQL 用 `exec` / `执行`,避免与 `select` 混淆。
|
||||
|
||||
### 5.4 应用 · `app` / `应用`
|
||||
|
||||
**英文:** `# app` · `## route` · `## static` · `## listen` · 形参 `page` `db` `admin` `host` `port`
|
||||
**中文:** `# 应用` · `## 路由` · `## 静态` · `## 监听` · 形参 `页面` `数据库` `后台` `主机` `端口`
|
||||
|
||||
`listen` / `监听`:加载插件、注入 `db_url`、按页面 part 提供 `/_part/{id}`(首页)与 `{path}/_part/{id}`(`app.route` 页)、可选 `static` 目录挂载、启动 HTTP。作者不必手写 part 注册。
|
||||
|
||||
`static` / `静态`:`dir=`(或 `目录=`)+ 可选 `mount=`(默认 `/static`);`listen` 时用 `tower-http` 提供只读文件服务。
|
||||
|
||||
### 5.5 表单 · `form` / `表单`(规划锁定)
|
||||
|
||||
用户输入也走「表 + 类方法」,与页面/库同一心智;**提交最终调用 `# db` 的 insert/update**,不另开旁路。
|
||||
|
||||
**英文(`web.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# form
|
||||
+ `table`=None # bound db table name (optional until submit)
|
||||
+ `action`=insert # insert | update
|
||||
+ `id`=None # required when action=update
|
||||
|
||||
## fields
|
||||
+ `fields` # |字段|标签|类型|必填|默认|…
|
||||
|
||||
## validate
|
||||
+ `rules`=None # |字段|规则|消息|… (optional extra rules)
|
||||
+ `data` # submitted row / map
|
||||
|
||||
## render
|
||||
# → HTML form (or form descriptor for page slot)
|
||||
|
||||
## submit
|
||||
+ `data`
|
||||
+ `db` # db handle
|
||||
```
|
||||
|
||||
**中文(`网页.mq.md`):**
|
||||
|
||||
```markdown
|
||||
# 表单
|
||||
+ `表`=None
|
||||
+ `动作`=插入 # 插入 | 更新
|
||||
+ `id`=None
|
||||
|
||||
## 字段
|
||||
+ `字段`
|
||||
|
||||
## 校验
|
||||
+ `规则`=None
|
||||
+ `数据`
|
||||
|
||||
## 渲染
|
||||
|
||||
## 提交
|
||||
+ `数据`
|
||||
+ `数据库`
|
||||
```
|
||||
|
||||
#### 5.5.1 字段表(作者面)
|
||||
|
||||
```markdown
|
||||
`文章表单` =
|
||||
|
||||
| 字段 | 标签 | 类型 | 必填 | 默认 |
|
||||
|------|------|------|------|------|
|
||||
| title | 标题 | text | true | |
|
||||
| body | 正文 | textarea | false | |
|
||||
```
|
||||
|
||||
| 列 | 含义 |
|
||||
|----|------|
|
||||
| `字段` | 对应库列名(裸名或 `` `列` ``,与 schema 对齐) |
|
||||
| `标签` | 展示文案(字面量) |
|
||||
| `类型` | 控件/值类型:`text` `textarea` `number` `email` `url` `checkbox` `select` … |
|
||||
| `必填` | 是否必填 |
|
||||
| `默认` | 可选默认值 |
|
||||
|
||||
#### 5.5.2 校验表(作者面)
|
||||
|
||||
```markdown
|
||||
`文章校验` =
|
||||
|
||||
| 字段 | 规则 | 消息 |
|
||||
|------|------|------|
|
||||
| title | required | 标题不能为空 |
|
||||
| title | max:120 | 标题过长 |
|
||||
| body | max:8000 | 正文过长 |
|
||||
```
|
||||
|
||||
| 规则(初版) | 含义 |
|
||||
|--------------|------|
|
||||
| `required` | 非空 |
|
||||
| `min:N` / `max:N` | 字符串长度或数值范围 |
|
||||
| `email` / `url` | 格式 |
|
||||
| `match:字段` | 与另一字段相等(如确认密码) |
|
||||
| `in:a,b,c` | 枚举 |
|
||||
|
||||
schema 上的「可空 / 类型」在 **submit 时自动并入校验**(不必重复写 `required`,但校验表可覆盖消息)。
|
||||
|
||||
#### 5.5.3 行为流程
|
||||
|
||||
```text
|
||||
render → 按字段表出 HTML(或嵌入 page 主区)
|
||||
用户填写 → POST /_form/{id} 或同页提交
|
||||
validate → 合并 schema + 校验表;失败则带回字段级错误、不写库
|
||||
submit → action=insert → db.insert;action=update → db.update
|
||||
→ 成功后刷新槽位或跳转(由 form 选项约定)
|
||||
```
|
||||
|
||||
| 层 | 校验 |
|
||||
|----|------|
|
||||
| **服务端(必须)** | `validate` 在写库前执行;唯一可信边界 |
|
||||
| **浏览器(可选增强)** | 同源规则可生成 `required`/`maxlength` 等 HTML 属性;**不能**替代服务端 |
|
||||
|
||||
`/admin` 的新建/编辑页 = 内置 form:字段来自 schema,校验来自类型/可空;与站点自定义 form **同一套** `validate` + `db.insert`/`update`。
|
||||
|
||||
#### 5.5.4 与页面的关系
|
||||
|
||||
- 表单可以是独立路由页,或页面表里的一个「组件」导出(仍用 `|属性|值|样式|` 描述展示,提交走 form 类)。
|
||||
- **`page.compose_form id=… form=…`**:把 form 嵌入该页主区;`listen` 从首页与路由页收集表单并挂载 `/_form/{id}`(`app.mount_form` 仍可用)。校验失败时若表单有所属页,则带回该页壳重渲染。
|
||||
|
||||
### 5.6 文件职责
|
||||
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| `ext/web/web.mq.md` | 英文 `# page` `# style` `# db` `# form` `# app` |
|
||||
| `ext/web/网页.mq.md` | 中文 `# 页面` `# 样式` `# 数据库` `# 表单` `# 应用`(可包装英文实现,**不得**把中文名写进 `web.mq.md`) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 模块导出形状(配合寻址)
|
||||
|
||||
### 6.1 组件 `components/nav.mq.md`
|
||||
|
||||
```markdown
|
||||
## nav
|
||||
|
||||
`nav` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| `title` | `nav`.`title` | |
|
||||
| `href` | `nav`.`href` | |
|
||||
|
||||
**`nav`**
|
||||
```
|
||||
|
||||
说明:组件**内部**绑定仍可用 `` `表`.`列` ``(表名+列名皆引用)。与 index 主体里「模块命名空间 + 裸列名」的 `articles.`articles`.title` 分工:
|
||||
|
||||
- **跨文件、带导入命名空间** → `模块.`表`.列`;
|
||||
- **组件文件内、表已明确** → `` `表`.`列` `` 即可。
|
||||
|
||||
(若评审希望全站统一为一种形态,可在评审意见中二选一;默认允许上述两种。)
|
||||
|
||||
### 6.2 样式 `styles/shell.mq.md`
|
||||
|
||||
每个样式一个 `##`,**禁止** `## bag` + `json.set`:
|
||||
|
||||
```markdown
|
||||
## topnav
|
||||
… |属性|值| …
|
||||
**`topnav`**
|
||||
|
||||
## card-title
|
||||
…
|
||||
```
|
||||
|
||||
### 6.3 库 `db/articles.mq.md` / `db/index.mq.md`
|
||||
|
||||
- `articles`:`## schema`(或同名导出)返回结构表;
|
||||
- `index`:`## open` → 确保插件、建库、init、幂等种子,返回 `# 数据库` 句柄。
|
||||
|
||||
---
|
||||
|
||||
## 7. 运行时职责划分
|
||||
|
||||
```text
|
||||
作者 .mq.md 表(字面量单元格)
|
||||
│
|
||||
▼
|
||||
ext/web 类方法(Marqdo)
|
||||
│ 解析路径;需要时经 ABI host_query
|
||||
│ 调用入口模块 import 树上的 lib.member
|
||||
▼
|
||||
plugins/web(HTTP / SQL / HTML 壳)
|
||||
│
|
||||
▼
|
||||
浏览器:四区布局 + /_part 局部刷新 + /admin(可选)
|
||||
```
|
||||
|
||||
| 层 | 做 | 不做 |
|
||||
|----|----|------|
|
||||
| Marqdo 核心 | 表→Value、类/方法、import | 不识别 web 路径语法 |
|
||||
| `ext/web/*.mq.md` | 作者 API、中英面、委托插件 | 不直接 `host_*` |
|
||||
| `plugins/web` | 路径解析辅助、装配结果、listen、SQL、渲染 | 不要求作者写袋 |
|
||||
|
||||
**实现要点(评审通过后再做):**
|
||||
|
||||
1. ABI `host_query("call_lib_path")`:在**站点入口模块**上执行 `lib.member`;
|
||||
2. 插件函数由类方法调用(如 compose_components / compose_main);
|
||||
3. `listen` 合并页面内 part,注入 `db_url`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 全部废弃 · 从头开发(锁定)
|
||||
|
||||
**旧有网络扩展库内容一律作废**,包括但不限于:
|
||||
|
||||
| 范围 | 处理 |
|
||||
|------|------|
|
||||
| [`plugins/web/`](../../plugins/web/) | 评审通过后**删除或清空**,按本文重写 cdylib |
|
||||
| [`ext/web/`](../../ext/web/)(`web.mq.md` / `网页.mq.md` / templates) | 同上,**不**在旧 L1 上打补丁 |
|
||||
| 依赖旧 API 的示例(如当前 `examples/web-site`、`web-demo`、`man-write-site` 可跑胶水版) | 按 §4 规范重写或暂时移除 |
|
||||
| 依赖旧 API 的 gold / 单测 | 删除后按新 API 重写 |
|
||||
| 本文之前的袋式 / assemble / wire / `## bag` 等作者面 | 永久移出正典 |
|
||||
|
||||
**禁止**:在遗留代码上「修到能跑」再文档化。
|
||||
**允许**:实现时参考旧代码中的 HTTP/SQLite 技术经验,但**新树另起**,不以 ABI 表面或作者面兼容为目标。
|
||||
|
||||
历史摸索中明确不再回归的作者面模式:
|
||||
|
||||
- `json.parse` / `json.set` 拼 components/styles 袋;
|
||||
- 手写 `web.assemble` + 袋参数;
|
||||
- 手写 part JSON + `` `app`.part ``;
|
||||
- `|前端变量|后端数据库|` 填路由;
|
||||
- 「变量名即表名」魔法默认表;
|
||||
- 样式 `## bag`;掏空 index 只留 `wire.boot`。
|
||||
|
||||
---
|
||||
|
||||
## 9. 非本波次(可记入路线图)
|
||||
|
||||
- Postgres / Redis / S3 驱动细节(SQLite 已落地);
|
||||
- 复杂权限与多租户;
|
||||
- 子页路由糖的更多约定(`# 应用.route` 已够用)。
|
||||
|
||||
---
|
||||
|
||||
## 10. 评审清单
|
||||
|
||||
请确认或批注:
|
||||
|
||||
1. **§3 路径**:`模块.`导出`` 与 `模块.`表`.列`(列裸名)是否定为唯一正典?组件内 `` `表`.`列` `` 是否保留?
|
||||
2. **§4 index**:开库是否允许单独一行 `` db.open ``,还是必须进一步藏进 `web.应用`?
|
||||
3. **§5 分文件**:英文 `web.mq.md` / 中文 `网页.mq.md` 是否严格分语言、禁止混排?
|
||||
4. **§5.3**:列表查询用 `select` / `查询`、原始 SQL 用 `exec` / `执行` 是否认可?
|
||||
5. **§5.5 表单/校验**:字段表、校验表、服务端必校、admin 共用是否认可?
|
||||
6. **§5 槽位**:仅由组件导出名推断,是否足够?
|
||||
7. **§8 废弃**:是否确认**全部推倒重来**、不兼容旧实现?
|
||||
|
||||
评审通过后:冻结本文为 Accepted → **清空旧 web 扩展代码** → 按本文从零实现(骨架 → db CRUD/`select` → form/validate → 页面装配 → app listen → 规范示例 → gold)。
|
||||
@@ -4,9 +4,9 @@
|
||||
|---|---|
|
||||
| 状态 | 草案(已采纳方向;修正「配置文件」误解) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) |
|
||||
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) · **实现规范 [okf.md](okf.md)** |
|
||||
| 取代 | 此前「YAML = 人手写的编译器配置 / frontmatter 契约」的表述 |
|
||||
|
||||
| 说明 | 原则仍有效;**类型表、任务知识包、路线图以 [okf.md](okf.md) 为准** |
|
||||
---
|
||||
|
||||
## 决策
|
||||
|
||||
@@ -36,7 +36,7 @@ L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英
|
||||
|
||||
### 3.1 字面量 / 逻辑关键字(词法保留)
|
||||
|
||||
控制流仍靠 Markdown(`#` `+` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。
|
||||
控制流仍靠 Markdown(`#` `1.` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。形参用 `+`。
|
||||
|
||||
| 英文 | 中文(提案) | 备注 |
|
||||
|------|--------------|------|
|
||||
@@ -107,7 +107,7 @@ L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英
|
||||
|
||||
- 旧文「中文 `print` 废弃、统一为 `print`」:**废止**;改为正式双名 `print` / `打印`。
|
||||
- [keywords.md](keywords.md) 原则条「英文标识」改为「**内核双名;标准库分文件**」——实现阶段改正文。
|
||||
- 不引入中文控制流关键字(`如果`/`循环` 等);分支循环仍用 `+` / `-`。
|
||||
- 不引入中文控制流关键字(`如果`/`循环` 等);分支用 `1.` …,循环用 `-`。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
|
||||
## 1. 设计原则
|
||||
|
||||
1. **标记承担架构**:函数=`#`,分支=`+`,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
1. **标记承担架构**:函数=`#`,**形参=`+`**,**分支=`1.`…**,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
2. **内核双名**:字面量 / 逻辑词 / 五个核心内置函数均有中英别名,**无需导入**,可混用。
|
||||
3. **学 Python 的边界**:区分 **关键字** vs **内置函数名**。
|
||||
4. **宁少勿多**:扩展能力进可导入标准库(中英分文件,见 [stdlib-i18n.md](stdlib-i18n.md))。
|
||||
@@ -43,6 +43,8 @@
|
||||
| `str` | `文本` | 转为显示文本 |
|
||||
| `int` | `整数` | 转为整数 |
|
||||
|
||||
**文本**:裸 token 按字面量;需 `\n` 等转义时用 `"..."`(见 [markdown-mapping.md](markdown-mapping.md) §7)。
|
||||
|
||||
形参别名:
|
||||
|
||||
| 英文 | 中文 | 用于 |
|
||||
@@ -71,9 +73,9 @@
|
||||
|
||||
*`n` = 1*
|
||||
|
||||
+ `n` > 0
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
+ *
|
||||
2. *
|
||||
> 打印 内容=other
|
||||
```
|
||||
|
||||
|
||||
+182
-52
@@ -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))。
|
||||
|
||||
@@ -15,8 +15,13 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
1. `.mq.md`:打开即文档,运行即程序。
|
||||
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. 作用域 = `#` 层数;入口 = `index.mq.md`。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
5. **标识符默认反引号**:形参、绑定、引用写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
|
||||
**豁免:**
|
||||
- foreach 头 `` - [项](集合) `` 允许裸名或反引号(可混用),推荐裸名;循环体内引用仍用 `` `名` ``。
|
||||
- 脚注取元 `` 名[^键] ``:基名在紧跟 `` [^…] `` 时可省略反引号(`` `名`[^键] `` 仍合法);链式同理。
|
||||
- **斜体语句 / 粗体返回内部**:裸标识符默认是**变量**;字符串须 `"…"` 或 `'…'`;`` `名` `` 仍合法。
|
||||
|
||||
---
|
||||
|
||||
@@ -29,23 +34,26 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
| 普通文字 / 空 | **注释** |
|
||||
| 标记字符 | **代码** |
|
||||
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §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`) |
|
||||
| frontmatter `> path.mq.md` [`as` / `作为` name] | 导入(绑定库名;默认 = 文件名茎) |
|
||||
| frontmatter `> use lib.member` [`as` name] / `使用` | 将库路径成员绑为本地短名 |
|
||||
| `> lib.member …` / `> lib.Type.member …` | 点号路径调用(路径段裸名、无反引号) |
|
||||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
||||
| `**…**` | **返回值**(架构级;函数结果) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
@@ -55,13 +63,23 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
| ` ```lang ` | 外联异种代码 |
|
||||
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §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)。
|
||||
|
||||
@@ -72,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
|
||||
@@ -98,7 +121,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
### else 与斜体消歧
|
||||
|
||||
- 分支臂**第一行整行只有一个** `*` → else。
|
||||
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
|
||||
- `*中间有内容*` → 程序语句。
|
||||
- `**…**` → 返回(与 else 无关)。
|
||||
|
||||
@@ -106,14 +129,18 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
## 5. Frontmatter 与跨文件
|
||||
|
||||
同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。
|
||||
文件头 `---` 对为元信息。其中 `> file.mq.md` 为**导入**(绑定库名,成员不倒进全局);`> use lib.member` / `> 使用 库.成员` 引入本地短名。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法须 `` > `var`.method ``。详见 [module-namespace.md](module-namespace.md)。
|
||||
|
||||
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 函数、作用域、提升
|
||||
## 6. 对象、函数、形参
|
||||
|
||||
规则同 v0。推荐:
|
||||
- `# Name`:对象(构造体);`# main` 为入口对象。
|
||||
- `# Child = > Parent`:单继承(基类须为已定义对象名;方法沿链查找,子类可覆盖)。见 [objects.md](objects.md) §5。
|
||||
- `##` / `###` …:函数或方法;挂在对象下则为方法。
|
||||
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -121,53 +148,162 @@ 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` | 回车 |
|
||||
| `\\` | `\` |
|
||||
| `\"` | `"` |
|
||||
|
||||
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。
|
||||
|
||||
---
|
||||
|
||||
## 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 个条目」。
|
||||
- 基名:`` `名`[^键] `` 与 `` 名[^键] `` 等价;无 `` [^ `` 时裸词仍是**文本字面量**(不是变量)。
|
||||
- 文末 `[^1]: …` 定义块仍是注释,与取元无关。
|
||||
- foreach:`List` 遍历元素;`Map` 遍历**键**(值用脚注取)。
|
||||
|
||||
---
|
||||
|
||||
@@ -176,21 +312,19 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
|
||||
1. 加载 `index.mq.md` + 导入。
|
||||
2. Pass1 收集定义。
|
||||
3. Pass2 执行 `# main`。
|
||||
4. `*` 语句、`**` 返回、`>` 调用、`+`/`-` 控制流、表绑定按语义执行;`> print` 写 stdout。
|
||||
4. `*` 语句、`**` 返回、`>` 调用、`1.` 分支、`-` 循环、表绑定按语义执行;`> print` 写 stdout。
|
||||
|
||||
---
|
||||
|
||||
## 11. 函数体结束(`---` / `***` / 空返回)
|
||||
|
||||
无返回值(或已写完副作用)的函数,在体末用分割线收束,避免后续同级语句被吞进嵌套函数:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
@@ -199,20 +333,16 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| `---` 或 `***` | 函数体**顶层**单独一行(长度 ≥ 3 且全为 `-` 或全为 `*`)→ **结束本函数**;后续语句属于外层 |
|
||||
| `****` / 空粗体 | 空返回(值为 `None`),并同样结束本函数体 |
|
||||
| 有值 `**expr**` | 普通返回;**不**自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束) |
|
||||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息;与函数体内结束符消歧 |
|
||||
| 分支/循环臂内 | 分割线仍可忽略(噪声),不截断外层函数 |
|
||||
|
||||
曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。
|
||||
| `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** |
|
||||
| `****` / 空粗体 | 空返回(`None`),并结束本函数体 |
|
||||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息 |
|
||||
|
||||
---
|
||||
|
||||
## 12. v0.1 非目标
|
||||
## 12. v0.2 非目标
|
||||
|
||||
- break/continue、完整错误模型、静态类型、完整 FFI
|
||||
- 用 `*` 作无序列表符
|
||||
- `+` 作分支、`+`/`-` 作形参(**不保留**)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,266 @@
|
||||
# 模块命名空间(import / 点号寻址)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted;M1+M2 已落地** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
今日加载器把每个导入文件的顶层 `#` / `##` **扁平合并**进同一全局函数表;同名则**后导入静默覆盖**(`merge_top_level`)。
|
||||
|
||||
后果:
|
||||
|
||||
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存;import 顺序决定谁赢,错误表现为「缺 `pattern`」这类误导信息。
|
||||
- `lib/writeback` 的 `get` 盖住 `lib/json` 的 `get`。
|
||||
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
|
||||
|
||||
**结论**:Marqdo 必须支持**模块命名空间**与**点号寻址**。扁平静默覆盖不是可保留的「兼容糖」,而是会**掩盖冲突**的缺陷行为;本设计予以废除(落地时为破坏性变更,不设双轨裸名回退)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
### 2.1 目标
|
||||
|
||||
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
|
||||
2. **点号寻址调用**:`库.成员`、并预留 `库.对象.成员` 等多段路径;`.` 表示在定义树上的寻址,不是字段运算。
|
||||
3. **库名不是变量**:寻址段为**裸标识符**,**不加**反引号。反引号只用于值槽位(变量 / 形参 / 实例句柄)。
|
||||
4. **模块内名字默认不进全局**;需要本地短名时必须**显式** `use`,且冲突**报错**。
|
||||
5. **中英对等**:路径中英分文件;`as` / `作为` 与默认库名规则双语一致。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
- 第三方包管理 / 版本求解。
|
||||
- 在兼容期内继续支持扁平合并旧语义。
|
||||
- 「裸名仍可从最后一次导入解析」——**明确拒绝**。
|
||||
- 把库名写成 `` `time`.parse ``——**明确拒绝**(会把库名误当成变量)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心语义
|
||||
|
||||
### 3.1 模块 / 库
|
||||
|
||||
每个可导入的 `.mq.md` 文件是一个**库模块**:
|
||||
|
||||
| 内容 | 归属 |
|
||||
|------|------|
|
||||
| 顶层 `##` 自由函数 | 库根下的**函数** |
|
||||
| 顶层 `#` 对象 | 库根下的**类型(对象)** |
|
||||
| 类型下的 `##` 方法 | 该对象节点下的**成员函数**(可被路径寻址;实例调用见 §4.4) |
|
||||
| 被导入文件的 `# main` | **不**作为入口执行 |
|
||||
|
||||
### 3.2 导入句法(frontmatter)
|
||||
|
||||
| 英文 | 中文 | 含义 |
|
||||
|------|------|------|
|
||||
| `> lib/time.mq.md` | `> lib/时间.mq.md` | 导入;默认库名见 §3.3 |
|
||||
| `> lib/time.mq.md as time` | `> lib/时间.mq.md 作为 时间` | 导入并以给定库名绑定 |
|
||||
|
||||
规则:
|
||||
|
||||
- `as` / `作为` 后为**裸库名**(不加反引号)。
|
||||
- 同一文件内两个导入不得绑定同一库名 → 硬错误。
|
||||
- 禁止「只写路径、成员洒进全局」的旧语义。
|
||||
|
||||
### 3.3 默认库名
|
||||
|
||||
省略 `as` / `作为` 时,库名 = **文件名茎**(去掉 `.mq.md`):
|
||||
|
||||
| 路径 | 默认库名 |
|
||||
|------|----------|
|
||||
| `lib/time.mq.md` | `time` |
|
||||
| `lib/时间.mq.md` | `时间` |
|
||||
| `ext/ai/agent.mq.md` | `agent` |
|
||||
| `ext/ai/智能体.mq.md` | `智能体` |
|
||||
|
||||
### 3.4 调用解析顺序
|
||||
|
||||
1. **点号路径 callee**(§4)→ 按段在导入库 / 类型树上寻址。
|
||||
2. **当前文件**顶层 `#` / `##`(无点号的短名)。
|
||||
3. **L0 内置**。
|
||||
4. **插件注册名**(`lib/plugin` 加载后的全局表)。
|
||||
5. 否则 → 未知 callee。
|
||||
|
||||
---
|
||||
|
||||
## 4. 点号寻址(核心外形)
|
||||
|
||||
### 4.1 文法
|
||||
|
||||
```text
|
||||
path_callee ::= ident ('.' ident)+
|
||||
```
|
||||
|
||||
- 每一段都是**裸标识符**(库名、类型名、函数名)。
|
||||
- **整条路径都不使用反引号**。
|
||||
- `.` 只表示寻址分隔,与「变量上的方法调用」分流(§4.4)。
|
||||
|
||||
### 4.2 二段:`库.成员`
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/time.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`t` = > time.now_unix *
|
||||
*`s` = > time.format unix=`t` pattern=%Y-%m-%d *
|
||||
*`obj` = > json.parse text={"a":1} *
|
||||
*`a` = > json.get value=`obj` key=a *
|
||||
> print text=`s`
|
||||
```
|
||||
|
||||
| 路径 | 解析 |
|
||||
|------|------|
|
||||
| `time.now_unix` | 库 `time` → 函数 `now_unix` |
|
||||
| `json.parse` | 库 `json` → 函数 `parse` |
|
||||
| `agent.agent` | 库 `agent` → **类型** `agent`(构造) |
|
||||
|
||||
库根下的函数调用**不**注入 `self` / `自`。
|
||||
|
||||
### 4.3 三段及以上:`库.对象.成员`(预留并锁定语义)
|
||||
|
||||
后续常见形态:
|
||||
|
||||
```markdown
|
||||
> agent.agent # 库 → 类型:构造
|
||||
> 某库.某对象.某函数 # 库 → 类型 → 该类型下的 ## 成员
|
||||
```
|
||||
|
||||
解析规则(锁定):
|
||||
|
||||
1. 第一段必须是**已导入库名**。
|
||||
2. 第二段起在上一段节点的子表中查找:类型节点或函数节点。
|
||||
3. 若最终落在**函数**上则发起调用;若落在**类型**上则发起构造。
|
||||
4. 路径中任一段缺失 → 硬错误(禁止模糊回落到全局短名)。
|
||||
|
||||
实例方法若需要接收者,仍走 §4.4;`库.对象.方法` 表示定义树上的该成员(无接收者时:仅当该成员可作为无 `self` 的关联函数调用,否则报错「需要实例」)。这样 `.` 始终是**定义寻址**,逻辑一致。
|
||||
|
||||
中文库同理:`时间.格式化`、`智能体.智能体`、`智能体.智能体.单步`(若对类型成员做路径调用)。
|
||||
|
||||
### 4.4 变量 / 实例 vs 库路径(反引号分界)
|
||||
|
||||
| 写法 | 左侧重 | 是否反引号 |
|
||||
|------|--------|------------|
|
||||
| `time.parse` | 库名(绑定) | 路径段皆**裸名** |
|
||||
| `agent.agent` | 库名.类型名 | 裸名 |
|
||||
| `` > `助手`.step `` | **变量**(实例句柄) | 接收者**必须**反引号 |
|
||||
| `` > `out`.… `` | 变量 | 反引号 |
|
||||
|
||||
原则:
|
||||
|
||||
- **名在定义/导入空间里** → 点号路径,无 `` ` ` ``。
|
||||
- **名在值环境里**(绑定结果、形参、`self`)→ 反引号标识符;方法调用保持现有 `` > `obj`.method ``。
|
||||
|
||||
禁止混写 `` > `time`.parse ``(把库当成变量)。
|
||||
|
||||
### 4.5 应用侧完整示例
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/time.mq.md
|
||||
> lib/writeback.mq.md
|
||||
> ext/ai/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`助手` = > agent.agent model=… tools=… *
|
||||
*`out` = > `助手`.step task=… *
|
||||
*`body` = > json.stringify value=`out` *
|
||||
> writeback.record value=`body` key=ok
|
||||
```
|
||||
|
||||
(上例假定 `json` 已导入;`stringify` 为该库成员。)
|
||||
|
||||
---
|
||||
|
||||
## 5. 导出面
|
||||
|
||||
默认:库内顶层 `#` / `##` 均可被路径访问。
|
||||
|
||||
类型下的 `##` 挂在该类型节点下,供 `库.类型.成员` 寻址;实例调用仍用 `` `变量`.成员 ``。
|
||||
|
||||
本版不引入 `private`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 显式 `use`(可选短名,非静默兼容)
|
||||
|
||||
| 英文 | 中文 |
|
||||
|------|------|
|
||||
| `> use time.format` | `> 使用 时间.格式化` |
|
||||
| `> use time.format as fmt` | `> 使用 时间.格式化 作为 fmt` |
|
||||
|
||||
- `use` 右侧为**点号路径**(裸名寻址)。
|
||||
- 引入后本地短名可见;与导入库名或当前文件顶层同名 → **硬错误**。
|
||||
- **禁止** `use time.*`(无通配 `use`)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 与旧行为的关系(破坏性变更)
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| 导入 = 合并进全局 | 导入 = 绑定库名 |
|
||||
| 同名后写覆盖 | 无跨库扁平同名 |
|
||||
| `> parse` 来源不明 | 必须 `json.parse` 或显式 `use` |
|
||||
| (若曾设想)`` `time`.parse `` | **否**;库路径不加反引号 |
|
||||
|
||||
不提供扁平合并过渡开关。
|
||||
|
||||
---
|
||||
|
||||
## 8. 对分层与 ext 的影响
|
||||
|
||||
| 层 | 影响 |
|
||||
|----|------|
|
||||
| L0 内置 | 仍为全局短名 |
|
||||
| L1 / 官方 ext | 经库路径调用;**`ext/**/*.mq.md` 严禁 `host_*`** |
|
||||
| ABI 插件 | 插件注册表;agent/OKF 等领域逻辑放这里,**不得**塞进 `HostFn` |
|
||||
|
||||
**硬规则**:不得为「方便」把 `ext/ai` 领域能力写进 `src/host/dispatch.rs` / `src/host/*.rs`。标准库可走 `lib/*` → 薄 `host_*`;智能体专属走 `plugins/agent` 注册名(见 [ext-agent.md](ext-agent.md) §4)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 实现要点
|
||||
|
||||
1. 加载返回模块树(库 → 类型 → 成员);取消跨文件 `merge_top_level` 泼洒。
|
||||
2. 调用方解析 `path_callee`:按 `.` 分段,自导入表下行。
|
||||
3. 区分路径 callee 与 `` `变量`.方法 ``(词法:首段是否反引号 / 是否含裸点号路径)。
|
||||
4. 金样例与 stdlib 文档改为 `time.parse` 形态。
|
||||
|
||||
| 阶段 | 内容 |
|
||||
|------|------|
|
||||
| M0 | 本文 Accepted(含本修订) |
|
||||
| M1 | 二段路径 `库.成员` + 破坏旧扁平 — **已落地**(tree + bytecode;`as`/`作为`;stdlib/ext/tests 已迁) |
|
||||
| M2 | 三段 `库.对象.成员`;`use` / `使用` — **已落地**(实例方法路径调用报错,须 `` `var`.method ``) |
|
||||
| M3 | 诊断工具(可选) |
|
||||
|
||||
**双后端**:tree 与 bytecode 均支持点号路径调用与 `use` / `使用`(与 M1/M2 同语义)。
|
||||
|
||||
**金样例**:
|
||||
|
||||
| 路径 | 测什么 |
|
||||
|------|--------|
|
||||
| `tests/structure/ns/` | 二段/三段路径、`use`、导入 `as` |
|
||||
| `tests/errors/ns-instance-method.mq.md` | `库.类型.方法` 无接收者 → 硬错误(须 `` `var`.method ``) |
|
||||
|
||||
**L1 薄包装**:命名空间下 `net.http_post` 等解析到 **`lib/*.mq.md` 的 `##` 包装**,不是宿主别名。包装未声明的可选形参会被静默丢弃(曾导致 live agent 401:`headers` 未传到 `host_http_post`)。规则见 [stdlib-modules.md](stdlib-modules.md) §2.1。
|
||||
|
||||
---
|
||||
|
||||
## 10. 决议摘要
|
||||
|
||||
1. 导入绑定**库名**;成员不进全局。
|
||||
2. 调用以**裸名点号路径**寻址:`库.成员`,并支持 `库.对象.成员`;`.` = 定义树寻址。
|
||||
3. **库名 / 路径段不加反引号**;反引号只用于值变量与实例接收者。
|
||||
4. 拒绝扁平合并与裸名双轨兼容;短名仅显式单成员 `use`。
|
||||
5. M1/M2 已实现;M3 另开。
|
||||
@@ -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 分管工程目录与自我成长。**
|
||||
@@ -2,8 +2,8 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定(v1)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 状态 | **已落地(v1)** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
|
||||
|
||||
---
|
||||
|
||||
@@ -28,7 +28,7 @@
|
||||
|------|-------------------|
|
||||
| `> lib/text.mq.md` | `trim` · `split` · `join` |
|
||||
| `> lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
|
||||
| `> lib/table.mq.md` | `rows` · `row_at` |
|
||||
| `> lib/table.mq.md` | `put` · `rows` · `row_at` · list/map(见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| `> lib/表.mq.md` | `行数` · `取行` |
|
||||
|
||||
示例:
|
||||
|
||||
+100
-133
@@ -1,32 +1,36 @@
|
||||
# 标准库下一波(L1 扩展模块)
|
||||
# 标准库 L1 模块
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **五库 + 数学已落地**;下一波:**外联**([stdlib-foreign.md](stdlib-foreign.md)) |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 本波范围 | 文件 / 系统 / 时间 / JSON / 网络 / 数学(已完成) |
|
||||
| 下一波 | **外联**(本机解释器 / 具名围栏) |
|
||||
| 暂缓 | — |
|
||||
| 状态 | **已落地**: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) · [keywords-i18n.md](keywords-i18n.md) · [view.md](view.md) |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在现有 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本。标准库**必须导入**才可用。
|
||||
在 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本与可选原生扩展。标准库**必须导入**才可用。
|
||||
|
||||
| 模块族 | 英文库 | 中文库 | 本波 |
|
||||
| 模块族 | 英文库 | 中文库 | 状态 |
|
||||
|--------|--------|--------|------|
|
||||
| 文本(已有) | `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/time.mq.md` | `lib/时间.mq.md` | **做** |
|
||||
| **JSON** | `lib/json.mq.md` | **同文件(特例,§3.4)** | **做** |
|
||||
| **网络(简)** | `lib/net.mq.md` | `lib/网络.mq.md` | **做** |
|
||||
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | **下一波** |
|
||||
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | **做** |
|
||||
| 文本 | `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)。
|
||||
|
||||
---
|
||||
|
||||
@@ -34,35 +38,73 @@
|
||||
|
||||
```text
|
||||
用户 .mq.md
|
||||
│ > lib/fs.mq.md
|
||||
│ > lib/fs.mq.md / > ext/llm.mq.md
|
||||
▼
|
||||
L1 官方库(.mq.md)
|
||||
L1 官方库 / 官方 ext(.mq.md)
|
||||
│
|
||||
▼
|
||||
L0.5 宿主原语(Rust,英文蛇形)
|
||||
L0.5 宿主原语(Rust)或 原生插件(ABI v1)
|
||||
│
|
||||
▼
|
||||
OS / HTTP / 时钟 / …
|
||||
OS / HTTP / 时钟 / 共享库 …
|
||||
```
|
||||
|
||||
| 层 | 谁实现 | 用户是否直接调用 |
|
||||
|----|--------|------------------|
|
||||
| **L0** | 解释器内置 | 是(`print`/`len`/…) |
|
||||
| **L0.5 宿主原语** | Rust(`src/builtin` 或 `src/host/`) | **原则上否**;供 L1 包装;金样例可直测 |
|
||||
| **L1 官方库** | `lib/*.mq.md` | **是**(文档与用户站只教这一层) |
|
||||
| **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 顺序覆盖同名。
|
||||
|
||||
1. **导入即选择语言**(JSON 除外):`lib/fs.mq.md` → 英文 API;`lib/文件.mq.md` → 中文 API(见 [stdlib-i18n.md](stdlib-i18n.md))。
|
||||
2. **不设 `lang:`**。
|
||||
3. 宿主原语保持英文;中英差异只存在于 L1 包装层(JSON 无第二套包装)。
|
||||
4. 失败一律 `path:line:col: message`([stdlib.md](stdlib.md) §4)。
|
||||
### 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 草图(L1)
|
||||
## 3. 核心模块 API(摘要)
|
||||
|
||||
### 3.1 文件 — `fs` / `文件`
|
||||
文件 / 系统 / 时间 / 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` / `文件`
|
||||
|
||||
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|
||||
|------|------|-----------------|------|
|
||||
@@ -74,22 +116,19 @@ OS / HTTP / 时钟 / …
|
||||
| `make_dir` | `建目录` | `path` / `路径` | `None` |
|
||||
| `remove` | `删除` | `path` / `路径` | `None` |
|
||||
|
||||
约定:路径相对工作目录或绝对路径;二进制 I/O 本波不做;写/删默认需 `--allow-fs-write`(§6)。
|
||||
|
||||
### 3.2 系统 — `sys` / `系统`
|
||||
#### 系统 — `sys` / `系统`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `env_get` | `取环境` | `name` / `名` | 文本或 `None` |
|
||||
| `env_set` | `设环境` | `name`, `value` / `名`, `值` | `None` |
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 见上 |
|
||||
| `args` | `参数表` | (无) | 文本列表 |
|
||||
| `cwd` | `工作目录` | (无) | 文本 |
|
||||
| `exit` | `退出` | `code` / `码` | 不返回 |
|
||||
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码(实现时写死语义) |
|
||||
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码 |
|
||||
|
||||
`exec` 默认关(`--allow-exec`);view / 静态站永不开放。
|
||||
|
||||
### 3.3 时间 — `time` / `时间`
|
||||
#### 时间 — `time` / `时间`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
@@ -99,130 +138,58 @@ OS / HTTP / 时钟 / …
|
||||
| `sleep_ms` | `睡眠毫秒` | `ms` / `毫秒` | `None` |
|
||||
| `parse` | `解析时间` | `text`, `pattern` / `内容`, `格式` | 整数秒或诊断失败 |
|
||||
|
||||
view 中 `sleep_ms` 设上限(如 5s)。
|
||||
|
||||
### 3.4 JSON — `json`(**中英同库特例**)
|
||||
|
||||
JSON 是专有缩写,**很难也不必要**做合规中文库名/API 翻译。本波定稿:
|
||||
|
||||
| 项 | 约定 |
|
||||
|----|------|
|
||||
| 唯一路径 | **`lib/json.mq.md`**(中英文档均导入此路径) |
|
||||
| 函数名 | 国际通行英文:`parse` / `stringify` / `get` / `keys` |
|
||||
| 形参 | 英文:`text` / `value` / `key` / `indent` |
|
||||
| 不设 | `lib/数据.mq.md`、音译名、中文函数双份 |
|
||||
|
||||
这是对 [stdlib-i18n.md](stdlib-i18n.md)「一概念两文件」的**显式例外**;其它模块仍中英分文件。
|
||||
#### JSON — `json`
|
||||
|
||||
| 函数 | 形参 | 结果 |
|
||||
|------|------|------|
|
||||
| `parse` | `text` | 值(见下) |
|
||||
| `parse` | `text` | 值 |
|
||||
| `stringify` | `value`, 可选 `indent` | JSON 文本 |
|
||||
| `get` | `value`, `key` | 值或 `None` |
|
||||
| `keys` | `value` | 文本列表 |
|
||||
| `quote` | `text` | JSON 字符串字面量 |
|
||||
|
||||
**类型映射(草案)**:
|
||||
|
||||
| JSON | Marqdo Value |
|
||||
|------|----------------|
|
||||
| `null` | `None` |
|
||||
| bool | bool |
|
||||
| number(整数可表) | int |
|
||||
| number(其余) | 文本(本波不引入 float)或诊断拒绝 |
|
||||
| string | text |
|
||||
| array | list |
|
||||
| object | 倾向新宿主类型 **`map`**(`type` → `map`);否则体验差 |
|
||||
|
||||
`map` 为 L0.5 类型扩展,可与 json 同期或紧随;不阻塞 `fs`/`time` 先行。
|
||||
|
||||
### 3.5 网络(简)— `net` / `网络`
|
||||
#### 网络 — `net` / `网络`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `http_get` | `获取` | `url` / `地址` | 响应文本(或 map:status/body) |
|
||||
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` | 同上 |
|
||||
| `http_get` | `获取` | `url` / `地址` | 响应文本 |
|
||||
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` / `headers` | 同上 |
|
||||
| `url_encode` | `编码地址` | `text` / `内容` | 文本 |
|
||||
|
||||
仅 **HTTP 明文**(HTTPS 本波未做,会诊断提示);短超时、响应体上限;默认需 `--allow-net`;view / 静态站默认关。
|
||||
|
||||
**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
|
||||
|
||||
---
|
||||
|
||||
## 4. 中英路径总表(本波)
|
||||
## 4. 中英路径总表
|
||||
|
||||
```text
|
||||
lib/
|
||||
text.mq.md / 文本.mq.md # 已有
|
||||
table.mq.md / 表.mq.md # 已有
|
||||
fs.mq.md / 文件.mq.md # 本波
|
||||
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 # 本波;中英共用,无第二文件
|
||||
json.mq.md # 中英共用
|
||||
net.mq.md / 网络.mq.md
|
||||
# 暂缓:math / 数学 · foreign / 外联
|
||||
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/…`。
|
||||
别名:`std/…` ≡ `lib/…`。扩展解析:`MARQDO_EXT` / `./ext` / 二进制旁 `ext/`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 落地分期(本波 = M1–M5)
|
||||
## 5. 安全与 view / 静态导出
|
||||
|
||||
| 期 | 内容 | 完成定义 |
|
||||
|----|------|----------|
|
||||
| **M1** | 宿主能力框架:权限旗标、`host` 分发、错误文案 | `--allow-*` 可测 |
|
||||
| **M2** | `fs` + `time`(只读 fs + 时钟) | 中英库 + 金样例 |
|
||||
| **M3** | `sys`(env/cwd/args;`exec` 默认关) | 同上 |
|
||||
| **M4** | `json`(+ 可选 `map`) | 往返金样例;唯 `lib/json.mq.md` |
|
||||
| **M5** | `net`(默认关) | 本地 mock 或录制夹具 |
|
||||
|
||||
**不做 M6/M7**(数学 / 外联):详稿仅存档,待五库稳定后再议。
|
||||
|
||||
文档站:`fs`/`sys`/`time`/`net` 英中各一页;`json` 可一页双语叙述、同一导入路径。
|
||||
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**。差异仅在软退出 / sleep 钳制。相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。插件路径同沙箱。
|
||||
|
||||
---
|
||||
|
||||
## 6. 安全与 view / 静态导出
|
||||
## 6. 一句话
|
||||
|
||||
### 6.1 行为一致
|
||||
|
||||
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**(读/写盘、HTTP、exec 均可用)。导入库即表示要用;不再要求 `--allow-*`。
|
||||
|
||||
差异仅在 **软退出**:
|
||||
|
||||
| | CLI `run` | view / capture / 静态导出 |
|
||||
|--|-----------|---------------------------|
|
||||
| `exit` | 结束进程 | 报诊断,不杀 view/构建进程 |
|
||||
| `sleep_ms` | 默认可睡(有上限) | live 有上限;导出通常为 0 |
|
||||
|
||||
沙箱:相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。
|
||||
|
||||
### 6.2 静态部署
|
||||
|
||||
访客浏览器 **不再执行** Marqdo;HTML 里是构建时冻结的输出。源码中的路径/URL 访客改不了、也触发不了新的 host 调用。审 PR 时审查写死的目标即可。
|
||||
|
||||
勿在静态页嵌入「用户可改 URL 再请求」的浏览器脚本。
|
||||
|
||||
---
|
||||
|
||||
## 7. 与现有库的关系
|
||||
|
||||
- `text` / `table` 继续纯包装、无 IO。
|
||||
- JSON `stringify` ≠ `str`(显示)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 刻意不做(本波)
|
||||
|
||||
- 数学库、外联/胶水库(及其依赖、权限旗标实现)。
|
||||
- 数据库、异步事件循环、WebSocket、原始 TCP。
|
||||
- float/复数进 L0。
|
||||
- `lang:` 或按 locale 自动选库。
|
||||
- 为 JSON 强造中文库名或中文 API 双份。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话
|
||||
|
||||
**本波只落地文件 / 系统 / 时间 / JSON / 网络;JSON 中英共用 `lib/json.mq.md`;数学与外联暂缓。**
|
||||
**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
|
||||
---
|
||||
> 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)。
|
||||
+27
-17
@@ -2,12 +2,13 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 落地** |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [keywords.md](keywords.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [roadmap/next-phase.md](../roadmap/next-phase.md) |
|
||||
| 状态 | **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:`;中英分文件)。
|
||||
> **下一波模块(本波:文件 / 系统 / 时间 / JSON / 网络;数学·外联暂缓)**:见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -15,8 +16,9 @@
|
||||
|
||||
| 层 | 内容 |
|
||||
|----|------|
|
||||
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at` |
|
||||
| **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 / 用户站收录(随发版) |
|
||||
|
||||
---
|
||||
@@ -28,7 +30,7 @@
|
||||
| `len` | `value` | 文本标量数或列表长度 |
|
||||
| `str` | `value` | 显示文本 |
|
||||
| `int` | `value` | 整数(失败 → 诊断) |
|
||||
| `type` | `value` | `none`/`bool`/`int`/`text`/`list` |
|
||||
| `type` | `value` | `none`/`bool`/`int`/`text`/`list`/`map` |
|
||||
| `trim` | `value` | 去首尾空白 |
|
||||
| `split` | `value`, `sep` | 文本列表 |
|
||||
| `join` | `value`, `sep` | 拼接文本 |
|
||||
@@ -40,7 +42,7 @@
|
||||
|
||||
## 3. 官方库导入(S2)
|
||||
|
||||
Frontmatter:
|
||||
Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可改)。成员经点号路径调用(`time.parse`、`json.get`),不倒进全局短名。完整语义见 [module-namespace.md](module-namespace.md)。
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -49,28 +51,36 @@ Frontmatter:
|
||||
---
|
||||
```
|
||||
|
||||
调用示例:`> time.now_unix`、`> json.parse text=…`。需要本地短名时用 `> use time.format`(冲突 → 硬错误)。
|
||||
|
||||
`std/text.mq.md` 等价于 `lib/text.mq.md`。解析顺序:
|
||||
|
||||
1. 相对当前文件
|
||||
2. `MARQDO_LIB`(可指向 `lib` 目录或仓库根)
|
||||
3. 当前工作目录的 `lib/`
|
||||
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
|
||||
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`… / `取环境`… |
|
||||
| `lib/json.mq.md` | `parse` `stringify` `get` `keys`(中英同文件) |
|
||||
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`… / `获取`… |
|
||||
| `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` | `rows` `row_at` |
|
||||
| `lib/表.mq.md` | `行数` `取行` |
|
||||
| `lib/table.mq.md` | `put` 为首选写入;`rows`/`row_at` 及完整 list/map API — 见 [stdlib-table.md](stdlib-table.md) |
|
||||
| `lib/表.mq.md` | `改` 为首选写入;`行数`/`取行` 及完整 list/map API |
|
||||
|
||||
规划中的 L1 扩展见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
完整清单见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
---
|
||||
title: table cell expressions
|
||||
status: Accepted
|
||||
date: 2026-08-12
|
||||
related: markdown-mapping.md · roadmap/tables-maps-footnotes.md · call-arguments.md
|
||||
---
|
||||
|
||||
# 表单元格表达式(T5)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted** |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [call-arguments.md](call-arguments.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
v1 把 GFM 数据单元格一律收成 **字面量**(`Int` / `Text`)。结果虽是 `Map` / `List`,却不能写:
|
||||
|
||||
```markdown
|
||||
`h` =
|
||||
|
||||
| api_key | model |
|
||||
|---------|-------|
|
||||
| `api_key` | `model` |
|
||||
```
|
||||
|
||||
作者只好用 `json.set` 链或 JSON 字符串拼接——这是**实现缺口**,不是「字典只能装字面量」的语义必然。
|
||||
|
||||
---
|
||||
|
||||
## 2. 锁定规则
|
||||
|
||||
### 2.1 数据单元格 = 与调用实参相同的值语法
|
||||
|
||||
每个**数据**单元格(非表头、非分隔行)按 [`parse_call_arg_value`](../../src/parse/expr.rs) 解析,再在绑定求值时执行:
|
||||
|
||||
| 单元格写法 | 含义 |
|
||||
|------------|------|
|
||||
| `苹果` / `Alpha` | 裸词 → 文本字面量(与今日竖表兼容) |
|
||||
| `42` | 整数 |
|
||||
| `` `api_key` `` | 变量引用 |
|
||||
| `` `a` + `b` `` | 普通表达式 |
|
||||
| `True` / `假` / `None` | 布尔 / 空 |
|
||||
| `"https://…"` / `".marqdo/x"` | 引号字符串(可含 `/`、插值) |
|
||||
| `https://api.openai.com/v1` | **路径折叠**:无空格的 `Text/Text/…` 除法链收成整段文本(同调用实参) |
|
||||
| `gpt-4o-mini` | **连字符散文**:不拆成减法(同调用实参) |
|
||||
| `` /about ``、`` /chat/completions `` | 以 `/` 开头的路径散文 → 整段文本 |
|
||||
| 空单元格 | 空文本 `""` |
|
||||
|
||||
### 2.2 表头仍是键名文本
|
||||
|
||||
表头单元格**不**求值:键 = trim 后的表头字符串(与今日一致)。不允许 `` | `k` | `` 当动态键(v1 非目标;需要时另文)。
|
||||
|
||||
### 2.3 几何语义不变
|
||||
|
||||
竖表 / 横表单行 Map / 多行列向 Map / `@`·`行`·`row` 行向记录——**形状规则不变**;只把「单元格 → `Expr::Literal`」换成「单元格 → 完整 `Expr`」。
|
||||
|
||||
求值已由解释器对 `Expr::List` / `Expr::Map` 递归完成,字节码后端已发射列表/字典,**无需新 AST 节点**。
|
||||
|
||||
### 2.4 求值时机
|
||||
|
||||
表出现在 `` `名` = `` 右侧时,在**该绑定语句**求值:单元格内变量读**当时**环境。构造函数体里的表与语句表规则相同。
|
||||
|
||||
### 2.5 错误
|
||||
|
||||
- 单元格表达式非法 → 与别处表达式相同的 `path:line:col` 诊断(行号取该表行)。
|
||||
- 变量未定义 → 求值期报错。
|
||||
- 不引入「单元格静默当字面量」的回退(除 §2.1 已列的路径/连字符折叠,与调用实参对齐)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 作者示例(目标体验)
|
||||
|
||||
```markdown
|
||||
*`api_key` = > sys.env_get name=OPENAI_API_KEY *
|
||||
*`model` = "gpt-4o-mini" *
|
||||
|
||||
`handle` =
|
||||
|
||||
| api_key | base_url | model | suffix |
|
||||
|---------|----------|-------|--------|
|
||||
| `api_key` | https://api.openai.com/v1 | `model` | /chat/completions |
|
||||
```
|
||||
|
||||
`handle` 为含运行时 `api_key` / `model` 的字典;静态 URL 与 suffix 仍可裸写(路径折叠)。
|
||||
|
||||
嵌套:
|
||||
|
||||
```markdown
|
||||
*`prompt` = hello *
|
||||
|
||||
`msg` =
|
||||
|
||||
| role | content |
|
||||
|------|---------|
|
||||
| user | `prompt` |
|
||||
|
||||
*`messages` = > json.append list=None item=`msg` *
|
||||
```
|
||||
|
||||
(列表字面量表仍可用竖表;需要「单行记录」时用横表或 `@` 行向表。)
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容性
|
||||
|
||||
| 旧写法 | 行为 |
|
||||
|--------|------|
|
||||
| 纯中文/英文词、整数 | **不变** |
|
||||
| `gpt-4o-mini`、URL、`/path` | **不变**(折叠规则与调用实参一致) |
|
||||
| 真正要做除法 / 减法 | 用空格或括号:`` `n` / 2 ``、`` `a` - 1 ``;或先在表外算再 `` `x` `` 填入 |
|
||||
|
||||
破坏性:几乎无。唯一需注意的是「想在单元格里写算术且两侧是裸词」——与调用实参同一套消歧。
|
||||
|
||||
---
|
||||
|
||||
## 5. 非目标(本阶段)
|
||||
|
||||
- 表头动态键
|
||||
- 单元格内 `>` 调用(可用表外算完再引用)
|
||||
- 单元格内多语句 / 分支
|
||||
- 把叙述区(注释段)里的 GFM 表当成可执行(仍为注释)
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收
|
||||
|
||||
| 项 | 标准 |
|
||||
|----|------|
|
||||
| 金样 | 横表单元格 `` `var` `` 读环境;竖表旧金样全绿 |
|
||||
| 路径 | `https://…`、`/chat/completions`、`gpt-4o-mini` 仍为文本 |
|
||||
| 扩展 | `ext/ai/llm` 构造可用表写入运行时字段,去掉无必要的 `json.set` 链 |
|
||||
| 文档 | 本页 + roadmap T5 + markdown-mapping §9 同步 |
|
||||
|
||||
实现跟踪见 [roadmap/tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) **T5**。
|
||||
+11
-2
@@ -13,7 +13,7 @@
|
||||
| 路径 | 是否入库 | 职责 |
|
||||
|------|----------|------|
|
||||
| `doc/` | 是 | 开发者设计 / ADR / 路线图(单数 `doc`,勿再造 `docs/`) |
|
||||
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列 |
|
||||
| `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) |
|
||||
@@ -50,7 +50,16 @@ public/
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收
|
||||
## 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。
|
||||
|
||||
+49
-4
@@ -90,8 +90,16 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
|
||||
## 4. 信息架构
|
||||
|
||||
侧栏文件索引 + 主区:结构(AST+注释;旁侧函数大纲可搜索)· 执行 · 源码。表达式为表面语法。
|
||||
**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||||
侧栏文件索引 + 主区:结构(AST+注释)· 执行 · 源码。结构旁**右侧栏**(现有 outline 槽)为:
|
||||
|
||||
| 区块 | 内容 |
|
||||
|------|------|
|
||||
| **Functions** | 原函数大纲 + 搜索;可折叠(默认展开) |
|
||||
| **Variables** | 跑完后的入口(`# main`)顶层绑定只读快照;List/Map/`@` 行向渲成 HTML 表;可折叠(默认展开) |
|
||||
|
||||
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板。
|
||||
|
||||
表达式为表面语法。**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -102,8 +110,44 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
| `GET` | `/` | 默认打开第一个 `.mq.md`(无文件时为空提示) |
|
||||
| `GET` | `/file?path=…` | 单文件页 |
|
||||
| `GET` | `/api/tree` | JSON 树(可选) |
|
||||
| `GET` | `/api/events?path=…` | 可选长订 EventBus(调试);**Stream 面板默认不用**(避免页载常连导致标签页一直转圈) |
|
||||
| `POST` | `/api/run` | JSON `{path, stdin?}` → **直接返回** `text/event-stream`(本次 run 的事件);结束后关流 |
|
||||
| `POST` | `/api/foreign-run` | 外联代码块试跑 |
|
||||
|
||||
根目录锁死;拒绝 `..` 逃逸。
|
||||
根目录锁死;拒绝 `..` 逃逸。默认页加载仍可整页执行;Stream 为增强路径。
|
||||
|
||||
### 5.1 Stream 面板(对齐主流 LLM 呈现)
|
||||
|
||||
**仅当**当前文件 frontmatter 导入了 `ext/ai/llm` / `大模型` 或 `ext/ai/agent` / `智能体`(及等价路径)时,在 live Execution 区显示;普通脚本页不出现该组件。
|
||||
|
||||
参考常见助手产品(思考折叠 + 正文流式、工具/子步骤独立卡片):**不要**把所有 SSE 事件打成一条混色终端日志。
|
||||
|
||||
| 区块 | 事件 | 呈现 |
|
||||
|------|------|------|
|
||||
| **Thinking** | `reasoning` | 可折叠;流式追加到同一块;默认展开直至本轮 `delta`/`done` 开始,之后可收起 |
|
||||
| **Answer** | `delta` | **主文**;token 连续拼进同一段落(禁止每 token 换行);主色正文 |
|
||||
| **Decision** | `decision` | 时间线条目标记(`RUN` / `CONTINUE` / `DONE` / `REUSE` / `NEW` + 可选 summary) |
|
||||
| **Tool** | `tool_start` / `tool_end` | 父 Plan-and-Move 的 CALL/READ:名称 + kind;`tool_end` 可带截断 `result` |
|
||||
| **Phase** | `decompose` | 父 pre-run 分解开始(workbook 链);填补「决策后到首 token」空隙 |
|
||||
| **Child / Workbook** | `await` → `round` | `await`:Child **running…** 占位卡(quiet 子任务等待中);`round`:升级为完成卡(退出码 + 可选 `result`) |
|
||||
| **Status** | `run_start` / `done` / `error` | 顶栏状态 + 错误行;嵌套 LLM `done`(无 `run_id`)只冲刷 drip,不改顶栏;终态 `done.result` 仅在无 Answer 时作摘要 |
|
||||
|
||||
**传输与流畅度(对齐 ChatGPT 类产品):**
|
||||
|
||||
1. **Run = 一次 `fetch` POST**,用 `ReadableStream` 读响应体里的 SSE 帧;**不要**页载常驻 `EventSource`。
|
||||
2. **「Run with input」拦截表单**:`preventDefault` 后走同一 Stream `/api/run`,**禁止整页重载**;带 `?stdin=` 进入时 live 页也不再阻塞跑完,改为自动开 Stream。
|
||||
3. **只改 Stream 对话框 DOM**;token **按动画帧合批一次写入**(rAF coalesce,不人为节流;打字感来自网络到达节奏)。
|
||||
4. **Stick-to-bottom**:仅在用户仍贴底时跟随;程序化 `scrollTop` 产生的 scroll 事件忽略;上拉后不抢滚动,可点「↓ Latest」。
|
||||
5. **Stop**:`AbortController` 中止 fetch。
|
||||
6. **子任务并发进度**:`spawn` 立即返回;`wait` 阻塞父循环期间,子进程经 `MARQDO_EVENT_FORWARD` 把 EventBus 帧实时转发到父 SSE;view 把 `source=child` 的 delta 画进 Child 卡。quiet 仍不污染父 TTY。
|
||||
|
||||
视觉约束(与 §2 一致):
|
||||
|
||||
- 浅色内容面,不用深色「伪终端」底;Thinking 用次要字色 / 浅底。
|
||||
- 一屏只突出 Answer;Thinking 与 Child 是附属。
|
||||
- plan 多轮:每一轮 Child 一张卡;父侧 Thinking/Answer 按 decision 分轮,不清空历史。
|
||||
|
||||
事件字段约定(与 [agent-streaming.md](../roadmap/agent-streaming.md) 一致):`round` 可带 `result`(子 `# main` 返回值摘要);`reasoning`/`delta` 的 `text` 为增量。
|
||||
|
||||
---
|
||||
|
||||
@@ -113,4 +157,5 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
|
||||
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
|
||||
4. 冷启动无明显外网依赖。
|
||||
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
|
||||
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
|
||||
6. Stream:`fetch`+SSE 局部更新;Thinking/Answer 分栏;stick-to-bottom;rAF 合批;页载不常连 EventSource。
|
||||
@@ -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)。
|
||||
+3
-3
@@ -54,8 +54,8 @@ cargo clippy --all-targets
|
||||
|
||||
```bash
|
||||
# Windows PowerShell 示例
|
||||
$env:HTTPS_PROXY="http://127.0.0.1:7897"
|
||||
$env:HTTP_PROXY="http://127.0.0.1:7897"
|
||||
$env:HTTPS_PROXY="http://127.0.0.1:7890"
|
||||
$env:HTTP_PROXY="http://127.0.0.1:7890"
|
||||
cargo build
|
||||
```
|
||||
|
||||
@@ -63,7 +63,7 @@ cargo build
|
||||
|
||||
```toml
|
||||
[http]
|
||||
proxy = "http://127.0.0.1:7897"
|
||||
proxy = "http://127.0.0.1:7890"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -192,7 +192,7 @@ OKF 规范强调:一页纸能讲清 v0.1 的互通面;v0.2 只**加词汇、
|
||||
来自本次调研、建议在 `design/` 或 `adr/` 中跟进:
|
||||
|
||||
1. **`.mq.md` 的双重解析模型** — Markdown CST 与 Marqdo AST 如何共享同一文本、何处分叉。
|
||||
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳,见 [design/generated-yaml-manifest.md](../design/generated-yaml-manifest.md))。
|
||||
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳;**实现规范见 [okf.md](../design/okf.md)**,命令见 [catalog-cli.md](../design/catalog-cli.md))。
|
||||
3. **正文中的依赖声明语法** — import / 链接如何写出,供工具提取进生成清单。
|
||||
4. **Agent 友好但不 Agent 绑定** — 源格式对 LLM 可写,语义对确定性工具可检。
|
||||
5. **可渲染结果的 attestation(后期)** — 文档内求值结果的可验证性。
|
||||
|
||||
@@ -0,0 +1,181 @@
|
||||
# 智能体流式输出(未来规划)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 已落地**(view SSE) |
|
||||
| 日期 | 2026-08-10 |
|
||||
| 相关 | [ext-llm.md](../design/ext-llm.md) · [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md)(父 Plan-and-Move / CALL·READ) · [stdlib-subtask.md](../design/stdlib-subtask.md) · [view.md](../design/view.md) |
|
||||
| 痛点 | `complete` / `step` / `plan` 均为整段返回;用户看不到思考与中间输出 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
当前体验:
|
||||
|
||||
| 路径 | 行为 | 体验问题 |
|
||||
|------|------|----------|
|
||||
| `` `model`.complete `` | 等 HTTP 整包结束再返回字符串 | 长推理「卡住」无反馈 |
|
||||
| `` `助手`.step `` | 拼提示 → complete → 解析 CALL/答案 | 工具轮次与模型吐字均不可见 |
|
||||
| `` `助手`.plan `` | 多轮 spawn + 父 LLM;子任务默认 `quiet` | 父侧只有最终 `result` map;过程静默 |
|
||||
|
||||
这与「文档驱动、过程可审计」并不矛盾——**落盘真相**仍可以是工作簿与写回;缺的是**运行时的渐进呈现**(TTY / view / 调用方回调)。
|
||||
|
||||
约束回顾(不得破坏):
|
||||
|
||||
1. 文件子任务默认静默:答案走 `# main` **返回值**([stdlib-subtask.md](../design/stdlib-subtask.md))。
|
||||
2. `ext/**` 不直调 `host_*`;流式原语进 `ext/ai/llm` + 必要时薄 host/net。
|
||||
3. 多轮哲学仍是模式 C(子文件接力 + OKF),不是把 transcript 堆进单文件。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标
|
||||
|
||||
1. **可选**流式看到:模型增量文本、(可选)工具调用开始/结束、plan 轮次边界。
|
||||
2. 默认保持今日语义:未开流式 = 整段 `complete` / 整包 `result`。
|
||||
3. 流式是**呈现与旁路**,不替代 `**返回**` / `plan.result` / 写回。
|
||||
4. CLI、`marqdo view`、嵌入调用方可共用同一事件模型。
|
||||
|
||||
非目标(本规划):
|
||||
|
||||
- 把 Marqdo 做成聊天产品 UI 框架。
|
||||
- 强制所有 `print` 改流式 API。
|
||||
- 在 quiet 子进程里把子 `print` 默认真传父 TTY(与返回优先冲突)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 分层设计
|
||||
|
||||
```text
|
||||
LLM 供应商 SSE / chunked
|
||||
↓
|
||||
ext/ai/llm stream=True → 事件迭代 / 回调 / 写 channel
|
||||
↓
|
||||
ext/ai/agent step/plan 订阅事件 → 可选透传或写回「过程槽」
|
||||
↓
|
||||
呈现面:TTY | view EventSource | 调用方 foreach 事件表
|
||||
```
|
||||
|
||||
### 3.1 事件模型(锁定方向)
|
||||
|
||||
统一为可 JSON 化的小 map(便于写回与 view):
|
||||
|
||||
| `type` | 含义 | 主要字段 |
|
||||
|--------|------|----------|
|
||||
| `reasoning` | 模型思考增量(如 DeepSeek `reasoning_content`) | `text` |
|
||||
| `delta` | 模型答案增量文本 | `text` |
|
||||
| `tool_start` / `tool_end` | 工具轮(父 plan CALL/READ 已发;view Tool 卡) | `name`, `kind?`, `result?` |
|
||||
| `round` | plan 轮次边界(子工作簿跑完) | `round`, `workbook`, `exit_code?`, `result?`(子返回值摘要) |
|
||||
| `decision` | DONE / CONTINUE / RUN | `decision`, `summary?` |
|
||||
| `done` | 本调用结束 | `result`(答案正文;不含 thinking) |
|
||||
| `error` | 失败 | `message` |
|
||||
|
||||
中英键名可在 L1 包装层镜像;插件/wire 先用英文 `type`。
|
||||
|
||||
### 3.2 `llm`:流式完成
|
||||
|
||||
```markdown
|
||||
*`model` = > llm *
|
||||
*`stream` = > `model`.complete prompt=… stream=True *
|
||||
- [`ev`](`stream`)
|
||||
*`t` = > json.get value=`ev` key=type *
|
||||
1. `t` == delta
|
||||
*`chunk` = > json.get value=`ev` key=text *
|
||||
> print text=`chunk`
|
||||
2. `t` == done
|
||||
*`answer` = > json.get value=`ev` key=result *
|
||||
```
|
||||
|
||||
或回调形(若日后支持函数值作实参):`on_delta=` —— v1 优先 **事件列表 / 可迭代句柄**,少发明回调语法。
|
||||
|
||||
实现要点:
|
||||
|
||||
- `lib/net` 或 llm 插件支持 **读 SSE / chunked body**(今日 `http_post` 偏整包)。
|
||||
- `stream=False`(默认)路径零行为变化。
|
||||
- 金样:mock SSE fixture,不强制打真网。
|
||||
|
||||
### 3.3 `agent.step` / `plan`:过程透传
|
||||
|
||||
| 开关(草案) | 默认 | 行为 |
|
||||
|--------------|------|------|
|
||||
| `stream=False` | ✓ | 与今日相同 |
|
||||
| `stream=True` | | 向**当前进程**呈现面推送事件;返回值仍是最终 map |
|
||||
| `trace=True` | 可选 | 把事件追加写入调用行写回槽 `trace`(审计);与 TTY 流式可分立 |
|
||||
|
||||
plan 特有:
|
||||
|
||||
- `await_workbook` **前**发 `await`(view Child running 占位);结束后发 `round`。
|
||||
- 父 pre-run 分解发 `decompose`。
|
||||
- 父 LLM 的 `complete` 若 `stream=True`,`delta` 冒泡到 plan 的 stream。
|
||||
- **子文件 quiet 不变(TTY)**;默认骨架 `step stream=True`,子 EventBus 经 `MARQDO_EVENT_FORWARD` **实时转发**到父 SSE(`source=child`)。答案仍以 `# main` 返回为准。
|
||||
|
||||
### 3.4 呈现面
|
||||
|
||||
| 面 | 做法 |
|
||||
|----|------|
|
||||
| CLI | `delta` 直接写 stdout(无额外 JSON 包装);结构化事件可 `--trace-events` 走 stderr / 旁路文件 |
|
||||
| `marqdo view` | Execution 区 Stream 面板订阅 SSE(见 [view.md](../design/view.md) §5.1):Thinking / Answer / Child 分栏,非混色日志 |
|
||||
| 库调用方 | foreach 事件集合,自行决定 UI |
|
||||
|
||||
**view Stream 锁定(S3 UI):**
|
||||
|
||||
1. `reasoning` → 可折叠 Thinking;`delta` → 主文 Answer(连续拼接)。
|
||||
2. `round` → 独立 Child/Workbook 卡(路径链 + 可选 `result`);不与父 Answer 混排。
|
||||
3. `decision` → 时间线条目标记。
|
||||
4. 视觉跟 view HIG 浅色壳,不用深色终端底。
|
||||
5. **传输**:`POST /api/run` 直接 SSE;前端 `fetch`+`ReadableStream`(非页载 EventSource);rAF 合批;stick-to-bottom。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与「返回优先」的关系
|
||||
|
||||
| 通道 | 职责 |
|
||||
|------|------|
|
||||
| stream / trace | **过程**(体验、调试、审计) |
|
||||
| `# main` `**…**` / `plan.result` | **结果**(编排、OKF、调用方消费) |
|
||||
| writeback `ok`/`error` | **落盘摘要**(默认可关) |
|
||||
|
||||
禁止:仅靠 stream 文本当作子任务成功条件;DONE / 固化仍看退出码、返回值与源码形态。
|
||||
|
||||
---
|
||||
|
||||
## 5. 推荐落地顺序
|
||||
|
||||
```text
|
||||
S0 net/llm:SSE 读 + complete stream=True + 事件 foreach ✅
|
||||
S1 step stream=True(echo 增量;返回 map 不变) ✅
|
||||
S2 plan stream=True:round + 父 delta;trace 写回可选 ✅
|
||||
S3 view 订阅(EventBus + GET /api/events + POST /api/run) ✅
|
||||
```
|
||||
|
||||
### 开放点决议(S0)
|
||||
|
||||
1. **Eager 事件列表**(非惰性句柄):`complete stream=True` 返回 `List` of maps,可用今日 foreach。
|
||||
2. **默认不自动 print**:`echo=False`;需要边读边打时传 `echo=True` / `打印增量=真`。
|
||||
3. 中文:`## 运行` 用 `流式=` / `打印增量=`。
|
||||
|
||||
### 开放点决议(S2)
|
||||
|
||||
1. `plan` / `多步` 增加 `stream` / `echo` / `trace`(中文 `流式` / `打印增量` / `轨迹`)。
|
||||
2. 事件挂在返回 map 的 `events`;父 `complete` 只冒泡 `delta`/`error`(嵌套 `done` 不进列表)。
|
||||
3. `trace=True` → 写回槽 `trace`(与 TTY `echo` 可分立)。
|
||||
4. **体验(父先子后)**:非命中路径先 `decompose`(SSE + 可选 TTY `plan:decompose`),再 `await`(SSE 占位 + 可选 TTY `plan:await`),子 quiet。修订轮仍是观察后父决策。SSE 本身用 `tests/ext/llm-stream-live.mq.md`。
|
||||
|
||||
验收:
|
||||
|
||||
1. 未传 `stream` 的金样零 diff。
|
||||
2. `stream=True` 时用户在首包 token 到达前不应长时间无输出(允许短连接建立延迟)。
|
||||
3. 最终 `result` 与非流式路径一致(同 prompt fixture)。
|
||||
4. quiet 子任务仍不污染父 TTY。
|
||||
|
||||
---
|
||||
|
||||
## 6. 开放点
|
||||
|
||||
1. ~~Eager vs 惰性~~ → S0 选 eager;惰性句柄可后补。
|
||||
2. ~~delta 默认 print~~ → 默认关;`echo=True` 可选。
|
||||
3. ~~中文面~~ → `流式=` / `打印增量=`。
|
||||
4. ~~S2~~ → `plan stream=True`:`round` / 父 delta / `decision` / `done`;可选 `trace`。
|
||||
5. ~~**S3**~~ → `marqdo view`:进程内 EventBus;`GET /api/events`(SSE);`POST /api/run` 后台执行;Execution 区 EventSource 面板。CLI 默认不订阅。
|
||||
|
||||
S0 可与 [okf-near-match.md](okf-near-match.md) 并行,互不阻塞。
|
||||
@@ -0,0 +1,56 @@
|
||||
# 官方扩展:`ext/quantum` 实现路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Q0–Q6 已落地**(含公式自定义门;更大 n / 完整开放系统另文) |
|
||||
| 日期 | 2026-08-12 |
|
||||
| **锁定设计** | [design/ext-quantum.md](../design/ext-quantum.md) |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) |
|
||||
| 安装 | `marqdo ext add quantum`(`quantum` / `量子`) |
|
||||
|
||||
本文只跟踪**实现阶段**。作者面、模拟语义、view 可视化、分期以设计文为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标回顾(一句)
|
||||
|
||||
**可运行的量子电路文档**:表声明门序列 → ABI 模拟概率/采样 → view 内嵌电路/概率 SVG;文档跑通即公式约定成立。
|
||||
|
||||
---
|
||||
|
||||
## 2. 落地阶段
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **Q0** | CATALOG + `plugins/quantum` ping + L1 `ensure_plugin` | **done** |
|
||||
| **Q1** | 态向量;I/X/H/CX;`simulate` / `probabilities`;贝尔态 gold | **done** |
|
||||
| **Q2** | Y/Z/S/T/R\* /CZ/SWAP;`run seed=`;中英 API | **done** |
|
||||
| **Q3** | `steps=` 电路表;`draw` 轨线 SVG;view `record_plot` 或值识别 | **done** |
|
||||
| **Q4** | 概率条 / 布洛赫;`matches_matrix`;examples + 用户文档 | **done** |
|
||||
| **Q5** | 教学噪声 + barrier/measure/append/state — [ext-quantum-q5.md](../design/ext-quantum-q5.md) | **done(最小)** |
|
||||
| **Q5.5** | `amplitude_damping` 轨迹 — [ext-quantum-q5.5.md](../design/ext-quantum-q5.5.md) | **done** |
|
||||
| **Q6** | 公式/`matrix=` 自定义门 + `apply` — [ext-quantum-custom-gate.md](../design/ext-quantum-custom-gate.md) | **done** |
|
||||
|
||||
验收金样:`tests/ext/quantum-bell-smoke.mq.md`、`quantum-draw-smoke.mq.md`、`quantum-gate-matrix-smoke.mq.md`、`quantum-gate-heatmap-smoke.mq.md`、`quantum-author-api-smoke.mq.md`、`quantum-noise-smoke.mq.md`、`quantum-amp-damp-smoke.mq.md`、`quantum-custom-gate-smoke.mq.md`、中文对称样例。
|
||||
|
||||
---
|
||||
|
||||
## 3. 已收敛的原开放点
|
||||
|
||||
| 原疑问 | 锁定结论(见设计文) |
|
||||
|--------|----------------------|
|
||||
| 并进 math? | **否**,独立 `ext/quantum` |
|
||||
| 电路表 | **要做**(Q3),与方法链等价 |
|
||||
| view 图 | 自绘 SVG;优先 `host_query("record_plot")`;不依赖 web |
|
||||
| 自由函数面 | **不**与对象面并行 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 与其它文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [design/ext-quantum.md](../design/ext-quantum.md) | **真理** |
|
||||
| [stdlib-math.md](../design/stdlib-math.md) | 公式/作图精神对照;实现分离 |
|
||||
| [ext-web.md](../design/ext-web.md) | 同属官方 ext + ABI + `ext add` 模板 |
|
||||
| [view.md](../design/view.md) | 结构卡 + Execution 内嵌 SVG |
|
||||
@@ -0,0 +1,53 @@
|
||||
# 官方扩展:`ext/web` 实现路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **W0–W3 骨架已落地;W4 待** |
|
||||
| 日期 | 2026-08-11 |
|
||||
| **锁定设计** | [design/ext-web.md](../design/ext-web.md) |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [ext-llm.md](../design/ext-llm.md) |
|
||||
| 安装 | `marqdo ext add web`(`web` / `网页`) |
|
||||
|
||||
本文只跟踪**实现阶段**。类模型、赋值绑定、后台、`.env`、异步边界、ABI 名等以设计文为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标回顾(一句)
|
||||
|
||||
**表格完成动态站**:页面表拼组件、组件表绑库与样式、样式表定外观;热路径进 ABI 插件;可选 S3 / Redis。人写目标见设计 §0.1 与 `examples/man-write-site/`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 落地阶段
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **W0** | CATALOG + L1 + `web_listen` Hello | **done** |
|
||||
| **W1** | env 端口;`page` 四栏;nav 表;static | **done** |
|
||||
| **W2** | SQLite `define`/`migrate`/`all` | **done** |
|
||||
| **W3** | 三列绑定;变量名即表名;`/admin` CRUD+日志+布局 | **done**(登录鉴权仍简) |
|
||||
| **W3.5** | 人写面首版:`web.assemble` + `` `表`.`字段` `` + `examples/man-write-site` | **done**(编排袋仍可再瘦) |
|
||||
| **W4** | Postgres;Redis / S3 驱动 | pending |
|
||||
|
||||
验收金样:`tests/ext/web-smoke.mq.md`、`ext_cli_add_web`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 已收敛的原开放点
|
||||
|
||||
| 原疑问 | 锁定结论(见设计文) |
|
||||
|--------|----------------------|
|
||||
| listen 阻塞 vs 后台任务 | `# main` 内 `listen` **同步阻塞**;插件内部异步 |
|
||||
| handler 形态 | **不主推**手写 REST;表 href + bind + 自动后台 |
|
||||
| `marqdo web` 子命令 | scaffold 经 `web.scaffold`;`marqdo web new` 可后续补 |
|
||||
| Windows + SQLite | 路径用 `DATABASE_URL` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 与其它文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [design/ext-web.md](../design/ext-web.md) | **真理** |
|
||||
| [user-site.md](../design/user-site.md) | 静态站互补 |
|
||||
| [ext-quantum.md](ext-quantum.md) | 同属官方 ext + ABI + `ext add` |
|
||||
@@ -62,7 +62,7 @@ index.mq.md (+ 导入的 .mq.md)
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入合并
|
||||
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入模块树(见 module-namespace)
|
||||
│ │ 作用域链、形参、未定义名诊断
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
|
||||
@@ -19,7 +19,7 @@
|
||||
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
|
||||
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
|
||||
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
|
||||
| **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 |
|
||||
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
|
||||
|
||||
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
|
||||
|
||||
|
||||
@@ -0,0 +1,167 @@
|
||||
# 对象继承语法(未来规划)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **I0–I3 已落地**(显式父构造约定;**不做**隐式 auto-super) |
|
||||
| 日期 | 2026-08-10 |
|
||||
| 相关 | [objects.md](../design/objects.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [keywords.md](../design/keywords.md) |
|
||||
| 提案语法 | `# 子类 = > 父类` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
今日 [`objects.md`](../design/objects.md) 明确非目标:**继承 / 接口 / 可见性**。
|
||||
实际扩展(如 `# agent` / `# llm`)靠「再写一个对象 + 组合句柄」,缺少:
|
||||
|
||||
- 复用父构造 / 父方法而不复制 `.mq.md`
|
||||
- 子类型在 `_type` 链上解析方法
|
||||
- 与 Markdown 标题体系一致的、可读的继承声明
|
||||
|
||||
需要一种**不引入 `class`/`extends` 关键字**、且与现有 `=`(绑定)与 `>`(调用)语义兼容的写法。
|
||||
|
||||
---
|
||||
|
||||
## 2. 锁定语法(提案)
|
||||
|
||||
```markdown
|
||||
# 子类 = > 父类
|
||||
```
|
||||
|
||||
| 片段 | 既有含义 | 组合后含义 |
|
||||
|------|----------|------------|
|
||||
| `# 子类` | 定义对象 / 类型 | 子类型名 |
|
||||
| `=` | 绑定 / 赋值 | 类型关系写在「类型定义槽」上 |
|
||||
| `> 父类` | 调用(此处为类型名) | **基类引用**(不是构造实例) |
|
||||
|
||||
可选带参基类(若基类本身是泛化构造,v1 可暂不支持):
|
||||
|
||||
```markdown
|
||||
# 特化智能体 = > 智能体
|
||||
```
|
||||
|
||||
中英对称:
|
||||
|
||||
```markdown
|
||||
# Child = > Parent
|
||||
# 子类 = > 父类
|
||||
```
|
||||
|
||||
### 2.1 为何不冲突
|
||||
|
||||
1. **今日** `# 名` 后接的是构造体正文,不是 `` `# 名 = …` `` 标题行。
|
||||
2. **语句绑定**是 `*…*` 或行内 `` `x` = ``,不是 ATX `#` 标题。
|
||||
3. **`> 父类` 在标题行**出现在 `=` 右侧:解析器可把「`#` 标题含 `=` 与 `>`」识别为**类型声明**,而非执行构造。
|
||||
4. 真正构造实例仍是正文或 `# main` 里的 `` `x` = > 子类 … ``。
|
||||
|
||||
反例(仍是今日语义,不变):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`a` = > 父类 *
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 运行时语义(草案)
|
||||
|
||||
### 3.1 方法解析
|
||||
|
||||
实例 map 仍有 `_type` = 构造时的类型名(子类名)。
|
||||
|
||||
查找 `` `obj`.方法 ``:
|
||||
|
||||
1. 在 `_type` 对应对象上找 `## 方法`
|
||||
2. 未找到 → 沿 **基类链** 查找
|
||||
3. 仍无 → 报错(带类型链)
|
||||
|
||||
构造:
|
||||
|
||||
1. 若子类构造体未显式处理,可先调基类构造(见开放点:是否自动 `super`)。
|
||||
2. 返回 map 的 `_type` = **最具体子类名**(不是父类名)。
|
||||
|
||||
### 3.2 子类正文
|
||||
|
||||
```markdown
|
||||
# 工蜂 = > 智能体
|
||||
|
||||
## 采蜜
|
||||
+ `花`
|
||||
|
||||
*`out` = > `self`.step task=`花` *
|
||||
**`out`**
|
||||
```
|
||||
|
||||
- 子类可定义新 `##`
|
||||
- 可覆盖同名 `##`(子类优先)
|
||||
- 站立提示 / 字段约定:文档层说明,v1 不引入可见性关键字
|
||||
|
||||
### 3.3 多继承
|
||||
|
||||
**v1 不支持。** 一个 `# 子 = > 父` 仅一条基类。混入用组合(句柄字段)而非多 `>`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 解析与 AST
|
||||
|
||||
标题形态需在 [markdown-mapping.md](../design/markdown-mapping.md) / parse 中新增一种 object decl:
|
||||
|
||||
| 字段 | 值 |
|
||||
|------|-----|
|
||||
| `name` | 子类 |
|
||||
| `base` | 父类(标识符) |
|
||||
| `body` | 与今日 object body 相同 |
|
||||
|
||||
歧义处理:
|
||||
|
||||
- `# Foo = 1` → **非法**(右侧必须是 `> 类型名`)
|
||||
- `# Foo = > bar.baz` → v1 **非法**(基类须为已定义对象名,不走任意调用表达式)
|
||||
- 基类尚未定义 → Pass1 收集后解析;循环继承报错
|
||||
|
||||
---
|
||||
|
||||
## 5. 与标准库 / 扩展
|
||||
|
||||
| 用途 | 例子 |
|
||||
|------|------|
|
||||
| 扩展官方智能体 | `# 客服 = > agent` / `# 客服 = > 智能体` |
|
||||
| 扩展 llm 句柄 | 一般不必要;优先组合 |
|
||||
| 用户域模型 | `# 订单服务 = > 服务基类` |
|
||||
|
||||
官方 `lib/*` 仍以自由函数为主;继承主要服务 `ext/` 与用户对象。
|
||||
|
||||
---
|
||||
|
||||
## 6. 推荐落地顺序
|
||||
|
||||
```text
|
||||
I0 语法 + AST + 金样(解析/循环继承错误) ✅
|
||||
I1 方法解析沿基类链;构造 _type=子类 ✅
|
||||
I2 覆盖方法;文档更新 objects.md ✅
|
||||
I3 显式父构造约定(**不做**隐式 auto-super) ✅
|
||||
```
|
||||
|
||||
验收:
|
||||
|
||||
1. 无继承文件行为不变。
|
||||
2. 子类实例能调父类 `##`;覆盖后只走子类。
|
||||
3. `` # A = > B `` / `` # B = > A `` 诊断清晰。
|
||||
4. Skill / 金样:`tests/structure/inherit-*.mq.md`(含显式 `` `self` = > Parent ``)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 开放点
|
||||
|
||||
1. ~~**隐式 super**~~ → **不做**:子类构造体不自动跑父构造。需要父初始化时正文写 `` `self` = > 父类 … `` 再改字段后 `**`self`**`;构造完成时 `_type` 仍为最具体子类名。
|
||||
2. 中英基类别名:`> agent` 与 `> 智能体` 是否同一对象(取决于模块导出)。
|
||||
3. 继承是否写入 OKF Module 页(catalog 展示 `extends`)——可随 O3/O4 增强。
|
||||
|
||||
---
|
||||
|
||||
## 8. 非目标
|
||||
|
||||
- 接口 / 抽象方法 / 可见性(`public`)
|
||||
- 多继承、mixin 关键字
|
||||
- 用继承替代 `plan` 工作簿接力
|
||||
- 把 `# 子 = > 父` 解析成「定义时立即构造父实例」
|
||||
@@ -0,0 +1,108 @@
|
||||
# OKF 相近任务命中
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **A 规范句 + B aliases + C 父裁决(soft_match)+ D 本地 n-gram `near` 已落地**;E dense embedding 仍非目标 |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 相关 | [okf.md](../design/okf.md) §7 · [ext-agent-plan.md](../design/ext-agent-plan.md) §4.2 · [ext-agent.md](../design/ext-agent.md) |
|
||||
| 触发观察 | `man-test`:相近 goal 生成两份独立 resource |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
v1 agent-kb **精确命中仍是默认快路径**:
|
||||
|
||||
1. `normalize_goal`:去首尾空白、合并连续空白(**不做**近义改写)。
|
||||
2. `sig` = 规范化字符串的稳定短哈希;`slug` = 可读路径名。
|
||||
3. `agent_kb_lookup`:精确 → aliases → canonicalize → **本地 n-gram `near`(默认开)**;仍 miss 且 `plan soft_match=True` 时父裁决 REUSE/NEW(候选为排序 near 列表)。
|
||||
|
||||
历史痛点(已由 A/B/C/D 缓解):
|
||||
|
||||
| goal(调用方输入) | 旧行为 |
|
||||
|--------------------|--------|
|
||||
| `你是一个智能体,帮我规划明天的行程` | 独立 slug,与下方不命中 |
|
||||
| `帮我规划明天的行程` | 另一份 resource |
|
||||
| `帮我规划明天行程` | 又一份(近句碎片) |
|
||||
|
||||
调用方直觉:「这不是同一件事吗?」——现可用 canonicalize、默认 `near_match`,或显式 `soft_match` 父裁决。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为何精确指纹仍优先
|
||||
|
||||
| 理由 | 说明 |
|
||||
|------|------|
|
||||
| 假阳性代价高 | 错复用旧工作簿比多建一个文件更糟 |
|
||||
| 可审计 | `sig` 可复算;`near` 留下 `match`/`score` |
|
||||
| 哲学 | 多轮 = 子文件接力 + OKF 索引,不是聊天式模糊检索 |
|
||||
|
||||
**结论:** 精确命中长期保留为**默认快路径**;`near` 是可关闭的第四趟(`near_match=False`)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 已落地层
|
||||
|
||||
### A. 规范化后再精确命中 — **已落地**
|
||||
|
||||
`agent_kb_canonicalize`:剥站立前缀、去尾标点;`match: canonical`。
|
||||
|
||||
### B. 别名 / 标签表 — **已落地**
|
||||
|
||||
Task FM `aliases:`;`match: alias`。
|
||||
|
||||
### C. 父智能体软裁决 — **已落地(默认关)**
|
||||
|
||||
`plan soft_match=True`:`agent_kb_near_match` 排序候选(含 `score`;空则退回 `list_tasks`)→ 父 `DECISION: REUSE` + `SLUG:` 或 `DECISION: NEW`。
|
||||
|
||||
### D. 本地字符 bigram + 余弦 — **已落地(默认开)**
|
||||
|
||||
| | |
|
||||
|--|--|
|
||||
| 做法 | 稀疏词法向量化(**不是** embedding 模型):canonicalize 后对 goal 与 Task `title\|description\|aliases` 建字符 bigram 词袋,算余弦 |
|
||||
| API | `agent_kb_near_match`;`agent_kb_lookup` 第四趟 |
|
||||
| 参数 | `near_match`/`近义命中` 默认 `True`;`near_threshold`/`近义阈值` 默认 `0.78` |
|
||||
| 痕迹 | `match: near` + `score`;`cache=soft-hit`;可写 alias |
|
||||
|
||||
术语:这是 **sparse lexical near-match**,勿宣传为向量库 / embedding 检索。
|
||||
|
||||
### E. Dense embedding(可选远期)
|
||||
|
||||
远程 / 本地 dense 向量与 ANN **仍非本仓默认目标**;仅当 D 在真实包体量下证据不足时再评估。
|
||||
|
||||
---
|
||||
|
||||
## 4. 演进顺序
|
||||
|
||||
```text
|
||||
精确 sig(永不删除)
|
||||
→ A 规范句 + B aliases(已落地)
|
||||
→ C soft_match 父裁决(已落地,默认关)
|
||||
→ D 本地 n-gram near(已落地,默认开)
|
||||
→ E dense embedding(仅有证据再开)
|
||||
```
|
||||
|
||||
验收原则:
|
||||
|
||||
1. `near_match=False` 时与无 near 行为一致;`force`/`optimize` 仍跳过 reuse。
|
||||
2. 软/近义命中留下 `cache=soft-hit` / `match` / 可选 `score`。
|
||||
3. 假阳性可被 `force=True` / 显式 `workbook=` / 调高 `near_threshold` 覆盖。
|
||||
4. 实现仍在 **agent 插件 + `ext/ai`**,不进核心 `src/host`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 调用方建议
|
||||
|
||||
- 固定规范 goal;站立语可由 canonicalize 剥掉。
|
||||
- 近句碎片依赖默认 `near_match`;字面差更大时开 `soft_match=True`。
|
||||
- 策展:合并重复 task,次要措辞写入 `aliases`(O4)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 与现有路线图的关系
|
||||
|
||||
| 条目 | 关系 |
|
||||
|------|------|
|
||||
| [okf.md](../design/okf.md) O2 / O5 | 精确 reuse + A/B/C/D;E dense 仍待 |
|
||||
| [okf.md](../design/okf.md) O4 | `kb query` / 策展可继续扩 aliases |
|
||||
| [ext-agent-plan.md](../design/ext-agent-plan.md) | 多轮仍只走子文件接力;软命中只影响「选哪个子文件」 |
|
||||
@@ -0,0 +1,303 @@
|
||||
# 表格语义打磨:列表 · 字典 · 嵌套 · 脚注取元(未来规划)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **T0–T5 已落地**(单元格表达式见 [table-cell-expressions.md](../design/table-cell-expressions.md)) |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 相关 | [markdown-mapping.md](../design/markdown-mapping.md) §9 · [table-cell-expressions.md](../design/table-cell-expressions.md) · [objects.md](../design/objects.md) · [stdlib.md](../design/stdlib.md)(`lib/table`) · [keywords.md](../design/keywords.md) |
|
||||
| 现状金样 | [tests/structure/collection.mq.md](../../tests/structure/collection.mq.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
### 1.1 今日表格 =「竖表 → 列表」
|
||||
|
||||
```markdown
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
```
|
||||
|
||||
语义(已落地):绑定为**列表**(列值);表头名供 `` [`果`](`篮子`) `` 遍历。
|
||||
单列表头是当前唯一一等集合外形;**没有**一等「横表 = 字典」。
|
||||
|
||||
### 1.2 缺字典外形与嵌套
|
||||
|
||||
用户期望:GFM 表的两种几何对应两种结构,并允许嵌套——这样「多行表格」才有稳定、可教的含义。
|
||||
|
||||
### 1.3 不能按下标 / 键直接取元
|
||||
|
||||
今日要从列表取第 *n* 项,往往只能遍历或走 `lib/table`(`row_at` 等),**语言级**缺少与 Markdown 同构的取元语法。字典亦然。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标
|
||||
|
||||
1. **竖表**继续表示列表(兼容现有金样)。
|
||||
2. **横表**(多列表头 + 数据行)表示字典及「字典 ↔ 列表」嵌套。
|
||||
3. 用 **Markdown 脚注外形** 做列表下标 / 字典键的取元(表达式级)。
|
||||
4. 不引入 `[]` 下标关键字风暴;少而精,与「标记即语法」一致。
|
||||
|
||||
非目标:
|
||||
|
||||
- 完整电子表格公式引擎
|
||||
- 用表声明对象字段 schema(仍见 objects 非目标;与数据集合分开)
|
||||
- 破坏现有单列竖表金样
|
||||
|
||||
---
|
||||
|
||||
## 3. 表格几何 → 值(锁定提案)
|
||||
|
||||
判定在 **绑定右侧的 GFM 表** 上做(`` `名` = `` 后接表)。
|
||||
|
||||
### 3.1 竖表 → 列表(现状,保留)
|
||||
|
||||
**形状:** 恰好 **1** 列。
|
||||
|
||||
```markdown
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
```
|
||||
|
||||
| 结果 | 说明 |
|
||||
|------|------|
|
||||
| 值 | `List`:`["苹果","梨","桃"]` |
|
||||
| 表头 | 元素逻辑名(foreach 绑定名);不进入列表元素 |
|
||||
|
||||
### 3.2 横表单数据行 → 字典
|
||||
|
||||
**形状:** ≥2 列,且 **恰好 1 行数据**(表头 + 分隔 + 一行)。
|
||||
|
||||
```markdown
|
||||
`分类` =
|
||||
|
||||
| 苹果 | 黄瓜 | 鼠标 |
|
||||
|------|------|------|
|
||||
| 水果 | 蔬菜 | 数码用品 |
|
||||
```
|
||||
|
||||
| 结果 | 说明 |
|
||||
|------|------|
|
||||
| 值 | `Map`:`苹果→水果`, `黄瓜→蔬菜`, `鼠标→数码用品` |
|
||||
| 键 | 表头单元格文本(规范化空白后) |
|
||||
| 值 | 唯一数据行对应列 |
|
||||
|
||||
### 3.3 横表多数据行 → 字典套列表(默认)
|
||||
|
||||
**形状:** ≥2 列,且 **≥2 行数据**。
|
||||
|
||||
```markdown
|
||||
`货架` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 红富士 | 青瓜 |
|
||||
| 嘎啦 | 黄瓜条 |
|
||||
```
|
||||
|
||||
**默认语义(锁定):列向聚合**
|
||||
|
||||
```text
|
||||
{
|
||||
"苹果": ["红富士", "嘎啦"],
|
||||
"黄瓜": ["青瓜", "黄瓜条"]
|
||||
}
|
||||
```
|
||||
|
||||
即:**键 = 表头,值 = 该列数据行组成的列表**。
|
||||
这与竖表「一列 = 一列表」在多列时自然推广,嵌套外形稳定。
|
||||
|
||||
**备选语义(不默认):行向记录列表**
|
||||
|
||||
```text
|
||||
[
|
||||
{"苹果":"红富士","黄瓜":"青瓜"},
|
||||
{"苹果":"嘎啦","黄瓜":"黄瓜条"}
|
||||
]
|
||||
```
|
||||
|
||||
更像 SQL / CSV。若未来需要,用显式标记区分(见 §3.5),**不得**与默认列向字典静默混用。
|
||||
|
||||
### 3.4 单列多行 vs 多列
|
||||
|
||||
| 列数 | 数据行 | 值类型 |
|
||||
|------|--------|--------|
|
||||
| 1 | ≥0 | `List` |
|
||||
| ≥2 | 1 | `Map`(标量值) |
|
||||
| ≥2 | ≥2 | `Map`(值均为 `List`) |
|
||||
| ≥2 | 0 | `Map`(键存在,值空列表或错误——开工时锁定为「空列表」) |
|
||||
|
||||
### 3.5 显式形态标记(行向记录)— **已落地**
|
||||
|
||||
首列表头为下列之一时,整表改为**行向**(不静默混用列向默认):
|
||||
|
||||
| 标记 | 说明 |
|
||||
|------|------|
|
||||
| `@` | ASCII 短标记 |
|
||||
| `行` | 中文 |
|
||||
| `row` | 英文 |
|
||||
|
||||
规则:
|
||||
|
||||
1. 标记列**不进入**记录字段(数据格可写行号给人看)。
|
||||
2. 其余列 → 每行一个 `Map`;整体为 `List`。
|
||||
3. 须至少有一列字段(仅 `| 行 |` → 诊断)。
|
||||
4. 数据行数任意(含 0 → 空列表;1 行仍是 `List` of one `Map`,不是列向 `Map`)。
|
||||
|
||||
```markdown
|
||||
`订单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
| 2 | 梨 | 3 |
|
||||
```
|
||||
|
||||
→ `[{品名: 苹果, 数量: 2}, {品名: 梨, 数量: 3}]`。取元:`` `订单`[^1][^品名] ``。
|
||||
|
||||
---
|
||||
|
||||
## 4. 脚注取元(提案)
|
||||
|
||||
### 4.1 为何用脚注外形
|
||||
|
||||
- Markdown 已有 `[^…]` 引用形态,读者不陌生。
|
||||
- 避免 `篮子[0]` 与链接 / 图片语法纠缠。
|
||||
- 与「标识符反引号」组合清晰:`` `篮子`[^1] ``。
|
||||
|
||||
### 4.2 列表:按下标
|
||||
|
||||
```markdown
|
||||
*`第一` = `篮子`[^1] *
|
||||
> print text=`第一`
|
||||
```
|
||||
|
||||
| 约定 | 选择(提案) |
|
||||
|------|----------------|
|
||||
| 下标基准 | **1-based**(与 Markdown / 人类表格行语感一致;脚注 `[^1]` 即第一项) |
|
||||
| `[^0]` | 报错(保留 0 不用)或日后表示「最后一项」—— v1 **报错** |
|
||||
| 越界 | 清晰诊断 `path:line:col` |
|
||||
|
||||
### 4.3 字典:按键
|
||||
|
||||
键为脚注标签文本(推荐与表头一致;**允许纯数字键**,如基矢标签 `00`)。基名可写 `` `概率`[^00] `` 或 `` 概率[^00] ``(紧跟 `[^` 时可省略反引号):
|
||||
|
||||
```markdown
|
||||
*`种` = `分类`[^苹果] *
|
||||
*`p00` = `概率`[^00] *
|
||||
> print text=`种`
|
||||
```
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| `[^苹果]` | 键文本 `苹果` |
|
||||
| `[^00]` / `[^1]` | 键文本 `00` / `1`(**不是**「第 n 个 map 条目」) |
|
||||
| 含空格的键 | 允许 `[^数码用品]`;极端键用引号策略开工前定 |
|
||||
| 缺失键 | 报错或 `None`——建议 v1 **报错**(少静默) |
|
||||
|
||||
### 4.4 嵌套取元
|
||||
|
||||
列向字典套列表:
|
||||
|
||||
```markdown
|
||||
*`货架` = …多行横表… *
|
||||
*`第一种苹果` = `货架`[^苹果][^1] *
|
||||
```
|
||||
|
||||
从左到右:先键、再下标。
|
||||
类型不对(对 List 用非数字键名脚注)→ 诊断。Map 上的纯数字标签按**键名**解析。
|
||||
|
||||
### 4.5 与 GFM「定义脚注」正文
|
||||
|
||||
标准 Markdown 文末 `[^1]: 说明` 是**注释/文献**,不是取元。
|
||||
|
||||
规则:
|
||||
|
||||
- **表达式位置**的 `` `名`[^…] `` → 取元。
|
||||
- **文末脚注定义块** → 仍作注释(或不支持,避免混用)。
|
||||
- 不要求为每个 `[^1]` 写定义;Marqdo 取元**不依赖**定义块。
|
||||
|
||||
### 4.6 与 `lib/table` 关系
|
||||
|
||||
| 层 | 职责 |
|
||||
|----|------|
|
||||
| 语言脚注取元 | 一等、短、金样覆盖 |
|
||||
| `lib/table` | 行列切片、整表变换;可逐步把 `row_at` 文档改为「等价于脚注」 |
|
||||
|
||||
---
|
||||
|
||||
## 5. foreach 与字典
|
||||
|
||||
今日:`` [果](篮子) `` / `` [`果`](`篮子`) `` 遍历列表(裸名与反引号均可)。
|
||||
|
||||
扩展草案:
|
||||
|
||||
| 集合 | 遍历 |
|
||||
|------|------|
|
||||
| List | 不变,项为元素 |
|
||||
| Map | `` [`键`](`映射`) `` 遍历键;或 `` [`对`](`映射`) `` 若引入对类型—— v1 建议 **遍历键**,值用 `` `映射`[^…] `` / 辅助 |
|
||||
|
||||
具体键值对遍历语法开工前写一小段进 mapping;避免与链接外形 `` [`x`](`y`) `` 冲突(今日已是 foreach)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 推荐落地顺序
|
||||
|
||||
```text
|
||||
T0 横表单行 → Map;金样;竖表回归 ✅
|
||||
T1 横表多行 → Map of List(列向);嵌套金样 ✅
|
||||
T2 脚注取元:List [^n]、Map [^键]、链式 ✅
|
||||
T3 文档:markdown-mapping §9;Skill / examples;table 库 ✅
|
||||
T4 行向记录表:首列 `@` / `行` / `row` ✅
|
||||
T5 数据单元格 = 表达式(同调用实参值语法) ✅
|
||||
```
|
||||
|
||||
验收:
|
||||
|
||||
1. `tests/structure/collection.mq.md` 行为不变。
|
||||
2. 新金样:`collection-map.mq.md`、`collection-map-list.mq.md`、`footnote-index.mq.md`。
|
||||
3. 错误下标 / 缺键带 `line:col`。
|
||||
4. 双后端(tree / bytecode)一致。
|
||||
5. **T5:** 单元格 `` `var` `` / 算术;URL 与 `gpt-4o-mini` 仍为文本;设计见 [table-cell-expressions.md](../design/table-cell-expressions.md)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 教学对照(写入 Skill 的素材)
|
||||
|
||||
| 几何 | 含义 | 取元 |
|
||||
|------|------|------|
|
||||
| 单列竖表 | 列表 | `` `a`[^1] `` |
|
||||
| 多列 + 一行 | 字典 | `` `m`[^键] `` |
|
||||
| 多列 + 多行 | 字典 → 列表 | `` `m`[^键][^1] `` |
|
||||
| 首列 `@`/`行`/`row` | 记录列表 | `` `r`[^1][^字段] `` |
|
||||
|
||||
竖表表头是「元素名」;横表表头是「键名」——几何决定角色,减少「这张表到底是啥」的歧义。
|
||||
|
||||
---
|
||||
|
||||
## 8. 开放点
|
||||
|
||||
1. 表头重复列名:报错还是后缀 `_2`?建议 **报错**。
|
||||
2. 数字表头:字典键为文本 `"1"` 还是整数?建议 **文本**(与单元格一致)。
|
||||
3. 脚注 1-based 与宿主语言习惯(0-based)的文档警示。
|
||||
4. 字节码:`Index` / `KeyGet` 操作码是否与 T2 同批。
|
||||
|
||||
---
|
||||
|
||||
## 9. 与其它规划的关系
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [object-inheritance.md](object-inheritance.md) | 正交;表不表示类字段 schema |
|
||||
| [agent-streaming.md](agent-streaming.md) | 正交;事件列表可用竖表金样演示 foreach |
|
||||
| [okf-near-match.md](okf-near-match.md) | 正交 |
|
||||
@@ -0,0 +1,10 @@
|
||||
# quantum-bell
|
||||
|
||||
Bell |Φ⁺⟩ via `ext/quantum` circuit table + draw.
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_quantum
|
||||
marqdo run examples/quantum-bell/index.mq.md
|
||||
```
|
||||
|
||||
Writes `bell.svg` next to the program (sandbox cwd).
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: Bell state
|
||||
description: H then CX; probabilities ≈ 1/2; circuit SVG.
|
||||
> ext/quantum/quantum.mq.md
|
||||
> lib/math.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
# Bell |Φ+⟩
|
||||
|
||||
H on qubit 0, then CNOT(0→1). Ideal measurement: |00⟩ and |11⟩ each with probability 1/2.
|
||||
|
||||
# main
|
||||
|
||||
`steps` =
|
||||
|
||||
| step | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
|
||||
*`p` = > `qc`.probabilities *
|
||||
*`_` = > `qc`.draw path=bell.svg *
|
||||
*`_` = > `qc`.draw kind=probs path=bell-probs.svg *
|
||||
|
||||
> print text=`p`
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: GHZ state
|
||||
description: 3-qubit GHZ; |000⟩/|111⟩ ≈ 1/2; probs + H matrix heatmap.
|
||||
> ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# GHZ
|
||||
|
||||
H on qubit 0, CX(0→1), CX(0→2). Ideal: |000⟩ and |111⟩ each with probability 1/2.
|
||||
|
||||
# main
|
||||
|
||||
`steps` =
|
||||
|
||||
| step | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
| 3 | CX | 0,2 |
|
||||
|
||||
*`qc` = > quantum.circuit qubits=3 steps=`steps` *
|
||||
*`p` = > `qc`.probabilities *
|
||||
*`_` = > `qc`.draw path=ghz.svg *
|
||||
*`_` = > `qc`.draw kind=probs path=ghz-probs.svg *
|
||||
*`H` = > quantum.gate name=H *
|
||||
*`_` = > `H`.draw kind=matrix path=ghz-h-matrix.svg *
|
||||
|
||||
> print text=`p`
|
||||
@@ -0,0 +1,10 @@
|
||||
# examples/web-site-zh
|
||||
|
||||
中文作者面示例:只导入 `ext/web/网页.mq.md`(不用英文 `web.mq.md`)。
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_web
|
||||
cargo run -- examples/web-site-zh/index.mq.md
|
||||
```
|
||||
|
||||
打开 http://127.0.0.1:18082/ — `/about`、`/new`、`/admin`、`/static/site.css`。
|
||||
@@ -0,0 +1,9 @@
|
||||
## foot
|
||||
|
||||
`foot` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Marqdo | https://github.com | |
|
||||
|
||||
**`foot`**
|
||||
@@ -0,0 +1,12 @@
|
||||
## nav
|
||||
|
||||
`nav` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 首页 | / | |
|
||||
| 关于 | /about | |
|
||||
| 写文章 | /new | |
|
||||
| 后台 | /admin | |
|
||||
|
||||
**`nav`**
|
||||
@@ -0,0 +1,10 @@
|
||||
## side
|
||||
|
||||
`side` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 笔记 | / | |
|
||||
| 文档 | https://github.com | |
|
||||
|
||||
**`side`**
|
||||
@@ -0,0 +1,22 @@
|
||||
## schema
|
||||
|
||||
`fields` =
|
||||
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | integer | false |
|
||||
| title | text | false |
|
||||
| body | text | true |
|
||||
|
||||
**`fields`**
|
||||
|
||||
## seed
|
||||
|
||||
`rows` =
|
||||
|
||||
| id | title | body |
|
||||
|----|-------|------|
|
||||
| 1 | 你好 Marqdo | 第一篇来自 GFM 表格。 |
|
||||
| 2 | 代码即文档 | 页面表就是程序。 |
|
||||
|
||||
**`rows`**
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: db/index
|
||||
description: 打开 sqlite、建表、幂等种子。
|
||||
> ext/web/网页.mq.md
|
||||
> articles.mq.md as articles
|
||||
---
|
||||
|
||||
## open
|
||||
|
||||
*`store` = > 网页.数据库 地址="sqlite:data/site-zh.db" *
|
||||
*`fields` = > articles.schema *
|
||||
> `store`.初始化 名=articles 字段=`fields`
|
||||
*`rows` = > `store`.查询 表=articles 上限=1 *
|
||||
1. `rows`
|
||||
**`store`**
|
||||
2. *
|
||||
*`seed` = > articles.seed *
|
||||
> `store`.插入 表=articles 行=`seed`
|
||||
**`store`**
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: 中文站点示例
|
||||
description: Home + /about + /new(表单嵌入)+ 后台;只用 ext/web/网页.mq.md。
|
||||
> ext/web/网页.mq.md
|
||||
> styles/shell.mq.md
|
||||
> components/nav.mq.md
|
||||
> components/side.mq.md
|
||||
> components/foot.mq.md
|
||||
> db/articles.mq.md
|
||||
> db/index.mq.md as db
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`home` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`nav` | shell.`topnav` |
|
||||
| side.`side` | shell.`side_panel` |
|
||||
| foot.`foot` | |
|
||||
|
||||
`index` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| `title` | articles.`articles`.title | shell.`card_title` |
|
||||
| `body` | articles.`articles`.body | shell.`card_body` |
|
||||
|
||||
`article_fields` =
|
||||
|
||||
| 字段 | 标签 | 类型 | 必填 | 默认 |
|
||||
|------|------|------|------|------|
|
||||
| title | 标题 | text | true | |
|
||||
| body | 正文 | textarea | false | |
|
||||
|
||||
`article_rules` =
|
||||
|
||||
| 字段 | 规则 | 消息 |
|
||||
|------|------|------|
|
||||
| title | required | 标题不能为空 |
|
||||
| title | max:120 | 标题太长 |
|
||||
| body | max:8000 | 正文太长 |
|
||||
|
||||
*`store` = > db.open *
|
||||
*`page` = > 网页.页面 标题="Marqdo 中文站" 引言="<h1>中文站</h1><p>表格 + 类方法。</p>" *
|
||||
*`page` = > `page`.组件装配 组件=`home` *
|
||||
*`page` = > `page`.主体装配 主体=`index` *
|
||||
|
||||
*`about` = > 网页.页面 标题="关于" 引言="<h1>关于</h1><p>导入网页.mq.md 即用中文 API。</p>" *
|
||||
*`about` = > `about`.组件装配 组件=`home` *
|
||||
|
||||
*`article_form` = > 网页.表单 表=articles 动作=插入 *
|
||||
*`article_form` = > `article_form`.字段 字段=`article_fields` *
|
||||
*`article_form` = > `article_form`.规则 规则=`article_rules` *
|
||||
|
||||
*`new` = > 网页.页面 标题="写文章" 引言="<h1>写文章</h1><p>表单嵌在主区。</p>" *
|
||||
*`new` = > `new`.组件装配 组件=`home` *
|
||||
*`new` = > `new`.表单装配 id=article 表单=`article_form` *
|
||||
|
||||
*`app` = > 网页.应用 页面=`page` 数据库=`store` 后台=True 主机=127.0.0.1 端口=18082 *
|
||||
*`app` = > `app`.路由 路径=/about 页面=`about` *
|
||||
*`app` = > `app`.路由 路径=/new 页面=`new` *
|
||||
*`app` = > `app`.静态 目录=public 挂载=/static *
|
||||
> `app`.监听
|
||||
@@ -0,0 +1,5 @@
|
||||
/* 可选站点样式 — /static/site.css */
|
||||
body.site-hint::before {
|
||||
content: "static ok";
|
||||
display: none;
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
## topnav
|
||||
|
||||
`topnav` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #ffffff |
|
||||
| border-bottom | 1px solid #e7e5e4 |
|
||||
|
||||
**`topnav`**
|
||||
|
||||
## side_panel
|
||||
|
||||
`side_panel` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #f5f5f4 |
|
||||
|
||||
**`side_panel`**
|
||||
|
||||
## card_title
|
||||
|
||||
`card_title` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| font-size | 1.15rem |
|
||||
| margin | 0 0 0.35rem |
|
||||
|
||||
**`card_title`**
|
||||
|
||||
## card_body
|
||||
|
||||
`card_body` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| color | #57534e |
|
||||
| margin | 0 |
|
||||
|
||||
**`card_body`**
|
||||
@@ -0,0 +1,10 @@
|
||||
# examples/web-site
|
||||
|
||||
Canonical English sample for `ext/web` (design §4).
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_web
|
||||
cargo run -- examples/web-site/index.mq.md
|
||||
```
|
||||
|
||||
Then open http://127.0.0.1:18081/ — `/about`, `/new` (form in page slot), `/admin`, `/static/site.css`.
|
||||
@@ -0,0 +1,9 @@
|
||||
## foot
|
||||
|
||||
`foot` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Marqdo | https://github.com | |
|
||||
|
||||
**`foot`**
|
||||
@@ -0,0 +1,14 @@
|
||||
## nav
|
||||
|
||||
Static top links for the shell.
|
||||
|
||||
`nav` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Home | / | |
|
||||
| About | /about | |
|
||||
| New | /new | |
|
||||
| Admin | /admin | |
|
||||
|
||||
**`nav`**
|
||||
@@ -0,0 +1,10 @@
|
||||
## side
|
||||
|
||||
`side` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Notes | / | |
|
||||
| Docs | https://github.com | |
|
||||
|
||||
**`side`**
|
||||
@@ -0,0 +1,22 @@
|
||||
## schema
|
||||
|
||||
`fields` =
|
||||
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | integer | false |
|
||||
| title | text | false |
|
||||
| body | text | true |
|
||||
|
||||
**`fields`**
|
||||
|
||||
## seed
|
||||
|
||||
`rows` =
|
||||
|
||||
| id | title | body |
|
||||
|----|-------|------|
|
||||
| 1 | Hello Marqdo | First article from a GFM table. |
|
||||
| 2 | Code as docs | The page table is the program. |
|
||||
|
||||
**`rows`**
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: db/index
|
||||
description: Open sqlite, init articles, seed once.
|
||||
> ext/web/web.mq.md
|
||||
> articles.mq.md as articles
|
||||
> lib/fs.mq.md
|
||||
---
|
||||
|
||||
## open
|
||||
|
||||
*`store` = > web.db url="sqlite:data/site.db" *
|
||||
*`fields` = > articles.schema *
|
||||
> `store`.init name=articles fields=`fields`
|
||||
*`rows` = > `store`.select table=articles limit=1 *
|
||||
1. `rows`
|
||||
**`store`**
|
||||
2. *
|
||||
*`seed` = > articles.seed *
|
||||
> `store`.insert table=articles rows=`seed`
|
||||
**`store`**
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: web-site
|
||||
description: Home + /about + /new (form in page slot) + admin.
|
||||
> ext/web/web.mq.md
|
||||
> styles/shell.mq.md
|
||||
> components/nav.mq.md
|
||||
> components/side.mq.md
|
||||
> components/foot.mq.md
|
||||
> db/articles.mq.md
|
||||
> db/index.mq.md as db
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`home` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`nav` | shell.`topnav` |
|
||||
| side.`side` | shell.`side_panel` |
|
||||
| foot.`foot` | |
|
||||
|
||||
Main content is not a reusable component, so it is authored here.
|
||||
|
||||
`index` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| `title` | articles.`articles`.title | shell.`card_title` |
|
||||
| `body` | articles.`articles`.body | shell.`card_body` |
|
||||
|
||||
Article create form (design §5.5): field table + rules table.
|
||||
|
||||
`article_fields` =
|
||||
|
||||
| 字段 | 标签 | 类型 | 必填 | 默认 |
|
||||
|------|------|------|------|------|
|
||||
| title | Title | text | true | |
|
||||
| body | Body | textarea | false | |
|
||||
|
||||
`article_rules` =
|
||||
|
||||
| 字段 | 规则 | 消息 |
|
||||
|------|------|------|
|
||||
| title | required | Title is required |
|
||||
| title | max:120 | Title is too long |
|
||||
| body | max:8000 | Body is too long |
|
||||
|
||||
*`store` = > db.open *
|
||||
*`page` = > web.page title="Marqdo Web Site" intro="<h1>Web Site</h1><p>Tables + class methods.</p>" *
|
||||
*`page` = > `page`.compose_components components=`home` *
|
||||
*`page` = > `page`.compose_main main=`index` *
|
||||
|
||||
About page: same shell, different intro (no main bind).
|
||||
|
||||
*`about` = > web.page title="About" intro="<h1>About</h1><p>Marqdo web = tables + class methods.</p>" *
|
||||
*`about` = > `about`.compose_components components=`home` *
|
||||
|
||||
*`article_form` = > web.form table=articles action=insert *
|
||||
*`article_form` = > `article_form`.fields fields=`article_fields` *
|
||||
*`article_form` = > `article_form`.rules rules=`article_rules` *
|
||||
|
||||
New article: form embedded in the page main slot (design §5.5.4).
|
||||
|
||||
*`new` = > web.page title="New article" intro="<h1>New article</h1><p>Form lives in the main slot.</p>" *
|
||||
*`new` = > `new`.compose_components components=`home` *
|
||||
*`new` = > `new`.compose_form id=article form=`article_form` *
|
||||
|
||||
*`app` = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
|
||||
*`app` = > `app`.route path=/about page=`about` *
|
||||
*`app` = > `app`.route path=/new page=`new` *
|
||||
*`app` = > `app`.static dir=public mount=/static *
|
||||
> `app`.listen
|
||||
@@ -0,0 +1,5 @@
|
||||
/* Optional site stylesheet — served at /static/site.css */
|
||||
body.site-hint::before {
|
||||
content: "static ok";
|
||||
display: none;
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
## topnav
|
||||
|
||||
`topnav` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #ffffff |
|
||||
| border-bottom | 1px solid #e7e5e4 |
|
||||
|
||||
**`topnav`**
|
||||
|
||||
## side_panel
|
||||
|
||||
`side_panel` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #f5f5f4 |
|
||||
|
||||
**`side_panel`**
|
||||
|
||||
## card_title
|
||||
|
||||
`card_title` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| font-size | 1.15rem |
|
||||
| margin | 0 0 0.35rem |
|
||||
|
||||
**`card_title`**
|
||||
|
||||
## card_body
|
||||
|
||||
`card_body` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| color | #57534e |
|
||||
| margin | 0 |
|
||||
|
||||
**`card_body`**
|
||||
+1859
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,126 @@
|
||||
---
|
||||
title: ext/ai/llm
|
||||
description: OpenAI-compatible LLM object (English). Import ext/ai/llm.mq.md.
|
||||
> lib/sys.mq.md
|
||||
> lib/net.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/table.mq.md
|
||||
---
|
||||
|
||||
## load_env
|
||||
+ `path`=None
|
||||
|
||||
Load `.env` from cwd (optional named arg `path=`). Does not override existing variables.
|
||||
|
||||
**> sys.load_dotenv path=`path`**
|
||||
|
||||
## stream_result
|
||||
+ `events`
|
||||
|
||||
Reduce a `complete stream=True` event list to the final `done.result` text (or `error.message`). Unknown event types abort.
|
||||
|
||||
*answer = ""*
|
||||
|
||||
- [ev](events)
|
||||
*t = ev[^type]*
|
||||
1. `t` == "done"
|
||||
*answer = ev[^result]*
|
||||
2. `t` == "error"
|
||||
*answer = ev[^message]*
|
||||
3. `t` == "delta"
|
||||
4. *
|
||||
> print text=ext/ai/llm: unexpected SSE event type
|
||||
> print text=`t`
|
||||
> sys.exit code=1
|
||||
|
||||
**answer**
|
||||
|
||||
# llm
|
||||
|
||||
Construct an LLM handle from `OPENAI_*` / `MARQDO_LLM_*`.
|
||||
|
||||
*api_key = > sys.env_get name=OPENAI_API_KEY*
|
||||
1. not `api_key`
|
||||
*api_key = > sys.env_get name=MARQDO_LLM_API_KEY*
|
||||
|
||||
1. not `api_key`
|
||||
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY
|
||||
> sys.exit code=1
|
||||
|
||||
*base_url = > sys.env_get name=OPENAI_BASE_URL*
|
||||
1. not `base_url`
|
||||
*base_url = > sys.env_get name=MARQDO_LLM_BASE_URL*
|
||||
1. not `base_url`
|
||||
*base_url = "https://api.openai.com/v1"*
|
||||
|
||||
*model = > sys.env_get name=OPENAI_MODEL*
|
||||
1. not `model`
|
||||
*model = > sys.env_get name=MARQDO_LLM_MODEL*
|
||||
1. not `model`
|
||||
*model = "gpt-4o-mini"*
|
||||
|
||||
`h` =
|
||||
|
||||
| api_key | base_url | model | suffix | bearer |
|
||||
|---------|----------|-------|--------|--------|
|
||||
| `api_key` | `base_url` | `model` | /chat/completions | "Bearer " |
|
||||
|
||||
**h**
|
||||
|
||||
## complete
|
||||
+ `prompt`
|
||||
+ `stream`=False
|
||||
+ `echo`=False
|
||||
|
||||
Chat completion using `self` handle fields.
|
||||
|
||||
Wire body is `{model, messages:[{role,content}], stream?}`. Messages are an `@` row table; headers and optional `stream` use `table.put`. `json` is only for stringify/parse.
|
||||
|
||||
*url = self[^base_url] + self[^suffix]*
|
||||
*auth = self[^bearer] + self[^api_key]*
|
||||
*headers = > table.put in=None at=Authorization value=`auth`*
|
||||
|
||||
`messages` =
|
||||
|
||||
| @ | role | content |
|
||||
|---|------|---------|
|
||||
| 1 | user | `prompt` |
|
||||
|
||||
`req` =
|
||||
|
||||
| model | messages |
|
||||
|-------|----------|
|
||||
| self[^model] | `messages` |
|
||||
|
||||
1. `stream`
|
||||
*req = > table.put in=`req` at=stream value=True*
|
||||
*body = > json.stringify value=`req`*
|
||||
*resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`*
|
||||
1. resp[^status] == 200
|
||||
**resp[^events]**
|
||||
2. *
|
||||
> print text=ext/ai/llm: HTTP error (stream)
|
||||
> print text=resp[^status]
|
||||
> sys.exit code=1
|
||||
2. *
|
||||
*body = > json.stringify value=`req`*
|
||||
*resp = > net.http_post url=`url` body=`body` headers=`headers`*
|
||||
1. resp[^status] == 200
|
||||
*data = > json.parse text=resp[^body]*
|
||||
**data[^choices][^1][^message][^content]**
|
||||
2. *
|
||||
> print text=ext/ai/llm: HTTP error
|
||||
> print text=resp[^status]
|
||||
> print text=resp[^body]
|
||||
> sys.exit code=1
|
||||
|
||||
---
|
||||
|
||||
## chat
|
||||
+ `prompt`
|
||||
+ `stream`=False
|
||||
+ `echo`=False
|
||||
|
||||
Alias for `complete`.
|
||||
|
||||
**> `self`.complete prompt=`prompt` stream=`stream` echo=`echo`**
|
||||
@@ -0,0 +1,126 @@
|
||||
---
|
||||
title: ext/ai/大模型
|
||||
description: OpenAI 兼容大模型对象(中文)。导入 ext/ai/大模型.mq.md。
|
||||
> lib/系统.mq.md
|
||||
> lib/网络.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/表.mq.md
|
||||
---
|
||||
|
||||
## 加载环境
|
||||
+ `路径`=None
|
||||
|
||||
从工作目录加载 `.env`(可选命名实参 `路径=`)。不覆盖已有变量。
|
||||
|
||||
**> 系统.加载环境 路径=`路径`**
|
||||
|
||||
## 流式结果
|
||||
+ `事件`
|
||||
|
||||
把 `运行 流式=真` 的事件列表收成最终 `done.result`(或 `error.message`)。未知事件类型直接失败。
|
||||
|
||||
*answer = ""*
|
||||
|
||||
- [ev](事件)
|
||||
*t = ev[^type]*
|
||||
1. `t` == "done"
|
||||
*answer = ev[^result]*
|
||||
2. `t` == "error"
|
||||
*answer = ev[^message]*
|
||||
3. `t` == "delta"
|
||||
4. *
|
||||
> 打印 内容=ext/ai/大模型: 未预期的 SSE 事件类型
|
||||
> 打印 内容=`t`
|
||||
> 系统.退出 码=1
|
||||
|
||||
**answer**
|
||||
|
||||
# 大模型
|
||||
|
||||
从 `OPENAI_*` / `MARQDO_LLM_*` 构造句柄。
|
||||
|
||||
*api_key = > 系统.取环境 名=OPENAI_API_KEY*
|
||||
1. 非 `api_key`
|
||||
*api_key = > 系统.取环境 名=MARQDO_LLM_API_KEY*
|
||||
|
||||
1. 非 `api_key`
|
||||
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
|
||||
> 系统.退出 码=1
|
||||
|
||||
*base_url = > 系统.取环境 名=OPENAI_BASE_URL*
|
||||
1. 非 `base_url`
|
||||
*base_url = > 系统.取环境 名=MARQDO_LLM_BASE_URL*
|
||||
1. 非 `base_url`
|
||||
*base_url = "https://api.openai.com/v1"*
|
||||
|
||||
*model = > 系统.取环境 名=OPENAI_MODEL*
|
||||
1. 非 `model`
|
||||
*model = > 系统.取环境 名=MARQDO_LLM_MODEL*
|
||||
1. 非 `model`
|
||||
*model = "gpt-4o-mini"*
|
||||
|
||||
`h` =
|
||||
|
||||
| api_key | base_url | model | suffix | bearer |
|
||||
|---------|----------|-------|--------|--------|
|
||||
| `api_key` | `base_url` | `model` | /chat/completions | "Bearer " |
|
||||
|
||||
**h**
|
||||
|
||||
## 运行
|
||||
+ `提示`
|
||||
+ `流式`=False
|
||||
+ `打印增量`=False
|
||||
|
||||
使用 `自` 句柄字段做聊天补全。
|
||||
|
||||
线上 body 为 `{model, messages:[{role,content}], stream?}`。消息用 `@` 行向表;headers 与可选 `stream` 用 `表.改`。`json` 只做 stringify/parse。
|
||||
|
||||
*url = 自[^base_url] + 自[^suffix]*
|
||||
*auth = 自[^bearer] + 自[^api_key]*
|
||||
*headers = > 表.改 入=None 于=Authorization 值=`auth`*
|
||||
|
||||
`messages` =
|
||||
|
||||
| @ | role | content |
|
||||
|---|------|---------|
|
||||
| 1 | user | `提示` |
|
||||
|
||||
`req` =
|
||||
|
||||
| model | messages |
|
||||
|-------|----------|
|
||||
| 自[^model] | `messages` |
|
||||
|
||||
1. `流式`
|
||||
*req = > 表.改 入=`req` 于=stream 值=True*
|
||||
*body = > json.stringify value=`req`*
|
||||
*resp = > 网络.提交流式 地址=`url` 内容=`body` headers=`headers` 打印增量=`打印增量`*
|
||||
1. resp[^status] == 200
|
||||
**resp[^events]**
|
||||
2. *
|
||||
> 打印 内容=ext/ai/大模型: HTTP 错误(流式)
|
||||
> 打印 内容=resp[^status]
|
||||
> 系统.退出 码=1
|
||||
2. *
|
||||
*body = > json.stringify value=`req`*
|
||||
*resp = > 网络.提交 地址=`url` 内容=`body` headers=`headers`*
|
||||
1. resp[^status] == 200
|
||||
*data = > json.parse text=resp[^body]*
|
||||
**data[^choices][^1][^message][^content]**
|
||||
2. *
|
||||
> 打印 内容=ext/ai/大模型: HTTP 错误
|
||||
> 打印 内容=resp[^status]
|
||||
> 打印 内容=resp[^body]
|
||||
> 系统.退出 码=1
|
||||
|
||||
---
|
||||
|
||||
## 聊天
|
||||
+ `提示`
|
||||
+ `流式`=False
|
||||
+ `打印增量`=False
|
||||
|
||||
运行 的别名。
|
||||
|
||||
**> `自`.运行 提示=`提示` 流式=`流式` 打印增量=`打印增量`**
|
||||
@@ -0,0 +1,235 @@
|
||||
---
|
||||
title: ext/ai/智能体
|
||||
description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务;运行时经 ABI v2 agent 插件。
|
||||
> ext/ai/大模型.mq.md
|
||||
> ext/ai/agent.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/系统.mq.md
|
||||
> lib/自写回.mq.md
|
||||
> lib/子任务.mq.md
|
||||
> lib/插件.mq.md
|
||||
---
|
||||
|
||||
## 构建单步上下文
|
||||
+ `智能体`
|
||||
+ `任务`
|
||||
|
||||
组装可读提示:站立提示、任务、工具、调用位置、源码、Skill,以及人可见的行动约定。
|
||||
|
||||
*`standing` = > json.get value=`智能体` key=standing *
|
||||
1. `standing`
|
||||
*`up` = `standing`*
|
||||
2. *
|
||||
*`up` = 空*
|
||||
|
||||
*`tools` = > json.get value=`智能体` key=tools *
|
||||
*`tools_s` = > agent_format_tools tools=`tools` *
|
||||
*`src` = > agent_module_source *
|
||||
*`site` = > agent_call_site *
|
||||
*`site_s` = > json.stringify value=`site` *
|
||||
*`skill` = > agent_marqdo_skill *
|
||||
*`task_s` = > json.stringify value=`任务` *
|
||||
|
||||
*`esc` = > json.parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- task ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source (.mq.md) ---\n","f":"\n\n--- marqdo skill ---\n","g":"\n\n--- how to act ---\nTools are ## functions in the source above. To call one, reply with exactly one line: CALL:<name>\n(Chinese ok: 调用:<name>)\nOtherwise reply with the final answer only.\nTools run via Marqdo subtask (spawn fn / wait).\n"} *
|
||||
*`a` = > json.get value=`esc` key=a *
|
||||
*`b` = > json.get value=`esc` key=b *
|
||||
*`c` = > json.get value=`esc` key=c *
|
||||
*`d` = > json.get value=`esc` key=d *
|
||||
*`e` = > json.get value=`esc` key=e *
|
||||
*`f` = > json.get value=`esc` key=f *
|
||||
*`g` = > json.get value=`esc` key=g *
|
||||
|
||||
*`p` = "You are a Marqdo agent. The runbook source is your ground truth — code is documentation." *
|
||||
*`p` = `p` + `a` + `up` + `b` + `task_s` + `c` + `tools_s` + `g` + `d` + `site_s` + `e` + `src` + `f` + `skill` *
|
||||
**`p`**
|
||||
|
||||
---
|
||||
|
||||
## 提取工具名
|
||||
+ `回复`
|
||||
|
||||
解析人可读调用行:`CALL:<名>` 或 `调用:<名>` / `调用:<名>`。
|
||||
|
||||
*`esc` = > json.parse text={"nl":"\n"} *
|
||||
*`nl` = > json.get value=`esc` key=nl *
|
||||
*`text` = > trim value=`回复` *
|
||||
*`lines` = > split value=`text` sep=`nl` *
|
||||
*`found` = 空*
|
||||
|
||||
- [`line`](`lines`)
|
||||
*`t` = > trim value=`line` *
|
||||
*`parts` = > split value=`t` sep=: *
|
||||
*`n` = > len value=`parts` *
|
||||
1. `n` > 1
|
||||
*`head` = > at value=`parts` index=0 *
|
||||
*`head` = > trim value=`head` *
|
||||
*`rest` = > at value=`parts` index=1 *
|
||||
*`rest` = > trim value=`rest` *
|
||||
1. `head` == CALL
|
||||
*`found` = `rest`*
|
||||
2. `head` == 调用
|
||||
*`found` = `rest`*
|
||||
3. *
|
||||
*`_` = 1*
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`found`**
|
||||
|
||||
---
|
||||
|
||||
## 运行工具
|
||||
+ `工具`
|
||||
+ `名`
|
||||
|
||||
白名单校验后,经 `lib/子任务`(`启动 函数=` → `等待`)调用 runbook 中的 `##`。
|
||||
|
||||
*`allowed` = > agent_tool_allowed tools=`工具` name=`名` *
|
||||
1. `allowed`
|
||||
*`id` = > 子任务.启动 函数=`名` *
|
||||
**> 子任务.等待 id=`id`**
|
||||
2. *
|
||||
*`msg` = "Tool not allowed:" *
|
||||
**`msg` + `名`**
|
||||
|
||||
# 智能体
|
||||
+ `大模型`
|
||||
+ `工具`
|
||||
+ `站立提示`
|
||||
|
||||
加载 ABI v2 agent 插件(会话袋 + 上下文查询)。
|
||||
|
||||
*`p` = > 插件.原生路径 名=agent *
|
||||
1. `p`
|
||||
> 插件.加载 路径=`p`
|
||||
2. *
|
||||
> 打印 内容=ext/ai/智能体: 未找到原生 agent 插件(请先 cargo build -p marqdo_plugin_agent 或 marqdo ext add agent)
|
||||
> 系统.退出 码=1
|
||||
|
||||
*`id` = > agent_alloc *
|
||||
*`h` = > json.parse text={"_type":"智能体"} *
|
||||
*`h` = > json.set map=`h` key=id value=`id` *
|
||||
*`h` = > json.set map=`h` key=model value=`大模型` *
|
||||
*`h` = > json.set map=`h` key=tools value=`工具` *
|
||||
|
||||
1. `站立提示`
|
||||
*`h` = > json.set map=`h` key=standing value=`站立提示` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`h`**
|
||||
|
||||
## 清空历史
|
||||
|
||||
清空本智能体 id 的插件会话袋。
|
||||
|
||||
*`id` = > json.get value=`自` key=id *
|
||||
> agent_history_clear id=`id`
|
||||
****
|
||||
|
||||
## 单步
|
||||
+ `任务`
|
||||
+ `写回`=真
|
||||
+ `流式`=假
|
||||
+ `打印增量`=假
|
||||
|
||||
原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 **map**(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。默认(`写回=真`)将结果写入调用行下的命名槽 `ok` / `error`;传 `写回=假` 可关闭。
|
||||
|
||||
流式=真 时走 SSE;打印增量=真 边读边打印。返回 map 仍是最终 result 文本。
|
||||
|
||||
*`ctx` = > 构建单步上下文 智能体=`自` 任务=`任务` *
|
||||
*`id` = > json.get value=`自` key=id *
|
||||
*`model` = > json.get value=`自` key=model *
|
||||
*`tools` = > json.get value=`自` key=tools *
|
||||
|
||||
*`user_turn` = > json.parse text={"role":"user"} *
|
||||
*`user_turn` = > json.set map=`user_turn` key=content value=`任务` *
|
||||
> agent_history_append id=`id` item=`user_turn`
|
||||
|
||||
1. `流式`
|
||||
*`evs` = > `model`.运行 提示=`ctx` 流式=真 打印增量=`打印增量` *
|
||||
*`reply` = > 大模型.流式结果 事件=`evs` *
|
||||
2. *
|
||||
*`reply` = > `model`.运行 提示=`ctx` *
|
||||
|
||||
*`reply` = > trim value=`reply` *
|
||||
*`decision` = `reply`*
|
||||
*`tool_name` = > 提取工具名 回复=`reply` *
|
||||
*`out` = > json.parse text={"status":"ok"} *
|
||||
*`out` = > json.set map=`out` key=task value=`任务` *
|
||||
*`out` = > json.set map=`out` key=decision value=`decision` *
|
||||
|
||||
1. `tool_name`
|
||||
*`tool_out` = > 运行工具 工具=`tools` 名=`tool_name` *
|
||||
*`tool_s` = > json.stringify value=`tool_out` *
|
||||
*`deny` = > split value=`tool_s` sep=Tool not allowed *
|
||||
*`deny_n` = > len value=`deny` *
|
||||
1. `deny_n` > 1
|
||||
*`out` = > json.set map=`out` key=status value=error *
|
||||
*`out` = > json.set map=`out` key=error value=`tool_s` *
|
||||
*`reply` = `tool_s`*
|
||||
2. *
|
||||
*`task_s` = > json.stringify value=`任务` *
|
||||
*`fp` = "The user asked:" *
|
||||
*`fp` = `fp` + `task_s` *
|
||||
*`fp` = `fp` + ". Tool" *
|
||||
*`fp` = `fp` + `tool_name` *
|
||||
*`fp` = `fp` + "ran via subtask and returned:" *
|
||||
*`fp` = `fp` + `tool_s` *
|
||||
*`fp` = `fp` + ". Reply to the user briefly." *
|
||||
1. `流式`
|
||||
*`evs2` = > `model`.运行 提示=`fp` 流式=真 打印增量=`打印增量` *
|
||||
*`reply` = > 大模型.流式结果 事件=`evs2` *
|
||||
2. *
|
||||
*`reply` = > `model`.运行 提示=`fp` *
|
||||
*`out` = > json.set map=`out` key=tool value=`tool_name` *
|
||||
*`out` = > json.set map=`out` key=tool_result value=`tool_s` *
|
||||
*`out` = > json.set map=`out` key=result value=`reply` *
|
||||
2. *
|
||||
*`out` = > json.set map=`out` key=result value=`reply` *
|
||||
|
||||
*`as_turn` = > json.parse text={"role":"assistant"} *
|
||||
*`as_turn` = > json.set map=`as_turn` key=content value=`reply` *
|
||||
> agent_history_append id=`id` item=`as_turn`
|
||||
|
||||
1. `写回`
|
||||
*`body` = > json.stringify value=`out` *
|
||||
*`st` = > json.get value=`out` key=status *
|
||||
1. `st` == ok
|
||||
> 自写回.写回 值=`body` 键=ok
|
||||
2. *
|
||||
> 自写回.写回 值=`body` 键=error
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`out`**
|
||||
|
||||
## 多步
|
||||
+ `目标`
|
||||
+ `工作簿目录`=None
|
||||
+ `工作簿`=None
|
||||
+ `最大轮次`=4
|
||||
+ `确认分解`=False
|
||||
+ `写回`=True
|
||||
+ `骨架`=single
|
||||
+ `复用`=True
|
||||
+ `优化`=False
|
||||
+ `强制`=False
|
||||
+ `软命中`=False
|
||||
+ `近义命中`=True
|
||||
+ `近义阈值`=0.78
|
||||
+ `晋升`=True
|
||||
+ `知识库目录`=.marqdo/agent-kb
|
||||
+ `改进周期`=3
|
||||
+ `探索次数`=3
|
||||
+ `流式`=False
|
||||
+ `打印增量`=False
|
||||
+ `轨迹`=False
|
||||
|
||||
多步工作簿默认写入 OKF `知识库目录/resources/<slug>.mq.md`;仅当传入 `工作簿目录` 时才用临时 runs。转发至英文 `agent.plan`。`流式` / `打印增量` / `轨迹` 对应 `stream` / `echo` / `trace`;`软命中` → `soft_match`;`近义命中` / `近义阈值` → `near_match` / `near_threshold`。
|
||||
|
||||
*`model` = > json.get value=`self` key=model *
|
||||
*`tools` = > json.get value=`self` key=tools *
|
||||
*`standing` = > json.get value=`self` key=standing *
|
||||
*`en` = > agent.agent model=`model` tools=`tools` standing=`standing` *
|
||||
**> `en`.plan goal=`目标` workbook_dir=`工作簿目录` workbook=`工作簿` max_rounds=`最大轮次` confirm=`确认分解` writeback=`写回` skeleton=`骨架` reuse=`复用` optimize=`优化` force=`强制` soft_match=`软命中` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` kb_dir=`知识库目录` improve_every=`改进周期` explore_n=`探索次数` stream=`流式` echo=`打印增量` trace=`轨迹`**
|
||||
@@ -0,0 +1,201 @@
|
||||
---
|
||||
title: ext/quantum/quantum
|
||||
description: Official quantum circuit simulator (English). Gates + circuits; ABI plugin.
|
||||
> lib/plugin.mq.md
|
||||
> lib/sys.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## ensure_plugin
|
||||
|
||||
Load the ABI v2 `quantum` plugin once.
|
||||
|
||||
*`p` = > plugin.native_path name=quantum *
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/quantum: native quantum plugin not found (build marqdo_plugin_quantum or marqdo ext add quantum)
|
||||
> sys.exit code=1
|
||||
****
|
||||
|
||||
# circuit
|
||||
+ `qubits`=1
|
||||
+ `steps`=None
|
||||
|
||||
State-vector circuit (default |0…0⟩). Optional `steps=` gate table (column or row records). Methods append gates and return an updated handle.
|
||||
|
||||
> ensure_plugin
|
||||
**> quantum_circuit_new qubits=`qubits` steps=`steps`**
|
||||
|
||||
## h
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_h circuit=`self` qubit=`qubit`**
|
||||
|
||||
## x
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_x circuit=`self` qubit=`qubit`**
|
||||
|
||||
## y
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_y circuit=`self` qubit=`qubit`**
|
||||
|
||||
## z
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_z circuit=`self` qubit=`qubit`**
|
||||
|
||||
## s
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_s circuit=`self` qubit=`qubit`**
|
||||
|
||||
## t
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_t circuit=`self` qubit=`qubit`**
|
||||
|
||||
## i
|
||||
+ `qubit`=0
|
||||
|
||||
**> quantum_i circuit=`self` qubit=`qubit`**
|
||||
|
||||
## rx
|
||||
+ `qubit`=0
|
||||
+ `theta`
|
||||
|
||||
**> quantum_rx circuit=`self` qubit=`qubit` theta=`theta`**
|
||||
|
||||
## ry
|
||||
+ `qubit`=0
|
||||
+ `theta`
|
||||
|
||||
**> quantum_ry circuit=`self` qubit=`qubit` theta=`theta`**
|
||||
|
||||
## rz
|
||||
+ `qubit`=0
|
||||
+ `theta`
|
||||
|
||||
**> quantum_rz circuit=`self` qubit=`qubit` theta=`theta`**
|
||||
|
||||
## cx
|
||||
+ `control`=0
|
||||
+ `target`=1
|
||||
|
||||
**> quantum_cx circuit=`self` control=`control` target=`target`**
|
||||
|
||||
## cz
|
||||
+ `control`=0
|
||||
+ `target`=1
|
||||
|
||||
**> quantum_cz circuit=`self` control=`control` target=`target`**
|
||||
|
||||
## swap
|
||||
+ `a`=0
|
||||
+ `b`=1
|
||||
|
||||
**> quantum_swap circuit=`self` a=`a` b=`b`**
|
||||
|
||||
## barrier
|
||||
|
||||
Visual separator only (no state change).
|
||||
|
||||
**> quantum_barrier circuit=`self`**
|
||||
|
||||
## measure
|
||||
+ `qubits`=None
|
||||
|
||||
Mark computational-basis readout (`None` / empty = all qubits). Affects which bits `run` reports.
|
||||
|
||||
**> quantum_measure circuit=`self` qubits=`qubits`**
|
||||
|
||||
## append
|
||||
+ `op`
|
||||
|
||||
Append another circuit's ops or a `{gate,qubits}` op map.
|
||||
|
||||
**> quantum_append circuit=`self` op=`op`**
|
||||
|
||||
## apply
|
||||
+ `gate`
|
||||
+ `qubits`=0
|
||||
|
||||
Apply a gate handle (named or custom `matrix=`) on `qubits` (int or list).
|
||||
|
||||
**> quantum_apply circuit=`self` gate=`gate` qubits=`qubits`**
|
||||
|
||||
## noise
|
||||
+ `kind`
|
||||
+ `p`
|
||||
|
||||
Teaching noise for `run` trajectories (`bitflip` / `depolarizing` / `amplitude_damping`). Ignored by `simulate` / `probabilities`.
|
||||
|
||||
**> quantum_noise circuit=`self` kind=`kind` p=`p`**
|
||||
|
||||
## simulate
|
||||
|
||||
Return state vector amplitudes `{re,im}` (ideal; no noise).
|
||||
|
||||
**> quantum_simulate circuit=`self`**
|
||||
|
||||
## state
|
||||
|
||||
Ideal state vector (same amplitudes as `simulate`).
|
||||
|
||||
**> quantum_state circuit=`self`**
|
||||
|
||||
## probabilities
|
||||
|
||||
Return map of basis label → probability (qubit 0 = rightmost bit). Ideal; ignores noise.
|
||||
|
||||
**> quantum_probabilities circuit=`self`**
|
||||
|
||||
## run
|
||||
+ `shots`=1024
|
||||
+ `seed`=1
|
||||
|
||||
Sample computational-basis shots (deterministic with `seed=`). Applies circuit `noise` if set.
|
||||
|
||||
**> quantum_run circuit=`self` shots=`shots` seed=`seed`**
|
||||
|
||||
## draw
|
||||
+ `path`=None
|
||||
+ `kind`=circuit
|
||||
+ `qubit`=0
|
||||
|
||||
Circuit rail / probability bars / Bloch sphere SVG (`kind=circuit|probs|bloch`). Records into view/CLI plots via host `record_plot`.
|
||||
|
||||
**> quantum_draw_circuit circuit=`self` path=`path` kind=`kind` qubit=`qubit`**
|
||||
|
||||
# gate
|
||||
+ `name`=None
|
||||
+ `theta`=None
|
||||
+ `matrix`=None
|
||||
|
||||
Named built-in gate (`name=H`) or custom unitary from `matrix=` (nested list / `$$` matrix fence). Optional `name=` label for custom gates (default `U`).
|
||||
|
||||
> ensure_plugin
|
||||
1. `matrix`
|
||||
**> quantum_gate_from_matrix matrix=`matrix` name=`name`**
|
||||
2. *
|
||||
**> quantum_gate_new name=`name` theta=`theta`**
|
||||
|
||||
## matrix
|
||||
|
||||
**> quantum_gate_matrix gate=`self`**
|
||||
|
||||
## matches_matrix
|
||||
+ `matrix`
|
||||
+ `tol`=0.000000001
|
||||
|
||||
**> quantum_gate_matches_matrix gate=`self` matrix=`matrix` tol=`tol`**
|
||||
|
||||
## draw
|
||||
+ `path`=None
|
||||
+ `kind`=gate
|
||||
|
||||
Gate glyph or complex-matrix heatmap (`kind=gate|matrix`). Records via host `record_plot`.
|
||||
|
||||
**> quantum_gate_draw gate=`self` path=`path` kind=`kind`**
|
||||
@@ -0,0 +1,201 @@
|
||||
---
|
||||
title: ext/quantum/量子
|
||||
description: 官方量子电路模拟(中文)。门 + 电路;ABI 插件。
|
||||
> lib/plugin.mq.md
|
||||
> lib/sys.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## 确保插件
|
||||
|
||||
加载 ABI v2 `quantum` 插件。
|
||||
|
||||
*`p` = > plugin.native_path name=quantum *
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/quantum: 未找到原生 quantum 插件(请 build marqdo_plugin_quantum 或 marqdo ext add quantum)
|
||||
> sys.exit code=1
|
||||
****
|
||||
|
||||
# 电路
|
||||
+ `比特数`=1
|
||||
+ `步骤`=None
|
||||
|
||||
状态向量电路(默认 |0…0⟩)。可选 `步骤=` 门序列表。方法追加门并返回更新后的句柄。
|
||||
|
||||
> 确保插件
|
||||
**> quantum_circuit_new qubits=`比特数` steps=`步骤`**
|
||||
|
||||
## 哈达玛
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_h circuit=`self` qubit=`比特`**
|
||||
|
||||
## 泡利X
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_x circuit=`self` qubit=`比特`**
|
||||
|
||||
## 泡利Y
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_y circuit=`self` qubit=`比特`**
|
||||
|
||||
## 泡利Z
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_z circuit=`self` qubit=`比特`**
|
||||
|
||||
## 相位S
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_s circuit=`self` qubit=`比特`**
|
||||
|
||||
## 相位T
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_t circuit=`self` qubit=`比特`**
|
||||
|
||||
## 单位
|
||||
+ `比特`=0
|
||||
|
||||
**> quantum_i circuit=`self` qubit=`比特`**
|
||||
|
||||
## 绕X
|
||||
+ `比特`=0
|
||||
+ `参数`
|
||||
|
||||
**> quantum_rx circuit=`self` qubit=`比特` theta=`参数`**
|
||||
|
||||
## 绕Y
|
||||
+ `比特`=0
|
||||
+ `参数`
|
||||
|
||||
**> quantum_ry circuit=`self` qubit=`比特` theta=`参数`**
|
||||
|
||||
## 绕Z
|
||||
+ `比特`=0
|
||||
+ `参数`
|
||||
|
||||
**> quantum_rz circuit=`self` qubit=`比特` theta=`参数`**
|
||||
|
||||
## 控非
|
||||
+ `控制`=0
|
||||
+ `目标`=1
|
||||
|
||||
**> quantum_cx circuit=`self` control=`控制` target=`目标`**
|
||||
|
||||
## 控相
|
||||
+ `控制`=0
|
||||
+ `目标`=1
|
||||
|
||||
**> quantum_cz circuit=`self` control=`控制` target=`目标`**
|
||||
|
||||
## 交换
|
||||
+ `比特甲`=0
|
||||
+ `比特乙`=1
|
||||
|
||||
**> quantum_swap circuit=`self` a=`比特甲` b=`比特乙`**
|
||||
|
||||
## 屏障
|
||||
|
||||
仅可视化分隔(不改态)。
|
||||
|
||||
**> quantum_barrier circuit=`self`**
|
||||
|
||||
## 测量
|
||||
+ `比特`=None
|
||||
|
||||
标记计算基读出(空 = 全部比特)。影响 `运行` 报告哪些位。
|
||||
|
||||
**> quantum_measure circuit=`self` qubits=`比特`**
|
||||
|
||||
## 追加
|
||||
+ `操作`
|
||||
|
||||
追加另一电路的 ops,或 `{gate,qubits}` 操作表。
|
||||
|
||||
**> quantum_append circuit=`self` op=`操作`**
|
||||
|
||||
## 施加
|
||||
+ `门`
|
||||
+ `比特`=0
|
||||
|
||||
将门句柄(具名或 `矩阵=` 自定义)施加到 `比特`(整数或列表)。
|
||||
|
||||
**> quantum_apply circuit=`self` gate=`门` qubits=`比特`**
|
||||
|
||||
## 噪声
|
||||
+ `种类`
|
||||
+ `概率`
|
||||
|
||||
教学噪声,供 `运行` 轨迹使用(`bitflip` / `depolarizing` / `amplitude_damping`,或中文:比特翻转 / 退极化 / 振幅阻尼)。`模拟` / `概率` 忽略。
|
||||
|
||||
**> quantum_noise circuit=`self` kind=`种类` p=`概率`**
|
||||
|
||||
## 模拟
|
||||
|
||||
返回态矢量振幅 `{re,im}`(理想;无噪声)。
|
||||
|
||||
**> quantum_simulate circuit=`self`**
|
||||
|
||||
## 态
|
||||
|
||||
理想态矢量(与 `模拟` 相同振幅)。
|
||||
|
||||
**> quantum_state circuit=`self`**
|
||||
|
||||
## 概率
|
||||
|
||||
基矢标签 → 概率(qubit 0 为最右侧比特)。理想;忽略噪声。
|
||||
|
||||
**> quantum_probabilities circuit=`self`**
|
||||
|
||||
## 运行
|
||||
+ `次数`=1024
|
||||
+ `种子`=1
|
||||
|
||||
计算基采样(`种子=` 可复现)。若设置了电路噪声则启用。
|
||||
|
||||
**> quantum_run circuit=`self` shots=`次数` seed=`种子`**
|
||||
|
||||
## 绘图
|
||||
+ `路径`=None
|
||||
+ `种类`=circuit
|
||||
+ `比特`=0
|
||||
|
||||
电路轨线 / 概率条 / 布洛赫球(种类 circuit、probs 或 bloch)。经 record_plot 进入 view/CLI plots。
|
||||
|
||||
**> quantum_draw_circuit circuit=`self` path=`路径` kind=`种类` qubit=`比特`**
|
||||
|
||||
# 门
|
||||
+ `名`=None
|
||||
+ `参数`=None
|
||||
+ `矩阵`=None
|
||||
|
||||
具名内置门(`名=H`)或由 `矩阵=`(嵌套 list / `$$` 矩阵围栏)定义的自定义酉门。自定义门可选 `名=`(默认 `U`)。
|
||||
|
||||
> 确保插件
|
||||
1. `矩阵`
|
||||
**> quantum_gate_from_matrix matrix=`矩阵` name=`名`**
|
||||
2. *
|
||||
**> quantum_gate_new name=`名` theta=`参数`**
|
||||
|
||||
## 矩阵
|
||||
|
||||
**> quantum_gate_matrix gate=`self`**
|
||||
|
||||
## 匹配矩阵
|
||||
+ `矩阵`
|
||||
+ `容差`=0.000000001
|
||||
|
||||
**> quantum_gate_matches_matrix gate=`self` matrix=`矩阵` tol=`容差`**
|
||||
|
||||
## 绘图
|
||||
+ `路径`=None
|
||||
+ `种类`=gate
|
||||
|
||||
门符号或复矩阵热力图(`种类=gate|matrix`)。经 `record_plot` 记录。
|
||||
|
||||
**> quantum_gate_draw gate=`self` path=`路径` kind=`种类`**
|
||||
@@ -0,0 +1,31 @@
|
||||
# ext/web
|
||||
|
||||
Official dynamic website extension: **GFM tables + class methods**.
|
||||
Design: [`doc/design/ext-web.md`](../../doc/design/ext-web.md).
|
||||
|
||||
| Surface | Import | Classes |
|
||||
|---------|--------|---------|
|
||||
| English | `> ext/web/web.mq.md` | `page` · `db` · `app` · `form` · `style` |
|
||||
| Chinese | `> ext/web/网页.mq.md` | `页面` · `数据库` · `应用` · `表单` · `样式` |
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_web
|
||||
# optional install into ~/.marqdo/ext
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
Canonical sample (design §4): [`examples/web-site/`](../../examples/web-site/).
|
||||
|
||||
```bash
|
||||
cargo run -- run examples/web-site/index.mq.md
|
||||
# http://127.0.0.1:18081/
|
||||
# /_form/article · /admin · /admin/articles/new
|
||||
```
|
||||
|
||||
Offline smokes: `tests/ext/web-smoke.mq.md`, `web-form-smoke.mq.md`, `web-admin-smoke.mq.md`.
|
||||
|
||||
| Feature | Notes |
|
||||
|---------|--------|
|
||||
| Form §5.5 | field/rules tables · `validate` · `submit` · `mount_form` → `GET\|POST /_form/{id}` |
|
||||
| Admin CRUD | `admin=True` · schema → same form path · new/edit/delete under `/admin/{table}` |
|
||||
| Route | `` `app`.route path=/about page=`about` `` → `GET /about` |
|
||||
@@ -0,0 +1,213 @@
|
||||
---
|
||||
title: ext/web/web
|
||||
description: Official web site classes (English). Tables + methods; no bag glue.
|
||||
> lib/plugin.mq.md
|
||||
> lib/sys.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## ensure_plugin
|
||||
|
||||
Load the ABI v2 `web` plugin once.
|
||||
|
||||
*`p` = > plugin.native_path name=web *
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/web: native web plugin not found (build marqdo_plugin_web or marqdo ext add web)
|
||||
> sys.exit code=1
|
||||
****
|
||||
|
||||
# page
|
||||
+ `title`="Marqdo Web"
|
||||
+ `intro`=""
|
||||
|
||||
> ensure_plugin
|
||||
**> web_page_new title=`title` intro=`intro`**
|
||||
|
||||
## compose_components
|
||||
+ `components`
|
||||
|
||||
Assemble nav / sidebar / footer from a page table (`|组件|样式|` or `|src|style|`).
|
||||
|
||||
**> web_compose_components page=`self` components=`components`**
|
||||
|
||||
## compose_main
|
||||
+ `main`
|
||||
|
||||
Assemble main from a bind table (`|属性|值|样式|` or `|front|back|css|`).
|
||||
|
||||
**> web_compose_main page=`self` main=`main`**
|
||||
|
||||
## compose_form
|
||||
+ `form`
|
||||
+ `id`
|
||||
|
||||
Embed a form into the page main slot. `listen` auto-registers `GET|POST /_form/{id}` from page/route forms (optional `app.mount_form`).
|
||||
|
||||
**> web_compose_form page=`self` form=`form` id=`id`**
|
||||
|
||||
## render
|
||||
+ `db`=None
|
||||
|
||||
Offline HTML for tests / previews.
|
||||
|
||||
1. `db`
|
||||
*`url` = > json.get value=`db` key=url *
|
||||
**> web_render page=`self` url=`url`**
|
||||
2. *
|
||||
**> web_render page=`self`**
|
||||
|
||||
# style
|
||||
+ `name`=""
|
||||
|
||||
Style tables live as `##` exports in site style modules; compose resolves them by path.
|
||||
|
||||
**`self`**
|
||||
|
||||
## process
|
||||
+ `style`=None
|
||||
+ `name`=None
|
||||
+ `path`=None
|
||||
|
||||
**`self`**
|
||||
|
||||
# db
|
||||
+ `url`="sqlite:site.db"
|
||||
|
||||
> ensure_plugin
|
||||
**> web_db_new url=`url`**
|
||||
|
||||
## init
|
||||
+ `name`
|
||||
+ `fields`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_init url=`url` name=`name` fields=`fields`**
|
||||
|
||||
## insert
|
||||
+ `table`
|
||||
+ `rows`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_insert url=`url` table=`table` rows=`rows`**
|
||||
|
||||
## select
|
||||
+ `table`
|
||||
+ `where`=None
|
||||
+ `limit`=200
|
||||
|
||||
Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作|值|` (`=` `!=` `>` `>=` `<` `<=` `like`).
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
*`r` = > web_db_select url=`url` table=`table` where=`where` limit=`limit` *
|
||||
**> json.get value=`r` key=rows**
|
||||
|
||||
## get
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_get url=`url` table=`table` id=`id`**
|
||||
|
||||
## update
|
||||
+ `table`
|
||||
+ `id`
|
||||
+ `row`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_update url=`url` table=`table` id=`id` row=`row`**
|
||||
|
||||
## delete
|
||||
+ `table`
|
||||
+ `id`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_delete url=`url` table=`table` id=`id`**
|
||||
|
||||
## exec
|
||||
+ `sql`
|
||||
+ `args`=None
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_exec url=`url` sql=`sql` args=`args`**
|
||||
|
||||
# form
|
||||
+ `table`=None
|
||||
+ `action`=insert
|
||||
+ `id`=None
|
||||
|
||||
Field table + rules table; submit writes through `# db`.
|
||||
|
||||
> ensure_plugin
|
||||
**> web_form_new table=`table` action=`action` id=`id`**
|
||||
|
||||
## fields
|
||||
+ `fields`
|
||||
|
||||
**> web_form_fields form=`self` fields=`fields`**
|
||||
|
||||
## rules
|
||||
+ `rules`
|
||||
|
||||
**> web_form_rules form=`self` rules=`rules`**
|
||||
|
||||
## validate
|
||||
+ `rules`=None
|
||||
+ `data`
|
||||
|
||||
**> web_form_validate form=`self` rules=`rules` data=`data`**
|
||||
|
||||
## render
|
||||
+ `id`=form
|
||||
+ `data`=None
|
||||
+ `errors`=None
|
||||
|
||||
**> web_form_render form=`self` id=`id` data=`data` errors=`errors`**
|
||||
|
||||
## submit
|
||||
+ `data`
|
||||
+ `db`
|
||||
|
||||
*`url` = > json.get value=`db` key=url *
|
||||
**> web_form_submit form=`self` data=`data` url=`url`**
|
||||
|
||||
# app
|
||||
+ `page`
|
||||
+ `db`=None
|
||||
+ `admin`=False
|
||||
+ `host`=127.0.0.1
|
||||
+ `port`=18081
|
||||
|
||||
> ensure_plugin
|
||||
**> web_app_new page=`page` db=`db` admin=`admin` host=`host` port=`port`**
|
||||
|
||||
## route
|
||||
+ `path`
|
||||
+ `page`
|
||||
|
||||
Mount an assembled page at `path` (e.g. `/about`). `/` is the home `page=`.
|
||||
|
||||
**> web_app_route app=`self` path=`path` page=`page`**
|
||||
|
||||
## mount_form
|
||||
+ `id`
|
||||
+ `form`
|
||||
|
||||
Register `GET|POST /_form/{id}` for listen when the form is not already embedded via `page.compose_form`.
|
||||
|
||||
**> web_app_mount_form app=`self` id=`id` form=`form`**
|
||||
|
||||
## static
|
||||
+ `dir`
|
||||
+ `mount`=/static
|
||||
|
||||
Serve files from `dir` under `mount` (default `/static`). Path is resolved from the process working directory at listen time.
|
||||
|
||||
**> web_app_static app=`self` dir=`dir` mount=`mount`**
|
||||
|
||||
## listen
|
||||
|
||||
Serve `/`, routed pages, `/_part/{id}` (home) and `{path}/_part/{id}` (routes), `/_form/{id}` (from mounts + page embeds), optional `/static` (or custom mount), and optional `/admin`.
|
||||
|
||||
**> web_listen app=`self`**
|
||||
@@ -0,0 +1,203 @@
|
||||
---
|
||||
title: ext/web/网页
|
||||
description: 官方网站类(中文)。表格 + 方法;不写袋式胶水。
|
||||
> lib/plugin.mq.md
|
||||
> lib/sys.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## 确保插件
|
||||
|
||||
加载 ABI v2 `web` 插件。
|
||||
|
||||
*`p` = > plugin.native_path name=web *
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=ext/web: 未找到原生 web 插件(请 build marqdo_plugin_web 或 marqdo ext add web)
|
||||
> sys.exit code=1
|
||||
****
|
||||
|
||||
# 页面
|
||||
+ `标题`="站点"
|
||||
+ `引言`=""
|
||||
|
||||
> 确保插件
|
||||
**> web_page_new title=`标题` intro=`引言`**
|
||||
|
||||
## 组件装配
|
||||
+ `组件`
|
||||
|
||||
**> web_compose_components page=`self` components=`组件`**
|
||||
|
||||
## 主体装配
|
||||
+ `主体`
|
||||
|
||||
**> web_compose_main page=`self` main=`主体`**
|
||||
|
||||
## 表单装配
|
||||
+ `表单`
|
||||
+ `id`
|
||||
|
||||
将表单嵌入页面主区。`listen` 会从页面/路由上的表单自动挂载 `GET|POST /_form/{id}`(可选再 `挂载表单`)。
|
||||
|
||||
**> web_compose_form page=`self` form=`表单` id=`id`**
|
||||
|
||||
## 渲染
|
||||
+ `数据库`=None
|
||||
|
||||
1. `数据库`
|
||||
*`url` = > json.get value=`数据库` key=url *
|
||||
**> web_render page=`self` url=`url`**
|
||||
2. *
|
||||
**> web_render page=`self`**
|
||||
|
||||
# 样式
|
||||
+ `名`=""
|
||||
|
||||
**`self`**
|
||||
|
||||
## 样式处理
|
||||
+ `样式`=None
|
||||
+ `名`=None
|
||||
+ `路径`=None
|
||||
|
||||
**`self`**
|
||||
|
||||
# 数据库
|
||||
+ `地址`="sqlite:site.db"
|
||||
|
||||
> 确保插件
|
||||
**> web_db_new url=`地址`**
|
||||
|
||||
## 初始化
|
||||
+ `名`
|
||||
+ `字段`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_init url=`url` name=`名` fields=`字段`**
|
||||
|
||||
## 插入
|
||||
+ `表`
|
||||
+ `行`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_insert url=`url` table=`表` rows=`行`**
|
||||
|
||||
## 查询
|
||||
+ `表`
|
||||
+ `条件`=None
|
||||
+ `上限`=200
|
||||
|
||||
简单条件:单行列→值映射(AND `=`),或 `|字段|操作|值|` 表(`=` `!=` `>` `>=` `<` `<=` `like`)。
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
*`r` = > web_db_select url=`url` table=`表` where=`条件` limit=`上限` *
|
||||
**> json.get value=`r` key=rows**
|
||||
|
||||
## 获取
|
||||
+ `表`
|
||||
+ `id`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_get url=`url` table=`表` id=`id`**
|
||||
|
||||
## 更新
|
||||
+ `表`
|
||||
+ `id`
|
||||
+ `行`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_update url=`url` table=`表` id=`id` row=`行`**
|
||||
|
||||
## 删除
|
||||
+ `表`
|
||||
+ `id`
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_delete url=`url` table=`表` id=`id`**
|
||||
|
||||
## 执行
|
||||
+ `sql`
|
||||
+ `参数`=None
|
||||
|
||||
*`url` = > json.get value=`self` key=url *
|
||||
**> web_db_exec url=`url` sql=`sql` args=`参数`**
|
||||
|
||||
# 表单
|
||||
+ `表`=None
|
||||
+ `动作`=插入
|
||||
+ `id`=None
|
||||
|
||||
字段表 + 校验表;提交经 `# 数据库` 写入。
|
||||
|
||||
> 确保插件
|
||||
**> web_form_new table=`表` action=`动作` id=`id`**
|
||||
|
||||
## 字段
|
||||
+ `字段`
|
||||
|
||||
**> web_form_fields form=`self` fields=`字段`**
|
||||
|
||||
## 规则
|
||||
+ `规则`
|
||||
|
||||
**> web_form_rules form=`self` rules=`规则`**
|
||||
|
||||
## 校验
|
||||
+ `规则`=None
|
||||
+ `数据`
|
||||
|
||||
**> web_form_validate form=`self` rules=`规则` data=`数据`**
|
||||
|
||||
## 渲染
|
||||
+ `id`=form
|
||||
+ `数据`=None
|
||||
+ `错误`=None
|
||||
|
||||
**> web_form_render form=`self` id=`id` data=`数据` errors=`错误`**
|
||||
|
||||
## 提交
|
||||
+ `数据`
|
||||
+ `数据库`
|
||||
|
||||
*`url` = > json.get value=`数据库` key=url *
|
||||
**> web_form_submit form=`self` data=`数据` url=`url`**
|
||||
|
||||
# 应用
|
||||
+ `页面`
|
||||
+ `数据库`=None
|
||||
+ `后台`=False
|
||||
+ `主机`=127.0.0.1
|
||||
+ `端口`=18081
|
||||
|
||||
> 确保插件
|
||||
**> web_app_new page=`页面` db=`数据库` admin=`后台` host=`主机` port=`端口`**
|
||||
|
||||
## 路由
|
||||
+ `路径`
|
||||
+ `页面`
|
||||
|
||||
将已装配页面挂到 `路径`(如 `/about`)。`/` 由首页 `页面=` 提供。
|
||||
|
||||
**> web_app_route app=`self` path=`路径` page=`页面`**
|
||||
|
||||
## 挂载表单
|
||||
+ `id`
|
||||
+ `表单`
|
||||
|
||||
**> web_app_mount_form app=`self` id=`id` form=`表单`**
|
||||
|
||||
## 静态
|
||||
+ `目录`
|
||||
+ `挂载`=/static
|
||||
|
||||
将 `目录` 下的文件挂到 `挂载`(默认 `/static`)。路径在 `监听` 时相对进程工作目录解析。
|
||||
|
||||
**> web_app_static app=`self` dir=`目录` mount=`挂载`**
|
||||
|
||||
## 监听
|
||||
|
||||
提供 `/`、路由页、首页 `/_part/{id}`、路由 `{路径}/_part/{id}`、`/_form/{id}`、可选静态目录,以及可选 `/admin`。
|
||||
|
||||
**> web_listen app=`self`**
|
||||
@@ -0,0 +1,55 @@
|
||||
/* Marqdo plugin ABI v2 — C contract (source of truth).
|
||||
*
|
||||
* Plugins are optional shared libraries (.dll / .so / .dylib), never linked
|
||||
* into the marqdo binary. Values cross the boundary as UTF-8 JSON.
|
||||
*
|
||||
* v1: register_fn, alloc, free
|
||||
* v2: + host_query (allowlisted host introspection for plugins)
|
||||
*/
|
||||
#ifndef MARQDO_ABI_H
|
||||
#define MARQDO_ABI_H
|
||||
|
||||
#include <stddef.h>
|
||||
#include <stdint.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#define MARQDO_ABI_VERSION 2u
|
||||
#define MARQDO_ABI_VERSION_MIN 1u
|
||||
|
||||
/* Plugin function: args_json is a UTF-8 JSON object whose keys are param names.
|
||||
* On success: return 0, set *out_json to a heap string (host frees via free).
|
||||
* On failure: return non-zero; optional *err_msg heap string (host frees).
|
||||
* out_json / err_msg may be left NULL.
|
||||
*/
|
||||
typedef int (*MarqdoPluginFn)(const char *args_json, char **out_json, char **err_msg);
|
||||
|
||||
/* Host → plugin query (v2). `name` is an allowlisted query id.
|
||||
* Same success/failure convention as MarqdoPluginFn.
|
||||
*/
|
||||
typedef int (*MarqdoHostQueryFn)(void *userdata, const char *name, const char *args_json,
|
||||
char **out_json, char **err_msg);
|
||||
|
||||
typedef struct MarqdoHostApi {
|
||||
void *userdata;
|
||||
/* params: comma-separated param names in order, e.g. "a,b". May be "". */
|
||||
int (*register_fn)(void *userdata, const char *name, const char *params,
|
||||
MarqdoPluginFn fn);
|
||||
void *(*alloc)(size_t n);
|
||||
void (*free)(void *p);
|
||||
/* v2: NULL for hosts that only speak v1; required when plugin abi >= 2 */
|
||||
MarqdoHostQueryFn host_query;
|
||||
} MarqdoHostApi;
|
||||
|
||||
/* Required exports from every plugin shared library. */
|
||||
uint32_t marqdo_plugin_abi_version(void);
|
||||
int marqdo_plugin_init(const MarqdoHostApi *host);
|
||||
void marqdo_plugin_shutdown(void);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* MARQDO_ABI_H */
|
||||
+13
-11
@@ -3,23 +3,25 @@ title: lib/foreign
|
||||
description: Run bound code fences and inline sources via local interpreters
|
||||
---
|
||||
|
||||
# set_cmd
|
||||
- lang
|
||||
- cmd
|
||||
## set_cmd
|
||||
+ `lang`
|
||||
+ `cmd`
|
||||
|
||||
**> host_foreign_set_cmd lang=`lang` cmd=`cmd`**
|
||||
|
||||
# run
|
||||
- code
|
||||
## run
|
||||
+ `code`
|
||||
+ `stdin`=None
|
||||
|
||||
**> host_foreign_run code=`code`**
|
||||
**> host_foreign_run code=`code` stdin=`stdin`**
|
||||
|
||||
# run_lang
|
||||
- lang
|
||||
- source
|
||||
## run_lang
|
||||
+ `lang`
|
||||
+ `source`
|
||||
+ `stdin`=None
|
||||
|
||||
**> host_foreign_run_lang lang=`lang` source=`source`**
|
||||
**> host_foreign_run_lang lang=`lang` source=`source` stdin=`stdin`**
|
||||
|
||||
# langs
|
||||
## langs
|
||||
|
||||
**> host_foreign_langs**
|
||||
+33
-16
@@ -3,39 +3,56 @@ title: lib/fs
|
||||
description: English filesystem wrappers
|
||||
---
|
||||
|
||||
# read_text
|
||||
- path
|
||||
## read_text
|
||||
+ `path`
|
||||
|
||||
**> host_read_text path=`path`**
|
||||
|
||||
# write_text
|
||||
- path
|
||||
- text
|
||||
## write_text
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
**> host_write_text path=`path` text=`text`**
|
||||
|
||||
# append_text
|
||||
- path
|
||||
- text
|
||||
## append_text
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
**> host_append_text path=`path` text=`text`**
|
||||
|
||||
# exists
|
||||
- path
|
||||
## exists
|
||||
+ `path`
|
||||
|
||||
**> host_exists path=`path`**
|
||||
|
||||
# list_dir
|
||||
- path
|
||||
## list_dir
|
||||
+ `path`
|
||||
|
||||
**> host_list_dir path=`path`**
|
||||
|
||||
# make_dir
|
||||
- path
|
||||
## make_dir
|
||||
+ `path`
|
||||
|
||||
**> host_make_dir path=`path`**
|
||||
|
||||
# remove
|
||||
- path
|
||||
## remove
|
||||
+ `path`
|
||||
|
||||
**> host_remove path=`path`**
|
||||
|
||||
## text_patch
|
||||
+ `path`
|
||||
+ `find`
|
||||
+ `replace`
|
||||
|
||||
Exact FIND→REPLACE once in a UTF-8 text file. `find` must match exactly once.
|
||||
|
||||
**> host_text_patch path=`path` find=`find` replace=`replace`**
|
||||
|
||||
## apply_patch_blocks
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
Apply plan-style `<<<` / FIND / === / REPLACE / `>>>` blocks from `text` to `path`.
|
||||
|
||||
**> host_apply_patch_blocks path=`path` text=`text`**
|
||||
+29
-10
@@ -3,23 +3,42 @@ title: lib/json
|
||||
description: JSON parse/stringify (shared EN/ZH import)
|
||||
---
|
||||
|
||||
# parse
|
||||
- text
|
||||
## parse
|
||||
+ `text`
|
||||
|
||||
**> host_json_parse text=`text`**
|
||||
|
||||
# stringify
|
||||
- value
|
||||
## stringify
|
||||
+ `value`
|
||||
+ `indent`=None
|
||||
|
||||
**> host_json_stringify value=`value`**
|
||||
**> host_json_stringify value=`value` indent=`indent`**
|
||||
|
||||
# get
|
||||
- value
|
||||
- key
|
||||
## get
|
||||
+ `value`
|
||||
+ `key`
|
||||
|
||||
**> host_json_get value=`value` key=`key`**
|
||||
|
||||
# keys
|
||||
- value
|
||||
## keys
|
||||
+ `value`
|
||||
|
||||
**> host_json_keys value=`value`**
|
||||
|
||||
## quote
|
||||
+ `text`
|
||||
|
||||
**> host_json_quote text=`text`**
|
||||
|
||||
## set
|
||||
+ `map`
|
||||
+ `key`
|
||||
+ `value`
|
||||
|
||||
**> host_map_set map=`map` key=`key` value=`value`**
|
||||
|
||||
## append
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_append list=`list` item=`item`**
|
||||
+105
-92
@@ -3,198 +3,211 @@ title: lib/math
|
||||
description: High-school math — num, random, formula, plot
|
||||
---
|
||||
|
||||
# pi
|
||||
## pi
|
||||
|
||||
**> host_pi**
|
||||
|
||||
# e
|
||||
## e
|
||||
|
||||
**> host_e**
|
||||
|
||||
# num
|
||||
- value
|
||||
## num
|
||||
+ `value`
|
||||
|
||||
**> host_num value=`value`**
|
||||
|
||||
# add
|
||||
- a
|
||||
- b
|
||||
## add
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_add a=`a` b=`b`**
|
||||
|
||||
# sub
|
||||
- a
|
||||
- b
|
||||
## sub
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_sub a=`a` b=`b`**
|
||||
|
||||
# mul
|
||||
- a
|
||||
- b
|
||||
## mul
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_mul a=`a` b=`b`**
|
||||
|
||||
# div
|
||||
- a
|
||||
- b
|
||||
## div
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_div a=`a` b=`b`**
|
||||
|
||||
# pow
|
||||
- a
|
||||
- b
|
||||
## pow
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_pow a=`a` b=`b`**
|
||||
|
||||
# neg
|
||||
- value
|
||||
## neg
|
||||
+ `value`
|
||||
|
||||
**> host_math_neg value=`value`**
|
||||
|
||||
# sin
|
||||
- value
|
||||
## sin
|
||||
+ `value`
|
||||
|
||||
**> host_math_sin value=`value`**
|
||||
|
||||
# cos
|
||||
- value
|
||||
## cos
|
||||
+ `value`
|
||||
|
||||
**> host_math_cos value=`value`**
|
||||
|
||||
# tan
|
||||
- value
|
||||
## tan
|
||||
+ `value`
|
||||
|
||||
**> host_math_tan value=`value`**
|
||||
|
||||
# asin
|
||||
- value
|
||||
## asin
|
||||
+ `value`
|
||||
|
||||
**> host_math_asin value=`value`**
|
||||
|
||||
# acos
|
||||
- value
|
||||
## acos
|
||||
+ `value`
|
||||
|
||||
**> host_math_acos value=`value`**
|
||||
|
||||
# atan
|
||||
- value
|
||||
## atan
|
||||
+ `value`
|
||||
|
||||
**> host_math_atan value=`value`**
|
||||
|
||||
# sqrt
|
||||
- value
|
||||
## sqrt
|
||||
+ `value`
|
||||
|
||||
**> host_math_sqrt value=`value`**
|
||||
|
||||
# abs
|
||||
- value
|
||||
## abs
|
||||
+ `value`
|
||||
|
||||
**> host_math_abs value=`value`**
|
||||
|
||||
# ln
|
||||
- value
|
||||
## ln
|
||||
+ `value`
|
||||
|
||||
**> host_math_ln value=`value`**
|
||||
|
||||
# exp
|
||||
- value
|
||||
## exp
|
||||
+ `value`
|
||||
|
||||
**> host_math_exp value=`value`**
|
||||
|
||||
# floor
|
||||
- value
|
||||
## floor
|
||||
+ `value`
|
||||
|
||||
**> host_math_floor value=`value`**
|
||||
|
||||
# ceil
|
||||
- value
|
||||
## ceil
|
||||
+ `value`
|
||||
|
||||
**> host_math_ceil value=`value`**
|
||||
|
||||
# min
|
||||
- a
|
||||
- b
|
||||
## min
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_min a=`a` b=`b`**
|
||||
|
||||
# max
|
||||
- a
|
||||
- b
|
||||
## max
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_max a=`a` b=`b`**
|
||||
|
||||
# random
|
||||
## random
|
||||
|
||||
**> host_random**
|
||||
|
||||
# random_int
|
||||
- min
|
||||
- max
|
||||
## random_int
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_random_int min=`min` max=`max`**
|
||||
|
||||
# seed
|
||||
- value
|
||||
## seed
|
||||
+ `value`
|
||||
|
||||
**> host_seed value=`value`**
|
||||
|
||||
# formula
|
||||
- text
|
||||
## formula
|
||||
+ `text`
|
||||
|
||||
**> host_formula value=`text`**
|
||||
|
||||
# simplify
|
||||
- formula
|
||||
## simplify
|
||||
+ `formula`
|
||||
|
||||
**> host_simplify value=`formula`**
|
||||
|
||||
# expand
|
||||
- formula
|
||||
## expand
|
||||
+ `formula`
|
||||
|
||||
**> host_expand value=`formula`**
|
||||
|
||||
# diff
|
||||
- formula
|
||||
- var
|
||||
## diff
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_diff formula=`formula` var=`var`**
|
||||
|
||||
# subs
|
||||
- formula
|
||||
- var
|
||||
- value
|
||||
## subs
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_subs formula=`formula` var=`var` value=`value`**
|
||||
|
||||
# eval
|
||||
- formula
|
||||
- var
|
||||
- value
|
||||
## eval
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_eval formula=`formula` var=`var` value=`value`**
|
||||
|
||||
# solve
|
||||
- formula
|
||||
- var
|
||||
## solve
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`=None
|
||||
+ `max`=None
|
||||
|
||||
**> host_solve formula=`formula` var=`var`**
|
||||
**> host_solve formula=`formula` var=`var` min=`min` max=`max`**
|
||||
|
||||
# plot
|
||||
- formula
|
||||
- var
|
||||
- min
|
||||
- max
|
||||
## plot
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`
|
||||
+ `max`
|
||||
+ `steps`=None
|
||||
+ `path`=None
|
||||
+ `derivative`=None
|
||||
+ `grid`=None
|
||||
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max` steps=`steps` path=`path` derivative=`derivative` grid=`grid`**
|
||||
|
||||
# plot_points
|
||||
- xs
|
||||
- ys
|
||||
## plot_points
|
||||
+ `xs`
|
||||
+ `ys`
|
||||
+ `path`=None
|
||||
+ `grid`=None
|
||||
|
||||
**> host_plot_points xs=`xs` ys=`ys`**
|
||||
**> host_plot_points xs=`xs` ys=`ys` path=`path` grid=`grid`**
|
||||
|
||||
# plot_conic
|
||||
- kind
|
||||
- a
|
||||
## plot_conic
|
||||
+ `kind`
|
||||
+ `a`
|
||||
+ `b`=None
|
||||
+ `h`=None
|
||||
+ `k`=None
|
||||
+ `path`=None
|
||||
+ `grid`=None
|
||||
|
||||
**> host_plot_conic kind=`kind` a=`a`**
|
||||
**> host_plot_conic kind=`kind` a=`a` b=`b` h=`h` k=`k` path=`path` grid=`grid`**
|
||||
+47
-10
@@ -1,20 +1,57 @@
|
||||
---
|
||||
title: lib/net
|
||||
description: English minimal HTTP wrappers
|
||||
description: English HTTP(S) wrappers. Optional headers / content_type via host aliases.
|
||||
---
|
||||
|
||||
# http_get
|
||||
- url
|
||||
## http_get
|
||||
+ `url`
|
||||
+ `headers`=None
|
||||
|
||||
**> host_http_get url=`url`**
|
||||
HTTPS supported. Optional named arg `headers=` (map).
|
||||
|
||||
# http_post
|
||||
- url
|
||||
- body
|
||||
**> host_http_get url=`url` headers=`headers`**
|
||||
|
||||
**> host_http_post url=`url` body=`body`**
|
||||
## http_post
|
||||
+ `url`
|
||||
+ `body`
|
||||
+ `content_type`=None
|
||||
+ `headers`=None
|
||||
|
||||
# url_encode
|
||||
- text
|
||||
Default content type is JSON. Optional `content_type=` / `headers=` (map).
|
||||
|
||||
**> host_http_post url=`url` body=`body` content_type=`content_type` headers=`headers`**
|
||||
|
||||
## http_post_sse
|
||||
+ `url`
|
||||
+ `body`
|
||||
+ `content_type`=None
|
||||
+ `headers`=None
|
||||
+ `echo`=False
|
||||
|
||||
POST and consume OpenAI-compatible SSE. Returns `{status, events}` where `events` is a list of `{type, …}` maps (`delta` / `done` / `error`). Optional `echo=True` prints delta text to stdout as chunks arrive.
|
||||
|
||||
**> host_http_post_sse url=`url` body=`body` content_type=`content_type` headers=`headers` echo=`echo`**
|
||||
|
||||
## openai_sse_parse
|
||||
+ `text`
|
||||
+ `echo`=False
|
||||
|
||||
Offline: parse an OpenAI chat SSE body into the same event list (no network).
|
||||
|
||||
**> host_openai_sse_parse text=`text` echo=`echo`**
|
||||
|
||||
## http_request
|
||||
+ `method`
|
||||
+ `url`
|
||||
+ `body`=None
|
||||
+ `content_type`=None
|
||||
+ `headers`=None
|
||||
|
||||
Optional `body=` / `content_type=` / `headers=`.
|
||||
|
||||
**> host_http_request method=`method` url=`url` body=`body` content_type=`content_type` headers=`headers`**
|
||||
|
||||
## url_encode
|
||||
+ `text`
|
||||
|
||||
**> host_url_encode text=`text`**
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: lib/plugin
|
||||
description: Load optional native ABI plugins (.dll / .so / .dylib)
|
||||
---
|
||||
|
||||
## load
|
||||
+ `path`
|
||||
|
||||
**> host_plugin_load path=`path`**
|
||||
|
||||
## unload
|
||||
|
||||
**> host_plugin_unload**
|
||||
|
||||
## list
|
||||
|
||||
**> host_plugin_list**
|
||||
|
||||
## native_path
|
||||
+ `name`
|
||||
|
||||
Resolve installed / local native plugin path (e.g. `agent`).
|
||||
|
||||
**> host_ext_native_path name=`name`**
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: lib/subtask
|
||||
description: Concurrent subtasks — file, function, or foreign code
|
||||
---
|
||||
|
||||
## spawn
|
||||
+ `path`=None
|
||||
+ `fn`=None
|
||||
+ `args`=None
|
||||
+ `code`=None
|
||||
+ `lang`=None
|
||||
+ `source`=None
|
||||
+ `stdin`=None
|
||||
+ `quiet`=True
|
||||
|
||||
File children are silent by default (`quiet=True`: piped capture, no TTY noise).
|
||||
Set `quiet=False` to inherit parent stdout/stderr.
|
||||
File `wait` returns `{code, value}` plus optional `stdout`/`stderr` tails when quiet-captured.
|
||||
`value` is the child's `# main` return (not stdout).
|
||||
|
||||
**> host_subtask_spawn path=`path` fn=`fn` args=`args` code=`code` lang=`lang` source=`source` stdin=`stdin` quiet=`quiet`**
|
||||
|
||||
## poll
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_poll id=`id`**
|
||||
|
||||
## wait
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_join id=`id`**
|
||||
|
||||
## kill
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_kill id=`id`**
|
||||
|
||||
## wait_all
|
||||
|
||||
**> host_subtask_wait_all**
|
||||
+28
-13
@@ -1,33 +1,48 @@
|
||||
---
|
||||
title: lib/sys
|
||||
description: English system wrappers
|
||||
description: English system wrappers (load_dotenv accepts optional path via host alias)
|
||||
---
|
||||
|
||||
# env_get
|
||||
- name
|
||||
## env_get
|
||||
+ `name`
|
||||
|
||||
**> host_env_get name=`name`**
|
||||
|
||||
# env_set
|
||||
- name
|
||||
- value
|
||||
## env_set
|
||||
+ `name`
|
||||
+ `value`
|
||||
|
||||
**> host_env_set name=`name` value=`value`**
|
||||
|
||||
# args
|
||||
## load_dotenv
|
||||
+ `path`=None
|
||||
|
||||
Load `.env` (optional named arg `path=`). Existing process env is not overridden.
|
||||
|
||||
**> host_dotenv_load path=`path`**
|
||||
|
||||
## args
|
||||
|
||||
**> host_args**
|
||||
|
||||
# cwd
|
||||
## cwd
|
||||
|
||||
**> host_cwd**
|
||||
|
||||
# exit
|
||||
- code
|
||||
## exit
|
||||
+ `code`
|
||||
|
||||
**> host_exit code=`code`**
|
||||
|
||||
# exec
|
||||
- cmd
|
||||
## exec
|
||||
+ `cmd`
|
||||
+ `args`=None
|
||||
|
||||
**> host_exec cmd=`cmd`**
|
||||
**> host_exec cmd=`cmd` args=`args`**
|
||||
|
||||
## stream_publish
|
||||
+ `event`
|
||||
|
||||
Publish a stream event map onto the process EventBus (`marqdo view` SSE). No-op when nothing is subscribed.
|
||||
|
||||
**> host_stream_publish event=`event`**
|
||||
+195
-6
@@ -1,15 +1,204 @@
|
||||
---
|
||||
title: lib/table
|
||||
description: English table helpers over len / at
|
||||
description: >-
|
||||
List and map helpers. Prefer put (1-based path, same as footnotes); at/set_at/slice
|
||||
are 0-based. json is for parse/stringify.
|
||||
---
|
||||
|
||||
# rows
|
||||
- xs
|
||||
## put
|
||||
+ `in`
|
||||
+ `at`
|
||||
+ `value`
|
||||
|
||||
Directly update one element. `at=` is a text key, a **1-based** list index, or a list path of keys/indices (same nesting as footnotes).
|
||||
|
||||
**> host_collection_put in=`in` at=`at` value=`value`**
|
||||
|
||||
## len
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
# row_at
|
||||
- xs
|
||||
- i
|
||||
## rows
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
## at
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
Index is zero-based (same as builtin `at`). Out of range → `None`.
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
|
||||
## row_at
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
|
||||
## append
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_append list=`list` item=`item`**
|
||||
|
||||
## prepend
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_prepend list=`list` item=`item`**
|
||||
|
||||
## concat
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_list_concat a=`a` b=`b`**
|
||||
|
||||
## insert
|
||||
+ `list`
|
||||
+ `index`
|
||||
+ `item`
|
||||
|
||||
Index is zero-based (may insert at `len` to append).
|
||||
|
||||
**> host_list_insert list=`list` index=`index` item=`item`**
|
||||
|
||||
## set_at
|
||||
+ `list`
|
||||
+ `index`
|
||||
+ `item`
|
||||
|
||||
Zero-based replace. Prefer `put` with 1-based index for author-facing edits.
|
||||
|
||||
**> host_list_set_at list=`list` index=`index` item=`item`**
|
||||
|
||||
## remove_at
|
||||
+ `list`
|
||||
+ `index`
|
||||
|
||||
**> host_list_remove_at list=`list` index=`index`**
|
||||
|
||||
## pop
|
||||
+ `list`
|
||||
|
||||
Drop the last item (errors if empty). Use `last` first when you need the removed value.
|
||||
|
||||
*`n` = > len `list`*
|
||||
1. `n` > 0
|
||||
**> host_list_remove_at list=`list` index=`n` - 1**
|
||||
2. *
|
||||
**> host_list_remove_at list=`list` index=0**
|
||||
|
||||
## first
|
||||
+ `list`
|
||||
|
||||
**> host_list_first list=`list`**
|
||||
|
||||
## last
|
||||
+ `list`
|
||||
|
||||
**> host_list_last list=`list`**
|
||||
|
||||
## slice
|
||||
+ `list`
|
||||
+ `start`
|
||||
+ `end`=None
|
||||
|
||||
Zero-based half-open range from `start` to `end`.
|
||||
|
||||
**> host_list_slice list=`list` start=`start` end=`end`**
|
||||
|
||||
## contains
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_contains list=`list` item=`item`**
|
||||
|
||||
## index_of
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
Zero-based index or `None`.
|
||||
|
||||
**> host_list_index_of list=`list` item=`item`**
|
||||
|
||||
## reverse
|
||||
+ `list`
|
||||
|
||||
**> host_list_reverse list=`list`**
|
||||
|
||||
## clear
|
||||
+ `value`
|
||||
|
||||
Empty list or empty map (by type).
|
||||
|
||||
**> host_collection_clear value=`value`**
|
||||
|
||||
## get
|
||||
+ `map`
|
||||
+ `key`
|
||||
|
||||
Missing key → `None`.
|
||||
|
||||
**> host_map_get map=`map` key=`key`**
|
||||
|
||||
## set
|
||||
+ `map`
|
||||
+ `key`
|
||||
+ `value`
|
||||
|
||||
Shallow map update. Prefer `put` for nested paths.
|
||||
|
||||
**> host_map_set map=`map` key=`key` value=`value`**
|
||||
|
||||
## delete
|
||||
+ `map`
|
||||
+ `key`
|
||||
|
||||
**> host_map_delete map=`map` key=`key`**
|
||||
|
||||
## has
|
||||
+ `map`
|
||||
+ `key`
|
||||
|
||||
**> host_map_has map=`map` key=`key`**
|
||||
|
||||
## keys
|
||||
+ `map`
|
||||
|
||||
**> host_map_keys map=`map`**
|
||||
|
||||
## values
|
||||
+ `map`
|
||||
|
||||
**> host_map_values map=`map`**
|
||||
|
||||
## items
|
||||
+ `map`
|
||||
|
||||
Rows shaped as key/value maps.
|
||||
|
||||
**> host_map_items map=`map`**
|
||||
|
||||
## merge
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
Right-hand keys win.
|
||||
|
||||
**> host_map_merge a=`a` b=`b`**
|
||||
|
||||
## size
|
||||
+ `map`
|
||||
|
||||
**> host_map_size map=`map`**
|
||||
|
||||
## empty_list
|
||||
|
||||
**> host_list_concat a=None b=None**
|
||||
|
||||
## empty_map
|
||||
|
||||
**> host_map_merge a=None b=None**
|
||||
+8
-8
@@ -3,19 +3,19 @@ title: lib/text
|
||||
description: English text helpers over trim / split / join
|
||||
---
|
||||
|
||||
# str_trim
|
||||
- s
|
||||
## str_trim
|
||||
+ `s`
|
||||
|
||||
**> trim `s`**
|
||||
|
||||
# str_split
|
||||
- s
|
||||
- sep
|
||||
## str_split
|
||||
+ `s`
|
||||
+ `sep`
|
||||
|
||||
**> split value=`s` sep=`sep`**
|
||||
|
||||
# str_join
|
||||
- xs
|
||||
- sep
|
||||
## str_join
|
||||
+ `xs`
|
||||
+ `sep`
|
||||
|
||||
**> join value=`xs` sep=`sep`**
|
||||
+10
-10
@@ -3,27 +3,27 @@ title: lib/time
|
||||
description: English time wrappers
|
||||
---
|
||||
|
||||
# now_unix
|
||||
## now_unix
|
||||
|
||||
**> host_now_unix**
|
||||
|
||||
# now_ms
|
||||
## now_ms
|
||||
|
||||
**> host_now_ms**
|
||||
|
||||
# format
|
||||
- unix
|
||||
- pattern
|
||||
## format
|
||||
+ `unix`
|
||||
+ `pattern`
|
||||
|
||||
**> host_format_time unix=`unix` pattern=`pattern`**
|
||||
|
||||
# sleep_ms
|
||||
- ms
|
||||
## sleep_ms
|
||||
+ `ms`
|
||||
|
||||
**> host_sleep_ms ms=`ms`**
|
||||
|
||||
# parse
|
||||
- text
|
||||
- pattern
|
||||
## parse
|
||||
+ `text`
|
||||
+ `pattern`
|
||||
|
||||
**> host_parse_time text=`text` pattern=`pattern`**
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: lib/writeback
|
||||
description: Persist run output in .mq.md (Jupyter-style writeback)
|
||||
---
|
||||
|
||||
## record
|
||||
+ `value`
|
||||
+ `at_end`=False
|
||||
+ `key`=None
|
||||
+ `line`=None
|
||||
|
||||
Write `value` to `<!-- marqdo-out … -->` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` replaces the unkeyed EOF block. With `key=` (e.g. `ok` / `error`), replace or create that **named** slot only — slots do not overwrite each other. Optional `line=` anchors the block under that source line (needed when writing from a subtask).
|
||||
|
||||
**> host_writeback_record value=`value` at_end=`at_end` key=`key` line=`line`**
|
||||
|
||||
## get
|
||||
+ `at_end`=False
|
||||
+ `key`=None
|
||||
+ `line`=None
|
||||
|
||||
Read persisted output for the current call site (adjacent unkeyed block), the unkeyed EOF block when `at_end=true`, or a named slot when `key=` is set.
|
||||
|
||||
**> host_writeback_get at_end=`at_end` key=`key` line=`line`**
|
||||
|
||||
## clear
|
||||
+ `at_end`=False
|
||||
+ `key`=None
|
||||
+ `line`=None
|
||||
|
||||
Remove the adjacent, EOF, or named output block.
|
||||
|
||||
**> host_writeback_clear at_end=`at_end` key=`key` line=`line`**
|
||||
|
||||
## ensure
|
||||
+ `key`
|
||||
+ `placeholder`=pending
|
||||
+ `line`=None
|
||||
|
||||
Create a named slot with `placeholder` if missing. Never overwrites an existing slot body.
|
||||
|
||||
**> host_writeback_ensure key=`key` placeholder=`placeholder` line=`line`**
|
||||
|
||||
## list
|
||||
|
||||
List all output blocks in the entry file (includes `key` when named).
|
||||
|
||||
**> host_writeback_list**
|
||||
|
||||
## scan_path
|
||||
+ `path`
|
||||
|
||||
List `<!-- marqdo-out … -->` slots in any file (workbook inspection).
|
||||
|
||||
**> host_writeback_scan_path path=`path`**
|
||||
Loaded 100 of 366 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user