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 | ||
|
|
54a507d906 | ||
|
|
ea17ae1074 | ||
|
|
fe9046cecf | ||
|
|
b5e9d15391 | ||
|
|
dcd0cdb8f7 | ||
|
|
a53ebb65ee | ||
|
|
a5d30c00b3 | ||
|
|
fd36b92224 | ||
|
|
30cd39fd8f | ||
|
|
31a4b69bbd | ||
|
|
7848180454 | ||
|
|
69fecaeaab | ||
|
|
04098db74c | ||
|
|
96a7c6ce76 | ||
|
|
29418e14f2 | ||
|
|
ac0a3fbced | ||
|
|
a29bf6e97b | ||
|
|
69b626e919 | ||
|
|
63d7866d06 | ||
|
|
27a289217f | ||
|
|
1ae2ae0be8 | ||
|
|
fd128abd13 | ||
|
|
8f44f10bc9 | ||
|
|
23fa4284a8 | ||
|
|
c1a4bb47b6 | ||
|
|
0ae5bce70a | ||
|
|
2cb05fd838 | ||
|
|
117a03ca8e | ||
|
|
84317a1607 |
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 |
|
||||
@@ -0,0 +1,50 @@
|
||||
# Build public/ with marqdo and publish to the gh-pages branch.
|
||||
name: User docs site
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, master]
|
||||
paths:
|
||||
- "public/**"
|
||||
- "src/**"
|
||||
- "Cargo.toml"
|
||||
- "Cargo.lock"
|
||||
- ".github/workflows/pages.yml"
|
||||
- "scripts/build-public.*"
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
build-and-deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Build & export site
|
||||
run: |
|
||||
cargo build --release
|
||||
find public -name '*.mq.md' ! -name 'utils.mq.md' ! -name '¹¤¾ß.mq.md' -print0 \
|
||||
| xargs -0 -n1 ./target/release/marqdo run
|
||||
./target/release/marqdo view output public -o public
|
||||
|
||||
- name: Verify site shape
|
||||
run: |
|
||||
if grep -R "tests/errors" public --include='*.html' ; then
|
||||
echo "user site must not include tests/errors fixtures" >&2
|
||||
exit 1
|
||||
fi
|
||||
test -f public/index.html
|
||||
test -f public/00-welcome.mq.md
|
||||
|
||||
- name: Deploy to gh-pages
|
||||
uses: peaceiris/actions-gh-pages@v4
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./public
|
||||
publish_branch: gh-pages
|
||||
force_orphan: true
|
||||
@@ -0,0 +1,126 @@
|
||||
# Build and attach release binaries when a version tag is pushed.
|
||||
name: Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "v*"
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
windows:
|
||||
runs-on: windows-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Install Node (VS Code extension)
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "20"
|
||||
|
||||
- name: Build release
|
||||
run: cargo build --release
|
||||
|
||||
- name: Checkout extension sources (branch vscode-extension only)
|
||||
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
|
||||
|
||||
- name: Build VSIX
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ver = "${{ github.ref_name }}".TrimStart("v")
|
||||
New-Item -ItemType Directory -Force -Path dist | Out-Null
|
||||
Push-Location vscode-extension
|
||||
npm ci
|
||||
npm run compile
|
||||
npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-$ver.vsix"
|
||||
Pop-Location
|
||||
|
||||
- name: Package
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ver = "${{ github.ref_name }}".TrimStart("v")
|
||||
$target = "x86_64-pc-windows-msvc"
|
||||
New-Item -ItemType Directory -Force -Path dist | Out-Null
|
||||
$exe = "marqdo-$ver-$target.exe"
|
||||
$zip = "marqdo-$ver-$target.zip"
|
||||
$stdlib = "marqdo-$ver-stdlib.zip"
|
||||
$source = "marqdo-$ver-source.zip"
|
||||
$vsix = "marqdo-$ver.vsix"
|
||||
$public = "marqdo-$ver-public.zip"
|
||||
$extZip = "marqdo-$ver-ext.zip"
|
||||
Copy-Item target/release/marqdo.exe "dist/$exe"
|
||||
git archive --format=zip -o "dist/$source" HEAD
|
||||
./target/release/marqdo view output public -o public
|
||||
Compress-Archive -Path public/* -DestinationPath "dist/$public" -Force
|
||||
$stageExt = "dist/stage-ext"
|
||||
if (Test-Path $stageExt) { Remove-Item $stageExt -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stageExt | Out-Null
|
||||
Copy-Item ext "$stageExt/ext" -Recurse
|
||||
if (Test-Path "dist/$extZip") { Remove-Item "dist/$extZip" -Force }
|
||||
Compress-Archive -Path "$stageExt/*" -DestinationPath "dist/$extZip" -Force
|
||||
$stage = "dist/stage-bundle"
|
||||
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stage | Out-Null
|
||||
Copy-Item target/release/marqdo.exe "$stage/marqdo.exe"
|
||||
Copy-Item lib "$stage/lib" -Recurse
|
||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
||||
$stageLib = "dist/stage-stdlib"
|
||||
if (Test-Path $stageLib) { Remove-Item $stageLib -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stageLib | Out-Null
|
||||
Copy-Item lib "$stageLib/lib" -Recurse
|
||||
if (Test-Path "dist/$stdlib") { Remove-Item "dist/$stdlib" -Force }
|
||||
Compress-Archive -Path "$stageLib/*" -DestinationPath "dist/$stdlib" -Force
|
||||
echo "EXE=$exe" >> $env:GITHUB_ENV
|
||||
echo "ZIP=$zip" >> $env:GITHUB_ENV
|
||||
echo "STDLIB=$stdlib" >> $env:GITHUB_ENV
|
||||
echo "VSIX=$vsix" >> $env:GITHUB_ENV
|
||||
echo "SOURCE=$source" >> $env:GITHUB_ENV
|
||||
echo "PUBLIC=$public" >> $env:GITHUB_ENV
|
||||
echo "EXT=$extZip" >> $env:GITHUB_ENV
|
||||
|
||||
- name: Upload release assets
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
body: |
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### Highlights — 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 }}
|
||||
+50
@@ -0,0 +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/
|
||||
@@ -1,17 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 360" width="520" height="360" role="img" aria-label="function plot">
|
||||
<defs>
|
||||
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
|
||||
<path d="M 0 0 L 10 5 L 0 10 z" fill="#4b5563"/>
|
||||
</marker>
|
||||
</defs>
|
||||
<style>
|
||||
.grid { stroke: #e5e7eb; stroke-width: 1; }
|
||||
.axis { stroke: #4b5563; stroke-width: 1.5; }
|
||||
.tick { stroke: #4b5563; stroke-width: 1; }
|
||||
.curve { fill: none; stroke: #1f6feb; stroke-width: 2; }
|
||||
.pt { fill: #1f6feb; }
|
||||
.axis-label { font: 12px ui-sans-serif, system-ui, sans-serif; fill: #374151; font-weight: 600; }
|
||||
.tick-label { font: 10px ui-sans-serif, system-ui, sans-serif; fill: #6b7280; }
|
||||
</style>
|
||||
<line x1="36.00" y1="36" x2="36.00" y2="324" class="grid"/><line x1="110.67" y1="36" x2="110.67" y2="324" class="grid"/><line x1="185.33" y1="36" x2="185.33" y2="324" class="grid"/><line x1="260.00" y1="36" x2="260.00" y2="324" class="grid"/><line x1="334.67" y1="36" x2="334.67" y2="324" class="grid"/><line x1="409.33" y1="36" x2="409.33" y2="324" class="grid"/><line x1="484.00" y1="36" x2="484.00" y2="324" class="grid"/><line x1="36" y1="310.91" x2="484" y2="310.91" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="grid"/><line x1="36" y1="194.55" x2="484" y2="194.55" class="grid"/><line x1="36" y1="136.36" x2="484" y2="136.36" class="grid"/><line x1="36" y1="78.18" x2="484" y2="78.18" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="axis" marker-end="url(#arrow)"/><line x1="260.00" y1="324" x2="260.00" y2="36" class="axis" marker-end="url(#arrow)"/><text x="488.00" y="256.73" class="axis-label">x</text><text x="266.00" y="40.00" class="axis-label">y</text><line x1="36.00" y1="248.73" x2="36.00" y2="256.73" class="tick"/><text x="36.00" y="266.73" text-anchor="middle" class="tick-label">-3</text><line x1="110.67" y1="248.73" x2="110.67" y2="256.73" class="tick"/><text x="110.67" y="266.73" text-anchor="middle" class="tick-label">-2</text><line x1="185.33" y1="248.73" x2="185.33" y2="256.73" class="tick"/><text x="185.33" y="266.73" text-anchor="middle" class="tick-label">-1</text><line x1="334.67" y1="248.73" x2="334.67" y2="256.73" class="tick"/><text x="334.67" y="266.73" text-anchor="middle" class="tick-label">1</text><line x1="409.33" y1="248.73" x2="409.33" y2="256.73" class="tick"/><text x="409.33" y="266.73" text-anchor="middle" class="tick-label">2</text><line x1="484.00" y1="248.73" x2="484.00" y2="256.73" class="tick"/><text x="484.00" y="266.73" text-anchor="middle" class="tick-label">3</text><line x1="256.00" y1="310.91" x2="264.00" y2="310.91" class="tick"/><text x="252.00" y="310.91" text-anchor="end" dominant-baseline="middle" class="tick-label">-2</text><line x1="256.00" y1="194.55" x2="264.00" y2="194.55" class="tick"/><text x="252.00" y="194.55" text-anchor="end" dominant-baseline="middle" class="tick-label">2</text><line x1="256.00" y1="136.36" x2="264.00" y2="136.36" class="tick"/><text x="252.00" y="136.36" text-anchor="end" dominant-baseline="middle" class="tick-label">4</text><line x1="256.00" y1="78.18" x2="264.00" y2="78.18" class="tick"/><text x="252.00" y="78.18" text-anchor="end" dominant-baseline="middle" class="tick-label">6</text><text x="252.00" y="266.73" class="tick-label">0</text><path d="M 36.00 49.09 L 38.24 54.30 L 40.48 59.46 L 42.72 64.56 L 44.96 69.62 L 47.20 74.62 L 49.44 79.57 L 51.68 84.46 L 53.92 89.31 L 56.16 94.10 L 58.40 98.84 L 60.64 103.52 L 62.88 108.16 L 65.12 112.74 L 67.36 117.27 L 69.60 121.75 L 71.84 126.17 L 74.08 130.54 L 76.32 134.86 L 78.56 139.13 L 80.80 143.35 L 83.04 147.51 L 85.28 151.62 L 87.52 155.68 L 89.76 159.68 L 92.00 163.64 L 94.24 167.54 L 96.48 171.39 L 98.72 175.18 L 100.96 178.93 L 103.20 182.62 L 105.44 186.26 L 107.68 189.84 L 109.92 193.38 L 112.16 196.86 L 114.40 200.29 L 116.64 203.67 L 118.88 206.99 L 121.12 210.27 L 123.36 213.49 L 125.60 216.65 L 127.84 219.77 L 130.08 222.83 L 132.32 225.84 L 134.56 228.80 L 136.80 231.71 L 139.04 234.56 L 141.28 237.36 L 143.52 240.11 L 145.76 242.81 L 148.00 245.45 L 150.24 248.05 L 152.48 250.59 L 154.72 253.07 L 156.96 255.51 L 159.20 257.89 L 161.44 260.22 L 163.68 262.50 L 165.92 264.72 L 168.16 266.90 L 170.40 269.02 L 172.64 271.09 L 174.88 273.10 L 177.12 275.07 L 179.36 276.98 L 181.60 278.84 L 183.84 280.64 L 186.08 282.40 L 188.32 284.10 L 190.56 285.75 L 192.80 287.35 L 195.04 288.89 L 197.28 290.38 L 199.52 291.82 L 201.76 293.21 L 204.00 294.55 L 206.24 295.83 L 208.48 297.06 L 210.72 298.24 L 212.96 299.36 L 215.20 300.44 L 217.44 301.46 L 219.68 302.43 L 221.92 303.34 L 224.16 304.21 L 226.40 305.02 L 228.64 305.78 L 230.88 306.48 L 233.12 307.14 L 235.36 307.74 L 237.60 308.29 L 239.84 308.79 L 242.08 309.23 L 244.32 309.63 L 246.56 309.97 L 248.80 310.25 L 251.04 310.49 L 253.28 310.67 L 255.52 310.80 L 257.76 310.88 L 260.00 310.91 L 262.24 310.88 L 264.48 310.80 L 266.72 310.67 L 268.96 310.49 L 271.20 310.25 L 273.44 309.97 L 275.68 309.63 L 277.92 309.23 L 280.16 308.79 L 282.40 308.29 L 284.64 307.74 L 286.88 307.14 L 289.12 306.48 L 291.36 305.78 L 293.60 305.02 L 295.84 304.21 L 298.08 303.34 L 300.32 302.43 L 302.56 301.46 L 304.80 300.44 L 307.04 299.36 L 309.28 298.24 L 311.52 297.06 L 313.76 295.83 L 316.00 294.55 L 318.24 293.21 L 320.48 291.82 L 322.72 290.38 L 324.96 288.89 L 327.20 287.35 L 329.44 285.75 L 331.68 284.10 L 333.92 282.40 L 336.16 280.64 L 338.40 278.84 L 340.64 276.98 L 342.88 275.07 L 345.12 273.10 L 347.36 271.09 L 349.60 269.02 L 351.84 266.90 L 354.08 264.72 L 356.32 262.50 L 358.56 260.22 L 360.80 257.89 L 363.04 255.51 L 365.28 253.07 L 367.52 250.59 L 369.76 248.05 L 372.00 245.45 L 374.24 242.81 Line truncated
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 6.4 KiB |
@@ -1,135 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Welcome to Marqdo
|
||||
description: User-docs home — code as documentation (English)
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Hello — and welcome. I built Marqdo so that code is documentation and documentation is code: Markdown markers are the program structure, so what you read is what runs.
|
||||
|
||||
AI systems already favor Markdown-shaped output. That raised a simple question: why keep docs and programs as two separate artifacts? Marqdo is the answer. The `.mq.md` suffix exists so a file stays renderable as Markdown while remaining executable. Richer OKF-style YAML catalogs and even slide decks are on the roadmap; for now this site itself is generated by Marqdo — and that often saves tokens when an AI is writing with you.
|
||||
|
||||
The language is still early: structural markers, English/Chinese builtin aliases (`print` / `打印` …), an importable standard library (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Join in at [GitHub](https://github.com/cflmy/marqdo).
|
||||
|
||||
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
|
||||
|
||||
Want a quick hello? `marqdo run` executes the entry `# main`. Try **greet who="marqdo"**. Names can include spaces: **greet who="marqdo user"**.
|
||||
|
||||
This version also runs one function on its own. `marqdo call` takes the file, the function and named arguments. The page you read is the program that runs. What that is for, and why it matters, is in [features/22-call.mq.md](features/22-call.mq.md).
|
||||
|
||||
Beyond the basics, Marqdo ships table, time, text, files, system, math, foreign, and more. Math and foreign deserve a special mention.
|
||||
|
||||
Write a math block and bind it with a TeX comment:
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
Then plot it: **_svg = math.plot formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
Foreign lets you embed another language. Use Node Intl for locale-aware currency formatting, a genuine presentation boundary:
|
||||
|
||||
`hi` =
|
||||
```node
|
||||
console.log(new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"}).format(950));
|
||||
```
|
||||
|
||||
Under Markdown this stays easy to read — which is the point: code as documentation, documentation as code.
|
||||
|
||||
One file, three surfaces.
|
||||
|
||||
| Surface | What it is |
|
||||
|---|---|
|
||||
| Document | ordinary Markdown: prose, tables, links and fenced code |
|
||||
| Program | the same markers are executable: assignments, calls, returns |
|
||||
| Knowledge | frontmatter, links and generated catalog entries an agent can query |
|
||||
|
||||
The static site you are reading is generated from these files, so the examples are not screenshots. Run the same source and you get the same page.
|
||||
|
||||
Foreign v2 is a good example. Probe Node, then run the bound fence:
|
||||
|
||||
We first **node = [Check the formatting runtime](foreign.probe(lang="node"))** for the next step.
|
||||
|
||||
1. [ok](access(`node`, "ok"))
|
||||
We first **hello = [Format the native amount](foreign.run(code=`hi`))** for the next step.
|
||||
We now **[Display this step's result](> print text=`hello`)**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="(node not found — install Node to run this cell)")**.
|
||||
|
||||
The same module also supports JSON calls, parallel fan-out, persistent kernels and an explicit state bridge. See [stdlib/foreign.mq.md](stdlib/foreign.mq.md) and the native-first Intl walkthrough in [features/19-foreign-view-cells.mq.md](features/19-foreign-view-cells.mq.md).
|
||||
|
||||
A view document is still a document. Named kernels and a cell order are ordinary bound tables:
|
||||
|
||||
```text
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 说明 |
|
||||
|------|------|------|
|
||||
| 分析 | node | shared state |
|
||||
| 复核 | node | isolated state |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | write |
|
||||
| 计算指标 | 分析 | read |
|
||||
| 独立复核 | 复核 | validate |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
```
|
||||
|
||||
`marqdo view` consumes the foreign-owned `会话` handle and turns it into Run All, Step, per-cell kernels, a journal and a state panel. Without `会话`, cells are stateless one-shot runs. There is no separate interactive mode or command; `marqdo run` still executes the file as one program.
|
||||
|
||||
Documentation becomes knowledge when it can be discovered, verified and reused. OKF supplies the portable Markdown + YAML shape; EKC projects the repository into catalog layers L0–L4, a graph and an engineering preflight. The source `.mq.md` remains the only authority; generated artifacts are marked and rebuildable.
|
||||
|
||||
| Loop | Question |
|
||||
|---|---|
|
||||
| OKF | How do people and agents share a readable knowledge page? |
|
||||
| EKC | What existing capability, decision, constraint or failure should be reused before creating more? |
|
||||
| Preflight | REUSE → ADAPT → CREATE |
|
||||
|
||||
Read [features/20-okf-ekc.mq.md](features/20-okf-ekc.mq.md) for the concepts and commands.
|
||||
|
||||
Welcome again — enjoy exploring Marqdo.
|
||||
|
||||
Installation choices.
|
||||
|
||||
Install the interpreter (CLI) in any of these ways:
|
||||
|
||||
| Way | Notes |
|
||||
|------|------|
|
||||
| Ubuntu PPA | sudo add-apt-repository ppa:cflmy/marqdo then sudo apt install marqdo |
|
||||
| GitHub Releases | Prebuilt Windows / Linux packages from [releases](https://github.com/cflmy/marqdo/releases) |
|
||||
| From source | cargo build --release (needs a local Rust toolchain) |
|
||||
|
||||
Official extensions update independently of the CLI:
|
||||
|
||||
```text
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
`ext add` tries CDN https://ext.marqdo.com first, then GitHub, then the proxy mirror. See [`features/05-extensions.mq.md`](features/05-extensions.mq.md).
|
||||
|
||||
|
||||
## greet
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| who | any | required | Recipient name inserted into the greeting |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; this function performs the described effects instead of returning business data |
|
||||
|
||||
When we meet a visitor `who`, we **print text="Welcome, `who`!"** and close with*None*.
|
||||
@@ -1,17 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 360" width="520" height="360" role="img" aria-label="function plot">
|
||||
<defs>
|
||||
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
|
||||
<path d="M 0 0 L 10 5 L 0 10 z" fill="#4b5563"/>
|
||||
</marker>
|
||||
</defs>
|
||||
<style>
|
||||
.grid { stroke: #e5e7eb; stroke-width: 1; }
|
||||
.axis { stroke: #4b5563; stroke-width: 1.5; }
|
||||
.tick { stroke: #4b5563; stroke-width: 1; }
|
||||
.curve { fill: none; stroke: #1f6feb; stroke-width: 2; }
|
||||
.pt { fill: #1f6feb; }
|
||||
.axis-label { font: 12px ui-sans-serif, system-ui, sans-serif; fill: #374151; font-weight: 600; }
|
||||
.tick-label { font: 10px ui-sans-serif, system-ui, sans-serif; fill: #6b7280; }
|
||||
</style>
|
||||
<line x1="36.00" y1="36" x2="36.00" y2="324" class="grid"/><line x1="110.67" y1="36" x2="110.67" y2="324" class="grid"/><line x1="185.33" y1="36" x2="185.33" y2="324" class="grid"/><line x1="260.00" y1="36" x2="260.00" y2="324" class="grid"/><line x1="334.67" y1="36" x2="334.67" y2="324" class="grid"/><line x1="409.33" y1="36" x2="409.33" y2="324" class="grid"/><line x1="484.00" y1="36" x2="484.00" y2="324" class="grid"/><line x1="36" y1="310.91" x2="484" y2="310.91" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="grid"/><line x1="36" y1="194.55" x2="484" y2="194.55" class="grid"/><line x1="36" y1="136.36" x2="484" y2="136.36" class="grid"/><line x1="36" y1="78.18" x2="484" y2="78.18" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="axis" marker-end="url(#arrow)"/><line x1="260.00" y1="324" x2="260.00" y2="36" class="axis" marker-end="url(#arrow)"/><text x="488.00" y="256.73" class="axis-label">x</text><text x="266.00" y="40.00" class="axis-label">y</text><line x1="36.00" y1="248.73" x2="36.00" y2="256.73" class="tick"/><text x="36.00" y="266.73" text-anchor="middle" class="tick-label">-3</text><line x1="110.67" y1="248.73" x2="110.67" y2="256.73" class="tick"/><text x="110.67" y="266.73" text-anchor="middle" class="tick-label">-2</text><line x1="185.33" y1="248.73" x2="185.33" y2="256.73" class="tick"/><text x="185.33" y="266.73" text-anchor="middle" class="tick-label">-1</text><line x1="334.67" y1="248.73" x2="334.67" y2="256.73" class="tick"/><text x="334.67" y="266.73" text-anchor="middle" class="tick-label">1</text><line x1="409.33" y1="248.73" x2="409.33" y2="256.73" class="tick"/><text x="409.33" y="266.73" text-anchor="middle" class="tick-label">2</text><line x1="484.00" y1="248.73" x2="484.00" y2="256.73" class="tick"/><text x="484.00" y="266.73" text-anchor="middle" class="tick-label">3</text><line x1="256.00" y1="310.91" x2="264.00" y2="310.91" class="tick"/><text x="252.00" y="310.91" text-anchor="end" dominant-baseline="middle" class="tick-label">-2</text><line x1="256.00" y1="194.55" x2="264.00" y2="194.55" class="tick"/><text x="252.00" y="194.55" text-anchor="end" dominant-baseline="middle" class="tick-label">2</text><line x1="256.00" y1="136.36" x2="264.00" y2="136.36" class="tick"/><text x="252.00" y="136.36" text-anchor="end" dominant-baseline="middle" class="tick-label">4</text><line x1="256.00" y1="78.18" x2="264.00" y2="78.18" class="tick"/><text x="252.00" y="78.18" text-anchor="end" dominant-baseline="middle" class="tick-label">6</text><text x="252.00" y="266.73" class="tick-label">0</text><path d="M 36.00 49.09 L 38.24 54.30 L 40.48 59.46 L 42.72 64.56 L 44.96 69.62 L 47.20 74.62 L 49.44 79.57 L 51.68 84.46 L 53.92 89.31 L 56.16 94.10 L 58.40 98.84 L 60.64 103.52 L 62.88 108.16 L 65.12 112.74 L 67.36 117.27 L 69.60 121.75 L 71.84 126.17 L 74.08 130.54 L 76.32 134.86 L 78.56 139.13 L 80.80 143.35 L 83.04 147.51 L 85.28 151.62 L 87.52 155.68 L 89.76 159.68 L 92.00 163.64 L 94.24 167.54 L 96.48 171.39 L 98.72 175.18 L 100.96 178.93 L 103.20 182.62 L 105.44 186.26 L 107.68 189.84 L 109.92 193.38 L 112.16 196.86 L 114.40 200.29 L 116.64 203.67 L 118.88 206.99 L 121.12 210.27 L 123.36 213.49 L 125.60 216.65 L 127.84 219.77 L 130.08 222.83 L 132.32 225.84 L 134.56 228.80 L 136.80 231.71 L 139.04 234.56 L 141.28 237.36 L 143.52 240.11 L 145.76 242.81 L 148.00 245.45 L 150.24 248.05 L 152.48 250.59 L 154.72 253.07 L 156.96 255.51 L 159.20 257.89 L 161.44 260.22 L 163.68 262.50 L 165.92 264.72 L 168.16 266.90 L 170.40 269.02 L 172.64 271.09 L 174.88 273.10 L 177.12 275.07 L 179.36 276.98 L 181.60 278.84 L 183.84 280.64 L 186.08 282.40 L 188.32 284.10 L 190.56 285.75 L 192.80 287.35 L 195.04 288.89 L 197.28 290.38 L 199.52 291.82 L 201.76 293.21 L 204.00 294.55 L 206.24 295.83 L 208.48 297.06 L 210.72 298.24 L 212.96 299.36 L 215.20 300.44 L 217.44 301.46 L 219.68 302.43 L 221.92 303.34 L 224.16 304.21 L 226.40 305.02 L 228.64 305.78 L 230.88 306.48 L 233.12 307.14 L 235.36 307.74 L 237.60 308.29 L 239.84 308.79 L 242.08 309.23 L 244.32 309.63 L 246.56 309.97 L 248.80 310.25 L 251.04 310.49 L 253.28 310.67 L 255.52 310.80 L 257.76 310.88 L 260.00 310.91 L 262.24 310.88 L 264.48 310.80 L 266.72 310.67 L 268.96 310.49 L 271.20 310.25 L 273.44 309.97 L 275.68 309.63 L 277.92 309.23 L 280.16 308.79 L 282.40 308.29 L 284.64 307.74 L 286.88 307.14 L 289.12 306.48 L 291.36 305.78 L 293.60 305.02 L 295.84 304.21 L 298.08 303.34 L 300.32 302.43 L 302.56 301.46 L 304.80 300.44 L 307.04 299.36 L 309.28 298.24 L 311.52 297.06 L 313.76 295.83 L 316.00 294.55 L 318.24 293.21 L 320.48 291.82 L 322.72 290.38 L 324.96 288.89 L 327.20 287.35 L 329.44 285.75 L 331.68 284.10 L 333.92 282.40 L 336.16 280.64 L 338.40 278.84 L 340.64 276.98 L 342.88 275.07 L 345.12 273.10 L 347.36 271.09 L 349.60 269.02 L 351.84 266.90 L 354.08 264.72 L 356.32 262.50 L 358.56 260.22 L 360.80 257.89 L 363.04 255.51 L 365.28 253.07 L 367.52 250.59 L 369.76 248.05 L 372.00 245.45 L 374.24 242.81 Line truncated
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 6.4 KiB |
-135
@@ -1,135 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 欢迎使用 Marqdo
|
||||
description: 用户文档首页 — 代码即文档(中文版)
|
||||
导入:
|
||||
数学: lib/数学.mq.md
|
||||
外联: lib/外联.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门「代码即文档,文档即代码」的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
|
||||
|
||||
AI 偏爱 Markdown 结构的输出。我当时的念头很简单——何必再把文档和代码拆成两套?于是有了 marqdo。为了让文件既能当文档渲染又能执行,后缀定为 `.mq.md`。更远的目标还有 OKF 式知识库的 YAML、甚至自动生成 PPT;眼下它至少已经是个不错的博客工具——对,这个站点就是 Marqdo 生成的。AI 写 `.mq.md` 时往往更省 token,钱包也会轻松一点。
|
||||
|
||||
语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
|
||||
|
||||
English docs: [`00-welcome.mq.md`](00-welcome.mq.md)(English prose and English builtins).
|
||||
|
||||
想先打个招呼?`marqdo run` 会运行入口 `# main`。比如:**问候 谁="marqdo"**。名字里可以带空格:**问候 谁="marqdo user"**。
|
||||
|
||||
从这一版起,不必为了试用一个函数再包一层入口。`marqdo call` 直接运行文件里的某个函数,参数写在命令上。同一页仍然是给人读的文档。作用和价值写在 [features/22-函数调用.mq.md](features/22-函数调用.mq.md)。
|
||||
|
||||
除了这些基本面,标准库里还有表、时间、文本、文件、系统、数学、外联等。我特别想提数学和外联。
|
||||
|
||||
比方说,直接写一块公式,并用 TeX 注释标上变量名:
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
接着画出来:**_svg = 数学.绘图 formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
外联则允许嵌一段别的语言。把`hi`绑成下面这样即可:
|
||||
|
||||
`hi` =
|
||||
```node
|
||||
console.log(new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"}).format(950));
|
||||
```
|
||||
|
||||
这些在 Markdown 里读起来仍然像文章——这就是 marqdo 想坚持的:代码即文档,文档即代码。
|
||||
|
||||
一份文件,三个面。
|
||||
|
||||
| 面 | 是什么 |
|
||||
|---|---|
|
||||
| 文档 | 普通 Markdown:叙述、表格、链接、围栏代码 |
|
||||
| 程序 | 同一批标记可执行:赋值、调用、返回 |
|
||||
| 知识 | frontmatter、链接与生成的 catalog 条目,Agent 可查询 |
|
||||
|
||||
你正在读的静态站就是由这些文件生成的,所以示例不是截图。运行同一份源,会得到同一页。
|
||||
|
||||
外联 v2 是个好例子。先探测 Node,再运行绑定围栏:
|
||||
|
||||
我们先**node = [检查本地化展示所需的解释器](外联.探测(语言="node"))**,供下一步使用。
|
||||
|
||||
1. [ok](access(`node`, "ok"))
|
||||
我们先**问候 = [通过 Intl 展示原生金额](外联.运行(代码=`hi`))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`问候`)**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="(未找到 node — 安装 Node 后可运行此单元)")**。
|
||||
|
||||
同一个模块还支持 JSON 调用、并行扇出、持久内核与显式状态桥。见 [stdlib/外联.mq.md](stdlib/外联.mq.md) 与原生分析与 Intl 示例 [features/19-外联视图单元.mq.md](features/19-外联视图单元.mq.md)。
|
||||
|
||||
view 仍然是一篇文档。命名内核与单元顺序就是普通绑定表:
|
||||
|
||||
```text
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 说明 |
|
||||
|------|------|------|
|
||||
| 分析 | node | 共享状态 |
|
||||
| 复核 | node | 隔离状态 |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | 写入 |
|
||||
| 计算指标 | 分析 | 读取 |
|
||||
| 独立复核 | 复核 | 校验 |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
```
|
||||
|
||||
`marqdo view` 消费 foreign 拥有的 `会话` 句柄,变成 Run All、Step、每单元内核、journal 与状态面板。没有 `会话` 时,单元是无状态的一次性运行。没有单独的交互模式或命令;`marqdo run` 仍然把文件当单个程序运行。
|
||||
|
||||
文档能被发现、验证和复用时,才成为知识。OKF 提供可移植的 Markdown + YAML 形态;EKC 把仓库投影成 catalog L0–L4、图与工程 preflight。源 `.mq.md` 始终是唯一权威,生成物有标记、可重建。
|
||||
|
||||
| 循环 | 问题 |
|
||||
|---|---|
|
||||
| OKF | 人和 Agent 如何共享一页可读知识? |
|
||||
| EKC | 创建之前,应该复用哪些已有能力、决策、约束与失败? |
|
||||
| Preflight | REUSE → ADAPT → CREATE |
|
||||
|
||||
概念与命令见 [features/20-OKF与EKC.mq.md](features/20-OKF与EKC.mq.md)。
|
||||
|
||||
最后,再次欢迎你,尽情体验 marqdo 吧!
|
||||
|
||||
安装方式。
|
||||
|
||||
解释器(CLI)任选其一:
|
||||
|
||||
| 方式 | 说明 |
|
||||
|------|------|
|
||||
| Ubuntu PPA | sudo add-apt-repository ppa:cflmy/marqdo 后 sudo apt install marqdo |
|
||||
| GitHub Releases | [releases](https://github.com/cflmy/marqdo/releases) 下载 Windows / Linux 预编译包 |
|
||||
| 源码 | cargo build --release(需本机 Rust) |
|
||||
|
||||
官方扩展与 CLI 可分开更新。安装扩展:
|
||||
|
||||
```text
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
`ext add` 下载顺序:CDN https://ext.marqdo.com → GitHub → proxy 镜像。详见本站 [`features/05-扩展.mq.md`](features/05-扩展.mq.md)。
|
||||
|
||||
|
||||
## 问候
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 谁 | any | 必填 | 要显示在问候中的称呼 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;本函数通过上述操作产生效果,不返回业务数据。 |
|
||||
|
||||
见到访客`谁`时,我们 **打印 内容="欢迎,`谁`!"**,然后收束为*None*。
|
||||
@@ -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
+1661
File diff suppressed because it is too large.
Load diff
+36
@@ -0,0 +1,36 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.2.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
readme = "README.md"
|
||||
repository = "https://github.com/cflmy/marqdo"
|
||||
|
||||
[[bin]]
|
||||
name = "marqdo"
|
||||
path = "src/main.rs"
|
||||
|
||||
[dependencies]
|
||||
anyhow = "1"
|
||||
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
|
||||
clap = { version = "=4.4.18", features = ["derive"] }
|
||||
pulldown-cmark = "0.12"
|
||||
serde_json = "1"
|
||||
thiserror = "1"
|
||||
tiny_http = "0.12"
|
||||
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"] }
|
||||
idna_adapter = "=1.1.0"
|
||||
zeroize = "=1.8.1"
|
||||
libloading = "=0.8.6"
|
||||
include_dir = "0.7"
|
||||
libc = "0.2"
|
||||
|
||||
[workspace]
|
||||
members = ["plugins/demo", "plugins/agent", "plugins/web", "plugins/quantum"]
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
assert_cmd = "=2.0.14"
|
||||
predicates = "=3.1.0"
|
||||
@@ -0,0 +1,201 @@
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
@@ -1,34 +1,137 @@
|
||||
# 用户文档(可执行 · 可下载 · 中英双语)
|
||||
# Marqdo
|
||||
|
||||
本目录即面向访客的 Marqdo 介绍:每个 `.mq.md` 既是文稿也能 `marqdo run`,并随仓库 / 静态站一起下载。
|
||||
**代码即文档。文档即代码。文档即知识库。**
|
||||
|
||||
**双语约定:** 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程。成对放在同一目录。标准库:拉丁路径用英文 API,中文路径用中文 API;JSON 仅 `lib/json.mq.md`。
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
|
||||
|
||||
| 路径 | 内容 |
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 为什么重要
|
||||
|
||||
| 痛点 | Marqdo 的答案 |
|
||||
|------|----------------|
|
||||
| 文档过期、示例跑不通 | **一份源文件**:叙述、结构与执行结果同源 |
|
||||
| 知识散落在 Wiki / 注释 / 脚本里 | **`.mq.md` 即知识单元**,可浏览、可运行、可检索 |
|
||||
| 人写给人看,AI / 工具另起一套 | **人机同读同写同构**:标记语言对人类友好,对解释器确定 |
|
||||
| 大仓里「文档站」与「代码仓」脱节 | `view` 文档站 + `debug` 调试面 + `catalog` 清单,同一棵树长大 |
|
||||
|
||||
这不是「再做一个 Markdown 渲染器」,而是:**把文档升格为可解释的程序与可生长的知识库**,让协作在大型项目里依然站得住。
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.2)
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| [`00-welcome.mq.md`](00-welcome.mq.md) / [`00-欢迎.mq.md`](00-欢迎.mq.md) | 首页(英 / 中) |
|
||||
| [`structure/`](structure/) | 基本结构 |
|
||||
| [`keywords/`](keywords/) | 关键字与 L0 内置 |
|
||||
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件/**自写回**/**子任务**;v0.1.2+ 内置于 CLI) |
|
||||
| [`features/`](features/) | 特性迭代(含对象、官方 `ext/`) |
|
||||
| [`features/19-foreign-view-cells.mq.md`](features/19-foreign-view-cells.mq.md) / [`19-外联视图单元.mq.md`](features/19-外联视图单元.mq.md) | 外联 v2 完整 Python 示例:probe / JSON call / 并行 / 持久内核 / 状态桥 / view 单元 |
|
||||
| [`features/20-okf-ekc.mq.md`](features/20-okf-ekc.mq.md) / [`20-OKF与EKC.mq.md`](features/20-OKF与EKC.mq.md) | 代码即文档、文档即知识:OKF 形态与 EKC 工程知识编译器 |
|
||||
| [`features/21-persistence.mq.md`](features/21-persistence.mq.md) / [`21-持久化.mq.md`](features/21-持久化.mq.md) | 外联结果持久化:静态快照与 writeback |
|
||||
| [`features/22-call.mq.md`](features/22-call.mq.md) / [`22-函数调用.mq.md`](features/22-函数调用.mq.md) | `marqdo call`:同一份文档按函数执行,知识可以直接当工具 |
|
||||
| 无标记行 | 注释(空行分段) |
|
||||
| `*…*` | 程序语句 |
|
||||
| `**…**` | **返回值**(架构) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||||
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
|
||||
| `##` … | 函数 / 方法(按标题深度嵌套) |
|
||||
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
|
||||
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) `` / `` - [`项`](`集合`) ``) |
|
||||
| 表格 | 集合 |
|
||||
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
|
||||
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
|
||||
|
||||
官方扩展(非 stdlib):`ext/llm`、`ext/agent`、`ext/web`、`ext/quantum`、`ext/linalg` — 见 `features/05-*.mq.md`、`06-*.mq.md`、`07-linalg.mq.md` / `07-线性代数.mq.md` 与 `doc/design/ext-*.md`。
|
||||
```markdown
|
||||
# main
|
||||
|
||||
中层标准库(Mid):`08`–`12`(re/encoding · path/fs · hash/secrets · csv/text · list/cli;及对应中文页)。
|
||||
> 问候 谁=World
|
||||
|
||||
**不放** `errors/`:失败样例只在 `tests/errors/`。
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
开发文档在 [`doc/`](../doc/)。
|
||||
> print text=Hello `谁`!
|
||||
|
||||
## 浏览与生成 HTML
|
||||
---
|
||||
|
||||
```bash
|
||||
cargo run -- view public
|
||||
cargo run -- view output public -o public
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
详见 [user-site.md](../doc/design/user-site.md)。
|
||||
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
|
||||
|
||||
---
|
||||
|
||||
## 理念
|
||||
|
||||
1. **叙述默认安全**(无标记 = 注释)。
|
||||
2. **返回是架构;打印只是函数。**
|
||||
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
|
||||
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||||
|
||||
---
|
||||
|
||||
## OKF 风格清单(自动生成)
|
||||
|
||||
从源码派生 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/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [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
|
||||
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
|
||||
```
|
||||
|
||||
**发布包(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)
|
||||
|
||||
---
|
||||
|
||||
## 命名
|
||||
|
||||
**Marqdo** = Marq(Markdown)+ do(执行)
|
||||
|
||||
## 许可
|
||||
|
||||
[Apache License 2.0](LICENSE)
|
||||
@@ -0,0 +1,70 @@
|
||||
# Marqdo 开发文档
|
||||
|
||||
本目录存放各阶段设计、选型与路线图。
|
||||
|
||||
## 目录约定
|
||||
|
||||
| 路径 | 用途 |
|
||||
|------|------|
|
||||
| [`research/`](research/) | 外部标准与调研 |
|
||||
| [`design/`](design/) | 语言设计(语法映射等) |
|
||||
| [`adr/`](adr/) | 架构决策记录 |
|
||||
| [`roadmap/`](roadmap/) | 实现路线与里程碑 |
|
||||
|
||||
## 当前文档
|
||||
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [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/okf.md](design/okf.md) | **Marqdo OKF 实现规范**(catalog v0 + 任务知识包) |
|
||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
||||
| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
|
||||
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
|
||||
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
|
||||
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置函数** |
|
||||
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
|
||||
| [design/module-namespace.md](design/module-namespace.md) | **模块命名空间:导入绑定库名、`库.成员` / `use`(M1+M2 已落地)** |
|
||||
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** |
|
||||
| [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** |
|
||||
| [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** |
|
||||
| [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/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/)。
|
||||
|
||||
## 写作原则
|
||||
|
||||
1. 先宪法与路线图,再实现。
|
||||
2. 金样例不过 = 未完成。
|
||||
3. 示例统一 `.mq.md`。
|
||||
@@ -0,0 +1,53 @@
|
||||
# ADR 0001:参考实现语言与前端工具
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**(修订:实现语言 = Rust) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 决策者 | chaungming + 协作 |
|
||||
| 相关 | [dependencies.md](../design/dependencies.md) · [interpreter 路线图](../roadmap/interpreter.md) · [spike/REPORT.md](../../spike/REPORT.md) |
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
语法宪法 v0.1 已定;Python Spike 已验证 GFM/行扫描风险。产品目标是正经**解释器**(`marqdo run index.mq.md`),实现语言需兼顾安全与可维护性。
|
||||
|
||||
---
|
||||
|
||||
## 决策
|
||||
|
||||
1. **参考解释器实现语言:Rust(stable)**
|
||||
- 内存安全、单静态二进制、适合长期演进到字节码 VM。
|
||||
- Python Spike **保留为算法原型/对照**,不是运行时依赖。
|
||||
|
||||
2. **词法 / 语法:不使用 Flex、Bison**
|
||||
- **主因是 Marqdo 的 Markdown 语法形态**,不是「因为选了 Rust」。换成 C++ 同样不建议用 Flex/Bison 做整语言前端。
|
||||
- 解释器需要词法·语法**阶段**;采用自研行分类 + GFM 库 + **手写递归下降** → AST。
|
||||
- 详见 [dependencies.md](../design/dependencies.md)。
|
||||
|
||||
3. **架构分期不变**
|
||||
- Phase I:树遍历解释器
|
||||
- Phase II:字节码 + VM
|
||||
- 见 [interpreter.md](../roadmap/interpreter.md)
|
||||
|
||||
4. **Markdown 库**
|
||||
- `pulldown-cmark` 或 `comrak` 二选一(建包前短 Spike 钉死)。
|
||||
|
||||
---
|
||||
|
||||
## 后果
|
||||
|
||||
- 正式代码以 Cargo 工程生长;不把 Flex/Bison/LLVM 列入 v1 依赖。
|
||||
- 金样例仍为 `tests/`;行为与宪法一致。
|
||||
- 此前「Python 作参考实现」的倾向由本修订取代;Spike 结论(行扫描等)仍然有效并迁入 Rust。
|
||||
|
||||
---
|
||||
|
||||
## 否决
|
||||
|
||||
| 方案 | 原因 |
|
||||
|------|------|
|
||||
| Flex + Bison 作主前端 | 与 Markup-as-Syntax / Rust 栈错配;解释器非必需 |
|
||||
| v1 上 LLVM | 产品是解释执行文档,不是机器后端 |
|
||||
| 仅 Python 正则玩具 | 达不到安全与长期目标 |
|
||||
@@ -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 是面向模型的压缩操作手册。
|
||||
@@ -0,0 +1,90 @@
|
||||
# Marqdo 字节码(M5 原型)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 进行中(原型) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [roadmap/interpreter.md](../roadmap/interpreter.md) · Phase I 树遍历 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在保留树遍历后端(`--backend tree`,默认)的同时,提供栈式字节码 VM(`--backend bytecode`),使**核心金样例** stdout 与树遍历 bit 一致。
|
||||
|
||||
```
|
||||
.mq.md → load/parse → Module AST
|
||||
├─ tree-walk
|
||||
└─ compile → Chunk → VM
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 指令集(草案 / 原型已实现子集)
|
||||
|
||||
| Op | 栈效应 | 说明 |
|
||||
|----|--------|------|
|
||||
| `Constant i` | → v | 常量池 |
|
||||
| `True` / `False` / `None` | → b | |
|
||||
| `Pop` | v → | |
|
||||
| `GetLocal i` / `SetLocal i` | | 当前帧槽 |
|
||||
| `GetGlobal i` / `SetGlobal i` | | 名字在常量池(文本) |
|
||||
| `Add` `Sub` `Mul` `Div` `Negate` `Not` | | |
|
||||
| `Equal` `NotEqual` `Greater` `GreaterEqual` `Less` `LessEqual` | | |
|
||||
| `Jump a` / `JumpIfFalse a` / `JumpBack a` | | 相对/绝对跳转(原型用绝对 u16) |
|
||||
| `Print` | v → | 弹出并写 stdout |
|
||||
| `BuildList n` | v… → list | |
|
||||
| `GetIndex` | list, i → v | foreach 用 |
|
||||
| `Call f argc` | args… → ret | 用户函数(按形参序压栈) |
|
||||
| `Return` | | 返回 / 结束帧 |
|
||||
| `Interp n` | parts… → text | n 个交错 Lit/Var 标记后的拼接(简化:编译期展开为常量+拼接) |
|
||||
|
||||
原型实现以 `src/bytecode/` 为准;未列出的 Op 不存在于当前构建。
|
||||
|
||||
---
|
||||
|
||||
## 3. 编译约定
|
||||
|
||||
- 每个 Marqdo `Function` → 一个 `FnChunk`(含 `name`、`params`、`code`、`constants`)。
|
||||
- 模块级 `Program`:函数表 + 入口名(`main` 或唯一无参 level-1)。
|
||||
- 局部变量:函数体内首次赋值/形参分配槽位。
|
||||
- 嵌套 `##`:编入同一 `Program`,按名 `Call`;查找规则对齐树遍历(子树优先,再顶层)。
|
||||
- `and` / `or`:短接跳转。
|
||||
- 分支 / while:`JumpIfFalse` + `Jump` / `JumpBack`。
|
||||
- foreach:`BuildList` 或已有 list 全局/局部 → 索引循环。
|
||||
|
||||
---
|
||||
|
||||
## 4. 覆盖表(M5 原型)
|
||||
|
||||
| 金样例 | tree | bytecode |
|
||||
|--------|------|----------|
|
||||
| `structure/hello` | ✅ | ✅ |
|
||||
| `structure/branch` | ✅ | ✅ |
|
||||
| `structure/loop` | ✅ | ✅ |
|
||||
| `structure/collection` | ✅ | ✅ |
|
||||
| `keywords/print` | ✅ | ✅ |
|
||||
| `keywords/bool-logic` | ✅ | ✅ |
|
||||
| `structure/nested-call` | ✅ | ✅ |
|
||||
| `structure/positional-call` | ✅ | ✅ |
|
||||
| `structure/import/*` | ✅ | ✅(导入模块树后编译) |
|
||||
| `structure/ns/*` | ✅ | ✅ |
|
||||
| `tests/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) |
|
||||
|
||||
核心金样例双后端已对齐;后续可扩展 Op、优化与更好的调试信息。
|
||||
|
||||
---
|
||||
|
||||
## 5. CLI
|
||||
|
||||
```bash
|
||||
marqdo run FILE --backend tree # 默认
|
||||
marqdo run FILE --backend bytecode
|
||||
marqdo run FILE --dump-bytecode # 反汇编后仍可按 backend 执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 非目标(本原型)
|
||||
|
||||
优化、寄存器分配、GC、与树遍历指令级调试对齐、独立 sema IR。
|
||||
@@ -0,0 +1,53 @@
|
||||
# 调用实参:具名与位置
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.1 增补) |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`>` 调用同时支持:
|
||||
|
||||
| 形式 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| **具名**(保留) | `> 问候 谁=Marqdo` | `名=值`;值可含空格(至下一 `名=`) |
|
||||
| **位置**(新增) | `> 问候 Marqdo` | 按形参声明顺序绑定 |
|
||||
|
||||
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 文法(调用尾部)
|
||||
|
||||
```
|
||||
call_tail ::= callee arg*
|
||||
arg ::= named | positional
|
||||
named ::= ident '=' value
|
||||
positional ::= value_token
|
||||
```
|
||||
|
||||
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
|
||||
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
|
||||
- 内置 `print` / `打印` 形参:`text` ≡ `内容`。
|
||||
- `input` / `输入`:`prompt` ≡ `提示`。
|
||||
- `len` / `长度`、`str` / `文本`、`int` / `整数`:`value` ≡ `值`。
|
||||
- 完整中英双名见 [keywords-i18n.md](keywords-i18n.md)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 绑定算法
|
||||
|
||||
1. 收集具名 → 映射;冲突则报错。
|
||||
2. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
|
||||
3. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
|
||||
4. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
|
||||
|
||||
---
|
||||
|
||||
## 4. 金样例
|
||||
|
||||
见 `tests/structure/positional-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
|
||||
@@ -0,0 +1,127 @@
|
||||
# OKF 兼容清单:`marqdo catalog`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(O1 + O3:工程目录包 + agent-kb 概念并入) |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 |
|
||||
| 相关 | [okf.md](okf.md)(**实现规范总览**)· [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 决策(重申)
|
||||
|
||||
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。完整词汇、任务知识包与路线图见 [**okf.md**](okf.md)。生成式方向见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
|
||||
|
||||
本文件规定 **CLI 与工程目录包落盘格式**(含 O3:扫入本地 `agent-kb` 概念,供人与工具同览)。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI
|
||||
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
# 别名(与早期草案一致)
|
||||
marqdo sync [PATH] -o OUT_DIR
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
|
||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
|
||||
|
||||
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 生成物
|
||||
|
||||
```
|
||||
OUT_DIR/
|
||||
catalog.yaml # 机器向总清单(OKF 风格字段)
|
||||
index.md # 人可读总览:Modules + Agent knowledge
|
||||
modules/
|
||||
<stem>.md # 每个工程 .mq.md 一个 Module 页
|
||||
concepts/ # 从 **/.marqdo/agent-kb/concepts/ 复制(O3)
|
||||
tasks/…
|
||||
skills/…
|
||||
```
|
||||
|
||||
路径中的目录层级拍扁为文件名时用 `__` 连接,例如:
|
||||
|
||||
`structure/import/main.mq.md` → `modules/structure__import__main.md`
|
||||
|
||||
`.marqdo/agent-kb/` 下的可执行 `.mq.md` **不**进 Module 表(由 Task/Skill 概念页的 `resource` 指向)。
|
||||
|
||||
### 3.1 `catalog.yaml`(示意)
|
||||
|
||||
```yaml
|
||||
# GENERATED by marqdo — do not edit by hand
|
||||
type: Marqdo Catalog
|
||||
title: marqdo-project
|
||||
generated:
|
||||
by: marqdo/0.1.2
|
||||
modules:
|
||||
- id: structure/hello
|
||||
resource: structure/hello.mq.md
|
||||
title: Hello World
|
||||
imports: []
|
||||
exports:
|
||||
- name: Hello World
|
||||
kind: fn
|
||||
- id: structure/import/main
|
||||
resource: structure/import/main.mq.md
|
||||
imports:
|
||||
- utils.mq.md
|
||||
exports:
|
||||
- name: main
|
||||
kind: fn
|
||||
concepts: [] # 有 agent-kb 时为 Task/Skill 条目列表
|
||||
```
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) |
|
||||
| `modules[].resource` | 相对 `PATH` 的源路径 |
|
||||
| `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` |
|
||||
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`) |
|
||||
| `modules[].verified` / `sources` | 源 frontmatter 有则透传(O3) |
|
||||
| `concepts[]` | 本地 agent-kb 概念摘要(`id`/`type`/`page`/…) |
|
||||
| `generated.by` | `marqdo/<crate version>` |
|
||||
|
||||
不在现行范围:版本锁定哈希、跨仓 URL、完整符号类型、`log.md`(见 okf O4)。
|
||||
|
||||
### 3.2 模块概念页
|
||||
|
||||
Frontmatter 仍用 `depends` 字符串列表(机器可读);**正文 Dependencies** 链到同包其它 Module 页(人可点)。源若带 `verified` / `sources` 则写入页头。
|
||||
|
||||
### 3.3 Agent knowledge
|
||||
|
||||
`index.md` 的 **Agent knowledge** 节列出扫到的 Task/Skill,链到 `concepts/…`。概念页内容从本地 `agent-kb` **复制**,与 Agent 运行时包同源,便于人审阅晋升结果。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 `view output` 的分工
|
||||
|
||||
| 命令 | 产物 | 受众 |
|
||||
|------|------|------|
|
||||
| `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
|
||||
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引(含 agent-kb) | 人浏览依赖/技能 · 工具 / Agent |
|
||||
|
||||
二者都从同一源树生成,互不替代。发布用户文档时可同时:
|
||||
|
||||
```bash
|
||||
marqdo view output public -o public
|
||||
marqdo catalog tests -o .marqdo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml`、`modules/`、`concepts:` 键。
|
||||
2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。
|
||||
3. 模块页 Dependencies 对已解析导入为 Markdown 链接。
|
||||
4. 若扫描根下有 `.marqdo/agent-kb/concepts/`,则复制进 `OUT_DIR/concepts/` 且 `index.md` 有 Agent knowledge 条目。
|
||||
5. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
|
||||
6. `marqdo sync` 与 `catalog` 行为一致。
|
||||
@@ -0,0 +1,38 @@
|
||||
# 可执行面与叙述面
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 与 mapping v0.1 / keywords 对齐(成段注释) |
|
||||
| 日期 | 2026-08-04 |
|
||||
|
||||
---
|
||||
|
||||
## 三层
|
||||
|
||||
| 层 | 形态 | 角色 |
|
||||
|----|------|------|
|
||||
| **叙述面** | 成段注释(空行分段) | 注释;段内任意标记无语义 |
|
||||
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
|
||||
| **外联面** | ` ```lang ` | 其它语言(FFI) |
|
||||
|
||||
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
|
||||
|
||||
### 成段注释
|
||||
|
||||
- 以**空行**划分段落。
|
||||
- 段首行:首字符非标记 → 注释。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
|
||||
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
|
||||
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
|
||||
|
||||
---
|
||||
|
||||
## 语句 vs 返回 vs 输出
|
||||
|
||||
| 标记/形式 | 角色 | 是否架构级 |
|
||||
|-----------|------|------------|
|
||||
| `*…*` | 程序语句 | 是 |
|
||||
| `**…**` | 返回值 | 是 |
|
||||
| `****` / 空粗体 | 空返回 + 结束函数体 | 是 |
|
||||
| `> print …` | 打印副作用 | 否(内置函数) |
|
||||
| 函数体 `---` / `***` | 结束函数体 | 是(边界) |
|
||||
@@ -0,0 +1,175 @@
|
||||
# Marqdo 实现依赖说明(Rust 参考解释器)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [ADR 0001](../adr/0001-implementation-language.md) · [interpreter 路线图](../roadmap/interpreter.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 要不要 Flex / Bison?
|
||||
|
||||
### 结论:**不需要。** 主因不是「用了 Rust」,而是 **Marqdo 的语法形态 + 解释器并不绑定生成器。**
|
||||
|
||||
把两件事分开:
|
||||
|
||||
| 问题 | 答案 |
|
||||
|------|------|
|
||||
| 因为 Rust 才不用 Flex/Bison? | **否。** Flex/Bison 生成的是 C(也可接 C++)。若实现改成 **C++**,**仍然不建议**用它们做 Marqdo 主前端。 |
|
||||
| 因为是解释器才不用? | **部分相关,但不是全部。** 解释器**需要**词法/语法阶段,但**不规定**必须用 Flex/Bison;手写递归下降是主流。即便将来做「编译到字节码/原生」,Marqdo 也因 Markdown 外壳而不适合整语言 Bison 化。 |
|
||||
| 真正主因 | **Markup-as-Syntax**:源是 GFM 文档结构(标题/列表/强调/表格/行分类),不是 Cminusf 那种纯字符流文法。 |
|
||||
|
||||
| 工具 | 典型用途 | Marqdo 为何不用(与宿主语言无关) |
|
||||
|------|----------|----------------------------------|
|
||||
| **Flex** | 正则 → C 词法分析器 | 「词法」是 **行分类 + Markdown 标记**,不是经典 `id\|num\|op` 字符流 |
|
||||
| **Bison** | Yacc 文法 → C LR 分析器 | 整体语法绑在 **GFM 块结构**上,硬写成单一 Bison 文法别扭且难与预览器对齐 |
|
||||
|
||||
[USTC 编译课 Lab1](https://ustc-compiler-2025.github.io/homepage/) 用 Flex/Bison,是因为对象语言是 **C 式源码的编译器**;换 C++ 写那个编译器也合理。
|
||||
Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这一判断。
|
||||
|
||||
**解释型语言同样需要词法与语法分析**,要的是阶段,不是这两个具体程序。
|
||||
|
||||
---
|
||||
|
||||
## 2. Marqdo 前端应怎样做(替代 Flex/Bison)
|
||||
|
||||
拆成三层,比「一个大 lexer/parser」更贴合宪法:
|
||||
|
||||
```
|
||||
.mq.md 文本
|
||||
│
|
||||
├─① 行分类(自研) 无标记 → 注释;有标记 → 代码行
|
||||
├─② GFM 块/行内(库) 标题、表、强调、列表结构
|
||||
├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `> file.mq.md`
|
||||
└─④ Marqdo 语法(自研) 递归下降:Module/Fun/Stmt/Expr → AST
|
||||
└─ 表达式子语言 可手写,或仅对 Expr 用 pest/nom
|
||||
```
|
||||
|
||||
| 阶段 | 做法 | 对应编译学 |
|
||||
|------|------|------------|
|
||||
| ①③ | Rust 手写扫描 | 词法 / 扫描器 |
|
||||
| ② | `pulldown-cmark` 或 `comrak` | 复用 GFM,避免自研表格/强调 |
|
||||
| ④ | **手写递归下降**(推荐主路径) | 语法分析 |
|
||||
| Expr(可选) | `pest`(PEG)或 `nom`(组合子) | 仅迷你表达式,不是整门语言 |
|
||||
|
||||
**不推荐**整门语言上 LALRPOP / rusty_lr / Bison 等价物作为 v1 主前端:Markdown 外壳 + 行语义会让文法极度别扭。若将来有「纯文本 Marqdo 方言」,再另议生成器。
|
||||
|
||||
---
|
||||
|
||||
## 3. 详细依赖清单(Rust)
|
||||
|
||||
### 3.1 工具链(开发机)
|
||||
|
||||
| 依赖 | 用途 | 安装 |
|
||||
|------|------|------|
|
||||
| **Rust**(stable,建议 ≥ 1.75) | 编译实现 | [rustup](https://rustup.rs/):`rustup default stable` |
|
||||
| **Cargo** | 包与构建 | 随 rustup |
|
||||
| **rustfmt / clippy** | 格式与静态检查 | `rustup component add rustfmt clippy` |
|
||||
| **Git** | 版本管理 | 已有 |
|
||||
|
||||
**不要安装:** Flex、Bison、LLVM(v1 解释器不需要)。
|
||||
(日后若做原生后端再开 ADR;与当前解释器无关。)
|
||||
|
||||
### 3.2 Cargo crate(建议写入根 `Cargo.toml` / workspace)
|
||||
|
||||
#### 必选(Phase I 树遍历解释器)
|
||||
|
||||
| Crate | 角色 | 说明 |
|
||||
|-------|------|------|
|
||||
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
| Crate | 角色 |
|
||||
|-------|------|
|
||||
| **camino** 或标准 `PathBuf` | 路径 |
|
||||
| **indexmap** | 保序 map(模块导出等) |
|
||||
|
||||
#### 测试
|
||||
|
||||
| Crate | 角色 |
|
||||
|-------|------|
|
||||
| **rust 自带** `#[test]` | 单元测试 |
|
||||
| **insta** 或手写金文件 | tests 期望 stdout 快照(可选) |
|
||||
| **assert_cmd** / **predicates** | CLI 集成测试(可选) |
|
||||
|
||||
#### Phase II(字节码 VM,后加)
|
||||
|
||||
无强制新依赖;VM 以自研为主。可选:
|
||||
|
||||
| Crate | 角色 |
|
||||
|-------|------|
|
||||
| **num_enum** 等 | opcode 枚举(可选) |
|
||||
|
||||
#### 明确不引入(v1)
|
||||
|
||||
| 东西 | 原因 |
|
||||
|------|------|
|
||||
| flex / bison / lemon | 见 §1 |
|
||||
| lalrpop / rusty_lr 作**整语言**前端 | 与 MD 外壳冲突;递归下降更合适 |
|
||||
| llvm-sys / inkwell | 非解释器 v1 |
|
||||
| 完整 Python 运行时嵌入 | 参考实现已定为 Rust,避免双运行时 |
|
||||
|
||||
### 3.3 表达式子语言(可选增强)
|
||||
|
||||
若手写 Expr 递归下降过痛,**仅**对 `` `a` + 1 == `b` `` 这类表达式引入其一:
|
||||
|
||||
| 选项 | 类型 | 何时用 |
|
||||
|------|------|--------|
|
||||
| **手写递归下降** | 无新依赖 | 默认;与全书一致、错误信息最好控 |
|
||||
| **pest** | PEG 生成器 | 文法清晰、想要 `.pest` 文件时 |
|
||||
| **nom** | 解析组合子 | 要零拷贝/细控时 |
|
||||
|
||||
整文件 `.mq.md` **不要**整份丢给 pest/nom。
|
||||
|
||||
---
|
||||
|
||||
## 4. 仓库布局(与依赖对应)
|
||||
|
||||
```
|
||||
Cargo.toml # workspace 或单包
|
||||
crates/marqdo/ # 或根包 marqdo
|
||||
src/
|
||||
main.rs / lib.rs
|
||||
lex/ # 行分类、Token(自研,无 flex)
|
||||
parse/ # 递归下降(自研,无 bison)
|
||||
ast/
|
||||
sema/
|
||||
interp/ # Phase I
|
||||
bytecode/ # Phase II
|
||||
runtime/
|
||||
tests/ # gold.rs + structure|keywords|errors
|
||||
public/ # 用户可执行文档
|
||||
spike/ # Python 风险探测存档(可保留,非运行时依赖)
|
||||
```
|
||||
|
||||
开发命令示例:
|
||||
|
||||
```bash
|
||||
cargo build
|
||||
cargo test
|
||||
cargo run -- run tests/structure/nested-call.mq.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 与 Python Spike 的关系
|
||||
|
||||
| | Python `spike/` | Rust 参考实现 |
|
||||
|--|-----------------|---------------|
|
||||
| 角色 | 已验证 S1–S5 风险 | **正式**词法/语法/语义/解释器 |
|
||||
| 是否运行时依赖 | 否 | 是 |
|
||||
| 算法可迁移 | 行扫描、`split_front_matter`、导入正则 | 用 Rust 重写同算法 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话对照
|
||||
|
||||
- **需要:** 词法(行分类+标记)、语法(递归下降→AST)、语义、解释器/日后 VM。
|
||||
- **不需要:** Flex、Bison、LLVM(v1)。
|
||||
- **外部库只需:** Rust 工具链 + GFM crate(pulldown-cmark/comrak)+ CLI/错误/测试若干;表达式可选 pest/nom。
|
||||
@@ -0,0 +1,76 @@
|
||||
# 示例与测试布局
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 原则 | **夹具即金样例**:`tests/{structure,keywords,errors}/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view tests` 也可浏览 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目录
|
||||
|
||||
只保留 **`tests/`**,用子目录区分类别(不再另设 `examples/`):
|
||||
|
||||
```
|
||||
tests/
|
||||
README.md
|
||||
gold.rs # 集成测试入口
|
||||
structure/ # 代码基础结构(Markup 架构)
|
||||
hello.mq.md
|
||||
nested-call.mq.md
|
||||
positional-call.mq.md
|
||||
branch.mq.md
|
||||
loop.mq.md
|
||||
collection.mq.md
|
||||
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
|
||||
…
|
||||
```
|
||||
|
||||
面向访客的可执行介绍在 [`public/`](../../public/)(无 `errors/`),见 [user-site.md](user-site.md)。
|
||||
开发设计文稿在 [`doc/`](../)(单数)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分类职责
|
||||
|
||||
| 类别 | 测什么 | 不测什么 |
|
||||
|------|--------|----------|
|
||||
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、点号路径 / `use`、位置/具名实参 | 关键字边角 |
|
||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
||||
|
||||
未单独建夹、但应覆盖的其它测试(`src/**` 单测或日后 `tests/runtime/`):
|
||||
|
||||
- **流水线调试**:`--dump-lines` / `--dump-ast` / `--trace-eval`
|
||||
- **CLI**:默认 `index.mq.md`、退出码
|
||||
- **view**:目录扫描、单文件页、执行区(见 [view.md](view.md))
|
||||
- **模块图**:循环导入拒绝;`errors/ns-instance-method`(实例方法路径)
|
||||
- **ext live**:`ext/agent-run-live`(需 `.env` + `libagent`)
|
||||
|
||||
---
|
||||
|
||||
## 3. 金样例约定
|
||||
|
||||
每个可执行 `.mq.md` 在 `tests/gold.rs` 登记期望 stdout。
|
||||
`errors/` 内文件登记期望 stderr 子串与非零退出码。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 `view` / `public` 的关系
|
||||
|
||||
- `marqdo view tests`:开发者浏览金样例(含 errors)。
|
||||
- `marqdo view public`:用户文档站源;**不要**把 `tests/errors` 编进 `public/`。
|
||||
@@ -0,0 +1,105 @@
|
||||
# Native plugin ABI (v2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted |
|
||||
| Date | 2026-08-07 |
|
||||
| Header | [`include/marqdo_abi.h`](../../include/marqdo_abi.h) |
|
||||
| Related | [ext-agent.md](ext-agent.md) · [stdlib-modules.md](stdlib-modules.md) |
|
||||
|
||||
## Goals
|
||||
|
||||
- Optional **native** extensions as shared libraries (`.dll` / `.so` / `.dylib`).
|
||||
- **Not** linked into the `marqdo` binary; load at runtime.
|
||||
- Stable **C** ABI only (no cross-compiler Rust ABI for plugins).
|
||||
- Official / local paths only — **no** third-party package registry.
|
||||
- **v2**: allowlisted `host_query` so plugins can read entry source / call site / skill without baking agent logic into the core.
|
||||
|
||||
## Contract
|
||||
|
||||
`MARQDO_ABI_VERSION = 2` (host accepts plugins with version `1..=2`).
|
||||
|
||||
Every plugin exports:
|
||||
|
||||
| Symbol | Role |
|
||||
|--------|------|
|
||||
| `marqdo_plugin_abi_version` | `1` or `2` |
|
||||
| `marqdo_plugin_init` | Register functions via `MarqdoHostApi` |
|
||||
| `marqdo_plugin_shutdown` | Teardown |
|
||||
|
||||
Host provides `register_fn`, `alloc`, `free`, and (v2) `host_query`.
|
||||
|
||||
### Wire format
|
||||
|
||||
Arguments and results are **UTF-8 JSON**:
|
||||
|
||||
- Args: JSON object keyed by parameter names (from `params` CSV at registration).
|
||||
- Result: any JSON value mappable to Marqdo `Value` (same rules as `lib/json`).
|
||||
|
||||
Plugin fn returns `0` + `*out_json` on success; non-zero + optional `*err_msg` on failure. Host frees both strings with the host `free`.
|
||||
|
||||
### `host_query` allowlist (v2)
|
||||
|
||||
| name | Result JSON | Notes |
|
||||
|------|-------------|--------|
|
||||
| `module_source` | string | Entry `.mq.md` text |
|
||||
| `call_site` | `{path,function,line}` | Active call site |
|
||||
| `marqdo_skill` | string | Skill pack text |
|
||||
| `cwd` | string | Host `cwd` (entry file directory) for path resolution |
|
||||
| `record_plot` | `{ok:true}` | Args `{svg}` + optional `path`; push SVG into host plots (view embed / CLI auto-write), same channel as math plots |
|
||||
|
||||
Unknown names fail. Queries are only valid during a plugin function call (host sets thread-local context).
|
||||
|
||||
## Marqdo surface (`lib/plugin` / `lib/插件`)
|
||||
|
||||
| English | Chinese | Host |
|
||||
|---------|---------|------|
|
||||
| `## load` (`path`) | `## 加载` (`路径`) | `host_plugin_load` |
|
||||
| `## unload` | `## 卸载` | `host_plugin_unload` |
|
||||
| `## list` | `## 列出` | `host_plugin_list` |
|
||||
| `## native_path` (`name`) | `## 原生路径` (`名`) | `host_ext_native_path` |
|
||||
|
||||
```markdown
|
||||
---
|
||||
> 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)。
|
||||
@@ -0,0 +1,163 @@
|
||||
# 设计草案:机器生成的 YAML 清单(OKF 风格)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 草案(已采纳方向;修正「配置文件」误解) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) · **实现规范 [okf.md](okf.md)** |
|
||||
| 取代 | 此前「YAML = 人手写的编译器配置 / frontmatter 契约」的表述 |
|
||||
| 说明 | 原则仍有效;**类型表、任务知识包、路线图以 [okf.md](okf.md) 为准** |
|
||||
---
|
||||
|
||||
## 决策
|
||||
|
||||
Marqdo 项目中的 **YAML(及由其组成的 OKF 风格知识包)是工具自动生成的产物,不是给人填的配置文件。**
|
||||
|
||||
它的角色接近其它语言里由工具维护的**依赖与包元数据**,例如:
|
||||
|
||||
| 生态 | 类比(职责相近,不是语法相同) |
|
||||
|------|--------------------------------|
|
||||
| Rust | `Cargo.toml` / 解析后的依赖图(由源与清单共同推导,工具可改写) |
|
||||
| Python | `requirements.txt`(常由解析/冻结生成) |
|
||||
| Go | `go.mod` + `go.sum`(`go mod tidy` 维护) |
|
||||
|
||||
我们选择 **OKF 的形态**(Markdown + YAML frontmatter 的概念目录)来承载这份生成结果,从而一举两得:
|
||||
|
||||
1. **给编译器 / 包管理**:依赖图、模块身份、导出符号、版本锁定等可查询元数据
|
||||
2. **给本项目文档**:同一份生成物可直接渲染为「项目知识目录」——模块说明、依赖关系、API 索引等**自动生成本项目文档内容**
|
||||
|
||||
**唯一手写真相**仍是 `.mq.md` 源文件正文。YAML 清单是派生工件;过时则重新生成,禁止当成第二套权威配置去手改(除非工具链明确支持的「生成后微调」流程,且须可复现)。
|
||||
|
||||
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `> other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
|
||||
|
||||
---
|
||||
|
||||
## 纠正:它不是什么
|
||||
|
||||
| ❌ 不是 | ✅ 是 |
|
||||
|--------|------|
|
||||
| 人手维护的 `run` / `target` / 路径配置 | 从源码 **推导** 出的依赖与模块元数据 |
|
||||
| 编译器「怎么跑」的 ini/配置替代品 | 解析、链接、文档站共用的 **生成清单** |
|
||||
| 与正文平行的第二套程序描述 | 正文的 **投影**(projection):结构化、可查询、可渲染 |
|
||||
|
||||
执行方式(解释 / 检查 / 编译到某后端)由 **CLI、子命令或工程约定** 决定,不塞进这份 YAML 让人配置。
|
||||
|
||||
---
|
||||
|
||||
## 数据流
|
||||
|
||||
```
|
||||
手写 .mq.md 源
|
||||
(叙事 + 类型 + 函数 + 正文中的引用/导入)
|
||||
│
|
||||
▼
|
||||
marqdo 工具链
|
||||
· 解析正文 AST
|
||||
· 收集 import / 链接 / 导出
|
||||
· 解析依赖、锁定版本
|
||||
│
|
||||
├──────────────────────────────┐
|
||||
▼ ▼
|
||||
生成 OKF 风格清单 编译 / 类型检查 / 运行
|
||||
(YAML + 概念 Markdown) (消费清单加速解析)
|
||||
│
|
||||
▼
|
||||
自动生成本项目文档
|
||||
(模块索引、依赖图、API 目录……)
|
||||
```
|
||||
|
||||
- **源 → 清单**:单向派生;清单不得反向成为「唯一写依赖的地方」。
|
||||
- **清单 → 文档**:OKF 包本身即可浏览;也可再生成站点/目录页。
|
||||
- **清单 → 编译**:编译器可读生成结果以跳过重复发现,但语义仍以源为准;清单缺失时应能从源重建。
|
||||
|
||||
---
|
||||
|
||||
## 生成物长什么样(示意)
|
||||
|
||||
工程在构建或 `marqdo sync` 类命令后,可得到类似 OKF bundle 的目录(路径未定):
|
||||
|
||||
```
|
||||
.marqdo/ # 或 docs/catalog/ 等 — 待 ADR
|
||||
index.md # 生成:项目总览
|
||||
modules/
|
||||
cart.md # 生成:每个模块一个概念文档
|
||||
prelude-list.md
|
||||
deps/
|
||||
lock.yaml # 生成:依赖锁定(机器向)
|
||||
```
|
||||
|
||||
单个生成的概念文件可呈 OKF 形:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Marqdo Module # 生成
|
||||
title: cart
|
||||
description: 购物车:行项目与总额
|
||||
resource: src/cart.mq.md # 指向源文件
|
||||
depends:
|
||||
- prelude/list
|
||||
- math/sum
|
||||
exports: [Line, total]
|
||||
generated:
|
||||
by: "marqdo/0.1"
|
||||
at: 2026-08-04T01:00:00Z
|
||||
---
|
||||
|
||||
# cart
|
||||
|
||||
> 本页由 Marqdo 工具链根据 [`src/cart.mq.md`](../../src/cart.mq.md) **自动生成**,请勿手改。
|
||||
|
||||
## 依赖
|
||||
|
||||
- [prelude/list](../modules/prelude-list.md)
|
||||
- [math/sum](../modules/math-sum.md)
|
||||
|
||||
## 导出
|
||||
|
||||
| 符号 | 种类 |
|
||||
|------|------|
|
||||
| `Line` | type |
|
||||
| `total` | fn |
|
||||
```
|
||||
|
||||
人要改行为或说明 → 改 `src/cart.mq.md`;再生成,文档与依赖清单一起更新。
|
||||
|
||||
---
|
||||
|
||||
## 与「代码即文档」的关系
|
||||
|
||||
Marqdo 有两层「文档」,不要混为一谈:
|
||||
|
||||
| 层 | 谁写 | 是什么 |
|
||||
|----|------|--------|
|
||||
| **源文档** | 人(及协助编写的 Agent) | `.mq.md`:程序本身,打开即读、即可跑 |
|
||||
| **项目目录文档** | 机器 | OKF 风格 YAML/Markdown:从全项目源 **汇总** 的依赖、模块图、索引 |
|
||||
|
||||
前者消灭「实现与说明漂移」;后者消灭「仓库级总览靠手维护 README 目录」——总览从源自动长出,格式还对 Agent / 搜索友好(OKF)。
|
||||
|
||||
---
|
||||
|
||||
## 原则
|
||||
|
||||
1. **源为唯一权威** — 依赖与导出以 `.mq.md` 正文中的语言构造为准;YAML 是提取结果。
|
||||
2. **生成、可复现** — 同一源树 + 同一工具版本 → 同一清单(允许时间戳等字段除外或规范化)。
|
||||
3. **勿手改生成物** — 生成文件应带头注释或 `generated` 字段;CI 可校验「未提交脏生成」或「提交的生成与源一致」。
|
||||
4. **OKF 形、Marqdo 义** — 文件形态对齐 OKF(`type`、链接、目录),词汇服务模块/依赖/导出,而不是照搬 BigQuery 概念类型。
|
||||
5. **清单可删可再生** — 没有清单时,编译器仍须能直接从源工作(可能更慢);清单是缓存与文档面,不是语言语义的一部分。
|
||||
|
||||
---
|
||||
|
||||
## 待决问题(后续 ADR)
|
||||
|
||||
- [x] 生成物默认路径:`.marqdo/`(`-o` 可改)— 见 [catalog-cli.md](catalog-cli.md)
|
||||
- [x] `marqdo catalog` / `sync`;静态用户文档:`marqdo view output` — 见 [view.md](view.md)
|
||||
- [ ] 是否提交生成物进 git(项目自定;CI 可校验干净生成)
|
||||
- [ ] 与「可手写包身份 name/version」的边界
|
||||
- [ ] 是否沿用 OKF v0.2 的 `sources` 等溯源字段
|
||||
|
||||
---
|
||||
|
||||
## 结论
|
||||
|
||||
**YAML(OKF 风格清单)= 机器从 `.mq.md` 自动生成的依赖与项目元数据,并可据此自动生成本项目文档;不是人手填写的配置文件。**
|
||||
人写源,工具写清单与目录文档;编译器与文档站共同消费生成物,语义始终回到源。
|
||||
@@ -0,0 +1,137 @@
|
||||
# 内置关键字 / 函数:中英双名(草案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定(已实现)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 原则 | **无需导入**;中英为**同一语义的别名**,不是语言模式开关 |
|
||||
| 相关 | [keywords.md](keywords.md) · [stdlib-i18n.md](stdlib-i18n.md) · [call-arguments.md](call-arguments.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
Marqdo 要中英文都能自然书写。标准库已约定「**库文件名区分语言**」(见 [stdlib-i18n.md](stdlib-i18n.md));对**不必导入**的一层——字面量关键字与极少内置函数——也要对等提供中文名。
|
||||
|
||||
正因为每增加一个内置名,就要同时维护中英(及日后更多语言)别名,所以:
|
||||
|
||||
> **关键字 / 内置必须少而精**——体积在「名字 × 语言」上放大,而不是在功能清单上堆满。
|
||||
|
||||
更多能力进可导入的 `lib/`,用中英**不同库文件、不同函数名**扩展,不膨胀解释器内核。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层(与标准库对齐)
|
||||
|
||||
| 层 | 是否导入 | 中英怎么区分 |
|
||||
|----|----------|--------------|
|
||||
| **L0 内核** | 否 | **同一文件内双名**:`print` ≡ `打印`;`True` ≡ `真` |
|
||||
| **L1 标准库** | 是(`> lib/…`) | **不同文件**:`text.mq.md` vs `文本.mq.md`(见 i18n 草案) |
|
||||
|
||||
L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英文,写中文名就用中文,可在同一程序里混用。
|
||||
|
||||
---
|
||||
|
||||
## 3. 范围:哪些要双名
|
||||
|
||||
### 3.1 字面量 / 逻辑关键字(词法保留)
|
||||
|
||||
控制流仍靠 Markdown(`#` `1.` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。形参用 `+`。
|
||||
|
||||
| 英文 | 中文(提案) | 备注 |
|
||||
|------|--------------|------|
|
||||
| `True` | `真` | 布尔真 |
|
||||
| `False` | `假` | 布尔假 |
|
||||
| `None` | `空` | 空值 |
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
中英文名均**不可作变量名**(同一保留集)。
|
||||
|
||||
### 3.2 内置函数(可调用、无需导入)
|
||||
|
||||
**仅**下列核心五项做中英双名(与「少而精」一致):
|
||||
|
||||
| 英文 | 中文(提案) | 作用 |
|
||||
|------|--------------|------|
|
||||
| `print` | `打印` | 写 stdout |
|
||||
| `input` | `输入` | 读一行 |
|
||||
| `len` | `长度` | 文本/表长度 |
|
||||
| `str` | `文本` | 转为显示文本 |
|
||||
| `int` | `整数` | 转为整数 |
|
||||
|
||||
形参名也提供中英别名(便于纯中文调用):
|
||||
|
||||
| 英文形参 | 中文形参 | 用于 |
|
||||
|----------|----------|------|
|
||||
| `text` | `内容` | `print` / `打印` |
|
||||
| `prompt` | `提示` | `input` / `输入` |
|
||||
| `value` | `值` | `len`/`str`/`int` 及对应中文名 |
|
||||
|
||||
示例(等价):
|
||||
|
||||
```markdown
|
||||
> print text=Hello
|
||||
> 打印 内容=你好
|
||||
|
||||
*`n` = > len `s`*
|
||||
*`n` = > 长度 值=`s`*
|
||||
```
|
||||
|
||||
### 3.3 明确不进 L0 双名表
|
||||
|
||||
下列若已在解释器中实现,视为**宿主原语 / 过渡 API**,**不**再批中文内核别名;应迁入或仅通过标准库暴露(中英分文件):
|
||||
|
||||
| 英文名 | 去向 |
|
||||
|--------|------|
|
||||
| `type` | L1 或维持实现细节,不进「关键字最少集」宣传 |
|
||||
| `trim` `split` `join` | L1:`lib/text.mq.md` / `lib/文本.mq.md` |
|
||||
| `at` | L1:`lib/table.mq.md` / `lib/表.mq.md` |
|
||||
|
||||
这样 L0 公开面 ≈ **6 个关键字词 ×2 + 5 个函数 ×2**,而不是「每个工具函数都 ×2」。
|
||||
|
||||
---
|
||||
|
||||
## 4. 语义规则
|
||||
|
||||
1. **别名等价**:中英文名绑定同一实现;诊断文案可用英文稳定串(金样例已有),用户文档中英均可举例。
|
||||
2. **可混用**:同一文件可同时出现 `print` 与 `打印`、`True` 与 `真`。
|
||||
3. **遮蔽**:用户 `# 打印` 与 `# print` 均会遮蔽对应内置名(实现阶段应警告)。
|
||||
4. **大小写**:英文关键字保持 Python 风格(`True`/`False`/`None`);中文无名感大小写问题。
|
||||
5. **扩语言**:日后日文等 → 再为 L0 增加第三个别名列;仍无「名字表」而非语言开关。标准库继续用**文件名**区分(见 i18n 草案)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与旧决议的关系
|
||||
|
||||
- 旧文「中文 `print` 废弃、统一为 `print`」:**废止**;改为正式双名 `print` / `打印`。
|
||||
- [keywords.md](keywords.md) 原则条「英文标识」改为「**内核双名;标准库分文件**」——实现阶段改正文。
|
||||
- 不引入中文控制流关键字(`如果`/`循环` 等);分支用 `1.` …,循环用 `-`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 文档与金样例义务(实现时)
|
||||
|
||||
| 项 | 要求 |
|
||||
|----|------|
|
||||
| `keywords.md` | L0 表改为中英并列;砍掉对 `trim`/`split`/… 的「内核关键字」宣传 |
|
||||
| `public/` | 英 / 中文件同目录并列(拉丁名 vs 中文名) |
|
||||
| `tests/` | 中文关键字 / `打印`·`长度` 等金样例;与英文样例对等 |
|
||||
| 诊断 | 位置格式不变;message 可暂维持英文,或中英均可接受(另开小节) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 实现备忘(暂不开发)
|
||||
|
||||
1. 词法 / 解析:字面量与 `and`/`or`/`not` 识别中文别名。
|
||||
2. 调用解析:内置表按别名归一到同一 `BuiltinId`。
|
||||
3. 形参绑定:`text`≡`内容`,`prompt`≡`提示`,`value`≡`值`。
|
||||
4. **不要**加 `lang:` 或全局「中文模式」。
|
||||
5. 与 [stdlib-i18n.md](stdlib-i18n.md) 一并落地时:先收束 L0 公开面,再铺 `lib/text` ↔ `lib/文本`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 一句话
|
||||
|
||||
**内核:中英别名、无需导入、必须少;标准库:中英分文件、靠导入路径选择——这样 Marqdo 才能中英文通用而不把解释器撑爆。**
|
||||
@@ -0,0 +1,97 @@
|
||||
# Marqdo 关键字与内置名(v0 最小集)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(中英双名) |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 原则 | **少而精**;控制流靠 Markdown;内核中英**别名等价**(见 [keywords-i18n.md](keywords-i18n.md)) |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords-i18n.md](keywords-i18n.md) · [stdlib-i18n.md](stdlib-i18n.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计原则
|
||||
|
||||
1. **标记承担架构**:函数=`#`,**形参=`+`**,**分支=`1.`…**,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
2. **内核双名**:字面量 / 逻辑词 / 五个核心内置函数均有中英别名,**无需导入**,可混用。
|
||||
3. **学 Python 的边界**:区分 **关键字** vs **内置函数名**。
|
||||
4. **宁少勿多**:扩展能力进可导入标准库(中英分文件,见 [stdlib-i18n.md](stdlib-i18n.md))。
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键字(词法保留,不可作变量名)
|
||||
|
||||
| 英文 | 中文 | 含义 |
|
||||
|------|------|------|
|
||||
| `True` | `真` | 布尔真 |
|
||||
| `False` | `假` | 布尔假 |
|
||||
| `None` | `空` | 空值 |
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
**不引入:** `if` `else` `while` `for` `def` `return` …(分支臂 `*` 不是单词 `else`。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 内置函数(可调用,无需导入)
|
||||
|
||||
| 英文 | 中文 | 作用 |
|
||||
|------|------|------|
|
||||
| `print` | `打印` | 写 stdout |
|
||||
| `input` | `输入` | 读一行;capture / view 用 frontmatter `stdin:` / `输入:`、表单或 `--stdin-file` 预置 |
|
||||
| `len` | `长度` | 文本/表长度 |
|
||||
| `str` | `文本` | 转为显示文本 |
|
||||
| `int` | `整数` | 转为整数 |
|
||||
|
||||
**文本**:裸 token 按字面量;需 `\n` 等转义时用 `"..."`(见 [markdown-mapping.md](markdown-mapping.md) §7)。
|
||||
|
||||
形参别名:
|
||||
|
||||
| 英文 | 中文 | 用于 |
|
||||
|------|------|------|
|
||||
| `text` | `内容` | `print` / `打印` |
|
||||
| `prompt` | `提示` | `input` / `输入` |
|
||||
| `value` | `值` | `len`/`str`/`int` 及其中文名 |
|
||||
|
||||
```markdown
|
||||
> print text=Hello
|
||||
> 打印 内容=你好
|
||||
|
||||
*`n` = > 长度 值=`s`*
|
||||
```
|
||||
|
||||
宿主原语 `type` / `trim` / `split` / `join` / `at` **无**内核中文别名;文本/表扩展走标准库文件(见 [stdlib-i18n.md](stdlib-i18n.md))。转换错误见 [stdlib.md](stdlib.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 Markup 调用的关系
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=Hello World!
|
||||
|
||||
*`n` = 1*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. *
|
||||
> 打印 内容=other
|
||||
```
|
||||
|
||||
- `>` 是调用标记;`print` / `打印` 是同一内置的别名。
|
||||
- 用户 `# print` 或 `# 打印` 会遮蔽对应名字。
|
||||
|
||||
---
|
||||
|
||||
## 5. 标识符规则(摘要)
|
||||
|
||||
- 变量:`` `name` ``;不可为上表任一中英文关键字。
|
||||
- 函数名:`#` 标题;中英文均可。
|
||||
- 比较:`==` `>` `<` `>=` `<=`;逻辑:`and`/`且`、`or`/`或`、`not`/`非`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 后续可增(未批准)
|
||||
|
||||
`float`、`range`;以及 `break`/`continue`。增加前开短 ADR,并同步考虑是否值得占用双名配额。
|
||||
@@ -0,0 +1,351 @@
|
||||
# Marqdo 语法映射 v0.2(Markup-as-Syntax)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定论(修订:形参 `+`、分支 `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))。
|
||||
|
||||
---
|
||||
|
||||
## 1. 哲学
|
||||
|
||||
1. `.mq.md`:打开即文档,运行即程序。
|
||||
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
5. **标识符默认反引号**:形参、绑定、引用写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
|
||||
**豁免:**
|
||||
- foreach 头 `` - [项](集合) `` 允许裸名或反引号(可混用),推荐裸名;循环体内引用仍用 `` `名` ``。
|
||||
- 脚注取元 `` 名[^键] ``:基名在紧跟 `` [^…] `` 时可省略反引号(`` `名`[^键] `` 仍合法);链式同理。
|
||||
- **斜体语句 / 粗体返回内部**:裸标识符默认是**变量**;字符串须 `"…"` 或 `'…'`;`` `名` `` 仍合法。
|
||||
|
||||
---
|
||||
|
||||
## 2. 行首判别与成段注释
|
||||
|
||||
跳过前导空白后,对**段首行**(空行之后的第一行,或文件起始):
|
||||
|
||||
| 首字符 | 分类 |
|
||||
|--------|------|
|
||||
| 普通文字 / 空 | **注释** |
|
||||
| 标记字符 | **代码** |
|
||||
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
|
||||
|
||||
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
|
||||
|
||||
---
|
||||
|
||||
## 3. 映射总表(v0.2)
|
||||
|
||||
| 标记 | 语义 |
|
||||
|------|------|
|
||||
| `#` … `######` | **`#` = 对象/类型**(可 `# Child = > Parent`);**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
|
||||
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
|
||||
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
|
||||
| 体内 `-` | **循环**(`while` 条件,或 `[项](集合)` / `` [`项`](`集合`) `` 遍历) |
|
||||
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
|
||||
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
|
||||
| `` > `对象`.方法 … `` | 方法调用(实例 map 须含 `_type`) |
|
||||
| frontmatter `> path.mq.md` [`as` / `作为` name] | 导入(绑定库名;默认 = 文件名茎) |
|
||||
| frontmatter `> use lib.member` [`as` name] / `使用` | 将库路径成员绑为本地短名 |
|
||||
| `> lib.member …` / `> lib.Type.member …` | 点号路径调用(路径段裸名、无反引号) |
|
||||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
||||
| `**…**` | **返回值**(架构级;函数结果) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| 无标记行 / 成段续行 | 注释(空行分段,见 §2) |
|
||||
| GFM 表格 | 集合 |
|
||||
| 空 RHS 赋值 + 后随 `$$…$$`(或同行 `$$…$$`) | **公式赋值** → 运行时 `formula`(见 [stdlib-math.md](stdlib-math.md));叙述面无名 `$$` 仅展示 |
|
||||
| ` ```lang ` | 外联异种代码 |
|
||||
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) |
|
||||
|
||||
### `+` / `-` / `1.` 消歧
|
||||
|
||||
| 位置 | `+` | `1.` … | `-` |
|
||||
|------|-----|--------|-----|
|
||||
| 函数标题后、**首条体语句前** | 形参:`` + `名` `` / `` + `名`=默认 `` | (非法) | (非法作形参) |
|
||||
| 函数体内 | (非法作分支) | 分支臂:`1. `条件`` / `2. *` | 循环 |
|
||||
|
||||
**分支从未使用 `+`。** 自 v0 起即采用 GFM 有序列表;`+` 在 v0.2 专用于形参,与 `-` 循环彻底分离。
|
||||
|
||||
### 输出不是架构
|
||||
|
||||
| 错误(旧) | 正确(v0.2) |
|
||||
|------------|--------------|
|
||||
| `**Hello**` 表示打印 | `> print text=Hello` |
|
||||
| `+ `x` > 0` 作分支 | `1. `x` > 0` |
|
||||
| `- 谁` 作形参 | `` + `谁` `` |
|
||||
| `[果](篮子)` 裸名遍历 | **仍合法**(foreach 豁免);亦可用 `` [`果`](`篮子`) `` |
|
||||
|
||||
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 语句、返回、调用
|
||||
|
||||
### 程序语句(斜体)
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
*answer = ev[^message]*
|
||||
*`亦可用` = 1*
|
||||
```
|
||||
|
||||
斜体内部:裸标识符 = 变量;字符串写 `"…"` / `'…'`。行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
|
||||
### 返回值(粗体)
|
||||
|
||||
```markdown
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
**"ok"**
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
粗体内部与斜体相同的值语法(裸词 = 变量;文本须引号)。
|
||||
|
||||
### 输出(内置函数 `print`)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
### else 与斜体消歧
|
||||
|
||||
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
|
||||
- `*中间有内容*` → 程序语句。
|
||||
- `**…**` → 返回(与 else 无关)。
|
||||
|
||||
---
|
||||
|
||||
## 5. Frontmatter 与跨文件
|
||||
|
||||
文件头 `---` 对为元信息。其中 `> file.mq.md` 为**导入**(绑定库名,成员不倒进全局);`> use lib.member` / `> 使用 库.成员` 引入本地短名。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法须 `` > `var`.method ``。详见 [module-namespace.md](module-namespace.md)。
|
||||
|
||||
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 对象、函数、形参
|
||||
|
||||
- `# Name`:对象(构造体);`# main` 为入口对象。
|
||||
- `# Child = > Parent`:单继承(基类须为已定义对象名;方法沿链查找,子类可覆盖)。见 [objects.md](objects.md) §5。
|
||||
- `##` / `###` …:函数或方法;挂在对象下则为方法。
|
||||
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
|
||||
## 加问候
|
||||
+ `谁`
|
||||
|
||||
**你好,`谁`**
|
||||
```
|
||||
|
||||
可选形参:
|
||||
|
||||
```markdown
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
```
|
||||
|
||||
方法体内自动绑定 `` `自` `` / `` `self` ``。
|
||||
|
||||
---
|
||||
|
||||
## 7. 绑定、比较与字符串
|
||||
|
||||
| 写法 | 含义 |
|
||||
|------|------|
|
||||
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定 |
|
||||
| `` `x` == 1 `` | 相等比较 |
|
||||
| `"text"` | **双引号字符串**(复杂文本;见下) |
|
||||
| `hello` / `路径` | **裸 token**(无转义,按字面量) |
|
||||
|
||||
### 双引号字符串(复杂文本)
|
||||
|
||||
需要转义或嵌入变量时用 `"..."`;**裸 token 不转义**,保持文档简洁:
|
||||
|
||||
```markdown
|
||||
> input prompt="你叫什么名字\n"
|
||||
*`msg` = "Hello, `name`!\n"*
|
||||
```
|
||||
|
||||
| 转义 | 含义 |
|
||||
|------|------|
|
||||
| `\n` | 换行 |
|
||||
| `\t` | 制表 |
|
||||
| `\r` | 回车 |
|
||||
| `\\` | `\` |
|
||||
| `\"` | `"` |
|
||||
|
||||
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分支与循环
|
||||
|
||||
分支(**有序列表** `1.` `2.` …),循环(`-`):
|
||||
|
||||
```markdown
|
||||
*`x` = 0*
|
||||
|
||||
1. `x` > 0
|
||||
> print text=正数
|
||||
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. 集合(表格)
|
||||
|
||||
`` `名` = `` 后接 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` 遍历**键**(值用脚注取)。
|
||||
|
||||
---
|
||||
|
||||
## 10. 求值入口
|
||||
|
||||
1. 加载 `index.mq.md` + 导入。
|
||||
2. Pass1 收集定义。
|
||||
3. Pass2 执行 `# main`。
|
||||
4. `*` 语句、`**` 返回、`>` 调用、`1.` 分支、`-` 循环、表绑定按语义执行;`> print` 写 stdout。
|
||||
|
||||
---
|
||||
|
||||
## 11. 函数体结束(`---` / `***` / 空返回)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** |
|
||||
| `****` / 空粗体 | 空返回(`None`),并结束本函数体 |
|
||||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息 |
|
||||
|
||||
---
|
||||
|
||||
## 12. v0.2 非目标
|
||||
|
||||
- break/continue、完整错误模型、静态类型、完整 FFI
|
||||
- `+` 作分支、`+`/`-` 作形参(**不保留**)
|
||||
|
||||
---
|
||||
|
||||
## 13. 示例索引
|
||||
|
||||
见 [`tests/`](../../tests/)。
|
||||
@@ -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 分管工程目录与自我成长。**
|
||||
@@ -0,0 +1,75 @@
|
||||
# 解释器流水线可视调试
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(开发期强制友好) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 参考 | [Crafting Interpreters — Scanning](https://www.craftinginterpreters.com/scanning.html)(先打 token)· [AstPrinter](https://craftinginterpreters.com/representing-code.html) · CLI `--dump-ast` 类实践 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
开发 `marqdo` 时,对任意 `.mq.md` 应能**分阶段看见**中间结果,避免黑盒;正式 `run` 默认安静,仅输出程序 `print` 的内容。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI 开关
|
||||
|
||||
```bash
|
||||
marqdo run FILE [dumps...]
|
||||
marqdo dump FILE --stage lines|tokens|ast|sema|all
|
||||
```
|
||||
|
||||
| 标志 | 阶段 | 输出内容 |
|
||||
|------|------|----------|
|
||||
| `--dump-lines` | 行分类 | 每行:`LINE kind=Comment\|Code\|Blank` + 原文预览 |
|
||||
| `--dump-tokens` | 词法 | Token 流:`type lexeme line:col` |
|
||||
| `--dump-ast` | 语法 | S 表达式或缩进树(模块/函数/语句) |
|
||||
| `--dump-sema` | 语义 | 作用域、导入图、提升后的符号表 |
|
||||
| `--trace-eval` | 求值 | **JSON 行**(stderr):语句级事件,含 `path` / `span`(`line:col`) |
|
||||
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(指令旁带 `@line:col`;见 [bytecode.md](bytecode.md)) |
|
||||
| `--backend tree\|bytecode` | 执行后端 | 默认 `tree`;`bytecode` 走栈式 VM |
|
||||
| `--dump-all` | 以上全部 | 按管道顺序打印,段之间用横幅分隔 |
|
||||
|
||||
格式约定:
|
||||
|
||||
- dump 人类可读优先;段首统一:`=== marqdo: <stage> ===`
|
||||
- `--trace-eval`:每条事件一行 JSON,例如
|
||||
`{"event":"stmt","path":"…","span":"5:1","kind":"call","callee":"print"}`
|
||||
树遍历:`enter_fn` / `stmt` / `leave_fn`;字节码:`op`(`print`/`input`/`call`/`return`)。
|
||||
- 有 dump 时:若求值未实现,仍打印已实现阶段再以非 0 退出(便于 M1 只测 lines)
|
||||
|
||||
---
|
||||
|
||||
## 3. 横幅示例
|
||||
|
||||
```
|
||||
=== marqdo: lines (tests/structure/hello.mq.md) ===
|
||||
1 Blank
|
||||
2 Comment | # Hello World
|
||||
3 Blank
|
||||
4 Comment | 本程序调用...
|
||||
5 Blank
|
||||
6 Code | > print text=Hello World!
|
||||
=== marqdo: end lines ===
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 实现要点
|
||||
|
||||
- dump 逻辑放在 `src/debug/`(或各阶段 `fmt`),**不**与安静求值路径搅在一起。
|
||||
- 每个阶段纯函数:`input → (artifacts, diagnostics)`,CLI 负责打印。
|
||||
- 单测可断言 dump 字符串包含关键行(稳定子集),避免绑死全文格式。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与里程碑
|
||||
|
||||
| 里程碑 | 必须可用的 dump |
|
||||
|--------|-----------------|
|
||||
| M1 | `--dump-lines`(及可选 tokens 雏形) |
|
||||
| M2 | `--dump-ast` |
|
||||
| M3–M4 | `--dump-sema`、`--trace-eval` |
|
||||
| 全程 | `--dump-all` 随阶段增长自动变完整 |
|
||||
@@ -0,0 +1,19 @@
|
||||
# 记录:返回 / 语句 / 输出 / 分割线(决议)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已决议(并入 mapping v0.1 + keywords;2026-08-04 修订函数收束) |
|
||||
| 日期 | 2026-08-04 |
|
||||
|
||||
---
|
||||
|
||||
## 决议
|
||||
|
||||
1. **`*…*` = 程序语句**。
|
||||
2. **`**…**` = 返回值**(架构级);空粗体 `****` / `** **` = 空返回(`None`)并结束函数体。
|
||||
3. **输出**用内置函数 **`print`**(英文),不是粗体,不是中文名。
|
||||
4. **`---` / `***`(函数体顶层)**:结束本函数体(无返回值函数收束);**不是**分支/循环装饰框。
|
||||
5. **成段注释**:空行分段;段内续行不因首字符升级为代码。
|
||||
6. **否决**:无标记行 = 默认代码。
|
||||
|
||||
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)、[code-vs-comment.md](code-vs-comment.md)。
|
||||
@@ -0,0 +1,49 @@
|
||||
# 外联 / 胶水标准库
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(v1)** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原则
|
||||
|
||||
**导入即用**:`lib/foreign` / `lib/外联`。解释器来自用户本机(PATH / `set_cmd` / `MARQDO_FOREIGN_*`)。live view 可点 Run;静态导出展示源码,Run 禁用。
|
||||
|
||||
---
|
||||
|
||||
## 2. 绑定语法(与公式同构)
|
||||
|
||||
```markdown
|
||||
`hi` =
|
||||
```python
|
||||
print("hello")
|
||||
```
|
||||
|
||||
*`out` = > run code=`hi` *
|
||||
```
|
||||
|
||||
得到运行时类型 **`code`**(`lang` + `source`)。未绑定的 \`\`\` 围栏仍是叙述注释。
|
||||
|
||||
曾用的 \`\`\`python name=hi **已移除**。
|
||||
|
||||
---
|
||||
|
||||
## 3. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `set_cmd` | `设置命令` | `lang`, `cmd` | None |
|
||||
| `run` | `运行` | `code`(code 值) | 文本 stdout |
|
||||
| `run_lang` | `按语言运行` | `lang`, `source` | 文本 |
|
||||
| `langs` | `语言表` | | 列表 |
|
||||
|
||||
live view:Structure 中 code 卡片带命令框 + Run → `POST /api/foreign-run`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 一句话
|
||||
|
||||
**`name` = + \`\`\`lang 围栏 → code 值;显式 run;本机解释器可配置。**
|
||||
@@ -0,0 +1,146 @@
|
||||
# 标准库多语言命名(草案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **草案(先文档、后实现)** |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 原则 | **不指定语言**;靠**库文件名**区分中英(及日后其它语言) |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [keywords.md](keywords.md) · [keywords-i18n.md](keywords-i18n.md) · [user-site.md](user-site.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 要解决什么
|
||||
|
||||
- 内置(解释器里的名字)必须**少而精**;更多能力放进可 `>` 导入的标准库。
|
||||
- 标准库需要**中英两套 API**(函数名不同),并方便以后再加日文、西班牙文等。
|
||||
- **不要**用 frontmatter `lang:`、环境变量默认语言、或「同一导入路径再解析语言」——那是负累,也不符合「文档即代码」的直观性。
|
||||
|
||||
---
|
||||
|
||||
## 2. 方案(采用)
|
||||
|
||||
**导入哪个库文件,就用哪套函数名。**
|
||||
文件名本身表达语言;解释器只做路径解析,不做语言推断。
|
||||
|
||||
### 2.1 推荐:库名用目标语言书写
|
||||
|
||||
| 导入 | 库内函数名(示例) |
|
||||
|------|-------------------|
|
||||
| `> lib/text.mq.md` | `trim` · `split` · `join` |
|
||||
| `> lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
|
||||
| `> lib/table.mq.md` | `put` · `rows` · `row_at` · list/map(见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| `> lib/表.mq.md` | `行数` · `取行` |
|
||||
|
||||
示例:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
*`xs` = > split value=a,b,c sep=,*
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/文本.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
*`xs` = > 拆分 s=a,b,c sep=,*
|
||||
```
|
||||
|
||||
读者看到导入路径就能知道后面该用英文还是中文函数名——**无需再声明语言**。
|
||||
|
||||
### 2.2 可选:同概念用后缀区分(同目录、同「概念」)
|
||||
|
||||
若希望「同一概念」在文件名上仍共享拉丁词根,可用:
|
||||
|
||||
| 导入 | 含义 |
|
||||
|------|------|
|
||||
| `> lib/text-en.mq.md` | 英文 API |
|
||||
| `> lib/text-zh.mq.md` | 中文 API |
|
||||
|
||||
这与 §2.1 **等价可选**,不是第二套解析器:仍然是「写哪个路径就加载哪个文件」。
|
||||
**优先推荐 §2.1**(`text` / `文本`),后缀形式留给需要 ASCII-only 路径的环境。
|
||||
|
||||
### 2.3 明确不做
|
||||
|
||||
| 不做 | 原因 |
|
||||
|------|------|
|
||||
| `lang: zh` / `MARQDO_LANG` | 隐式状态,难读、难测 |
|
||||
| `> std/text` 再按语言展开 | 多一次魔法 |
|
||||
| 同一文件内中英函数双份导出 | 遮蔽与文档混乱 |
|
||||
| 强制用户只许用中文或只许用英文 | Marqdo 本就多语言友好 |
|
||||
|
||||
---
|
||||
|
||||
## 2.4 特例:JSON
|
||||
|
||||
`JSON` 为专有缩写,**不强求**中文库名或中文 API 翻译。官方只提供:
|
||||
|
||||
```text
|
||||
lib/json.mq.md # 中英文档均 `> lib/json.mq.md`;函数 parse / stringify / get / keys
|
||||
```
|
||||
|
||||
不设 `lib/数据.mq.md` 等平行文件。其余模块仍遵守 §2.1。详见 [stdlib-modules.md](stdlib-modules.md) §3.4。
|
||||
|
||||
---
|
||||
|
||||
## 3. 与「少而精内置」的边界
|
||||
|
||||
| 层 | 内容 | 如何获得 |
|
||||
|----|------|----------|
|
||||
| **内置(L0)** | 极少:`print` `input` `len` `str` `int`(及语言字面量关键字) | 直接调用,无需导入 |
|
||||
| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `> lib/…` |
|
||||
| **宿主原语(实现细节)** | 若 `trim`/`split` 等暂由解释器实现 | 仅供标准库包装调用;**文档与用户站引导走 L1**,不鼓励当「关键字」堆砌 |
|
||||
|
||||
日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。
|
||||
|
||||
---
|
||||
|
||||
## 4. 目录与扩展约定
|
||||
|
||||
```text
|
||||
lib/
|
||||
text.mq.md / 文本.mq.md
|
||||
table.mq.md / 表.mq.md
|
||||
# 本波:fs/文件 · sys/系统 · time/时间 · json(中英同文件)· net/网络
|
||||
# 暂缓:math/数学 · foreign/外联
|
||||
# 其它语言:texte.mq.md / テキスト.mq.md …
|
||||
```
|
||||
|
||||
扩展新语言时:
|
||||
|
||||
1. **新加一个库文件**(文件名用该语言或 `概念-xx`)。
|
||||
2. 库内函数名用该语言习惯。
|
||||
3. 文档表增加一行映射;**无需改解释器语言开关**。
|
||||
|
||||
导入解析仍沿用现有规则:相对路径 → 官方 `lib/` 根(`MARQDO_LIB` / 工作区 `lib/` 等),**不增加语言分支**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 文档与示例义务
|
||||
|
||||
- 用户站:英/中库各一页(或同页两小节),导入路径与调用名并排;**JSON** 可共用一页、同一导入。
|
||||
- 金样例:分文件模块中英导入至少各一条;JSON 测 `lib/json.mq.md` 即可。
|
||||
- [keywords.md](keywords.md) 只列 L0;L1 指向本文 + [stdlib.md](stdlib.md) + [stdlib-modules.md](stdlib-modules.md)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 实现备忘(暂不开发)
|
||||
|
||||
实现阶段仅需:
|
||||
|
||||
1. 落地 `lib/text.mq.md` 与 `lib/文本.mq.md`(及 table / 表)两套文件与函数名。
|
||||
2. 更新导入示例与金样例;删除「仅中文库名」的单轨示例。
|
||||
3. **不要**实现 `lang:`、默认语言、或 `std/text` 自动选语言。
|
||||
|
||||
若历史上加过 `Module.lang` / `lang:` 解析,应撤回,与本草案对齐。
|
||||
|
||||
---
|
||||
|
||||
## 7. 一句话
|
||||
|
||||
**标准库用文件名区分语言(导入即选择);JSON 为缩写特例,中英共用 `lib/json.mq.md`——无语言开关。**
|
||||
@@ -0,0 +1,231 @@
|
||||
# 数学标准库(方案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已实现(M1–M4)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) |
|
||||
| 导入 | `lib/math.mq.md`(英)· `lib/数学.mq.md`(中) |
|
||||
| 范围 | **高中数学**(初等函数、导数、圆锥曲线、简单方程);非大学 CAS |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **公式类型**:解析 `$$…$$`(及行内 `$…$` 的可选支持),得到可绑定、可传递的 **`formula` 值**——语义上像「公式常量 / 公式变量」。
|
||||
2. **数学库对 `formula`(及文本表达式)做操作**:求值、化简、求导、求解、作图等。
|
||||
3. **数值 + 随机**:日常算术与可复现随机。
|
||||
4. **作图**:view / 静态页内嵌 SVG;CLI 写本地文件(可指定 `path`)。
|
||||
|
||||
**难度自觉:** 只覆盖高中知识面,自研小型表达式 AST + 规则即可,**不**追求 Mathematica / SymPy 完备性。
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心模型:`formula` 类型
|
||||
|
||||
### 2.1 运行时
|
||||
|
||||
| 类型 | `type` 标签 | 说明 |
|
||||
|------|-------------|------|
|
||||
| `Value::Num(f64)` | `num` | 浮点 |
|
||||
| `Value::Formula(…)` | `formula` | 已解析的表达式树(或等价内部表示) |
|
||||
|
||||
`print` / `str` 对 `formula`:输出规范 ASCII(如 `2*x + 1`)或保留源 LaTeX 的一种(实现时写死并文档化;建议 **ASCII 规范式** 便于测试)。
|
||||
|
||||
### 2.2 文档中的 `$$` = 公式赋值(与表格同构)
|
||||
|
||||
在可执行面用 **空 RHS 赋值** 后跟展示数学块,把公式绑到变量(与 `` `xs` = `` 后跟表格一致):
|
||||
|
||||
````markdown
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
sin(x) + x
|
||||
$$
|
||||
|
||||
*`df` = > diff formula=`f` var=x *
|
||||
|
||||
> plot formula=`f` var=x min=-3 max=3 path=f.svg
|
||||
````
|
||||
|
||||
也支持:
|
||||
|
||||
- 单行围栏:下一行 `$$x^2 - 2$$`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`
|
||||
|
||||
**废除:** `$$:name` / `$$ name=…` 模块级具名块(不再产生绑定)。
|
||||
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区若出现未挂在赋值上的裸 `$$` 围栏 → 报错,提示使用 `` `name` = `` + 围栏。
|
||||
|
||||
**行内 `$…$`:** v1 不做绑定;需要时用 `> formula text=…` 显式构造。
|
||||
|
||||
### 2.3 从文本构造
|
||||
|
||||
| 英文 | 中文 | 说明 |
|
||||
|------|------|------|
|
||||
| `formula` | `公式` | `text=` 解析为 `formula`(ASCII 或简单 LaTeX 子集) |
|
||||
|
||||
数学库函数形参统一接受:**`formula` 值**,或能解析的 **文本**(内部先 `formula` 化)。
|
||||
|
||||
### 2.4 与叙述面的关系
|
||||
|
||||
- `` `f` = `` + `$$…$$`:代码面赋值,得到 `formula` 值。
|
||||
- 成段注释里的 `$$`:仍是注释,不解析为公式。
|
||||
- view:公式赋值在 Structure 中显示为绑定,不是 comment。
|
||||
|
||||
(见 [markdown-mapping.md](markdown-mapping.md):空 RHS + `$$` → 公式赋值。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 知识范围(高中)
|
||||
|
||||
### 3.1 表达式与符号(S)
|
||||
|
||||
| 纳入 | 例子 |
|
||||
|------|------|
|
||||
| 多项式 | `x^2 - 3*x + 2` |
|
||||
| 初等函数 | `sin` `cos` `tan` `ln` `exp` `sqrt` `abs` |
|
||||
| 四则、幂 | `+ - * / ^` |
|
||||
| 化简 / 展开 | 合并同类项、基本三角恒等(小集合) |
|
||||
| 求导 | 单变元,初等函数求导法则 |
|
||||
| 代入求值 | `subs` → `num` 或公式 |
|
||||
| 求解 | 一元一次 / 二次闭式;其它用数值求根并标明 |
|
||||
|
||||
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、矩阵、复数完备、任意证明。
|
||||
|
||||
### 3.2 作图(P)
|
||||
|
||||
| 纳入 | 说明 |
|
||||
|------|------|
|
||||
| 显函数 `y=f(x)` | 采样折线 SVG |
|
||||
| 导数曲线 | 对 `formula` 先 `diff` 再画,或 `plot` 选项 `derivative=true` |
|
||||
| 圆锥曲线 | 标准形:圆、椭圆、双曲线、抛物线(参数方程或隐式采样) |
|
||||
| 点列 | `plot_points` |
|
||||
|
||||
**不做:** 三维、隐函数通用求解器、交互缩放(静态 SVG 足够)。
|
||||
|
||||
### 3.3 数值与随机(N)
|
||||
|
||||
常数、四则、三角、对数、取整、`num` 转换、`random` / `random_int` / `seed`(同前稿)。
|
||||
|
||||
---
|
||||
|
||||
## 4. API 草图(对 `formula` 操作)
|
||||
|
||||
### 4.1 构造与数值
|
||||
|
||||
| 英文 | 中文 | 要点 |
|
||||
|------|------|------|
|
||||
| `formula` | `公式` | 文本 → formula |
|
||||
| `pi` `e` | `圆周率` `自然底数` | → num |
|
||||
| `add`… / `sin`… | `加`… / `正弦`… | 对 num;若传入 formula 则返回 formula(符号)或报错——**v1 建议:算术函数只接 num;符号用 simplify/diff/subs** |
|
||||
| `eval` | `求值` | `formula` + 变量赋值 → num |
|
||||
| `random` / `random_int` / `seed` | `随机` / `随机整数` / `设种子` | 见前 |
|
||||
|
||||
### 4.2 符号
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `simplify` | `化简` | `formula` | formula |
|
||||
| `expand` | `展开` | `formula` | formula |
|
||||
| `diff` | `求导` | `formula`, `var` | formula |
|
||||
| `subs` | `代入` | `formula`, `var`, `value` | formula 或 num |
|
||||
| `solve` | `求解` | `formula`, `var`,可选区间 | list(num 或公式根) |
|
||||
|
||||
### 4.3 作图
|
||||
|
||||
| 英文 | 中文 | 形参 |
|
||||
|------|------|------|
|
||||
| `plot` | `绘图` | **`formula`**(或 `expr` 文本), `var`, `min`, `max`;可选 `steps`, `path`, `derivative`, **`grid`**(默认开;`False`/`假` 关) |
|
||||
| `plot_conic` | `绘圆锥` | `kind`(circle/ellipse/hyperbola/parabola)+ 系数;可选 `path`, `grid` |
|
||||
| `plot_points` | `绘点列` | `xs`, `ys`;可选 `path`, `grid` |
|
||||
|
||||
返回 **SVG 文本**;坐标轴带箭头与刻度,默认网格;写文件与 view 嵌入规则同前(§5)。
|
||||
|
||||
`diff` / `simplify` / `expand` / 未完全数值化的 `subs` 返回 **`formula`**,可继续链式调用。
|
||||
|
||||
示例:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*`roots` = > solve formula=`f` var=x *
|
||||
|
||||
> print text=`roots`
|
||||
|
||||
*`svg` = > plot formula=`f` var=x min=-3 max=3 path=parabola.svg *
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 作图:CLI / view / 静态(不变精神)
|
||||
|
||||
| 场景 | 行为 |
|
||||
|------|------|
|
||||
| 带 `path=` | 写 SVG 到该路径(沙箱内) |
|
||||
| CLI 无 path | 自动 `{stem}-plot-{n}.svg` + 一行 `plot: …` |
|
||||
| view / 导出无 path | 不强制写盘;加入 **plots 产物列表**,Execution 内嵌 |
|
||||
| view / 导出有 path | 写盘 + 内嵌 |
|
||||
|
||||
不把整段 SVG 默认灌进 CLI stdout。
|
||||
|
||||
---
|
||||
|
||||
## 6. 分期
|
||||
|
||||
| 期 | 交付 |
|
||||
|----|------|
|
||||
| **M1** | `Num` + 数值/随机;`Formula` AST + `` `name` = `` + `$$…$$` 赋值绑定 |
|
||||
| **M2** | `simplify` / `diff` / `subs` / `eval` / 二次 `solve`(高中子集) |
|
||||
| **M3** | `plot` / `plot_points` / `plot_conic` + view 内嵌 + path 写盘 |
|
||||
| **M4** | 用户文档 `public/stdlib/math*` · 金样例 · mapping 文档补丁 |
|
||||
|
||||
M1–M3 可在同一发版列车上连续落地;验收以「公式赋值 → 求导 → 作图」一条龙为准。
|
||||
|
||||
---
|
||||
|
||||
## 7. 实现要点
|
||||
|
||||
```text
|
||||
src/formula/ # 词法/AST/化简/求导/求值(高中规则表)
|
||||
src/host/math.rs # 数值、随机、对 formula 的 host 入口
|
||||
src/host/plot.rs # SVG
|
||||
lex/parse:空 RHS 赋值 + $$ 围栏 → Expr::Formula
|
||||
Value::Num / Value::Formula
|
||||
Interpreter.plots: Vec<String>
|
||||
lib/math.mq.md · lib/数学.mq.md
|
||||
```
|
||||
|
||||
依赖:纯 Rust;不绑 SymPy。公式复杂度、采样点、SVG 大小设硬上限。
|
||||
|
||||
---
|
||||
|
||||
## 8. 刻意不做
|
||||
|
||||
- `$$:name` 模块级具名绑定(已废除)。
|
||||
- 无名 `$$` 自动进运行时。
|
||||
- 大学级数 / 完备积分 / 定理证明。
|
||||
- 通用隐函数作图引擎。
|
||||
- 3D、交互式图表库。
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收
|
||||
|
||||
1. `` `f` = `` + `$$…$$` + `diff` / `solve` / `plot` 金样例(中英库)。
|
||||
2. 固定 `seed` 的随机金样例。
|
||||
3. `plot` + `path` 在 CLI 落盘;view HTML 含 `<svg`。
|
||||
4. `type` 对公式为 `formula`,对浮点为 `num`。
|
||||
5. view Structure 将公式赋值显示为绑定,而非 comment。
|
||||
|
||||
---
|
||||
|
||||
## 10. 一句话
|
||||
|
||||
**`` `f` = `` + `$$…$$` 产出 `formula` 值;数学库对它做高中范围的符号运算、求解与作图——数值与随机并行,图在 view 内嵌、在 CLI 写文件。**
|
||||
@@ -0,0 +1,195 @@
|
||||
# 标准库 L1 模块
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本与可选原生扩展。标准库**必须导入**才可用。
|
||||
|
||||
| 模块族 | 英文库 | 中文库 | 状态 |
|
||||
|--------|--------|--------|------|
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有(`put`/`改` + list/map;见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
|
||||
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
|
||||
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
|
||||
| JSON | `lib/json.mq.md` | **同文件** | 已有(含 `quote`) |
|
||||
| 网络 | `lib/net.mq.md` | `lib/网络.mq.md` | 已有(HTTPS + headers) |
|
||||
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | 已有 |
|
||||
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | 已有 |
|
||||
| **插件** | `lib/plugin.mq.md` | `lib/插件.mq.md` | **已有**(加载 C ABI 共享库) |
|
||||
| **自写回** | `lib/writeback.mq.md` | `lib/自写回.mq.md` | **已有**(Jupyter 式输出写回) |
|
||||
| **子任务** | `lib/subtask.mq.md` | `lib/子任务.mq.md` | **已有**(OS 子进程 + KillOnDrop) |
|
||||
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` — 见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层与实现分工
|
||||
|
||||
```text
|
||||
用户 .mq.md
|
||||
│ > lib/fs.mq.md / > ext/llm.mq.md
|
||||
▼
|
||||
L1 官方库 / 官方 ext(.mq.md)
|
||||
│
|
||||
▼
|
||||
L0.5 宿主原语(Rust)或 原生插件(ABI v1)
|
||||
│
|
||||
▼
|
||||
OS / HTTP / 时钟 / 共享库 …
|
||||
```
|
||||
|
||||
| 层 | 谁实现 | 用户是否直接调用 |
|
||||
|----|--------|------------------|
|
||||
| **L0** | 解释器内置 | 是(`print`/`len`/…) |
|
||||
| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装;ABI v2 `host_query` 仅插件可调 |
|
||||
| **L1 官方库** | `lib/*.mq.md` | **是** |
|
||||
| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`);**禁止** `host_*`,经 `lib/*` 或插件注册名 |
|
||||
|
||||
> **已变更(M1+M2)**:[module-namespace.md](module-namespace.md) — 取消跨文件扁平合并;L1/ext 经**裸名点号路径**调用(`time.parse`、`agent.agent`;M2:`库.对象.成员` + `use`),库名不加反引号;实例方法须 `` `var`.method ``;不再靠 import 顺序覆盖同名。
|
||||
|
||||
### 2.1 L1 薄包装 → 宿主(命名空间后必读)
|
||||
|
||||
点号路径 `net.http_post` / `json.stringify` 等解析到 **`lib/*.mq.md` 的 `##` 函数**,再转发 `host_*`。未在包装形参表声明的可选实参会被**静默丢弃**(曾导致 live agent 401:`Authorization` 等 `headers` 从未到达宿主)。
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| 每个 `host_*` 包装 | 须在 `+` 形参表声明**全部**宿主可选参数,默认 `None`,并在 `**> host_…**` 中**原样转发** |
|
||||
| `http_post` / `提交` | `content_type=None` 时宿主按默认 JSON charset 处理 |
|
||||
| 已对齐(2026-08-07) | `net`/`网络`(headers、content_type、body)、`sys`/`系统`(load_dotenv、exec)、`ext/ai/llm`(load_env / 加载环境 path)、`json.stringify` indent、`foreign`/`外联` stdin、`math`/`数学` plot*/solve 可选项 |
|
||||
|
||||
**无**扁平合并回退;**无**裸名双轨兼容。
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心模块 API(摘要)
|
||||
|
||||
文件 / 系统 / 时间 / JSON / 网络 API 见下文历史草图(已实现)。补充:
|
||||
|
||||
### 3.2 系统 — 已含 dotenv
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 新写入的键数量;缺文件 → `0`;不覆盖已有环境变量 |
|
||||
|
||||
### 3.4 JSON — 已含 `quote`
|
||||
|
||||
| 函数 | 形参 | 结果 |
|
||||
|------|------|------|
|
||||
| `quote` | `text` | JSON 字符串字面量(含引号) |
|
||||
|
||||
### 3.5 网络 — HTTPS
|
||||
|
||||
仅 **HTTP / HTTPS**(ureq);可选 `headers=`(map)、`content_type=`。
|
||||
|
||||
### 3.6 插件 — `plugin` / `插件`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `load` | `加载` | `path` / `路径` | 注册函数个数 |
|
||||
| `unload` | `卸载` | (无) | `None` |
|
||||
| `list` | `列出` | (无) | 已注册名列表 |
|
||||
|
||||
契约:[ext-abi.md](ext-abi.md)。路径受 cwd/fs_root 沙箱约束。
|
||||
|
||||
### 3.1–3.5 历史 API 草图
|
||||
|
||||
#### 文件 — `fs` / `文件`
|
||||
|
||||
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|
||||
|------|------|-----------------|------|
|
||||
| `read_text` | `读文本` | `path` / `路径` | 文本 |
|
||||
| `write_text` | `写文本` | `path`, `text` / `路径`, `内容` | `None` |
|
||||
| `append_text` | `追加文本` | 同上 | `None` |
|
||||
| `exists` | `存在` | `path` / `路径` | 布尔 |
|
||||
| `list_dir` | `列目录` | `path` / `路径` | 文本列表 |
|
||||
| `make_dir` | `建目录` | `path` / `路径` | `None` |
|
||||
| `remove` | `删除` | `path` / `路径` | `None` |
|
||||
|
||||
#### 系统 — `sys` / `系统`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `env_get` | `取环境` | `name` / `名` | 文本或 `None` |
|
||||
| `env_set` | `设环境` | `name`, `value` / `名`, `值` | `None` |
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 见上 |
|
||||
| `args` | `参数表` | (无) | 文本列表 |
|
||||
| `cwd` | `工作目录` | (无) | 文本 |
|
||||
| `exit` | `退出` | `code` / `码` | 不返回 |
|
||||
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码 |
|
||||
|
||||
#### 时间 — `time` / `时间`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `now_unix` | `此刻秒` | (无) | 整数(Unix 秒) |
|
||||
| `now_ms` | `此刻毫秒` | (无) | 整数 |
|
||||
| `format` | `格式化` | `unix`, `pattern` / `秒`, `格式` | 文本 |
|
||||
| `sleep_ms` | `睡眠毫秒` | `ms` / `毫秒` | `None` |
|
||||
| `parse` | `解析时间` | `text`, `pattern` / `内容`, `格式` | 整数秒或诊断失败 |
|
||||
|
||||
#### JSON — `json`
|
||||
|
||||
| 函数 | 形参 | 结果 |
|
||||
|------|------|------|
|
||||
| `parse` | `text` | 值 |
|
||||
| `stringify` | `value`, 可选 `indent` | JSON 文本 |
|
||||
| `get` | `value`, `key` | 值或 `None` |
|
||||
| `keys` | `value` | 文本列表 |
|
||||
| `quote` | `text` | JSON 字符串字面量 |
|
||||
|
||||
#### 网络 — `net` / `网络`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `http_get` | `获取` | `url` / `地址` | 响应文本 |
|
||||
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` / `headers` | 同上 |
|
||||
| `url_encode` | `编码地址` | `text` / `内容` | 文本 |
|
||||
|
||||
**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
|
||||
|
||||
---
|
||||
|
||||
## 4. 中英路径总表
|
||||
|
||||
```text
|
||||
lib/
|
||||
text.mq.md / 文本.mq.md
|
||||
table.mq.md / 表.mq.md
|
||||
fs.mq.md / 文件.mq.md
|
||||
sys.mq.md / 系统.mq.md
|
||||
time.mq.md / 时间.mq.md
|
||||
json.mq.md # 中英共用
|
||||
net.mq.md / 网络.mq.md
|
||||
math.mq.md / 数学.mq.md
|
||||
foreign.mq.md / 外联.mq.md
|
||||
plugin.mq.md / 插件.mq.md
|
||||
|
||||
ext/ # 非 stdlib
|
||||
llm.mq.md / 大模型.mq.md
|
||||
agent.mq.md / 智能体.mq.md
|
||||
```
|
||||
|
||||
别名:`std/…` ≡ `lib/…`。扩展解析:`MARQDO_EXT` / `./ext` / 二进制旁 `ext/`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 安全与 view / 静态导出
|
||||
|
||||
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**。差异仅在软退出 / sleep 钳制。相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。插件路径同沙箱。
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话
|
||||
|
||||
**L1 含文件 / 系统 / 时间 / JSON / 网络 / 数学 / 外联 / 插件;`ext/` 为可选官方扩展(llm、agent)。**
|
||||
@@ -0,0 +1,29 @@
|
||||
# 子任务标准库(subtask)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | v2 |
|
||||
| 库 | `lib/subtask.mq.md` · `lib/子任务.mq.md` |
|
||||
|
||||
## 定位
|
||||
|
||||
**并发**执行单元。`spawn` 四选一:
|
||||
|
||||
| 参数 | 执行方式 | `join` / `wait` 返回值 |
|
||||
|------|----------|------------------------|
|
||||
| `path=` | `marqdo run <file> --emit-result <tmp>` 子进程 | map `{ code, value, stdout?, stderr? }`(`# main` 返回值;quiet 时 piped 捕获 I/O 尾部,不 inherit TTY) |
|
||||
| `fn=` + 可选 `args=` | 当前入口模块中的函数(进程内线程) | 函数返回值 `Value` |
|
||||
| `code=` | 外联代码块(`Value::Code`)子进程 | stdout `Text` |
|
||||
| `lang=` + `source=` | 外联源码子进程 | stdout `Text` |
|
||||
|
||||
`args=`:文件子任务为 `List`(命令行参数);函数子任务为 `Map`(形参绑定)或 `List`(按 `arg0`… 命名)。
|
||||
|
||||
`quiet=` / `静默=`(默认 `True`):仅影响 **文件** 子任务的 **TTY**。默认 **piped 捕获** stdout/stderr(父终端不被污染,`wait` map 带截断后的 `stdout`/`stderr` 供父智能体观察);`False` 时继承父进程 stdout/stderr(map 中 I/O 字段为空)。**答案载荷仍以 `# main` 返回值为主**(经 `--emit-result` 旁路)。外联子任务仍经管道收集 stdout 供 `join` 返回,不受此参数影响。
|
||||
|
||||
**事件转发(文件子任务)**:spawn 时设置 `MARQDO_EVENT_FORWARD=<临时 ndjson>`;子进程内 `EventBus.publish` 追加写入该文件;父在 `wait` 阻塞期间 tail 并 republish(加 `source=child`)。这样子 LLM `stream=True` 的 token 能进 `marqdo view` SSE,而不破坏 quiet TTY 契约。函数子任务在同进程内,本来就共享 EventBus。
|
||||
|
||||
父进程结束(含 panic)时 **KillOnDrop** 终止所有文件/外联子进程;函数线程标记为 killed 并 detach(无法强杀 OS 线程)。
|
||||
|
||||
`poll` → `{ status: running | done | failed, … }`;函数 done 时含 `value`,进程/外联 failed 时含 `code` 或 `error`。
|
||||
|
||||
Host:`host_subtask_*`(`src/host/subtask.rs`)。
|
||||
@@ -0,0 +1,82 @@
|
||||
# `lib/table` / `lib/表` — 列表与字典
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地**(可用级集合 API) |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [table-cell-expressions.md](table-cell-expressions.md) · [roadmap/tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 读写对
|
||||
|
||||
| 读 | 写 |
|
||||
|----|----|
|
||||
| 脚注 `` `xs`[^1] `` / `` `m`[^key] `` / 嵌套 `` `m`[^a][^1] `` | **`table.put` / `表.改`** |
|
||||
|
||||
`put` / `改` 的 `at=`(`于=`)与脚注同构:文本键、**1-based** 整数下标,或键/下标组成的路径列表。
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`h` = > table.put in=None at=Authorization value=Bearer-x*
|
||||
|
||||
`xs` =
|
||||
|
||||
| v |
|
||||
|---|
|
||||
| a |
|
||||
| b |
|
||||
|
||||
*`xs` = > table.put in=`xs` at=1 value=A*
|
||||
```
|
||||
|
||||
`in=None` 且 `at=` 为单个文本键 → 新建单键字典。值一律不可变更新(返回新集合)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 索引约定
|
||||
|
||||
| API | 基数 |
|
||||
|-----|------|
|
||||
| `put` / `改` 路径中的整数;脚注 `[^n]` | **1-based** |
|
||||
| `at` / `row_at` / `set_at` / `insert` / `remove_at` / `slice` / `index_of` | **0-based** |
|
||||
|
||||
---
|
||||
|
||||
## 3. API 摘要(EN ↔ ZH)
|
||||
|
||||
| EN | ZH | 说明 |
|
||||
|----|----|------|
|
||||
| `put` | `改` | 按路径改一元(首选写入) |
|
||||
| `len` / `rows` | `长度` / `行数` | 长度 |
|
||||
| `at` / `row_at` | `取` / `取行` | 0-based 取元 |
|
||||
| `append` / `prepend` / `concat` | `追加` / `前插` / `拼接` | 列表 |
|
||||
| `insert` / `set_at` / `remove_at` / `pop` | `插入` / `改位` / `删位` / `弹出` | 列表位操作 |
|
||||
| `first` / `last` / `slice` | `首` / `末` / `切片` | |
|
||||
| `contains` / `index_of` / `reverse` | `含有` / `下标` / `反转` | |
|
||||
| `clear` | `清空` | 列表或字典 |
|
||||
| `get` / `set` / `delete` / `has` | `取键` / `设` / `删键` / `有键` | 浅层字典 |
|
||||
| `keys` / `values` / `items` / `merge` / `size` | `键表` / `值表` / `项表` / `合并` / `键数` | |
|
||||
| `empty_list` / `empty_map` | `空表` / `空字典` | |
|
||||
|
||||
嵌套改写优先 `put`/`改`;`set`/`set_at` 仅浅层。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 `lib/json`
|
||||
|
||||
| 用途 | 用 |
|
||||
|------|----|
|
||||
| 解析 / 序列化 / `quote` | `json.parse` · `json.stringify` · `json.quote` |
|
||||
| 集合读写 | **`table.*` / `表.*`** |
|
||||
| 兼容 | `json.set` / `json.append` / `json.get` / `json.keys` 仍为别名,新代码勿依赖 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 宿主
|
||||
|
||||
`host_collection_put` + list/map 原语(见 `src/host/collection.rs`)。作者面经 `lib/table` / `lib/表` 调用,不直接写 `host_*`。
|
||||
@@ -0,0 +1,59 @@
|
||||
# 自写回标准库(writeback)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | v1 已落地 |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 库 | `lib/writeback.mq.md` · `lib/自写回.mq.md` |
|
||||
|
||||
## 定位
|
||||
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
|
||||
|
||||
## 存储格式
|
||||
|
||||
```markdown
|
||||
*`n` = > len value=`xs` *
|
||||
<!-- marqdo-out
|
||||
42
|
||||
-->
|
||||
```
|
||||
|
||||
命名槽(智能体成功/失败互不覆盖):
|
||||
|
||||
```markdown
|
||||
<!-- marqdo-out ok
|
||||
status=ok result=…
|
||||
-->
|
||||
<!-- marqdo-out error
|
||||
pending
|
||||
-->
|
||||
```
|
||||
|
||||
- 注释内为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
|
||||
- 默认在**调用行下方**插入或替换紧邻**无键**块
|
||||
- `at_end=true`:替换文件末尾的**无键**块
|
||||
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽(智能体单步用父调用行,即 `step` 语句下方);`ensure` 在缺失时写入占位且不覆盖已有正文。命名槽互不覆盖,也不使用文件末尾单块。
|
||||
- `line=` / `行=`:显式锚点行号。子任务 / 异步写回必须带上,否则会锚到子任务内部调用行。主机侧有全局互斥锁,写前从磁盘重读入口源,避免并发写互相覆盖。
|
||||
|
||||
### 替换跨度与空行
|
||||
|
||||
替换 `<!-- marqdo-out … -->` 时,被替换跨度**包含**注释块结束 `-->` 后的**单个**换行符(不把该换行留在文件里)。这样多次 `record` **不会**在块下方累积多余空行。
|
||||
|
||||
命名槽仍锚在调用行(如 `step` / `写回`)下方;整簇结束后保留**一条**有意空行即可,且应稳定。
|
||||
|
||||
## API
|
||||
|
||||
| EN | ZH | 说明 |
|
||||
|----|-----|------|
|
||||
| `record` | `写回` | `value=`;可选 `at_end`、`key`、`line` |
|
||||
| `get` | `取` | 可选 `at_end`、`key`、`line` |
|
||||
| `clear` | `清除` | 可选 `at_end`、`key`、`line` |
|
||||
| `ensure` | `确保` | `key=` + 可选 `placeholder=`、`line=`;槽已存在则不动 |
|
||||
| `list` | `列出` | 全文所有输出块(命名槽含 `key` 字段) |
|
||||
|
||||
可选参数语法:`` + `参数名`=默认值 ``(与现有参数列表兼容)。
|
||||
|
||||
Host:`host_writeback_*`(`src/host/writeback.rs`);智能体侧经 `lib/subtask` 异步调用写回,避免阻塞推理主路径。
|
||||
|
||||
**与 `ext/ai/agent`:** `## step` / `## 单步` 在 D2 起 **默认自动** `record` 到 `ok`/`error` 槽(参数 `writeback=` / `写回=` 可关)。多步工作簿依赖此默认,见 [ext-agent-plan.md](ext-agent-plan.md) · [ext-agent.md](ext-agent.md)。
|
||||
@@ -0,0 +1,106 @@
|
||||
# 标准库(P2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 + L1 全模块落地** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
|
||||
|
||||
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
|
||||
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 分层
|
||||
|
||||
| 层 | 内容 |
|
||||
|----|------|
|
||||
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
|
||||
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
|
||||
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
|
||||
| **L2** | catalog / 用户站收录(随发版) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 内置一览(S0 + S1)
|
||||
|
||||
| 名 | 形参 | 结果 |
|
||||
|----|------|------|
|
||||
| `len` | `value` | 文本标量数或列表长度 |
|
||||
| `str` | `value` | 显示文本 |
|
||||
| `int` | `value` | 整数(失败 → 诊断) |
|
||||
| `type` | `value` | `none`/`bool`/`int`/`text`/`list`/`map` |
|
||||
| `trim` | `value` | 去首尾空白 |
|
||||
| `split` | `value`, `sep` | 文本列表 |
|
||||
| `join` | `value`, `sep` | 拼接文本 |
|
||||
| `at` | `value`, `index` | 列表下标(越界 → `None`) |
|
||||
|
||||
表(单列表格)在运行时是 `list`:行数用 `len`,取行用 `at`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 官方库导入(S2)
|
||||
|
||||
Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可改)。成员经点号路径调用(`time.parse`、`json.get`),不倒进全局短名。完整语义见 [module-namespace.md](module-namespace.md)。
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/text.mq.md
|
||||
> lib/table.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
调用示例:`> 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` 的相对路径)
|
||||
5. **内嵌 stdlib**(v0.1.2+,编译进二进制;无磁盘 `lib/` 时自动使用)
|
||||
|
||||
当前模块(API 多为 `##` 自由函数;见 [objects.md](objects.md)):
|
||||
|
||||
| 路径 | 导出 |
|
||||
|------|------|
|
||||
| `lib/fs.mq.md` / `lib/文件.mq.md` | `read_text`… / `读文本`… |
|
||||
| `lib/time.mq.md` / `lib/时间.mq.md` | `now_unix`… / `此刻秒`… |
|
||||
| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`…、`load_dotenv`… / `取环境`…、`加载环境`… |
|
||||
| `lib/json.mq.md` | `parse` `stringify` `get` `keys` `quote`(中英同文件) |
|
||||
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`…(HTTPS)/ `获取`… |
|
||||
| `lib/math.mq.md` / `lib/数学.mq.md` | 数值 / 随机 / 公式 / 绘图 |
|
||||
| `lib/foreign.mq.md` / `lib/外联.mq.md` | 具名围栏外联 |
|
||||
| `lib/plugin.mq.md` / `lib/插件.mq.md` | `load` / `unload` / `list`(原生 ABI) |
|
||||
| `lib/writeback.mq.md` / `lib/自写回.mq.md` | `record` `get` `clear` `list` |
|
||||
| `lib/subtask.mq.md` / `lib/子任务.mq.md` | `spawn` `poll` `wait` `kill` `wait_all` |
|
||||
| `lib/text.mq.md` | `str_trim` `str_split` `str_join` |
|
||||
| `lib/文本.mq.md` | `去空白` `拆分` `拼接` |
|
||||
| `lib/table.mq.md` | `put` 为首选写入;`rows`/`row_at` 及完整 list/map API — 见 [stdlib-table.md](stdlib-table.md) |
|
||||
| `lib/表.mq.md` | `改` 为首选写入;`行数`/`取行` 及完整 list/map API |
|
||||
|
||||
完整清单见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 转换错误约定(S3)
|
||||
|
||||
用户可见失败统一为:
|
||||
|
||||
```text
|
||||
path:line:col: message
|
||||
```
|
||||
|
||||
内置转换相关文案(稳定子集,金样例断言):
|
||||
|
||||
| 情况 | message |
|
||||
|------|---------|
|
||||
| 非法整数文本 | `cannot convert to int: "…"` |
|
||||
| `int` 类型不对 | `int needs int, bool, or text` |
|
||||
| `len` 类型不对 | `len needs text or list` |
|
||||
| `trim` 非文本 | `trim needs text` |
|
||||
| `split`/`join` 参数类型 | `split needs text value` 等 |
|
||||
| 空分隔符 | `split sep must not be empty` |
|
||||
|
||||
不引入独立异常类型对象;一律走 `Diagnostic`。
|
||||
@@ -0,0 +1,138 @@
|
||||
---
|
||||
title: table cell expressions
|
||||
status: Accepted
|
||||
date: 2026-08-12
|
||||
related: markdown-mapping.md · roadmap/tables-maps-footnotes.md · call-arguments.md
|
||||
---
|
||||
|
||||
# 表单元格表达式(T5)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted** |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [call-arguments.md](call-arguments.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
v1 把 GFM 数据单元格一律收成 **字面量**(`Int` / `Text`)。结果虽是 `Map` / `List`,却不能写:
|
||||
|
||||
```markdown
|
||||
`h` =
|
||||
|
||||
| api_key | model |
|
||||
|---------|-------|
|
||||
| `api_key` | `model` |
|
||||
```
|
||||
|
||||
作者只好用 `json.set` 链或 JSON 字符串拼接——这是**实现缺口**,不是「字典只能装字面量」的语义必然。
|
||||
|
||||
---
|
||||
|
||||
## 2. 锁定规则
|
||||
|
||||
### 2.1 数据单元格 = 与调用实参相同的值语法
|
||||
|
||||
每个**数据**单元格(非表头、非分隔行)按 [`parse_call_arg_value`](../../src/parse/expr.rs) 解析,再在绑定求值时执行:
|
||||
|
||||
| 单元格写法 | 含义 |
|
||||
|------------|------|
|
||||
| `苹果` / `Alpha` | 裸词 → 文本字面量(与今日竖表兼容) |
|
||||
| `42` | 整数 |
|
||||
| `` `api_key` `` | 变量引用 |
|
||||
| `` `a` + `b` `` | 普通表达式 |
|
||||
| `True` / `假` / `None` | 布尔 / 空 |
|
||||
| `"https://…"` / `".marqdo/x"` | 引号字符串(可含 `/`、插值) |
|
||||
| `https://api.openai.com/v1` | **路径折叠**:无空格的 `Text/Text/…` 除法链收成整段文本(同调用实参) |
|
||||
| `gpt-4o-mini` | **连字符散文**:不拆成减法(同调用实参) |
|
||||
| `` /about ``、`` /chat/completions `` | 以 `/` 开头的路径散文 → 整段文本 |
|
||||
| 空单元格 | 空文本 `""` |
|
||||
|
||||
### 2.2 表头仍是键名文本
|
||||
|
||||
表头单元格**不**求值:键 = trim 后的表头字符串(与今日一致)。不允许 `` | `k` | `` 当动态键(v1 非目标;需要时另文)。
|
||||
|
||||
### 2.3 几何语义不变
|
||||
|
||||
竖表 / 横表单行 Map / 多行列向 Map / `@`·`行`·`row` 行向记录——**形状规则不变**;只把「单元格 → `Expr::Literal`」换成「单元格 → 完整 `Expr`」。
|
||||
|
||||
求值已由解释器对 `Expr::List` / `Expr::Map` 递归完成,字节码后端已发射列表/字典,**无需新 AST 节点**。
|
||||
|
||||
### 2.4 求值时机
|
||||
|
||||
表出现在 `` `名` = `` 右侧时,在**该绑定语句**求值:单元格内变量读**当时**环境。构造函数体里的表与语句表规则相同。
|
||||
|
||||
### 2.5 错误
|
||||
|
||||
- 单元格表达式非法 → 与别处表达式相同的 `path:line:col` 诊断(行号取该表行)。
|
||||
- 变量未定义 → 求值期报错。
|
||||
- 不引入「单元格静默当字面量」的回退(除 §2.1 已列的路径/连字符折叠,与调用实参对齐)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 作者示例(目标体验)
|
||||
|
||||
```markdown
|
||||
*`api_key` = > sys.env_get name=OPENAI_API_KEY *
|
||||
*`model` = "gpt-4o-mini" *
|
||||
|
||||
`handle` =
|
||||
|
||||
| api_key | base_url | model | suffix |
|
||||
|---------|----------|-------|--------|
|
||||
| `api_key` | https://api.openai.com/v1 | `model` | /chat/completions |
|
||||
```
|
||||
|
||||
`handle` 为含运行时 `api_key` / `model` 的字典;静态 URL 与 suffix 仍可裸写(路径折叠)。
|
||||
|
||||
嵌套:
|
||||
|
||||
```markdown
|
||||
*`prompt` = hello *
|
||||
|
||||
`msg` =
|
||||
|
||||
| role | content |
|
||||
|------|---------|
|
||||
| user | `prompt` |
|
||||
|
||||
*`messages` = > json.append list=None item=`msg` *
|
||||
```
|
||||
|
||||
(列表字面量表仍可用竖表;需要「单行记录」时用横表或 `@` 行向表。)
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容性
|
||||
|
||||
| 旧写法 | 行为 |
|
||||
|--------|------|
|
||||
| 纯中文/英文词、整数 | **不变** |
|
||||
| `gpt-4o-mini`、URL、`/path` | **不变**(折叠规则与调用实参一致) |
|
||||
| 真正要做除法 / 减法 | 用空格或括号:`` `n` / 2 ``、`` `a` - 1 ``;或先在表外算再 `` `x` `` 填入 |
|
||||
|
||||
破坏性:几乎无。唯一需注意的是「想在单元格里写算术且两侧是裸词」——与调用实参同一套消歧。
|
||||
|
||||
---
|
||||
|
||||
## 5. 非目标(本阶段)
|
||||
|
||||
- 表头动态键
|
||||
- 单元格内 `>` 调用(可用表外算完再引用)
|
||||
- 单元格内多语句 / 分支
|
||||
- 把叙述区(注释段)里的 GFM 表当成可执行(仍为注释)
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收
|
||||
|
||||
| 项 | 标准 |
|
||||
|----|------|
|
||||
| 金样 | 横表单元格 `` `var` `` 读环境;竖表旧金样全绿 |
|
||||
| 路径 | `https://…`、`/chat/completions`、`gpt-4o-mini` 仍为文本 |
|
||||
| 扩展 | `ext/ai/llm` 构造可用表写入运行时字段,去掉无必要的 `json.set` 链 |
|
||||
| 文档 | 本页 + roadmap T5 + markdown-mapping §9 同步 |
|
||||
|
||||
实现跟踪见 [roadmap/tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) **T5**。
|
||||
@@ -0,0 +1,152 @@
|
||||
# 参考实现:技术选型分析(尚未拍板)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **分析中 — 未定案** |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 说明 | 对比候选与约束;**不在本文直接开写实现仓库脚手架** |
|
||||
|
||||
上一版曾草率写「就用 TypeScript」——信息不足,已作废为定论。本文只做选型框架与对比,**最终实现语言须单开 ADR 确认后再动工。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 我们在选什么
|
||||
|
||||
参考实现至少包含:
|
||||
|
||||
1. **读入** `.mq.md`(含 frontmatter 混合行)
|
||||
2. **对齐 GFM** 的结构:标题、列表(`-`/`+`/`1.`)、强调、表格、围栏、链接
|
||||
3. **Lower**:行首判别、标题树作用域、列表符语义、注释剥离
|
||||
4. **两遍**:收集定义 + 导入 → 求值
|
||||
5. **CLI** + **金样例测试**(`tests/`)
|
||||
|
||||
可选后期:字节码/编译、LSP、格式化。首版目标是**验证语法宪法**,不是上生产编译器。
|
||||
|
||||
---
|
||||
|
||||
## 2. 选型准则(按权重)
|
||||
|
||||
| 权重 | 准则 | 说明 |
|
||||
|------|------|------|
|
||||
| 高 | GFM 忠实度 | 表格、列表符、强调边界与 GitHub 预览一致,减少「能渲染不能跑 / 能跑不能渲染」 |
|
||||
| 高 | 与宪法同构 | 易于表达「先 mdast/事件流,再 Marqdo AST」 |
|
||||
| 高 | 测试与迭代速度 | 改语法宪法时能快速改测试 |
|
||||
| 中 | 静态类型 / 可维护 AST | 长期改解释器不疼 |
|
||||
| 中 | CLI 与打包 | 单二进制或 `npx`/等价体验 |
|
||||
| 低 | 极致性能 | v0 样例很小 |
|
||||
| 低 | 浏览器内运行 | 可后置 |
|
||||
|
||||
非准则:跟风、先写再选、与「生成 OKF」强绑某一云厂商。
|
||||
|
||||
---
|
||||
|
||||
## 3. 架构共性(与语言无关)
|
||||
|
||||
无论选哪门实现语言,流水线应一致:
|
||||
|
||||
```
|
||||
.mq.md 文本
|
||||
→ 前端:GFM 友好解析(或事件扫描)
|
||||
→ Middle:Marqdo lower(行类、标题树、- / +、表、围栏)
|
||||
→ Marqdo AST
|
||||
→ 语义:导入图、提升、作用域
|
||||
→ 后端:解释器(v0)/日后编译
|
||||
→ 测试:tests 金样例 → 期望 stdout
|
||||
```
|
||||
|
||||
**前端可复用成熟 GFM 库,也可自研**;Middle/后端必须自研(这是语言本体)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 候选对比
|
||||
|
||||
### A. TypeScript / Node + remark(mdast)
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| remark-gfm 与预览器语义接近;mdast 节点齐全 | 运行时依赖 Node;发行 CLI 需打包 |
|
||||
| 迭代快、Vitest 方便 | 性能与「系统级编译器」形象偏软 |
|
||||
| 与 Markdown 工具链同生态 | 需纪律:避免把业务写进插件泥潭 |
|
||||
|
||||
**适合:** 验证宪法、快速金样例。
|
||||
**不自动等于最终生产编译器。**
|
||||
|
||||
### B. Rust + pulldown-cmark / comrak
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 单静态二进制、性能好、适合日后正式编译器 | GFM 表格/细节与 GitHub 仍可能有差异,要对齐测试 |
|
||||
| 类型与代数数据类型适合 AST | 前期迭代比 TS 慢 |
|
||||
| 无 GC、可嵌入 | MD 生态碎片,选库要论证 |
|
||||
|
||||
**适合:** 中长期「真编译器」或与 TS 原型双轨。
|
||||
**风险:** 首版就上 Rust 可能拖慢语法验证。
|
||||
|
||||
### C. Python + markdown-it-py / mistune
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 原型极快 | 类型与工程化偏弱;双实现时易弃 |
|
||||
| 文本处理友好 | 打包 CLI 体验一般 |
|
||||
|
||||
**适合:** 一次性语法实验。
|
||||
**不推荐**作为唯一长期实现,除非团队强约束。
|
||||
|
||||
### D. Go + goldmark
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 单二进制、部署简单 | 泛型/AST 表达力一般;MD 库选 goldmark 需 GFM 扩展评估 |
|
||||
| 并发与工具链成熟 | 与 MD 研究生态联系弱于 JS |
|
||||
|
||||
**适合:** 工具型 CLI 优先的团队。
|
||||
|
||||
### E. 自研扫描器(任意语言)+ 仅用 GFM 做对照测试
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 完全控制行首判别与 `+`/`-` 语义 | 重复实现表格/强调,易与渲染不一致 |
|
||||
| 可强制「行分类优先于块解析」 | 工作量大 |
|
||||
|
||||
**适合:** 证明「行首判别」与 CommonMark 块结构冲突时的研究分支。
|
||||
可与 A/B 组合:自研 lower,块结构仍喂给现成解析器。
|
||||
|
||||
---
|
||||
|
||||
## 5. 关键技术风险(与选语言正交)
|
||||
|
||||
1. **行首判别 vs 块解析器** — CommonMark 先成块再看内容;Marqdo 先看行类。可能需「行预分类再喂解析器」或「解析后按源位置重分类」。选型时要让候选语言/库能拿到**源行映射**。
|
||||
2. **frontmatter 非纯 YAML** — `>` 导入行是扩展;不能整块丢给严格 YAML 解析器。
|
||||
3. **`+` 与 `-` 列表** — 多数解析器都认,但 lower 必须保留**项目符字符**,不能只得「unordered list」。选库时验证 AST 是否保留 bullet type。
|
||||
4. **`*` else vs `*返回*` vs 强调** — 依赖 inline 解析与「整行恰好一个 `*`」的行级规则并存。
|
||||
|
||||
以上 4 点应作为**选型验收用例**,写进 ADR:用最小样例在候选栈上 Spike,再定案。
|
||||
|
||||
---
|
||||
|
||||
## 6. 建议的决策流程(尚未执行)
|
||||
|
||||
1. **Spike(各 ≤0.5–1 日)**
|
||||
- 候选 A:TS + remark-gfm — 能否区分 `-`/`+` bullet、解析单列表格、读 strong/emphasis。
|
||||
- 候选 B:Rust + comrak/pulldown — 同上。
|
||||
- (可选)C 或 D 若团队有偏好再做。
|
||||
2. **对照验收用例**(固定):`tests/structure/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `> x.mq.md` 的 frontmatter 行。
|
||||
3. **出 ADR**:选定「验证期实现」与(可选)「生产目标实现」是否同一语言。
|
||||
4. **再**建仓库脚手架与测试——禁止在 ADR 前默认生成 `package.json` / `Cargo.toml` 当既成事实。
|
||||
|
||||
---
|
||||
|
||||
## 7. 当前态度(非正式投票)
|
||||
|
||||
| 阶段 | 倾向(待 Spike 验证) |
|
||||
|------|------------------------|
|
||||
| 语法验证期 | 更可能是 **TypeScript + remark**(快、GFM 近) |
|
||||
| 长期生产编译器 | **开放** Rust / Go,不与验证期绑定 |
|
||||
|
||||
**本文不授权开始实现。** 确认 Spike 计划或直接指定语言后,再写 `adr/0001-implementation-language.md`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 与「无标记 = 注释」的关系
|
||||
|
||||
实现必须先做**行分类**(见 [code-vs-comment.md](code-vs-comment.md)),再谈用何种语言写分类器。选型不能假设「整文件都是可执行代码」。
|
||||
@@ -0,0 +1,66 @@
|
||||
# 用户静态文档站(public / gh-pages)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [view.md](view.md) · 源目录 [`public/`](../../public/) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 分工
|
||||
|
||||
| 路径 | 是否入库 | 职责 |
|
||||
|------|----------|------|
|
||||
| `doc/` | 是 | 开发者设计 / ADR / 路线图(单数 `doc`,勿再造 `docs/`) |
|
||||
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / **stdlib** / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列。stdlib 含 `plugin`;特性页覆盖对象与 `ext/`(llm / agent) |
|
||||
| `public/index.html`、`public/pages/` | **否**(ignore) | `marqdo view output` 生成的 HTML |
|
||||
| `tests/{structure,keywords,errors}/` | 是 | 金样例与失败夹具(含 errors) |
|
||||
| 远程分支 `gh-pages` | 发布产物 | 发布整个 `public/`(源文件 + 生成 HTML) |
|
||||
|
||||
**禁止**把 `tests/errors/` 编进用户站。
|
||||
|
||||
---
|
||||
|
||||
## 2. 生成
|
||||
|
||||
```bash
|
||||
cargo run --release -- view output public -o public
|
||||
# 或
|
||||
./scripts/build-public.sh
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
产物写在源旁:
|
||||
|
||||
```
|
||||
public/
|
||||
*.mq.md / structure/ / … # 入库源
|
||||
index.html # 生成(ignore)
|
||||
pages/… # 生成(ignore)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 发布分支
|
||||
|
||||
将构建后的 `public/` 推到 **`gh-pages`**。CI:`.github/workflows/pages.yml`。
|
||||
|
||||
仓库 Settings → Pages → Source = Deploy from branch → `gh-pages` / root。
|
||||
|
||||
---
|
||||
|
||||
## 4. 内容分层(用户站)
|
||||
|
||||
| 目录 | 内容 |
|
||||
|------|------|
|
||||
| `public/stdlib/` | L1 模块页(含 `plugin` / `插件`);概述注明 `ext/` 非 stdlib |
|
||||
| `public/features/` | 迭代特性:树遍历、字节码、view、**对象**、**官方扩展** |
|
||||
|
||||
设计文档仍在 `doc/design/`(`objects.md`、`ext-llm.md`、`ext-abi.md`、`ext-agent.md`)。
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. `public/` 下每个 `.mq.md`(除纯工具模块外)`marqdo run` 退出码 0。
|
||||
2. `view output public -o public` 后首页为欢迎页,侧栏无 errors。
|
||||
3. 主分支跟踪 `public/**/*.mq.md`;不提交 `public/index.html` / `public/pages/`。
|
||||
@@ -0,0 +1,42 @@
|
||||
# View 调试(`marqdo debug`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **v1(独立 debug 页)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
|
||||
## 分工
|
||||
|
||||
| 命令 | 角色 |
|
||||
|------|------|
|
||||
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
|
||||
|
||||
静态 `gh-pages` / `view output` **不能**真断点。
|
||||
|
||||
## Debug 布局(对齐常见调试器)
|
||||
|
||||
参考 VS Code / Chrome DevTools / Jupyter debugger:
|
||||
|
||||
```
|
||||
┌ Toolbar: Start · Continue (F5) · Step (F10) · Stop · status ─┐
|
||||
├ Files ─┬─ Structure (gutter BP) + outline ─┬─ Variables ┤
|
||||
│ │ ├─ Breakpoints │
|
||||
│ │ └─ Call stack │
|
||||
├────────┴────────────────────────────────────┴────────────────┤
|
||||
│ Debug Console (session stdout) │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- 暂停粒度:语句起点(树遍历)。
|
||||
- 无断点时 Start 停在第一句。
|
||||
- Structure 为断点面(非 Source 行)。
|
||||
|
||||
## API
|
||||
|
||||
与此前相同:`POST /api/debug/start|continue|step|stop|breakpoints`(仅 debug 服务)。
|
||||
|
||||
## View 大纲
|
||||
|
||||
Structure 旁(或窄屏下方)函数树:`#fn-{line}` 锚点 + 搜索框过滤 `data-fn` / `data-fn-path`。
|
||||
@@ -0,0 +1,161 @@
|
||||
# `marqdo view` — 源结构浏览器与静态文档导出
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.0.2 方向) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
`.mq.md` 既是文档也是程序。需要:
|
||||
|
||||
1. **本地浏览**:按 AST 展示结构 + 执行结果;
|
||||
2. **静态导出**:同一套渲染写成 HTML,作为**用户文档站点**(勿手写第二套站点);
|
||||
3. **启动快**:样式极简,无外链字体/厚主题,避免 view 冷启动慢。
|
||||
|
||||
---
|
||||
|
||||
## 2. 视觉(Apple HIG / Docs 极简)
|
||||
|
||||
对齐 [Apple HIG](https://developer.apple.com/design/human-interface-guidelines) 的 **clarity / deference / white space**,并参考常见 docs 布局(sticky 侧栏 + 居中主栏,见 Nextra / Docusaurus 类站点):**系统灰底、白内容面、浅分隔线、系统字体**。作者站 [id.cflmy.cn](https://id.cflmy.cn) 仍作克制感参考,但不强行纯黑描边。
|
||||
|
||||
| 规则 | 要求 |
|
||||
|------|------|
|
||||
| 色板 | 页底 `#f5f5f7`;内容面 `#ffffff`;正文 `#1d1d1f`;次要字 `#6e6e73`;分隔 `#d2d2d7`;选中侧栏项反白 |
|
||||
| 布局 | 壳层 `max-width ≈ 1680px`;侧栏 ≈280px;主内容 `max-width ≈ 76rem`;Structure 旁函数大纲;**≤800px 侧栏收起** |
|
||||
| 默认页 | 打开目录时 **直接展示排序后的第一个 `.mq.md`**(实时 `/` 与静态 `index.html` 同),不要求用户先从欢迎页点选 |
|
||||
| 字体 | 仅系统栈:`-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif`;等宽 `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` |
|
||||
| 外链 | **禁止** Google Fonts / CDN 样式;CSS 全部内联于 HTML |
|
||||
| 装饰 | 无多层阴影、无渐变、无发光;圆角 ≈12px;结构区为分组列表(底部分隔),非堆叠厚卡片 |
|
||||
| 诊断路径 | 展示时去掉 Windows `\\?\` 前缀,并优先用相对 view 根的路径 |
|
||||
|
||||
验收:首屏无外网字体请求;宽屏主栏明显宽于早期 `58rem` 方案(现约 `76rem` / 壳 `1680px`)。
|
||||
|
||||
---
|
||||
|
||||
## 3. CLI
|
||||
|
||||
### 3.1 实时浏览
|
||||
|
||||
```bash
|
||||
marqdo view [PATH] [--port PORT] [--host HOST] [--no-open]
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | `.mq.md` 或目录 |
|
||||
| `--port` | `7429` | |
|
||||
| `--host` | `127.0.0.1` | |
|
||||
| `--no-open` | 关 | 不打开浏览器 |
|
||||
|
||||
### 3.2 静态导出(文档生成)
|
||||
|
||||
```bash
|
||||
marqdo view output [PATH] -o OUT_DIR [--no-exec]
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 与 `view` 相同扫描范围 |
|
||||
| `-o` / `--out` | (必填) | 输出目录(不存在则创建) |
|
||||
| `--no-exec` | 关 | 不跑程序,执行区显示「skipped」 |
|
||||
|
||||
**产物布局:**
|
||||
|
||||
```
|
||||
OUT_DIR/
|
||||
index.html # 默认 = 排序后第一个 .mq.md 的完整页(侧栏高亮该项)
|
||||
pages/
|
||||
<相对路径>.html # 每个 .mq.md 一页;路径中的 `/` 保留为子目录
|
||||
# 例:structure/hello.mq.md → pages/structure/hello.mq.md.html
|
||||
```
|
||||
|
||||
- 页内链接一律**相对路径**,可用任意静态服务器或 `file://`(同目录结构下)打开。
|
||||
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
|
||||
- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
|
||||
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
|
||||
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
|
||||
|
||||
示例:
|
||||
|
||||
```bash
|
||||
marqdo view output public -o public
|
||||
marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 信息架构
|
||||
|
||||
侧栏文件索引 + 主区:结构(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)。
|
||||
|
||||
---
|
||||
|
||||
## 5. HTTP(实时模式)
|
||||
|
||||
| 方法 | 路径 | 含义 |
|
||||
|------|------|------|
|
||||
| `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` 为增量。
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收
|
||||
|
||||
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件;函数大纲可搜索跳转。
|
||||
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
|
||||
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
|
||||
4. 冷启动无明显外网依赖。
|
||||
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
|
||||
6. Stream:`fetch`+SSE 局部更新;Thinking/Answer 分栏;stick-to-bottom;rAF 合批;页载不常连 EventSource。
|
||||
@@ -0,0 +1,82 @@
|
||||
# VS Code 扩展 — 分支与提交约定
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **强制约定**(勿在 `main` 提交扩展源码) |
|
||||
| 扩展分支 | **`vscode-extension`** |
|
||||
| 设计说明 | [vscode-extension.md](vscode-extension.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原则(必读)
|
||||
|
||||
| 分支 | 是否跟踪 `vscode-extension/` |
|
||||
|------|-------------------------------|
|
||||
| **`main`** | **否** — `.gitignore` 含 `/vscode-extension/` |
|
||||
| **`vscode-extension`** | **是** — 扩展唯一源码所在分支 |
|
||||
|
||||
**禁止**在 `main` 上:
|
||||
|
||||
- 删除 `.gitignore` 里的 `/vscode-extension/`
|
||||
- `git add vscode-extension/`
|
||||
- 把扩展目录「合并进 main」以便发版
|
||||
|
||||
发版时从 **`vscode-extension` 分支检出**扩展目录打 VSIX(见 §4),**不是**把扩展提交进 `main`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 日常开发(扩展)
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git checkout vscode-extension
|
||||
cd vscode-extension && npm ci && npm run compile
|
||||
```
|
||||
|
||||
改语法、CLI 检测、扩展版本 → **只在 `vscode-extension` 分支提交**:
|
||||
|
||||
```bash
|
||||
git add vscode-extension/
|
||||
git commit -m "vscode-extension: <简要说明>"
|
||||
git push origin vscode-extension
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 日常开发(CLI / 语言)
|
||||
|
||||
在 **`main`** 上改 `src/`、`lib/`、`public/`、`tests/` 等;**不要**顺带提交 `vscode-extension/`。
|
||||
|
||||
若本地为了调试 checkout 过扩展目录,工作区里可以有 `vscode-extension/` 文件夹,但应被 ignore,且 **`git status` 不应出现**该目录下文件。
|
||||
|
||||
---
|
||||
|
||||
## 4. 发版(CLI tag + VSIX)
|
||||
|
||||
1. **`main`**:打 tag(如 `v0.1.2`),CI 构建 `marqdo.exe` 等。
|
||||
2. **VSIX**:Release 工作流在 tag 构建时执行:
|
||||
```bash
|
||||
git fetch origin vscode-extension
|
||||
git checkout origin/vscode-extension -- vscode-extension
|
||||
cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package
|
||||
```
|
||||
3. 本地脚本 `scripts/release-windows.ps1` 同样假定:先 `git checkout origin/vscode-extension -- vscode-extension`(或已在 `vscode-extension` 分支),再打 VSIX。
|
||||
|
||||
扩展版本号与最低 CLI 要求写在 **`vscode-extension/package.json`** 与分支 README,**不要**在 `main` 的 CHANGELOG 里冒充已合并扩展源码。
|
||||
|
||||
---
|
||||
|
||||
## 5. 给 Agent / 协作者
|
||||
|
||||
执行「更新 VS Code 插件」类任务时:
|
||||
|
||||
1. **切到或基于 `vscode-extension` 分支**改 `vscode-extension/**`
|
||||
2. **不要**移除 `main` 上 `.gitignore` 的 `/vscode-extension/`
|
||||
3. **不要**在 `main` 的 release 提交里包含 `vscode-extension/package-lock.json` 等大文件
|
||||
4. 仅需在 `main` 更新时:改 `doc/design/vscode-extension.md`、Release 说明、**本文件** — 指针文档即可
|
||||
|
||||
---
|
||||
|
||||
## 6. 历史说明
|
||||
|
||||
v0.1.2 准备阶段曾误将 `vscode-extension/` 并入 `main`(并删除 ignore),导致推送体积过大。已恢复:**扩展仅 `vscode-extension` 分支**;`main` 只保留本约定与设计指针。
|
||||
@@ -0,0 +1,31 @@
|
||||
# VS Code 扩展(分支指针)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定分支模型** |
|
||||
| 代码分支 | **`vscode-extension`**(同仓库) |
|
||||
| 目录 | 工作区 `vscode-extension/`(**仅在该分支跟踪;`main` 在 `.gitignore` 忽略**) |
|
||||
| 提交约定 | **[vscode-extension-commit.md](vscode-extension-commit.md)**(必读,避免误提交到 `main`) |
|
||||
|
||||
---
|
||||
|
||||
## 分工(类比 `public` / `gh-pages`)
|
||||
|
||||
| 分支 | 内容 |
|
||||
|------|------|
|
||||
| `main` | Marqdo 语言 / CLI / `public/*.mq.md`;**不**存放扩展实现 |
|
||||
| `vscode-extension` | VS Code 扩展源码、TextMate 语法、VSIX 发版 |
|
||||
| `gh-pages` | 用户站生成 HTML |
|
||||
|
||||
```bash
|
||||
git checkout vscode-extension
|
||||
cd vscode-extension && npm install
|
||||
```
|
||||
|
||||
规范入口(在 **`vscode-extension` 分支**上阅读):
|
||||
|
||||
- `vscode-extension/README.md` — 目标与目录
|
||||
- `vscode-extension/DEVELOPMENT.md` — 日常流程
|
||||
- `vscode-extension/ARCHITECTURE.md` — 与 CLI 边界
|
||||
|
||||
扩展是 CLI 的薄宿主;语法真相仍是 [markdown-mapping.md](markdown-mapping.md)。
|
||||
@@ -0,0 +1,87 @@
|
||||
# 开发环境配置(Rust 参考解释器)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | M0 |
|
||||
| 相关 | [dependencies.md](design/dependencies.md) · [interpreter.md](roadmap/interpreter.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 必备软件
|
||||
|
||||
| 软件 | 要求 | 检查 |
|
||||
|------|------|------|
|
||||
| Rust + Cargo | stable,建议 ≥ 1.81(本机验证过 1.81) | `rustc --version` / `cargo --version` |
|
||||
| Git | 任意近期版本 | `git --version` |
|
||||
|
||||
安装 Rust(若尚未安装):
|
||||
|
||||
- 官方:[https://rustup.rs/](https://rustup.rs/)
|
||||
- Windows:下载 `rustup-init.exe`,按提示安装后**重新打开终端**
|
||||
|
||||
本仓库可选 `rust-toolchain.toml`(钉 1.81.0)。若本机无 `rustup`、但已有匹配的 `rustc`/`cargo`,也可直接开发。
|
||||
|
||||
**不需要:** Flex、Bison、LLVM、Node/npm(实现栈为 Rust)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 获取代码与构建
|
||||
|
||||
```bash
|
||||
git clone https://github.com/cflmy/marqdo.git
|
||||
cd marqdo
|
||||
|
||||
cargo build
|
||||
cargo test
|
||||
cargo run -- run tests/structure/hello.mq.md
|
||||
```
|
||||
|
||||
当前 M0:`run` 会读入文件并明确报错「evaluation not implemented」(脚手架,非静默假成功)。
|
||||
|
||||
> 若 `cargo build` 报 `edition2024` / 过新 crate:仓库已对 `clap` 等做兼容钉扎(见 `Cargo.toml`);请使用附带的 `Cargo.lock`,勿盲目 `cargo update` 到最新 major。
|
||||
|
||||
---
|
||||
|
||||
## 3. 推荐组件
|
||||
|
||||
```bash
|
||||
rustup component add rustfmt clippy # 若使用 rustup
|
||||
cargo fmt
|
||||
cargo clippy --all-targets
|
||||
```
|
||||
|
||||
代理下拉 crate(可选,与 git 推送类似):
|
||||
|
||||
```bash
|
||||
# Windows PowerShell 示例
|
||||
$env:HTTPS_PROXY="http://127.0.0.1:7890"
|
||||
$env:HTTP_PROXY="http://127.0.0.1:7890"
|
||||
cargo build
|
||||
```
|
||||
|
||||
或配置 `%USERPROFILE%\.cargo\config.toml`:
|
||||
|
||||
```toml
|
||||
[http]
|
||||
proxy = "http://127.0.0.1:7890"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 目录约定
|
||||
|
||||
| 路径 | 含义 |
|
||||
|------|------|
|
||||
| `src/lex` | 行分类 / 词法(自研) |
|
||||
| `src/parse` | 递归下降语法 |
|
||||
| `src/diagnostics` | 诊断 |
|
||||
| `tests/` | 金样例 + 集成测试(`structure` / `keywords` / `errors`) |
|
||||
| `public/` | 用户可执行文档(无 errors) |
|
||||
| `spike/` | 旧 Python 风险探测,非运行时依赖 |
|
||||
| `doc/` | 设计与路线图 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 下一里程碑
|
||||
|
||||
见 [interpreter.md](roadmap/interpreter.md):M1 词法·行分类与最小 AST。
|
||||
@@ -0,0 +1,215 @@
|
||||
# 调研:Google Open Knowledge Format(OKF)与 Marqdo
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 调研笔记 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 对象 | [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) |
|
||||
| 公告 | [v0.1 介绍](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) · [v0.2 trust signals](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals) |
|
||||
|
||||
---
|
||||
|
||||
## 1. OKF 是什么
|
||||
|
||||
**Open Knowledge Format(开放知识格式)** 是 Google Cloud 于 2026 年 6 月发布的厂商中立开放规范(Apache 2.0)。它把「LLM Wiki」模式形式化为可移植格式:用**目录树中的 Markdown 文件 + YAML frontmatter** 表示组织知识(表结构、指标、API、操作手册等),供人类与 AI Agent 共同阅读、交换与维护。
|
||||
|
||||
一句话定位:
|
||||
|
||||
> 知识应活在**格式**里,而不是专有服务或散落的非结构化文本里。
|
||||
|
||||
### 核心形态
|
||||
|
||||
```
|
||||
bundle/
|
||||
index.md # 可选:目录索引(渐进披露)
|
||||
log.md # 可选:变更历史
|
||||
concepts/.../*.md # 每个概念一个 Markdown 文件
|
||||
```
|
||||
|
||||
每个概念文件:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Metric # 唯一必填
|
||||
title: Monthly Active Users
|
||||
description: ...
|
||||
tags: [product, growth]
|
||||
sources: [...] # v0.2:出处
|
||||
generated: {...} # v0.2:谁生成的
|
||||
verified: {...} # v0.2:谁验证的
|
||||
status: stable # v0.2:生命周期
|
||||
stale_after: 2026-12-01 # v0.2:过期日
|
||||
---
|
||||
|
||||
# 正文(自由 Markdown)
|
||||
|
||||
指标定义为……
|
||||
```
|
||||
|
||||
- **Concept ID** = 相对路径去掉 `.md`
|
||||
- **链接** = 普通 Markdown 链接,形成可遍历关系图
|
||||
- **无中心 schema registry**;未知 `type` 必须被优雅降级处理
|
||||
|
||||
### 设计三原则(官方表述)
|
||||
|
||||
1. **Minimally opinionated** — 只强制互通所需的最小公约;其余留给生产者。
|
||||
2. **Producer / consumer independence** — 写知识的人(或 Agent)与读知识的 Agent/工具解耦;格式即契约。
|
||||
3. **Format, not platform** — 不绑定云、数据库、模型或 Agent 框架;`cat` 能读,`git clone` 能分发。
|
||||
|
||||
### v0.2 新增:五类信任信号
|
||||
|
||||
当知识主要由 Agent **持续生成**时,纯 Markdown 不够。v0.2 把下列问题变成 frontmatter 一等字段:
|
||||
|
||||
| 问题 | 机制 |
|
||||
|------|------|
|
||||
| 从何而来? | `sources`(出处 + 可信度信号,不作统一打分) |
|
||||
| 该信多少? | `generated` / `verified` → 推导 trust tier(未验证 / 机器确认 / 人工审核) |
|
||||
| 是否仍真? | `stale_after`(绝对日期,非相对 TTL) |
|
||||
| 是否现行? | `status`: `draft` → `stable` → `deprecated` |
|
||||
| 数字是否按约定算出? | 概念类型 `Attested Computation`:executor 跑计算出 receipt,**非 LLM** 的 attester 核验 |
|
||||
|
||||
---
|
||||
|
||||
## 2. OKF 与 Marqdo:相邻,但不等同
|
||||
|
||||
| 维度 | OKF | Marqdo |
|
||||
|------|-----|--------|
|
||||
| 本质 | **知识交换格式** | **编程语言** |
|
||||
| 文件角色 | 描述资产与概念的文档 | 可执行程序 = 可渲染文档 |
|
||||
| 机器侧 | 解析 metadata、遍历链接、过滤信任 | 解析、类型检查、求值/编译 |
|
||||
| Markdown 地位 | 载体与呈现层 | **语法表层的一部分**(源即 Markdown) |
|
||||
| 成功标准 | 跨组织互通、Agent 可策展 | 严肃编程能力 + 阅读体验同时成立 |
|
||||
|
||||
OKF 回答:「人和 Agent 如何**共享与信任知识**?」
|
||||
Marqdo 回答:「程序如何**本身就是知识**,且仍能运行?」
|
||||
|
||||
因此借鉴应落在**表示哲学与工程约束**,而不是照搬「知识目录」产品形态。
|
||||
|
||||
---
|
||||
|
||||
## 3. 值得借鉴的设计点
|
||||
|
||||
### 3.1 后缀与生态搭便车 — 已采纳
|
||||
|
||||
OKF 坚持「就是 Markdown」:GitHub 渲染、编辑器预览、静态站、搜索索引零摩擦。
|
||||
|
||||
**Marqdo 对应决策:源文件后缀为 `.mq.md`。**
|
||||
|
||||
- `.md` 确保通用 Markdown 渲染器开箱可用
|
||||
- `.mq` 前缀声明这是 Marqdo 源,而非普通文档
|
||||
- 与 OKF「格式优先于平台」一致:可读性不依赖自研 viewer
|
||||
|
||||
### 3.2 最小强制面(Minimally opinionated)
|
||||
|
||||
OKF 只强制 `type`;其余可选,未知字段保留不拒绝。
|
||||
|
||||
**对 Marqdo 的启发:**
|
||||
|
||||
- 语言的「文档面」与「程序面」之间,划清**硬语法**与**散文**
|
||||
- 第一版语法宜小:标题层级、声明、表达式……先钉死互通/可执行最小集
|
||||
- 扩展用约定或可选 frontmatter,避免一上来造完整注解宇宙
|
||||
|
||||
### 3.3 生成式 YAML / OKF 清单 — 已采纳方向(已修正)
|
||||
|
||||
OKF 用 YAML frontmatter 承载「可查询元数据」。Marqdo **借鉴其形态**,但职责不同:
|
||||
|
||||
**YAML(OKF 风格知识包)由工具从 `.mq.md` 自动生成,不是人手写的配置文件。**
|
||||
|
||||
详见 [`design/generated-yaml-manifest.md`](../design/generated-yaml-manifest.md)。
|
||||
|
||||
| | |
|
||||
|--|--|
|
||||
| 类比 | 其它语言中由工具维护的依赖描述(如 `Cargo.toml` / `requirements.txt` 所承担的那类角色) |
|
||||
| 形态 | OKF:概念目录 + YAML frontmatter + Markdown 正文 |
|
||||
| 用途 | ① 编译器/包管理消费依赖图与导出 ② **自动生成本项目文档**(模块索引、依赖关系等) |
|
||||
| 权威 | 始终是手写 `.mq.md`;清单可删、可重建 |
|
||||
|
||||
```
|
||||
.mq.md 源(人写)
|
||||
→ marqdo 工具链
|
||||
→ 生成 OKF 风格清单(YAML + 概念页)
|
||||
→ 供编译解析,并渲染为项目目录文档
|
||||
```
|
||||
|
||||
执行方式等运行参数不放进该 YAML 当配置;由 CLI / 子命令决定。
|
||||
程序本体(类型、函数)只活在源正文里。
|
||||
|
||||
### 3.4 路径即身份,链接即关系
|
||||
|
||||
Concept ID = 路径;关系 = Markdown 链接;目录 = 渐进披露(`index.md`)。
|
||||
|
||||
**对模块系统的启发:**
|
||||
|
||||
- 文件路径可成为模块身份的一部分(类比 OKF concept ID)
|
||||
- `import` / 交叉引用尽量与 Markdown 链接同构,使「读文档跳转」与「解析依赖」共用一种边
|
||||
- 大型程序按「书的章节」组织目录,而不是扁平包名墙
|
||||
|
||||
### 3.5 生产者 / 消费者分离
|
||||
|
||||
同一 bundle:人手写、Agent 生成、管道导出,均可被另一 Agent 或 UI 消费。
|
||||
|
||||
**对 Marqdo 工具链:**
|
||||
|
||||
- 解析器、渲染器、求值器、LSP 都是**消费者**;源格式是唯一契约
|
||||
- 允许 Agent 协助编写 `.mq.md`,但语言必须对「纯手写」同样友好
|
||||
- 不把语义锁进某一 IDE 或云服务
|
||||
|
||||
### 3.6 信任与 attestation(中长期)
|
||||
|
||||
OKF v0.2 的 Attested Computation:批准的算法 + 确定性核验,防止 Agent「随口报数」。
|
||||
|
||||
**远期可借鉴(非 v0 范围):**
|
||||
|
||||
- 文档中嵌入的「可运行示例」是否经过核验执行?
|
||||
- 渲染出的结果是否带来源与 receipt?
|
||||
- Agent 生成的 Marqdo 模块如何标注 `generated` / `verified`?
|
||||
|
||||
这强化「文档中的数字/行为与真实执行一致」——与 Marqdo「同一份真相」高度同向。
|
||||
|
||||
### 3.7 规范本身的克制
|
||||
|
||||
OKF 规范强调:一页纸能讲清 v0.1 的互通面;v0.2 只**加词汇、不加强制规则**。
|
||||
|
||||
**对 Marqdo 文档文化:**
|
||||
|
||||
- ADR 记录否决项
|
||||
- 语法草案保持短小、可验证的 conformance 描述
|
||||
- 版本演进优先加法兼容,避免随意破坏「已是有效程序」的源文件
|
||||
|
||||
---
|
||||
|
||||
## 4. 不应照搬之处
|
||||
|
||||
1. **OKF 不是语言** — 其 body 是自由散文;Marqdo body 必须有严格可执行语义。不能停在「Markdown 知识库」。
|
||||
2. **无中心 type 注册** 适合知识目录;编程语言的类型系统需要更强的一致性与检查规则。
|
||||
3. **`Attested Computation` 的 executor/attester** 面向数据平台查询核验;Marqdo 若引入类似机制,应长在「测试 / 示例求值 / 再现构建」上,而不是 BigQuery 收据模型。
|
||||
4. **保留文件名**(`index.md` / `log.md`)可参考,但是否占用需在模块设计里单独 ADR,避免与源文件约定冲突。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议纳入 Marqdo 设计议程的议题
|
||||
|
||||
来自本次调研、建议在 `design/` 或 `adr/` 中跟进:
|
||||
|
||||
1. **`.mq.md` 的双重解析模型** — Markdown CST 与 Marqdo AST 如何共享同一文本、何处分叉。
|
||||
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(后期)** — 文档内求值结果的可验证性。
|
||||
|
||||
---
|
||||
|
||||
## 6. 参考链接
|
||||
|
||||
- 规范:[okf/SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(v0.2)
|
||||
- 仓库:[GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
|
||||
- 博客:[Introducing OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)
|
||||
- 博客:[OKF v0.2 trust signals](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals)
|
||||
|
||||
---
|
||||
|
||||
## 7. 结论
|
||||
|
||||
OKF 证明了一条与 Marqdo 同向的产业判断:**人类可读的 Markdown 可以成为机器与 Agent 的一等交换面**,前提是约定足够小、足够稳,并把信任做成可查询字段而非口头保证。
|
||||
|
||||
Marqdo 比 OKF 多走一步:Markdown 不仅是知识的容器,更是**程序的表面语法**。我们借鉴 OKF 的形态,用作**从源自动生成的依赖清单与项目目录文档**(而非人手配置);同时借鉴「格式而非平台」、路径/链接身份、以及(远期)provenance。语言设计必须单独完成——**可渲染不等于可执行,可执行才是 Marqdo 的终点。**
|
||||
@@ -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` |
|
||||
@@ -0,0 +1,178 @@
|
||||
# Marqdo 参考实现:正经解释器路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已采纳方向 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 目标 | `marqdo run path/to/index.mq.md` 得到真实执行结果;非演示玩具 |
|
||||
| 相关 | [markdown-mapping.md](../design/markdown-mapping.md) · [ADR 0001](../adr/0001-implementation-language.md) · [USTC 编译课 2025](https://ustc-compiler-2025.github.io/homepage/) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何是解释器,而不是 USTC 式「编译到机器码」
|
||||
|
||||
[USTC《编译原理与技术》2025](https://ustc-compiler-2025.github.io/homepage/) 的实验链是经典**编译器**路径:
|
||||
|
||||
```
|
||||
源码 → 词法(Flex) → 语法(Bison) → AST
|
||||
→ 语义 / Light IR → 优化 → 后端(龙芯汇编等)
|
||||
```
|
||||
|
||||
这条路适合 Cminusf 一类「最终变成机器指令」的语言。Marqdo 的产品形态是:
|
||||
|
||||
- 源即 Markdown 文档,**打开即读、运行即算**;
|
||||
- 首要交付是 **从 `index.mq.md` 得到求值结果**(stdout、返回值、模块图),不是龙芯/ x86 二进制;
|
||||
- 语法表面是 Markup-as-Syntax,前端与传统正则+Bison 不同,但**中后端的编译学知识仍然全部用得上**。
|
||||
|
||||
因此:
|
||||
|
||||
| USTC / 龙书阶段 | Marqdo 解释器中的对应 |
|
||||
|-----------------|------------------------|
|
||||
| 词法分析 | **行分类 + 标记词法**(无标记=注释;`#`/`*`/`**`/`>`/`+`/`-`/表…) |
|
||||
| 语法分析 | **结构解析 → Marqdo AST**(可递归下降;不必上 Bison,除非日后自研纯文本方言) |
|
||||
| 语义分析 | 作用域、提升、导入、形参绑定、类型(可后置) |
|
||||
| 中间代码 | **可选**:先树遍历;第二期再降到**字节码** |
|
||||
| 优化 / 目标代码 | **非 v1 目标**;日后若要可另开「编译后端」ADR |
|
||||
|
||||
**结论:做正经解释器 = 把编译前端做扎实 + 把运行时做完整;不是跳过词法语法,也不是一上来 LLVM。**
|
||||
|
||||
权威地图见 [Crafting Interpreters — A Map of the Territory](https://craftinginterpreters.com/a-map-of-the-territory.html):用户眼里的「解释器」内部往往仍含编译到字节码(如 CPython);树遍历是第一期,字节码 VM 是第二期。
|
||||
|
||||
---
|
||||
|
||||
## 2. 推荐总体架构
|
||||
|
||||
```
|
||||
index.mq.md (+ 导入的 .mq.md)
|
||||
│
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 0. 源加载 / 模块图 │ frontmatter `> a.mq.md` → 依赖图
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 1. 词法·行分类 │ 注释行丢弃语义;代码行 → Token 流
|
||||
│ (+ MD 块辅助) │ pulldown-cmark/comrak;+/- 靠行扫描
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 2. 语法分析 │ Token/块 → Marqdo AST
|
||||
│ (递归下降) │ Module / Fun / Stmt / Expr / Branch / Loop …
|
||||
│ │ **不用 Flex/Bison**(见 dependencies.md)
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入模块树(见 module-namespace)
|
||||
│ │ 作用域链、形参、未定义名诊断
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 4a. 树遍历解释器 │ ← Phase I(必须先完成,跑通全部 tests 金样例)
|
||||
│ 或 │
|
||||
│ 4b. 字节码编译+VM │ ← Phase II(性能与「更像真语言实现」)
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
stdout / 返回值 / 退出码
|
||||
```
|
||||
|
||||
Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对齐 **clox(字节码 VM)**(见 [Chunks of Bytecode](https://craftinginterpreters.com/chunks-of-bytecode.html))。这是 Python/Ruby/Lua 主实现走过的正经路径,不是玩具捷径。
|
||||
|
||||
---
|
||||
|
||||
## 3. 各阶段「做满」的标准(反玩具清单)
|
||||
|
||||
### Phase 0 — 工程骨架(正式包,不是 `spike/`)
|
||||
|
||||
- 包名:`marqdo`(`src/marqdo/` 或 `marqdo/`)
|
||||
- CLI:`marqdo run <file.mq.md>`,默认找目录下 `index.mq.md`
|
||||
- 诊断:带文件名、行号、列号
|
||||
- 测试:每个 `tests/{structure,keywords}/*.mq.md` 有期望 stdout(金样例);CI 可跑
|
||||
|
||||
### Phase I — 可运行的语言核心(树遍历)
|
||||
|
||||
必须全部为真实现,禁止「正则特判 hello」:
|
||||
|
||||
1. **词法 / 行分类**:注释与代码严格分离。
|
||||
2. **语法 → AST**:函数、形参、`*` 语句、`**` 返回、`>` 调用、`+` 分支、`-` 循环、表格集合、绑定与 `==`。
|
||||
3. **语义**:提升、嵌套作用域、`##` 私有、frontmatter 导入公有顶层。
|
||||
4. **运行时**:环境、调用栈、值(文/数/表/记录)、内置 `print`。
|
||||
5. **验收**:`tests/structure/*` 与 `tests/keywords/*` 全部 `marqdo run` 通过。
|
||||
|
||||
### Phase II — 字节码 VM(正经化)
|
||||
|
||||
- AST → 线性字节码(栈式 VM 即可,与 clox / [GoAWK 经验](https://benhoyt.com/writings/goawk-compiler-vm/) 同类)
|
||||
- 控制流用跳转指令实现分支/循环
|
||||
- 同一套金样例必须 bit-同结果(回归)
|
||||
- 性能与可调试性(反汇编、栈跟踪)优于 Phase I
|
||||
|
||||
### Phase III — 语言完备(按需)
|
||||
|
||||
- 更完整表达式文法、错误模型、外联围栏 FFI
|
||||
- 生成 OKF 依赖目录
|
||||
- (可选)另一后端:编译到 Python/WASM——**另开 ADR**,不替代自研语义
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 USTC Lab 的知识复用(学什么、不搬什么)
|
||||
|
||||
| 课程内容(摘要) | Marqdo 用法 |
|
||||
|------------------|-------------|
|
||||
| Lab1 词法/语法/AST | **直接对标** Phase I 前端;工具可自研递归下降,不必 Flex/Bison |
|
||||
| Lab2 IR / 访问者 | Phase II 字节码 ≈ 轻量 IR;访问者可用于 AST→字节码 |
|
||||
| Lab3 后端汇编 | **v1 不做**;解释器 VM 代替机器后端 |
|
||||
| Lab4 优化 | Phase II 之后可选;解释器也可做常量折叠等 |
|
||||
|
||||
教材仍可读:龙书、陈意云《编译原理》、课主页参考书;解释器专项读 **Crafting Interpreters**(免费:[craftinginterpreters.com](https://craftinginterpreters.com/))。
|
||||
|
||||
---
|
||||
|
||||
## 5. 实现语言(本路线图默认)
|
||||
|
||||
**参考解释器:Rust**([ADR 0001](../adr/0001-implementation-language.md))。
|
||||
|
||||
- 词法/语法:**自研 + GFM crate**,不用 Flex/Bison([dependencies.md](../design/dependencies.md))。
|
||||
- Python `spike/` 仅作风险探测与算法草稿。
|
||||
- Phase I 树遍历、Phase II 字节码 VM 均在 Rust 中实现。
|
||||
|
||||
---
|
||||
|
||||
## 6. 目录规划(正式代码,非 spike)
|
||||
|
||||
```
|
||||
Cargo.toml
|
||||
src/lex/ parse/ ast/ sema/ interp/ bytecode/ runtime/
|
||||
tests/ # gold.rs + structure|keywords|errors 夹具
|
||||
public/ # 用户可执行文档
|
||||
doc/ # 设计文稿
|
||||
spike/ # Python 存档,非运行时依赖
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 近期里程碑(可执行顺序)
|
||||
|
||||
| 周序 | 交付 | 完成定义 |
|
||||
|------|------|----------|
|
||||
| M0 | 正式包 + CLI 空壳 + 金样例框架 | `marqdo run` 可调用;测试发现「未实现」 | ✅ |
|
||||
| M1 | 词法·行分类 + 最小 AST | 单测覆盖注释/代码行 | ✅ |
|
||||
| M2 | 解析:函数、输出调用、返回 | `hello` + `index` 金样例绿 | ✅ |
|
||||
| M3 | 分支、循环、表格、绑定 | `branch`/`loop`/`collection` 绿 | ✅ |
|
||||
| M4 | 导入与提升 | `with-import` 绿;**宣称 Phase I 达标** | ✅ |
|
||||
| M5 | 字节码设计文档 + 原型 opcode | 核心金样例双后端一致;覆盖表见 [bytecode.md](../design/bytecode.md) | ✅ 原型 |
|
||||
|
||||
**Phase I 完成前,不宣称「语言已实现」。**
|
||||
**仅 hello 特判通过,不算完成。**
|
||||
|
||||
---
|
||||
|
||||
## 8. 成功判据(产品级)
|
||||
|
||||
在仓库根或任意含 `index.mq.md` 的目录:
|
||||
|
||||
```bash
|
||||
marqdo run tests/structure/nested-call.mq.md
|
||||
# 或
|
||||
marqdo run tests/structure/import/main.mq.md
|
||||
```
|
||||
|
||||
输出与金样例一致;错误带位置;新增语法必须加金样例与单测。这才是「一门解释型语言」的最低合格线。
|
||||
@@ -0,0 +1,220 @@
|
||||
# 下一阶段:从玩具到可用语言
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **进行中**(P3-D1–D3 live view 断点 v1) |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 目标 | 交互 I/O、可信诊断、可生长标准库;view 渐进成为调试宿主 |
|
||||
| 相关 | [interpreter.md](interpreter.md) · [keywords.md](../design/keywords.md) · [pipeline-debug.md](../design/pipeline-debug.md) · [view.md](../design/view.md) · [view-debug.md](../design/view-debug.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 现状快照(决策依据)
|
||||
|
||||
| 能力 | 现状 | 结论 |
|
||||
|------|------|------|
|
||||
| **`print`** | 树遍历 + 字节码均可用 | 够用 |
|
||||
| **`input`** | CLI 双后端 + `--stdin-file`;frontmatter `stdin:`/`输入:`;live view 表单覆盖;无预置时 capture 提示补线 | **P1a + P1b 完成** |
|
||||
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
|
||||
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
|
||||
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
|
||||
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
|
||||
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
|
||||
|
||||
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
|
||||
|
||||
---
|
||||
|
||||
## 1. 轻重缓急(总序)
|
||||
|
||||
```text
|
||||
P0 诊断加固(短、撬动后续一切)
|
||||
P1 输入补完(先 CLI,再 view)
|
||||
P2 最小标准库(内置 + 可选 .mq.md 库)
|
||||
P3 view 调试(断点 / 单步)—— 在 P0 之后分期,勿一上来做 DAP
|
||||
```
|
||||
|
||||
| 优先级 | 主题 | 为何此刻 | 不做的代价 |
|
||||
|--------|------|----------|------------|
|
||||
| **P0** | 诊断完备度 | 便宜;给金样例、字节码、调试打地基 | 断点停错行;双后端错误体验分裂 |
|
||||
| **P1** | `input` | 「真语言」最低交互面;已有半截实现 | 只能写纯计算/打印 demo |
|
||||
| **P2** | 标准库 | 无库则用户无法写稍大程序 | 人人自造轮子、示例膨胀 |
|
||||
| **P3** | 前端调试 | 差异化(文档即调试);成本最高 | view 仍停留在「跑完看 stdout」 |
|
||||
|
||||
**原则:** 先让 **CLI 树遍历**成为完备参考实现;字节码跟进同语义;view 只接「已有事件/钩子」,不单独发明第二套语义。
|
||||
|
||||
---
|
||||
|
||||
## 2. P0 — 诊断与错误模型(约 3–7 天)
|
||||
|
||||
### 目标
|
||||
|
||||
所有用户可见失败统一为:
|
||||
|
||||
```text
|
||||
path:line:col: message
|
||||
```
|
||||
|
||||
树遍历与字节码**同文案、同位置粒度(至少语句级)**;金样例断言位置而不只子串。
|
||||
|
||||
### 工作项
|
||||
|
||||
1. **统一出口**
|
||||
- 解析侧尽量只产 `Diagnostic`(减少裸 `bail!("7:1: …")`)。
|
||||
- 字节码编译/VM:错误携带 `Span`(或指令 → 源行映射)。
|
||||
2. **位置粒度**
|
||||
- 短期:保持「语句起点」亦可;中期:为 `Expr`/`CallExpr` 补 `span`,让「未定义名」落在标识符上。
|
||||
3. **金样例**
|
||||
- `tests/errors/*`:断言完整 `path:line:col` 前缀(或相对路径规范化后的形式)。
|
||||
- 补:类型错误、除零、循环条件、capture 下 `input` 等。
|
||||
4. **文档**
|
||||
- 更新 [pipeline-debug.md](../design/pipeline-debug.md):错误码/严重级别可列为 P0.5(可选 `E0001` 一类,不阻塞)。
|
||||
|
||||
### 完成定义
|
||||
|
||||
- `cargo test`:errors 金样例含位置。
|
||||
- 同一 `.mq.md` 在 `--backend tree|bytecode` 下诊断一致(允许实现细节差异写进豁免表)。
|
||||
- view 执行失败区仍可读,路径无 `\\?\`。
|
||||
|
||||
### 刻意不做
|
||||
|
||||
- IDE DAP、完整堆栈 UI、sourcemap 可视化编辑器。
|
||||
|
||||
---
|
||||
|
||||
## 3. P1 — 输入(约 1–2 周)
|
||||
|
||||
分两轨:**CLI 必须先绿**;**view 交互后做**。
|
||||
|
||||
### P1a — CLI 完备(高优先级)
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 树遍历 | 已实现 stdin;补 `tests/keywords/input.mq.md`(用管道喂入) |
|
||||
| 字节码 | 增加 `Op::Input`(或等价 host call);与树同语义;capture 下同样拒绝或改走注入 API |
|
||||
| 文档/用户站 | `public/keywords/input.mq.md`;说明「view 默认无交互 stdin」 |
|
||||
|
||||
完成定义:`echo Alice | marqdo run …` 与字节码后端输出一致;金样例稳定。
|
||||
|
||||
### P1b — view / 静态站中的输入(中优先级,接在 P1a 后)
|
||||
|
||||
当前 `run_file_capture` **不能**接真实 stdin——这是设计,不是偶然 bug。
|
||||
|
||||
推荐路径(由易到难):
|
||||
|
||||
1. **脚本化注入(无 UI)**
|
||||
- `marqdo run --stdin-file answers.txt` 或 frontmatter/`---` 旁测数据。
|
||||
- view:执行前提供「预置输入行」文本框,一次性灌入队列。
|
||||
2. **实时交互(live view)**
|
||||
- 执行到 `input` → 暂停 → HTTP/WS 返回 prompt → 用户提交一行 → 继续。
|
||||
- 依赖 P3 的「可暂停执行」钩子;可与断点共用会话模型。
|
||||
3. **静态 `view output`**
|
||||
- 无服务器则只支持预置输入或跳过并标明 `input skipped`。
|
||||
|
||||
完成定义:live `marqdo view` 下至少一个带 `input` 的示例可点按跑通;静态导出行为有文档。
|
||||
|
||||
---
|
||||
|
||||
## 4. P2 — 标准库(约 2–3 周,可与 P1b/P3 前半重叠)
|
||||
|
||||
### 分层
|
||||
|
||||
```text
|
||||
L0 内置函数(解释器内) len / str / int / float? / type?
|
||||
L1 标准库模块(.mq.md) 文本、表/集合小工具;官方路径如 lib/ 或 std/
|
||||
L2 生态约定 catalog 收录;用户站专章
|
||||
```
|
||||
|
||||
### 建议落地顺序
|
||||
|
||||
| 迭代 | 内容 | 依据 |
|
||||
|------|------|------|
|
||||
| **S0** | `len`(文本/表)、`str`、`int` | keywords.md 已列候选;字节码已有闲置 `Op::Len` 可接线 |
|
||||
| **S1** | 表工具:取列、行数;字符串 trim/split(先内置或纯 mq 实现二选一) | 文档型语言高频 |
|
||||
| **S2** | 官方 `lib/` 或 `std/` + 导入约定(仍可用 frontmatter;或日后 `> std/text.mq.md`) | 可生长而不破现有导入 |
|
||||
| **S3** | 错误类型约定(如非法 `int` 文本 → 诊断) | 依赖 P0 |
|
||||
|
||||
### 完成定义(S0)
|
||||
|
||||
- 金样例 + 双后端;`public/` 有对应介绍页。
|
||||
- 不引入 `if`/`while` 英文关键字(控制流仍归 Markdown 标记)。
|
||||
|
||||
### 刻意不做(本阶段)
|
||||
|
||||
- 完整面向对象、包管理器、异步 I/O、HTTP 客户端(可列远期)。
|
||||
|
||||
---
|
||||
|
||||
## 5. P3 — 前端成为调试机构(约 3–6 周,分里程碑)
|
||||
|
||||
**不要从 DAP/VS Code 插件开干。** view 已有 Structure / Source / Execution,是天然宿主。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
P0loc[P0 可信位置] --> Pause[语句边界暂停钩子]
|
||||
Pause --> Sess[调试会话 API]
|
||||
Sess --> UI[view 断点与单步 UI]
|
||||
UI --> DAP[可选 DAP 适配]
|
||||
```
|
||||
|
||||
| 里程碑 | 交付 | 依赖 |
|
||||
|--------|------|------|
|
||||
| **D0** | 语句级源映射(树优先;字节码指令→行) | P0 |
|
||||
| **D1** | 运行时钩子:进入语句前可 pause;`--trace-eval` 结构化事件(JSON 行) | D0 |
|
||||
| **D2** | 进程内调试会话:设/清断点、continue、step over(先树遍历) | D1 |
|
||||
| **D3** | **view debug 模式**:源码行点击断点;高亮当前行;侧栏 locals/栈;与文档模式切换 | D2 + 少量 JS 或服务端推进 |
|
||||
| **D4** | 与 P1b 合流:`input` 暂停复用同一会话 | P1b |
|
||||
| **D5**(可选) | DAP 薄适配,供外部 IDE | D2 稳定后 |
|
||||
|
||||
### 完成定义(D3 即「可用调试」)
|
||||
|
||||
- 用户能在 `marqdo view` 对某 `.mq.md` 设断点、单步、看变量。
|
||||
- 文档站默认模式不变(一次执行);debug 为显式开关。
|
||||
- 断点命中行与 P0 诊断行一致(允许文档说明「语句起点」语义)。
|
||||
|
||||
### 风险与边界
|
||||
|
||||
- 静态 `gh-pages` **无法**真断点(无常驻 VM);调试仅 **live view**(或未来 WASM 解释器)。
|
||||
- 字节码调试可晚于树遍历一个迭代。
|
||||
|
||||
---
|
||||
|
||||
## 6. 推荐排期(可执行流程)
|
||||
|
||||
按「每段都可合并、可演示」切周,避免大爆炸:
|
||||
|
||||
| 周序 | 主题 | 可合并交付 |
|
||||
|------|------|------------|
|
||||
| **W1** | P0 诊断统一 + errors 金样例加固 | 双后端错误位置一致 |
|
||||
| **W2** | P1a `input` 字节码 + 管道金样例 + 用户文档 | CLI 交互闭环 |
|
||||
| **W3** | P2-S0 `len`/`str`/`int` + 样例 | 「有点像语言」的第一批库 |
|
||||
| **W4** | P1b 预置输入(view 文本框 / `--stdin-file`) | view 可跑含 input 的 demo |
|
||||
| **W5–W6** | P3-D0–D2 暂停与会话 | 无 UI 也能用 API/CLI 单步 |
|
||||
| **W7–W8** | P3-D3 view 断点 UI + D4 与 input 暂停 | **调试机构**第一版 |
|
||||
| **并行/随后** | P2-S1/S2 扩库;P3-D5 DAP | 按反馈加 |
|
||||
|
||||
若人力紧:**砍掉顺序为 D5 → S2 花活 → 字节码调试**;**不可砍:P0、P1a、P2-S0、D3 之前的 D0–D2。**
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收总表(「真正可用」最低线)
|
||||
|
||||
1. **I/O**:CLI 上 `print`/`input` 双后端一致;view 至少支持预置或交互输入之一。
|
||||
2. **错误**:失败必有稳定位置;常见错误有金样例;用户站不靠「瞎猜 stderr」。
|
||||
3. **库**:至少 `len`/`str`/`int` 可用并有文档。
|
||||
4. **调试**:live view 可断点 + 单步 + 看当前绑定(树遍历即可宣称 v1)。
|
||||
5. **不破坏**:现有 `tests/` 金样例与 `public/` 用户站回归绿。
|
||||
|
||||
---
|
||||
|
||||
## 8. 文档与工程动作(开工时)
|
||||
|
||||
1. 本文件定为「下一阶段宪法」;开工后把各 P 拆到 `doc/design/` 子设计(`input-interactive.md`、`stdlib.md`、`view-debug.md`)。
|
||||
2. 每个里程碑:金样例 → 实现 → `public/` 更新 →(若行为用户可见)再发版 / 刷 `gh-pages`。
|
||||
3. 版本建议:P1a+P0 可打 `v0.0.4`;P2-S0 打 `v0.0.5`;P3-D3 打 `v0.1.0`(「可用调试」语义升级)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话路线
|
||||
|
||||
**先把错误说准、把输入在 CLI 做完,再长出最小标准库;最后把现有 view 升级成可暂停的调试宿主——而不是先做 IDE 插件或大而全标准库。**
|
||||
@@ -0,0 +1,167 @@
|
||||
# 对象继承语法(未来规划)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **I0–I3 已落地**(显式父构造约定;**不做**隐式 auto-super) |
|
||||
| 日期 | 2026-08-10 |
|
||||
| 相关 | [objects.md](../design/objects.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [keywords.md](../design/keywords.md) |
|
||||
| 提案语法 | `# 子类 = > 父类` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
今日 [`objects.md`](../design/objects.md) 明确非目标:**继承 / 接口 / 可见性**。
|
||||
实际扩展(如 `# agent` / `# llm`)靠「再写一个对象 + 组合句柄」,缺少:
|
||||
|
||||
- 复用父构造 / 父方法而不复制 `.mq.md`
|
||||
- 子类型在 `_type` 链上解析方法
|
||||
- 与 Markdown 标题体系一致的、可读的继承声明
|
||||
|
||||
需要一种**不引入 `class`/`extends` 关键字**、且与现有 `=`(绑定)与 `>`(调用)语义兼容的写法。
|
||||
|
||||
---
|
||||
|
||||
## 2. 锁定语法(提案)
|
||||
|
||||
```markdown
|
||||
# 子类 = > 父类
|
||||
```
|
||||
|
||||
| 片段 | 既有含义 | 组合后含义 |
|
||||
|------|----------|------------|
|
||||
| `# 子类` | 定义对象 / 类型 | 子类型名 |
|
||||
| `=` | 绑定 / 赋值 | 类型关系写在「类型定义槽」上 |
|
||||
| `> 父类` | 调用(此处为类型名) | **基类引用**(不是构造实例) |
|
||||
|
||||
可选带参基类(若基类本身是泛化构造,v1 可暂不支持):
|
||||
|
||||
```markdown
|
||||
# 特化智能体 = > 智能体
|
||||
```
|
||||
|
||||
中英对称:
|
||||
|
||||
```markdown
|
||||
# Child = > Parent
|
||||
# 子类 = > 父类
|
||||
```
|
||||
|
||||
### 2.1 为何不冲突
|
||||
|
||||
1. **今日** `# 名` 后接的是构造体正文,不是 `` `# 名 = …` `` 标题行。
|
||||
2. **语句绑定**是 `*…*` 或行内 `` `x` = ``,不是 ATX `#` 标题。
|
||||
3. **`> 父类` 在标题行**出现在 `=` 右侧:解析器可把「`#` 标题含 `=` 与 `>`」识别为**类型声明**,而非执行构造。
|
||||
4. 真正构造实例仍是正文或 `# main` 里的 `` `x` = > 子类 … ``。
|
||||
|
||||
反例(仍是今日语义,不变):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`a` = > 父类 *
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 运行时语义(草案)
|
||||
|
||||
### 3.1 方法解析
|
||||
|
||||
实例 map 仍有 `_type` = 构造时的类型名(子类名)。
|
||||
|
||||
查找 `` `obj`.方法 ``:
|
||||
|
||||
1. 在 `_type` 对应对象上找 `## 方法`
|
||||
2. 未找到 → 沿 **基类链** 查找
|
||||
3. 仍无 → 报错(带类型链)
|
||||
|
||||
构造:
|
||||
|
||||
1. 若子类构造体未显式处理,可先调基类构造(见开放点:是否自动 `super`)。
|
||||
2. 返回 map 的 `_type` = **最具体子类名**(不是父类名)。
|
||||
|
||||
### 3.2 子类正文
|
||||
|
||||
```markdown
|
||||
# 工蜂 = > 智能体
|
||||
|
||||
## 采蜜
|
||||
+ `花`
|
||||
|
||||
*`out` = > `self`.step task=`花` *
|
||||
**`out`**
|
||||
```
|
||||
|
||||
- 子类可定义新 `##`
|
||||
- 可覆盖同名 `##`(子类优先)
|
||||
- 站立提示 / 字段约定:文档层说明,v1 不引入可见性关键字
|
||||
|
||||
### 3.3 多继承
|
||||
|
||||
**v1 不支持。** 一个 `# 子 = > 父` 仅一条基类。混入用组合(句柄字段)而非多 `>`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 解析与 AST
|
||||
|
||||
标题形态需在 [markdown-mapping.md](../design/markdown-mapping.md) / parse 中新增一种 object decl:
|
||||
|
||||
| 字段 | 值 |
|
||||
|------|-----|
|
||||
| `name` | 子类 |
|
||||
| `base` | 父类(标识符) |
|
||||
| `body` | 与今日 object body 相同 |
|
||||
|
||||
歧义处理:
|
||||
|
||||
- `# Foo = 1` → **非法**(右侧必须是 `> 类型名`)
|
||||
- `# Foo = > bar.baz` → v1 **非法**(基类须为已定义对象名,不走任意调用表达式)
|
||||
- 基类尚未定义 → Pass1 收集后解析;循环继承报错
|
||||
|
||||
---
|
||||
|
||||
## 5. 与标准库 / 扩展
|
||||
|
||||
| 用途 | 例子 |
|
||||
|------|------|
|
||||
| 扩展官方智能体 | `# 客服 = > agent` / `# 客服 = > 智能体` |
|
||||
| 扩展 llm 句柄 | 一般不必要;优先组合 |
|
||||
| 用户域模型 | `# 订单服务 = > 服务基类` |
|
||||
|
||||
官方 `lib/*` 仍以自由函数为主;继承主要服务 `ext/` 与用户对象。
|
||||
|
||||
---
|
||||
|
||||
## 6. 推荐落地顺序
|
||||
|
||||
```text
|
||||
I0 语法 + AST + 金样(解析/循环继承错误) ✅
|
||||
I1 方法解析沿基类链;构造 _type=子类 ✅
|
||||
I2 覆盖方法;文档更新 objects.md ✅
|
||||
I3 显式父构造约定(**不做**隐式 auto-super) ✅
|
||||
```
|
||||
|
||||
验收:
|
||||
|
||||
1. 无继承文件行为不变。
|
||||
2. 子类实例能调父类 `##`;覆盖后只走子类。
|
||||
3. `` # A = > B `` / `` # B = > A `` 诊断清晰。
|
||||
4. Skill / 金样:`tests/structure/inherit-*.mq.md`(含显式 `` `self` = > Parent ``)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 开放点
|
||||
|
||||
1. ~~**隐式 super**~~ → **不做**:子类构造体不自动跑父构造。需要父初始化时正文写 `` `self` = > 父类 … `` 再改字段后 `**`self`**`;构造完成时 `_type` 仍为最具体子类名。
|
||||
2. 中英基类别名:`> agent` 与 `> 智能体` 是否同一对象(取决于模块导出)。
|
||||
3. 继承是否写入 OKF Module 页(catalog 展示 `extends`)——可随 O3/O4 增强。
|
||||
|
||||
---
|
||||
|
||||
## 8. 非目标
|
||||
|
||||
- 接口 / 抽象方法 / 可见性(`public`)
|
||||
- 多继承、mixin 关键字
|
||||
- 用继承替代 `plan` 工作簿接力
|
||||
- 把 `# 子 = > 父` 解析成「定义时立即构造父实例」
|
||||
@@ -0,0 +1,108 @@
|
||||
# OKF 相近任务命中
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **A 规范句 + B aliases + C 父裁决(soft_match)+ D 本地 n-gram `near` 已落地**;E dense embedding 仍非目标 |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 相关 | [okf.md](../design/okf.md) §7 · [ext-agent-plan.md](../design/ext-agent-plan.md) §4.2 · [ext-agent.md](../design/ext-agent.md) |
|
||||
| 触发观察 | `man-test`:相近 goal 生成两份独立 resource |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
v1 agent-kb **精确命中仍是默认快路径**:
|
||||
|
||||
1. `normalize_goal`:去首尾空白、合并连续空白(**不做**近义改写)。
|
||||
2. `sig` = 规范化字符串的稳定短哈希;`slug` = 可读路径名。
|
||||
3. `agent_kb_lookup`:精确 → aliases → canonicalize → **本地 n-gram `near`(默认开)**;仍 miss 且 `plan soft_match=True` 时父裁决 REUSE/NEW(候选为排序 near 列表)。
|
||||
|
||||
历史痛点(已由 A/B/C/D 缓解):
|
||||
|
||||
| goal(调用方输入) | 旧行为 |
|
||||
|--------------------|--------|
|
||||
| `你是一个智能体,帮我规划明天的行程` | 独立 slug,与下方不命中 |
|
||||
| `帮我规划明天的行程` | 另一份 resource |
|
||||
| `帮我规划明天行程` | 又一份(近句碎片) |
|
||||
|
||||
调用方直觉:「这不是同一件事吗?」——现可用 canonicalize、默认 `near_match`,或显式 `soft_match` 父裁决。
|
||||
|
||||
---
|
||||
|
||||
## 2. 为何精确指纹仍优先
|
||||
|
||||
| 理由 | 说明 |
|
||||
|------|------|
|
||||
| 假阳性代价高 | 错复用旧工作簿比多建一个文件更糟 |
|
||||
| 可审计 | `sig` 可复算;`near` 留下 `match`/`score` |
|
||||
| 哲学 | 多轮 = 子文件接力 + OKF 索引,不是聊天式模糊检索 |
|
||||
|
||||
**结论:** 精确命中长期保留为**默认快路径**;`near` 是可关闭的第四趟(`near_match=False`)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 已落地层
|
||||
|
||||
### A. 规范化后再精确命中 — **已落地**
|
||||
|
||||
`agent_kb_canonicalize`:剥站立前缀、去尾标点;`match: canonical`。
|
||||
|
||||
### B. 别名 / 标签表 — **已落地**
|
||||
|
||||
Task FM `aliases:`;`match: alias`。
|
||||
|
||||
### C. 父智能体软裁决 — **已落地(默认关)**
|
||||
|
||||
`plan soft_match=True`:`agent_kb_near_match` 排序候选(含 `score`;空则退回 `list_tasks`)→ 父 `DECISION: REUSE` + `SLUG:` 或 `DECISION: NEW`。
|
||||
|
||||
### D. 本地字符 bigram + 余弦 — **已落地(默认开)**
|
||||
|
||||
| | |
|
||||
|--|--|
|
||||
| 做法 | 稀疏词法向量化(**不是** embedding 模型):canonicalize 后对 goal 与 Task `title\|description\|aliases` 建字符 bigram 词袋,算余弦 |
|
||||
| API | `agent_kb_near_match`;`agent_kb_lookup` 第四趟 |
|
||||
| 参数 | `near_match`/`近义命中` 默认 `True`;`near_threshold`/`近义阈值` 默认 `0.78` |
|
||||
| 痕迹 | `match: near` + `score`;`cache=soft-hit`;可写 alias |
|
||||
|
||||
术语:这是 **sparse lexical near-match**,勿宣传为向量库 / embedding 检索。
|
||||
|
||||
### E. Dense embedding(可选远期)
|
||||
|
||||
远程 / 本地 dense 向量与 ANN **仍非本仓默认目标**;仅当 D 在真实包体量下证据不足时再评估。
|
||||
|
||||
---
|
||||
|
||||
## 4. 演进顺序
|
||||
|
||||
```text
|
||||
精确 sig(永不删除)
|
||||
→ A 规范句 + B aliases(已落地)
|
||||
→ C soft_match 父裁决(已落地,默认关)
|
||||
→ D 本地 n-gram near(已落地,默认开)
|
||||
→ E dense embedding(仅有证据再开)
|
||||
```
|
||||
|
||||
验收原则:
|
||||
|
||||
1. `near_match=False` 时与无 near 行为一致;`force`/`optimize` 仍跳过 reuse。
|
||||
2. 软/近义命中留下 `cache=soft-hit` / `match` / 可选 `score`。
|
||||
3. 假阳性可被 `force=True` / 显式 `workbook=` / 调高 `near_threshold` 覆盖。
|
||||
4. 实现仍在 **agent 插件 + `ext/ai`**,不进核心 `src/host`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 调用方建议
|
||||
|
||||
- 固定规范 goal;站立语可由 canonicalize 剥掉。
|
||||
- 近句碎片依赖默认 `near_match`;字面差更大时开 `soft_match=True`。
|
||||
- 策展:合并重复 task,次要措辞写入 `aliases`(O4)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 与现有路线图的关系
|
||||
|
||||
| 条目 | 关系 |
|
||||
|------|------|
|
||||
| [okf.md](../design/okf.md) O2 / O5 | 精确 reuse + A/B/C/D;E dense 仍待 |
|
||||
| [okf.md](../design/okf.md) O4 | `kb query` / 策展可继续扩 aliases |
|
||||
| [ext-agent-plan.md](../design/ext-agent-plan.md) | 多轮仍只走子文件接力;软命中只影响「选哪个子文件」 |
|
||||
@@ -0,0 +1,303 @@
|
||||
# 表格语义打磨:列表 · 字典 · 嵌套 · 脚注取元(未来规划)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **T0–T5 已落地**(单元格表达式见 [table-cell-expressions.md](../design/table-cell-expressions.md)) |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 相关 | [markdown-mapping.md](../design/markdown-mapping.md) §9 · [table-cell-expressions.md](../design/table-cell-expressions.md) · [objects.md](../design/objects.md) · [stdlib.md](../design/stdlib.md)(`lib/table`) · [keywords.md](../design/keywords.md) |
|
||||
| 现状金样 | [tests/structure/collection.mq.md](../../tests/structure/collection.mq.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题
|
||||
|
||||
### 1.1 今日表格 =「竖表 → 列表」
|
||||
|
||||
```markdown
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
```
|
||||
|
||||
语义(已落地):绑定为**列表**(列值);表头名供 `` [`果`](`篮子`) `` 遍历。
|
||||
单列表头是当前唯一一等集合外形;**没有**一等「横表 = 字典」。
|
||||
|
||||
### 1.2 缺字典外形与嵌套
|
||||
|
||||
用户期望:GFM 表的两种几何对应两种结构,并允许嵌套——这样「多行表格」才有稳定、可教的含义。
|
||||
|
||||
### 1.3 不能按下标 / 键直接取元
|
||||
|
||||
今日要从列表取第 *n* 项,往往只能遍历或走 `lib/table`(`row_at` 等),**语言级**缺少与 Markdown 同构的取元语法。字典亦然。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标
|
||||
|
||||
1. **竖表**继续表示列表(兼容现有金样)。
|
||||
2. **横表**(多列表头 + 数据行)表示字典及「字典 ↔ 列表」嵌套。
|
||||
3. 用 **Markdown 脚注外形** 做列表下标 / 字典键的取元(表达式级)。
|
||||
4. 不引入 `[]` 下标关键字风暴;少而精,与「标记即语法」一致。
|
||||
|
||||
非目标:
|
||||
|
||||
- 完整电子表格公式引擎
|
||||
- 用表声明对象字段 schema(仍见 objects 非目标;与数据集合分开)
|
||||
- 破坏现有单列竖表金样
|
||||
|
||||
---
|
||||
|
||||
## 3. 表格几何 → 值(锁定提案)
|
||||
|
||||
判定在 **绑定右侧的 GFM 表** 上做(`` `名` = `` 后接表)。
|
||||
|
||||
### 3.1 竖表 → 列表(现状,保留)
|
||||
|
||||
**形状:** 恰好 **1** 列。
|
||||
|
||||
```markdown
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
```
|
||||
|
||||
| 结果 | 说明 |
|
||||
|------|------|
|
||||
| 值 | `List`:`["苹果","梨","桃"]` |
|
||||
| 表头 | 元素逻辑名(foreach 绑定名);不进入列表元素 |
|
||||
|
||||
### 3.2 横表单数据行 → 字典
|
||||
|
||||
**形状:** ≥2 列,且 **恰好 1 行数据**(表头 + 分隔 + 一行)。
|
||||
|
||||
```markdown
|
||||
`分类` =
|
||||
|
||||
| 苹果 | 黄瓜 | 鼠标 |
|
||||
|------|------|------|
|
||||
| 水果 | 蔬菜 | 数码用品 |
|
||||
```
|
||||
|
||||
| 结果 | 说明 |
|
||||
|------|------|
|
||||
| 值 | `Map`:`苹果→水果`, `黄瓜→蔬菜`, `鼠标→数码用品` |
|
||||
| 键 | 表头单元格文本(规范化空白后) |
|
||||
| 值 | 唯一数据行对应列 |
|
||||
|
||||
### 3.3 横表多数据行 → 字典套列表(默认)
|
||||
|
||||
**形状:** ≥2 列,且 **≥2 行数据**。
|
||||
|
||||
```markdown
|
||||
`货架` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 红富士 | 青瓜 |
|
||||
| 嘎啦 | 黄瓜条 |
|
||||
```
|
||||
|
||||
**默认语义(锁定):列向聚合**
|
||||
|
||||
```text
|
||||
{
|
||||
"苹果": ["红富士", "嘎啦"],
|
||||
"黄瓜": ["青瓜", "黄瓜条"]
|
||||
}
|
||||
```
|
||||
|
||||
即:**键 = 表头,值 = 该列数据行组成的列表**。
|
||||
这与竖表「一列 = 一列表」在多列时自然推广,嵌套外形稳定。
|
||||
|
||||
**备选语义(不默认):行向记录列表**
|
||||
|
||||
```text
|
||||
[
|
||||
{"苹果":"红富士","黄瓜":"青瓜"},
|
||||
{"苹果":"嘎啦","黄瓜":"黄瓜条"}
|
||||
]
|
||||
```
|
||||
|
||||
更像 SQL / CSV。若未来需要,用显式标记区分(见 §3.5),**不得**与默认列向字典静默混用。
|
||||
|
||||
### 3.4 单列多行 vs 多列
|
||||
|
||||
| 列数 | 数据行 | 值类型 |
|
||||
|------|--------|--------|
|
||||
| 1 | ≥0 | `List` |
|
||||
| ≥2 | 1 | `Map`(标量值) |
|
||||
| ≥2 | ≥2 | `Map`(值均为 `List`) |
|
||||
| ≥2 | 0 | `Map`(键存在,值空列表或错误——开工时锁定为「空列表」) |
|
||||
|
||||
### 3.5 显式形态标记(行向记录)— **已落地**
|
||||
|
||||
首列表头为下列之一时,整表改为**行向**(不静默混用列向默认):
|
||||
|
||||
| 标记 | 说明 |
|
||||
|------|------|
|
||||
| `@` | ASCII 短标记 |
|
||||
| `行` | 中文 |
|
||||
| `row` | 英文 |
|
||||
|
||||
规则:
|
||||
|
||||
1. 标记列**不进入**记录字段(数据格可写行号给人看)。
|
||||
2. 其余列 → 每行一个 `Map`;整体为 `List`。
|
||||
3. 须至少有一列字段(仅 `| 行 |` → 诊断)。
|
||||
4. 数据行数任意(含 0 → 空列表;1 行仍是 `List` of one `Map`,不是列向 `Map`)。
|
||||
|
||||
```markdown
|
||||
`订单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
| 2 | 梨 | 3 |
|
||||
```
|
||||
|
||||
→ `[{品名: 苹果, 数量: 2}, {品名: 梨, 数量: 3}]`。取元:`` `订单`[^1][^品名] ``。
|
||||
|
||||
---
|
||||
|
||||
## 4. 脚注取元(提案)
|
||||
|
||||
### 4.1 为何用脚注外形
|
||||
|
||||
- Markdown 已有 `[^…]` 引用形态,读者不陌生。
|
||||
- 避免 `篮子[0]` 与链接 / 图片语法纠缠。
|
||||
- 与「标识符反引号」组合清晰:`` `篮子`[^1] ``。
|
||||
|
||||
### 4.2 列表:按下标
|
||||
|
||||
```markdown
|
||||
*`第一` = `篮子`[^1] *
|
||||
> print text=`第一`
|
||||
```
|
||||
|
||||
| 约定 | 选择(提案) |
|
||||
|------|----------------|
|
||||
| 下标基准 | **1-based**(与 Markdown / 人类表格行语感一致;脚注 `[^1]` 即第一项) |
|
||||
| `[^0]` | 报错(保留 0 不用)或日后表示「最后一项」—— v1 **报错** |
|
||||
| 越界 | 清晰诊断 `path:line:col` |
|
||||
|
||||
### 4.3 字典:按键
|
||||
|
||||
键为脚注标签文本(推荐与表头一致;**允许纯数字键**,如基矢标签 `00`)。基名可写 `` `概率`[^00] `` 或 `` 概率[^00] ``(紧跟 `[^` 时可省略反引号):
|
||||
|
||||
```markdown
|
||||
*`种` = `分类`[^苹果] *
|
||||
*`p00` = `概率`[^00] *
|
||||
> print text=`种`
|
||||
```
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| `[^苹果]` | 键文本 `苹果` |
|
||||
| `[^00]` / `[^1]` | 键文本 `00` / `1`(**不是**「第 n 个 map 条目」) |
|
||||
| 含空格的键 | 允许 `[^数码用品]`;极端键用引号策略开工前定 |
|
||||
| 缺失键 | 报错或 `None`——建议 v1 **报错**(少静默) |
|
||||
|
||||
### 4.4 嵌套取元
|
||||
|
||||
列向字典套列表:
|
||||
|
||||
```markdown
|
||||
*`货架` = …多行横表… *
|
||||
*`第一种苹果` = `货架`[^苹果][^1] *
|
||||
```
|
||||
|
||||
从左到右:先键、再下标。
|
||||
类型不对(对 List 用非数字键名脚注)→ 诊断。Map 上的纯数字标签按**键名**解析。
|
||||
|
||||
### 4.5 与 GFM「定义脚注」正文
|
||||
|
||||
标准 Markdown 文末 `[^1]: 说明` 是**注释/文献**,不是取元。
|
||||
|
||||
规则:
|
||||
|
||||
- **表达式位置**的 `` `名`[^…] `` → 取元。
|
||||
- **文末脚注定义块** → 仍作注释(或不支持,避免混用)。
|
||||
- 不要求为每个 `[^1]` 写定义;Marqdo 取元**不依赖**定义块。
|
||||
|
||||
### 4.6 与 `lib/table` 关系
|
||||
|
||||
| 层 | 职责 |
|
||||
|----|------|
|
||||
| 语言脚注取元 | 一等、短、金样覆盖 |
|
||||
| `lib/table` | 行列切片、整表变换;可逐步把 `row_at` 文档改为「等价于脚注」 |
|
||||
|
||||
---
|
||||
|
||||
## 5. foreach 与字典
|
||||
|
||||
今日:`` [果](篮子) `` / `` [`果`](`篮子`) `` 遍历列表(裸名与反引号均可)。
|
||||
|
||||
扩展草案:
|
||||
|
||||
| 集合 | 遍历 |
|
||||
|------|------|
|
||||
| List | 不变,项为元素 |
|
||||
| Map | `` [`键`](`映射`) `` 遍历键;或 `` [`对`](`映射`) `` 若引入对类型—— v1 建议 **遍历键**,值用 `` `映射`[^…] `` / 辅助 |
|
||||
|
||||
具体键值对遍历语法开工前写一小段进 mapping;避免与链接外形 `` [`x`](`y`) `` 冲突(今日已是 foreach)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 推荐落地顺序
|
||||
|
||||
```text
|
||||
T0 横表单行 → Map;金样;竖表回归 ✅
|
||||
T1 横表多行 → Map of List(列向);嵌套金样 ✅
|
||||
T2 脚注取元:List [^n]、Map [^键]、链式 ✅
|
||||
T3 文档:markdown-mapping §9;Skill / examples;table 库 ✅
|
||||
T4 行向记录表:首列 `@` / `行` / `row` ✅
|
||||
T5 数据单元格 = 表达式(同调用实参值语法) ✅
|
||||
```
|
||||
|
||||
验收:
|
||||
|
||||
1. `tests/structure/collection.mq.md` 行为不变。
|
||||
2. 新金样:`collection-map.mq.md`、`collection-map-list.mq.md`、`footnote-index.mq.md`。
|
||||
3. 错误下标 / 缺键带 `line:col`。
|
||||
4. 双后端(tree / bytecode)一致。
|
||||
5. **T5:** 单元格 `` `var` `` / 算术;URL 与 `gpt-4o-mini` 仍为文本;设计见 [table-cell-expressions.md](../design/table-cell-expressions.md)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 教学对照(写入 Skill 的素材)
|
||||
|
||||
| 几何 | 含义 | 取元 |
|
||||
|------|------|------|
|
||||
| 单列竖表 | 列表 | `` `a`[^1] `` |
|
||||
| 多列 + 一行 | 字典 | `` `m`[^键] `` |
|
||||
| 多列 + 多行 | 字典 → 列表 | `` `m`[^键][^1] `` |
|
||||
| 首列 `@`/`行`/`row` | 记录列表 | `` `r`[^1][^字段] `` |
|
||||
|
||||
竖表表头是「元素名」;横表表头是「键名」——几何决定角色,减少「这张表到底是啥」的歧义。
|
||||
|
||||
---
|
||||
|
||||
## 8. 开放点
|
||||
|
||||
1. 表头重复列名:报错还是后缀 `_2`?建议 **报错**。
|
||||
2. 数字表头:字典键为文本 `"1"` 还是整数?建议 **文本**(与单元格一致)。
|
||||
3. 脚注 1-based 与宿主语言习惯(0-based)的文档警示。
|
||||
4. 字节码:`Index` / `KeyGet` 操作码是否与 T2 同批。
|
||||
|
||||
---
|
||||
|
||||
## 9. 与其它规划的关系
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [object-inheritance.md](object-inheritance.md) | 正交;表不表示类字段 schema |
|
||||
| [agent-streaming.md](agent-streaming.md) | 正交;事件列表可用竖表金样演示 foreach |
|
||||
| [okf-near-match.md](okf-near-match.md) | 正交 |
|
||||
@@ -0,0 +1,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`**
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: view and the user docs site
|
||||
description: Local browse and static export from the interpreter
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Version 2.6.0 keeps action descriptions in the sentence and moves their implementation to side notes. Empty parentheses explicitly mark missing logic. Multiple actions and returns keep their original prose, while ordinary links remain navigation. On compact screens, native disclosures keep the implementation readable even without JavaScript.
|
||||
|
||||
Executable knowledge now presents inputs, returns, effects, dependencies and separate verification facts. Technical identities and digests stay folded. Source explanations are distinct from captured results; a pure effect summary or linked source is not proof that a program ran or its content was verified.
|
||||
|
||||
The reader introduced in 2.5.1: `marqdo view` and `view output` share a warm paper reader with a new
|
||||
Marqdo logo, serif document text, botanical ornaments, navigation, search and a
|
||||
floating action toolbar. Wide screens place real execution notes in the margins;
|
||||
compact screens keep them below the corresponding paragraph. Click a note to
|
||||
inspect its full captured value. Call and loop frame selectors remain available.
|
||||
|
||||
Static exports embed decorations, KaTeX and math fonts for offline reading. The
|
||||
play button runs the document in live view; static pages retain their captured
|
||||
results and explain how to start a live view. Ordinary document reruns update
|
||||
prose, bindings and notes from the same execution capture.
|
||||
|
||||
Annotations follow the exact source span across calls and loop iterations. Flowing
|
||||
curves and staggered margin notes avoid source text and neighboring connections.
|
||||
The floating toolbar labels its actions: refresh, settings, run, clear and more.
|
||||
|
||||
Local: `marqdo view public`
|
||||
|
||||
Static export: `marqdo view output public -o public`
|
||||
|
||||
Browse Structure keeps narration, highlights executable markers, and attaches
|
||||
run results (values, taken branch arms, call/loop frames). The same render path
|
||||
builds this user docs site; CI publishes to `gh-pages`.
|
||||
|
||||
We now **[Display this step's result](> print text="Docs site: generated by the Marqdo interpreter, not hand-written HTML.")**.
|
||||
Loaded 100 of 631 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user