Compare commits

..
5 Commits
Author SHA1 Message Date
cflmy 111849d92a 添加readme 2026-08-11 17:38:49 +08:00
cflmy 235384fb85 开发基本的骨架,错误处理的结构体和框架 2026-08-11 17:29:43 +08:00
cflmy a9b59b361e 初始化项目的基本框架 2026-08-11 16:37:13 +08:00
cflmy c4501a17f2 master分支 init 2026-08-11 15:26:16 +08:00
cflmyandCursor 5f00572e24 Empty master branch.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 15:09:22 +08:00
284 changed files with 240 additions and 29051 deletions

No files matched your search

-159
View File
@@ -1,159 +0,0 @@
---
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` ``, bindings `` `x` ``, foreach `` [`item`](`coll`) ``. **Complex text** uses `"..."` with escapes; bare tokens stay literal (no `\n` magic).
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
7. **Paths in bare expressions:** `/` is division. Prefer `` `path` `` vars, same-dir names, or call args — not raw `a/b` in expressions.
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
## Markup → meaning (v0.2)
| Marker | Meaning |
|--------|---------|
| `#` | **Object / type** (constructor body). `# main` = entry object. |
| `##` … `######` | **Function / method** (nesting by heading depth). |
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else) |
| `- …` inside body | Loop (`while` or `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
| Frontmatter `> path.mq.md` | Import |
| `*…*` | 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 |
| `` ```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
```markdown
---
title: example
> lib/text.mq.md
---
# main
*`xs` = > split value=a,b,c sep=,*
> print text=`xs`
```
- Import **English** or **Chinese** library file; call that file’s API names (do not mix).
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm` / `add agent` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — agent framework (layout + ABI; compose LLM per `doc/design/ext-agent.md`).
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
- 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 `拆分` | Match file language |
## 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)
-162
View File
@@ -1,162 +0,0 @@
# 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=`果`
```
## 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` / `自`.
## 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
```
-135
View File
@@ -1,135 +0,0 @@
# 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. * ``; loops `` - [`item`](`coll`) ``; identifiers in backticks. 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` | table/rows helpers |
| `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 |
-50
View File
@@ -1,50 +0,0 @@
# 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
-102
View File
@@ -1,102 +0,0 @@
# 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")
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"
$vsix = "marqdo-$ver.vsix"
Copy-Item target/release/marqdo.exe "dist/$exe"
$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
- name: Upload release assets
uses: softprops/action-gh-release@v2
with:
body: |
## Marqdo ${{ github.ref_name }}
### Highlights
- **Embedded stdlib** (v0.1.2+): `lib/*.mq.md` built into the binary
- **writeback** + **subtask** stdlibs
- **`marqdo version --check`**
- VSIX built from branch **`vscode-extension`** (not tracked on `main`)
### 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-*.vsix` | VS Code / Cursor extension |
Extension workflow: [doc/design/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.VSIX }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+1 -39
View File
@@ -1,39 +1 @@
/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/
.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
/target
-22
View File
@@ -1,22 +0,0 @@
# Changelog
## 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
+1 -1157
View File
File diff suppressed because it is too large. Load diff
+5 -30
View File
@@ -1,35 +1,10 @@
[package]
name = "marqdo"
version = "0.1.2"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
readme = "README.md"
repository = "https://github.com/cflmy/marqdo"
version = "0.1.0"
edition = "2024"
[dependencies]
[[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"
[workspace]
members = ["plugins/demo", "plugins/agent"]
resolver = "2"
[dev-dependencies]
assert_cmd = "=2.0.14"
predicates = "=3.1.0"
path = "src/marqdo.rs"
-201
View File
@@ -1,201 +0,0 @@
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.
-137
View File
@@ -1,137 +0,0 @@
# Marqdo
**代码即文档。文档即代码。文档即知识库。**
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)
| 标记 | 含义 |
|------|------|
| 无标记行 | 注释(空行分段) |
| `*…*` | 程序语句 |
| `**…**` | **返回值**(架构) |
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
| `##` … | 函数 / 方法(按标题深度嵌套) |
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [`项`](`集合`) ``) |
| 表格 | 集合 |
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
```markdown
# main
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello `谁`!
---
## 加一
+ `n`
**`n` + 1**
```
完整约定:[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.1.2)
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
- **`marqdo version --check`**:与 GitHub 最新 release 对比
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
- **官方扩展 `ext/`**(非 stdlib):[`ext/llm`](doc/design/ext-llm.md);[`ext/agent`](doc/design/ext-agent.md) 智能体开发框架。安装:`marqdo ext list` / `add llm|agent` / `remove`(见 [ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext` 或 `MARQDO_EXT`)
- **原生插件 ABI v1**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);demo `plugins/demo`
- **用户静态站**:`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)**:自 **v0.1.2** 起,单独 `.exe` **已内置**官方 `lib/`(`> lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发;`ext/` 与原生插件 `.dll` 仍须单独安装。`marqdo version --check` 可查看是否有新版本。OpenAI 兼容聊天见 [ext-llm.md](doc/design/ext-llm.md)。智能体布局见 [ext-agent.md](doc/design/ext-agent.md)。
文档:用户站 [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)
+91
View File
@@ -0,0 +1,91 @@
---
title: Marqdo主分支开发记录
date: 2026-08-11
author: pingan
---
## 前言
在经过一周多的ai疯狂开发之后,尽管marqdo已经做出了并拥有了许多非常良好的特性,作者确逐渐感到非常的不安,
这种不安来自于崩塌感,作者不知道什么时候,ai就会更改关键的定义,导致突然的崩塌,在开发智能体拓展库的时候作者还尚未有这种感觉,但是在网络拓展库,这种不安定感几乎席卷了作者的全部身心。
必须承认,ai在没有经过大量训练就撰写一门崭新的语法,定义一些它完全没有接触过的东西对于ai还是太困难了,ai并不能通过我的监督,真正的理解marqdo代码即文档的设计思路,所以,尽管非常的遗憾,作者还是决定回归古法编程,还是手搓代码吧,尽管这意味着marqdo很难赶上ai的浪潮了。
marqdo的设计初衷很是简单,这就不是一门设计给程序员的语言,哪个程序员会用markdown表格来表示集合呢?不会的,这太过繁复了,但是ai可以,这就使得过去编程语言的范式变得不是那么重要了。
自然如果只是为了易读性,marqdo并没有完全的开发必要,重点在于对md的支持,作者必须承认谷歌提出的OKF规范,把markdown这种文件格式放到了一个极高的位置,这意味着,可执行的知识体系,如果能做到,为什么不试试?
此外,jupyter notebook笔记本体积太大不利于管理的问题也是存在的,作者就在想,markdown支持代码块的插入,这个代码如果可以直接执行并放回,这不就是最好的jupyter替代品吗?事实上,在main分支的marqdo已经实现了这个功能,但是还不够好,作者要把marqdo真正做成一门科学计算的顶级语言。
最后是数学公式的支持,公式库需要能够自动的渲染,高可读,还要能够自动的画图,自动的完成诸多内容,让可执行=正确,让ai支持数学推理不再困难。
最后,2026年8月11日,我预祝未来的自己,开发成功。
## 开发
### Marqdo上下文无关文法
file -> "---" metadata "---" content ;
metadata -> file_information |
import_lib_name ;
content -> comment |
code_body ;
comment -> comment_content ;
code_body -> class |
function|
code|
$formula$|$$formula$$|\[formula\]|
```code_block_type
code_block
```;
class -> # class_name code_body |
# class_name => parent_class_name code_body ;
function -> function_header param_list body return_stmt ;
function_header -> ## identifier |
### identifier |
#### identifier ;
param_list -> + identifier ;
body -> statement |
branch |
loop ;
return_stmt -> ** statement ** ;
<!--the number of # stand for the level of function -->
code -> 1. branch |
- loop |
statement ;
<!--Ordered lists represent branch, unordered lists represent loop-->
branch -> statement ;
loop -> statement ;
statement -> > call |
literal|
`var_value_name`|
list and dict|
"str"|
*statement_without_any_marker*;
<!--here we use markdown table to stand for list and dict-->
call -> function_name args;
literal -> literal_code as other code;
formula -> latex math code;
code_block_type -> code_block's code type;
code_block -> code of a code_block;
-59
View File
@@ -1,59 +0,0 @@
# 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/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置函数** |
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `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`(智能体开发框架;布局已落地,编排/大模型组合路线已记录)** |
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
| [design/user-site.md](design/user-site.md) | **用户站:`public/` → `gh-pages`** |
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
| [design/view-debug.md](design/view-debug.md) | **`marqdo debug` 独立调试页** |
| [design/vscode-extension.md](design/vscode-extension.md) | **VS Code 扩展:分支 `vscode-extension`(main 不跟踪源码)** |
| [design/vscode-extension-commit.md](design/vscode-extension-commit.md) | **扩展提交约定(禁止在 main 提交 `vscode-extension/`)** |
| [design/bytecode.md](design/bytecode.md) | **M5 字节码 / 双后端** |
| [design/pipeline-debug.md](design/pipeline-debug.md) | **流水线 `--dump-*` 可视调试** |
| [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) |
| [roadmap/interpreter.md](roadmap/interpreter.md) | 正经解释器路线图 |
| [roadmap/next-phase.md](roadmap/next-phase.md) | **下一阶段:input / 诊断 / 标准库 / view 调试** |
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
## 写作原则
1. 先宪法与路线图,再实现。
2. 金样例不过 = 未完成。
3. 示例统一 `.mq.md`。
-53
View File
@@ -1,53 +0,0 @@
# 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 正则玩具 | 达不到安全与长期目标 |
-29
View File
@@ -1,29 +0,0 @@
# 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 是面向模型的压缩操作手册。
-89
View File
@@ -1,89 +0,0 @@
# 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/*` | ✅ | ✅(load 合并 AST 后编译) |
| `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。
-53
View File
@@ -1,53 +0,0 @@
# 调用实参:具名与位置
| | |
|---|---|
| 状态 | 已定(v0.1 增补) |
| 日期 | 2026-08-04 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.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/import/`。
-128
View File
@@ -1,128 +0,0 @@
# OKF 兼容清单:`marqdo catalog`
| | |
|---|---|
| 状态 | 已定(v0 命令落地) |
| 日期 | 2026-08-04 |
| 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 |
| 相关 | [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
---
## 1. 决策(重申)
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。详见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
本文件规定 **CLI 与 v0 落盘格式**。
---
## 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. 生成物(v0)
```
OUT_DIR/
catalog.yaml # 机器向总清单(OKF 风格字段)
index.md # 人/Agent 可读总览(含 YAML frontmatter)
modules/
<stem>.md # 每个 .mq.md 一个概念页(frontmatter + 摘要)
```
路径中的目录层级拍扁为文件名时用 `__` 连接,例如:
`structure/import/main.mq.md` → `modules/structure__import__main.md`
### 3.1 `catalog.yaml`(示意)
```yaml
# GENERATED by marqdo — do not edit by hand
type: Marqdo Catalog
title: marqdo-project
generated:
by: marqdo/0.0.1
# at: 可选 ISO8601;CI 比对时可忽略
modules:
- id: structure/hello
resource: structure/hello.mq.md
title: Hello World # 来自源 frontmatter title,缺省用文件名
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
```
字段约定(v0 最小集):
| 字段 | 含义 |
|------|------|
| `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) |
| `modules[].resource` | 相对 `PATH` 的源路径 |
| `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` |
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`);嵌套 `##` 列入 `children`(可选,v0 可扁平只列顶层) |
| `generated.by` | `marqdo/<crate version>` |
不在 v0:版本锁定哈希、跨仓 URL、完整符号类型。
### 3.2 模块概念页 frontmatter
```yaml
---
type: Marqdo Module
title: …
resource: structure/hello.mq.md
depends: [] # imports 列表
exports: [Hello World]
generated:
by: marqdo/0.0.1
---
```
正文含「请勿手改」提示、依赖列表、导出列表;可链到同包其它模块页。
---
## 4. 与 `view output` 的分工
| 命令 | 产物 | 受众 |
|------|------|------|
| `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引 | 工具 / 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/`。
2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。
3. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
4. `marqdo sync` 与 `catalog` 行为一致。
-38
View File
@@ -1,38 +0,0 @@
# 可执行面与叙述面
| | |
|---|---|
| 状态 | 与 mapping v0.1 / keywords 对齐(成段注释) |
| 日期 | 2026-08-04 |
---
## 三层
| 层 | 形态 | 角色 |
|----|------|------|
| **叙述面** | 成段注释(空行分段) | 注释;段内任意标记无语义 |
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
| **外联面** | ` ```lang ` | 其它语言(FFI) |
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
### 成段注释
- 以**空行**划分段落。
- 段首行:首字符非标记 → 注释。
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
---
## 语句 vs 返回 vs 输出
| 标记/形式 | 角色 | 是否架构级 |
|-----------|------|------------|
| `*…*` | 程序语句 | 是 |
| `**…**` | 返回值 | 是 |
| `****` / 空粗体 | 空返回 + 结束函数体 | 是 |
| `> print …` | 打印副作用 | 否(内置函数) |
| 函数体 `---` / `***` | 结束函数体 | 是(边界) |
-175
View File
@@ -1,175 +0,0 @@
# 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。
-68
View File
@@ -1,68 +0,0 @@
# 示例与测试布局
| | |
|---|---|
| 状态 | 已定 |
| 日期 | 2026-08-04 |
| 原则 | **夹具即金样例**:`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
keywords/ # 关键字与内置名
print.mq.md
bool-logic.mq.md
errors/ # 期望失败(诊断文案稳定后再加金样例)
…
```
面向访客的可执行介绍在 [`public/`](../../public/)(无 `errors/`),见 [user-site.md](user-site.md)。
开发设计文稿在 [`doc/`](../)(单数)。
---
## 2. 分类职责
| 类别 | 测什么 | 不测什么 |
|------|--------|----------|
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、位置/具名实参 | 关键字边角 |
| **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))
- **模块图**:循环导入拒绝
---
## 3. 金样例约定
每个可执行 `.mq.md` 在 `tests/gold.rs` 登记期望 stdout。
`errors/` 内文件登记期望 stderr 子串与非零退出码。
---
## 4. 与 `view` / `public` 的关系
- `marqdo view tests`:开发者浏览金样例(含 errors)。
- `marqdo view public`:用户文档站源;**不要**把 `tests/errors` 编进 `public/`。
-85
View File
@@ -1,85 +0,0 @@
# Native plugin ABI (v1)
| | |
|---|---|
| Status | Accepted |
| Date | 2026-08-06 |
| 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.
## Contract
`MARQDO_ABI_VERSION = 1`.
Every plugin exports:
| Symbol | Role |
|--------|------|
| `marqdo_plugin_abi_version` | Must equal host’s supported version |
| `marqdo_plugin_init` | Register functions via `MarqdoHostApi` |
| `marqdo_plugin_shutdown` | Teardown |
Host provides `register_fn(name, params_csv, fn)`, `alloc`, `free`.
### 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`.
## Marqdo surface (`lib/plugin` / `lib/插件`)
| English | Chinese | Host |
|---------|---------|------|
| `## load` (`path`) | `## 加载` (`路径`) | `host_plugin_load` |
| `## unload` | `## 卸载` | `host_plugin_unload` |
| `## list` | `## 列出` | `host_plugin_list` |
```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. Prefer a same-directory filename, or pass a path via a variable / env (see gold tests).
## Demo
```bash
cargo build -p marqdo_plugin_demo
# Windows: target/debug/demo.dll
# Linux: target/debug/libdemo.so
# macOS: target/debug/libdemo.dylib
```
Registers `demo_add(a,b)`, `demo_echo(text)`. Gold: [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
Official agent layout plugin: [`plugins/agent`](../../plugins/agent) — see [ext-agent.md](ext-agent.md).
## Non-goals
- Embedding plugins in the release exe by default
- Callbacks from plugin into arbitrary Marqdo evaluation
- OS sandbox / seccomp
- **Third-party** plugin / package registry
Official install of known extensions (`marqdo ext add …`) is **planned** — see [ext-cli.md](ext-cli.md). That is not a public marketplace.
-137
View File
@@ -1,137 +0,0 @@
# Official agent development framework (`ext/ai/agent`)
| | |
|---|---|
| Status | Accepted · **thin agent loop locked** |
| Date | 2026-08-06 |
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [objects.md](objects.md) |
## What we are building
An **agent-development framework** — smallest runtime surface for agents on Marqdo.
**Not** task-dispatch, **not** bundled domain tools, **not** layout/match/ticket helpers in official ext.
| In scope | Out of scope (your runbook / your code) |
|----------|-------------------------------------------|
| `# 智能体` ctor | `## 技能匹配` · `## 分配任务` · `## 创建工单` … |
| `## 执行` | Anything task-specific in `ext/` |
| `## 清空历史` | |
| Auto context: source, position, history, Marqdo skill | |
## Repo layout (`ext/`)
Official extensions for LLM + agent live under **`ext/ai/`** only. No flat `.mq.md` at `ext/` root; future domains get their own subdir.
```text
ext/
ai/
llm.mq.md
大模型.mq.md
agent.mq.md
智能体.mq.md
```
Import: `> ext/ai/智能体.mq.md` · `> ext/ai/llm.mq.md`
## Layering
| Layer | Role |
|-------|------|
| **Your runbook** | Tables, loops, **your** tools & logic |
| **`ext/ai/llm`** | Model I/O |
| **`ext/ai/agent`** | Framework: ctor + `执行` + `清空历史` |
| **`lib/*`** | Generic I/O |
```text
> ext/ai/智能体.mq.md
▼
# 智能体 (大模型, 工具, 用户提示信息?)
## 执行
## 清空历史
```
`工具` = caller-supplied **function catalog** (table of `##` names); framework resolves names via `call_fn` / `调用` and runs the matching zero-arg function in the runbook module.
Install: [`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`.
### Tools (v1)
Tools are **not** framework builtins — you define `## 函数名` in your runbook and list names in a table:
```markdown
`工具表` =
| 工具 |
|------|
| 获取时间 |
| 分配任务 |
```
- Single-column table → list of function **names** (text).
- Multi-column table → each row is a map; name from column `工具` / `tools` / `name`.
- Marqdo has no first-class function values in tables yet; the name must match a `##` in the same module (or imports). `执行` calls it with `call_fn` after the model replies `TOOL:<name>`.
- Do **not** use `parse text=["fn"]` for the tools list — unquoted identifiers inside `parse` are evaluated as calls.
---
## Public API (v1)
| | Role |
|--|------|
| `# 智能体` / `# agent` | **大模型**, **工具**, optional **用户提示信息** |
| `## 执行` / `## run` | **额外信息**; context + LLM + history append |
| `## 清空历史` / `## clear_history` | Wipe history on this handle |
Module-level `##` helpers (e.g. context assembly) are internal — not public contract.
### Auto context (each `执行`)
- `.mq.md` source
- Call-site / position
- Conversation history on this handle
- Marqdo skill (`skills/marqdo/`)
### History (v1)
- Host-backed id per handle
- Append after each successful `执行`
- `清空历史` ships with `执行`
---
## Example runbook (application — not framework)
```markdown
---
> ext/ai/智能体.mq.md
> ext/ai/大模型.mq.md
---
# main
*`模型` = > 大模型 *
*`工具名` = | 技能匹配 | 分配任务 | … |
*`助手` = > 智能体 大模型=`模型` 工具=`工具名` 用户提示信息=… *
- [任务](任务队列)
> `助手`.清空历史
*`结果` = > `助手`.执行 额外信息=`任务` *
```
Domain `##` functions live in **this file** or your lib — never in `ext/ai/`.
---
## Shipped / roadmap
| Item | Status |
|------|--------|
| `ext/ai/` + framework + context injection | in progress |
| Live `执行` test (`tests/ext/agent-run-live.mq.md` + `.env`) | shipped |
| Tool-call loop in `执行` (`TOOL:<name>` → `call_fn`) | shipped |
### Non-goals
- Domain tools in official ext
- Flat `ext/*.mq.md` at repo root
- Second chat stack beside llm
-61
View File
@@ -1,61 +0,0 @@
# Official extension installer (`marqdo ext`)
| | |
|---|---|
| Status | **Accepted (v0.1)** |
| Date | 2026-08-06 |
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.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/foo/`), 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` |
## Tests
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` (needs `tests/ext/.env`).
## Non-goals
- Third-party registry
- Merging into `lib/`
- Bundling domain/task helpers in official ext
-70
View File
@@ -1,70 +0,0 @@
# 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) (**agent development framework** — layout shipped; orchestration + LLM composition on roadmap). Installer CLI (planned): [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
**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` |
| `# llm` | `# 大模型` | Object ctor → handle map |
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods on the handle |
```markdown
---
> ext/ai/llm.mq.md
---
# main
> load_env
*`model` = > llm *
*`reply` = > `model`.complete prompt=Say hi in one word *
> print text=`reply`
```
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`
- Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env`
- Live agent `执行`: `tests/ext/agent-run-live.mq.md` + same `.env` (gold: `ext_agent_run_live`, skips if missing)
- Offline agent smoke: `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`)
-163
View File
@@ -1,163 +0,0 @@
# 设计草案:机器生成的 YAML 清单(OKF 风格)
| | |
|---|---|
| 状态 | 草案(已采纳方向;修正「配置文件」误解) |
| 日期 | 2026-08-04 |
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) |
| 取代 | 此前「YAML = 人手写的编译器配置 / frontmatter 契约」的表述 |
---
## 决策
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` 自动生成的依赖与项目元数据,并可据此自动生成本项目文档;不是人手填写的配置文件。**
人写源,工具写清单与目录文档;编译器与文档站共同消费生成物,语义始终回到源。
-137
View File
@@ -1,137 +0,0 @@
# 内置关键字 / 函数:中英双名(草案)
| | |
|---|---|
| 状态 | **已定(已实现)** |
| 日期 | 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 才能中英文通用而不把解释器撑爆。**
-97
View File
@@ -1,97 +0,0 @@
# 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,并同步考虑是否值得占用双名配额。
-271
View File
@@ -1,271 +0,0 @@
# Marqdo 语法映射 v0.2(Markup-as-Syntax)
| | |
|---|---|
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、标识符反引号、`-` 专用于循环) |
| 日期 | 2026-08-06 |
| 取代 | 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) |
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
---
## 1. 哲学
1. `.mq.md`:打开即文档,运行即程序。
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
5. **标识符一律反引号**:凡表示变量槽位(形参、绑定、引用、遍历项、集合名)均写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
---
## 2. 行首判别与成段注释
跳过前导空白后,对**段首行**(空行之后的第一行,或文件起始):
| 首字符 | 分类 |
|--------|------|
| 普通文字 / 空 | **注释** |
| 标记字符 | **代码** |
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
---
## 3. 映射总表(v0.2)
| 标记 | 语义 |
|------|------|
| `#` … `######` | **`#` = 对象/类型**;**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
| 体内 `-` | **循环**(`while` 条件,或 `` [`项`](`集合`) `` 遍历) |
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
| `` > `对象`.方法 … `` | 方法调用(实例 map 须含 `_type`) |
| frontmatter `> path.mq.md` | 跨文件导入 |
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
| `**…**` | **返回值**(架构级;函数结果) |
| `****` / `**` + 空白 + `**` | **空返回**(`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` |
| `- 谁` 作形参 | `` + `谁` `` |
| `[果](篮子)` 裸名遍历 | `` [`果`](`篮子`) `` |
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
---
## 4. 语句、返回、调用
### 程序语句(斜体)
```markdown
*`x` = 1*
*`y` = `x` + 2*
```
行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
### 返回值(粗体)
```markdown
## 加一
+ `n`
**`n` + 1**
```
### 输出(内置函数 `print`)
```markdown
# main
> print text=Hello World!
```
### else 与斜体消歧
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
- `*中间有内容*` → 程序语句。
- `**…**` → 返回(与 else 无关)。
---
## 5. Frontmatter 与跨文件
同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
---
## 6. 对象、函数、形参
- `# Name`:对象(构造体);`# main` 为入口对象。
- `##` / `###` …:函数或方法;挂在对象下则为方法。
- 标准库顶层 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
```
```markdown
- [`果`](`篮子`)
> print text=今天吃`果`
```
`while`:
```markdown
- `n` > 0
> print text=`n`
*`n` = `n` - 1*
```
---
## 9. 集合(表格)
同 v0。`` `篮子` = `` 后接 GFM 表。
---
## 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/)。
-73
View File
@@ -1,73 +0,0 @@
# 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. 非目标(本波)
- 继承 / 接口 / 可见性
- 无 `_type` 的「鸭子」方法分发
- 用表格声明字段 schema(表格仍表示集合)
## 6. 迁移摘要
| 旧 | 新 |
|----|----|
| 库顶层 `# http_get` | `## http_get` |
| `# main` + `## 嵌套` | 不变(main = 入口对象) |
| `ext` 顶层 `# complete` | `# llm` / `# 大模型` 构造 + `## complete` / `## 运行` |
-75
View File
@@ -1,75 +0,0 @@
# 解释器流水线可视调试
| | |
|---|---|
| 状态 | 已定(开发期强制友好) |
| 日期 | 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` 随阶段增长自动变完整 |
-19
View File
@@ -1,19 +0,0 @@
# 记录:返回 / 语句 / 输出 / 分割线(决议)
| | |
|---|---|
| 状态 | 已决议(并入 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)。
-49
View File
@@ -1,49 +0,0 @@
# 外联 / 胶水标准库
| | |
|---|---|
| 状态 | **已落地(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;本机解释器可配置。**
-146
View File
@@ -1,146 +0,0 @@
# 标准库多语言命名(草案)
| | |
|---|---|
| 状态 | **草案(先文档、后实现)** |
| 日期 | 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` | `rows` · `row_at` |
| `> 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`——无语言开关。**
-231
View File
@@ -1,231 +0,0 @@
# 数学标准库(方案)
| | |
|---|---|
| 状态 | **已实现(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 写文件。**
-181
View File
@@ -1,181 +0,0 @@
# 标准库 L1 模块
| | |
|---|---|
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
| 日期 | 2026-08-06 |
| 原则 | 全部经 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) |
---
## 1. 目标
在 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本与可选原生扩展。标准库**必须导入**才可用。
| 模块族 | 英文库 | 中文库 | 状态 |
|--------|--------|--------|------|
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有 |
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `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 包装 |
| **L1 官方库** | `lib/*.mq.md` | **是** |
| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`) |
---
## 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)。**
-25
View File
@@ -1,25 +0,0 @@
# 子任务标准库(subtask)
| | |
|---|---|
| 状态 | v2 |
| 库 | `lib/subtask.mq.md` · `lib/子任务.mq.md` |
## 定位
**并发**执行单元。`spawn` 四选一:
| 参数 | 执行方式 | `join` 返回值 |
|------|----------|---------------|
| `path=` | `marqdo run <file>` 子进程 | 退出码 `Int` |
| `fn=` + 可选 `args=` | 当前入口模块中的函数(进程内线程) | 函数返回值 `Value` |
| `code=` | 外联代码块(`Value::Code`)子进程 | stdout `Text` |
| `lang=` + `source=` | 外联源码子进程 | stdout `Text` |
`args=`:文件子任务为 `List`(命令行参数);函数子任务为 `Map`(形参绑定)或 `List`(按 `arg0`… 命名)。
父进程结束(含 panic)时 **KillOnDrop** 终止所有文件/外联子进程;函数线程标记为 killed 并 detach(无法强杀 OS 线程)。
`poll` → `{ status: running | done | failed, … }`;函数 done 时含 `value`,进程/外联 failed 时含 `code` 或 `error`。
Host:`host_subtask_*`(`src/host/subtask.rs`)。
-36
View File
@@ -1,36 +0,0 @@
# 自写回标准库(writeback)
| | |
|---|---|
| 状态 | v1 已落地 |
| 库 | `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
-->
```
- 注释内仅保留 `marqdo-out` 标识,**不存行号**(避免写回后行号漂移)
- 默认在**调用行下方**插入或替换紧邻块(中间可有空行)
- `at_end=true` / `末尾=true`:在文件末尾保留单块(替换已有末尾块)
## API
| EN | ZH | 说明 |
|----|-----|------|
| `record` | `写回` | `value=`,可选 `at_end=false` |
| `get` | `取` | 可选 `at_end=false` |
| `clear` | `清除` | 可选 `at_end=false` |
| `list` | `列出` | 全文所有输出块(含推断锚点行) |
可选参数语法:`` + `参数名`=默认值 ``(与现有参数列表兼容)。
Host:`host_writeback_*`(`src/host/writeback.rs`)。
-104
View File
@@ -1,104 +0,0 @@
# 标准库(P2)
| | |
|---|---|
| 状态 | **S0–S3 + L1 全模块落地** |
| 日期 | 2026-08-06 |
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) |
> **多语言库命名**:见 [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:
```markdown
---
> lib/text.mq.md
> lib/table.mq.md
---
```
`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` | `rows` `row_at` |
| `lib/表.mq.md` | `行数` `取行` |
完整清单见 [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`。
-152
View File
@@ -1,152 +0,0 @@
# 参考实现:技术选型分析(尚未拍板)
| | |
|---|---|
| 状态 | **分析中 — 未定案** |
| 日期 | 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)),再谈用何种语言写分类器。选型不能假设「整文件都是可执行代码」。
-66
View File
@@ -1,66 +0,0 @@
# 用户静态文档站(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/`。
-42
View File
@@ -1,42 +0,0 @@
# 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`。
-116
View File
@@ -1,116 +0,0 @@
# `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+注释;旁侧函数大纲可搜索)· 执行 · 源码。表达式为表面语法。
**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
---
## 5. HTTP(实时模式)
| 方法 | 路径 | 含义 |
|------|------|------|
| `GET` | `/` | 默认打开第一个 `.mq.md`(无文件时为空提示) |
| `GET` | `/file?path=…` | 单文件页 |
| `GET` | `/api/tree` | JSON 树(可选) |
根目录锁死;拒绝 `..` 逃逸。
---
## 6. 验收
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件;函数大纲可搜索跳转。
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
4. 冷启动无明显外网依赖。
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
-82
View File
@@ -1,82 +0,0 @@
# 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` 只保留本约定与设计指针。
-31
View File
@@ -1,31 +0,0 @@
# 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)。
-87
View File
@@ -1,87 +0,0 @@
# 开发环境配置(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:7897"
$env:HTTP_PROXY="http://127.0.0.1:7897"
cargo build
```
或配置 `%USERPROFILE%\.cargo\config.toml`:
```toml
[http]
proxy = "http://127.0.0.1:7897"
```
---
## 4. 目录约定
| 路径 | 含义 |
|------|------|
| `src/lex` | 行分类 / 词法(自研) |
| `src/parse` | 递归下降语法 |
| `src/diagnostics` | 诊断 |
| `tests/` | 金样例 + 集成测试(`structure` / `keywords` / `errors`) |
| `public/` | 用户可执行文档(无 errors) |
| `spike/` | 旧 Python 风险探测,非运行时依赖 |
| `doc/` | 设计与路线图 |
---
## 5. 下一里程碑
见 [interpreter.md](roadmap/interpreter.md):M1 词法·行分类与最小 AST。
-215
View File
@@ -1,215 +0,0 @@
# 调研: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` 行为(方向已采纳,见 [design/generated-yaml-manifest.md](../design/generated-yaml-manifest.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 的终点。**
-178
View File
@@ -1,178 +0,0 @@
# 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: 收集函数(提升)+ 导入合并
│ │ 作用域链、形参、未定义名诊断
└─────────┬─────────┘
▼
┌───────────────────┐
│ 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
```
输出与金样例一致;错误带位置;新增语法必须加金样例与单测。这才是「一门解释型语言」的最低合格线。
-220
View File
@@ -1,220 +0,0 @@
# 下一阶段:从玩具到可用语言
| | |
|---|---|
| 状态 | **进行中**(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 完成;五库扩展设计中** |
| **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 |
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 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 插件或大而全标准库。**
-111
View File
@@ -1,111 +0,0 @@
---
title: ext/ai/agent
description: Thin agent framework — ctor, run, clear_history only.
> ext/ai/llm.mq.md
---
## build_agent_context
+ `agent`
+ `extra`
Internal: assemble prompt (user prompt, extra, tool list, source, call site, history, Marqdo skill).
*`user_prompt` = > get value=`agent` key=user_prompt *
1. `user_prompt`
*`up` = `user_prompt`*
2. *
*`up` = None*
*`tools` = > get value=`agent` key=tools *
*`tools_s` = > host_format_tools_for_llm tools=`tools` *
*`src` = > host_module_source *
*`site` = > host_call_site *
*`site_s` = > stringify value=`site` *
*`id` = > get value=`agent` key=id *
*`hist` = > host_agent_history_get id=`id` *
*`hist_s` = > stringify value=`hist` *
*`skill` = > host_marqdo_skill *
*`extra_s` = > stringify value=`extra` *
*`sep` = > parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- extra ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source ---\n","f":"\n\n--- history ---\n","g":"\n\n--- marqdo skill ---\n"} *
*`a` = > get value=`sep` key=a *
*`b` = > get value=`sep` key=b *
*`c` = > get value=`sep` key=c *
*`d` = > get value=`sep` key=d *
*`e` = > get value=`sep` key=e *
*`f` = > get value=`sep` key=f *
*`g` = > get value=`sep` key=g *
*`tool_proto` = \n\n--- tool protocol ---\nEach tool is a zero-arg Marqdo function in this module (see tools list). To call one, reply with exactly one line: TOOL:<name>. No other text on that line.\nAfter the tool runs you will get its output and should answer the user.\n *
*`p` = You are a Marqdo agent. Follow Marqdo skill rules when reading or writing .mq.md. *
*`p` = `p` + `a` + `up` + `b` + `extra_s` + `c` + `tool_proto` + `tools_s` + `d` + `site_s` + `e` + `src` + `f` + `hist_s` + `g` + `skill` *
**`p`**
# agent
+ `model`
+ `tools`
+ `user_prompt`
*`id` = > host_agent_alloc *
*`h` = > parse text={"_type":"agent"} *
*`h` = > map_set map=`h` key=id value=`id` *
*`h` = > map_set map=`h` key=model value=`model` *
*`h` = > map_set map=`h` key=tools value=`tools` *
1. `user_prompt`
*`h` = > map_set map=`h` key=user_prompt value=`user_prompt` *
2. *
*`_` = 1*
**`h`**
## clear_history
*`id` = > get value=`self` key=id *
> host_agent_history_clear id=`id`
****
## run
+ `extra`
*`ctx` = > build_agent_context agent=`self` extra=`extra` *
*`id` = > get value=`self` key=id *
*`user_turn` = > parse text={"role":"user"} *
*`user_turn` = > map_set map=`user_turn` key=content value=`extra` *
> host_agent_history_append id=`id` item=`user_turn`
*`model` = > get value=`self` key=model *
*`reply` = > `model`.complete prompt=`ctx` *
*`tools` = > get value=`self` key=tools *
*`reply` = > trim value=`reply` *
*`parts` = > split value=`reply` sep=: *
*`head` = > at value=`parts` index=0 *
*`tool_name` = > at value=`parts` index=1 *
*`tool_name` = > trim value=`tool_name` *
1. `head` == TOOL
*`allowed` = > host_tool_allowed tools=`tools` name=`tool_name` *
1. `allowed`
*`tool_out` = > call_fn name=`tool_name` *
*`tool_s` = > stringify value=`tool_out` *
*`extra_s` = > stringify value=`extra` *
*`fp` = The user asked: *
*`fp` = `fp` + `extra_s` *
*`fp` = `fp` + . You invoked tool *
*`fp` = `fp` + `tool_name` *
*`fp` = `fp` + which returned: *
*`fp` = `fp` + `tool_s` *
*`fp` = `fp` + . Reply to the user in one brief sentence. *
*`reply` = > `model`.complete prompt=`fp` *
2. *
*`reply` = Tool not allowed: `tool_name` *
2. *
*`_` = 1*
*`as_turn` = > parse text={"role":"assistant"} *
*`as_turn` = > map_set map=`as_turn` key=content value=`reply` *
> host_agent_history_append id=`id` item=`as_turn`
**`reply`**
-130
View File
@@ -1,130 +0,0 @@
---
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
---
## load_env
Load `.env` from cwd (optional named arg `path=`). Does not override existing variables.
**> load_dotenv**
# llm
Construct an LLM handle from `OPENAI_*` / `MARQDO_LLM_*` (default base OpenAI v1, model `gpt-4o-mini`).
*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} *
*`api_key` = > env_get name=OPENAI_API_KEY *
1. `api_key`
*`_k` = 1*
2. *
*`api_key` = > env_get name=MARQDO_LLM_API_KEY *
3. `api_key`
*`_k` = 1*
4. *
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY
> exit code=1
*`base_url` = > env_get name=OPENAI_BASE_URL *
1. `base_url`
*`_k` = 1*
2. *
*`base_url` = > env_get name=MARQDO_LLM_BASE_URL *
3. `base_url`
*`_k` = 1*
4. *
*`base_url` = > get value=`d` key=base *
*`model` = > env_get name=OPENAI_MODEL *
1. `model`
*`_k` = 1*
2. *
*`model` = > env_get name=MARQDO_LLM_MODEL *
3. `model`
*`_k` = 1*
4. *
*`model` = > get value=`d` key=model *
*`q_key` = > quote text=`api_key` *
*`q_base` = > quote text=`base_url` *
*`q_model` = > quote text=`model` *
*`suffix` = > get value=`d` key=suffix *
*`bearer` = > get value=`d` key=bearer *
*`p1` = > get value=`d` key=p1 *
*`p2` = > get value=`d` key=p2 *
*`p3` = > get value=`d` key=p3 *
*`h1` = > get value=`d` key=h1 *
*`h2` = > get value=`d` key=h2 *
*`q_suf` = > quote text=`suffix` *
*`q_br` = > quote text=`bearer` *
*`q_p1` = > quote text=`p1` *
*`q_p2` = > quote text=`p2` *
*`q_p3` = > quote text=`p3` *
*`q_h1` = > quote text=`h1` *
*`q_h2` = > quote text=`h2` *
*`a1` = > get value=`d` key=a1 *
*`a2` = > get value=`d` key=a2 *
*`a3` = > get value=`d` key=a3 *
*`a4` = > get value=`d` key=a4 *
*`a5` = > get value=`d` key=a5 *
*`a6` = > get value=`d` key=a6 *
*`a7` = > get value=`d` key=a7 *
*`a8` = > get value=`d` key=a8 *
*`a9` = > get value=`d` key=a9 *
*`a10` = > get value=`d` key=a10 *
*`a11` = > get value=`d` key=a11 *
*`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` *
**> parse text=`raw`**
## complete
+ `prompt`
Chat completion using `self` / `自` handle fields.
*`api_key` = > get value=`self` key=api_key *
*`base_url` = > get value=`self` key=base_url *
*`model` = > get value=`self` key=model *
*`suffix` = > get value=`self` key=suffix *
*`bearer` = > get value=`self` key=bearer *
*`p1` = > get value=`self` key=p1 *
*`p2` = > get value=`self` key=p2 *
*`p3` = > get value=`self` key=p3 *
*`h1` = > get value=`self` key=h1 *
*`h2` = > get value=`self` key=h2 *
*`url` = `base_url` + `suffix` *
*`auth` = `bearer` + `api_key` *
*`q_auth` = > quote text=`auth` *
*`hdr_raw` = `h1` + `q_auth` + `h2` *
*`headers` = > parse text=`hdr_raw` *
*`q_model` = > quote text=`model` *
*`q_prompt` = > quote text=`prompt` *
*`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` *
*`resp` = > http_post url=`url` body=`body` headers=`headers` *
*`status` = > get value=`resp` key=status *
*`raw` = > get value=`resp` key=body *
1. `status` == 200
*`data` = > parse text=`raw` *
*`choices` = > get value=`data` key=choices *
*`first` = > at value=`choices` index=0 *
*`message` = > get value=`first` key=message *
*`content` = > get value=`message` key=content *
**`content`**
2. *
> print text=ext/ai/llm: HTTP error
> print text=`status`
> print text=`raw`
> exit code=1
---
## chat
+ `prompt`
Alias for `complete`.
**> `self`.complete prompt=`prompt`**
-130
View File
@@ -1,130 +0,0 @@
---
title: ext/ai/大模型
description: OpenAI 兼容大模型对象(中文)。导入 ext/ai/大模型.mq.md。
> lib/系统.mq.md
> lib/网络.mq.md
> lib/json.mq.md
---
## 加载环境
从工作目录加载 `.env`(可选具名实参 `path=`)。不覆盖已有变量。
**> load_dotenv**
# 大模型
从 `OPENAI_*` / `MARQDO_LLM_*` 构造句柄(默认 OpenAI v1 + `gpt-4o-mini`)。
*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} *
*`api_key` = > 取环境 名=OPENAI_API_KEY *
1. `api_key`
*`_k` = 1*
2. *
*`api_key` = > 取环境 名=MARQDO_LLM_API_KEY *
3. `api_key`
*`_k` = 1*
4. *
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
> 退出 码=1
*`base_url` = > 取环境 名=OPENAI_BASE_URL *
1. `base_url`
*`_k` = 1*
2. *
*`base_url` = > 取环境 名=MARQDO_LLM_BASE_URL *
3. `base_url`
*`_k` = 1*
4. *
*`base_url` = > get value=`d` key=base *
*`model` = > 取环境 名=OPENAI_MODEL *
1. `model`
*`_k` = 1*
2. *
*`model` = > 取环境 名=MARQDO_LLM_MODEL *
3. `model`
*`_k` = 1*
4. *
*`model` = > get value=`d` key=model *
*`q_key` = > quote text=`api_key` *
*`q_base` = > quote text=`base_url` *
*`q_model` = > quote text=`model` *
*`suffix` = > get value=`d` key=suffix *
*`bearer` = > get value=`d` key=bearer *
*`p1` = > get value=`d` key=p1 *
*`p2` = > get value=`d` key=p2 *
*`p3` = > get value=`d` key=p3 *
*`h1` = > get value=`d` key=h1 *
*`h2` = > get value=`d` key=h2 *
*`q_suf` = > quote text=`suffix` *
*`q_br` = > quote text=`bearer` *
*`q_p1` = > quote text=`p1` *
*`q_p2` = > quote text=`p2` *
*`q_p3` = > quote text=`p3` *
*`q_h1` = > quote text=`h1` *
*`q_h2` = > quote text=`h2` *
*`a1` = > get value=`d` key=a1 *
*`a2` = > get value=`d` key=a2 *
*`a3` = > get value=`d` key=a3 *
*`a4` = > get value=`d` key=a4 *
*`a5` = > get value=`d` key=a5 *
*`a6` = > get value=`d` key=a6 *
*`a7` = > get value=`d` key=a7 *
*`a8` = > get value=`d` key=a8 *
*`a9` = > get value=`d` key=a9 *
*`a10` = > get value=`d` key=a10 *
*`a11` = > get value=`d` key=a11 *
*`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` *
**> parse text=`raw`**
## 运行
+ `提示`
使用 `自` / `self` 句柄字段做聊天补全。
*`api_key` = > get value=`自` key=api_key *
*`base_url` = > get value=`自` key=base_url *
*`model` = > get value=`自` key=model *
*`suffix` = > get value=`自` key=suffix *
*`bearer` = > get value=`自` key=bearer *
*`p1` = > get value=`自` key=p1 *
*`p2` = > get value=`自` key=p2 *
*`p3` = > get value=`自` key=p3 *
*`h1` = > get value=`自` key=h1 *
*`h2` = > get value=`自` key=h2 *
*`url` = `base_url` + `suffix` *
*`auth` = `bearer` + `api_key` *
*`q_auth` = > quote text=`auth` *
*`hdr_raw` = `h1` + `q_auth` + `h2` *
*`headers` = > parse text=`hdr_raw` *
*`q_model` = > quote text=`model` *
*`q_prompt` = > quote text=`提示` *
*`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` *
*`resp` = > http_post url=`url` body=`body` headers=`headers` *
*`status` = > get value=`resp` key=status *
*`raw` = > get value=`resp` key=body *
1. `status` == 200
*`data` = > parse text=`raw` *
*`choices` = > get value=`data` key=choices *
*`first` = > at value=`choices` index=0 *
*`message` = > get value=`first` key=message *
*`content` = > get value=`message` key=content *
**`content`**
2. *
> 打印 内容=ext/ai/大模型: HTTP 错误
> 打印 内容=`status`
> 打印 内容=`raw`
> 退出 码=1
---
## 聊天
+ `提示`
`运行` 的别名。
**> `自`.运行 提示=`提示`**
-111
View File
@@ -1,111 +0,0 @@
---
title: ext/ai/智能体
description: 薄智能体框架 — 仅构造、执行、清空历史。
> ext/ai/大模型.mq.md
---
## 构建上下文
+ `智能体`
+ `额外信息`
内部:组装提示(用户提示、额外信息、工具列表、源码、位置、历史、Marqdo skill)。
*`user_prompt` = > get value=`智能体` key=user_prompt *
1. `user_prompt`
*`up` = `user_prompt`*
2. *
*`up` = 空*
*`tools` = > get value=`智能体` key=tools *
*`tools_s` = > host_format_tools_for_llm tools=`tools` *
*`src` = > host_module_source *
*`site` = > host_call_site *
*`site_s` = > stringify value=`site` *
*`id` = > get value=`智能体` key=id *
*`hist` = > host_agent_history_get id=`id` *
*`hist_s` = > stringify value=`hist` *
*`skill` = > host_marqdo_skill *
*`extra_s` = > stringify value=`额外信息` *
*`sep` = > parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- extra ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source ---\n","f":"\n\n--- history ---\n","g":"\n\n--- marqdo skill ---\n"} *
*`a` = > get value=`sep` key=a *
*`b` = > get value=`sep` key=b *
*`c` = > get value=`sep` key=c *
*`d` = > get value=`sep` key=d *
*`e` = > get value=`sep` key=e *
*`f` = > get value=`sep` key=f *
*`g` = > get value=`sep` key=g *
*`tool_proto` = \n\n--- tool protocol ---\nEach tool is a zero-arg Marqdo function in this module (see tools list). To call one, reply with exactly one line: TOOL:<name>. No other text on that line.\nAfter the tool runs you will get its output and should answer the user.\n *
*`p` = You are a Marqdo agent. Follow Marqdo skill rules when reading or writing .mq.md. *
*`p` = `p` + `a` + `up` + `b` + `extra_s` + `c` + `tool_proto` + `tools_s` + `d` + `site_s` + `e` + `src` + `f` + `hist_s` + `g` + `skill` *
**`p`**
# 智能体
+ `大模型`
+ `工具`
+ `用户提示信息`
*`id` = > host_agent_alloc *
*`h` = > parse text={"_type":"智能体"} *
*`h` = > map_set map=`h` key=id value=`id` *
*`h` = > map_set map=`h` key=model value=`大模型` *
*`h` = > map_set map=`h` key=tools value=`工具` *
1. `用户提示信息`
*`h` = > map_set map=`h` key=user_prompt value=`用户提示信息` *
2. *
*`_` = 1*
**`h`**
## 清空历史
*`id` = > get value=`自` key=id *
> host_agent_history_clear id=`id`
****
## 执行
+ `额外信息`
*`ctx` = > 构建上下文 智能体=`自` 额外信息=`额外信息` *
*`id` = > get value=`自` key=id *
*`user_turn` = > parse text={"role":"user"} *
*`user_turn` = > map_set map=`user_turn` key=content value=`额外信息` *
> host_agent_history_append id=`id` item=`user_turn`
*`model` = > get value=`自` key=model *
*`reply` = > `model`.运行 提示=`ctx` *
*`tools` = > get value=`自` key=tools *
*`reply` = > trim value=`reply` *
*`parts` = > split value=`reply` sep=: *
*`head` = > at value=`parts` index=0 *
*`tool_name` = > at value=`parts` index=1 *
*`tool_name` = > trim value=`tool_name` *
1. `head` == TOOL
*`allowed` = > host_tool_allowed tools=`tools` name=`tool_name` *
1. `allowed`
*`tool_out` = > 调用 名=`tool_name` *
*`tool_s` = > stringify value=`tool_out` *
*`extra_s` = > stringify value=`额外信息` *
*`fp` = The user asked: *
*`fp` = `fp` + `extra_s` *
*`fp` = `fp` + . You invoked tool *
*`fp` = `fp` + `tool_name` *
*`fp` = `fp` + which returned: *
*`fp` = `fp` + `tool_s` *
*`fp` = `fp` + . Reply to the user in one brief sentence. *
*`reply` = > `model`.运行 提示=`fp` *
2. *
*`reply` = Tool not allowed: `tool_name` *
2. *
*`_` = 1*
*`as_turn` = > parse text={"role":"assistant"} *
*`as_turn` = > map_set map=`as_turn` key=content value=`reply` *
> host_agent_history_append id=`id` item=`as_turn`
**`reply`**
-43
View File
@@ -1,43 +0,0 @@
/* Marqdo plugin ABI v1 — C contract (source of truth).
*
* Plugins are optional shared libraries (.dll / .so / .dylib), never linked
* into the marqdo binary. Values cross the boundary as UTF-8 JSON.
*/
#ifndef MARQDO_ABI_H
#define MARQDO_ABI_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define MARQDO_ABI_VERSION 1u
/* Plugin function: args_json is a UTF-8 JSON object whose keys are param names.
* On success: return 0, set *out_json to a heap string (host frees via free).
* On failure: return non-zero; optional *err_msg heap string (host frees).
* out_json / err_msg may be left NULL.
*/
typedef int (*MarqdoPluginFn)(const char *args_json, char **out_json, char **err_msg);
typedef struct MarqdoHostApi {
void *userdata;
/* params: comma-separated param names in order, e.g. "a,b". May be "". */
int (*register_fn)(void *userdata, const char *name, const char *params,
MarqdoPluginFn fn);
void *(*alloc)(size_t n);
void (*free)(void *p);
} MarqdoHostApi;
/* Required exports from every plugin shared library. */
uint32_t marqdo_plugin_abi_version(void);
int marqdo_plugin_init(const MarqdoHostApi *host);
void marqdo_plugin_shutdown(void);
#ifdef __cplusplus
}
#endif
#endif /* MARQDO_ABI_H */
-25
View File
@@ -1,25 +0,0 @@
---
title: lib/foreign
description: Run bound code fences and inline sources via local interpreters
---
## set_cmd
+ `lang`
+ `cmd`
**> host_foreign_set_cmd lang=`lang` cmd=`cmd`**
## run
+ `code`
**> host_foreign_run code=`code`**
## run_lang
+ `lang`
+ `source`
**> host_foreign_run_lang lang=`lang` source=`source`**
## langs
**> host_foreign_langs**
-41
View File
@@ -1,41 +0,0 @@
---
title: lib/fs
description: English filesystem wrappers
---
## read_text
+ `path`
**> host_read_text path=`path`**
## write_text
+ `path`
+ `text`
**> host_write_text path=`path` text=`text`**
## append_text
+ `path`
+ `text`
**> host_append_text path=`path` text=`text`**
## exists
+ `path`
**> host_exists path=`path`**
## list_dir
+ `path`
**> host_list_dir path=`path`**
## make_dir
+ `path`
**> host_make_dir path=`path`**
## remove
+ `path`
**> host_remove path=`path`**
-43
View File
@@ -1,43 +0,0 @@
---
title: lib/json
description: JSON parse/stringify (shared EN/ZH import)
---
## parse
+ `text`
**> host_json_parse text=`text`**
## stringify
+ `value`
**> host_json_stringify value=`value`**
## get
+ `value`
+ `key`
**> host_json_get value=`value` key=`key`**
## keys
+ `value`
**> host_json_keys value=`value`**
## quote
+ `text`
**> host_json_quote text=`text`**
## set
+ `map`
+ `key`
+ `value`
**> host_map_set map=`map` key=`key` value=`value`**
## append
+ `list`
+ `item`
**> host_list_append list=`list` item=`item`**
-200
View File
@@ -1,200 +0,0 @@
---
title: lib/math
description: High-school math — num, random, formula, plot
---
## pi
**> host_pi**
## e
**> host_e**
## num
+ `value`
**> host_num value=`value`**
## add
+ `a`
+ `b`
**> host_math_add a=`a` b=`b`**
## sub
+ `a`
+ `b`
**> host_math_sub a=`a` b=`b`**
## mul
+ `a`
+ `b`
**> host_math_mul a=`a` b=`b`**
## div
+ `a`
+ `b`
**> host_math_div a=`a` b=`b`**
## pow
+ `a`
+ `b`
**> host_math_pow a=`a` b=`b`**
## neg
+ `value`
**> host_math_neg value=`value`**
## sin
+ `value`
**> host_math_sin value=`value`**
## cos
+ `value`
**> host_math_cos value=`value`**
## tan
+ `value`
**> host_math_tan value=`value`**
## asin
+ `value`
**> host_math_asin value=`value`**
## acos
+ `value`
**> host_math_acos value=`value`**
## atan
+ `value`
**> host_math_atan value=`value`**
## sqrt
+ `value`
**> host_math_sqrt value=`value`**
## abs
+ `value`
**> host_math_abs value=`value`**
## ln
+ `value`
**> host_math_ln value=`value`**
## exp
+ `value`
**> host_math_exp value=`value`**
## floor
+ `value`
**> host_math_floor value=`value`**
## ceil
+ `value`
**> host_math_ceil value=`value`**
## min
+ `a`
+ `b`
**> host_math_min a=`a` b=`b`**
## max
+ `a`
+ `b`
**> host_math_max a=`a` b=`b`**
## random
**> host_random**
## random_int
+ `min`
+ `max`
**> host_random_int min=`min` max=`max`**
## seed
+ `value`
**> host_seed value=`value`**
## formula
+ `text`
**> host_formula value=`text`**
## simplify
+ `formula`
**> host_simplify value=`formula`**
## expand
+ `formula`
**> host_expand value=`formula`**
## diff
+ `formula`
+ `var`
**> host_diff formula=`formula` var=`var`**
## subs
+ `formula`
+ `var`
+ `value`
**> host_subs formula=`formula` var=`var` value=`value`**
## eval
+ `formula`
+ `var`
+ `value`
**> host_eval formula=`formula` var=`var` value=`value`**
## solve
+ `formula`
+ `var`
**> host_solve formula=`formula` var=`var`**
## plot
+ `formula`
+ `var`
+ `min`
+ `max`
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
## plot_points
+ `xs`
+ `ys`
**> host_plot_points xs=`xs` ys=`ys`**
## plot_conic
+ `kind`
+ `a`
**> host_plot_conic kind=`kind` a=`a`**
-32
View File
@@ -1,32 +0,0 @@
---
title: lib/net
description: English HTTP(S) wrappers. Optional headers / content_type via host aliases.
---
## http_get
+ `url`
HTTPS supported. Optional named arg `headers=` (map).
**> host_http_get url=`url`**
## http_post
+ `url`
+ `body`
Default content type is JSON. Optional `content_type=` / `headers=` (map).
**> host_http_post url=`url` body=`body`**
## http_request
+ `method`
+ `url`
Optional `body=` / `content_type=` / `headers=`.
**> host_http_request method=`method` url=`url`**
## url_encode
+ `text`
**> host_url_encode text=`text`**
-17
View File
@@ -1,17 +0,0 @@
---
title: lib/plugin
description: Load optional native ABI plugins (.dll / .so / .dylib)
---
## load
+ `path`
**> host_plugin_load path=`path`**
## unload
**> host_plugin_unload**
## list
**> host_plugin_list**
-34
View File
@@ -1,34 +0,0 @@
---
title: lib/subtask
description: Concurrent subtasks — file, function, or foreign code
---
## spawn
+ `path`=None
+ `fn`=None
+ `args`=None
+ `code`=None
+ `lang`=None
+ `source`=None
+ `stdin`=None
**> host_subtask_spawn path=`path` fn=`fn` args=`args` code=`code` lang=`lang` source=`source` stdin=`stdin`**
## poll
+ `id`
**> host_subtask_poll id=`id`**
## wait
+ `id`
**> host_subtask_join id=`id`**
## kill
+ `id`
**> host_subtask_kill id=`id`**
## wait_all
**> host_subtask_wait_all**
-39
View File
@@ -1,39 +0,0 @@
---
title: lib/sys
description: English system wrappers (load_dotenv accepts optional path via host alias)
---
## env_get
+ `name`
**> host_env_get name=`name`**
## env_set
+ `name`
+ `value`
**> host_env_set name=`name` value=`value`**
## load_dotenv
Load `.env` (optional named arg `path=`). Existing process env is not overridden.
**> host_dotenv_load**
## args
**> host_args**
## cwd
**> host_cwd**
## exit
+ `code`
**> host_exit code=`code`**
## exec
+ `cmd`
**> host_exec cmd=`cmd`**
-15
View File
@@ -1,15 +0,0 @@
---
title: lib/table
description: English table helpers over len / at
---
## rows
+ `xs`
**> len `xs`**
## row_at
+ `xs`
+ `i`
**> at value=`xs` index=`i`**
-21
View File
@@ -1,21 +0,0 @@
---
title: lib/text
description: English text helpers over trim / split / join
---
## str_trim
+ `s`
**> trim `s`**
## str_split
+ `s`
+ `sep`
**> split value=`s` sep=`sep`**
## str_join
+ `xs`
+ `sep`
**> join value=`xs` sep=`sep`**
-29
View File
@@ -1,29 +0,0 @@
---
title: lib/time
description: English time wrappers
---
## now_unix
**> host_now_unix**
## now_ms
**> host_now_ms**
## format
+ `unix`
+ `pattern`
**> host_format_time unix=`unix` pattern=`pattern`**
## sleep_ms
+ `ms`
**> host_sleep_ms ms=`ms`**
## parse
+ `text`
+ `pattern`
**> host_parse_time text=`text` pattern=`pattern`**
-32
View File
@@ -1,32 +0,0 @@
---
title: lib/writeback
description: Persist run output in .mq.md (Jupyter-style writeback)
---
## record
+ `value`
+ `at_end`=False
Write `value` to `<!-- marqdo-out … -->` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` appends a single block at EOF.
**> host_writeback_record value=`value` at_end=`at_end`**
## get
+ `at_end`=False
Read persisted output for the current call site (adjacent block), or the EOF block when `at_end=true`.
**> host_writeback_get at_end=`at_end`**
## clear
+ `at_end`=False
Remove the adjacent or EOF output block.
**> host_writeback_clear at_end=`at_end`**
## list
List all output blocks in the entry file.
**> host_writeback_list**
-25
View File
@@ -1,25 +0,0 @@
---
title: lib/外联
description: 通过本机解释器运行绑定的代码围栏与内联源码
---
## 设置命令
+ `语言`
+ `命令`
**> host_foreign_set_cmd lang=`语言` cmd=`命令`**
## 运行
+ `代码`
**> host_foreign_run code=`代码`**
## 按语言运行
+ `语言`
+ `源码`
**> host_foreign_run_lang lang=`语言` source=`源码`**
## 语言表
**> host_foreign_langs**
-34
View File
@@ -1,34 +0,0 @@
---
title: lib/子任务
description: 并发子任务 — 文件、函数或外联代码
---
## 启动
+ `路径`=None
+ `函数`=None
+ `参数`=None
+ `代码`=None
+ `语言`=None
+ `源码`=None
+ `输入`=None
**> host_subtask_spawn path=`路径` fn=`函数` args=`参数` code=`代码` lang=`语言` source=`源码` stdin=`输入`**
## 探测
+ `id`
**> host_subtask_poll id=`id`**
## 等待
+ `id`
**> host_subtask_join id=`id`**
## 终止
+ `id`
**> host_subtask_kill id=`id`**
## 等待全部
**> host_subtask_wait_all**
-17
View File
@@ -1,17 +0,0 @@
---
title: lib/插件
description: 加载可选原生 ABI 插件(.dll / .so / .dylib)
---
## 加载
+ `路径`
**> host_plugin_load path=`路径`**
## 卸载
**> host_plugin_unload**
## 列出
**> host_plugin_list**
-200
View File
@@ -1,200 +0,0 @@
---
title: lib/数学
description: 高中数学 — 数值、随机、公式、作图
---
## 圆周率
**> host_pi**
## 自然底数
**> host_e**
## 数
+ `value`
**> host_num value=`value`**
## 加
+ `a`
+ `b`
**> host_math_add a=`a` b=`b`**
## 减
+ `a`
+ `b`
**> host_math_sub a=`a` b=`b`**
## 乘
+ `a`
+ `b`
**> host_math_mul a=`a` b=`b`**
## 除
+ `a`
+ `b`
**> host_math_div a=`a` b=`b`**
## 幂
+ `a`
+ `b`
**> host_math_pow a=`a` b=`b`**
## 负
+ `value`
**> host_math_neg value=`value`**
## 正弦
+ `value`
**> host_math_sin value=`value`**
## 余弦
+ `value`
**> host_math_cos value=`value`**
## 正切
+ `value`
**> host_math_tan value=`value`**
## 反正弦
+ `value`
**> host_math_asin value=`value`**
## 反余弦
+ `value`
**> host_math_acos value=`value`**
## 反正切
+ `value`
**> host_math_atan value=`value`**
## 平方根
+ `value`
**> host_math_sqrt value=`value`**
## 绝对值
+ `value`
**> host_math_abs value=`value`**
## 对数
+ `value`
**> host_math_ln value=`value`**
## 指数
+ `value`
**> host_math_exp value=`value`**
## 向下取整
+ `value`
**> host_math_floor value=`value`**
## 向上取整
+ `value`
**> host_math_ceil value=`value`**
## 最小
+ `a`
+ `b`
**> host_math_min a=`a` b=`b`**
## 最大
+ `a`
+ `b`
**> host_math_max a=`a` b=`b`**
## 随机
**> host_random**
## 随机整数
+ `min`
+ `max`
**> host_random_int min=`min` max=`max`**
## 设种子
+ `value`
**> host_seed value=`value`**
## 公式
+ `text`
**> host_formula value=`text`**
## 化简
+ `formula`
**> host_simplify value=`formula`**
## 展开
+ `formula`
**> host_expand value=`formula`**
## 求导
+ `formula`
+ `var`
**> host_diff formula=`formula` var=`var`**
## 代入
+ `formula`
+ `var`
+ `value`
**> host_subs formula=`formula` var=`var` value=`value`**
## 求值
+ `formula`
+ `var`
+ `value`
**> host_eval formula=`formula` var=`var` value=`value`**
## 求解
+ `formula`
+ `var`
**> host_solve formula=`formula` var=`var`**
## 绘图
+ `formula`
+ `var`
+ `min`
+ `max`
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
## 绘点列
+ `xs`
+ `ys`
**> host_plot_points xs=`xs` ys=`ys`**
## 绘圆锥
+ `kind`
+ `a`
**> host_plot_conic kind=`kind` a=`a`**
-41
View File
@@ -1,41 +0,0 @@
---
title: lib/文件
description: 中文文件系统包装
---
## 读文本
+ `路径`
**> host_read_text path=`路径`**
## 写文本
+ `路径`
+ `内容`
**> host_write_text path=`路径` text=`内容`**
## 追加文本
+ `路径`
+ `内容`
**> host_append_text path=`路径` text=`内容`**
## 存在
+ `路径`
**> host_exists path=`路径`**
## 列目录
+ `路径`
**> host_list_dir path=`路径`**
## 建目录
+ `路径`
**> host_make_dir path=`路径`**
## 删除
+ `路径`
**> host_remove path=`路径`**
-21
View File
@@ -1,21 +0,0 @@
---
title: lib/文本
description: 中文文本库:去空白 / 拆分 / 拼接
---
## 去空白
+ `s`
**> trim `s`**
## 拆分
+ `s`
+ `sep`
**> split value=`s` sep=`sep`**
## 拼接
+ `xs`
+ `sep`
**> join value=`xs` sep=`sep`**
-29
View File
@@ -1,29 +0,0 @@
---
title: lib/时间
description: 中文时间包装
---
## 此刻秒
**> host_now_unix**
## 此刻毫秒
**> host_now_ms**
## 格式化
+ `秒`
+ `格式`
**> host_format_time unix=`秒` pattern=`格式`**
## 睡眠毫秒
+ `毫秒`
**> host_sleep_ms ms=`毫秒`**
## 解析时间
+ `内容`
+ `格式`
**> host_parse_time text=`内容` pattern=`格式`**
-39
View File
@@ -1,39 +0,0 @@
---
title: lib/系统
description: 中文系统包装(加载环境 可选 路径=)
---
## 取环境
+ `名`
**> host_env_get name=`名`**
## 设环境
+ `名`
+ `值`
**> host_env_set name=`名` value=`值`**
## 加载环境
加载 `.env`(可选具名实参 `路径=`)。不覆盖已有进程环境变量。
**> host_dotenv_load**
## 参数表
**> host_args**
## 工作目录
**> host_cwd**
## 退出
+ `码`
**> host_exit code=`码`**
## 执行
+ `命令`
**> host_exec cmd=`命令`**
-32
View File
@@ -1,32 +0,0 @@
---
title: lib/网络
description: 中文 HTTP(S) 包装。可选 headers / content_type 经宿主别名绑定。
---
## 获取
+ `地址`
支持 HTTPS。可选具名实参 `headers=`(映射)。
**> host_http_get url=`地址`**
## 提交
+ `地址`
+ `内容`
默认 Content-Type 为 JSON。可选 `content_type=` / `headers=`。
**> host_http_post url=`地址` body=`内容`**
## 请求
+ `方法`
+ `地址`
可选 `body=` / `content_type=` / `headers=`。
**> host_http_request method=`方法` url=`地址`**
## 编码地址
+ `内容`
**> host_url_encode text=`内容`**
-30
View File
@@ -1,30 +0,0 @@
---
title: lib/自写回
description: 将运行结果写回 .mq.md(Jupyter 式自写回)
---
## 写回
+ `值`
+ `末尾`=False
在入口文件中写入 `<!-- marqdo-out … -->`。默认在调用行下方插入或替换;`末尾=true` 时在文件末尾保留单块。
**> host_writeback_record value=`值` at_end=`末尾`**
## 取
+ `末尾`=False
读取当前调用处紧邻块,或 `末尾=true` 时读取文件末尾块。
**> host_writeback_get at_end=`末尾`**
## 清除
+ `末尾`=False
删除紧邻块或末尾块。
**> host_writeback_clear at_end=`末尾`**
## 列出
**> host_writeback_list**
-15
View File
@@ -1,15 +0,0 @@
---
title: lib/表
description: 中文表库:行数 / 取行
---
## 行数
+ `xs`
**> len `xs`**
## 取行
+ `xs`
+ `i`
**> at value=`xs` index=`i`**
-39
View File
@@ -1,39 +0,0 @@
---
title: 人工文档
description: 这是人工写的文档,禁止机器修改
---
对于marqdo这个项目,详细的语法定义为:
---
#标识对象,#main不算特殊这是一个项目的传统入口可以视为是一个对象。
---
##、### 、####等标识函数,不同数目表示从属关系,例如###是##函数的子函数,作用域不超过
这个函数,使用-表示函数的变量名
**** 空返回(None),并结束本函数体
---
无标记行表示注释信息,对于无标记行应该这么约定不是说开头没有符合不然就会出现:
**强调信息**是什么什么
上面应该是一个注释
---
程序语言使用*程序*也就是斜体表示
---
`变量名`表示变量
---
> 表示引用函数
---
有序列表表示分支语句
---
无序列表表示循环语句
---
公式由数学库渲染
---
代码片段由外联库渲染
---
添加一个新的标准库,自写回标准库,自写回的内容必须使用<!---->包裹,这个不会被md识别,
但是这个可以被marqdo识别,当作提示信息或生成结果的一律表示,markdo view要能渲染,以某种方式
---
添加一个新的标准库,子任务库,能够自由的运行子任务,现在的调用还是顺序化的,但是子任务允许多个
进程式的调用,子任务库将成为marqdo的护城河项目,子任务要依赖于父任务,父任务结束子任务一定结束,防止出现问题
-20
View File
@@ -1,20 +0,0 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
这是人工构建的用于测试的样例
`测试目录` =
|测试文件夹|
|-----|
|structure|
|keyword|
|lib|
- [`测试文件夹`](`测试目录`)
> 打印 `测试文件夹`
-14
View File
@@ -1,14 +0,0 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
*`a` = True*
*`b` = False*
1. `a` and not `b`
> print text=ok
2. *
> print text=fail
-12
View File
@@ -1,12 +0,0 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
测试输入
*`name`=> input "你叫什么名字\n"*
> print `name`
-10
View File
@@ -1,10 +0,0 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
测试输出
> print 欢迎你
-33
View File
@@ -1,33 +0,0 @@
---
title: 手工构造的测试样例
description: AI禁止更改
> lib/math.mq.md
---
# main
`f` =
$$
x^2 + 2
$$
`f` =
$$
x^2 - 2
$$
*`ty` = > type `f` *
> print text=`ty`
*`df` = > diff formula=`f` var=x *
> print text=`df`
*`roots` = > solve formula=`f` var=x *
> print text=`roots`
*`y` = > eval formula=`f` var=x value=3 *
> print text=`y`
-23
View File
@@ -1,23 +0,0 @@
---
title: 手工构造的测试样例
description: AI禁止更改
> lib/writeback.mq.md
---
# main
测试写回库
*`name`=>input "你叫什么名字?\n"*
> record `name`
<!-- marqdo-out
123132
-->
-15
View File
@@ -1,15 +0,0 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
测试分支语句
* `bool_value` = True *
1. `bool_value` == True
> print True
2. *
> print False
-15
View File
@@ -1,15 +0,0 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
测试循环语句语句
*`n`=0*
- `n` < 42
`n`=`n`+1
> print `n`
-14
View File
@@ -1,14 +0,0 @@
[package]
name = "marqdo_plugin_agent"
version = "0.1.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo agent layout plugin (ABI v1 cdylib)"
publish = false
[lib]
name = "agent"
crate-type = ["cdylib"]
[dependencies]
serde_json = "1"
-574
View File
@@ -1,574 +0,0 @@
//! Agent layout plugin (C ABI v1): find_root, ensure_layout, probe, scaffold.
use std::ffi::{CStr, CString};
use std::os::raw::{c_char, c_int, c_void};
use std::path::{Component, Path, PathBuf};
use std::ptr;
const ABI_VERSION: u32 = 1;
const DEFAULT_MARKERS: &str = "agents,runbooks,marqdo.agent.json";
const LAYOUT_DIRS: &[&str] = &["agents", "runbooks", "templates", "reports"];
type PluginFn = unsafe extern "C" fn(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int;
#[repr(C)]
pub struct MarqdoHostApi {
pub userdata: *mut c_void,
pub register_fn: Option<
unsafe extern "C" fn(
userdata: *mut c_void,
name: *const c_char,
params: *const c_char,
fn_ptr: PluginFn,
) -> c_int,
>,
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
}
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
unsafe fn host_strdup(s: &str) -> *mut c_char {
let alloc = HOST_ALLOC.expect("host alloc");
let bytes = s.as_bytes();
let p = alloc(bytes.len() + 1) as *mut u8;
if p.is_null() {
return ptr::null_mut();
}
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
*p.add(bytes.len()) = 0;
p as *mut c_char
}
fn set_out(out: *mut *mut c_char, s: &str) {
if out.is_null() {
return;
}
unsafe {
*out = host_strdup(s);
}
}
fn set_err(err: *mut *mut c_char, s: &str) {
if err.is_null() {
return;
}
unsafe {
*err = host_strdup(s);
}
}
fn parse_args(args_json: *const c_char) -> Result<serde_json::Value, String> {
if args_json.is_null() {
return Err("null args".into());
}
let s = unsafe { CStr::from_ptr(args_json) }
.to_str()
.map_err(|_| "args not utf-8".to_string())?;
serde_json::from_str(s).map_err(|e| e.to_string())
}
fn arg_str<'a>(v: &'a serde_json::Value, key: &str) -> Result<&'a str, String> {
v.get(key)
.and_then(|x| x.as_str())
.ok_or_else(|| format!("missing text `{key}`"))
}
fn has_parent_escape(rel: &Path) -> bool {
rel.components().any(|c| matches!(c, Component::ParentDir))
}
fn find_root(start: &str, markers: &str) -> Result<PathBuf, String> {
let markers: Vec<&str> = markers
.split(',')
.map(|s| s.trim())
.filter(|s| !s.is_empty())
.collect();
if markers.is_empty() {
return Err("empty markers".into());
}
let mut cur = PathBuf::from(start);
if cur.as_os_str().is_empty() {
cur = std::env::current_dir().map_err(|e| e.to_string())?;
}
if !cur.exists() {
return Err(format!("start path missing: {}", cur.display()));
}
let mut cur = std::fs::canonicalize(&cur).map_err(|e| e.to_string())?;
loop {
for m in &markers {
let p = cur.join(m);
let ok = if m.contains('.') {
p.is_file()
} else {
p.is_dir()
};
if ok {
return Ok(cur);
}
}
if !cur.pop() {
break;
}
}
Err("agent project root not found".into())
}
fn ensure_layout(root: &Path) -> Result<i64, String> {
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
let mut created = 0i64;
for d in LAYOUT_DIRS {
let p = root.join(d);
if !p.exists() {
std::fs::create_dir_all(&p).map_err(|e| e.to_string())?;
created += 1;
} else if !p.is_dir() {
return Err(format!("{} exists and is not a directory", p.display()));
}
}
Ok(created)
}
fn probe(root: &Path) -> Result<serde_json::Value, String> {
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
let mut map = serde_json::Map::new();
map.insert(
"root".into(),
serde_json::Value::String(root.to_string_lossy().into_owned()),
);
for d in LAYOUT_DIRS {
let key = format!("has_{d}");
map.insert(key, serde_json::Value::Bool(root.join(d).is_dir()));
}
Ok(serde_json::Value::Object(map))
}
fn scaffold(root: &Path, name: &str, template: &str, dest: &str) -> Result<String, String> {
if name.is_empty() {
return Err("name is empty".into());
}
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
let tmpl_rel = Path::new(template);
let dest_rel = Path::new(dest);
if has_parent_escape(tmpl_rel) {
return Err("template path escapes project root".into());
}
if has_parent_escape(dest_rel) {
return Err("dest path escapes project root".into());
}
let tmpl_path = root.join(tmpl_rel);
if !tmpl_path.is_file() {
return Err(format!("template not found: {}", tmpl_path.display()));
}
let tmpl_can = std::fs::canonicalize(&tmpl_path).map_err(|e| e.to_string())?;
if !tmpl_can.starts_with(&root) {
return Err("template path escapes project root".into());
}
let dest_path = root.join(dest_rel);
if let Some(parent) = dest_path.parent() {
std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
let parent_can = std::fs::canonicalize(parent).map_err(|e| e.to_string())?;
if !parent_can.starts_with(&root) {
return Err("dest path escapes project root".into());
}
}
let body = std::fs::read_to_string(&tmpl_can).map_err(|e| e.to_string())?;
let body = body.replace("{{name}}", name);
std::fs::write(&dest_path, body).map_err(|e| e.to_string())?;
Ok(dest_path.to_string_lossy().into_owned())
}
fn map_get_str<'a>(m: &'a serde_json::Value, keys: &[&str]) -> Option<&'a str> {
let obj = m.as_object()?;
for k in keys {
if let Some(v) = obj.get(*k) {
if let Some(s) = v.as_str() {
return Some(s);
}
if let Some(n) = v.as_i64() {
// allow numeric fields to be read as display later
let _ = n;
}
}
}
None
}
fn map_get_i64(m: &serde_json::Value, keys: &[&str]) -> i64 {
let Some(obj) = m.as_object() else {
return i64::MAX;
};
for k in keys {
if let Some(v) = obj.get(*k) {
if let Some(n) = v.as_i64() {
return n;
}
if let Some(s) = v.as_str() {
if let Ok(n) = s.parse::<i64>() {
return n;
}
}
}
}
i64::MAX
}
fn skills_text(m: &serde_json::Value) -> String {
map_get_str(m, &["技能", "skills", "skill"])
.unwrap_or("")
.to_string()
}
fn match_skill(skill: &str, members: &serde_json::Value) -> Result<serde_json::Value, String> {
let arr = members
.as_array()
.ok_or_else(|| "members must be a JSON array".to_string())?;
let skill = skill.trim();
if skill.is_empty() {
return Err("skill is empty".into());
}
let mut best: Option<&serde_json::Value> = None;
let mut best_load = i64::MAX;
for m in arr {
let sk = skills_text(m);
if sk.split(',').any(|p| p.trim() == skill) || sk.contains(skill) {
let load = map_get_i64(m, &["负载", "load"]);
if load < best_load {
best_load = load;
best = Some(m);
}
}
}
Ok(best.cloned().unwrap_or(serde_json::Value::Null))
}
fn bump_load(member: &serde_json::Value, delta: i64) -> Result<serde_json::Value, String> {
let mut obj = member
.as_object()
.cloned()
.ok_or_else(|| "member must be a JSON object".to_string())?;
let key = if obj.contains_key("负载") {
"负载"
} else if obj.contains_key("load") {
"load"
} else {
obj.insert("负载".into(), serde_json::Value::Number(0.into()));
"负载"
};
let cur = match obj.get(key) {
Some(serde_json::Value::Number(n)) => n.as_i64().unwrap_or(0),
Some(serde_json::Value::String(s)) => s.parse().unwrap_or(0),
_ => 0,
};
obj.insert(
key.into(),
serde_json::Value::Number((cur + delta).into()),
);
Ok(serde_json::Value::Object(obj))
}
unsafe extern "C" fn agent_find_root(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
let v = match parse_args(args_json) {
Ok(v) => v,
Err(e) => {
set_err(err_msg, &format!("agent_find_root: {e}"));
return 1;
}
};
let start = match arg_str(&v, "start") {
Ok(s) => s,
Err(e) => {
set_err(err_msg, &format!("agent_find_root: {e}"));
return 1;
}
};
let markers = v
.get("markers")
.and_then(|x| x.as_str())
.filter(|s| !s.is_empty())
.unwrap_or(DEFAULT_MARKERS);
match find_root(start, markers) {
Ok(p) => {
let out = serde_json::Value::String(p.to_string_lossy().into_owned()).to_string();
set_out(out_json, &out);
0
}
Err(e) => {
set_err(err_msg, &format!("agent_find_root: {e}"));
1
}
}
}
unsafe extern "C" fn agent_ensure_layout(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
let v = match parse_args(args_json) {
Ok(v) => v,
Err(e) => {
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
return 1;
}
};
let root = match arg_str(&v, "root") {
Ok(s) => s,
Err(e) => {
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
return 1;
}
};
match ensure_layout(Path::new(root)) {
Ok(n) => {
set_out(out_json, &n.to_string());
0
}
Err(e) => {
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
1
}
}
}
unsafe extern "C" fn agent_probe(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
let v = match parse_args(args_json) {
Ok(v) => v,
Err(e) => {
set_err(err_msg, &format!("agent_probe: {e}"));
return 1;
}
};
let root = match arg_str(&v, "root") {
Ok(s) => s,
Err(e) => {
set_err(err_msg, &format!("agent_probe: {e}"));
return 1;
}
};
match probe(Path::new(root)) {
Ok(j) => {
set_out(out_json, &j.to_string());
0
}
Err(e) => {
set_err(err_msg, &format!("agent_probe: {e}"));
1
}
}
}
unsafe extern "C" fn agent_scaffold(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
let v = match parse_args(args_json) {
Ok(v) => v,
Err(e) => {
set_err(err_msg, &format!("agent_scaffold: {e}"));
return 1;
}
};
let root = match arg_str(&v, "root") {
Ok(s) => s,
Err(e) => {
set_err(err_msg, &format!("agent_scaffold: {e}"));
return 1;
}
};
let name = match arg_str(&v, "name") {
Ok(s) => s,
Err(e) => {
set_err(err_msg, &format!("agent_scaffold: {e}"));
return 1;
}
};
let template = match arg_str(&v, "template") {
Ok(s) => s,
Err(e) => {
set_err(err_msg, &format!("agent_scaffold: {e}"));
return 1;
}
};
let dest = match arg_str(&v, "dest") {
Ok(s) => s,
Err(e) => {
set_err(err_msg, &format!("agent_scaffold: {e}"));
return 1;
}
};
match scaffold(Path::new(root), name, template, dest) {
Ok(p) => {
let out = serde_json::Value::String(p).to_string();
set_out(out_json, &out);
0
}
Err(e) => {
set_err(err_msg, &format!("agent_scaffold: {e}"));
1
}
}
}
unsafe extern "C" fn agent_match_skill(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
let v = match parse_args(args_json) {
Ok(v) => v,
Err(e) => {
set_err(err_msg, &format!("agent_match_skill: {e}"));
return 1;
}
};
let skill = match arg_str(&v, "skill") {
Ok(s) => s,
Err(e) => {
set_err(err_msg, &format!("agent_match_skill: {e}"));
return 1;
}
};
let members = match v.get("members") {
Some(m) => m.clone(),
None => {
set_err(err_msg, "agent_match_skill: missing members");
return 1;
}
};
// members may be a JSON string (from Marqdo stringify) or already an array
let members = if let Some(s) = members.as_str() {
match serde_json::from_str::<serde_json::Value>(s) {
Ok(j) => j,
Err(e) => {
set_err(err_msg, &format!("agent_match_skill: members JSON: {e}"));
return 1;
}
}
} else {
members
};
match match_skill(skill, &members) {
Ok(j) => {
set_out(out_json, &j.to_string());
0
}
Err(e) => {
set_err(err_msg, &format!("agent_match_skill: {e}"));
1
}
}
}
unsafe extern "C" fn agent_bump_load(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
let v = match parse_args(args_json) {
Ok(v) => v,
Err(e) => {
set_err(err_msg, &format!("agent_bump_load: {e}"));
return 1;
}
};
let member = match v.get("member") {
Some(m) => m.clone(),
None => {
set_err(err_msg, "agent_bump_load: missing member");
return 1;
}
};
let member = if let Some(s) = member.as_str() {
match serde_json::from_str::<serde_json::Value>(s) {
Ok(j) => j,
Err(e) => {
set_err(err_msg, &format!("agent_bump_load: member JSON: {e}"));
return 1;
}
}
} else {
member
};
let delta = v.get("delta").and_then(|x| x.as_i64()).unwrap_or(1);
match bump_load(&member, delta) {
Ok(j) => {
set_out(out_json, &j.to_string());
0
}
Err(e) => {
set_err(err_msg, &format!("agent_bump_load: {e}"));
1
}
}
}
fn register(host: &MarqdoHostApi, name: &str, params: &str, fn_ptr: PluginFn) -> c_int {
let register = match host.register_fn {
Some(f) => f,
None => return 1,
};
let n = CString::new(name).unwrap();
let p = CString::new(params).unwrap();
unsafe { register(host.userdata, n.as_ptr(), p.as_ptr(), fn_ptr) }
}
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
ABI_VERSION
}
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
if host.is_null() {
return 1;
}
let host = &*host;
HOST_ALLOC = host.alloc;
HOST_FREE = host.free;
if register(host, "agent_find_root", "start,markers", agent_find_root) != 0 {
return 1;
}
if register(host, "agent_ensure_layout", "root", agent_ensure_layout) != 0 {
return 1;
}
if register(host, "agent_probe", "root", agent_probe) != 0 {
return 1;
}
if register(
host,
"agent_scaffold",
"root,name,template,dest",
agent_scaffold,
) != 0
{
return 1;
}
if register(host, "agent_match_skill", "skill,members", agent_match_skill) != 0 {
return 1;
}
if register(host, "agent_bump_load", "member,delta", agent_bump_load) != 0 {
return 1;
}
0
}
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_shutdown() {
HOST_ALLOC = None;
HOST_FREE = None;
}
-14
View File
@@ -1,14 +0,0 @@
[package]
name = "marqdo_plugin_demo"
version = "0.1.0"
edition = "2021"
license = "Apache-2.0"
description = "Demo Marqdo ABI v1 plugin (cdylib)"
publish = false
[lib]
name = "demo"
crate-type = ["cdylib"]
[dependencies]
serde_json = "1"
-170
View File
@@ -1,170 +0,0 @@
//! Demo Marqdo plugin (C ABI v1). Registers `demo_add` and `demo_echo`.
use std::ffi::{CStr, CString};
use std::os::raw::{c_char, c_int, c_void};
use std::ptr;
const ABI_VERSION: u32 = 1;
type PluginFn = unsafe extern "C" fn(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int;
#[repr(C)]
pub struct MarqdoHostApi {
pub userdata: *mut c_void,
pub register_fn: Option<
unsafe extern "C" fn(
userdata: *mut c_void,
name: *const c_char,
params: *const c_char,
fn_ptr: PluginFn,
) -> c_int,
>,
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
}
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
unsafe fn host_strdup(s: &str) -> *mut c_char {
let alloc = HOST_ALLOC.expect("host alloc");
let bytes = s.as_bytes();
let p = alloc(bytes.len() + 1) as *mut u8;
if p.is_null() {
return ptr::null_mut();
}
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
*p.add(bytes.len()) = 0;
p as *mut c_char
}
fn set_out(out: *mut *mut c_char, s: &str) {
if out.is_null() {
return;
}
unsafe {
*out = host_strdup(s);
}
}
fn set_err(err: *mut *mut c_char, s: &str) {
if err.is_null() {
return;
}
unsafe {
*err = host_strdup(s);
}
}
unsafe extern "C" fn demo_add(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
if args_json.is_null() {
set_err(err_msg, "demo_add: null args");
return 1;
}
let s = match CStr::from_ptr(args_json).to_str() {
Ok(s) => s,
Err(_) => {
set_err(err_msg, "demo_add: args not utf-8");
return 1;
}
};
let v: serde_json::Value = match serde_json::from_str(s) {
Ok(v) => v,
Err(e) => {
set_err(err_msg, &format!("demo_add: {e}"));
return 1;
}
};
let a = v.get("a").and_then(|x| x.as_i64()).unwrap_or(0);
let b = v.get("b").and_then(|x| x.as_i64()).unwrap_or(0);
set_out(out_json, &(a + b).to_string());
0
}
unsafe extern "C" fn demo_echo(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
if args_json.is_null() {
set_err(err_msg, "demo_echo: null args");
return 1;
}
let s = match CStr::from_ptr(args_json).to_str() {
Ok(s) => s,
Err(_) => {
set_err(err_msg, "demo_echo: args not utf-8");
return 1;
}
};
let v: serde_json::Value = match serde_json::from_str(s) {
Ok(v) => v,
Err(e) => {
set_err(err_msg, &format!("demo_echo: {e}"));
return 1;
}
};
let text = v
.get("text")
.and_then(|x| x.as_str())
.unwrap_or("");
let out = serde_json::Value::String(text.to_string()).to_string();
set_out(out_json, &out);
0
}
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
ABI_VERSION
}
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
if host.is_null() {
return 1;
}
let host = &*host;
HOST_ALLOC = host.alloc;
HOST_FREE = host.free;
let register = match host.register_fn {
Some(f) => f,
None => return 1,
};
let name_add = CString::new("demo_add").unwrap();
let params_add = CString::new("a,b").unwrap();
if register(
host.userdata,
name_add.as_ptr(),
params_add.as_ptr(),
demo_add,
) != 0
{
return 1;
}
let name_echo = CString::new("demo_echo").unwrap();
let params_echo = CString::new("text").unwrap();
if register(
host.userdata,
name_echo.as_ptr(),
params_echo.as_ptr(),
demo_echo,
) != 0
{
return 1;
}
0
}
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_shutdown() {
HOST_ALLOC = None;
HOST_FREE = None;
}
-55
View File
@@ -1,55 +0,0 @@
---
title: Welcome to Marqdo
description: User docs home — code is documentation (English)
> lib/math.mq.md
> lib/foreign.mq.md
---
# main
Hi — thanks for reading this far. I am Marqdo’s developer. Marqdo is a language where **code is documentation, and documentation is code**: Markdown markers are the program structure, so what you read is what runs.
AI already prefers Markdown-shaped output. The idea was: why keep docs and code as two separate worlds? So Marqdo was born as a “docs are code” language. To keep every source renderable as Markdown, files use the `.mq.md` suffix. From early on we aimed for richer tooling — auto-generated YAML for OKF-style knowledge bases, even auto-generated slides — those are later goals. Happily, it already works well as a blogging tool: yes, this site is generated by Marqdo. And when AI writes Marqdo, you tend to burn fewer tokens — wallets everywhere thank you.
The language is still young: structure markers, bilingual core names (`print` / `打印`, …), importable stdlibs (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Contribute on [GitHub](https://github.com/cflmy/marqdo).
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
A small function to say hello:
> greet who=marqdo
Named args can include spaces:
> greet who=marqdo user
## greet
+ `who`
> print text=Welcome, `who`!
---
Beyond the basics above, Marqdo also ships standard libraries: table, time, text, files, system, math, foreign, and more.
Math and foreign deserve a special mention. With the math library you can bind a formula like this:
`f` =
$$
x^2 - 2
$$
Then plot it:
*`_svg` = > plot formula=`f` var=x min=-3 max=3 *
The foreign library lets you call external code, for example:
`hi` =
```python
print("hello-from-python")
```
Under Markdown this stays easy to read — which is the point: Marqdo’s design is code as documentation, documentation as code.
Welcome again — enjoy exploring Marqdo.
-56
View File
@@ -1,56 +0,0 @@
---
title: 欢迎使用 Marqdo
description: 用户文档首页 — 代码即文档(中文版)
> lib/数学.mq.md
> lib/外联.mq.md
---
# main
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门**代码即文档,文档即代码**的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
AI 偏爱 Markdown结构的输出。作者的念头是:何必再把文档和代码拆成两套?我们来实现一个文档即代码的语言,所以marqdo应运而生,为了确保代码一定可以被渲染,marqdo的文件后缀定义为了`.mq.md`。在开发之处我们就尝试希望更丰富的支持,自动生成一个yaml文件使得 OKF 式知识库便捷的自动配置,乃至自动生成ppt,自然这都是以后的目标了。不过相当不错的是,至少这会成为一个不错的博客工具——对,这个站点就是 Marqdo 生成的,而且AI输出的时候会节约不少token,你知道的,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
具名实参可以带空格:
> 问候 谁=marqdo user
## 问候
+ `谁`
> 打印 内容=欢迎,`谁`!
---
除了上面的一些基本内容之外,我还开发了这个语言的一些标准库,包括表、时间、文本、文件、系统、数学和外联等标准库。
其中数学库和外联库是我要着重提到的,例如数学库,你可以通过下面的方式调用:
`f` =
$$
x^2 - 2
$$
之后让我们画个图像吧!
*`_svg` = > 绘图 formula=`f` var=x min=-3 max=3 *
外联库则允许你调用外部代码,例如:
`hi` =
```python
print("hello-from-python")
```
这些代码在markdown下面都非常的易读,就像我说的,marqdo的设计思想就是代码即文档,
文档即代码。
最后,再次欢迎你,尽情体验marqdo吧!
-28
View File
@@ -1,28 +0,0 @@
# 用户文档(可执行 · 可下载 · 中英双语)
本目录即面向访客的 Marqdo 介绍:每个 `.mq.md` 既是文稿也能 `marqdo run`,并随仓库 / 静态站一起下载。
**双语约定:** 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程。成对放在同一目录。标准库:拉丁路径用英文 API,中文路径用中文 API;JSON 仅 `lib/json.mq.md`。
| 路径 | 内容 |
|------|------|
| [`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/`) |
官方扩展(非 stdlib):`ext/llm`、`ext/agent` — 见 `features/05-extensions.mq.md` / `05-扩展.mq.md` 与 `doc/design/ext-*.md`。
**不放** `errors/`:失败样例只在 `tests/errors/`。
开发文档在 [`doc/`](../doc/)。
## 浏览与生成 HTML
```bash
cargo run -- view public
cargo run -- view output public -o public
```
详见 [user-site.md](../doc/design/user-site.md)。
-14
View File
@@ -1,14 +0,0 @@
---
title: Phase I — tree-walk interpreter
description: Lex · parse · check · tree-walk end to end
---
# main
Milestone: Phase I (tree-walk).
Pipeline: load → line classify → recursive-descent parse → semantic check → tree-walk eval. No Flex/Bison.
This page runs as a program — documentation is executable:
> print text=Phase I: tree-walk interpreter is live.
-14
View File
@@ -1,14 +0,0 @@
---
title: 第一阶段 — 树遍历解释器
description: 词法 · 语法 · 语义 · 树遍历已贯通
---
# main
里程碑:第一阶段(树遍历)。
流水线:加载 → 行分类 → 递归下降语法 → 语义检查 → 树遍历执行。实现不用 Flex/Bison。
本页本身即可运行,证明「文档即程序」已落地:
> 打印 内容=第一阶段:树遍历解释器已就绪。
-18
View File
@@ -1,18 +0,0 @@
---
title: Bytecode backend
description: `--backend bytecode` shares semantics with tree-walk
---
# main
Milestone: bytecode prototype.
The same `.mq.md` runs on tree-walk or the bytecode VM:
marqdo run FILE --backend tree
marqdo run FILE --backend bytecode
Output matches on both backends:
> print text=Bytecode backend: same program, alternate engine.
-18
View File
@@ -1,18 +0,0 @@
---
title: 字节码后端
description: `--backend bytecode` 与树遍历共用语义
---
# main
里程碑:字节码原型。
同一套 `.mq.md` 可用树遍历或字节码 VM:
marqdo run FILE --backend tree
marqdo run FILE --backend bytecode
两种后端输出一致:
> 打印 内容=字节码后端:同一程序,另一引擎。
-16
View File
@@ -1,16 +0,0 @@
---
title: view and the user docs site
description: Local browse and static export from the interpreter
---
# main
Milestone: `marqdo view` and `view output`.
Local: `marqdo view public`
Static export: `marqdo view output public -o public`
Executable user docs live under `public/`. Generated HTML (`index.html` / `pages/`) is for hosting; CI publishes to `gh-pages`.
> print text=Docs site: generated by the Marqdo interpreter, not hand-written HTML.
-16
View File
@@ -1,16 +0,0 @@
---
title: view 与用户文档站
description: 本地浏览与静态导出由解释器生成
---
# main
里程碑:`marqdo view` 与 `view output`。
本地浏览:`marqdo view public`
静态导出:`marqdo view output public -o public`
用户可执行文档在 `public/`;生成的 HTML(`index.html` / `pages/`)供静态托管,CI 发布到 `gh-pages`。
> 打印 内容=文档站:由 Marqdo 解释器生成,不是手写 HTML。
-12
View File
@@ -1,12 +0,0 @@
---
title: Objects and methods
description: Sharp heading is a type; deeper headings are functions or methods
---
# main
In Marqdo, a single sharp (#) defines an object / type constructor. Double sharp and deeper (## …) define free functions or methods. Constructing an object yields a map handle tagged with _type. Call methods with backtick object, then dot, then method name.
See doc/design/objects.md. Example gold: tests/structure/object-handle.mq.md. Official ext/llm and ext/agent use this pattern.
> print text=objects-ok
Loaded 100 of 284 files, more files were not shown because too many files have changed in this diff. Show more